create-agdf 0.6.8 → 0.7.0

package/README.md

@@ -51,8 +51,8 @@ If no language is provided, `create-agdf` derives the preference from the local
 - `codex-repo` writes a repository-local Codex marketplace under `.agents/plugins/` and a local AGDF plugin copy under `plugins/agdf/`
 - `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 as a user-wide OpenCode hook
-- `opencode-status` reports OpenCode global config, package loadability, session signals and repository surface presence
+- `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-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
 - `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
@@ -75,7 +75,7 @@ Then verify the visible installation state:
 npx --yes @agdf/cli@latest opencode-status --json
 ```
 
-The status command reports global configuration, whether `create-agdf` is loadable from the OpenCode config directory, whether the current process exposes AGDF 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, 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.
 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:
@@ -84,10 +84,10 @@ Use the `opencode-repo` target when AGDF should be available to OpenCode from re
 npm create agdf@latest -- opencode-repo
 ```
 
-OpenCode loads the AGDF npm plugin from global OpenCode config or repository `opencode.json`, AGENTS-style rules from `.opencode/AGDF.md`, explicit `edit`/`bash`/`skill` permissions and the `agdf-` prefixed native skills under `.opencode/skills/`. AGDF for OpenCode has two layers: a global npm plugin hook installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by the `opencode-repo` target.
+OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `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.
 If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment.
-Using OpenCode's plugin installer or global config for `create-agdf` can add the npm plugin hook, but AGDF still needs the repository instructions and native skills. The `opencode-repo` target writes the repository files together.
+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.
 
 ## Control scaffold
 

package/bin/create-agdf.js

@@ -32,14 +32,23 @@ const generatedRoot = join(packageRoot, "generated");
 const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
 const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
 const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
-const npmCommand = process.platform === "win32" ? process.execPath : "npm";
-const npmPrefixArgs = process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
+const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_NPM_CLI_PATH || "" : "";
+const npmCommand = testNpmCliPath
+  ? process.execPath
+  : process.platform === "win32"
+    ? process.execPath
+    : "npm";
+const npmPrefixArgs = testNpmCliPath
+  ? [testNpmCliPath]
+  : process.platform === "win32"
+    ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")]
+    : [];
 const allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-status", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map", "delivery-path-search", "run-create", "run-migrate", "run-render-legacy"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 const openCodeConfigFragmentPath = "opencode.agdf.json";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
-const internalStepArtefacts = new Set(["Brownfield Review"]);
+const internalStepArtefacts = new Set(["Brownfield Review", "Brownfield Analysis", "CD+Tests", "CR"]);
 const deliveryRelationships = [
   { from: "UR", relationship: "approved_by", to: "Approval: UR", requiredBy: "UR" },
   { from: "PRD", relationship: "derived_from", to: "UR", requiredBy: "PRD" },
@@ -62,24 +71,13 @@ const nextSkillByGate = {
   UAT: "delivery-closeout",
   OR: "release-or",
 };
-const gateProgressOrder = [
-  "UR",
-  "Brownfield Review",
-  "Mode/Slice Decision",
-  "Quick Task Execution",
-  "PRD",
-  "SD",
-  "TP",
-  "Brownfield Analysis",
-  "CD+Tests",
-  "CR",
-  "QA",
-  "UAT",
-  "OR",
-];
 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 globalOpenCodeSkillOwnershipMarker = "<!-- AGDF-GLOBAL-SKILL: ";
+const globalOpenCodeInstructionsOwnershipMarker = "<!-- AGDF-GLOBAL-INSTRUCTIONS -->";
+const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->";
 const codexPluginFiles = [
   join(".agents", "plugins", "marketplace.json"),
   join("plugins", "agdf", ".codex-plugin", "plugin.json"),
@@ -476,6 +474,8 @@ function defaultOpenCodeConfigDir() {
 }
 
 function installOpenCodeGlobalPlugin(configDir) {
+  assertGlobalOpenCodeSurfaceWritable(configDir);
+  const previousPackage = resolveOpenCodePackage(configDir);
   const configPath = join(configDir, "opencode.json");
   let config = {};
 
@@ -503,17 +503,145 @@ function installOpenCodeGlobalPlugin(configDir) {
     plugin: plugins,
   };
 
+  if (nextConfig.instructions !== undefined && !Array.isArray(nextConfig.instructions)) {
+    throw new Error(`Refusing to update OpenCode config with non-array instructions field: ${configPath}`);
+  }
+  nextConfig.instructions = [...(nextConfig.instructions ?? [])];
+  if (!nextConfig.instructions.includes("AGDF.md")) nextConfig.instructions.push("AGDF.md");
+
+  if (nextConfig.permission === undefined) {
+    nextConfig.permission = { skill: { "agdf-*": "allow" } };
+  } else if (nextConfig.permission && typeof nextConfig.permission === "object" && !Array.isArray(nextConfig.permission)) {
+    nextConfig.permission = { ...nextConfig.permission };
+    if (nextConfig.permission.skill === undefined) {
+      nextConfig.permission.skill = { "agdf-*": "allow" };
+    } else if (nextConfig.permission.skill && typeof nextConfig.permission.skill === "object" && !Array.isArray(nextConfig.permission.skill)) {
+      nextConfig.permission.skill = { ...nextConfig.permission.skill };
+      if (nextConfig.permission.skill["agdf-*"] === undefined) nextConfig.permission.skill["agdf-*"] = "allow";
+    }
+  }
+
   mkdirSync(configDir, { recursive: true });
   try {
-    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--prefix", configDir, packageRoot], { stdio: "pipe" });
+    const packageSpecifier = `${pluginDefinition.opencode.npmPackage}@${pluginDefinition.version}`;
+    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--save-exact", packageSpecifier], {
+      cwd: configDir,
+      stdio: "pipe",
+    });
   } catch (error) {
     throw new Error(`Failed to install ${pluginDefinition.opencode.npmPackage} into the OpenCode config directory: ${(error.stderr || error.message).toString().trim()}`);
   }
   writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+  const installedPackage = resolveOpenCodePackage(configDir);
 
   return {
     configPath,
     added: !alreadyInstalled,
+    transition: openCodePackageTransition(previousPackage, installedPackage),
+  };
+}
+
+function globalOpenCodeConfigPaths(configDir) {
+  return {
+    instructions: join(configDir, pluginDefinition.opencode.instructionsFileName),
+    runtimeContract: join(configDir, pluginDefinition.opencode.runtimeContractFileName),
+    skills: join(configDir, "skills"),
+  };
+}
+
+function globalOpenCodeOwnershipMarkerIsValid(content, marker, placement) {
+  const lines = content.split(/\r?\n/);
+  if (placement === "first-line") return lines[0] === marker;
+  const frontmatterEnd = lines.findIndex((line, index) => index > 0 && line === "---");
+  return frontmatterEnd >= 0 && lines[frontmatterEnd + 1] === marker;
+}
+
+function assertGlobalOpenCodeFileWritable(path, marker, placement) {
+  if (!existsSync(path)) return;
+  const existing = readFileSync(path, "utf8");
+  if (!globalOpenCodeOwnershipMarkerIsValid(existing, marker, placement)) {
+    throw new Error(`Refusing to overwrite unowned global OpenCode file: ${path}`);
+  }
+}
+
+function assertGlobalOpenCodeSurfaceWritable(configDir) {
+  const paths = globalOpenCodeConfigPaths(configDir);
+  assertGlobalOpenCodeFileWritable(paths.instructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
+  assertGlobalOpenCodeFileWritable(paths.runtimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+  for (const skillName of globalOpenCodeSkillNames) {
+    assertGlobalOpenCodeFileWritable(
+      join(paths.skills, skillName, "SKILL.md"),
+      `${globalOpenCodeSkillOwnershipMarker}${skillName} -->`,
+      "after-frontmatter",
+    );
+  }
+}
+
+function writeOwnedGlobalOpenCodeFile(path, content, marker, placement) {
+  if (existsSync(path)) {
+    assertGlobalOpenCodeFileWritable(path, marker, placement);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}
+
+function globalOpenCodeBoundary() {
+  return [
+    "## 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.",
+    "",
+  ].join("\n");
+}
+
+function toGlobalOpenCodeContent(content) {
+  let next = content;
+  for (const skill of pluginDefinition.skillSet) {
+    const localName = `${pluginDefinition.opencode.skillPrefix}${skill.slug}`;
+    const globalName = `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`;
+    next = next.replaceAll(localName, globalName);
+  }
+  return next;
+}
+
+function installOpenCodeGlobalSurface(configDir) {
+  const paths = globalOpenCodeConfigPaths(configDir);
+  const generatedOpenCodeRoot = join(generatedRoot, ".opencode");
+  const generatedInstructions = readFileSync(join(generatedOpenCodeRoot, pluginDefinition.opencode.instructionsFileName), "utf8");
+  const generatedRuntimeContract = readFileSync(join(generatedOpenCodeRoot, pluginDefinition.opencode.runtimeContractFileName), "utf8");
+  const globalInstructions = [
+    globalOpenCodeInstructionsOwnershipMarker,
+    "# AGDF Global OpenCode instructions",
+    "",
+    "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.",
+    "",
+    toGlobalOpenCodeContent(generatedInstructions),
+  ].join("\n");
+  const globalRuntimeContract = `${globalOpenCodeRuntimeContractOwnershipMarker}\n${generatedRuntimeContract}`;
+
+  writeOwnedGlobalOpenCodeFile(paths.instructions, globalInstructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
+  writeOwnedGlobalOpenCodeFile(paths.runtimeContract, globalRuntimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+
+  for (let index = 0; index < openCodeSkillNames.length; index += 1) {
+    const sourceName = openCodeSkillNames[index];
+    const skillName = globalOpenCodeSkillNames[index];
+    const sourcePath = join(generatedOpenCodeRoot, "skills", sourceName, "SKILL.md");
+    const sourceContent = readFileSync(sourcePath, "utf8");
+    const marker = `${globalOpenCodeSkillOwnershipMarker}${skillName} -->`;
+    const content = toGlobalOpenCodeContent(sourceContent).replace(/^(---[\s\S]*?\n---\n)/, `$1${marker}\n\n${globalOpenCodeBoundary()}`);
+    writeOwnedGlobalOpenCodeFile(join(paths.skills, skillName, "SKILL.md"), content, marker, "after-frontmatter");
+  }
+
+  return {
+    instructions: paths.instructions,
+    runtimeContract: paths.runtimeContract,
+    skills: paths.skills,
   };
 }
 
@@ -534,30 +662,86 @@ function isOpenCodeRepositorySurfacePresent(targetDir) {
 function resolveOpenCodePackage(configDir) {
   const packageName = pluginDefinition.opencode.npmPackage;
   try {
+    const resolvedPath = execFileSync(process.execPath, ["-e", `process.stdout.write(require.resolve(${JSON.stringify(packageName)}))`], {
+      cwd: configDir,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    let installedVersion = "";
+    try {
+      const packageManifest = JSON.parse(readFileSync(join(dirname(resolvedPath), "package.json"), "utf8"));
+      installedVersion = typeof packageManifest.version === "string" && packageManifest.version.trim() ? packageManifest.version.trim() : "";
+    } catch {
+      installedVersion = "";
+    }
     return {
       loadable: true,
-      path: execFileSync(process.execPath, ["-e", `process.stdout.write(require.resolve(${JSON.stringify(packageName)}))`], {
-        cwd: configDir,
-        encoding: "utf8",
-        stdio: "pipe",
-      }),
+      path: resolvedPath,
+      installed_version: installedVersion,
       error: "",
     };
   } catch (error) {
     return {
       loadable: false,
       path: "",
+      installed_version: "",
       error: (error.stderr || error.message || "package not resolvable").toString().trim(),
     };
   }
 }
 
-function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir()) {
+function openCodePackageVersionStatus(packageState) {
+  if (!packageState.loadable) return "unloadable";
+  if (!packageState.installed_version) return "unknown";
+  return packageState.installed_version === pluginDefinition.version ? "current" : "outdated";
+}
+
+function openCodePackageTransition(previousPackage, installedPackage) {
+  const previousVersion = previousPackage.loadable ? previousPackage.installed_version : "";
+  const installedVersion = installedPackage.loadable ? installedPackage.installed_version : "";
+  if (!installedVersion || (previousPackage.loadable && !previousVersion)) {
+    return {
+      previous_version: previousVersion,
+      installed_version: installedVersion,
+      status: "unknown",
+    };
+  }
+  if (!previousPackage.loadable) {
+    return {
+      previous_version: "",
+      installed_version: installedVersion,
+      status: "installed",
+    };
+  }
+  return {
+    previous_version: previousVersion,
+    installed_version: installedVersion,
+    status: previousVersion === installedVersion ? "unchanged" : "updated",
+  };
+}
+
+function evaluateGlobalOpenCodeSurface(configDir) {
+  const paths = globalOpenCodeConfigPaths(configDir);
+  const skillCount = globalOpenCodeSkillNames.filter((skillName) => existsSync(join(paths.skills, skillName, "SKILL.md"))).length;
+  return {
+    path: paths.skills,
+    instructions: paths.instructions,
+    runtime_contract: paths.runtimeContract,
+    expected_skill_count: globalOpenCodeSkillNames.length,
+    skill_count: skillCount,
+    present: existsSync(paths.skills),
+    complete: existsSync(paths.instructions) && existsSync(paths.runtimeContract) && skillCount === openCodeSkillNames.length,
+  };
+}
+
+function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(), transition = null) {
   const configPath = join(configDir, "opencode.json");
   const configState = readOpenCodeConfig(configPath);
   const plugins = Array.isArray(configState.config.plugin) ? configState.config.plugin : [];
   const globalConfigured = plugins.includes(pluginDefinition.opencode.npmPackage);
   const packageState = resolveOpenCodePackage(configDir);
+  const packageVersionStatus = openCodePackageVersionStatus(packageState);
+  const globalNativeSurface = evaluateGlobalOpenCodeSurface(configDir);
   const sessionSignals = {
     active: process.env.AGDF_PLUGIN_ACTIVE === "1",
     version: process.env.AGDF_PLUGIN_VERSION || "",
@@ -572,6 +756,9 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
   if (configState.parseError) findings.push(`OpenCode global config is not valid JSON: ${configState.parseError}`);
   if (!globalConfigured) findings.push(`OpenCode global config does not include ${pluginDefinition.opencode.npmPackage}.`);
   if (!packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is not loadable from the OpenCode config directory.`);
+  if (packageVersionStatus === "outdated") findings.push(`${pluginDefinition.opencode.npmPackage} version ${packageState.installed_version} is outdated; expected ${pluginDefinition.version}.`);
+  if (packageVersionStatus === "unknown" && packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is loadable but its installed version is unknown.`);
+  if (!globalNativeSurface.complete) findings.push(`Global OpenCode native skill surface is incomplete (${globalNativeSurface.skill_count}/${globalNativeSurface.expected_skill_count} skills).`);
   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.");
 
@@ -588,8 +775,13 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
       name: pluginDefinition.opencode.npmPackage,
       loadable: packageState.loadable,
       resolved_path: packageState.path,
+      installed_version: packageState.installed_version || null,
+      expected_version: pluginDefinition.version,
+      version_status: packageVersionStatus,
+      ...(transition ? { transition } : {}),
       error: packageState.error,
     },
+    global_native_surface: globalNativeSurface,
     session: sessionSignals,
     repository_surface: {
       path: targetDir,
@@ -600,7 +792,11 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
     },
     visible_entrypoint: repositorySurface ? `${pluginDefinition.opencode.skillPrefix}gate-check (native skill)` : "none until opencode-repo is installed for this repository",
     findings,
-    next_step: repositorySurface
+    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.`
       : "Run npx --yes @agdf/cli@latest opencode-repo in repositories where AGDF governance should be active and reviewable.",
   };
@@ -618,6 +814,20 @@ function printOpenCodeStatus(report, json) {
   if (report.global_config.parse_error) console.log(`Config parse error: ${report.global_config.parse_error}`);
   console.log(`Package loadable: ${report.package.loadable ? "yes" : "no"}`);
   if (report.package.resolved_path) console.log(`Package path: ${report.package.resolved_path}`);
+  console.log(`Package version: ${report.package.installed_version || "unknown"}`);
+  console.log(`Expected version: ${report.package.expected_version}`);
+  console.log(`Version status: ${report.package.version_status}`);
+  if (report.package.transition?.status === "updated") {
+    console.log(`Version transition: ${report.package.transition.previous_version} -> ${report.package.transition.installed_version}`);
+  } else if (report.package.transition?.status === "installed") {
+    console.log(`Version transition: new install (${report.package.transition.installed_version || "unknown"})`);
+  } else if (report.package.transition?.status === "unchanged") {
+    console.log(`Version transition: unchanged (${report.package.transition.installed_version})`);
+  } else if (report.package.transition?.status === "unknown") {
+    console.log("Version transition: unknown");
+  }
+  console.log(`Global native skills: ${report.global_native_surface.complete ? "complete" : "incomplete"} (${report.global_native_surface.skill_count}/${report.global_native_surface.expected_skill_count})`);
+  console.log(`Global skill path: ${report.global_native_surface.path}`);
   console.log(`Session active signal: ${report.session.active ? "yes" : "no"}`);
   if (report.session.version) console.log(`Session plugin version: ${report.session.version}`);
   if (report.session.control_dir) console.log(`Session control dir: ${report.session.control_dir}`);
@@ -1605,20 +1815,6 @@ function readRunState(targetDir, selection = {}) {
   };
 }
 
-function firstUnapprovedGate(approvals) {
-  for (const gate of userGateOrder) {
-    const status = approvals.get(gate)?.status ?? "";
-    if (status !== "approved" && status !== "not_applicable") return gate;
-  }
-  return "OR";
-}
-
-function normalizeCurrentGate(value, fallbackGate) {
-  if (isPlaceholderValue(value)) return fallbackGate;
-  const normalized = value.replace(/`/g, "").trim();
-  return normalized || fallbackGate;
-}
-
 function gateApprovalStatus(runState, gate) {
   if (!userGateOrder.includes(gate)) return "not_applicable";
   return runState.approvals.get(gate)?.status ?? "";
@@ -1672,7 +1868,9 @@ function analyzeDurableGateArtefactConsistency(runState) {
 function isInternalStepSatisfied(runState, step) {
   const artefact = runState.artefacts.get(step);
   if (!artefact) return false;
-  return artefact.status === "done" || artefact.status === "not_applicable";
+  if (artefact.status === "done") return true;
+  return artefact.status === "not_applicable"
+    && (step === "Brownfield Review" || step === "Brownfield Analysis");
 }
 
 function modeSliceDecision(runState) {
@@ -1891,15 +2089,6 @@ function buildStatusCard({
   };
 }
 
-function effectiveCurrentGate(runState, transitionDecision) {
-  if (transitionDecision.status !== "open") return transitionDecision.current_gate;
-  const explicitGate = normalizeCurrentGate(runState.current_gate, "");
-  const explicitIndex = gateProgressOrder.indexOf(explicitGate);
-  const fallbackIndex = gateProgressOrder.indexOf(transitionDecision.current_gate);
-  if (explicitIndex === -1 || fallbackIndex === -1) return transitionDecision.current_gate;
-  return explicitIndex > fallbackIndex ? explicitGate : transitionDecision.current_gate;
-}
-
 function durableArtefactBlock(gate, nextGate) {
   const label = gate === "QA" ? "QA report" : `${gate} artefact`;
   const stablePath = gate === "QA" ? ".agdf/control/artefacts/<key>/QA_REPORT.md" : `.agdf/control/artefacts/<key>/${gate}.md`;
@@ -2044,6 +2233,43 @@ function transitionDecisionForRunState(runState) {
     };
   }
 
+  const implementationStepsRequired = gateApprovalStatus(runState, "TP") === "approved";
+  if (implementationStepsRequired && !isInternalStepSatisfied(runState, "Brownfield Analysis")) {
+    return {
+      status: "open",
+      current_gate: "Brownfield Analysis",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["run Brownfield Analysis for the approved TP scope", "verify existing owners, reuse paths and regression risks"],
+      forbidden: ["implement before Brownfield evidence supports the approved TP path", "claim QA or release readiness"],
+      next_allowed_action: "Run Brownfield Analysis for the approved TP scope before CD+Tests.",
+    };
+  }
+
+  if (implementationStepsRequired && !isInternalStepSatisfied(runState, "CD+Tests")) {
+    return {
+      status: "open",
+      current_gate: "CD+Tests",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["implement the approved TP tasks", "run the approved test plan", "record implementation and test evidence"],
+      forbidden: ["claim QA pass", "request UAT approval", "release"],
+      next_allowed_action: "Implement the approved TP scope, run its tests, and record CD+Tests evidence before CR.",
+    };
+  }
+
+  if (implementationStepsRequired && !isInternalStepSatisfied(runState, "CR")) {
+    return {
+      status: "open",
+      current_gate: "CR",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["run mandatory code review", "record correctness, regression, security and maintainability findings", "fix blocking review findings"],
+      forbidden: ["claim QA pass", "request UAT approval", "release"],
+      next_allowed_action: "Run Code Review for the implemented TP scope and resolve blocking findings before QA.",
+    };
+  }
+
   if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
 
   if (isGateSatisfied(runState, "QA") && !isGateSatisfied(runState, "UAT")) {
@@ -2072,12 +2298,12 @@ function transitionDecisionForRunState(runState) {
 
   return {
     status: "open",
-    current_gate: "Brownfield Analysis",
+    current_gate: "QA",
     blocking_reason: "none",
-    missing_approval: "none",
-    allowed: ["run Brownfield Analysis for the approved TP scope", "verify existing owners, reuse paths and regression risks"],
-    forbidden: ["implement before Brownfield evidence supports the approved TP path", "claim QA or release readiness"],
-    next_allowed_action: "Run Brownfield Analysis for the approved TP scope before CD+Tests.",
+    missing_approval: "Approval: QA",
+    allowed: ["run QA gate", "persist or refine the QA report", "request exact QA approval"],
+    forbidden: ["request UAT approval", "release", "claim delivery readiness before QA approval and report evidence"],
+    next_allowed_action: "Run the QA gate, persist the QA report, and request exact approval: Approval: QA",
   };
 }
 
@@ -2090,7 +2316,7 @@ function evaluateGateCheck(targetDir, selection = {}) {
   const doctorRevise = doctorReport.findings.find((finding) => finding.severity === "revise");
 
   let status = transitionDecision.status;
-  let currentGate = effectiveCurrentGate(runState, transitionDecision);
+  let currentGate = transitionDecision.current_gate;
   let blockingReason = transitionDecision.blocking_reason;
   let missingApproval = transitionDecision.missing_approval;
   let allowed = transitionDecision.allowed;
@@ -2265,7 +2491,7 @@ function evaluateDeliveryMap(targetDir, selection = {}) {
   const runState = readRunState(targetDir, selection);
   const map = analyzeDeliveryMap(runState);
   const gateDecision = transitionDecisionForRunState(runState);
-  const currentGate = effectiveCurrentGate(runState, gateDecision);
+  const currentGate = gateDecision.current_gate;
 
   const severityRank = { block: 3, revise: 2, warn: 1 };
   const deliverySeverity = map.findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
@@ -2497,8 +2723,9 @@ async function main() {
     const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
     try {
       const result = installOpenCodeGlobalPlugin(configDir);
+      installOpenCodeGlobalSurface(configDir);
       console.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
-      const report = evaluateOpenCodeStatus(options.dir, configDir);
+      const report = evaluateOpenCodeStatus(options.dir, configDir, result.transition);
       printOpenCodeStatus(report, false);
       console.log("Restart OpenCode so it loads the updated global plugin config.");
     } catch (error) {

package/generated/.agdf/control/templates/RUN_STATE.md

@@ -37,6 +37,27 @@ Describe the trustworthy outcome.
 | QA | missing |  |
 | UAT | missing |  |
 
+## Artefacts
+
+| Type | Path | Status | Notes |
+|---|---|---|---|
+| UR |  | draft |  |
+| Brownfield Review |  | missing |  |
+| PRD |  | missing |  |
+| SD |  | missing |  |
+| TP |  | missing |  |
+| Brownfield Analysis |  | missing |  |
+| CD+Tests |  | missing |  |
+| CR |  | missing |  |
+| QA |  | missing |  |
+
+## Mode/Slice Decision
+
+- decision:
+- required_next_gate:
+- scope_reason:
+- evidence:
+
 ## Evidence
 
 | Evidence | Source | Covers | Strength |

package/generated/.github/skills/agdf-runtime-contract.md

@@ -233,6 +233,7 @@ section or any other existing line.
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
 - Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Brownfield Analysis -> CD+Tests -> CR -> OR`
+- On the approved-TP path, `CD+Tests` and `CR` are satisfied only by `done`; `not_applicable` may satisfy Brownfield Review or Brownfield Analysis, but it must not bypass implementation/test evidence or mandatory Code Review.
 - Exact approval formula: `Approval: <GateName>`
 - Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
 - Implicit consent is not approval. Phrases such as "ok", "go ahead", "do it", "approved", "continue", "leg los" or "looks good" are work intent, not gate approval.
@@ -293,7 +294,11 @@ This table is the canonical transition model. Skills may reference it, but must
 | `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
 | `TP` approved and TP artefact persisted or linked, Brownfield Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
 | Brownfield Analysis passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
+| `CD+Tests` done for approved TP, CR missing | `CR` | run mandatory Code Review and resolve blocking findings | QA pass, UAT, release | none |
+| `CR` done, QA not approved | `QA` | run QA gate, persist/refine QA report, request `Approval: QA` | UAT, release | `Approval: QA` |
 | `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+| QA approved and QA report is `pass` or `passed`, UAT not approved | `UAT` | request `Approval: UAT`, prepare non-operative delivery summary | release and automatic VCS actions | `Approval: UAT` |
+| UAT approved | `OR` | produce OR or delivery closeout; prepare VCS handoff only when requested | automatic commit, push, PR or release | none |
 
 ## Brownfield Modes
 

package/generated/.opencode/AGDF.md

@@ -101,13 +101,13 @@ For relevant runs that change durable state, code, artefacts or gate status:
 ## OpenCode Files
 
 - OpenCode loads this file through `opencode.json` `instructions`.
-- AGDF for OpenCode has two layers: an optional global npm plugin hook and this repository-local governance surface.
-- The global plugin hook does not replace this file, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
+- 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 this file, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
 - Native OpenCode skills live under `.opencode/skills/` and use the `agdf-` prefix.
 - The generated AGDF skills are loaded on demand through OpenCode's native `skill` tool; they are not parallel subagents or primary menu agents.
 - For new build/change intent or unclear approval, load the `agdf-gate-check` skill before later artefacts or implementation.
 - The AGDF OpenCode plugin is loaded from npm through `opencode.json` `plugin: ["create-agdf"]`.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to verify global config, package loadability, active session signals and repository surface presence separately.
-- OpenCode permissions keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly.
+- Use `npx --yes @agdf/cli@latest opencode-status --json` to verify global config, package loadability, global native-skill completeness, active session signals and repository surface presence separately.
+- OpenCode permissions keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly; global adapters use the `agdf-global-*` namespace.
 - Shared output and gate rules live in `.opencode/agdf-runtime-contract.md`.
 - Do not paste full control files, templates or artefact bodies into chat unless the user explicitly asks for the full content; summarize and link paths instead.

package/generated/.opencode/README.md

@@ -3,12 +3,12 @@
 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 two layers: an optional global npm plugin hook and this repository-local governance surface.
-- The global plugin hook does not replace `.opencode/AGDF.md`, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- `opencode.json` keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills.
+- 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` keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills; global adapters use `agdf-global-*` to avoid same-name masking.
 - `.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 configuration, package loadability, session activity and this repository surface.
+- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, session activity and this repository surface.
 - Use `npx --yes @agdf/cli@latest gate-check --status-card` for compact interactive gate state; reserve full `--json` output for automation or audit evidence.
 - `.opencode/agdf-runtime-contract.md` is the shared gate and output contract.
 

package/generated/.opencode/agdf-runtime-contract.md

@@ -233,6 +233,7 @@ section or any other existing line.
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
 - Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Brownfield Analysis -> CD+Tests -> CR -> OR`
+- On the approved-TP path, `CD+Tests` and `CR` are satisfied only by `done`; `not_applicable` may satisfy Brownfield Review or Brownfield Analysis, but it must not bypass implementation/test evidence or mandatory Code Review.
 - Exact approval formula: `Approval: <GateName>`
 - Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
 - Implicit consent is not approval. Phrases such as "ok", "go ahead", "do it", "approved", "continue", "leg los" or "looks good" are work intent, not gate approval.
@@ -293,7 +294,11 @@ This table is the canonical transition model. Skills may reference it, but must
 | `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
 | `TP` approved and TP artefact persisted or linked, Brownfield Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
 | Brownfield Analysis passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
+| `CD+Tests` done for approved TP, CR missing | `CR` | run mandatory Code Review and resolve blocking findings | QA pass, UAT, release | none |
+| `CR` done, QA not approved | `QA` | run QA gate, persist/refine QA report, request `Approval: QA` | UAT, release | `Approval: QA` |
 | `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+| QA approved and QA report is `pass` or `passed`, UAT not approved | `UAT` | request `Approval: UAT`, prepare non-operative delivery summary | release and automatic VCS actions | `Approval: UAT` |
+| UAT approved | `OR` | produce OR or delivery closeout; prepare VCS handoff only when requested | automatic commit, push, PR or release | none |
 
 ## Brownfield Modes
 

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

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/control/templates/RUN_STATE.md

@@ -37,6 +37,27 @@ Describe the trustworthy outcome.
 | QA | missing |  |
 | UAT | missing |  |
 
+## Artefacts
+
+| Type | Path | Status | Notes |
+|---|---|---|---|
+| UR |  | draft |  |
+| Brownfield Review |  | missing |  |
+| PRD |  | missing |  |
+| SD |  | missing |  |
+| TP |  | missing |  |
+| Brownfield Analysis |  | missing |  |
+| CD+Tests |  | missing |  |
+| CR |  | missing |  |
+| QA |  | missing |  |
+
+## Mode/Slice Decision
+
+- decision:
+- required_next_gate:
+- scope_reason:
+- evidence:
+
 ## Evidence
 
 | Evidence | Source | Covers | Strength |

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -52,6 +52,7 @@
   },
   "opencode": {
     "skillPrefix": "agdf-",
+    "globalSkillPrefix": "agdf-global-",
     "runtimeContractFileName": "agdf-runtime-contract.md",
     "instructionsFileName": "AGDF.md",
     "npmPackage": "create-agdf",

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -233,6 +233,7 @@ section or any other existing line.
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
 - Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Brownfield Analysis -> CD+Tests -> CR -> OR`
+- On the approved-TP path, `CD+Tests` and `CR` are satisfied only by `done`; `not_applicable` may satisfy Brownfield Review or Brownfield Analysis, but it must not bypass implementation/test evidence or mandatory Code Review.
 - Exact approval formula: `Approval: <GateName>`
 - Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
 - Implicit consent is not approval. Phrases such as "ok", "go ahead", "do it", "approved", "continue", "leg los" or "looks good" are work intent, not gate approval.
@@ -293,7 +294,11 @@ This table is the canonical transition model. Skills may reference it, but must
 | `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
 | `TP` approved and TP artefact persisted or linked, Brownfield Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
 | Brownfield Analysis passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
+| `CD+Tests` done for approved TP, CR missing | `CR` | run mandatory Code Review and resolve blocking findings | QA pass, UAT, release | none |
+| `CR` done, QA not approved | `QA` | run QA gate, persist/refine QA report, request `Approval: QA` | UAT, release | `Approval: QA` |
 | `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+| QA approved and QA report is `pass` or `passed`, UAT not approved | `UAT` | request `Approval: UAT`, prepare non-operative delivery summary | release and automatic VCS actions | `Approval: UAT` |
+| UAT approved | `OR` | produce OR or delivery closeout; prepare VCS handoff only when requested | automatic commit, push, PR or release | none |
 
 ## Brownfield Modes
 

package/lib/control-state/run-state-parser.js

@@ -101,11 +101,13 @@ export function parseControlState(
   const approvals = new Map();
   for (const h of ["Approvals", "Gate Checklist"])
     for (const [g, s, e] of rows(section(content, h))) {
-      if (userGates.includes(g))
+      if (userGates.includes(g)) {
+        const status = clean(s);
         approvals.set(g, {
-          status: clean(s) === "passed" && g === "QA" ? "approved" : clean(s),
+          status: g === "QA" && (status === "pass" || status === "passed") ? "approved" : status,
           evidence: e ?? "",
         });
+      }
     }
   const artefacts = new Map();
   for (const [t, p, s, n] of rows(section(content, "Artefacts"))) {
@@ -113,7 +115,9 @@ export function parseControlState(
       artefacts.set(t, { path: p ?? "", status: clean(s), notes: n ?? "" });
   }
   const mapRows = (h, header, fn) => dataRows(content, h, header).map(fn);
-  const mode = "Mode / Slice Decision",
+  const mode = section(content, "Mode/Slice Decision").trim()
+      ? "Mode/Slice Decision"
+      : "Mode / Slice Decision",
     source = "Source And Scope State",
     memory = "Knowledge Persistence Decision";
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [