@event4u/agent-config 14.7.0 → 14.8.0

package/dist/cli-delegate/cmd_adr_effective.js

@@ -0,0 +1,1162 @@
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  DeadScopeError,
+  reportScanned
+} from "./chunk-I3EIN2YG.js";
+import "./chunk-J55WI3RR.js";
+
+// src/scripts/_cli/cmd_adr_effective.ts
+import * as fs2 from "node:fs";
+import * as path3 from "node:path";
+import process4 from "node:process";
+import { fileURLToPath as fileURLToPath2, pathToFileURL as pathToFileURL2 } from "node:url";
+
+// src/scripts/adr_cite_check.ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path2 from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/scripts/_lib/adr_frontmatter.ts
+var FOLD_MARKERS = /* @__PURE__ */ new Set([">", ">-", ">+", "|", "|-", "|+"]);
+function consumeFolded(lines, start, parentIndent) {
+  const parts = [];
+  let i = start;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.indent <= parentIndent) break;
+    parts.push(line.text);
+    i += 1;
+  }
+  return [parts.join(" ").trim(), i];
+}
+var QUOTED = /^["'](.*)["']$/;
+function stripQuotes(value) {
+  return value.replace(QUOTED, "$1");
+}
+function parseInlineList(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner === "") return [];
+  return inner.split(",").map((part) => stripQuotes(part.trim())).filter((part) => part !== "");
+}
+function significantLines(block) {
+  const out = [];
+  for (const raw of block.split("\n")) {
+    const line = raw.replace(/\s+$/, "");
+    if (line === "") continue;
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("#")) continue;
+    out.push({ indent: line.length - trimmed.length, text: trimmed });
+  }
+  return out;
+}
+function parseBlock(lines, start, parentIndent) {
+  const first = lines[start];
+  if (first === void 0) return ["", start];
+  if (first.text.startsWith("- ") || first.text === "-") {
+    const items = [];
+    let i2 = start;
+    while (i2 < lines.length) {
+      const line = lines[i2];
+      if (line.indent <= parentIndent || !line.text.startsWith("-")) break;
+      items.push(stripQuotes(line.text.replace(/^-\s*/, "").trim()));
+      i2 += 1;
+    }
+    return [items, i2];
+  }
+  const colon = first.text.indexOf(":");
+  if (colon > 0) {
+    const map = {};
+    let i2 = start;
+    while (i2 < lines.length) {
+      const line = lines[i2];
+      if (line.indent <= parentIndent) break;
+      const idx = line.text.indexOf(":");
+      if (idx <= 0) break;
+      const key = line.text.slice(0, idx).trim();
+      const rest = line.text.slice(idx + 1).trim();
+      i2 += 1;
+      if (rest === "" || FOLD_MARKERS.has(rest)) {
+        const next = lines[i2];
+        if (next !== void 0 && next.indent > line.indent) {
+          if (FOLD_MARKERS.has(rest)) {
+            const [folded, consumed2] = consumeFolded(lines, i2, line.indent);
+            map[key] = folded;
+            i2 = consumed2;
+            continue;
+          }
+          const [child, consumed] = parseBlock(lines, i2, line.indent);
+          map[key] = child;
+          i2 = consumed;
+          continue;
+        }
+        map[key] = "";
+        continue;
+      }
+      const inline = parseInlineList(rest);
+      map[key] = inline ?? stripQuotes(rest);
+    }
+    return [map, i2];
+  }
+  const parts = [];
+  let i = start;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.indent <= parentIndent) break;
+    parts.push(line.text);
+    i += 1;
+  }
+  return [parts.join(" ").trim(), i];
+}
+function foldToString(node) {
+  if (typeof node === "string") return node;
+  if (Array.isArray(node)) return `[${node.join(", ")}]`;
+  return Object.entries(node).map(([k, v]) => `${k}: ${foldToString(v)}`).join(" ").trim();
+}
+function readAdrFrontmatter(text) {
+  if (!text.startsWith("---\n")) return null;
+  const end = text.indexOf("\n---\n", 4);
+  if (end === -1) return null;
+  const lines = significantLines(text.slice(4, end));
+  const scalars = {};
+  const nested = {};
+  const keyOrder = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.indent > 0) {
+      i += 1;
+      continue;
+    }
+    const idx = line.text.indexOf(":");
+    if (idx <= 0) {
+      i += 1;
+      continue;
+    }
+    const key = line.text.slice(0, idx).trim();
+    const rest = line.text.slice(idx + 1).trim();
+    keyOrder.push(key);
+    i += 1;
+    const next = lines[i];
+    const hasBlock = next !== void 0 && next.indent > 0;
+    if (FOLD_MARKERS.has(rest) && hasBlock) {
+      const [folded, consumed] = consumeFolded(lines, i, 0);
+      scalars[key] = folded;
+      i = consumed;
+      continue;
+    }
+    if (rest === "" && hasBlock) {
+      const [child, consumed] = parseBlock(lines, i, 0);
+      i = consumed;
+      if (typeof child === "string") {
+        scalars[key] = child;
+      } else {
+        nested[key] = child;
+      }
+      continue;
+    }
+    const inline = parseInlineList(rest);
+    if (inline !== null) {
+      nested[key] = inline;
+      continue;
+    }
+    if (hasBlock) {
+      const [folded, consumed] = consumeFolded(lines, i, 0);
+      scalars[key] = `${stripQuotes(rest)} ${folded}`.trim();
+      i = consumed;
+      continue;
+    }
+    scalars[key] = stripQuotes(rest).replace(/^>-?$/, "");
+  }
+  return { scalars, nested, keyOrder };
+}
+function readAdrFrontmatterScalars(text) {
+  const parsed = readAdrFrontmatter(text);
+  if (parsed === null) return null;
+  const out = { ...parsed.scalars };
+  for (const [key, node] of Object.entries(parsed.nested)) {
+    out[key] = foldToString(node);
+  }
+  return out;
+}
+function asString(node) {
+  if (typeof node === "string") return node === "" ? null : node;
+  return null;
+}
+function asList(node) {
+  if (Array.isArray(node)) return node;
+  if (typeof node === "string" && node !== "") return [node];
+  return [];
+}
+function provenanceOf(fm) {
+  const node = fm.nested.provenance;
+  if (node === void 0 || typeof node === "string" || Array.isArray(node)) return null;
+  return {
+    kind: asString(node.kind),
+    decisionMakers: asList(node.decision_makers),
+    humanDirected: asString(node.human_directed),
+    agenticMode: asString(node.agentic_mode)
+  };
+}
+function evidenceOf(fm) {
+  const node = fm.nested.evidence;
+  if (node === void 0 || typeof node === "string" || Array.isArray(node)) return null;
+  return {
+    strength: asString(node.strength),
+    discovery: asString(node.discovery),
+    basis: asList(node.basis)
+  };
+}
+function authorityBasisOf(fm) {
+  return fm.scalars.authority_basis ?? null;
+}
+function isLowEvidenceAccepted(fm) {
+  if ((fm.scalars.status ?? "") !== "accepted") return false;
+  if (authorityBasisOf(fm) === "owner_intent") return false;
+  const evidence = evidenceOf(fm);
+  return evidence?.strength === "E0" || evidence?.strength === "E1";
+}
+
+// src/scripts/_lib/gate_ledger.ts
+import process2 from "node:process";
+var SKIP_REASON_MESSAGE = {
+  excluded_directory: "the target sits under a directory this gate deliberately does not walk",
+  size_limit: "the target exceeds the size ceiling this gate reads within",
+  binary_content: "the target is not decodable text, so the check does not apply to it",
+  missing_credentials: "the check needs a credential that is not present in this environment",
+  rules_unavailable: "the rule or policy corpus this check compares against could not be loaded",
+  manifest_absent: "the manifest that declares what to check for this target does not exist",
+  no_applicable_files: "the target resolved to zero files the check applies to",
+  disabled_by_configuration: "a setting in this repository turns this check off for the target",
+  generated_artifact: "the target is generated output whose source is checked instead",
+  dead_scan_root: "the root this target was enumerated from no longer exists",
+  declared_exemption: "the target carries an explicit, reviewable exemption from this check",
+  not_applicable_kind: "the target is a kind of artifact this check does not apply to",
+  precondition_unmet: "a precondition of this run settled the verdict before the target could be inspected",
+  check_did_not_run: "the check itself could not be executed, so the target was never read"
+};
+var UnaccountedTargetsError = class extends Error {
+  gate;
+  targets;
+  constructor(gate, targets) {
+    const shown = targets.slice(0, 20);
+    const more = targets.length - shown.length;
+    super(
+      `${gate}: ${String(targets.length)} planned target(s) reached no terminal outcome \u2014 the gate enumerated them and then neither checked, failed, skipped, nor excluded them, so its green result covers less than it appears to. Unaccounted: ${shown.join(", ")}${more > 0 ? ` \u2026 and ${String(more)} more` : ""}`
+    );
+    this.name = "UnaccountedTargetsError";
+    this.gate = gate;
+    this.targets = targets;
+  }
+};
+var LedgerUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LedgerUsageError";
+  }
+};
+var GateLedger = class {
+  gate;
+  /** Insertion-ordered so the unaccounted list reads in enumeration order. */
+  planned = /* @__PURE__ */ new Map();
+  constructor(gate) {
+    this.gate = gate;
+  }
+  /** Declare one or more targets this run intends to consider. */
+  plan(target) {
+    const targets = typeof target === "string" ? [target] : target;
+    for (const t of targets) {
+      if (this.planned.has(t)) {
+        throw new LedgerUsageError(
+          `${this.gate}: target planned twice: ${t}. A duplicate plan makes the denominator wrong in the direction that hides work.`
+        );
+      }
+      this.planned.set(t, void 0);
+    }
+  }
+  /** The target was checked and satisfied the gate. */
+  complete(target) {
+    this.resolve(target, { kind: "completed", reason: "" });
+  }
+  /** The target was checked and violated the gate. `reason` is the finding text. */
+  fail(target, reason) {
+    this.resolve(target, { kind: "failed", reason });
+  }
+  /** The target was NOT checked; `reason` names why, from the closed vocabulary. */
+  skip(target, reason) {
+    this.resolve(target, { kind: "skipped", reason });
+  }
+  /** The target does not belong to this gate's corpus; `reason` names why. */
+  outOfScope(target, reason) {
+    this.resolve(target, { kind: "out_of_scope", reason });
+  }
+  resolve(target, resolution) {
+    if (!this.planned.has(target)) {
+      throw new LedgerUsageError(
+        `${this.gate}: ${resolution.kind} recorded for an unplanned target: ${target}. Every target reaching an outcome must first be planned, or the denominator understates the work.`
+      );
+    }
+    const existing = this.planned.get(target);
+    if (existing !== void 0) {
+      throw new LedgerUsageError(
+        `${this.gate}: target resolved twice (${existing.kind} then ${resolution.kind}): ${target}.`
+      );
+    }
+    this.planned.set(target, resolution);
+  }
+  /** Planned targets that have not yet reached a terminal outcome, in enumeration order. */
+  unaccountedTargets() {
+    const out = [];
+    for (const [target, resolution] of this.planned) {
+      if (resolution === void 0) {
+        out.push(target);
+      }
+    }
+    return out;
+  }
+  /**
+   * Close the ledger and return the tally.
+   *
+   * @throws {UnaccountedTargetsError} when any planned target reached no outcome.
+   */
+  finalize() {
+    const unaccounted = this.unaccountedTargets();
+    if (unaccounted.length > 0) {
+      throw new UnaccountedTargetsError(this.gate, unaccounted);
+    }
+    const tally = {
+      planned: this.planned.size,
+      completed: 0,
+      skipped: 0,
+      failed: 0,
+      out_of_scope: 0,
+      unaccounted: 0,
+      skips_by_reason: {}
+    };
+    for (const resolution of this.planned.values()) {
+      if (resolution === void 0) {
+        continue;
+      }
+      if (resolution.kind === "completed") {
+        tally.completed += 1;
+      } else if (resolution.kind === "failed") {
+        tally.failed += 1;
+      } else {
+        if (resolution.kind === "skipped") {
+          tally.skipped += 1;
+        } else {
+          tally.out_of_scope += 1;
+        }
+        const code = resolution.reason;
+        tally.skips_by_reason[code] = (tally.skips_by_reason[code] ?? 0) + 1;
+      }
+    }
+    return tally;
+  }
+  /**
+   * Finalize and print the denominator on the success path.
+   *
+   * The line goes to stdout unconditionally, exactly as
+   * {@link import('./scan_scope.js').reportScanned} does and for the same
+   * recorded reason: CI passes `--quiet`, and a count only visible without it
+   * is not a count. It is deliberately NOT the `scanned: <N>` line
+   * `check_gate_coverage` parses — that stays the single machine-read
+   * coverage signal, and this is the human-auditable completeness breakdown
+   * beside it.
+   *
+   * @throws {UnaccountedTargetsError} via {@link finalize}.
+   */
+  report(write = process2.stdout.write.bind(process2.stdout)) {
+    const tally = this.finalize();
+    const checked = tally.completed + tally.failed;
+    const parts = [
+      `scanned=${String(checked)}`,
+      `planned=${String(tally.planned)}`,
+      `skipped=${String(tally.skipped + tally.out_of_scope)}`
+    ];
+    write(`${this.gate} ledger: ${parts.join(" ")}
+`);
+    const codes = Object.keys(tally.skips_by_reason).sort();
+    for (const code of codes) {
+      const n = tally.skips_by_reason[code] ?? 0;
+      write(`  ${code} \xD7${String(n)} \u2014 ${SKIP_REASON_MESSAGE[code]}
+`);
+    }
+    return tally;
+  }
+};
+
+// src/scripts/_lib/gate_self_test.ts
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import process3 from "node:process";
+function runGateCli(repoRoot, scriptRelPath, args, cwd) {
+  const tsx = path.join(
+    repoRoot,
+    "node_modules",
+    ".bin",
+    process3.platform === "win32" ? "tsx.cmd" : "tsx"
+  );
+  const res = spawnSync(tsx, [path.join(repoRoot, scriptRelPath), ...args], {
+    cwd,
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+    // The child must not recurse into its own self-test.
+    env: { ...process3.env, GATE_SELF_TEST_CHILD: "1" }
+  });
+  return res.status ?? 1;
+}
+function runSelfTest(opts) {
+  const write = opts.write ?? process3.stdout.write.bind(process3.stdout);
+  const minReject = opts.minRejectCases ?? 1;
+  const rejectCases = opts.cases.filter((c) => c.expect === "reject").length;
+  if (opts.cases.length < opts.minCases || rejectCases < minReject) {
+    write(
+      `\u274C  ${opts.gate} --self-test: ${String(opts.cases.length)} case(s) (${String(rejectCases)} rejecting) is below the declared floor of ${String(opts.minCases)} (${String(minReject)} rejecting). A truncated self-test must fail rather than print success \u2014 deleting cases is otherwise the cheapest route to a green one.
+`
+    );
+    return 1;
+  }
+  let failed = 0;
+  for (const testCase of opts.cases) {
+    let exit;
+    try {
+      exit = testCase.run();
+    } catch (e) {
+      write(`\u274C  ${opts.gate} --self-test: ${testCase.name} \u2014 threw: ${String(e)}
+`);
+      failed += 1;
+      continue;
+    }
+    const behaved = testCase.expect === "reject" ? exit !== 0 : exit === 0;
+    if (behaved) {
+      write(`\u2705  ${testCase.name} (expected ${testCase.expect}, exit ${String(exit)})
+`);
+    } else {
+      write(
+        `\u274C  ${testCase.name}: expected the gate to ${testCase.expect} this fixture, got exit ${String(exit)}. The gate's detection has stopped firing on a case it is supposed to catch.
+`
+      );
+      failed += 1;
+    }
+  }
+  write(
+    `
+${opts.gate} --self-test: ${String(opts.cases.length - failed)}/${String(opts.cases.length)} case(s) behaved (${String(rejectCases)} rejecting, floor ${String(opts.minCases)})
+`
+  );
+  return failed > 0 ? 1 : 0;
+}
+
+// src/scripts/adr_cite_check.ts
+var _HERE = path2.dirname(fileURLToPath(import.meta.url));
+var REPO_ROOT = path2.resolve(_HERE, "..", "..");
+function scan_root() {
+  return process.env["ADR_CITE_CHECK_ROOT"] ?? REPO_ROOT;
+}
+var ADR_DIRS = ["docs/decisions", "docs/adrs"];
+var SURFACES_NOT_SCANNED = [
+  "docs/contracts/adr-*.md \u2014 slug-named contracts, no ADR number to resolve against",
+  "agents/settings/contexts/adr-*.md \u2014 shadow notes, own status vocabulary",
+  "agents/decisions/ \u2014 row ledger, not per-decision files"
+];
+var PARTIAL_COVERAGE = [];
+var LOW_EVIDENCE_NOTICE = [
+  "authority_effect: disabled-shadow-mode",
+  "This record documents the prior choice. It does not by itself",
+  "establish that alternatives remain invalid."
+].join("\n");
+function normalise_ref(ref) {
+  const raw = ref.trim();
+  const byPath = /(?:^|\/)docs\/adrs\/([a-z0-9-]+)\/(\d{1,4})-/i.exec(raw);
+  if (byPath?.[1] !== void 0 && byPath[2] !== void 0) {
+    const num = byPath[2].padStart(4, "0");
+    return { id: `ADR-${byPath[1]}-${num}`, area: byPath[1], num };
+  }
+  const byArea = /^adr-([a-z][a-z0-9-]*?)-(\d{1,4})$/i.exec(raw.replace(/\.md$/i, ""));
+  if (byArea?.[1] !== void 0 && byArea[2] !== void 0) {
+    const area = byArea[1].toLowerCase();
+    const num = byArea[2].padStart(4, "0");
+    return { id: `ADR-${area}-${num}`, area, num };
+  }
+  const m = /(?:^|[^0-9])(\d{1,4})(?:[^0-9]|$)/.exec(raw.replace(/^.*\//, ""));
+  if (m?.[1] === void 0) return null;
+  return { id: `ADR-${m[1].padStart(3, "0")}`, area: null, num: String(Number(m[1])) };
+}
+function walk_md(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path2.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk_md(full));
+    else if (entry.name.endsWith(".md") && entry.name !== "INDEX.md") out.push(full);
+  }
+  return out.sort();
+}
+function adr_files(repo_root = REPO_ROOT) {
+  return ADR_DIRS.flatMap((d) => walk_md(path2.join(repo_root, d)));
+}
+var CITATION_ROOTS = ["src/rules", "src/skills", "src/domains", "docs"];
+var CITATION_FILE_EXTS = /* @__PURE__ */ new Set([".md", ".ts", ".yml", ".yaml"]);
+var CITATION_RE = /ADR-(?:[a-z][a-z0-9]*-\d{1,4}|\d{1,4})(?![0-9A-Za-z])/g;
+function walk_citable(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path2.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk_citable(full));
+    else if (CITATION_FILE_EXTS.has(path2.extname(entry.name))) out.push(full);
+  }
+  return out.sort();
+}
+function cited_refs(repo_root = REPO_ROOT) {
+  const found = /* @__PURE__ */ new Set();
+  for (const root of CITATION_ROOTS) {
+    for (const file of walk_citable(path2.join(repo_root, root))) {
+      for (const m of fs.readFileSync(file, "utf-8").matchAll(CITATION_RE)) {
+        found.add(m[0]);
+      }
+    }
+  }
+  return [...found].sort();
+}
+function parse_frontmatter(text) {
+  return readAdrFrontmatterScalars(text);
+}
+function protected_dimensions_of(fm) {
+  const node = fm.nested["protected_dimensions"];
+  if (Array.isArray(node)) return node;
+  if (typeof node === "string" && node !== "") return [node];
+  return [];
+}
+function unresolved_basis_refs(basis, repo_root) {
+  const missing = [];
+  for (const ref of basis) {
+    if (basis_ref_kind(ref) !== "path") continue;
+    if (!fs.existsSync(path2.join(repo_root, basis_ref_path(ref)))) missing.push(ref);
+  }
+  return missing;
+}
+function basis_ref_kind(ref) {
+  const t = ref.trim();
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(t)) return "url";
+  if (/^claim:/i.test(t)) return "claim";
+  return "path";
+}
+function basis_ref_path(ref) {
+  return ref.trim().replace(/\s*\([^)]*\)\s*$/, "").replace(/:\d+(-\d+)?$/, "").trim();
+}
+function amendment_blocks(body) {
+  const found = [];
+  for (const line of body.split("\n")) {
+    if (/^#{2,3}\s+Amendment\b/i.test(line) || /^\*\*Amended\b/i.test(line)) {
+      found.push(line.trim().replace(/^#+\s*/, "").replace(/\*\*/g, ""));
+    }
+  }
+  return found;
+}
+function trigger_state(fm) {
+  const t = (fm["review_trigger"] ?? "").trim();
+  if (t === "") return "none";
+  if (t.toLowerCase() === "unclassified") return "none";
+  return "indeterminate";
+}
+function verdict_for(r) {
+  if (!r.resolved) return "UNRESOLVED \u2014 no ADR file carries this number on a scanned surface.";
+  const status = (r.status ?? "").toLowerCase();
+  if (status === "superseded" || status === "deprecated") {
+    const by = r.superseded_by !== void 0 && r.superseded_by !== "\u2014" ? ` (by ${r.superseded_by})` : "";
+    return `NOT A LIVE LOCK \u2014 status is \`${status}\`${by}. Citing it as a blocker is a stale-state claim.`;
+  }
+  if (status === "rejected") {
+    return "LIVE \u2014 status `rejected` records a REJECTED PROPOSAL, so the rejection is the decision and it still binds. Reopening it means showing the premise it rejected on has changed; it does not mean the record is stale.";
+  }
+  if (r.amendment_blocks.length > 0 || r.amended_by !== void 0 && r.amended_by !== "\u2014") {
+    return "AMENDED \u2014 read the amendment before citing the original decision; the text above it may no longer hold.";
+  }
+  if (r.trigger_state === "none") {
+    return "LIVE, NO REOPEN CONDITION \u2014 the ADR records no `review_trigger`, so nothing would ever reopen it on its own. Treat that as a defect in the ADR, not as strength of the lock.";
+  }
+  return "LIVE, TRIGGER INDETERMINATE \u2014 the reopen condition is semantic and this tool cannot decide it. Not an unqualified lock: evaluate the condition against the current tree and route the result.";
+}
+function cite_check(refs, repo_root = REPO_ROOT) {
+  const files = adr_files(repo_root);
+  const contents = /* @__PURE__ */ new Map();
+  for (const f of files) contents.set(f, fs.readFileSync(f, "utf-8"));
+  return refs.map((ref) => {
+    const parsed = normalise_ref(ref);
+    if (parsed === null) {
+      const empty = {
+        ref,
+        resolved: false,
+        trigger_state: "none",
+        amendment_blocks: [],
+        referenced_by: []
+      };
+      return { ...empty, verdict: verdict_for(empty) };
+    }
+    const { id, area, num } = parsed;
+    const match = area === null ? files.find((f) => new RegExp(`(^|/)ADR-0*${num}[-.]`, "i").test(f)) : files.find(
+      (f) => new RegExp(`/docs/adrs/${area}/0*${Number(num)}-`, "i").test(f)
+    );
+    if (match === void 0) {
+      const empty = {
+        ref: id,
+        resolved: false,
+        trigger_state: "none",
+        amendment_blocks: [],
+        referenced_by: []
+      };
+      return { ...empty, verdict: verdict_for(empty) };
+    }
+    const text = contents.get(match) ?? "";
+    const fm = parse_frontmatter(text) ?? {};
+    const structured = readAdrFrontmatter(text);
+    const provenance = structured === null ? null : provenanceOf(structured);
+    const evidence = structured === null ? null : evidenceOf(structured);
+    const basis = structured === null ? null : authorityBasisOf(structured);
+    const evidence_basis = evidence?.basis ?? [];
+    const declared_policy = fm["reopen_policy"];
+    const reopen_policy = declared_policy !== void 0 && declared_policy !== "" ? declared_policy : "unclassified";
+    const reopen_policy_defaulted = declared_policy === void 0 || declared_policy === "";
+    const protected_dimensions = structured === null ? [] : protected_dimensions_of(structured);
+    const provisional = structured !== null && isLowEvidenceAccepted(structured);
+    const bodyStart = text.indexOf("\n---\n", 4);
+    const body = bodyStart === -1 ? text : text.slice(bodyStart + 5);
+    const cited = area === null ? new RegExp(`ADR-0*${num}\\b`, "i") : new RegExp(`ADR-${area}-0*${Number(num)}\\b`, "i");
+    const referenced_by = files.filter((f) => f !== match && cited.test(contents.get(f) ?? "")).map((f) => path2.relative(repo_root, f));
+    const partial = {
+      ref: id,
+      resolved: true,
+      file: path2.relative(repo_root, match),
+      ...fm["status"] !== void 0 ? { status: fm["status"] } : {},
+      ...fm["date"] !== void 0 ? { date: fm["date"] } : {},
+      ...fm["decision"] !== void 0 ? { decision: fm["decision"] } : {},
+      ...fm["review_trigger"] !== void 0 && fm["review_trigger"] !== "" ? { review_trigger: fm["review_trigger"] } : {},
+      trigger_state: trigger_state(fm),
+      ...fm["supersedes"] !== void 0 ? { supersedes: fm["supersedes"] } : {},
+      ...fm["superseded_by"] !== void 0 ? { superseded_by: fm["superseded_by"] } : {},
+      ...fm["amends"] !== void 0 ? { amends: fm["amends"] } : {},
+      ...fm["amended_by"] !== void 0 ? { amended_by: fm["amended_by"] } : {},
+      amendment_blocks: amendment_blocks(body),
+      referenced_by,
+      ...provenance?.kind !== void 0 && provenance.kind !== null ? { provenance_kind: provenance.kind } : {},
+      ...provenance?.agenticMode !== void 0 && provenance.agenticMode !== null ? { provenance_agentic_mode: provenance.agenticMode } : {},
+      ...evidence?.strength !== void 0 && evidence.strength !== null ? { evidence_strength: evidence.strength } : {},
+      ...evidence?.discovery !== void 0 && evidence.discovery !== null ? { evidence_discovery: evidence.discovery } : {},
+      ...evidence_basis.length > 0 ? {
+        evidence_basis,
+        evidence_basis_unresolved: unresolved_basis_refs(evidence_basis, repo_root)
+      } : {},
+      ...basis !== null ? { authority_basis: basis } : {},
+      reopen_policy,
+      reopen_policy_defaulted,
+      protected_dimensions,
+      ...provisional ? { authority_effect: "disabled-shadow-mode" } : {}
+    };
+    return { ...partial, verdict: verdict_for(partial) };
+  });
+}
+function render(results) {
+  const lines = [];
+  for (const r of results) {
+    lines.push(`
+${r.ref}${r.file !== void 0 ? `  \xB7  ${r.file}` : ""}`);
+    if (!r.resolved) {
+      lines.push(`  \u274C  ${r.verdict}`);
+      continue;
+    }
+    lines.push(`  status           ${r.status ?? "\u2014"}   date ${r.date ?? "\u2014"}`);
+    if (r.decision !== void 0) lines.push(`  decision         ${r.decision}`);
+    lines.push(`  review_trigger   ${r.review_trigger ?? "\u2014 (none recorded)"}`);
+    lines.push(`  trigger state    ${r.trigger_state}`);
+    if (r.supersedes !== void 0 && r.supersedes !== "\u2014") lines.push(`  supersedes       ${r.supersedes}`);
+    if (r.superseded_by !== void 0 && r.superseded_by !== "\u2014")
+      lines.push(`  superseded_by    ${r.superseded_by}`);
+    if (r.amends !== void 0 && r.amends !== "\u2014") lines.push(`  amends           ${r.amends}`);
+    if (r.amended_by !== void 0 && r.amended_by !== "\u2014") lines.push(`  amended_by       ${r.amended_by}`);
+    if (r.amendment_blocks.length > 0)
+      lines.push(`  amendments       ${String(r.amendment_blocks.length)}: ${r.amendment_blocks.join(" \xB7 ")}`);
+    if (r.referenced_by.length > 0)
+      lines.push(`  referenced by    ${String(r.referenced_by.length)} other ADR(s): ${r.referenced_by.join(", ")}`);
+    const provenanceLine = r.provenance_kind ?? "\u2014 (no provenance axis)";
+    const mode = r.provenance_agentic_mode !== void 0 ? `  \xB7  mode ${r.provenance_agentic_mode}` : "";
+    lines.push(`  provenance       ${provenanceLine}${mode}`);
+    lines.push(
+      `  evidence         ${r.evidence_strength ?? "\u2014 (ungraded)"}  \xB7  discovery ${r.evidence_discovery ?? "\u2014"}`
+    );
+    lines.push(`  authority_basis  ${r.authority_basis ?? "\u2014 (absent \u2192 evidence)"}`);
+    if (r.evidence_basis === void 0 || r.evidence_basis.length === 0) {
+      lines.push("  evidence_basis   \u2014 (none recorded)");
+    } else {
+      const unresolved = new Set(r.evidence_basis_unresolved ?? []);
+      lines.push(
+        `  evidence_basis   ${String(r.evidence_basis.length)} ref(s), ${String(unresolved.size)} unresolved:`
+      );
+      for (const ref of r.evidence_basis) {
+        const kind = basis_ref_kind(ref);
+        const marker = kind !== "path" ? `[not checked: ${kind}]` : unresolved.has(ref) ? "[MISSING]" : "[found]";
+        lines.push(`                     ${marker} ${ref}`);
+      }
+    }
+    const policyNote = r.reopen_policy_defaulted === true ? " (absent \u2192 default)" : " (declared)";
+    const dims = r.protected_dimensions !== void 0 && r.protected_dimensions.length > 0 ? r.protected_dimensions.join(", ") : "\u2014 (none declared)";
+    lines.push(`  reopen_policy    ${r.reopen_policy ?? "unclassified"}${policyNote}`);
+    lines.push(`  protected dims   ${dims}`);
+    lines.push(`  \u2192  ${r.verdict}`);
+    if (r.authority_effect === "disabled-shadow-mode") lines.push(LOW_EVIDENCE_NOTICE);
+  }
+  return lines.join("\n");
+}
+function selfTest() {
+  const tmp = fs.mkdtempSync(path2.join(os.tmpdir(), "acc-"));
+  const mk = (adr, citation) => {
+    const root = fs.mkdtempSync(path2.join(tmp, "root-"));
+    fs.mkdirSync(path2.join(root, "docs", "decisions"), { recursive: true });
+    fs.mkdirSync(path2.join(root, "src", "rules"), { recursive: true });
+    if (adr !== null) {
+      fs.writeFileSync(
+        path2.join(root, "docs", "decisions", `ADR-${adr}-probe.md`),
+        `---
+status: accepted
+date: 2026-08-21
+decision: probe
+---
+
+# Probe
+`,
+        "utf-8"
+      );
+    }
+    fs.writeFileSync(
+      path2.join(root, "src", "rules", "probe.md"),
+      citation === null ? "# Probe\n\nNo decision is named here.\n" : `# Probe
+
+See ${citation}.
+`,
+      "utf-8"
+    );
+    return root;
+  };
+  const run = (root) => {
+    process.env["ADR_CITE_CHECK_ROOT"] = root;
+    try {
+      return runGateCli(REPO_ROOT, "src/scripts/adr_cite_check.ts", ["--cited"], REPO_ROOT);
+    } finally {
+      delete process.env["ADR_CITE_CHECK_ROOT"];
+    }
+  };
+  try {
+    return runSelfTest({
+      gate: "adr_cite_check",
+      minCases: 3,
+      minRejectCases: 2,
+      cases: [
+        {
+          name: "a citation whose ADR exists passes",
+          expect: "accept",
+          run: () => run(mk("001", "ADR-001"))
+        },
+        {
+          name: "a citation to an ADR that does not exist is rejected \u2014 the gate's whole subject",
+          expect: "reject",
+          run: () => run(mk("001", "ADR-993"))
+        },
+        {
+          name: "citation roots that name no ADR at all are rejected as a dead scope, never green",
+          expect: "reject",
+          run: () => run(mk("001", null))
+        }
+      ]
+    });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+function main(argv) {
+  const as_json = argv.includes("--json");
+  if (argv.includes("--self-test")) return selfTest();
+  const corpus_mode = argv.includes("--cited");
+  const explicit = argv.filter((a) => !a.startsWith("--"));
+  if (!corpus_mode && explicit.length === 0) {
+    process.stderr.write(
+      `usage: adr_cite_check <ADR-NNN> [ADR-NNN \u2026] [--json]
+       adr_cite_check --cited [--json]
+       evaluate a decision before citing it as a reason not to act
+       --cited: resolve every ADR citation in ${CITATION_ROOTS.join(", ")} (the CI gate)
+`
+    );
+    return 2;
+  }
+  const root = scan_root();
+  const refs = corpus_mode ? cited_refs(root) : explicit;
+  const results = cite_check(refs, root);
+  let ledger = null;
+  if (corpus_mode) {
+    ledger = new GateLedger("adr_cite_check");
+    ledger.plan(refs);
+    for (const r of results) {
+      if (r.resolved) ledger.complete(r.ref);
+      else ledger.fail(r.ref, "citation resolves to no decision record");
+    }
+  }
+  if (as_json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          results,
+          surfaces_not_scanned: SURFACES_NOT_SCANNED,
+          partial_coverage: PARTIAL_COVERAGE,
+          ...ledger !== null ? { ledger: ledger.finalize() } : {}
+        },
+        null,
+        2
+      ) + "\n"
+    );
+  } else {
+    const shown = corpus_mode ? results.filter((r) => !r.resolved) : results;
+    if (corpus_mode) {
+      process.stdout.write(
+        `ADR citations: ${String(results.length)} distinct reference(s) across ${CITATION_ROOTS.join(", ")} \xB7 ${String(results.filter((r) => !r.resolved).length)} unresolved
+`
+      );
+    }
+    if (shown.length > 0) process.stdout.write(render(shown) + "\n");
+    if (ledger !== null) {
+      try {
+        reportScanned({
+          gate: "adr_cite_check",
+          scanned: results.length,
+          units: "cited ADR reference(s)",
+          roots: [...CITATION_ROOTS, ...ADR_DIRS]
+        });
+      } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+          process.stderr.write(`\u274C  ${exc.message}
+`);
+          return 1;
+        }
+        throw exc;
+      }
+      ledger.report();
+    }
+  }
+  const unresolved = results.filter((r) => !r.resolved);
+  if (unresolved.length > 0) {
+    process.stderr.write(
+      `
+\u274C  ${String(unresolved.length)} reference(s) did not resolve on a scanned surface. Not scanned: ${SURFACES_NOT_SCANNED.join(" \xB7 ")}
+`
+    );
+    return 1;
+  }
+  return 0;
+}
+if (process.argv[1] !== void 0) {
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path2.resolve(process.argv[1]));
+    if (here === argv1) {
+      process.exitCode = main(process.argv.slice(2));
+    }
+  } catch {
+    const argvUrl = pathToFileURL(path2.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+      process.exitCode = main(process.argv.slice(2));
+    }
+  }
+}
+
+// src/scripts/_cli/cmd_adr_effective.ts
+var _HERE2 = path3.dirname(fileURLToPath2(import.meta.url));
+var REPO_ROOT2 = path3.resolve(_HERE2, "..", "..", "..");
+var ASSERTIVE_SECTIONS = ["decision", "consequences", "amendment"];
+var RETIRES_RE = /^>?\s*retires:\s*(.+)$/i;
+var CLAUSE_MARKER_RE = /\*\*\((?:Superseded|Narrowed|Reopened) by ([^—)]+?)\s*(?:—[^)]*)?\)\*\*/;
+function cleanToken(raw) {
+  return raw.trim().replace(/^`+|`+$/g, "").trim();
+}
+function sectionOf(headings, line) {
+  let current = "(preamble)";
+  for (const h of headings) {
+    if (h.line > line) break;
+    current = h.text;
+  }
+  return current;
+}
+function isAssertive(section) {
+  const first = section.toLowerCase().replace(/^#+\s*/, "").split(/[\s·—-]/)[0] ?? "";
+  return ASSERTIVE_SECTIONS.includes(first);
+}
+function splitClauses(lines, headings) {
+  const out = [];
+  let start = -1;
+  let buf = [];
+  const flush = () => {
+    if (start === -1) return;
+    out.push({ line: start, section: sectionOf(headings, start), text: buf.join("\n") });
+    start = -1;
+    buf = [];
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const num = i + 1;
+    if (raw.trim() === "") {
+      flush();
+      continue;
+    }
+    if (/^\s*(?:[-*+]\s|\d+\.\s)/.test(raw)) flush();
+    if (start === -1) start = num;
+    buf.push(raw);
+  }
+  flush();
+  return out;
+}
+function headingsOf(lines) {
+  const out = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    if (/^#{2,3}\s+/.test(raw)) out.push({ line: i + 1, text: raw.replace(/^#+\s*/, "").trim() });
+  }
+  return out;
+}
+function amendmentsOf(lines) {
+  const headings = headingsOf(lines);
+  const out = [];
+  for (let h = 0; h < headings.length; h += 1) {
+    const heading = headings[h];
+    if (!/^amend/i.test(heading.text)) continue;
+    const next = headings[h + 1];
+    const end = next === void 0 ? lines.length : next.line - 1;
+    const retires = [];
+    for (let i = heading.line; i < end; i += 1) {
+      const m = RETIRES_RE.exec(lines[i].trim());
+      if (m?.[1] === void 0) continue;
+      for (const part of m[1].split(",")) {
+        const token = cleanToken(part);
+        if (token !== "") retires.push(token);
+      }
+    }
+    out.push({ heading: heading.text, line: heading.line, retires, range: [heading.line, end] });
+  }
+  return out;
+}
+function decisionSection(lines) {
+  const headings = headingsOf(lines);
+  for (let h = 0; h < headings.length; h += 1) {
+    const heading = headings[h];
+    if (!/^decision\b/i.test(heading.text)) continue;
+    const next = headings[h + 1];
+    const end = next === void 0 ? lines.length : next.line - 1;
+    return lines.slice(heading.line, end).filter((l, idx, all) => !(l.trim() === "" && all[idx + 1] === void 0));
+  }
+  return [];
+}
+function clauseFindings(lines, amendments) {
+  const headings = headingsOf(lines);
+  const clauses = splitClauses(lines, headings);
+  const superseded = [];
+  const contradictions = [];
+  for (const clause of clauses) {
+    const marker = CLAUSE_MARKER_RE.exec(clause.text);
+    const excerpt = (clause.text.split("\n")[0] ?? "").trim();
+    if (marker?.[1] !== void 0) {
+      superseded.push({
+        line: clause.line,
+        section: clause.section,
+        subject: marker[1].trim(),
+        excerpt
+      });
+      continue;
+    }
+    if (!isAssertive(clause.section)) continue;
+    for (const amendment of amendments) {
+      const inDeclaringBlock = clause.line >= amendment.range[0] && clause.line <= amendment.range[1];
+      if (inDeclaringBlock) continue;
+      for (const token of amendment.retires) {
+        if (!clause.text.includes(token)) continue;
+        contradictions.push({
+          line: clause.line,
+          section: clause.section,
+          subject: token,
+          excerpt
+        });
+        break;
+      }
+    }
+  }
+  return { superseded, contradictions };
+}
+function resolveAdrFile(ref, repoRoot) {
+  const parsed = normalise_ref(ref);
+  if (parsed === null) return null;
+  const files = adr_files(repoRoot);
+  const { area, num } = parsed;
+  const match = area === null ? files.find((f) => new RegExp(`(^|/)ADR-0*${num}[-.]`, "i").test(f)) : files.find((f) => new RegExp(`/docs/adrs/${area}/0*${String(Number(num))}-`, "i").test(f));
+  return match ?? null;
+}
+function effectiveState(ref, repoRoot = REPO_ROOT2) {
+  const parsed = normalise_ref(ref);
+  const id = parsed?.id ?? ref;
+  const match = resolveAdrFile(ref, repoRoot);
+  if (match === null) {
+    return {
+      ref: id,
+      resolved: false,
+      trigger_state: "none",
+      amendments: [],
+      retired_tokens: [],
+      superseded_clauses: [],
+      contradictions: [],
+      effective_decision: []
+    };
+  }
+  const text = fs2.readFileSync(match, "utf-8");
+  const scalars = parse_frontmatter(text) ?? {};
+  const structured = readAdrFrontmatter(text);
+  const provenance = structured === null ? null : provenanceOf(structured);
+  const evidence = structured === null ? null : evidenceOf(structured);
+  const basis = structured === null ? null : authorityBasisOf(structured);
+  const bodyStart = text.indexOf("\n---\n", 4);
+  const frontmatterLines = bodyStart === -1 ? 0 : text.slice(0, bodyStart + 5).split("\n").length - 1;
+  const lines = text.split("\n");
+  const amendments = amendmentsOf(lines).filter((a) => a.line > frontmatterLines);
+  const { superseded, contradictions } = clauseFindings(lines, amendments);
+  const retired = [...new Set(amendments.flatMap((a) => a.retires))];
+  return {
+    ref: id,
+    resolved: true,
+    file: path3.relative(repoRoot, match),
+    ...scalars["status"] !== void 0 ? { status: scalars["status"] } : {},
+    ...scalars["date"] !== void 0 ? { date: scalars["date"] } : {},
+    ...scalars["decision"] !== void 0 ? { decision: scalars["decision"] } : {},
+    ...provenance?.kind != null ? { provenance_kind: provenance.kind } : {},
+    ...evidence?.strength != null ? { evidence_strength: evidence.strength } : {},
+    ...evidence?.discovery != null ? { evidence_discovery: evidence.discovery } : {},
+    ...basis !== null ? { authority_basis: basis } : {},
+    ...scalars["review_trigger"] !== void 0 && scalars["review_trigger"] !== "" ? { review_trigger: scalars["review_trigger"] } : {},
+    trigger_state: trigger_state(scalars),
+    ...scalars["amended_by"] !== void 0 && scalars["amended_by"] !== "\u2014" ? { amended_by: scalars["amended_by"] } : {},
+    amendments,
+    retired_tokens: retired,
+    superseded_clauses: superseded,
+    contradictions,
+    effective_decision: decisionSection(lines)
+  };
+}
+function render2(state) {
+  const out = [];
+  out.push(`${state.ref}${state.file !== void 0 ? `  \xB7  ${state.file}` : ""}`);
+  if (!state.resolved) {
+    out.push("  \u274C  UNRESOLVED \u2014 no decision record carries this number on a scanned surface.");
+    return out;
+  }
+  out.push(`  status           ${state.status ?? "\u2014"}   date ${state.date ?? "\u2014"}`);
+  if (state.decision !== void 0) out.push(`  decision         ${state.decision}`);
+  out.push(`  provenance       ${state.provenance_kind ?? "\u2014 (no provenance axis)"}`);
+  out.push(
+    `  evidence         ${state.evidence_strength ?? "\u2014 (ungraded)"}  \xB7  discovery ${state.evidence_discovery ?? "\u2014"}`
+  );
+  out.push(`  authority_basis  ${state.authority_basis ?? "\u2014 (absent \u2192 evidence)"}`);
+  out.push(`  review_trigger   ${state.review_trigger ?? "\u2014 (none recorded)"}`);
+  out.push(`  trigger state    ${state.trigger_state}`);
+  if (state.amended_by !== void 0) out.push(`  amended_by       ${state.amended_by}`);
+  out.push("", "  active amendments");
+  if (state.amendments.length === 0) {
+    out.push("    \u2014 none in the body");
+  } else {
+    for (const a of state.amendments) {
+      const declares = a.retires.length > 0 ? `  \xB7  retires ${a.retires.map((t) => `\`${t}\``).join(", ")}` : "";
+      out.push(`    :${String(a.line)}  ${a.heading}${declares}`);
+    }
+  }
+  out.push("", "  superseded clauses");
+  if (state.retired_tokens.length === 0 && state.superseded_clauses.length === 0) {
+    out.push("    \u2014 no amendment declares a `retires:` list and no clause carries a marker,");
+    out.push("      so nothing is claimed about this record's clauses. Read the amendments.");
+  } else if (state.superseded_clauses.length === 0) {
+    out.push("    \u2014 none marked");
+  } else {
+    for (const c of state.superseded_clauses) {
+      out.push(`    :${String(c.line)}  ${c.section} \u2014 superseded by ${c.subject}`);
+      out.push(`             ${c.excerpt}`);
+    }
+  }
+  out.push("", "  effective decision");
+  if (state.effective_decision.length === 0) {
+    out.push("    \u2014 no `## Decision` section");
+  } else {
+    for (const line of state.effective_decision) out.push(`    ${line}`);
+  }
+  if (state.contradictions.length > 0) {
+    out.push("", "  \u274C  current-vs-amendment contradiction");
+    for (const c of state.contradictions) {
+      out.push(`    :${String(c.line)}  ${c.section} asserts \`${c.subject}\`, which an`);
+      out.push("             amendment on this record declares retired, and carries no marker.");
+      out.push(`             ${c.excerpt}`);
+    }
+  }
+  return out;
+}
+function parseArgv(argv) {
+  let json = false;
+  const refs = [];
+  for (const a of argv) {
+    if (a === "--json") json = true;
+    else if (a === "-h" || a === "--help")
+      return { ok: false, message: "usage: agent-config adr:effective <ADR-NNN> [ADR-NNN \u2026] [--json]" };
+    else if (a.startsWith("--")) return { ok: false, message: `unknown argument: ${a}` };
+    else refs.push(a);
+  }
+  if (refs.length === 0)
+    return { ok: false, message: "usage: agent-config adr:effective <ADR-NNN> [ADR-NNN \u2026] [--json]" };
+  return { ok: true, refs, json };
+}
+function main2(argv = process4.argv.slice(2)) {
+  const parsed = parseArgv(argv);
+  if (!parsed.ok) {
+    process4.stderr.write(`${parsed.message ?? "usage error"}
+`);
+    return 2;
+  }
+  const states = (parsed.refs ?? []).map((ref) => effectiveState(ref));
+  if (parsed.json === true) {
+    process4.stdout.write(`${JSON.stringify(states, null, 2)}
+`);
+  } else {
+    for (const state of states) {
+      for (const line of render2(state)) process4.stdout.write(`${line}
+`);
+      process4.stdout.write("\n");
+    }
+  }
+  const bad = states.filter((s) => !s.resolved || s.contradictions.length > 0);
+  return bad.length > 0 ? 1 : 0;
+}
+function _isCliEntry() {
+  if (process4.argv[1] === void 0) return false;
+  const argvUrl = pathToFileURL2(path3.resolve(process4.argv[1])).href;
+  if (import.meta.url === argvUrl) return true;
+  try {
+    return fs2.realpathSync(fileURLToPath2(import.meta.url)) === fs2.realpathSync(path3.resolve(process4.argv[1]));
+  } catch {
+    return false;
+  }
+}
+if (_isCliEntry()) {
+  process4.exitCode = main2();
+}
+export {
+  ASSERTIVE_SECTIONS,
+  amendmentsOf,
+  clauseFindings,
+  decisionSection,
+  effectiveState,
+  main2 as main,
+  parseArgv,
+  render2 as render,
+  resolveAdrFile,
+  splitClauses
+};