create-agdf 0.2.3 → 0.2.5

package/bin/create-agdf.js

@@ -11,10 +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 = [
@@ -27,10 +35,12 @@ const codexPluginFiles = [
   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", "BROWNFIELD_REVIEW.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"),
@@ -48,10 +58,12 @@ const controlFiles = [
   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", "BROWNFIELD_REVIEW.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 = [
   {
@@ -77,10 +89,12 @@ const liveControlFiles = [
 ];
 const artefactTemplateFiles = [
   join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.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"),
@@ -109,11 +123,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
 `);
 }
@@ -176,7 +191,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);
   }
@@ -361,6 +376,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) {
@@ -504,6 +534,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 };
@@ -549,6 +584,11 @@ 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();
 }
@@ -575,6 +615,11 @@ function readRunState(targetDir) {
       approvals: new Map(),
       artefacts: new Map(),
       evidence_refs: [],
+      artefact_chain: [],
+      mode_slice_decision: {},
+      missing_evidence: [],
+      risks: [],
+      context_graph: {},
     };
   }
 
@@ -584,10 +629,10 @@ function readRunState(targetDir) {
   addApprovalRows(approvals, content.match(/## Gate Checklist([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "");
 
   const artefacts = new Map();
-  const artefactsSection = content.match(/## Artefacts([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
+  const artefactsSection = markdownSection(content, "Artefacts");
   for (const cells of tableRows(artefactsSection)) {
     const [type, path, status, notes] = cells;
-    if (!userGateOrder.includes(type)) continue;
+    if (!userGateOrder.includes(type) && !internalStepArtefacts.has(type)) continue;
     artefacts.set(type, {
       path: path ?? "",
       status: cleanStatusCell(status ?? ""),
@@ -595,10 +640,17 @@ function readRunState(targetDir) {
     });
   }
 
-  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] ?? "",
@@ -606,6 +658,40 @@ 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,
@@ -614,6 +700,11 @@ function readRunState(targetDir) {
     approvals,
     artefacts,
     evidence_refs,
+    artefact_chain: artefactChain,
+    mode_slice_decision: modeSliceDecision,
+    missing_evidence: missingEvidence,
+    risks,
+    context_graph: contextGraph,
   };
 }
 
@@ -649,6 +740,118 @@ function isDurableGateArtefactSatisfied(runState, gate) {
   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 ?? "";
+  const scopeReason = runState.mode_slice_decision?.scope_reason ?? "";
+  const evidence = runState.mode_slice_decision?.evidence ?? "";
+  if (!decision || isPlaceholderValue(decision) || !filled(scopeReason) || !filled(evidence)) 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`;
@@ -694,6 +897,63 @@ function transitionDecisionForRunState(runState) {
   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, evidence and required next gate depth 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 with scope reason and evidence 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",
@@ -701,7 +961,9 @@ function transitionDecisionForRunState(runState) {
       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: "Draft or refine the PRD; do not implement before PRD, SD and TP are approved.",
+      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.",
     };
   }
 
@@ -750,6 +1012,7 @@ function evaluateGateCheck(targetDir) {
   const doctorReport = evaluateDoctor(targetDir);
   const runState = readRunState(targetDir);
   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");
 
@@ -789,6 +1052,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,
   };
 }
@@ -814,6 +1083,85 @@ 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] ?? "",
+      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] ?? "",
+    }));
+}
+
+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));
 
@@ -829,6 +1177,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);
 

package/generated/.agdf/control/README.md

@@ -9,12 +9,14 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 | File | Purpose |
 |---|---|
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
-| `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/PRD/SD/TP artefacts |
+| `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
+| `templates/artefacts/BROWNFIELD_REVIEW.md` | Template for the durable Brownfield Review and Mode/Slice Decision |
 | `templates/artefacts/PRD.md` | Template for the durable product requirements artefact |
 | `templates/artefacts/SD.md` | Template for the durable solution design artefact |
 | `templates/artefacts/TP.md` | Template for the durable task and test plan artefact |
 | `templates/artefacts/QA_REPORT.md` | Template for the durable QA decision report |
+| `templates/artefacts/OR.md` | Template for the durable Orchestration Report closeout |
 | `templates/SOT_REGISTRY.md` | Template for the source-of-truth registry: one primary owner per domain |
 | `templates/CONTEXT_GRAPH.md` | Template for project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
 | `templates/AGENT_QUALITY_CONTRACTS.json` | Template for machine-readable warning, revise and block contracts for review and QA |
@@ -29,10 +31,12 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
     artefacts/
       <work-item>/
         UR.md
