peaks-cli 1.3.1 → 1.3.3

package/skills/peaks-solo/SKILL.md

@@ -44,7 +44,7 @@ peaks-solo (orchestrate only)
 
 | Mode | Swarm side (after PRD) | Repair loop side (RD↔QA) |
 |---|---|---|
-| `full-auto` / `swarm` | `Task(subagent_type="general-purpose")` sub-agent running `peaks-rd`/`peaks-qa`/`peaks-ui` body | `Task(...)` sub-agent per cycle |
+| `full-auto` / `swarm` | `peaks sub-agent dispatch <role>` — IDE-agnostic dispatch primitive; CLI returns a tool-call descriptor the LLM executes in its own environment | `peaks sub-agent dispatch <role>` per cycle |
 | `assisted` / `strict` / inline-fallback | Solo executes the role steps inline in the main loop (the `peaks-solo` skill IS the role's owner) | Solo executes inline |
 
 In all modes, the work itself follows the same `peaks-rd` and `peaks-qa` contracts. The only difference is whether the role's body is being read by a sub-agent Task prompt or by Solo's own main loop. **Never bypass the role contracts regardless of which path runs.**
@@ -192,7 +192,7 @@ done
 **Strict quality guarantee (per user's hard rule: "严格要保证不能比当前的效果差")**:
 - If no in-flight slice is detected, this step is a no-op: zero extra commands beyond the existing Step 0 probe, zero extra token cost.
 - If an in-flight slice is detected, the cost is one `find` + one `grep` loop (sub-millisecond) + one `AskUserQuestion` (one round-trip). The savings are 3-5k tokens (the cost of manually re-reading 3-5 artifact files).
-- The dogfood test in `tests/unit/skill-resume-mode.test.ts` (added in this slice) asserts: (a) fresh-session classification returns "no resume", (b) in-flight slice classification returns the right gate, (c) the classification is deterministic across two invocations on the same fixture.
+- The dogfood test in `tests/unit/skill-resume-mode.test.ts` (8 cases, bash-fixture shim — the legacy interface used by `skills/peaks-solo-resume`) and `tests/unit/services/skill/resume-detector.test.ts` (24 cases, the canonical TypeScript classifier at `src/services/skill/resume-detector.ts`) together cover: (a) fresh / complete / resume:rd-planning / resume:qa-validation / resume:txt-handoff state-based classifications, (b) the "Other resume triggers" overrides (missing `rd/tech-doc.md` → `rd-planning`; missing `rd/code-review.md` or `rd/security-review.md` → `rd-review-fanout`; missing `qa/test-reports/<rid>.md` → `qa-execution`), (c) the mid-implementation distinction (`spec-locked` / `implemented` / `running` / `blocked` all return `in-flight:<state>`), (d) the primary-vs-abandoned filter (multiple RDs → spec-locked wins; single blocked RD stays primary; 2+ all-abandoned → fresh), (e) the legacy `.peaks/<sid>/` path fallback, and (f) determinism across two invocations on the same fixture.
 
 ### Peaks-Cli Step 1: Mode selection
 
@@ -262,6 +262,12 @@ peaks session title $(cat .peaks/.session.json | python3 -c "import sys,json; pr
 
 If the session directory already has a title (check via `peaks session list --json`), skip this step — the title is already set.
 
+## Sub-agent session sharing (MANDATORY — one conversation = one sid)
+
+When peaks-solo dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt, peaks-sc), the sub-agent prompt MUST include the parent's session id. The sub-agent then passes `--session-id <parent-sid>` for any session-creating CLI call (e.g. `peaks request init --session-id <parent-sid>`). The sub-agent MUST NOT call `peaks workspace init` — that would create a new session dir and orphan the parent's binding. The sub-agent reads `.peaks/_runtime/session.json` to discover the parent's sid (or the orchestrator passes it explicitly). Sub-agents also accept the parent's sid via the new `peaks session info --active` primitive when they need a one-shot read.
+
+Note: `peaks request init` is **dry-run by default** — the JSON response has `applied: false` and no file is written unless `--apply` is passed. This is the same safe-by-default pattern as `peaks workspace migrate --apply`. Sub-agents that need to actually create a slice must add `--apply`.
+
 ## Boundaries
 
 Peaks-Cli Solo may:
@@ -618,24 +624,26 @@ Sub-agent presence in this list = Solo launched a Task for it. Absence = the rol
 
 In all modes, **the plan must be written to `sc/swarm-plan.json` before any Task call.** Solo updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
 
-### Sub-agent mechanism (Task tool, NOT Skill tool)
+### Sub-agent mechanism (IDE-agnostic dispatch, NOT Skill tool)
 
-**Solo is itself a skill running in the current session. To invoke a role in the Swarm, Solo MUST use the `Task` tool with `subagent_type="general-purpose"` and a prompt that embeds the role's contract — NOT the `Skill` tool.** The `Skill` tool is single-stack and blocking; using it for "parallel" work was the v1.x illusion of concurrency. The Task tool is the only mechanism that gives real fan-out in Claude Code.
+**Solo is itself a skill running in the current session. To invoke a role in the Swarm, Solo MUST call the IDE-agnostic dispatch primitive `peaks sub-agent dispatch <role>` — NOT the `Skill` tool, NOT any IDE-private sub-agent literal.** The `Skill` tool is single-stack and blocking; using it for "parallel" work was the v1.x illusion of concurrency. The dispatch CLI is the only mechanism that keeps SKILL.md free of IDE-private tool names and lets the same prompt work on every registered IDE.
 
-Each sub-agent Task call looks like:
+Each sub-agent dispatch call looks like:
 
 ```
-Task(
-  subagent_type="general-purpose",
-  description="<role> for rid=<rid>",
-  prompt="<paste peaks-<role>/SKILL.md body, minus the self-presence / Step 0 blocks, plus
-          the runtime arguments: project=<repo>, session-id=<sid>, request-id=<rid>, mode=<mode>>
-          plus the explicit output contract: 'Write your artefacts to the paths listed below and
-          return only the list of paths. Do not call Skill(...). Do not set presence. Do not
-          hand back prose.'"
-)
+peaks sub-agent dispatch <role> \
+  --prompt "<paste peaks-<role>/SKILL.md body, minus the self-presence / Step 0 blocks,
+            plus the runtime arguments: project=<repo>, session-id=<sid>, request-id=<rid>, mode=<mode>,
+            plus the explicit output contract: 'Write your artefacts to the paths listed below and
+            return only the list of paths. Do not call Skill(...). Do not set presence. Do not
+            hand back prose.', plus the heartbeat instruction: 'While running, call
+            peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note \"<text>\"
+            at least every 30 seconds.'>" \
+  --request-id <rid> --session-id <sid> --project <repo> --json
 ```
 
+Then the LLM takes `data.toolCall` from the envelope (a `{name, args}` descriptor), looks up the tool by `name` in its environment, and invokes it with `args` — IDE-private, no SKILL.md hardcoding.
+
 The role's required artefact paths (also see peaks-ui/rd/qa SKILL.md and `references/swarm-dispatch-contract.md`):
 
 | Role | Writes | Reads (PRD-side) |
@@ -644,16 +652,17 @@ The role's required artefact paths (also see peaks-ui/rd/qa SKILL.md and `refere
 | `rd-planning` | `.peaks/<sid>/rd/tech-doc.md` (feature/refactor) or `.peaks/<sid>/rd/bug-analysis.md` (bugfix) | PRD body, project-scan, existing-system, codegraph |
 | `qa-test-cases` | `.peaks/<sid>/qa/test-cases/<rid>.md` | PRD body, RD planning artefact, project-scan, codegraph |
 
-**Solo launches all sub-agents in the swarm plan in a single message (multiple Task tool calls in parallel)** — this is what gives real concurrency. Do not sequentialize them. Solo then waits for all to return, runs `ls` checks against the paths above (Peaks-Cli Gate B), and only then advances to RD implementation.
+**Solo launches all sub-agents in the swarm plan in a single message (multiple `peaks sub-agent dispatch` calls in parallel, each followed by execution of the returned toolCall)** — this is what gives real concurrency. Do not sequentialize them. The CLI returns N toolCall descriptors; the LLM fires all N in the same message; the IDE dispatches them concurrently; Solo then waits for all to return, runs `ls` checks against the paths above (Peaks-Cli Gate B), and only then advances to RD implementation.
 
-**Hard prohibitions on sub-agents** (also passed in each Task prompt):
+**Hard prohibitions on sub-agents** (also passed in each dispatch prompt):
 
 - Do NOT call `Skill(skill="...")` — sub-agents must not recursively activate skills, that defeats the fan-out.
 - Do NOT call `peaks skill presence:set` — only the main Solo loop owns `.peaks/.active-skill.json`. Sub-agents write to a per-agent marker file `.peaks/<sid>/system/sub-agent-<role>.json` if they need to record state, but never the main presence file.
 - Do NOT open interactive user prompts. If a sub-agent needs clarification, it must return a `blocked` verdict in its return string and let Solo handle the user message.
 - Do NOT commit, push, install hooks, or apply settings.json mutations. Only Solo holds those permissions.
+- **Do write heartbeats** — call `peaks sub-agent heartbeat --record <dispatchRecordPath> --status running --progress <pct> --note "<text>"` at least every 30s (see `references/sub-agent-dispatch.md` §G6 for the full contract). The parent Dispatcher uses these to render the live status line during the wait.
 
-After every sub-agent Task returns, Solo **restores presence** once (not per-agent), then continues to Gate B verification:
+After every sub-agent dispatch returns, Solo **restores presence** once (not per-agent), then continues to Gate B verification:
 
 ```bash
 peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
@@ -700,7 +709,7 @@ After `peaks-rd` finishes any implementation, repair, or code-output slice, Peak
 
 Solo is itself a skill running in the current session. There are **two distinct mechanisms** in this skill, and they MUST NOT be confused:
 
-1. **Swarm fan-out (planning side, after PRD confirmed)** — uses the `Task` tool with `subagent_type="general-purpose"` to launch real concurrent sub-agents. See "Peaks-Cli Swarm parallel phase" above for the full contract. Sub-agents do NOT call Skill(...) back into the role; they execute the role's instructions inline from the prompt.
+1. **Swarm fan-out (planning side, after PRD confirmed)** — uses `peaks sub-agent dispatch <role>` to launch real concurrent sub-agents. The CLI returns a per-IDE tool-call descriptor that the LLM executes in its environment. See "Peaks-Cli Swarm parallel phase" above for the full contract. Sub-agents do NOT call Skill(...) back into the role; they execute the role's instructions inline from the prompt.
 2. **Sequential handoff (execution side, RD↔QA repair loop)** — Solo is the only loop, and after RD or QA finishes (whether as a sub-agent or directly), Solo drives the next step from the orchestrator seat. Do NOT use the `Skill` tool to "reactivate" peaks-rd or peaks-qa in the main loop; doing so is the v1.x anti-pattern that masqueraded as "calling the role" but actually just re-prompted the same session. From v1.3 onward, the main loop drives roles via the CLI gate (`peaks request transition`) and reads back artefacts (`peaks request show ... --json`); the actual RD/QA work is either done inline by Solo (when Solo has just been re-invoked by the user) or by a Task sub-agent (in swarm mode).
 
 After RD completes (whether inline or sub-agent), Solo does not stop — it must advance to QA. There is no "RD done, ask the user" state in full-auto mode. The only valid stops are: (a) QA verdict=pass, (b) repair cap hit, (c) explicit user cancel.
@@ -715,7 +724,7 @@ peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <curre
 
 This keeps the CLAUDE.md status header accurate (`Peaks-Cli Skill: peaks-solo`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last-known gate permanently.
 
-**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately drives QA — by launching a `Task(subagent_type="general-purpose", ...)` sub-agent carrying the `peaks-qa` body (swarm path), or by running QA inline in the main loop (assisted/strict path). Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
+**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately drives QA — by launching a `peaks sub-agent dispatch qa` sub-agent carrying the `peaks-qa` body (swarm path), then executing the returned toolCall, or by running QA inline in the main loop (assisted/strict path). Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
 
 A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
 
@@ -732,7 +741,7 @@ When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite R
    ```
    `spec-locked` is the canonical "needs more RD work" state. The reason is mandatory in repair cycles so the artifact history shows the loop.
 3. Re-launch `peaks-rd` work. Two paths, mode-driven:
-   - **Swarm / full-auto**: launch a fresh `Task(subagent_type="general-purpose", ...)` sub-agent with the same `peaks-rd` body used in the Swarm phase, plus the QA findings path so it can read the failure list. Solo restores presence after the sub-agent returns.
+   - **Swarm / full-auto**: launch a fresh `peaks sub-agent dispatch rd` sub-agent (then execute the returned toolCall) with the same `peaks-rd` body used in the Swarm phase, plus the QA findings path so it can read the failure list. Solo restores presence after the sub-agent returns.
    - **Assisted / strict / inline-fallback**: Solo executes the RD repair steps directly in the main loop, since there is no concurrent fan-out to coordinate.
    In both paths, pass the QA findings path so the repair sees what failed.
 4. peaks-rd fixes the reported issues only (red-line scope: do not modify unrelated surfaces), regenerates code-review and security-review evidence if changes touched reviewed surfaces, then transitions `rd → implemented → qa-handoff` again.
@@ -850,3 +859,57 @@ Do not run upstream installer flows, mutate agent settings, or commit `.codegrap
 **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/openspec-mcp-workflow.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`.
+
+## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+
+> Slice #010 adds the **layer 3.5** context-governance push to the slice #009 sub-agent dispatch primitives. This section is the MANDATORY reference for the main LLM reducer. Detailed protocol: `references/context-governance.md` + `references/headroom-integration.md`.
+
+### G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
+
+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/<sid>/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-solo] 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)
+
+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)
+
+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/<sid>/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)
+
+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-solo/references/context-governance.md

@@ -0,0 +1,144 @@
+# 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-solo] 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)
+
+| 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 + `contextWarning: 'high'` |
+
+### 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.

package/skills/peaks-solo/references/headroom-integration.md

@@ -0,0 +1,107 @@
+# Headroom Integration — G7.7 opt-in compression channel
+
+> Slice #010 (G7.7 headroom-ai integration route).
+> Source: https://github.com/chopratejas/headroom
+> Package: `headroom-ai@0.22.4` (Apache-2.0, MIT-compatible).
+> See: `THIRD_PARTY_LICENSES.md` for the license record.
+
+## Why headroom-ai is justified (R-14)
+
+The dev-preference red line "非必要不添加新的 dep" is preserved:
+headroom-ai is the only opt-in mechanism for G7.7 + G9 to compress
+sub-agent prompts that exceed the 75% / 80% threshold. Without
+headroom-ai, `--use-headroom` is a no-op and the only fallback is
+`--force` override at CLI.
+
+The user's explicit reference (https://github.com/chopratejas/headroom)
+is the basis for the dev-preference override.
+
+## API shape (real SDK, not the PRD's spec)
+
+```ts
+import { compress } from 'headroom-ai';
+
+const result = await compress(messages, {
+  model: 'claude-sonnet-4-5-20250929',
+  baseUrl: 'http://localhost:8787',  // local proxy; not used in slice #010
+  apiKey: 'hr_...',                   // Headroom Cloud; not used in slice #010
+  timeout: 30_000,
+  fallback: true,                     // CRITICAL: return original messages if proxy is dead
+  retries: 1,
+  tokenBudget: 4000,                  // compress to fit this limit
+  hooks: new MyHooks(),               // pre/post compression hooks
+});
+
+result.messages          // compressed messages
+result.tokensBefore      // original token count
+result.tokensAfter       // compressed token count
+result.tokensSaved       // tokens removed
+result.compressionRatio  // tokensAfter / tokensBefore
+result.transformsApplied // e.g. ['router:smart_crusher:0.35']
+result.compressed        // false if fallback kicked in
+```
+
+`fallback: true` is the key option: if the proxy is unavailable, the SDK
+returns the original messages + `result.compressed: false` instead of
+throwing. This makes the failure mode non-blocking (RL-22d / RL-32).
+
+## Mode table (peaks wrapper)
+
+The peaks wrapper maps the user-facing `HeadroomMode` to the SDK's
+`tokenBudget` option. Slice #010 does not consume the SDK's internal
+"audit" / "optimize" / "simulate" modes (those are SDK-internal);
+
+| 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, accuracy-critical |
+
+The `0.40 / 4` factor approximates 60% byte reduction (1 token ≈ 4 bytes
+for English text). The SDK does its own tokenization internally; the
+`tokenBudget` is a hint, not a hard cap.
+
+## Failure semantics (RL-22d / RL-32)
+
+- `result.compressed === false` → `code: "HEADROOM_UNAVAILABLE"` warning
+- `compress()` throws (network error, JSON parse error) → caught and treated as `HEADROOM_UNAVAILABLE`
+- Import failure (headroom-ai not installed) → caught and treated as `HEADROOM_UNAVAILABLE`
+- **NOT blocking** — peak falls back to G7 metadata-only and continues dispatch
+
+## CCR reversible hydration (slice #011+ TODO)
+
+The PRD mentions "CCR (Cross-Context Reversible)" as a benefit of
+headroom. In the SDK, this is implemented via the `hooks` option on
+`compress()`. A pre/post hook can persist the `ccrHashes` to disk,
+and a later `rehydrate()` call can re-hydrate the compressed prompt
+to the original. Slice #010 does NOT consume CCR — it only uses
+compression. R-17 (CCR for aggressive / conservative modes) is
+deferred to slice #011+.
+
+## Cross-platform behavior (R-19)
+
+- In-process compression (the SDK's library mode) is platform-agnostic.
+- The long-running `headroom proxy` daemon is platform-specific
+  (Unix socket on Linux/macOS, named pipe on Windows). Slice #010
+  does NOT consume the proxy daemon.
+- All headroom-ai calls in slice #010 go through the in-process SDK
+  with `fallback: true`. The peak wrapper at
+  `src/services/context/headroom-client.ts` catches all errors and
+  treats them as fallback.
+
+## What slice #010 does NOT do
+
+- Does NOT install the `headroom proxy` daemon (N-7).
+- Does NOT consume headroom's `SharedContext` directly (G7.7.3 in the
+  PRD); the peak-internal `SharedChannel` (G8) is the cross-sub-agent
+  state store. `buildSharedContextBridge()` is a stub that returns
+  the peak-internal channel ID + a placeholder headroom context ID.
+- Does NOT use the SDK's `audit` / `optimize` / `simulate` modes
+  (those are SDK-internal; the peak wrapper exposes
+  `balanced` / `aggressive` / `conservative` to the user).
+
+## Security + license
+
+- License: Apache-2.0 (MIT-compatible) — see `THIRD_PARTY_LICENSES.md`.
+- Pinned version: exact `0.22.4` (no `^` / `~` range) per dev-preference.
+- `pnpm audit` ran on install; no new high-severity vulnerabilities.

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

