peaks-cli 1.3.7 → 1.3.8

package/dist/src/services/session/platform-fallbacks.js

@@ -0,0 +1,35 @@
+/**
+ * PLATFORM_FALLBACKS — the Level 3 fallback table for caller-id resolution.
+ *
+ * Slice 020 (D3): when neither `--caller-id` nor `PEAKS_CALLER_ID` is
+ * set, the resolver walks this table top-to-bottom and takes the
+ * first non-empty entry. Today there is exactly one entry: Claude
+ * Code (`CLAUDE_CODE_SESSION_ID`).
+ *
+ * To add a new platform (Cursor, Windsurf, peaks-ide, etc.):
+ *
+ *   1. Add a new entry below.
+ *   2. Bump the contract doc's A5 acceptance criterion
+ *      (`.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`).
+ *   3. Add a regression test that asserts the new entry resolves
+ *      correctly under D4 priority.
+ *
+ * The contract's A5 test (`tests/unit/services/session/caller-id-resolution.test.ts`)
+ * asserts `PLATFORM_FALLBACKS.length === 1`; adding a new entry will
+ * fail that test, forcing the contract bump.
+ *
+ * Adding an entry does NOT require code changes to read points
+ * (statusline, doctor, sc, session-info) — they all call the same
+ * resolver. Each entry is a one-line additive change.
+ */
+export const PLATFORM_FALLBACKS = [
+    {
+        envVar: 'CLAUDE_CODE_SESSION_ID',
+        description: 'Claude Code session id',
+        addedIn: '1.3.7'
+    }
+    // Future entries (do NOT add without bumping the contract's A5):
+    // { envVar: 'CURSOR_SESSION_ID', description: 'Cursor session id', addedIn: 'TBD' },
+    // { envVar: 'WINDSURF_SESSION_ID', description: 'Windsurf session id', addedIn: 'TBD' },
+    // { envVar: 'PEAKS_IDE_SESSION_ID', description: 'peaks-ide session id', addedIn: 'TBD' },
+];

package/dist/src/services/session/resolve-caller-id.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ *
+ * `resolveCallerId` is the single source of truth for "who is calling
+ * the CLI". The resolver applies D4 priority (flag > env > platform
+ * fallback > reject) and validates the winner against D1's regex;
+ * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ *
+ * The function is synchronous and pure. It does NOT touch the
+ * filesystem, does NOT read any caller binding file, and does NOT
+ * mutate state. The caller (a CLI command, a service, a test) decides
+ * what to do with the resolved id.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7).
+ */
+import { CallerIdError } from './caller-id-types.js';
+export { CallerIdError };
+export interface ResolveCallerIdOptions {
+    /**
+     * The `--caller-id <id>` flag value (per-invocation override).
+     * D4 priority level 1: flag wins.
+     */
+    flagValue?: string;
+    /**
+     * Override for the `PEAKS_CALLER_ID` environment variable. D4
+     * priority level 2: env wins. Defaults to `process.env.PEAKS_CALLER_ID`.
+     * The override exists so tests can run without mutating process.env.
+     */
+    envOverride?: string;
+    /**
+     * The env object to read. Defaults to `process.env`. Exists so
+     * tests can drive Level 3 (platform fallback) without mutating
+     * process.env.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the calling process's callerId per D1-D5.
+ *
+ * D4 priority (strict, no merge):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
+ *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
+ *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
+ *
+ * On success: returns the resolved id (matches D1's regex, validated).
+ * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
+ * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ *
+ * @example
+ *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
+ *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ */
+export declare function resolveCallerId(opts?: ResolveCallerIdOptions): string;

package/dist/src/services/session/resolve-caller-id.js

@@ -0,0 +1,88 @@
+/**
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ *
+ * `resolveCallerId` is the single source of truth for "who is calling
+ * the CLI". The resolver applies D4 priority (flag > env > platform
+ * fallback > reject) and validates the winner against D1's regex;
+ * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ *
+ * The function is synchronous and pure. It does NOT touch the
+ * filesystem, does NOT read any caller binding file, and does NOT
+ * mutate state. The caller (a CLI command, a service, a test) decides
+ * what to do with the resolved id.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7).
+ */
+import { CALLER_ID_REGEX, CallerIdError } from './caller-id-types.js';
+import { PLATFORM_FALLBACKS } from './platform-fallbacks.js';
+// Re-export for CLI consumers (avoids a second import line).
+export { CallerIdError };
+/**
+ * Check whether `value` looks like a callerId (non-empty, matches D1).
+ * Returns the trimmed value if so, undefined otherwise. Does not throw.
+ */
+function isNonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Read a single platform-fallback env var from `env`. Returns the
+ * non-empty trimmed value or `undefined`. Logs nothing.
+ */
+function readPlatformFallback(env) {
+    for (let i = 0; i < PLATFORM_FALLBACKS.length; i++) {
+        const candidate = env[PLATFORM_FALLBACKS[i].envVar];
+        if (isNonEmpty(candidate)) {
+            return { value: candidate, index: i };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate `value` against D1's regex. Returns the value on success,
+ * throws `CallerIdError` (EX_DATAERR, exit 65) on failure.
+ */
+function validateCallerId(value, source) {
+    if (!CALLER_ID_REGEX.test(value)) {
+        throw new CallerIdError('EX_DATAERR', source, `Invalid caller id "${value}" (source: ${source}). callerId must match ^[a-zA-Z0-9._-]{1,200}$.`, value);
+    }
+    return value;
+}
+/**
+ * Resolve the calling process's callerId per D1-D5.
+ *
+ * D4 priority (strict, no merge):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
+ *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
+ *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
+ *
+ * On success: returns the resolved id (matches D1's regex, validated).
+ * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
+ * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ *
+ * @example
+ *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
+ *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ */
+export function resolveCallerId(opts = {}) {
+    const env = opts.env ?? process.env;
+    // D4 level 1: flag value
+    if (isNonEmpty(opts.flagValue)) {
+        return validateCallerId(opts.flagValue, 'flag');
+    }
+    // D4 level 2: env var
+    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : env.PEAKS_CALLER_ID;
+    if (isNonEmpty(envValue)) {
+        return validateCallerId(envValue, 'env');
+    }
+    // D4 level 3: PLATFORM_FALLBACKS table (top-to-bottom)
+    const fallback = readPlatformFallback(env);
+    if (fallback !== undefined) {
+        return validateCallerId(fallback.value, 'fallback');
+    }
+    // D4 level 4: D2 fires — no callerId available
+    throw new CallerIdError('EX_USAGE', 'none', 'No caller id available. Set PEAKS_CALLER_ID or pass --caller-id.');
+}

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -43,6 +43,17 @@ export type SkillPresence = {
     lastHeartbeat?: string;
 };
 export declare function exportSkillPresence(projectRootOverride?: string): string;
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export declare function setSkillPresenceForCaller(projectRootOverride: string, callerId: string, peakSessionId: string, skill: string, mode?: string, gate?: string): SkillPresence;
 export declare function setSkillPresence(skill: string, mode?: string, gate?: string, projectRootOverride?: string): SkillPresence;
 export declare function getSkillPresence(projectRootOverride?: string): SkillPresence | null;
 export declare function touchSkillHeartbeat(projectRootOverride?: string): SkillPresence | null;

package/dist/src/services/skills/skill-presence-service.js

@@ -160,6 +160,65 @@ function getPreviousOuterSessionId(projectRootOverride) {
 export function exportSkillPresence(projectRootOverride) {
     return resolvePresencePath(projectRootOverride);
 }
+// ============================================================================
+// Slice 020 — caller-keyed active-skill marker (D6).
+// ============================================================================
+//
+// Today's per-project active-skill marker (`.peaks/_runtime/active-skill.json`)
+// races when multiple Claude Code windows (or different platforms) drive the
+// same project concurrently. Slice 020 introduces a per-caller file at
+// `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Two callers
+// bound to the same peak session never clobber each other.
+//
+// The single-file marker is RETAINED for one minor release as read-only
+// back-compat (M1, M4). The new write path is `setSkillPresenceForCaller`;
+// the legacy `setSkillPresence` is now a thin wrapper that synthesises a
+// legacy callerId from `process.env.CLAUDE_CODE_SESSION_ID` (or
+// `projectRoot` for the truly-anonymous case) and delegates.
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export function setSkillPresenceForCaller(projectRootOverride, callerId, peakSessionId, skill, mode, gate) {
+    const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
+    const now = new Date().toISOString();
+    const presence = {
+        skill,
+        ...(validatedMode ? { mode: validatedMode } : {}),
+        ...(gate ? { gate } : {}),
+        ...(peakSessionId ? { sessionId: peakSessionId } : {}),
+        ...(callerId ? { outerSessionId: callerId } : {}),
+        setAt: now,
+        lastHeartbeat: now
+    };
+    const presencePath = getActiveSkillFileForCallerPath(resolveProjectRoot(projectRootOverride), peakSessionId, callerId);
+    const presenceDir = dirname(presencePath);
+    if (!existsSync(presenceDir)) {
+        mkdirSync(presenceDir, { recursive: true });
+    }
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: bring the memory store into existence for
+    // fresh projects. Same fail-open contract as the legacy path.
+    ensureMemoryBootstrap(resolveProjectRoot(projectRootOverride));
+    return presence;
+}
+/**
+ * Compute the per-caller active-skill file path. Re-exported for test
+ * ergonomics; canonical path lives in
+ * `src/services/session/caller-binding-service.ts` but inlined here to
+ * avoid a circular import (`caller-binding-service` reads
+ * `skill-presence-service` for the `setCallerBinding` integration in
+ * future slices; the inverse import would deadlock).
+ */
+function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
+    return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
+}
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);

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

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

package/dist/src/shared/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.7",
+  "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-rd/SKILL.md

@@ -295,146 +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 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.
-```
+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 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.
-```
+> **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 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.
-```
+**Index of gates** (full contract in `references/rd-transition-gates.md`):
 
-**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`.
-```
+| 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`.
+```