create-agdf 0.10.0 → 0.10.2

package/lib/installers/plugin-installers.js

@@ -1,41 +1,117 @@
 import { execFileSync } from "node:child_process";
 import { pluginDefinition } from "../cli/runtime-context.js";
+import { classifyMarketplaceList, prepareLocalMarketplace } from "./local-marketplace.js";
 
-export function installCodexGlobalPlugin({ exec = execFileSync, io = console } = {}) {
+export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
-  nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], "marketplace", captureOptions()));
-  nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "upgrade", "agdf"], "marketplace", captureOptions()));
-  nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], "plugin_operation", captureOptions()));
-  const listOutput = runPluginPhase(exec, "codex", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
-  const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
-  if (installedVersion !== expectedVersion) {
-    throw lifecycleAdapterError("version", versionMismatchMessage("Codex", "agdf@agdf", expectedVersion, installedVersion, "codex plugin marketplace upgrade agdf && codex plugin add agdf --marketplace agdf"));
+  const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
+  const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  try {
+    const marketplaceOutput = runPluginPhase(exec, "codex", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
+    migrateMarketplace({ surface: "codex", exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], "plugin_operation", captureOptions()));
+    const listOutput = runPluginPhase(exec, "codex", ["plugin", "list"], "verification", captureOptions());
+    const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
+    if (installedVersion !== expectedVersion) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("Codex", "agdf@agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest codex"));
+    }
+    transaction.commit();
+    return {
+      surface: "codex", operation: migration.state === "owned_local_current" ? "update" : "install", expectedVersion, installedVersion, verificationStatus: "healthy",
+      evidence: ["durable_local_marketplace", `marketplace:${migration.state}`, "codex plugin list"],
+      nativeOutput: nativeOutput.filter(Boolean).map(String),
+    };
+  } catch (error) {
+    recoverMarketplace({ surface: "codex", exec, migration, transaction, error });
+    throw error;
   }
-  return { surface: "codex", expectedVersion, installedVersion, verificationStatus: "healthy", evidence: ["codex plugin list"], nativeOutput: nativeOutput.filter(Boolean).map(String) };
 }
 
-export function installClaudeGlobalPlugin({ exec = execFileSync, io = console } = {}) {
+export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
-  nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], "marketplace", captureOptions()));
-  nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "update", "agdf"], "marketplace", captureOptions()));
-  const beforeList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
-  const alreadyInstalled = pluginListHasPlugin(beforeList, "agdf@agdf");
-  nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", alreadyInstalled ? "update" : "install", "agdf@agdf"], "plugin_operation", captureOptions()));
-  const afterList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
-  const installedVersion = pluginVersionFromList(afterList, "agdf@agdf");
-  if (installedVersion && installedVersion !== expectedVersion) {
-    throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "claude plugin marketplace update agdf && claude plugin update agdf@agdf"));
+  const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
+  const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  try {
+    const marketplaceOutput = runPluginPhase(exec, "claude", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
+    migrateMarketplace({ surface: "claude", exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "update", "agdf"], "marketplace", captureOptions()));
+    const beforeList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", captureOptions());
+    const alreadyInstalled = pluginListHasPlugin(beforeList, "agdf@agdf");
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", alreadyInstalled ? "update" : "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) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest claude"));
+    }
+    transaction.commit();
+    return {
+      surface: "claude",
+      operation: migration.state === "owned_local_current" ? "update" : "install",
+      expectedVersion,
+      installedVersion,
+      verificationStatus: installedVersion ? "healthy" : "degraded",
+      evidence: ["durable_local_marketplace", `marketplace:${migration.state}`, "claude plugin list", ...(installedVersion ? [] : ["host_did_not_expose_version"])],
+      nativeOutput: nativeOutput.filter(Boolean).map(String),
+    };
+  } catch (error) {
+    recoverMarketplace({ surface: "claude", exec, migration, transaction, error });
+    throw error;
+  }
+}
+
+function migrateMarketplace({ surface, exec, output, root, nativeOutput, migration }) {
+  const classification = classifyMarketplaceList(surface, output, root);
+  Object.assign(migration, classification);
+  if (["conflict", "unknown"].includes(classification.state)) {
+    throw lifecycleAdapterError("marketplace", `Refusing to replace non-AGDF marketplace registration agdf (${classification.reason || classification.state}).`, classification);
   }
-  return {
-    surface: "claude",
-    expectedVersion,
-    installedVersion,
-    verificationStatus: installedVersion ? "healthy" : "degraded",
-    evidence: ["claude plugin list", ...(installedVersion ? [] : ["host_did_not_expose_version"])],
-    nativeOutput: nativeOutput.filter(Boolean).map(String),
+  const executable = surface === "claude" ? "claude" : "codex";
+  if (classification.state === "legacy_github") {
+    const args = surface === "claude"
+      ? ["plugin", "marketplace", "remove", "agdf", "--scope", "user"]
+      : ["plugin", "marketplace", "remove", "agdf", "--json"];
+    nativeOutput.push(runPluginPhase(exec, executable, args, "marketplace", captureOptions()));
+    migration.removedLegacy = true;
+  }
+  if (["absent", "legacy_github"].includes(classification.state)) {
+    const args = surface === "claude"
+      ? ["plugin", "marketplace", "add", root, "--scope", "user"]
+      : ["plugin", "marketplace", "add", root, "--json"];
+    nativeOutput.push(runPluginPhase(exec, executable, args, "marketplace", captureOptions()));
+    migration.addedLocal = true;
+  }
+}
+
+function recoverMarketplace({ surface, exec, migration, transaction, error }) {
+  const executable = surface === "claude" ? "claude" : "codex";
+  const recovery = [];
+  const attempt = (args) => {
+    try {
+      exec(executable, args, captureOptions());
+      recovery.push({ args, status: "restored" });
+    } catch (rollbackError) {
+      recovery.push({ args, status: "failed", message: commandErrorText(rollbackError) });
+    }
   };
+  if (migration?.addedLocal) {
+    attempt(surface === "claude"
+      ? ["plugin", "marketplace", "remove", "agdf", "--scope", "user"]
+      : ["plugin", "marketplace", "remove", "agdf", "--json"]);
+  }
+  if (migration?.removedLegacy && migration.source) {
+    attempt(surface === "claude"
+      ? ["plugin", "marketplace", "add", migration.source, "--scope", "user"]
+      : ["plugin", "marketplace", "add", migration.source, "--json"]);
+  }
+  try {
+    transaction.rollback();
+    recovery.push({ filesystem: transaction.root, status: "restored" });
+  } catch (rollbackError) {
+    recovery.push({ filesystem: transaction.root, status: "failed", message: rollbackError.message });
+  }
+  error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
 }
 
 function captureOptions() {

package/lib/runtime/local-validator.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import process from "node:process";
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function digestDirectory(root) {
+  const files = [];
+  function visit(directory) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const stats = statSync(path);
+      if (stats.isDirectory()) visit(path);
+      else if (stats.isFile()) files.push(path);
+    }
+  }
+  visit(root);
+  const hash = createHash("sha256");
+  for (const path of files) {
+    hash.update(relative(root, path).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(readFileSync(path));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function envelope(machineValidation, options, evidence = {}) {
+  return {
+    schema_version: "1",
+    machine_validation: machineValidation,
+    surface: options.surface,
+    expected_version: options.expectedVersion,
+    observed_version: evidence.observedVersion ?? null,
+    source: evidence.source ?? null,
+    registry_access: false,
+    ...(evidence.reason ? { reason: evidence.reason } : {}),
+  };
+}
+
+export function resolveLocalValidator(options) {
+  if (options.ownedPackageRoot) {
+    const packageManifest = readJson(join(options.ownedPackageRoot, "package.json"));
+    const observedVersion = packageManifest?.version ?? null;
+    if (!packageManifest) {
+      return { envelope: envelope("unavailable", options, { source: "config_local_package", reason: "package_missing" }) };
+    }
+    if (observedVersion !== options.expectedVersion) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "config_local_package" }) };
+    }
+    const entrypoint = join(options.ownedPackageRoot, "bin", "create-agdf.js");
+    if (!existsSync(entrypoint)) {
+      return { envelope: envelope("unavailable", options, { observedVersion, source: "config_local_package", reason: "entrypoint_missing" }) };
+    }
+    return {
+      envelope: envelope("owned_version_matched", options, { observedVersion, source: "config_local_package" }),
+      executable: process.execPath,
+      prefixArgs: [entrypoint],
+    };
+  }
+  const manifestPath = join(options.runtimeRoot, "runtime-manifest.json");
+  const manifestExists = existsSync(manifestPath);
+  const manifest = manifestExists ? readJson(manifestPath) : null;
+  if (manifestExists && !manifest) {
+    return { envelope: envelope("version_mismatch", options, { source: "plugin_bundle", reason: "manifest_invalid" }) };
+  }
+  if (manifest) {
+    const packageRoot = join(options.runtimeRoot, "create-agdf");
+    if (!existsSync(packageRoot)) {
+      return { envelope: envelope("unavailable", options, { source: "plugin_bundle", reason: "package_missing" }) };
+    }
+    const packageManifest = readJson(join(packageRoot, "package.json"));
+    const observedVersion = packageManifest?.version ?? manifest.version ?? null;
+    if (observedVersion !== options.expectedVersion || manifest.version !== options.expectedVersion) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "plugin_bundle" }) };
+    }
+    let observedDigest = null;
+    try { observedDigest = digestDirectory(packageRoot); } catch {}
+    if (!observedDigest || manifest.digest !== observedDigest) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "plugin_bundle", reason: "digest_mismatch" }) };
+    }
+    const entrypoint = resolve(options.runtimeRoot, manifest.entrypoint ?? "");
+    const entrypointRelative = relative(options.runtimeRoot, entrypoint);
+    if (!manifest.entrypoint || entrypointRelative === ".." || entrypointRelative.startsWith(`..${sep}`) || isAbsolute(entrypointRelative)) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "plugin_bundle", reason: "invalid_entrypoint" }) };
+    }
+    if (!existsSync(entrypoint)) {
+      return { envelope: envelope("unavailable", options, { observedVersion, source: "plugin_bundle", reason: "entrypoint_missing" }) };
+    }
+    return {
+      envelope: envelope("owned_version_matched", options, { observedVersion, source: "plugin_bundle" }),
+      executable: process.execPath,
+      prefixArgs: [entrypoint],
+    };
+  }
+
+  const configuredPath = options.configuredPath ?? process.env.AGDF_VALIDATOR_PATH ?? "";
+  if (configuredPath) {
+    if (!isAbsolute(configuredPath) || !existsSync(configuredPath)) {
+      return { envelope: envelope("unavailable", options, { source: "configured_path", reason: "invalid_absolute_path" }) };
+    }
+    const versionProbe = spawnSync(configuredPath, ["--version", "--json"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    let observedVersion = null;
+    try { observedVersion = JSON.parse(versionProbe.stdout)?.version ?? null; } catch {}
+    if (versionProbe.status !== 0 || observedVersion !== options.expectedVersion) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "configured_path" }) };
+    }
+    return {
+      envelope: envelope("configured_version_matched", options, { observedVersion, source: "configured_path" }),
+      executable: configuredPath,
+      prefixArgs: [],
+    };
+  }
+
+  return { envelope: envelope(options.externalRequired ? "external_required" : "unavailable", options) };
+}
+
+export function runLocalValidator(options, args, io = console) {
+  const resolved = resolveLocalValidator(options);
+  if (args[0] === "--resolve-only") {
+    io.log(JSON.stringify(resolved.envelope, null, args.includes("--json") ? 2 : 0));
+    return resolved.executable ? 0 : 2;
+  }
+  if (!resolved.executable) {
+    io.error(JSON.stringify(resolved.envelope));
+    return 2;
+  }
+  const child = spawnSync(resolved.executable, [...resolved.prefixArgs, ...args], {
+    cwd: options.cwd ?? process.cwd(),
+    env: { ...process.env, AGDF_MACHINE_VALIDATION: resolved.envelope.machine_validation },
+    stdio: "inherit",
+  });
+  return child.status ?? 2;
+}

package/lib/runtime/validator-application.js

@@ -0,0 +1,40 @@
+import process from "node:process";
+import { createValidationHandlers } from "../cli/validation-handlers.js";
+import { validateCommandOptions } from "../cli/command-registry.js";
+import { CliUsageError, parseArgs } from "../cli/parse-args.js";
+import { pluginDefinition } from "../cli/runtime-context.js";
+
+const validatorCommands = new Set(["doctor", "gate-check", "delivery-map", "delivery-path-search"]);
+
+export async function runValidatorCli(argv = process.argv.slice(2), adapters = {}) {
+  const io = adapters.io ?? console;
+  if (argv.includes("--version")) {
+    const output = { name: "create-agdf", version: pluginDefinition.version };
+    io.log(argv.includes("--json") ? JSON.stringify(output) : output.version);
+    return 0;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs(argv, adapters.parser);
+  } catch (error) {
+    if (!(error instanceof CliUsageError)) throw error;
+    io.error(error.message);
+    return error.exitCode;
+  }
+  if (parsed.kind === "help") {
+    io.log("AGDF surface-local validator: doctor | gate-check | delivery-map | delivery-path-search");
+    return 0;
+  }
+  let options;
+  try {
+    options = validateCommandOptions(parsed.options);
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  if (!validatorCommands.has(options.target)) {
+    io.error(`The surface-local validator does not support lifecycle command: ${options.target}`);
+    return 1;
+  }
+  return await createValidationHandlers(io).get(options.target)(options);
+}

package/lib/scaffold/plan.js

@@ -1,12 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { generatedRoot, languageConfigContent, pluginDefinition } from "../cli/runtime-context.js";
+export { doctorRequiredFiles } from "../control-evaluation/required-files.js";
 
 export const agdfFragmentPath = "AGENTS.agdf.md";
-export const openCodeConfigFragmentPath = "opencode.agdf.json";
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
-const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.skillPrefix}${skill.slug}`);
 const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`);
 const contractModules = [
   "gate-transition.md",
@@ -94,13 +93,6 @@ const artefactTemplateFiles = [
   join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
   join(".agdf", "control", "templates", "artefacts", "OR.md"),
 ];
-export const doctorRequiredFiles = [
-  join(".agdf", "control", "AGDF_RUN.md"),
-  join(".agdf", "control", "MASTER_BACKLOG.md"),
-  join(".agdf", "control", "SOT_REGISTRY.md"),
-  join(".agdf", "control", "CONTEXT_GRAPH.md"),
-  join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json"),
-];
 const copilotInstructionFiles = [
   join(".github", "copilot-instructions.md"),
   join(".github", "instructions", "agdf-governance.instructions.md"),
@@ -111,13 +103,6 @@ const copilotSkillFiles = [
   ...contractModules.map((moduleName) => join(".github", "skills", "contracts", moduleName)),
   ...copilotSkillNames.map((skillName) => join(".github", "skills", skillName, "SKILL.md")),
 ];
-const openCodeFiles = [
-  join(".opencode", pluginDefinition.opencode.instructionsFileName),
-  join(".opencode", "README.md"),
-  join(".opencode", pluginDefinition.opencode.runtimeContractFileName),
-  ...contractModules.map((moduleName) => join(".opencode", "contracts", moduleName)),
-  ...openCodeSkillNames.map((skillName) => join(".opencode", "skills", skillName, "SKILL.md")),
-];
 
 function loadAsset(relativePath) {
   return readFileSync(join(generatedRoot, relativePath), "utf8");
@@ -252,19 +237,6 @@ export function generatedFilesForTarget(target, targetDir, force, languagePrefer
 
   if (target === "opencode-repo") {
     addLanguageConfig(files, languagePreference);
-    const openCodeConfigTargetPath = existsSync(join(targetDir, "opencode.json")) && !force ? openCodeConfigFragmentPath : "opencode.json";
-    files.push({
-      path: openCodeConfigTargetPath,
-      content: loadAsset("opencode.json"),
-    });
-
-    for (const openCodePath of openCodeFiles) {
-      files.push({
-        path: openCodePath,
-        content: loadAsset(openCodePath),
-      });
-    }
-
     for (const controlPath of controlFiles) {
       files.push({
         path: controlPath,
@@ -275,4 +247,3 @@ export function generatedFilesForTarget(target, targetDir, force, languagePrefer
 
   return files;
 }
-

package/lib/scaffold/presentation.js

@@ -3,11 +3,11 @@ import { join } from "node:path";
 import { pluginDefinition } from "../cli/runtime-context.js";
 import { printLifecycleResult } from "../lifecycle/presentation.js";
 import { createLifecycleResult } from "../lifecycle/result.js";
-import { agdfFragmentPath, openCodeConfigFragmentPath } from "./plan.js";
+import { agdfFragmentPath } from "./plan.js";
 
 const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
 
-export function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents = [], { verbose = false, json = false, io = console } = {}) {
+export function printNextSteps(target, destination, files, wroteAgentsFragment, removedOpenCodeAgents = [], { verbose = false, json = false, io = console } = {}) {
   const repositorySurface = { "codex-repo": "codex", "opencode-repo": "opencode", copilot: "copilot" }[target];
   const verified = files.every((file) => {
     const path = join(destination, file.path);
@@ -17,7 +17,7 @@ export function printNextSteps(target, destination, files, wroteAgentsFragment,
     const nextAction = repositorySurface === "codex"
       ? "Restart Codex, open /plugins, select This repository and install agdf; then start a new task with: Run an AGDF gate check for this request."
       : repositorySurface === "opencode"
-        ? "Restart OpenCode in this repository so it loads the generated AGDF repository configuration."
+        ? "Restart OpenCode in this repository so the global AGDF plugin observes the durable control configuration."
         : "Run /instructions in GitHub Copilot CLI to confirm that the generated AGDF repository instructions are visible.";
     printLifecycleResult(createLifecycleResult({
       operation: "repository_setup",
@@ -70,13 +70,13 @@ export function printNextSteps(target, destination, files, wroteAgentsFragment,
   }
   if (target === "init") {
     io.log("- Create or migrate a canonical run, then fill its RUN_STATE.md with the current gate, evidence and next allowed action.");
-    io.log("- Run npx --yes @agdf/cli@latest doctor to check the control state before the next agent run.");
+    io.log("- Run the installed `agdf doctor` to check the control state before the next agent run.");
     io.log("- Commit the live control files once they represent the repository's current delivery state.");
     return;
   }
   if (target === "config") {
     io.log("- Restart or start a new agent session so the AGDF SessionStart hook reads the updated project language config.");
-    io.log("- Run npx --yes @agdf/cli@latest doctor when this repository also uses durable AGDF control state.");
+    io.log("- Run the installed `agdf doctor` when this repository also uses durable AGDF control state.");
     return;
   }
   if (wroteAgentsFragment) {
@@ -90,15 +90,10 @@ export function printNextSteps(target, destination, files, wroteAgentsFragment,
     io.log(`- Optional global Claude Code install: ${pluginInstallCommand}`);
   }
   if (target === "opencode-repo") {
-    if (wroteOpenCodeConfigFragment) {
-      io.log(`- Existing opencode.json detected. Review ${openCodeConfigFragmentPath} and merge its owned entries so OpenCode loads .opencode/AGDF.md; preserve an explicit permission.question decision.`);
-    }
-    io.log(`- OpenCode will install the ${pluginDefinition.opencode.npmPackage} npm plugin from opencode.json at startup.`);
-    io.log("- Optional: also add create-agdf to ~/.config/opencode/opencode.json plugin[] for a user-wide OpenCode hook.");
-    io.log("- The global hook does not replace repository instructions or native skills; this repository's .opencode files remain the AGDF source of truth.");
-    io.log("- Start OpenCode in this repository; it will load opencode.json, .opencode/AGDF.md and the native AGDF skills.");
-    io.log("- Load agdf-gate-check through OpenCode's native skill tool for new build/change intent or unclear approval before later artefacts or implementation.");
-    io.log("- Run npx --yes @agdf/cli@latest init when the repository needs live AGDF control files.");
+    io.log("- Install the global OpenCode surface once with npx --yes @agdf/cli@latest opencode if it is not already installed.");
+    io.log("- Start or restart OpenCode in this repository; valid .agdf/control/config.json activates the global AGDF runtime here.");
+    io.log("- Load agdf-global-gate-check through OpenCode's native skill tool for new build/change intent or unclear approval before later artefacts or implementation.");
+    io.log("- Existing .opencode files are left untouched as a compatibility path; this command does not copy a second runtime surface.");
   }
   if (target === "copilot" || target === "both") {
     io.log("- In GitHub Copilot CLI, run /instructions after the AGENTS.md step is complete to confirm that AGDF instructions and the repository skills are visible.");

package/opencode-plugin.js

@@ -1,16 +1,34 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { evaluateOpenCodeRepositoryActivation } from "./lib/installers/opencode-activation.js";
 
 const packageJson = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
 
 export const AGDFPlugin = async ({ directory, client }) => {
   const controlDir = `${directory}/.agdf/control`;
-  const hasRepositorySurface = () => existsSync(`${directory}/.opencode/AGDF.md`) && existsSync(`${directory}/.opencode/skills/agdf-gate-check/SKILL.md`);
-  const status = () => ({
-    active: true,
+  const activation = () => evaluateOpenCodeRepositoryActivation(directory);
+  const status = () => {
+    const repositoryActivation = activation();
+    return {
+    active: repositoryActivation.active,
     version: packageJson.version,
     controlDir,
-    repositorySurface: hasRepositorySurface(),
-  });
+    repositoryActivation: repositoryActivation.state,
+    repositorySurface: repositoryActivation.legacy_surface,
+    };
+  };
+
+  const activeGuidance = [
+    "## AGDF Runtime Reminder",
+    "This repository is AGDF-active through `.agdf/control/config.json`; use the globally installed AGDF runtime surface.",
+    "For new build/change intent or unclear approval, load the native `agdf-global-gate-check` skill before later artefacts or implementation.",
+    "Use the config-local `agdf/bin/agdf-local.js gate-check --status-card` for compact interactive status. Use `--json` only as deterministic proof for automation or audit evidence, and summarize it instead of mirroring full JSON into chat.",
+  ].join("\n");
+
+  const inactiveGuidance = [
+    "## AGDF Plugin Notice",
+    "The AGDF OpenCode npm plugin is loaded, but this repository has no valid `.agdf/control/config.json`.",
+    "Do not apply AGDF gates from the global plugin alone. Create or repair durable AGDF control state with `npx --yes @agdf/cli@latest opencode-repo` when governance should be active here.",
+  ].join("\n");
 
   return {
     event: async ({ event }) => {
@@ -20,7 +38,7 @@ export const AGDFPlugin = async ({ directory, client }) => {
           body: {
             service: "agdf",
             level: "info",
-            message: currentStatus.repositorySurface ? "AGDF OpenCode active" : "AGDF OpenCode global hook active without repository surface",
+            message: currentStatus.active ? "AGDF OpenCode active through durable control" : "AGDF OpenCode global hook active without durable control",
             extra: currentStatus,
           },
         });
@@ -29,29 +47,19 @@ export const AGDFPlugin = async ({ directory, client }) => {
 
     "shell.env": async (_input, output) => {
       const currentStatus = status();
-      output.env.AGDF_PLUGIN_ACTIVE = "1";
+      output.env.AGDF_PLUGIN_ACTIVE = currentStatus.active ? "1" : "0";
       output.env.AGDF_PLUGIN_VERSION = currentStatus.version;
       output.env.AGDF_CONTROL_DIR = controlDir;
       output.env.AGDF_OPENCODE_REPOSITORY_SURFACE = currentStatus.repositorySurface ? "1" : "0";
+      output.env.AGDF_OPENCODE_REPOSITORY_ACTIVATION = currentStatus.repositoryActivation;
     },
 
-    "experimental.session.compacting": async (_input, output) => {
-      if (!hasRepositorySurface()) {
-        output.context.push([
-          "## AGDF Plugin Notice",
-          "The AGDF OpenCode npm plugin is loaded, but this repository does not contain the AGDF OpenCode surface.",
-          "Do not apply AGDF gates from the global plugin alone; repository instructions, native skills and control files are the source of truth.",
-          "Run `npx --yes @agdf/cli@latest opencode-repo` in this repository when AGDF governance should be active here.",
-        ].join("\n"));
-        return;
-      }
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(activation().active ? activeGuidance : inactiveGuidance);
+    },
 
-      output.context.push([
-        "## AGDF Runtime Reminder",
-        "Use `.opencode/AGDF.md`, `.opencode/skills/` and `.agdf/control/` as the AGDF source for this OpenCode session.",
-        "For new build/change intent or unclear approval, load the native `agdf-gate-check` skill before later artefacts or implementation.",
-        "Use `npx --yes @agdf/cli@latest gate-check --status-card` for compact interactive status. Use `--json` only as deterministic proof for automation or audit evidence, and summarize it instead of mirroring full JSON into chat.",
-      ].join("\n"));
+    "experimental.session.compacting": async (_input, output) => {
+      output.context.push(activation().active ? activeGuidance : inactiveGuidance);
     },
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
@@ -25,6 +25,10 @@
     "test:delivery-path-search-unit": "node ./scripts/delivery-path-search-unit-test.js",
     "test:delivery-path-search-generator": "node ./scripts/delivery-path-search-generator-test.js",
     "test:cli-modularization": "node ./scripts/cli-modularization-test.js",
+    "test:local-validator": "node ./scripts/local-validator-test.js",
+    "test:local-marketplace": "node ./scripts/local-marketplace-test.js",
+    "test:package-contents": "node ./scripts/package-contents-test.js",
+    "test:package-build": "node ./scripts/package-build-test.js",
     "test:lifecycle": "node ./scripts/lifecycle-test.js",
     "test:control-state": "node ./scripts/control-state-test.js",
     "test:interaction-presentation": "node ./scripts/interaction-presentation-test.js",
@@ -36,7 +40,7 @@
     "eval:skills:record": "node ./scripts/record-skill-evals.js",
     "test:release-bootstrap": "node ./scripts/release-bootstrap-smoke-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run sync-package-assets && npm run test:cli-modularization && npm run test:lifecycle && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run sync-package-assets && npm run test:cli-modularization && npm run test:local-validator && npm run test:local-marketplace && npm run test:package-build && npm run test:package-contents && npm run test:lifecycle && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run sync-package-assets"
   },
   "keywords": [