@ecoma-io/archkeep 0.13.0

package/src/architecture-intent/selectors.mjs

@@ -0,0 +1,170 @@
+/**
+ * The exact-match selector engine for Architecture Intent.
+ *
+ * A boundary's `match[]` values select projects. This is deliberately NOT
+ * `findMatchingProjects` (`../rules/match.mjs`): that matcher is a faithful port
+ * of Nx's own, and Nx's unlabeled patterns fall back to a case-insensitive
+ * substring regular expression over project names (`applyName`, match.mjs:193).
+ * Two things make that fallback wrong here:
+ *
+ *   - A boundary is a claim about which projects share an architecture role.
+ *     `{ "match": ["domain"] }` quietly pulling in `platform-domain` because a
+ *     substring regex matched is a boundary that means something other than what
+ *     its author wrote — a silent false negative (a real violation routed
+ *     through the stray member is never reported). Nx tolerates the
+ *     over-approximation because its matcher already guards other text; intent
+ *     IS the contract, so it must mean exactly what it says.
+ *   - The fallback interpolates the selector into `new RegExp(...)`. In intent
+ *     the selector is attacker-adjacent input (anything a pull request can add),
+ *     and building a RegExp from it is a rejection / injection surface. Exact
+ *     string comparison constructs no RegExp, so neither the over-approximation
+ *     nor an injection surface exists.
+ *
+ * So intent owns this tiny grammar, matched by string equality only. Three
+ * labeled forms plus a bare name, `*` for everything, and `!` for set
+ * difference — nothing else. No glob, no `?`, no character class, no regex. A
+ * `label:` prefix that is not one of the three is a load error (a `tagz:x` typo
+ * surfaces red, never as a silent zero-match), handled by
+ * `../architecture-intent/model.mjs` calling `selectorType` — this module
+ * resolves members, it does not validate the file.
+ */
+
+/** The three selector labels. `unlabeled` is a bare project name (equals `name:`). */
+export const SELECTOR_LABELS = Object.freeze(["name", "tag", "directory"]);
+
+/**
+ * Split a selector into `{exclude, label, value}` — `!` prefix removed, `*`
+ * kept as `*`. The `!`-prefix is the only leading signal a selector has; it
+ * does not participate in the label or value lookup.
+ */
+export function splitSelector(value) {
+  const exclude = value.startsWith("!");
+  const body = exclude ? value.substring(1) : value;
+  const separator = body.indexOf(":");
+  const label = separator === -1 ? null : body.substring(0, separator);
+  const val = separator === -1 ? body : body.substring(separator + 1);
+  return { exclude, label, value: val };
+}
+
+/** Whether `value` is a syntactically valid selector — `!` prefix, then a known label or none. */
+export function isValidSelector(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  const { exclude, label, value: body } = splitSelector(value);
+  if (label !== null && !SELECTOR_LABELS.includes(label)) return false;
+  if (body.length === 0) return false;
+  return exclude === true || exclude === false;
+}
+
+/**
+ * The projects positively selected by one selector — a fresh array every call,
+ * so callers can union results, and a sorted array, so the first thing a caller
+ * doing set-math sees is a deterministic order. The `!` prefix is ignored here:
+ * exclusion is a LIST-level operation over a boundary's whole `match[]`
+ * (`resolveMembers` below), because `!a` means "everything already matched,
+ * minus `a`" and so has no meaning as a single selector.
+ *
+ * `nodes` is the provider-neutral project map `{name: {data: {root, tags}}}`
+ * every command receives.
+ *
+ * @param {string} selector
+ * @param {Record<string, {data?: {root?: string, tags?: string[]}}>} nodes
+ * @returns {string[]}
+ */
+export function selectProjects(selector, nodes) {
+  const { label, value } = splitSelector(selector);
+
+  let found;
+  // `*` is a TOKEN of this grammar, not a wildcard character in it, so only the
+  // BARE `*` means "every project" — `label === null` is what says "bare".
+  // `docs/reference/architecture-intent.md`'s selector table gives `*` its own
+  // row ("every project") separate from the three labeled rows, each of which
+  // reads as an exact-equality test: `name:<name>` is "the project with that
+  // exact name", `tag:<tag>` is "every project carrying that tag",
+  // `directory:<d>` is "every project whose root directory is exactly `<d>`".
+  // Testing `value === "*"` FIRST discarded the label, so `name:*`, `tag:*` and
+  // `directory:*` each silently returned every project in the graph — a
+  // boundary that reads as "the project literally named `*`" quietly became
+  // "all of them", and, worse, it could never reach the zero-member no-verdict
+  // in `./judge.mjs` that a selector matching nothing is supposed to raise.
+  //
+  // So a label puts `*` back in the value's own alphabet: `name:*` selects the
+  // project actually named `*` (none, in every real workspace, so the boundary
+  // is loudly unresolvable); `tag:*` selects the projects carrying a tag
+  // literally spelled `*`, NOT "any project carrying any tag"; `directory:*`
+  // the projects rooted at a directory literally named `*`. That reading is
+  // forced twice over — this module's header admits no glob, no `?`, no
+  // character class and no regex, and the doc's table defines each labeled form
+  // as an exact match — and it is also the fail-loud one: every labeled `*`
+  // that an author meant as a wildcard now resolves to nothing and surfaces as
+  // a no-verdict, where the old behaviour answered a question nobody asked with
+  // a set nobody wrote.
+  if (label === null && value === "*") {
+    found = Object.keys(nodes);
+  } else if (label === "tag") {
+    found = Object.keys(nodes).filter((name) => (nodes[name].data?.tags ?? []).includes(value));
+  } else if (label === "directory") {
+    found = Object.keys(nodes).filter((name) => nodes[name].data?.root === value);
+  } else {
+    // name: and unlabeled both mean an exact project name. Exact equality —
+    // no substring, no case folding — so `domain` selects nothing when only
+    // `platform-domain` exists, and the boundary is accurately empty.
+    //
+    // `Object.hasOwn`, never `nodes[value]`: `nodes` is a caller-supplied map
+    // whose keys are project NAMES, and most providers hand over a plain object
+    // (`JSON.parse` of `nx graph --file=`, `Object.fromEntries` in a test) that
+    // still inherits from `Object.prototype`. A truthiness test on it answered
+    // `constructor`, `toString`, `valueOf`, `hasOwnProperty` and `__proto__`
+    // with an inherited member and reported the selector as matching a project
+    // of that name — measured: `selectProjects("constructor", nodes)` returned
+    // `["constructor"]` on a graph with no such project, while `"nosuch"`
+    // correctly returned `[]`. That is the silent direction twice: the phantom
+    // member kept the boundary's zero-member check in `./judge.mjs` from ever
+    // firing, so `intentUnresolved` stayed 0 and `check` exited 0 where its
+    // contract owes 3, and every row anchored on that boundary was judged
+    // against a project the workspace does not contain. The same names reach
+    // `dependencies.forbidden` through a `Map` and are loud there; this branch
+    // was the one that answered from the prototype.
+    found = Object.hasOwn(nodes, value) ? [value] : [];
+  }
+
+  return found.sort();
+}
+
+/**
+ * The members of a boundary: the union of its positive selectors, minus
+ * whatever its `!` selectors carve out — order-independent, because
+ * `docs/reference/architecture-intent.md` documents `match[]` as a set
+ * expression ("the union of its positive selectors minus its `!` selectors"),
+ * not a sequence of edits applied left to right. A list with NO positive
+ * selector at all, like `["!tag:type-package"]`, means "everything except…",
+ * so an implicit `*` seeds the union in that case only — decided by whether
+ * any entry lacks `!`, never by which entry the list happens to start with.
+ *
+ * This deliberately does NOT reuse `findMatchingProjects`'s
+ * (`../rules/match.mjs`) upstream-Nx rule of checking only `patterns[0]`:
+ * that check is a faithful port of Nx's own `find-matching-projects.js`
+ * (`isExcludePattern(patterns[0])`), and it makes the result depend on
+ * selector ORDER — `["!tag:legacy", "tag:layer:app"]` seeds the wildcard
+ * (exclusion first) and then the later positive selector re-adds a legacy
+ * project the exclusion just removed, while the reverse order never seeds the
+ * wildcard and correctly excludes it. That is upstream Nx's documented
+ * behaviour and stays correct in `../rules/match.mjs`, which exists to match
+ * Nx byte-for-byte; it would be wrong here, where the same list must resolve
+ * the same way regardless of how the author happened to order it.
+ *
+ * @param {string[]} patterns A boundary's `match[]`, already validated.
+ * @param {Record<string, {data?: {root?: string, tags?: string[]}}>} nodes
+ * @returns {string[]} Sorted member names.
+ */
+export function resolveMembers(patterns, nodes) {
+  const positives = patterns.filter((pattern) => !pattern.startsWith("!"));
+  const negatives = patterns.filter((pattern) => pattern.startsWith("!"));
+  const members = new Set();
+  for (const pattern of positives.length > 0 ? positives : ["*"]) {
+    for (const name of selectProjects(pattern, nodes)) members.add(name);
+  }
+  for (const pattern of negatives) {
+    for (const name of selectProjects(pattern, nodes)) members.delete(name);
+  }
+  return Array.from(members).sort();
+}

