peaks-loop 3.0.0

package/skills/peaks-solo/references/envelope-contract.md

@@ -0,0 +1,130 @@
+# Envelope contract — `peaks` CLI JSON envelope versioning
+
+> **Slice**: 2026-06-23-audit-4th #E1. Bump on any future breaking change.
+
+## Versioning policy
+
+Every `peaks` CLI action that returns a JSON envelope stamps
+`data.envelopeVersion` on the success path. The version is a
+semver-style string (`MAJOR.MINOR.PATCH`).
+
+- **MAJOR** — breaking change (field removed, field renamed,
+  type tightened). Consumers should refuse to operate on an
+  envelope whose MAJOR version is greater than their pinned version.
+- **MINOR** — additive change (new optional field, new union
+  member). Consumers may ignore unknown fields; old consumers
+  continue to work.
+- **PATCH** — no observable contract change (comment fix, internal
+  refactor that surfaces through serialization).
+
+## Current version
+
+**`2.1.0`** — slice 2026-06-23-audit-4th introduced the marker.
+The only breaking change since `2.0.0` is the removal of
+`data.prompt` from `sub-agent.dispatch` (slice
+2026-06-23-audit-3rd #4).
+
+## Per-command shape
+
+### `sub-agent.dispatch` (single)
+
+Top-level fields (post-2.1.0):
+
+- `envelopeVersion: '2.1.0'`
+- `role: string` — sub-agent role string
+- `ide: string` — detected IDE label (`claude-code` etc.)
+- `originalPromptSize: number` — bytes of the un-compressed prompt
+- `promptSize: number` — bytes after headroom compression (or
+  equal to `originalPromptSize` when `--use-headroom` is off or
+  unavailable)
+- `toolCall: { name: string; args: Record<string, unknown> }` —
+  the per-IDE tool-call descriptor the LLM must execute
+- `dispatchRecordPath: string` — absolute path to the dispatch
+  record on disk
+- `batchId: string` — uuid-like opaque token grouping one batch
+- `dispatchedInBatch: number` — current count after this dispatch
+- `headroomCompressed: boolean` — true if headroom-ai actually
+  reduced the prompt
+- `headroomResult: { mode, compressed, compressionRatio, tokensSaved, warning } | null`
+- `forcedAt: string | null` — ISO8601 when `--force` overrode
+  the G9 hard-reject tier
+- `contextImpact: { promptBytes, artifactBytes, totalBytes }`
+- `artifactMetas: ArtifactMeta[]` — `--write-artifact` results
+
+Removed in 2.0.0: `data.prompt` (audit-3rd #4). Consumers MUST
+read `data.toolCall.args.prompt` for the prompt content.
+
+### `sub-agent.dispatch --from-dag`
+
+Same fields as single dispatch, plus:
+
+- `fromDag: string` — path to the input DAG file
+- `dispatchCount: number` — N toolCalls emitted in this level
+- `levelsTotal: number` — total topological levels
+- `firstLevel: string[]` — slice ids at level 1 (the only ones
+  surfaced to the CLI; levels 2+ are orchestrated internally)
+- `toolCalls: SubAgentToolCall[]` — N tool calls (one per slice)
+- `existingContractCount: number` — number of ancestor contracts
+  spliced into the prompts
+
+### `sub-agent.heartbeat`
+
+- `envelopeVersion: '2.1.0'`
+- `recordPath: string`
+- `heartbeatCount: number`
+- `lastBeatAt: string | null` (ISO8601)
+- `status: 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'stale'`
+- `truncated: boolean` — true if the heartbeats[] array hit the
+  100-entry cap and old entries were dropped
+
+### `sub-agent.share`
+
+- `envelopeVersion: '2.1.0'`
+- `ok: true`
+- `batchId: string`
+- `entryKey: string`
+- `writtenAt: string` (ISO8601)
+- `channelSize: number` — bytes of the channel file after this write
+- `lastWriteWins: boolean` — true if `entryKey` was already present
+- `valueSize: number`
+
+### `sub-agent.shared-read`
+
+- `envelopeVersion: '2.1.0'`
+- `ok: true`
+- `batchId: string`
+- `entries: Record<string, SharedChannelEntry>` — key → entry
+- `totalEntries: number`
+- `channelSize: number` — bytes of the filtered channel
+- `updatedAt: string` (ISO8601)
+
+### `sub-agent.await`
+
+- `envelopeVersion: '2.1.0'`
+- `batchId: string`
+- `ide: string`
+- `results: SubAgentBatchResult[]`
+- `summary: { total, done, failed, cancelled, timeout }`
+
+## Migration policy
+
+When the `MAJOR` version increments, the audit memory doc
+(`.peaks/memory/`) MUST ship a migration memo with:
+
+1. A diff of removed/renamed fields with old → new mapping.
+2. A code-search commit that updates any in-repo consumers
+   (currently only `dispatch-commands.ts`, `heartbeat-commands.ts`,
+   `share-commands.ts`, `dispatch-from-dag.ts`).
+3. A test fixture that pins the v{N-1} → v{N} migration.
+
+For `MINOR` increments, only a changelog line in
+`.peaks/memory/<date>-envelope-<v>.md` is required.
+
+## Why a version field and not just a stable schema
+
+The alternative — Zod-validate the response — was rejected as
+over-engineering for a CLI whose consumers are LLMs (not RPC
+clients). A short `envelopeVersion: '2.1.0'` string is cheap
+for the LLM to ignore when unnecessary, and unambiguous when
+needed: "if you see `envelopeVersion` >= 3.x, do not assume
+`data.toolCall` is still shape-valid."

package/skills/peaks-solo/references/existing-system-extraction.md

@@ -0,0 +1,78 @@
+# Existing visual & convention system extraction
+
+Run this step when `project-scan.md` archetype is `legacy-frontend`, `legacy-fullstack`, or `frontend-monorepo`. Skip for `greenfield` and `unknown`.
+
+Output: `.peaks/_runtime/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file records both UI tokens AND code conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. UI design-draft and RD implementation MUST read this file and treat extracted tokens/conventions as hard constraints. New tokens or conventions may only be introduced when PRD explicitly authorizes them.
+
+## Step 1 — Run the CLI (deterministic, source of truth)
+
+```bash
+peaks scan existing-system --project <repo> --json
+```
+
+The CLI emits stable JSON containing:
+
+- `scanned`: `true | false` (skipped for greenfield / unknown archetypes; copy `scanSkippedReason` if false)
+- `visualTokens`:
+  - `colors[]`, `spacing[]`, `typography[]`, `radii[]` — each entry is `{ name, value, source }` parsed deterministically from Less/Sass variables, CSS variables, and `tailwind.config.*` color blocks
+  - `sources[]` — every theme/style file the parser actually read (path + kind)
+- `conventions`:
+  - `componentNaming`: `PascalCase | kebab-case | mixed | unknown` (decided from real file names under the component directory)
+  - `componentDir`, `serviceDir`, `hookDir` — first matching path found
+  - `samples[]` — up to 5 most-recently-modified files per kind
+- `inconsistencies[]` — token names that have different values across sources
+
+Copy these fields VERBATIM into `existing-system.md`. Do not re-classify tokens; do not invent additional samples.
+
+## Step 2 — Render the markdown
+
+Use the template below. Every value must come from the CLI JSON; leave a section as `- (none detected)` when the CLI returned an empty array.
+
+```markdown
+# Existing visual & convention system
+**Project:** <name>
+**Date:** YYYY-MM-DD
+**CLI command:** peaks scan existing-system --project <repo> --json
+**Source files inspected:** <paste visualTokens.sources[*].path>
+
+## Color tokens
+<paste visualTokens.colors as "- {name}: {value} (source: {source})">
+
+## Typography
+<paste visualTokens.typography>
+
+## Spacing
+<paste visualTokens.spacing>
+
+## Radius
+<paste visualTokens.radii>
+
+## Component conventions
+- Naming: <conventions.componentNaming>
+- Directory: <conventions.componentDir>
+- Sample files: <conventions.samples filtered by kind=component>
+
+## Service layer convention
+- Directory: <conventions.serviceDir>
+- Sample files: <conventions.samples filtered by kind=service>
+
+## Hooks convention
+- Directory: <conventions.hookDir>
+- Sample files: <conventions.samples filtered by kind=hook>
+
+## Detected inconsistencies
+<paste inconsistencies[*] verbatim; if empty, write "- (none)">
+```
+
+## Hard rules for downstream consumers
+
+- **UI design-draft**: every color, font, radius, spacing value used in the draft MUST come from `visualTokens.*` above. New values require an explicit `## New tokens (requested)` section with PRD justification.
+- **RD implementation**: new components must match `conventions.componentNaming` and live under `conventions.componentDir`. Service and hook code must match the recorded directory.
+- **QA**: regression checks must verify that no new color/spacing values escaped the recorded token set; inconsistencies from the CLI become QA acceptance items (resolve or explicitly accept).
+
+## When the CLI returns empty results
+
+If `scanned=true` but all token arrays are empty AND `conventions.componentDir` is null, the project has no detectable token system or component convention. Record this verbatim in `existing-system.md` under `## Detected inconsistencies → no theme system; values are hard-coded across files; no canonical component dir`. Surface it in the TXT handoff as a known risk. Do NOT invent a token system.
+
+When `scanned=false` (archetype = greenfield or unknown), do not write `existing-system.md` at all — the greenfield path applies.
+

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

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

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

@@ -0,0 +1,72 @@
+# Canonical external-skill invocation pattern for Peaks skills
+
+Peaks skills reference many external resources — `mattpocock/skills`, `gstack`, `awesome-design-md`, `taste-skill`, `design-taste-frontend`, `superpowers`, `shadcn/ui`, `React Bits`, `Chrome DevTools MCP`, `Agent Browser`, `Figma Context MCP`, `Penpot`, `Context7`, `SearchCode`, `claude-mem`, `context-mode`, `everything-claude-code`, `Claude Code Best Practice`, `andrej-karpathy-skills`, `OpenSpec`, `GitNexus`, and others.
+
+Every reference must follow the same three-stage pattern so the Peaks gates stay authoritative and side effects stay observable.
+
+> **Slice #016 (2026-06-09)**: peaks-cli no longer manages MCP install or invocation. MCP capability detection moves from the peaks-cli CLI to the LLM's own tool list (the LLM checks for `mcp__<server>__*` entries in its own function schema). Skill bodies instruct the LLM to either invoke the tool by name (when present) or tell the user the install command (when absent).
+
+## Stage 1 — Discovery before naming
+
+Do not name an external skill or MCP server as if it is always available. Route discovery through the Peaks CLI for non-MCP capabilities, and through the LLM's own tool list for MCP capabilities:
+
+- `peaks capabilities --source access-repo --json` for non-MCP capabilities (skills, agents, rules, browser tools).
+- `peaks capabilities --source mcp-server --json` for MCP catalog discovery (which MCPs are *known*, not which are *installed*).
+- For MCP install state, the LLM checks its own tool list for any `mcp__<server>__*` entry. If present, the MCP is installed. If absent, the user installs via the IDE-native MCP install command (e.g. `claude mcp add <server> -- <npx-command>` for Claude Code).
+
+A skill body may mention the capability id, but it must say or imply that the skill only applies "when capability discovery exposes …" (or equivalent phrasing). Skills must not pretend the capability is already installed.
+
+## Stage 2 — Reference, never auto-execute
+
+External skills are inspection material for the role's own artifacts. They are not auto-runnable workflows. Every reference must:
+
+- explicitly say it is a reference (e.g. "use these upstream methods as <role> references only");
+- name the specific methods or surfaces the role borrows;
+- forbid executing upstream instructions, installing upstream resources, persisting upstream examples, or running upstream installers;
+- declare that the Peaks role artifacts remain authoritative.
+
+For MCP servers, the LLM consumes the install state from its own tool list. Skill bodies tell the LLM: "if the tool is present, invoke it by name; if absent, surface the install command for the user's IDE and stop until the user installs the MCP". peaks-cli does not install MCPs on the user's behalf as of slice #016.
+
+## Stage 3 — Side effect through Peaks CLI only
+
+The skill body must not silently:
+
+- install hooks;
+- create agents;
+- enable or configure an MCP server;
+- modify `~/.claude/settings.json` or project `.claude/settings.json`;
+- write to `.codegraph/`, `.openspec/`, or other upstream tool state;
+- store tokens, cookies, login URLs, headers, storage state, or PII / SSO / MFA browser material;
+- commit or sync intermediate artifacts;
+- create remote repositories.
+
+All of these must route through the Peaks CLI under the appropriate command (`peaks artifacts …`, `peaks memory …`, `peaks openspec …`, `peaks standards …`, `peaks codegraph …`, `peaks capabilities …`), with dry-run preview where supported and `--yes` / `--apply` where a real write is required. The `peaks mcp …` command tree was retired in slice #016; MCP install / dispatch is the LLM runtime's job, not the CLI's.
+
+## Allowed in-process references
+
+Some references are not external skills but project-approved utilities and may be named directly without the discovery stage:
+
+- `peaks` CLI commands (this binary).
+- `npx`, `npm`, `pnpm`, `yarn`, package managers — only as the underlying mechanism when a `peaks` CLI command spawns them.
+- `mcp__chrome_devtools__*` — Chrome DevTools MCP tools exposed by the LLM's MCP runtime when the user has installed Chrome DevTools MCP (Claude Code: `claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest`). Skill bodies tell the LLM to invoke these tools by name when they appear in the tool list. Login / CAPTCHA / SSO / MFA handoff rules and sanitization rules in `browser-workflow.md` still apply.
+
+These are not subject to capability discovery because they are part of the Peaks engineering surface, not external skills. The previous `gstack/browse/dist/browse` binary reference is no longer endorsed — see `browser-workflow.md` for the migration recipe.
+
+## Common phrasing the audit looks for
+
+The skill-external-invocation dogfood test scans skill bodies for:
+
+- a `capability discovery exposes` clause or equivalent before naming a discoverable external skill;
+- a `references only` / `reference material` / `reference resources` phrase qualifying any external skill name;
+- a `do not execute upstream instructions` / `do not run upstream installer flows` / `do not persist sensitive examples` clause;
+- a `Peaks` authoritative-gate clause (e.g. "Peaks gates remain authoritative", "Peaks artifacts remain authoritative", "Peaks acceptance authority").
+
+When a skill body adds a new external reference, it must include the equivalent phrasing or the audit test fails.
+
+## Repair recipe when audit fails
+
+1. read the failing skill body section;
+2. identify the external skill or MCP that triggered the failure;
+3. add the capability discovery clause, the reference-only qualifier, the do-not-execute clause, and the Peaks-authoritative gate to that section;
+4. for MCP servers, point the LLM at the tool-list self-check (its own `mcp__<server>__*` namespace) instead of describing manual `~/.claude/settings.json` edits;
+5. rerun the audit.

package/skills/peaks-solo/references/fanout-mandatory.md

@@ -0,0 +1,109 @@
+# Fan-out is mandatory (slice 2026-06-24-audit-5th-p2)
+
+> **Reference contract.** Slice 5 (`feat(solo): default to multi-sub-agent
+> fan-out when DAG has >= 2 same-level leaves`) shipped in 2.8.0 with
+> `'fan-out'` as the default but kept `'serial'` as an opt-out. Slice
+> 2026-06-24-audit-5th-p2 (this slice, 2.8.4) **removes the opt-out** by
+> user direction: single-sub-agent dispatch is no longer permitted when
+> the DAG has ≥ 2 leaves at one topological level. This file is the
+> canonical rationale + migration contract for that breaking change.
+
+## Why the opt-out was removed
+
+The 2.8.3-era `'serial'` mode was originally added to support four
+caller personas (deterministic logs, single-sub-agent rate limits,
+replay harnesses, step-by-step debugging). After a multi-cycle audit
+(2026-06-23 → 2026-06-24), the operator concluded:
+
+- **Deterministic logs** — achievable via `peaks slice check --verbose
+  --no-color` per-slice logs, no opt-out needed.
+- **Rate limits** — handled at the LLM-side runner's batch budget, not
+  by serializing the dispatch shape (fan-out's `dispatchCount === N`
+  still gives the platform one batch to schedule concurrently).
+- **Replay / step-debug** — already covered by `peaks contract write`
+  + `peaks sub-agent dispatch --batch-id <existing>`; replay targets
+  one slice by id, no need to disable fan-out at the orchestrator.
+- **The opt-out masked a foot-gun**: a user setting `'serial'` got
+  `dispatchCount === 1` per CLI invocation and silently turned the
+  orchestrator into a serial runner — wall-time `sum`, not `max`.
+
+The hard constraint is now: when the slice DAG has ≥ 2 leaves at the
+same topological level, the orchestrator MUST use `--from-dag` and
+emit N parallel `buildToolCall` envelopes in one batch. There is no
+preference, env-var, or CLI flag that overrides this.
+
+## Default rule (unchanged)
+
+```text
+topological-level leaf count ≥ 2
+  → peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>
+  → dispatchCount === N (parallel)
+  → wall-time ≈ max(per-slice latency), not sum
+
+topological-level leaf count === 1
+  → peaks sub-agent dispatch <role> --prompt ...
+  → dispatchCount === 1 (single dispatch is fine; only one slice exists)
+```
+
+`config | docs | chore` request types still skip Swarm (no DAG emitted).
+
+## Migration: legacy `'serial'` preferences.json
+
+A project that wrote `'serial'` into `.peaks/preferences.json` between
+2.8.3 and 2.8.4 will see the following when it next runs `peaks`
+(any CLI that calls `loadPreferences`):
+
+```text
+PREFERENCES_FANOUT_INVALID: fanout.defaultMode must be one of fan-out
+  (got "serial") in .peaks/preferences.json. The 'serial' opt-out was
+  removed in 2.8.4 — remove the fanout block to use the fan-out default.
+```
+
+**Recovery:** delete the `fanout` block from `.peaks/preferences.json`
+(keeping the rest of the file intact), or run `peaks preferences
+migrate --write` which rewrites `serial` → `fan-out` automatically
+and surfaces a `changes[]` entry:
+
+```text
+fanout.defaultMode rewrote 'serial' → 'fan-out' (the 'serial' opt-out
+  was removed in 2.8.4; single-sub-agent dispatch is no longer
+  permitted when DAG has >= 2 leaves)
+```
+
+## Schema reference (locked)
+
+Defined in `src/services/preferences/preferences-types.ts`:
+
+```typescript
+export type FanoutMode = 'fan-out';
+
+export const FANOUT_MODES: readonly FanoutMode[] = ['fan-out'];
+
+export interface FanoutPreference {
+  /** Hard-coded mode. Slice 2026-06-24-audit-5th-p2 removed the serial opt-out. */
+  readonly defaultMode: FanoutMode;
+}
+
+// DEFAULT_PREFERENCES
+fanout: { defaultMode: 'fan-out' }
+```
+
+`FANOUT_MODES` is intentionally exported with a single element so the
+type guard (`isFanoutMode`) can keep the same closed-set validation
+shape it had pre-slice — the difference is that anything outside
+`'fan-out'` now throws instead of being silently coerced to default.
+
+## Tests
+
+- `tests/unit/solo/skills-solo-fanout-mandatory.test.ts` — pins that
+  SKILL.md still mentions `--from-dag`, does NOT mention `serial`
+  opt-out, and references `references/fanout-mandatory.md`.
+- `tests/integration/solo/multi-sub-agent-fanout.test.ts` — pins the
+  runtime fan-out behavior; not affected by this slice.
+
+## Rollout
+
+This is a **breaking change** for any project that opted into
+`defaultMode = 'serial'`. The migration path is automatic on next
+`peaks` run (silent coercion via `migratePreferences`); manual
+recovery is `delete the fanout block from preferences.json`.

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

@@ -0,0 +1,23 @@
+# Solo fast mode (slice 2 — round-trip ≤ 30s)
+
+For hot-fix / small-bug slices where the full 5-step workflow is overkill,
+use **fast mode**: `peaks solo plan --fast <change-id>`. Fast mode skips
+three steps that dominate cold-start cost:
+
+| Step | Default | Fast |
+|------|---------|------|
+| `load-memory` (full `.peaks/memory/*` load) | run | **skip** (use last-touched subset / `--tag` filter) |
+| `standards-preflight` (5-axis rule fan-out) | run | **skip** |
+| `qa-cycle` (single round + repair loop) | repair=on | repair=off |
+| `rd-cycle`, `emit-txt` | run | run |
+
+## Acceptance gate
+
+`test pass + tsc pass + lint pass` = GO. Single QA round, NO repair loop.
+Use fast mode only when the user explicitly opts in (default stays
+conservative).
+
+## Karpathy-4 in fast mode
+
+= condensed 1-paragraph version (not the full 4-block injection).
+Full guidelines still apply, just shipped inline as one block.

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

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

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

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

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

@@ -0,0 +1,107 @@
+# Headroom Integration — G7.7 opt-in compression channel
+
+> Slice #010 (G7.7 headroom-ai integration route).
+> Source: https://github.com/chopratejas/headroom
+> Package: `headroom-ai@0.22.4` (Apache-2.0, MIT-compatible).
+> See: `THIRD_PARTY_LICENSES.md` for the license record.
+
+## Why headroom-ai is justified (R-14)
+
+The dev-preference red line "非必要不添加新的 dep" is preserved:
+headroom-ai is the only opt-in mechanism for G7.7 + G9 to compress
+sub-agent prompts that exceed the 75% / 80% threshold. Without
+headroom-ai, `--use-headroom` is a no-op and the only fallback is
+`--force` override at CLI.
+
+The user's explicit reference (https://github.com/chopratejas/headroom)
+is the basis for the dev-preference override.
+
+## API shape (real SDK, not the PRD's spec)
+
+```ts
+import { compress } from 'headroom-ai';
+
+const result = await compress(messages, {
+  model: 'claude-sonnet-4-5-20250929',
+  baseUrl: 'http://localhost:8787',  // local proxy; not used in slice #010
+  apiKey: 'hr_...',                   // Headroom Cloud; not used in slice #010
+  timeout: 30_000,
+  fallback: true,                     // CRITICAL: return original messages if proxy is dead
+  retries: 1,
+  tokenBudget: 4000,                  // compress to fit this limit
+  hooks: new MyHooks(),               // pre/post compression hooks
+});
+
+result.messages          // compressed messages
+result.tokensBefore      // original token count
+result.tokensAfter       // compressed token count
+result.tokensSaved       // tokens removed
+result.compressionRatio  // tokensAfter / tokensBefore
+result.transformsApplied // e.g. ['router:smart_crusher:0.35']
+result.compressed        // false if fallback kicked in
+```
+
+`fallback: true` is the key option: if the proxy is unavailable, the SDK
+returns the original messages + `result.compressed: false` instead of
+throwing. This makes the failure mode non-blocking (RL-22d / RL-32).
+
+## Mode table (peaks wrapper)
+
+The peaks wrapper maps the user-facing `HeadroomMode` to the SDK's
+`tokenBudget` option. Slice #010 does not consume the SDK's internal
+"audit" / "optimize" / "simulate" modes (those are SDK-internal);
+
+| Mode | tokenBudget | Use case |
+|---|---|---|
+| `balanced` (default) | promptSize * 0.40 / 4 | General sub-agent dispatch |
+| `aggressive` | promptSize * 0.20 / 4 | Last-resort large prompt |
+| `conservative` | promptSize * 0.70 / 4 | Sensitive code analysis, accuracy-critical |
+
+The `0.40 / 4` factor approximates 60% byte reduction (1 token ≈ 4 bytes
+for English text). The SDK does its own tokenization internally; the
+`tokenBudget` is a hint, not a hard cap.
+
+## Failure semantics (RL-22d / RL-32)
+
+- `result.compressed === false` → `code: "HEADROOM_UNAVAILABLE"` warning
+- `compress()` throws (network error, JSON parse error) → caught and treated as `HEADROOM_UNAVAILABLE`
+- Import failure (headroom-ai not installed) → caught and treated as `HEADROOM_UNAVAILABLE`
+- **NOT blocking** — peak falls back to G7 metadata-only and continues dispatch
+
+## CCR reversible hydration (slice #011+ TODO)
+
+The PRD mentions "CCR (Cross-Context Reversible)" as a benefit of
+headroom. In the SDK, this is implemented via the `hooks` option on
+`compress()`. A pre/post hook can persist the `ccrHashes` to disk,
+and a later `rehydrate()` call can re-hydrate the compressed prompt
+to the original. Slice #010 does NOT consume CCR — it only uses
+compression. R-17 (CCR for aggressive / conservative modes) is
+deferred to slice #011+.
+
+## Cross-platform behavior (R-19)
+
+- In-process compression (the SDK's library mode) is platform-agnostic.
+- The long-running `headroom proxy` daemon is platform-specific
+  (Unix socket on Linux/macOS, named pipe on Windows). Slice #010
+  does NOT consume the proxy daemon.
+- All headroom-ai calls in slice #010 go through the in-process SDK
+  with `fallback: true`. The peak wrapper at
+  `src/services/context/headroom-client.ts` catches all errors and
+  treats them as fallback.
+
+## What slice #010 does NOT do
+
+- Does NOT install the `headroom proxy` daemon (N-7).
+- Does NOT consume headroom's `SharedContext` directly (G7.7.3 in the
+  PRD); the peak-internal `SharedChannel` (G8) is the cross-sub-agent
+  state store. `buildSharedContextBridge()` is a stub that returns
+  the peak-internal channel ID + a placeholder headroom context ID.
+- Does NOT use the SDK's `audit` / `optimize` / `simulate` modes
+  (those are SDK-internal; the peak wrapper exposes
+  `balanced` / `aggressive` / `conservative` to the user).
+
+## Security + license
+
+- License: Apache-2.0 (MIT-compatible) — see `THIRD_PARTY_LICENSES.md`.
+- Pinned version: exact `0.22.4` (no `^` / `~` range) per dev-preference.
+- `pnpm audit` ran on install; no new high-severity vulnerabilities.