peaks-loop 4.1.0 → 4.1.2

package/dist/services/observability/aggregation.d.ts

@@ -7,10 +7,6 @@
  * them in. Tests pass synthetic events directly.
  *
  * Aggregations:
- *   - `aggregateStatus(events)`        → AC-1
- *   - `aggregateSlices(events)`        → AC-2
- *   - `aggregateFanout(events)`        → AC-3
- *   - `aggregateRepairCycles(events)`  → AC-4
  *
  * The dispatch / mode-gate / context / post-compact categories land
  * in Slice C (more hooks); for Slice B only `slice-transition` events

package/dist/services/observability/aggregation.js

@@ -7,10 +7,6 @@
  * them in. Tests pass synthetic events directly.
  *
  * Aggregations:
- *   - `aggregateStatus(events)`        → AC-1
- *   - `aggregateSlices(events)`        → AC-2
- *   - `aggregateFanout(events)`        → AC-3
- *   - `aggregateRepairCycles(events)`  → AC-4
  *
  * The dispatch / mode-gate / context / post-compact categories land
  * in Slice C (more hooks); for Slice B only `slice-transition` events
@@ -129,7 +125,6 @@ export function aggregateRepairCycles(events) {
         perSlice
     };
 }
-// ----- period rollup (AC-5 — Slice D, but helpers live here) -----
 export function periodStartIso(period, now = () => new Date()) {
     const d = now();
     if (period === 'day') {
@@ -151,7 +146,6 @@ export function filterByPeriod(events, period, now) {
     const start = periodStartIso(period, now);
     return events.filter((e) => e.ts >= start);
 }
-// ----- rid-030 F-direction: 5-metric dashboard summary -----
 /**
  * Aggregate the 5 dashboard metric classes for a single session, filtered
  * to events with `ts >= since`. Events with unparseable timestamps are

package/dist/services/observability/observability-schema.js

@@ -25,7 +25,6 @@ export const OBSERVABILITY_CATEGORIES = [
     'cycle',
     'token-usage',
     'monotonic-trigger',
-    // Slice 2026-07-29-worktree-l2-extended Part 4.A: lease lifecycle
     // metrics. Emitted by `peaks worktree spawn / renew / release /
     // gc` and by the auto-release hook in dispatch finalization (Part
     // 3.A). Read by `peaks lease metrics`. The `detail.kind` field

package/dist/services/observability/observability-service.d.ts

@@ -50,7 +50,6 @@ export declare function readObservabilityEvents(projectRoot: string, sessionId:
  */
 export declare function isCurrentSchemaVersion(record: unknown): record is ObservabilityEvent;
 /**
- * Slice 2026-07-29-worktree-l2-extended Part 4.A: lease lifecycle
  * observability. Each `peaks worktree spawn / renew / release /
  * gc` CLI emits a `lease` event; the auto-release hook in
  * dispatch finalization emits `autoRelease` (success) or
@@ -74,7 +73,6 @@ export declare function emitLeaseEvent(opts: {
     reason?: string;
 }): EmitResult;
 /**
- * rid-030 F-direction: per-cycle event (cycle started / completed / failed).
  * Fire-and-forget; never throws. Tagging `kind` for downstream dashboards.
  */
 export declare function emitCycleEvent(opts: {
@@ -84,7 +82,6 @@ export declare function emitCycleEvent(opts: {
     status: 'started' | 'completed' | 'failed';
 }): EmitResult;
 /**
- * rid-030 F-direction: per-token-usage event. `totalTokens` is the
  * sum the dashboard cares about; `inputTokens`/`outputTokens` are kept
  * for downstream drill-down.
  */
@@ -95,7 +92,6 @@ export declare function emitTokenUsageEvent(opts: {
     outputTokens: number;
 }): EmitResult;
 /**
- * rid-030 F-direction: per-monotonic-trigger event.
  */
 export declare function emitMonotonicTriggerEvent(opts: {
     sessionId: string;
@@ -104,7 +100,6 @@ export declare function emitMonotonicTriggerEvent(opts: {
     action: string;
 }): EmitResult;
 /**
- * rid-030 F-direction: per-subagent-dispatch event. Reuses the
  * existing `dispatch` category (rd/qa/reviewer/audit). Provides a
  * canonical emit helper so dashboards don't have to hand-author the
  * `ObservabilityEvent` envelope.

package/dist/services/observability/observability-service.js

@@ -117,7 +117,6 @@ export function emitLeaseEvent(opts) {
     }, { projectRoot: opts.projectRoot });
 }
 /**
- * rid-030 F-direction: per-cycle event (cycle started / completed / failed).
  * Fire-and-forget; never throws. Tagging `kind` for downstream dashboards.
  */
 export function emitCycleEvent(opts) {
@@ -130,7 +129,6 @@ export function emitCycleEvent(opts) {
     }, { projectRoot: opts.projectRoot });
 }
 /**
- * rid-030 F-direction: per-token-usage event. `totalTokens` is the
  * sum the dashboard cares about; `inputTokens`/`outputTokens` are kept
  * for downstream drill-down.
  */
@@ -149,7 +147,6 @@ export function emitTokenUsageEvent(opts) {
     }, { projectRoot: opts.projectRoot });
 }
 /**
- * rid-030 F-direction: per-monotonic-trigger event.
  */
 export function emitMonotonicTriggerEvent(opts) {
     return emitObservabilityEvent({
@@ -161,7 +158,6 @@ export function emitMonotonicTriggerEvent(opts) {
     }, { projectRoot: opts.projectRoot });
 }
 /**
- * rid-030 F-direction: per-subagent-dispatch event. Reuses the
  * existing `dispatch` category (rd/qa/reviewer/audit). Provides a
  * canonical emit helper so dashboards don't have to hand-author the
  * `ObservabilityEvent` envelope.

package/dist/services/observability/report-formatter.d.ts

@@ -1,13 +1,11 @@
 /**
  * Markdown report formatter for slice topology observability.
  *
- * Slice D of v2.11.1 (AC-5). Pure functions: inputs are aggregations
  * from `aggregation.ts`, outputs are stable markdown strings suitable
  * for pasting into PR descriptions or `.peaks/PROJECT.md` timeline
  * entries. The CLI subcommand `peaks observability report` wires
  * the file read + aggregation + format pipeline.
  *
- * Format contract (per PRD AC-5):
  *   - Header: scope, period, generated-at timestamp
  *   - Slice table: rid | transitions | finalState | durationMs | success
  *   - Fanout table: role | count

package/dist/services/observability/report-formatter.js

@@ -1,13 +1,11 @@
 /**
  * Markdown report formatter for slice topology observability.
  *
- * Slice D of v2.11.1 (AC-5). Pure functions: inputs are aggregations
  * from `aggregation.ts`, outputs are stable markdown strings suitable
  * for pasting into PR descriptions or `.peaks/PROJECT.md` timeline
  * entries. The CLI subcommand `peaks observability report` wires
  * the file read + aggregation + format pipeline.
  *
- * Format contract (per PRD AC-5):
  *   - Header: scope, period, generated-at timestamp
  *   - Slice table: rid | transitions | finalState | durationMs | success
  *   - Fanout table: role | count

package/dist/services/openspec/artifact-boundary.d.ts

@@ -1,7 +1,6 @@
 /**
  * Artifact boundary helpers for peaks-loop.
  *
- * Slice rid-009:
  *   - sub-slice 1: change-id validation (`validateChangeId`).
  *   - sub-slice 2: artifact path planning (`planArtifactPath` + `isPathInsideArtifactRoot` re-export).
  *   - sub-slice 3: workspace-unavailable response (`buildWorkspaceUnavailable`).
@@ -61,7 +60,6 @@ export type BoundaryError = ChangeIdError | {
  * distinguishes "empty" / "format" / "reserved" so callers can branch on
  * the cause without re-parsing the message.
  *
- * Acceptance contract (rid-009 §3.3.1, task 1):
  *   - accepts `[A-Za-z0-9][A-Za-z0-9._-]*` (existing regex semantics)
  *   - rejects empty string with `change-id-empty`
  *   - rejects `.` and `..` with `change-id-reserved`
@@ -80,7 +78,6 @@ export declare function validateChangeId(id: string): Result<{
  *
  * Single source of truth: the primitive is owned by `src/shared/path-safety.ts`;
  * this module owns the *domain* helpers (change-id + path planner) that consume
- * the primitive. Tests in `tests/unit/services/openspec/artifact-boundary.test.ts`
  * exercise the RE-EXPORT wiring; the primitive's own correctness is covered by
  * its native test file.
  */
@@ -109,7 +106,6 @@ export type PlanArtifactPathOutput = {
 /**
  * Plan an artifact-relative path under the configured Peaks artifact workspace.
  *
- * Semantics (rid-009 §3.3.2, tasks 5–9):
  *   - Backslashes in the candidate path are normalized to forward slashes for
  *     JSON safety; empty segments (`foo//bar`) are collapsed by `posix.normalize`.
  *   - If the resolved absolute path is NOT contained under `workspaceRoot`

package/dist/services/openspec/artifact-boundary.js

@@ -1,7 +1,6 @@
 /**
  * Artifact boundary helpers for peaks-loop.
  *
- * Slice rid-009:
  *   - sub-slice 1: change-id validation (`validateChangeId`).
  *   - sub-slice 2: artifact path planning (`planArtifactPath` + `isPathInsideArtifactRoot` re-export).
  *   - sub-slice 3: workspace-unavailable response (`buildWorkspaceUnavailable`).
@@ -38,7 +37,6 @@ const CHANGE_ID_FORMAT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
  * distinguishes "empty" / "format" / "reserved" so callers can branch on
  * the cause without re-parsing the message.
  *
- * Acceptance contract (rid-009 §3.3.1, task 1):
  *   - accepts `[A-Za-z0-9][A-Za-z0-9._-]*` (existing regex semantics)
  *   - rejects empty string with `change-id-empty`
  *   - rejects `.` and `..` with `change-id-reserved`
@@ -75,7 +73,6 @@ export function validateChangeId(id) {
  *
  * Single source of truth: the primitive is owned by `src/shared/path-safety.ts`;
  * this module owns the *domain* helpers (change-id + path planner) that consume
- * the primitive. Tests in `tests/unit/services/openspec/artifact-boundary.test.ts`
  * exercise the RE-EXPORT wiring; the primitive's own correctness is covered by
  * its native test file.
  */
@@ -90,7 +87,6 @@ function interpolateTemplate(template, changeId, role, requestId) {
 /**
  * Plan an artifact-relative path under the configured Peaks artifact workspace.
  *
- * Semantics (rid-009 §3.3.2, tasks 5–9):
  *   - Backslashes in the candidate path are normalized to forward slashes for
  *     JSON safety; empty segments (`foo//bar`) are collapsed by `posix.normalize`.
  *   - If the resolved absolute path is NOT contained under `workspaceRoot`

package/dist/services/openspec/coverage-evidence-reader.d.ts

@@ -1,7 +1,6 @@
 /**
  * Coverage Evidence reader for c8 `coverage-summary.json` (Fix-6B).
  *
- * Slice rid-Fix-6B / sub-slice T1:
  *   - pure helper module, no side effects beyond FS reads
  *   - reads the istanbul-reporter JSON shape emitted by `c8 --reporter=json-summary`
  *     (the project's coverage tool — see scripts/coverage-c8.mjs)

package/dist/services/openspec/coverage-evidence-reader.js

@@ -1,7 +1,6 @@
 /**
  * Coverage Evidence reader for c8 `coverage-summary.json` (Fix-6B).
  *
- * Slice rid-Fix-6B / sub-slice T1:
  *   - pure helper module, no side effects beyond FS reads
  *   - reads the istanbul-reporter JSON shape emitted by `c8 --reporter=json-summary`
  *     (the project's coverage tool — see scripts/coverage-c8.mjs)

package/dist/services/polyrepo/polyrepo-dispatcher.js

@@ -1,5 +1,4 @@
 /**
- * Polyrepo dispatcher — slice S2-b of RD-2.
  *
  * Takes a parent root + a list of target child ids + a PRD/RD/QA
  * artifact, and mirrors the artifact into each target child's

package/dist/services/polyrepo/polyrepo-scanner.js

@@ -1,5 +1,4 @@
 /**
- * Polyrepo scanner — slice S2-b of RD-2.
  *
  * Walks a parent directory looking for child git repos. A "child
  * git repo" is defined as: a directory that contains a `.git`

package/dist/services/polyrepo/polyrepo-service.js

@@ -1,5 +1,4 @@
 /**
- * Polyrepo service — slice S2-b of RD-2.
  *
  * Thin orchestrator wrapping the scanner + dispatcher. CLI commands
  * call into this service so they don't need to know about the

package/dist/services/polyrepo/polyrepo-types.d.ts

@@ -1,5 +1,4 @@
 /**
- * Polyrepo types — slice S2-b of RD-2.
  *
  * Models a parent directory that hosts one or more child git repos,
  * each of which may carry its own `.peaks/` state. The root `.peaks/`

package/dist/services/prd/best-practice-auto-trigger.d.ts

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-08-12 best-practice-scan — auto-trigger post-step (Slice F).
  *
  * When peaks-prd's request artifact transitions to `handed-off`, this helper
  * extracts the `businessGoal` (first non-empty bullet under `## Goals` of the
@@ -18,7 +17,6 @@
  *   - Spawn 'spawn' event        → status: 'triggered' (resolved; child detached)
  *
  * Karpathy §1 (Think Before Coding): extracted from the QA verdict
- * `verdict-rid-best-practice-scan-qa-ship.md` AC-1 PARTIAL finding. The
  * `prd:handed-off` transition in `src/cli/commands/request-commands.ts`
  * is the canonical hook point — peaks-prd's contract in
  * `skills/bee/peaks-prd/SKILL.md` §"Step 2.5 sub-step" mandates this firing

package/dist/services/prd/best-practice-auto-trigger.js

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-08-12 best-practice-scan — auto-trigger post-step (Slice F).
  *
  * When peaks-prd's request artifact transitions to `handed-off`, this helper
  * extracts the `businessGoal` (first non-empty bullet under `## Goals` of the
@@ -18,7 +17,6 @@
  *   - Spawn 'spawn' event        → status: 'triggered' (resolved; child detached)
  *
  * Karpathy §1 (Think Before Coding): extracted from the QA verdict
- * `verdict-rid-best-practice-scan-qa-ship.md` AC-1 PARTIAL finding. The
  * `prd:handed-off` transition in `src/cli/commands/request-commands.ts`
  * is the canonical hook point — peaks-prd's contract in
  * `skills/bee/peaks-prd/SKILL.md` §"Step 2.5 sub-step" mandates this firing

package/dist/services/prd/gate-evidence-derivation.d.ts

@@ -1,10 +1,8 @@
 /**
  * Where `gateEvidence` comes FROM, and where its promise is checked.
  *
- * B2 (merged with the B1 repair), rid `rid-b2-gate-evidence-wiring`.
  *
  * B1 made the field real at the SERVICE layer and QA found the hole that
- * mattered (F1 of `rid-b1-qa`): all three frontmatter producers passed
  * nothing, so no capsule on disk ever carried the field — the dead surface
  * had moved one layer out, from "no producer function" to "no production
  * caller". This module closes that by DERIVING the map instead of accepting
@@ -56,7 +54,6 @@
  * For `docs`/`chore` nothing ever reads it, so it is not declared: keeping an
  * inert statement in every docs capsule would recreate, in miniature, the exact
  * defect this whole line of work exists to remove — a claim no one reads, which
- * is how the field was dead in the first place (F1 of `rid-b2-qa`). Scope, in
  * one sentence: **this map declares the evidence paths Gate C will check for
  * this slice**, so an empty declaration is the honest one when there is no such
  * gate.
@@ -99,7 +96,6 @@ export declare function deriveGateEvidence(opts: {
  * so a caller can tell "this slice has nothing to declare" apart from "the
  * artifact could not be read".
  *
- * F4 (`rid-f4-ceiling-breach`). This used to be `catch { return undefined }`,
  * which folded those two into one value — and the repository's own ratchet
  * caught it (`capability-guard-runner/contracts/J03.ts`, rule
  * `catch-return-null`; the ceiling was written for exactly this shape). Nothing

package/dist/services/prd/gate-evidence-derivation.js

@@ -1,10 +1,8 @@
 /**
  * Where `gateEvidence` comes FROM, and where its promise is checked.
  *
- * B2 (merged with the B1 repair), rid `rid-b2-gate-evidence-wiring`.
  *
  * B1 made the field real at the SERVICE layer and QA found the hole that
- * mattered (F1 of `rid-b1-qa`): all three frontmatter producers passed
  * nothing, so no capsule on disk ever carried the field — the dead surface
  * had moved one layer out, from "no producer function" to "no production
  * caller". This module closes that by DERIVING the map instead of accepting
@@ -56,7 +54,6 @@
  * For `docs`/`chore` nothing ever reads it, so it is not declared: keeping an
  * inert statement in every docs capsule would recreate, in miniature, the exact
  * defect this whole line of work exists to remove — a claim no one reads, which
- * is how the field was dead in the first place (F1 of `rid-b2-qa`). Scope, in
  * one sentence: **this map declares the evidence paths Gate C will check for
  * this slice**, so an empty declaration is the honest one when there is no such
  * gate.
@@ -147,7 +144,6 @@ export function deriveGateEvidence(opts) {
  * so a caller can tell "this slice has nothing to declare" apart from "the
  * artifact could not be read".
  *
- * F4 (`rid-f4-ceiling-breach`). This used to be `catch { return undefined }`,
  * which folded those two into one value — and the repository's own ratchet
  * caught it (`capability-guard-runner/contracts/J03.ts`, rule
  * `catch-return-null`; the ceiling was written for exactly this shape). Nothing
@@ -163,7 +159,6 @@ export function deriveGateEvidence(opts) {
  * worse than a loud, already-duplicated one.
  */
 export async function deriveGateEvidenceForRequest(opts) {
-    // F4 (`rid-f4-ceiling-breach`). The throw from `showRequestArtifact` is
     // propagated, so a caller can tell "this slice has nothing to declare"
     // (artifact missing → `artifact === null` → `requestType === null` →
     // `undefined`) apart from "the artifact could not be read" (an id the

package/dist/services/prd/handoff-auto-regen.js

@@ -1,5 +1,4 @@
 /**
- * v2.13.2 AC-4 — prd/handoff-<rid>.md auto-regen on prd:handed-off.
  *
  * When `peaks request transition --role prd --state handed-off` succeeds
  * and this slice's capsule is missing, this helper writes a sha256-locked
@@ -8,8 +7,6 @@
  * the existing handoff is canonical (it may carry a richer body that
  * peaks-prd produced in an earlier session).
  *
- * Slice `2026-09-14-prd-capsule-rid-scoping`: the path carries the rid, so
- * "already exists" is now asked per SLICE. The pre-rid-scoping bare name is
  * deliberately NOT consulted — writing there would recreate the
  * one-slot-per-session collision for the next slice in the session.
  *
@@ -47,12 +44,10 @@ export async function autoRegenPrdHandoff(opts) {
     }
     const body = artifact.content;
     const sha256 = sha256OfBody(body);
-    // v2.13.3 AC-4 — align with `AUDIT_REQUIRES_HANDOFF` prereq which
     // pins `mustContain: ['schemaVersion: 2', 'sha256:']`. Primary field is
     // `sha256`; `handoffHash` is kept as a literal alias for the readers that
     // still use the old key.
     //
-    // Slice `2026-09-14-handoff-writer-gate-divergence`: this block used to be
     // hand-rolled here while `handoff-service.serializeHandoff` rendered the
     // SAME contract a second, incompatible way. Both now go through
     // `serializeHandoffFrontmatter`, so the two producers cannot drift again.

package/dist/services/prd/handoff-frontmatter-shape.d.ts

@@ -14,7 +14,6 @@ export declare function serializeHandoff(handoff: Handoff): string;
  * readable handoff was satisfied by a handoff the parser would not read, and
  * `peaks prd handoff verify` exited 1 on a healthy file.
  *
- * Slice `2026-09-14-handoff-writer-gate-divergence` then fixed the other half:
  * the writer no longer emits the quoted form at all (see
  * `handoff-frontmatter.ts`). This tolerance stays because handoffs already on
  * disk were written by the old writer and by hand; the writer fix must not
@@ -26,7 +25,6 @@ export declare function isSchemaVersion2(value: unknown): boolean;
  * strings — an ARRAY here is the pre-B1 shape its own test file used to
  * write, and it is a broken declaration, not a claim.
  *
- * F2 of `rid-b1-qa` removed this function's own copy of the shape rule. It
  * used to be a second predicate (same boundary, different downstream result)
  * that let the same bytes read one way here and another way through
  * `readHandoffGateEvidence`; both now ask `classifyGateEvidence`. Only

package/dist/services/prd/handoff-frontmatter-shape.js

@@ -34,7 +34,6 @@ export function serializeHandoff(handoff) {
  * readable handoff was satisfied by a handoff the parser would not read, and
  * `peaks prd handoff verify` exited 1 on a healthy file.
  *
- * Slice `2026-09-14-handoff-writer-gate-divergence` then fixed the other half:
  * the writer no longer emits the quoted form at all (see
  * `handoff-frontmatter.ts`). This tolerance stays because handoffs already on
  * disk were written by the old writer and by hand; the writer fix must not
@@ -48,7 +47,6 @@ export function isSchemaVersion2(value) {
  * strings — an ARRAY here is the pre-B1 shape its own test file used to
  * write, and it is a broken declaration, not a claim.
  *
- * F2 of `rid-b1-qa` removed this function's own copy of the shape rule. It
  * used to be a second predicate (same boundary, different downstream result)
  * that let the same bytes read one way here and another way through
  * `readHandoffGateEvidence`; both now ask `classifyGateEvidence`. Only

package/dist/services/prd/handoff-frontmatter.d.ts

@@ -1,7 +1,6 @@
 /**
  * The ONE canonical serialization of `prd/handoff.md` frontmatter.
  *
- * Why this module exists (slice `2026-09-14-handoff-writer-gate-divergence`):
  * the handoff capsule is written by two producers and read by four
  * consumers, and they did not agree on the bytes:
  *

package/dist/services/prd/handoff-frontmatter.js

@@ -1,7 +1,6 @@
 /**
  * The ONE canonical serialization of `prd/handoff.md` frontmatter.
  *
- * Why this module exists (slice `2026-09-14-handoff-writer-gate-divergence`):
  * the handoff capsule is written by two producers and read by four
  * consumers, and they did not agree on the bytes:
  *
@@ -48,6 +47,20 @@ function blockSequence(key, values) {
         return [`${key}: []`];
     return [`${key}:`, ...values.map((value) => `  - ${yamlScalar(value)}`)];
 }
+/**
+ * The OPTIONAL form: no line at all when the field is absent or empty.
+ *
+ * `goals` and its siblings cannot use this — `isHandoffFrontmatter` requires an
+ * ARRAY there, so an omitted line would fail the shape check on read, and `[]` is
+ * the honest rendering of "declared, none". The authored fields have no such
+ * requirement: a capsule that names no files declares nothing, and a `files: []`
+ * line would read as a claim that the slice touches no file.
+ */
+function blockOptionalSequence(key, values) {
+    if (values === undefined || values.length === 0)
+        return [];
+    return [`${key}:`, ...values.map((value) => `  - ${yamlScalar(value)}`)];
+}
 /**
  * Render `gateEvidence` as a YAML map of quoted path scalars, or as NOTHING.
  *
@@ -71,7 +84,6 @@ function blockSequence(key, values) {
 function gateEvidenceBlock(evidence) {
     if (evidence === undefined)
         return [];
-    // F3 of `rid-b1-qa`: this function used to iterate only the five known keys,
     // so anything else was dropped WITHOUT A TRACE — `initHandoff({gateEvidence:
     // {projectScans: 'typo.md'}})` wrote no block at all and the capsule then
     // read back as `field-absent`, i.e. as if nothing had ever been declared.
@@ -103,6 +115,44 @@ function gateEvidenceBlock(evidence) {
     });
     return entries.length === 0 ? [] : ['gateEvidence:', ...entries];
 }
+/**
+ * Render a sequence of records (`decisions`, `risks`) as a YAML block list, or
+ * as NOTHING when the list is absent or empty — the same omission policy as
+ * `gateEvidence`, so a capsule that declares no risks gains no noise line.
+ *
+ * The field names are rendered in the order given, and every value is validated
+ * as a string HERE rather than dropped later. That is deliberate: the bug these
+ * fields fix was a serializer that rendered from the type and so discarded
+ * anything the type did not name, silently, on every rewrite. A record missing a
+ * required field therefore has to stop the write, not vanish from it.
+ */
+function blockRecords(key, items, requiredFields) {
+    if (items === undefined || items.length === 0)
+        return [];
+    const lines = [`${key}:`];
+    items.forEach((rawItem, index) => {
+        // The values are checked at RUNTIME, not trusted from the type, because a
+        // capsule reaches here from `readHandoff` as well as from a producer: the
+        // spread that makes an authored field survive a read also makes it survive
+        // unvalidated. A record missing a required field stops the write rather than
+        // vanishing from it — which is precisely how the old serializer made a
+        // declared risk look satisfied.
+        const record = rawItem !== null && typeof rawItem === 'object' ? { ...rawItem } : {};
+        const missing = requiredFields.filter((field) => typeof record[field] !== 'string' || record[field] === '');
+        if (missing.length > 0) {
+            throw new Error(`handoff: ${key}[${index}] is missing ${missing.join(', ')} — refusing to write a ` +
+                `record the next role cannot read (a risk without a mitigation is a red line, and ` +
+                'dropping the field is how it looked satisfied)');
+        }
+        requiredFields.forEach((field, fieldIndex) => {
+            const value = record[field];
+            lines.push(fieldIndex === 0
+                ? `  - ${field}: ${yamlScalar(value)}`
+                : `    ${field}: ${yamlScalar(value)}`);
+        });
+    });
+    return lines;
+}
 /**
  * Serialize `frontmatter` into the fenced block, terminated by the closing
  * `---` and a trailing newline. Callers append the body verbatim, which keeps
@@ -125,6 +175,15 @@ export function serializeHandoffFrontmatter(frontmatter) {
         ...blockSequence('acceptanceCriteria', frontmatter.acceptanceCriteria),
         ...blockSequence('preservedBehavior', frontmatter.preservedBehavior),
         `handoffPath: ${yamlScalar(frontmatter.handoffPath)}`,
+        // The authored fields: written by peaks-prd / peaks-rd, read by peaks-qa's
+        // mechanical cross-checks, and PRESERVED by every rewrite. They sit after
+        // `handoffPath` because `schemaVersion` and `sha256` must stay first-parsed,
+        // and before `gateEvidence` because that block is last by contract.
+        ...blockOptionalSequence('scope', frontmatter.scope),
+        ...blockOptionalSequence('files', frontmatter.files),
+        ...blockRecords('decisions', frontmatter.decisions, ['id', 'summary', 'rationale']),
+        ...blockRecords('risks', frontmatter.risks, ['id', 'description', 'mitigation']),
+        ...blockOptionalSequence('nextActions', frontmatter.nextActions),
         // LAST, after every anchored field: `schemaVersion` / `sha256` are
         // matched as `^`-anchored lines by the gate and both audit loaders, so
         // nothing new may be inserted before them. A nested map also renders

package/dist/services/prd/handoff-gate-evidence.d.ts

@@ -56,7 +56,6 @@ export type HandoffGateEvidenceResult = {
 /**
  * THE shape rule for a `gateEvidence` value — one home, two callers.
  *
- * F2 of `rid-b1-qa` found this rule written twice (`handoff-service.ts`'s
  * `isGateEvidenceMap`, added by B1, and this module's own inline checks) with
  * the SAME accept/reject boundary but DIFFERENT results: the same bytes
  * produced a map WITH unknown keys through `readHandoff` and a map WITHOUT

package/dist/services/prd/handoff-gate-evidence.js

@@ -2,25 +2,15 @@
 //
 // The SOLE reader of the handoff frontmatter's `gateEvidence` field.
 //
-// WHAT THE FIELD IS (slice B1, rid `rid-b1-gate-evidence-producer`): a map
 // from one of five fixed gate keys to the PATH of that gate's evidence file.
 // The normative description is
 // `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:35-41`; the
 // key set is `GATE_EVIDENCE_KEYS` in `./handoff-types.js`.
 //
-// WHAT THIS FILE USED TO SAY, AND WHY THAT WAS FALSE: its header claimed the
-// field was a `string[]` of "gate names" and that `initHandoff` wrote it.
-// Neither held. `grep -rn gateEvidence src/` hit this file and nothing else —
-// there was no producer (`HandoffFrontmatter` had no such field,
-// `serializeHandoffFrontmatter` never emitted it, `initHandoff` rejected it)
-// and no consumer. The field was prose describing data that did not exist,
-// and the comment asserting a producer was the reason nobody noticed.
-//
 // WHAT IS ON DISK NOW, stated precisely because a header that overclaims is
-// the defect above. B1 added the producer FUNCTIONS; B2 wired their callers,
+// the defect below. B1 added the producer FUNCTIONS; B2 wired their callers,
 // which is what made the difference — until then every producer passed
 // nothing, so no capsule carried the field and saying otherwise would have
-// described a fact that held only inside tests (F1 of `rid-b1-qa`). At
 // HEAD after B2: the three producers DERIVE the map from the request type
 // (`services/prd/gate-evidence-derivation.ts`), so a capsule written by
 // `peaks prd handoff init`, by the auto-regen on `prd:handed-off`, or by
@@ -28,7 +18,17 @@
 // artifact is readable — and carries no `gateEvidence` block at all when it
 // is not. Gate C (`checkPrerequisites` at `rd:qa-handoff`) fails a declared
 // path that is not on disk. Every clause above is asserted end-to-end in
-// `tests/unit/prd/gate-evidence-derivation.test.ts`.
+// `tests/unit/prd/gate-evidence-derivation.test.ts`. The derived map is also
+// printed by `peaks prd handoff init` (dry-run and applied), so the key set
+// does not have to be read out of this source file.
+//
+// field was a `string[]` of "gate names" and that `initHandoff` wrote it.
+// Neither held. `grep -rn gateEvidence src/` hit this file and nothing else —
+// there was no producer (`HandoffFrontmatter` had no such field,
+// `serializeHandoffFrontmatter` never emitted it, `initHandoff` rejected it)
+// and the comment asserting a producer was the reason nobody noticed. That
+// paragraph describes the PRE-B1 state; reading it as the current state is
+// the exact misreading that put it here.
 //
 // WHY IT IS STILL STAND-ALONE: keeping the typed-value logic here, rather
 // than in `handoff-service.ts`, keeps `HandoffFrontmatter` a pure data shape

package/dist/services/prd/handoff-path-resolution.d.ts

@@ -1,7 +1,6 @@
 /**
  * The canonical capsule path for ONE SLICE, relative to the project root.
  *
- * Slice `2026-09-14-prd-capsule-rid-scoping`: the capsule used to be one slot
  * per SESSION (`prd/handoff.md`), so the second slice's handoff silently
  * overwrote the first slice's — and `AUDIT_REQUIRES_HANDOFF` stayed green
  * because it never checked WHOSE rid the file named. Measured on
@@ -9,24 +8,18 @@
  * capsule left by a different line of work.
  *
  * This is the WRITE target, so it always carries the rid — a consumer-side
- * fallback here would leave a rid-scoped requirement with a bare-name writer,
  * which is the defect shape this slice exists to remove. Readers that must
- * tolerate pre-rid-scoping sessions call `resolveHandoffPath` instead.
  */
 export declare function handoffRelativePath(sessionId: string, requestId: string): string;
 /**
- * The capsule a CONSUMER should read for (session, requestId): the rid-scoped
- * path when it is on disk, else the pre-rid-scoping bare name. Returns null
  * when neither exists.
  *
  * Three sessions on disk still hold only the bare file
- * (`2026-09-06-session-a87ca4`, `2026-09-12-session-e37ef0`,
  * `2026-09-13-session-21878f`), so the legacy tier has to keep resolving for
  * the gate and for every reader below.
  *
  * `requestId` is optional because the detect-only audit surface reaches its
  * service without one. Such a caller can name only the bare path: a session
- * holding nothing but rid-scoped capsules reports missing rather than picking
  * among its siblings' capsules, which would re-open the cross-slice mix-up
  * this scoping exists to close (fail closed, not "some capsule is there").
  */