specflow-cc 1.17.1 → 1.18.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.18.0] - 2026-04-08
+
+### Added
+
+- **Per-file TODO storage** — TODOs migrated from monolithic `TODO.md` to individual `TODO-XXX.md` files with YAML frontmatter, mirroring the established `SPEC-XXX.md` pattern
+  - Each TODO is now a standalone file in `.specflow/todos/` with structured metadata (id, title, priority, complexity, status, effort, depends_on, created)
+  - Auto-generated `INDEX.md` serves as a human-readable cache, regenerated by `/sf:todos`
+  - New `bin/lib/todo.cjs` utility module with `cmdTodoLoad`, `cmdTodoList`, `cmdTodoNextId` functions
+  - New CLI commands: `todo load <id>`, `todo list [--all]`, `todo next-id`
+  - New `/sf:migrate-todos` command for one-time migration from legacy format (with `--dry-run` support)
+  - Backward compatibility: projects with legacy `TODO.md` continue to work transparently
+  - Eliminated TODOs use `status: eliminated` soft-delete instead of file deletion, preserving history
+- **Updated commands** — all 10 TODO-touching commands and 3 agents updated to use per-file format:
+  `sf:todo`, `sf:todos`, `sf:plan`, `sf:done`, `sf:priority`, `sf:triage`, `sf:revise`, `sf:health`, `sf:status`, `sf:metrics`, `sf:init`, `spec-reviser`, `spec-creator`
+- **New health checks** — W009 (TODO file without valid frontmatter), W010 (legacy TODO.md alongside per-file TODOs)
+
+### Fixed
+
+- **W001 health check** — now checks for `todos/` directory instead of `TODO.md` file
+
 ## [1.17.1] - 2026-04-07
 
 ### Fixed

package/agents/spec-creator.md

@@ -156,6 +156,8 @@ If no specs exist in either directory, start with SPEC-001.
 Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 
 1. **Frontmatter:** id, type, status (draft), priority, complexity, created, source (if `<todo_context>` provided — set to the TODO ID, e.g., `source: TODO-006`), and optionally `delta: true` (only for brownfield tasks detected in Step 2.7)
+
+   **Note on `source:` field:** The `source: TODO-XXX` value refers to the identifier of a per-file TODO stored at `.specflow/todos/TODO-XXX.md`. It does NOT refer to an entry in a monolithic `TODO.md`. When `/sf:plan` converts a TODO and then `/sf:done` completes the spec, the cleanup step deletes `.specflow/todos/TODO-XXX.md` based on this field.
 2. **Title:** Clear, action-oriented
 3. **Context:** Why this is needed
    - **If `<prior_discussion>` provided:** Add "Prior Discussion" subsection linking to PRE-XXX or DISC-XXX with key decisions

package/agents/spec-reviser.md

@@ -143,16 +143,33 @@ After recording the Response, check if any items were marked as deferred (⏸).
 
 For each deferred item:
 
