specflow-cc 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.21.0] - 2026-05-15
+
+### Added
+
+- **L1 archive summary layer** — every archived spec now has a sibling `.specflow/archive/<SPEC-ID>.summary.md` file (~24 lines: goal, key decisions, key files, tests, completion date, link to full spec). Modelled on TencentDB Agent Memory's atomic-facts tier: agents read the summary first and drill down to the full archived spec only when the summary is insufficient. Measured against the existing 22-spec archive: ~94% token reduction when consulting completed-spec history (435-line average full spec → 24-line average summary; ~5.2k → ~0.3k tokens per spec).
+- **`archive summarize <SPEC-ID>` CLI subcommand** in `bin/sf-tools.cjs` — parses an archived spec's frontmatter and `## Goal Analysis` / `## Completion` / `## Delta` sections and writes the `.summary.md` sibling via atomic temp-rename. Falls back to first paragraph of `## Context` for older specs lacking `## Goal Analysis`.
+- **`archive backfill [--force]` CLI subcommand** — iterates `.specflow/archive/SPEC-*.md` and generates missing summaries. Idempotent by default (existing summaries are skipped, zero-diff on second run); `--force` regenerates everything.
+- **`/sf:done` Step 8.5** — automatically generates the L1 summary for every newly archived spec. Non-fatal: summary failure logs a warning but does not abort archival (the full spec is already on disk and `archive backfill` can regenerate later).
+- **Prefer-summary guidance in four agent prompts** — `sf-spec-auditor`, `sf-researcher`, `sf-spec-creator`, and `sf-spec-reviser` now read `<SPEC-ID>.summary.md` first when consulting completed-spec history. Graceful fallback: if no `.summary.md` exists (transitional state during rollout), the agent silently reads the full spec — no error, no warning.
+- `bin/lib/archive-summary.cjs` — pure-Node parser/renderer/generator module (`parseArchivedSpec`, `renderSummary`, `generateSummary`); zero npm dependencies (only `fs`/`path` from stdlib); atomic temp-rename writes consistent with `bin/lib/core.cjs`.
+- `templates/archive-summary.md` — canonical L1 template defining the summary structure; reviewed and stable.
+- `scripts/measure-archive-tokens.cjs` — re-runnable measurement script that scans `.specflow/archive/`, computes average line counts and approximate tokens (lines × ~12 tokens/line), and prints a markdown-formatted ratio report so future contributors can detect regression in the L1 layer's compactness.
+- 11 new tests in `test/archive-summary.test.cjs` covering parser correctness (extracts goal/decisions/keyFiles from fixture specs), older-style spec fallback (no `## Goal Analysis` → goal derived from `## Context`), renderer truncation caps (top 5 decisions, top 6 key files), generator atomic-write behaviour, backfill idempotency, `--force` regeneration, and `archive summarize` error paths.
+
+## [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/researcher.md

@@ -66,6 +66,8 @@ Use Glob and Grep to find:
 - Similar implementations
 - Configuration patterns
 
+**Reading archived specs:** When the research touches completed specs in `.specflow/archive/`, prefer `<SPEC-ID>.summary.md` over `<SPEC-ID>.md`. The summary is 10–15 lines and surfaces the goal, key decisions, and touched files — sufficient for most research queries. Read the full spec only if the summary lacks the specific detail you need. If `.summary.md` does not exist (transitional state during rollout), fall back gracefully to the full spec.
+
 ## Step 4: External Research (if needed)
 
 For topics requiring external knowledge:

package/agents/spec-auditor.md

@@ -136,6 +136,8 @@ Read `.specflow/PROJECT.md` for:
 - Patterns (to check alignment)
 - Constraints (to verify compliance)
 
+**Reading archived specs:** When you need to consult completed specs (e.g., to check pattern compliance or prior decisions), read `.specflow/archive/<SPEC-ID>.summary.md` first. The summary is 10–15 lines and surfaces the goal, key decisions, and touched files. Open the full `<SPEC-ID>.md` only when the summary does not contain the detail you need. If `.summary.md` does not exist (transitional state during rollout), fall back gracefully to the full spec.
+
 ## Step 3: Audit Dimensions
 
 Evaluate each dimension:

package/agents/spec-creator.md

@@ -79,6 +79,8 @@ Read the discussion file (PRE-XXX.md or DISC-XXX.md) to understand:
 - Questions already answered
 - User preferences and constraints
 
+**Reading archived specs:** When making assumptions informed by prior decisions, read `.specflow/archive/<SPEC-ID>.summary.md` rather than the full archived spec. The summary is 10–15 lines and surfaces the goal, key decisions, and touched files. Open the full `<SPEC-ID>.md` only when the summary does not contain the specific detail you need. If `.summary.md` does not exist (transitional state during rollout), fall back gracefully to the full spec.
+
 ## Step 2: Analyze Task
 
 Parse the user's task description:

package/agents/spec-reviser.md

@@ -58,6 +58,8 @@ Read `.specflow/STATE.md` to get:
 
 Read the full specification file.
 
+**Reading archived specs:** When making assumptions informed by prior decisions, read `.specflow/archive/<SPEC-ID>.summary.md` rather than the full archived spec. The summary is 10–15 lines and surfaces the goal, key decisions, and touched files. Open the full `<SPEC-ID>.md` only when the summary does not contain the specific detail you need. If `.summary.md` does not exist (transitional state during rollout), fall back gracefully to the full spec.
+
 ## Step 2: Parse Latest Audit
 
 Find the most recent "Audit v[N]" section in Audit History.
@@ -176,7 +178,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 +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)
 - [ ] Frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes provided

package/bin/lib/archive-summary.cjs

@@ -0,0 +1,508 @@
+/**
+ * bin/lib/archive-summary.cjs — L1 archive summary generator
+ *
+ * Exports:
+ *   parseArchivedSpec(specPath)  → structured summary object
+ *   renderSummary(parsed, templatePath) → markdown string
+ *   generateSummary(specPath, templatePath, outputPath) → { written, reason? }
+ *
+ * No npm dependencies — only fs, path from Node standard library.
+ * Caller is responsible for providing correct paths.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML-style frontmatter from a markdown file.
+ * Matches the simple key: value parsing in bin/lib/core.cjs.
+ * @param {string} content
+ * @returns {{ frontmatter: Object, body: string }}
+ */
+function _parseFrontmatter(content) {
+  if (!content || typeof content !== 'string') {
+    return { frontmatter: {}, body: content || '' };
+  }
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!fmMatch) {
+    return { frontmatter: {}, body: content };
+  }
+  const fm = {};
+  fmMatch[1].split('\n').forEach(line => {
+    const kv = line.match(/^([^:]+):\s*(.*)$/);
+    if (kv) {
+      fm[kv[1].trim()] = kv[2].trim();
+    }
+  });
+  return { frontmatter: fm, body: fmMatch[2] };
+}
+
+/**
+ * Extract a named section's content (between the heading and the next same/higher-level heading).
+ * @param {string} body - Full body text
+ * @param {string} headingText - Exact heading text (without # prefix)
+ * @param {number} level - Heading level (2 = ##, 3 = ###)
+ * @returns {string|null}
+ */
+function _extractSection(body, headingText, level) {
+  const hashes = '#'.repeat(level);
+  // Match the heading line; content follows until the next heading of same or higher level
+  const headingRe = new RegExp(
+    `^${hashes}\\s+${headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+    'm'
+  );
+  const match = body.match(headingRe);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  // Next heading at same level or higher (fewer or equal hashes)
+  const stopRe = new RegExp(`^#{1,${level}}\\s`, 'm');
+  const rest = body.slice(start);
+  const stopMatch = rest.match(stopRe);
+  return stopMatch ? rest.slice(0, stopMatch.index).trim() : rest.trim();
+}
+
+/**
+ * Extract bullet list items from a markdown section string.
+ * Captures lines that start with `- ` (with optional leading spaces).
+ * @param {string} text
+ * @returns {string[]}
+ */
+function _extractBullets(text) {
+  if (!text) return [];
+  return text
+    .split('\n')
+    .filter(l => /^\s*-\s+/.test(l))
+    .map(l => l.replace(/^\s*-\s+/, '').trim())
+    .filter(l => l.length > 0);
+}
+
+/**
+ * Get the first non-empty, non-heading paragraph from a text block.
+ * @param {string} text
+ * @returns {string}
+ */
+function _firstParagraph(text) {
+  if (!text) return '';
+  const lines = text.split('\n');
+  const paragraphLines = [];
+  let inParagraph = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('#')) continue; // skip headings
+    if (trimmed === '') {
+      if (inParagraph) break; // end of first paragraph
+      continue;
+    }
+    inParagraph = true;
+    paragraphLines.push(trimmed);
+  }
+  return paragraphLines.join(' ').trim();
+}
+
+/**
+ * Extract the title from the first # heading in the body.
+ * @param {string} body
+ * @returns {string}
+ */
+function _extractTitle(body) {
+  const m = body.match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : '';
+}
+
+/**
+ * Extract test file references from text.
+ * Matches patterns like test/foo.test.cjs
+ * @param {string} text
+ * @returns {string[]}
+ */
+function _extractTestRefs(text) {
+  if (!text) return [];
+  const matches = text.match(/test\/[^\s,)]+\.test\.cjs/g);
+  if (!matches) return [];
+  return [...new Set(matches)];
+}
+
+/**
+ * Extract the completion date from a Completion section.
+ * Looks for lines like: **Completed:** YYYY-MM-DD
+ * @param {string} completionSection
+ * @returns {string}
+ */
+function _extractCompletedDate(completionSection) {
+  if (!completionSection) return '';
+  const m = completionSection.match(/\*\*Completed:\*\*\s*(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : '';
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an archived spec file and return a structured summary object.
+ *
+ * Field extraction strategy:
+ *  - goal: from ## Goal Analysis > ### Goal Statement; fallback to first paragraph of ## Context
+ *  - decisions: from ## Completion > ### Patterns Established bullets;
+ *               fallback to ## Delta ADDED/MODIFIED bullets (top 5)
+ *  - keyFiles: from ## Completion > ### Key Files bullets; fallback to ## Delta ADDED bullets (top 6)
+ *  - tests: test/*.test.cjs refs found in ### Key Files or elsewhere in ## Completion
+ *  - completed: from ## Completion > **Completed:** date line
+ *  - title: from first # heading
+ *
+ * @param {string} specPath - Absolute path to the archived spec file
+ * @returns {{
+ *   specId: string,
+ *   title: string,
+ *   type: string,
+ *   completed: string,
+ *   goal: string,
+ *   decisions: string[],
+ *   keyFiles: Array<{path: string, purpose: string}>,
+ *   tests: string[]
+ * }}
+ */
+function parseArchivedSpec(specPath) {
+  const content = fs.readFileSync(specPath, 'utf8');
+  const { frontmatter, body } = _parseFrontmatter(content);
+
+  const specId = frontmatter.id || path.basename(specPath, '.md');
+  const type = frontmatter.type || 'feature';
+
+  // Title
+  const title = _extractTitle(body);
+
+  // --- Goal ---
+  let goal = '';
+  const goalAnalysisSection = _extractSection(body, 'Goal Analysis', 2);
+  if (goalAnalysisSection) {
+    const goalStatementSection = _extractSection(goalAnalysisSection, 'Goal Statement', 3);
+    if (goalStatementSection) {
+      goal = _firstParagraph(goalStatementSection);
+    }
+  }
+  if (!goal) {
+    // Fallback: first paragraph of ## Context
+    const contextSection = _extractSection(body, 'Context', 2);
+    goal = _firstParagraph(contextSection || body);
+  }
+  // Trim goal to a single sentence if possible (stop at first period followed by space or end)
+  const sentenceEnd = goal.match(/^([^.!?]+[.!?])/);
+  if (sentenceEnd && sentenceEnd[1].length >= 20) {
+    goal = sentenceEnd[1].trim();
+  }
+
+  // --- Key Decisions ---
+  let decisions = [];
+  const completionSection = _extractSection(body, 'Completion', 2);
+  if (completionSection) {
+    const patternsSection = _extractSection(completionSection, 'Patterns Established', 3);
+    if (patternsSection) {
+      decisions = _extractBullets(patternsSection);
+    }
+  }
+  if (decisions.length === 0) {
+    // Fallback: ADDED/MODIFIED bullets from ## Delta
+    const deltaSection = _extractSection(body, 'Delta', 2);
+    if (deltaSection) {
+      const addedSection = _extractSection(deltaSection, 'ADDED', 3);
+      const modifiedSection = _extractSection(deltaSection, 'MODIFIED', 3);
+      const addedBullets = _extractBullets(addedSection || '');
+      const modifiedBullets = _extractBullets(modifiedSection || '');
+      decisions = [...addedBullets, ...modifiedBullets];
+    }
+  }
+  // Cap at 5
+  decisions = decisions.slice(0, 5);
+
+  // --- Key Files ---
+  let keyFiles = [];
+  if (completionSection) {
+    const keyFilesSection = _extractSection(completionSection, 'Key Files', 3);
+    if (keyFilesSection) {
+      const bullets = _extractBullets(keyFilesSection);
+      keyFiles = bullets.map(b => {
+        // Format: `path/to/file.cjs` — purpose  OR  `path/to/file.cjs` purpose
+        const dashSplit = b.match(/^`?([^\s`]+)`?\s+[—–-]+\s+(.+)$/);
+        if (dashSplit) {
+          return { path: dashSplit[1], purpose: dashSplit[2].trim() };
+        }
+        // Fallback: first token is path, rest is purpose
+        const spaceIdx = b.indexOf(' ');
+        if (spaceIdx > 0) {
+          return { path: b.slice(0, spaceIdx).replace(/`/g, ''), purpose: b.slice(spaceIdx + 1).trim() };
+        }
+        return { path: b.replace(/`/g, ''), purpose: '' };
+      });
+    }
+  }
+  if (keyFiles.length === 0) {
+    // Fallback: ADDED bullets from Delta
+    const deltaSection = _extractSection(body, 'Delta', 2);
+    if (deltaSection) {
+      const addedSection = _extractSection(deltaSection, 'ADDED', 3);
+      const bullets = _extractBullets(addedSection || '');
+      keyFiles = bullets.map(b => {
+        const dashSplit = b.match(/^`?([^\s`]+)`?\s+[—–-]+\s+(.+)$/);
+        if (dashSplit) {
+          return { path: dashSplit[1], purpose: dashSplit[2].trim() };
+        }
+        const spaceIdx = b.indexOf(' ');
+        if (spaceIdx > 0) {
+          return { path: b.slice(0, spaceIdx).replace(/`/g, ''), purpose: b.slice(spaceIdx + 1).trim() };
+        }
+        return { path: b.replace(/`/g, ''), purpose: '' };
+      });
+    }
+  }
+  // Cap at 6
+  keyFiles = keyFiles.slice(0, 6);
+
+  // --- Tests ---
+  let tests = [];
+  if (completionSection) {
+    tests = _extractTestRefs(completionSection);
+  }
+  if (tests.length === 0) {
+    tests = _extractTestRefs(body);
+  }
+
+  // --- Completed date ---
+  const completed = _extractCompletedDate(completionSection || '') ||
+    frontmatter.completed || '';
+
+  return {
+    specId,
+    title,
+    type,
+    completed,
+    goal,
+    decisions,
+    keyFiles,
+    tests,
+  };
+}
+
+/**
+ * Render a summary markdown string from a parsed spec object and a template file.
+ * Substitutes placeholders in the template with actual values.
+ * Truncates decisions to top 5 and keyFiles to top 6 (already enforced by parser,
+ * but re-enforced here for callers who bypass parseArchivedSpec).
+ *
+ * @param {{ specId, title, type, completed, goal, decisions, keyFiles, tests }} parsed
+ * @param {string} templatePath - Absolute path to templates/archive-summary.md
+ * @returns {string} Rendered markdown string
+ */
+function renderSummary(parsed, templatePath) {
+  const template = fs.readFileSync(templatePath, 'utf8');
+
+  const {
+    specId,
+    title,
+    type,
+    completed,
+    goal,
+    decisions,
+    keyFiles,
+    tests,
+  } = parsed;
+
+  // Cap arrays
+  const cappedDecisions = (decisions || []).slice(0, 5);
+  const cappedKeyFiles = (keyFiles || []).slice(0, 6);
+
+  // Build decisions bullet list
+  const decisionsBlock = cappedDecisions.length > 0
+    ? cappedDecisions.map(d => `- ${d}`).join('\n')
+    : '- (none recorded)';
+
+  // Build key files bullet list
+  const keyFilesBlock = cappedKeyFiles.length > 0
+    ? cappedKeyFiles.map(kf => {
+        const p = typeof kf === 'string' ? kf : kf.path;
+        const pu = typeof kf === 'string' ? '' : kf.purpose;
+        return pu ? `- ${p} — ${pu}` : `- ${p}`;
+      }).join('\n')
+    : '- (none recorded)';
+
+  // Tests field
+  const testsField = (tests && tests.length > 0) ? tests.join(', ') : 'none';
+
+  // Substitute all placeholders
+  let output = template
+    // Frontmatter fields (replace globally after first-pass)
+    .replace(/\{SPEC-ID\}/g, specId)
+    .replace('{full title}', title || specId)
+    .replace('{feature|refactor|bugfix}', type || 'feature')
+    .replace('{YYYY-MM-DD}', completed || 'unknown')
+    // Goal
+    .replace('{one-sentence goal extracted from Goal Statement or Context}', goal || '(not extracted)')
+    // Decisions block — replace the 3-line placeholder block
+    .replace(
+      /^- \{decision 1\}\n- \{decision 2\}\n- \{decision 3\}$/m,
+      decisionsBlock
+    )
+    // Key files block — replace the 2-line placeholder block
+    .replace(
+      /^- \{path 1\} — \{one-line purpose\}\n- \{path 2\} — \{one-line purpose\}$/m,
+      keyFilesBlock
+    )
+    // Tests
+    .replace('{test/foo.test.cjs, ...} or "none"', testsField)
+    // Related future specs
+    .replace('{list of SPEC-IDs that reference this, or "none yet"}', 'none yet');
+
+  return output;
+}
+
+/**
+ * Orchestrate parse → render → write for a single spec.
+ * Uses atomic temp-rename pattern consistent with bin/lib/core.cjs.
+ *
+ * @param {string} specPath - Path to source archived spec (.md)
+ * @param {string} templatePath - Path to templates/archive-summary.md
+ * @param {string} outputPath - Destination path for the summary (.summary.md)
+ * @returns {{ written: boolean, reason?: string }}
+ */
+function generateSummary(specPath, templatePath, outputPath) {
+  let parsed;
+  try {
+    parsed = parseArchivedSpec(specPath);
+  } catch (e) {
+    return { written: false, reason: 'parse failed: ' + e.message };
+  }
+
+  let rendered;
+  try {
+    rendered = renderSummary(parsed, templatePath);
+  } catch (e) {
+    return { written: false, reason: 'render failed: ' + e.message };
+  }
+
+  // Atomic temp-rename write
+  const tmpPath = outputPath + '.tmp.' + process.pid;
+  try {
+    fs.writeFileSync(tmpPath, rendered, 'utf8');
+    fs.renameSync(tmpPath, outputPath);
+  } catch (e) {
+    // Clean up temp file if it exists
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    return { written: false, reason: 'write failed: ' + e.message };
+  }
+
+  return { written: true };
+}
+
+// ---------------------------------------------------------------------------
+// CLI command implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * CLI handler for `archive summarize <SPEC-ID>`.
+ * Generates (or regenerates with --force) a .summary.md for one archived spec.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} specId - Spec ID (e.g. "SPEC-011")
+ * @param {{ force?: boolean }} [opts]
+ */
+function cmdArchiveSummarize(cwd, specId, opts) {
+  const { force = false } = opts || {};
+  const archiveDir = path.join(cwd, '.specflow', 'archive');
+  const specPath = path.join(archiveDir, specId + '.md');
+  const outputPath = path.join(archiveDir, specId + '.summary.md');
+  const templatePath = path.join(cwd, 'templates', 'archive-summary.md');
+
+  // Validate spec exists in archive
+  if (!fs.existsSync(specPath)) {
+    process.stderr.write('Error: Spec not found in archive: ' + specPath + '\n');
+    process.exit(1);
+  }
+
+  // Skip if summary already exists and not --force
+  if (!force && fs.existsSync(outputPath)) {
+    process.stdout.write(JSON.stringify({ written: false, reason: 'already exists (use --force to overwrite)', path: outputPath }, null, 2) + '\n');
+    return;
+  }
+
+  const result = generateSummary(specPath, templatePath, outputPath);
+  if (!result.written) {
+    process.stderr.write('Error: Failed to generate summary: ' + result.reason + '\n');
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify({ written: true, path: outputPath }, null, 2) + '\n');
+}
+
+/**
+ * CLI handler for `archive backfill [--force]`.
+ * Generates summary files for all archived specs that lack them.
+ * With --force, regenerates all summaries.
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ force?: boolean }} [opts]
+ */
+function cmdArchiveBackfill(cwd, opts) {
+  const { force = false } = opts || {};
+  const archiveDir = path.join(cwd, '.specflow', 'archive');
+  const templatePath = path.join(cwd, 'templates', 'archive-summary.md');
+
+  let files;
+  try {
+    files = fs.readdirSync(archiveDir);
+  } catch (e) {
+    process.stderr.write('Error: Cannot read archive directory: ' + archiveDir + '\n');
+    process.exit(1);
+  }
+
+  // Identify spec files (SPEC-*.md, not *.summary.md)
+  const specFiles = files
+    .filter(f => f.match(/^SPEC-[A-Z0-9-]+\.md$/) && !f.endsWith('.summary.md'))
+    .sort();
+
+  const results = [];
+  let written = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const file of specFiles) {
+    const specId = file.replace(/\.md$/, '');
+    const specPath = path.join(archiveDir, file);
+    const outputPath = path.join(archiveDir, specId + '.summary.md');
+
+    // Skip if summary exists and not --force
+    if (!force && fs.existsSync(outputPath)) {
+      skipped++;
+      results.push({ specId, written: false, reason: 'already exists' });
+      continue;
+    }
+
+    const result = generateSummary(specPath, templatePath, outputPath);
+    if (result.written) {
+      written++;
+      results.push({ specId, written: true, path: outputPath });
+    } else {
+      failed++;
+      results.push({ specId, written: false, reason: result.reason });
+    }
+  }
+
+  process.stdout.write(JSON.stringify({
+    total: specFiles.length,
+    written,
+    skipped,
+    failed,
+    results,
+  }, null, 2) + '\n');
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = { parseArchivedSpec, renderSummary, generateSummary, cmdArchiveSummarize, cmdArchiveBackfill };

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)
@@ -21,6 +22,8 @@
  *   state remove-active <id>              Remove one row from Active Specifications table
  *   state resolve [id]                    Resolve active spec; emit JSON contract
  *   state migrate                         One-shot idempotent migration to new schema
+ *   archive summarize <SPEC-ID>           Generate L1 summary for one archived spec
+ *   archive backfill [--force]            Generate missing summaries for all archived specs
  *   resolve-model <agent-type>            Model for agent by current profile
  *   verify-structure                      Check .specflow/ integrity
  *   generate-slug <text>                  Text to URL-safe slug
@@ -40,9 +43,10 @@ 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');
+const { cmdArchiveSummarize, cmdArchiveBackfill } = require('./lib/archive-summary.cjs');
 
 const cwd = process.cwd();
 const args = process.argv.slice(2);
@@ -75,6 +79,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)
@@ -112,6 +117,14 @@ const COMMANDS = {
       .catch(e => error(e.message));
   },
 
+  'archive summarize': () => {
+    if (!filteredArgs[2]) error('Missing SPEC-ID. Usage: archive summarize <SPEC-ID>');
+    cmdArchiveSummarize(cwd, filteredArgs[2], { force: flags.force });
+  },
+  'archive backfill': () => {
+    cmdArchiveBackfill(cwd, { force: flags.force });
+  },
+
   'resolve-model':   () => {
     if (!filteredArgs[1]) error('Missing agent type. Usage: resolve-model <agent-type>');
     cmdResolveModel(cwd, filteredArgs[1], raw);
@@ -136,6 +149,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)
@@ -144,6 +158,8 @@ Commands:
   state remove-active <id>               Remove one row (under advisory lock)
   state resolve [SPEC-ID]                Resolve active spec; emit JSON contract
   state migrate                          One-shot idempotent migration to new schema
+  archive summarize <SPEC-ID>            Generate L1 summary for one archived spec
+  archive backfill [--force]             Generate missing summaries for all archived specs
   resolve-model <agent-type>              Resolve model for agent by current profile
   verify-structure                        Check .specflow/ directory integrity
   generate-slug <text>                    Convert text to URL-safe slug

package/commands/sf/done.md

@@ -318,6 +318,16 @@ Move spec to archive:
 mv .specflow/specs/SPEC-XXX.md .specflow/archive/
 ```
 
+## Step 8.5: Generate L1 Summary
+
+Generate a compact summary of the just-archived spec for agent consumption:
+
+    node ~/.claude/specflow-cc/bin/sf-tools.cjs archive summarize SPEC-XXX
+
+On success, `.specflow/archive/SPEC-XXX.summary.md` exists.
+
+If the command fails (parser cannot extract required fields), log a warning to the completion summary but do NOT abort archival — the full spec is already archived and the summary can be regenerated later via `node ~/.claude/specflow-cc/bin/sf-tools.cjs archive backfill`.
+
 ## Step 9: Update STATE.md
 
 ### Remove from Active Specifications Table
@@ -457,6 +467,7 @@ git commit -m "docs(sf): complete SPEC-XXX"
 - [ ] Decisions extracted (if any)
 - [ ] Source TODO file deleted (if `source:` field exists in spec and file exists in todos/)
 - [ ] Spec moved to archive
+- [ ] L1 summary file created at .specflow/archive/SPEC-XXX.summary.md (or warning logged)
 - [ ] STATE.md updated (cleared active, removed from queue)
 - [ ] Final commit created
 - [ ] Clear completion summary shown

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.21.0",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"

package/templates/archive-summary.md

@@ -0,0 +1,25 @@
+---
+spec_id: {SPEC-ID}
+title: {full title}
+type: {feature|refactor|bugfix}
+completed: {YYYY-MM-DD}
+---
+
+# {SPEC-ID} Summary
+
+**Goal:** {one-sentence goal extracted from Goal Statement or Context}
+
+**Key Decisions:**
+- {decision 1}
+- {decision 2}
+- {decision 3}
+
+**Key Files:**
+- {path 1} — {one-line purpose}
+- {path 2} — {one-line purpose}
+
+**Tests:** {test/foo.test.cjs, ...} or "none"
+
+**Full Spec:** [.specflow/archive/{SPEC-ID}.md](./{SPEC-ID}.md)
+
+**Related Future Specs:** none yet

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 |
 |---|-----|-------|----------|--------|---------|