peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,87 @@
+# Peaks-Loop Frontend-only development mode
+
+> 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 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), Code 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 Code should switch to).
+
+When there is no conflict, do not ask — the CLI value wins and the workflow proceeds.
+
+### Mock data strategy selection
+
+Code 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.
+
+Code 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 → Code 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. Code 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/`. Code 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, Code 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.
+
+Code 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-code/references/job-loop.md

@@ -0,0 +1,68 @@
+# Peaks-Loop Code — Job Loop Deep-Dive
+
+> Read alongside `SKILL.md` Steps 0.8 / 0.81 / 0.85 / 0.86 / 0.87.
+
+## State machine
+
+```
+       init ─────────► pending ─► in-progress ─┐
+                          │                     │
+                          ▼                     ▼
+                       blocked (one slice)    done ──► (next slice)
+                          │                     ▲
+                          ▼                     │
+                       (strict: STOP,           │
+                        best-effort: skipped)   │
+```
+
+## Visibility
+
+| Layer | Tool | Cost | User reads |
+|---|---|---|---|
+| LLM-runner transcript | (the chat) | free | always |
+| `--watch` poll | peaks job status --watch | 1% CPU | when in a 2nd terminal pane |
+| Statusline | peaks statusline install | ambient | in IDE bottom bar |
+
+## Rotation cadence
+
+- `len(slices) ≤ 2` → single-mode (auto-compact passively).
+- `len(slices) ≥ 3` → rotating-mode, K=3 default.
+- LLM-initiated override (rotating→single) is **strongly discouraged**; if used, must record `mainLoopOverride` in state.json with `reason ≥ 10 chars` and predicted wall-time ≤ 30 min.
+
+## Cleanup gate
+
+Every `peaks sub-agent dispatch` inside a Job scope MUST be matched by a `peaks job subagent-cleanup --force` BEFORE the next slice checkpoint. The wrapper (M5) refuses dispatch return-success without matching cleanup.
+
+## Cross-day recovery
+
+`peaks session resume --job-id <jid>` reads:
+1. `job/<jid>/state.json` — current job state
+2. `session/cycle-<n>.md` — main-session cycle summary (rotating mode)
+3. `session/auto-decisions.md` — auto-compact history
+4. `session/checkpoints/*.json` — generic session checkpoints
+
+The resume endpoint cross-checks all four before offering continuation; if any layer is stale, the user gets an AskUserQuestion (resume / restart / skip).
+
+## Visibility prose
+
+The Job loop is foreground. Three visibility layers, all on by default:
+1. **LLM-runner transcript** — primary surface; user reads the chat to see active step.
+2. **`peaks job status --watch`** — terminal poll, ANSI bar, refresh every 3 s.
+3. **Statusline** — ambient `job: <jid> [done/total] currentSlice ETA m:s context main%. cycle`.
+
+No detached workers, no `nohup`, no `disown`. Any attempt to spawn a background job → red line violation → block.
+
+## Red lines (9 hard rules)
+
+The LLM-runner MUST NOT:
+1. Enter Step 11 / write final handoff while job has remaining slices.
+2. Re-ask the user about cost / length / context.
+3. Coalesce multiple slices into one rid.
+4. Modify a committed slice (`git commit --amend` on `done`).
+5. Fake completion (CLI verifies commit-sha exists in git log).
+6. Use detached / background / daemon-mode sub-agents inside a Job.
+7. Skip `peaks job subagent-cleanup` between dispatch and slice checkpoint.
+8. Skip or postpone a scheduled `peaks session rotate`.
+9. Suppress visibility — no silencing statusline / `--watch`.
+
+Violations trigger a `peaks job block` event with the specific red-line number.

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

@@ -0,0 +1,79 @@
+# Local intermediate artifact workspace
+
+> Body of `## Peaks-Loop 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-code / -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` (Code 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` (Code 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-Loop 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-code/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-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-code (main loop) | micro-cycle（5-10s 一个） |
+| RD slice 边界 | peaks-code 调用 `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-code 的设计合理
+
+- **快**：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-code 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-Loop 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-Loop Code MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Code must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
+
+**How Code invokes another role (mechanism, not metaphor):**
+
+Code 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-Loop 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)** — Code is the only loop, and after RD or QA finishes (whether as a sub-agent or directly), Code 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 Code (when Code 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), Code 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`. Code does NOT need to track three separate RD-side sub-runs; the RD role owns the fan-out lifecycle end-to-end. Code'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 Code 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-code --project <repo> --mode <mode> --gate <current-gate>
+```
+
+This keeps the CLAUDE.md status header accurate (`Peaks-Loop Skill: peaks-code`) 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`, Code 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 Code routes QA findings back to RD (mechanism, not metaphor):**
+
+When `peaks-qa` returns `verdict=return-to-rd`, Code 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. Code restores presence after the sub-agent returns.
+   - **Assisted / strict / inline-fallback**: Code 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. Code 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), Code MUST restore presence:
+   ```bash
+   peaks skill presence:set peaks-code --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-code 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.