@@ -53,10 +53,10 @@ peaks request lint <rid> --role prd --project <repo> --json
 peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
 peaks request transition <rid> --role prd --state handed-off --project <repo> --json
 
-# 3. Peaks-Cli Swarm parallel — sub-agent fan-out (Task tool, NOT Skill tool)
+# 3. Peaks-Cli Swarm parallel — sub-agent fan-out (peaks sub-agent dispatch, NOT Skill tool)
 #    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
 #    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
-#    Task(subagent_type="general-purpose", ...) call per sub-agent in the same message.
+#    `peaks sub-agent dispatch <role>` call per sub-agent in the same message.
 #    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
 #    prompt template; the role's required artefact paths are listed there.
 #    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
@@ -75,7 +75,7 @@ peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-
 # e.g. if plan = [ui, rd, qa]: run init for ui, rd, qa.
 # If plan = [rd, qa]: run for rd, qa only.
 # If plan = [] (config|docs|chore skip): no inits here, jump to step 4 directly.
-# 3b. Solo issues N Task(subagent_type="general-purpose", ...) calls in ONE message
+# 3b. Solo issues N `peaks sub-agent dispatch <role>` calls in ONE message
 #     (N = len(swarm-plan.subAgents)). Each prompt embeds the role's body minus
 #     Step 0 / presence, plus the runtime args (rid / sid / mode / type / paths).
 # 3c. After fan-out, Solo restores presence once and runs Gate B (ls checks):