specflow-cc 1.18.2 → 1.19.0

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.19.0] - 2026-04-12
+
+### Added
+
+- **Deferred work detection in auditor** — the auditor now detects deferred work items (TODOs, FIXMEs, placeholder implementations) in the spec and flags them as findings (step 3.9.5)
+
+### Fixed
+
+- **TODO INDEX.md auto-sync** — `INDEX.md` in `.specflow/todos/` was getting out of sync because `/sf:todo` and `/sf:done` modified TODO files without regenerating the index. Added `todo reindex` command to `sf-tools.cjs` and wired it into both `/sf:todo` (Step 6.5) and `/sf:done` (Step 7.5, after TODO file deletion)
+
+## [1.18.3] - 2026-04-11
+
+### Fixed
+
+- **Auto-heal for users upgrading from 1.18.0 / 1.18.1** — the installer now scans `hooks.PostToolUse` during every install and removes any flat `{ type, command }` entry that references `context-monitor`. These entries were written by the buggy `1.18.0`/`1.18.1` installer and would otherwise linger in `settings.json` next to the newly written correct matcher group, still tripping Claude Code's `"Expected array, but received undefined"` parse error. Foreign flat entries (belonging to other tools) are left untouched — only entries unambiguously written by prior SpecFlow versions are removed.
+- Three new smoke tests cover clean auto-heal, preservation of foreign flat entries, and the mixed state (pre-existing correct hook + flat broken duplicate).
+
 ## [1.18.2] - 2026-04-11
 
 ### Fixed

package/agents/spec-auditor.md

@@ -457,6 +457,55 @@ Check if spec includes items marked as "Out of Scope" or "Deferred" in PROJECT.m
 **If compliant:**
 - Add to audit output: "Project compliance: ✓ Honors PROJECT.md decisions"
 
+## Step 3.9.5: Deferred Work Detection
+
+Scan the specification's prose sections for mentions of work that is explicitly deferred, out of scope, or planned for a follow-up. This prevents deferred work from being silently lost when the spec is archived.
+
+### 3.9.5.1 Scan Sections
+
+Search the following sections of the spec for deferred work signals:
+- Context
+- Goal Analysis
+- Requirements
+- Constraints
+- Assumptions
+- Acceptance Criteria
+
+**Signal patterns to detect** (case-insensitive):
+- "defer", "deferred"
+- "follow-up", "follow up", "followup"
+- "future work", "future spec", "future phase"
+- "separate spec", "separate task"
+- "out of scope", "out-of-scope"
+- "not in this spec", "not included in this spec"
+- "will be added later", "added in a later"
+- "TBD", "to be determined"
+- "planned for", "tracked as", "tracked in"
+
+### 3.9.5.2 Cross-Reference with TODOs
+
+For each deferred item found:
+
+1. Extract a short description of the deferred work from the surrounding sentence
+2. Check if a corresponding TODO already exists:
+   - Search `.specflow/todos/` files for keywords from the deferred item description
+   - If a matching TODO exists: note as covered
+   - If no matching TODO found: flag as untracked
+
+### 3.9.5.3 Deferred Work Verdict
+
+**If untracked deferred items found:**
+- Add **Recommendation** with prefix `[Deferred]` for each:
+  - `"Deferred work mentioned but no TODO found: '{quoted phrase from spec}'. Create via /sf:todo to prevent scope loss."`
+
+**If all deferred items have matching TODOs:**
+- Add to audit output: `"Deferred work: ✓ All deferred items tracked"`
+
+**If no deferred work mentions found:**
+- Omit from audit output (no line needed)
+
+**Note:** This is always a Recommendation, never Critical — the spec itself may be correct, and the TODO may have been created outside SpecFlow or may be intentionally deferred to a later planning session.
+
 ## Step 3.10: Language Profile Check
 
 **Detection:** Check if PROJECT.md contains a `## Language Profile` section.
@@ -840,6 +889,7 @@ Tip: `/clear` recommended before `/sf:run` — executor needs fresh context
 - [ ] PROJECT.md context loaded
 - [ ] All 10 dimensions evaluated (clarity, completeness, testability, scope, feasibility, architecture, duplication, cognitive load, strategic fit, project compliance)
 - [ ] Language profile checked (if present in PROJECT.md)
+- [ ] Deferred work scanned and cross-referenced with TODOs
 - [ ] Assumptions extracted and impact assessed
 - [ ] Project alignment verified
 - [ ] Project compliance verified (decisions, constraints, out-of-scope)

package/bin/install.js

@@ -289,6 +289,32 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
 
+  // Auto-heal: remove flat, broken context-monitor entries written by
+  // installer versions 1.18.0 and 1.18.1. Those versions pushed
+  // { type: "command", command: "..." } directly into PostToolUse, but
+  // Claude Code requires every PostToolUse entry to be a matcher group
+  // of shape { matcher?, hooks: [{ type, command }, ...] }. A flat entry
+  // makes Claude Code fail to parse settings.json entirely. Only entries
+  // that are unambiguously ours (flat + command references context-monitor)
+  // are removed; everything else is left untouched.
+  {
+    const before = settings.hooks.PostToolUse.length;
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+      const isFlatBrokenMonitor =
+        entry &&
+        !Array.isArray(entry.hooks) &&
+        entry.type === 'command' &&
+        typeof entry.command === 'string' &&
+        entry.command.includes('context-monitor');
+      return !isFlatBrokenMonitor;
+    });
+    const removed = before - settings.hooks.PostToolUse.length;
+    if (removed > 0) {
+      const plural = removed === 1 ? 'y' : 'ies';
+      console.log(`  ${green}✓${reset} Repaired settings.json (removed ${removed} broken hook entr${plural} from prior install)`);
+    }
+  }
+
   // Claude Code expects each PostToolUse entry to be a matcher group:
   //   { matcher?: string, hooks: [{ type, command }, ...] }
   // Detect an existing context-monitor hook inside any matcher group.

