peaks-loop 3.1.2 → 4.0.0-beta.10

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

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

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

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

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

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

package/skills/peaks-rd/references/rd-fanout-contracts.md

@@ -1,216 +0,0 @@
-# peaks-rd 3-way parallel fan-out (v2.12.0 — Group A collapse)
-
-The Parallel review fan-out is the canonical RD-side review pattern: at the
-end of implementation, RD fires 3 sub-agents in parallel via
-`peaks sub-agent dispatch <role>` instead of running them sequentially.
-
-> **v2.12.0 collapse (Group A — Tier 1+2+3):** the previous 5-way fan-out
-> (slice 002 3-way + slice 004 qa-test-cases + slice 5/6 karpathy-reviewer)
-> collapsed to **3 sub-agents** in the RD fan-out. The two removed slots
-> (`security-reviewer`, `perf-baseline-reviewer`) moved to standalone audit
-> skills consumed at pre-RD / pre-QA time:
->
-> - `peaks-security-audit` — CLI: `peaks security-audit run`. Output:
->   `audit/security.md`. Required RD-side prereq: `AUDIT_SECURITY`.
-> - `peaks-perf-audit` — CLI: `peaks perf-audit run`. Output:
->   `audit/perf.md`. Required RD-side prereq: `AUDIT_PERF`.
->
-> Both audit skills consume the immutable peaks-prd handoff
-> (`prd/handoff.md`) and the project-scoped audit templates under
-> `.peaks/project-scan/{security-template, perf-template, audit-output-schema}.md`.
-> The handoff presence is enforced by the `AUDIT_REQUIRES_HANDOFF` prereq.
-> The 1-minor-release back-compat window (`v2.12.0`) keeps the old
-> `rd/{security-review,perf-baseline}.md` paths readable via `mustContainAny` —
-> see `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (8 cases) and
-> `tests/unit/artifact-prerequisites-typed.test.ts`.
-
-## The 3 sub-agents
-
-> **Karpathy pointer (Slice 1/6):** Each of the 3 sub-agents below operates under the 4 Karpathy guidelines. The canonical reference is `andrej-karpathy-skills:karpathy-guidelines` (full text) and `peaks-rd/SKILL.md` §"Karpathy enforcement". The dispatch primitive also injects the verbatim context block from `rd-sub-agent-dispatch.md` §"Karpathy-guidelines context" into every sub-agent prompt. Sub-agents MUST NOT silently drop the block.
-
-- **Sub-agent 1 — code-reviewer** runs `code-review` against the diff and
-  writes `rd/code-review.md`. **v2.11.0 Tier 7 (Group D):** the dispatch goes
-  through the **ECC bridge** (`src/services/code-review/ecc-bridge.ts`):
-  `Agent({ subagent_type: 'everything-claude-code:code-review', ... })` returns
-  `{ passed, violations[], gateAction }`; `adaptEccEnvelopeToRdCodeReview`
-  renders it to the canonical markdown. On any non-ready `detectEcc` state
-  (plugin-missing / agent-missing / dispatch-failed / envelope-malformed) the
-  parent RD loop falls back to inline review; the `code-review-ecc-degraded-to-inline`
-  TXT note records the fallback.
-- **Sub-agent 2 — 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`.
-- **Sub-agent 3 — karpathy-reviewer** (Slice 5/6 — hard gate) inspects
-  the diff + handoff against the 4 Karpathy-guidelines and writes
-  `rd/karpathy-review.md` (v2.11.0: the immutable peaks-prd handoff
-  at `prd/handoff.md` replaces `rd/tech-doc.md`). The file MUST
-  contain a `## Karpathy-Gate` header and at least one of the 4
-  guideline section markers; the transition CLI gate reads those
-  markers and refuses `rd:qa-handoff` when the file is missing or
-  the markers are absent. The sub-agent returns a JSON envelope
-  `{ passed, violations, gateAction }` (see contract below). Do NOT
-  modify code; the writer's only write target is `rd/karpathy-review.md`.
-
-> **Removed from v2.12.0 fan-out (back-compat window only):**
-> - ~~Sub-agent — security-reviewer~~ — moved to standalone
->   `peaks-security-audit` skill; output `audit/security.md`. The legacy
->   path `.peaks/_runtime/<sessionId>/rd/security-review.md` remains
->   readable via `mustContainAny` for the v2.12.0 1-minor-release window.
-> - ~~Sub-agent — perf-baseline-reviewer~~ — moved to standalone
->   `peaks-perf-audit` skill; output `audit/perf.md`. The legacy path
->   `.peaks/_runtime/<sessionId>/rd/perf-baseline.md` remains readable
->   via `mustContainAny` for the v2.12.0 1-minor-release window.
->
-> See `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (8 cases)
-> and `RD_DEPRECATED_REVIEWERS` in
-> `src/services/rd/reviewer-dispatch-policy.ts`.
-
-## Hard prohibitions on all 3 sub-agents (single block)
-
-- Sub-agents are spawned via `peaks sub-agent dispatch <role>` 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 3 envelopes, runs `peaks request lint`
-on the produced artifacts, and only then attempts
-`peaks request transition --state qa-handoff`. The aggregation step
-runs 3 ls checks: Gate B3 (code-review file), Gate C2 (qa-test-cases
-pre-draft, the 2nd sub-agent's deliverable), and the KARPATHY_REVIEW
-prereq (the 3rd sub-agent's `rd/karpathy-review.md`). The audit
-prereqs (`AUDIT_SECURITY` + `AUDIT_PERF` + `AUDIT_REQUIRES_HANDOFF`)
-are NOT fan-out outputs — they are produced by the standalone audit
-skills and consumed by the CLI gate. A failure in any of the 3
-fan-out 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 2 sub-agents
-(`code-reviewer`, **`karpathy-reviewer`**) are NOT degradeable — their
-failure blocks qa-handoff. The `karpathy-reviewer` is a hard gate per
-karpathy §1 Think Before Coding + §3 Surgical Changes.
-
-### karpathy-reviewer contract (Slice 5/6)
-
-**Inputs**:
-- The verbatim 4-section Karpathy-guidelines block (injected by
-  `rd-sub-agent-dispatch.md` §"Karpathy-guidelines context").
-- The current slice's diff (changed files + their content).
-- The current slice's `.peaks/_runtime/<sessionId>/prd/handoff.md`
-  (v2.11.0: architecture summary — the immutable peaks-prd handoff
-  replaces `rd/tech-doc.md`).
-- The current slice's PRD body (acceptance criteria).
-
-**Outputs** (compact JSON envelope returned to the parent RD loop):
-- `passed: boolean` — true when all 4 guideline sections pass.
-- `violations: KarpathyViolation[]` — each `{ kind, line, snippet, hint }`
-  with `kind` ∈ {`think-before-coding`, `simplicity-first`,
-  `surgical-changes`, `goal-driven-execution`}.
-- `gateAction: 'pass' | 'block' | 'warn'` — when the file is missing
-  or all 4 section markers are absent, `gateAction` is `block`. When
-  any violation is detected, `gateAction` is `warn`. When clean,
-  `gateAction` is `pass`.
-
-**File write**: the sub-agent writes ONLY `rd/karpathy-review.md`,
-formatted as:
-
-```md
-# Karpathy review — <rid>
-
-## Karpathy-Gate
-
-gateAction: <pass|block|warn>
-generatedAt: <ISO 8601>
-
-## 1. Think Before Coding
-
-<bullet-list of evidence>
-
-## 2. Simplicity First
-
-<bullet-list of evidence>
-
-## 3. Surgical Changes
-
-<bullet-list of evidence>
-
-## 4. Goal-Driven Execution
-
-<bullet-list of evidence>
-```
-
-The transition CLI gate reads `mustContain: ['## Karpathy-Gate',
-'think-before-coding']` and `mustContainAny: ['simplicity-first',
-'surgical-changes', 'goal-driven-execution']` from
-`KARPATHY_REVIEW` in `src/services/artifacts/artifact-prerequisites.ts`.
-
-**Hard prohibitions** (in addition to the 3-sub-agent block above):
-- MUST NOT write code, modify the request artifact, or call
-  `peaks request transition`.
-- MUST NOT install hooks, agents, MCP, or settings.
-- MUST NOT touch Slice 1+2+3+4 products (zero regression).
-- MUST NOT skip the `## Karpathy-Gate` header. The CLI gate
-  enforces its presence; absence blocks the transition.
-
-## Deprecated reviewer back-compat (v2.12.0)
-
-The 2 removed sub-agent slots (`security-reviewer`, `perf-baseline-reviewer`)
-are exposed as `RD_DEPRECATED_REVIEWERS` in
-`src/services/rd/reviewer-dispatch-policy.ts`. The
-`isDeprecatedReviewer(name)` predicate lets back-compat code detect
-a legacy dispatch record and route to the new audit skill instead of
-failing the gate.
-
-**Back-compat contract (v2.12.0 1-minor-release window only):**
-
-- **On-disk dispatch records** (`.peaks/_sub_agents/<sessionId>/dispatch/<name>.json`)
-  for `security-reviewer` or `perf-baseline-reviewer` are routed to the
-  new audit skill by `isDeprecatedReviewer(name)`. No CLI gate failure.
-- **Legacy review artifact paths**
-  (`.peaks/_runtime/<sessionId>/rd/security-review.md`,
-  `.peaks/_runtime/<sessionId>/rd/perf-baseline.md`) are accepted via
-  `mustContainAny: [...]` on the `AUDIT_SECURITY` / `AUDIT_PERF` prereqs
-  during the back-compat window. v2.13.0 hard-deletes the legacy paths.
-
-**Pinning:** `tests/unit/rd/deprecated-reviewer-back-compat.test.ts`
-(8 cases) pins the dispatch routing + the legacy-path acceptance.
-
-## Gate C evidence (RD-side, type-specific)
-
-| Request type | Required RD evidence (under `.peaks/_runtime/<sessionId>/`) |
-|---|---|
-| feature / refactor | `prd/handoff.md` (immutable) + `audit/security.md` (peaks-security-audit) + `audit/perf.md` (peaks-perf-audit) + `rd/code-review.md` + `rd/karpathy-review.md` + `qa/test-cases/<rid>.md` |
-| bugfix | `prd/handoff.md` (immutable) + `audit/security.md` (peaks-security-audit) + `audit/perf.md` (peaks-perf-audit, perf-shaped only) + `rd/code-review.md` + `rd/karpathy-review.md` + `qa/test-cases/<rid>.md` |
-| config | `audit/security.md` (peaks-security-audit) |
-| docs / chore | (no extra evidence required) |
-
-Always required (in addition to the type-specific row):
-`ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md`. Missing any required file →
-DO NOT attempt the qa-handoff transition; CLI will reject with
-`PREREQUISITES_MISSING`.
-
-> **v2.11.0 change (Group A):** `rd/tech-doc.md` is removed from the
-> required-evidence matrix; the immutable peaks-prd handoff
-> (`prd/handoff.md` with sha256 frontmatter) replaces it as the
-> per-slice source of truth.
->
-> **v2.12.0 change (Group A — Tier 4+5):** `rd/security-review.md` and
-> `rd/perf-baseline.md` are removed from the required-evidence matrix;
-> `audit/security.md` (peaks-security-audit) + `audit/perf.md`
-> (peaks-perf-audit) replace them. The `AUDIT_REQUIRES_HANDOFF` prereq
-> enforces the immutable handoff consumption by the audit skills.

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

@@ -1,190 +0,0 @@
-## 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.
-
-```bash
-# 0. confirm RD's own runbook integrity before any code edit
-peaks skill runbook peaks-rd --json
-peaks skill presence:set peaks-rd --project <repo>  # show persistent skill presence every turn
-
-# 1. capture the RD request artifact and read upstream PRD / UI scope
-peaks request init --role rd --id <request-id> --project <repo> --apply --json
-peaks request show <request-id> --role prd --project <repo> --json
-peaks request show <request-id> --role ui  --project <repo> --json   # if UI involved
-
-# 2. standards preflight before planning any code edit
-peaks standards init   --project <repo> --dry-run --json
-peaks standards update --project <repo> --dry-run --json
-
-# 3. pull OpenSpec context when openspec/ exists in the repo
-peaks openspec list --project <repo> --json
-peaks openspec show     <change-id> --project <repo> --json
-peaks openspec validate <change-id> --project <repo> --json    # entry gate
-peaks openspec to-rd    <change-id> --project <repo> --json    # acceptance + commit boundaries
-
-# 4. project-analysis evidence — MANDATORY before implementation
-peaks understand status --project <repo> --json
-peaks understand show   --project <repo> --json                # when UA artifact exists
-peaks codegraph context --project <repo> "<task>"
-peaks codegraph affected --project <repo> <changed-files...> --json
-
-# 4.1 read project-scan from Solo's pre-RD scan — BLOCKING if missing
-# **STOP if .peaks/_runtime/<sessionId>/rd/project-scan.md does not exist.**
-# **Do not write any code, do not plan any implementation, do not pass go.**
-# **Create the project-scan first, then proceed.**
-# NOTE: project-scan.md is a session-scoped singleton. Check if it already exists
-# before regenerating (e.g. via `ls .peaks/_runtime/<sessionId>/rd/project-scan.md`). If it exists
-# and is complete (has `## Archetype` and `## Project mode` sections), reuse it.
-# Required sections in project-scan:
-#   - build tool and framework
-#   - component library (antd, MUI, shadcn, etc.) and version
-#   - CSS solution (Less, Sass, TailwindCSS, CSS-in-JS) and conflicts
-#   - state management, routing, data fetching libraries
-#
-# After writing project-scan, embed durable memory markers for stable project facts.
-# Append one <!-- peaks-memory:start --> block per fact at the end of project-scan.md:
-#
-#   <!-- peaks-memory:start -->
-#   title: <component library>
-#   kind: module
-#   ---
-#   <Library> <version> — detected from package.json and source imports.
-#   <!-- peaks-memory:end -->
-#
-# Embed markers for: component library, CSS solution, build tool, state management,
-# routing, data fetching, and any legacy constraints. These facts are session-invariant
-# and valuable for future sessions. Do NOT embed secrets, credentials, or transient state.
-
-# 4.2 component library detection — verify against package.json, not assumptions
-# WRONG: "looks like a React project, let me use shadcn/ui"
-# RIGHT: check package.json for antd/@mui/@shadcn/etc., match imports in source files
-
-# 4.3 CSS framework conflict check (CRITICAL)
-# Detect conflicts BEFORE adding any CSS dependency:
-# - TailwindCSS + antd → HIGH conflict (preflight reset vs antd base styles)
-# - TailwindCSS + MUI → HIGH conflict (utility classes vs sx/system props)
-# - Adding a second CSS-in-JS lib to a project that already has one → BLOCK
-# - Adding Less/Sass to a CSS-in-JS project → wasteful, not conflicting
-# If a conflict is detected, DO NOT add the conflicting dependency.
-# Record the conflict in the RD artifact and propose a compatible alternative.
-
-# 4.4 source-code component import verification
-# grep source files for actual component imports to confirm library usage:
-# grep -r "from 'antd'" src/ --include="*.tsx" --include="*.ts"
-# grep -r "from '@mui/material'" src/ --include="*.tsx"
-# grep -r "from '@/components/ui'" src/ --include="*.tsx"
-
-# 4.5 mock data strategy — MANDATORY for frontend-only projects
-# Check project-scan for the detected build tool:
-#   Umi → use mock/*.ts (Umi's built-in mock directory)
-#   Vite → use src/mock/ (service-layer mock files)
-#   Next.js → match existing project pattern
-# NEVER write mock data inline in component files.
-# See "Mock data placement rules" section for the full framework mapping.
-
-# 5. optional library docs lookup through the LLM's own tool list (Context7 MCP)
-# If the Context7 MCP is present in the tool list, invoke the
-# tool directly (resolve-library-id / query-docs / etc.). If absent, skip
-# library docs and rely on existing project knowledge — do NOT hand-edit
-# `~/.claude/settings.json` to install MCPs.
-
-# 6. record red-line scope, slice contract, coverage status into the RD artifact, then implement
-
-# 6.5 BEFORE tech-doc: verify EVERY path in the tech-doc against actual project structure (Peaks-Loop Gate A2)
-#     ls every directory path in the tech-doc — zero "No such file" allowed
-#     This is the most common RD failure mode. Do not skip it.
-
-# 1.x API surface scan (Slice 3/6 — `peaks scan api-surface` lands)
-#     Identify existing API endpoints / components / stores / mocks in the
-#     project that the slice could reuse, BEFORE writing any new code. The
-#     output of this step feeds directly into the tech-doc's
-#     `## Existing API / Component Inventory` section (mandatory since
-#     Slice 2, enforced at spec-locked gate C).
-#
-#     Concrete command (Slice 3 lands the CLI):
-#       peaks scan api-surface --project <path> --max-per-kind 50
-#     The default markdown output can be pasted directly into the tech-doc
-#     section 7. For machine-readable JSON use `--format json`.
-#     Ad-hoc grep fallback if the CLI is unavailable:
-#       grep -r "router\.\(get\|post\|put\|delete\)" src/
-#       grep -r "@Get\|@Post\|@Put\|@Delete" src/
-#       grep -r "createSlice\|defineStore" src/
-#       grep -r "mock\|fixture" src/
-#     Record the inventory in the tech-doc section 7 (see mandatory-tech-doc.md).
-
-# 1.y Orphan scan (Slice 4/6 — `peaks scan orphan` lands)
-#     After the slice is implemented (or near-complete), scan for 4 kinds of
-#     orphans that the RD may have left behind (karpathy §3 Surgical Changes
-#     — "remove what your changes made unused"):
-#       1. exportOrphan: declared export with no in-repo importer
-#       2. importOrphan: import whose source no longer exports the symbol
-#       3. cliSubcommandOrphan: `.command('x')` registered but only referenced
-#          at the declaration site
-#       4. docEndpointOrphan: tech-doc declares `peaks <sub>` that the codebase
-#          does not implement
-#
-#     Concrete command (Slice 4 lands the CLI):
-#       peaks scan orphan --project <path>                    # default: working-tree scope
-#       peaks scan orphan --project <path> --scope all --strict  # full audit
-#       peaks scan orphan --project <path> --format json     # machine-readable
-#     Re-run after cleanup; pass with zero counts before `peaks request
-#     transition --state qa-handoff`. The Slice 4 service is read-only and
-#     uses `git diff --name-status HEAD` for working-tree scope (no git CLI
-#     writes). Falls back to empty diff if git is unavailable (degraded mode).
-
-# 1.z Karpathy scan (Slice 5/6 + Slice 6/6 — `peaks scan karpathy` + karpathy-reviewer sub-agent)
-#     After the slice is implemented, scan `rd/karpathy-review.md` for the
-#     4 Karpathy guidelines (Think / Simplicity / Surgical / Goal) and verify
-#     the hard Karpathy-Gate (KARPATHY_REVIEW prereq in artifact-prerequisites.ts).
-#     The structural scanner covers regex / file-presence checks; the semantic
-#     review is owned by the karpathy-reviewer sub-agent.
-#
-#     Concrete commands:
-#       peaks scan karpathy --project <path>                       # markdown report
-#       peaks scan karpathy --project <path> --format json         # machine-readable
-#       peaks scan karpathy --project <path> --scope all           # full audit (gateAction: block if missing)
-#     Required output before `peaks request transition --state qa-handoff`:
-#       - `rd/karpathy-review.md` exists with `## Karpathy-Gate` header
-#       - 4 title-case section headers present (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution)
-#       - `gateAction: pass` (or `warn` with documented justification)
-#
-#     Sub-agent dispatch (Slice 6/6 deliverable — karpathy-reviewer sub-agent):
-#       peaks sub-agent dispatch karpathy-reviewer \
-#         --rid <rid> --project <repo> --json
-#     The sub-agent reads `~/.claude/agents/karpathy-reviewer.md` (user-installed)
-#     which is the project-internal draft at
-#     `skills/peaks-rd/references/karpathy-reviewer-prompt.md` plus a
-#     `rd/karpathy-reviewer-agent-handoff.md` install guide.
-#     Hard gate: missing karpathy-reviewer sub-agent OR missing rd/karpathy-review.md
-#     → `peaks request transition --state qa-handoff` returns `code: PREREQUISITES_MISSING`.
-#     Escape hatch (assisted mode): `--allow-incomplete --confirm`.
-
-# 6.6 BEFORE implementation: verify CLAUDE.md + .claude/rules/ exist (Peaks-Loop Gate A3)
-#     Missing standards files → run `peaks standards init --project .` first
-#     Without project rules, security review and code review triggers won't fire.
-
-# 7. AFTER implementation, BEFORE QA handoff — RUN THESE GATES:
-#    Peaks-Loop Gate B2: unit tests exist and pass for the changed surface → npx vitest run --changed (or project equivalent; the changed-only mode is the peaks slice check default as of run 017; use --run-tests for the full suite, or invoke /peaks-solo-test to run the full suite standalone)
-#    Peaks-Loop Gate B3: code review evidence → .peaks/_runtime/<sessionId>/rd/code-review.md
-#    Peaks-Loop Gate B4: security review evidence → .peaks/_runtime/<sessionId>/rd/security-review.md
-#    Peaks-Loop Gate B5 (NEW): RD artifact body has no unfilled placeholders.
-peaks request lint <rid> --role rd --project <repo> --session-id <session-id> --json
-#    Peaks-Loop Gate B6 (NEW): declared --type still matches the actual diff after implementation.
-peaks scan request-type-sanity --project <repo> --type <type> --json
-#    Peaks-Loop Gate B7 (NEW, repair cycles only): we have not exceeded the 3-cycle cap.
-peaks request repair-status <rid> --project <repo> --session-id <session-id> --json
-#    Peaks-Loop Gate B8 (NEW): every changed file matches the RD red-line scope (no out-of-bounds writes).
-peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <session-id> --json
-#    All six non-zero → BLOCKED. Fix and re-check before attempting the qa-handoff transition.
-
-# 7. self-validate before QA handoff
-peaks openspec validate <change-id> --project <repo> --json    # exit gate (re-run)
-
-# 8. hand off to QA via the cross-linked request id
-peaks request init --role qa --id <request-id> --project <repo> --apply --json
-peaks request show <request-id> --role rd --project <repo> --json
-peaks project memories:extract --session-id <session-id> --project <repo> --json  # extract durable memories
-peaks skill presence:clear --project <repo>                      # handoff complete, remove presence indicator
-```
-
-For refactor work, the coverage ≥ 95% gate in `Refactor hard gates` still applies and must be recorded in the artifact before slicing begins.