peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -1,115 +0,0 @@
-# A2A artifact mapping (informational)
-
-> Reference for `peaks-solo` 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-solo` 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-solo/references/anchoring-and-session-info.md

@@ -1,34 +0,0 @@
-# Step 0 — Anchor the workflow
-
-> Body of `### Peaks-Loop Step 0: Anchor the workflow`. The instant Peaks-Loop Solo 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 Solo, always omit --session-id
-# here and let the CLI auto-generate.
-peaks workspace init --project <repo> --json
-peaks skill presence:set peaks-solo --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-solo 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-solo 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-solo` 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-solo` from the very first turn even if the user never reaches mode selection.

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

@@ -1,65 +0,0 @@
-# artifact-contracts.md
-
-Default local artifact root: `.peaks/_runtime/<session-id>/` with role subdirectories `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
-
-Solo 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-solo (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-solo (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-solo/references/boundaries.md

@@ -1,21 +0,0 @@
-# Boundaries
-
-> Body of `## Boundaries`. Peaks-Loop Solo may:
-
-- identify scenarios such as refactor, bugfix, QA hardening, release validation, and incident response;
-- recommend Solo, 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 Solo 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.

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

@@ -1,127 +0,0 @@
-# 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-loop 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-loop 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-loop 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/codegraph-orchestration.md

@@ -1,5 +0,0 @@
-# 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-Loop gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.

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

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

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

@@ -1,23 +0,0 @@
-# Completion handoff
-
-> Body of `## Peaks-Loop 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-Loop 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.
-
-> **Owned by runbook Step 10 (TXT handoff) + Step 11 (Memory sediment in SKILL.md).** Do not duplicate the CLI invocation here — the canonical command is:
->
-> ```bash
-> peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
-> ```
->
-> `peaks project memories:extract` is a different (batch-scoped, no-artifact) CLI used in non-handoff flows. Step 11 in SKILL.md enforces the artifact-scoped path; follow that.

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

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