create-agdf 0.14.1 → 0.14.3

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-evaluation/run-state.js

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import process from "node:process";
+import { parseControlState, resolveRuns } from "../control-state/index.js";
+import { buildRunCandidates } from "../interaction-presentation.js";
+import { cleanStatusCell, filled, isPlaceholderValue, readTargetFile } from "./shared.js";
+import { extractField, isSafeRepoRelativePath, readVerifiedChangeRecord } from "./verified-change.js";
+
+export const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
+export const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
+export const internalStepArtefacts = new Set(["Brownfield Review", "Verified Change", "Brownfield Analysis", "CD+Tests", "TP Review", "Clean Implementation Review", "Clean Review", "CR", "Code Review"]);
+export const closeoutArtefacts = new Set(["OR"]);
+
+export function resolvedArtefactFile(targetDir, rawPath) {
+  const normalizedPath = String(rawPath ?? "").replace(/^`|`$/g, "").trim();
+  if (!normalizedPath || isAbsolute(normalizedPath) || normalizedPath.includes("<") || normalizedPath.includes(">")) return "";
+  const absolutePath = resolve(targetDir, normalizedPath);
+  if (relative(targetDir, absolutePath).startsWith("..") || !existsSync(absolutePath)) return "";
+  try {
+    const realPath = realpathSync(absolutePath);
+    return relative(realpathSync(targetDir), realPath).startsWith("..") || !statSync(realPath).isFile() ? "" : realPath;
+  } catch {
+    return "";
+  }
+}
+
+export function readArtefactHeading(targetDir, artefact) {
+  const artefactPath = resolvedArtefactFile(targetDir, artefact?.path);
+  if (!artefactPath) return "";
+  try {
+    return readFileSync(artefactPath, "utf8").match(/^#\s+(.+)$/m)?.[1]?.trim() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+export function readRunState(targetDir, selection = {}) {
+  let runPath = join(".agdf", "control", "AGDF_RUN.md");
+  const canonicalRoot = join(targetDir, ".agdf", "control", "runs");
+  let resolutionError;
+  let candidateRuns = [];
+  if (existsSync(canonicalRoot)) {
+    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 (resolutionError.startsWith("AGDF_ACTIVE_RUN_AMBIGUOUS")) {
+        const active = resolveRuns(targetDir, { allActive: true }).runs.map((run) => {
+          const controlState = parseControlState(run.content, {
+            userGates: userGateOrder,
+            internalSteps: [...internalStepArtefacts],
+            closeoutArtefacts: [...closeoutArtefacts],
+          });
+          return {
+            ...run,
+            control_state: controlState,
+            current_artefact_heading: readArtefactHeading(targetDir, controlState.artefacts.get(controlState.current_gate)),
+            ur_heading: readArtefactHeading(targetDir, controlState.artefacts.get("UR")),
+          };
+        });
+        candidateRuns = buildRunCandidates(active);
+      }
+    }
+  }
+  if (resolutionError || !existsSync(join(targetDir, runPath))) {
+    return {
+      path: runPath,
+      content: "",
+      current_gate: "",
+      next_allowed_action: "",
+      approvals: new Map(),
+      artefacts: new Map(),
+      evidence_refs: [],
+      artefact_chain: [],
+      mode_slice_decision: {},
+      missing_evidence: [],
+      risks: [],
+      context_graph: {},
+      quality_outlook: "",
+      source_scope: {},
+      memory: {},
+      candidate_runs: candidateRuns,
+      resolution_error: resolutionError,
+    };
+  }
+
+  const content = readTargetFile(targetDir, runPath);
+  const parsed = parseControlState(content, {
+    userGates: userGateOrder,
+    internalSteps: [...internalStepArtefacts],
+    closeoutArtefacts: [...closeoutArtefacts],
+  });
+
+  return {
+    path: runPath,
+    content,
+    ...parsed,
+  };
+}
+
+export function gateApprovalStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return "not_applicable";
+  return runState.approvals.get(gate)?.status ?? "";
+}
+
+export function gateArtefactStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return { status: "not_applicable", path: "" };
+  return runState.artefacts.get(gate) ?? { status: "", path: "" };
+}
+
+export function isDurableGateArtefactSatisfied(runState, gate) {
+  if (!durableGateArtefacts.has(gate)) return true;
+  const artefact = gateArtefactStatus(runState, gate);
+  if (!artefact.path || isPlaceholderValue(artefact.path)) return false;
+  if (gate === "QA") return artefact.status === "pass" || artefact.status === "passed";
+  return artefact.status === "approved";
+}
+
+export function expectedDurableArtefactStatuses(gate) {
+  return gate === "QA" ? ["pass", "passed"] : ["approved"];
+}
+
+export function describeDurableArtefactStatuses(gate) {
+  return expectedDurableArtefactStatuses(gate).map((status) => `\`${status}\``).join(" or ");
+}
+
+export function analyzeDurableGateArtefactConsistency(runState) {
+  const findings = [];
+
+  for (const gate of durableGateArtefacts) {
+    if (gateApprovalStatus(runState, gate) !== "approved") continue;
+
+    const artefact = gateArtefactStatus(runState, gate);
+    if (!artefact.path || isPlaceholderValue(artefact.path) || !artefact.status) continue;
+
+    const expectedStatuses = expectedDurableArtefactStatuses(gate);
+    if (expectedStatuses.includes(artefact.status)) continue;
+
+    findings.push({
+      severity: "revise",
+      code: "AGDF_GATE_ARTEFACT_STATUS_INCONSISTENT",
+      message: `${gate} approval is recorded, but the durable artefact row uses status \`${artefact.status}\`; expected ${describeDurableArtefactStatuses(gate)}.`,
+      path: runState.path,
+      next_step: `Update the ${gate} artefact row in the selected RUN_STATE.md to use the gate-specific durable status vocabulary.`,
+    });
+  }
+
+  return findings;
+}
+
+export function analyzeArtefactRoleConsistency(targetDir, runState) {
+  const findings = [];
+  for (const [type, artefact] of runState.artefacts) {
+    if (artefact.path_format === "invalid") {
+      findings.push({
+        severity: "block",
+        code: "AGDF_ARTEFACT_PATH_FORMAT_INVALID",
+        message: `${type} uses an invalid artefact path cell (${artefact.path_reason}).`,
+        path: runState.path,
+        next_step: "Use a plain repository-relative path or one complete Markdown code span.",
+      });
+    } else if (artefact.path && !isSafeRepoRelativePath(artefact.path)) {
+      findings.push({
+        severity: "block",
+        code: "AGDF_ARTEFACT_PATH_INVALID",
+        message: `${type} must use a normalized repository-relative artefact path.`,
+        path: runState.path,
+        next_step: "Remove absolute, traversal, unsupported-backslash or otherwise non-normalized path text.",
+      });
+    }
+  }
+  const rolesByPath = new Map();
+  for (const [type, artefact] of runState.artefacts) {
+    if (!artefact.path) continue;
+    rolesByPath.set(artefact.path, [...(rolesByPath.get(artefact.path) ?? []), type]);
+  }
+  for (const [path, roles] of rolesByPath) {
+    if (roles.length < 2) continue;
+    const allowedRoles = new Set(["Brownfield Review", "Verified Change", "OR"]);
+    if (modeSliceDecision(runState) !== "verified_change" || roles.some((role) => !allowedRoles.has(role))) {
+      findings.push({ severity: "block", code: "AGDF_ARTEFACT_ROLE_ALIAS_INVALID", message: `Artefact path is reused across incompatible roles: ${roles.join(", ")}.`, path, next_step: "Use distinct artefacts or a lifecycle-consistent Verified Change compact record." });
+      continue;
+    }
+    const record = readVerifiedChangeRecord(targetDir, runState);
+    if (record.status !== "present") continue;
+    const recordStatus = cleanStatusCell(extractField(record.content, "status"));
+    const brownfieldComplete = extractField(record.content, "decision") === "verified_change" && filled(extractField(record.content, "scope_reason")) && filled(extractField(record.content, "evidence"));
+    const miniCloseoutComplete = ["delivered", "intentionally_not_delivered", "residual_risk", "next_step"].every((field) => filled(extractField(record.content, field)));
+    if (roles.includes("Brownfield Review") && (runState.artefacts.get("Brownfield Review")?.status !== "done" || !brownfieldComplete)) findings.push({ severity: "block", code: "AGDF_VERIFIED_CHANGE_BROWNFIELD_ROLE_INVALID", message: "Consolidated Brownfield Review role is incomplete.", path, next_step: "Complete Brownfield Selection before eligibility." });
+    if (roles.includes("Verified Change") && runState.artefacts.get("Verified Change")?.status !== recordStatus) findings.push({ severity: "block", code: "AGDF_VERIFIED_CHANGE_ROLE_STATUS_MISMATCH", message: "Verified Change artefact row status does not match the compact record.", path, next_step: "Align the run-state row and record status." });
+    if (roles.includes("OR") && runState.artefacts.get("OR")?.status === "done" && (recordStatus !== "executed" || !miniCloseoutComplete)) findings.push({ severity: "block", code: "AGDF_VERIFIED_CHANGE_OR_ROLE_INVALID", message: "Consolidated OR is complete before execution and Mini-Closeout evidence are complete.", path, next_step: "Complete execution and Mini-Closeout evidence before marking OR done." });
+  }
+  return findings;
+}
+
+export function isInternalStepSatisfied(runState, step) {
+  const artefact = runState.artefacts.get(step);
+  if (!artefact) return false;
+  if (artefact.status === "done") return true;
+  return artefact.status === "not_applicable"
+    && (step === "Brownfield Review" || step === "Brownfield Analysis");
+}
+
+export 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;
+}
+

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-evaluation/shared.js

@@ -0,0 +1,345 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+
+export function cleanStatusCell(value) {
+  return (value ?? "").replace(/\x60/g, "").trim();
+}
+
+export function readTargetFile(targetDir, relativePath) {
+  return readFileSync(join(targetDir, relativePath), "utf8");
+}
+
+export function addFinding(findings, severity, code, message, path, nextStep) {
+  findings.push({
+    severity,
+    code,
+    message,
+    path,
+    next_step: nextStep,
+  });
+}
+
+export 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("`")));
+}
+
+export 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;
+    });
+}
+
+const compactBacklogHeaders = ["priority", "key", "work item", "status", "artefacts", "current spec", "next step"];
+const legacyBacklogHeaders = ["prio", "key", "title", "status", "ur", "brownfield review", "prd", "sd", "tp", "qa", "or", "current spec", "notes"];
+const backlogStatusLabels = new Map([
+  ["needs ur", "needs_ur"],
+  ["awaiting brownfield review", "awaiting_brownfield_review"],
+  ["awaiting prd", "awaiting_prd"],
+  ["awaiting prd approval", "awaiting_prd_approval"],
+  ["awaiting sd", "awaiting_sd"],
+  ["awaiting sd approval", "awaiting_sd_approval"],
+  ["awaiting tp", "awaiting_tp"],
+  ["awaiting tp approval", "awaiting_tp_approval"],
+  ["in progress", "in_progress"],
+  ["blocked", "blocked"],
+  ["awaiting qa", "awaiting_qa"],
+  ["awaiting uat", "awaiting_uat"],
+  ["awaiting or", "awaiting_or"],
+  ["completed", "completed"],
+  ["superseded", "superseded"],
+  ["abandoned", "abandoned"],
+]);
+const backlogArtefactLabels = new Map([
+  ["ur", "ur"],
+  ["brownfield", "brownfield_review"],
+  ["prd", "prd"],
+  ["sd", "sd"],
+  ["tp", "tp"],
+  ["qa", "qa"],
+  ["or", "or"],
+]);
+const backlogScopeLabels = new Map([
+  ["framework-maintenance", "framework_maintenance"],
+  ["external-delivery", "external_delivery"],
+]);
+
+export function normalizeBacklogHeader(value) {
+  return value.replace(/`/g, "").trim().toLowerCase();
+}
+
+export function markdownLink(value) {
+  const match = value.trim().match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+  return match ? { label: match[1].trim(), target: match[2].trim() } : null;
+}
+
+export function resolvedBacklogLinkTarget(target) {
+  if (!target
+    || target.startsWith("/")
+    || target.includes("\\")
+    || /^[a-z][a-z0-9+.-]*:/i.test(target)) {
+    return null;
+  }
+  const resolved = posix.normalize(posix.join(".agdf/control", target));
+  if (resolved === ".." || resolved.startsWith("../")) return null;
+  return resolved;
+}
+
+export function normalizedBacklogLinkTarget(value, findings, backlogPath, label) {
+  const link = markdownLink(value);
+  if (!link) return value.trim();
+  const resolved = resolvedBacklogLinkTarget(link.target);
+  if (!resolved) {
+    if (findings) {
+      addFinding(
+        findings,
+        "revise",
+        "AGDF_BACKLOG_LINK_TARGET_INVALID",
+        `Backlog ${label} link must be relative to MASTER_BACKLOG.md: ${link.target || "<empty>"}.`,
+        backlogPath,
+        "Use a document-relative artefact target such as artefacts/<key>/UR.md.",
+      );
+    }
+    return link.target;
+  }
+  return resolved;
+}
+
+export function normalizeBacklogStatus(value, findings, backlogPath) {
+  const cleaned = cleanStatusCell(value ?? "");
+  const lookup = cleaned.replaceAll("_", " ").toLowerCase();
+  const normalized = backlogStatusLabels.get(lookup);
+  if (normalized) return normalized;
+  if (/^[a-z][a-z0-9_]*$/.test(cleaned)) return cleaned;
+  if (findings && filled(cleaned)) {
+    addFinding(
+      findings,
+      "revise",
+      "AGDF_BACKLOG_STATUS_UNKNOWN",
+      `MASTER_BACKLOG.md uses an unknown human status label: ${cleaned}.`,
+      backlogPath,
+      "Use a documented human status label or a supported legacy snake_case value.",
+    );
+  }
+  return cleaned;
+}
+
+export 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;
+}
+
+export function emptyBacklogPointer() {
+  return {
+    prio: "",
+    key: "",
+    title: "",
+    scope: "",
+    status: "",
+    ur: "",
+    brownfield_review: "",
+    prd: "",
+    sd: "",
+    tp: "",
+    qa: "",
+    or: "",
+    current_spec: "",
+    notes: "",
+  };
+}
+
+export function parseCompactArtefacts(value, pointer, findings, backlogPath) {
+  if (!filled(value)) return;
+  const seen = new Set();
+  for (const entry of value.split(/\s+·\s+/)) {
+    const link = markdownLink(entry);
+    if (!link) {
+      if (findings) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_BACKLOG_ARTEFACT_LINK_INVALID",
+          `Compact Artefacts entry is not a Markdown link: ${entry}.`,
+          backlogPath,
+          "Use [UR](artefacts/<key>/UR.md) style links separated by a middle dot.",
+        );
+      }
+      continue;
+    }
+    const field = backlogArtefactLabels.get(link.label.toLowerCase());
+    if (!field) {
+      if (findings) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN",
+          `Compact Artefacts uses an unknown label: ${link.label}.`,
+          backlogPath,
+          "Use UR, Brownfield, PRD, SD, TP, QA or OR.",
+        );
+      }
+      continue;
+    }
+    if (seen.has(field)) {
+      if (findings) {
+        addFinding(
+          findings,
+          "revise",
+          "AGDF_BACKLOG_ARTEFACT_LABEL_DUPLICATE",
+          `Compact Artefacts repeats the ${link.label} link.`,
+          backlogPath,
+          "Keep exactly one link per artefact type.",
+        );
+      }
+      continue;
+    }
+    seen.add(field);
+    pointer[field] = normalizedBacklogLinkTarget(entry, findings, backlogPath, link.label);
+  }
+}
+
+export function parseBacklogSection(section, findings = null, backlogPath = ".agdf/control/MASTER_BACKLOG.md") {
+  const rows = tableRows(section);
+  if (rows.length === 0) return [];
+  const headers = rows[0].map(normalizeBacklogHeader);
+  const layout = headers.join("|") === compactBacklogHeaders.join("|")
+    ? "compact"
+    : headers.join("|") === legacyBacklogHeaders.join("|")
+      ? "legacy"
+      : "unknown";
+
+  if (layout === "unknown") {
+    if (findings) {
+      addFinding(
+        findings,
+        "revise",
+        "AGDF_BACKLOG_LAYOUT_UNKNOWN",
+        `MASTER_BACKLOG.md uses an unsupported table layout: ${headers.join(", ")}.`,
+        backlogPath,
+        "Use the canonical compact layout or the supported legacy 13-column layout.",
+      );
+    }
+    return [];
+  }
+
+  return rows.slice(1)
+    .filter((cells) => cells.some((cell) => filled(cell)))
+    .map((cells) => {
+      const pointer = emptyBacklogPointer();
+      if (layout === "legacy") {
+        [
+          pointer.prio,
+          pointer.key,
+          pointer.title,
+          pointer.status,
+          pointer.ur,
+          pointer.brownfield_review,
+          pointer.prd,
+          pointer.sd,
+          pointer.tp,
+          pointer.qa,
+          pointer.or,
+          pointer.current_spec,
+          pointer.notes,
+        ] = cells.map((cell) => cell ?? "");
+        pointer.status = normalizeBacklogStatus(pointer.status, findings, backlogPath);
+        return pointer;
+      }
+
+      pointer.prio = cells[0] ?? "";
+      pointer.key = cleanStatusCell(cells[1] ?? "");
+      pointer.title = cells[2] ?? "";
+      pointer.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");
+      pointer.notes = cells[6] ?? "";
+      return pointer;
+    });
+}
+
+export function hasFilledTableRow(content, firstCellPattern) {
+  return tableRows(content)
+    .filter((cells) => firstCellPattern.test(cells[0] ?? ""))
+    .some((cells) => cells.slice(1).some((cell) => cell && !cell.startsWith("`")));
+}
+
+export function isPlaceholderValue(value) {
+  return !value || (value.startsWith("`") && value.includes("|"));
+}
+
+export 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);
+    });
+}
+
+export function allowNoActiveRuns(targetDir) {
+  const configPath = join(targetDir, ".agdf", "control", "config.json");
+  if (!existsSync(configPath)) return false;
+  try {
+    return JSON.parse(readFileSync(configPath, "utf8")).allow_no_active_runs === true;
+  } catch {
+    return false;
+  }
+}
+
+export function markdownSection(content, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return content.match(new RegExp(`(?:^|\\n)## ${escaped}\\s*\\n([\\s\\S]*?)(?:\\n## |\\n# |$)`))?.[1] ?? "";
+}
+
+export function filled(value) {
+  return Boolean(value && !isPlaceholderValue(value) && value.trim() !== "");
+}
+
+export function runSelectionRecovery(target) {
+  const directSelection = "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run";
+  return ["doctor", "delivery-map"].includes(target)
+    ? `${directSelection}, or use --all-active to evaluate every active run independently.`
+    : `${directSelection}.`;
+}
+
+export 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;
+}
+