peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -1,136 +0,0 @@
-# Peaks-Loop 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

@@ -1,13 +0,0 @@
-# Quality-gate commands (CLI cheat sheet)
-
-> Body of `## Peaks-Loop 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,63 +0,0 @@
-# Step 0.7 — Detect unfinished work and offer resume
-
-> Body of `### Peaks-Loop 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

@@ -1,249 +0,0 @@
-# Peaks-Loop 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-loop 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-Loop Snapshot + 0.5 Peaks-Loop Workspace + 0.6 Peaks-Loop Project scan + 0.7 Peaks-Loop 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-Loop 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-Loop Gate A.5)
-
-# 1. Peaks-Loop 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-Loop Gate G).
-
-# 2. Peaks-Loop 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-Loop 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-Loop 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-Loop Gate B convergence check. Assisted/Strict: [CONFIRM]
-
-# 4. Peaks-Loop 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-Loop 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-Loop 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-Loop Gate D check. Assisted/Strict: [CONFIRM]
-
-# 7. Peaks-Loop 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-Loop 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-Loop 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-Loop TXT handoff — invoke peaks-txt which embeds memory markers (BLOCKING)
-#     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. Applies to ALL modes including
-#     `assisted` (audit 2026-07-03 found `assisted` previously skipped this step).
-#
-# 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-Loop 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.
-
-```bash
-
-# Peaks-Loop Default runbook — Job path (excerpt; full flow in references/job-loop.md)
-
-# Step 0.8 (BLOCKING): LLM judges Job-shape, CLI records it.
-# This is a RECORDER, not a detector. The LLM supplies --is-job + --rationale;
-# the CLI writes .peaks/_runtime/<sid>/job-shape.json. Downstream steps call
-# `peaks solo read-job-shape` to enforce the decision exists.
-
-# (The LLM does the semantic judgement, e.g.:)
-#   "The user named N=35 parallel app/ subdirs, said 'continue until all done',
-#    and disavowed cost. isJob=true, rationale=..., suggestedJobId=app-ut-batch,
-#    suggestedStrategy=rotating, confidence=high."
-peaks solo detect-job \
-  --is-job true \
-  --rationale "35 parallel app/ subdirs + 'until all done' + '不用考虑费用'" \
-  --suggested-job-id app-ut-batch \
-  --suggested-strategy rotating \
-  --confidence high
-
-# Step 0.81-init: if Job-shaped, init BEFORE Step 1.
-DECISION=$(peaks solo read-job-shape --json)
-if [ "$(echo "$DECISION" | jq -r '.data.decision.isJob')" = "true" ]; then
-  JID=$(echo "$DECISION" | jq -r '.data.decision.suggestedJobId')
-  STRATEGY=$(echo "$DECISION" | jq -r '.data.decision.suggestedStrategy')
-  # LLM-derived slice list (not CLI-derived).
-  peaks job init --job-id "$JID" --slice-list "<LLM_DERIVED>" --main-loop-strategy "$STRATEGY" --rotate-every 3 --json
-fi
-
-# After Step 7 (RD+QA commit) lands AND Step 0.8 fired (state.json exists):
-peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)
-# v3.1.2: `peaks job checkpoint --state done` ALSO writes
-# .peaks/_runtime/<sid>/job/<jid>/progress.json. Read it on resume:
-peaks job progress --job-id <jid> --json
-peaks job status --job-id <jid> --json
-peaks job subagent-cleanup --job-id <jid> --batch-id <bid> --force   # Step 0.87 gate
-# Loop control:
-#   remaining > 0  → return to Step 1 (next slice)
-#   remaining == 0 → Step 8/9/10/11 (original tail)
-#   blocked (strict) → peaks job block + STOP
-# Rotating-mode: every rotateEvery slices → Step 0.86 (peaks session rotate + resume)
-
-# v3.1.2 size-fear ban: refuse to emit a final handoff while remaining > 0.
-# The LLM cannot bypass this; --force-under-job requires explicit user approval.
-peaks solo emit-handoff --project <repo> --job-id <jid> --json
-
-# v3.1.2 forced auto-compact: when --enforce-job-mode is set OR
-# job-shape.json says isJob=true, ≥0.85 is MANDATORY auto-compact.
-# Solo MUST call this without confirmation under Job mode.
-peaks solo context-now --project <repo> --enforce-job-mode --json
-peaks session auto-compact --execute --project <repo> --json
-
-# v3.1.2 PreToolUse gate (installed by `peaks workspace init`):
-# every Bash tool call runs `peaks solo gate-step-08` automatically.
-# Exit 0 = allow (with optional Next: slice #N+1 of M line when
-# progress.json exists). Exit 2 = BLOCKED; LLM must call
-# `peaks solo detect-job` first.
-peaks solo gate-step-08 --project <repo> --json
-```

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

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

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

