feat(doctor, sync-project): mxcli fix property-sets in the upgrade path, report first; model-stamp.sh known-fix note

[MendixMau]

Depends on #315 (the baseline word trim), which is merged into this branch. The new learned-detection-gaps.md row needs room in the baseline budget, so merge #315 first.

#295: adopt mxcli v0.25/v0.26 commands (partial)

Problem. mxcli up to v0.25 wrote units that are missing part of the property set Studio Pro writes. mx check, the build and the runtime all pass. Studio Pro's merge/diff then throws ("Objects with ID … do not have the same properties") once Studio Pro has saved such a document. No toolkit gate saw it.

Fix: report first; repair only through the gate.

bin/doctor.sh --property-sets <project> runs mxcli fix property-sets -p <mpr> --dry-run, which is read-only. Exit codes:

Exit	Meaning
0	clean
1	units need repair (NEEDS/FAILED rows)
2	not run: no model, no mxcli, or a timeout
3	this mxcli is older than v0.26.0 and has no fix property-sets
4	could not check: an error, unclassifiable output, a crashed fix --help probe, or no readable Mendix version. A repair would not help, so none is suggested.

There is never a green result by absence.

• Receipt. Only settled results are recorded in .claude/.property-sets-receipt: clean, needs, failed, and unsupported. Unsupported is recorded only when mxcli fix --help itself ran. The receipt is machine-local and gitignored, and adding it to .gitignore is announced. Errors and timeouts are never recorded.
• --if-stale. Skips the run only when the receipt holds a clean or unsupported result for the installed mxcli. A needs result or a one-off error is checked again.
• Time bound. The dry-run is bounded by MXTK_PROPSETS_TIMEOUT: 300 s by default in doctor, and 120 s by default under sync. It uses timeout when a working one is on PATH, and a polling watchdog otherwise.
• Repair. bin/doctor.sh --fix-property-sets <project> runs the repair only through bin/exec.sh --patch, which gives it a snapshot, the mxbuild gate, and restore on failure. doctor.sh is its own patch script. It refuses when the project's exec.sh has no --patch, and it re-checks after the repair.
• doctor (full run) includes the check.
• doctor --quick only compares the receipt with the installed mxcli. It warns while the check is owed or the last result was not clean. If the support probe crashed, it says "could not probe" rather than saying the mxcli predates the command. exec.sh runs --quick whenever the mxcli version changes.
• sync-project.sh (section 4d) first prints checking property sets (read-only, up to 120s)…, then runs the check with --if-stale. It never repairs. How it handles each exit:
  • Exit 1 gets a sync warning that names --fix-property-sets.
  • Exit 3 gets an info line saying to upgrade mxcli.
  • Exit 4 gets a neutral line, could not check property sets: <reason>. There is no warning and no repair advice.
  • Exit 2 shows doctor's NOT RUN note.
  • With --dry-run, sync only says it would run the check.
• Docs.
  • skills/learned-detection-gaps.md gets a short row: trigger, rule, and one line showing the failure.
  • skills/platform-link.md (loaded on demand) gets a section, "Before a Team Server merge". It covers fix property-sets, fix hashes and git note, plus the sync, --quick and timeout behaviour.
  • Trap 6c is untouched, because fix(platform-link): CLI commits show their changed documents in Studio Pro History #271 is changing that section.

Evidence. Checked against mxcli source at v0.26.0 (cmd/mxcli/cmd_fix_property_sets.go) and the release binaries:

• The dry-run exits 1 both when units need repair and on errors such as "project not found" (captured). So the rows decide the result, never the exit code alone.
• On v0.24.0 and v0.25.0, mxcli fix property-sets --help exits 0 and prints the parent fix help (captured). For that reason, support is detected from the mxcli fix --help listing.

Golden input. Captured from the official v0.24.0, v0.25.0 and v0.26.0 linux-amd64 binaries. None of them was run against a model.

• --version
• fix --help, cut at "Global Flags:"
• fix property-sets --help on v0.25
• a dry-run against a missing project

The clean, NEEDS and FAILED reports are not captured, because they need a real model. The test stub prints them from mxcli's source format strings, and the fixture header says so.

Still pending in #295:

