# RESULT — Campaign100 092 norm-linter

**Type.** BUILD / tooling (block L instruments). Deliverable: `norm_linter.py` — a norm/geometry
report + PASS/FLAG verdict + recommended normalization to run **before** any
`delta = mean(z_A) − mean(z_B)` / offset construction. Packages instrument **lesson #3**
(norm-profile check before any delta). Sibling of 090 (probe_power_kit) and 091 (canon_check).

**Verdict. ★ BUILT + VALIDATED (T3).** The linter flags **two distinct failure modes** and passes
real directions. All **13 self-tests PASS** and all **6 validation gates PASS** on real SONAR z
(027-local-id = 036 corpus A, n=29029) + synthetic controls. One substantive design finding
(below) improved the linter mid-build; disclosed in full.

Tier: **T3-exploratory** (a tooling instrument; validated on one real corpus family + synthetic).

## What the linter does (four checks + verdict)
- **(a) norm distribution / magnitude gap** — mean/CV of `|z_A|,|z_B|`, between-group norm
  Cohen's *d*, **norm-only AUC**. Escalates to **FLAG** when the groups are ~perfectly
  norm-separable (AUC>0.90 **and** real *d*): the delta is **norm-defined / confounded**.
- **(b) raw-vs-cosine (036, decisive)** — cross-fit separation AUC along the delta axis in raw vs
  per-vector L2-normalized (cosine) space; `retention`. **FLAG** if the raw effect **dies under
  cosine** (a pure magnitude artifact).
- **(c) anisotropy / top-PC (037)** — top-PC var fraction, participation ratio, `|cos(δ,PC1)|`,
  `|δ|²` in top-*k* PCs. WARN if δ rides a dominant axis → whiten.
- **(d) effect-vs-norm** — Pearson *r* of per-point delta-projection vs `|z|`. WARN if confounded.
- **Overall FLAG** iff (a) **or** (b) fires. Recommendation prioritised: cosine (b) › decompose
  (a) › center/whiten (WARNs) › clean PASS.
- **Cross-fit (2-fold)** AUC guards the dim≫n regime (an in-sample mean-difference projection
  separates pure noise; `test_crossfit_no_inflation_on_noise` certifies ~chance on null data).

## Validation results (`out/results.json`, all 6 gates PASS)
| case | verdict | mechanism | 
|---|---|---|
| **REAL 036 norm-split** (hi-\|z\| vs lo-\|z\|, real corpus) | **FLAG** | check (a): norm-only AUC **1.000**, norm *d* **5.48**; **survives cosine** (raw 0.994→cos 0.996), effect↔\|z\| r **0.91** → **decompose** |
| **REAL norm-orthogonal split** (mid PC ⟂ radial) | **PASS** | matched norms (norm-AUC 0.638), survives cosine (0.999) |
| **magnitude fake** (cone dirs ×1.3 vs ×0.7) | **FLAG** | check (b): raw 0.998 → cosine **0.520** (retention 0.04) → **cosine** |
| **operator-faithful** (078 geometry, matched norms) | **PASS** | clean: norm *d* 0.0, effect↔\|z\| r **0.00**, "raw delta is safe" |
| **control sweep** mag-frac 0→1 | 0→**PASS**, 1→**FLAG** | gap0 pure-direction PASS; gap1 cosine dies (0.52, retention 0.04) |

- FLAGs the 036 artifact anchor: **YES** (via norm-confound gate). Passes operators/real
  directions: **YES** (operator, norm-orthogonal, clean, sweep-gap0 all PASS).

## ★ Key design finding (and honest development note)
The prereg imagined the 036 anchor would FLAG because **cosine kills the separation**. On the real
corpus that is **FALSE**: a high-|z| vs low-|z| split of real SONAR **survives cosine** (raw AUC
0.994 → cosine 0.996) — because norm carries a **real specificity direction** (036's own finding:
high-|z| sentences are genuinely entity-dense). So the decisive raw-vs-cosine check (b) — built
first — did **NOT** flag it (it correctly reported "a real direction survives"). The confound is
that the groups are **norm-defined** (norm-only AUC = 1.000) and the effect is 91% correlated with
|z|: you cannot attribute the raw delta to that surviving direction.

