mandrel 2.58.0 → 2.60.0

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/orchestration/ticket-validator.js

@@ -3,7 +3,6 @@ import { normalizeOwnedProvenance } from '../findings/provenance-field.js';
 import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
-import { Logger } from '../Logger.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
 import { isExternalDependencyRef } from './plan-persist/external-deps.js';
 import {
@@ -41,38 +40,6 @@ function collectPathsFromText(text, paths) {
   }
 }
 
-/**
- * Resolve every acceptance line a Story declares, across both authoring
- * shapes (Story #4541).
- *
- * The canonical shape is a **serialized string body** with the criteria at
- * the ticket's **top level** — the machine contract persist syncs into the
- * body. `validateAcceptanceSubjectPrefix` used to read `body.acceptance` on
- * an object body only, so on every real plan it scanned nothing and the gate
- * silently passed. Union both sources (deduplicated) so the gate fires on
- * whichever surface the author used.
- *
- * @param {object} story
- * @returns {string[]}
- */
-function resolveAcceptanceLines(story) {
-  const lines = new Set();
-  if (Array.isArray(story?.acceptance)) {
-    for (const item of story.acceptance) lines.add(String(item ?? ''));
-  }
-  const body = story?.body;
-  let bodyAcceptance = null;
-  if (typeof body === 'string' && body.trim().length > 0) {
-    bodyAcceptance = parseStoryBodyOrThrow(story).acceptance;
-  } else if (body !== null && typeof body === 'object') {
-    bodyAcceptance = body.acceptance;
-  }
-  if (Array.isArray(bodyAcceptance)) {
-    for (const item of bodyAcceptance) lines.add(String(item ?? ''));
-  }
-  return [...lines];
-}
-
 function collectTaskPathReferences(task) {
   const paths = new Set();
   const body = task.body;
@@ -283,117 +250,6 @@ export function validateAcFreshness({
   return misses.map((m) => renderMissLine(m, baseBranchRef));
 }
 
-/**
- * Allowed leading Conventional-Commits types. Mirrors the `changelog-sections`
- * keys in `release-please-config.json` and the `type-enum` list in
- * `commitlint.config.js`. When a planner LLM prescribes a commit subject in a
- * Task acceptance item via the "Commit subject begins with '<prefix>:'" form,
- * the captured prefix must reduce to one of these types (optionally followed
- * by a `(scope)` qualifier) — anything else fails commitlint locally and
- * release-please's changelog parser on `main`, so the decompose is rejected
- * before the Story branch is ever cut.
- *
- * Epic #2501 introduced this guard after the legacy `baseline-refresh`
- * leading-token prescription created a wave of commit-msg hook failures
- * across story-deliver sub-agents. See
- * `.agents/skills/core/gates-and-baselines/SKILL.md` for the canonical refresh
- * shape (Conventional-Commits subject + `baseline-refresh: true` body
- * trailer).
- */
-const ALLOWED_COMMIT_TYPES = new Set([
-  'feat',
-  'fix',
-  'chore',
-  'refactor',
-  'perf',
-  'docs',
-  'style',
-  'test',
-  'build',
-  'ci',
-  'revert',
-]);
-
-/**
- * Regex matching the canonical "Commit subject begins with '<prefix>:'"
- * prescription shape the planner emits in `body.acceptance[]` entries.
- * The leading quote is captured loosely (single, double, or backtick) so the
- * three quoting styles the decomposer LLM has historically emitted all
- * match. The captured group is the prefix token *without* the trailing
- * colon — callers normalize by stripping an optional `(scope)` qualifier
- * before comparing against the allowed-types set.
- */
-const SUBJECT_PREFIX_RE = /Commit subject begins with ['"`]([^'"`]+):['"`]/g;
-
-/**
- * Scan every Story's `body.acceptance[]` for "Commit subject begins with
- * '<prefix>:'" prescriptions and reject the decompose when any captured
- * prefix is not a valid Conventional-Commits type.
- *
- * A captured prefix of the form `chore(baselines)` is accepted — the
- * leading `chore` is in the allowed-types set, and the `(scope)` qualifier
- * is the standard Conventional-Commits scope shape. A captured prefix of
- * the form `baseline-refresh` is rejected because no Conventional-Commits
- * type starts with that token.
- *
- * Only acceptance criteria are scanned; `body.goal` / `body.verify` /
- * `body.changes` are not commit-subject prescriptions by convention and
- * scanning them would surface false positives from prose that happens to
- * quote a forbidden prefix while explaining why it's forbidden.
- *
- * Both authoring shapes are covered (Story #4541): the canonical top-level
- * `acceptance[]` on a serialized string body, and the pre-serialize
- * `body.acceptance[]` object shape. Scanning only the latter made the gate
- * inert on every real plan.
- *
- * @param {object}   opts
- * @param {object[]} opts.tickets - Validated ticket hierarchy.
- * @throws {ValidationError} when one or more Story acceptance items
- *   prescribe a forbidden subject prefix. The error carries
- *   `code: 'forbidden-subject-prefix'` and a `violations[]` payload
- *   listing each `{ slug, prefix, line }` so the decompose loop can
- *   surface the exact offending text to the operator.
- */
-export function validateAcceptanceSubjectPrefix({ tickets }) {
-  const violations = [];
-  const stories = (tickets ?? []).filter((t) => t.type === 'story');
-  for (const story of stories) {
-    for (const line of resolveAcceptanceLines(story)) {
-      // Reset the global regex between iterations.
-      SUBJECT_PREFIX_RE.lastIndex = 0;
-      let match = SUBJECT_PREFIX_RE.exec(line);
-      while (match !== null) {
-        const rawPrefix = match[1];
-        // Strip an optional `(scope)` qualifier — `chore(baselines)` reduces
-        // to `chore` for the allowed-types check.
-        const type = rawPrefix.replace(/\(.*\)$/, '').trim();
-        if (!ALLOWED_COMMIT_TYPES.has(type)) {
-          violations.push({
-            slug: story.slug ?? '<unknown>',
-            prefix: rawPrefix,
-            line,
-          });
-        }
-        match = SUBJECT_PREFIX_RE.exec(line);
-      }
-    }
-  }
-  if (violations.length === 0) return;
-  const allowed = [...ALLOWED_COMMIT_TYPES].join('|');
-  const lines = violations
-    .map(
-      (v) =>
-        `  - "${v.slug}" → forbidden subject prefix "${v.prefix}:" in acceptance item: ${v.line}`,
-    )
-    .join('\n');
-  const err = new ValidationError(
-    `Cross-Validation Failed: ${violations.length} Story acceptance item(s) prescribe a non-Conventional-Commits subject prefix:\n${lines}\n\nAllowed leading types: ${allowed}. Use a Conventional-Commits subject (e.g. "chore(baselines): refresh ...") and a body trailer (e.g. "baseline-refresh: true") for machine-readable markers. See Epic #2501.`,
-    { violations },
-  );
-  err.code = 'forbidden-subject-prefix';
-  throw err;
-}
-
 /**
  * Render one missing-path warning with a remediation hint pointing at the
  * Story's `changes[]`. For `tests/**` paths we suggest the explicit
@@ -482,44 +338,55 @@ function assertAllTicketsAreStories({ tickets, stories }) {
 }
 
 /**
- * Return true when a Story object carries inline acceptance + verify
- * arrays — the inline-contract shape (Epic #3078) where the Story is itself the
- * implementation unit and acceptance / verify live on the Story body
- * rather than in child Task tickets.
+ * Return true when a Story carries a non-empty top-level `acceptance[]` —
+ * the inline-contract shape (Epic #3078) where the Story is itself the
+ * implementation unit and its criteria live on the Story rather than in
+ * child Task tickets.
  *
- * Both arrays must be present, be actual arrays, and contain at least
- * one entry. Either alone is insufficient — a Story with only
- * `acceptance[]` (no `verify[]`) cannot be implemented without a
- * verification handle, and a Story with only `verify[]` (no
- * `acceptance[]`) carries no observable criterion. Requiring both is the
- * inline-contract invariant every Story must satisfy.
+ * Story #5342 narrowed the invariant to `acceptance[]` alone. A Story with
+ * no observable criterion is genuinely unimplementable and nothing
+ * downstream can recover it; an empty `verify[]` only means the deliverer
+ * picks the commands, which the close gate chain runs regardless — so that
+ * half is a warning ({@link collectMissingVerifyWarnings}), not a refusal.
  */
-function hasInlineAcceptanceAndVerify(story) {
+function hasInlineAcceptance(story) {
   if (story === null || typeof story !== 'object') return false;
-  const { acceptance, verify } = story;
-  return (
-    Array.isArray(acceptance) &&
-    acceptance.length > 0 &&
-    Array.isArray(verify) &&
-    verify.length > 0
-  );
+  const { acceptance } = story;
+  return Array.isArray(acceptance) && acceptance.length > 0;
 }
 
 function assertEveryStoryHasInlineContract({ stories }) {
-  // Every Story is its own implementation
-  // unit and MUST carry a non-empty inline contract — top-level
-  // `acceptance[]` AND `verify[]`. A Story missing either is the legacy
-  // 4-tier shape that expected child Tasks; there is no Task tier any
-  // more, so such a Story is unimplementable and the decompose is
-  // rejected outright.
-  const missing = stories.filter((s) => !hasInlineAcceptanceAndVerify(s));
+  const missing = stories.filter((s) => !hasInlineAcceptance(s));
   if (missing.length === 0) return;
   const list = missing.map((s) => `"${s.title}" (${s.slug})`).join(', ');
   throw new Error(
-    `Cross-Validation Failed: ${missing.length} Story/Stories lack an inline acceptance + verify contract: ${list}. Every Story must carry non-empty top-level acceptance[] and verify[].`,
+    `Cross-Validation Failed: ${missing.length} Story/Stories lack an inline acceptance contract: ${list}. Every Story must carry a non-empty top-level acceptance[] — the outcomes a PR reviewer confirms once it lands.`,
   );
 }
 
+/**
+ * One warning per Story with no `verify[]` entry (Story #5342).
+ *
+ * Demoted from the hard refusal above: an absent verify list costs the
+ * acceptance critic its cheapest evidence, which is worth saying on the
+ * dry-run, but it never makes the Story unimplementable — the deliverer
+ * derives the commands and the close gate chain runs either way.
+ *
+ * @param {object[]} stories
+ * @returns {string[]}
+ */
+function collectMissingVerifyWarnings(stories) {
+  return (stories ?? [])
+    .filter((s) => !Array.isArray(s?.verify) || s.verify.length === 0)
+    .map(
+      (s) =>
+        `Story "${s.slug ?? s.title ?? '<unknown>'}" lists no verify[] entry — ` +
+        'the deliverer and the acceptance critic have no mechanical check to ' +
+        'read as evidence. Add the exact command or test path unless the ' +
+        'Story genuinely has none.',
+    );
+}
+
 /**
  * Shape-check the optional per-Story `provenance` field (Story #5045).
  *
@@ -619,19 +486,12 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
   assertAcyclic(slugAdjacency);
 
   // Story #4541 — refuse an unparseable Story body up front, with a named
-  // error pointing at the offending section + entry. Must precede both the
-  // subject-prefix scan and the freshness gate: each parses the body, and
-  // the freshness gate's net-new whitelist comes from `body.changes`, so a
-  // malformed body used to surface as a stale-path miss naming the paths the
-  // Story had legitimately declared.
+  // error pointing at the offending section + entry. Must precede the
+  // freshness gate: it parses the body, and its net-new whitelist comes from
+  // `body.changes`, so a malformed body used to surface as a stale-path miss
+  // naming the paths the Story had legitimately declared.
   assertStoryBodiesParse({ tickets });
 
-  // Reject any Task acceptance item that prescribes a non-Conventional-Commits
-  // subject prefix (e.g. legacy "Commit subject begins with 'baseline-refresh:'"
-  // from pre-Epic-#2501 planner output). Runs before the freshness gate so
-  // the failure mode is reported up-front rather than after a git probe.
-  validateAcceptanceSubjectPrefix({ tickets });
-
   // Hoist a single memoized (ref, path) → boolean probe shared across both
   // git-probe gates below. Without this, `validateAcFreshness` and
   // `validateStoryFileAssumptions` each maintain an independent cache, so a
@@ -643,7 +503,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
     ? makeMemoizedGitRunner(opts.gitRunner ?? defaultGitRunner)
     : null;
 
-  const warnings = [];
+  const warnings = [...collectMissingVerifyWarnings(stories)];
   // Story #5312: a goal / acceptance / verify path absent at base is a
   // warning the dry-run lists, not a refusal. Skipped when the caller omits
   // `baseBranchRef` so unit tests keep their semantics; production
@@ -702,5 +562,6 @@ export const _internal = {
   assertNoUnknownDeps,
   assertAcyclic,
   attachFindingsAndErrors,
-  hasInlineAcceptanceAndVerify,
+  hasInlineAcceptance,
+  collectMissingVerifyWarnings,
 };

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -77,20 +77,19 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'follow-ups',
   // v2 plan-run epilogue artifacts (posted on the primary Story)
   'plan-run-audit-roster',
-  'plan-run-sibling-coherence',
   'epic-run-state',
   'epic-run-progress',
   'epic-plan-state',
   // `parked-follow-ons` retired in Story #5114 with the module that was its
-  // only writer. A kind the reader still recognises but nothing emits is the
-  // same dead wiring in a new place.
+  // only writer, and `plan-run-sibling-coherence` in Story #5341 with the
+  // epilogue step that was its. Story #5367 retired two more on the same
+  // rule: `story-init` (its write went away in #5343 — the receipt is read
+  // off disk now) and `model-attribution` (its writer went with the per-Task
+  // progress writer in #3157, and its reader modules are deleted). A kind the
+  // reader still recognises but nothing emits is the same dead wiring in a
+  // new place.
   // Story #566 — per-phase wall-clock summary posted by single-story-close.js.
   'phase-timings',
-  // Story #831 — story-init upserts a `story-init` comment that
-  // surfaces `dependenciesInstalled` (and the underlying installStatus) so
-  // downstream workflow steps don't have to infer install state from
-  // node_modules presence.
-  'story-init',
   // Story #2128 — Phase 6 Epic Clarity Gate (CLI retired). Historical
   // `clarity-gate-update` comments may still exist on older tickets.
   'clarity-gate-update',
@@ -100,16 +99,6 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // operator can correct drift before Phase 8 decomposes from a stale
   // spec. Advisory: the run continues regardless of the report contents.
   'spec-freshness',
-  // Story #2813 — the per-Task progress writer (since retired under
-  // #3157) upserted a `model-attribution` comment on a Task ticket at
-  // the moment it transitioned to `agent::executing`, recording which
-  // Claude model was actively executing the work. One entry per Task
-  // (upsert is idempotent across resume re-runs). Story- and Epic-level
-  // rollups are computed at query time by `rollupModelAttribution` in
-  // `lib/orchestration/model-attribution.js` — no Story/Epic-scope
-  // emissions are written. Schema:
-  // `.agents/schemas/model-attribution.schema.json`.
-  'model-attribution',
   // Story #2894 — `finalize/post-handoff-comment.js` upserts an
   // `epic-handoff` comment on the Epic at the end of the bus-owned
   // finalize flow (after `open-or-locate-pr`
@@ -157,13 +146,13 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `graduator="<name>"` attr so independent graduators do not clobber each
   // other's comment; re-runs upsert in place.
   'cross-repo-deferred',
-  // Epic #4474 (PR3) / v2 Stage 3 — `plan-persist.js` upserts a single
-  // `plan-summary` comment on the primary Story at terminal persist
-  // success, carrying risk / routing receipts and the depends_on order
-  // table. One entry per plan; a re-persist upserts in place.
-  'plan-summary',
-  // v2 Stage 3 — flat Story persist checkpoint on every created Story
-  // (replaces epic-plan-state for new plans). plan-summary stays primary-only.
+  // v2 Stage 3 — the flat Story persist comment on every created Story
+  // (replaces epic-plan-state for new plans). Since Story #5343 it is the
+  // ONLY comment persist posts: the primary-Story-only `plan-summary` marker
+  // was retired and its content — story set, delivery order, deliver command
+  // — rides this marker on every Story. Story #5367 deleted the machine
+  // checkpoint that used to lead the body; the marker remains, and it is what
+  // makes a re-persist upsert in place.
   'story-plan-state',
   // Story #4535 — `plan-persist.js` upserts a `superseded-by` comment on
   // each `/mandrel-plan --tickets` source issue at persist time, naming the single

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`).