create-agdf 0.14.3 → 0.14.4

package/lib/installers/plugin-installers.js

@@ -4,10 +4,22 @@ import { join, resolve } from "node:path";
 import process from "node:process";
 import { pluginDefinition } from "../cli/runtime-context.js";
 import { digestNormalizedPluginSource } from "../runtime/plugin-provenance.js";
+import { recoverClaudeCacheTemp } from "./claude-cache-recovery.js";
 import { CODEX_REGISTRATION_REVISION, classifyMarketplaceList, inspectLocalMarketplaceProjection, inspectOwnedSharedMarketplaceForCopilotMigration, isCodexLocalInstallVersion, prepareCopilotMarketplace, prepareLocalMarketplace } from "./local-marketplace.js";
 
 export const COPILOT_CLI_NPM_PACKAGE = "@github/copilot@1.0.80";
 
+function historicalEvidenceEntries(transaction) {
+  const historical = transaction.historicalEvidence;
+  if (!historical) return [];
+  return [
+    `historical_release:${historical.releaseVersion}`,
+    `historical_contract:${historical.contractId}`,
+    `historical_contract_digest:${historical.contractDigest}`,
+    `historical_entry_digest:${historical.entryDigest}`,
+  ];
+}
+
 export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
@@ -34,12 +46,15 @@ export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepar
         ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
         ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
         ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
+        ...(transaction.existingClassification === "owned_supported_historical_rebuild" ? ["marketplace_recovery:owned_supported_historical_rebuild", "loaded_session:fresh_session_required"] : []),
+        ...historicalEvidenceEntries(transaction),
         ...(expectedInstallVersion === expectedVersion ? [] : [`canonical_version:${expectedVersion}`, `local_install_version:${expectedInstallVersion}`]),
       ],
       pluginRoot: transaction.pluginRoot ?? null,
       digest: transaction.digest ?? null,
       runtimeDigest: transaction.runtimeDigest ?? null,
       sourceDigest: transaction.sourceDigest ?? null,
+      historicalEvidence: transaction.historicalEvidence ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {
@@ -48,11 +63,19 @@ export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepar
   }
 }
 
