create-agdf 0.9.1 → 0.9.5

package/generated/.agdf/control/templates/MASTER_BACKLOG.md

@@ -15,10 +15,10 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 9. Historical artefacts remain linkable but do not override the current pointer.
 10. If an item is superseded, mark the replacement.
 11. If active work grows beyond roughly ten items, triage the backlog.
-12. `Status` must be one of the human-readable labels `create-agdf/bin/create-agdf.js`'s `backlogStatusLabels` normalizes: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Completed, Superseded, Abandoned. That map is authoritative; this list only mirrors it for readability.
-13. `Artefacts` link labels must be one of `backlogArtefactLabels`: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
+12. `Status` must be one of the human-readable labels normalized by `create-agdf/lib/control-evaluation/shared.js`: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Completed, Superseded, Abandoned. The parser module is authoritative; this list only mirrors it for readability.
+13. `Artefacts` link labels must be one of the labels normalized by the same parser module: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
 14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
-15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/bin/create-agdf.js`'s `backlogScopeLabels` map is authoritative for the two accepted values.
+15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/lib/control-evaluation/shared.js` is authoritative for the accepted values.
 16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
 
 ## Active Backlog

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

@@ -64,6 +64,11 @@ Use the Runtime Contract's Native Interaction Contract to classify every candida
 
 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.

package/generated/.github/skills/agdf-interaction-locales.json

