mandrel 2.31.0 → 2.32.0

package/.agents/scripts/install-matrix-assert.js

@@ -67,7 +67,6 @@ const FRAMEWORK_RUNTIME_DEPS = [
   'js-yaml',
   'minimatch',
   'picomatch',
-  'string-argv',
   'typhonjs-escomplex',
 ];
 

package/.agents/scripts/lib/ITicketingProvider.js

@@ -112,17 +112,6 @@ export class ITicketingProvider {
     throw new Error('Not implemented: getTicketDependencies');
   }
 
-  /**
-   * Fetch recent comments across the repository.
-   * Useful for auditing and visualization of agent telemetry.
-   *
-   * @param {number} [limit=100]
-   * @returns {Promise<object[]>}
-   */
-  async getRecentComments(_limit = 100) {
-    throw new Error('Not implemented: getRecentComments');
-  }
-
   /**
    * Fetch all comments for a specific ticket.
    *
@@ -137,42 +126,6 @@ export class ITicketingProvider {
   // Write Operations
   // ---------------------------------------------------------------------------
 
-  /**
-   * Create a child ticket within an Epic's structural hierarchy.
-   *
-   * @param {number} parentId - GitHub Issue number of the immediate structural parent (e.g. Epic or Story).
-   * @param {{
-   *   epicId: number,
-   *   title: string,
-   *   body: string,
-   *   labels: string[],
-   *   dependencies: number[]
-   * }} ticketData - The ticket content and metadata.
-   * @returns {Promise<{ id: number, url: string }>}
-   */
-
-  /**
-   * Link an existing issue as a sub-issue of a parent.
-   *
-   * @param {number} parentId - GitHub Issue number of the parent.
-   * @param {number} childId - GitHub internal database ID of the sub-issue.
-   * @returns {Promise<void>}
-   */
-  async addSubIssue(_parentId, _childId) {
-    throw new Error('Not implemented: addSubIssue');
-  }
-
-  /**
-   * Remove a sub-issue link from a parent.
-   *
-   * @param {number} parentId - GitHub Issue number of the parent.
-   * @param {number} childId - GitHub internal database ID of the sub-issue.
-   * @returns {Promise<void>}
-   */
-  async removeSubIssue(_parentId, _childId) {
-    throw new Error('Not implemented: removeSubIssue');
-  }
-
   /**
    * Mutate labels, body (tasklist checkboxes), and assignees on a ticket.
    *
@@ -213,17 +166,6 @@ export class ITicketingProvider {
     throw new Error('Not implemented: deleteComment');
   }
 
-  /**
-   * Open a Pull Request linking the specified ticket.
-   *
-   * @param {string} branchName - The source branch for the PR.
-   * @param {number} ticketId - GitHub Issue number to link.
-   * @returns {Promise<{ number: number, url: string, htmlUrl: string }>}
-   */
-  async createPullRequest(_branchName, _ticketId) {
-    throw new Error('Not implemented: createPullRequest');
-  }
-
   // ---------------------------------------------------------------------------
   // Setup Operations (used by bootstrap)
   // ---------------------------------------------------------------------------

package/.agents/scripts/lib/audit-baselines/staleness.js

@@ -16,25 +16,25 @@
  * @module lib/audit-baselines/staleness
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileCapture } from '../child-exec.js';
 import { KIND_SPECS } from './kinds.js';
 import { ageInDays } from './read.js';
 
 /**
  * Run a git command under `cwd`, returning trimmed stdout, or `null` on any
- * failure or empty result.
+ * failure or empty result. Buffer and shell policy come from the shared
+ * child-process surface ([`child-exec.js`](../child-exec.js)).
  *
  * @param {string[]} args
  * @param {{ cwd: string, run?: Function }} io
  * @returns {string | null}
  */
-function git(args, { cwd, run = execFileSync }) {
+function git(args, { cwd, run }) {
   try {
     const stdout = String(
-      run('git', args, {
+      execFileCapture('git', args, {
+        run,
         cwd,
-        encoding: 'utf8',
-        maxBuffer: 16 * 1024 * 1024,
         stdio: ['ignore', 'pipe', 'ignore'],
       }),
     ).trim();

package/.agents/scripts/lib/audit-baselines/trend.js

@@ -16,7 +16,7 @@
  * @module lib/audit-baselines/trend
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileCapture } from '../child-exec.js';
 import { trendRollupOf } from './kinds.js';
 
 /**
@@ -25,13 +25,13 @@ import { trendRollupOf } from './kinds.js';
  * @param {{ cwd: string, relPath: string, limit: number, run?: Function }} args
  * @returns {Array<{ sha: string, committedAt: string }>}
  */
-function listCommits({ cwd, relPath, limit, run = execFileSync }) {
+function listCommits({ cwd, relPath, limit, run }) {
   let stdout;
   try {
-    stdout = run(
+    stdout = execFileCapture(
       'git',
       ['log', `-n${limit}`, '--format=%H %cI', '--', relPath],
-      { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      { run, cwd, stdio: ['ignore', 'pipe', 'ignore'] },
     );
   } catch {
     return [];
@@ -52,13 +52,12 @@ function listCommits({ cwd, relPath, limit, run = execFileSync }) {
  * @param {{ cwd: string, kind: string, sha: string, relPath: string, run?: Function }} args
  * @returns {object | null}
  */
-function rollupAt({ cwd, kind, sha, relPath, run = execFileSync }) {
+function rollupAt({ cwd, kind, sha, relPath, run }) {
   let stdout;
   try {
-    stdout = run('git', ['show', `${sha}:${relPath}`], {
+    stdout = execFileCapture('git', ['show', `${sha}:${relPath}`], {
+      run,
       cwd,
-      encoding: 'utf8',
-      maxBuffer: 64 * 1024 * 1024,
       stdio: ['ignore', 'pipe', 'ignore'],
     });
   } catch {

package/.agents/scripts/lib/audit-baselines/weights.js

@@ -16,9 +16,9 @@
  * @module lib/audit-baselines/weights
  */
 
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileCapture } from '../child-exec.js';
 import { computeInDegree, resolveRepoGraph } from '../import-graph.js';
 
 /** Neutral multiplier every degraded weight collapses to. */
@@ -47,10 +47,10 @@ function saturate(count, half) {
  *   `degraded` is true when git could not answer at all — not a git work
  *   tree, no commits yet, or the binary is unavailable.
  */
-export function readChurn({ cwd, windowDays = 180, run = execFileSync }) {
+export function readChurn({ cwd, windowDays = 180, run }) {
   let stdout;
   try {
-    stdout = run(
+    stdout = execFileCapture(
       'git',
       [
         'log',
@@ -60,9 +60,8 @@ export function readChurn({ cwd, windowDays = 180, run = execFileSync }) {
         '--no-renames',
       ],
       {
+        run,
         cwd,
-        encoding: 'utf8',
-        maxBuffer: 64 * 1024 * 1024,
         // git narrates "not a git repository" on stderr; the degradation is
         // reported in the envelope, not shouted at the operator.
         stdio: ['ignore', 'pipe', 'ignore'],

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

@@ -41,7 +41,7 @@ import path from 'node:path';
 import { AUDIT_LENSES } from '../audit-to-stories/audit-lenses.js';
 import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
-import { estimateTokens } from '../orchestration/context-envelope.js';
+import { estimateTokens } from '../orchestration/spec-spill.js';
 import {
   changeSetLacksSiblingTest,
   matchesAnyFilePattern,

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -249,7 +249,6 @@ export function buildStoryBody({ group, edges = [] }) {
     wide: null,
     reason_to_exist: null,
     depends_on: [],
-    estimated_test_files: null,
   };
 
   // Serialize via the canonical serializer (no footer — depends_on is empty).

package/.agents/scripts/lib/baselines/envelope.js

@@ -40,46 +40,26 @@
  * @module lib/baselines/envelope
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import Ajv from 'ajv';
-import addFormats from 'ajv-formats';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import {
+  BASELINE_KIND_SCHEMA_FILES,
+  buildBaselineSchemaAjv,
+} from '../baseline-schema-registry.js';
 
 /**
- * Repo-relative `.agents/schemas/baselines/` directory. Resolved off the
- * module URL so the envelope works the same in the main checkout, in a
- * worktree, and inside CI's bare clone — none of those have a stable
- * `process.cwd()` relative to the schemas.
+ * Canonical list of kinds the shared envelope supports, **derived** from the
+ * schema registry rather than restated (Story #5002).
+ *
+ * It used to be a hand-kept literal that happened to mirror
+ * `BASELINE_KIND_SCHEMA_FILES` name for name. Deriving it makes
+ * "`kind` is known" and "`kind`'s schema is registered" the same fact, so
+ * `getValidator` below cannot be handed a kind the AJV instance never
+ * compiled — the not-registered branch is gone because the state is
+ * unreachable, not because it was hidden.
  */
-const SCHEMAS_DIR = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'baselines',
+export const KNOWN_KINDS = Object.freeze(
+  BASELINE_KIND_SCHEMA_FILES.map((file) => file.replace(/\.schema\.json$/, '')),
 );
 
-/**
- * Canonical list of kinds the shared envelope supports. The writer's
- * per-kind module list lives in `kinds/index.js`; this constant is the
- * envelope's view of the same set, kept here to break the import cycle
- * (`kinds/<kind>` imports envelope; envelope only needs the names).
- */
-export const KNOWN_KINDS = Object.freeze([
-  'lint',
-  'coverage',
-  'crap',
-  'maintainability',
-  'mutation',
-  'lighthouse',
-  'bundle-size',
-  'duplication',
-]);
-
 function schemaRefFor(kind) {
   return `.agents/schemas/baselines/${kind}.schema.json`;
 }
@@ -193,36 +173,37 @@ export function buildEnvelope({
 }
 
 /**
- * Lazy AJV instance — compiled schemas are memoised so successive writes
- * during a single Node process don't re-compile the seven schemas.
+ * Lazy AJV instance, built by the canonical
+ * [`baseline-schema-registry`](../baseline-schema-registry.js) — the ONE
+ * place a baselines-directory schema is read off disk and compiled
+ * (Story #5002). This module used to keep its own `SCHEMAS_DIR` + AJV +
+ * per-kind compile cache alongside the registry's, so the writer and
+ * `baselines/reader.js` validated the same envelope through two independently
+ * configured instances; a registration added to one was invisible to the
+ * other. One builder means the writer and the reader cannot disagree about
+ * what a valid envelope is.
+ *
+ * Memoised: building it reads eleven schema files, and a single baseline
+ * regeneration calls `assertEnvelope` once per write plus once per re-read.
  */
 let _ajv = null;
-const _validators = new Map();
-
-function getAjv() {
-  if (_ajv) return _ajv;
-  const ajv = new Ajv({ allErrors: true, strict: false });
-  addFormats(ajv);
-  const envelopeSchema = JSON.parse(
-    fs.readFileSync(
-      path.join(SCHEMAS_DIR, 'baseline-envelope.schema.json'),
-      'utf8',
-    ),
-  );
-  ajv.addSchema(envelopeSchema, 'baseline-envelope.schema.json');
-  _ajv = ajv;
-  return ajv;
+function ajv() {
+  if (_ajv === null) {
+    _ajv = buildBaselineSchemaAjv();
+  }
+  return _ajv;
 }
 
+/**
+ * Look up the pre-registered validator for a per-kind schema. Total over
+ * `KNOWN_KINDS` — that list is derived from the registry's own filenames, so
+ * every kind reaching here has a compiled schema.
+ *
+ * @param {string} kind
+ * @returns {import('ajv').ValidateFunction}
+ */
 function getValidator(kind) {
-  if (_validators.has(kind)) return _validators.get(kind);
-  const ajv = getAjv();
-  const schema = JSON.parse(
-    fs.readFileSync(path.join(SCHEMAS_DIR, `${kind}.schema.json`), 'utf8'),
-  );
-  const validate = ajv.compile(schema);
-  _validators.set(kind, validate);
-  return validate;
+  return ajv().getSchema(`${kind}.schema.json`);
 }
 
 /**

package/.agents/scripts/lib/baselines/git-base.js

@@ -22,6 +22,13 @@
 //     `ref` and `file` are passed as separate argv tokens, never
 //     interpolated into a shell command.
 //
+// Story #5009 moved the spawn itself, the stdout ceiling and the
+// failure-message shape out to `lib/child-exec.js` — the one child-process
+// surface — so this module now owns only what is genuinely its own: the
+// `(ref, file)` LRU, the exit-code semantics below, and the test seam. The
+// `__setSpawnRunner` seam still injects a mock runner; it is threaded through
+// the shared wrapper as `run` rather than calling `spawnSync` directly.
+//
 // Exit semantics are intentionally narrow:
 //
 //   - Exit 0: stdout is the file contents, returned as a UTF-8 string.
@@ -39,7 +46,7 @@
 // means "path absent at ref". Callers may therefore treat a throw as a
 // hard failure without having to re-diagnose it.
 
-import { spawnSync } from 'node:child_process';
+import { formatChildFailure, spawnChild } from '../child-exec.js';
 
 // ---------------------------------------------------------------------------
 // LRU cache. Small footprint — even a fan-out across all seven baseline
@@ -53,21 +60,13 @@ import { spawnSync } from 'node:child_process';
 const DEFAULT_MAX_ENTRIES = 64;
 
 /**
- * Story #4914 — explicit stdout ceiling for every git read in this module.
- *
- * `child_process.spawnSync` defaults `maxBuffer` to 1 MB. A committed
- * baseline legitimately grows past that (a real consumer's crap baseline
- * measured 1,178,910 bytes), at which point the child is killed —
- * `status: null`, `signal: 'SIGTERM'`, `error.code: 'ENOBUFS'` — and the
- * read fails for a reason that has nothing to do with the repository.
+ * Injected spawn runner, or `undefined` to use the shared surface's real one.
+ * Story #4914's explicit 64 MB ceiling still applies to both git reads below —
+ * it is now `child-exec.js`'s `MAX_BUFFER_BYTES`, applied by `spawnChild`.
  *
- * 64 MB is not a new number: it is the bound already used at
- * `run-test-profile.js:87`, `audit-baselines/trend.js:61` and
- * `audit-baselines/weights.js:65`. This module was the outlier.
+ * @type {Function | undefined}
  */
-const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-
-let _spawnSync = spawnSync;
+let _spawnRunner;
 let _cache = new Map();
 let _maxEntries = DEFAULT_MAX_ENTRIES;
 
@@ -80,12 +79,12 @@ let _maxEntries = DEFAULT_MAX_ENTRIES;
  * the contract.
  *
  * @param {object} [opts]
- * @param {typeof spawnSync} [opts.spawn] - Mock spawnSync.
- * @param {number} [opts.maxEntries]      - Override LRU capacity.
+ * @param {Function} [opts.spawn]    - Mock spawnSync.
+ * @param {number} [opts.maxEntries] - Override LRU capacity.
  */
 export function __setSpawnRunner(opts = {}) {
   if (opts.spawn) {
-    _spawnSync = opts.spawn;
+    _spawnRunner = opts.spawn;
   }
   if (typeof opts.maxEntries === 'number') {
     _maxEntries = opts.maxEntries;
@@ -98,7 +97,7 @@ export function __setSpawnRunner(opts = {}) {
  * to keep state from leaking across files.
  */
 export function __resetForTests() {
-  _spawnSync = spawnSync;
+  _spawnRunner = undefined;
   _maxEntries = DEFAULT_MAX_ENTRIES;
   _cache = new Map();
 }
@@ -179,13 +178,10 @@ export function readBaseFromGit(ref, file, opts = {}) {
 
   const cwd = opts.cwd ?? process.cwd();
   const spec = `${ref}:${file}`;
-  const result = _spawnSync('git', ['show', spec], {
+  const result = spawnChild('git', ['show', spec], {
+    run: _spawnRunner,
     cwd,
-    stdio: 'pipe',
-    encoding: 'utf-8',
-    shell: false,
     env: cleanGitEnv(),
-    maxBuffer: MAX_BUFFER_BYTES,
   });
 
   // `child_process.spawnSync` returns `status: null` when the child died
@@ -206,9 +202,12 @@ export function readBaseFromGit(ref, file, opts = {}) {
     return null;
   }
 
-  const stderr = (result.stderr || '').toString().trim();
   throw new Error(
-    `readBaseFromGit: git show ${spec} failed (status=${status}): ${stderr}`,
+    formatChildFailure({
+      label: `readBaseFromGit: git show ${spec}`,
+      status,
+      stderr: result.stderr,
+    }),
   );
 }
 
@@ -222,9 +221,10 @@ export function readBaseFromGit(ref, file, opts = {}) {
  * Restricting the log to `-- <file>` means the returned subjects already
  * satisfy the "commit whose diff touches the baseline file" half of the
  * predicate; the caller only has to match the tag substring against each
- * subject. Runs through the same `spawnSync` seam as `readBaseFromGit`, so
- * it inherits the identical env scrubbing (drop inherited `GIT_*`) and the
- * spawn-not-exec security posture (argv tokens, `shell: false`).
+ * subject. Runs through the same shared `spawnChild` surface and injected
+ * runner as `readBaseFromGit`, so it inherits the identical env scrubbing
+ * (drop inherited `GIT_*`), the same stdout ceiling, and the spawn-not-exec
+ * security posture (argv tokens, `shell: false`).
  *
  * Returns an empty array whenever the range cannot be walked (missing base
  * ref, git failure, empty range) — the acknowledgment path treats "no
@@ -244,17 +244,10 @@ export function readRangeSubjectsTouchingFile(baseRef, file, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   let result;
   try {
-    result = _spawnSync(
+    result = spawnChild(
       'git',
       ['log', `${baseRef}..HEAD`, '--format=%s', '--', file],
-      {
-        cwd,
-        stdio: 'pipe',
-        encoding: 'utf-8',
-        shell: false,
-        env: cleanGitEnv(),
-        maxBuffer: MAX_BUFFER_BYTES,
-      },
+      { run: _spawnRunner, cwd, env: cleanGitEnv() },
     );
   } catch {
     return [];

package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js

@@ -0,0 +1,103 @@
+/**
+ * _crap-new-method-gate.js — the policy `kinds/crap.js#compareCrap` applies to
+ * a method that has no baseline row (Story #5002).
+ *
+ * Underscore-prefixed like `_shared-metric.js`: this is a helper for the
+ * per-kind modules in this directory, not a kind of its own.
+ *
+ * A leaf — it imports nothing, so `kinds/crap.js` can consume it without
+ * adding an edge to anything the comparator does not already reach.
+ */
+
+/**
+ * The set of scanned files in which **every** measured method resolved 0%
+ * coverage — the observable signature of a source no test loads at all.
+ *
+ * Deliberately derived from the scan rows rather than plumbed down from the
+ * coverage artifact: the rows are the only thing both the preview gate and the
+ * close-validation projection hand the comparator, and "the whole file is at
+ * zero" is exactly what an all-zero istanbul entry produces here.
+ *
+ * A row carrying `coverage: null` is skipped, not counted as a zero — an
+ * absent observation is not a measured one, and letting it vote would hand the
+ * relief below to a file nothing measured at all.
+ *
+ * @param {Array<{file: string, coverage?: number|null}>} currentRows
+ * @returns {Set<string>}
+ */
+export function deriveUncoveredFiles(currentRows) {
+  const allZeroByFile = new Map();
+  for (const row of currentRows ?? []) {
+    if (typeof row?.coverage !== 'number') continue;
+    const soFar = allZeroByFile.get(row.file);
+    allZeroByFile.set(row.file, (soFar ?? true) && row.coverage === 0);
+  }
+  const uncovered = new Set();
+  for (const [file, allZero] of allZeroByFile) {
+    if (allZero) uncovered.add(file);
+  }
+  return uncovered;
+}
+
+/**
+ * The score a **new** method is judged against `newMethodCeiling` with.
+ *
+ * Normally the measured CRAP. In a file whose every method scored 0%, the
+ * complexity term `c` alone.
+ *
+ * **Why.** `crap = c²·(1 − cov)³ + c` collapses to `c² + c` at zero coverage,
+ * so the default ceiling of 30 caps a *brand-new* method in an untested file
+ * at `c ≈ 5`. For the code that is untestable by construction — argv parsing,
+ * `spawn` wiring, a CLI's top-level `main()` — that is not a quality signal
+ * but a fragmentation tax: the only way past it is to shatter cohesive wiring
+ * into sub-five-branch fragments, which raises the file's method count and its
+ * reader's cost while measuring nothing. The coverage term still governs every
+ * method in a file the tests *do* reach, and a genuinely sprawling function is
+ * still refused — `c` alone must clear the ceiling.
+ *
+ * This is a **gate** decision, not a scoring one: the persisted baseline row
+ * keeps its measured `c² + c`, so the regression arm on the next run compares
+ * like with like.
+ *
+ * @param {{file: string, crap: number, cyclomatic?: number}} row
+ * @param {Set<string>} uncoveredFiles
+ * @returns {number}
+ */
+export function newMethodGateScore(row, uncoveredFiles) {
+  if (!uncoveredFiles.has(row.file)) return row.crap;
+  return Number.isFinite(row.cyclomatic) ? row.cyclomatic : row.crap;
+}
+
+/**
+ * Assemble a new-method violation.
+ *
+ * `gateScore` is written **only** when the ceiling was judged against
+ * something other than the measured `crap` — the same write-only-when-
+ * non-default idiom `projectRow` uses for its row markers — so the printer can
+ * name the number that actually failed instead of one nothing tested.
+ *
+ * @param {object} row
+ * @param {number} ceiling
+ * @param {number} gateScore
+ * @returns {object}
+ */
+export function buildNewViolation(row, ceiling, gateScore) {
+  return {
+    ...row,
+    kind: 'new',
+    baseline: null,
+    ceiling,
+    ...(gateScore === row.crap ? {} : { gateScore }),
+  };
+}
+
+/**
+ * Render the measured-vs-gated half of a new-method violation line.
+ *
+ * @param {{crap: number, gateScore?: number}} v
+ * @returns {string}
+ */
+export function formatNewViolationMeasure(v) {
+  if (v.gateScore === undefined) return `crap=${v.crap.toFixed(2)}`;
+  return `complexity=${v.gateScore} (file has no coverage; crap=${v.crap.toFixed(2)})`;
+}