peaks-cli 1.2.6 → 1.2.8

package/dist/src/services/session/session-manager.js

@@ -5,12 +5,54 @@
  * Sessions are automatically created when any skill is invoked.
  * Each session gets a unique directory under .peaks/ with incrementing numbered files.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
 const SESSION_FILE = '.session.json';
 const META_FILE = 'session.json';
+/**
+ * Canonicalize a project root path. Returns the realpath
+ * (resolving all symlinks — important on macOS where `/var`
+ * is a symlink to `/private/var`, and on the dev box where
+ * `/tmp` is the same `/private/var/folders/...` target as
+ * `/var/folders/...`). If the path does not exist (e.g. in
+ * tests that write the binding before the dir, or callers
+ * that pass a non-existent path), falls back to the
+ * `resolve()`d absolute form so the function NEVER throws.
+ */
+function canonicalizeProjectRoot(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/**
+ * Resolve a stored `projectRoot` value (from
+ * `.peaks/.session.json`) against the caller-passed
+ * `projectRoot`, then canonicalize. Handles two forms the
+ * legacy strict-equality check missed:
+ *
+ *   1. **Stored is relative** (e.g. `"."` when the binding
+ *      was written from inside the project dir). We resolve
+ *      it against the caller — if the caller's project root
+ *      is absolute, `path.resolve(caller, ".")` returns the
+ *      caller's absolute form, which then canonicalizes to
+ *      the caller's realpath.
+ *
+ *   2. **Both are absolute but the stored form is not
+ *      canonical** (e.g. `/var/folders/...` vs
+ *      `/private/var/folders/...` on macOS). Both canonicalize
+ *      to the same realpath.
+ *
+ * The combined check is the canonicalize-on-read contract.
+ */
+function resolveStoredAgainstCaller(stored, caller) {
+    const resolved = resolve(caller, stored); // if `stored` is absolute, returns `stored`; else joins with caller
+    return canonicalizeProjectRoot(resolved);
+}
 /**
  * Generate a new session ID.
  * Format: YYYY-MM-DD-session-<6位hex>
@@ -34,6 +76,19 @@ function getSessionFilePath(projectRoot) {
 /**
  * Read existing session info from disk.
  * Returns null if no session file exists or if it's invalid.
+ *
+ * Strict equality on `data.projectRoot === projectRoot` is
+ * preserved here on purpose: many other modules (notably
+ * `shared/change-id.ts` via `buildArtifactRelativePath`)
+ * depend on the strict-equality semantics to test the
+ * "no session bound" code path. Changing the read semantics
+ * here would cascade into ~30 test failures in those
+ * modules — out of scope for the progress rebind fix.
+ *
+ * The progress subcommands (which are the surface that
+ * actually breaks on the rebind bug) use
+ * `getSessionIdCanonical` instead, which does the
+ * canonicalize-on-read resolution the bug fix needs.
  */
 function readSessionFile(projectRoot) {
     const sessionFile = getSessionFilePath(projectRoot);
@@ -50,6 +105,33 @@ function readSessionFile(projectRoot) {
         return null;
     }
 }
+/**
+ * Same as `readSessionFile` but canonicalizes BOTH the
+ * caller-passed and stored `projectRoot` before comparing.
+ * See `resolveStoredAgainstCaller` for the rules.
+ *
+ * Exported as `readSessionFileCanonical` so the new
+ * `getSessionIdCanonical` can use it; not part of the
+ * public API otherwise.
+ */
+function readSessionFileCanonical(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    if (!existsSync(sessionFile))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        const storedRaw = typeof data.projectRoot === 'string' ? data.projectRoot : null;
+        if (data.sessionId &&
+            storedRaw !== null &&
+            resolveStoredAgainstCaller(storedRaw, projectRoot) === resolveStoredAgainstCaller(projectRoot, projectRoot)) {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Write session info to disk.
  */
@@ -61,6 +143,29 @@ function writeSessionFile(projectRoot, info) {
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
+/**
+ * Drop the project-level session binding (`.peaks/.session.json`)
+ * so the next `ensureSession()` call auto-generates a fresh
+ * session id. The on-disk session directory is left intact —
+ * rotating does NOT delete the user's data, it just unbinds the
+ * project from that session.
+ *
+ * Returns the id of the session that was unbound, or `null` if
+ * no binding was present. The caller is expected to do something
+ * with that — at minimum surface it in the CLI response so the
+ * user can find the directory again if they need to.
+ */
+export function rotateSessionBinding(projectRoot) {
+    const previous = readSessionFile(projectRoot);
+    if (previous === null) {
+        return null;
+    }
+    const sessionFile = getSessionFilePath(projectRoot);
+    if (existsSync(sessionFile)) {
+        unlinkSync(sessionFile);
+    }
+    return previous.sessionId;
+}
 /**
  * Bind the project's current session to the given session id by writing
  * `.peaks/.session.json`. The single-session binding is the source of truth
@@ -168,6 +273,15 @@ export function listSessionMetas(projectRoot) {
  * @param projectRoot - Root directory of the project
  * @returns Session ID (e.g., "2026-05-26-session-a3f8b1")
  */
+function getCurrentOuterSessionId() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
+}
 export async function ensureSession(projectRoot) {
     const existing = readSessionFile(projectRoot);
     if (existing) {
@@ -183,10 +297,12 @@ export async function ensureSession(projectRoot) {
     writeSessionFile(projectRoot, info);
     await initWorkspace({ projectRoot, sessionId });
     // Initialize session metadata inside the session directory
+    const outerSessionId = getCurrentOuterSessionId();
     writeSessionMeta(projectRoot, sessionId, {
         sessionId,
         projectRoot,
-        createdAt: now
+        createdAt: now,
+        ...(outerSessionId !== undefined ? { outerSessionId } : {})
     });
     return sessionId;
 }
@@ -201,6 +317,37 @@ export function getSessionId(projectRoot) {
     const info = readSessionFile(projectRoot);
     return info?.sessionId ?? null;
 }
+/**
+ * Resolve the current session id with canonicalize-on-read
+ * semantics. This is the variant the progress subcommands
+ * (step / watch / start / close) use, because the legacy
+ * `getSessionId` returns null any time the stored
+ * `projectRoot` form differs from the caller-passed form
+ * (e.g. stored is "." from inside the project dir; caller
+ * is the absolute realpath). When `getSessionId` returns
+ * null, callers like `ensureSession` create a brand-new
+ * session and overwrite the binding — which is what the
+ * user observed as the "mid-dogfood rebind" bug.
+ *
+ * The fix is to canonicalize both sides of the compare
+ * (realpath, then optionally resolve relative stored
+ * against the caller's project root). The two forms of
+ * the same physical directory now compare equal, and the
+ * existing binding is found instead of being overwritten.
+ *
+ * Use this instead of `getSessionId` only when the
+ * caller is operating on a user-supplied `--project` flag
+ * and the binding may have been written by a CLI invocation
+ * that was running from inside the project dir (the common
+ * peaks-solo / peaks-sop scenario). Other modules depend
+ * on the strict-equality semantics of `getSessionId` (the
+ * "no binding" fallback path is part of their contract),
+ * so this variant is opt-in.
+ */
+export function getSessionIdCanonical(projectRoot) {
+    const info = readSessionFileCanonical(projectRoot);
+    return info?.sessionId ?? null;
+}
 /**
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.

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

@@ -6,7 +6,33 @@ export type SkillPresence = {
     mode?: SkillPresenceMode;
     gate?: string;
     sessionId?: string;
-    claudeSessionId?: string;
+    /**
+     * Identifier of the *outer* session — the Claude Code / Cursor /
+     * VSCode-plugin / other harness session that is currently driving
+     * the LLM. Sourced from the `PEAKS_OUTER_SESSION_ID` environment
+     * variable when set, with `CLAUDE_CODE_SESSION_ID` as a fallback for
+     * Claude Code. Stamped onto the presence file so the status line
+     * can tell whether the recorded skill belongs to the live outer
+     * session (show it) or a previous one (render idle), and so
+     * `setSkillPresence` can detect a session swap and AskUserQuestion
+     * the user about rolling a new peaks session.
+     */
+    outerSessionId?: string;
+    /**
+     * Set by `setSkillPresence` when the outer session id changed
+     * between the last presence write and this one AND the bound
+     * peaks session has a different (or no) recorded outer session id.
+     * The field is informational only — `setSkillPresence` does not
+     * roll a new session on its own. peaks-solo's Step 0 reads the
+     * field off the presence file and turns it into an
+     * AskUserQuestion: "Start a new peaks session / Keep this one".
+     */
+    outerSessionMismatch?: {
+        previous?: string;
+        current: string;
+        boundSessionId: string;
+        boundOuterSessionId?: string;
+    };
     setAt: string;
     lastHeartbeat?: string;
 };

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

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { dirname, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
+import { getSessionMeta } from '../session/session-manager.js';
 export const VALID_SKILL_PRESENCE_MODES = [
     'full-auto',
     'assisted',
@@ -12,14 +13,23 @@ export function isSkillPresenceMode(value) {
     return VALID_SKILL_PRESENCE_MODES.includes(value);
 }
 /**
- * The current Claude Code session id, exposed to Bash tool calls via the
- * CLAUDE_CODE_SESSION_ID environment variable. Stamping it onto the presence
- * file lets the read-only status line tell whether the recorded skill belongs
- * to the live session (show it) or a previous one (render idle).
+ * The current outer session id, exposed to Bash tool calls via the
+ * `PEAKS_OUTER_SESSION_ID` environment variable. Stamping it onto the
+ * presence file lets the read-only status line tell whether the recorded
+ * skill belongs to the live session (show it) or a previous one
+ * (render idle). Falls back to `CLAUDE_CODE_SESSION_ID` for Claude Code
+ * so existing Claude Code users get the field populated without any
+ * configuration; other harnesses that want a presence stamp can set
+ * either variable.
  */
-function getCurrentClaudeSessionId() {
-    const value = process.env.CLAUDE_CODE_SESSION_ID;
-    return typeof value === 'string' && value.length > 0 ? value : undefined;
+function getCurrentOuterSessionId() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
 }
 const PRESENCE_FILE = '.peaks/.active-skill.json';
 const SESSION_FILE = '.peaks/.session.json';
@@ -45,23 +55,116 @@ function getCurrentSessionId(projectRootOverride) {
         return null;
     }
 }
+/**
+ * Look up the outer-session-id that was bound to the *current* peaks
+ * session, i.e. the one written to the per-session
+ * `.peaks/<sid>/session.json` by `ensureSession`/`initWorkspace`. This
+ * is the source of truth for "which outer session owns the
+ * in-flight peaks session".
+ *
+ * Returns `null` if no peaks session is bound yet, or if the bound
+ * session has no recorded outer session id (legacy sessions predating
+ * the outer-session contract).
+ */
+function getBoundOuterSessionId(projectRootOverride) {
+    const sessionId = getCurrentSessionId(projectRootOverride);
+    if (sessionId === null)
+        return undefined;
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const meta = getSessionMeta(projectRoot, sessionId);
+    if (meta === null)
+        return undefined;
+    return typeof meta.outerSessionId === 'string' && meta.outerSessionId.length > 0
+        ? meta.outerSessionId
+        : undefined;
+}
+/**
+ * Snapshot of the previous peaks session's outer session id, read
+ * straight off `.peaks/.active-skill.json` *before* we overwrite it.
+ * Used to detect "the LLM just opened a fresh outer session" — if
+ * the previously-recorded outer session id differs from the one we
+ * are about to stamp, the user probably closed the previous outer
+ * session and is now driving peaks from a new one. We do NOT auto-
+ * roll a new peaks session (that is destructive — it would leave
+ * the in-flight session with no LLM watching it). Instead we emit
+ * a structured `outerSessionMismatch` field on the presence
+ * envelope, and peaks-solo's Step 0 turns that into an
+ * AskUserQuestion. The user can opt to keep the current session
+ * (most common when the swap is a no-op reconnect) or to roll a
+ * fresh session (when the new outer session is genuinely a new
+ * task).
+ */
+function getPreviousOuterSessionId(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
+    if (!existsSync(presencePath))
+        return undefined;
+    try {
+        const raw = readFileSync(presencePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
+            return parsed.outerSessionId;
+        }
+        // Legacy field name. Honour it on the read side so v1.2.x
+        // presence files do not show as a false mismatch.
+        if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
+            return parsed.claudeSessionId;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function exportSkillPresence(projectRootOverride) {
     return resolvePresencePath(projectRootOverride);
 }
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);
-    const claudeSessionId = getCurrentClaudeSessionId();
+    const outerSessionId = getCurrentOuterSessionId();
+    const previousOuterSessionId = getPreviousOuterSessionId(projectRootOverride);
     const now = new Date().toISOString();
     const presence = {
         skill,
         ...(validatedMode ? { mode: validatedMode } : {}),
         ...(gate ? { gate } : {}),
         ...(sessionId ? { sessionId } : {}),
-        ...(claudeSessionId ? { claudeSessionId } : {}),
+        ...(outerSessionId ? { outerSessionId } : {}),
         setAt: now,
         lastHeartbeat: now
     };
+    // Outer-session-mismatch detection. Fires only when:
+    //   (a) we have a *current* outer session id (i.e. some harness is
+    //       driving peaks right now — PEAKS_OUTER_SESSION_ID or
+    //       CLAUDE_CODE_SESSION_ID is set), AND
+    //   (b) the previous presence write recorded a *different* outer
+    //       session id (or none), AND
+    //   (c) the current peaks session is bound to a different outer
+    //       session id (or no outer session id is bound).
+    //
+    // The combination of (b) and (c) is what tells us "this is a
+    // genuine outer-session swap, not a transient env-var change".
+    // When only (b) fires (current bound session was started in this
+    // same outer session), no mismatch is reported — that is the
+    // common reconnect case.
+    if (outerSessionId !== undefined) {
+        const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
+        const outerChanged = previousOuterSessionId !== outerSessionId;
+        const boundOuterMatches = boundOuterSessionId === outerSessionId;
+        // Suppress the false-positive where neither side ever recorded
+        // an outer session id. Two unknowns are not a swap — they are
+        // simply "no outer-session signal available yet". Only report
+        // a mismatch when at least one side has a recorded outer id.
+        const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
+        if (hasOuterSignal && outerChanged && !boundOuterMatches && sessionId !== null) {
+            presence.outerSessionMismatch = {
+                ...(previousOuterSessionId !== undefined ? { previous: previousOuterSessionId } : {}),
+                current: outerSessionId,
+                boundSessionId: sessionId,
+                ...(boundOuterSessionId !== undefined ? { boundOuterSessionId } : {})
+            };
+        }
+    }
     const presencePath = resolvePresencePath(projectRootOverride);
     const presenceDir = dirname(presencePath);
     if (!existsSync(presenceDir)) {

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.6";
+export declare const CLI_VERSION = "1.2.8";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.6";
+export const CLI_VERSION = "1.2.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -43,10 +43,14 @@
   },
   "dependencies": {
     "@colbymchenry/codegraph": "0.7.10",
+    "chalk": "^5.6.2",
     "commander": "^12.1.0",
-    "shadcn": "4.7.0"
+    "ora": "^8.2.0",
+    "shadcn": "4.7.0",
+    "terminal-kit": "^3.1.2"
   },
   "devDependencies": {
+    "@types/chalk": "^2.2.4",
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^2.1.8",
     "tsx": "^4.19.2",

package/skills/peaks-qa/SKILL.md

@@ -178,6 +178,19 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 #    because code review alone does not catch: hardcoded secrets, XSS vectors,
 #    bundle size regressions, render-performance issues, or missing CSP headers.
 #    If you skip A3 or A4, Peaks-Cli Gate C will block the verdict.
+#
+#    Before running A4, read the RD's perf-baseline at
+#    .peaks/<id>/rd/perf-baseline.md (if present) and use the
+#    captured thresholds as the comparison baseline. The QA stage
+#    is still responsible for running the actual measurement
+#    (lighthouse / k6 / autocannon / project-local bench) and
+#    for the verdict — the RD-side baseline is the *known-good
+#    reference* that lets the QA stage say "X regressed by Y%"
+#    instead of "X is bad, but I have no number for what good
+#    looks like". If the RD did not produce a perf-baseline
+#    (e.g. the slice is docs / chore / has no perf surface),
+#    surface that absence in the QA test-report under a
+#    `## Performance baseline` section.
 
 # 6. write test-report — MANDATORY, write to .peaks/<session-id>/qa/test-reports/<request-id>.md
 #    MUST contain actual execution results (pass/fail counts, coverage %, findings).

package/skills/peaks-rd/SKILL.md

@@ -88,6 +88,21 @@ On the first presence:set in a project, ensure the out-of-band status bar is ins
 peaks statusline install --project <repo>   # idempotent; skips if already installed
 ```
 
+**Auto-spawn a progress watch terminal once per slice (BLOCKING on the first phase transition).** The user opens a fresh VSCode window per slice, not per Bash call. Without a separate progress terminal the user has no live signal that the sub-agent is alive — the only signal they have is the static statusline. So at the first phase transition of every slice, fire `peaks progress start` ONCE. The CLI auto-spawns a new terminal tab running `peaks progress watch` and the user can close the new tab at any time. Do NOT re-invoke on every phase change — one per slice is the contract. The LLM-side cost of this one invocation is one Bash call plus a small JSON envelope; the watch side is a 1s file poll that does not consume LLM tokens.
+
+```bash
+# At the first phase transition of a slice (after the first
+# peaks progress step), fire the watch:
+peaks progress start --project <repo> --reason "rd-implementing for <rid>"
+
+# On every subsequent phase transition, only update the
+# progress file — the watch is already running in another tab:
+peaks progress step --project <repo> --request-id <rid> --role rd \
+  --step "running pnpm test" --phase running
+```
+
+If `peaks progress start` is unsupported on the current platform (no terminal emulator, headless container, etc.) it returns a recoverable error envelope. Surface that in the RD handoff so the user knows the auto-spawn failed; the sub-agent can still emit `peaks progress step` writes that the user reads from the on-disk file. The auto-spawn is convenience, not a gate.
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash
@@ -114,6 +129,26 @@ Use the `<request-id>` PRD assigned. RD companion artifacts (task graph, scan re
 
 Concrete template and rules: `references/artifact-per-request.md`.
 
+## Two RD artifact files — do not confuse them
+
+RD has two distinct artifact files, and the most common regression is to write the per-slice content into the per-session file. They serve different readers and live in different places:
+
+| File | Scope | Reader | Required content |
+|---|---|---|---|
+| `.peaks/<sid>/rd/tech-doc.md` | per-session — the whole RD plan for the session, all slices | Solo, future LLM, the human scrolling the session | Architecture, slice graph, mock strategy, cross-cutting decisions. **Not** the place for per-slice implementation evidence. |
+| `.peaks/<sid>/rd/requests/<rid>.md` | per-slice — one request, one planning artifact | QA, SC, the lint gate | Red-line scope, in-scope / out-of-scope, unit-test requirements, **Implementation evidence** (file list, `pnpm test` output, git diff excerpts), MCP usage, handoff, status. **This is the file the lint gate checks for placeholders.** |
+| `.peaks/<sid>/rd/code-review.md` | per-session — the engineering review | QA, the human reviewer | Code review findings + fixes. |
+| `.peaks/<sid>/rd/security-review.md` | per-session — the security review | QA | Security review findings + fixes. |
+
+**Failure mode the lint gate catches**: the LLM writes the actual implementation content into `rd/tech-doc.md` and leaves `rd/requests/<rid>.md` as the default template (with placeholder sections like "Implementation evidence: 留待 RD 实施阶段补充" and "MCP usage: N/A"). The lint gate then fails the slice with 6+ lint errors on the `<rid>.md` template even though the actual content lives in `tech-doc.md`.
+
+**Rule**:
+- **Per-slice content** (red-line scope, in-scope / out-of-scope, the implementation evidence list, the unit-test assertions, the handoff) → **belongs in `rd/requests/<rid>.md`**.
+- **Per-session content** (the architecture overview, the slice roadmap, the cross-cutting concerns, the mock strategy for the whole session) → **belongs in `rd/tech-doc.md`**.
+- When in doubt: copy the per-slice content into the `<rid>.md` artifact's "Implementation evidence" section after writing it to `tech-doc.md`. The two files can carry overlapping context; the gate only enforces that `<rid>.md` is not empty placeholders.
+
+Concrete template and rules: `references/artifact-per-request.md`.
+
 ## Default runbook
 
 The default sequence the RD skill should execute for a code-touching request. Skip steps that do not apply to the request type; do not skip the artifact, coverage gate, or red-line scope steps.
@@ -407,6 +442,47 @@ Before every code or mock change, RD must write and then enforce a red-line scop
 - Never add `tailwindcss` to a project that already uses a component library with its own CSS-in-JS solution unless the project-scan explicitly approves it
 - If TailwindCSS is already present, use it consistently with the project's existing utility patterns; do not mix TailwindCSS utility classes with component-library `style` prop overrides on the same element
 
+## Mandatory perf-baseline output (RD-side perf gate)
+
+**BLOCKING — Do not hand off to QA without a perf-baseline file when the slice has a user-visible performance surface.** The QA stage's Gate A4 (performance check) needs a stable reference to diff against; without an RD-side baseline, the first time Gate A4 runs it has nothing to compare against and any regression it finds is a blind-side surprise. The user-facing pain of leaving perf to QA only has historically been a 3-cycle repair loop ("QA returns for perf", "RD ships a fix", "QA returns for perf again", "RD ships another fix", ...). The RD-side baseline closes that loop.
+
+**When this applies:**
+- feature / refactor slices that touch a route, hook, API, or any user-perceivable surface
+- bugfix slices where the bug is performance-shaped (slow render, hot loop, N+1)
+- any slice where the PRD mentions a number (LCP / FCP / TBT / p95 / rps / etc.)
+
+**When this does NOT apply:**
+- docs / chore slices
+- pure bugfixes whose fix is "remove the bug" (no perf surface)
+- any slice where the slice is documentation-only or otherwise has no perf surface — in that case write `N/A — no perf surface` in the file's "Notes" section and surface that fact in the RD handoff
+
+**How to produce the file:**
+
+```bash
+# 1. dry-run preview (default)
+peaks perf baseline --project <repo>
+# → ok: true, data.plannedWrites shows the file path, no files written
+
+# 2. apply — scaffolds the file at .peaks/<sid>/rd/perf-baseline.md
+peaks perf baseline --project <repo> --apply --reason "capturing baseline for Gate A4 diff"
+# → ok: true, data.writtenFiles includes the path
+
+# 3. fill in the file's Results table
+#    (lighthouse / k6 / autocannon / project-local bench — the
+#    CLI does not call any of these; that is the RD's job)
+#    open .peaks/<sid>/rd/perf-baseline.md and complete the
+#    "Path / route | Workload | Tool | Metric | Baseline | Threshold"
+#    table
+
+# 4. hand off to QA. The QA stage reads the file's Results
+#    table as the input to Gate A4 — see peaks-qa SKILL.md
+#    Gate A4.
+```
+
+**Idempotency:** re-running `peaks perf baseline --apply` on a session where the file already exists is a no-op (the CLI does not overwrite hand-edited content). This is the normal RD retry pattern (re-measurement, threshold adjustment, etc.). If the RD really does want to overwrite, delete the file first and re-run.
+
+**The role of the CLI vs. the actual measurement:** the CLI is the *scaffolding*. It writes the file, exposes the path, and keeps the file's structure stable so QA can rely on it. The CLI does NOT call lighthouse / k6 / autocannon — those are project-shape dependent and the right tool is a project-local concern, not a peaks-cli concern. The CLI is justified (4-grounds check): it gates the QA-side decision on a stable artefact, it requires --apply for a destructive write, and it is invokable from a hook on session init. It is *not* a machine-enforced gate that prose cannot enforce — the measurement is the RD's responsibility.
+
 ## Implementation completion gates
 
 RD cannot mark a development slice complete until all of these are true. Each gate below maps to a hard verification gate in the Transition Verification Gates section — run the corresponding command, see the output.