create-agdf 0.14.1 → 0.14.3

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

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { isAbsolute, posix, relative, resolve } from "node:path";
+import { cleanStatusCell, isPlaceholderValue } from "./shared.js";
+
+export function extractField(content, field) {
+  const pattern = new RegExp(`^- ${field}:[^\\S\\r\\n]*(.*)$`, "m");
+  return content.match(pattern)?.[1]?.trim() ?? "";
+}
+
+export const verifiedChangeStatuses = new Set(["draft", "eligible", "executed", "escalated"]);
+export const verifiedChangeEscalationTargets = new Set(["structured_slice", "structured_delivery"]);
+
+export function parseVerifiedChangePathList(value) {
+  const cleaned = cleanStatusCell(value ?? "");
+  if (!cleaned || cleaned === "none") return [];
+  return cleaned.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+export function isSafeRepoRelativePath(value) {
+  if (!value || value === "none" || value.startsWith("/") || value.includes("\\")) return false;
+  const normalized = posix.normalize(value);
+  return normalized !== "." && normalized !== ".." && !normalized.startsWith("../") && normalized === value;
+}
+
+export function gitPathList(targetDir, args) {
+  try {
+    return execFileSync("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .split("\n")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+export function gitValue(targetDir, args) {
+  try {
+    return execFileSync("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function readVerifiedChangeRecord(targetDir, runState) {
+  const artefact = runState.artefacts.get("Verified Change");
+  if (!artefact?.path || isPlaceholderValue(artefact.path)) return { status: "missing", path: "", content: "" };
+  if (!isSafeRepoRelativePath(artefact.path)) return { status: "invalid", path: artefact.path, content: "", error: "record_path_invalid" };
+  const absolutePath = resolve(targetDir, artefact.path);
+  const relativePath = relative(resolve(targetDir), absolutePath);
+  if (isAbsolute(relativePath) || relativePath === ".." || relativePath.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || !existsSync(absolutePath)) {
+    return { status: "missing", path: artefact.path, content: "", error: "record_missing" };
+  }
+  return { status: "present", path: artefact.path, content: readFileSync(absolutePath, "utf8") };
+}
+
+export function evaluateVerifiedChange(targetDir, runState) {
+  const record = readVerifiedChangeRecord(targetDir, runState);
+  const findings = [];
+  const add = (code, message, nextStep, severity = "revise") => findings.push({
+    severity,
+    code,
+    message,
+    path: record.path || runState.path,
+    next_step: nextStep,
+  });
+
+  if (record.status === "missing") {
+    return { status: "missing", record, findings };
+  }
+  if (record.status === "invalid") {
+    add("AGDF_VERIFIED_CHANGE_RECORD_PATH_INVALID", "Verified Change record path must be a repository-relative path inside the target repository.", "Link a stable repository-relative VERIFIED_CHANGE.md artefact from the selected run state.", "block");
+    return { status: "invalid", record, findings };
+  }
+
+  const status = cleanStatusCell(extractField(record.content, "status"));
+  const relatedUr = cleanStatusCell(extractField(record.content, "related_ur"));
+  const escalationTarget = cleanStatusCell(extractField(record.content, "escalation_target"));
+  const canonicalOwner = cleanStatusCell(extractField(record.content, "canonical_owner"));
+  const sourcePaths = parseVerifiedChangePathList(extractField(record.content, "allowed_source_paths"));
+  const derivedPaths = parseVerifiedChangePathList(extractField(record.content, "allowed_derived_paths"));
+  const prohibitedImpacts = cleanStatusCell(extractField(record.content, "prohibited_impacts"));
+  const propagationCommand = extractField(record.content, "propagation_command");
+  const validationCommands = extractField(record.content, "validation_commands");
+  const baselineTracked = parseVerifiedChangePathList(extractField(record.content, "baseline_tracked_paths"));
+  const baselineUntracked = parseVerifiedChangePathList(extractField(record.content, "baseline_untracked_paths"));
+  const baselineCommit = cleanStatusCell(extractField(record.content, "baseline_commit"));
+  const executionChangedPaths = parseVerifiedChangePathList(extractField(record.content, "execution_changed_paths"));
+  const executionScopeStatus = cleanStatusCell(extractField(record.content, "execution_scope_status"));
+  const validationStatus = cleanStatusCell(extractField(record.content, "validation_status"));
+  const propagationStatus = cleanStatusCell(extractField(record.content, "propagation_status"));
+  const urArtefact = runState.artefacts.get("UR");
+  const lifecycle = extractField(runState.content, "lifecycle") || "active";
+  const runId = extractField(runState.content, "run_id") || "";
+
+  if (!verifiedChangeStatuses.has(status)) add("AGDF_VERIFIED_CHANGE_STATUS_INVALID", "Verified Change record must use status draft, eligible, executed or escalated.", "Set a supported record status or escalate to the declared structured target.");
+  if (!isSafeRepoRelativePath(relatedUr) || relatedUr !== urArtefact?.path) add("AGDF_VERIFIED_CHANGE_RELATED_UR_INVALID", "Verified Change record must link exactly to the selected run's repository-relative UR artefact.", "Set related_ur to the selected run's durable UR artefact path.");
+  if (!verifiedChangeEscalationTargets.has(escalationTarget)) add("AGDF_VERIFIED_CHANGE_ESCALATION_INVALID", "Verified Change record must declare structured_slice or structured_delivery as its escalation target.", "Record the Brownfield-selected structured escalation target.");
+  if (!canonicalOwner || canonicalOwner.includes(",") || !isSafeRepoRelativePath(canonicalOwner)) add("AGDF_VERIFIED_CHANGE_OWNER_INVALID", "Verified Change requires exactly one repository-relative canonical_owner.", "Name one canonical owner path; otherwise escalate.");
+  if (sourcePaths.length === 0 || sourcePaths.some((path) => !isSafeRepoRelativePath(path))) add("AGDF_VERIFIED_CHANGE_SOURCE_PATHS_INVALID", "Verified Change requires non-empty normalized allowed_source_paths.", "Declare a bounded comma-separated source path list; otherwise escalate.");
+  if (derivedPaths.some((path) => !isSafeRepoRelativePath(path))) add("AGDF_VERIFIED_CHANGE_DERIVED_PATHS_INVALID", "Verified Change derived paths must be normalized repository-relative paths or none.", "Correct the derived path list or escalate.");
+  if (prohibitedImpacts !== "none") add("AGDF_VERIFIED_CHANGE_IMPACTS_INVALID", "Verified Change must declare prohibited_impacts: none after checking gates, permissions, security, persistence, architecture, external API, CLI and release behavior.", "Use the structured path when any prohibited impact applies.");
+  if (!validationCommands || validationCommands === "none") add("AGDF_VERIFIED_CHANGE_VALIDATION_MISSING", "Verified Change requires at least one deterministic validation command.", "Record a deterministic acceptance or consistency check, or escalate.");
+  if (derivedPaths.length > 0 && (!propagationCommand || propagationCommand === "none")) add("AGDF_VERIFIED_CHANGE_PROPAGATION_MISSING", "Derived paths require a deterministic propagation command.", "Record the propagation command or escalate.");
+  if (!extractField(record.content, "baseline_tracked_paths") || !extractField(record.content, "baseline_untracked_paths")) add("AGDF_VERIFIED_CHANGE_BASELINE_MISSING", "Verified Change requires both tracked and untracked baseline path fields, using none when empty.", "Capture the worktree baseline before marking the record eligible.");
+  if (["eligible", "executed"].includes(status) && !/^[0-9a-f]{40,64}$/i.test(baselineCommit)) add("AGDF_VERIFIED_CHANGE_BASELINE_COMMIT_INVALID", "Eligible or executed Verified Change requires a full Git baseline_commit.", "Capture the current full Git commit id before eligibility or escalate.");
+
+  if (["eligible", "executed"].includes(status) && lifecycle !== "completed" && /^[0-9a-f]{40,64}$/i.test(baselineCommit)) {
+    const currentHead = gitValue(targetDir, ["rev-parse", "HEAD"]);
+    if (!currentHead) {
+      add("AGDF_VERIFIED_CHANGE_BASELINE_COMMIT_UNAVAILABLE", "Active Verified Change requires a readable current Git HEAD for baseline identity validation.", "Restore Git repository access or use the structured path.", "block");
+    } else if (baselineCommit !== currentHead) {
+      add("AGDF_VERIFIED_CHANGE_BASELINE_COMMIT_MISMATCH", "Active Verified Change baseline_commit does not match the current Git HEAD.", "Recapture the baseline before eligibility or escalate; do not reuse a stale or fabricated baseline identity.", "block");
+    }
+  }
+
+  const allowedPaths = new Set([...sourcePaths, ...derivedPaths]);
+  const baselinePaths = new Set([...baselineTracked, ...baselineUntracked]);
+  const dirtyCandidate = [...allowedPaths].find((path) => baselinePaths.has(path));
+  if (dirtyCandidate) add("AGDF_VERIFIED_CHANGE_BASELINE_CANDIDATE_DIRTY", `Declared candidate path is already dirty at baseline: ${dirtyCandidate}.`, "Escalate or start from a clean candidate path; do not adopt pre-existing edits.", "block");
+
+  const permittedControlPaths = new Set([record.path, runState.path, ".agdf/control/MASTER_BACKLOG.md"]);
+  const runArtefactPrefix = `.agdf/control/artefacts/${runId}/`;
+  for (const artefact of runState.artefacts.values()) {
+    if (artefact.path_format === "invalid") continue;
+    if (isSafeRepoRelativePath(artefact.path) && artefact.path.startsWith(runArtefactPrefix)) permittedControlPaths.add(artefact.path);
+  }
+
+  if (!(lifecycle === "completed" && status === "executed")) {
+    const currentTracked = gitPathList(targetDir, ["diff", "HEAD", "--name-only"]);
+    const currentUntracked = gitPathList(targetDir, ["ls-files", "--others", "--exclude-standard"]);
+    if (currentTracked === null || currentUntracked === null) {
+      add("AGDF_VERIFIED_CHANGE_GIT_BASELINE_UNAVAILABLE", "Verified Change requires a readable Git worktree for scoped baseline validation.", "Use the structured path or restore Git worktree access.", "block");
+    } else {
+      const introduced = [...new Set([...currentTracked, ...currentUntracked])].filter((path) => !baselinePaths.has(path)).sort();
+      const unexpected = introduced.filter((path) => !allowedPaths.has(path) && !permittedControlPaths.has(path));
+      if (unexpected.length > 0) add("AGDF_VERIFIED_CHANGE_SCOPE_ESCAPE", `Verified Change introduced unlisted path(s): ${unexpected.join(", ")}.`, "Mark the record escalated and continue at the declared structured target.", "block");
+      if (status === "executed" && JSON.stringify(introduced) !== JSON.stringify([...executionChangedPaths].sort())) {
+        add("AGDF_VERIFIED_CHANGE_EXECUTION_SCOPE_MISMATCH", "Executed Verified Change execution_changed_paths must equal the post-baseline changed-path set.", "Record the exact changed paths or escalate.", "block");
+      }
+    }
+  } else {
+    const unsafeExecutionPath = executionChangedPaths.find((path) => !isSafeRepoRelativePath(path) || (!allowedPaths.has(path) && !permittedControlPaths.has(path)));
+    if (unsafeExecutionPath) add("AGDF_VERIFIED_CHANGE_EXECUTION_SCOPE_INVALID", `Recorded execution path is outside the eligible scope: ${unsafeExecutionPath}.`, "Correct the historical execution snapshot or escalate.", "block");
+  }
+
+  if (status === "executed") {
+    if (executionChangedPaths.length === 0 || !executionChangedPaths.some((path) => allowedPaths.has(path)) || executionScopeStatus !== "pass") add("AGDF_VERIFIED_CHANGE_EXECUTION_EVIDENCE_MISSING", "Executed Verified Change requires a non-empty execution_changed_paths set containing a declared source/derived path and execution_scope_status: pass.", "Record complete execution-scope evidence or escalate.");
+    if (validationStatus !== "pass") add("AGDF_VERIFIED_CHANGE_VALIDATION_EVIDENCE_MISSING", "Executed Verified Change requires validation_status: pass.", "Record passing deterministic validation evidence or escalate.");
+    if (derivedPaths.length > 0 && propagationStatus !== "pass") add("AGDF_VERIFIED_CHANGE_PROPAGATION_EVIDENCE_MISSING", "Executed Verified Change with derived paths requires propagation_status: pass.", "Record successful propagation evidence or escalate.");
+  }
+
+  if (status === "escalated") return { status: "escalated", record, escalation_target: escalationTarget, findings };
+  if (findings.length > 0) return { status: "invalid", record, escalation_target: escalationTarget, findings };
+  return { status, record, escalation_target: escalationTarget, findings };
+}

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

@@ -0,0 +1,18 @@
+const STATUS_RANK = { pass: 0, warn: 1, revise: 2, block: 3 };
+
+export function aggregate(results, { allowNoActiveRuns = false } = {}) {
+  const runs = [...results].sort((left, right) =>
+    left.run_id.localeCompare(right.run_id),
+  );
+  const status = runs.length
+    ? runs.reduce(
+        (current, run) =>
+          STATUS_RANK[run.status] > STATUS_RANK[current] ? run.status : current,
+        "pass",
+      )
+    : allowNoActiveRuns
+      ? "pass"
+      : "revise";
+
+  return { status, runs };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-state/gate-approval-validator.js

@@ -0,0 +1,49 @@
+import { normalizeInteractionOutcome } from "../interaction-presentation.js";
+
+export function validateGateApprovalResponse({
+  response,
+  responseOutcome,
+  responseOrigin,
+  expectedApproval,
+  expectedRunId,
+  currentRunId,
+  expectedGate,
+  currentGate,
+  expectedRevisionId,
+  currentRevisionId,
+  durableArtefactReady,
+  timedOut = false,
+  noResponse = false,
+}) {
+  const checks = [
+    [responseOrigin === "deliberate_user_input", "non_deliberate_response"],
+    [expectedApproval === `Approval: ${expectedGate}`, "approval_formula_mismatch"],
+    [Boolean(expectedRunId) && expectedRunId === currentRunId, "changed_or_wrong_run"],
+    [Boolean(expectedGate) && expectedGate === currentGate, "changed_or_wrong_gate"],
+    [Boolean(expectedRevisionId) && expectedRevisionId === currentRevisionId, "stale_revision"],
+    [durableArtefactReady === true, "durable_artefact_not_ready"],
+  ];
+
+  const failed = checks.find(([accepted]) => !accepted);
+  if (failed) return { accepted: false, reason: failed[1] };
+
+  const outcomeCandidate = responseOutcome && responseOutcome !== "approve" ? responseOutcome : response;
+  const outcome = normalizeInteractionOutcome(outcomeCandidate, {
+    expectedApproval,
+    timedOut,
+    noResponse,
+  });
+  const rejectionReasons = {
+    revise: "revision_requested",
+    decline: "declined",
+    cancel: "cancelled",
+    no_response: "no_response",
+    timeout: "timed_out",
+    empty: "empty_response",
+    invalid: "wrong_or_non_approval_response",
+    stale: "stale_response",
+  };
+  return outcome === "approve"
+    ? { accepted: true, reason: "accepted" }
+    : { accepted: false, reason: rejectionReasons[outcome] ?? "wrong_or_non_approval_response" };
+}

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

@@ -0,0 +1,7 @@
+export * from "./run-state-parser.js";
+export * from "./run-state-repository.js";
+export * from "./run-state-resolver.js";
+export * from "./run-state-writer.js";
+export * from "./legacy-migration.js";
+export * from "./aggregate.js";
+export * from "./gate-approval-validator.js";

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-state/legacy-migration.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmdirSync, unlinkSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  discoverRuns,
+  renderRunState,
+  runPath,
+} from "./run-state-repository.js";
+import {
+  parseRunState,
+  RUN_ID_PATTERN,
+  scalarFields,
+  semanticBody,
+  semanticFingerprint,
+} from "./run-state-parser.js";
+import { atomicWrite } from "./run-state-writer.js";
+export function migrateLegacy(root, requested, io = {}) {
+  const writeCanonical = io.atomicWrite ?? atomicWrite;
+  const readCanonical = io.readFile ?? readFileSync;
+  const lp = join(root, ".agdf", "control", "AGDF_RUN.md");
+  if (!existsSync(lp)) throw Error("AGDF_LEGACY_RUN_MISSING");
+  const legacy = readFileSync(lp, "utf8");
+  if (legacy.startsWith("<!-- AGDF LEGACY PROJECTION"))
+    throw Error("AGDF_LEGACY_ALREADY_PROJECTED");
+  if (!legacy.startsWith("# AGDF Run State") || !semanticBody(legacy))
+    throw Error("AGDF_LEGACY_RUN_INVALID");
+  const id = requested || scalarFields(legacy).values.get("run_id");
+  if (!RUN_ID_PATTERN.test(id ?? "")) throw Error("AGDF_RUN_ID_INVALID");
+  const legacyMeta = Object.fromEntries(scalarFields(legacy).values);
+  const dest = runPath(root, id),
+    next = renderRunState(id, semanticBody(legacy), legacyMeta);
+  if (existsSync(dest)) {
+    if (
+      semanticFingerprint(readFileSync(dest, "utf8")) ===
+      semanticFingerprint(next)
+    )
+      return { status: "already_migrated", path: dest };
+    throw Error("AGDF_RUN_COLLISION");
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  try {
+    writeCanonical(dest, next);
+    const persisted = readCanonical(dest, "utf8"),
+      parsed = parseRunState(persisted, id);
+    if (
+      !parsed.valid ||
+      semanticFingerprint(persisted) !== semanticFingerprint(next)
+    ) throw Error("AGDF_MIGRATION_VERIFICATION_FAILED");
+  } catch (error) {
+    if (existsSync(dest)) unlinkSync(dest);
+    try {
+      rmdirSync(dirname(dest));
+    } catch (cleanupError) {
+      if (!["ENOENT", "ENOTEMPTY"].includes(cleanupError.code)) throw cleanupError;
+    }
+    throw error;
+  }
+  return { status: "migrated", path: dest };
+}
+export function renderLegacyProjection(path, root = process.cwd()) {
+  const content = readFileSync(path, "utf8"),
+    parsed = parseRunState(content),
+    digest = createHash("sha256").update(content).digest("hex");
+  if (!parsed.valid) throw Error("AGDF_RUN_NOT_SELECTABLE");
+  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), "../..")));
+}
+export function verifyLegacyProjection(root) {
+  const path = join(root, ".agdf", "control", "AGDF_RUN.md");
+  if (!existsSync(path)) return { status: "absent" };
+  const p = readFileSync(path, "utf8"),
+    source = p.match(/canonical_source:\s*(.*?)\s*-->/)?.[1],
+    runId = p.match(/<!-- run_id:\s*(.*?)\s*-->/)?.[1],
+    digest = p.match(/sha256:\s*([0-9a-f]{64})/)?.[1],
+    projectedStart = p.indexOf("# AGDF Run State"),
+    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.replaceAll("\\", "/")),
+    rel = relative(resolve(root), target),
+    expected = relative(resolve(root), resolve(runPath(root, runId)));
+  if (rel.startsWith("..") || !rel || rel !== expected || !existsSync(target))
+    return { status: "projection_source_invalid" };
+  const canonical = readFileSync(target, "utf8"),
+    canonicalDigest = createHash("sha256").update(canonical).digest("hex");
+  return {
+    status:
+      canonicalDigest === digest && projected === canonical
+        ? "valid"
+        : "legacy_projection_drift",
+  };
+}

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

@@ -0,0 +1,265 @@
+export const RUN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+export const LIFECYCLES = new Set([
+  "active",
+  "completed",
+  "superseded",
+  "abandoned",
+]);
+export function scalarFields(content) {
+  const values = new Map(),
+    duplicates = [];
+  const runMeta = content.match(/(?:^|\n)## Run Meta\s*\n([\s\S]*?)(?=\n## |$)/)?.[1] ?? "";
+  for (const [, k, v] of runMeta.matchAll(/^- ([a-z_]+):\s*(.*?)\s*$/gm)) {
+    if (values.has(k)) duplicates.push(k);
+    else values.set(k, v.replace(/^`|`$/g, ""));
+  }
+  return { values, duplicates };
+}
+export function parseRunState(content, expected) {
+  const { values, duplicates } = scalarFields(content),
+    findings = duplicates.map((field) => ({
+      code: "AGDF_RUN_FIELD_DUPLICATE",
+      field,
+    })),
+    id = values.get("run_id") ?? "";
+  if (content.split(/\r?\n/).some((line) => line.trimStart().startsWith("|") && !line.trimEnd().endsWith("|"))) {
+    findings.push({ code: "AGDF_RUN_TABLE_INVALID" });
+  }
+  if (!RUN_ID_PATTERN.test(id)) findings.push({ code: "AGDF_RUN_ID_INVALID" });
+  if (expected && id !== expected)
+    findings.push({ code: "AGDF_RUN_PATH_MISMATCH" });
+  if (values.get("control_state_version") !== "2")
+    findings.push({ code: "AGDF_RUN_VERSION_UNSUPPORTED" });
+  if (!LIFECYCLES.has(values.get("lifecycle")))
+    findings.push({ code: "AGDF_RUN_LIFECYCLE_INVALID" });
+  if (!/^[1-9]\d*$/.test(values.get("revision") ?? ""))
+    findings.push({ code: "AGDF_RUN_REVISION_INVALID" });
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(values.get("revision_id") ?? ""))
+    findings.push({ code: "AGDF_RUN_REVISION_ID_INVALID" });
+  return {
+    content,
+    meta: Object.fromEntries(values),
+    findings,
+    valid: !findings.length,
+  };
+}
+export function semanticBody(content) {
+  return content
+    .replace(/^# AGDF Run State\s*/m, "")
+    .replace(/## Run Meta[\s\S]*?(?=\n## )/, "")
+    .trim();
+}
+export function semanticFingerprint(content) {
+  return semanticBody(content).replace(/\s+/g, " ");
+}
+
+function section(c, h) {
+  const e = h.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return (
+    c.match(
+      new RegExp(`(?:^|\\n)## ${e}\\s*\\n([\\s\\S]*?)(?:\\n## |\\n# |$)`),
+    )?.[1] ?? ""
+  );
+}
+function rows(s) {
+  return s
+    .split(/\r?\n/)
+    .filter((l) => l.trim().startsWith("|"))
+    .map((l) =>
+      l
+        .split("|")
+        .slice(1, -1)
+        .map((x) => x.trim()),
+    )
+    .filter((r) => !r.every((x) => /^[-:]+$/.test(x)));
+}
+function clean(v = "") {
+  return v.replace(/^`|`$/g, "").trim();
+}
+export function parseArtefactPathCell(value = "") {
+  const raw = String(value).trim();
+  if (!raw) return { raw, path: "", format: "plain", reason: "empty" };
+  const ticks = [...raw].filter((character) => character === "`").length;
+  if (ticks === 0) return { raw, path: raw, format: "plain", reason: "none" };
+  if (ticks === 2 && raw.startsWith("`") && raw.endsWith("`")) {
+    const path = raw.slice(1, -1).trim();
+    if (path && !path.includes("`")) return { raw, path, format: "code_span", reason: "none" };
+  }
+  return {
+    raw,
+    path: "",
+    format: "invalid",
+    reason: ticks === 1 || raw.startsWith("`") !== raw.endsWith("`")
+      ? "unmatched_delimiter"
+      : "embedded_delimiter",
+  };
+}
+function meaningful(v = "") {
+  return Boolean(v && !(v.startsWith("`") && v.includes("|")));
+}
+function field(c, k) {
+  return (
+    c.match(new RegExp(`^- ${k}:[^\\S\\r\\n]*(.*)$`, "m"))?.[1]?.trim() ?? ""
+  );
+}
+function sectionField(c, h, k) {
+  return field(section(c, h), k);
+}
+function sectionScalar(c, h, k) {
+  const body = section(c, h);
+  const escaped = k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const matches = [...body.matchAll(new RegExp(`^- ${escaped}:[^\\S\\r\\n]*(.*)$`, "gm"))];
+  return {
+    value: clean(matches[0]?.[1] ?? ""),
+    count: matches.length,
+  };
+}
+function dataRows(c, h, header) {
+  return rows(section(c, h)).filter(
+    (r) =>
+      r[0] !== header &&
+      (h === "Evidence" ? r.slice(0, 3).some(meaningful) : r.some(meaningful)),
+  );
+}
+export function parseControlState(
+  content,
+  { userGates = [], internalSteps = [], closeoutArtefacts = [] } = {},
+) {
+  const metaValues = scalarFields(content).values;
+  const approvals = new Map();
+  for (const h of ["Approvals", "Gate Checklist"])
+    for (const [g, s, e] of rows(section(content, h))) {
+      if (userGates.includes(g)) {
+        const status = clean(s);
+        approvals.set(g, {
+          status: g === "QA" && (status === "pass" || status === "passed") ? "approved" : status,
+          evidence: e ?? "",
+        });
+      }
+    }
+  const artefacts = new Map();
+  for (const [t, p, s, n] of rows(section(content, "Artefacts"))) {
+    if (userGates.includes(t) || internalSteps.includes(t) || closeoutArtefacts.includes(t)) {
+      const parsedPath = parseArtefactPathCell(p ?? "");
+      artefacts.set(t, {
+        path: parsedPath.path,
+        status: clean(s),
+        notes: n ?? "",
+        raw_path: parsedPath.raw,
+        path_format: parsedPath.format,
+        path_reason: parsedPath.reason,
+      });
+    }
+  }
+  const mapRows = (h, header, fn) => dataRows(content, h, header).map(fn);
+  const mode = section(content, "Mode/Slice Decision").trim()
+      ? "Mode/Slice Decision"
+      : "Mode / Slice Decision",
+    source = "Source And Scope State",
+    memory = "Knowledge Persistence Decision",
+    handoff = "Parent Reconciliation Handoff",
+    aggregation = "Programme Aggregation Readiness";
+  const disposition = sectionScalar(content, handoff, "parent_reconciliation_disposition");
+  const reconciliationNextAction = sectionScalar(content, handoff, "parent_reconciliation_next_action");
+  const acceptanceRef = sectionScalar(content, aggregation, "programme_acceptance_ref");
+  const aggregationEvidence = sectionScalar(content, aggregation, "programme_aggregation_evidence");
+  const aggregationMissingEvidence = sectionScalar(content, aggregation, "programme_aggregation_missing_evidence");
+  return {
+    run_id: clean(metaValues.get("run_id") ?? ""),
+    current_gate: field(content, "current_gate"),
+    next_allowed_action: field(content, "next_allowed_action"),
+    approvals,
+    artefacts,
+    evidence_refs: mapRows("Evidence", "Evidence", (r) => ({
+      evidence: r[0] ?? "",
+      source: r[1] ?? "",
+      covers: r[2] ?? "",
+      strength: clean(r[3]),
+    })),
+    artefact_chain: mapRows("Artefact Chain", "From", (r) => ({
+      from: r[0] ?? "",
+      relationship: clean(r[1]),
+      to: clean(r[2]),
+      evidence: r[3] ?? "",
+    })),
+    missing_evidence: mapRows("Missing Evidence", "Missing evidence", (r) => ({
+      missing_evidence: r[0] ?? "",
+      impact: clean(r[1]),
+      required_next_step: r[2] ?? "",
+    })),
+    risks: mapRows("Risks", "Risk", (r) => ({
+      risk: r[0] ?? "",
+      impact: clean(r[1]),
+      mitigation_or_owner: r[2] ?? "",
+    })),
+    context_graph: {
+      impact: clean(field(content, "context_graph_impact")),
+      refs: field(content, "context_graph_refs"),
+      required_action: clean(field(content, "context_graph_required_action")),
+      gate_effect: clean(field(content, "context_graph_gate_effect")),
+      evidence: field(content, "context_graph_evidence"),
+    },
+    quality_outlook: field(content, "quality_outlook"),
+    mode_slice_decision: {
+      decision: clean(sectionField(content, mode, "decision")),
+      required_next_gate: clean(
+        sectionField(content, mode, "required_next_gate"),
+      ),
+      scope_reason: sectionField(content, mode, "scope_reason"),
+      evidence: sectionField(content, mode, "evidence"),
+    },
+    source_scope: {
+      normative_instruction_source: sectionField(
+        content,
+        source,
+        "normative_instruction_source",
+      ),
+      multi_scope_state: clean(
+        sectionField(content, source, "multi_scope_state"),
+      ),
+      active_scope_evidence: sectionField(
+        content,
+        source,
+        "active_scope_evidence",
+      ),
+      competing_scope_lines: sectionField(
+        content,
+        source,
+        "competing_scope_lines",
+      ),
+      branch_workspace_evidence: sectionField(
+        content,
+        source,
+        "branch_workspace_evidence",
+      ),
+      branch_workspace_scope_effect: clean(
+        sectionField(content, source, "branch_workspace_scope_effect"),
+      ),
+    },
+    memory: {
+      target: clean(sectionField(content, memory, "memory_target")),
+      reason: sectionField(content, memory, "memory_reason"),
+      refs: sectionField(content, memory, "memory_refs"),
+    },
+    parent_reconciliation: {
+      present: Boolean(section(content, handoff).trim()),
+      disposition: disposition.value,
+      next_action: reconciliationNextAction.value,
+      field_counts: {
+        disposition: disposition.count,
+        next_action: reconciliationNextAction.count,
+      },
+    },
+    programme_aggregation: {
+      present: Boolean(section(content, aggregation).trim()),
+      acceptance_ref: acceptanceRef.value,
+      evidence: aggregationEvidence.value,
+      missing_evidence: aggregationMissingEvidence.value,
+      field_counts: {
+        acceptance_ref: acceptanceRef.count,
+        evidence: aggregationEvidence.count,
+        missing_evidence: aggregationMissingEvidence.count,
+      },
+    },
+  };
+}

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

@@ -0,0 +1,68 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { parseRunState, RUN_ID_PATTERN } from "./run-state-parser.js";
+export function runPath(root, id) {
+  if (!RUN_ID_PATTERN.test(id)) throw Error(`invalid run_id: ${id}`);
+  return join(root, ".agdf", "control", "runs", id, "RUN_STATE.md");
+}
+export function discoverRuns(root) {
+  const dir = join(root, ".agdf", "control", "runs");
+  if (!existsSync(dir)) return [];
+  const rootStats = lstatSync(dir);
+  if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
+    return [invalidRun("<repository>", dir)];
+  }
+  return readdirSync(dir)
+    .filter((x) => !x.startsWith("."))
+    .sort()
+    .map((id) => {
+      const d = join(dir, id),
+        path = join(d, "RUN_STATE.md");
+      const directoryStats = lstatSync(d);
+      if (
+        !RUN_ID_PATTERN.test(id) ||
+        directoryStats.isSymbolicLink() ||
+        !directoryStats.isDirectory() ||
+        !existsSync(path)
+      )
+        return invalidRun(id, path);
+
+      const stateStats = lstatSync(path);
+      if (stateStats.isSymbolicLink() || !stateStats.isFile()) {
+        return invalidRun(id, path);
+      }
+      return {
+        run_id: id,
+        path,
+        ...parseRunState(readFileSync(path, "utf8"), id),
+      };
+    });
+}
+
+function invalidRun(runId, path) {
+  return {
+    run_id: runId,
+    path,
+    valid: false,
+    findings: [{ code: "AGDF_RUN_PATH_INVALID", path }],
+  };
+}
+const DEFAULT_BODY = `## Objective\n\nDescribe the trustworthy outcome.\n\n## Current Control State\n\n| Question | Answer |\n|---|---|\n| What is known? | New run created. |\n| What is approved? | Nothing yet. |\n| What is missing? | Durable UR and exact approval. |\n| What is the next allowed action? | Draft the UR. |\n| What is explicitly forbidden right now? | Later artefacts and implementation. |\n\n## Evidence\n\n| Evidence | Source | Covers | Strength |\n|---|---|---|---|\n| Run creation | run-create | Control initialization | direct |\n\n## Closeout\n\n- next_allowed_action: Draft the UR.\n- quality_outlook: Establish evidence before later gates.\n`;
+export function renderRunState(id, body = DEFAULT_BODY, meta = {}) {
+  return `# AGDF Run State\n\n## Run Meta\n\n- control_state_version: 2\n- run_id: ${id}\n- lifecycle: ${meta.lifecycle ?? "active"}\n- revision: 1\n- revision_id: ${randomUUID()}\n- mode: ${meta.mode ?? "structured_delivery"}\n- current_gate: ${meta.current_gate ?? "UR"}\n- decision: ${meta.decision ?? "in_progress"}\n- owner: ${meta.owner ?? "agent"}\n\n${body}`;
+}
+export function createRun(root, id, body = "") {
+  const path = runPath(root, id);
+  if (existsSync(path)) throw Error("AGDF_RUN_COLLISION");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, renderRunState(id, body), { flag: "wx" });
+  return path;
+}