create-agdf 0.20.2 → 0.31.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/acceptance-criteria.js

@@ -4,6 +4,8 @@ const CRITERION_ID = /^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*$/u;
 export const ACCEPTANCE_CRITERIA_FORMAT = Object.freeze({
   section: "Acceptance Criteria", declaration: "criterion_id: <stable id>",
   fields: "semicolon-separated inline fields or following bullet key: value lines",
+  description_fields: Object.freeze(["observable_success", "visible_feedback", "expected_effective_state"]),
+  description_rule: "For same-language approval rendering, provide at least one nonempty description field separately. Never concatenate field names or infer their meaning from combined keys.",
   id_pattern: CRITERION_ID.source,
   examples: Object.freeze([
     "## Acceptance Criteria\n- criterion_id: AC-001; observable_success: Saved choice remains selected",

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/closeout-readiness.js

@@ -8,6 +8,14 @@ import { inspectQaReports } from './qa-follow-up.js';
 export { STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType };
 
 export const closeoutConfirmation = (runId, revisionId, operationId, orDigest) => `Close Run: ${runId} ${revisionId} ${operationId} ${orDigest}`;
+// Discovery and validation share the existing compact document requirements.
+export const QUICK_CLOSEOUT_AUTHORING_FORMAT = {
+  template: 'OR', report_mode: 'OR-lite',
+  required_metadata: [{ field: 'run_id', label: 'Run' }, { field: 'report_mode', label: 'Report mode' }],
+  run_binding: 'Exactly one Run: <current run_id> or - run_id: <current run_id>; never both.',
+  required_sections: ['Result', 'Evidence', 'Risk', 'Next Step'],
+  template_scope: 'Use the bound OR template for identity; OR-lite needs only the declared metadata and four concrete sections, not OR-full sections.',
+};
 const value = (text, field, label) => cleanStatusCell(extractField(text, field) || (label ? text.match(new RegExp(`^${label}:[ \\t]*(.*)$`, 'mu'))?.[1] : ''));
 const concrete = text => filled(text) && !isPlaceholderValue(text) && !/^(?:tbd|todo|<)/iu.test(text);
 export function closeoutContext(text) {
@@ -16,13 +24,31 @@ export function closeoutContext(text) {
 }
 export const closeoutContextDigest = text => digest(`agdf-closeout-context/1\0${canonicalJson(closeoutContext(text))}`);
 
+// Bindings a structured OR states; the same tables drive the check and the
+// expectations returned with a refusal.
+const OR_SOURCE_FIELDS = Object.freeze({ related_ur: 'UR', related_prd: 'PRD', related_sd: 'SD', related_tp: 'TP', related_qa_report: 'QA' });
+const OR_GATE_ROWS = Object.freeze(['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'Brownfield Analysis', 'CD+Tests', 'CR', 'QA', 'UAT']);
+const OR_MEMORY_TARGETS = Object.freeze(['context_graph', 'sot_registry', 'scope_artifact', 'open_questions', 'none']);
+const gateRowExpectation = (state, type) => ({
+  status: state.approvals.has(type) ? state.approvals.get(type).status : state.artefacts.get(type)?.status,
+  reference: state.artefacts.get(type)?.path || state.approvals.get(type)?.evidence,
+});
+function structuredOrExpectations(state, route) {
+  return {
+    fields: { ...Object.fromEntries(Object.entries(OR_SOURCE_FIELDS).map(([field, type]) => [field, state.artefacts.get(type)?.path ?? null])),
+      mode_slice_decision: route, current_gate: 'OR', decision: 'pass', required_approval: 'none' },
+    gate_state_rows: Object.fromEntries(OR_GATE_ROWS.map(type => [type, gateRowExpectation(state, type)])),
+    memory_target: OR_MEMORY_TARGETS, memory_fields: 'memory_reason and memory_refs need concrete text',
+  };
+}
+
 // Shared observation of registered OR and prepared OR candidates. Legacy reports retain
 // their documented formats; the new writer additionally requires the complete template.
 export function evaluateCloseoutReadiness(state, report, readArtefact, { prepared = false } = {}) {
   const findings = [], fail = reason => findings.push(reason), route = state.mode_slice_decision?.decision;
   const structured = ['structured_slice', 'structured_delivery'].includes(route);
   if (typeof report !== 'string' || Buffer.byteLength(report) > 131072) return { ready: false, findings: ['or_unavailable_or_oversized'] };
-  if (prepared) for (const [field, label] of [['run_id', 'Run'], ['report_mode', 'Report mode'], ...(structured ? [['status', 'Status']] : [])]) {
+  if (prepared) for (const [field, label] of [...QUICK_CLOSEOUT_AUTHORING_FORMAT.required_metadata.map(row => [row.field, row.label]), ...(structured ? [['status', 'Status']] : [])]) {
     const declarations = [...report.matchAll(new RegExp(`^(?:- ${field}|${label}):[ \\t]*(.*)$`, 'gmu'))];
     if (declarations.length !== 1) fail('or_field_ambiguous:' + field);
   }
@@ -34,7 +60,7 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
   if (programme?.applicable && !programme.final_ready) fail('programme_aggregation_unfulfilled');
   if (!structured) {
     if (state.artefacts.get('CR')?.status !== 'done') fail('code_review_missing');
-    for (const section of ['Result', 'Evidence', 'Risk', 'Next Step']) if (!concrete(markdownSection(report, section).trim())) fail(`or_${section.toLowerCase().replaceAll(' ', '_')}_missing`);
+    for (const section of QUICK_CLOSEOUT_AUTHORING_FORMAT.required_sections) if (!concrete(markdownSection(report, section).trim())) fail(`or_${section.toLowerCase().replaceAll(' ', '_')}_missing`);
   } else {
     if (!['done', 'completed', 'pass'].includes(value(report, 'status', 'Status'))) fail('or_status_unconfirmed');
     for (const gate of ['UR', 'PRD', 'SD', 'TP', 'QA', 'UAT']) {
@@ -77,14 +103,13 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
         ...Object.keys(context), 'next_allowed_action', 'required_approval', 'forbidden_until_then']) {
         if ([...report.matchAll(new RegExp(`^- ${field}:[ \\t]*(.*)$`, 'gmu'))].length !== 1) fail('or_field_ambiguous:' + field);
       }
-      for (const [field, type] of Object.entries({ related_ur: 'UR', related_prd: 'PRD', related_sd: 'SD', related_tp: 'TP', related_qa_report: 'QA' })) {
+      for (const [field, type] of Object.entries(OR_SOURCE_FIELDS)) {
         if (value(report, field) !== state.artefacts.get(type)?.path) fail('or_source_reference_invalid:' + field);
       }
       if (value(report, 'mode_slice_decision') !== route || value(report, 'current_gate') !== 'OR' || value(report, 'decision') !== 'pass') fail('or_control_binding_invalid');
       const gateRows = tableRows(markdownSection(report, 'Gate State')).filter(row => row[0] !== 'Gate or step');
-      for (const type of ['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'Brownfield Analysis', 'CD+Tests', 'CR', 'QA', 'UAT']) {
-        const rows = gateRows.filter(row => row[0] === type), expected = state.approvals.has(type) ? state.approvals.get(type).status : state.artefacts.get(type)?.status;
-        const reference = state.artefacts.get(type)?.path || state.approvals.get(type)?.evidence;
+      for (const type of OR_GATE_ROWS) {
+        const rows = gateRows.filter(row => row[0] === type), { status: expected, reference } = gateRowExpectation(state, type);
         if (rows.length !== 1 || rows[0][1] !== expected || !concrete(rows[0][2])
           || cleanStatusCell(rows[0][2]) !== cleanStatusCell(reference)) fail('or_gate_state_unconfirmed:' + type);
       }
@@ -93,11 +118,12 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
         if (!concrete(text) || /<[^>]+>|\|[ \t]*\|/u.test(text)) fail('or_section_incomplete:' + section);
       }
       for (const section of ['Missing Evidence', 'Risks And Open Items']) if (/\|\s*(?:revise|block)\s*\|/u.test(markdownSection(report, section))) fail('or_required_obligation_open:' + section);
-      if (!['context_graph', 'sot_registry', 'scope_artifact', 'open_questions', 'none'].includes(context.memory_target)
+      if (!OR_MEMORY_TARGETS.includes(context.memory_target)
         || !concrete(context.memory_reason) || !concrete(context.memory_refs)) fail('or_knowledge_decision_incomplete');
       if (value(report, 'required_approval') !== 'none') fail('or_required_approval_open');
     }
   }
   return { ready: findings.length === 0, findings, route, context_digest: closeoutContextDigest(report),
-    parent_reconciliation: parent ?? null, programme_aggregation: programme ?? null };
+    parent_reconciliation: parent ?? null, programme_aggregation: programme ?? null,
+    ...(prepared && structured && findings.length ? { expected: structuredOrExpectations(state, route) } : {}) };
 }

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/decision-content-placeholder.js

@@ -0,0 +1,9 @@
+// Template prompts and status-only values that never count as authored content. Pure, so the
+// run inventory and other `node:`-free readers share the same rule.
+const prompts = new Set(['describe the trustworthy outcome.', 'what outcome should become possible?',
+  'which tp tasks are fully done, partially done or not done?', 'what remains unverified?', 'which risks remain and what is their impact?']);
+export function isDecisionContentPlaceholder(value) {
+  if (typeof value !== 'string') return true;
+  const text = value.trim().replace(/^`([^`]+)`$/u, '$1').replace(/\s+/gu, ' ').toLowerCase();
+  return !text || prompts.has(text) || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/.test(text);
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/decision-content-readiness.js

@@ -3,14 +3,9 @@ import { containedRegularFile, hasSymlinkComponent } from '../control-state/cont
 import { artefactFileDigest } from '../control-state/run-seal-compute.js';
 import { readAuthoredContent, readReportDecision } from './report-decision.js';
 import { inspectQaReports } from './qa-follow-up.js';
+import { isDecisionContentPlaceholder } from './decision-content-placeholder.js';
 
-const prompts = new Set(['describe the trustworthy outcome.', 'what outcome should become possible?',
-  'which tp tasks are fully done, partially done or not done?', 'what remains unverified?', 'which risks remain and what is their impact?']);
-export function isDecisionContentPlaceholder(value) {
-  if (typeof value !== 'string') return true;
-  const text = value.trim().replace(/^`([^`]+)`$/u, '$1').replace(/\s+/gu, ' ').toLowerCase();
-  return !text || prompts.has(text) || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/.test(text);
-}
+export { isDecisionContentPlaceholder };
 export function concreteDecisionContent(value, { allowNone = false } = {}) {
   return typeof value === 'string' && value.length <= 1200 && !isDecisionContentPlaceholder(value)
     && !/^(?:pass|passed|revise|block|done|ready|draft)$/iu.test(value.trim())

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/definition-sources.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { readFileSync } from '../control-read/fs.js';
 import { hasSymlinkComponent, containedRegularFile } from '../control-state/contained-file.js';
 import { artefactFileDigest } from '../control-state/run-seal-compute.js';
@@ -14,7 +15,7 @@ export function inspectUxIntentDecision(content) {
 export function inspectDefinitionSources(root, state, runId, gate, sourceTypes) {
   const sources = [];
   const issue = (code, path, expected, observed, repairable = false) => ({ sources, issue: { code, path, expected, observed, repairable } });
-  const output = `.agdf/control/artefacts/${runId}/${gate}.md`;
+  const output = `${runDocumentPath(runId, '')}/${gate}.md`;
   if (!state || hasSymlinkComponent(root, output)) return issue('unsafe_destination', output, 'contained non-symlink output', 'unsafe');
   for (const type of sourceTypes) {
     const path = String(state.artefacts.get(type)?.path ?? '').replace(/^`|`$/gu, '');
@@ -29,7 +30,7 @@ export function inspectDefinitionSources(root, state, runId, gate, sourceTypes)
   const reviewSource = sources.find(source => source.type === 'Brownfield Review');
   const review = reviewSource ? readFileSync(containedRegularFile(root, reviewSource.path).path, 'utf8') : '';
   if (extractField(review, 'ux_intent_definition_required') === 'yes') {
-    const canonical = `.agdf/control/artefacts/${runId}/UX_INTENT_DEFINITION.md`;
+    const canonical = `${runDocumentPath(runId, '')}/UX_INTENT_DEFINITION.md`;
     const analysis = state.artefacts.get('UX Intent Definition');
     const path = String(analysis?.path || canonical).replace(/^`|`$/gu, '');
     if (path !== canonical || hasSymlinkComponent(root, path)) return issue('unsafe_ux_source', path, canonical, 'foreign or unsafe source');

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/delivery-map.js

@@ -1,5 +1,3 @@
-import { existsSync } from "../control-read/fs.js";
-import { join } from 'node:path';
 import { aggregate } from "../control-state/aggregate.js";
 import { resolveRuns } from "../control-state/run-state-resolver.js";
 import { resolveConfiguredChatLanguage } from "../resources/context.js";
@@ -7,7 +5,7 @@ import { isGateSatisfied, transitionDecisionForRunState } from "./gate-policy.js
 import { effectiveNextAllowedAction } from "./next-action.js";
 import { gateApprovalStatus, readRunState, resolvedArtefactFile } from "./run-state.js";
 import { deliveryRelationships, relationshipRequired, sameRelationship } from "./delivery-relationships.js";
-import { allowNoActiveRuns, filled, markdownSection, parseBacklogSection, readTargetFile } from "./shared.js";
+import { allowNoActiveRuns, filled } from "./shared.js";
 import { evaluateReconciliationState } from "./parent-reconciliation.js";
 import { readSourceRevisions, sourceRevisionObservation } from "../control-state/run-source-revisions.js";
 import { readArtefactBindings } from "../control-state/artefact-bindings.js";
@@ -153,14 +151,6 @@ export function deriveQualityOutlook(runState, findings = []) {
   return "No additional quality follow-up identified from the current control state.";
 }
 
-function readBacklogPointers(targetDir) {
-  const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");
-  if (!existsSync(join(targetDir, backlogPath))) return [];
-
-  const backlog = readTargetFile(targetDir, backlogPath);
-  const activeSection = markdownSection(backlog, "Active Backlog");
-  return parseBacklogSection(activeSection);
-}
 
 export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}) {
   const { evaluateDoctor, buildStatusCard, postApprovalTransition } = dependencies;
@@ -253,7 +243,7 @@ export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}
       chatLanguage: resolveConfiguredChatLanguage(targetDir),
       findings: map.findings,
     }),
-    backlog_pointers: readBacklogPointers(targetDir),
+    backlog_pointers: [], // Legacy field: current relationships come from registered Run sources.
     artefacts: Object.fromEntries([...runState.artefacts.entries()]),
     approvals: Object.fromEntries([...runState.approvals.entries()]),
     mode_slice_decision: runState.mode_slice_decision,

package/generated/plugins/agdf/runtime/create-agdf/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("");