create-agdf 0.4.1 → 0.4.2

package/generated/AGENTS.md

@@ -11,6 +11,7 @@ GitHub Copilot repository skills do not have a plugin namespace.
 
 Therefore generated Copilot skill 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/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",

package/generated/plugins/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/plugins/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/plugins/agdf/meta/agdf-agent-router.md

@@ -12,6 +12,7 @@ Codex and Claude Code already provide the `agdf` plugin namespace.
 Therefore plugin skill names are intentionally unprefixed:
 
 - `gate-check`
+- `delivery-path-search`
 - `brownfield-analysis`
 - `task-plan-review`
 - `clean-implementation-review`
@@ -49,6 +50,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 ## Skill Routing
 | Skill | Use For | Boundary |
 |---|---|---|
+| `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 |
 | `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 |
 | `clean-implementation-review` | inspect workarounds, fallbacks, parallel structures or symptom fixes | not a TP or QA substitute |
 | `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/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
@@ -61,6 +61,11 @@
     }
   },
   "skillSet": [
+    {
+      "slug": "delivery-path-search",
+      "useFor": "high-impact planning decisions with several plausible next delivery steps before implementation",
+      "boundary": "read-only advisory search; never grants gate permission or replaces gate-check"
+    },
     {
       "slug": "brownfield-analysis",
       "useFor": "after gate-check permits Brownfield Review or implementation preparation, before non-trivial changes in existing systems",

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

@@ -52,6 +52,18 @@ It must not introduce a second gate model or override `gate-check`, `delivery-ma
 
 `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 `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/plugins/agdf/skills/delivery-closeout/SKILL.md

@@ -32,6 +32,7 @@ Use `../../meta/agdf-runtime-contract.md` for closeout discipline, gate terms, C
 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/plugins/agdf/skills/delivery-path-search/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: 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 `gate-check` remains the only authority for whether the recommended step may proceed.
+
+## Runtime Contract
+
+Use `../../meta/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/plugins/agdf/skills/delivery-path-search/help.md

@@ -0,0 +1,5 @@
+# Delivery Path Search
+
+Use this workflow before implementation when competing high-impact delivery paths need an evidence-backed comparison.
+
+It is read-only and advisory. The canonical AGDF gate-check still decides what may happen next.

package/generated/plugins/agdf/skills/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 `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 `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 `../../meta/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/lib/delivery-path-search/candidate-policy.js

@@ -0,0 +1,34 @@
+import { validateCandidate } from "./contracts.js";
+
+function normalized(value) {
+  return String(value).toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
+}
+
+export function candidateLegality(candidateValue, input) {
+  const candidate = validateCandidate(candidateValue);
+  const action = normalized(candidate.action);
+  const forbiddenMatch = input.forbidden_actions.find((item) => {
+    const forbidden = normalized(item);
+    return forbidden && action === forbidden;
+  });
+  if (forbiddenMatch) return { legal: false, reason: `forbidden_by_gate: ${forbiddenMatch}`, candidate };
+
+  const allowedMatch = input.allowed_actions.some((item) => {
+    const allowed = normalized(item);
+    return allowed && action === allowed;
+  });
+  if (!allowedMatch) return { legal: false, reason: "not_in_allowed_actions", candidate };
+  return { legal: true, reason: "allowed_by_current_gate", candidate };
+}
+
+export function candidatesFromInput(input) {
+  return input.allowed_actions.slice(0, input.budgets.max_candidates).map((action, index) => ({
+    id: `candidate-${index + 1}`,
+    action,
+    expected_evidence: input.evidence_refs,
+    tests: [],
+    assumptions: [],
+    depth: 0,
+    parent_id: null,
+  }));
+}

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

@@ -0,0 +1,110 @@
+export const CONTRACT_VERSION = "1";
+export const SCORING_POLICY_VERSION = "1";
+export const SCORE_DIMENSIONS = [
+  "scope_fit",
+  "gate_readiness",
+  "risk_reduction",
+  "evidence_gain",
+  "testability",
+  "reversibility",
+  "cost",
+];
+
+function requireObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return value;
+}
+
+function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be a non-empty string`);
+  return value.trim();
+}
+
+function stringArray(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`${label} must be a string array`);
+  return value.map((item) => item.trim()).filter(Boolean);
+}
+
+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}`);
+  requireString(input.scope_key, "scope_key");
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(input.scope_key) || input.scope_key.includes("..")) {
+    throw new Error("scope_key must be a safe path segment");
+  }
+  requireString(input.objective, "objective");
+  requireString(input.current_gate, "current_gate");
+  stringArray(input.allowed_actions, "allowed_actions");
+  stringArray(input.forbidden_actions, "forbidden_actions");
+  stringArray(input.evidence_refs ?? [], "evidence_refs");
+  stringArray(input.risks ?? [], "risks");
+  validateEnforcement(input.enforcement);
+  const budgets = requireObject(input.budgets, "budgets");
+  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`);
+  }
+  return structuredClone(input);
+}
+
+export function validateCandidate(value) {
+  const candidate = requireObject(value, "candidate");
+  requireString(candidate.id, "candidate.id");
+  requireString(candidate.action, "candidate.action");
+  stringArray(candidate.expected_evidence ?? [], "candidate.expected_evidence");
+  stringArray(candidate.tests ?? [], "candidate.tests");
+  stringArray(candidate.assumptions ?? [], "candidate.assumptions");
+  return structuredClone(candidate);
+}
+
+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}`);
+  if (evaluation.candidate_id !== candidateId) throw new Error(`evaluation candidate_id must be ${candidateId}`);
+  for (const dimension of SCORE_DIMENSIONS) {
+    if (!Number.isInteger(evaluation[dimension]) || evaluation[dimension] < 0 || evaluation[dimension] > 5) {
+      throw new Error(`${dimension} must be an integer from 0 to 5`);
+    }
+  }
+  if (!Number.isInteger(evaluation.uncertainty) || evaluation.uncertainty < 0 || evaluation.uncertainty > 5) {
+    throw new Error("uncertainty must be an integer from 0 to 5");
+  }
+  requireString(evaluation.rationale, "evaluation.rationale");
+  stringArray(evaluation.risks ?? [], "evaluation.risks");
+  stringArray(evaluation.assumptions ?? [], "evaluation.assumptions");
+  stringArray(evaluation.child_actions ?? [], "evaluation.child_actions");
+  if (/(^|\s)(rm|sudo|curl|wget|bash|sh|exec)\s/i.test(evaluation.rationale)) {
+    throw new Error("evaluation rationale contains executable instructions");
+  }
+  return structuredClone(evaluation);
+}
+
+export function validateEnforcement(value) {
+  const enforcement = requireObject(value, "enforcement");
+  if (!["full", "tool_enforced", "instruction_only"].includes(enforcement.level)) {
+    throw new Error("enforcement.level must be full, tool_enforced or instruction_only");
+  }
+  const evidence = stringArray(enforcement.evidence ?? [], "enforcement.evidence");
+  if (enforcement.level !== "instruction_only" && evidence.length === 0) {
+    throw new Error(`${enforcement.level} requires enforcement evidence`);
+  }
+  return { level: enforcement.level, evidence };
+}
+
+export function evaluatorOutputSchema() {
+  const scoreProperties = Object.fromEntries(SCORE_DIMENSIONS.map((key) => [key, { type: "integer", minimum: 0, maximum: 5 }]));
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["contract_version", "candidate_id", ...SCORE_DIMENSIONS, "uncertainty", "rationale", "risks", "assumptions", "child_actions"],
+    properties: {
+      contract_version: { type: "string", const: CONTRACT_VERSION },
+      candidate_id: { type: "string" },
+      ...scoreProperties,
+      uncertainty: { type: "integer", minimum: 0, maximum: 5 },
+      rationale: { type: "string", minLength: 1, maxLength: 1000 },
+      risks: { type: "array", items: { type: "string" } },
+      assumptions: { type: "array", items: { type: "string" } },
+      child_actions: { type: "array", items: { type: "string" }, maxItems: 5 },
+    },
+  };
+}

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

@@ -0,0 +1,67 @@
+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 { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+
+export function codexEvaluator(options = {}) {
+  const codexBin = options.codexBin ?? "codex";
+  let runtime = "codex version unavailable";
+  try {
+    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" },
+    async evaluate(input, candidate) {
+      const temp = mkdtempSync(join(tmpdir(), "agdf-dps-"));
+      const schemaPath = join(temp, "schema.json");
+      const outputPath = join(temp, "output.json");
+      try {
+        writeFileSync(schemaPath, `${JSON.stringify(evaluatorOutputSchema(), null, 2)}\n`, "utf8");
+        const prompt = [
+          "You are an evaluation-only component. Do not use tools, execute commands, or modify files.",
+          `Return JSON matching contract version ${input.contract_version}.`,
+          `Objective: ${input.objective}`,
+          `Current gate: ${input.current_gate}`,
+          `Candidate id: ${candidate.id}`,
+          `Candidate action: ${candidate.action}`,
+          "Score scope_fit, gate_readiness, risk_reduction, evidence_gain, testability, reversibility and cost from 0 to 5.",
+          "Cost 0 is low and 5 is high. uncertainty is 0 low to 5 high.",
+          "Keep rationale concise. child_actions must only contain actions permitted by the current gate.",
+        ].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);
+        const before = gitState();
+        execFileSync(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/evaluators/protocol.js

@@ -0,0 +1,13 @@
+import { validateEvaluation } from "../contracts.js";
+
+export function fixtureEvaluator(evaluations) {
+  return {
+    name: "fixture",
+    metadata: { name: "fixture", runtime: "deterministic-test" },
+    async evaluate(_input, candidate) {
+      const value = evaluations[candidate.id];
+      if (!value) throw new Error(`missing fixture evaluation for ${candidate.id}`);
+      return validateEvaluation(value, candidate.id);
+    },
+  };
+}

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

@@ -0,0 +1,34 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+function safeResult(result) {
+  return JSON.parse(JSON.stringify(result, (key, value) => {
+    if (/(prompt|hidden_reasoning|secret|credential|source_snapshot)/i.test(key)) return undefined;
+    return value;
+  }));
+}
+
+export function persistSearchResult(targetDir, result) {
+  const root = join(targetDir, ".agdf", "control", "artefacts", result.scope_key);
+  const jsonPath = join(root, "DELIVERY_PATH_SEARCH.json");
+  const markdownPath = join(root, "DELIVERY_PATH_SEARCH.md");
+  mkdirSync(dirname(jsonPath), { recursive: true });
+  const safe = safeResult(result);
+  writeFileSync(jsonPath, `${JSON.stringify(safe, null, 2)}\n`, "utf8");
+  const recommendation = safe.recommendation?.action ?? "No safe recommendation";
+  writeFileSync(markdownPath, [
+    "# Delivery Path Search Decision",
+    "",
+    `- status: ${safe.status}`,
+    `- current_gate: ${safe.current_gate}`,
+    `- enforcement: ${safe.enforcement.level}`,
+    `- recommendation: ${recommendation}`,
+    `- stopping_reason: ${safe.stopping_reason}`,
+    `- evaluations: ${safe.budgets.evaluations}`,
+    `- next_gate_action: ${safe.next_gate_action}`,
+    "",
+    "This summary contains model judgements, not measured facts. Canonical AGDF gate-check remains authoritative.",
+    "",
+  ].join("\n"), "utf8");
+  return { jsonPath, markdownPath };
+}

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

@@ -0,0 +1,21 @@
+import { SCORING_POLICY_VERSION } from "./contracts.js";
+
+export const DEFAULT_WEIGHTS = Object.freeze({
+  scope_fit: 3,
+  gate_readiness: 3,
+  risk_reduction: 2,
+  evidence_gain: 2,
+  testability: 2,
+  reversibility: 1,
+  cost: -1,
+  uncertainty: -2,
+});
+
+const enforcementPenalty = { full: 0, tool_enforced: 1, instruction_only: 4 };
+
+export function scoreEvaluation(evaluation, enforcementLevel, weights = DEFAULT_WEIGHTS) {
+  const contributions = Object.fromEntries(Object.entries(weights).map(([key, weight]) => [key, evaluation[key] * weight]));
+  const penalty = enforcementPenalty[enforcementLevel] ?? 4;
+  const score = Object.values(contributions).reduce((sum, value) => sum + value, 0) - penalty;
+  return { score, contributions, enforcement_penalty: penalty, scoring_policy_version: SCORING_POLICY_VERSION };
+}

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

@@ -0,0 +1,92 @@
+import { CONTRACT_VERSION, SCORING_POLICY_VERSION, validateEvaluation, validateSearchInput } from "./contracts.js";
+import { candidateLegality, candidatesFromInput } from "./candidate-policy.js";
+import { scoreEvaluation } from "./scoring.js";
+
+export async function runDeliveryPathSearch(inputValue, evaluator, options = {}) {
+  const input = validateSearchInput(inputValue);
+  const startedAt = Date.now();
+  const queue = [...(options.candidates ?? candidatesFromInput(input))];
+  const rejected = [];
+  const evaluated = [];
+  let evaluations = 0;
+  let costUnits = 0;
+  let lastLeaderId = null;
+  let stableComparisons = 0;
+  let stoppingReason = "candidate_queue_exhausted";
+
+  while (queue.length > 0) {
+    if (evaluations >= input.budgets.max_evaluations) { stoppingReason = "evaluation_budget_exhausted"; break; }
+    if (costUnits >= input.budgets.max_cost_units) { stoppingReason = "cost_budget_exhausted"; break; }
+    if (Date.now() - startedAt >= input.budgets.max_duration_ms) { stoppingReason = "duration_budget_exhausted"; break; }
+    const candidate = queue.shift();
+    const legality = candidateLegality(candidate, input);
+    if (!legality.legal) {
+      rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: legality.reason });
+      continue;
+    }
+
+    try {
+      const evaluation = validateEvaluation(await evaluator.evaluate(input, candidate), candidate.id);
+      evaluations += 1;
+      costUnits += evaluation.cost;
+      const scored = scoreEvaluation(evaluation, input.enforcement.level);
+      evaluated.push({ candidate, evaluation, ...scored });
+      const currentLeader = [...evaluated].sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id))[0];
+      if (currentLeader?.candidate.id === lastLeaderId) stableComparisons += 1;
+      else stableComparisons = 1;
+      lastLeaderId = currentLeader?.candidate.id ?? null;
+      if (evaluated.length > 1 && stableComparisons >= input.budgets.stability_window) {
+        stoppingReason = "stable_leader";
+        break;
+      }
+      if ((candidate.depth ?? 0) + 1 < input.budgets.max_depth) {
+        for (const [index, action] of evaluation.child_actions.slice(0, input.budgets.max_candidates).entries()) {
+          queue.push({
+            id: `${candidate.id}.${index + 1}`,
+            parent_id: candidate.id,
+            depth: (candidate.depth ?? 0) + 1,
+            action,
+            expected_evidence: [],
+            tests: [],
+            assumptions: evaluation.assumptions,
+          });
+        }
+      }
+    } catch (error) {
+      rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: `invalid_evaluation: ${error.message}` });
+    }
+  }
+
+  evaluated.sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
+  const leader = evaluated[0];
+  if (!leader) stoppingReason = rejected.length ? "no_safe_candidate" : stoppingReason;
+  return {
+    contract_version: CONTRACT_VERSION,
+    scoring_policy_version: SCORING_POLICY_VERSION,
+    scope_key: input.scope_key,
+    current_gate: input.current_gate,
+    status: leader ? "recommendation" : "no_safe_recommendation",
+    recommendation: leader ? {
+      candidate_id: leader.candidate.id,
+      action: leader.candidate.action,
+      score: leader.score,
+      rationale: leader.evaluation.rationale,
+      expected_evidence: leader.candidate.expected_evidence,
+      tests: leader.candidate.tests,
+      risks: leader.evaluation.risks,
+      assumptions: leader.evaluation.assumptions,
+    } : null,
+    alternatives: evaluated.slice(1).map((item) => ({
+      candidate_id: item.candidate.id,
+      action: item.candidate.action,
+      score: item.score,
+      rejection_reason: `ranked_below_${leader?.candidate.id ?? "safety_threshold"}`,
+    })),
+    rejected,
+    enforcement: input.enforcement,
+    evaluator: evaluator.metadata ?? { name: evaluator.name ?? "unknown" },
+    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.",
+  };
+}