peaks-loop 4.0.52 → 4.0.54

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

@@ -35,7 +35,7 @@
  * parses the block through YAML and requires a STRING, and a bare all-digit
  * sha256 would parse as a YAML number and be refused by the shape check.
  */
-import type { HandoffFrontmatter } from './handoff-types.js';
+import { type HandoffFrontmatter } from './handoff-types.js';
 /**
  * Serialize `frontmatter` into the fenced block, terminated by the closing
  * `---` and a trailing newline. Callers append the body verbatim, which keeps

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

@@ -35,6 +35,7 @@
  * parses the block through YAML and requires a STRING, and a bare all-digit
  * sha256 would parse as a YAML number and be refused by the shape check.
  */
+import { GATE_EVIDENCE_KEYS, isGateEvidenceKey } from './handoff-types.js';
 /** Render a string as a YAML double-quoted scalar. JSON string escapes are a
  *  subset of YAML 1.2's double-quoted escapes, so this is valid YAML and
  *  handles `\` (Windows paths), quotes, colons and newlines in one step. */
@@ -47,6 +48,61 @@ function blockSequence(key, values) {
         return [`${key}: []`];
     return [`${key}:`, ...values.map((value) => `  - ${yamlScalar(value)}`)];
 }
+/**
+ * Render `gateEvidence` as a YAML map of quoted path scalars, or as NOTHING.
+ *
+ * Two shape decisions, both load-bearing:
+ *
+ *   - **Omitted when absent or empty.** An absent map and an empty map both
+ *     render zero lines, so a handoff that declares no evidence is
+ *     byte-identical to a pre-B1 capsule. `gateEvidence: {}` would add a line
+ *     to every handoff in the repo to say nothing — and the `each key exactly
+ *     once` assertions in `handoff-auto-regen.test.ts` /
+ *     `handoff-writer-gate-convergence.test.ts` pin the emitted key SET.
+ *   - **Canonical key order** (`GATE_EVIDENCE_KEYS`), NOT insertion order of
+ *     the caller's object. The frontmatter is sha256-adjacent and read by
+ *     substring/regex consumers; a caller that built its map `{perfBaseline,
+ *     projectScan}` must not produce different bytes from one that built it
+ *     the other way round.
+ *
+ * Values go through `yamlScalar` because these are PATHS: on Windows they
+ * contain backslashes, which a plain YAML scalar would escape.
+ */
+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.
+    // The type system blocks literal typos, but not a value that arrived through
+    // `JSON.parse`, an `as` assertion, or a JS caller — and the derivation added
+    // in B2 is exactly such an adapter. So the check is runtime, and it is HERE
+    // because this serializer is the single funnel every producer passes
+    // through: one check covers all three writers and any future one.
+    const provided = Object.entries(evidence);
+    const unknownKeys = provided
+        .map(([key]) => key)
+        .filter((key) => !isGateEvidenceKey(key))
+        .sort();
+    if (unknownKeys.length > 0) {
+        throw new Error(`handoff: unknown gateEvidence key(s) [${unknownKeys.join(', ')}]; expected one of ` +
+            `${GATE_EVIDENCE_KEYS.join(', ')} — refusing to write a declaration that would be ` +
+            'dropped silently');
+    }
+    const nonStringKeys = provided
+        .filter(([, value]) => typeof value !== 'string')
+        .map(([key]) => key)
+        .sort();
+    if (nonStringKeys.length > 0) {
+        throw new Error(`handoff: gateEvidence value(s) for [${nonStringKeys.join(', ')}] must be strings (evidence paths)`);
+    }
+    const entries = GATE_EVIDENCE_KEYS.flatMap((key) => {
+        const value = evidence[key];
+        return value === undefined ? [] : [`  ${key}: ${yamlScalar(value)}`];
+    });
+    return entries.length === 0 ? [] : ['gateEvidence:', ...entries];
+}
 /**
  * Serialize `frontmatter` into the fenced block, terminated by the closing
  * `---` and a trailing newline. Callers append the body verbatim, which keeps
@@ -69,6 +125,12 @@ export function serializeHandoffFrontmatter(frontmatter) {
         ...blockSequence('acceptanceCriteria', frontmatter.acceptanceCriteria),
         ...blockSequence('preservedBehavior', frontmatter.preservedBehavior),
         `handoffPath: ${yamlScalar(frontmatter.handoffPath)}`,
+        // 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
+        // indented lines only, leaving the top-level key set exactly as it was
+        // for every capsule that declares no evidence.
+        ...gateEvidenceBlock(frontmatter.gateEvidence),
         '---',
     ];
     return `${lines.join('\n')}\n`;

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

@@ -0,0 +1,95 @@
+import { type GateEvidence } from './handoff-types.js';
+/**
+ * Why a `gateEvidence` read produced what it produced.
+ *
+ * `ok` is the only success. `field-absent` is NOT a failure — a capsule with
+ * no declaration is a valid capsule (every pre-B1 handoff) — while
+ * `field-not-map` and `value-not-string` are declarations that exist and are
+ * broken, and `file-missing` / `read-error` / `frontmatter-malformed` mean
+ * nothing could be read at all. Collapsing any two of these is the defect
+ * this reader was rewritten to remove.
+ */
+export type HandoffGateEvidenceStatus = 'ok' | 'file-missing' | 'read-error' | 'frontmatter-malformed' | 'field-absent' | 'field-not-map' | 'value-not-string';
+/**
+ * Discriminated result. `status` alone decides the branch, so a caller that
+ * only wants "is there a usable declaration?" checks `result.status === 'ok'`
+ * and reads `result.evidence` — and a caller that must refuse corrupt
+ * declarations gets `keys` / `actualType` / `reason` to name the problem in
+ * its failure message.
+ */
+export type HandoffGateEvidenceResult = {
+    readonly status: 'ok';
+    /** Only the five known keys. Absent key = not declared. An EMPTY map
+     *  on disk yields an empty `evidence`, not an error: the field was
+     *  written and declares nothing, which is a different fact from
+     *  `field-absent` and is reported as such. */
+    readonly evidence: GateEvidence;
+    /** Keys present in the YAML that are not one of the five. Sorted.
+     *  Reported rather than dropped: a typo'd key is why a required gate
+     *  reads as "not declared", and this is the only place that can say so.
+     *  The serializer cannot emit these, so they are hand-authored only. */
+    readonly unknownKeys: readonly string[];
+} | {
+    readonly status: 'file-missing';
+} | {
+    readonly status: 'read-error';
+    readonly reason: string;
+} | {
+    readonly status: 'frontmatter-malformed';
+    readonly reason: string;
+} | {
+    readonly status: 'field-absent';
+}
+/** `actualType` is the YAML type found (`array`, `null`, `string`, …) —
+ *  `array` is the pre-B1 shape, present in old test fixtures only. */
+ | {
+    readonly status: 'field-not-map';
+    readonly actualType: string;
+}
+/** At least one value was not a string; `keys` names every offender. The
+ *  whole declaration is refused rather than filtered down to its good
+ *  entries — dropping a malformed value is the collapse this replaced. */
+ | {
+    readonly status: 'value-not-string';
+    readonly keys: readonly string[];
+};
+/**
+ * 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
+ * them through the reader, and `gateEvidence:` (null) threw on one path and
+ * reported a status on the other. That falsified the invariant
+ * `handoff-service.ts` stated about itself. Both paths now call this, and
+ * only the REFUSAL MECHANISM differs (a status vs a throw) — which is the
+ * pre-existing, documented policy split between the throwing `readHandoff`
+ * and the permissive reader, not a second opinion about the shape.
+ *
+ * `absent` is a first-class kind rather than an error: a capsule that
+ * declares nothing is valid, and (invariant 1 of B1) every pre-B1 handoff
+ * is one.
+ */
+export type GateEvidenceShape = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'not-map';
+    readonly actualType: string;
+} | {
+    readonly kind: 'value-not-string';
+    readonly keys: readonly string[];
+} | {
+    readonly kind: 'ok';
+    readonly evidence: GateEvidence;
+    readonly unknownKeys: readonly string[];
+};
+/** Classify a `gateEvidence` VALUE (already located — see the reader for the
+ *  fence/YAML/presence layers, which are file-level concerns, not shape). */
+export declare function classifyGateEvidence(value: unknown): GateEvidenceShape;
+/**
+ * Read + classify the `gateEvidence` map out of `filePath`. Never throws.
+ * See the header for the permissive contract and
+ * `HandoffGateEvidenceResult` for the outcomes.
+ */
+export declare function readHandoffGateEvidence(filePath: string): Promise<HandoffGateEvidenceResult>;

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

@@ -0,0 +1,145 @@
+// src/services/prd/handoff-gate-evidence.ts
+//
+// 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,
+// 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
+// `peaks evidence generate` carries this field whenever that slice's PRD
+// 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`.
+//
+// WHY IT IS STILL STAND-ALONE: keeping the typed-value logic here, rather
+// than in `handoff-service.ts`, keeps `HandoffFrontmatter` a pure data shape
+// and lets this reader stay PERMISSIVE where `readHandoff` must throw.
+//
+// PERMISSIVE, RE-ARGUED (the old rationale did not survive contact with its
+// own return type): the pre-B1 reader returned `null` for "field absent",
+// "field malformed", "YAML broken" and "file missing" alike. Its stated
+// justification — "a malformed frontmatter is the caller's signal to surface
+// the failure to the operator" — was therefore unimplementable: the caller
+// could not distinguish a handoff that DECLARED NOTHING from one whose
+// declaration was CORRUPT, so it could not tell whether to proceed or to
+// stop. The rationale was a promise the shape could not keep.
+//
+// It holds now, because the shape changed rather than the policy: this reader
+// still never throws (a broken capsule must not crash the gate pipeline, and
+// `readHandoff` already owns the throwing contract for capsules that must be
+// valid), but every outcome is a DISTINCT `status`. Under the map shape the
+// callers that matter are Gate C and the QA role, and both must fail closed on
+// `field-not-map` / `value-not-string` while passing `field-absent` — which is
+// only expressible if those are different values. So: permissive stays, and it
+// is now a decision the return type can actually support.
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import { isGateEvidenceKey } from './handoff-types.js';
+/** Frontmatter is the `---`-fenced YAML block at the top of the file. */
+const FRONTMATTER_FENCE = /^---\r?\n([\s\S]*?)\r?\n---/;
+function isPlainMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describeType(value) {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    return typeof value;
+}
+/** Classify a `gateEvidence` VALUE (already located — see the reader for the
+ *  fence/YAML/presence layers, which are file-level concerns, not shape). */
+export function classifyGateEvidence(value) {
+    if (value === undefined)
+        return { kind: 'absent' };
+    if (!isPlainMap(value))
+        return { kind: 'not-map', actualType: describeType(value) };
+    const nonStringKeys = Object.keys(value).filter((key) => typeof value[key] !== 'string');
+    if (nonStringKeys.length > 0) {
+        return { kind: 'value-not-string', keys: nonStringKeys.sort() };
+    }
+    const evidence = {};
+    const unknownKeys = [];
+    for (const key of Object.keys(value)) {
+        if (isGateEvidenceKey(key)) {
+            evidence[key] = value[key];
+        }
+        else {
+            unknownKeys.push(key);
+        }
+    }
+    return { kind: 'ok', evidence, unknownKeys: unknownKeys.sort() };
+}
+/**
+ * Read + classify the `gateEvidence` map out of `filePath`. Never throws.
+ * See the header for the permissive contract and
+ * `HandoffGateEvidenceResult` for the outcomes.
+ */
+export async function readHandoffGateEvidence(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        // N1 of `handoff-service.verifyHandoff` is the same lesson one layer up:
+        // folding every read failure into `file-missing` sends an operator to
+        // look for a file that is right there. Only a genuine absence is
+        // `file-missing`.
+        const code = error.code;
+        if (code === 'ENOENT')
+            return { status: 'file-missing' };
+        return { status: 'read-error', reason: `${code ?? 'unknown'}` };
+    }
+    const match = FRONTMATTER_FENCE.exec(raw);
+    if (!match) {
+        return { status: 'frontmatter-malformed', reason: 'no-frontmatter-fence' };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(match[1] ?? '');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { status: 'frontmatter-malformed', reason: `yaml-parse-error: ${message}` };
+    }
+    if (!isPlainMap(parsed)) {
+        return { status: 'frontmatter-malformed', reason: 'frontmatter-not-a-map' };
+    }
+    // `in`, not `!== undefined`: `gateEvidence:` with an empty value parses to
+    // `null`, which IS a (broken) declaration and must not be reported as if
+    // the author had written nothing.
+    if (!('gateEvidence' in parsed))
+        return { status: 'field-absent' };
+    // The shape rule is shared with `handoff-service.isHandoffFrontmatter` — see
+    // `classifyGateEvidence`. This reader only decides how to REPORT it.
+    const shape = classifyGateEvidence(parsed['gateEvidence']);
+    switch (shape.kind) {
+        case 'absent':
+            return { status: 'field-absent' };
+        case 'not-map':
+            return { status: 'field-not-map', actualType: shape.actualType };
+        case 'value-not-string':
+            return { status: 'value-not-string', keys: shape.keys };
+        case 'ok':
+            return { status: 'ok', evidence: shape.evidence, unknownKeys: shape.unknownKeys };
+    }
+}

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

@@ -22,7 +22,7 @@
  * the body content as UTF-8 bytes. The body MUST be the literal
  * markdown source — no normalization, no trailing-newline padding.
  */
-import type { Handoff, HandoffProbe } from './handoff-types.js';
+import type { GateEvidence, Handoff, HandoffProbe } from './handoff-types.js';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export declare function sha256OfBody(body: string): string;
 /**
@@ -74,6 +74,26 @@ export declare function initHandoff(opts: {
     preservedBehavior: readonly string[];
     /** Override path; defaults to `.peaks/_runtime/<sid>/prd/handoff-<rid>.md`. */
     handoffPath?: string;
+    /** Paths to the gate evidence files, keyed by gate. Omitted field and
+     *  empty map are equivalent here: neither renders a `gateEvidence` block,
+     *  so a caller that declares nothing writes bytes identical to a pre-B1
+     *  capsule.
+     *
+     *  THIS IS NOT A SECOND SOURCE (B2). In production the value reaching this
+     *  parameter is always `deriveGateEvidence(...)`
+     *  (`services/prd/gate-evidence-derivation.ts`), which computes it from the
+     *  request type and the gate table. This function stays pure — it does not
+     *  read the type itself — so the map can be constructed without touching
+     *  the disk; that is why the parameter exists rather than an internal call.
+     *
+     *  SHAPE CONTRACT (F2 of `rid-b1-qa`, now enforced in both directions): a
+     *  map this accepts is EXACTLY what `readHandoffGateEvidence` reports as
+     *  `evidence` — `classifyGateEvidence` is the one shape rule behind both,
+     *  and `parseHandoffContent` stores the classified map rather than the raw
+     *  YAML. A declaration both paths REFUSE (`not-map` / `value-not-string`)
+     *  is refused here by a throw and there by a status; neither silently
+     *  produces a map the other cannot. */
+    gateEvidence?: GateEvidence;
 }): Handoff;
 /** Write a Handoff to disk. `projectRoot` is the absolute project
  *  root (so the `.peaks/_runtime/...` path is resolved absolutely).

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

@@ -30,6 +30,7 @@ import { parse as parseYaml } from 'yaml';
 import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
 import { serializeHandoffFrontmatter } from './handoff-frontmatter.js';
+import { classifyGateEvidence } from './handoff-gate-evidence.js';
 /** Required schema version for new handoffs. */
 const HANDOFF_SCHEMA_VERSION = '2';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
@@ -139,6 +140,12 @@ export function initHandoff(opts) {
         acceptanceCriteria: [...opts.acceptanceCriteria],
         preservedBehavior: [...opts.preservedBehavior],
         handoffPath,
+        // Conditionally spread rather than `gateEvidence: undefined`: this
+        // tsconfig sets `exactOptionalPropertyTypes`, and an explicit `undefined`
+        // would also make `serializeHandoffFrontmatter`'s
+        // `frontmatter.gateEvidence` key present-but-undefined for every caller
+        // that declares nothing.
+        ...(opts.gateEvidence === undefined ? {} : { gateEvidence: opts.gateEvidence }),
     };
     return { frontmatter, body: opts.body };
 }
@@ -233,8 +240,21 @@ function parseHandoffContent(content) {
     // frontmatter is returned with the canonical `'2'` rather than the raw scalar
     // — otherwise every downstream `=== '2'` comparison would depend on which
     // producer wrote the file.
+    //
+    // F2: `gateEvidence` is normalized the same way, for the same reason. The
+    // raw YAML value is not returned: the CLASSIFIED map is. Unknown keys are
+    // not part of `GateEvidence`, so storing the raw object made the interface
+    // claim a five-key map while holding a six-key one — and made
+    // `frontmatter.gateEvidence` disagree with what the field's reader reports
+    // for the same bytes. The predicate above has already rejected every shape
+    // that is not `absent` or `ok`, so this spread only ever adds a clean map.
+    const gateEvidenceShape = classifyGateEvidence(parsed.gateEvidence);
     return {
-        frontmatter: { ...parsed, schemaVersion: HANDOFF_SCHEMA_VERSION },
+        frontmatter: {
+            ...parsed,
+            schemaVersion: HANDOFF_SCHEMA_VERSION,
+            ...(gateEvidenceShape.kind === 'ok' ? { gateEvidence: gateEvidenceShape.evidence } : {})
+        },
         body
     };
 }
@@ -296,5 +316,28 @@ function isHandoffFrontmatter(value) {
         Array.isArray(v.goals) &&
         Array.isArray(v.acceptanceCriteria) &&
         Array.isArray(v.preservedBehavior) &&
-        typeof v.handoffPath === 'string');
+        typeof v.handoffPath === 'string' &&
+        isGateEvidence(v.gateEvidence));
+}
+/**
+ * B1: `gateEvidence` is optional, but when present it MUST be a map of
+ * 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
+ * `absent` and `ok` are accepted: a malformed declaration must be refused by
+ * `readHandoff` (which is documented to throw on malformed input) exactly as
+ * the reader refuses it, so the two can never disagree about the same file.
+ *
+ * Unknown keys are still accepted HERE — the map is normalized to the five
+ * known keys by the caller — because refusing them would make a typo render
+ * a whole capsule unreadable, and the reader's `unknownKeys` is the surface
+ * that makes the typo diagnosable instead.
+ */
+function isGateEvidence(value) {
+    const kind = classifyGateEvidence(value).kind;
+    return kind === 'absent' || kind === 'ok';
 }

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

@@ -24,6 +24,39 @@
  *  IDs in frontmatter). Every consumer MUST refuse a handoff whose
  *  frontmatter is missing or carries `schemaVersion !== '2'`. */
 export type HandoffSchemaVersion = '2';
+/**
+ * The FIVE fixed `gateEvidence` keys, in canonical serialization order.
+ *
+ * This array is the single source of truth for the key set: the
+ * `GateEvidenceKey` type is derived from it, the serializer iterates it,
+ * and the reader matches against it. Slice B1
+ * (`2026-09-17-4-0-51-cleanup`) collapsed four mutually contradictory
+ * descriptions of this field (a `string[]` in the reader's code comment,
+ * a `string[]` of PATHS in its tests, a map of paths in
+ * `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:35-41`)
+ * onto the documented map. Do NOT re-spell these five literals anywhere
+ * else — a second copy is how the four descriptions diverged.
+ */
+export declare const GATE_EVIDENCE_KEYS: readonly ["projectScan", "prdHandoff", "codeReview", "securityReview", "perfBaseline"];
+/** One of the five `gateEvidence` keys. Derived, never re-spelled. */
+export type GateEvidenceKey = (typeof GATE_EVIDENCE_KEYS)[number];
+/**
+ * Is `key` one of the five? THE membership test — the serializer's
+ * unknown-key check, the reader's classifier and the shape predicate all ask
+ * this one function, so no caller can disagree about what the key set is.
+ */
+export declare function isGateEvidenceKey(key: string): key is GateEvidenceKey;
+/**
+ * `gateEvidence` — a partial map from gate key to the PATH of that gate's
+ * evidence file. Partial because a slice may legitimately not have run
+ * every gate; the consumer (Gate C, wired in slice B2) fails on a missing
+ * key, which is where "did you declare it?" is decided — NOT here.
+ *
+ * Unknown keys are not expressible in this type. The reader still reports
+ * them at runtime (`unknownKeys`) so a typo is diagnosable rather than
+ * silently dropped.
+ */
+export type GateEvidence = Readonly<Partial<Record<GateEvidenceKey, string>>>;
 /**
  * Handoff frontmatter — the structured header block between the
  * leading and trailing `---` fences. `readonly` enforces D1's
@@ -47,6 +80,13 @@ export interface HandoffFrontmatter {
     readonly preservedBehavior: readonly string[];
     /** Absolute path to the handoff file on disk (for re-verify). */
     readonly handoffPath: string;
+    /** Paths to the evidence files peaks-qa validates at Gate C, keyed by
+     *  gate. ABSENT (not `{}`) when the slice declared none — the serializer
+     *  omits the block entirely rather than emitting an empty map, so old
+     *  handoffs gain no noise line. Read it through
+     *  `readHandoffGateEvidence`, which reports WHY it is unusable instead of
+     *  collapsing every failure to `null`. */
+    readonly gateEvidence?: GateEvidence;
 }
 /** Handoff — frontmatter + body. The body is the markdown source of
  *  truth that sub-agents and downstream consumers parse. */

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

@@ -20,4 +20,31 @@
  * `.peaks/_runtime/current-change`). NEVER write under
  * `.peaks/_runtime/<change-id>/...` directly (slice 2.8.3 hard ban).
  */
-export {};
+/**
+ * The FIVE fixed `gateEvidence` keys, in canonical serialization order.
+ *
+ * This array is the single source of truth for the key set: the
+ * `GateEvidenceKey` type is derived from it, the serializer iterates it,
+ * and the reader matches against it. Slice B1
+ * (`2026-09-17-4-0-51-cleanup`) collapsed four mutually contradictory
+ * descriptions of this field (a `string[]` in the reader's code comment,
+ * a `string[]` of PATHS in its tests, a map of paths in
+ * `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:35-41`)
+ * onto the documented map. Do NOT re-spell these five literals anywhere
+ * else — a second copy is how the four descriptions diverged.
+ */
+export const GATE_EVIDENCE_KEYS = [
+    'projectScan',
+    'prdHandoff',
+    'codeReview',
+    'securityReview',
+    'perfBaseline'
+];
+/**
+ * Is `key` one of the five? THE membership test — the serializer's
+ * unknown-key check, the reader's classifier and the shape predicate all ask
+ * this one function, so no caller can disagree about what the key set is.
+ */
+export function isGateEvidenceKey(key) {
+    return GATE_EVIDENCE_KEYS.includes(key);
+}

package/dist/services/prd/project-scan-reader.d.ts

@@ -10,6 +10,13 @@
  * errors propagate (no silent failures).
  */
 import type { BusinessKnowledge, ProjectScan } from './project-scan-types.js';
+/**
+ * `.peaks/project-scan/project-scan.md`, project-relative. Exported so the
+ * gate-evidence derivation (`gate-evidence-derivation.ts`) can declare this
+ * path without spelling the literal a fourth time — it was already inlined in
+ * `project-commands.ts`, `workspace/init-command.ts` and here.
+ */
+export declare const PROJECT_SCAN_RELATIVE: string;
 /** Read `.peaks/project-scan/project-scan.md`. Returns `null` when the
  *  file or its parent dir is absent (fresh project). Throws on other
  *  IO failures or malformed YAML. */

package/dist/services/prd/project-scan-reader.js