-export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
+export function installClaudeGlobalPlugin({
+  exec = execFileSync,
+  prepare = prepareLocalMarketplace,
+  dataRoot,
+  recoverCache = recoverClaudeCacheTemp,
+  cacheRecoveryOptions = {},
+} = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
   const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
   const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  let previousPluginRemoved = false;
+  let pluginInstalled = false;
   try {
     const marketplaceOutput = runPluginPhase(exec, "claude", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
     migrateMarketplace({ surface: "claude", exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
@@ -63,11 +86,41 @@ export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepa
     // same-version local source change never reaches the host; reinstall replaces the content.
     if (alreadyInstalled) {
       nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "uninstall", "agdf@agdf"], "plugin_operation", captureOptions()));
+      previousPluginRemoved = true;
+    }
+    let cacheRecovery = null;
+    try {
+      nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", "agdf@agdf"], "plugin_operation", captureOptions()));
+      pluginInstalled = true;
+    } catch (installError) {
+      cacheRecovery = recoverCache({
+        error: installError,
+        expectedVersion,
+        ...cacheRecoveryOptions,
+      });
+      if (cacheRecovery.status !== "recovered") {
+        installError.evidence = {
+          ...(installError.evidence ?? {}),
+          claude_cache_recovery: cacheRecovery.reason,
+        };
+        throw installError;
+      }
+      try {
+        nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", "agdf@agdf"], "plugin_operation", captureOptions()));
+        pluginInstalled = true;
+      } catch (retryError) {
+        retryError.evidence = {
+          ...(retryError.evidence ?? {}),
+          claude_cache_recovery: "claude_cache_temp_retry_exhausted",
+        };
+        throw retryError;
+      }
     }
-    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", "agdf@agdf"], "plugin_operation", captureOptions()));
     const afterList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", captureOptions());
     const installedVersion = pluginVersionFromList(afterList, "agdf@agdf");
-    if (installedVersion && installedVersion !== expectedVersion) {
+    const historicalRebuild = transaction.existingClassification === "owned_supported_historical_rebuild";
+    if ((historicalRebuild && installedVersion !== expectedVersion)
+        || (installedVersion && installedVersion !== expectedVersion)) {
       throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest claude"));
     }
     transaction.commit();
@@ -85,16 +138,20 @@ export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepa
         ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
         ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
         ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
+        ...(transaction.existingClassification === "owned_supported_historical_rebuild" ? ["marketplace_recovery:owned_supported_historical_rebuild", "loaded_session:fresh_session_required"] : []),
+        ...historicalEvidenceEntries(transaction),
+        ...(cacheRecovery?.status === "recovered" ? ["claude_cache_temp_recovery:bounded_retry"] : []),
         ...(installedVersion ? [] : ["host_did_not_expose_version"]),
       ],
       pluginRoot: transaction.pluginRoot ?? null,
       digest: transaction.digest ?? null,
       runtimeDigest: transaction.runtimeDigest ?? null,
       sourceDigest: transaction.sourceDigest ?? null,
+      historicalEvidence: transaction.historicalEvidence ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {
-    recoverMarketplace({ surface: "claude", exec, migration, transaction, error });
+    recoverMarketplace({ surface: "claude", exec, migration, transaction, error, previousPluginRemoved, pluginInstalled });
     throw error;
   }
 }
@@ -118,7 +175,7 @@ export function installCopilotGlobalPlugin({ exec = execFileSync, packagedCopilo
   try {
     before = activeExec("copilot", ["plugin", "list"], captureOptions());
   } catch (error) {
-    if (error?.code !== "ENOENT") {
+    if (!copilotCliUnavailable(error)) {
       transaction?.rollback();
       throw lifecycleAdapterError("verification", commandErrorText(error), { executable: "copilot", args: ["plugin", "list"] });
     }
@@ -126,7 +183,10 @@ export function installCopilotGlobalPlugin({ exec = execFileSync, packagedCopilo
     activeExec = (_executable, args, options) => packagedCopilotExec(invocation.executable, [...invocation.args, ...args], options);
     try {
       before = activeExec("copilot", ["plugin", "list"], captureOptions());
-      bootstrapEvidence.push("copilot_cli_not_found", `copilot_cli_npm_package:${COPILOT_CLI_NPM_PACKAGE}`);
+      bootstrapEvidence.push(
+        error?.code === "ENOENT" ? "copilot_cli_not_found" : "copilot_cli_launcher_unavailable",
+        `copilot_cli_npm_package:${COPILOT_CLI_NPM_PACKAGE}`,
+      );
     } catch (bootstrapError) {
       transaction?.commit();
       return {
@@ -302,7 +362,15 @@ function migrateMarketplace({ surface, exec, output, root, nativeOutput, migrati
   }
 }
 
-function recoverMarketplace({ surface, exec, migration, transaction, error }) {
+function recoverMarketplace({
+  surface,
+  exec,
+  migration,
+  transaction,
+  error,
+  previousPluginRemoved = false,
+  pluginInstalled = false,
+}) {
   const executable = surface === "claude" ? "claude" : "codex";
   const recovery = [];
   const attempt = (args) => {
@@ -316,13 +384,19 @@ function recoverMarketplace({ surface, exec, migration, transaction, error }) {
     }
   };
   if (migration?.refreshOwnedLocal) {
+    if (surface === "claude" && pluginInstalled) {
+      attempt(["plugin", "uninstall", "agdf@agdf"]);
+    }
     const refreshedRegistrationRemoved = migration.addedLocal
       ? attempt(["plugin", "marketplace", "remove", "agdf", "--json"])
       : true;
-    rollbackMarketplaceFilesystem(transaction, recovery);
+    const filesystemRestored = rollbackMarketplaceFilesystem(transaction, recovery);
     if (migration.removedOwnedLocal && refreshedRegistrationRemoved) {
       attempt(["plugin", "marketplace", "add", migration.source || transaction.root, "--json"]);
     }
+    if (surface === "claude" && previousPluginRemoved && filesystemRestored) {
+      attempt(["plugin", "install", "agdf@agdf"]);
+    }
     error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
     return;
   }
@@ -336,7 +410,13 @@ function recoverMarketplace({ surface, exec, migration, transaction, error }) {
       ? ["plugin", "marketplace", "add", migration.source, "--scope", "user"]
       : ["plugin", "marketplace", "add", migration.source, "--json"]);
   }
-  rollbackMarketplaceFilesystem(transaction, recovery);
+  if (surface === "claude" && pluginInstalled) {
+    attempt(["plugin", "uninstall", "agdf@agdf"]);
+  }
+  const filesystemRestored = rollbackMarketplaceFilesystem(transaction, recovery);
+  if (surface === "claude" && previousPluginRemoved && filesystemRestored) {
+    attempt(["plugin", "install", "agdf@agdf"]);
+  }
   error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
 }
 
@@ -344,8 +424,10 @@ function rollbackMarketplaceFilesystem(transaction, recovery) {
   try {
     transaction.rollback();
     recovery.push({ filesystem: transaction.root, status: "restored" });
+    return true;
   } catch (rollbackError) {
     recovery.push({ filesystem: transaction.root, status: "failed", message: rollbackError.message });
+    return false;
   }
 }
 
@@ -404,6 +486,11 @@ function commandErrorText(error) {
   return (error.stderr || error.stdout || error.message || "").toString().trim();
 }
 
+function copilotCliUnavailable(error) {
+  return error?.code === "ENOENT"
+    || /^Cannot find GitHub Copilot CLI(?:\s|$|\()/i.test(commandErrorText(error));
+}
+
 export function pluginListHasPlugin(output, pluginId) {
   const escapedPluginId = pluginId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   return output

package/lib/interaction-presentation.js

@@ -1,3 +1,5 @@
+import { RUN_ID_PATTERN } from "./control-state/run-identity.js";
+
 const REQUIRED_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const ARTEFACT_ORDER = ["UR", "PRD", "SD", "TP"];
 const OUTCOMES = new Set(["approve", "revise", "decline", "cancel", "no_response", "timeout", "empty", "invalid", "stale"]);
@@ -313,17 +315,37 @@ function operationalBreadcrumb(value, labels) {
     .join(labels.breadcrumbSeparator);
 }
 
+export function validateOperationalStatusCardPreconditions(statusCard, {
+  registry,
+  humanPresentation,
+} = {}) {
+  const errors = [];
+  if (!plainObject(statusCard)) errors.push("status_card_missing");
+  if (humanPresentation !== undefined && !plainObject(humanPresentation)) errors.push("human_presentation_missing");
+  if (plainObject(statusCard)) {
+    if (!String(statusCard.run_id ?? "").trim()) errors.push("run_id_missing");
+    if (!String(statusCard.current_gate ?? "").trim()) errors.push("current_gate_missing");
+    let locale = "";
+    try {
+      locale = resolvePresentationLocale(registry, statusCard.presentation_language);
+    } catch {
+      locale = "";
+    }
+    if (!locale) errors.push("locale_unresolved");
+  }
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
 export function renderOperationalStatusCard(statusCard, {
   registry,
   humanPresentation,
   revisionId = "",
 } = {}) {
-  if (!plainObject(statusCard) || !plainObject(humanPresentation)) return null;
+  if (!validateOperationalStatusCardPreconditions(statusCard, { registry, humanPresentation: humanPresentation ?? null }).valid) return null;
   const runId = String(statusCard.run_id ?? "").trim();
   const currentGate = String(statusCard.current_gate ?? "").trim();
   const revision = String(revisionId ?? "").trim() || "unversioned";
   const locale = resolvePresentationLocale(registry, statusCard.presentation_language);
-  if (!runId || !currentGate || !locale) return null;
 
   const pack = localePack(registry, locale);
   const labels = pack.statusCard;
@@ -537,6 +559,37 @@ export function normalizeInteractionOutcome(value, { expectedApproval, stale = f
   return "invalid";
 }
 
+export function validateApprovalOrientationPreconditions({
+  statusCard,
+  humanPresentation,
+  registry,
+  requestedLocale,
+} = {}) {
+  const errors = [];
+  if (!plainObject(statusCard)) return Object.freeze({ valid: false, errors: Object.freeze(["status_card_missing"]) });
+  if (humanPresentation !== undefined && !plainObject(humanPresentation)) errors.push("human_presentation_missing");
+  const gate = String(statusCard.current_gate ?? "").trim();
+  const runId = String(statusCard.run_id ?? "").trim();
+  if (!REQUIRED_GATES.includes(gate)) errors.push("gate_not_user_gate");
+  if (!RUN_ID_PATTERN.test(runId)) errors.push("run_id_invalid");
+  if (statusCard.status !== "open") errors.push("status_not_open");
+  if (statusCard.missing_approval !== `Approval: ${gate}`) errors.push("missing_approval_mismatch");
+  const nextGate = String(statusCard.next_gate_after_approval ?? "none");
+  const nextUserGate = String(statusCard.next_user_gate ?? "").trim();
+  const userActionRequired = String(statusCard.user_action_required ?? "").trim();
+  const userActionSemanticsValid = (userActionRequired === "no" && nextUserGate === "none")
+    || (userActionRequired === "yes" && REQUIRED_GATES.includes(nextUserGate) && nextGate === nextUserGate);
+  if (!userActionSemanticsValid) errors.push("user_action_semantics_invalid");
+  let locale = "";
+  try {
+    locale = resolvePresentationLocale(registry, requestedLocale);
+  } catch {
+    locale = "";
+  }
+  if (!locale) errors.push("locale_unresolved");
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
 export function buildApprovalOrientationSnapshot({
   ready = false,
   statusCard,
@@ -545,11 +598,11 @@ export function buildApprovalOrientationSnapshot({
   registry,
   requestedLocale,
 } = {}) {
-  if (!ready || !plainObject(statusCard) || !plainObject(humanPresentation)) return null;
+  if (!ready) return null;
+  if (!validateApprovalOrientationPreconditions({ statusCard, humanPresentation: humanPresentation ?? null, registry, requestedLocale }).valid) return null;
   const gate = String(statusCard.current_gate ?? "").trim();
   const runId = String(statusCard.run_id ?? "").trim();
   const expectedApproval = `Approval: ${gate}`;
-  if (!REQUIRED_GATES.includes(gate) || !/^[A-Za-z0-9._-]+$/.test(runId) || statusCard.status !== "open" || statusCard.missing_approval !== expectedApproval) return null;
 
   const locale = resolvePresentationLocale(registry, requestedLocale);
   const pack = localePack(registry, locale);
@@ -560,9 +613,6 @@ export function buildApprovalOrientationSnapshot({
   const nextGate = String(statusCard.next_gate_after_approval ?? "none");
   const nextUserGate = String(statusCard.next_user_gate ?? "").trim();
   const userActionRequired = String(statusCard.user_action_required ?? "").trim();
-  const userActionSemanticsValid = (userActionRequired === "no" && nextUserGate === "none")
-    || (userActionRequired === "yes" && REQUIRED_GATES.includes(nextUserGate) && nextGate === nextUserGate);
-  if (!userActionSemanticsValid) return null;
   const narration = pack.primary.narration.gates[gate] ?? {};
   const nextDecision = userActionRequired === "no"
     ? pack.primary.narration.noAction

package/lib/lifecycle/operations.js

@@ -2,6 +2,11 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pluginDefinition } from "../cli/runtime-context.js";
+import {
+  applyCopilotRepositoryDisable,
+  planCopilotRepositoryDisable,
+  verifyCopilotRepositoryDisabled,
+} from "../installers/copilot-settings.js";
 import { evaluateOpenCodeStatus, openCodeNpmInvocation } from "../installers/opencode.js";
 import { inspectPluginSurface } from "../installers/plugin-installers.js";
 import { inspectGeneratedRepositoryMarketplace } from "../runtime/plugin-provenance.js";
@@ -19,8 +24,22 @@ function repositorySelector(targetDir, config = "") {
   return pluginSection(config, "agdf@agdf-repo") ? "agdf@agdf-repo" : "agdf@agdf";
 }
 
-export function planRepositoryDisable(targetDir, surface) {
-  if (surface !== "codex") {
+export function planRepositoryDisable(targetDir, surface, { shared = false, exec = execFileSync } = {}) {
+  if (surface === "copilot") {
+    const settings = planCopilotRepositoryDisable({ targetDir, shared, exec });
+    return Object.freeze({
+      operation: "disable",
+      surface,
+      scope: "repository",
+      audience: settings.audience,
+      mutations: Object.freeze(settings.changed
+        ? [{ kind: "copilot_settings", path: settings.path, settings }]
+        : []),
+      retained: Object.freeze([join(targetDir, ".agdf", "control"), "global AGDF plugin availability", "independent repository instructions"]),
+      expected: Object.freeze({ repository_status: "configured_disabled", activation_status: "pending_restart", settings_path: settings.path }),
+    });
+  }
+  if (surface !== "codex" || shared) {
     throw new Error(`Repository disable is not supported safely for ${surface}; no files were changed.`);
   }
   const path = join(targetDir, ".codex", "config.toml");
@@ -49,7 +68,9 @@ export function planRepositoryDisable(targetDir, surface) {
   });
 }
 
-export function verifyRepositoryDisabled(targetDir) {
+export function verifyRepositoryDisabled(targetDir, surface = "codex", { shared = false } = {}) {
+  if (surface === "copilot") return verifyCopilotRepositoryDisabled(targetDir, { shared });
+  if (surface !== "codex") return { status: "failed", evidence: [`unsupported_surface:${surface}`] };
   const path = join(targetDir, ".codex", "config.toml");
   if (!existsSync(path)) return { status: "failed", evidence: [`missing:${path}`] };
   const config = readFileSync(path, "utf8");
@@ -165,7 +186,7 @@ function nativeUninstallPlan(surface, executable, args) {
   });
 }
 
-export function applyLifecyclePlan(plan, { exec = execFileSync } = {}) {
+export function applyLifecyclePlan(plan, { exec = execFileSync, applyCopilotSettings = applyCopilotRepositoryDisable } = {}) {
   const completed = [];
   for (const mutation of plan.mutations) {
     try {
@@ -173,6 +194,9 @@ export function applyLifecyclePlan(plan, { exec = execFileSync } = {}) {
         mkdirSync(dirname(mutation.path), { recursive: true });
         writeFileSync(mutation.path, mutation.content, "utf8");
         completed.push({ kind: "write", path: mutation.path });
+      } else if (mutation.kind === "copilot_settings") {
+        const result = applyCopilotSettings(mutation.settings);
+        completed.push({ kind: "copilot_settings", path: mutation.path, status: result.status });
       } else if (mutation.kind === "remove") {
         rmSync(mutation.path);
         completed.push({ kind: "remove", path: mutation.path });

package/lib/lifecycle/result.js

@@ -3,10 +3,10 @@ const RESULTS = new Set(["success", "partial", "failed", "preview"]);
 const SCOPES = new Set(["global", "repository"]);
 const SURFACES = new Set(["codex", "claude", "copilot", "opencode", "generic"]);
 const GLOBAL_INSTALL_RESTART_ACTIONS = Object.freeze({
-  codex: "Restart Codex.",
-  claude: "Restart Claude Code.",
-  copilot: "Restart GitHub Copilot.",
-  opencode: "Restart OpenCode.",
+  codex: "Fully restart Codex, then start a fresh session. Restoring the previous session can retain stale AGDF skills.",
+  claude: "Fully restart Claude Code, then start a fresh session. Restoring the previous session can retain stale AGDF skills.",
+  copilot: "Fully restart GitHub Copilot, then start a fresh session. Restoring the previous session can retain stale AGDF skills.",
+  opencode: "Fully restart OpenCode, then start a fresh session. Restoring the previous session can retain stale AGDF skills.",
 });
 
 function text(value) {

package/lib/release/profile-history.js

@@ -0,0 +1,222 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  classifyHistoricalDistributionProfile,
+  validateDistributionProfileHistory,
+} from "../runtime/distribution-profile-history.js";
+
+export const SUPPORTED_PROFILE_RELEASES = Object.freeze([
+  "0.13.6",
+  "0.13.7",
+  "0.13.8",
+  "0.14.1",
+  "0.14.2",
+  "0.14.3",
+]);
+
+const HISTORY_PATH = "plugin/meta/distribution-profile-history.json";
+const GENERATED_HISTORY_PATHS = [
+  "create-agdf/generated/plugins/agdf/meta/distribution-profile-history.json",
+  "create-agdf/generated/plugins/copilot/agdf/meta/distribution-profile-history.json",
+];
+
+function fail(reason, detail) {
+  const error = new Error(`${reason}: ${detail}`);
+  error.code = reason;
+  throw error;
+}
+
+function parseJson(content, reason, label) {
+  try {
+    return JSON.parse(content);
+  } catch {
+    fail(reason, `${label} is not valid JSON`);
+  }
+}
+
+function defaultReadTagFile(repoRoot) {
+  return (tag, relativePath) => execFileSync(
+    "git",
+    ["show", `${tag}:${relativePath}`],
+    { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+  );
+}
+
+function defaultTagExists(repoRoot) {
+  return (tag) => {
+    try {
+      execFileSync(
+        "git",
+        ["rev-parse", "--verify", "--quiet", `refs/tags/${tag}`],
+        { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  };
+}
+
+function assertTagRecord(catalogue, version, readTagFile) {
+  const tag = `agdf-v${version}`;
+  let definition;
+  let packageManifest;
+  let codexManifest;
+  try {
+    definition = parseJson(readTagFile(tag, "plugin/meta/agdf-plugin.definition.json"), "profile_history_tag_mismatch", `${tag} definition`);
+    packageManifest = parseJson(readTagFile(tag, "create-agdf/package.json"), "profile_history_tag_mismatch", `${tag} package`);
+    codexManifest = parseJson(readTagFile(tag, "plugin/.codex-plugin/plugin.json"), "profile_history_tag_mismatch", `${tag} Codex manifest`);
+  } catch (error) {
+    if (error.code === "profile_history_tag_mismatch") throw error;
+    fail("profile_history_tag_mismatch", `${tag} evidence is unavailable`);
+  }
+  if (definition.version !== version || packageManifest.version !== version || codexManifest.version !== version) {
+    fail("profile_history_tag_mismatch", `${tag} does not identify exact version ${version}`);
+  }
+  const classification = classifyHistoricalDistributionProfile({
+    catalogue,
+    version,
+    distributionProfiles: definition.distributionProfiles,
+  });
+  if (classification.status !== "matched") {
+    fail("profile_history_tag_mismatch", `${tag} does not match its catalogue contract`);
+  }
+}
+
+function assertIncoherentTagNegative(catalogue, readTagFile) {
+  if (Object.hasOwn(catalogue.releases, "0.14.0")) {
+    fail("profile_history_tag_mismatch", "incoherent agdf-v0.14.0 must not have a release record");
+  }
+  const tag = "agdf-v0.14.0";
+  let versions;
+  try {
+    versions = [
+      parseJson(readTagFile(tag, "plugin/meta/agdf-plugin.definition.json"), "profile_history_tag_mismatch", `${tag} definition`).version,
+      parseJson(readTagFile(tag, "create-agdf/package.json"), "profile_history_tag_mismatch", `${tag} package`).version,
+      parseJson(readTagFile(tag, "plugin/.codex-plugin/plugin.json"), "profile_history_tag_mismatch", `${tag} Codex manifest`).version,
+    ];
+  } catch (error) {
+    if (error.code === "profile_history_tag_mismatch") throw error;
+    fail("profile_history_tag_mismatch", `${tag} negative evidence is unavailable`);
+  }
+  if (versions.some((version) => version !== "0.13.8")) {
+    fail("profile_history_tag_mismatch", `${tag} must remain the explicit internally-0.13.8 negative`);
+  }
+}
+
+function baselineFromRepository(repoRoot) {
+  let mergeBase;
+  try {
+    mergeBase = execFileSync(
+      "git",
+      ["merge-base", "HEAD", "origin/main"],
+      { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+  } catch {
+    fail("profile_history_continuity_break", "merge-base evidence is unavailable");
+  }
+  try {
+    return execFileSync(
+      "git",
+      ["show", `${mergeBase}:${HISTORY_PATH}`],
+      { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+  } catch {
+    let matchingPaths;
+    try {
+      matchingPaths = execFileSync(
+        "git",
+        ["ls-tree", "--name-only", mergeBase, "--", HISTORY_PATH],
+        { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+      ).trim();
+    } catch {
+      fail("profile_history_continuity_break", "baseline tree evidence is unavailable");
+    }
+    if (matchingPaths === "") return null;
+    fail("profile_history_continuity_break", "baseline catalogue cannot be read");
+  }
+}
+
+function assertContinuity(catalogue, baselineContent) {
+  if (baselineContent === null) return "initial_catalogue";
+  if (baselineContent === undefined) {
+    fail("profile_history_continuity_break", "baseline continuity evidence is unavailable");
+  }
+  const baseline = parseJson(baselineContent, "profile_history_continuity_break", "baseline catalogue");
+  if (validateDistributionProfileHistory(baseline).status !== "matched") {
+    fail("profile_history_continuity_break", "baseline catalogue is invalid");
+  }
+  for (const [version, priorRelease] of Object.entries(baseline.releases)) {
+    const currentRelease = catalogue.releases[version];
+    const priorContract = baseline.contracts[priorRelease.contract_id];
+    const currentContract = catalogue.contracts[currentRelease?.contract_id];
+    if (JSON.stringify(currentRelease) !== JSON.stringify(priorRelease)
+        || JSON.stringify(currentContract) !== JSON.stringify(priorContract)) {
+      fail("profile_history_continuity_break", `supported release ${version} was removed or changed`);
+    }
+  }
+  return "matched";
+}
+
+export function assertDistributionProfileHistory({
+  repoRoot,
+  catalogueContent,
+  generatedContents,
+  currentDefinition,
+  readTagFile,
+  tagExists,
+  baselineContent,
+} = {}) {
+  repoRoot = repoRoot ? resolve(repoRoot) : null;
+  catalogueContent ??= readFileSync(join(repoRoot, HISTORY_PATH), "utf8");
+  const canonicalBytes = catalogueContent.replaceAll("\r\n", "\n");
+  const catalogue = parseJson(canonicalBytes, "profile_history_invalid", "distribution profile history");
+  if (validateDistributionProfileHistory(catalogue).status !== "matched") {
+    fail("profile_history_invalid", "catalogue schema or digest validation failed");
+  }
+
+  currentDefinition ??= JSON.parse(readFileSync(join(repoRoot, "plugin", "meta", "agdf-plugin.definition.json"), "utf8"));
+  const current = classifyHistoricalDistributionProfile({
+    catalogue,
+    version: currentDefinition.version,
+    distributionProfiles: currentDefinition.distributionProfiles,
+  });
+  if (current.status !== "matched") {
+    fail("profile_history_current_release_mismatch", `current definition ${currentDefinition.version} has no exact matching snapshot`);
+  }
+
+  generatedContents ??= Object.fromEntries(GENERATED_HISTORY_PATHS.map((path) => [
+    path,
+    existsSync(join(repoRoot, path)) ? readFileSync(join(repoRoot, path), "utf8") : null,
+  ]));
+  for (const path of GENERATED_HISTORY_PATHS) {
+    if (generatedContents[path] !== canonicalBytes) {
+      fail("profile_history_current_release_mismatch", `generated catalogue drift at ${path}`);
+    }
+  }
+
+  const suppliedReadTagFile = Boolean(readTagFile);
+  readTagFile ??= defaultReadTagFile(repoRoot);
+  tagExists ??= suppliedReadTagFile && !repoRoot ? () => true : defaultTagExists(repoRoot);
+  const supportedVersions = [...new Set([
+    ...SUPPORTED_PROFILE_RELEASES,
+    ...Object.keys(catalogue.releases),
+  ])];
+  for (const version of supportedVersions) {
+    const tag = `agdf-v${version}`;
+    if (version === currentDefinition.version && !tagExists(tag)) continue;
+    assertTagRecord(catalogue, version, readTagFile);
+  }
+  assertIncoherentTagNegative(catalogue, readTagFile);
+
+  if (baselineContent === undefined && repoRoot) baselineContent = baselineFromRepository(repoRoot);
+  const continuity = assertContinuity(catalogue, baselineContent);
+  return {
+    catalogue,
+    currentVersion: currentDefinition.version,
+    supportedVersions,
+    generatedPaths: [...GENERATED_HISTORY_PATHS],
+    continuity,
+  };
+}