mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/audit-suite/dispatch-checklist.js

@@ -1,21 +1,8 @@
 /**
- * lib/audit-suite/dispatch-checklist.js — the deliver-dispatch call site for
- * write-time checklist threading (Story #4627, activating Epic #4405's
- * Story #4410 machinery).
- *
- * `checklist-threading.js#buildChecklistPayload` was built and unit-tested but
- * had **zero production call sites**: nothing derived a footprint, assembled
- * the payload, or handed a `checklistPath` to the spawned Story worker. This
- * module is that call site. Given a Story's predicted footprint (its
- * `changes[]` / `references[]` path entries), it assembles the footprint-matched
- * local-lens checklist payload, writes it to the run's temp dir, and returns
- * the `checklistPath` the deliver-story spawn threads into the maker's prompt
- * (the same way the docs digest reaches the worker as `docsDigestPath`).
- *
- * Pure modulo the single file write, which is an injectable seam
- * (`writeFileFn`) so the builder is unit-testable without touching disk. No
- * git, no provider, no network — the footprint is the planner's *prediction*,
- * not a diff, so no repository read is involved.
+ * Deliver-dispatch call site for checklist threading: builds the payload from
+ * a Story's predicted `changes[]` + `references[]` footprint, writes it to
+ * the run temp dir, and returns the `checklistPath` the worker spawn threads.
+ * The footprint is a prediction, not a diff: no git, provider, or network.
  */
 
 import fs from 'node:fs';
@@ -23,9 +10,7 @@ import path from 'node:path';
 import { buildChecklistPayload } from './checklist-threading.js';
 
 /**
- * Extract clean path strings from a Story's `changes[]` / `references[]`
- * entries. Accepts both the parsed `{ path, assumption }` PathEntry shape and a
- * bare `string`, dropping empty / non-string entries.
+ * Accepts `{ path }` entries or bare strings.
  *
  * @param {unknown} entries
  * @returns {string[]}
@@ -39,13 +24,7 @@ function footprintFromEntries(entries) {
 }
 
 /**
- * Derive the predicted footprint the checklist matcher reads: the union of a
- * Story's `changes[]` and `references[]` path entries, in that order.
- *
- * Module-local: a detail of {@link buildDispatchChecklist}, exercised through
- * that public entry point (assert the footprint the injected payload builder
- * received) rather than imported directly, so it adds no test-only public
- * export the dead-export ratchet would flag.
+ * Module-local so it adds no test-only export for the dead-export ratchet.
  *
  * @param {{ changes?: unknown, references?: unknown }} [args]
  * @returns {string[]}
@@ -58,8 +37,6 @@ function deriveDispatchFootprint({ changes, references } = {}) {
 }
 
 /**
- * Default file writer: ensure the parent dir exists, then write the payload.
- *
  * @param {string} filePath
  * @param {string} content
  * @returns {void}
@@ -70,24 +47,16 @@ function defaultWriteFile(filePath, content) {
 }
 
 /**
- * Build the write-time checklist payload for a Story and write it to the run's
- * temp dir, returning the `checklistPath` the deliver-story spawn threads.
- *
- * When the footprint matches no local lens (the common case for a
- * docs-only or infra-only Story), nothing is written and `checklistPath` is
- * `null` — the worker then runs with no write-time checklist, exactly as it
- * does today, and lens-aware coverage still runs maker-blind at Story-scope
- * close.
+ * No matched lens → nothing written, `checklistPath: null`.
  *
  * @param {object} args
- * @param {number|string} args.storyId — names the payload file.
- * @param {unknown} [args.changes] — the Story's `changes[]` path entries.
- * @param {unknown} [args.references] — the Story's `references[]` path entries.
- * @param {string} args.runTempDir — the run temp dir the payload is written to.
- * @param {number} [args.tokenBudget] — override the payload cap.
- * @param {typeof buildChecklistPayload} [args.buildPayloadFn] — injectable seam.
- * @param {(filePath: string, content: string) => void} [args.writeFileFn] —
- *   injectable write seam (defaults to the on-disk writer).
+ * @param {number|string} args.storyId
+ * @param {unknown} [args.changes]
+ * @param {unknown} [args.references]
+ * @param {string} args.runTempDir
+ * @param {number} [args.tokenBudget]
+ * @param {typeof buildChecklistPayload} [args.buildPayloadFn]
+ * @param {(filePath: string, content: string) => void} [args.writeFileFn]
  * @returns {{
  *   checklistPath: string|null,
  *   skipped: boolean,

package/.agents/scripts/lib/audit-suite/findings.js

@@ -1,26 +1,13 @@
 /**
- * lib/audit-suite/findings.js — Findings histogram + baseline delta emitters.
- *
- * `aggregateSummary` (Story #963, Epic #946) populates the `metadata.summary`
- * block of the audit-suite envelope with a severity histogram.
- *
- * `aggregateBaselineDelta` (Task #1920, Epic #1786) reports per-component
- * rollup deltas between two committed baseline envelopes loaded via
- * `lib/baselines/reader.js`. It supersedes the prior row-by-row diff —
- * row-level deltas surfaced noise from churn that did not move any
- * component's rollup, drowning out the regressions that actually mattered.
- *
- * The delta function is **pure**: it takes the two `{ rollup, rows }`
- * envelopes returned by the reader plus the resolved components map and
- * returns a deterministic per-component delta. No filesystem I/O.
+ * Findings severity histogram and per-component baseline rollup deltas.
+ * Deltas are per rollup, not per row: row churn that moves no rollup is noise.
+ * Pure, no I/O.
  */
 
 import { groupRows, resolveComponents } from '../baselines/components.js';
 
 /**
- * Pure: count findings into a {critical,high,medium,low} histogram. Findings
- * with severities outside that set are ignored, keeping the rendered summary
- * truthful even if upstream callers append non-standard severities.
+ * Non-standard severities are ignored.
  *
  * @param {Array<{ severity?: string }>|null|undefined} findings
  * @returns {{ critical: number, high: number, medium: number, low: number }}
@@ -36,20 +23,10 @@ export function aggregateSummary(findings) {
 }
 
 /**
- * The single halting rule for the unified `verification-results` findings
- * contract (Story #4411, Epic #4405): a **surviving** (unfixed) Critical
- * finding halts the delivery gate. Every code consumer of the contract —
- * the in-process code-review producer (`runCodeReview`) and the auto-merge
- * integration gate (`evaluateAutoMergePredicate`) — routes its
- * halt-on-critical decision through this one predicate so the rule has a
- * single definition rather than a re-derived `critical > 0` expression at
- * each site.
- *
- * Accepts either the severity **count object** produced by
- * `countBySeverity` / {@link aggregateSummary} (`{ critical: n, ... }`) or a
- * raw `Finding[]`. A non-numeric / absent `critical` count (e.g. the
- * auto-merge gate's "unparseable body" sentinel `null`) is **not** a halt —
- * the caller owns that fail-open path separately. Pure; never throws.
+ * The single halting rule: a surviving Critical finding halts delivery. Every
+ * consumer routes through this rather than re-deriving `critical > 0`.
+ * Accepts a severity count object or a `Finding[]`; a non-numeric `critical`
+ * (e.g. an unparseable-body `null`) is not a halt — the caller owns that path.
  *
  * @param {{ critical?: unknown }|Array<{ severity?: string }>|null|undefined} input
  * @returns {boolean} `true` when at least one surviving Critical is present.
@@ -63,11 +40,7 @@ export function hasSurvivingCritical(input) {
 }
 
 /**
- * Resolve the per-component rollup map for an envelope. When the envelope
- * already carries a `rollup` block (every writer-produced baseline does), we
- * trust it as the source of truth. When `rollup` is absent (raw test
- * fixtures, hand-written cases) we recompute from rows via the supplied
- * `recompute` callback so the function stays useful in both shapes.
+ * The envelope's own `rollup` when present, else recomputed from rows.
  *
  * @param {{ rollup?: object, rows?: Array<object> }} envelope
  * @param {Record<string, string[]>} components
@@ -89,13 +62,8 @@ function resolveRollup(envelope, components, keyField, recompute) {
 }
 
 /**
- * Compare two component rollup objects (`{ axis: value }`) and emit one
- * delta entry per axis that differs. Pure.
- *
- * The direction is informational only — the audit emitter does not enforce
- * pass/fail policy; floor enforcement happens in `check-baselines.js`. We
- * report `before`, `after`, and the signed delta so a reviewer can read the
- * sign in context (lint count up = bad; coverage % down = bad).
+ * One entry per differing axis. Informational only — floors are enforced by
+ * `check-baselines.js`.
  *
  * @param {Record<string, number>|null|undefined} before
  * @param {Record<string, number>|null|undefined} after
@@ -120,12 +88,6 @@ function diffAxes(before, after) {
 }
 
 /**
- * Compute per-component rollup deltas between two baseline envelopes.
- *
- * Inputs are the shapes returned by `lib/baselines/reader.js#load(kind)`.
- * The function is pure — disk reads happen in the caller so the audit
- * emitter (and its tests) can drive synthetic before/after pairs.
- *
  * @param {{
  *   before: { rollup?: object, rows?: Array<object> },
  *   after:  { rollup?: object, rows?: Array<object> },
@@ -137,9 +99,7 @@ function diffAxes(before, after) {
  *   component: string,
  *   axes: Array<{ axis: string, before: number|null, after: number|null, delta: number|null }>
  * }>}
- *   One entry per component whose rollup changed. `*` always sorts first;
- *   the remainder is alpha. Components with no axis changes are omitted so
- *   an unchanged baseline yields `[]`.
+ *   Changed components only, `*` first then alpha.
  */
 export function aggregateBaselineDelta(params = {}) {
   const before = params.before ?? { rollup: {}, rows: [] };

package/.agents/scripts/lib/audit-suite/frontmatter.js

@@ -1,20 +1,10 @@
 /**
- * lib/audit-suite/frontmatter.js — Markdown frontmatter + summary helpers.
- *
- * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
- * Pure module — no IO, no provider calls, safe to unit-test in isolation.
- *
- * The functions here are the parsing seam used by the audit suite to derive
- * a 1–3-sentence summary from a workflow's `description` frontmatter field
- * (falling back to its first prose paragraph). Keep them tiny and free of
- * cross-module imports so the audit-suite entry-point stays orchestration-only.
+ * Pure frontmatter + workflow-summary helpers; keep free of cross-module
+ * imports.
  */
 
-// All RegExp instances are built via the constructor (rather than literal
-// `/.../`) so the maintainability engine's AST walker (typhonjs-escomplex) can
-// score this file. The walker has a long-standing bug where it crashes on
-// RegExp literals via `RegExpLiteral`, returning MI=0 — see the parse-time
-// fallback in lib/maintainability-engine.js#calculateForSource.
+// RegExp constructors, not literals: typhonjs-escomplex crashes on
+// `RegExpLiteral` and scores the file MI=0.
 // biome-ignore-start lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
 const FRONTMATTER_RE = new RegExp(String.raw`^---\r?\n([\s\S]*?)\r?\n---\r?\n`);
 const NEWLINE_SPLIT_RE = new RegExp(String.raw`\r?\n`);
@@ -27,9 +17,7 @@ const SUMMARY_MAX_SENTENCES = 3;
 const SUMMARY_MAX_CHARS = 280;
 
 /**
- * Pure: parse a workflow's leading `---` frontmatter block into a flat
- * key→value map. Quoted values are unwrapped; entries without a `:` separator
- * are skipped. Returns `{}` when no frontmatter is present.
+ * Flat key→value map; quotes unwrapped, `:`-less lines skipped.
  *
  * @param {string} content
  * @returns {Record<string, string>}
@@ -55,10 +43,6 @@ export function extractFrontmatter(content) {
 }
 
 /**
- * Pure: find the first prose paragraph after the frontmatter block, skipping
- * headings and `---` rules. Whitespace inside the paragraph is collapsed to
- * single spaces. Returns `''` when the body is empty / heading-only.
- *
  * @param {string} content
  * @returns {string}
  */
@@ -75,11 +59,6 @@ export function firstProseParagraph(content) {
 }
 
 /**
- * Pure: trim a candidate summary to at most three sentences and 280 chars.
- * Sentences are matched by `[^.!?\n]+[.!?]+`; bare paragraphs that contain no
- * terminator are returned verbatim (subject to the char clamp). The 280-char
- * trim appends an ellipsis to signal truncation to readers.
- *
  * @param {string} text
  * @returns {string}
  */
@@ -97,9 +76,6 @@ export function clampSummary(text) {
 }
 
 /**
- * Pure: derive a 1–3-sentence summary from a workflow's frontmatter
- * `description` field, falling back to the first prose paragraph.
- *
  * @param {string} content
  * @returns {string}
  */

package/.agents/scripts/lib/audit-suite/index.js

@@ -1,17 +1,4 @@
-/**
- * lib/audit-suite/index.js — Audit-suite SDK barrel.
- *
- * Single library entry point for the audit-suite. Exports the two public
- * functions (`runAuditSuite`, `selectAudits`) plus the pure rule-matching
- * helpers (`matchesFilePattern`, `matchesAnyFilePattern`).
- *
- * Consumers import from this file — the former top-level CLI wrappers
- * (`run-audit-suite.js`, `select-audits.js`) were retired in #4482; this
- * barrel is the only supported entry point (Story #1083 / Epic #1072).
- *
- * @example
- *   import { runAuditSuite, selectAudits } from './lib/audit-suite/index.js';
- */
+/** Audit-suite barrel — the only supported entry point. */
 
 export {
   buildChecklistPayload,
@@ -23,7 +10,6 @@ export { buildDispatchChecklist } from './dispatch-checklist.js';
 export {
   countChangedLines,
   evaluateLensDiffFloor,
-  resolveLensDiffFloor,
 } from './lens-diff-floor.js';
 export { runAuditSuite } from './runner.js';
 export {

package/.agents/scripts/lib/audit-suite/lens-checklist.js

@@ -1,34 +1,13 @@
 /**
- * lib/audit-suite/lens-checklist.js — distill an `audit-<lens>.md` workflow
- * body into a compact, drift-gated authoring checklist.
- *
- * Epic #4405 (shift-left audit) moves each lens's concerns to the innermost,
- * write-time tier: instead of an engineer only learning what a lens checks
- * when `/audit-<lens>` runs, a compact per-lens checklist ships as a committed
- * build artifact under `.agents/audit-checklists/`. This module is the pure
- * distillation seam — no IO — so it is unit-testable and the generator
- * (`generate-lens-checklists.js`) owns only the file read/write/prune and the
- * `--check` drift gate.
- *
- * The distillation is a deterministic transform of the workflow markdown: it
- * lifts the lens's *concern* labels — the bold lead-ins of the analysis /
- * evaluation list items — from the audit region of the workflow (everything
- * before the `Output Requirements` / report-template boundary), skipping the
- * recurring boilerplate sections (Role, Context, Scope, Execution strategy,
- * Configuration). When a lens exposes no bold concern items it falls back to
- * its audit-step headings so every checklist is non-empty. The output is
- * hard-capped at {@link MAX_CHECKLIST_LINES} lines.
- *
- * Pure: no IO, no provider calls, safe to unit-test in isolation.
- *
- * @see Story #4408 — per-lens authoring checklists as drift-gated artifacts.
+ * Pure distillation of an `audit-<lens>.md` workflow into the committed,
+ * drift-gated authoring checklist (the generator owns I/O). Lifts bold
+ * concern lead-ins from the audit region, skipping boilerplate sections and
+ * stopping at the report-template boundary; falls back to step headings.
  */
 
 import { clampSummary, extractFrontmatter } from './frontmatter.js';
 
-// All RegExp instances are built via the constructor (rather than literal
-// `/.../`) so the maintainability engine's AST walker (typhonjs-escomplex) can
-// score this file — see the note in lib/audit-suite/frontmatter.js.
+// RegExp constructors, not literals: typhonjs-escomplex crashes on literals.
 // biome-ignore-start lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
 const LINE_SPLIT_RE = new RegExp(String.raw`\r?\n`);
 const FRONTMATTER_BLOCK_RE = new RegExp(
@@ -44,14 +23,11 @@ const BOLD_LEAD_ITEM_RE = new RegExp(
 );
 const STEP_PREFIX_RE = new RegExp(String.raw`^Step\s+\d+\s*[:.]?\s*`, 'i');
 const TRAILING_COLON_RE = new RegExp(String.raw`\s*:\s*$`);
-// A `##` section whose heading opens with one of these is workflow boilerplate,
-// not a lens concern — its list items are skipped during concern extraction.
 const BOILERPLATE_SECTION_RE = new RegExp(
   String.raw`^(Role|Context & Objective|Scope|Execution strategy|Configuration|Run Context|Target set)\b`,
   'i',
 );
-// The report-template / output-contract boundary. Everything at or after the
-// first heading matching this is template scaffolding, never a concern.
+// Everything from this heading on is report-template scaffolding.
 const OUTPUT_BOUNDARY_RE = new RegExp(
   '(Output Requirements|Generate the Report)',
   'i',
@@ -61,15 +37,9 @@ const OUTPUT_BOUNDARY_RE = new RegExp(
 /** Hard cap on generated checklist lines (asserted by the drift test). */
 export const MAX_CHECKLIST_LINES = 40;
 
-/** Fixed header/intro line budget consumed before the checklist items. */
 const HEADER_LINE_BUDGET = 12;
 
 /**
- * Pure: walk the workflow body once, collecting the lens's concern labels (bold
- * lead-ins of analysis/evaluation list items) and, as a fallback, its audit
- * step headings. Extraction stops at the report-template boundary and ignores
- * boilerplate sections.
- *
  * @param {string} content — raw `audit-<lens>.md` markdown.
  * @returns {{ title: string|null, concerns: string[], stepHeadings: string[] }}
  */
@@ -114,10 +84,8 @@ export function extractLensConcerns(content) {
 }
 
 /**
- * Pure: resolve a workflow's `description` to a single clamped line, folding a
- * YAML block scalar (`description: >-` / `|` with indented continuation lines)
- * back into one line. `extractFrontmatter` only sees the indicator token
- * (`>-`) for a block scalar, so this reads the continuation lines directly.
+ * One clamped description line; folds a YAML block scalar, whose indicator
+ * token is all `extractFrontmatter` sees.
  *
  * @param {string} content — raw workflow markdown.
  * @param {Record<string, string>} fm — parsed frontmatter map.
@@ -146,7 +114,7 @@ export function resolveDescription(content, fm) {
 }
 
 /**
- * Pure: dedupe a list case-insensitively, preserving first-seen order.
+ * Case-insensitive, first-seen order.
  *
  * @param {string[]} items
  * @returns {string[]}
@@ -164,10 +132,7 @@ function dedupePreserveOrder(items) {
 }
 
 /**
- * Pure: render the authoring checklist for a single lens from its workflow
- * markdown. The output is deterministic (a pure function of `content`) and
- * hard-capped at {@link MAX_CHECKLIST_LINES} lines including the trailing
- * newline, so the same input always regenerates byte-identically.
+ * Deterministic, capped at {@link MAX_CHECKLIST_LINES} lines.
  *
  * @param {string} lens — canonical lens name (e.g. `security`).
  * @param {string} content — raw `audit-<lens>.md` markdown.

package/.agents/scripts/lib/audit-suite/lens-diff-floor.js

@@ -1,74 +1,22 @@
 /**
- * lib/audit-suite/lens-diff-floor.js — the close-scope lens diff-floor
- * (Story #4699).
- *
- * ## Why this exists
- *
- * The Story-scope local-lens pass materialized ~28 KB of lens prompts per
- * close while sampled closes yielded almost zero findings — and none above
- * Suggestion severity. The cheapest correct response is a deterministic
- * floor: a *small* diff that touches *no* sensitive path earns no lens
- * materialization at all. The floor is measured in **changed lines**
- * (additions + deletions across the diff), configured via
- * `delivery.review.lensDiffFloor` (default {@link DEFAULT_LENS_DIFF_FLOOR};
- * `0` disables the skip entirely).
- *
- * ## Fail-open contract
- *
- * The skip only fires on positive evidence that the diff is small and
- * non-sensitive. Every degraded input — an unknown line count, an
- * unreadable manifest, a disabled floor — resolves to "do not skip", so a
- * measurement failure can never buy a change less review. Sensitive-path
- * hits are matched with the same `sensitivePaths` classes the review-depth
- * derivation reads (`selectSensitivePathClasses`), so the floor and the
- * depth tiering can never disagree about what "sensitive" means.
- *
- * All exports are total: no throws, no I/O beyond the injected git spawn in
- * {@link countChangedLines}.
+ * Close-scope lens diff-floor: a diff under the changed-line floor that
+ * touches no sensitive path skips lens materialization. Fail-open — every
+ * degraded input (unknown count, unreadable manifest, floor `0`) means "do
+ * not skip". Sensitive classes come from the same selector as review depth,
+ * so the two never disagree. Total; no I/O beyond the injected git spawn.
  */
 
 import { gitSpawn } from '../git-utils.js';
 import { readNumstatRows } from '../orchestration/diff-magnitude.js';
 import { selectSensitivePathClasses } from './selector.js';
 
-/**
- * Default changed-line floor below which a non-sensitive diff skips lens
- * materialization. Chosen from the measured distribution (Story #4699): the
- * sampled zero-yield closes clustered well under this size.
- */
+/** Measured: zero-yield closes clustered well under this size. */
 export const DEFAULT_LENS_DIFF_FLOOR = 40;
 
 /**
- * Resolve the configured lens diff-floor from a resolved config wrapper.
- * `delivery.review.lensDiffFloor` must be a non-negative integer; anything
- * else (absent block, wrong type, negative, non-finite) falls back to
- * {@link DEFAULT_LENS_DIFF_FLOOR}. `0` is a valid, deliberate "floor off".
- *
- * @param {object|null|undefined} config Resolved `.agentrc.json` wrapper.
- * @returns {number}
- */
-export function resolveLensDiffFloor(config) {
-  const value = config?.delivery?.review?.lensDiffFloor;
-  if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
-    return value;
-  }
-  return DEFAULT_LENS_DIFF_FLOOR;
-}
-
-/**
- * Count the changed lines (additions + deletions) in the
- * `baseRef...headRef` diff via `git diff --numstat`.
- *
- * The read and the parse are shared with the light path's magnitude backstop
- * ({@link module:lib/orchestration/diff-magnitude.readNumstatRows}) so the two
- * cannot disagree about how a diff is measured. This one keeps a whole-diff
- * total: the lens floor asks "is this diff small", not "is its implementation
- * half small", so it deliberately does **not** apply the companion exemption.
- *
- * Total — never throws. Returns `null` (the neutral "count unknown" signal
- * the floor fails open on) for any git failure or unparseable output, and
- * `0` for a genuinely empty diff. Binary rows (`-\t-\tpath`) contribute 0
- * text lines but do not poison the parse.
+ * Whole-diff additions + deletions (no companion exemption: the question is
+ * "is this diff small"). Shares the numstat parse with the light path's
+ * backstop. `null` on any git failure; binary rows count 0.
  *
  * @param {{
  *   baseRef: string,
@@ -90,20 +38,8 @@ export function countChangedLines({
 }
 
 /**
- * Decide whether the close-scope lens pass should skip materialization for
- * this diff. Skips **only** when all of the following hold:
- *
- *   1. The floor is enabled (`floor > 0`).
- *   2. The changed-line count is *known* and strictly below the floor.
- *   3. The changed-file set intersects **zero** registered sensitive-path
- *      classes (`audit-rules.json#sensitivePaths`).
- *
- * Every other state — floor disabled, unknown count, at-or-above floor, a
- * sensitive-path hit — resolves to `skip: false` with a named reason, so
- * the verdict is auditable in the findings-yield ledger.
- *
- * Pure and total: never throws (a throwing sensitive-path matcher degrades
- * to "not skippable").
+ * Skip only when the floor is enabled, the count is known and below it, and
+ * no sensitive-path class matches; every other state names its reason.
  *
  * @param {{
  *   changedFiles?: string[]|null,
@@ -153,7 +89,6 @@ export function evaluateLensDiffFloor(input = {}) {
       injectedRules: input.injectedRules,
     });
   } catch {
-    // An unreadable manifest is not evidence the change is safe to skip.
     return verdict(false, 'sensitive-classes-unknown');
   }
   const matched = Array.isArray(classes) ? classes : [];

package/.agents/scripts/lib/audit-suite/runner.js

@@ -1,20 +1,6 @@
 /**
- * lib/audit-suite/runner.js — `runAuditSuite` aggregation core.
- *
- * Extracted from the former `run-audit-suite.js` CLI (Story #963, Epic #946;
- * the CLI wrapper itself was retired in #4482 — `runAuditSuite` via the
- * barrel is the only supported entry point).
- *
- * The runner composes the focused helpers from this directory:
- *   - frontmatter.js     → `summarizeWorkflow`
- *   - substitutions.js   → `applySubstitutions`, `computeAllowedKeys`
- *   - findings.js        → `aggregateSummary`
- *   - workflow-loader.js → `loadWorkflow`, `defaultWriteArtifact`
- *
- * It owns the audit envelope shape (`metadata`, `findings`, `workflows`) and
- * the per-audit fan-out + result reduction. The former CLI entry-point
- * (`run-audit-suite.js`) was retired in #4482; callers invoke
- * `runAuditSuite` via the `lib/audit-suite/index.js` barrel.
+ * `runAuditSuite`: owns the audit envelope shape (`metadata`, `findings`,
+ * `workflows`) and the per-audit fan-out; invoked via the barrel.
  */
 
 import fs from 'node:fs/promises';
@@ -149,35 +135,19 @@ async function reduceResults({
 }
 
 /**
- * Run a suite of named audit workflows.
- *
- * For each audit name the suite will:
- *   1. Validate it is registered in audit-rules.json.
- *   2. Locate the corresponding `.agents/workflows/<auditName>.md` file.
- *   3. Return a slim `workflow` descriptor (audit name, source path, summary,
- *      byte size) for the calling AI agent. Full prompt bodies are written to
- *      `<auditOutputDir>/audit-<runId>-<audit>.md` (resolved from
- *      `project.paths.tempRoot`, default `temp/audits/`) when `artifactPrefix`
- *      (or `runId`) is provided, so downstream agents can read them locally
- *      without bloating the GitHub comment surface.
- *
- * Substitutions: callers may pass a `substitutions` map of `{{key}}` → value
- * pairs. Allowed keys are the built-ins (auditOutputDir, ticketId, baseBranch,
- * changedFiles) plus any `substitutionKeys` declared on the requested audits in
- * audit-rules.json, aggregated across auditWorkflows. Unknown keys
- * raise a ValidationError.
+ * Resolve registered audit workflows into slim descriptors; with
+ * `artifactPrefix`, full bodies are written to disk instead of travelling in
+ * the envelope. Substitution keys beyond the built-ins must be declared as
+ * `substitutionKeys` in audit-rules.json, else ValidationError.
  *
  * @param {object} opts
- * @param {string[]} opts.auditWorkflows - List of audit names to run.
- * @param {Record<string,string>} [opts.substitutions] - Optional template substitutions.
- * @param {string} [opts.artifactPrefix] - When set, write full bodies to
- *   `<artifactsDir>/audit-<artifactPrefix>-<audit>.md`.
- * @param {string} [opts.artifactsDir] - Override the artifacts directory
- *   (default: `<PROJECT_ROOT>/<auditOutputDir>`, which resolves to
- *   `<tempRoot>/audits` — `temp/audits` with default config).
- * @param {Function} [opts.injectedLoadWorkflow] - Optional override for testing.
- * @param {object} [opts.injectedRules] - Optional override for the audit-rules content (testing).
- * @param {Function} [opts.injectedWriteArtifact] - Optional override for filesystem-free testing.
+ * @param {string[]} opts.auditWorkflows
+ * @param {Record<string,string>} [opts.substitutions]
+ * @param {string} [opts.artifactPrefix] - writes `audit-<prefix>-<audit>.md`.
+ * @param {string} [opts.artifactsDir] - defaults to `<auditOutputDir>`.
+ * @param {Function} [opts.injectedLoadWorkflow]
+ * @param {object} [opts.injectedRules]
+ * @param {Function} [opts.injectedWriteArtifact]
  * @returns {Promise<object>} Aggregated audit results.
  */
 export async function runAuditSuite({