+        BROWNFIELD_REVIEW.md
         PRD.md
         SD.md
         TP.md
         QA_REPORT.md
+        OR.md
     SOT_REGISTRY.md
     CONTEXT_GRAPH.md
     AGENT_QUALITY_CONTRACTS.json
@@ -61,7 +65,9 @@ npm create agdf@latest gate-check --json
 
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
+- Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.
+- OR records the run closeout and next permissible step; it does not approve later gates.
 - `SOT_REGISTRY.md` decides which document owns which domain.
 - `CONTEXT_GRAPH.md` records durable project knowledge only when it has evidence and an exit criterion.
 - `AGENT_QUALITY_CONTRACTS.json` names reusable block, revise and warning conditions.

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

@@ -5,7 +5,7 @@
 - run_id:
 - started_at:
 - mode: `quick_task | structured_delivery`
-- current_gate: `none | UR | PRD | SD | TP | CD+Tests | CR | QA | UAT | OR`
+- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
 - decision: `pass | revise | block | in_progress`
 - owner:
 
@@ -44,10 +44,34 @@ Valid approval format for new runs: `Approval: <GateName>`.
 | PRD |  | `draft | approved | superseded | not_applicable` |  |
 | SD |  | `draft | approved | superseded | not_applicable` |  |
 | TP |  | `draft | approved | superseded | not_applicable` |  |
+| Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
 | Review |  | `missing | done | not_applicable` |  |
 | QA |  | `missing | pass | revise | block | not_applicable` |  |
 | OR |  | `missing | done | not_applicable` |  |
 
+## Mode / Slice Decision
+
+Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
+Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
+
+- decision: `undecided | quick_task | structured_slice | structured_delivery | block`
+- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
+- scope_reason:
+- evidence:
+- transparency_note:
+
+## Artefact Chain
+
+Keep the active work item traceable. A gate may open only when the previous gate has both exact approval and a durable or linked artefact.
+
+| From | Relationship | To | Evidence |
+|---|---|---|---|
+| UR | `approved_by` | `Approval: UR` |  |
+| PRD | `derived_from` | UR |  |
+| SD | `derived_from` | PRD |  |
+| TP | `derived_from` | SD |  |
+| QA_REPORT | `tests` | TP |  |
+
 ## Evidence
 
 | Evidence | Source | Covers | Strength |

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

@@ -1,30 +1,32 @@
 # AGDF Master Backlog
 
-This file is the living control pointer for active AGDF delivery work. Detailed UR, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
+This file is the living control pointer for active AGDF delivery work. Detailed UR, Brownfield Review, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
 
 ## Rules
 
 1. New product semantics, functional change or user-visible behaviour change starts as a new UR draft in a stable local artefact path, for example `.agdf/control/artefacts/<key>/UR.md`, unless an authoritative repository SoT already exists and is linked here.
 2. `Approval: UR` adds or updates exactly one steering row with a link to the UR.
-3. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved.
-4. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
-5. Keep only steering-relevant work in `Active Backlog`.
-6. Every active item has exactly one current spec pointer.
-7. Historical artefacts remain linkable but do not override the current pointer.
-8. If an item is superseded, mark the replacement.
-9. If active work grows beyond roughly ten items, triage the backlog.
+3. Brownfield Review is created for the same work item after UR approval when existing-system impact must be sized before PRD depth or Quick Task execution.
+4. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved and persisted or linked.
+5. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
+6. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
+7. Keep only steering-relevant work in `Active Backlog`.
+8. Every active item has exactly one current spec pointer and a visible artefact chain.
+9. Historical artefacts remain linkable but do not override the current pointer.
+10. If an item is superseded, mark the replacement.
+11. If active work grows beyond roughly ten items, triage the backlog.
 
 ## Active Backlog
 
-| Prio | Key | Title | Status | Current Spec | Notes |
-|---:|---|---|---|---|---|
-| P1 |  |  | `in_progress | blocked` |  |  |
+| Prio | Key | Title | Status | UR | Brownfield Review | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|---|
+| P1 |  |  | `in_progress | blocked` |  |  |  |  |  |  |  |  |  |
 
 ## Planned / Parking Lot
 
-| Prio | Key | Title | Status | Current Spec | Notes |
-|---:|---|---|---|---|---|
-| P2 |  |  | `planned | review_needed` |  |  |
+| Prio | Key | Title | Status | UR | Brownfield Review | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|---|
+| P2 |  |  | `planned | review_needed` |  |  |  |  |  |  |  |  |  |
 
 ## Completed / Superseded Pointers