peaks-loop 4.0.47 → 4.0.48

package/dist/services/evidence/evidence-generator.js

@@ -7,22 +7,34 @@
  * gates plus the verify-pipeline, so the orchestrator no longer hand-writes
  * them per mechanical file-split (or similar) slice.
  *
- * The content markers emitted here are the exact strings the CLI gates +
- * verify-pipeline mechanically check — see
- * `src/services/artifacts/artifact-prerequisites.ts` (mustContain /
- * mustContainAny / headingMustContain) and
- * `src/services/workflow/pipeline-verify-gate-support.ts` +
- * `src/services/workflow/artifact-paths.ts` (suffixed security/performance
- * findings). Do NOT reword the marker lines.
+ * The content markers emitted here are the exact strings the CLI gates
+ * mechanically check — see `src/services/artifacts/artifact-prerequisites.ts`
+ * (mustContain / mustContainAny / headingMustContain — the authoritative
+ * table). `peaks workflow verify-pipeline` reads that same table for both the
+ * evidence paths it probes and the markers it enforces
+ * (`src/services/workflow/pipeline-verify-gate-support.ts#contractEvidencePaths`).
+ * Do NOT reword the marker lines.
+ *
+ * This paragraph used to send editors to `src/services/workflow/artifact-paths.ts`
+ * as the checker of "suffixed security/performance findings". That is no longer
+ * true: the `security-findings-<rid>.md` / `performance-findings-<rid>.md` gates
+ * were removed in rid `2026-09-14-verify-pipeline-contract-drift` (no
+ * `qa:verdict-issued` table names those paths; security and perf evidence is
+ * resolved on the RD side at `audit/security-<rid>.md` / `audit/perf-<rid>.md`),
+ * and `artifact-paths.ts` has had zero code consumers since. It is not a marker
+ * authority, so it is not a pointer worth keeping.
  *
  * Karpathy §2 (Simplicity First): a single generator function + a handful of
  * pure body builders. No speculative options, no validation beyond what the
  * reference prototype performs.
  */
