create-agdf 0.3.4 → 0.4.0

package/bin/create-agdf.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
 
@@ -10,8 +12,8 @@ const packageRoot = resolve(__dirname, "..");
 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", "opencode", "both", "init", "config", "doctor", "gate-check", "delivery-map"]);
+const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
+const allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 const openCodeConfigFragmentPath = "opencode.agdf.json";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
@@ -24,6 +26,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}`);
@@ -126,15 +158,21 @@ function printUsage() {
 
 Preferred AGDF CLI:
   npx --yes @agdf/cli@latest codex
+  npx --yes @agdf/cli@latest codex-repo
+  npx --yes @agdf/cli@latest claude
   npx --yes @agdf/cli@latest opencode
+  npx --yes @agdf/cli@latest opencode-repo
   npx --yes @agdf/cli@latest init
   npx --yes @agdf/cli@latest doctor
   npx --yes @agdf/cli@latest gate-check --json
 
 Scaffold-compatible npm create usage:
   npm create agdf@latest -- codex
+  npm create agdf@latest -- codex-repo
+  npm create agdf@latest -- claude
   npm create agdf@latest -- copilot
   npm create agdf@latest -- opencode
+  npm create agdf@latest -- opencode-repo
   npm create agdf@latest -- both
   npm create agdf@latest -- init
   npm create agdf@latest -- config --language de
@@ -147,7 +185,7 @@ Backward-compatible create-agdf usage:
   npx --yes create-agdf@latest gate-check --json
 
 Options:
-  --dir <path>   Write files into a specific directory
+  --dir <path>   Write files into a specific directory. With opencode, use this as the OpenCode config directory.
   --force        Overwrite existing generated files
   --language <de|en>
                  Set AGDF chat and artefact language. Defaults to detected system locale.
@@ -215,6 +253,7 @@ function parseArgs(argv) {
   let force = false;
   let json = false;
   let language;
+  let dirExplicit = false;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -258,6 +297,7 @@ function parseArgs(argv) {
         process.exit(1);
       }
       dir = next;
+      dirExplicit = true;
       i += 1;
       continue;
     }
@@ -283,7 +323,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot, opencode, both, init, config, doctor, gate-check or delivery-map.");
+    console.error("Please choose one target: codex, codex-repo, claude, copilot, opencode, opencode-repo, both, init, config, doctor, gate-check or delivery-map.");
     printUsage();
     process.exit(1);
   }
@@ -293,10 +333,69 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    dirExplicit,
     language: resolveLanguagePreference(language),
   };
 }
 
+function defaultOpenCodeConfigDir() {
+  return process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode");
+}
+
+function installOpenCodeGlobalPlugin(configDir) {
+  const configPath = join(configDir, "opencode.json");
+  let config = {};
+
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(`Refusing to update unreadable OpenCode config: ${configPath}`);
+    }
+  }
+
+  if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+    throw new Error(`Refusing to update OpenCode config with non-array plugin field: ${configPath}`);
+  }
+
+  const plugins = [...(config.plugin ?? [])];
+  const alreadyInstalled = plugins.includes(pluginDefinition.opencode.npmPackage);
+  if (!alreadyInstalled) {
+    plugins.push(pluginDefinition.opencode.npmPackage);
+  }
+
+  const nextConfig = {
+    "$schema": config.$schema ?? "https://opencode.ai/config.json",
+    ...config,
+    plugin: plugins,
+  };
+
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+
+  return {
+    configPath,
+    added: !alreadyInstalled,
+  };
+}
+
+function installCodexGlobalPlugin() {
+  try {
+    execFileSync("codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
+    execFileSync("codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], { stdio: "inherit" });
+  } catch (error) {
+    throw new Error("Failed to install the AGDF Codex plugin. Make sure the Codex CLI is installed and available on PATH, then rerun this command.");
+  }
+}
+
+function installClaudeGlobalPlugin() {
+  try {
+    execFileSync("claude", ["plugin", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
+  } catch {
+    throw new Error("Failed to install the AGDF Claude Code plugin. Make sure the Claude Code CLI is installed and available on PATH, then rerun this command.");
+  }
+}
+
 function loadAsset(relativePath) {
   return readFileSync(join(generatedRoot, relativePath), "utf8");
 }
@@ -355,7 +454,7 @@ function generatedFilesForTarget(target, targetDir, force, languagePreference) {
     return files;
   }
 
-  if (target === "codex" || target === "both") {
+  if (target === "codex-repo" || target === "both") {
     addLanguageConfig(files, languagePreference);
     for (const codexPath of codexPluginFiles) {
       files.push({
@@ -395,7 +494,7 @@ function generatedFilesForTarget(target, targetDir, force, languagePreference) {
     }
   }
 
-  if (target === "opencode") {
+  if (target === "opencode-repo") {
     addLanguageConfig(files, languagePreference);
     const openCodeConfigTargetPath = existsSync(join(targetDir, "opencode.json")) && !force ? openCodeConfigFragmentPath : "opencode.json";
     files.push({
@@ -451,20 +550,23 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
   if (wroteAgentsFragment) {
     console.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
   }
-  if (target === "codex" || target === "both") {
+  if (target === "codex-repo" || target === "both") {
     console.log("- Restart Codex in this repository, open /plugins, select This repository and install agdf.");
     console.log("- Start a new Codex thread in this repository and ask: Run an AGDF gate check for this request.");
   }
   if (target === "both") {
     console.log(`- Optional global Claude Code install: ${pluginInstallCommand}`);
   }
-  if (target === "opencode") {
+  if (target === "opencode-repo") {
     if (wroteOpenCodeConfigFragment) {
       console.log(`- Existing opencode.json detected. Merge ${openCodeConfigFragmentPath} into your current opencode.json so OpenCode loads .opencode/AGDF.md.`);
     }
     console.log(`- OpenCode will install the ${pluginDefinition.opencode.npmPackage} npm plugin from opencode.json at startup.`);
+    console.log("- Optional: also add create-agdf to ~/.config/opencode/opencode.json plugin[] for a user-wide OpenCode hook.");
+    console.log("- The global hook does not replace repository instructions or subagents; this repository's .opencode files remain the AGDF source of truth.");
     console.log("- Start OpenCode in this repository; it will load opencode.json, .opencode/AGDF.md and the AGDF subagents.");
-    console.log("- Use @agdf-gate-check for new build/change intent or unclear approval before later artefacts or implementation.");
+    console.log("- AGDF OpenCode agents are mode: subagent workflow controls; they are not .opencode/skills entries or primary menu agents.");
+    console.log("- Use @agdf-gate-check as the visible entry point for new build/change intent or unclear approval before later artefacts or implementation.");
     console.log("- Run npx --yes @agdf/cli@latest init when the repository needs live AGDF control files.");
   }
   if (target === "copilot" || target === "both") {
@@ -510,6 +612,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 +937,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 +1070,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 +1103,9 @@ function readRunState(targetDir) {
       missing_evidence: [],
       risks: [],
       context_graph: {},
+      quality_outlook: "",
+      source_scope: {},
+      memory: {},
     };
   }
 
@@ -846,6 +1178,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 +1208,9 @@ function readRunState(targetDir) {
     missing_evidence: missingEvidence,
     risks,
     context_graph: contextGraph,
+    quality_outlook: extractField(content, "quality_outlook"),
+    source_scope: sourceScope,
+    memory,
   };
 }
 
@@ -890,7 +1242,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 +1349,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 +1464,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 +1586,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 +1630,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 +1679,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 +1713,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 +1731,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 +1739,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 +1747,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 +1778,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 +1796,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}`);
 
@@ -1351,6 +1829,42 @@ function main() {
     process.exit(report.status === "block" ? 2 : 0);
   }
 
+  if (options.target === "codex") {
+    try {
+      installCodexGlobalPlugin();
+      console.log("AGDF Codex plugin installed globally.");
+      console.log("Run npx --yes @agdf/cli@latest codex-repo in a repository when you want to test AGDF from repository-local plugin files.");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (options.target === "claude") {
+    try {
+      installClaudeGlobalPlugin();
+      console.log("AGDF Claude Code plugin installed globally.");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (options.target === "opencode") {
+    const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
+    try {
+      const result = installOpenCodeGlobalPlugin(configDir);
+      console.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
+      console.log("Run npx --yes @agdf/cli@latest opencode-repo in each repository where AGDF governance should be active and reviewable.");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
   const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
   const wroteAgentsFragment = files.some(file => file.path === agdfFragmentPath);
   const wroteOpenCodeConfigFragment = files.some(file => file.path === openCodeConfigFragmentPath);