peaks-loop 3.0.0

package/skills/peaks-rd/references/rd-transition-gates.md

@@ -0,0 +1,148 @@
+# Peaks-Cli RD transition verification gates
+
+> Extracted from `skills/peaks-rd/SKILL.md` on 2026-06-09 (slice 019 — slim skill files to references) to keep SKILL.md under the 800-line cap from `common/coding-style.md`. The content below is the verbatim "Transition verification gates" section that was previously inline; nothing was paraphrased, just relocated.
+
+## Transition verification gates (MANDATORY — full per-gate contract)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file" or any command returns empty, the phase is incomplete.
+
+> **CLI enforcement (NEW)**: the gates below are now ALSO enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. The exact required files depend on the request type chosen at `peaks request init --type <feature|bugfix|refactor|docs|config|chore>` (default `feature`):
+>
+> | Type | rd:implemented requires | rd:qa-handoff also requires |
+> |---|---|---|
+> | feature / refactor | `rd/tech-doc.md` | `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` (filled Results table, or `N/A — no perf surface` in Notes) + **`qa/test-cases/<rid>.md`** (added in slice 004; pre-drafted by the 4th sub-agent in the parallel fan-out) |
+> | bugfix | `rd/bug-analysis.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review.md` + `rd/security-review.md` + **`qa/test-cases/<rid>.md`**; `rd/perf-baseline.md` only when the bug is performance-shaped (matches the L449-452 "When this applies" criteria) |
+> | config | (none) | `rd/security-review.md` only |
+> | docs / chore | (none) | (none) |
+>
+> The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions; the bypass is recorded in the artifact transition note.
+
+**Peaks-Cli Gate A — After project-scan read (before any implementation):**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/project-scan.md
+# Expected output: .peaks/_runtime/<sessionId>/rd/project-scan.md
+# "No such file" → STOP, create the project-scan first. Do not write code.
+```
+
+**Peaks-Cli Gate A2 — Before tech-doc write: project structure verified (PATH CORRECTNESS — CRITICAL):**
+```bash
+# Verify EVERY file path and directory in the tech-doc exists in the actual project.
+# Do not assume paths. Do not guess directory structures. Open the files and verify.
+# Example verification (adapt paths to the actual tech-doc):
+ls <every-single-directory-path-in-tech-doc> 2>&1 | grep -c "No such file"
+# Expected: 0 (zero "No such file" errors)
+# Any "No such file" → WRONG PATH. Fix the tech-doc BEFORE writing another word.
+# This gate exists because a tech-doc with wrong paths wastes QA time,
+# breaks the implementation, and forces the user to correct the engineer.
+```
+
+**Peaks-Cli Gate A3 — Before implementation: project standards files exist (CLAUDE.md + .claude/rules/):**
+```bash
+ls CLAUDE.md .claude/rules/common/coding-style.md .claude/rules/common/code-review.md .claude/rules/common/security.md 2>&1 | grep -c "No such file"
+# Expected: 0 (all four files exist)
+# Any missing → BLOCKED. Run `peaks standards init --project .` to generate them FIRST.
+# Do not write a single line of implementation code without standards files in place.
+# Without CLAUDE.md and .claude/rules/, code review and security review triggers won't fire.
+```
+
+**Peaks-Cli Gate B — Before QA handoff:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md \
+   .peaks/_runtime/<sessionId>/rd/tech-doc.md
+# Both must exist. Missing either → BLOCKED, do not hand off to QA
+```
+
+**Peaks-Cli Gate B2 — Before QA handoff: unit tests exist and pass for the changed surface:**
+```bash
+# Run the project's test command against changed files. Record the output.
+# Example (adapt to project test runner):
+npx vitest run --changed --reporter=verbose 2>&1 | tail -20
+# Expected: exit code 0, all changed-surface tests passing, coverage for new/changed code recorded
+# Any failing test or zero tests for new code → BLOCKED. Write tests, then re-run.
+#
+# To run the FULL suite (slower; not the default for `peaks slice check`),
+# drop `--changed` or use `npx vitest run --reporter=verbose`. The peaks-solo-test
+# skill is the user-facing wrapper for the full suite; the slice check's
+# `--run-tests` flag is the CLI opt-in.
+```
+
+**Peaks-Cli Gate B3 — Before QA handoff: code review evidence exists:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/code-review.md 2>&1
+# Expected: .peaks/_runtime/<sessionId>/rd/code-review.md
+# "No such file" → BLOCKED. Run code review (use code-reviewer agent or equivalent),
+# record findings, fix CRITICAL/HIGH issues, then re-check.
+```
+
+**Peaks-Cli Gate B4 — Before QA handoff: security review evidence exists:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/security-review.md 2>&1
+# Expected: .peaks/_runtime/<sessionId>/rd/security-review.md
+# "No such file" → BLOCKED. Run security review (use security-reviewer agent or equivalent),
+# fix CRITICAL/HIGH issues, record findings, then re-check.
+```
+
+**Peaks-Cli Gate B5 — RD artifact body has no unfilled placeholders:**
+```bash
+peaks request lint <rid> --role rd --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# ok=false → BLOCKED. The lint output lists every <placeholder>, "- ..." stub,
+# and TBD/TODO marker with line numbers. Fill them in before attempting handoff.
+```
+
+**Peaks-Cli Gate B6 — Declared --type matches the actual diff:**
+```bash
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# Expected: consistent=true. exit 0.
+# consistent=false → BLOCKED. Either the implementation scope-creeped beyond what
+# the declared type covers, or the type was mis-classified at PRD time. Re-classify
+# (`peaks request init` with the corrected --type) or trim the scope.
+```
+
+**Peaks-Cli Gate B7 — Repair cycle cap (only relevant during RD↔QA repair loop):**
+```bash
+peaks request repair-status <rid> --project <repo> --session-id <session-id> --json
+# Expected: atCap=false. exit 0.
+# atCap=true → BLOCKED. Three repair cycles already attempted; emit a blocked TXT
+# handoff via Solo rather than entering a fourth cycle.
+```
+
+**Peaks-Cli Gate B8 — Diff stays inside the declared red-line scope:**
+```bash
+peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# violations[] non-empty → BLOCKED. A changed file matches an explicit out-of-scope
+#   pattern. Revert it, or — only with PRD approval — expand the RD red-line scope.
+# unclassified[] non-empty → BLOCKED. A changed file does not match any declared
+#   in-scope pattern. Either add it to the in-scope list (intentional widening, requires
+#   PRD approval) or revert the change.
+# patternsDeclared=false → BLOCKED. The RD artifact's `## Red-line scope` section has
+#   no concrete path or glob patterns. Fill it in with paths like `src/services/login/**`
+#   before re-running. Auto-allowed paths (test files, .peaks/, __mocks__/) never need a pattern.
+```
+
+**Peaks-Cli Gate B9 — RD-side perf-baseline output present (when slice has a user-perceivable perf surface):**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/perf-baseline.md 2>&1
+# Expected: .peaks/_runtime/<sessionId>/rd/perf-baseline.md
+# "No such file" + slice is feature / refactor / bugfix-when-perf → BLOCKED.
+#   Run the perf-baseline sub-agent from "Parallel review fan-out" below (or
+#   `peaks perf baseline --apply` inline), then fill in the Results table
+#   with measurements (lighthouse / k6 / autocannon / project-local bench —
+#   the CLI does not run these; that is the RD's job), then re-verify.
+# "No such file" + slice is docs / chore / pure-bugfix-no-perf → OK to proceed;
+#   this gate does not apply to those slice types.
+# File exists but Results table is empty (only the header row, no data rows) →
+#   BLOCKED. The sub-agent scaffolds the file; the main RD loop must fill in
+#   the Path / route | Workload | Tool | Metric | Baseline | Threshold table
+#   with actual numbers before handoff.
+# File contains the marker `N/A — no perf surface` in its Notes section →
+#   OK to proceed. This is the explicit opt-out the sub-agent writes when
+#   the slice has no user-perceivable perf surface (e.g. a feature that only
+#   adds an internal flag with no runtime cost, or a refactor that does not
+#   alter any hot path).
+#
+# The CLI enforcement table below the section header also gates this at the
+# `peaks request transition rd:qa-handoff` call, so a missing or empty file
+# is rejected by the CLI with `code: PREREQUISITES_MISSING`.
+```

package/skills/peaks-rd/references/reading-v2-slice-results.md

@@ -0,0 +1,54 @@
+# Reading v2 slice results (peaks-slice-decompose v2 schema)
+
+`peaks-slice-decompose` produces a **v2 envelope** with multi-pass topology. RD reads it before dispatching implementation work. Routing is automatic via `SchemaRouter` (see `src/services/slice/schema-router.ts`); do not branch on version strings in the prompt.
+
+## Envelope shape (v2)
+
+```json
+{
+  "schemaVersion": "2.0",
+  "result": {
+    "passes": [
+      {
+        "passId": "pass-1",
+        "granularity": "service",
+        "slices": [
+          { "sliceId": "s1", "parentSliceId": null, "files": ["src/foo.ts"], "edges": [] }
+        ]
+      },
+      {
+        "passId": "pass-2",
+        "granularity": "file",
+        "slices": [
+          { "sliceId": "s2", "parentSliceId": "s1", "files": ["src/foo/bar.ts"], "edges": ["s1"] }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Read fields in this order
+
+1. `result.passes[]` — ordered list; Pass 1 runs before Pass 2.
+2. `passes[].granularity` — `service` | `file` | `module`; informs dispatch shape.
+3. `passes[].slices[].parentSliceId` — non-null on Pass ≥ 2 → child of a Pass 1 slice. Build a child→parent map before dispatch.
+4. `passes[].slices[].edges[]` — cross-slice dependencies; honor topological order when fanning out.
+
+## v1 fallback
+
+Legacy v1 envelopes use `result.dependencyDAG.edges` and `result.workUnits`. `SchemaRouter` returns a v1-shaped view automatically when `schemaVersion === "1.0"`; treat `workUnit` ≈ v2 `slice`. Do not migrate v1 envelopes in-flight — read them as-is.
+
+## LLM dispatch strategy
+
+- **`passes.length === 1`** → single fan-out across `passes[0].slices`. One CC per slice, all parallel.
+- **`passes.length > 1`** → per-pass fan-out. Run Pass 1 to completion first (so children resolve `parentSliceId`); then run Pass 2 in parallel. Do NOT interleave passes — child slices read parent outputs.
+- Each CC receives **only its own slice subset** (filter `slices[]` by `sliceId`), never the full envelope. The orchestrator keeps the parent→child map.
+
+## Verifiable success
+
+- Every `sliceId` in the v2 envelope has a corresponding CC dispatch in the runbook.
+- No CC receives a `sliceId` outside its pass.
+- Child CCs run after their parent completes (when `parentSliceId` is set).
+
+See `../peaks-slice-decompose/SKILL.md` for the v2 envelope contract.

package/skills/peaks-rd/references/refactor-workflow.md

@@ -0,0 +1,39 @@
+# Peaks RD Refactor Workflow
+
+## Standards loading order
+
+1. Existing project standards.
+2. Peaks language standard packs.
+3. Peaks universal engineering baseline.
+4. Reviewer judgment.
+
+## Hard gates
+
+- UT coverage must be >= 95% before refactor implementation.
+- Missing, unknown, unverifiable, or failing coverage blocks refactoring.
+- For non-refactor development in legacy repos with pre-existing low coverage, require focused unit-test coverage for new or changed code.
+- Coverage success only allows analysis and spec generation.
+- Broad refactors must be split into minimal functional slices.
+- Each slice needs a strict verifiable spec before implementation.
+- Existing `openspec/` repos require OpenSpec change artifacts before non-trivial implementation.
+- Each implemented slice must pass unit tests, code review, and security review before RD dry-run.
+- The post-check dry-run runs after tests, CR, and security review, not before them.
+- Each slice must pass 100% acceptance.
+- Code changes and sanitized intermediate artifacts must be traceable in local `.peaks/_runtime/<session-id>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized. Browser evidence must not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
+
+## Required artifacts
+
+- `project-scan.md`
+- `engineering-constitution.md`
+- `coverage-report.md`
+- `feature-slice-map.md`
+- `refactor-options.md`
+- `risk-matrix.md`
+- `rollback-plan.md`
+- `slice-spec.md`
+- `openspec-change-paths.md` when OpenSpec is required
+- `code-review-report.md`
+- `security-review-report.md`
+- `post-check-dry-run.md`
+- `validation-report.md`
+- `retention-boundary.md` documenting local `.peaks/_runtime/<session-id>/` traceability, browser-evidence sanitization, and any explicitly authorized commit/sync requirement

package/skills/peaks-rd/references/skill-presence-and-title.md

@@ -0,0 +1,22 @@
+# Skill presence (RD)
+
+> Body of `## Skill presence (MANDATORY first action — main-loop context only)`. When this skill is running in the main Claude session (not as a sub-agent — i.e. user invoked `peaks-rd` directly, or `peaks-solo` is executing the role inline in assisted/strict mode), before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Read persistent project memory via CLI (durable, LLM-authored memories):
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-rd | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.

package/skills/peaks-rd/references/v2-12-fanout-collapse.md

@@ -0,0 +1,64 @@
+# v2.12.0 fan-out collapse (Group A — Tier 1+2+3+4+5)
+
+The v2.12.0 release collapses the peaks-rd parallel review fan-out from
+**5 sub-agents** (slice 002 3-way + slice 004 qa-test-cases + slice 5/6
+karpathy-reviewer) to **3 sub-agents** by moving
+`security-reviewer` + `perf-baseline-reviewer` out of the RD fan-out
+into two new standalone audit skills.
+
+## Removed sub-agent slots
+
+- `security-reviewer` — moved to standalone `peaks-security-audit` skill.
+  Output: `.peaks/_runtime/<sessionId>/audit/security.md`.
+  Required RD-side prereq: `AUDIT_SECURITY`.
+- `perf-baseline-reviewer` — moved to standalone `peaks-perf-audit` skill.
+  Output: `.peaks/_runtime/<sessionId>/audit/perf.md`.
+  Required RD-side prereq: `AUDIT_PERF`.
+
+Both audit skills consume the immutable peaks-prd handoff
+(`.peaks/_runtime/<sessionId>/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.
+
+## CLI surface
+
+- `peaks security-audit run` — dispatches `peaks-security-audit` skill.
+- `peaks perf-audit run` — dispatches `peaks-perf-audit` skill.
+
+Both produce output as side-effects on the standard paths above. They
+are runnable before RD (as a pre-RD audit pass) or in parallel with
+RD's 3-way fan-out.
+
+## Back-compat window
+
+The 1-minor-release back-compat window (`v2.12.0`) keeps the legacy
+paths readable via `mustContainAny` on the new prereqs:
+
+- Legacy `rd/security-review.md` → accepted via `AUDIT_SECURITY.mustContainAny`.
+- Legacy `rd/perf-baseline.md` → accepted via `AUDIT_PERF.mustContainAny`.
+- Legacy `RD_FANOUT_REVIEWERS`-slot dispatch records → routed via
+  `isDeprecatedReviewer(name)` to the new audit skill.
+
+v2.13.0 hard-deletes the legacy paths.
+
+## Pinning
+
+- `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts` — 6 cases pinning the 3-element `reviewerListFor('feat')` shape.
+- `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` — 8 cases pinning `isDeprecatedReviewer` + the legacy-path acceptance.
+- `tests/unit/artifact-prerequisites-typed.test.ts` — back-compat for the prereq forms.
+- `tests/unit/parallel-fan-out.test.ts` — 18 cases pinning the 3-way SKILL.md + reference content.
+- `tests/unit/skills/karpathy-5way-fanout.test.ts` — 17 cases pinning the v2.12.0 collapse invariants.
+
+## Migration sequence
+
+1. Run the standalone audit skills (`peaks security-audit run` +
+   `peaks perf-audit run`) at pre-RD time.
+2. RD-side fan-out dispatches only the 3 sub-agents
+   (`code-reviewer` + `qa-test-cases-writer` + `karpathy-reviewer`).
+3. The `AUDIT_SECURITY` + `AUDIT_PERF` + `AUDIT_REQUIRES_HANDOFF`
+   prereqs block the `rd:qa-handoff` transition if the audit outputs
+   are missing.
+4. The 1-minor-release back-compat window reads the legacy
+   `rd/{security-review,perf-baseline}.md` paths via `mustContainAny`
+   if the new audit outputs are absent.

package/skills/peaks-rd/references/writing-handoff-frontmatter.md

@@ -0,0 +1,68 @@
+# Writing handoff frontmatter (peaks-rd → peaks-qa)
+
+Every RD handoff artifact carries a **YAML frontmatter block** so peaks-qa (and downstream roles) can mechanically cross-check decisions, risks, and gate evidence. The body below the frontmatter is free-form prose (markdown).
+
+## Path
+
+`.peaks/_runtime/<sessionId>/prd/handoff.md` — the canonical immutable PRD handoff path (v2.11.0+). The handoff is written by peaks-prd, sha256-hashed in frontmatter, and verified by every downstream sub-agent against the dispatched hash before reading.
+
+> **v2.11.0 change (Group A):** the per-session `rd/tech-doc.md` is removed; the immutable peaks-prd handoff replaces it as the slice's source-of-truth architecture document.
+
+## Required frontmatter fields
+
+```yaml
+---
+requestId: 2026-06-25-slice-topology-multipass
+scope:
+  - src/services/slice/schema-router.ts
+  - src/services/audit/audit-goal-service.ts
+files:
+  - src/services/slice/schema-router.ts
+  - src/services/audit/audit-goal-service.ts
+handoffPath: .peaks/_runtime/<sessionId>/prd/handoff.md
+handoffHash: sha256:<64 hex chars>
+decisions:
+  - id: D1
+    summary: "Route v1/v2 envelopes via SchemaRouter instead of branching in prompts"
+    rationale: "Single source of truth; SchemaRouter already lives in src/services/slice/"
+risks:
+  - id: R1
+    description: "v1 fallback path untested when sliceIds collide with v2 parentSliceIds"
+    mitigation: "Added 3 collision cases to v1-fallback.test.ts"
+nextActions:
+  - "peaks-qa reads this handoff and runs the regression matrix"
+  - "If Gate C passes, transition to txt handoff"
+gateEvidence:
+  projectScan: .peaks/_runtime/<sessionId>/rd/project-scan.md
+  prdHandoff: .peaks/_runtime/<sessionId>/prd/handoff.md
+  codeReview: .peaks/_runtime/<sessionId>/rd/code-review.md
+  securityReview: .peaks/_runtime/<sessionId>/rd/security-review.md
+  perfBaseline: .peaks/_runtime/<sessionId>/rd/perf-baseline.md
+schemaVersion: '2.0'
+---
+```
+
+## Field rules
+
+- `requestId` — kebab-case; matches the PRD `requestId`.
+- `scope` / `files` — absolute repo-relative paths (`src/...`). Sorted alphabetically.
+- `handoffPath` + `handoffHash` — the immutable PRD handoff location and its sha256 hash. Sub-agents MUST verify `handoffHash` matches the file's actual sha256 before reading; mismatch → return `blocked`.
+- `decisions[]` — every decision an LLM made that an implementer could question. `id` is local; `summary` is one line; `rationale` is ≤ 2 sentences.
+- `risks[]` — same shape; `mitigation` is required. A risk without a mitigation is a red line (gate blocked).
+- `nextActions[]` — verb-first; what peaks-qa should do next, in order.
+- `gateEvidence` — paths to the gate files peaks-qa will validate. Missing keys → Gate C failure.
+- `schemaVersion: '2.0'` — pinned (bumped from `'1.0'` in v2.11.0); bump only when the field set changes.
+
+> **v2.11.0 Group A change:** the validation tests at `tests/unit/artifacts/handoff-frontmatter-shape.test.ts` now assert `schemaVersion === '2.0'`. Files still carrying `'1.0'` will fail validation until upgraded.
+
+## Validation
+
+The frontmatter MUST parse as valid YAML. The regression test `tests/unit/artifacts/handoff-frontmatter-shape.test.ts` (≥ 4 cases) enforces (a) required fields present, (b) `gateEvidence` keys match the per-request-type matrix in `peaks-rd/SKILL.md` Gate C table, (c) `schemaVersion: '1.0'`. Run before commit:
+
+```bash
+./node_modules/.bin/vitest run tests/unit/artifacts/handoff-frontmatter-shape.test.ts
+```
+
+## Body (prose, free-form)
+
+Markdown below the frontmatter is the implementation narrative: what changed, why this slice, what the next role should know. Do NOT restate frontmatter fields in prose.

package/skills/peaks-reviewer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: peaks-reviewer
+description: Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.
+---
+
+## Single-scope-axis naming convention
+
+> **Read once at the top of this file; the rest of the skill is written against it.**
+
+The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, at `.peaks/_runtime/<sessionId>/...`) with a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` placeholders (NEVER bare `<sid>`). The peaks-cli change-id axis was removed in slice `2026-06-29-change-id-root-removal`; reviewable artifacts now live under `.peaks/_runtime/<sessionId>/<role>/...` only. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. CLI mapping: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Regression test `tests/unit/skills/skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) every `.peaks/_runtime/<X>/` has an axis label, (c) this callout is present.
+
+## peaks-context auto-build (v3.0)
+
+The peaks-reviewer workflow automatically runs `peaks context build --audience peaks-reviewer` before the LLM is invoked. No manual setup needed.
+
+# Peaks-Cli Third-Party Reviewer (v2.14.0 G4)
+
+`peaks-reviewer` is a **parallel** reviewer to `karpathy-reviewer`. It is intentionally **not** a replacement: karpathy-reviewer keeps enforcing the 4 guidelines; peaks-reviewer adds an out-of-band perspective from a different model family to mitigate single-LLM self-dogfood blind spots.
+
+## Why a separate reviewer (R6 from the PRD)
+
+In v2.13.x, two real cases slipped through 49/49 unit-test-pass + tsc-clean + single-LLM dogfood:
+- v2.13.1: aggregateVerdict cross-source dedup BLOCKER
+- v2.13.2: parseSecurity/Perf v2.12.0 markdown envelope parse failure
+
+`peaks-reviewer` does NOT promise to eliminate such cases (A4.5 prohibits the claim). It is a structural mitigation that adds a second opinion with a guaranteed-distinct model family.
+
+## Hard contract — modelFamily distinctness (BLOCKING)
+
+The peaks-reviewer modelFamily MUST differ from the karpathy-reviewer modelFamily. Configuration enforces this:
+- `~/.peaks/config.json` `reviewer.providers[]` lists at least 2 distinct providers
+- `reviewer.requireDistinctModelFamily: true` (default)
+- The CLI/agent stamps `modelFamily` from the actual `modelId` we called — the LLM cannot self-report a different family
+
+If the distinctness check fails, the CI gate fails. See `references/reviewer-schema.md` for the envelope shape and `references/reviewer-prompt.md` for the prompt the provider receives.
+
+## CLI surface
+
+```
+peaks reviewer run --rid <rid> [--json]
+peaks reviewer status [--json]
+```
+
+`run` produces `rd/third-party-review.json` (and a human-readable `rd/third-party-review.md`) under `.peaks/_runtime/<sessionId>/`. `status` shows whether the reviewer is configured and which selection mode is active.
+
+## Configuration (`~/.peaks/config.json`)
+
+```jsonc
+{
+  "reviewer": {
+    "providers": [
+      { "name": "ollama",    "model": "llama3.2:8b", "endpoint": "http://localhost:11434" },
+      { "name": "anthropic", "model": "claude-haiku-4-5" },
+      { "name": "openai",    "model": "gpt-4o-mini" }
+    ],
+    "selection": "round-robin",
+    "rdProviderName": null,
+    "requireDistinctModelFamily": true,
+    "fallbackOnError": "skip",
+    "schemaPath": "schemas/reviewer-envelope.schema.json"
+  }
+}
+```
+
+Missing section: reviewer is skipped (transition still passes; envelope records `skipped: no-reviewer-config`). Per A4.1, the CLI flag `--reviewer-model` is REMOVED — users edit the config file.
+
+## Hard prohibitions
+
+- DO NOT modify karpathy-reviewer (NG4). peaks-reviewer is a parallel addition.
+- DO NOT introduce new heavy dependencies (no langchain / openai-sdk). Use `fetch` + manual schema validation.
+- DO NOT silently prompt users for API keys. Missing env vars surface as `providerUnavailable` and the `fallbackOnError` policy decides skip vs throw.
+- DO NOT change the schema for the 5 existing envelope parsers (v2.13.3 territory). The ReviewerEnvelope schema is additive.
+
+## Sub-agent dispatch (when launched by peaks-solo swarm)
+
+When this skill runs as a sub-agent dispatched by peaks-solo, the sub-agent receives the parent session id and change-id via envelope. It MUST write its output to `.peaks/_runtime/<sessionId>/rd/third-party-review.json` + `.md` and return a compact JSON envelope.

package/skills/peaks-reviewer/references/reviewer-prompt.md

@@ -0,0 +1,50 @@
+# peaks-reviewer prompt (v2.14.0 G4)
+
+The reviewer prompt is built deterministically from the slice context. The provider receives exactly one JSON object as response — no prose, no markdown, no free-form LLM JSON.
+
+## Prompt structure
+
+```
+# peaks-reviewer prompt (v2.14.0 G4)
+
+rid: <rid>
+contextSha256: <sha256-prefix>
+
+## Slice context (truncated to 8KB)
+<context, capped at 8192 bytes>
+
+## Required output (ReviewerEnvelope JSON)
+
+Respond with EXACTLY one JSON object matching this schema (no prose):
+{
+  "reviewerId": "third-party-reviewer-v2.14.0",
+  "modelId": "<your modelId>",
+  "modelFamily": "<e.g. claude / gpt-4o / llama>",
+  "passed": <bool>,
+  "violations": [{"kind": "<kind>", "file": "<path>", "line": <int>, "hint": "<str>"}],
+  "gateAction": "block" | "allow" | "warn",
+  "reason": "<one-sentence rationale>"
+}
+
+Forbidden: prose, markdown, multiple objects, free-form JSON. Schema-validated only.
+```
+
+## What peaks-reviewer does NOT do
+
+- Does NOT replace karpathy-reviewer.
+- Does NOT mutate karpathy-reviewer.md.
+- Does NOT introduce new dependencies (no langchain, no openai-sdk).
+- Does NOT silently prompt the user for API keys.
+- Does NOT claim "no more fake green" (A4.5).
+
+## Failure modes
+
+| Failure                          | fallbackOnError=skip | fallbackOnError=error |
+| -------------------------------- | -------------------- | --------------------- |
+| Missing `reviewer.providers`     | skip (envelope: `no-reviewer-config`) | throw + transition blocked |
+| Missing API key env var          | warn envelope        | throw + transition blocked |
+| Provider returns non-JSON        | warn envelope        | throw + transition blocked |
+| JSON does not validate schema    | warn envelope        | throw + transition blocked |
+| Same modelFamily as karpathy     | CI gate fail (AC-4.4) | CI gate fail |
+
+The CLI never silently prompts for API keys; missing env vars surface as `providerUnavailable` and the fallbackOnError policy decides whether to skip or throw.

package/skills/peaks-reviewer/references/reviewer-schema.md

@@ -0,0 +1,49 @@
+# ReviewerEnvelope schema (v2.14.0 G4 AC-4.2)
+
+`peaks-reviewer` MUST emit a JSON object that validates against
+`schemas/reviewer-envelope.schema.json`. Free-form LLM JSON is rejected.
+
+## Field reference
+
+| Field        | Type    | Required | Notes |
+| ------------ | ------- | -------- | ----- |
+| `reviewerId` | string  | yes      | Stable id (`third-party-reviewer-v2.14.0`). |
+| `modelId`    | string  | yes      | Concrete model id (overwritten server-side from the provider we called). |
+| `modelFamily`| string  | yes      | Family bucket (overwritten server-side via `deriveModelFamily(modelId)`). |
+| `passed`     | bool    | yes      | True when no blocking violations. |
+| `violations` | array   | yes      | `[{kind, file, line, hint}]`. Empty when none. |
+| `gateAction` | enum    | yes      | `block` | `allow` | `warn`. |
+| `reason`     | string  | yes      | One-sentence rationale. |
+
+## Violation kinds (closed enum)
+
+- `karpathy-violation` — karpathy 4-guidelines breach
+- `code-smell` — generic code smell
+- `security` — security issue
+- `perf` — performance issue
+- `surgical-changes` — touched more than the request requires
+- `simplicity-first` — overengineered
+- `goal-driven-execution` — weak / unverifiable success criteria
+- `think-before-coding` — hidden assumptions
+
+## Distinctness gate (AC-4.4)
+
+`third-party-review.json.modelFamily` MUST differ from `karpathy-review.json.modelFamily`. Equality fails the build. The reviewer service stamps `modelFamily` from the actual `modelId` (the LLM cannot self-report a different family).
+
+## Skipped envelope
+
+When `~/.peaks/config.json` lacks the `reviewer` section, the reviewer returns:
+
+```json
+{
+  "reviewerId": "third-party-reviewer-v2.14.0",
+  "modelId": "skipped",
+  "modelFamily": "skipped",
+  "passed": true,
+  "violations": [],
+  "gateAction": "allow",
+  "reason": "skipped: no-reviewer-config (fallbackOnError=skip)"
+}
+```
+
+The transition still passes; the THIRD_PARTY_REVIEW prereq records the skip in `prerequisites.warnings`.