specflow-cc 1.19.0 → 1.20.1

package/commands/sf/plan.md

@@ -171,6 +171,14 @@ rm .specflow/todos/TODO-{XXX}.md
 
 **Important:** Only remove after confirmed spec creation. No "Last updated" lines to update.
 
+3. **Refresh INDEX.md** via the shared regen helper so the cache no longer references the removed file:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
+
+This is mandatory — skipping it leaves INDEX.md listing a TODO that no longer exists on disk, which trips the `/sf:status` freshness check and breaks downstream consumers.
+
 ## Step 8: Display Result
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
@@ -232,7 +240,12 @@ Use `/sf:new "{todo description}"` logic:
 
 ### Remove Todo
 
-Delete the file `.specflow/todos/TODO-{XXX}.md`.
+Delete the file `.specflow/todos/TODO-{XXX}.md`, then refresh INDEX.md:
+
+```bash
+rm .specflow/todos/TODO-{XXX}.md
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
 
 </fallback>
 
@@ -246,5 +259,6 @@ Delete the file `.specflow/todos/TODO-{XXX}.md`.
 - [ ] Priority inherited from todo
 - [ ] TODO-XXX.md file deleted (not edited — whole file removed)
 - [ ] Deletion verified (file no longer exists)
+- [ ] INDEX.md refreshed via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex`
 - [ ] Clear result with next step
 </success_criteria>

package/commands/sf/priority.md

@@ -123,7 +123,12 @@ If input matches pattern `{ID}={priority}`:
 
 1. Validate priority (high | medium | low)
 2. **If ID is a spec (SPEC-XXX):** Update `priority:` in frontmatter of `.specflow/specs/SPEC-XXX.md` using the Edit tool
-3. **If ID is a TODO (TODO-XXX):** Read `.specflow/todos/TODO-XXX.md`, update `priority:` line in frontmatter using the Edit tool
+3. **If ID is a TODO (TODO-XXX):**
+   a. Read `.specflow/todos/TODO-XXX.md`, update `priority:` line in frontmatter using the Edit tool
+   b. Refresh INDEX.md so the cached priority column matches:
+      ```bash
+      node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+      ```
 4. Display confirmation
 5. Return to Step 3
 
@@ -203,6 +208,7 @@ Use `/sf:next` to work on highest priority task.
 - [ ] Reorder command works
 - [ ] Technical order suggestion available
 - [ ] TODO priority updated in individual file frontmatter (not TODO.md)
+- [ ] INDEX.md refreshed via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex` after any TODO priority change
 - [ ] STATE.md Queue updated after spec reorder
 - [ ] Clear feedback on changes
 </success_criteria>

package/commands/sf/review.md

@@ -1,6 +1,7 @@
 ---
 name: sf:review
 description: Review the implementation against specification
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -36,17 +37,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to review.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to review.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to review?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -319,8 +330,12 @@ Append Review History to spec.
 
 ### Update STATE.md
 
-- If APPROVED: Status → "done", Next Step → "/sf:done"
-- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf:fix"
+```bash
+# If APPROVED:
+node bin/sf-tools.cjs state add-active SPEC-XXX done /sf:done
+# If CHANGES_REQUESTED:
+node bin/sf-tools.cjs state add-active SPEC-XXX review /sf:fix
+```
 
 </fallback>
 

package/commands/sf/revise.md

@@ -1,6 +1,7 @@
 ---
 name: sf:revise
 description: Revise specification based on audit feedback
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -37,17 +38,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided; strip non-SPEC-ID args first).
 
-**If no active specification:**
-```
-No active specification to revise.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to revise.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to revise?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -500,16 +511,21 @@ After recording the Response, if any items were marked "Deferred":
    Origin: {SPEC-XXX} Response v{N}. {reason for deferral}
    ```
 3. Append "**TODOs Created:**" subsection to the Response in Audit History listing created TODO IDs
+4. After the loop completes (at least one TODO created), refresh INDEX.md:
+   ```bash
+   node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+   ```
 
-**This step is mandatory.** Every "Deferred" decision MUST produce a corresponding TODO-XXX.md file.
+**This step is mandatory.** Every "Deferred" decision MUST produce a corresponding TODO-XXX.md file AND the reindex helper MUST run if any TODO was created — otherwise INDEX.md silently drifts out of sync with `todos/`.
 
 ### Update Status
 
 In spec frontmatter: `status: auditing`
 
 In STATE.md:
-- Status → "auditing"
-- Next Step → "/sf:audit"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX auditing /sf:audit
+```
 
 </fallback>
 
