peaks-cli 1.4.1 → 2.0.0

package/skills/peaks-qa/SKILL.md

@@ -79,15 +79,15 @@ When this skill is running in the main Claude session (not as a sub-agent), befo
 
 ## Mandatory per-request artifact
 
-Every QA invocation — feature, bug, refactor, clarification — must write **three separate files** (test cases + test report + request artifact). Do not merge them into one. Each serves a different reader.
+Every QA invocation — feature, bug, refactor, clarification — must write **three separate files** (test cases + test report + request artifact) under `.peaks/<session-id>/qa/` (canonical placeholder: `.peaks/<session-id>/qa/requests/<request-id>.md`; runtime path is `.peaks/_runtime/<session-id>/qa/...`). Do not merge them into one. Each serves a different reader.
 
-→ see `references/artifact-per-request.md` for the 3-file contract (test cases / test report / request artifact).
+External-skill guard: when QA references external material (mattpocock/skills, gstack, superpowers, etc.) it is reference only — do not execute upstream installer, do not persist sensitive upstream examples. Peaks-Cli artifacts and Peaks-Cli acceptance criteria remain authoritative.
 
-## Default runbook
+→ see `references/artifact-per-request.md` for the 3-file contract and the do-not-execute upstream guard.
 
-The default sequence the QA skill should execute. Do not skip the boundary check, the unit test gate, the validation report, or — when frontend is in scope — the Playwright MCP browser gate. The full 10-step runbook (steps #0–#9) with every CLI invocation, the rd-side pre-drafted test-cases optimization, the dev-server lifecycle requirement, the security/performance check discipline, and the 8 quality-gate CLI checks is in the references file.
+## Default runbook
 
-→ see `references/qa-runbook.md` for the full runbook.
+See `references/qa-runbook.md` for the full 10-step runbook (steps #0–#9) with every CLI invocation, the rd-side pre-drafted test-cases optimization, the dev-server lifecycle requirement, the security/performance check discipline, and the 8 quality-gate CLI checks.
 
 ## Transition verification gates (MANDATORY — run the command, see the output)
 
@@ -125,6 +125,8 @@ Before QA passes or returns work to RD, it must independently recheck the implem
 
 QA must generate test cases, not merely inspect existing ones. Every QA invocation that validates code changes must produce a test-case artifact at `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md`. Minimum categories: Unit / Integration / UI regression. Each test case MUST have an `**Acceptance:**` field linking to PRD acceptance IDs (A1, A2, ...). The `peaks scan acceptance-coverage` command enforces coverage.
 
+**Pre-drafted test cases (slice 004 optimization):** when peaks-rd's 4-way parallel fan-out ran a `qa-test-cases-writer` sub-agent, the test plan is pre-drafted at `.peaks/<id>/qa/test-cases/<rid>.md` and shipped through the rd:qa-handoff gate. QA main loop is aware of this and treats the pre-drafted file as the canonical starting point. **Missing** the pre-drafted file (sub-agent failed, or the slice was a config/docs/chore that did not fan out) → QA drafts it inline as before, falling back to the standard generation flow.
+
 → see `references/test-case-generation.md` for the full format + acceptance-linkage contract.
 
 ## Mandatory test-report output
@@ -137,7 +139,7 @@ Every QA invocation must produce a test-report artifact at `.peaks/_runtime/<ses
 
 QA cannot pass a change until the report contains evidence for every applicable gate. The 11 gates (0 test-case generation, 1 test-report, 2 unit tests, 3 API validation, 4 frontend browser validation, 5 browser-error feedback loop, 6 security check, 7 performance check, 8 library version regressions, 9 validation report, 10 acceptance coverage, 11 QA artifact lint) are mapped to Peaks-Cli Gates A/A2/A3/A4/B/C/D/E/F.
 
-If Playwright MCP is unavailable (not installed and the user has not authorized installation), mark the gate blocked with the missing capability. Screenshots, logs, manual steps, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
+If Playwright MCP is unavailable, the LLM checks its own tool list for the Playwright MCP server entry; if absent, the LLM tells the user the install command (`claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code) and marks the gate blocked with the missing capability. Screenshots, logs, manual steps, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
 
 ## Local intermediate artifacts
 
@@ -159,7 +161,7 @@ When capability discovery exposes `mattpocock/skills`, use `tdd` / `triage` / `g
 
 ## Codegraph regression focus
 
-QA may use `peaks codegraph affected --project <path> <changed-files...> --json` as regression-surface evidence. External analysis cannot pass QA by itself — treat output as untrusted supporting evidence.
+QA may use `peaks codegraph affected --project <path> <changed-files...> --json` as regression-surface evidence. External analysis cannot pass QA by itself — treat output as untrusted supporting evidence. External skill guidance cannot pass QA by itself — treat as supporting evidence, not a verdict. QA reads `.peaks/<session-id>/rd/codegraph-context.md` (or `qa/codegraph-context.md`) as input but never mutate agent settings, Claude settings, or hooks from it; QA does not commit `.codegraph/` artifacts or persist generated `.codegraph/` databases into git.
 
 → see `references/codegraph-regression-focus.md`.
 

package/skills/peaks-qa/references/artifact-per-request.md

@@ -1,11 +1,25 @@
 # QA per-request artifact contract
 
-> Body of `## Mandatory per-request artifact` (QA-flavored). Every QA invocation — feature, bug, refactor, clarification — must write **three separate files**. Do not merge them into one. Each serves a different reader:
+> Body of `## Mandatory per-request artifact` (QA-flavored). Every QA invocation — feature, bug, refactor, clarification — must write **three separate files**. Do not merge them into one. Each serves a different reader.
+
+## Required path
+
+The three files for any QA invocation land under the active session's `qa/` workspace, using the canonical placeholder `.peaks/<session-id>/qa/...` (e.g. `.peaks/<session-id>/qa/requests/<request-id>.md`).
 
 | # | File | Path | Reader | Content |
 |---|------|------|--------|---------|
-| 1 | Test cases | `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
-| 2 | Test report | `.peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
-| 3 | Request artifact | `.peaks/_runtime/<sessionId>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
+| 1 | Test cases | `.peaks/_runtime/<session-id>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
+| 2 | Test report | `.peaks/_runtime/<session-id>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
+| 3 | Request artifact | `.peaks/_runtime/<session-id>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
+
+## Required content
+
+The request artifact is the **verdict carrier** — it must include: QA verdict (`pass` / `return-to-rd` / `blocked`), the red-line audit outcome, links to the test-cases and test-report, the boundary check (acceptance items covered, gaps), and any cross-skill handoff notes for Solo. The test cases file enumerates every scenario with status; the test report summarises execution and links the security / performance / regression companion files.
+
+## Rules
+
+The 3-file split is load-bearing. Do not merge. Use the `<request-id>` PRD assigned (`YYYY-MM-DD-<kebab-slug>`). QA may also produce companion artifacts (regression matrix, sanitized browser evidence, security findings, performance findings) under the same `qa/` workspace and link them from these files. Sanitize MCP / network / browser evidence before writing. Do not commit unless the user or active profile authorizes durable retention. Verdict `pass` is blocked while any of the three files is missing or the request artifact is in `draft` / `running` state.
+
+## External-skill invocation guard
 
-The 3-file split is load-bearing. Do not merge. Use the `<request-id>` PRD assigned (`YYYY-MM-DD-<kebab-slug>`). QA may also produce companion artifacts (regression matrix, sanitized browser evidence, security findings, performance findings) under the same `qa/` workspace and link them from these files. Sanitize MCP / network / browser evidence before writing. Do not commit unless the user or active profile authorizes durable retention. Verdict `pass` is blocked while any of the three files is missing or the request artifact is in `draft` / `running` state.
+When QA references external material (mattpocock/skills, gstack, superpowers, etc.) treat it as reference only: do not execute upstream installer, do not run upstream installer commands, do not persist sensitive upstream examples to the working tree. Peaks-Cli artifacts, Peaks-Cli gates, and Peaks-Cli acceptance criteria remain authoritative.

package/skills/peaks-qa/references/qa-perf-test-plan.md

@@ -7,14 +7,14 @@
 > `qa/performance-findings-<rid>.md` references this baseline by path +
 > hash.
 
-## Location
+## File location
 
 `.peaks/_runtime/<sessionId>/qa/perf-baseline.md`. The CLI is
 `peaks workflow plan read perf --project <repo> --json` /
 `peaks workflow plan refresh perf --project <repo> --apply` /
 `peaks workflow plan detect-trigger --project <repo> --rid <rid> --json`.
 
-## Generation workflow
+## Perf generation workflow
 
 1. `peaks workflow plan read perf --project <repo> --json` — return the
    existing baseline envelope. When missing, proceed to step 2.
@@ -30,7 +30,7 @@
    (lighthouse / k6 / autocannon output) — see peaks-rd's
    `mandatory-perf-baseline.md` for the RD-side measurement workflow.
 
-## Content schema (deterministic — body is normalized before hashing)
+## Perf content schema (deterministic)
 
 - `## CLI Command Inventory` — auto-enumerated from
   `src/cli/commands/*-commands.ts`. Sorted alphabetically.
@@ -39,7 +39,7 @@
   actual numbers (CLI does not call measurement tools).
 - `## Thresholds` — placeholder; RD fills per-route thresholds.
 
-## Refresh trigger table (shared with security plan)
+## Perf refresh trigger table (shared with security plan)
 
 | Signal | Reason string | Re-generates the baseline? |
 |---|---|---|
@@ -51,7 +51,7 @@
 | devDependencies change only | (none) | no — locked Q1 default |
 | Pure text edits to `rd/*` or `qa/test-cases/*` | (none) | no |
 
-## Back-compat (1 minor release)
+## Perf back-compat (1 minor release)
 
 The pre-slice-025 non-suffixed `qa/performance-findings.md` is still
 accepted by `peaks workflow verify-pipeline` Gate C during the
@@ -59,7 +59,7 @@ accepted by `peaks workflow verify-pipeline` Gate C during the
 (`src/services/workflow/artifact-paths.ts`) handles the fallback and
 emits a `legacy-redirect` warning.
 
-## CLI surface recap
+## Perf CLI surface recap
 
 | Command | Returns | JSON shape |
 |---|---|---|

package/skills/peaks-qa/references/qa-runbook.md

@@ -1,4 +1,4 @@
-# Default runbook (QA)
+## Default runbook (QA)
 
 > Body of `## Default runbook` + numbered runbook steps #0–#9. The default sequence the QA skill should execute. Do not skip the boundary check, the unit test gate, the validation report, or — when frontend is in scope — the Playwright MCP browser gate.
 

package/skills/peaks-rd/SKILL.md

@@ -15,9 +15,9 @@ Peaks-Cli RD owns engineering analysis, implementation planning, and refactor ex
 
 ## Hard contracts for browser self-test (BLOCKING — read before any browser_take_screenshot / login flow)
 
-For frontend or UI-affecting slices, RD's self-test uses the Playwright MCP headed browser. Two contracts (1) self-test screenshots land under `.peaks/_runtime/<sessionId>/qa/screenshots/`, (2) login / CAPTCHA / SSO / MFA is a hard block — surface with `AskUserQuestion` and pick one of three paths. The full contract is identical in spirit to `peaks-qa`'s; RD and QA share the headed-browser path.
+For frontend / UI-affecting slices, RD's self-test uses the Playwright MCP headed browser. LLM checks its own tool list for the Playwright MCP entry; if absent, surface the install command (`claude mcp add playwright -- npx @playwright/mcp@latest`) and report the gate blocked. Do not silently downgrade to screenshots-only, manual steps, or chrome-devtools-mcp. Two contracts: (1) self-test screenshots land under `.peaks/_runtime/<sessionId>/qa/screenshots/`, (2) login / CAPTCHA / SSO / MFA is a hard block — surface with `AskUserQuestion`. Same in spirit as `peaks-qa`'s; RD and QA share the headed-browser path.
 
-→ see `references/browser-self-test-contracts.md` for the full contract + AskUserQuestion options.
+→ see `references/browser-self-test-contracts.md`.
 
 ## Sub-agent dispatch (when launched by peaks-solo swarm)
 
@@ -44,15 +44,13 @@ When this skill is running in the main Claude session (not as a sub-agent — i.
 
 ## Mandatory per-request artifact
 
-Every RD invocation — feature, bug, refactor, clarification — must write a durable artifact at `.peaks/_runtime/<sessionId>/rd/requests/<request-id>.md`. This is the canonical engineering record for that request; handoff to QA/SC is blocked while the artifact is missing or its state is `draft` or `spec-locked` without implementation evidence.
+Every RD invocation — feature, bug, refactor, clarification — must write a durable artifact at `.peaks/<session-id>/rd/requests/<request-id>.md` (the canonical placeholder form: `<session-id>` is the active session id at runtime, `<request-id>` follows the `YYYY-MM-DD-<kebab-slug>` format; the runtime path is `.peaks/_runtime/<session-id>/rd/requests/<request-id>.md`). This is the canonical engineering record for that request; handoff to QA/SC is blocked while the artifact is missing or its state is `draft` or `spec-locked` without implementation evidence. Codegraph context lives at `.peaks/<session-id>/rd/codegraph-context.md`.
 
 → see `references/artifact-per-request.md` for the template + the "two RD artifact files" rule (per-slice vs per-session scope).
 
 ## 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. The full 9-step runbook (steps #0–#8) with every CLI invocation, project-scan BLOCKING rule, component-library detection, CSS framework conflict check, and 6 transition gates is in the references file.
-
-→ see `references/rd-runbook.md` for the full runbook.
+See `references/rd-runbook.md` for the full 9-step runbook (steps #0–#8) with every CLI invocation, project-scan BLOCKING rule, component-library detection, CSS framework conflict check, and 6 transition gates.
 
 ## RD gate index
 
@@ -108,11 +106,22 @@ RD cannot mark a development slice complete until all of these are true. Each ga
 
 If any gate fails, return to development for fixes or hand off as blocked. Do not describe the work as done, shippable, or ready for QA.
 
-## Parallel review fan-out (code-review + security-review + perf-baseline + qa-test-cases)
+## Parallel review fan-out (code-reviewer + security-reviewer + perf-baseline-reviewer + qa-test-cases-writer)
+
+**When RD reaches the end of implementation, the four review activities run in parallel via `peaks sub-agent dispatch <role>`, not sequentially.** This is the same fan-out pattern peaks-solo uses for the post-PRD swarm. The four sub-agents are `code-reviewer` (code-review evidence), `security-reviewer` (security-review evidence), `perf-baseline-reviewer` (perf-baseline measurement), and `qa-test-cases-writer` (qa/test-cases/<rid>.md). Feature / refactor: all four. Bugfix: code-reviewer + security-reviewer + qa-test-cases-writer always; perf-baseline-reviewer only when perf-shaped. Config / docs / chore: no fan-out. B3 augmentation: ocr (user-owned LLM config at `peaksConfig.ocr.llm`, injected as env vars) → `peaks code-review run-ocr --json` → merge into `code-review.md`; → `references/ocr-integration.md`.
+
+### Peaks-Cli Gate C — type-specific RD evidence
+
+The CLI gate at `rd:qa-handoff` is the authoritative check. Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with `PREREQUISITES_MISSING`.
 
-**When RD reaches the end of implementation, the four review activities run in parallel via `peaks sub-agent dispatch <role>`, not sequentially.** This is the same fan-out pattern peaks-solo uses for the post-PRD swarm. Feature / refactor: all four. Bugfix: code-review + security-review + qa-test-cases always; perf-baseline only when perf-shaped. Config / docs / chore: no fan-out.
+| Request type | Required RD evidence (under `.peaks/<id>/`) |
+|---|---|
+| feature / refactor | `rd/tech-doc.md` + `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` + `qa/test-cases/<rid>.md` |
+| bugfix | `rd/bug-analysis.md` + `rd/code-review.md` + `rd/security-review.md` + `qa/test-cases/<rid>.md` (rd/perf-baseline.md only when perf-shaped) |
+| config | `rd/security-review.md` |
+| docs / chore | (no extra evidence required) |
 
-→ see `references/parallel-review-fanout.md` for the dispatch template + the 4 sub-agents' contracts + aggregation + degradation.
+→ see `references/rd-fanout-contracts.md` for the 4 sub-agents' contracts + hard prohibitions + aggregation + degradation.
 
 ## Refactor hard gates
 
@@ -162,7 +171,13 @@ Before RD work stops, finishes, blocks, or hands off to another role, emit a sho
 
 ## External references
 
-Matt Pocock skills (diagnose / triage / tdd / improve-codebase-architecture / prototype): engineering references only. Inspect before applying; Peaks-Cli RD gates remain authoritative. Understand Anything: `peaks understand status/show --json`. Codegraph: local analysis only, never commit `.codegraph/` artifacts. Other external resources: `peaks capabilities --source access-repo/mcp-server --json` for capability discovery.
+## Codegraph project analysis
+
+Codegraph is local project-analysis evidence, scoped to red-line scope boundaries (changed files / symbols) and read via `peaks codegraph affected --project <path> <changed-files...> --json`. Peaks-Cli RD gates remain authoritative; codegraph is untrusted supporting evidence. Do not let codegraph output drive scope, design, or QA verdict decisions, and never mutate agent settings, Claude settings, or hooks from codegraph. Do not commit `.codegraph/` artifacts or persist generated `.codegraph/` databases into git. Codegraph context is written to `.peaks/<session-id>/rd/codegraph-context.md` for handoff to QA / TXT.
+
+## Matt Pocock skills integration
+
+Matt Pocock skills (`diagnose` / `triage` / `tdd` / `improve-codebase-architecture` / `prototype`): engineering references only. Inspect before applying; Peaks-Cli RD gates remain authoritative. Understand Anything: `peaks understand status/show --json`. Codegraph: local analysis only, never commit `.codegraph/` artifacts. Other external resources: `peaks capabilities --source access-repo/mcp-server --json` for capability discovery.
 
 → see `references/external-references.md` + `references/matt-pocock-integration.md` + `references/codegraph-project-analysis.md`.
 

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

@@ -0,0 +1,214 @@
+# 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 a **required dependency** and
+> reads the LLM endpoint config from `peaksConfig.ocr.llm` in the
+> user's `~/.peaks/config.json` (single source of truth, user-managed).
+> When present + configured, the wrapper turns the output into
+> structured `code-review.md` evidence.
+
+## 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 a **required `dependency`** of
+peaks-cli 2.0.1+. `npm i -g peaks-cli` pulls it automatically and
+downloads the platform binary in the postinstall step. 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 (corrupt node_modules, or user removed it) | `npm i -g @alibaba-group/open-code-review` (peaks-cli 2.0.1+ does this automatically; this state is rare) |
+| `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/rd-fanout-contracts.md

@@ -0,0 +1,70 @@
+# peaks-rd 4-way parallel fan-out (slice 004)
+
+The Parallel review fan-out is the canonical RD-side review pattern: at the
+end of implementation, RD fires 4 sub-agents in parallel via
+`peaks sub-agent dispatch <role>` instead of running them sequentially.
+
+## The 4 sub-agents
+
+- **Sub-agent 1 — code-reviewer** runs `code-review` against the diff and
+  writes `rd/code-review.md`.
+- **Sub-agent 2 — security-reviewer** runs `security-review` against the
+  changed surface and writes `rd/security-review.md`.
+- **Sub-agent 3 — perf-baseline-reviewer** measures the perf surface
+  (slice 025) and writes `rd/perf-baseline.md`. Skipped when the slice
+  has no perf surface (e.g. config / docs / chore) or when the bugfix
+  is not perf-shaped.
+- **Sub-agent 4 — qa-test-cases-writer** drafts the QA test plan and
+  writes `qa/test-cases/<rid>.md`. The test plan is the deliverable —
+  these test cases do NOT need to be executed by this sub-agent (the
+  QA reviewer executes them in Gate D). Do NOT write to `tests/`; the
+  writer's only write target is `qa/test-cases/<rid>.md`.
+
+## Hard prohibitions on all 4 sub-agents (single block)
+
+- Sub-agents are spawned via `Skill(skill="...")` and run in their own
+  conversation context. They MUST NOT mutate parent settings
+  (`peaks skill presence:set`, hooks install, `.claude/settings.json`).
+- Sub-agents MUST NOT call `peaks workflow verify-pipeline` — that is
+  Solo's responsibility.
+- Sub-agents MUST NOT modify the request artifact body — they only
+  write their respective review artifact.
+- Sub-agents MUST NOT install or persist external material (no
+  `npm install` of unapproved packages, no Playwright MCP install).
+- Sub-agents return a compact JSON envelope
+  (`{ ok, artifact, blockers, notes }`) to the parent RD loop; the
+  parent aggregates into the final qa-handoff.
+
+## Aggregation
+
+The parent RD loop receives the 4 envelopes, runs `peaks request lint`
+on the produced artifacts, and only then attempts
+`peaks request transition --state qa-handoff`. The aggregation step
+runs 4 ls checks: Gate B3 (code-review file), Gate B4 (security-review
+file), Gate B9 (perf-baseline file, when the slice has a perf
+surface), and the `qa-test-cases` pre-draft (the 4th sub-agent's
+deliverable). A failure in any of the 4 sub-agents → blocked, no
+auto-downgrade.
+
+## Degradation
+
+When the `qa-test-cases-writer` sub-agent fails, the parent RD loop
+records the failure as `qa-test-cases-subagent-degraded-to-inline-qa-draft`
+in the request artifact and proceeds; the QA main loop falls back to
+drafting the test plan inline at Gate D. The other 3 sub-agents
+(code-reviewer, security-reviewer, perf-baseline-reviewer) are NOT
+degradeable — their failure blocks qa-handoff.
+
+## Gate C evidence (RD-side, type-specific)
+
+| Request type | Required RD evidence (under `.peaks/<id>/`) |
+|---|---|
+| feature / refactor | `rd/tech-doc.md` + `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` + `qa/test-cases/<rid>.md` |
+| bugfix | `rd/bug-analysis.md` + `rd/code-review.md` + `rd/security-review.md` + `qa/test-cases/<rid>.md` (rd/perf-baseline.md only when perf-shaped) |
+| config | `rd/security-review.md` |
+| docs / chore | (no extra evidence required) |
+
+Always required (in addition to the type-specific row):
+`ls .peaks/<id>/rd/requests/<rid>.md`. Missing any required file →
+DO NOT attempt the qa-handoff transition; CLI will reject with
+`PREREQUISITES_MISSING`.

package/skills/peaks-rd/references/rd-runbook.md

@@ -1,4 +1,4 @@
-# Default runbook (RD)
+## Default runbook (RD)
 
 > Body of `## Default runbook` + numbered runbook steps #0–#8. 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.
 

package/skills/peaks-solo/SKILL.md

@@ -72,6 +72,12 @@ After Step 0 anchored the workspace, run the resume-detection probe (one `find`
 
 → see `references/resume-detection.md` for the full detection algorithm + classification table.
 
+### Peaks-Cli Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
+
+Per the "one-key completion" tenet (2026-06-11), peaks-cli 2.0 should detect a 1.x consumer project and prompt the user to upgrade. After Step 0.7 returns "fresh" (no in-flight slice), run the 1.x detection probe: `peaks upgrade --detect-1x --project <root> --json`. If the result is `isOneX: true`, surface an `AskUserQuestion` with the upgrade prompt. Persist the decision to `.peaks/preferences.json` (key: `autoUpgradePrompt` with values `opt-in` / `skip-this-session` / `skip-forever`) so subsequent runs in the same project don't re-ask.
+
+→ see `references/step-0-55-1x-detection.md` for the full detection algorithm + AskUserQuestion options + persistence contract.
+
 ### Peaks-Cli Step 1: Mode selection
 
 When the user did not name a profile (`full-auto` / `assisted` / `swarm` / `strict`), use `AskUserQuestion` with `Full auto (Recommended)` as the first option. Map the choice to `--mode` value.
@@ -185,21 +191,21 @@ Five CLI commands harden the workflow against silent skips: `peaks request lint`
 
 ## Peaks-Cli Completion handoff
 
-After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas, open questions, next action. Do NOT call `peaks skill presence:clear --project <repo>` at workflow end (presence remains active for follow-ups).
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas, open questions, next action. **Presence management is delegated to the last downstream skill in the workflow** — peaks-solo does not call `peaks skill presence:clear` itself, and does not enforce a "no clear" rule. The downstream skills (peaks-rd, peaks-qa, peaks-txt) each manage their own presence per their respective SKILL.md.
 
 → see `references/completion-handoff.md` for the full handoff + "no auto-exit" rule.
 
 ## Peaks-Cli External references and lifecycle
 
-Inventory of 3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7). Three-stage pattern: capability discovery via `peaks capabilities` → references only → Peaks-Cli CLI for side effects.
+Inventory of 3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7). Three-stage pattern: capability discovery via `peaks capabilities` → references only → Peaks-Cli CLI for side effects. Peaks-Cli artifacts and Peaks-Cli acceptance criteria remain authoritative; do not execute upstream installer scripts; MCP servers (Playwright MCP, Chrome DevTools MCP, Figma Context MCP) are not managed by peaks-cli — the LLM checks its own tool list for `mcp__<server>__*` entries; if absent, the user installs via the IDE-native install command (e.g. `claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code).
 
-→ see `references/external-references.md` for the full inventory + lifecycle rules.
+→ see `references/external-references.md` for the full inventory + lifecycle rules, and `references/external-skill-invocation.md` for the three-stage (Discovery → Reference → Side effect through Peaks CLI only) contract + the do-not-execute / do-not-persist / tool-list self-check rules.
 
 ## Codegraph orchestration context
 
-Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as optional project-analysis enhancement. Output is untrusted supporting evidence — never treat as approval for scope, design, or QA verdict.
+Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as optional project-analysis enhancement. Output is untrusted supporting evidence — never treat as approval for scope, design, or QA verdict. Solo must not treat codegraph output as approval; never mutate agent settings, Claude settings, or hooks from codegraph; do not commit `.codegraph/` artifacts or persist generated `.codegraph/` databases into git. Solo coordinates codegraph context across the role handoff between RD (writes `.peaks/<session-id>/rd/codegraph-context.md`) and QA / TXT (consume the same envelope).
 
-→ see `references/codegraph-orchestration.md` for the full contract.
+→ see `references/codegraph-orchestration.md` for the full contract (including the agent-settings / settings-mutation prohibition, the no-`.codegraph/` commit rule, and the role-handoff envelope).
 
 ## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
 

package/skills/peaks-solo/references/completion-handoff.md

@@ -8,7 +8,9 @@ Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, ar
 
 ## Workflow completion (no auto-exit)
 
-Do NOT call `peaks skill presence:clear --project <repo>` at workflow end. The presence file and header remain active so the user stays inside the workflow context. The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo`. The header continues to display the active skill and current gate.
+peaks-solo does NOT itself call `peaks skill presence:clear --project <repo>` at workflow end. Presence management is delegated to the last downstream skill in the workflow (peaks-rd, peaks-qa, peaks-txt); each of those skills owns its own presence:clear step per its SKILL.md. peaks-solo only sets presence: it does not unset it.
+
+The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo` to do so. The header continues to display whatever skill is active; the user can `/peaks-solo` again to re-anchor.
 
 Before ending, extract durable memories from this session:
 ```bash