create-agdf 0.20.2 → 0.30.0

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

@@ -1,40 +1,39 @@
+import { extractField } from '../control-evaluation/verified-change.js';
+import { transitionDecisionForRunState } from '../control-evaluation/gate-policy.js';
+import { runDocumentPath, runEvidencePath, isRunDataPath } from './run-identity.js';
+import { resolutionRecordVersion } from './input-resolution.js';
 import { resolveControlCommandTarget } from './approval-command-contract.js';
-import { policyForRunContent as policyForDecision } from '../control-evaluation/run-step-policy.js';
+
 import { assertRunOperationIdentity } from "./run-operation-identity.js";
 import { readArtefactBindings } from "./artefact-bindings.js";
 import { pendingRunStepPath } from "./run-step-pending.js";
-import { appendRunOperation, readRunOperations } from "./run-operations.js";
+import { appendRunOperation, readRunOperations, closureSuccessorText } from "./run-operations.js";
 import { readOperationSource, operationSourceSetDigest, operationSources, operationReceipt, internalStepEligibility, reviewCorrectionRefusal, reviewCorrectionAvailable } from "./run-operation-proof.js";
 import { appendEvidenceBinding, evidenceSourceSetDigest, CORRECTABLE_REVIEWS } from './evidence-bindings.js';
 import { reviewFindingDiagnostics } from '../control-evaluation/normalized-gaps.js';
 import { qaReportReferences } from '../control-evaluation/qa-follow-up.js';
 import { COOPERATIVE_ASSURANCE } from './approval-command-contract.js';
 import { INTERNAL_STEP_FILES, prepareOwnedOutput } from "./run-owned-outputs.js";
-import { canonicalJson, digest } from "./approval-command-contract.js";
+import { withControlMutation, assertLayoutRunWrite } from './control-layout.js';
+import { digest } from "./approval-command-contract.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join, posix } from "node:path";
 import { runPath } from "./run-state-reader.js";
-import { parseControlState } from "./run-state-parser.js";
-import { APPROVAL_GATES, canonicalRunText } from "./run-seal-compute.js";
+import { parseRunState } from "./run-state-parser.js";
+import { canonicalRunText } from "./run-seal-compute.js";
 import {
   firstSection,
   projectUrObjective,
   guardedWrite,
   readRun,
   rejected,
-  removeTableRows,
+  endedRunRejection,
   replaceFirstScalar,
   replaceSectionScalar,
-  tableCells,
-  tableLineIndexes,
-  upsertTableRow,
-  appendTableRow,
 } from "./run-state-edits.js";
-import { withOwnedFileLock, writeRunLocked } from "./run-state-writer.js";
-import { commitRunStepLocked, recoverPendingRunStepLocked, readPendingRunStepJournal } from "./run-step-transaction.js";
-import { pendingRunStepIds } from "./run-step-pending.js";
+import { withOwnedFileLock } from "./run-state-writer.js";
+import { commitRunStepLocked, recoverPendingRunStepLocked, readPendingRunStepJournal, pendingRunStepConflictIds } from "./run-step-transaction.js";
 import { prepareArtefactRecording } from "./run-artefact-recording.js";
-import { backlogStatusForSummary, assertBacklogPath, prepareRunBacklog, backlogTableLayout } from "./run-backlog.js";
 import { prepareRunContentState } from "../control-evaluation/run-state.js";
 import { randomUUID } from "node:crypto";
 import { evaluateCloseoutReadiness, closeoutConfirmation, closeoutContext } from '../control-evaluation/closeout-readiness.js';
@@ -43,39 +42,34 @@ import { inspectQaReports } from '../control-evaluation/qa-follow-up.js';
 import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
 import { statSync } from 'node:fs';
 import { runWorkSummary, assertSummarySources } from "../control-evaluation/run-work-summary.js";
-import { recordBacklogSummary } from "./backlog-summary.js";
 import { decisionMaterial, presentationDecisionState, decisionRemediationOwner } from './presentation-decision.js';
 import { validateRunPresentation, validateRunPresentationRecord } from './run-presentation.js';
-import { withRunBacklogLock, writeRunWithBacklogLocked } from './run-backlog-writer.js';
+import { withRunMutationLock, writeRunMutationLocked } from './run-mutation.js';
 import { APPROVAL_GATES as DECISION_GATES, REVISION_ID_PATTERN } from './run-identity.js';
 import { runSealState, artefactFileDigest } from './run-seal.js';
 import { inspectUxIntentDecision } from '../control-evaluation/definition-sources.js';
 import { readReportDecision } from '../control-evaluation/report-decision.js';
+import { prepareVerifiedChangeRecording } from './run-verified-change.js';
 
-// run-step records one standard transition of the small path in a single sealed revision. The agent
-// supplies content, reasons and evidence; the command maintains the dependent tables, the backlog
-// pointer and the policy-derived next action so no hand edit of the control state is needed.
+// Record one typed transition and its owned files in a single sealed revision.
+// Current control and next actions are derived from those canonical facts.
 export const RUN_STEPS = Object.freeze(["ur", "route", "review", "evidence", "closeout", "artefact", "internal"]);
 export const RUN_STEP_ROUTES = Object.freeze(["quick_task", "verified_change", "structured_slice", "structured_delivery", "block"]);
+// Internal steps are reachable only from their owning Core operation, never from run-step or step.record.
+const INTERNAL_STEP_KINDS = Object.freeze({ lifecycle_close: "lifecycle_close.record" });
+const knownStep = (step, operationContext) => RUN_STEPS.includes(step) || Object.hasOwn(INTERNAL_STEP_KINDS, step) && INTERNAL_STEP_KINDS[step] === operationContext?.kind;
+export const RUN_CLOSED_NEXT_ACTION = "none, run ended";
 const REVIEW_DECISIONS = new Set(["pass", "revise", "block"]);
