create-agdf 0.10.0 → 0.10.2

package/generated/plugins/agdf/skills/brownfield-analysis/SKILL.md

@@ -37,7 +37,7 @@ Do not mix both modes silently. Name the active mode in the output.
 
 ## Rules
 1. Brownfield first: understand the existing codebase before PRD/SD decisions when existing-system impact is possible, and again before implementation.
-2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
+2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen. Persist the completed review and its decision, scope reason, evidence and required next gate in the same internal operation; mark the review `done` only after both the artefact and canonical run projection are complete. An interrupted, incomplete or legacy record stays at fail-closed `Mode/Slice Decision` recovery without another user approval.
 3. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
 4. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
 5. No silent parallel structures.

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

@@ -35,16 +35,17 @@ Skip for routine questions, obvious local fixes and approved implementation with
 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:
+4. Resolve the exact-version surface-local validator using the same ownership rules as `gate-check`. Do not search `PATH`, query a registry, install a package or invoke `npx ...@latest` during routine planning. If no owned or explicitly configured exact-version validator is available, report `machine_validation: unavailable` or `machine_validation: external_required` and stop the machine-evaluated search.
+5. Invoke the shared CLI runtime:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search --surface <surface> --json
+node <surface-local-agdf> delivery-path-search --surface <surface> --json
 ```
 
 Optional AI-native candidate generation is explicit:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search \
+node <surface-local-agdf> delivery-path-search \
   --surface codex \
   --generate-candidates \
   --json
@@ -52,9 +53,9 @@ npx --yes @agdf/cli@latest delivery-path-search \
 
 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.
+6. Treat facts, repository evidence, assumptions and model judgements separately.
+7. Return exactly one recommendation or `no_safe_recommendation`.
+8. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
 
 ## Enforcement
 

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -44,17 +44,23 @@ If required control files are missing, do not automatically create a full `.agdf
 The default first action is to draft the minimal UR in the response and request `Approval: UR`.
 Use `init` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
 
-Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, when CI or PR evidence is needed, when deterministic ready-gate rendering is required, or when a repository-local automation needs JSON output. Prefer an already installed `agdf` executable; use registry-resolved `npx ...@latest` only for bootstrap, installation, explicit refresh or when no local executable exists:
+Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, when CI or PR evidence is needed, when deterministic ready-gate rendering is required, or when a repository-local automation needs JSON output. Resolve the version-matched validator owned by the active surface first: `<plugin-root>/runtime/agdf-local.js` for Codex or Claude, or `<opencode-config>/agdf/bin/agdf-local.js` for OpenCode. Run its `--resolve-only --json` probe before treating its output as machine evidence. An explicitly configured absolute `AGDF_VALIDATOR_PATH` is the only secondary local candidate and must match the active AGDF version.
+
+Routine validation uses that resolved local entrypoint:
 
 ```bash
-npx --yes @agdf/cli@latest init
-npx --yes @agdf/cli@latest doctor --json
-npx --yes @agdf/cli@latest gate-check --json
-npx --yes @agdf/cli@latest delivery-map --json
+node <surface-local-agdf> doctor --json
+node <surface-local-agdf> gate-check --json
+node <surface-local-agdf> delivery-map --json
 ```
 
-For repeated local checks, use `agdf doctor --json`, `agdf gate-check --json` or
-`agdf gate-check --approval-envelope`. The last command prints the validated
+If no exact-version local validator exists, continue through agent-native inspection where permitted
+and state `machine_validation: unavailable` or `external_required`; do not automatically invoke
+`npx`, install a package or contact the registry. Registry-resolved commands are reserved for an
+explicit bootstrap, installation, repair or refresh requested as a lifecycle action.
+
+For repeated local checks, use the resolved entrypoint with `doctor --json`, `gate-check --json` or
+`gate-check --approval-envelope`. The last command prints the validated
 two-card exact-text interaction; JSON exposes the same `approval_presentation`
 for a native-capable adapter.
 
@@ -65,93 +71,24 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 
 ## Native Interaction Path
 
-Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission`, `gate_approval`, `blocked` or `status` before selecting a host control.
-
-Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
-
-For a fresh request classified as read-only with no required run decision, emit the locale pack's
-`primary.readOnlyOrientationDescription` sentence once before the findings. This path creates no run, persists
-nothing, requests no approval and reuses the existing status projection. Do not repeat the sentence
-during the same request.
-
-For a ready `gate_approval`:
-
-1. Resolve exactly one selected run and evaluate the current gate.
-2. Confirm the required durable artefact is present and ready before presenting a question.
-3. Consume the validated canonical `approval_presentation` for the same selected run, gate and revision. Do not compose or rewrite headings, fields, card order, locale copy or Markdown in the model.
-4. Emit its complete `run_status_card` block first and `gate_transition_card` block second in one immediately preceding assistant message. The first heading is neutral; the five status fields are selected run, readiness, current gate, human-readable required decision and a neutral approve/revise/decline instruction. The exact approval value appears only in the transition card across these two blocks.
-5. Never put either card only into the question, button description or hidden tool context. Do not invoke a native question until both rendered blocks are visible.
-6. If the projection is absent or invalid, render no partial card and invoke no native control. Re-evaluate the gate. Use only the exact-text request when the same gate is still ready and its canonical value is independently valid; otherwise report the non-ready reason and request no decision.
-7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
-8. Ask exactly one question that names the selected `run_id` and `current_gate`.
-9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
-10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution and can transport `exact_option_value` or `separate_label_and_value`; never invoke a `decorated_label_only` adapter. Otherwise request the same exact approval in concise text.
-11. Render both supplied cards once in that single complete assistant message. Never merge, reverse, omit, duplicate or reconstruct them; the decision heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
-12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
-13. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
-14. Persist accepted input only through the existing control-state workflow.
-
-Before projecting a ready gate, evaluate adapter callability, deliberate wait safety and canonical
-approval-value transport. Expose `native_attempt_required: true` only when that preflight proves
-`exact_option_value` or `separate_label_and_value` transport with safe deliberate waiting. Decorated-only,
-missing, conflicting or unknown capability exposes false and `unavailable_before_invocation`; unsafe
-waiting exposes false and `unsafe_to_wait`. In both cases use exact text without invoking the adapter.
-A hook, permission result or session context message cannot replace an eligible attempt or supply its answer.
-
-Before composing the question, resolve the configured chat locale from `.agdf/control/config.json` through `plugin/meta/agdf-interaction-locales.json`: exact complete pack, language subtag, then English fallback. German and English are initial packs, not a closed language list. Keep `Approval: <GateName>` exactly unchanged in every language, and do not mix presentation languages within one interaction. Labels and descriptions use the same resolved locale; host-owned UI chrome remains host-owned and may use a different language.
-
-The canonical renderer resolves the complete locale pack. The initial German pack includes `Bereit für deine Entscheidung`, `Jetzt freigeben` and `Danach`; the initial English pack includes `Ready for your decision`, `Approve now` and `Next`. Verify that the supplied blocks use one locale and a neutral decision heading while leaving the exact gate identifier and approval value unchanged. Do not model-edit the supplied Markdown.
-
-The primary option is derived exactly as `Approval: <GateName>` from the evaluated current gate; only explanatory copy and non-authoritative outcome labels are localized. Concrete localized copy belongs to the user-facing interaction layer or the approved delivery artefact, not to English runtime rules.
-
-Make exactly one native-attempt for the eligible ready gate. If the host does not render,
-apply or safely return the native question on that attempt, switch immediately
-to the exact textual approval. Do not ask the user to request the buttons again
-and do not create a retry loop or simulated control.
-
-State the outcome visibly: `presented`, `unavailable_before_invocation`,
-`attempted_not_applied` or `unsafe_to_wait`. For every fallback, say in the
-configured locale why a native control was not usable, show the exact approval
-value and confirm that authority is unchanged. This transient outcome is not
-approval evidence. A new explicit user request may reopen the unchanged decision
-only after fresh run/gate/artefact revalidation; never retry automatically.
-
-Surface behavior:
-
-- Codex: invoke the native short-question/request-user-input control only when preflight proves `exact_option_value` or `separate_label_and_value`, and omit auto-resolution. The canonical `decorated_label_only` capability must use exact text without invoking the adapter. `Approval: <GateName> (Recommended)` is never a valid option or approval.
-- Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
-- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
-- GitHub Copilot: the current repository-instruction surface has no conforming native approval adapter. Transmit the canonical rendered cards followed by the exact-text request; never claim or simulate a native control. Copilot tool confirmations, plan interactions and repository permissions remain separate.
-- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
-
-Localized labels such as `Überarbeiten`/`Revise`, `Ablehnen`/`Decline` and `Abbrechen`/`Cancel` are presentation mappings to stable non-approval outcomes only. A label, description, option position or recommendation never authorizes a gate. Host-provided free-text or `Überspringen`/`Skip` actions never advance an AGDF gate.
-
-A free-form response must still exactly match the current gate's approval formula after revalidation. Keep `decline`, `cancel`, `no_response`, `timeout`, `empty`, `invalid` and `stale` distinct; none advances the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
-
-Every primary chat card shows the selected run's `UR`, `PRD`, `SD` and `TP` in that order. Render an existing canonical path as a readable link and a missing artefact as localized non-link text; never guess paths. Resolve the human run title from current artefact heading, approved UR heading, Objective, then normalized `run_id`. Status, blocked, clarification and internal-step interactions use the same locale and artefact projection but do not show approval buttons. Keep raw process keys and machine status values in JSON or audit detail.
-
-### Breadcrumb Rendering
-
-The compact human Run Status Card includes a single-line path-derived breadcrumb showing the user's position in the delivery journey. Derive it from the Mode/Slice Decision and the Approvals table — not a fixed template. Use `✓` for fulfilled, `●` for current, `○` for open, separated by ` · `. Non-applicable gates are absent. See the Runtime Contract §Breadcrumb for the path templates and the derived `breadcrumb` array.
-
-### Post-Acceptance Transition Narration
-
-After each accepted gate approval is persisted, emit exactly one narration line using the template `<what was satisfied> → <what the agent does next internally> → <user action: yes/no>`. This generalizes the existing TP pattern (step 7 above) to every gate advancement. The narration is post-acceptance only: it never appears in the same message as the Gate Transition Card, never contains the `Approval:` value, and never repeats the decision's effect. For internal steps (Brownfield Review, Brownfield Analysis), state what the agent does next and that no user action is required, without exposing `next_user_gate: none` or asking for a second approval. See the Runtime Contract §Post-Acceptance Transition Narration for the full contract.
-
-### Internal-State Collapse in the Human Card
-
-When rendering the compact human Run Status Card, collapse internal sub-states (`verified_change` sub-states, `context_graph_required_action`, `multi_scope_state`) to stable human labels. `escalated`, `open_gap` and `blocked` remain explicitly visible. The full machine/audit projection retains all raw values unchanged. See the Runtime Contract §Internal-State Collapse for the complete mapping table.
-
-### On-Demand "Why?" Response
+`../../meta/contracts/interaction.md` is the complete normative owner for interaction kinds, locale,
+canonical values, presentation order, adapter capability, deliberate waiting, native/fallback
+behavior, transient outcomes, permissions and post-response validation. Load and apply that contract;
+do not restate or infer a surface matrix in this skill.
 
-When the user asks "why?" or "Warum?" at any gate or internal step, respond with a `status` interaction (not `gate_approval`):
+This skill owns only these operational responsibilities:
 
-1. Pull the curated rationale from `gateRationale()` in the resolved locale.
-2. Compose one fulfilled line from the selected run's Approvals table and artefact status.
-3. Compose one protects-against line from the gate's rationale and the existing `primary.actions` copy.
-4. Do not show approval controls. Do not advance any gate. Do not merge with the approval envelope.
+1. Select exactly one run and evaluate its current gate.
+2. Confirm that the required durable artefact is present and ready.
+3. Consume the canonical `approval_presentation` verbatim for the selected run, gate and revision.
+4. Present that projection and obtain deliberate input through the contract-selected native or exact-text path.
+5. Revalidate the same run, gate and revision immediately after the response and before persistence.
+6. Persist only a currently valid exact approval through the existing control-state workflow.
 
-The response is deterministic: same gate, same question, same answer. The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no "why" option is added. See the Runtime Contract §Gate-Rationale-Registry and §On-Demand "Why?" Interaction for the full contract.
+For status, blocked, read-only or rationale interactions, consume the same canonical projection and
+locale contract without asking for approval. Internal process steps remain distinct from user
+decisions. If the projection, adapter evidence or revalidation is missing, follow the contract's
+fail-closed outcome and leave authority unchanged.
 
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.

package/lib/cli/application.js

@@ -6,18 +6,6 @@ import {
   resolveRuns,
   writeLegacyProjection,
 } from "../control-state/index.js";
-import {
-  buildStatusCard,
-  evaluateGateCheck,
-  printApprovalEnvelope,
-  postApprovalTransition,
-  printGateCheckReport,
-} from "../control-evaluation/gate-check.js";
-import {
-  evaluateDeliveryMap,
-  printDeliveryMapReport,
-} from "../control-evaluation/delivery-map.js";
-import { evaluateDoctor, printDoctorReport } from "../control-evaluation/doctor.js";
 import {
   defaultOpenCodeConfigDir,
   evaluateOpenCodeStatus,
@@ -39,23 +27,23 @@ import {
 import { printGeneralStatus, printLifecycleResult } from "../lifecycle/presentation.js";
 import { createLifecycleResult, globalInstallRestartAction, lifecycleFailure } from "../lifecycle/result.js";
 import { evaluateGeneralStatus } from "../lifecycle/status.js";
-import { agdfFragmentPath, generatedFilesForTarget, openCodeConfigFragmentPath } from "../scaffold/plan.js";
+import { agdfFragmentPath, generatedFilesForTarget } from "../scaffold/plan.js";
 import { printNextSteps } from "../scaffold/presentation.js";
-import { assertGeneratedWritePlan, removeOwnedLegacyOpenCodeAgents, writeGeneratedFile } from "../scaffold/write.js";
+import { assertGeneratedWritePlan, writeGeneratedFile } from "../scaffold/write.js";
 import { renderUsage, resolveCommand, validateCommandOptions } from "./command-registry.js";
-import { executeDeliveryPathSearch } from "./delivery-path-search-command.js";
 import { CliUsageError, parseArgs } from "./parse-args.js";
+import { pluginDefinition } from "./runtime-context.js";
+import { createValidationHandlers } from "./validation-handlers.js";
 
-const deliveryMapDependencies = Object.freeze({
-  evaluateDoctor,
-  buildStatusCard,
-  postApprovalTransition,
-});
-
-function createHandlers({ io, env, exec }) {
-  const installerAdapters = exec ? { exec, io } : { io };
+function createHandlers({ io, env, exec, prepare }) {
+  const installerAdapters = {
+    ...(exec ? { exec } : {}),
+    ...(prepare ? { prepare } : {}),
+    ...(env.AGDF_DATA_DIR ? { dataRoot: env.AGDF_DATA_DIR } : {}),
+  };
   const scaffoldHandler = (options) => runScaffold(options, io);
   return new Map([
+    ...createValidationHandlers(io),
     ["codex-repo", scaffoldHandler],
     ["copilot", scaffoldHandler],
     ["opencode-repo", scaffoldHandler],
@@ -77,37 +65,6 @@ function createHandlers({ io, env, exec }) {
       io.log(output);
       return 0;
     }],
-    ["doctor", (options) => {
-      const report = evaluateDoctor(options.dir, options);
-      printDoctorReport(report, options.json, io);
-      return report.status === "block" ? 2 : 0;
-    }],
-    ["gate-check", (options) => {
-      const report = evaluateGateCheck(options.dir, options);
-      if (options.approvalEnvelope) {
-        const output = printApprovalEnvelope(report, {
-          io,
-          reEvaluate: () => evaluateGateCheck(options.dir, options),
-        });
-        return output.status === "blocked" ? 2 : 0;
-      }
-      printGateCheckReport(report, options.json, options.statusCard, io);
-      return report.status === "blocked" ? 2 : 0;
-    }],
-    ["delivery-map", (options) => {
-      const report = evaluateDeliveryMap(options.dir, options, deliveryMapDependencies);
-      printDeliveryMapReport(report, options.json, io);
-      return report.status === "block" ? 2 : 0;
-    }],
-    ["delivery-path-search", async (options) => {
-      try {
-        const result = await executeDeliveryPathSearch(options, io);
-        return result.status === "recommendation" ? 0 : 2;
-      } catch (error) {
-        io.error(`Delivery Path Search failed: ${error.message}`);
-        return 2;
-      }
-    }],
     ["opencode-status", (options) => {
       const configDir = env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir();
       const report = evaluateOpenCodeStatus(options.dir, configDir);
@@ -198,7 +155,7 @@ function runLifecyclePhase(phase, operation) {
 
 function installResult(installed, { restartRequired, nextAction }) {
   return createLifecycleResult({
-    operation: "install",
+    operation: installed.operation ?? "install",
     result: "success",
     surface: installed.surface,
     scope: "global",
@@ -308,7 +265,6 @@ function runUninstall(options, { io, env, exec }) {
 function runScaffold(options, io) {
   const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
   const wroteAgentsFragment = files.some((file) => file.path === agdfFragmentPath);
-  const wroteOpenCodeConfigFragment = files.some((file) => file.path === openCodeConfigFragmentPath);
   let removedOpenCodeAgents = [];
 
   try {
@@ -316,19 +272,25 @@ function runScaffold(options, io) {
     for (const file of files) {
       writeGeneratedFile(options.dir, file.path, file.content, options.force, file.allowOverwrite);
     }
-    if (options.target === "opencode-repo") removedOpenCodeAgents = removeOwnedLegacyOpenCodeAgents(options.dir);
+    // Legacy OpenCode assets are intentionally preserved. A future explicit migration command
+    // may remove only ownership-proven files after its precedence behavior is verified.
   } catch (error) {
     io.error(error.message);
     return 1;
   }
 
-  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
+  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
   return 0;
 }
 
 export async function runCli(argv = process.argv.slice(2), adapters = {}) {
   const io = adapters.io ?? console;
   const env = adapters.env ?? process.env;
+  if (argv.includes("--version")) {
+    const output = { name: "create-agdf", version: pluginDefinition.version };
+    io.log(argv.includes("--json") ? JSON.stringify(output) : output.version);
+    return 0;
+  }
   let parsed;
   try {
     parsed = parseArgs(argv, adapters.parser);
@@ -353,7 +315,7 @@ export async function runCli(argv = process.argv.slice(2), adapters = {}) {
   }
   const command = resolveCommand(options.target);
   if (!command) throw new Error(`No handler is registered for ${options.target}.`);
-  const handler = createHandlers({ io, env, exec: adapters.exec }).get(command.handler);
+  const handler = createHandlers({ io, env, exec: adapters.exec, prepare: adapters.prepare }).get(command.handler);
   if (!handler) throw new Error(`No implementation is registered for ${command.name}.`);
   return await handler(options);
 }

package/lib/cli/command-registry.js

@@ -23,16 +23,16 @@ export const commandRegistry = Object.freeze([
   command("both", { scaffold: [""] }),
   command("init", { preferred: [""], scaffold: [""] }),
   command("config", { scaffold: [" --language de"] }),
-  command("doctor", { preferred: [""], scaffold: [""], legacy: [" --json"] }),
-  command("gate-check", { preferred: [" --approval-envelope", " --json"], scaffold: [""], legacy: [" --json"] }),
-  command("delivery-map", { scaffold: [""] }),
+  command("doctor", { local: [""], scaffold: [""], legacy: [" --json"] }),
+  command("gate-check", { local: [" --approval-envelope", " --json"], scaffold: [""], legacy: [" --json"] }),
+  command("delivery-map", { local: [" --json"], scaffold: [""] }),
   command("delivery-path-search", {
-    preferred: [" --surface codex --json", " --surface claude --json"],
+    local: [" --surface codex --json", " --surface claude --json"],
     scaffold: [" --surface codex", " --surface claude"],
   }),
-  command("run-create", { preferred: [" --run <run_id>"] }),
-  command("run-migrate", { preferred: [" [--run <run_id>]"] }),
-  command("run-render-legacy", { preferred: [" --run <run_id>"] }),
+  command("run-create", { local: [" --run <run_id>"] }),
+  command("run-migrate", { local: [" [--run <run_id>]"] }),
+  command("run-render-legacy", { local: [" --run <run_id>"] }),
 ]);
 
 const commandByName = new Map(commandRegistry.map((entry) => [entry.name, entry]));
@@ -87,13 +87,11 @@ Operating model:
   The CLI validates, renders deterministic gate output and supports automation.
 
 Repeated local validation (after global installation):
-  agdf doctor
-  agdf gate-check --approval-envelope
-  agdf gate-check --json
+${usageLines("local", "agdf ")}
 
 Bootstrap, installation and explicit refresh:
 
-Primary commands:
+Bootstrap and lifecycle commands:
 ${usageLines("preferred", "npx --yes @agdf/cli@latest ")}
 
 Advanced / Compatibility

package/lib/cli/validation-handlers.js

@@ -0,0 +1,45 @@
+import {
+  buildStatusCard,
+  evaluateGateCheck,
+  printApprovalEnvelope,
+  postApprovalTransition,
+  printGateCheckReport,
+} from "../control-evaluation/gate-check.js";
+import { evaluateDeliveryMap, printDeliveryMapReport } from "../control-evaluation/delivery-map.js";
+import { evaluateDoctor, printDoctorReport } from "../control-evaluation/doctor.js";
+import { executeDeliveryPathSearch } from "./delivery-path-search-command.js";
+
+const deliveryMapDependencies = Object.freeze({ evaluateDoctor, buildStatusCard, postApprovalTransition });
+
+export function createValidationHandlers(io = console) {
+  return new Map([
+    ["doctor", (options) => {
+      const report = evaluateDoctor(options.dir, options);
+      printDoctorReport(report, options.json, io);
+      return report.status === "block" ? 2 : 0;
+    }],
+    ["gate-check", (options) => {
+      const report = evaluateGateCheck(options.dir, options);
+      if (options.approvalEnvelope) {
+        const output = printApprovalEnvelope(report, { io, reEvaluate: () => evaluateGateCheck(options.dir, options) });
+        return output.status === "blocked" ? 2 : 0;
+      }
+      printGateCheckReport(report, options.json, options.statusCard, io);
+      return report.status === "blocked" ? 2 : 0;
+    }],
+    ["delivery-map", (options) => {
+      const report = evaluateDeliveryMap(options.dir, options, deliveryMapDependencies);
+      printDeliveryMapReport(report, options.json, io);
+      return report.status === "block" ? 2 : 0;
+    }],
+    ["delivery-path-search", async (options) => {
+      try {
+        const result = await executeDeliveryPathSearch(options, io);
+        return result.status === "recommendation" ? 0 : 2;
+      } catch (error) {
+        io.error(`Delivery Path Search failed: ${error.message}`);
+        return 2;
+      }
+    }],
+  ]);
+}

package/lib/control-evaluation/doctor.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { aggregate, resolveRuns, verifyLegacyProjection } from '../control-state/index.js';
-import { doctorRequiredFiles } from '../scaffold/plan.js';
+import { doctorRequiredFiles } from './required-files.js';
 import { analyzeDeliveryMap } from './delivery-map.js';
 import { evaluateVerifiedChange } from './verified-change.js';
 import { analyzeArtefactRoleConsistency, analyzeDurableGateArtefactConsistency, modeSliceDecision, readRunState } from './run-state.js';

package/lib/control-evaluation/gate-check.js

@@ -28,10 +28,10 @@ export function postApprovalTransition(missingApproval) {
   const transitions = new Map([
     ["Approval: UR", {
       next_gate_after_approval: "Brownfield Review",
-      allowed_after_approval: "Run Brownfield Review and record Mode/Slice Decision before PRD or implementation.",
-      internal_next_step: "Brownfield Review and Mode/Slice Decision",
-      next_user_gate: "PRD",
-      user_action_required: "yes",
+      allowed_after_approval: "Run Brownfield Review and proportional routing as one internal operation; no user action is required now.",
+      internal_next_step: "Brownfield Review and proportional routing",
+      next_user_gate: "none",
+      user_action_required: "no",
     }],
     ["Approval: PRD", {
       next_gate_after_approval: "SD",
@@ -80,7 +80,7 @@ const BREADCRUMB_PATH_TEMPLATES = {
   structured_delivery: ["UR", "PRD", "SD", "TP", "QA", "UAT"],
   structured_slice: ["UR", "PRD", "SD", "TP", "QA", "UAT"],
   verified_change: ["UR", "Verified Change", "OR"],
-  quick_task: ["UR", "Quick Task"],
+  quick_task: ["UR", "Compact Delivery"],
   block: ["UR", "Block"],
   undecided: ["UR"],
 };
@@ -102,11 +102,11 @@ function buildBreadcrumbPath(modeSliceDecision, currentGate, runState) {
       return { gate, status: "open" };
     }
     if (gate === currentGate) return { gate, status: "current" };
-    if ((gate === "Verified Change" || gate === "Quick Task") && currentGate === "OR")
+    if ((gate === "Verified Change" || gate === "Compact Delivery") && currentGate === "OR")
       return { gate, status: "fulfilled" };
     if (gate === "Verified Change" && modeSliceDecision === "verified_change")
       return { gate, status: "current" };
-    if (gate === "Quick Task" && modeSliceDecision === "quick_task")
+    if (gate === "Compact Delivery" && modeSliceDecision === "quick_task")
       return { gate, status: "current" };
     if (gate === "Block" && modeSliceDecision === "block")
       return { gate, status: "current" };

package/lib/control-evaluation/required-files.js

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+
+export const doctorRequiredFiles = Object.freeze([
+  join(".agdf", "control", "AGDF_RUN.md"),
+  join(".agdf", "control", "MASTER_BACKLOG.md"),
+  join(".agdf", "control", "SOT_REGISTRY.md"),
+  join(".agdf", "control", "CONTEXT_GRAPH.md"),
+  join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json"),
+]);