create-agdf 0.1.7 → 0.1.9

package/README.md

@@ -8,6 +8,9 @@ Bootstrap AGDF repository instructions for one repository.
 npm create agdf@latest codex
 npm create agdf@latest copilot
 npm create agdf@latest both
+npm create agdf@latest init
+npm create agdf@latest doctor
+npm create agdf@latest gate-check
 ```
 
 Optional flags:
@@ -29,7 +32,7 @@ After `npm create agdf@latest codex`, restart Codex in that repository, open `/p
 
 ## Control scaffold
 
-The generated `.agdf/control/templates/` files are starting points for durable AGDF state:
+The generated `.agdf/control/templates/` files are reusable starting points for durable AGDF state:
 
 - `AGDF_RUN.md` for the current run dashboard
 - `MASTER_BACKLOG.md` for active delivery pointers
@@ -37,7 +40,37 @@ The generated `.agdf/control/templates/` files are starting points for durable A
 - `CONTEXT_GRAPH.md` for durable Brownfield findings, decisions, risks, evidence and exit criteria
 - `AGENT_QUALITY_CONTRACTS.json` for reusable block, revise and warning conditions
 
-Copy or promote templates into live `.agdf/control/` files only when the target repository is ready to own them as source-of-truth artefacts.
+Use `init` to promote those templates into live control files:
+
+```bash
+npm create agdf@latest init
+```
+
+This writes:
+
+- `.agdf/control/AGDF_RUN.md`
+- `.agdf/control/MASTER_BACKLOG.md`
+- `.agdf/control/SOT_REGISTRY.md`
+- `.agdf/control/CONTEXT_GRAPH.md`
+- `.agdf/control/AGENT_QUALITY_CONTRACTS.json`
+
+Use `doctor` to check whether the live control state is actionable:
+
+```bash
+npm create agdf@latest doctor
+npm create agdf@latest doctor --json
+```
+
+The doctor reports missing live control files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts. It exits non-zero only for blocking control failures.
+
+Use `gate-check` to derive the next process decision from the doctor result and `AGDF_RUN.md`:
+
+```bash
+npm create agdf@latest gate-check
+npm 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.
 
 ## Single source of truth
 

package/bin/create-agdf.js

@@ -11,8 +11,9 @@ 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"]);
+const allowedTargets = new Set(["codex", "copilot", "both", "init", "doctor", "gate-check"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
+const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const codexPluginFiles = [
@@ -41,6 +42,35 @@ const controlFiles = [
   join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
 ];
+const liveControlFiles = [
+  {
+    path: join(".agdf", "control", "AGDF_RUN.md"),
+    source: join(".agdf", "control", "templates", "AGDF_RUN.md"),
+  },
+  {
+    path: join(".agdf", "control", "MASTER_BACKLOG.md"),
+    source: join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
+  },
+  {
+    path: join(".agdf", "control", "SOT_REGISTRY.md"),
+    source: join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
+  },
+  {
+    path: join(".agdf", "control", "CONTEXT_GRAPH.md"),
+    source: join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
+  },
+  {
+    path: join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json"),
+    source: join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  },
+];
+const doctorRequiredFiles = [
+  join(".agdf", "control", "AGDF_RUN.md"),
+  join(".agdf", "control", "MASTER_BACKLOG.md"),
+  join(".agdf", "control", "SOT_REGISTRY.md"),
+  join(".agdf", "control", "CONTEXT_GRAPH.md"),
+  join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json"),
+];
 const copilotInstructionFiles = [
   join(".github", "copilot-instructions.md"),
   join(".github", "instructions", "agdf-governance.instructions.md"),
@@ -58,10 +88,14 @@ Usage:
   npm create agdf@latest codex
   npm create agdf@latest copilot
   npm create agdf@latest both
+  npm create agdf@latest init
+  npm create agdf@latest doctor
+  npm create agdf@latest gate-check
 
 Options:
   --dir <path>   Write files into a specific directory
   --force        Overwrite existing generated files
+  --json         Print doctor or gate-check output as JSON
   --help         Show this help
 `);
 }
@@ -71,6 +105,7 @@ function parseArgs(argv) {
   let target;
   let dir = ".";
   let force = false;
+  let json = false;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -86,6 +121,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+
     if (arg === "--dir") {
       const next = args[i + 1];
       if (!next) {
@@ -118,7 +158,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot or both.");
+    console.error("Please choose one target: codex, copilot, both, init, doctor or gate-check.");
     printUsage();
     process.exit(1);
   }
@@ -127,6 +167,7 @@ function parseArgs(argv) {
     target,
     dir: resolve(process.cwd(), dir),
     force,
+    json,
   };
 }
 
@@ -148,6 +189,22 @@ function writeGeneratedFile(targetDir, relativePath, content, force) {
 function generatedFilesForTarget(target, targetDir, force) {
   const files = [];
 
+  if (target === "init") {
+    files.push({
+      path: join(".agdf", "control", "README.md"),
+      content: loadAsset(join(".agdf", "control", "README.md")),
+    });
+
+    for (const controlPath of liveControlFiles) {
+      files.push({
+        path: controlPath.path,
+        content: loadAsset(controlPath.source),
+      });
+    }
+
+    return files;
+  }
+
   if (target === "codex" || target === "both") {
     for (const codexPath of codexPluginFiles) {
       files.push({
@@ -200,6 +257,12 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
 
   console.log("");
   console.log("Next steps:");
+  if (target === "init") {
+    console.log("- Fill .agdf/control/AGDF_RUN.md with the current gate, evidence and next allowed action.");
+    console.log("- Run npm create agdf@latest doctor to check the control state before the next agent run.");
+    console.log("- Commit the live control files once they represent the repository's current delivery state.");
+    return;
+  }
   if (wroteAgentsFragment) {
     console.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
   }
@@ -212,13 +275,422 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
   }
   if (target === "copilot" || target === "both") {
     console.log("- In GitHub Copilot CLI, run /instructions after the AGENTS.md step is complete to confirm that AGDF instructions and the repository skills are visible.");
-    console.log("- Copy the templates under .agdf/control/templates into live control files when the repository needs a durable run state, backlog pointer, SoT registry or context graph.");
+    console.log("- Run npm create agdf@latest init when the repository needs live AGDF control files.");
   }
   console.log("- Commit the generated files so the repository becomes the source of truth.");
 }
 
+function readTargetFile(targetDir, relativePath) {
+  return readFileSync(join(targetDir, relativePath), "utf8");
+}
+
+function addFinding(findings, severity, code, message, path, nextStep) {
+  findings.push({
+    severity,
+    code,
+    message,
+    path,
+    next_step: nextStep,
+  });
+}
+
+function nonEmptyTableRows(content) {
+  return content
+    .split("\n")
+    .filter((line) => line.trim().startsWith("|"))
+    .filter((line) => !line.includes("---"))
+    .map((line) => line.split("|").map((cell) => cell.trim()).filter(Boolean))
+    .filter((cells) => cells.some((cell) => cell && !cell.startsWith("`")));
+}
+
+function tableRows(content) {
+  return content
+    .split("\n")
+    .filter((line) => line.trim().startsWith("|"))
+    .filter((line) => !line.includes("---"))
+    .map((line) => {
+      const cells = line.split("|").map((cell) => cell.trim());
+      if (cells[0] === "") cells.shift();
+      if (cells.at(-1) === "") cells.pop();
+      return cells;
+    });
+}
+
+function hasFilledTableRow(content, firstCellPattern) {
+  return tableRows(content)
+    .filter((cells) => firstCellPattern.test(cells[0] ?? ""))
+    .some((cells) => cells.slice(1).some((cell) => cell && !cell.startsWith("`")));
+}
+
+function isPlaceholderValue(value) {
+  return !value || (value.startsWith("`") && value.includes("|"));
+}
+
+function hasFilledEvidenceRow(content) {
+  const evidenceSection = content.match(/## Evidence([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
+  return tableRows(evidenceSection)
+    .filter((cells) => cells[0] !== "Evidence")
+    .some((cells) => {
+      const [evidence, source, covers] = cells;
+      return Boolean(evidence || source || covers);
+    });
+}
+
+function parseQualityContracts(content) {
+  const parsed = JSON.parse(content);
+  if (!Array.isArray(parsed.contracts) || parsed.contracts.length === 0) {
+    throw new Error("contracts must be a non-empty array");
+  }
+  for (const contract of parsed.contracts) {
+    if (!contract.code || !contract.impact || !contract.required_evidence) {
+      throw new Error(`contract ${contract.code ?? "<unknown>"} is missing code, impact or required_evidence`);
+    }
+  }
+  return parsed;
+}
+
+function evaluateDoctor(targetDir) {
+  const findings = [];
+  const missing = doctorRequiredFiles.filter((relativePath) => !existsSync(join(targetDir, relativePath)));
+
+  for (const relativePath of missing) {
+    const templatePath = join(dirname(relativePath), "templates", relativePath.split("/").at(-1));
+    const hasTemplate = existsSync(join(targetDir, templatePath));
+    addFinding(
+      findings,
+      "block",
+      "AGDF_CONTROL_FILE_MISSING",
+      hasTemplate
+        ? "Live control file is missing; only the template exists."
+        : "Required live control file is missing.",
+      relativePath,
+      "Run npm create agdf@latest init, then fill the live control files with the current repository state.",
+    );
+  }
+
+  if (missing.length === 0) {
+    const runPath = join(".agdf", "control", "AGDF_RUN.md");
+    const run = readTargetFile(targetDir, runPath);
+    const currentGateLine = run.match(/^- current_gate:[^\S\r\n]*(.*)$/m)?.[1]?.trim() ?? "";
+    const nextActionLine = run.match(/^- next_allowed_action:[^\S\r\n]*(.*)$/m)?.[1]?.trim() ?? "";
+    const hasEvidence = hasFilledEvidenceRow(run);
+
+    if (isPlaceholderValue(currentGateLine)) {
+      addFinding(
+        findings,
+        "revise",
+        "AGDF_CURRENT_GATE_MISSING",
+        "AGDF_RUN.md does not name the current gate.",
+        runPath,
+        "Set current_gate to the current delivery gate or none.",
+      );
+    }
+
+    if (isPlaceholderValue(nextActionLine)) {
+      addFinding(
+        findings,
+        "revise",
+        "AGDF_NEXT_ALLOWED_ACTION_MISSING",
+        "AGDF_RUN.md does not state the next allowed action.",
+        runPath,
+        "Fill the next allowed action before asking an agent to continue delivery work.",
+      );
+    }
+
+    if (!hasEvidence) {
+      addFinding(
+        findings,
+        "warn",
+        "AGDF_EVIDENCE_EMPTY",
+        "AGDF_RUN.md has no visible evidence row yet.",
+        runPath,
+        "Add at least one evidence row or explicitly document that no evidence exists yet.",
+      );
+    }
+
+    const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");
+    const backlog = readTargetFile(targetDir, backlogPath);
+    if (!hasFilledTableRow(backlog, /^P[0-9]/)) {
+      addFinding(
+        findings,
+        "warn",
+        "AGDF_BACKLOG_POINTER_EMPTY",
+        "MASTER_BACKLOG.md does not contain an active or planned work pointer.",
+        backlogPath,
+        "Add the active item or document that no governed delivery item is active.",
+      );
+    }
+
+    const sotPath = join(".agdf", "control", "SOT_REGISTRY.md");
+    const sot = readTargetFile(targetDir, sotPath);
+    if (!hasFilledTableRow(sot, /Product intent|Architecture|Runtime contracts|UX \/ user flows|Operations \/ release/)) {
+      addFinding(
+        findings,
+        "warn",
+        "AGDF_SOT_REGISTRY_EMPTY",
+        "SOT_REGISTRY.md has no filled primary source-of-truth row.",
+        sotPath,
+        "Assign one primary source of truth for at least the domains relevant to the next run.",
+      );
+    }
+
+    const activeDomains = new Map();
+    for (const cells of nonEmptyTableRows(sot)) {
+      const [domain, document, status] = cells;
+      if (!domain || !document || status !== "active") continue;
+      activeDomains.set(domain, (activeDomains.get(domain) ?? 0) + 1);
+    }
+    for (const [domain, count] of activeDomains.entries()) {
+      if (count > 1) {
+        addFinding(
+          findings,
+          "block",
+          "AGDF_PARALLEL_SOT",
+          `Domain has ${count} active source-of-truth rows: ${domain}.`,
+          sotPath,
+          "Keep exactly one active primary source of truth for this domain.",
+        );
+      }
+    }
+
+    const contextPath = join(".agdf", "control", "CONTEXT_GRAPH.md");
+    const contextGraph = readTargetFile(targetDir, contextPath);
+    if (contextGraph.includes("### CG-001 Example")) {
+      addFinding(
+        findings,
+        "warn",
+        "AGDF_CONTEXT_GRAPH_TEMPLATE_NODE",
+        "CONTEXT_GRAPH.md still contains the example node.",
+        contextPath,
+        "Remove the example or replace it with an evidenced node that has an exit criterion.",
+      );
+    }
+
+    const contractsPath = join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json");
+    try {
+      parseQualityContracts(readTargetFile(targetDir, contractsPath));
+    } catch (error) {
+      addFinding(
+        findings,
+        "block",
+        "AGDF_QUALITY_CONTRACTS_INVALID",
+        `AGENT_QUALITY_CONTRACTS.json is invalid: ${error.message}`,
+        contractsPath,
+        "Restore the generated contracts or fix the JSON contract schema.",
+      );
+    }
+  }
+
+  const severityRank = { block: 3, revise: 2, warn: 1 };
+  const maxSeverity = findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
+  const status = maxSeverity >= 3 ? "block" : maxSeverity === 2 ? "revise" : maxSeverity === 1 ? "warn" : "pass";
+
+  return {
+    schema_version: "1",
+    status,
+    checked_at: new Date().toISOString(),
+    target_dir: targetDir,
+    summary: {
+      findings: findings.length,
+      block: findings.filter((finding) => finding.severity === "block").length,
+      revise: findings.filter((finding) => finding.severity === "revise").length,
+      warn: findings.filter((finding) => finding.severity === "warn").length,
+    },
+    findings,
+  };
+}
+
+function printDoctorReport(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log(`AGDF doctor: ${report.status}`);
+  console.log(`Checked: ${report.target_dir}`);
+  console.log(`Findings: ${report.summary.findings} (${report.summary.block} block, ${report.summary.revise} revise, ${report.summary.warn} warn)`);
+
+  for (const finding of report.findings) {
+    console.log("");
+    console.log(`[${finding.severity}] ${finding.code}`);
+    console.log(`Path: ${finding.path}`);
+    console.log(finding.message);
+    console.log(`Next step: ${finding.next_step}`);
+  }
+}
+
+function extractField(content, field) {
+  const pattern = new RegExp(`^- ${field}:[^\\S\\r\\n]*(.*)$`, "m");
+  return content.match(pattern)?.[1]?.trim() ?? "";
+}
+
+function cleanStatusCell(value) {
+  return value.replace(/^`|`$/g, "").trim();
+}
+
+function readRunState(targetDir) {
+  const runPath = join(".agdf", "control", "AGDF_RUN.md");
+  if (!existsSync(join(targetDir, runPath))) {
+    return {
+      path: runPath,
+      content: "",
+      current_gate: "",
+      next_allowed_action: "",
+      approvals: new Map(),
+      evidence_refs: [],
+    };
+  }
+
+  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, {
+      status: cleanStatusCell(status ?? ""),
+      evidence: evidence ?? "",
+    });
+  }
+
+  const evidenceSection = content.match(/## Evidence([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
+  const evidence_refs = tableRows(evidenceSection)
+    .filter((cells) => cells[0] !== "Evidence")
+    .filter((cells) => Boolean(cells[0] || cells[1] || cells[2]))
+    .map((cells) => ({
+      evidence: cells[0] ?? "",
+      source: cells[1] ?? "",
+      covers: cells[2] ?? "",
+      strength: cleanStatusCell(cells[3] ?? ""),
+    }));
+
+  return {
+    path: runPath,
+    content,
+    current_gate: extractField(content, "current_gate"),
+    next_allowed_action: extractField(content, "next_allowed_action"),
+    approvals,
+    evidence_refs,
+  };
+}
+
+function firstUnapprovedGate(approvals) {
+  for (const gate of userGateOrder) {
+    const status = approvals.get(gate)?.status ?? "";
+    if (status !== "approved" && status !== "not_applicable") return gate;
+  }
+  return "OR";
+}
+
+function normalizeCurrentGate(value, fallbackGate) {
+  if (isPlaceholderValue(value)) return fallbackGate;
+  const normalized = value.replace(/`/g, "").trim();
+  return normalized || fallbackGate;
+}
+
+function gateApprovalStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return "not_applicable";
+  return runState.approvals.get(gate)?.status ?? "";
+}
+
+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 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 nextAllowedAction = isPlaceholderValue(runState.next_allowed_action)
+    ? "Continue with the current documented gate only after setting next_allowed_action."
+    : runState.next_allowed_action;
+
+  if (doctorBlocker) {
+    status = "blocked";
+    blockingReason = doctorBlocker.code;
+    allowed = ["repair the AGDF control scaffold", "run doctor again"];
+    forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
+    nextAllowedAction = doctorBlocker.next_step;
+  } else if (doctorRevise) {
+    status = "blocked";
+    blockingReason = doctorRevise.code;
+    allowed = ["repair the incomplete control state", "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 {
+    schema_version: "1",
+    status,
+    current_gate: currentGate,
+    blocking_reason: blockingReason,
+    missing_approval: missingApproval,
+    allowed,
+    forbidden,
+    next_allowed_action: nextAllowedAction,
+    doctor_status: doctorReport.status,
+    doctor_summary: doctorReport.summary,
+    evidence_refs: runState.evidence_refs,
+    doctor_report: doctorReport,
+  };
+}
+
+function printGateCheckReport(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log(`AGDF gate-check: ${report.status}`);
+  console.log(`Current gate: ${report.current_gate}`);
+  console.log(`Blocking reason: ${report.blocking_reason}`);
+  console.log(`Missing approval: ${report.missing_approval}`);
+  console.log(`Doctor: ${report.doctor_status} (${report.doctor_summary.findings} findings)`);
+  console.log("");
+  console.log("Allowed:");
+  for (const item of report.allowed) console.log(`- ${item}`);
+  console.log("");
+  console.log("Forbidden:");
+  for (const item of report.forbidden) console.log(`- ${item}`);
+  console.log("");
+  console.log(`Next allowed action: ${report.next_allowed_action}`);
+}
+
 function main() {
   const options = parseArgs(process.argv.slice(2));
+
+  if (options.target === "doctor") {
+    const report = evaluateDoctor(options.dir);
+    printDoctorReport(report, options.json);
+    process.exit(report.status === "block" ? 2 : 0);
+  }
+
+  if (options.target === "gate-check") {
+    const report = evaluateGateCheck(options.dir);
+    printGateCheckReport(report, options.json);
+    process.exit(report.status === "blocked" ? 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

@@ -8,11 +8,11 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 | File | Purpose |
 |---|---|
-| `templates/AGDF_RUN.md` | Current run state: mode, gate, approvals, evidence, risks, next allowed action |
-| `templates/MASTER_BACKLOG.md` | Living backlog pointer: active initiatives and current UR/PRD/SD/TP artefacts |
-| `templates/SOT_REGISTRY.md` | Source-of-truth registry: one primary owner per domain |
-| `templates/CONTEXT_GRAPH.md` | Project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
-| `templates/AGENT_QUALITY_CONTRACTS.json` | Machine-readable warning, revise and block contracts for review and QA |
+| `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/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 |
 
 ## Recommended Target Layout
 
@@ -28,6 +28,23 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 Keep these files small and reviewable. They are control artefacts, not a second documentation site.
 
+Create the live files with:
+
+```bash
+npm create agdf@latest init
+```
+
+Then check whether the live state is actionable:
+
+```bash
+npm create agdf@latest doctor
+npm create agdf@latest doctor --json
+npm create agdf@latest gate-check --json
+```
+
+`doctor` does not replace agent judgment. It catches basic control failures: missing live files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts.
+`gate-check` consumes the doctor result and live run state to report whether the next process step is `open` or `blocked`.
+
 ## Operating Rules
 
 - `AGDF_RUN.md` is the current run dashboard.

package/generated/.github/skills/agdf-gate-check/SKILL.md

@@ -20,6 +20,19 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 ## Runtime Contract
 Use `../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
 
+## Machine-Readable Control Path
+
+When the target repository contains live AGDF control files, prefer the executable control path before deriving a gate decision manually:
+
+```bash
+npm create agdf@latest doctor --json
+npm create agdf@latest gate-check --json
+```
+
+`doctor` checks whether `.agdf/control/` is actionable. `agdf-gate-check` consumes that result and `AGDF_RUN.md` to report the operative process decision: `open | blocked`, current gate, blocking reason, missing approval, allowed outputs, forbidden outputs, next allowed action and evidence references.
+
+The CLI report is evidence for this skill, not a second rule system. If the report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",

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

@@ -8,11 +8,11 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 | File | Purpose |
 |---|---|
-| `templates/AGDF_RUN.md` | Current run state: mode, gate, approvals, evidence, risks, next allowed action |
-| `templates/MASTER_BACKLOG.md` | Living backlog pointer: active initiatives and current UR/PRD/SD/TP artefacts |
-| `templates/SOT_REGISTRY.md` | Source-of-truth registry: one primary owner per domain |
-| `templates/CONTEXT_GRAPH.md` | Project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
-| `templates/AGENT_QUALITY_CONTRACTS.json` | Machine-readable warning, revise and block contracts for review and QA |
+| `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/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 |
 
 ## Recommended Target Layout
 
@@ -28,6 +28,23 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 Keep these files small and reviewable. They are control artefacts, not a second documentation site.
 
+Create the live files with:
+
+```bash
+npm create agdf@latest init
+```
+
+Then check whether the live state is actionable:
+
+```bash
+npm create agdf@latest doctor
+npm create agdf@latest doctor --json
+npm create agdf@latest gate-check --json
+```
+
+`doctor` does not replace agent judgment. It catches basic control failures: missing live files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts.
+`gate-check` consumes the doctor result and live run state to report whether the next process step is `open` or `blocked`.
+
 ## Operating Rules
 
 - `AGDF_RUN.md` is the current run dashboard.

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -20,6 +20,19 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 ## Runtime Contract
 Use `../../meta/agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
 
+## Machine-Readable Control Path
+
+When the target repository contains live AGDF control files, prefer the executable control path before deriving a gate decision manually:
+
+```bash
+npm create agdf@latest doctor --json
+npm create agdf@latest gate-check --json
+```
+
+`doctor` checks whether `.agdf/control/` is actionable. `gate-check` consumes that result and `AGDF_RUN.md` to report the operative process decision: `open | blocked`, current gate, blocking reason, missing approval, allowed outputs, forbidden outputs, next allowed action and evidence references.
+
+The CLI report is evidence for this skill, not a second rule system. If the report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Bootstrap AGDF repository-local Codex plugin marketplaces, Copilot instructions, skills and control templates.",
   "type": "module",
   "files": [