specflow-cc 1.20.1 → 1.21.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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

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.

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/sf-tools.cjs

@@ -22,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
@@ -44,6 +46,7 @@ const { cmdSpecLoad, cmdSpecList, cmdSpecNextId } = require('./lib/spec.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);
@@ -114,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);
@@ -147,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.20.1",
+  "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