mandrel 1.57.0

package/.agents/scripts/lib/Logger.js

@@ -0,0 +1,194 @@
+/**
+ * Logger conventions (see `docs/patterns.md` → "Error Handling Convention"):
+ *
+ *   - `debug`:  verbose trace; only emitted when the logger level is `verbose`.
+ *   - `info`:   normal progress.
+ *   - `warn`:   recoverable issue the operator should notice.
+ *   - `error`:  non-fatal failure; caller continues. Use when `throw` would
+ *               be too loud (e.g. best-effort cleanup paths).
+ *   - `fatal`:  unrecoverable; exits the process. Use only at CLI
+ *               boundaries, never inside library code.
+ *
+ * Level is resolved **lazily on every emit** from `AGENT_LOG_LEVEL` (or a
+ * `setLevel` override). Resolving per emit — rather than once at module
+ * load — lets tests exercise every level branch in-process via `setLevel`
+ * or a live `AGENT_LOG_LEVEL` flip, without spawning a child process per
+ * level (Story #3329):
+ *
+ *   - `silent`   → only `fatal` emits.
+ *   - `info`     → default. Emits `info` and above; suppresses `debug`.
+ *   - `verbose`  → emits everything (including `debug`).
+ *   - `debug`    → alias for `verbose` (backward compatible).
+ */
+/**
+ * Recognized log levels, lowest-noise first. Anything outside this set
+ * resolves to `info`.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const VALID_LEVELS = Object.freeze(
+  new Set(['silent', 'info', 'verbose', 'debug']),
+);
+
+/**
+ * Process-wide level override. `null` means "no explicit override — read
+ * `AGENT_LOG_LEVEL` from the environment on each resolve". `setLevel`
+ * pins this so tests (and embedders) can exercise every level branch
+ * in-process without spawning a child whose module-load reads a different
+ * env var. `setLevel(null)` clears the pin and restores env-driven
+ * resolution.
+ *
+ * @type {string|null}
+ */
+let levelOverride = null;
+
+/**
+ * Resolve the active log level lazily. Honors an explicit `setLevel`
+ * override first, otherwise reads `AGENT_LOG_LEVEL` from the environment
+ * on every call. Resolving per emit (rather than once at module load)
+ * means a test can flip `AGENT_LOG_LEVEL` — or call `setLevel` — and see
+ * the level branches react in-process, without a child process per level
+ * (Story #3329).
+ *
+ * @returns {'silent'|'info'|'verbose'|'debug'}
+ */
+export function resolveLevel() {
+  const raw = (
+    levelOverride ??
+    process.env.AGENT_LOG_LEVEL ??
+    ''
+  ).toLowerCase();
+  return VALID_LEVELS.has(raw) ? raw : 'info';
+}
+
+/**
+ * Pin the process-wide log level, bypassing `AGENT_LOG_LEVEL`. Pass a
+ * recognized level (`silent` / `info` / `verbose` / `debug`) to force it,
+ * or `null` to clear the pin and restore env-driven resolution. An
+ * unrecognized non-null value throws so callers cannot silently pin a
+ * level that resolves to `info`.
+ *
+ * @param {('silent'|'info'|'verbose'|'debug')|null} level
+ * @returns {void}
+ */
+export function setLevel(level) {
+  if (level === null) {
+    levelOverride = null;
+    return;
+  }
+  if (typeof level !== 'string' || !VALID_LEVELS.has(level.toLowerCase())) {
+    throw new RangeError(
+      `setLevel: level must be one of silent|info|verbose|debug or null (got ${level})`,
+    );
+  }
+  levelOverride = level.toLowerCase();
+}
+
+function debugEnabled() {
+  const level = resolveLevel();
+  return level === 'verbose' || level === 'debug';
+}
+
+function infoEnabled() {
+  return resolveLevel() === 'info' || debugEnabled();
+}
+
+// Mutable sinks for `info` (defaults to stdout via console.log) and the
+// stdout branch of `createProgress` (defaults to console.log). `warn` already
+// uses console.warn which Node routes to stderr, but we expose a sink for it
+// too so a single `routeAllOutputToStderr()` call gives a uniform guarantee
+// to callers that "no Logger output lands on stdout" (Story #2278).
+let infoSink = (msg) => console.log(msg);
+let warnSink = (msg) => console.warn(msg);
+let progressStdoutSink = (msg) => console.log(msg);
+
+/**
+ * Flip every Logger output that can land on stdout (`info`, `warn`, and the
+ * stdout branch of `createProgress`) to stderr for the lifetime of the
+ * process. Idempotent. Use when stdout is reserved for a structured payload
+ * — for example the `--emit-context` JSON envelopes emitted by
+ * `epic-plan-spec.js` and `epic-plan-decompose.js`, where any interleaved
+ * `[Orchestrator] ℹ️ …` log line corrupts the captured file
+ * (Story #2278).
+ */
+export function routeAllOutputToStderr() {
+  infoSink = (msg) => console.error(msg);
+  warnSink = (msg) => console.error(msg);
+  progressStdoutSink = (msg) => console.error(msg);
+}
+
+export const Logger = {
+  /**
+   * The currently-resolved level. A getter (not a frozen snapshot) so it
+   * reflects `setLevel` overrides and live `AGENT_LOG_LEVEL` changes —
+   * reading `Logger.level` always returns what the next emit will use.
+   */
+  get level() {
+    return resolveLevel();
+  },
+
+  debug(message) {
+    if (debugEnabled()) console.error(`[Orchestrator] 🐛 ${message}`);
+  },
+
+  info(message) {
+    if (infoEnabled()) infoSink(`[Orchestrator] ℹ️ ${message}`);
+  },
+
+  warn(message) {
+    if (infoEnabled()) warnSink(`[Orchestrator] ⚠️ ${message}`);
+  },
+
+  error(message) {
+    if (infoEnabled()) console.error(`[Orchestrator] ❌ ${message}`);
+  },
+
+  fatal(message) {
+    console.error(`[Orchestrator] ❌ ${message}`);
+    process.exit(1);
+  },
+
+  createProgress(scriptName, { stderr = true } = {}) {
+    return (phase, message) => {
+      if (!infoEnabled()) return;
+      const line = `▶ [${scriptName}] [${phase}] ${message}`;
+      if (stderr) console.error(line);
+      else progressStdoutSink(line);
+    };
+  },
+};
+
+/**
+ * Frozen no-op logger shaped like the public `Logger` surface (minus `fatal`,
+ * which must never be silenced — silencing process-exit is a footgun). Use
+ * this as the default-argument value when a function accepts an optional
+ * logger; consumers that don't pass one get a uniform shape without each
+ * call site re-declaring its own inline literal.
+ *
+ * Deliberately omits `fatal` so that any code path tempted to call
+ * `logger.fatal(...)` against the no-op fails loudly rather than silently
+ * skipping a process-exit that would otherwise have surfaced an
+ * unrecoverable error.
+ */
+export const NOOP_LOGGER = Object.freeze({
+  silent: true,
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+});
+
+/**
+ * Frozen logger that routes every level to **stderr**. Use this when a
+ * caller's stdout is a structured payload (e.g. `--emit-context` JSON
+ * envelopes from `epic-plan-spec.js` / `epic-plan-decompose.js`) and any
+ * progress/telemetry log must not interleave with the payload. Mirrors the
+ * `{ info, warn, error, debug }` shape that the orchestration helpers
+ * accept via optional `logger` arguments.
+ */
+export const STDERR_LOGGER = Object.freeze({
+  debug: (message) => console.error(message),
+  info: (message) => console.error(message),
+  warn: (message) => console.error(message),
+  error: (message) => console.error(message),
+});

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

