create-agdf 0.20.1 → 0.30.0

package/lib/cli/codex-document-command.js

@@ -0,0 +1,195 @@
+// A terminal frontend for Codex JSONL, not a model message or approval recorder.
+import { createHash } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { validateRunPresentationRecord } from '#agdf-core/control-state/run-presentation.js';
+import { resolutionRecordVersion } from '#agdf-core/control-state/input-resolution.js';
+import { resolveControlCommandTarget, canonicalJson } from '#agdf-core/control-state/approval-command-contract.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN, APPROVAL_GATES } from '#agdf-core/control-state/run-identity.js';
+import { pluginDefinition } from '../runtime/control-context.js';
+
+const fail = code => { throw Error(`document_delivery_${code}`); };
+const hash = bytes => 'sha256:' + createHash('sha256').update(bytes).digest('hex');
+const digestPattern = /^[a-f0-9]{64}$/u;
+const LIMITS = Object.freeze({ frame: 4 * 1024 ** 2, stream: 64 * 1024 ** 2, events: 10000, document: 131072 });
+
+export function validateDocumentSelection(options) {
+  if (!isAbsolute(options.dir ?? '') || !RUN_ID_PATTERN.test(options.runId ?? '')
+    || !REVISION_ID_PATTERN.test(options.revisionId ?? '') || !REVISION_ID_PATTERN.test(options.presentationId ?? '')
+    || !APPROVAL_GATES.includes(options.gate)) fail('selection_required');
+  if (options.documentServer !== undefined && (typeof options.documentServer !== 'string'
+    || !/^[A-Za-z0-9_.-]{1,128}$/u.test(options.documentServer))) fail('server_invalid');
+}
+
+function binding(options) {
+  validateDocumentSelection(options);
+  const root = realpathSync(options.dir);
+  const targetId = resolveControlCommandTarget(root).target_id;
+  if (!targetId) fail('target_unavailable');
+  // Canonical envelope reader validates paths, links, identity and record digest.
+  // It does not read the document snapshot. Output bytes must come from MCP.
+  const checked = validateRunPresentationRecord(root, options);
+  if (checked.reason || resolutionRecordVersion(checked.record) !== 7) fail('presentation_unavailable');
+  return { root, targetId, checked };
+}
+
+function domainFor(item) {
+  const result = item.result;
+  if (result?.isError || result?.is_error || item.error || item.status !== 'completed') fail('tool_failed');
+  const snake = result?.structured_content, camel = result?.structuredContent;
+  if (snake && camel && canonicalJson(snake) !== canonicalJson(camel)) fail('conflicting_channels');
+  const domain = snake ?? camel;
+  if (!domain || typeof domain !== 'object') fail('structured_result_required');
+  if (!Array.isArray(result.content) || result.content.length !== 1 || result.content[0]?.type !== 'text') fail('text_result_required');
+  let text;
+  try { text = JSON.parse(result.content[0].text); } catch { fail('text_result_invalid'); }
+  if (canonicalJson(text) !== canonicalJson(domain)) fail('conflicting_channels');
+  return domain;
+}
+
+// Async iterable input supports real stdin and byte-split stream regression tests.
+export async function readCodexDocument(input, options) {
+  const expected = binding(options), server = options.documentServer ?? 'agdf';
+  const record = expected.checked.record, pages = new Map(), activeTools = new Map();
+  const prefix = expected.checked.digest.slice(7) + ':';
+  const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+  let pending = '', streamBytes = 0, events = 0, offset = 0, cursor, duplicates = 0, reads = 0, failedReads = 0;
+  let threadId, started = false, completed = false, runtimeDigest;
+  function event(line) {
+    if (++events > LIMITS.events || Buffer.byteLength(line) > LIMITS.frame) fail('stream_limit');
+    let value;
+    try { value = JSON.parse(line); } catch { fail('json_invalid'); }
+    if (completed) fail('events_after_completion');
+    if (value.type === 'thread.started') {
+      if (threadId || !REVISION_ID_PATTERN.test(value.thread_id ?? '')) fail('thread_invalid');
+      threadId = value.thread_id; return;
+    }
+    if (value.type === 'turn.started') {
+      if (!threadId || started) fail('turn_invalid');
+      started = true; return;
+    }
+    if (!started) fail('turn_missing');
+    if (value.type === 'turn.completed') {
+      if (activeTools.size) fail('unfinished_tool');
+      completed = true; return;
+    }
+    if (['turn.failed', 'error'].includes(value.type)) fail('turn_failed');
+    if (!['item.started', 'item.updated', 'item.completed'].includes(value.type) || !value.item) fail('event_unsupported');
+    const item = value.item;
+    if (['error', 'command_execution', 'file_change', 'web_search'].includes(item.type)) fail('unexpected_action');
+    if (item.type !== 'mcp_tool_call') {
+      if (!['agent_message', 'reasoning', 'todo_list'].includes(item.type)) fail('item_unsupported');
+      return;
+    }
+    if (item.server !== server || item.tool !== 'agdf_inspect') fail('unexpected_tool');
+    if (typeof item.id !== 'string' || !item.id) fail('tool_id_invalid');
+    if (value.type === 'item.started') {
+      if (activeTools.has(item.id)) fail('tool_id_repeated');
+      activeTools.set(item.id, true); return;
+    }
+    if (value.type !== 'item.completed') return;
+    if (!activeTools.delete(item.id)) fail('tool_start_missing');
+    const call = item.arguments;
+    // Other read-only orientation calls cannot supply document bytes.
+    if (call?.operation !== 'presentation-document') return;
+    if (item.status === 'failed') { failedReads++; return; }
+    const domain = domainFor(item), report = domain.report;
+    if (domain.schema_version !== '1' || domain.outcome !== 'inspect_result'
+      || domain.operation !== 'presentation-document' || domain.authorizes !== false
+      || report?.available !== true || report.authorizes !== false) fail('document_result_invalid');
+    const runtime = domain.runtime;
+    if (runtime?.provenance_status !== 'matched' || runtime.expected_version !== pluginDefinition.version
+      || !digestPattern.test(runtime.runtime_digest ?? '')) fail('runtime_unmatched');
+    if (runtimeDigest && runtimeDigest !== runtime.runtime_digest) fail('runtime_changed');
+    runtimeDigest = runtime.runtime_digest;
+    if (!['explicit_target', 'continued_target', 'current_repository'].includes(call.target_source)
+      || call.primary_target !== expected.root || domain.target?.resolution_state !== 'resolved'
+      || domain.target.governance_target !== expected.root || domain.target.primary_target !== expected.root
+      || domain.target.target_source !== call.target_source || domain.target.authorizes !== false) fail('target_mismatch');
+    for (const [field, wanted] of Object.entries({ target_id: expected.targetId, run_id: options.runId,
+      gate: options.gate, presentation_id: options.presentationId })) {
+      if (call[field] !== wanted || report[field] !== wanted) fail('selection_mismatch');
+    }
+    if (call.expected_revision_id !== options.revisionId || report.revision_id !== options.revisionId
+      || report.presentation_digest !== expected.checked.digest || report.content_digest !== record.document_digest
+      || report.total_bytes !== record.document_bytes || report.presentation_language !== record.presentation_language
+      || report.document_language !== record.document_language) fail('binding_mismatch');
+    const start = report.byte_start, end = report.byte_end;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start
+      || end > record.document_bytes || end > LIMITS.document || typeof report.content !== 'string') fail('range_invalid');
+    const bytes = Buffer.from(report.content, 'utf8');
+    if (bytes.toString('utf8') !== report.content || bytes.length !== end - start) fail('utf8_invalid');
+    if (call.cursor !== (start === 0 ? undefined : prefix + start)
+      || report.complete !== (end === record.document_bytes)
+      || report.next_cursor !== (end === record.document_bytes ? null : prefix + end)) fail('cursor_invalid');
+    reads++;
+    if (pages.has(start)) {
+      const old = pages.get(start);
+      if (old.end !== end || !old.bytes.equals(bytes)) fail('duplicate_conflict');
+      duplicates++; return;
+    }
+    if (start !== offset || call.cursor !== cursor) fail('page_gap');
+    pages.set(start, { end, bytes }); offset = end; cursor = report.next_cursor;
+  }
+  for await (const chunk of input) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    streamBytes += bytes.length;
+    if (streamBytes > LIMITS.stream) fail('stream_limit');
+    pending += decoder.decode(bytes, { stream: true });
+    let newline;
+    while ((newline = pending.indexOf('\n')) >= 0) {
+      const line = pending.slice(0, newline); pending = pending.slice(newline + 1);
+      if (!line.trim()) fail('empty_frame');
+      event(line);
+    }
+    if (Buffer.byteLength(pending) > LIMITS.frame) fail('stream_limit');
+  }
+  pending += decoder.decode();
+  if (pending) event(pending);
+  if (!completed || offset !== record.document_bytes || cursor !== null) fail('incomplete');
+  const document = Buffer.concat([...pages.values()].map(page => page.bytes));
+  if (hash(document) !== record.document_digest) fail('digest_mismatch');
+  const current = binding(options);
+  if (current.root !== expected.root || current.targetId !== expected.targetId
+    || current.checked.digest !== expected.checked.digest) fail('binding_changed');
+  // Never interpret raw terminal controls from a frozen artefact. Reject, do not
+  // sanitize bytes and then pretend the original digest was delivered.
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]|\r(?!\n)/u.test(document.toString('utf8'))) fail('terminal_controls');
+  return { document, receipt: { mode: 'verified_terminal', proof_scope: 'stdout_bytes_written',
+    authorizes: false, thread_id: threadId, target_id: expected.targetId, run_id: options.runId,
+    gate: options.gate, revision_id: options.revisionId, presentation_id: options.presentationId,
+    presentation_digest: expected.checked.digest, content_digest: record.document_digest,
+    bytes: document.length, pages: pages.size, reads, duplicate_reads: duplicates, failed_reads: failedReads,
+    runtime_digest: runtimeDigest, turn_completed: true } };
+}
+
+async function write(stream, data) {
+  await new Promise((resolve, reject) => stream.write(data, error => error ? reject(error) : resolve()));
+}
+
+export function createCodexDocumentRequest(options) {
+  const selected = binding(options), server = options.documentServer ?? 'agdf';
+  const request = { operation: 'presentation-document', presentation_language: selected.checked.record.presentation_language,
+    working_directory: selected.root, target_source: 'explicit_target', primary_target: selected.root,
+    target_id: selected.targetId, run_id: options.runId, gate: options.gate,
+    expected_revision_id: options.revisionId, presentation_id: options.presentationId };
+  return `The verified AGDF render-document terminal frontend is explicitly configured for this request. It receives the original MCP frames and independently validates the selected canonical binding, every page and SHA256 before writing any text. This is a read-only request, never approval. Use only agdf_inspect from server ${JSON.stringify(server)}. Use the literal tool name already supplied in the code when it is available. Do not add ALL_TOOLS discovery or dynamic tools[variable], tools[match.name] or aliases. If the configured server exposes a different name, discover it separately and replace ONLY the literal name; never select a tool dynamically. The strict observer rejects dynamic dispatch. Preserve every selected value, including this historical revision even if a newer revision exists. Execute the complete bounded read loop in one Code Mode cell. Progress is in result.structuredContent.report, not at the structuredContent root. Print only progress metadata, not content or whole tool replies. Never repeat completed pages or infer a cursor.\n\n`
+    + `const selected = ${JSON.stringify(request)};\nlet cursor;\nlet done = false;\nfor (let pageNumber = 0; pageNumber < 64; pageNumber++) {\n`
+    + `  const result = await tools[${JSON.stringify('mcp__' + server + '__agdf_inspect')}](cursor === undefined ? selected : {...selected, cursor});\n`
+    + `  const domain = result.structuredContent;\n  const page = domain?.report;\n`
+    + `  if (domain?.outcome !== "inspect_result" || page?.available !== true) throw new Error("Document read failed");\n`
+    + `  text({byte_end:page.byte_end, complete:page.complete, next_cursor:page.next_cursor});\n`
+    + `  if (page.complete === true) { done = true; break; }\n`
+    + `  if (typeof page.next_cursor !== "string" || page.next_cursor === cursor) throw new Error("Missing or repeated cursor");\n`
+    + `  cursor = page.next_cursor;\n}\nif (!done) throw new Error("Document page limit exceeded");\n\n`
+    + 'After successful completion say only that the pages were retrieved and the host will perform verified output. Do not claim that output or human approval already happened. The renderer receipt proves stdout bytes written only, not human visibility or approval.\n';
+}
+
+export async function renderCodexDocument(options, { input = process.stdin, output = process.stdout, errors = process.stderr } = {}) {
+  if (options.documentRequest) { await write(output, createCodexDocumentRequest(options)); return 0; }
+  if (input.isTTY) fail('jsonl_stdin_required');
+  const { document, receipt } = await readCodexDocument(input, options);
+  await write(output, document);
+  await write(errors, 'AGDF_DOCUMENT_DELIVERY ' + JSON.stringify(receipt) + '\n');
+  return 0;
+}

