docs(proposal): project brain, with the brief's assumptions verified

[ako]

Response to mendixlabs/mxcli#1017, which asks for a proposal in docs/11-proposals/, for the brief's assumptions to be checked against the codebase rather than trusted, and for implementation to wait for review. No code here.

The four assumptions — all four needed amending, one is wrong

1. Can MDL write Documentation? Partly. Doc comments and ALTER ENTITY … SET DOCUMENTATION work for domain-model objects, but the surface is uneven — and there is a recorded finding that create … comment 'text' was accepted and wrote nothing on seven doctypes, and was removed rather than wired. Phase 3 now opens with a per-doctype audit.

2. What does the catalog give us, and how fast? Everything needed, for free. The objects view unions 43 document types with a QualifiedName. Measured on a real project (382 objects, 1.6 MB catalog):

resolve one anchor: 0.038 ms   (mean of 1000)

Speed should not shape the design. Two caveats that should: the view indexes only describable types — so a missing anchor is not proof of staleness, and check needs a third state — and member-level anchors (@Mod.Entity.Attr) need attributes_data, a second query.

3. Starlark rules generated at runtime? The question doesn't arise. Rules are discovered from .claude/lint-rules/*.star by walking up, so a generated rule is just a generated file — no engine work. The hazard the brief misses is that mxcli init writes bundled rules into that same directory, so generated ones need a reserved filename prefix and ID namespace.

4. Release and skill mechanics? There is no goreleaser. No .goreleaser.yml exists; releases run make release. Skills ship via //go:embed all:skills from cmd/mxcli/skills/, mirrored from .claude/skills/mendix/ with rsync --delete — so the embed directory must never be edited directly.

Evidence from mxcli's own store of this shape

The proposal's §3 is the part I'd most want reviewed. mxcli already runs a store of exactly this design — the bug findings and their docs-wiki/bug-patterns/ digest — and it has failed in four ways all reachable from the brief as written:

• it grew past being readable — 1.05 MB / 630 rows, and the instruction to read it before diagnosing was unfollowable for months, because an unread file has no failure mode;
• the digest nothing triggered stopped — three pages written on one day in May, none re-synced for three months while the corpus grew 200×;
• append-only + merge=union produced silent duplicates — main currently holds 885 records of which 629 are distinct; the executor shard is essentially the same 247 findings twice;
• claims about the mechanism went stale, including a README and a PR body that both said the check ran in CI when it did not.

None of that argues against the feature. It argues that the parts of the brief that look like restraint — the caps, no auto-promotion, promote-only-through-a-human — are the parts carrying the design, and the plumbing is where it will fail. Seven amendments (A1–A7) are each traced back to one of these findings or to §2.

Open questions, recorded not answered

1. What does brain check --ci cost on a cold clone? Catalog validity is an .mpr mtime comparison that a fresh checkout always fails.
2. Is docs/ the right home when a project already has one that isn't ours?
3. THEORY.md does not exist anywhere in the repository — the issue says to read it and to update it if the working theory changes.

🤖 Generated with Claude Code