peaks-cli 1.4.2 → 2.0.1

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

@@ -66,12 +66,24 @@ Run `peaks workspace init` + `peaks skill presence:set peaks-solo` BEFORE any an
 
 → see `references/anchoring-and-session-info.md` for the full Step 0 contract + session-conflict resolution.
 
+#### Step 0 bypass — Claude Code [Fact-Forcing Gate] (slice 2.0.1-bug3)
+
+`peaks workspace init` materializes `.claude/settings.local.json` (a PreToolUse hook allow-list for `.peaks/**` paths and `peaks <subcommand>` Bash) so the [Fact-Forcing Gate] does not block Step 0. Pass `--no-claude-hooks` to opt out.
+
+→ see `references/anchoring-and-session-info.md` for the full bypass contract, recovery flow, and anti-bail-out rule.
+
 ### Peaks-Cli Step 0.7: Detect unfinished work and offer resume (BLOCKING on first invocation per session)
 
 After Step 0 anchored the workspace, run the resume-detection probe (one `find` + one `grep` + classification table). Surface resume options via `AskUserQuestion` if a slice is in flight. Never silently auto-resume.
 
 → 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.
@@ -191,15 +203,15 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 ## 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/anchoring-and-session-info.md

@@ -22,4 +22,13 @@ peaks skill presence:set peaks-solo --project <repo> --gate startup
 **Session conflict resolution (read once, internalise):** If `peaks workspace init` returns `code: "CONFLICTING_SESSION"` with a body like
 `{"existingSessionId":"<Y>","requestedSessionId":"<X>"}`, the project is already bound to a different in-flight session `<Y>` (the one you or a prior run was working on). The fix is **NOT** to pass `--allow-session-rebind` to clobber `<Y>` — that destroys an active session's data. Instead: finish or abandon `<Y>` first (use `peaks session list --json` to see what it is, then `peaks session finish --id <Y>` or `peaks session abandon --id <Y>` — see your session command's help for the exact verbs). Only after `<Y>` is closed should you re-run `peaks workspace init`. The same rule applies to `peaks workspace init --session-id "<manually-forged>"` — do not pre-forge session ids; the CLI's auto-generated value is the binding.
 
+**Fact-Forcing Gate bypass (slice 2.0.1-bug3):** Claude Code's [Fact-Forcing Gate] fires in two shapes inside peaks-solo Step 0: (1) Bash-side "Quote the user's current instruction verbatim. Then retry the same operation." and (2) Write-side 4-facts prompt. Both block the very first Write to `.peaks/_runtime/<sid>/session.json` and the first `peaks skill presence:set peaks-solo` invocation. The default `peaks workspace init` (no flag) materializes `.claude/settings.local.json` in the consumer project root with a PreToolUse hook allow-list that exits 0 for tool calls inside `.peaks/**` and for `peaks <whitelisted-subcommand>` Bash commands. The hook bypasses the gate before it fires.
+
+If the bypass is not in effect (e.g. `.claude/` was read-only, or the user passed `--no-claude-hooks`, or the consumer manually deleted the file), the recovery flow is:
+
+1. Re-run `peaks workspace init --project <repo> --json` **without** `--no-claude-hooks`. The next-action list will say "Materialized .claude/settings.local.json (action: written/refreshed)". Restart Claude Code so the hook takes effect.
+2. If `.claude/` cannot be written (read-only mount, container with no write access, etc.), drop the contents of `.peaks/.claude-settings-template.json` into `.claude/settings.local.json` manually. The peaks-cli init always writes the offline template copy (regardless of `--no-claude-hooks`) so the user has a known source-of-truth on disk. After copying, restart Claude Code.
+
+**Anti-bail-out rule for the gate:** Do NOT skip Step 0 because the gate fired. The gate is a Claude Code core feature that peaks-cli cannot modify directly; peaks-cli can only sidestep it via the hook allow-list. If the gate still blocks Step 0 after the bypass is in effect, the user has a misconfigured `.claude/settings.json` upstream — surface that as a separate `AskUserQuestion` ("Your `.claude/settings.json` is overriding the local allow-list. May peaks-cli delete the local file and regenerate it?") rather than skipping Step 0.
+
 `presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.

package/skills/peaks-solo/references/step-0-55-1x-detection.md

@@ -0,0 +1,82 @@
+# Step 0.55 — 1.x → 2.0 detection reference
+
+> Body of `### Peaks-Cli Step 0.55`. Slice: 2026-06-12-solo-step-0-55-1x-detection.
+
+## Why this step exists
+
+The peaks-cli 1.x → 2.0 closeout ships:
+
+1. A postinstall that auto-detects 1.x state and dispatches the upgrade (slice 1, commit `b6e34e6`).
+2. A standards-migrate path that thins `.claude/rules/**/*.md` and scaffolds `.peaks/standards/` (slice 2, commit `33dd392`).
+3. **THIS STEP** — a peaks-solo startup sequence probe that detects 1.x state when the user invokes `/peaks-solo` directly in a 1.x consumer project, and prompts the user to upgrade.
+
+The 1.x user experience is: "I just typed /peaks-solo. Why is it not working in 2.0 mode?" Step 0.55 catches this case and surfaces an `AskUserQuestion` with a one-click upgrade.
+
+## Detection algorithm
+
+```bash
+# 1. Read-only probe via the umbrella CLI
+peaks upgrade --detect-1x --project <root> --json
+```
+
+The CLI returns:
+```json
+{
+  "ok": true,
+  "command": "upgrade.detect-1x",
+  "data": {
+    "isOneX": true,
+    "signals": [
+      "<path> has schema_version 1.0.0, expected '2.0.0'",
+      "..."
+    ],
+    "projectRoot": "/path/to/project",
+    "configPath": null
+  },
+  "warnings": [],
+  "nextActions": [
+    "Detected 1.x state. peaks-solo Step 0.55 should present an AskUserQuestion to invoke `peaks upgrade --to 2.0 --auto --project /path/to/project`."
+  ]
+}
+```
+
+The detection logic mirrors `scripts/install-skills.mjs:detect1xProjectState` (canonical implementation) — it walks up to find `.peaks/_runtime/`, then sniffs:
+
+1. `~/.peaks/config.json` for `version: 1.x`
+2. `<projectRoot>/.claude/rules/common/dev-preference.md` for "peaks progress"
+3. `<projectRoot>/.peaks/preferences.json` for missing or non-`2.0.0` `schema_version`
+
+The TS mirror in `src/services/upgrade/1x-detector-service.ts` is the canonical entrypoint for the skill; the postinstall `.mjs` version is the canonical entrypoint for the npm-install flow. The two implementations MUST stay in parity (a parity test is in the slice's test suite).
+
+## AskUserQuestion (only when `isOneX: true`)
+
+| Option | What it does |
+|---|---|
+| Run `peaks upgrade --to 2.0 --auto --project <root>` (Recommended) | Invokes the umbrella. The user sees the 6 sub-step results in the terminal. After the upgrade, re-run peaks-solo with the standing 2.0 layout. Persist `autoUpgradePrompt: opt-in` to `.peaks/preferences.json`. |
+| Skip for this session | Continue with the standing 1.x layout. Persist `autoUpgradePrompt: skip-this-session` to `.peaks/preferences.json`. The next time the user invokes peaks-solo in this project, the question re-asks. |
+| Never ask again for this project | Persist `autoUpgradePrompt: skip-forever` to `.peaks/preferences.json`. Step 0.55 becomes a no-op for this project from now on. The user can re-enable later by removing the `autoUpgradePrompt` key from preferences.json. |
+
+## Persistence contract
+
+The decision is persisted via `peaks preferences set --project <root> --key autoUpgradePrompt --value <opt-in|skip-this-session|skip-forever> --apply`. Subsequent Step 0.55 invocations read the value first:
+
+- If `opt-in` (and Step 0.55 is the first invocation in the session), the user has already opted in; auto-run the umbrella without re-asking.
+- If `skip-this-session`, the user already said no this session; skip without re-asking (but re-ask next session).
+- If `skip-forever`, the user said no permanently; skip without re-asking.
+- If the key is absent, present the AskUserQuestion.
+
+## What is NOT in this step
+
+- The auto-upgrade execution itself: the umbrella is invoked via the AskUserQuestion's recommended option. The umbrella's behavior (6 sub-commands + write-upgrade-record) is documented in the umbrella's own help text.
+- The postinstall auto-dispatch: that's `scripts/install-skills.mjs:autoUpgrade1xProjectIfPresent`, which fires fire-and-forget on `npm i -g peaks-cli@2.0`. Step 0.55 is the user-invoked path.
+- Re-authoring the 1.x detector heuristics: the implementation is a 1:1 mirror of the canonical `.mjs` version. Drift is prevented by the parity test.
+
+## How this integrates with the rest of the workflow
+
+- Step 0.5 (OpenSpec opt-in) — runs first if `openspec/` is missing.
+- Step 0 (anchor) — runs always.
+- Step 0.7 (resume detection) — runs after Step 0.
+- **Step 0.55 (1.x detection) — runs after Step 0.7, only when the project is not on a 2.0 layout.**
+- Step 1 (mode selection) — runs after Step 0.55.
+
+The 1.x detection is intentionally placed AFTER Step 0.7 because the user might already have a 1.x-converted in-flight slice; the resume flow takes precedence over the upgrade prompt.

package/skills/peaks-solo/references/workflow-gates-and-types.md

@@ -102,6 +102,15 @@ ls .peaks/<id>/ui/design-draft.md 2>&1
 
 The CLI gate (`peaks request transition --state qa-handoff`) is the authoritative check; running this `ls` first lets you produce missing files before the CLI rejects the transition.
 
+| 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` (qa/test-cases pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004) |
+| `bugfix` | `rd/bug-analysis.md` + `rd/code-review.md` + `rd/security-review.md` + `qa/test-cases/<rid>.md` (rd/perf-baseline.md only when the bug is performance-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.
+
 ```bash
 # Always required
 ls .peaks/<id>/rd/requests/<rid>.md