peaks-loop 3.0.0

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

@@ -0,0 +1,230 @@
+# 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-Cli 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-Cli 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-Cli Skill: peaks-solo | Peaks-Cli 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.

package/skills/peaks-solo/references/workflow-gates-and-types.md

@@ -0,0 +1,186 @@
+# Peaks-Cli Workflow Order + Request Type Classification + Transition Verification Gates
+
+> **Maintenance**: This reference holds the canonical contract for (a) how Solo sequences the 11 workflow steps, (b) which `--type` to pass to `peaks request init` for which slice shape, and (c) the executable `ls` / `grep` gate commands that physically block progression. SKILL.md keeps the narrative ("what peaks-solo does"); this file keeps the contract.
+>
+> **Why extracted from SKILL.md**: this content is 165 lines of mostly-tabular + bash-block contract — reference data, not orchestration prose. Inlining it bloats SKILL.md past the 800-line cap (per `common/coding-style.md`). The numbers, gate command shapes, and type-classification rules change rarely; the SKILL.md prose around them (orchestration flow, repair-loop intent, swarm fan-out shape) changes more often.
+>
+> **How peaks-cli tooling reads this file**:
+> - `peaks skill runbook peaks-solo` (CLI) and the in-line LLM reading the SKILL.md should reference this file when the gate-machine or type-classification contract is in play.
+> - The test `tests/unit/skill-default-runbook.test.ts` does NOT check this file (it only checks the runbook). Future tests can add a similar fallback for the gates-and-types contract.
+
+## Peaks-Cli Request type classification (MANDATORY before `peaks request init`)
+
+Before initializing any role artifact, classify the request into exactly one of six types. The choice drives RD/QA gate strictness (see "Mandatory RD QA repair loop"). Pick the **primary intent** — if a request could fit two types, the higher-strictness one wins.
+
+| `--type` | Pick this when the PRD says... | Pick something else when... |
+|---|---|---|
+| `feature` | Add new capability, new page/component/route/API path, new user-facing behavior. Includes "extend X to support Y" when Y is a new code path. | The PRD is fixing an existing broken behavior → `bugfix`. The PRD is reshaping existing code without changing user-visible behavior → `refactor`. |
+| `bugfix` | Fix a specific broken behavior; PRD includes reproduction steps or a defect description; success = "the broken thing now works as it was supposed to". | The "fix" actually adds new capability (validation that didn't exist, a missing field) → `feature`. The "fix" is purely cosmetic and has zero risk → still `bugfix`; do NOT downgrade to `chore`. |
+| `refactor` | Restructure code without changing user-visible behavior. Examples: rename modules, extract shared utilities, migrate a library version with no API surface change, split a monolithic file. PRD mentions coverage targets or "no behavior change". | The refactor incidentally adds or changes user-visible behavior → split into `refactor` + `feature` or pick `feature`. The change is one-line formatting → `chore`. |
+| `config` | Modify config / infrastructure files only: `tsconfig.json`, `eslint`, CI YAML, `package.json` scripts, env defaults, CORS/CSP rules, build config, Docker, deployment manifests. No application source-code changes. | The config change is paired with code changes that consume the new config → `feature` or `refactor` (whichever the code change is). |
+| `docs` | Modify only `*.md` / docs site / inline JSDoc / README. No `.ts` / `.tsx` / `.js` / `.css` / config-file changes. | Any source code change is included → use the type matching the code change. Adding a code example to docs that requires the example to compile → still `docs` if the example is illustrative only. |
+| `chore` | Pure mechanical hygiene: formatter run, lint fix, dependency version bump with no API surface change, dead-code removal of unused files identified by tooling. | The bump changes API behavior or requires consumer migration → `refactor` (or `feature` if it adds capability). Any logic edit → `bugfix` or `refactor`. |
+
+**Self-check before locking the type**: read the PRD scope and answer "what is the smallest gate set that still protects users from regression?" — that is the right type. Picking `docs` or `chore` to skip gates when source code is actually changing is a workflow violation and the SC phase will reject it.
+
+For ambiguous cases (e.g. "improve login flow"), ask the user to clarify before initializing. The cost of one `AskUserQuestion` round is much lower than running the wrong gate matrix for the whole workflow.
+
+When Peaks-Cli Solo coordinates development in a code repository, keep this order explicit:
+
+0. **Peaks-Cli Snapshot** — `peaks doctor` + `peaks project dashboard` to capture baseline state before anything else;
+0.5. **Peaks-Cli Workspace initialization** — `.peaks/_runtime/<session-id>/` created, directory structure verified;
+0.6. **Peaks-Cli Project scan** — archetype, component library, CSS framework, build tool, state management, routing, data fetching, legacy signals detected and recorded to `.peaks/_runtime/<session-id>/rd/project-scan.md`;
+0.7. **Peaks-Cli Existing-system extraction** (MANDATORY when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}; SKIP for greenfield) — extract visual tokens and code conventions from the live codebase to `.peaks/_runtime/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file also records non-UI conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. See `references/existing-system-extraction.md`. UI design-draft and RD implementation MUST treat the extracted tokens and conventions as hard constraints;
+1. **Peaks-Cli Standards preflight** — `peaks standards init/update --dry-run`, must reference concrete project-scan findings (never emit generic templates);
+2. **Peaks-Cli PRD phase** — capture request as canonical artifact, extract scope and acceptance criteria:
+   - Full-auto/Swarm: auto-transition to `confirmed-by-user` once the artifact is complete;
+   - Assisted/Strict: pause with `AskUserQuestion` for explicit user confirmation before proceeding;
+3. **Peaks-Cli Swarm parallel phase** — after PRD confirmed, launch UI, RD(planning), QA(test-cases) simultaneously:
+   3a. UI design draft and visual direction (MANDATORY when request is frontend/user-visible; skipped for `--type docs|chore|config` or pure-backend requests);
+   3b. RD planning artifact — `rd/tech-doc.md` for feature/refactor, `rd/bug-analysis.md` for bugfix, skipped for docs/chore/config;
+   3c. QA test-case generation (skipped for docs/chore — no acceptance surface to validate);
+4. **Peaks-Cli RD implementation** — consumes the type-appropriate inputs: project-scan + standards + (if UI involved) UI design-draft + RD planning artifact + QA test-cases. Includes unit tests for new/changed behavior (TDD) unless `--type` is docs/chore;
+5. **Peaks-Cli Code review + security review** — CRITICAL/HIGH issues fixed before progression; marked-blocked issues only allow a blocked handoff;
+6. **Peaks-Cli QA validation** (auto-proceed from RD in full-auto) — execute test cases + API checks + Playwright MCP headed browser E2E for frontend + security/perf checks + test report;
+7. **Peaks-Cli RD↔QA repair loop** — if QA verdict is `return-to-rd`, loop back to step 4 (RD implementation) and re-run through QA; max 3 repair cycles, then emit blocked TXT regardless;
+8. **Peaks-Cli SC phase** — change-control evidence: impact, retention, validate, boundary;
+9. **Peaks-Cli OpenSpec archive** — exit gate: validate → archive only after QA verdict=pass (when `openspec/` exists);
+10. **Peaks-Cli TXT handoff capsule** — mode, validated decisions, artifact paths, standards deltas, open questions, next action;
+11. **Peaks-Cli Final snapshot** — `peaks project dashboard` + `peaks skill doctor` to confirm the workflow closed cleanly.
+
+### Peaks-Cli Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file", the phase is incomplete.
+
+**Peaks-Cli Gate A — After workspace init + project scan:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/project-scan.md
+# Expected output: .peaks/_runtime/<sessionId>/rd/project-scan.md
+# "No such file" → STOP, run project scan first
+# File present but missing `## Archetype` or `## Project mode` sections → INCOMPLETE, rerun scan
+# File present and complete → reuse (project-scan is a session-scoped singleton)
+```
+
+**Peaks-Cli Gate A.5 — Existing-system extraction (legacy projects only):**
+```bash
+# If project-scan.md `## Archetype` is greenfield → skip this gate
+# Otherwise:
+ls .peaks/_runtime/<sessionId>/system/existing-system.md
+# "No such file" → STOP, run existing-system extraction
+# (see references/existing-system-extraction.md)
+```
+
+**Peaks-Cli Gate B — After swarm convergence (UI + RD planning + QA test-cases):**
+
+Peaks-Cli Gate B has two sub-checks: a HARD gate (blocks progression) and an INFORMATIONAL check (records degradation but does not block).
+
+```bash
+# B.hard — REQUIRED before continuing to RD implementation.
+#          Missing any of these → STOP, return to the role that owns the file.
+
+# Always required (every type):
+ls .peaks/_runtime/<sessionId>/prd/requests/<rid>.md
+
+# Type-specific RD planning artifact:
+#   feature / refactor → ls .peaks/_runtime/<sessionId>/rd/tech-doc.md
+#   bugfix             → ls .peaks/_runtime/<sessionId>/rd/bug-analysis.md
+#   config / docs / chore → (no RD planning artifact required)
+
+# QA test-cases (skipped for docs/chore):
+ls .peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md
+```
+
+```bash
+# B.info — NON-BLOCKING. Record degradation in TXT, then proceed.
+ls .peaks/_runtime/<sessionId>/ui/design-draft.md 2>&1
+# "No such file" + request affects user-visible UI → swarm degradation rule 1 fires:
+#   note "ui-design-missing" in TXT, RD continues with PRD visual descriptions.
+# "No such file" + pure backend / docs / chore / config → state skip reason in TXT, proceed.
+```
+
+**Peaks-Cli Gate C — After RD implementation (before QA handoff):**
+
+The CLI gate (`peaks request transition --state qa-handoff`) is the authoritative check; running this `ls` first lets you produce missing files before the CLI rejects the transition.
+
+| Request type | Required RD evidence (under `.peaks/_runtime/<sessionId>/`) |
+|---|---|
+| `feature` / `refactor` | `rd/tech-doc.md` + `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` + `qa/test-cases/<rid>.md` (qa/test-cases pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004) |
+| `bugfix` | `rd/bug-analysis.md` + `rd/code-review.md` + `rd/security-review.md` + `qa/test-cases/<rid>.md` (rd/perf-baseline.md only when the bug is performance-shaped) |
+| `config` | `rd/security-review.md` |
+| `docs` / `chore` | (no extra evidence required) |
+
+Always required (in addition to the type-specific row): `ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md`. Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
+
+```bash
+# Always required
+ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md
+
+# Type-specific RD evidence (must match the type recorded in the artifact body)
+#   feature / refactor → ls rd/tech-doc.md rd/code-review.md rd/security-review.md rd/perf-baseline.md qa/test-cases/<rid>.md
+#                         (qa/test-cases/<rid>.md pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004)
+#   bugfix             → ls rd/bug-analysis.md rd/code-review.md rd/security-review.md qa/test-cases/<rid>.md
+#                         (rd/perf-baseline.md only when the bug is performance-shaped)
+#   config             → ls rd/security-review.md
+#   docs / chore       → (no extra evidence required)
+# Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
+```
+
+**Peaks-Cli Gate D — After QA validation:**
+
+The CLI gate at `qa:verdict-issued` is the authoritative check; this `ls` lets you produce missing evidence before the CLI rejects the transition.
+
+```bash
+# Always required
+ls .peaks/_runtime/<sessionId>/qa/requests/<rid>.md
+
+# Type-specific QA evidence
+#   feature / refactor → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md qa/performance-findings.md
+#   bugfix             → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md
+#   config             → ls qa/security-findings.md
+#   docs / chore       → (no QA evidence files required)
+# Missing required file → QA incomplete; do not transition to verdict-issued.
+```
+
+**Peaks-Cli Gate E — Before declaring workflow complete:**
+```bash
+find .peaks/_runtime/<sessionId>/ -type f | sort
+# Verify: files from gates A-D all appear in this list.
+# Any mandatory file missing → NOT complete. Do not emit TXT.
+# Peaks-Cli Gate G (CLAUDE.md + .claude/rules/**) must ALSO pass before TXT is emitted.
+```
+
+**Peaks-Cli Gate F — Root pollution check (BLOCKING before completion):**
+```bash
+# Verify no Peaks-Cli intermediate artifacts leaked to project root.
+ls feishu-doc-*.md *-snapshot.md qa-server.js 2>&1
+# Expected: "No such file or directory" for ALL patterns.
+# Any file found → ROOT POLLUTION. Move it to .peaks/_runtime/<sessionId>/prd/source/
+# (for doc snapshots) or .peaks/_runtime/<sessionId>/qa/ (for QA artifacts).
+# Note the migration in TXT handoff. Do NOT complete the workflow
+# with intermediate artifacts in the project root.
+```
+```bash
+# Extended check for common leak patterns
+find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "mock-server.*" 2>&1
+# Any Peaks-Cli QA/UI intermediate files here → ROOT POLLUTION. Move and note.
+# Legitimate project files (e.g. favicon.png) are fine — only move Peaks-Cli artifacts.
+```
+
+**Peaks-Cli Gate G — Project standards present (BLOCKING before workflow completion):**
+```bash
+# After `peaks standards init/update --apply`, verify the files actually landed
+# at the project root. The CLAUDE.md and rules files are required so that
+# subsequent peaks-rd / peaks-qa / peaks-solo runs perform the project-local
+# preflight described in CLAUDE.md (read coding-style.md, code-review.md, security.md).
+ls <repo>/CLAUDE.md
+# "No such file" → BLOCKED. Run `peaks standards init --project <repo> --apply --json`
+# (first time) or `peaks standards update --project <repo> --apply --json` (existing).
+ls <repo>/.claude/rules/common/coding-style.md \
+   <repo>/.claude/rules/common/code-review.md \
+   <repo>/.claude/rules/common/security.md
+# Any "No such file" → BLOCKED. The standards apply step did not complete; re-run
+# standards init/update with --apply and re-verify.
+# Skipping Peaks-Cli Gate G (e.g. because the user did not explicitly authorize writes) is
+# only acceptable in `assisted`/`strict` modes where the user actively declined; in
+# `full-auto`/`swarm` the absence of these files is a workflow violation.
+```

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

@@ -0,0 +1,38 @@
+# Peaks Solo Workflow
+
+Peaks Solo is a facade over role skills. It keeps the workflow moving without absorbing role-specific responsibility.
+
+## Modes
+
+- Solo: default, single controller with soft gates.
+- Assisted: role skills contribute artifacts without broad swarm execution.
+- Swarm: multiple subagents work in parallel when the CLI-managed profile is enabled.
+- Strict: hook/profile guarded mode for high-risk work.
+
+## Required code workflow evidence
+
+A code workflow is not complete until Solo has linked or summarized:
+
+1. standards preflight;
+2. PRD/RD scope and OpenSpec artifacts when required;
+3. RD implementation evidence;
+4. unit-test evidence for new or changed behavior;
+5. code-review evidence;
+6. security-review evidence;
+7. RD post-check dry-run evidence;
+8. QA API validation when applicable;
+9. sanitized QA Playwright MCP browser E2E evidence for frontend projects (`mcp__playwright__browser_snapshot` / `take_screenshot` / `list_console_messages` / `list_network_requests`), with mandatory visible-browser confirmation and without login URLs, cookies, headers, tokens, storage state, browser traces, or PII/SSO/MFA screenshots/logs;
+10. QA security, performance, and validation report evidence;
+11. RD repair evidence for every failed, blocked, missing, or unverified QA item;
+12. final QA report showing all acceptance items passed, or a blocked TXT handoff;
+13. TXT handoff capsule.
+
+For legacy repositories with pre-existing low UT coverage, do not require historical coverage cleanup as part of an unrelated change, but do require focused coverage evidence for the new or changed code.
+
+## RD QA loop
+
+Every RD implementation or repair slice must be followed by QA validation. If QA does not fully pass, Solo routes the report back to RD, then repeats RD repair and QA validation until QA is all green or the workflow is blocked. In full-auto mode, Claude Code's `goal` command may be used to keep the controller objective explicit while Peaks artifacts remain authoritative.
+
+## Capability discovery
+
+Before using `find-skills`, explain the benefit and token cost unless the active profile permits automatic discovery.

package/skills/peaks-solo-resume/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: peaks-solo-resume
+description: Resume an in-flight peaks-solo slice in the current session. Use when the user says "continue the unfinished work", "继续完成", "把刚才没做完的收尾", or invokes `/peaks-solo-resume` directly. Detects the current session's deepest completed gate (via the Step 0.7 detection script at `tests/fixtures/skill-resume-mode-detect.sh`) and surfaces a resume option via `AskUserQuestion`. Triggers on `/peaks-solo-resume`, "继续完成刚才的", "resume the unfinished slice", "把刚才没做完的收尾".
+---
+
+# Peaks-Cli Solo Resume (wrapper)
+
+Peaks-Cli Solo Resume is a thin wrapper that handles the **most common high-frequency request shape**: "I was in the middle of something, continue it." It detects the current session's deepest completed gate, surfaces a resume option, then yields to the main `peaks-solo` skill (which runs the actual workflow from the matching gate onwards).
+
+**This is a transparent wrapper.** The user does not stay in this skill — once the resume option is confirmed, control hands off to `peaks-solo`. The wrapper exists only to (a) detect the in-flight slice without the LLM re-reading 3-5 artifact files, and (b) surface the resume option as a `AskUserQuestion` before the main loop skips ahead.
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-resume --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Detect the current session's in-flight slice
+
+Use the Step 0.7 detection script (added in slice 003) to classify the current session:
+
+```bash
+# 1. Confirm the current session id
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 2. Run the detection script
+bash tests/fixtures/skill-resume-mode-detect.sh "$sid" .peaks
+# Possible outputs: fresh | complete | resume:rd-planning | resume:qa-validation
+#                  | resume:txt-handoff | in-flight:<state>
+```
+
+## Step 2: Branch on the detection
+
+**If `fresh`**: no in-flight slice. Tell the user "No in-flight slice in this session." Then hand off to `peaks-solo` for a fresh start (set presence back, then run `peaks workspace init --project <repo> --json` and continue with Step 1 of `peaks-solo`).
+
+**If `complete`**: the workflow is already done. Tell the user "This session is complete — your previous slice already shipped." Then suggest a fresh start (`peaks-solo`) or close-out.
+
+**If `resume:<gate>`**: surface a resume option via `AskUserQuestion`:
+
+| Option | What it does |
+|---|---|
+| Resume from `<gate>` (Recommended) | Hand off to `peaks-solo` with the gate already at the matching point. The main loop skips ahead; the existing artifacts are preserved as-is. |
+| Start a fresh slice | Treat the current 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 <rid> --role rd --state deferred --reason "user abandoned"`) and start fresh. |
+
+**If `in-flight:<state>`**: the slice is mid-implementation. Surface a CONFIRM (not a resume):
+
+> "The slice is mid-implementation (state: `<state>`). The only valid option is to resume the in-flight gate. Continue?"
+
+Use `AskUserQuestion` with a single option (Confirm and resume from `<state>`). Do NOT auto-resume mid-implementation.
+
+## Step 3: Hand off to peaks-solo
+
+After the user confirms, **re-assert `peaks-solo` presence** so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <matching-gate>
+```
+
+Then tell the user: "Resuming from `<gate>`. The main peaks-solo skill will take over from there." and yield control. The user's next message will land in the `peaks-solo` main loop, which will pick up the workflow from the matching gate.
+
+## Hard rules (do NOT skip)
+
+- **Never silently auto-resume.** Always use `AskUserQuestion` first. The detection is a discovery; the user's confirmation is the gate.
+- **Never auto-resume mid-implementation.** For `in-flight:<state>`, the only valid option is "Confirm and resume from `<state>`" — never "Start a fresh slice" or "Abandon" without the user's explicit choice.
+- **Never write code or modify files in this skill.** This is a wrapper. The actual work (PRD, RD, QA, SC, TXT) is the main `peaks-solo` skill's job.
+- **Never add a new `peaks <cmd>`.** Use the existing CLI primitives: `peaks workspace init`, `peaks project dashboard`, `peaks session list`, `peaks skill runbook`, `peaks skill doctor`, `peaks scan archetype`, `peaks request transition`. The detection script (`tests/fixtures/skill-resume-mode-detect.sh`) is the only executable this skill invokes.
+
+## Anti-patterns (do NOT do)
+
+- Do NOT re-read 3-5 artifact files to determine the workflow state. The detection script does this in <1ms; re-reading is the bug Step 0.7 was added to prevent.
+- Do NOT skip the `AskUserQuestion` even if the user says "just continue". The user might have changed their mind, or there might be multiple in-flight slices.
+- Do NOT write to `.peaks/_runtime/<sid>/` files. This skill is read-only on the workspace; it only reads `.peaks/.session.json` + runs the detection script.
+- Do NOT run `peaks workspace init` on a real session (would bind a new session id). Only run it on a fresh detection where no session exists.
+
+## Cross-references
+
+- The detection logic is canonical at `tests/fixtures/skill-resume-mode-detect.sh` (added in slice 003). The 8 vitest cases in `tests/unit/skill-resume-mode.test.ts` cover all classification outcomes.
+- The SKILL.md prose at `skills/peaks-solo/SKILL.md` Step 0.7 (added in slice 003) is the same logic, written for LLM consumption. This wrapper reuses the same script — there is no parallel implementation.
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent for this wrapper.