peaks-cli 1.3.2 → 1.3.4

package/skills/peaks-solo/SKILL.md

@@ -3,6 +3,36 @@ name: peaks-solo
 description: Full-auto orchestration facade for the Peaks-Cli skill family. Use when the user asks Peaks-Cli to handle a project workflow end-to-end (端到端/全流程/需求开发), especially from a product document (产品文档/PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-ui, peaks-qa, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-solo`, "peaks solo", "全流程开发", "端到端迭代", "根据产品文档开发", "从需求到上线".
 ---
 
+## Two-axis naming convention
+
+> **Read once at the top of this file; the rest of the skill is written against it.**
+
+The `.peaks/` workspace is partitioned by **two orthogonal axes**. Every path in this SKILL.md uses one of them; mixing them is the original `.peaks/<sid>/` / `.peaks/_runtime/<sid>/` bug class this slice corrects.
+
+| Axis | Path root | Holds | When to use |
+|---|---|---|---|
+| **change-id axis** (reviewable artifacts) | `.peaks/<changeId>/...` | PRD, RD plan, code-review, security-review, test-cases, handoff capsules, gate targets | The artifact should be reviewable on its own and survives across sessions for the same change. Change-id is the unit of work. |
+| **session-id axis** (ephemeral state) | `.peaks/_runtime/<sessionId>/...` | Session bindings (`.peaks/_runtime/session.json`), live in-flight state, the per-session project-scan and tech-doc scaffold while the session is open | The artifact is session-scoped and only meaningful while the parent session is live. |
+| **sub-agent axis** | `.peaks/_sub_agents/<sessionId>/...` | Sub-agent dispatch records, sub-agent heartbeats, per-sub-agent shared channel entries, sub-agent artifact outputs | A sub-agent ran in a parent session. The axis nests under the parent session-id; sub-agent outputs are flushed into the change-id root on commit. |
+
+**Which CLI commands operate on which axis:**
+
+- **change-id axis** (reviewable artifacts): `peaks request init`, `peaks request transition`, `peaks request show`, `peaks request lint`, `peaks request repair-status`, `peaks scan diff-vs-scope`, `peaks scan acceptance-coverage`. Inputs reference `.peaks/<changeId>/...`.
+- **session-id axis** (ephemeral state): `peaks session info`, `peaks session start`, `peaks session finish`, `peaks session list`. Reads/writes `.peaks/_runtime/<sessionId>/session.json`.
+- **sub-agent axis** (under parent session-id): `peaks sub-agent dispatch`, `peaks sub-agent heartbeat`, `peaks sub-agent share`, `peaks sub-agent shared-read`. All output paths are under `.peaks/_sub_agents/<sessionId>/...`.
+
+**Placeholder convention used in this file:**
+
+- `<changeId>` / `<change-id>` — the change-id axis. Use when describing a path that lives at `.peaks/<changeId>/...` (root-level, NOT inside `_runtime/`).
+- `<sessionId>` / `<session-id>` — the session-id axis. Use when describing a path that lives at `.peaks/_runtime/<sessionId>/...` or `.peaks/_sub_agents/<sessionId>/...`. The long form `<session-id>` is used inside bash / shell examples where `<sessionId>` would break parsing.
+- The bare `<sid>` placeholder is **forbidden** in new content — it is ambiguous between the two axes. Legacy occurrences are replaced by this convention; new content must use the right axis label.
+
+**Cross-references:**
+
+- Slice `2026-06-05-change-id-as-unit-of-work` (commits `48958fc` + `928eb53`) — established the change-id axis as the canonical root for reviewable artifacts (`src/shared/change-id.ts:131,335`, `src/services/scan/acceptance-coverage-service.ts:155`).
+- Slice `005-session-runtime-dir-regression` (commit `178a47e`) — added the `getSessionDir()` resolver at `src/services/session/getSessionDir.ts` and routed 4 stragglers that were constructing `.peaks/${sessionId}` (no `_runtime/`) through the canonical resolver. Defense-in-depth scan: `tests/unit/services/session/session-dir-canonical.test.ts`.
+- Slice `006-5th-writer-changeid-path` (this slice) — disambiguates the SKILL.md placeholders and adds the regression test `tests/unit/skills/skills-skill-md-naming.test.ts` that mechanically enforces (a) zero bare `<sid>`, (b) every `.peaks/<X>/` reference has an axis label, (c) the "Two-axis naming convention" callout is present in `peaks-solo`, `peaks-rd`, `peaks-qa`.
+
 # Peaks-Cli Solo
 
 Peaks-Cli Solo is the orchestration facade for the Peaks-Cli short skill family.
@@ -44,7 +74,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 +222,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/_runtime/<sessionId>/` path fallback, and (f) determinism across two invocations on the same fixture.
 
 ### Peaks-Cli Step 1: Mode selection
 
@@ -294,7 +324,7 @@ Use the Peaks-Cli CLI for runtime side effects.
 
 Map gstack stages to Peaks-Cli role artifacts; preserve Peaks-Cli confirmation gates. Do not delegate orchestration to gstack commands.
 
-For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` tool namespace) for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
+For frontend workflows, RD and QA must use Playwright MCP for real browser E2E. The skill body never bakes in the `mcp__playwright__` prefix; it uses the peaks mcp plan/apply/call pattern (`peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` then `peaks mcp call --capability playwright-mcp.browser-validation --tool <toolName> --args-json '<args>' --json`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
 
 ## Peaks-Cli Local intermediate artifact workspace (MANDATORY)
 
@@ -326,7 +356,7 @@ The workspace initialization creates this structure under `.peaks/`:
 
 # Per-slice artifact dirs (auto-generated, one per session). Files
 # inside ARE tracked by the 提交中间产物 convention.
-.peaks/<session-id>/
+.peaks/_runtime/<sessionId>/
 prd/source/      # PRD source documents (Feishu exports, pasted content)
 prd/requests/    # PRD request artifacts (goals, non-goals, acceptance, frontend delta)
 ui/requests/     # UI request artifacts (visual direction, taste reports)
@@ -364,7 +394,7 @@ Files written into these directories during the workflow (not pre-created — th
 
 Legitimate source files (e.g. `jest-setup.ts`, `tailwind.config.js`) belong at root — do not move them.
 
-If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/<session-id>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/<session-id>/` and note the migration in the TXT handoff.
+If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/_runtime/<sessionId>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/_runtime/<sessionId>/` and note the migration in the TXT handoff.
 
 ### Git and sync policy
 
@@ -372,7 +402,7 @@ Do not default to git-backed storage or automatic commits for intermediate artif
 
 ## Peaks-Cli Pre-RD project scan checklist (MANDATORY)
 
-Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/<session-id>/rd/project-scan.md`. RD and UI roles read this before starting work. **project-scan.md is a session-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/<session-id>/rd/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
+Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/_runtime/<sessionId>/rd/project-scan.md`. RD and UI roles read this before starting work. **project-scan.md is a session-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/_runtime/<sessionId>/rd/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
 
 ### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
 
@@ -522,7 +552,7 @@ When there is no conflict, do not ask — the CLI value wins and the workflow pr
 
 ### Mock data strategy selection
 
-Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
+Solo records the chosen mock strategy in `.peaks/_runtime/<sessionId>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
 
 | Project data-fetching pattern | Recommended mock approach | Rationale |
 |---|---|---|
@@ -541,7 +571,7 @@ Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` un
 2. Mock data should be realistic (not `"test"`, `"foo"`, `123`) — use plausible Chinese/English content that resembles production data.
 3. Each mock must export its TypeScript interface so RD implementation and QA test-cases can import the same types.
 4. Mark every mock file with a header comment: `// MOCK: Replace with real API call when swagger.json is available`.
-5. Before producing any mock file, register the plan in `.peaks/<session-id>/rd/mock-plan.md` with: chosen strategy (from the table above), planned file paths, and a one-line rationale per file. This file is the source of truth for mock locations across runs — RD must read it before writing code, QA must read it before writing test cases.
+5. Before producing any mock file, register the plan in `.peaks/_runtime/<sessionId>/rd/mock-plan.md` with: chosen strategy (from the table above), planned file paths, and a one-line rationale per file. This file is the source of truth for mock locations across runs — RD must read it before writing code, QA must read it before writing test cases.
 
 ### API contract placeholder pattern
 
@@ -572,7 +602,7 @@ When the PRD source is a Feishu/Lark document that requires authentication:
 
 1. **Primary path**: Playwright MCP headed browser → user completes login → Solo reads document content via `browser_snapshot`.
 2. **Fallback A (user cannot login)**: Ask user to copy-paste the document content or export as Markdown/PDF. Solo creates the PRD artifact from the pasted content.
-3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/<session-id>/prd/source/`. Solo reads and processes it.
+3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/_runtime/<sessionId>/prd/source/`. Solo reads and processes it.
 4. **Fallback C (none of the above)**: Mark PRD as `blocked` with reason `doc-inaccessible`, list the exact next steps for the user, and pause the workflow.
 
 Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
@@ -595,11 +625,11 @@ Before launching any sub-agent, Solo must compute the **swarm plan** from three
    - `feature` / `refactor` / `bugfix` → RD(planning) and QA(test-cases) are always in the swarm
    - `config` / `docs` / `chore` → no swarm. RD/QA artefacts are not required by Gates B/C/D for these types. Skip the Swarm phase entirely and proceed to step 4 (RD implementation) with only the PRD in hand.
 3. **Frontend touch** — does the request affect user-visible behavior? This is decided by:
-   - Reading `.peaks/<session-id>/rd/project-scan.md` `## Project mode` for `frontendOnly` (project-shape signal)
+   - Reading `.peaks/_runtime/<sessionId>/rd/project-scan.md` `## Project mode` for `frontendOnly` (project-shape signal)
    - **AND** scanning the PRD body for frontend keywords: 页面 / 组件 / 表单 / 弹窗 / 表格 / 样式 / 布局 / 交互 / UI / UX / page / component / form / modal / table / styling / layout / interaction
    - UI joins the swarm when (a) is `true` OR (b) matches. Both signals required `false` to skip UI.
 
-Solo records the swarm plan in `.peaks/<session-id>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
+Solo records the swarm plan in `.peaks/_runtime/<sessionId>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
 
 ```json
 {
@@ -624,42 +654,45 @@ 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=<session-id>, 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 <session-id> --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) |
 |---|---|---|
-| `ui` | `.peaks/<sid>/ui/design-draft.md`, `.peaks/<sid>/ui/requests/<rid>.md` | PRD body, project-scan, archetype |
-| `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 |
+| `ui` | `.peaks/_runtime/<sessionId>/ui/design-draft.md`, `.peaks/_runtime/<sessionId>/ui/requests/<rid>.md` | PRD body, project-scan, archetype |
+| `rd-planning` | `.peaks/_runtime/<sessionId>/rd/tech-doc.md` (feature/refactor) or `.peaks/_runtime/<sessionId>/rd/bug-analysis.md` (bugfix) | PRD body, project-scan, existing-system, codegraph |
+| `qa-test-cases` | `.peaks/_runtime/<sessionId>/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 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/_runtime/<sessionId>/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
@@ -681,7 +714,7 @@ Skipping the entire swarm (when `--type` is `config|docs|chore`) is not a degrad
 
 Before computing the swarm plan, Solo runs the keyword scan deterministically:
 
-1. Read `.peaks/<session-id>/prd/requests/<rid>.md` body.
+1. Read `.peaks/_runtime/<sessionId>/prd/requests/<rid>.md` body.
 2. Lowercase + strip markdown; check regex `\b(页面|组件|表单|弹窗|表格|样式|布局|交互|UI|UX|page|component|form|modal|table|styling|layout|interaction|frontend|前端)\b`.
 3. If match count ≥ 1 → `frontendKeywordHit=true`.
 4. If `frontendOnly` (from project-scan) is `true` and no keyword hit → UI joins anyway (frontend-only project, even non-visual changes may need visual sanity for regressions).
@@ -706,7 +739,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.
@@ -721,7 +754,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.
 
@@ -738,7 +771,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.
@@ -779,9 +812,9 @@ Before orchestrating an end-to-end code repository workflow, gather the project
 
 Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. In `full-auto` and `swarm` profiles, `--apply` runs automatically after `--dry-run` succeeds — these files live inside the target project, are required for downstream skill preflight, and producing them is part of finishing the workflow (Peaks-Cli Gate G enforces this). `assisted` and `strict` profiles pause for explicit user confirmation between dry-run and apply.
 
-**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/<id>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
+**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/<changeId>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
 
-**Legacy projects additionally** — when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}, the `CLAUDE.md` Conventions section MUST extract concrete naming, directory, service-layer, and hooks conventions from `.peaks/<id>/system/existing-system.md` and record them as hard constraints for new code. It must also list the `## Legacy constraints` from `project-scan.md` (class components, moment, enzyme, etc.) and instruct that new code in the same module preserves those patterns unless PRD explicitly authorizes modernization. A `CLAUDE.md` for a legacy project that contains only generic rule pointers without naming the actual conventions is a blocking violation — regenerate it.
+**Legacy projects additionally** — when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}, the `CLAUDE.md` Conventions section MUST extract concrete naming, directory, service-layer, and hooks conventions from `.peaks/<changeId>/system/existing-system.md` and record them as hard constraints for new code. It must also list the `## Legacy constraints` from `project-scan.md` (class components, moment, enzyme, etc.) and instruct that new code in the same module preserves those patterns unless PRD explicitly authorizes modernization. A `CLAUDE.md` for a legacy project that contains only generic rule pointers without naming the actual conventions is a blocking violation — regenerate it.
 
 Do not hand-write standards file mutations inside the skill.
 
