create-agdf 0.4.8 → 0.5.0

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

@@ -27,6 +27,25 @@ Use this compact output shape when no formal gate artefact is required:
 
 Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
 
+### Non-Normative Trivial Change Boundary
+
+A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
+the compact output shape above, and must not create, rewrite or expand any of `AGDF_RUN.md`'s core
+sections (Run Meta, Objective, Current Control State, Source And Scope State, Run Status Card,
+Approvals, Artefacts, Mode/Slice Decision, Artefact Chain, Evidence, Missing Evidence, Risks, Context
+Graph Impact, Knowledge Persistence Decision, Closeout):
+
+- `plugin/skills/**`
+- `plugin/control/templates/**`
+- `plugin/meta/**`
+- `create-agdf/lib/**`
+- `create-agdf/bin/**`
+- any other executable code file, in any language, anywhere in the repository
+
+A `MASTER_BACKLOG.md` entry is required only when the change is otherwise a "Relevant Run" below. A
+change that is not clearly and fully outside every listed path fails closed to the existing, unchanged
+ceremony — ambiguity is never read as permission for the lighter path.
+
 ## Run Status Card
 
 When a run needs an operational status view, use the Run Status Card as a compact projection of existing control state.
@@ -72,6 +91,12 @@ Delivery Path Search is an optional read-only planning step for high-impact deci
 - Search output is evidence only. Canonical `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.
+- Optional AI-native candidate generation supplements the deterministic candidate baseline; it never replaces it.
+- Generated proposals are untrusted. The core must validate schema, exact canonical gate action, scope, duplicates and material diversity before evaluation.
+- Generation is opt-in and bounded to one call, five proposals, 30 seconds and five abstract cost units by default, within whole-run budgets.
+- External generation receives only bounded normalized control summaries and references, never secrets, full artefacts, raw prompts, hidden reasoning or source snapshots.
+- Generator status, provenance, accepted/rejected counts, separate budget use and typed failure must remain visible. Failure retains the deterministic baseline; automatic provider fallback is forbidden.
+- Codex and Claude Code may provide tool-enforced generator transports. Copilot, OpenCode and generic surfaces remain instruction-only without conforming evidence.
 
 The field names above are the stable machine-readable contract used by JSON
 reports and automation. Human-facing Markdown must present the same projection
@@ -181,6 +206,11 @@ A relevant run is any run that changes durable state, creates or updates an AGDF
 OR is not mandatory for a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
 When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
 
+A `quick_task` fully inside the Non-Normative Trivial Change Boundary above stays exempt from the full
+`AGDF_RUN.md` ceremony even when it is otherwise a relevant run. If `AGDF_RUN.md` currently reflects
+another active run, append exactly one line to that run's `Prior Run Pointers` section noting what
+changed and that it is unrelated; do not edit any other section or any other existing line.
+
 ## Gate Rules
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`

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

@@ -37,6 +37,17 @@ Skip for routine questions, obvious local fixes and approved implementation with
 npx --yes @agdf/cli@latest delivery-path-search --surface <surface> --json
 ```
 
+Optional AI-native candidate generation is explicit:
+
+```bash
+npx --yes @agdf/cli@latest delivery-path-search \
+  --surface codex \
+  --generate-candidates \
+  --json
+```
+
+It supplements the deterministic baseline with at most one bounded generator call. Treat proposals as untrusted until the canonical core validates schema, gate action, scope, duplicates and material diversity. Report generation provenance, budgets, rejections and failure. Never hide deterministic fallback or switch providers automatically.
+
 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.
@@ -73,3 +84,6 @@ Persist only the redacted decision summary when durable evidence is required. Do
 - 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.
+- Do not replace deterministic candidates with generated proposals.
+- Do not send secrets, full artefacts, source snapshots, raw prompts or hidden reasoning to a generator.
+- Do not claim executable generation for instruction-only surfaces.

package/lib/delivery-path-search/candidate-policy.js

@@ -1,12 +1,37 @@
 import { validateCandidate } from "./contracts.js";
 
 function normalized(value) {
-  return String(value).toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
+  return String(value).normalize("NFKC").toLowerCase().replace(/[`*_]/g, "").replace(/[^\p{L}\p{N}\s-]/gu, " ").replace(/\s+/g, " ").trim();
+}
+
+const STOP_WORDS = new Set(["a", "an", "and", "der", "die", "das", "ein", "eine", "the", "to", "und", "zu"]);
+
+function tokens(value) {
+  return new Set(normalized(value).split(/\s+/).filter((item) => item && !STOP_WORDS.has(item)));
+}
+
+function jaccard(left, right) {
+  const union = new Set([...left, ...right]);
+  if (!union.size) return 1;
+  let intersection = 0;
+  for (const item of left) if (right.has(item)) intersection += 1;
+  return intersection / union.size;
+}
+
+function signature(candidate) {
+  return JSON.stringify({
+    gate_action: normalized(candidate.gate_action ?? candidate.action),
+    affected_boundaries: [...(candidate.affected_boundaries ?? [])].map(normalized).sort(),
+    evidence: [...(candidate.expected_evidence ?? [])].map(normalized).sort(),
+    tests: [...(candidate.tests ?? [])].map(normalized).sort(),
+    risk_strategy: normalized(candidate.risk_strategy ?? ""),
+    reversibility: normalized(candidate.reversibility ?? ""),
+  });
 }
 
 export function candidateLegality(candidateValue, input) {
   const candidate = validateCandidate(candidateValue);
-  const action = normalized(candidate.action);
+  const action = normalized(candidate.gate_action ?? candidate.action);
   const forbiddenMatch = input.forbidden_actions.find((item) => {
     const forbidden = normalized(item);
     return forbidden && action === forbidden;
@@ -32,3 +57,43 @@ export function candidatesFromInput(input) {
     parent_id: null,
   }));
 }
+
+export function generatedCandidatesFromResponse(response, input, existingCandidates = []) {
+  const accepted = [];
+  const rejected = [];
+  for (const proposal of response.proposals) {
+    const candidate = {
+      id: `generated-${proposal.proposal_id}`,
+      action: proposal.intent,
+      source: "generated",
+      gate_action: proposal.gate_action,
+      intent: proposal.intent,
+      expected_evidence: proposal.expected_evidence,
+      tests: proposal.tests,
+      assumptions: proposal.assumptions,
+      affected_boundaries: proposal.affected_boundaries,
+      risk_strategy: proposal.risk_strategy,
+      reversibility: proposal.reversibility,
+      generator_proposal_id: proposal.proposal_id,
+      depth: 0,
+      parent_id: null,
+    };
+    const legality = candidateLegality(candidate, input);
+    if (!legality.legal) {
+      rejected.push({ proposal_id: proposal.proposal_id, reason: legality.reason });
+      continue;
+    }
+    const peers = [...existingCandidates, ...accepted].filter((item) => normalized(item.gate_action ?? item.action) === normalized(candidate.gate_action));
+    const duplicate = peers.find((item) => {
+      const same = normalized(item.intent ?? item.action) === normalized(candidate.intent);
+      const sameDecision = signature(item) === signature(candidate);
+      return same || sameDecision || jaccard(tokens(item.intent ?? item.action), tokens(candidate.intent)) >= 0.8;
+    });
+    if (duplicate) {
+      rejected.push({ proposal_id: proposal.proposal_id, reason: "cosmetic_or_material_duplicate" });
+      continue;
+    }
+    accepted.push(candidate);
+  }
+  return { accepted, rejected };
+}

package/lib/delivery-path-search/contracts.js

@@ -1,4 +1,5 @@
 export const CONTRACT_VERSION = "1";
