@ecoma-io/archkeep 0.16.1 → 0.18.0

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

package/src/commands/trajectory.mjs

@@ -140,6 +140,35 @@ export const INSUFFICIENT_HISTORY = "insufficient_history";
  * @property {number|null} persistent
  */
 
+/**
+ * The trend-facts block: per-class counts and boundary-movement totals over
+ * the SAME comparable transitions the axes count — a pair whose fingerprint
+ * or provenance could not be compared is excluded exactly as it is excluded
+ * from `transitions.unchanged`, so the basis is one consistent subset. Each
+ * class counts once per transition carrying it (a transition may carry
+ * several). `violationsIntroduced`/`violationsResolved` count classes, never
+ * violation rows — and for snapshot-sourced transitions no finding evidence
+ * exists at all, so those totals are `0` with the `note` saying why: the
+ * absence of evidence, never a claim that none occurred (the silent
+ * direction).
+ *
+ * `null` when no trend can be derived: fewer than two observations, or a
+ * history where every transition was incomparable. Never a zero-filled block.
+ *
+ * @typedef {object} TrajectoryTrends
+ * @property {{CHANGE: number, DRIFT: number, VIOLATION: number, REPAIR: number,
+ *   DECISION_CHANGE: number}} byClass One count per evolution class, over
+ *   comparable transitions whose `classifications` carry it.
+ * @property {number} violationsIntroduced
+ * @property {number} violationsResolved
+ * @property {number} comparableTransitions The number of transitions the
+ *   counts were derived over — `transitions.count − transitions.incomparable`.
+ * @property {"comparable transition classifications"} basis What the counts
+ *   are a claim about, stated as a value.
+ * @property {string} [note] A disclosure when the counts cannot speak about
+ *   evidence the input never carried (violation/repair rows).
+ */
+
 /**
  * Aggregates the deterministic trajectory over an ordered snapshot set.
  * Pure: same bytes in, same object out. All keys are always present — shape
@@ -154,7 +183,8 @@ export const INSUFFICIENT_HISTORY = "insufficient_history";
  *   transitions: {count: number, architecture: number, policy: number,
  *     provider: number, codeDrift: number, incomparable: number, unchanged: number},
  *   disclosures: {policyOneSided: number, provenanceOneSided: number, crossRepo: number},
- *   projects: TrajectoryAxis, edges: TrajectoryAxis}}
+ *   projects: TrajectoryAxis, edges: TrajectoryAxis,
+ *   trends: TrajectoryTrends|null}}
  */
 export function computeTrajectory(files) {
   const n = files.length;
@@ -182,6 +212,10 @@ export function computeTrajectory(files) {
   };
   const disclosures = { policyOneSided: 0, provenanceOneSided: 0, crossRepo: 0 };
 
+  /** @type {{CHANGE: number, DRIFT: number, VIOLATION: number, REPAIR: number,
+        DECISION_CHANGE: number}} */
+  const classCounts = { CHANGE: 0, DRIFT: 0, VIOLATION: 0, REPAIR: 0, DECISION_CHANGE: 0 };
+
   // Cumulative transition events, accumulated while classifying. Kept as
   // scalars rather than deferred to a second pass — one walk over the pairs.
   let addedProjectEvents = 0;
@@ -231,15 +265,34 @@ export function computeTrajectory(files) {
       if (record.policyChanged === true) transitions.policy += 1;
       if (record.providerChanged) transitions.provider += 1;
       if (record.codeDrift) transitions.codeDrift += 1;
-
       // The asymmetric-evidence cases, counted from `meta` itself — never
       // parsed back out of the record's prose notes.
       if (meta.policyOneSided) disclosures.policyOneSided += 1;
       if (meta.provenanceOneSided) disclosures.provenanceOneSided += 1;
       if (meta.crossRepo) disclosures.crossRepo += 1;
-      const incomparable = meta.policyOneSided || meta.provenanceOneSided;
+      // The advanced-both-absent pair is the same incomparable case as
+      // one-sided: neither side records the boundary law while the commit
+      // advanced, so the transition carried real code motion the tool cannot
+      // classify (F-HIST-1). `provenanceChanged === true` requires both sides
+      // to record provenance AND the commits to differ, so neither-side-
+      // absent histories (both commits `null`) stay comparable-unchanged.
+      const incomparable =
+        meta.policyOneSided ||
+        meta.provenanceOneSided ||
+        (meta.policyChanged === null && meta.provenanceChanged === true);
       if (incomparable) transitions.incomparable += 1;
 
+      // The trend classes are counted over the SAME comparable subset the
+      // axes already disclose: a pair excluded from `unchanged` because its
+      // fingerprint or provenance could not be compared is excluded from the
+      // trend facts the same way — never silently folded in. Each class is a
+      // fact per transition; a transition carrying several counts in each.
+      if (!incomparable) {
+        for (const cls of record.classifications) {
+          classCounts[cls] += 1;
+        }
+      }
+
       // `unchanged` is deliberately STRICTER than the label `history`'s text
       // renderer prints for the same transition: an aggregate has no
       // per-transition note to disclose "one side carried no fingerprint",
@@ -328,6 +381,38 @@ export function computeTrajectory(files) {
     resolved: available ? edgeMovement.resolved : null,
     persistent: available ? persistentCount(edgePresence) : null,
   };
+  // The trend-facts block. It exists only when comparable evidence exists:
+  // fewer than two observations, or a history whose every transition was
+  // incomparable, yields `null` — never a zero-filled block (a zero would
+  // claim "no change" over evidence this run could not compare). The counts
+  // ride the same classification the axes classify with; both come from
+  // `classifyTransition`'s one walk, so the trends are idempotent: same
+  // snapshots, same object, every run.
+  //
+  // The violation/repair totals are computed from the classification inputs,
+  // and snapshot-sourced transitions carry none: stored snapshots hold the
+  // graph and the policy fingerprint, not findings. Zero there is the absence
+  // of evidence, never a claim that none occurred — the note says so, on
+  // every non-null trends block.
+  /** @type {TrajectoryTrends|null} */
+  let trends = null;
+  if (available) {
+    const comparableTransitions = transitions.count - transitions.incomparable;
+    if (comparableTransitions > 0) {
+      trends = {
+        byClass: classCounts,
+        violationsIntroduced: 0,
+        violationsResolved: 0,
+        comparableTransitions,
+        basis: "comparable transition classifications",
+        note:
+          "transition classifications carry no violation or repair evidence — stored " +
+          "snapshots hold the graph and the policy fingerprint, not findings, so " +
+          "VIOLATION/REPAIR and the violations-* totals are 0 because no finding could " +
+          "be classified, never because none occurred",
+      };
+    }
+  }
 
   return {
     observations: {
@@ -344,6 +429,7 @@ export function computeTrajectory(files) {
     disclosures,
     projects,
     edges,
+    trends,
   };
 }