create-agdf 0.10.0 → 0.10.1

package/README.md

@@ -25,7 +25,7 @@ Use a different target when Codex is not your agent surface:
 |---|---|---|
 | Claude Code | `npx --yes @agdf/cli@latest claude` | The AGDF plugin for Claude Code. |
 | OpenCode, user-wide discovery | `npx --yes @agdf/cli@latest opencode` | The npm plugin and global native skills; repository governance remains opt-in. |
-| OpenCode, one repository | `npx --yes @agdf/cli@latest opencode-repo` | Repository instructions, native skills, permissions and control templates. |
+| OpenCode, one repository | `npx --yes @agdf/cli@latest opencode-repo` | Durable control configuration that activates the once-installed global runtime. |
 | GitHub Copilot | `npx --yes @agdf/cli@latest copilot` | Repository instructions, visible skills and control templates. |
 | Durable control state in an existing setup | `npx --yes @agdf/cli@latest init` | Live `.agdf/control/` state when the repository explicitly needs it. |
 
@@ -115,11 +115,11 @@ it does not localize the CLI lifecycle card.
 - `claude` installs the AGDF plugin globally for Claude Code
 - `copilot` writes `AGENTS.md`, Copilot custom instructions under `.github/`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
 - `opencode` installs the AGDF npm plugin and nine native skills as a user-wide OpenCode surface
-- `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, session signals and repository surface presence
+- `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, durable repository activation, legacy compatibility and observable session signals
 - `status` reports installation, repository activation and delivery separately without mutating state
 - `disable` writes a supported repository-local opt-out while retaining global capability and durable control state
 - `uninstall` previews and, only with `--confirm`, applies a selected global removal through supported native/owned operations
-- `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit question/edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
+- `opencode-repo` writes durable AGDF control configuration and templates under `.agdf/control/`; it does not copy a second OpenCode runtime surface
 - `both` writes the Codex repository-local marketplace plus the Copilot-facing repository files
 - `config` writes or updates only `.agdf/control/config.json` for an already installed plugin or an existing repository
 
@@ -141,19 +141,19 @@ Then verify the visible installation state:
 npx --yes @agdf/cli@latest opencode-status --json
 ```
 
-The status command reports global configuration, package loadability, global native-skill completeness, session signals and whether the current repository has `.opencode/AGDF.md` plus the `agdf-gate-check` surface. It does not infer an active OpenCode session from config alone.
+The status command reports global configuration, package loadability, global native-skill completeness, durable repository activation, legacy local-surface compatibility and session signals. It does not infer an active OpenCode session from config alone.
 In JSON schema version 1, `repository_surface.gate_check_agent` remains a deprecated compatibility alias for the native `gate_check_skill` path so existing status consumers keep working during the agent-to-skill migration.
 
-Use the `opencode-repo` target when AGDF should be available to OpenCode from repository files:
+Use the `opencode-repo` target when a repository should opt into the globally installed AGDF OpenCode runtime:
 
 ```bash
 npm create agdf@latest -- opencode-repo
 ```
 
-OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `question`/`edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
-Those generated skills load on demand through OpenCode's native `skill` tool. Use `agdf-gate-check` first for new build/change intent or unclear approval.
-The built-in `question` tool can present a gate choice, but `.agdf/control/` and exact post-response validation remain authoritative; technical permission and auto-mode outcomes never approve an AGDF gate. If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment. Preserve any explicit `permission.question` decision when reviewing that fragment; `deny` uses exact-text fallback.
-The global layer makes the nine native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`. Use `opencode-repo` to write that repository surface.
+OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config. Global adapters use the collision-safe `agdf-global-` prefix, including `agdf-global-gate-check`. `opencode-repo` adds the durable `.agdf/control/config.json` marker and control templates; it does not write `opencode.json`, `.opencode/AGDF.md`, copied contracts or copied skills.
+The global skills load on demand through OpenCode's native `skill` tool. Use `agdf-global-gate-check` first for new build/change intent or unclear approval. Existing local `.opencode/` assets remain supported as a compatibility path and are not deleted.
+The built-in `question` tool can present a gate choice, but `.agdf/control/` and exact post-response validation remain authoritative; technical permission and auto-mode outcomes never approve an AGDF gate. Explicit `permission.question: deny` remains unchanged and uses exact-text fallback.
+The global layer makes the nine native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has valid `.agdf/control/config.json`. Use `opencode-repo` to create the durable activation marker.
 
 ## Control scaffold
 

package/generated/.opencode/README.md

@@ -2,16 +2,14 @@
 
 These files were generated from the AGDF source repository for OpenCode.
 
-- `opencode.json` loads the npm plugin `create-agdf` and `.opencode/AGDF.md` as repository instructions.
-- AGDF for OpenCode has a global npm/native-skill discoverability layer and this repository-local governance surface.
-- The global plugin and skills do not replace `.opencode/AGDF.md`, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- `opencode.json` allows the built-in `question` tool, keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills; global adapters use `agdf-global-*` to avoid same-name masking.
+- The globally installed npm plugin `create-agdf` owns the shared OpenCode runtime surface.
+- A repository is AGDF-active when `.agdf/control/config.json` is valid; this activation does not copy `.opencode/` assets.
+- Global adapters use `agdf-global-*` to avoid same-name masking by supported legacy local `agdf-*` skills.
 - Preserve an explicit user `permission.question: deny`; AGDF then uses exact textual approval and never interprets OpenCode permission outcomes or auto mode as gate authority.
-- `.opencode/skills/` contains native OpenCode skills generated from the canonical AGDF skills.
-- For new build/change intent or unclear approval, load `agdf-gate-check` through OpenCode's native `skill` tool.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, session activity and this repository surface.
+- For new build/change intent or unclear approval, load `agdf-global-gate-check` through OpenCode's native `skill` tool.
+- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, durable activation, legacy compatibility and session activity.
 - For deterministic ready-gate rendering, prefer an installed `agdf gate-check --approval-envelope`; reserve `agdf gate-check --json` for native-adapter input, automation or audit evidence and use `npx ...@latest` only for bootstrap, refresh or a missing local executable.
-- `.opencode/agdf-runtime-contract.md` is the shared gate and output contract.
+- The globally installed runtime contract is the shared gate and output contract.
 
 ## Skills
 

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Operating system for governed AI-assisted delivery.",

package/lib/cli/application.js

@@ -39,9 +39,9 @@ import {
 import { printGeneralStatus, printLifecycleResult } from "../lifecycle/presentation.js";
 import { createLifecycleResult, globalInstallRestartAction, lifecycleFailure } from "../lifecycle/result.js";
 import { evaluateGeneralStatus } from "../lifecycle/status.js";
-import { agdfFragmentPath, generatedFilesForTarget, openCodeConfigFragmentPath } from "../scaffold/plan.js";
+import { agdfFragmentPath, generatedFilesForTarget } from "../scaffold/plan.js";
 import { printNextSteps } from "../scaffold/presentation.js";
-import { assertGeneratedWritePlan, removeOwnedLegacyOpenCodeAgents, writeGeneratedFile } from "../scaffold/write.js";
+import { assertGeneratedWritePlan, writeGeneratedFile } from "../scaffold/write.js";
 import { renderUsage, resolveCommand, validateCommandOptions } from "./command-registry.js";
 import { executeDeliveryPathSearch } from "./delivery-path-search-command.js";
 import { CliUsageError, parseArgs } from "./parse-args.js";
@@ -308,7 +308,6 @@ function runUninstall(options, { io, env, exec }) {
 function runScaffold(options, io) {
   const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
   const wroteAgentsFragment = files.some((file) => file.path === agdfFragmentPath);
-  const wroteOpenCodeConfigFragment = files.some((file) => file.path === openCodeConfigFragmentPath);
   let removedOpenCodeAgents = [];
 
   try {
@@ -316,13 +315,14 @@ function runScaffold(options, io) {
     for (const file of files) {
       writeGeneratedFile(options.dir, file.path, file.content, options.force, file.allowOverwrite);
     }
-    if (options.target === "opencode-repo") removedOpenCodeAgents = removeOwnedLegacyOpenCodeAgents(options.dir);
+    // Legacy OpenCode assets are intentionally preserved. A future explicit migration command
+    // may remove only ownership-proven files after its precedence behavior is verified.
   } catch (error) {
     io.error(error.message);
     return 1;
   }
 
-  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
+  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
   return 0;
 }
 

package/lib/installers/opencode-activation.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pluginDefinition } from "../cli/runtime-context.js";
+
+const requiredConfigFields = ["artifact_language", "chat_language", "runtime_language"];
+
+export function isOpenCodeLegacySurfacePresent(targetDir) {
+  return existsSync(join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName))
+    && existsSync(join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md"));
+}
+
+export function evaluateOpenCodeRepositoryActivation(targetDir) {
+  const controlDir = join(targetDir, ".agdf", "control");
+  const configPath = join(controlDir, "config.json");
+  const legacySurface = isOpenCodeLegacySurfacePresent(targetDir);
+  const base = {
+    control_dir: controlDir,
+    config_path: configPath,
+    legacy_surface: legacySurface,
+  };
+
+  if (!existsSync(configPath)) {
+    return { ...base, state: "inactive", active: false, diagnostic: "missing_control_config" };
+  }
+
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    const valid = config
+      && typeof config === "object"
+      && !Array.isArray(config)
+      && requiredConfigFields.every((field) => typeof config[field] === "string" && config[field].trim());
+    if (!valid) return { ...base, state: "invalid_control", active: false, diagnostic: "invalid_control_config" };
+  } catch (error) {
+    return { ...base, state: "invalid_control", active: false, diagnostic: "invalid_control_json", error: error.message };
+  }
+
+  return {
+    ...base,
+    state: legacySurface ? "legacy_compatible" : "active",
+    active: true,
+    diagnostic: "valid_control_config",
+  };
+}

package/lib/installers/opencode.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import process from "node:process";
 import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
+import { evaluateOpenCodeRepositoryActivation } from "./opencode-activation.js";
 
 const contractModules = ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"];
 const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => pluginDefinition.opencode.skillPrefix + skill.slug);
@@ -169,9 +170,9 @@ function globalOpenCodeBoundary() {
     "## Global OpenCode Surface Boundary",
     "",
     "This skill is globally discoverable, but global plugin or skill presence is not repository governance activation.",
-    "Before applying AGDF gates, later artefacts or implementation guidance, inspect the current repository for `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`.",
-    "If the repository surface is absent, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo` in this repository.",
-    "When the repository surface exists, its local instructions, native skills and `.agdf/control/` state are authoritative.",
+    "Before applying AGDF gates, later artefacts or implementation guidance, inspect the current repository for valid `.agdf/control/config.json` durable control.",
+    "If durable control is missing or invalid, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo` in this repository.",
+    "When durable control is valid, use the global `agdf-global-*` skill surface; existing local OpenCode assets remain a compatibility path.",
     "",
   ].join("\n");
 }
@@ -198,7 +199,7 @@ export function installOpenCodeGlobalSurface(configDir) {
     "AGDF native skills are globally discoverable through OpenCode.",
     "",
     globalOpenCodeBoundary(),
-    "The repository-local `.opencode/AGDF.md`, `.opencode/skills/` and `.agdf/control/` files remain the source of truth for active governance.",
+    "Valid `.agdf/control/` is the repository source of truth for active governance; legacy `.opencode/` assets remain supported without being required.",
     "",
     toGlobalOpenCodeContent(generatedInstructions),
   ].join("\n");
@@ -243,11 +244,6 @@ function readOpenCodeConfig(configPath) {
   }
 }
 
-function isOpenCodeRepositorySurfacePresent(targetDir) {
-  return existsSync(join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName))
-    && existsSync(join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md"));
-}
-
 function resolveOpenCodePackage(configDir) {
   const packageName = pluginDefinition.opencode.npmPackage;
   try {
@@ -343,8 +339,9 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
     version: process.env.AGDF_PLUGIN_VERSION || "",
     control_dir: process.env.AGDF_CONTROL_DIR || "",
     repository_surface: process.env.AGDF_OPENCODE_REPOSITORY_SURFACE === "1",
+    repository_activation: process.env.AGDF_OPENCODE_REPOSITORY_ACTIVATION || "",
   };
-  const repositorySurface = isOpenCodeRepositorySurfacePresent(targetDir);
+  const repositoryActivation = evaluateOpenCodeRepositoryActivation(targetDir);
   const gateCheckSkillPath = join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md");
 
   const findings = [];
@@ -360,7 +357,11 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
     );
   }
   if (!sessionSignals.active) findings.push("No active AGDF OpenCode session signal is visible in this process.");
