Close out BACKLOG 1a and file what gating the page uncovered

1a is done, so it leaves BACKLOG.md. What replaces it is 1a-followup: the
subset of the page's remaining skips whose reason is "this example is wrong"
rather than "the harness cannot wrap it" -- OrderPlaced shown with two field
sets on one page, epic steps whose paths contradict the page's own
application fence, an adaptor crossing its isolation seam, a projector with
no record. Each was read off a real riddlc diagnostic.

1b absorbs the last 17 blanket skips, which live in migration/ and guides/.

CLAUDE.md gains the domain-prelude mechanism and, more usefully, the two
ways this gate can report a green that means nothing: a probe filtering only
[error]/[severe] misses [deprecated], and a directive that fails to parse
degrades silently to `standalone`. Both were hit this session.

Gate re-run after these edits: 183/43/0, exit 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: reid-spencer

BACKLOG.md

@@ -6,101 +6,47 @@ what is durably true goes to CLAUDE.md.
 
 ---
 
-## 1a. Retire the blanket "illustrative fragment" skips  ← START HERE
-
-**What:** When filed, the gated pages reported 84 validated and **128 skipped**,
-**118 of them carrying one identical reason**: `illustrative fragment;
-references vocabulary this page does not define`. That is precisely what a
-`<!-- riddl-prelude ... -->` exists to supply, so they were bulk-skipped rather
-than annotated.
-
-A skip is a legitimate outcome for a fence that genuinely cannot compile — a
-deliberate counter-example, or an `include` resolved against a file that does
-not exist. What 1a retires is the **blanket** reason applied without looking.
-Each such fence keeps a skip, but with a reason that says which of those it is.
-
-**Measured 2026-08-08**, not estimated: stripping that one reason from 8 sample
-concept pages (14 such skips) and re-running with `--auto` — **4 of the 14
-needed nothing but an existing wrapper** and were skipped for no reason at all.
-The other 10 need a per-page prelude, which is the documented remedy, not a
-correction to the examples.
-
-**Method per page:**
-```bash
-# strip the blanket skip (WHOLE line, indentation included -- a leftover
-# indent corrupts fence matching and silently changes the counts)
-# then see which wrapper each fence fits:
-python3 scripts/validate-riddl-examples.py --auto ../bin/riddlc <page>.md
-```
-Annotate the ones that place; write one page prelude for the rest.
-
-**Progress:** `concepts/` and `introduction/` are **done** — not one blanket
-skip remains in either. `language-reference.md` has had a first slice: 23
-validated / 52 skipped → **35 / 40**. Gate-wide: **171 validated / 55 skipped
-/ 0 failed**, from 84/128 when 1a was filed.
-
-**49 blanket skips remain:**
-
-| Where | Count | Note |
-|---|---|---|
-| `references/language-reference.md` | 32 | in scope; see below |
-| `migration/1.x-to-2.0.md` | 6 | **outside the gate** — 1b territory |
-| `guides/authors/design/command-event-patterns.md` | 6 | outside the gate |
-| `guides/authors/design/ui-modeling.md` | 3 | outside the gate |
-| `guides/authors/index.md` | 2 | outside the gate |
-
-### What the remaining 32 need (measured, do not re-derive)
-
-The page's prelude has been extended once and **compiles clean on its own** —
-probe it with `wrap("in-context", "type ProbeOnly is String", prelude)` before
-blaming a fence. What is left divides roughly into:
-
-- **Statement fences** (`send`/`tell`/`set`/`let`/`match`/`foreach`/`become`)
-  that want `in-handler`. The wrapper already supplies `order`, `cart` and
-  their fields; what they lack is page vocabulary — outlets, events, target
-  entities — some of which is now in the prelude and some not.
-- **Whole-context fences** (adaptor, projector, pipeline, application, epic)
-  that declare their own `context`. These want `in-domain` plus a
-  **`riddl-domain-prelude`** holding the sibling contexts they name
-  (`PaymentContext`, `OrderContext`, `Storefront`). The page has no domain
-  prelude yet; that is the single biggest lever left.
-- **Genuinely unskippable, needing a precise reason instead of the blanket
-  one:** the two `import "commerce.bast"` fences, and the
-  `on command DoIt from context Other` pair (two spellings of the same clause,
-  which cannot share a handler — same fence as `onclause.md`).
-- **Known content bugs to fix while there:** `button Checkout activates type
-  Boolean` (fifth page with that line), and the `version` fence whose
-  `entity Order` has no handler.
-
-**Two traps this page taught, both costly:**
-
-- **Never name a prelude entry `Tax`.** The `in-function` wrapper supplies a
-  sibling `context Tax`, so a prelude `function Tax` makes every `Tax.…` path
-  ambiguous and breaks the page's in-function fences. The prelude carries a
-  comment saying so.
-- **`annotate-riddl-examples.py` places a fence against the prelude AS IT
-  WAS.** Extending the prelude afterwards can invalidate earlier placements —
-  it silently invalidated 8. Annotate, then extend, then re-run the page.
-
-**The gate's scope is a file list, not a directory.** The exact command is in
-CLAUDE.md § "Compiling RIDDL examples". Compare numbers only within one scope.
-
-**Rules the work established** (each earned by a regression):
-
-- Wrapper-internal names keep the `Example` prefix. A record named `OrderData`
-  collided with `language-reference.md`'s own prelude — a page prelude and the
-  wrapper share one context — and broke two of its fences.
-- Wrapper vocabulary is only ever ADDED, never renamed: an extra field cannot
-  break a fence that ignores it.
-- **Re-run the FULL gate after any wrapper edit**, never just the page in hand.
-  Wrapper changes have regressed other pages three times in this work.
-- A wrapper must satisfy the checks its own shape triggers: `in-entity` needs a
-  state with a handler, or a fence contributing only invariants fails for the
-  wrapper rather than for itself.
-
-**Why this outranks 1b:** these pages are already gated, so the gate reports
-green while checking barely 40% of their RIDDL. That is the same
-"green-but-measured-nothing" failure recorded in NOTEBOOK.
+## 1a-followup. Content bugs found by gating language-reference.md
+
+← START HERE
+
+**What:** Retiring the blanket skips (1a, done 2026-08-10) compiled every
+fence on the page that can compile. The 20 that still carry a skip each name
+their own reason now, and these are the ones whose reason is **the example is
+wrong**, not "the harness cannot wrap it". Each was read off a real riddlc
+diagnostic, so none needs re-deriving:
+
+- **`OrderPlaced` has two different shapes on one page.** One fence yields
+  `OrderPlaced(id, total)`, another `OrderPlaced(orderId, total = cart.total,
+  currency = "USD")`. A prelude can supply only one. Decide which is the
+  event and make both fences agree.
+- **The epic's steps use paths the page's own application fence contradicts.**
+  `step take input Storefront.AddToCartForm` treats the form as a direct child
+  of the context, while the application fence puts forms inside `page`s. 2.0
+  containment agrees with the application fence, so the epic's paths are
+  wrong.
+- **The adaptor example crosses its own isolation seam.** `PaymentIntegration`
+  emits `OrderPaymentReceived`, which belongs to neither its parent context
+  nor its referent. 2.0 rejects this. The example needs the event declared in
+  `OrderContext`, which means showing it.
+- **The projector example has no record.** A 2.0 projector requires one.
+- **`button Checkout activates type Boolean`** — the fifth page carrying this
+  line. Still not valid 2.0.
+- **The `version` fence's `entity Order` has no handler and no state.**
+- **`match order.status`** matches a String against type-cases and a numeric
+  `>=` threshold. For it to compile, `status` would have to be an enumerated
+  type — which directly conflicts with the `set field status to "Active"`
+  fence. The two examples cannot both be right.
+
+**Also parked, and NOT a content bug:** the `repository CartRepository` fence
+names `record Cart` in its schema, while the page prelude must supply
+`entity Cart` for other fences. One context cannot hold both names. Fixing it
+means renaming the prelude's entity and every fence that reaches it, which is
+a bigger edit than it looks.
+
+**Verification:** the page and both gates are green as it stands — 2.0 at
+183/43/0, 1.31 at 6/0/0. These are skips with honest reasons, not failures,
+so nothing is red while they wait.
 
 ---
 
