specflow-cc 1.22.1 → 1.23.0

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.23.0] - 2026-05-27
+
+### Added
+
+- **Strict TODO frontmatter validation in `cmdTodoReindex` (SPEC-015)** — the indexing chokepoint at [`bin/lib/todo.cjs`](bin/lib/todo.cjs) now enforces a `REQUIRED_TODO_FIELDS = ['id', 'title', 'created']` invariant per TODO file. Files missing any required field (or lacking a frontmatter block entirely) are no longer silently defaulted into the index — they are surfaced as `MALFORMED: <reason>` sentinel rows in `INDEX.md`, sorted after well-formed entries by `fileId` ascending. Each malformed file emits a per-file warning to stderr, the `**Total:**` summary line gains a `… X malformed` component, and `node bin/sf-tools.cjs todo reindex` exits non-zero (`process.exitCode = 1` after `output()` flushes) so callers can gate on it. Well-formed runs remain byte-identical to the legacy format. Validation lives at the call site, not in shared `parseFrontmatter()` — `cmdTodoLoad` / `cmdTodoList` keep their tolerance. 6 new tests in `tests/todo-index.test.cjs` cover the four malformed shapes, malformed-YAML, and a regression guard for legacy parity.
+- **`todo check-stale` exit gate (TODO-029)** — `cmdTodoCheckStale` in [`bin/lib/todo.cjs`](bin/lib/todo.cjs) now sets `process.exitCode = 1` when `INDEX.md` drifts from disk (ghost rows or missing entries). Previously it only reported drift via JSON/text output and always exited 0, so callers could not gate on it.
+
+### Fixed
+
+- **Ghost-row drift after `/sf:done` and `/sf:plan` finalize (TODO-029)** — the LLM-orchestrated `rm .specflow/todos/{source}.md` + `node bin/sf-tools.cjs todo reindex` sequence in [`commands/sf/done.md`](commands/sf/done.md) Step 7.5 and [`commands/sf/plan.md`](commands/sf/plan.md) Step 7 (plus its inline fallback) had no enforced atomicity — any inversion, interruption, or skipped step left `INDEX.md` with a row pointing at a deleted file, and the only enforcement was `/sf:status` running `check-stale` reactively, days later. Both command files now invoke `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo check-stale` immediately after the `rm` + `reindex` block and treat non-zero exit as a finalization failure (re-run reindex once; if still stale, halt and surface `extra_in_index` / `missing_from_index` to the user). Surfaced in a downstream project (`~/Projects/topgun`) where SPEC-275 finalization left TODO-406 as a ghost in `INDEX.md`, then `/sf:plan TODO-406` operated on it.
+
+## [1.22.2] - 2026-05-22
+
+### Fixed
+
+- **Installed `/sf:*` commands broken on user projects** — every `/sf:*` command shipped in `commands/sf/*.md` is now safe to run from a project directory with no local `bin/`. Two bugs fixed:
+  1. **Bare `bin/sf-tools.cjs` paths in 15 command files** (`audit.md`, `autopilot.md`, `discuss.md`, `done.md`, `fix.md`, `health.md`, `help.md`, `pause.md`, `review.md`, `revise.md`, `run.md`, `show.md`, `split.md`, `status.md`, `verify.md`) were rewritten to `~/.claude/specflow-cc/bin/sf-tools.cjs`. The installer rewrites this literal prefix to the actual install location, so every invocation now resolves correctly. Previously these lines errored with `Cannot find module '/path/to/project/bin/sf-tools.cjs'`.
+  2. **Unsafe `state resolve $ARGUMENTS` in 8 commands** (`audit.md`, `autopilot.md`, `done.md`, `fix.md`, `pause.md`, `review.md`, `run.md`, `verify.md`) was replaced with a SPEC-ID parsing guard: `$ARGUMENTS` is split into `FIRST_TOKEN` (matched against `^SPEC-\d{3,}$`) and a per-command scope variable (`FIX_SCOPE`, `DONE_SCOPE`, `AUDIT_SCOPE`, …). Previously `/sf:fix all`, `/sf:done --apply=minor`, etc. produced spurious `SPEC_NOT_ACTIVE` errors because the scope/mode flag was passed to the resolver as if it were a SPEC-ID.
+
 ## [1.22.1] - 2026-05-20
 
 ### Fixed