@@ -109,6 +109,24 @@
         "notYetCreated": "not yet created"
       },
       "primary": {
+        "readOnlyOrientationDescription": "Read-only check — no new AGDF run and no approval required.",
+        "lifecycleResult": {
+          "title": "AGDF lifecycle result",
+          "statusTitle": "AGDF status",
+          "result": "Result",
+          "surface": "Surface",
+          "scope": "Installation scope",
+          "version": "AGDF version",
+          "verification": "Verification",
+          "restart": "Restart required",
+          "installation": "Installation",
+          "repository": "Repository",
+          "delivery": "Delivery",
+          "next": "Next action",
+          "yes": "yes",
+          "no": "no",
+          "unknown": "unknown"
+        },
         "status": {
           "open": "open",
           "blocked": "blocked",
@@ -278,6 +296,24 @@
         "notYetCreated": "noch nicht erstellt"
       },
       "primary": {
+        "readOnlyOrientationDescription": "Read-only Prüfung – kein neuer AGDF-Run und keine Freigabe erforderlich.",
+        "lifecycleResult": {
+          "title": "AGDF-Lifecycle-Ergebnis",
+          "statusTitle": "AGDF-Status",
+          "result": "Ergebnis",
+          "surface": "Oberfläche",
+          "scope": "Installationsscope",
+          "version": "AGDF-Version",
+          "verification": "Verifikation",
+          "restart": "Neustart erforderlich",
+          "installation": "Installation",
+          "repository": "Repository",
+          "delivery": "Delivery",
+          "next": "Nächste Aktion",
+          "yes": "ja",
+          "no": "nein",
+          "unknown": "unbekannt"
+        },
         "status": {
           "open": "offen",
           "blocked": "blockiert",

package/generated/.github/skills/contracts/interaction.md

@@ -274,6 +274,15 @@ Surface adapter rules:
 
 Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
 
+### Read-only request orientation
+
+For a newly classified read-only request that does not require a run decision, render the localized
+`primary.readOnlyOrientationDescription` sentence exactly once before the findings. This is a visible
+orientation, not durable state: do not create a run, write control files, request gate approval or
+repeat the sentence later in the same request. Existing-run status inspection remains read-only and
+uses the existing status projection; this branch must not create a second status-card or narration
+owner.
+
 Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
 
 ### Interaction Locale Contract
@@ -367,4 +376,3 @@ Missing input, timeout, cancellation and empty input are not decline. Only
 `approve` backed by the exact revalidated `Approval: <GateName>` value may
 advance a gate. Clarification, blocked, internal-step and status-only
 interactions must not display gate-approval controls.
-

package/generated/.opencode/agdf-interaction-locales.json

@@ -109,6 +109,24 @@
         "notYetCreated": "not yet created"
       },
       "primary": {
+        "readOnlyOrientationDescription": "Read-only check — no new AGDF run and no approval required.",
+        "lifecycleResult": {
+          "title": "AGDF lifecycle result",
+          "statusTitle": "AGDF status",
+          "result": "Result",
+          "surface": "Surface",
+          "scope": "Installation scope",
+          "version": "AGDF version",
+          "verification": "Verification",
+          "restart": "Restart required",
+          "installation": "Installation",
+          "repository": "Repository",
+          "delivery": "Delivery",
+          "next": "Next action",
+          "yes": "yes",
+          "no": "no",
+          "unknown": "unknown"
+        },
         "status": {
           "open": "open",
           "blocked": "blocked",
@@ -278,6 +296,24 @@
         "notYetCreated": "noch nicht erstellt"
       },
       "primary": {
+        "readOnlyOrientationDescription": "Read-only Prüfung – kein neuer AGDF-Run und keine Freigabe erforderlich.",
+        "lifecycleResult": {
+          "title": "AGDF-Lifecycle-Ergebnis",
+          "statusTitle": "AGDF-Status",
+          "result": "Ergebnis",
+          "surface": "Oberfläche",
+          "scope": "Installationsscope",
+          "version": "AGDF-Version",
+          "verification": "Verifikation",
+          "restart": "Neustart erforderlich",
+          "installation": "Installation",
+          "repository": "Repository",
+          "delivery": "Delivery",
+          "next": "Nächste Aktion",
+          "yes": "ja",
+          "no": "nein",
+          "unknown": "unbekannt"
+        },
         "status": {
           "open": "offen",
           "blocked": "blockiert",

package/generated/.opencode/contracts/interaction.md

@@ -274,6 +274,15 @@ Surface adapter rules:
 
 Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
 
+### Read-only request orientation
+
+For a newly classified read-only request that does not require a run decision, render the localized
+`primary.readOnlyOrientationDescription` sentence exactly once before the findings. This is a visible
+orientation, not durable state: do not create a run, write control files, request gate approval or
+repeat the sentence later in the same request. Existing-run status inspection remains read-only and
+uses the existing status projection; this branch must not create a second status-card or narration
+owner.
+
 Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
 
 ### Interaction Locale Contract
@@ -367,4 +376,3 @@ Missing input, timeout, cancellation and empty input are not decline. Only
 `approve` backed by the exact revalidated `Approval: <GateName>` value may
 advance a gate. Clarification, blocked, internal-step and status-only
 interactions must not display gate-approval controls.
-

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

@@ -64,6 +64,11 @@ Use the Runtime Contract's Native Interaction Contract to classify every candida
 
 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.

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.9.1",
+  "version": "0.9.5",
   "description": "Operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/control/templates/MASTER_BACKLOG.md

@@ -15,10 +15,10 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 9. Historical artefacts remain linkable but do not override the current pointer.
 10. If an item is superseded, mark the replacement.
 11. If active work grows beyond roughly ten items, triage the backlog.
-12. `Status` must be one of the human-readable labels `create-agdf/bin/create-agdf.js`'s `backlogStatusLabels` normalizes: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Completed, Superseded, Abandoned. That map is authoritative; this list only mirrors it for readability.
-13. `Artefacts` link labels must be one of `backlogArtefactLabels`: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
+12. `Status` must be one of the human-readable labels normalized by `create-agdf/lib/control-evaluation/shared.js`: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Completed, Superseded, Abandoned. The parser module is authoritative; this list only mirrors it for readability.
+13. `Artefacts` link labels must be one of the labels normalized by the same parser module: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
 14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
-15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/bin/create-agdf.js`'s `backlogScopeLabels` map is authoritative for the two accepted values.
+15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/lib/control-evaluation/shared.js` is authoritative for the accepted values.
 16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
 
 ## Active Backlog

package/generated/plugins/agdf/meta/agdf-interaction-locales.json

@@ -109,6 +109,24 @@
         "notYetCreated": "not yet created"
       },
       "primary": {
+        "readOnlyOrientationDescription": "Read-only check — no new AGDF run and no approval required.",
+        "lifecycleResult": {
+          "title": "AGDF lifecycle result",
+          "statusTitle": "AGDF status",
+          "result": "Result",
+          "surface": "Surface",
+          "scope": "Installation scope",
+          "version": "AGDF version",
+          "verification": "Verification",
+          "restart": "Restart required",
+          "installation": "Installation",
+          "repository": "Repository",
+          "delivery": "Delivery",
+          "next": "Next action",
+          "yes": "yes",
+          "no": "no",
+          "unknown": "unknown"
+        },
         "status": {
           "open": "open",
           "blocked": "blocked",
@@ -278,6 +296,24 @@
         "notYetCreated": "noch nicht erstellt"
       },
       "primary": {
+        "readOnlyOrientationDescription": "Read-only Prüfung – kein neuer AGDF-Run und keine Freigabe erforderlich.",
+        "lifecycleResult": {
+          "title": "AGDF-Lifecycle-Ergebnis",
+          "statusTitle": "AGDF-Status",
+          "result": "Ergebnis",
+          "surface": "Oberfläche",
+          "scope": "Installationsscope",
+          "version": "AGDF-Version",
+          "verification": "Verifikation",
+          "restart": "Neustart erforderlich",
+          "installation": "Installation",
+          "repository": "Repository",
+          "delivery": "Delivery",
+          "next": "Nächste Aktion",
+          "yes": "ja",
+          "no": "nein",
+          "unknown": "unbekannt"
+        },
         "status": {
           "open": "offen",
           "blocked": "blockiert",

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.9.1",
+  "version": "0.9.5",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Operating system for governed AI-assisted delivery.",

package/generated/plugins/agdf/meta/contracts/interaction.md

@@ -274,6 +274,15 @@ Surface adapter rules:
 
 Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
 
+### Read-only request orientation
+
+For a newly classified read-only request that does not require a run decision, render the localized
+`primary.readOnlyOrientationDescription` sentence exactly once before the findings. This is a visible
+orientation, not durable state: do not create a run, write control files, request gate approval or
+repeat the sentence later in the same request. Existing-run status inspection remains read-only and
+uses the existing status projection; this branch must not create a second status-card or narration
+owner.
+
 Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
 
 ### Interaction Locale Contract
@@ -367,4 +376,3 @@ Missing input, timeout, cancellation and empty input are not decline. Only
 `approve` backed by the exact revalidated `Approval: <GateName>` value may
 advance a gate. Clarification, blocked, internal-step and status-only
 interactions must not display gate-approval controls.
-

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

@@ -64,6 +64,11 @@ Use the Runtime Contract's Native Interaction Contract to classify every candida
 
 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.

package/lib/cli/application.js

@@ -0,0 +1,342 @@
+import { join } from "node:path";
+import process from "node:process";
+import {
+  createRun,
+  migrateLegacy,
+  resolveRuns,
+  writeLegacyProjection,
+} from "../control-state/index.js";
+import {
+  buildStatusCard,
+  evaluateGateCheck,
+  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,
+  installOpenCodeGlobalPlugin,
+  installOpenCodeGlobalSurface,
+  printOpenCodeStatus,
+} from "../installers/opencode.js";
+import {
+  installClaudeGlobalPlugin,
+  installCodexGlobalPlugin,
+} from "../installers/plugin-installers.js";
+import {
+  applyLifecyclePlan,
+  planGlobalUninstall,
+  planRepositoryDisable,
+  verifyGlobalUninstall,
+  verifyRepositoryDisabled,
+} from "../lifecycle/operations.js";
+import { printGeneralStatus, printLifecycleResult } from "../lifecycle/presentation.js";
+import { createLifecycleResult, lifecycleFailure } from "../lifecycle/result.js";
+import { evaluateGeneralStatus } from "../lifecycle/status.js";
+import { agdfFragmentPath, generatedFilesForTarget, openCodeConfigFragmentPath } from "../scaffold/plan.js";
+import { printNextSteps } from "../scaffold/presentation.js";
+import { assertGeneratedWritePlan, removeOwnedLegacyOpenCodeAgents, 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";
+
+const deliveryMapDependencies = Object.freeze({
+  evaluateDoctor,
+  buildStatusCard,
+  postApprovalTransition,
+});
+
+function createHandlers({ io, env, exec }) {
+  const installerAdapters = exec ? { exec, io } : { io };
+  const scaffoldHandler = (options) => runScaffold(options, io);
+  return new Map([
+    ["codex-repo", scaffoldHandler],
+    ["copilot", scaffoldHandler],
+    ["opencode-repo", scaffoldHandler],
+    ["both", scaffoldHandler],
+    ["init", scaffoldHandler],
+    ["config", scaffoldHandler],
+    ["run-create", (options) => {
+      io.log(createRun(options.dir, options.runId));
+      return 0;
+    }],
+    ["run-migrate", (options) => {
+      io.log(JSON.stringify(migrateLegacy(options.dir, options.runId), null, 2));
+      return 0;
+    }],
+    ["run-render-legacy", (options) => {
+      const selected = resolveRuns(options.dir, { runIdArg: options.runId });
+      const output = join(options.dir, ".agdf", "control", "AGDF_RUN.md");
+      writeLegacyProjection(output, selected.run.path);
+      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);
+      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);
+      printOpenCodeStatus(report, options.json, io);
+      return report.status === "configured" ? 0 : 1;
+    }],
+    ["status", (options) => {
+      const report = evaluateGeneralStatus(options.dir, {
+        ...options,
+        configDir: env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir(),
+      }, { exec });
+      printGeneralStatus(report, { json: options.json, locale: options.language.chat_language, io });
+      return report.installation.status === "healthy" ? 0 : 1;
+    }],
+    ["disable", (options) => runDisable(options, { io, exec })],
+    ["uninstall", (options) => runUninstall(options, { io, env, exec })],
+    ["codex", (options) => {
+      try {
+        const installed = installCodexGlobalPlugin(installerAdapters);
+        printLifecycleResult(installResult(installed, {
+          restartRequired: true,
+          nextAction: "Restart Codex, then run npx --yes @agdf/cli@latest codex-repo in a repository where AGDF should be active.",
+        }), { json: options.json, locale: options.language.chat_language, io });
+        return 0;
+      } catch (error) {
+        printInstallFailure("codex", error, options, io);
+        return 1;
+      }
+    }],
+    ["claude", (options) => {
+      try {
+        const installed = installClaudeGlobalPlugin(installerAdapters);
+        printLifecycleResult(installResult(installed, {
+          restartRequired: true,
+          nextAction: "Restart Claude Code, then verify the plugin in a new session.",
+        }), { json: options.json, locale: options.language.chat_language, io });
+        return 0;
+      } catch (error) {
+        printInstallFailure("claude", error, options, io);
+        return 1;
+      }
+    }],
+    ["opencode", (options) => {
+      const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
+      try {
+        const result = runLifecyclePhase("plugin_operation", () => installOpenCodeGlobalPlugin(configDir));
+        runLifecyclePhase("global_surface", () => installOpenCodeGlobalSurface(configDir));
+        const report = runLifecyclePhase("verification", () => evaluateOpenCodeStatus(options.dir, configDir, result.transition));
+        const verificationHealthy = report.status === "configured"
+          && report.package.version_status === "current"
+          && report.global_native_surface.complete;
+        printLifecycleResult(createLifecycleResult({
+          operation: result.transition.status === "updated" ? "update" : "install",
+          result: verificationHealthy ? "success" : "partial",
+          surface: "opencode",
+          scope: "global",
+          version: {
+            expected: report.package.expected_version,
+            installed: report.package.installed_version,
+            previous: result.transition.previous_version,
+            status: report.package.version_status === "current" ? "verified" : "unknown",
+            transition: result.transition.status,
+          },
+          verification: { status: verificationHealthy ? "healthy" : "degraded", evidence: [report.global_config.path, report.global_native_surface.path] },
+          restart: { required: true, reason: "host_reload" },
+          next_action: { kind: "restart", text: "Restart OpenCode so it loads the updated global plugin config." },
+        }), { json: options.json, locale: options.language.chat_language, io });
+        return verificationHealthy ? 0 : 1;
+      } catch (error) {
+        printInstallFailure("opencode", error, options, io);
+        return 1;
+      }
+    }],
+  ]);
+}
+
+function runLifecyclePhase(phase, operation) {
+  try {
+    return operation();
+  } catch (error) {
+    if (!error.phase) error.phase = phase;
+    if (!error.evidence) error.evidence = {};
+    throw error;
+  }
+}
+
+function installResult(installed, { restartRequired, nextAction }) {
+  return createLifecycleResult({
+    operation: "install",
+    result: "success",
+    surface: installed.surface,
+    scope: "global",
+    version: { expected: installed.expectedVersion, installed: installed.installedVersion, status: installed.installedVersion ? "verified" : "unknown" },
+    verification: { status: installed.verificationStatus, evidence: installed.evidence },
+    restart: { required: restartRequired, reason: restartRequired ? "host_reload" : "none" },
+    next_action: { kind: restartRequired ? "restart" : "prompt", text: nextAction },
+  });
+}
+
+function printInstallFailure(surface, error, options, io) {
+  const report = lifecycleFailure({
+    operation: "install",
+    surface,
+    scope: "global",
+    phase: error.phase || "plugin_operation",
+    message: error.message,
+    evidence: [error.evidence ?? {}],
+    nextAction: `Resolve the ${error.phase || "plugin operation"} failure and rerun npx --yes @agdf/cli@latest ${surface}.`,
+  });
+  if (options.json) printLifecycleResult(report, { json: true, io });
+  else {
+    io.error(error.message);
+    printLifecycleResult(report, { locale: options.language.chat_language, io });
+  }
+}
+
+function runDisable(options, { io, exec }) {
+  try {
+    const plan = planRepositoryDisable(options.dir, options.surface);
+    const applied = applyLifecyclePlan(plan, exec ? { exec } : {});
+    const verified = applied.status === "success" ? verifyRepositoryDisabled(options.dir) : { status: "failed", evidence: [] };
+    const result = applied.status === "success" && verified.status !== "healthy" ? "failed" : applied.status;
+    const report = createLifecycleResult({
+      operation: "disable",
+      result,
+      surface: options.surface,
+      scope: "repository",
+      verification: { status: verified.status === "healthy" ? "healthy" : "degraded", evidence: [...applied.completed.map((item) => item.path || item.executable), ...verified.evidence] },
+      restart: { required: result === "success", reason: result === "success" ? "host_reload" : "none" },
+      next_action: result === "success"
+        ? { kind: "restart", text: "Restart the host in this repository; global AGDF availability and .agdf/control are retained." }
+        : { kind: "verify", text: "Inspect the reported repository configuration failure before retrying disable." },
+      changes: applied.completed,
+      retained: applied.retained,
+      failure: applied.error
+        ? { phase: "repository_configuration", message: applied.error.message }
+        : result === "failed" ? { phase: "verification", message: "Repository disable postcondition was not observed." } : null,
+    });
+    printLifecycleResult(report, { json: options.json, locale: options.language.chat_language, io });
+    return result === "success" ? 0 : 1;
+  } catch (error) {
+    io.error(error.message);
+    return 1;
+  }
+}
+
+function runUninstall(options, { io, env, exec }) {
+  try {
+    const configDir = env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir();
+    const plan = planGlobalUninstall(options.surface, { configDir });
+    if (!options.confirm) {
+      const preview = createLifecycleResult({
+        operation: "uninstall", result: "preview", surface: options.surface, scope: "global",
+        verification: { status: "unknown", evidence: ["non_mutating_preview"] },
+        restart: { required: false },
+        next_action: { kind: "confirm", text: `Review this preview, then rerun with --surface ${options.surface} --scope global --confirm; ownership is revalidated before apply.` },
+        changes: plan.mutations, retained: plan.retained,
+      });
+      printLifecycleResult(preview, { json: options.json, locale: options.language.chat_language, io });
+      return 0;
+    }
+    const applied = applyLifecyclePlan(plan, exec ? { exec } : {});
+    const verified = applied.status === "success"
+      ? verifyGlobalUninstall(plan, options.dir, { configDir, exec })
+      : { status: "failed", evidence: [] };
+    const result = applied.status === "success" && verified.status !== "healthy" ? "failed" : applied.status;
+    const report = createLifecycleResult({
+      operation: "uninstall", result, surface: options.surface, scope: "global",
+      verification: { status: verified.status === "healthy" ? "healthy" : "degraded", evidence: [...applied.completed.map((item) => item.path || item.executable), ...verified.evidence] },
+      restart: { required: result === "success", reason: result === "success" ? "host_reload" : "none" },
+      next_action: result === "success"
+        ? { kind: "restart", text: "Restart the host; the uninstall postcondition has already been verified." }
+        : { kind: "verify", text: "Inspect the reported uninstall or verification failure before retrying." },
+      changes: applied.completed, retained: applied.retained,
+      failure: applied.error
+        ? { phase: "plugin_operation", message: applied.error.message }
+        : result === "failed" ? { phase: "verification", message: "Global uninstall postcondition was not observed." } : null,
+    });
+    printLifecycleResult(report, { json: options.json, locale: options.language.chat_language, io });
+    return result === "success" ? 0 : 1;
+  } catch (error) {
+    io.error(error.message);
+    return 1;
+  }
+}
+
+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 {
+    assertGeneratedWritePlan(options.dir, files, options.force);
+    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);
+  } catch (error) {
+    io.error(error.message);
+    return 1;
+  }
+
+  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents, io);
+  return 0;
+}
+
+export async function runCli(argv = process.argv.slice(2), adapters = {}) {
+  const io = adapters.io ?? console;
+  const env = adapters.env ?? process.env;
+  let parsed;
+  try {
+    parsed = parseArgs(argv, adapters.parser);
+  } catch (error) {
+    if (!(error instanceof CliUsageError)) throw error;
+    io.error(error.message);
+    if (error.showUsage) io.log(renderUsage());
+    return error.exitCode;
+  }
+
+  if (parsed.kind === "help") {
+    io.log(renderUsage());
+    return 0;
+  }
+
+  let options;
+  try {
+    options = validateCommandOptions(parsed.options);
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  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);
+  if (!handler) throw new Error(`No implementation is registered for ${command.name}.`);
+  return await handler(options);
+}
+
+export const main = runCli;