create-agdf 0.4.0 → 0.4.2

package/README.md

@@ -10,10 +10,13 @@ Preferred long-term CLI shape:
 npx --yes @agdf/cli@latest codex
 npx --yes @agdf/cli@latest codex-repo
 npx --yes @agdf/cli@latest claude
+npx --yes @agdf/cli@latest opencode
+npx --yes @agdf/cli@latest opencode-status
 npx --yes @agdf/cli@latest opencode-repo
 npx --yes @agdf/cli@latest init
 npx --yes @agdf/cli@latest config --language en
 npx --yes @agdf/cli@latest doctor
+npx --yes @agdf/cli@latest gate-check --status-card
 npx --yes @agdf/cli@latest gate-check --json
 ```
 
@@ -24,6 +27,8 @@ npm create agdf@latest -- codex
 npm create agdf@latest -- codex-repo
 npm create agdf@latest -- claude
 npm create agdf@latest -- copilot
+npm create agdf@latest -- opencode
+npm create agdf@latest -- opencode-status
 npm create agdf@latest -- opencode-repo
 npm create agdf@latest -- both
 npm create agdf@latest -- init
@@ -47,6 +52,7 @@ If no language is provided, `create-agdf` derives the preference from the local
 - `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-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed OpenCode agents under `.opencode/agents/`, explicit edit/bash 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
@@ -63,6 +69,14 @@ Use the `opencode` target to install the AGDF npm plugin as a user-wide OpenCode
 npx --yes @agdf/cli@latest opencode
 ```
 
+Then verify the visible installation state:
+
+```bash
+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.
+
 Use the `opencode-repo` target when AGDF should be available to OpenCode from repository files:
 
 ```bash
@@ -133,6 +147,29 @@ npx --yes create-agdf@latest gate-check --json
 
 The gate check reports `open | blocked`, the current gate, blocking reason, missing exact approval, allowed outputs, forbidden outputs, next allowed action, evidence references and the embedded doctor report.
 
+Use `gate-check --status-card` for compact interactive output, especially in OpenCode where shell output is highly visible. Keep `gate-check --json` for automation, CI, regression evidence and audit trails.
+
+Use `delivery-path-search` only for high-impact planning decisions with several materially different next steps:
+
+```bash
+npx --yes @agdf/cli@latest delivery-path-search --surface codex --json
+```
+
+The first release uses bounded best-first Delivery Path Search, not MCTS. It is read-only and advisory: the result must be checked by canonical `gate-check`. Codex is the executable reference adapter; Claude Code, Copilot and OpenCode reuse the same skill and contracts while declaring whether enforcement is full, tool-enforced or instruction-only.
+
+Requirements and boundaries:
+
+- run it only in a repository with live `.agdf/control/AGDF_RUN.md` state
+- the current control state must expose legal next actions
+- Codex CLI must be installed and authenticated for `--surface codex`
+- `--model <id>` optionally selects the Codex evaluator model
+- `--persist` writes redacted `DELIVERY_PATH_SEARCH.json` and `.md` evidence under the current scope
+- `--fixture <path>` is for deterministic contract tests, not a production evaluator
+- Claude Code, Copilot and OpenCode have shared workflow mappings but no executable native evaluator in this release
+- cost units are rubric values used for bounded comparison, not measured provider currency
+
+The result is either one recommendation or `no_safe_recommendation`. In both cases run canonical `gate-check` afterwards.
+
 `gate-check --json` and `delivery-map --json` also expose a `status_card` object. It is a compact projection of the current control state: current gate, allowed and forbidden actions, blocker, next skill, next permissible step and `quality_outlook`. `next_step` is process permission; `quality_outlook` is the next meaningful quality-improvement focus and does not unlock gates.
 
 Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction layer into a repository control system when durable control state is needed. For normal fresh requests, keep the path lighter: draft the minimal UR in the response, request `Approval: UR`, and use CLI validators only when machine-readable proof is useful.

package/bin/create-agdf.js

@@ -6,6 +6,12 @@ import { homedir } from "node:os";
 import { dirname, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
+import { searchInputFromControl } from "../lib/delivery-path-search/state-adapter.js";
+import { runDeliveryPathSearch } from "../lib/delivery-path-search/search-engine.js";
+import { codexEvaluator } from "../lib/delivery-path-search/evaluators/codex.js";
+import { fixtureEvaluator } from "../lib/delivery-path-search/evaluators/protocol.js";
+import { enforcementForSurface } from "../lib/delivery-path-search/surfaces/capabilities.js";
+import { persistSearchResult } from "../lib/delivery-path-search/persistence.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
@@ -13,7 +19,9 @@ 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 allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map"]);
+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 allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-status", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map", "delivery-path-search"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 const openCodeConfigFragmentPath = "opencode.agdf.json";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
@@ -161,10 +169,12 @@ Preferred AGDF CLI:
   npx --yes @agdf/cli@latest codex-repo
   npx --yes @agdf/cli@latest claude
   npx --yes @agdf/cli@latest opencode
+  npx --yes @agdf/cli@latest opencode-status
   npx --yes @agdf/cli@latest opencode-repo
   npx --yes @agdf/cli@latest init
   npx --yes @agdf/cli@latest doctor
   npx --yes @agdf/cli@latest gate-check --json
+  npx --yes @agdf/cli@latest delivery-path-search --surface codex --json
 
 Scaffold-compatible npm create usage:
   npm create agdf@latest -- codex
@@ -172,6 +182,7 @@ Scaffold-compatible npm create usage:
   npm create agdf@latest -- claude
   npm create agdf@latest -- copilot
   npm create agdf@latest -- opencode
+  npm create agdf@latest -- opencode-status
   npm create agdf@latest -- opencode-repo
   npm create agdf@latest -- both
   npm create agdf@latest -- init
@@ -179,6 +190,7 @@ Scaffold-compatible npm create usage:
   npm create agdf@latest -- doctor
   npm create agdf@latest -- gate-check
   npm create agdf@latest -- delivery-map
+  npm create agdf@latest -- delivery-path-search --surface codex
 
 Backward-compatible create-agdf usage:
   npx --yes create-agdf@latest doctor --json
@@ -190,7 +202,14 @@ Options:
   --language <de|en>
                  Set AGDF chat and artefact language. Defaults to detected system locale.
   --lang <de|en> Alias for --language
-  --json         Print doctor, gate-check or delivery-map output as JSON
+  --json         Print machine-readable command output as JSON
+  --status-card  Print compact gate-check status-card output for interactive use
+  --surface <codex|claude|copilot|opencode|generic>
+                 Declare the active Delivery Path Search surface
+  --fixture <path>
+                 Use deterministic evaluator/candidate fixtures instead of a live evaluator
+  --persist      Persist the redacted Delivery Path Search result under the current scope
+  --model <id>   Optional Codex evaluator model
   --help         Show this help
 `);
 }
