specflow-cc 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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
+
+- **Brownfield / Delta Specifications** — spec-creator now detects existing implementations and generates a `## Delta` section describing only what changes, preserving what already works
+- **Delta validation in spec-auditor** — auditor validates delta sections for completeness and correctness in brownfield specs
+- **Changes Applied subsection** in `/sf:done` — delta spec completion summaries now include a dedicated section listing what was actually changed
+
+### Fixed
+
+- **Init re-initialization safety** — `/sf:init` now safely handles re-initialization without overwriting existing `.specflow/` state
+- **Deviations subsection disambiguation** — delta completion template no longer collides subsection names when both Deviations and Delta Deviations are present
+
 ## [1.15.0] - 2026-03-11
 
 ### Fixed

package/agents/spec-auditor.md

@@ -267,6 +267,48 @@ 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`.
+
+**If no delta field or delta is false:** Skip this check entirely.
+
+**If delta is true:**
+
+a. Verify `## Delta` section exists. If missing: Critical issue "Spec marked as delta but no Delta section found."
+
+b. Validate ADDED entries:
+   - For each file in ADDED: use Glob/Grep to check if file already exists in the codebase
+   - If file exists: Critical issue "Delta ADDED file `{path}` already exists. Should this be MODIFIED instead?"
+
+c. Validate MODIFIED entries:
+   - For each file in MODIFIED: use Glob/Grep to check if file exists in the codebase
+   - If file does NOT exist: Critical issue "Delta MODIFIED file `{path}` not found. Should this be ADDED instead?"
+   - Check that each MODIFIED entry has at least one sub-bullet describing the change
+   - If no sub-bullets: Warning "MODIFIED entry `{path}` lacks change description"
+
+d. Validate REMOVED entries:
+   - For each file in REMOVED: use Glob/Grep to check if file exists in the codebase
+   - If file does NOT exist: Warning "Delta REMOVED file `{path}` not found. Already removed or wrong path?"
+
+e. Cross-reference: Check that every file mentioned in `## Requirements` is also listed in `## Delta`
+   - Before comparing, normalize all paths: strip any leading `./` and any trailing `/` from both sides so that `./agents/foo.md`, `agents/foo.md`, and `agents/foo.md/` all resolve to the same key.
+   - Files in Requirements but not in Delta (after normalization): Warning "File `{path}` in Requirements but not in Delta section"
+   - Files in Delta but not in Requirements (after normalization): Warning "File `{path}` in Delta but no detailed requirements specified"
+
+**Record in audit output:**
+
+If delta was present, add to audit summary:
+```
+Delta validation: {pass_count}/{total_count} entries valid
+```
+
+If no delta: omit this line.
+
 ## Step 3.7: Goal-Backward Validation
 
 **Detection:** Check if Goal Analysis section exists in the spec.

package/agents/spec-creator.md

@@ -104,6 +104,22 @@ Then derive requirements that ensure ALL truths are achievable.
 - If complexity is clearly "small" (single file, simple change), Goal Analysis is optional
 - For medium/large specs, include Goal Analysis in the generated specification
 
+## Step 2.7: Brownfield Detection
+
+Determine if the task is brownfield (modifying existing code) or greenfield (creating new functionality from scratch).
+
+Detection heuristic:
+- Task description mentions existing files, modules, or features → brownfield
+- Task type is "refactor" → always brownfield
+- Task type is "bugfix" → always brownfield
+- Task description uses terms like "extend", "add to", "change", "update", "remove from", "refactor" → brownfield
+- Task description mentions creating entirely new commands/agents/features with no existing counterpart → greenfield
+
+**Note:** The `type` values "refactor" and "bugfix" above must match the valid frontmatter `type` values actually used in this project. Before implementing, scan existing spec files (e.g., `ls .specflow/specs/`) and note which `type` values appear. If "refactor" or "bugfix" are not present in the schema, map the heuristic to the closest equivalent types that are. For any task `type` not recognized by the heuristic, fall back to keyword-based detection on the task description rather than failing or treating the task as greenfield by default.
+
+If brownfield: set `delta: true` in frontmatter and generate Delta section in Step 5.
+If greenfield: proceed with existing Requirements format (no change).
+
 ## Step 3: Critical Questions (if needed)
 
 If the task has genuine ambiguity that affects approach, use AskUserQuestion.
@@ -139,17 +155,40 @@ If no specs exist in either directory, start with SPEC-001.
 
 Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 
-1. **Frontmatter:** id, type, status (draft), priority, complexity, created, source (if `<todo_context>` provided — set to the TODO ID, e.g., `source: TODO-006`)
+1. **Frontmatter:** id, type, status (draft), priority, complexity, created, source (if `<todo_context>` provided — set to the TODO ID, e.g., `source: TODO-006`), and optionally `delta: true` (only for brownfield tasks detected in Step 2.7)
 2. **Title:** Clear, action-oriented
 3. **Context:** Why this is needed
    - **If `<prior_discussion>` provided:** Add "Prior Discussion" subsection linking to PRE-XXX or DISC-XXX with key decisions
 4. **Task:** What to do
-5. **Requirements:** Files, interfaces, deletions
-6. **Acceptance Criteria:** Specific, measurable
-7. **Validation Checklist** (medium/large specs only): 3-5 concrete verification steps with expected outcomes. Each item = action + expected result. Examples: "Run `npm test` — all pass", "POST /api/users with invalid email — returns 422", "Open settings page — new toggle visible"
-8. **Constraints:** What NOT to do
-9. **Assumptions:** What you assumed (clearly marked)
-   - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
+5. **Delta section (brownfield tasks only):** When `delta: true`, add a `## Delta` section immediately after Context:
+
+   ```markdown
+   ## Delta
+
+   ### ADDED
+   - `path/to/new-file.md` — Description of what this new file provides
+
+   ### MODIFIED
+   - `path/to/existing-file.md` — Description of what changes and why
+     - Section X: Add Y
+     - Section Z: Replace W with V
+
+   ### REMOVED
+   - `path/to/obsolete-file.md` — Why this file is no longer needed
+   ```
+
+   Rules for Delta section:
+   - Each subsection (ADDED/MODIFIED/REMOVED) is optional; omit if empty
+   - At least one subsection must be present
+   - MODIFIED entries include bullet points describing specific changes within the file
+   - The existing `## Requirements` section remains and contains the detailed specifications for each change (the Delta section is a summary/index)
+
+6. **Requirements:** Files, interfaces, deletions
+7. **Acceptance Criteria:** Specific, measurable
+8. **Validation Checklist** (medium/large specs only): 3-5 concrete verification steps with expected outcomes. Each item = action + expected result. Examples: "Run `npm test` — all pass", "POST /api/users with invalid email — returns 422", "Open settings page — new toggle visible"
+9. **Constraints:** What NOT to do
+10. **Assumptions:** What you assumed (clearly marked)
+    - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
 
 ## Step 5.5: Generate Implementation Tasks (for medium and large specs)
 

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/done.md

@@ -175,7 +175,58 @@ mkdir -p .specflow/archive
 Update frontmatter:
 - status → "done"
 