+export const GENERATOR_CONTRACT_VERSION = "1";
 export const SCORING_POLICY_VERSION = "1";
 export const SCORE_DIMENSIONS = [
   "scope_fit",
@@ -25,6 +26,39 @@ function stringArray(value, label) {
   return value.map((item) => item.trim()).filter(Boolean);
 }
 
+function optionalBoundedString(value, label, maxLength = 1000) {
+  if (value === undefined) return undefined;
+  const result = requireString(value, label);
+  if (result.length > maxLength) throw new Error(`${label} must be at most ${maxLength} characters`);
+  return result;
+}
+
+function rejectUnknownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new Error(`${label} contains unknown fields: ${unknown.join(", ")}`);
+}
+
+function generationConfig(value, wholeRunBudgets) {
+  if (value === undefined) return undefined;
+  const generation = requireObject(value, "generation");
+  if (typeof generation.enabled !== "boolean") throw new Error("generation.enabled must be a boolean");
+  const limits = {
+    max_calls: 1,
+    max_proposals: 5,
+    max_duration_ms: 30000,
+    max_cost_units: 5,
+  };
+  for (const [key, maximum] of Object.entries(limits)) {
+    if (!Number.isInteger(generation[key]) || generation[key] < 1 || generation[key] > maximum) {
+      throw new Error(`generation.${key} must be an integer from 1 to ${maximum}`);
+    }
+  }
+  if (generation.max_calls !== 1) throw new Error("generation.max_calls must equal 1 in this contract version");
+  if (generation.max_duration_ms > wholeRunBudgets.max_duration_ms) throw new Error("generation.max_duration_ms cannot exceed budgets.max_duration_ms");
+  if (generation.max_cost_units > wholeRunBudgets.max_cost_units) throw new Error("generation.max_cost_units cannot exceed budgets.max_cost_units");
+  return structuredClone(generation);
+}
+
 export function validateSearchInput(value) {
   const input = requireObject(value, "search input");
   if (input.contract_version !== CONTRACT_VERSION) throw new Error(`unsupported search input contract_version: ${input.contract_version}`);
@@ -43,6 +77,7 @@ export function validateSearchInput(value) {
   for (const key of ["max_candidates", "max_depth", "max_evaluations", "max_duration_ms", "max_cost_units", "stability_window"]) {
     if (!Number.isInteger(budgets[key]) || budgets[key] < 1) throw new Error(`budgets.${key} must be a positive integer`);
   }
+  generationConfig(input.generation, budgets);
   return structuredClone(input);
 }
 
@@ -53,9 +88,101 @@ export function validateCandidate(value) {
   stringArray(candidate.expected_evidence ?? [], "candidate.expected_evidence");
   stringArray(candidate.tests ?? [], "candidate.tests");
   stringArray(candidate.assumptions ?? [], "candidate.assumptions");
+  if (candidate.source !== undefined && !["deterministic", "generated", "expanded"].includes(candidate.source)) {
+    throw new Error("candidate.source must be deterministic, generated or expanded");
+  }
+  optionalBoundedString(candidate.gate_action, "candidate.gate_action");
+  optionalBoundedString(candidate.intent, "candidate.intent");
+  stringArray(candidate.affected_boundaries ?? [], "candidate.affected_boundaries");
+  optionalBoundedString(candidate.risk_strategy, "candidate.risk_strategy");
+  optionalBoundedString(candidate.reversibility, "candidate.reversibility");
+  optionalBoundedString(candidate.generator_proposal_id, "candidate.generator_proposal_id", 200);
   return structuredClone(candidate);
 }
 
+export function validateGeneratorRequest(value) {
+  const request = requireObject(value, "generator request");
+  rejectUnknownKeys(request, ["contract_version", "scope_key", "objective", "scope_summary", "current_gate", "allowed_actions", "forbidden_actions", "artefact_refs", "evidence", "missing_evidence", "risks", "constraints", "enforcement", "budgets"], "generator request");
+  if (request.contract_version !== GENERATOR_CONTRACT_VERSION) throw new Error(`unsupported generator contract_version: ${request.contract_version}`);
+  requireString(request.scope_key, "generator scope_key");
+  optionalBoundedString(request.objective, "generator objective", 2000);
+  optionalBoundedString(request.scope_summary, "generator scope_summary", 2000);
+  requireString(request.current_gate, "generator current_gate");
+  for (const key of ["allowed_actions", "forbidden_actions", "artefact_refs", "evidence", "missing_evidence", "risks", "constraints"]) {
+    const items = stringArray(request[key] ?? [], `generator ${key}`);
+    if (items.length > 20 || items.some((item) => item.length > 500)) throw new Error(`generator ${key} exceeds context bounds`);
+  }
+  validateEnforcement(request.enforcement);
+  const budgets = requireObject(request.budgets, "generator budgets");
+  generationConfig({ enabled: true, ...budgets }, { max_duration_ms: 120000, max_cost_units: 20 });
+  const serialized = JSON.stringify(request);
+  if (/(secret|credential|environment|raw_prompt|hidden_reasoning|source_snapshot)/i.test(serialized)) {
+    throw new Error("generator request contains disallowed context");
+  }
+  return structuredClone(request);
+}
+
+export function validateGeneratorResponse(value) {
+  const response = requireObject(value, "generator response");
+  rejectUnknownKeys(response, ["contract_version", "proposals", "cost_units", "metadata"], "generator response");
+  if (response.contract_version !== GENERATOR_CONTRACT_VERSION) throw new Error(`unsupported generator contract_version: ${response.contract_version}`);
+  if (!Array.isArray(response.proposals) || response.proposals.length > 5) throw new Error("generator proposals must be an array with at most 5 items");
+  if (!Number.isInteger(response.cost_units) || response.cost_units < 0 || response.cost_units > 5) throw new Error("generator cost_units must be an integer from 0 to 5");
+  if (response.metadata !== undefined) {
+    const metadata = requireObject(response.metadata, "generator metadata");
+    rejectUnknownKeys(metadata, ["name", "runtime", "model"], "generator metadata");
+    for (const [key, item] of Object.entries(metadata)) optionalBoundedString(item, `generator metadata.${key}`, 500);
+  }
+  const proposals = response.proposals.map((proposal, index) => {
+    const item = requireObject(proposal, `proposal ${index}`);
+    rejectUnknownKeys(item, ["proposal_id", "gate_action", "intent", "expected_evidence", "tests", "assumptions", "affected_boundaries", "risk_strategy", "reversibility"], `proposal ${index}`);
+    const normalized = {
+      proposal_id: requireString(item.proposal_id, `proposal ${index}.proposal_id`),
+      gate_action: requireString(item.gate_action, `proposal ${index}.gate_action`),
+      intent: requireString(item.intent, `proposal ${index}.intent`),
+      expected_evidence: stringArray(item.expected_evidence ?? [], `proposal ${index}.expected_evidence`),
+      tests: stringArray(item.tests ?? [], `proposal ${index}.tests`),
+      assumptions: stringArray(item.assumptions ?? [], `proposal ${index}.assumptions`),
+      affected_boundaries: stringArray(item.affected_boundaries ?? [], `proposal ${index}.affected_boundaries`),
+      risk_strategy: requireString(item.risk_strategy, `proposal ${index}.risk_strategy`),
+      reversibility: requireString(item.reversibility, `proposal ${index}.reversibility`),
+    };
+    if (JSON.stringify(normalized).length > 5000) throw new Error(`proposal ${index} exceeds size limit`);
+    if (/(^|\s)(rm|sudo|curl|wget|bash|sh|exec)\s/i.test(normalized.intent)) throw new Error(`proposal ${index} contains executable instructions`);
+    return normalized;
+  });
+  return {
+    contract_version: response.contract_version,
+    proposals,
+    cost_units: response.cost_units,
+    metadata: response.metadata ? structuredClone(response.metadata) : {},
+  };
+}
+
+export function generatorOutputSchema() {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["contract_version", "proposals", "cost_units"],
+    properties: {
+      contract_version: { type: "string", const: GENERATOR_CONTRACT_VERSION },
+      cost_units: { type: "integer", minimum: 0, maximum: 5 },
+      proposals: {
+        type: "array", maxItems: 5, items: {
+          type: "object", additionalProperties: false,
+          required: ["proposal_id", "gate_action", "intent", "expected_evidence", "tests", "assumptions", "affected_boundaries", "risk_strategy", "reversibility"],
+          properties: {
+            proposal_id: { type: "string", minLength: 1 }, gate_action: { type: "string", minLength: 1 }, intent: { type: "string", minLength: 1 },
+            expected_evidence: { type: "array", items: { type: "string" } }, tests: { type: "array", items: { type: "string" } },
+            assumptions: { type: "array", items: { type: "string" } }, affected_boundaries: { type: "array", items: { type: "string" } },
+            risk_strategy: { type: "string", minLength: 1 }, reversibility: { type: "string", minLength: 1 },
+          },
+        },
+      },
+    },
+  };
+}
+
 export function validateEvaluation(value, candidateId) {
   const evaluation = requireObject(value, "evaluation");
   if (evaluation.contract_version !== CONTRACT_VERSION) throw new Error(`unsupported evaluator contract_version: ${evaluation.contract_version}`);

package/lib/delivery-path-search/evaluators/claude.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
 
 export function claudeEvaluator(options = {}) {
   const claudeBin = options.claudeBin ?? "claude";
@@ -8,18 +9,6 @@ export function claudeEvaluator(options = {}) {
     runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {}
 
-  function gitState() {
-    try {
-      return execFileSync("git", ["status", "--porcelain=v1", "-z"], {
-        cwd: options.cwd,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-    } catch {
-      return null;
-    }
-  }
-
   return {
     name: "claude",
     metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },
@@ -41,15 +30,12 @@ export function claudeEvaluator(options = {}) {
       ];
       if (options.model) args.push("--model", options.model);
       args.push(prompt);
-      const before = gitState();
-      const raw = execFileSync(claudeBin, args, {
+      const raw = guardedExecFileSync(claudeBin, args, {
         cwd: options.cwd,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
         timeout: options.timeoutMs ?? 120000,
       });
-      const after = gitState();
-      if (before !== null && after !== before) throw new Error("repository mutation detected during read-only evaluator run");
       const response = JSON.parse(raw);
       if (response.is_error) throw new Error(`claude evaluator returned an error: ${response.result ?? "unknown error"}`);
       return validateEvaluation(JSON.parse(response.result), candidate.id);

package/lib/delivery-path-search/evaluators/codex.js

@@ -3,6 +3,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
 
 export function codexEvaluator(options = {}) {
   const codexBin = options.codexBin ?? "codex";
@@ -11,18 +12,6 @@ export function codexEvaluator(options = {}) {
     runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {}
 
-  function gitState() {
-    try {
-      return execFileSync("git", ["status", "--porcelain=v1", "-z"], {
-        cwd: options.cwd,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-    } catch {
-      return null;
-    }
-  }
-
   return {
     name: "codex",
     metadata: { name: "codex", runtime, model: options.model ?? "configured-default" },
@@ -49,15 +38,12 @@ export function codexEvaluator(options = {}) {
         ];
         if (options.model) args.push("--model", options.model);
         args.push(prompt);
-        const before = gitState();
-        execFileSync(codexBin, args, {
+        guardedExecFileSync(codexBin, args, {
           cwd: options.cwd,
           encoding: "utf8",
           stdio: ["ignore", "pipe", "pipe"],
           timeout: options.timeoutMs ?? 120000,
         });
-        const after = gitState();
-        if (before !== null && after !== before) throw new Error("repository mutation detected during read-only evaluator run");
         return validateEvaluation(JSON.parse(readFileSync(outputPath, "utf8")), candidate.id);
       } finally {
         rmSync(temp, { recursive: true, force: true });

package/lib/delivery-path-search/generators/claude.js

@@ -0,0 +1,40 @@
+import { execFileSync } from "node:child_process";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+
+export function claudeGenerator(options = {}) {
+  const claudeBin = options.claudeBin ?? "claude";
+  const execute = options.execute ?? guardedExecFileSync;
+  let runtime = options.runtime ?? "claude version unavailable";
+  if (!options.runtime) try { runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  return {
+    name: "claude",
+    metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },
+    async generate(requestValue) {
+      const request = validateGeneratorRequest(requestValue);
+      const prompt = [
+        "Generate bounded advisory delivery-path proposals. Do not use tools, execute commands, or modify files.",
+        "Return only JSON matching the supplied schema. Do not include hidden reasoning.",
+        `Normalized request: ${JSON.stringify(request)}`,
+      ].join("\n");
+      const args = ["-p", "--disallowedTools", "Edit,Write,Bash", "--output-format", "json", "--json-schema", JSON.stringify(generatorOutputSchema())];
+      if (options.model) args.push("--model", options.model);
+      args.push(prompt);
+      let raw;
+      try {
+        raw = execute(claudeBin, args, { cwd: options.cwd, timeout: options.timeoutMs ?? request.budgets.max_duration_ms });
+      } catch (error) {
+        const providerOutput = String(error?.stdout ?? "");
+        if (/not logged in|unauthorized|authentication/i.test(providerOutput)) {
+          const authentication = new Error("claude generator authentication failed");
+          authentication.code = "GENERATOR_AUTHENTICATION_FAILED";
+          throw authentication;
+        }
+        throw error;
+      }
+      const response = JSON.parse(raw);
+      if (response.is_error) throw new Error(`claude generator returned an error: ${response.result ?? "unknown error"}`);
+      return validateGeneratorResponse(JSON.parse(response.result));
+    },
+  };
+}

package/lib/delivery-path-search/generators/codex.js

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+
+export function codexGenerator(options = {}) {
+  const codexBin = options.codexBin ?? "codex";
+  const execute = options.execute ?? guardedExecFileSync;
+  let runtime = options.runtime ?? "codex version unavailable";
+  if (!options.runtime) try { runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  return {
+    name: "codex",
+    metadata: { name: "codex", runtime, model: options.model ?? "configured-default" },
+    async generate(requestValue) {
+      const request = validateGeneratorRequest(requestValue);
+      const temp = mkdtempSync(join(tmpdir(), "agdf-dps-generator-"));
+      const schemaPath = join(temp, "schema.json");
+      const outputPath = join(temp, "output.json");
+      try {
+        writeFileSync(schemaPath, `${JSON.stringify(generatorOutputSchema(), null, 2)}\n`, "utf8");
+        const prompt = [
+          "Generate bounded advisory delivery-path proposals. Do not use tools, execute commands, or modify files.",
+          "Return only JSON matching the supplied schema. Do not include hidden reasoning.",
+          `Normalized request: ${JSON.stringify(request)}`,
+        ].join("\n");
+        const args = ["exec", "--sandbox", "read-only", "--ephemeral", "--ignore-user-config", "--output-schema", schemaPath, "--output-last-message", outputPath, "--color", "never"];
+        if (options.model) args.push("--model", options.model);
+        args.push(prompt);
+        execute(codexBin, args, { cwd: options.cwd, timeout: options.timeoutMs ?? request.budgets.max_duration_ms });
+        return validateGeneratorResponse(JSON.parse(readFileSync(outputPath, "utf8")));
+      } finally {
+        rmSync(temp, { recursive: true, force: true });
+      }
+    },
+  };
+}

package/lib/delivery-path-search/generators/protocol.js

@@ -0,0 +1,12 @@
+import { validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+
+export function fixtureGenerator(response, metadata = { name: "fixture-generator" }) {
+  return {
+    name: metadata.name,
+    metadata,
+    async generate(request) {
+      validateGeneratorRequest(request);
+      return validateGeneratorResponse(response);
+    },
+  };
+}

package/lib/delivery-path-search/persistence.js

@@ -25,6 +25,11 @@ export function persistSearchResult(targetDir, result) {
     `- recommendation: ${recommendation}`,
     `- stopping_reason: ${safe.stopping_reason}`,
     `- evaluations: ${safe.budgets.evaluations}`,
+    `- generation_status: ${safe.generation?.status ?? "legacy_deterministic"}`,
+    `- generated_candidates: ${safe.generation ? `${safe.generation.accepted}/${safe.generation.returned}` : "0/0"}`,
+    `- generation_cost_units: ${safe.generation?.cost_units ?? 0}`,
+    `- generation_duration_ms: ${safe.generation?.duration_ms ?? 0}`,
+    ...(safe.generation?.failure_code ? [`- generation_failure: ${safe.generation.failure_code}`] : []),
     `- next_gate_action: ${safe.next_gate_action}`,
     "",
     "This summary contains model judgements, not measured facts. Canonical AGDF gate-check remains authoritative.",

package/lib/delivery-path-search/search-engine.js

@@ -1,11 +1,24 @@
 import { CONTRACT_VERSION, SCORING_POLICY_VERSION, validateEvaluation, validateSearchInput } from "./contracts.js";
-import { candidateLegality, candidatesFromInput } from "./candidate-policy.js";
+import { candidateLegality, candidatesFromInput, generatedCandidatesFromResponse } from "./candidate-policy.js";
 import { scoreEvaluation } from "./scoring.js";
+import { generatorRequestFromInput } from "./state-adapter.js";
+
+function generatorFailureCode(error) {
+  if (error?.code === "GENERATOR_MUTATION_DETECTED") return "generator_mutation_detected";
+  if (error?.code === "GENERATOR_TIMEOUT") return "generator_timeout";
+  if (error?.code === "GENERATOR_AUTHENTICATION_FAILED") return "generator_authentication_failed";
+  if (error?.code === "ENOENT") return "generator_unavailable";
+  if (/auth/i.test(error?.message ?? "")) return "generator_authentication_failed";
+  if (/context|disallowed/i.test(error?.message ?? "")) return "generator_context_rejected";
+  if (/budget/i.test(error?.message ?? "")) return "generator_budget_exceeded";
+  return "generator_schema_invalid";
+}
 
 export async function runDeliveryPathSearch(inputValue, evaluator, options = {}) {
   const input = validateSearchInput(inputValue);
   const startedAt = Date.now();
-  const queue = [...(options.candidates ?? candidatesFromInput(input))];
+  const baseline = [...(options.candidates ?? candidatesFromInput(input))];
+  const queue = [...baseline];
   const rejected = [];
   const evaluated = [];
   let evaluations = 0;
@@ -13,6 +26,53 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
   let lastLeaderId = null;
   let stableComparisons = 0;
   let stoppingReason = "candidate_queue_exhausted";
+  const generation = {
+    status: input.generation?.enabled ? "failed" : "disabled",
+    adapter: options.generator?.metadata ?? null,
+    budgets: input.generation ?? null,
+    returned: 0,
+    accepted: 0,
+    rejected: [],
+    cost_units: 0,
+    duration_ms: 0,
+    failure_code: null,
+  };
+
+  if (input.generation?.enabled) {
+    if (!options.generator) {
+      generation.failure_code = "generator_unavailable";
+    } else {
+      const generationStartedAt = Date.now();
+      try {
+        const response = await options.generator.generate(generatorRequestFromInput(input));
+        const elapsed = Date.now() - generationStartedAt;
+        generation.returned = response.proposals.length;
+        generation.cost_units = response.cost_units;
+        costUnits += response.cost_units;
+        if (elapsed > input.generation.max_duration_ms) {
+          const error = new Error("generator duration budget exceeded");
+          error.code = "GENERATOR_TIMEOUT";
+          throw error;
+        }
+        if (response.cost_units > input.generation.max_cost_units || response.proposals.length > input.generation.max_proposals) {
+          const error = new Error("generator response exceeds configured budget");
+          error.code = "GENERATOR_BUDGET_EXCEEDED";
+          throw error;
+        }
+        const filtered = generatedCandidatesFromResponse(response, input, baseline);
+        generation.accepted = filtered.accepted.length;
+        generation.rejected = filtered.rejected;
+        queue.push(...filtered.accepted.slice(0, input.generation.max_proposals));
+        generation.status = filtered.accepted.length === response.proposals.length ? "success" : "partial";
+        if (!filtered.accepted.length) generation.failure_code = "generator_no_diverse_proposals";
+      } catch (error) {
+        generation.failure_code = generatorFailureCode(error);
+        if (generation.failure_code === "generator_mutation_detected") throw error;
+      } finally {
+        generation.duration_ms = Date.now() - generationStartedAt;
+      }
+    }
+  }
 
   while (queue.length > 0) {
     if (evaluations >= input.budgets.max_evaluations) { stoppingReason = "evaluation_budget_exhausted"; break; }
@@ -46,6 +106,7 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
             parent_id: candidate.id,
             depth: (candidate.depth ?? 0) + 1,
             action,
+            source: "expanded",
             expected_evidence: [],
             tests: [],
             assumptions: evaluation.assumptions,
@@ -85,6 +146,7 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
     rejected,
     enforcement: input.enforcement,
     evaluator: evaluator.metadata ?? { name: evaluator.name ?? "unknown" },
+    generation,
     budgets: { configured: input.budgets, evaluations, cost_units: costUnits, stable_comparisons: stableComparisons, duration_ms: Date.now() - startedAt },
     stopping_reason: stoppingReason,
     next_gate_action: "Run canonical AGDF gate-check; search does not grant permission.",

package/lib/delivery-path-search/state-adapter.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { CONTRACT_VERSION } from "./contracts.js";
+import { CONTRACT_VERSION, GENERATOR_CONTRACT_VERSION, validateGeneratorRequest } from "./contracts.js";
 
 function section(content, heading) {
   return content.match(new RegExp(`## ${heading}\\r?\\n([\\s\\S]*?)(?=\\r?\\n## |$)`))?.[1] ?? "";
@@ -35,7 +35,7 @@ export function searchInputFromControl(targetDir, options = {}) {
   const meta = Object.fromEntries([...content.matchAll(/^- ([a-z_]+):\s*(.+)$/gm)].map((match) => [match[1], match[2].replace(/^`|`$/g, "").trim()]));
   const answers = tableAnswers(content);
   const card = statusCard(content);
-  return {
+  const result = {
     contract_version: CONTRACT_VERSION,
     scope_key: options.scopeKey ?? meta.run_id ?? "unknown-scope",
     objective: section(content, "Objective").trim(),
@@ -55,4 +55,36 @@ export function searchInputFromControl(targetDir, options = {}) {
       stability_window: options.stabilityWindow ?? 3,
     },
   };
+  if (options.generation?.enabled) result.generation = {
+    enabled: true,
+    max_calls: 1,
+    max_proposals: options.generation.maxProposals ?? 5,
+    max_duration_ms: options.generation.maxDurationMs ?? 30000,
+    max_cost_units: options.generation.maxCostUnits ?? 5,
+  };
+  return result;
+}
+
+export function generatorRequestFromInput(input) {
+  return validateGeneratorRequest({
+    contract_version: GENERATOR_CONTRACT_VERSION,
+    scope_key: input.scope_key,
+    objective: input.objective,
+    scope_summary: input.objective,
+    current_gate: input.current_gate,
+    allowed_actions: input.allowed_actions,
+    forbidden_actions: input.forbidden_actions,
+    artefact_refs: [],
+    evidence: input.evidence_refs ?? [],
+    missing_evidence: [],
+    risks: input.risks ?? [],
+    constraints: ["advisory only", "canonical gate-check remains authoritative"],
+    enforcement: input.enforcement,
+    budgets: {
+      max_calls: input.generation.max_calls,
+      max_proposals: input.generation.max_proposals,
+      max_duration_ms: input.generation.max_duration_ms,
+      max_cost_units: input.generation.max_cost_units,
+    },
+  });
 }