create-agdf 0.4.9 → 0.6.0

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

@@ -30,7 +30,8 @@ Do not add a separate `Quality outlook` line for pure Quick Tasks unless the tas
 ### Non-Normative Trivial Change Boundary
 
 A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
-the compact output shape above, and must not create, rewrite or expand any of `AGDF_RUN.md`'s core
+the compact output shape above, and must not create, rewrite or expand any selected canonical
+`RUN_STATE.md` core
 sections (Run Meta, Objective, Current Control State, Source And Scope State, Run Status Card,
 Approvals, Artefacts, Mode/Slice Decision, Artefact Chain, Evidence, Missing Evidence, Risks, Context
 Graph Impact, Knowledge Persistence Decision, Closeout):
@@ -91,6 +92,12 @@ Delivery Path Search is an optional read-only planning step for high-impact deci
 - Search output is evidence only. Canonical `gate-check` independently decides what may proceed.
 - The bounded first-release algorithm must not be labelled MCTS.
 - Surface adapters may translate transport and presentation, but must not fork scoring, search or gate semantics.
+- Optional AI-native candidate generation supplements the deterministic candidate baseline; it never replaces it.
+- Generated proposals are untrusted. The core must validate schema, exact canonical gate action, scope, duplicates and material diversity before evaluation.
+- Generation is opt-in and bounded to one call, five proposals, 30 seconds and five abstract cost units by default, within whole-run budgets.
+- External generation receives only bounded normalized control summaries and references, never secrets, full artefacts, raw prompts, hidden reasoning or source snapshots.
+- Generator status, provenance, accepted/rejected counts, separate budget use and typed failure must remain visible. Failure retains the deterministic baseline; automatic provider fallback is forbidden.
+- Codex and Claude Code may provide tool-enforced generator transports. Copilot, OpenCode and generic surfaces remain instruction-only without conforming evidence.
 
 The field names above are the stable machine-readable contract used by JSON
 reports and automation. Human-facing Markdown must present the same projection
@@ -201,9 +208,10 @@ OR is not mandatory for a pure explanation, read-only inspection, small review,
 When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
 
 A `quick_task` fully inside the Non-Normative Trivial Change Boundary above stays exempt from the full
-`AGDF_RUN.md` ceremony even when it is otherwise a relevant run. If `AGDF_RUN.md` currently reflects
-another active run, append exactly one line to that run's `Prior Run Pointers` section noting what
-changed and that it is unrelated; do not edit any other section or any other existing line.
+selected-run ceremony even when it is otherwise a relevant run. If a selected canonical
+`RUN_STATE.md` currently reflects another scope, append exactly one line to that run's
+`Prior Run Pointers` section noting what changed and that it is unrelated; do not edit any other
+section or any other existing line.
 
 ## Gate Rules
 
@@ -219,7 +227,7 @@ changed and that it is unrelated; do not edit any other section or any other exi
 - Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
 - `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
-- The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in `AGDF_RUN.md` or an equivalent linked control artefact.
+- The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in the selected canonical `RUN_STATE.md` or an equivalent linked control artefact.
 - `Approval: PRD` permits Solution Design drafting, not implementation.
 - `Approval: SD` permits Task/Test Plan drafting, not implementation.
 - `Approval: TP` permits implementation-preparation Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
@@ -321,10 +329,18 @@ Relevant-run closeout must reconcile Context Graph impact before presenting a cl
 
 ## Control Scaffold
 
+### Run-Scoped Control State
+
+Canonical mutable run state lives at `.agdf/control/runs/<run_id>/RUN_STATE.md`, one file per run.
+Repository-level discovery is derived; do not maintain a writable active-run dashboard. Select with
+`--run`, then `AGDF_RUN_ID`, or automatically only when exactly one run is active. Ambiguity fails
+closed. Legacy `AGDF_RUN.md` is migration input or an explicitly rendered non-authoritative projection,
+never a second writable owner. Read-only commands must not migrate state.
+
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
 
 - `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