package/src/canonical.mjs

@@ -0,0 +1,48 @@
+/**
+ * Canonical JSON — the deterministic serialization Contract K's fingerprints
+ * are built on: plain-object keys sorted at every depth so two objects meaning
+ * the same thing serialize identically.
+ *
+ * The one rule that matters: **only plain-object keys are sorted.** Array
+ * element order is never re-ordered, on purpose — for a boundary policy's
+ * `depConstraints` and an intent's `dependencies.forbidden` rows, order is
+ * semantic, and a fingerprint that ignored it could not tell two arrangements
+ * apart. A fingerprint therefore *changes* when rows are re-ordered, which is
+ * correct.
+ *
+ * Used by `computePolicyFingerprint` (`../commands/graph.mjs`), the intent
+ * fingerprint (`./intent-fingerprint.mjs`), and anything else a fingerprint
+ * is computed over — one canonicalizer, in one place, so two serializations
+ * cannot drift.
+ */
+
+/**
+ * Serialize `value` with keys sorted at every object level.
+ *
+ * @param {*} value Any JSON-serializable value.
+ * @returns {string} The canonical serialization.
+ */
+export function canonicalizeJson(value) {
+  return JSON.stringify(value, (key, current) => {
+    if (current !== null && typeof current === "object" && !Array.isArray(current)) {
+      // A null-prototype accumulator, not `{}`: `JSON.parse('{"__proto__":…}')`
+      // produces an OWN key literally named "__proto__" (JSON has no notion of
+      // prototypes), and `sorted[keyName] = …` on an ordinary object treats
+      // that one key specially — it sets the object's prototype instead of
+      // creating an own property, so the key silently vanishes from
+      // `JSON.stringify`'s output. Two documents that disagree only in a
+      // `__proto__` field would then canonicalize identically, a silent
+      // fingerprint collision (`../../../AGENTS.md`, "An empty result is a claim,
+      // not a shrug" — this is the same failure shape: two different inputs
+      // must never produce one indistinguishable output). `Object.create(null)`
+      // has no `__proto__` accessor to intercept the assignment, so every key
+      // — "__proto__" included — always becomes a real own property.
+      const sorted = Object.create(null);
+      for (const keyName of Object.keys(current).sort()) {
+        sorted[keyName] = current[keyName];
+      }
+      return sorted;
+    }
+    return current;
+  });
+}

package/src/commands/README.md

@@ -0,0 +1,266 @@
+# `src/commands/` — one module per CLI command
+
+One module per CLI command, holding the computation and nothing about argv,
+exit codes or where output goes. `../../cli.mjs` owns those three. A module
+here may read the graph, the workspace and the policy; it may not print, and
+it may not decide the process's exit code — it returns a status and `cli.mjs`
+maps it.
+
+`context.mjs` and `policy.mjs` are the exceptions in kind, not in rule: each is
+a preamble the commands share rather than a command. `context.mjs` composes
+`../workspace.mjs`, `../providers/` and `../options.mjs`; it does not
+reimplement any of them. `policy.mjs` holds the one boundary-policy ladder every
+command that reads a law resolves through, so no command grows a second copy of
+the resolution order.
+
+## Commands
+
+- **`check`** (`./check.mjs`'s `check`, driven by `../../cli.mjs`'s `runCheck`) —
+  judges every import site against the boundary rules and folds in every other
+  finding class a verdict counts:
+  declared-edge violations, go.work drift, dead tsconfig path aliases, intent
+  drift, a failing fitness gate, and a failing custom rule
+  (`./custom-rules.mjs`). Exits 1 on any of them, and it is the only
+  command holding all four exit codes
+  ([which verbs carry exit 1 is settled in `docs/concepts/architecture.md`](../../../../docs/concepts/architecture.md)
+  — `fitness` is the other one).
+
+- **`graph`** (`./graph.mjs`'s `graphCommand`) — the project graph as a
+  deterministic, serialisable snapshot: projects (with `targets` and `tags`) and
+  dependencies, each as a flat sorted array. Strips internal fields
+  (`mfeRemote`, `entryPoints`, `declaredPackages`). Includes
+  `workspaceLayout`/`workspaceLayoutSource`. Refuses an Nx workspace with
+  polyglot manifests but no plugin registration. Descriptive: never exits 1.
+
+- **`diff`** (`./diff.mjs`'s `diffCommand`) — two graph snapshots compared edge
+  by edge. Takes a baseline file (not a git ref). When a boundary config is
+  available (via `--config` or the workspace's declared config), also reports
+  which boundary violations the diff introduces and which it resolves — this
+  is narrower than `check`: it checks only `depConstraints` (tag-based), not
+  npm/circular/lazy-load rules that need import-site details.
+  Refuses an incomplete baseline or head.
+  Refuses an Nx workspace with polyglot manifests but no plugin registration.
+  Descriptive: never exits 1.
+
+- **`impact`** (`./impact.mjs`'s `impactCommand`) — reverse reachability from
+  the project graph: given a project name, lists every project that transitively
+  depends on it. Separates direct from transitive dependents. When a boundary
+  config is available, also shows the constraint context for each dependent:
+  which constraint rows govern its edge and whether that edge violates them.
+  Refuses incomplete coverage (whole-file analysis failures).
+  Refuses an Nx workspace with polyglot manifests but no plugin registration.
+  Descriptive: never exits 1.
+
+- **`explain`** (`./explain.mjs`'s `explainCommand`) — the judgment for one import
+  site, explained. Takes a `file:line:column` site, finds the matching import
+  record, and explains: which constraint row matched, which tags applied,
+  whether it is a violation and why. Reports an `UNRESOLVABLE` verdict for a
+  site-level failure (dynamic import with non-literal argument). Refuses an Nx
+  workspace with polyglot manifests but no plugin registration. Descriptive:
+  never exits 1.
+
+- **`context`** (`./context-command.mjs`'s `contextCommand`) — the architecture
+  constraints that apply to one project. Takes a project name and returns the
+  project's tags plus every matching `depConstraints` row, including optional
+  descriptions and remediation guidance. The filename deliberately avoids
+  colliding with `./context.mjs`, which is the shared command preamble. Refuses
+  an Nx workspace with polyglot manifests but no plugin registration.
+  Descriptive: never exits 1.
+
+- **`context --plan`** (`./plan-context-command.mjs`'s `planContextCommand`) —
+  the `--plan` face of the command above: the deterministic facts an agent needs
+  before it reasons about, plans and executes a change, scoped to the target
+  project plus optional paths. Current architecture, the applicable policy rows
+  with their authored description and remediation plus the policy fingerprint,
+  impact (dependents capped, with an explicit overflow note), current
+  violations, go.work and tsconfig-path drift, the canonical architecture-intent
+  verdict, coverage, and the commands that verify the change afterwards. It
+  never generates a plan, decides an implementation strategy, modifies source
+  code, or weakens policy — every field is a fact the tree or the boundary law
+  states, and a section that cannot state one says so (`null`, `[]`, or an
+  explicit `no-verdict`). The rule verdict is computed over the WHOLE
+  analyzeable tree and then filtered to the scoped reporting set, because the
+  circular-dependency and lazy-load rules need the whole file index; that is
+  what makes the verdict correct on every provider. Descriptive: never exits 1.
+
+- **`history`** (`./history.mjs`'s `historyCommand`) — the architecture's
+  evolution across a consumer-managed directory of `graph --format json`
+  snapshots. Reads every snapshot (the directory is the sole source of truth —
+  no index, no database), in filename byte-sort (history) order, and classifies
+  each transition by what the snapshots carry: graph diff (architecture),
+  `policy.fingerprint` (policy/intent), `workspace.provider` (provider), and
+  provenance advance with neither changed (code drift). One-sided or cross-repo
+  signals are disclosed as incomparable rather than read as unchanged.
+  `--capture` writes `<sequence>-<sha8>.json` (deduplicating when the
+  architecture identity already is the last snapshot) and refuses incomplete
+  head coverage. Refuses an empty or unreadable directory, and a snapshot that
+  parses as an incomplete envelope. Descriptive: never exits 1.
+
+- **`provenance`** (`./provenance-command.mjs`'s `provenanceCommand`) — where
+  this run's facts came from and which governance rows carry an origin.
+  Two surfaces: repository provenance (the git commit, remote and dirty state
+  `./provenance.mjs` exposes to every envelope) and decision provenance (each
+  `architecture-intent.json` row and each boundary-config `depConstraints` row,
+  and whether it carries an `origin` record — a row without one is flagged
+  `no origin recorded — cannot attest`). Reads the workspace's OWN declared
+  intent and config, and its own provider via `resolveCommandContext`; never
+  changes a verdict and never exits 1. Refuses out of a malformed intent or
+  boundary config the way `drift` does — a row list built from a file it could
+  not read is a claim about rows that do not exist. Descriptive: never exits 1.
+
+- **`report`** (`./report.mjs`'s `reportCommand`) — one architecture governance
+  document: how healthy the architecture is, and why. Composes `healthCommand`,
+  `waiversCommand`, `fitnessCommand`, the ADR registry (`readAdrContext` plus
+  `resolveDecisionRef`) and `resolveProvenance` — every number through the
+  function that owns it, so no section can disagree with the command it came
+  from — over ONE boundary law `cli.mjs` resolved for the whole page. Links each
+  governed row carrying a `decisionRef` to the record it cites, and each declared
+  fitness gate to the ADRs binding it; a citation that resolves to nothing reads
+  `unknown`, never a pass. `result.uninspectable` names every surface the run
+  could not establish and is what makes the status `no-verdict` (exit 3).
+  Descriptive: never exits 1 — a live violation or a failing gate is reported
+  over exit 0.
+
+- **`discover`** (`./discover.mjs`'s `discoverCommand`) — the observed
+  architecture, and under `--propose` the candidate architecture those
+  observations imply. Builds the observed `{projects, edges}` from the same
+  model `graph`/`drift` read, reports projects/edges/tags plus the coverage a
+  verdict could trust, and optionally drives
+  `../../src/governance/discovery-proposal.mjs`'s pure evaluator over it.
+  Proposal-only: every candidate carries `proposed: true` and
+  `notAuthoritative: true`, and the command never writes
+  `architecture-intent.json`. Returns `status: "no-verdict"` (exit 3) over
+  incomplete coverage and refuses `--propose` over it; refuses an Nx workspace
+  with polyglot manifests but no plugin registration; a zero-project workspace
+  is the empty `unknown` proposal, not a refusal. Descriptive: never exits 1.
+
+- **`drift`** (`./drift.mjs`'s `driftCommand`) — the observed architecture
+  compared against the declared intended one. The intended side is the one
+  canonical contract the workspace declares — `architecture-intent.json` at its
+  root, loaded and judged by the same `../architecture-intent/model.mjs` and
+  `../architecture-intent/judge.mjs` the `check` command uses, so there is no
+  parallel intent grammar and no `intentConfig` option. Reads only the resolved
+  `CommandContext` and never a provider, so the same intent produces the same
+  verdict under Nx, Moon or native. Refuses an intent that cannot be read or
+  parsed, incomplete observed coverage, an Nx workspace with polyglot manifests
+  but no plugin registration, and a boundary or row side that matched no
+  observed project. Resolving each intent row's `decisionRef` against the ADR
+  registry is a separate, NON-VERDICT axis — it never becomes a finding and
+  never changes the exit code — and it is the only thing here that reads the
+  boundary law, so `cli.mjs` hands that load's failure over as `io.configError`
+  rather than throwing it where it happens: rethrown unchanged at the one site
+  that reads the policy when a row does carry a citation, and otherwise stated
+  as a coverage note rather than dropped. Descriptive: never exits 1.
+
+- **`reconcile`** (`./reconcile.mjs`'s `reconcileCommand`) — the two-sided
+  mirror of `drift`: where drift asks which intended rows reality violates,
+  reconcile asks, element by element, what the model says about reality and what
+  it would take to make the two agree. Read-only by design; `--propose` emits a
+  ranked candidate list of model edits — add-only, removal, tag-change,
+  boundary-change — each carrying the evidence that supports it and an explicit
+  `proposed: true` / `notAuthoritative` marker, and the command never writes back
+  into `architecture-intent.json`. Makes the same four refusals `drift` makes,
+  and reads no boundary law, so it makes only those four. Those refusals mean an
+  `unknown` score can only ever come from a whole-file failure the command
+  already refused on — and `../governance/reconcile-score.mjs` marks it anyway,
+  so the scoring module can never render a partial read as a claim on its own.
+  Descriptive: never exits 1 — divergence is described, never gated.
+
+- **`waivers`** (`./waivers.mjs`'s `waiversCommand`) — the whole
+  `boundarySuppressions` surface, read-only: the temporary rows carrying an
+  `expiresAt`, with their remaining term, and the permanent ones carrying none,
+  with what each currently covers. Evaluates the tree with the suppression table
+  REMOVED, so every row's coverage is judged against the full finding set rather
+  than against the run the table already cleaned — a row that covers nothing is
+  named as stale instead of silently doing nothing. A permanent suppression
+  never appears in `check`'s findings at all, which makes this the only surface
+  that names one. Refuses whole-file analysis failures, and refuses an Nx
+  workspace with polyglot manifests but no plugin registration through
+  `./drift.mjs`'s `refuseIncompleteGraph` — the one shared guard for that state —
+  because a row measured against a graph that never drew the workspace's
+  polyglot edges reads as covering nothing it was never shown. The
+  remaining-time column is computed against the injected clock
+  (`../governance/clock.mjs`), so a fixed `now` reproduces the report byte for
+  byte. Descriptive: never exits 1, and it never modifies the table.
+
+- **`fitness`** (`./fitness.mjs`'s `fitnessCommand`) — every declared fitness
+  function judged against the observed workspace, as a verdict table. The
+  functions are the policy's own `fitness` export, validated by `../config.mjs`
+  and judged through `../governance/fitness-registry.mjs`, which reuses the
+  shared member resolution and verdict envelope rather than duplicating a judge,
+  against the same observed facts `check` reads. A verdict rather than a
+  description: a failing function is a finding (exit 1) and an undetermined one
+  is a could-not-determine (exit 3). A function that cannot be determined is
+  `unknown`, never `pass`; one whose `match` selects no project is `skipped` —
+  loud ("declared but matches nothing"), never folded into `pass` — and a
+  `coverage-minimum` row judged from a path-scoped run joins it there, because a
+  scoped run structurally cannot answer a whole-tree coverage question.
+
+- **`health`** (`./health.mjs`'s `healthCommand`) — deterministic
+  architecture-health metrics and trends for the current workspace: violation
+  count, waiver surface, debt rows, coverage ratio, project and edge counts,
+  cycle count, edge density and the intent verdict. Every number is re-derived
+  from records the run already holds, through the same functions
+  `check`/`graph`/`drift` use, so it performs no new scans and cannot disagree
+  with those commands about the same tree. Each metric is decided over complete
+  evidence or says it could not look — no evidence reads `not_applicable`,
+  partial evidence reads `unknown`, and a metric is never reported as a bare
+  zero over evidence the run could not inspect. Trends come from the same
+  snapshot directory `history` reads, limited to what a `graph` snapshot
+  carries. `status` is `"ok"` only when every metric reached a verdict and
+  `"no-verdict"` (exit 3) when any is `unknown`. Descriptive: never exits 1, and
+  purely additive — it changes no other command's verdict or exit code.
+
+- **`debt`** (`./debt.mjs`'s `debtCommand`) — the architecture-debt ledger: the
+  exemptions, gaps and violations a workspace is carrying, each aged across the
+  history directory `history` reads. Computes today's facts the same way
+  `check`/`drift` do — the boundary config's `boundarySuppressions`, and
+  `judgeIntent`'s findings, notes and unresolved — over a config the caller
+  resolved exactly as `diff`'s is, so a debt run and a `check` run never
+  disagree about the current boundary law. Fewer than two snapshots sets
+  `agings: false`, stating that every entry is really age-0 because the record
+  cannot establish age, rather than guessing one. Refuses incomplete graph
+  coverage, an intent that cannot be verified, and a directory that cannot be
+  read or parsed — a missing directory is a no-verdict, never an empty ledger.
+  Descriptive: never exits 1 — a report, not a gate.
+
+- **`adr`** (`./adr.mjs`'s `adrCommand`) — the workspace's recorded architecture
+  decisions and the rule/fitness ids each makes enforceable, read from
+  `docs/adr/NNN-slug.md` at the workspace root
+  (`../governance/adr-registry.mjs` owns the format and the index). With no
+  argument it dumps the whole registry: every record, its status, its
+  supersession chain, and what it binds. Given an id it shows that record, and
+  for a `rule:`/`fitness:`-prefixed ref the reverse lookup naming which ADRs
+  bind it. Needs no project graph, no Nx and no boundary config — the registry
+  is self-contained in the tree, so `resolveCommandContext`'s heavy preamble is
+  skipped and `adr` runs on a tree with no Nx at all. Refuses an unreadable
+  registry and an unresolvable reference; a binding to a fitness id no
+  declaration carries is listed `unknown` — named, never hidden. Descriptive:
+  never exits 1.
+
+## Shared modules
+
+- **`snapshot-meta.mjs`** — `compareSnapshotMetadata`, shared by `diff` and
+  `history`: the provider, provenance (with cross-repo and one-sided
+  detection) and policy-fingerprint comparison between a baseline and a head.
+
+- **`custom-rules.mjs`** — the custom-rules fold `check` runs by presence: each
+  row the policy's `customRules` list declares, loaded from its artifact's bytes
+  and judged over the evidence the run already computed. It owns the file
+  reading the host deliberately does not (`../custom-rules/host.mjs` takes
+  bytes, never a path) and the routing of the host's two failure classes: a
+  LOAD failure throws, so the run refuses the way it refuses a malformed
+  boundary config, and an EVALUATE failure becomes that rule's `unknown`
+  verdict with the host's own reason. A path-scoped run answers
+  `not_applicable` for every declared rule before reading anything, the posture
+  `coverage-minimum` takes for the same reason. Returns the verdict records
+  `check` folds into the fitness exit lanes plus the finding catalogue SARIF's
+  descriptors are built from; it prints nothing and decides no exit code.
+
+- **`edge-constraints.mjs`** — edge-constraint analysis shared by `diff` and
+  `impact`. Judges a single graph edge against the `depConstraints` table,
+  producing violations with their constraint rows. Checks only tag-based rules
+  (`onlyDependOnLibsWithTags`, `notDependOnLibsWithTags`,
+  `projectWithoutTagsCannotHaveDependencies`); npm/circular/lazy-load rules
+  need import-site details that graph edges do not carry. A consumer who needs
+  the complete verdict should run `check`.