mandrel 2.22.0 → 2.24.0

package/.agents/scripts/lib/orchestration/diff-magnitude.js

@@ -0,0 +1,283 @@
+/**
+ * lib/orchestration/diff-magnitude.js — the changed-line magnitude of a diff,
+ * split into implementation and mandated-companion halves (Story #4856).
+ *
+ * ## Why magnitude, and why the split
+ *
+ * The light path's diff backstop used to bound scope with a single
+ * `maxFiles: 4` ceiling. Measured against this repository's own history that
+ * ceiling was wrong in both directions:
+ *
+ *   - **Too tight.** Of 33 real-work squash merges on `main` (excluding
+ *     release-please and `chore(baselines)` automation) only 7 — 21% — touch
+ *     four files or fewer; the median is 8. The framework's *own* narrow-diff
+ *     scale, `DEFAULT_DIFF_WIDTH.softFiles` in `review-depth.js`, is 15.
+ *   - **Blind.** A three-file, 323-line rewrite passed while a 190-file change
+ *     was rejected 47× over — even though 186 of those files were tests and its
+ *     implementation was 7 files.
+ *
+ * So the axis is **changed lines over implementation files**, and the companion
+ * classes the framework itself mandates are exempt from the count: obeying
+ * `rules/testing-standards.md` (test-first), the `delivery.docsFreshness` gate,
+ * and the baseline ratchets must not inflate the number that then rejects the
+ * change. Re-counting those same 33 merges on implementation files alone moves
+ * the four-file pass rate from 21% to 58%.
+ *
+ * ## Three contracts worth not rediscovering
+ *
+ *   1. **Additions plus deletions, never net.** A modified line counts twice
+ *      (one `+`, one `-`), which is the intended weighting. Net is actively
+ *      broken as a size signal: the merge retiring the planner snapshot is
+ *      1119 add+del but **−803** net, so a large deletion would measure as
+ *      trivial.
+ *   2. **A pure rename is free.** `git diff --numstat` reports `0\t0` for one,
+ *      and its path arrives in `old => new` form — normalized here to the
+ *      destination so the file still counts toward the implementation tally.
+ *   3. **Exemption is from *counting*, never from *risk*.** Nothing here
+ *      touches sensitive-path derivation, which every caller runs over the
+ *      full changed set including companions.
+ *
+ * Companion matching runs through the audit suite's picomatch seam as a
+ * **positive** glob list negated by the caller. A `!`-prefixed picomatch
+ * pattern widens a match rather than narrowing it, so expressing the
+ * behavior-bearing exceptions as negations would silently exempt more than
+ * intended.
+ *
+ * Every export is total: no throws. {@link readNumstatRows} owns the one git
+ * read; everything else is pure.
+ *
+ * The public surface is deliberately just those two functions. The numstat
+ * parse, the rename normalization, and the companion classifier are internal:
+ * each is fully observable through them (a stubbed `gitSpawnFn` drives the
+ * parse, an `isCompanionFn` seam drives the classification), so exporting them
+ * would widen the module's contract for no caller.
+ *
+ * @module lib/orchestration/diff-magnitude
+ */
+
+import { matchesAnyFilePattern } from '../audit-suite/selector.js';
+import { gitSpawn } from '../git-utils.js';
+
+/**
+ * Paths whose churn is a **mandated companion** of a change rather than the
+ * change itself, exempt from the implementation line and file counts.
+ *
+ * Deliberately absent, and load-bearing in their absence: `.agentrc.json`,
+ * `.agents/schemas/**`, `.github/workflows/**`, and `package.json`. Those are
+ * "config" by file type but behavior by effect, and `.agents/schemas/audit-rules.json`
+ * is the sensitive-path SSOT — exempting it would let a change widen the very
+ * allowlist that decides whether it is risky.
+ *
+ * Note the anchoring: `baselines/**` is the generated baseline **data** at the
+ * repository root. The baseline *schemas* under `.agents/schemas/baselines/`
+ * are unanchored by this pattern and therefore still count as implementation.
+ *
+ * Markdown is exempt wholesale, which includes `.agents/workflows/**` and
+ * `.agents/rules/**`. That is intended: rewriting a workflow contract is not
+ * *effort* the way a module rewrite is, and its real guards are the close-time
+ * context-budget, doc-link, and docs-reference-sync gates — none of which this
+ * ceiling replaces.
+ */
+const COMPANION_PATH_GLOBS = Object.freeze([
+  // Tests — mandated by rules/testing-standards.md's test-first discipline.
+  '**/__tests__/**',
+  '**/*.test.js',
+  '**/*.test.mjs',
+  '**/*.test.cjs',
+  '**/*.test.ts',
+  '**/*.test.tsx',
+  'tests/**',
+  'features/**',
+  // Documentation — mandated by the delivery.docsFreshness gate.
+  'docs/**',
+  '**/*.md',
+  // Generated baseline data — written by the ratchets, not hand-authored.
+  'baselines/**',
+  // Lockfiles — regenerated wholesale; their line count means nothing.
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+]);
+
+/**
+ * Normalize a `git diff --numstat` path field to the single file it names.
+ * Rename rows arrive as `old => new` or with a braced infix
+ * (`dir/{old => new}/file.js`); both resolve to the destination, so a renamed
+ * implementation file still counts as one implementation file.
+ *
+ * Pure and total.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeNumstatPath(raw) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value === '') return '';
+  const braced = /^(.*)\{(.*) => (.*)\}(.*)$/.exec(value);
+  if (braced) {
+    const [, prefix, , to, suffix] = braced;
+    return `${prefix}${to}${suffix}`.replace(/\/{2,}/g, '/');
+  }
+  const arrow = value.split(' => ');
+  return (arrow.length > 1 ? arrow[arrow.length - 1] : value).trim();
+}
+
+/**
+ * Parse `git diff --numstat` output into per-file rows.
+ *
+ * Binary rows (`-\t-\tpath`) contribute zero text lines without poisoning the
+ * parse. Any line that does not match the numstat shape makes the whole result
+ * untrustworthy, so the function returns `null` — the "magnitude unknown"
+ * signal every caller fails closed (or fails open) on deliberately.
+ *
+ * Pure and total.
+ *
+ * @param {unknown} stdout
+ * @returns {Array<{ additions: number, deletions: number, path: string }>|null}
+ */
+function parseNumstatRows(stdout) {
+  if (typeof stdout !== 'string') return null;
+  const rows = [];
+  for (const line of stdout.split('\n')) {
+    const trimmedEnd = line.replace(/\s+$/, '');
+    if (trimmedEnd.length === 0) continue;
+    const match = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(trimmedEnd);
+    if (!match) return null;
+    rows.push({
+      additions: match[1] === '-' ? 0 : Number(match[1]),
+      deletions: match[2] === '-' ? 0 : Number(match[2]),
+      path: normalizeNumstatPath(match[3]),
+    });
+  }
+  return rows;
+}
+
+/**
+ * True when `file` is a mandated companion rather than implementation.
+ *
+ * Pure and total — a throwing matcher resolves to `false`, which counts the
+ * file as implementation. That is the conservative direction: a
+ * classification failure must never shrink the measured magnitude.
+ *
+ * @param {unknown} file
+ * @param {{ matchFn?: typeof matchesAnyFilePattern }} [deps]
+ * @returns {boolean}
+ */
+function isCompanionPath(file, { matchFn = matchesAnyFilePattern } = {}) {
+  if (typeof file !== 'string' || file.trim() === '') return false;
+  try {
+    return matchFn(COMPANION_PATH_GLOBS, [file.trim()]) === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the per-file numstat rows for the `baseRef...headRef` diff. The one
+ * side-effecting function in this module.
+ *
+ * Total — never throws; returns `null` on any git failure or unparseable
+ * output.
+ *
+ * @param {{
+ *   baseRef?: string,
+ *   headRef?: string,
+ *   cwd?: string,
+ *   gitSpawnFn?: typeof gitSpawn,
+ * }} [args]
+ * @returns {Array<{ additions: number, deletions: number, path: string }>|null}
+ */
+export function readNumstatRows({
+  baseRef,
+  headRef,
+  cwd = process.cwd(),
+  gitSpawnFn = gitSpawn,
+} = {}) {
+  if (typeof baseRef !== 'string' || baseRef.length === 0) return null;
+  if (typeof headRef !== 'string' || headRef.length === 0) return null;
+  try {
+    const result = gitSpawnFn(
+      cwd,
+      'diff',
+      '--numstat',
+      `${baseRef}...${headRef}`,
+    );
+    if (!result || result.status !== 0) return null;
+    return parseNumstatRows(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Summarize a diff's magnitude, splitting implementation from mandated
+ * companions.
+ *
+ * `implFiles` is counted from `changedFiles` — the canonical
+ * `git diff --name-only` enumeration produced by `change-set.js` — rather than
+ * from the numstat rows, so file counting uses clean paths from the one
+ * enumerator every other consumer reads. `implLines` comes from the numstat
+ * rows, which is the only surface carrying line counts.
+ *
+ * Returns `null` when either input is unusable: the magnitude is then *unknown*,
+ * which is deliberately distinct from *zero* so a caller can fail closed on the
+ * absence of evidence.
+ *
+ * Pure and total.
+ *
+ * @param {{
+ *   changedFiles?: unknown,
+ *   rows?: unknown,
+ *   isCompanionFn?: typeof isCompanionPath,
+ * }} [args]
+ * @returns {{
+ *   implFiles: number,
+ *   implLines: number,
+ *   companionFiles: number,
+ *   companionLines: number,
+ *   totalFiles: number,
+ * }|null}
+ */
+export function summarizeDiffMagnitude({
+  changedFiles,
+  rows,
+  isCompanionFn = isCompanionPath,
+} = {}) {
+  if (!Array.isArray(changedFiles) || !Array.isArray(rows)) return null;
+  const files = changedFiles.filter(
+    (f) => typeof f === 'string' && f.trim() !== '',
+  );
+
+  // A classification failure resolves to "implementation" — the conservative
+  // direction, since counting a companion as implementation can only ever make
+  // the measured magnitude larger. Guarded here as well as inside the default
+  // classifier so an injected one cannot break this function's totality.
+  const isCompanion = (file) => {
+    try {
+      return isCompanionFn(file) === true;
+    } catch {
+      return false;
+    }
+  };
+
+  let implFiles = 0;
+  for (const file of files) {
+    if (!isCompanion(file)) implFiles += 1;
+  }
+
+  let implLines = 0;
+  let companionLines = 0;
+  for (const row of rows) {
+    const lines = (row?.additions ?? 0) + (row?.deletions ?? 0);
+    if (isCompanion(row?.path)) companionLines += lines;
+    else implLines += lines;
+  }
+
+  return {
+    implFiles,
+    implLines,
+    companionFiles: files.length - implFiles,
+    companionLines,
+    totalFiles: files.length,
+  };
+}

package/.agents/scripts/lib/orchestration/light-backstop.js

@@ -0,0 +1,107 @@
+/**
+ * lib/orchestration/light-backstop.js — the light path's diff-backstop pass
+ * (Story #4856).
+ *
+ * The backstop is invariant 3 of the light path: after implementation the
+ * **actual** change set is re-checked, because the diff — not the prompt — is
+ * the real scope signal. This module owns that pass end to end so
+ * `deliver-light.js` stays the thin CLI shell it claims to be: it reads the two
+ * git surfaces, applies
+ * {@link module:lib/orchestration/light-suitability.checkLightDiffBackstop},
+ * and resolves what a refusal means.
+ *
+ * ## Two git surfaces, each used for what it reports reliably
+ *
+ *   - `--name-only`, via the one canonical `computeChangeSet` enumerator, gives
+ *     the clean full file list. Sensitive-path derivation and
+ *     implementation-file counting both read it, so the backstop and every
+ *     other consumer are looking at the same change set.
+ *   - `--numstat` gives per-file line counts, the only surface carrying them.
+ *
+ * @module lib/orchestration/light-backstop
+ */
+
+import { computeChangeSet } from './change-set.js';
+import { readNumstatRows, summarizeDiffMagnitude } from './diff-magnitude.js';
+import { handleBlockedBackstop } from './light-escalation.js';
+import { checkLightDiffBackstop } from './light-suitability.js';
+
+/** Exit code when the diff backstop blocked the land. */
+const EXIT_BACKSTOP_BLOCKED = 3;
+
+/**
+ * Run the diff backstop against a Story branch's actual change set.
+ *
+ * @param {{
+ *   storyId: number,
+ *   baseRef?: string,
+ *   cwd?: string,
+ *   computeFn?: typeof computeChangeSet,
+ *   readRowsFn?: typeof readNumstatRows,
+ *   injectedRules?: object,
+ * }} args
+ * @returns {ReturnType<typeof checkLightDiffBackstop>}
+ */
+function runDiffBackstop({
+  storyId,
+  baseRef = 'main',
+  cwd = process.cwd(),
+  computeFn = computeChangeSet,
+  readRowsFn = readNumstatRows,
+  injectedRules,
+} = {}) {
+  const headRef = `story-${storyId}`;
+  const { files } = computeFn({ baseRef, headRef, cwd });
+  const rows = readRowsFn({ baseRef, headRef, cwd });
+  const magnitude = summarizeDiffMagnitude({ changedFiles: files, rows });
+  return checkLightDiffBackstop({
+    changedFiles: files,
+    magnitude,
+    injectedRules,
+  });
+}
+
+/**
+ * Resolve the backstop pass into everything the CLI needs to print and exit
+ * with: the verdict, the recycle command on a refusal (`null` when clean), the
+ * exit code, and the log line.
+ *
+ * @param {{
+ *   storyId: number,
+ *   runFn?: typeof runDiffBackstop,
+ *   handleBlockedFn?: typeof handleBlockedBackstop,
+ * }} args Any further keys (`baseRef`, `cwd`, `computeFn`, `readRowsFn`,
+ *   `injectedRules`) forward to the backstop run, so the git-surface join is
+ *   drivable through this one entry point.
+ * @returns {Promise<{
+ *   result: ReturnType<typeof checkLightDiffBackstop>,
+ *   nextCommand: string|null,
+ *   exitCode: number,
+ *   message: string,
+ * }>}
+ */
+export async function resolveBackstopOutcome({
+  storyId,
+  runFn = runDiffBackstop,
+  handleBlockedFn = handleBlockedBackstop,
+  ...seams
+} = {}) {
+  const result = runFn({ storyId, ...seams });
+  if (!result.blocked) {
+    return {
+      result,
+      nextCommand: null,
+      exitCode: 0,
+      message: `[deliver-light] diff backstop clean for Story #${storyId}.`,
+    };
+  }
+  const nextCommand = await handleBlockedFn({ storyId, result });
+  return {
+    result,
+    nextCommand,
+    exitCode: EXIT_BACKSTOP_BLOCKED,
+    message:
+      `[deliver-light] diff backstop BLOCKED Story #${storyId}: ` +
+      `${result.reasons.join('; ')} — recycle the receipt with "${nextCommand}"`,
+  };
+}

package/.agents/scripts/lib/orchestration/light-escalation.js

@@ -0,0 +1,169 @@
+/**
+ * lib/orchestration/light-escalation.js — what the light path does when it
+ * refuses a scope (Story #4856).
+ *
+ * Two behaviors, both previously missing, and both about a refusal rather than
+ * a verdict — the verdicts live in
+ * {@link module:lib/orchestration/light-suitability}:
+ *
+ *   1. **Recycling the receipt.** A blocked diff backstop used to tell the
+ *      operator to "escalate to `/plan`", which authored a brand-new Story and
+ *      left the receipt open with no successor — orphaning its branch, its
+ *      worktree, and a finished implementation. Naming the receipt as `/plan`'s
+ *      *input* recycles it instead: tickets mode already fetches a ticket,
+ *      rewrites it into properly-planned Stories, and closes the source as
+ *      superseded.
+ *
+ *      Deferring receipt creation until after the backstop would be the other
+ *      fix, and is deliberately not taken: the issue id is load-bearing in
+ *      `single-story-init.js` (the assignee lease, the `story-<id>` branch, the
+ *      label state machine) and in the `(refs #<id>)` commit subject.
+ *
+ *   2. **Telemetering the refusal.** Neither light-path rejection emitted any
+ *      signal, so an over-tight ceiling could only reach the framework as
+ *      anecdote — which is exactly how the `maxFiles: 4` defect surfaced. The
+ *      roll-up aggregates by category, so recording these makes the ceilings
+ *      recalibratable from evidence.
+ *
+ * Telemetry is best-effort by construction: a signals-write failure must never
+ * change a gate's verdict.
+ *
+ * @module lib/orchestration/light-escalation
+ */
+
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../observability/runtime-friction.js';
+
+/**
+ * The `/plan` invocation that owns a Story the light path could not land.
+ *
+ * @param {number} storyId
+ * @returns {string}
+ */
+function buildRecycleCommand(storyId) {
+  return `/plan ${storyId}`;
+}
+
+/**
+ * Coerce an `--amends` argument (`#123` or `123`) into a positive integer issue
+ * number, or `null` when absent/malformed.
+ *
+ * This is the only Story context a **gate-stage** rejection can legitimately
+ * claim: the signals stream is keyed on a Story id, and an `ask-operator` gate
+ * has authored no receipt yet — deliberately, since not creating one is the
+ * point of that outcome. A bare prompt's rejection therefore has no stream to
+ * land in, and attributing it to a fabricated id would be worse than recording
+ * nothing.
+ *
+ * @param {unknown} amends
+ * @returns {number|null}
+ */
+function normalizeAmendsId(amends) {
+  const match = /^#?(\d+)$/.exec(String(amends ?? '').trim());
+  if (!match) return null;
+  const n = Number.parseInt(match[1], 10);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Record a suitability-gate refusal (`ask-operator`) as friction, attributed to
+ * the `--amends` target when there is one.
+ *
+ * @param {{
+ *   gate: object,
+ *   amends?: unknown,
+ *   recordFrictionFn?: typeof recordScopeFriction,
+ * }} args
+ * @returns {Promise<boolean>}
+ */
+export async function recordGateRefusal({
+  gate,
+  amends,
+  emitFn,
+  recordFrictionFn = recordScopeFriction,
+} = {}) {
+  return recordFrictionFn({
+    emitFn,
+    storyId: normalizeAmendsId(amends),
+    surface: 'suitability-gate',
+    reasons: gate?.outcome?.reasons ?? [],
+    details: {
+      action: gate?.action ?? null,
+      code: gate?.suitability?.shape?.code ?? null,
+    },
+  });
+}
+
+/**
+ * Handle a blocked diff backstop: record the refusal as friction and return the
+ * `/plan` invocation that recycles the receipt.
+ *
+ * Lives here rather than in the CLI so the shell stays a shell — the backstop
+ * mode's job is to branch and print, not to decide what a refusal means.
+ *
+ * @param {{
+ *   storyId: number,
+ *   result: object,
+ *   recordFrictionFn?: typeof recordScopeFriction,
+ * }} args `result` is a {@link module:lib/orchestration/light-suitability.checkLightDiffBackstop}
+ *   verdict.
+ * @returns {Promise<string>} The recycle command.
+ */
+export async function handleBlockedBackstop({
+  storyId,
+  result,
+  emitFn,
+  recordFrictionFn = recordScopeFriction,
+} = {}) {
+  await recordFrictionFn({
+    emitFn,
+    storyId,
+    surface: 'diff-backstop',
+    reasons: result?.reasons ?? [],
+    details: {
+      fileCount: result?.fileCount ?? null,
+      implFiles: result?.magnitude?.implFiles ?? null,
+      implLines: result?.magnitude?.implLines ?? null,
+      ceilings: result?.ceilings ?? null,
+      classes: result?.classes ?? [],
+    },
+  });
+  return buildRecycleCommand(storyId);
+}
+
+/**
+ * Record a light-path scope rejection as friction.
+ *
+ * Total: never throws, and returns `false` rather than propagating when the
+ * signals surface is unavailable.
+ *
+ * @param {{
+ *   storyId?: number|null,
+ *   surface: string,
+ *   reasons?: string[],
+ *   details?: object,
+ *   emitFn?: typeof emitRuntimeFriction,
+ * }} args
+ * @returns {Promise<boolean>}
+ */
+async function recordScopeFriction({
+  storyId,
+  surface,
+  reasons = [],
+  details = {},
+  emitFn,
+} = {}) {
+  const emit = emitFn ?? emitRuntimeFriction;
+  try {
+    return await emit({
+      storyId,
+      category: RUNTIME_FRICTION_CATEGORIES.LIGHT_SCOPE_REJECTED,
+      tool: 'deliver-light',
+      details: { surface, reasons, ...details },
+    });
+  } catch {
+    return false;
+  }
+}