peaks-cli 1.3.7 → 1.3.9

package/skills/peaks-solo/references/anchoring-and-session-info.md

@@ -0,0 +1,25 @@
+# Step 0 — Anchor the workflow
+
+> Body of `### Peaks-Cli Step 0: Anchor the workflow`. The instant Peaks-Cli Solo is invoked, **before** the mode-selection question, before any analysis, and before you decide whether the request "needs" the full pipeline, you MUST run these two commands and see their output:
+
+```bash
+# Session ID is auto-generated when omitted; the command returns it in the JSON output.
+# Do NOT pass --session-id manually — the CLI is the single source of truth for the
+# project session binding. To look up the active session id from a skill / sub-agent,
+# use `peaks session info --active --json` (read-only, no side effects). To avoid
+# the "two sessions in .peaks/" confusion that bites Solo, always omit --session-id
+# here and let the CLI auto-generate.
+peaks workspace init --project <repo> --json
+peaks skill presence:set peaks-solo --project <repo> --gate startup
+```
+
+> `<repo>` is the **git project root** (the directory containing `.git`). In a monorepo / single-repo-multi-package layout, this is the repo root, NOT a sub-package — `.peaks/` lives at the repo root so every package shares one workspace. If unsure, run `git rev-parse --show-toplevel` and use that path. Never let `.peaks/` land inside a sub-package directory.
+
+**There is no request too lightweight to skip this.** "分析下这个项目", "看一下代码", "分析项目", "解释一下架构", a one-line question — all of them still create the workspace and set presence first. The workspace is cheap; a missing `.peaks/` is the #1 reported failure.
+
+**Anti-bail-out rule (BLOCKING):** You MUST NOT exit the peaks-solo workflow, hand control back, or produce a final answer before Step 0 has run. If you catch yourself thinking "this is just analysis, I don't need the workflow" — STOP. Run Step 0, set presence, then continue. A pure-analysis request runs the **lightweight analysis branch** (project scan + standards dry-run + handoff with a Standards-increment section), but it still anchors the workspace and keeps presence active. Declining to anchor is a workflow violation.
+
+**Session conflict resolution (read once, internalise):** If `peaks workspace init` returns `code: "CONFLICTING_SESSION"` with a body like
+`{"existingSessionId":"<Y>","requestedSessionId":"<X>"}`, the project is already bound to a different in-flight session `<Y>` (the one you or a prior run was working on). The fix is **NOT** to pass `--allow-session-rebind` to clobber `<Y>` — that destroys an active session's data. Instead: finish or abandon `<Y>` first (use `peaks session list --json` to see what it is, then `peaks session finish --id <Y>` or `peaks session abandon --id <Y>` — see your session command's help for the exact verbs). Only after `<Y>` is closed should you re-run `peaks workspace init`. The same rule applies to `peaks workspace init --session-id "<manually-forged>"` — do not pre-forge session ids; the CLI's auto-generated value is the binding.
+
+`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.

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

@@ -0,0 +1,21 @@
+# Boundaries
+
+> Body of `## Boundaries`. Peaks-Cli Solo may:
+
+- identify scenarios such as refactor, bugfix, QA hardening, release validation, and incident response;
+- recommend Solo, Assisted, Swarm, or Strict profiles;
+- coordinate Peaks-Cli role skills through artifacts;
+- coordinate project memory extraction from stable skill artifact sections;
+- request user confirmation at risk and commit boundaries;
+- read CLI doctor/profile/artifact reports.
+
+Peaks-Cli Solo must not silently:
+
+- install hooks;
+- create agents;
+- enable MCP servers;
+- modify Claude settings;
+- create GitHub repositories;
+- bypass role-skill artifacts.
+
+Use the Peaks-Cli CLI for runtime side effects.

package/skills/peaks-solo/references/codegraph-orchestration.md

@@ -0,0 +1,5 @@
+# Codegraph orchestration context
+
+> Body of `## Codegraph orchestration context`. Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Solo must not treat codegraph output as approval for scope, design, or QA verdict.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks-Cli gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.

