specflow-cc 1.20.0 → 1.20.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.20.1] - 2026-05-14
+
+### Fixed
+
+- **INDEX.md staleness across all TODO-mutating paths** — `1.19.0` wired the `todo reindex` helper into `/sf:todo` and `/sf:done`, but every other command that mutates `.specflow/todos/` (`/sf:plan` `rm`, `/sf:triage` create, `/sf:revise` deferred-TODO creation, `/sf:priority` priority edits, `/sf:migrate-todos`, and the `sf-spec-reviser` agent) still left INDEX.md silently out of sync. All of these now invoke `node bin/sf-tools.cjs todo reindex` after the mutation. `/sf:todos` no longer writes INDEX.md inline — it delegates to the same helper, making the reindex routine the single source of truth for INDEX layout.
+
+### Added
+
+- **`todo check-stale` CLI subcommand** in `bin/sf-tools.cjs` — compares the set of `TODO-*.md` files on disk to the set of IDs in `INDEX.md` and returns `{stale, index_exists, todo_count, index_count, missing_from_index, extra_in_index}`. Used by `/sf:status` as a safety-net freshness check: if any drift is detected (external edits, manual `rm`, a missed helper call), `/sf:status` surfaces an "INDEX.md stale" warning naming the specific divergences. No auto-fix — the user re-runs `/sf:todos` or the helper.
+- 9 new tests in `tests/todo-index.test.cjs` covering reindex idempotency, header content, drop-after-delete, and all `check-stale` scenarios (fresh, extra-in-index, missing-from-index, no-INDEX-with-files, empty-both, raw output).
+
+### Changed
+
+- **INDEX.md header text** rewritten to describe actual behaviour. Old wording ("Auto-generated from individual TODO files. Do not edit manually. Regenerate with `/sf:todos`.") implied a self-maintaining file. New wording: "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." Applied in both `bin/lib/todo.cjs` (the source of truth) and `templates/todo-index.md`.
+
 ## [1.20.0] - 2026-05-02
 
 ### Added

package/agents/spec-reviser.md

@@ -176,7 +176,13 @@ For each deferred item:
 - 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.
+4. After the loop completes (at least one TODO created), refresh the INDEX.md cache so it reflects the newly-created files:
+
+```bash
+node bin/sf-tools.cjs todo reindex
+```
+
+**Important:** Both substeps are mandatory. Every deferred item MUST produce a TODO, and if any TODO is created the reindex helper MUST run before reporting completion. Skipping the reindex leaves `.specflow/todos/INDEX.md` missing the just-created entries, which the `/sf:status` freshness check will then flag. If TODO creation fails, report the failure — do not silently skip.
 
 ## Step 6: Update Frontmatter
 
@@ -245,6 +251,7 @@ Tip: `/clear` recommended — auditor needs fresh context
 - [ ] Revision Response recorded in Audit History
 - [ ] Deferred items (if any) created as individual `.specflow/todos/TODO-XXX.md` files
 - [ ] TODOs Created subsection appended to Response (if deferred items exist)
+- [ ] INDEX.md refreshed via `node bin/sf-tools.cjs todo reindex` (if any TODO was created)
 - [ ] Frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes provided

package/bin/lib/todo.cjs

