peaks-loop 4.0.47 → 4.0.48

package/dist/cli/commands/verdict-aggregate-command.js

@@ -4,11 +4,51 @@ import { aggregateVerdict } from '../../services/verdict/verdict-aggregator.js';
 import { parseKarpathyEnvelope, parseMutEnvelope, parseQaEnvelope, parseSecurityEnvelope, parsePerfEnvelope, envelopesToAggregatorInput } from '../../services/verdict/envelopes.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
-const SECURITY_REL = 'audit/security.md';
-const PERF_REL = 'audit/perf.md';
-const KARPATHY_REL = 'rd/karpathy-review.md';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { DEFAULT_REQUEST_TYPE } from '../../services/artifacts/artifact-prerequisites.js';
+import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
+import { contractEvidencePaths } from '../../services/workflow/pipeline-verify-gate-support.js';
+// Slice `2026-09-14-audit-artifact-rid-scoping`: the audit/review evidence
+// filenames carry the rid. The ridless names are the pre-rid locations and
+// stay readable during the back-compat window. `mut/` is NOT rid-scoped —
+// see `MUT_REPORT` in `artifact-prerequisites.ts`: no producer in the repo
+// can write a rid-scoped mut report, so probing a templated name here would
+// look for a file that no writer can create.
+//
+// The candidate lists are read FROM the contract — the same
+// `contractEvidencePaths()` the verify pipeline resolves with — rather than
+// hand-written here. Hand-written lists held two of the contract's THREE
+// tiers, so a session whose security/perf evidence sits at the oldest tier
+// (`rd/security-review.md`, `rd/perf-baseline.md` — the live shape of three
+// sessions on disk) reported `block` while `peaks request transition`
+// accepted the same tree, and the hint named a legacy location it had never
+// probed. One table, one answer.
 const MUT_REL = 'mut/mut-report.json';
 const QA_REL = 'qa/test-reports';
+/**
+ * The declared tiers for one artifact name, primary first. Probed by the name
+ * this command used before the rid-scoping (the table matches it as either
+ * the primary or a legacy tier), so the lookup survives the primary moving.
+ * `verdict aggregate` is request-type-agnostic and every fanout-trigger type
+ * declares these artifacts identically, so the default type's list is the
+ * full one; a name the table does not carry falls back to itself.
+ */
+function contractRels(probeName) {
+    return contractEvidencePaths('rd', 'qa-handoff', DEFAULT_REQUEST_TYPE, probeName) ?? [probeName];
+}
+const SECURITY_RELS = contractRels('audit/security.md');
+const PERF_RELS = contractRels('audit/perf.md');
+const KARPATHY_RELS = contractRels('rd/karpathy-review.md');
+/**
+ * Sources whose absence must not read as `pass`. `mut` is excluded on
+ * purpose: `MUT_REPORT` carries `backCompat: true`, so the contract itself
+ * treats a missing mut report as a warning rather than a gate failure.
+ */
+const REQUIRED_SOURCES = [
+    { key: 'security', source: 'security-audit', rels: SECURITY_RELS },
+    { key: 'perf', source: 'perf-audit', rels: PERF_RELS },
+    { key: 'karpathy', source: 'karpathy-reviewer', rels: KARPATHY_RELS }
+];
 export function registerVerdictAggregateCommands(program, io) {
     const verdict = program.command('verdict').description('Aggregate the 5 envelope sources feeding peaks-code verdict logic');
     addJsonOption(verdict
@@ -25,6 +65,27 @@ export function registerVerdictAggregateCommands(program, io) {
             process.exitCode = 1;
             return;
         }
+        // The rid SELECTS THE FILE, so it has to be one path segment. This is the
+        // repo's own request-id guard — the one `request-artifact-service.ts`
+        // applies to every request artifact and the reason `peaks workflow
+        // verify-pipeline` refuses a hostile rid — and it was not applied to the
+        // joins below. Measured before it was: `--from-rid
+        // '../../../../../../ONLY-HERE'` read `<project>/ONLY-HERE.md`, a file
+        // outside `.peaks/`, as this slice's security AND perf evidence.
+        if (!REQUEST_ID_PATTERN.test(rid)) {
+            printResult(io, fail('verdict.aggregate', 'RID_INVALID', `Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`, {}, ['Pass the rid of the slice whose evidence you want aggregated, e.g. 2026-09-14-some-slug']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // `--sid` names the session DIRECTORY and is the same axis. Reject
+        // anything that is not one safe path segment rather than pinning a
+        // format: the default here is the deliberately non-format value
+        // `default`.
+        if (isUnsafePathInput(sid)) {
+            printResult(io, fail('verdict.aggregate', 'SID_INVALID', `Invalid session id: ${sid} (must be a single path segment)`, {}, ['Pass the session id, e.g. 2026-09-14-session-abc123']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         try {
             const sources = {
                 // v2.13.3 AC-1: use the canonical markdown-aware parser from
@@ -34,9 +95,9 @@ export function registerVerdictAggregateCommands(program, io) {
                 // returned `verdict: warn, violations: []` — the aggregator
                 // then produced `reasons: []` and `verdict: 'pass'` even when
                 // the audit had flagged HIGH violations.
-                security: readAudit(projectRoot, sid, SECURITY_REL, parseSecurityEnvelope),
-                perf: readAudit(projectRoot, sid, PERF_REL, parsePerfEnvelope),
-                karpathy: readAudit(projectRoot, sid, KARPATHY_REL, (m) => parseKarpathyEnvelope(m)),
+                security: readAudit(projectRoot, sid, rid, SECURITY_RELS, parseSecurityEnvelope),
+                perf: readAudit(projectRoot, sid, rid, PERF_RELS, parsePerfEnvelope),
+                karpathy: readAudit(projectRoot, sid, rid, KARPATHY_RELS, (m) => parseKarpathyEnvelope(m)),
                 mut: await readMut(projectRoot, sid),
                 qa: readQa(projectRoot, sid, rid)
             };
@@ -55,7 +116,26 @@ export function registerVerdictAggregateCommands(program, io) {
                 mut: sources.mut !== null ? 'present' : 'missing',
                 qa: sources.qa !== null ? 'present' : 'missing'
             };
-            printResult(io, ok('verdict.aggregate', { verdict: result.verdict, reasons: result.reasons, sources: sourceFlags }, [], []), options.json);
+            // Fail closed. `aggregateVerdict()` starts its top-level verdict at
+            // `'pass'`, so a source that could not be read simply never enters the
+            // input and the run reports green. Before this slice the bare paths
+            // were the ones the writers wrote; after it the writers moved and this
+            // reader did not — so a missing security or perf audit became a `pass`
+            // for the loop evaluator (`services/loop/evaluator-dispatcher.ts`). A
+            // guard that cannot read its input must not report success.
+            const missingRequired = REQUIRED_SOURCES.filter((entry) => sources[entry.key] === null);
+            const missingReasons = missingRequired.map((entry) => ({
+                source: entry.source,
+                sources: [entry.source],
+                signal: 'block',
+                kind: 'missing-evidence',
+                hint: `${entry.rels.map((rel) => rel.replace('<rid>', rid)).join(' | ')} could not be read under .peaks/_runtime/${sid}/`
+            }));
+            printResult(io, ok('verdict.aggregate', {
+                verdict: missingReasons.length > 0 ? 'block' : result.verdict,
+                reasons: [...missingReasons, ...result.reasons],
+                sources: sourceFlags
+            }, [], []), options.json);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -64,12 +144,14 @@ export function registerVerdictAggregateCommands(program, io) {
         }
     });
 }
-function readAudit(projectRoot, sid, rel, parse) {
-    const path = join(projectRoot, '.peaks', '_runtime', sid, rel);
-    if (!existsSync(path))
-        return null;
-    const md = readFileSync(path, 'utf8');
-    return parse(md);
+function readAudit(projectRoot, sid, rid, rels, parse) {
+    // Canonical rid-scoped location first, then the pre-rid locations.
+    for (const rel of rels) {
+        const path = join(projectRoot, '.peaks', '_runtime', sid, rel.replace('<rid>', rid));
+        if (existsSync(path))
+            return parse(readFileSync(path, 'utf8'));
+    }
+    return null;
 }
 async function readMut(projectRoot, sid) {
     const path = join(projectRoot, '.peaks', '_runtime', sid, MUT_REL);

package/dist/cli/commands/workflow-commands.js

@@ -420,7 +420,7 @@ export function registerWorkflowCommands(program, io) {
     // semantics, role-based auth).
     addJsonOption(workflow
         .command('skip')
-        .description('Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, tech-doc, code-review, security-review, qa-request-exists, test-cases, test-report, security-findings, performance-findings). Three rules apply: (1) only docs/config/chore slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.')
+        .description('Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, prd-handoff, bug-analysis, code-review, security-review, perf-baseline, qa-request-exists, test-cases, test-report). Three rules apply: (1) only docs/config/chore slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.')
         .requiredOption('--rid <rid>', 'request identifier')
         .requiredOption('--project <path>', 'project root path')
         .requiredOption('--gates <list>', 'comma-separated gate names (e.g. "QA" or "QA,slice-check" or "code-review,security-review")')

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 import { CommanderError } from 'commander';
 import { createProgram } from './program.js';
 import { getErrorMessage } from 'peaks-loop-shared/result';
-import { printErrorEnvelope } from './cli-helpers.js';
+import { printErrorEnvelope, printMissingRequiredOptionEnvelope, resolveInvokedCommandPath } from './cli-helpers.js';
 const defaultIo = {
     stdout: (text) => process.stdout.write(`${text}\n`),
     stderr: (text) => process.stderr.write(`${text}\n`)
@@ -30,32 +30,6 @@ const argv = process.argv.slice(2);
 const hasHelp = argv.some((arg) => arg === '--help' || arg === '-h');
 const firstPositional = argv.find((arg) => !arg.startsWith('-'));
 const program = createProgram();
-/**
- * The subcommand path the caller actually invoked, in the same tokens they
- * typed (`release canary`). Derived from the registered command tree by
- * consuming leading non-`-` argv tokens, so it never disagrees with what
- * Commander dispatched on.
- *
- * Commander's `CommanderError` carries a code and a message but no command
- * reference — `missingMandatoryOptionValue` is raised by the leaf command and
- * throws out of `parseAsync` with nothing naming it. Without this walk the
- * missing-option envelope could only say `command: "cli"`, which is the field
- * the caller needs to act on.
- */
-function resolveInvokedCommandPath() {
-    let cmd = program;
-    const parts = [];
-    for (const token of argv) {
-        if (token.startsWith('-'))
-            break;
-        const next = cmd.commands.find((c) => c.name() === token || c.aliases().includes(token));
-        if (next === undefined)
-            break;
-        parts.push(next.name());
-        cmd = next;
-    }
-    return parts.length > 0 ? parts.join(' ') : program.name();
-}
 if (hasHelp && firstPositional !== undefined) {
     const registered = new Set(program.commands.map((c) => c.name()));
     if (!registered.has(firstPositional)) {
@@ -86,24 +60,10 @@ program.parseAsync(process.argv).catch((error) => {
             return;
         }
         if (error.code === 'commander.missingMandatoryOptionValue') {
-            // A `.requiredOption()` the caller did not supply. Commander raises this
-            // as a plain `Error`-shaped `CommanderError`, so the `.catch()` below used
-            // to file it under `UNHANDLED_ERROR` — "you left out an argument" reported
-            // as a crash, with empty `nextActions` and no way to see WHICH option or
-            // what values it takes. The flags string Commander formats carries both
-            // (`--percent <10|50>`), so it is worth extracting rather than
-            // paraphrasing: it is the option's own declaration.
-            const message = getErrorMessage(error);
-            const option = /required option '([^']+)'/.exec(message)?.[1];
-            const invoked = resolveInvokedCommandPath();
-            printErrorEnvelope(defaultIo, invoked, 'MISSING_REQUIRED_OPTION', option === undefined
-                ? message
-                : `Missing required option '${option}' for \`peaks ${invoked}\`.`, { option: option ?? null }, [
-                option === undefined
-                    ? `Run \`peaks ${invoked} --help\` to see the options this command requires.`
-                    : `Supply ${option} — it is required, so the command has no default for it.`,
-                `Run \`peaks ${invoked} --help\` for the option's accepted values and its siblings.`
-            ]);
+            // See `printMissingRequiredOptionEnvelope` — the same builder backs the
+            // in-process test runner, so the envelope a test asserts is the envelope
+            // a user gets.
+            printMissingRequiredOptionEnvelope(defaultIo, resolveInvokedCommandPath(program, argv), getErrorMessage(error));
             return;
         }
         if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {

package/dist/services/artifacts/artifact-prerequisites.d.ts

@@ -29,18 +29,36 @@ export type ArtifactPrerequisite = {
      */
     headingMustContain?: ReadonlyArray<string>;
     /**
-     * Slice v2.12.0 Group B Tier 5: optional legacy path that satisfies
-     * the same gate. When `relativePath` does not resolve on disk, the
-     * resolver tries this fallback path before reporting the prereq as
-     * missing. Use this for 1-minor-release back-compat windows where
-     * an old artifact location is still accepted alongside the new one.
-     * v2.13.0 should remove all `legacyRelativePath` entries.
+     * The immediately previous location of this artifact. When
+     * `relativePath` does not resolve on disk, the resolver tries this
+     * path before reporting the prereq as missing.
+     *
+     * This field is a published surface, not just a private hint:
+     * `verify-pipeline`'s `contractEvidencePaths()`
+     * (`src/services/workflow/pipeline-verify-gate-support.ts`) reads it
+     * to build its probe list, so it must keep meaning "the one path a
+     * previous release wrote". Do not repurpose it as a general list —
+     * add older tiers to `legacyRelativePaths` instead.
      *
      * Body checks (`mustContain` / `mustContainAny` /
      * `headingMustContain`) apply to whichever path resolved — the
-     * gate does not distinguish which path served the file.
+     * gate does not distinguish which path served the file. That is
+     * deliberate: a legacy hit must keep the gate open, or existing
+     * sessions would fail the transition on upgrade.
      */
     legacyRelativePath?: string;
+    /**
+     * Further, older locations, tried **in declared order** after
+     * `legacyRelativePath`. Slice `2026-09-14-audit-artifact-rid-scoping`
+     * added this because the two audit artifacts have a two-release
+     * history behind their rid-scoped path: the pre-rid-scoping
+     * `audit/security.md` (v2.12.0) and, behind it, the v2.11.x
+     * `rd/security-review.md`. Three sessions on disk
+     * (`2026-09-06-session-a87ca4`, `2026-09-10-session-528a63`,
+     * `2026-09-12-session-e37ef0`) hold their security evidence only at
+     * the last of those, so the oldest tier still has to resolve.
+     */
+    legacyRelativePaths?: ReadonlyArray<string>;
 };
 export type PrerequisiteCheckResult = {
     ok: boolean;
@@ -75,4 +93,17 @@ export type CheckPrerequisitesOptions = {
     requestType?: RequestType;
 };
 export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
+/**
+ * The contract's BODY checks for one prerequisite, applied to `body`. Returns
+ * one human-readable message per failed check, empty when the body satisfies
+ * the contract.
+ *
+ * Exported because this contract has a SECOND enforcer: `peaks workflow
+ * verify-pipeline` probes the same table for the paths it checks
+ * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
+ * `existsSync` passed files this function rejects — a guard laxer than the
+ * contract it claims to read. Both callers now share this one implementation,
+ * so the checker cannot drift from the table again.
+ */
+export declare function prerequisiteBodyViolations(prerequisite: ArtifactPrerequisite, body: string): string[];
 export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;

package/dist/services/artifacts/artifact-prerequisites.js

@@ -26,8 +26,17 @@ const BUG_ANALYSIS = {
     description: 'Bug root-cause analysis (reproduction, affected paths, fix approach, regression test plan)',
     mustContain: ['## Root cause', '## Fix approach']
 };
+// Slice `2026-09-14-audit-artifact-rid-scoping`: the rid is part of the
+// filename (`code-review-<rid>.md`). A fixed per-session path cannot hold
+// two slices' evidence at once — the second slice's write silently
+// destroyed the first slice's on 2026-09-13, and the gate stayed green
+// because it only checks that *some* file is there, not whose it is.
+// The bare path stays accepted (see `legacyRelativePath`) so sessions
+// written before this change — and any writer still emitting it — keep
+// passing.
 const CODE_REVIEW = {
-    relativePath: 'rd/code-review.md',
+    relativePath: 'rd/code-review-<rid>.md',
+    legacyRelativePath: 'rd/code-review.md',
     description: 'Code review evidence (CRITICAL/HIGH must be fixed before handoff)',
     mustContain: ['## Findings', 'CRITICAL']
 };
@@ -52,23 +61,31 @@ const PERF_BASELINE = {
 // are dispatched as pre-RD audit runs that consume the public PRD
 // handoff (`prd/handoff.md`) — see `AUDIT_REQUIRES_HANDOFF` below.
 //
-// Back-compat: the canonical location is `audit/security.md` (and
-// `audit/perf.md`); the legacy `rd/security-review.md` (and
-// `rd/perf-baseline.md`) path is also accepted via `legacyRelativePath`
-// for the 1-minor-release window. v2.13.0 hard-deletes the legacy paths.
+// Back-compat: the canonical location is `audit/security-<rid>.md`
+// (and `audit/perf-<rid>.md`); the pre-rid-scoping `audit/security.md`
+// (and `audit/perf.md`) plus the older `rd/security-review.md` (and
+// `rd/perf-baseline.md`) are accepted via `legacyRelativePaths`, in
+// that order, for the back-compat window.
 const AUDIT_SECURITY = {
-    relativePath: 'audit/security.md',
-    legacyRelativePath: 'rd/security-review.md',
-    description: 'Independent security audit output (peaks-security-audit skill, v2.12.0+). Replaces the v2.11.x rd/security-review.md slot for fanout-trigger request types. The legacy path is accepted during the 1-minor-release back-compat window via legacyRelativePath.',
+    relativePath: 'audit/security-<rid>.md',
+    // Two legacy tiers behind the rid-scoped path: the pre-rid-scoping
+    // v2.12.0 location, then the v2.11.x one. Both are live on disk.
+    legacyRelativePath: 'audit/security.md',
+    legacyRelativePaths: ['rd/security-review.md'],
+    description: 'Independent security audit output (peaks-security-audit skill, v2.12.0+). Replaces the v2.11.x rd/security-review.md slot for fanout-trigger request types. The rid is part of the filename so two slices in one session do not collide; the bare and rd/-prefixed legacy locations are accepted during the back-compat window via legacyRelativePaths.',
     // New canonical path writes a "## Verdict" header on the audit
     // envelope. The legacy rd/security-review.md writes a "## Findings"
     // header. Both pass the gate.
     mustContainAny: ['## Verdict', '## Findings']
 };
 const AUDIT_PERF = {
-    relativePath: 'audit/perf.md',
-    legacyRelativePath: 'rd/perf-baseline.md',
-    description: 'Independent perf audit output (peaks-perf-audit skill, v2.12.0+). Replaces the v2.11.x rd/perf-baseline.md slot for fanout-trigger request types. The legacy path is accepted during the 1-minor-release back-compat window via legacyRelativePath.',
+    relativePath: 'audit/perf-<rid>.md',
+    // Same two-tier history as AUDIT_SECURITY. This is the pair that
+    // produced the 2026-09-13 evidence: `audit/perf.md` was overwritten by
+    // the second slice and the first slice's audit is unrecoverable.
+    legacyRelativePath: 'audit/perf.md',
+    legacyRelativePaths: ['rd/perf-baseline.md'],
+    description: 'Independent perf audit output (peaks-perf-audit skill, v2.12.0+). Replaces the v2.11.x rd/perf-baseline.md slot for fanout-trigger request types. The rid is part of the filename so two slices in one session do not collide; the bare and rd/-prefixed legacy locations are accepted during the back-compat window via legacyRelativePaths.',
     // New schema writes "## Baseline" header; the legacy schema writes
     // "## Results". Both pass the gate, as does the explicit
     // no-perf-surface stub (slices whose surface is purely logic /
@@ -93,6 +110,16 @@ const AUDIT_PERF = {
 // failure. The hard-fail behavior for `passed: false` is preserved
 // (the body still has to carry `"passed": true` when present).
 // v2.14.0 will remove `backCompat` and re-elevate missing → throw.
+//
+// Slice `2026-09-14-audit-artifact-rid-scoping` deliberately does NOT
+// rid-scope this path, unlike the four audit/review artifacts above. The
+// repo's own producer/reader constant is `mutReportPath()` in
+// `packages/peaks-loop-mut/src/services/mut/report-loader.ts`, which names
+// `mut/mut-report.json`, and `peaks mut run`'s `--out` is supplied by the
+// caller. A `<rid>`-templated requirement here would be a name no producer
+// in the repo can write — a gate that exists only in prose, sitting behind
+// `backCompat: true` so it gates nothing at all. If mut ever gains a
+// rid-scoped producer, the constant and this path move together.
 const MUT_REPORT = {
     relativePath: 'mut/mut-report.json',
     description: 'peaks-mut mutation + weak-assertion report (Plan 2, v2.12.0+). v2.13.1: required at rd:qa-handoff for feature / bugfix / refactor slices. v2.13.2: back-compat window — missing file downgrades to a warning (1-minor-release); passed:false still throws. The body must carry `"passed": true` when present; failed runs are blocked at this gate. CONFIG / DOCS / CHORE slices retain the legacy "no acceptance surface" exemption.',
@@ -105,10 +132,11 @@ const MUT_REPORT = {
     backCompat: true
 };
 // v2.12.0 Group B Tier 5 — gate that the peaks-prd handoff (the
-// immutable handoff capsule at `prd/handoff.md`) exists before any
+// immutable, per-slice handoff capsule at `prd/handoff-<rid>.md`
+// since slice `2026-09-14-prd-capsule-rid-scoping`) exists before any
 // audit skill is allowed to consume it. The peaks-security-audit
-// and peaks-perf-audit CLI commands read frontmatter from
-// `prd/handoff.md` (AC-2.4 / AC-3.4); if the handoff is missing the
+// and peaks-perf-audit CLI commands read frontmatter from the
+// capsule (AC-2.4 / AC-3.4); if the handoff is missing the
 // audit skill aborts — and so should the prereq gate when those
 // audits are required at rd:qa-handoff.
 //
@@ -117,8 +145,21 @@ const MUT_REPORT = {
 // the old form (no PRD handoff chain — config slices may run before
 // PRD handoff exists for small CONFIG-only commits).
 const AUDIT_REQUIRES_HANDOFF = {
-    relativePath: 'prd/handoff.md',
-    description: 'PRD handoff capsule (v2.12.0+) — peaks-security-audit / peaks-perf-audit both read frontmatter from this file. Must exist before audit prereqs are evaluated at rd:qa-handoff.',
+    relativePath: 'prd/handoff-<rid>.md',
+    // Slice `2026-09-14-prd-capsule-rid-scoping`: the rid is part of the
+    // filename, like the four audit/review artifacts above. A single slot per
+    // SESSION cannot hold two slices' capsules — `peaks prd handoff init`
+    // overwrote it on every call, and this gate stayed green because it pinned
+    // only `schemaVersion: 2` + `sha256:`, never WHOSE rid the file named.
+    // Measured on `2026-09-13-session-21878f`: a four-slice job passed this
+    // prerequisite on a capsule written for a different line of work.
+    // The bare path stays accepted (see `legacyRelativePath`) so the three
+    // sessions on disk that hold only `prd/handoff.md` keep passing. That tier
+    // is rid-blind by design — the scoping binds for capsules written from now
+    // on, and every producer (`handoff-service.initHandoff`,
+    // `handoff-auto-regen`, `evidence generate`) writes the rid-scoped name.
+    legacyRelativePath: 'prd/handoff.md',
+    description: 'PRD handoff capsule (v2.12.0+) — peaks-security-audit / peaks-perf-audit both read frontmatter from this file. Must exist before audit prereqs are evaluated at rd:qa-handoff. The rid is part of the filename so two slices in one session do not collide; the bare pre-rid-scoping location is accepted as the legacy tier.',
     // Empty `mustContain` is fine — file existence is the contract.
     // The peaks-prd handoff service writes frontmatter with
     // `schemaVersion: 2` and a sha256 fingerprint; we pin a
@@ -138,7 +179,8 @@ const AUDIT_REQUIRES_HANDOFF = {
 // header remains a substring match (it is the file's own gate header, not
 // a structural section anchor).
 const KARPATHY_REVIEW = {
-    relativePath: 'rd/karpathy-review.md',
+    relativePath: 'rd/karpathy-review-<rid>.md',
+    legacyRelativePath: 'rd/karpathy-review.md',
     description: 'RD-side karpathy review (peaks-rd 5-way fanout) — must contain a "## Karpathy-Gate" header AND the 4 guideline section markers (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution) as actual markdown headings. Per karpathy §1 / §3.',
     mustContain: ['## Karpathy-Gate'],
     headingMustContain: [
@@ -328,6 +370,57 @@ async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, reques
     const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(targetSuffix));
     return match ? join(dir, match) : null;
 }
+/**
+ * The contract's BODY checks for one prerequisite, applied to `body`. Returns
+ * one human-readable message per failed check, empty when the body satisfies
+ * the contract.
+ *
+ * Exported because this contract has a SECOND enforcer: `peaks workflow
+ * verify-pipeline` probes the same table for the paths it checks
+ * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
+ * `existsSync` passed files this function rejects — a guard laxer than the
+ * contract it claims to read. Both callers now share this one implementation,
+ * so the checker cannot drift from the table again.
+ */
+export function prerequisiteBodyViolations(prerequisite, body) {
+    const violations = [];
+    const lowered = body.toLowerCase();
+    if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
+        const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
+        if (missingMarkers.length > 0) {
+            violations.push(`${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`);
+        }
+    }
+    if (prerequisite.headingMustContain && prerequisite.headingMustContain.length > 0) {
+        // Slice 2.6.1.F: a line beginning with `#`, `##`, or `###` followed by
+        // the marker (case-insensitive). Fenced code blocks are NOT excluded
+        // here — a "heading" inside a code fence is rare and, when present,
+        // should still be reported as missing to keep the contract strict.
+        const headingLines = body
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => /^#{1,3}\s+/.test(line));
+        const loweredHeadings = headingLines.map((h) => h.toLowerCase());
+        const missingHeadings = prerequisite.headingMustContain.filter((marker) => !loweredHeadings.some((h) => h.includes(marker.toLowerCase())));
+        if (missingHeadings.length > 0) {
+            violations.push(`${prerequisite.description} — missing heading(s): ${missingHeadings.join(', ')}`);
+        }
+    }
+    if (prerequisite.mustContainAny && prerequisite.mustContainAny.length > 0) {
+        const hitAny = prerequisite.mustContainAny.some((marker) => lowered.includes(marker.toLowerCase()));
+        if (!hitAny) {
+            violations.push(`${prerequisite.description} — none of the escape-hatch markers present: ${prerequisite.mustContainAny.join(', ')}`);
+        }
+    }
+    return violations;
+}
+/** True when `prerequisite` declares any body check at all. Guards the read so
+ *  a prereq with no body contract is never opened (unchanged behaviour). */
+function hasBodyChecks(prerequisite) {
+    return (prerequisite.mustContain?.length ?? 0) > 0
+        || (prerequisite.headingMustContain?.length ?? 0) > 0
+        || (prerequisite.mustContainAny?.length ?? 0) > 0;
+}
 export async function checkPrerequisites(options) {
     const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
     if (requirements.length === 0) {
@@ -369,45 +462,10 @@ export async function checkPrerequisites(options) {
             missing.push({ path: relative, description: prerequisite.description });
             continue;
         }
-        if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
+        if (hasBodyChecks(prerequisite)) {
             const body = await readFile(absolute, 'utf8');
-            const lowered = body.toLowerCase();
-            const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
-            if (missingMarkers.length > 0) {
-                missing.push({
-                    path: relative,
-                    description: `${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`
-                });
-            }
-        }
-        if (prerequisite.headingMustContain && prerequisite.headingMustContain.length > 0) {
-            const body = await readFile(absolute, 'utf8');
-            // Slice 2.6.1.F: a line beginning with `#`, `##`, or `###` followed by
-            // the marker (case-insensitive). Fenced code blocks are NOT excluded
-            // here — a "heading" inside a code fence is rare and, when present,
-            // should still be reported as missing to keep the contract strict.
-            const headingLines = body
-                .split('\n')
-                .map((line) => line.trim())
-                .filter((line) => /^#{1,3}\s+/.test(line));
-            const loweredHeadings = headingLines.map((h) => h.toLowerCase());
-            const missingHeadings = prerequisite.headingMustContain.filter((marker) => !loweredHeadings.some((h) => h.includes(marker.toLowerCase())));
-            if (missingHeadings.length > 0) {
-                missing.push({
-                    path: relative,
-                    description: `${prerequisite.description} — missing heading(s): ${missingHeadings.join(', ')}`
-                });
-            }
-        }
-        if (prerequisite.mustContainAny && prerequisite.mustContainAny.length > 0) {
-            const body = await readFile(absolute, 'utf8');
-            const lowered = body.toLowerCase();
-            const hitAny = prerequisite.mustContainAny.some((marker) => lowered.includes(marker.toLowerCase()));
-            if (!hitAny) {
-                missing.push({
-                    path: relative,
-                    description: `${prerequisite.description} — none of the escape-hatch markers present: ${prerequisite.mustContainAny.join(', ')}`
-                });
+            for (const description of prerequisiteBodyViolations(prerequisite, body)) {
+                missing.push({ path: relative, description });
             }
         }
     }
@@ -454,12 +512,13 @@ function emitPrereqTransitionEvent(opts) {
  * (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
  * path, or null when nothing matches.
  *
- * v2.12.0 Group B Tier 5: if `prerequisite.legacyRelativePath` is set
- * and neither primary session-root tier resolved, the resolver tries
- * the legacy relative path at BOTH session roots before declaring the
- * prereq missing. This is the 1-minor-release back-compat mechanism
- * for artifacts that moved location (e.g. `rd/security-review.md` →
- * `audit/security.md`).
+ * Back-compat: once neither primary session-root tier resolved, the
+ * resolver walks `prerequisite.legacyRelativePaths` in declared order
+ * and tries each at BOTH session roots before declaring the prereq
+ * missing. This covers both artifacts that moved location
+ * (`rd/security-review.md` → `audit/security.md`) and ones that later
+ * gained a rid in the filename (`audit/security.md` →
+ * `audit/security-<rid>.md`, slice `2026-09-14-audit-artifact-rid-scoping`).
  */
 async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, requestId) {
     const roots = [canonicalSessionRoot, legacySessionRoot];
@@ -471,13 +530,19 @@ async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot,
         if (found !== null)
             return found;
     }
-    // Second pass: if a legacyRelativePath is declared, try it at every
-    // root. Only the relativePath is swapped — the same numbered-prefix
+    // Second pass: the single previous location, then any further older
+    // ones, at every root — newest first, so a session that somehow holds
+    // both a pre-rid and a v2.11.x file resolves to the newer shape.
+    // Only the relativePath is swapped — the same numbered-prefix
     // tolerance applies via the shared resolver.
-    if (prerequisite.legacyRelativePath !== undefined) {
+    const legacyTiers = [
+        ...(prerequisite.legacyRelativePath !== undefined ? [prerequisite.legacyRelativePath] : []),
+        ...(prerequisite.legacyRelativePaths ?? [])
+    ];
+    for (const legacy of legacyTiers) {
         const legacyPrereq = {
             ...prerequisite,
-            relativePath: prerequisite.legacyRelativePath
+            relativePath: legacy
         };
         for (const root of roots) {
             if (root === null)

package/dist/services/artifacts/request-artifact-service.d.ts

@@ -50,6 +50,14 @@ export type CreateRequestArtifactResult = {
      */
     scopeDir: string;
 };
+/**
+ * F-1 (slice 025 security): reject rids that contain path separators, null
+ * bytes, or traversal sequences. A request id is a single path segment, so
+ * anything that builds a filename from one must test it against this first —
+ * it is exported so those call sites reuse it instead of re-declaring a copy
+ * that can drift.
+ */
+export declare const REQUEST_ID_PATTERN: RegExp;
 export declare function createRequestArtifact(options: CreateRequestArtifactOptions): Promise<CreateRequestArtifactResult>;
 export type RequestArtifactSummary = {
     role: RequestArtifactRole;