mandrel 2.59.0 → 2.61.0

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({