peaks-loop 4.0.53 → 4.1.0

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

@@ -0,0 +1,67 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the handoff
+ * frontmatter's FIELD-level primitives from `./handoff-service.ts`: the required
+ * schema version, the one canonical frontmatter rendering, and the two
+ * per-field acceptance rules (`schemaVersion`, `gateEvidence`). The composite
+ * predicate that calls them, `isHandoffFrontmatter`, stays in
+ * `handoff-service.ts` — it carries an existing `complexity` finding, and a new
+ * module must start clean, so only what it calls moved.
+ *
+ * Bodies, doc comments and thrown strings are unchanged; `handoff-service.ts`
+ * imports these and keeps exporting its own public surface, so no importer
+ * changed.
+ */
+import { serializeHandoffFrontmatter } from './handoff-frontmatter.js';
+import { classifyGateEvidence } from './handoff-gate-evidence.js';
+/** Required schema version for new handoffs. */
+export const HANDOFF_SCHEMA_VERSION = '2';
+export function serializeHandoff(handoff) {
+    // The one canonical frontmatter rendering, shared with
+    // `handoff-auto-regen.ts`. `yaml.stringify` used to render this block and
+    // emitted `schemaVersion: "2"` + a bare `handoffHash:`, which the
+    // `AUDIT_REQUIRES_HANDOFF` gate and both audit loaders all reject.
+    return `${serializeHandoffFrontmatter(handoff.frontmatter)}${handoff.body}`;
+}
+/**
+ * N1: accept BOTH shapes of `schemaVersion` — the string `'2'` and the bare
+ * YAML number `2` — and reject any other value.
+ *
+ * The reader used to require `typeof v.schemaVersion === 'string'`. That made
+ * `readHandoff` refuse `prd/handoff.md` written by `handoff-auto-regen.ts`,
+ * which emits the unquoted `schemaVersion: 2`, while the
+ * `AUDIT_REQUIRES_HANDOFF` prereq — a SUBSTRING check for `schemaVersion: 2` —
+ * happily passed the same bytes. So the gate that exists to guarantee a
+ * 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
+ * retroactively make them unreadable.
+ */
+export function isSchemaVersion2(value) {
+    return value === HANDOFF_SCHEMA_VERSION || value === 2;
+}
+/**
+ * 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.
+ */
+export function isGateEvidence(value) {
+    const kind = classifyGateEvidence(value).kind;
+    return kind === 'absent' || kind === 'ok';
+}

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,7 +125,13 @@ 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

@@ -1 +1,95 @@
-export declare function readHandoffGateEvidence(filePath: string): Promise<readonly string[] | null>;
+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

@@ -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-path-resolution.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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
+ * `2026-09-13-session-21878f`: a four-slice job passed that prerequisite on a
+ * 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").
+ */
+export declare function resolveHandoffPath(opts: {
+    projectRoot: string;
+    sessionId: string;
+    requestId?: string;
+}): string | null;

package/dist/services/prd/handoff-path-resolution.js

@@ -0,0 +1,101 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the handoff
+ * capsule PATH layer from `./handoff-service.ts` (the id guard, the rid-scoped
+ * write path and the consumer-side resolver) so that module clears the 300
+ * raw-line cap. No guard, no message string and no join changed;
+ * `handoff-service.ts` re-exports both public names from its own path, so no
+ * importer changed. The id->path escape this module guards is measured by
+ * `tests/unit/runtime/no-runtime-input-guard.test.ts` rule D, whose scanned
+ * module list now names this file next to `handoff-service.ts`.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+/**
+ * Both ids in a handoff path are caller-supplied path segments, so both are
+ * checked at the join. Added 2026-09-14 (repair R1, security audit F2 of
+ * `2026-09-14-cli-id-escape-instrumentation`).
+ *
+ * This function was introduced by `0536d5bd` — the commit that instrumented
+ * this defect class — with neither id checked, and it sat outside rule D's
+ * scanned layer, so the instrument could not see its own new member.
+ * Measured on the pre-fix tree (`prd handoff init --apply`, temp project,
+ * `ok: true` both times):
+ *
+ *   --rid '../../../../../../README'  replaced the project-root README.md
+ *   --sid '../../../../SIDOUT'        wrote 4 levels above the project root
+ *
+ * The two axes need two different controls, for a recorded reason: the rid has
+ * a pinned format (`REQUEST_ID_PATTERN`, no separator, no dot-dot, no drive)
+ * and the sid has none, so it gets the segment check. `isUnsafePathInput`
+ * alone is NOT enough for the rid — it admits `a/b` (two non-empty segments),
+ * which `request-artifact-service.ts` would reject.
+ *
+ * Guarding HERE rather than at the three `prd`/`env` flags means every producer
+ * that writes through this constructor — `initHandoff`'s default,
+ * `handoff-auto-regen.ts`, `evidence-generator.ts` — is covered by the join
+ * itself, not by each caller re-deciding.
+ */
+function assertSafeHandoffIds(sessionId, requestId) {
+    if (!REQUEST_ID_PATTERN.test(requestId)) {
+        throw new Error(`Invalid request id: ${requestId} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
+}
+/**
+ * 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
+ * `2026-09-13-session-21878f`: a four-slice job passed that prerequisite on a
+ * 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 function handoffRelativePath(sessionId, requestId) {
+    assertSafeHandoffIds(sessionId, requestId);
+    return join('.peaks', '_runtime', sessionId, 'prd', `handoff-${requestId}.md`);
+}
+/**
+ * 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").
+ */
+export function resolveHandoffPath(opts) {
+    // The legacy bare-name candidate below is a second join of the same sid, in a
+    // second function, so it needs the sid guarded in its own right — the
+    // optional-requestId branch reaches `handoffRelativePath` (guarded there), but
+    // the branch that is taken when a caller has NO rid reaches this join only.
+    if (isUnsafePathInput(opts.sessionId)) {
+        throw new Error(`Invalid session id: ${opts.sessionId} (must be a single path segment)`);
+    }
+    const candidates = [
+        ...(opts.requestId !== undefined ? [handoffRelativePath(opts.sessionId, opts.requestId)] : []),
+        join('.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md')
+    ];
+    for (const relative of candidates) {
+        const absolute = join(opts.projectRoot, relative);
+        if (existsSync(absolute))
+            return absolute;
+    }
+    return null;
+}