package/skills/peaks-solo/references/completion-handoff.md

@@ -0,0 +1,16 @@
+# Completion handoff
+
+> Body of `## Peaks-Cli Completion handoff` + `### Workflow completion (no auto-exit)`.
+
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Merge scan-backed changes incrementally; preserve hand-maintained content unless user confirms deletion.
+
+Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas (`CLAUDE.md` and `.claude/rules/**` statuses), open questions, next action. Do not restate the full workflow log.
+
+## Workflow completion (no auto-exit)
+
+Do NOT call `peaks skill presence:clear --project <repo>` at workflow end. The presence file and header remain active so the user stays inside the workflow context. The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo`. The header continues to display the active skill and current gate.
+
+Before ending, extract durable memories from this session:
+```bash
+peaks project memories:extract --session-id <session-id> --project <repo> --json
+```

package/skills/peaks-solo/references/context-governance.md

@@ -142,3 +142,54 @@ PROTOCOL (mandatory):
 
 - AC-38..AC-43 (G7) + AC-44..AC-46 (G7.7) + AC-47..AC-49 (G8) + AC-50..AC-65 (G9)
 - See PRD §Acceptance criteria.
+
+---
+
+### G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
+
+> Body of `### G7`. Sub-agent artifacts (rd/tech-doc.md, qa/test-cases/<rid>.md, ui/design-draft.md) MUST NOT be inlined into dispatch records and fed back to the main LLM during reduce.
+
+- Sub-agent writes artifact to disk at a known path (path convention: `.peaks/_sub_agents/<sessionId>/artifacts/<rid>-<role>-<idx>.<ext>`).
+- Sub-agent calls `peaks sub-agent dispatch --write-artifact <path>` (or via dispatch CLI flag). The CLI computes sha256 + size + writes `ArtifactMeta` to record.
+- Main LLM reduces the batch and sees ONLY the metadata view (~200 chars per sub-agent, vs ~1MB if content were inlined) — a 3000-5000× reduction.
+- Main LLM decides whether to `Read <path>` for full content (LLM tool call, NOT via peaks CLI).
+
+Main LLM view format (G7.4.e):
+```
+[peaks-solo] batch 3/3 done in 47.3s
+- rd → .peaks/_sub_agents/2026-06-06-session-5b1095/artifacts/003-rd-001.md (12KB, sha256:abc123) summary: "wrote RD tech-doc with 4 sub-roles"
+- qa-business → .../artifacts/003-qa-business-001.md (8KB, sha256:def456) summary: "wrote 12 API test cases"
+- qa-perf → .../artifacts/003-qa-perf-001.md (5KB, sha256:ghi789) summary: "p95 latency target ≤ 200ms"
+```
+
+### G7.7 — headroom-ai integration (opt-in compression)
+
+> Body of `### G7.7`. If a sub-agent prompt is too large even after G7 metadata-only (e.g. 1MB artifact description, 5MB mid-prompt analysis), use `--use-headroom`:
+- Default `false` (G7 remains default).
+- Modes: `balanced` (default) | `aggressive` | `conservative`.
+- Failure: `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback (NOT blocking).
+
+### G8 — cross sub-agent shared channel (dispatcher-mediated indirect signal)
+
+> Body of `### G8`. Sub-agent A's completion **immediately** writes a shared entry; sub-agent B (still in flight) can read shared entries from sibling sub-agents. **This is NOT peer-to-peer messaging.** The dispatcher stores, the sub-agents read/write; A and B never directly talk.
+
+- Path: `.peaks/_sub_agents/<sessionId>/shared/<batchId>.json`.
+- Two new CLI atoms (NO new top-level CLI): `peaks sub-agent share` + `peaks sub-agent shared-read`.
+- RL-23 strong constraint: when sub-agent calls `peaks sub-agent heartbeat --status done`, it MUST also call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`.
+
+### G9 — forced compression gate (CLI 兜底 + hook double-guard)
+
+> Body of `### G9`. Threshold table (256K default context capacity):
+
+| Threshold | Prompt size | Behavior |
+|---|---|---|
+| 50% (early warn) | ≥ 128KB | Soft warning, suggest `--use-headroom` |
+| **75% (user red line)** | ≥ 192KB | Soft warn + `warnings: ["CONTEXT_NEAR_LIMIT"]` |
+| **80% (hard reject)** | ≥ 204KB | Hard reject `code: "PROMPT_TOO_LARGE"`; `--force` allowed at CLI |
+| 90% (emergency) | ≥ 230KB | Hard reject + `contextWarning: 'high'` |
+
+Two layers:
+- **CLI 兜底** — `peaks sub-agent dispatch` validates prompt size; `--force` allowed.
+- **PreToolUse hook** — `peaks sub-agent-dispatch-guard` re-validates; **NO `--force`** at hook layer (RL-30 strict).
+
+The sub-agent prompt template (G8.6 + G9 self-check) is in `references/context-governance.md`.

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

@@ -0,0 +1,17 @@
+# External references and lifecycle
+
+> Body of `## Peaks-Cli External references and lifecycle`.
+
+**Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
+
+Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Solo must not treat codegraph output as approval for scope, design, or QA verdict.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks-Cli gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.
+
+**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery via `peaks capabilities` before naming, references only (no execute/install/persist), Peaks-Cli CLI for all side effects. Do not execute upstream installers, do not install upstream resources, do not persist sensitive examples — Peaks-Cli gates remain authoritative. External skills inform, they do not approve.
+
+**OpenSpec lifecycle**: `render → validate → show → to-rd → validate → archive`. Solo's default runbook handles the exit gate (validate → archive after QA pass). Entry-gate validation (to-rd before slicing) is available when `openspec/` exists pre-workflow; Solo delegates it to `peaks-rd` during implementation.
+
+**MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
+
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`. For an informational mapping of peaks artefact paths to the A2A (Agent2Agent) protocol's Task / Artifact / Part / Message / AgentCard vocabulary (no A2A implementation, just a shared naming layer), see `references/a2a-artifact-mapping.md`.

package/skills/peaks-solo/references/frontend-only-mode.md

@@ -0,0 +1,87 @@
+# Peaks-Cli Frontend-only development mode
+
+> 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 Frontend-only development mode section that was previously inline; nothing was paraphrased, just relocated.
+
+When the project has no live backend (no swagger.json, no API server), Solo must activate frontend-only mode.
+
+### Mode determination (deterministic — CLI is the source of truth)
+
+The CLI decision is authoritative. Read `frontendOnly` and `frontendOnlyReason` directly from the `peaks scan archetype --json` output and copy both into `project-scan.md` under `## Project mode`. Do NOT re-derive the decision from user phrasing.
+
+User-stated intent is **only** consulted when it conflicts with the CLI result. The two conflict cases:
+
+- **CLI says `frontendOnly=false` but the user says "前端项目 / 没有后端 / 先 mock 数据"**: STOP and `AskUserQuestion` to confirm whether to override the scan (the repo probably contains a backend folder the user wants to ignore). Record the override decision and reason in `project-scan.md`.
+- **CLI says `frontendOnly=true` but the user says "需要做后端 / 加 API"**: STOP and `AskUserQuestion` to confirm whether the request actually targets the missing backend (the user may be confused about repo scope, or there is a separate backend repo Solo should switch to).
+
+When there is no conflict, do not ask — the CLI value wins and the workflow proceeds.
+
+### Mock data strategy selection
+
+Solo records the chosen mock strategy in `.peaks/_runtime/<sessionId>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
+
+| Project data-fetching pattern | Recommended mock approach | Rationale |
+|---|---|---|
+| Umi + `umi-request` / `@umijs/plugins` request | Umi mock directory (`mock/*.ts`) | Built-in, zero-config, auto-reload on file change |
+| `@tanstack/react-query` + custom fetcher | Service-layer mock with `Promise.resolve()` stubs in the service file | Keeps query hooks unchanged; swap fetcher target later |
+| `ahooks` `useRequest` + service functions | Service-layer mock: replace HTTP call with `Promise.resolve(mockData)` | Matches existing service-function pattern |
+| MSW (Mock Service Worker) already configured | Add new handlers to existing MSW setup | Consistent with project convention |
+| No existing pattern (greenfield) | Service-layer mock with a `mock/` directory and typed fixture files | Clean separation, easy to delete later |
+| Existing `src/services/*` but no fetcher abstraction | Inline mock inside the service file; preserve the function signature | Keeps existing call-sites unchanged |
+| Mixed data-fetching styles (e.g. react-query + raw fetch in legacy files) | Match the style of the most recently added code in the same module | Avoid introducing a third style |
+| Cannot decide from scan alone | STOP and `AskUserQuestion` | Asking once beats picking differently on every run |
+
+**Mock data rules:**
+
+1. Every mock response must match the shape of the expected real API response. Define a TypeScript interface for the response type first, then create mock data that satisfies it.
+2. Mock data should be realistic (not `"test"`, `"foo"`, `123`) — use plausible Chinese/English content that resembles production data.
+3. Each mock must export its TypeScript interface so RD implementation and QA test-cases can import the same types.
+4. Mark every mock file with a header comment: `// MOCK: Replace with real API call when swagger.json is available`.
+5. Before producing any mock file, register the plan in `.peaks/_runtime/<sessionId>/rd/mock-plan.md` with: chosen strategy (from the table above), planned file paths, and a one-line rationale per file. This file is the source of truth for mock locations across runs — RD must read it before writing code, QA must read it before writing test cases.
+
+### API contract placeholder pattern
+
+When no swagger.json exists, RD defines API contracts as TypeScript interfaces with a mock-then-real service layer:
+
+```
+src/services/types/<feature>-api.types.ts   ← API request/response interfaces
+src/services/<feature>-service.ts          ← Service functions (mock → real)
+mock/<feature>-mock.ts                     ← Mock data satisfying interfaces
+```
+
+Each service function returns a typed mock response marked with `// MOCK: Replace with real API call when swagger.json is available`.
+
+### Mock-to-real migration path
+
+When swagger.json becomes available later, the migration follows this sequence:
+
+1. Generate typed API client from swagger.json (e.g. via `openapi-typescript` or manual mapping).
+2. Replace mock imports with generated API calls, one service file at a time.
+3. Remove corresponding mock files.
+4. Run QA regression to verify the real API responses match the mock interface contracts.
+
+Solo records the migration readiness in the TXT handoff capsule under a `## API Migration` section listing: mock file paths, the corresponding swagger endpoints (when known), and the migration status for each.
+
+### Feishu document access fallback
+
+When the PRD source is a Feishu/Lark document that requires authentication:
+
+1. **Primary path**: Playwright MCP headed browser → user completes login → Solo reads document content via `browser_snapshot`.
+2. **Fallback A (user cannot login)**: Ask user to copy-paste the document content or export as Markdown/PDF. Solo creates the PRD artifact from the pasted content.
+3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/_runtime/<sessionId>/prd/source/`. Solo reads and processes it.
+4. **Fallback C (none of the above)**: Mark PRD as `blocked` with reason `doc-inaccessible`, list the exact next steps for the user, and pause the workflow.
+
+Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
+
+---
+
+### Frontend-only trigger pre-flight
+
+> Body of `### Frontend-only trigger pre-flight`. Before computing the swarm plan, Solo runs the keyword scan deterministically:
+
+1. Read `.peaks/_runtime/<sessionId>/prd/requests/<rid>.md` body.
+2. Lowercase + strip markdown; check regex `\b(页面|组件|表单|弹窗|表格|样式|布局|交互|UI|UX|page|component|form|modal|table|styling|layout|interaction|frontend|前端)\b`.
+3. If match count ≥ 1 → `frontendKeywordHit=true`.
+4. If `frontendOnly` (from project-scan) is `true` and no keyword hit → UI joins anyway (frontend-only project, even non-visual changes may need visual sanity for regressions).
+5. If `frontendOnly` is `false` and no keyword hit → UI skipped.
+
+Solo records the pre-flight result in `sc/swarm-plan.json` so the audit trail shows why UI was or was not included.

package/skills/peaks-solo/references/gstack-integration.md

@@ -0,0 +1,7 @@
+# Peaks-Cli GStack integration
+
+> Body of `## Peaks-Cli GStack integration`.
+
+Map gstack stages to Peaks-Cli role artifacts; preserve Peaks-Cli confirmation gates. Do not delegate orchestration to gstack commands.
+
+For frontend workflows, RD and QA must use Playwright MCP for real browser E2E. The consuming LLM detects the MCP from its own tool list: any Playwright MCP entry in the LLM tool list means the MCP is installed; absent means the user needs to install (`claude mcp add playwright -- npx @playwright/mcp@latest` in Claude Code; other IDEs have their own MCP install path). The LLM invokes the tool directly (browser_navigate / browser_click / browser_snapshot / browser_take_screenshot / browser_console_messages / browser_network_requests / browser_close) by name — there is no peaks-cli indirection. Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.

package/skills/peaks-solo/references/local-artifact-workspace.md

@@ -0,0 +1,79 @@
+# Local intermediate artifact workspace
+
+> Body of `## Peaks-Cli Local intermediate artifact workspace` plus all sub-sections (workspace initialization gate, root pollution prohibition, git and sync policy).
+
+## Workspace initialization gate
+
+The workspace is created in Step 0 (Startup sequence) as a mandatory first action — before any analysis, role handoff, or artifact write, and regardless of how lightweight the request is. Session IDs are now **auto-generated** with the format `YYYY-MM-DD-session-<6位hex>` (e.g. `2026-05-26-session-a3f8b1`). The user does not provide a session ID — the system creates and persists it in `.peaks/_runtime/session.json` (the canonical home as of slice `2026-06-05-peaks-runtime-layer`; the legacy `.peaks/.session.json` is read-only back-compat for one minor release).
+
+When `peaks workspace init` is run without `--session-id`, it automatically generates a new session ID using today's date and a random hex suffix. If a valid session binding exists at `.peaks/_runtime/session.json` (the canonical home, slice 2026-06-05-peaks-runtime-layer; the legacy `.peaks/.session.json` is read-only back-compat for one minor release), the existing session is reused. To read the active session id from a skill or sub-agent, use the `peaks session info --active --json` primitive — never `cat` the on-disk file directly (the path is internal).
+
+**Existing old-session cleanup**: If `.peaks/` contains numeric-only or generic session directories from prior runs (e.g. `2026-05-25-auth-system`), create the new correctly-named session, migrate any reusable artifacts into it, and note the migration in the TXT handoff. Delete empty old-session directories.
+
+```bash
+peaks workspace init --project <repo> --json
+```
+
+The workspace initialization creates this structure under `.peaks/`:
+
+```
+# Canonical home for all per-project ephemeral state (active-skill
+# marker, session binding, sop-state). All writes go here; reads also
+# tolerate the legacy paths (`.peaks/.active-skill.json`,
+# `.peaks/.session.json` — read-only back-compat for one minor release,
+# `.peaks/sop-state/`) for one minor release so a fresh upgrade does
+# not break in-flight workflows. Older trees are auto-migrated by
+# `peaks workspace reconcile --apply`. Skills and sub-agents MUST
+# NOT `cat` any of these files directly — use `peaks session info
+# --active --json` (and the matching read-only primitives for the
+# other two) to discover session-id / active-skill / sop-state.
+.peaks/_runtime/
+├── active-skill.json   # orchestrator presence marker (peaks-solo / -rd / -qa / -ui / -sc / -sop / -txt)
+├── session.json        # project → session binding (the only single-session source of truth)
+└── sop-state/          # current phase + history; definitions live globally in ~/.peaks
+
+# Per-slice artifact dirs (auto-generated, one per session). Files
+# inside ARE tracked by the 提交中间产物 convention.
+.peaks/_runtime/<sessionId>/
+prd/source/      # PRD source documents (Feishu exports, pasted content)
+prd/requests/    # PRD request artifacts (goals, non-goals, acceptance, frontend delta)
+ui/requests/     # UI request artifacts (visual direction, taste reports)
+rd/requests/     # RD request artifacts (slice specs, coverage, CR findings)
+rd/project-scan.md  # Project scan (session-scoped singleton, generated once per session)
+qa/test-cases/   # QA test cases
+qa/test-reports/ # QA test reports (regression matrices, browser evidence)
+qa/requests/     # QA request artifacts
+sc/              # SC artifacts (change-control, impact, retention, boundary)
+txt/             # TXT artifacts (handoff capsules, lessons, memory extraction)
+system/          # Existing-system extraction output (visual tokens, conventions)
+```
+
+Files written into these directories during the workflow (not pre-created — they appear as their step runs):
+
+- `rd/project-scan.md` (Solo step 0.6)
+- `rd/tech-doc.md` (feature/refactor planning; required by `rd → implemented` gate)
+- `rd/bug-analysis.md` (bugfix planning; required by `rd → implemented` gate for `--type bugfix`)
+- `rd/code-review.md`, `rd/security-review.md` (required by `rd → qa-handoff` gate for feature/bugfix/refactor; security-review only for config)
+- `rd/mock-plan.md` (frontend-only mode)
+- `ui/design-draft.md` (UI step)
+- `system/existing-system.md` (Solo step 0.7; legacy projects only)
+- `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md` (gated per `--type`)
+
+## Root pollution prohibition (CRITICAL)
+
+**NEVER write Peaks-Cli intermediate artifacts to the project root directory.** Specifically prohibited at root level:
+
+- PRD snapshots, document extracts, or requirement notes (`feishu-doc-*.md`, `*-snapshot.md`, etc.)
+- RD tech docs, scan reports, slice specs, or architecture notes
+- QA screenshots, browser evidence, test reports, or validation logs (`.png`, `.jpg`)
+- QA test helper files, mock servers, or fixture scripts (`qa-server.js`, etc.)
+- UI design drafts, taste reports, or visual direction notes
+- TXT handoff capsules or lesson files
+
+Legitimate source files (e.g. `jest-setup.ts`, `tailwind.config.js`) belong at root — do not move them.
+
+If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/_runtime/<sessionId>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/_runtime/<sessionId>/` and note the migration in the TXT handoff.
+
+## Git and sync policy
+
+Do not default to git-backed storage or automatic commits for intermediate artifacts. Git inclusion or sync requires explicit user confirmation or an active profile that authorizes it.

package/skills/peaks-solo/references/micro-cycle.md

@@ -155,3 +155,71 @@ verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
 - peaks-qa 接管 = 边界 + `verdict != pass` 时的下一轮
 
 完整流程见 SKILL.md。
+
+---
+
+# Mandatory RD QA repair loop (AUTO-PROCEED)
+
+> Body of `## Peaks-Cli Mandatory RD QA repair loop`.
+
+> **CLI gate enforcement**: `peaks request transition` now refuses to move RD/QA to gated states when required artifacts are missing. The required files depend on `--type` chosen at `peaks request init` (default `feature`):
+>
+> - `feature` / `refactor`: full gates (tech-doc, code-review, security-review, test-cases, test-report, security-findings, performance-findings)
+> - `bugfix`: lighter planning (`bug-analysis.md` instead of `tech-doc.md`); still requires code-review + security-review + regression test-cases + security-findings; performance-findings optional unless the bug is performance-related
+> - `config`: only security-review (RD) and security-findings (QA)
+> - `docs` / `chore`: no gates
+>
+> When PRD lands, classify the request type before running `peaks request init` for every role — pass `--type <type>` so the artifact records it and downstream transitions enforce the right gates. Misclassifying a feature as `docs` to skip gates is a workflow violation. If a transition fails with `code: PREREQUISITES_MISSING`, the response lists every missing path — produce them, then re-transition. For one-off exceptions, the escape hatch `--allow-incomplete --reason "<text>"` records the bypass in the artifact transition note.
+
+After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks-Cli Solo MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Solo must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
+
+**How Solo invokes another role (mechanism, not metaphor):**
+
+Solo is itself a skill running in the current session. There are **two distinct mechanisms** in this skill, and they MUST NOT be confused:
+
+1. **Swarm fan-out (planning side, after PRD confirmed)** — uses `peaks sub-agent dispatch <role>` to launch real concurrent sub-agents. The CLI returns a per-IDE tool-call descriptor that the LLM executes in its environment. See "Peaks-Cli Swarm parallel phase" above for the full contract. Sub-agents do NOT call Skill(...) back into the role; they execute the role's instructions inline from the prompt.
+2. **Sequential handoff (execution side, RD↔QA repair loop)** — Solo is the only loop, and after RD or QA finishes (whether as a sub-agent or directly), Solo drives the next step from the orchestrator seat. Do NOT use the `Skill` tool to "reactivate" peaks-rd or peaks-qa in the main loop; doing so is the v1.x anti-pattern that masqueraded as "calling the role" but actually just re-prompted the same session. From v1.3 onward, the main loop drives roles via the CLI gate (`peaks request transition`) and reads back artefacts (`peaks request show ... --json`); the actual RD/QA work is either done inline by Solo (when Solo has just been re-invoked by the user) or by a Task sub-agent (in swarm mode).
+
+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
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <current-gate>
+```
+
+This keeps the CLAUDE.md status header accurate (`Peaks-Cli Skill: peaks-solo`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last-known gate permanently.
+
+**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately drives QA — by launching a `peaks sub-agent dispatch qa` sub-agent carrying the `peaks-qa` body (swarm path), then executing the returned toolCall, or by running QA inline in the main loop (assisted/strict path). Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
+
+A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
+
+**How Solo routes QA findings back to RD (mechanism, not metaphor):**
+
+When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite RD artifacts. Instead it follows this exact sequence:
+
+1. Read the QA verdict and findings via `peaks request show <rid> --role qa --project <repo> --json`. The findings live in the QA artifact body (failing acceptance items, evidence paths, severity).
+2. Transition the RD artifact back from `qa-handoff` to a working state and record the QA verdict in the transition note:
+   ```bash
+   peaks request transition <rid> --role rd --state spec-locked \
+     --reason "QA return-to-rd cycle <N>: <one-line summary of failing items; full findings in qa/test-reports/<rid>.md>" \
+     --project <repo> --json
+   ```
+   `spec-locked` is the canonical "needs more RD work" state. The reason is mandatory in repair cycles so the artifact history shows the loop.
+3. Re-launch `peaks-rd` work. Two paths, mode-driven:
+   - **Swarm / full-auto**: launch a fresh `peaks sub-agent dispatch rd` sub-agent (then execute the returned toolCall) with the same `peaks-rd` body used in the Swarm phase, plus the QA findings path so it can read the failure list. Solo restores presence after the sub-agent returns.
+   - **Assisted / strict / inline-fallback**: Solo executes the RD repair steps directly in the main loop, since there is no concurrent fan-out to coordinate.
+   In both paths, pass the QA findings path so the repair sees what failed.
+4. peaks-rd fixes the reported issues only (red-line scope: do not modify unrelated surfaces), regenerates code-review and security-review evidence if changes touched reviewed surfaces, then transitions `rd → implemented → qa-handoff` again.
+5. Solo re-runs QA (sub-agent Task in swarm/full-auto, inline in assisted/strict) with the same `<request-id>`. QA re-runs gates against the new diff.
+6. Repeat steps 1-5 until QA returns `verdict=pass`, or the cap below fires.
+   **After each repair iteration** (after peaks-rd and peaks-qa both return), Solo MUST restore presence:
+   ```bash
+   peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate repair-cycle-<N>
+   ```
+
+**Repair cycle cap**: After 3 repair cycles without a passing QA verdict, emit a blocked TXT handoff regardless of remaining issues. Do not loop indefinitely. If a specific issue cannot be resolved within 3 cycles, mark it as a known blocker in the TXT handoff and proceed to the SC phase.
+
+In full-auto mode, treat the RD↔QA repair loop as a built-in controller objective: loop through RD→QA until all acceptance items pass (max 3 cycles). Do not exit the loop on a non-passing QA verdict unless the TXT handoff marks the workflow as blocked.

package/skills/peaks-solo/references/mode-selection.md

@@ -0,0 +1,21 @@
+# Step 1 — Mode selection
+
+> Body of `### Peaks-Cli Step 1`. 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:
+
+1. **Full auto (Recommended)** — Peaks-Cli handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
+2. **Assisted** — Peaks-Cli proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
+3. **Swarm** — Peaks-Cli maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
+4. **Strict** — Peaks-Cli uses the most conservative gates: explicit confirmations, strict slice specs, coverage evidence, QA acceptance, and commit boundaries before continuing.
+
+Map the user's selection to the `--mode` flag value (used by `peaks skill presence:set`; `presence:set --mode` accepts any string, so the name matches the user-facing label rather than overloading "solo" which is also the skill name):
+
+| User selects | `--mode` value |
+|---|---|
+| Full auto | `full-auto` |
+| Assisted | `assisted` |
+| Swarm | `swarm` |
+| Strict | `strict` |
+
+> Note: `peaks workflow route --mode solo|team` is a **different** CLI dimension (solo developer vs team flow) and is unrelated to the profile choice here. Do not conflate them.
+
+If the user already names a profile in their invocation (e.g. `/peaks-solo --full-auto`, "用全自动模式"), skip this question and use the named profile directly.

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

@@ -36,3 +36,46 @@ If the consuming LLM needs an MCP server for docs lookup or research (e.g. Conte
 ## Boundary
 
 Solo must not write `openspec/changes/**` or `~/.claude/settings.json` directly. Every mutation goes through the CLI commands above. The CLI returns stable envelopes; Solo captures them as artifact links rather than re-explaining their content in the handoff.
+
+---
+
+# Step 0.5 — OpenSpec first-run opt-in (conditional)
+
+> Body of `### Peaks-Cli Step 0.5`. After the workspace is anchored, before project scan, Solo checks whether
+the project already has an `openspec/` directory. The lifecycle
+(`render → validate → show → to-rd → validate → archive`) only applies
+when `openspec/` exists; without it, RD/QA/SC silently skip the
+openspec-aware paths and you lose change-proposal tracking, commit
+boundaries from `tasks.md`, and the historical archive.
+
+To make that opt-in visible instead of silent, Solo runs:
+
+```bash
+# 1. Detect whether the project already has openspec/.
+ls <repo>/openspec/changes 2>&1
+# 2. If absent, ask the user once — only on the first Solo run in this
+#    project. The decision is sticky: write it to .peaks/.peaks-openspec-opt-in.json
+#    so subsequent Solo invocations do not re-ask.
+test -f <repo>/.peaks/.peaks-openspec-opt-in.json || \
+  echo "{\"enabled\": <bool>}" > <repo>/.peaks/.peaks-openspec-opt-in.json
+```
+
+**AskUserQuestion** (only when `openspec/` is absent and the opt-in
+file is missing):
+
+| Option | What it does |
+|---|---|
+| Enable OpenSpec for this project (Recommended) | Run `peaks openspec init --project <repo> --apply`. After that, every Solo run uses the change-proposal lifecycle for the same project. |
+| Skip for now | Do nothing. Solo proceeds without openspec; the question is re-asked on the next first-run detection. |
+| Never ask again for this project | Write `{enabled: false, sticky: true}`. Solo stops asking. The user can re-enable later by removing `.peaks/.peaks-openspec-opt-in.json` and re-running. |
+
+The first option is the recommended default because it gives Solo the
+full change-proposal lifecycle (proposal / tasks / design / specs
+deltas, archive on ship, commit boundaries from `tasks.md`). It costs
+only a single scaffolded directory and pays back the first time the
+project needs a real review trail.
+
+If the user picks "Enable", the only required follow-up is to make
+sure `openspec/changes/` is added to git (it is part of the project
+repo, not a tool-managed artefact). Solo does not run `git add` for
+the user; that is the user's commit boundary.

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.