create-agdf 0.14.4 → 0.20.0

package/runtime/core/lib/control-evaluation/decision-content-readiness.js

@@ -0,0 +1,131 @@
+import { readFileSync, statSync } from '../control-read/fs.js';
+import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
+import { artefactFileDigest } from '../control-state/run-seal-compute.js';
+import { readAuthoredContent, readReportDecision } from './report-decision.js';
+import { inspectQaReports } from './qa-follow-up.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 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())
+    && (allowNone || !/^(?:none|keine|n\/a|not_applicable)$/iu.test(value.trim()));
+}
+export function authoredGoal(text) {
+  const value = readAuthoredContent(text, 'goal');
+  return concreteDecisionContent(value) ? value : null;
+}
+
+function deliveredContent(value, title, path) {
+  if (!concreteDecisionContent(value)) return false;
+  if ([title, title?.replace(/^QA(?: Report)?:\s*/iu, ''), path?.split('/').at(-1)].some(name => name?.toLowerCase() === value.toLowerCase())) return false;
+  if (/^(?:\d+(?:\/\d+)?(?: tasks?)?(?: (?:done|complete|completed))?|all (?:tasks|criteria|checks) (?:are )?(?:done|complete|completed|fulfilled)|alle (?:aufgaben|kriterien) (?:sind )?(?:erledigt|erfüllt))\.?$/iu.test(value)) return false;
+  // Closed whole-value identifier/reference lists are association evidence only.
+  // Prose containing these references remains valid; no intent inference.
+  return !/^(?:(?:UR|PRD|SD|TP|QA(?:_REPORT)?|T-\d+|(?:[a-z0-9_.-]+\/)*[a-z0-9_.-]+\.(?:md|json|js|mjs|log)|\[[^\]\n]+\]\([^\)\n]+\))(?:[\s,;·|`]+|\s+(?:and|und)\s+|$))+$/iu.test(value.replace(/`/gu, ''));
+}
+
+// Fields that UAT reads from a localized approval summary, per gate and locale.
+const LOCALIZED_DECISION_FIELDS = Object.freeze({
+  UR: { de: [['ziel', 'goal', 'Ziel']], en: [['goal', 'goal', 'Goal']] },
+  QA: {
+    de: [['ergebnis', 'result', 'Ergebnis'], ['grenzen', 'limits', 'Grenzen'], ['risiken', 'risks', 'Risiken']],
+    en: [['delivered result', 'result', 'Delivered result'], ['qualification limits', 'limits', 'Qualification limits'], ['risks', 'risks', 'Risks']],
+  },
+});
+
+// One owner for the localized fields a later gate reads: UAT observation and the
+// earlier summary readiness/presentation call it, so they cannot disagree.
+export function localizedDecisionFields(gate, text, { locale, sourceLanguage, path } = {}) {
+  const spec = LOCALIZED_DECISION_FIELDS[gate]?.[locale];
+  if (!spec || locale === sourceLanguage) return { fields: {}, gaps: [] };
+  const summary = readAuthoredContent(text, 'localized', { locale, sourceLanguage });
+  const title = gate === 'QA' ? readAuthoredContent(text, 'title') : null;
+  const fields = {}, gaps = [];
+  for (const [field, key, label] of spec) {
+    // Older approved UR summaries state the goal as prose instead of a named field.
+    const value = summary?.[field] ?? (gate === 'UR' ? readAuthoredContent(text, 'localized_goal', { locale, sourceLanguage }) : undefined);
+    const concrete = gate === 'UR' ? concreteDecisionContent(value)
+      : key === 'result' ? deliveredContent(value, title, path) : concreteDecisionContent(value, { allowNone: true });
+    if (concrete) fields[key] = value;
+    else gaps.push({ field, key, expected: `- ${label}:` });
+  }
+  return { fields, gaps };
+}
+
+// Reads only captured contained sources. This pure observation neither decides
+// QA nor repairs, persists or approves any content. Historical proof stays owned
+// by the stored document/receipt readers, outside current preparation.
+export function observeDecisionContent(root, state, { gate, locale = 'en', sourceLanguage = 'en', readArtefact, objectiveOnly = false } = {}) {
+  const groups = {}, sources = [], gaps = [];
+  const gap = (field, path, owner, reason = 'missing_or_placeholder') => gaps.push({ field, path, owner, reason });
+  const result = () => ({ ready: gaps.length === 0, groups, sources, gaps });
+  if (state.meta?.lifecycle !== 'active') return result();
+  const ur = state.artefacts.get('UR');
+  if (!ur?.path) return result(); // Initial intake remains authorable.
+  const runPath = state.path || `.agdf/control/runs/${state.run_id}/RUN_STATE.md`;
+  if (!concreteDecisionContent(readAuthoredContent(state.content, 'objective'))) gap('Objective', runPath, 'gate-check');
+  if (objectiveOnly || !['QA', 'UAT'].includes(gate) || !['structured_slice', 'structured_delivery'].includes(state.mode_slice_decision?.decision)) return result();
+  const source = type => {
+    const row = state.artefacts.get(type), path = row?.path?.replace(/^`|`$/gu, '');
+    try {
+      if (!path || hasSymlinkComponent(root, path)) throw Error('unavailable');
+      const file = containedRegularFile(root, path);
+      if (file.status !== 'valid' || statSync(file.path).size > 131072) throw Error('unavailable');
+      const text = readArtefact ? readArtefact(path) : readFileSync(file.path, 'utf8');
+      if (typeof text !== 'string' || Buffer.byteLength(text) > 131072) throw Error('unavailable');
+      sources.push({ type, path, digest: artefactFileDigest(root, path) });
+      return { text, path };
+    } catch { gap(type, path || type, type === 'UR' ? 'ur-definition' : 'qa-gate', 'source_unavailable'); return {}; }
+  };
+  const qa = source('QA');
+  if (qa.text) {
+    for (const [profile, field, key] of [['result', 'delivered_result', 'result'], ['limits', 'qualification_limits', 'limits'], ['risks', 'delivery_risks', 'risks']]) {
+      const value = readAuthoredContent(qa.text, profile)?.[field];
+      const heading = readAuthoredContent(qa.text, 'title');
+      if (!(key === 'result' ? deliveredContent(value, heading, qa.path) : concreteDecisionContent(value, { allowNone: true }))) gap(field, qa.path, 'qa-gate');
+      else groups[key] = value;
+    }
+    groups.qa = readReportDecision(qa.text);
+    if (!groups.qa) gap('QA Decision', qa.path, 'qa-gate', 'technical_result_unconfirmed');
+    if (groups.qa === 'pass') {
+      const quality = inspectQaReports(root, state, state.run_id, 'pass', 64, true, { readArtefact });
+      if (quality.kind !== 'none' || quality.findings.length) {
+        gap('Normalized Findings', qa.path, 'qa-gate', quality.reason || 'open_review_findings_contradict_pass');
+      }
+      for (const observed of quality.sources) if (!sources.some(item => item.path === observed.path)) {
+        sources.push({ type: 'Review', path: observed.path, digest: observed.digest });
+      }
+    }
+    const localized = localizedDecisionFields('QA', qa.text, { locale, sourceLanguage, path: qa.path });
+    for (const missing of localized.gaps) gap(missing.field, qa.path, 'qa-gate', 'localized_content_missing');
+    Object.assign(groups, localized.fields);
+  }
+  if (gate === 'UAT') {
+    const intent = source('UR');
+    if (intent.text) {
+      const goal = authoredGoal(intent.text);
+      if (!goal) gap('Goal', intent.path, 'ur-definition');
+      else groups.goal = goal;
+      const localized = localizedDecisionFields('UR', intent.text, { locale, sourceLanguage, path: intent.path });
+      for (const missing of localized.gaps) gap(missing.field, intent.path, 'ur-definition', 'localized_content_missing');
+      Object.assign(groups, localized.fields);
+    }
+  }
+  return result();
+}
+
+export function decisionContentRecovery(observation, { locale = 'en', state } = {}) {
+  const de = locale === 'de';
+  return [(de ? 'Entscheidungsinhalt vervollständigen' : 'Complete decision content'), ...observation.gaps.map(g => {
+    const approved = state?.approvals?.get(g.owner === 'qa-gate' ? 'QA' : g.owner === 'ur-definition' ? 'UR' : '')?.status === 'approved';
+    return `${g.field}: ${g.reason} · ${g.path} · ${de ? 'Zuständig' : 'Owner'}: ${g.owner}. `
+      + (approved ? de ? 'Genehmigte Quelle bleibt geschützt; den bestehenden Erneuerungsweg prüfen, nicht still ändern.' : 'Approved source stays protected; assess its existing renewal route, do not silently edit.'
+        : de ? 'Nur erlaubte unfreigegebene Angaben kanonisch ergänzen und dieselbe aktuelle Fassung erneut prüfen.' : 'Complete only permitted unapproved content canonically and recheck this same current version.');
+  })].join('\n\n');
+}

package/runtime/core/lib/control-evaluation/definition-sources.js

@@ -0,0 +1,46 @@
+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';
+import { extractField } from './verified-change.js';
+import { previewRequirement } from '../control-state/preview-review.js';
+
+export const UX_DECISION_FORMAT = Object.freeze({ declaration: '- decision: ready | blocked | not_applicable', values: Object.freeze(['ready', 'blocked', 'not_applicable']), readiness_value: 'ready' });
+export function inspectUxIntentDecision(content) {
+  const decisions = [...content.matchAll(/^- decision:[ \t]*(.*)$/gmu)], decision = extractField(content, 'decision');
+  return { decision, well_formed: decisions.length === 1 && !!decision, supported: UX_DECISION_FORMAT.values.includes(decision), ready: decisions.length === 1 && decision === UX_DECISION_FORMAT.readiness_value };
+}
+
+// Read-only facts shared by authoring consumers. Facts never grant correction permission.
+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`;
+  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, '');
+    const file = containedRegularFile(root, path);
+    if (hasSymlinkComponent(root, path) || file.status !== 'valid') return issue('source_unavailable', path, type, file.status);
+    sources.push({ type, path, digest: artefactFileDigest(root, path) });
+    if (type === 'UR') {
+      try { previewRequirement(readFileSync(file.path, 'utf8')); }
+      catch (error) { return issue('source_unavailable', path, 'valid Preview requirement declaration', error.message); }
+    }
+  }
+  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 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');
+    const file = containedRegularFile(root, path);
+    if (file.status !== 'valid') return issue('ux_source_missing', path, '- decision: ready', file.status, file.status === 'missing');
+    const content = readFileSync(file.path, 'utf8');
+    const checked = inspectUxIntentDecision(content);
+    if (!checked.well_formed) return issue('ux_decision_malformed', path, '- decision: ready', 'exact unambiguous field required', true);
+    if (!checked.ready) return issue('ux_not_ready', path, '- decision: ready', checked.decision);
+    if (analysis?.status !== 'done' || String(analysis.path).replace(/^`|`$/gu, '') !== canonical) return issue('ux_source_unrecorded', path, 'UX Intent Definition: done at this path', analysis?.status || 'unrecorded', true);
+    sources.push({ type: 'UX Intent Definition', path, digest: artefactFileDigest(root, path) });
+  }
+  return { sources, issue: null };
+}

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

@@ -1,36 +1,17 @@
-import { existsSync } from 'node:fs';
+import { existsSync } from "../control-read/fs.js";
 import { join } from 'node:path';
-import { aggregate, resolveRuns } from '../control-state/index.js';
-import { resolveConfiguredChatLanguage } from '../cli/runtime-context.js';
-import { isGateSatisfied, transitionDecisionForRunState } from './gate-policy.js';
-import { gateApprovalStatus, readRunState, resolvedArtefactFile } from './run-state.js';
-import { allowNoActiveRuns, filled, isPlaceholderValue, markdownSection, parseBacklogSection, readTargetFile } from './shared.js';
-import { evaluateReconciliationState } from './parent-reconciliation.js';
-
-const deliveryRelationships = [
-  { from: "UR", relationship: "approved_by", to: "Approval: UR", requiredBy: "UR" },
-  { from: "PRD", relationship: "derived_from", to: "UR", requiredBy: "PRD" },
-  { from: "SD", relationship: "derived_from", to: "PRD", requiredBy: "SD" },
-  { from: "TP", relationship: "derived_from", to: "SD", requiredBy: "TP" },
-  { from: "QA_REPORT", relationship: "tests", to: "TP", requiredBy: "QA" },
-];
-
-function relationshipRequired(runState, requiredBy) {
-  if (gateApprovalStatus(runState, requiredBy) === "not_applicable") return false;
-  if (requiredBy === "QA") {
-    return isGateSatisfied(runState, "QA");
-  }
-
-  return isGateSatisfied(runState, requiredBy);
-}
-
-function findRelationship(runState, expected) {
-  return runState.artefact_chain.find((row) =>
-    row.from === expected.from
-    && row.relationship === expected.relationship
-    && row.to === expected.to
-  );
-}
+import { aggregate } from "../control-state/aggregate.js";
+import { resolveRuns } from "../control-state/run-state-resolver.js";
+import { resolveConfiguredChatLanguage } from "../resources/context.js";
+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 { evaluateReconciliationState } from "./parent-reconciliation.js";
+import { readSourceRevisions, sourceRevisionObservation } from "../control-state/run-source-revisions.js";
+import { readArtefactBindings } from "../control-state/artefact-bindings.js";
+import { validateBindingProof } from "../control-state/artefact-binding-proof.js";
 
 function severityFromImpact(value) {
   if (value === "block") return "block";
@@ -44,15 +25,25 @@ export function analyzeDeliveryMap(runState, dependencies = {}) {
   const reconciliation = evaluateReconciliationState(runState, dependencies);
   findings.push(...reconciliation.findings);
   const relationships = deliveryRelationships.map((expected) => {
-    const row = findRelationship(runState, expected);
-    const required = relationshipRequired(runState, expected.requiredBy);
+    const relevant = runState.artefact_chain.filter(row => row.from === expected.from && row.relationship === expected.relationship);
+    const row = relevant.find(row => sameRelationship(row, expected));
+    const required = relationshipRequired(expected, { approvalStatus: gateApprovalStatus(runState, expected.requiredBy),
+      satisfied: isGateSatisfied(runState, expected.requiredBy), currentGate: transitionDecisionForRunState(runState).current_gate,
+      artefact: runState.artefacts.get(expected.requiredBy), resolveFile: dependencies.resolveFile });
     const evidence = row?.evidence ?? "";
-    const status = !row ? "missing" : filled(evidence) ? "pass" : required ? "missing_evidence" : "template";
+    const revisions = readSourceRevisions(runState.content ?? "");
+    const binding = readArtefactBindings(runState.content ?? "").active.find(item => sameRelationship(item.relationship, expected)
+      && evidence.startsWith(`binding ${item.binding_id};`));
+    const currentProof = !revisions.present || expected.requiredBy === "UR" || Boolean(binding && dependencies.targetDir
+      && validateBindingProof(dependencies.targetDir, binding));
+    const status = relevant.length > 1 || relevant.some(row => !sameRelationship(row, expected)) ? "conflict"
+      : !row ? "missing" : filled(evidence) && currentProof ? "pass" : required ? "missing_evidence" : "template";
 
     if (required && status !== "pass") {
       findings.push({
         severity: "revise",
-        code: status === "missing" ? "AGDF_DELIVERY_RELATIONSHIP_MISSING" : "AGDF_DELIVERY_RELATIONSHIP_EVIDENCE_MISSING",
+        code: status === "missing" ? "AGDF_DELIVERY_RELATIONSHIP_MISSING"
+          : status === "conflict" ? "AGDF_DELIVERY_RELATIONSHIP_CONFLICT" : "AGDF_DELIVERY_RELATIONSHIP_EVIDENCE_MISSING",
         message: `${expected.from} must be traceable via ${expected.relationship} ${expected.to}.`,
         path: runState.path,
         next_step: "Fill the Artefact Chain row with concrete evidence before treating the delivery map as complete.",
@@ -221,6 +212,7 @@ export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}
   const doctorReport = evaluateDoctor(targetDir, selection);
   const runState = readRunState(targetDir, selection);
   const map = analyzeDeliveryMap(runState, {
+    targetDir,
     loadRun: (runId) => readRunState(targetDir, { runId }),
     resolveFile: (path) => resolvedArtefactFile(targetDir, path),
   });
@@ -234,8 +226,9 @@ export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}
   const status = maxSeverity >= 3 ? "block" : maxSeverity === 2 ? "revise" : maxSeverity === 1 ? "warn" : "pass";
 
   const qualityOutlook = deriveQualityOutlook(runState, map.findings);
-  const nextAllowedAction = isPlaceholderValue(runState.next_allowed_action) ? gateDecision.next_allowed_action : runState.next_allowed_action;
+  const nextAllowedAction = effectiveNextAllowedAction(runState, gateDecision);
   const postApproval = postApprovalTransition(gateDecision.missing_approval);
+  const sourceRevisions = sourceRevisionObservation(runState.content, doctorReport.findings.some(row => /AGDF_RUN_SEAL|AGDF_RUN_APPROVAL/u.test(row.code)));
 
   return {
     schema_version: "1",
@@ -243,6 +236,7 @@ export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}
     checked_at: new Date().toISOString(),
     target_dir: targetDir,
     current_gate: currentGate,
+    ...(sourceRevisions ? { source_revisions: sourceRevisions } : {}),
     next_allowed_action: nextAllowedAction,
     next_gate_after_approval: postApproval.next_gate_after_approval,
     allowed_after_approval: postApproval.allowed_after_approval,

package/runtime/core/lib/control-evaluation/delivery-relationships.js

@@ -0,0 +1,21 @@
+// Sole registry shared by audit, prospective readiness and reviewed artefact recording.
+export const deliveryRelationships = Object.freeze([
+  { from: "UR", relationship: "approved_by", to: "Approval: UR", requiredBy: "UR" },
+  { from: "PRD", relationship: "derived_from", to: "UR", requiredBy: "PRD" },
+  { from: "SD", relationship: "derived_from", to: "PRD", requiredBy: "SD" },
+  { from: "TP", relationship: "derived_from", to: "SD", requiredBy: "TP" },
+  { from: "QA_REPORT", relationship: "tests", to: "TP", requiredBy: "QA" },
+].map(Object.freeze));
+
+export const relationshipForGate = gate => deliveryRelationships.find(row => row.requiredBy === gate);
+export const sameRelationship = (row, expected) => row.from === expected.from
+  && row.relationship === expected.relationship && row.to === expected.to;
+
+export function relationshipRequired(expected, { approvalStatus, satisfied, currentGate, artefact, resolveFile } = {}) {
+  if (approvalStatus === "not_applicable") return false;
+  if (satisfied) return true;
+  if (expected.requiredBy === "UR") return false; // Only a deliberate UR approval creates this row.
+  const readyStatus = expected.requiredBy === "QA" ? ["pass", "passed"] : ["draft", "ready"];
+  return currentGate === expected.requiredBy && readyStatus.includes(artefact?.status)
+    && Boolean(artefact.path && resolveFile?.(artefact.path));
+}

package/{generated/plugins/copilot/agdf/runtime/create-agdf → runtime/core}/lib/control-evaluation/doctor.js

@@ -1,18 +1,52 @@
-import { existsSync } from 'node:fs';
+import { existsSync } from "../control-read/fs.js";
 import { dirname, join } from 'node:path';
-import { aggregate, resolveRuns, verifyLegacyProjection } from '../control-state/index.js';
-import { doctorRequiredFiles } from './required-files.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 { 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 { 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 { 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";
 
-export function evaluateDoctor(targetDir, selection = {}) {
+const RUN_SEAL_FINDINGS = Object.freeze({
+  approvals_changed: {
+    code: "AGDF_RUN_APPROVALS_UNRECORDED",
+    message: "The Approvals rows differ from the approvals recorded by run-approve.",
+    next_step: "Restore the recorded Approvals rows; record a gate approval only with run-approve after the exact user reply.",
+  },
+  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.",
+  },
+  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.",
+  },
+  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.",
+  },
+});
+
+export function evaluateDoctor(targetDir, selection = {}, dependencies = {}) {
+  return evaluateDoctorWithRunState(targetDir, selection, dependencies).report;
+}
+
+// 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 = {}) {
   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 }),
+      report: evaluateDoctor(targetDir, { runId: run.run_id }, dependencies),
     }));
     const status = selected.findings.length
       ? "block"
@@ -29,11 +63,16 @@ export function evaluateDoctor(targetDir, selection = {}) {
       })),
       ...runs.flatMap((item) => item.report.findings.map((finding) => ({ ...finding, run_id: item.run_id }))),
     ];
-    return {
+    return { report: {
       schema_version: "1",
       status,
       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,
+      },
       summary: {
         findings: findings.length,
         block: findings.filter((finding) => finding.severity === "block").length,
@@ -42,10 +81,20 @@ export function evaluateDoctor(targetDir, selection = {}) {
       },
       findings,
       runs,
-    };
+    } };
   }
   const findings = [];
-  let reconciliation;
+  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.",
+    );
+  }
+  let reconciliation, selectedRunState;
   const hasCanonicalRuns = existsSync(join(targetDir, ".agdf", "control", "runs"));
   if (hasCanonicalRuns) {
     const projection = verifyLegacyProjection(targetDir);
@@ -80,7 +129,7 @@ export function evaluateDoctor(targetDir, selection = {}) {
   }
 
   if (missing.length === 0) {
-    const selectedRunState = readRunState(targetDir, selection);
+    selectedRunState = readRunState(targetDir, selection);
     const runPath = selectedRunState.path;
     const run = selectedRunState.content;
 
@@ -97,6 +146,10 @@ export function evaluateDoctor(targetDir, selection = {}) {
       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 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(
@@ -143,6 +196,9 @@ export function evaluateDoctor(targetDir, selection = {}) {
           "Run run-migrate to repair the run identity, or migrate the legacy state to a canonical run record.",
         );
       }
+
+      const sealFinding = RUN_SEAL_FINDINGS[runSealState(targetDir, run).status];
+      if (sealFinding) addFinding(findings, "block", sealFinding.code, sealFinding.message, runPath, sealFinding.next_step);
     }
 
     const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");
@@ -152,7 +208,8 @@ export function evaluateDoctor(targetDir, selection = {}) {
     const completedRows = tableRows(markdownSection(backlog, "Completed / Superseded Pointers"))
       .slice(1)
       .filter((cells) => cells.some((cell) => filled(cell)));
-    if (!hasFilledTableRow(backlog, /^P[0-9]/) && completedRows.length === 0) {
+    // 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",
@@ -223,8 +280,18 @@ export function evaluateDoctor(targetDir, selection = {}) {
     }
 
     const runState = selectedRunState;
+    for (const type of runState.artefact_row_duplicates ?? []) {
+      addFinding(
+        findings,
+        "block",
+        "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.",
+      );
+    }
     if (modeSliceDecision(runState) === "verified_change") {
-      const verifiedChange = evaluateVerifiedChange(targetDir, runState);
+      const verifiedChange = evaluateVerifiedChange(targetDir, runState, dependencies);
       for (const finding of verifiedChange.findings) {
         addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
       }
@@ -236,6 +303,7 @@ export function evaluateDoctor(targetDir, selection = {}) {
       addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
     }
     reconciliation = analyzeDeliveryMap(runState, {
+      targetDir,
       loadRun: (runId) => readRunState(targetDir, { runId }),
       resolveFile: (path) => resolvedArtefactFile(targetDir, path),
     });
@@ -248,7 +316,7 @@ export function evaluateDoctor(targetDir, selection = {}) {
   const maxSeverity = findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
   const status = maxSeverity >= 3 ? "block" : maxSeverity === 2 ? "revise" : maxSeverity === 1 ? "warn" : "pass";
 
-  return {
+  return { runState: selectedRunState, report: {
     schema_version: "1",
     status,
     checked_at: new Date().toISOString(),
@@ -262,7 +330,7 @@ export function evaluateDoctor(targetDir, selection = {}) {
     parent_reconciliation: reconciliation?.parent_reconciliation,
     programme_aggregation: reconciliation?.programme_aggregation,
     findings,
-  };
+  } };
 }
 
 export function printDoctorReport(report, json, io = console) {