peaks-loop 3.1.2 → 4.0.0-beta.10

package/skills/peaks-code/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: peaks-code
+description: Code-domain loop engineering orchestrator for the Peaks-Loop skill family. Use when the user asks Peaks-Loop to handle a code-repo workflow end-to-end (端到端/全流程/需求开发), especially from a product document (PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-qa, peaks-ui, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-code`, "peaks code", "全流程开发", "端到端迭代". General primitives (peaks-resume / peaks-status / peaks-test) are sibling skills, not children.
+---
+
+## Scope (RL-8 — red line, locked 2026-07-08)
+
+`peaks-code` is a **code-domain long-task loop engineering orchestrator; not a general-purpose orchestrator.**
+
+This is RL-8 from the Loop Engineering crystallization design
+(`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 and §10 RL-8).
+The boundary is closed under this slice:
+
+- **In scope:** end-to-end code-domain workflows — repository scanning, RD planning, code implementation via RD, QA verification, UI changes inside a code repo, source-control handoff, and code-repo context packaging. Coordinated role skills: `peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`.
+- **Out of scope:** research / content / product / medical / non-code domains. Each of those ships as an independent `peaks-*` skill that imports `.peaks/standards/loop-engineering-guidelines.md` and passes `peaks skill lint --category loop-engineering-readiness`. They are **not** subclasses or variants of `peaks-code`.
+- **Failure modes this rule prevents:** (a) `peaks-code` widening into a general orchestrator; (b) non-code capabilities being smuggled into `peaks-code`; (c) other domains being expressed as "peaks-code variants".
+- **Self-check:** before any new peak-* capability is added here, ask "is this code-domain?" If the answer is no, the right move is a new `peaks-*` skill, not an extension of `peaks-code`.
+
+## Single-scope-axis naming convention (2.7.1)
+
+The `.peaks/` workspace has a **single scope axis** (session-id) plus a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` (NEVER bare `<sid>`). Reviewable artifacts live at `.peaks/_runtime/<sessionId>/<role>/...` (gitignored); the change-id is an optional filename slug and does NOT route filesystem writes. CLI: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Test `skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) axis labels, (c) this callout.
+
+## Karpathy guidance (Slice 1/6 — karpathy prompt-injection-lift)
+
+Every sub-agent dispatch (`peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`) MUST receive the 4 Karpathy guidelines. Append the verbatim block from `peaks-rd/references/rd-sub-agent-dispatch.md` §"Karpathy-guidelines context" to the dispatch prompt. Canonical skill id: `andrej-karpathy-skills:karpathy-guidelines`. Summary: **#1 Think Before Coding**, **#2 Simplicity First**, **#3 Surgical Changes**, **#4 Goal-Driven Execution**.
+
+## Hard ban (effective 2.8.3 — read every session, no exceptions)
+
+Never create `.peaks/_runtime/<YYYY-MM-DD-*>/` at the top level of `.peaks/`. ALL reviewable artifact dirs live under `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) — never as siblings of `.peaks/_runtime/`. `peaks workspace init` creates only `.peaks/_runtime/<sessionId>/session.json`. If you find yourself about to write a date-prefixed directory directly under `.peaks/`, STOP and reroute under `.peaks/_runtime/<sessionId>/`. The `.gitignore` rule + vitest guard at `tests/unit/workspace/top-level-change-id-guard.test.ts` enforce this.
+
+# Peaks-Loop Code
+
+Peaks-Loop Code is the orchestration facade for the Peaks-Loop short skill family. Use it to identify the user scenario, recommend an execution mode, coordinate role skills, and produce the final handoff report. Do not collapse role responsibilities into this skill.
+
+## 产品定位(2026-06-28 校准)
+
+> peaks-loop 真实定位 = 24h AI 程序员编排器;user 角色 = 业务/产品审阅者,不参与技术决策。详见 `.peaks/memory/peaks-loop-24h-ai-programmer-positioning.md`。
+
+## Skill-first architecture note (read once, internalise)
+
+This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary** — invoked by the skill prompt only when a primitive is the right tool. Behaviour only an LLM in a skill prompt would use lives **here in the SKILL.md**.
+
+## Code-Change Red Line (BLOCKING — read before ANY tool call)
+
+**Peaks-Loop Code is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.** Every code change goes through `peaks-code → RD → QA → verdict`. **If you catch yourself about to write code, STOP.** Hand off to RD. Before declaring workflow complete, run `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`.
+
+## Peaks-Loop Startup sequence (MANDATORY — execute in order)
+
+### Peaks-Loop Slice 011 — workspace consolidate + session checkpoint/resume
+
+`peaks workspace consolidate` is the slice-011 umbrella primitive. `peaks session checkpoint` (context-overflow defense) and `peaks session resume` surface as Step 0.75 + Step N. See `references/cross-date-session-check.md`.
+
+### Peaks-Loop Step 0.75: Resume from checkpoint (BLOCKING on same-day re-invocation)
+
+When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` has `*.json`, surface via `peaks session info --active --json` + `peaks session resume --from <path> --project <repo>`. Prompt via `AskUserQuestion` (resume / fresh); if "resume", prepend the block. Step 0.75 is no-op on precondition fail. See `references/checkpoint-resume.md`.
+
+### Peaks-Loop Step N: Periodic checkpoint (auto-fire, no user action)
+
+Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write. See `references/periodic-checkpoint.md` (otherwise `tests/unit/code/checkpoint-periodic-frequency.test.ts` fails).
+
+### Peaks-Loop Step 0.6: Audit + Goal (NEW)
+
+Invoke peaks-audit after need expressed; store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All autonomous work requires approved goal.** → `references/audit-goal-gate.md`.
+
+### Peaks-Loop Step N+1: Final Review (NEW)
+
+After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-dim evidence. All 4 pass → final delivery; else loop back. See `references/final-review-gate.md`.
+
+### Peaks-Loop Step N+2: Main-session context monitor (D6 + slice 2026-07-02)
+
+After every 4th tool call, probe via `peaks code context-now --project <repo> --json`. Thresholds: 50% / **0.85 pre-compact / 0.95 red-line** (v2.13.0). **In Job mode ≥ 0.85 is MANDATORY auto-compact** (`peaks session auto-compact --execute`). Pass `--enforce-job-mode` for single-rid. **≥ 0.95** red line: next Bash/Task fires `peaks session auto-compact-hook`. **Karpathy §4 exception**: compact red line keeps runner alive — zero-intervention wins; LLM MUST NOT ask user to run `/compact`. Honor `--in-flight-batch` (D6.e).
+
+### Peaks-Loop Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
+
+Run `peaks workspace init` + `peaks skill presence:set peaks-code` BEFORE any analysis, role handoff, or mode-selection question. Even "分析下这个项目" / "看一下代码" / one-line questions anchor first.
+
+→ see `references/anchoring-and-session-info.md` for the full Step 0 contract + session-conflict resolution.
+
+#### Step 0 bypass — Claude Code [Fact-Forcing Gate] (slice 2.0.1-bug3)
+
+`peaks workspace init` materializes `.claude/settings.local.json` (a PreToolUse hook allow-list for `.peaks/**` paths and `peaks <subcommand>` Bash) so the [Fact-Forcing Gate] does not block Step 0. Pass `--no-claude-hooks` to opt out.
+
+→ see `references/anchoring-and-session-info.md` for the full bypass contract, recovery flow, and anti-bail-out rule.
+
+### Peaks-Loop Step 0.7: Detect unfinished work and offer resume (BLOCKING on first invocation per session)
+
+After Step 0, run the resume-detection probe; surface via `AskUserQuestion` if a slice is in flight. **v3.1.2 resume rule:** if `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` exists, read FIRST and surface `Next: slice #N of M`. **v2.11.0 D7 override:** if user just `/compact`ed, run `peaks code post-compact-detect --project <repo> --json` FIRST; `shouldAutoResume: true` skips AskUserQuestion. → `references/resume-detection.md`.
+
+### Peaks-Loop Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
+
+After Step 0.7 returns "fresh", run `peaks upgrade --detect-1x --project <root> --json`. If `isOneX: true`, surface `AskUserQuestion`. → `references/step-0-55-1x-detection.md`.
+
+### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch + v3.1.2 mechanical gates)
+
+> **CLI reality check (D-001 sediment, 2026-07-09):** The CLI surface has changed since this section was last verified. The actual command is **`peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating> [--parallelism-hint <serial|llm-decides>] [--exit-policy <strict|best-effort>] [--project <repo>]`**. The legacy `peaks code detect-job --is-job/--suggested-job-id/--confidence` form described below is **no longer present** in 4.0.0-beta.6. If you find `--is-job` rejected, fall back to `peaks job init`.
+
+The CLI is a **recorder + gate** for job-shape (the LLM judges). LLM calls `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating>` (with `--caller-id <id>` and `--project <repo>` in non-Claude-Code environments), which writes `.peaks/_runtime/<sessionId>/job/<jid>/state.json` and emits a `[job-event] {kind: job-started, jobId, total, strategy}` line. Downstream steps call `peaks job status --job-id <jid>` to read state.
+
+**Hard rule (v3.1.1 red-line #10):** LLM MUST NOT skip the job-init call. If `peaks job status` reports `done: 0` and the slice work has begun, the LLM forgot to initialize — re-call `peaks job init` immediately.
+
+> **D-003 sediment (2026-07-09):** The historical `JOB_SHAPE_NOT_DECIDED` exception thrown by `read-job-shape` is no longer wired in 4.0.0-beta.6. The current CLI uses `peaks job status` which reports a passive `done: 0` instead of throwing. Both behaviors enforce the same intent (no work may begin before init) but the failure mode is a soft warning rather than a hard exception. LLM should treat `done: 0` after Step 0.8 as a recoverable miss, not an unrecoverable error.
+
+**v3.1.2 mechanical gates** (recorder-only was bypassed twice):
+
+PreToolUse hook on `peaks code gate-step-08`; size-fear ban on `peaks code emit-handoff`; forced auto-compact at ≥ 0.85 in Job mode; on-disk slice progress via `peaks job checkpoint` (canonical reader `peaks job progress --job-id <jid>`). Full mechanics (judgement criteria, hook table, backup-regex rationale, hook wiring) at `references/step-0-8-gate.md`.
+
+### Peaks-Loop Step 0.81 — per-slice 收尾
+
+After commit: `peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)` → `peaks job status` → loop (remaining>0 → Step 1; ==0 → Step 8/9/10/11; blocked → Step 0.85).
+
+### Peaks-Loop Step 0.85 — slice 阻塞处理
+
+Trigger: `repair-status` atCap=true, context-now red-line ≥5min, or `subagent-cleanup` fails twice. Action: `peaks job block --slice-id <rid> --reason "<reason>"` then STOP.
+
+### Peaks-Loop Step 0.86 — main session rotation
+
+Active in rotating mode; fires every `rotateEvery` slices or via `peaks job rotate-now`. Sequence: cycle-summary → checkpoint rotate-marker → `peaks session rotate` → resume via `peaks session resume --job-id <jid>`.
+
+### Peaks-Loop Step 0.87 — sub-agent cleanup gate
+
+After every `peaks sub-agent dispatch --batch-id <id>` inside a Job, BEFORE next slice checkpoint: `peaks job subagent-cleanup --job-id <jid> --batch-id <id> --force`. Non-zero → block.
+
+→ see `references/job-loop.md` for state machine, visibility, rotation cadence, cross-day recovery, 9 red lines.
+
+### Peaks-Loop Step 1: Mode selection
+
+Use `AskUserQuestion` with `Full auto (Recommended)` first when user did not name a profile OR skill presence is stale (run `peaks skill presence:check-stale --project <path> --json` first; `stale: true` ⇒ re-ask). → `references/mode-selection.md`, `references/fast-mode.md`, `references/mode-selection-with-stale-presence.md`.
+
+### Peaks-Loop Step 2: Re-set skill presence with the chosen mode
+
+Re-run `peaks skill presence:set peaks-code --mode <mode-value> --gate startup`. Install statusline on first run (`peaks statusline install`). → `references/skill-presence-and-title.md`.
+
+### Peaks-Loop Step 2.3: Load project memory (durable, LLM-authored memories)
+
+Run `peaks project memories --project <repo> --json` to read decisions / conventions / modules / rules / lessons from `.peaks/memory`. → `references/project-memory-loading.md`.
+
+### Peaks-Loop Step 2.5: Set session title
+
+Extract a short title from the user's first request (8-20 Chinese chars or 4-10 English words). Run `peaks session title <sessionId> "<title>" --json`. Skip if a title is already set. → `references/skill-presence-and-title.md` (same file as Step 2). D-002: sid is positional, NOT `--session-id` flag (rejected with `error: unknown option`).
+
+## Sub-agent session sharing (MANDATORY — one conversation = one sid)
+
+When peaks-code dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt, peaks-sc), the prompt MUST include the parent's sid. The sub-agent MUST NOT call `peaks workspace init` (would orphan the parent's binding).
+
+## Boundaries
+
+Peaks-Loop Code may identify scenarios, recommend profiles, coordinate role skills via artifacts, coordinate project memory extraction, request user confirmation at risk/commit boundaries. MUST NOT silently install hooks / create agents / enable MCP / modify Claude settings / create GitHub repos / bypass role-skill artifacts. → `references/boundaries.md`.
+
+## CLI Drift Index (sediment 2026-07-09)
+
+> **Reading guide:** Verified against peaks-loop 4.0.0-beta.6. Each drift below is annotated inline at the relevant step with a `> CLI reality check`. On `error: unknown option ...`, **read the inline reality check first** before guessing.
+
+| Drift ID | Step | Symptom | Fix | Inline location |
+|---|---|---|---|---|
+| **D-001** | 0.8 | `peaks code detect-job --is-job ...` rejected with `error: unknown option '--is-job'` | Use `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single\|rotating>` | §Step 0.8 first paragraph |
+| **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` (this is the bare `<sid>` anti-pattern) | sid is positional: `peaks session title <sessionId> "<title>" --json` | §Step 2.5 |
+| **D-003** | 0.8 | `JOB_SHAPE_NOT_DECIDED` exception expected but never thrown | Current behavior is `peaks job status` reports `done: 0` passively — treat as recoverable miss, not hard error | §Step 0.8 third paragraph |
+| **D-010** | 11c | `peaks memory extract` returns `extractedCount: 0` despite `<!-- peaks-memory:start -->` existing | Block requires YAML frontmatter (`title:` + `kind:` + `---`) + closing `<!-- peaks-memory:end -->`. Bare `peaks-memory:start` is parsed silently but produces no writes | §Step 11c + 11d |
+
+> **Sediment lesson (master record):** `.peaks/memory/peaks-code-runbook-4-0-0-beta-6-skill-md-cli-d-001-d-002-d-003-d-010.md`
+
+## Peaks-Loop GStack integration
+
+Map gstack stages to Peaks-Loop role artifacts; preserve confirmation gates. → `references/gstack-integration.md` + `references/browser-workflow.md`.
+
+## Peaks-Loop Local intermediate artifact workspace (MANDATORY)
+
+Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_runtime/<sessionId>/`. NEVER write Peaks-Loop intermediate artifacts to the project root.
+
+## Peaks-Loop Pre-RD project scan checklist (MANDATORY)
+
+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`). Slice 2026-07-15-project-scan-bootstrap (G1 + G2): `peaks workspace init` and `peaks project context` both bootstrap this file automatically; only re-run the manual flow when the scan output is genuinely out of date. → `references/project-scan-checklist.md`.
+
+> **Slice 2026-07-15-project-scan-bootstrap G4b / AC9:** after `peaks workspace init`, the consumer project's `.peaks/project-scan/` directory carries 5 files: `project-scan.md` (generated by the scan logic) + `business-knowledge.md` + `security-template.md` + `perf-template.md` + `audit-output-schema.md` (the 4 audit/business templates bundled at `src/services/workspace/templates/project-scan/*.md`, copied on init; idempotent — existing files preserved unless `--force-project-scan-templates`). RD / UI / TXT / QA read from this tree; nothing else.
+
+## Peaks-Loop Frontend-only development mode
+
+When the project has no live backend (no swagger.json, no API server), Code must activate frontend-only mode. The CLI is authoritative — read `frontendOnly` and `frontendOnlyReason` from `peaks scan archetype --json`. → `references/frontend-only-mode.md`.
+
+## Peaks-Loop Request type classification + Workflow order + Transition verification gates
+
+The 6-type table + 11-step order + 7 transition gates (A-G) live in `references/workflow-gates-and-types.md`. peaks-code narrative references Gate A-G — keep both files in lockstep.
+
+## Peaks-Loop Default sub-agent fan-out (≥ 2 leaves/topological level → `--from-dag`)
+
+> **Slice 5:** when the slice DAG has ≥ 2 leaves at one topological level, dispatch via `peaks sub-agent dispatch --from-dag <dag-file>` (wall-time ≈ max, not sum).
+
+Write DAG → `.peaks/_runtime/<sessionId>/sc/slice-dag.json`, run `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` once; orchestrator emits N parallel `buildToolCall` (`dispatchCount === N`). 主路径 = 唯一蜂群;config/docs/chore 跳过不打断。详见 `.peaks/memory/peaks-loop-24h-ai-programmer-positioning.md`。
+
+### Hard constraint: fan-out is mandatory (slice 2026-06-24-audit-5th-p2)
+
+> **No serial opt-out.** `preferences.fanout.defaultMode = 'serial'` was removed in 2.8.4; legacy values auto-migrate to `fan-out`.
+
+→ see `references/swarm-dispatch-contract.md`, `references/sub-agent-dispatch.md` (NOT `Skill` tool), `references/fanout-mandatory.md`.
+
+## Slice 调度:分层并行 + 上游同步(2026-06-28 校准)
+
+> 分层并行(G12)+ 上游同步(G11)见 `.peaks/memory/peaks-loop-fork-sync-and-layered-parallel.md`。
+
+## Peaks-Loop Mandatory RD QA repair loop (AUTO-PROCEED)
+
+After `peaks-rd` finishes, Code MUST auto-route to `peaks-qa` without waiting for confirmation. Cap: 3 cycles; on 3rd failure emit blocked TXT handoff. Full 5-step procedure at `references/micro-cycle.md`.
+
+## Default runbook
+
+The end-to-end CLI sequence for `full-auto` lives in `references/runbook.md`. `assisted`/`strict` pause at `[CONFIRM]`; `full-auto`/`swarm` auto-proceed.
+
+When adding new CLI commands, mirror into `references/runbook.md` and `tests/unit/skill-default-runbook.test.ts` (test falls back to the reference).
+
+## RD micro-cycle (TDD small-step rapid-test loop)
+
+> **Slice 内部**的修复 / refactor / lint 修复走 micro-cycle（5-10s/cycle）；Slice 边界走 `peaks slice check`。完整手册：`references/micro-cycle.md`。
+
+## Peaks-Loop Project standards preflight
+
+Gather via `peaks standards init/update --project <path> --dry-run`. Standards must reflect the project scan (component library, CSS, build tool, state, routing) — never emit a generic template.
+
+## Peaks-Loop Refactor mode
+
+Read `references/refactor-mode.md` first. Default MVP: `peaks-code refactor`. Red lines: understand before changes, ≥95% UT coverage, split broad refactors, strict verifiable specs, 100% acceptance per slice.
+
+## Peaks-Loop Quality-gate commands (CLI cheat sheet)
+
+Five CLI commands harden the workflow against silent skips: `peaks request lint`, `peaks request repair-status`, `peaks scan request-type-sanity`, `peaks scan libraries`, `peaks slice check` (plus `peaks request transition`). See `references/quality-gate-cheatsheet.md`.
+
+## Peaks-Loop Completion handoff
+
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Use Peaks-Loop TXT for the compact handoff capsule. **Presence management is delegated to the last downstream skill** — peaks-code does not call `peaks skill presence:clear` itself.
+
+## Peaks-Loop Step 11: Memory sediment (BLOCKING on workflow complete)
+
+> **Hard rule.** Code MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Canonical CLI: `peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json` (the artifact-scoped extract; the batch-scoped sibling `peaks project memories:extract` is for non-handoff flows only). Substeps 11a/11b/11c/11d (Gate A/B/C), D-010 fix root cause check → `references/step-11-memory-sediment.md` + `references/runbook.md` §Step 11.
+
+## Peaks-Loop External references and lifecycle
+
+3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7) follow Discovery → Reference → Side effect through Peaks CLI only. Run `peaks capabilities` for capability discovery; treat external skills as reference material only. MCP servers (Playwright / Chrome DevTools / Figma) are user-installed — check the tool list for `mcp__<server>__*` entries. Do not execute upstream installer / run upstream commands / persist sensitive examples / install upstream resources directly — funnel side effects through the Peaks CLI surface. Peaks-Loop Code gates remain authoritative. → `references/external-references.md` + `references/external-skill-invocation.md`.
+
+## Codegraph orchestration context
+
+`peaks codegraph affected` is an optional project-analysis enhancement (untrusted supporting evidence) for role handoff. Code must not treat codegraph output as approval for scope, design, or QA verdict. Never mutate agent settings / hooks from codegraph; do not commit `.codegraph/` artifacts. RD writes `.peaks/_runtime/<sessionId>/rd/codegraph-context.md`; QA / TXT consume the same envelope. → `references/codegraph-orchestration.md`.
+
+## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+
+Main LLM reducer sees metadata-only view (~200 chars/sub-agent); on-demand `Read` for full content. Threshold table: 50% soft warn, 75% `CONTEXT_NEAR_LIMIT`, 80% hard reject (CLI + hook double-guard). → `references/context-governance.md`.
+
+## Sub-agent cross-batch signal — G8.4 share / shared-read / await
+
+Three CLI primitives: `peaks sub-agent share / shared-read / await` (last-write-wins, ≤ 1KB warn / ≥ 64KB reject). Channel gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
+
+## References
+
+Index of every `references/` file. Read on demand.
+
+| File | Coverage |
+|---|---|
+| `references/dag-orchestrator.md` | DAG-aware sub-agent dispatch. |
+| `references/a2a-artifact-mapping.md` | A2A artifact-path mapping. |
+| `references/anchoring-and-session-info.md` | Step 0 + session-conflict. |
+| `references/artifact-contracts.md` | Sub-agent handoff contracts. |
+| `references/boundaries.md` | Code's do / don't list. |
+| `references/browser-workflow.md` | Browser workflow (Playwright MCP). |
+| `references/codegraph-orchestration.md` | Codegraph role handoff. |
+| `references/command-migration.md` | Legacy command migration. |
+| `references/completion-handoff.md` | Completion handoff. |
+| `references/context-governance.md` | G7-G9 sub-agent thresholds. |
+| `references/external-references.md` | 3rd-party inventory + lifecycle. |
+| `references/external-skill-invocation.md` | External skill invocation. |
+| `references/existing-system-extraction.md` | Legacy project extraction. |
+| `references/frontend-only-mode.md` | Frontend-only mode + mocks. |
+| `references/gstack-integration.md` | GStack → Peaks mapping. |
+| `references/headroom-integration.md` | Headroom-ai compression. |
+| `references/local-artifact-workspace.md` | Workspace tree + root-prohibition. |
+| `references/micro-cycle.md` | RD micro-cycle + repair loop. |
+| `references/mode-selection.md` | Step 1 mode + `--mode`. |
+| `references/playwright-mcp-multi-terminal.md` | Multi-terminal Playwright MCP. |
+| `references/project-memory-loading.md` | Step 2.3 memories. |
+| `references/project-scan-checklist.md` | Pre-RD scan + template. |
+| `references/quality-gate-cheatsheet.md` | 5 CLI commands. |
+| `references/refactor-mode.md` | Refactor mode + red lines. |
+| `references/resume-detection.md` | Step 0.7 unfinished-work. |
+| `references/runbook.md` | End-to-end CLI sequence. |
+| `references/job-loop.md` | Step 0.8 / 0.81 / 0.85 / 0.86 / 0.87 deep-dive. |
+| `references/skill-presence-and-title.md` | Step 2 + Step 2.5. |
+| `references/standards-preflight.md` | Standards preflight. |
+| `references/sub-agent-dispatch.md` | IDE-agnostic dispatch. |
+| `references/swarm-dispatch-contract.md` | Swarm fan-out gate + shape. |
+| `references/workflow-gates-and-types.md` | Type classification + 7 gates. |
+| `references/workflow.md` | Workflow flow + transitions. |

package/skills/peaks-code/references/a2a-artifact-mapping.md

@@ -0,0 +1,115 @@
+# A2A artifact mapping (informational)
+
+> Reference for `peaks-code` and any other peaks skill that produces durable artefacts in `.peaks/_runtime/<session-id>/`. Maps peaks's on-disk artefact vocabulary onto the A2A (Agent2Agent) protocol's vocabulary so a future peaks consumer (e.g. an external LLM agent or a downstream peaks-loop extension) can read peaks output without having to learn a brand-new schema. This is a **documentation mapping**, not a protocol implementation: peaks-loop does not speak A2A over HTTP, does not host an AgentCard endpoint, and does not advertise its capabilities via A2A's discovery mechanism. It only uses A2A's *concepts* as a shared naming layer.
+
+## 1. Why this reference exists
+
+The A2A protocol (https://a2acn.com) defines five core concepts: **AgentCard**, **Task**, **Artifact**, **Message**, and **Part**. peaks-loop's session workspace is a parallel vocabulary that grew up independently: `prd/requests/<rid>.md`, `rd/tech-doc.md`, `qa/test-cases/<rid>.md`, etc. The two vocabularies are *not* identical (A2A is HTTP-shaped, peaks is filesystem-shaped), but the A2A concepts are close enough that aligning peaks artefact names with A2A terms in this reference:
+
+- gives an external consumer a single translation table instead of two schemas to learn,
+- lets a peaks operator talk about "the artifact" or "the task" in mixed conversations without losing precision,
+- documents what peaks output is **not** (no SSE streaming, no remote AgentCard), so the limits are explicit.
+
+This is the kind of borrowing that costs zero code and earns some interoperability. It is **not** an integration: peaks-loop does not implement A2A, does not run an A2A server, and does not depend on the a2a-protocol package. Adopting A2A concepts here is the same as adopting any other shared nomenclature (UML, OpenTelemetry, etc.): it improves the conversation, nothing more.
+
+## 2. Concept-to-path mapping
+
+The mapping below uses peaks's own paths verbatim. Each row also notes where peaks **diverges** from A2A, so a reader does not assume parity.
+
+| A2A concept | peaks artefact | Path (under `.peaks/_runtime/<session-id>/`) | Notes |
+|---|---|---|---|
+| **AgentCard** (capability advertisement) | `peaks-skill-output-style` + `.peaks/.active-skill.json` | `.peaks/.active-skill.json`, `.peaks/.session.json` | peaks is a *local* tool, not a service. The "card" is the active-skill file plus a peek at `.peaks/PROJECT.md` for human-readable history. There is no `/.well-known/agent-card.json` endpoint. |
+| **Task** (stateful unit of work) | `peaks request` state machine for a single `<rid>` | `.peaks/_runtime/<sid>/{prd,rd,qa,ui,sc}/requests/<rid>.md` (the request artefact); `.peaks/_runtime/<sid>/<role>/session.json` (per-session metadata) | peaks's task lifecycle is `prd:confirmed-by-user → handed-off`, then per role `draft → spec-locked → implemented → qa-handoff`, then `qa:running → verdict-issued`. The full state graph is enforced by `peaks request transition`. A2A's Task object is JSON; peaks's task is **a set of files with a `state` field per role**. |
+| **Artifact** (immutable output) | `rd/tech-doc.md`, `rd/code-review.md`, `rd/security-review.md`, `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md`, `sc/handoff.md` | as listed | peaks's artefacts are *append-once*, not strictly immutable: a `qa/test-reports/<rid>.md` may be re-emitted on repair cycles. The convention is "newest write wins; the file at the end of the workflow is the truth", which is close enough to A2A's immutable-Artifact semantics for translation purposes. |
+| **Message** (non-artifact communication) | `peaks skill presence` heartbeat + transition `--reason` notes | `.peaks/.active-skill.json` (`lastHeartbeat`), transition notes in `.peaks/_runtime/<sid>/<role>/requests/<rid>.md` | peaks does **not** separate Messages from Artifacts at the storage layer; a "message" is anything that is not the artefact body (the `<!-- peaks-memory:start -->` markers, the `state` field, the `--reason` text on a transition). Treat these as inline metadata of the artefact, not as separate objects. |
+| **Part** (atomic content unit) | Markdown sections within an artefact, frontmatter fields | inline within the artefact | peaks's Artifacts are single Markdown files, so the "Part" concept maps to a heading or a frontmatter field. A `Part`'s `kind` in A2A terms is `text` (the prose), `file` (a `<!-- peaks-memory:start -->` block as a structured chunk), or `data` (the frontmatter). A2A's `form` / `iframe` / video `Part` kinds are not produced by peaks. |
+
+## 3. Field-level mapping (A2A Part ↔ peaks frontmatter)
+
+A2A `Part` has `kind` and `metadata` (free-form) plus `content` (typed by kind). peaks's per-artifact frontmatter carries a subset:
+
+```yaml
+---
+name: <slug>            # used in memory extraction; not a 1:1 A2A field
+description: <title>     # roughly the A2A Artifact.description
+metadata:
+  type: <kind>          # A2A Artifact.kind equivalent
+  sourceArtifact: <rel> # A2A Artifact.source / provenance equivalent
+---
+```
+
+A consumer reading a peaks artefact and translating it to A2A can populate:
+
+- `Artifact.name` ← peaks `name`
+- `Artifact.description` ← peaks `description` (or the first H1)
+- `Artifact.kind` ← peaks `metadata.type`
+- `Artifact.parts[0]` ← the body text (A2A `Part{kind: "text"}`)
+- `Artifact.metadata.sourcePath` ← peaks `metadata.sourceArtifact`
+- `Artifact.metadata.sessionId` ← from `.peaks/.session.json`
+
+The mapping is not 100% lossless: A2A's `Part` can carry structured forms or file references, peaks cannot. That is the explicit *non-goal* of this mapping; it would be over-claiming to assert parity where there is none.
+
+## 4. State-graph mapping (A2A Task ↔ peaks request)
+
+A2A's Task object has a small set of states (typically: `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`). peaks's per-role request state machine is richer and per-role:
+
+| Role | peaks states (in order) | Closest A2A Task state |
+|---|---|---|
+| `prd` | `draft` → `confirmed-by-user` → `handed-off` | `submitted` → `working` → `input-required` (for the confirm gate) |
+| `rd` | `draft` → `spec-locked` → `implemented` → `qa-handoff` | `working` |
+| `qa` | `draft` → `running` → `verdict-issued` (verdict is `pass` / `return-to-rd` / `blocked`) | `working` → `completed` (pass) / `input-required` (return-to-rd) / `failed` (blocked) |
+| `ui` | `draft` → `direction-locked` → `handed-off` | `working` → `completed` |
+| `sc` | `draft` → `recorded` | `working` → `completed` |
+
+A consumer translating peaks states to A2A should:
+
+- collapse peaks's multi-role state machine to a *single* A2A Task state by taking the most progressed of any role,
+- use the A2A `input-required` state to model **any** gate where peaks is waiting for a human (`confirmed-by-user`, `--confirm`, AskUserQuestion for a login wall, etc.),
+- emit `completed` only when QA verdict is `pass` and SC has recorded the change,
+- emit `failed` on `blocked` QA verdict or `blocked` handoff.
+
+## 5. Worked example: a feature slice from start to finish
+
+A user runs `peaks-code` for a "add user authentication" feature. Mapping the resulting files to A2A concepts:
+
+```
+.peaks/_runtime/<sessionId>/prd/requests/001.md      → A2A Artifact (kind=proposal)
+.peaks/_runtime/<sessionId>/ui/requests/001.md       → A2A Artifact (kind=design-direction)
+.peaks/_runtime/<sessionId>/ui/design-draft.md       → A2A Artifact (kind=visual-spec)
+.peaks/_runtime/<sessionId>/rd/tech-doc.md           → A2A Artifact (kind=implementation-plan)
+.peaks/_runtime/<sessionId>/qa/test-cases/001.md     → A2A Artifact (kind=test-cases)
+.peaks/_runtime/<sessionId>/rd/code-review.md        → A2A Artifact (kind=review, status=fixed)
+.peaks/_runtime/<sessionId>/rd/security-review.md    → A2A Artifact (kind=security-review)
+.peaks/_runtime/<sessionId>/qa/test-reports/001.md    → A2A Artifact (kind=test-report, verdict=pass)
+.peaks/_runtime/<sessionId>/qa/security-findings.md  → A2A Artifact (kind=security-findings)
+.peaks/_runtime/<sessionId>/qa/performance-findings.md → A2A Artifact (kind=performance-findings)
+.peaks/_runtime/<sessionId>/sc/handoff.md            → A2A Artifact (kind=change-record)
+.peaks/_runtime/<sessionId>/txt/handoff.md           → A2A Artifact (kind=handoff-capsule)
+.peaks/_runtime/<sessionId>/system/sub-agent-*.json  → A2A Message (sub-agent presence markers)
+.peaks/_runtime/<sessionId>/sc/swarm-plan.json       → A2A Message (the dispatch plan)
+.peaks/memory/*.md                    → A2A Artifact (kind=project-memory, persists across sessions)
+```
+
+A consumer wanting to render a single "feature" object in A2A terms picks the `test-reports/001.md` (verdict=pass) as the terminal Artifact and the rest as supporting Parts or sibling Artifacts. The mapping is intentionally loose: peaks's value is that *all of these files exist*, not that they fit A2A's object model exactly.
+
+## 6. What peaks does NOT provide
+
+To keep the mapping honest, peaks-loop **does not** currently provide the following A2A primitives, and consumers should not expect them:
+
+- A2A **AgentCard** served over HTTP at `/.well-known/agent-card.json`. peaks-loop is a local CLI; its "card" is the on-disk `.peaks/.active-skill.json` plus `peaks skill doctor --json`.
+- A2A **streaming** responses (SSE / WebSocket). peaks commands are synchronous and return a single JSON envelope.
+- A2A **identity / auth** (OAuth, OIDC, mTLS). peaks assumes local-machine trust.
+- A2A **cross-vendor discovery**. peaks has no A2A registry entry; MCP-compatible capabilities are discovered by the LLM via its own tool list (the LLM checks for `mcp__<server>__*` entries in its own function schema) and reported back to the user. Slice #016 retired the `peaks mcp *` indirection layer.
+- A2A **Task delegation across the network**. peaks's "sub-agent" is a Claude Code `Task` tool call in the same process, not a remote A2A server.
+
+These are *deliberate* omissions. peaks-loop solves a different problem (a local workflow-gating CLI for Claude Code), and adopting A2A's networking surface would add weight without addressing peaks's actual failure modes (which are around LLM bypassing gates, not around inter-agent discovery).
+
+## 7. When to re-evaluate
+
+Re-open this mapping in any of the following cases:
+
+- a peaks user reports a real need to share workflow state with a non-peaks agent (e.g. an Autogen / LangChain agent that wants to read a peaks handoff capsule);
+- peaks-loop ships a hosted / multi-user mode where AgentCard-style discovery becomes useful;
+- the A2A protocol stabilises on a thin `Artifact` JSON schema that matches peaks's on-disk shape close enough to make translation a one-liner rather than a reference doc.
+
+Until one of those fires, this reference doc is the entire A2A surface area of peaks-loop. Adding more is over-engineering.

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

@@ -0,0 +1,34 @@
+# Step 0 — Anchor the workflow
+
+> Body of `### Peaks-Loop Step 0: Anchor the workflow`. The instant Peaks-Loop Code is invoked, **before** the mode-selection question, before any analysis, and before you decide whether the request "needs" the full pipeline, you MUST run these two commands and see their output:
+
+```bash
+# Session ID is auto-generated when omitted; the command returns it in the JSON output.
+# Do NOT pass --session-id manually — the CLI is the single source of truth for the
+# project session binding. To look up the active session id from a skill / sub-agent,
+# use `peaks session info --active --json` (read-only, no side effects). To avoid
+# the "two sessions in .peaks/" confusion that bites Code, always omit --session-id
+# here and let the CLI auto-generate.
+peaks workspace init --project <repo> --json
+peaks skill presence:set peaks-code --project <repo> --gate startup
+```
+
+> `<repo>` is the **git project root** (the directory containing `.git`). In a monorepo / single-repo-multi-package layout, this is the repo root, NOT a sub-package — `.peaks/` lives at the repo root so every package shares one workspace. If unsure, run `git rev-parse --show-toplevel` and use that path. Never let `.peaks/` land inside a sub-package directory.
+
+**There is no request too lightweight to skip this.** "分析下这个项目", "看一下代码", "分析项目", "解释一下架构", a one-line question — all of them still create the workspace and set presence first. The workspace is cheap; a missing `.peaks/` is the #1 reported failure.
+
+**Anti-bail-out rule (BLOCKING):** You MUST NOT exit the peaks-code workflow, hand control back, or produce a final answer before Step 0 has run. If you catch yourself thinking "this is just analysis, I don't need the workflow" — STOP. Run Step 0, set presence, then continue. A pure-analysis request runs the **lightweight analysis branch** (project scan + standards dry-run + handoff with a Standards-increment section), but it still anchors the workspace and keeps presence active. Declining to anchor is a workflow violation.
+
+**Session conflict resolution (read once, internalise):** If `peaks workspace init` returns `code: "CONFLICTING_SESSION"` with a body like
+`{"existingSessionId":"<Y>","requestedSessionId":"<X>"}`, the project is already bound to a different in-flight session `<Y>` (the one you or a prior run was working on). The fix is **NOT** to pass `--allow-session-rebind` to clobber `<Y>` — that destroys an active session's data. Instead: finish or abandon `<Y>` first (use `peaks session list --json` to see what it is, then `peaks session finish --id <Y>` or `peaks session abandon --id <Y>` — see your session command's help for the exact verbs). Only after `<Y>` is closed should you re-run `peaks workspace init`. The same rule applies to `peaks workspace init --session-id "<manually-forged>"` — do not pre-forge session ids; the CLI's auto-generated value is the binding.
+
+**Fact-Forcing Gate bypass (slice 2.0.1-bug3):** Claude Code's [Fact-Forcing Gate] fires in two shapes inside peaks-code Step 0: (1) Bash-side "Quote the user's current instruction verbatim. Then retry the same operation." and (2) Write-side 4-facts prompt. Both block the very first Write to `.peaks/_runtime/<sid>/session.json` and the first `peaks skill presence:set peaks-code` invocation. The default `peaks workspace init` (no flag) materializes `.claude/settings.local.json` in the consumer project root with a PreToolUse hook allow-list that exits 0 for tool calls inside `.peaks/**` and for `peaks <whitelisted-subcommand>` Bash commands. The hook bypasses the gate before it fires.
+
+If the bypass is not in effect (e.g. `.claude/` was read-only, or the user passed `--no-claude-hooks`, or the consumer manually deleted the file), the recovery flow is:
+
+1. Re-run `peaks workspace init --project <repo> --json` **without** `--no-claude-hooks`. The next-action list will say "Materialized .claude/settings.local.json (action: written/refreshed)". Restart Claude Code so the hook takes effect.
+2. If `.claude/` cannot be written (read-only mount, container with no write access, etc.), drop the contents of `.peaks/.claude-settings-template.json` into `.claude/settings.local.json` manually. The peaks-loop init always writes the offline template copy (regardless of `--no-claude-hooks`) so the user has a known source-of-truth on disk. After copying, restart Claude Code.
+
+**Anti-bail-out rule for the gate:** Do NOT skip Step 0 because the gate fired. The gate is a Claude Code core feature that peaks-loop cannot modify directly; peaks-loop can only sidestep it via the hook allow-list. If the gate still blocks Step 0 after the bypass is in effect, the user has a misconfigured `.claude/settings.json` upstream — surface that as a separate `AskUserQuestion` ("Your `.claude/settings.json` is overriding the local allow-list. May peaks-loop delete the local file and regenerate it?") rather than skipping Step 0.
+
+`presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-code` from the very first turn even if the user never reaches mode selection.

package/skills/peaks-code/references/artifact-contracts.md

@@ -0,0 +1,65 @@
+# artifact-contracts.md
+
+Default local artifact root: `.peaks/_runtime/<session-id>/` with role subdirectories `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+
+Code coordinates artifact paths and handoff completeness. Keep artifacts local by default. Do not commit, sync, or move them to a git-backed artifact repository unless explicitly authorized.
+
+## Artifact file naming conventions
+
+Each role produces artifacts with predictable file names so cross-role references are stable:
+
+| Role | Directory | File pattern | Produced by | Consumed by |
+|---|---|---|---|---|
+| PRD | `prd/requests/` | `<request-id>.md` | peaks-prd | peaks-ui, peaks-rd, peaks-qa, peaks-txt |
+| UI | `ui/` | `design-draft.md` | peaks-ui | peaks-rd (implementation), peaks-qa (visual regression) |
+| RD planning | `rd/` | `tech-doc.md` | peaks-rd (planning phase) | peaks-rd (implementation phase) |
+| RD project scan | `rd/` | `project-scan.md` | peaks-code (pre-RD scan) | peaks-rd, peaks-ui |
+| RD implementation | `rd/requests/` | `<request-id>.md` | peaks-rd | peaks-qa, peaks-sc, peaks-txt |
+| QA test cases | `qa/test-cases/` | `<request-id>.md` | peaks-qa (pre-implementation) | peaks-rd (TDD guidance), peaks-qa (execution) |
+| QA test reports | `qa/test-reports/` | `<request-id>.md` | peaks-qa (post-execution) | peaks-code (verdict), peaks-txt |
+| QA requests | `qa/requests/` | `<request-id>.md` | peaks-qa | peaks-txt |
+| SC | `sc/` | `<change-id>-impact.md`, `<slice-id>-retention.md` | peaks-sc | peaks-txt |
+| TXT | `txt/` | `handoff-<request-id>.md` | peaks-txt | user (final deliverable) |
+
+## Artifact state transitions
+
+Each artifact has a lifecycle status tracked via `peaks request transition`:
+
+- **PRD**: `draft` → `confirmed-by-user` → `handed-off`
+- **UI**: `draft` → `direction-locked` → `handed-off`
+- **RD**: `draft` → `spec-locked` → `implemented` → `qa-handoff`
+- **QA**: `draft` → `running` → `verdict-issued` (pass | return-to-rd | blocked)
+- **TXT**: `draft` → `finalized`
+
+## Cross-role artifact dependencies
+
+```
+PRD (confirmed-by-user)
+ ├── UI → design-draft.md        reads: PRD artifact
+ ├── RD → tech-doc.md            reads: PRD artifact, project-scan.md
+ ├── QA → test-cases/<id>.md     reads: PRD artifact
+ │
+ ↓ all three complete
+ │
+RD (implementation)              reads: design-draft.md + tech-doc.md + test-cases/<id>.md
+ │
+ ↓ implemented + qa-handoff
+ │
+QA (validation)                  reads: RD implementation artifact + test-cases/<id>.md
+ │                                writes: test-reports/<id>.md
+ ↓ verdict
+ │
+TXT (handoff)                    reads: all artifacts from PRD through QA
+```
+
+## Artifact content requirements
+
+Each role artifact must include these sections at minimum:
+
+- **PRD**: goals, non-goals, acceptance criteria, frontend delta (pages/components affected)
+- **UI**: visual direction, component inventory, responsive breakpoints, accessibility notes
+- **RD tech-doc**: architecture decisions, component tree, data flow, API contracts, dependencies
+- **RD implementation**: slice specs, code changes summary, coverage evidence, CR findings
+- **QA test-cases**: unit tests, integration tests, UI regression tests (per acceptance criterion)
+- **QA test-reports**: test results, browser evidence summary, security/perf notes, verdict
+- **TXT**: mode, validated decisions, artifact paths, standards deltas, open questions, next action

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

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