-1. Read `.specflow/todos/TODO.md` to find the highest existing TODO ID
-2. Generate next TODO ID (zero-padded to 3 digits, starting from 001)
-3. Create a new TODO entry with:
-   - **Description:** `{item description} (deferred from {SPEC-XXX} audit v{N})`
-   - **Priority:** —
-   - **Notes:** `Origin: {SPEC-XXX} Response v{N}. {reason for deferral}`
-
-4. Use the **Edit** tool (NOT Write) to insert the new entry into `.specflow/todos/TODO.md` after the first `---` following `# To-Do List` — never rewrite the entire file, as this would destroy existing todos
-
-5. Append a "TODOs Created" subsection to the Response in Audit History:
+1. Generate next TODO ID:
+   ```bash
+   node bin/sf-tools.cjs todo next-id --raw
+   ```
+2. Create `.specflow/todos/TODO-{XXX}.md` using the Write tool:
+   ```markdown
+   ---
+   id: TODO-{XXX}
+   title: "{item description} (deferred from {SPEC-XXX} audit v{N})"
+   priority: —
+   complexity: —
+   status: open
+   effort: —
+   depends_on: —
+   created: {YYYY-MM-DD}
+   ---
+
+   ## Description
+
+   {item description} (deferred from {SPEC-XXX} audit v{N})
+
+   ## Notes
+
+   Origin: {SPEC-XXX} Response v{N}. {reason for deferral}
+   ```
+
+3. Append a "TODOs Created" subsection to the Response in Audit History:
 
 ```markdown
 **TODOs Created:**
@@ -209,7 +226,7 @@ Output directly as formatted text (not wrapped in a code block):
 
 - .specflow/specs/SPEC-XXX.md
 {If TODOs created:}
-- .specflow/todos/TODO.md
+- .specflow/todos/TODO-{XXX}.md
 
 ### Next Step
 
@@ -226,7 +243,7 @@ Tip: `/clear` recommended — auditor needs fresh context
 - [ ] User's revision scope understood
 - [ ] Changes applied precisely
 - [ ] Revision Response recorded in Audit History
-- [ ] Deferred items (if any) created as TODOs in `.specflow/todos/TODO.md`
+- [ ] Deferred items (if any) created as individual `.specflow/todos/TODO-XXX.md` files
 - [ ] TODOs Created subsection appended to Response (if deferred items exist)
 - [ ] Frontmatter status updated
 - [ ] STATE.md updated

package/bin/lib/todo.cjs

@@ -0,0 +1,238 @@
+/**
+ * bin/lib/todo.cjs — TODO operations
+ *
+ * Exports: cmdTodoLoad(), cmdTodoList(), cmdTodoNextId()
+ *
+ * Mirrors the pattern of bin/lib/spec.cjs.
+ * Supports both per-file format (TODO-XXX.md) and legacy monolithic TODO.md.
+ * Format detection is based on presence of TODO-*.md files — INDEX.md is NOT
+ * the detection signal (it may not exist until sf:todos is first run).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, parseFrontmatter } = require('./core.cjs');
+
+/**
+ * Priority sort order (lower number = higher priority in sort).
+ */
+const PRIORITY_ORDER = { high: 0, medium: 1, low: 2 };
+
+/**
+ * Get sort key for a priority value.
+ * @param {string} priority
+ * @returns {number}
+ */
+function priorityKey(priority) {
+  if (priority && PRIORITY_ORDER[priority] !== undefined) {
+    return PRIORITY_ORDER[priority];
+  }
+  return 3; // unset / —
+}
+
+/**
+ * Load and parse a TODO file.
+ * @param {string} cwd - Working directory
+ * @param {string} id - TODO ID (e.g., "TODO-007")
+ * @param {boolean} raw - Output raw string
+ */
+function cmdTodoLoad(cwd, id, raw) {
+  if (!id) {
+    error('Missing TODO ID. Usage: todo load <id>');
+  }
+
+  const todoPath = path.join(cwd, '.specflow', 'todos', id + '.md');
+  const content = safeReadFile(todoPath);
+
+  if (!content) {
+    error('TODO not found: ' + todoPath);
+  }
+
+  const parsed = parseFrontmatter(content);
+
+  output({
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+  }, raw, parsed.body);
+}
+
+/**
+ * List all TODOs.
+ *
+ * Format detection:
+ * 1. If TODO-*.md files exist in .specflow/todos/ — use per-file format
+ * 2. If no per-file TODOs but TODO.md exists — use legacy format
+ * 3. If neither — return empty list
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ * @param {object} options - Options
+ * @param {boolean} options.showAll - If true, include eliminated items
+ */
+function cmdTodoList(cwd, raw, { showAll } = {}) {
+  const todosDir = path.join(cwd, '.specflow', 'todos');
+
+  // Check for per-file TODOs
+  let perFiles;
+  try {
+    perFiles = fs.readdirSync(todosDir).filter(f => /^TODO-\d+\.md$/.test(f)).sort();
+  } catch (e) {
+    perFiles = [];
+  }
+
+  if (perFiles.length > 0) {
+    // Per-file format
+    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;
+
+      // Filter eliminated unless showAll
+      if (!showAll && fm.status === 'eliminated') continue;
+
+      todos.push({
+        id: fm.id || file.replace('.md', ''),
+        title: fm.title || '',
+        priority: fm.priority || '—',
+        status: fm.status || 'open',
+        complexity: fm.complexity || '—',
+        created: fm.created || '',
+      });
+    }
+
+    // Sort by priority (high > medium > low > unset), then by created date (oldest first)
+    todos.sort((a, b) => {
+      const pa = priorityKey(a.priority);
+      const pb = priorityKey(b.priority);
+      if (pa !== pb) return pa - pb;
+      // Compare dates lexicographically (ISO dates sort correctly as strings)
+      if (a.created < b.created) return -1;
+      if (a.created > b.created) return 1;
+      return 0;
+    });
+
+    output(todos, raw, todos.map(t => t.id).join('\n'));
+    return;
+  }
+
+  // Legacy format: check for monolithic TODO.md
+  const legacyPath = path.join(todosDir, 'TODO.md');
+  const legacyContent = safeReadFile(legacyPath);
+
+  if (legacyContent) {
+    // Parse legacy TODO blocks: ## TODO-XXX — YYYY-MM-DD
+    const todos = [];
+    const blockRegex = /^## (TODO-\d+) — (\d{4}-\d{2}-\d{2})\s*\n([\s\S]*?)(?=^## TODO-|\Z)/gm;
+    let match;
+
+    // Append sentinel heading so the last block's lazy [\s\S]*? terminates correctly
+    while ((match = blockRegex.exec(legacyContent + '\n## TODO-END')) !== null) {
+      const id = match[1];
+      const created = match[2];
+      const body = match[3];
+
+      // Extract description
+      const descMatch = body.match(/\*\*Description:\*\*\s*(.+)/);
+      const title = descMatch ? descMatch[1].trim() : '';
+
+      // Extract priority
+      const prioMatch = body.match(/\*\*Priority:\*\*\s*(\S+)/);
+      const priority = prioMatch ? prioMatch[1].trim() : '—';
+
+      if (!showAll) {
+        // Legacy format has no eliminated status — always include
+      }
+
+      todos.push({
+        id,
+        title,
+        priority,
+        status: 'open',
+        complexity: '—',
+        created,
+      });
+    }
+
+    // Sort same way
+    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;
+    });
+
+    output(todos, raw, todos.map(t => t.id).join('\n'));
+    return;
+  }
+
+  // Neither format found — empty list
+  output([], raw, '');
+}
+
+/**
+ * Calculate the next available TODO-XXX number.
+ *
+ * Scans:
+ * 1. .specflow/todos/TODO-*.md filenames using fs.readdirSync() + JS regex
+ * 2. .specflow/todos/TODO.md for legacy IDs using fs.readFileSync() + /TODO-(\d+)/g
+ *
+ * NOTE: Does NOT use grep -oP (GNU-only, unavailable on macOS).
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdTodoNextId(cwd, raw) {
+  const todosDir = path.join(cwd, '.specflow', 'todos');
+
+  let maxNum = 0;
+
+  // Scan per-file TODOs
+  try {
+    const files = fs.readdirSync(todosDir);
+    for (const file of files) {
+      const match = file.match(/^TODO-(\d+)\.md$/);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) maxNum = num;
+      }
+    }
+  } catch (e) {
+    // directory may not exist yet
+  }
+
+  // Scan legacy TODO.md for any IDs referenced there
+  const legacyPath = path.join(todosDir, 'TODO.md');
+  try {
+    const legacyContent = fs.readFileSync(legacyPath, 'utf8');
+    const regex = /TODO-(\d+)/g;
+    let match;
+    while ((match = regex.exec(legacyContent)) !== null) {
+      const num = parseInt(match[1], 10);
+      if (num > maxNum) maxNum = num;
+    }
+  } catch (e) {
+    // file may not exist — skip
+  }
+
+  const nextNumber = maxNum + 1;
+  const nextId = 'TODO-' + String(nextNumber).padStart(3, '0');
+
+  output({
+    next_id: nextId,
+    next_number: nextNumber,
+  }, raw, nextId);
+}
+
+module.exports = {
+  cmdTodoLoad,
+  cmdTodoList,
+  cmdTodoNextId,
+};

package/bin/sf-tools.cjs

@@ -9,6 +9,9 @@
  *   spec load <id>                        Parse spec file, return frontmatter + body
  *   spec list                             List all specs
  *   spec next-id                          Next available SPEC-XXX number
+ *   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
  *   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
@@ -22,6 +25,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 { cmdResolveModel } = require('./lib/config.cjs');
 const { cmdVerifyStructure } = require('./lib/verify.cjs');
 
@@ -34,6 +38,14 @@ const filteredArgs = args.filter(a => a !== '--raw');
  * Command dispatch table.
  * Keys are "command subcommand" or just "command".
  */
+const flags = {};
+for (const arg of filteredArgs) {
+  if (arg.startsWith('--')) {
+    const key = arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    flags[key] = true;
+  }
+}
+
 const COMMANDS = {
   'spec load':       () => {
     if (!filteredArgs[2]) error('Missing spec ID. Usage: spec load <id>');
@@ -41,6 +53,12 @@ const COMMANDS = {
   },
   'spec list':       () => cmdSpecList(cwd, raw),
   'spec next-id':    () => cmdSpecNextId(cwd, raw),
+  'todo load':       () => {
+    if (!filteredArgs[2]) error('Missing TODO ID. Usage: todo load <id>');
+    cmdTodoLoad(cwd, filteredArgs[2], raw);
+  },
+  'todo list':       () => cmdTodoList(cwd, raw, { showAll: flags.all ?? false }),
+  'todo next-id':    () => cmdTodoNextId(cwd, raw),
   'queue next':      () => cmdQueueNext(cwd, raw),
   'state get':       () => cmdStateGet(cwd, raw),
   'state set-active': () => {
@@ -69,6 +87,9 @@ Commands:
   spec load <id>                          Parse spec file, return frontmatter + body
   spec list                               List all specs from .specflow/specs/
   spec next-id                            Next available SPEC-XXX number
+  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
   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

@@ -277,12 +277,21 @@ Check if the spec frontmatter contains a `source:` field (e.g., `source: TODO-00
 
 **If `source:` field exists:**
 