I therefore **added, mid-build, the norm-only-AUC FLAG gate to check (a)** (plus a `norm_sep_min_d`
guard after a floating-point robustness bug where numerically-identical norms gave a spurious
AUC=1.0). This is a genuine instrument improvement — the linter now flags **norm-artifact**
(cosine kills → cosine) **and** norm-confounded (norm-defined → decompose) — validated
independently by a synthetic norm-defined test and the magnitude fake. **Disclosure:** prediction
(1) is satisfied by this improved design, not the pre-registered (b-only) one; my underlying belief
"cosine kills the 036 split" was falsified.

## Predictions & Brier (frozen in PREREG_LITE)
- **(1)** FLAGs the real 036 norm-split. p=0.92 → **TRUE** (via added check-a gate; see note above). 
- **(2)** PASSES the real norm-orthogonal split. p=0.80 → **TRUE**.
- **(3)** pure-magnitude → FLAG AND operator-faithful → PASS. p=0.85 → **TRUE**.
- **(4)** recommended fix for the 036 anchor is cosine/L2-normalize. p=0.88 → **TRUE literally**
  (the recommendation says "L2-normalize (cosine) to isolate the direction"), but the headline verb
  is **decompose**, not the plain "it's an artifact, use cosine" I had in mind — scored strictly it
  is FALSE (my simple-cosine mental model was wrong).
- **(5)** low false-positive: matched-norm real-direction deltas PASS. p=0.70 → **TRUE** (operator,
  norm-orthogonal, clean, sweep-gap0 all PASS; the linter FLAGs only genuinely norm-separable deltas).
- **gate** all self-tests pass. p=0.90 → **TRUE** (13/13).

**Brier (primary, (4)=TRUE literal) = 0.031.** Stricter variant with (4)=FALSE (penalizing the
falsified "cosine-kills-it" mental model) **= 0.157**. The honest penalty is the design iteration
disclosed above, not a threshold-tuned pass.

## Gates
- **G_flag_anchor PASS** — real 036 norm-split FLAGs (norm-confounded) + magnitude fake FLAGs (artifact).
- **G_pass_anchor PASS** — operator-faithful + real norm-orthogonal split PASS.
- **G_selftests PASS** — 13/13.
- **G_crossfit PASS** — null (same-distribution) cross-fit AUC ~0.5 (no dim≫n inflation).

## Limitations
- One real corpus family (027/036 SONAR English, greedy AE). Real anchors are a **norm-split** and a
  **norm-orthogonal split** of that corpus — not paired operator z (033/078 do not cache raw before/
  after vectors; their `offsets.json` corroborates matched norms: z_before 0.207 ≈ z_after 0.200,
  which our operator-faithful synthetic mirrors). Re-encoding real 033/078 pairs on GPU would upgrade
  the PASS anchor from "faithful synthetic + real norm-orthogonal" to "real operator" — cheap follow-up.
- Check (c) anisotropy never fires on real SONAR (it is fairly isotropic, PR≈195/1024); it is exercised
  only by a synthetic dominant-axis test. Thresholds (norm_auc_flag 0.90, retention 0.50, etc.) are
  defensible defaults, overridable per call, not swept.
- The `norm-defined` FLAG is deliberately conservative: any moderate magnitude gap that makes groups
  norm-separable trips it, even with a surviving direction. That is the intended behavior (decompose),
  but callers building deliberately norm-linked deltas should read the per-check detail, not just the
  verdict.

## Follow-up worth funding? **Weak-Y (narrow, cheap).**
- Re-encode ~40 real 033/078 operator before/after pairs (GPU, seconds) → run the linter on a **real
  operator delta** as the PASS anchor (closes the one synthetic gap).
- Wire `norm_linter.lint_delta` as a pre-flight assert into future offset/operator rows
  (034/046/062/063/064/080) — it is a 2-second `import norm_linter` call.