specflow-cc 1.20.1 → 1.22.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.22.0] - 2026-05-19
+
+### Added
+
+- **`Recommendation:` line on `/sf:audit` and `/sf:review` output** — after every audit or review, the Next Step block now includes a deterministic `**Recommendation:** {action} — {reason}` line (e.g. `done — implementation is clean, ready to finalize`, `run --apply=minor — 2 non-blocking recommendations, apply inline`, `revise — 1 critical issue blocks execution`). Removes the "what next" guesswork when the result has only non-blocking findings. Emitted by `sf-spec-auditor` and `sf-impl-reviewer` agents via a new Step 7.5 that shells out to `node bin/sf-tools.cjs recommend`. STATE.md's canonical `Next Step` is unchanged — the Recommendation line is advisory in agent output only.
+- **`--apply=minor` flag on `/sf:done` and `/sf:run`** — quick-fix path for non-blocking findings. `/sf:done --apply=minor` (review path): requires spec status `review` with only Minor findings; invokes `/sf:fix --internal` to apply each finding as an atomic commit; runs project test + lint gate; on success, proceeds to standard finalization. `/sf:run --apply=minor` (audit path): requires status `audited` with only Recommendations; invokes `/sf:revise --internal`; runs structural `spec validate` gate; on success, proceeds to standard execution. **No second audit/review cycle is invoked.** Both refuse with a clear error when Critical/Major findings exist. On gate failure: applied commits remain in git, but STATE.md status is unchanged (sole rollback signal).
+- **`recommend` CLI subcommand** in `bin/sf-tools.cjs` — pure mapping module exposed via `node bin/sf-tools.cjs recommend --source <audit|review> --critical N --major N --minor N`. Emits JSON `{action, reason}` to stdout. Single source of truth for the recommendation truth-table consumed by both agents and `--apply=minor` callers.
+- **`spec validate` CLI subcommand** in `bin/sf-tools.cjs` — lightweight structural validation (frontmatter parses, required fields present, `## Requirements` heading present). Exits 0 on success with no stdout; exits 1 with `Error: spec validation failed: {reason}` on stderr. Used by `/sf:run --apply=minor` as the post-revise integrity gate (distinct from content-driven `/sf:audit`).
+- **`--internal` flag on `/sf:fix` and `/sf:revise`** — symmetric guard that suppresses the Step 8 `state add-active` STATE.md mutation. Lets `/sf:done --apply=minor` and `/sf:run --apply=minor` shell out to the existing fix/revise machinery without losing control of the lifecycle transition. Reusable pattern for future composite commands.
+- `bin/lib/recommend.cjs` — pure 57-line `recommend({source, critical, major, minor})` → `{action, reason}` function; no I/O, no state mutation. Zero new runtime npm dependencies — Node.js built-ins only.
+- 39 new tests across `test/recommend.test.cjs` (28 tests: truth-table coverage, CLI integration, error cases) and `test/spec-validate.test.cjs` (11 tests: success + all five failure modes). Full suite: 93/93 pass.
+
+### Fixed
+
+- **Brittle hardcoded-spec test in spec-validate suite** — removed a test that referenced a live `SPEC-013.md` file, which broke the moment SPEC-013 was archived (the normal end of every spec's lifecycle). The success path is fully covered by an adjacent temp-fixture test, so the duplicate was removed rather than rewritten.
+
+## [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/impl-reviewer.md

@@ -283,6 +283,31 @@ Append to specification's Review History:
 **Summary:** {Brief overall assessment}
 ```
 
+## Step 7.5: Emit Recommendation
+
+Using the Critical, Major, and Minor counts determined in Step 5:
+
+1. Shell out to obtain the recommendation:
+   ```
+   node bin/sf-tools.cjs recommend --source review --critical <N> --major <M> --minor <K>
+   ```
+
+2. Parse the JSON response: `{ "action": "...", "reason": "..." }`
+
+3. In the REVIEW RESULT output block (within the "Next Step" section), emit:
+   ```
+   **Recommendation:** {action} — {reason}
+   ```
+
+4. Also append the same line to the Review History entry (in Step 7) below the existing fields:
+   ```
+   **Recommendation:** {action}
+   ```
+
+**Verb mapping per source:** For `source=review`, blocker verb is `fix` (matches STATE.md canonical `/sf:fix`); non-blocker verbs are `done` / `done --apply=minor`. This asymmetry is deliberate: Recommendation verbs align with the existing per-path canonical commands.
+
+**Note:** STATE.md Next Step (Step 8) continues to use the canonical command (`/sf:done`, `/sf:fix`) without any `--apply=minor` suffix. The Recommendation line is advisory and appears only in agent output and review history.
+
 ## Step 8: Update STATE.md
 
 - If APPROVED: Status → "done", Next Step → "/sf:done"
@@ -344,14 +369,21 @@ Output directly as formatted text (not wrapped in a code block):
 ## Next Step
 
 {If APPROVED with NO minor issues:}
+**Recommendation:** {action} — {reason}
+
 `/sf:done` — finalize and archive
 
 {If APPROVED WITH minor issues:}
+**Recommendation:** {action} — {reason}
+
 Choose one:
 • `/sf:done` — finalize as-is (minor issues are optional)
 • `/sf:fix` — address minor issues first
+• `/sf:done --apply=minor` — apply minor fixes inline and finalize in one step
 
 {If CHANGES_REQUESTED:}
+**Recommendation:** {action} — {reason}
+
 `/sf:fix` — address issues
 
 Options:

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:
@@ -768,6 +770,30 @@ N+1. [recommendation]
 **Comment:** [Brief positive note about spec quality]
 ```
 
+## Step 7.5: Emit Recommendation
+
+Using the Critical count and Recommendations count determined in Step 5:
+
+1. Shell out to obtain the recommendation:
+   ```
+   node bin/sf-tools.cjs recommend --source audit --critical <N> --minor <M>
+   ```
+   Note: The CLI flag is `--minor` even though the auditor uses the label "Recommendations" — this is intentional for parser symmetry across audit/review sources.
+
+2. Parse the JSON response: `{ "action": "...", "reason": "..." }`
+
+3. In the AUDIT RESULT output block (within the "Next Step" section), emit:
+   ```
+   **Recommendation:** {action} — {reason}
+   ```
+
+4. Also append the same line to the Audit History entry (in Step 7) below the existing fields:
+   ```
+   **Recommendation:** {action}
+   ```
+
+**Note:** STATE.md Next Step (Step 8) continues to use the canonical command (`/sf:run`, `/sf:revise`, `/sf:split`) without any `--apply=minor` suffix. The Recommendation line is advisory and appears only in agent output and audit history.
+
 ## Step 8: Update STATE.md
 
 Update status:
@@ -824,6 +850,8 @@ Output directly as formatted text (not wrapped in a code block):
 
 ### Next Step
 
+**Recommendation:** {action} — {reason}
+
 Choose one:
 - `/sf:run --parallel` — execute with subagent orchestration
 - `/sf:split` — decompose into smaller specs
@@ -844,6 +872,8 @@ Choose one:
 
 ### Next Step
 
+**Recommendation:** {action} — {reason}
+
 `/sf:revise` — address critical issues
 
 ---
@@ -856,6 +886,8 @@ Choose one:
 
 ### Next Step
 
+**Recommendation:** {action} — {reason}
+
 `/sf:run` — implement specification
 
 Tip: `/clear` recommended — executor needs fresh context for implementation
@@ -875,6 +907,8 @@ N+1. [recommendation]
 
 ### Next Steps
 
+**Recommendation:** {action} — {reason}
+
 Choose one:
 - `/sf:run` — implement specification as-is
 - `/sf:revise` — apply optional recommendations first ({N} items)

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/lib/recommend.cjs

@@ -0,0 +1,57 @@
+/**
+ * bin/lib/recommend.cjs — Pure mapping module for audit/review recommendations.
+ *
+ * Exports: recommend({ source, critical, major, minor }) → { action, reason }
+ *
+ * No I/O, no state mutation, fully unit-testable.
+ */
+
+'use strict';
+
+/**
+ * Map severity counts and source to a recommended action and human-readable reason.
+ *
+ * @param {object} opts
+ * @param {string} opts.source   - 'audit' or 'review'
+ * @param {number} [opts.critical=0] - Number of critical findings
+ * @param {number} [opts.major=0]    - Number of major findings (ignored for source 'audit')
+ * @param {number} [opts.minor=0]    - Number of minor findings / recommendations
+ * @returns {{ action: string, reason: string }}
+ */
+function recommend({ source, critical = 0, major = 0, minor = 0 } = {}) {
+  if (source !== 'audit' && source !== 'review') {
+    throw new Error(`Unknown source: ${source}. Expected 'audit' or 'review'.`);
+  }
+
+  if (
+    !Number.isInteger(critical) || critical < 0 ||
+    !Number.isInteger(major) || major < 0 ||
+    !Number.isInteger(minor) || minor < 0
+  ) {
+    throw new Error('Counts must be non-negative integers.');
+  }
+
+  if (source === 'audit') {
+    if (critical >= 1) {
+      return { action: 'revise', reason: `${critical} critical issue(s) block execution` };
+    }
+    if (minor >= 1) {
+      return { action: 'run --apply=minor', reason: `${minor} non-blocking recommendation(s), apply inline` };
+    }
+    return { action: 'run', reason: 'spec is clean, ready for execution' };
+  }
+
+  // source === 'review'
+  if (critical >= 1) {
+    return { action: 'fix', reason: `${critical} critical finding(s) block finalize` };
+  }
+  if (major >= 1) {
+    return { action: 'fix', reason: `${major} major finding(s) block finalize` };
+  }
+  if (minor >= 1) {
+    return { action: 'done --apply=minor', reason: `${minor} minor finding(s), apply inline before finalize` };
+  }
+  return { action: 'done', reason: 'implementation is clean, ready to finalize' };
+}
+
+module.exports = { recommend };

package/bin/sf-tools.cjs

@@ -9,6 +9,7 @@
  *   spec load <id>                        Parse spec file, return frontmatter + body
  *   spec list                             List all specs
  *   spec next-id                          Next available SPEC-XXX number
+ *   spec validate <id>                    Validate spec frontmatter and required headings
  *   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
@@ -22,6 +23,9 @@
  *   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
+ *   recommend                             Map severity counts to recommended action
  *   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 +48,8 @@ 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 { recommend } = require('./lib/recommend.cjs');
 
 const cwd = process.cwd();
 const args = process.argv.slice(2);
@@ -69,6 +75,49 @@ const COMMANDS = {
   },
   'spec list':       () => cmdSpecList(cwd, raw),
   'spec next-id':    () => cmdSpecNextId(cwd, raw),
+  'spec validate':   () => {
+    const specId = filteredArgs[2];
+    if (!specId) {
+      process.stderr.write('Error: spec validation failed: missing spec ID. Usage: spec validate <SPEC-XXX>\n');
+      process.exit(1);
+    }
+    const { safeReadFile, parseFrontmatter } = require('./lib/core.cjs');
+    const specPath = require('path').join(cwd, '.specflow', 'specs', specId + '.md');
+    const content = safeReadFile(specPath);
+    if (content === null) {
+      process.stderr.write(`Error: spec validation failed: spec file not found at ${specPath}\n`);
+      process.exit(1);
+    }
+    let frontmatter;
+    try {
+      const parsed = parseFrontmatter(content);
+      frontmatter = parsed.frontmatter;
+      if (!frontmatter || typeof frontmatter !== 'object') {
+        throw new Error('invalid frontmatter');
+      }
+    } catch (e) {
+      process.stderr.write('Error: spec validation failed: invalid or missing frontmatter\n');
+      process.exit(1);
+    }
+    // Require ---...--- block to exist (parseFrontmatter returns empty obj if absent)
+    if (!content.match(/^---\r?\n[\s\S]*?\r?\n---/)) {
+      process.stderr.write('Error: spec validation failed: invalid or missing frontmatter\n');
+      process.exit(1);
+    }
+    const required = ['id', 'type', 'status', 'priority'];
+    for (const field of required) {
+      if (!frontmatter[field]) {
+        process.stderr.write(`Error: spec validation failed: missing frontmatter field '${field}'\n`);
+        process.exit(1);
+      }
+    }
+    if (!content.match(/^## Requirements/m)) {
+      process.stderr.write("Error: spec validation failed: missing required heading '## Requirements'\n");
+      process.exit(1);
+    }
+    // Success: no stdout, exit 0
+    process.exit(0);
+  },
   'todo load':       () => {
     if (!filteredArgs[2]) error('Missing TODO ID. Usage: todo load <id>');
     cmdTodoLoad(cwd, filteredArgs[2], raw);
@@ -114,6 +163,66 @@ 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 });
+  },
+
+  'recommend':       () => {
+    // Parse --source, --critical, --major, --minor from filteredArgs
+    // Flags take the form: --source audit  or  --critical 2  etc.
+    const flagValues = {};
+    for (let i = 1; i < filteredArgs.length; i++) {
+      const a = filteredArgs[i];
+      if (a.startsWith('--')) {
+        const key = a.slice(2);
+        const val = filteredArgs[i + 1];
+        if (val !== undefined && !val.startsWith('--')) {
+          flagValues[key] = val;
+          i++; // skip value token
+        } else {
+          flagValues[key] = true;
+        }
+      }
+    }
+
+    const source = flagValues['source'];
+    if (!source || source === true) {
+      process.stderr.write('Error: --source is required (audit|review)\n');
+      process.exit(1);
+    }
+
+    // Parse integer counts with validation
+    function parseCount(flagName) {
+      const raw = flagValues[flagName];
+      if (raw === undefined || raw === true) return 0;
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 0) {
+        process.stderr.write(`Error: --${flagName} must be a non-negative integer\n`);
+        process.exit(1);
+      }
+      return n;
+    }
+
+    const critical = parseCount('critical');
+    const major = parseCount('major');
+    const minor = parseCount('minor');
+
+    let result;
+    try {
+      result = recommend({ source, critical, major, minor });
+    } catch (e) {
+      process.stderr.write('Error: ' + e.message + '\n');
+      process.exit(1);
+    }
+
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(0);
+  },
+
   'resolve-model':   () => {
     if (!filteredArgs[1]) error('Missing agent type. Usage: resolve-model <agent-type>');
     cmdResolveModel(cwd, filteredArgs[1], raw);
@@ -134,6 +243,7 @@ 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
+  spec validate <id>                      Validate spec frontmatter and required headings
   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
@@ -147,6 +257,9 @@ 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
+  recommend                              Map severity counts to recommended action
   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/audit.md

@@ -290,6 +290,8 @@ After the agent updates STATE.md, check if rotation is needed:
 
 ## Next Step
 
+**Recommendation:** run — spec is clean, ready for execution
+
 `/sf:run` — implement specification
 
 Tip: `/clear` recommended — executor needs fresh context for implementation
@@ -297,6 +299,8 @@ Tip: `/clear` recommended — executor needs fresh context for implementation
 
 ### If APPROVED (with optional recommendations):
 
+The `Recommendation:` line is emitted by the auditor agent (Step 7.5 in `agents/spec-auditor.md`) using `node bin/sf-tools.cjs recommend --source audit --critical 0 --minor N`. The STATE.md Next Step remains `/sf:run` (without the `--apply=minor` suffix) — the suffix is advisory here only.
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AUDIT PASSED
@@ -318,8 +322,11 @@ Tip: `/clear` recommended — executor needs fresh context for implementation
 
 ## Next Step
 
+**Recommendation:** run --apply=minor — {N} non-blocking recommendation(s), apply inline
+
 Choose one:
 • `/sf:run` — implement specification as-is
+• `/sf:run --apply=minor` — apply recommendations inline then execute
 • `/sf:revise` — apply optional recommendations first ({N} items)
 
 Tip: `/clear` recommended before `/sf:run` — executor needs fresh context
@@ -352,6 +359,8 @@ Tip: `/clear` recommended before `/sf:run` — executor needs fresh context
 
 ## Next Step
 
+**Recommendation:** revise — {N} critical issue(s) block execution
+
 `/sf:revise` — address critical issues
 
 Options:

package/commands/sf/done.md

@@ -59,6 +59,87 @@ Parse the JSON response:
   Options: {id — title (status)} for each entry
   ```
 
+## Step 2.5: Handle `--apply=minor` Flag
+
+**Check if `--apply=minor` was passed in the invocation arguments.**
+
+**If `--apply=minor` is NOT present:** Continue to Step 3 (existing behavior unchanged).
+
+**If `--apply=minor` IS present:**
+
+### 2.5.a Verify Status Precondition
+
+Confirm the resolved spec has `status == "review"` in its frontmatter.
+
+If status is NOT `review`:
+```
+Error: --apply=minor requires status 'review' (current: {status})
+```
+Exit 1. No state mutation.
+
+### 2.5.b Parse Severity Counts from Latest Review History
+
+Read the spec file and find the most recent `### Review v[N]` entry in Review History.
+
+Extract Critical, Major, and Minor counts from that entry.
+
+Run:
+```bash
+node bin/sf-tools.cjs recommend --source review --critical N --major M --minor K
+```
+
+Parse the JSON response.
+
+If `action != "done --apply=minor"`:
+```
+Error: --apply=minor cannot be used when Critical or Major findings exist (found {N} Critical, {M} Major). Run /sf:fix instead.
+```
+Exit 1. No state mutation.
+
+### 2.5.c Apply Minor Fixes via `/sf:fix` Machinery
+
+Parse the latest Review History entry and extract the numbered list of Minor findings (the sequential numbers as they appear in the Minor section, e.g. `"4,5,7"`).
+
+Invoke existing `/sf:fix` machinery passing the numbered target list and `--internal` flag (so `/sf:fix` Step 8 does NOT mutate STATE.md — the caller owns the status transition):
+```
+/sf:fix SPEC-XXX "{N,M,K}" --internal
+```
+
+This reuses `/sf:fix`'s existing per-fix atomic commit behavior. Do NOT duplicate fix logic.
+
+### 2.5.d Test Gate
+
+Detect and run the project test command:
+
+1. If `package.json` exists and has `scripts.test` → run `npm test`
+2. Else if `test/` directory exists → run `node --test test/`
+3. Else → note `No test command detected; proceeding without test gate.`
+
+If test command exits non-zero:
+- Print captured stdout+stderr
+- Leave STATE.md status as `review` (no transition)
+- Exit 1
+- Note: Fix commits remain in git history; user can manually `git revert` or run full `/sf:fix` cycle.
+
+### 2.5.e Lint Gate
+
+Detect and run lint:
+
+1. If `package.json` exists and has `scripts.lint` → run `npm run lint`
+2. Else if `.eslintrc*` or `eslint.config.*` present → run `npx eslint .`
+3. Else → skip silently
+
+If lint exits non-zero:
+- Same abort semantics as 2.5.d (print output, leave STATUS as `review`, exit 1)
+
+### 2.5.f On Gate Success: Continue to Finalization
+
+On all gates passing: continue into existing Step 3+ finalization path (update spec frontmatter status → "done", archive, generate L1 summary per SPEC-012).
+
+All STATE.md mutations use Read+Write per SPEC-004 (not Bash/awk/sed).
+
+---
+
 ## Step 3: Load Specification
 
 Read the active spec file: `.specflow/specs/SPEC-XXX.md`
@@ -318,6 +399,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 +548,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/fix.md

@@ -15,6 +15,8 @@ allowed-tools:
 
 <purpose>
 Fix the implementation based on review feedback. Can apply all fixes, specific numbered items, or custom fixes described by user. Creates atomic commits for each fix.
+
+Accepts an `--internal` flag: when present, Step 8 (STATE.md mutation) is suppressed. Used by `/sf:done --apply=minor` to apply minor fixes inline without advancing the spec lifecycle status prematurely.
 </purpose>
 
 <context>
@@ -175,6 +177,10 @@ Append to Review History:
 
 ## Step 8: Update STATE.md
 
+**If `--internal` flag was passed:** SKIP this step entirely. Do NOT mutate STATE.md or spec frontmatter status. The caller (`/sf:done --apply=minor`) owns the status transition and needs the status to remain `review` until its test+lint gate passes.
+
+**If `--internal` is NOT set (normal invocation):**
+
 ```bash
 node bin/sf-tools.cjs state add-active SPEC-XXX review /sf:review
 ```

package/commands/sf/review.md

@@ -158,6 +158,8 @@ After the agent updates STATE.md, check if rotation is needed:
 
 ### If APPROVED (no minor issues):
 
+The `Recommendation:` line is emitted by the reviewer agent (Step 7.5 in `agents/impl-reviewer.md`) using `node bin/sf-tools.cjs recommend --source review --critical 0 --major 0 --minor 0`. The STATE.md Next Step remains `/sf:done` (canonical).
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  REVIEW PASSED
@@ -185,11 +187,15 @@ After the agent updates STATE.md, check if rotation is needed:
 
 ## Next Step
 
+**Recommendation:** done — implementation is clean, ready to finalize
+
 `/sf:done` — finalize and archive specification
 ```
 
 ### If APPROVED (with minor suggestions):
 
+The `Recommendation:` line uses action `done --apply=minor` when only Minor findings exist. STATE.md Next Step stays `/sf:done` (canonical; the `--apply=minor` suffix is advisory here only).
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  REVIEW PASSED
@@ -218,13 +224,18 @@ After the agent updates STATE.md, check if rotation is needed:
 
 ## Next Step
 
+**Recommendation:** done --apply=minor — {N} minor finding(s), apply inline before finalize
+
 Choose one:
 • `/sf:done` — finalize and archive as-is
-• `/sf:fix` — apply minor suggestions first ({N} items)
+• `/sf:done --apply=minor` — apply minor fixes inline and finalize in one step
+• `/sf:fix` — apply minor suggestions first ({N} items) then finalize
 ```
 
 ### If CHANGES_REQUESTED:
 
+The `Recommendation:` line uses action `fix` when Critical or Major findings exist (STATE.md Next Step is `/sf:fix`).
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  REVIEW: CHANGES REQUESTED
@@ -262,6 +273,8 @@ Choose one:
 
 ## Next Step
 
+**Recommendation:** fix — {N} critical/major finding(s) block finalize
+
 `/sf:fix` — address the issues
 
 Options:

package/commands/sf/revise.md

@@ -14,6 +14,8 @@ allowed-tools:
 
 <purpose>
 Revise the active specification based on audit feedback. Can apply all comments, specific numbered items, or custom changes described by user.
+
+Accepts an `--internal` flag: when present, Step 8 STATE.md mutation (status → `auditing`, Next Step → `/sf:audit`) is suppressed. Used by `/sf:run --apply=minor` to apply Recommendations inline without advancing the spec lifecycle status prematurely.
 </purpose>
 
 <context>
@@ -330,7 +332,9 @@ Apply the specified changes and record the revision response.
 
 ## Step 8: Handle Agent Response
 
-The agent will:
+**If `--internal` flag was passed:** The agent applies revisions and records Response v[N] in Audit History, but DOES NOT update status to "auditing" and DOES NOT update STATE.md. Return to caller after revisions are applied.
+
+**If `--internal` is NOT set (normal invocation),** the agent will:
 1. Parse the latest audit
 2. Apply requested revisions
 3. Record Response v[N] in Audit History
@@ -520,6 +524,10 @@ After recording the Response, if any items were marked "Deferred":
 
 ### Update Status
 
+**If `--internal` flag was passed:** SKIP this step entirely. Do NOT mutate STATE.md or spec frontmatter status. The caller (`/sf:run --apply=minor`) owns the status transition and needs the status to remain `audited` until its structural-validate gate passes.
+
+**If `--internal` is NOT set (normal invocation):**
+
 In spec frontmatter: `status: auditing`
 
 In STATE.md:

package/commands/sf/run.md

@@ -66,6 +66,77 @@ Parse the JSON response:
 
 Read the active spec file: `.specflow/specs/SPEC-XXX.md`
 
+## Step 3.5: Handle `--apply=minor` Flag
+
+**Check if `--apply=minor` was passed in the invocation arguments.**
+
+**If `--apply=minor` is NOT present:** Continue to Step 4 (existing behavior unchanged).
+
+**If `--apply=minor` IS present:**
+
+### 3.5.a Verify Status Precondition
+
+Confirm the resolved spec has `status == "audited"` in its frontmatter.
+
+If status is NOT `audited`:
+```
+Error: --apply=minor requires status 'audited' (current: {status})
+```
+Exit 1. No state mutation.
+
+### 3.5.b Parse Severity Counts from Latest Audit History
+
+Read the spec file and find the most recent `### Audit v[N]` entry in Audit History.
+
+Extract Critical count and Recommendations count from that entry. Map Recommendations count to `--minor` (per R2 CLI contract).
+
+Run:
+```bash
+node bin/sf-tools.cjs recommend --source audit --critical N --minor M
+```
+
+Parse the JSON response.
+
+If `action != "run --apply=minor"`:
+```
+Error: --apply=minor requires only Recommendations (found {N} Critical). Run /sf:revise instead.
+```
+Exit 1. No state mutation.
+
+### 3.5.c Apply Recommendations via `/sf:revise` Machinery
+
+Parse the latest Audit History Recommendations list and extract numbered items as a comma-separated string (e.g. `"2,3,5"` — the sequence numbers as they appear in the Recommendations section).
+
+Invoke existing `/sf:revise` machinery passing the numbered target list and `--internal` flag (so `/sf:revise` Step 8 does NOT mutate STATE.md — the caller owns the status transition; status must remain `audited` until the structural-validate gate passes):
+```
+/sf:revise SPEC-XXX "{N,M,K}" --internal
+```
+
+This reuses `/sf:revise`'s existing per-item commit behavior. Do NOT duplicate revise logic.
+
+### 3.5.d Structural Validation Gate
+
+Run spec structural validation:
+```bash
+node bin/sf-tools.cjs spec validate SPEC-XXX
+```
+
+This is the exact gate specified in R2.5: verifies frontmatter parses, required fields present (`id`, `type`, `status`, `priority`), and `## Requirements` heading present. No fallback path.
+
+If `spec validate` exits non-zero:
+- Print error output
+- Leave STATE.md status as `audited` (no transition)
+- Exit 1
+- Note: Revise commits remain in git history; user can manually `git revert` or run full `/sf:revise` cycle. STATE.md status is the sole rollback signal.
+
+### 3.5.e On Gate Success: Continue to Execution
+
+On validation passing: skip Steps 4–7 (audit status check, mode determination, pre-execution summary, model profile, status update) and proceed directly to Step 8 (Spawn Executor Agent) with mode="orchestrated" (or "single" based on the spec's Implementation Tasks section — same logic as Step 4.5).
+
+All STATE.md mutations use Read+Write per SPEC-004 (not Bash/awk/sed).
+
+---
+
 ## Step 4: Check Audit Status
 
 **If status is "audited":**

package/package.json

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