peaks-loop 3.0.0

package/skills/peaks-rd/references/library-version-awareness.md

@@ -0,0 +1,30 @@
+# Library version awareness
+
+> Body of `## Library version awareness (3rd-party breaking-change gate)`. After `peaks scan libraries` lands the dependency list under `## Library versions` in `rd/project-scan.md`, RD MUST cross-check the slice's diff against `schemas/library-breaking-changes.data.json` before writing any 3rd-party API call. Concretely:
+
+1. **Read the project's `## Library versions` section** in `.peaks/_runtime/<sessionId>/rd/project-scan.md`. Identify the `name` + `major` of every dependency the slice imports from.
+2. **Open `schemas/library-breaking-changes.data.json`** (LLM reads via the `Read` tool). For each library where the installed `major` matches a `toMajor` in the table, load the corresponding `breakingChanges[]` list.
+3. **For each `import` statement in the slice's diff** (e.g. `import { Drawer } from 'antd'`), check whether the imported symbol or its prop signature matches any `breakingChanges[].api` entry for the library's installed major.
+4. **On a hit**:
+   - **Warn the LLM in the slice's handoff**: in `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md` under `## Implementation evidence`, append a one-line note per hit: `- [lib-version] <library> <installed version> imports <api>; breaking-change rule says use <replacement> instead.`
+   - **Persist a `lesson` memory** at the END of `.peaks/_runtime/<sessionId>/rd/project-scan.md` (or the tech-doc, or the handoff — any of these is read by future RD runs):
+     ```
+     <!-- peaks-memory:start -->
+     title: <library> <installed major> requires <api> → <replacement>
+     kind: lesson
+     ---
+     Observed in slice <rid>: project is on <library>@<major> and the diff imported <api> which is on the breaking-changes list. Use <replacement> instead. Source: schemas/library-breaking-changes.data.json.
+     <!-- peaks-memory:end -->
+     ```
+   - The next RD run will see this lesson in `peaks project memories` and skip the same drift.
+
+**Why this exists**: the LLM's training data lags the latest major versions. The user hit `[antd: Drawer] width is deprecated. Please use size instead` in an antv6 project because the LLM wrote v5-style code. The breaking-changes table is the canonical place for "library X at major Y has these known migrations" so the LLM doesn't have to guess.
+
+**Out of scope**: the breaking-changes table is hand-curated; auto-syncing from upstream changelogs (Context7, etc.) is a follow-up slice. Per-slice the LLM only reads the table — it does NOT maintain it.
+
+**Data freshness check (read schemas/library-breaking-changes.meta.json first)**:
+- Before reading `schemas/library-breaking-changes.data.json`, also read `schemas/library-breaking-changes.meta.json`.
+- Compute `ageInDays = (today - meta.lastUpdated)`. The LLM is responsible for this date math.
+- If `ageInDays > meta.freshnessPolicyDays` (default 180 days), surface a **freshness warning** in the handoff: `- [data-staleness] library-breaking-changes.data.json is ${ageInDays} days old (last touched ${meta.lastUpdated}); the breaking-changes below may miss library X's recent major. Re-verify against the library's official changelog before relying on these substitutions.`
+- The warning is **informational**, not blocking. A stale table is better than no table. The LLM still applies the entries it has, just with the caveat.
+- When a row in the table matches an `import` in the diff AND the table is fresh, proceed without the warning.

package/skills/peaks-rd/references/mandatory-perf-baseline.md

@@ -0,0 +1,42 @@
+# Mandatory perf-baseline output (RD)
+
+> Body of `## Mandatory perf-baseline output` + numbered perf-baseline steps. **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. The RD-side baseline closes that loop.
+
+> **Slice 025 — stable across slices within a session; refreshed on trigger.** The perf baseline is a **project-level** artifact (`.peaks/_runtime/<sessionId>/qa/perf-baseline.md`) and is **stable across slices within a session**. It is regenerated only when the slice diff matches the refresh trigger table (see `peaks-qa/references/qa-perf-test-plan.md`). Slices that do not trigger a refresh reference the existing baseline by hash from the per-slice `qa/performance-findings-<rid>.md` (not by regenerating the baseline). The CLI is `peaks workflow plan read|refresh|detect-trigger perf --project <repo>`; the RD-side `peaks perf baseline --apply` workflow below still scaffolds the initial file but the canonical refresh path post-slice-025 is the new `peaks workflow plan refresh` primitive.
+
+**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/_runtime/<sessionId>/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/_runtime/<sessionId>/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.

package/skills/peaks-rd/references/matt-pocock-integration.md