@@ -1,23 +0,0 @@
-# Project standards preflight
-
-> Body of `## Peaks-Loop Project standards preflight`. Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks-Loop CLI:
-
-- `peaks standards init --project <path> --dry-run`
-- `peaks standards update --project <path> --dry-run`
-
-Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. In `full-auto` and `swarm` profiles, `--apply` runs automatically after `--dry-run` succeeds — these files live inside the target project, are required for downstream skill preflight, and producing them is part of finishing the workflow (Peaks-Loop Gate G enforces this). `assisted` and `strict` profiles pause for explicit user confirmation between dry-run and apply.
-
-**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/_runtime/<sessionId>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
-
-**Legacy projects additionally** — when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}, the `CLAUDE.md` Conventions section MUST extract concrete naming, directory, service-layer, and hooks conventions from `.peaks/_runtime/<sessionId>/system/existing-system.md` and record them as hard constraints for new code. It must also list the `## Legacy constraints` from `project-scan.md` (class components, moment, enzyme, etc.) and instruct that new code in the same module preserves those patterns unless PRD explicitly authorizes modernization. A `CLAUDE.md` for a legacy project that contains only generic rule pointers without naming the actual conventions is a blocking violation — regenerate it.
-
-Do not hand-write standards file mutations inside the skill.
-
-For project-analysis requests such as "分析项目" / "分析下这个项目", Step 0 still applies: the workspace is initialized and `peaks-solo` presence is set before any analysis output. These requests run the lightweight analysis branch (project scan + standards dry-run) rather than the full RD/QA pipeline, but they never skip workspace anchoring or exit the workflow. The handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
-
-- whether `CLAUDE.md` is missing, existing, planned, skipped, appended, or review-only;
-- which `.claude/rules/**` files are planned, existing, skipped, appended, or review-only;
-- whether writes were applied or intentionally left as dry-run because authorization or scope was absent;
-- the exact next action if standards should be applied later.
-
-If the dry-run output lacks enough detail to explain those deltas, say that the standards increment is unknown and keep standards application blocked until another `peaks standards init/update --dry-run` provides evidence.

package/skills/peaks-solo/references/step-0-55-1x-detection.md