package/bin/lib/todo.cjs

@@ -231,8 +231,102 @@ function cmdTodoNextId(cwd, raw) {
   }, raw, nextId);
 }
 
+/**
+ * Reindex: scan TODO-*.md files, regenerate INDEX.md.
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdTodoReindex(cwd, raw) {
+  const todosDir = path.join(cwd, '.specflow', 'todos');
+
+  // Collect per-file TODOs
+  let perFiles;
+  try {
+    perFiles = fs.readdirSync(todosDir).filter(f => /^TODO-\d+\.md$/.test(f)).sort();
+  } catch (e) {
+    perFiles = [];
+  }
+
+  const todos = [];
+
+  for (const file of perFiles) {
+    const content = safeReadFile(path.join(todosDir, file));
+    if (!content) continue;
+
+    const parsed = parseFrontmatter(content);
+    const fm = parsed.frontmatter;
+
+    // Strip surrounding quotes from title (YAML may preserve them)
+    let title = fm.title || '';
+    if ((title.startsWith('"') && title.endsWith('"')) || (title.startsWith("'") && title.endsWith("'"))) {
+      title = title.slice(1, -1);
+    }
+
+    todos.push({
+      id: fm.id || file.replace('.md', ''),
+      title,
+      priority: fm.priority || '—',
+      status: fm.status || 'open',
+      created: fm.created || '',
+    });
+  }
+
+  // Sort by priority (high > medium > low > unset), then by created date
+  todos.sort((a, b) => {
+    const pa = priorityKey(a.priority);
+    const pb = priorityKey(b.priority);
+    if (pa !== pb) return pa - pb;
+    if (a.created < b.created) return -1;
+    if (a.created > b.created) return 1;
+    return 0;
+  });
+
+  // Count by priority
+  const counts = { high: 0, medium: 0, low: 0, unset: 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++;
+  }
+
+  // Build INDEX.md
+  const lines = [
+    '# To-Do Index',
+    '',
+    '> Auto-generated from individual TODO files. Do not edit manually.',
+    '> Regenerate with `/sf:todos`.',
+    '',
+    '| # | ID | Title | Priority | Status | Created |',
+    '|---|-----|-------|----------|--------|---------|',
+  ];
+
+  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} |`);
+  }
+
+  lines.push('');
+  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();
+  const timestamp = now.toISOString().replace('T', ' ').slice(0, 16);
+  lines.push(`*Last regenerated: ${timestamp}*`);
+  lines.push('');
+
+  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`);
+}
+
 module.exports = {
   cmdTodoLoad,
   cmdTodoList,
   cmdTodoNextId,
+  cmdTodoReindex,
 };

package/bin/sf-tools.cjs

@@ -12,6 +12,7 @@
  *   todo load <id>                        Parse TODO file, return frontmatter + body
  *   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
  *   queue next                            First actionable spec from queue
  *   state get                             Current active spec, status, next step
  *   state set-active <id> <status> [next] Update active spec in STATE.md
@@ -25,7 +26,7 @@
 const { output, error, generateSlug } = require('./lib/core.cjs');
 const { cmdStateGet, cmdStateSetActive, cmdQueueNext } = require('./lib/state.cjs');
 const { cmdSpecLoad, cmdSpecList, cmdSpecNextId } = require('./lib/spec.cjs');
-const { cmdTodoLoad, cmdTodoList, cmdTodoNextId } = require('./lib/todo.cjs');
+const { cmdTodoLoad, cmdTodoList, cmdTodoNextId, cmdTodoReindex } = require('./lib/todo.cjs');
 const { cmdResolveModel } = require('./lib/config.cjs');
 const { cmdVerifyStructure } = require('./lib/verify.cjs');
 
@@ -59,6 +60,7 @@ const COMMANDS = {
   },
   'todo list':       () => cmdTodoList(cwd, raw, { showAll: flags.all ?? false }),
   'todo next-id':    () => cmdTodoNextId(cwd, raw),
+  'todo reindex':    () => cmdTodoReindex(cwd, raw),
   'queue next':      () => cmdQueueNext(cwd, raw),
   'state get':       () => cmdStateGet(cwd, raw),
   'state set-active': () => {
@@ -90,6 +92,7 @@ Commands:
   todo load <id>                          Parse TODO file, return frontmatter + body
   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
   queue next                              First actionable spec from queue table
   state get                               Current active spec, status, next step
   state set-active <id> <status> [next]   Update active spec, status, next step

package/commands/sf/done.md

@@ -283,12 +283,16 @@ Check if the spec frontmatter contains a `source:` field (e.g., `source: TODO-00
 [ -f .specflow/todos/{source}.md ] && echo "FOUND" || echo "NOT_FOUND"
 ```
 
-2. **If FOUND:** Delete the file:
+2. **If FOUND:** Delete the file and reindex:
 
 ```bash
 rm .specflow/todos/{source}.md
 ```
 
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
+
 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/todo.md

@@ -96,6 +96,12 @@ created: {YYYY-MM-DD}
 
 Do NOT create or modify TODO.md. Do NOT update any "Last updated" lines.
 
+## Step 6.5: Reindex
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
+
 ## Step 7: Display Confirmation
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:

package/package.json

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