@@ -109,11 +55,18 @@ green while checking barely 40% of their RIDDL. That is the same
 **What:** Not yet gated: `tutorials/rbbq/` (30 pages, the most-read tree),
 `guides/`, `tools/`, and the `riddlg`/`synapify`/`shell` sites.
 
+**17 blanket skips live in these trees** and are the natural first slice:
+`migration/1.x-to-2.0.md` (6), `guides/authors/design/command-event-patterns.md`
+(6), `guides/authors/design/ui-modeling.md` (3), `guides/authors/index.md` (2).
+They are the last of the original 118. These trees also carry 4 pre-existing
+failures, so starting here means going red before green -- gate a page at a
+time.
+
 **Also open:** `check-riddl-blocks.py` flags 33 advisory items, all in
 `migration/` (which shows 1.x deliberately — arguably belongs in EXEMPT_PATHS)
 and `tutorials/rbbq/`.
 
-**Order:** After 1a, which is smaller and buys more real coverage.
+**Order:** after 1a-followup, which fixes examples readers can see today.
 
 ---
 

CLAUDE.md

@@ -407,7 +407,19 @@ render, so readers never see them:
 | `<!-- riddl: skip -->` | not validated |
 
 A page may declare a `<!-- riddl-prelude ... -->` block of definitions that its
