peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,216 @@
+# 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
+  Code'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/bee/peaks-rd/references/rd-runbook.md

@@ -0,0 +1,190 @@
+## 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 Code's pre-RD scan — BLOCKING if missing
+# **STOP if .peaks/project-scan/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/project-scan/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-code-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.

package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md

@@ -0,0 +1,111 @@
+# Sub-agent dispatch (RD)
+
+> Body of `## Sub-agent dispatch`. When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-code`, the following sections of THIS skill are **suspended** for the sub-agent run:
+
+## Default `--from-dag` is mandatory (slice 2026-06-24-efficiency-4p-bundle / G2 / P0.3)
+
+> **Hard constraint**: when the swarm plan DAG has ≥ 2 leaves at the
+> same topological level, the **only** allowed dispatch shape is
+>
+> ```
+> peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>
+> ```
+>
+> — i.e. one batch with `dispatchCount === N` parallel `buildToolCall`
+> envelopes. Do NOT fan out by issuing N separate
+> `peaks sub-agent dispatch <role> --prompt ...` calls in sequence
+> (or as a non-DAG multi-call in one message); that serialises the
+> wait and turns wall-time into `sum`, not `max`. The CLI rejects
+> hand-rolled serial fan-out for ≥ 2-leaf DAGs at the SKILL.md /
+> orchestrator level — there is no preference, env-var, or CLI flag
+> that overrides this constraint.
+>
+> Single-leaf (≥ 1 leaf, exactly 1) DAGs may still use the legacy
+> single-dispatch shape `peaks sub-agent dispatch <role> --prompt ...`
+> because no parallelism is on the table. `config | docs | chore`
+> request types still skip Swarm (no DAG emitted) and remain on the
+> single-dispatch path.
+>
+> This constraint is **text-locked** in this reference (so the LLM
+> runner sees the rule every time it reads the dispatch contract) and
+> **test-locked** by
+> `tests/unit/dispatch/dispatch-fanout-mandatory.test.ts` (≥ 8 cases
+> covering 1-leaf, 2-leaf, 3+-leaf, config/docs/chore type-bypass, and
+> the preferences-with-serial-default fan-out escape hatch). See also
+> `skills/peaks-code/references/fanout-mandatory.md` for the
+> orchestrator-side rationale; the two files share the same wording by
+> design — if either changes, update the other.
+
+- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
+- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Code loop owns that file. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-rd.json` and only that.
+- **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.
+- **Mode selection** — Code has already chosen the mode. Read it from the prompt arguments (or from `.peaks/.active-skill.json` if you can, but do not write it).
+- **Statusline install** — already done by Code at session startup; do not re-run.
+
+What the sub-agent **MUST** still do, from this skill's contract:
+
+0. **Do NOT call `peaks request init`** — Code has already initialised the request artefact slot in the main loop before fan-out (the runbook has the exact `peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json` call). The sub-agent reads the slot via `peaks request show <rid> --role rd --project <repo> --json` if it needs to. Note: `peaks request init` is **dry-run by default**. Pass `--apply` to actually create the artifact.
+2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role ui` if UI is in the swarm plan).
+3. Standards preflight (dry-run only; Code owns the apply step).
+4. Project-scan read; create `rd/project-scan.md` only if Code flagged it missing in the dispatch prompt.
+5. Write the planning artefact: `rd/requests/<rid>.md` (feature/refactor, per the `artifact-per-request.md` contract) or `rd/bug-analysis.md` (bugfix). If `--type` is `config|docs|chore`, **no planning artefact is required** — return immediately with `{"role":"rd-planning","status":"skipped","reason":"type=<type>"}`.
+
+   > **v2.11.0 change (Group A):** `rd/tech-doc.md` is removed. The per-slice planning record is the per-request artefact at `rd/requests/<rid>.md`; the slice's source-of-truth architecture is the immutable peaks-prd handoff at `prd/handoff.md` (verify handoff hash = `<dispatched value>` before reading).
+6. Return only a compact JSON envelope — Code will run the convergence gate (`ls` checks):
+
+```json
+{
+  "role": "rd-planning",
+  "rid": "<rid>",
+  "status": "ok" | "blocked" | "skipped",
+  "artefacts": [".peaks/_runtime/<sessionId>/rd/requests/<rid>.md"],
+  "warnings": [],
+  "blockedReason": null
+}
+```
+
+**Hard prohibitions** (sub-agent context, in addition to general red lines):
+
+- Do NOT call `Skill(skill="...")` from inside the sub-agent — that defeats the fan-out.
+- Do NOT call `peaks skill presence:set` — Code owns the active-skill file.
+- Do NOT commit, push, install hooks, or apply settings.json mutations.
+- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}` and let Code handle the user message.
+- Do NOT modify code (the Swarm phase is planning only; code edits happen in the RD implementation phase, which is a separate sub-agent or inline run after Gate B).
+
+After returning, Code re-checks Gate B (`ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md` etc.) and proceeds to RD implementation, which is a different sub-agent or inline run.
+
+## Test Tool Detection (mandatory)
+
+The dispatch CLI (`peaks sub-agent dispatch`) automatically prepends a Test Tool Detection block to every sub-agent prompt — telling the sub-agent to read `package.json#scripts.test` first and use the project-local runner (`./node_modules/.bin/<runner>` or `pnpm test -- <file>`). NEVER use `npx <runner>`. This rule is machine-injected, not a prompt ritual — every sub-agent gets it including rd/qa/ui/txt/sc.
+
+If the framework is not obvious from `package.json#scripts.test`, the sub-agent should run `peaks test --json` to introspect the resolved framework + argv before picking a runner.
+
+See the block constant at `src/services/dispatch/test-tool-detection.ts` for the verbatim text.
+
+## Karpathy-guidelines context (Slice 1/6 — karpathy prompt-injection-lift)
+
+When the dispatch primitive constructs the sub-agent prompt, the following context block MUST be appended to the sub-agent prompt verbatim. The block is the canonical injection source for any RD-spawned sub-agent (including 4-way fanout, including inline main-loop RD).
+
+```
+Karpathy-guidelines context (REQUIRED — read before any code action)
+
+The 4 Karpathy guidelines are mandatory for every planning, implementation, refactor, and review action you take. If 200 lines could be 50, rewrite. Touch only what the request requires. Surface assumptions, do not hide them. Define verifiable success criteria.
+
+1. Think Before Coding
+
+Don't assume. Don't hide confusion. Surface tradeoffs. Before implementing: state assumptions explicitly; if multiple interpretations exist, present them; if a simpler approach exists, say so; if unclear, stop and ask.
+
+2. Simplicity First
+
+Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. No "flexibility" or "configurability" that wasn't requested. No error handling for impossible scenarios. If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+3. Surgical Changes
+
+Touch only what you must. Clean up only your own mess. When editing existing code: don't "improve" adjacent code, comments, or formatting; don't refactor things that aren't broken; match existing style. When your changes create orphans: remove imports/variables/functions that YOUR changes made unused. The test: every changed line should trace directly to the user's request.
+
+4. Goal-Driven Execution
+
+Define success criteria. Loop until verified. "Add validation" → write tests for invalid inputs, then make them pass. "Fix the bug" → write a test that reproduces it, then make it pass. For multi-step tasks, state a brief plan with verify checkpoints. Strong success criteria let you loop independently. Weak criteria require constant clarification.
+```
+
+Sub-agents MUST NOT silently drop this block. The regression test `tests/unit/skills/karpathy-prompt-injection.test.ts` asserts this block is present. The canonical skill id for the full guidelines text is `andrej-karpathy-skills:karpathy-guidelines`.