create-agdf 0.3.2 → 0.3.5

package/README.md

@@ -117,6 +117,8 @@ npx --yes create-agdf@latest gate-check --json
 
 The gate check reports `open | blocked`, the current gate, blocking reason, missing exact approval, allowed outputs, forbidden outputs, next allowed action, evidence references and the embedded doctor report.
 
+`gate-check --json` and `delivery-map --json` also expose a `status_card` object. It is a compact projection of the current control state: current gate, allowed and forbidden actions, blocker, next skill, next permissible step and `quality_outlook`. `next_step` is process permission; `quality_outlook` is the next meaningful quality-improvement focus and does not unlock gates.
+
 Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction layer into a repository control system when durable control state is needed. For normal fresh requests, the agent-native path can stay lighter: draft the minimal UR in the response, request `Approval: UR`, and use CLI validators only when machine-readable proof is useful.
 
 ## Single source of truth
@@ -147,15 +149,8 @@ The routing test installs `both` into a temporary target repository and checks t
 
 ## Publishing
 
-The repository publishes this package from `create-agdf/` via the GitHub Actions workflow `.github/workflows/publish-create-agdf.yml`.
-
-The primary user-facing CLI package is published separately from `agdf/` and delegates to this package through the shared `create-agdf/cli` export.
-
-- From the repository root, run `npm run set-version -- <version>`
-- The version script updates the coupled package, plugin and site versions and refuses versions already published as `create-agdf` or `@agdf/cli`
-- Push a matching git tag in the form `create-agdf-v<version>`
-- After `create-agdf` is published, push `agdf-cli-v<version>` for the primary CLI package
-- Ensure the repository secret `NPM_TOKEN` exists with publish rights for `create-agdf`
+The repository publishes this package and the primary user-facing `@agdf/cli` wrapper as one coupled AGDF release.
+See the root `RELEASE.md` for the sequenced `agdf-v<version>` workflow and npm token requirements.
 
 ## Trademark Notice
 

package/bin/create-agdf.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
 
@@ -24,6 +24,36 @@ const deliveryRelationships = [
   { from: "TP", relationship: "derived_from", to: "SD", requiredBy: "TP" },
   { from: "QA_REPORT", relationship: "tests", to: "TP", requiredBy: "QA" },
 ];
