peaks-cli 1.3.6 → 1.3.8

package/dist/src/services/slice/slice-check-service.js

@@ -69,16 +69,27 @@ function parseVitestSummary(stdout, fallbackDuration) {
         durationMs: durationMatch ? Math.round(parseFloat(durationMatch[1]) * 1000) : fallbackDuration
     };
 }
-async function runUnitTests(projectRoot) {
+async function runUnitTests(projectRoot, runTests) {
     const start = Date.now();
-    const result = runCommand('npx', ['vitest', 'run', '--reporter=default', '--coverage=false'], projectRoot, 600_000);
+    // Default: changed-only suite (`vitest run --changed`) — runs only tests
+    // related to git-changed files. Cost drops from 30s+ to ~1-3s in steady
+    // state. Opt-in to the full suite via `runTests: true` (CLI flag
+    // `--run-tests`). See `references/runbook.md` for the rationale and
+    // `tests/unit/slice-check-service.test.ts` for the regression net.
+    const args = runTests
+        ? ['vitest', 'run', '--reporter=default', '--coverage=false']
+        : ['vitest', 'run', '--changed', '--reporter=default', '--coverage=false'];
+    const description = runTests
+        ? 'npx vitest run (full test suite, coverage off)'
+        : 'npx vitest run --changed (tests for git-changed files only, coverage off)';
+    const result = runCommand('npx', args, projectRoot, 600_000);
     const summary = parseVitestSummary(result.stdout, result.durationMs);
     // Vitest doesn't always print the per-bucket counts cleanly; infer "passed"
     // as total - failed - skipped when failed/skipped buckets are present.
     const passed = Math.max(summary.tests - summary.failed - summary.skipped, 0);
     return {
         name: 'unit-tests',
-        description: 'npx vitest run (full test suite, coverage off)',
+        description,
         status: result.status,
         durationMs: result.durationMs,
         detail: result.status === 'pass'
@@ -89,6 +100,7 @@ async function runUnitTests(projectRoot) {
             passed,
             failed: summary.failed,
             skipped: summary.skipped,
+            mode: runTests ? 'full' : 'changed',
             exitCode: result.exitCode
         }
     };
@@ -206,40 +218,45 @@ export async function sliceCheck(options) {
     }
     const totalStart = Date.now();
     const stages = [];
+    let unitTestsRunMode = 'skipped';
     // Stage 1: typecheck
     stages.push(await runTypecheck(options.projectRoot));
-    // Stage 2: full vitest
-    if (!options.skipTests) {
-        const unitTests = await runUnitTests(options.projectRoot);
-        // Opt-in override: if --allow-pre-existing-failures is set AND the
+    // Stage 2: unit-tests — by default changed-only suite, opt-in to full
+    if (options.skipTests) {
+        stages.push({
+            name: 'unit-tests',
+            description: 'npx vitest run (skipped per --skip-tests)',
+            status: 'skipped',
+            durationMs: 0,
+            detail: 'Skipped: --skip-tests was set. Use the peaks-solo-test skill to run the full suite manually.'
+        });
+        unitTestsRunMode = 'skipped';
+    }
+    else {
+        const unitTests = await runUnitTests(options.projectRoot, options.runTests === true);
         // unit-test stage failed, downgrade `failed` to `skipped` with a
         // reason that names the failure count and points to the long-term
-        // fix. Does NOT affect the other 3 stages.
+        // fix. Does NOT affect the other 3 stages. Only meaningful when
+        // the stage actually runs (skipped-tests bypass short-circuits
+        // above).
         if (options.allowPreExistingFailures === true &&
             unitTests.status === 'fail') {
             const failureCount = unitTests.data?.failed ?? 0;
             stages.push({
                 name: 'unit-tests',
-                description: 'npx vitest run (overridden via --allow-pre-existing-failures)',
+                description: `npx vitest run ${options.runTests === true ? '' : '--changed '} (overridden via --allow-pre-existing-failures)`.trim(),
                 status: 'skipped',
                 durationMs: unitTests.durationMs,
                 detail: `pre-existing failures: ${failureCount} failing test(s) under coverage.exclude or unrelated to this slice; user opted in via --allow-pre-existing-failures. For the long-term fix, mark these tests .skip or move to coverage.exclude (see dogfood-2-f1-f4.md F17c).`,
                 data: { ...(unitTests.data ?? {}), overriddenFrom: 'fail', failureCount }
             });
+            unitTestsRunMode = 'overridden';
         }
         else {
             stages.push(unitTests);
+            unitTestsRunMode = options.runTests === true ? 'full' : 'changed';
         }
     }
-    else {
-        stages.push({
-            name: 'unit-tests',
-            description: 'npx vitest run (skipped per --skip-tests)',
-            status: 'skipped',
-            durationMs: 0,
-            detail: 'Skipped: --skip-tests was set.'
-        });
-    }
     // Stage 3: 3-way review fanout check
     stages.push(await runReviewFanout(options.projectRoot, rid, options.refreshFanout));
     // Stage 4: gate verify-pipeline
@@ -260,6 +277,7 @@ export async function sliceCheck(options) {
         projectRoot: options.projectRoot,
         rid,
         stages,
+        unitTestsRunMode,
         boundaryReady,
         totalDurationMs: Date.now() - totalStart,
         nextActions

package/dist/src/services/slice/slice-check-types.d.ts

@@ -7,13 +7,23 @@
  * off to peaks-qa:
  *
  *   1. typecheck (`npx tsc --noEmit`)
- *   2. unit tests (`npx vitest run`)
+ *   2. unit tests — by default the **changed-only** suite
+ *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
+ *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      entirely (e.g. docs-only or config-only slices).
  *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
  *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
  *
  * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
  * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
  * This command is for the BOUNDARY, not the inner loop.
+ *
+ * The unit-test stage emits a `unitTestsRunMode` field on the result
+ * envelope so downstream tooling and the QA test-report can record
+ * which mode actually ran: `"changed"` (default), `"full"` (with
+ * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
+ * (with `--allow-pre-existing-failures` when the run failed and the
+ * stage was downgraded to `skipped` with a reason).
  */
 export type SliceCheckStageStatus = 'pass' | 'fail' | 'skipped';
 export type SliceCheckStage = {
@@ -36,6 +46,15 @@ export type SliceCheckResult = {
     rid: string | null;
     /** All stages in execution order. */
     stages: SliceCheckStage[];
+    /**
+     * Which unit-test mode actually ran. One of:
+     * - `"changed"` — default: `npx vitest run --changed` (tests for git-changed files only)
+     * - `"full"` — opt-in via `--run-tests`: `npx vitest run` (full suite)
+     * - `"skipped"` — opt-in via `--skip-tests` (stage not executed)
+     * - `"overridden"` — full mode + `--allow-pre-existing-failures` and the run failed;
+     *   stage downgraded to `skipped` with the pre-existing-failure reason
+     */
+    unitTestsRunMode: 'changed' | 'full' | 'skipped' | 'overridden';
     /** True iff every stage passed (or was skipped) and the boundary is OK to hand off. */
     boundaryReady: boolean;
     /** Total wall-clock duration in ms. */
@@ -54,17 +73,32 @@ export type SliceCheckOptions = {
      */
     refreshFanout: boolean;
     /**
-     * When true, skip the unit-test stage. Useful when a slice has no unit
-     * tests (e.g. a docs-only or config-only slice).
+     * When true, run the **full** `npx vitest run` suite at the boundary.
+     * When false (the default), run the **changed-only** suite
+     * (`npx vitest run --changed`) which only exercises tests related to
+     * git-changed files. The changed-only mode is the new default as of
+     * run 017 — full suite costs 30s+ on this repo; the changed-only
+     * mode costs ~1-3s in steady state and is what catches the
+     * regressions that actually matter. The service treats `undefined`
+     * the same as `false`.
+     */
+    runTests?: boolean;
+    /**
+     * When true, skip the unit-test stage entirely. Useful when a slice
+     * has no test surface (e.g. a docs-only or config-only slice), or
+     * when the user wants a "typecheck + review + gate" boundary check
+     * without any test execution.
      */
     skipTests: boolean;
     /**
      * When true, an `unit-tests` stage that fails is reported as `skipped`
      * (with a `reason` naming the pre-existing failure count) instead of
      * `failed`. Used to opt in to bypassing the 28 pre-existing Windows
-     * test failures documented in dogfood-2-f1-f4.md F17. Does NOT affect
-     * the other 3 stages (typecheck / review-fanout / gate-verify-pipeline).
-     * Default: false. The service treats `undefined` the same as `false`.
+     * test failures documented in dogfood-2-f1-f4.md F17. Only meaningful
+     * when the unit-test stage actually runs (i.e. not when `skipTests`
+     * is true). Does NOT affect the other 3 stages (typecheck /
+     * review-fanout / gate-verify-pipeline). Default: false. The service
+     * treats `undefined` the same as `false`.
      */
     allowPreExistingFailures?: boolean;
 };

package/dist/src/services/slice/slice-check-types.js

@@ -7,12 +7,22 @@
  * off to peaks-qa:
  *
  *   1. typecheck (`npx tsc --noEmit`)
- *   2. unit tests (`npx vitest run`)
+ *   2. unit tests — by default the **changed-only** suite
+ *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
+ *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      entirely (e.g. docs-only or config-only slices).
  *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
  *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
  *
  * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
  * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
  * This command is for the BOUNDARY, not the inner loop.
+ *
+ * The unit-test stage emits a `unitTestsRunMode` field on the result
+ * envelope so downstream tooling and the QA test-report can record
+ * which mode actually ran: `"changed"` (default), `"full"` (with
+ * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
+ * (with `--allow-pre-existing-failures` when the run failed and the
+ * stage was downgraded to `skipped` with a reason).
  */
 export {};

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.6";
+export declare const CLI_VERSION = "1.3.8";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.6";
+export const CLI_VERSION = "1.3.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-qa/SKILL.md

@@ -356,7 +356,10 @@ ls .peaks/<changeId>/qa/test-cases/<rid>.md
 ```bash
 # Run the project's test command. Do NOT skip this. Writing test cases is not enough.
 # Example (adapt to project):
-npx vitest run --reporter=verbose 2>&1 | tail -30
+# QA validation defaults to the CHANGED-ONLY suite (matches `peaks slice check` default as of run 017).
+# Use the full suite only when the slice is structurally significant or when the user explicitly asks
+# for it (e.g. via /peaks-solo-test or `peaks slice check --run-tests`).
+npx vitest run --changed --reporter=verbose 2>&1 | tail -30
 # Expected: exit code 0, actual test output with pass/fail counts
 # "0 tests executed" or "no test files found" → BLOCKED. Tests were written but not run.
 # Record the raw test output and link it in the test report.
@@ -504,7 +507,7 @@ QA must generate test cases, not merely inspect existing ones. Every QA invocati
 
 **Acceptance linkage (MANDATORY)** — every test case MUST have an `**Acceptance:**` field that references one or more acceptance items from the PRD by their position-based IDs (A1 = first bullet, A2 = second, …). The `peaks scan acceptance-coverage --rid <rid> --project <repo>` command parses both the PRD and this file, builds the coverage map, and fails the QA `verdict-issued` gate if any acceptance item has zero linked test cases. Test cases that genuinely have no acceptance owner (e.g. defense-in-depth regressions) should still include `- **Acceptance:** —` and explain in the **Evidence** field; the coverage report flags these as `unlinkedTestCases` for review without auto-blocking.
 
-**Test-case execution**: Run the project's test command and record results against each generated test case. If the project uses Jest, run `npx jest --coverage` and link the coverage report. If the project uses Vitest, run `npx vitest run --coverage`. Record the coverage percentage for changed files in the test report.
+**Test-case execution**: Run the project's test command and record results against each generated test case. If the project uses Jest, run `npx jest --coverage` and link the coverage report. If the project uses Vitest, run `npx vitest run --changed --coverage` by default (matches the new `peaks slice check` default as of run 017); use the full suite `npx vitest run --coverage` only when the slice warrants a deeper regression check, or when invoked via /peaks-solo-test or `peaks slice check --run-tests`. Record the coverage percentage for changed files in the test report.
 
 ## Mandatory test-report output
 

package/skills/peaks-rd/SKILL.md

@@ -266,7 +266,7 @@ peaks codegraph affected --project <repo> <changed-files...> --json
 #     Without project rules, security review and code review triggers won't fire.
 
 # 7. AFTER implementation, BEFORE QA handoff — RUN THESE GATES:
-#    Peaks-Cli Gate B2: unit tests exist and pass → npx vitest run (or project equivalent)
+#    Peaks-Cli Gate B2: unit tests exist and pass for the changed surface → npx vitest run --changed (or project equivalent; the changed-only mode is the peaks slice check default as of run 017; use --run-tests for the full suite, or invoke /peaks-solo-test to run the full suite standalone)
 #    Peaks-Cli Gate B3: code review evidence → .peaks/<changeId>/rd/code-review.md
 #    Peaks-Cli Gate B4: security review evidence → .peaks/<changeId>/rd/security-review.md
 #    Peaks-Cli Gate B5 (NEW): RD artifact body has no unfilled placeholders.
@@ -295,141 +295,26 @@ For refactor work, the coverage ≥ 95% gate in `Refactor hard gates` still appl
 
 You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file" or any command returns empty, the phase is incomplete.
 
-> **CLI enforcement (NEW)**: the gates below are now ALSO enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. The exact required files depend on the request type chosen at `peaks request init --type <feature|bugfix|refactor|docs|config|chore>` (default `feature`):
->
-> | Type | rd:implemented requires | rd:qa-handoff also requires |
-> |---|---|---|
-> | feature / refactor | `rd/tech-doc.md` | `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` (filled Results table, or `N/A — no perf surface` in Notes) + **`qa/test-cases/<rid>.md`** (added in slice 004; pre-drafted by the 4th sub-agent in the parallel fan-out) |
-> | bugfix | `rd/bug-analysis.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review.md` + `rd/security-review.md` + **`qa/test-cases/<rid>.md`**; `rd/perf-baseline.md` only when the bug is performance-shaped (matches the L449-452 "When this applies" criteria) |
-> | config | (none) | `rd/security-review.md` only |
-> | docs / chore | (none) | (none) |
->
-> The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions; the bypass is recorded in the artifact transition note.
-
-**Peaks-Cli Gate A — After project-scan read (before any implementation):**
-```bash
-ls .peaks/<changeId>/rd/project-scan.md
-# Expected output: .peaks/<changeId>/rd/project-scan.md
-# "No such file" → STOP, create the project-scan first. Do not write code.
-```
-
-**Peaks-Cli Gate A2 — Before tech-doc write: project structure verified (PATH CORRECTNESS — CRITICAL):**
-```bash
-# Verify EVERY file path and directory in the tech-doc exists in the actual project.
-# Do not assume paths. Do not guess directory structures. Open the files and verify.
-# Example verification (adapt paths to the actual tech-doc):
-ls <every-single-directory-path-in-tech-doc> 2>&1 | grep -c "No such file"
-# Expected: 0 (zero "No such file" errors)
-# Any "No such file" → WRONG PATH. Fix the tech-doc BEFORE writing another word.
-# This gate exists because a tech-doc with wrong paths wastes QA time,
-# breaks the implementation, and forces the user to correct the engineer.
-```
-
-**Peaks-Cli Gate A3 — Before implementation: project standards files exist (CLAUDE.md + .claude/rules/):**
-```bash
-ls CLAUDE.md .claude/rules/common/coding-style.md .claude/rules/common/code-review.md .claude/rules/common/security.md 2>&1 | grep -c "No such file"
-# Expected: 0 (all four files exist)
-# Any missing → BLOCKED. Run `peaks standards init --project .` to generate them FIRST.
-# Do not write a single line of implementation code without standards files in place.
-# Without CLAUDE.md and .claude/rules/, code review and security review triggers won't fire.
-```
-
-**Peaks-Cli Gate B — Before QA handoff:**
-```bash
-ls .peaks/<changeId>/rd/requests/<rid>.md \
-   .peaks/<changeId>/rd/tech-doc.md
-# Both must exist. Missing either → BLOCKED, do not hand off to QA
-```
-
-**Peaks-Cli Gate B2 — Before QA handoff: unit tests exist and pass:**
-```bash
-# Run the project's test command against changed files. Record the output.
-# Example (adapt to project test runner):
-npx vitest run --reporter=verbose 2>&1 | tail -20
-# Expected: exit code 0, all tests passing, coverage for new/changed code recorded
-# Any failing test or zero tests for new code → BLOCKED. Write tests, then re-run.
-```
-
-**Peaks-Cli Gate B3 — Before QA handoff: code review evidence exists:**
-```bash
-ls .peaks/<changeId>/rd/code-review.md 2>&1
-# Expected: .peaks/<changeId>/rd/code-review.md
-# "No such file" → BLOCKED. Run code review (use code-reviewer agent or equivalent),
-# record findings, fix CRITICAL/HIGH issues, then re-check.
-```
-
-**Peaks-Cli Gate B4 — Before QA handoff: security review evidence exists:**
-```bash
-ls .peaks/<changeId>/rd/security-review.md 2>&1
-# Expected: .peaks/<changeId>/rd/security-review.md
-# "No such file" → BLOCKED. Run security review (use security-reviewer agent or equivalent),
-# fix CRITICAL/HIGH issues, record findings, then re-check.
-```
+The full per-gate contract — including the CLI enforcement table (per `--type` required files), the `ls` / `grep` shell snippets for Gate A, A2, A3, B, B2, B3, B4, B5, B6, B7, B8, B9, and the expected outcomes — lives in [`references/rd-transition-gates.md`](references/rd-transition-gates.md). Read that file before declaring a phase complete. The summary below is the index; the reference file is the contract.
 
-**Peaks-Cli Gate B5 — RD artifact body has no unfilled placeholders:**
-```bash
-peaks request lint <rid> --role rd --project <repo> --session-id <session-id> --json
-# Expected: ok=true. exit 0.
-# ok=false → BLOCKED. The lint output lists every <placeholder>, "- ..." stub,
-# and TBD/TODO marker with line numbers. Fill them in before attempting handoff.
-```
+> **CLI enforcement**: the gates below are ALSO enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. Per-type required files: see the table at the top of `references/rd-transition-gates.md`. The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions.
 
-**Peaks-Cli Gate B6 — Declared --type matches the actual diff:**
-```bash
-peaks scan request-type-sanity --project <repo> --type <type> --json
-# Expected: consistent=true. exit 0.
-# consistent=false → BLOCKED. Either the implementation scope-creeped beyond what
-# the declared type covers, or the type was mis-classified at PRD time. Re-classify
-# (`peaks request init` with the corrected --type) or trim the scope.
-```
+**Index of gates** (full contract in `references/rd-transition-gates.md`):
 
-**Peaks-Cli Gate B7 — Repair cycle cap (only relevant during RD↔QA repair loop):**
-```bash
-peaks request repair-status <rid> --project <repo> --session-id <session-id> --json
-# Expected: atCap=false. exit 0.
-# atCap=true → BLOCKED. Three repair cycles already attempted; emit a blocked TXT
-# handoff via Solo rather than entering a fourth cycle.
-```
-
-**Peaks-Cli Gate B8 — Diff stays inside the declared red-line scope:**
-```bash
-peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <session-id> --json
-# Expected: ok=true. exit 0.
-# violations[] non-empty → BLOCKED. A changed file matches an explicit out-of-scope
-#   pattern. Revert it, or — only with PRD approval — expand the RD red-line scope.
-# unclassified[] non-empty → BLOCKED. A changed file does not match any declared
-#   in-scope pattern. Either add it to the in-scope list (intentional widening, requires
-#   PRD approval) or revert the change.
-# patternsDeclared=false → BLOCKED. The RD artifact's `## Red-line scope` section has
-#   no concrete path or glob patterns. Fill it in with paths like `src/services/login/**`
-#   before re-running. Auto-allowed paths (test files, .peaks/, __mocks__/) never need a pattern.
-```
-
-**Peaks-Cli Gate B9 — RD-side perf-baseline output present (when slice has a user-perceivable perf surface):**
-```bash
-ls .peaks/<changeId>/rd/perf-baseline.md 2>&1
-# Expected: .peaks/<changeId>/rd/perf-baseline.md
-# "No such file" + slice is feature / refactor / bugfix-when-perf → BLOCKED.
-#   Run the perf-baseline sub-agent from "Parallel review fan-out" below (or
-#   `peaks perf baseline --apply` inline), then fill in the Results table
-#   with measurements (lighthouse / k6 / autocannon / project-local bench —
-#   the CLI does not run these; that is the RD's job), then re-verify.
-# "No such file" + slice is docs / chore / pure-bugfix-no-perf → OK to proceed;
-#   this gate does not apply to those slice types.
-# File exists but Results table is empty (only the header row, no data rows) →
-#   BLOCKED. The sub-agent scaffolds the file; the main RD loop must fill in
-#   the Path / route | Workload | Tool | Metric | Baseline | Threshold table
-#   with actual numbers before handoff.
-# File contains the marker `N/A — no perf surface` in its Notes section →
-#   OK to proceed. This is the explicit opt-out the sub-agent writes when
-#   the slice has no user-perceivable perf surface (e.g. a feature that only
-#   adds an internal flag with no runtime cost, or a refactor that does not
-#   alter any hot path).
-#
-# The CLI enforcement table below the section header also gates this at the
-# `peaks request transition rd:qa-handoff` call, so a missing or empty file
-# is rejected by the CLI with `code: PREREQUISITES_MISSING`.
-```
+| Gate | When | File / command | Why |
+|---|---|---|---|
+| A | After project-scan read, before any implementation | `ls .peaks/<changeId>/rd/project-scan.md` | Confirms the project-scan exists before code edits |
+| A2 | Before tech-doc write | `ls <every-path-in-tech-doc> \| grep -c "No such file"` | Catches wrong paths in the tech-doc |
+| A3 | Before implementation | `ls CLAUDE.md .claude/rules/...` | Confirms project standards exist |
+| B | Before QA handoff | `ls rd/requests/<rid>.md rd/tech-doc.md` | Both files must exist |
+| B2 | Before QA handoff | `npx vitest run --changed` | Unit tests pass on the changed surface |
+| B3 | Before QA handoff | `ls rd/code-review.md` | Code review evidence exists |
+| B4 | Before QA handoff | `ls rd/security-review.md` | Security review evidence exists |
+| B5 | Before QA handoff | `peaks request lint` | RD artifact has no unfilled placeholders |
+| B6 | Before QA handoff | `peaks scan request-type-sanity` | Declared `--type` matches the diff |
+| B7 | Before QA handoff (repair only) | `peaks request repair-status` | Cycle count under the 3-cycle cap |
+| B8 | Before QA handoff | `peaks scan diff-vs-scope` | Diff stays in red-line scope |
+| B9 | Before QA handoff (perf surface) | `ls rd/perf-baseline.md` | Perf baseline filled (or `N/A — no perf surface`) |
 
 ## Project standards preflight
 

package/skills/peaks-rd/references/rd-transition-gates.md

@@ -0,0 +1,148 @@
+# Peaks-Cli RD transition verification gates
+
+> Extracted from `skills/peaks-rd/SKILL.md` on 2026-06-09 (slice 019 — slim skill files to references) to keep SKILL.md under the 800-line cap from `common/coding-style.md`. The content below is the verbatim "Transition verification gates" section that was previously inline; nothing was paraphrased, just relocated.
+
+## Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file" or any command returns empty, the phase is incomplete.
+
+> **CLI enforcement (NEW)**: the gates below are now ALSO enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. The exact required files depend on the request type chosen at `peaks request init --type <feature|bugfix|refactor|docs|config|chore>` (default `feature`):
+>
+> | Type | rd:implemented requires | rd:qa-handoff also requires |
+> |---|---|---|
+> | feature / refactor | `rd/tech-doc.md` | `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` (filled Results table, or `N/A — no perf surface` in Notes) + **`qa/test-cases/<rid>.md`** (added in slice 004; pre-drafted by the 4th sub-agent in the parallel fan-out) |
+> | bugfix | `rd/bug-analysis.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review.md` + `rd/security-review.md` + **`qa/test-cases/<rid>.md`**; `rd/perf-baseline.md` only when the bug is performance-shaped (matches the L449-452 "When this applies" criteria) |
+> | config | (none) | `rd/security-review.md` only |
+> | docs / chore | (none) | (none) |
+>
+> The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions; the bypass is recorded in the artifact transition note.
+
+**Peaks-Cli Gate A — After project-scan read (before any implementation):**
+```bash
+ls .peaks/<changeId>/rd/project-scan.md
+# Expected output: .peaks/<changeId>/rd/project-scan.md
+# "No such file" → STOP, create the project-scan first. Do not write code.
+```
+
+**Peaks-Cli Gate A2 — Before tech-doc write: project structure verified (PATH CORRECTNESS — CRITICAL):**
+```bash
+# Verify EVERY file path and directory in the tech-doc exists in the actual project.
+# Do not assume paths. Do not guess directory structures. Open the files and verify.
+# Example verification (adapt paths to the actual tech-doc):
+ls <every-single-directory-path-in-tech-doc> 2>&1 | grep -c "No such file"
+# Expected: 0 (zero "No such file" errors)
+# Any "No such file" → WRONG PATH. Fix the tech-doc BEFORE writing another word.
+# This gate exists because a tech-doc with wrong paths wastes QA time,
+# breaks the implementation, and forces the user to correct the engineer.
+```
+
+**Peaks-Cli Gate A3 — Before implementation: project standards files exist (CLAUDE.md + .claude/rules/):**
+```bash
+ls CLAUDE.md .claude/rules/common/coding-style.md .claude/rules/common/code-review.md .claude/rules/common/security.md 2>&1 | grep -c "No such file"
+# Expected: 0 (all four files exist)
+# Any missing → BLOCKED. Run `peaks standards init --project .` to generate them FIRST.
+# Do not write a single line of implementation code without standards files in place.
+# Without CLAUDE.md and .claude/rules/, code review and security review triggers won't fire.
+```
+
+**Peaks-Cli Gate B — Before QA handoff:**
+```bash
+ls .peaks/<changeId>/rd/requests/<rid>.md \
+   .peaks/<changeId>/rd/tech-doc.md
+# Both must exist. Missing either → BLOCKED, do not hand off to QA
+```
+
+**Peaks-Cli Gate B2 — Before QA handoff: unit tests exist and pass for the changed surface:**
+```bash
+# Run the project's test command against changed files. Record the output.
+# Example (adapt to project test runner):
+npx vitest run --changed --reporter=verbose 2>&1 | tail -20
+# Expected: exit code 0, all changed-surface tests passing, coverage for new/changed code recorded
+# Any failing test or zero tests for new code → BLOCKED. Write tests, then re-run.
+#
+# To run the FULL suite (slower; not the default for `peaks slice check`),
+# drop `--changed` or use `npx vitest run --reporter=verbose`. The peaks-solo-test
+# skill is the user-facing wrapper for the full suite; the slice check's
+# `--run-tests` flag is the CLI opt-in.
+```
+
+**Peaks-Cli Gate B3 — Before QA handoff: code review evidence exists:**
+```bash
+ls .peaks/<changeId>/rd/code-review.md 2>&1
+# Expected: .peaks/<changeId>/rd/code-review.md
+# "No such file" → BLOCKED. Run code review (use code-reviewer agent or equivalent),
+# record findings, fix CRITICAL/HIGH issues, then re-check.
+```
+
+**Peaks-Cli Gate B4 — Before QA handoff: security review evidence exists:**
+```bash
+ls .peaks/<changeId>/rd/security-review.md 2>&1
+# Expected: .peaks/<changeId>/rd/security-review.md
+# "No such file" → BLOCKED. Run security review (use security-reviewer agent or equivalent),
+# fix CRITICAL/HIGH issues, record findings, then re-check.
+```
+
+**Peaks-Cli Gate B5 — RD artifact body has no unfilled placeholders:**
+```bash
+peaks request lint <rid> --role rd --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# ok=false → BLOCKED. The lint output lists every <placeholder>, "- ..." stub,
+# and TBD/TODO marker with line numbers. Fill them in before attempting handoff.
+```
+
+**Peaks-Cli Gate B6 — Declared --type matches the actual diff:**
+```bash
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# Expected: consistent=true. exit 0.
+# consistent=false → BLOCKED. Either the implementation scope-creeped beyond what
+# the declared type covers, or the type was mis-classified at PRD time. Re-classify
+# (`peaks request init` with the corrected --type) or trim the scope.
+```
+
+**Peaks-Cli Gate B7 — Repair cycle cap (only relevant during RD↔QA repair loop):**
+```bash
+peaks request repair-status <rid> --project <repo> --session-id <session-id> --json
+# Expected: atCap=false. exit 0.
+# atCap=true → BLOCKED. Three repair cycles already attempted; emit a blocked TXT
+# handoff via Solo rather than entering a fourth cycle.
+```
+
+**Peaks-Cli Gate B8 — Diff stays inside the declared red-line scope:**
+```bash
+peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# violations[] non-empty → BLOCKED. A changed file matches an explicit out-of-scope
+#   pattern. Revert it, or — only with PRD approval — expand the RD red-line scope.
+# unclassified[] non-empty → BLOCKED. A changed file does not match any declared
+#   in-scope pattern. Either add it to the in-scope list (intentional widening, requires
+#   PRD approval) or revert the change.
+# patternsDeclared=false → BLOCKED. The RD artifact's `## Red-line scope` section has
+#   no concrete path or glob patterns. Fill it in with paths like `src/services/login/**`
+#   before re-running. Auto-allowed paths (test files, .peaks/, __mocks__/) never need a pattern.
+```
+
+**Peaks-Cli Gate B9 — RD-side perf-baseline output present (when slice has a user-perceivable perf surface):**
+```bash
+ls .peaks/<changeId>/rd/perf-baseline.md 2>&1
+# Expected: .peaks/<changeId>/rd/perf-baseline.md
+# "No such file" + slice is feature / refactor / bugfix-when-perf → BLOCKED.
+#   Run the perf-baseline sub-agent from "Parallel review fan-out" below (or
+#   `peaks perf baseline --apply` inline), then fill in the Results table
+#   with measurements (lighthouse / k6 / autocannon / project-local bench —
+#   the CLI does not run these; that is the RD's job), then re-verify.
+# "No such file" + slice is docs / chore / pure-bugfix-no-perf → OK to proceed;
+#   this gate does not apply to those slice types.
+# File exists but Results table is empty (only the header row, no data rows) →
+#   BLOCKED. The sub-agent scaffolds the file; the main RD loop must fill in
+#   the Path / route | Workload | Tool | Metric | Baseline | Threshold table
+#   with actual numbers before handoff.
+# File contains the marker `N/A — no perf surface` in its Notes section →
+#   OK to proceed. This is the explicit opt-out the sub-agent writes when
+#   the slice has no user-perceivable perf surface (e.g. a feature that only
+#   adds an internal flag with no runtime cost, or a refactor that does not
+#   alter any hot path).
+#
+# The CLI enforcement table below the section header also gates this at the
+# `peaks request transition rd:qa-handoff` call, so a missing or empty file
+# is rejected by the CLI with `code: PREREQUISITES_MISSING`.
+```