@ecoma-io/archkeep 0.16.1 → 0.17.0

package/src/commands/explain.mjs

@@ -44,6 +44,27 @@
  * plugin but whose tracked files include polyglot manifests under project
  * roots, `explain` refuses loudly rather than explaining a judgment from a
  * graph whose edges silently under-represent the real architecture.
+ *
+ * ## The "why does this constraint exist" chain
+ *
+ * A constraint row that carries a `decisionRef` claims a governing decision —
+ * an ADR record, or a rule/fitness id the law declares. `explain` resolves
+ * that claim against the workspace's ADR registry and walks it through the
+ * governance graph (`../governance/decision-graph.mjs`), surfacing the
+ * decision's status and authority, its rationale/context prose, and its
+ * supersession lineage — not just the pointer. It is read-only, exactly like
+ * the rest of `explain`: an agent is shown WHY the row exists, never handed
+ * the authority to change the decision or the verdict.
+ *
+ * Resolution never changes the exit code and never invents a fact. A
+ * `decisionRef` that resolves to nothing — or a registry that cannot be read
+ * at all — renders as UNRESOLVED, the same loud wording `check`/`report`
+ * use; a `rule:`/`fitness:`-shaped ref that the law declares renders as
+ * exactly that, a fitness rule this law declares. Only an unresolved site or
+ * incomplete analysis moves `status`, so an unchanged tree pays no changed
+ * exit code. The registry is read lazily, only when a matched row actually
+ * carries a `decisionRef` — the common case (no `docs/adr/` adopted yet)
+ * pays no extra read.
  */
 import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
