peaks-loop 3.0.0

package/skills/peaks-solo/references/browser-workflow.md

@@ -0,0 +1,127 @@
+# Headed browser workflow for Peaks skills
+
+Peaks skills standardize on **Playwright MCP** as the controlled headed-browser surface for opening a browser on demand (PRD authenticated docs, UI design inspection, QA E2E validation). Chrome DevTools MCP is a secondary surface that **connects to an existing Chrome instance launched with `--remote-debugging-port=9222`** — it does not launch a browser on its own. Picking the right tool for the right job is critical:
+
+| Need | Tool | Why |
+|---|---|---|
+| Open a controlled browser when the user supplies a URL | **Playwright MCP** | Spawns its own browser instance per session; no prerequisite. |
+| Drive console/network/performance inspection on a Chrome the user already has open | Chrome DevTools MCP | Connects via CDP to an existing Chrome on `:9222`. |
+| Frontend E2E validation that needs to start, navigate, capture, close | **Playwright MCP** | Headed mode, full lifecycle in one tool. |
+| Live page debugging where the user wants to keep their own Chrome session in front | Chrome DevTools MCP | Stays attached without disrupting the user's tabs. |
+
+> **Bug history**: an earlier version of this document recommended Chrome DevTools MCP for "open a headed browser when peaks-solo gets a product document link." Dogfood testing in 2026-05 revealed the tool requires a pre-running Chrome with remote debugging enabled — it does NOT launch its own browser. Playwright MCP is the correct tool for the "open on demand" case.
+
+> **Slice #016 (2026-06-09)**: peaks-cli no longer manages MCP install / dispatch. Skill bodies instruct the LLM to (a) check its own tool list for any Playwright MCP entry, (b) invoke the tool by name if present, (c) tell the user the install command if absent. There is no peaks-cli MCP indirection layer anymore.
+
+## When to open the headed browser
+
+Open a controlled browser when:
+
+- PRD source is an authenticated product document (Feishu/Lark, Notion, internal wiki) and the URL passes the allow-list check.
+- UI design or full-auto frontend work needs visible regression observation.
+- QA needs E2E validation on a frontend, including console / network / accessibility / performance inspection.
+
+Never open a browser to bypass authentication, run arbitrary URLs the user has not approved, or interact with payment / delete / authenticated mutation flows without explicit user confirmation.
+
+## Playwright MCP — install + detect
+
+The LLM runtime exposes Playwright's tools under the `mcp__playwright__*` namespace when the user has installed the MCP. Skill bodies MUST NOT bake the prefix into a SKILL.md or reference; the prefix is owned by the LLM runtime.
+
+**Detect**: the LLM checks its own tool list for any `mcp__playwright__*` entry. If present, the MCP is installed; the LLM invokes the tool by name (e.g. `browser_navigate`, `browser_take_screenshot`).
+
+**Install (if absent)**: skill bodies surface the install command to the user. The user runs it themselves — peaks-cli does not hand-edit `~/.claude/settings.json`.
+
+- Claude Code:
+  ```bash
+  claude mcp add playwright -- npx @playwright/mcp@latest
+  ```
+  Restart Claude Code (or reload the window) so the MCP runtime picks up the new server.
+
+- Other IDEs (Trae, Cursor, Codex, Qoder, Tongyi, ...): consult the IDE's MCP install docs. The install command and the runtime prefix differ per IDE; the LLM checks the tool list rather than assuming a prefix.
+
+The skill body uses the LLM's tool list as the source of truth — never the cached `~/.claude/settings.json` (the LLM cannot read the file, and the file's contents may have drifted from runtime state).
+
+## Chrome DevTools MCP — optional, secondary surface
+
+When inspecting an already-running Chrome (e.g., the user's own browser session opened with `chrome --remote-debugging-port=9222`), the LLM checks its tool list for any `mcp__chrome_devtools__*` entry. If present, the LLM invokes the tool by name directly (e.g. `list_pages`, `take_screenshot`, `performance_start_trace`).
+
+Install (if absent) is the user's responsibility:
+
+- Claude Code:
+  ```bash
+  claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+  ```
+
+Chrome DevTools tools fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design and the skill must surface it as a blocked precondition, not silently fall back.
+
+## Tool mapping for the "open a browser on demand" path (Playwright MCP)
+
+The LLM invokes these tools directly from its `mcp__playwright__*` namespace. Peaks skill bodies describe the args shape; the LLM supplies them.
+
+| Verb | Direct invocation (LLM tool list) | Notes |
+|---|---|---|
+| Open visible browser and navigate | `browser_navigate --args '{"url":"<url>"}'` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
+| Confirm visible browser opened | `browser_take_screenshot --args '{"filename":"<abs-path>"}'` | Screenshot is the visible-browser confirmation. |
+| Read structured page (text + a11y) | `browser_snapshot --args '{}'` | Accessibility tree with element refs. |
+| Click / fill / press key | `browser_click --args '<args>'` (and `browser_type`, `browser_press_key`) | Drive the page after navigation. |
+| Inspect console errors | `browser_console_messages --args '{"level":"error"}'` | Pass `level` to filter (`error`, `warning`). |
+| Inspect network failures | `browser_network_requests --args '{"filter":"<regex>"}'` | Pass `filter` regex when the page has many requests. |
+| Resize viewport for responsive checks | `browser_resize --args '<args>'` | |
+| Capture a full-page screenshot | `browser_take_screenshot --args '{"filename":"<abs-path>","fullPage":true}'` | Sanitize before retention. |
+| Close the session cleanly | `browser_close --args '{}'` | End-of-task. |
+| **Runtime prefix (LLM-owned, do not bake into skills)** | `mcp__playwright__<toolName>` | The Claude Code / Trae / etc. runtime prefix; the LLM resolves this from the registered server. |
+
+## Tool mapping for the "connect to running Chrome" path (Chrome DevTools MCP, optional)
+
+| Verb | Direct invocation (LLM tool list) | Notes |
+|---|---|---|
+| List pages in user's Chrome | `list_pages --args '{}'` | Requires Chrome already running with `--remote-debugging-port=9222`. |
+| Bring a tab to front | `select_page --args '{"bringToFront":true}'` | Useful when the user navigated themselves. |
+| Screenshot the visible viewport | `take_screenshot --args '<args>'` | |
+| Read structured page | `take_snapshot --args '{}'` | |
+| Performance trace | `performance_start_trace --args '<args>'` then `performance_stop_trace` | |
+| Lighthouse audit | `lighthouse_audit --args '{"mode":"snapshot"}'` | |
+| **Runtime prefix (LLM-owned, do not bake into skills)** | `mcp__chrome_devtools__<toolName>` | The Claude Code / Trae / etc. runtime prefix; the LLM resolves this from the registered server. |
+
+If Chrome is not running on `:9222`, every Chrome DevTools MCP tool fails. The skill must surface that as a blocked precondition, not silently fall back.
+
+## URL allow-list (always required before navigation)
+
+Before invoking `browser_navigate --args '{"url":"<url>"}'` (or any other navigation), verify:
+
+1. URL uses `https:` (reject `http:`, `file:`, `data:`, `javascript:`).
+2. Host belongs to an approved domain for the role (Feishu/Lark tenant for PRD product docs, the user-approved app target for UI/QA validation).
+3. Reject `localhost`, loopback, link-local, raw IP, and private IP unless the user explicitly approves a controlled local test target.
+4. Reject the navigation entirely if any check fails and surface the reason to the user. Do not silently downgrade to an unauthenticated fetch.
+
+## Login / CAPTCHA / SSO / MFA handoff
+
+If the page redirects to a login challenge:
+
+1. Do not auto-fill credentials. Do not bypass authentication.
+2. The headed browser is already visible; surface that to the user and wait for explicit confirmation that they have completed authentication. Do not assume a state transition from any DOM signal alone.
+3. After the user confirms, resume with `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests` as needed for the role artifact.
+4. If the user cannot complete authentication, mark the role artifact `blocked` with a sanitized reason category (`login-required`, `mfa-required`, `access-denied`) and the exact next user action.
+
+## Sensitive data sanitization
+
+Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifacts:
+
+- Login URLs, redirect URLs, OAuth callback URLs containing tokens or state.
+- Cookies, request or response headers, session tokens, storage state, QR payloads.
+- Raw network logs.
+- Raw browser state, browser traces.
+- Screenshots or logs containing PII, SSO challenge content, or MFA material.
+
+Redact sensitive values before retention. Store evidence as sanitized observations (e.g., "user reached settings page; first 3 list items had a missing-image regression") rather than raw captures.
+
+## Fallback when Playwright MCP is not installed
+
+If the LLM tool list does not include `mcp__playwright__*`:
+
+1. Surface the install command for the user's IDE (the Claude Code install is `claude mcp add playwright -- npx @playwright/mcp@latest`; other IDEs differ).
+2. Do not silently fall back to unauthenticated fetch tools, screenshots-only, or manual transcription.
+3. Frontend QA workflows that require headed browser validation mark the gate `blocked` with the install command in the next action. Manual steps or text-only fetching do not substitute for the mandatory headed browser gate.
+4. Restart the IDE after install; the runtime picks up the new server only after a fresh process / window reload.
+
+Peaks role artifacts (PRD / UI / RD / QA) remain authoritative for what evidence the role recorded; Playwright MCP is the tool, not the verdict.

package/skills/peaks-solo/references/checkpoint-resume.md

@@ -0,0 +1,70 @@
+# Step 0.75: checkpoint resume — full probe + decision tree
+
+## Mid-session resume
+
+When a NEW conversation opens on a session whose `lastActivity` is from the
+SAME date as today (within minutes/hours), the LLM should surface the most
+recent checkpoint so the user can resume mid-session without losing context.
+
+## When this step fires (resume)
+
+Only when ALL of the following hold:
+
+1. Canonical `<sessionId>` is bound (resolved via `peaks session info --active`).
+2. `<sessionId>` lastActivity is from today's date (`YYYY-MM-DD` matches).
+3. `lastActivity` time-of-day is recent (within minutes/hours, not days).
+4. `.peaks/_runtime/<sessionId>/checkpoints/` contains at least one `*.json` file.
+
+If any of these are false, Step 0.75 is a no-op and the skill proceeds to Step 1 (mode selection).
+
+## Resume probe
+
+```sh
+sid=$(peaks session info --active --json | jq -r '.data.sessionId // empty')
+[ -z "$sid" ] && exit 0
+last=$(jq -r '.lastActivity // empty' ".peaks/_runtime/$sid/session.json" 2>/dev/null)
+today=$(date -u +%Y-%m-%d)
+[ "${last:0:10}" != "$today" ] && exit 0
+latest=$(ls -1t ".peaks/_runtime/$sid/checkpoints/"*.json 2>/dev/null | head -1)
+[ -z "$latest" ] && exit 0
+echo "$latest"
+```
+
+## Resume decision tree
+
+```
+If a checkpoint path exists:
+  LLM prompts the user via IDE-native ask_user_question:
+    Q: "Resume from checkpoint <basename> (last saved <relative-time>)?
+        1: resume (recommended), 2: start fresh."
+  A1 -> peaks session resume --from <path> --project <repo>
+        prepend the emitted markdown block to the skill's own prompt
+  A2 -> ignore the checkpoint; proceed to Step 1
+
+Else:
+  proceed to Step 1 (mode selection)
+```
+
+## Resume CLI contract
+
+`peaks session resume --from <path> [--project <path>] [--json]`
+
+- Reads the checkpoint JSON at `<path>`.
+- Emits a markdown "resume context" block on stdout (or in the `--json` envelope) listing the captured state: session id, captured at, last activity, reason, relative age, current plan, open questions, recent decisions, recent artifact paths, todo state, active skills, git status.
+
+Alternative discovery when the caller does not have the path handy:
+
+`peaks session resume --session-id <sid> [--project <path>]`
+
+This resolves the latest checkpoint for the given `<sid>` automatically.
+
+## Resume edge cases
+
+- **No checkpoint dir**: Step 0.75 is a no-op; proceed to Step 1.
+- **Multiple checkpoints**: use the latest by mtime (`ls -1t`).
+- **Checkpoint JSON malformed**: CLI throws `SyntaxError`; treat as "no resume possible" and proceed to Step 1.
+- **User picks "fresh" but session is recent**: honor the choice; the on-disk checkpoint stays untouched for the next invocation.
+
+## Resume IDE note
+
+This step is strictly IDE-agnostic. All checkpoint discovery goes through the peaks CLI.

package/skills/peaks-solo/references/codegraph-orchestration.md

@@ -0,0 +1,5 @@
+# Codegraph orchestration context
+
+> Body of `## Codegraph orchestration context`. 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.

package/skills/peaks-solo/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-solo.

package/skills/peaks-solo/references/completion-handoff.md

@@ -0,0 +1,18 @@
+# Completion handoff
+
+> Body of `## Peaks-Cli Completion handoff` + `### Workflow completion (no auto-exit)`.
+
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Merge scan-backed changes incrementally; preserve hand-maintained content unless user confirms deletion.
+
+Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas (`CLAUDE.md` and `.claude/rules/**` statuses), open questions, next action. Do not restate the full workflow log.
+
+## Workflow completion (no auto-exit)
+
+peaks-solo does NOT itself call `peaks skill presence:clear --project <repo>` at workflow end. Presence management is delegated to the last downstream skill in the workflow (peaks-rd, peaks-qa, peaks-txt); each of those skills owns its own presence:clear step per its SKILL.md. peaks-solo only sets presence: it does not unset it.
+
+The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo` to do so. The header continues to display whatever skill is active; the user can `/peaks-solo` again to re-anchor.
+
+Before ending, extract durable memories from this session:
+```bash
+peaks project memories:extract --session-id <session-id> --project <repo> --json
+```

package/skills/peaks-solo/references/context-governance.md

@@ -0,0 +1,204 @@
+# Context Governance — G7 + G7.7 + G8 + G9 protocol details
+
+> Slice #010 (G7 + G7.7 + G8 + G9 context-governance push).
+> See: `.peaks/memory/sub-agent-context-minimal-occupation.md` + `sub-agent-shared-channel-cross-completion.md` + `sub-agent-headroom-forced-compression-gate.md` for the red lines.
+
+## G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
+
+### Path convention
+
+```
+.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>
+```
+
+### ArtifactMeta schema
+
+```ts
+interface ArtifactMeta {
+  readonly path: string;
+  readonly size: number;
+  readonly sha256: string;
+  readonly status: 'created' | 'finalized' | 'partial' | 'failed';
+  readonly contentInlined: false;  // mandatory literal
+  readonly summary: string | null; // ≤ 200 chars
+  readonly writtenAt: string;
+  readonly rid: string;
+  readonly role: string;
+  readonly idx: number;
+}
+```
+
+### Sub-agent completion protocol (G3 + G7.4.g)
+
+```
+On completion:
+1. Write artifact to .peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>
+2. Call `peaks sub-agent dispatch --write-artifact <path>` (or via --write-artifact on dispatch)
+   → CLI computes sha256 + size + writes ArtifactMeta to record
+3. Call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>` (G8.6)
+```
+
+### Main LLM reducer view (G7.4.e)
+
+```
+[peaks-solo] batch 3/3 done in 47.3s
+- rd → .peaks/_sub_agents/2026-06-06-session-5b1095/artifacts/003-rd-001.md (12KB, sha256:abc123) summary: "wrote RD tech-doc with 4 sub-roles and dispatcher interface"
+- qa-business → .../artifacts/003-qa-business-001.md (8KB, sha256:def456) summary: "wrote 12 API test cases covering happy + 3 error paths"
+- qa-perf → .../artifacts/003-qa-perf-001.md (5KB, sha256:ghi789) summary: "wrote perf baseline; p95 latency target ≤ 200ms"
+```
+
+### Numerical budget
+
+| 方案 | Per sub-agent | 3-sub-agent batch | 6-sub-agent batch |
+|---|---|---|---|
+| Old: inline full content | 1MB typical | 3MB | 6MB |
+| **G7 metadata-only (this slice)** | ~200 chars | **600 chars** | **1.2KB** |
+
+3000-5000× improvement. Main LLM full-slice context net increase: < 10KB for 5 batches × 6 sub-agents.
+
+## G7.7 — headroom-ai integration (opt-in)
+
+### `--use-headroom` flag
+
+Opt-in flag on `peaks sub-agent dispatch`. Default `false` (G7 metadata-only remains the default).
+
+### Mode table
+
+| 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 |
+
+### Failure mode (RL-22d / RL-32)
+
+- headroom daemon dead / proxy unreachable / times out
+- → `code: "HEADROOM_UNAVAILABLE"` warning + G7 metadata-only fallback
+- → NOT blocking (warn, then continue dispatch)
+
+## G8 — cross sub-agent shared channel
+
+### Path convention
+
+```
+.peaks/_sub_agents/<sid>/shared/<rid>-<batchId>.json
+```
+
+### Two new CLI atoms
+
+```
+peaks sub-agent share --batch <batchId> --key <k> --value <json> --json
+  Writes a shared entry. Last-write-wins by key. value ≤ 1KB soft warn, ≥ 64KB rejected.
+
+peaks sub-agent shared-read --batch <batchId> [--since <iso>] [--key <pattern>] --json
+  Reads entries. --key is a glob pattern with * wildcard.
+```
+
+### Sub-agent prompt template (G8.6)
+
+```
+You are sub-agent role <role>, batch <batchId>.
+
+PROTOCOL (mandatory):
+1. On start: peek at shared channel: `peaks sub-agent shared-read --batch <batchId> --json`
+   to see what other sub-agents in this batch have shared so far.
+2. While running: if you find a blocker or partial work, write share entry
+   `peaks sub-agent share --key "<role>.found-blocker" --value {"reason": "..."}`
+   so other in-flight sub-agents can avoid duplicating effort.
+3. On completion: write share entry
+   `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`
+   BEFORE the final `peaks sub-agent heartbeat --status done` heartbeat.
+4. The shared channel is your only visibility into sibling sub-agents.
+   Do NOT attempt to read other sub-agents' dispatch records directly.
+```
+
+### RL-23 completion-time mandatory write
+
+- When sub-agent calls `peaks sub-agent heartbeat --status done`, it MUST also call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`.
+- If sub-agent omits the share, heartbeat still succeeds but emit warning `code: "COMPLETED_WITHOUT_SHARE"`.
+
+## G9 — forced compression gate
+
+### Threshold table (256K default context capacity)
+
+> **Slice 2026-06-23-audit-4th #F4:** the canonical source is
+> `src/services/context/threshold.ts` (4 tiers: `ok` / `soft-warn` /
+> `near-limit` / `hard-reject` / `emergency`). When editing this
+> table, ALSO edit the constants in `threshold.ts` — drift between
+> the two is a contract bug. Pre-#F4 the doc listed
+> `+ contextWarning: 'high'` for 90%, which did NOT match the
+> in-code `code: "PROMPT_EMERGENCY"`. The row below is the
+> post-#F4 fix.
+
+| Threshold | Prompt size | Behavior |
+|---|---|---|
+| 50% (early warn) | ≥ 128KB | Soft warning, suggest `--use-headroom` |
+| **75% (user red line)** | ≥ 192KB | Soft warn + mandatory suggest `--use-headroom`; `warnings: ["CONTEXT_NEAR_LIMIT"]` |
+| **80% (hard reject)** | ≥ 204KB | Hard reject `code: "PROMPT_TOO_LARGE"`; `--force` allowed at CLI |
+| **90% (emergency)** | ≥ 230KB | Hard reject `code: "PROMPT_EMERGENCY"`; `--force` STILL rejects at 90% (no override) |
+
+### Two-layer enforcement (G9.2)
+
+- **CLI 兜底** — `peaks sub-agent dispatch` validates prompt size; `--force` allowed.
+- **PreToolUse hook** — `peaks sub-agent-dispatch-guard` re-validates; **NO `--force`** allowed at hook layer (RL-30 strict).
+
+### `--force` semantics
+
+- At CLI: `--force` allowed; emits `code: "FORCED_OVER_THRESHOLD"` warning + records `forcedAt: ISO8601`.
+- At PreToolUse hook: `--force` is REJECTED (RL-30 strict). The hook's CLI does not declare a `--force` flag; the override path is physically not available.
+
+## AC mapping
+
+- AC-38..AC-43 (G7) + AC-44..AC-46 (G7.7) + AC-47..AC-49 (G8) + AC-50..AC-65 (G9)
+- See PRD §Acceptance criteria.
+
+---
+
+### G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
+
+> Body of `### G7`. Sub-agent artifacts (rd/tech-doc.md, qa/test-cases/&lt;rid&gt;.md, ui/design-draft.md) MUST NOT be inlined into dispatch records and fed back to the main LLM during reduce.
+
+- Sub-agent writes artifact to disk at a known path (path convention: `.peaks/_sub_agents/<sessionId>/artifacts/<rid>-<role>-<idx>.<ext>`).
+- Sub-agent calls `peaks sub-agent dispatch --write-artifact <path>` (or via dispatch CLI flag). The CLI computes sha256 + size + writes `ArtifactMeta` to record.
+- Main LLM reduces the batch and sees ONLY the metadata view (~200 chars per sub-agent, vs ~1MB if content were inlined) — a 3000-5000× reduction.
+- Main LLM decides whether to `Read <path>` for full content (LLM tool call, NOT via peaks CLI).
+
+Main LLM view format (G7.4.e):
+```
+[peaks-solo] batch 3/3 done in 47.3s
+- rd → .peaks/_sub_agents/2026-06-06-session-5b1095/artifacts/003-rd-001.md (12KB, sha256:abc123) summary: "wrote RD tech-doc with 4 sub-roles"
+- qa-business → .../artifacts/003-qa-business-001.md (8KB, sha256:def456) summary: "wrote 12 API test cases"
+- qa-perf → .../artifacts/003-qa-perf-001.md (5KB, sha256:ghi789) summary: "p95 latency target ≤ 200ms"
+```
+
+### G7.7 — headroom-ai integration (opt-in compression)
+
+> Body of `### G7.7`. If a sub-agent prompt is too large even after G7 metadata-only (e.g. 1MB artifact description, 5MB mid-prompt analysis), use `--use-headroom`:
+- Default `false` (G7 remains default).
+- Modes: `balanced` (default) | `aggressive` | `conservative`.
+- Failure: `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback (NOT blocking).
+
+### G8 — cross sub-agent shared channel (dispatcher-mediated indirect signal)
+
+> Body of `### G8`. Sub-agent A's completion **immediately** writes a shared entry; sub-agent B (still in flight) can read shared entries from sibling sub-agents. **This is NOT peer-to-peer messaging.** The dispatcher stores, the sub-agents read/write; A and B never directly talk.
+
+- Path: `.peaks/_sub_agents/<sessionId>/shared/<batchId>.json`.
+- Two new CLI atoms (NO new top-level CLI): `peaks sub-agent share` + `peaks sub-agent shared-read`.
+- RL-23 strong constraint: when sub-agent calls `peaks sub-agent heartbeat --status done`, it MUST also call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`.
+
+### G9 — forced compression gate (CLI 兜底 + hook double-guard)
+
+> Body of `### G9`. Threshold table (256K default context capacity):
+
+| Threshold | Prompt size | Behavior |
+|---|---|---|
+| 50% (early warn) | ≥ 128KB | Soft warning, suggest `--use-headroom` |
+| **75% (user red line)** | ≥ 192KB | Soft warn + `warnings: ["CONTEXT_NEAR_LIMIT"]` |
+| **80% (hard reject)** | ≥ 204KB | Hard reject `code: "PROMPT_TOO_LARGE"`; `--force` allowed at CLI |
+| 90% (emergency) | ≥ 230KB | Hard reject + `contextWarning: 'high'` |
+
+Two layers:
+- **CLI 兜底** — `peaks sub-agent dispatch` validates prompt size; `--force` allowed.
+- **PreToolUse hook** — `peaks sub-agent-dispatch-guard` re-validates; **NO `--force`** at hook layer (RL-30 strict).
+
+The sub-agent prompt template (G8.6 + G9 self-check) is in `references/context-governance.md`.

package/skills/peaks-solo/references/cross-date-session-check.md

@@ -0,0 +1,67 @@
+# Step 0.5: cross-date session check — full probe + decision tree
+
+## Cross-date detection
+
+Before invoking `peaks workspace init`, the LLM should detect whether the
+user's previous session is from a different date. If so, present a decision
+to the user via the IDE-native question tool (text fallback when no
+structured tool is available).
+
+## Cross-date probe
+
+```sh
+find .peaks/_runtime -mindepth 1 -maxdepth 1 -type d \
+  -printf '%f\n' \
+| while read sid; do
+    last=$(jq -r '.lastActivity // empty' ".peaks/_runtime/$sid/session.json" 2>/dev/null)
+    printf '%s\t%s\n' "$sid" "$last"
+  done
+```
+
+Compare each `last` against today's `YYYY-MM-DD` (use `new Date().toISOString().slice(0,10)`). The canonical "current" `<sessionId>` is the one bound in `.peaks/_runtime/session.json`, resolved via `peaks session info --active`.
+
+## Cross-date decision tree
+
+```
+For each <sessionId> in .peaks/_runtime/:
+  read .peaks/_runtime/<sessionId>/session.json.lastActivity
+  classify:
+    invalid sid            -> skip (already covered by peaks workspace clean)
+    lastActivity absent    -> skip
+    lastActivity == today  -> same-date (current binding)
+    lastActivity != today  -> cross-date candidate
+
+If cross-date candidates exist AND canonical sid != today:
+  LLM prompts the user via IDE-native ask_user_question:
+    Q: "Cross-date session(s) detected: <sid-A>, <sid-B>. Start a new
+        conversation (archives the old sessions) or continue the
+        previous one?"
+    A1: new conversation (recommended)
+    A2: continue
+
+  If A1 -> peaks workspace consolidate --apply --keep <currentSid>
+          then peaks workspace init
+  If A2 -> peaks workspace init (binding stays)
+```
+
+## Consolidate CLI contract
+
+`peaks workspace consolidate --apply --keep <currentSid> [--older-than <days>] [--project <path>]`
+
+- Default `--older-than 1` (cross-date).
+- Moves `.peaks/_runtime/<sid>/` -> `.peaks/_archive/retrospective-<YYYY-MM-DD>/<sid>/`.
+- Writes `manifest.json` per moved session.
+- Atomic per-session: a failure mid-move leaves the source untouched.
+- `--keep <sid>` excludes the current binding from the move set.
+
+## Consolidate edge cases
+
+- **Multiple cross-date sessions**: `--keep` only filters ONE current sid. To keep N sessions, pass `--keep` repeatedly.
+- **Empty `_runtime/`**: Step 0.5 is a no-op; proceed to Step 0.
+- **All sessions same-date**: Step 0.5 is a no-op; proceed to Step 0.
+- **`.peaks/` not initialized yet**: Step 0.5 fails silently; proceed to Step 0 init.
+- **IDE without structured question tool**: ask via plain text in the next assistant turn; honor whichever choice the user types.
+
+## Consolidate IDE note
+
+This step is strictly IDE-agnostic. All IDE-specific discovery lives in the `peaks-ide` skill (separate file). The skill body uses no IDE-specific paths, only generic terminology.

package/skills/peaks-solo/references/dag-orchestrator.md

@@ -0,0 +1,56 @@
+# DAG-aware sub-agent dispatch (2.7.0)
+
+Solo delegates layer-by-layer fan-out + join-barrier + cancel-on-fail
+to **`runDag(dag, opts)`** in `src/services/solo/dag-orchestrator.ts`
+when a slice's dependency surface is a DAG. Solo MUST NOT re-implement
+these mechanics inline.
+
+## When to use `runDag`
+
+Use `runDag` when **any** of these is true:
+
+- The slice has 2+ independent parallel leaves with per-layer rollback.
+- The slice has 1+ upstream contracts to inject into downstream
+  dispatch prompts (`formatContractInjection` reads
+  `.peaks/_runtime/<sessionId>/dispatch/contracts/`).
+- The slice has 2+ topological levels (orchestrator-driven re-invoke,
+  not manual "next-level" CLI calls).
+
+Use single-role `peaks sub-agent dispatch <role>` for everything else.
+
+## Contract
+
+```ts
+import { runDag } from '../services/solo/dag-orchestrator.js';
+const result = await runDag(dag, {
+  projectRoot, sessionId, requestId, role, ide,
+  dispatch: async (spec) => { /* LLM-side runner executes SubAgentDispatcher.buildToolCall(spec) */ },
+  await:    async (batchId, timeoutMs) => { /* SubAgentDispatcher.awaitBatch(...) */ },
+  writer:   writeContract,
+});
+// result.contracts: readonly SliceContract[] — written + ready for injection
+```
+
+## Failure handling
+
+Any leaf failure → orchestrator sends `cancel` to in-flight siblings;
+Solo gets partial `DagRunResult`, treats slice as `return-to-rd`,
+re-enters at the failed layer on next repair cycle. Per-IDE timeout:
+trae / trae-cn / cursor 30s, codex 45s, claude-code 60s; uniform
+120_000ms clamp ceiling.
+
+## Source-of-truth pointers
+
+- Orchestrator: `src/services/solo/dag-orchestrator.ts` (`runDag` +
+  `buildDispatchSpec` + `formatContractInjection`)
+- DAG model: `src/services/dispatch/slice-dag.ts`
+  (`validateDag` / `topologicalLevels` / `sliceReadyToRun` / `hashDag`)
+- Per-IDE await: `src/services/dispatch/sub-agent-dispatcher.ts`
+  (`SubAgentDispatcher.awaitBatch` — real impl on all 5 IDEs)
+- Contract store: `src/services/dispatch/contract-store.ts`
+- CLI surface: `peaks sub-agent dispatch --from-dag <file> --batch-id <id>`
+  and `peaks sub-agent await --batch <id> [--timeout <ms>]`
+- Tests: `tests/unit/solo/dag-orchestrator.test.ts` (cancel-on-fail),
+  `tests/unit/dispatch/run-dag-dogfood-mvp.test.ts` (MVP dogfood),
+  `tests/unit/dispatch/slice-dag-dispatcher-5ide-dogfood.test.ts`
+  (5 IDE end-to-end).