package/bin/lib/todo.cjs

@@ -15,6 +15,13 @@ const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, parseFrontmatter } = require('./core.cjs');
 
+/**
+ * Required YAML frontmatter fields for each TODO file.
+ * When any of these is absent or blank, the reindex records the file as MALFORMED
+ * rather than silently defaulting to empty values (which would hide drift).
+ */
+const REQUIRED_TODO_FIELDS = ['id', 'title', 'created'];
+
 /**
  * Priority sort order (lower number = higher priority in sort).
  */
@@ -284,23 +291,55 @@ function cmdTodoReindex(cwd, raw) {
     const parsed = parseFrontmatter(content);
     const fm = parsed.frontmatter;
 
+    // Determine which required fields are absent or blank.
+    const missing = REQUIRED_TODO_FIELDS.filter(k => !fm[k] || String(fm[k]).trim() === '');
+
+    if (missing.length > 0) {
+      // Distinguish "no frontmatter block at all" (fm has no keys) from "some
+      // fields present but specific ones missing".
+      const hasAnyKey = Object.keys(fm).length > 0;
+      const reason = hasAnyKey
+        ? 'missing fields: ' + missing.join(', ')
+        : 'no frontmatter block';
+
+      process.stderr.write('warn: ' + file + ' — ' + reason + '\n');
+
+      todos.push({
+        malformed: true,
+        fileId: file.replace('.md', ''),
+        reason,
+      });
+      continue;
+    }
+
     // Strip surrounding quotes from title (YAML may preserve them)
-    let title = fm.title || '';
+    let title = String(fm.title);
     if ((title.startsWith('"') && title.endsWith('"')) || (title.startsWith("'") && title.endsWith("'"))) {
       title = title.slice(1, -1);
     }
 
     todos.push({
-      id: fm.id || file.replace('.md', ''),
+      id: fm.id,
       title,
       priority: fm.priority || '—',
       status: fm.status || 'open',
-      created: fm.created || '',
+      created: fm.created,
     });
   }
 