-  if (!repositorySurface) findings.push("Current repository does not contain the AGDF OpenCode surface.");
+  if (!repositoryActivation.active) {
+    findings.push(repositoryActivation.state === "invalid_control"
+      ? "Current repository has invalid AGDF durable control configuration."
+      : "Current repository does not contain valid AGDF durable control configuration.");
+  }
 
   return {
     schema_version: "1",
@@ -383,21 +384,30 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
     },
     global_native_surface: globalNativeSurface,
     session: sessionSignals,
+    repository_activation: repositoryActivation.state,
+    repository_control: {
+      path: repositoryActivation.config_path,
+      diagnostic: repositoryActivation.diagnostic,
+      ...(repositoryActivation.error ? { error: repositoryActivation.error } : {}),
+    },
     repository_surface: {
       path: targetDir,
-      present: repositorySurface,
+      present: repositoryActivation.active,
+      legacy_present: repositoryActivation.legacy_surface,
       instructions: join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName),
       gate_check_agent: gateCheckSkillPath,
       gate_check_skill: gateCheckSkillPath,
     },
-    visible_entrypoint: repositorySurface ? `${pluginDefinition.opencode.skillPrefix}gate-check (native skill)` : "none until opencode-repo is installed for this repository",
+    visible_entrypoint: repositoryActivation.active ? `${pluginDefinition.opencode.globalSkillPrefix}gate-check (native skill)` : "none until durable AGDF control is configured for this repository",
     findings,
     next_step: packageVersionStatus !== "current"
       ? "Run npx --yes @agdf/cli@latest opencode to install or repair the OpenCode package version."
       : !globalNativeSurface.complete
       ? "Run npx --yes @agdf/cli@latest opencode to install or repair the global native OpenCode skill surface."
-      : repositorySurface
-      ? `Restart OpenCode if needed, then load ${pluginDefinition.opencode.skillPrefix}gate-check through the native skill tool for new build/change intent.`
+      : repositoryActivation.state === "invalid_control"
+      ? "Repair .agdf/control/config.json so it contains valid artifact_language, chat_language and runtime_language values."
+      : repositoryActivation.active
+      ? `Restart OpenCode if needed, then load ${pluginDefinition.opencode.globalSkillPrefix}gate-check through the native skill tool for new build/change intent.`
       : "Run npx --yes @agdf/cli@latest opencode-repo in repositories where AGDF governance should be active and reviewable.",
   };
 }
@@ -431,7 +441,9 @@ export function printOpenCodeStatus(report, json, io = console) {
   io.log(`Session active signal: ${report.session.active ? "yes" : "no"}`);
   if (report.session.version) io.log(`Session plugin version: ${report.session.version}`);
   if (report.session.control_dir) io.log(`Session control dir: ${report.session.control_dir}`);
-  io.log(`Repository surface: ${report.repository_surface.present ? "present" : "missing"}`);
+  io.log(`Repository activation: ${report.repository_activation}`);
+  io.log(`Repository control: ${report.repository_control.path} (${report.repository_control.diagnostic})`);
+  io.log(`Legacy repository surface: ${report.repository_surface.legacy_present ? "present" : "absent"}`);
   io.log(`Visible entrypoint: ${report.visible_entrypoint}`);
   io.log(`Next step: ${report.next_step}`);
 

package/lib/scaffold/plan.js

@@ -3,10 +3,8 @@ import { join } from "node:path";
 import { generatedRoot, languageConfigContent, pluginDefinition } from "../cli/runtime-context.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",
@@ -111,13 +109,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 +243,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 +253,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",
@@ -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 `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");
+
+  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.1",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [