@ecoma-io/archkeep 0.17.0 → 0.18.0

package/src/commands/explain.mjs

@@ -65,6 +65,19 @@
  * 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.
+ *
+ * ## The lineage comparison (optional, additive)
+ *
+ * `explainCommand` accepts an optional `options.baseRegistry` — a base
+ * ADR registry state to compare the workspace's current one against. When it
+ * is supplied, the resolved-site explanation gains a `decisionChange` field:
+ * whether the decision lineage moved between the two states
+ * (`detectDecisionChange`, `../governance/decision-lineage.mjs` —
+ * DECISION_CHANGE, never DRIFT, and never asserted without both registry
+ * states: a one-sided base renders as a "not comparable" note). Without the
+ * option — every current caller — the explanation is byte-for-byte what it
+ * was: the field, and its rendered lines, exist only when the comparison was
+ * requested.
  */
 import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
@@ -77,6 +90,7 @@ import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { lineage } from "../governance/decision-graph.mjs";
 import { unresolvedDecisionRefNote } from "./provenance-command.mjs";
+import { detectDecisionChange } from "../governance/decision-lineage.mjs";
 import {
   declaredFitnessNames,
   hasAuthority,
@@ -265,6 +279,37 @@ function resolveDecisionChains(matchedConstraints, root, tracked, config) {
   });
 }
 
+/**
+ * The lineage-comparison seam: `detectDecisionChange` fed the caller-supplied
+ * base registry and the workspace's current registry — the same
+ * `readAdrContext` read the decision-chain walk makes, made only when the
+ * caller asked for the comparison. A registry that cannot be read resolves
+ * nothing and says so (the same fail-closed posture the chain walk takes for
+ * the same condition), so a supersession is never asserted from a registry
+ * that was never read.
+ *
+ * @param {{records: object[], byId: Map<string, object>}|null|undefined} baseRegistry
+ *   The base state's registry (a `loadAdrRegistry` result), or `null` for a
+ *   one-sided base — the comparison then discloses "not comparable" instead
+ *   of asserting anything.
+ * @param {string} root The workspace root, for the head registry read.
+ * @param {string[]} tracked Tracked files, for the head registry read.
+ * @returns {{superseded: boolean, comparable: boolean, notes: string[]}}
+ */
+function computeDecisionChange(baseRegistry, root, tracked) {
+  let headRegistry;
+  try {
+    headRegistry = readAdrContext(root, { tracked });
+  } catch (error) {
+    return {
+      superseded: false,
+      comparable: false,
+      notes: [`the decision registry could not be read: ${String(error?.message ?? error)}`],
+    };
+  }
+  return detectDecisionChange(baseRegistry, headRegistry);
+}
+
 /**
  * Runs the `explain` command: resolves the command context, finds the import
  * site, evaluates the rules, and returns the explanation.
@@ -272,12 +317,22 @@ function resolveDecisionChains(matchedConstraints, root, tracked, config) {
  * @param {string} site A `file:line:column` string.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} config The loaded boundary config (from `loadBoundaryConfig`).
+ * @param {object} [options]
+ * @param {{records: object[], byId: Map<string, object>}|null|undefined} [options.baseRegistry]
+ *   The ADR registry at the comparison base (a `loadAdrRegistry` result), or
+ *   `null` for a one-sided base. Supplied, the resolved-site explanation
+ *   also carries a `decisionChange` field — whether the decision lineage
+ *   moved between base and head (the workspace's current registry):
+ *   DECISION_CHANGE, never DRIFT, and never asserted without both registry
+ *   states (one-sided ⇒ a "not comparable" note, `detectDecisionChange`'s
+ *   own contract). Absent — every current caller — the explanation changes
+ *   no byte.
  * @returns {{status: "ok"|"no-verdict", explanation: object, coverage: object,
  *   report: {text: string, json: string}}}
  * @throws {Error} when the plugin is unregistered on a polyglot Nx workspace,
  *   when the site string is malformed, or when the site cannot be found.
  */