@@ -0,0 +1,11 @@
+## Matt Pocock skills integration (RD)
+
+> Body of `## Matt Pocock skills integration`. Engineering methods from `mattpocock/skills` can inform RD work but never replace Peaks-Cli gates. Inspect upstream skill content before applying any method.
+
+- `diagnose` — root-cause investigation before fixing
+- `triage` — prioritize bug surface area
+- `tdd` — drive implementation from failing tests
+- `improve-codebase-architecture` — opportunistic refactor framing
+- `prototype` — throwaway exploration before committing to a slice
+
+These are references only; Peaks-Cli RD gates remain authoritative for handoff, acceptance, and slice closure.

package/skills/peaks-rd/references/mock-data-placement.md

@@ -0,0 +1,40 @@
+# Mock data placement rules
+
+> Body of `## Mock data placement rules` + `### Framework-to-mock-directory mapping` + `### Hard rules` + `### Verification gate`. **BLOCKING — framework-aware.**
+
+When the project-scan in `.peaks/_runtime/<sessionId>/rd/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
+
+## Framework-to-mock-directory mapping
+
+| Project-scan finding | Mock location | Notes |
+|---|---|---|
+| Umi (`@umijs/max`, `.umirc.ts`) | `mock/*.ts` | Umi's built-in mock directory. Zero config, auto-reload. |
+| Next.js (`next.config.*`) | `__mocks__/` or MSW handlers | Match the project's existing pattern |
+| Vite (`vite.config.*`) | `src/mock/` | Service-layer mock files with typed fixtures |
+| CRA / Webpack | `src/__mocks__/` | Match the project's existing pattern |
+
+## Hard rules
+
+1. **Umi project → `mock/*.ts`**: If the project-scan says the build tool is Umi, mock data MUST go in the `mock/` directory at project root. This is Umi's built-in feature — it intercepts requests matching the defined path and method. Do NOT write `Promise.resolve(mockData)` in component files or service files for Umi projects.
+
+2. **Never inline mock data in component files**: Mock data, fixture objects, and stub responses belong in dedicated mock files. Components should receive data through their normal channels (props, API calls via services). Writing `const mockData = [...]` inside a `.tsx` file is prohibited.
+
+3. **Mock files must export TypeScript interfaces**: Every mock response type must be exported so RD implementation and QA test-cases can import the same contract. See peaks-solo's "Frontend-only development mode" for the full mock-to-real migration pattern.
+
+4. **Every mock file must be marked**: Add `// MOCK: Replace with real API call when swagger.json is available` at the top of every mock file.
+
+5. **Mock data must be realistic**: No `"test"`, `"foo"`, `"123"` values. Use plausible content that resembles production data.
+
+## Verification gate (after mock creation)
+
+```bash
+# If project-scan detected Umi, verify mock/ directory was used
+ls mock/*.ts 2>&1
+# Expected: one or more .ts files in mock/
+# "No such file" → BLOCKED. Umi projects must use mock/ directory.
+
+# Verify no inline mock data in component files
+grep -r "const mock\|mockData\|mock_data\|MOCK_DATA" src/ --include="*.tsx" --include="*.ts" -l 2>&1
+# Expected: no matches (or only in dedicated mock files / test files)
+# Any match in a component → BLOCKED. Move to mock/ (Umi) or src/mock/ (Vite).
+```

package/skills/peaks-rd/references/ocr-integration.md

@@ -0,0 +1,229 @@
+# OCR (Open Code Review) integration
+
+> Soft-optional second-opinion code review for peaks-rd Gate B3.
+> Mirrors the ECC 64-agents pattern (spec §7.2): peaks-cli ships
+> `@alibaba-group/open-code-review` as an **`optionalDependency`**
+> (was promoted to `dependencies` in 2.0.1 and reverted in 2.0.3
+> because its postinstall downloads a Go binary via HTTPS and would
+> otherwise abort `npm i -g peaks-cli` in restricted/proxied
+> environments). The LLM endpoint config still lives under
+> `peaksConfig.ocr.llm` in the user's `~/.peaks/config.json` (single
+> source of truth, user-managed). When the user installs + configures
+> ocr, the wrapper turns its output into structured `code-review.md`
+> evidence; when missing, peaks-rd proceeds LLM-only and the slice
+> ships without the second opinion.
+
+## What ocr is
+
+[Open Code Review](https://github.com/alibaba/open-code-review) is
+an AI-powered code review CLI from Alibaba. It reads git diffs,
+sends the changed files to a **user-configured LLM endpoint**
+(OpenAI- or Anthropic-compatible), and emits structured
+line-precise review comments. It is NOT a hosted service —
+all LLM traffic goes to the user's own configured endpoint.
+
+Distribution: npm `@alibaba-group/open-code-review` (Go binary
+inside; the npm postinstall downloads the platform-specific
+binary from GitHub Releases).
+
+## Why peaks-rd uses it (soft-optional)
+
+The default peaks-rd code-review evidence is produced by the
+main RD LLM (or the `code-reviewer` sub-agent in the parallel
+fan-out). That's one pair of eyes. When ocr is available, the
+wrapper adds a **second pair** — an independent LLM tuned for
+code review — and the two reviews are merged into the same
+`code-review.md` file. Soft-optional: if ocr isn't installed or
+configured, RD proceeds with the LLM-only review and the slice
+ships without the second opinion.
+
+## Install
+
+`@alibaba-group/open-code-review` is an **`optionalDependency`** of
+peaks-cli 2.0.3+ (was a required `dependency` in 2.0.1/2.0.2; reverted
+because the postinstall downloads a Go binary via HTTPS, which fails in
+restricted/proxied environments and would otherwise abort
+`npm i -g peaks-cli`). peaks-cli does NOT auto-install it. To enable
+the second-opinion review:
+
+```bash
+npm i -g @alibaba-group/open-code-review
+```
+
+(Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review`
+so the binary download script can run.) Verify with:
+
+```bash
+peaks code-review detect-ocr --json
+```
+
+Five possible states:
+
+| state | Meaning | Recovery |
+|---|---|---|
+| `ready` | Installed + binary downloaded + peaks-cli's `peaksConfig.ocr.llm` valid | Nothing — `run-ocr` will work. |
+| `package-missing` | npm dep not installed (peaks-cli 2.0.3+ ships with ocr as an `optionalDependency`, so the common cause is the user has not installed it yet, or it was removed from node_modules) | `npm i -g @alibaba-group/open-code-review` (peaks-cli no longer auto-installs it; under pnpm also run `pnpm approve-builds @alibaba-group/open-code-review`) |
+| `binary-missing` | npm dep present but Go binary did not download | `pnpm approve-builds @alibaba-group/open-code-review`, OR run `node node_modules/@alibaba-group/open-code-review/scripts/install.js`, OR manually fetch from https://github.com/alibaba/open-code-review/releases and place the binary at the path shown in `nextActions[2]`. |
+| `config-missing` | binary present but `peaksConfig.ocr.llm` is empty or partial | See "Configure" below. |
+| `detection-failed` | Unexpected error during detection | Inspect stderr; re-run probe. |
+
+## Configure (one-time, per user) — peaks-cli does NOT auto-configure
+
+The LLM endpoint config is **user-maintained inside peaks-cli's own
+config** at `~/.peaks/config.json` under the `ocr.llm` key. The user
+is the only party that touches their LLM token / URL / model. peaks-cli
+never auto-writes the config and never writes `~/.opencodereview/config.json`.
+
+```bash
+# 1) Print the JSON snippet to paste (read-only, no side effects):
+peaks code-review config-template --json
+
+# 2) Paste the snippet into ~/.peaks/config.json under "ocr.llm",
+#    replace <your-api-key> with your real key. Alternatively,
+#    set keys one at a time:
+peaks config set --key ocr.llm.url --value 'https://api.example.com/v1/messages'
+peaks config set --key ocr.llm.authToken --value '<your-key>'
+peaks config set --key ocr.llm.model --value 'claude-3-5-sonnet-latest'
+peaks config set --key ocr.llm.useAnthropic --value 'true'
+peaks config set --key ocr.llm.authHeader --value 'x-api-key'
+
+# 3) Verify readiness (peaks-rd also runs this automatically):
+peaks code-review detect-ocr --json
+```
+
+### Field map: `peaksConfig.ocr.llm` ↔ ocr subprocess env vars
+
+peaks-rd calls ocr with the `peaksConfig.ocr.llm` values **injected as
+env vars** (ocr's highest-priority config path). The mapping is:
+
+| `peaksConfig.ocr.llm.*` | Spawn env var | Notes |
+|---|---|---|
+| `url` | `OCR_LLM_URL` | HTTPS endpoint, no embedded credentials |
+| `authToken` | `OCR_LLM_TOKEN` | Sensitive — stored only in the user-layer `~/.peaks/config.json`; `peaks config get` redacts this field |
+| `model` | `OCR_LLM_MODEL` | e.g. `claude-3-5-sonnet-latest` |
+| `useAnthropic` | `OCR_USE_ANTHROPIC` | Boolean; serialised as `"true"` / `"false"` |
+| `authHeader` | `OCR_LLM_AUTH_HEADER` | One of `authorization` (default Bearer), `x-api-key` (for `sk-ant-*` keys), or `bearer` |
+
+The `~/.opencodereview/config.json` file the user might have set up
+for 2.0.0 is no longer consulted by peaks-cli. The user may delete it
+at their discretion — the ocr subprocess ignores the file when peaks-
+cli's env vars are present (and the env-var surface is highest priority).
+
+### Required vs optional fields
+
+The minimum for `state == "ready"` is the **url + authToken + model**
+triple. `useAnthropic` and `authHeader` are optional; `authHeader`
+defaults to `authorization` (Bearer) inside the ocr subprocess, but
+`sk-ant-*` keys require `authHeader: "x-api-key"`.
+
+When the user has not yet populated the config, `detect-ocr` returns
+`state: "config-missing"` with `missingKeys: ["ocr.llm.url",
+"ocr.llm.authToken", "ocr.llm.model"]` and a templated
+`nextActions[1]` payload that includes the JSON snippet to paste.
+
+## Use from peaks-rd (LLM workflow)
+
+In Gate B3 (code review evidence), before writing
+`.peaks/_runtime/<sid>/rd/code-review.md`, the code-reviewer
+sub-agent runs:
+
+```bash
+# 1. Detect
+peaks code-review detect-ocr --json
+# 2. If state == "ready", run the review
+peaks code-review run-ocr --json --project . --from origin/main --to HEAD
+```
+
+The `run-ocr` envelope is:
+
+```jsonc
+{
+  "ok": true,
+  "command": "code-review.run-ocr",
+  "data": {
+    "spawned": true,
+    "state": "ready",
+    "exitCode": 0,
+    "stdout": "...",
+    "stderr": "",
+    "durationMs": 12345,
+    "parsed": {
+      "findings": [
+        { "file": "src/foo.ts", "line": 42, "severity": "minor", "message": "..." }
+      ]
+    },
+    "warnings": [],
+    "nextActions": []
+  },
+  ...
+}
+```
+
+Merge `data.parsed.findings` into `code-review.md` under
+`## Second opinion (ocr)`. Cite each finding by file + line.
+Reconcile disagreements with the LLM-only review explicitly
+(don't silently drop one source).
+
+## Soft-fail policy
+
+`peaks code-review run-ocr` **never** sets a non-zero exit code,
+even when ocr is not ready or the subprocess fails. The envelope
+`ok` field carries the success signal; the caller (peaks-rd) is
+expected to pattern-match on `data.state` and proceed without the
+second opinion if needed. This matches the ECC 64-agents
+soft-fail policy and the peaks-cli "minimal user operation"
+tenet — missing ocr should never block a slice.
+
+## Security
+
+- ocr sends your changed files to whatever LLM endpoint you
+  configure. Treat this the same as any external code-review
+  tool you opt into: don't point it at a free public endpoint
+  for proprietary code; use a vendor / self-hosted endpoint with
+  appropriate data controls.
+- peaks-cli does NOT auto-configure ocr. Your `ocr.llm.authToken`
+  is yours. Rotate as needed. The token is stored only in the
+  user-layer `~/.peaks/config.json` (project layer rejects writes
+  to any key matching `isSensitiveConfigPath`), and
+  `peaks config get` redacts it as `***`.
+- peaks-cli's wrapper records ocr's `stdout` verbatim in the
+  envelope (and in `code-review.md` when peaks-rd merges
+  findings). Don't put secrets in your code being reviewed.
+- The `peaks code-review config-template` snippet embeds the
+  placeholder string `<your-api-key>`; the user is expected to
+  replace it before pasting.
+
+## Failure modes (real)
+
+These are the actual failure modes the wrapper has been
+dogfooded against:
+
+1. **Network blocked from GitHub Releases** during postinstall →
+   `binary-missing`. peaks-cli still runs cleanly because ocr
+   is detected as not-ready; user manually fetches the binary
+   and places it at `nextActions[2]`'s path.
+2. **pnpm-installed peaks-cli** → ocr postinstall blocked by
+   pnpm's safe-by-default policy → `binary-missing`. Recover
+   with `pnpm approve-builds @alibaba-group/open-code-review`.
+3. **No / partial LLM config** → `config-missing` with
+   `missingKeys` listing the unpopulated fields. Recover by
+   pasting the `peaks code-review config-template` output into
+   `~/.peaks/config.json` (or by `peaks config set` per-key).
+4. **Wrong key / wrong endpoint** → ocr subprocess exits non-zero;
+   wrapper soft-fails (`ok: false`, `warnings[0]` includes the
+   exit code, `stderr` carries ocr's own error message).
+5. **User 2.0.0 → 2.0.1 migration** — they configured
+   `~/.opencodereview/config.json` for 2.0.0; peaks-cli 2.0.1
+   no longer reads that file. They paste the same values into
+   `~/.peaks/config.json` under `ocr.llm` (peaks-cli handles the
+   camelCase conversion in the template).
+
+## See also
+
+- ocr upstream: https://github.com/alibaba/open-code-review
+- peaks-cli source: `src/services/code-review/ocr-service.ts`,
+  `src/cli/commands/code-review-commands.ts`
+- peaks-cli config schema: `src/services/config/config-types.ts`
+  (`OcrLlmConfig`, `OcrConfig`, `PeaksConfig.ocr?`)
+- ECC 64-agents soft-optional pattern (mirrored):
+  `src/services/agent/ecc-agent-service.ts`

package/skills/peaks-rd/references/openspec-cli.md

@@ -0,0 +1,62 @@
+# OpenSpec CLI for Peaks RD
+
+Peaks RD reads OpenSpec change packs through the Peaks CLI rather than re-parsing markdown or spawning subprocesses by hand. The CLI returns the same stable envelope shape (`{ ok, command, data, warnings, nextActions }`) so RD can capture it as artifact JSON.
+
+> **Slice #016 (2026-06-09)**: this document used to live at `openspec-mcp-cli.md` and contained a section on the now-retired peaks-cli MCP install / call verbs. The MCP subsystem was retired in slice #016; the LLM's own tool list is now the source of truth for installed MCPs. The OpenSpec CLI recipes below are unchanged.
+
+## Loading an existing OpenSpec change as RD input
+
+When the target repository already has `openspec/changes/<id>/`, project the change pack into the RD input shape before slicing:
+
+```bash
+peaks openspec show <change-id> --project <repo> --json
+peaks openspec to-rd <change-id> --project <repo> --json
+```
+
+- `show` returns the parsed proposal sections, tasks progress, and detected `specs/<capability>/` capabilities.
+- `to-rd` returns `{ changeId, acceptance, whatChanges, dependencies, risks, outOfScope, commitBoundaries[] }`. RD slice acceptance must be derived from `acceptance`; out-of-scope items from `outOfScope` must remain out of scope in the slice spec.
+
+If the change does not exist, `to-rd` returns `OPENSPEC_CHANGE_NOT_FOUND`. Treat that as a blocker, not an excuse to free-form a slice spec.
+
+## Rendering a new OpenSpec change pack from RD work
+
+When RD plans a non-trivial change in a repository that already uses `openspec/`, generate the change pack first (default dry-run), inspect the rendered markdown, and only then write it:
+
+```bash
+peaks openspec render --request <jsonPath> --project <repo> --json
+peaks openspec render --request <jsonPath> --project <repo> --apply --json
+```
+
+The request JSON shape is:
+
+```json
+{
+  "changeId": "<kebab-case>",
+  "why": "...",
+  "whatChanges": ["..."],
+  "outOfScope": ["..."],
+  "dependencies": ["..."],
+  "risks": ["..."],
+  "acceptanceCriteria": ["..."],
+  "tasks": [{ "heading": "1. <section>", "todos": ["..."], "doneItems": ["..."] }],
+  "design": "<raw markdown>"
+}
+```
+
+`render --apply` refuses to overwrite an existing change directory unless `--overwrite` is passed. Treat that refusal as intentional.
+
+## Library docs lookup via the LLM's own MCP tool list (slice #016)
+
+When RD needs external library or API docs, the consuming LLM checks its own tool list for an MCP entry (typically `mcp__plugin_context7_context7__*` for Context7). If present, the LLM invokes the tool by name directly (`resolve-library-id` then `query-docs` are the canonical Context7 tool names). If absent, the LLM tells the user the install command:
+
+```bash
+# Claude Code:
+claude mcp add context7 -- npx @upstash/context7-mcp
+# Restart the IDE after install; the runtime picks up the new server only after a fresh process.
+```
+
+peaks-cli does not install MCPs on the user's behalf as of slice #016; the LLM is the executor and the IDE is the dispatcher. Evidence of the lookup (sanitized query + response summary) goes into the RD artifact, not full network bodies or secrets.
+
+## Boundary
+
+Peaks RD must not hand-edit `openspec/changes/**` or `~/.claude/settings.json` directly. All OpenSpec writes go through the CLI commands above with dry-run preview, explicit confirmation, and Peaks-managed source labels.

package/skills/peaks-rd/references/parallel-review-fanout.md

@@ -0,0 +1,90 @@
+# Parallel review fan-out (RD)
+
+> Body of `## Parallel review fan-out`. **When RD reaches the end of implementation, the three review activities (code review, QA test-cases draft, AND karpathy review) run in parallel via `peaks sub-agent dispatch <role>` (then executing the returned toolCall), not sequentially.** This is the same fan-out pattern peaks-solo uses for the post-PRD swarm. RD itself, when it is the main loop, behaves as a sub-agent orchestrator: it issues 3 `peaks sub-agent dispatch` calls in a single message and waits for all to return before aggregating findings and transitioning to `qa-handoff`.
+
+**v2.12.0 collapse (Group A — Tier 1+2+3):** the previous 4-way fan-out (slice 004) plus the appended `karpathy-reviewer` (slice 5/6) totalled **5 sub-agents**. The `security-reviewer` and `perf-baseline-reviewer` slots moved out of the RD fan-out into two new standalone audit skills:
+
+- `peaks-security-audit` — CLI: `peaks security-audit run`. Writes `.peaks/_runtime/<sessionId>/audit/security.md`. Required RD-side prereq `AUDIT_SECURITY`.
+- `peaks-perf-audit` — CLI: `peaks perf-audit run`. Writes `.peaks/_runtime/<sessionId>/audit/perf.md`. Required RD-side prereq `AUDIT_PERF`.
+
+Both audit skills consume the immutable peaks-prd handoff (`prd/handoff.md`) and the project-scoped audit templates under `.peaks/project-scan/{security-template, perf-template, audit-output-schema}.md`. The handoff presence is enforced by the `AUDIT_REQUIRES_HANDOFF` prereq. The 1-minor-release back-compat window (`v2.12.0`) keeps the old `rd/{security-review,perf-baseline}.md` paths readable via `mustContainAny` — see `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (8 cases) and `tests/unit/artifact-prerequisites-typed.test.ts`.
+
+The current fan-out is therefore **3 sub-agents**:
+
+1. `code-reviewer` (always runs for feature / refactor / bugfix)
+2. `qa-test-cases-writer` (always runs for feature / refactor / bugfix)
+3. `karpathy-reviewer` (always runs for feature / refactor / bugfix — the **hard Karpathy-Gate**)
+
+Config / docs / chore: no fan-out (no review surface). Document N/A in the request artifact.
+
+**Why 3 sub-agents (v2.12.0):** the original 3-way fan-out (code-review + security-review + perf-baseline — slice 002) cut the RD→QA wall-clock by running 3 LLM writes in parallel. Slice 004 added `qa-test-cases-writer` (4-way), slice 5/6 added `karpathy-reviewer` (5-way). The v2.12.0 collapse moves `security-reviewer` + `perf-baseline-reviewer` out of the fan-out into standalone pre-RD audit passes; the remaining 3 sub-agents are dispatched from the RD main loop as before. Wall-clock: the security + perf audit work shifts to pre-RD / pre-QA and runs as `peaks sub-agent dispatch peaks-security-audit` + `peaks sub-agent dispatch peaks-perf-audit` — those are also parallelizable, so the end-to-end wall-clock is unchanged or improved.
+
+**When to fan out:**
+- Feature / refactor slices: all three sub-agents always run.
+- Bugfix slices: all three sub-agents always run (no perf-shaped conditional — perf audit is now a separate skill that the LLM decides to dispatch when the bug is perf-shaped).
+- Config / docs / chore slices: no fan-out (no review surface). Document N/A in the request artifact.
+
+**The dispatch template:**
+
+```
+peaks sub-agent dispatch <role> \
+  --prompt "<role contract below>, plus runtime args: project=<repo>, session-id=<session-id>, request-id=<rid>.
+             Write your evidence file at .peaks/_runtime/<sessionId>/<evidence-path> and return ONLY the path.
+             Do not call Skill(...). Do not set presence. Do not prompt the user. Do not commit, push,
+             install hooks, or mutate settings.json. Do not edit any source file — review only.
+             While running, call peaks sub-agent heartbeat --record <dispatchRecordPath>
+             --status running --progress <pct> --note \"<text>\" at least every 30 seconds;
+             on completion call --status done --progress 100 --note 'completed'." \
+  --request-id <rid> --session-id <session-id> --project <repo> --json
+```
+
+Note: sub-agent 1 (code-reviewer) and sub-agent 3 (karpathy-reviewer) write to `rd/<evidence-path>`; sub-agent 2 (qa-test-cases-writer) writes to `qa/test-cases/<rid>.md` (QA's dir). The role name in the description differentiates them.
+
+**Sub-agent 1 — code-reviewer (always runs for feature / refactor / bugfix):**
+- Read the git diff for this slice (`git diff main...HEAD` or equivalent).
+- Read `.peaks/_runtime/<sessionId>/prd/handoff.md` for slice intent (v2.11.0: the immutable peaks-prd handoff replaces `rd/tech-doc.md`). Verify the handoff hash matches the dispatched value before proceeding.
+- Inspect for: correctness, type safety, error handling, mutation patterns, file-size, naming, dead code, regressions, contract drift.
+- Output: `.peaks/_runtime/<sessionId>/rd/code-review.md` with sections: Summary, Findings, Required Fixes, Recommended, Verdict.
+- Required for Gate B3.
+- **v2.11.0 Tier 7 (Group D):** the code-reviewer dispatch goes through the **ECC bridge** (`src/services/code-review/ecc-bridge.ts`). The parent RD loop invokes the Agent tool with `subagent_type: "everything-claude-code:code-review"` and receives a structured envelope `{ passed, violations[], gateAction }`. The bridge adapter (`adaptEccEnvelopeToRdCodeReview`) renders that envelope into the canonical `rd/code-review.md` markdown shape that Gate B3 reads (`mustContain: ['## Findings', 'CRITICAL']`). The pre-Tier-7 5-state detect (`detectEcc`: ready / plugin-missing / agent-missing / dispatch-failed / envelope-malformed) soft-fails to inline review on any non-ready state — TXT note `code-review-ecc-degraded-to-inline`. Same soft-fail philosophy as `ocr-service.ts` and `detectOcr`.
+
+**Sub-agent 2 — qa-test-cases-writer (always runs for feature / refactor / bugfix):**
+- Read the git diff and the PRD acceptance criteria.
+- Draft the test plan: enumerate every acceptance criterion as a separate test case; for each, write a `ts` snippet, assert the expected outcome, link to the PRD criterion by ID.
+- Include the standard sections: ## Test cases, ## Test case summary, ## Mandatory validation gates, ## Regression matrix, ## Verdict.
+- Output: `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md`.
+- Required for Gate C (RD-side qa-handoff transition). When this file is present at RD's qa-handoff transition, QA's main loop can skip its own "draft test plan" step and proceed directly to "execute pre-drafted test plan + write test-report + verdict".
+
+**Sub-agent 3 — karpathy-reviewer (always runs for feature / refactor / bugfix — the hard gate):**
+- Inspect the diff + handoff against the 4 Karpathy-guidelines.
+- Read `.peaks/_runtime/<sessionId>/prd/handoff.md` (v2.11.0: architecture summary — the immutable peaks-prd handoff replaces `rd/tech-doc.md`).
+- Output: `.peaks/_runtime/<sessionId>/rd/karpathy-review.md` containing a `## Karpathy-Gate` header and the 4 guideline section markers (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution).
+- Required for the `KARPATHY_REVIEW` prereq. The transition CLI gate reads those markers and refuses `rd:qa-handoff` when the file is missing or the markers are absent.
+- See `references/rd-fanout-contracts.md` §"karpathy-reviewer contract" for the JSON envelope shape + file format.
+
+**Hard prohibitions on all 3 sub-agents:**
+- Do NOT call `Skill(skill="...")` — would re-enter RD or another skill and break the fan-out.
+- Do NOT call `peaks skill presence:set` — only the main RD loop owns presence.
+- Do NOT open interactive user prompts. If something is unclear, return `blocked` and let the main loop handle the user.
+- Do NOT commit, push, install hooks, or mutate settings.json.
+- Do NOT edit any source file under src/, tests/, skills/, bin/, scripts/, docs/, schemas/. Review only.
+
+**Aggregation (after all 3 sub-agents return):**
+
+1. Restore presence: `peaks skill presence:set peaks-rd --project <repo> --gate review-fan-out-converged`
+2. Run the 3 `ls` checks (Gate B3 code-review, Gate C2 qa-test-cases, KARPATHY_REVIEW prereq).
+3. Read each evidence file. Aggregate CRITICAL/HIGH across code-review.
+4. If any CRITICAL or HIGH finding exists: fix in the main RD loop, then re-launch ONLY the affected sub-agent(s) to verify the fix. Loop until clean, or mark as blocked if the issue cannot be resolved.
+5. For qa-test-cases: the file is now pre-drafted by sub-agent 2. The main RD loop does NOT re-draft it; it only verifies (a) the file exists, (b) every PRD acceptance criterion is enumerated, (c) every `ts` test snippet is syntactically valid. If incomplete, fix it inline in the main RD loop (small edits only) OR re-launch the sub-agent (large re-drafts).
+6. Re-run all 3 `ls` checks to confirm the evidence files are present and not empty.
+7. Confirm the audit prereqs (`AUDIT_SECURITY` + `AUDIT_PERF` + `AUDIT_REQUIRES_HANDOFF`) are satisfied — those are produced by the standalone audit skills, not the fan-out.
+8. Only then transition `peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json`.
+
+**Degradation when a sub-agent fails or returns blocked:**
+- code-review sub-agent fails: fall back to inline RD code review. TXT handoff note: `code-review-subagent-degraded-to-inline`.
+- code-review sub-agent runs the ECC bridge but ECC is unavailable (plugin-missing / agent-missing / dispatch-failed / envelope-malformed per `detectEcc`): fall back to inline RD code review. TXT handoff note: `code-review-ecc-degraded-to-inline`.
+- qa-test-cases sub-agent fails: fall back to inline QA test-case drafting at the start of QA's main loop. TXT note: `qa-test-cases-subagent-degraded-to-inline-qa-draft`.
+- karpathy-reviewer sub-agent fails: NOT degradeable — its failure blocks qa-handoff. Per karpathy §1 Think Before Coding + §3 Surgical Changes, the file MUST exist with the gate header + at least one guideline marker.
+- 2 or more fail: do not hand off as clean; transition to `qa-handoff` with `--allow-incomplete --reason "<degradation>"` OR block.
+
+**Why this works (3-loop repair closure):** the original 3-loop repair pain was caused by perf being QA-only. Slice 002 moved perf to RD-side fan-out; slice 004 extended the same parallel pattern to QA test-cases so the QA→verdict loop is also faster on the first attempt. The v2.12.0 collapse preserves the parallel pattern but moves `security-reviewer` + `perf-baseline-reviewer` out of the RD-side fan-out into standalone pre-RD audit passes (`peaks-security-audit` + `peaks-perf-audit`). Those passes are themselves parallelizable, so the end-to-end wall-clock is preserved or improved.

package/skills/peaks-rd/references/rd-context-governance.md

@@ -0,0 +1,36 @@
+# Sub-agent context governance (RD)
+
+> Body of `## Sub-agent context governance` + `### G7` + `### G8.6` + `### G9`. RD sub-agent prompt template MUST include the G7 path convention + G8.6 share protocol.
+
+## G7 — RD sub-agent protocol
+
+1. Write artifact to `.peaks/_sub_agents/<sessionId>/artifacts/<rid>-rd-001.md` (path convention mandatory).
+2. Call `peaks sub-agent dispatch --write-artifact <path>` (or via the dispatch CLI flag) to register ArtifactMeta.
+3. The dispatch record stores only `path + size + sha256 + status + contentInlined:false + summary` — main LLM sees ~200 chars/sub-agent.
+
+## G8.6 — RD sub-agent prompt template (mandatory)
+
+Sub-agent prompts dispatched by peaks-rd must include:
+
+```
+You are sub-agent role rd, batch <batchId>.
+
+PROTOCOL (mandatory):
+1. On start: peek at shared channel: `peaks sub-agent shared-read --batch <batchId> --json`
+   to see what other sub-agents in this batch have shared so far.
+2. While running: if you find a blocker or partial work, write share entry
+   `peaks sub-agent share --key "rd.found-blocker" --value {"reason": "..."}`.
+3. On completion: write share entry
+   `peaks sub-agent share --key "rd.completed" --value <artifact-meta>` BEFORE the
+   final `peaks sub-agent heartbeat --status done` heartbeat (RL-23 strong constraint).
+4. The shared channel is your only visibility into sibling sub-agents.
+   Do NOT attempt to read other sub-agents' dispatch records directly.
+```
+
+## G9 — RD prompt size self-check
+
+Before dispatching a sub-agent, RD self-checks prompt size:
+- < 50%: pass through.
+- 50-75%: soft warn (consider `--use-headroom`).
+- 75-80%: soft warn + `warnings: ["CONTEXT_NEAR_LIMIT"]` (mandatory suggest `--use-headroom`).
+- 80%+: reject (CLI 兜底 returns `code: "PROMPT_TOO_LARGE"`). Use `--force` at CLI only when overriding; hook layer will still reject (RL-30).