package/lib/cli/command-registry.js

@@ -2,6 +2,7 @@ import { TASK_TARGET_SOURCES } from "#agdf-core/task-target-resolution.js";
 import { skillDispatchArgumentGrammar, skillDispatchCommandGrammar } from "#agdf-core/skill-dispatch/contract.js";
 import { validateReadSelection } from "#agdf-core/control-inspect/selection.js";
 import { RUN_COMMAND_GROUPS } from '#agdf-core/control-state/run-command-contract.js';
+import { validateDocumentSelection } from './codex-document-command.js';
 export { skillDispatchArgumentGrammar };
 export const commandGroupRoutes = Object.freeze(Object.fromEntries(Object.keys(RUN_COMMAND_GROUPS).map(group => [group.replace('_', '-'), group])));
 
@@ -19,40 +20,42 @@ function command(name, usages) {
 }
 
 export const commandRegistry = Object.freeze([
-  command("codex", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
+  command("codex", { preferred: [" [--package <core|planning>] [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
   command("codex-repo", { preferred: [" --dir <path>"], scaffold: [" --dir <path>"] }),
   command("claude", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
   command("copilot", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"] }),
   command("opencode", { preferred: [" [--with-mcp --dir <absolute-target> [--scope <project|user>] | --plugin-only]"], scaffold: [""] }),
   command("opencode-status", { preferred: [""], scaffold: [""] }),
-  command("status", { preferred: [" [--surface <surface>] [--dir <absolute-target> [--scope <project|user>]] [--run <run_id>] [--json]"] }),
+  command("status", { preferred: [" [--surface <surface>] [--dir <absolute-target> [--scope <project|user>]] [--run <run_id>] [--native] [--json]"] }),
   command("runtime-checks", { preferred: [" <status|enable|manual> --surface <codex|claude|copilot|opencode> [--json]"] }),
   command("mcp", { preferred: [" <status|enable|disable> --surface <codex|claude|copilot|opencode> [--scope <project|user>] --dir <absolute-target> [--json]"] }),
   command("disable", { preferred: [" --surface <surface> [--scope repository] [--shared] [--dir <path>] [--with-mcp]"] }),
   command("uninstall", { preferred: [" --surface <surface> --scope global [--with-mcp --mcp-scope <project|user> --dir <absolute-target>] [--confirm]"] }),
   command("opencode-repo", { preferred: [" --dir <path>"], scaffold: [" --dir <path>"] }),
-  command("init", { preferred: [""], scaffold: [""] }),
+  command("init", { preferred: [" [--operation <original-uuid>]"], scaffold: [""] }),
+  command('project-state', { local: [' --dir <absolute-git-root> [--json] [--language <tag>]'] }),
+  command('operation-status', { local: [' --dir <absolute-git-root> --module project.initialize/<original-uuid> [--json] [--language <tag>]'] }),
   command("config", { scaffold: [" --language de"] }),
   command("target-check", { local: [` --json [--language <tag>] [--working-directory <absolute-path>] [--target-source ${TASK_TARGET_SOURCE_GRAMMAR} --primary-target <absolute-path>]`] }),
   command("skill-dispatch", { local: [` ${skillDispatchCommandGrammar()}`] }),
   command("doctor", { local: [""], scaffold: [""], legacy: [" --json"] }),
   command("gate-check", { local: [" --approval-envelope", " --json"], scaffold: [""], legacy: [" --json"] }),
   command("delivery-map", { local: [" --json"], scaffold: [""] }),
+  command("inventory", { local: [" [--json] [--language <tag>]"] }),
+  command('planned', { local: [' --dir <absolute-target> --action <list|inspect|create|replace|start|status> [--plan-id <id> --source-digest <sha256>] [--evidence <UR.md> --priority <high|normal|low>] [--operation <uuid>]'] }),
   command("delivery-path-search", {
     local: [" --surface codex --json", " --surface claude --json", " --surface opencode --json"],
     scaffold: [" --surface codex", " --surface claude", " --surface opencode"],
   }),
   command("contract", { local: [" --module <runtime-contract-module> [--json]"] }),
-  command("control-maintenance", { local: [" --dir <absolute-repository> [--guided | --details | --json] [--language <tag>]"] }),
-  command("run-present", { local: [" --run <run_id> --gate <gate> --revision <revision_id>"] }),
-  command("run-create", { local: [" --run <run_id>"] }),
-  command("run-update", { local: [" --run <run_id> --revision <revision_id>"] }),
-  command("run-revise", { local: [" --run <run_id> --revision <revision_id>", " --preview|--apply --run <run_id> --revision <revision_id> --source-gate <UR|PRD|SD|TP> --operation <uuid> --evidence <proposal.json> [--preview-digest <sha256>]"] }),
-  command("run-step", { local: [" --run <run_id> --revision <revision_id> --step <ur|route|review|evidence|closeout|artefact> [step fields]"] }),
-  command("run-approve", { local: [" --run <run_id> --gate <UR|PRD|SD|TP|QA|UAT> --revision <revision_id> --presentation <presentation_id> --response \"Approval: <gate>\""] }),
-  command("run-migrate", { local: [" [--run <run_id>]"] }),
-  command("run-recovery", { local: [" --run <run_id> --action <inspect|preview>", " --run <run_id> --action apply --preview-id <uuid> --recovery-confirmation \"RECOVER <run_id> <preview_id>\""] }),
-  command("run-render-legacy", { local: [" --run <run_id>"] }),
+  command("control-maintenance", { local: [" --dir <absolute-repository> [--details | --json] [--language <tag>]"] }),
+  command('run-create', { local: [' --title <title> [--operation <original-uuid>]'] }),
+  command('run-present', { local: [' --run <id> --revision <uuid> --gate <gate> [--operation <original-uuid>]'] }),
+  command('render-document', { local: [' --dir <absolute-target> --run <id> --revision <uuid> --gate <gate> --presentation <uuid> [--server <codex-mcp-server-id>] [--request | < codex-events.jsonl]'] }),
+  command('run-approve', { local: [' --run <id> --revision <uuid> --gate <gate> --presentation <uuid> --response <exact-reply> [--operation <original-uuid>]'] }),
+  command('run-step', { local: [' --run <id> --revision <uuid> --step <ur|route|review|evidence|artefact|closeout> --evidence <source-file> [step fields] [--operation <original-uuid>]'] }),
+  command('run-revise', { local: [' --run <id> --revision <uuid> --operation <original-uuid> [--preview|--apply|--inspect|--recover --source-gate <UR|PRD|SD|TP> --evidence <current-proposal.json>] [--confirmation <exact-selector>]'] }),
+  command('run-close', { local: [' --action <preview|apply> [--closure-file <entries.json>|--run <id> --outcome <superseded|abandoned> --reason <text>] [--preview-id <id> --confirmation <exact-selector>] [--operation <original-uuid>]'] }),
   ...Object.keys(commandGroupRoutes).map(name => command(name, { local: [' --command-file <bounded-command.json>'] })),
 ]);
 
@@ -67,12 +70,58 @@ export function supportedCommandNames() {
 }
 
 export function validateCommandOptions(options) {
+  if (options.native && (options.target !== 'status' || options.surface !== 'codex' || !options.dirExplicit || !options.dirInputAbsolute))
+    throw Error('--native requires status --surface codex --dir <absolute-target>.');
+  if (['project-state', 'operation-status'].includes(options.target)) {
+    if (!options.dirExplicit || !options.dirInputAbsolute) throw Error('Project reads require an explicit absolute --dir Git root.');
+    if (options.target === 'operation-status' && !/^project\.initialize\/[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/u.test(options.contractModule ?? ''))
+      throw Error('operation-status requires --module project.initialize/<original-uuid>.');
+    return options;
+  }
+  if (options.target === 'render-document') {
+    if (!options.dirExplicit || !options.dirInputAbsolute) throw Error('render-document requires an explicit absolute --dir');
+    validateDocumentSelection(options);
+    return options;
+  }
+  if (['run-create', 'run-present', 'run-approve', 'run-step', 'run-revise', 'run-close'].includes(options.target)) {
+    if (options.commandFile || options.allActive || options.force || options.intake || options.continueDelivery || options.packageSelection) throw Error('A current Run command rejects unrelated scopes and force.');
+    if (options.target === 'run-create' && (options.runId || !options.stepFields?.title)) throw Error('run-create requires --title; its original UUID determines the new Run ID.');
+    if (!['run-create', 'run-close'].includes(options.target) && (!options.runId || !options.revisionId)) throw Error('The current Run command requires --run and --revision.');
+    if (options.target === 'run-present' && !options.gate) throw Error('run-present requires --gate.');
+    if (options.target === 'run-approve' && (!options.gate || !options.response || !options.presentationId)) throw Error('run-approve requires --gate, --presentation and --response.');
+    if (options.target === 'run-step' && !options.runStep) throw Error('run-step requires --step.');
+    if (options.target === 'run-revise' && !options.revisionMode && options.gate !== 'PRD') throw Error('Early source reopening requires --gate PRD; other sources use explicit preview/apply.');
+    if (options.target === 'run-revise' && !options.operationId) throw Error('run-revise requires the original --operation UUID.');
+    if (options.target === 'run-close' && !['preview', 'apply'].includes(options.recoveryAction)) throw Error('run-close requires --action preview or apply.');
+    return options;
+  }
+
+  if (options.target === 'planned') {
+    if (!options.dirExplicit || !options.dirInputAbsolute || options.runId || options.revisionId || options.gate || options.allActive
+      || options.force || options.intake || options.continueDelivery || options.commandFile || options.packageSelection) throw Error('Planning requires an explicit absolute --dir and no Run/gate/force scope');
+    const actions = ['list', 'inspect', 'create', 'replace', 'start', 'status'];
+    if (!actions.includes(options.recoveryAction)) throw Error('Unsupported planning action');
+    if (options.target === 'planned') {
+      if (['inspect', 'replace', 'start', 'status'].includes(options.recoveryAction) && !options.planId) throw Error('--plan-id is required for the selected source');
+      if (['replace', 'start'].includes(options.recoveryAction) && !options.sourceDigest) throw Error('--source-digest is required');
+      if (['create', 'replace'].includes(options.recoveryAction) && !options.stepFields.evidence) throw Error('--evidence UR.md is required');
+      if (options.priority && (options.recoveryAction !== 'create' || !['high', 'normal', 'low'].includes(options.priority))) throw Error('Priority is high, normal or low on create; replacement edits canonical metadata');
+      if (options.recoveryAction === 'create' && (options.planId || options.sourceDigest)) throw Error('Create derives its plan identity from the original UUID');
+    }
+    if (['apply', 'recover', 'status'].includes(options.recoveryAction) && !options.operationId) throw Error('--operation must retain the original UUID');
+    return options;
+  }
+  if (options.packageSelection !== undefined && (options.target !== 'codex' || !['core', 'planning'].includes(options.packageSelection))) throw Error('--package supports only codex core or planning');
+  if (options.packageSelection === 'planning' && (options.setupRequest !== 'plugin_only' || options.acceptPluginCapabilities || options.runtimeChecksDecision
+    || options.controlDir || options.scope)) throw Error('The optional package requires --plugin-only and does not change Core setup, hooks or project control');
+  if ([options.planId, options.sourceDigest, options.priority, options.pendingDigest].some(value => value !== undefined)) throw Error('Planning source fields require planned');
   if (Object.hasOwn(commandGroupRoutes, options.target)) {
     if (!options.commandFile) throw new Error('Bound command routes require --command-file; target/Run/revision/UUID are taken only from that strict envelope.');
     return options;
   }
   if (options.commandFile) throw new Error('--command-file requires a fixed AGDF command-group route');
-  if ((options.guided || options.details) && options.target !== "control-maintenance") {
+  if (options.guided) throw Error('Guided migration/reset is unsupported; inspect current control and recover only the original bounded operation.');
+  if ((options.details) && options.target !== "control-maintenance") {
     throw new Error("--guided and --details are supported only by control-maintenance");
   }
   if (options.target === "control-maintenance") {
@@ -82,13 +131,10 @@ export function validateCommandOptions(options) {
   }
   const installTargets = ["codex", "claude", "copilot", "opencode"];
   const installTarget = installTargets.includes(options.target);
-  if ((options.controlDir || options.controlMigration) && !installTarget) {
-    throw new Error("--control-dir and --control-migration are supported only by installation commands");
-  }
-  if (options.controlMigration === "safe" && !options.controlDir
-      && !(options.dirExplicit && (options.target !== "opencode" || options.setupRequest === "full"))) {
-    throw new Error("--control-migration safe requires an explicit repository target (--control-dir or --dir).");
+  if ((options.controlDir) && !installTarget) {
+    throw new Error("--control-dir is supported only by installation commands");
   }
+
   if (options.target !== "mcp" && options.target !== "status" && !installTarget && ["project", "user"].includes(options.scope)) {
     throw new Error("project and user scopes are supported only by mcp or a full installation setup");
   }
@@ -121,13 +167,9 @@ export function validateCommandOptions(options) {
   }
   if (options.skillId && options.target !== "skill-dispatch") throw new Error("--skill is supported only by skill-dispatch");
   if ((options.intakeMode || options.urAction || options.prdAction || options.sdAction || options.tpAction || options.continueDelivery) && options.target !== "skill-dispatch") throw new Error("delivery modes are supported only by skill-dispatch");
-  if (options.assurance !== undefined && options.target !== "run-approve"
-      || options.operationId !== undefined && options.target !== "run-approve" && !(options.target === "run-revise" && options.revisionMode)) {
-    throw new Error("--operation requires run-approve or an explicit run-revise mode; --assurance requires run-approve");
-  }
-  if ((options.revisionMode || options.sourceGate !== undefined || options.previewDigest !== undefined) && options.target !== "run-revise") throw new Error("Source revision fields require run-revise");
-  if (options.presentationId && options.target !== "run-approve") throw new Error("--presentation is supported only by run-approve");
-  if (options.target === "run-present" && (!options.runId || !options.gate || !options.revisionId)) throw new Error("run-present requires --run, --gate and --revision");
+  if (options.operationId !== undefined && options.target !== 'init') throw Error('--operation is supported only by init or planned; other writes use the bound command file.');
+  if (options.assurance !== undefined || options.revisionMode || options.sourceGate !== undefined || options.previewDigest !== undefined || options.presentationId)
+    throw Error('Use the current bound AGDF command group and --command-file for delivery writes.');
   if (options.intake && options.target !== "skill-dispatch") throw new Error("--intake is supported only by skill-dispatch");
   if (options.target === "skill-dispatch") {
     if (!options.json) throw new Error("skill-dispatch requires --json");
@@ -141,66 +183,15 @@ export function validateCommandOptions(options) {
   }
   // Shared read-selection rules (MCP agdf_inspect applies the same function). The gate-check
   // --status-card/--approval-envelope flags keep their historical CLI tolerance and are not passed here.
-  validateReadSelection({ operation: options.target, allActive: options.allActive, contractModule: options.contractModule });
-  if (options.target === "run-create" && (!options.runId || options.allActive)) {
-    throw new Error("run-create requires --run and rejects --all-active");
-  }
-  if (options.target === "run-recovery") {
-    if (!options.runId || !["inspect", "preview", "apply"].includes(options.recoveryAction)) {
-      throw new Error("run-recovery requires --run and --action inspect, preview or apply");
-    }
-    if (options.recoveryAction === "apply" && (!options.recoveryPreviewId || !options.recoveryConfirmation)) {
-      throw new Error("run-recovery apply requires --preview-id and --recovery-confirmation");
-    }
-    if (options.recoveryAction !== "apply" && (options.recoveryPreviewId || options.recoveryConfirmation)) {
-      throw new Error("--preview-id and --recovery-confirmation are supported only by run-recovery apply");
-    }
-  } else if (options.recoveryAction || options.recoveryPreviewId || options.recoveryConfirmation) {
-    throw new Error("--action, --preview-id and --recovery-confirmation are supported only by run-recovery");
-  }
-  if ((options.gate && !["run-approve", "run-present"].includes(options.target)
-      && !(options.target === "run-step" && options.runStep === "artefact")) || (options.response !== undefined && options.target !== "run-approve")) {
-    throw new Error("--gate is supported by run-present/run-approve; --response only by run-approve");
-  }
-  if (options.revisionId && !["run-update", "run-revise", "run-approve", "run-step", "run-present", "skill-dispatch"].includes(options.target)) {
-    throw new Error("--revision is supported only by run-update, run-revise, run-present, run-approve, run-step and skill-dispatch");
-  }
-  if ((options.runStep || Object.keys(options.stepFields ?? {}).length) && options.target !== "run-step"
-      && !(options.target === "run-revise" && ["preview", "apply"].includes(options.revisionMode)
-        && !options.runStep && Object.keys(options.stepFields).every(key => key === "evidence"))
-      && !(options.target === 'mcp' && (options.retireCockpit || options.restoreCockpit)
-        && !options.runStep && Object.keys(options.stepFields).every(key => key === 'evidence'))) {
-    throw new Error("--step and step fields are supported only by run-step");
-  }
-  if (options.target === "run-step" && (!options.runId || !options.revisionId || !options.runStep)) {
-    throw new Error("run-step requires --run, --revision and --step");
-  }
-  if (options.target === "run-step" && options.runStep === "artefact"
-      && (!["PRD", "SD", "TP", "QA"].includes(options.gate) || !options.stepFields?.evidence
-        || Object.keys(options.stepFields).some(key => key !== "evidence"))) throw new Error("run-step artefact requires --gate PRD|SD|TP|QA and --evidence <recording-input.json>; other step fields are rejected");
-  if (options.target === "run-update" && (!options.runId || !options.revisionId || options.gate || options.response !== undefined)) {
-    throw new Error("run-update requires --run and --revision and rejects --gate and --response");
-  }
-  if (options.target === "run-revise" && (!options.runId || !options.revisionId || options.gate || options.response !== undefined)) {
-    throw new Error("run-revise requires --run and --revision and rejects --gate and --response");
-  }
-  if (options.target === "run-revise") {
-    const mode = options.revisionMode;
-    if (!mode && (options.sourceGate !== undefined || options.previewDigest !== undefined)) throw new Error("Late revision requires an explicit mode");
-    if (mode && !["preview", "apply", "inspect", "recover"].includes(mode)) throw new Error("Unsupported source revision mode");
-    if (mode && !options.operationId) throw new Error("Source revision requires --operation");
-    if (["preview", "apply"].includes(mode) && (!["UR", "PRD", "SD", "TP"].includes(options.sourceGate) || !options.stepFields?.evidence)) throw new Error("Source revision preview/apply requires --source-gate and --evidence");
-    if (mode === "apply" && !/^sha256:[a-f0-9]{64}$/u.test(options.previewDigest ?? "")) throw new Error("Source revision apply requires its --preview-digest");
-    if (mode !== "apply" && options.previewDigest !== undefined) throw new Error("--preview-digest requires --apply");
-    if (["inspect", "recover"].includes(mode) && (options.sourceGate !== undefined || Object.keys(options.stepFields ?? {}).length)) throw new Error("Source revision inspect/recover accepts only run, revision and operation identity");
-    if (mode && !options.dirExplicit) throw new Error("Source revision requires an explicit --dir target");
-  }
-  if (options.target === "run-approve" && (!options.runId || !options.gate || !options.revisionId || options.response === undefined)) {
-    throw new Error("run-approve requires --run, --gate, --revision and --response");
-  }
-  if (options.target === "run-render-legacy" && !options.runId) {
-    throw new Error("run-render-legacy requires --run");
-  }
+  validateReadSelection({ operation: options.target, allActive: options.allActive, contractModule: options.contractModule, runId: options.runId });
+  if (options.gate || options.response !== undefined || options.runStep || options.recoveryAction || options.recoveryPreviewId
+    || options.recoveryConfirmation || options.closureFile || options.closureOutcome || options.successorRun !== undefined
+    || options.successorReference !== undefined || options.closureConfirmation !== undefined)
+    throw Error('Use the current bound AGDF command group and --command-file for delivery writes.');
+  if (options.revisionId && options.target !== 'skill-dispatch') throw Error('--revision is supported only by skill-dispatch; a bound write takes its revision from the command file.');
+  if (Object.keys(options.stepFields ?? {}).length && !(options.target === 'mcp' && (options.retireCockpit || options.restoreCockpit)
+    && Object.keys(options.stepFields).every(key => key === 'evidence')))
+    throw Error('Delivery sources belong to the bound command file; --evidence is reserved for explicit MCP cockpit retirement/recovery.');
   if (["disable", "uninstall"].includes(options.target) && ["", "generic", undefined].includes(options.surface)) {
     throw new Error(`${options.target} requires an explicit --surface`);
   }
@@ -290,13 +281,12 @@ Backward-compatible create-agdf usage:
 ${usageLines("legacy", "npx --yes create-agdf@latest ")}
 
 Options:
+  --native      Explicit bounded Codex catalog observation on status; requires --surface codex and absolute --dir.
   --dir <path>   Select an explicit target directory. OpenCode installation uses it as its config directory; MCP requires an absolute repository target.
   --with-mcp     Install the plugin and explicitly enable AGDF MCP for the selected target.
   --plugin-only  Install or update only the plugin and leave MCP unchanged.
   --control-dir <absolute-repository>
-                 Inspect existing .agdf state separately from host configuration; enables safe migrations.
-  --control-migration <inspect|safe>
-                 Inspect without changes, or migrate eligible unsealed runs in the explicit repository.
+                 Inspect existing project control separately from host configuration; inspection never resets or converts it.
   --force        Overwrite existing generated files
   --language <tag>
                  Set AGDF chat and artefact language. Defaults to detected system locale.
@@ -307,64 +297,8 @@ Options:
   --approval-envelope
                  Preview the current gate artefact; run-present is required before asking for approval
   --run <run_id> Select one canonical run
-  --action <inspect|preview|apply>
-                 run-recovery operation; apply also requires its preview ID and exact recovery confirmation
-  --preview-id <uuid>
-                 Bind run-recovery apply to one stored read-only preview
-  --recovery-confirmation <text>
-                 Exact confirmation printed by run-recovery preview
-  --module <runtime-contract-module>
-                 Runtime-contract module for contract, for example gate-transition
-  --step <ur|route|review|evidence|closeout|artefact>
-                 Standard transition for run-step. artefact --gate PRD|SD|TP|QA --evidence <recording-input.json>;
-                 other step fields: ur --title; route --route
-                 <quick_task|verified_change|structured_slice|structured_delivery|block> --reason
-                 --evidence; review --decision <pass|revise|block> --evidence [--source]; evidence
-                 --evidence [--source --covers]; closeout --result --evidence --risk --next
-  --revision <revision_id>
-                 Expected current run revision for run-update, run-revise, run-present, run-approve and run-step
-  --gate <UR|PRD|SD|TP|QA|UAT>
-                 Gate to present or approve
-  --response <text>
-                 The user's verbatim reply to the presented gate question
-  --target-source ${TASK_TARGET_SOURCE_GRAMMAR}
-                 Classify the semantic source for target-check
-  --primary-target <absolute-path>
-                 Supply exactly one target for target-check; cwd is never implied
-  --working-directory <absolute-path>
-                 Report execution context without granting target authority
-  --skill <skill-id>
-                 Select one canonical skill for skill-dispatch
-  --intake-mode <new|resume>  Explicit new scope or bound intake recovery; requires --intake and --run
-  --ur-action revise  Explicit unapproved UR revision; requires revision-bound resume intake
-  --prd-action revise Explicit unapproved PRD revision; requires revision-bound resume intake
-  --sd-action revise Explicit unapproved SD revision; requires revision-bound resume intake
-  --tp-action revise Explicit unapproved TP revision; requires revision-bound resume intake
-  --continue-delivery  Bound internal continuation; excludes intake and read-only status
-  --preview|--apply|--inspect|--recover
-                 Explicit run-revise mode; no mode keeps the early PRD revision path
-  --source-gate <UR|PRD|SD|TP>
-                 Earliest changed approved source in a reviewed late proposal
-  --preview-digest <sha256>
-                 Exact read-only late revision preview required by --apply
-  --operation <uuid>     Explicit idempotent approval or source revision command identity
-  --assurance <lane>     Only cooperative_local is supported; no independent human proof
-  --presentation <uuid>  Previously prepared run-present binding required for run-approve
-  --intake       Declare the governed delivery intake (delivery.start) for a gate-check skill-dispatch
-  --target-candidate <absolute-path>
-                 Repeat to expose competing plausible targets
-  --evidence-source <value>
-                 Repeat to report non-authorizing evidence sources
-  --target-changed
-                 Mark an explicit replacement of a previously confirmed target
-  --all-active   Evaluate every active run (doctor and delivery-map only)
-  --surface <codex|claude|copilot|opencode|generic>
-                 Declare the selected coding-agent surface
-  --scope <repository|global|project|user>
-                 Select the lifecycle mutation scope. MCP defaults to project.
-  --mcp-scope <project|user>
-                 Select the MCP scope for an explicitly coupled global uninstall.
-  --confirm      Apply a previously previewed global uninstall plan
+  Delivery writes use the fixed agdf-* command group and --command-file.
+  init --operation <original-uuid> preserves an interrupted initialization identity.
   --shared       Apply Copilot repository disable through shared .github/copilot/settings.json
   --runtime-checks <enable|manual|cancel>
                  Make the installation-time automatic-check decision explicitly; no TTY defaults to manual

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

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