create-agdf 0.20.1 → 0.30.0

package/generated/plugins/agdf/runtime/create-agdf/generated/plugins/agdf/meta/contracts/ur-definition.md

@@ -1,11 +1,44 @@
 # AGDF Runtime Contract — UR Definition
 
 This contract guides `ur-definition` only after a non-authorizing, bound
-`skill_continuation` with `phase: ur_definition`. It creates no gate or persistence authority.
+`skill_continuation` with `phase: ur_definition` or `phase: planned_ur_definition`.
+The same owner defines UR content in both modes. It creates no gate or persistence authority.
 
-## Binding and ownership
+## Planning mode before a Run
 
-Use only the returned governance_target, run_id, revision_id, artifact_path and template_path.
+For explicit capture/refinement/priority intent, dispatch this same skill with the confirmed
+target and `planning: {plan_id, expected_digest}`. Use null digest for capture and an inspected
+canonical digest for replacement. Planning is mutually exclusive with Run/revision, delivery
+intake, continue_delivery and source-revision selectors. Do not enter Run assignment to save a
+planned need. The optional planning plugin orchestrates this mode; Core owns its semantics.
+
+Follow `phase: planned_ur_definition` only. Read every returned authoring-inputs page for the
+version-matched UR template, current source and `planning_capability`. Use the same need,
+clarification, preview, language and summary rules below. An incomplete draft remains saveable
+with clarification open. Planning stops at UR and minimal metadata: never author planned PRD,
+SD or TP, present a gate, collect Approval: UR or infer delivery permission.
+
+Use `agdf_record/planned_material.stage` for one UR, then `planned_ur.create` or
+`planned_ur.replace` with that exact planning scope and original mutation UUID. Choose the new
+identity as `plan-<mutation UUID>` without asking the user for an identifier. Creation material
+contains the ordinary UR template without planning scalar fields: Core adds exactly one initial
+`Planning schema: planned-ur-v1`, `Planning id: <plan_id>` and `Planning priority: high|normal|low`.
+Default normal applies only on explicit create. Replacement preserves schema/identity and
+changes priority in that same UR source under its expected digest; no saved parallel title/status.
+No Run-bound material, generic file writer, shell fallback or copied template is permitted.
+
+Return the saved readable title, source reference/digest, priority and remaining clarification.
+Completeness/priority/selection never starts delivery. Only a later explicit request to start from
+the selected current source uses `agdf_run/run.create_from_planned`; read its contract and preserve
+the original UUID after uncertainty. The handoff creates one unapproved Run for normal UR review.
+A different UUID on an already transferred identity returns that Run. Historical planning source
+is read-only afterwards; later product edits use the active Run's existing revision owner.
+Inspect the original operation before retry. Missing/incompatible Core, unsafe/stale source,
+pending recovery or ambiguous origins stop the affected action with concrete diagnosis.
+
+## Run mode binding and ownership
+
+For `phase: ur_definition`, use only the returned governance_target, run_id, revision_id, artifact_path and template_path.
 template_path is the absolute, version-matched template owned by the installed plugin runtime.
 Repository copies under `.agdf/control/templates/` are derived scaffold references and never
 override this authoring source. Read the template without rewriting it; persist only artifact_path.
@@ -42,7 +75,7 @@ Preserve the requirement and name a concrete recovery or obtain an explicit scop
 cannot be delivered. Record the responsible later UX/PRD step in Next Step; UR authoring still
 writes only its assigned UR, not a preview or product implementation. A requested before-PRD preview
 is created through UX intent clarification under the existing post-UR routing owner. Its durable
-output belongs to `.agdf/control/artefacts/<run_id>/previews/` for the bound run; the UX skill owns
+output belongs to `.agdf/control/runs/<run_id>/evidence/previews/` for the bound run; the UX skill owns
 creation, versioning, evidence and references. An inline chat rendering alone does not fulfill that
 run deliverable. In a new UR, set exactly one initial metadata line before the first section:
 `Preview requirement: before_prd_interactive` for a required interactive before-PRD preview,
@@ -79,15 +112,16 @@ For new-format URs, a missing or invalid required summary returns to this same a
 route before presentation. Correct it through the existing revision writer; no user approval
 is required merely to complete an unapproved incomplete draft.
 
-## Revision and recording
+## Run mode revision and recording
 
 A new draft is recorded through existing run-step --step ur --title <short title>, using
 --dir <governance_target> --run <run_id> --revision <revision_id>.
 For an already registered unapproved draft, require explicit user revision intent. Resume
 through gate-check with intake true, intake_mode resume, run_id, expected_revision_id and
 ur_action revise (CLI --ur-action revise). Ordinary intake of a ready draft still presents it.
-After editing a registered draft use existing run-update, not run-step: the previous seal
-must be replaced by the canonical revision writer. Never edit an approved UR or its approval.
+Stage the replacement and use ur_draft.replace with the current binding. The writer
+publishes the document and typed evidence atomically. Never edit bound bytes, reseal
+an unknown change or alter an approved UR or its approval.
 Use the returned new revision, redispatch gate-check for this target/run, prepare the fresh
 run-present when supplied, show its returned text verbatim and wait for a NEW deliberate
 `Approval: UR`. Previous presentations/replies cannot approve a changed draft.

package/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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