scaffold-agent-specs 0.2.1 → 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/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",
@@ -71,7 +74,8 @@
     "e5eab6b6a716b79a496d25aa501a1c98cef886b0ce695ef9becc94c77c442824",
     "e697e51065467c9b160859efea601535fb0fcec175c7705ce13424fe7b363269",
     "a6160169f9e674ca96105498854550b7dbe3557454f6dab57325e255648468ab",
-    "79548f0b3701dbac5b3872726fcba40663774eb867744bdfdc21b55b75ca2dd5"
+    "79548f0b3701dbac5b3872726fcba40663774eb867744bdfdc21b55b75ca2dd5",
+    "b2602cb00f67b62bb7a372d40d7bfeb815331853610da550e22253c37044c289"
   ],
   "CLAUDE.md": [
     "67de3db5b7413656ff1d221df90360fdfd0dd80608eb5dbae0416fecf359cbf8",
@@ -91,7 +95,8 @@
     "05dd5854cb7a287ad2d39119c4f10b647415d2a6b01be0d7c6fe8427a012590c",
     "b112b7ebdae8c2b7eed70aa15c7118f6804abcf44b628d89b0f0ac58ac84da51",
     "9a1e43ec8035a467e546d8e9a6a53a9d5ad86d87a493680f938a4ada24b13fb1",
-    "f486c636571db610be3cfbb4d832db28ff22b2f1a50fbfcbf721c66a349d20de"
+    "f486c636571db610be3cfbb4d832db28ff22b2f1a50fbfcbf721c66a349d20de",
+    "3f2ba6e5ec19b4f54149c5e344c985e8df51078be206a5ba7429596b987acf30"
   ],
   "docs/adr/README.md": [
     "1d2c05c11246d0d45592f930b3a339bf454363875b968f650165e91a906c95af"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.2.1",
+  "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,14 +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. To extend a completed feature, follow [Amending a completed feature](docs/WORKFLOW.md#amending-a-completed-feature).
+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.
-- A new capability follows the feature workflow even when the user asks for it directly. The only exception is a small one whose whole behavior fits in one sentence, such as an extra option or a single-step command like undo: the request approves it. Before building it, ask about any consequential choice it leaves open, such as which item "most recent" means. If a feature is in progress, commit its current milestone first. Record it in the active or a completed feature when it fits that feature's purpose; otherwise describe it in the commit message. A new view, report, or multi-step workflow, or anything needing more than a quick question to settle, is a new feature.
-- 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
 

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. A direct user request approves it only within the small-capability exception in `AGENTS.md`; anything larger becomes a separate feature. 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,15 +108,19 @@ 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
 
-## Amending a completed 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.
 
-When the user asks to extend a completed feature with a small addition that fits its purpose (for example, a new output option for an existing command), amend that feature instead of creating a new one. A specific, explicit request approves the addition; if it leaves consequential choices open, propose them first as in Phase 2.
+- **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.
 
-- **Record before building:** add new requirement, acceptance, and task IDs after the existing ones, and log the change, its date, and the user's request in the plan's scope change log. Never renumber, rewrite, or delete existing rows or their evidence.
-- **Reopen honestly:** set the `TASKS.md` status to `In progress` while working. Implement and verify through Phases 4 and 5, including automated tests, and set it back to `Complete` only when the new criteria pass.
-- **Know the limits:** use a new feature instead when the addition is independently useful, needs more than a few acceptance criteria, or changes behavior that existing requirements define. Changing defined behavior follows the superseding rules below. Ordinary bug fixes that restore specified behavior need no feature documents.
+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