@@ -520,6 +536,7 @@ In STATE.md:
 - [ ] Changes applied correctly
 - [ ] Response recorded in Audit History
 - [ ] Deferred items (if any) created as individual TODO-XXX.md files in `.specflow/todos/`
+- [ ] INDEX.md refreshed via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex` (if any TODO was created)
 - [ ] Spec frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes shown

package/commands/sf/run.md

@@ -1,6 +1,7 @@
 ---
 name: sf:run
 description: Execute the specification (implement the code)
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -39,17 +40,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to execute.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to execute.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to run?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -182,9 +193,9 @@ Use model for `spec-executor` or `spec-executor-orchestrator` from selected prof
 
 ## Step 7: Update Status
 
-Update STATE.md:
-- Status → "running"
-- Next Step → "(in progress)"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX running "(in progress)"
+```
 
 Update spec frontmatter:
 - status → "running"

package/commands/sf/show.md

@@ -1,6 +1,7 @@
 ---
 name: sf:show
 description: Display full specification details
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve when no arg
 allowed-tools:
   - Read
   - Bash
@@ -41,16 +42,22 @@ Exit.
 Use provided ID (e.g., SPEC-003).
 
 **If no argument:**
-Read `.specflow/STATE.md` and get Active Specification.
-
-**If no active specification and no argument:**
-```
-No specification specified and no active specification.
-
-Use `/sf:show SPEC-XXX` to view a specific spec
-or `/sf:list` to see all specifications.
-```
-Exit.
+Call `node bin/sf-tools.cjs state resolve` to get active spec.
+
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → use SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No specification specified and no active specification.
+
+  Use `/sf:show SPEC-XXX` to view a specific spec
+  or `/sf:list` to see all specifications.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to show?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Find Specification File
 

package/commands/sf/split.md

@@ -1,6 +1,7 @@
 ---
 name: sf:split
 description: Split a large specification into smaller sub-specifications
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve when no arg
 allowed-tools:
   - Read
   - Write
@@ -57,18 +58,22 @@ Use `/sf:list` to see available specifications.
 Exit.
 
 **If no ID provided:**
-Read active specification from `.specflow/STATE.md`:
-- Parse "Active Specification" field
-- Use that ID
-
-**If no active specification:**
-```
-No specification specified and no active specification.
-
-Usage: `/sf:split SPEC-001`
-   or: Set active spec with `/sf:show SPEC-001`
-```
-Exit.
+Call `node bin/sf-tools.cjs state resolve` to get active spec.
+
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → use SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No specification specified and no active specification.
+
+  Usage: `/sf:split SPEC-001`
+     or: Set active spec with `/sf:show SPEC-001`
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to split?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Check Complexity
 
@@ -356,9 +361,13 @@ Add split reference to archived parent.
 
 ### Update STATE.md
 
-- Remove parent from Queue
-- Add children to Queue
-- Set first child as Active Specification
+- Remove parent from Queue (using Read+Write)
+- Add children to Queue (using Read+Write)
+- Register first child in Active Specifications table:
+  ```bash
+  node bin/sf-tools.cjs state remove-active SPEC-PARENT
+  node bin/sf-tools.cjs state add-active SPEC-XXXa draft /sf:audit
+  ```
 
 </fallback>
 

package/commands/sf/status.md

@@ -1,6 +1,7 @@
 ---
 name: sf:status
 description: Show current SpecFlow state and recommended next step
+# SPEC-011: Uses state list-active and state resolve for multi-spec awareness
 allowed-tools:
   - Read
   - Bash
@@ -34,13 +35,22 @@ Exit.
 
 ## Step 2: Load State
 
