feat(resolver): pt5 — coherence + merge-loss audits, judgment probes, gloss legend; evals → top-level

.githooks/pre-commit

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Pre-commit hook for dotfiles.
-# - When AGENTS.md is staged, runs scripts/audit-agents-md.sh and blocks
+# - When AGENTS.md is staged, runs audits/agents-md.sh and blocks
 #   the commit if any invariant regressed.
 # - For all other commits, this hook is a no-op (fast path).
 #
@@ -16,19 +16,19 @@ set -uo pipefail
 ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT" || exit 1
 
-if git diff --cached --name-only | grep -qE '^(AGENTS\.md|AGENTS_INVARIANCE\.md|docs/gates/.*\.md|scripts/audit-agents-md\.sh|scripts/fixtures/.*\.diff)$'; then
+if git diff --cached --name-only | grep -qE '^(AGENTS\.md|audits/agents-md\.(md|sh)|audits/data\.sh|audits/parity-dispatch\.sh|dispatch/.*\.md|audits/fixtures/.*\.diff)$'; then
   if [[ "${SKIP_AGENTS_AUDIT:-0}" = "1" ]]; then
     echo "pre-commit: SKIP_AGENTS_AUDIT=1 — bypassing AGENTS.md audit (one-off)" >&2
   else
-    echo "pre-commit: AGENTS.md or its audit changed — running scripts/audit-agents-md.sh" >&2
-    if ! bash "$ROOT/scripts/audit-agents-md.sh"; then
+    echo "pre-commit: AGENTS.md or its audit changed — running audits/agents-md.sh" >&2
+    if ! bash "$ROOT/audits/agents-md.sh"; then
       cat >&2 <<'MSG'
 
 pre-commit: AGENTS.md invariance regressed.
 
 Fix the FAIL: lines above, then re-stage and re-commit.
 
-If you also changed AGENTS.md semantics, run AGENTS_INVARIANCE.md
+If you also changed AGENTS.md semantics, run audits/agents-md.md
 through an LLM agent before merging — the script catches mechanical
 regressions; the questionnaire catches reading-comprehension ones.
 

.githooks/pre-push

@@ -2,10 +2,10 @@
 # Pre-push hook for dotfiles.
 #
 # Behaviour:
-# - Runs scripts/audit-agents-md.sh always (script layer; deterministic).
-# - When the push includes commits that touched AGENTS.md, AGENTS_INVARIANCE.md,
-#   or any docs/gates/*.md, ALSO requires a fresh sign-off file written by an
-#   LLM agent that ran the AGENTS_INVARIANCE.md questionnaire.
+# - Runs audits/agents-md.sh always (script layer; deterministic).
+# - When the push includes commits that touched AGENTS.md, audits/agents-md.md,
+#   or any dispatch/*.md, ALSO requires a fresh sign-off file written by an
+#   LLM agent that ran the audits/agents-md.md questionnaire.
 #
 # Sign-off file: .agents-invariance-signoff (gitignored — it's a machine-local
 # attestation, not a tracked artifact). Format:
@@ -15,8 +15,8 @@
 # A sign-off is "fresh" if its <commit-sha-short> matches HEAD and the file was
 # written within the last 24 hours.
 #
-# To produce the sign-off: open AGENTS_INVARIANCE.md in an LLM session and
-# instruct: "Read AGENTS.md and answer every question in AGENTS_INVARIANCE.md.
+# To produce the sign-off: open audits/agents-md.md in an LLM session and
+# instruct: "Read AGENTS.md and answer every question in audits/agents-md.md.
 # When all-YES, write the sign-off line to .agents-invariance-signoff."
 #
 # One-off bypass:  SKIP_INVARIANCE_PUSH=1 git push ...
@@ -28,8 +28,8 @@ ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT" || exit 1
 
 # 1. Always run the script layer.
-echo "pre-push: running scripts/audit-agents-md.sh" >&2
-if ! bash "$ROOT/scripts/audit-agents-md.sh"; then
+echo "pre-push: running audits/agents-md.sh" >&2
+if ! bash "$ROOT/audits/agents-md.sh"; then
   echo "pre-push: script layer failed — fix before push" >&2
   exit 1
 fi
@@ -46,7 +46,7 @@ while read -r local_ref local_sha remote_ref remote_sha; do
     range="$remote_sha..$local_sha"
     files=$(git diff --name-only "$range")
   fi
-  if echo "$files" | grep -qE '^(AGENTS\.md|AGENTS_INVARIANCE\.md|docs/gates/.*\.md)$'; then
+  if echo "$files" | grep -qE '^(AGENTS\.md|audits/agents-md\.md|dispatch/.*\.md)$'; then
     contract_changed=1
   fi
 done
@@ -69,11 +69,11 @@ fi
 if [[ ! -f "$SIGNOFF" ]]; then
   cat >&2 <<MSG
 
-pre-push: 🔴 BLOCKED — AGENTS.md / docs/gates / AGENTS_INVARIANCE.md changed in
+pre-push: 🔴 BLOCKED — AGENTS.md / dispatch/ / audits/agents-md.md changed in
           this push, but no .agents-invariance-signoff file exists.
 
 To proceed:
-  1. Open AGENTS_INVARIANCE.md in an LLM agent session.
+  1. Open audits/agents-md.md in an LLM agent session.
   2. Instruct: "Read AGENTS.md and answer every question. When all-YES, write
      a sign-off line to .agents-invariance-signoff in this format:
          <commit-sha-short>  <UTC-timestamp>  PASS"

Makefile

@@ -1,28 +1,52 @@
-.PHONY: audit test-audit llmevals llmevals-check signoff
+.PHONY: audit test-audit llmevals signoff \
+        dispatch-coverage dispatch-evals dispatch-parity
 
-# Run the deterministic audit (script layer of the invariance suite).
+# Run the deterministic audit chain (all green):
+#   1. agents-md.sh          — AGENTS.md invariance + dispatch parity (script layer).
+#   2. dispatch-coverage.sh  — dispatch façade-pair coherence (6.3 + 6.4).
+#   3. evals/dispatch/run.sh — prose-pinned deterministic façade evals.
 audit:
-	@bash scripts/audit-agents-md.sh
+	@bash audits/agents-md.sh
+	@bash evals/dispatch/coverage.sh
+	@bash evals/dispatch/run.sh
+
+# Dispatch façade-pair coherence in isolation (tags ↔ checks ↔ fixtures ↔
+# probes ↔ leaf-helpers ↔ canonical gloss legend).
+dispatch-coverage:
+	@bash evals/dispatch/coverage.sh
+
+# Deterministic dispatch evals in isolation — pass+fail fixture per code.
+dispatch-evals:
+	@bash evals/dispatch/run.sh
 
 # Negative-test the audit itself — prove every check still FAILS on a bad
-# tree (conformance + determinism). Run whenever audit-agents-md.sh changes.
+# tree (conformance + determinism). Run whenever agents-md.sh changes.
 test-audit:
-	@bash scripts/test-audit-agents-md.sh
+	@bash evals/test-agents-md.sh
 
-# Cross-agent LLM eval signoff (AGENTS_INVARIANCE.md Scenario 23): each
+# Dispatch-parity proof — runs audits/parity-dispatch.sh against a model-B
+# sandbox (docs/gates/ empty, AGENTS.md dispatch table, 10 entries) and asserts
+# it goes green AND bites. agents-md.sh now sources the same check (check 9b);
+# this isolates + proves it against synthetic regressions.
+dispatch-parity:
+	@bash evals/test-dispatch-parity.sh
+
+# Cross-agent LLM eval signoff (audits/agents-md.md Scenario 23): each
 # installed agent (claude/codex/amp/opencode) answers the frozen golden-set;
 # verdicts graded by exact match. Live LLM calls — costs tokens on every
 # agent. Resumable (journalled); writes .agents-llmevals-signoff on
 # all-gradable-agents-pass.
+#
+# One entry point. The live run validates fixtures + reports availability as a
+# mandatory preamble (run.sh:188) before any spend. For the zero-token
+# dry path (CI / runner unavailable, Scenario 23.8) pass CHECK=1:
+#   make llmevals          — live graded run (costs tokens)
+#   make llmevals CHECK=1  — validate fixtures + availability only, no live calls
 llmevals:
-	@bash scripts/llmevals/run-llmevals.sh
-
-# Dry validation — fixtures well-formed + agent availability. No live calls.
-llmevals-check:
-	@bash scripts/llmevals/run-llmevals.sh --check
+	@bash evals/llms/run.sh $(if $(CHECK),--check)
 
 # Write the AGENTS_INVARIANCE sign-off file against current HEAD.
-# Only run this AFTER answering every AGENTS_INVARIANCE.md question with YES.
+# Only run this AFTER answering every audits/agents-md.md question with YES.
 # The pre-push hook reads .agents-invariance-signoff to allow contract pushes.
 signoff:
 	@printf '%s  %s  PASS\n' \

README.md

@@ -13,9 +13,40 @@ git config core.hooksPath .githooks    # arms pre-commit + pre-push (one-time, p
 The `core.hooksPath` line wires the AGENTS.md invariance suite into every
 commit and push from this clone. Without it, `.githooks/` is just files —
 git keeps using `.git/hooks/` (sample stubs only). Re-run on every fresh
-clone or worktree. See [AGENTS_INVARIANCE.md](AGENTS_INVARIANCE.md) for the
+clone or worktree. See [audits/agents-md.md](audits/agents-md.md) for the
 contract; run `make audit` any time to verify it by hand.
 
+## How the rules work (in plain terms)
+
+[`AGENTS.md`](AGENTS.md) is the rulebook every AI agent follows. Instead of one
+giant list, the rules are split by **what you're about to do** — and the agent is
+handed only the one page that applies.
+
+Think of it like a front desk: you say "I'm about to write some Zig," and it gives
+you exactly the Zig rules — not the whole binder. Each of those pages lives in
+[`dispatch/`](dispatch/), and where a rule can be checked by a machine, a small
+script runs it automatically.
+
+| If you're about to… | The agent reads… |
+|---|---|
+| write Zig | `dispatch/write_zig.md` |
+| write TypeScript / JavaScript | `dispatch/write_ts_adhere_bun.md` |
+| write SQL or a database schema | `dispatch/write_sql.md` |
+| write *any* code at all | `dispatch/write_any.md` |
+| write a spec / changelog / API / auth code | the matching `dispatch/write_*.md` |
+| say "it's done — tests pass" | `dispatch/verify.md` |
+| name a stream or design a flow | `dispatch/name_architecture.md` |
+| change the rules themselves | `dispatch/edit_rules.md` |
+
+One command — `make audit` — keeps the rulebook honest: it fails loudly if this
+list, the files on disk, and the agent's own checklist ever fall out of sync.
+
+> **Want the full story?** The *why* behind this design — the latent/deterministic
+> "façade pair" per topic, the 🟢/🔴/🔵/⚪ signal tags, the parity guarantees, and
+> the migration that produced it — is written up in detail in
+> [`docs/DISPATCH_ARCHITECTURE.md`](docs/DISPATCH_ARCHITECTURE.md). The exact,
+> machine-checked list of entries lives in [`audits/data.sh`](audits/data.sh).
+
 The instructions below assume you are in the `~/Projects/dotfiles` directory.
 
 ## Install