peaks-cli 1.2.7 → 1.2.9

package/skills/peaks-solo/SKILL.md

@@ -131,6 +131,69 @@ peaks skill presence:set peaks-solo --project <repo> --gate startup
 
 `presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.
 
+### Peaks-Cli Step 0.7: Detect unfinished work and offer resume (BLOCKING on first invocation per session)
+
+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
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['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` (added in this slice) asserts: (a) fresh-session classification returns "no resume", (b) in-flight slice classification returns the right gate, (c) the classification is deterministic across two invocations on the same fixture.
+
 ### Peaks-Cli Step 1: Mode selection
 
 After Step 0 has anchored the workspace and presence, when the user invokes Peaks-Cli Solo without explicitly naming an execution profile, use `AskUserQuestion` to pick the profile. Present the recommended full-auto path as the first/default option with a practical description for each:
@@ -185,7 +248,7 @@ This returns durable memories from `.peaks/memory`, grouped by kind:
 - **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>` 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`.
+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.
 
@@ -413,6 +476,11 @@ Grep `src/` for outdated patterns and list them as constraints in `project-scan.
 - 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>
 ```
@@ -489,171 +557,9 @@ When the PRD source is a Feishu/Lark document that requires authentication:
 
 Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
 
-## 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/<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/<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/<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/<id>/rd/project-scan.md
-# Expected output: .peaks/<id>/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/<id>/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/<id>/prd/requests/<rid>.md
-
-# Type-specific RD planning artifact:
-#   feature / refactor → ls .peaks/<id>/rd/tech-doc.md
-#   bugfix             → ls .peaks/<id>/rd/bug-analysis.md
-#   config / docs / chore → (no RD planning artifact required)
-
-# QA test-cases (skipped for docs/chore):
-ls .peaks/<id>/qa/test-cases/<rid>.md
-```
-
-```bash
-# B.info — NON-BLOCKING. Record degradation in TXT, then proceed.
-ls .peaks/<id>/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):**
+## Peaks-Cli Request type classification + Workflow order + Transition verification gates
 
-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.
-
-```bash
-# Always required
-ls .peaks/<id>/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
-#   bugfix             → ls rd/bug-analysis.md rd/code-review.md rd/security-review.md
-#   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/<id>/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/<id>/ -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/<id>/prd/source/
-# (for doc snapshots) or .peaks/<id>/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.
-```
+The full contract for the 6-type classification table, the 11-step workflow order, and the 7 transition verification gates (A through G with their `ls` / `grep` shell snippets) lives in `references/workflow-gates-and-types.md`. The peaks-solo narrative in this SKILL.md references those gate numbers (Gate A through Gate G) — keep both files in lockstep when adding or renaming a gate. The reference file is the canonical contract; SKILL.md keeps the prose.
 
 
 ## Peaks-Cli Swarm parallel phase (sub-agent fan-out, conditional)
@@ -785,6 +691,8 @@ Solo is itself a skill running in the current session. There are **two distinct
 
 After RD completes (whether inline or sub-agent), Solo does not stop — it must advance to QA. There is no "RD done, ask the user" state in full-auto mode. The only valid stops are: (a) QA verdict=pass, (b) repair cap hit, (c) explicit user cancel.
 
