peaks-loop 3.0.0

package/skills/peaks-slice-decompose/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: peaks-slice-decompose
+description: Run multi-pass slice decomposition on a PRD-ready request and emit a v2 envelope with passes, cross-pass edges, and an LLM-arbitration trace. Use when a PRD is ready and the caller needs service-level and/or file-level cuts in one artifact.
+---
+
+## 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.
+
+## Read via `SchemaRouter.readResult()` — never parse the file directly
+
+> **BLOCKING for any consumer of the v2 envelope.**
+
+The decomposition file at `.peaks/sc/slice-decomposition/<rid>.json` may be either v1 (no `schemaVersion` field) or v2 (`schemaVersion: 'v2'`). Callers MUST use `SchemaRouter.readResult(<path>)` from `src/services/slice/schema-router.ts` and narrow on the discriminator:
+
+```ts
+import { readResult } from '../../services/slice/schema-router.js';
+
+const parsed = readResult(outPath);
+if (parsed.schemaVersion === 'v2') {
+  handleV2(parsed); // DecompositionResultV2
+} else {
+  handleV1(parsed); // DecompositionResult
+}
+```
+
+Do NOT call `JSON.parse(readFileSync(...))` directly. Unknown `schemaVersion` values throw `UnknownSchemaVersionError` with code `UNKNOWN_SCHEMA_VERSION` — surface that to the CLI as exit-code-mapped failure, do not silently fall back to v1.
+
+# Peaks-Cli slice-decompose
+
+`peaks-slice-decompose` wraps the v2 multi-pass orchestrator (`MultiPassOrchestrator.decompose`) and the v1/v2 dual-read SchemaRouter. It owns the artifact shape emitted by `peaks slice decompose` when a non-default `--granularity` is passed.
+
+## Trigger conditions
+
+Invoke when ALL of the following hold:
+
+- a PRD body exists for `<rid>` (under `.peaks/2026/prd/requests/`, `.peaks/prd/requests/`, or `.peaks/_runtime/*/prd/requests/`);
+- the request is **PRD-ready** (the PRD has acceptance criteria and is past `peaks-prd`'s draft gate);
+- the caller needs one or both of:
+  - service-level cuts (Pass 1) AND/OR file-level cuts (Pass 2) in a single artifact, OR
+  - cross-pass edges (type-shares / fixture-shares / import-re-export / llm-arbitrated) connecting the two granularity levels.
+
+Do NOT invoke for:
+
+- v1-only consumers still on the 6-stage path (use the default `--granularity both` and the v1 envelope);
+- re-deriving the PRD — this skill consumes PRD output, it does not produce it.
+
+## Preconditions
+
+- `peaks codegraph index` has been run at least once (the orchestrator reads codegraph status during Pass 1 / Pass 2);
+- the audit-goal envelope for the project exists (`.peaks/_runtime/<sid>/audit-goal/<rid>.md` or equivalent) — without it, downstream `peaks-rd` dispatch cannot read the LLM-call budget context;
+- `--granularity` value is one of `service`, `file`, `both`, `auto`. The CLI rejects other values with `code: SLICE_DECOMPOSE_FAILED` BEFORE any I/O. Default `both` keeps the v1 path — for v2, pass an explicit non-default value.
+
+## Invocation
+
+```bash
+peaks slice decompose <rid> --granularity <service|file|both|auto> [--project <path>] [--refresh]
+```
+
+| Flag | Type | Default | Effect |
+|---|---|---|---|
+| `--granularity` | enum | `both` | `service` → Pass 1 only. `file` → Pass 2 only (no parent subdivision). `both` → Pass 1 + Pass 2 per parent, no filtering. `auto` → Pass 1 + Pass 2 only for parents where `shouldSubdivide()` is not explicitly false. |
+| `--project` | path | `.` | Target project root. |
+| `--refresh` | flag | `false` | Re-run `peaks codegraph index` before reading. |
+
+Exit code is non-zero only on `SLICE_DECOMPOSE_FAILED` (PRD not found, codegraph not initialised, invalid granularity, etc.). A successful run always emits the v2 envelope on disk; partial failures set `partial: true` rather than failing.
+
+## Output
+
+```text
+.peaks/sc/slice-decomposition/<rid>.json
+```
+
+The envelope is a `DecompositionResultV2` (see `references/v2-schema.md`):
+
+| Top-level field | Purpose |
+|---|---|
+| `schemaVersion` | Literal `'v2'`. Discriminator vs v1. |
+| `rid` | The request id passed in. |
+| `generatedAt` | ISO 8601 UTC. |
+| `passes` | Ordered `PassResult[]` — Pass 1 first, then Pass 2 (one entry per qualifying parent). |
+| `crossPassEdges` | Edges spanning passes (see `references/cross-pass-edge-interpretation.md`). |
+| `llmArbitrations` | Trace of every LLM call made during decomposition (capped at 2 per invocation). |
+| `codegraph` | `CodegraphEnvelope` — nodes/edges/dbMB/freshness/affectedCrossFile/note. |
+| `understandAnything` | `UnderstandAnythingEnvelope` — kgNodes/kgEdges/available/fallback/note. |
+| `partial` | `true` iff any pass failed to complete. |
+
+The file is pretty-printed (`JSON.stringify(result, null, 2)`). Size scales with `passes.length * slices.length` plus the arbitration trace; typical runs are 5–80 KB.
+
+## How peaks-rd / peaks-qa / peaks-final-review consume this
+
+- `peaks-rd` reads `passes[*].slices` to build the dispatch graph; `crossPassEdges` become the `dependsOn` set in `peaks request init`.
+- `peaks-rd` reads `llmArbitrations[*].callId` (referenced by `CrossPassEdge.arbitratedBy`) to audit any LLM-inferred relationship.
+- `peaks-qa` reads `passes[*].partial` and the top-level `partial` flag to detect incomplete decomposition before launching the verification fan-out.
+- `peaks-final-review` reads `passes[*].granularity` to confirm the slice topology matches the PRD's stated scope.
+
+Consumers MUST go through `SchemaRouter.readResult()`. v1 envelopes still on disk (legacy) are read transparently as `DecompositionResult`; the router narrows on `schemaVersion`.
+
+## Surgical-change contract
+
+This skill does NOT modify source code. It documents the v2 envelope produced by the W2 orchestrator modules (`multi-pass-orchestrator.ts`, `granularity-decider.ts`, `cross-pass-edge-merger.ts`, `slice-topology-types.ts`, `schema-router.ts`). Schema changes require a `schemaVersion` bump and a router update.
+
+## References
+
+| File | Coverage |
+|---|---|
+| `references/v2-schema.md` | Field-by-field table for `DecompositionResultV2`, `PassResult`, `SliceV2`, `CrossPassEdge.arbitratedBy`, `LlmArbitration`. |
+| `references/granularity-decision.md` | Decision tree for the 4 `--granularity` modes; `shouldSubdivide()` thresholds + tie-break semantics. |
+| `references/cross-pass-edge-interpretation.md` | The 4 edge kinds and how `peaks-rd` should use them for dispatch ordering; `LlmArbitration` trace reader. |

package/skills/peaks-slice-decompose/references/cross-pass-edge-interpretation.md

@@ -0,0 +1,158 @@
+# Cross-pass edge interpretation
+
+Source of truth: `src/services/slice/cross-pass-edge-merger.ts` (`merge` function) + `src/services/slice/llm-arbitrator.ts` (`arbitrate`). Read this together with `references/v2-schema.md` for the field-level definitions.
+
+## What is a `CrossPassEdge`
+
+A directed edge connecting a slice in one pass (the **upper / coarser** pass) to a slice in another pass (the **lower / finer** pass). Direction: `fromSliceId` ∈ upper pass → `toSliceId` ∈ lower pass. Edges are produced ONLY when `--granularity` is non-default AND `opts.llmRunner` is provided to `MultiPassOrchestrator.decompose`. Without an `llmRunner`, the envelope ships `crossPassEdges: []` and `llmArbitrations: []`.
+
+## Pipeline per adjacent pass pair
+
+```
+for each adjacent (upper, lower) pair in passes:
+    build upperFileToSlice: Map<file, sliceId> from upper.slices
+    for each slice in lower.slices:
+        for each file in slice.files:
+            detectStaticEdges(file, slice.id, ...)  # appends CrossPassEdges
+        if no edge emitted for this slice AND llmRunner available AND budget remaining:
+            runLlmFallback(upper, slice, ...)        # at most one edge per slice
+```
+
+Pairs are processed left-to-right so the order of `crossPassEdges[]` is deterministic.
+
+## The 4 edge kinds
+
+### 1. `type-shares`
+
+**Meaning:** a lower-pass file has `import type { ... } from '...'` whose target resolves to a file owned by an upper-pass slice. The two slices share a TypeScript type across the granularity boundary.
+
+| Field | Value |
+|---|---|
+| `kind` | `'type-shares'` |
+| `confidence` | `'structural'` |
+| `arbitratedBy` | `null` |
+| `evidence` | The matched `import type { ... } from '...'` line. |
+| Detector regex | `/import\s+type\s+(?:\{[^}]*\}\|\*\s+as\s+\w+\|\w+)\s+from\s+['"]([^'"]+)['"]/g` |
+
+**Dispatch ordering for `peaks-rd`:** a `type-shares` edge means the lower slice's runtime correctness depends on the upper slice's type definitions shipping first. Add the upper slice as a `dependsOn` ancestor of the lower slice in the dispatch graph.
+
+### 2. `fixture-shares`
+
+**Meaning:** a lower-pass file is a test file (`.test.ts` / `.test.tsx` / `.test.js`, OR under `__tests__/`, OR under `tests/`) AND it has a `from '...'` import whose target resolves to a file owned by an upper-pass slice.
+
+| Field | Value |
+|---|---|
+| `kind` | `'fixture-shares'` |
+| `confidence` | `'structural'` |
+| `arbitratedBy` | `null` |
+| `evidence` | The matched `from '...'` line. |
+| File predicate | `isTestFile(filePath)` (see `cross-pass-edge-merger.ts:330`) |
+
+**Dispatch ordering for `peaks-rd`:** the lower slice's tests cannot run until the upper slice is built. Sequence the upper slice first; treat the lower slice as part of the upper slice's verification chain.
+
+### 3. `import-re-export`
+
+**Meaning:** a lower-pass file has `export { ... } from '...'` (or `export * from '...'` / `export type { ... } from '...'`) whose target resolves to a file owned by an upper-pass slice. The lower slice re-exports an upper-slice symbol.
+
+| Field | Value |
+|---|---|
+| `kind` | `'import-re-export'` |
+| `confidence` | `'structural'` |
+| `arbitratedBy` | `null` |
+| `evidence` | The matched `export ... from '...'` line. |
+| Detector regex | `/\bexport\s+(?:type\s+)?(?:\*\|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/g` |
+
+**Dispatch ordering for `peaks-rd`:** the lower slice's public API is a re-export of the upper slice's symbols. Sequencing must put the upper slice first; consumers of the lower slice's exports cannot resolve until the upper slice's symbols exist.
+
+### 4. `llm-arbitrated`
+
+**Meaning:** the static detectors produced NO edge for this lower slice, the budget allowed, and the LLM arbitrator returned `{"depends": true, "reason": "..."}` for the prompt `"Does upper slice <upper> depend on lower slice <lower>?"`.
+
+| Field | Value |
+|---|---|
+| `kind` | `'llm-arbitrated'` |
+| `confidence` | `'llm'` |
+| `arbitratedBy` | The `LlmArbitration.callId` (non-null; foreign key into `llmArbitrations[]`). |
+| `evidence` | `llm:<callId>: <reason>` — the LLM's free-text reason. |
+
+**Dispatch ordering for `peaks-rd`:** `llm-arbitrated` edges are LLM inferences, not ground truth. Treat them as a dispatch-ordering **hint**, not a hard dependency. The auditor at `peaks-qa` may challenge the edge by reading the arbitration trace (`llmArbitrations[callId]`). For the initial dispatch pass, sequence the upper slice first; if a `peaks-rd` reviewer later concludes the LLM was wrong, drop the edge and re-dispatch.
+
+## Resolution algorithm
+
+`resolveImport(fromFile, spec)` (in `cross-pass-edge-merger.ts`):
+
+1. If `spec` is absolute, take it as-is. Otherwise resolve relative to `dirname(fromFile)`.
+2. Try each extension in `RESOLVE_EXTENSIONS` (`'', '.ts', '.tsx', '.js', '/index.ts', '/index.tsx', '/index.js'`) and return the first that exists on disk.
+3. If none exist (virtual / generated), fall back to `<base>.ts` so the upper-index lookup still matches against the same key the orchestrator indexed.
+
+## Static-vs-LLM dispatch summary
+
+| Edge kind | Confidence | Source | Auditor action |
+|---|---|---|---|
+| `type-shares` | `structural` | regex | none — trust as-is |
+| `fixture-shares` | `structural` | regex + `isTestFile` | none — trust as-is |
+| `import-re-export` | `structural` | regex | none — trust as-is |
+| `llm-arbitrated` | `llm` | LLM via `arbitrate()` | read `llmArbitrations[arbitratedBy]`; reject if reason is empty or contradicts codegraph |
+
+## Reading the `LlmArbitration` trace
+
+`llmArbitrations[]` is the audit trail for every LLM call made during decomposition. Cap: **≤ 2 calls per invocation** (`maxLlmCalls = 2`, default; the merger returns early when the budget is exhausted and never crashes).
+
+```ts
+interface LlmArbitration {
+  readonly callId: string;
+  readonly promptHash: string;        // sha256 hex; '' for MultiPassOrchestrator-produced entries (W2)
+  readonly input: string;             // the actual prompt; '' for MultiPassOrchestrator-produced entries
+  readonly output: string;            // the raw LLM response; '' for MultiPassOrchestrator-produced entries
+  readonly confidence: 'high' | 'medium' | 'low';  // currently 'low' from MultiPassOrchestrator
+  readonly tokens: { input: number; output: number };  // coalesced from null
+}
+```
+
+### Walk-the-trace pseudocode
+
+```ts
+const v2 = readResult(outPath);  // DecompositionResultV2
+
+for (const edge of v2.crossPassEdges) {
+  if (edge.kind !== 'llm-arbitrated') continue;
+  const arb = v2.llmArbitrations.find(a => a.callId === edge.arbitratedBy);
+  if (!arb) {
+    // foreign-key violation — log and skip
+    continue;
+  }
+  // arb.confidence, arb.tokens, arb.promptHash are the audit handle.
+  // arb.input / arb.output are currently '' for MultiPassOrchestrator entries;
+  // W5+ will fill them in.
+}
+```
+
+### What to do when audit fields are empty
+
+`MultiPassOrchestrator`'s `llmCallsToArbitrations` helper fills `promptHash`, `input`, `output` with empty strings and `confidence` with `'low'`. This is a known limitation of W2 — the merger traces only `callId` and `tokens`. For full LLM provenance, either:
+
+- re-run `merge(passes, opts)` programmatically with `opts.cacheDir` pointing at `.peaks/cache/arbitrator`, OR
+- wait for W5+ to extend `merge` to surface the full trace into `LlmArbitration`.
+
+Until then, `callId` is the only stable foreign key. A future `peaks-rd` revision will index `.peaks/cache/arbitrator` by `promptHash` so reviewers can replay the call.
+
+## Field reference
+
+```ts
+type CrossPassEdgeKind =
+  | 'type-shares'
+  | 'fixture-shares'
+  | 'import-re-export'
+  | 'llm-arbitrated';
+
+interface CrossPassEdge {
+  readonly fromPass: PassNumber;        // 1 | 2 | 3
+  readonly toPass: PassNumber;
+  readonly fromSliceId: string;
+  readonly toSliceId: string;
+  readonly kind: CrossPassEdgeKind;
+  readonly confidence: EdgeConfidence | 'llm';
+  readonly evidence: string;
+  readonly arbitratedBy: string | null; // foreign key into LlmArbitration.callId
+}
+```

package/skills/peaks-slice-decompose/references/granularity-decision.md

@@ -0,0 +1,129 @@
+# Granularity decision
+
+Source of truth: `src/services/slice/multi-pass-orchestrator.ts` (orchestrator) + `src/services/slice/granularity-decider.ts` (`shouldSubdivide`). Defaults: `granularity = 'both'`. `DEFAULT_THRESHOLDS = { maxFiles: 3, maxLoc: 400 }`.
+
+This reference is what `peaks-rd` reads to decide which `--granularity` value to pass when invoking `peaks slice decompose` for a given PRD.
+
+## Top-level decision
+
+```
+peaks slice decompose <rid> --granularity ?
+            |
+            v
+    ┌───────┴────────┐
+    │                │
+ service           file / both / auto
+ (Pass 1 only)          |
+                        v
+              run Pass 1 if granularity includes 'service'
+                        |
+                        v
+              run Pass 2 if granularity includes 'file'
+                        |
+                        v
+              crossPassEdges = llmRunner ? merge(passes) : []
+```
+
+## Mode table
+
+| `--granularity` | Pass 1? | Pass 2? | Parent subdivision? | Per-parent filter |
+|---|---|---|---|---|
+| `service` | yes | no | n/a | n/a |
+| `file` | no | yes (one call, full scope) | no — every `WorkUnit` becomes a Pass 2 slice with `parentSliceId: null` | none |
+| `both` | yes | yes (one Pass 2 call per Pass 1 slice) | yes — every Pass 1 slice becomes a parent | none — every Pass 1 slice gets a Pass 2 expansion |
+| `auto` | yes | yes (one Pass 2 call per qualifying Pass 1 slice) | yes — but only for parents where `shouldSubdivide(wu).subdivide !== false` | `shouldSubdivide(wu)` (see below) |
+
+Default is `both`. The CLI description flags this: `"both"` is the v1 path-equivalent; non-default values enable v2 multi-pass.
+
+## `shouldSubdivide(wu, thresholds?)` semantics
+
+Source: `granularity-decider.ts`. Pure function. No LLM dependency.
+
+```ts
+interface GranularityThresholds {
+  readonly maxFiles: number;  // default 3
+  readonly maxLoc: number;    // default 400
+}
+```
+
+The function returns one of three branches:
+
+| Branch | Trigger | Meaning |
+|---|---|---|
+| `{ subdivide: true, reason }` | `wu.loc > maxLoc` OR `wu.files.length > maxFiles` | Strictly over threshold. Split now. |
+| `{ subdivide: 'tie-break', reason }` | `wu.loc > maxLoc * 0.8` OR `wu.files.length > maxFiles * 0.8` (and not strictly over) | Within 20% of threshold. Defer to LLM arbitrator for the final call. |
+| `{ subdivide: false, reason }` | otherwise | Under threshold. Stop subdividing. |
+
+### Boundary semantics
+
+- `>` (strict). At the exact threshold (`wu.loc === maxLoc`, `wu.files.length === maxFiles`) the result is `subdivide: false`. The threshold is exclusive — we only subdivide what is OVER it.
+- `auto` mode treats both `true` and `'tie-break'` as qualifying (`subdivide !== false`). Only `false` is filtered out.
+
+### Tie-break behavior
+
+`auto` mode does NOT itself consult the LLM — the `'tie-break'` branch only signals that the workUnit is borderline. The actual LLM call happens during cross-pass edge detection in `cross-pass-edge-merger.ts` (see `references/cross-pass-edge-interpretation.md`). The merge step may add an `llm-arbitrated` edge even when the parent was subdivided as `'tie-break'`.
+
+## `auto` decision tree
+
+For each Pass 1 slice, the orchestrator asks `shouldSubdivide(slice).subdivide !== false`:
+
+```
+Pass 1 slice
+    |
+    v
+shouldSubdivide(wu)?
+    |
+    ├── true           ──> qualifies for Pass 2 expansion
+    ├── 'tie-break'    ──> qualifies for Pass 2 expansion
+    └── false          ──> skip Pass 2 (slice remains a leaf)
+```
+
+## `both` decision tree
+
+```
+Pass 1 slice
+    |
+    v
+always qualifies for Pass 2 expansion
+```
+
+`both` is the unfiltered superset. Use it when you want maximum resolution at the cost of file-size growth.
+
+## When to use which mode
+
+| Mode | Use when |
+|---|---|
+| `service` | The PRD is about service boundaries (monorepo → micro-services, layered architecture). Pass 1 alone is sufficient; file-level cuts would dilute the boundary signal. |
+| `file` | The PRD is about a single large surface (one file or one module). Skip the service-level cut; go straight to file-level cuts across the full scope. |
+| `both` | Default. Both granularities are wanted and every Pass 1 slice should expand. Most general-purpose runs. |
+| `auto` | Most Pass 1 slices are already small; only the outliers (loose `shouldSubdivide` threshold or borderline) need Pass 2 expansion. Smaller artifact, faster run. |
+
+## Default-thresholds rationale
+
+`maxFiles: 3, maxLoc: 400` is the v2 default. A slice with ≤ 3 files OR ≤ 400 LoC is considered already-small; one above either threshold needs subdivision. The 20% borderline band (`maxFiles * 0.8 = 2.4`, `maxLoc * 0.8 = 320`) catches slices that read like one unit but are technically approaching the cap.
+
+For projects with very different file sizes, override `DEFAULT_THRESHOLDS` via a future CLI flag — currently the thresholds are not exposed on the CLI surface; pass them via `MultiPassOptions` only in programmatic use.
+
+## Stop condition
+
+Subdivision stops at Pass 2 in v2. There is no Pass 3 in current production even though `PassNumber` allows `3` (`'sub-file'` is reserved). The `MultiPassOrchestrator.decompose` function only emits `passNumber: 1` and `passNumber: 2` entries.
+
+If a Pass 2 slice is itself over threshold, the v2 envelope records it as-is — there is no recursive Pass 3. Consumers that need recursive subdivision must re-run with a project-local script against `MultiPassOrchestrator.decompose`.
+
+## Field reference for the decision
+
+```ts
+export type Granularity = 'service' | 'file' | 'both' | 'auto';
+
+export interface MultiPassOptions extends DecomposeOptions {
+  readonly granularity?: Granularity;     // default 'both'
+  readonly llmRunner?: LlmRunner;         // when present, crossPassEdges are computed
+}
+```
+
+```ts
+export const DEFAULT_THRESHOLDS: GranularityThresholds = {
+  maxFiles: 3,
+  maxLoc: 400
+};
+```

package/skills/peaks-slice-decompose/references/v2-schema.md

@@ -0,0 +1,156 @@
+# v2 schema — `DecompositionResultV2`
+
+Source of truth: `src/services/slice/slice-topology-types.ts` (W2 T6). All fields are `readonly`. `peaks slice decompose` with a non-default `--granularity` emits this envelope; the default `both` keeps the v1 `DecompositionResult` (see `slice-decompose-types.ts`).
+
+The CLI serialises via `SchemaRouter.writeResult()` → `JSON.stringify(result, null, 2)`.
+
+## Discriminator
+
+| Field | Type | Value | Purpose |
+|---|---|---|---|
+| `schemaVersion` | literal | `'v2'` | Read-side router branches on this. v1 files have the field absent. |
+
+## Top-level envelope — `DecompositionResultV2`
+
+| Field | Type | Source | Notes |
+|---|---|---|---|
+| `schemaVersion` | `'v2'` | orchestrator | Discriminator. |
+| `rid` | `string` | CLI arg | Echoes the input request id. |
+| `generatedAt` | `string` | `new Date().toISOString()` | ISO 8601 UTC, e.g. `2026-06-25T12:00:00.000Z`. |
+| `passes` | `readonly PassResult[]` | `MultiPassOrchestrator.decompose` | Ordered: Pass 1 first (if requested), then Pass 2 (one entry per qualifying parent). Length: 0–N. |
+| `crossPassEdges` | `readonly CrossPassEdge[]` | `cross-pass-edge-merger.ts` (via `merge`) | Empty when `opts.llmRunner` is not provided. |
+| `llmArbitrations` | `readonly LlmArbitration[]` | `merge.llmCalls` mapped via `llmCallsToArbitrations` | Empty when no LLM call was made. Cap: ≤ 2 calls per invocation. |
+| `codegraph` | `CodegraphEnvelope` | from Pass 1 / Pass 2 result | Reused from v1 (see `slice-decompose-types.ts`). Falls back to `zeroCodegraph()` if neither pass ran. |
+| `understandAnything` | `UnderstandAnythingEnvelope` | from Pass 1 / Pass 2 result | Reused from v1. Falls back to `zeroUnderstand()` if neither pass ran. |
+| `partial` | `boolean` | orchestrator | `true` iff any pass failed to complete. Currently always `false` from `MultiPassOrchestrator`; reserved for future partial-failure paths. |
+
+## `CodegraphEnvelope` (re-exported from v1)
+
+| Field | Type | Notes |
+|---|---|---|
+| `nodes` | `number` | Codegraph node count at the time of decomposition. |
+| `edges` | `number` | Codegraph edge count. |
+| `dbMB` | `number` | Codegraph database size. |
+| `freshness` | `string` | Git SHA at which the index was built, or `'unindexed'`. |
+| `affectedCrossFile` | `boolean` | `true` iff `codegraph.affected` reported > 0 cross-file dependents. |
+| `note` | `string` | Free-form operator note; `'no decomposition run'` when both passes were skipped. |
+
+## `UnderstandAnythingEnvelope` (re-exported from v1)
+
+| Field | Type | Notes |
+|---|---|---|
+| `kgNodes` | `number` | Knowledge-graph node count. |
+| `kgEdges` | `number` | Knowledge-graph edge count. |
+| `available` | `boolean` | `false` when the `.understand-anything/knowledge-graph.json` file is missing. |
+| `fallback` | `'semantic' \| 'structural-only'` | `'structural-only'` when `available` is `false`. |
+| `note` | `string` | Free-form note. |
+
+## `PassResult`
+
+| Field | Type | Notes |
+|---|---|---|
+| `passNumber` | `PassNumber` (`1 \| 2 \| 3`) | `3` reserved for future sub-file pass. |
+| `granularity` | `SliceGranularity` (`'service' \| 'file' \| 'sub-file'`) | The granularity the pass was run at. |
+| `slices` | `readonly SliceV2[]` | One entry per discovered slice. Length: 0–N. |
+| `internalEdges` | `readonly InternalEdge[]` | Always `[]` in current `MultiPassOrchestrator`. Reserved for future within-pass edges. |
+
+### `SliceV2`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Stable id within the pass. Pass 1: `"W1".."Wn"`. Pass 2: `"<parent.id>.<i+1>"`, e.g. `"W1.3"`. |
+| `label` | `string` | Human-readable; shown in `peaks slice pick` fzf list (v1 only — current pick consumes v1 envelopes). |
+| `granularity` | `SliceGranularity` | Matches the enclosing `PassResult.granularity`. |
+| `files` | `readonly string[]` | Project-relative paths. |
+| `loc` | `number` | Total LoC across all `files`. |
+| `parentSliceId` | `string \| null` | `null` for Pass 1. For Pass 2, the id of the parent Pass 1 slice. |
+| `semanticAnchor` | `string` | `"domain:<name>"` when understand-anything indexed, else `"file:<path>"`. Currently always `"file:<wu.filePath>"` from the orchestrator's `workUnitToSliceV2`. |
+
+### `InternalEdge` (reserved)
+
+| Field | Type | Notes |
+|---|---|---|
+| `from` | `string` | SliceV2 id. |
+| `to` | `string` | SliceV2 id. |
+| `kind` | `InternalEdgeKind` (`'imports' \| 'calls' \| 'depends_on' \| 'contains_flow' \| 'flow_step'`) | Within-pass edge kind. |
+| `weight` | `number` | Downstream min-cut / dispatch-ordering heuristic input. |
+| `evidence` | `string` | The actual import statement or graph edge. |
+| `confidence` | `EdgeConfidence` (`'structural' \| 'semantic'`) | Source of the edge. |
+
+> **Note:** `MultiPassOrchestrator` always emits `internalEdges: []`. This contract is reserved for a future within-pass edge detector; v2 consumers must tolerate an empty array.
+
+## `CrossPassEdge`
+
+| Field | Type | Notes |
+|---|---|---|
+| `fromPass` | `PassNumber` | The upper (coarser) pass number. |
+| `toPass` | `PassNumber` | The lower (finer) pass number. Always `fromPass < toPass`. |
+| `fromSliceId` | `string` | Slice id in `fromPass`. |
+| `toSliceId` | `string` | Slice id in `toPass`. |
+| `kind` | `CrossPassEdgeKind` (`'type-shares' \| 'fixture-shares' \| 'import-re-export' \| 'llm-arbitrated'`) | See `references/cross-pass-edge-interpretation.md`. |
+| `confidence` | `EdgeConfidence \| 'llm'` | `'llm'` only when `kind === 'llm-arbitrated'`. Structural detectors emit `'structural'`. |
+| `evidence` | `string` | Human-readable: the import line, the shared fixture id, or `llm:<callId>: <reason>` for LLM edges. |
+| `arbitratedBy` | `string \| null` | The `LlmArbitration.callId` that produced this edge, or `null` for static-detected edges. |
+
+### `arbitratedBy` discriminator
+
+| Value | Meaning |
+|---|---|
+| `null` | Edge was emitted by a static detector (`type-shares` / `fixture-shares` / `import-re-export`). |
+| `string` (a `callId`) | Edge was emitted by the LLM fallback (`kind === 'llm-arbitrated'`). The `callId` is a foreign key into `llmArbitrations[].callId`. |
+
+If `kind === 'llm-arbitrated'` then `arbitratedBy` MUST be a non-null `callId`. If `kind !== 'llm-arbitrated'` then `arbitratedBy` MUST be `null`. The CLI does not enforce this at the type level (TypeScript's structural typing allows mismatches) — downstream consumers may assert.
+
+## `LlmArbitration`
+
+| Field | Type | Notes |
+|---|---|---|
+| `callId` | `string` | Stable id within the invocation. Referenced by `CrossPassEdge.arbitratedBy`. |
+| `promptHash` | `string` | sha256 hex of the prompt; used for content-hash cache lookup. Currently `''` (empty string) when produced via `MultiPassOrchestrator` — see `llmCallsToArbitrations`. |
+| `input` | `string` | The actual prompt sent to the LLM. Currently `''` (empty string) when produced via `MultiPassOrchestrator`. |
+| `output` | `string` | The raw LLM response. Currently `''` (empty string) when produced via `MultiPassOrchestrator`. |
+| `confidence` | `LlmConfidence` (`'high' \| 'medium' \| 'low'`) | Currently always `'low'` when produced via `MultiPassOrchestrator`. Real values land when the merger surfaces the full trace (W5+). |
+| `tokens` | `{ input: number; output: number }` | Token count for the call. Coalesced to `{ input: 0, output: 0 }` when the underlying trace carries `null`. |
+
+> **Implication for audit:** consumers that need to inspect the actual prompt or response currently see empty strings for `LlmArbitration` produced by `MultiPassOrchestrator`. Use `callId` as a foreign key into a future side-channel trace, or wait for the W5+ merger upgrade that fills these fields.
+
+## Type unions (quick reference)
+
+```ts
+export type SchemaVersion = 'v1' | 'v2';
+export type SliceGranularity = 'service' | 'file' | 'sub-file';
+export type PassNumber = 1 | 2 | 3;
+export type EdgeConfidence = 'structural' | 'semantic';
+export type LlmConfidence = 'high' | 'medium' | 'low';
+export type InternalEdgeKind =
+  | 'imports' | 'calls' | 'depends_on' | 'contains_flow' | 'flow_step';
+export type CrossPassEdgeKind =
+  | 'type-shares' | 'fixture-shares' | 'import-re-export' | 'llm-arbitrated';
+```
+
+## Read path (BLOCKING)
+
+```ts
+import { readResult } from '../../services/slice/schema-router.js';
+
+const parsed = readResult(outPath);
+if (parsed.schemaVersion === 'v2') {
+  // typed as DecompositionResultV2
+} else {
+  // typed as DecompositionResult (v1)
+}
+```
+
+`SchemaRouter.readResult()` throws `UnknownSchemaVersionError` (code `UNKNOWN_SCHEMA_VERSION`) for any other `schemaVersion` value. The CLI maps that to exit code 1 with a `nextActions` hint. Do not swallow the error — the file may be a partial write from a crashed orchestrator.
+
+## Schema migration contract
+
+Any future schema change MUST:
+
+1. Add a new `SchemaVersion` literal (`'v3'` etc.).
+2. Extend `SchemaRouter.readResult()` to accept and dispatch it.
+3. Bump `DecompositionResultV3.schemaVersion: 'v3'`.
+4. Keep the v2 reader path intact (no in-place rewrite of v2 files).
+5. Update this reference + add a `references/v3-schema.md`.
+
+In-place edits to v1/v2 fields are forbidden: any consumer that already wrote a v2 file expects its schema to remain stable.