scaffold-agent-specs 0.2.0 → 0.2.2

package/README.md

@@ -103,6 +103,12 @@ npx scaffold-agent-specs@latest update
 
 There is intentionally no `implement` command: an agent should follow `AGENTS.md` and `docs/WORKFLOW.md` and wait for a separate implementation instruction. ADRs can be created from `.agent-specs/templates/adr/ADR.md` once architectural decisions are adopted.
 
+## Workflow classification
+
+The opinionated workflow uses an ordered [classification procedure](scaffold/docs/WORKFLOW.md#classifying-a-change) for fixes, implementation details, amendments, new features, and behavioral replacements. Amendments preserve earlier completion events and verification evidence while tracking the expanded scope honestly. Direct requests and sentence length do not bypass new-feature gates.
+
+The [classification regression suite](examples/workflow-classification/README.md) defines controlled scenarios, approval boundaries, repeated cross-agent trials, and a completed-amendment walkthrough. It is an evaluation protocol; passing CLI tests does not establish cross-agent consistency.
+
 ## Develop
 
 To run the CLI from a clone of this repository:

package/lib/basic-AGENTS.md

@@ -8,6 +8,7 @@ These shared instructions apply to all coding agents. Follow existing project pr
 - Explain assumptions, uncertainty, incomplete work, and failed or unrun checks honestly.
 - Follow existing UI conventions and design-system documentation when working on visual interfaces.
 - Update affected documentation alongside code. Document consequential decisions where the project normally records them. Keep documentation concise and prefer an existing source of truth.
+- Add or update automated tests for behavior changes when the project has a test suite; if a behavior can't reasonably be tested automatically, say why.
 - Run relevant checks before claiming completion. Never claim unverified success. Report changes, verification evidence, and remaining limitations.
 - Follow repository conventions and the user's instructions for Git workflow and commit messages. Keep commits focused; do not commit secrets, credentials, local environment files, or unrelated changes.
 - Do not push, rewrite history, or change branches without the user's authorization.

package/lib/released-fingerprints.json

@@ -12,7 +12,8 @@
     "2c4ced9eefb608d9dac68708a760b4425bafccb287dfd3701d16d4f416afa7a8",
     "418ad2f5d8693d63d436e77b61d09a335919cbe7caad702c62e330cbfcc8bc2e",
     "13465e7579dee1327232b4d2ca468b4c2dae7e988764a0149f9dfeb9febfa39f",
-    "38bf94015959e497a19487e25ba7165ec7dc8d984c38c3bf3e30628f80064432"
+    "38bf94015959e497a19487e25ba7165ec7dc8d984c38c3bf3e30628f80064432",
+    "c22ee1a760d626567b03e41e9386df5ee7c3f7915db0a08196e33c2d0f206f0f"
   ],
   ".agent-specs/templates/feature/DESIGN.md": [
     "67ab041fede40d545a8a1e39866648e0fbbea0dfcc754082e6484d90d4e9780d",
@@ -26,7 +27,8 @@
     "41f8adea2769c825a4e50b82ab1c7f20249923fd8fd0cdb2f91a3c45626cd723",
     "66e60c4ac70c18ff549a57691b73113dc0f015fcfefcbad537a20fe1213f3702",
     "08bfa77df5a28778ea6ab9d8c44858c3fe37f6beb2719f38f30cfc314f80f147",
-    "23ee3da377f7f99718bfc846fa7e37e5b9470bbbf0f3ec08359d4a53756428dc"
+    "23ee3da377f7f99718bfc846fa7e37e5b9470bbbf0f3ec08359d4a53756428dc",
+    "14edcfe7eb6e46b9bcd1e82d91c385b93ec92bc3b214a80c9d46f087fb946468"
   ],
   ".agent-specs/templates/feature/RESEARCH.md": [
     "667580dd935face184e8f8a8177a092bf8d146a9e60c9396fddbae2b64c9cb40",
@@ -34,7 +36,8 @@
   ],
   ".agent-specs/templates/feature/TASKS.md": [
     "aa8494ff4e045f8ab65f360654b0f2f4036c744dd72caa720e14436d48626fde",
-    "bed26521049b15acfbd80ebe226873d75c604f9d0c88238a3ecabb8a9dd73cac"
+    "bed26521049b15acfbd80ebe226873d75c604f9d0c88238a3ecabb8a9dd73cac",
+    "103676389ad9290852d643d02aff8065cb2bc01108a67cf560a108e149b8fb1e"
   ],
   ".agent-specs/templates/project/ARCHITECTURE.md": [
     "d4b2e5ed4449b70746b3dfd628e111edffbb69d7247267cab86e6d48c506943d",
@@ -67,7 +70,12 @@
     "d527b953d0f1d6fd805e9800ba4ba71db2e5e1c25dcdfe4bdbfc6706e1782314",
     "f730107d9764f5a0a294124e04c9a5c89ecda9e6f3365afc9b0ca4a952dec1d1",
     "9c8d3e7eb471911d0ca58bfd0331298effcee068f28b71f52373c05641c3bc93",
-    "94a8b845546e7f7564cac89ee73cdcb24ac4d54989c7a9f6c676e7e8066c64cd"
+    "94a8b845546e7f7564cac89ee73cdcb24ac4d54989c7a9f6c676e7e8066c64cd",
+    "e5eab6b6a716b79a496d25aa501a1c98cef886b0ce695ef9becc94c77c442824",
+    "e697e51065467c9b160859efea601535fb0fcec175c7705ce13424fe7b363269",
+    "a6160169f9e674ca96105498854550b7dbe3557454f6dab57325e255648468ab",
+    "79548f0b3701dbac5b3872726fcba40663774eb867744bdfdc21b55b75ca2dd5",
+    "b2602cb00f67b62bb7a372d40d7bfeb815331853610da550e22253c37044c289"
   ],
   "CLAUDE.md": [
     "67de3db5b7413656ff1d221df90360fdfd0dd80608eb5dbae0416fecf359cbf8",
@@ -84,7 +92,11 @@
     "6ae499a00796e17367c1c25bd5f162b040622aa1bcc4f0d39ba5efc8817bfbd3",
     "59708748d05e26859c71eb9beab4f27b1e9dcded7bc4648d04bb35033b853022",
     "70de8d1dc3a24c3bc293a696ad2b150c6d9dced69d0a5d03f54f3f7e275bfa33",
-    "05dd5854cb7a287ad2d39119c4f10b647415d2a6b01be0d7c6fe8427a012590c"
+    "05dd5854cb7a287ad2d39119c4f10b647415d2a6b01be0d7c6fe8427a012590c",
+    "b112b7ebdae8c2b7eed70aa15c7118f6804abcf44b628d89b0f0ac58ac84da51",
+    "9a1e43ec8035a467e546d8e9a6a53a9d5ad86d87a493680f938a4ada24b13fb1",
+    "f486c636571db610be3cfbb4d832db28ff22b2f1a50fbfcbf721c66a349d20de",
+    "3f2ba6e5ec19b4f54149c5e344c985e8df51078be206a5ba7429596b987acf30"
   ],
   "docs/adr/README.md": [
     "1d2c05c11246d0d45592f930b3a339bf454363875b968f650165e91a906c95af"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A tiny, spec-driven workflow scaffold for AI coding agents",
   "type": "module",
   "license": "MIT",

package/scaffold/.agent-specs/templates/feature/ACCEPTANCE_MATRIX.md

@@ -23,6 +23,8 @@ If the user approves changing or waiving a criterion, update the approved scope
 
 If a later feature supersedes this behavior, preserve these criteria, results, and evidence as historical records. Add a dated note under verification notes identifying the affected IDs and linking to the replacement feature's plan and acceptance matrix. A historical `Pass` does not verify the replacement; its matrix must record fresh evidence. See the supersession rules in `docs/WORKFLOW.md`.
 
+For amendments, preserve existing rows and evidence and append dated verification runs below with criterion IDs, results, and evidence. Record new criteria in new rows. Recheck relevant existing behavior and explain any reliance on earlier evidence. Historical passes do not override later failures or missing required verification. See the amendment procedure in `docs/WORKFLOW.md`.
+
 ## Verification notes
 
 [Commands, test environment, observations, limitations, and links to test reports. Leave as 'Not yet verified' during initial specification.]

package/scaffold/.agent-specs/templates/feature/PLAN.md

@@ -63,6 +63,8 @@
 | ------------ | ---------------------- | -------------------------------------------- |
 | [YYYY-MM-DD] | Initial approved scope | [Explicit approval reference / conversation] |
 
+For amendments, append the bounded scope and approval reference above before implementation; preserve existing requirements and exclusions and append new IDs. Lifecycle events belong in `TASKS.md`, and historical and current verification evidence in `ACCEPTANCE_MATRIX.md`.
+
 ## Related and superseded features
 
 [State 'None' if unrelated to earlier features. Otherwise link the relevant feature plans and identify the affected requirement and acceptance IDs, the behavior being replaced or extended, and what remains unchanged. Qualify IDs with their feature because IDs are local to each feature. Distinguish planned replacement from implemented supersession; approval alone does not replace existing behavior.]

package/scaffold/.agent-specs/templates/feature/TASKS.md

@@ -11,7 +11,7 @@ This is the **authoritative progress checklist**. Draft ordered, independently v
 - `Ready`: readiness checked before implementation; remaining blockers are listed below.
 - `In progress`: implementation underway.
 - `Implemented (verification pending)`: tasks done, but some acceptance criteria are not yet `Pass`.
-- `Complete`: every acceptance criterion is `Pass`, or the user has explicitly accepted the exceptions.
+- `Complete`: every required current-scope acceptance criterion has passing applicable evidence, or the user has explicitly accepted the exceptions. For amendments, consult appended verification runs; historical passes do not override current failures or missing verification.
 
 ## Tasks
 
@@ -26,3 +26,7 @@ This is the **authoritative progress checklist**. Draft ordered, independently v
 ## Progress notes
 
 [Only durable information needed to interpret task state. Put architecture rationale in `PLAN.md` or adopted ADRs, and test results in `ACCEPTANCE_MATRIX.md`.]
+
+## Lifecycle history
+
+[Append dated completion and reopening/scope-extension events as they occur. Include covered requirement/acceptance IDs and a reference to verification evidence for completion; link the scope change for amendments. Preserve prior events and task checkmarks. Do not invent dates for missing history. This is an event log, not another current status. Before any such events, state 'No lifecycle events recorded yet'.]

package/scaffold/AGENTS.md

@@ -22,13 +22,13 @@ For new features:
 4. **Stop after specification.** Summarize the documents and blockers. Start implementation only when the user explicitly requests it.
 5. Implement within approved scope, keep documents current, and verify acceptance outcomes before declaring completion.
 
-Existing-feature work and ordinary fixes follow the user's requested scope; do not force a new feature directory for every small change.
+Classify requests using [Classifying a change](docs/WORKFLOW.md#classifying-a-change) before choosing a workflow. That procedure owns the boundaries between fixes, implementation details, amendments, new features, and behavioral replacements, including their approval requirements. Apply it to active and completed features alike. Sentence length, implementation effort, and a direct request do not exempt a new feature from the workflow.
 
 ### Scope and decision boundaries
 
-- Ask before changing promised behavior, exclusions, or acceptance criteria, or adding an independent user-facing capability, however small.
-- Implementation choices necessary to fulfill agreed outcomes may proceed without renewed approval. This includes validation and error feedback needed to make an agreed form work coherently. Record meaningful choices in the plan. New capabilities such as undo, additional management actions, or a changed recovery policy need approval.
-- Surface major dependencies, migrations that modify or delete existing data, security-sensitive choices, substantial complexity, and broad architectural consequences before committing to them. Follow the workflow for technical refinements within scope.
+- Stay within the approved observable contract. Follow the classification procedure before adding capabilities or changing requirements, exclusions, or acceptance expectations.
+- Separate scope classification from decision approval. Routine implementation choices need no renewed approval; surface major dependencies, migrations that modify or delete existing data, security-sensitive choices, substantial complexity, and broad architectural consequences before committing to them.
+- Reuse explicit authorization already given for the classified scope. Clarifying a consequential choice does not replace the proposal and specification gates for a new feature.
 
 ## Documentation and completion
 
@@ -36,13 +36,14 @@ Existing-feature work and ordinary fixes follow the user's requested scope; do n
 - Respect document ownership: `PLAN.md` owns scope and approach; `ACCEPTANCE_MATRIX.md` owns verification evidence; `TASKS.md` owns progress and the sole feature lifecycle status. Optional documents must not supersede them.
 - Use the [optional project document catalog](docs/WORKFLOW.md#optional-project-document-catalog) for creation triggers, ownership, and when to consult shared references. Reuse existing sources, create documents only when useful and authorized, and remove stale claims. Feature-level optional documents are covered by the workflow's Phase 3 table.
 - Record significant adopted architectural decisions in `docs/adr/`; keep unimplemented proposals in the plan. Use the ADR template and avoid ADRs for routine local details.
+- Add or update automated tests for every behavior change, inside or outside a feature, whenever the project has a test suite. If a behavior cannot reasonably be tested automatically, say why and verify it another way; manual verification alone is not a substitute for an achievable test.
 - Run relevant tests, linters, type checks, and builds before claiming completion, or explain precisely why checks were not run. Record concrete evidence; implementation alone is not a pass.
 - For applicable changes, document rollout, migrations, recovery limits, and post-release checks in the existing feature documents, linking to shared deployment/publishing guidance. Distinguish implemented and verified work from released behavior. Follow existing authorization for release execution; documentation alone does not grant it.
 - Mark a feature complete only when acceptance criteria pass or the user explicitly accepts exceptions. Report unresolved failures, missing verification, migrations, and follow-up work.
 
 ## Git commits
 
-Follow the user's explicit commit preference first, including requests to review diffs before commits or to leave work uncommitted. Otherwise, commit your work as you go, without waiting to be asked. Commit approved feature specs on their own. During implementation, commit at **milestones**: points you would want to return to. A milestone passes the relevant checks and has one theme you can describe in a sentence, such as the domain logic for a feature with its tests, or the UI built on top of it. A feature typically takes a few commits; neither one per task nor one per feature. Also commit before risky steps (large refactors, migrations, dependency changes) and before ending a session. Split a commit that would mix unrelated concerns.
+Follow the user's explicit commit preference first, including requests to review diffs before commits or to leave work uncommitted. Otherwise, commit your work as you go, without waiting to be asked. Commit approved feature specs on their own. During implementation, commit at **milestones**: points you would want to return to. A milestone passes the relevant checks and has one theme you can describe in a sentence, such as the domain logic for a feature with its tests, or the UI built on top of it. A feature typically takes a few commits; neither one per task nor one per feature. When a feature has both substantial domain logic and an interface layer (UI, CLI, or API), commit the domain logic with its tests before building on it. Also commit before risky steps (large refactors, migrations, dependency changes) and before ending a session. Split a commit that would mix unrelated concerns.
 
 - Run the relevant checks before committing. If you commit while something is failing or incomplete, say so in the message.
 - Don't commit secrets, credentials, local environment files, or build output that the repository doesn't already track.

package/scaffold/docs/WORKFLOW.md

@@ -2,6 +2,29 @@
 
 This document expands the feature lifecycle required by [`AGENTS.md`](../AGENTS.md). Feature specifications live in `docs/features/`; reusable templates live in `.agent-specs/templates/`.
 
+## Classifying a change
+
+Before choosing a path, inspect the request, relevant implementation, existing requirements and exclusions, tests, and approval history. Classify the behavioral change, not its wording, line count, estimated effort, or the number of questions asked. State the classification and owning feature briefly when scope changes or the boundary is unclear.
+
+Apply these rules in order:
+
+1. **Fix:** restores an established contract without changing it. Identify the requirement, test, or other agreed behavior being restored; calling a request a "bug" is not evidence. Implement and verify under the user's requested scope without new feature documents. If intended behavior is unknown or sources conflict, resolve that uncertainty before classifying dependent work.
+2. **Implementation detail:** fulfills approved outcomes without adding or changing the observable contract. Proceed within authorized implementation scope, recording meaningful choices in the owning plan when one exists. Refactoring and necessary validation/error feedback may qualify; a new recovery policy does not.
+3. **Behavioral replacement:** changes an existing approved requirement or exclusion, including changing a default or removing a promised outcome. Use the new-feature workflow and the supersession rules below, identifying exactly what changes. This takes precedence over amendment even for a tiny change. For an unimplemented feature, revise its scope through Phase 2 and update its specification instead; preserve the approval/change history, and obtain implementation authorization for the revised scope.
+4. **Amendment:** adds a bounded variation of an existing feature's outcome. All of the following must hold: an existing feature clearly owns the outcome; existing requirements and exclusions remain valid; there is no distinct user outcome, separate operation, or new workflow; acceptance coverage extends existing scenarios rather than establishing a separate behavioral contract. Follow the amendment procedure below for active or completed features.
+5. **New feature:** any other added capability, including a distinct user outcome or independently useful operation. Follow Phases 1–5 even when requested directly or easy to implement. If there is no existing feature to own an addition, use this path rather than recording new scope only in a commit message.
+
+"Independently useful" means a distinct user outcome, not technical independence: undo depends on an existing action but adds a recovery operation. A new view, report, or history browser normally adds an outcome. An optional output format for an existing command can be an amendment if the existing contract permits it; changing its promised default is a replacement. Extra coverage for empty inputs or the same formatting option does not by itself make a new feature. New permissions, retention rules, recovery semantics, or journeys introduce separate contracts that cannot be hidden by combining acceptance rows. Neither sentence length nor a numerical acceptance-criterion threshold decides classification.
+
+For mixed requests, separate independently classifiable parts and identify their dependencies. Do not use a fix or amendment to carry an unrelated new capability through a lighter path. If information needed to distinguish paths is missing, ask a focused question; do not silently assume the lighter path.
+
+### Classification and authorization are separate
+
+- A specific request to implement a qualifying fix or amendment authorizes that stated work. A request to explore or propose does not authorize implementation. For an agent-proposed amendment, obtain explicit scope approval and implementation authorization before building; these may be given together. Record amendment scope before implementation.
+- Consequential unresolved choices require human input regardless of classification. Asking and answering those questions does not waive a new feature's proposal, specification, or separate implementation gate.
+- For a new feature or replacement, reuse prior approval only when it clearly covers the same proposed scope and workflow stage. Otherwise follow the applicable gates. Routine technical choices within authorized scope do not need another approval.
+- Significant dependencies, destructive/data-modifying migrations, security-sensitive choices, and broad architectural consequences still require human input even when they are implementation details. Purely additive migrations that leave existing data untouched may proceed within scope; record and report them.
+
 ## Phase 1: Discover (conversation only)
 
 - Read existing code and documentation when relevant, then explore the user's idea collaboratively. Consult `docs/PRODUCT.md` or the existing product reference when present to understand users, core journeys, and agreed boundaries; it does not authorize new feature scope.
@@ -68,7 +91,7 @@ If the approved scope changes behavior owned by an earlier feature, fill the pla
 - Re-read the active feature's plan, acceptance matrix, and tasks, plus any optional design/research documents; inspect relevant code and applicable `docs/conventions/` documentation.
 - Check readiness: requirements coherent, blockers identified, implementation direction sensible, verification approach practical. Consult the existing testing guide for setup, check selection, and integration boundaries. Record any blockers under "Dependencies and blockers" in `TASKS.md`, then set its status to `Ready`, and to `In progress` once work starts.
 - Seek human input before significant new dependencies, migrations that modify or delete existing data, security-sensitive choices, or changes to approved behavior. Purely additive migrations (for example, a new table or store that leaves existing data untouched) need no prior approval, but record them in the plan and report them. Technical refinement that stays within scope usually needs no additional approval.
-- Treat an independent user-facing capability beyond the approved requirements as a scope change, however small (for example, undoing an action or an extra management capability): ask before building it, then add it to the plan's requirements and scope change log. Validation and error feedback necessary to fulfill agreed outcomes may proceed without another gate; document meaningful choices in the plan. For example, an agreed form needs feedback when submission fails, but adding a new retry policy or recovery workflow may change the product contract. Supporting work that leaves behavior unchanged, such as operator scripts or security hardening, needs no approval but belongs in the plan's technical approach.
+- Classify discoveries and requested changes using the procedure above before building them. Amendments extend the owning feature's documents; new capabilities and replacements follow their respective gates. Necessary validation and error feedback may be implementation details, but new retry or recovery semantics can change the contract. Supporting scripts or security hardening qualify as implementation details only when they preserve that contract; their names alone do not exempt them from scope review.
 - Prepare and verify release/recovery steps within the approved scope. Use the project's existing authorization process before deploying, publishing, or modifying production data; a written procedure or implementation request alone is not authorization. Reuse explicit authorization already given rather than asking again.
 - Work through `TASKS.md`, updating checked items to reflect reality. Keep plan notes synchronized when implementation choices change.
 - Add or update tests and record concrete results in `ACCEPTANCE_MATRIX.md`.
@@ -85,14 +108,26 @@ If the approved scope changes behavior owned by an earlier feature, fill the pla
 - Report release state separately from implementation completion: distinguish locally verified, ready for release, and actually released behavior, naming the version/environment when known. Required release or recovery checks remain `Not run` or `Blocked` until evidenced; do not mark the feature complete while they remain required and unverified. If release is explicitly outside the approved scope, implementation may be complete once its acceptance criteria pass; record the remaining release work, owner (or unassigned ownership), and prerequisites in the plan and final handoff without claiming it shipped. Do not introduce a second feature lifecycle status.
 - Create ADRs for meaningful architectural decisions **actually adopted**. Normally do this after the implementation is known; for a consequential choice adopted earlier, record it at that point.
 - Report what was implemented and, if applicable, released, what was validated, any limitations, and whether the feature is complete. A feature is not complete while required acceptance criteria remain failing, blocked, or unverified.
-- Set the `TASKS.md` status to `Complete` only when that holds; otherwise use `Implemented (verification pending)` and list what remains.
+- Set the `TASKS.md` status to `Complete` only when that holds; otherwise use `Implemented (verification pending)` and list what remains. Append a dated completion event in its lifecycle history with covered requirement/acceptance IDs and a reference to verification evidence; preserve earlier events.
+
+## Amending an existing feature
+
+Use this procedure only for changes classified as amendments above. It applies equally to active and completed features. A specific implementation request authorizes a qualifying amendment; settle consequential open choices first. An independent capability or changed approved behavior must take its classified path instead.
+
+- **Record before building:** append requirement, acceptance, and task IDs after existing IDs. Log the date, scope, and approval reference in the plan's scope change log. Preserve existing requirements, exclusions, checked tasks, acceptance rows, results, and evidence. Never renumber or silently rewrite them.
+- **Preserve completion history:** before reopening a completed feature, append its prior completion event to `TASKS.md` lifecycle history if not already recorded, including the covered requirement/acceptance IDs and evidence reference. Use known dates and references only; if historical information is missing, state that rather than inventing it. Existing documents need no wholesale migration.
+- **Reopen honestly:** append a dated reopening event linked to the amendment scope, then set the sole current status to `In progress` when implementation starts. For an approved amendment awaiting implementation, use `Specified` and record that transition; do not leave expanded unverified scope marked `Complete`. For active features, record the scope extension and keep the status accurate. Preserve completed task checkmarks.
+- **Implement and verify:** follow Phases 4 and 5, including automated tests. Verify new criteria and relevant existing behavior for regressions. Append dated verification entries with criterion IDs, actual results, and evidence; do not overwrite historical evidence. A historical `Pass` does not establish that the amended implementation still passes. Explain which existing criteria were rechecked or why earlier evidence remains applicable. New failures or missing required checks prevent completion even when old rows say `Pass`.
+- **Close with evidence:** reconcile documents and set status to `Complete` only when all required current-scope criteria pass or the user explicitly accepts recorded exceptions. Append a new completion event identifying covered IDs and current evidence. If verification remains pending, use `Implemented (verification pending)` and identify unresolved criteria.
+
+Lifecycle history records past events, not additional current statuses. Keep it in `TASKS.md`; verification runs and results belong in `ACCEPTANCE_MATRIX.md`. Correcting an inaccurate historical record requires an explicit explanation, not silent replacement.
 
 ## Superseding earlier feature specifications
 
 A later feature may replace only part of an earlier feature. Related work or an extension does not automatically supersede the entire earlier specification.
 
 - **During specification:** In the new plan's "Related and superseded features" section, link the earlier plan and identify exactly which requirements and acceptance criteria will change, the replacement behavior, and what remains in force. Qualify references with the feature ID (for example, `feature-003-export / FR-002`), since IDs repeat across features. Label the replacement as planned; scope approval alone does not mean the current behavior has changed.
-- **When implemented:** Record the effective replacement date and a commit, PR, or other concrete implementation reference in the new plan. Add a reciprocal "Related and superseded features" note to the earlier plan identifying the affected IDs and linking to the replacement. For staged rollouts, state where the replacement is effective and where the earlier behavior still applies. Do not mark unimplemented portions as superseded.
+- **When implemented:** Record the effective replacement date and a commit, PR, or other concrete implementation reference in the new plan. A commit cannot contain its own hash, so cite the implementing commit's subject, or add its hash in a later commit. Add a reciprocal "Related and superseded features" note to the earlier plan identifying the affected IDs and linking to the replacement. For staged rollouts, state where the replacement is effective and where the earlier behavior still applies. Do not mark unimplemented portions as superseded.
 - **Preserve evidence:** Keep the earlier requirements, acceptance rows, results, and evidence intact. Add a dated supersession note to the earlier acceptance matrix's verification notes, naming affected criteria and linking to the new plan and matrix. An old `Pass` describes the earlier behavior at the recorded verification point; it is not evidence for the replacement. Verify replacement behavior in the new feature's matrix, leaving unverified criteria `Not run` or `Blocked` as appropriate.
 - **Preserve lifecycle history:** Do not reopen a completed feature or rewrite its task checklist merely because a later feature replaces its behavior. Supersession is a relationship recorded in the plans, not a new lifecycle status or acceptance result. Unaffected requirements remain in force. Correcting genuinely inaccurate records is separate from supersession and must be explained explicitly.