💫 Toolkit to help you get started with SDD or any other process!
docs: distinguish extension reconciliation from core SDD (#4948)
Manfred Riemfe3de81d5b53
diff --git a/docs/concepts/spec-persistence.md b/docs/concepts/spec-persistence.mdindex 9269eca58..d6b97ba9e 100644--- a/docs/concepts/spec-persistence.md+++ b/docs/concepts/spec-persistence.md@@ -19,11 +19,21 @@ is adding remaining work to `tasks.md`. It does not select a persistence model,rewrite intent to match code, or treat approval of code as agreement withdocumented intent.+The core workflow has no dedicated command that automatically reconciles+differences among `spec.md`, `plan.md`, and `tasks.md`. Analyze reports+inconsistencies without editing artifacts, and converge only appends remaining+work to `tasks.md`. Teams can reconcile artifacts directly, and extensions can+provide their own commands or hooks to coordinate reconciliation during or+after delivery. Extension behavior does not change the responsibilities of the+core commands.+Persistence is the team's choice of how to maintain artifacts **afterdelivery**, not an alternative way to deliver or determine completeness.Discoveries can occur during implementation, but their timing does not define-the persistence model. If the team agrees to change the intended contract,-make that intent explicit in the artifacts and deliver against it.+the persistence model. Reconciliation can also occur during delivery without+becoming part of the core workflow or the persistence strategy. If the team+agrees to change the intended contract, make that intent explicit in the+artifacts and deliver against it.A later change requiring implementation still goes through the shared deliveryprocess and convergence against its explicit intended artifacts, whether those@@ -55,14 +65,17 @@ all allowed to inform each other.After delivery, accepted discoveries can inform maintenance edits to anyartifact. The team decides what those discoveries mean for intended behavior,-technical approach, or task breakdown, then manually reconciles `spec.md`,-`plan.md`, and `tasks.md` with that agreed direction. The implementation is-evidence for that discussion, not a replacement source of intent.+technical approach, or task breakdown. The team can reconcile `spec.md`,+`plan.md`, and `tasks.md` itself or use an extension whose documented behavior+does so. The implementation is evidence for that discussion, not a replacement+source of intent.This is a team-owned maintenance convention, not a requirement for a new core-amendment command or an artifact-rewriting role for converge. If reconciliation-identifies implementation work, deliver that change through the shared process-against the explicit intended artifacts.+amendment command or an artifact-rewriting role for analyze or converge.+Extension-provided reconciliation remains extension behavior, whether it runs+during or after delivery. If reconciliation identifies implementation work,+deliver that change through the shared process against the explicit intended+artifacts.Flow-back works well when:diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.mdindex f55928445..1a0cf9db9 100644--- a/docs/guides/evolving-specs.md+++ b/docs/guides/evolving-specs.md@@ -44,10 +44,18 @@ Converge is append-only: its only possible write is adding tasks to `tasks.md`.It does not choose a persistence strategy or rewrite the artifacts to acceptcode as a replacement for documented intent.+Core has no dedicated command that automatically reconciles differences among+`spec.md`, `plan.md`, and `tasks.md`. `/speckit.analyze` reports inconsistencies+without changing the artifacts. A team can reconcile them directly, or an+extension can provide commands or hooks that do so during or after delivery+according to that extension's documented behavior. Those actions do not change+the responsibilities of the core commands.+Discoveries may arise during delivery under any model. If they lead to anagreed change of intent, make the revised contract explicit in the artifacts-and deliver against it. The maintenance choices below apply after delivery;-they do not replace this loop.+and deliver against it. Reconciliation may occur during delivery, but the+maintenance choices below describe what the team persists after delivery; they+do not replace this loop.## Flow-Forward Spec@@ -68,17 +76,16 @@ Use living spec when `spec.md` is the contract and `plan.md` and `tasks.md` arederived from it.After delivery, maintain `spec.md` as the contract. When intended behavior-changes, revise the existing `spec.md` first. Then regenerate or manually revise-downstream artifacts so they match the updated spec:+changes, revise the existing `spec.md` first. Then reconcile downstream+artifacts so they match the updated spec:-1. Start from a clean working tree or a dedicated branch so every generated+1. Start from a clean working tree or a dedicated branch so every artifactchange is reviewable.-2. Update `spec.md` with `/speckit.clarify` or an explicit edit.-3. Rerun `/speckit.plan` or revise `plan.md` so the technical approach matches- the revised spec.-4. Rerun `/speckit.tasks` or revise `tasks.md` so implementation work matches- the revised plan.-5. Run `/speckit.analyze` to catch gaps between the spec, plan, and tasks.+2. Update `spec.md` with the intended contract.+3. Reconcile `plan.md` and `tasks.md` directly or through an extension according+ to the team's documented convention.+4. Run `/speckit.analyze` to report any remaining gaps between the spec, plan,+ and tasks.These steps maintain the artifact set; they do not deliver changed behavior.If the revised contract requires implementation, use the shared delivery loop@@ -107,7 +114,8 @@ alignment with that agreed direction:The implementation provides evidence for the team's decision; accepting codedoes not automatically make it the intended contract. Reconcile the artifacts-manually, not through converge or a required core amendment command. If the+directly or through an extension. Analyze and converge do not provide automatic+all-artifact reconciliation, and no core amendment command is required. If theagreed direction requires implementation, use the shared delivery loop aboveagainst explicit intended artifacts.diff --git a/docs/reference/extensions.md b/docs/reference/extensions.mdindex e39ff9d69..676428a07 100644--- a/docs/reference/extensions.md+++ b/docs/reference/extensions.md@@ -2,6 +2,13 @@Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. They introduce new commands and templates that go beyond the built-in Spec-Driven Development workflow.+An extension can define commands or hooks that reconcile `spec.md`, `plan.md`,+and `tasks.md` during or after feature delivery. Any such edits follow the+extension's documented behavior and the project's governance; they are not+performed by, or added to the responsibilities of, the core Spec Kit commands.+The team's persistence model separately determines how artifacts are maintained+after delivery.+## Search Available Extensions```bash