-- `AGDF_RUN.md` is the current run dashboard.
+- `.agdf/control/runs/<run_id>/RUN_STATE.md` is the canonical current-run dashboard; legacy `AGDF_RUN.md` is migration input or an explicit non-authoritative projection.
 - `MASTER_BACKLOG.md` is the living pointer for active delivery work.
 - `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - `SOT_REGISTRY.md` prevents parallel sources of truth.
@@ -372,8 +388,8 @@ They make the repository state checkable, but they do not replace the native ski
 
 ## Delivery Map
 
-`delivery-map --json` is the machine-readable delivery picture for the active control state.
-It derives, but does not replace, the live `.agdf/control/AGDF_RUN.md` and `MASTER_BACKLOG.md` state.
+`delivery-map --json` is the machine-readable delivery picture for the selected canonical control state.
+It derives, but does not replace, the selected `RUN_STATE.md` and `MASTER_BACKLOG.md` state.
 
 It must expose:
 

package/generated/plugins/agdf/skills/brownfield-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brownfield-analysis
-description: Use this skill after gate-check or live AGDF control state confirms that Brownfield Review or implementation preparation is allowed. Use it after Approval: UR as the lightweight Brownfield Review after G-00 before PRD when existing systems may be affected, and again before non-trivial implementation after TP. Do not use it as the first AGDF skill for a fresh "I want to build/change X" prompt when approval, scope, or next allowed action is unclear.
+description: "Use this skill after gate-check or live AGDF control state confirms that Brownfield Review or implementation preparation is allowed. Use it after Approval: UR as the lightweight Brownfield Review after G-00 before PRD when existing systems may be affected, and again before non-trivial implementation after TP. Do not use it as the first AGDF skill for a fresh \"I want to build/change X\" prompt when approval, scope, or next allowed action is unclear."
 ---
 
 # brownfield-analysis
@@ -47,8 +47,8 @@ Do not mix both modes silently. Name the active mode in the output.
 13. Specification archive migrations must follow the archive index if present.
 
 ## When To Use
-- after `gate-check` permits `Brownfield Review` or live `.agdf/control/AGDF_RUN.md` names Brownfield Review as the next allowed action
-- after `gate-check` permits implementation preparation or live `.agdf/control/AGDF_RUN.md` already names Brownfield Analysis as the next allowed action
+- after `gate-check` permits `Brownfield Review` or the selected canonical run record names Brownfield Review as the next allowed action
+- after `gate-check` permits implementation preparation or the selected canonical run record already names Brownfield Analysis as the next allowed action
 - after `Approval: UR` when existing owners, SoT, contracts, policies, persistence, runtime paths, tests, UI, UX or architecture may affect PRD/SD scope
 - before `CD+Tests`
 - before changes to an existing repository

package/generated/plugins/agdf/skills/delivery-path-search/SKILL.md

@@ -37,6 +37,17 @@ Skip for routine questions, obvious local fixes and approved implementation with
 npx --yes @agdf/cli@latest delivery-path-search --surface <surface> --json
 ```
 
+Optional AI-native candidate generation is explicit:
+
+```bash
+npx --yes @agdf/cli@latest delivery-path-search \
+  --surface codex \
+  --generate-candidates \
+  --json
+```
+
+It supplements the deterministic baseline with at most one bounded generator call. Treat proposals as untrusted until the canonical core validates schema, gate action, scope, duplicates and material diversity. Report generation provenance, budgets, rejections and failure. Never hide deterministic fallback or switch providers automatically.
+
 5. Treat facts, repository evidence, assumptions and model judgements separately.
 6. Return exactly one recommendation or `no_safe_recommendation`.
 7. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
@@ -73,3 +84,6 @@ Persist only the redacted decision summary when durable evidence is required. Do
 - Do not invent default scores for invalid evaluator output.
 - Do not implement, approve or release based on search output.
 - Do not create agent-specific scoring, gate logic or skill copies.
+- Do not replace deterministic candidates with generated proposals.
+- Do not send secrets, full artefacts, source snapshots, raw prompts or hidden reasoning to a generator.
+- Do not claim executable generation for instruction-only surfaces.

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

@@ -28,7 +28,7 @@ This skill is the primary operating path for gate judgement.
 
 First inspect the durable control state directly:
 
-- `.agdf/control/AGDF_RUN.md`
+- selected `.agdf/control/runs/<run_id>/RUN_STATE.md` (or legacy `AGDF_RUN.md` before explicit migration)
 - `.agdf/control/MASTER_BACKLOG.md`
 - `.agdf/control/SOT_REGISTRY.md`
 - `.agdf/control/CONTEXT_GRAPH.md`
@@ -47,7 +47,7 @@ npx --yes @agdf/cli@latest gate-check --json
 npx --yes @agdf/cli@latest delivery-map --json
 ```
 
-`init` creates the control scaffold. `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.
+`init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `gate-check` consumes that result and the selected canonical run record to report the operative process decision: `open | blocked`, current gate, blocking reason, missing approval, allowed outputs, forbidden outputs, next allowed action and evidence references.
 `delivery-map` reports the durable delivery picture: active artefacts, approvals, Artefact Chain relationships, evidence refs, missing evidence, risks, Context Graph gate effect and machine-readable findings.
 
 The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
@@ -124,14 +124,19 @@ If a status is not explicit, do not assume it is satisfied.
 12. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
 
 ## Output
-Keep the result short and operational:
-
-- **Current gate:** `<GateName or internal step>`
-- **Status:** `open | blocked`
-- **Allowed:** `<allowed outputs>`
-- **Forbidden:** `<forbidden outputs>`
-- **Missing approval:** `Approval: <GateName> | none`
-- **Next step:** `<single permissible next step>`
+Keep the result short and operational. Render the Runtime Contract's compact human-facing Run Status Card rather than a surface-specific summary:
+
+| Run status | Value |
+|---|---|
+| Status | `open | blocked` |
+| Current gate | `<GateName or internal step>` |
+| Allowed now | `<currently allowed outputs>` |
+| Blocked by | `<blocking condition or none>` |
+| Missing approval | `Approval: <GateName> | none` |
+| Next step | `<single permissible next step>` |
+| Quality outlook | `<next meaningful quality focus or none>` |
+
+When an approval is missing, also include `Next gate after approval` and `Allowed after approval` exactly as constrained by the Runtime Contract. Keep forbidden outputs, evidence and next-skill detail in the concise surrounding text when relevant; they are not extra status-card rows.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.

package/generated/plugins/agdf/skills/release-or/SKILL.md

@@ -28,7 +28,7 @@ It reports:
 Use `../../meta/agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
-When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from `AGDF_RUN.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
+When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
 Use the Runtime Contract definition of `Relevant Run` to decide whether OR is mandatory or whether a Quick Task mini-closeout is enough.
 
 ## Rules

package/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/lib/control-state/index.js

@@ -0,0 +1,6 @@
+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";

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

@@ -0,0 +1,94 @@
+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) {
+  const content = readFileSync(path, "utf8"),
+    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: ${path} -->\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));
+}
+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(source),
+    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/lib/control-state/run-state-parser.js

@@ -0,0 +1,196 @@
+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();
+}
+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 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 = [] } = {},
+) {
+  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))
+        approvals.set(g, {
+          status: clean(s) === "passed" && g === "QA" ? "approved" : clean(s),
+          evidence: e ?? "",
+        });
+    }
+  const artefacts = new Map();
+  for (const [t, p, s, n] of rows(section(content, "Artefacts"))) {
+    if (userGates.includes(t) || internalSteps.includes(t))
+      artefacts.set(t, { path: p ?? "", status: clean(s), notes: n ?? "" });
+  }
+  const mapRows = (h, header, fn) => dataRows(content, h, header).map(fn);
+  const mode = "Mode / Slice Decision",
+    source = "Source And Scope State",
+    memory = "Knowledge Persistence Decision";
+  return {
+    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"),
+    },
+  };
+}

package/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;
+}

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

@@ -0,0 +1,45 @@
+import { discoverRuns } from "./run-state-repository.js";
+export function resolveRuns(
+  root,
+  { runIdArg, runIdEnv, allActive = false } = {},
+) {
+  if (
+    (allActive && (runIdArg || runIdEnv)) ||
+    (runIdArg && runIdEnv && runIdArg !== runIdEnv)
+  )
+    throw Error("AGDF_SELECTOR_CONFLICT");
+  const runs = discoverRuns(root),
+    active = runs.filter((r) => r.valid && r.meta.lifecycle === "active");
+  const findings = runs
+    .filter((run) => !run.valid)
+    .flatMap((run) =>
+      run.findings.map((finding) => ({ ...finding, run_id: run.run_id })),
+    );
+  if (allActive)
+    return { selection_source: "all_active", runs: active, findings };
+  const id = runIdArg || runIdEnv;
+  if (id) {
+    const run = runs.find((r) => r.run_id === id);
+    if (!run?.valid) {
+      throw Error(
+        `AGDF_RUN_NOT_SELECTABLE:${id}; discovered=${runs.map((item) => item.run_id).join(",")}; next=select a valid run`,
+      );
+    }
+    return {
+      selection_source: runIdArg ? "cli" : "environment",
+      run,
+      active_run_ids: active.map((r) => r.run_id),
+    };
+  }
+  if (active.length !== 1)
+    throw Error(
+      active.length
+        ? `AGDF_ACTIVE_RUN_AMBIGUOUS:${active.map((r) => r.run_id)}`
+        : "AGDF_ACTIVE_RUN_MISSING",
+    );
+  return {
+    selection_source: "single_active",
+    run: active[0],
+    active_run_ids: [active[0].run_id],
+  };
+}