peaks-loop 4.0.54 → 4.1.1

package/dist/services/openspec/openspec-validate-service.js

@@ -27,10 +27,18 @@ function buildInternalIssues(changeId, detail) {
         issues.push({ level: 'warning', rule: 'why-non-empty', message: 'Why section is empty' });
     }
     if (proposal.whatChanges.length === 0) {
-        issues.push({ level: 'error', rule: 'what-changes-non-empty', message: 'What Changes section has no bullets' });
+        issues.push({
+            level: 'error',
+            rule: 'what-changes-non-empty',
+            message: 'What Changes section has no bullets'
+        });
     }
     if (proposal.acceptanceCriteria.length === 0) {
-        issues.push({ level: 'error', rule: 'acceptance-non-empty', message: 'Acceptance Criteria section has no bullets' });
+        issues.push({
+            level: 'error',
+            rule: 'acceptance-non-empty',
+            message: 'Acceptance Criteria section has no bullets'
+        });
     }
     return issues;
 }
@@ -57,11 +65,20 @@ export async function validateOpenSpecChange(changeId, options = {}) {
     if (options.preferExternal === true) {
         const outcome = await runner('openspec', ['validate', changeId]);
         if (outcome.available) {
-            const cliOutput = [outcome.stdout, outcome.stderr].filter((part) => part.length > 0).join('\n').trim();
+            const cliOutput = [outcome.stdout, outcome.stderr]
+                .filter((part) => part.length > 0)
+                .join('\n')
+                .trim();
             const passed = outcome.exitCode === 0;
             const issues = passed
                 ? []
-                : [{ level: 'error', rule: 'openspec-cli-failed', message: `openspec validate exited with code ${outcome.exitCode ?? 'null'}` }];
+                : [
+                    {
+                        level: 'error',
+                        rule: 'openspec-cli-failed',
+                        message: `openspec validate exited with code ${outcome.exitCode ?? 'null'}`
+                    }
+                ];
             return { changeId, valid: passed, source: 'openspec-cli', issues, cliOutput };
         }
         const internal = await runInternal(changeId, openspecRoot);
@@ -69,7 +86,11 @@ export async function validateOpenSpecChange(changeId, options = {}) {
             return null;
         }
         internal.issues = [
-            { level: 'warning', rule: 'openspec-cli-unavailable', message: 'openspec CLI not found, fell back to internal lint' },
+            {
+                level: 'warning',
+                rule: 'openspec-cli-unavailable',
+                message: 'openspec CLI not found, fell back to internal lint'
+            },
             ...internal.issues
         ];
         return internal;

package/dist/services/perf/perf-baseline-service.js

@@ -117,12 +117,8 @@ function renderBaselineTemplate() {
 }
 function buildPlan(projectRoot, apply) {
     const sessionId = getSessionId(projectRoot);
-    const sessionRoot = sessionId !== null
-        ? getSessionDir(projectRoot, sessionId)
-        : null;
-    const perfBaselinePath = sessionRoot !== null
-        ? join(sessionRoot, 'rd', 'perf-baseline.md')
-        : null;
+    const sessionRoot = sessionId !== null ? getSessionDir(projectRoot, sessionId) : null;
+    const perfBaselinePath = sessionRoot !== null ? join(sessionRoot, 'rd', 'perf-baseline.md') : null;
     const plannedWrites = [];
     if (sessionRoot !== null && perfBaselinePath !== null) {
         plannedWrites.push({

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

@@ -118,7 +118,8 @@ export function readManifest(root) {
         const raw = readFileSync(p, 'utf8');
         return JSON.parse(raw);
     }
-    catch { // TODO(g2): fail-closed JSON parse — null is the documented contract, caller checks via existsSync
+    catch {
+        // TODO(g2): fail-closed JSON parse — null is the documented contract, caller checks via existsSync
         return null;
     }
 }

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

@@ -29,7 +29,10 @@ function childHasPeaks(dir) {
  *  leading dots or dashes. Used when the dir name itself is the id
  *  (the common case). */
 function sanitizeId(name) {
-    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
 }
 /** Walk the parent root at depth 1 and return discovered children. */
 export function scanPolyrepo(root, opts = {}) {

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

@@ -0,0 +1,42 @@
+import type { Handoff, HandoffSchemaVersion } from './handoff-types.js';
+/** Required schema version for new handoffs. */
+export declare const HANDOFF_SCHEMA_VERSION: HandoffSchemaVersion;
+export declare function serializeHandoff(handoff: Handoff): string;
+/**
+ * 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 declare function isSchemaVersion2(value: unknown): boolean;
+/**
+ * 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 declare function isGateEvidence(value: unknown): boolean;

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.js

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

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

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

@@ -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;
+}

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

@@ -22,46 +22,10 @@
  * the body content as UTF-8 bytes. The body MUST be the literal
  * markdown source — no normalization, no trailing-newline padding.
  */
-import type { GateEvidence, Handoff, HandoffProbe } from './handoff-types.js';
+import type { GateEvidence, Handoff, HandoffDecision, HandoffProbe, HandoffRisk } from './handoff-types.js';
+export { handoffRelativePath, resolveHandoffPath } from './handoff-path-resolution.js';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export declare function sha256OfBody(body: string): string;
-/**
- * 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;
 /** Pure: produce a Handoff with the frontmatter populated. Hash is
  *  computed here; callers MUST NOT pre-populate `handoffHash`. */
 export declare function initHandoff(opts: {
@@ -94,6 +58,16 @@ export declare function initHandoff(opts: {
      *  is refused here by a throw and there by a status; neither silently
      *  produces a map the other cannot. */
     gateEvidence?: GateEvidence;
+    /** The authored fields peaks-qa cross-checks (`decisions[] ↔ tests`,
+     *  `risks[] ↔ security tests`, `files[] ↔ git diff`). They are OPTIONAL and
+     *  pass through verbatim: unlike `gateEvidence`, nothing derives them — they
+     *  are a writer's judgement about the slice, so a producer that has not made
+     *  that judgement declares nothing rather than an empty claim. */
+    scope?: readonly string[];
+    files?: readonly string[];
+    decisions?: readonly HandoffDecision[];
+    risks?: readonly HandoffRisk[];
+    nextActions?: readonly string[];
 }): Handoff;
 /** Write a Handoff to disk. `projectRoot` is the absolute project
  *  root (so the `.peaks/_runtime/...` path is resolved absolutely).