[saingge]

Branch fix/exec-model-scope-wiring, one commit (f8147b3) on origin/master 95e1b30. Lane 3 (direct). It follows #559, which put model-scope.py on master. It stands alone: nothing is stacked on it and it does not need the canvas PRs.

What changed and why

model-scope.py (#559) finds units a write changed only in XPath whitespace, as mxcli v0.27.0's alter entity … rename attribute did to 135 units in 20 unrelated modules of a Mendix 10.24.18 app (mendixlabs/mxcli#1596). On master nothing calls it: project-bin/exec.sh and the pre-commit hook do not mention it. This PR puts it where the noise is made and where it would be committed.

• exec.sh runs model-scope.py restore right after the write (MDL and --patch) and before the mxbuild gate, so the gate checks the final model. It prints the counts and the real changes per module, and adds a scope: N unit file(s) changed, R real, K noise restored note to the BUILD-LOG row. It never blocks: a non-zero exit prints a warning, the write is kept with any noise not yet restored, and model-scope.py's own message says what it left (a part-way restore keeps the index matching). MXTK_NO_SCOPE=1 skips it, and it is skipped when FORCE_EXEC let the write run over uncommitted model changes, where the diff against HEAD is not this write's alone.
• The pre-commit hook (marker v2) runs model-scope.py check --staged before the stamp check and refuses staged noise, naming restore as the remedy (a commit is not the remedy). MODEL_SCOPE_OK=1 lets one commit through. A project without model-scope.py skips the check silently; a machine without Python gets a warning; either way the commit stands. --check reports a v1 hook as stale, and a re-run rewrites it in place instead of chaining it as a foreign hook. The core.hooksPath advice gains the matching line.
• Two lines in what new(model-scope): find and put back units a write changed only in XPath whitespace (replaces #535) #559 merged are corrected. The header of model-scope.py ("Run it by hand; nothing calls it yet.") now says bin/exec.sh runs it after each write to a committed model, and the CHANGELOG entry for new(model-scope): find and put back units a write changed only in XPath whitespace (replaces #535) #559 ("Not wired into exec.sh or the pre-commit hook yet.") now points at the entry above it. Both were true when merged and are not true with this change.

Impact

Row	Answer
Process	One new commit-time refusal: staged units that changed only in XPath whitespace. Remedy python3 -I bin/model-scope.py restore; one-commit override MODEL_SCOPE_OK=1. exec.sh gains a step that never blocks. Projects pick the hook up on the next sync-project.sh (--check now reports v1 as stale).
Dependencies	project-bin/exec.sh (shared; the _detail line of the BUILD-LOG row also carries ${ROWS_NOTE} on master now, and this adds ${SCOPE_NOTE:+ · $SCOPE_NOTE} after the HV_NOTE part) and project-bin/install-project-hooks.sh, plus the model-scope docstring line and CHANGELOG line above. Draft #311, which edited the same _detail line, was closed unmerged (read 2026-10-28). Draft #384 (exec --on-copy, open, unchanged since 2026-10-19) writes the live model only after the gate, so this step would see nothing to restore under --on-copy. Whichever merges second should run the step after the promotion, or skip it under --on-copy with a note.
Context cost	none: no routed or always-loaded file touched. render-routing.sh --check, base 95e1b30 and head: both "Baseline: 65444 words (budget 80000)", all ten output lines identical.
Behaviour	n/a: scripts only.
Runtime	Per exec: one model-scope.py restore, which reads only the unit files git reports as changed. Measured report at 0.19 s on the golden capture (3 changed units, 2026-10-21); not measured on a large model.

Field evidence

Field run of this wiring, end to end (2026-10-21, on the earlier base; the commit's content is unchanged by the rebase except the _detail line). Scratch copy of a Mendix 10.24.18 enterprise app (own git repository, HEAD = clean pre-write state; this branch's project-bin installed with sync-project.sh --only-bin, hooks with bin/install-project-hooks.sh). ./bin/exec.sh ran one mxcli v0.27.0 attribute rename. The scope step reported 149 unit files changed, 3 real, 146 noise in 21 modules (a different rename from the one #1596 reports, 135 units in 20 modules), and restored the 146. exec.sh's own mxbuild gate then ran on the restored model (mxbuild 10.24.18 through a Docker shim set as MXBUILD_PATH): 0 errors, exit 0, 94 s for the whole exec. The BUILD-LOG cell read scope: 149 unit file(s) changed, 3 real, 146 noise restored. The hook accepted the commit of that result. The rename back, run through exec.sh with MXTK_NO_SCOPE=1, left 149 changed units (its gate also passed: the noise is harmless to mxbuild and costly to a reviewer); git commit then refused (exit 1, "146 staged unit file(s) changed only in XPath whitespace"), and MODEL_SCOPE_OK=1 git commit went through with the WARNING.

I did not repeat the field run on 95e1b30; the fixture below covers the rebased code.

Checklist

• No client data anywhere in the diff (LEAKGUARD_ALLOW_NO_DENYLIST=1 LEAKGUARD_BASE=origin/master bin/check-no-client-data.sh: clean; fixture names are synthetic).
• Size: 4 counted files, 189 lines changed (185 added, 4 removed), excluding CHANGELOG. Within the cap.
• Test tier: T1 (the subject's fixture and the fixtures that target the changed files, below) and T2 (the field run above, on the earlier base).
• Instrument change: none beyond one docstring line; the wiring is exercised in test-model-scope.sh sections E and F. macOS only; Git Bash/Windows not run (Python found through resolve_py, paths through native_path).
• [n/a] New skill.
• CHANGELOG.md line, credited, and the new(model-scope): find and put back units a write changed only in XPath whitespace (replaces #535) #559 line corrected.
• [n/a] Bug entries.

Verification

Run on this branch (f8147b3, rebased on 95e1b30), macOS arm64, 2026-10-29.

bash tests/wave2/test-model-scope.sh project-bin/model-scope.py -> PASS: 60  FAIL: 0

• Sections E (hook) and F (exec.sh) add 21 of the 60. E: installed hook calls model-scope.py; staged noise refused and no commit made; MODEL_SCOPE_OK=1 commits; a real change commits; a v1 hook is reported "older version" by --check and upgraded in place with no .pre-mxtk chain; no model-scope.py and the hook does not block. F: exec.sh with a stub mxcli that rewrites 3 units' XPath whitespace and makes 1 real change prints "4 unit file(s) changed, 1 real, 3 noise", "restored 3 noise unit(s) from HEAD", "real changes by module"; 1 unit left changed; ContentsHash index clean; the mxbuild gate stub saw 1 changed unit, so it checked the restored model; the BUILD-LOG row carries the scope note. MXTK_NO_SCOPE=1 leaves 4 changed. --patch restores 2 noise units and the gate saw 1. No model-scope.py: exec.sh runs as before.
• Control: the same fixture with origin/master's exec.sh and install-project-hooks.sh swapped in -> PASS: 47 FAIL: 13, every E/F guard failing, so the checks catch a missing wiring.
• Fixtures that install the hook or read the BUILD-LOG row: test-model-stamp.sh 35/0, test-mx-metadata-note.sh 40/0, test-exec-gate-log.sh 24/0, test-exec-hash-verify.sh 43/0, test-exec-step-times.sh 7/0.
• CI floor: bin/check-scripts.sh 125/125 shell and 25/25 Node parse; bin/check-pr-discipline.sh origin/master clean; bin/render-routing.sh --check in sync, baseline 65444; bin/mdl-rules.sh --check in sync; bin/check-portability.sh clean; bin/check-no-private-citations.sh clean; bin/check-no-client-data.sh clean; bash tests/run-tests.sh passed=33 failed=0.
• bash tests/wave2/run-all.sh: not run to the end (about 180 fixtures; the machine was too loaded). Instead the 56 fixtures that name the files this change touches (exec.sh, the hook installer and model-scope) were run the way run-all.sh runs them, on a copy of this branch (before a last amend that changed comments, one docstring, the CHANGELOG line and the commit message, and no code line) and on a copy of origin/master, with identical exit codes. The other fixtures were not run.

[MendixMau]

Triage (outside PR, code not run): DISCUSS track. Verdict: DISCUSS, plus a required rebase.

• Why DISCUSS:
  • It adds a new commit-time refusal, the pre-commit hook v2, in every entry mode that commits a model. That is a process-path change: it changes what blocks.
  • It adds a step to every exec.sh run. That is a performance change, landing right after Exec speed: mx check gate by default, doctor performance check, Windows overhead fixes (#584, #585) #587 and exec: ~60% fewer process starts per exec (Windows overhead, #584/#585) #590 cut the per-exec process starts.
• Rebase needed:
  • project-bin/exec.sh conflicts for real with master 60e369b. Exec speed: mx check gate by default, doctor performance check, Windows overhead fixes (#584, #585) #587 made mx check the default gate and exec: ~60% fewer process starts per exec (Windows overhead, #584/#585) #590 restructured the hot path. Overall exec.sh has moved about 360 lines since the base 95e1b30.
  • install-project-hooks.sh merges cleanly but has also moved about 46 lines.
  • After the rebase the scope step must still sit before whichever gate runs, and the field run should be repeated on the new base.
• Injection / malicious code: none found. Every added line read.
  • No hidden or bidi characters, no network calls, no credential reads.
  • Hook writes stay in the project's own .git/hooks.
  • restore runs git checkout HEAD -- <noise units> in the project only.
  • It is skipped under FORCE_EXEC, i.e. when the model was already dirty.
• Guard rules: met.
  • Rule 7: the remedy is model-scope.py restore, which is not a commit, so the hook never blocks its own fix.
  • Rule 6: MODEL_SCOPE_OK=1 overrides one commit, out loud.
  • A missing script or missing Python never blocks.
• Value: High while mxcli v0.27.x produces this noise. Without it, one rename leaves reviewers reading 135–146 untouched units (alter entity ... rename attribute rewrites XPath constraints in documents that never reference the attribute and drops their line breaks mendixlabs/mxcli#1596).
• Options:
  1. As proposed: restore during exec, and the hook refuses staged noise. This is the strongest protection, but every project picks up a new refusal at its next sync-project.sh. A v1 hook shows as stale until it's reinstalled.
  2. Restore in exec.sh; the hook only warns. Writes that go through exec get cleaned up. Noise from writes made outside exec still gets through, with a warning. No new refusal.
  3. Opt-in: both behaviours off unless MXTK_SCOPE=1 is set in the project. Zero risk, but low reach, which is the "documented only as advice" problem from Speed follow-ups: Stage 3 in parallel by default, facts-lock resolve + Stage 2 check, row-groups reads backticked plans #586's facts-lock.
• Recommendation: 1, after the rebase. On Windows the PR should also report what the step costs per exec, given exec: ~60% fewer process starts per exec (Windows overhead, #584/#585) #590's process-start budget. The refusal is cheap to get past, and the noise costs reviewers far more than the step costs exec.
• Decision needed from the maintainer: should the pre-commit hook refuse whitespace-only units by default (option 1), only warn (option 2), or should both be opt-in (option 3)?

---

Generated by Claude Code

[MendixMau]

Maintainer decision: option 2, with a narrower scope.

What's new: mxcli v0.29.0 (released 2026-10-30) fixes the source of this noise upstream:

rename attribute no longer rewrites every unrelated XPath constraint with a line break in it, 147 units in 21 modules on one project (ako/mxcli#1506)

The fix is commit c7b06400, and v0.29.0 is the only release that contains it. v0.28.0 already kept the line breaks an author writes into an XPath constraint. Only projects still on mxcli v0.27 or v0.28 can produce this noise now.

What that means for this PR:

1. Keep the model-scope.py restore step in exec.sh. It never blocks and is cheap insurance for projects on mxcli < 0.29. Please rebase it onto current master: the exec.sh conflict comes from Exec speed: mx check gate by default, doctor performance check, Windows overhead fixes (#584, #585) #587 and exec: ~60% fewer process starts per exec (Windows overhead, #584/#585) #590.
2. Drop the pre-commit hook v2 refusal, together with the marker bump and --check staleness. With the upstream fix shipped, a new commit-time refusal in every synced project costs more than it protects. model-scope.py check --staged stays available to run by hand.
3. Optional: in the exec.sh step's header, note that the noise source is fixed in mxcli ≥ 0.29.0, so the step can be retired once older versions are out of use.

Still needed: a Windows timing for the step on the new base (process starts after #590), and the independent merge review.

Thanks for the careful field run. It made this an easy call.

---

Generated by Claude Code

[MendixMau]

Thank you @saingge — the core of this landed in #606 (merged as 2a51963), with you kept as commit author: exec.sh now restores the model scope before the gate and records it in the BUILD-LOG line.

We took a reduced scope to keep regression risk down: the hook-side refusal and fixture section E were left out. Closing this one in favour of #606; happy to discuss the remaining parts in a new issue if you still need them.

---

Generated by Claude Code