peaks-loop 4.0.54 → 4.1.1

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

@@ -23,112 +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';
 import { classifyGateEvidence } from './handoff-gate-evidence.js';
-/** Required schema version for new handoffs. */
-const HANDOFF_SCHEMA_VERSION = '2';
+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,
@@ -146,6 +64,16 @@ export function initHandoff(opts) {
         // `frontmatter.gateEvidence` key present-but-undefined for every caller
         // that declares nothing.
         ...(opts.gateEvidence === undefined ? {} : { gateEvidence: opts.gateEvidence }),
+        // The authored fields, each spread only when present. The same
+        // `exactOptionalPropertyTypes` reason as `gateEvidence` above: an absent
+        // field is absent, not present-and-undefined, so a capsule that declares
+        // nothing writes nothing — and a copy is taken so a caller mutating its own
+        // array afterwards cannot change a handoff that has already been hashed.
+        ...(opts.scope === undefined ? {} : { scope: [...opts.scope] }),
+        ...(opts.files === undefined ? {} : { files: [...opts.files] }),
+        ...(opts.decisions === undefined ? {} : { decisions: [...opts.decisions] }),
+        ...(opts.risks === undefined ? {} : { risks: [...opts.risks] }),
+        ...(opts.nextActions === undefined ? {} : { nextActions: [...opts.nextActions] })
     };
     return { frontmatter, body: opts.body };
 }
@@ -194,7 +122,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);
@@ -203,7 +131,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 };
@@ -258,34 +186,6 @@ function parseHandoffContent(content) {
         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.
@@ -319,25 +219,3 @@ function isHandoffFrontmatter(value) {
         typeof v.handoffPath === 'string' &&
         isGateEvidence(v.gateEvidence));
 }
-/**
- * B1: `gateEvidence` is optional, but when present it MUST be a map of
- * strings — an ARRAY here is the pre-B1 shape its own test file used to
- * write, and it is a broken declaration, not a claim.
- *
- * F2 of `rid-b1-qa` removed this function's own copy of the shape rule. It
- * used to be a second predicate (same boundary, different downstream result)
- * that let the same bytes read one way here and another way through
- * `readHandoffGateEvidence`; both now ask `classifyGateEvidence`. Only
- * `absent` and `ok` are accepted: a malformed declaration must be refused by
- * `readHandoff` (which is documented to throw on malformed input) exactly as
- * the reader refuses it, so the two can never disagree about the same file.
- *
- * Unknown keys are still accepted HERE — the map is normalized to the five
- * known keys by the caller — because refusing them would make a typo render
- * a whole capsule unreadable, and the reader's `unknownKeys` is the surface
- * that makes the typo diagnosable instead.
- */
-function isGateEvidence(value) {
-    const kind = classifyGateEvidence(value).kind;
-    return kind === 'absent' || kind === 'ok';
-}

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

@@ -63,7 +63,39 @@ export type GateEvidence = Readonly<Partial<Record<GateEvidenceKey, string>>>;
  * immutability: once written, peaks-rd / peaks-qa / sub-agents MUST
  * NOT mutate the on-disk copy.
  */
