peaks-loop 4.0.53 → 4.0.54

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

@@ -1,77 +1,145 @@
 // src/services/prd/handoff-gate-evidence.ts
 //
-// AC-5 of slice 2026-09-17-4-0-51-cleanup: the handoff's frontmatter
-// carries a `gateEvidence: string[]` field naming the gate names whose
-// `gateEvidence` is asserted by this handoff. Pre-S2, the field was
-// written into the frontmatter (by `initHandoff`) but NO consumer in
-// `src/` ever READ it back — the field was prose, not data.
+// The SOLE reader of the handoff frontmatter's `gateEvidence` field.
 //
-// This module is the SOLE reader for that field. It is a stand-alone
-// reader (not a member of `handoff-service.ts`) so that the
-// `HandoffFrontmatter` type stays a pure-data shape and this consumer
-// can be added independently without disturbing every existing
-// parse-and-validate path.
+// 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`.
 //
-// Returns:
-//   - `string[]`  — the gate names declared in the frontmatter
-//   - `null`      — the file is missing, the frontmatter is malformed,
-//                   the field is absent, or the field is not an array
-//                   of strings. Callers MUST treat null as "no claim"
-//                   and not as a failure.
+// 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.
 //
-// The reader is intentionally permissive (returns null instead of
-// throwing) because a malformed frontmatter is the caller's signal to
-// surface the failure to the operator, not the reader's signal to
-// throw inside the gate pipeline.
-import { existsSync } from 'node:fs';
+// 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';
-function parseGateEvidenceFrontmatter(raw) {
-    // Frontmatter is the `---`-fenced YAML block at the top of the file.
-    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (!match)
-        return { gateEvidence: null };
-    const yamlBody = match[1] ?? '';
-    let parsed;
-    try {
-        parsed = parseYaml(yamlBody);
+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() };
     }
-    catch (_error) {
-        // reader is permissive by design: malformed YAML → no claim (not throw)
-        void _error;
-        return { gateEvidence: null };
+    const evidence = {};
+    const unknownKeys = [];
+    for (const key of Object.keys(value)) {
+        if (isGateEvidenceKey(key)) {
+            evidence[key] = value[key];
+        }
+        else {
+            unknownKeys.push(key);
+        }
     }
-    if (parsed === null || typeof parsed !== 'object')
-        return { gateEvidence: null };
-    const gateEvidence = parsed['gateEvidence'];
-    if (!Array.isArray(gateEvidence))
-        return { gateEvidence: null };
-    return { gateEvidence };
+    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) {
-    if (!existsSync(filePath))
-        return null;
     let raw;
     try {
         raw = await readFile(filePath, 'utf8');
     }
-    catch (_error) {
-        // reader is permissive by design: missing file → no claim (not throw)
-        void _error;
-        return null;
+    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 {
-        const { gateEvidence } = parseGateEvidenceFrontmatter(raw);
-        if (gateEvidence === null)
-            return null;
-        // Filter to strings only — a non-string element (number/boolean/
-        // null) is treated as "not a gate name" rather than as an error.
-        const strings = gateEvidence.filter((item) => typeof item === 'string');
-        return strings.length > 0 ? strings : null;
+        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' };
     }
-    catch (_error) {
-        // reader is permissive by design: unexpected parse failure → no claim
-        void _error;
-        return null;
+    // `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];

package/dist/services/rd/reviewer-dispatch-policy.js

@@ -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 const RD_REVIEW_REQUEST_TYPES = [
     'feat',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.53",
+  "version": "4.0.54",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -83,7 +83,7 @@
     "schemas/*.json",
     ".claude-plugin/**",
     "config/eslint/.peaks-rules.cjs",
-    "docs/test-style-contract.md",
+    "contracts/test-style-contract.md",
     "README.md",
     "README-en.md",
     "CHANGELOG.md",
@@ -102,10 +102,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-shared": "0.0.87",
-    "peaks-loop-internal-runtime": "0.0.38",
-    "peaks-loop-mut": "0.1.51",
-    "peaks-loop-shared-channel": "0.0.55"
+    "peaks-loop-internal-runtime": "0.0.39",
+    "peaks-loop-shared": "0.0.88",
+    "peaks-loop-shared-channel": "0.0.56",
+    "peaks-loop-mut": "0.1.52"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-rd/SKILL.md

@@ -65,7 +65,7 @@ Every RD action MUST align with the 4 Karpathy guidelines (full text at `andrej-
 3. **Surgical Changes** — touch only what the user's request requires. Remove imports / variables / functions that *your* changes made unused. Do not refactor adjacent code. Every changed line must trace to the user's request.
 4. **Goal-Driven Execution** — define verifiable success criteria (`peaks request show --role rd` carries ACs from PRD). For multi-step work, state plan + verify checkpoints before acting.
 
-Cross-references: Slice 1 PRD §AC-1. The 4-point assertion guard that PRD named was deleted in `f17aa377`; the block below is held by documentation only. The canonical skill id is `andrej-karpathy-skills:karpathy-guidelines`.
+Cross-references: Slice 1 PRD §AC-1. The 4-point assertion guard that PRD named was deleted in `f17aa377`; it is re-pinned by `tests/unit/skills/karpathy-injection.test.ts`, which fails if any of the 4 titles above is dropped. The canonical skill id is `andrej-karpathy-skills:karpathy-guidelines`.
 
 ## Scope directory (slice 10 — read scopeDir from envelope)