-1. Read `.specflow/todos/TODO.md`
-2. Check if the referenced TODO-XXX entry still exists in the file
-3. **If it exists** — use the **Edit** tool (NOT Write) to remove the entire block (from `## TODO-XXX` heading through the next `---` separator, inclusive) — replace with empty string
-4. Use the **Edit** tool to update `*Last updated:` timestamp with note: `TODO-XXX cleaned up (completed via SPEC-YYY)`
+1. Check if `.specflow/todos/{source}.md` exists (per-file format):
 
-**CRITICAL:** Never rewrite the entire file with Write. Use Edit to remove the specific block and update the timestamp — this preserves all other todos.
+```bash
+[ -f .specflow/todos/{source}.md ] && echo "FOUND" || echo "NOT_FOUND"
+```
+
+2. **If FOUND:** Delete the file:
+
+```bash
+rm .specflow/todos/{source}.md
+```
+
+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.
 
 **If no `source:` field or TODO already removed:** Skip — no action needed.
 
@@ -431,7 +440,7 @@ git commit -m "docs(sf): complete SPEC-XXX"
 - [ ] Spec status updated to "done"
 - [ ] Completion section added
 - [ ] Decisions extracted (if any)
-- [ ] Source TODO cleaned up (if `source:` field exists in spec)
+- [ ] Source TODO file deleted (if `source:` field exists in spec and file exists in todos/)
 - [ ] Spec moved to archive
 - [ ] STATE.md updated (cleared active, removed from queue)
 - [ ] Final commit created