@@ -808,7 +841,7 @@ It must enforce the shared refactor red lines:
 4. split broad refactors into minimal functional slices;
 5. require strict verifiable specs before each slice;
 6. require 100% acceptance for each slice;
-7. require code changes and sanitized intermediate artifacts to be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
+7. require code changes and sanitized intermediate artifacts to be traceable in local `.peaks/_runtime/<sessionId>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
 
 ## Peaks-Cli Quality-gate commands (CLI cheat sheet)
 
@@ -856,3 +889,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/<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-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/<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)
+
+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/browser-workflow.md

@@ -33,7 +33,7 @@ peaks mcp apply  --capability playwright-mcp.browser-validation --yes --json
 
 If a non-peaks-managed Playwright MCP entry already exists in `.claude/settings.json`, `apply` will refuse unless `--claim` is passed. Discuss with the user before claiming.
 
-After install, Claude Code's MCP runtime exposes the tools under the `mcp__playwright__*` namespace. Peaks skills reference these tools directly; they are not invoked through `peaks mcp call` because Claude Code is the host that calls them.
+After install, Claude Code's MCP runtime exposes the tools under the `mcp__playwright__*` namespace. Peaks skill bodies reference these tools via the `peaks mcp call` primitive (the skill body never bakes in the `mcp__playwright__` prefix; the prefix is owned by Claude Code's runtime, and `peaks mcp call` is the load-bearing fallback for sub-agents and non-Claude IDEs). The 4-step plan → apply → call pattern is the contract.
 
 ## Optional: install Chrome DevTools MCP for CDP inspection
 
@@ -44,38 +44,40 @@ peaks mcp plan   --capability chrome-devtools-mcp.browser-debug --json
 peaks mcp apply  --capability chrome-devtools-mcp.browser-debug --yes --json
 ```
 
-Tools become available under `mcp__chrome-devtools__*`. They fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design.
+Tools become available under `mcp__chrome-devtools__*` in the LLM runtime. Peaks skill bodies invoke them via `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool <name> --args-json '<args>' --json` (the skill body never bakes in the `mcp__chrome-devtools__` prefix). They fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design.
 
 ## Tool mapping for the "open a browser on demand" path (Playwright MCP)
 
-| Verb | Playwright MCP tool | Notes |
+| Verb | peaks mcp call invocation | Notes |
 |---|---|---|
-| Open visible browser and navigate | `mcp__playwright__browser_navigate` with `url` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
-| Confirm visible browser opened | `mcp__playwright__browser_take_screenshot` | Screenshot is the visible-browser confirmation. |
-| Read structured page (text + a11y) | `mcp__playwright__browser_snapshot` | Accessibility tree with element refs. |
-| Click / fill / press key | `mcp__playwright__browser_click`, `browser_fill`, `browser_press_key` | Drive the page after navigation. |
-| Inspect console errors | `mcp__playwright__browser_console_messages` | Pass `level` to filter (`error`, `warning`). |
-| Inspect network failures | `mcp__playwright__browser_network_requests` | Pass `filter` regex when the page has many requests. |
-| Resize viewport for responsive checks | `mcp__playwright__browser_resize` | |
-| Capture a full-page screenshot | `mcp__playwright__browser_take_screenshot` with `fullPage: true` | Sanitize before retention. |
-| Close the session cleanly | `mcp__playwright__browser_close` | End-of-task. |
+| Open visible browser and navigate | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
+| Confirm visible browser opened | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>"}' --json` | Screenshot is the visible-browser confirmation. |
+| Read structured page (text + a11y) | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_snapshot --args-json '{}' --json` | Accessibility tree with element refs. |
+| Click / fill / press key | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_click --args-json '<args>' --json` (and `browser_fill`, `browser_press_key`) | Drive the page after navigation. |
+| Inspect console errors | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_console_messages --args-json '{"level":"error"}' --json` | Pass `level` to filter (`error`, `warning`). |
+| Inspect network failures | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_network_requests --args-json '{"filter":"<regex>"}' --json` | Pass `filter` regex when the page has many requests. |
+| Resize viewport for responsive checks | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_resize --args-json '<args>' --json` | |
+| Capture a full-page screenshot | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>","fullPage":true}' --json` | Sanitize before retention. |
+| Close the session cleanly | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_close --args-json '{}' --json` | End-of-task. |
+| **Reference (runtime prefix, do not bake into skills)** | `mcp__playwright__<toolName>` | The Claude Code runtime prefix; the LLM resolves this from the registered server. The skill body uses `peaks mcp call` exclusively. |
 
 ## Tool mapping for the "connect to running Chrome" path (Chrome DevTools MCP, optional)
 
-| Verb | Chrome DevTools MCP tool | Notes |
+| Verb | peaks mcp call invocation | Notes |
 |---|---|---|
-| List pages in user's Chrome | `mcp__chrome-devtools__list_pages` | Requires Chrome already running with `--remote-debugging-port=9222`. |
-| Bring a tab to front | `mcp__chrome-devtools__select_page` with `bringToFront: true` | Useful when the user navigated themselves. |
-| Screenshot the visible viewport | `mcp__chrome-devtools__take_screenshot` | |
-| Read structured page | `mcp__chrome-devtools__take_snapshot` | |
-| Performance trace | `mcp__chrome-devtools__performance_start_trace` then `performance_stop_trace` | |
-| Lighthouse audit | `mcp__chrome-devtools__lighthouse_audit` with `mode: snapshot` | |
+| List pages in user's Chrome | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool list_pages --args-json '{}' --json` | Requires Chrome already running with `--remote-debugging-port=9222`. |
+| Bring a tab to front | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool select_page --args-json '{"bringToFront":true}' --json` | Useful when the user navigated themselves. |
+| Screenshot the visible viewport | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool take_screenshot --args-json '<args>' --json` | |
+| Read structured page | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool take_snapshot --args-json '{}' --json` | |
+| Performance trace | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool performance_start_trace --args-json '<args>' --json` then `performance_stop_trace` (each via `peaks mcp call`) | |
+| Lighthouse audit | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool lighthouse_audit --args-json '{"mode":"snapshot"}' --json` | |
+| **Reference (runtime prefix, do not bake into skills)** | `mcp__chrome-devtools__<toolName>` | The Claude Code runtime prefix; the LLM resolves this from the registered server. The skill body uses `peaks mcp call` exclusively. |
 
 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 calling `mcp__playwright__browser_navigate` (or any other navigation), verify:
+Before calling `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json` (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).

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.