docs(wiki): digest the mdl/grammar findings into three bug-pattern pages

[ako]

Stacked on #358 — and note that #356, #357 and #358 are all still open (main is at #352). This branch also merges current main in, so the chain stays current.

49 of the 53 mdl/grammar findings (92%) now fall under a named class. Three pages are new; the rest reuse describe-round-trip-gaps and silent-property-drop.

page	thesis
capability-gap-as-parse-error	an unspelled capability presents as no viable alternative — and the user concludes the feature is impossible
keyword-collisions	the distinguishing question is how a collision fails, not whether one happens
scripts-that-cannot-rerun	statement-level idempotence, which is not the write-level idempotence people mean

capability-gap-as-parse-error

The distinctive class in this area, and the one with the clearest cost. A parse error is indistinguishable from a mistake the user made, so the reports are not feature requests — they are workarounds:

• an admin screen hand-rolled as five pages with bespoke SCSS, because a tab container was believed not to exist (two days);
• "use a Java action" for a binary upload;
• "go to Studio Pro" as the standing answer to translating an app;
• a headless pipeline that ends in a manual step, because anonymous access has no statement.

The gap is bidirectional. MDL not being able to write a construct is half of it — DESCRIBE of a document that has one must do something, and dropping it silently is the common outcome. In the mapping findings it did worse: emitted MDL that parsed and rebuilt a different document, which looks like a successful round trip and is not.

Two method points recorded: a narrow/wide statement pair is a whitelist that gets extended one bug report at a time (SET vs REPLACE), so the fix is to reuse the wide rule rather than add another case to the narrow one; and "not in the metamodel" is not a conclusion until the namespace is right — a grep under one prefix ruled out a capability that lives under another, and one 4 KB Studio Pro unit settled in minutes what the grep had "disproved".

keyword-collisions

A parse error is recoverable — the user quotes the name. The same collision resolving to a different valid parse is not: a widget conditional calling trim() was silently dropped, so the page lost its visibility rule and built cleanly.

A grammar alternative and its visitor case are one change. Accepting an unquoted -7 in XPath without the matching AST case made the constraint serialize as [Amount > ] — a dropped operand instead of a loud error, caught only because the visitor has a round-trip helper. And a relaxation is proven with a control binary (stash the .g4, regenerate, sweep every example with both), not by reading: 13 scripts failed with the change, the same 13, all pre-existing.

One correction before committing

The coverage figure in CLAUDE.md said 98%. The measurement says 92%, and I'd written the first number from memory rather than from the script. Corrected in the same commit, and noted in the commit message.

Where the digest stands

area	findings	covered
mdl/executor	248	83%
cmd/mxcli	95	92%
mdl/backend	83	99%
mdl/grammar	53	92%
mdl/visitor	28	—

🤖 Generated with Claude Code