peaks-loop 3.1.2 → 4.0.0-beta.10

package/skills/peaks-solo/references/step-0-8-gate.md

@@ -1,60 +0,0 @@
-# Peaks-Loop Solo — Step 0.8 (v3.1.1 + v3.1.2) Gate Deep-Dive
-
-> Read alongside `SKILL.md` Step 0.8. The SKILL.md header is the LOCKED CONTRACT; this file is the mechanics.
-
-## Recorder contract (`peaks solo detect-job`)
-
-The CLI does NOT judge whether the request is Job-shaped — that is the LLM's job. Keyword regexes are wrong here (too brittle, miss natural-language variants, shift the LLM's semantic understanding into code). The CLI is a **recorder and gate**: the LLM makes the judgement, writes it via `peaks solo detect-job`, and downstream steps refuse to proceed until the decision file exists.
-
-### LLM judgement criteria (read once, then call the recorder)
-
-- N parallel targets (`app/components/*`, `app/modules/*`, `for each subdir`, "以目录为维度", "把剩下的也跑了").
-- Completion phrase implying batch continuation (`until all done`, "继续执行下个 slice", "全部添加完", "all of them").
-- Cost / length disavowal (`不用考虑费用`, "don't worry about cost", "一直跑").
-- Explicit slice count (`25 slices`, "切分成 N 段", "拆成 N 块").
-
-### Action sequence
-
-1. LLM reads the user prompt and applies judgement → `isJob: boolean + rationale + suggestedJobId + suggestedStrategy + confidence`.
-2. LLM calls `peaks solo detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> --suggested-strategy <single|rotating> --confidence <high|medium|low> [--force]`.
-3. CLI records to `.peaks/_runtime/<sessionId>/job-shape.json`.
-4. If `isJob: true` → `peaks job init --job-id <jid> --slice-list <...> --main-loop-strategy <strategy> --rotate-every 3` (BEFORE Step 1).
-5. Downstream steps (Step 1, Step 0.81, etc.) call `read-job-shape` to refuse if missing.
-
-### Hard rule (v3.1.1 red-line #10)
-
-LLM MUST NOT skip `peaks solo detect-job` even when the trigger is obvious from context. If the next step's `read-job-shape` throws `JOB_SHAPE_NOT_DECIDED`, Solo MUST record a decision before proceeding. Keyword-based "I already know it's a Job" is not a substitute.
-
-## v3.1.2 mechanical gates
-
-The recorder-only design was bypassed twice under load; the gate must be un-bypassable.
-
-### 1. PreToolUse hook — `peaks solo gate-step-08`
-
-`peaks workspace init` installs the `Bash` matcher `peaks solo gate-step-08 --project .` in `.claude/settings.local.json` (alongside the existing Write|Edit|MultiEdit matcher). The hook runs before every Bash call:
-
-| Condition | Exit | Behaviour |
-|---|---|---|
-| `job-shape.json` exists | 0 (allow) | allow + emit decision; if `progress.json` exists, add `Next: slice #N+1 of M (<currentSlice>)` |
-| `job-shape.json` missing AND prompt matches the fail-closed backup regex | 2 (BLOCKED) | LLM must call `peaks solo detect-job` before retrying |
-| `job-shape.json` missing AND no regex match | 0 (allow) | allow, no Job trigger |
-
-### 2. Size-fear ban — `peaks solo emit-handoff`
-
-Refuses to emit a final handoff while `remaining > 0` under Job mode. Pass `--force-under-job` only with explicit user approval.
-
-### 3. Forced auto-compact — `--enforce-job-mode`
-
-`peaks solo context-now --enforce-job-mode` (auto-enabled when `job-shape.json` says `isJob=true`) returns `action: 'auto-compact-now'` at ≥ 0.85; Solo MUST call `peaks session auto-compact --execute` without confirmation.
-
-### 4. On-disk slice progress — `progress.json`
-
-`peaks job checkpoint --state done` writes `progress.json`. `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader; `peaks solo gate-step-08` also surfaces it on every Bash call so the LLM cannot "wake up cold".
-
-## Backup regex rationale
-
-The fail-closed backup regex (mentioned above) exists so the gate has defense in depth: even if the recorder's downstream enforcement is bypassed, the hook catches obvious Job-shaped prompts. The regex is intentionally narrow — it MUST miss benign prompts and MUST hit obvious batches — so the LLM-side judgement remains primary.
-
-## Hook wiring
-
-`peaks workspace init` writes both matchers (Bash + Write|Edit|MultiEdit) atomically; if either fails the whole init fails. `peaks workspace init --remove-hooks` reverses both. The Bash matcher is required for Step 0.8; the Write|Edit|MultiEdit matcher pre-existed (Step 0 [Fact-Forcing Gate]).

package/skills/peaks-solo/references/sub-agent-dispatch.md

@@ -1,334 +0,0 @@
-# sub-agent-dispatch.md — peaks sub-agent dispatch orchestrator contract
-
-> **Slice**: 2026-06-07-sub-agent-dispatch-decouple (G3 + G6)
-> **Audience**: SKILL.md authors and LLM readers of peaks-solo / peaks-rd / peaks-qa
-> **Status**: stable
-
-This reference is the orchestrator-side contract for sub-agent dispatch.
-It explains why the peaks family uses `peaks sub-agent dispatch <role>` as
-the canonical primitive, how the dispatch envelope flows back to the LLM,
-and how the new G6 heartbeat channel keeps the user informed during the
-batch-sync wait. Read this before writing or extending any peaks-*
-SKILL.md that dispatches sub-agents.
-
-**LLM anti-collision note:** Do NOT guess flag names. The ONLY prompt flag is `--prompt <text>`. If unsure, run `peaks sub-agent dispatch <role> --help` first (see canonical signature below).
-
-## Why a CLI primitive (skill-first / CLI-auxiliary)
-
-The peaks skill family is the **product**. The CLI is a thin atomic
-the skills compose. For sub-agent dispatch the relationship is:
-
-| Surface | Who owns | What it does | Who calls it |
-|---|---|---|---|
-| SKILL.md (主面) | peaks-solo, peaks-rd, peaks-qa | Tells the LLM when and why to dispatch a sub-agent; what prompt to pass; what artifacts to expect back | LLM (during normal Solo / RD / QA flow) |
-| CLI (副 / 原子) | `peaks sub-agent dispatch` | Validates the role, looks up the current IDE's `subAgentDispatcher`, returns a per-IDE tool-call descriptor + writes a dispatch record | LLM (read from the SKILL.md) |
-| Dispatcher 抽象 (per-IDE) | `src/services/dispatch/sub-agent-dispatcher.ts` | Encapsulates the IDE-private tool name (claude-code: `Task`, trae: UNVERIFIED placeholder) and arg shape | CLI (called by the CLI) |
-
-This is the **inverse** of the prior shape: SKILL.md used to hardcode
-`Task(subagent_type="general-purpose", ...)`, which made peaks-loop
-depend on Claude Code's specific tool name. Adding a new IDE meant
-editing every SKILL.md that mentioned sub-agents. With the new shape,
-the only per-IDE thing in the dispatch chain is the dispatcher — SKILL.md
-stays IDE-agnostic.
-
-> **Red line**: do not invoke `peaks sub-agent dispatch` from your own
-> shell. The CLI is a primitive the LLM composes. Users do not need it.
-
-## Dispatch contract
-
-**Command**:
-
-```
-peaks sub-agent dispatch <role> --prompt <text> [--request-id <rid>] [--session-id <sid>] [--project <repo>] [--batch-id <uuid>] --json
-```
-
-**Envelope** (AC-8) — **2.1.0** (slice 2026-06-23-audit-4th #E1):
-
-> **Audit-3rd #4 + audit-4th #E1**: the `data.prompt` field was
-> deliberately removed from the CLI envelope. Prompts can carry user
-> content (sometimes test credentials / internal URLs) that has no
-> business landing in shell history, log aggregators, or tmux
-> scrollback. The dispatch record on disk (gitignored under
-> `.peaks/_sub_agents/`) keeps the prompt for the sub-agent to read;
-> CLI stdout stays metadata-only. Surface `originalPromptSize` +
-> `promptSize` so the LLM-side runner can still reason about headroom
-> without seeing the content. The prompt content the LLM should pass
-> through lives in `data.toolCall.args.prompt` (the IDE-arg the
-> consumer passes to the tool), NOT in the outer envelope.
-
-```json
-{
-  "ok": true,
-  "command": "sub-agent.dispatch",
-  "data": {
-    "envelopeVersion": "2.1.0",
-    "role": "rd",
-    "ide": "claude-code",
-    "originalPromptSize": 4321,
-    "promptSize": 4321,
-    "toolCall": {
-      "name": "Task",
-      "args": {
-        "subagent_type": "general-purpose",
-        "description": "rd for rid=002-2026-06-07-...",
-        "prompt": "<complete prompt the LLM should pass through to the tool>"
-      }
-    },
-    "dispatchRecordPath": ".peaks/_sub_agents/2026-06-06-session-5b1095/dispatch-002-2026-06-07-...-...json",
-    "batchId": "<uuid>",
-    "dispatchedInBatch": 3,
-    "headroomCompressed": false,
-    "headroomResult": null,
-    "forcedAt": null,
-    "contextImpact": {
-      "promptBytes": 4321,
-      "artifactBytes": 0,
-      "totalBytes": 4321
-    },
-    "artifactMetas": []
-  },
-  "warnings": [],
-  "nextActions": [
-    "Tool call is dry-run; LLM must execute the tool to actually dispatch the sub-agent.",
-    "After dispatching, the sub-agent should call `peaks sub-agent heartbeat --record <dispatchRecordPath>` periodically."
-  ]
-}
-```
-
-**LLM side**: read `data.toolCall` (the `{name, args}` descriptor), look
-up the tool by `name` in the current environment, and invoke it with
-`args`. The CLI does not spawn anything. The IDE (Claude Code, Trae,
-etc.) is the one that actually runs the sub-agent.
-
-> **Slice 2026-06-23-audit-4th #F2 callout**: the prompt content the
-> LLM should pass through lives in `data.toolCall.args.prompt` (the
-> IDE-arg the consumer passes to the tool), NOT in the outer envelope
-> (`data.prompt` was removed in slice 2026-06-23-audit-3rd #4; see the
-> `envelopeVersion: '2.1.0'` marker and the `envelope-contract.md`
-> reference for the full contract). A reader skimming the example
-> should not conflate the two fields.
-
-**Side effect**: the CLI writes a dispatch record to
-`.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json` (R-2 path-guarded).
-The record starts with `heartbeats: []`, `lastBeatAt: null`, `status: 'queued'`
-and is updated by the heartbeat flow (§G6 below).
-
-## Role model
-
-`SubAgentRole` is a free-form string. The CLI **does not** enforce a
-hard whitelist. Recommended roles:
-
-- Top-level: `rd` | `qa` | `ui` | `txt` | `general-purpose`
-- QA sub-roles: `qa-business` | `qa-perf` | `qa-security`
-- Business sub-divisions: `qa-business-api` | `qa-business-frontend` |
-  `qa-business-regression` | ... (≤ 2 levels deep per RL-4)
-- Promotable Worker (architecture预留, slice #009 不实际提升): `prd-business` |
-  `prd-technical` | `prd-ux` | `ui-visual` | `ui-flow` | `ui-component`
-
-The only hard validation is: non-empty, ≤ 256 chars, no control
-characters. Any other string is a convention, not a contract.
-
-## Per-IDE dispatchers (G1)
-
-| IDE | Tool name | Args shape | Status |
-|---|---|---|---|
-| `claude-code` | `Task` | `{subagent_type: "general-purpose", description, prompt}` | verified |
-| `trae` | `Task` | byte-identical to claude-code by design | UNVERIFIED — pending real Trae dogfood |
-| `null` (no IDE detected) | — | throws `IDE_NOT_SUPPORTED` | fallback |
-
-Adding a new IDE means:
-
-1. Add a new adapter to `src/services/ide/adapters/<id>-adapter.ts`.
-2. Fill in `subAgentDispatcher: <yourDispatcher>` (implements
-   `SubAgentDispatcher`).
-3. Register the adapter in `ide-registry.ts`.
-
-SKILL.md and existing dispatcher implementations are untouched.
-
-## G6 — heartbeat + dynamic progress (RL-13..RL-16)
-
-Sub-agents run for 30 s to 2 min. During that wait, the LLM platform
-provides no progress signal to the Dispatcher. Without a heartbeat
-channel, the user sees a frozen terminal and reasonably assumes the
-system is dead. G6 is the rule that says: **no**.
-
-### The three-layer contract
-
-| Layer | Who | What | Cadence |
-|---|---|---|---|
-| **Sub-agent writes** | The sub-agent itself | Calls `peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note "<text>"` to append a heartbeat | 30 s default; SKILL.md can override via `heartbeatIntervalSec: 15` |
-| **Dispatcher reads** | peaks-solo main loop, during the batch-sync wait | In-process async poller (`BatchHeartbeatPoller`) reads `heartbeats[]` + `lastBeatAt` from each record, emits a single-line status per G6.5 | 10 s (offset from 30 s to avoid jitter) |
-| **User / CLI reads** | Anyone, anytime | `peaks sub-agent list --session-id <sid> --json` (G5 RL-10, future slice) | manual |
-
-### Sub-agent prompt template (heartbeat-aware + MCP-decoupled)
-
-Every sub-agent prompt dispatched via `peaks sub-agent dispatch` should
-include the heartbeat instruction so the LLM knows when and how to
-report progress. The recommended paragraph (auto-generated by the CLI
-and the SKILL.md heart of each Dispatcher) is:
-
-```
-While running, call `peaks sub-agent heartbeat --record <dispatchRecordPath>
---status <state> --progress <pct> --note "<text>"` at least every 30 seconds
-(the Dispatcher expects 30s cadence). On completion call
-`--status done --progress 100 --note "completed"`. On failure,
-`--status failed`. Do not skip heartbeats; the parent Dispatcher uses them
-to keep the user informed during the wait.
-```
-
-**Slice #016 retirement (G3 prompt template — MCP subsystem removed)**:
-The MCP-decouple paragraph from slice #007-007 no longer applies.
-peaks-loop no longer manages MCP install or invocation. Sub-agents
-check their own tool list for `mcp__<server>__*` entries and invoke
-the tool by name directly. The only prompt-template addition that
-remains is the tool-list self-check:
-
-```
-This task may need an MCP server (playwright, chrome-devtools, figma,
-or context7). Check your tool list for any `mcp__<server>__*` entry.
-If present, invoke the tool by name directly. If absent, tell the user
-the install command for their IDE (Claude Code:
-`claude mcp add <server> -- <npx-command>`) and stop the sub-task until
-the user installs the MCP. Do NOT hand-edit `.claude/settings.json` or
-auto-install on the user's behalf.
-```
-
-The tool-list self-check is required for any sub-agent that needs a
-browser, design, or docs-lookup capability. The CLI auto-generates it
-for `role in (rd, qa, ui, txt)`.
-when the active IDE is not `claude-code`; for `role = general-purpose`
-or unknown roles, the caller (the SKILL.md heart of the Dispatcher) must
-add it explicitly.
-
-`heartbeatIntervalSec` is overridable per SKILL.md (5..600). Default 30.
-
-### Status line shape (G6.5)
-
-Single line, 80-120 chars:
-
-```
-[peaks-solo] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
-[peaks-solo] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
-...
-[peaks-solo] swarm 3/3 done
-```
-
-If a sub-agent has not written a heartbeat in 5 minutes, the poller
-appends `⚠ stale` to that sub-agent's segment and marks
-`status: 'stale'` on the record. **It does not cancel, kill, or send
-SIGTERM** (RL-15). Stale is a user-visible warning, not a failure.
-The user decides.
-
-### Truncation (RL-16)
-
-`heartbeats[]` is append-only for audit, but capped at 100 entries.
-Past 100, the oldest are dropped and `truncated: true` is set. The
-record JSON can otherwise balloon to MB on long-running sub-agents.
-100 is the LLM-friendly limit — stale heartbeats are not informative
-once the poller has read them.
-
-### Acceptance criteria covered
-
-- AC-33 `peaks sub-agent heartbeat` CLI primitive (implemented)
-- AC-34 Dispatch record schema upgrade (`heartbeats[]` + `lastBeatAt` + `status` aggregate, backward-compat defaults)
-- AC-35 peaks-solo main loop batch-sync poller (10 s cadence, 5 min stale)
-- AC-36 SKILL.md fan-out sections include heartbeat instruction
-- AC-37 G6 E2E dogfood (3 heartbeats, 101 → truncated, stale simulation)
-
-## Acceptance criteria (overall G1-G6)
-
-- AC-1..AC-5: dispatcher interface + 3 adapter impls (`claudeCodeSubAgentDispatcher`, `traeSubAgentDispatcher`, `nullSubAgentDispatcher`)
-- AC-6: dispatcher unit tests
-- AC-7..AC-9: dispatch CLI signature + envelope + steps
-- AC-10: dispatch CLI unit tests
-- AC-11 / AC-11b / AC-11c: E2E dogfood on the live repo
-- AC-12: `peaks --help` byte-level delta is `+1` line (`sub-agent <cmd>`)
-- AC-13..AC-19: SKILL.md fan-out rewrites (peaks-solo 5 spots, peaks-rd 2, peaks-qa 3-way, peaks-ui 1; this reference is the canonical contract)
-- AC-22..AC-24: R-2 path guard, prompt size limit, atomic write
-- AC-25..AC-32: G5 resource lifecycle (RL-1 batch counter, dispatch record schema, reducer dispose, slice archive, cancel dispose)
-- AC-33..AC-37: G6 heartbeat CLI, schema, poller, status line, E2E
-
-## How to apply
-
-When writing a SKILL.md that fans out sub-agents:
-
-1. Use `peaks sub-agent dispatch <role>` (never `Task(...)`).
-2. Issue all dispatches in a single message; the LLM will fire all
-   returned toolCalls in parallel.
-3. Pass `--request-id` and `--session-id` (or omit and let the CLI
-   resolve the active session).
-4. The sub-agent prompt **must** include the heartbeat instruction
-   (30 s cadence; override via `heartbeatIntervalSec` if needed).
-5. After the fan-out returns, the Dispatcher reducer reads the
-   dispatch record + the artifacts the sub-agents wrote, marks
-   `disposed: true` on each record, and advances the state machine.
-6. The poller handles the 5-min stale case as a warning, never as a
-   failure. The user is the one who decides to cancel.
-
-## Cross-reference
-
-- PRD #009 G1-G6 (this slice's source of truth)
-- RD request #009 in-scope files (implementation contract)
-- `.peaks/memory/sub-agent-resource-lifecycle-red-line.md` (G5 red line)
-- `.peaks/memory/sub-agent-heartbeat-progress-red-line.md` (G6 red line)
-- `skills/peaks-solo/references/swarm-dispatch-contract.md` (predecessor contract)
-- `skills/peaks-qa/references/qa-fanout-contract.md` (QA-specific fan-out)
-
----
-
-### Sub-agent mechanism (IDE-agnostic dispatch, NOT Skill tool)
-
-> Body of `### Sub-agent mechanism`. **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 dispatch call looks like:
-
-```
-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/_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 `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-Loop Gate B), and only then advances to RD implementation.
-
-**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/_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.
-  - **Reinforced (2026-06-28 incident):** an RD sub-agent silently auto-committed its own diff during a fix-callerid-leak dispatch (commit `bff4dff`). The orchestrator caught the unauthorized commit on the next turn but the user had to manually re-approve. **Every dispatch prompt MUST copy the verbatim block below into its `--prompt` argument** so the sub-agent sees the rule with full weight:
-
-    ```
-    ## Commit / push policy (verbatim, mandatory)
-    - Do NOT run `git commit`, `git push`, `git tag`, `git checkout -b`, or any
-      state-mutating git command. Leave the diff on disk and return the
-      diff summary in your final message. The orchestrator (Solo) owns the
-      commit / push decision; it will run `git status` and `git diff` after
-      your return and decide whether to commit.
-    - If you believe a commit is urgent (e.g. emergency hotfix), return
-      `verdict: blocked-by-orchestrator-policy` and explain. Do NOT commit
-      yourself even in emergencies.
-    ```
-- **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 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
-```

package/skills/peaks-solo/references/swarm-dispatch-contract.md

@@ -1,230 +0,0 @@
-# Swarm dispatch contract
-
-> Reference for `peaks-solo` Swarm phase and the role sub-agents (`peaks-ui` / `peaks-rd` planning / `peaks-qa` test-cases). Defines the **mechanism** of fan-out: how Solo launches sub-agents, what the sub-agent prompt must contain, what the sub-agent must return, and how Solo reduces the result.
-
-## Peaks-Loop Swarm parallel phase (sub-agent fan-out, default)
-
-> **Slice 5 (2026-06-23) + slice 2026-06-23-audit-4th #F3:** the
-> previous "conditional swarm" framing is replaced by the **default
-> fan-out rule** in `skills/peaks-solo/SKILL.md` §"Peaks-Loop Default
-> sub-agent fan-out". When the slice DAG has ≥ 2 leaves at the same
-> topological level, dispatch goes through
-> `peaks sub-agent dispatch --from-dag` (NOT one-at-a-time). The
-> gate logic below remains the canonical source for: PRD state,
-> request type, frontend touch, mode-driven shape, and degradation
-> rules. As of 2.8.4 the `'serial'` opt-out was removed by user
-> direction — single-sub-agent dispatch is no longer permitted when
-> ≥ 2 leaves exist at one topological level (see
-> `references/fanout-mandatory.md`).
-
-The Swarm phase is the **default** for any DAG with ≥ 2 leaves at
-the same topological level. Solo derives the fan-out set from the
-DAG topology — not from a default of "always launch three", and
-not from a strict conditional check. The swarm gate (PRD state +
-request type + frontend touch), mode-driven fan-out shape, and
-degradation rules live in the references file.
-
-## 1. Why this exists
-
-The previous "Swarm" used `Skill(skill="peaks-rd")` calls. That is **single-stack and blocking** — there is no concurrency. Three sequential `Skill` calls run in order on the same main loop, not in parallel. The "parallel Agent calls" wording in the old SKILL.md was a v1.x illusion.
-
-This contract (slice #009) replaces the IDE-private sub-agent literal with the IDE-agnostic primitive `peaks sub-agent dispatch <role>`. The CLI returns a JSON `data.toolCall` descriptor; the LLM executes that tool in its own environment. SKILL.md is now free of IDE-private tool names and the same prompt works on every registered IDE. Real concurrent fan-out is achieved by Solo launching N dispatch calls in a single message and the platform scheduling the returned toolCalls concurrently.
-
-```
-You are a sub-agent invoked by peaks-solo. You are NOT the main Claude session.
-Your job: execute ONE role from the peaks skill family and write its artefact(s).
-Return a compact JSON envelope — do not write prose.
-
-## Hard prohibitions
-- Do NOT call Skill(skill="..."). You are the role.
-- Do NOT call `peaks skill presence:set` — the main loop owns .peaks/.active-skill.json.
-  If you need to record state, write to .peaks/_runtime/<session-id>/system/sub-agent-<role>.json.
-- Do NOT commit, push, install hooks, or apply settings.json mutations.
-- Do NOT ask the user interactive questions. If you need clarification, return
-  {"status":"blocked","blockedReason":"<text>"} and let the main loop handle it.
-
-## Runtime arguments (provided by Solo)
-- project: <repo>            (git repo root, NOT a sub-package)
-- session-id: <sid>          (from .peaks/.active-skill.json or .peaks/.session.json)
-- request-id: <rid>          (PRD id)
-- type: <type>               (feature | bugfix | refactor | config | docs | chore)
-- mode: <mode>               (full-auto | swarm | assisted | strict)
-- project-scan-path: <path>  (read this for component library / CSS / build tool)
-- existing-system-path: <path>  (legacy projects only)
-- frontendOnly: <bool>       (from project-scan)
-- frontendKeywordHit: <bool> (Solo's PRD scan result)
-```
-
-### 3.2 peaks-ui sub-agent prompt
-
-Append after the common header:
-
-```
-## Role: UI design direction
-You are running peaks-ui. Produce design direction, not code. RD will implement.
-
-Steps:
-1. peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
-2. peaks request show <rid> --role prd --project <repo> --json
-3. Read <project-scan-path> for component library / CSS framework.
-4. Run the prototype fidelity gate: Figma file? PRD visuals? Headed browser?
-5. Write TWO artefacts:
-   - .peaks/_runtime/<sid>/ui/design-draft.md
-   - .peaks/_runtime/<sid>/ui/requests/<rid>.md
-6. Return:
-   {
-     "role": "ui",
-     "rid": "<rid>",
-     "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/_runtime/<sid>/ui/design-draft.md", ".peaks/_runtime/<sid>/ui/requests/<rid>.md"],
-     "warnings": [],
-     "blockedReason": null
-   }
-
-If you determine the request is non-visual (no UI surface, no design impact),
-return {"status":"skipped","reason":"non-frontend-request"} so Solo can record
-the misfire in sc/swarm-plan.json.
-```
-
-### 3.3 peaks-rd (planning) sub-agent prompt
-
-```
-## Role: RD planning
-You are running peaks-rd's planning step. Produce the planning artefact, not code.
-Code is written in a later sub-agent or inline run.
-
-Steps:
-1. peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
-2. peaks request show <rid> --role prd --project <repo> --json
-3. peaks request show <rid> --role ui  --project <repo> --json  (if ui in plan)
-4. Read <project-scan-path>. If absent and Solo did not pre-create it, create it
-   by running `peaks scan archetype --project <repo> --json` and copying the JSON
-   into rd/project-scan.md.
-5. Read <existing-system-path> if archetype is legacy-*.
-6. Write the type-appropriate planning artefact:
-   - feature | refactor  → .peaks/_runtime/<sid>/rd/tech-doc.md
-   - bugfix              → .peaks/_runtime/<sid>/rd/bug-analysis.md
-   - config | docs | chore → no planning artefact required. Return skipped.
-7. Return:
-   {
-     "role": "rd-planning",
-     "rid": "<rid>",
-     "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/_runtime/<sid>/rd/tech-doc.md"],   // or [] when skipped
-     "warnings": [],
-     "blockedReason": null
-   }
-```
-
-### 3.4 peaks-qa (test-cases) sub-agent prompt
-
-```
-## Role: QA test-case generation (planning, not execution)
-You are running peaks-qa's planning step. Produce test cases, do NOT execute them.
-The execution step runs after RD implementation in a separate sub-agent.
-
-Steps:
-1. peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
-2. peaks request show <rid> --role prd --project <repo> --json
-3. peaks request show <rid> --role rd  --project <repo> --json
-4. Read <project-scan-path>.
-5. Write .peaks/_runtime/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
-   acceptance items (use **Acceptance:** A1, A2 style).
-6. Return:
-   {
-     "role": "qa-test-cases",
-     "rid": "<rid>",
-     "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/_runtime/<sid>/qa/test-cases/<rid>.md"],
-     "warnings": [],
-     "blockedReason": null
-   }
-
-If --type is docs|chore, return {"status":"skipped","reason":"type=<type>"} —
-no acceptance surface to plan tests for.
-```
-
-## 4. Reducer (Solo side)
-
-After all sub-agent dispatch calls return and the LLM has invoked the toolCalls, Solo:
-
-1. Restores presence ONCE (not per-agent):
-   ```
-   peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
-   ```
-2. Runs `ls` checks against `sc/swarm-plan.json` — every promised artefact must exist (Gate B hard). If any are missing, apply the degradation rules in "Degradation when swarm roles fail or are absent" (main SKILL.md).
-3. Updates `sc/swarm-plan.json` with the final status of each sub-agent (ok / blocked / skipped / error).
-4. Advances to step 4 (RD implementation) with all the artefacts in hand.
-
-## 5. Presence restoration (single-shot)
-
-Sub-agents are explicitly forbidden from calling `peaks skill presence:set`. That means `.peaks/.active-skill.json` does not move during the fan-out. Solo sets it to `gate=swarm-fan-out` before fan-out and to `gate=swarm-converged` once after all Tasks return. The status header (the `Peaks-Loop Skill: peaks-solo | Peaks-Loop Gate: <gate>` line) therefore reads consistently across the fan-out window.
-
-If a sub-agent is misbehaving and writes to `.peaks/.active-skill.json` anyway, the next Solo presence-set (after fan-out) overwrites it — the bug self-heals on the next gate advance, but the swarm-phase display may be off. The hard prohibition is there to prevent this; Solo should still treat the file as a single-writer resource.
-
-## 6. Why not a `peaks-swarm` skill?
-
-A skill cannot itself trigger sub-agents — the Skill tool runs in the main loop. The orchestrator (peaks-solo) has to be in the main loop and has to call `peaks sub-agent dispatch` directly. Putting swarm logic into a separate skill would either re-introduce the "single-stack blocking" anti-pattern or require a custom slash command that bypasses the Skill tool. The current design keeps swarm control in peaks-solo where it belongs.
-
-## 7. Tests / dogfood
-
-- `peaks scan archetype --project <repo> --json` must keep emitting `frontendOnly` and `frontendOnlyReason`. Both fields are read here and by the existing pre-RD scan contract.
-- `peaks request show <rid> --role prd --json` must surface the `--type` chosen at `peaks request init`. Sub-agents pass it through unchanged.
-- `peaks skill presence:set` must remain single-writer-friendly (the sub-agents do not call it).
-- Smoke test: a full-auto peaks-solo run on a `legacy-frontend` project with a UI-affecting PRD should produce `sc/swarm-plan.json` containing all three sub-agents and three corresponding artefacts in `ui/`, `rd/`, `qa/`.
-
----
-
-### Swarm gate (decide BEFORE fan-out)
-
-> Body of `### Swarm gate`. Before launching any sub-agent, Solo must compute the **swarm plan** from three signals:
-
-1. **PRD state** — `prd/requests/<rid>.md` must be in state `confirmed-by-user` or `handed-off`. If not, STOP. The Swarm is downstream of PRD, not a substitute for it.
-2. **Request type** (`--type` from `peaks request init`):
-   - `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/_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/_runtime/<sessionId>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
-
-```json
-{
-  "rid": "<rid>",
-  "type": "feature",
-  "frontendOnly": true,
-  "frontendKeywordHit": true,
-  "subAgents": ["ui", "rd-planning", "qa-test-cases"]
-}
-```
-
-Sub-agent presence in this list = Solo launched a Task for it. Absence = the role was skipped with documented reason.
-
-### Mode-driven fan-out shape
-
-> Body of `### Mode-driven fan-out shape`.
-
-| Mode | How the swarm plan is decided | What Solo does |
-|---|---|---|
-| `full-auto` | Compute plan from signals above, no question to user | Auto-launch all sub-agents in the plan in parallel |
-| `swarm` | Same as `full-auto` | Same as `full-auto` (this profile name is historical — behavior is identical) |
-| `assisted` | `AskUserQuestion` with three options: (a) Full — UI + RD(planning) + QA(test-cases); (b) Backend-only — RD(planning) + QA(test-cases); (c) Sequential — run RD first, then QA, skip UI | Use the user's choice as the plan |
-| `strict` | Same as `assisted` (the question is informational; strict still enforces confirmation gates later) | Same as `assisted` |
-
-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.
-
-### Degradation when swarm roles fail or are absent
-
-> Body of `### Degradation when swarm roles fail or are absent`.
-
-| Condition | Solo action | TXT handoff note |
-|---|---|---|
-| UI sub-agent returns blocked/error | RD continues with PRD visual descriptions | `ui-design-missing` |
-| RD planning sub-agent returns blocked/error | RD continues with PRD-derived planning | `tech-doc-missing` |
-| QA test-cases sub-agent returns blocked/error | RD continues; QA backfills test cases before verdict | `qa-test-cases-missing` |
-| Two or more of the above | Fall back to sequential: `peaks request transition rd → spec-locked` then inline RD run, then QA | `swarm-degraded-to-sequential` |
-| All three fail | Pause workflow; surface to user; request confirmation to continue | `swarm-aborted` |
-
-Skipping the entire swarm (when `--type` is `config|docs|chore`) is not a degradation — record `swarm-skipped: type=<type>` and proceed.