@ecoma-io/archkeep 0.16.1 → 0.18.0

package/src/commands/explain.mjs

@@ -44,6 +44,40 @@
  * 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.
+ *
+ * ## 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";
@@ -53,6 +87,16 @@ 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 { detectDecisionChange } from "../governance/decision-lineage.mjs";
+import {
+  declaredFitnessNames,
+  hasAuthority,
+  resolveDecisionRef,
+  stripAdrPrefix,
+} from "../governance/adr-registry.mjs";
 
 /**
  * Parses a `file:line:column` site string into its components.
@@ -138,6 +182,133 @@ 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) };
+  });
+}
+
+/**
+ * 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
@@ -146,12 +317,22 @@ function findMatchingConstraints(depConstraints, sourceProjectNode) {
  * @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.
@@ -353,6 +534,29 @@ 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;
+  }
+
+  // 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 = {
@@ -375,6 +579,8 @@ export function explainCommand(site, commandContext, config) {
     matchedConstraints,
     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