create-agdf 0.2.2 → 0.2.4

package/bin/create-agdf.js

@@ -11,9 +11,18 @@ const generatedRoot = join(packageRoot, "generated");
 const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
 const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
 const pluginInstallCommand = "claude plugin add arndtgold/ai-native-governance-delivery-framework";
-const allowedTargets = new Set(["codex", "copilot", "both", "init", "doctor", "gate-check"]);
+const allowedTargets = new Set(["codex", "copilot", "both", "init", "doctor", "gate-check", "delivery-map"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
+const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
+const internalStepArtefacts = new Set(["Brownfield Review"]);
+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" },
+];
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const codexPluginFiles = [
@@ -25,6 +34,12 @@ const codexPluginFiles = [
   join("plugins", "agdf", "control", "templates", "SOT_REGISTRY.md"),
   join("plugins", "agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join("plugins", "agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "UR.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "PRD.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "SD.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "TP.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "OR.md"),
   join("plugins", "agdf", "hooks", "hooks.json"),
   join("plugins", "agdf", "hooks", "session-start.sh"),
   join("plugins", "agdf", "meta", "agdf-agent-router.md"),
@@ -41,6 +56,12 @@ const controlFiles = [
   join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
   join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "PRD.md"),
+  join(".agdf", "control", "templates", "artefacts", "SD.md"),
+  join(".agdf", "control", "templates", "artefacts", "TP.md"),
+  join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+  join(".agdf", "control", "templates", "artefacts", "OR.md"),
 ];
 const liveControlFiles = [
   {
@@ -64,6 +85,14 @@ const liveControlFiles = [
     source: join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
   },
 ];
+const artefactTemplateFiles = [
+  join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "PRD.md"),
+  join(".agdf", "control", "templates", "artefacts", "SD.md"),
+  join(".agdf", "control", "templates", "artefacts", "TP.md"),
+  join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+  join(".agdf", "control", "templates", "artefacts", "OR.md"),
+];
 const doctorRequiredFiles = [
   join(".agdf", "control", "AGDF_RUN.md"),
   join(".agdf", "control", "MASTER_BACKLOG.md"),
@@ -91,11 +120,12 @@ Usage:
   npm create agdf@latest init
   npm create agdf@latest doctor
   npm create agdf@latest gate-check
+  npm create agdf@latest delivery-map
 
 Options:
   --dir <path>   Write files into a specific directory
   --force        Overwrite existing generated files
-  --json         Print doctor or gate-check output as JSON
+  --json         Print doctor, gate-check or delivery-map output as JSON
   --help         Show this help
 `);
 }
@@ -158,7 +188,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot, both, init, doctor or gate-check.");
+    console.error("Please choose one target: codex, copilot, both, init, doctor, gate-check or delivery-map.");
     printUsage();
     process.exit(1);
   }
@@ -202,6 +232,13 @@ function generatedFilesForTarget(target, targetDir, force) {
       });
     }
 
+    for (const templatePath of artefactTemplateFiles) {
+      files.push({
+        path: templatePath,
+        content: loadAsset(templatePath),
+      });
+    }
+
     return files;
   }
 
@@ -336,6 +373,21 @@ function hasFilledEvidenceRow(content) {
     });
 }
 
+function markdownSection(content, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return content.match(new RegExp(`(?:^|\\n)## ${escaped}\\s*\\n([\\s\\S]*?)(?:\\n## |\\n# |$)`))?.[1] ?? "";
+}
+
+function filled(value) {
+  return Boolean(value && !isPlaceholderValue(value) && value.trim() !== "");
+}
+
+function nonTemplateRows(section, headerCell) {
+  return tableRows(section)
+    .filter((cells) => cells[0] !== headerCell)
+    .filter((cells) => cells.some((cell) => filled(cell)));
+}
+
 function parseQualityContracts(content) {
   const parsed = JSON.parse(content);
   if (!Array.isArray(parsed.contracts) || parsed.contracts.length === 0) {
@@ -479,6 +531,11 @@ function evaluateDoctor(targetDir) {
         "Restore the generated contracts or fix the JSON contract schema.",
       );
     }
+
+    const runState = readRunState(targetDir);
+    for (const finding of analyzeDeliveryMap(runState).findings) {
+      addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
+    }
   }
 
   const severityRank = { block: 3, revise: 2, warn: 1 };
@@ -524,10 +581,26 @@ function extractField(content, field) {
   return content.match(pattern)?.[1]?.trim() ?? "";
 }
 
+function extractSectionField(section, field) {
+  const pattern = new RegExp(`^- ${field}:[^\\S\\r\\n]*(.*)$`, "m");
+  return section.match(pattern)?.[1]?.trim() ?? "";
+}
+
 function cleanStatusCell(value) {
   return value.replace(/^`|`$/g, "").trim();
 }
 
+function addApprovalRows(approvals, section) {
+  for (const cells of tableRows(section)) {
+    const [gate, status, evidence] = cells;
+    if (!userGateOrder.includes(gate)) continue;
+    approvals.set(gate, {
+      status: cleanStatusCell(status ?? ""),
+      evidence: evidence ?? "",
+    });
+  }
+}
+
 function readRunState(targetDir) {
   const runPath = join(".agdf", "control", "AGDF_RUN.md");
   if (!existsSync(join(targetDir, runPath))) {
@@ -537,26 +610,44 @@ function readRunState(targetDir) {
       current_gate: "",
       next_allowed_action: "",
       approvals: new Map(),
+      artefacts: new Map(),
       evidence_refs: [],
+      artefact_chain: [],
+      mode_slice_decision: {},
+      missing_evidence: [],
+      risks: [],
+      context_graph: {},
     };
   }
 
   const content = readTargetFile(targetDir, runPath);
-  const approvalsSection = content.match(/## Approvals([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
   const approvals = new Map();
-  for (const cells of tableRows(approvalsSection)) {
-    const [gate, status, evidence] = cells;
-    if (!userGateOrder.includes(gate)) continue;
-    approvals.set(gate, {
+  addApprovalRows(approvals, content.match(/## Approvals([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "");
+  addApprovalRows(approvals, content.match(/## Gate Checklist([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "");
+
+  const artefacts = new Map();
+  const artefactsSection = markdownSection(content, "Artefacts");
+  for (const cells of tableRows(artefactsSection)) {
+    const [type, path, status, notes] = cells;
+    if (!userGateOrder.includes(type) && !internalStepArtefacts.has(type)) continue;
+    artefacts.set(type, {
+      path: path ?? "",
       status: cleanStatusCell(status ?? ""),
-      evidence: evidence ?? "",
+      notes: notes ?? "",
     });
   }
 
-  const evidenceSection = content.match(/## Evidence([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
-  const evidence_refs = tableRows(evidenceSection)
+  const artefactChain = nonTemplateRows(markdownSection(content, "Artefact Chain"), "From")
+    .map((cells) => ({
+      from: cells[0] ?? "",
+      relationship: cleanStatusCell(cells[1] ?? ""),
+      to: cleanStatusCell(cells[2] ?? ""),
+      evidence: cells[3] ?? "",
+    }));
+
+  const evidence_refs = tableRows(markdownSection(content, "Evidence"))
     .filter((cells) => cells[0] !== "Evidence")
-    .filter((cells) => Boolean(cells[0] || cells[1] || cells[2]))
+    .filter((cells) => filled(cells[0]) || filled(cells[1]) || filled(cells[2]))
     .map((cells) => ({
       evidence: cells[0] ?? "",
       source: cells[1] ?? "",
@@ -564,13 +655,53 @@ function readRunState(targetDir) {
       strength: cleanStatusCell(cells[3] ?? ""),
     }));
 
+  const missingEvidence = tableRows(markdownSection(content, "Missing Evidence"))
+    .filter((cells) => cells[0] !== "Missing evidence")
+    .filter((cells) => filled(cells[0]))
+    .map((cells) => ({
+      missing_evidence: cells[0] ?? "",
+      impact: cleanStatusCell(cells[1] ?? ""),
+      required_next_step: cells[2] ?? "",
+    }));
+
+  const risks = tableRows(markdownSection(content, "Risks"))
+    .filter((cells) => cells[0] !== "Risk")
+    .filter((cells) => filled(cells[0]))
+    .map((cells) => ({
+      risk: cells[0] ?? "",
+      impact: cleanStatusCell(cells[1] ?? ""),
+      mitigation_or_owner: cells[2] ?? "",
+    }));
+
+  const contextGraph = {
+    impact: cleanStatusCell(extractField(content, "context_graph_impact")),
+    refs: extractField(content, "context_graph_refs"),
+    required_action: cleanStatusCell(extractField(content, "context_graph_required_action")),
+    gate_effect: cleanStatusCell(extractField(content, "context_graph_gate_effect")),
+    evidence: extractField(content, "context_graph_evidence"),
+  };
+
+  const modeSliceSection = markdownSection(content, "Mode / Slice Decision");
+  const modeSliceDecision = {
+    decision: cleanStatusCell(extractSectionField(modeSliceSection, "decision")),
+    required_next_gate: cleanStatusCell(extractSectionField(modeSliceSection, "required_next_gate")),
+    scope_reason: extractSectionField(modeSliceSection, "scope_reason"),
+    evidence: extractSectionField(modeSliceSection, "evidence"),
+  };
+
   return {
     path: runPath,
     content,
     current_gate: extractField(content, "current_gate"),
     next_allowed_action: extractField(content, "next_allowed_action"),
     approvals,
+    artefacts,
     evidence_refs,
+    artefact_chain: artefactChain,
+    mode_slice_decision: modeSliceDecision,
+    missing_evidence: missingEvidence,
+    risks,
+    context_graph: contextGraph,
   };
 }
 
@@ -593,29 +724,301 @@ function gateApprovalStatus(runState, gate) {
   return runState.approvals.get(gate)?.status ?? "";
 }
 
+function gateArtefactStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return { status: "not_applicable", path: "" };
+  return runState.artefacts.get(gate) ?? { status: "", path: "" };
+}
+
+function isDurableGateArtefactSatisfied(runState, gate) {
+  if (!durableGateArtefacts.has(gate)) return true;
+  const artefact = gateArtefactStatus(runState, gate);
+  if (!artefact.path || isPlaceholderValue(artefact.path)) return false;
+  if (gate === "QA") return artefact.status === "pass";
+  return artefact.status === "approved";
+}
+
+function isInternalStepSatisfied(runState, step) {
+  const artefact = runState.artefacts.get(step);
+  if (!artefact) return false;
+  return artefact.status === "done" || artefact.status === "not_applicable";
+}
+
+function modeSliceDecision(runState) {
+  const decision = runState.mode_slice_decision?.decision ?? "";
+  if (!decision || isPlaceholderValue(decision)) return "undecided";
+  return decision;
+}
+
+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
+  );
+}
+
+function severityFromImpact(value) {
+  if (value === "block") return "block";
+  if (value === "revise") return "revise";
+  if (value === "warning" || value === "warn") return "warn";
+  return null;
+}
+
+function analyzeDeliveryMap(runState) {
+  const findings = [];
+  const relationships = deliveryRelationships.map((expected) => {
+    const row = findRelationship(runState, expected);
+    const required = relationshipRequired(runState, expected.requiredBy);
+    const evidence = row?.evidence ?? "";
+    const status = !row ? "missing" : filled(evidence) ? "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",
+        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.",
+      });
+    }
+
+    return {
+      from: expected.from,
+      relationship: expected.relationship,
+      to: expected.to,
+      required,
+      status,
+      evidence,
+    };
+  });
+
+  for (const item of runState.missing_evidence) {
+    const severity = severityFromImpact(item.impact);
+    if (!severity) continue;
+    findings.push({
+      severity,
+      code: "AGDF_MISSING_EVIDENCE_DECLARED",
+      message: item.missing_evidence,
+      path: runState.path,
+      next_step: item.required_next_step || "Resolve or explicitly accept the missing evidence before advancing the gate.",
+    });
+  }
+
+  for (const item of runState.risks) {
+    const severity = severityFromImpact(item.impact);
+    if (!severity) continue;
+    findings.push({
+      severity,
+      code: "AGDF_RISK_DECLARED",
+      message: item.risk,
+      path: runState.path,
+      next_step: item.mitigation_or_owner || "Assign mitigation or ownership before advancing the gate.",
+    });
+  }
+
+  const contextSeverity = severityFromImpact(runState.context_graph?.gate_effect);
+  if (contextSeverity) {
+    findings.push({
+      severity: contextSeverity,
+      code: "AGDF_CONTEXT_GRAPH_GATE_EFFECT",
+      message: `Context Graph impact is ${runState.context_graph.impact || "unspecified"} with gate effect ${runState.context_graph.gate_effect}.`,
+      path: runState.path,
+      next_step: runState.context_graph.required_action && runState.context_graph.required_action !== "none"
+        ? `Resolve Context Graph action: ${runState.context_graph.required_action}.`
+        : "Clarify the Context Graph impact before advancing the gate.",
+    });
+  }
+
+  return {
+    relationships,
+    missing_evidence: runState.missing_evidence,
+    risks: runState.risks,
+    context_graph: runState.context_graph,
+    findings,
+  };
+}
+
+function durableArtefactBlock(gate, nextGate) {
+  const label = gate === "QA" ? "QA report" : `${gate} artefact`;
+  const stablePath = gate === "QA" ? ".agdf/control/artefacts/<key>/QA_REPORT.md" : `.agdf/control/artefacts/<key>/${gate}.md`;
+  return {
+    status: "blocked",
+    current_gate: gate,
+    blocking_reason: `missing_durable_${gate.toLowerCase()}_artefact`,
+    missing_approval: "none",
+    allowed: [
+      `persist the approved ${label} in a stable artefact path such as ${stablePath}`,
+      "link the artefact from AGDF_RUN.md and MASTER_BACKLOG.md",
+      "run gate-check again",
+    ],
+    forbidden: nextGate
+      ? [`create ${nextGate}`, "create later-gate artefacts", "implement gated work", "claim QA or release readiness"]
+      : ["create later-gate artefacts", "implement gated work", "claim release readiness"],
+    next_allowed_action: `Persist the approved ${label} and link it from the AGDF control state before continuing.`,
+  };
+}
+
+function isGateSatisfied(runState, gate) {
+  const status = gateApprovalStatus(runState, gate);
+  if (status === "not_applicable") return true;
+  if (status !== "approved") return false;
+  return isDurableGateArtefactSatisfied(runState, gate);
+}
+
+function transitionDecisionForRunState(runState) {
+  if (gateApprovalStatus(runState, "UR") === "approved" && !isGateSatisfied(runState, "UR")) return durableArtefactBlock("UR", "PRD");
+
+  if (!isGateSatisfied(runState, "UR")) {
+    return {
+      status: "blocked",
+      current_gate: "UR",
+      blocking_reason: "missing_exact_approval",
+      missing_approval: "Approval: UR",
+      allowed: ["clarify user need", "formulate and persist UR", "record evidence", "request exact UR approval"],
+      forbidden: ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Clarify the user requirement, persist the UR, and request exact approval: Approval: UR",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "PRD") === "approved" && !isGateSatisfied(runState, "PRD")) return durableArtefactBlock("PRD", "SD");
+
+  if (!isGateSatisfied(runState, "PRD")) {
+    if (!isInternalStepSatisfied(runState, "Brownfield Review")) {
+      return {
+        status: "open",
+        current_gate: "Brownfield Review",
+        blocking_reason: "none",
+        missing_approval: "none",
+        allowed: [
+          "run Brownfield Review after G-00",
+          "identify existing workstream, owners, SoT, reuse risks and open PRD/SD questions",
+          "mark Brownfield Review as done or not_applicable in AGDF_RUN.md",
+        ],
+        forbidden: ["create PRD before Brownfield Review is resolved", "create SD", "create TP", "implement code", "claim QA or release readiness"],
+        next_allowed_action: "Run Brownfield Review after G-00 before drafting PRD, or mark Brownfield Review not_applicable with evidence.",
+      };
+    }
+
+    const modeDecision = modeSliceDecision(runState);
+    if (modeDecision === "undecided") {
+      return {
+        status: "open",
+        current_gate: "Mode/Slice Decision",
+        blocking_reason: "none",
+        missing_approval: "none",
+        allowed: [
+          "decide whether the approved UR is quick_task, structured_slice, structured_delivery or block",
+          "record scope reason and evidence in AGDF_RUN.md",
+          "choose the next required gate depth before drafting PRD or implementing",
+        ],
+        forbidden: ["create PRD before process size is decided", "create SD", "create TP", "implement code", "claim QA or release readiness"],
+        next_allowed_action: "Record the Mode/Slice Decision from Brownfield Review before choosing PRD depth or Quick Task execution.",
+      };
+    }
+
+    if (modeDecision === "block") {
+      return {
+        status: "blocked",
+        current_gate: "Mode/Slice Decision",
+        blocking_reason: "mode_slice_decision_blocked",
+        missing_approval: "none",
+        allowed: ["resolve ownership, SoT, evidence, impact or product-direction uncertainty", "run gate-check again"],
+        forbidden: ["create PRD", "create SD", "create TP", "implement code", "claim QA or release readiness"],
+        next_allowed_action: "Resolve the Brownfield Review blocker before choosing a delivery path.",
+      };
+    }
+
+    if (modeDecision === "quick_task") {
+      return {
+        status: "open",
+        current_gate: "Quick Task Execution",
+        blocking_reason: "none",
+        missing_approval: "none",
+        allowed: ["implement the narrow approved UR scope", "run relevant checks", "record evidence and close with OR-lite"],
+        forbidden: ["expand scope beyond the Brownfield Review decision", "create broad PRD/SD/TP artefacts by ritual", "claim QA or release readiness without evidence"],
+        next_allowed_action: "Proceed as a Quick Task within the Brownfield Review scope and record verification evidence.",
+      };
+    }
+
+    return {
+      status: "open",
+      current_gate: "PRD",
+      blocking_reason: "none",
+      missing_approval: "Approval: PRD",
+      allowed: ["draft or refine PRD", "define scope", "define acceptance criteria", "define non-goals", "request exact PRD approval"],
+      forbidden: ["create SD", "create TP", "run Brownfield Analysis as implementation preparation", "implement code", "claim QA or release readiness"],
+      next_allowed_action: modeDecision === "structured_slice"
+        ? "Draft or refine the smallest PRD slice justified by Brownfield Review; do not implement before required artefacts are approved."
+        : "Draft or refine the PRD; do not implement before PRD, SD and TP are approved.",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "SD") === "approved" && !isGateSatisfied(runState, "SD")) return durableArtefactBlock("SD", "TP");
+
+  if (!isGateSatisfied(runState, "SD")) {
+    return {
+      status: "open",
+      current_gate: "SD",
+      blocking_reason: "none",
+      missing_approval: "Approval: SD",
+      allowed: ["draft or refine Solution Design", "define architecture", "define ownership", "request exact SD approval"],
+      forbidden: ["create TP", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Draft or refine the Solution Design; do not implement before SD and TP are approved.",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "TP") === "approved" && !isGateSatisfied(runState, "TP")) return durableArtefactBlock("TP", "Brownfield Analysis");
+
+  if (!isGateSatisfied(runState, "TP")) {
+    return {
+      status: "open",
+      current_gate: "TP",
+      blocking_reason: "none",
+      missing_approval: "Approval: TP",
+      allowed: ["draft or refine Task/Test Plan", "define task IDs", "define test evidence", "request exact TP approval"],
+      forbidden: ["implement code", "claim QA or release readiness"],
+      next_allowed_action: "Draft or refine the Task/Test Plan; do not implement before TP is approved.",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
+
+  return {
+    status: "open",
+    current_gate: "Brownfield Analysis",
+    blocking_reason: "none",
+    missing_approval: "none",
+    allowed: ["run Brownfield Analysis for the approved TP scope", "verify existing owners, reuse paths and regression risks"],
+    forbidden: ["implement before Brownfield evidence supports the approved TP path", "claim QA or release readiness"],
+    next_allowed_action: "Run Brownfield Analysis for the approved TP scope before CD+Tests.",
+  };
+}
+
 function evaluateGateCheck(targetDir) {
   const doctorReport = evaluateDoctor(targetDir);
   const runState = readRunState(targetDir);
-  const fallbackGate = firstUnapprovedGate(runState.approvals);
-  const currentGate = normalizeCurrentGate(runState.current_gate, fallbackGate);
-  const currentApprovalStatus = gateApprovalStatus(runState, currentGate);
+  const transitionDecision = transitionDecisionForRunState(runState);
+  const deliveryMap = analyzeDeliveryMap(runState);
   const doctorBlocker = doctorReport.findings.find((finding) => finding.severity === "block");
   const doctorRevise = doctorReport.findings.find((finding) => finding.severity === "revise");
 
-  let status = "open";
-  let blockingReason = "none";
-  let missingApproval = "none";
-  let allowed = [
-    "continue with the documented next allowed action",
-    "update evidence when new facts are observed",
-    "run doctor or gate-check again after control changes",
-  ];
-  let forbidden = [
-    "bypass the documented gate state",
-    "treat warnings as resolved without evidence",
-  ];
+  let status = transitionDecision.status;
+  let currentGate = transitionDecision.current_gate;
+  let blockingReason = transitionDecision.blocking_reason;
+  let missingApproval = transitionDecision.missing_approval;
+  let allowed = transitionDecision.allowed;
+  let forbidden = transitionDecision.forbidden;
   let nextAllowedAction = isPlaceholderValue(runState.next_allowed_action)
-    ? "Continue with the current documented gate only after setting next_allowed_action."
+    ? transitionDecision.next_allowed_action
     : runState.next_allowed_action;
 
   if (doctorBlocker) {
@@ -627,16 +1030,9 @@ function evaluateGateCheck(targetDir) {
   } else if (doctorRevise) {
     status = "blocked";
     blockingReason = doctorRevise.code;
-    allowed = ["repair the incomplete control state", "run doctor again"];
+    allowed = [...new Set(["repair the incomplete control state", ...transitionDecision.allowed, "run doctor again"])];
     forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
     nextAllowedAction = doctorRevise.next_step;
-  } else if (userGateOrder.includes(currentGate) && currentApprovalStatus !== "approved" && currentApprovalStatus !== "not_applicable") {
-    status = "blocked";
-    blockingReason = "missing_exact_approval";
-    missingApproval = `Approval: ${currentGate}`;
-    allowed = ["clarify the current gate", "record evidence", "write OR-lite status", "request exact approval"];
-    forbidden = ["create later-gate artefacts", "implement gated work", "mark QA or UAT as passed"];
-    nextAllowedAction = `Request exact approval: Approval: ${currentGate}`;
   }
 
   return {
@@ -651,6 +1047,12 @@ function evaluateGateCheck(targetDir) {
     doctor_status: doctorReport.status,
     doctor_summary: doctorReport.summary,
     evidence_refs: runState.evidence_refs,
+    delivery_map: {
+      relationships: deliveryMap.relationships,
+      mode_slice_decision: runState.mode_slice_decision,
+      context_graph: deliveryMap.context_graph,
+      findings: deliveryMap.findings,
+    },
     doctor_report: doctorReport,
   };
 }
@@ -676,6 +1078,84 @@ function printGateCheckReport(report, json) {
   console.log(`Next allowed action: ${report.next_allowed_action}`);
 }
 
+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 nonTemplateRows(activeSection, "Prio")
+    .map((cells) => ({
+      prio: cells[0] ?? "",
+      key: cells[1] ?? "",
+      title: cells[2] ?? "",
+      status: cleanStatusCell(cells[3] ?? ""),
+      ur: cells[4] ?? "",
+      prd: cells[5] ?? "",
+      sd: cells[6] ?? "",
+      tp: cells[7] ?? "",
+      qa: cells[8] ?? "",
+      or: cells[9] ?? "",
+      current_spec: cells[10] ?? "",
+      notes: cells[11] ?? "",
+    }));
+}
+
+function evaluateDeliveryMap(targetDir) {
+  const doctorReport = evaluateDoctor(targetDir);
+  const runState = readRunState(targetDir);
+  const map = analyzeDeliveryMap(runState);
+  const gateDecision = transitionDecisionForRunState(runState);
+
+  const severityRank = { block: 3, revise: 2, warn: 1 };
+  const deliverySeverity = map.findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
+  const doctorSeverity = severityRank[doctorReport.status] ?? 0;
+  const maxSeverity = Math.max(deliverySeverity, doctorSeverity);
+  const status = maxSeverity >= 3 ? "block" : maxSeverity === 2 ? "revise" : maxSeverity === 1 ? "warn" : "pass";
+
+  return {
+    schema_version: "1",
+    status,
+    checked_at: new Date().toISOString(),
+    target_dir: targetDir,
+    current_gate: gateDecision.current_gate,
+    next_allowed_action: isPlaceholderValue(runState.next_allowed_action) ? gateDecision.next_allowed_action : runState.next_allowed_action,
+    backlog_pointers: readBacklogPointers(targetDir),
+    artefacts: Object.fromEntries([...runState.artefacts.entries()]),
+    approvals: Object.fromEntries([...runState.approvals.entries()]),
+    mode_slice_decision: runState.mode_slice_decision,
+    relationships: map.relationships,
+    evidence_refs: runState.evidence_refs,
+    missing_evidence: map.missing_evidence,
+    risks: map.risks,
+    context_graph: map.context_graph,
+    findings: map.findings,
+    doctor_status: doctorReport.status,
+    doctor_summary: doctorReport.summary,
+    doctor_report: doctorReport,
+  };
+}
+
+function printDeliveryMapReport(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log(`AGDF delivery-map: ${report.status}`);
+  console.log(`Current gate: ${report.current_gate}`);
+  console.log(`Next allowed action: ${report.next_allowed_action}`);
+  console.log(`Relationships: ${report.relationships.filter((item) => item.status === "pass").length}/${report.relationships.length} evidenced`);
+  console.log(`Findings: ${report.findings.length}`);
+
+  for (const finding of report.findings) {
+    console.log("");
+    console.log(`[${finding.severity}] ${finding.code}`);
+    console.log(finding.message);
+    console.log(`Next step: ${finding.next_step}`);
+  }
+}
+
 function main() {
   const options = parseArgs(process.argv.slice(2));
 
@@ -691,6 +1171,12 @@ function main() {
     process.exit(report.status === "blocked" ? 2 : 0);
   }
 
+  if (options.target === "delivery-map") {
+    const report = evaluateDeliveryMap(options.dir);
+    printDeliveryMapReport(report, options.json);
+    process.exit(report.status === "block" ? 2 : 0);
+  }
+
   const files = generatedFilesForTarget(options.target, options.dir, options.force);
   const wroteAgentsFragment = files.some(file => file.path === agdfFragmentPath);