peaks-loop 3.0.0

package/skills/peaks-solo/references/periodic-checkpoint.md

@@ -0,0 +1,71 @@
+# Step N: periodic checkpoint — trigger table + field reference
+
+## Cadence guidance
+
+The LLM is the only one that knows when context pressure is high. Step N
+gives the LLM a clear trigger table and a field reference so it can call
+`peaks session checkpoint` at the right moments without user action. The
+CLI is idempotent and self-pruning (max 10 retained) so the LLM can
+checkpoint as often as it wants.
+
+## Trigger table
+
+| Trigger                                | `--reason`         |
+|----------------------------------------|--------------------|
+| Every 20 tool calls (LLM keeps a counter; **hard-coded — do NOT override**) | `periodic` (default) |
+| After each PRD/RD/QA/TXT artifact published | `artifact-written` |
+| LLM notices context getting full       | `context-fill`     |
+| User says "save" / "pause"             | `user-pause`       |
+| User closes the session                | `user-close`       |
+
+> **Slice 2026-06-24-efficiency-4p-bundle / G1 (P0.1) — frequency lock**:
+> The `--reason periodic` row above is hard-locked at **20 tool calls**.
+> The threshold is a textual contract between SKILL.md (line 79) and
+> this reference doc; the LLM runner is expected to fire
+> `peaks session checkpoint --reason periodic` once every 20 tool calls
+> (i.e. on each 20-call mark, not "approximately every 20"). The CLI
+> does **not** expose a `--periodic-every <n>` override flag — the
+> cadence is owned by the skill, not the CLI. Any patch that relaxes
+> this must update both files in lockstep or fail the
+> `tests/unit/solo/checkpoint-periodic-frequency.test.ts` guard.
+
+## Checkpoint CLI contract
+
+`peaks session checkpoint [--reason <r>] [--session-id <sid>] [--project <path>] [--current-plan <text>] [--open-questions <list>] [--recent-decisions <list>] [--recent-artifact-paths <list>] [--git-status <text>] [--skills-active <list>] [--todo-state <list>] [--json]`
+
+- `<list>` options accept newline-separated values (one per line).
+- `<sid>` defaults to the canonical binding from `.peaks/_runtime/session.json` (`peaks session info --active`).
+- The CLI writes `.peaks/_runtime/<sid>/checkpoints/<iso>.json` with all 11 documented fields.
+- Idempotent: any number of checkpoints may exist; the oldest beyond 10 are auto-pruned by mtime.
+
+## Field reference
+
+| Field | Source |
+|-------|--------|
+| `sessionId` | canonical binding (resolved via `peaks session info --active`) |
+| `lastActivity` | read from `.peaks/_runtime/<sid>/session.json.lastActivity`; falls back to `createdAt` if missing |
+| `currentPlan` | `--current-plan` flag (one-line slice summary) |
+| `openQuestions` | `--open-questions` flag (newline list) |
+| `recentDecisions` | `--recent-decisions` flag (newline list) |
+| `recentArtifactPaths` | `--recent-artifact-paths` flag (newline list) |
+| `gitStatus` | `--git-status` flag (one `git status --short` output) |
+| `skillsActive` | `--skills-active` flag (newline list of peaks skill names) |
+| `todoState` | `--todo-state` flag (newline list of todo lines) |
+| `reason` | `--reason` flag (one of the 5 documented values) |
+| `createdAt` | stamped at writeCheckpoint() invocation |
+
+## Skill recommendations
+
+- After every major artifact write: `peaks session checkpoint --reason artifact-written --recent-artifact-paths <list> --recent-decisions <list>`.
+- Every 20 tool calls (LLM keeps a counter; locked at 20 per slice 2026-06-24-efficiency-4p-bundle / G1): `peaks session checkpoint --reason periodic`.
+- When user says "save" / "pause" / "checkpoint": `peaks session checkpoint --reason user-pause --current-plan <text>`.
+
+## Checkpoint edge cases
+
+- **No canonical session**: CLI throws `NO_ACTIVE_SESSION`; LLM should call `peaks workspace init` first.
+- **Invalid reason**: CLI throws `INVALID_REASON`; LLM retries with one of the 5 documented values.
+- **Idempotent**: running checkpoint twice in a row produces two distinct files (different `<iso>` filenames). No state corruption.
+
+## Checkpoint IDE note
+
+This step is strictly IDE-agnostic. The LLM calls the peaks CLI; no IDE-specific tools or paths are involved.

package/skills/peaks-solo/references/playwright-mcp-multi-terminal.md

@@ -0,0 +1,114 @@
+# peaks playwright — multi-terminal Playwright MCP (slice 2.5.0 sub-fix C)
+
+## Why this exists
+
+When two or more terminals / IDE sessions each spawn a `playwright` MCP server, they fight over:
+
+1. The default port (8931) — only one server can bind it.
+2. The browser's user-data dir — two servers writing to the same dir corrupt each other's profiles.
+3. The process state — no record of "is anyone else running this?".
+
+`peaks playwright start | ls | stop` is the multi-terminal resolution. Each terminal/IDE session runs `peaks playwright start` once and gets a unique port + a unique user-data dir.
+
+## CLI surface
+
+```sh
+peaks playwright start \
+  [--port <n>]                      # default 8931; walks 8931→8949 if busy
+  [--browser chromium|firefox|webkit]  # default chromium
+  [--user-data-dir <path>]          # default: <projectRoot>/.peaks/_runtime/playwright-userdata/<terminal-id>
+  [--reuse]                         # if a session already exists for this terminal, return its port instead of erroring
+  [--project <path>]                # default: cwd
+  [--json]
+
+peaks playwright ls    [--project <path>] [--json]
+peaks playwright stop  [--terminal <id>] [--project <path>] [--json]
+```
+
+## Port-walk behavior
+
+`peaks playwright start` tries ports in the order `8931, 8932, 8933, ..., 8949`. The first port that is **not** bound by anything (probe uses `net.createServer().listen()`; an `EADDRINUSE` is a busy port) is used. If 8931..8949 are all busy, the command exits with `PORT_EXHAUSTED`.
+
+The CLI does NOT bundle the playwright-mcp binary. It shells out to `npx playwright-mcp@latest --port=<n> --browser=<b> --user-data-dir=<path>`. peaks-cli is the lifecycle orchestrator, not the install medium.
+
+## Session file layout
+
+Each successful `start` writes:
+
+```
+<projectRoot>/.peaks/_runtime/playwright-sessions/<terminal-id>.json
+```
+
+The schema:
+
+```json
+{
+  "terminalId": "tty-aabbccddeeff0011",
+  "port": 8931,
+  "browser": "chromium",
+  "userDataDir": "/abs/path/to/playwright-userdata/<terminal-id>",
+  "startedAt": "2026-06-17T15:00:00.000Z",
+  "pid": 12345
+}
+```
+
+The directory is gitignored (covered by the existing `.peaks/_runtime/` rule in `.gitignore`, with an explicit comment line for future readers).
+
+## Terminal ID derivation (R4)
+
+The terminal id is derived from the process environment, in this order:
+
+1. `process.env.TERM_SESSION_ID` (macOS Terminal, iTerm2)
+2. `process.env.WT_SESSION` (Windows Terminal) — prefixed with `wt-`
+3. Hash of `process.ppid + process.env.SSH_TTY || 'no-tty'` — prefixed with `tty-` (16 hex chars)
+
+Edge cases:
+
+- SSH sessions without `SSH_TTY` → falls back to a hash. Two SSH sessions on the same ppid without `SSH_TTY` would share an id, but in practice each interactive SSH session sets `SSH_TTY` once a pty is allocated.
+- IDEs that don't set `TERM_SESSION_ID` (e.g. some VSCode integrated terminals) → falls back to the hash.
+- Untrusted characters in `TERM_SESSION_ID` (`/`, `\`, space, etc.) are replaced with `_` and truncated to 64 chars.
+
+## Conflict detection (G21 / AC18)
+
+If `peaks playwright start` finds an existing session file for the current terminal, it exits with a clear error:
+
+```
+CONFLICT: another playwright MCP is already running on port 8931 (terminal tty-aabbcc...). Reuse it (--reuse) or pick a new port (--port <n>).
+```
+
+Two ways out:
+
+- `peaks playwright start --reuse` — return the existing session's port (idempotent).
+- `peaks playwright start --port 8940` — pick a different port and try again.
+
+## Workflow
+
+Typical two-terminal setup:
+
+```sh
+# Terminal A
+$ peaks playwright start
+playwright MCP started on port 8931 (browser=chromium, terminal=tty-aabb...)
+
+# Terminal B
+$ peaks playwright start
+playwright MCP started on port 8932 (browser=chromium, terminal=tty-ccdd...)   # walks past 8931
+
+# Inspect
+$ peaks playwright ls
+port=8931   browser=chromium  terminal=tty-aabb...  pid=12345  started=2026-06-17T15:00:00.000Z
+port=8932   browser=chromium  terminal=tty-ccdd...  pid=12346  started=2026-06-17T15:00:01.000Z
+
+# Tear down
+$ peaks playwright stop
+stopped playwright session on port 8931 (terminal=tty-aabb...)
+```
+
+## When this command is unavailable
+
+`peaks playwright start` requires `npx` to be on PATH and reachable network to fetch `playwright-mcp@latest` on first run. If the user's environment has no network or no `npx`, the command fails at spawn time. Document this in onboarding.
+
+## Precedent
+
+- slice 2.3.0 (workspace consolidate + session checkpoint/resume) — same `_runtime/` directory pattern.
+- slice 2.4.0 (cross-IDE byte-stability) — same "do not touch the IDE adapter files" rule; this command is CLI-only.

package/skills/peaks-solo/references/project-memory-loading.md

@@ -0,0 +1,17 @@
+# Step 2.3 — Load project memory
+
+> Body of `### Peaks-Cli Step 2.3`. Before planning any work, read the project's persistent memory — durable memories that survive across sessions:
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory`, grouped by kind:
+- **module** — code areas touched, with risk and rationale captured by past sessions
+- **decision** — architectural choices, why they were made, what they affect
+- **convention** — discovered project patterns (code style, naming, tooling)
+- **rule** / **reference** / **project** — standing constraints, external pointers, and project context
+
+Filter with `--kind <decision|convention|module|rule|reference|project|lesson>` when you only need one slice. Use this to understand what exists, what was decided, and what to avoid re-litigating. Memories are LLM-authored at approved checkpoints via `peaks memory extract`. The `lesson` kind is for LLM-discovered runtime lessons (e.g. "this project's antv6 Drawer uses `size` not `width`"); write them as `<!-- peaks-memory:start kind=lesson -->` blocks in the RD handoff or TXT handoff.
+
+`.peaks/PROJECT.md` is a human-readable session timeline only — do NOT use it for LLM context.

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/refactor-mode.md

@@ -0,0 +1,24 @@
+# Peaks Solo Refactor Mode
+
+`peaks-solo refactor` is the primary MVP path.
+
+## Flow
+
+1. Detect refactor intent and risk.
+2. Ask CLI doctor for available runtime capabilities.
+3. Coordinate `peaks-prd` for goals, non-goals, preserved behavior, and acceptance spec.
+4. Coordinate `peaks-txt` for initial context capsule.
+5. Coordinate `peaks-rd` for project scan, standards scan, coverage report, slice map, and options.
+6. Block implementation unless UT coverage is >= 95%.
+7. Coordinate `peaks-qa` for regression matrix and baseline report.
+8. Ask the user to confirm option, scope, and accepted risks.
+9. Execute one minimal functional slice at a time.
+10. After every RD slice, coordinate `peaks-qa`; if QA reports any failed, blocked, missing, or unverified item, return the report to RD for repair and repeat QA.
+11. Require 100% acceptance for the slice before completion or the next slice.
+12. Coordinate `peaks-sc` for local artifact retention and the `.peaks/_runtime/<session-id>/sc/retention-boundary.md` boundary.
+13. Exclude login URLs, cookies, headers, tokens, storage state, browser traces, and PII/SSO/MFA screenshots or logs from retained artifacts.
+14. Refuse the next slice until code changes and sanitized intermediate artifacts are traceable in local `.peaks/_runtime/<session-id>/` storage; commit or sync only after explicit user or profile authorization.
+
+## Runtime resources
+
+Use CLI-managed profiles for hooks, agents, swarm, MCP, and external skills. Do not install them from the skill body.

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

@@ -0,0 +1,188 @@
+# Peaks-Cli Default Runbook (orchestrator, full-auto profile)
+
+> **Maintenance**: The numbered workflow list in `skills/peaks-solo/SKILL.md` (steps 0-11) is the canonical phase sequence. This runbook is the executable CLI transcription. When updating, keep both in lockstep — a change to one must be reflected in the other.
+>
+> **Why this is a reference, not inline**: the runbook is a stable, copy-pasteable shell (~150 lines of bash) that does not change between skill runs. Inlining it bloats the orchestrator skill body past the 800-line cap (per `common/coding-style.md`). Extracting it here keeps SKILL.md focused on flow / decisions / contracts, while the runbook stays as the canonical place for the CLI sequence.
+>
+> **How peaks-cli tooling reads this file**:
+> - `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 — 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.
+
+Canonical single-shot sub-agent dispatch (the `--prompt` flag is required):
+
+```bash
+peaks sub-agent dispatch <role> --prompt "<body>" --request-id <rid> --batch-id <uuid> --json
+```
+
+```bash
+# 0. Peaks-Cli Snapshot + 0.5 Peaks-Cli Workspace + 0.6 Peaks-Cli Project scan + 0.7 Peaks-Cli Existing-system extraction
+peaks doctor --json
+peaks project dashboard --project <repo> --json
+peaks skill runbook peaks-solo --json
+peaks workspace init --project <repo> --json
+peaks workspace reconcile --project <repo> --json
+peaks scan archetype --project <repo> --json
+# → copy archetype, frontendOnly, signals into .peaks/_runtime/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
+# → copy libraries[] into .peaks/_runtime/<session-id>/rd/project-scan.md under `## Library versions`
+peaks scan libraries --project <repo> --json
+# → if archetype != greenfield AND archetype != unknown:
+peaks scan existing-system --project <repo> --json
+# → copy tokens, sources, conventions, inconsistencies into .peaks/_runtime/<session-id>/system/existing-system.md (Peaks-Cli Gate A.5)
+
+# 1. Peaks-Cli Standards preflight + apply
+#    Run dry-run first to inspect deltas, then APPLY. In full-auto and swarm modes,
+#    --apply is the default — Standards files (CLAUDE.md, .claude/rules/**) live INSIDE
+#    the target project and are required for downstream skill preflight, so producing
+#    them is part of completing the workflow. Assisted/Strict modes pause for [CONFIRM]
+#    between dry-run and apply.
+peaks standards init   --project <repo> --dry-run --json
+# or: peaks standards update --project <repo> --dry-run --json
+peaks standards init   --project <repo> --apply --json
+# or: peaks standards update --project <repo> --apply --json
+# After apply, verify the files actually exist on disk (see Peaks-Cli Gate G).
+
+# 2. Peaks-Cli PRD (Assisted/Strict: [CONFIRM] before confirmed-by-user)
+# Classify the request type from the PRD: feature | bugfix | refactor | docs | config | chore
+# This drives RD/QA gate strictness — see "Mandatory RD QA repair loop" for the matrix.
+peaks request init --role prd --id <rid> --project <repo> --apply --type <type> --json
+# Cross-verify the chosen --type against the current git diff (only meaningful if RD has started writing code;
+# safe to run early too, just expect "no changes" rationale until code lands).
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → re-classify before continuing. consistent=true → proceed.
+# Lint the PRD artifact before transitioning out of draft.
+peaks request lint <rid> --role prd --project <repo> --json
+# → ok=false → fill in <placeholders>, then re-run.
+peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
+peaks request transition <rid> --role prd --state handed-off --project <repo> --json
+
+# 3. Peaks-Cli Default sub-agent fan-out (slice 5 contract)
+#    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
+#    writes it to .peaks/_runtime/<sid>/sc/swarm-plan.json, then writes the slice
+#    DAG to .peaks/_runtime/<sid>/sc/slice-dag.json and launches ONE
+#    `peaks sub-agent dispatch --from-dag <dag-file>` call. The CLI's
+#    envelope.dispatchCount is N (not 1) when the DAG has >= 2 leaves at the
+#    same topological level — that is the canonical "fan-out" signal. The
+#    orchestrator emits N parallel `buildToolCall` descriptors in ONE response;
+#    the LLM-side runner executes them concurrently.
+#    See "Peaks-Cli Default sub-agent fan-out" above for the default rule and
+#    exceptions; the gate logic is single-sourced in references/swarm-dispatch-contract.md.
+#    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
+#    the Swarm phase — that's the v1.x anti-pattern. And do NOT issue N sequential
+#    `peaks sub-agent dispatch <role>` calls in N separate messages when a fan-out
+#    shape exists — `--from-dag` is the only path that exercises the orchestrator.
+#
+# 3a. Pre-fan-out: Solo initialises every role's request artefact slot in the main
+#     loop so sub-agents find a stable rid <-> artefact binding. Each role's
+#     sub-agent may also call peaks request init itself (idempotent on the same rid);
+#     Solo's call here is the source of truth. Only init roles that are in the
+#     swarm plan — roles not in the plan do not get a slot yet.
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-fan-out
+# for each role in swarm-plan.subAgents:
+# peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+# e.g. if plan = [ui, rd, qa]: run init for ui, rd, qa.
+# If plan = [rd, qa]: run for rd, qa only.
+# If plan = [] (config|docs|chore skip): no inits here, jump to step 4 directly.
+# 3b. Solo writes the slice DAG to a JSON file then issues ONE
+#     `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` call.
+#     The CLI envelope returns N parallel buildToolCall descriptors
+#     (dispatchCount = len(swarm-plan.subAgents) when the DAG has >= 2
+#     same-level leaves; 1 otherwise). Each prompt embeds the role's body
+#     minus Step 0 / presence, plus the runtime args (rid / sid / mode /
+#     type / paths). The orchestrator's Promise.all drives the N leaves
+#     concurrently, so wall-time approximates max(per-leaf time), not sum.
+peaks sc build-dag --change-id <cid> --project <repo> --json > .peaks/_runtime/<sid>/sc/slice-dag.json
+peaks sub-agent dispatch --from-dag .peaks/_runtime/<sid>/sc/slice-dag.json --batch-id <id> --project <repo> --json
+# 3c. After fan-out, Solo restores presence once and runs Gate B (ls checks):
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
+ls .peaks/_runtime/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
+# feature / refactor → ls .peaks/_runtime/<sid>/rd/tech-doc.md
+# bugfix             → ls .peaks/_runtime/<sid>/rd/bug-analysis.md
+ls .peaks/_runtime/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
+# ui (only when in plan):
+ls .peaks/_runtime/<sid>/ui/design-draft.md 2>&1               # non-blocking (Gate B info)
+# Apply the degradation rules in the main SKILL.md if any artefact is missing.
+# → Peaks-Cli Gate B convergence check. Assisted/Strict: [CONFIRM]
+
+# 4. Peaks-Cli RD planning artifact (the file required by the prerequisite gate)
+#    feature / refactor → write .peaks/_runtime/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/_runtime/<id>/rd/bug-analysis.md
+#    config             → no planning artifact required at this state
+#    docs / chore       → no planning artifact required
+peaks request transition <rid> --role rd --state implemented --project <repo> --json
+
+# 5. Peaks-Cli Code review + security review BEFORE qa-handoff transition.
+#    Produce the evidence files the CLI gate enforces:
+#      - .peaks/_runtime/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/_runtime/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
+#    Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
+peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
+
+# 6. Peaks-Cli QA validation (AUTO-PROCEED from RD in full-auto)
+#    Before each QA transition, produce the evidence files the CLI gate enforces:
+#      Before qa:running        → .peaks/_runtime/<id>/qa/test-cases/<rid>.md
+peaks request transition <rid> --role qa --state running --project <repo> --json
+#      Before qa:verdict-issued → .peaks/_runtime/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/_runtime/<id>/qa/security-findings.md
+#                                 + .peaks/_runtime/<id>/qa/performance-findings.md (feature/refactor only)
+peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
+# → Peaks-Cli Gate D check. Assisted/Strict: [CONFIRM]
+
+# 7. Peaks-Cli RD↔QA repair loop — if verdict is return-to-rd, re-run 4 through 6 until QA passes or blocked TXT.
+#    Before invoking peaks-rd again, check the cycle count so you don't blow past the cap silently:
+peaks request repair-status <rid> --project <repo> --json
+# → atCap=true → STOP and emit a blocked TXT handoff. Do NOT enter another cycle.
+# → remaining > 0 → safe to continue. The next transition's --reason must include "QA return-to-rd cycle N: ..."
+#                   so this command keeps counting accurately.
+# After RD finishes the repair, re-check that the diff is still consistent with the declared --type:
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → RD scope-creeped during repair; review before re-handoff.
+
+# 8. Peaks-Cli SC phase
+peaks sc impact --change-id <cid> --module <module> --file <path> --json
+peaks sc retention --slice-id <rid> --prd <prd> --rd <rd> --qa <qa> --json
+peaks sc validate --slice-id <rid> --json
+peaks sc boundary --slice-id <rid> --artifact <artifact> --code <file> --json
+
+# 9. Peaks-Cli OpenSpec archive (exit gate; only after QA pass, when openspec/ exists)
+peaks openspec validate <cid> --project <repo> --json
+peaks openspec archive <cid> --project <repo> --apply --json
+peaks workspace reconcile --project <repo> --apply --older-than 7
+
+# 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
+#     peaks-txt writes the handoff capsule to .peaks/_runtime/<id>/txt/handoff.md. Inside the
+#     capsule body, peaks-txt embeds <!-- peaks-memory:start --> blocks for every
+#     stable project fact surfaced this session.
+#
+# 10a. Skill-side scan (do this BEFORE the AskUserQuestion below):
+#      grep -n "peaks-memory:start" .peaks/_runtime/<id>/txt/handoff.md
+#      Record the count. This is the skill doing the work, not a CLI command —
+#      we deliberately do not ship a `peaks memory scan` because the LLM is
+#      the only consumer and the LLM has grep.
+
+# 10b. AskUserQuestion (only if 10a returned count >= 1):
+#      "The TXT handoff has N peaks-memory:start blocks. Persist to .peaks/memory/?
+#       (a) Apply all — `peaks memory extract --project <repo>
+#                            --artifact .peaks/_runtime/<id>/txt/handoff.md --apply --json`
+#       (b) Apply selectively — re-edit handoff.md first, then re-apply
+#       (c) Skip for now — blocks stay in the handoff only, no .peaks/memory/ write"
+#      If 10a returned 0 AND the session surfaced a stable project fact
+#      (decision / convention / approved refactor), STOP — peaks-txt must go
+#      back and embed at least one block before Solo can advance.
+
+# 10c. After the user picks (a) or (b), run:
+peaks memory extract --project <repo> --artifact .peaks/_runtime/<id>/txt/handoff.md --apply --json
+#      --apply is REQUIRED to write .peaks/memory/; without it the command only
+#      previews. The extract regenerates index.json in the same call.
+
+# 11. Peaks-Cli Final snapshot
+peaks project dashboard --project <repo> --json
+peaks skill doctor --json
+```
+
+Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.