create-agdf 0.20.1 → 0.30.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-closure.js

@@ -0,0 +1,343 @@
+import { pendingRunStepConflictIds } from './run-step-transaction.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWrite, withOwnedFileLock } from './run-state-writer.js';
+import { withControlMutation, markControlMutationEffect, readControlLayout, CURRENT_LAYOUT } from './control-layout.js';
+import { readPendingRunStepJournal } from './run-step-transaction.js';
+import { resolutionRecordVersion } from './input-resolution.js';
+import { canonicalJson, digest, DIGEST_PATTERN, exactObject, resolveControlCommandTarget } from './approval-command-contract.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN, APPROVAL_GATES } from './run-identity.js';
+import { parseRunState } from './run-state-parser.js';
+import { runSealState, listedArtefactPaths } from './run-seal.js';
+import { readRunOperations, closureLine, ENDED_LIFECYCLES } from './run-operations.js';
+import { readApprovalOperations } from './approval-operations.js';
+import { pendingRunStepIds } from './run-step-pending.js';
+import { recordRunStep } from './run-steps.js';
+import { policyForRunContent } from '../control-evaluation/run-step-policy.js';
+import { readArtefactHeading, prepareRunContentState } from '../control-evaluation/run-state.js';
+import { resolveHumanRunTitle } from '../interaction-presentation.js';
+import { readGitIdentity } from './git-identity.js';
+import { bindInputResolution, currentInputResolution, recordedInputResolution, resolutionRecord } from './input-resolution.js';
+import { inspectRunOperation } from './run-operation-status.js';
+import { assertInputConfigurationCurrent } from '../resources/configuration.js';
+
+// Closure of active Runs as superseded or abandoned. A preview is a stored, immutable and
+// non-authorizing working file; only the owner's exact phrase applies it, one Run at a time,
+// each through the existing run-step journal with its own sealed receipt.
+export const CLOSURE_OUTCOMES = Object.freeze(['superseded', 'abandoned']);
+export const CLOSURE_LIMITS = Object.freeze({ entries: 64, reason: 1024, reference: 512, preview_bytes: 1048576 });
+export const CLOSURE_PREVIEW_DIRECTORY = '.agdf/control/closure-previews';
+export const CLOSURE_PREVIEW_ID_PATTERN = /^[0-9a-f]{8}$/u;
+export const closurePhrase = previewId => `Close runs: ${previewId}`;
+export function closureOperationId(previewId, runId) {
+  const hex = createHash('sha256').update(`agdf-run-close/1\0${previewId}\0${runId}`, 'utf8').digest('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+const previewDigest = body => digest(canonicalJson(body));
+const singleLine = value => typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f\s]+/gu, ' ').replaceAll('|', '/').trim() : '';
+const language = value => String(value ?? '').toLowerCase().startsWith('de') ? 'de' : 'en';
+const ENTRY_FIELDS = ['run_id', 'outcome', 'reason', 'successor_run', 'successor_reference'];
+const NEXT = Object.freeze({
+  run_missing: 'Check the run id, then create a new preview.', run_unreadable: 'Repair the run file, then create a new preview.',
+  run_completed: 'none', run_already_ended: 'none', seal_invalid: 'Inspect the original operation and exact source bytes; resolve unconfirmed state before creating a new preview.',
+  changed_since_preview: 'Create a new preview.', not_active: 'none', successor_run_unknown: 'Create a new preview with an existing successor run or a free reference.',
+  run_write_locked: 'Retry the apply with the same preview while the run is unchanged.',
+  run_step_recovery_required: 'Recover the pending run step, then repeat the same apply.',
+  closure_write_failed: 'Repeat the same apply; if it fails again, inspect the run.',
+  closed_recovery_pending: 'Recover the pending Run step, then repeat the same apply.',
+  closure_recovery_pending: 'Recover the pending run step first, then create a new preview.',
+});
+const nextAction = reason => NEXT[reason] ?? 'Inspect the run, then create a new preview.';
+const NEXT_DE = Object.freeze({
+  run_missing: 'Run-ID prüfen, dann eine neue Vorschau erstellen.', run_unreadable: 'Run-Datei reparieren, dann eine neue Vorschau erstellen.',
+  run_completed: 'keiner', run_already_ended: 'keiner', seal_invalid: 'Ursprüngliche Operation und genaue Quellbytes prüfen; den ungeklärten Stand vor einer neuen Vorschau auflösen.',
+  changed_since_preview: 'Eine neue Vorschau erstellen.', not_active: 'keiner', successor_run_unknown: 'Eine neue Vorschau mit vorhandenem Nachfolge-Run oder freiem Verweis erstellen.',
+  run_write_locked: 'Mit derselben Vorschau erneut anwenden, solange der Run unverändert ist.',
+  run_step_recovery_required: 'Den offenen Run-Step wiederherstellen, dann dieselbe Anwendung wiederholen.',
+  closure_write_failed: 'Dieselbe Anwendung wiederholen; scheitert sie erneut, den Run prüfen.',
+  closed_recovery_pending: 'Den ursprünglichen offenen Run-Schritt wiederaufnehmen, dann dieselbe Anwendung wiederholen.',
+  closure_recovery_pending: 'Erst den offenen Run-Step wiederherstellen, dann eine neue Vorschau erstellen.',
+  preview_unknown: 'Eine neue Vorschau erstellen.', preview_invalid: 'Eine neue Vorschau erstellen.', preview_blocked: 'Eine neue Vorschau erstellen.',
+});
+const actionDe = (reason, text) => NEXT_DE[reason] ?? (String(reason).startsWith('confirmation_')
+  ? text.replace(/^Repeat with the exact phrase (.+)\.$/u, 'Mit dem genauen Satz $1 wiederholen.') : text);
+
+function readRunFile(root, runId) {
+  const relative = `.agdf/control/runs/${runId}/RUN_STATE.md`;
+  if (!RUN_ID_PATTERN.test(runId ?? '')) return { reason: 'run_missing' };
+  if (!existsSync(join(root, relative))) return { reason: 'run_missing' };
+  const file = hasSymlinkComponent(root, relative) ? { status: 'invalid' } : containedRegularFile(root, relative);
+  if (file.status !== 'valid') return { reason: 'run_unreadable' };
+  try {
+    const content = readFileSync(file.path, 'utf8'), parsed = parseRunState(content, runId);
+    return parsed.valid ? { content, meta: parsed.meta, path: file.path } : { reason: 'run_unreadable' };
+  } catch { return { reason: 'run_unreadable' }; }
+}
+
+// Refusals name each affected entry before anything is stored.
+function entryProblems(root, entries) {
+  if (!Array.isArray(entries) || !entries.length || entries.length > CLOSURE_LIMITS.entries) return [{ index: null, run_id: null, problem: 'entries_invalid' }];
+  const problems = [], seen = new Set();
+  entries.forEach((entry, index) => {
+    const add = problem => problems.push({ index, run_id: typeof entry?.run_id === 'string' ? entry.run_id : null, problem });
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some(key => !ENTRY_FIELDS.includes(key))) return add('entry_fields_invalid');
+    if (typeof entry.run_id !== 'string' || !RUN_ID_PATTERN.test(entry.run_id)) add('run_id_invalid');
+    else if (seen.has(entry.run_id)) add('run_id_duplicate');
+    seen.add(entry.run_id);
+    if (!CLOSURE_OUTCOMES.includes(entry.outcome)) add('outcome_invalid');
+    const reason = singleLine(entry.reason);
+    if (!reason) add('reason_missing'); else if (reason.length > CLOSURE_LIMITS.reason) add('reason_too_long');
+    const run = entry.successor_run !== undefined, reference = entry.successor_reference !== undefined;
+    if (entry.outcome === 'abandoned' && (run || reference)) add('successor_not_allowed');
+    if (entry.outcome === 'superseded') {
+      if (run && reference) add('successor_ambiguous');
+      else if (!run && !reference) add('successor_missing');
+      else if (run && entry.successor_run === entry.run_id) add('successor_run_self');
+      else if (run && (typeof entry.successor_run !== 'string' || readRunFile(root, entry.successor_run).reason)) add('successor_run_unknown');
+      else if (reference && !singleLine(entry.successor_reference)) add('successor_missing');
+      else if (reference && singleLine(entry.successor_reference).length > CLOSURE_LIMITS.reference) add('successor_reference_too_long');
+    }
+  });
+  return problems;
+}
+
+function lastActivity(content, meta) {
+  const stamps = [...readRunOperations(content).receipts.map(row => row.created_at),
+    ...readApprovalOperations(content).receipts.map(row => row.created_at)].filter(Boolean).sort();
+  return stamps.at(-1) ?? meta.updated_at ?? null;
+}
+
+// Per-run facts the owner needs to decide, read only from the sealed Run and its UR heading.
+function previewEntry(root, entry) {
+  const successor = entry.outcome !== 'superseded' ? null : entry.successor_run !== undefined
+    ? { kind: 'run', value: entry.successor_run, verified: true } : { kind: 'reference', value: singleLine(entry.successor_reference), verified: false };
+  const row = { run_id: entry.run_id, outcome: entry.outcome, reason: singleLine(entry.reason), successor, revision_id: null,
+    closable: false, not_closable: null, facts: null, warnings: [] };
+  const run = readRunFile(root, entry.run_id);
+  const refuse = reason => ({ ...row, not_closable: { reason, next_action: nextAction(reason) } });
+  if (run.reason) return refuse(run.reason);
+  const control = prepareRunContentState(root, run.content, run.path);
+  const approved = APPROVAL_GATES.filter(gate => control.approvals.get(gate)?.status === 'approved');
+  const gate = control.current_gate;
+  row.revision_id = run.meta.revision_id;
+  row.facts = { title: resolveHumanRunTitle({ urHeading: readArtefactHeading(root, control.artefacts.get('UR')).replace(/^UR:\s*/iu, ''), runContent: run.content, runId: entry.run_id }),
+    lifecycle: run.meta.lifecycle, current_gate: gate, approved_gates: approved,
+    open_approvals: APPROVAL_GATES.filter(name => !approved.includes(name) && control.approvals.get(name)?.status !== 'not_applicable'),
+    last_activity: lastActivity(run.content, run.meta), artefact_count: listedArtefactPaths(run.content).length };
+  if (approved.length) row.warnings.push('approved_gates_exist');
+  if (['CD+Tests', 'CR', 'QA', 'UAT', 'OR'].includes(gate) || ['CD+Tests', 'CR'].some(type => ['done', 'revise', 'block'].includes(control.artefacts.get(type)?.status))) row.warnings.push('implementation_started');
+  if (successor?.verified === false) row.warnings.push('successor_unverified');
+  if (run.meta.lifecycle === 'completed') return refuse('run_completed');
+  if (ENDED_LIFECYCLES.includes(run.meta.lifecycle)) return refuse('run_already_ended');
+  if (runSealState(root, run.content).status !== 'valid') return refuse('seal_invalid');
+  return { ...row, closable: true };
+}
+
+// Exclusive creation of one immutable preview file per random 8-hex id, written atomically.
+function storePreview(root, body) {
+  return withControlMutation(root, { resource: 'closure-preview', operation_id: currentInputResolution()?.operation_id ?? null },
+    () => storePreviewAdmitted(root, body));
+}
+
+function storePreviewAdmitted(root, body) {
+  assertInputConfigurationCurrent(root);
+  if (hasSymlinkComponent(root, CLOSURE_PREVIEW_DIRECTORY)) throw Error('AGDF_RUN_PATH_INVALID');
+  const directory = join(root, CLOSURE_PREVIEW_DIRECTORY);
+  try { mkdirSync(directory); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  if (!statSync(directory).isDirectory()) throw Error('AGDF_RUN_PATH_INVALID');
+  for (let attempt = 0; attempt < 16; attempt++) {
+    const resolution = currentInputResolution();
+    const id = resolution?.operation_id?.slice(0, 8) ?? randomBytes(4).toString('hex'), path = join(directory, `${id}.json`);
+    if (resolution && existsSync(path)) {
+      const loaded = readPreview(root, id);
+      if (loaded.reason || recordedInputResolution(loaded.preview)?.logical_digest !== resolution.logical_digest) throw Error('operation_payload_conflict');
+      return loaded.preview;
+    }
+    const preview = bindInputResolution({ ...body, preview_id: id });
+    const stored = { ...preview, preview_digest: previewDigest(preview) };
+    if (withOwnedFileLock(path, () => withControlMutation(root, { resource: `closure-preview:${id}`, operation_id: resolution?.operation_id ?? null },
+      () => existsSync(path) ? false : (markControlMutationEffect(), atomicWrite(path, `${JSON.stringify(stored, null, 2)}\n`), true)))) return stored;
+  }
+  throw Error('AGDF_CLOSURE_PREVIEW_UNAVAILABLE');
+}
+
+const validStoredEntry = row => exactObject(row, ['run_id', 'outcome', 'reason', 'successor', 'revision_id', 'closable', 'not_closable', 'facts', 'warnings'])
+  && RUN_ID_PATTERN.test(row.run_id) && CLOSURE_OUTCOMES.includes(row.outcome) && closureLine(row.reason, CLOSURE_LIMITS.reason)
+  && typeof row.closable === 'boolean' && (!row.closable || REVISION_ID_PATTERN.test(row.revision_id ?? '') && row.not_closable === null)
+  && (row.closable || exactObject(row.not_closable, ['reason', 'next_action'])) && Array.isArray(row.warnings);
+function readPreview(root, previewId) {
+  if (typeof previewId !== 'string' || !CLOSURE_PREVIEW_ID_PATTERN.test(previewId)) return { reason: 'preview_unknown' };
+  const relative = `${CLOSURE_PREVIEW_DIRECTORY}/${previewId}.json`;
+  if (!existsSync(join(root, relative))) return { reason: 'preview_unknown' };
+  const file = hasSymlinkComponent(root, relative) ? { status: 'invalid' } : containedRegularFile(root, relative);
+  if (file.status !== 'valid' || statSync(file.path).size > CLOSURE_LIMITS.preview_bytes) return { reason: 'preview_invalid' };
+  try {
+    const raw = JSON.parse(readFileSync(file.path, 'utf8')), { preview_digest: recorded, ...body } = raw;
+    const stored = resolutionRecord(raw);
+    if (!stored) return { reason: 'preview_invalid' };
+    if (!exactObject(stored, ['schema_version', 'preview_id', 'created_at', 'target_id', 'blocked', 'entries', 'preview_digest'])
+      || stored.schema_version !== '1' || stored.preview_id !== previewId || !DIGEST_PATTERN.test(recorded ?? '') || recorded !== previewDigest(body)
+      || stored.target_id !== resolveControlCommandTarget(root).target_id || !Array.isArray(stored.entries)
+      || !stored.entries.length || stored.entries.length > CLOSURE_LIMITS.entries || !stored.entries.every(validStoredEntry)) return { reason: 'preview_invalid' };
+    return { preview: raw };
+  } catch { return { reason: 'preview_invalid' }; }
+}
+
+// Existing preview/per-Run records remain the only closure persistence owners.
+export function inspectClosureInputResolution(root, input) {
+  if (input.command.kind === 'closure.preview') {
+    const loaded = readPreview(root, input.operation_id.slice(0, 8));
+    if (loaded.reason === 'preview_unknown') return null;
+    if (loaded.reason) throw Error('original_operation_unconfirmed');
+    return { known: true, resolution: recordedInputResolution(loaded.preview) };
+  }
+  const loaded = readPreview(root, input.command.payload.preview_id);
+  if (loaded.reason) return null; // The existing apply owner reports selector errors.
+  for (const entry of loaded.preview.entries) {
+    const id = closureOperationId(loaded.preview.preview_id, entry.run_id);
+    const observed = inspectRunOperation(root, { runId: entry.run_id, operationId: id, targetId: input.target_id });
+    let resolution = recordedInputResolution(observed.receipt);
+    if (observed.status === 'pending') resolution = recordedInputResolution(readPendingRunStepJournal(root, entry.run_id));
+    if (resolution?.operation_id === input.operation_id && resolution.kind === 'closure.apply') return { known: true, resolution };
+  }
+  return null;
+}
+
+function safePreviewEntry(root, entry, beforeFacts) {
+  try { beforeFacts?.(entry.run_id); return previewEntry(root, entry); }
+  catch {
+    return { run_id: entry.run_id, outcome: entry.outcome, reason: singleLine(entry.reason), successor: null, revision_id: null, closable: false,
+      not_closable: { reason: 'run_unreadable', next_action: nextAction('run_unreadable') }, facts: null, warnings: [] };
+  }
+}
+
+// `beforeFacts` is a package-owned test seam for a failing per-run observation.
+export function previewRunClosure(root, { entries, language: requested } = {}, { beforeFacts } = {}) {
+  const lang = language(requested);
+  const problems = entryProblems(root, entries);
+  if (problems.length) return finish({ schema_version: '1', outcome: 'rejected', reason: 'closure_entries_invalid', problems,
+    next_action: 'Add the reason, add or correct the successor, give a free reference, or choose abandoned; then request a new preview.', authorizes: false }, lang);
+  const sharedPending = new Set(pendingRunStepConflictIds(root, null));
+  const selectedIds = new Set(entries.map(entry => entry.run_id));
+  const pending = pendingRunStepIds(root).filter(id => selectedIds.has(id) || sharedPending.has(id));
+  let stored;
+  try {
+    stored = storePreview(root, { schema_version: '1', created_at: new Date().toISOString(), target_id: resolveControlCommandTarget(root).target_id,
+      blocked: pending.length ? { reason: 'closure_recovery_pending', pending_run_ids: pending, next_action: nextAction('closure_recovery_pending') } : null,
+      entries: entries.map(entry => safePreviewEntry(root, entry, beforeFacts)) });
+  } catch { return finish({ schema_version: '1', outcome: 'rejected', reason: 'closure_preview_unavailable', authorizes: false }, lang); }
+  return finish({ schema_version: '1', outcome: 'preview', preview_id: stored.preview_id, preview_digest: stored.preview_digest,
+    preview_path: `${CLOSURE_PREVIEW_DIRECTORY}/${stored.preview_id}.json`, confirmation_phrase: stored.blocked ? null : closurePhrase(stored.preview_id),
+    run_count: stored.entries.length, closable_count: stored.entries.filter(row => row.closable).length, blocked: stored.blocked,
+    entries: stored.entries, authorizes: false }, lang);
+}
+
+function closeEntry(root, preview, entry, confirmedBy, { packageVersion, afterWrite }) {
+  const base = { run_id: entry.run_id, outcome: entry.outcome, successor: entry.successor };
+  const notClosed = (reason, extra = {}) => ({ ...base, result: 'not_closed', reason, next_action: nextAction(reason), ...extra });
+  if (!entry.closable) return { ...base, result: 'not_closed', ...entry.not_closable };
+  if (entry.successor?.kind === 'run' && readRunFile(root, entry.successor.value).reason) return notClosed('successor_run_unknown');
+  const record = { lifecycle: entry.outcome, reason: entry.reason, successor: entry.successor, confirmed_by: confirmedBy,
+    preview: { id: preview.preview_id, digest: preview.preview_digest } };
+  const context = { kind: 'lifecycle_close.record', operation_id: closureOperationId(preview.preview_id, entry.run_id), target_id: preview.target_id,
+    request_digest: digest(canonicalJson({ contract: 'agdf-run-close/1', preview_id: preview.preview_id, preview_digest: preview.preview_digest,
+      run_id: entry.run_id, revision_id: entry.revision_id, lifecycle: entry.outcome, reason: entry.reason, successor: entry.successor })) };
+  let result;
+  try {
+    result = recordRunStep(root, { runId: entry.run_id, revisionId: entry.revision_id, step: 'lifecycle_close', closure: record },
+      { policy: policyForRunContent, packageVersion, operationContext: context, afterWrite });
+  } catch (error) { return notClosed('closure_write_failed', { detail: String(error?.message ?? error).slice(0, 256) }); }
+  if (result.outcome === 'recorded') return { ...base, result: 'closed', operation_id: context.operation_id, revision_id: result.revision_id };
+  if (result.outcome === 'already_applied') return { ...base, result: 'already_closed', operation_id: context.operation_id };
+  const reason = { stale_revision: 'changed_since_preview', lifecycle_ended: 'not_active' }[result.reason] ?? result.reason;
+  if (result.committed) return { ...base, result: 'closed_recovery_pending', reason, operation_id: context.operation_id, revision_id: result.revision_id,
+    next_action: nextAction('closed_recovery_pending') };
+  return notClosed(reason);
+}
+
+export function applyRunClosure(root, { previewId, confirmation, language: requested } = {}, { packageVersion = '0.14.5', afterWrite, readIdentity = readGitIdentity } = {}) {
+  const lang = language(requested);
+  const refuse = (reason, extra = {}) => finish({ schema_version: '1', outcome: 'rejected', reason, preview_id: typeof previewId === 'string' ? previewId : null,
+    applied: false, next_action: extra.next_action ?? { preview_unknown: 'Create a new preview.', preview_invalid: 'Create a new preview.', preview_blocked: 'Create a new preview.' }[reason]
+      ?? `Repeat with the exact phrase ${CLOSURE_PREVIEW_ID_PATTERN.test(previewId ?? '') ? closurePhrase(previewId) : 'of the preview'}.`, ...extra, authorizes: false }, lang);
+  const loaded = readPreview(root, previewId);
+  if (loaded.reason) return refuse(loaded.reason);
+  const preview = loaded.preview, phrase = closurePhrase(preview.preview_id), reply = typeof confirmation === 'string' ? confirmation.trim() : '';
+  if (!reply) return refuse('confirmation_missing');
+  if (reply !== phrase) return refuse(/^Close runs: [0-9a-f]{8}$/u.test(reply) ? 'confirmation_other_preview' : 'confirmation_mismatch');
+  const sharedPending = new Set(pendingRunStepConflictIds(root, null));
+  const selectedIds = new Set(preview.entries.map(entry => entry.run_id));
+  const pending = pendingRunStepIds(root).filter(id => selectedIds.has(id) || sharedPending.has(id));
+  if (pending.length) return refuse('closure_recovery_pending', { pending_run_ids: pending, next_action: nextAction('closure_recovery_pending') });
+  if (preview.blocked) return refuse('preview_blocked');
+  const confirmedBy = readIdentity(root);
+  const results = preview.entries.map(entry => closeEntry(root, preview, entry, confirmedBy, { packageVersion, afterWrite }));
+  return finish({ schema_version: '1', outcome: 'applied', preview_id: preview.preview_id, preview_digest: preview.preview_digest, applied: true,
+    confirmed_by: confirmedBy, closed_count: results.filter(row => row.result === 'closed').length,
+    recovery_pending_count: results.filter(row => row.result === 'closed_recovery_pending').length, run_count: results.length, results, authorizes: false }, lang);
+}
+
+// Rendering in German or English; the confirmation phrase is always the fixed English text.
+const COPY = {
+  en: { previewHeading: (id, n, d) => `Closure preview ${id} · ${n} run${n === 1 ? '' : 's'} · digest ${d}`,
+    finality: 'A closed run is final: it cannot be reopened, and continuing the work needs a new run.',
+    phrase: phrase => `To close the closable runs below, reply exactly: ${phrase}`,
+    blocked: ids => `Blocked: pending run-step recovery in ${ids.join(', ')}. ${NEXT.closure_recovery_pending}`, action: (reason, text) => text,
+    gate: 'Gate', open: 'Open approvals', activity: 'Last activity', artefacts: 'Artefacts', none: 'none', unknown: 'unknown',
+    outcome: row => row.outcome === 'superseded' ? `superseded by ${row.successor.value}${row.successor.verified ? '' : ' (unverified reference)'}` : 'abandoned',
+    outcomeLabel: 'Outcome', reasonLabel: 'Reason', warningsLabel: 'Warnings', next: 'Next',
+    warnings: { approved_gates_exist: 'approved gates exist', implementation_started: 'implementation has started', successor_unverified: 'the successor is an unverified free reference' },
+    notClosable: 'Not closable', resultHeading: (id, closed, n, d) => `Closure result ${id} · ${closed} of ${n} closed · digest ${d}`,
+    recoveryPending: row => `closed as ${row.outcome}; Run recovery pending (${row.reason})`,
+    confirmedBy: 'Confirmed by', cooperative: 'cooperative local Git statement', unknownPerson: 'unknown (no local Git identity found)',
+    closed: row => `closed as ${row.outcome === 'superseded' ? `superseded by ${row.successor.value}${row.successor.verified ? '' : ' (unverified reference)'}` : 'abandoned'}`,
+    already: 'already closed by this preview', notClosed: 'not closed',
+    rejected: 'Nothing was applied.', refusal: 'Refused; no preview was stored.' },
+  de: { previewHeading: (id, n, d) => `Abschlussvorschau ${id} · ${n} ${n === 1 ? 'Run' : 'Runs'} · Digest ${d}`,
+    finality: 'Ein geschlossener Run ist endgültig: Er kann nicht wieder geöffnet werden; für weitere Arbeit braucht es einen neuen Run.',
+    phrase: phrase => `Zum Schließen der schließbaren Runs genau antworten: ${phrase}`,
+    blocked: ids => `Blockiert: offene Run-Step-Wiederherstellung in ${ids.join(', ')}. ${NEXT_DE.closure_recovery_pending}`, action: actionDe,
+    gate: 'Gate', open: 'Offene Freigaben', activity: 'Letzte Aktivität', artefacts: 'Artefakte', none: 'keine', unknown: 'unbekannt',
+    outcome: row => row.outcome === 'superseded' ? `ersetzt durch ${row.successor.value}${row.successor.verified ? '' : ' (ungeprüfter Verweis)'}` : 'aufgegeben',
+    outcomeLabel: 'Ergebnis', reasonLabel: 'Grund', warningsLabel: 'Warnungen', next: 'Nächster Schritt',
+    warnings: { approved_gates_exist: 'es gibt freigegebene Gates', implementation_started: 'die Umsetzung hat begonnen', successor_unverified: 'der Nachfolger ist ein ungeprüfter freier Verweis' },
+    notClosable: 'Nicht schließbar', resultHeading: (id, closed, n, d) => `Abschlussergebnis ${id} · ${closed} von ${n} geschlossen · Digest ${d}`,
+    recoveryPending: row => `geschlossen als ${row.outcome === 'superseded' ? 'ersetzt' : 'aufgegeben'}; Run-Wiederherstellung offen (${row.reason})`,
+    confirmedBy: 'Bestätigt durch', cooperative: 'kooperative Angabe aus der lokalen Git-Identität', unknownPerson: 'unbekannt (keine lokale Git-Identität gefunden)',
+    closed: row => `geschlossen als ${row.outcome === 'superseded' ? `ersetzt durch ${row.successor.value}${row.successor.verified ? '' : ' (ungeprüfter Verweis)'}` : 'aufgegeben'}`,
+    already: 'bereits durch diese Vorschau geschlossen', notClosed: 'nicht geschlossen',
+    rejected: 'Es wurde nichts angewendet.', refusal: 'Abgelehnt; es wurde keine Vorschau gespeichert.' },
+};
+const shortDigest = value => String(value ?? '').replace(/^sha256:/u, '').slice(0, 12);
+export function renderRunClosure(result, requested) {
+  const c = COPY[language(requested)], lines = [];
+  if (result.outcome === 'preview') {
+    lines.push(c.previewHeading(result.preview_id, result.run_count, shortDigest(result.preview_digest)), c.finality);
+    lines.push(result.blocked ? c.blocked(result.blocked.pending_run_ids) : c.phrase(result.confirmation_phrase), '');
+    result.entries.forEach((row, i) => {
+      lines.push(`${i + 1}. ${row.facts?.title ?? row.run_id} · \`${row.run_id}\``);
+      if (row.facts) lines.push(`   ${c.gate}: ${row.facts.current_gate} · ${c.open}: ${row.facts.open_approvals.join(', ') || c.none} · ${c.activity}: ${row.facts.last_activity ?? c.unknown} · ${c.artefacts}: ${row.facts.artefact_count}`);
+      lines.push(`   ${c.outcomeLabel}: ${c.outcome(row)}`, `   ${c.reasonLabel}: ${row.reason}`);
+      if (row.warnings.length) lines.push(`   ${c.warningsLabel}: ${row.warnings.map(key => c.warnings[key] ?? key).join('; ')}`);
+      if (!row.closable) lines.push(`   ${c.notClosable}: ${row.not_closable.reason} · ${c.next}: ${c.action(row.not_closable.reason, row.not_closable.next_action)}`);
+    });
+  } else if (result.outcome === 'applied') {
+    const person = result.confirmed_by.statement === 'unknown' ? c.unknownPerson
+      : `${[result.confirmed_by.name, result.confirmed_by.email && `<${result.confirmed_by.email}>`].filter(Boolean).join(' ')} (${c.cooperative})`;
+    lines.push(c.resultHeading(result.preview_id, result.closed_count, result.run_count, shortDigest(result.preview_digest)), `${c.confirmedBy}: ${person}`, '');
+    result.results.forEach((row, i) => {
+      lines.push(`${i + 1}. \`${row.run_id}\`: ${row.result === 'closed' ? c.closed(row) : row.result === 'already_closed' ? c.already
+        : row.result === 'closed_recovery_pending' ? `${c.recoveryPending(row)} · ${c.next}: ${c.action(row.result, row.next_action)}`
+        : `${c.notClosed}: ${row.reason} · ${c.next}: ${c.action(row.reason, row.next_action)}`}`);
+    });
+  } else {
+    lines.push(`${result.problems ? c.refusal : c.rejected} ${result.reason}`);
+    for (const problem of result.problems ?? []) lines.push(`- ${problem.run_id ?? `#${problem.index ?? '-'}`}: ${problem.problem}`);
+    if (result.pending_run_ids) lines.push(`- ${result.pending_run_ids.join(', ')}`);
+    if (result.next_action) lines.push(`${c.next}: ${c.action(result.reason, result.next_action)}`);
+  }
+  return lines.join('\n');
+}
+const finish = (result, lang) => Object.freeze({ ...result, presentation_language: lang, text: renderRunClosure(result, lang) });

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-command-contract.js

@@ -1,141 +1,55 @@
+import { projectMcpInputSchema } from '../mcp-input-schema.js';
+// Compatibility facade: existing exports retain the same schema/validator objects.
+export { RUN_COMMAND_VERSION, RUN_COMMAND_LIMITS, TARGET_SCOPED_COMMAND_KINDS, PLANNING_COMMAND_KINDS, PLANNING_SCOPE_SCHEMA, strictObject, MATERIAL_REFERENCE_SCHEMA, RUN_COMMAND_DESCRIPTORS, RUN_COMMAND_GROUPS, commandGroupSchema, compactCommandSchema, RUN_COMMAND_RESULT_SCHEMA, commandResultSchema, validateRunCommandResult, commandGroupDefinition, schemaDiagnostics, validateRunCommand, runCommandRequestDigest } from './run-command-schema.js';
+import { RUN_COMMAND_GROUPS, RUN_COMMAND_VERSION, RUN_COMMAND_DESCRIPTORS, payloadSchema, describeFields, strictObject, commandEnvelope, RUN_COMMAND_RESULT_SCHEMA, RUN_COMMAND_LIMITS } from './run-command-schema.js';
 import { UR_AUTHORING_FORMAT } from '../control-evaluation/ur-readiness.js';
 import { PRD_DECISION_FORMAT } from '../control-evaluation/prd-readiness.js';
 import { SD_DECISION_FORMAT } from '../control-evaluation/sd-readiness.js';
-import { DIGEST_PATTERN, canonicalJson, digest } from './approval-command-contract.js';
-import { RUN_ID_PATTERN, REVISION_ID_PATTERN, APPROVAL_GATES } from './run-identity.js';
-import { TASK_TARGET_SOURCES } from '../task-target-resolution.js';
-import { PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE } from '../interaction-presentation.js';
 import { ACCEPTANCE_CRITERIA_FORMAT, TP_AUTHORING_FORMAT } from '../control-evaluation/traceability-readiness.js';
 import { UX_DECISION_FORMAT } from '../control-evaluation/definition-sources.js';
-import { REVIEWED_REQUEST_FORMAT, REVISION_PROPOSAL_FORMAT } from './recording-formats.js';
+import { REVIEWED_BINDING_FORMAT, REVISION_PROPOSAL_FORMAT } from './recording-formats.js';
 import { relationshipForGate } from '../control-evaluation/delivery-relationships.js';
 import { PREVIEW_REVIEW_FORMAT } from './preview-review.js';
+import { closeoutConfirmation, QUICK_CLOSEOUT_AUTHORING_FORMAT } from '../control-evaluation/closeout-readiness.js';
 
-export const RUN_COMMAND_VERSION = '1';
-export const RUN_COMMAND_LIMITS = Object.freeze({ input_bytes: 65536, result_bytes: 1048576, definition_bytes: 8192, aggregate_definition_bytes: 24576 });
-const string = (maxLength = 4096) => ({ type: 'string', minLength: 1, maxLength });
-const identity = { type: 'string', pattern: REVISION_ID_PATTERN.source };
-const hash = { type: 'string', pattern: DIGEST_PATTERN.source };
-const enumeration = values => ({ enum: [...values] });
-export const strictObject = (properties, required = Object.keys(properties)) => ({ type: 'object', additionalProperties: false, properties, required });
-const source = strictObject({ path: string(), digest: hash });
-const recoveryGroups = Object.freeze({ 'step.record': 'agdf_record', 'artefact.record': 'agdf_record',
-  'presentation_decision.record': 'agdf_record', 'prd_revision.reopen': 'agdf_revise', 'closeout.record': 'agdf_closeout' });
-const recovery = strictObject({ original_kind: enumeration(Object.keys(recoveryGroups)), pending_digest: hash, recovery_revision_id: identity });
-const recordStep = { oneOf: [
-  strictObject({ step: { const: 'ur' }, source, title: string(1024) }),
-  strictObject({ step: { const: 'route' }, source, reason: string(8192), route: enumeration(['quick_task', 'structured_slice', 'structured_delivery']) }),
-  strictObject({ step: { const: 'review' }, source, decision: enumeration(['pass', 'revise', 'block']) }),
-  strictObject({ step: { const: 'evidence' }, source, reason: string(8192), covers: string(1024) }),
-  { oneOf: [strictObject({ step: { const: 'internal' }, source,
-    internal_step: { const: 'UX Intent Definition' }, decision: enumeration(['ready', 'blocked', 'not_applicable']), reason: string(8192), covers: string(1024),
-  }, ['step', 'source', 'internal_step', 'decision']), strictObject({ step: { const: 'internal' }, source,
-    internal_step: enumeration(['Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR']),
-    decision: enumeration(['pass', 'revise', 'block', 'not_applicable']), reason: string(8192), covers: string(1024),
-  }, ['step', 'source', 'internal_step', 'decision'])] },
-] };
 
-const spec = (group, payload, owner, effects, confirmation = 'authorized_recording') => ({ group, payload_schema: payload, owner, effects, confirmation });
-const proposal = strictObject({ source_gate: enumeration(['UR', 'PRD', 'SD', 'TP']), proposal: source });
-const apply = strictObject({ ...proposal.properties, preview_digest: hash, confirmation: string(8192) });
-const closeout = strictObject({ or: source, confirmation: string(8192) });
-const descriptors = {
-  'runtime_generation.replace': spec('agdf_record', strictObject({ candidate: source, confirmation: string(256) }), 'owned-runtime-generation.replace', ['replace only the serving facade own runtime; no Run or gate write'], 'concrete_candidate_digest'),
-  'presentation.prepare': spec('agdf_prepare', strictObject({ gate: enumeration(APPROVAL_GATES) }), 'run-presentation.prepareRunPresentation', ['create immutable exact presentation'], 'no_gate_approval'),
-  'step.record': spec('agdf_record', recordStep, 'run-steps.recordRunStep', ['register bounded actual internal/evidence result; update Run/backlog']),
-  'artefact.record': spec('agdf_record', strictObject({ gate: enumeration(['PRD', 'SD', 'TP', 'QA']), reviewed_request: source }), 'run-artefact-recording.prepareArtefactRecording', ['register reviewed source mapping; replace only unapproved draft']),
-  'approval.record': spec('agdf_approve', strictObject({ gate: enumeration(APPROVAL_GATES), presentation_id: identity, response: string(8192) }), 'approval-command.executeApprovalCommand', ['record one exact deliberate gate reply'], 'new_deliberate_exact_reply'),
-  'presentation_decision.record': spec('agdf_record', strictObject({ gate: enumeration(APPROVAL_GATES), presentation_id: identity,
-    action: enumeration(['request_change', 'reject']), comment: { type: 'string', maxLength: 8192 } }),
-    'run-steps.recordRunPresentationDecision', ['record one exact deliberate change request or rejection; no gate approval'], 'new_deliberate_bound_human_reply'),
-  'source_revision.preview': spec('agdf_revise', proposal, 'run-revision.previewSourceRevision', ['read exact revision impact'], 'no_mutation'),
-  'source_revision.apply': spec('agdf_revise', apply, 'run-revision.applySourceRevision', ['archive selected material; invalidate affected decisions; reopen earliest source'], 'exact_material_confirmation'),
-  'source_revision.recover': spec('agdf_revise', strictObject({ proposal: source, source_gate: enumeration(['UR', 'PRD', 'SD', 'TP']), recovery_revision_id: identity, pending_digest: hash }), 'run-revision.recoverSourceRevision', ['recover original bounded source revision'], 'original_confirmed_effect'),
-  'prd_revision.reopen': spec('agdf_revise', strictObject({ prd: source, confirmation: string(8192) }), 'run-revision.reopenPrdRevision', ['reopen existing early PRD boundary preserving history'], 'exact_material_confirmation'),
-  'closeout.record': spec('agdf_closeout', closeout, 'run-steps.recordRunStep', ['publish exact OR; complete selected Run; synchronize selected backlog'], 'exact_material_confirmation'),
-  'operation.recover': { ...spec(null, recovery, 'run-step-transaction.recoverPendingRunStep', ['recover original bounded owned outputs and selected backlog'], 'original_confirmed_effect'), groups: ['agdf_record', 'agdf_revise', 'agdf_closeout'] },
-};
-function freeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(freeze); Object.freeze(value); } return value; }
-export const RUN_COMMAND_DESCRIPTORS = freeze(descriptors);
-export const RUN_COMMAND_GROUPS = freeze({
-  agdf_prepare: ['presentation.prepare'], agdf_record: ['step.record', 'artefact.record', 'presentation_decision.record', 'runtime_generation.replace', 'operation.recover'],
-  agdf_approve: ['approval.record'], agdf_revise: ['source_revision.preview', 'source_revision.apply', 'source_revision.recover', 'prd_revision.reopen', 'operation.recover'],
-  agdf_closeout: ['closeout.record', 'operation.recover'],
-});
-const envelope = {
-  schema_version: { const: RUN_COMMAND_VERSION }, presentation_language: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE },
-  working_directory: string(), target_source: enumeration(TASK_TARGET_SOURCES), primary_target: string(), target_id: hash,
-  run_id: { type: 'string', pattern: RUN_ID_PATTERN.source }, expected_revision_id: identity, operation_id: identity,
-  assurance: { const: 'cooperative_local' },
-};
-function payloadSchema(group, kind) {
-  return kind === 'operation.recover' ? strictObject({ ...recovery.properties,
-    original_kind: enumeration(Object.keys(recoveryGroups).filter(original => recoveryGroups[original] === group)) })
-    : RUN_COMMAND_DESCRIPTORS[kind].payload_schema;
-}
-export function commandGroupSchema(group) {
-  const kinds = RUN_COMMAND_GROUPS[group]; if (!kinds) throw Error('command_group_unsupported');
-  return strictObject({ ...envelope, command: { oneOf: kinds.map(kind => strictObject({ kind: { const: kind }, payload: payloadSchema(group, kind) })) } });
-}
-export function commandGroupDefinition(group) {
-  const definition = { name: group,
-    description: `${group}: ${RUN_COMMAND_GROUPS[group]?.join(', ')}. Exact target/Run/revision/UUID required. Cooperative caller intent only; tool permission never approves a gate. Inspect operation-contract before use; retry original UUID via operation-status after uncertainty. No VCS.`,
-    annotations: { readOnlyHint: false, destructiveHint: group !== 'agdf_prepare', idempotentHint: false, openWorldHint: false }, inputSchema: commandGroupSchema(group) };
-  if (Buffer.byteLength(JSON.stringify(definition)) > RUN_COMMAND_LIMITS.definition_bytes) throw Error('command_definition_budget_exceeded');
-  return freeze(definition);
-}
-// A deliberately small schema interpreter over the same generated JSON Schema subset.
-// No caller validator, accessor execution, coercion or default-expanded effect is allowed.
-export function schemaDiagnostics(value, schema, path = '$') {
-  const errors = [];
-  if (schema.oneOf) return schema.oneOf.filter(choice => schemaDiagnostics(value, choice, path).length === 0).length === 1 ? [] : [{ path, code: 'one_of_invalid' }];
-  if (Object.hasOwn(schema, 'const') && value !== schema.const) errors.push({ path, code: 'constant_invalid' });
-  if (schema.enum && !schema.enum.includes(value)) errors.push({ path, code: 'enum_invalid' });
-  if (schema.type === 'object') {
-    if (value === null || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return [{ path, code: 'object_required' }];
-    const keys = Reflect.ownKeys(value);
-    for (const key of keys) {
-      if (typeof key !== 'string' || !Object.hasOwn(schema.properties, key)) { errors.push({ path, code: 'unknown_field' }); continue; }
-      const property = Object.getOwnPropertyDescriptor(value, key);
-      if (!Object.hasOwn(property, 'value')) { errors.push({ path: `${path}.${key}`, code: 'accessor_forbidden' }); continue; }
-      errors.push(...schemaDiagnostics(property.value, schema.properties[key], `${path}.${key}`));
-    }
-    for (const key of schema.required ?? []) if (!Object.hasOwn(value, key)) errors.push({ path: `${path}.${key}`, code: 'field_required' });
-  }
-  if (schema.type === 'string') {
-    if (typeof value !== 'string') return [...errors, { path, code: 'string_required' }];
-    if (schema.minLength !== undefined && value.length < schema.minLength || schema.maxLength !== undefined && value.length > schema.maxLength
-      || schema.pattern && !(new RegExp(schema.pattern, 'u')).test(value)) errors.push({ path, code: 'string_invalid' });
-  }
-  return errors;
-}
-export function validateRunCommand(group, input) {
-  if (!RUN_COMMAND_GROUPS[group]) return [{ path: '$', code: 'command_group_unsupported' }];
-  const errors = schemaDiagnostics(input, commandGroupSchema(group));
-  if (errors.length) return errors;
-  if (Buffer.byteLength(canonicalJson(input)) > RUN_COMMAND_LIMITS.input_bytes) return [{ path: '$', code: 'command_input_budget_exceeded' }];
-  const kind = input.command.kind;
-  if (kind === 'operation.recover' && group !== recoveryGroups[input.command.payload.original_kind]) return [{ path: '$.command.payload.original_kind', code: 'command_group_effect_mismatch' }];
-  return [];
-}
-export const runCommandRequestDigest = input => digest(`agdf-run-command/1\0${canonicalJson(input)}`);
 export function operationContract(group, kind, { gate } = {}) {
   if (!RUN_COMMAND_GROUPS[group]?.includes(kind)) return { available: false, reason: 'command_group_unsupported' };
-  return { schema_version: RUN_COMMAND_VERSION, available: true, group, kind, ...RUN_COMMAND_DESCRIPTORS[kind], payload_schema: payloadSchema(group, kind),
-    schema: strictObject({ ...envelope, command: strictObject({ kind: { const: kind }, payload: payloadSchema(group, kind) }) }), retry_class: 'inspect_original_operation_after_dispatch', assurance: 'cooperative_local',
+  return { schema_version: RUN_COMMAND_VERSION, available: true, group, kind, ...RUN_COMMAND_DESCRIPTORS[kind], payload_schema: projectMcpInputSchema(payloadSchema(group, kind)),
+    schema: projectMcpInputSchema(describeFields(strictObject({ ...commandEnvelope(group, kind), command: strictObject({ kind: { const: kind }, payload: { ...payloadSchema(group, kind), description: RUN_COMMAND_DESCRIPTORS[kind].effects.join('; ') } }) }))), input_completion: { precedence: 'explicit > confirmed project config > versioned plugin defaults', constants: ['schema_version', 'assurance'], cwd: 'Explicit unless private trustworthy task context exists; current native adapters require it.', core: 'The adapter validates a complete envelope before dispatch; target/Run/revision/UUID/material/reply bindings remain explicit.' }, result_schema: RUN_COMMAND_RESULT_SCHEMA, retry_class: 'inspect_original_operation_after_dispatch', assurance: 'cooperative_local',
     reference_limits: { input_bytes: RUN_COMMAND_LIMITS.input_bytes, source_file_bytes: 131072, result_bytes: RUN_COMMAND_LIMITS.result_bytes },
+    ...(['planned_material.stage', 'planned_ur.create'].includes(kind) ? { planning_capture: {
+      applies_to: 'New planned UR creation only. Replacement retains the existing plan_id and current expected_digest.',
+      plan_id: 'plan-<planned_ur.create operation_id>', expected_digest: null,
+      instructions: 'For a new planned UR, reserve the future planned_ur.create UUID first. Use plan- followed by that exact UUID as planning.plan_id. Begin, append and seal planned_material.stage with the same plan_id and null expected_digest; each material call has its own operation_id. Create with the reserved UUID. Creation source material is the plain canonical UR: omit Planning schema, Planning id and Planning priority lines; the writer adds them from the request. Replacement instead stages the full selected UR with its existing planning metadata. Never use a title/slug as the creation plan_id.',
+    } } : {}),
+    ...(['material.stage', 'planned_material.stage'].includes(kind) ? { material_transport: { part_bytes: 16384, file_bytes: 131072, set_bytes: 524288, max_sets: 4,
+      total_bytes: 2097152, lifetime_ms: 600000, idle_ms: 120000, effect: 'private transfer only; no canonical files or gate decision',
+      encoding: 'append data is canonical standard base64 (no whitespace) of raw UTF-8 bytes; bytes and offsets count decoded bytes, not characters',
+      replay: 'begin preserves its original UUID; append uses exact offsets/base64 bytes. Seal returns Core identity/digest. Read transfer status after uncertainty; generation loss requires restaging semantic bytes. Preserve the future canonical write UUID.',
+      lifecycle: 'A receipt-confirmed canonical commit retires its consumed set; otherwise discard it explicitly or let it expire.' } } : {}),
     internal_result_formats: kind === 'step.record' ? { 'UX Intent Definition': UX_DECISION_FORMAT,
       reviews: { declaration: '- decision: pass | revise | block | not_applicable', result_scope: 'actual current owner report; no generated judgement or approval' } } : undefined,
-    reviewed_request_format: kind === 'artefact.record' ? { ...REVIEWED_REQUEST_FORMAT, current_relationship: relationshipForGate(gate) ?? null,
+    reviewed_binding_format: kind === 'artefact.record' ? { ...REVIEWED_BINDING_FORMAT, current_relationship: relationshipForGate(gate) ?? null,
       destination_status: gate === 'QA' ? 'pass | revise | block matching the actual QA report' : 'draft' } : undefined,
     proposal_format: kind.startsWith('source_revision.') ? REVISION_PROPOSAL_FORMAT : undefined,
-    authorizes: false, authoring_format: kind === 'artefact.record' || kind === 'presentation.prepare' || kind === 'step.record'
+    ...(kind === 'closeout.record' ? { confirmation_format: closeoutConfirmation('{run_id}', '{expected_revision_id}', '{operation_id}', '{or.digest}'),
+      closeout_modes: { quick_task: 'OR-lite: Result, Evidence, Risk, Next Step', verified_change: 'Verified Change Mini-Closeout; retain the same canonical record',
+        structured_slice: 'Existing OR-full closeout and its applicable obligations', structured_delivery: 'Existing OR-full closeout and its applicable obligations' } } : {}),
+    ...(kind === 'verified_change.record' ? { canonical_receipt_kind: 'step.record', execution: 'Actual edits/tests/Git actions remain external; this writer records their bounded observed result.' } : {}),
+    ...(['planned_ur.create', 'planned_ur.replace', 'run.create_from_planned'].includes(kind) ? { planning_capability: { schema: 'planned-ur-v1', protocol_version: 1,
+      owner: 'ur-definition', approval: 'none; explicit handoff starts an unapproved Run', metadata: ['Planning schema', 'Planning id', 'Planning priority'],
+      priority: ['high', 'normal', 'low'], default_priority: 'normal only on explicit create', source_identity: 'SHA-256 of the whole canonical UR text',
+      fields: kind === 'planned_ur.create' ? 'Stage the canonical UR without any Planning schema/id/priority lines. The create writer inserts all three from the request.' : 'Use the selected canonical UR including exactly one initial scalar of each planning metadata field. Planning id remains unchanged on replacement.' },
+      authoring_format: UR_AUTHORING_FORMAT } : {}),
+    authorizes: false, ...(!kind.startsWith('planned_ur.') && kind !== 'run.create_from_planned' ? { authoring_format: kind === 'closeout.record' ? { quick_task: QUICK_CLOSEOUT_AUTHORING_FORMAT } : kind === 'artefact.record' || kind === 'presentation.prepare' || kind === 'step.record'
       ? ({ UR: UR_AUTHORING_FORMAT, PRD: { decisions: PRD_DECISION_FORMAT, criteria: ACCEPTANCE_CRITERIA_FORMAT, preview_review: PREVIEW_REVIEW_FORMAT }, SD: SD_DECISION_FORMAT, TP: TP_AUTHORING_FORMAT }[gate] ?? null) : undefined,
+    } : {}),
     presentation_format: kind === 'presentation.prepare' || kind === 'artefact.record' ? {
-      owner: 'run-presentation-render', compact_brief_fields: ['Goal/Ziel', 'Proposal/Vorschlag or Scope/Umfang', 'Changes/Änderungen', 'Risks/Risiken'],
+      owner: 'run-presentation-render', record_version: 6, primary_document: 'one immutable Markdown with the complete source summary exactly once',
       source: 'source-authored canonical artefact or validated localized AGDF Approval Summary; no adapter paraphrase',
-      missing_fields: 'retain absence and the complete validated summary; do not fabricate a legacy brief',
-      delivery: 'native_plus_chat only with qualified native approval and confirmed display on the current user surface; otherwise full_chat; forward one exact decision request. Mac display never proves iPad visibility.',
+      missing_fields: 'retain absence; do not fabricate summary fields',
+      delivery: 'prepare opens no UI. Optional agdf_decision_view is a non-primary preview. presentation.deliver selects ui_primary only with live exact current-surface display proof, otherwise full_markdown. UI primary gets only a short Chat pointer. Qualification and intent are separate. Replay adds no question; fallback retires UI first.',
       remote_document: 'presentation-document; exact binding and every cursor; local file links do not prove iPad access',
       remote_preview: 'presentation-preview; exact binding and every cursor; render only through isolated supported access; unavailable access leaves the review open',
     } : undefined,