peaks-cli 1.3.7 → 1.3.9

package/skills/peaks-solo/references/project-scan-checklist.md

@@ -0,0 +1,136 @@
+# Peaks-Cli Pre-RD project scan checklist
+
+> Extracted from `skills/peaks-solo/SKILL.md` on 2026-06-09 (slice 019 — slim skill files to references) to keep SKILL.md under the 800-line cap from `common/coding-style.md`. The content below is the verbatim Pre-RD project scan checklist that was previously inline; nothing was paraphrased, just relocated.
+
+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)
+
+Run the CLI; do NOT infer the archetype from prompts. Record the JSON output as `## Archetype` and `## Project mode` in `project-scan.md`. Later gates (frontend-only mode, visual system extraction, standards generation) read these fields.
+
+```bash
+peaks scan archetype --project <repo> --json
+```
+
+The command emits a stable JSON envelope with these fields you copy verbatim into `project-scan.md`:
+
+- `archetype`: `greenfield | legacy-frontend | legacy-fullstack | frontend-monorepo | unknown`
+- `confidence`: `high | medium | low`
+- `frontendOnly`: `true | false`
+- `frontendOnlyReason`: short string explaining the decision
+- `signals[]`: each signal's name, matched flag, and detail (paste under `## Archetype → Signals matched`)
+- `detected`: raw filesystem facts (package.json presence, backend frameworks, swagger paths, monorepo configs, src file count, lockfile age)
+
+If `archetype` is `unknown`, STOP and surface to the user as an open question in the TXT handoff — do NOT guess. If `confidence` is `low`, note the uncertainty in `project-scan.md` and confirm the choice with the user before proceeding.
+
+The CLI is the sole source of truth for archetype and frontend-only-mode decisions. Manual heuristics in older versions of this skill are superseded by the CLI output.
+
+### 1. Build tool: inspect config files for the framework
+
+| Config file | Framework |
+|---|---|
+| `.umirc.ts`, `config/config.ts` | Umi (Ant Design Pro) |
+| `next.config.*` | Next.js |
+| `vite.config.*` | Vite |
+| `rsbuild.config.*` | Rsbuild |
+| `rspack.config.*` | Rspack |
+| `farm.config.*` | Farm |
+| `craco.config.*` | CRA + craco |
+| `webpack.config.*` | Webpack |
+| `gulpfile.*` | Gulp (legacy) |
+| `angular.json` | Angular |
+| Custom `build/` or `scripts/build.*` only | Bespoke pipeline — record as `custom` and capture entry script path |
+
+If multiple build configs coexist (e.g. `webpack.config.js` + `vite.config.ts`), record ALL of them and mark `build.mixed: true`. Mixed builds are a constraint, not an error — do not silently pick one.
+
+### 2. Component library: check `package.json` dependencies
+
+| Package | Library |
+|---|---|
+| `antd` (capture major version: v3/v4/v5) | Ant Design |
+| `@ant-design/pro-components`, `@ant-design/pro-*` | Ant Design Pro suite |
+| `@mui/material` | Material UI |
+| `tailwindcss` + `radix-ui` | shadcn/ui |
+| `element-plus` / `element-ui` | Element UI/Plus |
+| `@arco-design/web-react` | Arco Design |
+| `tdesign-react` / `tdesign-vue-next` | TDesign |
+| `@douyinfe/semi-ui` | Semi Design |
+| `@nextui-org/react` | NextUI |
+| `@chakra-ui/react` | Chakra UI |
+| `vant` | Vant (mobile) |
+| Workspace package (`workspace:*`) or private-registry scope matching internal design system | In-house design system — record package name and entry path |
+
+**CRITICAL**: Never add a second component library to a project that already has one. Do not introduce shadcn/ui to an antd project or vice versa. For antd, ALSO record the major version — v3 / v4 / v5 have incompatible APIs and tokens; mixing component code across majors is a blocker.
+
+### 3. CSS framework: check for conflicts
+
+- **antd + TailwindCSS**: High conflict risk (preflight reset overrides base styles). Resolution:
+  - Both already in `package.json` → coexist; use Tailwind for layout, antd for components.
+  - Tailwind breaks antd styles → add `corePlugins: { preflight: false }` or `important: '#root'`.
+  - Only antd, user wants Tailwind → **Block**; propose antd `ConfigProvider` tokens or CSS Modules.
+- **Less/Sass**: Standard for Umi+antd projects; compatible with CSS Modules.
+- **CSS-in-JS (@emotion, styled-components)**: Check if component library already uses one internally; don't add competing solutions.
+
+### 4. State management, routing, data fetching: detect from `package.json`
+
+State: `zustand`, `jotai`, `redux`/`@reduxjs/toolkit`, `valtio`, `mobx`, `hox`
+Routing: `react-router-dom`, `@umijs/max`, Next.js file-based, `vue-router`
+Data fetching: `@tanstack/react-query`, `swr`, `ahooks` (`useRequest`), `umi-request`
+
+### 5. Legacy signals (legacy-frontend / legacy-fullstack only)
+
+Grep `src/` for outdated patterns and list them as constraints in `project-scan.md` under `## Legacy constraints`. RD must preserve these patterns for new code in the same file/module unless PRD explicitly authorizes modernization.
+
+| Signal | Detection |
+|---|---|
+| Class components | `extends React.Component` / `extends Component` in `.tsx`/`.jsx` |
+| `moment` instead of dayjs/date-fns | `package.json` dep |
+| Enzyme test suite | `package.json` dep `enzyme*` |
+| redux-saga / redux-thunk | `package.json` dep |
+| HOC-heavy patterns | `withRouter`, `connect()`, `compose(` frequency in `src/` |
+| Legacy lifecycle | `componentWillMount`/`componentWillReceiveProps` occurrences |
+| jQuery / Backbone / Vue 2 | `package.json` dep |
+| Inline styles dominant | `style={{` occurrences ≥ 50 |
+
+### 6. Project-scan artifact template
+
+```markdown
+# Project Scan: <project-name>
+**Date:** YYYY-MM-DD
+**Session:** <session-id>
+
+## Archetype
+- Type: <greenfield | legacy-frontend | legacy-fullstack | frontend-monorepo | unknown>
+- Signals matched: <bullet list of signals that drove the decision>
+
+## Project mode
+- Frontend-only: <true | false>
+- Reason: <archetype-derived | user-stated | backend-detected>
+
+## Build tool
+- Framework: <name> <version>
+- Config file: <path>
+- Mixed builds: <true | false; list all configs if true>
+
+## Component library
+- Library: <name> <version (major matters for antd)>
+- Design-system packages: <list>
+- In-house design system: <package name | none>
+
+## CSS solution
+- Primary: <Less/Sass/CSS-in-JS/TailwindCSS/CSS Modules>
+- Conflicts detected: <none | description and recommendation>
+
+## State management, routing, data fetching
+- State: <name>
+- Routing: <name>
+- Data fetching: <name>
+
+## Library versions
+- Source: output of `peaks scan libraries --project <repo> --json` (see Gate A; cross-check diff imports against `schemas/library-breaking-changes.data.json` in `peaks-rd` preflight)
+- Total: <count from scan.libraries.totalCount>
+- Notable: <bullet list of libraries with major >= a known breaking change in `schemas/library-breaking-changes.data.json`; e.g. "- antd@^5.18.0 (major=5) — see breaking-change rule for antd v4→v5 if any code uses Drawer.width">
+
+## Legacy constraints
+- <bullet list of legacy signals from section 5; empty for greenfield>
+```

package/skills/peaks-solo/references/quality-gate-cheatsheet.md

@@ -0,0 +1,13 @@
+# Quality-gate commands (CLI cheat sheet)
+
+> Body of `## Peaks-Cli Quality-gate commands`. These commands harden the workflow against silent skips. Use them in the runbook at the points indicated; they all support `--json` and `--session-id`.
+
+| Command | Purpose | When to run | Non-zero exit when |
+|---|---|---|---|
+| `peaks request lint <rid> --role <role> --project <path>` | Scan artifact body for unfilled `<placeholder>`, bare `- ...` bullets, TBD/TODO markers | Before every transition out of `draft` / before role handoff | Any `error`-severity finding (unfilled placeholder, bare-dot bullet) |
+| `peaks request repair-status <rid> --project <path>` | Count RD↔QA repair cycles from `--reason` transition notes ("QA cycle N: ...") | Before every RD repair iteration in step 7 | Cycle count reached the 3-cycle cap |
+| `peaks scan request-type-sanity --project <path> --type <type>` | Cross-verify declared `--type` against the actual `git diff` file mix (catches "feature mis-declared as docs" workflow violations) | After PRD type lock-in AND after each RD repair iteration | Declared type disagrees with the file mix |
+| `peaks scan libraries --project <path>` | Enumerate every dependency + devDependency + peerDependency + optionalDependency with parsed major version; output goes to `## Library versions` in `rd/project-scan.md`. Read-only. | At Solo step 0.6 (alongside `peaks scan archetype`) | Always exits 0 (warnings in JSON envelope; never blocks) |
+| `peaks slice check [--rid <rid>] [--project <path>]` | 4-stage slice 边界 check (typecheck + unit-tests + review-fanout + gate-verify-pipeline). Aggregate pass/fail; non-zero exit if any stage fails. See "Slice 边界 check" below for usage rules (boundary only, never inside a micro-cycle). | At slice 边界（post-micro-cycle, pre-peaks-qa）| Any stage fails |
+
+Together with `peaks request transition` (which already CLI-enforces per-type artifact prerequisites), these five commands form the runtime quality net. SKILL.md prose is descriptive; the CLI is what physically blocks bad workflows.

package/skills/peaks-solo/references/resume-detection.md

@@ -0,0 +1,63 @@
+# Step 0.7 — Detect unfinished work and offer resume
+
+> Body of `### Peaks-Cli Step 0.7`. After Step 0 has anchored the workspace and presence, before Step 1 mode selection, run the resume-detection probe. If the current session has in-flight slice artifacts, the user is most likely "continuing" — surface resume options instead of starting a fresh PRD.
+
+**Why this is a separate step** (per `feedback_peaks_solo_natural_language_primary` — a high-frequency request shape, see also the user's "继续完成刚才为完成的" pattern from session `2026-06-04-session-b60252`): the LLM was previously re-reading 3-5 artifact files to determine workflow state, wasting 3-5k tokens per resume request. This step replaces that work with a single deterministic read.
+
+**Detection logic** (all read-only, no side effects; uses only existing CLIs):
+
+```bash
+# 1. Confirm the current session id via the read-only CLI primitive
+#    (the on-disk binding file is internal — never `cat` it directly)
+sid=$(peaks session info --active --project "$(git rev-parse --show-toplevel)" --json | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['sessionId'])")
+
+# 2. Enumerate the session's artifact tree (one `find` call, no new CLI)
+find ".peaks/$sid/" -type f 2>/dev/null | sort
+
+# 3. For each role request artifact present, read its `state:` field
+#    (one-pass grep; only files that exist)
+for f in .peaks/$sid/prd/requests/*.md .peaks/$sid/rd/requests/*.md .peaks/$sid/qa/requests/*.md; do
+  [ -f "$f" ] && echo "$f: $(grep -m1 '^state:' "$f" | awk '{print $2}')"
+done
+
+# 4. Compute "deepest completed gate" by file-presence + state mapping
+#    (see classification table below)
+```
+
+**Classification table** (file-presence + state → "deepest completed gate"):
+
+| Files present | State | Deepest completed gate | Resume point (if any) |
+|---|---|---|---|
+| only `.peaks/$sid/.session.json` | (no slice) | (none) | fresh — skip to Step 1 |
+| `prd/requests/<rid>.md` | `state: handed-off` | Gate B (swarm converged) | resume at Step 3 (swarm) — but if swarm already ran and produced `rd/tech-doc.md` / `qa/test-cases/<rid>.md`, drop to deepest |
+| `rd/requests/<rid>.md` | `state: qa-handoff` | Gate C (RD done) | resume at Step 6 (QA validation) |
+| `qa/requests/<rid>.md` | `state: verdict-issued` | Gate D (QA done) | resume at Step 10 (TXT handoff) |
+| `txt/handoff.md` | (any) | Gate E (workflow complete) | this session is closed — user is starting new work |
+
+**Other resume triggers** (file-presence, no state read needed):
+
+| Missing file | Resume at |
+|---|---|
+| `rd/tech-doc.md` (for `feature`/`refactor`) or `rd/bug-analysis.md` (for `bugfix`) | Step 3b (RD planning) |
+| `rd/code-review.md` or `rd/security-review.md` | Step 5 (RD review fan-out) |
+| `rd/perf-baseline.md` (for `feature`/`refactor`) | Step 5 (perf baseline) |
+| `qa/test-cases/<rid>.md` | Step 6 (QA test-case generation) |
+| `qa/test-reports/<rid>.md` or `qa/security-findings.md` or `qa/performance-findings.md` | Step 6 (QA execution) |
+| `txt/handoff.md` | Step 10 (TXT handoff) |
+
+**AskUserQuestion** (only if a resume is detected; default option is "Resume from the deepest missing gate"):
+
+| Option | What it does |
+|---|---|
+| Resume from `<gate>` (Recommended) | Skip ahead to the matching step, preserving all existing artifacts. The LLM does NOT re-read the existing artifacts — it trusts the classification and proceeds. |
+| Start a fresh slice | Keep the workspace, treat the current user request as a new slice (new rid). Existing artifacts are preserved but not auto-resumed. |
+| Abandon the in-flight slice | Mark the in-flight slice as `deferred` (`peaks request transition … --state deferred`); start a new one. |
+
+**Hard rule: never silently auto-resume.** Resume detection is the discovery; AskUserQuestion is the confirmation. Even if the user's request is "继续完成刚才为完成的" (continue the unfinished work), the skill must run this detection, surface the options, and wait for user confirmation before skipping ahead.
+
+**Hard rule: never auto-resume a slice that is mid-implementation.** Resume only when the deepest completed gate is in {B, C, D, E}. For mid-implementation states (RD `state: implemented`, RD `state: running`, RD `state: spec-locked`, QA `state: running`, QA `state: blocked`), the slice is still in flight — the only valid option is "Resume from in-flight gate" (the user must confirm).
+
+**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` (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.

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

@@ -8,7 +8,7 @@
 > - `peaks skill runbook peaks-solo` (CLI) reads the `## Default runbook` section in either SKILL.md or `references/runbook.md` (whichever has the bash code).
 > - The test in `tests/unit/skill-default-runbook.test.ts` looks for `## Default runbook` in SKILL.md first, then falls back to `references/runbook.md` here.
 
-## Default runbook
+## Default runbook — CLI sequence
 
 The end-to-end CLI sequence for the `full-auto` profile. `assisted` and `strict` profiles pause at `[CONFIRM]` markers below. `full-auto` and `swarm` auto-proceed through all gates. See Transition Gates for artifact verification at each stage.
 

package/skills/peaks-solo/references/skill-presence-and-title.md

@@ -0,0 +1,31 @@
+# Step 2 + 2.5 — Skill presence and session title
+
+> Combined body for `### Peaks-Cli Step 2: Re-set skill presence with the chosen mode` and `### Peaks-Cli Step 2.5: Set session title`.
+
+## Step 2 — Re-set skill presence
+
+Step 0 already set presence with no mode. Now that the mode is known (user selected or explicitly named), re-run presence:set so the header/status line shows the profile:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode-value> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Then display the compact status header: `Peaks-Cli Skill: peaks-solo | Peaks-Cli Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
+
+Update with `peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
+
+## Step 2.5 — Set session title
+
+Extract a short (8-20 Chinese characters, or 4-10 English words) descriptive title from the user's first request. The title should capture the core task — e.g. "修复登录页OAuth回调异常", "添加暗色模式开关", "搭建项目基础架构". Then run:
+
+```bash
+peaks session title $(peaks session info --active --project "$(git rev-parse --show-toplevel)" --json | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['sessionId'])") "<title>"
+```
+
+If the session directory already has a title (check via `peaks session list --json`), skip this step — the title is already set.

package/skills/peaks-solo/references/standards-preflight.md

@@ -0,0 +1,23 @@
+# Project standards preflight
+
+> Body of `## Peaks-Cli Project standards preflight`. Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks-Cli CLI:
+
+- `peaks standards init --project <path> --dry-run`
+- `peaks standards update --project <path> --dry-run`
+
+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/<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/<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.
+
+For project-analysis requests such as "分析项目" / "分析下这个项目", Step 0 still applies: the workspace is initialized and `peaks-solo` presence is set before any analysis output. These requests run the lightweight analysis branch (project scan + standards dry-run) rather than the full RD/QA pipeline, but they never skip workspace anchoring or exit the workflow. The handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
+
+- whether `CLAUDE.md` is missing, existing, planned, skipped, appended, or review-only;
+- which `.claude/rules/**` files are planned, existing, skipped, appended, or review-only;
+- whether writes were applied or intentionally left as dry-run because authorization or scope was absent;
+- the exact next action if standards should be applied later.
+
+If the dry-run output lacks enough detail to explain those deltas, say that the standards increment is unknown and keep standards application blocked until another `peaks standards init/update --dry-run` provides evidence.

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

@@ -240,3 +240,49 @@ When writing a SKILL.md that fans out sub-agents:
 - `.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-Cli 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.
+- **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

@@ -150,3 +150,59 @@ A skill cannot itself trigger sub-agents — the Skill tool runs in the main loo
 - `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.