@open-agent-toolkit/cli 0.2.25 → 0.2.27

package/assets/skills/oat-explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-explainer-kit
-version: 1.0.3
+version: 1.0.5
 description: Use when building project explainers or recaps from OAT configuration, state, and lifecycle artifacts.
 disable-model-invocation: false
 user-invocable: true
@@ -19,7 +19,10 @@ Adapt OAT project context into the versioned request consumed by the canonical
 - Derive canonical project or repository output roots.
 - Bind OAT lifecycle artifacts to generic recipe source roles.
 - Resolve project explainer and recap intent before invoking the core.
+- Resolve one provider-neutral set planner for unattended project recaps.
 - Require lifecycle callers to construct a brief-aware author seam.
+- Require first-class browser-evidence and whole-set visual-review providers
+  for unattended project recaps.
 
 ## Dependency Direction
 
@@ -34,7 +37,7 @@ rollback, and operator-owned real-wrapper gate, use `references/migration.md`.
 
 Before reading OAT config or invoking the core, call
 `scripts/check-core.mjs#checkCoreCompatibility` with this installed skill
-directory and minimum core version `2.0.0`. Continue only when it returns
+directory and minimum core version `2.0.3`. Continue only when it returns
 `ok: true`.
 
 - Missing core: stop and show
@@ -55,7 +58,7 @@ Call `scripts/run.mjs#runOatExplainer` with the repository root, project
 invocation, active project path, recipe, slug, lifecycle mode, and any explicit
 runtime overrides. The adapter:
 
-1. checks the user-scoped installed core at minimum version `2.0.0`;
+1. checks the user-scoped installed core at minimum version `2.0.3`;
 2. resolves only the public `explainers.*` and `workflow.explainers.*` keys;
 3. derives the canonical project output root;
 4. binds approved OAT artifacts to the recipe's single `project` source set;
@@ -69,15 +72,40 @@ Missing optional artifacts are omitted, but at least one approved lifecycle
 artifact is required. An explicit supplied fact-base path bypasses artifact
 federation and is passed through as `factBase.mode: supplied`.
 
-Before invocation, read `references/author-callback.md` and construct exactly
-one provider-neutral author seam in both modes: in-process callers supply
-`author`, while JSON/CLI callers supply `authorModulePath` naming a module with
-an `author` function export. The callback consumes `author-request/v2` with the
-recipe brief and fact base inlined, plus theme and any recipe-selected artistic
-shell. It may propose expansion only through recipe profile IDs. The adapter
-validates and resolves that executable input before passing it to
-`core.runExplainer`; callbacks and module paths never enter the persisted run
-request.
+Before invocation, read `references/author-callback.md`. Unattended
+`project-recap` runs require exactly one provider-neutral set planner:
+in-process callers supply `planSet`, while JSON/CLI callers supply
+`planSetModulePath` naming a module with a `planSet` function export. The
+adapter resolves this executable capability and passes only the callback to the
+core. It never persists provider configuration or module paths.
+
+Construct exactly one provider-neutral author seam in both modes: in-process
+callers supply `author`, while JSON/CLI callers supply `authorModulePath` naming
+a module with an `author` function export. The core invokes that callback once
+per planned artifact. Every request carries the immutable shared `setContext`,
+the matching `plannedArtifact`, the recipe brief, theme, and any
+recipe-selected artistic shell. Those bundled inputs are the required
+medium-specific guidance; an optional visual-explainer installation may enhance
+provider execution but is never required. The adapter validates and resolves
+executable inputs before passing them to `core.runExplainer`; callbacks and
+module paths never enter the persisted run request.
+
+Also read `references/visual-review-callback.md`. Unattended `project-recap`
+runs require exactly one trusted launched-Chromium browser session and one
+whole-set visual critic. In-process callers supply a branded `browserSession`
+created by the compatible core and `visualCritic`; JSON/CLI callers supply
+`browserSessionModulePath` and `visualCriticModulePath`, naming modules with
+matching exports. Bare browser callbacks and caller-authored runtime metadata
+are rejected. These are first-class adapter inputs; do not place either
+provider in `coreOptions`.
+
+The adapter resolves all executable providers before core invocation, enforces
+direct-versus-module mutual exclusion, and requires distinct identities for
+authoring, fact criticism, browser evidence, and visual criticism. A missing,
+forged, or deterministic fixture session fails production validation before the
+core runs. A runtime browser or visual-review failure is retained by the core
+as `built-needs-review`, never as a successful durability or publication
+outcome.
 
 Unattended project runs pass `approved-oat-artifacts` provenance to the core's
 content-approval seam and never prompt. Automated completion and

package/assets/skills/oat-explainer-kit/references/author-callback.md

@@ -15,6 +15,10 @@ core constructs that request from recipe-owned policy:
 
 - `brief` contains the prose loaded from the floor entry or expansion profile's
   `briefRef`; the author must treat the inlined brief as its editorial contract.
+- `visualAuthoringGuidance` contains the installed core's bundled
+  representation, hierarchy, responsive-navigation, table, diagram, and deck
+  rules. Treat it as the medium baseline; do not read ambient or home-directory
+  guidance.
 - `factBase` contains the reconciled evidence for the run. Ground claims in that
   fact base and do not replace it with ambient project context.
 - `authoring` selects the output path. Return Markdown for `markdown` and a
@@ -24,23 +28,21 @@ core constructs that request from recipe-owned policy:
   brief's license to elaborate.
 - A floor request may include `floor.requiredNarrative`, which identifies the
   narrative coverage checked later as non-blocking guidelines.
+- `setContext` is the complete immutable planner-owned portfolio and shared
+  ledger. `plannedArtifact` is the exact entry assigned to this callback;
+  preserve its identity, sources, draft, and visual intent.
 
 Return one matching `explainer-kit.author-result/v2`: preserve `artifactId`,
 set exactly one of `content.markdown` or `content.html`, and include
 `provenance`. Do not persist provider credentials or callback configuration in
 the result.
 
-## Expansion
+## Planner-owned expansion
 
-Only a floor result may propose expansion. Put each proposal in
-`proposedArtifacts` as `{id, profileId, rationale}`. Do not choose an artifact
-type, authoring mode, brief, or shell in the proposal; the referenced recipe
-profile, selected by `profileId`, owns those values.
-
-The core validates proposal IDs, profile membership, collisions, and finite
-caps. It rejects malformed proposals, records over-limit proposals as warnings,
-and issues a new author request for every accepted artifact. Handle each
-follow-up request independently and do not recursively propose more artifacts.
+The set planner finalizes the complete floor and expansion portfolio before any
+author runs. Authors must not return `proposedArtifacts` or otherwise add,
+remove, replace, or reorder portfolio entries. Handle only the supplied
+`plannedArtifact`; the core rejects author-driven expansion after planning.
 
 ## Lifecycle invocation
 

package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md

@@ -86,13 +86,48 @@ The resolved callback is passed only as the `author` option to
 `run-request.json`, or another retained data contract. Interactive runs use the
 same author contract and differ only at the later approval gate.
 
+## Browser and visual-review execution
+
+Every unattended `project-recap` must provide exactly one browser-evidence
+session and exactly one whole-set visual critic through the adapter's
+first-class boundary. In-process callers pass `browserSession`, created by the
+compatible core's `createBrowserProbeSession()`, and `visualCritic`. JSON-only
+and official CLI callers pass `browserSessionModulePath` and
+`visualCriticModulePath`, naming modules whose matching exports are
+`browserSession` and `visualCritic`. Direct-plus-module conflicts, invalid
+exports, bare `browserProbe` inputs, and the legacy
+`coreOptions.browserProbe`, `coreOptions.browserSession`, or
+`coreOptions.visualCritic` routes fail before core invocation.
+
+The author, fact critic, branded session probe, and visual critic must have
+distinct callback identities. The adapter asks the loaded core to validate the
+session's private brand and launched-Chromium runtime before passing it to
+`core.runExplainer`. Executable callbacks, descriptors, and module paths never
+enter the retained run request. Deterministic fixture sessions are rejected for
+unattended project recaps. See `visual-review-callback.md` for the session,
+request/result, and byte-bound whole-set review contracts.
+
+The core retains canonical 320, 768, and 1440 viewport screenshots, paired
+`explainer-kit.browser-evidence/v2` metrics with launched Chromium name,
+version, and capture identity, each review request/result, cohesion
+observations, and any one-pass revision record. Missing, malformed, forged,
+cross-record mismatched, stale, or failed review-chain evidence terminates as
+`built-needs-review`; durability and publication remain blocked.
+
 ## Tracked-run finalization
 
 `planTrackedRunFinalization(request, context)` is the shared command planner for
 tracked project explainer and recap runs. The request contains `runRoot`,
 `manifestPath`, `commitMode`, and optional `relocatedFrom`. Context supplies the
-repository root, project name, and, for `completion-bookkeeping`, the existing
-full artifact commit SHA.
+repository root, project name, an explicit compatible `coreRoot`, and, for
+`completion-bookkeeping`, the existing full artifact commit SHA. Finalization
+dynamically loads the versioned package-coverage contract from that core root;
+it does not maintain an adapter-local path list.
+
+A core `built-needs-review` outcome is a terminal review gate, not a
+non-durable success. The planner rejects it before producing artifact,
+attestation, evidence-commit, or push commands. The recap must instead be
+reviewed and rebuilt to a passing visual-review outcome.
 
 The returned stages must run in order:
 
@@ -152,6 +187,9 @@ export remains committed, the mutable records retain the warning and
 complete. A later attestation may recover durability without repeating the
 archive.
 
+This recovery path applies only to `built-not-durable`.
+`built-needs-review` cannot be exported, attested, finalized, or pushed.
+
 Post-archive summary and PR recap links target `projectRecapExport.exportRoot`
 under `.oat/repo/reference/project-recaps/` on the current head branch. The
 tracked summary export and the PR body may carry that link; the gitignored

package/assets/skills/oat-explainer-kit/references/visual-review-callback.md

@@ -0,0 +1,72 @@
+# Browser and visual-review callbacks
+
+Unattended project recaps require two provider-neutral executable seams. Supply
+each seam either directly or through a module path, never both:
+
+| Role             | Direct input     | Module-path input          | Required export  |
+| ---------------- | ---------------- | -------------------------- | ---------------- |
+| Browser evidence | `browserSession` | `browserSessionModulePath` | `browserSession` |
+| Whole-set review | `visualCritic`   | `visualCriticModulePath`   | `visualCritic`   |
+
+Do not route these callbacks through `coreOptions`. The adapter resolves and
+validates both providers before core invocation and keeps callbacks and module
+paths out of retained requests.
+
+## Browser evidence
+
+Create the direct descriptor with the compatible core's
+`createBrowserProbeSession()`. A module-path provider exports that branded
+descriptor as `browserSession`; it does not export a bare callback or a
+caller-authored metadata object. The core derives Chromium type and version
+from the launched `Browser` instance and validates the private session brand.
+Callers remain responsible for closing the session.
+
+The descriptor's probe receives one provider-neutral request for each artifact,
+viewport, and required interaction scenario. The request includes the rendered
+artifact, exact viewport dimensions, scenario, interaction expectations, and,
+for the default scenario, an absolute `screenshotPath`. The probe writes a PNG
+to that path and returns measured browser facts:
+
+- `pageOverflowX` as a boolean;
+- `clippedX`, `viewportClipped`, and `unreadableHeadings` as arrays;
+- `reducedMotion` as a boolean;
+- `keyboard` as an object describing observed key behavior; and
+- applicable deck, theme-toggle, animation, and layout measurements.
+
+For unattended project recaps the core chooses the canonical 320, 768, and 1440
+widths. The retained PNG signature and IHDR dimensions must match the requested
+viewport. The core writes paired metrics JSON itself; callback assertions do
+not substitute for retained evidence. Those
+`explainer-kit.browser-evidence/v2` records retain the launched Chromium name,
+version, capture settings, and stable capture identity. Deterministic fixture
+sessions are explicit test-only descriptors and are rejected by unattended
+project-recap production paths.
+
+## Whole-set visual review
+
+The visual critic receives one
+`explainer-kit.visual-review-request/v1` plus a confined evidence reader. The
+request contains every rendered artifact, exact rendered-content hashes,
+viewport-matched screenshot and metrics hashes, observed cohesion claims, and
+the exact browser runtime and capture identity shared by every evidence record.
+Use the evidence reader to inspect the byte snapshot named by the request.
+
+Return `explainer-kit.visual-review-result/v1` with:
+
+- a safe `reviewId`;
+- the request's exact `requestId` and `requestHash`;
+- an ISO `reviewedAt`;
+- `disposition` equal to `pass`, `correct`, or `fail`;
+- the complete reviewed `artifactIds`; and
+- structured `findings`.
+
+The callback must not mutate rendered files, screenshots, or metrics. The core
+revalidates all bound bytes after the callback returns.
+
+## Correction and terminal behavior
+
+`correct` permits one correction callback and exactly one final review. There
+is never a second correction or third review. Missing evidence, invalid
+contracts, thrown callbacks, byte mutation, unresolved correction, or a `fail`
+disposition produces `built-needs-review`. Such a run retains available review
+evidence but invokes neither durability nor publication.

