create-agdf 0.4.0 → 0.4.2

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.",
+  };
+}

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

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONTRACT_VERSION } from "./contracts.js";
+
+function section(content, heading) {
+  return content.match(new RegExp(`## ${heading}\\r?\\n([\\s\\S]*?)(?=\\r?\\n## |$)`))?.[1] ?? "";
+}
+
+function tableAnswers(content) {
+  const answers = {};
+  for (const line of section(content, "Current Control State").split(/\r?\n/)) {
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+    if (cells.length >= 2 && cells[0] && !cells[0].startsWith("---") && cells[0] !== "Question") answers[cells[0]] = cells[1];
+  }
+  return answers;
+}
+
+function statusCard(content) {
+  const card = {};
+  for (const line of section(content, "Run Status Card").split(/\r?\n/)) {
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim().replace(/^`|`$/g, ""));
+    if (cells.length >= 2 && cells[0] && !cells[0].startsWith("---") && cells[0] !== "Run status") card[cells[0]] = cells[1];
+  }
+  return card;
+}
+
+function listCell(value) {
+  return String(value ?? "").split(/\s*;\s*/).map((item) => item.trim()).filter(Boolean);
+}
+
+export function searchInputFromControl(targetDir, options = {}) {
+  const runPath = join(targetDir, ".agdf", "control", "AGDF_RUN.md");
+  if (!existsSync(runPath)) throw new Error("missing .agdf/control/AGDF_RUN.md");
+  const content = readFileSync(runPath, "utf8");
+  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 {
+    contract_version: CONTRACT_VERSION,
+    scope_key: options.scopeKey ?? meta.run_id ?? "unknown-scope",
+    objective: section(content, "Objective").trim(),
+    current_gate: card["Current gate"] ?? meta.current_gate ?? "unknown",
+    allowed_actions: options.allowedActions ?? listCell(card["Allowed now"]),
+    forbidden_actions: options.forbiddenActions ?? listCell(answers["What is explicitly forbidden right now?"]),
+    evidence_refs: [...content.matchAll(/\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*(direct|indirect)\s*\|/g)]
+      .slice(1).map((match) => `${match[1].trim()}: ${match[2].trim()}`),
+    risks: section(content, "Risks").split(/\r?\n/).filter((line) => line.startsWith("|") && !line.includes("---") && !line.includes("| Risk |")).map((line) => line.split("|")[1].trim()),
+    enforcement: options.enforcement ?? { level: "instruction_only", evidence: ["surface instruction prohibits implementation during search"] },
+    budgets: {
+      max_candidates: options.maxCandidates ?? 5,
+      max_depth: options.maxDepth ?? 2,
+      max_evaluations: options.maxEvaluations ?? 8,
+      max_duration_ms: options.maxDurationMs ?? 120000,
+      max_cost_units: options.maxCostUnits ?? 20,
+      stability_window: options.stabilityWindow ?? 3,
+    },
+  };
+}

package/lib/delivery-path-search/surfaces/capabilities.js

@@ -0,0 +1,14 @@
+import { validateEnforcement } from "../contracts.js";
+
+export function enforcementForSurface(surface, evidence = []) {
+  const defaults = {
+    codex: { level: "tool_enforced", evidence: ["codex exec --sandbox read-only --ephemeral"] },
+    claude: { level: "instruction_only", evidence: [] },
+    copilot: { level: "instruction_only", evidence: [] },
+    opencode: { level: "instruction_only", evidence: [] },
+    generic: { level: "instruction_only", evidence: [] },
+  };
+  const selected = structuredClone(defaults[surface] ?? defaults.generic);
+  if (evidence.length) selected.evidence = evidence;
+  return validateEnforcement(selected);
+}

package/opencode-plugin.js

@@ -1,26 +1,38 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
 
 export const AGDFPlugin = async ({ directory, client }) => {
   const controlDir = `${directory}/.agdf/control`;
   const hasRepositorySurface = () => existsSync(`${directory}/.opencode/AGDF.md`) && existsSync(`${directory}/.opencode/agents`);
+  const status = () => ({
+    active: true,
+    version: packageJson.version,
+    controlDir,
+    repositorySurface: hasRepositorySurface(),
+  });
 
   return {
     event: async ({ event }) => {
       if (event?.type === "session.created") {
-        const repositorySurface = hasRepositorySurface();
+        const currentStatus = status();
         await client.app.log({
           body: {
             service: "agdf",
             level: "info",
-            message: repositorySurface ? "AGDF OpenCode surface active" : "AGDF OpenCode plugin loaded without repository surface",
-            extra: { controlDir, repositorySurface },
+            message: currentStatus.repositorySurface ? "AGDF OpenCode active" : "AGDF OpenCode global hook active without repository surface",
+            extra: currentStatus,
           },
         });
       }
     },
 
     "shell.env": async (_input, output) => {
+      const currentStatus = status();
+      output.env.AGDF_PLUGIN_ACTIVE = "1";
+      output.env.AGDF_PLUGIN_VERSION = currentStatus.version;
       output.env.AGDF_CONTROL_DIR = controlDir;
+      output.env.AGDF_OPENCODE_REPOSITORY_SURFACE = currentStatus.repositorySurface ? "1" : "0";
     },
 
     "experimental.session.compacting": async (_input, output) => {
@@ -38,7 +50,7 @@ export const AGDFPlugin = async ({ directory, client }) => {
         "## AGDF Runtime Reminder",
         "Use `.opencode/AGDF.md`, `.opencode/agents/` and `.agdf/control/` as the AGDF source for this OpenCode session.",
         "For new build/change intent or unclear approval, route first to `agdf-gate-check` before later artefacts or implementation.",
-        "Use `npx --yes @agdf/cli@latest gate-check --json` only as deterministic proof, not as a replacement for AGDF judgement.",
+        "Use `npx --yes @agdf/cli@latest gate-check --status-card` for compact interactive status. Use `--json` only as deterministic proof for automation or audit evidence, and summarize it instead of mirroring full JSON into chat.",
       ].join("\n"));
     },
   };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "create-agdf",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
     "bin",
+    "lib",
     "generated",
     "opencode-plugin.js",
     "README.md",
@@ -20,8 +21,9 @@
   },
   "scripts": {
     "sync-package-assets": "node ./scripts/sync-package-assets.js",
+    "test:delivery-path-search": "node ./scripts/delivery-path-search-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run sync-package-assets && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run sync-package-assets && npm run test:delivery-path-search && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run sync-package-assets"
   },
   "keywords": [