create-agdf 0.4.1 → 0.4.3

package/README.md

@@ -149,6 +149,27 @@ The gate check reports `open | blocked`, the current gate, blocking reason, miss
 
 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, "..");
@@ -15,7 +21,7 @@ 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 allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-status", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map"]);
+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"];
@@ -168,6 +174,7 @@ Preferred AGDF CLI:
   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
@@ -183,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
@@ -194,8 +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
 `);
 }
@@ -260,6 +274,10 @@ function parseArgs(argv) {
   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];
@@ -285,6 +303,29 @@ function parseArgs(argv) {
       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) {
@@ -334,7 +375,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, codex-repo, claude, copilot, opencode, opencode-status, 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);
   }
@@ -347,6 +388,10 @@ function parseArgs(argv) {
     statusCard,
     dirExplicit,
     language: resolveLanguagePreference(language),
+    surface,
+    fixture: fixture ? resolve(process.cwd(), fixture) : null,
+    persist,
+    model,
   };
 }
 
@@ -1143,6 +1188,9 @@ function evaluateDoctor(targetDir) {
     }
 
     const runState = readRunState(targetDir);
+    for (const finding of analyzeDurableGateArtefactConsistency(runState)) {
+      addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
+    }
     for (const finding of analyzeDeliveryMap(runState).findings) {
       addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
     }
@@ -1376,6 +1424,38 @@ function isDurableGateArtefactSatisfied(runState, gate) {
   return artefact.status === "approved";
 }
 
+function expectedDurableArtefactStatuses(gate) {
+  return gate === "QA" ? ["pass", "passed"] : ["approved"];
+}
+
+function describeDurableArtefactStatuses(gate) {
+  return expectedDurableArtefactStatuses(gate).map((status) => `\`${status}\``).join(" or ");
+}
+
+function analyzeDurableGateArtefactConsistency(runState) {
+  const findings = [];
+
+  for (const gate of durableGateArtefacts) {
+    if (gateApprovalStatus(runState, gate) !== "approved") continue;
+
+    const artefact = gateArtefactStatus(runState, gate);
+    if (!artefact.path || isPlaceholderValue(artefact.path) || !artefact.status) continue;
+
+    const expectedStatuses = expectedDurableArtefactStatuses(gate);
+    if (expectedStatuses.includes(artefact.status)) continue;
+
+    findings.push({
+      severity: "revise",
+      code: "AGDF_GATE_ARTEFACT_STATUS_INCONSISTENT",
+      message: `${gate} approval is recorded, but the durable artefact row uses status \`${artefact.status}\`; expected ${describeDurableArtefactStatuses(gate)}.`,
+      path: runState.path,
+      next_step: `Update the ${gate} artefact row in AGDF_RUN.md to use the gate-specific durable status vocabulary.`,
+    });
+  }
+
+  return findings;
+}
+
 function isInternalStepSatisfied(runState, step) {
   const artefact = runState.artefacts.get(step);
   if (!artefact) return false;
@@ -1956,7 +2036,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") {
@@ -1977,6 +2085,17 @@ 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);
@@ -2038,4 +2157,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/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:

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

