mandrel 2.58.0 → 2.59.0

package/.agents/README.md

@@ -292,9 +292,12 @@ the script's location to your repo root). The required set is enumerated in
 a single vendored manifest that ships inside the bundle:
 
 - **[`runtime-deps.json`](runtime-deps.json)** — the single source of
-  truth. Its `dependencies` block lists the **required** packages (`ajv`,
-  `ajv-formats`, `js-yaml`, `minimatch`, `picomatch`,
-  `typhonjs-escomplex`); its `optionalDependencies` block lists packages
+  truth. Its `dependencies` block lists the **required** packages — `ajv`,
+  `ajv-formats`, `js-yaml`, `minimatch`, `picomatch`, plus the complexity
+  kernel's closure (`@babel/parser`, `typhonjs-escomplex-commons`,
+  `escomplex-plugin-metrics-module`, `escomplex-plugin-syntax-babylon`,
+  `typhonjs-ast-walker`, and `babel-runtime`, which those packages require
+  without declaring); its `optionalDependencies` block lists packages
   used behind graceful-degradation paths (`typescript` for TS-source
   scoring in the maintainability engine, `chokidar` for `quality:watch`,
   `@commitlint/load` for commit-subject sizing).

package/.agents/docs/SDLC.md

@@ -36,7 +36,7 @@ From zero to shipped:
    handoff via `--emit-plan-seed`), and `/mandrel-plan --tickets 123[,456…]` (analyze
    existing issue(s), preferring an N=1 rewrite). `/mandrel-plan` is a **single path**
    — interrogate → author → persist, bracketed by two HITL gates and a single
-   critic gate — with no Epic/Story router, scope-triage verdict, or
+   critic gate — with no Epic/Story router, split-routing verdict, or
    `deliveryShape`. Duplicate search targets open **Stories**, never Epics. The
    step-by-step lives in [`mandrel-plan.md`](../workflows/mandrel-plan.md).
 
@@ -211,15 +211,14 @@ the SDLC depends on:
   Epic-era Tech Spec / Acceptance Table / clarity-gate / decompose /
   reconciler machinery. `plan-persist.js` runs the deterministic gates
   (ticket validator, split policy, reachability, budget) and — for N>1 —
-  `assertAcceptancePartition` so every acceptance criterion belongs to
-  exactly one Story.
+  the same-wave collision refusal, so a split whose siblings the dispatcher
+  would serialize anyway is rejected before the first `createIssue`.
 - **Handoff.** Persist creates the Story issue(s) at `agent::ready` and
   names the delivery command: `/mandrel-deliver <storyId> [<storyId> ...]`.
 
-Optional split advisory notes come from
-[`core/scope-triage`](../skills/core/scope-triage/SKILL.md); there is no
-`epic|story` routing verdict, scorer, schema field, or label transition
-behind them.
+There is no `epic|story` routing verdict, scorer, schema field, or label
+transition anywhere on the path: sizing is the authoring model's cohesion
+judgment, and the one deterministic split gate is the collision refusal.
 
 Audit findings enter planning through
 [`/audit-to-stories`](../workflows/audit-to-stories.md), which groups and

package/.agents/docs/quality-gates.md

@@ -397,7 +397,7 @@ fails the run.
 
 A sibling per-method gate alongside the maintainability ratchet. CRAP
 scores each JavaScript method via `c² · (1 − cov)³ + c`, combining
-`typhonjs-escomplex` cyclomatic complexity with per-method coverage from
+kernel-derived cyclomatic complexity with per-method coverage from
 the `coverage/coverage-final.json` artifact your test runner already
 produces. No new runtime dependencies. Runs at three sites:
 `close-validation` (story close), `ci.yml` (push + PR), and

package/.agents/instructions.md

@@ -194,8 +194,7 @@ anything under it.
 `/mandrel-plan` sizes each Story as a **capability slice a frontier model
 delivers and self-verifies in one pass** — a broad footprint is normal
 when the change is cohesive, and no plan-time ceiling scores it; do not
-re-slice it into per-module fragments. On a `⚠️ COMPLEXITY WARNING` or
-out-of-scope task: **plan first** (numbered cohesive sub-steps in a
-`<!-- DECOMPOSITION -->`
+re-slice it into per-module fragments. On an out-of-scope task: **plan
+first** (numbered cohesive sub-steps in a `<!-- DECOMPOSITION -->`
 block), **commit incrementally** per sub-step, and **fail fast** — STOP
 and report if any sub-step fails validation.

package/.agents/runtime-deps.json

@@ -1,12 +1,17 @@
 {
-  "description": "Single source of truth for the third-party npm packages the .agents/ framework scripts import at runtime. This manifest ships *inside* .agents/ so it travels with the mandrel package into consumer projects. Consumers must provide these packages in the node_modules resolvable from their repository root (the framework scripts free-ride on the consumer's install). The `dependencies` block is fail-fast enforced by the preflight guard (.agents/scripts/lib/runtime-deps/ensure-installed.js); the `optionalDependencies` block lists packages that are imported behind graceful-degradation paths (try/catch or dev-only watch tooling) and are therefore declared but never preflight-blocked. A drift test (tests/scripts/runtime-deps-drift.test.js) asserts every third-party import under .agents/scripts/** is declared here. Version ranges mirror the framework's own root package.json.",
+  "description": "Single source of truth for the third-party npm packages the .agents/ framework scripts import at runtime. This manifest ships *inside* .agents/ so it travels with the mandrel package into consumer projects. Consumers must provide these packages in the node_modules resolvable from their repository root (the framework scripts free-ride on the consumer's install). The `dependencies` block is fail-fast enforced by the preflight guard (.agents/scripts/lib/runtime-deps/ensure-installed.js); the `optionalDependencies` block lists packages that are imported behind graceful-degradation paths (try/catch or dev-only watch tooling) and are therefore declared but never preflight-blocked. A drift test (tests/scripts/runtime-deps-drift.test.js) asserts every third-party import under .agents/scripts/** is declared here. Version ranges mirror the framework's own root package.json. Two entries need their reason recorded. `@babel/parser` is pinned to ^7 because the kernel's fixed plugin list does not parse under 8.x, and the range is documentation rather than enforcement \u2014 `.agents/` resolves from the consumer's own node_modules \u2014 so the kernel asserts the resolved major at load. `babel-runtime` is declared even though no framework script imports it: four of the metric-core packages require it and none of them declares it, so it resolved only by being hoisted from the parse/dispatch plumbing this framework used to depend on. Declaring it makes the closure explicit and preflight-enforced. The import-vs-manifest drift guard only flags imported-but-undeclared, so a declared-but-unimported peer repair like this is legal by design.",
   "dependencies": {
+    "@babel/parser": "^7.29.3",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "babel-runtime": "^6.26.0",
+    "escomplex-plugin-metrics-module": "^0.1.0",
+    "escomplex-plugin-syntax-babylon": "^0.1.0",
     "js-yaml": "^4.3.1",
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
-    "typhonjs-escomplex": "^0.1.0"
+    "typhonjs-ast-walker": "^0.2.1",
+    "typhonjs-escomplex-commons": "^0.1.1"
   },
   "optionalDependencies": {
     "@commitlint/load": "^21.0.0",

package/.agents/schemas/crap-baseline.schema.json

@@ -18,7 +18,7 @@
     },
     "escomplexVersion": {
       "type": "string",
-      "description": "Version of the typhonjs-escomplex dependency used to produce this baseline. A mismatch against the installed dependency fails the gate closed (different kernel semantics are not negotiable)."
+      "description": "Version of the package that computes the metrics (escomplex-plugin-metrics-module) used to produce this baseline. Informational: the axis that compared it was removed in Story #5336 — the v2 envelope does not carry the field, so it could not fire. scoringSemantics is the axis that rejects an incompatible scorer."
     },
     "tsTranspilerVersion": {
       "type": "string",

package/.agents/schemas/crap-report.schema.json

@@ -14,7 +14,7 @@
     },
     "escomplexVersion": {
       "type": "string",
-      "description": "typhonjs-escomplex version used for the scan."
+      "description": "Version of the package that computes the metrics (escomplex-plugin-metrics-module) used for the scan."
     },
     "summary": {
       "type": "object",

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

@@ -59,17 +59,62 @@ import path from 'node:path';
  * `.agents/runtime-deps.json` and provided by the consumer's install of
  * `mandrel` (npm hoists them into node_modules), but they MUST NOT
  * appear in the consumer's *declared* package.json dependencies. Kept in sync
- * with `.agents/runtime-deps.json` `dependencies` keys.
+ * with `.agents/runtime-deps.json` `dependencies` keys — the whole set, so
+ * this list documents the closure; {@link SHAREABLE_RUNTIME_DEPS} carries the
+ * policy about which of them a consumer may also declare.
  */
 const FRAMEWORK_RUNTIME_DEPS = [
+  '@babel/parser',
   'ajv',
   'ajv-formats',
+  'babel-runtime',
+  'escomplex-plugin-metrics-module',
+  'escomplex-plugin-syntax-babylon',
   'js-yaml',
   'minimatch',
   'picomatch',
-  'typhonjs-escomplex',
+  'typhonjs-ast-walker',
+  'typhonjs-escomplex-commons',
 ];
 
+/**
+ * Runtime dependencies the framework declares but does **not** claim
+ * exclusively, so a consumer declaring one is not evidence of a mutated
+ * manifest.
+ *
+ * This check exists to catch a consumer's `package.json` being written into
+ * with framework-internal packages. That inference only holds for packages
+ * nobody else would plausibly declare. `@babel/parser` and `babel-runtime`
+ * fail that test completely: a repository with its own Babel pipeline, AST
+ * tooling or legacy transpile output declares them for its own reasons, and
+ * failing `manifest-clean` for that would be a false positive on an ordinary
+ * consumer rather than a caught mutation.
+ *
+ * Kept as an explicit list rather than a heuristic: adding a widely-used
+ * package to the framework's runtime closure should be a deliberate decision
+ * to stop policing it, recorded here.
+ */
+const SHAREABLE_RUNTIME_DEPS = ['@babel/parser', 'babel-runtime'];
+
+/**
+ * Is this framework dependency's presence in a consumer manifest evidence of a
+ * mutated manifest?
+ *
+ * Only for packages the framework claims exclusively. A shareable one is
+ * declared by ordinary repositories for their own reasons.
+ *
+ * @param {string} dep
+ * @param {Record<string, string>} declared Consumer's merged declared deps.
+ * @returns {boolean}
+ */
+function isLeak(dep, declared) {
+  if (!(dep in declared)) return false;
+  return !SHAREABLE_RUNTIME_DEPS.includes(dep);
+}
+
+/** Exported for the manifest-mirror drift assertion. */
+export { FRAMEWORK_RUNTIME_DEPS, SHAREABLE_RUNTIME_DEPS };
+
 /** The verdict marker `mandrel doctor` prints when every check passes. */
 const DOCTOR_READY_MARKER = '✅  Ready';
 
@@ -157,7 +202,7 @@ export function checkManifestClean({ consumer, packageName, fs = nodeFs }) {
     ...(manifest.peerDependencies ?? {}),
   };
 
-  const leaked = FRAMEWORK_RUNTIME_DEPS.filter((dep) => dep in declared);
+  const leaked = FRAMEWORK_RUNTIME_DEPS.filter((dep) => isLeak(dep, declared));
   if (leaked.length > 0) {
     return {
       ok: false,

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -9,7 +9,7 @@
  *   - Problem Statement (aggregated severity profile)
  *   - Recommended Direction (rollup of recommendations by dimension)
  *   - Key Assumptions (carries the source-report links forward)
- *   - MVP Scope (the proposed Stories, one bullet per group)
+ *   - MVP Scope (the findings themselves, flat — Story #5332)
  *   - Key Files (explicit file paths so `/mandrel-plan` authoring has concrete
  *     anchors)
  *   - Not Doing (out-of-scope items by convention)
@@ -19,7 +19,6 @@
 
 import { SEVERITIES } from '../findings/severity.js';
 import { auditLabelFooterForFindings } from './audit-label-taxonomy.js';
-import { formatEpicGrouping } from './epic-grouping-directive.js';
 import {
   renderFingerprintFooter,
   renderSemanticKeyFooter,
@@ -93,35 +92,56 @@ function formatRecommendedDirection(findings) {
   return lines.join('\n');
 }
 
-function formatMVPScope(groups) {
+/**
+ * The findings, flat (Story #5332).
+ *
+ * This section used to render one numbered bullet per `groupFindings` group
+ * under a `## Grouping` directive — a partition the seed had already decided
+ * before the planner read a word of it, and at a grain (`groupFindings`'s) the
+ * planner's cohesion judgment never got to review. The measured result was a
+ * sweep of 44 findings arriving as 18 Stories. The seed now states what was
+ * found and lets N reach the planner undecided; container grouping is Gate
+ * #3's call at persist, where N is known.
+ *
+ * @param {object[]} findings
+ * @returns {string}
+ */
+function formatFindingsList(findings) {
+  return findings
+    .map((f) => {
+      const label = DIMENSION_LABEL[f.dimension] ?? f.dimension;
+      const file = f.files?.[0] ? ` (\`${f.files[0]}\`)` : '';
+      const severity = f.severity ? `${f.severity} · ` : '';
+      return `- **${f.title}** — ${severity}${label}${file}`;
+    })
+    .join('\n');
+}
+
+/**
+ * The machine-readable dedup identity, one footer set per group.
+ *
+ * Deliberately **not** folded into one footer over the whole sweep, and
+ * deliberately not attached to a visible bullet. Each group's fingerprint and
+ * location-based semantic-key footers are the identity the next sweep matches
+ * on (Story #4626), and the `audit::*` labels are the reason it ever looks at
+ * the issue at all — an indexed sweep answers exact lookups from the labelled
+ * pool without reaching the provider, so a Story missing the labels is
+ * invisible however good its fingerprints (Story #5307). They are HTML
+ * comments, so they carry no partition to the planner's eye while staying
+ * byte-identical to what the standalone-Stories path emits.
+ *
+ * @param {object[]} groups
+ * @returns {string}
+ */
+function formatDedupFooters(groups) {
   return groups
-    .map((g, idx) => {
-      const dims = g.dimensions.join(' / ');
-      const file = g.files[0] ? ` (\`${g.files[0]}\`)` : '';
-      // Carry each group's fingerprint (and location-based semantic-key)
-      // footer into the seed so a Story authored from it via `/mandrel-plan` inherits
-      // the dedup identity — without this the recommended `/mandrel-plan --seed-file`
-      // path is invisible to the next sweep's dedup (Story #4626). The footers
-      // are HTML comments, so they never render in the visible one-pager but
-      // stay machine-readable for the dedup probe.
+    .map((g) => {
       const findings = Array.isArray(g.findings) ? g.findings : [];
-      const footers = [
+      return [
         renderFingerprintFooter(findings),
         renderSemanticKeyFooter(findings),
-        // ...and the `audit::*` labels the dedup corpus is listed by.
-        //
-        // Without them a Story the chained planning path files is absent from
-        // the pool an indexed sweep matches against, and with an index in play
-        // the exact lookup is answered from that pool without ever reaching
-        // the provider — so the fingerprint footer above cannot rescue it. The
-        // two footers are therefore a pair: one carries the identity, the
-        // other carries the reason the next sweep ever looks at this issue
-        // (Story #5307).
         auditLabelFooterForFindings(findings),
-      ]
-        .map((f) => `   ${f}`)
-        .join('\n');
-      return `${idx + 1}. **${g.title}** — ${dims}${file}\n${footers}`;
+      ].join('\n');
     })
     .join('\n');
 }
@@ -165,10 +185,10 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   }
   const problem = formatProblemStatement(findings);
   const direction = formatRecommendedDirection(findings);
-  const scope = formatMVPScope(groups);
+  const scope = formatFindingsList(findings);
   const files = formatKeyFiles(groups);
   const assumptions = formatKeyAssumptions(sourceReports);
-  const grouping = formatEpicGrouping(groups);
+  const dedupFooters = formatDedupFooters(groups);
 
   return [
     '# Idea Seed: Audit Remediation',
@@ -187,16 +207,14 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
     '',
     '## MVP Scope',
     '',
-    scope || '_(no proposed stories)_',
+    scope || '_(no findings)_',
+    '',
+    dedupFooters,
     '',
     '## Key Files',
     '',
     files,
     '',
-    '## Grouping',
-    '',
-    grouping,
-    '',
     '## Not Doing',
     '',
     '- Findings with severity below the operator-selected threshold.',

package/.agents/scripts/lib/baselines/kinds/_crap-read.js

@@ -22,7 +22,6 @@
 
 import path from 'node:path';
 import { readBaselineAtRef } from '../../baseline-loader.js';
-import { resolveEscomplexVersion } from '../../crap-utils.js';
 import { loadBaseline } from '../../gates/baseline-store.js';
 import {
   loadFile as loadBaselineFile,
@@ -38,11 +37,6 @@ import {
  * epic-ref callers always know their own path); without one the reader
  * resolves the configured location for the `crap` kind itself.
  *
- * `escomplexVersion` is back-filled from the running scorer exactly as the
- * deleted projection stamped it — the v2 envelope does not carry the field, and
- * `escomplex-mismatch` is a fatal axis, so omitting it would fail every
- * baseline closed on a value that was never on disk.
- *
  * Returns `null` on any read/parse/schema failure; the preview gate maps that
  * to "no baseline" and fails open, as it always did.
  *
@@ -69,7 +63,6 @@ function readCrapBaselineFromTree({ baselinePath, projectRoot } = {}) {
   }
   return {
     kernelVersion: envelope.kernelVersion,
-    escomplexVersion: resolveEscomplexVersion(),
     scoringSemantics: envelope.scoringSemantics ?? null,
     tsTranspilerVersion:
       typeof envelope.tsTranspilerVersion === 'string'
@@ -135,7 +128,6 @@ export function loadCrapBaseline({
   // No-epicRef path delegates to readFromTree which already applies the
   // shape-check + tsTranspilerVersion back-fill, so a tree read returns either
   // a valid envelope or null. Epic-ref path bypasses that helper — shape-check
-  // + back-fill happens here.
   if (!epicRef) return parsed;
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     return null;

package/.agents/scripts/lib/baselines/kinds/crap.js

@@ -53,11 +53,29 @@ export { loadCrapBaseline } from './_crap-read.js';
 const __filename = fileURLToPath(import.meta.url);
 
 /**
- * Resolve the running `typhonjs-escomplex` version by walking up from this
- * module's directory and reading the nearest
- * `node_modules/typhonjs-escomplex/package.json`. Returns `'0.0.0'` when
- * the dependency cannot be found — callers treat that sentinel as
- * "unknown environment" and the writer refuses to persist a baseline.
+ * Package whose resolved version is stamped as the CRAP scorer identity.
+ *
+ * `escomplex-plugin-metrics-module` owns the Halstead and cyclomatic math. The
+ * displaced `typhonjs-escomplex` shell contributed a parser and a plugin bus
+ * and never computed a metric, so stamping it described the shell.
+ */
+const SCORER_PACKAGE = 'escomplex-plugin-metrics-module';
+
+/**
+ * Resolve the running scorer's version by walking up from this module's
+ * directory and reading the nearest `node_modules/<SCORER_PACKAGE>/package.json`.
+ *
+ * The package read is `escomplex-plugin-metrics-module`, which computes the
+ * metrics. It was `typhonjs-escomplex` until Story #5336 replaced that shell's
+ * parse and dispatch layers; reading a package that no longer exists would
+ * yield the sentinel below on every fresh install, and the writer would refuse
+ * to persist a baseline. (Locally it can look fine anyway — the walk-up escapes
+ * a worktree into the parent checkout, whose `node_modules` may still hold the
+ * removed package. CI's fresh clone has no such parent.)
+ *
+ * Returns `'0.0.0'` when the dependency cannot be found — callers treat that
+ * sentinel as "unknown environment" and the writer refuses to persist a
+ * baseline.
  *
  * @returns {string}
  */
@@ -68,7 +86,7 @@ export function kernelVersion() {
     const pkgPath = path.join(
       dir,
       'node_modules',
-      'typhonjs-escomplex',
+      SCORER_PACKAGE,
       'package.json',
     );
     if (fs.existsSync(pkgPath)) {
@@ -695,7 +713,14 @@ export function assessComparisonBasis(compareResult, opts = {}) {
  * transpiler's sourcemap. `startLine` is half the row identity key, so a
  * transpiler change makes the rows incomparable rather than merely stale; see
  * the `ts-transpiler-drift` axis below for the two exemptions that bound it.
- * `escomplexVersion` mismatch has always failed closed.
+ *
+ * There is no `escomplexVersion` axis. One existed, declared `fatal`, and
+ * could not fire in either direction: the v2 envelope does not carry the
+ * field, so the loaded-envelope pass excluded it as vacuous, and the peer pass
+ * back-filled the value from the running scorer before comparing it against
+ * the running scorer. A gate that presents as fatal and cannot fail is worse
+ * than an absent one, so it was removed rather than repaired — `scoringSemantics`
+ * is the axis that actually rejects an incompatible scorer.
  */
 /**
  * The one re-seed recipe every coordinate-invalidating axis ends on. Three
@@ -713,14 +738,6 @@ export const CRAP_COMPAT_AXES = [
   // missing-baseline and kernel-drift checks live in exactly one place;
   // each per-kind table composes them in with its own kind label.
   missingBaselineAxis('CRAP'),
-  {
-    name: 'escomplex-mismatch',
-    severity: 'fatal',
-    check: ({ baseline, runningEscomplexVersion }) =>
-      baseline && baseline.escomplexVersion !== runningEscomplexVersion
-        ? `[CRAP] scorer changed from ${baseline.escomplexVersion} to ${runningEscomplexVersion} — run 'npm run crap:update'`
-        : null,
-  },
   kernelDriftAxis('CRAP'),
   {
     name: 'scoring-semantics-drift',
@@ -874,9 +891,9 @@ export function evaluateBaselineCompatibility(ctx) {
  * predating both questions. The fourth (Story #4969) is about the `method`
  * half — a baseline still carrying ordinal-keyed anonymous rows.
  *
- * `escomplex-mismatch` and `kernel-drift` stay out — the v2 envelope carries
- * no `escomplexVersion`, so that axis would compare `undefined` to `undefined`
- * and pass vacuously, which is worse than not running it.
+ * `kernel-drift` stays out: it is a warn-level axis, and this pass turns a
+ * message into a fail-closed error. (`escomplex-mismatch` was the other
+ * exclusion until it was removed outright — see `CRAP_COMPAT_AXES`.)
  */
 const LOADED_ENVELOPE_AXES = [
   'scoring-semantics-drift',

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/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;