create-agdf 0.20.2 → 0.31.0

package/runtime/core/lib/control-evaluation/doctor.js

@@ -1,16 +1,19 @@
-import { existsSync } from "../control-read/fs.js";
+import { existsSync, withControlReadMemo, memoizeControlRead } from "../control-read/fs.js";
 import { dirname, join } from 'node:path';
 import { aggregate } from "../control-state/aggregate.js";
-import { verifyLegacyProjection } from "../control-state/legacy-projection-reader.js";
 import { resolveRuns } from "../control-state/run-state-resolver.js";
+import { readRunInventory } from "../control-state/run-inventory-reader.js";
 import { runSealState } from "../control-state/run-seal.js";
 import { observeDecisionContent, decisionContentRecovery } from './decision-content-readiness.js';
-import { pendingRunStepIds } from "../control-state/run-step-pending.js";
-import { doctorRequiredFiles } from "./required-files.js";
+import { pendingRunStepConflictIds } from "../control-state/run-step-transaction.js";
+import { requiredControlFiles } from "./required-files.js";
+import { readControlLayout, CURRENT_LAYOUT } from '../control-state/control-layout.js';
+import { readPendingRunStepJournal } from '../control-state/run-step-transaction.js';
+import { resolutionRecordVersion } from '../control-state/input-resolution.js';
 import { analyzeDeliveryMap } from "./delivery-map.js";
 import { evaluateVerifiedChange } from "./verified-change.js";
 import { analyzeArtefactRoleConsistency, analyzeDurableGateArtefactConsistency, modeSliceDecision, readRunState, resolvedArtefactFile } from "./run-state.js";