+**RD's internal reviews are already parallelized.** When RD finishes implementation, it issues a 3-way sub-agent fan-out (code-review + security-review + perf-baseline, see `skills/peaks-rd/SKILL.md` "Parallel review fan-out") and waits for all to return before transitioning to `qa-handoff`. Solo does NOT need to track three separate RD-side sub-runs; the RD role owns the fan-out lifecycle end-to-end. Solo's presence restoration after the swarm converges is the only coordination point.
+
 **Presence restoration after RD/QA work returns (MANDATORY):** In v1.x, role skills called `peaks skill presence:set <role>` internally and stomped on `.peaks/.active-skill.json`. From v1.3 onward, sub-agents in the Swarm path are forbidden from calling `peaks skill presence:set` (see "Sub-agent dispatch" in each role's SKILL.md), so the main loop's presence file is preserved across the fan-out window by construction. The one place Solo still has to actively restore presence is **once after the fan-out returns** (gate=swarm-converged) and again **after each RD↔QA repair iteration** (gate=repair-cycle-<N>). Use the same command from Step 2 with the current mode and the gate that has just advanced:
 
 ```bash
@@ -827,158 +735,9 @@ In full-auto mode, treat the RD↔QA repair loop as a built-in controller object
 
 ## Default runbook
 
-> **Maintenance**: The numbered workflow list above (steps 0-11) is the canonical phase sequence. This runbook is the executable CLI transcription. When updating this skill, keep both in lockstep — a change to one must be reflected in the other.
+The end-to-end CLI sequence for the `full-auto` profile lives in `references/runbook.md` (extracted from this file to keep SKILL.md under the 800-line cap from `common/coding-style.md`). `assisted` and `strict` profiles pause at `[CONFIRM]` markers in the runbook; `full-auto` and `swarm` auto-proceed through all gates. See Transition Gates for artifact verification at each stage. The numbered workflow list (steps 0-11) earlier in this SKILL.md is the canonical phase sequence; the runbook is the executable CLI transcription — keep both in lockstep when updating.
 
-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.
-
-```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 scan archetype --project <repo> --json
-# → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
-# → if archetype != greenfield AND archetype != unknown:
-peaks scan existing-system --project <repo> --json
-# → copy tokens, sources, conventions, inconsistencies into .peaks/<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 Swarm parallel — sub-agent fan-out (Task tool, NOT Skill tool)
-#    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
-#    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
-#    Task(subagent_type="general-purpose", ...) call per sub-agent in the same message.
-#    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
-#    prompt template; the role's required artefact paths are listed there.
-#    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
-#    the Swarm phase — that's the v1.x anti-pattern.
-#
-# 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 issues N Task(subagent_type="general-purpose", ...) calls in ONE message
-#     (N = len(swarm-plan.subAgents)). Each prompt embeds the role's body minus
-#     Step 0 / presence, plus the runtime args (rid / sid / mode / type / paths).
-# 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/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
-# feature / refactor → ls .peaks/<sid>/rd/tech-doc.md
-# bugfix             → ls .peaks/<sid>/rd/bug-analysis.md
-ls .peaks/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
-# ui (only when in plan):
-ls .peaks/<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/<id>/rd/tech-doc.md
-#    bugfix             → write .peaks/<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/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
-#      - .peaks/<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/<id>/qa/test-cases/<rid>.md
-peaks request transition <rid> --role qa --state running --project <repo> --json
-#      Before qa:verdict-issued → .peaks/<id>/qa/test-reports/<rid>.md
-#                                 + .peaks/<id>/qa/security-findings.md
-#                                 + .peaks/<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
-
-# 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
-#     peaks-txt writes the handoff capsule to .peaks/<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/<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/<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/<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
-```
+Maintenance: when adding new CLI commands to the runbook, mirror them into both `references/runbook.md` and the test in `tests/unit/skill-default-runbook.test.ts` (the test falls back to `references/runbook.md` when the SKILL.md section is a pointer).
 
 Repair loop details: see `## Mandatory RD QA repair loop` above for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.
 
@@ -1031,6 +790,7 @@ These commands harden the workflow against silent skips. Use them in the runbook
 | `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) |
 
 Together with `peaks request transition` (which already CLI-enforces per-type artifact prerequisites), these four commands form the runtime quality net. SKILL.md prose is descriptive; the CLI is what physically blocks bad workflows.
 

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

@@ -0,0 +1,166 @@
+# 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
+
+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.
+
+```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 scan archetype --project <repo> --json
+# → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
+# → copy libraries[] into .peaks/<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/<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 Swarm parallel — sub-agent fan-out (Task tool, NOT Skill tool)
+#    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
+#    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
+#    Task(subagent_type="general-purpose", ...) call per sub-agent in the same message.
+#    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
+#    prompt template; the role's required artefact paths are listed there.
+#    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
+#    the Swarm phase — that's the v1.x anti-pattern.
+#
+# 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 issues N Task(subagent_type="general-purpose", ...) calls in ONE message
+#     (N = len(swarm-plan.subAgents)). Each prompt embeds the role's body minus
+#     Step 0 / presence, plus the runtime args (rid / sid / mode / type / paths).
+# 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/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
+# feature / refactor → ls .peaks/<sid>/rd/tech-doc.md
+# bugfix             → ls .peaks/<sid>/rd/bug-analysis.md
+ls .peaks/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
+# ui (only when in plan):
+ls .peaks/<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/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/<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/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/<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/<id>/qa/test-cases/<rid>.md
+peaks request transition <rid> --role qa --state running --project <repo> --json
+#      Before qa:verdict-issued → .peaks/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/<id>/qa/security-findings.md
+#                                 + .peaks/<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
+
+# 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
+#     peaks-txt writes the handoff capsule to .peaks/<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/<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/<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/<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.