create-agdf 0.14.4 → 0.20.0

package/lib/cli/command-registry.js

@@ -1,3 +1,12 @@
+import { TASK_TARGET_SOURCES } from "#agdf-core/task-target-resolution.js";
+import { skillDispatchArgumentGrammar, skillDispatchCommandGrammar } from "#agdf-core/skill-dispatch/contract.js";
+import { validateReadSelection } from "#agdf-core/control-inspect/selection.js";
+import { RUN_COMMAND_GROUPS } from '#agdf-core/control-state/run-command-contract.js';
+export { skillDispatchArgumentGrammar };
+export const commandGroupRoutes = Object.freeze(Object.fromEntries(Object.keys(RUN_COMMAND_GROUPS).map(group => [group.replace('_', '-'), group])));
+
+const TASK_TARGET_SOURCE_GRAMMAR = `<${TASK_TARGET_SOURCES.join("|")}>`;
+
 function command(name, usages) {
   return Object.freeze({
     name,
@@ -10,19 +19,22 @@ function command(name, usages) {
 }
 
 export const commandRegistry = Object.freeze([
-  command("codex", { preferred: [""], scaffold: [""] }),
-  command("codex-repo", { preferred: [""], scaffold: [""] }),
-  command("claude", { preferred: [""], scaffold: [""] }),
-  command("copilot", { preferred: [""] }),
-  command("opencode", { preferred: [""], scaffold: [""] }),
+  command("codex", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
+  command("codex-repo", { preferred: [" --dir <path>"], scaffold: [" --dir <path>"] }),
+  command("claude", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
+  command("copilot", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"] }),
+  command("opencode", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
   command("opencode-status", { preferred: [""], scaffold: [""] }),
-  command("status", { preferred: [" [--surface <surface>] [--run <run_id>] [--json]"] }),
+  command("status", { preferred: [" [--surface <surface>] [--dir <absolute-target> [--scope <project|user>]] [--run <run_id>] [--json]"] }),
   command("runtime-checks", { preferred: [" <status|enable|manual> --surface <codex|claude|copilot|opencode> [--json]"] }),
-  command("disable", { preferred: [" --surface <surface> [--scope repository] [--shared] [--dir <path>]"] }),
-  command("uninstall", { preferred: [" --surface <surface> --scope global [--confirm]"] }),
-  command("opencode-repo", { preferred: [""], scaffold: [""] }),
+  command("mcp", { preferred: [" <status|enable|disable> --surface <codex|claude|copilot|opencode> [--scope <project|user>] --dir <absolute-target> [--json]"] }),
+  command("disable", { preferred: [" --surface <surface> [--scope repository] [--shared] [--dir <path>] [--with-mcp]"] }),
+  command("uninstall", { preferred: [" --surface <surface> --scope global [--with-mcp --mcp-scope <project|user> --dir <absolute-target>] [--confirm]"] }),
+  command("opencode-repo", { preferred: [" --dir <path>"], scaffold: [" --dir <path>"] }),
   command("init", { preferred: [""], scaffold: [""] }),
   command("config", { scaffold: [" --language de"] }),
+  command("target-check", { local: [` --json [--language <tag>] [--working-directory <absolute-path>] [--target-source ${TASK_TARGET_SOURCE_GRAMMAR} --primary-target <absolute-path>]`] }),
+  command("skill-dispatch", { local: [` ${skillDispatchCommandGrammar()}`] }),
   command("doctor", { local: [""], scaffold: [""], legacy: [" --json"] }),
   command("gate-check", { local: [" --approval-envelope", " --json"], scaffold: [""], legacy: [" --json"] }),
   command("delivery-map", { local: [" --json"], scaffold: [""] }),
@@ -30,9 +42,18 @@ export const commandRegistry = Object.freeze([
     local: [" --surface codex --json", " --surface claude --json", " --surface opencode --json"],
     scaffold: [" --surface codex", " --surface claude", " --surface opencode"],
   }),
+  command("contract", { local: [" --module <runtime-contract-module> [--json]"] }),
+  command("control-maintenance", { local: [" --dir <absolute-repository> [--guided | --details | --json] [--language <tag>]"] }),
+  command("run-present", { local: [" --run <run_id> --gate <gate> --revision <revision_id>"] }),
   command("run-create", { local: [" --run <run_id>"] }),
+  command("run-update", { local: [" --run <run_id> --revision <revision_id>"] }),
+  command("run-revise", { local: [" --run <run_id> --revision <revision_id>", " --preview|--apply --run <run_id> --revision <revision_id> --source-gate <UR|PRD|SD|TP> --operation <uuid> --evidence <proposal.json> [--preview-digest <sha256>]"] }),
+  command("run-step", { local: [" --run <run_id> --revision <revision_id> --step <ur|route|review|evidence|closeout|artefact> [step fields]"] }),
+  command("run-approve", { local: [" --run <run_id> --gate <UR|PRD|SD|TP|QA|UAT> --revision <revision_id> --presentation <presentation_id> --response \"Approval: <gate>\""] }),
   command("run-migrate", { local: [" [--run <run_id>]"] }),
+  command("run-recovery", { local: [" --run <run_id> --action <inspect|preview>", " --run <run_id> --action apply --preview-id <uuid> --recovery-confirmation \"RECOVER <run_id> <preview_id>\""] }),
   command("run-render-legacy", { local: [" --run <run_id>"] }),
+  ...Object.keys(commandGroupRoutes).map(name => command(name, { local: [' --command-file <bounded-command.json>'] })),
 ]);
 
 const commandByName = new Map(commandRegistry.map((entry) => [entry.name, entry]));
@@ -46,12 +67,137 @@ export function supportedCommandNames() {
 }
 
 export function validateCommandOptions(options) {
-  if (options.allActive && !["doctor", "delivery-map"].includes(options.target)) {
-    throw new Error("--all-active is supported only by doctor and delivery-map");
+  if (Object.hasOwn(commandGroupRoutes, options.target)) {
+    if (!options.commandFile) throw new Error('Bound command routes require --command-file; target/Run/revision/UUID are taken only from that strict envelope.');
+    return options;
+  }
+  if (options.commandFile) throw new Error('--command-file requires a fixed AGDF command-group route');
+  if ((options.guided || options.details) && options.target !== "control-maintenance") {
+    throw new Error("--guided and --details are supported only by control-maintenance");
+  }
+  if (options.target === "control-maintenance") {
+    if (!options.dirExplicit || !options.dirInputAbsolute) throw new Error("control-maintenance requires an explicit absolute --dir target");
+    if (options.guided && (options.json || options.details)) throw new Error("--guided cannot be combined with --json or --details");
+    if (options.runId || options.allActive || options.force || options.confirm || options.persist) throw new Error("control-maintenance does not support run selection or implicit apply flags");
+  }
+  const installTargets = ["codex", "claude", "copilot", "opencode"];
+  const installTarget = installTargets.includes(options.target);
+  if ((options.controlDir || options.controlMigration) && !installTarget) {
+    throw new Error("--control-dir and --control-migration are supported only by installation commands");
+  }
+  if (options.controlMigration === "safe" && !options.controlDir
+      && !(options.dirExplicit && (options.target !== "opencode" || options.setupRequest === "full"))) {
+    throw new Error("--control-migration safe requires an explicit repository target (--control-dir or --dir).");
+  }
+  if (options.target !== "mcp" && options.target !== "status" && !installTarget && ["project", "user"].includes(options.scope)) {
+    throw new Error("project and user scopes are supported only by mcp or a full installation setup");
+  }
+  if (options.setupRequest && !installTarget && !["disable", "uninstall"].includes(options.target)) {
+    throw new Error("--with-mcp and --plugin-only are supported only by installation, disable and uninstall commands");
+  }
+  if (options.setupRequest === "plugin_only" && !installTarget) {
+    throw new Error("--plugin-only is supported only by codex, claude, copilot and opencode installation commands");
+  }
+  if (installTarget && options.scope && (options.setupRequest !== "full" || !["project", "user"].includes(options.scope))) {
+    throw new Error("Installation --scope project or user requires --with-mcp");
+  }
+  if (options.mcpScope && !(options.target === "uninstall" && options.setupRequest === "full")) {
+    throw new Error("--mcp-scope is supported only by uninstall --with-mcp");
+  }
+  if (options.target === "status" && options.scope && (!options.dirExplicit
+      || !["codex", "claude", "copilot", "opencode"].includes(options.surface))) {
+    throw new Error("status --scope requires an explicit --surface and --dir target");
+  }
+  if (["codex-repo", "opencode-repo"].includes(options.target) && !options.dirExplicit) {
+    throw new Error(`${options.target} requires an explicit --dir`);
+  }
+  const targetOptionsUsed = Boolean(options.targetSource || options.primaryTarget || options.workingDirectoryExplicit || options.targetChanged
+    || options.targetCandidates?.length || options.evidenceSources?.length);
+  if (targetOptionsUsed && !["target-check", "skill-dispatch"].includes(options.target)) {
+    throw new Error("Task-target options are supported only by target-check and skill-dispatch");
+  }
+  if (options.target === "target-check" && !options.json) {
+    throw new Error("target-check requires --json");
+  }
+  if (options.skillId && options.target !== "skill-dispatch") throw new Error("--skill is supported only by skill-dispatch");
+  if ((options.intakeMode || options.urAction || options.prdAction || options.sdAction || options.tpAction || options.continueDelivery) && options.target !== "skill-dispatch") throw new Error("delivery modes are supported only by skill-dispatch");
+  if (options.assurance !== undefined && options.target !== "run-approve"
+      || options.operationId !== undefined && options.target !== "run-approve" && !(options.target === "run-revise" && options.revisionMode)) {
+    throw new Error("--operation requires run-approve or an explicit run-revise mode; --assurance requires run-approve");
   }
+  if ((options.revisionMode || options.sourceGate !== undefined || options.previewDigest !== undefined) && options.target !== "run-revise") throw new Error("Source revision fields require run-revise");
+  if (options.presentationId && options.target !== "run-approve") throw new Error("--presentation is supported only by run-approve");
+  if (options.target === "run-present" && (!options.runId || !options.gate || !options.revisionId)) throw new Error("run-present requires --run, --gate and --revision");
+  if (options.intake && options.target !== "skill-dispatch") throw new Error("--intake is supported only by skill-dispatch");
+  if (options.target === "skill-dispatch") {
+    if (!options.json) throw new Error("skill-dispatch requires --json");
+    if (!options.skillId) throw new Error("skill-dispatch requires --skill");
+    if (!options.surfaceExplicit || options.surface === "generic") throw new Error("skill-dispatch requires --surface codex, claude, copilot or opencode");
+    if (!options.languageExplicit) throw new Error("skill-dispatch requires --language");
+    if (!options.workingDirectoryExplicit) throw new Error("skill-dispatch requires --working-directory");
+    if (options.targetChanged || options.targetCandidates?.length || options.evidenceSources?.length) {
+      throw new Error("skill-dispatch accepts only the paired --target-source and --primary-target target options");
+    }
+  }
+  // Shared read-selection rules (MCP agdf_inspect applies the same function). The gate-check
+  // --status-card/--approval-envelope flags keep their historical CLI tolerance and are not passed here.
+  validateReadSelection({ operation: options.target, allActive: options.allActive, contractModule: options.contractModule });
   if (options.target === "run-create" && (!options.runId || options.allActive)) {
     throw new Error("run-create requires --run and rejects --all-active");
   }
+  if (options.target === "run-recovery") {
+    if (!options.runId || !["inspect", "preview", "apply"].includes(options.recoveryAction)) {
+      throw new Error("run-recovery requires --run and --action inspect, preview or apply");
+    }
+    if (options.recoveryAction === "apply" && (!options.recoveryPreviewId || !options.recoveryConfirmation)) {
+      throw new Error("run-recovery apply requires --preview-id and --recovery-confirmation");
+    }
+    if (options.recoveryAction !== "apply" && (options.recoveryPreviewId || options.recoveryConfirmation)) {
+      throw new Error("--preview-id and --recovery-confirmation are supported only by run-recovery apply");
+    }
+  } else if (options.recoveryAction || options.recoveryPreviewId || options.recoveryConfirmation) {
+    throw new Error("--action, --preview-id and --recovery-confirmation are supported only by run-recovery");
+  }
+  if ((options.gate && !["run-approve", "run-present"].includes(options.target)
+      && !(options.target === "run-step" && options.runStep === "artefact")) || (options.response !== undefined && options.target !== "run-approve")) {
+    throw new Error("--gate is supported by run-present/run-approve; --response only by run-approve");
+  }
+  if (options.revisionId && !["run-update", "run-revise", "run-approve", "run-step", "run-present", "skill-dispatch"].includes(options.target)) {
+    throw new Error("--revision is supported only by run-update, run-revise, run-present, run-approve, run-step and skill-dispatch");
+  }
+  if ((options.runStep || Object.keys(options.stepFields ?? {}).length) && options.target !== "run-step"
+      && !(options.target === "run-revise" && ["preview", "apply"].includes(options.revisionMode)
+        && !options.runStep && Object.keys(options.stepFields).every(key => key === "evidence"))
+      && !(options.target === 'mcp' && (options.retireCockpit || options.restoreCockpit)
+        && !options.runStep && Object.keys(options.stepFields).every(key => key === 'evidence'))) {
+    throw new Error("--step and step fields are supported only by run-step");
+  }
+  if (options.target === "run-step" && (!options.runId || !options.revisionId || !options.runStep)) {
+    throw new Error("run-step requires --run, --revision and --step");
+  }
+  if (options.target === "run-step" && options.runStep === "artefact"
+      && (!["PRD", "SD", "TP", "QA"].includes(options.gate) || !options.stepFields?.evidence
+        || Object.keys(options.stepFields).some(key => key !== "evidence"))) throw new Error("run-step artefact requires --gate PRD|SD|TP|QA and --evidence <recording-input.json>; other step fields are rejected");
+  if (options.target === "run-update" && (!options.runId || !options.revisionId || options.gate || options.response !== undefined)) {
+    throw new Error("run-update requires --run and --revision and rejects --gate and --response");
+  }
+  if (options.target === "run-revise" && (!options.runId || !options.revisionId || options.gate || options.response !== undefined)) {
+    throw new Error("run-revise requires --run and --revision and rejects --gate and --response");
+  }
+  if (options.target === "run-revise") {
+    const mode = options.revisionMode;
+    if (!mode && (options.sourceGate !== undefined || options.previewDigest !== undefined)) throw new Error("Late revision requires an explicit mode");
+    if (mode && !["preview", "apply", "inspect", "recover"].includes(mode)) throw new Error("Unsupported source revision mode");
+    if (mode && !options.operationId) throw new Error("Source revision requires --operation");
+    if (["preview", "apply"].includes(mode) && (!["UR", "PRD", "SD", "TP"].includes(options.sourceGate) || !options.stepFields?.evidence)) throw new Error("Source revision preview/apply requires --source-gate and --evidence");
+    if (mode === "apply" && !/^sha256:[a-f0-9]{64}$/u.test(options.previewDigest ?? "")) throw new Error("Source revision apply requires its --preview-digest");
+    if (mode !== "apply" && options.previewDigest !== undefined) throw new Error("--preview-digest requires --apply");
+    if (["inspect", "recover"].includes(mode) && (options.sourceGate !== undefined || Object.keys(options.stepFields ?? {}).length)) throw new Error("Source revision inspect/recover accepts only run, revision and operation identity");
+    if (mode && !options.dirExplicit) throw new Error("Source revision requires an explicit --dir target");
+  }
+  if (options.target === "run-approve" && (!options.runId || !options.gate || !options.revisionId || options.response === undefined)) {
+    throw new Error("run-approve requires --run, --gate, --revision and --response");
+  }
   if (options.target === "run-render-legacy" && !options.runId) {
     throw new Error("run-render-legacy requires --run");
   }
@@ -71,12 +217,41 @@ export function validateCommandOptions(options) {
   if (options.target === "disable" && options.surface === "copilot" && options.scope !== "repository") {
     throw new Error("Copilot disable requires explicit --scope repository");
   }
+  if (options.target === "disable" && options.setupRequest === "full" && !options.dirExplicit) {
+    throw new Error("disable --with-mcp requires an explicit --dir target");
+  }
+  if (options.target === "disable" && options.setupRequest === "full" && options.scope !== "repository") {
+    throw new Error("disable --with-mcp requires explicit --scope repository");
+  }
+  if (options.target === "uninstall" && options.setupRequest === "full") {
+    if (!options.mcpScope) throw new Error("uninstall --with-mcp requires --mcp-scope project or user");
+    if (!options.dirExplicit || !options.dirInputAbsolute) throw new Error("uninstall --with-mcp requires an explicit absolute --dir target");
+  }
   if (options.runtimeChecksDecision && !["codex", "claude", "copilot", "opencode"].includes(options.target)) {
     throw new Error("--runtime-checks is supported only by codex, claude, copilot and opencode installation commands");
   }
+  if (options.acceptPluginCapabilities && (options.target !== "codex"
+      || (options.runtimeChecksDecision && options.runtimeChecksDecision !== "enable"))) {
+    throw new Error("--accept-plugin-capabilities requires codex installation and cannot be combined with manual or cancel.");
+  }
   if (options.target === "runtime-checks" && !["codex", "claude", "copilot", "opencode"].includes(options.surface)) {
     throw new Error("runtime-checks requires --surface codex, claude, copilot or opencode");
   }
+  if (options.target === "mcp") {
+    if (!["status", "enable", "disable"].includes(options.mcpAction)) throw new Error("mcp requires status, enable or disable");
+    if (!["codex", "claude", "copilot", "opencode"].includes(options.surface) || !options.surfaceExplicit) {
+      throw new Error("mcp requires --surface codex, claude, copilot or opencode");
+    }
+    if (!options.dirExplicit) throw new Error("mcp requires an explicit --dir target");
+    if (options.scope && !["project", "user"].includes(options.scope)) throw new Error("mcp --scope must be project or user");
+  }
+  if (options.retireCockpit !== undefined || options.restoreCockpit !== undefined) {
+    if (options.target !== 'mcp' || options.surface !== 'codex' || options.scope !== 'project'
+      || options.retireCockpit && options.restoreCockpit
+      || !['agdf-cockpit', 'agdf-cockpit-local'].includes(options.retireCockpit ?? options.restoreCockpit)
+      || (options.retireCockpit ? options.mcpAction !== 'disable' : options.mcpAction !== 'enable')
+      || !options.stepFields?.evidence) throw new Error('Cockpit transition requires Codex project scope, matching enable/disable and exact --evidence');
+  }
   if (options.approvalEnvelope && options.target !== "gate-check") throw new Error("--approval-envelope is supported only by gate-check");
   if (options.approvalEnvelope && (options.json || options.statusCard || options.allActive)) {
     throw new Error("--approval-envelope cannot be combined with --json, --status-card or --all-active");
@@ -115,7 +290,13 @@ Backward-compatible create-agdf usage:
 ${usageLines("legacy", "npx --yes create-agdf@latest ")}
 
 Options:
-  --dir <path>   Write files into a specific directory. With opencode, use this as the OpenCode config directory.
+  --dir <path>   Select an explicit target directory. OpenCode installation uses it as its config directory; MCP requires an absolute repository target.
+  --with-mcp     Install the plugin and explicitly enable AGDF MCP for the selected target.
+  --plugin-only  Install or update only the plugin and leave MCP unchanged.
+  --control-dir <absolute-repository>
+                 Inspect existing .agdf state separately from host configuration; enables safe migrations.
+  --control-migration <inspect|safe>
+                 Inspect without changes, or migrate eligible unsealed runs in the explicit repository.
   --force        Overwrite existing generated files
   --language <tag>
                  Set AGDF chat and artefact language. Defaults to detected system locale.
@@ -124,17 +305,71 @@ Options:
   --verbose       Print captured host command output and generated-file details
   --status-card  Print compact gate-check status-card output for interactive use
   --approval-envelope
-                 Print the deterministic ready-gate cards and exact-text request
+                 Preview the current gate artefact; run-present is required before asking for approval
   --run <run_id> Select one canonical run
+  --action <inspect|preview|apply>
+                 run-recovery operation; apply also requires its preview ID and exact recovery confirmation
+  --preview-id <uuid>
+                 Bind run-recovery apply to one stored read-only preview
+  --recovery-confirmation <text>
+                 Exact confirmation printed by run-recovery preview
+  --module <runtime-contract-module>
+                 Runtime-contract module for contract, for example gate-transition
+  --step <ur|route|review|evidence|closeout|artefact>
+                 Standard transition for run-step. artefact --gate PRD|SD|TP|QA --evidence <recording-input.json>;
+                 other step fields: ur --title; route --route
+                 <quick_task|verified_change|structured_slice|structured_delivery|block> --reason
+                 --evidence; review --decision <pass|revise|block> --evidence [--source]; evidence
+                 --evidence [--source --covers]; closeout --result --evidence --risk --next
+  --revision <revision_id>
+                 Expected current run revision for run-update, run-revise, run-present, run-approve and run-step
+  --gate <UR|PRD|SD|TP|QA|UAT>
+                 Gate to present or approve
+  --response <text>
+                 The user's verbatim reply to the presented gate question
+  --target-source ${TASK_TARGET_SOURCE_GRAMMAR}
+                 Classify the semantic source for target-check
+  --primary-target <absolute-path>
+                 Supply exactly one target for target-check; cwd is never implied
+  --working-directory <absolute-path>
+                 Report execution context without granting target authority
+  --skill <skill-id>
+                 Select one canonical skill for skill-dispatch
+  --intake-mode <new|resume>  Explicit new scope or bound intake recovery; requires --intake and --run
+  --ur-action revise  Explicit unapproved UR revision; requires revision-bound resume intake
+  --prd-action revise Explicit unapproved PRD revision; requires revision-bound resume intake
+  --sd-action revise Explicit unapproved SD revision; requires revision-bound resume intake
+  --tp-action revise Explicit unapproved TP revision; requires revision-bound resume intake
+  --continue-delivery  Bound internal continuation; excludes intake and read-only status
+  --preview|--apply|--inspect|--recover
+                 Explicit run-revise mode; no mode keeps the early PRD revision path
+  --source-gate <UR|PRD|SD|TP>
+                 Earliest changed approved source in a reviewed late proposal
+  --preview-digest <sha256>
+                 Exact read-only late revision preview required by --apply
+  --operation <uuid>     Explicit idempotent approval or source revision command identity
+  --assurance <lane>     Only cooperative_local is supported; no independent human proof
+  --presentation <uuid>  Previously prepared run-present binding required for run-approve
+  --intake       Declare the governed delivery intake (delivery.start) for a gate-check skill-dispatch
+  --target-candidate <absolute-path>
+                 Repeat to expose competing plausible targets
+  --evidence-source <value>
+                 Repeat to report non-authorizing evidence sources
+  --target-changed
+                 Mark an explicit replacement of a previously confirmed target
   --all-active   Evaluate every active run (doctor and delivery-map only)
   --surface <codex|claude|copilot|opencode|generic>
-                 Declare the active Delivery Path Search surface
-  --scope <repository|global>
-                 Select the lifecycle mutation scope
+                 Declare the selected coding-agent surface
+  --scope <repository|global|project|user>
+                 Select the lifecycle mutation scope. MCP defaults to project.
+  --mcp-scope <project|user>
+                 Select the MCP scope for an explicitly coupled global uninstall.
   --confirm      Apply a previously previewed global uninstall plan
   --shared       Apply Copilot repository disable through shared .github/copilot/settings.json
   --runtime-checks <enable|manual|cancel>
                  Make the installation-time automatic-check decision explicitly; no TTY defaults to manual
+  --accept-plugin-capabilities
+                 Codex install: consent to the AGDF hook and approve only agdf_dispatch. Native hook trust remains separate.
   --fixture <path>
                  Use deterministic evaluator/candidate fixtures instead of a live evaluator
   --persist      Persist the redacted Delivery Path Search result under the current scope

package/lib/cli/contract-command.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import process from "node:process";
+import { generatedRoot, pluginDefinition } from "./runtime-context.js";
+import { createHash } from "node:crypto";
+
+export { runtimeContractModules } from "#agdf-core/resources/contracts.js";
+import { resources } from "../runtime/control-context.js";
+import { readSkillRuntimeContracts as readOwnedSkillContracts } from "#agdf-core/resources/contracts.js";
+export function readSkillRuntimeContracts(skill, { definition = resources.pluginDefinition, packageGeneratedRoot = resources.generatedRoot } = {}) {
+  if (packageGeneratedRoot !== resources.generatedRoot) throw new Error("runtime_contracts_unavailable");
+  return readOwnedSkillContracts(skill, { context: { ...resources, pluginDefinition: definition } });
+}
+import { runtimeContractModules, readRuntimeContract as readOwnedContract } from "#agdf-core/resources/contracts.js";
+export function readRuntimeContract(module, { pluginRoot = process.env.AGDF_DISPATCH_PLUGIN_ROOT, definition = pluginDefinition, packageGeneratedRoot = resources.generatedRoot } = {}) {
+  const modules = runtimeContractModules(definition);
+  if (!modules.includes(module)) return Object.freeze({ ok: false, reason: "module_unknown", modules });
+  if (pluginRoot) for (const root of [join(pluginRoot, "meta", "contracts"), join(pluginRoot, "skills", "contracts")]) {
+    const path = join(root, `${module}.md`);
+    if (existsSync(path)) return Object.freeze({ ok: true, module, path, content: readFileSync(path, "utf8") });
+  }
+  if (packageGeneratedRoot !== resources.generatedRoot) return Object.freeze({ ok: false, reason: "module_unavailable", modules });
+  return readOwnedContract(module, { context: resources });
+}

package/lib/cli/control-maintenance-command.js

@@ -0,0 +1,44 @@
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+import { runControlMaintenance } from "../control-maintenance/service.js";
+import { maintenanceResult, maintenanceExitCode } from "#agdf-core/control-maintenance/contract.js";
+import { renderMaintenanceResult } from "#agdf-core/control-maintenance/presentation.js";
+import { selectControlMaintenance, selectControlMigration, selectControlRepair } from "../control-maintenance/interaction.js";
+
+export async function executeControlMaintenance(options, io = console, adapters = {}) {
+  const input = adapters.input ?? process.stdin;
+  const output = adapters.output ?? process.stdout;
+  if (options.guided && (options.json || !(adapters.interactive ?? (input.isTTY && output.isTTY)))) {
+    io.error("AGDF_MAINTENANCE_INTERACTION_REQUIRED: --guided requires interactive input and cannot be combined with --json.");
+    return 1;
+  }
+  let prompt;
+  let closed = false;
+  const language = options.language?.chat_language ?? "en";
+  const write = (value) => io.log(value);
+  const readChoice = adapters.readChoice ?? (({ prompt: question }) => new Promise((resolve, reject) => {
+    if (closed) { reject(new Error("EOF")); return; }
+    const onClose = () => reject(new Error("EOF"));
+    prompt.once("close", onClose);
+    prompt.question(question).then(resolve, reject).finally(() => prompt.removeListener("close", onClose));
+  }));
+  const interaction = { language, write, readChoice };
+  try {
+    if (options.guided && !adapters.readChoice) {
+      prompt = createInterface({ input, output });
+      prompt.on("close", () => { closed = true; });
+    }
+    const report = await runControlMaintenance(options.dir, {
+      guided: options.guided,
+      chooseMaintenance: (control) => selectControlMaintenance(control, interaction),
+      confirmMigration: (plan) => selectControlMigration(plan, interaction),
+      confirmRepair: (plan) => selectControlRepair(plan, { ...interaction, phase: "plan" }),
+    });
+    io.log(options.json ? JSON.stringify(report, null, 2) : renderMaintenanceResult(report, { language, details: options.details }));
+    return maintenanceExitCode(report);
+  } catch (error) {
+    const report = maintenanceResult(options.dir, null, { operation: options.guided ? "guided" : "inspect", diagnostic: String(error.code ?? error.message) });
+    io.log(options.json ? JSON.stringify(report, null, 2) : renderMaintenanceResult(report, { language }));
+    return 1;
+  } finally { prompt?.close(); }
+}

package/lib/cli/delivery-path-search-command.js

@@ -1,15 +1,15 @@
 import { readFileSync } from 'node:fs';
-import { searchInputFromControl } from '../delivery-path-search/state-adapter.js';
-import { runDeliveryPathSearch } from '../delivery-path-search/search-engine.js';
-import { codexEvaluator } from '../delivery-path-search/evaluators/codex.js';
-import { claudeEvaluator } from '../delivery-path-search/evaluators/claude.js';
-import { openCodeEvaluator, preflightOpenCodeEvaluator } from '../delivery-path-search/evaluators/opencode.js';
-import { fixtureEvaluator } from '../delivery-path-search/evaluators/protocol.js';
-import { codexGenerator } from '../delivery-path-search/generators/codex.js';
-import { claudeGenerator } from '../delivery-path-search/generators/claude.js';
-import { fixtureGenerator } from '../delivery-path-search/generators/protocol.js';
-import { enforcementForSurface } from '../delivery-path-search/surfaces/capabilities.js';
-import { persistSearchResult } from '../delivery-path-search/persistence.js';
+import { searchInputFromControl } from "#agdf-core/delivery-path-search/state-adapter.js";
+import { runDeliveryPathSearch } from "#agdf-core/delivery-path-search/search-engine.js";
+import { codexEvaluator } from "../delivery-path-search/evaluators/codex.js";
+import { claudeEvaluator } from "../delivery-path-search/evaluators/claude.js";
+import { openCodeEvaluator, preflightOpenCodeEvaluator } from "../delivery-path-search/evaluators/opencode.js";
+import { fixtureEvaluator } from "../delivery-path-search/evaluators/protocol.js";
+import { codexGenerator } from "../delivery-path-search/generators/codex.js";
+import { claudeGenerator } from "../delivery-path-search/generators/claude.js";
+import { fixtureGenerator } from "../delivery-path-search/generators/protocol.js";
+import { enforcementForSurface } from "../delivery-path-search/surfaces/capabilities.js";
+import { persistSearchResult } from "#agdf-core/delivery-path-search/persistence.js";
 
 function unavailableOpenCodeResult({ options, preflight, input = null, error = null }) {
   const surface = options.surface ?? "opencode";