MendixMau · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
 
 ## Unreleased
 
+- new(app-facts): **the app map's loop sweep is incremental, and `bin/status.sh` says how stale the map is** ([#297](https://github.com/MendixMau/mxcli-project-toolkit/issues/297)). Every run re-described every loop-containing microflow: on a 17,500-unit app that was 1,917 describes in 2 h 45 at 6 workers (about 31 s each, not the 1-2 s `app-analysis.md` promised), while about 80 units had changed between rounds. `manifest.json` now stores a `{UnitID: ContentsHash}` snapshot of the `.mpr` Unit table and an `mdl_index` recording the unit state each `mdl/` file was described from. A refresh describes only candidates whose hash, module or folder changed, or that have no output, keeps the rest and deletes outputs of removed or loop-free units. The sweep is full on the first run, with `--full`, after an mxcli version change, or when the Unit table cannot be read (MPR v1); `sections.loops.sweep` says which and why. UnitID-to-name mapping is `mx-metadata-note.py units`, the Studio Pro History note's own walk, refactored into a shared `Model` base for git revisions and the working tree. The hash is computed from the `.mxunit` bytes in the column's format, so a Unit-table row that lags its file cannot hide a change; disagreements are counted in the manifest. `bin/status.sh` prints `app map: N units changed since <date>` or `app map: fresh` when a map exists (`app-facts.sh --freshness`, no mxcli needed; the unit list goes through a temp file, never an env var, so it works past ~1,600 units), and nothing otherwise. A `--skip-loops` run keeps the last loop sweep's snapshot, so a stale loop map never reads fresh. `app-analysis.md` gives the measured cost by app size and names `--full` as the remedy after edits made outside Studio Pro. Fixture `tests/wave2/test-app-facts-incremental.sh`, 108 checks on both layouts with captured template units and a stub mxcli: all describes on a first run, 0 when nothing changed, 1 for a changed, moved, or stale-row unit, a removed unit's output deleted, a failed describe retried, a renamed module re-described under its new name, `--freshness` and status.sh on 2,101 units, a `--skip-loops` run not reading fresh, outputs byte-identical to `--full` and to a fresh full run, and the status line; 78 checks fail against master. `tests/wave2/bench-app-sweep.sh`, 2,000 units with 1 % changed: 20 describes incremental against 2,000 full, and `--freshness` reads fresh / 20 changed / fresh. Follow-up, not built: skip re-hashing unchanged `.mxunit` files by mtime + size. Field evidence: no field run; checked on synthetic and captured fixtures only. Not built: replacing describe with catalog queries (mxcli v0.25 `activities` with loop depth), NEEDS-FIELD-DATA, a real v0.25 catalog capture to check parity with the parser. — jopterhorst (#297)
 - process(build): **Stage 5 drafts the ready set in parallel and applies serially.** The runbook dispatch row said "sequential within a module", which serialised drafting even for independent scripts; it now points to `iterative-build-loop.md` → Gate cost, the single statement of the rule. The unit is the build-plan row: every `BUILD` row whose "Depends on" rows are all applied, minus overlapping writers (two rows that replace, alter or drop+create the same document never share a ready set, and no row is drafted while it overlaps a queued unapplied one; `brd-to-build-plan.md` has Produces name every document a row writes), runs at once, its scripts in order, one `mdl-agent` per script. Applies stay one at a time through `bin/exec.sh`, and the ready set is recomputed after each. A queued draft made before a sibling apply landed is re-checked with `mxcli diff --format struct` (preflight STOP rule 23); any removal line (checked against `describe` per BUG-146) or STOP rule 21 target means re-draft, never patch, because a stale restatement of a shared document is exactly rule 21's silent seed-call loss and passes `check --references`. Report `ready set N, drafted N, applied k`; the `mdl-agent` template says a drafter never applies and never depends on an unapplied draft. Field evidence: none yet. — MendixMau
 - fix(platform-link): **CLI commits now show their changed documents in Studio Pro History.** Studio Pro's History → Model changes pane reads a `ModelChanges` array from the commit's `refs/notes/mx_metadata` note. Trap 6c's hand-written template set it to `[]`, so every mxcli/agent commit showed "Model changes 0" (field project: 270 of 270 notes empty). New `project-bin/mx-metadata-note.py` (stdlib only) computes the array from the commit's changed `.mxunit` files, in Studio Pro's entry shape: Status, UnitID, UnitType, UnitName and Module (walked up the `.mpr` Unit tree). It has `changes` / `write` / `backfill` / `sync <remote>` subcommands. `install-project-hooks.sh` now also installs post-commit and post-rewrite hooks that write the note and never block, and `--check` covers them, so `sync-project.sh` rolls them out to wired projects. Notes are published with `mx-metadata-note.py sync <remote>` after the branch push. Push config is never touched. With mxcli v0.26+ in the project root the hooks call `mxcli git note --write` instead (mendixlabs/mxcli#1337); the Python script is the fallback for older pins, and on 160 field commits both wrote the same 3,594 entries. Trap 6c rewritten. Measured against Studio Pro's own notes, 51 commits in 5 apps: 3387/3389 entries exact on all five fields. Field run on a 357-commit Mendix 11.15.0 app: 158 notes backfilled and pushed, and Studio Pro History lists the documents per revision. Review fixes: an earlier revision added `HEAD` + the notes ref to `remote.<r>.push`. It was dropped because any push refspec replaces `push.default`. A branch tracking a differently named upstream got a new same-named branch on Team Server where `simple` refuses, a missing local notes ref failed the whole push, and nobody knows whether Studio Pro's own push reads that config. The installer now only fetches the remote's notes (non-forced). It removes that exact `HEAD` + notes pair if present, and leaves and reports any other entry. `sync` handles a remote with no notes ref (it used to exit 1) and retries a rejected push once after re-merging. A note that already lists changes (Studio Pro's) is never overwritten by `write`/`backfill` without `--force`, and `sync` keeps a colleague's non-empty note over ours. The mxcli probe greps `git note --help` for `--write`. Hooks and docs call the script through `resolve_py`. Fixture `tests/wave2/test-mx-metadata-note.sh` (40 cases, over real captured template units; single- and two-tree layouts, amend, backfill and `--force`, push exit codes identical to a no-hooks clone, leftover-refspec cleanup, sync to an empty remote and its retry, notes fetch at install, a diverged notes merge; green under `init.defaultBranch` master and main). — field project (Mendix 11.15 app), MendixMau
 - learn(fixture-seeding): **explore the data structure first, choose rows by use case, scan actions for resets before any run.** Two seeding runs on public template apps: seeding raised journey passes 33 -> 58 and 20 -> 51 of the same sets (FAIL 93 -> 68, 163 -> 132; INVALID unchanged), and a "Reset all demodata" journey wiped accounts so 104 of 127 journeys reported `The username or password you entered is incorrect`, identical on empty and seeded databases. Skill gains three questions a seed must answer, a use-case checklist, a destructive-action scan, a generic traps table with symptoms, measured expectations and a denominator checklist; routing trigger now fires on seed/test/demo data and empty pages. Independent review fixes: object ids follow the Mendix bigint pattern with a business-key guard (no uuids), associations are seeded where the page's path stores them, four new traps (enum names, inheritance chain, calculated attributes, view/external entities), and the port-offset and container-label traps moved to `harness-architecture.md`. — MendixMau

diff --git a/bin/status.sh b/bin/status.sh
@@ -149,6 +149,16 @@ if [ -f "$MS_FILE" ]; then
     END { printf "manual steps pending %d of %d", p, t }' "$MS_FILE")"
 fi
 
+# --- app map freshness (#297) --------------------------------------------------------------
+# The map (skills/app-analysis.md) costs hours on a large model, so how stale it is matters:
+# app-facts.sh --freshness compares the .mpr Unit table now with the {UnitID: ContentsHash}
+# snapshot the last map stored. No map, no line — the screen is unchanged for projects without one.
+APPMAP=""
+if [ -f "$PROJECT_DIR/analysis/app-facts/manifest.json" ]; then
+  APPMAP="$(PROJECT_ROOT="$PROJECT_DIR" bash "$TOOLKIT_ROOT/project-bin/app-facts.sh" --freshness \
+            --facts-dir "$PROJECT_DIR/analysis/app-facts" 2>/dev/null | head -1)"
+fi
+
 # --- doctor receipt -------------------------------------------------------------------------
 DR="$PROJECT_DIR/.claude/.doctor-receipt"
 if [ -f "$DR" ]; then
@@ -267,7 +277,7 @@ done
 if [ "$BRIEF" = 1 ]; then
   echo "WHERE   $NAME · $STAGE_LINE${ENTRY:+ · $ENTRY}${ADOPTED:+ · joined at $ADOPTED}"
   [ -n "$ROUND_LINE" ] && echo "ROUND   $ROUND_LINE"
-  echo "STATE   scripts $N_SCRIPTS written / $N_PASS gate-pass / $N_DONE done- · modules opened $MOD_OPENED${SKELETON:+ · skeleton $SKELETON} · UNSYNCED $UNSYNCED · open questions $OPEN_Q${MANUAL:+ · $MANUAL}"
+  echo "STATE   scripts $N_SCRIPTS written / $N_PASS gate-pass / $N_DONE done- · modules opened $MOD_OPENED${SKELETON:+ · skeleton $SKELETON} · UNSYNCED $UNSYNCED · open questions $OPEN_Q${MANUAL:+ · $MANUAL}${APPMAP:+ · $APPMAP}"
   [ -n "$WATCH" ] && echo "WATCH   $WATCH"
   echo "NEXT    $NEXT"
   "$TOOLKIT_ROOT/bin/token-burn.sh" "$PROJECT_DIR" --brief 2>/dev/null
@@ -279,6 +289,7 @@ printf '%s\n\n' "$TK"
 printf 'DONE      scripts: %s written, %s gate-pass, %s done-  ·  modules opened: %s%s\n' "$N_SCRIPTS" "$N_PASS" "$N_DONE" "$MOD_OPENED" "${SKELETON:+  ·  skeleton proven $SKELETON}"
 printf 'OVERDUE   %s  ·  %s  ·  %s  ·  UNSYNCED markers: %s  ·  open questions: %s\n' "$DOCTOR" "$LINT" "${COH:-coherence: cadence script not installed}" "$UNSYNCED" "$OPEN_Q"
 [ -n "$MANUAL" ] && printf '          %s (docs/manual-steps.md)\n' "$MANUAL"
+[ -n "$APPMAP" ] && printf '          %s (refresh: bin/app-facts.sh)\n' "$APPMAP"
 [ -n "$OB_PENDING" ] && printf '          obligations pending: %s\n' "$OB_PENDING"
 [ -n "$LAST_FAIL" ] && printf '          last gate FAILED: %s\n' "$LAST_FAIL"
 [ -n "$WATCH" ] && printf 'WATCH     %s\n' "$WATCH"