test+docs: drift guards batch — grammar completeness, docs sync, surface-authority honesty (architecture review F1/F6/F9)

[silversurfer562]

Summary

Batch C of the 2026-08-20 dynamic-forms architecture review. Stacked on #52 (base: claude/forms-cleanup-batch) — merge that first, then retarget/merge this.

The review's central ruling was to ACCEPT the ~19-file per-construct cost as the honest price of four surfaces (a construct means something different on each one) and pin it with drift catchers instead of abstractions. This batch is those pins.

Changes

• tests/test_grammar_completeness.py (F1 pin): every QuestionType member must carry a row in two completeness tables (widget collect mode + a canonically wrong-shaped answer), and each of the four surfaces must emit construct-specific output for it — widget data-collect modes, AskUserQuestion expansion counts (derived from the shared helpers), elicitation-schema property shapes, the markdown reply skeleton's answer shapes, and validator rejection by field name. A construct wired into only three surfaces, or a 16th type added without updating the tables, fails red instead of degrading silently.
• tests/test_docs_drift.py (F6): README's spelled-out construct count must track the enum (it rotted by hand once — 543a7a0), README/SKILL.md must describe every construct/question type, and every MCP tool or x_to_y library function the skill names must actually exist.
• docs/adding-a-construct.md: the 19-touchpoint checklist with file anchors, PRs feat: ranking construct — grammar member #7 (0.6.0) #24/feat: assumption-review construct — grammar member #8 (0.6.0) #25 as worked examples, and the rejected alternatives (base class, entry points, codegen) recorded so they stay rejected.
• Surface-authority honesty (F9): select_form_surface's docstring and the README now state that in the shipped plugin the router is advisory — the agent's MCP tool choice is the effective decision (skill prose ladder), the router runs after the fact for telemetry agreement, and its answer is binding only for library consumers routing their own calls. The markdown-surface gap in its range is noted for the 0.7.0 follow-through (Batch D).

Not in this batch (release-gated → 0.7.0, Batch D)

SKILL.md step 4 still instructs library-only markdown calls a plugin-only (uvx) install cannot make (F3). That fix is either two thin MCP tools or an honest degradation paragraph — a chair decision on the 0.7.0 train.

Verification

• Full suite: 715 passed.
• Mutation check: changing README's "eight constructs" fails test_readme_states_the_real_construct_count red.

🤖 Generated with Claude Code