peaks-loop 3.0.0

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

@@ -0,0 +1,316 @@
+# RD micro-cycle (TDD 小步快测)
+
+> 参考 TDD 模式的红绿循环。设计目标：把 1 行 bug fix 的反馈循环从
+> ~30s（全 suite + verify-pipeline）压到 ~100ms（单测 + 心算）。
+
+## 什么时候用 micro-cycle
+
+- 在 **RD 实现** 阶段，**slice 内部** 做小修复 / refactor / lint fix / 微调时
+- 节奏：5-10 秒一个 micro-cycle
+
+## 什么时候**不**用 micro-cycle
+
+- slice 边界（一个 RD 任务结束 / 用户说 ship / 一个 logical change 整体完成）→ 走 `peaks slice check`
+- 新增 slice / 跨模块 refactor / 依赖升级 → 直接走 peaks-rd 主流程
+- `--type docs` / `--type chore` → 没有 acceptance 表面，micro-cycle 不适用
+
+## The cycle (硬约束顺序)
+
+### 1. RED — 写/改一个 unit test 反映 bug
+
+```bash
+vim tests/unit/<file>.test.ts  # 加 1 个 test 反映 bug
+```
+
+约束：**先写测试，再写实现**。LLM 写完实现再补 test 属于反向 TDD，等同于 skip micro-cycle。
+
+### 2. 跑这一个 test（确认 red）
+
+```bash
+npx vitest run tests/unit/<file>.test.ts \
+  -t "<new test name>" \
+  --no-coverage
+```
+
+预期：test FAIL。**如果已经 pass → 你的测试没反映 bug，回去重写**。
+
+### 3. GREEN — 修实现
+
+```bash
+vim src/<file>.ts
+```
+
+约束：**minimal change**，不要顺手"改进"无关代码。
+
+### 4. 跑这一个 test（确认 green）
+
+```bash
+npx vitest run tests/unit/<file>.test.ts \
+  -t "<new test name>" \
+  --no-coverage
+```
+
+预期：test PASS。**如果还 FAIL → 你的实现不对，回去修**。
+
+### 5. 局部回扫 — 跑同 file 的所有 test
+
+```bash
+npx vitest run tests/unit/<file>.test.ts --no-coverage
+```
+
+目的：防"改一处坏一处"。比全 suite 快 10-50×。
+
+### 6. 写一个 commit message（先不 commit）
+
+```bash
+git add -p
+# commit message: [micro-cycle] <slice-id>: <one-line summary>
+```
+
+## micro-cycle 内**禁止**触发
+
+| 命令 | 理由 |
+|---|---|
+| `npx vitest run`（无 filter）| 30s+，micro-cycle 内禁止 |
+| `npx tsc --noEmit` | 边界点才跑 |
+| `peaks workflow verify-pipeline` | 边界点才跑 |
+| 3-way fan-out（code-review / security-review / perf-baseline）| 边界点 + RD-internal 才跑 |
+| `peaks request transition <rid> --state qa-handoff` | micro-cycle 内**不切 slice 状态** |
+
+**违反任何一条 = workflow violation**（slice 边界才能跑全套）。
+
+## 边界 check（slice 结束）
+
+当一个 slice 内的所有 micro-cycle 都 green 且用户/agent 准备进入 peaks-qa 时，**必须**跑：
+
+```bash
+peaks slice check [--rid <rid>] [--project <path>] [--json]
+```
+
+这个命令编排：
+1. `npx tsc --noEmit`（typecheck）
+2. `npx vitest run --changed`（默认；changed-only suite，只跑 git 改动相关的 test，~1-3s）。要全量请加 `--run-tests`；要彻底跳过请加 `--skip-tests`。
+3. 3-way fan-out（code-review + security-review + perf-baseline）
+4. `peaks workflow verify-pipeline --rid <rid> --project <path>`
+
+4 个 check 全绿 + verify-pipeline pass → 才进 `peaks request transition --state qa-handoff`，让 peaks-qa 接管。
+
+> **新增 run 017（2026-06-09）**：边界默认走 changed-only suite，原来的全 suite 行为移到 `--run-tests` opt-in。`peaks-solo-test` skill 仍然是手动跑全量的入口。rationale: 全量 30s+ 严重拖慢 workflow；changed-only 命中 99% 真正回归。详见 PRD `.peaks/_runtime/2026-06-07-session-84feb7/prd/requests/002-017-2026-06-09-remove-auto-full-vitest-from-slice-check.md`。
+
+## Micro-cycle → 边界 check → QA 的串联
+
+```
+peaks-rd 启动一个 slice
+  ↓
+  bug 1 → micro-cycle (红绿, ~10s)
+  bug 2 → micro-cycle
+  bug 3 → micro-cycle
+  ...
+  ↓ 全部 green
+peaks slice check  # 4 项检查全绿
+  ↓
+peaks request transition --state qa-handoff
+  ↓
+peaks-qa 接管 (full gate machinery)
+  ↓
+verdict=pass → SC + TXT → handoff
+verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
+```
+
+## Anti-patterns（明确禁止）
+
+- ❌ 写实现先于测试（反向 TDD）
+- ❌ micro-cycle 内跑全 suite（`vitest run`）
+- ❌ micro-cycle 内调 `peaks workflow verify-pipeline`
+- ❌ 1 个 micro-cycle 改 < 1 行代码（合并到下一个相关变更）
+- ❌ skip 边界 check 直接 ship
+- ❌ 在 micro-cycle 内修改 reviewed artifacts（code-review / security-review / perf-baseline）— 等边界再 regenerate
+- ❌ micro-cycle 跨 PR/branch（一次 PR 内的所有 micro-cycles 才合在一起 review）
+
+## 跟其他 skill 的边界
+
+| 阶段 | 谁负责 | 节奏 |
+|---|---|---|
+| RD slice 内部 | peaks-solo (main loop) | micro-cycle（5-10s 一个） |
+| RD slice 边界 | peaks-solo 调用 `peaks slice check` | 一次 |
+| QA test execution | peaks-qa (sub-agent or inline) | slice 级 |
+| 3-way fan-out (CR + sec + perf) | peaks-rd (sub-agent) | slice 级（RD 内部一次 + 边界 check 一次） |
+| TXT handoff | peaks-txt | slice 级 |
+| SC commit-boundaries | peaks-sc | slice 级 |
+
+## 为什么这套比当前 peaks-solo 的设计合理
+
+- **快**：micro-cycle ~100ms（vs 30s 全 suite），改 10 个 bug 从 5 分钟降到 30 秒
+- **稳**：边界 check 不省，4 项检查（tsc + vitest run --changed + 3-way + verify-pipeline）一次全跑；changed-only 模式 1-3s 内出结果，全量用 `--run-tests` opt-in
+- **清晰**：LLM 看到一个 explicit "禁止" 列表 + 强制 sequence，比"建议"更不容易越界
+- **可观测**：micro-cycle 走单测 → 边界跑 verify-pipeline，每步都有 JSON envelope 验证
+
+## 跟 peaks-solo SKILL.md 的对账
+
+- `peaks slice check` = 边界命令
+- micro-cycle = slice 内部
+- 3-way fan-out = peaks-rd 内部 + `peaks slice check` 末尾
+- `peaks workflow verify-pipeline` = 边界 check
+- `peaks request transition` = 边界切状态
+- 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.
+
+---
+
+## Verdict reasoning (v2.13.1)
+
+> v2.13.1 Group A: the 6-step cycle above stays unchanged. This new
+> section adds the **依据** (evidence/justification) layer for when the
+> runbook triggers an RD re-run. The aggregator
+> (`src/services/verdict/verdict-aggregator.ts`) is the source of
+> `reasons`; this section tells the runbook how to print them and how
+> to decide between `return-to-rd` (repair loop) vs `block` (blocked
+> TXT handoff).
+
+### When the runbook prints reasons
+
+Trigger an aggregator call **before** re-running RD. The reasons
+array is the payload that gets persisted into the rd transition note
+so the artifact history shows *why* a re-run was triggered, not just
+*that* it was. Print format (compatible with `peaks log --json`):
+
+```
+re-run reason: { source, signal, severity, file, line, hint }
+```
+
+#### Example: multi-signal failure (mock output)
+
+```json
+[
+  {
+    "source": "security-audit",
+    "signal": "block",
+    "severity": "CRITICAL",
+    "file": "src/auth/login.ts",
+    "line": 42,
+    "hint": "plaintext password compare"
+  },
+  {
+    "source": "peaks-mut",
+    "signal": "block",
+    "kind": "mutationKillRateMin",
+    "actual": 0.62,
+    "threshold": 0.8,
+    "hint": "kill rate 0.620 < 0.800"
+  },
+  {
+    "source": "peaks-qa",
+    "signal": "return-to-rd",
+    "reportPath": ".peaks/_runtime/sid/qa/test-reports/rid.md"
+  }
+]
+```
+
+Aggregated verdict (top-level precedence `block > return-to-rd > warn > pass`):
+
+```json
+{ "verdict": "block", "reasons": [...] }
+```
+
+### Decision table: `return-to-rd` vs `block`
+
+| Aggregator verdict | Runbook action | Why |
+|---|---|---|
+| `pass` | Stop — accept the slice. | All signals green; no repair needed. |
+| `warn` | Re-run RD (repair loop) once. | Soft signal; RD can address the warnings without escalation. |
+| `return-to-rd` | Re-run RD (repair loop) up to cap. | QA found a recoverable failing acceptance item; stay in the loop. |
+| `block` | Emit blocked TXT handoff. | Hard gate (security / perf CRITICAL / karpathy block / mut `passed:false` / qa `blocked`) — do NOT re-run RD; mark as known blocker per the repair-cycle cap rule above. |
+
+The `block` row is what **does NOT** consume a repair cycle. The 3-cycle
+cap counts only `return-to-rd` and `warn` re-runs; a `block` exits the
+loop immediately and writes a blocked TXT handoff with the aggregator's
+reasons array preserved verbatim.
+
+### Runbook integration
+
+When the peaks-solo main loop sees `qa verdict != pass` or any audit
+prereq missing, the runbook now does:
+
+1. Call `aggregateVerdict({ security, perf, karpathy, mut, qa })` with
+   whatever envelopes are available (missing envelopes → omit the key;
+   the aggregator treats undefined as "not run").
+2. Sort the `reasons` array by severity (`CRITICAL` first, then
+   `HIGH`, then threshold delta for mut).
+3. Print the sorted reasons using the format above. The print must
+   happen **before** `peaks request transition --role rd --state
+   spec-locked` so the user can see what triggered the re-run.
+4. Apply the decision table to pick `return-to-rd` (loop) vs `block`
+   (TXT handoff).
+
+The aggregator is a pure function — no I/O, no clock. v2.13.1 wires
+the print step into the runbook; v2.14 will surface the aggregator
+result via a `peaks verdict aggregate --rid <id>` CLI subcommand.

package/skills/peaks-solo/references/mode-selection-with-stale-presence.md

@@ -0,0 +1,124 @@
+# Mode selection with stale presence (v2.15.0 slice 002)
+
+> Companion to `mode-selection.md`. Read together — this file only
+> covers the v2.15.0 stale-presence branch that prevents a previous
+> session's mode from silently carrying over into a new session.
+
+## Why this reference exists
+
+Defect A (from PRD-002, 2026-06-28 session 88b27d):
+
+1. session A runs in `full-auto` → `peaks skill presence:set peaks-solo --mode full-auto --gate startup` stamps
+   `.peaks/_runtime/active-skill.json` with `outerSessionId=outer-A`.
+2. session A closes (Claude window quit).
+3. session B opens (a new Claude window, `outerSessionId=outer-B`).
+4. `peaks skill presence:get --project <path>` still returns `mode=full-auto` because the file is on disk.
+5. peaks-solo Step 1 reads the presence, sees `mode=full-auto`, **skips** AskUserQuestion.
+6. The user never picked `full-auto` for THIS session — the mode was sticky from the previous one.
+
+The fix: presence is only authoritative when its `outerSessionId` matches the current outer session. Otherwise Step 1 must re-ask.
+
+## Detection protocol
+
+Before deciding to skip Step 1's AskUserQuestion, the LLM driver (or any peaks-solo caller) MUST run:
+
+```bash
+peaks skill presence:check-stale --project <path> --json
+```
+
+The CLI returns a JSON envelope of shape:
+
+```json
+{
+  "ok": true,
+  "command": "skill.presence:check-stale",
+  "data": {
+    "stale": true,
+    "reason": "outer-session-mismatch",
+    "presence": { "skill": "peaks-solo", "mode": "full-auto", "outerSessionId": "outer-A", ... },
+    "currentOuterSessionId": "outer-B",
+    "recordedOuterSessionId": "outer-A"
+  },
+  "warnings": [],
+  "nextActions": []
+}
+```
+
+Reason codes:
+
+| `reason` | Meaning | Step 1 action |
+|---|---|---|
+| `null` | presence exists and its `outerSessionId` matches the current outer session. | May reuse the recorded `mode` (or AskUserQuestion — the user's choice to skip is preserved either way). |
+| `outer-session-mismatch` | presence exists but its `outerSessionId` does NOT match the current one. | AskUserQuestion — the previous session's mode is NOT authoritative for this session. |
+| `no-presence` | no presence file on disk. | AskUserQuestion — fresh start, no prior choice recorded. |
+
+## Optional companion flag: `presence --check-stale`
+
+For callers that already use `peaks skill presence` to read the active skill, slice 002 adds `--check-stale`:
+
+```bash
+peaks skill presence --check-stale --project <path> --json
+```
+
+Returns the same `stale` / `reason` / `currentOuterSessionId` / `recordedOuterSessionId` fields attached to the standard presence envelope. Default `false` (back-compat).
+
+## Pause integration via `peaks solo should-pause`
+
+`peaks solo should-pause --step step-1-mode-select --mode <mode>` now consults `presence:check-stale` automatically. When stale:
+
+```json
+{
+  "ok": true,
+  "command": "solo.should-pause",
+  "data": {
+    "shouldPause": true,
+    "reason": "stale-presence — re-ask Step 1 (recorded outer session id does not match current)",
+    "gateKind": "mode-selection-itself",
+    "logLine": "..."
+  }
+}
+```
+
+The hard-pause on `step-1-mode-select` is preserved for ALL modes (defect #1 fix from slice 2026-06-28-solo-mode-bypass-fix). Stale-presence is an additional reason — even when the user names a profile explicitly, peaks-solo can still surface the staleness for visibility.
+
+## Auto-clear on session rotation
+
+`peaks workspace init` now calls `clearStalePresenceOnRotation` whenever an `outer-session-mismatch` rotation fires. This means in the COMMON path (user reopens Claude → peaks-solo auto-runs `peaks workspace init` → rotation clears the stale presence → Step 1 reads no-presence → re-ask). The check-stale CLI is the safety net for the rare case where rotation was suppressed (`--no-rotate-on-outer-mismatch`).
+
+The auto-clear respects two guards so it never destroys a user-explicit mode:
+
+1. **Reconnect guard** — if the recorded outer id matches the CURRENT outer id, do NOT clear (the user just reconnected from the same Claude session after rotation).
+2. **Live-different-outer guard** — if the recorded outer id belongs to a different LIVE outer session (e.g. another Claude window is also driving this project), do NOT clear (would destroy that user's explicit mode).
+
+## Worked example (the 88b27d defect)
+
+Session A: `peaks skill presence:set peaks-solo --mode full-auto` (outer A).
+Session A closes. Session B starts (outer B).
+
+```bash
+# 1. Run init (the common entry into peaks-solo).
+peaks workspace init --project . --json
+# → auto-rotates session binding AND auto-clears stale presence
+#   nextActions: ["Auto-cleared stale skill presence ..."]
+#   data.rotation: { previousSessionId: "session-A", reason: "outer-session-mismatch" }
+
+# 2. peaks-solo Step 1 (was: skip AskUserQuestion because presence.mode=full-auto).
+# Now: presence is gone → no-presence → AskUserQuestion fires.
+
+peaks skill presence:check-stale --project . --json
+# → { stale: true, reason: "no-presence", presence: null }
+
+peaks solo should-pause --step step-1-mode-select --mode full-auto --json
+# → { shouldPause: true, reason: "step=step-1-mode-select is a mode/context-selection step → always pause" }
+
+# 3. User picks a profile (or repeats "full-auto"). Then:
+peaks skill presence:set peaks-solo --mode full-auto --gate startup
+# → re-stamps with outer=B. Future sessions that read this presence
+#   see outerSessionId=outer-B matching THEIR outer=B → not stale.
+```
+
+## ACL — what NOT to do
+
+- **NEVER** skip Step 1 just because `.peaks/_runtime/active-skill.json` shows a `mode` field. Run `presence:check-stale` first.
+- **NEVER** call `peaks skill presence:clear` from peaks-solo to "fix" a stale mode. The auto-clear path is `peaks workspace init`'s job; manual clears destroy user-explicit mode choices that may belong to another live outer session.
+- **NEVER** set the presence `mode` field from inside a sub-agent (peaks-rd, peaks-qa, etc.). Sub-agents may read presence to honour the user's chosen mode but the write authority for Step 1 belongs to the peaks-solo driver.

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

@@ -0,0 +1,81 @@
+# OpenSpec Lifecycle for Peaks Solo
+
+Peaks Solo orchestrates RD, QA, and SC. When the target repository uses OpenSpec, Solo must drive the full lifecycle through the Peaks CLI so each role works against the same stable surface.
+
+> **Slice #016 (2026-06-09)**: this document used to live at `openspec-mcp-workflow.md` and contained a section on the `peaks mcp *` lifecycle. The MCP subsystem was retired in slice #016; that section is gone. The OpenSpec lifecycle described below is unchanged.
+
+## OpenSpec change lifecycle
+
+```text
+peaks openspec render   →  RD authors a change pack (dry-run, then --apply)
+peaks openspec validate →  Solo gates RD output before slicing starts
+peaks openspec show     →  any role reads parsed proposal/tasks state
+peaks openspec to-rd    →  RD projects the pack into refactor slice input
+                          SC projects it into commit boundary candidates
+peaks openspec validate →  QA gates the final state before sign-off
+peaks openspec archive  →  Solo moves the change under changes/archive/<id>/
+```
+
+Rules Solo applies:
+
+- `render --apply` is the only Peaks-managed way to write a change pack. Other roles must not hand-edit `openspec/changes/**`.
+- `validate` is run twice per change in a refactor flow: once before slicing (RD entry gate) and once before archive (QA exit gate). Both must end with `data.valid === true`.
+- `archive --apply` is the lifecycle terminator; Solo only invokes it after QA acceptance and SC commit.
+
+## Refactor workflow wiring
+
+For `peaks-solo refactor` runs against a repository with `openspec/`:
+
+1. RD entry gate — `peaks openspec validate <id>` must pass and `peaks openspec to-rd <id>` must return `acceptance.length > 0`.
+2. Each slice must reference one OpenSpec tasks section as its commit boundary (per `references/openspec-commit-boundaries.md` in peaks-sc).
+3. QA exit gate — re-run `peaks openspec validate <id>` after implementation; record the result in the QA validation report.
+4. Archive — `peaks openspec archive <id> --apply` only after QA passes the exit gate and SC closes the final commit.
+
+If the consuming LLM needs an MCP server for docs lookup or research (e.g. Context7), it checks its own tool list for `mcp__<server>__*` and tells the user the install command if absent. peaks-cli is no longer in the install path; the LLM is the executor, the IDE is the dispatcher.
+
+## 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.