-const NEXT_GATE_BY_ROUTE = Object.freeze({
-  quick_task: "Quick Task Execution",
-  verified_change: "Verified Change Execution",
-  structured_slice: "PRD",
-  structured_delivery: "PRD",
-  block: "none",
-});
-const BACKLOG_LABELS = Object.freeze([["UR", "UR"], ["Brownfield Review", "Brownfield"], ["PRD", "PRD"], ["SD", "SD"], ["TP", "TP"], ["QA", "QA"], ["OR", "OR"]]);
-const BACKLOG_PATH = join(".agdf", "control", "MASTER_BACKLOG.md");
 const CONTROL_PREFIX = ".agdf/control/";
 
-const artefactPath = (key, file) => `${CONTROL_PREFIX}artefacts/${key}/${file}`;
+const artefactPath = (key, file) => file.startsWith('EVIDENCE-') ? runEvidencePath(key, file) : runDocumentPath(key, file);
 const filled = (value) => typeof value === "string" && value.trim() !== "";
+const recordingStep = (step, context) => knownStep(step, context) || step === 'verified_change' && context?.kind === 'step.record';
 const oneLine = (value) => String(value ?? "").replace(/\s+/gu, " ").trim();
 // Bounded strict-UTF-8 read of an artefact inside the selected Run; anything else is unavailable.
 function readRunArtefact(root, runId, rawPath, limit = 131072) {
   const path = String(rawPath ?? '').replace(/^`|`$/gu, '');
-  if (!path.startsWith(`.agdf/control/artefacts/${runId}/`) || posix.normalize(path) !== path || hasSymlinkComponent(root, path)) return undefined;
+  if (!isRunDataPath(runId, path) || posix.normalize(path) !== path || hasSymlinkComponent(root, path)) return undefined;
   const file = containedRegularFile(root, path);
   if (file.status !== 'valid' || statSync(file.path).size > limit) return undefined;
   try { return new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(file.path)); } catch { return undefined; }
@@ -85,8 +79,8 @@ const REVIEW_REPORT_LIMIT = 262144;
 // Every recording of a review or QA report applies the closeout quality rules; at most 64 diagnostics are returned.
 const findingsRefusal = (runId, diagnostics) => rejected(runId, 'review_findings_invalid',
   { diagnostics: diagnostics.slice(0, 64), ...(diagnostics.length > 64 ? { diagnostics_truncated: true } : {}) });
-function qaReportDiagnostics(root, runId, qa, control) {
-  const content = readRunArtefact(root, runId, qa.path, REVIEW_REPORT_LIMIT);
+function qaReportDiagnostics(root, runId, qa, control, proposedContent) {
+  const content = proposedContent ?? readRunArtefact(root, runId, qa.path, REVIEW_REPORT_LIMIT);
   if (typeof content !== 'string') return [{ review: 'QA', finding_id: null, field: 'report', expected: 'a readable UTF-8 report of at most 256 KiB inside the Run', rule: 'report_unreadable' }];
   const references = qaReportReferences(content, qa.path);
   // Closeout inspects at most 64 distinct reports: the QA report, the recorded reviews and its references.
@@ -113,91 +107,10 @@ function withSectionEdit(runId, text, edit) {
   return next === null ? { rejection: rejected(runId, "run_layout_unsupported") } : { text: next };
 }
 
-function artefactHeading(root, path) {
-  try {
-    return readFileSync(join(root, path), "utf8").match(/^#\s+(.+)$/mu)?.[1]?.trim() ?? "";
-  } catch {
-    return "";
-  }
-}
-
-function backlogLinks(text) {
-  const control = parseControlState(text, { userGates: APPROVAL_GATES, internalSteps: ["Brownfield Review"], closeoutArtefacts: ["OR"] });
-  return BACKLOG_LABELS
-    .map(([type, label]) => [label, control.artefacts.get(type)?.path ?? ""])
-    .filter(([, path]) => path.startsWith(CONTROL_PREFIX))
-    .map(([label, path]) => `[${label}](${path.slice(CONTROL_PREFIX.length)})`);
-}
-
-function prepareBacklog(root, key, { title, status, links, next, closeout }) {
-  const path = join(root, BACKLOG_PATH);
-  if (!existsSync(path)) return { status: "missing", update: null };
-  const original = readFileSync(path, "utf8");
-  let text = canonicalRunText(original);
-  const lines = text.split("\n");
-  const active = firstSection(lines, "Active Backlog");
-  const indexes = active ? tableLineIndexes(lines, active) : [];
-  const layout = indexes.length ? backlogTableLayout(tableCells(lines[indexes[0]])) : null;
-  if (layout === "legacy") return { status: "layout_legacy", update: null };
-  if (layout !== "compact") return { status: "layout_unsupported", update: null };
-  const matching = indexes.slice(2).filter(index => tableCells(lines[index])[1]?.replaceAll("`", "").trim() === key);
-  if (matching.length > 1) throw Error("AGDF_BACKLOG_IDENTITY_AMBIGUOUS");
-  if (matching.some(index => tableCells(lines[index]).length !== 7)) return { status: "layout_unsupported", update: null };
-  const existing = active
-    ? tableLineIndexes(lines, active).slice(2).map((index) => tableCells(lines[index])).find((cells) => cells[1]?.replaceAll("`", "").trim() === key)
-    : undefined;
-  const rowTitle = oneLine(title) || existing?.[2] || key;
-  if (closeout) {
-    text = removeTableRows(text, "Active Backlog", 1, existing?.[1] ?? key) ?? text;
-    text = upsertTableRow(text, "Completed / Superseded Pointers", 0, key, [key, rowTitle, "Completed", closeout.record, oneLine(closeout.outcome)]);
-  } else {
-    text = upsertTableRow(text, "Active Backlog", 1, existing?.[1] ?? key, [
-      existing?.[0] || "P1",
-      existing?.[1] ?? key,
-      rowTitle,
-      status ?? existing?.[3] ?? "In Progress",
-      links.join(" · "),
-      links[0] ?? "",
-      oneLine(next),
-    ]);
-  }
-  if (text === null) return { status: "layout_unsupported", update: null };
-  // A step commits a new Run revision even when its visible row cells are unchanged.
-  // Keep the candidate so the caller records that revision's observation in this transaction.
-  return { status: "updated", update: { old: original, next: text } };
-}
-
-function closeoutRecord({ title, runId, date, result, evidence, risk, next }) {
-  return [
-    `# OR-lite: ${title}`,
-    "",
-    "Report mode: OR-lite",
-    `Run: \`${runId}\``,
-    "Route: `quick_task` (Compact Delivery)",
-    `Date: ${date}`,
-    "",
-    "## Result",
-    "",
-    oneLine(result),
-    "",
-    "## Evidence",
-    "",
-    oneLine(evidence),
-    "",
-    "## Risk",
-    "",
-    oneLine(risk),
-    "",
-    "## Next Step",
-    "",
-    oneLine(next),
-    "",
-  ].join("\n");
-}
-
-function recordRunStepLocked(root, input, { policy, date, afterWrite, operationContext, packageVersion }) {
+function recordRunStepLocked(root, input, { policy, date, afterWrite, operationContext, packageVersion, resolveMaterial, gitObservation }) {
   const { runId, revisionId, step } = input;
-  if (!RUN_STEPS.includes(step)) return rejected(runId, "step_invalid", { steps: RUN_STEPS });
+  if (!operationContext) return rejected(runId, 'operation_context_required');
+  if (!recordingStep(step, operationContext)) return rejected(runId, "step_invalid", { steps: RUN_STEPS });
   const run = readRun(root, runId);
   if (run.rejection) return run.rejection;
   if (operationContext) {
@@ -211,7 +124,30 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
         receipt: previous.original ?? previous, revision_id: run.meta.revision_id, authorizes: false };
     }
   }
+  const ended = endedRunRejection(runId, run.content);
+  if (ended) return ended;
   if (run.meta.revision_id !== revisionId) return rejected(runId, "stale_revision");
+  let stagedSource;
+  if (input.sourceBinding?.material_id) {
+    stagedSource = resolveMaterial?.(input.sourceBinding);
+    const slot = input.step === 'internal' ? input.internalStep : input.step === 'verified_change' ? 'Verified Change'
+      : input.step === 'closeout' && stagedSource?.slot === 'Verified Change' ? 'Verified Change'
+      : ({ ur: 'UR', route: 'Brownfield Review', review: 'CR', evidence: 'EVIDENCE', closeout: 'OR' })[input.step];
+    if (!stagedSource || stagedSource.slot !== slot) return rejected(runId, 'material_slot_mismatch');
+    const file = slot === 'EVIDENCE' ? `EVIDENCE-${stagedSource.digest.slice(7)}.md`
+      : ({ UR: 'UR.md', OR: 'OR.md', 'Verified Change': 'VERIFIED_CHANGE.md', ...INTERNAL_STEP_FILES })[slot];
+    const path = artefactPath(runId, file);
+    input = { ...input, sourceBinding: { path, digest: stagedSource.digest }, evidence: path };
+  }
+  if (input.material) {
+    const sourceFile = input.material.path ? readOperationSource(root, runId, input.material) : null;
+    const staged = sourceFile ? { slot: input.gate, content: sourceFile.content, digest: input.material.digest, validate: sourceFile.validate } : resolveMaterial?.(input.material);
+    if (!staged || staged.slot !== input.gate) return rejected(runId, 'material_slot_mismatch');
+    input = { ...input, stagedMaterial: staged };
+  }
+  const readSource = () => stagedSource ? { content: stagedSource.content,
+    validate: () => { if (digest(canonicalRunText(stagedSource.content)) !== input.sourceBinding.digest) throw Error('AGDF_RUN_OPERATION_SOURCE_CHANGED'); } }
+    : readOperationSource(root, runId, input.sourceBinding);
 
   const key = runId;
   let text = canonicalRunText(run.content);
@@ -219,14 +155,13 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
   const approved = (gate) => control.approvals.get(gate)?.status === "approved";
   const route = control.mode_slice_decision.decision;
   const before = policy(root, text, run.path);
-  let known = "";
-  let evidenceRow = null;
-  let backlog = null;
-  let orContent = null;
+  if (operationContext?.kind === 'ur_draft.replace' && (before.current_gate !== 'UR'
+    || !control.artefacts.get('UR')?.path || approved('UR'))) return rejected(runId, 'ur_draft_not_replaceable');
   let recording = null;
   let ownedOutputs = [];
   let operationSource = null;
   let operationRecord = null;
+  let compactPreparation = null;
   const edit = (fn) => {
     const result = withSectionEdit(runId, text, fn);
     if (result.rejection) return result.rejection;
@@ -234,11 +169,12 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     return null;
   };
 
-  if (operationContext && step !== "internal" && step !== "artefact" && step !== "closeout") {
+  if (operationContext && !['internal', 'artefact', 'closeout', 'verified_change', 'lifecycle_close'].includes(step)) {
     if (!input.sourceBinding || control.meta.lifecycle !== "active") return rejected(runId, "operation_source_required");
-    operationSource = readOperationSource(root, runId, input.sourceBinding);
+    operationSource = readSource();
     const canonicalFile = { ur: "UR.md", route: "BROWNFIELD_REVIEW.md", review: INTERNAL_STEP_FILES.CR }[step];
     if (canonicalFile) ownedOutputs = [prepareOwnedOutput(root, runId, artefactPath(key, canonicalFile), operationSource.content)];
+    else if (stagedSource) ownedOutputs = [prepareOwnedOutput(root, runId, input.sourceBinding.path, operationSource.content)];
     if (step === "review") {
       if (!['CR', 'Quick Task Execution'].includes(before.current_gate)
           || !['pass', 'revise', 'block'].includes(input.decision)) return rejected(runId, "review_step_not_ready");
@@ -250,12 +186,33 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
       status: step === "review" && input.decision !== "pass" ? input.decision : "done", covers: oneLine(input.covers) || "selected Run scope",
       source_set_digest: operationSourceSetDigest(root, control, step) };
   }
-  if (step === "internal") {
+  if (step === "lifecycle_close") {
+    // Only an active, validly sealed Run closes; the closure keeps its gate and every artefact byte.
+    const closure = input.closure;
+    if (control.meta.lifecycle !== "active") return rejected(runId, "not_active");
+    if (runSealState(root, run.content).status !== "valid") return rejected(runId, "seal_invalid");
+    for (const fn of [value => replaceFirstScalar(value, "lifecycle", closure.lifecycle)]) {
+      const failed = edit(fn); if (failed) return failed;
+    }
+    const successor = closureSuccessorText(closure.successor);
+    const confirmer = closure.confirmed_by.statement === "unknown" ? "unknown person" : [closure.confirmed_by.name, closure.confirmed_by.email && `<${closure.confirmed_by.email}>`].filter(Boolean).join(" ");
+
+    operationRecord = closure;
+
+  } else if (step === 'verified_change') {
+    operationSource = readSource();
+    try { compactPreparation = prepareVerifiedChangeRecording(root, run, control, before, input, operationSource, gitObservation); }
+    catch (e) { if (e.message.startsWith('verified_change_') || e.message === 'confirmation_required') return rejected(runId, e.message); throw e; }
+    text = compactPreparation.text; ownedOutputs = compactPreparation.outputs;
+    operationRecord = { step: 'Verified Change', source: { path: compactPreparation.path, digest: compactPreparation.digest },
+      status: extractField(compactPreparation.content, 'status'), covers: `Verified Change ${input.phase}`, source_set_digest: operationSourceSetDigest(root, control, 'Verified Change') };
+
+  } else if (step === "internal") {
     const ux = input.internalStep === 'UX Intent Definition';
     if (!operationContext || !internalStepEligibility(control, before, input, root) || !(ux ? ['ready', 'blocked', 'not_applicable'] : ["pass", "revise", "block", "not_applicable"]).includes(input.decision)
         || ["CD+Tests", "CR", "TP Review", "Clean Implementation Review"].includes(input.internalStep) && input.decision === "not_applicable"
         || input.decision === "not_applicable" && !filled(input.reason)) return rejected(runId, "internal_step_not_ready");
-    operationSource = readOperationSource(root, runId, input.sourceBinding);
+    operationSource = readSource();
     if (ux) {
       const checked = inspectUxIntentDecision(operationSource.content);
       if (!checked.well_formed || !checked.supported || checked.decision !== input.decision
@@ -276,24 +233,20 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     const path = artefactPath(key, INTERNAL_STEP_FILES[input.internalStep]);
     const status = ['pass', 'ready'].includes(input.decision) ? "done" : input.decision === 'blocked' ? 'block' : input.decision;
     ownedOutputs = [prepareOwnedOutput(root, runId, path, operationSource.content)];
-    const failed = edit(value => upsertTableRow(value, "Artefacts", 0, input.internalStep,
-      [input.internalStep, path, status, `Recorded exact internal result; operation ${operationContext.operation_id}`]));
-    if (failed) return failed;
-    known = `${input.internalStep} result recorded: ${input.decision}.`;
-    evidenceRow = [input.internalStep, path, oneLine(input.covers) || "approved TP scope", "bound cooperative result"];
+
     operationRecord = { step: input.internalStep, source: { path, digest: input.sourceBinding.digest }, status,
       covers: oneLine(input.covers) || "approved TP scope", source_set_digest: operationSourceSetDigest(root, control, input.internalStep) };
-    backlog = {};
+
   } else if (step === "artefact") {
-    if (operationContext) operationSource = readOperationSource(root, runId, input.sourceBinding);
+    if (operationContext && !input.material) operationSource = readSource();
     recording = prepareArtefactRecording(root, run, { ...input, ...(operationContext ? { operationId: operationContext.operation_id, requestDigest: operationContext.request_digest } : {}) }, control, before);
+    ownedOutputs = recording.outputs ?? [];
     if (input.gate === 'QA') {
-      const diagnostics = qaReportDiagnostics(root, runId, recording.receipt.destination, control);
+      const diagnostics = qaReportDiagnostics(root, runId, recording.receipt.destination, control, input.stagedMaterial?.content);
       if (diagnostics.length) return findingsRefusal(runId, diagnostics);
     }
     text = recording.text;
-    known = `${input.gate} artefact and reviewed source binding recorded together.`;
-    backlog = {};
+
   } else if (step === "ur") {
     if (approved("UR")) return rejected(runId, "gate_not_ready", { current_gate: before.current_gate });
     if (!filled(input.title)) return rejected(runId, "title_missing");
@@ -302,11 +255,7 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     if (missing) return missing;
     // Only this authorized UR writer projects orientation; reading never repairs.
     text = projectUrObjective(text, operationSource?.content ?? readFileSync(join(root, path), 'utf8'));
-    const failed = edit((value) => upsertTableRow(value, "Artefacts", 0, "UR", ["UR", `\`${path}\``, "draft"]));
-    if (failed) return failed;
-    known = `UR drafted at \`${path}\`.`;
-    evidenceRow = ["UR draft", `\`${path}\``, "problem, goal, scope and acceptance signals", "direct"];
-    backlog = { title: input.title };
+
   } else if (step === "route") {
     const routeBeforeUrApproval = !approved("UR")
       && before.status === "open"
@@ -321,9 +270,6 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     const missing = ownedOutputs.some(row => row.path === path) ? null : requireFile(root, runId, path, `${CONTROL_PREFIX}templates/artefacts/BROWNFIELD_REVIEW.md`);
     if (missing) return missing;
     for (const fn of [
-      (value) => upsertTableRow(value, "Artefacts", 0, "Brownfield Review", ["Brownfield Review", `\`${path}\``, "done"]),
-      (value) => replaceSectionScalar(value, "Mode/Slice Decision", "decision", input.route),
-      (value) => replaceSectionScalar(value, "Mode/Slice Decision", "required_next_gate", NEXT_GATE_BY_ROUTE[input.route]),
       (value) => replaceSectionScalar(value, "Mode/Slice Decision", "scope_reason", oneLine(input.reason)),
       (value) => replaceSectionScalar(value, "Mode/Slice Decision", "evidence", oneLine(input.evidence)),
       (value) => replaceFirstScalar(value, "mode", input.route),
@@ -331,32 +277,29 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
       const failed = edit(fn);
       if (failed) return failed;
     }
-    known = `Brownfield Review at \`${path}\` selected \`${input.route}\`.`;
-    evidenceRow = ["Brownfield Review", `\`${path}\``, `Mode/Slice Decision \`${input.route}\``, "direct"];
-    backlog = {};
+
   } else if (step === "review") {
     if (!RUN_STEP_ROUTES.includes(route)) return rejected(runId, "gate_not_ready", { current_gate: before.current_gate });
     if (!REVIEW_DECISIONS.has(input.decision)) return rejected(runId, "decision_invalid", { decisions: [...REVIEW_DECISIONS] });
     if (!filled(input.evidence)) return rejected(runId, "evidence_missing");
     const status = input.decision === "pass" ? "done" : input.decision;
-    const failed = edit((value) => upsertTableRow(value, "Artefacts", 0, "CR", ["CR", "", status, `Code Review ${input.decision}`]));
-    if (failed) return failed;
-    if (operationContext) {
-      const failed = edit(value => upsertTableRow(value, "Artefacts", 0, "CR", ["CR", operationRecord.source.path, status, "Bound actual Code Review result"]));
-      if (failed) return failed;
-    }
-    known = `Code Review decision \`${input.decision}\`.`;
-    evidenceRow = ["Code Review", oneLine(input.source) || "code-review", `decision ${input.decision}: ${oneLine(input.evidence)}`, "direct"];
-    backlog = {};
+
   } else if (step === "evidence") {
     if (!filled(input.evidence)) return rejected(runId, "evidence_missing");
-    known = `Evidence recorded: ${oneLine(input.evidence)}.`;
-    evidenceRow = [oneLine(input.evidence), oneLine(input.source) || "agent", oneLine(input.covers) || "delivery", "direct"];
+
+  } else if (step === 'closeout' && route === 'verified_change') {
+    if (operationContext?.kind !== 'closeout.record') return rejected(runId, 'closeout_not_ready');
+    operationSource = readSource();
+    try { compactPreparation = prepareVerifiedChangeRecording(root, run, control, before, { ...input, operationId: operationContext.operation_id }, operationSource, gitObservation); }
+    catch (e) { if (e.message.startsWith('verified_change_') || e.message === 'confirmation_required') return rejected(runId, e.message); throw e; }
+    if (!exactApprovedArtefacts(root, control)) return rejected(runId, 'approved_source_proof_invalid');
+    text = compactPreparation.text; ownedOutputs = compactPreparation.outputs; operationRecord = compactPreparation.record;
+
   } else if (step === "closeout") {
     if (operationContext) {
       if (operationContext.kind !== 'closeout.record' || !input.sourceBinding || control.meta.lifecycle !== 'active'
         || !['OR', 'Quick Task Execution'].includes(before.current_gate) || before.status === 'blocked') return rejected(runId, 'closeout_not_ready');
-      operationSource = readOperationSource(root, runId, input.sourceBinding);
+      operationSource = readSource();
       const report = operationSource.content;
       const readiness = evaluateCloseoutReadiness(control, report, path => readRunArtefact(root, runId, path), { prepared: true });
       if (!readiness.ready) {
@@ -377,8 +320,7 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
       if (input.confirmation !== confirmation) return rejected(runId, 'closeout_confirmation_required', { confirmation_selector: confirmation });
       const path = artefactPath(key, 'OR.md');
       ownedOutputs = [prepareOwnedOutput(root, runId, path, report)];
-      for (const fn of [value => upsertTableRow(value, 'Artefacts', 0, 'OR', ['OR', path, 'done', 'Bound exact orchestration report']),
-        value => replaceFirstScalar(value, 'lifecycle', 'completed'), value => replaceFirstScalar(value, 'current_gate', 'OR'), value => replaceFirstScalar(value, 'decision', 'completed')]) {
+      for (const fn of [value => replaceFirstScalar(value, 'lifecycle', 'completed')]) {
         const failed = edit(fn); if (failed) return failed;
       }
       if (route !== 'quick_task') for (const [field, value] of Object.entries(closeoutContext(report))) {
@@ -388,93 +330,41 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
         const failed = edit(text => replaceSectionScalar(text, heading, field, value)); if (failed) return failed;
       }
       operationRecord = { or: { path, digest: input.sourceBinding.digest }, lifecycle: 'completed', context_evidence_digest: readiness.context_digest, confirmation_digest: digest(confirmation) };
-      known = `Run delivery completed; exact ${route === 'quick_task' ? 'OR-lite' : 'OR-full'} at ${path}.`;
-      evidenceRow = ['OR', path, 'selected Run closeout; no VCS or publication effect', 'bound cooperative result'];
-      backlog = { closeout: { record: `[OR](artefacts/${key}/OR.md)`, outcome: 'Completed approved scope with disclosed report obligations.' } };
-    } else {
-    if (route !== "quick_task") return rejected(runId, "closeout_route_unsupported", { route: route || "undecided" });
-    if (before.current_gate !== "Quick Task Execution") return rejected(runId, "gate_not_ready", { current_gate: before.current_gate });
-    if (control.artefacts.get("CR")?.status !== "done") return rejected(runId, "code_review_missing");
-    if (![input.result, input.evidence, input.risk, input.next].every(filled)) return rejected(runId, "closeout_fields_missing");
-    const path = artefactPath(key, "OR.md");
-    const title = artefactHeading(root, artefactPath(key, "UR.md")).replace(/^UR:\s*/u, "") || key;
-    for (const fn of [
-      (value) => upsertTableRow(value, "Artefacts", 0, "OR", ["OR", `\`${path}\``, "done"]),
-      (value) => replaceFirstScalar(value, "lifecycle", "completed"),
-      (value) => replaceFirstScalar(value, "current_gate", "OR"),
-      (value) => replaceFirstScalar(value, "decision", "completed"),
-    ]) {
-      const failed = edit(fn);
-      if (failed) return failed;
-    }
-    orContent = closeoutRecord({ title, runId, date, ...input });
-    known = `Quick task delivered; OR-lite at \`${path}\`.`;
-    evidenceRow = ["OR-lite", `\`${path}\``, "quick task closeout", "direct"];
-    backlog = { closeout: { record: `[OR](artefacts/${key}/OR.md)`, outcome: input.result } };
+
     }
   }
 
-  if (evidenceRow) {
-    const failed = edit((value) => appendTableRow(value, "Evidence", evidenceRow));
-    if (failed) return failed;
-  }
-  const proposedArtefacts = new Map(ownedOutputs.map(row => [row.path, { content: row.next, digest: input.sourceBinding.digest }]));
-  if (orContent) proposedArtefacts.set(artefactPath(key, 'OR.md'), { content: orContent, digest: digest(canonicalRunText(orContent)) });
+  const proposedArtefacts = new Map(ownedOutputs.map(row => [row.path, { content: row.next, digest: digest(canonicalRunText(row.next)) }]));
   const nextRevisionId = recording?.nextRevisionId ?? randomUUID();
   let appendedOperation = null, appendedEvidence = null;
-  if (operationContext && operationRecord) {
-    appendedOperation = operationReceipt(root, run, operationContext, nextRevisionId, operationRecord, packageVersion);
-    text = appendRunOperation(text, appendedOperation);
-  }
-  if (operationContext && (operationRecord && operationContext.kind === 'step.record' || recording && input.gate === 'QA')) {
+  if (operationContext && (operationRecord && ['step.record', 'ur_draft.replace'].includes(operationContext.kind) || recording && input.gate === 'QA')) {
     const evidenceStep = operationRecord?.step ?? input.gate;
     const sources = operationSources(root, control, evidenceStep);
-    appendedEvidence = { schema_version: '1', run_id: runId, operation_id: operationContext.operation_id, action: operationContext.kind, step: evidenceStep,
+    appendedEvidence = { schema_version: operationContext.kind === 'ur_draft.replace' ? '2' : '1', run_id: runId, operation_id: operationContext.operation_id, action: operationContext.kind, step: evidenceStep,
       report: operationRecord?.source ?? { path: recording.receipt.destination.path, digest: recording.receipt.destination.digest }, sources,
       source_set_digest: evidenceSourceSetDigest(sources), producer: { contract: 'run-command/1', package_version: packageVersion }, assurance: COOPERATIVE_ASSURANCE };
     text = appendEvidenceBinding(text, appendedEvidence);
   }
-  const after = policy(root, text, run.path, { proposedArtefacts });
-  const approvedGates = APPROVAL_GATES.filter((gate) => parseControlState(text, { userGates: APPROVAL_GATES }).approvals.get(gate)?.status === "approved");
-  for (const fn of [
-    (value) => replaceFirstScalar(value, "current_gate", after.current_gate),
-    (value) => replaceFirstScalar(value, "next_allowed_action", after.next_allowed_action),
-    (value) => upsertTableRow(value, "Current Control State", 0, "What is known?", ["What is known?", known]),
-    (value) => upsertTableRow(value, "Current Control State", 0, "What is approved?", ["What is approved?", approvedGates.length ? approvedGates.map((gate) => `Approval: ${gate}`).join(", ") : "Nothing yet."]),
-    (value) => upsertTableRow(value, "Current Control State", 0, "What is missing?", ["What is missing?", after.missing_approval !== "none" ? `Exact ${after.missing_approval}.` : "No approval is pending."]),
-    (value) => upsertTableRow(value, "Current Control State", 0, "What is the next allowed action?", ["What is the next allowed action?", after.next_allowed_action]),
-    (value) => upsertTableRow(value, "Current Control State", 0, "What is explicitly forbidden right now?", ["What is explicitly forbidden right now?", after.forbidden.join("; ") || "none"]),
-  ]) {
-    const failed = edit(fn);
-    if (failed) return failed;
+  if (operationContext && operationRecord) {
+    const record = appendedEvidence ? { evidence_binding_id: appendedEvidence.operation_id, status: operationRecord.status, covers: operationRecord.covers } : operationRecord;
+    appendedOperation = operationReceipt(root, run, operationContext, nextRevisionId, record, packageVersion);
+    text = appendRunOperation(text, appendedOperation);
   }
+  const after = policy(root, text, run.path, { proposedArtefacts });
+  const closing = step === 'lifecycle_close', nextAction = closing ? RUN_CLOSED_NEXT_ACTION : after.next_allowed_action;
 
   // Owned outputs are published before the precommit source check, so the summary reads them as proposed.
   const summary = runWorkSummary(root, text, run.path, after, { proposed: new Map([...proposedArtefacts].map(([path, row]) => [path, row.content])) });
-  const statusLabel = backlogStatusForSummary(summary, after);
-  let backlogPlan = backlog
-    ? prepareBacklog(root, key, { ...backlog, status: statusLabel, links: backlogLinks(text), next: summary.display_action })
-    : prepareRunBacklog(root, key, text, run.path, nextRevisionId);
-  // Legacy rows keep their title and per-gate link columns. Status and next step still follow
-  // the Run where the row exists; a closeout move is left to the maintainer.
-  if (backlogPlan.status === "layout_legacy") backlogPlan = { ...(backlog.closeout ? { status: "skipped", update: null }
-    : prepareRunBacklog(root, key, text, run.path, nextRevisionId)), reason: "backlog_layout_legacy" };
-  if (backlogPlan.status === "layout_unsupported") return rejected(runId, "backlog_layout_unsupported");
-  if (backlog && backlogPlan.update) backlogPlan.update.next = recordBacklogSummary(root, backlogPlan.update.next, key,
-    backlog.closeout ? "Completed / Superseded Pointers" : "Active Backlog", summary, nextRevisionId);
-  const written = guardedWrite(runId, () => (recording || orContent || backlogPlan.update || operationContext)
-    ? commitRunStepLocked(root, {
+  const written = guardedWrite(runId, () => commitRunStepLocked(root, {
       runId, runPath: run.path, content: text, revisionId, expectedContent: run.content,
-      backlog: backlogPlan.update, or: orContent, afterWrite,
+      afterWrite,
       nextRevisionId, outputs: ownedOutputs, operationContext,
       writeOptions: { ...(appendedOperation ? { appendedOperation } : {}), ...(appendedEvidence ? { appendedEvidence } : {}), ...(recording ? { appendedBinding: recording.receipt, allowContentChange: recording.allowContentChange } : {}),
-        validateBeforeWrite: () => { recording?.validateBeforeWrite(); operationSource?.validate();
+        validateBeforeWrite: () => { recording?.validateBeforeWrite(); operationSource?.validate(); compactPreparation?.validate();
           if (operationRecord?.step && operationSourceSetDigest(root, control, operationRecord.step) !== operationRecord.source_set_digest) throw Error("AGDF_RUN_OPERATION_SOURCE_CHANGED");
           if (operationContext?.kind === 'closeout.record' && !exactApprovedArtefacts(root, control)) throw Error('AGDF_RUN_OPERATION_SOURCE_CHANGED');
           assertSummarySources(root, summary); } },
-    })
-    : writeRunLocked(run.path, text, revisionId, { expectedContent: run.content, nextRevisionId,
-      validateBeforeWrite: () => assertSummarySources(root, summary) }));
+    }));
   if (written.rejection) return written.rejection;
   return Object.freeze({
     schema_version: "1",
@@ -484,40 +374,42 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     previous_revision_id: revisionId,
     revision: written.state.meta.revision,
     revision_id: written.state.meta.revision_id,
-    current_gate: after.current_gate,
-    next_allowed_action: after.next_allowed_action,
-    backlog: backlogPlan.status,
-    ...(backlogPlan.reason ? { backlog_reason: backlogPlan.reason } : {}),
+    current_gate: closing ? before.current_gate : after.current_gate,
+    next_allowed_action: nextAction,
     ...(appendedOperation ? { operation_id: appendedOperation.operation_id, receipt: appendedOperation }
       : recording ? { operation_id: recording.receipt.operation.id, receipt: recording.receipt } : {}),
   });
 }
 
-export function recordRunStep(root, input, { policy, date = new Date().toISOString().slice(0, 10), afterWrite, operationContext, packageVersion = "0.14.5" } = {}) {
+export function recordRunStep(root, input, { policy, date = new Date().toISOString().slice(0, 10), afterWrite, operationContext, packageVersion = "0.14.5", resolveMaterial, gitObservation } = {}) {
   const { runId, step } = input;
-  if (!RUN_STEPS.includes(step)) return rejected(runId, "step_invalid", { steps: RUN_STEPS });
+  if (!recordingStep(step, operationContext)) return rejected(runId, "step_invalid", { steps: RUN_STEPS });
   let path;
   try { path = runPath(root, runId); } catch { return rejected(runId, "run_id_invalid"); }
-  const backlogPath = join(root, BACKLOG_PATH);
   const locked = guardedWrite(runId, () => withOwnedFileLock(path, () => {
-    assertBacklogPath(root);
-    return withOwnedFileLock(backlogPath, () => {
-    const otherPending = pendingRunStepIds(root).find((id) => id !== runId);
+    return withControlMutation(root, { resource: `run:${runId}`, operation_id: operationContext?.operation_id ?? randomUUID(),
+      resume: true, proveOutcome: result => ['recorded', 'recovered', 'already_applied'].includes(result?.outcome) }, () => {
+    const perform = () => {
+    const parsed = parseRunState(readFileSync(path, 'utf8'));
+    if (!parsed.valid) return rejected(runId, 'run_state_invalid');
+    assertLayoutRunWrite(root, parsed);
+    const otherPending = pendingRunStepConflictIds(root, runId).find((id) => id !== runId);
     if (otherPending) return rejected(runId, "run_step_recovery_required", { pending_run_id: otherPending });
     if (operationContext && existsSync(pendingRunStepPath(root, runId))) {
       const pending = readPendingRunStepJournal(root, runId);
-      if (pending.schema_version !== 3 || pending.kind !== operationContext.kind || pending.operation_id !== operationContext.operation_id
+      if (resolutionRecordVersion(pending) !== 7 || pending.kind !== operationContext.kind || pending.operation_id !== operationContext.operation_id
           || pending.request_digest !== operationContext.request_digest || pending.old_revision_id !== input.revisionId) return rejected(runId, "original_operation_recovery_required");
       recoverPendingRunStepLocked(root, runId);
-      return recordRunStepLocked(root, input, { policy, date, afterWrite, operationContext, packageVersion });
+      return recordRunStepLocked(root, input, { policy, date, afterWrite, operationContext, packageVersion, resolveMaterial, gitObservation });
     }
     const recovered = recoverPendingRunStepLocked(root, runId);
     if (recovered.status === "completed") {
       return Object.freeze({ schema_version: "1", outcome: "recovered", run_id: runId,
-        operation_id: recovered.operation_id, revision_id: recovered.revision_id,
-        backlog: "updated" });
+        operation_id: recovered.operation_id, revision_id: recovered.revision_id });
     }
-    return recordRunStepLocked(root, input, { policy, date, afterWrite, operationContext, packageVersion });
+    return recordRunStepLocked(root, input, { policy, date, afterWrite, operationContext, packageVersion, resolveMaterial, gitObservation });
+    };
+    return perform();
     });
   }));
   return locked.rejection ?? locked.state;
@@ -532,13 +424,14 @@ export function recordRunPresentationDecision(root, input, { evaluateGateCheck,
     || typeof comment !== 'string' || Buffer.byteLength(comment) > 8192 || /\0/u.test(comment)
     || action === 'request_change' && !comment.trim() || !/^sha256:[0-9a-f]{64}$/u.test(requestDigest ?? '')) return rejected(runId, 'decision_input_invalid');
   const context = { kind: 'presentation_decision.record', operation_id: operationId, request_digest: requestDigest };
-  const written = guardedWrite(runId, () => withRunBacklogLock(root, runPath(root, runId), () => {
+  const written = guardedWrite(runId, () => withRunMutationLock(root, runPath(root, runId), () => {
     const run = readRun(root, runId); if (run.rejection) return run.rejection;
     assertRunOperationIdentity(root, run, operationId, context.kind);
     const previous = readRunOperations(run.content).receipts.find(row => row.operation_id === operationId);
     if (previous) return previous.kind === context.kind && previous.request_digest === requestDigest
       ? { outcome: 'already_applied', receipt: previous, historical_effect: true, authorizes: false }
       : rejected(runId, 'operation_payload_conflict');
+    const ended = endedRunRejection(runId, run.content); if (ended) return ended;
     if (run.meta.revision_id !== revisionId) return rejected(runId, 'stale_revision');
     if (runSealState(root, run.content).status !== 'valid') return rejected(runId, 'seal_invalid');
     const state = prepareRunContentState(root, run.content, run.path);
@@ -553,18 +446,13 @@ export function recordRunPresentationDecision(root, input, { evaluateGateCheck,
       owner: decisionRemediationOwner(gate), artefact_digest: gate === 'UAT' ? null : artefactFileDigest(root, state.artefacts.get(gate)?.path) };
     const receipt = operationReceipt(root, run, context, nextRevisionId, record, packageVersion);
     let next = appendRunOperation(run.content, receipt);
-    next = appendTableRow(next, 'Evidence', [`Gate ${action}`, `presentation ${presentationId}`, `Version ${material.material_version}; comment: ${comment || '(none)'}`, 'cooperative bound decision']);
-    if (next === null) return rejected(runId, 'run_layout_unsupported');
-    const after = policyForDecision(root, next, run.path);
-    next = replaceFirstScalar(next, 'next_allowed_action', after.next_allowed_action) ?? next;
-    for (const [key, value] of [['What is known?', `${action} recorded for current ${gate} material.`], ['What is missing?', 'Changed material and a fresh deliberate decision.'],
-      ['What is the next allowed action?', after.next_allowed_action]]) next = upsertTableRow(next, 'Current Control State', 0, key, [key, value]) ?? next;
-    const saved = writeRunWithBacklogLocked(root, run.path, next, revisionId, { expectedContent: run.content,
+    const saved = writeRunMutationLocked(root, run.path, next, revisionId, { expectedContent: run.content,
       appendedOperation: receipt, nextRevisionId, operationContext: { ...context, target_id: receipt.target_id }, afterWrite,
       validateDuringTransaction: () => {
         const fresh = validateRunPresentationRecord(root, { runId, gate, revisionId, presentationId });
         if (fresh.reason || fresh.digest !== presentation.digest || decisionMaterial(root, state, gate).material_version !== material.material_version) throw Error('AGDF_STALE_RUN_REVISION');
       } });
+    const after = transitionDecisionForRunState(prepareRunContentState(root, saved.content, run.path));
     return { outcome: 'recorded', receipt, revision_id: saved.meta.revision_id, next_operation: after.next_operation, authorizes: false };
   }, { operationContext: { ...context, target_id: resolveControlCommandTarget(root).target_id } }));
   return written.rejection ?? written.state;