@@ -295,8 +295,10 @@ function cmdTodoReindex(cwd, raw) {
   const lines = [
     '# 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 |',
     '|---|-----|-------|----------|--------|---------|',
@@ -324,9 +326,79 @@ function cmdTodoReindex(cwd, raw) {
   output({ reindexed: todos.length, path: indexPath }, raw, `Reindexed ${todos.length} TODOs → INDEX.md`);
 }
 
+/**
+ * Check whether INDEX.md is stale relative to TODO-*.md files.
+ *
+ * Stale = the set of TODO-XXX IDs on disk diverges from the set of TODO-XXX IDs
+ * listed in INDEX.md (file deleted but still in INDEX, or file present but missing).
+ *
+ * NOTE: Eliminated TODOs (`status: eliminated`) still appear in `/sf:todos --all`
+ * regenerated INDEX.md output, so they are NOT filtered here — both sides see them.
+ *
+ * Output JSON: { stale, missing_from_index, extra_in_index, index_exists }
+ *  - missing_from_index: file exists on disk but not in INDEX.md
+ *  - extra_in_index: ID listed in INDEX.md but no file on disk
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output mode
+ */
+function cmdTodoCheckStale(cwd, raw) {
+  const todosDir = path.join(cwd, '.specflow', 'todos');
+  const indexPath = path.join(todosDir, 'INDEX.md');
+
+  // Collect IDs from disk
+  const diskIds = new Set();
+  try {
+    for (const f of fs.readdirSync(todosDir)) {
+      const m = f.match(/^(TODO-\d+)\.md$/);
+      if (m) diskIds.add(m[1]);
+    }
+  } catch (e) {
+    // todos dir missing — treat as empty
+  }
+
+  // Collect IDs referenced in INDEX.md (parse only the table rows)
+  const indexIds = new Set();
+  const indexContent = safeReadFile(indexPath);
+  const indexExists = indexContent !== null;
+
+  if (indexContent) {
+    // Match TODO-XXX in pipe-table cells: "| N | TODO-001 | ..."
+    const regex = /\|\s*\d+\s*\|\s*(TODO-\d+)\s*\|/g;
+    let m;
+    while ((m = regex.exec(indexContent)) !== null) {
+      indexIds.add(m[1]);
+    }
+  }
+
+  const missingFromIndex = [...diskIds].filter(id => !indexIds.has(id)).sort();
+  const extraInIndex = [...indexIds].filter(id => !diskIds.has(id)).sort();
+
+  // If INDEX.md does not exist but there are TODO files, INDEX is stale.
+  // If INDEX.md does not exist and no TODO files, not stale (nothing to track).
+  const stale =
+    missingFromIndex.length > 0 ||
+    extraInIndex.length > 0 ||
+    (!indexExists && diskIds.size > 0);
+
+  output(
+    {
+      stale,
+      index_exists: indexExists,
+      todo_count: diskIds.size,
+      index_count: indexIds.size,
+      missing_from_index: missingFromIndex,
+      extra_in_index: extraInIndex,
+    },
+    raw,
+    stale ? 'STALE' : 'FRESH'
+  );
+}
+
 module.exports = {
   cmdTodoLoad,
   cmdTodoList,
   cmdTodoNextId,
   cmdTodoReindex,
+  cmdTodoCheckStale,
 };

package/bin/sf-tools.cjs

@@ -13,6 +13,7 @@
  *   todo list [--all]                     List all TODOs sorted by priority
  *   todo next-id                          Next available TODO-XXX number
  *   todo reindex                          Regenerate INDEX.md from TODO files
+ *   todo check-stale                      Report drift between TODO-*.md and INDEX.md
  *   queue next                            First actionable spec from queue
  *   state get                             Current active spec, status, next step (legacy shim)
  *   state set-active <id> <status> [next] Update active spec in STATE.md (legacy shim)
@@ -40,7 +41,7 @@ const {
   cmdQueueNext,
 } = require('./lib/state.cjs');
 const { cmdSpecLoad, cmdSpecList, cmdSpecNextId } = require('./lib/spec.cjs');
-const { cmdTodoLoad, cmdTodoList, cmdTodoNextId, cmdTodoReindex } = require('./lib/todo.cjs');
+const { cmdTodoLoad, cmdTodoList, cmdTodoNextId, cmdTodoReindex, cmdTodoCheckStale } = require('./lib/todo.cjs');
 const { cmdResolveModel } = require('./lib/config.cjs');
 const { cmdVerifyStructure } = require('./lib/verify.cjs');
 
@@ -75,6 +76,7 @@ const COMMANDS = {
   'todo list':       () => cmdTodoList(cwd, raw, { showAll: flags.all ?? false }),
   'todo next-id':    () => cmdTodoNextId(cwd, raw),
   'todo reindex':    () => cmdTodoReindex(cwd, raw),
+  'todo check-stale': () => cmdTodoCheckStale(cwd, raw),
   'queue next':      () => cmdQueueNext(cwd, raw),
 
   // Legacy shims (backwards compatible)
@@ -136,6 +138,7 @@ Commands:
   todo list [--all]                       List TODOs sorted by priority (--all includes eliminated)
   todo next-id                            Next available TODO-XXX number
   todo reindex                            Regenerate INDEX.md from TODO files
+  todo check-stale                        Report drift between TODO-*.md and INDEX.md
   queue next                              First actionable spec from queue table
   state get                               Current active spec, status, next step (legacy shim)
   state set-active <id> <status> [next]   Update active spec, status, next step (legacy shim)

package/commands/sf/migrate-todos.md

@@ -13,7 +13,7 @@ Migrate an existing monolithic `.specflow/todos/TODO.md` to the new per-file for
 This is a one-time migration command. After migration:
 - `TODO.md` is renamed to `TODO.md.bak` (NOT deleted — safety net)
 - Each TODO becomes its own `TODO-XXX.md` file
-- `INDEX.md` is generated from the new files
+- `INDEX.md` is regenerated from the new files via the shared `todo reindex` helper
 - All other commands will use the new per-file format automatically
 
 Use `--dry-run` to preview the migration without writing any files.
@@ -173,24 +173,14 @@ created: {YYYY-MM-DD}
 
 ## Step 7: Generate INDEX.md
 
-Write `.specflow/todos/INDEX.md` with all migrated TODOs, sorted by priority then date:
+Invoke the shared regen helper to build `.specflow/todos/INDEX.md` from the migrated files:
 
-```markdown
-# To-Do Index
-
-> Auto-generated from individual TODO files. Do not edit manually.
-> Regenerate with `/sf:todos`.
-
-| # | ID | Title | Priority | Status | Created |
-|---|-----|-------|----------|--------|---------|
-{one row per TODO, sorted by priority then created date}
-
-**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
 ```
 
+Do NOT write INDEX.md inline — the helper is the single source of truth for its layout (see `templates/todo-index.md`).
+
 ## Step 8: Rename Legacy TODO.md
 
 ```bash
@@ -245,7 +235,7 @@ Migrated {N} TODOs from TODO.md to per-file format.
 - [ ] Individual TODO-XXX.md files created for each block
 - [ ] Each file has valid YAML frontmatter (id, title, priority, status, created)
 - [ ] Title derived from description (first sentence, ~80 chars)
-- [ ] INDEX.md generated from migrated files
+- [ ] INDEX.md regenerated via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex`
 - [ ] TODO.md renamed to TODO.md.bak (NOT deleted)
 - [ ] Clear migration summary shown
 - [ ] Cleanup instructions provided

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

@@ -511,8 +511,12 @@ 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
 
@@ -532,6 +536,7 @@ node bin/sf-tools.cjs state add-active SPEC-XXX auditing /sf:audit
 - [ ] 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/status.md

@@ -103,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:
@@ -208,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.20.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/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 |
 |---|-----|-------|----------|--------|---------|