peaks-loop 3.0.0

package/skills/peaks-doctor/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: peaks-doctor
+description: Orchestrate peaks-cli's L3 doctor (peaks audit + peaks doctor + peaks openspec from-doctor) for project health. Use when the user asks for a project health check, doctor report, audit, or wants to convert doctor findings into OpenSpec change records. Coordinates the L2 audit framework + the L3.2 doctor + the L3.3 from-doctor proposal generator. Triggers on `/peaks-doctor`, "peaks doctor", "项目健康", "doctor report", "health check", "check the project", "audit my repo".
+internal: true
+---
+---
+
+# Peaks-Cli Doctor
+
+Peaks-Cli Doctor is the orchestration facade for the L3 doctor workflow. It runs the L2 audit framework (`peaks audit red-lines`) + the L3.2 doctor checks (`peaks doctor`) + the L3.3 from-doctor proposal generator (`peaks openspec from-doctor`). Use it when the user wants a project health check, a red-line audit, or to convert doctor findings into OpenSpec change records.
+
+## Skill-first architecture note (read once, internalise)
+
+This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary** — invoked by the skill prompt only when a primitive is the right tool. Behaviour only an LLM in a skill prompt would use lives **here in the SKILL.md**, not as a new CLI command. See `.claude/rules/common/dev-preference.md` for the decision template.
+
+## Code-Change Red Line (BLOCKING — read before ANY tool call)
+
+**Peaks-Cli Doctor is a doctor orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.**
+
+The doctor workflow is read-only by design. It produces:
+- `peaks audit red-lines` report (121 red lines in the current repo, 6 cli-backed)
+- `peaks doctor` report (69 checks: 68 pass, 1 fail — L3:l3-memory-health)
+- Optional OpenSpec change records via `peaks openspec from-doctor`
+
+If a doctor finding requires a code change, the workflow hands off to `peaks-rd` (or `peaks-solo` for the full pipeline). The doctor itself does NOT modify code.
+
+## Workflow (5 steps)
+
+1. **Anchor**: `peaks workspace init --project <repo> --json` (idempotent; same as every peaks-* skill).
+2. **Run audit**: `peaks audit red-lines --project <repo> --json` — returns the red-line audit (catalog-matched markers + live enforcer findings). Inspect the `enforcerFindings` array for runtime-detected issues.
+3. **Run doctor**: `peaks doctor --json` — returns 69 checks. Pay special attention to:
+   - `L3:l3-orphan-sessions` — invalid sids in .peaks/_runtime/
+   - `L3:l3-memory-health` — .peaks/memory/index.json shape
+   - `integration:gateguard-peaks-conflict` — third-party Edit/Write hook interference
+   - `build:workspace-layout-canonical` — workspace layout
+4. **Triage findings**: For each FAIL check, decide:
+   - **Real bug requiring fix** → hand off to peaks-rd (run `peaks openspec from-doctor` first to generate a draft proposal; then peaks-rd to implement)
+   - **Acceptable false positive** → document in the handoff; do not act
+   - **Configuration drift** → run the suggested recovery command (e.g. `peaks workspace clean`)
+5. **Generate proposals** (per FAIL finding): `peaks openspec from-doctor --project <repo> --check-id <id>` writes `openspec/changes/<date>-fix-<slug>/proposal.md`. Hand off to peaks-rd for implementation.
+
+## CLI primitives the skill composes
+
+- `peaks workspace init` — anchor the workspace (Step 0)
+- `peaks audit red-lines` — L2 audit
+- `peaks doctor` — L3.2 doctor
+- `peaks openspec from-doctor` — L3.3 proposal generator
+- `peaks openspec validate` — gate a draft proposal
+
+## Boundaries
+
+- The doctor is read-only. It does NOT modify code, fix bugs, or clean up sessions.
+- The doctor does NOT install UA or any third-party tool. The opt-in UX is surfaced via `peaks understand opt-in`; the doctor just reports state.
+- The doctor does NOT generate change records automatically; it surfaces findings + the LLM calls `peaks openspec from-doctor` to generate them.
+
+## References
+
+- `references/doctor-check-catalog.md` — every doctor check id + what it means
+- `references/from-doctor-flow.md` — the end-to-end "finding → proposal" path

package/skills/peaks-doctor/references/doctor-check-catalog.md

@@ -0,0 +1,31 @@
+# Doctor check catalog (peaks-doctor skill reference)
+
+Slice L3.2 ships 69 doctor checks. The most user-relevant ones:
+
+## L2 audit (slice #2)
+
+- **`L2:audit:cli-backed`** — count of red lines whose catalog match has a real enforcer
+- **`L2:audit:prose-only`** — count of red lines that need a future enforcer
+
+## L3.2 (slice #9)
+
+- **`L3:l3-orphan-sessions`** — directories in `.peaks/_runtime/` that fail `isValidSessionId`. Recover with `peaks workspace clean`.
+- **`L3:l3-memory-health`** — `.peaks/memory/index.json` must be well-formed JSON with a `schema_version` field and an array `entries`. Recovers by re-running `peaks memory extract`.
+
+## Build / workspace
+
+- **`build:dist-version-matches-source`** — `dist/src/shared/version.js` matches the source `package.json` version
+- **`build:workspace-layout-canonical`** — `.peaks/` follows the canonical `._archive` / `_runtime` / `_sub_agents` layout
+- **`build:workspace-migrate-not-needed`** — when the layout is already canonical
+
+## Integration (third-party hooks)
+
+- **`integration:gateguard-peaks-conflict`** — warns when `gateguard-fact-force` is installed without a `.peaks/**` skip pattern (the 3rd-party hook would block all peaks-qa .peaks/ artifact writes)
+
+## Skills
+
+- **`skill:<required-skill>`** — each required skill (peaks-ide, peaks-prd, peaks-rd, peaks-qa, peaks-sc, peaks-solo, peaks-sop, peaks-txt, peaks-ui, peaks-doctor) must be installed in the bundled skills dir
+
+## Doctor self
+
+- **`doctor-self:check-id-pattern`** — all check IDs match the `doctor-report.schema.json` regex pattern (prevents typos like `L3:l3-orphan-sesions`)

package/skills/peaks-doctor/references/from-doctor-flow.md

@@ -0,0 +1,64 @@
+# from-doctor flow (peaks-doctor skill reference)
+
+End-to-end path from a doctor finding to an OpenSpec change record.
+
+## Flow
+
+```
+peaks doctor --json                  # 1. discover findings
+  ↓
+match: any check where ok=false
+  ↓
+peaks openspec from-doctor \
+  --project <repo> \
+  --check-id <id>                   # 2. generate draft proposal
+  ↓
+openspec/changes/<date>-fix-<slug>/proposal.md   # 3. LLM reviews + edits
+  ↓
+peaks openspec validate <change-id>  # 4. gate
+  ↓
+[next slice: peaks-rd implements the change per the proposal]
+```
+
+## Example
+
+```bash
+# Discover
+$ peaks doctor --json | jq '.data.checks[] | select(.ok==false) | .id'
+"L3:l3-memory-health"
+
+# Generate draft
+$ peaks openspec from-doctor \
+    --project . \
+    --check-id L3:l3-memory-health \
+    --json
+{
+  "ok": true,
+  "command": "openspec.from-doctor",
+  "data": {
+    "changeId": "2026-06-11-fix-l3-l3-memory-health",
+    "proposalPath": ".../openspec/changes/2026-06-11-fix-l3-l3-memory-health/proposal.md",
+    "created": true
+  }
+}
+
+# LLM reviews + edits the draft (in this case: add a Why section
+# explaining the missing schema_version field; add an Acceptance
+# Criterion that requires peaks doctor to return ok=true for the check)
+
+# Validate
+$ peaks openspec validate 2026-06-11-fix-l3-l3-memory-health --json
+{
+  "ok": true,
+  "data": { "valid": true, "issues": [] }
+}
+
+# Implement (peaks-rd)
+$ /peaks-rd 2026-06-11-fix-l3-l3-memory-health
+```
+
+## Edge cases
+
+- **CHECK_ALREADY_PASSING**: `--check-id` matches a passing check. The CLI returns code CHECK_ALREADY_PASSING. Pick a failing check.
+- **CHECK_NOT_FOUND**: `--check-id` doesn't match any check id. Run `peaks doctor --json | jq '.data.checks[].id'` to list.
+- **OPENSPEC_FROM_DOCTOR_FAILED**: filesystem write error (e.g. openspec/ not initialized). Run `peaks openspec init --apply` first.

package/skills/peaks-doctor/test_prompts.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": "doctor-baseline",
+    "prompt": "/peaks-doctor",
+    "expectedOutcome": "Runs peaks workspace init + peaks audit + peaks doctor; returns a triage of FAIL checks with hand-off suggestions."
+  },
+  {
+    "id": "doctor-from-finding",
+    "prompt": "peaks doctor flagged L3:l3-memory-health. Generate an OpenSpec change record from it.",
+    "expectedOutcome": "Calls peaks openspec from-doctor --check-id L3:l3-memory-health; verifies the proposal.md was written; suggests next step (peaks-rd)."
+  },
+  {
+    "id": "doctor-only-audit",
+    "prompt": "Run only the audit (not the full doctor).",
+    "expectedOutcome": "Calls peaks audit red-lines --project . --json; summarizes the enforcerFindings and the prose-only ratio."
+  }
+]

package/skills/peaks-final-review/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: peaks-final-review
+description: Final-review skill for Peaks. Use when a workflow needs to assemble 4-dimension business-review evidence (functional-completeness, problem-resolution, no-new-bugs, existing-functionality-intact) for human acceptance at the end of an autonomous slice. Triggers on "/peaks-final-review", "prepare final review", "4-dim review", or peaks-solo end-of-workflow handoff.
+---
+
+## Single-scope-axis naming convention
+
+> **Read once at the top of this file; the rest of the skill is written against it.**
+
+The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, at `.peaks/_runtime/<sessionId>/...`) with a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` placeholders (NEVER bare `<sid>`). The peaks-cli change-id axis was removed in slice `2026-06-29-change-id-root-removal`; reviewable artifacts now live under `.peaks/_runtime/<sessionId>/<role>/...` only. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. CLI mapping: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Regression test `tests/unit/skills/skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) every `.peaks/_runtime/<X>/` has an axis label, (c) this callout is present.
+
+# Peaks-Cli Final Review
+
+Prepare 4-dim business review evidence for human acceptance. The LLM does the work; the human judges the outcome.
+
+## Service entry point (authoritative)
+
+The single source of truth for the 4-dim review is the service:
+
+```ts
+// src/services/final-review/final-review-service.ts
+export async function prepareFinalReview(
+  rid: string,
+  opts: PrepareFinalReviewOptions
+): Promise<FinalReviewOutput>;
+```
+
+Where `PrepareFinalReviewOptions` is:
+
+```ts
+interface PrepareFinalReviewOptions {
+  readonly projectRoot: string;
+  readonly sessionId: string;
+  readonly llmRunner: LlmRunner; // imported from src/services/audit/audit-goal-service.js
+}
+```
+
+The service is the **gate primitive** that closes the 10% human / 90% LLM loop. It reads the approved audit-goal JSON from `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`, calls an injected `LlmRunner` exactly once with a 4-dim review prompt, parses the response, and validates that all four required dimensions are present. It throws `IncompleteFinalReviewError` on malformed JSON or missing dimensions — callers MUST treat that as a gate failure (return to human for re-prompting) and never let autonomous work proceed on a partial review.
+
+> The `LlmRunner` interface is intentionally minimal so this service reuses the same provider injection seam as `audit-goal-service` and the slice LLMArbitrator (`src/services/audit/audit-goal-service.ts:16`). No provider implementation is baked in at this layer.
+
+## Precondition
+
+All of the following MUST be true before invoking this skill:
+
+- **RD complete** — implementation merged and the slice boundary recorded at `.peaks/sc/slice-decomposition/<rid>.json` (or `peaks slice check --rid <rid> --json` returns `pass`).
+- **QA complete** — `test-cases` + `test-reports` + `security-findings` + `performance-findings` present under `.peaks/_runtime/<sessionId>/qa/...` and all applicable gates A/A2/A3/A4/B/C/E/F satisfied (per `skills/peaks-qa/references/qa-transition-gates.md`).
+- **Security check complete** — slice 025 project-level security test plan executed; no open CRITICAL/HIGH findings.
+- **Performance baseline complete** — slice 025 project-level perf baseline recorded; no regression beyond the agreed threshold.
+- **Approved audit-goal on disk** — `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json` exists and contains `successCriteria` (the service feeds these into the LLM user prompt verbatim).
+
+If any precondition is missing, **STOP** and route back to the responsible skill. Do not paper over a missing artifact with a hand-written successCriteria — the review must reflect what the human originally approved.
+
+## Invocation (CLI wrapper status — READ FIRST)
+
+> **Pre-flight finding (HARD):** The plan prose at `docs/superpowers/plans/2026-06-25-slice-topology-multipass-phase-4.md:146` documents the invocation as:
+>
+> ```bash
+> peaks prepare-final-review --rid <rid> --json
+> ```
+>
+> **This CLI command does NOT yet exist.** `prepareFinalReview()` is implemented as a service in `src/services/final-review/final-review-service.ts` and is unit-tested in `tests/unit/final-review/final-review-service.test.ts`, but it is **not wired to a CLI subcommand**. A `peaks prepare-final-review` subcommand is the planned forward-looking surface; the integration sits at the service layer, not the CLI layer, today.
+>
+> **Pick for the future CLI wrapper file (audit recommendation):** create a new `src/cli/commands/final-review-commands.ts` matching the `peaks-<group>-commands.ts` naming convention (`qa-commands.ts`, `code-review-commands.ts`, `audit-commands.ts`). A grep of `src/cli/commands/` confirms NO `final-review-commands.ts` and NO `prepareFinalReview` import in any CLI file. Rationale: the 4-dim business review is conceptually distinct from `peaks qa *` (which is autonomous gate verification) — it is the human-acceptance terminator, not an internal gate. A separate command group preserves that boundary.
+
+### Current call path (today, until a CLI wrapper is built)
+
+```ts
+// peaks-solo end-of-workflow, peaks-txt, or any other hand-rolled caller
+import { prepareFinalReview } from './src/services/final-review/final-review-service.js';
+import { auditGoalLlmRunner } from './src/services/audit/llm-runner.js'; // or your provider
+
+const out = await prepareFinalReview('<rid>', {
+  projectRoot: '<absolute path>',
+  sessionId: '<sessionId>',
+  llmRunner: auditGoalLlmRunner
+});
+```
+
+### Planned call path (after the CLI wrapper lands)
+
+```bash
+# Forward-looking — does not work yet. Track under
+#   src/cli/commands/final-review-commands.ts
+peaks prepare-final-review --rid <rid> [--session-id <sid>] --json
+```
+
+`--rid` is required and resolves to `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. `--json` is required for machine consumption (peaks-solo, peaks-txt, downstream CI). The wrapper will resolve `--session-id` from `.peaks/_runtime/current-change` when omitted, matching the workspace binding pattern used by `peaks request *`.
+
+## Output
+
+A `FinalReviewOutput` (`src/services/final-review/final-review-types.ts:50`):
+
+```ts
+interface FinalReviewOutput {
+  readonly rid: string;
+  readonly generatedAt: string;                   // ISO timestamp
+  readonly dimensions: readonly DimensionEvidence[]; // EXACTLY 4
+  readonly overallSummary: string;                 // one paragraph
+  readonly allPass: boolean;                       // all 4 verdicts === 'pass'
+  readonly needsAttention: readonly DimensionKind[]; // dims that are 'fail' or 'inconclusive'
+}
+```
+
+Each `DimensionEvidence` carries:
+
+- `dimension` — one of the four required `DimensionKind` values
+- `verdict` — `pass | fail | inconclusive`
+- `summary` — one short paragraph
+- `evidence` — list of `EvidenceItem` (`{ kind, description, artifact?, link? }`) with `EvidenceKind` ∈ `test-result | test-coverage | manual-spot-check | pre-post-diff | regression-suite | ac-mapping`
+- `confidence` — `high | medium | low`
+
+The service enforces that **all 4 dimensions are present**; a missing dimension throws `IncompleteFinalReviewError` and the call is a gate failure. Treat `allPass === true` + empty `needsAttention` as a clean handoff to the human. Anything else — `allPass === false`, a `fail` verdict, or an `inconclusive` verdict — must come back to the LLM loop with a re-prompt (do not ask the human to interpret raw LLM output).
+
+## The 4 dimensions (one-line summary)
+
+Full evidence contract per dimension: `references/4-dimensions.md`.
+
+1. **functional-completeness** — every AC from the approved audit-goal maps to a passing test (`evidence.kind === 'ac-mapping'` + `test-result`).
+2. **problem-resolution** — there is a targeted test for the original problem case (`evidence.kind === 'test-result'` against the original repro).
+3. **no-new-bugs** — the regression suite is green AND the LLM surfaces 0 net-new failures (`evidence.kind === 'regression-suite'` + `manual-spot-check`).
+4. **existing-functionality-intact** — a pre/post baseline diff (test count, public API surface, key behavior) shows no unintended drift (`evidence.kind === 'pre-post-diff'`).
+
+## Human's role
+
+The human reviews evidence, **judges business outcomes (NOT code)**. The LLM produces structured evidence; the human's job is to:
+
+- confirm that `allPass === true` corresponds to the business outcome they actually want (not just "tests are green");
+- decide what to do with `needsAttention` items — accept the LLM's verdict, override a `pass` to `fail` when the evidence is weak, or send the slice back to RD with a re-prompt;
+- gate the release / archive action based on `allPass` + their own business review, not just on the LLM signal.
+
+The LLM does NOT decide whether the work is shipped. The LLM only assembles evidence. The human is the final reviewer of business outcomes; the service is the gate that gives them structured evidence to review.
+
+## Boundaries
+
+- Do not modify the audit-goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json` — the service reads it as-is. If criteria need to change, route back to `peaks-audit` and re-approve.
+- Do not call `prepareFinalReview()` twice for the same `(rid, sessionId)` without first surfacing the prior result to the human. Each call costs one LLM invocation and may diverge.
+- Do not substitute the 4-dim review for the QA gate family (A/A2/A3/A4/B/C/E/F). The 4-dim review is a human-acceptance surface, not a regression gate. QA gates must pass first.
+- Do not write the review output to git. The LLM output is ephemeral — keep it under `.peaks/_runtime/<sessionId>/final-review/<rid>.json` (gitignored) and reference it from the change-id-scoped handoff at `.peaks/_runtime/<changeId>/handoff/<rid>-<change-id>.md` if downstream review needs it.
+- Do not allow autonomous work to proceed on a `IncompleteFinalReviewError` — that is a gate failure, not a recoverable runtime error.
+
+## Compact handoff
+
+When handing off, emit: rid, `allPass`, `needsAttention[]`, output path, source service version (commit hash of `src/services/final-review/final-review-service.ts`), LLM provider used, and one-line summary. Link to the full `FinalReviewOutput` JSON instead of pasting it.
+
+## References
+
+| File | Coverage |
+|---|---|
+| `references/4-dimensions.md` | Per-dimension evidence contract, verdict semantics, examples. |
+| `src/services/final-review/final-review-service.ts` | Authoritative service implementation. |
+| `src/services/final-review/final-review-types.ts` | `FinalReviewOutput`, `DimensionEvidence`, verdict/evidence/confidence enums. |
+| `src/services/audit/audit-goal-service.ts:16` | Line of evidence that `LlmRunner` is reusable across audit + final-review (service-level integration). |
+| `tests/unit/final-review/final-review-service.test.ts` | Existing service-level unit tests (5 cases). |
+| `docs/superpowers/plans/2026-06-25-slice-topology-multipass-phase-4.md:127` | Phase-4 plan prose (Task 14). |
+| `skills/peaks-qa/SKILL.md` | Upstream QA skill — 4-dim review is downstream of all QA gates. |
+| `skills/peaks-audit/SKILL.md` | Sibling skill — produces the `audit-goal` JSON that this skill consumes. |

package/skills/peaks-final-review/references/4-dimensions.md

@@ -0,0 +1,117 @@
+# 4 Dimensions — Final Review
+
+This reference defines the evidence contract, verdict semantics, and worked examples for the four `DimensionKind` values the LLM must produce in `FinalReviewOutput.dimensions[]`. The authoritative types live at `src/services/final-review/final-review-types.ts`. Verdict values: `pass | fail | inconclusive` (the type-level enum). `inconclusive` is the wire-level name; the human-facing label is **needs-human** — the human must judge this dimension rather than accept the LLM's verdict.
+
+When the service at `src/services/final-review/final-review-service.ts` returns `allPass === true` and `needsAttention` is empty, every dimension was judged `pass`. Anything else surfaces to the human for review.
+
+---
+
+## 1. functional-completeness
+
+### Definition
+
+Every acceptance criterion in the approved audit-goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json` is realized by at least one passing test, and no AC is left dangling. The LLM is asserting that the slice delivers what the human originally asked for, not just that "something was built."
+
+### Evidence the LLM must produce
+
+- An `ac-mapping` `EvidenceItem` for every AC in the approved goal's `successCriteria[]`. Each item references the AC by ID (e.g. `AC-1`) and the test file or test name that exercises it.
+- A `test-result` `EvidenceItem` summarizing the run (e.g. `vitest run src/services/<x>` → 12/12 pass). `artifact` should be the report path; `link` the run URL when CI is involved.
+- A `test-coverage` `EvidenceItem` if the project maintains a coverage threshold for the changed surface. Cover only what is gated by the project's own standards; do not invent thresholds.
+
+### Verdict semantics
+
+- `pass` — every AC has a passing test and the test suite is green.
+- `fail` — one or more ACs are unmapped, the targeted test is failing, or the suite is red on a non-flaky ground.
+- `inconclusive` (needs-human) — the mapping is plausible but the human needs to confirm that a passing test truly reflects the business intent of an AC. Example: a test exists for "config-service splits into 3 modules" but the human must decide whether the *seam* the test exercises is the seam they actually wanted.
+
+### Example
+
+> `dimension: "functional-completeness"`, `verdict: "pass"`, `summary: "All 3 success criteria from the approved goal are covered by passing tests. AC-1 covered by config-service.modules.test.ts; AC-2 covered by config-service.api.test.ts (public API snapshot unchanged); AC-3 covered by coverage report at 100% lines/branches for the changed files."`, `evidence: [...]`, `confidence: "high"`.
+
+---
+
+## 2. problem-resolution
+
+### Definition
+
+The original problem case the slice was opened to fix has a targeted test that fails without the fix and passes with it. This is the most concrete dimension — it asks the LLM to prove the slice actually solves the specific problem on the record, not a generic improvement.
+
+### Evidence the LLM must produce
+
+- A `test-result` `EvidenceItem` naming the targeted test (e.g. `tests/integration/<surface>/regression-XXX.test.ts`) with the repro steps encoded as test assertions, and the post-fix result (pass).
+- A `manual-spot-check` `EvidenceItem` when the original problem was a UI or operator-facing behavior that cannot be unit-tested cleanly. `artifact` should point to the recorded evidence (screenshot, log capture, transcript).
+- An `ac-mapping` `EvidenceItem` linking the targeted test back to the original problem statement (e.g. the audit-goal's `proposedGoal` or the human's verbatim "fix X" wording). Without that link, the test is just coverage, not problem-resolution evidence.
+
+### Verdict semantics
+
+- `pass` — there is a targeted test that proves the original case is fixed AND that test is currently green.
+- `fail` — there is no targeted test, the targeted test is red, or the targeted test does not actually reproduce the original problem (e.g. it tests an adjacent but different case).
+- `inconclusive` (needs-human) — the targeted test exists and is green, but the human must confirm the test does reproduce the problem they originally reported. Example: the LLM fixed a config-file write race but the targeted test exercises a slightly different code path than the user's reproducer.
+
+### Example
+
+> `dimension: "problem-resolution"`, `verdict: "pass"`, `summary: "Targeted test repros the original config-write race (concurrent writes to the same key) and now passes deterministically. The test fails on the pre-fix commit and passes on the post-fix commit."`, `evidence: [{ kind: "test-result", description: "tests/integration/config-write-race.test.ts — 200/200 deterministic", artifact: "tests/integration/config-write-race.test.ts" }, { kind: "ac-mapping", description: "Maps to the user's reported repro: 'concurrent config writes corrupt the file'" }]`, `confidence: "high"`.
+
+---
+
+## 3. no-new-bugs
+
+### Definition
+
+The slice did not introduce net-new failures. The pre-existing regression suite is green AND the LLM performed targeted spot-checks on surfaces adjacent to the change (imported modules, callers, fixtures, type signatures). A green regression suite alone is insufficient — a slice can "fix" one thing while breaking an adjacent surface that no test directly covers.
+
+### Evidence the LLM must produce
+
+- A `regression-suite` `EvidenceItem` showing the full suite is green on the post-fix commit, with the run command and the aggregate pass/fail/skip count.
+- One or more `manual-spot-check` `EvidenceItem` entries for each adjacent surface the LLM inspected (e.g. "called `config-service.resolve()` from a downstream consumer in a 30-second smoke run; output identical to the pre-fix golden"). List the surfaces explicitly.
+- A `test-result` `EvidenceItem` for any newly-added test that targets the changed surface's direct neighbors (callers, importers, shared fixtures).
+
+### Verdict semantics
+
+- `pass` — regression suite is green AND every adjacent surface the LLM spot-checked behaves correctly.
+- `fail` — the regression suite is red OR a spot-check surfaced a behavior change that is not part of the slice's scope (out-of-scope regression).
+- `inconclusive` (needs-human) — the regression suite is green but at least one adjacent surface was either not spot-checked or surfaced a behavior the LLM cannot rule out as intentional. The human judges whether the behavior is acceptable drift or a hidden bug.
+
+### Example
+
+> `dimension: "no-new-bugs"`, `verdict: "pass"`, `summary: "Full vitest suite green (2417/2417). Spot-checked 4 adjacent surfaces: callers in src/cli/commands/*, the resolve() consumer in src/services/runtime-bootstrap, the schema fixtures in tests/fixtures/config, and the type signatures exposed via the index file — all behaviorally identical to the pre-fix golden."`, `evidence: [...]`, `confidence: "high"`.
+
+---
+
+## 4. existing-functionality-intact
+
+### Definition
+
+A pre/post baseline diff shows no unintended drift in the test surface, public API, or key behavior. This is the structural counterpart to `no-new-bugs`: where `no-new-bugs` is "I ran the suite and spot-checked," this dimension is "I compared the structural shape of the project before and after the slice." The two dimensions can both pass and tell complementary stories — a green suite with a shrinking public API is still a regression in `existing-functionality-intact`.
+
+### Evidence the LLM must produce
+
+- A `pre-post-diff` `EvidenceItem` with a concrete diff artifact: a test-count diff (e.g. `+12 / -3`), a public-API surface diff (e.g. a snapshot of exported symbols from the package's main entry), or a behavior-baseline diff (e.g. golden output of an end-to-end happy path).
+- A `test-result` `EvidenceItem` for any existing test that touched the changed surface, confirming it still passes on the post-fix commit.
+- A `manual-spot-check` `EvidenceItem` for any behavioral baseline that is not covered by a test (e.g. CLI help text, error message format) — the LLM must record the pre and post values.
+
+### Verdict semantics
+
+- `pass` — every measured dimension (tests, API, behavior) is unchanged or changed only in ways that the slice was explicitly authorized to change (e.g. AC-2 says "add a new exported helper `resolveWithSchema()`" — that IS the authorized change).
+- `fail` — an unauthorized change slipped in: an exported symbol disappeared, a test was deleted rather than updated, a behavior baseline drifted without a corresponding AC.
+- `inconclusive` (needs-human) — a change is present that *could* be authorized drift or *could* be an unintentional regression. The human rules.
+
+### Example
+
+> `dimension: "existing-functionality-intact"`, `verdict: "pass"`, `summary: "Public API snapshot: 0 symbols removed, 1 symbol added (resolveWithSchema — authorized by AC-2). Test count: +12 (new tests for resolveWithSchema), -3 (deleted tests for the old monolithic resolve that resolveWithSchema supersedes). CLI help text byte-identical to pre-fix golden."`, `evidence: [{ kind: "pre-post-diff", description: "Public API surface diff: +resolveWithSchema, -3 obsolete test files, no other deltas", artifact: ".peaks/_runtime/<sessionId>/final-review/api-diff.txt" }]`, `confidence: "high"`.
+
+---
+
+## How `allPass` and `needsAttention` are computed
+
+The service contract (`src/services/final-review/final-review-service.ts:23-31` and `:88-93`):
+
+- `allPass === true` iff every dimension's `verdict === 'pass'`.
+- `needsAttention` is the list of dimension names whose verdict is `fail` or `inconclusive`. The LLM does NOT need to populate it — the service enforces presence of all 4 dimensions and the human-facing summarizer (in peaks-solo or peaks-txt) computes `needsAttention` for display.
+- An `IncompleteFinalReviewError` is thrown when JSON is malformed or any required dimension is missing. That is a **gate failure**, not a `fail` verdict — the LLM call is invalid and must be re-prompted, not surfaced to the human.
+
+## Confidence and what it means
+
+- `high` — evidence is concrete (named test file, named artifact, deterministic run).
+- `medium` — evidence is concrete but covers only part of the dimension; the LLM is being honest about coverage gaps.
+- `inconclusive` verdicts should always be `medium` or `low` confidence; `high` confidence on `inconclusive` is a contradiction and the LLM should be re-prompted.

package/skills/peaks-ide/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: peaks-ide
+description: Orchestrate peaks-cli's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, "set up peaks for my IDE", "switch peaks to Trae", "what did peaks install", "uninstall peaks hooks". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.
+internal: true
+---
+---
+
+# Peaks-Cli IDE Setup (peaks-ide)
+
+`peaks-ide` is the **user-facing surface** for everything peaks-cli does that's IDE-aware. It does NOT introduce new CLI commands. It orchestrates the existing CLI primitives — `peaks hooks install`, `peaks statusline install`, `peaks hook handle` — based on the user's intent and the IDE the user is on.
+
+**Why this exists (dev-preference red line):** "skill is primary, CLI is auxiliary." The behavior that only an LLM in a skill prompt would use ("detect which IDE the user is on", "plan the migration steps", "ask the user before destructive actions") lives in this SKILL.md, not in a new `peaks <cmd>`. The CLI commands stay as atomic primitives the skill composes.
+
+**Slice #2 scope:** the first version supports Trae (alongside Claude Code, the only other adapter in slice #2's registry). Cursor / Codex / Qoder / Tongyi Lingma will land in slice #3+ — the skill will pick them up automatically because the underlying auto-detect (the `peaks project dashboard --json` flow internally calls `listAdapterIds()` via the `IdeRegistry`) registers them as the registry grows.
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-ide --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+The presence marker tells the global peaks status line that peaks-ide is orchestrating. The memory read pulls forward the slice #1 contract: `peaks <cmd> --project <path>` is the canonical project-root source; `process.env[adapter.envVar]` (e.g. `CLAUDE_PROJECT_DIR`, `TRAE_PROJECT_DIR`) is the env-var override for auto-detect.
+
+## Step 1: detect current state
+
+The skill's first move is to **read**, not to ask. Build a complete picture of the user's IDE environment before any AskUserQuestion.
+
+```bash
+# 1. What adapters are registered? (slice #2 ships with claude-code + trae)
+peaks project dashboard --project <repo> --json
+
+# 2. Is the user on Claude Code, Trae, or something else?
+#    Check the cwd for adapter-specific directories:
+ls -la <repo>/.claude 2>/dev/null && echo "claude-code detected"
+ls -la <repo>/.trae 2>/dev/null && echo "trae detected"
+
+# 3. Are peaks hooks already installed? For each candidate, read settings.json:
+#    claude: <root>/.claude/settings.json
+#    trae:   <root>/.trae/settings.json
+peaks hooks status --project <repo> --json 2>/dev/null
+peaks statusline status --project <repo> --json 2>/dev/null
+```
+
+The skill composes a 1-2 sentence **state summary** before asking anything:
+
+> "I see you're on **Trae** (`.trae/` exists in the project root). peaks hooks are **not installed** yet. peaks statusline is **not installed** either. The `peaks hook handle` runtime is available as a CLI primitive — you don't need to install it separately; what needs installing is the settings.json entries that point to it."
+
+The user gets a complete picture without having to answer any question. The next step only fires AskUserQuestion if intent is genuinely ambiguous.
+
+## Step 2: AskUserQuestion (only if intent is ambiguous)
+
+If the user typed `/peaks-ide` without context, the skill's intent is genuinely ambiguous. The four canonical intents are:
+
+| Option | What it does |
+|---|---|
+| First-time install | Run `peaks hooks install` + `peaks statusline install` for the detected IDE |
+| Switch to a different IDE | Detect current install, uninstall from old IDE, install on new IDE (e.g. Claude → Trae) |
+| Show current status | Just print the state summary from Step 1; no side effects |
+| Uninstall peaks hooks | Run `peaks hooks uninstall` + `peaks statusline uninstall` for the detected IDE |
+
+**Default option is "Show current status"** — the cheapest action, and the user gets useful output even if they didn't know what they wanted. AskUserQuestion is the ONLY place this skill asks anything. All destructive paths (Switch, Uninstall) gate on user confirmation here.
+
+## Step 3: plan & preview (dry-run)
+
+Before any side effect, the skill prints the exact CLI invocations it will run. This is the "see before you leap" step.
+
+```
+Plan: First-time install for Trae (.trae/ detected in project root)
+
+  1. peaks hooks install --project <repo>
+     → writes a beforeToolCall hook entry to <root>/.trae/settings.json
+       that points to `peaks hook handle --project "${TRAE_PROJECT_DIR}"`
+
+  2. peaks statusline install --project <repo>
+     → writes a statusLine field with command `peaks statusline`
+
+  3. (no third command — `peaks hook handle` is the runtime; once the
+     settings.json entries point to it, the user's Trae will invoke it
+     on every PreToolUse event)
+
+Verification: after install, re-run `peaks hooks status --project <repo>`
+             to confirm the entries are present.
+
+Proceed? (Y/n)
+```
+
+The plan MUST be human-readable. Don't run a side effect until the user confirms.
+
+## Step 4: execute
+
+For each step in the plan, invoke the CLI primitive. The skill does NOT call out to a hidden script — it runs the actual peaks CLI commands, so the user sees the same output they'd see typing the command themselves.
+
+```bash
+# Example: first-time Trae install
+peaks hooks install --project <repo>
+peaks statusline install --project <repo>
+
+# After each command, check the exit code. If non-zero, STOP and report
+# the failure to the user. The skill does NOT auto-rollback; the user
+# decides what to do next.
+```
+
+For destructive paths (Switch, Uninstall), the skill uses a **transactional pattern**: it captures the current state, runs the destructive CLI, then runs the install CLI; if any step fails, it reports the partial state and lets the user decide.
+
+## Step 5: audit log
+
+Every successful execution writes one JSON line to `.peaks/_runtime/<sid>/ide-onboard.log`:
+
+```json
+{"timestamp":"2026-06-06T19:55:00Z","intent":"first-time-install","detected_ide":"trae","cli_invocations":["peaks hooks install --project <repo>","peaks statusline install --project <repo>"],"outcome":"success","session_id":"2026-06-06-session-22f08c"}
+```
+
+The audit log is **machine-readable** (so `peaks project dashboard` can read it and surface "you installed peaks for Trae on 2026-06-06") and **human-readable** (so the user can `cat` it to see the install history). The skill does NOT write the log file itself — it delegates to `peaks project dashboard` (the canonical log writer, per the dev-preference red line "skill-first for workflow, CLI-backed for gates / side effects"). The audit log writer is a CLI primitive, not a per-skill helper; the skill body MUST NOT introduce a new `peaks <cmd>` for the log writer. The thin helper that writes the log is `scripts/peaks-ide-audit-log.mjs`; see [audit-log-helper.md](references/audit-log-helper.md) for its CLI surface and contract.
+
+## Boundaries
+
+`peaks-ide` may:
+
+- detect the current IDE (cwd + env var + settings.json)
+- ask the user via AskUserQuestion (Step 2 only)
+- preview the CLI invocations (Step 3)
+- execute existing peaks CLI commands (Step 4)
+- write a single line to the audit log (Step 5)
+
+`peaks-ide` must NOT:
+
+- introduce new `peaks <cmd>` CLI commands (dev-preference red line: "Default-no on new CLI commands")
+- bypass the user's confirmation on destructive paths (Switch / Uninstall)
+- write the settings.json directly (the CLI primitives own that)
+- run other peaks skills (peaks-solo, peaks-qa, etc.) — those are separate skills with their own scopes
+- handle multi-IDE scenarios in slice #2 (e.g. "I use Claude at work and Trae at home" — the registry is single-IDE per session; a future slice could add multi-IDE)
+
+## Reference: the CLI primitives the skill composes
+
+- `peaks hooks install` / `peaks hooks uninstall` / `peaks hooks status` — adapter-driven; auto-detects IDE from env / stdin / cwd
+- `peaks statusline install` / `peaks statusline uninstall` / `peaks statusline status` — same
+- `peaks hook handle` — the runtime handler; not installed, just invoked
+- `peaks project dashboard --json` — surfaces the current state summary
+- `peaks skill runbook` — surfaces the peaks-ide skill body for inspection
+
+## Next-step references
+
+- The slice #1 RD artifact at `.peaks/_runtime/<sid>/rd/requests/002-2026-06-06-peaks-ide-skeleton.md` documents the slim `IdeAdapter` shape that the skill is built on.
+- The slice #2 PRD at `.peaks/_runtime/<sid>/prd/requests/002-2026-06-06-trae-adapter-and-peaks-ide-skill.md` documents the 13 ACs this skill is part of.
+- The slice #2 RD artifact (in flight) documents the implementation contract.
+
+## Default runbook
+
+The skill is invoked as `/peaks-ide` or via the natural-language triggers listed in the frontmatter. The runbook is the body of this SKILL.md (steps 1-5 plus the boundaries and reference sections above); the runbook-service extracts the section between this `## Default runbook` heading and the next `##` heading.
+
+When the user types `/peaks-ide` (or "set up peaks for my IDE" / "switch peaks to Trae" / "what did peaks install" / "uninstall peaks hooks"), execute Steps 1 → 5 in order:
+
+1. **Skill presence (MANDATORY first action)**: `peaks skill presence:set peaks-ide --project <repo> --gate startup` and `peaks project memories --project <repo> --json` (load durable memory).
+2. **Detect current state** (Step 1 above): `peaks project dashboard --project <repo> --json` + `peaks hooks status --project <repo> --json` + `peaks statusline status --project <repo> --json` + `ls -la <repo>/.claude 2>/dev/null` + `ls -la <repo>/.trae 2>/dev/null`. Build a 1-2 sentence state summary.
+3. **AskUserQuestion** (Step 2 above, only if intent is ambiguous). Default option: "Show current status". Destructive paths (Switch, Uninstall) gate on user confirmation here.
+4. **Plan & preview** (Step 3 above): print the exact `peaks hooks install` / `peaks statusline install` invocations before running them. Wait for "Proceed? (Y/n)".
+5. **Execute** (Step 4 above): run the `peaks hooks install` / `peaks statusline install` (or uninstall / status) commands. Stop on non-zero exit. Do not auto-rollback.
+6. **Audit log** (Step 5 above): delegate the JSONL write to `peaks project dashboard` (the canonical log writer; per the dev-preference red line, the skill MUST NOT introduce a new CLI primitive for the log writer).
+
+CLI primitives the skill composes (per the "Reference" section above): `peaks skill presence:set`, `peaks project memories`, `peaks project dashboard`, `peaks hooks install` / `uninstall` / `status`, `peaks statusline install` / `uninstall` / `status`, `peaks hook handle`, `peaks skill runbook`. The skill does NOT introduce any new `peaks <cmd>` command.