[Feature]: Core flow-back step for drift where the code is ahead of the spec #4940

Problem Statement

Spec Kit documents three spec persistence models in docs/guides/evolving-specs.md. Flow-forward and living spec both end with /speckit.converge. Flow-back has no command for its main step: after implementation, the guide says to update the artifacts that now disagree with the accepted direction and run /speckit.analyze, but nothing performs that update.

/speckit.converge already finds this kind of drift. Its unrequested and contradicts findings often mean the code is right and the spec or plan is out of date, for example an endpoint the plan never declared, or a behavior that changed during implementation for a good reason. Converge treats the artifacts as the only source of intent, so the only remedy it offers is a task to justify or remove the code. When the team wants to keep the code, the agent edits spec.md and plan.md by hand, with no rules about IDs, completed tasks, or where the new content may come from.

Proposed Solution

Keep converge append-only and give its code-ahead findings a second route.

1. For each unrequested or contradicts finding, converge asks which side is right. "The spec is right" keeps today's behavior and appends a task. "The code is right" adds no task, and the report lists the finding as artifact drift.
2. A core amend step takes those confirmed findings and edits the feature's own spec.md and plan.md under fixed rules:
   • Content comes only from the confirmed finding and the feature's artifacts. Code is read only to resolve file paths, never to write requirements. Git history is not a source.
   • Existing FR, SC and T IDs are never reused or renumbered. New IDs continue the file's own convention and width.
   • Tasks marked [X] are never edited.
   • Entries marked RETIRED, SUPERSEDED by [ID] or CANCELLED are never amended or revived. The amendment goes to the live entry.
   • An item that conflicts with a constitution MUST rule is withheld and reported, not written.
   • A dated revision note records which entries changed.

Out of scope: deduplicating repeated converge runs (#4269 points toward stopping on unchecked tasks instead), and extension-specific parts such as parsing a feature path from the arguments.

Alternatives Considered

• A standalone core command that takes a hand-written gap report and amends spec, plan and tasks. The community reconcile extension works this way today. It does the job, but the user has to find drift that converge has already found.
• A flow-back mode inside converge that edits spec.md and plan.md directly. This breaks converge's append-only contract, so I don't recommend it.
• Leave this to community extensions and link them from the Flow-Back section of evolving-specs.md. If maintainers prefer this, I'm happy to send that docs PR instead.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

All agents

Use Cases

1. Implementation added POST /api/v1/exports, which plan.md never mentions. Converge reports it as unrequested. The team keeps it, so plan.md gets the endpoint and spec.md gets a new FR, and nobody gets a task to remove code that works.
2. A validation rule was relaxed during implementation after a product discussion. Converge reports contradicts on FR-007. The team confirms the code, and FR-007 is amended with a revision note instead of getting a revert task.

Acceptance Criteria

• Converge still writes only to tasks.md, and only by appending
• Code-ahead findings can be marked as artifact drift instead of producing a task
• The amend step edits only the current feature's spec.md and plan.md, and only from confirmed findings
• No ID reuse or renumbering, no edits to [X] tasks, no revival of RETIRED, SUPERSEDED or CANCELLED entries
• The Flow-Back section of evolving-specs.md names the command
• Template scaffold tests cover the new rules, with positive and negative cases

Additional Context

Two community extensions already cover this gap:

• reconcile (https://github.com/stn1slv/spec-kit-reconcile), which I maintain. It amends spec, plan and tasks from a gap report. Its fixture project has 23 regression traps covering ID conventions, bugfix markers, retired entries and constitution conflicts. I would deprecate it if core covers this.
• intent (https://github.com/SuhaibAslam/spec-kit-reconcile), first proposed as a bundled extension in Add intent reconciliation extension #3848.

Related: #4156 and #4158 (/speckit.revise) handle intentional requirement changes. This issue is about drift found after implementation. Both rely on the same RETIRED, SUPERSEDED and CANCELLED markers.

AI Disclosure

Drafted with Claude Code (Claude Opus 5.5), human-supervised. The agent compared the reconcile extension with converge.md, the docs and the related issues, and drafted this text.