specflow-cc 1.22.2 → 1.23.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.1] - 2026-05-28
+
+### Fixed
+
+- **spec-auditor could not emit its Recommendation line** (agent lacked the Bash tool, and both audit/review agents referenced a non-existent relative `bin/sf-tools.cjs` path). Granted Bash to spec-auditor and corrected both paths to the canonical `~/.claude/specflow-cc/bin/sf-tools.cjs`. Also prefixed the same latent bare-path bug in [`agents/spec-reviser.md`](agents/spec-reviser.md) (`todo next-id` / `todo reindex`) so no bare relative `bin/sf-tools.cjs` remains in any agent. Both audit/review Step 7.5 blocks now fall back to the deterministic action mapping if the shell-out fails.
+
+## [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

package/agents/impl-reviewer.md

@@ -289,8 +289,9 @@ Using the Critical, Major, and Minor counts determined in Step 5:
 
 1. Shell out to obtain the recommendation:
    ```
-   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>
    ```
+   If the shell-out fails for any reason, derive the recommendation deterministically from the documented (critical/major/minor)→action mapping rather than omitting the line.
 
 2. Parse the JSON response: `{ "action": "...", "reason": "..." }`
 

package/agents/spec-auditor.md

@@ -1,7 +1,7 @@
 ---
 name: sf-spec-auditor
 description: Audits specifications for quality, completeness, and clarity in a fresh context
-tools: Read, Write, Glob, Grep
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 <role>
@@ -776,9 +776,9 @@ Using the Critical count and Recommendations count determined in Step 5:
 
 1. Shell out to obtain the recommendation:
    ```
-   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>
    ```
-   Note: The CLI flag is `--minor` even though the auditor uses the label "Recommendations" — this is intentional for parser symmetry across audit/review sources.
+   Note: The CLI flag is `--minor` even though the auditor uses the label "Recommendations" — this is intentional for parser symmetry across audit/review sources. If the shell-out fails for any reason, derive the recommendation deterministically from the documented (critical/minor)→action mapping rather than omitting the line.
 
 2. Parse the JSON response: `{ "action": "...", "reason": "..." }`
 

package/agents/spec-reviser.md

@@ -147,7 +147,7 @@ For each deferred item:
 
 1. Generate next TODO ID:
    ```bash
-   node bin/sf-tools.cjs todo next-id --raw
+   node ~/.claude/specflow-cc/bin/sf-tools.cjs todo next-id --raw
    ```
 2. Create `.specflow/todos/TODO-{XXX}.md` using the Write tool:
    ```markdown
@@ -181,7 +181,7 @@ For each deferred item:
 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
+node ~/.claude/specflow-cc/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.
@@ -253,7 +253,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)
+- [ ] INDEX.md refreshed via `node ~/.claude/specflow-cc/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

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

@@ -400,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.

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/package.json

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