specflow-cc 1.16.0 → 1.17.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.1] - 2026-04-07
+
+### Fixed
+
+- **TODO.md data loss prevention** — all 6 commands that modify TODO.md now use the `Edit` tool (targeted diff) instead of `Write` (full rewrite), preventing the agent from accidentally dropping entries when reconstructing large files
+  - Affected: `sf:todo`, `sf:plan`, `sf:done`, `sf:triage`, `sf:priority`, `spec-reviser`
+  - `Write` is now only used for initial TODO.md creation; all subsequent modifications use `Edit`
+  - Each command includes explicit "CRITICAL: never rewrite the entire file" guardrails
+
+## [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

@@ -1,7 +1,7 @@
 ---
 name: sf-spec-reviser
 description: Revises specifications based on audit feedback, applying targeted or full changes
-tools: Read, Write, Glob, Grep, AskUserQuestion
+tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
 <role>
@@ -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. Use the **Edit** tool (NOT Write) to insert the new entry into `.specflow/todos/TODO.md` after the first `---` following `# To-Do List` — never rewrite the entire file, as this would destroy existing todos
+
+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/done.md

@@ -4,6 +4,7 @@ description: Finalize specification, archive, and update state
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - Glob
   - Grep
@@ -278,9 +279,10 @@ Check if the spec frontmatter contains a `source:` field (e.g., `source: TODO-00
 
 1. Read `.specflow/todos/TODO.md`
 2. Check if the referenced TODO-XXX entry still exists in the file
-3. **If it exists** — remove it (the entire block from `## TODO-XXX` heading through the next `---` separator, inclusive)
-4. Update `*Last updated:` timestamp with note: `TODO-XXX cleaned up (completed via SPEC-YYY)`
-5. Write the updated TODO.md
+3. **If it exists** — use the **Edit** tool (NOT Write) to remove the entire block (from `## TODO-XXX` heading through the next `---` separator, inclusive) — replace with empty string
+4. Use the **Edit** tool to update `*Last updated:` timestamp with note: `TODO-XXX cleaned up (completed via SPEC-YYY)`
+
+**CRITICAL:** Never rewrite the entire file with Write. Use Edit to remove the specific block and update the timestamp — this preserves all other todos.
 
 **If no `source:` field or TODO already removed:** Skip — no action needed.
 

package/commands/sf/plan.md

@@ -4,6 +4,7 @@ description: Convert a to-do item into a full specification
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - Glob
   - Grep
@@ -152,10 +153,11 @@ Use the priority from the todo as the spec's initial priority.
 **This step is MANDATORY. Do NOT skip it after the agent returns.**
 
 1. Read `.specflow/todos/TODO.md`
-2. Remove the entire todo block (from `## TODO-XXX` heading through the next `---` separator, inclusive)
-3. Update `*Last updated:` timestamp with note: `TODO-XXX converted to SPEC-YYY`
-4. Write the updated TODO.md
-5. **Verify** by reading TODO.md again — the converted todo MUST NOT appear
+2. Use the **Edit** tool (NOT Write) to remove the entire todo block (from `## TODO-XXX` heading through the next `---` separator, inclusive) — replace the block with empty string
+3. Use the **Edit** tool to update `*Last updated:` timestamp with note: `TODO-XXX converted to SPEC-YYY`
+4. **Verify** by reading TODO.md again — the converted todo MUST NOT appear
+
+**CRITICAL:** Never rewrite the entire file with Write. Use Edit to remove the specific block and update the timestamp — this preserves all other todos.
 
 **Important:** Only remove after confirmed spec creation.
 

package/commands/sf/priority.md

@@ -4,6 +4,7 @@ description: Interactive prioritization of specifications and to-dos
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - Glob
   - AskUserQuestion
@@ -117,7 +118,7 @@ Your choice:
 If input matches pattern `{ID}={priority}`:
 
 1. Validate priority (high | medium | low)
-2. Update frontmatter in spec file OR priority line in TODO.md
+2. Update frontmatter in spec file OR use the **Edit** tool (NOT Write) to update the priority line in TODO.md — never rewrite the entire file
 3. Display confirmation
 4. Return to Step 3
 

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/commands/sf/todo.md

@@ -4,6 +4,7 @@ description: Add a new to-do item for future work
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - AskUserQuestion
 ---
@@ -84,7 +85,9 @@ Create from template:
 ```
 
 **If TODO.md exists:**
-Insert new todo after `# To-Do List` line:
+Use the **Edit** tool (NOT Write) to make two targeted edits:
+
+1. Insert new todo block after the first `---` following `# To-Do List`:
 
 ```markdown
 ## TODO-{XXX} — {YYYY-MM-DD}
@@ -95,7 +98,9 @@ Insert new todo after `# To-Do List` line:
 ---
 ```
 
-Also update `*Last updated:` line at the bottom.
+2. Update the `*Last updated:` line at the bottom.
+
+**CRITICAL:** Never rewrite the entire file. Use Edit to insert the new block and update the timestamp — this preserves all existing todos.
 
 ## Step 6: Display Confirmation
 

package/commands/sf/triage.md

@@ -4,6 +4,7 @@ description: Convert scan findings into actionable TODO items
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - AskUserQuestion
 ---
@@ -182,7 +183,11 @@ If TODO.md doesn't exist, create with header:
 *Last updated: {YYYY-MM-DD}*
 ```
 
-If TODO.md exists, insert new entries after `# To-Do List` line and update timestamp.
+If TODO.md exists, use the **Edit** tool (NOT Write) to make two targeted edits:
+1. Insert new entries after the first `---` following `# To-Do List`
+2. Update the `*Last updated:` timestamp
+
+**CRITICAL:** Never rewrite the entire file with Write. Use Edit to insert new blocks and update the timestamp — this preserves all existing todos.
 
 ## Step 7: Display Results
 

package/package.json

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