peaks-loop 4.0.53 → 4.1.0

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

@@ -22,46 +22,10 @@
  * the body content as UTF-8 bytes. The body MUST be the literal
  * markdown source — no normalization, no trailing-newline padding.
  */
-import type { Handoff, HandoffProbe } from './handoff-types.js';
+import type { GateEvidence, Handoff, HandoffProbe } from './handoff-types.js';
+export { handoffRelativePath, resolveHandoffPath } from './handoff-path-resolution.js';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export declare function sha256OfBody(body: string): string;
-/**
- * The canonical capsule path for ONE SLICE, relative to the project root.
- *
- * Slice `2026-09-14-prd-capsule-rid-scoping`: the capsule used to be one slot
- * per SESSION (`prd/handoff.md`), so the second slice's handoff silently
- * overwrote the first slice's — and `AUDIT_REQUIRES_HANDOFF` stayed green
- * because it never checked WHOSE rid the file named. Measured on
- * `2026-09-13-session-21878f`: a four-slice job passed that prerequisite on a
- * capsule left by a different line of work.
- *
- * This is the WRITE target, so it always carries the rid — a consumer-side
- * fallback here would leave a rid-scoped requirement with a bare-name writer,
- * which is the defect shape this slice exists to remove. Readers that must
- * tolerate pre-rid-scoping sessions call `resolveHandoffPath` instead.
- */
-export declare function handoffRelativePath(sessionId: string, requestId: string): string;
-/**
- * The capsule a CONSUMER should read for (session, requestId): the rid-scoped
- * path when it is on disk, else the pre-rid-scoping bare name. Returns null
- * when neither exists.
- *
- * Three sessions on disk still hold only the bare file
- * (`2026-09-06-session-a87ca4`, `2026-09-12-session-e37ef0`,
- * `2026-09-13-session-21878f`), so the legacy tier has to keep resolving for
- * the gate and for every reader below.
- *
- * `requestId` is optional because the detect-only audit surface reaches its
- * service without one. Such a caller can name only the bare path: a session
- * holding nothing but rid-scoped capsules reports missing rather than picking
- * among its siblings' capsules, which would re-open the cross-slice mix-up
- * this scoping exists to close (fail closed, not "some capsule is there").
- */
-export declare function resolveHandoffPath(opts: {
-    projectRoot: string;
-    sessionId: string;
-    requestId?: string;
-}): string | null;
 /** Pure: produce a Handoff with the frontmatter populated. Hash is
  *  computed here; callers MUST NOT pre-populate `handoffHash`. */
 export declare function initHandoff(opts: {
@@ -74,6 +38,26 @@ export declare function initHandoff(opts: {
     preservedBehavior: readonly string[];
     /** Override path; defaults to `.peaks/_runtime/<sid>/prd/handoff-<rid>.md`. */
     handoffPath?: string;
+    /** Paths to the gate evidence files, keyed by gate. Omitted field and
+     *  empty map are equivalent here: neither renders a `gateEvidence` block,
+     *  so a caller that declares nothing writes bytes identical to a pre-B1
+     *  capsule.
+     *
+     *  THIS IS NOT A SECOND SOURCE (B2). In production the value reaching this
+     *  parameter is always `deriveGateEvidence(...)`
+     *  (`services/prd/gate-evidence-derivation.ts`), which computes it from the
+     *  request type and the gate table. This function stays pure — it does not
+     *  read the type itself — so the map can be constructed without touching
+     *  the disk; that is why the parameter exists rather than an internal call.
+     *
+     *  SHAPE CONTRACT (F2 of `rid-b1-qa`, now enforced in both directions): a
+     *  map this accepts is EXACTLY what `readHandoffGateEvidence` reports as
+     *  `evidence` — `classifyGateEvidence` is the one shape rule behind both,
+     *  and `parseHandoffContent` stores the classified map rather than the raw
+     *  YAML. A declaration both paths REFUSE (`not-map` / `value-not-string`)
+     *  is refused here by a throw and there by a status; neither silently
+     *  produces a map the other cannot. */
+    gateEvidence?: GateEvidence;
 }): Handoff;
 /** Write a Handoff to disk. `projectRoot` is the absolute project
  *  root (so the `.peaks/_runtime/...` path is resolved absolutely).

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

@@ -23,111 +23,30 @@
  * markdown source — no normalization, no trailing-newline padding.
  */
 import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
-import { isUnsafePathInput } from '../../shared/path-safety.js';
-import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
-import { serializeHandoffFrontmatter } from './handoff-frontmatter.js';
-/** Required schema version for new handoffs. */
-const HANDOFF_SCHEMA_VERSION = '2';
+import { classifyGateEvidence } from './handoff-gate-evidence.js';
+import { HANDOFF_SCHEMA_VERSION, isGateEvidence, isSchemaVersion2, serializeHandoff } from './handoff-frontmatter-shape.js';
+import { handoffRelativePath } from './handoff-path-resolution.js';
+// Slice `b1-filesplit-campaign` (wave 3): the capsule PATH layer
+// (`assertSafeHandoffIds` / `handoffRelativePath` / `resolveHandoffPath`) and the
+// frontmatter field primitives (`HANDOFF_SCHEMA_VERSION` / `serializeHandoff` /
+// `isSchemaVersion2` / `isGateEvidence`) moved VERBATIM to
+// `./handoff-path-resolution.ts` and `./handoff-frontmatter-shape.ts` so this
+// file clears the 300 raw-line cap. The public names below are re-exported from
+// this path, so no importer changed; the id->path guard these joins carry is
+// still measured — the new module is named in rule D's scanned set in
+// `tests/unit/runtime/no-runtime-input-guard.test.ts`.
+export { handoffRelativePath, resolveHandoffPath } from './handoff-path-resolution.js';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export function sha256OfBody(body) {
     return createHash('sha256').update(body, 'utf8').digest('hex');
 }
-/**
- * Both ids in a handoff path are caller-supplied path segments, so both are
- * checked at the join. Added 2026-09-14 (repair R1, security audit F2 of
- * `2026-09-14-cli-id-escape-instrumentation`).
- *
- * This function was introduced by `0536d5bd` — the commit that instrumented
- * this defect class — with neither id checked, and it sat outside rule D's
- * scanned layer, so the instrument could not see its own new member.
- * Measured on the pre-fix tree (`prd handoff init --apply`, temp project,
- * `ok: true` both times):
- *
- *   --rid '../../../../../../README'  replaced the project-root README.md
- *   --sid '../../../../SIDOUT'        wrote 4 levels above the project root
- *
- * The two axes need two different controls, for a recorded reason: the rid has
- * a pinned format (`REQUEST_ID_PATTERN`, no separator, no dot-dot, no drive)
- * and the sid has none, so it gets the segment check. `isUnsafePathInput`
- * alone is NOT enough for the rid — it admits `a/b` (two non-empty segments),
- * which `request-artifact-service.ts` would reject.
- *
- * Guarding HERE rather than at the three `prd`/`env` flags means every producer
- * that writes through this constructor — `initHandoff`'s default,
- * `handoff-auto-regen.ts`, `evidence-generator.ts` — is covered by the join
- * itself, not by each caller re-deciding.
- */
-function assertSafeHandoffIds(sessionId, requestId) {
-    if (!REQUEST_ID_PATTERN.test(requestId)) {
-        throw new Error(`Invalid request id: ${requestId} (expected letters, digits, dots, underscores, or dashes)`);
-    }
-    if (isUnsafePathInput(sessionId)) {
-        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
-    }
-}
-/**
- * The canonical capsule path for ONE SLICE, relative to the project root.
- *
- * Slice `2026-09-14-prd-capsule-rid-scoping`: the capsule used to be one slot
- * per SESSION (`prd/handoff.md`), so the second slice's handoff silently
- * overwrote the first slice's — and `AUDIT_REQUIRES_HANDOFF` stayed green
- * because it never checked WHOSE rid the file named. Measured on
- * `2026-09-13-session-21878f`: a four-slice job passed that prerequisite on a
- * capsule left by a different line of work.
- *
- * This is the WRITE target, so it always carries the rid — a consumer-side
- * fallback here would leave a rid-scoped requirement with a bare-name writer,
- * which is the defect shape this slice exists to remove. Readers that must
- * tolerate pre-rid-scoping sessions call `resolveHandoffPath` instead.
- */
-export function handoffRelativePath(sessionId, requestId) {
-    assertSafeHandoffIds(sessionId, requestId);
-    return join('.peaks', '_runtime', sessionId, 'prd', `handoff-${requestId}.md`);
-}
-/**
- * The capsule a CONSUMER should read for (session, requestId): the rid-scoped
- * path when it is on disk, else the pre-rid-scoping bare name. Returns null
- * when neither exists.
- *
- * Three sessions on disk still hold only the bare file
- * (`2026-09-06-session-a87ca4`, `2026-09-12-session-e37ef0`,
- * `2026-09-13-session-21878f`), so the legacy tier has to keep resolving for
- * the gate and for every reader below.
- *
- * `requestId` is optional because the detect-only audit surface reaches its
- * service without one. Such a caller can name only the bare path: a session
- * holding nothing but rid-scoped capsules reports missing rather than picking
- * among its siblings' capsules, which would re-open the cross-slice mix-up
- * this scoping exists to close (fail closed, not "some capsule is there").
- */
-export function resolveHandoffPath(opts) {
-    // The legacy bare-name candidate below is a second join of the same sid, in a
-    // second function, so it needs the sid guarded in its own right — the
-    // optional-requestId branch reaches `handoffRelativePath` (guarded there), but
-    // the branch that is taken when a caller has NO rid reaches this join only.
-    if (isUnsafePathInput(opts.sessionId)) {
-        throw new Error(`Invalid session id: ${opts.sessionId} (must be a single path segment)`);
-    }
-    const candidates = [
-        ...(opts.requestId !== undefined ? [handoffRelativePath(opts.sessionId, opts.requestId)] : []),
-        join('.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md')
-    ];
-    for (const relative of candidates) {
-        const absolute = join(opts.projectRoot, relative);
-        if (existsSync(absolute))
-            return absolute;
-    }
-    return null;
-}
 /** Pure: produce a Handoff with the frontmatter populated. Hash is
  *  computed here; callers MUST NOT pre-populate `handoffHash`. */
 export function initHandoff(opts) {
-    const handoffPath = opts.handoffPath ??
-        handoffRelativePath(opts.sessionId, opts.requestId);
+    const handoffPath = opts.handoffPath ?? handoffRelativePath(opts.sessionId, opts.requestId);
     const handoffHash = sha256OfBody(opts.body);
     const frontmatter = {
         requestId: opts.requestId,
@@ -139,6 +58,12 @@ export function initHandoff(opts) {
         acceptanceCriteria: [...opts.acceptanceCriteria],
         preservedBehavior: [...opts.preservedBehavior],
         handoffPath,
+        // Conditionally spread rather than `gateEvidence: undefined`: this
+        // tsconfig sets `exactOptionalPropertyTypes`, and an explicit `undefined`
+        // would also make `serializeHandoffFrontmatter`'s
+        // `frontmatter.gateEvidence` key present-but-undefined for every caller
+        // that declares nothing.
+        ...(opts.gateEvidence === undefined ? {} : { gateEvidence: opts.gateEvidence })
     };
     return { frontmatter, body: opts.body };
 }
@@ -187,7 +112,7 @@ export async function verifyHandoff(filePath) {
         return {
             ok: false,
             reason: 'schema-version-mismatch',
-            actualHash: handoff.frontmatter.handoffHash,
+            actualHash: handoff.frontmatter.handoffHash
         };
     }
     const actualHash = sha256OfBody(handoff.body);
@@ -196,7 +121,7 @@ export async function verifyHandoff(filePath) {
             ok: false,
             reason: 'hash-mismatch',
             actualHash,
-            expectedHash: handoff.frontmatter.handoffHash,
+            expectedHash: handoff.frontmatter.handoffHash
         };
     }
     return { ok: true, actualHash, expectedHash: actualHash };
@@ -233,39 +158,24 @@ function parseHandoffContent(content) {
     // frontmatter is returned with the canonical `'2'` rather than the raw scalar
     // — otherwise every downstream `=== '2'` comparison would depend on which
     // producer wrote the file.
+    //
+    // F2: `gateEvidence` is normalized the same way, for the same reason. The
+    // raw YAML value is not returned: the CLASSIFIED map is. Unknown keys are
+    // not part of `GateEvidence`, so storing the raw object made the interface
+    // claim a five-key map while holding a six-key one — and made
+    // `frontmatter.gateEvidence` disagree with what the field's reader reports
+    // for the same bytes. The predicate above has already rejected every shape
+    // that is not `absent` or `ok`, so this spread only ever adds a clean map.
+    const gateEvidenceShape = classifyGateEvidence(parsed.gateEvidence);
     return {
-        frontmatter: { ...parsed, schemaVersion: HANDOFF_SCHEMA_VERSION },
+        frontmatter: {
+            ...parsed,
+            schemaVersion: HANDOFF_SCHEMA_VERSION,
+            ...(gateEvidenceShape.kind === 'ok' ? { gateEvidence: gateEvidenceShape.evidence } : {})
+        },
         body
     };
 }
-function serializeHandoff(handoff) {
-    // The one canonical frontmatter rendering, shared with
-    // `handoff-auto-regen.ts`. `yaml.stringify` used to render this block and
-    // emitted `schemaVersion: "2"` + a bare `handoffHash:`, which the
-    // `AUDIT_REQUIRES_HANDOFF` gate and both audit loaders all reject.
-    return `${serializeHandoffFrontmatter(handoff.frontmatter)}${handoff.body}`;
-}
-/**
- * N1: accept BOTH shapes of `schemaVersion` — the string `'2'` and the bare
- * YAML number `2` — and reject any other value.
- *
- * The reader used to require `typeof v.schemaVersion === 'string'`. That made
- * `readHandoff` refuse `prd/handoff.md` written by `handoff-auto-regen.ts`,
- * which emits the unquoted `schemaVersion: 2`, while the
- * `AUDIT_REQUIRES_HANDOFF` prereq — a SUBSTRING check for `schemaVersion: 2` —
- * happily passed the same bytes. So the gate that exists to guarantee a
- * readable handoff was satisfied by a handoff the parser would not read, and
- * `peaks prd handoff verify` exited 1 on a healthy file.
- *
- * Slice `2026-09-14-handoff-writer-gate-divergence` then fixed the other half:
- * the writer no longer emits the quoted form at all (see
- * `handoff-frontmatter.ts`). This tolerance stays because handoffs already on
- * disk were written by the old writer and by hand; the writer fix must not
- * retroactively make them unreadable.
- */
-function isSchemaVersion2(value) {
-    return value === HANDOFF_SCHEMA_VERSION || value === 2;
-}
 /**
  * The READER's shape check — deliberately looser than `verifyHandoff`:
  * `handoffHash` must be a string, and nothing about its VALUE is validated here.
@@ -296,5 +206,6 @@ function isHandoffFrontmatter(value) {
         Array.isArray(v.goals) &&
         Array.isArray(v.acceptanceCriteria) &&
         Array.isArray(v.preservedBehavior) &&
-        typeof v.handoffPath === 'string');
+        typeof v.handoffPath === 'string' &&
+        isGateEvidence(v.gateEvidence));
 }

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

@@ -24,6 +24,39 @@
  *  IDs in frontmatter). Every consumer MUST refuse a handoff whose
  *  frontmatter is missing or carries `schemaVersion !== '2'`. */
 export type HandoffSchemaVersion = '2';
+/**
+ * The FIVE fixed `gateEvidence` keys, in canonical serialization order.
+ *
+ * This array is the single source of truth for the key set: the
+ * `GateEvidenceKey` type is derived from it, the serializer iterates it,
+ * and the reader matches against it. Slice B1
+ * (`2026-09-17-4-0-51-cleanup`) collapsed four mutually contradictory
+ * descriptions of this field (a `string[]` in the reader's code comment,
+ * a `string[]` of PATHS in its tests, a map of paths in
+ * `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:35-41`)
+ * onto the documented map. Do NOT re-spell these five literals anywhere
+ * else — a second copy is how the four descriptions diverged.
+ */
+export declare const GATE_EVIDENCE_KEYS: readonly ["projectScan", "prdHandoff", "codeReview", "securityReview", "perfBaseline"];
+/** One of the five `gateEvidence` keys. Derived, never re-spelled. */
+export type GateEvidenceKey = (typeof GATE_EVIDENCE_KEYS)[number];
+/**
+ * Is `key` one of the five? THE membership test — the serializer's
+ * unknown-key check, the reader's classifier and the shape predicate all ask
+ * this one function, so no caller can disagree about what the key set is.
+ */
+export declare function isGateEvidenceKey(key: string): key is GateEvidenceKey;
+/**
+ * `gateEvidence` — a partial map from gate key to the PATH of that gate's
+ * evidence file. Partial because a slice may legitimately not have run
+ * every gate; the consumer (Gate C, wired in slice B2) fails on a missing
+ * key, which is where "did you declare it?" is decided — NOT here.
+ *
+ * Unknown keys are not expressible in this type. The reader still reports
+ * them at runtime (`unknownKeys`) so a typo is diagnosable rather than
+ * silently dropped.
+ */
+export type GateEvidence = Readonly<Partial<Record<GateEvidenceKey, string>>>;
 /**
  * Handoff frontmatter — the structured header block between the
  * leading and trailing `---` fences. `readonly` enforces D1's
@@ -47,6 +80,13 @@ export interface HandoffFrontmatter {
     readonly preservedBehavior: readonly string[];
     /** Absolute path to the handoff file on disk (for re-verify). */
     readonly handoffPath: string;
+    /** Paths to the evidence files peaks-qa validates at Gate C, keyed by
+     *  gate. ABSENT (not `{}`) when the slice declared none — the serializer
+     *  omits the block entirely rather than emitting an empty map, so old
+     *  handoffs gain no noise line. Read it through
+     *  `readHandoffGateEvidence`, which reports WHY it is unusable instead of
+     *  collapsing every failure to `null`. */
+    readonly gateEvidence?: GateEvidence;
 }
 /** Handoff — frontmatter + body. The body is the markdown source of
  *  truth that sub-agents and downstream consumers parse. */

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

@@ -20,4 +20,31 @@
  * `.peaks/_runtime/current-change`). NEVER write under
  * `.peaks/_runtime/<change-id>/...` directly (slice 2.8.3 hard ban).
  */
-export {};
+/**
+ * The FIVE fixed `gateEvidence` keys, in canonical serialization order.
+ *
+ * This array is the single source of truth for the key set: the
+ * `GateEvidenceKey` type is derived from it, the serializer iterates it,
+ * and the reader matches against it. Slice B1
+ * (`2026-09-17-4-0-51-cleanup`) collapsed four mutually contradictory
+ * descriptions of this field (a `string[]` in the reader's code comment,
+ * a `string[]` of PATHS in its tests, a map of paths in
+ * `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:35-41`)
+ * onto the documented map. Do NOT re-spell these five literals anywhere
+ * else — a second copy is how the four descriptions diverged.
+ */
+export const GATE_EVIDENCE_KEYS = [
+    'projectScan',
+    'prdHandoff',
+    'codeReview',
+    'securityReview',
+    'perfBaseline'
+];
+/**
+ * Is `key` one of the five? THE membership test — the serializer's
+ * unknown-key check, the reader's classifier and the shape predicate all ask
+ * this one function, so no caller can disagree about what the key set is.
+ */
+export function isGateEvidenceKey(key) {
+    return GATE_EVIDENCE_KEYS.includes(key);
+}

package/dist/services/prd/prd-blocks-checker.js

@@ -17,10 +17,30 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 const BLOCK_HEADINGS = [
-    { block: 1, name: '业务场景', pattern: /^#{1,4}\s*(?:\d+\.\s*)?业务场景[^\n]*$/m, requiredByDefault: true },
-    { block: 2, name: '边界 case', pattern: /^#{1,4}\s*(?:\d+\.\s*)?边界\s*case[^\n]*$/mi, requiredByDefault: true },
-    { block: 3, name: 'UI 装配意图', pattern: /^#{1,4}\s*(?:\d+\.\s*)?UI\s*装配[^\n]*$/mi, requiredByDefault: true },
-    { block: 4, name: '上游基线', pattern: /^#{1,4}\s*(?:\d+\.\s*)?上游基线[^\n]*$/m, requiredByDefault: false }
+    {
+        block: 1,
+        name: '业务场景',
+        pattern: /^#{1,4}\s*(?:\d+\.\s*)?业务场景[^\n]*$/m,
+        requiredByDefault: true
+    },
+    {
+        block: 2,
+        name: '边界 case',
+        pattern: /^#{1,4}\s*(?:\d+\.\s*)?边界\s*case[^\n]*$/im,
+        requiredByDefault: true
+    },
+    {
+        block: 3,
+        name: 'UI 装配意图',
+        pattern: /^#{1,4}\s*(?:\d+\.\s*)?UI\s*装配[^\n]*$/im,
+        requiredByDefault: true
+    },
+    {
+        block: 4,
+        name: '上游基线',
+        pattern: /^#{1,4}\s*(?:\d+\.\s*)?上游基线[^\n]*$/m,
+        requiredByDefault: false
+    }
 ];
 const MIN_CONTENT_LENGTH = 50;
 export function findPrdArtifact(projectRoot, requestId) {
@@ -75,9 +95,7 @@ export function checkPrdBlocks(projectRoot, requestId) {
                 required: h.requiredByDefault,
                 present: false,
                 content: null,
-                issues: h.requiredByDefault
-                    ? ['PRD artifact not found — write the prd body first.']
-                    : []
+                issues: h.requiredByDefault ? ['PRD artifact not found — write the prd body first.'] : []
             })),
             ok: false
         };
@@ -95,7 +113,9 @@ export function checkPrdBlocks(projectRoot, requestId) {
                 present: false,
                 content: null,
                 issues: required
-                    ? [`Missing required block: ${h.name}. Add a heading like "## ${h.name}" with at least ${MIN_CONTENT_LENGTH} chars of content.`]
+                    ? [
+                        `Missing required block: ${h.name}. Add a heading like "## ${h.name}" with at least ${MIN_CONTENT_LENGTH} chars of content.`
+                    ]
                     : []
             };
         }

package/dist/services/prd/project-scan-bootstrap-service.js

@@ -42,11 +42,7 @@ const SOURCE_FILE_EXTENSIONS = /\.(tsx?|jsx?|vue|svelte)$/;
  *   here — those projects should be detected via `package.json`
  *   workspaces[] field below.
  */
-const MONOREPO_ROOT_CONFIGS = [
-    'pnpm-workspace.yaml',
-    'turbo.json',
-    'nx.json'
-];
+const MONOREPO_ROOT_CONFIGS = ['pnpm-workspace.yaml', 'turbo.json', 'nx.json'];
 /** True iff the project root declares pnpm / yarn / npm workspaces. */
 function projectHasWorkspacesInPackageJson(projectRoot) {
     const pkgPath = join(projectRoot, 'package.json');

package/dist/services/prd/project-scan-reader.d.ts

@@ -10,6 +10,13 @@
  * errors propagate (no silent failures).
  */
 import type { BusinessKnowledge, ProjectScan } from './project-scan-types.js';
+/**
+ * `.peaks/project-scan/project-scan.md`, project-relative. Exported so the
+ * gate-evidence derivation (`gate-evidence-derivation.ts`) can declare this
+ * path without spelling the literal a fourth time — it was already inlined in
+ * `project-commands.ts`, `workspace/init-command.ts` and here.
+ */
+export declare const PROJECT_SCAN_RELATIVE: string;
 /** Read `.peaks/project-scan/project-scan.md`. Returns `null` when the
  *  file or its parent dir is absent (fresh project). Throws on other
  *  IO failures or malformed YAML. */

package/dist/services/prd/project-scan-reader.js

@@ -12,7 +12,13 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
-const PROJECT_SCAN_RELATIVE = join('.peaks', 'project-scan', 'project-scan.md');
+/**
+ * `.peaks/project-scan/project-scan.md`, project-relative. Exported so the
+ * gate-evidence derivation (`gate-evidence-derivation.ts`) can declare this
+ * path without spelling the literal a fourth time — it was already inlined in
+ * `project-commands.ts`, `workspace/init-command.ts` and here.
+ */
+export const PROJECT_SCAN_RELATIVE = join('.peaks', 'project-scan', 'project-scan.md');
 const BUSINESS_KNOWLEDGE_RELATIVE = join('.peaks', 'project-scan', 'business-knowledge.md');
 /** Read `.peaks/project-scan/project-scan.md`. Returns `null` when the
  *  file or its parent dir is absent (fresh project). Throws on other
@@ -53,10 +59,7 @@ async function readOptionalFile(projectRoot, relativePath) {
     }
 }
 function isEnoent(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        'code' in error &&
-        error.code === 'ENOENT');
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
 function parseProjectScanContent(content) {
     const { frontmatter } = splitFrontmatter(content);

package/dist/services/prd/project-scan-sediment.js

@@ -397,10 +397,7 @@ async function readOptionalFile(absolutePath) {
     }
 }
 function isEnoent(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        'code' in error &&
-        error.code === 'ENOENT');
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
 /** Serialize a `BusinessKnowledge` to the markdown-table body format.
  *  Matches the bootstrap template at `.peaks/project-scan/business-knowledge.md`. */

package/dist/services/preferences/preferences-service.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { DEFAULT_PREFERENCES, FANOUT_MODES, isFanoutMode, PREFERENCES_SCHEMA_VERSION, } from './preferences-types.js';
+import { DEFAULT_PREFERENCES, FANOUT_MODES, isFanoutMode, PREFERENCES_SCHEMA_VERSION } from './preferences-types.js';
 const PREFS_REL_PATH = '.peaks/preferences.json';
 export { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION };
 export function preferencesPath(projectRoot) {
@@ -93,7 +93,7 @@ function mergePreferences(base, overrides) {
     // that already specified `defaultMode` in their preferences.json.
     const shallow = {
         ...base,
-        ...Object.fromEntries(definedEntries),
+        ...Object.fromEntries(definedEntries)
     };
     const overrideFanout = overrides.fanout;
     if (overrideFanout !== undefined &&
@@ -107,7 +107,7 @@ function mergePreferences(base, overrides) {
     }
     return {
         ...shallow,
-        schema_version: PREFERENCES_SCHEMA_VERSION,
+        schema_version: PREFERENCES_SCHEMA_VERSION
     };
 }
 export function migratePreferences(projectRoot, opts = {}) {
@@ -122,9 +122,7 @@ export function migratePreferences(projectRoot, opts = {}) {
     catch (err) {
         throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
     }
-    const fromVersion = typeof raw.schema_version === 'string'
-        ? raw.schema_version
-        : 'unknown';
+    const fromVersion = typeof raw.schema_version === 'string' ? raw.schema_version : 'unknown';
     if (fromVersion === PREFERENCES_SCHEMA_VERSION) {
         return {
             fromVersion,
@@ -158,9 +156,9 @@ export function migratePreferences(projectRoot, opts = {}) {
     const migrated = mergePreferences(DEFAULT_PREFERENCES, {
         ...raw,
         fanout: typeof raw.fanout === 'object' && raw.fanout !== null && !Array.isArray(raw.fanout)
-            ? (raw.fanout.defaultMode === 'serial'
+            ? raw.fanout.defaultMode === 'serial'
                 ? { defaultMode: 'fan-out' }
-                : raw.fanout)
+                : raw.fanout
             : { defaultMode: 'fan-out' }
     });
     let written = false;

package/dist/services/preferences/preferences-types.js

@@ -26,12 +26,12 @@ export const DEFAULT_PREFERENCES = {
     classifyRules: {
         feature_threshold_files: 10,
         feature_threshold_lines: 100,
-        runtime_clean_grace_hours: 24,
+        runtime_clean_grace_hours: 24
     },
     swarmSpeculative: {
         enabled: true,
         maxConcurrent: 3,
-        minHitRate: 0.5,
+        minHitRate: 0.5
     },
     loopAutonomousEnabled: false,
     agentShieldEnabled: false,
@@ -55,6 +55,6 @@ export const DEFAULT_PREFERENCES = {
         warmItemCap: 4,
         warmMinTokenHits: 1,
         selectionTimeBudgetMs: 200,
-        includeBodies: false,
-    },
+        includeBodies: false
+    }
 };

package/dist/services/qa/bdd-test-style-contract.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `src/services/qa/bdd-test-style-contract.ts`
+ *
+ * Verdict types and pure string matchers extracted verbatim from
+ * `bdd-test-style-verifier.ts` (wave 2, file-size cap campaign) so the
+ * verifier stays under the 300 raw-line cap. Mechanical move only —
+ * the verifier re-exports every public type from its original path.
+ */
+/** Structured failure reasons the verifier can return. */
+export type BddStyleFailureReason = 'missing-given-when-then' | 'description-no-should-when';
+/** Successful verdict — includes the count of inspected `it`/`test` calls. */
+export interface BddStyleOk {
+    readonly ok: true;
+    readonly scanned: number;
+}
+/** Structured failure verdict — the file/line makes the rejection actionable. */
+export interface BddStyleFail {
+    readonly ok: false;
+    readonly reason: BddStyleFailureReason;
+    readonly file: string;
+    readonly line: number;
+    /** For `description-no-should-when`: the original description. */
+    readonly description?: string;
+    /** For `missing-given-when-then`: a stable string the caller can compare. */
+    readonly expected?: string;
+}
+export type BddStyleVerdict = BddStyleOk | BddStyleFail;
+/** Public input surface — keep small so the contract is hard to misuse. */
+export interface VerifyBddStyleInput {
+    readonly projectRoot: string;
+    readonly testFiles: readonly string[];
+}
+/**
+ * Match the three leading comments against the BDD triple. Each
+ * entry must be a `// <keyword>:` line (with optional trailing
+ * whitespace); the keywords must appear in `given`, `when`, `then`
+ * order, case-insensitive.
+ */
+export declare function matchesBddTriple(triple: readonly string[]): boolean;
+/** True when `text` contains `when` or `should` as a whole word. */
+export declare function hasWhenOrShould(text: string): boolean;

package/dist/services/qa/bdd-test-style-contract.js

@@ -0,0 +1,37 @@
+/**
+ * `src/services/qa/bdd-test-style-contract.ts`
+ *
+ * Verdict types and pure string matchers extracted verbatim from
+ * `bdd-test-style-verifier.ts` (wave 2, file-size cap campaign) so the
+ * verifier stays under the 300 raw-line cap. Mechanical move only —
+ * the verifier re-exports every public type from its original path.
+ */
+/** Number of comment lines that make up the BDD triple (`given`/`when`/`then`). */
+const BDD_TRIPLE_SIZE = 3;
+/**
+ * Match the three leading comments against the BDD triple. Each
+ * entry must be a `// <keyword>:` line (with optional trailing
+ * whitespace); the keywords must appear in `given`, `when`, `then`
+ * order, case-insensitive.
+ */
+export function matchesBddTriple(triple) {
+    if (triple.length !== BDD_TRIPLE_SIZE)
+        return false;
+    // Each entry must be a `// <keyword>:` line, optionally followed
+    // by descriptive text. The Slice A migrator's `buildCommentBlock`
+    // produces `// given: the test setup` / `// when:  the function
+    // under test is invoked` / `// then:  the result matches the
+    // expectation` — the `when` line uses two spaces after the colon
+    // for visual alignment with `given:` and `then:`, so the regex
+    // is intentionally permissive about trailing text.
+    const patterns = [
+        /^\s*\/\/\s*given\s*:/i,
+        /^\s*\/\/\s*when\s*:/i,
+        /^\s*\/\/\s*then\s*:/i
+    ];
+    return patterns.every((pat, i) => pat.test(triple[i] ?? ''));
+}
+/** True when `text` contains `when` or `should` as a whole word. */
+export function hasWhenOrShould(text) {
+    return /(\bwhen\b|\bshould\b)/i.test(text);
+}