@agentsfleet/orly 0.5.0

package/docs/DISPATCH_ARCHITECTURE.md

@@ -0,0 +1,664 @@
+# Dispatch Architecture — operating-model (v3, EXECUTED)
+
+> Documentation prerequisite: read
+> [`DOCUMENTATION_RULES.md`](./DOCUMENTATION_RULES.md) before editing this file.
+> This internal explanation is not a published Markdown JSX (MDX) page, so page front matter and
+> skeleton rules do not apply. Plain-language and acronym rules do.
+
+Date: Jun 04, 2026 (proposed) · Jun 05, 2026 (Stage-2 executed)
+Status: **v3 EXECUTED** — the Stage-2 atomic switchover landed on
+`feat/resolver-architecture` (PR #18): the 20 `docs/gates/` cards + `ZIG_RULES.md`
++ `BUN_RULES.md` dissolved into the 10 `dispatch/` entries; `docs/gates/` no longer
+exists; `audits/agents-md.sh` enforces dispatch parity on every commit. The body
+below is preserved as the design rationale **as proposed** (v2) — past-tense future
+sections ("will", "Stage 2 does…") describe the now-completed migration; it is the
+durable record of *why* the dispatch model exists, not a live to-do list.
+Owner: Orly (Oracle)
+Scope: `~/Projects/dotfiles` operating model + cross-repo rule-doc references
+
+> Design doc, not a milestone spec (dotfiles has no `docs/v*/` train). Lands on
+> `master` via `feat/dispatch-architecture`. **v2 supersedes v1** after a 7-lens
+> adversarial Chief Technology Officer (CTO) review (38 findings confirmed: 19
+> P0 / 16 P1 / 3 P2) returned **REWORK** — concept sound, migration plan
+> under-scoped ~10×, two determinism claims overstated. v2 keeps the façade-pair
+> core and rewrites the migration, the blast-radius accounting, and the claims to
+> match what the mechanisms actually deliver. Every change below is grounded in a
+> grep of the branch, not the review prose — file:line citations are real.
+> **Per-finding disposition (all 38 + resolved/partial status) is tracked in
+> [`DISPATCH_REVIEW_DISPOSITION.md`](./DISPATCH_REVIEW_DISPOSITION.md).**
+
+---
+
+## 0 · What changed from v1 (the review's verdict, absorbed)
+
+| v1 claim / gap | v2 correction |
+|---|---|
+| "the two façades **cannot drift**" (headline invariant) | Downgraded to **"no missing symbol + prose-pinned thresholds."** The coherence audit proves symbol presence, not that a check enforces the prose. Real semantic anchors added (§3, §6.3). |
+| §11 = cross-repo footnote | §8 = **primary in-dotfiles blast-radius inventory** (grounded, ~14 files). Cross-repo is downstream of it (§10). |
+| Dissolve `docs/gates/` + rename `*_RULES.md` (single act) | **Staged, non-destructive migration** (§9): scaffold → prove equivalence → atomic switchover. `make audit` never goes red mid-flight. Rollback defined. |
+| `make audit` "ALL CHECKS PASSED" as an acceptance bullet | The audit/hook/harness **rewrites are first-class deliverables** (§8, §13) and edit the harness → **explicit Indy sign-off required** (Hard-Safety rule). |
+| "nothing unique dies" on merge | A **mechanical merge-loss proof** (`merge-coverage.sh`, §6.5). No card deleted until its delta-landed assertion is green. |
+| `🟡` = JUDGMENT-open | **Glyph collision fixed** — `HARNESS_VERIFY_OUTPUT.md:19` already uses `🟡` for "violations addressed." v2 introduces **`🤔 DECIDE`** for judgment-open (§3.1). |
+| JUDGMENT "mitigated" / "blocks the turn" | Honestly scoped: **proven for DETERMINISTIC, attested-by-honor for JUDGMENT.** A `HARNESS_VERIFY` JUDGMENT row makes the *attestation* auditable (§11). |
+| Helper-absent → `🟣`, exit 0 | A DETERMINISTIC helper that is **absent hard-fails RED** (§10) — no silent green no-op. |
+| `.git/hooks/pre-commit` backstop | Wired to **`.githooks/pre-commit`** (`core.hooksPath` = `.githooks`, confirmed) — `.git/hooks/` never runs on a fresh clone. |
+| Dispatch run in dotfiles; leaf checks "just run" | **Execution-location model defined** (§10): `bin/link-agents-md` **symlinks** (confirmed `:160,176`), so the dispatch runs in the product repo against a symlink back to dotfiles. `DISPATCH_ROOT` (target repo) is derived from `git rev-parse --show-toplevel`, NOT `BASH_SOURCE` — so a symlinked dispatch scopes to the repo it runs in, not dotfiles. |
+| fn≤50 / method≤70 sub-cap | **Not silently dropped** — `dispatch_length_gate` is file-cap only today (`lib.sh:107`); v2 names the sub-cap as a delegated/[JUDGMENT] decision in §13. |
+
+> **This doc is the TARGET STATE, not current code.** The dispatch WIP on this
+> branch (`dispatch/lib.sh`, `dispatch/write_zig.sh`) is v1-era: it still emits
+> `🟡` for judgment, returns `🟣`/exit 0 on an absent helper, derives
+> `DISPATCH_ROOT` from `BASH_SOURCE`, and wires `ufs.sh --all`. Every such
+> correction below is *specified here and implemented during the staged
+> migration* (§9), not already present. A second adversarial pass (Jun 04, 21
+> resolved / 17 partial) confirmed the partials are "doc correct, code pending" —
+> tracked as Stage-0 implementation work, not doc defects.
+
+---
+
+## 1 · Intent (the testable goal)
+
+**Goal (as a test name):** *"Writing a `*.zig` file dispatches a SMALL ORDERED
+façade set — the language façade (`dispatch/write_zig.md`) plus the one
+cross-cutting façade (`dispatch/write_any.md`) — the agent reads, and the
+matching deterministic `.sh` set the machine runs; every rule is tagged
+DETERMINISTIC (has a `.sh` check + a prose-pinned fixture) or JUDGMENT (has a
+Large Language Model (LLM) comprehension probe); the deterministic value lives
+once (in the `.sh`) and the prose references it, so a fixture catches prose↔check
+divergence; an audit ties tags ↔ checks ↔ evals ↔ merged-prose."*
+
+> Not literally "one façade" — a write triggers its language façade composed with
+> `write_any` (§5). Two façades, fixed and ordered, is still the single runnable
+> question v1 lacked; the scatter it kills was 20 cards + 478-line prose doc, not
+> "more than one file."
+
+**Why:** Today the Zig discipline is scattered: `docs/ZIG_RULES.md` (478 lines),
+`docs/gates/*.md` (20 cards), 10 `audits/*.sh`. Nothing makes "did I
+adhere to all Zig rules?" a runnable, testable question. This unifies them into
+a **façade pair per language** and proves adherence in both spaces.
+
+**What v2 does NOT claim:** that the `.md` and `.sh` *cannot* diverge in meaning.
+A symbol-presence audit cannot prove that. v2's mechanism for semantic coherence
+is **single-source thresholds + prose-pinned fixtures** (§3, §6.1), not the tag.
+
+## 2 · Core insight — a dispatch is a FAÇADE PAIR over one gate set
+
+A dispatch is not one file. It is the dispatcher *concept*, presenting two faces:
+
+```
+          ┌──────────── THE ZIG DISPATCH (one concept) ────────────┐
+LATENT ──▶ │  dispatch/write_zig.md   façade for the AGENT          │
+SPACE      │     prose dispatcher: "writing zig? adhere to this."    │
+           │     every § tagged [DETERMINISTIC → CODE] or [JUDGMENT] │
+           │            │ DETERMINISTIC tags link to ↓               │
+DETERM. ──▶│  dispatch/write_zig.sh   façade for the MACHINE        │
+SPACE      │     owns the threshold values; runs the checkable       │
+           │     subset → 🟢/🔴 + 🤔 judgment nudges                  │
+           │            │ calls ↓                                    │
+           │  audits/*.sh  +  inline checks (the leaf checks) │
+           └─────────────────────────────────────────────────────────┘
+```
+
+- **`write_zig.md`** = `docs/ZIG_RULES.md` **merged with the Zig-relevant
+  `docs/gates/*.md` deltas**, perfected and made more deterministic — not a bare
+  rename. It gains per-section enforcement tags; mechanical content moves to the
+  `.sh`; teaching prose stays.
+- **`write_zig.sh`** = the deterministic façade. **It owns every threshold value
+  verbatim** (`dispatch_length_gate 350`); the `.md` *references* the value
+  ("see `write_zig.sh::length`"), never restates the number. This is the v2
+  anti-drift mechanism — one source, not two copies bridged by a tag.
+
+**`gates/*.md` is DISSOLVED selectively, not wholesale** (§5 taxonomy): authoring
+gates merge into a façade `.md`; **process/meta gates stay in `AGENTS.md`**. Merge
+is **merge-then-delete with a proof gate** (§6.5): a card is deleted only after
+`merge-coverage.sh` confirms its non-boilerplate prose landed in a façade.
+
+## 3 · Enforcement tags + the semantic anchor
+
+Each section of the latent façade carries exactly one tag. **The tag grammar is
+frozen to one form** matching what `write_zig.sh` actually emits — a rule CODE,
+not a `::function` reference (v1 mixed `sh::X` and `write_zig.sh::<check>`; both
+are dropped):
+
+| Tag | Meaning | Enforced by | Eval kind |
+|---|---|---|---|
+| `[DETERMINISTIC → CODE]` | machine can pass/fail it | the `.sh` row for `CODE` (e.g. `FLL`, `UFS`) | prose-pinned fixture (pass + fail) |
+| `[JUDGMENT → CODE]` | no script can decide; agent decides at write time | agent reading the prose | LLM-judge scenario |
+| `[container]` | structural wrapper heading, not a rule | nothing — its tagged subsections carry the real codes | skipped (coherence audit §6.3) |
+
+Walk all ~40 ZIG sections + merged gate deltas; tag each. A DETERMINISTIC tag
+whose CODE has no `.sh` row is a *build-the-check* TODO; a section that genuinely
+can't be checked is honestly `[JUDGMENT]`. Structural wrapper headings (e.g.
+"Merged from dissolved gate cards") carry `[container]` — the sole non-rule tag —
+and the coherence audit skips them; their tagged subsections carry the real codes.
+
+**The semantic anchor (the v2 fix for "false determinism"):**
+1. **Single source.** The numeric/threshold lives ONLY in the `.sh`
+   (`dispatch_length_gate 350`). The `.md` says "≤ the cap in
+   `write_zig.sh::length`" — it carries no competing number to drift.
+2. **Prose-pinned fixture.** For any rule whose prose states a bound, a fixture
+   pins it: `length_351_fail.zig` MUST exit 1. If someone edits the `.sh` cap to
+   500, the 351 fixture flips to pass and `dispatch-evals` goes red. The
+   **fixture**, not the tag, is the drift detector.
+
+### 3.1 · Signal semantics (🟢 / 🔴 / 🤔) — and the glyph-collision fix
+
+`HARNESS_VERIFY_OUTPUT.md:19` already defines `🟡 = violations addressed` (a
+resolved-but-noted deterministic state, e.g. `LENGTH GATE | 🟡 files at cap`).
+v1 reused `🟡` for "judgment open question" — the **opposite** semantics (open vs
+resolved). v2 introduces a distinct glyph so one symbol never carries two
+meanings:
+
+| Signal | Meaning | Agent MUST | Exit |
+|---|---|---|---|
+| 🟢 GREEN | deterministic check passed | proceed | 0 |
+| 🔴 RED | deterministic check failed | STOP, fix code, re-run | 1 (blocks) |
+| 🟡 YELLOW | deterministic violation **addressed** (informational) | note it; existing meaning, unchanged | 0 |
+| 🤔 DECIDE | judgment-only rule; no script can decide | read linked §, make the call, **state the verdict in chat** | 0 (does NOT block script) |
+
+**Why a new glyph, not re-glyphing `🟡`:** re-glyphing the established
+"violations addressed" cells touches an audited doc and retrains every agent on a
+symbol they already know. `🤔` is additive — a new concept gets a new glyph. The
+fix still requires a one-line `HARNESS_VERIFY_OUTPUT.md` legend update and an
+`audits/agents-md.md` question pinning `🤔` (§8, §13).
+
+**🤔 blocks the TURN, not the script** — see §11 for how that is made auditable
+rather than honor-only.
+
+## 4 · Two worked gates (the concrete shape)
+
+**GATE 1 — LENGTH (deterministic, single-source threshold):**
+```
+write_zig.md §Length:
+  - `.zig` ≤ the cap in write_zig.sh::length; split by concern when over.
+    [DETERMINISTIC → FLL]   (the number lives in the .sh, not here)
+write_zig.sh:  dispatch_length_gate 350
+fixture:  length_351_fail.zig → exit 1   (pins the prose bound; flips if cap moves)
+run:  FLL 🔴 File & Function Length Limits — foo.zig: 360 (cap 350) — split
+→ machine decides. pass/fail. prose carries no drift-able number.
+```
+
+**GATE 2 — TAGGED-UNIONS (judgment, no script):**
+```
+write_zig.md §Tagged unions for result types:
+  - Result with distinct failure modes → union(enum) w/ payload, not
+    optional-field struct. Callers need the *reason*, not the verdict.
+    [JUDGMENT → TGU]
+write_zig.sh:  dispatch_judgment "TGU" "result w/ failure modes? union(enum)…"
+eval:  evals/llms — scenario asserts union(enum), not optional struct
+run:  TGU 🤔 DECIDE — result w/ failure modes? union(enum), not optional-field
+→ agent decides, states verdict in chat; CONFORM audits the attestation.
+```
+
+## 5 · Dispatch set + gate disposition (all 20 mapped — no homeless gate)
+
+| Latent façade (.md) | Deterministic façade (.sh) | Triggers |
+|---|---|---|
+| `write_zig.md` | `write_zig.sh` | `*.zig` |
+| `write_ts_adhere_bun.md` | `write_ts_adhere_bun.sh` | `*.ts *.tsx *.js *.jsx` |
+| `write_sql.md` | `write_sql.sh` | `schema/*.sql` |
+| `write_any.md` | `write_any.sh` | any source (cross-cutting authoring rules) |
+
+**Disposition taxonomy — all 20 mapped; 15 dissolve, 5 stay (NOT emptied):**
+
+- **(A) Language-authoring gates → that language's façade.** `zig`, `pub-surface`,
+  `lifecycle` → `write_zig`; `ui-substitution`, `design-token` → `write_ts_adhere_bun`;
+  `schema-removal` → `write_sql`.
+- **(B) Cross-cutting authoring gates → `write_any`.** `file-length`, `logging`,
+  `milestone-id`, `error-registry`, `ufs`, `greptile`, and the legacy-workaround
+  family (`nlr`, `nlg`, `legacy-design`). **Principle (not a junk drawer):**
+  `write_any` holds *language-agnostic authoring invariants that apply identically
+  to every source file* — literal hygiene, length, observability, milestone-free
+  naming, dead-code/legacy. The discriminator vs (C): (B) is checked **per file at
+  write time**; (C) governs the **lifecycle/process**, never a single file's bytes.
+- **(C) Process / meta gates → STAY as `docs/gates/` bodies (NOT dissolved).**
+  `verification`, `invariance-suite`, `spec-template`, `architecture`, `doc-read`.
+  **Why they keep their `docs/gates/` cards (not inlined into `AGENTS.md`):**
+  `AGENTS.md` is 28744 / 29696 bytes — ~950 bytes headroom; five bodies cannot fit.
+  So `docs/gates/` is **never emptied** — it retains exactly these five cards. This
+  is also what de-fangs the "disk_count → 0 fails the parity check" risk (§9).
+
+**The new parity invariant (the hard part v1 hand-waved).** `agents-md.sh`
+check #9b becomes: `AGENTS.md dispatch-rows == (retained docs/gates/ bodies = 5)
++ (dispatch façades = 4)`, and the empty-set guard (`:177`) flips from "≥1 gate
+body" to "exactly the 5 process bodies present." `REQUIRED_GATES` (data.sh)
+splits into `REQUIRED_PROCESS_GATES` (5) + `REQUIRED_DISPATCH` (4). No gate is
+homeless, none double-homed, and the audit counts a well-defined mixed end-state.
+
+## 6 · EVALS — both spaces + two new proofs
+
+### 6.1 Deterministic façade evals — prose-pinned fixtures
+```
+evals/dispatch/fixtures/
+  length_350_pass.zig    → write_zig.sh expects exit 0
+  length_351_fail.zig    → expects exit 1   (PINS the prose bound)
+  ufs_dup_string.zig     → expects exit 1
+  deinit_missing.zig     → expects exit 1
+evals/dispatch/run.sh  → runs each fixture, diffs actual vs expected exit
+```
+Every `[DETERMINISTIC → CODE]` rule MUST have ≥1 pass + ≥1 fail fixture, and any
+rule whose prose states a bound MUST have a fixture that pins it (§3).
+
+### 6.2 Latent façade evals — COMPREHENSION probes (rewire the EXISTING harness)
+`evals/llms/run.sh` is a **cross-agent comprehension runner**
+(claude/codex/amp/opencode, `:69-78`). It grades by exact match on a
+`VERDICT: YES|NO` line over `fixtures.jsonl` (`:125-174`) — it is a *comprehension*
+grader, **not an adherence judge** over free-form code. v2 is honest about that:
+1. **Repoint context.** `build_context()` (`:83-90`) currently cats
+   `"$GATES_DIR"/*.md`. Repoint to cat **`dispatch/*.md` PLUS the retained
+   `docs/gates/*.md`** (the 5 process cards, §5). Without this, `cat
+   "$GATES_DIR"/*.md` dies on a changed dir. `GATES_DIR` at `:22`.
+2. **JUDGMENT evals are comprehension probes, not adherence proofs.** A probe asks:
+   *"given `write_zig.md`, does the model correctly answer the TGU judgment
+   question (union vs optional-struct)?"* — a YES/NO the existing grader can score.
+   It proves the model **understands** the rule, NOT that a real diff **adhered**.
+   **Real-diff adherence is checked at `/review` + greptile, not in CI** — claiming
+   a CI judge proves adherence was v1's category error. A true adherence judge
+   (elicit code → rubric-grade with a pinned model) is **out of scope for v2**;
+   flagged in §16 if you want it scoped later.
+
+### 6.3 Coherence audit — `evals/dispatch/coverage.sh` (honest scope)
+Proves **completeness and symbol-presence** — NOT prose semantics (that's §6.1's
+fixtures). Fails if any of:
+- a `[DETERMINISTIC → CODE]` tag has no row for `CODE` in **any** dispatch `.sh` (a *universal* code like `UFS` is wired once in its home façade — `write_any` — and satisfies the tag wherever the rule's prose appears; only a code wired in NO dispatch fails — §16 Decision 6);
+- a DETERMINISTIC rule has no pass+fail fixture — this audit checks fixture *presence* only; the boundary-*pinning* of a bounded rule (the `351` flips if the cap moves) is proven by `run.sh` executing the boundary fixtures against the live cap, NOT by this audit (§6.1);
+- a `[JUDGMENT]` rule has no comprehension probe (§6.2);
+- a `.sh` CODE row has no tag in the `.md` (orphan check);
+- **a CODE row delegates to a leaf helper that is absent / non-executable**
+  (closes the silent-green hole, §10);
+- a CODE appears in `.sh` output with no gloss-map entry (no naked codes).
+
+### 6.4 Rule-code glosses — ONE canonical list
+v1 already drifted: `lib.sh:45-61` carries codes (`FLL`/`LENGTH` duplicated;
+`PUB`/`DRAIN`/`DEINIT`/`ARCH`/`XCOMPILE`) absent from the `RULES.md` legend and the
+old §6.4 table. v2: **one canonical gloss list** in `RULES.md`; `lib.sh` mirrors it;
+`dispatch-coverage.sh` fails on any divergence. Drop the `FLL`/`LENGTH`
+duplicate. Delegated-only codes (`PUB`/`DRAIN`/`XCOMPILE`) get legend entries too.
+
+### 6.5 Merge-loss proof — `evals/dispatch/merge-coverage.sh` (NEW, keystone)
+For each of the 15 authoring cards scheduled for deletion: assert every
+non-boilerplate token-line appears in some `dispatch/*.md`, **or** is captured as
+an explicit drop. **Honest scope (same discipline as §6.3):** this proves
+*prose-token coverage*, NOT semantic equivalence and NOT trigger-enforcement —
+that a reworded-but-faithful merge and an enforcement-orphaned trigger are *both*
+risks the token scan alone won't catch. Three guards close the gameable holes the
+adversarial pass flagged:
+- **Frozen normalization** (not "normalized", hand-wave): lowercase → strip
+  markdown punctuation/backticks → collapse whitespace → tokenize to a word
+  multiset. The grammar is pinned in the script + a negative fixture proves an
+  orphaned sentence FAILS.
+- **No agent self-certification.** The "intentionally-dropped" branch requires an
+  **Indy ack-quote** in the PR (Pull Request) body (per the deferral-discipline
+  rule) — the merging agent may not author its own drop justification.
+- **Trigger-surface enforcement is separate.** Each dissolved card's machine
+  trigger (e.g. `milestone-id`'s `M[0-9]+_[0-9]+` regex, `ui-substitution`'s raw
+  element list) must reproduce as a `.sh` CODE row, verified by §6.3's tag↔check
+  wiring — token-coverage alone does not prove the trigger still fires.
+
+A card is not deleted until its delta-landed assertion is green. Preserve any
+`audits/agents-md.md` scenario that quotes a deleted body verbatim (§11).
+
+### 6.6 The docs tier — same grammar, one more class (M02_001)
+
+Everything above governs `dispatch/`. The `docs/` rule tier sat outside every
+coverage glob: hundreds of normative clauses with no enforcement class, no
+report, and no signal when a trigger went dead. `audits/rule-ledger.sh` extends
+this model there, reusing the tag grammar rather than forking it.
+
+**One new class.** `[DETERMINISTIC → CODE]` and `[JUDGMENT → CODE]` keep their
+meanings. `[UNENFORCED → reason]` is added, and its reason is prose on purpose:
+a clause nobody checks should say *why* in the place a reader meets it. The
+class exists so acknowledged prose is distinguishable from a clause nobody has
+triaged — without it, both read as "untagged" and the backlog lies.
+
+**Tag scope.** A tag alone on its line covers every clause beneath it until the
+next heading; a tag at the end of a sentence covers that sentence. The `docs/`
+tier is paragraph-shaped where `dispatch/` is section-shaped, and forcing one
+tag per line would have meant editing prose to satisfy a counter.
+
+**What counts as a clause.** A line carrying a normative keyword, outside
+headings and markdown tables — a heading is a title, and a table row's `always`
+is usually a column value. The count is a keyword heuristic and never gates:
+the only reds are structural (a cited-but-unregistered doc, a registered path
+missing from disk, a façade `.sh` with no `dispatch_init` scope, a stale
+scoreboard).
+
+**Where the registry lives.** `REGISTERED_DOCS` / `EXCLUDED_DOCS` /
+`EXCLUDED_PREFIXES` in `audits/rule-ledger-lib.sh`. A `docs/*.md` cited by a
+façade and absent from both lists is a parity red — silence is the one outcome
+not allowed, because it under-reports the corpus. The generated scoreboard is
+`docs/RULE_ENFORCEMENT.md`, currency-checked by `make audit`.
+
+## 7 · Firing planes (corrected wiring + latency)
+
+| Plane | When | Invocation |
+|---|---|---|
+| Latent | EXECUTE, about to write | agent reads `write_zig.md`; runs `write_zig.sh <file>` (scoped to the touched file, NOT `--all`) |
+| Anchor | CONFORM (end-of-turn) | `write_zig.sh --staged`; 🔴 → back to EXECUTE; 🤔 → state verdict |
+| Backstop | COMMIT | **`.githooks/pre-commit`** (core.hooksPath, confirmed) runs `dispatch/*.sh --staged` — **dotfiles repo only;** product repos keep the 8 leaf audits (Reading A, §10.7) |
+| Audit | pre-push + `make audit` | `dispatch-coverage.sh` + `merge-coverage.sh` wired into the SAME chain as `agents-md.sh` |
+| Evals | pre-push + `make` | deterministic fixtures + live smoke; full `make llmevals` is explicit |
+
+**Latency fix:** v1's `write_zig.sh` wired `ufs.sh --all` (full-tree scan)
+on every per-edit call — contradicting "instant on no-match." v2 scopes leaf runs
+to `DISPATCH_FILES` (teach `ufs.sh` a file-list mode; pass the staged set);
+`--all` runs only on the Audit/Evals planes. State a measured latency on
+`agentsfleet` before claiming "instant."
+
+## 8 · In-dotfiles blast radius (PRIMARY — grounded, ~14 files)
+
+The dissolution + rename touches the operating model's own enforcement spine.
+**Every edit below lands in the Stage-2 atomic commit (§9).** Citations verified
+against `feat/dispatch-architecture`:
+
+| File | Line(s) | What it pins | Must change to |
+|---|---|---|---|
+| `audits/agents-md.sh` | `:14` | `GATES_DIR=docs/gates` | derive from `dispatch/` |
+| ″ | `:46-65` (#1) | `REQUIRED_GATES` ⊂ AGENTS.md index | dispatch-set inventory |
+| ″ | `:171-187` (#8) | gate bodies; **`:177` empty-set guard** | dispatch-body completeness |
+| ″ | `:190-209` (#9b) | parity `index==disk==REQUIRED` | dispatch parity |
+| ″ | `:263-277` | both hooks must grep `docs/gates` | grep `dispatch/` |
+| ″ | `:130-133` | `DOTFILES_RESIDENT` docs exist | new resident paths |
+| `audits/data.sh` | `:36-46` | `REQUIRED_GATES` name array | dispatch set |
+| ″ | `:70-78` | `DOTFILES_RESIDENT` (ZIG/BUN/greptile RULES) | `dispatch/*.md` |
+| ″ | `:94-118` | `NAMED_SCENARIOS` 1:1 w/ invariance | mirror scenario edits |
+| `.githooks/pre-commit` | trigger glob | gates `AGENTS.md`/`docs/gates` edits | add `dispatch/` |
+| `.githooks/pre-push` | `:72` + guard | message + `docs/gates` guard | repoint + reword |
+| `evals/llms/run.sh` | `:22`, `:83-90` | `build_context` cats `docs/gates/*.md` | cat `dispatch/*.md` |
+| `evals/test-agents-md.sh` | `:39,46,165-167` | sandbox builds `docs/gates`+RULES; negative case asserts hook bites on dropped `docs/gates` | rewrite sandbox + negatives for dispatch model |
+| `bin/link-agents-md` | `:35,37,45` | propagates `ZIG_RULES`/`BUN_RULES`/`docs/gates` → product repos | repoint + **add `dispatch/`** |
+| `AGENTS.md` | `:66,212` | `*.zig`→ZIG_RULES; /review→ZIG_RULES | →`write_zig.md` + Dispatch table |
+| `docs/EXECUTE_DOC_READS.md` | `:11,12` | zig→ZIG_RULES, ts→BUN_RULES | →façades |
+| `docs/greptile-learnings/RULES.md` | `:42,91` | cross-ref ZIG_RULES sections | →`write_zig.md` |
+| `docs/LIFECYCLE_PATTERNS.md` | `:3,311` | sister-doc refs ZIG_RULES | →`write_zig.md` |
+| `docs/LOGGING_STANDARD.md` | `:193,195,263,283-285` | BUN_RULES §9/§10, ZIG_RULES | →façades |
+| `docs/TEMPLATE.md` | `:139,142,154,356` | ZIG/BUN doc-read rows | →façades |
+| `docs/ZIG_RULES.md` | `:415` | refs BUN_RULES §2 | `git rm` (deleted; cross-ref already resolved in the merged `write_zig.md`) |
+| `audits/logging.sh` | `:152` | fail message cites `BUN_RULES §10` | →`write_ts_adhere_bun.md §logging` |
+| `skills/orly-spec-new/SKILL.md` | `:63` | names `ZIG_RULES.md`/`BUN_RULES.md` as per-surface rule files | →façades (verify sync scope before assuming it ships to product repos) |
+| `docs/HARNESS_VERIFY_OUTPUT.md` | `:19,26-36` | `🟡 = violations addressed` | add `🤔 DECIDE` legend + JUDGMENT row (§11) |
+
+**Magnitude:** ~30+ edits across ~16 files, all in one atomic commit. This is the
+work v1 never scoped — it is the dominant cost, not a footnote.
+
+**Completeness is machine-enforced, not trust-the-table.** A
+`zero-dangling-ref` audit gates Stage 2: `grep -rIl 'ZIG_RULES\|BUN_RULES\|docs/gates/[a-z-]*\.md'`
+across the tree (minus this doc, git history, and the 5 retained process cards)
+must return **zero** hits. The table above is the human map; the grep is the gate
+— it catches any ref site (like `logging.sh` / `SKILL.md`) the table missed.
+
+**Product-repo files are out of scope (Reading A — Indy, confirmed).** This
+inventory is dotfiles-only: no product repo's `make/harness.mk` or
+`.githooks/pre-commit` is edited by the migration. The 8 leaf audits remain each
+repo's commit-plane + harness enforcement and reach it as `link-agents-md`
+**symlinks**, so the one in-scope leaf edit (`logging.sh:152`, fail-message
+repoint) propagates with **zero product-repo commit**. Dispatch ship to product
+repos as **agent-facing files only** (§10.7) — never wired into a product Makefile
+or hook.
+
+## 9 · Migration plan — staged, non-destructive (the keystone fix)
+
+The Invariance Suite Gate is **no-override** and derives the gate set from disk
+with 3-way parity, so any intermediate state where `docs/gates/` is half-gone
+fails `make audit` — which the hooks run unconditionally, blocking the very commit.
+v2 therefore **never lets `make audit` go red mid-flight**:
+
+**Stage 0 — Scaffold (purely additive; gates + RULES untouched).** Create
+`dispatch/{lib,write_zig,write_ts_adhere_bun,write_sql,write_any}.{sh}` and the
+`.md` façades (merge ZIG_RULES + gate deltas) ALONGSIDE the still-present
+`docs/gates/` and `docs/ZIG_RULES.md`. Add `evals/dispatch/`,
+`dispatch-coverage.sh`, `merge-coverage.sh`. **`make audit` stays
+green** (nothing removed). One or more commits.
+
+**Stage 1 — Prove equivalence (still additive).** `merge-coverage.sh` green
+(every gate-card delta landed in a façade). `dispatch-evals/run.sh` green.
+`make llmevals` green against the new dispatch context. Dispatch and legacy gates
+both present and passing. **`make audit` stays green.** Commit.
+
+**Stage 2 — Atomic switchover (the ONLY harness-editing commit → Indy sign-off).**
+In ONE commit: all §8 edits + zero-dangling-ref grep green + `git rm
+docs/ZIG_RULES.md docs/BUN_RULES.md` — **deletion, not `git mv`**: the prose was
+already additively merged into `dispatch/write_zig.md` (657 lines) and
+`dispatch/write_ts_adhere_bun.md` in Stage 0, so a `git mv` would clobber the
+merged façades; `merge-coverage.sh` is the proof-of-no-loss — + `git rm` the **15
+authoring cards only** (the 5 process cards STAY, §5; only after §6.5 green) +
+`git rm` the now-spent **merge-coverage set** (`evals/dispatch/merge-coverage.sh`,
+`merge_coverage.py`, `merge-coverage-drops.tsv`, `fixtures/merge_orphan_card.md`)
+— one-shot migration scaffolding, dead once the cards are gone (RULE NDC) — +
+AGENTS.md gate-index → Dispatch table (4 rows) + slimmed 5-row process-gate index +
+`link-agents-md` repoint & dispatch-add.
+
+**Why atomic IS green (the fresh-eyes "impossible" objection, resolved).** The
+pre-commit hook runs the *worktree's* `agents-md.sh` against the *worktree*.
+In this single commit the rewritten audit AND the new tree are both
+staged-and-saved together, so the **new** parity check (`5 process + 4 dispatch`,
+§5) evaluates the **new** state — never the old check against a half-migrated tree.
+`docs/gates/` is never emptied (5 cards stay), so the `:177` empty-set guard is
+satisfied throughout. Run `make audit && make test-audit` as a **pre-flight on the
+fully-staged worktree** before `git commit`; the hook then re-confirms. No
+`--no-verify`, ever.
+
+**Rollback.** Stages 0–1 are additive → nothing to revert. Stage 2 is one commit →
+`git revert` restores the full prior spine (gate cards live in git history; the
+merge was additive prose, so reverting loses no rule). No kill-switch needed
+because no destructive state exists before Stage 2.
+
+**Per Hard-Safety:** Stage 2 edits `audit-*.sh` + hooks (a harness/gate) → it
+requires **explicit Indy sign-off naming the files + reason**, captured in the PR
+Session Notes. The agent does not switch over unilaterally.
+
+## 10 · Execution-location & cross-repo delivery
+
+**The problem v1 ignored — and the symlink twist the adversarial pass caught:**
+`dispatch_resolve_files --staged` discovers files via `git -C "$DISPATCH_ROOT"`,
+where `DISPATCH_ROOT` is derived from `BASH_SOURCE` (`lib.sh:35`). But
+**`bin/link-agents-md` SYMLINKS** (`ln -s`, confirmed `:160,176`) — it does not copy.
+So a dispatch "shipped" into `agentsfleet` is a symlink back to
+`~/Projects/dotfiles/dispatch/`, and a `BASH_SOURCE`-derived `DISPATCH_ROOT`
+resolves to **dotfiles**, not `agentsfleet` — the Zig checks scan dotfiles' empty
+tree and pass **vacuously**, exactly the bug propagation was supposed to cure.
+
+**v2 model — separate the two roots `lib.sh` currently conflates:**
+1. **`DISPATCH_HOME`** (where the scripts live, for `source lib.sh` + finding
+   `audits/`) — from `BASH_SOURCE`. Follows the symlink to dotfiles; that's
+   correct for *locating the code*.
+2. **`TARGET_ROOT`** (the repo being checked, for `--staged` git discovery AND the
+   leaf-check scope) — from **`git rev-parse --show-toplevel`** of the CWD (or the
+   file arg's dir). This resolves to `agentsfleet` when the symlinked dispatch is run
+   from inside `agentsfleet`, so discovery and the leaves (`ufs.sh` etc., which
+   already root off `--show-toplevel`) **agree on the same repo**. Robust whether
+   sync copies or symlinks.
+3. **Ship dispatch into each product repo via `bin/link-agents-md`** (add a
+   `dispatch:dispatch` entry to the link list). With (2), the symlink is now safe.
+4. **Dotfiles = source-of-truth + fixture/eval host**, not where Zig checks run on
+   real code. `evals/dispatch/` fixtures are the only place these checks
+   are provable in dotfiles (it has no `*.zig`).
+5. **`dispatch_run_helper` hard-fails (🔴, `DISPATCH_RC=1`) on an absent
+   DETERMINISTIC helper** — never `🟣`/exit 0. `🟣` is reserved for
+   `dispatch_delegate`. `dispatch-coverage.sh` enforces helper presence (§6.3).
+6. Add a `link-agents-md` propagation test + a **staleness note:** symlinks are always
+   current; a product-repo *real-file* override triggers `link-agents-md`'s existing
+   warn-and-skip (`:171`) — flagged, not silent. Add `dispatch/*.md` to
+   `DOTFILES_RESIDENT`.
+7. **Product repos are NOT rewired (Reading A — Indy, confirmed).** `link-agents-md`
+   ships `dispatch/{*.md,*.sh}` into each product repo as **agent-facing files**
+   (read at EXECUTE; runnable on a touched file) — but **no product repo's
+   `make/harness.mk` or `.githooks/pre-commit` is edited.** The 8 leaf audits
+   (`audit-ufs` … `audit-msid-ui`, symlinked in) stay each repo's codebase-wide
+   mechanical net; dispatch are the per-file authoring lens + the dotfiles-side
+   coherence/merge audits (§6.3/§6.5). The §7 Backstop plane is therefore
+   **dotfiles-only** — it fires against `evals/dispatch/` fixtures (dotfiles
+   has no real `*.zig`/`*.ts`), which keeps the §8 zero-dangling-ref grep and the
+   Stage-2 sign-off scoped to dotfiles.
+
+## 11 · JUDGMENT enforcement — honest, and made auditable
+
+`dispatch_judgment` prints a `🤔` row and exits 0. No script can decide a taste
+question, and faking determinism on one is the anti-goal. So the claim is scoped
+honestly: **DETERMINISTIC rules are proven; JUDGMENT rules are attested.** v2
+makes the *attestation* auditable rather than pure honor-system:
+
+- Add a **JUDGMENT row to `HARNESS_VERIFY_OUTPUT.md`** (`HARNESS_KEYS` in
+  `data.sh:62-67`). **Honest scope:** the audit check is `grep -qF "$kw"
+  AGENTS.md` (`agents-md.sh:117`) — it verifies the row *exists* in the prose
+  (so CONFORM always lists a judgment line), NOT that a *specific turn*
+  answered its `🤔`. Per-turn answering is **not machine-checked** — claiming
+  otherwise was the overclaim the coverage pass flagged.
+- **The machine backstop is the deferred ledger, not this row.** A turn-scoped
+  verdict ledger that `pre-commit` refuses until each `🤔` has a `CODE: applied|N/A`
+  ack is the only thing that mechanically blocks an unanswered judgment. Deferred
+  to §16 Q1 — without it, judgment adherence is attested + comprehension-probed
+  (§6.2), not enforced. Stated plainly, not dressed up.
+- **Cross-agent caveat:** headless non-Orly agents (codex/amp/opencode) emit `🤔`
+  to stdout with no chat audience; the comprehension probe (§6.2) is the only
+  signal for them. The turn-verdict ritual is interactive-Orly best-effort.
+
+**Invariance-questionnaire migration (part of Stage 2).** Dissolving the 15
+authoring cards can strand `audits/agents-md.md` scenarios that assert facts about
+those bodies. Before deletion: `grep` the questionnaire for every scenario that
+(a) quotes a dissolved body verbatim, (b) requires a per-body structural section
+(the review flagged a `Scope (M70)` requirement), or (c) triggers on "edits any
+`docs/gates/*.md`". Each must be **relocated, retired, or rebased onto the façade
+with an Indy ack** so it stays answerable-YES. The review named ~7.10/13.1/14.5/
+22.4/23.1 — **confirm exact IDs at execution** (the grep is the source of truth,
+not these numbers). `NAMED_SCENARIOS` parity (`data.sh:94-118`) keeps the
+keyword count honest but does not make a YES answer true — that's manual.
+
+§1/§9 language is downgraded accordingly: "proven, not promised" holds for the
+DETERMINISTIC half; the JUDGMENT half is "attested + eval-sampled."
+
+## 12 · Invariants (code-enforced)
+
+1. One verdict format — all `.sh` source `lib.sh`.
+2. **No missing symbol** (not "no drift") — coherence audit (§6.3).
+3. **No threshold drift** — single-source value + prose-pinned fixture (§3, §6.1).
+4. Determinism — caps intrinsic to file content, never git history.
+5. Every rule classified — no untagged section (audit-enforced).
+6. Every rule evaluable — DETERMINISTIC→fixture, JUDGMENT→judge (audit-enforced).
+7. No rule lost on merge — `merge-coverage.sh` (§6.5).
+8. No naked codes — one canonical gloss list (§6.4).
+9. No silent green — absent DETERMINISTIC helper → 🔴 (§10).
+10. One glyph, one meaning — `🟡` addressed, `🤔` decide (§3.1).
+
+## 13 · Acceptance criteria
+
+**Dispatch assets**
+- [ ] `dispatch/{lib,write_zig,write_ts_adhere_bun,write_sql,write_any}.{sh}` exist
+- [ ] `dispatch/{write_zig,write_ts_adhere_bun,write_sql,write_any}.md` exist; every § tagged; thresholds single-sourced in the `.sh`
+- [ ] `file-length` fn≤50 / method≤70 sub-cap **implemented as a leaf check OR honestly tagged `[JUDGMENT]`** — named explicitly, not collapsed into "300/350"
+- [ ] glyph `🤔 DECIDE` defined; `🟡` left as "violations addressed"
+
+**Evals & proofs**
+- [ ] `evals/dispatch/` fixtures: every DETERMINISTIC rule pass+fail; every prose bound pinned
+- [ ] `evals/llms/` JUDGMENT scenario per rule; `build_context` repointed to `dispatch/`
+- [ ] `evals/dispatch/coverage.sh` clean (tags↔checks↔evals↔helper-presence↔glosses)
+- [ ] `evals/dispatch/merge-coverage.sh` clean (every deleted card's delta landed)
+- [ ] one canonical gloss list (`RULES.md` ↔ `lib.sh`); `FLL`/`LENGTH` dup removed
+
+- [ ] `dispatch/lib.sh`: `DISPATCH_HOME` (BASH_SOURCE) vs `TARGET_ROOT` (`git rev-parse --show-toplevel`) split (§10); absent DETERMINISTIC helper → 🔴 not 🟣/0
+- [ ] `docs/EXECUTE_DOC_READS.md`: doc-reads trigger rows for the NET-NEW façades (`write_sql.md`, `write_any.md`), not just repointed zig/ts rows
+
+**Harness rewrites (first-class; Stage-2; Indy sign-off)**
+- [ ] `data.sh`: `REQUIRED_GATES` → `REQUIRED_PROCESS_GATES` (5) + `REQUIRED_DISPATCH` (4); `DOTFILES_RESIDENT`→`dispatch/*.md`; `NAMED_SCENARIOS` mirrors invariance edits
+- [ ] `agents-md.sh`: checks #1/#8/#9b derive the mixed end-state; parity `index == 5 process bodies + 4 dispatch`; empty-set guard → "exactly the 5 process cards present"; hook-trigger check greps `dispatch/` + `docs/gates/`
+- [ ] `.githooks/pre-commit` + `pre-push` repointed (NOT `.git/hooks/`)
+- [ ] `evals/test-agents-md.sh` rewritten: sandbox + negative cases prove the NEW coherence audit bites
+- [ ] `HARNESS_VERIFY_OUTPUT.md` JUDGMENT row + `🤔` legend; `audits/agents-md.md` question pinning `🤔` and the dispatch model
+- [ ] `bin/link-agents-md` repointed + `dispatch:dispatch` added + propagation test
+
+**Migration & references**
+- [ ] Stage 0/1 commits keep `make audit` green; Stage 2 atomic; rollback note in PR
+- [ ] `zero-dangling-ref` grep gate green (§8) — machine-enforced, not trust-the-table
+- [ ] invariance-questionnaire migration done: stranded scenarios relocated/retired/rebased with Indy ack (§11)
+- [ ] all §8 sibling-doc references repointed in the Stage-2 diff (incl. `logging.sh`, `SKILL.md`)
+- [ ] cross-repo (`agentsfleet`) refs resolved via `link-agents-md` propagation (§10)
+- [ ] `make audit` + `make test-audit` ALL CHECKS PASSED at Stage-2 boundary + invariance signoff
+
+## 14 · Failure modes → mitigations
+
+| Failure | Mitigation |
+|---|---|
+| `.md` prose value drifts from `.sh` | single-source threshold + prose-pinned fixture (§3) — not the tag |
+| DETERMINISTIC helper deleted/renamed → silent green | `dispatch_run_helper` → 🔴; coherence audit asserts helper presence (§10) |
+| `make audit` red mid-migration blocks the commit | staged, additive migration; red only conceivable inside the one atomic Stage-2 commit (§9) |
+| Unique gate prose lost on merge | `merge-coverage.sh` blocks deletion until delta lands (§6.5) |
+| `llmevals` dies on empty `docs/gates/` under `set -e` | `build_context` repointed to `dispatch/` in Stage 2 (§6.2, §8) |
+| Dispatch never reaches `agentsfleet` | added to `link-agents-md`; dispatch ship into product repos (§10) |
+| `🤔` judgment silently ignored | CONFORM JUDGMENT row audited; Large Language Model (LLM) judge evaluation samples adherence (§11) |
+| Glyph ambiguity | `🟡` and `🤔` disjoint, pinned by invariance question (§3.1) |
+| Backstop never runs on fresh clone | wired to `.githooks/` (core.hooksPath), not `.git/hooks/` (§7) |
+
+## 15 · Discovery (consult log)
+
+- **Façade-pair insight (Indy, Jun 04):** dispatch = `.md`+`.sh` pair, not one file.
+- **Merge, not rename (Indy, Jun 04):** *"latentspace `dispatch/write_zig.md`
+  (merged perfected made more deterministic merge of the ZIG_RULES.md + the
+  gates/\*.md relevant to zig)"* → §2: façade `.md` is a merge of ZIG_RULES + zig
+  gate deltas; `zig.sh` renamed to `write_zig.sh` (the bare `zig.sh` name rejected).
+- **Manifest rejected:** `.sh` is executable truth; manifest duplicates.
+- **gates/\*.md dissolved selectively (v2):** authoring gates → façade; process
+  gates stay in AGENTS.md (§5) — v1's "all 20 → façades" was a category error.
+- **new=300/edited=350 rejected:** git-state-dependent → flat caps, intrinsic.
+- **Evals in both spaces (Indy, Jun 04):** fixtures + LLM-judge + coherence audit.
+- **Glosses (Indy, Jun 04):** gloss map + RULES.md legend + baked into output.
+- **Adversarial CTO review (Orly, Jun 04):** 7 lenses, 38 confirmed findings
+  (19 P0), verdict REWORK. v2 absorbs all P0/P1: staged migration (§9), primary
+  in-dotfiles blast radius (§8), downgraded drift claim + semantic anchor (§3),
+  merge-loss proof (§6.5), execution-location model (§10), glyph fix (§3.1),
+  honest JUDGMENT (§11), `.githooks` wiring (§7).
+- **Decisions made this turn (Orly, pick-and-proceed):** (a) `🤔` for judgment
+  rather than re-glyph `🟡` — additive, lower blast radius; (b) staged migration
+  over single atomic diff — keeps `make audit` green and gives free rollback;
+  (c) dispatch ship into product repos via `link-agents-md` — the only way the Zig
+  checks run against real `*.zig`. Indy to confirm or redirect.
+- **Stage-2 sign-off (Indy, Jun 04, 2026):** *"stage-2 yes signed off"* — context:
+  authorizes the Stage-2 atomic switchover to edit `audit-*.sh` + `.githooks` (a
+  harness/gate), satisfying the Hard-Safety harness-patch rule. The `🤔` glyph and
+  the JUDGMENT ledger remain open (§16, Q1/Q2).
+
+## 16 · Decisions (was: open questions)
+
+1. **JUDGMENT hardening — DEFERRED** (Indy, Jun 04, 2026: *"I defer the ledger,
+   its complicated"*). v2 ships judgment as **attested + comprehension-probed**
+   (§11); the turn-scoped verdict ledger is a possible later hardening, not v2 scope.
+2. **`🤔` glyph — pending confirm** (default: accept `🤔 DECIDE`, leaving `🟡` as
+   "violations addressed"; alternative is re-glyphing `🟡` in
+   `HARNESS_VERIFY_OUTPUT.md`). Cosmetic/semantic only — a colored-circle swap.
+3. **Stage-2 sign-off — GRANTED** (Indy, Jun 04, 2026, §15): the Stage-2 atomic
+   switchover may edit `audit-*.sh` + `.githooks` per the Hard-Safety harness-patch
+   rule.
+4. **Code length cap = 350 — RECONCILED** (Indy, Jun 04, 2026): the file-length
+   gate card's `350` is canonical for all code (`.zig`/`.ts`/`.tsx`/`.js`/`.py`/
+   `.rs`/`.go`/`.sql`). `write_zig.sh`'s stray `300` corrected to `350`; the §3/§4/
+   §6.1 examples regenerated at `350`/`351`. Every dispatch's `dispatch_length_gate`
+   equals the gate's `350`, so the early-warning never diverges from enforcement.
+5. **`.md` doc/spec length caps — DEFERRED** (Indy, Jun 04, 2026): `.md` stays
+   exempt from the length gate (status quo). The long merged façades (`write_zig.md`
+   654L, `write_ts_adhere_bun.md` 486L) are therefore legal. Tiered doc/spec caps
+   (e.g. docs 350 / specs 400) are a possible post-Stage-2 task, not v2 scope.
+6. **UFS enforcement consolidated to `write_any`** (Indy, Jun 04, 2026): `UFS` is a
+   universal rule, so it is run-wired ONCE in `write_any.sh` (which fires for every
+   source file). The `dispatch_run_helper "UFS"` rows were removed from
+   `write_zig.sh` + `write_ts_adhere_bun.sh`; their verbatim UFS prose stays, tagged
+   `[DETERMINISTIC → UFS]` but annotated as enforced-by-`write_any`. This restores
+   §5's "none double-homed" (enforcement is single-homed) and kills the redundant
+   full-tree `audit-ufs` scan on multi-language touches. `dispatch-coverage.sh`
+   (§6.3) accepts a universal code wired in any one dispatch.
+7. **Eval harnesses relocated to top-level `evals/`** (Indy, Jun 05, 2026): the
+   deterministic dispatch fixtures + the cross-agent comprehension probes moved
+   `audits/{dispatch-evals,llmevals}/` → `evals/{dispatch-evals,llmevals}/` — a
+   first-class test home, sibling of `dispatch/`. The merge-coverage drops
+   ledger moved out of `dispatch/` (the Stage-2 sync payload, where a
+   dotfiles-internal migration artifact must not ship) into
+   `evals/dispatch/`. `audits/` retains the `audit-*.sh` family. All
+   functional + spec path refs repointed; `DISPATCH_REVIEW_DISPOSITION.md`'s
+   review quote of the old path is left as a historical record.
+8. **Merge-coverage is a Stage-2 deletion gate, not a Stage-0 `make audit` check**
+   (Orly, Jun 05, 2026, pick-and-proceed): `merge-coverage.sh` is built +
+   self-tested (the orphan fixture bites) but NOT wired into `make audit` — at
+   Stage 0 the 15 cards still exist, and "a card is not deleted until its
+   assertion is green" (§6.5). Against the real merge it shows 13/15 cards fully
+   covered; `zig`/`pub-surface`/`lifecycle` surface ~40 reworded-away prose tokens
+   (classified — no lost rules; the PUB/DEINIT rules are tagged in `write_zig.md`).
+   These need Indy drop-acks in `evals/dispatch/merge-coverage-drops.tsv`
+   before the cards are deleted; wiring into `make audit` follows the acks.