@@ -53,6 +74,15 @@ import { findProjectForPath, createProjectRootMappings } from "../rules/specifie
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatExplainReport } from "../report/explain-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { readAdrContext } from "./adr.mjs";
+import { lineage } from "../governance/decision-graph.mjs";
+import { unresolvedDecisionRefNote } from "./provenance-command.mjs";
+import {
+  declaredFitnessNames,
+  hasAuthority,
+  resolveDecisionRef,
+  stripAdrPrefix,
+} from "../governance/adr-registry.mjs";
 
 /**
  * Parses a `file:line:column` site string into its components.
@@ -138,6 +168,102 @@ export function findSite(parsed, imports) {
 function findMatchingConstraints(depConstraints, sourceProjectNode) {
   return findConstraintsFor(depConstraints, sourceProjectNode);
 }
+/**
+ * Resolves the "why does this constraint exist" chain for every distinct
+ * `decisionRef` the matched constraint rows carry, in first-sight order.
+ *
+ * A `decisionRef` names the ADR (or rule/fitness id) that authorizes the row.
+ * Resolution is the registry's own (`resolveDecisionRef`); the walk that
+ * surfaces status/authority/rationale/context and lineage is the governance
+ * graph's (`lineage`). Failures are named, never silent:
+ *
+ * - a registry that cannot be read resolves nothing — every ref is `unknown`
+ *   with the read failure as its reason, the same posture `report` takes for
+ *   the same condition;
+ * - a ref that resolves to no ADR, rule, or fitness record the registry knows
+ *   is `unknown`, with `unresolvedDecisionRefNote`'s shared wording.
+ *
+ * Deterministic: matched-row order, distinct refs deduplicated on first
+ * sight, and the walk's own registry (byte-sorted filename) order. Empty when
+ * no matched row carries a `decisionRef` — the caller then changes no byte of
+ * its explanation.
+ *
+ * @param {object[]} matchedConstraints The constraint rows that matched the
+ *   explained site.
+ * @param {string} root The workspace root, for the registry read.
+ * @param {string[]} tracked Tracked files, for the registry read.
+ * @param {object} config The loaded boundary config, for the declared-name
+ *   half of `resolveDecisionRef`.
+ * @returns {object[]} One entry per distinct ref: `resolution` is the
+ *   registry's own `"adr" | "fitness" | "unknown"`; an `"adr"` entry carries
+ *   the record's authority and prose facts plus the lineage walk.
+ */
+function resolveDecisionChains(matchedConstraints, root, tracked, config) {
+  const refs = [];
+  for (const row of matchedConstraints) {
+    if (typeof row?.decisionRef !== "string" || row.decisionRef.trim() === "") continue;
+    if (!refs.includes(row.decisionRef)) refs.push(row.decisionRef);
+  }
+  if (refs.length === 0) return [];
+
+  let registry = null;
+  let registryReason = null;
+  try {
+    registry = readAdrContext(root, { tracked });
+  } catch (error) {
+    registryReason = String(error?.message ?? error);
+  }
+
+  const knownFitness = declaredFitnessNames(config);
+  return refs.map((ref) => {
+    if (registry === null) {
+      return {
+        ref,
+        resolution: "unknown",
+        reason: `the decision registry could not be read: ${registryReason}`,
+      };
+    }
+    const resolution = resolveDecisionRef(registry.byId, knownFitness, ref);
+    if (resolution === "adr") {
+      const record = registry.byId.get(stripAdrPrefix(ref));
+      const recordFacts = { id: record.id, status: record.status };
+      for (const key of [
+        "created",
+        "updated",
+        "context",
+        "decision",
+        "rationale",
+        "alternatives",
+        "consequences",
+        "assumptions",
+      ]) {
+        if (record[key] !== undefined) recordFacts[key] = record[key];
+      }
+      recordFacts.supersedes = record.supersedes;
+      recordFacts.supersededBy = record.supersededBy;
+      recordFacts.bindings = record.bindings;
+      return {
+        ref,
+        resolution: "adr",
+        authority: hasAuthority(record.status),
+        record: recordFacts,
+        lineage: lineage(record.id, {
+          records: registry.records,
+          byId: registry.byId,
+          // The lineage walk reads only `records`/`byId`; the graph walk's
+          // full shape is supplied so the call satisfies the type rather than
+          // leaning on an unchecked subset.
+          knownFitness,
+          rows: [],
+        }),
+      };
+    }
+    if (resolution === "fitness") {
+      return { ref, resolution: "fitness" };
+    }
+    return { ref, resolution: "unknown", reason: unresolvedDecisionRefNote(ref) };
+  });
+}
 
 /**
  * Runs the `explain` command: resolves the command context, finds the import
@@ -353,6 +479,15 @@ export function explainCommand(site, commandContext, config) {
     unresolvable: false,
     reason: null,
   };
+  // The "why does this constraint exist" chain — the governing decision(s)
+  // behind the rows that matched this site, resolved through the ADR registry
+  // and walked through the governance graph (`resolveDecisionChains`'s own
+  // header argues the fail-closed wording and the determinism). Additive: an
+  // explanation whose rows carry no `decisionRef` keeps every byte it had.
+  const decisions = resolveDecisionChains(matchedConstraints, root, commandContext.tracked, config);
+  if (decisions.length > 0) {
+    explanation.decisions = decisions;
+  }
 
   const context = { root, provider, marker, provenance: resolveProvenance(root) };
   const coverage = {
@@ -375,6 +510,7 @@ export function explainCommand(site, commandContext, config) {
     matchedConstraints,
     violations,
     verdict,
+    ...(decisions.length > 0 ? { decisions } : {}),
   };
 
   const envelope = jsonEnvelope({

package/src/commands/provenance-command.mjs

@@ -4,7 +4,7 @@
  * `decisionRef` any of them cite actually resolves to a recorded decision.
  *
  * Provenance is descriptive, exactly like `graph`/`diff`/`drift`: it never
- * changes a verdict, so it never exits 1. It answers three questions:
+ * changes a verdict, so it never exits 1. It answers four questions:
  *
  * 1. **Repository provenance** — the git commit, remote, and dirty state of the
  *    tree this run judged, through the shared `resolveProvenance`
@@ -28,7 +28,20 @@
  *    caller, and a row bound to a nonexistent ADR id read as legitimately
  *    documented everywhere it was rendered. A row with no `decisionRef` is
  *    not a finding here; a row whose `decisionRef` names nothing the registry
- *    knows is.
+ * 4. **Decision lifecycle provenance** — the provenance of the ADR records
+ *    themselves: for every decision in the registry, who created it and who
+ *    last changed it (read from the record file's own git history as
+ *    committed static facts — the author and author-date of the first and
+ *    last commits that touched `docs/adr/<id>.md`), which decision replaced
+ *    which, what constraints it binds, and the committed evidence of its
+ *    current state. The report is read-only: it surfaces the record, it never
+ *    computes or judges a verdict. A decision whose record file has no
+ *    attributable history is flagged `no origin recorded — cannot attest`,
+ *    never silently passed. (PR E —
+ *    https://github.com/ecoma-io/archkeep/issues/491.)
+ *    `recordOrigin`'s `on` never enters here: attribution reads a committed
+ *    author date, it does not produce one, so the injected clock stays out of
+ *    the read path by construction.
  *
  * ## Determinism
  *
@@ -53,15 +66,22 @@
  *
  * An empty `unattested` list must mean exactly "every governance row carries
  * an origin", an empty `unresolvedDecisionRefs` list must mean exactly "every
- * decisionRef citation resolves", and neither means the other.
+ * decisionRef citation resolves", and an empty `decisionLifecycle` list must
+ * mean exactly "the registry holds no decisions" — and neither means the
+ * other.
  */
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatProvenanceReport } from "../report/provenance-text.mjs";
 import { loadIntent } from "../architecture-intent/model.mjs";
 import { loadBoundaryConfig } from "../config.mjs";
