@ecoma-io/archkeep 0.16.1 → 0.17.0

package/src/governance/decision-graph.mjs

@@ -0,0 +1,483 @@
+/**
+ * The decision governance graph: a pure, descriptive, bidirectional walk over
+ * decisions (the ADR registry's records), the intent/constraint/fitness rows
+ * they govern, the projects those rows govern, and the projects' current
+ * findings.
+ *
+ * It answers the two directions of one question — "what does this decision
+ * make enforceable, and what does that enforcement currently see?" and "what
+ * decision governs this row/project/finding, and why was it made?" — as one
+ * pure data shape: `{ok, nodes, edges, unresolved}`.
+ *
+ * ## Descriptive by contract (Wave 2 scope)
+ *
+ * This module NEVER gates. It decides nothing about whether a finding IS one
+ * (the rule that produced it owns that, `../report/evidence.mjs`'), never
+ * changes `check`'s exit code, and never turns green or red on its own. It
+ * reports the graph the registry and the caller's row/finding facts describe
+ * — or, where a reference cannot resolve, names the gap. The `adr`/`report`
+ * surface of the wave renders the walk; nothing here is a verdict.
+ *
+ * ## The invariant
+ *
+ * The repository's governing rule (`../../../../AGENTS.md`): an empty result
+ * must mean "no violation", and nothing else. For a walk that means an
+ * `unresolved` list is the only honest answer to a reference that cannot
+ * resolve:
+ *
+ * - an unknown decision id, a `binding` that names no governed row, a row
+ *   citing a decision that does not exist, a missing findings lookup, a row
+ *   or finding with no governing decision — every one lands in `unresolved`
+ *   with its `ref`, a `kind`, and a reason, and `ok` is false. A walk never
+ *   returns an empty-looking `nodes: []` over a reference it could not
+ *   resolve.
+ * - a reference that DID resolve and genuinely has nothing attached — a
+ *   decision that binds no rule and is cited by no row — is a true fact and
+ *   stays `ok: true`: the walk looked, and what it found is that nothing is
+ *   bound.
+ *
+ * ## Determinism
+ *
+ * No wall-clock time, no randomness, no environment. Iteration follows the
+ * caller's data orders — `records` in registry (byte-sorted filename) order,
+ * `rows` in the order given, each record's `bindings`/`supersedes` in the
+ * order the record declares — and nodes/edges/unresolved are emitted in
+ * first-discovery order, so two runs over the same context produce
+ * byte-identical output.
+ *
+ * ## Injection, never IO
+ *
+ * The module reads no files. The context — the registry index
+ * (`./adr-registry.mjs`'s `readAdrContext` returns `records`/`byId`), the
+ * workspace's declared rule/fitness ids (`declaredFitnessNames(config)`), the
+ * governed rows, and the findings lookups — is assembled by the caller (Wave
+ * 2's report/adr surface), so the walk is a pure function of facts, testable
+ * on in-memory fixtures.
+ *
+ * ## The two name spaces, resolved the way the registry resolves them
+ *
+ * Decision references are the registry's: an ADR id (`0002-case`, or the
+ * documented `adr:` spelling `stripAdrPrefix` handles). Rule/fitness ids are
+ * the declared-name space `declaredFitnessNames` owns, with the documented
+ * `rule:`/`fitness:` prefixes `stripRuleFitnessPrefix` handles. Both helpers
+ * (and `resolveDecisionRef`, the classification every other surface shares)
+ * come from `./adr-registry.mjs` — this walk consumes the registry's meaning,
+ * never a second opinion about what a reference names. Normalization for row
+ * matching applies the same documented aliases: a record binding `hotspot`
+ * and a row id `fitness:hotspot` name the same thing, exactly as a
+ * `decisionRef` of either spelling resolves identically everywhere else.
+ */
+
+import { resolveDecisionRef, stripAdrPrefix, stripRuleFitnessPrefix } from "./adr-registry.mjs";
+
+/**
+ * One governed row the walk knows: an intent row, a boundary constraint row,
+ * or a fitness rule, each carrying the governance block the wave's shared
+ * row schema (`./row-schema.mjs`) validates. The caller assembles this list
+ * from the surfaces it owns — `architecture-intent.json` rows, the boundary
+ * law's `depConstraints`, the declared `fitness` list — so the walk never
+ * reads a row itself.
+ *
+ * @typedef {object} GovernedRow
+ * @property {string} id The row's own reference — an intent-row label
+ *   (`projects.required[0]`) or a rule/fitness id (`rule:keep-a`,
+ *   `fitness:hotspot`, or the bare `hotspot` spelling).
+ * @property {"intent"|"constraint"|"fitness"} kind What kind of row it is.
+ * @property {string} [decisionRef] The decision that makes the row
+ *   enforceable — an ADR id (bare or `adr:`-prefixed), or a rule/fitness id
+ *   naming a decision that binds it.
+ * @property {string[]} [governs] The project/part ids this row governs.
+ */
+
+/**
+ * The facts a walk is a pure function of. Registry-shaped values come
+ * straight from `./adr-registry.mjs`'s `readAdrContext` and
+ * `declaredFitnessNames`; the rows and findings come from the caller.
+ *
+ * @typedef {object} GraphWalkContext
+ * @property {object[]} records The validated records, in registry order.
+ * @property {Map<string, object>} byId The registry index.
+ * @property {Set<string>} knownFitness Rule/fitness ids the workspace
+ *   declares (`declaredFitnessNames(config)`).
+ * @property {GovernedRow[]} rows The governed rows this workspace carries.
+ * @property {(projectId: string) => object[]} [findingsByProject] The current
+ *   findings/evidence for a project. Required for a forward walk's
+ *   "current findings" leg; when absent, the walk cannot claim a project has
+ *   no findings and says so in `unresolved`.
+ * @property {Map<string, object>} [findingsById] Finding id -> finding record,
+ *   for the reverse walk's finding route. A finding record must carry at
+ *   least `id`, `project`, and `ruleId`; any further fields pass through
+ *   untouched in the finding node's `data`.
+ */
+
+/**
+ * @typedef {"decision"|"intent"|"constraint"|"fitness"|"project"|"finding"} GraphNodeKind
+ * @typedef {object} GraphNode
+ * @property {string} id
+ * @property {GraphNodeKind} kind
+ * @property {string} label
+ * @property {object} [data]
+ * @typedef {"decisionRef"|"binding"|"governs"|"finding"|"supersedes"} GraphEdgeKind
+ * @typedef {object} GraphEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {GraphEdgeKind} kind
+ * @typedef {"decision"|"intent"|"constraint"|"fitness"|"project"|"finding"|"rule"|"binding"} UnresolvedKind
+ * @typedef {object} UnresolvedRef
+ * @property {string} ref The reference that did not resolve.
+ * @property {UnresolvedKind} kind What the walk was trying to resolve.
+ * @property {string} reason Why it cannot.
+ * @typedef {object} GraphWalk
+ * @property {boolean} ok False iff `unresolved` is non-empty — a walk that
+ *   could not resolve every reference it met never looks like a walk that
+ *   found nothing.
+ * @property {GraphNode[]} nodes
+ * @property {GraphEdge[]} edges
+ * @property {UnresolvedRef[]} unresolved
+ */
+
+/** A fresh, empty walk — `ok: true` until the first unresolved reference. */
+function newWalk() {
+  const walk = { ok: true, nodes: [], edges: [], unresolved: [] };
+  const nodeIds = new Set();
+  const edgeKeys = new Set();
+  const unresolvedKeys = new Set();
+  return {
+    walk,
+    node(id, kind, label, data) {
+      if (nodeIds.has(id)) return;
+      nodeIds.add(id);
+      walk.nodes.push(data === undefined ? { id, kind, label } : { id, kind, label, data });
+    },
+    edge(from, to, kind) {
+      const key = `${from}\u0000${kind}\u0000${to}`;
+      if (edgeKeys.has(key)) return;
+      edgeKeys.add(key);
+      walk.edges.push({ from, to, kind });
+    },
+    unresolved(ref, kind, reason) {
+      const key = `${kind}\u0000${ref}`;
+      if (unresolvedKeys.has(key)) return;
+      unresolvedKeys.add(key);
+      walk.ok = false;
+      walk.unresolved.push({ ref, kind, reason });
+    },
+  };
+}
+
+/** The decision node a record contributes, with the record's own facts. */
+function decisionNode(record) {
+  const data = { status: record.status };
+  for (const key of [
+    "created",
+    "updated",
+    "context",
+    "decision",
+    "rationale",
+    "alternatives",
+    "consequences",
+    "assumptions",
+  ]) {
+    if (record[key] !== undefined) data[key] = record[key];
+  }
+  if (record.supersedes.length > 0) data.supersedes = record.supersedes;
+  if ((record.supersededBy ?? []).length > 0) data.supersededBy = record.supersededBy;
+  return { id: record.id, kind: "decision", label: record.id, data };
+}
+
+/** `id`, with the documented `adr:` prefix stripped — the registry key. */
+function decisionIdOf(ref) {
+  return stripAdrPrefix(ref);
+}
+
+/**
+ * The records whose `bindings` name `target`, normalized by the same
+ * `rule:`/`fitness:` aliases the registry's own resolution applies.
+ */
+function bindingRecords(records, target) {
+  return records.filter((record) =>
+    record.bindings.some((binding) => stripRuleFitnessPrefix(binding) === target),
+  );
+}
+
+/** The derived reverse-lineage index every walk builds for itself. */
+function supersededByIndex(records) {
+  const index = new Map();
+  for (const record of records) {
+    for (const ref of record.supersedes) {
+      const list = index.get(ref) ?? [];
+      list.push(record.id);
+      index.set(ref, list);
+    }
+  }
+  return index;
+}
+
+/**
+ * Adds a record's node and the full supersession chain in both directions —
+ * `supersedes` forward, derived `supersededBy` backward — cycle-safe (a
+ * `visited` set; a raw, hand-built context can present a cycle the registry
+ * would have refused, and the walk must still terminate).
+ */
+function attachLineage(g, record, ctx) {
+  const index = supersededByIndex(ctx.records);
+  const visited = new Set();
+  const queue = [record.id];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const current = ctx.byId.get(id);
+    if (current === undefined) {
+      g.unresolved(
+        id,
+        "decision",
+        `"${id}" is named in a supersession chain but no matching ADR record is in the registry`,
+      );
+      continue;
+    }
+    g.node(current.id, "decision", current.id, decisionNode(current).data);
+    for (const next of current.supersedes) {
+      g.edge(current.id, next, "supersedes");
+      if (!visited.has(next)) queue.push(next);
+    }
+    for (const next of index.get(current.id) ?? []) {
+      g.edge(next, current.id, "supersedes");
+      if (!visited.has(next)) queue.push(next);
+    }
+  }
+}
+
+/**
+ * Every decision that governs `row`, in discovery order: the decision its
+ * `decisionRef` names (an ADR record, or — for a `rule:`/`fitness:`-shaped
+ * citation — the decisions whose `bindings` carry that id), plus every
+ * decision whose `bindings` name the row's own id. A citation that resolves
+ * to nothing lands in `unresolved`, never in a silent skip.
+ *
+ * @returns {number} How many governing decisions were attached.
+ */
+function governingDecisionsFor(g, row, ctx) {
+  let count = 0;
+  const decisionRef = row.decisionRef;
+  if (typeof decisionRef === "string" && decisionRef.trim() !== "") {
+    const resolution = resolveDecisionRef(ctx.byId, ctx.knownFitness, decisionRef);
+    if (resolution === "adr") {
+      const record = ctx.byId.get(decisionIdOf(decisionRef));
+      attachLineage(g, record, ctx);
+      g.edge(row.id, record.id, "decisionRef");
+      count += 1;
+    } else if (resolution === "fitness") {
+      const target = stripRuleFitnessPrefix(decisionRef);
+      for (const record of bindingRecords(ctx.records, target)) {
+        attachLineage(g, record, ctx);
+        g.edge(record.id, row.id, "binding");
+        count += 1;
+      }
+    } else {
+      g.unresolved(
+        decisionRef,
+        "decision",
+        `${row.id} cites "${decisionRef}", which does not resolve — no matching ADR, rule, or fitness record`,
+      );
+    }
+  }
+  const target = stripRuleFitnessPrefix(row.id);
+  for (const record of bindingRecords(ctx.records, target)) {
+    attachLineage(g, record, ctx);
+    g.edge(record.id, row.id, "binding");
+    count += 1;
+  }
+  return count;
+}
+
+/** Adds a governed row's node plus its governed projects and their findings. */
+function attachRowLeg(g, row, ctx) {
+  g.node(row.id, row.kind, row.id);
+  for (const projectId of row.governs ?? []) {
+    g.node(projectId, "project", projectId);
+    g.edge(row.id, projectId, "governs");
+    if (ctx.findingsByProject === undefined) {
+      g.unresolved(
+        projectId,
+        "project",
+        `the context provides no findingsByProject lookup — the walk cannot claim "${projectId}" has no findings`,
+      );
+      continue;
+    }
+    for (const finding of ctx.findingsByProject(projectId)) {
+      g.node(finding.id, "finding", finding.id, finding);
+      g.edge(projectId, finding.id, "finding");
+    }
+  }
+}
+
+/**
+ * Forward walk: a decision -> the governed rows that attach to it (rows whose
+ * `decisionRef` names it — bare or `adr:`-prefixed — plus the rows whose ids
+ * its `bindings` name) -> the projects/parts those rows govern -> the
+ * projects' current findings/evidence, all read-only.
+ *
+ * Every hop that cannot resolve is reported: an unknown decision id, a
+ * binding that names no governed row, a governed project the context cannot
+ * produce findings for. A decision that resolves and attaches nothing is the
+ * true fact "recorded but not enforceable", and stays `ok: true`.
+ *
+ * @param {string} decisionId An ADR id (`0002-case`, or `adr:0002-case`).
+ * @param {GraphWalkContext} ctx
+ * @returns {GraphWalk}
+ */
+export function forwardDecision(decisionId, ctx) {
+  const g = newWalk();
+  const record = ctx.byId.get(decisionIdOf(decisionId));
+  if (record === undefined) {
+    g.unresolved(
+      decisionId,
+      "decision",
+      `"${decisionId}" does not resolve — no matching ADR record in the registry`,
+    );
+    return g.walk;
+  }
+  g.node(record.id, "decision", record.id, decisionNode(record).data);
+
+  const boundIds = new Set(record.bindings.map((binding) => stripRuleFitnessPrefix(binding)));
+  for (const row of ctx.rows) {
+    const viaDecisionRef =
+      typeof row.decisionRef === "string" &&
+      resolveDecisionRef(ctx.byId, ctx.knownFitness, row.decisionRef) === "adr" &&
+      decisionIdOf(row.decisionRef) === record.id;
+    const viaBinding = boundIds.has(stripRuleFitnessPrefix(row.id));
+    if (!viaDecisionRef && !viaBinding) continue;
+    attachRowLeg(g, row, ctx);
+    if (viaDecisionRef) g.edge(row.id, record.id, "decisionRef");
+    if (viaBinding) g.edge(record.id, row.id, "binding");
+  }
+
+  for (const binding of record.bindings) {
+    const target = stripRuleFitnessPrefix(binding);
+    if (!ctx.rows.some((row) => stripRuleFitnessPrefix(row.id) === target)) {
+      g.unresolved(
+        binding,
+        "binding",
+        `"${binding}" is bound by ${record.id} but no governed row in the context carries that id`,
+      );
+    }
+  }
+  return g.walk;
+}
+
+/**
+ * Reverse walk: a constraint/finding/rule id — a `rule:` id, a `fitness:` id,
+ * an intent-row label, or a finding id — -> the decision(s) that govern it
+ * (via the rows' `decisionRef` citations and the decisions' `bindings`) ->
+ * each governing decision's rationale/context/lineage/status, all read-only.
+ *
+ * A reference that matches nothing, a row whose `decisionRef` does not
+ * resolve, and a row or finding no decision binds or cites are all reported
+ * in `unresolved` — a reverse walk never answers "no decision governs this"
+ * about a reference it could not establish.
+ *
+ * @param {string} rowRef The id to walk back from.
+ * @param {GraphWalkContext} ctx
+ * @returns {GraphWalk}
+ */
+export function reverseRow(rowRef, ctx) {
+  const g = newWalk();
+
+  const row = ctx.rows.find((candidate) => candidate.id === rowRef);
+  if (row !== undefined) {
+    g.node(row.id, row.kind, row.id);
+    const governing = governingDecisionsFor(g, row, ctx);
+    if (governing === 0) {
+      g.unresolved(
+        rowRef,
+        "row",
+        `"${rowRef}" is governed by no decision — no decisionRef cites the row and no decision binds its id`,
+      );
+    }
+    return g.walk;
+  }
+
+  const finding = ctx.findingsById?.get(rowRef);
+  if (finding !== undefined) {
+    g.node(finding.id, "finding", finding.id, finding);
+    let governing = 0;
+    for (const candidate of ctx.rows) {
+      if ((candidate.governs ?? []).includes(finding.project)) {
+        governing += governingDecisionsFor(g, candidate, ctx);
+      }
+    }
+    const ruleId = stripRuleFitnessPrefix(finding.ruleId ?? "");
+    for (const record of bindingRecords(ctx.records, ruleId)) {
+      attachLineage(g, record, ctx);
+      g.edge(record.id, finding.id, "binding");
+      governing += 1;
+    }
+    if (governing === 0) {
+      g.unresolved(
+        rowRef,
+        "finding",
+        `"${rowRef}" is governed by no decision — no row governing its project cites one and no decision binds rule "${ruleId}"`,
+      );
+    }
+    return g.walk;
+  }
+
+  if (rowRef.startsWith("rule:") || rowRef.startsWith("fitness:")) {
+    const kind = rowRef.startsWith("rule:") ? "rule" : "fitness";
+    const target = stripRuleFitnessPrefix(rowRef);
+    let governing = 0;
+    for (const candidate of ctx.rows) {
+      if (stripRuleFitnessPrefix(candidate.id) === target) {
+        g.node(candidate.id, candidate.kind, candidate.id);
+        governing += governingDecisionsFor(g, candidate, ctx);
+      }
+    }
+    for (const record of bindingRecords(ctx.records, target)) {
+      attachLineage(g, record, ctx);
+      g.edge(record.id, rowRef, "binding");
+      governing += 1;
+    }
+    if (governing === 0) {
+      g.unresolved(
+        rowRef,
+        kind,
+        `"${rowRef}" does not resolve — no governed row carries that id and no decision binds it`,
+      );
+    }
+    return g.walk;
+  }
+
+  g.unresolved(
+    rowRef,
+    "row",
+    `"${rowRef}" does not resolve — no governed row, finding, rule, or fitness id carries it`,
+  );
+  return g.walk;
+}
+
+/**
+ * Lineage walk: the full supersession chain of a decision, `supersedes`
+ * forward and derived `supersededBy` backward, cycle-safe and deterministic
+ * (registry order, first-discovery emission). An unknown start id — and a
+ * chain that names a record the registry does not hold — is reported in
+ * `unresolved`, never as an empty chain.
+ *
+ * @param {string} decisionId An ADR id (`0002-case`, or `adr:0002-case`).
+ * @param {GraphWalkContext} ctx
+ * @returns {GraphWalk}
+ */
+export function lineage(decisionId, ctx) {
+  const g = newWalk();
+  const record = ctx.byId.get(decisionIdOf(decisionId));
+  if (record === undefined) {
+    g.unresolved(
+      decisionId,
+      "decision",
+      `"${decisionId}" does not resolve — no matching ADR record in the registry`,
+    );
+    return g.walk;
+  }
+  attachLineage(g, record, ctx);
+  return g.walk;
+}

package/src/governance/provenance-record.mjs

@@ -37,8 +37,17 @@
  * or a polluted prototype cannot smuggle keys into a validated origin. This
  * module builds nothing from untrusted keys; it validates and, at write time,
  * builds a fresh object with only the three permitted keys.
+ * ## The decision-lifecycle record
+ *
+ * The same discipline extends from a row to a DECISION (an ADR id — the
+ * stable handle later waves reference). `recordDecisionLifecycle` records one
+ * lifecycle event — a status transition, a supersession, or a bindings
+ * change — attributed by the same `origin` shape and the same clock door:
+ * `by`/`tool` are required, and `on` comes from `recordOrigin` and nowhere
+ * else. A record that records nothing (a no-op transition) is refused loudly.
  */
 
+import { ADR_STATUSES } from "./adr-registry.mjs";
 import { clockViolations } from "./clock.mjs";
 
 /** The only keys a validated `origin` may carry. */
@@ -175,3 +184,144 @@ export function recordOrigin({ by, tool, clock }) {
   // record, so two calls with the same clock are byte-identical.
   return { by, tool, on: clock.now() };
 }
+/**
+ * The decision-lifecycle events one record can hold, each a single fact about
+ * ONE decision (an ADR id — `docs/adr/NNN-slug.md` — the stable handle the
+ * registry's `byId` map keys on). A decision's creation and every status
+ * change, supersession, and bindings change is recorded as one of these.
+ */
+export const DECISION_LIFECYCLE_KINDS = Object.freeze([
+  "status-transition",
+  "supersession",
+  "bindings-change",
+]);
+
+/**
+ * @typedef {object} DecisionLifecycleRecord
+ * @property {"status-transition"|"supersession"|"bindings-change"} kind
+ *   One recorded lifecycle event on one decision.
+ * @property {string} decisionId The ADR id the event happened to — the stable
+ *   handle the ADR registry keys on (`docs/adr/NNN-slug.md`).
+ * @property {string|null} [from] status-transition: the status the decision
+ *   left, or null when the event is the decision's creation (its proposed
+ *   entry).
+ * @property {string} [to] status-transition: the status the decision entered.
+ * @property {string[]} [superseded] supersession: the ADR id(s) this decision
+ *   replaced — `decisionId` is the RECORDING record, the successor.
+ * @property {string[]} [added] bindings-change: constraint ids made
+ *   enforceable.
+ * @property {string[]} [removed] bindings-change: constraint ids unbound.
+ * @property {OriginRecord} origin WHO recorded the event and with what tool —
+ *   `on` produced by `recordOrigin`, the only door.
+ */
+
+/**
+ * Records one decision-lifecycle event, attributed by the same `origin`
+ * discipline as a row: `by` and `tool` are required, and `on` comes from the
+ * injected clock through `recordOrigin` — the only producer of an `on`, and
+ * the refusal to run without one is its own, inherited here.
+ *
+ * The record carries ONLY the kind's own keys and the origin, built fresh, so
+ * nothing from untrusted input rides along. A no-op event — a status
+ * transition that changes nothing, a supersession naming no target, a
+ * bindings change that adds and removes nothing — is refused loudly: a record
+ * that records nothing would read as a transition that happened, the silent
+ * direction this module exists to exclude.
+ *
+ * Statuses are validated against `ADR_STATUSES` (`./adr-registry.mjs`), the
+ * single status vocabulary — a record can never attest a status the registry
+ * could not hold.
+ *
+ * @param {{kind: "status-transition"|"supersession"|"bindings-change",
+ *   decisionId: string,
+ *   from?: string|null, to?: string,
+ *   superseded?: string[],
+ *   added?: string[], removed?: string[],
+ *   origin: {by: string, tool: string},
+ *   clock: import("./clock.mjs").Clock}} event
+ * @returns {DecisionLifecycleRecord}
+ * @throws {Error} on an unknown kind, a missing decisionId, a status outside
+ *   the registry's `ADR_STATUSES`, a no-op event, or an invalid origin/clock.
+ */
+export function recordDecisionLifecycle({
+  kind,
+  decisionId,
+  from = null,
+  to,
+  superseded,
+  added,
+  removed,
+  origin,
+  clock,
+}) {
+  const violations = [];
+  if (!DECISION_LIFECYCLE_KINDS.includes(kind)) {
+    violations.push(
+      `kind: must be one of ${DECISION_LIFECYCLE_KINDS.join(", ")}, got ${describe(kind)}`,
+    );
+  }
+  if (typeof decisionId !== "string" || decisionId.trim() === "") {
+    violations.push(
+      `decisionId: must be a non-empty string naming the ADR, got ${describe(decisionId)}`,
+    );
+  }
+  if (kind === "status-transition") {
+    if (from !== null && !ADR_STATUSES.includes(from)) {
+      violations.push(
+        `from: must be null or one of ${ADR_STATUSES.join(", ")}, got ${describe(from)}`,
+      );
+    }
+    if (!ADR_STATUSES.includes(to)) {
+      violations.push(`to: must be one of ${ADR_STATUSES.join(", ")}, got ${describe(to)}`);
+    }
+    if (from !== null && from === to) {
+      violations.push(
+        `to: equals from (${JSON.stringify(from)}) — a status transition that changes nothing is not a recordable event`,
+      );
+    }
+  } else if (kind === "supersession") {
+    if (
+      !Array.isArray(superseded) ||
+      superseded.length === 0 ||
+      superseded.some((ref) => typeof ref !== "string" || ref.trim() === "")
+    ) {
+      violations.push("superseded: must be a non-empty array of ADR ids this decision replaced");
+    }
+  } else if (kind === "bindings-change") {
+    for (const [name, value] of [
+      ["added", added],
+      ["removed", removed],
+    ]) {
+      if (value !== undefined && !Array.isArray(value)) {
+        violations.push(`${name}: must be an array of constraint ids, got ${describe(value)}`);
+      } else if (
+        Array.isArray(value) &&
+        value.some((id) => typeof id !== "string" || id.trim() === "")
+      ) {
+        violations.push(`${name}: every entry must be a non-empty constraint id`);
+      }
+    }
+    const addedList = Array.isArray(added) ? added : [];
+    const removedList = Array.isArray(removed) ? removed : [];
+    if (addedList.length === 0 && removedList.length === 0) {
+      violations.push(
+        "added/removed: a bindings change that adds nothing and removes nothing is not a recordable event",
+      );
+    }
+  }
+  if (violations.length > 0) {
+    throw new Error(`decisionLifecycle: ${violations.join("; ")}`);
+  }
+  const eventFields =
+    kind === "status-transition"
+      ? { from, to }
+      : kind === "supersession"
+        ? { superseded }
+        : { added: added ?? [], removed: removed ?? [] };
+  return {
+    kind,
+    decisionId,
+    ...eventFields,
+    origin: recordOrigin({ by: origin?.by, tool: origin?.tool, clock }),
+  };
+}

package/src/providers/native/model.mjs

@@ -246,6 +246,10 @@ const PROJECT_TYPES = ["app", "lib", "e2e"];
  * An explicit `exclude` list REPLACES this default (the `tsc` convention for
  * the same field): a workspace that names its own list takes over the whole
  * decision, `exclude: []` included — that spelling is the documented opt-out.
+ * `excludeBeyondDefaults` extends the effective set — the defaults when
+ * `exclude` is absent, an explicit list when it is present — without restating
+ * it, so a workspace with `testdata/` or `golden/` directories does not copy
+ * these three patterns by hand (issue #389).
  *
  * @see DEFAULT_MANIFEST_NAMES
  */
@@ -375,7 +379,7 @@ function declaredProjectViolations(row, index) {
   return violations;
 }
 
-const INFER_KEYS = ["manifests", "include", "exclude"];
+const INFER_KEYS = ["manifests", "include", "exclude", "excludeBeyondDefaults"];
 
 /** `projects.infer`'s problems, or `[]` when the key is absent — absent means "use the defaults", not "malformed". */
 function inferViolations(value) {
@@ -385,6 +389,11 @@ function inferViolations(value) {
     ...stringListViolations(value.manifests, "projects.infer.manifests"),
     ...stringListViolations(value.include, "projects.infer.include", globComplexityError),
     ...stringListViolations(value.exclude, "projects.infer.exclude", globComplexityError),
+    ...stringListViolations(
+      value.excludeBeyondDefaults,
+      "projects.infer.excludeBeyondDefaults",
+      globComplexityError,
+    ),
   ];
   // `[]` and "omit the key" both validate against `stringListViolations` above
   // — a list is still a list at length zero — but they must not mean the same
@@ -758,9 +767,14 @@ export function normalizeNativeModel(raw) {
           : {
               manifests: rawInfer.manifests ?? DEFAULT_MANIFEST_NAMES,
               include: rawInfer.include ?? ["**"],
-              // Replaces, never merges: an explicit list takes over the whole
-              // decision — `DEFAULT_INFER_EXCLUDE`'s doc comment owns the why.
-              exclude: rawInfer.exclude ?? DEFAULT_INFER_EXCLUDE,
+              // `exclude` replaces the defaults (`DEFAULT_INFER_EXCLUDE`'s doc
+              // comment owns the why); `excludeBeyondDefaults` then extends the
+              // effective set — the defaults when `exclude` is absent, the
+              // explicit list when it is present — without restating it.
+              exclude: [
+                .../** @type {string[]|undefined} */ (rawInfer.exclude ?? DEFAULT_INFER_EXCLUDE),
+                .../** @type {string[]|undefined} */ (rawInfer.excludeBeyondDefaults ?? []),
+              ],
             },
     },
     projectRules: /** @type {unknown[]} */ (raw.projectRules ?? []).map((row) => {