+const nextSkillByGate = {
+  UR: "gate-check",
+  "Brownfield Review": "brownfield-analysis",
+  "Mode/Slice Decision": "gate-check",
+  "Quick Task Execution": "none",
+  PRD: "gate-check",
+  SD: "gate-check",
+  TP: "gate-check",
+  "Brownfield Analysis": "brownfield-analysis",
+  "CD+Tests": "none",
+  CR: "code-review",
+  QA: "qa-gate",
+  UAT: "delivery-closeout",
+  OR: "release-or",
+};
+const gateProgressOrder = [
+  "UR",
+  "Brownfield Review",
+  "Mode/Slice Decision",
+  "Quick Task Execution",
+  "PRD",
+  "SD",
+  "TP",
+  "Brownfield Analysis",
+  "CD+Tests",
+  "CR",
+  "QA",
+  "UAT",
+  "OR",
+];
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.skillPrefix}${skill.slug}`);
@@ -510,6 +540,222 @@ function tableRows(content) {
     });
 }
 
+const compactBacklogHeaders = ["priority", "key", "work item", "status", "artefacts", "current spec", "next step"];
+const legacyBacklogHeaders = ["prio", "key", "title", "status", "ur", "brownfield review", "prd", "sd", "tp", "qa", "or", "current spec", "notes"];
+const backlogStatusLabels = new Map([
+  ["needs ur", "needs_ur"],
+  ["awaiting brownfield review", "awaiting_brownfield_review"],
+  ["awaiting prd", "awaiting_prd"],
+  ["awaiting prd approval", "awaiting_prd_approval"],
+  ["awaiting sd", "awaiting_sd"],
+  ["awaiting sd approval", "awaiting_sd_approval"],
+  ["awaiting tp", "awaiting_tp"],
+  ["awaiting tp approval", "awaiting_tp_approval"],
+  ["in progress", "in_progress"],
+  ["blocked", "blocked"],
+  ["awaiting qa", "awaiting_qa"],
+  ["awaiting uat", "awaiting_uat"],
+  ["completed", "completed"],
+  ["superseded", "superseded"],
+  ["abandoned", "abandoned"],
+]);
+const backlogArtefactLabels = new Map([
+  ["ur", "ur"],
+  ["brownfield", "brownfield_review"],
+  ["prd", "prd"],
+  ["sd", "sd"],
+  ["tp", "tp"],
+  ["qa", "qa"],
+  ["or", "or"],
+]);
+
+function normalizeBacklogHeader(value) {
+  return value.replace(/`/g, "").trim().toLowerCase();
+}
+
+function markdownLink(value) {
+  const match = value.trim().match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+  return match ? { label: match[1].trim(), target: match[2].trim() } : null;
+}
+
+function resolvedBacklogLinkTarget(target) {
+  if (!target
+    || target.startsWith("/")
+    || target.includes("\\")
+    || /^[a-z][a-z0-9+.-]*:/i.test(target)) {
+    return null;
+  }
+  const resolved = posix.normalize(posix.join(".agdf/control", target));
+  if (resolved === ".." || resolved.startsWith("../")) return null;
+  return resolved;
+}
+
+function normalizedBacklogLinkTarget(value, findings, backlogPath, label) {
+  const link = markdownLink(value);
+  if (!link) return value.trim();
+  const resolved = resolvedBacklogLinkTarget(link.target);
+  if (!resolved) {
+    if (findings) {
+      addFinding(
+        findings,
+        "revise",
+        "AGDF_BACKLOG_LINK_TARGET_INVALID",
+        `Backlog ${label} link must be relative to MASTER_BACKLOG.md: ${link.target || "<empty>"}.`,
+        backlogPath,
+        "Use a document-relative artefact target such as artefacts/<key>/UR.md.",
+      );
+    }
+    return link.target;
+  }
+  return resolved;
+}
+
+function normalizeBacklogStatus(value, findings, backlogPath) {
+  const cleaned = cleanStatusCell(value ?? "");
+  const lookup = cleaned.replaceAll("_", " ").toLowerCase();
+  const normalized = backlogStatusLabels.get(lookup);
+  if (normalized) return normalized;
+  if (/^[a-z][a-z0-9_]*$/.test(cleaned)) return cleaned;
+  if (findings && filled(cleaned)) {
+    addFinding(
+      findings,
+      "revise",
+      "AGDF_BACKLOG_STATUS_UNKNOWN",
+      `MASTER_BACKLOG.md uses an unknown human status label: ${cleaned}.`,
+      backlogPath,
+      "Use a documented human status label or a supported legacy snake_case value.",
+    );
+  }
+  return cleaned;
+}
+
+function emptyBacklogPointer() {
+  return {
+    prio: "",
+    key: "",
+    title: "",
+    status: "",
+    ur: "",
+    brownfield_review: "",
+    prd: "",
+    sd: "",
+    tp: "",
+    qa: "",
+    or: "",
+    current_spec: "",
+    notes: "",
+  };
+}
+
+function parseCompactArtefacts(value, pointer, findings, backlogPath) {
+  if (!filled(value)) return;
+  const seen = new Set();
+  for (const entry of value.split(/\s+·\s+/)) {
+    const link = markdownLink(entry);
+    if (!link) {
+      if (findings) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_BACKLOG_ARTEFACT_LINK_INVALID",
+          `Compact Artefacts entry is not a Markdown link: ${entry}.`,
+          backlogPath,
+          "Use [UR](artefacts/<key>/UR.md) style links separated by a middle dot.",
+        );
+      }
+      continue;
+    }
+    const field = backlogArtefactLabels.get(link.label.toLowerCase());
+    if (!field) {
+      if (findings) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN",
+          `Compact Artefacts uses an unknown label: ${link.label}.`,
+          backlogPath,
+          "Use UR, Brownfield, PRD, SD, TP, QA or OR.",
+        );
+      }
+      continue;
+    }
+    if (seen.has(field)) {
+      if (findings) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_BACKLOG_ARTEFACT_LABEL_DUPLICATE",
+          `Compact Artefacts repeats the ${link.label} link.`,
+          backlogPath,
+          "Keep exactly one link per artefact type.",
+        );
+      }
+      continue;
+    }
+    seen.add(field);
+    pointer[field] = normalizedBacklogLinkTarget(entry, findings, backlogPath, link.label);
+  }
+}
+
+function parseBacklogSection(section, findings = null, backlogPath = ".agdf/control/MASTER_BACKLOG.md") {
+  const rows = tableRows(section);
+  if (rows.length === 0) return [];
+  const headers = rows[0].map(normalizeBacklogHeader);
+  const layout = headers.join("|") === compactBacklogHeaders.join("|")
+    ? "compact"
+    : headers.join("|") === legacyBacklogHeaders.join("|")
+      ? "legacy"
+      : "unknown";
+
+  if (layout === "unknown") {
+    if (findings) {
+      addFinding(
+        findings,
+        "revise",
+        "AGDF_BACKLOG_LAYOUT_UNKNOWN",
+        `MASTER_BACKLOG.md uses an unsupported table layout: ${headers.join(", ")}.`,
+        backlogPath,
+        "Use the canonical compact layout or the supported legacy 13-column layout.",
+      );
+    }
+    return [];
+  }
+
+  return rows.slice(1)
+    .filter((cells) => cells.some((cell) => filled(cell)))
+    .map((cells) => {
+      const pointer = emptyBacklogPointer();
+      if (layout === "legacy") {
+        [
+          pointer.prio,
+          pointer.key,
+          pointer.title,
+          pointer.status,
+          pointer.ur,
+          pointer.brownfield_review,
+          pointer.prd,
+          pointer.sd,
+          pointer.tp,
+          pointer.qa,
+          pointer.or,
+          pointer.current_spec,
+          pointer.notes,
+        ] = cells.map((cell) => cell ?? "");
+        pointer.status = normalizeBacklogStatus(pointer.status, findings, backlogPath);
+        return pointer;
+      }
+
+      pointer.prio = cells[0] ?? "";
+      pointer.key = cleanStatusCell(cells[1] ?? "");
+      pointer.title = cells[2] ?? "";
+      pointer.status = normalizeBacklogStatus(cells[3], findings, backlogPath);
+      parseCompactArtefacts(cells[4] ?? "", pointer, findings, backlogPath);
+      pointer.current_spec = normalizedBacklogLinkTarget(cells[5] ?? "", findings, backlogPath, "Current spec");
+      pointer.notes = cells[6] ?? "";
+      return pointer;
+    });
+}
+
 function hasFilledTableRow(content, firstCellPattern) {
   return tableRows(content)
     .filter((cells) => firstCellPattern.test(cells[0] ?? ""))
@@ -619,7 +865,12 @@ function evaluateDoctor(targetDir) {
 
     const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");
     const backlog = readTargetFile(targetDir, backlogPath);
-    if (!hasFilledTableRow(backlog, /^P[0-9]/)) {
+    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)));
+    if (!hasFilledTableRow(backlog, /^P[0-9]/) && completedRows.length === 0) {
       addFinding(
         findings,
         "warn",
@@ -747,12 +998,18 @@ function cleanStatusCell(value) {
   return value.replace(/^`|`$/g, "").trim();
 }
 
+function normalizeGateStatus(gate, status) {
+  const normalized = cleanStatusCell(status ?? "");
+  if (gate === "QA" && normalized === "passed") return "approved";
+  return normalized;
+}
+
 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 ?? ""),
+      status: normalizeGateStatus(gate, status),
       evidence: evidence ?? "",
     });
   }
@@ -774,6 +1031,9 @@ function readRunState(targetDir) {
       missing_evidence: [],
       risks: [],
       context_graph: {},
+      quality_outlook: "",
+      source_scope: {},
+      memory: {},
     };
   }
 
@@ -846,6 +1106,23 @@ function readRunState(targetDir) {
     evidence: extractSectionField(modeSliceSection, "evidence"),
   };
 
+  const sourceScopeSection = markdownSection(content, "Source And Scope State");
+  const sourceScope = {
+    normative_instruction_source: extractSectionField(sourceScopeSection, "normative_instruction_source"),
+    multi_scope_state: cleanStatusCell(extractSectionField(sourceScopeSection, "multi_scope_state")),
+    active_scope_evidence: extractSectionField(sourceScopeSection, "active_scope_evidence"),
+    competing_scope_lines: extractSectionField(sourceScopeSection, "competing_scope_lines"),
+    branch_workspace_evidence: extractSectionField(sourceScopeSection, "branch_workspace_evidence"),
+    branch_workspace_scope_effect: cleanStatusCell(extractSectionField(sourceScopeSection, "branch_workspace_scope_effect")),
+  };
+
+  const memorySection = markdownSection(content, "Knowledge Persistence Decision");
+  const memory = {
+    target: cleanStatusCell(extractSectionField(memorySection, "memory_target")),
+    reason: extractSectionField(memorySection, "memory_reason"),
+    refs: extractSectionField(memorySection, "memory_refs"),
+  };
+
   return {
     path: runPath,
     content,
@@ -859,6 +1136,9 @@ function readRunState(targetDir) {
     missing_evidence: missingEvidence,
     risks,
     context_graph: contextGraph,
+    quality_outlook: extractField(content, "quality_outlook"),
+    source_scope: sourceScope,
+    memory,
   };
 }
 
@@ -890,7 +1170,7 @@ 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";
+  if (gate === "QA") return artefact.status === "pass" || artefact.status === "passed";
   return artefact.status === "approved";
 }
 
@@ -997,15 +1277,97 @@ function analyzeDeliveryMap(runState) {
     });
   }
 
+  const multiScopeState = runState.source_scope?.multi_scope_state;
+  if (multiScopeState === "ambiguous" || multiScopeState === "blocked") {
+    findings.push({
+      severity: multiScopeState === "blocked" ? "block" : "revise",
+      code: "AGDF_SCOPE_AMBIGUOUS",
+      message: "Multiple active scope lines are plausible; the agent must not choose one silently.",
+      path: runState.path,
+      next_step: "List competing scope lines with gate and artefact evidence, then clarify the active scope.",
+    });
+  }
+
+  const branchEffect = runState.source_scope?.branch_workspace_scope_effect;
+  if (branchEffect === "conflicts" || branchEffect === "insufficient") {
+    findings.push({
+      severity: branchEffect === "conflicts" ? "revise" : "warn",
+      code: "AGDF_BRANCH_NOT_SCOPE_PROOF",
+      message: "Branch or workspace evidence is not sufficient scope proof.",
+      path: runState.path,
+      next_step: "Confirm the active scope from durable artefacts or record why branch/workspace evidence is only supporting evidence.",
+    });
+  }
+
+  if (runState.memory?.target && runState.memory.target !== "none" && !filled(runState.memory.reason)) {
+    findings.push({
+      severity: "warn",
+      code: "AGDF_MEMORY_TARGET_REASON_MISSING",
+      message: "Knowledge persistence target is set without a reason.",
+      path: runState.path,
+      next_step: "Fill memory_reason or set memory_target to none.",
+    });
+  }
+
   return {
     relationships,
     missing_evidence: runState.missing_evidence,
     risks: runState.risks,
     context_graph: runState.context_graph,
+    source_scope: runState.source_scope,
+    memory: runState.memory,
     findings,
   };
 }
 