-import { resolveProvenance } from "./provenance.mjs";
+import { resolveFileAttribution, resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
-import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
+import {
+  ADR_DIR,
+  declaredFitnessNames,
+  hasAuthority,
+  unresolvedDecisionRefRows,
+} from "../governance/adr-registry.mjs";
 
 /**
  * Whether a row declares a governance origin (`origin.by`/`origin.tool`).
@@ -169,28 +189,41 @@ export function unresolvedDecisionRefNote(decisionRef) {
 }
 
 /**
- * The provenance verdict: three answer surfaces, each fail-closed.
+ * The provenance verdict: four answer surfaces, each fail-closed.
  *
  * `repo` is the git provenance, `established` whether git could answer,
- * `rows`/`unattested` the per-row decision provenance, and
+ * `rows`/`unattested` the per-row decision provenance,
  * `unresolvedDecisionRefs` every row whose `decisionRef` cites no ADR, rule,
- * or fitness record this workspace's registry knows. All three are findings
- * about *documentation*, not about the architecture — this command never
- * changes what `check` or `drift` decide, and it exits 0 when it completes.
+ * or fitness record this workspace's registry knows, and `decisionLifecycle`
+ * the attribution of every recorded decision (its ADR record file's git
+ * history) plus its committed status, authority, timeline, lineage, and
+ * bindings. All four are findings about *documentation*, not about the
+ * architecture — this command never changes what `check` or `drift` decide,
+ * and it exits 0 when it completes.
  *
  * @param {{root: string, tracked: string[], provider: string, marker: string,
  *   options: {boundaryConfig: string|object, inline?: boolean}}} commandContext
  *   From `resolveCommandContext`.
  * @param {{loadIntentOverride?: (root: string, io: object) => Promise<object>,
  *   loadConfigOverride?: (root: string, boundaryConfig: string) => Promise<object>,
- *   loadAdrRegistryOverride?: typeof import("../governance/adr-registry.mjs").loadAdrRegistry}} [io]
- *   `loadAdrRegistryOverride` is forwarded to `readAdrContext` (`./adr.mjs`)
- *   unchanged.
+ *   loadAdrRegistryOverride?: typeof import("../governance/adr-registry.mjs").loadAdrRegistry,
+ *   fileAttribution?: (root: string, file: string) =>
+ *     {createdBy: import("../governance/provenance-record.mjs").OriginRecord,
+ *     lastChangedBy: import("../governance/provenance-record.mjs").OriginRecord} | null}}
+ *   [io] `loadAdrRegistryOverride` is forwarded to `readAdrContext`
+ *   (`./adr.mjs`) unchanged; `fileAttribution` defaults to
+ *   `resolveFileAttribution` (`./provenance.mjs`) and reads a record file's
+ *   commit history as committed static facts.
  * @returns {Promise<{status: "ok", repo: {commit: string|null, remote: string|null,
  *   dirty: boolean|null, established: boolean},
  *   rows: {kind: string, attested: boolean, origin: object|null}[],
  *   unattested: {kind: string, label: string, note: string}[],
  *   unresolvedDecisionRefs: {kind: string, label: string, decisionRef: string, note: string}[],
+ *   decisionLifecycle: {id: string, status: string, authority: boolean,
+ *     created: string|null, updated: string|null, supersedes: string[],
+ *     supersededBy: string[], bindings: string[],
+ *     attribution: {createdBy: object|null, lastChangedBy: object|null},
+ *     attested: boolean, note: string|null}[],
  *   report: {text: string, json: string}}>}
  * @throws {Error} on a malformed intent, boundary config, or ADR registry —
  *   exit 3, the loud refusal every command that reads them makes.
@@ -274,6 +307,38 @@ export async function provenanceCommand(commandContext, io = {}) {
     note: unresolvedDecisionRefNote(decisionRef),
   }));
 
+  // PR E — decision lifecycle provenance: every recorded decision's current
+  // state (status, authority, committed timeline, lineage, bindings),
+  // attributed with WHO recorded it. Attribution reads the record file's own
+  // git history as committed static facts (first commit = createdBy, last =
+  // lastChangedBy) — a read, never a produced `on`, so no clock and no
+  // wall-clock time enter. When git cannot answer, the fact is named
+  // cannot-attest below, never silently passed.
+  const attributor = io.fileAttribution ?? resolveFileAttribution;
+  const decisionLifecycle = [];
+  for (const record of adrContext.records) {
+    const attribution = attributor(root, `${ADR_DIR}/${record.id}.md`);
+    const supersedes = Array.isArray(record.supersedes) ? record.supersedes : [];
+    const supersededBy = Array.isArray(record.supersededBy) ? record.supersededBy : [];
+    const bindings = Array.isArray(record.bindings) ? record.bindings : [];
+    decisionLifecycle.push({
+      id: record.id,
+      status: record.status,
+      authority: hasAuthority(record.status),
+      created: record.created ?? null,
+      updated: record.updated ?? null,
+      supersedes,
+      supersededBy,
+      bindings,
+      attribution: {
+        createdBy: attribution?.createdBy ?? null,
+        lastChangedBy: attribution?.lastChangedBy ?? null,
+      },
+      attested: attribution !== null,
+      note: attribution === null ? "no origin recorded — cannot attest" : null,
+    });
+  }
+
   const establishment = repo !== null;
   const repoResult = establishment ? repo : { commit: null, remote: null, dirty: null };
   const rowsTotal = rowList.length;
@@ -292,6 +357,7 @@ export async function provenanceCommand(commandContext, io = {}) {
     unattested,
     decisionRefTotal: decisionRefRows.length,
     unresolvedDecisionRefs,
+    decisionLifecycle,
   });
 
   const context = {
@@ -314,9 +380,10 @@ export async function provenanceCommand(commandContext, io = {}) {
       blindSpots: [],
       notes: [],
     },
-    // The three answer surfaces; `result.rows` preserves the canonical row
-    // order. `unresolvedDecisionRefs` is unconditional, like `unattested` —
-    // an empty array is itself the claim "every citation resolves", never an
+    // The four answer surfaces; `result.rows` preserves the canonical row
+    // order. `unresolvedDecisionRefs` and `decisionLifecycle` are both
+    // unconditional, like `unattested` — an empty array is itself the claim
+    // "every citation resolves"/"the registry holds no decisions", never an
     // omitted key that would leave a reader unable to tell "checked, clean"
     // from "never checked" (`../../../../AGENTS.md`).
     result: {
@@ -329,13 +396,14 @@ export async function provenanceCommand(commandContext, io = {}) {
       })),
       unattested: unattested.map(({ kind, label, note }) => ({ kind, label, note })),
       unresolvedDecisionRefs,
+      decisionLifecycle,
     },
   });
 
   return {
     status: "ok",
     repo: { ...repoResult, established: establishment },
-    // The three answer surfaces, also available readably (not only inside the
+    // The four answer surfaces, also available readably (not only inside the
     // envelope) so `cli.mjs` can drive the text report from the same facts.
     rows: rowList.map(({ kind, attested, origin }) => ({
       kind,
@@ -344,6 +412,7 @@ export async function provenanceCommand(commandContext, io = {}) {
     })),
     unattested: unattested.map(({ kind, label, note }) => ({ kind, label, note })),
     unresolvedDecisionRefs,
+    decisionLifecycle,
     report: {
       text: reportText,
       json: renderJson(envelope),

package/src/commands/provenance.mjs

@@ -120,3 +120,63 @@ export function resolveProvenance(root) {
 
   return { commit, remote, dirty };
 }
+/**
+ * Resolves the git attribution of ONE file under `root`: the origin that
+ * CREATED it and the origin that LAST CHANGED it, read from commit metadata.
+ *
+ * Both are committed static facts — an author name, email, and author date
+ * frozen in the repository's history — so the answer is byte-identical across
+ * every run over the same tree, and no wall-clock time and no injected clock
+ * ever enter (the determinism rule `resolveProvenance` states above). The
+ * origin shape is the same one a governance row carries: `by` names the
+ * author, `tool` is `"git"` (the commit records the change; the tool behind
+ * the commit is unknowable from the bytes), and `on` is the commit's author
+ * date — READ, not produced, which is exactly the read surface
+ * `../governance/provenance-record.mjs` already documents: an `on` is only
+ * ever written by `recordOrigin`, and a committed `on` is its own read fact.
+ *
+ * Returns `null` when git cannot answer (not a repository) or the file has
+ * never been committed — the reader then renders
+ * `no origin recorded — cannot attest` rather than pretending an author.
+ * A file whose history is missing is a legitimate "no claim" state, not the
+ * loud could-not-look a commitless repository is: `resolveProvenance` owns
+ * that refusal, and this reads only after a repository is established.
+ *
+ * @param {string} root The workspace root directory.
+ * @param {string} file The tracked file whose history is attributed, relative
+ *   to `root` (e.g. `docs/adr/0001-boundary-levels.md`).
+ * @returns {{createdBy: import("../governance/provenance-record.mjs").OriginRecord,
+ *   lastChangedBy: import("../governance/provenance-record.mjs").OriginRecord} | null}
+ */
+export function resolveFileAttribution(root, file) {
+  // First, the "is this even a git repository at all" question — the same
+  // probe `resolveProvenance` runs, so a non-repository is a clean `null`
+  // (no claim) rather than a thrown error here.
+  try {
+    runProcess("git", ["rev-parse", "--is-inside-work-tree"], root);
+  } catch {
+    return null;
+  }
+  let log;
+  try {
+    // Oldest-first (`--reverse`), so the first line is the creator. `%aI` is
+    // the strict ISO-8601 author date (no locale-dependent formatting), and
+    // NUL separators keep a name containing spaces or a newline parseable.
+    // `--` ends option parsing so a file name beginning with `-` is safe.
+    log = runProcess("git", ["log", "--reverse", "--format=%an%x00%ae%x00%aI", "--", file], root);
+  } catch {
+    // Not a repository, or the file path is unreadable — either way, no
+    // attributable history to claim. Null, not a thrown error.
+    return null;
+  }
+  const lines = log.split("\n").filter((line) => line.length > 0);
+  if (lines.length === 0) return null; // the file was never committed
+  const parse = (line) => {
+    const [name, email, on] = line.split("\u0000");
+    return { by: `${name} <${email}>`, tool: "git", on };
+  };
+  return {
+    createdBy: parse(lines[0]),
+    lastChangedBy: parse(lines[lines.length - 1]),
+  };
+}

package/src/commands/report.mjs

@@ -126,6 +126,8 @@ import {
   resolveDecisionRef,
   stripAdrPrefix,
 } from "../governance/adr-registry.mjs";
+import { computeDecisionFitness } from "../governance/decision-fitness.mjs";
+import { hasAuthority, stripRuleFitnessPrefix } from "../governance/adr-registry.mjs";
 
 /**
  * The message a thrown refusal carries, as the report's reason for a surface
@@ -442,6 +444,24 @@ export async function reportCommand(commandContext, io = {}) {
   // Those two must never read alike (`../report/report-text.mjs` renders both
   // and says the same).
   const unresolvedCitation = citations.some((citation) => citation.resolution === "unknown");
+  // The per-record fitness derivation. It is the same function `adr` runs
+  // over the same registry, folded here with THIS run's declared gates: the
+  // verdicts of the `fitness` surface above (same `{name, verdict}` shape
+  // `fitnessCommand` emits) are the ONLY door — a citation resolves against
+  // declared ids (F04), and a record's own bound id must match one to be
+  // verified. `computeDecisionFitness`'s second argument exists to carry
+  // verdicts but is unused by design: the lookup is the single door, so it is
+  // `null`, exactly as `adr` passes it. An empty verdict set is legitimate:
+  // every authority record then derives `unverifiable` — the registry alone
+  // asserts nothing, never a clean pass (the invariant).
+  const fitnessById = new Map(
+    computeDecisionFitness(registry === null ? [] : registry.records, null, (bindingId) => {
+      const stripped = stripRuleFitnessPrefix(bindingId);
+      const gate = fitness.functions.find((fn) => fn.name === stripped);
+      return gate === undefined ? undefined : { name: gate.name, verdict: gate.verdict };
+    }).map((entry) => [entry.id, entry]),
+  );
+
   const decisions = {
     verdict:
       registry === null
@@ -463,11 +483,38 @@ export async function reportCommand(commandContext, io = {}) {
         : registry.records.map((record) => ({
             id: record.id,
             status: record.status,
+            authority: hasAuthority(record.status),
             bindings: [...record.bindings],
+            // The per-decision fitness level from the derivation above. A
+            // record binding nothing this run's gates declared derives
+            // `unverifiable` — the registry alone asserts nothing.
+            fitness: fitnessById.get(record.id),
+            // The governed rows (intent + constraint) that CITATION this
+            // record as their authority — the "who stands on this decision"
+            // answer, filtered from the same citation walk above.
+            constraints: citations
+              .filter(
+                (citation) =>
+                  citation.resolution === "adr" &&
+                  citation.adr !== null &&
+                  citation.adr.id === record.id,
+              )
+              .map((citation) => ({ kind: citation.kind, label: citation.label })),
           })),
     citations,
+    // The citations that could not be resolved — every one is already a
+    // governed row that holds the document back (they feed `unresolvedCitation`
+    // and `uninspectable` above); this materializes them for the text face so
+    // a reader sees which rows, not only that one was missing.
+    unresolvedDecisionRefs: citations
+      .filter((citation) => citation.resolution === "unknown")
+      .map((citation) => ({
+        kind: citation.kind,
+        label: citation.label,
+        decisionRef: citation.decisionRef,
+        reason: unresolvedDecisionRefNote(citation.decisionRef),
+      })),
   };
-
   // ── Provenance ────────────────────────────────────────────────────────
   // Where this run's facts came from. `null` is git's honest "no origin
   // claim", printed as such and never folded into a commit this run cannot