@@ -52,6 +52,18 @@ It must not introduce a second gate model or override `agdf-gate-check`, `delive
 
 `quality_outlook` must not unlock gates, imply QA pass, or substitute for missing evidence.
 
+## Delivery Path Search
+
+Delivery Path Search is an optional read-only planning step for high-impact decisions with several materially different next actions.
+
+- It consumes current AGDF state and must reject gate-illegal candidates before model evaluation.
+- It returns one advisory recommendation or `no_safe_recommendation`.
+- It must report budgets, stopping reason and `full | tool_enforced | instruction_only` enforcement.
+- Model scores are judgements, not measurements.
+- Search output is evidence only. Canonical `agdf-gate-check` independently decides what may proceed.
+- The bounded first-release algorithm must not be labelled MCTS.
+- Surface adapters may translate transport and presentation, but must not fork scoring, search or gate semantics.
+
 The field names above are the stable machine-readable contract used by JSON
 reports and automation. Human-facing Markdown must present the same projection
 with readable labels such as `Current gate`, `Allowed now`, `Blocked by`,
@@ -254,6 +266,7 @@ When a run affects project memory or a Context Graph, use:
 - `Situation:` short plain-language summary when the impact is non-trivial
 - `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`
@@ -261,6 +274,17 @@ When a run affects project memory or a Context Graph, use:
 Do not create a new node for a mere version, a general chat summary, or a local observation without a concrete next clean step.
 `sot_drift` must not pass silently as a warning.
 
+### Context Graph Reconciliation
+
+Relevant-run closeout must reconcile Context Graph impact before presenting a clean delivery handoff.
+
+- Use `not_applicable` only when `context_graph_impact: none` and no durable graph knowledge is claimed.
+- Use `resolved` when required graph work is complete and concrete refs are present.
+- Use `open_gap` when graph work remains pending, refs are missing, or a node/update must still be curated.
+- `link`, `update`, `create` and `resolve_drift` require either `resolved` evidence or an explicit `open_gap`.
+- Resolved `link_only`, `update_existing_node` and `new_node_required` states require concrete `context_graph_refs`; `none`, empty refs or vague future-action language are not enough.
+- OR and delivery-closeout must not present commit-ready, release-ready or otherwise clean handoff while `context_graph_reconciliation: open_gap` remains.
+
 ## Control Scaffold
 
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.

package/generated/.opencode/AGDF.md

@@ -11,6 +11,7 @@ OpenCode project agents do not have a plugin namespace.
 
 Therefore generated OpenCode agent names use the AGDF prefix:
 
+- `agdf-delivery-path-search`
 - `agdf-brownfield-analysis`
 - `agdf-clean-implementation-review`
 - `agdf-code-review`
@@ -48,6 +49,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 ## Skill Routing
 | Skill | Use For | Boundary |
 |---|---|---|
+| `agdf-delivery-path-search` | high-impact planning decisions with several plausible next delivery steps before implementation | read-only advisory search; never grants gate permission or replaces gate-check |
 | `agdf-brownfield-analysis` | after gate-check permits Brownfield Review or implementation preparation, before non-trivial changes in existing systems | clarifies reuse, owners, risks and Mode/Slice Decision; never bypasses gate-check; Brownfield Review is not implementation permission |
 | `agdf-clean-implementation-review` | inspect workarounds, fallbacks, parallel structures or symptom fixes | not a TP or QA substitute |
 | `agdf-code-review` | mandatory CR step after code changes, focused on defects, regression and security findings | does not replace TP review, clean review or QA |

package/generated/.opencode/README.md

@@ -19,6 +19,7 @@ These files were generated from the AGDF source repository for OpenCode.
 - `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/.opencode/agdf-runtime-contract.md

@@ -52,6 +52,18 @@ It must not introduce a second gate model or override `agdf-gate-check`, `delive
 
 `quality_outlook` must not unlock gates, imply QA pass, or substitute for missing evidence.
 
+## Delivery Path Search
+
+Delivery Path Search is an optional read-only planning step for high-impact decisions with several materially different next actions.
+
+- It consumes current AGDF state and must reject gate-illegal candidates before model evaluation.
+- It returns one advisory recommendation or `no_safe_recommendation`.
+- It must report budgets, stopping reason and `full | tool_enforced | instruction_only` enforcement.
+- Model scores are judgements, not measurements.
+- Search output is evidence only. Canonical `agdf-gate-check` independently decides what may proceed.
+- The bounded first-release algorithm must not be labelled MCTS.
+- Surface adapters may translate transport and presentation, but must not fork scoring, search or gate semantics.
+
 The field names above are the stable machine-readable contract used by JSON
 reports and automation. Human-facing Markdown must present the same projection
 with readable labels such as `Current gate`, `Allowed now`, `Blocked by`,
@@ -254,6 +266,7 @@ When a run affects project memory or a Context Graph, use:
 - `Situation:` short plain-language summary when the impact is non-trivial
 - `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`
@@ -261,6 +274,17 @@ When a run affects project memory or a Context Graph, use:
 Do not create a new node for a mere version, a general chat summary, or a local observation without a concrete next clean step.
 `sot_drift` must not pass silently as a warning.
 
+### Context Graph Reconciliation
+
+Relevant-run closeout must reconcile Context Graph impact before presenting a clean delivery handoff.
+
+- Use `not_applicable` only when `context_graph_impact: none` and no durable graph knowledge is claimed.
+- Use `resolved` when required graph work is complete and concrete refs are present.
+- Use `open_gap` when graph work remains pending, refs are missing, or a node/update must still be curated.
+- `link`, `update`, `create` and `resolve_drift` require either `resolved` evidence or an explicit `open_gap`.
+- Resolved `link_only`, `update_existing_node` and `new_node_required` states require concrete `context_graph_refs`; `none`, empty refs or vague future-action language are not enough.
+- OR and delivery-closeout must not present commit-ready, release-ready or otherwise clean handoff while `context_graph_reconciliation: open_gap` remains.
+
 ## Control Scaffold
 
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.

package/generated/.opencode/agents/agdf-delivery-closeout.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/.opencode/agents/agdf-delivery-path-search.md

@@ -0,0 +1,76 @@
+---
+description: high-impact planning decisions with several plausible next delivery steps before implementation
+mode: subagent
+---
+
+# 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.
+