specflow-cc 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.17.0] - 2026-03-29
+
+### Added
+
+- **Defer-to-TODO enforcement** — when spec-reviser defers requirements during scope reduction, TODOs are now automatically created in `.specflow/todos/TODO.md`
+  - New Step 5.5 in spec-reviser agent: mandatory TODO creation for every deferred item
+  - Revise command fallback mode also enforces TODO creation for deferred items
+  - Spec-auditor now reminds that removed requirements must be captured as TODOs when recommending scope reduction
+  - Closes a process gap where deferred work could be silently lost (discovered via SPEC-159 incident)
+
 ## [1.16.0] - 2026-03-23
 
 ### Added

package/agents/spec-auditor.md

@@ -267,6 +267,10 @@ Set NEEDS_DECOMPOSITION if ANY of:
 - Recommend `/sf:run --parallel` mode
 - Set status to NEEDS_DECOMPOSITION (if no critical issues)
 
+**If recommending scope reduction (removing requirements):**
+- Explicitly note in the audit that removed requirements MUST be captured as TODOs
+- Add to recommendations: "Any requirements removed during revision must be tracked via `/sf:todo` to prevent scope loss"
+
 ## Step 3.6: Delta Validation
 
 **Detection:** Check if spec frontmatter contains `delta: true`.

package/agents/spec-reviser.md

@@ -123,13 +123,44 @@ Append to Audit History:
 **Applied:** [what was applied]
 
 **Changes:**
-1. [✓ if applied, ✗ if skipped] [Item description] — [what was done]
-2. [✓/✗] [Item description] — [what was done]
+1. [✓ if applied, ✗ if skipped, ⏸ if deferred] [Item description] — [what was done]
+2. [✓/✗/⏸] [Item description] — [what was done]
 
 {If any skipped:}
 **Skipped:** [reason for skipping recommendations]
+
+{If any deferred:}
+**Deferred:** [items deferred to follow-up work]
 ```
 
+## Step 5.5: Create TODOs for Deferred Items
+
+After recording the Response, check if any items were marked as deferred (⏸).
+
+**If no deferred items:** Skip this step.
+
+**If deferred items exist:**
+
+For each deferred item:
+
+1. Read `.specflow/todos/TODO.md` to find the highest existing TODO ID
+2. Generate next TODO ID (zero-padded to 3 digits, starting from 001)
+3. Create a new TODO entry with:
+   - **Description:** `{item description} (deferred from {SPEC-XXX} audit v{N})`
+   - **Priority:** —
+   - **Notes:** `Origin: {SPEC-XXX} Response v{N}. {reason for deferral}`
+
+4. Insert the new entry into `.specflow/todos/TODO.md` after the `# To-Do List` line
+
+5. Append a "TODOs Created" subsection to the Response in Audit History:
+
+```markdown
+**TODOs Created:**
+- TODO-{XXX} — {item description}
+```
+
+**Important:** This step is mandatory. Every deferred item MUST produce a TODO. If TODO creation fails, report the failure — do not silently skip.
+
 ## Step 6: Update Frontmatter
 
 Set status to "auditing" (ready for re-audit).
@@ -169,9 +200,16 @@ Output directly as formatted text (not wrapped in a code block):
 
 3. [✗] [Item] — [reason]
 
+{If any deferred:}
+### Deferred → TODOs Created
+
+4. [⏸] [Item] → TODO-{XXX}
+
 ### Files Modified
 
 - .specflow/specs/SPEC-XXX.md
+{If TODOs created:}
+- .specflow/todos/TODO.md
 
 ### Next Step
 
@@ -188,6 +226,8 @@ Tip: `/clear` recommended — auditor needs fresh context
 - [ ] User's revision scope understood
 - [ ] Changes applied precisely
 - [ ] Revision Response recorded in Audit History
+- [ ] Deferred items (if any) created as TODOs in `.specflow/todos/TODO.md`
+- [ ] TODOs Created subsection appended to Response (if deferred items exist)
 - [ ] Frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes provided

package/commands/sf/revise.md

@@ -404,7 +404,13 @@ Items {N, M} require clarification before deciding.
 `/sf:audit` — re-audit with applied changes
 
 {If deferred items exist:}
-Note: Deferred items saved to `.specflow/todos/` for future consideration.
+### Deferred → TODOs Created
+
+| Deferred Item | TODO Created |
+|---------------|-------------|
+| {item description} | TODO-{XXX} |
+
+Note: Each deferred item has been saved as a TODO for future consideration.
 ```
 
 </workflow>
@@ -464,6 +470,19 @@ NEXT_VERSION=$((RESPONSE_COUNT + 1))
 **Summary:** Applied {X}/{Y} items, Skipped {Z}, Deferred {W}
 ```
 
+### Create TODOs for Deferred Items
+
+After recording the Response, if any items were marked "Deferred":
+
+1. Read `.specflow/todos/TODO.md` to find the highest existing TODO ID
+2. For each deferred item, create a new TODO entry:
+   - **Description:** `{item description} (deferred from {SPEC-XXX} audit v{N})`
+   - **Priority:** —
+   - **Notes:** `Origin: {SPEC-XXX} Response v{N}. {reason for deferral}`
+3. Append "**TODOs Created:**" subsection to the Response in Audit History listing created TODO IDs
+
+**This step is mandatory.** Every "Deferred" decision MUST produce a corresponding TODO.
+
 ### Update Status
 
 In spec frontmatter: `status: auditing`
@@ -480,6 +499,7 @@ In STATE.md:
 - [ ] Revision scope determined (all/specific/custom)
 - [ ] Changes applied correctly
 - [ ] Response recorded in Audit History
+- [ ] Deferred items (if any) created as TODOs in `.specflow/todos/TODO.md`
 - [ ] Spec frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes shown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"