forms: the DSL's key vocabulary has no table-completeness gate, unlike wire.md

[Yaraslaut]

morph::forms has become a domain-specific language: a renderer that is not
morph's own must implement 26 x-* schema keys, 5 document keys (w-steps,
w-title, app-menu, app-screens, app-title) and 13 rule/condition kind
strings, and an application author must reach a C++ declaration surface of 64
public types and 44 public free functions across 10 headers (5,526 lines).

docs/spec/forms/ documents it — 6 files, 4,388 lines — and today it does so
almost completely. The problem is not the prose. It is that nothing can
notice when the prose stops being complete, and this is precisely the
situation morph#233 established a gate for on the other spec that third parties
implement against.

Measured coverage today

Every "x-*" / "w-*" / "app-*" string literal in include/morph/forms/**,
and every public type and free function outside a detail namespace, checked
against the concatenated text of docs/spec/forms/*.md:

Surface	Documented
Wire keys (26 x-* + w-steps, w-title, app-menu, app-screens, app-title)	31 / 31
Public types, concepts, aliases	62 / 64
Public free functions	40 / 44

The six gaps are small and worth closing on the way past:

• concepts HasExplicitSubmit and RuleLiteral are never named in the spec
  (the explicitSubmit member is documented; the concept that detects it is
  not).
• fieldKeyStem, fieldSlotName and withSlot (forms/i18n.hpp) and
  groupKindName (forms/layout.hpp). For the i18n three the spec documents
  the key format — <actionTypeId>.<wireField>.<slot> — but never names the
  functions that build it, so the seam is described and its API is not.

There is also a systematic asymmetry rather than an omission: the rule
constructs AtLeastOneOf, ExactlyOneOf, MutuallyExclusive, ReadonlyWhen,
NotEngaged, Equals, Greater, GreaterOrEqual, Less, LessOrEqual and
Plain appear in the spec only under their JSON-key spellings
(atLeastOneOf, …). A reader emitting JSON is fully served; a reader writing
C++ has to infer the capitalisation of every one of them.

Why the prose being fine today does not settle it

Two gates touch this area and neither can see completeness:

1. .github/workflows/spec-sync.yml requires only that some file under
   docs/spec/forms/ changed when include/morph/forms/** changed. A commit
   that adds x-newKey to forms.hpp and a typo fix to choice.md passes.
2. scripts/check_spec_citations.sh checks 1–3 work outward from
   docs/spec/pinned_facts.toml, a hand-maintained list. A key nobody pinned
   is a key nobody checks.

Check 4 of that same script is the shape this needs. It exists because
docs/spec/core/wire.md presented itself as exhaustive and was not — the
Envelope table omitted primary and shared, the discriminator table omitted
attach/assign/instances, and four make* factories were missing
(morph#233). Its reasoning applies here verbatim:

Nothing could notice, because morph's own client and server both read
wire.hpp — so neither can observe that the spec disagrees with it. Only a
check that reads both can.

morph's own Qt/QML renderer reads the same headers the schema generator does.
It cannot observe the spec disagreeing with them either. forms.md likewise
presents its key table as the renderer contract ("Renderer contract: the schema
key vocabulary"), and the renderer conformance kit is written against that
claim.

Proposal

Add a check 6 to scripts/check_spec_citations.sh, mirroring check 4:

• every "x-*" literal in include/morph/forms/** is a row in
  docs/spec/forms/*.md;
• every "w-*" / "app-*" document key likewise;
• every rule/condition kind string (atLeastOneOf, engaged, equals,
  exactlyOneOf, greater, greaterOrEqual, less, lessOrEqual,
  mutuallyExclusive, notEngaged, readonlyWhen, requiredWhen,
  visibleWhen) is documented as a kind, and its C++ constructor name is named
  beside it — which closes the capitalisation asymmetry above by construction.

Inherit check 4's per-category floors, not a lumped total. That check
carries a comment recording why: a lumped count let uint64_t Envelope fields
parse to nothing while the other two categories carried the total over the
line, and the check reported green while ignoring a whole category. A forms
version has the same failure mode across keys / document keys / rule kinds.

Extend scripts/test_check_spec_citations.sh with the matching self-test, as
the other drift-guard checkers have.

Acceptance

• Deleting any documented x-* row from docs/spec/forms/forms.md fails the
  check locally.
• Adding a new "x-…" literal to a forms header without documenting it fails
  the check locally.
• A category that parses to zero fails rather than passing quietly.
• The six gaps listed above are closed and the check passes on master.

[Yaraslaut]

Verified

Read scripts/check_spec_citations.sh on current master. It has exactly the 5 checks the issue references (its own header comment enumerates them 1-5), including check 4, "wire.md table-completeness" (scripts/check_spec_citations.sh:170-233), built for morph#233 exactly as described. grep -i forms scripts/check_spec_citations.sh returns nothing — confirmed there is no check 6, and no forms-specific completeness gate exists anywhere in the script.

Confirmed the two gates the issue says can't see completeness: spec-sync.yml's forms subdomain check only requires some file under docs/spec/forms/ to have changed alongside include/morph/forms/** — a substring match on changed paths, not a content check — so the "add x-newKey, touch an unrelated line in choice.md" scenario the issue describes would indeed pass.

Spot-checked the key-inventory claim rather than trusting it wholesale (per the "re-measure a number" step): grepped every "x-*" string literal across include/morph/forms/** and got 27 distinct keys, one more than the issue's stated 26 (x-colspan, x-computed, x-decimalPlaces, x-exactMaximum, x-exactMinimum, x-group, x-hidden, x-i18nKey, x-instanceConstraints, x-layout, x-max, x-maximum, x-min, x-minimum, x-optionLabel, x-optionValue, x-optionsAction, x-optionsDependsOn, x-order, x-placeholder, x-readonly, x-rules, x-section, x-step, x-submitMode, x-unitAlternatives, x-widget). Off by one from a naive grep, plausibly x-max/x-min counted as aliases of x-maximum/x-minimum in the issue's own count rather than distinct keys — this doesn't change the conclusion (a substantial, non-trivial key vocabulary exists and none of it is gated for completeness), but the exact count should be re-derived mechanically by whoever implements check 6, not taken from either count by hand.

Also spot-checked the file/line-count claim: docs/spec/forms/ actually has 7 files (choice.md, forms.md, instance_constraints.md, sections.md, views.md, widget_hints.md, workflows_navigation.md), summing to ~4,534 lines — the issue says "6 files, 4,388 lines." Both numbers are off by a small margin (one extra file, ~150 extra lines), most likely just spec prose that grew between when the issue was drafted and now. Immaterial to the core claim.

Invariant

Invariant 7 applies directly and is the whole point of the issue: "would this still pass if the feature did nothing?" A spec-sync.yml pass on a forms header change proves only that some forms doc line changed, not that the new key is documented — indistinguishable from the check having no forms-awareness at all. The issue's own citation of morph#233's precedent (an exhaustive-looking table that silently wasn't) is the right anchor: forms.md's key table makes the same "renderer contract" claim wire.md did before #233.

Verdict: triage: valid, area: forms, area: ci

Well-framed: real, demonstrated gap (no completeness gate for the forms DSL's key vocabulary, unlike the wire protocol's), a fix already shaped on an established, working precedent (check 4), and acceptance criteria that specifically guard against the "lumped total" failure mode check 4 itself warns about (per-category floors, not one combined count) — this is exactly invariant 7's discipline applied to itself. Not filing bug: this is a missing gate, not a defect in shipped runtime behavior or a spec/code disagreement (the six named gaps are minor and the issue itself frames closing them as incidental, not the main ask). Leaving both existing area labels (forms for the domain being gated, ci for the gate mechanism itself) since the change genuinely spans both.