-fragments reference but do not show.
+fragments reference but do not show. It lands at **context** level whatever the
+wrapper's depth.
+
+Domain-level vocabulary is a **separate** `<!-- riddl-domain-prelude ... -->`
+block, read only by `in-domain`. The two cannot be one block — a `user` is
+legal only in a domain, a `record` only in a context. It is what makes
+whole-`context` fences gateable: a domain body may hold type definitions, and a
+bare name resolves upward and across sibling contexts, so a sibling context in
+the domain prelude can supply outlets and events a fence names but never
+declares.
+
+A fence that defines a name a prelude also supplies must say
+`no-prelude=Name`. This applies to **both** preludes by the same names.
 
 `--auto` tries every wrapping and reports a fence only if none works. It is a
 *measurement* mode for pages that do not yet carry directives — not a
@@ -430,11 +442,26 @@ python3 scripts/validate-riddl-examples.py ../bin/riddlc "${files[@]}"
 # 1.31 -- same shape over sites/riddl-1x/docs, with the 1.31 compiler
 ```
 
-**Status**: `quickstart.md` is fully annotated and validates clean on both
-branches. The ~50 concept pages are not yet annotated; with `--auto`, 99 of
-their 120 fences still fail, dominated by fragments that reference definitions
-they deliberately do not show and so need a per-page prelude. That is a
-known gap, not a claim that those examples are wrong.
+**Status** (2026-08-10): the gated set is **183 validated / 43 skipped / 0
+failed**, and **every blanket `"illustrative fragment"` skip is gone** — there
+were 118 of them when the work started. `quickstart.md`, `concepts/`,
+`introduction/` and `references/language-reference.md` are all annotated and
+green. Every remaining skip states its own reason.
+
+A skip is not a pass in disguise: ~20 of them record examples that are
+genuinely wrong for 2.0, tracked as BACKLOG 1a-followup. `guides/`,
+`migration/` and `tutorials/rbbq/` are still ungated (BACKLOG 1b).
+
+**Two ways this gate can lie to you, both observed:**
+
+- A **hand-rolled probe that filters only `[error]`/`[severe]` will call a
+  fence clean that the gate rejects** — the gate also fails on `[deprecated]`.
+  Filter exactly as `validate()` does, or use the gate itself.
+- **A malformed directive silently degrades to `standalone`.** There is no
+  warning for a directive that does not parse, so a deliberate skip can quietly
+  become a validated fence. The `[^>]*` bug that caused this is fixed, but the
+  failure mode is structural: if a fence's result surprises you, check that its
+  directive actually parses before believing the result.
 
 **Version differences that matter for examples** (verified against both
 compilers):

NOTEBOOK.md

@@ -11,84 +11,124 @@ to the task file and note completion in this notebook.
 
 ---
 
-## HANDOFF — as of 2026-08-10
+## HANDOFF — as of 2026-08-10 (late)
 
 **All figures below were run in this session, not recalled.**
 
-**State:** branch `main`, tree clean, **0 commits ahead of `origin/main`**,
-HEAD `e446a20`. Everything is pushed; CI has deployed from it.
+**State:** branch `main`, tree clean, **2 commits ahead of `origin/main`** —
+`c52287c` (validator fixes) and `faa4cbe` (the page). Not yet pushed.
 
 **Compiler:** `../bin/riddlc` is **`2.0.0-rc.10-57-e012ebb9`** and `build.sbt`'s
-`With.Riddl.library` pin matches exactly. The Homebrew `riddlc` on PATH is
-**2.0.0-rc.5** and is the WRONG compiler for the 2.0 docs. riddlc is restaged
-often — re-check the binary against the pin at session start.
+pin matches exactly. The Homebrew `riddlc` on PATH is **2.0.0-rc.5** and is the
+WRONG compiler for the 2.0 docs. Re-check the binary against the pin at session
+start; it is restaged often.
 
-**Gates:** 2.0 — **171 validated / 55 skipped / 0 failed, exit 0**; 1.31 —
-6/0/0. `mkdocs build --strict` on `sites/riddl` clean.
+**Gates:** 2.0 — **183 validated / 43 skipped / 0 failed, exit 0** (was
+171/55); 1.31 — 6/0/0. `mkdocs build --strict` on `sites/riddl` clean.
 
 **`task/` holds only `done/`.** Nothing awaits triage.
 
-### In flight — BACKLOG 1a
+### BACKLOG 1a is DONE
 
-Retiring the blanket `"illustrative fragment"` skips. **49 remain**, from 118
-at session start. `concepts/` and `introduction/` are **finished**.
+**Not one blanket `"illustrative fragment"` skip remains in
+`sites/riddl/docs`** — 118 at the start of the work, 0 now. The 20 skips left
+on `language-reference.md` each state their own reason.
 
-`references/language-reference.md` is **half-done and is where to resume**: 12
-of its 44 retired (page 23/52 → 35/40), and **the other 32 were restored
-verbatim** so the page is green. That restore is deliberate, not abandoned
-work — the gate must never be left red.
+**Next is BACKLOG 1a-followup**, which is the subset of those reasons that mean
+*the example is wrong*: `OrderPlaced` shown with two different field sets on
+one page, epic steps whose paths contradict the page's own application fence,
+an adaptor that crosses its isolation seam, a projector with no record. All
+were read off real riddlc diagnostics — do not re-derive them.
 
-**BACKLOG 1a carries the measured analysis of those 32** — which want
-`in-handler`, which want `in-domain` plus a domain prelude the page still
-lacks, which are genuinely unskippable, and which hide known content bugs.
-Read it first; it cost a full pass to derive.
-
-The other 17 sit in `migration/` and `guides/`, **outside the gate scope**,
-in trees carrying 4 pre-existing failures. Starting them starts BACKLOG 1b.
+The remaining 17 blanket skips site-wide are in `migration/` and `guides/`,
+outside the gate, and are now folded into BACKLOG 1b.
 
 ### Traps
 
 - **The gate's scope is a FILE LIST, not a directory** — exact command in
   CLAUDE.md § "Compiling RIDDL examples". A figure is only comparable within
-  one scope; if one fails to reproduce, re-measure against the parent commit
-  rather than trusting it. That is why the inherited "108/107" was discarded.
+  one scope.
 - **The gate truncates diagnostics** to a position. For the real message,
-  import the script as a module, re-wrap with `wrap()` (mirroring any
-  `no-prelude`), and run `../bin/riddlc validate <file>` — a bare path, there
-  is no `--input-file` flag.
-- **Re-run the FULL gate after any wrapper or script edit.** Wrapper changes
-  have regressed unrelated pages four times.
-- **`annotate-riddl-examples.py` places a fence against the prelude AS IT
-  WAS.** Extending the prelude afterwards silently invalidated 8 placements.
+  import the script as a module, re-wrap with `wrap()`, and run
+  `../bin/riddlc validate <file>` — a bare path, there is no `--input-file`.
+- **A diagnostic filter that watches only `[error]`/`[severe]` will lie to
+  you.** The gate also fails on `[deprecated]`, so a hand-rolled probe called
+  a fence clean that the gate then rejected. Filter exactly as the gate does.
+- **Re-run the FULL gate after any wrapper or script edit**, and the 1.31 gate
+  too — a script change is not scoped to one tree. Wrapper changes have
+  regressed unrelated pages five times now.
+- **Extending a prelude regresses fences that were already green.** Adding
+  `currency` to `OrderPlaced` broke a fence in a different section; adding a
+  domain-level `Storefront` broke two more. Re-run the whole page after every
+  prelude edit, not just the fence in hand.
 - **Prelude/wrapper name collisions run both ways.** Wrapper names keep an
-  `Example` prefix; equally, a prelude must not take a name a wrapper supplies
-  — `function Tax` broke every in-function fence on its own page.
-- **Annotate fences by LINE NUMBER**, never by matching a fence's first line.
+  `Example` prefix; equally a prelude must not take a name a wrapper supplies.
+- **Annotate fences by LINE NUMBER**, never by matching a fence's first line —
+  and check the match is unique before writing, since several fences on this
+  page share an opening line.
 
 ### Certainty
 
 **Verified by command this session:** git state, both compiler versions, the
-pin, both gates, the strict build, that `task/` is empty, and that no
-unexecuted plan in `~/.claude/plans/` holds open work for this repo.
+pin, both gates, the strict build, that `task/` is empty, and that zero blanket
+skips remain.
 
-**Verified by compiling:** every example on the 25 pages changed, plus the
-rules recorded in BACKLOG 1a and in the pass entries below.
+**Verified by compiling:** every fence on `language-reference.md`, and every
+claim in BACKLOG 1a-followup.
 
-**Assumed, not re-verified:** BACKLOG item 5's 18 site items were carried over
-as written and none was re-checked against the current site. The gh-pages
-deploy triggered by the last push was not inspected.
+**Assumed, not re-verified:** BACKLOG item 5's 18 site items. The gh-pages
+deploy state — nothing has been pushed this session.
 
 ### Pointers
 
-Open work is **BACKLOG.md** — 1a is live. Durable facts are **CLAUDE.md**,
-notably § "Things that will bite" and § "Compiling RIDDL examples".
+Open work is **BACKLOG.md** — 1a-followup is live. Durable facts are
+**CLAUDE.md**, notably § "Things that will bite" and § "Compiling RIDDL
+examples".
 
 **Run `/ossuminc-skills:check-tasks` in the new session.**
 
 The sections below are kept as the record of how the current state was reached.
 
 ---
 
+### BACKLOG 1a, final pass: language-reference.md done ✅ **2026-08-10**
+
+The last 32 blanket skips retired; page 35/40 → 47/28, gate 171/55 → 183/43.
+1a is complete.
+
+**The harness was hiding work behind "no wrapper fits" — four separate ways.**
+The pattern from pass 4 (annotate kept a stale copy of the wrapper list)
+turned out not to be a one-off:
+
+- `no-prelude` reached only the page prelude, so a whole-context fence could
+  never use a domain prelude — the single biggest lever on the page was
+  unreachable, not absent.
+- `PRELUDE_ENTRY` did not match an intention prefix, so
+  `application context Storefront` was invisible to `no-prelude`.
+- **`DIRECTIVE` used `[^>]*`, so a skip reason containing `>=` ended the match
+  early and the fence silently became `standalone`.** This one fails toward
+  false confidence: a deliberate skip quietly turns into a validated fence.
+  It cost three mystery failures that looked like lost directives.
+
+**A domain prelude works because bare names resolve across sibling contexts.**
+That was worth proving rather than assuming, so it was checked in both
+directions — a bare `outlet Pings` in another context resolved, and a bogus
+name failed. A domain body may hold type definitions, which is what makes the
+stream events placeable.
+
+**Some fences cannot be made green without lying.** The adaptor example emits
+a message belonging to neither its parent nor its referent context. A prelude
+*can* silence that by hiding the event in the referent — and doing so would
+defeat exactly the check that makes the gate worth running. Those fences got
+an honest skip and a BACKLOG entry instead.
+
+**Two examples on one page can be mutually exclusive.** `match order.status`
+needs `status` to be an enumerated type; `set field status to "Active"` needs
+it to be a String. No prelude satisfies both, and that is a content decision,
+not a harness gap.
+
+---
+
 ### BACKLOG 1a, pass 4: language-reference.md, first slice ✅ **2026-08-10**
 
 12 of its 44 blanket skips retired (page 23/52 → 35/40); the other 32 restored