mandrel 2.58.0 → 2.60.0

package/.agents/scripts/lib/coverage-capture-fullscope.js

@@ -8,6 +8,7 @@
  * logic; behaviour is byte-for-byte the pre-#4981 body.
  */
 import path from 'node:path';
+import { resolveChangedFilesRef } from './changed-files.js';
 import {
   anyChangedUnderTargets,
   describeFreshness,
@@ -19,10 +20,14 @@ import {
  * content-digest freshness probe, and — when stale — the full-repo
  * `npm run test:coverage` capture + stamp write.
  *
+ * The skip check scores the ref `resolveChangedFilesRef` resolves — the rule,
+ * and the same answer, incremental mode applies, so a fall-through from it
+ * cannot change scope mid-run (Story #5365).
+ *
  * @param {{
  *   crap: object,
  *   coverage: object,
- *   args: { skipWhenNoCrapFiles: boolean, ref: string, cwd: string },
+ *   args: { skipWhenNoCrapFiles: boolean, ref: string | null, cwd: string },
  *   getChangedFilesImpl: Function,
  *   isCoverageFreshImpl: Function,
  *   runCaptureImpl: Function,
@@ -46,7 +51,10 @@ export function runFullScopeCapture({
   if (args.skipWhenNoCrapFiles) {
     let changed;
     try {
-      changed = getChangedFilesImpl({ ref: args.ref, cwd: args.cwd });
+      changed = getChangedFilesImpl({
+        ref: resolveChangedFilesRef({ crap, ref: args.ref }),
+        cwd: args.cwd,
+      });
     } catch (err) {
       // A bad ref must not silently relax the gate. Fall through to the
       // freshness check so coverage still gets captured if needed.

package/.agents/scripts/lib/coverage-capture-incremental.js

@@ -9,6 +9,7 @@
  * parameter (`.agents/rules/test-seams.md` rules 1-2, 4).
  */
 import path from 'node:path';
+import { resolveChangedFilesRef } from './changed-files.js';
 import { stampCapturedTree } from './coverage-capture.js';
 
 /**
@@ -38,7 +39,7 @@ import { stampCapturedTree } from './coverage-capture.js';
  * @param {{
  *   crap: object,
  *   coverage: object,
- *   args: { ref: string, cwd: string },
+ *   args: { ref: string | null, cwd: string },
  *   getChangedFilesImpl: Function,
  *   filterFilesUnderTargetsImpl: Function,
  *   isCoverageFreshImpl: Function,
@@ -63,7 +64,7 @@ export function tryIncrementalCapture({
 }) {
   if (crap.incrementalCoverage?.skipWhenUnchanged !== true) return null;
 
-  const ref = crap.incrementalCoverage.baseRef || args.ref;
+  const ref = resolveChangedFilesRef({ crap, ref: args.ref });
   let changed = null;
   try {
     changed = getChangedFilesImpl({ ref, cwd: args.cwd });

package/.agents/scripts/lib/coverage-capture-usage.js

@@ -39,7 +39,10 @@ const COVERAGE_CAPTURE_USAGE = {
       '--require-credited',
       'Refuse (exit 1) instead of spawning when no credited capture stamp covers this tree. Passed by the close gate when delivery.execution.requireCreditedCapture is set; a bare invocation always runs, so the deposit path stays open.',
     ],
-    ['--ref <git-ref>', 'Git ref the changed-file set is computed against.'],
+    [
+      '--ref <git-ref>',
+      'Git ref the changed-file set is computed against. Passing it wins over delivery.quality.gates.crap.incrementalCoverage.baseRef, so a caller that anchors another gate on the same ref gets one scope for both.',
+    ],
     ['--cwd <path>', 'Repository root the capture runs in.'],
   ],
 };

package/.agents/scripts/lib/crap-engine.js

@@ -1,4 +1,3 @@
-import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
 // `finalizeMethodRowsWithBaseline` (Story #4981) lives in
 // crap-baseline-join.js — `resolveRawRow`, the per-row policy it shares with
@@ -15,6 +14,7 @@ import {
 } from './crap-coordinates.js';
 import { deriveMethodIdentities } from './crap-method-identity.js';
 import { install as installAstCompat } from './escomplex-ast-compat.js';
+import { analyzeModule } from './escomplex-kernel.js';
 
 export { COORDINATE_ORIGINAL, COORDINATE_TRANSPILED, crapFormula };
 
@@ -256,7 +256,7 @@ export function calculateCrapForSource(
 ) {
   let report;
   try {
-    report = escomplex.analyzeModule(source);
+    report = analyzeModule(source);
   } catch {
     return UNSCORABLE;
   }

package/.agents/scripts/lib/crap-utils.js

@@ -1,6 +1,5 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import escomplex from 'typhonjs-escomplex';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { findCoverageEntry } from './coverage-utils.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
@@ -11,6 +10,7 @@ import {
   shouldSkipFileForNoCoverage,
 } from './crap-baseline-join.js';
 import { COORDINATE_ORIGINAL, methodRowsFromReport } from './crap-engine.js';
+import { analyzeModule } from './escomplex-kernel.js';
 import { Logger } from './Logger.js';
 import { scanDirectory } from './maintainability-utils.js';
 import {
@@ -36,8 +36,24 @@ export { resolveTsTranspilerVersion };
 const SCHEMA_REF = '.agents/schemas/crap-baseline.schema.json';
 
 /**
- * Resolve the running `typhonjs-escomplex` version by walking up from `cwd`
- * and reading the nearest `node_modules/typhonjs-escomplex/package.json`.
+ * Package whose resolved version is stamped as the scorer identity.
+ *
+ * `escomplex-plugin-metrics-module` computes the metrics. The retired
+ * `typhonjs-escomplex` facade did not, so stamping it described the shell
+ * rather than the scorer.
+ */
+const SCORER_PACKAGE = 'escomplex-plugin-metrics-module';
+
+/**
+ * Resolve the running scorer's version by walking up from `cwd` and reading the
+ * nearest `node_modules/<SCORER_PACKAGE>/package.json`.
+ *
+ * The package read is `escomplex-plugin-metrics-module`, which owns the
+ * Halstead and maintainability math — not the displaced `typhonjs-escomplex`
+ * shell, which contributed a parser and a plugin bus and never a metric. The
+ * stamp is supposed to answer "could this scorer have produced different
+ * numbers", so it has to name the package that computes them.
+ *
  * Returns `'0.0.0'` when the dependency cannot be found — callers treat that
  * sentinel as "unknown environment" and may refuse to persist a baseline.
  *
@@ -51,7 +67,7 @@ export function resolveEscomplexVersion(cwd = process.cwd()) {
     const pkgPath = path.join(
       dir,
       'node_modules',
-      'typhonjs-escomplex',
+      SCORER_PACKAGE,
       'package.json',
     );
     if (fs.existsSync(pkgPath)) {
@@ -266,7 +282,7 @@ export function checkResolutionFloor(resolution, floor) {
 function analyzeOnce(source, coverageForFile, mapLine = null) {
   let report;
   try {
-    report = escomplex.analyzeModule(source);
+    report = analyzeModule(source);
   } catch {
     return { report: null, miScore: 0, crapRows: [], parseError: true };
   }

package/.agents/scripts/lib/doc-tiers.js

@@ -27,8 +27,10 @@
  *   - `agentBoot`     — the role-scoped boot contexts `.agents/agents/*.md`
  *                       (issue #4478). Each is a standalone system prompt a
  *                       converted spawn boots on **instead of** the always-loaded
- *                       closure, so it is budgeted independently (per-file ≤8KB
- *                       ceiling gated by `check-context-budget.js`).
+ *                       closure, so it is measured independently. Its per-file
+ *                       8 KB ceiling was deleted by Story #5340;
+ *                       `check-context-budget.js` now reports these sizes and
+ *                       gates nothing on them.
  *   - `workflow` /    — the `.agents/workflows/**` read-tier (Story #4752),
  *     `workflowOnDemand` resolved as each entry point's transitive
  *                       markdown-link closure by

package/.agents/scripts/lib/escomplex-ast-compat.js

@@ -4,8 +4,8 @@
  *
  * ## The upstream defect
  *
- * `typhonjs-escomplex` parses with `@typhonjs/babel-parser`, so every AST it
- * analyses is a **Babel** AST. But `typhonjs-escomplex-commons`'
+ * The kernel parses with `@babel/parser`, so every AST it analyses is a
+ * **Babel** AST. But `typhonjs-escomplex-commons`'
  * `utils/ast/astSyntax.js` — the code generator that `ASTGenerator` drives —
  * was written against **ESTree**. The two disagree on node names
  * (`OptionalMemberExpression` vs a `MemberExpression` with `optional: true`)
@@ -62,6 +62,21 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 
+/**
+ * The package whose resolution anchors every `typhonjs-escomplex-commons` deep
+ * import in this module.
+ *
+ * `escomplex-plugin-syntax-babylon` is the package that actually reads the
+ * `astSyntax` table during a metric traversal, so its copy of `commons` is the
+ * only one worth patching.
+ *
+ * Module-local on purpose. A test proves the binding by resolving from this
+ * package's own root itself — which is the assertion worth making, since our
+ * copy and the plugin's coincide under a hoisting installer and an
+ * "ours === theirs" check would pass vacuously.
+ */
+const ANCHOR_PACKAGE = 'escomplex-plugin-syntax-babylon';
+
 /** Marker set on every function this module installs, for idempotency. */
 const PATCH_MARKER = Symbol.for('mandrel.escomplexAstCompat');
 
@@ -77,25 +92,32 @@ let installResult = null;
  * back to today's behaviour (unscorable files, now reported explicitly by
  * the engine rather than silently scored 0).
  *
- * The patch must land on the *same* `typhonjs-escomplex-commons` instance the
- * kernel loads, so `commons` is resolved **through `typhonjs-escomplex`'s own
- * resolution** rather than from here. Resolving it directly would be a coin
- * flip: under a hoisting installer it usually finds the same copy, but under
- * pnpm's isolated layout — or as soon as anything declares `commons` directly —
- * it can find a *different* physical copy, and the patch then lands on a table
- * nobody reads while `install()` cheerfully reports success. Anchoring makes
- * that failure mode unreachable.
+ * The patch must land on the *same* `astSyntax` table the metric traversal
+ * reads, and that table is resolved by **`escomplex-plugin-syntax-babylon`**,
+ * from its own location — `PluginSyntaxBabylon` requires
+ * `typhonjs-escomplex-commons/dist/utils/ast/ASTGenerator` and `ASTState` binds
+ * the table it finds. So `commons` is anchored through the syntax plugin's
+ * resolution, not through this module's and not through the kernel's.
+ *
+ * Resolving it from here, or from the kernel, would be a coin flip: under a
+ * hoisting installer every copy usually coincides, but under pnpm's isolated
+ * layout — or as soon as anything declares `commons` at a different version —
+ * the plugin can read a *different* physical copy, and the patch then lands on
+ * a table nobody reads while `install()` cheerfully reports success. Anchoring
+ * on the reader makes that unreachable. Note this is why a test asserting
+ * "our copy === the patched copy" proves nothing: under hoisting it passes
+ * vacuously — a test must resolve from the plugin's own root instead.
  *
  * `requireFn` is the test seam: a cross-checkout verification harness passes
- * its own `createRequire` so the anchor starts from that checkout's escomplex.
+ * its own `createRequire` so the anchor starts from that checkout's plugin.
  *
  * @param {NodeJS.Require} [requireFn]
  * @returns {Record<string, Function>|null}
  */
 function resolveSyntaxTable(requireFn = require) {
   try {
-    const fromKernel = createRequire(requireFn.resolve('typhonjs-escomplex'));
-    const mod = fromKernel(
+    const fromReader = createRequire(requireFn.resolve(ANCHOR_PACKAGE));
+    const mod = fromReader(
       'typhonjs-escomplex-commons/dist/utils/ast/astSyntax.js',
     );
     const table = mod?.default ?? mod;
@@ -337,8 +359,8 @@ export function install(options = {}) {
 /**
  * `ASTUtil` is only needed by the `OptionalCallExpression` handler, and only at
  * call time — resolving it lazily keeps `install()` free of a second deep
- * import that could fail at module load. Anchored through the kernel for the
- * same reason as {@link resolveSyntaxTable}.
+ * import that could fail at module load. Anchored through the syntax plugin
+ * for the same reason as {@link resolveSyntaxTable}.
  *
  * `formatSequence` is a pure helper that takes the traveler and state as
  * arguments, so which copy answers is immaterial — but resolving it the same
@@ -347,8 +369,8 @@ export function install(options = {}) {
  * @returns {{ formatSequence: Function }}
  */
 function ASTUtil() {
-  const fromKernel = createRequire(require.resolve('typhonjs-escomplex'));
-  const mod = fromKernel(
+  const fromReader = createRequire(require.resolve(ANCHOR_PACKAGE));
+  const mod = fromReader(
     'typhonjs-escomplex-commons/dist/utils/ast/ASTUtil.js',
   );
   return mod?.default ?? mod;

package/.agents/scripts/lib/escomplex-kernel.js

@@ -0,0 +1,298 @@
+/**
+ * escomplex-kernel.js — the complexity kernel's parse and dispatch layers,
+ * in-repo.
+ *
+ * ## Why this file exists
+ *
+ * `typhonjs-escomplex` was a thin shell around four packages that do all the
+ * actual work. The shell contributed two things: a parser front-end
+ * (`@typhonjs/babel-parser`, a ~100-LOC shim over `@babel/parser`) and a
+ * generic plugin bus (`typhonjs-plugin-manager`, used as a hardcoded
+ * two-plugin synchronous dispatcher). Nine packages of plumbing hang off
+ * those two, and none of it computes anything.
+ *
+ * What this does **not** do is remove `core-js@2`. Four of the retained
+ * metric-core packages `require('babel-runtime/core-js/*')` themselves, so it
+ * is load-bearing for the code that stays; a change that claimed otherwise
+ * would be unshippable. What it buys instead is an honest closure —
+ * `babel-runtime` is required by those packages and declared by none of them,
+ * so today it resolves only because the removed plumbing hoists it. Declaring
+ * it turns an accident into a contract.
+ *
+ * This module reimplements exactly those two layers over the retained metric
+ * core — `typhonjs-escomplex-commons`, `escomplex-plugin-metrics-module`,
+ * `escomplex-plugin-syntax-babylon`, `typhonjs-ast-walker` — which compute
+ * every score. Nothing here computes a metric; the scores come from the same
+ * packages as before, which is why they do not move.
+ *
+ * ## The equivalence contract
+ *
+ * Reproducing the displaced shell's *behaviour* means reproducing three
+ * details it never documented:
+ *
+ * 1. **The parser's fixed plugin list**, verbatim and in order, with
+ *    `sourceType: 'unambiguous'` — see `PARSER_PLUGINS` below. The list is
+ *    what makes a `.ts` file, a decorator or a pipeline operator parse at
+ *    all, and `unambiguous` is what lets a CommonJS script and an ES module
+ *    both score.
+ * 2. **Both plugin instances, in registration order** — syntax first, then
+ *    metrics. The metrics plugin reads trait tables the syntax plugin put on
+ *    the event.
+ * 3. **One mutable event object per dispatch**, threaded through every plugin
+ *    in turn, with the caller reading the mutations back off it. The displaced
+ *    bus also stamped `$$plugin_invoke_count` / `$$plugin_invoke_names` onto
+ *    every event's data; no plugin and no report reads them, so they are not
+ *    reproduced.
+ *
+ * Equivalence is not asserted by reasoning: `tests/lib/escomplex-kernel.test.js`
+ * replays a corpus captured under the displaced kernel *before* it left the
+ * tree (`tests/fixtures/escomplex-kernel-parity/`), because afterwards there is
+ * nothing left to compare against.
+ *
+ * ## The one uncontrolled input
+ *
+ * `.agents/` materializes into a consumer's repository root, so `@babel/parser`
+ * resolves from **their** `node_modules`. The preflight guard checks presence,
+ * not range, and `@babel/parser@8` is GA and rejects several names in the
+ * fixed plugin list. A manifest range documents the requirement; it does not
+ * enforce it. So the resolved major is asserted here, at load, with an error
+ * that names the problem — rather than surfacing as an opaque plugin-list
+ * syntax error partway through a scan.
+ */
+
+// Every metric-core package is reached by a STATIC import specifier with an
+// explicit `.js` extension. That is not style: `tests/scripts/
+// runtime-deps-drift.test.js` scans for literal `import`/`require` callees, so
+// a package reached through an aliased `createRequire` would be a runtime
+// dependency that is neither declared nor preflighted. The extensions are
+// mandatory because `typhonjs-escomplex-commons` ships an empty
+// `package.json` — no `main`, no `exports` — so a deep path is the only door.
+import { parse as babelParse } from '@babel/parser';
+import PluginMetricsModule from 'escomplex-plugin-metrics-module/dist/PluginMetricsModule.js';
+import PluginSyntaxBabylon from 'escomplex-plugin-syntax-babylon/dist/PluginSyntaxBabylon.js';
+import ASTWalker from 'typhonjs-ast-walker/dist/ASTWalker.js';
+import ModuleScopeControl from 'typhonjs-escomplex-commons/dist/module/report/control/ModuleScopeControl.js';
+import ModuleReport from 'typhonjs-escomplex-commons/dist/module/report/ModuleReport.js';
+import { install as installAstCompat } from './escomplex-ast-compat.js';
+import { describeParserMajorError } from './runtime-deps/parser-major.js';
+
+/**
+ * The displaced parser shim's plugin list, verbatim and in order.
+ *
+ * Order is preserved because it is cheap to preserve, not because a
+ * reordering is known to matter. The two entries with options
+ * (`decorators`, `pipelineOperator`) carry the shim's exact settings —
+ * `decoratorsBeforeExport: false` and the `minimal` pipeline proposal — which
+ * decide whether decorated classes and `|>` parse. Re-cloned per parse so a
+ * parser that mutated its options could not poison a later call.
+ */
+const PARSER_PLUGINS = [
+  'asyncGenerators',
+  'bigInt',
+  'classProperties',
+  'classPrivateProperties',
+  'classPrivateMethods',
+  ['decorators', { decoratorsBeforeExport: false }],
+  'doExpressions',
+  'dynamicImport',
+  'exportDefaultFrom',
+  'exportNamespaceFrom',
+  'functionBind',
+  'functionSent',
+  'importMeta',
+  'jsx',
+  'logicalAssignment',
+  'nullishCoalescingOperator',
+  'numericSeparator',
+  'objectRestSpread',
+  'optionalCatchBinding',
+  'optionalChaining',
+  ['pipelineOperator', { proposal: 'minimal' }],
+  'throwExpressions',
+  'typescript',
+];
+
+/**
+ * The two plugins, in registration order: syntax populates the trait tables
+ * the metrics plugin then reads. Neither defines `onPluginLoad`, and the
+ * displaced bus was constructed without an eventbus, so there is no plugin
+ * lifecycle or eventbus coupling to reproduce — only this list.
+ */
+const PLUGINS = [
+  ['escomplex-plugin-syntax-babylon', new PluginSyntaxBabylon()],
+  ['escomplex-plugin-metrics-module', new PluginMetricsModule()],
+];
+
+// The kernel's code generator predates the Babel AST its own parser emits, so
+// ordinary modern syntax aborts a WHOLE module — see `escomplex-ast-compat.js`
+// for the defect and the upstream status. Installing at the kernel rather than
+// at each caller makes the next scoring entrypoint correct by construction.
+installAstCompat();
+
+const parserProblem = describeParserMajorError();
+if (parserProblem !== null) {
+  throw new Error(`[escomplex-kernel] ${parserProblem}`);
+}
+
+/**
+ * Run one synchronous plugin dispatch.
+ *
+ * Reproduces the displaced bus's `invokeSyncEvents` for the degenerate shape
+ * this kernel uses: no `copyProps` (the shell passed `void 0` at every call
+ * site, so the merge base was always `{}`), no eventbus, and the caller
+ * reading its results back off the same mutated `data` object every plugin
+ * saw.
+ *
+ * @param {string} method Plugin method name, e.g. `onEnterNode`.
+ * @param {object} passthru Properties placed on the event's `data`.
+ * @returns {object} The event `data`, after every plugin has mutated it.
+ */
+function dispatch(method, passthru) {
+  const event = {
+    data: { ...passthru },
+    extra: undefined,
+    eventbus: undefined,
+    pluginName: undefined,
+    pluginOptions: undefined,
+  };
+  for (const [name, instance] of PLUGINS) {
+    if (typeof instance[method] !== 'function') continue;
+    event.pluginName = name;
+    instance[method](event);
+  }
+  return event.data;
+}
+
+/**
+ * The `ignoreKeys` a syntax trait wants withheld from the walker, if any.
+ *
+ * @param {object|undefined} syntax The trait entry for this node type.
+ * @param {object} node
+ * @param {object} parent
+ * @returns {string[]}
+ */
+function traitIgnoreKeys(syntax, node, parent) {
+  return typeof syntax === 'object' && syntax?.ignoreKeys
+    ? syntax.ignoreKeys.valueOf(node, parent)
+    : [];
+}
+
+/**
+ * The new scope a syntax trait opens at this node, if any.
+ *
+ * @param {object|undefined} syntax The trait entry for this node type.
+ * @param {object} node
+ * @param {object} parent
+ * @returns {object|null}
+ */
+function traitNewScope(syntax, node, parent) {
+  if (typeof syntax !== 'object' || !syntax?.newScope) return null;
+  return syntax.newScope.valueOf(node, parent) ?? null;
+}
+
+/**
+ * Build the walker visitor for one module traversal.
+ *
+ * Split out of {@link analyzeModule} so the enter/exit symmetry is readable
+ * side by side: each resolves the trait's scope, brackets the `scopeControl`
+ * mutation with a pre/post dispatch, and straddles it with the node dispatch
+ * in opposite order on the way in and out.
+ *
+ * The two event shapes are not interchangeable, and the difference is the
+ * displaced shell's, not a simplification available here: node events carry
+ * `syntaxes` and scope events do not, and a scope event names its scope
+ * `newScope` on the way in but `scope` on the way out.
+ *
+ * @param {{
+ *   moduleReport: object,
+ *   scopeControl: object,
+ *   syntaxes: Record<string, object>,
+ *   settings: object,
+ * }} context
+ * @returns {{enterNode: Function, exitNode: Function}}
+ */
+function buildVisitor({ moduleReport, scopeControl, syntaxes, settings }) {
+  const nodeBase = { moduleReport, scopeControl, syntaxes, settings };
+  const scopeBase = { moduleReport, scopeControl, settings };
+  return {
+    enterNode(node, parent) {
+      const syntax = syntaxes[node.type];
+      const event = dispatch('onEnterNode', {
+        ...nodeBase,
+        ignoreKeys: traitIgnoreKeys(syntax, node, parent),
+        node,
+        parent,
+      });
+      const ignoreKeys = event !== null ? event.ignoreKeys : [];
+      const newScope = traitNewScope(syntax, node, parent);
+      if (newScope) {
+        const scoped = { ...scopeBase, newScope, node, parent };
+        dispatch('onModulePreScopeCreated', scoped);
+        scopeControl.createScope(newScope);
+        dispatch('onModulePostScopeCreated', scoped);
+      }
+      return ignoreKeys;
+    },
+    exitNode(node, parent) {
+      const syntax = syntaxes[node.type];
+      const newScope = traitNewScope(syntax, node, parent);
+      if (newScope) {
+        const scoped = { ...scopeBase, scope: newScope, node, parent };
+        dispatch('onModulePreScopePopped', scoped);
+        scopeControl.popScope(newScope);
+        dispatch('onModulePostScopePopped', scoped);
+      }
+      dispatch('onExitNode', { ...nodeBase, node, parent });
+    },
+  };
+}
+
+/**
+ * Parse and score one module.
+ *
+ * Drop-in replacement for the displaced `escomplex.analyzeModule(source)`:
+ * same report object, same `finalize()` shape, same thrown errors for source
+ * the kernel cannot handle.
+ *
+ * @param {string} source JavaScript (or TypeScript) source text.
+ * @param {object} [options] Passed to the plugins' `onConfigure`, as before.
+ * @returns {object} The finalized module report.
+ * @throws {SyntaxError} Propagated from the parser, as before.
+ */
+export function analyzeModule(source, options = {}) {
+  const ast = babelParse(source, {
+    plugins: structuredClone(PARSER_PLUGINS),
+    sourceType: 'unambiguous',
+  });
+
+  const settings = dispatch('onConfigure', { options, settings: {} }).settings;
+  Object.freeze(settings);
+  const syntaxes = dispatch('onLoadSyntax', {
+    settings,
+    syntaxes: {},
+  }).syntaxes;
+
+  const moduleReport = new ModuleReport(
+    ast.loc.start.line,
+    ast.loc.end.line,
+    settings,
+  );
+  dispatch('onModuleStart', { ast, moduleReport, syntaxes, settings });
+
+  const scopeControl = new ModuleScopeControl(moduleReport);
+  new ASTWalker().traverse(
+    ast,
+    buildVisitor({ moduleReport, scopeControl, syntaxes, settings }),
+  );
+
+  for (const phase of [
+    'onModuleCalculate',
+    'onModuleAverage',
+    'onModulePostAverage',
+    'onModuleEnd',
+  ]) {
+    dispatch(phase, { moduleReport, syntaxes, settings });
+  }
+
+  return moduleReport.finalize();
+}

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -290,18 +290,19 @@ export function runChild({
 
 /**
  * Build an `isAutoFileEnabled(config)` reader bound to a specific
- * `delivery.feedbackLoop.<key>` toggle. The feature is opt-out: the
- * toggle defaults to `true` and only an explicit `false` disables it.
+ * `delivery.feedbackLoop.<key>` toggle. The feature is **opt-in** since Story
+ * #5341: the toggle defaults to `false` and only an explicit `true` enables
+ * it, because the filings the channel produced unattended were dominated by
+ * noise (see `config-settings-schema-delivery.js` for the measured record).
  *
  * @param {string} toggleKey — key under `config.delivery.feedbackLoop`
- *   (e.g. "auditResultsAutoFile", "retroProposals")
+ *   (today, only "retroProposals" — the factory stays keyed so the next
+ *   graduator does not have to reinvent the resolution)
  * @returns {(config: object|undefined|null) => boolean}
  */
 export function makeIsAutoFileEnabled(toggleKey) {
   return function isAutoFileEnabled(config) {
-    const value = config?.delivery?.feedbackLoop?.[toggleKey];
-    if (value === false) return false;
-    return true;
+    return config?.delivery?.feedbackLoop?.[toggleKey] === true;
   };
 }
 

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -28,9 +28,9 @@
  * is gone from the whole path, not just from this module. The `meta::<framework-gap|consumer-improvement>` +
  * `friction::<category>` labels are lifted verbatim from the routed item.
  *
- * Behind the `delivery.feedbackLoop.retroProposals` toggle (default ON,
- * per `graduator-core.js#makeIsAutoFileEnabled`). NEVER throws — every
- * failure path is captured in `errors[]`.
+ * Behind the `delivery.feedbackLoop.retroProposals` toggle (default OFF
+ * since Story #5341, per `graduator-core.js#makeIsAutoFileEnabled`). NEVER
+ * throws — every failure path is captured in `errors[]`.
  */
 
 import {
@@ -46,8 +46,10 @@ import {
 } from './graduator-core.js';
 
 /**
- * Resolve the toggle from the resolved agentrc config. Defaults to `true`
- * — the feature is opt-out (mirrors auditResultsAutoFile).
+ * Resolve the toggle from the resolved agentrc config. Defaults to `false`
+ * — the feature is opt-in (Story #5341). It is now the only such toggle: the
+ * audit-results sibling was removed by Story #5366, its graduator having been
+ * deleted two releases earlier.
  *
  * @param {object|undefined|null} config
  * @returns {boolean}