@@ -252,8 +271,13 @@ function parseArgs(argv) {
   let dir = ".";
   let force = false;
   let json = false;
+  let statusCard = false;
   let language;
   let dirExplicit = false;
+  let surface = "generic";
+  let fixture;
+  let persist = false;
+  let model;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -274,6 +298,34 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--status-card") {
+      statusCard = true;
+      continue;
+    }
+
+    if (arg === "--persist") {
+      persist = true;
+      continue;
+    }
+
+    if (["--surface", "--fixture", "--model"].includes(arg)) {
+      const next = args[i + 1];
+      if (!next) {
+        console.error(`Missing value for ${arg}`);
+        process.exit(1);
+      }
+      if (arg === "--surface") {
+        if (!["codex", "claude", "copilot", "opencode", "generic"].includes(next)) {
+          console.error("Unsupported surface. Use codex, claude, copilot, opencode or generic.");
+          process.exit(1);
+        }
+        surface = next;
+      } else if (arg === "--fixture") fixture = next;
+      else model = next;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--language" || arg === "--lang") {
       const next = args[i + 1];
       if (!next) {
@@ -323,7 +375,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, codex-repo, claude, copilot, opencode, opencode-repo, both, init, config, doctor, gate-check or delivery-map.");
+    console.error("Please choose one target: codex, codex-repo, claude, copilot, opencode, opencode-status, opencode-repo, both, init, config, doctor, gate-check, delivery-map or delivery-path-search.");
     printUsage();
     process.exit(1);
   }
@@ -333,8 +385,13 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    statusCard,
     dirExplicit,
     language: resolveLanguagePreference(language),
+    surface,
+    fixture: fixture ? resolve(process.cwd(), fixture) : null,
+    persist,
+    model,
   };
 }
 
@@ -371,6 +428,11 @@ function installOpenCodeGlobalPlugin(configDir) {
   };
 
   mkdirSync(configDir, { recursive: true });
+  try {
+    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--prefix", configDir, packageRoot], { 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");
 
   return {
@@ -379,6 +441,119 @@ function installOpenCodeGlobalPlugin(configDir) {
   };
 }
 
+function readOpenCodeConfig(configPath) {
+  if (!existsSync(configPath)) return { exists: false, parseError: "", config: {} };
+  try {
+    return { exists: true, parseError: "", config: JSON.parse(readFileSync(configPath, "utf8")) };
+  } catch (error) {
+    return { exists: true, parseError: error.message, config: {} };
+  }
+}
+
+function isOpenCodeRepositorySurfacePresent(targetDir) {
+  return existsSync(join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName))
+    && existsSync(join(targetDir, ".opencode", "agents", `${pluginDefinition.opencode.skillPrefix}gate-check.md`));
+}
+
+function resolveOpenCodePackage(configDir) {
+  const packageName = pluginDefinition.opencode.npmPackage;
+  try {
+    return {
+      loadable: true,
+      path: execFileSync(process.execPath, ["-e", `process.stdout.write(require.resolve(${JSON.stringify(packageName)}))`], {
+        cwd: configDir,
+        encoding: "utf8",
+        stdio: "pipe",
+      }),
+      error: "",
+    };
+  } catch (error) {
+    return {
+      loadable: false,
+      path: "",
+      error: (error.stderr || error.message || "package not resolvable").toString().trim(),
+    };
+  }
+}
+
+function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir()) {
+  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 sessionSignals = {
+    active: process.env.AGDF_PLUGIN_ACTIVE === "1",
+    version: process.env.AGDF_PLUGIN_VERSION || "",
+    control_dir: process.env.AGDF_CONTROL_DIR || "",
+    repository_surface: process.env.AGDF_OPENCODE_REPOSITORY_SURFACE === "1",
+  };
+  const repositorySurface = isOpenCodeRepositorySurfacePresent(targetDir);
+
+  const findings = [];
+  if (!configState.exists) findings.push("OpenCode global config not found.");
+  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 (!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.");
+
+  return {
+    schema_version: "1",
+    status: globalConfigured && packageState.loadable ? "configured" : "not_configured",
+    global_config: {
+      path: configPath,
+      exists: configState.exists,
+      parse_error: configState.parseError,
+      plugin_configured: globalConfigured,
+    },
+    package: {
+      name: pluginDefinition.opencode.npmPackage,
+      loadable: packageState.loadable,
+      resolved_path: packageState.path,
+      error: packageState.error,
+    },
+    session: sessionSignals,
+    repository_surface: {
+      path: targetDir,
+      present: repositorySurface,
+      instructions: join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName),
+      gate_check_agent: join(targetDir, ".opencode", "agents", `${pluginDefinition.opencode.skillPrefix}gate-check.md`),
+    },
+    visible_entrypoint: repositorySurface ? `@${pluginDefinition.opencode.skillPrefix}gate-check` : "none until opencode-repo is installed for this repository",
+    findings,
+    next_step: repositorySurface
+      ? `Restart OpenCode if needed, then use @${pluginDefinition.opencode.skillPrefix}gate-check for new build/change intent.`
+      : "Run npx --yes @agdf/cli@latest opencode-repo in repositories where AGDF governance should be active and reviewable.",
+  };
+}
+
+function printOpenCodeStatus(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log("AGDF OpenCode status");
+  console.log(`Status: ${report.status}`);
+  console.log(`Global config: ${report.global_config.plugin_configured ? "configured" : "missing"} (${report.global_config.path})`);
+  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(`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}`);
+  console.log(`Repository surface: ${report.repository_surface.present ? "present" : "missing"}`);
+  console.log(`Visible entrypoint: ${report.visible_entrypoint}`);
+  console.log(`Next step: ${report.next_step}`);
+
+  if (report.findings.length > 0) {
+    console.log("");
+    console.log("Findings:");
+    for (const finding of report.findings) console.log(`- ${finding}`);
+  }
+}
+
 function installCodexGlobalPlugin() {
   try {
     execFileSync("codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
@@ -1703,12 +1878,30 @@ function evaluateGateCheck(targetDir) {
   };
 }
 
-function printGateCheckReport(report, json) {
+function printGateCheckStatusCard(report) {
+  const card = report.status_card;
+  console.log(`AGDF status-card: ${card.status}`);
+  console.log(`Current gate: ${card.current_gate}`);
+  console.log(`Blocked by: ${card.blocking_condition}`);
+  console.log(`Missing approval: ${card.missing_approval}`);
+  console.log(`Next skill: ${card.next_skill}`);
+  console.log(`Next step: ${card.next_step}`);
+  console.log(`Quality outlook: ${card.quality_outlook}`);
+  if (card.allowed_now.length > 0) console.log(`Allowed now: ${card.allowed_now.join("; ")}`);
+  if (card.forbidden_now.length > 0) console.log(`Forbidden now: ${card.forbidden_now.join("; ")}`);
+}
+
+function printGateCheckReport(report, json, statusCard = false) {
   if (json) {
     console.log(JSON.stringify(report, null, 2));
     return;
   }
 
+  if (statusCard) {
+    printGateCheckStatusCard(report);
+    return;
+  }
+
   console.log(`AGDF gate-check: ${report.status}`);
   console.log(`Current gate: ${report.current_gate}`);
   console.log(`Blocking reason: ${report.blocking_reason}`);
@@ -1808,7 +2001,35 @@ function printDeliveryMapReport(report, json) {
   }
 }
 
-function main() {
+async function executeDeliveryPathSearch(options) {
+  const fixture = options.fixture ? JSON.parse(readFileSync(options.fixture, "utf8")) : null;
+  const enforcement = fixture?.input?.enforcement ?? enforcementForSurface(options.surface);
+  const input = fixture?.input ?? searchInputFromControl(options.dir, { enforcement });
+  const evaluator = fixture
+    ? fixtureEvaluator(fixture.evaluations ?? {})
+    : options.surface === "codex"
+      ? codexEvaluator({ cwd: options.dir, model: options.model })
+      : null;
+  if (!evaluator) {
+    throw new Error(`${options.surface} has no executable evaluator in this release. Codex is the reference adapter; --fixture is available for deterministic contract testing.`);
+  }
+  const result = await runDeliveryPathSearch(input, evaluator, { candidates: fixture?.candidates });
+  if (options.persist) result.persistence = persistSearchResult(options.dir, result);
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  console.log(`AGDF Delivery Path Search: ${result.status}`);
+  console.log(`Current gate: ${result.current_gate}`);
+  console.log(`Enforcement: ${result.enforcement.level}`);
+  console.log(`Recommendation: ${result.recommendation?.action ?? "none"}`);
+  console.log(`Evaluations: ${result.budgets.evaluations}`);
+  console.log(`Stopping reason: ${result.stopping_reason}`);
+  console.log(result.next_gate_action);
+  return result;
+}
+
+async function main() {
   const options = parseArgs(process.argv.slice(2));
 
   if (options.target === "doctor") {
@@ -1819,7 +2040,7 @@ function main() {
 
   if (options.target === "gate-check") {
     const report = evaluateGateCheck(options.dir);
-    printGateCheckReport(report, options.json);
+    printGateCheckReport(report, options.json, options.statusCard);
     process.exit(report.status === "blocked" ? 2 : 0);
   }
 
@@ -1829,6 +2050,24 @@ function main() {
     process.exit(report.status === "block" ? 2 : 0);
   }
 
+  if (options.target === "delivery-path-search") {
+    try {
+      const result = await executeDeliveryPathSearch(options);
+      process.exitCode = result.status === "recommendation" ? 0 : 2;
+    } catch (error) {
+      console.error(`Delivery Path Search failed: ${error.message}`);
+      process.exitCode = 2;
+    }
+    return;
+  }
+
+  if (options.target === "opencode-status") {
+    const configDir = process.env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir();
+    const report = evaluateOpenCodeStatus(options.dir, configDir);
+    printOpenCodeStatus(report, options.json);
+    process.exit(report.status === "configured" ? 0 : 1);
+  }
+
   if (options.target === "codex") {
     try {
       installCodexGlobalPlugin();
@@ -1857,7 +2096,9 @@ function main() {
     try {
       const result = installOpenCodeGlobalPlugin(configDir);
       console.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
-      console.log("Run npx --yes @agdf/cli@latest opencode-repo in each repository where AGDF governance should be active and reviewable.");
+      const report = evaluateOpenCodeStatus(options.dir, configDir);
+      printOpenCodeStatus(report, false);
+      console.log("Restart OpenCode so it loads the updated global plugin config.");
     } catch (error) {
       console.error(error.message);
       process.exit(1);
@@ -1881,4 +2122,4 @@ function main() {
   printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment);
 }
 
-main();
+await main();

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

@@ -117,6 +117,7 @@ Keep the active work item traceable. A gate may open only when the previous gate
 
 - context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
 - context_graph_refs:
+- context_graph_reconciliation: `resolved | not_applicable | open_gap`
 - context_graph_required_action: `none | link | update | create | resolve_drift`
 - context_graph_gate_effect: `none | warning | revise | block`
 - context_graph_evidence:

package/generated/.agdf/control/templates/artefacts/OR.md

@@ -81,6 +81,7 @@ This is a compact projection of the control state. It does not replace gate-chec
 
 - context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
 - context_graph_refs:
+- context_graph_reconciliation: `resolved | not_applicable | open_gap`
 - context_graph_required_action: `none | link | update | create | resolve_drift`
 - context_graph_gate_effect: `none | warning | revise | block`
 - context_graph_evidence:

package/generated/.github/copilot-instructions.md

@@ -13,3 +13,4 @@ AGDF is active in this repository.
 - Do not infer gate approval from generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved".
 - Do not treat chat history as the source of truth for gate state, approvals, evidence or delivery status.
 - 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.
+- For interactive checks, prefer `npx --yes @agdf/cli@latest gate-check --status-card`. Use `gate-check --json` for automation or audit evidence and summarize the status card instead of mirroring full JSON into chat.

package/generated/.github/skills/README.md

@@ -8,6 +8,7 @@ These repository skills were generated from the AGDF source repository and are i
 - `agdf-clean-implementation-review`
 - `agdf-code-review`
 - `agdf-delivery-closeout`
+- `agdf-delivery-path-search`
 - `agdf-gate-check`
 - `agdf-qa-gate`
 - `agdf-release-or`

package/generated/.github/skills/agdf-delivery-closeout/SKILL.md

@@ -32,6 +32,7 @@ Use `../agdf-runtime-contract.md` for closeout discipline, gate terms, Context G
 4. `Approval: UAT` unlocks an active commit offer when code changes exist.
 5. No commit handoff for runs without code changes.
 6. Always include exactly one next step and one quality outlook.
+7. If OR, QA or current run state reports `context_graph_reconciliation: open_gap`, do not provide a clean commit-ready handoff; set the next step to resolve or explicitly retain the Context Graph gap.
 
 ## When To Use
 - after `QA pass` with code changes
@@ -62,8 +63,10 @@ If code-change status is unclear, do not claim a commit handoff.
    - `uat_approved_with_code`
    - `uat_approved_without_code`
    - `non_delivery_closeout`
-2. Derive Git handoff only when code changes exist.
-3. Set exactly one next delivery step:
+2. Check Context Graph reconciliation from OR, QA, review and current run state.
+3. If reconciliation is `open_gap`, report the delivery status as not cleanly handoff-ready and do not derive commit-ready Git text.
+4. Derive Git handoff only when code changes exist and no unresolved Context Graph gap remains.
+5. Set exactly one next delivery step:
    - offer commit
    - offer push
    - offer PR
@@ -71,13 +74,15 @@ If code-change status is unclear, do not claim a commit handoff.
    - run QA/review
    - obtain UAT/approval
    - perform documentation follow-up
-4. Set quality outlook:
+   - resolve Context Graph gap
+6. Set quality outlook:
    - no further technical follow-up
    - more tests
    - refactoring
    - documentation sharpening
    - monitoring/runtime verification
-5. If `Approval: UAT` exists and code changes were delivered, actively offer the commit but do not run it.
+   - Context Graph reconciliation
+7. If `Approval: UAT` exists, code changes were delivered, and no Context Graph gap remains, actively offer the commit but do not run it.
 
 ## Output
 For code-changing runs:

package/generated/.github/skills/agdf-delivery-path-search/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: agdf-delivery-path-search
+description: Use this skill for high-impact planning decisions when several materially different next delivery steps are plausible and comparing scope, risk, evidence, tests, cost and gate readiness would reduce expensive rework. Do not use for routine tasks, during implementation, or as gate permission.
+---
+
+# Delivery Path Search
+
+## Purpose
+
+Search a bounded set of possible delivery paths before implementation and return one safest evidence-backed next step.
+
+The search is advisory and read-only. Canonical AGDF `agdf-gate-check` remains the only authority for whether the recommended step may proceed.
+
+## Runtime Contract
+
+Use `../agdf-runtime-contract.md` for canonical gate state, output discipline and Delivery Path Search boundaries. This skill must not maintain a second gate or scoring model.
+
+## Trigger
+
+Use only when at least one applies:
+
+- high product, architecture, security, policy, persistence or release impact
+- several materially different next actions are plausible
+- a wrong decision would cause expensive rework
+- the best evidence-gathering or test action is unclear
+
+Skip for routine questions, obvious local fixes and approved implementation with one clear next action.
+
+## Workflow
+
+1. Run AGDF gate-check and inspect durable control state.
+2. Confirm that search is allowed and implementation is not occurring during exploration.
+3. Declare the active surface and its enforcement level.
+4. Invoke the shared CLI runtime:
+
+```bash
+npx --yes @agdf/cli@latest delivery-path-search --surface <surface> --json
+```
+
+5. Treat facts, repository evidence, assumptions and model judgements separately.
+6. Return exactly one recommendation or `no_safe_recommendation`.
+7. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
+
+## Enforcement
+
+Report exactly one:
+
+- `full`: trusted lifecycle controls prevent writes
+- `tool_enforced`: the evaluator receives read/evaluation tools only
+- `instruction_only`: write prevention is instructional and not technically proven
+
+Do not overstate the surface's guarantee.
+
+## Output
+
+Keep chat output compact:
+
+- recommendation or `no_safe_recommendation`
+- current gate
+- enforcement level
+- decisive evidence and assumptions
+- rejected alternatives and reasons
+- budgets and stopping reason
+- next AGDF gate action
+
+Persist only the redacted decision summary when durable evidence is required. Do not persist raw prompts, hidden reasoning, secrets or source snapshots.
+
+## Boundaries
+
+- This is bounded Delivery Path Search, not MCTS.
+- Do not modify repository files during search.
+- Do not execute evaluator-returned commands.
+- Do not invent default scores for invalid evaluator output.
+- Do not implement, approve or release based on search output.
+- Do not create agent-specific scoring, gate logic or skill copies.

package/generated/.github/skills/agdf-release-or/SKILL.md

@@ -44,6 +44,8 @@ Use the Runtime Contract definition of `Relevant Run` to decide whether OR is ma
 10. `CD+Tests` is not completion.
 11. When moving a backlog item to Completed or Superseded, use the canonical human-readable table and link the final OR with a document-relative Markdown link.
 12. Keep machine status normalization in the CLI; do not write internal snake_case status values into the human-facing backlog.
+13. Reconcile Context Graph impact before clean closeout: report `context_graph_reconciliation: resolved | not_applicable | open_gap`.
+14. If Context Graph work remains unresolved, report it as an explicit open gap and do not describe the run as cleanly handoff-ready.
 
 ## When To Use
 - at the end of every relevant run
@@ -89,10 +91,11 @@ If information is missing, state the gap instead of guessing.
 6. Summarize Brownfield fit and solution integrity if reviewed.
 7. Summarize tests and verification.
 8. Summarize documentation and Context Graph impact if relevant.
-9. Name retained fallbacks and exit criteria.
-10. Set exactly one next permissible step.
-11. Set exactly one quality outlook.
-12. State whether `agdf-delivery-closeout` is the next operational handoff step when code changes exist and the delivery state allows it.
+9. Record Context Graph reconciliation as `resolved`, `not_applicable`, or `open_gap`.
+10. Name retained fallbacks and exit criteria.
+11. Set exactly one next permissible step.
+12. Set exactly one quality outlook.
+13. State whether `agdf-delivery-closeout` is the next operational handoff step when code changes exist and the delivery state allows it.
 
 ## Output
 Use a compact structure:
@@ -114,6 +117,7 @@ Use a compact structure:
 ```
 
 When Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+Include `context_graph_reconciliation` whenever Context Graph impact is present. If the value is `open_gap`, required next step must resolve or explicitly retain that gap before commit-ready or release-ready handoff.
 
 ## Forbidden
 This skill must not: