peaks-cli 1.3.2 → 1.3.4

package/skills/peaks-qa/SKILL.md

@@ -3,6 +3,36 @@ name: peaks-qa
 description: QA and verification skill for Peaks. Use when a workflow needs unit-test coverage evidence, regression matrices, baseline reports, validation reports, acceptance checks, or refactor verification gates.
 ---
 
+## 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 QA
 
 Peaks-Cli QA proves that planned changes are protected and accepted.
@@ -11,29 +41,31 @@ Peaks-Cli QA proves that planned changes are protected and accepted.
 
 These two contracts are non-negotiable. The previous prose-only phrasing let the LLM skip the browser gate entirely when an auth wall appeared, and let screenshots land in the project root because the LLM forgot to pass `filename`. Both fail modes are blocking violations; the rules below are what a reviewer should hold the skill to.
 
-### Contract 1 — Screenshot path is mandatory and must land under .peaks/<sid>/qa/screenshots/
+### Contract 1 — Screenshot path is mandatory and must land under .peaks/_runtime/<sessionId>/qa/screenshots/
 
-Every `mcp__playwright__browser_take_screenshot` call **MUST** pass `filename` whose absolute path is **inside** `.peaks/<session-id>/qa/screenshots/`. Concrete form:
+Every Playwright screenshot tool call (via `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '<args>' --json`) **MUST** pass `filename` (in the args object) whose absolute path is **inside** `.peaks/_runtime/<sessionId>/qa/screenshots/`. Concrete form:
 
 ```bash
-mcp__playwright__browser_take_screenshot \
-  filename=".peaks/<sid>/qa/screenshots/<state-or-step>.png" \
-  fullPage=true
+peaks mcp call \
+  --capability playwright-mcp.browser-validation \
+  --tool browser_take_screenshot \
+  --args-json '{"filename":".peaks/_runtime/<session-id>/qa/screenshots/<state-or-step>.png","fullPage":true}' \
+  --json
 ```
 
-The default behaviour of Playwright MCP when `filename` is omitted or points outside that directory is to write a screenshot to the current working directory, which leaves `.png` files scattered at the project root. **This is a workflow violation.** If a screenshot does land outside `.peaks/<sid>/qa/screenshots/` for any reason (e.g. an upstream tool wrote there), QA MUST move it into that directory before declaring the test report complete; do not commit project-root `.png` files. Sanitise before retention: no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
+The default behaviour of Playwright MCP when `filename` is omitted or points outside that directory is to write a screenshot to the current working directory, which leaves `.png` files scattered at the project root. **This is a workflow violation.** If a screenshot does land outside `.peaks/_runtime/<session-id>/qa/screenshots/` for any reason (e.g. an upstream tool wrote there), QA MUST move it into that directory before declaring the test report complete; do not commit project-root `.png` files. Sanitise before retention: no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
 
 This rule is enforced by a Peaks-Cli preflight check inside this skill:
 
 ```bash
 # After every browser_take_screenshot batch and before declaring the test report complete:
-ls .peaks/<sid>/qa/screenshots/*.png 2>&1
+ls .peaks/_runtime/<session-id>/qa/screenshots/*.png 2>&1
 #   Expected: at least one .png file under the screenshots directory.
 #   "No such file" → BLOCKED. Either the screenshot was never taken, or
 #   it landed in the project root (move it before continuing).
 find . -maxdepth 1 -name '*.png' 2>&1
 #   Expected: empty. Any .png at the project root is a leak — move it
-#   to .peaks/<sid>/qa/screenshots/ before completing this skill.
+#   to .peaks/_runtime/<session-id>/qa/screenshots/ before completing this skill.
 ```
 
 ### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
@@ -60,10 +92,40 @@ 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=<session-id>, request-id=<rid>>" \
+  --request-id <rid> --session-id <session-id> --project <repo> --json
+
+peaks sub-agent dispatch qa-perf \
+  --prompt "<qa-perf contract, plus runtime args>" \
+  --request-id <rid> --session-id <session-id> --project <repo> --json
+
+peaks sub-agent dispatch qa-security \
+  --prompt "<qa-security contract, plus runtime args>" \
+  --request-id <rid> --session-id <session-id> --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/_runtime/<sessionId>/qa/test-reports/<rid>.md` (business findings)
+- `.peaks/_runtime/<sessionId>/qa/performance-findings.md` (perf findings)
+- `.peaks/_runtime/<sessionId>/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.
+- **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/_runtime/<sessionId>/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.
 - **Statusline install** — already done by Solo at session startup.