-import { addFinding, allowNoActiveRuns, filled, hasFilledEvidenceRow, hasFilledTableRow, isPlaceholderValue, markdownSection, nonEmptyTableRows, parseBacklogSection, parseQualityContracts, readTargetFile, runSelectionRecovery, tableRows } from "./shared.js";
+import { addFinding, allowNoActiveRuns, filled, hasFilledEvidenceRow, hasFilledTableRow, isPlaceholderValue, markdownSection, nonEmptyTableRows, parseQualityContracts, readTargetFile, runSelectionRecovery, tableRows } from "./shared.js";
 
 const RUN_SEAL_FINDINGS = Object.freeze({
   approvals_changed: {
@@ -21,20 +24,35 @@ const RUN_SEAL_FINDINGS = Object.freeze({
   content_changed: {
     code: "AGDF_RUN_SEAL_MISMATCH",
     message: "The run state or a listed artefact changed after the last recorded revision.",
-    next_step: "Record the reviewed change with run-update so the run revision advances, then run gate-check again.",
+    next_step: "Preserve unrecorded bytes, restore the trusted sealed state, then stage the intended change through its current recording owner.",
   },
   invalid: {
     code: "AGDF_RUN_SEAL_INVALID",
     message: "The run seal lines are missing or malformed.",
-    next_step: "Restore the last sealed revision from trusted history and inspect changes before run-update; do not remove seal lines to bypass approval checks.",
+    next_step: "Restore trusted sealed bytes and inspect the change; never remove seals or adopt unknown edits.",
   },
   unsealed: {
     code: "AGDF_RUN_SEAL_INVALID",
     message: "The run has no seal and cannot be changed by normal write commands.",
-    next_step: "Restore a trusted sealed revision or use the explicit legacy migration path; do not infer approvals from this file.",
+    next_step: "Preserve the original bytes; inspect the original current operation and its supported recovery owner.",
   },
 });
 
+// Keep inventory findings under the same diagnosis owner for direct and paged
+// observations; transport pagination must not reinterpret their domain content.
+export const doctorInventoryFindings = findings => findings.map(finding => ({
+  ...finding,
+  severity: 'block',
+  message: finding.classification === 'unsupported_version'
+    ? 'The recorded control-state version is unsupported by this reader; this does not establish corrupted history.'
+    : finding.classification === 'unclassified'
+      ? 'The control-state version is missing or malformed; producer incompatibility has not been established.'
+      : 'Invalid canonical run entry.',
+  next_step: finding.classification === 'unsupported_version'
+    ? 'Use a compatible reader supporting the recorded format; preserve original history bytes and provenance.'
+    : 'Inspect the original version and integrity evidence; do not automatically rewrite, migrate or remove unrelated history.',
+}));
+
 export function evaluateDoctor(targetDir, selection = {}, dependencies = {}) {
   return evaluateDoctorWithRunState(targetDir, selection, dependencies).report;
 }
@@ -42,36 +60,39 @@ export function evaluateDoctor(targetDir, selection = {}, dependencies = {}) {
 // A gate evaluation consumes the exact state already read by its doctor check.
 // This observation lives only for that evaluation; later calls and writes read afresh.
 export function evaluateDoctorWithRunState(targetDir, selection = {}, dependencies = {}) {
+  return withControlReadMemo(() => evaluateDoctorObserved(targetDir, selection, dependencies));
+}
+
+function evaluateDoctorObserved(targetDir, selection, dependencies) {
   if (selection.allActive) {
     const selected = resolveRuns(targetDir, { allActive: true });
     const runs = selected.runs.map((run) => ({
       run_id: run.run_id,
       report: evaluateDoctor(targetDir, { runId: run.run_id }, dependencies),
     }));
-    const status = selected.findings.length
-      ? "block"
-      : aggregate(
-          runs.map((item) => ({ run_id: item.run_id, status: item.report.status })),
-          { allowNoActiveRuns: allowNoActiveRuns(targetDir) },
-        ).status;
+    const aggregated = selected.findings.length ? { status: 'block' }
+      : aggregate(runs.map(item => ({ run_id: item.run_id, status: item.report.status })),
+        { allowNoActiveRuns: allowNoActiveRuns(targetDir) });
+    const status = aggregated.status;
     const findings = [
-      ...selected.findings.map((finding) => ({
-        ...finding,
-        severity: "block",
-        message: "Invalid canonical run entry.",
-        next_step: "Repair or remove the invalid run entry.",
-      })),
+      ...doctorInventoryFindings(selected.findings),
       ...runs.flatMap((item) => item.report.findings.map((finding) => ({ ...finding, run_id: item.run_id }))),
     ];
+    // Stored-state inventory of all runs; it never changes the evaluated doctor status above.
+    const listed = readRunInventory(targetDir, { language: selection.presentationLanguage });
     return { report: {
       schema_version: "1",
       status,
+      ...(!selected.findings.length && existsSync(join(targetDir, '.agdf/control')) && aggregated.empty_inventory
+        ? { empty_inventory: aggregated.empty_inventory } : {}),
       checked_at: new Date().toISOString(),
       target_dir: targetDir,
       inventory: {
         state: !existsSync(join(targetDir, ".agdf", "control")) ? "absent"
           : selected.findings.length ? "incomplete" : "complete",
         active_count: runs.length,
+        counts: listed.counts,
+        runs: listed.runs,
       },
       summary: {
         findings: findings.length,
@@ -83,58 +104,17 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
       runs,
     } };
   }
-  const findings = [];
-  for (const pendingId of pendingRunStepIds(targetDir)) {
-    addFinding(
-      findings,
-      "block",
-      "AGDF_RUN_STEP_RECOVERY_REQUIRED",
-      `A run-step transaction for ${pendingId} is incomplete; shared Backlog pointers may be in transition.`,
-      join(".agdf", "control", "runs", pendingId, "RUN_STEP_PENDING.json"),
-      "Retry the exact run-step for the pending run to recover it, or inspect conflicting bytes before manual repair.",
-    );
-  }
+  const shared = sharedDoctorContext(targetDir, selection.runId);
+  const findings = [...shared.findings], missing = shared.missing;
   let reconciliation, selectedRunState;
-  const hasCanonicalRuns = existsSync(join(targetDir, ".agdf", "control", "runs"));
-  if (hasCanonicalRuns) {
-    const projection = verifyLegacyProjection(targetDir);
-    if (!["absent", "valid"].includes(projection.status)) {
-      addFinding(
-        findings,
-        "block",
-        "AGDF_LEGACY_PROJECTION_DRIFT",
-        `Legacy compatibility state is not a valid projection: ${projection.status}.`,
-        join(".agdf", "control", "AGDF_RUN.md"),
-        "Regenerate the explicit legacy projection or remove it after legacy consumers are retired.",
-      );
-    }
-  }
-  const missing = doctorRequiredFiles.filter(
-    (relativePath) => !(relativePath.endsWith("AGDF_RUN.md") && hasCanonicalRuns) && !existsSync(join(targetDir, relativePath)),
-  );
-
-  for (const relativePath of missing) {
-    const templatePath = join(dirname(relativePath), "templates", relativePath.split("/").at(-1));
-    const hasTemplate = existsSync(join(targetDir, templatePath));
-    addFinding(
-      findings,
-      "block",
-      "AGDF_CONTROL_FILE_MISSING",
-      hasTemplate
-        ? "Live control file is missing; only the template exists."
-        : "Required live control file is missing.",
-      relativePath,
-      "Run npx --yes @agdf/cli@latest init only when the repository should own durable AGDF control state or deterministic setup is explicitly needed.",
-    );
-  }
-
   if (missing.length === 0) {
     selectedRunState = readRunState(targetDir, selection);
     const runPath = selectedRunState.path;
     const run = selectedRunState.content;
 
     if (selectedRunState.resolution_error) {
-      addFinding(
+      if (selectedRunState.resolution_findings?.length) findings.push(...doctorInventoryFindings(selectedRunState.resolution_findings));
+      else addFinding(
         findings,
         "block",
         selectedRunState.resolution_error.split(":")[0] || "AGDF_ACTIVE_RUN_UNRESOLVED",
@@ -143,36 +123,12 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
         runSelectionRecovery(selection.target),
       );
     } else {
-      const currentGateLine = run.match(/^- current_gate:[^\S\r\n]*(.*)$/m)?.[1]?.trim() ?? "";
-      const nextActionLine = run.match(/^- next_allowed_action:[^\S\r\n]*(.*)$/m)?.[1]?.trim() ?? "";
-      const hasEvidence = hasFilledEvidenceRow(run);
+      const hasEvidence = selectedRunState.evidence_refs.length > 0;
       const content = observeDecisionContent(targetDir, selectedRunState, { objectiveOnly: true });
       if (!content.ready) addFinding(findings, 'warn', 'AGDF_DECISION_CONTENT_INCOMPLETE',
         'The selected active Run has incomplete decision orientation.', runPath,
         decisionContentRecovery(content, { state: selectedRunState }));
 
-      if (isPlaceholderValue(currentGateLine)) {
-        addFinding(
-          findings,
-          "revise",
-          "AGDF_CURRENT_GATE_MISSING",
-          "The selected run state does not name the current gate.",
-          runPath,
-          "Set current_gate to the current delivery gate or none.",
-        );
-      }
-
-      if (isPlaceholderValue(nextActionLine)) {
-        addFinding(
-          findings,
-          "revise",
-          "AGDF_NEXT_ALLOWED_ACTION_MISSING",
-          "The selected run state does not state the next allowed action.",
-          runPath,
-          "Fill the next allowed action before asking an agent to continue delivery work.",
-        );
-      }
-
       if (!hasEvidence) {
         addFinding(
           findings,
@@ -180,7 +136,7 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
           "AGDF_EVIDENCE_EMPTY",
           "The selected run state has no visible evidence row yet.",
           runPath,
-          "Add at least one evidence row or explicitly document that no evidence exists yet.",
+          "Record actual evidence through the current Run evidence owner.",
         );
       }
 
@@ -193,7 +149,7 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
             ? "The selected run state has a missing or invalid run_id; interaction cards cannot be rendered for it."
             : "The selected run state has a missing or invalid revision_id; approval interactions cannot be rendered for it.",
           runPath,
-          "Run run-migrate to repair the run identity, or migrate the legacy state to a canonical run record.",
+          "Select a valid current Run; unsupported control is never converted automatically.",
         );
       }
 
@@ -201,84 +157,6 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
       if (sealFinding) addFinding(findings, "block", sealFinding.code, sealFinding.message, runPath, sealFinding.next_step);
     }
 
-    const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");
-    const backlog = readTargetFile(targetDir, backlogPath);
-    parseBacklogSection(markdownSection(backlog, "Active Backlog"), findings, backlogPath);
-    parseBacklogSection(markdownSection(backlog, "Planned / Parking Lot"), findings, backlogPath);
-    const completedRows = tableRows(markdownSection(backlog, "Completed / Superseded Pointers"))
-      .slice(1)
-      .filter((cells) => cells.some((cell) => filled(cell)));
-    // Priorities are written as P1 or, per the numeric template column, as 1.
-    if (!hasFilledTableRow(backlog, /^P?[0-9]/) && completedRows.length === 0) {
-      addFinding(
-        findings,
-        "warn",
-        "AGDF_BACKLOG_POINTER_EMPTY",
-        "MASTER_BACKLOG.md does not contain an active or planned work pointer.",
-        backlogPath,
-        "Add the active item or document that no governed delivery item is active.",
-      );
-    }
-
-    const sotPath = join(".agdf", "control", "SOT_REGISTRY.md");
-    const sot = readTargetFile(targetDir, sotPath);
-    if (!hasFilledTableRow(sot, /Product intent|Architecture|Runtime contracts|UX \/ user flows|Operations \/ release/)) {
-      addFinding(
-        findings,
-        "warn",
-        "AGDF_SOT_REGISTRY_EMPTY",
-        "SOT_REGISTRY.md has no filled primary source-of-truth row.",
-        sotPath,
-        "Assign one primary source of truth for at least the domains relevant to the next run.",
-      );
-    }
-
-    const activeDomains = new Map();
-    for (const cells of nonEmptyTableRows(sot)) {
-      const [domain, document, status] = cells;
-      if (!domain || !document || status !== "active") continue;
-      activeDomains.set(domain, (activeDomains.get(domain) ?? 0) + 1);
-    }
-    for (const [domain, count] of activeDomains.entries()) {
-      if (count > 1) {
-        addFinding(
-          findings,
-          "block",
-          "AGDF_PARALLEL_SOT",
-          `Domain has ${count} active source-of-truth rows: ${domain}.`,
-          sotPath,
-          "Keep exactly one active primary source of truth for this domain.",
-        );
-      }
-    }
-
-    const contextPath = join(".agdf", "control", "CONTEXT_GRAPH.md");
-    const contextGraph = readTargetFile(targetDir, contextPath);
-    if (contextGraph.includes("### CG-001 Example")) {
-      addFinding(
-        findings,
-        "warn",
-        "AGDF_CONTEXT_GRAPH_TEMPLATE_NODE",
-        "CONTEXT_GRAPH.md still contains the example node.",
-        contextPath,
-        "Remove the example or replace it with an evidenced node that has an exit criterion.",
-      );
-    }
-
-    const contractsPath = join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json");
-    try {
-      parseQualityContracts(readTargetFile(targetDir, contractsPath));
-    } catch (error) {
-      addFinding(
-        findings,
-        "block",
-        "AGDF_QUALITY_CONTRACTS_INVALID",
-        `AGENT_QUALITY_CONTRACTS.json is invalid: ${error.message}`,
-        contractsPath,
-        "Restore the generated contracts or fix the JSON contract schema.",
-      );
-    }
-
     const runState = selectedRunState;
     for (const type of runState.artefact_row_duplicates ?? []) {
       addFinding(
@@ -287,7 +165,7 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
         "AGDF_ARTEFACT_ROW_DUPLICATE",
         `The selected run has more than one Artefacts row for ${type}; the effective artefact is ambiguous.`,
         runState.path,
-        "Keep exactly one Artefacts row per type, record the reviewed correction with run-update, then retry the gate presentation.",
+        "Current document references derive from typed bindings; restore valid records instead of editing derived tables.",
       );
     }
     if (modeSliceDecision(runState) === "verified_change") {
@@ -333,7 +211,117 @@ export function evaluateDoctorWithRunState(targetDir, selection = {}, dependenci
   } };
 }
 
-export function printDoctorReport(report, json, io = console) {
+
+// Repeated Runs reuse shared policy/store findings only inside the same read observation.
+// This cache never survives a source change or becomes write permission.
+function sharedDoctorContext(targetDir, runId) {
+  return memoizeControlRead(`doctorShared:${targetDir}:${runId ?? ""}`, () => {
+    const findings = [];
+    let planned = false;
+    try { planned = readControlLayout(targetDir).layout === CURRENT_LAYOUT; }
+    catch (error) {
+      // Missing configuration is already reported by the existing setup checks.
+      if (existsSync(join(targetDir, '.agdf/control/config.json'))) addFinding(findings, 'block', error.message,
+        'The control layout cannot be read safely.', '.agdf/control/config.json', 'Restore a supported contained configuration.');
+    }
+    for (const pendingId of pendingRunStepConflictIds(targetDir, runId)) {
+      if (planned) {
+        try { if (resolutionRecordVersion(readPendingRunStepJournal(targetDir, pendingId)) === 7) continue; } catch {}
+      }
+      addFinding(
+        findings,
+        "block",
+        "AGDF_RUN_STEP_RECOVERY_REQUIRED",
+        `A run-step transaction for ${pendingId} is incomplete; its recorded outputs require recovery.`,
+        join(".agdf", "control", "runs", pendingId, "control", "RUN_STEP_PENDING.json"),
+        "Use explicit supported recovery for this exact pending operation; preserve conflicting bytes.",
+      );
+    }
+    const required = requiredControlFiles(targetDir);
+    const missing = required.filter(
+      (relativePath) => !existsSync(join(targetDir, relativePath)),
+    );
+
+    for (const relativePath of missing) {
+      const templatePath = join(dirname(relativePath), "templates", relativePath.split("/").at(-1));
+      const hasTemplate = existsSync(join(targetDir, templatePath));
+      addFinding(
+        findings,
+        "block",
+        "AGDF_CONTROL_FILE_MISSING",
+        hasTemplate
+          ? "Live control file is missing; only the template exists."
+          : "Required live control file is missing.",
+        relativePath,
+        "Run npx --yes @agdf/cli@latest init only when the repository should own durable AGDF control state or deterministic setup is explicitly needed.",
+      );
+    }
+    if (missing.length === 0) {
+
+      const sotPath = join(".agdf", "control", "SOT_REGISTRY.md");
+      const sot = readTargetFile(targetDir, sotPath);
+      if (!hasFilledTableRow(sot, /Product intent|Architecture|Runtime contracts|UX \/ user flows|Operations \/ release/)) {
+        addFinding(
+          findings,
+          "warn",
+          "AGDF_SOT_REGISTRY_EMPTY",
+          "SOT_REGISTRY.md has no filled primary source-of-truth row.",
+          sotPath,
+          "Assign one primary source of truth for at least the domains relevant to the next run.",
+        );
+      }
+
+      const activeDomains = new Map();
+      for (const cells of nonEmptyTableRows(sot)) {
+        const [domain, document, status] = cells;
+        if (!domain || !document || status !== "active") continue;
+        activeDomains.set(domain, (activeDomains.get(domain) ?? 0) + 1);
+      }
+      for (const [domain, count] of activeDomains.entries()) {
+        if (count > 1) {
+          addFinding(
+            findings,
+            "block",
+            "AGDF_PARALLEL_SOT",
+            `Domain has ${count} active source-of-truth rows: ${domain}.`,
+            sotPath,
+            "Keep exactly one active primary source of truth for this domain.",
+          );
+        }
+      }
+
+      const contextPath = join(".agdf", "control", "CONTEXT_GRAPH.md");
+      const contextGraph = readTargetFile(targetDir, contextPath);
+      if (contextGraph.includes("### CG-001 Example")) {
+        addFinding(
+          findings,
+          "warn",
+          "AGDF_CONTEXT_GRAPH_TEMPLATE_NODE",
+          "CONTEXT_GRAPH.md still contains the example node.",
+          contextPath,
+          "Remove the example or replace it with an evidenced node that has an exit criterion.",
+        );
+      }
+
+      const contractsPath = join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json");
+      try {
+        parseQualityContracts(readTargetFile(targetDir, contractsPath));
+      } catch (error) {
+        addFinding(
+          findings,
+          "block",
+          "AGDF_QUALITY_CONTRACTS_INVALID",
+          `AGENT_QUALITY_CONTRACTS.json is invalid: ${error.message}`,
+          contractsPath,
+          "Restore the generated contracts or fix the JSON contract schema.",
+        );
+      }
+    }
+    return { findings, missing };
+  });
+}
+
+export function printDoctorReport(report, json, io = console, { emptyInventoryText } = {}) {
   if (json) {
     io.log(JSON.stringify(report, null, 2));
     return;
@@ -342,6 +330,8 @@ export function printDoctorReport(report, json, io = console) {
   io.log(`AGDF doctor: ${report.status}`);
   io.log(`Checked: ${report.target_dir}`);
   io.log(`Findings: ${report.summary.findings} (${report.summary.block} block, ${report.summary.revise} revise, ${report.summary.warn} warn)`);
+  if (report.empty_inventory) io.log(emptyInventoryText
+    ?? `No active Runs; allow_no_active_runs=${report.empty_inventory.allow_no_active_runs}. The aggregate status reflects this policy, with no synthetic findings. Project health and delivery readiness are separate.`);
 
   for (const finding of report.findings) {
     io.log("");

package/runtime/core/lib/control-evaluation/gate-check.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { decisionRemediationOwner } from '../control-state/presentation-decision.js';
 import { attachApprovalOrientationSnapshot, buildArtefactRefs, buildQualityReadiness, gateTitle, isOperationalValueRenderable, localePack, renderApprovalOrientationSnapshot, renderControlSetupOrientation, renderDefinitionSourceRecovery, renderOperationalStatusCard, renderRunResolutionCard, resolveHumanRunTitle, resolvePresentationLocale, validateApprovalOrientationPreconditions, validateApprovalOrientationSnapshot, validateOperationalStatusCardPreconditions } from "../interaction-presentation.js";
 import { interactionLocales, resolveConfiguredChatLanguage, resolveArtifactPresentationLanguages } from "../resources/context.js";
@@ -8,7 +9,8 @@ import { isGateSatisfied, transitionDecisionForRunState } from "./gate-policy.js
 import { effectiveNextAllowedAction } from "./next-action.js";
 import { evaluateVerifiedChange, extractField, verifiedChangeEscalationTargets } from "./verified-change.js";
 import { gateApprovalStatus, isInternalStepSatisfied, modeSliceDecision, readArtefactHeading, readRunState, resolvedArtefactFile } from "./run-state.js";
-import { renderReviewableApproval } from "../control-state/run-presentation-render.js";
+import { evaluateApprovalSummaryReadiness, renderApprovalSummaryIssue, renderReviewableApproval } from "../control-state/run-presentation-render.js";
+import { readFileSync } from "../control-read/fs.js";
 import { evaluateUrReadiness } from "./ur-readiness.js";
 import { inspectDefinitionSources } from "./definition-sources.js";
 import { evaluatePrdReadiness } from "./prd-readiness.js";
@@ -60,8 +62,8 @@ function requiredGateArtifactPreparation({ status, currentGate, missingApproval,
     effect: "preparation",
     gate: currentGate,
     skill_id: currentGate === "SD" ? "sd-definition" : currentGate === "TP" ? "tp-definition" : "gate-check",
-    artifact_path: `.agdf/control/artefacts/${runId}/${plan.file}`,
-    source_artifacts: Object.freeze(plan.sources.map((source) => `.agdf/control/artefacts/${runId}/${source}`)),
+    artifact_path: `${runDocumentPath(runId, '')}/${plan.file}`,
+    source_artifacts: Object.freeze(plan.sources.map((source) => `${runDocumentPath(runId, '')}/${source}`)),
   });
 }
 
@@ -368,13 +370,13 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
     currentGate = "UR";
     missingApproval = "none";
     allowed = [
-      "create or migrate a canonical run with an explicit run id",
+      "create a current Run with an operation UUID",
       "select an existing canonical run explicitly",
       "persist a real UR revision before requesting gate approval",
       "run doctor again",
     ];
     forbidden = ["request gate approval without a durable run and artefact", "implement gated work", "claim QA or release readiness"];
-    nextAllowedAction = "Create, migrate or select the canonical run, then persist its UR revision before requesting approval.";
+    nextAllowedAction = "Create or select the current Run, then persist its UR revision before requesting approval.";
   } else if (doctorBlocker && /AGDF_(?:ACTIVE_RUN|RUN_NOT_SELECTABLE|RUN_PATH_INVALID)/u.test(doctorBlocker.code)) {
     status = "blocked";
     blockingReason = doctorBlocker.code;
@@ -419,38 +421,65 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
     blockingReason = "AGDF_UR_REQUIREMENTS_INCOMPLETE";
     allowed = ["complete the UR requirement clarification and record a new run revision"];
     forbidden = [...forbidden, "present or approve UR before requirement clarification is complete"];
-    nextAllowedAction = "complete the UR requirement clarification, then record the revision with run-update";
+    nextAllowedAction = "complete the UR requirement clarification, then record the revision through the inspected current recording operation";
   }
   let prdReadiness = currentGate === "PRD" && approvalArtefactReady
     ? evaluatePrdReadiness(targetDir, runState, { presentationLanguage: presentationLocale }) : null;
   if (status === "open" && prdReadiness && transitionDecision.next_operation?.type !== "reassess_source_analysis" && isGateSatisfied(runState, "UR") && isInternalStepSatisfied(runState, "Brownfield Review")
       && ["structured_delivery", "structured_slice"].includes(modeSliceDecision(runState))) {
     const inputFacts = inspectDefinitionSources(targetDir, runState, extractField(runState.content, "run_id"), "PRD", ["UR", "Brownfield Review"]);
-    if (inputFacts.issue) prdReadiness = { ready: false, open_decisions: [...prdReadiness.open_decisions,
+    if (inputFacts.issue) prdReadiness = { ...prdReadiness, ready: false, source_issue: inputFacts.issue, open_decisions: [...prdReadiness.open_decisions,
       renderDefinitionSourceRecovery(inputFacts.issue, { registry: interactionLocales, requestedLocale: presentationLocale })] };
   }
   if (status === "open" && currentGate === "PRD" && prdReadiness && !prdReadiness.ready) {
     status = "blocked";
+    const checks = prdReadiness.readiness_checks;
     blockingReason = "AGDF_PRD_DECISIONS_OPEN";
+    if (checks?.decisions_ready) {
+      const sourceCriteriaIncomplete = !checks.approval_summary.ready && [
+        "approval_summary_criterion_content_missing", "approval_summary_source_criteria_invalid",
+        "approval_summary_source_criteria_duplicate", "approval_summary_criteria_missing",
+      ].includes(checks.approval_summary.reason);
+      blockingReason = prdReadiness.source_issue || !checks.preview_ready || !checks.criteria_ready || sourceCriteriaIncomplete
+        ? "AGDF_PRD_READINESS_INCOMPLETE" : "AGDF_APPROVAL_SUMMARY_INCOMPLETE";
+    }
     allowed = ["complete the listed PRD readiness items together and record a new run revision"];
     forbidden = [...forbidden, "present or approve PRD before required decisions and acceptance criteria are ready"];
     // Fixed text keeps the card localizable; detailed gaps travel separately in prd_readiness.open_decisions.
-    nextAllowedAction = "complete the open PRD readiness items together, then record the revision with run-update";
+    nextAllowedAction = "complete the open PRD readiness items together, then record the revision through the inspected current recording operation";
   }
-  const sdReadiness = currentGate === "SD" && approvalArtefactReady ? evaluateSdReadiness(targetDir, runState) : null;
-  const traceabilityReadiness = status === "open" && approvalArtefactReady && currentGate === "SD"
+  let sdReadiness = currentGate === "SD" && approvalArtefactReady ? evaluateSdReadiness(targetDir, runState) : null;
+  let traceabilityReadiness = status === "open" && approvalArtefactReady && currentGate === "SD"
     ? evaluateSdTraceability(targetDir, runState)
     : status === "open" && approvalArtefactReady && currentGate === "TP"
       ? evaluateTpTraceability(targetDir, runState)
       : null;
-  if (status === "open" && sdReadiness && !sdReadiness.ready) {
+  // Presentation readiness belongs to the existing authoring gate, not to the
+  // traceability grammar. Use the same summary owner as preflight and rendering
+  // before a registered SD/TP draft can bypass its author and request approval.
+  let approvalSummaryReadiness = null;
+  if (status === "open" && approvalArtefactReady && ["SD", "TP"].includes(currentGate)) {
+    const path = runState.artefacts.get(currentGate).path;
+    const file = resolvedArtefactFile(targetDir, path);
+    const languages = resolveArtifactPresentationLanguages(targetDir, presentationLocale);
+    const summary = evaluateApprovalSummaryReadiness(currentGate, readFileSync(file, "utf8"), languages, { path });
+    if (!summary.ready) {
+      approvalSummaryReadiness = summary;
+      const issue = renderApprovalSummaryIssue(summary, { path, presentationLanguage: presentationLocale });
+      if (currentGate === "SD") sdReadiness = { ...sdReadiness, ready: false, decisions_ready: sdReadiness.ready,
+        open_decisions: [...sdReadiness.open_decisions, issue] };
+      else traceabilityReadiness = { ...traceabilityReadiness, ready: false, traceability_ready: traceabilityReadiness.ready,
+        open_items: [...traceabilityReadiness.open_items, issue] };
+    }
+  }
+  if (status === "open" && sdReadiness && !sdReadiness.ready && sdReadiness.decisions_ready !== true) {
     status = "blocked";
     blockingReason = "AGDF_SD_DECISIONS_OPEN";
     allowed = ["complete the listed SD readiness items together and record a new run revision"];
     forbidden = [...forbidden, "present or approve SD before required design decisions are ready"];
     nextAllowedAction = "complete the open SD readiness items together, then record the revision with the shared artefact writer";
   }
-  if (status === "open" && traceabilityReadiness && !traceabilityReadiness.ready) {
+  if (status === "open" && traceabilityReadiness && !traceabilityReadiness.ready && traceabilityReadiness.traceability_ready !== true) {
     status = "blocked";
     blockingReason = currentGate === "SD" ? "AGDF_SD_TRACEABILITY_INCOMPLETE" : "AGDF_TP_TRACEABILITY_INCOMPLETE";
     allowed = [currentGate === "SD"
@@ -458,8 +487,17 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
       : "complete the listed TP traceability rows and record a new run revision"];
     forbidden = [...forbidden, "present or approve the current artefact before its traceability is complete"];
     nextAllowedAction = currentGate === "SD"
-      ? "complete the listed SD traceability rows, then record the revision with run-update"
-      : "complete the listed TP traceability rows, then record the revision with run-update";
+      ? "complete the listed SD traceability rows, then record the revision through the inspected current recording operation"
+      : "complete the listed TP traceability rows, then record the revision through the inspected current recording operation";
+  }
+  if (status === "open" && approvalSummaryReadiness) {
+    status = "blocked";
+    blockingReason = "AGDF_APPROVAL_SUMMARY_INCOMPLETE";
+  }
+  if (blockingReason === "AGDF_APPROVAL_SUMMARY_INCOMPLETE") {
+    allowed = ["complete the current artefact approval summary and record a new run revision"];
+    forbidden = [...forbidden, "present or approve the current artefact before its required approval summary is ready"];
+    nextAllowedAction = "complete the current artefact approval summary, then record the revision through the inspected current recording operation";
   }
   if (status === "open" && /^Approval: /u.test(missingApproval) && !approvalArtefactReady) {
     allowed = allowed.filter((action) => !/^request exact .* approval$/iu.test(action));
@@ -646,7 +684,7 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
     : null);
   const completion = status === "pass" && transitionDecision.completion?.fulfilled
     ? transitionDecision.completion : { ...transitionDecision.completion, fulfilled: false,
-      status: extractField(runState.content ?? "", "lifecycle") === "completed" ? "unconfirmed" : "pending" };
+      status: { completed: "unconfirmed", superseded: "superseded", abandoned: "abandoned" }[extractField(runState.content ?? "", "lifecycle")] ?? "pending" };
   const sourceRevisions = sourceRevisionObservation(runState.content, doctorReport.findings.some(row => /AGDF_RUN_SEAL|AGDF_RUN_APPROVAL/u.test(row.code)));
 
   const report = {
@@ -661,6 +699,7 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
     ...(prdReadiness ? { prd_readiness: prdReadiness } : {}),
     ...(sdReadiness ? { sd_readiness: sdReadiness } : {}),
     ...(traceabilityReadiness ? { traceability_readiness: traceabilityReadiness } : {}),
+    ...(approvalSummaryReadiness ? { approval_summary_readiness: approvalSummaryReadiness } : {}),
     next_gate_after_approval: postApproval.next_gate_after_approval,
     allowed_after_approval: postApproval.allowed_after_approval,
     allowed,

package/runtime/core/lib/control-evaluation/gate-policy-inputs.js

@@ -0,0 +1,13 @@
+// Pure shared policy inputs; no host, filesystem, receipt-validation or clock access.
+export function extractField(content, field) {
+  const pattern = new RegExp(`^- ${field}:[^\\S\\r\\n]*(.*)$`, "m");
+  return content.match(pattern)?.[1]?.trim() ?? "";
+}
+
+export const verifiedChangeEscalationTargets = new Set(["structured_slice", "structured_delivery"]);
+export const STRUCTURED_REQUIRED_REVIEWS = Object.freeze(['TP Review', 'Clean Implementation Review']);
+// The skill that owns each required review report.
+export const REVIEW_SKILLS = Object.freeze({ 'TP Review': 'task-plan-review', 'Clean Implementation Review': 'clean-implementation-review' });
+// `Clean Review` is the supported legacy name of the Clean Implementation Review row.
+export const reviewArtefactType = (state, step) => step === 'Clean Implementation Review' && !state.artefacts.get(step)?.path
+  && state.artefacts.get('Clean Review')?.path ? 'Clean Review' : step;