peaks-loop 3.1.2 → 4.0.0-beta.10

package/skills/peaks-code/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-code --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-code 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-code 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-code", "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 code should-pause`
+
+`peaks code should-pause --step step-1-mode-select --mode <mode>` now consults `presence:check-stale` automatically. When stale:
+
+```json
+{
+  "ok": true,
+  "command": "code.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-code-mode-bypass-fix). Stale-presence is an additional reason — even when the user names a profile explicitly, peaks-code 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-code 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-code --mode full-auto` (outer A).
+Session A closes. Session B starts (outer B).
+
+```bash
+# 1. Run init (the common entry into peaks-code).
+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-code 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 code 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-code --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-code 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-code driver.

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

@@ -0,0 +1,21 @@
+# Step 1 — Mode selection
+
+> Body of `### Peaks-Loop Step 1`. After Step 0 has anchored the workspace and presence, when the user invokes Peaks-Loop Code 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-Loop 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-Loop proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
+3. **Swarm** — Peaks-Loop maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
+4. **Strict** — Peaks-Loop 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 "code" 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 code|team` is a **different** CLI dimension (code 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-code --full-auto`, "用全自动模式"), skip this question and use the named profile directly.

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

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

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

@@ -0,0 +1,138 @@
+# Peaks-Loop Pre-RD project scan checklist
+
+> Extracted from `skills/peaks-code/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/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). RD and UI roles read this before starting work. **project-scan.md is a project-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/project-scan/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
+
+> **Slice 2026-07-15-project-scan-bootstrap (G1 + G2 + G4b):** `peaks workspace init` and `peaks project context` now both bootstrap `.peaks/project-scan/project-scan.md` automatically. On a brand-new 0-1 project (no `package.json` or no source files) the file is seeded with `archetype: unknown` + `(empty)` placeholder rows. On an existing project it is filled from `peaks scan archetype` + `peaks scan libraries` output. Idempotent — re-running `workspace init` does NOT overwrite the existing file unless `--force` is passed.
+
+### 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-code/references/quality-gate-cheatsheet.md

@@ -0,0 +1,13 @@
+# 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 Code 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-code/references/refactor-mode.md

@@ -0,0 +1,24 @@
+# Peaks Code Refactor Mode
+
+`peaks-code 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-code/references/resume-detection.md

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