create-agdf 0.6.4 → 0.6.6

package/bin/create-agdf.js

@@ -1001,6 +1001,10 @@ const backlogArtefactLabels = new Map([
   ["qa", "qa"],
   ["or", "or"],
 ]);
+const backlogScopeLabels = new Map([
+  ["framework-maintenance", "framework_maintenance"],
+  ["external-delivery", "external_delivery"],
+]);
 
 function normalizeBacklogHeader(value) {
   return value.replace(/`/g, "").trim().toLowerCase();
@@ -1062,11 +1066,32 @@ function normalizeBacklogStatus(value, findings, backlogPath) {
   return cleaned;
 }
 
+function normalizeBacklogScope(workItem, findings, backlogPath) {
+  const match = (workItem ?? "").match(/^\[([^\]]+)\]/);
+  if (!match) return undefined;
+  const cleaned = match[1].trim();
+  const lookup = cleaned.replaceAll("_", " ").toLowerCase().replaceAll(" ", "-");
+  const normalized = backlogScopeLabels.get(lookup);
+  if (normalized) return normalized;
+  if (findings) {
+    addFinding(
+      findings,
+      "revise",
+      "AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN",
+      `MASTER_BACKLOG.md uses an unknown Work item scope tag: [${cleaned}].`,
+      backlogPath,
+      "Use [framework-maintenance] or [external-delivery], or remove the bracketed tag.",
+    );
+  }
+  return cleaned;
+}
+
 function emptyBacklogPointer() {
   return {
     prio: "",
     key: "",
     title: "",
+    scope: "",
     status: "",
     ur: "",
     brownfield_review: "",
@@ -1181,6 +1206,7 @@ function parseBacklogSection(section, findings = null, backlogPath = ".agdf/cont
       pointer.prio = cells[0] ?? "";
       pointer.key = cleanStatusCell(cells[1] ?? "");
       pointer.title = cells[2] ?? "";
+      pointer.scope = normalizeBacklogScope(cells[2], findings, backlogPath) ?? "";
       pointer.status = normalizeBacklogStatus(cells[3], findings, backlogPath);
       parseCompactArtefacts(cells[4] ?? "", pointer, findings, backlogPath);
       pointer.current_spec = normalizedBacklogLinkTarget(cells[5] ?? "", findings, backlogPath, "Current spec");
@@ -1316,41 +1342,53 @@ function evaluateDoctor(targetDir, selection = {}) {
     const selectedRunState = readRunState(targetDir, selection);
     const runPath = selectedRunState.path;
     const run = selectedRunState.content;
-    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)) {
+    if (selectedRunState.resolution_error) {
       addFinding(
         findings,
-        "revise",
-        "AGDF_CURRENT_GATE_MISSING",
-        "The selected run state does not name the current gate.",
+        "block",
+        selectedRunState.resolution_error.split(":")[0] || "AGDF_ACTIVE_RUN_UNRESOLVED",
+        `Run selection failed: ${selectedRunState.resolution_error}`,
         runPath,
-        "Set current_gate to the current delivery gate or none.",
+        "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run, or use --all-active to evaluate every active run independently.",
       );
-    }
+    } else {
+      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(nextActionLine)) {
-      addFinding(
-        findings,
-        "revise",
-        "AGDF_NEXT_ALLOWED_ACTION_MISSING",
-        "The selected run state does not state the next allowed action.",
-        runPath,
-        "Fill the next allowed action before asking an agent to continue delivery work.",
-      );
-    }
+      if (isPlaceholderValue(currentGateLine)) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_CURRENT_GATE_MISSING",
+          "The selected run state does not name the current gate.",
+          runPath,
+          "Set current_gate to the current delivery gate or none.",
+        );
+      }
 
-    if (!hasEvidence) {
-      addFinding(
-        findings,
-        "warn",
-        "AGDF_EVIDENCE_EMPTY",
-        "The selected run state has no visible evidence row yet.",
-        runPath,
-        "Add at least one evidence row or explicitly document that no evidence exists yet.",
-      );
+      if (isPlaceholderValue(nextActionLine)) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_NEXT_ALLOWED_ACTION_MISSING",
+          "The selected run state 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",
+          "The selected run state 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");
@@ -1489,16 +1527,21 @@ function cleanStatusCell(value) {
 function readRunState(targetDir, selection = {}) {
   let runPath = join(".agdf", "control", "AGDF_RUN.md");
   const canonicalRoot = join(targetDir, ".agdf", "control", "runs");
+  let resolutionError;
   if (existsSync(canonicalRoot)) {
-    const selected = resolveRuns(targetDir, {
-      runIdArg: selection.runId,
-      runIdEnv: process.env.AGDF_RUN_ID,
-    });
-    runPath = selected.run.path.startsWith(targetDir)
-      ? selected.run.path.slice(targetDir.length + 1)
-      : selected.run.path;
+    try {
+      const selected = resolveRuns(targetDir, {
+        runIdArg: selection.runId,
+        runIdEnv: process.env.AGDF_RUN_ID,
+      });
+      runPath = selected.run.path.startsWith(targetDir)
+        ? selected.run.path.slice(targetDir.length + 1)
+        : selected.run.path;
+    } catch (error) {
+      resolutionError = error.message;
+    }
   }
-  if (!existsSync(join(targetDir, runPath))) {
+  if (resolutionError || !existsSync(join(targetDir, runPath))) {
     return {
       path: runPath,
       content: "",
@@ -1515,6 +1558,7 @@ function readRunState(targetDir, selection = {}) {
       quality_outlook: "",
       source_scope: {},
       memory: {},
+      resolution_error: resolutionError,
     };
   }
 

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

@@ -18,6 +18,8 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 12. `Status` must be one of the human-readable labels `create-agdf/bin/create-agdf.js`'s `backlogStatusLabels` normalizes: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Completed, Superseded, Abandoned. That map is authoritative; this list only mirrors it for readability.
 13. `Artefacts` link labels must be one of `backlogArtefactLabels`: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
 14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
+15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/bin/create-agdf.js`'s `backlogScopeLabels` map is authoritative for the two accepted values.
+16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
 
 ## Active Backlog
 

package/generated/.github/skills/agdf-runtime-contract.md

@@ -47,6 +47,22 @@ A `MASTER_BACKLOG.md` entry is required only when the change is otherwise a "Rel
 change that is not clearly and fully outside every listed path fails closed to the existing, unchanged
 ceremony — ambiguity is never read as permission for the lighter path.
 
+#### Narrow Code-Fix Criterion
+
+A change that touches one of the otherwise-excluded code paths above may still close with only the
+compact Quick Task Output shape — Code Review remains mandatory regardless — when **all** of the
+following hold. Any single condition failing, or any ambiguity about whether a condition holds, keeps
+the full existing ceremony unchanged:
+
+1. The diff is confined to a single function, or a function together with its direct,
+   necessarily-coupled caller, in exactly one file.
+2. A new or updated automated regression test exercises the fixed behavior and passes.
+3. No PRD, SD, TP, gate name, exact approval formula, or documented CLI flag/output-schema field is
+   added, removed, or changed — only internal correctness of already-approved behavior.
+4. `doctor` (or the locally available equivalent) and the directly affected existing test suite both
+   pass unchanged in shape after the fix, with no assertion skipped or weakened beyond what the fix
+   itself introduces.
+
 ## Run Status Card
 
 When a run needs an operational status view, use the Run Status Card as a compact projection of existing control state.

package/generated/.opencode/agdf-runtime-contract.md

@@ -47,6 +47,22 @@ A `MASTER_BACKLOG.md` entry is required only when the change is otherwise a "Rel
 change that is not clearly and fully outside every listed path fails closed to the existing, unchanged
 ceremony — ambiguity is never read as permission for the lighter path.
 
+#### Narrow Code-Fix Criterion
+
+A change that touches one of the otherwise-excluded code paths above may still close with only the
+compact Quick Task Output shape — Code Review remains mandatory regardless — when **all** of the
+following hold. Any single condition failing, or any ambiguity about whether a condition holds, keeps
+the full existing ceremony unchanged:
+
+1. The diff is confined to a single function, or a function together with its direct,
+   necessarily-coupled caller, in exactly one file.
+2. A new or updated automated regression test exercises the fixed behavior and passes.
+3. No PRD, SD, TP, gate name, exact approval formula, or documented CLI flag/output-schema field is
+   added, removed, or changed — only internal correctness of already-approved behavior.
+4. `doctor` (or the locally available equivalent) and the directly affected existing test suite both
+   pass unchanged in shape after the fix, with no assertion skipped or weakened beyond what the fix
+   itself introduces.
+
 ## Run Status Card
 
 When a run needs an operational status view, use the Run Status Card as a compact projection of existing control state.

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

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",
@@ -32,6 +32,7 @@
     "composerIcon": "./assets/agdf-icon.svg",
     "logo": "./assets/agdf-logo.svg",
     "defaultPrompt": [
+      "Evaluate whether AGDF is appropriate for this repository and request. Explain its purpose, practical value, governance overhead, and fit for the project's risk level. Recommend the smallest suitable AGDF path before proposing implementation.",
       "Start this request under AGDF governance.",
       "Create durable AGDF control state for this repository.",
       "Close this delivery run with an auditable AGDF report."

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

@@ -18,6 +18,8 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 12. `Status` must be one of the human-readable labels `create-agdf/bin/create-agdf.js`'s `backlogStatusLabels` normalizes: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Completed, Superseded, Abandoned. That map is authoritative; this list only mirrors it for readability.
 13. `Artefacts` link labels must be one of `backlogArtefactLabels`: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
 14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
+15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `create-agdf/bin/create-agdf.js`'s `backlogScopeLabels` map is authoritative for the two accepted values.
+16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
 
 ## Active Backlog
 

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -35,6 +35,7 @@
       "Write"
     ],
     "defaultPrompt": [
+      "Evaluate whether AGDF is appropriate for this repository and request. Explain its purpose, practical value, governance overhead, and fit for the project's risk level. Recommend the smallest suitable AGDF path before proposing implementation.",
       "Start this request under AGDF governance.",
       "Create durable AGDF control state for this repository.",
       "Close this delivery run with an auditable AGDF report."

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -47,6 +47,22 @@ A `MASTER_BACKLOG.md` entry is required only when the change is otherwise a "Rel
 change that is not clearly and fully outside every listed path fails closed to the existing, unchanged
 ceremony — ambiguity is never read as permission for the lighter path.
 
+#### Narrow Code-Fix Criterion
+
+A change that touches one of the otherwise-excluded code paths above may still close with only the
+compact Quick Task Output shape — Code Review remains mandatory regardless — when **all** of the
+following hold. Any single condition failing, or any ambiguity about whether a condition holds, keeps
+the full existing ceremony unchanged:
+
+1. The diff is confined to a single function, or a function together with its direct,
+   necessarily-coupled caller, in exactly one file.
+2. A new or updated automated regression test exercises the fixed behavior and passes.
+3. No PRD, SD, TP, gate name, exact approval formula, or documented CLI flag/output-schema field is
+   added, removed, or changed — only internal correctness of already-approved behavior.
+4. `doctor` (or the locally available equivalent) and the directly affected existing test suite both
+   pass unchanged in shape after the fix, with no assertion skipped or weakened beyond what the fix
+   itself introduces.
+
 ## Run Status Card
 
 When a run needs an operational status view, use the Run Status Card as a compact projection of existing control state.

package/lib/control-state/legacy-migration.js

@@ -62,7 +62,8 @@ export function renderLegacyProjection(path, root = process.cwd()) {
     parsed = parseRunState(content),
     digest = createHash("sha256").update(content).digest("hex");
   if (!parsed.valid) throw Error("AGDF_RUN_NOT_SELECTABLE");
-  return `<!-- AGDF LEGACY PROJECTION: NON-AUTHORITATIVE -->\n<!-- canonical_source: ${relative(resolve(root), resolve(path))} -->\n<!-- run_id: ${parsed.meta.run_id} -->\n<!-- revision_id: ${parsed.meta.revision_id} -->\n<!-- sha256: ${digest} -->\n${content}`;
+  const canonicalSource = relative(resolve(root), resolve(path)).replaceAll("\\", "/");
+  return `<!-- AGDF LEGACY PROJECTION: NON-AUTHORITATIVE -->\n<!-- canonical_source: ${canonicalSource} -->\n<!-- run_id: ${parsed.meta.run_id} -->\n<!-- revision_id: ${parsed.meta.revision_id} -->\n<!-- sha256: ${digest} -->\n${content}`;
 }
 export function writeLegacyProjection(path, canonical) {
   atomicWrite(path, renderLegacyProjection(canonical, resolve(dirname(path), "../..")));
@@ -78,7 +79,7 @@ export function verifyLegacyProjection(root) {
     projected = projectedStart >= 0 ? p.slice(projectedStart) : undefined;
   if (!source || !runId || !digest || projected === undefined)
     return { status: discoverRuns(root).length ? "mixed_authority" : "legacy" };
-  const target = resolve(root, source),
+  const target = resolve(root, source.replaceAll("\\", "/")),
     rel = relative(resolve(root), target),
     expected = relative(resolve(root), resolve(runPath(root, runId)));
   if (rel.startsWith("..") || !rel || rel !== expected || !existsSync(target))

package/lib/control-state/run-state-writer.js

@@ -15,6 +15,7 @@ import { dirname } from "node:path";
 import { parseRunState } from "./run-state-parser.js";
 
 function fsyncDirectory(path) {
+  if (process.platform === "win32") return;
   const descriptor = openSync(path, "r");
   try {
     fsyncSync(descriptor);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [