# Design Conformance Review

How to check a change against this repo's design corpus **before merge**, so that
guidance does not drift out of agreement with itself or with the code.

## Why this exists

This repo's design lives in several places that must all tell the same story:
`docs/adr/`, `docs/principles/`, `CONTEXT.md`, and `docs/design/`. When a decision
is settled but only *some* of those copies are updated, the next builder follows
whichever copy they read and the design gets implemented "wrong" — not because the
decision was unclear, but because the guidance was inconsistent. PR #1 hit this
twice (load layer ownership; `setup/` layout). Existing guidance tells you to
"check the ADRs" (`AGENTS.md`) and "flag ADR conflicts" (`docs/agents/domain.md`)
but gives no method and never checks the corpus against itself. This is that
method.

## When to run

Before merging any change that touches ingestion, transform, or orchestration engine
code, the contract schemas, or anything under `docs/adr/`, `docs/principles/`, `docs/design/`, or `CONTEXT.md`.
Cheap to run on a diff; run it as part of review.

## Inputs

- The diff under review.
- The corpus: `docs/adr/`, `docs/principles/`, `CONTEXT.md`, `docs/design/`.

## Checks

1. **Doc-vs-doc consistency.** For every settled invariant the change relies on,
   confirm all copies agree. Known invariants and where they live:
   - *Layer ownership* — load materializes **only** raw; staging+ are
     transform-layer (`ADR-0016`, `CONTEXT.md`). Any "raw and/or staging" for the
     load stage is a drift bug.
   - *Contract kind & ownership* — producer owns the contract; `kind: source` vs
     `product`; sources carry no `layer` (`ADR-0015`, `ADR-0007`, `CONTEXT.md`).
   - *Contract compatibility* — pre-1.0 data product contracts are draft/non-live
     and may break under normal review; 1.0.0 is the first live compatibility
     baseline (`ADR-0021`, `CONTEXT.md`, `docs/design/v1-lakehouse-architecture.md`).
   - *Governance vocabulary* — the fixed eight-classification set (`ADR-0011`).
   - *Terms* — use the exact terms in `AGENTS.md` "Terms To Preserve"
     (`layer` not the old lifecycle-stage key, `data product` not table/pipeline, etc.).
   Grep the corpus for each term the change introduces or changes and read every
   hit, not just the nearest one.

2. **Code-vs-doc consistency.** Structure matches
   `docs/principles/config-driven-clean-structure.md`: reusable `engine/`, no
   source values in engine/shared code, producer-owns-contract holds, setup lives
   where the principle says. The architecture doc's claims match what the code does.

3. **Documented invariants are enforced in code.** A vocabulary or constraint
   fixed in an ADR (e.g. the `ADR-0011` classification set) must have a code-level
   guardrail, not just prose. Config decides *what to apply*; the valid universe is
   a platform invariant that belongs in engine code and should reject unknowns.
   For the engine/config boundary
   ([`engine-config-red-lines.md`](../principles/engine-config-red-lines.md)) the
   guardrail is runnable — when the diff touches ingestion, transform, or
   orchestration engine code, run it:

   ```bash
   python scripts/boundary_scan.py
   ```

   A new source/product literal in engine code is a Blocking finding unless it
   carries an inline `# boundary-scan: allow <reason>` or a justified
   `scripts/boundary_scan_allow.txt` entry.

4. **Superseded docs leave the active path.** Anything under `docs.historic/` (or
   otherwise superseded) carries a "superseded by ..." banner and is not linked
   from an active reading path as authoritative.

5. **New guidance is in-path and self-consistent.** A new principle/ADR/design doc
   is linked from the `AGENTS.md` reading path or `docs/*/README.md` index, and its
   own examples demonstrate the rule (not the anti-pattern).

6. **Contract-version review respects draft status.** Do not flag a breaking
   `0.x.y` data product contract change as missing major-version migration
   ceremony merely because it changes tests, meanings, or guarantees. Flag it
   only if the contract is 1.0.0 or later, or if the change claims live consumer
   compatibility while bypassing the live-contract rules.

## Output

Findings grouped **Blocking / Should-fix / Nit**, each with a `file:line` ref and
a concrete fix.

## The fix rule (important)

When a check fails because guidance drifted, **fix the guidance and its example,
not just the code** — update *every* copy of the invariant (ADR + principle +
CONTEXT + design doc) and the example that demonstrates it. A one-off code or
single-doc edit leaves the other copies to mislead the next builder. This is a
standing expectation in this repo, recorded across the violations the review of
PR #1 found.