-export function explainCommand(site, commandContext, config) {
+export function explainCommand(site, commandContext, config, options = {}) {
   const { root, provider, marker, graph } = commandContext;
 
   // Descriptive commands refuse when the graph is known to be incomplete.
@@ -489,6 +544,20 @@ export function explainCommand(site, commandContext, config) {
     explanation.decisions = decisions;
   }
 
+  // The lineage-comparison seam (Wave 3 §9): when the caller supplies a base
+  // registry, the resolved-site explanation also states whether the decision
+  // lineage moved between base and head — DECISION_CHANGE, never DRIFT, and
+  // never asserted without both registry states (a one-sided base ⇒ a
+  // "not comparable" note, `detectDecisionChange`'s own contract). Absent
+  // the option — every current caller — the explanation changes no byte:
+  // the field and its rendered lines exist only when the comparison was
+  // requested, and an unresolvable site (above) stays what it was.
+  let decisionChange = null;
+  if (options.baseRegistry !== undefined) {
+    decisionChange = computeDecisionChange(options.baseRegistry, root, commandContext.tracked);
+    explanation.decisionChange = decisionChange;
+  }
+
   const context = { root, provider, marker, provenance: resolveProvenance(root) };
   const coverage = {
     complete,
@@ -511,6 +580,7 @@ export function explainCommand(site, commandContext, config) {
     violations,
     verdict,
     ...(decisions.length > 0 ? { decisions } : {}),
+    ...(decisionChange !== null ? { decisionChange } : {}),
   };
 
   const envelope = jsonEnvelope({

package/src/commands/history.mjs

@@ -76,9 +76,10 @@ import { basename, join, resolve } from "node:path";
 
 import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { containmentViolation } from "../containment.mjs";
+import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHistoryReport } from "../report/history-text.mjs";
-import { computeDiff, parseBaseline } from "./diff.mjs";
+import { computeDiff, edgeIdentityKey, parseBaseline } from "./diff.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
@@ -268,11 +269,21 @@ export function nextSequence(read) {
  * `meta`; parsing `notes` strings would be a second copy of the decision
  * wearing a parser's name.
  *
+ * The record's `classifications` are the canonical evolution classes
+ * (`../governance/evolution-event.mjs`'s `classifyEvolution`) computed from
+ * the signals this transition's own record carries — the graph diff rows,
+ * the policy comparison, and the code-drift fact. Stored snapshots carry no
+ * findings, intent rows, debt ledger, or decision registries, so no class is
+ * ever asserted where the input holds no evidence for it (design §2): a
+ * violation, repair, or decision-change class would be a fabricated fact.
+ *
  * @param {{name: string, path: string, envelope: object, id: string}} from
  * @param {{name: string, path: string, envelope: object, id: string}} to
  * @returns {{record: {from: string, to: string, architectureChanged: boolean,
- *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
- *     codeDrift: boolean, notes: string[]},
+ *     changes: object|null, policyChanged: boolean|null,
+ *     policyOneSided: boolean, provenanceChanged: boolean|null,
+ *     providerChanged: boolean, codeDrift: boolean, notes: string[],
+ *     classifications: string[]},
  *   meta: object}} `meta` is `compareSnapshotMetadata`'s result.
  */
 export function classifyTransition(from, to) {
@@ -313,6 +324,15 @@ export function classifyTransition(from, to) {
         "records the boundary law and the other does not",
     );
   }
+  // Mirror of the one-sided rule: neither side records the law while the
+  // commit advanced. The pair carried real code motion the tool cannot
+  // classify, so it is disclosed — never asserted unchanged (F-HIST-1).
+  if (meta.policyChanged === null && meta.provenanceChanged === true) {
+    notes.push(
+      "policy (the declared architectural intent) could not be compared — neither snapshot " +
+        "records the boundary law while the provenance advanced, so code drift cannot be asserted",
+    );
+  }
   if (meta.provenanceOneSided) {
     notes.push(
       "repository provenance could not be compared — one snapshot records its origin and the other does not",
@@ -363,6 +383,55 @@ export function classifyTransition(from, to) {
   const codeDrift =
     !architectureChanged && meta.policyChanged === false && meta.provenanceChanged === true;
 
+  // The canonical classification: one definition (`classifyEvolution`), fed
+  // from the signals this transition's own record carries — the graph diff
+  // rows, the policy comparison, and the code-drift fact. Stored snapshots
+  // carry no findings, intent rows, debt ledger, or decision registries, so
+  // those evidence classes stay absent — a class is never asserted where the
+  // input holds no evidence for it (design §2).
+  const classification = classifyEvolution({
+    observed: {
+      projects: {
+        added: diff.addedProjects.map((project) => project.name),
+        removed: diff.removedProjects.map((project) => project.name),
+        changed: diff.changedProjects.map((project) => project.name),
+      },
+      edges: {
+        added: diff.addedEdges.map(edgeIdentityKey),
+        removed: diff.removedEdges.map(edgeIdentityKey),
+      },
+      policyChanged: meta.policyChanged,
+      policyOneSided: meta.policyOneSided,
+      provenanceChanged: meta.provenanceChanged,
+    },
+    codeDrift,
+  });
+
+  // `classifyEvolution`'s disclosures for snapshot-sourced evidence are the
+  // policy facts the notes above already state (its wording mirrors ours, per
+  // `../governance/evolution-event.mjs`) plus the empty-classification
+  // statement. The statement is appended only where it is true: a pair this
+  // record disclosed as policy-only, one-sided (policy or provenance), or
+  // provider-only is never read as "unchanged" — the same exclusions
+  // `./trajectory.mjs`'s `unchanged` bucket applies. `null` policy with
+  // advancing provenance is the same exclusion: a pair that moved and cannot
+  // be classified is never read as unchanged.
+  if (
+    classification.classifications.length === 0 &&
+    meta.policyChanged !== true &&
+    !meta.policyOneSided &&
+    !meta.provenanceOneSided &&
+    !meta.providerChanged &&
+    !(meta.policyChanged === null && meta.provenanceChanged === true)
+  ) {
+    const statement = classification.notes.find((note) =>
+      note.endsWith("no classification applies"),
+    );
+    if (statement !== undefined) {
+      notes.push(statement);
+    }
+  }
+
   const record = {
     from: from.name,
     to: to.name,
@@ -373,9 +442,14 @@ export function classifyTransition(from, to) {
     // interpretation changed".
     changes: architectureChanged || meta.providerChanged ? diff : null,
     policyChanged: meta.policyChanged,
+    policyOneSided: meta.policyOneSided,
+    provenanceChanged: meta.provenanceChanged,
     providerChanged: meta.providerChanged,
     codeDrift,
     notes,
+    // Appended after every existing key: the classifications are a fact
+    // about the transition, never a change to one of the facts above.
+    classifications: classification.classifications,
   };
   return { record, meta };
 }
@@ -395,8 +469,10 @@ export function classifyTransition(from, to) {
  * @param {{name: string, path: string, envelope: object, id: string}[]} files
  * @returns {{snapshots: {name: string, id: string}[],
  *   transitions: {from: string, to: string, architectureChanged: boolean,
- *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
- *     codeDrift: boolean, notes: string[]}[]}}
+ *     changes: object|null, policyChanged: boolean|null,
+ *     policyOneSided: boolean, provenanceChanged: boolean|null,
+ *     providerChanged: boolean, codeDrift: boolean, notes: string[],
+ *     classifications: string[]}[]}}
  */
 export function computeEvolution(files) {
   const snapshots = files.map((file) => ({ name: file.name, id: file.id }));

package/src/commands/plan-context-command.mjs

@@ -33,6 +33,17 @@
  * - **Intent** — the canonical Architecture Intent verdict (`driftForCheck`,
  *   the object `drift` and `check` share), absent when the workspace declares
  *   no `architecture-intent.json`, no-verdict when one cannot be established.
+ * - **Fitness** — the declared fitness functions that govern this workspace,
+ *   with per-function verdicts (pass/fail/no-verdict) or a note that no
+ *   fitness gates are declared.
+ * - **Waivers** — active boundary waivers, each with its remaining term and
+ *   how many violations it currently covers, plus permanent suppressions.
+ * - **Decisions / ADRs in scope** — the decision lineage: which ADR, rule, or
+ *   fitness record authorises each matched constraint row, resolved where
+ *   possible and listed with their context.
+ * - **Debt** — the architecture-debt snapshot for the target project (when a
+ *   history directory is available): current violations, exemptions, and gaps,
+ *   aged across the snapshot history.
  * - **Coverage / limitations** — complete vs no-verdict, with the exact files
  *   that could not be analyzed.
  * - **Verification commands** — the deterministic commands an agent runs after
@@ -66,6 +77,8 @@ import { collectProjectContext } from "./context-command.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
+import { declaresFitness, fitnessForCheck } from "./fitness.mjs";
+import { computeWaivers } from "./waivers.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
 import { formatPlanContextReport } from "../report/plan-context-text.mjs";
 
@@ -229,10 +242,20 @@ export function collectDrift(commandContext) {
  * @param {string[]} paths Optional workspace-relative paths the change touches.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} config The loaded boundary config.
+ * @param {string|null} [historyDir=null] Optional absolute path to the workspace's
+ *   history directory. When provided, the plan includes the architecture-debt
+ *   snapshot for the target project — current violations, exemptions, and gaps,
+ *   aged across the snapshot history. When absent, the debt section is omitted.
  * @returns {Promise<{status: "ok"|"no-verdict", exitCode: number, coverage: object,
  *   result: object, report: {text: string, json: string}}>}
  */
-export async function planContextCommand(projectName, paths, commandContext, config) {
+export async function planContextCommand(
+  projectName,
+  paths,
+  commandContext,
+  config,
+  historyDir = null,
+) {
   const { root, provider, marker, graph, workspace, pluginGap, tracked } = commandContext;
 
   // The same refusal every descriptive command carries: on an Nx workspace
@@ -269,9 +292,10 @@ export async function planContextCommand(projectName, paths, commandContext, con
   const planDecisionRefRows = projectContext.constraints
     .map((row, index) => ({ kind: `constraints[${index}]`, row }))
     .filter(({ row }) => typeof row?.decisionRef === "string" && row.decisionRef.trim() !== "");
+  let adrContext = null;
   let unresolvedDecisionRefs = new Set();
   if (planDecisionRefRows.length > 0) {
-    const adrContext = readAdrContext(root, { tracked });
+    adrContext = readAdrContext(root, { tracked });
     unresolvedDecisionRefs = new Set(
       // F04: the fitness half resolves against the ids THIS policy declares
       // (`declaredFitnessNames(config)`), never the ADRs' own `bindings`.
@@ -333,6 +357,125 @@ export async function planContextCommand(projectName, paths, commandContext, con
       };
     }
   }
+
+  // Fitness: the declared fitness functions that govern this workspace.
+  // Composed from `fitnessForCheck` (not re-implemented) — the same verdict
+  // `fitness` and `check` share. When the policy declares no fitness
+  // functions, state so honestly rather than omitting the section.
+  let fitness = null;
+  if (declaresFitness(config)) {
+    try {
+      const fitnessResult = fitnessForCheck(commandContext, {
+        rows: config.fitness,
+        intent: intent ?? null,
+        suppressions: config.suppressions ?? [],
+        scoped: false,
+      });
+      fitness = {
+        verified: true,
+        decisions: fitnessResult.decisions,
+        overall: fitnessResult.overall,
+      };
+    } catch (cause) {
+      fitness = {
+        verified: false,
+        decisions: [],
+        overall: { verdict: "no-verdict" },
+        error: `${cause?.message ?? cause}`,
+      };
+    }
+  }
+
+  // Waivers: active boundary waivers from the policy's suppressions table.
+  // Composed from `computeWaivers` — the same function `waivers` and `check`
+  // use. When no suppressions are declared, the section states "none" rather
+  // than omitting the key (the plan contract: every dimension present).
+  const suppressions = config.suppressions ?? [];
+  const waiversResult = suppressions.length > 0 ? computeWaivers(suppressions, wholeVerdict) : null;
+  const waivers =
+    waiversResult === null
+      ? {
+          declared: false,
+          waivers: [],
+          covered: 0,
+          expired: 0,
+          stale: 0,
+          permanentSuppressions: [],
+        }
+      : {
+          declared: true,
+          waivers: waiversResult.waivers,
+          covered: waiversResult.covered,
+          expired: waiversResult.expired,
+          stale: waiversResult.stale,
+          permanentSuppressions: waiversResult.suppressions,
+        };
+
+  // Decisions / ADRs in scope: the positive lineage — which ADRs, rules, or
+  // fitness IDs each matched constraint row cites and successfully resolves
+  // against. The negative case (unresolved refs) already exists above as
+  // `unresolvedDecisionRefs`; this is the resolved half.
+  const decisions = [];
+  if (planDecisionRefRows.length > 0 && adrContext !== null) {
+    for (const { kind, row } of planDecisionRefRows) {
+      const ref = row.decisionRef.trim();
+      if (!unresolvedDecisionRefs.has(ref)) {
+        const record = adrContext.byId.get(ref);
+        decisions.push({
+          decisionRef: ref,
+          kind,
+          resolved: true,
+          record: record
+            ? {
+                id: record.id,
+                title: record.title,
+                status: record.status,
+                ...(record.context ? { context: record.context } : {}),
+              }
+            : null,
+        });
+      }
+    }
+  }
+  decisions.sort((a, b) =>
+    a.decisionRef < b.decisionRef ? -1 : a.decisionRef > b.decisionRef ? 1 : 0,
+  );
+
+  // Architecture debt: the current debt snapshot for the target project, aged
+  // across the snapshot history. Composed from `debtCommand` (not re-implemented)
+  // — the same ledger the `debt` command builds. Present only when a history
+  // directory is available (matching the `intent` pattern: absent when the
+  // workspace has no history, never a claim of zero debt).
+  let debt = null;
+  if (historyDir !== null) {
+    try {
+      const { debtCommand } = await import("./debt.mjs");
+      const debtResult = await debtCommand(historyDir, commandContext, { config });
+      const ledger = debtResult.ledger;
+      debt = {
+        available: true,
+        dir: ledger.dir,
+        snapshots: ledger.snapshots,
+        entries: ledger.entries,
+        resolved: ledger.resolved,
+        total: ledger.total,
+        byKind: ledger.byKind,
+        bySeverity: ledger.bySeverity,
+        agings: ledger.agings,
+        lifecycle: ledger.lifecycle,
+      };
+    } catch (cause) {
+      debt = {
+        available: false,
+        reason: `${cause?.message ?? cause}`,
+        entries: [],
+        total: { open: 0, resolved: 0, total: 0 },
+        byKind: {},
+        bySeverity: {},
+        agings: { meanDays: null, maxDays: null },
+      };
+    }
+  }
   const failures = [...wholeTree.failures, ...drift.failures];
   const notAnalyzed = failures
     .filter(isWholeFileFailure)
@@ -436,6 +579,24 @@ export async function planContextCommand(projectName, paths, commandContext, con
         goWork: goWorkResult(drift.goWork),
         tsconfigPaths: tsconfigPathsResult(drift.tsconfigPaths),
       },
+      // Fitness: the declared fitness functions that govern this workspace.
+      // Present only when the policy declares fitness functions (matching
+      // the pattern: absent when the workspace chose not to declare any).
+      ...(fitness === null ? {} : { fitness }),
+      // Waivers: active boundary waivers and permanent suppressions.
+      // Always present — when no suppressions are declared, `declared: false`
+      // distinguishes "no waivers to show" from "waivers exist but none match".
+      waivers,
+      // Decisions / ADRs in scope: the resolved decision lineage — which
+      // ADRs, rules, or fitness IDs authorise each matched constraint row.
+      // Present only when at least one decision ref resolves; absent when
+      // no constraint row carries a decisionRef or none resolve.
+      ...(decisions.length > 0 ? { decisions } : {}),
+      // Architecture debt: the current debt snapshot for the target project,
+      // aged across the snapshot history. Present only when a history directory
+      // is available (matching the `intent` pattern: absent when the workspace
+      // has no history, never a claim of zero debt).
+      ...(debt === null ? {} : { debt }),
       // The canonical Architecture Intent verdict — the same fold `check` and
       // `drift` report. Absent (key omitted) when no intent file is tracked,
       // matching `check`: intent absence is a workspace decision about

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,
   };
 }