specflow-cc 1.21.0 → 1.22.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.1] - 2026-05-20
+
+### Fixed
+
+- `todo next-id` now scans `.specflow/specs/` and `.specflow/archive/` for `source: TODO-XXX` frontmatter entries, preventing reissue of retired IDs. Previously, a TODO file deleted during promotion to a spec could have its ID reassigned to an unrelated new TODO, leaving downstream `/sf:plan` unable to operate on the new TODO (it rejects the ID as "already promoted").
+
+## [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

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/spec-auditor.md

@@ -770,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:
@@ -826,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
@@ -846,6 +872,8 @@ Choose one:
 
 ### Next Step
 
+**Recommendation:** {action} — {reason}
+
 `/sf:revise` — address critical issues
 
 ---
@@ -858,6 +886,8 @@ Choose one:
 
 ### Next Step
 
+**Recommendation:** {action} — {reason}
+
 `/sf:run` — implement specification
 
 Tip: `/clear` recommended — executor needs fresh context for implementation
@@ -877,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/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/lib/todo.cjs

@@ -183,6 +183,8 @@ function cmdTodoList(cwd, raw, { showAll } = {}) {
  * Scans:
  * 1. .specflow/todos/TODO-*.md filenames using fs.readdirSync() + JS regex
  * 2. .specflow/todos/TODO.md for legacy IDs using fs.readFileSync() + /TODO-(\d+)/g
+ * 3. .specflow/specs/*.md and .specflow/archive/*.md for `source: TODO-XXX`
+ *    frontmatter entries (retired IDs from promoted TODOs).
  *
  * NOTE: Does NOT use grep -oP (GNU-only, unavailable on macOS).
  *
@@ -222,6 +224,31 @@ function cmdTodoNextId(cwd, raw) {
     // file may not exist — skip
   }
 
+  // Scan promoted-spec frontmatter for retired TODO IDs.
+  // On promotion, the source TODO file is deleted; the only surviving
+  // record is `source: TODO-XXX` in the spec's frontmatter. Without this
+  // scan, next-id can reissue a retired ID and downstream `/sf:plan` will
+  // reject the new TODO because the archive still records the old promotion.
+  for (const sub of ['specs', 'archive']) {
+    const dir = path.join(cwd, '.specflow', sub);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch (e) { continue; }
+    for (const file of files) {
+      let content;
+      try {
+        content = fs.readFileSync(path.join(dir, file), 'utf8');
+      } catch (e) { continue; }
+      const regex = /(?:^|\n)source:\s*TODO-(\d+)/g;
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) maxNum = num;
+      }
+    }
+  }
+
   const nextNumber = maxNum + 1;
   const nextId = 'TODO-' + String(nextNumber).padStart(3, '0');
 

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
@@ -24,6 +25,7 @@
  *   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
@@ -47,6 +49,7 @@ const { cmdTodoLoad, cmdTodoList, cmdTodoNextId, cmdTodoReindex, cmdTodoCheckSta
 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);
@@ -72,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);
@@ -125,6 +171,58 @@ const COMMANDS = {
     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);
@@ -145,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
@@ -160,6 +259,7 @@ Commands:
   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`

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