peaks-loop 3.1.2 → 4.0.0-beta.10

package/skills/peaks-code/references/browser-workflow.md

@@ -0,0 +1,127 @@
+# Headed browser workflow for Peaks skills
+
+Peaks skills standardize on **Playwright MCP** as the controlled headed-browser surface for opening a browser on demand (PRD authenticated docs, UI design inspection, QA E2E validation). Chrome DevTools MCP is a secondary surface that **connects to an existing Chrome instance launched with `--remote-debugging-port=9222`** — it does not launch a browser on its own. Picking the right tool for the right job is critical:
+
+| Need | Tool | Why |
+|---|---|---|
+| Open a controlled browser when the user supplies a URL | **Playwright MCP** | Spawns its own browser instance per session; no prerequisite. |
+| Drive console/network/performance inspection on a Chrome the user already has open | Chrome DevTools MCP | Connects via CDP to an existing Chrome on `:9222`. |
+| Frontend E2E validation that needs to start, navigate, capture, close | **Playwright MCP** | Headed mode, full lifecycle in one tool. |
+| Live page debugging where the user wants to keep their own Chrome session in front | Chrome DevTools MCP | Stays attached without disrupting the user's tabs. |
+
+> **Bug history**: an earlier version of this document recommended Chrome DevTools MCP for "open a headed browser when peaks-code gets a product document link." Dogfood testing in 2026-05 revealed the tool requires a pre-running Chrome with remote debugging enabled — it does NOT launch its own browser. Playwright MCP is the correct tool for the "open on demand" case.
+
+> **Slice #016 (2026-06-09)**: peaks-loop no longer manages MCP install / dispatch. Skill bodies instruct the LLM to (a) check its own tool list for any Playwright MCP entry, (b) invoke the tool by name if present, (c) tell the user the install command if absent. There is no peaks-loop MCP indirection layer anymore.
+
+## When to open the headed browser
+
+Open a controlled browser when:
+
+- PRD source is an authenticated product document (Feishu/Lark, Notion, internal wiki) and the URL passes the allow-list check.
+- UI design or full-auto frontend work needs visible regression observation.
+- QA needs E2E validation on a frontend, including console / network / accessibility / performance inspection.
+
+Never open a browser to bypass authentication, run arbitrary URLs the user has not approved, or interact with payment / delete / authenticated mutation flows without explicit user confirmation.
+
+## Playwright MCP — install + detect
+
+The LLM runtime exposes Playwright's tools under the `mcp__playwright__*` namespace when the user has installed the MCP. Skill bodies MUST NOT bake the prefix into a SKILL.md or reference; the prefix is owned by the LLM runtime.
+
+**Detect**: the LLM checks its own tool list for any `mcp__playwright__*` entry. If present, the MCP is installed; the LLM invokes the tool by name (e.g. `browser_navigate`, `browser_take_screenshot`).
+
+**Install (if absent)**: skill bodies surface the install command to the user. The user runs it themselves — peaks-loop does not hand-edit `~/.claude/settings.json`.
+
+- Claude Code:
+  ```bash
+  claude mcp add playwright -- npx @playwright/mcp@latest
+  ```
+  Restart Claude Code (or reload the window) so the MCP runtime picks up the new server.
+
+- Other IDEs (Trae, Cursor, Codex, Qoder, Tongyi, ...): consult the IDE's MCP install docs. The install command and the runtime prefix differ per IDE; the LLM checks the tool list rather than assuming a prefix.
+
+The skill body uses the LLM's tool list as the source of truth — never the cached `~/.claude/settings.json` (the LLM cannot read the file, and the file's contents may have drifted from runtime state).
+
+## Chrome DevTools MCP — optional, secondary surface
+
+When inspecting an already-running Chrome (e.g., the user's own browser session opened with `chrome --remote-debugging-port=9222`), the LLM checks its tool list for any `mcp__chrome_devtools__*` entry. If present, the LLM invokes the tool by name directly (e.g. `list_pages`, `take_screenshot`, `performance_start_trace`).
+
+Install (if absent) is the user's responsibility:
+
+- Claude Code:
+  ```bash
+  claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+  ```
+
+Chrome DevTools tools fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design and the skill must surface it as a blocked precondition, not silently fall back.
+
+## Tool mapping for the "open a browser on demand" path (Playwright MCP)
+
+The LLM invokes these tools directly from its `mcp__playwright__*` namespace. Peaks skill bodies describe the args shape; the LLM supplies them.
+
+| Verb | Direct invocation (LLM tool list) | Notes |
+|---|---|---|
+| Open visible browser and navigate | `browser_navigate --args '{"url":"<url>"}'` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
+| Confirm visible browser opened | `browser_take_screenshot --args '{"filename":"<abs-path>"}'` | Screenshot is the visible-browser confirmation. |
+| Read structured page (text + a11y) | `browser_snapshot --args '{}'` | Accessibility tree with element refs. |
+| Click / fill / press key | `browser_click --args '<args>'` (and `browser_type`, `browser_press_key`) | Drive the page after navigation. |
+| Inspect console errors | `browser_console_messages --args '{"level":"error"}'` | Pass `level` to filter (`error`, `warning`). |
+| Inspect network failures | `browser_network_requests --args '{"filter":"<regex>"}'` | Pass `filter` regex when the page has many requests. |
+| Resize viewport for responsive checks | `browser_resize --args '<args>'` | |
+| Capture a full-page screenshot | `browser_take_screenshot --args '{"filename":"<abs-path>","fullPage":true}'` | Sanitize before retention. |
+| Close the session cleanly | `browser_close --args '{}'` | End-of-task. |
+| **Runtime prefix (LLM-owned, do not bake into skills)** | `mcp__playwright__<toolName>` | The Claude Code / Trae / etc. runtime prefix; the LLM resolves this from the registered server. |
+
+## Tool mapping for the "connect to running Chrome" path (Chrome DevTools MCP, optional)
+
+| Verb | Direct invocation (LLM tool list) | Notes |
+|---|---|---|
+| List pages in user's Chrome | `list_pages --args '{}'` | Requires Chrome already running with `--remote-debugging-port=9222`. |
+| Bring a tab to front | `select_page --args '{"bringToFront":true}'` | Useful when the user navigated themselves. |
+| Screenshot the visible viewport | `take_screenshot --args '<args>'` | |
+| Read structured page | `take_snapshot --args '{}'` | |
+| Performance trace | `performance_start_trace --args '<args>'` then `performance_stop_trace` | |
+| Lighthouse audit | `lighthouse_audit --args '{"mode":"snapshot"}'` | |
+| **Runtime prefix (LLM-owned, do not bake into skills)** | `mcp__chrome_devtools__<toolName>` | The Claude Code / Trae / etc. runtime prefix; the LLM resolves this from the registered server. |
+
+If Chrome is not running on `:9222`, every Chrome DevTools MCP tool fails. The skill must surface that as a blocked precondition, not silently fall back.
+
+## URL allow-list (always required before navigation)
+
+Before invoking `browser_navigate --args '{"url":"<url>"}'` (or any other navigation), verify:
+
+1. URL uses `https:` (reject `http:`, `file:`, `data:`, `javascript:`).
+2. Host belongs to an approved domain for the role (Feishu/Lark tenant for PRD product docs, the user-approved app target for UI/QA validation).
+3. Reject `localhost`, loopback, link-local, raw IP, and private IP unless the user explicitly approves a controlled local test target.
+4. Reject the navigation entirely if any check fails and surface the reason to the user. Do not silently downgrade to an unauthenticated fetch.
+
+## Login / CAPTCHA / SSO / MFA handoff
+
+If the page redirects to a login challenge:
+
+1. Do not auto-fill credentials. Do not bypass authentication.
+2. The headed browser is already visible; surface that to the user and wait for explicit confirmation that they have completed authentication. Do not assume a state transition from any DOM signal alone.
+3. After the user confirms, resume with `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests` as needed for the role artifact.
+4. If the user cannot complete authentication, mark the role artifact `blocked` with a sanitized reason category (`login-required`, `mfa-required`, `access-denied`) and the exact next user action.
+
+## Sensitive data sanitization
+
+Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifacts:
+
+- Login URLs, redirect URLs, OAuth callback URLs containing tokens or state.
+- Cookies, request or response headers, session tokens, storage state, QR payloads.
+- Raw network logs.
+- Raw browser state, browser traces.
+- Screenshots or logs containing PII, SSO challenge content, or MFA material.
+
+Redact sensitive values before retention. Store evidence as sanitized observations (e.g., "user reached settings page; first 3 list items had a missing-image regression") rather than raw captures.
+
+## Fallback when Playwright MCP is not installed
+
+If the LLM tool list does not include `mcp__playwright__*`:
+
+1. Surface the install command for the user's IDE (the Claude Code install is `claude mcp add playwright -- npx @playwright/mcp@latest`; other IDEs differ).
+2. Do not silently fall back to unauthenticated fetch tools, screenshots-only, or manual transcription.
+3. Frontend QA workflows that require headed browser validation mark the gate `blocked` with the install command in the next action. Manual steps or text-only fetching do not substitute for the mandatory headed browser gate.
+4. Restart the IDE after install; the runtime picks up the new server only after a fresh process / window reload.
+
+Peaks role artifacts (PRD / UI / RD / QA) remain authoritative for what evidence the role recorded; Playwright MCP is the tool, not the verdict.

package/skills/peaks-code/references/codegraph-orchestration.md

@@ -0,0 +1,5 @@
+# Codegraph orchestration context
+
+> Body of `## Codegraph orchestration context`. Code treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Code must not treat codegraph output as approval for scope, design, or QA verdict.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks-Loop gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.

package/skills/peaks-code/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-code.

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

@@ -0,0 +1,23 @@
+# Completion handoff
+
+> Body of `## Peaks-Loop Completion handoff` + `### Workflow completion (no auto-exit)`.
+
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Merge scan-backed changes incrementally; preserve hand-maintained content unless user confirms deletion.
+
+Use Peaks-Loop TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas (`CLAUDE.md` and `.claude/rules/**` statuses), open questions, next action. Do not restate the full workflow log.
+
+## Workflow completion (no auto-exit)
+
+peaks-code does NOT itself call `peaks skill presence:clear --project <repo>` at workflow end. Presence management is delegated to the last downstream skill in the workflow (peaks-rd, peaks-qa, peaks-txt); each of those skills owns its own presence:clear step per its SKILL.md. peaks-code only sets presence: it does not unset it.
+
+The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-code` to do so. The header continues to display whatever skill is active; the user can `/peaks-code` again to re-anchor.
+
+Before ending, extract durable memories from this session.
+
+> **Owned by runbook Step 10 (TXT handoff) + Step 11 (Memory sediment in SKILL.md).** Do not duplicate the CLI invocation here — the canonical command is:
+>
+> ```bash
+> peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
+> ```
+>
+> `peaks project memories:extract` is a different (batch-scoped, no-artifact) CLI used in non-handoff flows. Step 11 in SKILL.md enforces the artifact-scoped path; follow that.

package/skills/peaks-code/references/context-governance.md

@@ -0,0 +1,204 @@
+# Context Governance — G7 + G7.7 + G8 + G9 protocol details
+
+> Slice #010 (G7 + G7.7 + G8 + G9 context-governance push).
+> See: `.peaks/memory/sub-agent-context-minimal-occupation.md` + `sub-agent-shared-channel-cross-completion.md` + `sub-agent-headroom-forced-compression-gate.md` for the red lines.
+
+## G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
+
+### Path convention
+
+```
+.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>
+```
+
+### ArtifactMeta schema
+
+```ts
+interface ArtifactMeta {
+  readonly path: string;
+  readonly size: number;
+  readonly sha256: string;
+  readonly status: 'created' | 'finalized' | 'partial' | 'failed';
+  readonly contentInlined: false;  // mandatory literal
+  readonly summary: string | null; // ≤ 200 chars
+  readonly writtenAt: string;
+  readonly rid: string;
+  readonly role: string;
+  readonly idx: number;
+}
+```
+
+### Sub-agent completion protocol (G3 + G7.4.g)
+
+```
+On completion:
+1. Write artifact to .peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>
+2. Call `peaks sub-agent dispatch --write-artifact <path>` (or via --write-artifact on dispatch)
+   → CLI computes sha256 + size + writes ArtifactMeta to record
+3. Call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>` (G8.6)
+```
+
+### Main LLM reducer view (G7.4.e)
+
+```
+[peaks-code] batch 3/3 done in 47.3s
+- rd → .peaks/_sub_agents/2026-06-06-session-5b1095/artifacts/003-rd-001.md (12KB, sha256:abc123) summary: "wrote RD tech-doc with 4 sub-roles and dispatcher interface"
+- qa-business → .../artifacts/003-qa-business-001.md (8KB, sha256:def456) summary: "wrote 12 API test cases covering happy + 3 error paths"
+- qa-perf → .../artifacts/003-qa-perf-001.md (5KB, sha256:ghi789) summary: "wrote perf baseline; p95 latency target ≤ 200ms"
+```
+
+### Numerical budget
+
+| 方案 | Per sub-agent | 3-sub-agent batch | 6-sub-agent batch |
+|---|---|---|---|
+| Old: inline full content | 1MB typical | 3MB | 6MB |
+| **G7 metadata-only (this slice)** | ~200 chars | **600 chars** | **1.2KB** |
+
+3000-5000× improvement. Main LLM full-slice context net increase: < 10KB for 5 batches × 6 sub-agents.
+
+## G7.7 — headroom-ai integration (opt-in)
+
+### `--use-headroom` flag
+
+Opt-in flag on `peaks sub-agent dispatch`. Default `false` (G7 metadata-only remains the default).
+
+### Mode table
+
+| Mode | tokenBudget | Use case |
+|---|---|---|
+| `balanced` (default) | promptSize * 0.40 / 4 | General sub-agent dispatch |
+| `aggressive` | promptSize * 0.20 / 4 | Last-resort large prompt |
+| `conservative` | promptSize * 0.70 / 4 | Sensitive code analysis |
+
+### Failure mode (RL-22d / RL-32)
+
+- headroom daemon dead / proxy unreachable / times out
+- → `code: "HEADROOM_UNAVAILABLE"` warning + G7 metadata-only fallback
+- → NOT blocking (warn, then continue dispatch)
+
+## G8 — cross sub-agent shared channel
+
+### Path convention
+
+```
+.peaks/_sub_agents/<sid>/shared/<rid>-<batchId>.json
+```
+
+### Two new CLI atoms
+
+```
+peaks sub-agent share --batch <batchId> --key <k> --value <json> --json
+  Writes a shared entry. Last-write-wins by key. value ≤ 1KB soft warn, ≥ 64KB rejected.
+
+peaks sub-agent shared-read --batch <batchId> [--since <iso>] [--key <pattern>] --json
+  Reads entries. --key is a glob pattern with * wildcard.
+```
+
+### Sub-agent prompt template (G8.6)
+
+```
+You are sub-agent role <role>, batch <batchId>.
+
+PROTOCOL (mandatory):
+1. On start: peek at shared channel: `peaks sub-agent shared-read --batch <batchId> --json`
+   to see what other sub-agents in this batch have shared so far.
+2. While running: if you find a blocker or partial work, write share entry
+   `peaks sub-agent share --key "<role>.found-blocker" --value {"reason": "..."}`
+   so other in-flight sub-agents can avoid duplicating effort.
+3. On completion: write share entry
+   `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`
+   BEFORE the final `peaks sub-agent heartbeat --status done` heartbeat.
+4. The shared channel is your only visibility into sibling sub-agents.
+   Do NOT attempt to read other sub-agents' dispatch records directly.
+```
+
+### RL-23 completion-time mandatory write
+
+- When sub-agent calls `peaks sub-agent heartbeat --status done`, it MUST also call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`.
+- If sub-agent omits the share, heartbeat still succeeds but emit warning `code: "COMPLETED_WITHOUT_SHARE"`.
+
+## G9 — forced compression gate
+
+### Threshold table (256K default context capacity)
+
+> **Slice 2026-06-23-audit-4th #F4:** the canonical source is
+> `src/services/context/threshold.ts` (4 tiers: `ok` / `soft-warn` /
+> `near-limit` / `hard-reject` / `emergency`). When editing this
+> table, ALSO edit the constants in `threshold.ts` — drift between
+> the two is a contract bug. Pre-#F4 the doc listed
+> `+ contextWarning: 'high'` for 90%, which did NOT match the
+> in-code `code: "PROMPT_EMERGENCY"`. The row below is the
+> post-#F4 fix.
+
+| Threshold | Prompt size | Behavior |
+|---|---|---|
+| 50% (early warn) | ≥ 128KB | Soft warning, suggest `--use-headroom` |
+| **75% (user red line)** | ≥ 192KB | Soft warn + mandatory suggest `--use-headroom`; `warnings: ["CONTEXT_NEAR_LIMIT"]` |
+| **80% (hard reject)** | ≥ 204KB | Hard reject `code: "PROMPT_TOO_LARGE"`; `--force` allowed at CLI |
+| **90% (emergency)** | ≥ 230KB | Hard reject `code: "PROMPT_EMERGENCY"`; `--force` STILL rejects at 90% (no override) |
+
+### Two-layer enforcement (G9.2)
+
+- **CLI 兜底** — `peaks sub-agent dispatch` validates prompt size; `--force` allowed.
+- **PreToolUse hook** — `peaks sub-agent-dispatch-guard` re-validates; **NO `--force`** allowed at hook layer (RL-30 strict).
+
+### `--force` semantics
+
+- At CLI: `--force` allowed; emits `code: "FORCED_OVER_THRESHOLD"` warning + records `forcedAt: ISO8601`.
+- At PreToolUse hook: `--force` is REJECTED (RL-30 strict). The hook's CLI does not declare a `--force` flag; the override path is physically not available.
+
+## AC mapping
+
+- AC-38..AC-43 (G7) + AC-44..AC-46 (G7.7) + AC-47..AC-49 (G8) + AC-50..AC-65 (G9)
+- See PRD §Acceptance criteria.
+
+---
+
+### G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
+
+> Body of `### G7`. Sub-agent artifacts (rd/tech-doc.md, qa/test-cases/&lt;rid&gt;.md, ui/design-draft.md) MUST NOT be inlined into dispatch records and fed back to the main LLM during reduce.
+
+- Sub-agent writes artifact to disk at a known path (path convention: `.peaks/_sub_agents/<sessionId>/artifacts/<rid>-<role>-<idx>.<ext>`).
+- Sub-agent calls `peaks sub-agent dispatch --write-artifact <path>` (or via dispatch CLI flag). The CLI computes sha256 + size + writes `ArtifactMeta` to record.
+- Main LLM reduces the batch and sees ONLY the metadata view (~200 chars per sub-agent, vs ~1MB if content were inlined) — a 3000-5000× reduction.
+- Main LLM decides whether to `Read <path>` for full content (LLM tool call, NOT via peaks CLI).
+
+Main LLM view format (G7.4.e):
+```
+[peaks-code] batch 3/3 done in 47.3s
+- rd → .peaks/_sub_agents/2026-06-06-session-5b1095/artifacts/003-rd-001.md (12KB, sha256:abc123) summary: "wrote RD tech-doc with 4 sub-roles"
+- qa-business → .../artifacts/003-qa-business-001.md (8KB, sha256:def456) summary: "wrote 12 API test cases"
+- qa-perf → .../artifacts/003-qa-perf-001.md (5KB, sha256:ghi789) summary: "p95 latency target ≤ 200ms"
+```
+
+### G7.7 — headroom-ai integration (opt-in compression)
+
+> Body of `### G7.7`. If a sub-agent prompt is too large even after G7 metadata-only (e.g. 1MB artifact description, 5MB mid-prompt analysis), use `--use-headroom`:
+- Default `false` (G7 remains default).
+- Modes: `balanced` (default) | `aggressive` | `conservative`.
+- Failure: `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback (NOT blocking).
+
+### G8 — cross sub-agent shared channel (dispatcher-mediated indirect signal)
+
+> Body of `### G8`. Sub-agent A's completion **immediately** writes a shared entry; sub-agent B (still in flight) can read shared entries from sibling sub-agents. **This is NOT peer-to-peer messaging.** The dispatcher stores, the sub-agents read/write; A and B never directly talk.
+
+- Path: `.peaks/_sub_agents/<sessionId>/shared/<batchId>.json`.
+- Two new CLI atoms (NO new top-level CLI): `peaks sub-agent share` + `peaks sub-agent shared-read`.
+- RL-23 strong constraint: when sub-agent calls `peaks sub-agent heartbeat --status done`, it MUST also call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`.
+
+### G9 — forced compression gate (CLI 兜底 + hook double-guard)
+
+> Body of `### G9`. Threshold table (256K default context capacity):
+
+| Threshold | Prompt size | Behavior |
+|---|---|---|
+| 50% (early warn) | ≥ 128KB | Soft warning, suggest `--use-headroom` |
+| **75% (user red line)** | ≥ 192KB | Soft warn + `warnings: ["CONTEXT_NEAR_LIMIT"]` |
+| **80% (hard reject)** | ≥ 204KB | Hard reject `code: "PROMPT_TOO_LARGE"`; `--force` allowed at CLI |
+| 90% (emergency) | ≥ 230KB | Hard reject + `contextWarning: 'high'` |
+
+Two layers:
+- **CLI 兜底** — `peaks sub-agent dispatch` validates prompt size; `--force` allowed.
+- **PreToolUse hook** — `peaks sub-agent-dispatch-guard` re-validates; **NO `--force`** at hook layer (RL-30 strict).
+
+The sub-agent prompt template (G8.6 + G9 self-check) is in `references/context-governance.md`.

package/skills/peaks-code/references/dag-orchestrator.md

@@ -0,0 +1,56 @@
+# DAG-aware sub-agent dispatch (2.7.0)
+
+Code delegates layer-by-layer fan-out + join-barrier + cancel-on-fail
+to **`runDag(dag, opts)`** in `src/services/code/dag-orchestrator.ts`
+when a slice's dependency surface is a DAG. Code MUST NOT re-implement
+these mechanics inline.
+
+## When to use `runDag`
+
+Use `runDag` when **any** of these is true:
+
+- The slice has 2+ independent parallel leaves with per-layer rollback.
+- The slice has 1+ upstream contracts to inject into downstream
+  dispatch prompts (`formatContractInjection` reads
+  `.peaks/_runtime/<sessionId>/dispatch/contracts/`).
+- The slice has 2+ topological levels (orchestrator-driven re-invoke,
+  not manual "next-level" CLI calls).
+
+Use single-role `peaks sub-agent dispatch <role>` for everything else.
+
+## Contract
+
+```ts
+import { runDag } from '../services/code/dag-orchestrator.js';
+const result = await runDag(dag, {
+  projectRoot, sessionId, requestId, role, ide,
+  dispatch: async (spec) => { /* LLM-side runner executes SubAgentDispatcher.buildToolCall(spec) */ },
+  await:    async (batchId, timeoutMs) => { /* SubAgentDispatcher.awaitBatch(...) */ },
+  writer:   writeContract,
+});
+// result.contracts: readonly SliceContract[] — written + ready for injection
+```
+
+## Failure handling
+
+Any leaf failure → orchestrator sends `cancel` to in-flight siblings;
+Code gets partial `DagRunResult`, treats slice as `return-to-rd`,
+re-enters at the failed layer on next repair cycle. Per-IDE timeout:
+trae / trae-cn / cursor 30s, codex 45s, claude-code 60s; uniform
+120_000ms clamp ceiling.
+
+## Source-of-truth pointers
+
+- Orchestrator: `src/services/code/dag-orchestrator.ts` (`runDag` +
+  `buildDispatchSpec` + `formatContractInjection`)
+- DAG model: `src/services/dispatch/slice-dag.ts`
+  (`validateDag` / `topologicalLevels` / `sliceReadyToRun` / `hashDag`)
+- Per-IDE await: `src/services/dispatch/sub-agent-dispatcher.ts`
+  (`SubAgentDispatcher.awaitBatch` — real impl on all 5 IDEs)
+- Contract store: `src/services/dispatch/contract-store.ts`
+- CLI surface: `peaks sub-agent dispatch --from-dag <file> --batch-id <id>`
+  and `peaks sub-agent await --batch <id> [--timeout <ms>]`
+- Tests: `tests/unit/code/dag-orchestrator.test.ts` (cancel-on-fail),
+  `tests/unit/dispatch/run-dag-dogfood-mvp.test.ts` (MVP dogfood),
+  `tests/unit/dispatch/slice-dag-dispatcher-5ide-dogfood.test.ts`
+  (5 IDE end-to-end).

package/skills/peaks-code/references/external-references.md

@@ -0,0 +1,15 @@
+# External references and lifecycle
+
+> Body of `## Peaks-Loop External references and lifecycle`.
+
+**Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
+
+Code treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Code must not treat codegraph output as approval for scope, design, or QA verdict.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks-Loop gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.
+
+**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery via `peaks capabilities` before naming, references only (no execute/install/persist), Peaks-Loop CLI for all side effects. Do not execute upstream installers, do not install upstream resources, do not persist sensitive examples — Peaks-Loop gates remain authoritative. External skills inform, they do not approve.
+
+**MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
+
+Detailed rules: `references/external-skill-invocation.md`, `references/workflow.md`, `references/existing-system-extraction.md`. For an informational mapping of peaks artefact paths to the A2A (Agent2Agent) protocol's Task / Artifact / Part / Message / AgentCard vocabulary (no A2A implementation, just a shared naming layer), see `references/a2a-artifact-mapping.md`.

package/skills/peaks-code/references/external-skill-invocation.md

@@ -0,0 +1,72 @@
+# Canonical external-skill invocation pattern for Peaks skills
+
+Peaks skills reference many external resources — `mattpocock/skills`, `gstack`, `awesome-design-md`, `taste-skill`, `design-taste-frontend`, `superpowers`, `shadcn/ui`, `React Bits`, `Chrome DevTools MCP`, `Agent Browser`, `Figma Context MCP`, `Penpot`, `Context7`, `SearchCode`, `claude-mem`, `context-mode`, `everything-claude-code`, `Claude Code Best Practice`, `andrej-karpathy-skills`, `OpenSpec`, `GitNexus`, and others.
+
+Every reference must follow the same three-stage pattern so the Peaks gates stay authoritative and side effects stay observable.
+
+> **Slice #016 (2026-06-09)**: peaks-loop no longer manages MCP install or invocation. MCP capability detection moves from the peaks-loop CLI to the LLM's own tool list (the LLM checks for `mcp__<server>__*` entries in its own function schema). Skill bodies instruct the LLM to either invoke the tool by name (when present) or tell the user the install command (when absent).
+
+## Stage 1 — Discovery before naming
+
+Do not name an external skill or MCP server as if it is always available. Route discovery through the Peaks CLI for non-MCP capabilities, and through the LLM's own tool list for MCP capabilities:
+
+- `peaks capabilities --source access-repo --json` for non-MCP capabilities (skills, agents, rules, browser tools).
+- `peaks capabilities --source mcp-server --json` for MCP catalog discovery (which MCPs are *known*, not which are *installed*).
+- For MCP install state, the LLM checks its own tool list for any `mcp__<server>__*` entry. If present, the MCP is installed. If absent, the user installs via the IDE-native MCP install command (e.g. `claude mcp add <server> -- <npx-command>` for Claude Code).
+
+A skill body may mention the capability id, but it must say or imply that the skill only applies "when capability discovery exposes …" (or equivalent phrasing). Skills must not pretend the capability is already installed.
+
+## Stage 2 — Reference, never auto-execute
+
+External skills are inspection material for the role's own artifacts. They are not auto-runnable workflows. Every reference must:
+
+- explicitly say it is a reference (e.g. "use these upstream methods as <role> references only");
+- name the specific methods or surfaces the role borrows;
+- forbid executing upstream instructions, installing upstream resources, persisting upstream examples, or running upstream installers;
+- declare that the Peaks role artifacts remain authoritative.
+
+For MCP servers, the LLM consumes the install state from its own tool list. Skill bodies tell the LLM: "if the tool is present, invoke it by name; if absent, surface the install command for the user's IDE and stop until the user installs the MCP". peaks-loop does not install MCPs on the user's behalf as of slice #016.
+
+## Stage 3 — Side effect through Peaks CLI only
+
+The skill body must not silently:
+
+- install hooks;
+- create agents;
+- enable or configure an MCP server;
+- modify `~/.claude/settings.json` or project `.claude/settings.json`;
+- write to `.codegraph/`, `.openspec/`, or other upstream tool state;
+- store tokens, cookies, login URLs, headers, storage state, or PII / SSO / MFA browser material;
+- commit or sync intermediate artifacts;
+- create remote repositories.
+
+All of these must route through the Peaks CLI under the appropriate command (`peaks artifacts …`, `peaks memory …`, `peaks standards …`, `peaks codegraph …`, `peaks capabilities …`), with dry-run preview where supported and `--yes` / `--apply` where a real write is required. The `peaks mcp …` command tree was retired in slice #016; MCP install / dispatch is the LLM runtime's job, not the CLI's. Note: peaks-code's 11-step workflow does NOT route through any external artifact lifecycle (OpenSpec or otherwise) — all reads/writes are confined to the LLM-authored artifact workspace under `.peaks/_runtime/<sessionId>/<role>/`. External CLI surfaces remain available for users who call them directly, but Code never calls them on the user's behalf as of the 2026-07-08 RR decoupling slice.
+
+## Allowed in-process references
+
+Some references are not external skills but project-approved utilities and may be named directly without the discovery stage:
+
+- `peaks` CLI commands (this binary).
+- `npx`, `npm`, `pnpm`, `yarn`, package managers — only as the underlying mechanism when a `peaks` CLI command spawns them.
+- `mcp__chrome_devtools__*` — Chrome DevTools MCP tools exposed by the LLM's MCP runtime when the user has installed Chrome DevTools MCP (Claude Code: `claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest`). Skill bodies tell the LLM to invoke these tools by name when they appear in the tool list. Login / CAPTCHA / SSO / MFA handoff rules and sanitization rules in `browser-workflow.md` still apply.
+
+These are not subject to capability discovery because they are part of the Peaks engineering surface, not external skills. The previous `gstack/browse/dist/browse` binary reference is no longer endorsed — see `browser-workflow.md` for the migration recipe.
+
+## Common phrasing the audit looks for
+
+The skill-external-invocation dogfood test scans skill bodies for:
+
+- a `capability discovery exposes` clause or equivalent before naming a discoverable external skill;
+- a `references only` / `reference material` / `reference resources` phrase qualifying any external skill name;
+- a `do not execute upstream instructions` / `do not run upstream installer flows` / `do not persist sensitive examples` clause;
+- a `Peaks` authoritative-gate clause (e.g. "Peaks gates remain authoritative", "Peaks artifacts remain authoritative", "Peaks acceptance authority").
+
+When a skill body adds a new external reference, it must include the equivalent phrasing or the audit test fails.
+
+## Repair recipe when audit fails
+
+1. read the failing skill body section;
+2. identify the external skill or MCP that triggered the failure;
+3. add the capability discovery clause, the reference-only qualifier, the do-not-execute clause, and the Peaks-authoritative gate to that section;
+4. for MCP servers, point the LLM at the tool-list self-check (its own `mcp__<server>__*` namespace) instead of describing manual `~/.claude/settings.json` edits;
+5. rerun the audit.

package/skills/peaks-code/references/fanout-mandatory.md

@@ -0,0 +1,109 @@
+# Fan-out is mandatory (slice 2026-06-24-audit-5th-p2)
+
+> **Reference contract.** Slice 5 (`feat(code): default to multi-sub-agent
+> fan-out when DAG has >= 2 same-level leaves`) shipped in 2.8.0 with
+> `'fan-out'` as the default but kept `'serial'` as an opt-out. Slice
+> 2026-06-24-audit-5th-p2 (this slice, 2.8.4) **removes the opt-out** by
+> user direction: single-sub-agent dispatch is no longer permitted when
+> the DAG has ≥ 2 leaves at one topological level. This file is the
+> canonical rationale + migration contract for that breaking change.
+
+## Why the opt-out was removed
+
+The 2.8.3-era `'serial'` mode was originally added to support four
+caller personas (deterministic logs, single-sub-agent rate limits,
+replay harnesses, step-by-step debugging). After a multi-cycle audit
+(2026-06-23 → 2026-06-24), the operator concluded:
+
+- **Deterministic logs** — achievable via `peaks slice check --verbose
+  --no-color` per-slice logs, no opt-out needed.
+- **Rate limits** — handled at the LLM-side runner's batch budget, not
+  by serializing the dispatch shape (fan-out's `dispatchCount === N`
+  still gives the platform one batch to schedule concurrently).
+- **Replay / step-debug** — already covered by `peaks contract write`
+  + `peaks sub-agent dispatch --batch-id <existing>`; replay targets
+  one slice by id, no need to disable fan-out at the orchestrator.
+- **The opt-out masked a foot-gun**: a user setting `'serial'` got
+  `dispatchCount === 1` per CLI invocation and silently turned the
+  orchestrator into a serial runner — wall-time `sum`, not `max`.
+
+The hard constraint is now: when the slice DAG has ≥ 2 leaves at the
+same topological level, the orchestrator MUST use `--from-dag` and
+emit N parallel `buildToolCall` envelopes in one batch. There is no
+preference, env-var, or CLI flag that overrides this.
+
+## Default rule (unchanged)
+
+```text
+topological-level leaf count ≥ 2
+  → peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>
+  → dispatchCount === N (parallel)
+  → wall-time ≈ max(per-slice latency), not sum
+
+topological-level leaf count === 1
+  → peaks sub-agent dispatch <role> --prompt ...
+  → dispatchCount === 1 (single dispatch is fine; only one slice exists)
+```
+
+`config | docs | chore` request types still skip Swarm (no DAG emitted).
+
+## Migration: legacy `'serial'` preferences.json
+
+A project that wrote `'serial'` into `.peaks/preferences.json` between
+2.8.3 and 2.8.4 will see the following when it next runs `peaks`
+(any CLI that calls `loadPreferences`):
+
+```text
+PREFERENCES_FANOUT_INVALID: fanout.defaultMode must be one of fan-out
+  (got "serial") in .peaks/preferences.json. The 'serial' opt-out was
+  removed in 2.8.4 — remove the fanout block to use the fan-out default.
+```
+
+**Recovery:** delete the `fanout` block from `.peaks/preferences.json`
+(keeping the rest of the file intact), or run `peaks preferences
+migrate --write` which rewrites `serial` → `fan-out` automatically
+and surfaces a `changes[]` entry:
+
+```text
+fanout.defaultMode rewrote 'serial' → 'fan-out' (the 'serial' opt-out
+  was removed in 2.8.4; single-sub-agent dispatch is no longer
+  permitted when DAG has >= 2 leaves)
+```
+
+## Schema reference (locked)
+
+Defined in `src/services/preferences/preferences-types.ts`:
+
+```typescript
+export type FanoutMode = 'fan-out';
+
+export const FANOUT_MODES: readonly FanoutMode[] = ['fan-out'];
+
+export interface FanoutPreference {
+  /** Hard-coded mode. Slice 2026-06-24-audit-5th-p2 removed the serial opt-out. */
+  readonly defaultMode: FanoutMode;
+}
+
+// DEFAULT_PREFERENCES
+fanout: { defaultMode: 'fan-out' }
+```
+
+`FANOUT_MODES` is intentionally exported with a single element so the
+type guard (`isFanoutMode`) can keep the same closed-set validation
+shape it had pre-slice — the difference is that anything outside
+`'fan-out'` now throws instead of being silently coerced to default.
+
+## Tests
+
+- `tests/unit/code/skills-code-fanout-mandatory.test.ts` — pins that
+  SKILL.md still mentions `--from-dag`, does NOT mention `serial`
+  opt-out, and references `references/fanout-mandatory.md`.
+- `tests/integration/code/multi-sub-agent-fanout.test.ts` — pins the
+  runtime fan-out behavior; not affected by this slice.
+
+## Rollout
+
+This is a **breaking change** for any project that opted into
+`defaultMode = 'serial'`. The migration path is automatic on next
+`peaks` run (silent coercion via `migratePreferences`); manual
+recovery is `delete the fanout block from preferences.json`.

package/skills/peaks-code/references/fast-mode.md

@@ -0,0 +1,23 @@
+# Code fast mode (slice 2 — round-trip ≤ 30s)
+
+For hot-fix / small-bug slices where the full 5-step workflow is overkill,
+use **fast mode**: `peaks code plan --fast <change-id>`. Fast mode skips
+three steps that dominate cold-start cost:
+
+| Step | Default | Fast |
+|------|---------|------|
+| `load-memory` (full `.peaks/memory/*` load) | run | **skip** (use last-touched subset / `--tag` filter) |
+| `standards-preflight` (5-axis rule fan-out) | run | **skip** |
+| `qa-cycle` (single round + repair loop) | repair=on | repair=off |
+| `rd-cycle`, `emit-txt` | run | run |
+
+## Acceptance gate
+
+`test pass + tsc pass + lint pass` = GO. Single QA round, NO repair loop.
+Use fast mode only when the user explicitly opts in (default stays
+conservative).
+
+## Karpathy-4 in fast mode
+
+= condensed 1-paragraph version (not the full 4-block injection).
+Full guidelines still apply, just shipped inline as one block.