+function deriveQualityOutlook(runState, findings = []) {
+  if (filled(runState.quality_outlook)) return runState.quality_outlook;
+  if (findings.some((finding) => finding.severity === "block" || finding.severity === "revise")) {
+    return "Resolve blocking or revise-level delivery-map findings before making stronger quality claims.";
+  }
+  if (findings.some((finding) => finding.severity === "warn")) {
+    return "Review warning-level findings when investing further in delivery confidence.";
+  }
+  return "No additional quality follow-up identified from the current control state.";
+}
+
+function buildStatusCard({
+  status,
+  currentGate,
+  allowed = [],
+  forbidden = [],
+  blockingReason = "none",
+  missingApproval = "none",
+  nextAllowedAction,
+  runState,
+  findings = [],
+}) {
+  const qualityOutlook = deriveQualityOutlook(runState, findings);
+  return {
+    mode: extractField(runState.content ?? "", "mode") || "unknown",
+    status,
+    current_gate: currentGate,
+    mode_slice_decision: runState.mode_slice_decision?.decision || "undecided",
+    allowed_now: allowed,
+    forbidden_now: forbidden,
+    blocking_condition: blockingReason || "none",
+    missing_approval: missingApproval || "none",
+    evidence: runState.evidence_refs,
+    next_skill: nextSkillByGate[currentGate] ?? "gate-check",
+    next_step: nextAllowedAction,
+    quality_outlook: qualityOutlook,
+  };
+}
+
+function effectiveCurrentGate(runState, transitionDecision) {
+  if (transitionDecision.status !== "open") return transitionDecision.current_gate;
+  const explicitGate = normalizeCurrentGate(runState.current_gate, "");
+  const explicitIndex = gateProgressOrder.indexOf(explicitGate);
+  const fallbackIndex = gateProgressOrder.indexOf(transitionDecision.current_gate);
+  if (explicitIndex === -1 || fallbackIndex === -1) return transitionDecision.current_gate;
+  return explicitIndex > fallbackIndex ? explicitGate : transitionDecision.current_gate;
+}
+
 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`;
@@ -1030,6 +1392,7 @@ function isGateSatisfied(runState, gate) {
   const status = gateApprovalStatus(runState, gate);
   if (status === "not_applicable") return true;
   if (status !== "approved") return false;
+  if (gate === "UAT") return true;
   return isDurableGateArtefactSatisfied(runState, gate);
 }
 
@@ -1151,6 +1514,30 @@ function transitionDecisionForRunState(runState) {
 
   if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
 
+  if (isGateSatisfied(runState, "QA") && !isGateSatisfied(runState, "UAT")) {
+    return {
+      status: "open",
+      current_gate: "UAT",
+      blocking_reason: "none",
+      missing_approval: "Approval: UAT",
+      allowed: ["request exact UAT approval", "prepare non-operative delivery summary"],
+      forbidden: ["release", "push", "open PR", "commit without explicit user instruction and required approval"],
+      next_allowed_action: "Request exact approval: Approval: UAT before delivery handoff.",
+    };
+  }
+
+  if (isGateSatisfied(runState, "UAT")) {
+    return {
+      status: "open",
+      current_gate: "OR",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["produce OR or delivery closeout", "prepare commit, push or PR handoff when requested"],
+      forbidden: ["commit, push, open PR or release automatically"],
+      next_allowed_action: "Produce delivery closeout or requested handoff; do not perform VCS actions automatically.",
+    };
+  }
+
   return {
     status: "open",
     current_gate: "Brownfield Analysis",
@@ -1171,7 +1558,7 @@ function evaluateGateCheck(targetDir) {
   const doctorRevise = doctorReport.findings.find((finding) => finding.severity === "revise");
 
   let status = transitionDecision.status;
-  let currentGate = transitionDecision.current_gate;
+  let currentGate = effectiveCurrentGate(runState, transitionDecision);
   let blockingReason = transitionDecision.blocking_reason;
   let missingApproval = transitionDecision.missing_approval;
   let allowed = transitionDecision.allowed;
@@ -1220,10 +1607,24 @@ function evaluateGateCheck(targetDir) {
     doctor_status: doctorReport.status,
     doctor_summary: doctorReport.summary,
     evidence_refs: runState.evidence_refs,
+    quality_outlook: deriveQualityOutlook(runState, deliveryMap.findings),
+    status_card: buildStatusCard({
+      status,
+      currentGate,
+      allowed,
+      forbidden,
+      blockingReason,
+      missingApproval,
+      nextAllowedAction,
+      runState,
+      findings: deliveryMap.findings,
+    }),
     delivery_map: {
       relationships: deliveryMap.relationships,
       mode_slice_decision: runState.mode_slice_decision,
       context_graph: deliveryMap.context_graph,
+      source_scope: deliveryMap.source_scope,
+      memory: deliveryMap.memory,
       findings: deliveryMap.findings,
     },
     doctor_report: doctorReport,
@@ -1240,6 +1641,7 @@ function printGateCheckReport(report, json) {
   console.log(`Current gate: ${report.current_gate}`);
   console.log(`Blocking reason: ${report.blocking_reason}`);
   console.log(`Missing approval: ${report.missing_approval}`);
+  console.log(`Quality outlook: ${report.quality_outlook}`);
   console.log(`Doctor: ${report.doctor_status} (${report.doctor_summary.findings} findings)`);
   console.log("");
   console.log("Allowed:");
@@ -1257,22 +1659,7 @@ function readBacklogPointers(targetDir) {
 
   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] ?? "",
-      brownfield_review: cells[5] ?? "",
-      prd: cells[6] ?? "",
-      sd: cells[7] ?? "",
-      tp: cells[8] ?? "",
-      qa: cells[9] ?? "",
-      or: cells[10] ?? "",
-      current_spec: cells[11] ?? "",
-      notes: cells[12] ?? "",
-    }));
+  return parseBacklogSection(activeSection);
 }
 
 function evaluateDeliveryMap(targetDir) {
@@ -1280,6 +1667,7 @@ function evaluateDeliveryMap(targetDir) {
   const runState = readRunState(targetDir);
   const map = analyzeDeliveryMap(runState);
   const gateDecision = transitionDecisionForRunState(runState);
+  const currentGate = effectiveCurrentGate(runState, gateDecision);
 
   const severityRank = { block: 3, revise: 2, warn: 1 };
   const deliverySeverity = map.findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
@@ -1287,13 +1675,28 @@ function evaluateDeliveryMap(targetDir) {
   const maxSeverity = Math.max(deliverySeverity, doctorSeverity);
   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;
+
   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,
+    current_gate: currentGate,
+    next_allowed_action: nextAllowedAction,
+    quality_outlook: qualityOutlook,
+    status_card: buildStatusCard({
+      status,
+      currentGate,
+      allowed: gateDecision.allowed,
+      forbidden: gateDecision.forbidden,
+      blockingReason: gateDecision.blocking_reason,
+      missingApproval: gateDecision.missing_approval,
+      nextAllowedAction,
+      runState,
+      findings: map.findings,
+    }),
     backlog_pointers: readBacklogPointers(targetDir),
     artefacts: Object.fromEntries([...runState.artefacts.entries()]),
     approvals: Object.fromEntries([...runState.approvals.entries()]),
@@ -1303,6 +1706,8 @@ function evaluateDeliveryMap(targetDir) {
     missing_evidence: map.missing_evidence,
     risks: map.risks,
     context_graph: map.context_graph,
+    source_scope: map.source_scope,
+    memory: map.memory,
     findings: map.findings,
     doctor_status: doctorReport.status,
     doctor_summary: doctorReport.summary,
@@ -1319,6 +1724,7 @@ function printDeliveryMapReport(report, json) {
   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(`Quality outlook: ${report.quality_outlook}`);
   console.log(`Relationships: ${report.relationships.filter((item) => item.status === "pass").length}/${report.relationships.length} evidenced`);
   console.log(`Findings: ${report.findings.length}`);
 

package/generated/.agdf/control/templates/AGDF_RUN.md

@@ -23,6 +23,29 @@ What outcome is this run trying to make trustworthy?
 | What is the next allowed action? |  |
 | What is explicitly forbidden right now? |  |
 
+## Source And Scope State
+
+- normative_instruction_source:
+- multi_scope_state: `clear | ambiguous | blocked`
+- active_scope_evidence:
+- competing_scope_lines:
+- branch_workspace_evidence:
+- branch_workspace_scope_effect: `supports | conflicts | insufficient | not_checked`
+
+## Run Status Card
+
+This is a compact projection of the control state. It does not replace gate-check, QA, OR or approvals.
+
+| Run status | Value |
+|---|---|
+| Status |  |
+| Current gate |  |
+| Allowed now |  |
+| Blocked by |  |
+| Missing approval |  |
+| Next step |  |
+| Quality outlook |  |
+
 ## Approvals
 
 Valid approval format for new runs: `Approval: <GateName>`.
@@ -98,6 +121,12 @@ Keep the active work item traceable. A gate may open only when the previous gate
 - context_graph_gate_effect: `none | warning | revise | block`
 - context_graph_evidence:
 
+## Knowledge Persistence Decision
+
+- memory_target: `context_graph | sot_registry | scope_artifact | open_questions | none`
+- memory_reason:
+- memory_refs:
+
 ## Closeout
 
 - delivered: