mandrel 2.64.0 → 2.66.0

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

@@ -1,99 +0,0 @@
-/**
- * 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';
-
-/** Measured: zero-yield closes clustered well under this size. */
-export const DEFAULT_LENS_DIFF_FLOOR = 40;
-
-/**
- * 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,
- *   headRef: string,
- *   cwd?: string,
- *   gitSpawnFn?: typeof gitSpawn,
- * }} args
- * @returns {number|null}
- */
-export function countChangedLines({
-  baseRef,
-  headRef,
-  cwd = process.cwd(),
-  gitSpawnFn = gitSpawn,
-} = {}) {
-  const rows = readNumstatRows({ baseRef, headRef, cwd, gitSpawnFn });
-  if (rows === null) return null;
-  return rows.reduce((total, row) => total + row.additions + row.deletions, 0);
-}
-
-/**
- * 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,
- *   changedLineCount?: number|null,
- *   floor?: number,
- *   injectedRules?: object,
- *   selectSensitivePathClassesFn?: typeof selectSensitivePathClasses,
- * }} [input]
- * @returns {{
- *   skip: boolean,
- *   reason: 'floor-disabled'|'line-count-unknown'|'at-or-above-floor'|'sensitive-classes-unknown'|'sensitive-path-hit'|'below-floor',
- *   floor: number,
- *   changedLineCount: number|null,
- *   sensitiveClasses: string[],
- * }}
- */
-export function evaluateLensDiffFloor(input = {}) {
-  const floorRaw = input.floor;
-  const floor =
-    typeof floorRaw === 'number' && Number.isInteger(floorRaw) && floorRaw >= 0
-      ? floorRaw
-      : DEFAULT_LENS_DIFF_FLOOR;
-  const count =
-    typeof input.changedLineCount === 'number' &&
-    Number.isFinite(input.changedLineCount) &&
-    input.changedLineCount >= 0
-      ? Math.floor(input.changedLineCount)
-      : null;
-  const verdict = (skip, reason, sensitiveClasses = []) => ({
-    skip,
-    reason,
-    floor,
-    changedLineCount: count,
-    sensitiveClasses,
-  });
-
-  if (floor <= 0) return verdict(false, 'floor-disabled');
-  if (count === null) return verdict(false, 'line-count-unknown');
-  if (count >= floor) return verdict(false, 'at-or-above-floor');
-
-  const select =
-    input.selectSensitivePathClassesFn ?? selectSensitivePathClasses;
-  let classes;
-  try {
-    classes = select({
-      changedFiles: Array.isArray(input.changedFiles) ? input.changedFiles : [],
-      injectedRules: input.injectedRules,
-    });
-  } catch {
-    return verdict(false, 'sensitive-classes-unknown');
-  }
-  const matched = Array.isArray(classes) ? classes : [];
-  if (matched.length > 0) {
-    return verdict(false, 'sensitive-path-hit', matched);
-  }
-  return verdict(true, 'below-floor');
-}

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

@@ -1,205 +0,0 @@
-/**
- * `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';
-import path from 'node:path';
-import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
-import { ValidationError } from '../errors/index.js';
-import { aggregateSummary } from './findings.js';
-import { summarizeWorkflow } from './frontmatter.js';
-import { applySubstitutions, computeAllowedKeys } from './substitutions.js';
-import { defaultWriteArtifact, loadWorkflow } from './workflow-loader.js';
-
-async function loadRules(paths) {
-  const rulesPath = path.join(
-    PROJECT_ROOT,
-    paths.schemasRoot,
-    'audit-rules.json',
-  );
-  const rulesContent = await fs.readFile(rulesPath, 'utf8');
-  return JSON.parse(rulesContent);
-}
-
-function rejectUnknownKeys(allowedKeys, callerSubstitutions) {
-  const unknownKeys = Object.keys(callerSubstitutions).filter(
-    (k) => !allowedKeys.has(k),
-  );
-  if (unknownKeys.length === 0) return;
-  const allowedList = [...allowedKeys].sort().join(', ');
-  throw new ValidationError(
-    `Unknown substitution key(s): ${unknownKeys.join(', ')}. Allowed for this call: ${allowedList}.`,
-    { unknownKeys, allowedKeys: [...allowedKeys] },
-  );
-}
-
-function emptyEnvelope(auditWorkflows) {
-  return {
-    metadata: {
-      timestamp: new Date().toISOString(),
-      auditsRequested: auditWorkflows,
-      auditsRun: [],
-      summary: { critical: 0, high: 0, medium: 0, low: 0 },
-    },
-    findings: [],
-    workflows: [],
-  };
-}
-
-function notDefinedFinding(auditName) {
-  return {
-    error: true,
-    finding: {
-      audit: auditName,
-      severity: 'low',
-      message: `Requested audit workflow '${auditName}' is not defined in audit-rules.json.`,
-    },
-  };
-}
-
-function notFoundFinding(auditName) {
-  return {
-    error: true,
-    finding: {
-      audit: auditName,
-      severity: 'low',
-      message: `Audit workflow '${auditName}.md' not found in workflows directory.`,
-    },
-  };
-}
-
-async function processAudit({
-  auditName,
-  validAudits,
-  loader,
-  workflowsDir,
-  effectiveSubstitutions,
-}) {
-  if (!validAudits.includes(auditName)) {
-    return notDefinedFinding(auditName);
-  }
-
-  const workflow = await loader(auditName, workflowsDir);
-  if (!workflow) {
-    return notFoundFinding(auditName);
-  }
-
-  const substituted = applySubstitutions(
-    workflow.content,
-    effectiveSubstitutions,
-  );
-
-  return {
-    success: true,
-    auditName,
-    workflowPath: workflow.path ?? null,
-    workflowContent: substituted,
-    summary: summarizeWorkflow(workflow.content),
-    byteSize: Buffer.byteLength(substituted, 'utf8'),
-  };
-}
-
-async function reduceResults({
-  results,
-  envelope,
-  artifactPrefix,
-  effectiveArtifactsDir,
-  writeArtifact,
-}) {
-  for (const result of results) {
-    if (result.error) {
-      envelope.findings.push(result.finding);
-      continue;
-    }
-    if (!result.success) continue;
-
-    envelope.metadata.auditsRun.push(result.auditName);
-    let artifactPath = null;
-    if (artifactPrefix) {
-      const fileName = `audit-${artifactPrefix}-${result.auditName}.md`;
-      artifactPath = await writeArtifact(
-        effectiveArtifactsDir,
-        fileName,
-        result.workflowContent,
-      );
-    }
-    envelope.workflows.push({
-      audit: result.auditName,
-      path: result.workflowPath,
-      summary: result.summary,
-      byteSize: result.byteSize,
-      artifactPath,
-    });
-  }
-}
-
-/**
- * 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
- * @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({
-  auditWorkflows,
-  substitutions,
-  artifactPrefix,
-  artifactsDir,
-  injectedLoadWorkflow,
-  injectedRules,
-  injectedWriteArtifact,
-}) {
-  const config = resolveConfig();
-  const paths = getPaths(config);
-  const callerSubstitutions = substitutions ?? {};
-  const rules = injectedRules ?? (await loadRules(paths));
-
-  const allowedKeys = computeAllowedKeys(rules, auditWorkflows);
-  rejectUnknownKeys(allowedKeys, callerSubstitutions);
-
-  const effectiveSubstitutions = {
-    auditOutputDir: paths.auditOutputDir,
-    ...callerSubstitutions,
-  };
-
-  const validAudits = Object.keys(rules.audits || {});
-  const envelope = emptyEnvelope(auditWorkflows);
-  const workflowsDir = path.join(PROJECT_ROOT, paths.workflowsRoot);
-  const effectiveArtifactsDir =
-    artifactsDir ?? path.join(PROJECT_ROOT, paths.auditOutputDir);
-  const writeArtifact = injectedWriteArtifact ?? defaultWriteArtifact;
-  const loader = injectedLoadWorkflow ?? loadWorkflow;
-
-  const results = await Promise.all(
-    auditWorkflows.map((auditName) =>
-      processAudit({
-        auditName,
-        validAudits,
-        loader,
-        workflowsDir,
-        effectiveSubstitutions,
-      }),
-    ),
-  );
-
-  await reduceResults({
-    results,
-    envelope,
-    artifactPrefix,
-    effectiveArtifactsDir,
-    writeArtifact,
-  });
-
-  envelope.metadata.summary = aggregateSummary(envelope.findings);
-  return envelope;
-}

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

@@ -1,96 +0,0 @@
-/**
- * `{{key}}` substitution for audit workflow bodies, plus the CLI glue and the
- * per-run allowed-key set.
- */
-
-import { ValidationError } from '../errors/index.js';
-
-export const BUILT_IN_SUBSTITUTION_KEYS = Object.freeze([
-  'auditOutputDir',
-  'ticketId',
-  'baseBranch',
-  // Newline-joined change set; when unsubstituted, lens templates read the
-  // literal as "no scope filter".
-  'changedFiles',
-]);
-
-function escapeRegExp(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Unrecognised placeholders are left intact; keys are validated upstream.
- *
- * @param {string} content
- * @param {Record<string, string>} substitutions
- * @returns {string}
- */
-export function applySubstitutions(content, substitutions) {
-  let out = content;
-  for (const [key, value] of Object.entries(substitutions)) {
-    out = out.replace(
-      new RegExp(`\\{\\{${escapeRegExp(key)}\\}\\}`, 'g'),
-      value,
-    );
-  }
-  return out;
-}
-
-/**
- * Throws {@link ValidationError} on a missing `=` or empty key.
- *
- * @param {string[]} [pairs]
- * @returns {Record<string, string>}
- */
-export function parseSubstitutionPairs(pairs = []) {
-  const out = {};
-  for (const entry of pairs) {
-    const eq = entry.indexOf('=');
-    if (eq <= 0) {
-      throw new ValidationError(
-        `Invalid --substitution "${entry}"; expected key=value.`,
-        { entry },
-      );
-    }
-    const key = entry.slice(0, eq);
-    const value = entry.slice(eq + 1);
-    out[key] = value;
-  }
-  return out;
-}
-
-/**
- * Fill `ticketId`/`baseBranch` from flags in place, unless an explicit
- * `--substitution` already set them.
- *
- * @param {Record<string, unknown>} values
- * @param {Record<string, string|undefined>} substitutions
- */
-export function applyImplicitSubstitutions(values, substitutions) {
-  if (values.ticket && substitutions.ticketId === undefined) {
-    substitutions.ticketId = String(values.ticket);
-  }
-  if (values['base-branch'] && substitutions.baseBranch === undefined) {
-    substitutions.baseBranch = values['base-branch'];
-  }
-}
-
-/**
- * Built-ins plus each requested audit's declared keys; unregistered audits
- * are rejected elsewhere.
- *
- * @param {{ audits?: Record<string, { substitutionKeys?: string[] }> }} rules
- * @param {string[]} auditWorkflows
- * @returns {Set<string>}
- */
-export function computeAllowedKeys(rules, auditWorkflows) {
-  const allowed = new Set(BUILT_IN_SUBSTITUTION_KEYS);
-  for (const auditName of auditWorkflows) {
-    const entry = rules.audits?.[auditName];
-    if (!entry) continue;
-    for (const k of entry.substitutionKeys ?? []) {
-      allowed.add(k);
-    }
-  }
-  return allowed;
-}

package/.agents/scripts/lib/audit-suite/workflow-loader.js

@@ -1,37 +0,0 @@
-/**
- * Filesystem IO for audit workflows, kept out of the runner so tests can
- * inject stubs.
- */
-
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-/**
- * `null` when missing; the runner records a finding rather than failing.
- *
- * @param {string} auditName
- * @param {string} workflowsDir absolute path to the workflows root
- * @returns {Promise<{ path: string, content: string } | null>}
- */
-export async function loadWorkflow(auditName, workflowsDir) {
-  const workflowPath = path.join(workflowsDir, `${auditName}.md`);
-  try {
-    const content = await fs.readFile(workflowPath, 'utf8');
-    return { path: workflowPath, content };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {string} artifactsDir
- * @param {string} fileName
- * @param {string} content
- * @returns {Promise<string>}
- */
-export async function defaultWriteArtifact(artifactsDir, fileName, content) {
-  await fs.mkdir(artifactsDir, { recursive: true });
-  const fullPath = path.join(artifactsDir, fileName);
-  await fs.writeFile(fullPath, content, 'utf8');
-  return fullPath;
-}

package/.agents/scripts/lib/orchestration/story-close/phases/local-lens-review.js

@@ -1,234 +0,0 @@
-/**
- * phases/local-lens-review.js — the Story-scope local-lens pass: selects the
- * local lenses matching the Story diff and materializes their prompts. The
- * review spine (`runStoryReviewCore`) owns diff enumeration and code review.
- */
-
-import {
-  evaluateLensDiffFloor,
-  runAuditSuite,
-  selectLocalLenses,
-} from '../../../audit-suite/index.js';
-import { gitSpawn } from '../../../git-utils.js';
-import {
-  emitRuntimeFriction,
-  RUNTIME_FRICTION_CATEGORIES,
-} from '../../../observability/runtime-friction.js';
-import { computeChangeSet } from '../../change-set.js';
-
-/** Fixed for this tier; not risk-scaled. */
-const STORY_SCOPE_LENS_DEPTH = 'light';
-
-/**
- * Roster of materialized lens-prompt artifacts the host MUST walk — the
- * default review provider never reads them, so without this they are inert.
- *
- * @param {object|null} materialized the `runAuditSuite` result envelope.
- * @returns {string|null} the roster block, or `null` when there is nothing to walk.
- */
-function renderLensArtifactRoster(materialized) {
-  const paths = (materialized?.workflows ?? [])
-    .map((w) => w?.artifactPath)
-    .filter((p) => typeof p === 'string' && p.length > 0);
-  if (paths.length === 0) return null;
-  return [
-    `Lens prompts materialized (host MUST read/walk each against the Story diff):`,
-    ...paths.map((p) => `  - ${p}`),
-  ].join('\n');
-}
-
-/**
- * Built-in substitution keys, so no per-lens declaration is needed.
- *
- * @param {{ changedFiles: string[], storyId?: number|string|null }} args
- * @returns {Record<string, string>}
- */
-function buildLensSubstitutions({ changedFiles, storyId }) {
-  const substitutions = { changedFiles: changedFiles.join('\n') };
-  if (storyId != null && `${storyId}`.length > 0) {
-    substitutions.ticketId = String(storyId);
-  }
-  return substitutions;
-}
-
-/**
- * Never throws: an unknown diff returns `[]`, which matches no lens, same as
- * an empty one.
- *
- * @param {{
- *   baseRef: string,
- *   headRef: string,
- *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
- * }} args
- * @returns {string[]} Changed file paths, or `[]` on any failure.
- */
-function enumerateChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
-  return computeChangeSet({ baseRef, headRef, gitSpawnFn }).files ?? [];
-}
-
-/**
- * Three-state injection: an array is used verbatim; `null` means the spine
- * already failed to enumerate, so don't re-spawn git; `undefined` means
- * nobody enumerated, so self-enumerate.
- *
- * @param {{
- *   changedFiles: string[]|null|undefined,
- *   baseRef: string,
- *   headRef: string,
- *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
- * }} args
- * @returns {string[]}
- */
-function resolveLensChangeSet({
-  changedFiles,
-  baseRef,
-  headRef,
-  gitSpawnFn = gitSpawn,
-}) {
-  if (changedFiles === undefined) {
-    return enumerateChangedFiles({ baseRef, headRef, gitSpawnFn });
-  }
-  return changedFiles ?? [];
-}
-
-/**
- * Run the maker-blind Story-scope lens pass (called only from
- * `runStoryReviewCore`). No matching lens → no lens work. A diff below the
- * lens diff-floor with no sensitive-path hits records the roster but skips
- * materialization; an unknown line count fails open. Advisory: any failure
- * degrades to a skipped envelope plus a friction signal.
- *
- * @param {{
- *   baseRef: string,
- *   headRef: string,
- *   changedFiles?: string[]|null,
- *   changedLineCount?: number|null,
- *   lensDiffFloor?: number,
- *   storyId?: number|string|null,
- *   artifactPrefix?: string,
- *   progress: (tag: string, msg: string) => void,
- *   progressTag?: string,
- *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
- *   selectLocalLensesFn?: typeof selectLocalLenses,
- *   runAuditSuiteFn?: typeof runAuditSuite,
- *   evaluateLensDiffFloorFn?: typeof evaluateLensDiffFloor,
- *   emitToolDegradationFn?: typeof emitRuntimeFriction,
- * }} args
- * @returns {Promise<{
- *   depth: 'light',
- *   lenses: string[],
- *   skipped: boolean,
- *   floorSkip: object|null,
- *   materialized: object|null,
- *   artifactPaths: string[],
- * }>}
- */
-export async function runLocalLensReview({
-  baseRef,
-  headRef,
-  changedFiles: injectedChangedFiles,
-  changedLineCount = null,
-  lensDiffFloor,
-  storyId,
-  artifactPrefix,
-  progress,
-  progressTag = 'CODE-REVIEW',
-  gitSpawnFn = gitSpawn,
-  selectLocalLensesFn = selectLocalLenses,
-  runAuditSuiteFn = runAuditSuite,
-  evaluateLensDiffFloorFn = evaluateLensDiffFloor,
-  emitToolDegradationFn = emitRuntimeFriction,
-}) {
-  const empty = {
-    depth: STORY_SCOPE_LENS_DEPTH,
-    lenses: [],
-    skipped: true,
-    floorSkip: null,
-    materialized: null,
-    artifactPaths: [],
-  };
-  try {
-    const changedFiles = resolveLensChangeSet({
-      changedFiles: injectedChangedFiles,
-      baseRef,
-      headRef,
-      gitSpawnFn,
-    });
-    const lenses = selectLocalLensesFn({ changedFiles });
-    if (lenses.length === 0) {
-      progress(
-        progressTag,
-        'No local lens matched the Story diff — skipping the lens pass.',
-      );
-      return empty;
-    }
-
-    // After selection so a floor-skip still records which lenses it skipped.
-    const floorVerdict = evaluateLensDiffFloorFn({
-      changedFiles,
-      changedLineCount,
-      floor: lensDiffFloor,
-    });
-    if (floorVerdict.skip) {
-      progress(
-        progressTag,
-        `Lens diff-floor: ${floorVerdict.changedLineCount} changed line(s) < ` +
-          `floor ${floorVerdict.floor} with zero sensitive-path hits — ` +
-          `skipping materialization of ${lenses.join(', ')}.`,
-      );
-      return {
-        depth: STORY_SCOPE_LENS_DEPTH,
-        lenses,
-        skipped: true,
-        floorSkip: floorVerdict,
-        materialized: null,
-        artifactPaths: [],
-      };
-    }
-    // Story-scoped names so concurrent closes can't clobber each other.
-    const effectivePrefix =
-      artifactPrefix ?? (storyId != null ? `story-${storyId}` : 'story-scope');
-    const materialized = await runAuditSuiteFn({
-      auditWorkflows: lenses,
-      substitutions: buildLensSubstitutions({ changedFiles, storyId }),
-      artifactPrefix: effectivePrefix,
-    });
-    progress(
-      progressTag,
-      `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
-    );
-    const roster = renderLensArtifactRoster(materialized);
-    if (roster) progress(progressTag, roster);
-    const artifactPaths = (materialized?.workflows ?? [])
-      .map((w) => w?.artifactPath)
-      .filter((p) => typeof p === 'string' && p.length > 0);
-    return {
-      depth: STORY_SCOPE_LENS_DEPTH,
-      lenses,
-      skipped: false,
-      floorSkip: floorVerdict,
-      materialized,
-      artifactPaths,
-    };
-  } catch (err) {
-    // Degradations are operational signals (friction), not findings.
-    progress(
-      progressTag,
-      `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
-    );
-    try {
-      await emitToolDegradationFn({
-        storyId,
-        category: RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED,
-        tool: 'local-lens-review',
-        details: {
-          surface: 'lens-materialization',
-          reason: String(err?.message ?? err).slice(0, 500),
-        },
-      });
-    } catch {
-      // Observability must never fail the close.
-    }
-    return empty;
-  }
-}