package/commands/sf/health.md

@@ -50,16 +50,22 @@ Initialize collectors:
 |-------|------|----------|------------|
 | E001 | `.specflow/STATE.md` missing | error | Yes — regenerate minimal STATE.md |
 | E002 | `.specflow/STATE.md` missing `## Queue` section | error | No |
-| W001 | `.specflow/todos/TODO.md` missing | warning | Yes — create empty TODO.md |
+| W001 | `.specflow/todos/` directory missing | warning | Yes — create directory |
 | W002 | `.specflow/specs/` directory missing | warning | Yes — create directory |
 | W003 | `.specflow/archive/` directory missing | warning | Yes — create directory |
 | W004 | `.specflow/execution/` directory missing | warning | Yes — create directory |
+| W009 | TODO file without valid YAML frontmatter | warning | No — inspect manually |
+| W010 | Legacy `TODO.md` exists alongside per-file TODOs (suggest migration) | info | No — run `/sf:migrate-todos` |
 
 For each check:
 1. Test existence
 2. If missing and repairable and `--repair`: fix it, add to `repairs[]`
 3. If missing and not repairable: add to `errors[]` or `warnings[]`
 
+**For W009:** List all `TODO-*.md` files in `.specflow/todos/` and check each for valid YAML frontmatter (presence of `id:`, `status:`, `created:` fields).
+
+**For W010:** If both `TODO-*.md` files AND `TODO.md` exist in `.specflow/todos/`, add info note suggesting `/sf:migrate-todos` to complete migration.
+
 ### 3.2 STATE.md Integrity
 
 Read STATE.md and validate:
@@ -181,7 +187,7 @@ Display final status.
 | E001 | error | STATE.md not found | Yes |
 | E002 | error | STATE.md missing Queue section | No |
 | E003 | error | Active spec references non-existent file | Yes |
-| W001 | warning | TODO.md not found | Yes |
+| W001 | warning | todos/ directory missing | Yes |
 | W002 | warning | specs/ directory missing | Yes |
 | W003 | warning | archive/ directory missing | Yes |
 | W004 | warning | execution/ directory missing | Yes |
@@ -189,6 +195,8 @@ Display final status.
 | W006 | warning | Queue has duplicate spec IDs | No |
 | W007 | warning | STATE.md missing required sections | No |
 | W008 | warning | Stale execution state files | Yes |
+| W009 | warning | TODO file without valid frontmatter | No |
+| W010 | info | Legacy TODO.md alongside per-file TODOs | No |
 | I001 | info | Spec not in queue (may be WIP) | No |
 | I002 | info | Completed spec not archived | No |
 
@@ -199,7 +207,7 @@ Display final status.
 | Action | Effect | Risk |
 |--------|--------|------|
 | Create STATE.md | Minimal template with empty queue | None |
-| Create TODO.md | Empty TODO template | None |
+| Create todos/ directory | Empty directory for per-file TODOs | None |
 | Create directories | specs/, archive/, execution/ | None |
 | Clear active spec | Set to "—" if spec file missing | Loses active reference |
 | Delete stale execution | Remove orphaned .json state files | None |

package/commands/sf/init.md

@@ -39,7 +39,7 @@ Check whether the user invoked `/sf:init --force`. Look at the invocation string
 [ -f .specflow/PROJECT.md ] && echo "HAS_PROJECT_MD" || true
 [ -f .specflow/STATE.md ] && echo "HAS_STATE_MD" || true
 [ -f .specflow/config.json ] && echo "HAS_CONFIG_JSON" || true
-[ -f .specflow/todos/TODO.md ] && echo "HAS_TODO_MD" || true
+[ -d .specflow/todos ] && echo "HAS_TODOS_DIR" || true
 [ "$(ls -A .specflow/specs 2>/dev/null)" ] && echo "HAS_SPECS" || true
 [ "$(ls -A .specflow/archive 2>/dev/null)" ] && echo "HAS_ARCHIVE" || true
 ```
@@ -58,7 +58,7 @@ The following files/directories would be overwritten:
   - .specflow/PROJECT.md
   - .specflow/STATE.md
   - .specflow/config.json
-  - .specflow/todos/TODO.md
+  - .specflow/todos/ (directory)
   - .specflow/specs/ (contains files)
   - .specflow/archive/ (contains files)
 

package/commands/sf/metrics.md

@@ -17,7 +17,7 @@ Calculate and display project statistics including completion rates, quality met
 @.specflow/STATE.md
 @.specflow/specs/SPEC-*.md
 @.specflow/archive/SPEC-*.md
-@.specflow/todos/TODO.md
+@.specflow/todos/
 </context>
 
 <workflow>
@@ -79,13 +79,22 @@ For each `.specflow/archive/SPEC-*.md`:
 ### Parse To-Dos
 
 ```bash
-# Count todos
-TODO_COUNT=$(grep -c "^## TODO-" .specflow/todos/TODO.md 2>/dev/null || echo 0)
+# Count todos via CLI tool (format-agnostic, excludes eliminated by default)
+node bin/sf-tools.cjs todo list --raw
+```
 
-# Count converted (todos that became specs - check STATE.md decisions)
-# This is approximated by todos with "converted" or spec reference
+This returns the list of open TODO IDs. For `--all` (including eliminated):
+```bash
+node bin/sf-tools.cjs todo list --all --raw
 ```
 
+Parse priority breakdown from the JSON output to count by priority level.
+
+Also check:
+- `TODO_COUNT` = number of open TODOs (from default list)
+- `TODO_COUNT_ALL` = total including eliminated (from --all list)
+- Count converted (todos that became specs) approximated from decisions table
+
 ### Get Project Start Date
 
 Read `.specflow/PROJECT.md` for initialized date, or use earliest spec creation date.
@@ -241,7 +250,7 @@ Based on calculated metrics, generate 2-4 actionable insights:
 
 ## To-Do Backlog
 
-{If TODO.md exists and has items:}
+{If TODO count > 0:}
 | Metric         | Value |
 |----------------|-------|
 | Total items    | {N}   |