@@ -12,7 +12,13 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
-const PROJECT_SCAN_RELATIVE = join('.peaks', 'project-scan', 'project-scan.md');
+/**
+ * `.peaks/project-scan/project-scan.md`, project-relative. Exported so the
+ * gate-evidence derivation (`gate-evidence-derivation.ts`) can declare this
+ * path without spelling the literal a fourth time — it was already inlined in
+ * `project-commands.ts`, `workspace/init-command.ts` and here.
+ */
+export const PROJECT_SCAN_RELATIVE = join('.peaks', 'project-scan', 'project-scan.md');
 const BUSINESS_KNOWLEDGE_RELATIVE = join('.peaks', 'project-scan', 'business-knowledge.md');
 /** Read `.peaks/project-scan/project-scan.md`. Returns `null` when the
  *  file or its parent dir is absent (fresh project). Throws on other

package/dist/services/rd/reviewer-dispatch-policy.d.ts

@@ -26,12 +26,33 @@
  * PRD handoff + the project-scoped audit templates (slice v2.12.0
  * Tier 1+2+3 = Group A).
  *
- * The dispatch policy here is the **canonical decision table** consumed
- * by the LLM-side runner and pinned by tests:
- *   - `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts`
- *     (5 → 3 element pinning)
- *   - `tests/unit/rd/deprecated-reviewer-back-compat.test.ts`
- *     (NEW in v2.12.0 — 8 cases; back-compat for the 2 removed slots)
+ * This module holds the machine-readable decision table for that collapse;
+ * the prose the LLM runner actually reads is
+ * `skills/bee/peaks-rd/references/parallel-review-fanout.md`. It used to
+ * describe itself as "consumed by the LLM-side runner", which named no
+ * mechanism — an LLM reads prose, not TypeScript exports — and that is the
+ * reason every export below sat at zero importers until slice F2.
+ *
+ * Pinning is half-done. The two test files this block used to cite —
+ * `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts` (the 5 → 3
+ * element pinning) and
+ * `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (the 8
+ * back-compat cases) — were both deleted in `f17aa377`. The **predicate
+ * half** was re-pinned by `tests/unit/rd/reviewer-dispatch-policy.test.ts`
+ * (`7191140f`, 6 cases: `RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`).
+ * The **decision-table half** — `RD_FANOUT_REVIEWERS`' 3-element
+ * membership, `reviewerListFor`, `karpathySlotIndex`,
+ * `shouldDispatchKarpathy` — still has no pin.
+ *
+ * Slice F2 (rid-f2-ac1-wiring) gave this module its FIRST caller in
+ * `src/cli/commands/sub-agent-shared.ts` (`deprecatedReviewerWarnings`),
+ * invoked from the dispatch chokepoint in
+ * `src/cli/commands/dispatch-commands.ts` and pinned by
+ * `tests/unit/cli/sub-agent-dispatch-deprecated-reviewer.test.ts`. Before
+ * that, all 13 exports had zero importers across src/ + packages/ +
+ * scripts/, so nothing rejected or rerouted `security-reviewer` /
+ * `perf-baseline-reviewer` on the way in. That import is still the only
+ * one: the other 12 exports below remain unreferenced in this repo.
  *
  * For `config | docs | chore` request types, the slice already skips
  * the entire fanout (SKILL.md line 132 says "Config / docs / chore: no
@@ -47,8 +68,15 @@
  * back-compat window. The `isDeprecatedReviewer(name)` predicate lets
  * dispatchers (or legacy on-disk rd/{security-review,perf-baseline}.md
  * readers) detect a removed slot and route to the new audit skill
- * instead of failing the gate. See Tier 5 (`artifact-prerequisites.ts`)
- * for the matching prereq-side back-compat (`mustContainAny` form).
+ * instead of failing the gate. Tier 5 (`artifact-prerequisites.ts`)
+ * holds the matching prereq-side back-compat: `AUDIT_SECURITY` /
+ * `AUDIT_PERF` accept the legacy `rd/security-review.md` /
+ * `rd/perf-baseline.md` artifacts via `legacyRelativePaths`.
+ *
+ * Both halves are wired as of slice F2 and both ACCEPT the legacy slot.
+ * The dispatch side emits the reroute notice as a warning
+ * (`deprecatedReviewerWarnings`) rather than a refusal, precisely so it
+ * does not disagree with the prereq side about the same deprecation.
  */
 export declare const RD_REVIEW_REQUEST_TYPES: readonly ["feat", "bugfix", "refactor", "config", "docs", "chore"];
 export type RdReviewRequestType = (typeof RD_REVIEW_REQUEST_TYPES)[number];