-Read `.specflow/STATE.md` and extract:
-- Active Specification
-- Status
-- Next Step
-- Queue
-- Recent Decisions
-- Warnings
+Read `.specflow/STATE.md` and extract Queue, Recent Decisions, Warnings.
+
+Get active specs:
+```bash
+node bin/sf-tools.cjs state list-active
+```
+
+For single-spec display, also call:
+```bash
+node bin/sf-tools.cjs state resolve
+```
+
+Parse the resolve response:
+- `{"action":"use","id":"SPEC-XXX"}` → show single active spec
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → show idle state
+- `{"action":"ask","options":[...]}` → show all active specs in table format
 
 ## Step 3: Load Project Info
 
@@ -77,10 +87,10 @@ for f in .specflow/specs/SPEC-*.md; do
 done
 ```
 
-**If STATE.md shows "Active Specification: None" but specs exist in specs/:**
+**If the Active Specifications table is empty (no rows) but specs exist in specs/:**
 Add warning:
 ```
-STATE MISMATCH: Found {N} spec(s) in specs/ but STATE.md shows no active spec.
+STATE MISMATCH: Found {N} spec(s) in specs/ but the Active Specifications table is empty.
 Likely cause: STATE.md was not updated after spec creation.
 Run: Read the spec file and manually update STATE.md, or delete orphan spec if duplicate.
 ```
@@ -93,6 +103,30 @@ Likely cause: Spec numbering bug - archive was not checked when generating ID.
 Fix: Rename the spec in specs/ to next available ID.
 ```
 
+### TODO Index Freshness
+
+Compare the set of TODO files on disk to the IDs listed in `.specflow/todos/INDEX.md`:
+
+```bash
+node bin/sf-tools.cjs todo check-stale
+```
+
+Parse the JSON response. If `stale: true`, add a warning to the Warnings section:
+
+```
+INDEX.md stale — run /sf:todos (or `node bin/sf-tools.cjs todo reindex`).
+{If missing_from_index is non-empty:}
+  Missing from INDEX.md (TODO file exists on disk but not listed):
+    {comma-separated list}
+{If extra_in_index is non-empty:}
+  Stale entries in INDEX.md (listed but TODO file no longer exists):
+    {comma-separated list}
+{If !index_exists and todo_count > 0:}
+  INDEX.md does not exist yet but {todo_count} TODO file(s) are on disk.
+```
+
+This is a safety net — every command that mutates `todos/` is supposed to call the regen helper itself, but external edits, manual `rm`, or a missed call will surface here. Do NOT auto-fix from `/sf:status`; only report. The user runs `/sf:todos` (or the helper directly) to clear the warning.
+
 ## Step 5: Determine Next Action
 
 Based on current status:
@@ -198,6 +232,7 @@ Based on state, provide additional guidance:
 - [ ] STATE.md loaded
 - [ ] PROJECT.md info extracted
 - [ ] Statistics calculated
+- [ ] TODO index freshness checked via `node bin/sf-tools.cjs todo check-stale` (warning surfaced if stale)
 - [ ] Current position displayed
 - [ ] Queue shown
 - [ ] Recommended next step clear

package/commands/sf/todos.md

@@ -8,7 +8,7 @@ allowed-tools:
 ---
 
 <purpose>
-Display all to-do items from the backlog, sorted by priority. Reads individual TODO-XXX.md files (or legacy TODO.md for backward compatibility). Writes an auto-generated INDEX.md after display. Provides quick access to convert items to specifications.
+Display all to-do items from the backlog, sorted by priority. Reads individual TODO-XXX.md files (or legacy TODO.md for backward compatibility). Refreshes the INDEX.md cache via the shared regen helper after display. Provides quick access to convert items to specifications.
 </purpose>
 
 <context>
@@ -109,27 +109,15 @@ From the list:
 
 ## Step 6: Regenerate INDEX.md
 
-After displaying the list, write `.specflow/todos/INDEX.md` using the Write tool.
+After displaying the list, regenerate `.specflow/todos/INDEX.md` by invoking the shared helper:
 
-Use the format from `templates/todo-index.md`:
-
-```markdown
-# To-Do Index
-
-> Auto-generated from individual TODO files. Do not edit manually.
-> Regenerate with `/sf:todos`.
-
-| # | ID | Title | Priority | Status | Created |
-|---|-----|-------|----------|--------|---------|
-{rows from sorted list — one row per TODO}
-
-**Total:** {N} items ({high} high, {medium} medium, {low} low, {unset} unset)
-
----
-*Last regenerated: {YYYY-MM-DD HH:MM}*
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
 ```
 