package/assets/skills/oat-explainer-kit/scripts/bind-project-sources.mjs

@@ -1,5 +1,10 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { access, readFile, realpath } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCallback);
 
 const RECIPE_ARTIFACTS = Object.freeze({
   'project-explainer': ['plan', 'design', 'spec'],
@@ -8,8 +13,10 @@ const RECIPE_ARTIFACTS = Object.freeze({
 
 export async function bindProjectSources({
   projectRoot,
+  repoRoot,
   recipe,
   suppliedFactBasePath,
+  reviewedRepository,
 }) {
   if (!projectRoot) {
     throw new TypeError('projectRoot is required to bind OAT artifacts.');
@@ -20,6 +27,9 @@ export async function bindProjectSources({
   }
 
   const canonicalProjectRoot = await realpath(projectRoot);
+  const repository =
+    reviewedRepository ??
+    (repoRoot ? await resolveReviewedRepository(repoRoot) : null);
   if (suppliedFactBasePath) {
     const path = await realpath(suppliedFactBasePath);
     return {
@@ -30,7 +40,8 @@ export async function bindProjectSources({
       },
       reviewedSource: {
         kind: 'approved-fact-base',
-        locator: path,
+        locator: repository?.repositoryUrl ?? path,
+        ...(repository && repository),
       },
     };
   }
@@ -59,6 +70,10 @@ export async function bindProjectSources({
       `No approved OAT lifecycle artifacts were found for ${recipe}.`,
     );
   }
+  const reviewedSources =
+    repository && repoRoot
+      ? await bindReviewedSources(sources, repoRoot, repository)
+      : undefined;
 
   return {
     factBase: {
@@ -68,25 +83,172 @@ export async function bindProjectSources({
     },
     reviewedSource: {
       kind: 'approved-oat-artifacts',
-      locator: canonicalProjectRoot,
+      locator: repository?.repositoryUrl ?? canonicalProjectRoot,
+      ...(repository && repository),
     },
-    sourceLoader: loadOatArtifact,
+    ...(reviewedSources && {
+      sourceProvenance: reviewedSources.provenance,
+    }),
+    sourceLoader: reviewedSources
+      ? (source) => loadReviewedOatArtifact(source, reviewedSources.documents)
+      : loadOatArtifact,
+  };
+}
+
+export async function resolveReviewedRepository(
+  repoRoot,
+  { command = execFile } = {},
+) {
+  const cwd = resolve(repoRoot);
+  const [{ stdout: revisionOutput }, { stdout: remoteOutput }] =
+    await Promise.all([
+      command('git', ['rev-parse', 'HEAD'], { cwd }),
+      command('git', ['config', '--get', 'remote.origin.url'], { cwd }),
+    ]);
+  const revision = String(revisionOutput).trim();
+  if (!/^[a-f0-9]{40}$/.test(revision)) {
+    throw new Error(
+      'Reviewed OAT sources require a full commit SHA, not a moving revision.',
+    );
+  }
+  const repository = githubRepositoryIdentity(String(remoteOutput).trim());
+  return {
+    repository,
+    repositoryUrl: `https://github.com/${repository}`,
+    revision,
   };
 }
 
 async function loadOatArtifact(source) {
-  const text = (await readFile(source.locator, 'utf8')).trim();
+  return oatArtifactDocument(
+    source,
+    (await readFile(source.locator, 'utf8')).trim(),
+  );
+}
+
+function loadReviewedOatArtifact(source, documents) {
+  const document = documents.get(source.id);
+  if (!document) {
+    throw new Error(
+      `No reviewed Git blob was bound for OAT source ${source.id}.`,
+    );
+  }
+  return structuredClone(document);
+}
+
+function oatArtifactDocument(source, text, sourceHash) {
   return {
     claims: [
       {
         id: source.id,
         text,
         locator: source.locator,
+        lineRange: lineRangeFor(text),
       },
     ],
+    ...(sourceHash && { sourceHash }),
   };
 }
 
+async function bindReviewedSources(sources, repoRoot, repository) {
+  const canonicalRepoRoot = await realpath(repoRoot);
+  const entries = await Promise.all(
+    sources.map(async (source) => {
+      const repositoryPath = relative(canonicalRepoRoot, source.locator)
+        .split(sep)
+        .join('/');
+      if (
+        !repositoryPath ||
+        repositoryPath.startsWith('../') ||
+        repositoryPath === '..'
+      ) {
+        throw new Error(
+          `OAT source ${source.id} is outside the reviewed repository.`,
+        );
+      }
+      try {
+        await execFile(
+          'git',
+          ['ls-files', '--error-unmatch', '--', repositoryPath],
+          { cwd: canonicalRepoRoot },
+        );
+      } catch {
+        throw new Error(
+          `OAT source ${source.id} is not tracked in the reviewed repository.`,
+        );
+      }
+      let reviewedBytes;
+      try {
+        ({ stdout: reviewedBytes } = await execFile(
+          'git',
+          ['show', `${repository.revision}:${repositoryPath}`],
+          {
+            cwd: canonicalRepoRoot,
+            encoding: null,
+            maxBuffer: 16 * 1024 * 1024,
+          },
+        ));
+      } catch {
+        throw new Error(
+          `OAT source ${source.id} is absent from reviewed revision ${repository.revision}.`,
+        );
+      }
+      const workingBytes = await readFile(source.locator);
+      const canonicalReviewedBytes = Buffer.from(reviewedBytes);
+      if (!workingBytes.equals(canonicalReviewedBytes)) {
+        throw new Error(
+          `OAT source ${source.id} working tree bytes mismatch reviewed Git blob at revision ${repository.revision}.`,
+        );
+      }
+      const text = canonicalReviewedBytes.toString('utf8').trim();
+      return {
+        id: source.id,
+        provenance: {
+          repository: repository.repository,
+          revision: repository.revision,
+          path: repositoryPath,
+          lineRange: lineRangeFor(text),
+        },
+        document: oatArtifactDocument(
+          source,
+          text,
+          `sha256:${createHash('sha256')
+            .update(canonicalReviewedBytes)
+            .digest('hex')}`,
+        ),
+      };
+    }),
+  );
+  return {
+    provenance: Object.fromEntries(
+      entries.map((entry) => [entry.id, entry.provenance]),
+    ),
+    documents: new Map(entries.map((entry) => [entry.id, entry.document])),
+  };
+}
+
+function lineRangeFor(text) {
+  return {
+    start: 1,
+    end: Math.max(1, text.split('\n').length),
+  };
+}
+
+function githubRepositoryIdentity(remote) {
+  const patterns = [
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/,
+    /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/,
+    /^ssh:\/\/git@github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/,
+  ];
+  for (const pattern of patterns) {
+    const match = remote.match(pattern);
+    if (match) return `${match[1]}/${match[2]}`;
+  }
+  throw new Error(
+    'Reviewed OAT sources require a canonical GitHub origin repository.',
+  );
+}
+
 function authoritativeTopics(id) {
   return {
     plan: ['phases', 'validation-approach'],

package/assets/skills/oat-explainer-kit/scripts/finalize-tracked-run.mjs

@@ -1,9 +1,12 @@
+import { createHash } from 'node:crypto';
 import { readFile, realpath } from 'node:fs/promises';
-import { relative, resolve, sep } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const MODES = new Set(['dedicated', 'completion-bookkeeping']);
 const ARTIFACT_COMMIT_TOKEN = '$ARTIFACT_COMMIT';
 const SHA_PATTERN = /^[a-f0-9]{40}$/;
+const PACKAGE_COVERAGE_VERSION = 'explainer-kit.package-coverage/v2';
 
 export async function planTrackedRunFinalization(request, context = {}) {
   assertRequest(request);
@@ -21,10 +24,16 @@ export async function planTrackedRunFinalization(request, context = {}) {
       'Finalization requires an explainer-kit.manifest/v1 record.',
     );
   }
+  if (manifest.outcome === 'built-needs-review') {
+    throw new Error(
+      'built-needs-review requires a passing visual review before finalization.',
+    );
+  }
+  const packageCoverage = await loadPackageCoverage(context.coreRoot);
 
-  const immutablePaths = immutablePackagePaths(manifest).map((path) =>
-    toRepoPath(repoRoot, resolveRunPath(runRoot, path)),
-  );
+  const immutablePaths = (
+    await immutablePackagePaths(manifest, runRoot, packageCoverage)
+  ).map((path) => toRepoPath(repoRoot, resolveRunPath(runRoot, path)));
   const mutablePaths = [
     toRepoPath(repoRoot, manifestPath),
     toRepoPath(repoRoot, resolveRunPath(runRoot, manifest.buildRecord?.path)),
@@ -245,7 +254,7 @@ function commitCommands(paths, subject) {
   ];
 }
 
-function immutablePackagePaths(manifest) {
+async function immutablePackagePaths(manifest, runRoot, packageCoverage) {
   if (
     !manifest.immutableHashes ||
     typeof manifest.immutableHashes !== 'object' ||
@@ -257,9 +266,87 @@ function immutablePackagePaths(manifest) {
   if (paths.length === 0) {
     throw new Error('Manifest does not identify a complete immutable package.');
   }
+  const verifiedBytes = new Map();
+  for (const path of paths) {
+    const expected = manifest.immutableHashes[path];
+    if (!/^sha256:[a-f0-9]{64}$/.test(expected)) {
+      throw new Error(`Manifest has an invalid immutable hash for ${path}.`);
+    }
+    const bytes = await readFile(resolveRunPath(runRoot, path));
+    const actual = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+    if (actual !== expected) {
+      throw new Error(`Immutable package hash mismatch for ${path}.`);
+    }
+    verifiedBytes.set(path, bytes);
+  }
+  const runMode =
+    manifest.recipe?.id === 'project-recap'
+      ? verifiedRunMode(verifiedBytes.get('run-request.json'))
+      : undefined;
+  const required = packageCoverage.requiredImmutablePackagePaths(manifest, {
+    runMode,
+  });
+  const missing = required.filter(
+    (path) => !(path in manifest.immutableHashes),
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `Manifest immutable hashes do not cover the canonical package: ${missing.join(', ')}.`,
+    );
+  }
+  await packageCoverage.validateImmutablePackageEvidence(manifest, {
+    runMode,
+    read: (path) => verifiedBytes.get(path),
+  });
   return paths;
 }
 
+function verifiedRunMode(bytes) {
+  if (!Buffer.isBuffer(bytes)) {
+    throw new Error(
+      'Manifest must include hash-verified run-request.json before package coverage is evaluated.',
+    );
+  }
+  let request;
+  try {
+    request = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new Error(
+      'Hash-verified run-request.json must contain valid JSON before package coverage is evaluated.',
+    );
+  }
+  if (!['interactive', 'unattended'].includes(request?.mode)) {
+    throw new Error(
+      'Hash-verified run-request.json must declare interactive or unattended mode.',
+    );
+  }
+  return request.mode;
+}
+
+async function loadPackageCoverage(coreRoot) {
+  const root = await realpathRequired(coreRoot, 'coreRoot');
+  const modulePath = join(root, 'scripts', 'lib', 'package-coverage.mjs');
+  let loaded;
+  try {
+    loaded = await import(pathToFileURL(modulePath).href);
+  } catch (loadError) {
+    throw new Error(
+      `Compatible explainer package coverage could not be loaded from coreRoot: ${loadError.message}`,
+      { cause: loadError },
+    );
+  }
+  if (
+    loaded.PACKAGE_COVERAGE_VERSION !== PACKAGE_COVERAGE_VERSION ||
+    typeof loaded.requiredImmutablePackagePaths !== 'function' ||
+    typeof loaded.validateImmutablePackageEvidence !== 'function'
+  ) {
+    throw new Error(
+      `coreRoot must provide ${PACKAGE_COVERAGE_VERSION} package coverage.`,
+    );
+  }
+  return loaded;
+}
+
 function resolveRunPath(runRoot, path) {
   const target = resolve(runRoot, path);
   assertWithin(runRoot, target, `Manifest path ${path}`);