@@ -73,7 +135,7 @@ What the sub-agent **MUST** still do:
 0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out. The sub-agent reads it via `peaks request show <rid> --role qa --project <repo> --json` if it needs to.
 2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role rd`, `--role ui` if UI is in the swarm plan).
 3. Standards preflight (dry-run only).
-4. Write `.peaks/<session-id>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items.
+4. Write `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items.
 5. Return only a compact JSON envelope:
 
 ```json
@@ -81,7 +143,7 @@ What the sub-agent **MUST** still do:
   "role": "qa-test-cases",
   "rid": "<rid>",
   "status": "ok" | "blocked" | "skipped",
-  "artefacts": [".peaks/<sid>/qa/test-cases/<rid>.md"],
+  "artefacts": [".peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md"],
   "warnings": [],
   "blockedReason": null
 }
@@ -137,9 +199,9 @@ Every QA invocation — feature, bug, refactor, clarification — must write **t
 
 | # | File | Path | Reader | Content |
 |---|------|------|--------|---------|
-| 1 | Test cases | `.peaks/<session-id>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
-| 2 | Test report | `.peaks/<session-id>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
-| 3 | Request artifact | `.peaks/<session-id>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
+| 1 | Test cases | `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
+| 2 | Test report | `.peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
+| 3 | Request artifact | `.peaks/_runtime/<sessionId>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
 
 Concrete template and rules: `references/artifact-per-request.md`.
 
@@ -167,12 +229,12 @@ peaks codegraph affected --project <repo> <changed-files...> --json   # regressi
 peaks openspec validate <change-id> --project <repo> --json
 peaks openspec validate <change-id> --project <repo> --prefer-external --json   # optional
 
-# 4. generate test cases — MANDATORY, write to .peaks/<session-id>/qa/test-cases/<request-id>.md
+# 4. generate test cases — MANDATORY, write to .peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md
 #    categories: unit, integration, UI regression (frontend only)
 #
 #    Optimization (slice 004): peaks-rd's parallel fan-out now includes a 4th
 #    sub-agent (`qa-test-cases-writer`) that pre-drafts this file at the
-#    end of RD implementation. If `.peaks/<sid>/qa/test-cases/<rid>.md`
+#    end of RD implementation. If `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md`
 #    already exists when QA's main loop reaches this step, **QA does NOT
 #    re-draft it** — it just verifies the file is present and the
 #    per-criterion `ts` snippets are syntactically valid, then proceeds
@@ -183,8 +245,8 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 
 # 5. EXECUTE tests against the actual implementation — Peaks-Cli Gate A2
 #    Run the project test command. Record output. Tests on paper are worthless.
-#    Peaks-Cli Gate A3: Run security review → .peaks/<id>/qa/security-findings.md
-#    Peaks-Cli Gate A4: Run performance check → .peaks/<id>/qa/performance-findings.md
+#    Peaks-Cli Gate A3: Run security review → .peaks/<changeId>/qa/security-findings.md
+#    Peaks-Cli Gate A4: Run performance check → .peaks/<changeId>/qa/performance-findings.md
 #    CRITICAL: Peaks-Cli Gate A3 and Peaks-Cli Gate A4 are NON-NEGOTIABLE. You MUST run actual security
 #    and performance checks — not just write a checklist item. These gates exist
 #    because code review alone does not catch: hardcoded secrets, XSS vectors,
@@ -192,7 +254,7 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 #    If you skip A3 or A4, Peaks-Cli Gate C will block the verdict.
 #
 #    Before running A4, read the RD's perf-baseline at
-#    .peaks/<id>/rd/perf-baseline.md (if present) and use the
+#    .peaks/<changeId>/rd/perf-baseline.md (if present) and use the
 #    captured thresholds as the comparison baseline. The QA stage
 #    is still responsible for running the actual measurement
 #    (lighthouse / k6 / autocannon / project-local bench) and
@@ -204,7 +266,7 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 #    surface that absence in the QA test-report under a
 #    `## Performance baseline` section.
 
-# 6. write test-report — MANDATORY, write to .peaks/<session-id>/qa/test-reports/<request-id>.md
+# 6. write test-report — MANDATORY, write to .peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md
 #    MUST contain actual execution results (pass/fail counts, coverage %, findings).
 #    A template with placeholder text does not pass Peaks-Cli Gate B.
 
@@ -227,19 +289,23 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 #      and does NOT satisfy Peaks-Cli Gate D. Treating prod build as a fallback is a workflow violation.
 #   4. After browser validation completes, KILL the dev server. Do not leave it running.
 # Playwright MCP MUST simulate real user operations — not just take static screenshots.
-# The minimum interaction sequence for every frontend page/flow:
-#   mcp__playwright__browser_navigate         → URL (after allow-list), launches headed browser
-#   mcp__playwright__browser_snapshot         → accessibility tree per regression seed
-#   mcp__playwright__browser_click            → click buttons, tabs, links, modals
-#   mcp__playwright__browser_type             → type into form fields, search inputs
-#   mcp__playwright__browser_select_option    → select dropdown values
-#   mcp__playwright__browser_fill_form        → fill complete forms as a user would
-#   mcp__playwright__browser_take_screenshot  → capture each state AFTER interaction
-#   mcp__playwright__browser_console_messages + browser_network_requests → error feedback loop
-#   mcp__playwright__browser_wait_for         → wait for async data to render
-#   mcp__playwright__browser_close            → end the session cleanly
+# The minimum interaction sequence for every frontend page/flow uses the peaks mcp
+# plan/apply/call pattern (skill body NEVER bakes in the bare MCP tool prefix;
+# the prefix is owned by the LLM runtime). The four steps:
+#   1. Detect install:  peaks mcp list --json | grep playwright
+#   2. Plan:            peaks mcp plan --capability playwright-mcp.browser-validation --json
+#      (read envCheck.missing; if non-empty, refuse to apply and ask the user to set the env vars)
+#   3. Apply:           peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
+#   4. Call tools:      peaks mcp call --capability playwright-mcp.browser-validation \
+#                        --tool <toolName> --args-json '<argsObject>' --json
+#      Tool names (resolved by the LLM from the registered server, NOT hardcoded here):
+#      browser_navigate / browser_snapshot / browser_click / browser_type /
+#      browser_select_option / browser_fill_form / browser_take_screenshot /
+#      browser_console_messages / browser_network_requests / browser_wait_for / browser_close.
 # Static screenshots without user-interaction simulation do NOT pass this gate.
 # Block QA pass if Playwright MCP is unavailable.
+# For sub-agents dispatched via `peaks sub-agent dispatch` (where the LLM cannot
+# directly call MCP tools via the bare prefix), use `peaks mcp call` for every MCP operation.
 #
 # CLEANUP: After browser validation completes (all screenshots saved, console/network
 # evidence captured), QA MUST kill every process it started during verification.
@@ -284,8 +350,8 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` or `g
 
 **Peaks-Cli Gate A — After test-case generation:**
 ```bash
-ls .peaks/<id>/qa/test-cases/<rid>.md
-# Expected output: .peaks/<id>/qa/test-cases/<rid>.md
+ls .peaks/<changeId>/qa/test-cases/<rid>.md
+# Expected output: .peaks/<changeId>/qa/test-cases/<rid>.md
 # "No such file" → STOP, generate test cases first. Do not proceed to validation.
 ```
 
@@ -302,8 +368,8 @@ npx vitest run --reporter=verbose 2>&1 | tail -30
 **Peaks-Cli Gate A3 — Security test executed (NOT just a checklist item):**
 ```bash
 # Run security review against the changed surface. Record findings.
-ls .peaks/<id>/qa/security-findings.md 2>&1
-# Expected: .peaks/<id>/qa/security-findings.md
+ls .peaks/<changeId>/qa/security-findings.md 2>&1
+# Expected: .peaks/<changeId>/qa/security-findings.md
 # "No such file" → BLOCKED. Run security review against changed files,
 # record every finding with severity, then re-check.
 ```
@@ -311,30 +377,30 @@ ls .peaks/<id>/qa/security-findings.md 2>&1
 **Peaks-Cli Gate A4 — Performance test executed:**
 ```bash
 # Run available performance check against the changed surface. Record findings.
-ls .peaks/<id>/qa/performance-findings.md 2>&1
-# Expected: .peaks/<id>/qa/performance-findings.md
+ls .peaks/<changeId>/qa/performance-findings.md 2>&1
+# Expected: .peaks/<changeId>/qa/performance-findings.md
 # "No such file" → BLOCKED. Run performance check (build-size, Lighthouse,
 # bundle analysis, or project equivalent), record baseline vs. after, then re-check.
 ```
 
 **Peaks-Cli Gate B — After test-report write (MUST contain execution results, not just planned cases):**
 ```bash
-ls .peaks/<id>/qa/test-reports/<rid>.md
-# Expected output: .peaks/<id>/qa/test-reports/<rid>.md
+ls .peaks/<changeId>/qa/test-reports/<rid>.md
+# Expected output: .peaks/<changeId>/qa/test-reports/<rid>.md
 # "No such file" → STOP, write the test report first. Do not issue a verdict.
 # Additionally verify the report is not a placeholder:
-grep -c "pass\|fail\|blocked" .peaks/<id>/qa/test-reports/<rid>.md
+grep -c "pass\|fail\|blocked" .peaks/<changeId>/qa/test-reports/<rid>.md
 # Expected: non-zero count (report contains actual pass/fail/blocked results)
 # Zero → the report is empty/template-only. Tests were not executed.
 ```
 
 **Peaks-Cli Gate C — Before issuing verdict:**
 ```bash
-ls .peaks/<id>/qa/test-cases/<rid>.md \
-   .peaks/<id>/qa/test-reports/<rid>.md \
-   .peaks/<id>/qa/security-findings.md \
-   .peaks/<id>/qa/performance-findings.md \
-   .peaks/<id>/qa/requests/<rid>.md
+ls .peaks/<changeId>/qa/test-cases/<rid>.md \
+   .peaks/<changeId>/qa/test-reports/<rid>.md \
+   .peaks/<changeId>/qa/security-findings.md \
+   .peaks/<changeId>/qa/performance-findings.md \
+   .peaks/<changeId>/qa/requests/<rid>.md
 # All five must exist. Missing any → QA incomplete, verdict blocked.
 # NOTE: security-findings.md and performance-findings.md are NOT optional.
 # If you can't run a full security scan, run at minimum: grep for secrets,
@@ -345,7 +411,7 @@ ls .peaks/<id>/qa/test-cases/<rid>.md \
 
 **Peaks-Cli Gate E — Acceptance coverage (every PRD acceptance item has a linked test case):**
 ```bash
-peaks scan acceptance-coverage --rid <rid> --project <repo> --session-id <sid> --json
+peaks scan acceptance-coverage --rid <rid> --project <repo> --session-id <session-id> --json
 # Expected: ok=true. exit 0.
 # uncovered[] non-empty → BLOCKED. List of acceptance items without test cases is in the output.
 #   Add `- **Acceptance:** A<N>` lines to the matching test cases in qa/test-cases/<rid>.md, then re-run.
@@ -357,7 +423,7 @@ peaks scan acceptance-coverage --rid <rid> --project <repo> --session-id <sid> -
 
 **Peaks-Cli Gate F — QA artifact body has no unfilled placeholders:**
 ```bash
-peaks request lint <rid> --role qa --project <repo> --session-id <sid> --json
+peaks request lint <rid> --role qa --project <repo> --session-id <session-id> --json
 # Expected: ok=true. exit 0.
 # ok=false → BLOCKED. Lint output lists every <placeholder>, "- ..." stub, and TBD marker.
 #   Fill them in before issuing the verdict.
@@ -367,7 +433,7 @@ peaks request lint <rid> --role qa --project <repo> --session-id <sid> --json
 ```bash
 # Verify browser screenshots exist. Screenshots are the only acceptable evidence
 # that Playwright MCP actually launched and interacted with the running app.
-ls .peaks/<id>/qa/screenshots/*.png 2>&1
+ls .peaks/<changeId>/qa/screenshots/*.png 2>&1
 # Expected: one or more .png files
 # "No such file" → BLOCKED. Playwright MCP was not used or screenshots not saved.
 # Screenshots, logs, manual steps, or other tools must NOT substitute for this gate.
@@ -379,7 +445,7 @@ ls .peaks/<id>/qa/screenshots/*.png 2>&1
 ```
 ```bash
 # Verify console and network checks were actually performed
-grep -c "browser_console_messages\|browser_network_requests" .peaks/<id>/qa/test-reports/<rid>.md
+grep -c "browser_console_messages\|browser_network_requests" .peaks/<changeId>/qa/test-reports/<rid>.md
 # Expected: non-zero count (means console/network were checked)
 # Zero → BLOCKED. Browser error feedback loop was not executed.
 ```
@@ -417,7 +483,7 @@ Before QA passes or returns work to RD, it must independently recheck the implem
 
 ## Mandatory test-case generation
 
-QA must generate test cases, not merely inspect existing ones. Every QA invocation that validates code changes must produce a test-case artifact at `.peaks/<session-id>/qa/test-cases/<request-id>.md`.
+QA must generate test cases, not merely inspect existing ones. Every QA invocation that validates code changes must produce a test-case artifact at `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md`.
 
 **Minimum test-case categories:**
 
@@ -445,7 +511,7 @@ QA must generate test cases, not merely inspect existing ones. Every QA invocati
 
 ## Mandatory test-report output
 
-Every QA invocation must produce a test-report artifact at `.peaks/<session-id>/qa/test-reports/<request-id>.md`. This is separate from both the test-case file and the request artifact — do not merge.
+Every QA invocation must produce a test-report artifact at `.peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md`. This is separate from both the test-case file and the request artifact — do not merge.
 
 **Minimum test-report sections:**
 
@@ -466,7 +532,13 @@ QA cannot pass a change until the report contains evidence for every applicable
 1. **Test-report** — enforced by Peaks-Cli Gate B.
 2. **Unit tests** — run the project test command or a focused test command that covers new/changed code. For legacy projects below the target coverage, require coverage for the new or changed code rather than failing on pre-existing uncovered code.
 3. **API validation** — when the change touches API contracts, data loading, request handling, auth, or integrations, exercise the relevant API path and record request/response evidence or a justified local substitute.
-4. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use Playwright MCP for real browser end-to-end validation. This means **simulating real user operations**: clicking buttons, filling forms, selecting dropdowns, navigating between pages, waiting for async data to render, and verifying each resulting state. Static screenshots without interaction are insufficient. Confirm Playwright MCP is installed via `peaks mcp list --json`; install through `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if missing. Use `mcp__playwright__browser_navigate` (launches headed browser), `mcp__playwright__browser_click` (simulate clicks on tabs/buttons/links), `mcp__playwright__browser_type` (type into inputs), `mcp__playwright__browser_select_option` (select dropdowns), `mcp__playwright__browser_fill_form` (fill complete forms), `mcp__playwright__browser_wait_for` (wait for async rendering), and `mcp__playwright__browser_take_screenshot` (capture state after each interaction). If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture sanitized interaction sequences, sanitized screenshots per state, sanitized console (`browser_console_messages`) and network (`browser_network_requests`) failures. Close with `mcp__playwright__browser_close` when done. (Chrome DevTools MCP is an optional secondary surface for CDP inspection of an already-running Chrome on `:9222`; it does NOT launch a browser and cannot simulate user interaction.)
+4. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use Playwright MCP for real browser end-to-end validation. This means **simulating real user operations**: clicking buttons, filling forms, selecting dropdowns, navigating between pages, waiting for async data to render, and verifying each resulting state. Static screenshots without interaction are insufficient. Confirm Playwright MCP is installed via `peaks mcp list --json`; install through `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if missing. Route every browser interaction through the canonical `peaks mcp call` envelope:
+
+   ```
+   peaks mcp call --capability playwright-mcp.browser-validation --tool <toolName> --args-json '<argsObject>' --json
+   ```
+
+   The Playwright tool names that drive validation are: `browser_navigate` (launches headed browser), `browser_click` (simulate clicks on tabs/buttons/links), `browser_type` (type into inputs), `browser_select_option` (select dropdowns), `browser_fill_form` (fill complete forms), `browser_wait_for` (wait for async rendering), `browser_take_screenshot` (capture state after each interaction), `browser_close` (close the browser when done), `browser_console_messages` (read console failures), and `browser_network_requests` (read network failures). The bare server-and-tool MCP prefix is owned by the LLM runtime, not by the skill body — never bake the prefix into this SKILL.md or any artifact QA emits. If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture sanitized interaction sequences, sanitized screenshots per state, sanitized console (`browser_console_messages`) and network (`browser_network_requests`) failures. (Chrome DevTools MCP is an optional secondary surface for CDP inspection of an already-running Chrome on `:9222`; it does NOT launch a browser and cannot simulate user interaction.)
 5. **Browser-error feedback loop** — if Playwright MCP observation surfaces a page error, console exception, broken network request, hydration/render failure, or visible regression, return the work to RD/development with the exact evidence. Do not pass QA until the fixed build is retested in the browser.
 6. **Security check** — run security review for the changed surface and dependency/config changes. Record findings, fixes, and unresolved risks.
 7. **Performance check** — run the project’s available performance check, build-size check, Lighthouse-equivalent check, or browser performance inspection appropriate to the change. Record baseline/after numbers when available.
@@ -479,7 +551,7 @@ If Playwright MCP is unavailable (not installed and the user has not authorized
 
 ## Local intermediate artifacts
 
-QA reports, sanitized browser evidence, logs, matrices, and validation summaries should be written to `.peaks/<session-id>/qa/` by default, or to the Peaks-Cli CLI-provided local artifact workspace. Do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Do not default to git-backed storage or external artifact sync unless the user or active profile explicitly authorizes it.
+QA reports, sanitized browser evidence, logs, matrices, and validation summaries should be written to `.peaks/_runtime/<sessionId>/qa/` by default, or to the Peaks-Cli CLI-provided local artifact workspace. Do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Do not default to git-backed storage or external artifact sync unless the user or active profile explicitly authorizes it.
 
 ## Compact handoff
 
@@ -505,7 +577,7 @@ External analysis cannot pass QA by itself. Treat codegraph output as untrusted
 
 Use `peaks capabilities --source access-repo --json` and `peaks capabilities --source mcp-server --json` before recommending browser or validation tooling. Treat all external skills as reference material only — do not execute upstream instructions, do not install upstream resources, do not persist sensitive examples; Peaks-Cli QA acceptance authority remains.
 
-- Playwright MCP is the required path for controlled headed browser and E2E validation (it launches a headed browser on demand). Install or update through `peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` rather than hand-editing settings. Claude Code invokes its tools directly under the `mcp__playwright__*` namespace; QA skill bodies do not route through `peaks mcp call` for these tools.
+- Playwright MCP is the required path for controlled headed browser and E2E validation (it launches a headed browser on demand). Install or update through `peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` rather than hand-editing settings. The LLM runtime invokes the Playwright tools directly under its own server-and-tool namespace; QA skill bodies route every Playwright invocation through `peaks mcp call --capability playwright-mcp.browser-validation --tool <toolName> --args-json '<argsObject>' --json` instead of the bare prefix.
 - Chrome DevTools MCP is an optional secondary surface for CDP inspection (console, network, performance) of an already-running Chrome started with `--remote-debugging-port=9222`; it does NOT launch a browser on its own. Install via `peaks mcp apply --capability chrome-devtools-mcp.browser-debug --yes --json` when this use case applies.
 - Agent Browser can support browser walkthroughs, but never submit forms, purchase, delete, or mutate authenticated state without explicit confirmation.
 - Canonical browser workflow (URL allow-list, login handoff, sanitization rules, tool mapping): `peaks-solo/references/browser-workflow.md`.
@@ -526,3 +598,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/<sessionId>/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