-Add completion summary section to the spec:
+Check if the spec frontmatter contains `delta: true`.
+
+**If delta spec (`delta: true`):** Add the following completion summary section, which includes a "Changes Applied" subsection populated from the spec's `## Delta` section content:
+
+```markdown
+---
+
+## Completion
+
+**Completed:** {date} {time}
+**Total Commits:** {count from Execution Summary}
+**Review Cycles:** {count of Review v[N] entries}
+
+### Outcome
+
+{1-2 sentence summary of what was delivered}
+
+### Key Files
+
+- `{path}` — {what it does/why it matters}
+
+### Changes Applied
+
+**Added:**
+- `path/to/new-file.md` — {brief description}
+
+**Modified:**
+- `path/to/existing-file.md` — {brief description of changes}
+
+**Removed:**
+- `path/to/obsolete-file.md` — {brief description}
+
+{Omit any subsection (Added/Modified/Removed) if it has no entries.}
+
+{If a /sf:review was performed before /sf:done, include this subsection noting differences between what the Delta section specified and what was actually implemented. If no deviations were found or no review was performed, omit this subsection entirely:}
+
+### Deviations from Delta
+
+- `path/to/file.md` — {description of how actual implementation differed from Delta entry}
+
+### Patterns Established
+
+{List any new patterns, conventions, or architectural decisions introduced.
+If none: "None — followed existing patterns."}
+
+### Spec Deviations
+
+{Any deviations from the original spec during implementation (unrelated to delta changes).
+If none: "None — implemented as specified."}
+```
+
+**If NOT a delta spec:** Add the standard completion summary section (no "Changes Applied" or "Deviations from Delta" subsections):
 
 ```markdown
 ---

package/commands/sf/init.md

@@ -20,19 +20,88 @@ Initialize SpecFlow in the current project. Analyzes the codebase to understand
 
 <workflow>
 
+## Step 0: Parse Arguments
+
+Check whether the user invoked `/sf:init --force`. Look at the invocation string for the `--force` flag. Set a mental variable `FORCE_MODE` to true or false accordingly.
+
 ## Step 1: Check if Already Initialized
 
 ```bash
 [ -d .specflow ] && echo "EXISTS" || echo "NOT_EXISTS"
 ```
 
-**If EXISTS:**
+**If NOT_EXISTS:** proceed to Step 2.
+
+**If EXISTS:** scan for existing data files and directories.
+
+```bash
+# Check each file/directory individually
+[ -f .specflow/PROJECT.md ] && echo "HAS_PROJECT_MD" || true
+[ -f .specflow/STATE.md ] && echo "HAS_STATE_MD" || true
+[ -f .specflow/config.json ] && echo "HAS_CONFIG_JSON" || true
+[ -f .specflow/todos/TODO.md ] && echo "HAS_TODO_MD" || true
+[ "$(ls -A .specflow/specs 2>/dev/null)" ] && echo "HAS_SPECS" || true
+[ "$(ls -A .specflow/archive 2>/dev/null)" ] && echo "HAS_ARCHIVE" || true
+```
+
+Collect which items exist. If ANY of the above are found:
+
+**If FORCE_MODE is false (no `--force` flag):**
+
+Print this warning (substituting actual found items):
+
+```
+WARNING: SpecFlow data already exists in this project.
+
+The following files/directories would be overwritten:
+[list each found item, one per line, e.g.:]
+  - .specflow/PROJECT.md
+  - .specflow/STATE.md
+  - .specflow/config.json
+  - .specflow/todos/TODO.md
+  - .specflow/specs/ (contains files)
+  - .specflow/archive/ (contains files)
+
+Re-running init will overwrite these files. Use `/sf:init --force` to reset.
+
+Tip: Run `/sf:status` to see current state.
+```
+
+Exit. Do NOT proceed.
+
+**If FORCE_MODE is true (`--force` was passed):**
+
+Print a warning listing all files that will be overwritten, then create a timestamped backup.
+
+```
+WARNING: --force flag detected. Existing SpecFlow data will be backed up and overwritten.
+
+The following files/directories will be backed up:
+[list each found item]
+```
+
+Create the backup directory with a timestamp:
+
+```bash
+BACKUP_DIR=".specflow/backup-$(date +%Y-%m-%d-%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+echo "Backup directory: $BACKUP_DIR"
 ```
-SpecFlow already initialized in this project.
 
-Use `/sf:status` to see current state.
+Copy all existing `.specflow/` content (except the backup directory itself) into the backup:
+
+```bash
+# Copy all existing .specflow content into backup
+# Use find to copy files while preserving structure, excluding backup dirs themselves
+find .specflow -maxdepth 1 -not -name "backup-*" -not -name ".specflow" | while read item; do
+  cp -r "$item" "$BACKUP_DIR/"
+done
+echo "Backup complete."
 ```
-Exit.
+
+Then proceed to Step 2.
+
+**If EXISTS but no data files found** (empty directory): proceed to Step 2.
 
 ## Step 2: Detect Tech Stack
 
@@ -162,6 +231,14 @@ mkdir -p .specflow/specs .specflow/audits .specflow/archive .specflow/todos .spe
 
 ## Step 6: Generate PROJECT.md
 
+**Defense-in-depth guard:** Before writing, check if `.specflow/PROJECT.md` already exists AND `--force` was NOT used. If both conditions are true, skip writing this file and note it was skipped.
+
+```bash
+[ -f .specflow/PROJECT.md ] && echo "PROJECT_MD_EXISTS" || echo "PROJECT_MD_MISSING"
+```
+
+If `PROJECT_MD_MISSING` OR `FORCE_MODE` is true: write the file.
+
 Based on detected stack and patterns, create `.specflow/PROJECT.md`:
 
 ```markdown
@@ -201,6 +278,14 @@ Based on detected stack and patterns, create `.specflow/PROJECT.md`:
 
 ## Step 7: Generate STATE.md
 
+**Defense-in-depth guard:** Before writing, check if `.specflow/STATE.md` already exists AND `--force` was NOT used. If both conditions are true, skip writing this file and note it was skipped.
+
+```bash
+[ -f .specflow/STATE.md ] && echo "STATE_MD_EXISTS" || echo "STATE_MD_MISSING"
+```
+
+If `STATE_MD_MISSING` OR `FORCE_MODE` is true: write the file.
+
 Create `.specflow/STATE.md`:
 
 ```markdown
@@ -237,6 +322,14 @@ Create `.specflow/STATE.md`:
 
 ## Step 8: Generate config.json
 
+**Defense-in-depth guard:** Before writing, check if `.specflow/config.json` already exists AND `--force` was NOT used. If both conditions are true, skip writing this file and note it was skipped.
+
+```bash
+[ -f .specflow/config.json ] && echo "CONFIG_JSON_EXISTS" || echo "CONFIG_JSON_MISSING"
+```
+
+If `CONFIG_JSON_MISSING` OR `FORCE_MODE` is true: write the file.
+
 Create `.specflow/config.json`:
 
 ```json

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.15.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"