@@ -1,82 +0,0 @@
-# Step 0.55 — 1.x → 2.0 detection reference
-
-> Body of `### Peaks-Loop Step 0.55`. Slice: 2026-06-12-solo-step-0-55-1x-detection.
-
-## Why this step exists
-
-The peaks-loop 1.x → 2.0 closeout ships:
-
-1. A postinstall that auto-detects 1.x state and dispatches the upgrade (slice 1, commit `b6e34e6`).
-2. A standards-migrate path that thins `.claude/rules/**/*.md` and scaffolds `.peaks/standards/` (slice 2, commit `33dd392`).
-3. **THIS STEP** — a peaks-solo startup sequence probe that detects 1.x state when the user invokes `/peaks-solo` directly in a 1.x consumer project, and prompts the user to upgrade.
-
-The 1.x user experience is: "I just typed /peaks-solo. Why is it not working in 2.0 mode?" Step 0.55 catches this case and surfaces an `AskUserQuestion` with a one-click upgrade.
-
-## Detection algorithm
-
-```bash
-# 1. Read-only probe via the umbrella CLI
-peaks upgrade --detect-1x --project <root> --json
-```
-
-The CLI returns:
-```json
-{
-  "ok": true,
-  "command": "upgrade.detect-1x",
-  "data": {
-    "isOneX": true,
-    "signals": [
-      "<path> has schema_version 1.0.0, expected '2.0.0'",
-      "..."
-    ],
-    "projectRoot": "/path/to/project",
-    "configPath": null
-  },
-  "warnings": [],
-  "nextActions": [
-    "Detected 1.x state. peaks-solo Step 0.55 should present an AskUserQuestion to invoke `peaks upgrade --to 2.0 --auto --project /path/to/project`."
-  ]
-}
-```
-
-The detection logic mirrors `scripts/install-skills.mjs:detect1xProjectState` (canonical implementation) — it walks up to find `.peaks/_runtime/`, then sniffs:
-
-1. `~/.peaks/config.json` for `version: 1.x`
-2. `<projectRoot>/.claude/rules/common/dev-preference.md` for "peaks progress"
-3. `<projectRoot>/.peaks/preferences.json` for missing or non-`2.0.0` `schema_version`
-
-The TS mirror in `src/services/upgrade/1x-detector-service.ts` is the canonical entrypoint for the skill; the postinstall `.mjs` version is the canonical entrypoint for the npm-install flow. The two implementations MUST stay in parity (a parity test is in the slice's test suite).
-
-## AskUserQuestion (only when `isOneX: true`)
-
-| Option | What it does |
-|---|---|
-| Run `peaks upgrade --to 2.0 --auto --project <root>` (Recommended) | Invokes the umbrella. The user sees the 6 sub-step results in the terminal. After the upgrade, re-run peaks-solo with the standing 2.0 layout. Persist `autoUpgradePrompt: opt-in` to `.peaks/preferences.json`. |
-| Skip for this session | Continue with the standing 1.x layout. Persist `autoUpgradePrompt: skip-this-session` to `.peaks/preferences.json`. The next time the user invokes peaks-solo in this project, the question re-asks. |
-| Never ask again for this project | Persist `autoUpgradePrompt: skip-forever` to `.peaks/preferences.json`. Step 0.55 becomes a no-op for this project from now on. The user can re-enable later by removing the `autoUpgradePrompt` key from preferences.json. |
-
-## Persistence contract
-
-The decision is persisted via `peaks preferences set --project <root> --key autoUpgradePrompt --value <opt-in|skip-this-session|skip-forever> --apply`. Subsequent Step 0.55 invocations read the value first:
-
-- If `opt-in` (and Step 0.55 is the first invocation in the session), the user has already opted in; auto-run the umbrella without re-asking.
-- If `skip-this-session`, the user already said no this session; skip without re-asking (but re-ask next session).
-- If `skip-forever`, the user said no permanently; skip without re-asking.
-- If the key is absent, present the AskUserQuestion.
-
-## What is NOT in this step
-
-- The auto-upgrade execution itself: the umbrella is invoked via the AskUserQuestion's recommended option. The umbrella's behavior (6 sub-commands + write-upgrade-record) is documented in the umbrella's own help text.
-- The postinstall auto-dispatch: that's `scripts/install-skills.mjs:autoUpgrade1xProjectIfPresent`, which fires fire-and-forget on `npm i -g peaks-loop@2.0`. Step 0.55 is the user-invoked path.
-- Re-authoring the 1.x detector heuristics: the implementation is a 1:1 mirror of the canonical `.mjs` version. Drift is prevented by the parity test.
-
-## How this integrates with the rest of the workflow
-
-- Step 0.5 (OpenSpec opt-in) — runs first if `openspec/` is missing.
-- Step 0 (anchor) — runs always.
-- Step 0.7 (resume detection) — runs after Step 0.
-- **Step 0.55 (1.x detection) — runs after Step 0.7, only when the project is not on a 2.0 layout.**
-- Step 1 (mode selection) — runs after Step 0.55.
-
-The 1.x detection is intentionally placed AFTER Step 0.7 because the user might already have a 1.x-converted in-flight slice; the resume flow takes precedence over the upgrade prompt.