-  // Sort by priority (high > medium > low > unset), then by created date
+  // Sort: well-formed records by priority then created date; malformed records
+  // always come after all well-formed ones, ordered by fileId ascending.
   todos.sort((a, b) => {
+    const am = a.malformed ? 1 : 0;
+    const bm = b.malformed ? 1 : 0;
+    if (am !== bm) return am - bm; // well-formed before malformed
+    if (a.malformed && b.malformed) {
+      // Both malformed: sort by fileId ascending
+      if (a.fileId < b.fileId) return -1;
+      if (a.fileId > b.fileId) return 1;
+      return 0;
+    }
+    // Both well-formed: priority then date
     const pa = priorityKey(a.priority);
     const pb = priorityKey(b.priority);
     if (pa !== pb) return pa - pb;
@@ -309,13 +348,21 @@ function cmdTodoReindex(cwd, raw) {
     return 0;
   });
 
-  // Count by priority
+  // Count by priority — malformed records are excluded from priority breakdown.
   const counts = { high: 0, medium: 0, low: 0, unset: 0 };
+  let malformedCount = 0;
   for (const t of todos) {
-    if (t.priority === 'high') counts.high++;
-    else if (t.priority === 'medium') counts.medium++;
-    else if (t.priority === 'low') counts.low++;
-    else counts.unset++;
+    if (t.malformed) {
+      malformedCount++;
+    } else if (t.priority === 'high') {
+      counts.high++;
+    } else if (t.priority === 'medium') {
+      counts.medium++;
+    } else if (t.priority === 'low') {
+      counts.low++;
+    } else {
+      counts.unset++;
+    }
   }
 
   // Build INDEX.md
@@ -333,13 +380,28 @@ function cmdTodoReindex(cwd, raw) {
 
   for (let i = 0; i < todos.length; i++) {
     const t = todos[i];
-    let title = t.title;
-    if (title.length > 50) title = title.slice(0, 50) + '...';
-    lines.push(`| ${i + 1} | ${t.id} | ${title} | ${t.priority} | ${t.status} | ${t.created} |`);
+    if (t.malformed) {
+      // Render the MALFORMED sentinel row; truncate the reason if very long.
+      let marker = 'MALFORMED: ' + t.reason;
+      if (marker.length > 50) marker = marker.slice(0, 50) + '...';
+      lines.push(`| ${i + 1} | ${t.fileId} | ${marker} | — | — | — |`);
+    } else {
+      let title = t.title;
+      if (title.length > 50) title = title.slice(0, 50) + '...';
+      lines.push(`| ${i + 1} | ${t.id} | ${title} | ${t.priority} | ${t.status} | ${t.created} |`);
+    }
   }
 
   lines.push('');
-  lines.push(`**Total:** ${todos.length} items (${counts.high} high, ${counts.medium} medium, ${counts.low} low, ${counts.unset} unset)`);
+  // Malformed records count toward N items total; they are excluded only from
+  // the priority breakdown (H/M/L/unset). When all TODOs are well-formed the
+  // summary line is byte-identical to the legacy format so downstream parsers
+  // of well-formed runs stay compatible.
+  if (malformedCount > 0) {
+    lines.push(`**Total:** ${todos.length} items (${counts.high} high, ${counts.medium} medium, ${counts.low} low, ${counts.unset} unset, ${malformedCount} malformed)`);
+  } else {
+    lines.push(`**Total:** ${todos.length} items (${counts.high} high, ${counts.medium} medium, ${counts.low} low, ${counts.unset} unset)`);
+  }
   lines.push('');
   lines.push('---');
   const now = new Date();
@@ -350,7 +412,15 @@ function cmdTodoReindex(cwd, raw) {
   const indexPath = path.join(todosDir, 'INDEX.md');
   fs.writeFileSync(indexPath, lines.join('\n'), 'utf8');
 
-  output({ reindexed: todos.length, path: indexPath }, raw, `Reindexed ${todos.length} TODOs → INDEX.md`);
+  // Signal callers that drift was found — set exit code non-zero AFTER writing
+  // INDEX.md (so the file is on disk) and BEFORE the output() call (so JSON
+  // still flushes). Do NOT call process.exit() here; Node will use exitCode
+  // when the event loop drains.
+  if (malformedCount > 0) {
+    process.exitCode = 1;
+  }
+
+  output({ reindexed: todos.length, malformed: malformedCount, path: indexPath }, raw, `Reindexed ${todos.length} TODOs → INDEX.md`);
 }
 
 /**
@@ -408,6 +478,13 @@ function cmdTodoCheckStale(cwd, raw) {
     extraInIndex.length > 0 ||
     (!indexExists && diskIds.size > 0);
 
+  // Exit non-zero when stale so callers can use this as a gate after
+  // delete-and-reindex sequences (per SPEC TODO-029). Set exitCode before
+  // output() so JSON still flushes; do not call process.exit() directly.
+  if (stale) {
+    process.exitCode = 1;
+  }
+
   output(
     {
       stale,

package/commands/sf/audit.md

@@ -43,7 +43,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `AUDIT_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `AUDIT_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `AUDIT_SCOPE` in the subsequent argument-parsing step (Step 3.5).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -77,7 +92,7 @@ Exit.
 
 ## Step 3.5: Check for --import Flag
 
-Parse arguments for `--import "feedback text"` pattern.
+Parse `AUDIT_SCOPE` for `--import "feedback text"` pattern.
 
 **If --import flag present:** Go to Step 4-IMPORT
 **Otherwise:** Continue to Step 4 (internal audit)
@@ -156,7 +171,7 @@ In spec frontmatter, set: `status: revision_requested`
 
 Update STATE.md via CLI:
 ```bash
-node bin/sf-tools.cjs state add-active SPEC-XXX external_review /sf:revise
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state add-active SPEC-XXX external_review /sf:revise
 ```
 Add decision: "Imported external feedback for SPEC-XXX"
 
@@ -299,7 +314,7 @@ Tip: `/clear` recommended — executor needs fresh context for implementation
 
 ### If APPROVED (with optional recommendations):
 
-The `Recommendation:` line is emitted by the auditor agent (Step 7.5 in `agents/spec-auditor.md`) using `node bin/sf-tools.cjs recommend --source audit --critical 0 --minor N`. The STATE.md Next Step remains `/sf:run` (without the `--apply=minor` suffix) — the suffix is advisory here only.
+The `Recommendation:` line is emitted by the auditor agent (Step 7.5 in `agents/spec-auditor.md`) using `node ~/.claude/specflow-cc/bin/sf-tools.cjs recommend --source audit --critical 0 --minor N`. The STATE.md Next Step remains `/sf:run` (without the `--apply=minor` suffix) — the suffix is advisory here only.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/commands/sf/autopilot.md

@@ -50,7 +50,22 @@ Parse the command argument to determine execution mode:
 
 **CRITICAL — N>1 guard (autopilot must be unambiguous):**
 
-Call `node bin/sf-tools.cjs state resolve $SPEC_ID_ARG` (pass SPEC-ID arg if provided; omit if not).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `AUTOPILOT_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `AUTOPILOT_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `AUTOPILOT_SCOPE` in the subsequent mode-determination step (e.g. `--all` flag).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -274,7 +289,7 @@ mv .specflow/specs/SPEC-XXX.md .specflow/archive/
 5. **Update STATE.md:**
    Remove SPEC-XXX from Active Specifications table:
    ```bash
-   node bin/sf-tools.cjs state remove-active SPEC-XXX
+   node ~/.claude/specflow-cc/bin/sf-tools.cjs state remove-active SPEC-XXX
    ```
    Remove SPEC-XXX row from Queue table (using Read+Write).
 

package/commands/sf/discuss.md

@@ -62,7 +62,7 @@ Determine discussion mode from arguments:
 - Mode: `requirements-gathering`
 
 **Case E: No arguments**
-- Call `node bin/sf-tools.cjs state resolve` to resolve active spec
+- Call `node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve` to resolve active spec
 - `{"action":"use","id":"SPEC-XXX"}` → discuss that spec
 - `{"action":"error","code":"NO_ACTIVE_SPEC"}` → ask what to discuss
 - `{"action":"ask","options":[...]}` → use AskUserQuestion to pick which spec to discuss

package/commands/sf/done.md

@@ -39,7 +39,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `DONE_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `DONE_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `DONE_SCOPE` in the subsequent argument-parsing step (Step 2.5).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -61,7 +76,7 @@ Parse the JSON response:
 
 ## Step 2.5: Handle `--apply=minor` Flag
 
-**Check if `--apply=minor` was passed in the invocation arguments.**
+**Check if `DONE_SCOPE` contains `--apply=minor`.**
 
 **If `--apply=minor` is NOT present:** Continue to Step 3 (existing behavior unchanged).
 
@@ -85,7 +100,7 @@ Extract Critical, Major, and Minor counts from that entry.
 
 Run:
 ```bash
-node bin/sf-tools.cjs recommend --source review --critical N --major M --minor K
+node ~/.claude/specflow-cc/bin/sf-tools.cjs recommend --source review --critical N --major M --minor K
 ```
 
 Parse the JSON response.
@@ -385,6 +400,15 @@ rm .specflow/todos/{source}.md
 node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
 ```
 
+   Then run the stale-check exit gate. The `rm` + `reindex` sequence is LLM-orchestrated and has no machine-enforced atomicity — any inversion, interruption, or skipped step leaves INDEX.md with a ghost row. Treat non-zero exit as a **finalization failure**: re-run `todo reindex`, and if still stale, surface the drift to the user before continuing.
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo check-stale
+```
+
+   - **Exit 0 (FRESH):** proceed to Step 8.
+   - **Exit 1 (STALE):** re-run `todo reindex` once; if `check-stale` still exits non-zero, halt finalization and report `extra_in_index` / `missing_from_index` from the JSON output so the user can repair the drift manually.
+
 3. **If NOT_FOUND (backward compatibility):** Also check legacy format — look in `.specflow/todos/TODO.md` for the referenced ID. If found there, remove the block using the Edit tool.
 
 No "Last updated" lines to update in per-file format.
@@ -414,7 +438,7 @@ If the command fails (parser cannot extract required fields), log a warning to t
 ### Remove from Active Specifications Table
 
 ```bash
-node bin/sf-tools.cjs state remove-active SPEC-XXX
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state remove-active SPEC-XXX
 ```
 
 ### Remove from Queue

package/commands/sf/fix.md

@@ -43,7 +43,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `FIX_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `FIX_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `FIX_SCOPE` in the subsequent argument-parsing step (Step 5).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -93,14 +108,16 @@ Exit.
 
 ## Step 5: Parse Arguments
 
-| Argument | Action |
-|----------|--------|
-| (none) | Interactive mode — show issues, ask what to fix |
+Parse `FIX_SCOPE` (set in Step 2):
+
+| Value of `FIX_SCOPE` | Action |
+|----------------------|--------|
+| (empty) | Interactive mode — show issues, ask what to fix |
 | "all" | Apply all critical AND major AND minor fixes |
 | "1,2,3" | Apply only numbered items |
 | "..." | Treat as custom fix instructions |
 
-### If Interactive Mode (no arguments):
+### If Interactive Mode (FIX_SCOPE is empty):
 
 Display review findings:
 
@@ -182,7 +199,7 @@ Append to Review History:
 **If `--internal` is NOT set (normal invocation):**
 
 ```bash
-node bin/sf-tools.cjs state add-active SPEC-XXX review /sf:review
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state add-active SPEC-XXX review /sf:review
 ```
 
 ## Step 9: Display Result

package/commands/sf/health.md

@@ -38,7 +38,7 @@ Exit.
 Run migration on entry — idempotent, no-op when already migrated:
 
 ```bash
-node bin/sf-tools.cjs state migrate
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state migrate
 ```
 
 Parse the response:
@@ -84,7 +84,7 @@ For each check:
 Read STATE.md and validate:
 
 **E003: Active spec references non-existent file**
-- List all active specs via `node bin/sf-tools.cjs state list-active`
+- List all active specs via `node ~/.claude/specflow-cc/bin/sf-tools.cjs state list-active`
 - For each SPEC-ID, check `.specflow/specs/{ID}.md` exists
 - If missing: error (repairable — remove that row via `state remove-active`)
 

package/commands/sf/help.md

@@ -206,7 +206,7 @@ Exit.
 
 Show active specs count (uses list-active for multi-spec awareness):
 ```bash
-node bin/sf-tools.cjs state list-active --raw
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state list-active --raw
 ```
 
 Display full command reference:

package/commands/sf/pause.md

@@ -36,7 +36,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `PAUSE_NOTE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `PAUSE_NOTE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `PAUSE_NOTE` in Step 6.5 (notes prompt — pre-populate if non-empty).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -53,7 +68,7 @@ Parse the JSON response:
   Options: {id — title (status)} for each entry
   ```
 
-Also call `node bin/sf-tools.cjs state list-active` to capture all active specs in the pause file.
+Also call `node ~/.claude/specflow-cc/bin/sf-tools.cjs state list-active` to capture all active specs in the pause file.
 
 ## Step 3: Load Active Specification Details
 

package/commands/sf/plan.md

@@ -179,6 +179,15 @@ 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.
 
+4. **Run the stale-check exit gate.** The `rm` + `reindex` sequence is LLM-orchestrated; this surfaces drift immediately instead of deferring it to the next `/sf:status`.
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo check-stale
+```
+
+   - **Exit 0 (FRESH):** proceed to Step 8.
+   - **Exit 1 (STALE):** re-run `todo reindex` once; if `check-stale` still exits non-zero, halt the conversion and report `extra_in_index` / `missing_from_index` from the JSON output so the user can repair the drift manually.
+
 ## Step 8: Display Result
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
@@ -240,13 +249,16 @@ Use `/sf:new "{todo description}"` logic:
 
 ### Remove Todo
 
-Delete the file `.specflow/todos/TODO-{XXX}.md`, then refresh INDEX.md:
+Delete the file `.specflow/todos/TODO-{XXX}.md`, then refresh INDEX.md and run the stale-check exit gate:
 
 ```bash
 rm .specflow/todos/TODO-{XXX}.md
 node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo check-stale
 ```
 
+Treat non-zero exit from `check-stale` as a failure: re-run `todo reindex`, and if still stale, surface the drift to the user before continuing.
+
 </fallback>
 
 <success_criteria>

package/commands/sf/review.md

@@ -39,7 +39,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `REVIEW_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `REVIEW_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `REVIEW_SCOPE` in subsequent steps for any review flags.
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -158,7 +173,7 @@ After the agent updates STATE.md, check if rotation is needed:
 
 ### If APPROVED (no minor issues):
 
-The `Recommendation:` line is emitted by the reviewer agent (Step 7.5 in `agents/impl-reviewer.md`) using `node bin/sf-tools.cjs recommend --source review --critical 0 --major 0 --minor 0`. The STATE.md Next Step remains `/sf:done` (canonical).
+The `Recommendation:` line is emitted by the reviewer agent (Step 7.5 in `agents/impl-reviewer.md`) using `node ~/.claude/specflow-cc/bin/sf-tools.cjs recommend --source review --critical 0 --major 0 --minor 0`. The STATE.md Next Step remains `/sf:done` (canonical).
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -345,9 +360,9 @@ Append Review History to spec.
 
 ```bash
 # If APPROVED:
-node bin/sf-tools.cjs state add-active SPEC-XXX done /sf:done
+node ~/.claude/specflow-cc/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
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state add-active SPEC-XXX review /sf:fix
 ```
 
 </fallback>

package/commands/sf/revise.md

@@ -42,7 +42,22 @@ Exit.
 
 ## Step 2: Resolve 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).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `REVISE_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `REVISE_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `REVISE_SCOPE` in the subsequent argument-parsing step (Step 5).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -160,9 +175,11 @@ Continue to Step 5 with analysis context available.
 
 ## Step 5: Parse Arguments
 
-| Argument | Action |
-|----------|--------|
-| (none) | Interactive mode — show comments, ask what to fix |
+Parse `REVISE_SCOPE` (set in Step 2):
+
+| Value of `REVISE_SCOPE` | Action |
+|-------------------------|--------|
+| (empty) | Interactive mode — show comments, ask what to fix |
 | "all" | Apply all critical issues AND recommendations |
 | "1,2,3" | Apply only numbered items |
 | "--no-analysis" | Skip pre-analysis, go directly to review mode |
@@ -170,9 +187,9 @@ Continue to Step 5 with analysis context available.
 
 **Check for `--no-analysis` flag:**
 
-If the arguments string contains `--no-analysis`:
+If `REVISE_SCOPE` contains `--no-analysis`:
 - Set SKIP_ANALYSIS to true
-- Remove the `--no-analysis` flag from the arguments string for further processing
+- Remove the `--no-analysis` flag from `REVISE_SCOPE` for further processing
 
 ### If Interactive Mode (no arguments):
 
@@ -532,7 +549,7 @@ In spec frontmatter: `status: auditing`
 
 In STATE.md:
 ```bash
-node bin/sf-tools.cjs state add-active SPEC-XXX auditing /sf:audit
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state add-active SPEC-XXX auditing /sf:audit
 ```
 
 </fallback>

package/commands/sf/run.md

@@ -42,7 +42,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `RUN_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `RUN_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `RUN_SCOPE` in the subsequent argument-parsing step (Step 3.5).
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
@@ -68,7 +83,7 @@ Read the active spec file: `.specflow/specs/SPEC-XXX.md`
 
 ## Step 3.5: Handle `--apply=minor` Flag
 
-**Check if `--apply=minor` was passed in the invocation arguments.**
+**Check if `RUN_SCOPE` contains `--apply=minor`.**
 
 **If `--apply=minor` is NOT present:** Continue to Step 4 (existing behavior unchanged).
 
@@ -92,7 +107,7 @@ Extract Critical count and Recommendations count from that entry. Map Recommenda
 
 Run:
 ```bash
-node bin/sf-tools.cjs recommend --source audit --critical N --minor M
+node ~/.claude/specflow-cc/bin/sf-tools.cjs recommend --source audit --critical N --minor M
 ```
 
 Parse the JSON response.
@@ -118,7 +133,7 @@ This reuses `/sf:revise`'s existing per-item commit behavior. Do NOT duplicate r
 
 Run spec structural validation:
 ```bash
-node bin/sf-tools.cjs spec validate SPEC-XXX
+node ~/.claude/specflow-cc/bin/sf-tools.cjs spec validate SPEC-XXX
 ```
 
 This is the exact gate specified in R2.5: verifies frontmatter parses, required fields present (`id`, `type`, `status`, `priority`), and `## Requirements` heading present. No fallback path.
@@ -265,7 +280,7 @@ Use model for `spec-executor` or `spec-executor-orchestrator` from selected prof
 ## Step 7: Update Status
 
 ```bash
-node bin/sf-tools.cjs state add-active SPEC-XXX running "(in progress)"
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state add-active SPEC-XXX running "(in progress)"
 ```
 
 Update spec frontmatter:

package/commands/sf/show.md

@@ -42,7 +42,7 @@ Exit.
 Use provided ID (e.g., SPEC-003).
 
 **If no argument:**
-Call `node bin/sf-tools.cjs state resolve` to get active spec.
+Call `node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve` to get active spec.
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → use SPEC-XXX

package/commands/sf/split.md

@@ -58,7 +58,7 @@ Use `/sf:list` to see available specifications.
 Exit.
 
 **If no ID provided:**
-Call `node bin/sf-tools.cjs state resolve` to get active spec.
+Call `node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve` to get active spec.
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → use SPEC-XXX
@@ -365,8 +365,8 @@ Add split reference to archived parent.
 - 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
+  node ~/.claude/specflow-cc/bin/sf-tools.cjs state remove-active SPEC-PARENT
+  node ~/.claude/specflow-cc/bin/sf-tools.cjs state add-active SPEC-XXXa draft /sf:audit
   ```
 
 </fallback>

package/commands/sf/status.md

@@ -39,12 +39,12 @@ Read `.specflow/STATE.md` and extract Queue, Recent Decisions, Warnings.
 
 Get active specs:
 ```bash
-node bin/sf-tools.cjs state list-active
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state list-active
 ```
 
 For single-spec display, also call:
 ```bash
-node bin/sf-tools.cjs state resolve
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve
 ```
 
 Parse the resolve response:
@@ -108,13 +108,13 @@ Fix: Rename the spec in specs/ to next available ID.
 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
+node ~/.claude/specflow-cc/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`).
+INDEX.md stale — run /sf:todos (or `node ~/.claude/specflow-cc/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}
@@ -232,7 +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)
+- [ ] TODO index freshness checked via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo check-stale` (warning surfaced if stale)
 - [ ] Current position displayed
 - [ ] Queue shown
 - [ ] Recommended next step clear

package/commands/sf/verify.md

@@ -36,7 +36,22 @@ Exit.
 
 ## Step 2: Resolve Active Specification
 
-Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+Parse `$ARGUMENTS`:
+- Let `FIRST_TOKEN` = first whitespace-separated token of `$ARGUMENTS`.
+- If `FIRST_TOKEN` matches `^SPEC-\d{3,}$`:
+  - Set `SPEC_ARG="$FIRST_TOKEN"`
+  - Set `VERIFY_SCOPE` = remainder of `$ARGUMENTS` after `FIRST_TOKEN` (trimmed)
+- Else:
+  - Set `SPEC_ARG=""` (resolver uses Active Specifications table)
+  - Set `VERIFY_SCOPE="$ARGUMENTS"`
+
+Call:
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs state resolve $SPEC_ARG
+```
+
+Use `VERIFY_SCOPE` in subsequent steps for any verify flags.
 
 Parse the JSON response:
 - `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX

package/package.json

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