@@ -0,0 +1,64 @@
+/**
+ * lib/audit-suite/cli.js — Argv parsing + help text for run-audit-suite.
+ *
+ * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
+ * No IO, no provider call. The entry-point composes these helpers with the
+ * runner from `./runner.js`.
+ */
+
+import { parseArgs } from 'node:util';
+
+export const HELP = `Usage: node .agents/scripts/run-audit-suite.js \\
+  --audits <comma-list> [--ticket <id>] [--base-branch main] \\
+  [--substitution key=value]... [--run-id <id>]
+
+Flags:
+  --audits         Comma-separated audit workflow names (required).
+  --ticket         Ticket id used for the {{ticketId}} substitution (optional).
+  --base-branch    Value used for the {{baseBranch}} substitution (default: main).
+  --substitution   Repeatable key=value substitution (e.g. --substitution alphaKey=val).
+                   Allowed keys are the built-ins (auditOutputDir, ticketId, baseBranch,
+                   changedFiles) plus any substitutionKeys declared on the requested audits.
+  --run-id         Optional artifact prefix. When set, full prompt bodies are written
+                   to <auditOutputDir>/audit-<run-id>-<audit>.md (defaults to
+                   temp/audits/) so downstream agents can read them.
+  --help           Show this message.
+`;
+
+/**
+ * Pure: split a comma-separated `--audits` value into a clean workflow list.
+ * Empty/whitespace tokens are dropped; nullish input yields an empty array.
+ *
+ * @param {string|null|undefined} commaList
+ * @returns {string[]}
+ */
+export function parseAuditList(commaList) {
+  return String(commaList ?? '')
+    .split(',')
+    .map((a) => a.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Parse the run-audit-suite CLI argv into a flat `values` object.
+ * `strict: false` keeps the parser permissive so callers can pass extra
+ * positional/unknown flags without aborting the run.
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, unknown>}
+ */
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      audits: { type: 'string' },
+      ticket: { type: 'string' },
+      'base-branch': { type: 'string' },
+      substitution: { type: 'string', multiple: true },
+      'run-id': { type: 'string' },
+      help: { type: 'boolean' },
+    },
+    strict: false,
+  });
+  return values;
+}

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

@@ -0,0 +1,164 @@
+/**
+ * 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.
+ */
+
+import { groupRows, resolveComponents } from '../baselines/components.js';
+
+const SEVERITIES = Object.freeze(['critical', 'high', 'medium', 'low']);
+
+/**
+ * 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.
+ *
+ * @param {Array<{ severity?: string }>|null|undefined} findings
+ * @returns {{ critical: number, high: number, medium: number, low: number }}
+ */
+export function aggregateSummary(findings) {
+  const summary = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const finding of findings ?? []) {
+    if (Object.hasOwn(summary, finding.severity)) {
+      summary[finding.severity] += 1;
+    }
+  }
+  return summary;
+}
+
+export const KNOWN_SEVERITIES = SEVERITIES;
+
+/**
+ * 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.
+ *
+ * @param {{ rollup?: object, rows?: Array<object> }} envelope
+ * @param {Record<string, string[]>} components
+ * @param {string} keyField
+ * @param {(rows: Array<object>) => Record<string, number>} [recompute]
+ * @returns {Record<string, Record<string, number>>}
+ */
+function resolveRollup(envelope, components, keyField, recompute) {
+  if (envelope?.rollup && typeof envelope.rollup === 'object') {
+    return envelope.rollup;
+  }
+  if (typeof recompute !== 'function') return { '*': {} };
+  const buckets = groupRows(envelope?.rows ?? [], components, keyField);
+  const out = {};
+  for (const [name, rows] of Object.entries(buckets)) {
+    out[name] = recompute(rows);
+  }
+  return out;
+}
+
+/**
+ * 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).
+ *
+ * @param {Record<string, number>|null|undefined} before
+ * @param {Record<string, number>|null|undefined} after
+ * @returns {Array<{ axis: string, before: number|null, after: number|null, delta: number|null }>}
+ */
+function diffAxes(before, after) {
+  const axes = new Set([
+    ...Object.keys(before ?? {}),
+    ...Object.keys(after ?? {}),
+  ]);
+  const out = [];
+  for (const axis of [...axes].sort()) {
+    const b = before?.[axis];
+    const a = after?.[axis];
+    const bNum = typeof b === 'number' && Number.isFinite(b) ? b : null;
+    const aNum = typeof a === 'number' && Number.isFinite(a) ? a : null;
+    if (bNum === aNum) continue;
+    const delta = bNum !== null && aNum !== null ? aNum - bNum : null;
+    out.push({ axis, before: bNum, after: aNum, delta });
+  }
+  return out;
+}
+
+/**
+ * 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> },
+ *   gateConfig?: object,
+ *   keyField?: string,
+ *   recompute?: (rows: Array<object>) => Record<string, number>,
+ * }} params
+ * @returns {Array<{
+ *   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 `[]`.
+ */
+export function aggregateBaselineDelta(params = {}) {
+  const before = params.before ?? { rollup: {}, rows: [] };
+  const after = params.after ?? { rollup: {}, rows: [] };
+  const components = resolveComponents(params.gateConfig);
+  const keyField =
+    typeof params.keyField === 'string' && params.keyField.length > 0
+      ? params.keyField
+      : 'path';
+
+  const beforeRollup = resolveRollup(
+    before,
+    components,
+    keyField,
+    params.recompute,
+  );
+  const afterRollup = resolveRollup(
+    after,
+    components,
+    keyField,
+    params.recompute,
+  );
+
+  const componentNames = new Set([
+    '*',
+    ...Object.keys(components),
+    ...Object.keys(beforeRollup),
+    ...Object.keys(afterRollup),
+  ]);
+
+  const entries = [];
+  for (const name of componentNames) {
+    const axes = diffAxes(beforeRollup[name], afterRollup[name]);
+    if (axes.length === 0) continue;
+    entries.push({ component: name, axes });
+  }
+
+  entries.sort((a, b) => {
+    if (a.component === '*') return -1;
+    if (b.component === '*') return 1;
+    return a.component.localeCompare(b.component);
+  });
+
+  return entries;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * lib/audit-suite/frontmatter-lint.js — workflow frontmatter linter.
+ *
+ * Lives next to `frontmatter.js` but stays in its own module so adding
+ * lints doesn't drag the summary helper's maintainability score down.
+ * Pure: no IO, no provider calls, safe to unit-test in isolation.
+ *
+ * Story #1324, Epic #1185 — Dispatch performance pass.
+ *
+ * Story #2824, Epic #2815 — Model-hint frontmatter was removed from
+ * every workflow and from the validator's field list. The function is
+ * retained as a no-op safety net so callers (and any future frontmatter
+ * lints) keep a stable entry point.
+ */
+
+import { extractFrontmatter } from './frontmatter.js';
+
+/**
+ * Pure: lint a frontmatter map (or raw workflow content). Currently a
+ * no-op — no frontmatter fields are validated after the model-hint
+ * removal. The signature is preserved so future field-level lints can
+ * slot in without churning callers.
+ *
+ * @param {string | Record<string, string>} input
+ * @returns {{ ok: boolean, errors: Array<{ field: string, value: string, message: string }> }}
+ */
+export function validateFrontmatter(input) {
+  // Extract so callers still pay the same "is this parseable?" cost as
+  // before; we just have no field-level rules to enforce right now.
+  if (typeof input === 'string') extractFrontmatter(input);
+  return { ok: true, errors: [] };
+}

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

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+
+// 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.
+// 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`);
+const PARAGRAPH_SPLIT_RE = new RegExp(String.raw`\r?\n\s*\r?\n`);
+const COLLAPSE_WS_RE = new RegExp(String.raw`\s+`, 'g');
+const SENTENCE_RE = new RegExp(String.raw`[^.!?\n]+[.!?]+`, 'g');
+// biome-ignore-end lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
+
+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.
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+export function extractFrontmatter(content) {
+  const match = FRONTMATTER_RE.exec(content);
+  if (!match) return {};
+  const fm = {};
+  for (const line of match[1].split(NEWLINE_SPLIT_RE)) {
+    const eq = line.indexOf(':');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    fm[key] = value;
+  }
+  return fm;
+}
+
+/**
+ * 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}
+ */
+export function firstProseParagraph(content) {
+  const stripped = content.replace(FRONTMATTER_RE, '');
+  for (const block of stripped.split(PARAGRAPH_SPLIT_RE)) {
+    const trimmed = block.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith('#')) continue;
+    if (trimmed.startsWith('---')) continue;
+    return trimmed.replace(COLLAPSE_WS_RE, ' ');
+  }
+  return '';
+}
+
+/**
+ * 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}
+ */
+export function clampSummary(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return '';
+  const sentences = trimmed.match(SENTENCE_RE);
+  let result = sentences
+    ? sentences.slice(0, SUMMARY_MAX_SENTENCES).join(' ').trim()
+    : trimmed;
+  if (result.length > SUMMARY_MAX_CHARS) {
+    result = `${result.slice(0, SUMMARY_MAX_CHARS - 1).trimEnd()}…`;
+  }
+  return result;
+}
+
+/**
+ * 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}
+ */
+export function summarizeWorkflow(content) {
+  const fm = extractFrontmatter(content);
+  const candidate = fm.description?.trim() || firstProseParagraph(content);
+  return clampSummary(candidate);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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`) used by the
+ * top-level CLIs (`run-audit-suite.js`, `select-audits.js`).
+ *
+ * Consumers import from this file rather than reaching upward into the
+ * CLI scripts (`../../run-audit-suite.js`, `../../select-audits.js`) —
+ * that direction inversion is the goal of Story #1083 / Epic #1072.
+ *
+ * @example
+ *   import { runAuditSuite, selectAudits } from './lib/audit-suite/index.js';
+ */
+
+export { runAuditSuite } from './runner.js';
+export {
+  matchesAnyFilePattern,
+  matchesFilePattern,
+  selectAudits,
+} from './selector.js';