Document the two silent breaking changes for AST consumers

Everything else in the 2.0 breaking-changes list announces itself as a
parse or validation error. These two keep consuming Scala compiling while
changing what it does, so a clean build is not evidence of a clean
migration -- which is how riddl-generator silently lost every event
handler and synapify hit four sites of the same shape.

`OnEventClause` is now a SIBLING of `OnMessageClause`, so a
`case _: OnMessageClause` compiles unchanged and stops matching event
handlers, with missing output rather than an error as the symptom. Both
extend `OnMessageLikeClause`, verified at AST.scala:3707/3778/3823, and
the guide names that parent -- "match on the common parent" is only
actionable if the parent is named.

`object StreamletShape` (AST.scala:4401) shadows a consumer's own type of
that name under `import AST.*`, and the resulting error points at
AST.StreamletShape rather than at the import.

Requested by riddl in task/add-silent-breaking-changes-to-2.0-migration-
guide.md; all three task files are now reconciled and moved to done.

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

Author: reid-spencer

NOTEBOOK.md

@@ -13,10 +13,9 @@ to the task file and note completion in this notebook.
 
 ## RESUME HERE — as of 2026-08-03
 
-**Tasks A–K are all closed.** What is still open:
+**Tasks A–K are all closed, and `task/` is empty** (everything in `task/done/`).
+What is still open:
 
-- `task/publish-riddl-license-page.md` — needs a change in **riddl**, not here;
-  see the note at the end of TASK C.
 - The ~50 concept pages still lack per-fence directives. 26 fences fail
   site-wide against rc.9, but no file is above three, which is the agreed
   threshold — a known gap, not a regression.
@@ -30,6 +29,35 @@ The sections below are kept as the record of how the current state was reached.
 
 ---
 
+### Task-queue triage ✅ **2026-08-03**
+
+Reid's point — *if it needs a change in riddl, drop a task there or it will
+never happen* — turned out to apply to the tracking itself. All three files in
+`task/` were reconciled:
+
+- **`publish-riddl-license-page.md`** — needed **no** riddl task. riddl had
+  already changed all three places in `733573373` (2026-07-30), the same day
+  our "still outstanding" note was written. The note was stale from the moment
+  it was filed and sat on the open list for four days because nobody re-checked
+  the other repo. Verified end to end: `riddlc info` prints
+  `/riddl/2.0/licenses/`, which returns 200.
+  riddl's reason is better than ours, and worth keeping: notices describe the
+  dependencies of **that** release, so a `/latest/` page would show a 2.0 user
+  the notices of a future build. Version-pinning is right on its merits.
+- **`activate-verb-now-parses.md`** — already done; `element.md` documents both
+  spellings and carries no caveat.
+- **`add-silent-breaking-changes-to-2.0-migration-guide.md`** — **genuinely
+  outstanding**, and the one that would have been lost. Now done: the migration
+  guide has a "Silent changes for tools that read the AST" section covering the
+  `OnEventClause`/`OnMessageClause` split and `AST` companion shadowing. Both
+  claims were re-verified against `AST.scala` rather than trusted — the shared
+  parent is `OnMessageLikeClause` (line 3707), which the guide names, because
+  "match on the common parent" is only actionable if the parent is named.
+
+**Lesson:** two of three were already done and one was quietly rotting. Check
+`task/` against the *other repo's* current state, not against what the task file
+says about it.
+
 ### TASK K — AST / Finder / Pass API documentation ✅ **DONE 2026-08-03**
 
 New page: `guides/developers/ast-api.md`. Nothing existed — the developer guide
@@ -559,10 +587,16 @@ removal of the old root-level `1.31/ 2.0/ latest/ next/`. Deleting the old
 layout *last* rather than first meant no outage — the old URLs kept serving
 until their replacements were live.
 
-**Still outstanding:** `task/publish-riddl-license-page.md`. The page is live at
-`/riddl/2.0/licenses/`, but `riddlc info` still prints `/riddl/licenses/`, which
-404s and cannot be made to work — the second path segment is a version. riddl
-must change three places, not the one the task file mentions.
+**Closed 2026-08-03:** `task/publish-riddl-license-page.md` is in `task/done/`.
+The note that used to sit here said `riddlc info` still printed the unversioned
+`/riddl/licenses/` and that riddl had to change three places. **riddl had
+already changed all three** — commit `733573373`, 2026-07-30, the same day this
+note was written. It was stale from the start and stayed on the open list for
+four days because nobody re-checked the other repo.
+
+Verified end to end: `riddlc info` prints `/riddl/2.0/licenses/`, and that URL
+returns 200 with the notices. Bump the constant, its test and
+`THIRD-PARTY-NOTICES.txt` together on each documented minor release.
 
 **Known wart:** the merge to `main` bypassed a branch-protection rule ("must not
 contain merge commits") because it was `--no-ff`. It was allowed through rather

sites/riddl/docs/migration/1.x-to-2.0.md

@@ -224,6 +224,59 @@ work.
 - A context-scoped connector whose ends cross contexts is under-scoped
 - An ascribed shape that contradicts the declared port arity is an Error
 
+### Silent changes for tools that read the AST
+
+Everything above announces itself as a parse or validation error. **These two do
+not.** They change the RIDDL libraries' Scala API in ways that keep consuming
+code compiling while changing what it does, so a clean build is not evidence of
+a clean migration. Both cost real debugging time — the first in
+riddl-generator, the second in synapify and sim-engine.
+
+Skip this if you only write RIDDL; it matters only if you write Scala against
+`AST`.
+
+#### `on event` clauses no longer match `OnMessageClause`
+
+`OnEventClause` is now a **sibling** of `OnMessageClause` rather than a subtype.
+Both extend `OnMessageLikeClause`.
+
+So this keeps compiling and silently stops matching event handlers:
+
+```scala
+case omc: OnMessageClause => …          // no longer sees `on event` clauses
+```
+
+The symptom is **missing output, not an error** — a generator quietly emits
+nothing for events. Match on the shared parent instead, or add an explicit case:
+
+```scala
+case c: OnMessageLikeClause => …        // both kinds
+// or
+case omc: OnMessageClause => …
+case oec: OnEventClause   => …
+```
+
+#### New `AST` companions can shadow your own types
+
+2.0 adds companion objects to `AST`, including `object StreamletShape`. If you
+have a type of the same name — sim-engine has a `StreamletShape` enum, and so
+would any tool modelling shapes — and you use a wildcard import, RIDDL's
+companion shadows yours, and the error points away from the cause:
+
+```
+value Source is not a member of object AST.StreamletShape
+```
+
+Your enum is intact; the import is the problem. Import selectively, or rename
+on import:
+
+```scala
+import AST.{StreamletShape => _, *}
+```
+
+See [AST, Finder and Passes](../guides/developers/ast-api.md) for the API more
+generally.
+
 ---
 
 ## 2. Deprecations