peaks-cli 1.3.1 → 1.3.3

package/schemas/doctor-report.schema.json

@@ -13,8 +13,8 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability):[A-Za-z0-9][A-Za-z0-9._-]*$",
-            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency)."
           },
           "ok": { "type": "boolean" },
           "message": { "type": "string", "minLength": 1 }

package/skills/peaks-ide/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: peaks-ide
+description: Orchestrate peaks-cli's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, "set up peaks for my IDE", "switch peaks to Trae", "what did peaks install", "uninstall peaks hooks". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.
+---
+
+# Peaks-Cli IDE Setup (peaks-ide)
+
+`peaks-ide` is the **user-facing surface** for everything peaks-cli does that's IDE-aware. It does NOT introduce new CLI commands. It orchestrates the existing CLI primitives — `peaks hooks install`, `peaks statusline install`, `peaks hook handle` — based on the user's intent and the IDE the user is on.
+
+**Why this exists (dev-preference red line):** "skill is primary, CLI is auxiliary." The behavior that only an LLM in a skill prompt would use ("detect which IDE the user is on", "plan the migration steps", "ask the user before destructive actions") lives in this SKILL.md, not in a new `peaks <cmd>`. The CLI commands stay as atomic primitives the skill composes.
+
+**Slice #2 scope:** the first version supports Trae (alongside Claude Code, the only other adapter in slice #2's registry). Cursor / Codex / Qoder / Tongyi Lingma will land in slice #3+ — the skill will pick them up automatically because the underlying auto-detect (the `peaks project dashboard --json` flow internally calls `listAdapterIds()` via the `IdeRegistry`) registers them as the registry grows.
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-ide --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+The presence marker tells the global peaks status line that peaks-ide is orchestrating. The memory read pulls forward the slice #1 contract: `peaks <cmd> --project <path>` is the canonical project-root source; `process.env[adapter.envVar]` (e.g. `CLAUDE_PROJECT_DIR`, `TRAE_PROJECT_DIR`) is the env-var override for auto-detect.
+
+## Step 1: detect current state
+
+The skill's first move is to **read**, not to ask. Build a complete picture of the user's IDE environment before any AskUserQuestion.
+
+```bash
+# 1. What adapters are registered? (slice #2 ships with claude-code + trae)
+peaks project dashboard --project <repo> --json
+
+# 2. Is the user on Claude Code, Trae, or something else?
+#    Check the cwd for adapter-specific directories:
+ls -la <repo>/.claude 2>/dev/null && echo "claude-code detected"
+ls -la <repo>/.trae 2>/dev/null && echo "trae detected"
+
+# 3. Are peaks hooks already installed? For each candidate, read settings.json:
+#    claude: <root>/.claude/settings.json
+#    trae:   <root>/.trae/settings.json
+peaks hooks status --project <repo> --json 2>/dev/null
+peaks statusline status --project <repo> --json 2>/dev/null
+```
+
+The skill composes a 1-2 sentence **state summary** before asking anything:
+
+> "I see you're on **Trae** (`.trae/` exists in the project root). peaks hooks are **not installed** yet. peaks statusline is **not installed** either. The `peaks hook handle` runtime is available as a CLI primitive — you don't need to install it separately; what needs installing is the settings.json entries that point to it."
+
+The user gets a complete picture without having to answer any question. The next step only fires AskUserQuestion if intent is genuinely ambiguous.
+
+## Step 2: AskUserQuestion (only if intent is ambiguous)
+
+If the user typed `/peaks-ide` without context, the skill's intent is genuinely ambiguous. The four canonical intents are:
+
+| Option | What it does |
+|---|---|
+| First-time install | Run `peaks hooks install` + `peaks statusline install` for the detected IDE |
+| Switch to a different IDE | Detect current install, uninstall from old IDE, install on new IDE (e.g. Claude → Trae) |
+| Show current status | Just print the state summary from Step 1; no side effects |
+| Uninstall peaks hooks | Run `peaks hooks uninstall` + `peaks statusline uninstall` for the detected IDE |
+
+**Default option is "Show current status"** — the cheapest action, and the user gets useful output even if they didn't know what they wanted. AskUserQuestion is the ONLY place this skill asks anything. All destructive paths (Switch, Uninstall) gate on user confirmation here.
+
+## Step 3: plan & preview (dry-run)
+
+Before any side effect, the skill prints the exact CLI invocations it will run. This is the "see before you leap" step.
+
+```
+Plan: First-time install for Trae (.trae/ detected in project root)
+
+  1. peaks hooks install --project <repo>
+     → writes a beforeToolCall hook entry to <root>/.trae/settings.json
+       that points to `peaks hook handle --project "${TRAE_PROJECT_DIR}"`
+
+  2. peaks statusline install --project <repo>
+     → writes a statusLine field with command `peaks statusline`
+
+  3. (no third command — `peaks hook handle` is the runtime; once the
+     settings.json entries point to it, the user's Trae will invoke it
+     on every PreToolUse event)
+
+Verification: after install, re-run `peaks hooks status --project <repo>`
+             to confirm the entries are present.
+
+Proceed? (Y/n)
+```
+
+The plan MUST be human-readable. Don't run a side effect until the user confirms.
+
+## Step 4: execute
+
+For each step in the plan, invoke the CLI primitive. The skill does NOT call out to a hidden script — it runs the actual peaks CLI commands, so the user sees the same output they'd see typing the command themselves.
+
+```bash
+# Example: first-time Trae install
+peaks hooks install --project <repo>
+peaks statusline install --project <repo>
+
+# After each command, check the exit code. If non-zero, STOP and report
+# the failure to the user. The skill does NOT auto-rollback; the user
+# decides what to do next.
+```
+
+For destructive paths (Switch, Uninstall), the skill uses a **transactional pattern**: it captures the current state, runs the destructive CLI, then runs the install CLI; if any step fails, it reports the partial state and lets the user decide.
+
+## Step 5: audit log
+
+Every successful execution writes one JSON line to `.peaks/_runtime/<sid>/ide-onboard.log`:
+
+```json
+{"timestamp":"2026-06-06T19:55:00Z","intent":"first-time-install","detected_ide":"trae","cli_invocations":["peaks hooks install --project <repo>","peaks statusline install --project <repo>"],"outcome":"success","session_id":"2026-06-06-session-22f08c"}
+```
+
+The audit log is **machine-readable** (so `peaks project dashboard` can read it and surface "you installed peaks for Trae on 2026-06-06") and **human-readable** (so the user can `cat` it to see the install history). The skill does NOT write the log file itself — it delegates to `peaks project dashboard` (the canonical log writer, per the dev-preference red line "skill-first for workflow, CLI-backed for gates / side effects"). The audit log writer is a CLI primitive, not a per-skill helper; the skill body MUST NOT introduce a new `peaks <cmd>` for the log writer.
+
+## Boundaries
+
+`peaks-ide` may:
+
+- detect the current IDE (cwd + env var + settings.json)
+- ask the user via AskUserQuestion (Step 2 only)
+- preview the CLI invocations (Step 3)
+- execute existing peaks CLI commands (Step 4)
+- write a single line to the audit log (Step 5)
+
+`peaks-ide` must NOT:
+
+- introduce new `peaks <cmd>` CLI commands (dev-preference red line: "Default-no on new CLI commands")
+- bypass the user's confirmation on destructive paths (Switch / Uninstall)
+- write the settings.json directly (the CLI primitives own that)
+- run other peaks skills (peaks-solo, peaks-qa, etc.) — those are separate skills with their own scopes
+- handle multi-IDE scenarios in slice #2 (e.g. "I use Claude at work and Trae at home" — the registry is single-IDE per session; a future slice could add multi-IDE)
+
+## Reference: the CLI primitives the skill composes
+
+- `peaks hooks install` / `peaks hooks uninstall` / `peaks hooks status` — adapter-driven; auto-detects IDE from env / stdin / cwd
+- `peaks statusline install` / `peaks statusline uninstall` / `peaks statusline status` — same
+- `peaks hook handle` — the runtime handler; not installed, just invoked
+- `peaks project dashboard --json` — surfaces the current state summary
+- `peaks skill runbook` — surfaces the peaks-ide skill body for inspection
+
+## Next-step references
+
+- The slice #1 RD artifact at `.peaks/_runtime/<sid>/rd/requests/002-2026-06-06-peaks-ide-skeleton.md` documents the slim `IdeAdapter` shape that the skill is built on.
+- The slice #2 PRD at `.peaks/_runtime/<sid>/prd/requests/002-2026-06-06-trae-adapter-and-peaks-ide-skill.md` documents the 13 ACs this skill is part of.
+- The slice #2 RD artifact (in flight) documents the implementation contract.
+
+## Default runbook
+
+The skill is invoked as `/peaks-ide` or via the natural-language triggers listed in the frontmatter. The runbook is the body of this SKILL.md (steps 1-5 plus the boundaries and reference sections above); the runbook-service extracts the section between this `## Default runbook` heading and the next `##` heading.
+
+When the user types `/peaks-ide` (or "set up peaks for my IDE" / "switch peaks to Trae" / "what did peaks install" / "uninstall peaks hooks"), execute Steps 1 → 5 in order:
+
+1. **Skill presence (MANDATORY first action)**: `peaks skill presence:set peaks-ide --project <repo> --gate startup` and `peaks project memories --project <repo> --json` (load durable memory).
+2. **Detect current state** (Step 1 above): `peaks project dashboard --project <repo> --json` + `peaks hooks status --project <repo> --json` + `peaks statusline status --project <repo> --json` + `ls -la <repo>/.claude 2>/dev/null` + `ls -la <repo>/.trae 2>/dev/null`. Build a 1-2 sentence state summary.
+3. **AskUserQuestion** (Step 2 above, only if intent is ambiguous). Default option: "Show current status". Destructive paths (Switch, Uninstall) gate on user confirmation here.
+4. **Plan & preview** (Step 3 above): print the exact `peaks hooks install` / `peaks statusline install` invocations before running them. Wait for "Proceed? (Y/n)".
+5. **Execute** (Step 4 above): run the `peaks hooks install` / `peaks statusline install` (or uninstall / status) commands. Stop on non-zero exit. Do not auto-rollback.
+6. **Audit log** (Step 5 above): delegate the JSONL write to `peaks project dashboard` (the canonical log writer; per the dev-preference red line, the skill MUST NOT introduce a new CLI primitive for the log writer).
+
+CLI primitives the skill composes (per the "Reference" section above): `peaks skill presence:set`, `peaks project memories`, `peaks project dashboard`, `peaks hooks install` / `uninstall` / `status`, `peaks statusline install` / `uninstall` / `status`, `peaks hook handle`, `peaks skill runbook`. The skill does NOT introduce any new `peaks <cmd>` command.

package/skills/peaks-qa/SKILL.md

@@ -60,8 +60,39 @@ This is the hard-block replacement for the previous "wait for the user" prose. W
 
 ## Sub-agent dispatch (when launched by peaks-solo swarm)
 
-When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
+When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+## QA fan-out (业务 + 性能 + 安全 并发, 业务可再分)
+
+When peaks-qa is the **main loop** (i.e. it is the active skill and is about to run its own sub-agent dispatch, rather than being a sub-agent itself), it fans out the 3 QA review activities concurrently using the same `peaks sub-agent dispatch` primitive:
+
+```
+peaks sub-agent dispatch qa-business \
+  --prompt "<qa-business contract, plus runtime args project=<repo>, session-id=<sid>, request-id=<rid>>" \
+  --request-id <rid> --session-id <sid> --project <repo> --json
+
+peaks sub-agent dispatch qa-perf \
+  --prompt "<qa-perf contract, plus runtime args>" \
+  --request-id <rid> --session-id <sid> --project <repo> --json
+
+peaks sub-agent dispatch qa-security \
+  --prompt "<qa-security contract, plus runtime args>" \
+  --request-id <rid> --session-id <sid> --project <repo> --json
+```
+
+All three are issued in a single message; the LLM fires all 3 returned toolCalls in parallel; the IDE runs them concurrently; peaks-qa then collects the three envelopes and merges their outputs into:
+
+- `.peaks/<sid>/qa/test-reports/<rid>.md` (business findings)
+- `.peaks/<sid>/qa/performance-findings.md` (perf findings)
+- `.peaks/<sid>/qa/security-findings.md` (security findings)
+
+## 业务测试细分 (optional)
+
+If the PRD or project warrants it, subdivide `qa-business` further into roles like `qa-business-api` / `qa-business-frontend` / `qa-business-regression`; each gets its own `peaks sub-agent dispatch` call. Names are convention not contract — the dispatcher accepts any non-empty string. **Subdivision must stay ≤ 2 levels deep** (RL-4): `qa-business-api` is fine, `qa-business-api-user` is not. Two levels of depth is the empirical sweet spot — past that, the reducer cannot audit the boundaries between sub-agents, and prompts start overlapping.
+
+For the full contract (heartbeat instructions for each sub-agent, batch-id discipline, 30s cadence, 100-truncation, 5min stale) see `skills/peaks-qa/references/qa-fanout-contract.md` and `skills/peaks-solo/references/sub-agent-dispatch.md` §G6.
+
+- **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-qa`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-qa.json` and only that.
 - **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
 - **Mode selection** — Solo has already chosen the mode.
@@ -525,3 +556,29 @@ Concrete rules and lint reference: `references/openspec-validation-gate.md`.
 Do not own product scope or implementation. Do not modify runtime configuration.
 
 Reference: `references/regression-gates.md`.
+
+## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+
+> QA sub-agents (qa / qa-business / qa-perf / qa-security) follow the same G7 metadata-only + G8.6 share protocol as RD. Detailed: `skills/peaks-solo/references/context-governance.md`.
+
+### G7 — QA sub-agent protocol
+
+1. Write test cases / perf baseline / security review to `.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-001.md` (path convention mandatory).
+2. Call `peaks sub-agent dispatch --write-artifact <path>` to register ArtifactMeta.
+3. Main LLM sees metadata-only view (~200 chars/QA sub-agent).
+
+### G8.6 — QA sub-agent prompt template
+
+```
+You are sub-agent role qa-<subrole>, batch <batchId>.
+
+PROTOCOL (mandatory):
+1. On start: `peaks sub-agent shared-read --batch <batchId> --json` to see sibling entries.
+2. While running: write share entry `peaks sub-agent share --key "qa-<subrole>.found-blocker" --value {"reason": "..."}` if a blocker is found.
+3. On completion: `peaks sub-agent share --key "qa-<subrole>.completed" --value <artifact-meta>` BEFORE final heartbeat (RL-23).
+```
+
+### G9 — QA prompt size self-check
+
+Same as RD: 50% soft warn, 75% `CONTEXT_NEAR_LIMIT`, 80% hard reject unless `--force`. QA test plans can grow large; prefer `--use-headroom balanced` for plans > 75%.
+

package/skills/peaks-qa/references/qa-fanout-contract.md

@@ -0,0 +1,150 @@
+# qa-fanout-contract.md — peaks-qa 3-way fan-out + business sub-division
+
+> **Slice**: 2026-06-07-sub-agent-dispatch-decouple (G3 + G5 + G6)
+> **Audience**: peaks-qa main loop and any future sub-role of peaks-qa
+> **Status**: stable
+
+This reference is the peaks-qa-specific contract for the 3-way fan-out
+(business / perf / security) and the optional business sub-division
+(`qa-business-api` / `qa-business-frontend` / `qa-business-regression` /
+...). peaks-qa is **itself a Dispatcher** (slice 2026-06-07 G1): when it
+is the main loop, it fans out 3 sub-agents in one message via the
+`peaks sub-agent dispatch <role>` primitive.
+
+## Why peaks-qa is a Dispatcher (not a Worker)
+
+The user has been explicit: "peaks-qa 是需要的,因为可以同时进行
+业务测试,性能测试,安全测试。而且业务测试还是可以再分的". Three concerns
+(business / perf / security) are **information-independent**:
+- business validation exercises the user's expected behavior,
+- perf baseline measures throughput / latency / memory,
+- security review audits the trust boundary.
+
+They have independent inputs (PRD / RD planning / codegraph for
+business; perf-signals for perf; trust model for security), independent
+outputs (different artifact paths), and can run concurrently without
+sharing mutable state. peaks-qa fans them out so QA wall-clock drops
+from "sum of all three" to "max of the three". Sub-dividing business
+(`qa-business-api` etc.) further drops wall-clock when the business
+slice is large.
+
+The 2-level cap (RL-4) is empirical: past 2 levels, the reducer cannot
+audit the boundaries between sub-agents and prompts start overlapping.
+
+## The 3-way fan-out
+
+When peaks-qa is the main loop and the QA phase is about to run, it
+issues 3 dispatch calls in a **single message**:
+
+```
+peaks sub-agent dispatch qa-business \
+  --prompt "<qa-business contract below, plus runtime args: project=<repo>,
+             session-id=<sid>, request-id=<rid>.
+             Write your evidence at .peaks/<sid>/qa/test-reports/<rid>.md
+             and return ONLY the path. While running, call
+             peaks sub-agent heartbeat --record <dispatchRecordPath>
+             --status running --progress <pct> --note '<text>' at least every 30s;
+             on completion call --status done --progress 100 --note 'completed'." \
+  --request-id <rid> --session-id <sid> --project <repo> --json
+
+peaks sub-agent dispatch qa-perf \
+  --prompt "<qa-perf contract below, plus runtime args; output .peaks/<sid>/qa/performance-findings.md>" \
+  --request-id <rid> --session-id <sid> --project <repo> --json
+
+peaks sub-agent dispatch qa-security \
+  --prompt "<qa-security contract below, plus runtime args; output .peaks/<sid>/qa/security-findings.md>" \
+  --request-id <rid> --session-id <sid> --project <repo> --json
+```
+
+The LLM reads the 3 `data.toolCall` descriptors from the envelopes and
+fires all 3 in the same message (real concurrency). peaks-qa then
+waits for all 3 to return, runs Gate B (`ls` checks on the 3 artifact
+paths), and merges their findings into the QA verdict.
+
+## Business sub-division (optional)
+
+If the project warrants it, `qa-business` can be split into:
+
+- `qa-business-api` — REST / RPC / message-bus contracts
+- `qa-business-frontend` — UI flows, component behavior, state machines
+- `qa-business-regression` — re-run a curated test plan against the slice diff
+
+Each gets its own `peaks sub-agent dispatch` call. The names are
+**convention not contract** — the dispatcher accepts any non-empty
+string. The recommended names above are hints, not a hard list.
+
+**Cap (RL-4)**: ≤ 2 levels deep. `qa-business-api` is fine;
+`qa-business-api-user` is not.
+
+## Independent inputs + independent artifacts
+
+| Sub-agent | Reads | Writes | Must not depend on |
+|---|---|---|---|
+| `qa-business` (or subdivisions) | PRD body, RD planning, codegraph, project scan, existing system | `qa/test-reports/<rid>.md` | perf / security output (run in parallel) |
+| `qa-perf` | RD planning, codegraph, perf baselines from prior slices | `qa/performance-findings.md` | business / security output |
+| `qa-security` | PRD body (trust model), codegraph, RD planning, existing security notes | `qa/security-findings.md` | business / perf output |
+
+The reducer merges all 3 outputs into the final QA verdict. None of
+the 3 sub-agents reads another sub-agent's output (no peer-to-peer
+messages — peaks is a pseudo-swarm, not a true bee colony).
+
+## Heartbeat instructions (G6)
+
+Each sub-agent prompt must include the heartbeat instruction so the
+parent peaks-qa can render a live status line during the wait. The
+recommended paragraph (also auto-generated by peaks CLI):
+
+```
+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'`. On
+failure call `--status failed --note '<reason>'`. Do not skip heartbeats;
+the parent peaks-qa uses them to render the live status line.
+```
+
+The `heartbeatIntervalSec` value can be overridden in the peaks-qa
+SKILL.md frontmatter (e.g. `heartbeatIntervalSec: 15` for fast QA
+sub-agents that finish in <2 min).
+
+## Batch counter (RL-1)
+
+peaks-qa is allowed up to 3 sub-agents in this fan-out by default. If
+business is sub-divided, the total batch size is `1 (business) + 1 (perf)
++ 1 (security) + N (business subdivisions) = 3 + N`. The peaks CLI
+emits a `BATCH_OVER_LIMIT` warning if the dispatch count exceeds the
+RL-1 empirical upper bound of 6, but does NOT block the dispatch (the
+user has been explicit: "RL-1 is empirical; if you have a real reason
+to go to 7, that's your call"). The warning goes into the dispatch
+envelope and into the slice's `reducerReport`.
+
+## Resource lifecycle (G5)
+
+- Each sub-agent dispatch writes a record to
+  `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json` (RL-5).
+- After the 3 sub-agents return, peaks-qa reducer marks each record
+  `disposed: true` + `disposedAt: <now>` (RL-7).
+- A reducer-report is emitted with
+  `{ batchId, total: 3 + N, disposed, leaked: 0 }`. `leaked > 0` is a
+  user-visible warning (RL-11).
+- Slice close archives the records to
+  `.peaks/_runtime/<sid>/_archive/_sub_agents/<slice-id>/` (RL-8).
+
+## Acceptance criteria covered
+
+- AC-17 (peaks-qa 3-way fan-out + 业务可再分)
+- AC-17b (peaks-ui说明行)
+- AC-26 / AC-34 (dispatch record schema)
+- AC-27 (RL-1 batch counter)
+- AC-28 (reducer dispose)
+- AC-29 (fan-out 原则)
+- AC-33..AC-36 (G6 heartbeat + SKILL.md)
+- AC-37 (E2E dogfood)
+
+## Cross-reference
+
+- `skills/peaks-solo/references/sub-agent-dispatch.md` — orchestrator
+  contract for all Dispatchers
+- `skills/peaks-solo/SKILL.md` "Peaks-Cli Swarm parallel phase" — sibling
+  fan-out pattern
+- `.peaks/memory/sub-agent-resource-lifecycle-red-line.md` — G5 red line
+- `.peaks/memory/sub-agent-heartbeat-progress-red-line.md` — G6 red line

package/skills/peaks-rd/SKILL.md

@@ -37,8 +37,9 @@ The full hard-block contract is defined in `peaks-qa` (see "Hard contracts for b
 
 ## Sub-agent dispatch (when launched by peaks-solo swarm)
 
-When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
+When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+- **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 Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-rd.json` and only that.
 - **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
 - **Mode selection** — Solo 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).
@@ -46,7 +47,7 @@ When this skill is launched as a sub-agent via `Task(subagent_type="general-purp
 
 What the sub-agent **MUST** still do, from this skill's contract:
 
-0. **Do NOT call `peaks request init`** — Solo 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.
+0. **Do NOT call `peaks request init`** — Solo 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; Solo owns the apply step).
 4. Project-scan read; create `rd/project-scan.md` only if Solo flagged it missing in the dispatch prompt.
@@ -565,7 +566,7 @@ If any gate fails, return to development for fixes or hand off as blocked. Do no
 
 ## Parallel review fan-out (code-review + security-review + perf-baseline + qa-test-cases)
 
-**When RD reaches the end of implementation, the four review activities (code review, security review, perf baseline, AND QA test-cases draft) run in parallel via Task() sub-agents, not sequentially.** This is the same fan-out pattern peaks-solo uses for the post-PRD swarm (see `peaks-solo/SKILL.md` "Peaks-Cli Swarm parallel phase" L659-764). RD itself, when it is the main loop, behaves as a sub-agent orchestrator: it issues 4 Task() calls in a single message and waits for all to return before aggregating findings and transitioning to `qa-handoff`.
+**When RD reaches the end of implementation, the four review activities (code review, security review, perf baseline, AND QA test-cases draft) 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 (see `peaks-solo/SKILL.md` "Peaks-Cli Swarm parallel phase" L659-764). RD itself, when it is the main loop, behaves as a sub-agent orchestrator: it issues 4 `peaks sub-agent dispatch` calls in a single message and waits for all to return before aggregating findings and transitioning to `qa-handoff`.
 
 **Why 4 sub-agents (added in slice 004):** the original 3-way fan-out (code-review + security-review + perf-baseline) cut the RD→QA wall-clock by running 3 LLM writes in parallel, but `qa/test-cases/<rid>.md` was still written sequentially by QA's main loop AFTER the RD handoff landed. Drafting QA test-cases in the same fan-out means the QA main loop's first action is "execute the pre-drafted test plan + write test-report" instead of "draft a test plan from scratch + execute + write report". Wall-clock drop: ~30-40% on the RD→QA-verdict segment for `feature` / `refactor` / `bugfix` slices.
 
@@ -574,14 +575,18 @@ If any gate fails, return to development for fixes or hand off as blocked. Do no
 - Bugfix slices: code-review + security-review + qa-test-cases always run; perf-baseline runs only when the bug is performance-shaped (matches the "When this applies" criteria in the perf-baseline section above).
 - Config / docs / chore slices: no fan-out (no review surface). Document N/A in the request artifact. (qa-test-cases also skipped — config / docs / chore have no acceptance surface to validate.)
 
-**The Task() template (mirror of peaks-solo L705-717):**
+**The dispatch template (mirror of peaks-solo L705-717):**
 
 ```
-Task(
-  subagent_type="general-purpose",
-  description="<role> review for rid=<rid>",
-  prompt="<role contract below>, plus runtime args: project=<repo>, session-id=<sid>, request-id=<rid>. Write your evidence file at .peaks/<sid>/<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."
-)
+peaks sub-agent dispatch <role> \
+  --prompt "<role contract below>, plus runtime args: project=<repo>, session-id=<sid>, request-id=<rid>.
+             Write your evidence file at .peaks/<sid>/<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 <sid> --project <repo> --json
 ```
 
 Note: sub-agents 1-3 write to `rd/<evidence-path>`, sub-agent 4 writes to `qa/test-cases/<rid>.md` (QA's dir). The role name in the description differentiates them.
@@ -790,3 +795,41 @@ Do not bypass PRD/QA artifacts. Do not install hooks, agents, MCP, or settings.
 Do not bypass the parallel review fan-out when the slice has a code-review / security-review / perf-baseline surface — see `## Parallel review fan-out` above for the contract. The three review activities are fan-out, not sequential; sequential re-implementation of the same logic by the main RD loop defeats the wall-clock benefit and is treated as a red-line violation.
 
 Reference: `references/refactor-workflow.md`.
+
+## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+
+> Slice #010 implements the G7 + G7.7 + G8 + G9 red lines from slice #009 closeout. RD sub-agent prompt template MUST include the G7 path convention + G8.6 share protocol. Detailed protocol: `skills/peaks-solo/references/context-governance.md` + `skills/peaks-solo/references/headroom-integration.md`.
+
+### G7 — RD sub-agent protocol
+
+1. Write artifact to `.peaks/_sub_agents/<sid>/artifacts/<rid>-rd-001.md` (path convention mandatory).
+2. Call `peaks sub-agent dispatch --write-artifact <path>` (or via the dispatch CLI flag) to register ArtifactMeta.
+3. The dispatch record stores only `path + size + sha256 + status + contentInlined:false + summary` — main LLM sees ~200 chars/sub-agent.
+
+### G8.6 — RD sub-agent prompt template (mandatory)
+
+Sub-agent prompts dispatched by peaks-rd must include:
+
+```
+You are sub-agent role rd, 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 "rd.found-blocker" --value {"reason": "..."}`.
+3. On completion: write share entry
+   `peaks sub-agent share --key "rd.completed" --value <artifact-meta>` BEFORE the
+   final `peaks sub-agent heartbeat --status done` heartbeat (RL-23 strong constraint).
+4. The shared channel is your only visibility into sibling sub-agents.
+   Do NOT attempt to read other sub-agents' dispatch records directly.
+```
+
+### G9 — RD prompt size self-check
+
+Before dispatching a sub-agent, RD self-checks prompt size:
+- < 50%: pass through.
+- 50-75%: soft warn (consider `--use-headroom`).
+- 75-80%: soft warn + `warnings: ["CONTEXT_NEAR_LIMIT"]` (mandatory suggest `--use-headroom`).
+- 80%+: reject (CLI 兜底 returns `code: "PROMPT_TOO_LARGE"`). Use `--force` at CLI only when overriding; hook layer will still reject (RL-30).
+