-export interface HandoffFrontmatter {
+/** One entry of `decisions[]` — a choice an implementer could question. */
+export type HandoffDecision = {
+    readonly id: string;
+    readonly summary: string;
+    readonly rationale: string;
+};
+/** One entry of `risks[]`. `mitigation` is required by the field rule in
+ *  `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:52`: a risk
+ *  without one is a red line, so the type has no optional form of it. */
+export type HandoffRisk = {
+    readonly id: string;
+    readonly description: string;
+    readonly mitigation: string;
+};
+/**
+ * The fields a WRITER authors and a READER cross-checks, absent when the capsule
+ * declares nothing. They were documented as required frontmatter long before the
+ * type carried them — `readHandoff` spread the parsed YAML, so an authored capsule
+ * kept them at runtime while the serializer, which renders from the TYPE, dropped
+ * them on every rewrite. That is the data loss `handoff-auto-regen` used to cause
+ * and these fields exist to end.
+ */
+export type HandoffAuthoredFields = {
+    /** Repo-relative paths this slice touches, sorted. */
+    readonly scope?: readonly string[];
+    /** Files the slice expects in its diff; peaks-qa checks this against git. */
+    readonly files?: readonly string[];
+    readonly decisions?: readonly HandoffDecision[];
+    readonly risks?: readonly HandoffRisk[];
+    /** Verb-first; what the next role does, in order. */
+    readonly nextActions?: readonly string[];
+};
+export interface HandoffFrontmatter extends HandoffAuthoredFields {
     readonly requestId: string;
     readonly sessionId: string;
     readonly schemaVersion: HandoffSchemaVersion;

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

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

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

@@ -39,30 +39,7 @@
  *   malformed test files. A parse error is a structural problem; the
  *   caller must surface it.
  */
-/** 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[];
-}
+import { type BddStyleVerdict, type VerifyBddStyleInput } from './bdd-test-style-contract.js';
 /**
  * Verify that every `it(...)` / `test(...)` call in the given test
  * files follows the BDD given-when-then contract.
@@ -86,3 +63,4 @@ export interface VerifyBddStyleInput {
  * caller maps to `qa-handoff` rejection.
  */
 export declare function verifyBddStyle(input: VerifyBddStyleInput): BddStyleVerdict;
+export type { BddStyleFailureReason, BddStyleOk, BddStyleFail, BddStyleVerdict, VerifyBddStyleInput } from './bdd-test-style-contract.js';

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

@@ -42,6 +42,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import ts from 'typescript';
+import { matchesBddTriple, hasWhenOrShould } from './bdd-test-style-contract.js';
 /** Test runners whose first string-arg is the test description. */
 const TEST_NAMES = new Set(['it', 'test']);
 /**
@@ -129,7 +130,7 @@ function checkDescription(call, sourceFile, relPath) {
             file: relPath,
             line: line + 1,
             description: '<non-literal first argument>',
-            expected: 'first argument must be a string literal containing "when" or "should"',
+            expected: 'first argument must be a string literal containing "when" or "should"'
         };
     }
     const description = firstArg.text;
@@ -142,7 +143,7 @@ function checkDescription(call, sourceFile, relPath) {
             file: relPath,
             line: line + 1,
             description,
-            expected: 'description must contain the word "when" or "should" (BDD style)',
+            expected: 'description must contain the word "when" or "should" (BDD style)'
         };
     }
     return null;
@@ -182,7 +183,7 @@ function checkBody(call, sourceFile, relPath) {
         reason: 'missing-given-when-then',
         file: relPath,
         line: line + 1,
-        expected: 'block-body callback with // given: / // when: / // then: comments at the top',
+        expected: 'block-body callback with // given: / // when: / // then: comments at the top'
     };
 }
 function getCallbackBlock(call) {
@@ -236,33 +237,6 @@ function makeMissingCommentFailure(block, sourceFile, relPath) {
         reason: 'missing-given-when-then',
         file: relPath,
         line: line + 1,
-        expected: '// given: / // when: / // then: triple at the top of the block body',
+        expected: '// given: / // when: / // then: triple at the top of the block body'
     };
 }
-/**
- * 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.
- */
-function matchesBddTriple(triple) {
-    if (triple.length !== 3)
-        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. */
-function hasWhenOrShould(text) {
-    return /(\bwhen\b|\bshould\b)/i.test(text);
-}

package/dist/services/qa/browser-event-logger.js

@@ -47,7 +47,8 @@ export class BrowserEventLogger {
         try {
             appendFileSync(this.filePath, line + '\n');
         }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        catch {
+            // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
             /* best-effort; never block the CLI on a log write */
         }
     }