mandrel 2.58.0 → 2.59.0

package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js

@@ -0,0 +1,107 @@
+/**
+ * wave-collision-gate.js — the split gate (Story #5332).
+ *
+ * Kept out of `wave-serialisation.js` because it answers a different
+ * question. That module *predicts* what the dispatcher will do with a draft
+ * and renders the prediction as a receipt; this one decides whether the draft
+ * may be created at all, and so owns both the one enumeration the refusal and
+ * the receipt share and the shape reconciliation that enumeration needs.
+ *
+ * @module lib/orchestration/plan-persist/wave-collision-gate
+ */
+
+import { predictWaveSerialisation } from './wave-serialisation.js';
+
+/**
+ * Expose an assembled Story's declared footprint where `storyFootprint`
+ * looks for it.
+ *
+ * `assemblePlanStories` returns the persisted artifact — `{ slug, title,
+ * body, bodyObject, acceptance, depends_on, … }` — and carries the parsed
+ * `changes[]` inside `bodyObject`, not at the top level. `storyFootprint`
+ * reads `files` / `changes` / `changeset` only, so from Story #5313 (which
+ * retired the body scrape that had been widening the footprint out of the
+ * markdown) until this Story the production call saw an empty footprint for
+ * every assembled Story and predicted nothing — the unit fixtures passed a
+ * top-level `changes` and so could not show it. The prediction is now the
+ * split gate, and a gate that cannot see a declaration cannot fire, so the
+ * shapes are reconciled here rather than by widening the dispatcher's own
+ * predicate: the runtime's records (`resolve-stories.js`) already carry
+ * `changes` at the top level and pass through untouched.
+ *
+ * @param {object} story
+ * @returns {object} The same record, with a top-level `changes` when one can
+ *   be resolved from its `bodyObject`.
+ */
+function withDeclaredFootprint(story) {
+  if (!story || typeof story !== 'object') return story;
+  const declared = [story.files, story.changes, story.changeset].some(
+    (shape) => Array.isArray(shape) && shape.length > 0,
+  );
+  if (declared) return story;
+  const fromBody = story.bodyObject?.changes;
+  return Array.isArray(fromBody) ? { ...story, changes: fromBody } : story;
+}
+
+/**
+ * Render one refused pair as a report line.
+ *
+ * @param {{ wave: number, slugs: [string, string], paths: string[], source: string }} collision
+ * @returns {string}
+ */
+function formatCollision({ wave, slugs, paths, source }) {
+  const declared = paths.map((p) => `\`${p}\``).join(', ');
+  return `  - wave ${wave}: "${slugs[0]}" + "${slugs[1]}" both declare ${declared} (${source})`;
+}
+
+/**
+ * Compute the same-wave collisions of a draft and refuse an N>1 draft that
+ * has any — the split gate.
+ *
+ * ADR `20260912-5312` deleted every numeric plan-time ceiling and left the
+ * default-single policy enforced by prose plus `assertAcceptancePartition`,
+ * which refused only byte-identical acceptance text across siblings — a shape
+ * model output does not produce. The measured result was a plan of 18 Stories
+ * whose own summary comment recorded 39 shared files across 14 same-wave
+ * Stories: the plan refuted its own parallelism claim, after persist, with
+ * nothing acting on it.
+ *
+ * So the gate is the dispatcher's own predicate rather than a proxy for it. A
+ * pair {@link predictWaveSerialisation} names is a pair
+ * `stories-wave-tick.js` will refuse to co-dispatch, so the split buys no
+ * parallelism while still paying a delivery session per Story. Two remedies,
+ * both the author's to take before anything is created: merge the pair into
+ * the one Story it already is, or order it with `depends_on` so the members
+ * land in different waves.
+ *
+ * **N=1 can never trip it.** A single-Story draft has no pair to score, so
+ * the prediction is empty by construction.
+ *
+ * The computed collisions are **returned** so the caller hands the same value
+ * to the plan-summary receipt instead of recomputing it — a recomputation is
+ * how the refusal and the receipt would come to disagree.
+ *
+ * @param {ReturnType<typeof import('./summary.js').buildWaveTable>} waveTable
+ * @param {Array<object>} stories The assembled Stories, in draft order.
+ * @param {{ tempRoot?: string }} [options] Threaded to the predicate.
+ * @returns {ReturnType<typeof predictWaveSerialisation>}
+ * @throws {Error} When an N>1 draft has at least one colliding same-wave pair.
+ */
+export function assertNoWaveCollisions(waveTable, stories, options = {}) {
+  const list = Array.isArray(stories) ? stories : [];
+  const collisions = predictWaveSerialisation(
+    waveTable,
+    list.map(withDeclaredFootprint),
+    options,
+  );
+  if (list.length <= 1 || collisions.length === 0) return collisions;
+  throw new Error(
+    `[plan-persist] ${collisions.length} same-wave collision(s) — the ` +
+      'dispatcher will refuse to co-dispatch these pairs, so the split buys ' +
+      'no parallelism and costs a delivery session per Story:\n' +
+      `${collisions.map(formatCollision).join('\n')}\n` +
+      'Remedy: merge each pair into the one Story it already is (its stages ' +
+      'belong in `## Slicing`), or order the pair with `depends_on` so the ' +
+      'members sit in different waves.',
+  );
+}

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -8,13 +8,12 @@ import { computeStoryReachability } from './story-reachability.js';
  * `collectStoryAssumptionEntries` (Story #3302) and the sizing gate's
  * `resolveStoryBody` (Story #4271).
  *
- * The decomposer emits `body` as the canonical serialized **string**, but
- * the conflict passes (`indexConsumers`, `computeMissingBddScaffoldFindings`,
- * and the producer path scan in `collectStoryProducerPaths`) historically
- * read `story.body` only when it was already an object — so on the
- * production string shape the `implicit-cross-story-dep` and
- * `missing-bdd-scaffold` findings emitted nothing. Parsing the body once at the entry point and
- * threading the normalized Story through every pass restores parity.
+ * The decomposer emits `body` as the canonical serialized **string**, but the
+ * conflict passes (the producer path scan in `collectStoryProducerPaths`, and
+ * the two substring-match advisories Story #5332 retired) historically read
+ * `story.body` only when it was already an object — so on the production
+ * string shape they emitted nothing. Parsing the body once at the entry point
+ * and threading the normalized Story through every pass restores parity.
  *
  * `collectStoryAssumptionEntries` already parses string bodies itself, so a
  * normalized object body round-trips through it unchanged. The returned Story
@@ -76,16 +75,20 @@ function normalizeStoryBody(story) {
  * @property {string}          path        Producer path written by ≥2 Stories.
  * @property {string[]}        storySlugs  Story slugs in the conflict cluster.
  *
- * @typedef {object} ImplicitCrossStoryDepFinding
- * @property {'implicit-cross-story-dep'} kind
- * @property {'hard'|'soft'}   severity
- * @property {string}          path        Path consumed without a depends_on link.
- * @property {{ storySlug: string, taskSlug: string }} producer
- * @property {{ storySlug: string, taskSlug: string, sourceField: 'acceptance'|'verify' }} consumer
- *
- * @typedef {SharedEditorFinding | ImplicitCrossStoryDepFinding} ConflictFinding
+ * @typedef {SharedEditorFinding} ConflictFinding
  */
 
+/**
+ * Story #5332 retired the `implicit-cross-story-dep` and
+ * `missing-bdd-scaffold` findings, leaving `shared-editor` as the one
+ * conflict kind. Both matched a producer path as a **substring** of a
+ * consumer's `acceptance[]` / `verify[]` text — the noise-prone shape the
+ * planning-diet ADR (`20260912-5312`) itself calls out — and both had been
+ * unreachable on the real payload for most of their life (see
+ * {@link computeAssembledConflictFindings}). What they nudged for, ordering a
+ * consumer after its producer, the same-wave collision refusal now enforces
+ * on declarations rather than guesses at from prose.
+
 /**
  * Every conflict class is advisory (`'soft'`) since Story #5312: the
  * `planning.failOnSharedEditors` / `requireExplicitCrossStoryDeps` /
@@ -160,46 +163,6 @@ function indexProducers(stories) {
   return producers;
 }
 
-/**
- * Build the consumers index — `Array<{path, storySlug, taskSlug, sourceField}>`.
- *
- * For each Task, scan `body.acceptance` and `body.verify` joined text for
- * literal substring occurrences of any known producer path. Only producer
- * paths are matched (intersect-then-test), so free-text path-like tokens
- * that no one writes never produce false positives.
- *
- * A Story is not its own consumer — entries whose producer is the same
- * Story are skipped to keep the surface focused on cross-Story signal.
- */
-function indexConsumers(stories, producers) {
-  const consumers = [];
-  if (producers.size === 0) return consumers;
-  const producerPaths = Array.from(producers.keys()).sort(
-    (a, b) => b.length - a.length,
-  );
-  for (const story of stories) {
-    const body = story.body;
-    if (!body || typeof body !== 'object') continue;
-    for (const sourceField of ['acceptance', 'verify']) {
-      const items = Array.isArray(body[sourceField]) ? body[sourceField] : [];
-      if (items.length === 0) continue;
-      const joined = items.map((it) => String(it ?? '')).join('\n');
-      for (const path of producerPaths) {
-        if (!joined.includes(path)) continue;
-        const producerEntries = producers.get(path) ?? [];
-        if (producerEntries.some((p) => p.taskSlug === story.slug)) continue;
-        consumers.push({
-          path,
-          storySlug: storySlugOf(story),
-          taskSlug: story.slug,
-          sourceField,
-        });
-      }
-    }
-  }
-  return consumers;
-}
-
 function inSameWave(reach, slugA, slugB) {
   if (slugA === slugB) return false;
   const a = reach.get(slugA);
@@ -240,133 +203,6 @@ function computeSharedEditorFindings(producers, reach, severity) {
   return findings;
 }
 
-/**
- * Emit one `implicit-cross-story-dep` finding per consumer entry whose
- * producer Story is not transitively reachable from the consumer Story.
- *
- * Multiple producers per path are possible — the finding pins the *first*
- * producer in declaration order (sufficient signal; the operator typically
- * fixes the missing `depends_on` by linking to whichever Story they
- * recognize). Consumers already covered by a transitive dependency to
- * *some* producer are silently allowed even if other producers exist.
- */
-function computeImplicitDepFindings(consumers, producers, reach, severity) {
-  const findings = [];
-  for (const consumer of consumers) {
-    const producerEntries = producers.get(consumer.path) ?? [];
-    if (producerEntries.length === 0) continue;
-    const reachable = reach.get(consumer.storySlug) ?? new Set();
-    const alreadyDependsOnSome = producerEntries.some(
-      (p) => p.storySlug === consumer.storySlug || reachable.has(p.storySlug),
-    );
-    if (alreadyDependsOnSome) continue;
-    const producer = producerEntries[0];
-    findings.push({
-      kind: 'implicit-cross-story-dep',
-      severity,
-      path: consumer.path,
-      producer: {
-        storySlug: producer.storySlug,
-        taskSlug: producer.taskSlug,
-      },
-      consumer: {
-        storySlug: consumer.storySlug,
-        taskSlug: consumer.taskSlug,
-        sourceField: consumer.sourceField,
-      },
-    });
-  }
-  return findings;
-}
-
-/**
- * Compute `missing-bdd-scaffold` findings (Story #3857).
- *
- * The features-first delivery model requires every `.feature` file a Story
- * verifies against to already exist when that Story runs. When a Story's
- * `verify[]` references a `.feature` path that another Story declares with
- * `assumption: "creates"`, the consumer is correct only if the producer
- * lands in an *earlier* wave — otherwise the consumer's `verify[]` runs
- * against a file that does not yet exist and verification fails mid-delivery.
- *
- * A finding fires for each consumer/producer pair where:
- *   - the path ends in `.feature`,
- *   - a *different* Story declares that path as `assumption: "creates"`, and
- *   - the consumer Story does not transitively `depends_on` the producer
- *     (i.e. they share a wave, or the producer runs later).
- *
- * The finding is advisory (`'soft'`) — it is a nudge to add a `depends_on`
- * link to the wave-0 scaffold Story (or to the producing Story), not a hard
- * block. The remediation is the same shape as `implicit-cross-story-dep`:
- * order the consumer after the producer so the scaffold lands first.
- *
- * @param {object[]} stories
- * @param {Map<string, Set<string>>} reach  Transitive predecessor sets.
- * @param {'soft'|'hard'} severity
- * @returns {object[]} `missing-bdd-scaffold` findings.
- */
-function computeMissingBddScaffoldFindings(stories, reach, severity) {
-  // Index every `.feature` path declared `creates` to its producing Story.
-  // A path may be created by more than one Story (unusual); pin the first in
-  // declaration order, mirroring the implicit-dep finding's single-producer
-  // shape.
-  const featureCreators = new Map(); // path -> storySlug (first creator)
-  for (const story of stories) {
-    const body = story?.body;
-    if (!body || typeof body !== 'object') continue;
-    const changes = Array.isArray(body.changes) ? body.changes : [];
-    for (const change of changes) {
-      if (
-        change === null ||
-        typeof change !== 'object' ||
-        change.assumption !== 'creates' ||
-        typeof change.path !== 'string' ||
-        !change.path.endsWith('.feature')
-      )
-        continue;
-      if (!featureCreators.has(change.path)) {
-        featureCreators.set(change.path, storySlugOf(story));
-      }
-    }
-  }
-  if (featureCreators.size === 0) return [];
-
-  const creatorPaths = Array.from(featureCreators.keys()).sort(
-    (a, b) => b.length - a.length,
-  );
-  const findings = [];
-  const seen = new Set(); // dedupe `${consumerSlug}::${path}` pairs
-  for (const story of stories) {
-    const body = story?.body;
-    if (!body || typeof body !== 'object') continue;
-    const verifyItems = Array.isArray(body.verify) ? body.verify : [];
-    if (verifyItems.length === 0) continue;
-    const joined = verifyItems.map((it) => String(it ?? '')).join('\n');
-    const consumerSlug = storySlugOf(story);
-    for (const path of creatorPaths) {
-      if (!joined.includes(path)) continue;
-      const producerSlug = featureCreators.get(path);
-      // A Story that creates the file it verifies is fine — no cross-Story gap.
-      if (producerSlug === consumerSlug) continue;
-      // Producer already runs in an earlier wave → consumer is correctly
-      // ordered, scaffold lands first, no finding.
-      const reachable = reach.get(consumerSlug) ?? new Set();
-      if (reachable.has(producerSlug)) continue;
-      const key = `${consumerSlug}::${path}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      findings.push({
-        kind: 'missing-bdd-scaffold',
-        severity,
-        path,
-        producer: { storySlug: producerSlug },
-        consumer: { storySlug: consumerSlug, sourceField: 'verify' },
-      });
-    }
-  }
-  return findings;
-}
-
 /**
  * Public entry point. Walks the normalized ticket spec once and returns
  * the structured cross-Story findings array. Every finding is `'soft'`
@@ -384,13 +220,8 @@ export function computeConflictFindings({ stories } = {}) {
   // shape across every conflict pass.
   const storyList = (stories ?? []).map(normalizeStoryBody);
   const producers = indexProducers(storyList);
-  const consumers = indexConsumers(storyList, producers);
   const reach = computeStoryReachability(storyList);
-  return [
-    ...computeSharedEditorFindings(producers, reach, SOFT),
-    ...computeImplicitDepFindings(consumers, producers, reach, SOFT),
-    ...computeMissingBddScaffoldFindings(storyList, reach, SOFT),
-  ];
+  return computeSharedEditorFindings(producers, reach, SOFT);
 }
 
 /**
@@ -402,11 +233,11 @@ export function computeConflictFindings({ stories } = {}) {
  * persisted. That is not a cosmetic ordering nit: the canonical authoring shape
  * carries `acceptance[]` / `verify[]` at the ticket's **top level**, and it is
  * assembly's `syncContractFieldFromTopLevel` that folds them into the body.
- * `indexConsumers` scans `body.acceptance` / `body.verify` for producer paths —
- * so on the real payload it scanned two empty arrays, and every
- * `implicit-cross-story-dep` and `missing-bdd-scaffold` finding was silently
- * unreachable. Running the passes again over the serialized bodies restores
- * them.
+ * The two retired advisories scanned `body.acceptance` / `body.verify` for
+ * producer paths, so on the real payload they scanned two empty arrays and
+ * were silently unreachable. Running the passes again over the serialized
+ * bodies is what keeps the surviving `shared-editor` pass honest about what
+ * persist actually writes.
  *
  * @param {{ stories: Array<{ slug: string, title: string, body: string, depends_on?: string[] }> }} args
  * @returns {ConflictFinding[]}
@@ -457,13 +288,7 @@ export function conflictFindingKey(finding) {
  * of this list is how readers drift apart, so it is defined exactly once and
  * imported.
  */
-export const CONFLICT_KINDS = Object.freeze(
-  new Set([
-    'shared-editor',
-    'implicit-cross-story-dep',
-    'missing-bdd-scaffold',
-  ]),
-);
+export const CONFLICT_KINDS = Object.freeze(new Set(['shared-editor']));
 
 /**
  * Render a conflict finding as a human-readable line. Every finding is soft
@@ -476,12 +301,6 @@ export function renderHardConflictError(finding) {
     const stories = finding.storySlugs.map((s) => `"${s}"`).join(', ');
     return `Shared-editor conflict: "${finding.path}" is written by ${finding.storySlugs.length} concurrent Stories (${stories}). Add depends_on chains between them or split the edits into a dedicated late-wave wiring Story.`;
   }
-  if (finding.kind === 'implicit-cross-story-dep') {
-    return `Implicit cross-Story dependency: Story "${finding.consumer.storySlug}" references "${finding.path}" (produced by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but Story "${finding.consumer.storySlug}" has no depends_on link to Story "${finding.producer.storySlug}". Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story or remove the reference.`;
-  }
-  if (finding.kind === 'missing-bdd-scaffold') {
-    return `Missing BDD scaffold: Story "${finding.consumer.storySlug}" verifies against "${finding.path}" (created by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but "${finding.consumer.storySlug}" has no depends_on path to "${finding.producer.storySlug}" — the .feature file is scaffolded in the same wave (or later), so verification runs before the file exists. Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story so the scaffold lands in an earlier wave.`;
-  }
   // Findings from other passes carry their own message — render it rather
   // than a shape-blind generic line, so the soft surface
   // (`surfaceSoftConflictFindings`) stays legible for every kind.
@@ -496,10 +315,7 @@ export const _internal = {
   collectStoryProducerPaths,
   WRITE_IMPLYING_ASSUMPTIONS,
   indexProducers,
-  indexConsumers,
   computeStoryReachability,
   inSameWave,
   computeSharedEditorFindings,
-  computeImplicitDepFindings,
-  computeMissingBddScaffoldFindings,
 };

package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js

@@ -1,7 +1,6 @@
 /**
  * Story authoring guidance — the two prose constants the story-author prompt
- * and the `core/scope-triage` skill both cite, stated once so the surfaces
- * cannot drift.
+ * cites, stated once so no second copy can drift.
  *
  * Story #5312 deleted the numeric sizing model that used to live beside
  * them: `DEFAULT_MODEL_CAPACITY` with its soft / hard session-mass ceilings,
@@ -18,12 +17,16 @@
 /**
  * `DELIVERABLE_GRANULARITY_GUIDANCE` is the **single source of truth** for the
  * deliverable-granularity definition of a Story (Story #3777). It is stated
- * ONCE here and consumed by BOTH the story-author prompt template and the
- * authoring SKILL.
+ * ONCE here and consumed by the story-author prompt template.
+ *
+ * Story #5332 re-anchored the definition off "a single reviewer-sized PR":
+ * that anchor read as a size ceiling and fragmented cohesive sweeps, so the
+ * only stated sizing test is now cohesion — one coherent change with one
+ * reason to exist.
  */
 export const DELIVERABLE_GRANULARITY_GUIDANCE = Object.freeze({
   definition:
-    'A Story is a **capability slice a frontier model delivers and self-verifies in one pass** — a shippable slice a reviewer would accept as a single PR, a capability or user-visible surface, **not a single module or file**. Fold module-level slices into the capability they belong to rather than emitting one Story per module.',
+    'A Story is a **capability slice a frontier model delivers and self-verifies in one pass** — one coherent change with one reason to exist, a capability or user-visible surface, **not a single module or file**. Fold module-level slices into the capability they belong to rather than emitting one Story per module. A remediation sweep over one subsystem is one Story; its stages belong in `## Slicing`, not in sibling tickets.',
   singleConsumerRule:
     '**Single-consumer merge rule.** A Story whose only consumer is one sibling Story should be **merged into that sibling** rather than emitted separately — a single-consumer downstream slice is not its own unit of work.',
   envelopeFloor:

package/.agents/scripts/lib/runtime-deps/dep-resolution.js

@@ -0,0 +1,155 @@
+/**
+ * runtime-deps/dep-resolution — is a declared runtime dependency actually
+ * there, is it the right major, and how do we say so.
+ *
+ * `.agents/` materializes into the consumer's repository root, so every
+ * framework runtime dependency resolves from *their* `node_modules`. A range
+ * in `.agents/runtime-deps.json` therefore documents a requirement it cannot
+ * enforce, and the preflight guard needs to compare the range against what
+ * actually resolved.
+ *
+ * Deliberately major-only, and deliberately not `semver`. The framework's
+ * runtime ranges are all `^`, whose whole contract is "this major"; pulling in
+ * a semver implementation to decide one comparison would add a dependency to
+ * the very closure this module exists to keep honest.
+ *
+ * @module lib/runtime-deps/dep-resolution
+ */
+
+/**
+ * Leading major number of a version or a caret/tilde range, or `null`.
+ *
+ * Module-local: `majorMismatch` is the only question callers have.
+ *
+ * Anything this cannot read as `<major>.` — `*`, a tag, a git URL, a
+ * `>=x <y` span — yields `null` and is treated as "not range-checked". That
+ * asymmetry is intentional: a conservative miss is a no-op, while a false
+ * positive blocks a working install.
+ *
+ * @param {string|null|undefined} spec
+ * @returns {number|null}
+ */
+function majorOf(spec) {
+  if (typeof spec !== 'string') return null;
+  const match = /^[\^~]?(\d+)\./.exec(spec.trim());
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Does `resolved` sit outside the major `range` names?
+ *
+ * Module-local: `checkRuntimeDeps` is the only caller, and exporting it only
+ * for a test would be a production-dead export.
+ *
+ * `false` whenever either side is unreadable, so an unparseable range or an
+ * unreadable installed version is never reported as a mismatch.
+ *
+ * `0.x` majors compare as written: `^0.1.0` and `0.2.1` differ in minor, not
+ * major, so this does not separate them. Accepted — the `0.x` packages in the
+ * closure are terminal, and the range this exists to enforce is
+ * `@babel/parser`'s `^7`.
+ *
+ * @param {string|null|undefined} range
+ * @param {string|null|undefined} resolved
+ * @returns {boolean}
+ */
+function majorMismatch(range, resolved) {
+  const want = majorOf(range);
+  if (want === null) return false;
+  const got = majorOf(resolved);
+  if (got === null) return false;
+  return want !== got;
+}
+
+/**
+ * Is a package present in the resolvable tree?
+ *
+ * The bare specifier is tried first, then `<name>/package.json`. The fallback
+ * is not belt-and-braces: a package with no `main` and no `exports` — which
+ * `typhonjs-escomplex-commons` and `babel-runtime` both are — cannot be
+ * resolved by name at all, and is reached only by deep path. Probing the bare
+ * name alone would report such a package missing while it sits installed, and
+ * this guard exits the process on that verdict.
+ *
+ * @param {string} dep
+ * @param {(specifier: string) => string} resolve
+ * @returns {boolean}
+ */
+export function isResolvable(dep, resolve) {
+  try {
+    resolve(dep);
+    return true;
+  } catch {
+    // fall through to the manifest probe
+  }
+  try {
+    resolve(`${dep}/package.json`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remediation text for a resolved dependency whose major differs from the
+ * range the framework declares.
+ *
+ * Named separately from the missing-deps message because the remedy differs:
+ * the package is installed, so installing again changes nothing. What is
+ * wrong is the version the consumer's own tree resolves, which only they can
+ * change.
+ *
+ * @param {{name: string, required: string, resolved: string}[]} mismatched
+ * @param {{ root: string }} ctx
+ * @returns {string}
+ */
+export function formatMismatchedDepsMessage(mismatched, { root }) {
+  const lines = mismatched.map(
+    (m) => `  - ${m.name}: need ${m.required}, resolved ${m.resolved}`,
+  );
+  return [
+    'Mandrel framework runtime dependency version mismatch:',
+    ...lines,
+    '',
+    `Resolved from: ${root}`,
+    'These packages are resolved from your repository, not from mandrel, so',
+    'the version your tree installs is the version the framework gets. Pin a',
+    'compatible major in your package.json and reinstall.',
+  ].join('\n');
+}
+
+/**
+ * Resolve each required package via the injected `resolve` seam and collect
+ * the ones that fail. `resolve` is typically `require.resolve` bound to the
+ * framework module location; it throws `MODULE_NOT_FOUND` when a package is
+ * absent from the resolvable `node_modules`.
+ *
+ * @param {{ required: string[], resolve: (specifier: string) => string }} opts
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function checkRuntimeDeps({
+  required,
+  resolve,
+  ranges = null,
+  readVersion = null,
+}) {
+  const missing = [];
+  const mismatched = [];
+  for (const dep of required) {
+    if (!isResolvable(dep, resolve)) {
+      missing.push(dep);
+      continue;
+    }
+    if (!ranges || !readVersion) continue;
+    const range = ranges[dep];
+    const resolved = readVersion(dep);
+    if (majorMismatch(range, resolved)) {
+      mismatched.push({ name: dep, required: range, resolved });
+    }
+  }
+  return {
+    ok: missing.length === 0 && mismatched.length === 0,
+    missing,
+    mismatched,
+  };
+}

package/.agents/scripts/lib/runtime-deps/ensure-installed.js

@@ -28,12 +28,13 @@
  */
 
 import { createRequire } from 'node:module';
-import { loadRuntimeDepsManifest } from './manifest.js';
+import { resolveDependencyVersion } from '../dependency-version.js';
 import {
   checkRuntimeDeps,
-  detectPackageManager,
-  formatMissingDepsMessage,
-} from './preflight.js';
+  formatMismatchedDepsMessage,
+} from './dep-resolution.js';
+import { loadRuntimeDepsManifest } from './manifest.js';
+import { detectPackageManager, formatMissingDepsMessage } from './preflight.js';
 
 // `require.resolve` bound to this module's location walks `node_modules`
 // upward from `.agents/scripts/lib/runtime-deps/` to the consumer root —
@@ -50,7 +51,8 @@ const frameworkRequire = createRequire(import.meta.url);
  *   cwd?: string,
  *   stderr?: { write: (s: string) => void },
  *   exit?: (code: number) => void,
- *   manifest?: { required: string[] },
+ *   manifest?: { required: string[], dependencies?: Record<string,string> },
+ *   readVersion?: (name: string) => string | null,
  * }} [opts]
  * @returns {{ ok: boolean, missing: string[] }}
  */
@@ -61,6 +63,7 @@ export function ensureRuntimeDepsInstalled(opts = {}) {
     stderr = process.stderr,
     exit = process.exit,
     manifest = safeLoadManifest(),
+    readVersion,
   } = opts;
 
   // A manifest we cannot read is a packaging defect the drift test owns —
@@ -70,17 +73,49 @@ export function ensureRuntimeDepsInstalled(opts = {}) {
   const result = checkRuntimeDeps({
     required: manifest.required,
     resolve: requireResolve,
+    ranges: manifest.dependencies ?? null,
+    readVersion: readVersion ?? defaultReadVersion,
   });
   if (result.ok) return result;
 
-  const packageManager = detectPackageManager(cwd);
-  stderr.write(
-    `${formatMissingDepsMessage(result.missing, { root: cwd, packageManager })}\n`,
-  );
+  stderr.write(`${describeFailure(result, cwd)}\n`);
   exit(1);
   return result;
 }
 
+/**
+ * Remediation text for a failed check.
+ *
+ * Absence is reported first: a package that is not installed cannot have a
+ * version, and installing it is the prerequisite for any version complaint
+ * being actionable.
+ *
+ * @param {{ missing: string[], mismatched: {name: string, required: string, resolved: string}[] }} result
+ * @param {string} cwd
+ * @returns {string}
+ */
+function describeFailure(result, cwd) {
+  if (result.missing.length === 0) {
+    return formatMismatchedDepsMessage(result.mismatched, { root: cwd });
+  }
+  const packageManager = detectPackageManager(cwd);
+  return formatMissingDepsMessage(result.missing, {
+    root: cwd,
+    packageManager,
+  });
+}
+
+/**
+ * Read a resolved package's version through the framework's own resolution,
+ * so the version checked is the one the framework's imports will load.
+ *
+ * @param {string} name
+ * @returns {string | null}
+ */
+function defaultReadVersion(name) {
+  return resolveDependencyVersion(name, frameworkRequire);
+}
+
 /**
  * Load the manifest, swallowing a read/parse failure to `null` so the guard
  * stays inert on a packaging defect (see `ensureRuntimeDepsInstalled`).