-**Important:** INDEX.md is a display cache only. Never edit it manually — it is regenerated here each time `/sf:todos` runs.
+The helper scans `.specflow/todos/TODO-*.md`, sorts the rows the same way Step 2 does, and writes INDEX.md in the format defined by `templates/todo-index.md`. It is the single source of truth for INDEX layout — do NOT write INDEX.md manually here.
+
+**Important:** INDEX.md is a cache. Other commands that mutate `todos/` (`/sf:todo`, `/sf:plan`, `/sf:done`, `/sf:triage`, `/sf:revise`, `/sf:priority`, `/sf:migrate-todos`, and the `sf-spec-reviser` agent) must call the same helper after their mutation so the cache stays consistent between `/sf:todos` invocations. `/sf:status` runs `todo check-stale` and warns if drift is detected.
 
 </workflow>
 
@@ -142,6 +130,6 @@ Use the format from `templates/todo-index.md`:
 - [ ] `--all` flag shows eliminated items visually distinct
 - [ ] Statistics shown (total, by priority)
 - [ ] Clear actions provided
-- [ ] INDEX.md written to `.specflow/todos/INDEX.md` after display
-- [ ] INDEX.md contains "Do not edit manually" notice
+- [ ] INDEX.md regenerated via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex` after display
+- [ ] INDEX.md header describes it as a cache refreshed by `/sf:todos` or the regen helper
 </success_criteria>

package/commands/sf/triage.md

@@ -188,6 +188,16 @@ created: {YYYY-MM-DD}
 
 Do NOT append to TODO.md. Do NOT update any "Last updated" lines. Each finding gets its own separate TODO-XXX.md file.
 
+### 6.3 Refresh INDEX.md
+
+After all selected TODO files have been written, regenerate the cache once:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
+
+This is mandatory whenever the triage loop creates at least one TODO. Skipping it leaves INDEX.md missing the just-created entries until the next `/sf:todos` run.
+
 ## Step 7: Display Results
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
@@ -255,5 +265,6 @@ Run /sf:triage again to review findings.
 - [ ] Each file has valid YAML frontmatter (id, title, priority, status, created)
 - [ ] Priority preserved from scan
 - [ ] Source reference included in notes (scan date, files, problem)
+- [ ] INDEX.md refreshed via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex` (skip only if zero TODOs created)
 - [ ] Clear summary of created TODOs
 </success_criteria>

package/commands/sf/verify.md

@@ -1,6 +1,7 @@
 ---
 name: sf:verify
 description: Interactive human verification of acceptance criteria
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -33,17 +34,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
-
-Read `.specflow/STATE.md` and extract Active Specification.
-
-**If no active specification:**
-```
-No active specification to verify.
-
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+## Step 2: Resolve Active Specification
+
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to verify.
+
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to verify?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 

package/package.json

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

package/templates/state.md

@@ -2,11 +2,13 @@
 
 <!-- This file is kept compact (<100 lines). Old decisions are automatically rotated to DECISIONS_ARCHIVE.md. -->
 
-## Current Position
+## Active Specifications
 
-- **Active Specification:** [none | SPEC-XXX]
-- **Status:** [idle | drafting | auditing | revision_requested | external_review | running | reviewing]
-- **Next Step:** [/sf:new | /sf:audit | /sf:revise | /sf:run | /sf:review | /sf:done]
+<!-- Multi-spec registry. Zero rows = no active specs. One row = single-spec ergonomics (no prompt). -->
+<!-- Multiple rows = resolver emits AskUserQuestion picker when no SPEC-ID argument provided. -->
+
+| SPEC-ID | Status | Next Step |
+|---------|--------|-----------|
 
 ## Queue
 

package/templates/todo-index.md

@@ -1,7 +1,9 @@
 # To-Do Index
 
-> Auto-generated from individual TODO files. Do not edit manually.
-> Regenerate with `/sf:todos`.
+> Cache of individual TODO files. Refreshed when `/sf:todos` runs OR when an
+> INDEX-mutating command explicitly invokes the regen helper
+> (`node bin/sf-tools.cjs todo reindex`). Do not edit manually — changes will
+> be overwritten on the next regen.
 
 | # | ID | Title | Priority | Status | Created |
 |---|-----|-------|----------|--------|---------|