Sync ako/mxcli: agent loop efficiency, page/widget writes, workflow fixes

.claude/commands/mxcli-dev/review.md

@@ -11,7 +11,8 @@ burned us before.
 ## Steps
 
 1. Run `gh pr view` and `gh pr diff` (or `git diff main...HEAD`) to read the change.
-2. Work through the CLAUDE.md "PR / Commit Review Checklist" in full.
+2. Work through CLAUDE.md's "Working Rules for a Change" (the evidence bar) and
+   the subsystem checklists at the end of this file, in full.
 3. Then check every row in the Recurring Findings table below — flag any match.
 4. Report: blockers first, then moderate issues, then minor. Include a concrete fix
    option for every blocker (not just "this is wrong").
@@ -68,3 +69,86 @@ proactively. Add a row after every review that surfaces something new.
 - [ ] Recurring Findings table updated with any new pattern.
 - [ ] If docs-only PR: every function name, path, and PR reference verified against
       live code before approving.
+
+## The subsystem checklists
+
+These moved out of CLAUDE.md, where they were re-read into every session but only
+apply when a change touches that subsystem. The evidence bar for a bug fix, and
+the one-thing-per-commit rule, stay there because they govern how the work is
+done rather than how it is reviewed.
+
+### Overlap & duplication
+- [ ] Check `docs/11-proposals/` for existing proposals covering the same functionality
+- [ ] Search the codebase for existing implementations (grep for key function names, command names, types)
+- [ ] Check `mdl-examples/doctype-tests/` for existing test coverage of the feature area
+- [ ] Verify the PR doesn't re-document already-shipped features as new
+
+### Syntax design for MDL features
+New or modified MDL syntax must follow the design guidelines. See [ADR-0003: MDL is SQL-shaped](docs/13-decisions/0003-mdl-is-sql-shaped.md) for the underlying decision and rejected alternatives; the design checklist below operationalises it.
+- [ ] **Design skill consulted** — read `.claude/skills/design-mdl-syntax.md` before designing syntax
+- [ ] **Follows standard patterns** — uses `create`/`alter`/`drop`/`show`/`describe`, not custom verbs
+- [ ] **Reads as English** — a business analyst understands the statement on first reading
+- [ ] **Qualified names** — uses `Module.Element` everywhere, no implicit module context
+- [ ] **Property format** — uses `( key: value, ... )` with colon separators, one per line
+- [ ] **LLM-friendly** — one example is sufficient for an LLM to generate correct variants
+- [ ] **Diff-friendly** — adding one property is a one-line diff
+
+### Version compatibility
+New features that depend on a specific Mendix version must be version-gated:
+- [ ] **Registry entry** — feature added to `sdk/versions/mendix-{9,10,11}.yaml` with correct `min_version`
+- [ ] **Executor pre-check** — `checkFeature()` called before BSON writes, with actionable error and hint
+- [ ] **Test coverage** — version-gated tests use `-- @version:` directives or `requireMinVersion()`
+- [ ] **Skill updated** — `.claude/skills/version-awareness.md` updated if the feature has a workaround for older versions
+
+### Backend abstraction compliance
+All executor code must go through the backend abstraction layer. **`sdk/mpr` no longer exists** — the package was deleted once its importer count reached zero, so reaching past the abstraction is now a compile error rather than a rule to remember. See [ADR-0002: Backend Abstraction Layer](docs/13-decisions/0002-backend-abstraction.md) for the context and alternatives. The codec (`modelsdk`) engine is the only local engine — the legacy `sdk/mpr` backend was deleted (`docs/plans/2026-09-14-retire-legacy-engine.md`), and `--engine`/`MXCLI_ENGINE` survive only as a warning-only no-op. It routes **all** document types — domain models included — through the codec, not a codec/legacy hybrid; see [ADR-0004: Full codec engine](docs/13-decisions/0004-full-codec-engine.md). Where the codec path cannot yet reproduce a construct, the backend **refuses** the op rather than dropping data. The backend interface speaks the **semantic model**, not gen/BSON or AST types — gen+codec are the MPR backend's internal storage adapter, one of several (MPR, MCP/PED, a future storage format); see [ADR-0005](docs/13-decisions/0005-semantic-model-interface-currency.md). CREATE is model→gen; fidelity-sensitive ALTER uses backend-internal gen-mutation, not a model round-trip.
+- [ ] **No engine internals in the executor** — executor files must not reach into `modelsdk/mpr`, `modelsdk/codec` or `modelsdk/gen` directly; use `ctx.Backend.*` instead. A method missing from the backend gets implemented there, not bypassed
+- [ ] **New backend methods on the interface** — any new data access or mutation goes in the appropriate interface in `mdl/backend/` (e.g., `DomainModelBackend`, `MicroflowBackend`), not as a direct SDK call
+- [ ] **MPR implementation in `mdl/backend/mpr/`** — the concrete implementation lives here; all BSON/reader/writer logic stays in this package
+- [ ] **Mock stub in `mdl/backend/mock/`** — every new backend method has a `Func`-field stub with a descriptive `"MockBackend.X not configured"` error default (not `nil, nil`)
+- [ ] **Compile-time interface check** — new backend implementations have `var _ backend.SomeInterface = (*impl)(nil)`
+- [ ] **ALTER operations use mutator pattern** — page/workflow mutations go through `ctx.Backend.OpenPageForMutation()` / `OpenWorkflowForMutation()`, not inline BSON construction
+- [ ] **New shared types in `mdl/types/`** — a type used by more than one layer goes in `mdl/types/` and the others alias it (`type Foo = types.Foo`), never as duplicate definitions. A same-shape duplicate compiles and tests green; it shows up only as an assignment failure *across* the boundary, naming the same type on both sides of "want". `modelsdk/mpr/version.ProjectVersion` was that case and is now an alias — the guard is a compile-time assertion (`var _ *types.ProjectVersion = (*version.ProjectVersion)(nil)`, `version_alias_test.go`), which builds only under an alias and so is stronger than anything a test body can assert
+- [ ] **Map iteration is deterministic** — any map iterated for serialization output must sort keys first (`sort.Strings(keys)` pattern); non-deterministic output causes flaky diffs and BSON instability
+- [ ] **Pluggable widgets via WidgetEngine** — new pluggable widget support uses `.def.json` + `WidgetRegistry`; no hardcoded BSON widget builders in the executor
+
+### Full-stack consistency for MDL features
+New MDL commands or language features must be wired through the full pipeline:
+- [ ] **Grammar** — rule added to `MDLParser.g4` (and `MDLLexer.g4` if new tokens)
+- [ ] **Parser regenerated** — `make grammar` run; generated files in `mdl/grammar/parser/` are **not** committed (they are regenerated by `make` at build time)
+- [ ] **AST** — node type added in `mdl/ast/`
+- [ ] **Visitor** — ANTLR listener bridges parse tree to AST in `mdl/visitor/`
+- [ ] **Executor** — thin handler in `mdl/executor/` dispatches to `ctx.Backend.*`; no BSON in the handler
+- [ ] **Backend method** — data access or mutation wired through `mdl/backend/` interface and implemented in `mdl/backend/mpr/`
+- [ ] **LSP** — if the feature adds formatting, diagnostics, or navigation targets, wire it into `cmd/mxcli/lsp.go` and register the capability
+- [ ] **DESCRIBE roundtrip** — if the feature creates artifacts, `describe` should output re-executable MDL
+- [ ] **VS Code extension** — if new LSP capabilities are added, update `vscode-mdl/package.json`
+
+### Test coverage
+- [ ] New packages have test files
+- [ ] New executor commands have MDL examples in `mdl-examples/doctype-tests/`
+- [ ] **MDL syntax changes** — any PR that adds or modifies MDL syntax must include working examples in `mdl-examples/doctype-tests/`
+- [ ] **Bug fixes** — every bug fix should include an MDL test script in `mdl-examples/bug-tests/` that reproduces the issue, so the fix can be verified in Studio Pro if applicable. **Three numbering namespaces meet in that directory**: the historical files are named after `mendixlabs/mxcli` **PR** numbers (`261-mx9-microflow-roundtrip.mdl` is upstream PR #261), issues filed on the fork are `ako/mxcli` numbers — and the two sequences already collide on 261–266 — while a few names are a **Mendix version** with the dot dropped (`1113-database-query-type-enum.mdl` is Mendix 11.13, not issue 1113). Name a file after a fork issue with a topic prefix (`mapping-261-object-handling-backup.mdl`) and write the reference qualified (`ako/mxcli#261`) wherever it appears, or the number silently resolves to the wrong thing
+- [ ] Integration paths (not just helpers) are tested
+- [ ] Tests don't rely on `time.Sleep` for synchronization — use channels or polling with timeout
+
+### Security & robustness
+- [ ] Unix sockets use restrictive permissions (`os.Chmod(path, 0600)`)
+- [ ] File I/O is not in hot paths (event loops, per-keystroke handlers) — cache in memory
+- [ ] No silent side effects on typos (e.g., auto-creating resources on misspelled names should be flagged)
+- [ ] Method receivers are correct (pointer vs value) for mutations
+
+### Documentation
+- [ ] **Skills** — new features documented in `.claude/skills/` (syntax, examples, gotchas)
+- [ ] **CLI help (Cobra)** — `mxcli` subcommand help text updated (Cobra `Short`/`Long`/`Example` fields)
+- [ ] **CLI help (syntax topics)** — `cmd/mxcli/syntax/features_*.go` updated with new/changed MDL syntax; new `SyntaxFeature` entries added for new document types; `OR MODIFY` / `OR REPLACE` variants reflected in existing `Syntax` fields; accessible via `mxcli syntax <topic>` and REPL `help`
+- [ ] **Syntax reference** — `docs/01-project/MDL_QUICK_REFERENCE.md` updated with new statement syntax
+- [ ] **MDL examples** — working examples added to `mdl-examples/` for new commands
+- [ ] **Site docs** — `docs-site/src/` pages added or updated for user-facing features
+
+### Code quality
+- [ ] Refactors are applied consistently across all relevant files (grep for the old pattern)
+- [ ] Manually maintained lists (keyword lists, type mappings) are flagged as maintenance risks
+- [ ] Design docs match the actual implementation — remove or update stale plans
+- [ ] Numeric type conversions are bounds-checked — `float64→int` casts need overflow guards (`±2^53` for safe integer range); silent overflow produces garbage in serialized output
+- [ ] `convert.go` updated when structs in `mdl/types/` gain or lose fields — `TestFieldCountDrift` will catch this at test time, but `convert.go` must be updated before merging

.claude/skills/diagnose-ce0463.md

@@ -196,3 +196,18 @@ Ordered by how often they have actually been the answer.
 - **Test any candidate fix against the bundled package too.** Pruning the fields the
   `update-widgets` reference omits fixes 2 widgets on Data Widgets 3.10 and takes the
   bundled 3.4 from **0 → 139**.
+
+## Pluggable Widget Templates
+
+For pluggable widgets (DataGrid2, ComboBox, Gallery, etc.), templates must include **both** `type` AND `object` fields:
+- `type`: Widget PropertyTypes schema (defines what properties exist)
+- `object`: Default WidgetObject with all property values
+
+**CE0463 "widget definition changed" error**: This error occurs when the Object's property structure doesn't match the Type's PropertyTypes. Always extract templates from Studio Pro-created widgets, not programmatically generated ones. See `sdk/widgets/templates/README.md` for details. For debugging CE0463 and other BSON issues, follow the workflow in `.claude/skills/debug-bson.md`.
+
+## `mxcli fix widgets` clears CE0463 after a headless install
+
+`fix widgets` / `fix design-properties` run `mx update-widgets` and
+`mx rename-design-properties` and **persist** the result without their MPR v2 -> v1
+collapse: let the tool convert, read the units back, restore v2, write the changed
+ones through mxcli's writer. Measured 203 -> 0 errors on a vanilla 11.12.1 app.