@open-agent-toolkit/cli 0.2.26 → 0.2.27

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

@@ -12,7 +12,7 @@ import {
 } from './resolve-config.mjs';
 import { resolveExplainerOutputRoot } from './resolve-paths.mjs';
 
-const MINIMUM_CORE_VERSION = '2.0.0';
+export const MINIMUM_CORE_VERSION = '2.0.3';
 const ADAPTER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 export async function runOatExplainer({
@@ -32,10 +32,18 @@ export async function runOatExplainer({
   defaultMode,
   renderStrategy,
   retainRawArtDirection = false,
+  planSet,
+  planSetModulePath,
   author,
   authorModulePath,
   critic,
   criticModulePath,
+  browserSession,
+  browserSessionModulePath,
+  browserProbe,
+  browserProbeModulePath,
+  visualCritic,
+  visualCriticModulePath,
   coreOptions = {},
 }) {
   const compatibility = await checkCoreCompatibility({
@@ -54,6 +62,14 @@ export async function runOatExplainer({
     error.compatibility = compatibility;
     throw error;
   }
+  if (!supportsAdaptiveSetPlanning(compatibility.installedVersion)) {
+    const error = new Error(
+      `Installed explainer-kit ${compatibility.installedVersion} does not provide adaptive set planning. Run \`oat tools update --pack utility --scope user\`.`,
+    );
+    error.code = 'E_CORE_INCOMPATIBLE';
+    error.compatibility = compatibility;
+    throw error;
+  }
 
   const resolvedConfig = await resolveExplainerConfig({
     repoRoot,
@@ -73,6 +89,7 @@ export async function runOatExplainer({
   const projectRoot = resolve(repoRoot, activeProject);
   const bound = await bindProjectSources({
     projectRoot,
+    repoRoot,
     recipe,
     suppliedFactBasePath,
   });
@@ -115,16 +132,53 @@ export async function runOatExplainer({
     authorModulePath,
     coreOptions,
   });
+  const lifecycleSetPlanner = await resolveLifecycleSetPlanner({
+    planSet,
+    planSetModulePath,
+    coreOptions,
+    required: recipe === 'project-recap' && mode === 'unattended',
+  });
   const lifecycleCritic = await resolveLifecycleCritic({
     critic,
     criticModulePath,
     coreOptions,
   });
+  const reviewProvidersRequired =
+    recipe === 'project-recap' && mode === 'unattended';
+  const lifecycleBrowserSession = await resolveLifecycleBrowserSession({
+    core,
+    browserSession,
+    browserSessionModulePath,
+    browserProbe,
+    browserProbeModulePath,
+    coreOptions,
+    required: reviewProvidersRequired,
+  });
+  const lifecycleVisualCritic = await resolveLifecycleVisualCritic({
+    visualCritic,
+    visualCriticModulePath,
+    coreOptions,
+    required: reviewProvidersRequired,
+  });
+  assertDistinctProviderRoles({
+    author: lifecycleAuthor,
+    factCritic: lifecycleCritic,
+    browserProbe: lifecycleBrowserSession?.probe,
+    visualCritic: lifecycleVisualCritic,
+  });
   const result = await core.runExplainer(request, {
     ...coreOptions,
+    ...(lifecycleSetPlanner && { planSet: lifecycleSetPlanner }),
     ...(lifecycleAuthor && { author: lifecycleAuthor }),
     ...(lifecycleCritic && { critic: lifecycleCritic }),
+    ...(lifecycleBrowserSession && {
+      browserSession: lifecycleBrowserSession,
+    }),
+    ...(lifecycleVisualCritic && { visualCritic: lifecycleVisualCritic }),
     ...(bound.sourceLoader && { sourceLoader: bound.sourceLoader }),
+    ...(bound.sourceProvenance && {
+      sourceProvenance: bound.sourceProvenance,
+    }),
     reviewedSource: bound.reviewedSource,
   });
   const criticContractError = result?.errors?.find(
@@ -145,6 +199,74 @@ export async function runOatExplainer({
   };
 }
 
+export function supportsAdaptiveSetPlanning(version) {
+  if (typeof version !== 'string') return false;
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-|$)/);
+  if (!match) return false;
+  const [major, minor, patch] = match.slice(1).map(Number);
+  return (
+    major === 2 &&
+    (minor > 0 ||
+      (minor === 0 && patch >= Number(MINIMUM_CORE_VERSION.split('.')[2])))
+  );
+}
+
+async function resolveLifecycleSetPlanner({
+  planSet,
+  planSetModulePath,
+  coreOptions,
+  required,
+}) {
+  if (coreOptions?.planSet !== undefined) {
+    throw new TypeError(
+      'coreOptions.planSet is not supported at the OAT adapter boundary; supply planSet directly.',
+    );
+  }
+  if (planSet !== undefined && typeof planSet !== 'function') {
+    throw new TypeError('planSet must be a function when supplied.');
+  }
+  if (planSet !== undefined && planSetModulePath !== undefined) {
+    throw new Error(
+      'Supply only one provider-neutral set planner callback or set planner module entry point.',
+    );
+  }
+  if (planSet === undefined && planSetModulePath === undefined) {
+    if (!required) return null;
+    const error = new Error(
+      'Unattended OAT project recaps require exactly one provider-neutral set planner callback or set planner module entry point.',
+    );
+    error.code = 'E_SET_PLANNER_REQUIRED';
+    throw error;
+  }
+  if (planSetModulePath === undefined) {
+    return planSet;
+  }
+  if (
+    typeof planSetModulePath !== 'string' ||
+    planSetModulePath.trim().length === 0
+  ) {
+    throw new TypeError('planSetModulePath must be a non-empty path.');
+  }
+
+  let plannerModule;
+  try {
+    plannerModule = await import(
+      pathToFileURL(resolve(planSetModulePath.trim())).href
+    );
+  } catch (cause) {
+    throw new Error(
+      `Unable to load provider-neutral set planner module at ${planSetModulePath}.`,
+      { cause },
+    );
+  }
+  if (typeof plannerModule.planSet !== 'function') {
+    throw new TypeError(
+      'Provider-neutral set planner module must export a planSet function.',
+    );
+  }
+  return plannerModule.planSet;
+}
+
 async function resolveLifecycleAuthor({
   author,
   authorModulePath,
@@ -255,7 +377,7 @@ async function resolveLifecycleCritic({
   if (!callback) {
     return null;
   }
-  return async (request) => {
+  const wrapped = async (request) => {
     const result = await callback(request);
     if (
       !result ||
@@ -273,6 +395,206 @@ async function resolveLifecycleCritic({
     }
     return result;
   };
+  return markProviderIdentity(wrapped, callback);
+}
+
+async function resolveLifecycleBrowserSession({
+  core,
+  browserSession,
+  browserSessionModulePath,
+  browserProbe,
+  browserProbeModulePath,
+  coreOptions,
+  required,
+}) {
+  if (coreOptions?.browserProbe !== undefined) {
+    throw new TypeError(
+      'coreOptions.browserProbe is not supported at the OAT adapter boundary; supply browserSession directly.',
+    );
+  }
+  if (browserProbe !== undefined || browserProbeModulePath !== undefined) {
+    throw new TypeError(
+      'Bare browserProbe callbacks are not supported at the OAT adapter boundary; supply a branded browserSession created by createBrowserProbeSession().',
+    );
+  }
+  if (coreOptions?.browserSession !== undefined) {
+    throw new TypeError(
+      'coreOptions.browserSession is not supported at the OAT adapter boundary; supply browserSession directly.',
+    );
+  }
+  if (browserSession !== undefined && browserSessionModulePath !== undefined) {
+    throw new Error(
+      'Supply only one browser session descriptor or browser session module entry point.',
+    );
+  }
+  let resolvedSession = browserSession;
+  if (browserSessionModulePath !== undefined) {
+    if (
+      typeof browserSessionModulePath !== 'string' ||
+      browserSessionModulePath.trim().length === 0
+    ) {
+      throw new TypeError('browserSessionModulePath must be a non-empty path.');
+    }
+    let sessionModule;
+    try {
+      sessionModule = await import(
+        pathToFileURL(resolve(browserSessionModulePath.trim())).href
+      );
+    } catch (cause) {
+      throw new Error(
+        `Unable to load browser session module at ${browserSessionModulePath}.`,
+        { cause },
+      );
+    }
+    resolvedSession = sessionModule.browserSession;
+  }
+  if (!resolvedSession) {
+    if (!required) return null;
+    const error = new Error(
+      'Unattended OAT project recaps require exactly one branded launched-Chromium browser session descriptor or browser session module entry point.',
+    );
+    error.code = 'E_BROWSER_PROBE_REQUIRED';
+    throw error;
+  }
+  if (typeof core.assertBrowserProbeSession !== 'function') {
+    const error = new Error(
+      'Compatible explainer-kit does not export browser session validation.',
+    );
+    error.code = 'E_CORE_INCOMPATIBLE';
+    throw error;
+  }
+  try {
+    return core.assertBrowserProbeSession(resolvedSession, {
+      allowFixture: !required,
+    });
+  } catch (cause) {
+    const error = new Error(
+      `Browser session validation failed: ${cause?.message ?? String(cause)}`,
+      { cause },
+    );
+    error.code = 'E_BROWSER_PROBE_REQUIRED';
+    throw error;
+  }
+}
+
+async function resolveLifecycleVisualCritic({
+  visualCritic,
+  visualCriticModulePath,
+  coreOptions,
+  required,
+}) {
+  if (coreOptions?.visualCritic !== undefined) {
+    throw new TypeError(
+      'coreOptions.visualCritic is not supported at the OAT adapter boundary; supply visualCritic directly.',
+    );
+  }
+  const callback = await resolveProviderCallback({
+    callback: visualCritic,
+    modulePath: visualCriticModulePath,
+    exportName: 'visualCritic',
+    label: 'visual critic',
+  });
+  if (!callback) {
+    if (!required) return null;
+    const error = new Error(
+      'Unattended OAT project recaps require exactly one provider-neutral visual critic callback or visual critic module entry point.',
+    );
+    error.code = 'E_VISUAL_CRITIC_REQUIRED';
+    throw error;
+  }
+  const wrapped = async (request, evidenceInput) => {
+    const result = await callback(request, evidenceInput);
+    if (
+      !result ||
+      typeof result !== 'object' ||
+      result.schemaVersion !== 'explainer-kit.visual-review-result/v1' ||
+      typeof result.reviewId !== 'string' ||
+      !/^[a-z0-9][a-z0-9._-]*$/.test(result.reviewId) ||
+      result.requestId !== request?.requestId ||
+      result.requestHash !== request?.requestHash ||
+      typeof result.reviewedAt !== 'string' ||
+      Number.isNaN(Date.parse(result.reviewedAt)) ||
+      !['pass', 'correct', 'fail'].includes(result.disposition) ||
+      !Array.isArray(result.artifactIds) ||
+      result.artifactIds.length !== request?.renderedArtifacts?.length ||
+      result.artifactIds.some(
+        (artifactId, index) =>
+          artifactId !== request.renderedArtifacts[index]?.artifactId,
+      ) ||
+      !Array.isArray(result.findings) ||
+      result.findings.some((finding) => !finding || typeof finding !== 'object')
+    ) {
+      throw new Error(
+        'Provider-neutral visual critic result does not match the visual review result contract.',
+      );
+    }
+    return result;
+  };
+  return markProviderIdentity(wrapped, callback);
+}
+
+async function resolveProviderCallback({
+  callback,
+  modulePath,
+  exportName,
+  label,
+}) {
+  if (callback !== undefined && typeof callback !== 'function') {
+    throw new TypeError(`${exportName} must be a function when supplied.`);
+  }
+  if (callback !== undefined && modulePath !== undefined) {
+    throw new Error(
+      `Supply only one provider-neutral ${label} callback or ${label} module entry point.`,
+    );
+  }
+  if (modulePath === undefined) return callback ?? null;
+  if (typeof modulePath !== 'string' || modulePath.trim().length === 0) {
+    throw new TypeError(`${exportName}ModulePath must be a non-empty path.`);
+  }
+  let providerModule;
+  try {
+    providerModule = await import(
+      pathToFileURL(resolve(modulePath.trim())).href
+    );
+  } catch (cause) {
+    throw new Error(
+      `Unable to load provider-neutral ${label} module at ${modulePath}.`,
+      { cause },
+    );
+  }
+  if (typeof providerModule[exportName] !== 'function') {
+    throw new TypeError(
+      `Provider-neutral ${label} module must export a ${exportName} function.`,
+    );
+  }
+  return providerModule[exportName];
+}
+
+const PROVIDER_IDENTITY = Symbol('oat-explainer-provider-identity');
+
+function markProviderIdentity(wrapper, callback) {
+  Object.defineProperty(wrapper, PROVIDER_IDENTITY, { value: callback });
+  return wrapper;
+}
+
+function providerIdentity(callback) {
+  return callback?.[PROVIDER_IDENTITY] ?? callback;
+}
+
+function assertDistinctProviderRoles(callbacks) {
+  const entries = Object.entries(callbacks).filter(([, callback]) => callback);
+  for (let left = 0; left < entries.length; left += 1) {
+    for (let right = left + 1; right < entries.length; right += 1) {
+      if (
+        providerIdentity(entries[left][1]) ===
+        providerIdentity(entries[right][1])
+      ) {
+        throw new Error(
+          `Provider roles ${entries[left][0]} and ${entries[right][0]} must use distinct callback identities.`,
+        );
+      }
+    }
+  }
 }
 
 async function readManifest(result, request) {

package/dist/commands/project/archive/archive-utils.d.ts

@@ -151,6 +151,7 @@ export declare function resolveLocalArchiveProjectPath(projectsRoot: string, pro
 export declare function resolvePrimaryRepoRoot(repoRoot: string, dependencies?: ResolvePrimaryRepoRootDependencies): Promise<string>;
 export declare function resolveArchiveProjectTarget(options: ResolveArchiveProjectTargetOptions, dependencies?: ResolveArchiveProjectTargetDependencies): Promise<ArchiveProjectTarget>;
 export declare function assertDurableArchiveProjectTarget(target: ArchiveProjectTarget): void;
+export declare function verifySelectedProjectRecapForArchive(projectPath: string, projectRecapRun: string): Promise<void>;
 export declare function archiveProjectOnCompletion(options: ArchiveProjectOnCompletionOptions, dependencies?: ArchiveProjectOnCompletionDependencies): Promise<ArchiveProjectOnCompletionResult>;
 export declare function ensureS3ArchiveAccess(options: EnsureS3ArchiveAccessOptions, dependencies?: EnsureS3ArchiveAccessDependencies): Promise<EnsureS3ArchiveAccessResult>;
 export {};

package/dist/commands/project/archive/archive-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-utils.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/archive-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"archive-utils.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/archive-utils.ts"],"names":[],"mappings":"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"}

package/dist/commands/project/archive/archive-utils.js

@@ -5,6 +5,8 @@ import { basename, dirname, isAbsolute, join, posix as path, relative, resolve,
 import { promisify } from 'node:util';
 import { CliError } from '../../../errors/cli-error.js';
 import { copyDirectory, copySingleFile, dirExists, ensureDir, fileExists, } from '../../../fs/io.js';
+import { loadExplainerPackageCoverage } from './explainer-package-coverage.js';
+import { loadExplainerSourceBacklinks, } from './explainer-source-backlinks.js';
 const execFileAsync = promisify(execFileCallback);
 export const ARCHIVE_SNAPSHOT_METADATA_FILENAME = '.oat-archive-source.json';
 /**
@@ -281,7 +283,7 @@ async function exportProjectSummary(archivePath, snapshotName, summaryExportPath
     await copySummary(summarySource, summaryTarget);
     return summaryTarget;
 }
-function parseProjectRecapManifest(contents) {
+async function parseProjectRecapManifest(contents) {
     let value;
     try {
         value = JSON.parse(contents);
@@ -289,43 +291,13 @@ function parseProjectRecapManifest(contents) {
     catch {
         throw new CliError('Selected project recap has an invalid manifest.json.');
     }
-    if (!isProjectRecapManifestV1(value)) {
+    const sourceBacklinks = await loadExplainerSourceBacklinks();
+    if (!isProjectRecapManifestV1(value, sourceBacklinks)) {
         throw new CliError('Selected project recap manifest does not match the explainer-kit manifest contract.');
     }
-    const requiredProvenancePaths = [
-        'run-request.json',
-        'source/content-approval.json',
-    ];
-    const recordedImmutablePaths = Object.keys(value.immutableHashes);
-    const missingLegacyPaths = requiredProvenancePaths.filter((relativePath) => !(relativePath in value.immutableHashes));
-    if (missingLegacyPaths.length > 0) {
-        throw new CliError(`Selected project recap uses a legacy manifest missing immutable coverage for ${missingLegacyPaths.join(', ')}; regenerate the recap package before archival.`);
-    }
-    const expectedImmutablePaths = new Set([
-        ...requiredProvenancePaths,
-        value.source.factBasePath,
-        'source/fact-base.md',
-        ...(value.source.authorResultPaths ?? []),
-        value.theme.path,
-        ...value.artifacts.flatMap((artifact) => [
-            artifact.contentPath,
-            ...(artifact.status === 'built' &&
-                typeof artifact.renderedPath === 'string'
-                ? [artifact.renderedPath]
-                : []),
-        ]),
-    ]);
-    if (expectedImmutablePaths.size === 0 ||
-        expectedImmutablePaths.size !== recordedImmutablePaths.length ||
-        [...expectedImmutablePaths].some((relativePath) => !(relativePath in value.immutableHashes)) ||
-        value.artifacts.some((artifact) => artifact.status === 'built' &&
-            typeof artifact.renderedPath === 'string' &&
-            artifact.hash !== value.immutableHashes[artifact.renderedPath])) {
-        throw new CliError('Selected project recap manifest immutable hashes do not cover the complete v1 package.');
-    }
     return value;
 }
-function isProjectRecapManifestV1(value) {
+function isProjectRecapManifestV1(value, sourceBacklinks) {
     if (!isRecord(value) ||
         !hasExactKeys(value, [
             'schemaVersion',
@@ -351,12 +323,14 @@ function isProjectRecapManifestV1(value) {
         !isNonEmptyString(value.recipe.id) ||
         !isNonEmptyString(value.recipe.version) ||
         !isRecord(value.source) ||
-        !hasExactKeys(value.source, ['factBasePath', 'factBaseHash', 'inputHashes'], ['sourceRevision', 'authorResultPaths']) ||
+        !hasExactKeys(value.source, ['factBasePath', 'factBaseHash', 'inputHashes'], ['sourceRevision', 'authorResultPaths', 'backlinks']) ||
         !isSafeRelativePath(value.source.factBasePath) ||
         !isSha256(value.source.factBaseHash) ||
         !isHashMap(value.source.inputHashes) ||
         (value.source.authorResultPaths !== undefined &&
             !isUniqueSafePathArray(value.source.authorResultPaths)) ||
+        (value.source.backlinks !== undefined &&
+            !isCanonicalSourceBacklinks(value.source.backlinks, sourceBacklinks)) ||
         (value.source.sourceRevision !== undefined &&
             !isNonEmptyString(value.source.sourceRevision)) ||
         !isRecord(value.theme) ||
@@ -369,7 +343,13 @@ function isProjectRecapManifestV1(value) {
         new Set(value.artifacts.map((artifact) => JSON.stringify(artifact)))
             .size !== value.artifacts.length ||
         !isHashMap(value.immutableHashes) ||
-        !['built-durable', 'built-not-durable', 'failed', 'incomplete'].includes(String(value.outcome)) ||
+        ![
+            'built-durable',
+            'built-not-durable',
+            'built-needs-review',
+            'failed',
+            'incomplete',
+        ].includes(String(value.outcome)) ||
         !isPathHashRecord(value.buildRecord, 'build-record.json') ||
         (value.publishReceipt !== undefined &&
             !isPathHashRecord(value.publishReceipt, 'publish-receipt.json')) ||
@@ -451,6 +431,32 @@ function isHashMap(value) {
     return (isRecord(value) &&
         Object.entries(value).every(([relativePath, hash]) => isSafeRelativePath(relativePath) && isSha256(hash)));
 }
+function isCanonicalSourceBacklinks(value, sourceBacklinks) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    const identities = new Set();
+    for (const backlink of value) {
+        if (!isRecord(backlink) ||
+            !hasExactKeys(backlink, ['sourceId', 'url']) ||
+            !isNonEmptyString(backlink.sourceId) ||
+            typeof backlink.url !== 'string') {
+            return false;
+        }
+        try {
+            sourceBacklinks.parseCanonicalGithubBlobUrl(backlink.url);
+        }
+        catch {
+            return false;
+        }
+        const identity = `${backlink.sourceId}\0${backlink.url}`;
+        if (identities.has(identity)) {
+            return false;
+        }
+        identities.add(identity);
+    }
+    return true;
+}
 function isUniqueSafePathArray(value) {
     return (Array.isArray(value) &&
         value.length > 0 &&
@@ -544,17 +550,78 @@ async function verifyProjectRecapImmutableHashes(stagedRoot, manifest) {
     }
     return entries.length;
 }
+async function readVerifiedRunMode(runRoot) {
+    let request;
+    try {
+        request = JSON.parse(await readFile(join(runRoot, 'run-request.json'), 'utf8'));
+    }
+    catch {
+        throw new CliError('Hash-verified project recap run-request.json must contain valid JSON.');
+    }
+    if (!isRecord(request) ||
+        (request.mode !== 'interactive' && request.mode !== 'unattended')) {
+        throw new CliError('Hash-verified project recap run-request.json must declare interactive or unattended mode.');
+    }
+    return request.mode;
+}
+async function loadVerifiedProjectRecap(projectPath, projectRecapRun) {
+    const sourceRunRoot = await resolveSelectedProjectRecapRun(projectPath, projectRecapRun);
+    const manifestContents = await readFile(join(sourceRunRoot, 'manifest.json'), 'utf8');
+    const manifest = await parseProjectRecapManifest(manifestContents);
+    if (manifest.recipe.id !== 'project-recap') {
+        throw new CliError('Selected project recap manifest recipe must be exactly `project-recap`.');
+    }
+    if (manifest.outcome === 'built-needs-review') {
+        throw new CliError('Selected project recap is built-needs-review and requires a passing visual review before archival.');
+    }
+    const verifiedArtifactCount = await verifyProjectRecapImmutableHashes(sourceRunRoot, manifest);
+    const runMode = await readVerifiedRunMode(sourceRunRoot);
+    const packageCoverage = await loadExplainerPackageCoverage();
+    const missingCoverage = packageCoverage
+        .requiredImmutablePackagePaths(manifest, { runMode })
+        .filter((relativePath) => !(relativePath in manifest.immutableHashes));
+    const missingLegacyCoverage = missingCoverage.filter((relativePath) => ['run-request.json', 'source/content-approval.json'].includes(relativePath));
+    if (missingLegacyCoverage.length > 0) {
+        throw new CliError(`Selected project recap uses a legacy manifest missing immutable coverage for ${missingLegacyCoverage.join(', ')}; regenerate the recap package before archival.`);
+    }
+    if (missingCoverage.some((relativePath) => relativePath.startsWith('qa/browser/') ||
+        relativePath.startsWith('qa/visual-review/'))) {
+        throw new CliError('Selected project recap manifest has an incomplete visual-review evidence chain.');
+    }
+    if (missingCoverage.length > 0) {
+        throw new CliError(`Selected project recap manifest immutable hashes do not cover the complete v2 package: ${missingCoverage.join(', ')}.`);
+    }
+    try {
+        await packageCoverage.validateImmutablePackageEvidence(manifest, {
+            runMode,
+            read: (relativePath) => readFile(join(sourceRunRoot, relativePath)),
+        });
+    }
+    catch (error) {
+        throw new CliError(`Selected project recap browser evidence contract is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (manifest.artifacts.some((artifact) => artifact.status === 'built' &&
+        typeof artifact.renderedPath === 'string' &&
+        artifact.hash !== manifest.immutableHashes[artifact.renderedPath])) {
+        throw new CliError('Selected project recap artifact hashes do not match the immutable package.');
+    }
+    return {
+        sourceRunRoot,
+        manifestContents,
+        manifest,
+        verifiedArtifactCount,
+    };
+}
+export async function verifySelectedProjectRecapForArchive(projectPath, projectRecapRun) {
+    await loadVerifiedProjectRecap(projectPath, projectRecapRun);
+}
 async function exportSelectedProjectRecap(options, snapshotName, dependencies) {
     const selectedRun = options.projectRecapRun?.trim();
     if (!selectedRun) {
         return null;
     }
-    const sourceRunRoot = await resolveSelectedProjectRecapRun(options.projectPath, selectedRun);
-    const sourceManifestContents = await readFile(join(sourceRunRoot, 'manifest.json'), 'utf8');
-    const sourceManifest = parseProjectRecapManifest(sourceManifestContents);
-    if (sourceManifest.recipe.id !== 'project-recap') {
-        throw new CliError('Selected project recap manifest recipe must be exactly `project-recap`.');
-    }
+    const verified = await loadVerifiedProjectRecap(options.projectPath, selectedRun);
+    const { sourceRunRoot, manifestContents: sourceManifestContents, manifest: sourceManifest, } = verified;
     const exportRoot = join(options.repoRoot, '.oat', 'repo', 'reference', 'project-recaps', snapshotName);
     if (await pathExists(exportRoot)) {
         throw new CliError(`Project recap export destination \`${exportRoot}\` already exists; refusing to overwrite it.`);

package/dist/commands/project/archive/explainer-package-coverage.d.ts

@@ -0,0 +1,14 @@
+declare const PACKAGE_COVERAGE_VERSION = "explainer-kit.package-coverage/v2";
+export interface ExplainerPackageCoverage {
+    PACKAGE_COVERAGE_VERSION: typeof PACKAGE_COVERAGE_VERSION;
+    requiredImmutablePackagePaths: (manifest: unknown, options?: {
+        runMode?: 'interactive' | 'unattended';
+    }) => string[];
+    validateImmutablePackageEvidence: (manifest: unknown, options: {
+        runMode?: 'interactive' | 'unattended';
+        read: (path: string) => Promise<Buffer | string>;
+    }) => Promise<void>;
+}
+export declare function loadExplainerPackageCoverage(): Promise<ExplainerPackageCoverage>;
+export {};
+//# sourceMappingURL=explainer-package-coverage.d.ts.map

package/dist/commands/project/archive/explainer-package-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainer-package-coverage.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/explainer-package-coverage.ts"],"names":[],"mappings":"AAMA,QAAA,MAAM,wBAAwB,sCAAsC,CAAC;AAErE,MAAM,WAAW,wBAAwB;IACvC,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,6BAA6B,EAAE,CAC7B,QAAQ,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAA;KAAE,KACjD,MAAM,EAAE,CAAC;IACd,gCAAgC,EAAE,CAChC,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE;QACP,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;QACvC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;KAClD,KACE,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAID,wBAAgB,4BAA4B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAGhF"}

package/dist/commands/project/archive/explainer-package-coverage.js

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CliError } from '../../../errors/cli-error.js';
+import { resolveAssetsRoot } from '../../../fs/assets.js';
+const PACKAGE_COVERAGE_VERSION = 'explainer-kit.package-coverage/v2';
+let cachedCoverage;
+export function loadExplainerPackageCoverage() {
+    cachedCoverage ??= loadGeneratedCoverage();
+    return cachedCoverage;
+}
+async function loadGeneratedCoverage() {
+    const assetsRoot = await resolveAssetsRoot();
+    const modulePath = join(assetsRoot, 'skills', 'explainer-kit', 'scripts', 'lib', 'package-coverage.mjs');
+    let loaded;
+    try {
+        loaded = (await import(pathToFileURL(modulePath).href));
+    }
+    catch (error) {
+        throw new CliError(`Bundled explainer package coverage could not be loaded: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+    if (loaded.PACKAGE_COVERAGE_VERSION !== PACKAGE_COVERAGE_VERSION ||
+        typeof loaded.requiredImmutablePackagePaths !== 'function' ||
+        typeof loaded.validateImmutablePackageEvidence !== 'function') {
+        throw new CliError(`Bundled assets must provide ${PACKAGE_COVERAGE_VERSION} package coverage.`, 2);
+    }
+    return loaded;
+}