• fix hashes as an exec.sh --patch post-step. exec.sh is owned by another PR in flight, so the patch was proposed separately and is not in this PR.
• git note vs fix(platform-link): CLI commits show their changed documents in Studio Pro History #271. mxcli git note -p <mpr> [--write] (v0.26.0) supersedes fix(platform-link): CLI commits show their changed documents in Studio Pro History #271's note computation (mx-metadata-note.py changes/write/backfill):
  • It computes ModelChanges from the .mpr unit index plus mprcontents at the commit and its parent.
  • It keeps notes Studio Pro wrote and replaces placeholders.
  • It does not replace fix(platform-link): CLI commits show their changed documents in Studio Pro History #271's post-commit/post-rewrite hooks, the notes push-refspec wiring, or sync <remote> (the 3-way notes merge).
  • Suggestion: fix(platform-link): CLI commits show their changed documents in Studio Pro History #271's hook calls mxcli git note --write when the project's mxcli is v0.26 or later, and falls back to the Python script otherwise.

#236 remainder

• known_fix_note in bin/sync-project.sh gets the model-stamp.sh) arm from patch 0004. It is keyed on GIT_WORK_TREE and says to upgrade model-stamp.sh and _common.sh together.
• tests/wave2/test-model-stamp.sh T9 adds the unstaged worktree cases commit -a and commit -- app.
• The silent rc 1 half of [bug] sync-project dies silently (rc 1) before its bin/ drift section, so a pre-fix model-stamp.sh is never reported #236 was already on master.

Review

Three rounds of independent review, all applied on this branch:

1. First review: MERGE-AFTER-SMALL-FIX.
   • Unsettled results (errors, timeouts, a failed help probe) are never cached. --if-stale short-circuits only on a recorded clean or unsupported result.
   • The dry-run got a time bound, with a timeout treated as NOT RUN.
   • The .gitignore append is announced.
   • In sync, an old mxcli shows as an info line, not a WARN.
   • The detection-gaps row was trimmed to trigger + rule + one failure line, and the mechanics moved to platform-link.md.
   • origin/master (Small fixes: arg parsing (#309), demo-video rules (#237), port holder before run --local (#262), detection gaps (#299), test strength (#172) #313) was merged in.
2. Lead correction. An intro edit to learned-detection-gaps.md, made only to fit the budget, was reverted, because a feature PR does not squeeze other text (process(merging): independent review before every merge #316). The room comes from chore(context): free baseline word budget without dropping rules #315, which is merged in. With it, LC_ALL=C bin/render-routing.sh --check reports the baseline at 76292 words against a budget of 80000.
3. Confirmation review: MERGE-AFTER-SMALL-FIX.
   • Sync announces the check and its bound, using its own 120 s default.
   • A check that could not run gets exit 4, which sync reports with a neutral line and no repair advice.
   • --quick says "could not probe" when the probe crashed.
   • The fixture stub's slow state now execs sleep, so no child process is left behind.

Checks run

• tests/wave2/test-property-sets.sh: 61 passed, 0 failed. The first-round version also fails on master's doctor.sh and sync-project.sh (23 passed, 35 failed).

• Existing fixtures for the changed files, all passing:

  Fixture	Result
  test-model-stamp	35/35
  test-bug12-sync	61/61
  test-sync-dup-heading-exit	6/6
  test-sync-past-stock	22/22
  test-dryrun-writes-nothing	6/6
  test-doctor-docker-probe	18/18
  test-doctor-gate-selftest	28/28
  test-ritual-slim	17/17
  test-slim-claude-md	16/16

  After the last round, only the doctor/sync-dup-heading/dryrun fixtures were re-run.

• Repo checks, all clean: check-no-client-data, check-pr-discipline, check-scripts (109/109), check-portability, check-no-private-citations.

• LC_ALL=C bin/render-routing.sh --check: in sync; baseline 76292 words, budget 80000.

Field run

Still owed. Nothing was run against a real model. Still to do:

• Run --property-sets on a project written with v0.24, to capture the real report rows and the timing on a large model.
• Run --fix-property-sets through a real exec.sh gate.

Windows/Git Bash has not been run either.

Risks

• On a very large model, the dry-run can hit its time bound (120 s under sync, 300 s in doctor). It then reports NOT RUN and is not recorded. Raise the bound with MXTK_PROPSETS_TIMEOUT.
• A FAILED unit makes exec.sh roll back the whole repair. This is deliberately conservative, and it is documented.

Refs #295
Closes #236

🤖 Generated with Claude Code

https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw

[MendixMau]

Landed on master as part of the integration squash #329 (commit 31e90ae), after independent review — its Review: line is in that commit message. Closing as superseded.

---

Generated by Claude Code