create-agdf 0.1.8 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # create-agdf
 
-Bootstrap AGDF repository instructions for one repository.
+Bootstrap AGDF repository instructions and a machine-checkable control loop for one repository.
 
 ## Usage
 
@@ -10,6 +10,7 @@ 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:
@@ -62,6 +63,17 @@ 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.
+
+Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction layer into a repository control system: the agent can be guided by rules, and the repository state can be checked before the next governed step.
+
 ## Single source of truth
 
 The repository-facing AGDF sources are maintained in:

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", "init", "doctor"]);
+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 = [
@@ -89,11 +90,12 @@ Usage:
   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 output as JSON
+  --json         Print doctor or gate-check output as JSON
   --help         Show this help
 `);
 }
@@ -156,7 +158,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot, both, init or doctor.");
+    console.error("Please choose one target: codex, copilot, both, init, doctor or gate-check.");
     printUsage();
     process.exit(1);
   }
@@ -517,6 +519,163 @@ function printDoctorReport(report, json) {
   }
 }
 
+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));
 
@@ -526,6 +685,12 @@ function main() {
     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

@@ -39,9 +39,11 @@ 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
 

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.8",
+  "version": "0.2.0",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",
@@ -15,7 +15,7 @@
   "interface": {
     "displayName": "AI Governance & Delivery Framework",
     "shortDescription": "Codex-first workflow skills for gated, auditable AI-assisted delivery.",
-    "longDescription": "AI Governance & Delivery Framework (AGDF) packages reusable Codex-first skills and control templates for gate checks, Brownfield analysis, task-plan review, solution-integrity review, QA decisions, durable run state and auditable delivery closeout.",
+    "longDescription": "AI Governance & Delivery Framework (AGDF) packages reusable Codex-first skills, control templates and machine-readable repository checks for gate decisions, Brownfield analysis, task-plan review, solution-integrity review, QA decisions, durable run state and auditable delivery closeout.",
     "developerName": "AI-native Governance & Delivery Framework",
     "category": "Productivity",
     "capabilities": ["Read", "Write"],

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

@@ -39,9 +39,11 @@ 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
 

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

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "claudeDescription": "Codex-first workflow skills and control templates for gated, auditable AI-assisted software delivery.",
   "shortDescription": "Codex-first workflow skills for gated, auditable AI-assisted delivery.",
-  "longDescription": "AI Governance & Delivery Framework (AGDF) packages reusable Codex-first skills and control templates for gate checks, Brownfield analysis, task-plan review, solution-integrity review, QA decisions, durable run state and auditable delivery closeout.",
+  "longDescription": "AI Governance & Delivery Framework (AGDF) packages reusable Codex-first skills, control templates and machine-readable repository checks for gate decisions, Brownfield analysis, task-plan review, solution-integrity review, QA decisions, durable run state and auditable delivery closeout.",
   "homepage": "https://agdf.iself.eu",
   "repository": "https://github.com/arndtgold/ai-native-governance-delivery-framework",
   "license": "Apache-2.0",

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,7 +1,7 @@
 {
   "name": "create-agdf",
-  "version": "0.1.8",
-  "description": "Bootstrap AGDF repository-local Codex plugin marketplaces, Copilot instructions, skills and control templates.",
+  "version": "0.2.0",
+  "description": "Bootstrap AGDF repository-local plugin files, Copilot instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
     "bin",