create-agdf 0.9.0 → 0.9.3

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/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "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-plugin.definition.json

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

package/lib/cli/application.js

@@ -0,0 +1,191 @@
+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 { 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;
+    }],
+    ["codex", () => {
+      try {
+        installCodexGlobalPlugin(installerAdapters);
+        io.log("AGDF Codex plugin installed globally.");
+        io.log("Run npx --yes @agdf/cli@latest codex-repo in a repository when you want to test AGDF from repository-local plugin files.");
+        return 0;
+      } catch (error) {
+        io.error(error.message);
+        return 1;
+      }
+    }],
+    ["claude", () => {
+      try {
+        installClaudeGlobalPlugin(installerAdapters);
+        io.log("AGDF Claude Code plugin installed globally.");
+        return 0;
+      } catch (error) {
+        io.error(error.message);
+        return 1;
+      }
+    }],
+    ["opencode", (options) => {
+      const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
+      try {
+        const result = installOpenCodeGlobalPlugin(configDir);
+        installOpenCodeGlobalSurface(configDir);
+        io.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
+        const report = evaluateOpenCodeStatus(options.dir, configDir, result.transition);
+        printOpenCodeStatus(report, false, io);
+        io.log("Restart OpenCode so it loads the updated global plugin config.");
+        return 0;
+      } 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;

package/lib/cli/command-registry.js

@@ -0,0 +1,101 @@
+function command(name, usages) {
+  return Object.freeze({
+    name,
+    handler: name,
+    groups: Object.freeze(Object.keys(usages)),
+    usages: Object.freeze(Object.fromEntries(
+      Object.entries(usages).map(([group, suffixes]) => [group, Object.freeze(suffixes)]),
+    )),
+  });
+}
+
+export const commandRegistry = Object.freeze([
+  command("codex", { preferred: [""], scaffold: [""] }),
+  command("codex-repo", { preferred: [""], scaffold: [""] }),
+  command("claude", { preferred: [""], scaffold: [""] }),
+  command("copilot", { scaffold: [""] }),
+  command("opencode", { preferred: [""], scaffold: [""] }),
+  command("opencode-status", { preferred: [""], scaffold: [""] }),
+  command("opencode-repo", { preferred: [""], scaffold: [""] }),
+  command("both", { scaffold: [""] }),
+  command("init", { preferred: [""], scaffold: [""] }),
+  command("config", { scaffold: [" --language de"] }),
+  command("doctor", { preferred: [""], scaffold: [""], legacy: [" --json"] }),
+  command("gate-check", { preferred: [" --json"], scaffold: [""], legacy: [" --json"] }),
+  command("delivery-map", { scaffold: [""] }),
+  command("delivery-path-search", {
+    preferred: [" --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>"] }),
+]);
+
+const commandByName = new Map(commandRegistry.map((entry) => [entry.name, entry]));
+
+export function resolveCommand(name) {
+  return commandByName.get(name) ?? null;
+}
+
+export function supportedCommandNames() {
+  return commandRegistry.map((entry) => entry.name);
+}
+
+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 (options.target === "run-create" && (!options.runId || options.allActive)) {
+    throw new Error("run-create requires --run and rejects --all-active");
+  }
+  if (options.target === "run-render-legacy" && !options.runId) {
+    throw new Error("run-render-legacy requires --run");
+  }
+  return options;
+}
+
+function usageLines(group, prefix) {
+  return commandRegistry
+    .flatMap((entry) => (entry.usages[group] ?? []).map((suffix) => `  ${prefix}${entry.name}${suffix}`))
+    .join("\n");
+}
+
+export function renderUsage() {
+  return `create-agdf
+
+Preferred AGDF CLI:
+${usageLines("preferred", "npx --yes @agdf/cli@latest ")}
+
+Scaffold-compatible npm create usage:
+${usageLines("scaffold", "npm create agdf@latest -- ")}
+
+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.
+  --force        Overwrite existing generated files
+  --language <tag>
+                 Set AGDF chat and artefact language. Defaults to detected system locale.
+  --lang <tag>   Alias for --language
+  --json         Print machine-readable command output as JSON
+  --status-card  Print compact gate-check status-card output for interactive use
+  --run <run_id> Select one canonical run
+  --all-active   Evaluate every active run (doctor and delivery-map only)
+  --surface <codex|claude|copilot|opencode|generic>
+                 Declare the active Delivery Path Search surface
+  --fixture <path>
+                 Use deterministic evaluator/candidate fixtures instead of a live evaluator
+  --persist      Persist the redacted Delivery Path Search result under the current scope
+  --model <id>   Optional Codex evaluator model
+  --generate-candidates
+                 Add one bounded AI-native candidate-generation call before evaluation
+  --generator-model <id>
+                 Optional candidate-generator model override
+  --max-generated-candidates <1-5>
+  --generation-timeout-ms <1-30000>
+  --generation-cost-units <1-5>
+  --help         Show this help
+`;
+}

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

@@ -0,0 +1,75 @@
+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 { 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';
+
+export async function executeDeliveryPathSearch(options, io = console) {
+  const fixture = options.fixture ? JSON.parse(readFileSync(options.fixture, "utf8")) : null;
+  const enforcement = fixture?.input?.enforcement ?? enforcementForSurface(options.surface);
+  const fixtureGeneration = fixture?.generator_response;
+  const generationEnabled = Boolean(fixtureGeneration || options.generateCandidates);
+  const baseInput = fixture?.input ?? searchInputFromControl(options.dir, {
+    scopeKey: options.runId,
+    enforcement,
+    generation: generationEnabled ? {
+      enabled: true,
+      maxProposals: options.maxGeneratedCandidates,
+      maxDurationMs: options.generationTimeoutMs,
+      maxCostUnits: options.generationCostUnits,
+    } : undefined,
+  });
+  const input = generationEnabled && !baseInput.generation ? {
+    ...baseInput,
+    generation: {
+      enabled: true,
+      max_calls: 1,
+      max_proposals: options.maxGeneratedCandidates,
+      max_duration_ms: options.generationTimeoutMs,
+      max_cost_units: options.generationCostUnits,
+    },
+  } : baseInput;
+  const evaluator = fixture
+    ? fixtureEvaluator(fixture.evaluations ?? {})
+    : options.surface === "codex"
+      ? codexEvaluator({ cwd: options.dir, model: options.model })
+      : options.surface === "claude"
+        ? claudeEvaluator({ cwd: options.dir, model: options.model })
+        : null;
+  if (!evaluator) {
+    throw new Error(`${options.surface} has no executable evaluator in this release. Codex and Claude are the reference adapters; --fixture is available for deterministic contract testing.`);
+  }
+  const generator = fixtureGeneration
+    ? fixtureGenerator(fixtureGeneration)
+    : options.generateCandidates && options.surface === "codex"
+      ? codexGenerator({ cwd: options.dir, model: options.generatorModel, timeoutMs: options.generationTimeoutMs })
+      : options.generateCandidates && options.surface === "claude"
+        ? claudeGenerator({ cwd: options.dir, model: options.generatorModel, timeoutMs: options.generationTimeoutMs })
+        : null;
+  if (options.generateCandidates && !generator) {
+    throw new Error(`${options.surface} has no executable candidate generator; Codex and Claude are tool-enforced reference transports.`);
+  }
+  const result = await runDeliveryPathSearch(input, evaluator, { candidates: fixture?.candidates, generator });
+  if (options.persist) result.persistence = persistSearchResult(options.dir, result);
+  if (options.json) {
+    io.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  io.log(`AGDF Delivery Path Search: ${result.status}`);
+  io.log(`Current gate: ${result.current_gate}`);
+  io.log(`Enforcement: ${result.enforcement.level}`);
+  io.log(`Recommendation: ${result.recommendation?.action ?? "none"}`);
+  io.log(`Evaluations: ${result.budgets.evaluations}`);
+  io.log(`Generation: ${result.generation.status} (${result.generation.accepted}/${result.generation.returned} accepted)`);
+  io.log(`Generation budget: ${result.generation.cost_units} cost units, ${result.generation.duration_ms} ms`);
+  if (result.generation.failure_code) io.log(`Generation failure: ${result.generation.failure_code}`);
+  io.log(`Stopping reason: ${result.stopping_reason}`);
+  io.log(result.next_gate_action);
+  return result;
+}

package/lib/cli/parse-args.js

@@ -0,0 +1,142 @@
+import { resolve } from "node:path";
+import process from "node:process";
+import { configuredLanguage, resolveLanguagePreference } from "./runtime-context.js";
+import { resolveCommand, supportedCommandNames } from "./command-registry.js";
+
+export class CliUsageError extends Error {
+  constructor(message, { showUsage = false } = {}) {
+    super(message);
+    this.name = "CliUsageError";
+    this.exitCode = 1;
+    this.showUsage = showUsage;
+  }
+}
+
+function requiredValue(args, index, option) {
+  const next = args[index + 1];
+  if (!next) throw new CliUsageError(`Missing value for ${option}`);
+  return next;
+}
+
+export function parseArgs(argv, dependencies = {}) {
+  const cwd = dependencies.cwd ?? process.cwd();
+  const languagePreference = dependencies.resolveLanguagePreference ?? resolveLanguagePreference;
+  const normalizeLanguage = dependencies.configuredLanguage ?? configuredLanguage;
+  const args = [...argv];
+  let target;
+  let dir = ".";
+  let force = false;
+  let json = false;
+  let statusCard = false;
+  let language;
+  let dirExplicit = false;
+  let surface = "generic";
+  let fixture;
+  let persist = false;
+  let model;
+  let generateCandidates = false;
+  let generatorModel;
+  let maxGeneratedCandidates = 5;
+  let generationTimeoutMs = 30000;
+  let generationCostUnits = 5;
+  let runId;
+  let allActive = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg === "--help" || arg === "-h") return { kind: "help" };
+    if (arg === "--force") { force = true; continue; }
+    if (arg === "--json") { json = true; continue; }
+    if (arg === "--status-card") { statusCard = true; continue; }
+    if (arg === "--persist") { persist = true; continue; }
+    if (arg === "--generate-candidates") { generateCandidates = true; continue; }
+    if (arg === "--all-active") { allActive = true; continue; }
+
+    if (arg === "--run") {
+      runId = requiredValue(args, i, arg);
+      i += 1;
+      continue;
+    }
+
+    if (["--surface", "--fixture", "--model", "--generator-model", "--max-generated-candidates", "--generation-timeout-ms", "--generation-cost-units"].includes(arg)) {
+      const next = requiredValue(args, i, arg);
+      if (arg === "--surface") {
+        if (!["codex", "claude", "copilot", "opencode", "generic"].includes(next)) {
+          throw new CliUsageError("Unsupported surface. Use codex, claude, copilot, opencode or generic.");
+        }
+        surface = next;
+      } else if (arg === "--fixture") fixture = next;
+      else if (arg === "--model") model = next;
+      else if (arg === "--generator-model") generatorModel = next;
+      else {
+        const value = Number(next);
+        const maximum = arg === "--generation-timeout-ms" ? 30000 : 5;
+        if (!Number.isInteger(value) || value < 1 || value > maximum) {
+          throw new CliUsageError(`${arg} must be an integer from 1 to ${maximum}.`);
+        }
+        if (arg === "--max-generated-candidates") maxGeneratedCandidates = value;
+        else if (arg === "--generation-timeout-ms") generationTimeoutMs = value;
+        else generationCostUnits = value;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--language" || arg === "--lang") {
+      const next = requiredValue(args, i, arg);
+      const normalized = normalizeLanguage(next);
+      if (!normalized) throw new CliUsageError("Invalid language tag. Use a BCP 47 tag such as de, en or fr-CA.");
+      language = normalized;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--dir") {
+      dir = requiredValue(args, i, arg);
+      dirExplicit = true;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--target" || arg === "-t") {
+      target = requiredValue(args, i, arg);
+      i += 1;
+      continue;
+    }
+
+    if (!arg.startsWith("-") && !target) {
+      target = arg;
+      continue;
+    }
+    throw new CliUsageError(`Unknown argument: ${arg}`);
+  }
+
+  if (!target || !resolveCommand(target)) {
+    throw new CliUsageError(`Please choose one target: ${supportedCommandNames().join(", ")}.`, { showUsage: true });
+  }
+
+  return {
+    kind: "command",
+    options: {
+      target,
+      dir: resolve(cwd, dir),
+      force,
+      json,
+      statusCard,
+      dirExplicit,
+      language: languagePreference(language),
+      surface,
+      fixture: fixture ? resolve(cwd, fixture) : null,
+      persist,
+      model,
+      generateCandidates,
+      runId,
+      allActive,
+      generatorModel,
+      maxGeneratedCandidates,
+      generationTimeoutMs,
+      generationCostUnits,
+    },
+  };
+}

package/lib/cli/runtime-context.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import {
+  canonicalizeLanguageTag,
+  resolvePresentationLocale,
+} from "../interaction-presentation.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const packageRoot = resolve(__dirname, "../..");
+export const generatedRoot = join(packageRoot, "generated");
+
+const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
+const interactionLocalesPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-interaction-locales.json");
+
+export const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
+export const interactionLocales = JSON.parse(readFileSync(interactionLocalesPath, "utf8"));
+
+export function configuredLanguage(value) {
+  const normalized = canonicalizeLanguageTag(value);
+  if (!normalized) return "";
+  const language = normalized.split("-")[0];
+  if (interactionLocales.locales[normalized] || interactionLocales.locales[language]) {
+    return resolvePresentationLocale(interactionLocales, normalized);
+  }
+  return normalized;
+}
+
+export function detectSystemLocale(env = process.env) {
+  const envLocale = env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE || "";
+  if (envLocale) return envLocale;
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale || "";
+  } catch {
+    return "";
+  }
+}
+
+export function resolveLanguagePreference(explicitLanguage, env = process.env) {
+  const explicit = configuredLanguage(explicitLanguage);
+  if (explicit) {
+    return {
+      artifact_language: explicit,
+      chat_language: explicit,
+      runtime_language: "en",
+      source: "parameter",
+      detected_locale: detectSystemLocale(env) || "unknown",
+    };
+  }
+
+  const detectedLocale = detectSystemLocale(env);
+  const detected = configuredLanguage(detectedLocale) || interactionLocales.fallbackLocale;
+  return {
+    artifact_language: detected,
+    chat_language: detected,
+    runtime_language: "en",
+    source: detectedLocale ? "system_locale" : "default",
+    detected_locale: detectedLocale || "unknown",
+  };
+}
+
+export function resolveConfiguredChatLanguage(targetDir) {
+  const configPath = join(targetDir, ".agdf", "control", "config.json");
+  if (!existsSync(configPath)) return interactionLocales.fallbackLocale;
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    return resolvePresentationLocale(interactionLocales, config.chat_language);
+  } catch {
+    return interactionLocales.fallbackLocale;
+  }
+}
+
+export function languageConfigContent(languagePreference) {
+  return `${JSON.stringify({
+    artifact_language: languagePreference.artifact_language,
+    chat_language: languagePreference.chat_language,
+    runtime_language: languagePreference.runtime_language,
+    source: languagePreference.source,
+    detected_locale: languagePreference.detected_locale,
+  }, null, 2)}\n`;
+}