peaks-loop 4.0.46 → 4.0.48

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/artifact-service.js

@@ -14,7 +14,7 @@ function getRemoteUrl(artifactRepo) {
 }
 function hasGit() {
     try {
-        execFileSync('git', ['--version']);
+        execFileSync('git', ['--version'], { windowsHide: true });
         return true;
     }
     catch {

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;

package/dist/services/artifacts/request-artifact-service.js

@@ -11,6 +11,7 @@ import { ensureSession, getSessionIdCanonical } from '../session/session-manager
 // live at `shared/path-safety.ts` if this module ever needs them.
 import { getNextNumber, buildNumberedFilename, slugifyDescription } from '../../shared/incrementing-number.js';
 import { lintRequestArtifact } from './artifact-lint-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { checkTypeSanity } from '../scan/type-sanity-service.js';
 import { requireUserConfirmation } from '../mode/mode-enforcement.js';
 import { scanFileSize } from '../scan/file-size-scan.js';
@@ -27,7 +28,14 @@ export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType };
 // the local namespace under `isolatedModules`).
 import { renderTemplate } from './artifact-templates.js';
 export { formatHandoffPath, formatCommitBoundaryPath, formatSkillUsageLessonsPath } from './artifact-templates.js';
-const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * 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 const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const VALID_ROLES = new Set(['prd', 'ui', 'rd', 'qa', 'sc']);
 function defaultClock() {
     return new Date().toISOString();
@@ -60,6 +68,13 @@ export async function createRequestArtifact(options) {
     // in the artifact body's frontmatter (under `- change-id:`) for
     // human navigation; it is no longer a filesystem path key.
     const sessionId = options.sessionId ?? await ensureSession(options.projectRoot);
+    // Sid axis. The rid axis is guarded three times above (`REQUEST_ID_PATTERN`
+    // at :110, and again in the numbered-filename path); the session id was
+    // never checked, so `--session-id ../../x` wrote the artifact outside the
+    // project root under an `ok: true` envelope.
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     // Slice 2026-06-29-change-id-root-removal: the `current-change`
     // binding file is gone. Resolution order for the change-id (file
     // body metadata) is now:
@@ -154,17 +169,12 @@ export async function createRequestArtifact(options) {
     };
 }
 function extractMetadata(markdown) {
-    let state = 'unknown';
+    const state = readArtifactState(markdown) ?? 'unknown';
     let createdAt;
     let requestType = DEFAULT_REQUEST_TYPE;
     let sessionId;
     for (const rawLine of markdown.split(/\r?\n/)) {
         const line = rawLine.trim();
-        const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(line);
-        if (stateMatch !== null && stateMatch[1] !== undefined) {
-            state = stateMatch[1];
-            continue;
-        }
         const createdMatch = /^-\s*created:\s*(.+?)\s*$/.exec(line);
         if (createdMatch !== null && createdMatch[1] !== undefined) {
             createdAt = createdMatch[1];
@@ -343,7 +353,7 @@ async function readRequestArtifact(projectRoot, scope, role, found) {
 // the sibling `request-artifact-state-helpers.ts` module — see
 // v2.18.3 file-split for the rationale. Function signatures and
 // behaviour are unchanged (verbatim move).
-import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock, } from './request-artifact-state-helpers.js';
+import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, readArtifactState, TypeSanityViolationError, updateStatusBlock, } from './request-artifact-state-helpers.js';
 export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
 export async function transitionRequestArtifact(options) {
     if (!VALID_ROLES.has(options.role)) {

package/dist/services/artifacts/request-artifact-state-helpers.d.ts

@@ -45,6 +45,63 @@ export declare class FileSizeViolationError extends Error {
         lines: number;
     }>, threshold: number);
 }
+export interface ArtifactStateLocation {
+    /** Index of the authoritative `- state:` line, or -1 when the document has none. */
+    stateLineIndex: number;
+    /** The authoritative state, or null when `stateLineIndex` is -1. */
+    state: string | null;
+}
+/**
+ * The ONE rule for "which `state:` line is this artifact's state": the LAST
+ * one. A request artifact is an append-only log — each QA round appends a
+ * section ending in its own `## Status`, and `request transition` rewrites the
+ * newest state line in place — so the last line is the current round and the
+ * earlier ones are history.
+ *
+ * Every reader (`verify-pipeline`, `request show`, the resume detector) and the
+ * writer (`updateStatusBlock`) MUST go through this. The 2026-09-14 defect was
+ * three readers disagreeing about one file: `verify-pipeline` and the resume
+ * detector took the first match, `request show` took the last, so an artifact
+ * appended to more than once read as its first round to the checker and the
+ * resume detector while reading as its last round to the viewer and the writer.
+ *
+ * Scoping the search to the last `## Status` block was evaluated as an
+ * alternative and rejected — as a SECOND locator, not as a broken rule. It is
+ * well defined on the specimen that motivated this slice (four blocks) and
+ * returns `verdict-issued`, the right answer; and a trailing appended
+ * `- state:` line does not defeat it the way it defeats this rule — on that
+ * input the two rules disagree, and the one the block rule then disagrees with
+ * is the writer. `updateStatusBlock` rewrites the last `- state:` line wherever
+ * it sits and never moves it into the newest block, so a block-scoped reader
+ * parts company with the writer as soon as those two positions differ: the
+ * writer writes the appended line while the block reader keeps reporting the
+ * block's own line. That is this slice's reader-vs-writer divergence on a new
+ * axis. Sharing the writer's locator makes the agreement structural, not
+ * accidental.
+ *
+ * Known boundary of this rule, pinned in
+ * `request-artifact-state-authority.test.ts` rather than hidden: a process that
+ * appends a bare `- state:` line takes over the field — consistent with the
+ * writer being its only sanctioned producer.
+ *
+ * Two narrowings keep that boundary to lines the writer could have produced.
+ * A line inside a fenced code region is skipped, and the line must start at
+ * column 0. Neither is defensive decoration: a document that *describes* the
+ * state machine quotes `- state: qa-block` inside a fence, and this job's own
+ * `qa/requests/*.md` artifacts do exactly that — under the unfenced rule the
+ * quoted example was an input to the transition checker, and it survived only
+ * because the quoted copies happened not to be last. Both narrowings were
+ * measured against every `*.md` under `.peaks/` (833 files) and change no
+ * artifact's answer, and the writer already satisfies both by construction
+ * (`updateStatusBlock` writes `- state: <state>` at column 0), so reader and
+ * writer stay the same locator.
+ *
+ * Fuller record: the slice-3 section of this session's `rd/tech-doc.md` and
+ * the repair-round section of `rd/repair2-meta-integrity-fixes.md`.
+ */
+export declare function locateArtifactState(lines: ReadonlyArray<string>): ArtifactStateLocation;
+/** `locateArtifactState` over a whole document. Null when there is no `- state:` line. */
+export declare function readArtifactState(markdown: string): string | null;
 export declare function updateStatusBlock(markdown: string, newState: RequestArtifactState, timestamp: string, reason?: string): {
     updated: string;
     previousState: string;

package/dist/services/artifacts/request-artifact-state-helpers.js

@@ -75,20 +75,101 @@ export class FileSizeViolationError extends Error {
         this.threshold = threshold;
     }
 }
-export function updateStatusBlock(markdown, newState, timestamp, reason) {
-    const lines = markdown.split(/\r?\n/);
-    let previousState = 'unknown';
+/**
+ * The `- state:` line the artifact templates and `request transition` write.
+ * Anchored on both ends so a prose mention (`state: qa-block`, without the
+ * leading dash) is not read as the field, and anchored at column 0 because
+ * every writer of this field (`updateStatusBlock`, `request init`) emits it
+ * as a top-level line — an indented match is a nested list item, not the
+ * field. `locateArtifactState` applies it only outside fenced code regions.
+ */
+const STATE_LINE_RE = /^-\s*state:\s*(.+?)\s*$/;
+/** A fenced-code delimiter line: three or more backticks or tildes. */
+const FENCE_LINE_RE = /^(`{3,}|~{3,})/;
+/**
+ * The ONE rule for "which `state:` line is this artifact's state": the LAST
+ * one. A request artifact is an append-only log — each QA round appends a
+ * section ending in its own `## Status`, and `request transition` rewrites the
+ * newest state line in place — so the last line is the current round and the
+ * earlier ones are history.
+ *
+ * Every reader (`verify-pipeline`, `request show`, the resume detector) and the
+ * writer (`updateStatusBlock`) MUST go through this. The 2026-09-14 defect was
+ * three readers disagreeing about one file: `verify-pipeline` and the resume
+ * detector took the first match, `request show` took the last, so an artifact
+ * appended to more than once read as its first round to the checker and the
+ * resume detector while reading as its last round to the viewer and the writer.
+ *
+ * Scoping the search to the last `## Status` block was evaluated as an
+ * alternative and rejected — as a SECOND locator, not as a broken rule. It is
+ * well defined on the specimen that motivated this slice (four blocks) and
+ * returns `verdict-issued`, the right answer; and a trailing appended
+ * `- state:` line does not defeat it the way it defeats this rule — on that
+ * input the two rules disagree, and the one the block rule then disagrees with
+ * is the writer. `updateStatusBlock` rewrites the last `- state:` line wherever
+ * it sits and never moves it into the newest block, so a block-scoped reader
+ * parts company with the writer as soon as those two positions differ: the
+ * writer writes the appended line while the block reader keeps reporting the
+ * block's own line. That is this slice's reader-vs-writer divergence on a new
+ * axis. Sharing the writer's locator makes the agreement structural, not
+ * accidental.
+ *
+ * Known boundary of this rule, pinned in
+ * `request-artifact-state-authority.test.ts` rather than hidden: a process that
+ * appends a bare `- state:` line takes over the field — consistent with the
+ * writer being its only sanctioned producer.
+ *
+ * Two narrowings keep that boundary to lines the writer could have produced.
+ * A line inside a fenced code region is skipped, and the line must start at
+ * column 0. Neither is defensive decoration: a document that *describes* the
+ * state machine quotes `- state: qa-block` inside a fence, and this job's own
+ * `qa/requests/*.md` artifacts do exactly that — under the unfenced rule the
+ * quoted example was an input to the transition checker, and it survived only
+ * because the quoted copies happened not to be last. Both narrowings were
+ * measured against every `*.md` under `.peaks/` (833 files) and change no
+ * artifact's answer, and the writer already satisfies both by construction
+ * (`updateStatusBlock` writes `- state: <state>` at column 0), so reader and
+ * writer stay the same locator.
+ *
+ * Fuller record: the slice-3 section of this session's `rd/tech-doc.md` and
+ * the repair-round section of `rd/repair2-meta-integrity-fixes.md`.
+ */
+export function locateArtifactState(lines) {
     let stateLineIndex = -1;
-    let lastUpdateLineIndex = -1;
+    let state = null;
+    let fence = null;
     for (const [index, raw] of lines.entries()) {
-        const trimmed = raw.trim();
-        const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(trimmed);
-        if (stateMatch !== null && stateMatch[1] !== undefined) {
-            previousState = stateMatch[1];
-            stateLineIndex = index;
+        const fenceMatch = FENCE_LINE_RE.exec(raw.trim());
+        if (fence === null) {
+            if (fenceMatch !== null) {
+                fence = fenceMatch[1][0];
+                continue;
+            }
+        }
+        else {
+            if (fenceMatch !== null && fenceMatch[1][0] === fence)
+                fence = null;
             continue;
         }
-        if (/^-\s*last update:\s*/.test(trimmed)) {
+        const match = STATE_LINE_RE.exec(raw);
+        if (match?.[1] !== undefined) {
+            stateLineIndex = index;
+            state = match[1];
+        }
+    }
+    return { stateLineIndex, state };
+}
+/** `locateArtifactState` over a whole document. Null when there is no `- state:` line. */
+export function readArtifactState(markdown) {
+    return locateArtifactState(markdown.split(/\r?\n/)).state;
+}
+export function updateStatusBlock(markdown, newState, timestamp, reason) {
+    const lines = markdown.split(/\r?\n/);
+    const { stateLineIndex, state } = locateArtifactState(lines);
+    const previousState = state ?? 'unknown';
+    let lastUpdateLineIndex = -1;
+    for (const [index, raw] of lines.entries()) {
+        if (/^-\s*last update:\s*/.test(raw.trim())) {
             lastUpdateLineIndex = index;
         }
     }

package/dist/services/audit-independent/perf-audit-service.d.ts

@@ -101,6 +101,15 @@ export declare function readPerfTemplate(projectRoot: string): string | null;
 export declare function detectPerfAudit(input: {
     readonly projectRoot: string;
     readonly sessionId: string;
+    /**
+     * The slice whose capsule this run audits. Slice
+     * `2026-09-14-prd-capsule-rid-scoping` put the rid in the capsule's
+     * filename, so a caller that knows it must pass it or the probe resolves
+     * only the pre-rid-scoping bare name. Both callers pass it:
+     * `runPerfAudit` always did, and `peaks perf-audit detect` forwards its
+     * long-standing `--rid` flag as of the post-verification repair round.
+     */
+    readonly requestId?: string;
     readonly dispatchError?: unknown;
     readonly envelope?: unknown;
 }): PerfAuditDetectResult;

package/dist/services/audit-independent/perf-audit-service.js

@@ -23,6 +23,8 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+import { resolveHandoffPath } from '../prd/handoff-service.js';
 /**
  * Validate a raw value as a PerfAuditEnvelope. Mirrors the
  * `isSecurityAuditEnvelope` strict-shape pattern.
@@ -134,8 +136,12 @@ export function readPerfTemplate(projectRoot) {
 export function detectPerfAudit(input) {
     const warnings = [];
     const nextActions = [];
-    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
-    const handoffPresent = existsSync(handoffPath);
+    const handoffPath = resolveHandoffPath({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {})
+    });
+    const handoffPresent = handoffPath !== null;
     const templatePath = join(input.projectRoot, '.peaks', 'project-scan', 'perf-template.md');
     const templatePresent = existsSync(templatePath);
     if (!handoffPresent) {
@@ -143,7 +149,12 @@ export function detectPerfAudit(input) {
             state: 'handoff-missing',
             handoffPresent: false,
             templatePresent,
-            warnings: [`peaks-prd handoff not found at ${handoffPath}`],
+            warnings: [
+                `peaks-prd handoff not found under ${join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd')}`,
+                ...(input.requestId === undefined
+                    ? ['No --rid was supplied, so only the pre-rid-scoping `prd/handoff.md` could be probed. Pass --rid to resolve this slice\'s `prd/handoff-<rid>.md`.']
+                    : [])
+            ],
             nextActions: [
                 'Run peaks-prd handoff init to produce a sha256-locked handoff before running peaks perf-audit.',
                 'Until the handoff exists, peaks-perf-audit cannot start (gate fail).'
@@ -268,6 +279,12 @@ export function renderPerfAuditArtifact(env, opts) {
  * Returns the absolute path on success.
  */
 export function writePerfAuditArtifact(projectRoot, sessionId, rid, body) {
+    // The rid is a filename below, and the write is tmp+rename, so an
+    // unvalidated rid can OVERWRITE an arbitrary `.md` rather than merely create
+    // one. Guarded here (not only at the CLI boundary) so no caller can skip it.
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        throw new Error(`Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`);
+    }
     const targetDir = join(projectRoot, '.peaks', '_runtime', sessionId, 'audit');
     mkdirSync(targetDir, { recursive: true });
     const targetPath = join(targetDir, `perf-${rid}.md`);
@@ -290,6 +307,7 @@ export function runPerfAudit(input) {
     const detect = detectPerfAudit({
         projectRoot: input.projectRoot,
         sessionId: input.sessionId,
+        requestId: input.rid,
         ...(input.dispatchError !== undefined ? { dispatchError: input.dispatchError } : {}),
         ...(input.envelope !== undefined ? { envelope: input.envelope } : {})
     });
@@ -298,8 +316,12 @@ export function runPerfAudit(input) {
     }
     // detect.state === 'ready' implies input.envelope passed isPerfAuditEnvelope.
     const env = input.envelope;
-    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
-    const verified = readAndVerifyHandoff(handoffPath, input.projectRoot);
+    const handoffPath = resolveHandoffPath({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        requestId: input.rid
+    });
+    const verified = handoffPath === null ? null : readAndVerifyHandoff(handoffPath, input.projectRoot);
     const handoffHash = verified?.frontmatter.sha256 ?? 'unknown';
     const rendered = renderPerfAuditArtifact(env, {
         rid: input.rid,