-import { createHash } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { serializeHandoffFrontmatter } from '../prd/handoff-frontmatter.js';
+import { handoffRelativePath, sha256OfBody } from '../prd/handoff-service.js';
 import { getSessionDir } from '../session/getSessionDir.js';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 /** Comma/space tolerant `--files` splitter. */
 export function parseFiles(raw) {
     return raw
@@ -235,40 +247,20 @@ function buildQaRequest(rid, sid, files) {
 `;
 }
 /**
- * Build the `prd/handoff.md` frontmatter + body and compute the sha256
- * fingerprint. The hash is computed over the frontmatter (with the
- * `handoffHash` line left empty — `sha256:`) concatenated with the body,
- * matching the reference prototype exactly.
+ * Build the `prd/handoff-<rid>.md` frontmatter + body. The frontmatter comes from the
+ * ONE canonical serializer and `handoffHash === sha256(body)` — the same
+ * pairing `handoff-service.initHandoff` and `handoff-auto-regen.ts` use, so
+ * this producer cannot drift from them.
+ *
+ * This function used to hand-roll a third, divergent frontmatter: a
+ * `handoffHash: sha256:<hex>` value with **no line beginning `sha256:`**, over
+ * a hash computed on `frontmatter + body` rather than the body. The
+ * `AUDIT_REQUIRES_HANDOFF` gate (a substring check) accepted that file while
+ * `readAndVerifyHandoff` in both audit skills returned `null` — the very
+ * producer/consumer divergence rid `2026-09-14-handoff-writer-gate-divergence`
+ * exists to remove, surviving in a function the same slice edited.
  */
 function buildHandoff(rid, sid, title, files, lineCounts) {
-    const bulletList = files.map((f) => `  - ${f}`).join('\n');
-    const frontmatter = `---
-requestId: ${rid}
-scope:
-${bulletList}
-files:
-${bulletList}
-handoffPath: .peaks/_runtime/${sid}/prd/handoff.md
-handoffHash: sha256:PLACEHOLDER
-decisions:
-  - id: D1
-    summary: "Mechanical verbatim module split"
-    rationale: "Satisfy the 800-line file-size gate."
-risks:
-  - id: R1
-    description: "Public exports may be imported elsewhere"
-    mitigation: "Import sites updated; tsc clean."
-nextActions:
-  - "peaks-qa validates the regression matrix"
-gateEvidence:
-  projectScan: .peaks/project-scan/project-scan.md
-  prdHandoff: .peaks/_runtime/${sid}/prd/handoff.md
-  codeReview: .peaks/_runtime/${sid}/rd/code-review.md
-  securityReview: .peaks/_runtime/${sid}/rd/security-review.md
-  perfBaseline: .peaks/_runtime/${sid}/audit/perf.md
-schemaVersion: 2
----
-`;
     const body = `# PRD Handoff — ${rid}
 
 ${title}. Mechanical verbatim module split; behavior-preserving.
@@ -279,10 +271,19 @@ ${filesMd(files)}
 Line counts:
 ${lineCountsMd(lineCounts)}
 `;
-    const hashInput = frontmatter.replace('sha256:PLACEHOLDER', 'sha256:') + body;
-    const hash = createHash('sha256').update(hashInput, 'utf8').digest('hex');
-    const content = frontmatter.replace('sha256:PLACEHOLDER', `sha256:${hash}`) + body;
-    return { content, hash };
+    const handoffHash = sha256OfBody(body);
+    const frontmatter = {
+        requestId: rid,
+        sessionId: sid,
+        schemaVersion: '2',
+        handoffHash,
+        writtenAt: new Date().toISOString(),
+        goals: [],
+        acceptanceCriteria: [],
+        preservedBehavior: [],
+        handoffPath: handoffRelativePath(sid, rid)
+    };
+    return { content: `${serializeHandoffFrontmatter(frontmatter)}${body}`, hash: handoffHash };
 }
 /** Find the existing numbered QA request file for `rid`, else the default. */
 async function resolveQaRequestPath(qaDir, rid) {
@@ -300,6 +301,21 @@ async function resolveQaRequestPath(qaDir, rid) {
 }
 export async function generateEvidence(options) {
     const { projectRoot, rid, title, files, lineCounts, sessionId } = options;
+    // Both values become path segments below — the rid as a filename, the sid as
+    // the session directory. Guard them BEFORE the first mkdir so a rejected run
+    // leaves nothing behind. `REQUEST_ID_PATTERN` is the repo's own request-id
+    // control (`request-artifact-service.ts`, F-1 slice 025 security); the sid
+    // gets the segment check because `--session-id` has no pinned format.
+    // Measured before these lines existed: `--rid '../../../pwned'` wrote
+    // `.peaks/_runtime/pwned.md`, outside the per-session evidence dir, and a
+    // deeper rid wrote above the project root with the string echoed into the
+    // artifact body.
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        throw new Error(`Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     const sessionRoot = getSessionDir(projectRoot, sessionId);
     const rdDir = join(sessionRoot, 'rd');
     const qaDir = join(sessionRoot, 'qa');
@@ -319,18 +335,39 @@ export async function generateEvidence(options) {
     }
     const qaRequestPath = await resolveQaRequestPath(qaDir, rid);
     const handoff = buildHandoff(rid, sessionId, title, files, lineCounts);
+    // Four of these twelve paths carry the rid because the `rd:qa-handoff` gate
+    // requires `<rid>` in them: every slice in a session shares `rd/` and
+    // `audit/`, so writing the ridless name silently destroyed the previous
+    // slice's evidence on 2026-09-13 while the gate stayed green (slice
+    // `2026-09-14-audit-artifact-rid-scoping`).
     const writes = [
-        [join(rdDir, 'code-review.md'), buildCodeReview(rid, title, files, lineCounts)],
+        [join(rdDir, `code-review-${rid}.md`), buildCodeReview(rid, title, files, lineCounts)],
+        [join(auditDir, `security-${rid}.md`), buildSecurityReview(rid)],
+        // ...but the `config` type is the one whose `rd:qa-handoff` row is
+        // `SECURITY_REVIEW` — the genuinely ridless `rd/security-review.md` — and
+        // this generator is request-type-agnostic (no `--request-type`). So it
+        // writes BOTH names: the rid-scoped one the fanout types resolve
+        // (`AUDIT_SECURITY`) and the bare one `config` resolves. Nothing is lost
+        // by having both; a `config` slice has nothing else to fall back on, and
+        // dropping this write made a `config` slice fail its own gate while the
+        // generator reported success (repair round: measured `missing:
+        // ['rd/security-review.md']` with the real generator and the real gate).
         [join(rdDir, 'security-review.md'), buildSecurityReview(rid)],
-        [join(rdDir, 'karpathy-review.md'), buildKarpathyReview(rid, lineCounts)],
+        [join(rdDir, `karpathy-review-${rid}.md`), buildKarpathyReview(rid, lineCounts)],
+        // `rd/tech-doc.md` stays ridless on purpose: the TECH_DOC prereq was
+        // removed in v2.11.0, so nothing gates it and there is no rid-scoped
+        // sibling that anything reads.
         [join(rdDir, 'tech-doc.md'), buildTechDoc(rid, title, files, lineCounts)],
-        [join(auditDir, 'perf.md'), buildPerfAudit(rid)],
+        [join(auditDir, `perf-${rid}.md`), buildPerfAudit(rid)],
         [join(qaDir, 'test-cases', `${rid}.md`), buildTestCases(rid)],
         [join(qaDir, 'test-reports', `${rid}.md`), buildTestReport(rid)],
         [join(qaDir, `security-findings-${rid}.md`), buildSecurityFindings(rid)],
         [join(qaDir, `performance-findings-${rid}.md`), buildPerformanceFindings(rid)],
         [qaRequestPath, buildQaRequest(rid, sessionId, files)],
-        [join(prdDir, 'handoff.md'), handoff.content]
+        // The handoff capsule carries the rid for the same reason as the four
+        // above (slice `2026-09-14-prd-capsule-rid-scoping`): one slot per
+        // session means the second slice's capsule overwrites the first's.
+        [join(prdDir, `handoff-${rid}.md`), handoff.content]
     ];
     const writtenFiles = [];
     for (const [path, content] of writes) {
@@ -341,7 +378,7 @@ export async function generateEvidence(options) {
         rid,
         sessionId,
         sessionRoot,
-        handoffPath: join(prdDir, 'handoff.md'),
+        handoffPath: join(prdDir, `handoff-${rid}.md`),
         handoffHash: handoff.hash,
         writtenFiles,
         createdDirectories

package/dist/services/final-review/final-review-service.d.ts

@@ -252,6 +252,15 @@ interface EvidenceSource {
     readonly label: string;
     /** Path segments under `.peaks/_runtime/<sessionId>/`. */
     readonly segments: readonly string[];
+    /**
+     * An older location of the SAME artifact, tried only when `segments` is not
+     * on disk. Slice `2026-09-14-prd-capsule-rid-scoping` moved the PRD handoff
+     * capsule to `prd/handoff-<rid>.md`; sessions written before it hold only
+     * the bare `prd/handoff.md`, and this module's delivery gate keys on that
+     * source — so a source that goes missing does not fail the gate, it stops
+     * it (`enforceScopeContractDelivery` returns early on `missing`).
+     */
+    readonly legacySegments?: readonly string[];
     /** Dimensions this source can supply evidence for. */
     readonly supports: readonly DimensionKind[];
     /** What DELIVERED means for this source. See `isDelivered()` — every source

package/dist/services/final-review/final-review-service.js

@@ -474,7 +474,10 @@ function evidenceSourcesFor(rid, prePostDiffAvailable) {
         {
             key: SCOPE_CONTRACT_SOURCE_KEY,
             label: 'PRD handoff (approved scope + non-goals)',
-            segments: ['prd', 'handoff.md'],
+            // One capsule per slice since `2026-09-14-prd-capsule-rid-scoping`; the
+            // bare name is the pre-scoping tier and still lives on 3 sessions.
+            segments: ['prd', `handoff-${rid}.md`],
+            legacySegments: ['prd', 'handoff.md'],
             supports: ['functional-completeness', 'existing-functionality-intact'],
             delivery: { kind: 'whole' }
         }
@@ -508,22 +511,43 @@ function classifyReadFailure(error) {
 function readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable) {
     const runtimeRoot = join(projectRoot, '.peaks', '_runtime', sessionId);
     return evidenceSourcesFor(rid, prePostDiffAvailable).map(source => {
-        const relativePath = ['.peaks', '_runtime', sessionId, ...source.segments].join('/');
-        const absolutePath = join(runtimeRoot, ...source.segments);
+        // The canonical location first; an older one is tried only when the
+        // canonical file is genuinely ABSENT (see `legacySegments`). A file that
+        // is present but unreadable stops the walk — falling through to an older
+        // copy would silently swap the evidence this run reports.
+        const attempts = [
+            source.segments,
+            ...(source.legacySegments !== undefined ? [source.legacySegments] : [])
+        ];
+        // The path reported when nothing resolved stays the CANONICAL one, so the
+        // operator is sent to where the artifact belongs, not to its old home.
+        let resolved = source.segments;
         let raw = null;
         let error = '';
-        let read = 'ok';
-        try {
-            raw = readFileSync(absolutePath);
-        }
-        catch (err) {
-            read = classifyReadFailure(err);
-            error = err instanceof Error ? err.message : String(err);
+        let read = 'missing';
+        for (const segments of attempts) {
+            try {
+                raw = readFileSync(join(runtimeRoot, ...segments));
+                read = 'ok';
+                resolved = segments;
+                break;
+            }
+            catch (err) {
+                read = classifyReadFailure(err);
+                error = err instanceof Error ? err.message : String(err);
+                // A file that exists but cannot be read IS this source's file, so it
+                // is also the path the report must name — walking on to an older copy
+                // would silently swap the evidence this run reports.
+                if (read === 'unreadable') {
+                    resolved = segments;
+                    break;
+                }
+            }
         }
         return {
             source,
-            relativePath,
-            absolutePath,
+            relativePath: ['.peaks', '_runtime', sessionId, ...resolved].join('/'),
+            absolutePath: join(runtimeRoot, ...resolved),
             raw,
             read,
             error,

package/dist/services/ide/ide-registry.d.ts

@@ -15,6 +15,25 @@ export declare function getAdapter(ide: IdeId): IdeAdapter;
 export declare function tryGetAdapter(ide: string): IdeAdapter | undefined;
 /** All registered adapter ids (insertion order). */
 export declare function listAdapterIds(): readonly IdeId[];
+/**
+ * Help text for every `--ide <id>` option, derived from the registry.
+ *
+ * It used to be a hand-written literal — `"target adapter id (claude-code |
+ * trae); default: auto-detect from env/cwd"` — copy-pasted into six option
+ * declarations across `hooks-commands.ts` and `statusline-commands.ts`. By the
+ * time anyone read it the registry had nine adapters, so the help named two of
+ * the nine values the option accepts and stayed silent about the other seven.
+ * A help string that enumerates a set it does not own cannot be kept true by
+ * discipline; deriving it here is the only form that cannot drift.
+ *
+ * Note for whoever is tempted to point the help at `peaks adapter list`
+ * instead: that command lists USER-REGISTERED vendor adapters from
+ * `.peaks/runtime/adapters.json` (a different registry, empty on a fresh
+ * project). It is not this set. The nine ids below have no CLI surface of
+ * their own; `peaks ide model --current` is the closest read-only viewer and
+ * it reports one adapter, not the list.
+ */
+export declare function resolveIdeOptionHelp(): string;
 /** All registered adapters (insertion order). */
 export declare function listAdapters(): readonly IdeAdapter[];
 /**

package/dist/services/ide/ide-registry.js

@@ -57,6 +57,27 @@ export function tryGetAdapter(ide) {
 export function listAdapterIds() {
     return Array.from(ADAPTERS.keys());
 }
+/**
+ * Help text for every `--ide <id>` option, derived from the registry.
+ *
+ * It used to be a hand-written literal — `"target adapter id (claude-code |
+ * trae); default: auto-detect from env/cwd"` — copy-pasted into six option
+ * declarations across `hooks-commands.ts` and `statusline-commands.ts`. By the
+ * time anyone read it the registry had nine adapters, so the help named two of
+ * the nine values the option accepts and stayed silent about the other seven.
+ * A help string that enumerates a set it does not own cannot be kept true by
+ * discipline; deriving it here is the only form that cannot drift.
+ *
+ * Note for whoever is tempted to point the help at `peaks adapter list`
+ * instead: that command lists USER-REGISTERED vendor adapters from
+ * `.peaks/runtime/adapters.json` (a different registry, empty on a fresh
+ * project). It is not this set. The nine ids below have no CLI surface of
+ * their own; `peaks ide model --current` is the closest read-only viewer and
+ * it reports one adapter, not the list.
+ */
+export function resolveIdeOptionHelp() {
+    return `target adapter id (${listAdapterIds().join(' | ')}); default: auto-detect from env/cwd`;
+}
 /** All registered adapters (insertion order). */
 export function listAdapters() {
     return Array.from(ADAPTERS.values());

package/dist/services/job/job-state-store.js

@@ -1,12 +1,19 @@
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { JobStateSchema } from './job-types.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 export class JobStateStore {
     rootDir;
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
     jobDir(jobId) {
+        // JobId axis. This is the only join the store performs, so one guard here
+        // covers every `peaks job *` subcommand — ten CLI call sites hand the
+        // store a caller-supplied `--job-id` and none of them checked it.
+        if (isUnsafePathInput(jobId)) {
+            throw new Error(`Invalid job id: ${jobId} (must be a single path segment)`);
+        }
         return join(this.rootDir, jobId);
     }
     init(input) {

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

@@ -25,6 +25,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 /** Compute the child-side path where the artifact should be mirrored.
  *  Mirrors the parent shape exactly: `.peaks/_runtime/<sid>/<role>/`. */
 function childArtifactPath(childRoot, sid, role, sourcePath) {
@@ -37,6 +38,16 @@ function ensureDirFor(file) {
 export function dispatchArtifact(opts) {
     const warnings = [];
     const perChild = [];
+    // `sid` becomes a path segment in every child (`childArtifactPath`). It has no
+    // pinned format (`--sid` is a free-form override), so it gets the repo's
+    // segment check — the same `isUnsafePathInput` `peaks evidence generate` and
+    // `peaks verdict aggregate` apply to their session id. Guard before the first
+    // mkdir so a rejected dispatch leaves nothing behind. Measured before this
+    // line existed: `--sid '../../../../../../PWNED-SID-ESCAPE'` wrote
+    // `<parent-of-fixture>/PWNED-SID-ESCAPE/prd/src.md`, above every project root.
+    if (isUnsafePathInput(opts.sid)) {
+        throw new Error(`Invalid session id: ${opts.sid} (must be a single path segment)`);
+    }
     // Validate targets against the manifest.
     const knownIds = new Set(opts.manifest.children.map((c) => c.id));
     const validTargets = [];

package/dist/services/prd/handoff-auto-regen.js

@@ -1,13 +1,18 @@
 /**
- * v2.13.2 AC-4 — prd/handoff.md auto-regen on prd:handed-off.
+ * v2.13.2 AC-4 — prd/handoff-<rid>.md auto-regen on prd:handed-off.
  *
  * When `peaks request transition --role prd --state handed-off` succeeds
- * and `prd/handoff.md` is missing, this helper writes a sha256-locked
+ * and this slice's capsule is missing, this helper writes a sha256-locked
  * handoff (schemaVersion: 2) using the request artifact body as the
- * handoff body. If the handoff already exists, it's NOT overwritten —
+ * handoff body. If the capsule already exists, it's NOT overwritten —
  * the existing handoff is canonical (it may carry a richer body that
  * peaks-prd produced in an earlier session).
  *
+ * Slice `2026-09-14-prd-capsule-rid-scoping`: the path carries the rid, so
+ * "already exists" is now asked per SLICE. The pre-rid-scoping bare name is
+ * deliberately NOT consulted — writing there would recreate the
+ * one-slot-per-session collision for the next slice in the session.
+ *
  * Karpathy §3 (Surgical Changes): this file only owns the auto-regen
  * path. The other 11 transitions are untouched.
  */
@@ -15,7 +20,8 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
-import { sha256OfBody } from './handoff-service.js';
+import { serializeHandoffFrontmatter } from './handoff-frontmatter.js';
+import { handoffRelativePath, sha256OfBody } from './handoff-service.js';
 import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Auto-regen the prd/handoff.md under `.peaks/_runtime/<sid>/prd/`.
@@ -25,7 +31,7 @@ export async function autoRegenPrdHandoff(opts) {
     if (opts.role !== 'prd') {
         return { status: 'failed', reason: 'role must be prd' };
     }
-    const handoffPath = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md');
+    const handoffPath = join(opts.projectRoot, handoffRelativePath(opts.sessionId, opts.requestId));
     if (existsSync(handoffPath)) {
         return { status: 'skipped-exists', path: handoffPath };
     }
@@ -41,28 +47,26 @@ export async function autoRegenPrdHandoff(opts) {
     const body = artifact.content;
     const sha256 = sha256OfBody(body);
     // v2.13.3 AC-4 — align with `AUDIT_REQUIRES_HANDOFF` prereq which
-    // pins `mustContain: ['schemaVersion: 2', 'sha256:']`. The previous
-    // field name `handoffHash` made peaks-loop write a handoff that the
-    // own prereq resolver would reject with "missing section(s): sha256:".
-    // Primary field is now `sha256`; `handoffHash` is kept as a literal
-    // alias for back-compat with any consumer (UI / external scripts)
-    // that still reads the old key.
-    const frontmatter = [
-        '---',
-        `requestId: ${opts.requestId}`,
-        `sessionId: ${opts.sessionId}`,
-        'schemaVersion: 2',
-        `sha256: ${sha256}`,
-        `handoffHash: ${sha256}`,
-        `writtenAt: ${new Date().toISOString()}`,
-        'goals: []',
-        'acceptanceCriteria: []',
-        'preservedBehavior: []',
-        `handoffPath: ${normalizePath(handoffPath.replace(opts.projectRoot, '')).replace(/^\//, '')}`,
-        '---',
-        ''
-    ].join('\n');
-    const content = `${frontmatter}${body}`;
+    // pins `mustContain: ['schemaVersion: 2', 'sha256:']`. Primary field is
+    // `sha256`; `handoffHash` is kept as a literal alias for the readers that
+    // still use the old key.
+    //
+    // Slice `2026-09-14-handoff-writer-gate-divergence`: this block used to be
+    // hand-rolled here while `handoff-service.serializeHandoff` rendered the
+    // SAME contract a second, incompatible way. Both now go through
+    // `serializeHandoffFrontmatter`, so the two producers cannot drift again.
+    const frontmatter = {
+        requestId: opts.requestId,
+        sessionId: opts.sessionId,
+        schemaVersion: '2',
+        handoffHash: sha256,
+        writtenAt: new Date().toISOString(),
+        goals: [],
+        acceptanceCriteria: [],
+        preservedBehavior: [],
+        handoffPath: normalizePath(handoffPath.replace(opts.projectRoot, '')).replace(/^\//, '')
+    };
+    const content = `${serializeHandoffFrontmatter(frontmatter)}${body}`;
     mkdirSync(dirname(handoffPath), { recursive: true });
     writeFileSync(handoffPath, content, 'utf8');
     const recomputed = createHash('sha256').update(body, 'utf8').digest('hex');

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

@@ -0,0 +1,44 @@
+/**
+ * The ONE canonical serialization of `prd/handoff.md` frontmatter.
+ *
+ * Why this module exists (slice `2026-09-14-handoff-writer-gate-divergence`):
+ * the handoff capsule is written by two producers and read by four
+ * consumers, and they did not agree on the bytes:
+ *
+ *   | consumer / producer | requirement |
+ *   |---|---|
+ *   | `AUDIT_REQUIRES_HANDOFF` (`artifact-prerequisites.ts`) | SUBSTRING `schemaVersion: 2` (unquoted) + `sha256:` |
+ *   | `audit-independent/{security,perf}-audit-service.ts` | anchored `^schemaVersion:\s*(\d+)\s*$` and `^sha256:\s*([a-f0-9]{64})\s*$` |
+ *   | `handoff-service.readHandoff` | YAML string `handoffHash` |
+ *   | `handoff-service.verifyHandoff` | `handoffHash` === sha256(body), bare hex |
+ *
+ * `handoff-service.serializeHandoff` fed the frontmatter through
+ * `yaml.stringify`, which emits `schemaVersion: "2"` and a bare
+ * `handoffHash:` — failing the gate AND both loaders. `handoff-auto-regen.ts`
+ * hand-rolled a second serialization that happened to satisfy all four. Two
+ * producers, two facts about the same contract, one of them wrong: that is
+ * the defect, and copying the right shape into a third place would keep it.
+ *
+ * So both producers call THIS function. `sha256` is emitted only here, and
+ * it is emitted plain, because the two audit loaders anchor a regex on it.
+ *
+ * Scalar-quoting rule — one rule, one documented exception set:
+ *   - every ordinary string is emitted through `yamlScalar` (a JSON
+ *     double-quoted scalar, which is valid YAML 1.2 and round-trips
+ *     backslashes correctly on Windows paths);
+ *   - `schemaVersion` and `sha256` are the exception: emitted PLAIN, because
+ *     they are the two scalars the gate and the loaders match textually and a
+ *     quoted scalar is invisible to all three. Both values are structurally
+ *     constrained (a version digit and 64 hex chars), so plain is unambiguous.
+ *
+ * `handoffHash` is quoted even though it is also a 64-hex value: the reader
+ * parses the block through YAML and requires a STRING, and a bare all-digit
+ * sha256 would parse as a YAML number and be refused by the shape check.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+/**
+ * Serialize `frontmatter` into the fenced block, terminated by the closing
+ * `---` and a trailing newline. Callers append the body verbatim, which keeps
+ * the sha256 of the body independent of how the frontmatter renders.
+ */
+export declare function serializeHandoffFrontmatter(frontmatter: HandoffFrontmatter): string;

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

@@ -0,0 +1,75 @@
+/**
+ * The ONE canonical serialization of `prd/handoff.md` frontmatter.
+ *
+ * Why this module exists (slice `2026-09-14-handoff-writer-gate-divergence`):
+ * the handoff capsule is written by two producers and read by four
+ * consumers, and they did not agree on the bytes:
+ *
+ *   | consumer / producer | requirement |
+ *   |---|---|
+ *   | `AUDIT_REQUIRES_HANDOFF` (`artifact-prerequisites.ts`) | SUBSTRING `schemaVersion: 2` (unquoted) + `sha256:` |
+ *   | `audit-independent/{security,perf}-audit-service.ts` | anchored `^schemaVersion:\s*(\d+)\s*$` and `^sha256:\s*([a-f0-9]{64})\s*$` |
+ *   | `handoff-service.readHandoff` | YAML string `handoffHash` |
+ *   | `handoff-service.verifyHandoff` | `handoffHash` === sha256(body), bare hex |
+ *
+ * `handoff-service.serializeHandoff` fed the frontmatter through
+ * `yaml.stringify`, which emits `schemaVersion: "2"` and a bare
+ * `handoffHash:` — failing the gate AND both loaders. `handoff-auto-regen.ts`
+ * hand-rolled a second serialization that happened to satisfy all four. Two
+ * producers, two facts about the same contract, one of them wrong: that is
+ * the defect, and copying the right shape into a third place would keep it.
+ *
+ * So both producers call THIS function. `sha256` is emitted only here, and
+ * it is emitted plain, because the two audit loaders anchor a regex on it.
+ *
+ * Scalar-quoting rule — one rule, one documented exception set:
+ *   - every ordinary string is emitted through `yamlScalar` (a JSON
+ *     double-quoted scalar, which is valid YAML 1.2 and round-trips
+ *     backslashes correctly on Windows paths);
+ *   - `schemaVersion` and `sha256` are the exception: emitted PLAIN, because
+ *     they are the two scalars the gate and the loaders match textually and a
+ *     quoted scalar is invisible to all three. Both values are structurally
+ *     constrained (a version digit and 64 hex chars), so plain is unambiguous.
+ *
+ * `handoffHash` is quoted even though it is also a 64-hex value: the reader
+ * parses the block through YAML and requires a STRING, and a bare all-digit
+ * sha256 would parse as a YAML number and be refused by the shape check.
+ */
+/** Render a string as a YAML double-quoted scalar. JSON string escapes are a
+ *  subset of YAML 1.2's double-quoted escapes, so this is valid YAML and
+ *  handles `\` (Windows paths), quotes, colons and newlines in one step. */
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+/** Render `key: []` or a YAML block sequence of quoted scalars. */
+function blockSequence(key, values) {
+    if (values.length === 0)
+        return [`${key}: []`];
+    return [`${key}:`, ...values.map((value) => `  - ${yamlScalar(value)}`)];
+}
+/**
+ * Serialize `frontmatter` into the fenced block, terminated by the closing
+ * `---` and a trailing newline. Callers append the body verbatim, which keeps
+ * the sha256 of the body independent of how the frontmatter renders.
+ */
+export function serializeHandoffFrontmatter(frontmatter) {
+    const lines = [
+        '---',
+        `requestId: ${yamlScalar(frontmatter.requestId)}`,
+        `sessionId: ${yamlScalar(frontmatter.sessionId)}`,
+        // PLAIN by construction (`HandoffSchemaVersion` is the literal '2').
+        `schemaVersion: ${frontmatter.schemaVersion}`,
+        // PLAIN: this is the field both audit loaders read, via an anchored
+        // regex that a quoted scalar would not match.
+        `sha256: ${frontmatter.handoffHash}`,
+        // Quoted: `readHandoff` requires a YAML string here.
+        `handoffHash: ${yamlScalar(frontmatter.handoffHash)}`,
+        `writtenAt: ${yamlScalar(frontmatter.writtenAt)}`,
+        ...blockSequence('goals', frontmatter.goals),
+        ...blockSequence('acceptanceCriteria', frontmatter.acceptanceCriteria),
+        ...blockSequence('preservedBehavior', frontmatter.preservedBehavior),
+        `handoffPath: ${yamlScalar(frontmatter.handoffPath)}`,
+        '---',
+    ];
+    return `${lines.join('\n')}\n`;
+}