From c660ea739259e1659001b10694a3f6c49cbbbf14 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 10:13:44 +0000
Subject: [PATCH 01/19] perf(ui-loop): skip the redundant baseline mxbuild,
 wait on page state, legible screenshots

- exec.sh skips the pre-flight baseline mxbuild when the model is unchanged
  since its last clean pass (stamp gains errors:, check --clean).
- New tests/e2e/settle.js replaces fixed sleeps in journey-runner and
  page-audit; SETTLE_MODE=fixed restores the old waits for an A/B run.
- page-audit saves a viewport shot beside the full-page one; ui-loop.md
  says to look at viewport shots.
- shrink-image-read.sh works off macOS (ImageMagick/Pillow, no-jq path).

Field run 2026-10-07, requirements-driven build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                            |  1 +
 bin/lib/install-manifest.sh             |  2 +-
 claude-hooks/hooks/shrink-image-read.sh | 76 +++++++++++++++------
 project-bin/exec.sh                     | 23 +++++--
 project-bin/model-stamp.sh              | 14 +++-
 project-bin/verify-model.sh             |  2 +-
 project-tests/e2e/journey-runner.js     |  9 ++-
 project-tests/e2e/page-audit.js         | 13 +++-
 project-tests/e2e/settle.js             | 90 +++++++++++++++++++++++++
 skills/journey-examples.md              |  4 +-
 skills/ui-loop.md                       |  5 +-
 11 files changed, 204 insertions(+), 35 deletions(-)
 create mode 100644 project-tests/e2e/settle.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a79d3c9..f99f456b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - feat(permissions): **intake now picks how much Claude Code may run without a prompt, and `doctor.sh` shows it.** Until now the allow-list covered only the safe wrappers (`bin/exec.sh`, `bin/*.sh`, `./mxcli`, `mx`), so every edit, test run, `npm install` or `git commit` in a project still prompted. New `bin/permission-profile.sh` resolves a profile (env, `.mxtk/permission-profile`, PROJECT.md `Permission profile:`, default `project`; a typo falls back to `wrappers`): `wrappers` is the old list; `project` adds edits anywhere inside the project folder (`Edit(/**)`) and the everyday test/npm/docker/git-add/commit commands, with force-push, `git reset --hard`, `git clean` and `sudo` behind `ask` rules that prompt in every mode; `full` adds bare `Bash`/`Edit`/`Read`/`WebFetch`/`WebSearch` to the per-machine `settings.local.json` only, never the shared file. `install-claude-permissions.sh` / `install-harness-permissions.sh` take `--profile`, and switching to a smaller profile removes only what the script itself added. Intake gains Q12, `init-project.sh` writes `Permission profile: project`, and `doctor.sh <project>` reports the profile, whether the settings files carry it, and warns on a `defaultMode` of auto/bypass in a project file, which Claude Code ignores there. No profile can switch on bypass or auto mode from the project: doctor says how to do that from the user's own settings. `test-install-claude-permissions.sh` gains T5b. — MendixMau
 - fix(small): **five small field defects (#146, #149, #152, #153, #156) and the missing v0.24 ledger entries (#168).** `gate-check.sh --closeout <dir> <stage>` now writes `index.html` when that stage PASSes or is WAIVED, so the board moves at every gate the runbook closes; plain stage queries stay read-only (#146). `journey-runner.js` refuses a journey whose `persona` differs from the signed-in user — INVALID, not walked, naming the `TEST_USER` to use — where before a non-admin journey walked green under admin; `journey-proof.md` says one file, one run per role, and `test-journey-persona.sh` is new (#149). `design-audit.js` rung 7 exempts the three `spacing-outer-bottom*` classes `design-spacing.md` prescribes (still FAIL when the widget also sets the Spacing property), and the skill names the list (#152). `verify-module.sh` runs `REFRESH CATALOG FULL` before the model-side instruments when the catalog is older than the `.mpr`, so `test --attach` then verify no longer reads INCOMPLETE (probed on a scratch model: stale, refreshed, fresh, then a no-op) (#153). `wiring-sweep.md` adds N/A (by design) for a control its own state disables and UNREACHED for a conditional widget the sweep never saw, and enumerates `Visible:`/`Editable:` widgets from `describe page` so the denominator is not the DOM's alone (#156). `mxcli-bugs.md` gains four BUG-DRAFT entries from a field comparison build (2026-09-29): false page-setting warnings, the unwritable pluggable `file` property, `index on createdDate`, and the `describe` replay CE1613; the inbox note is promoted and removed. Upstream asks in #168 stay open. — MendixMau
 - fix(gates): **a red gate under an approval, a `done-` deadlock and unfilled agent slots are now visible.** A field project had Stage 4 CONFIRMED in `PROJECT.md` while its gate FAILED, 47 scripts at gate-pass with none renamed `done-`, and 35 unfilled `{{...}}` slots in its agent stubs, and no instrument said so (a requirements-driven field build, 2026-10-06; #207, #210, #211). `gate-check.sh` now prefixes a FAIL on a CONFIRMED stage with `APPROVED OVER A FAILING GATE` and adds a summary line under Needs attention (verdict and exit code unchanged). `status.sh` gains a `WATCH` line for all three plus a stale `build-plan.html`, and its NEXT names the first one; its not-yet-`done-` list now skips BUILD-LOG rows for scripts no longer on disk. New `bin/lib/placeholders.sh` counts slots (excluding the `{{DOUBLE_BRACE}}` prose); `init-project.sh` and `sync-project.sh` list them per file. Slots stay unfilled until each agent's stage starts, as `agent-roles.md` says: these are reports, not failures. — MendixMau
diff --git a/bin/lib/install-manifest.sh b/bin/lib/install-manifest.sh
index e385ea68..4bb29c67 100644
--- a/bin/lib/install-manifest.sh
+++ b/bin/lib/install-manifest.sh
@@ -176,7 +176,7 @@ MXTK_LINT_RULES_NOINSTALL="README.md STOCK-HASHES.txt"
 #
 # project.config.template.js is listed separately because it is the one file a project is
 # EXPECTED to edit — installing it over an edited copy would silently revert the port.
-MXTK_PROJECT_TESTS="config.js helpers.js otel.js journey-runner.js journey-runner.selftest.js journey-rung4-scope.test.js monkey.js monkey.selftest.js page-audit.js page-audit-rules.js design-audit.js full-app-walkthrough.js report-normalize.js report-render.js review-report.js example.journey.json"
+MXTK_PROJECT_TESTS="config.js helpers.js settle.js otel.js journey-runner.js journey-runner.selftest.js journey-rung4-scope.test.js monkey.js monkey.selftest.js page-audit.js page-audit-rules.js design-audit.js full-app-walkthrough.js report-normalize.js report-render.js review-report.js example.journey.json"
 MXTK_PROJECT_TESTS_TEMPLATE="project.config.template.js"
 
 # Deliberately not installed. Same contract as the lists above.
diff --git a/claude-hooks/hooks/shrink-image-read.sh b/claude-hooks/hooks/shrink-image-read.sh
index 939cf777..6a1fc391 100755
--- a/claude-hooks/hooks/shrink-image-read.sh
+++ b/claude-hooks/hooks/shrink-image-read.sh
@@ -8,6 +8,11 @@
 # This rewrites the Read's file_path to point at a downscaled copy. Fail-open:
 # any error passes the original Read through untouched.
 #
+# Resizer, first one found: sips (macOS), ImageMagick (magick / convert), python3 with
+# Pillow. JSON via jq, else python3. WHY (field run 2026-10-07): this hook needed sips,
+# jq and md5, all macOS-only or often absent, so on Linux and Git Bash it was a silent
+# no-op — while screenshot reads were 11.5% of one run's re-read tokens.
+#
 # Tunables: CLAUDE_IMG_MAX_BYTES (default 150000), CLAUDE_IMG_MAX_DIM (default 1024)
 # Bypass entirely: CLAUDE_IMG_SHRINK=0
 
@@ -19,15 +24,32 @@ MAX_BYTES=${CLAUDE_IMG_MAX_BYTES:-150000}
 MAX_DIM=${CLAUDE_IMG_MAX_DIM:-1024}
 CACHE="${TMPDIR:-/tmp}/claude-shrunk"
 
-command -v jq   >/dev/null 2>&1 || exit 0
-command -v sips >/dev/null 2>&1 || exit 0
+PY=""
+for c in python3 python py; do  # portability-ok: installed to ~/.claude/hooks, cannot source portable.sh; same probe list
+  command -v "$c" >/dev/null 2>&1 && "$c" -c 'import sys; sys.exit(sys.version_info[0] < 3)' 2>/dev/null \
+    && { PY="$c"; break; }
+done
+HAVE_JQ=0; command -v jq >/dev/null 2>&1 && HAVE_JQ=1
+[ "$HAVE_JQ" = 1 ] || [ -n "$PY" ] || exit 0
+
+RESIZER=""
+if command -v sips >/dev/null 2>&1; then RESIZER=sips
+elif command -v magick >/dev/null 2>&1; then RESIZER=magick
+elif command -v convert >/dev/null 2>&1 && convert -version 2>/dev/null | grep -q ImageMagick; then RESIZER=convert
+elif [ -n "$PY" ] && "$PY" -c 'import PIL' 2>/dev/null; then RESIZER=pil
+fi
+[ -n "$RESIZER" ] || exit 0
 
 input=$(cat)
-path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+if [ "$HAVE_JQ" = 1 ]; then
+  path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+else
+  path=$(printf '%s' "$input" | "$PY" -c 'import json,sys; print((json.load(sys.stdin).get("tool_input") or {}).get("file_path") or "")' 2>/dev/null)
+fi
 [ -n "$path" ] || exit 0
 [ -f "$path" ] || exit 0
 
-# Image extensions sips can resample.
+# Image extensions the resizers can read.
 ext=$(printf '%s' "${path##*.}" | tr '[:upper:]' '[:lower:]')
 case "$ext" in
   png|jpg|jpeg|tif|tiff|bmp|gif|heic|webp) ;;
@@ -42,16 +64,24 @@ bytes=$(stat -f%z "$path" 2>/dev/null || stat -c%s "$path" 2>/dev/null \
 [ "$bytes" -gt "$MAX_BYTES" ] 2>/dev/null || exit 0
 
 mtime=$(stat -f%m "$path" 2>/dev/null || stat -c%Y "$path" 2>/dev/null)
-key=$(printf '%s:%s:%s:%s' "$path" "$mtime" "$bytes" "$MAX_DIM" | md5 -q 2>/dev/null)
+key=$(printf '%s:%s:%s:%s' "$path" "$mtime" "$bytes" "$MAX_DIM" \
+      | { md5 -q 2>/dev/null || md5sum 2>/dev/null || cksum; } | awk '{print $1}')
 [ -n "$key" ] || exit 0
 
 mkdir -p "$CACHE" 2>/dev/null || exit 0
 out="$CACHE/$key.png"
 
 if [ ! -f "$out" ]; then
-  sips --setProperty format png \
-       --resampleHeightWidthMax "$MAX_DIM" \
-       "$path" --out "$out" >/dev/null 2>&1 || exit 0
+  case "$RESIZER" in
+    sips) sips --setProperty format png --resampleHeightWidthMax "$MAX_DIM" \
+               "$path" --out "$out" >/dev/null 2>&1 ;;
+    magick|convert) "$RESIZER" "$path[0]" -resize "${MAX_DIM}x${MAX_DIM}>" "png:$out" >/dev/null 2>&1 ;;
+    pil) "$PY" -c 'import sys
+from PIL import Image
+im = Image.open(sys.argv[1]); im.thumbnail((int(sys.argv[3]),) * 2)
+(im if im.mode in ("RGB", "RGBA", "L", "LA", "P") else im.convert("RGBA")).save(sys.argv[2], "PNG", optimize=True)' \
+           "$path" "$out" "$MAX_DIM" >/dev/null 2>&1 ;;
+  esac || { rm -f "$out"; exit 0; }
 fi
 [ -s "$out" ] || exit 0
 
@@ -64,15 +94,23 @@ newbytes=$(stat -f%z "$out" 2>/dev/null || stat -c%s "$out" 2>/dev/null \
 # original beside it: project-bin/look-ledger.sh reads this to record which screenshot was seen.
 printf '%s\n' "$path" > "$CACHE/$key.src" 2>/dev/null || true
 
-printf '%s' "$input" | jq -c \
-  --arg p "$out" \
-  --arg orig "$path" \
-  --arg dim "$MAX_DIM" \
-  '{
-     hookSpecificOutput: {
-       hookEventName: "PreToolUse",
-       updatedInput: (.tool_input + {file_path: $p}),
-       additionalContext: ("Downscaled copy of \($orig) (max \($dim)px). Refer to the original path in your output.")
-     }
-   }'
+if [ "$HAVE_JQ" = 1 ]; then
+  printf '%s' "$input" | jq -c \
+    --arg p "$out" \
+    --arg orig "$path" \
+    --arg dim "$MAX_DIM" \
+    '{
+       hookSpecificOutput: {
+         hookEventName: "PreToolUse",
+         updatedInput: (.tool_input + {file_path: $p}),
+         additionalContext: ("Downscaled copy of \($orig) (max \($dim)px). Refer to the original path in your output.")
+       }
+     }'
+else
+  printf '%s' "$input" | "$PY" -c 'import json,sys
+d = json.load(sys.stdin); ti = dict(d.get("tool_input") or {}); ti["file_path"] = sys.argv[1]
+print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "updatedInput": ti,
+  "additionalContext": "Downscaled copy of %s (max %spx). Refer to the original path in your output." % (sys.argv[2], sys.argv[3])}}))' \
+    "$out" "$path" "$MAX_DIM" || exit 0
+fi
 exit 0
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index 761cef31..5e84a87f 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -91,6 +91,7 @@ BUILD_LOG="$PROJECT_ROOT/docs/BUILD-LOG.md"
 # Declared HERE, above log_build, not next to the gate: a row must be able to
 # carry a gate verdict even when the gate block below is never reached.
 GATE_STATE="not-run"   # not-run | skipped | unverified | pass | fail
+GATE_ERRORS="?"        # mxbuild error count behind a pass (0 = clean); recorded in the stamp
 MXB_WHY=""             # mxbuild's errors[] reason when it exited without checking the model
 
 # ── Exec approval (auto records itself) ──────────────────────────────────────
@@ -682,8 +683,22 @@ fi
 # Capture the CURRENT error set before touching anything, so the gate can tell
 # "this script broke it" from "it was already broken". Costs one extra mxbuild;
 # skip with SKIP_BASELINE=1 when you know the tree is clean.
+#
+# The extra mxbuild is also skipped when the verification stamp (bin/model-stamp.sh)
+# says THIS exact model state already passed mxbuild with 0 errors: the baseline is
+# then known to be empty without measuring it. Any change since (Studio Pro, a test
+# run, a bare exec) changes the fingerprint and the baseline runs as before.
+# WHY (field run 2026-10-07, requirements-driven build): exec.sh was 22% of all tool
+# time, with two mxbuilds per exec; the baseline one re-measured a model the previous
+# exec had just verified, in most of 100 execs.
 BASELINE_SET=""
 BASE_KNOWN=0
+if [ "${SKIP_BASELINE:-0}" != "1" ] && [ -x ./bin/model-stamp.sh ] \
+   && ./bin/model-stamp.sh check -q --clean >/dev/null 2>&1; then
+  echo "→ Pre-flight: model unchanged since its last clean mxbuild (verification stamp) — baseline 0, not re-measured"
+  _BC=0; _BCODES=""; BASE_KNOWN=1
+  SKIP_BASELINE=1
+fi
 if [ "${SKIP_BASELINE:-0}" != "1" ] && [ -x "$MXBUILD" ] && [ -x "$JAVA_EXE" ]; then
   echo "→ Pre-flight: checking whether the model already has errors..."
   _BF=$(mktemp /tmp/mxbuild-baseline.XXXXXX)
@@ -823,7 +838,7 @@ if [ -x "$MXBUILD" ] && [ -x "$JAVA_EXE" ]; then
       # A guard that tested only "file is non-empty" therefore took the restore
       # branch on a clean build and rolled back good work, while printing
       # "0 error(s) found". Test the parsed count, never the file's existence.
-      GATE_STATE="pass"
+      GATE_STATE="pass"; GATE_ERRORS=0
       echo "  ✓ mxbuild: 0 errors — model is clean."
       [ "$EXEC_STATUS" -eq 0 ] && log_applied "mxbuild clean"
     else
@@ -848,7 +863,7 @@ if [ -x "$MXBUILD" ] && [ -x "$JAVA_EXE" ]; then
         DELTA_KIND="subset"
       fi
       if [ -n "$DELTA_KIND" ]; then
-        GATE_STATE="pass"
+        GATE_STATE="pass"; GATE_ERRORS="$CE_COUNT"
         KEEP_CODES=$(err_codes "$ERRORS_FILE")
         if [ "$DELTA_KIND" = "subset" ]; then
           echo "  ⚠  mxbuild: $CE_COUNT error(s) — a STRICT SUBSET of the $_BC pre-flight baseline error(s), no new ones."
@@ -959,7 +974,7 @@ EOF
     # --patch logs its own row below, after rolling back; one row per run.
     [ "$PATCH_MODE" = "1" ] || log_build "❌ gate could not run" "mxbuild exit $MXBUILD_EXIT"
   else
-    GATE_STATE="pass"
+    GATE_STATE="pass"; GATE_ERRORS=0
     echo "  ✓ mxbuild: 0 errors — model is clean."
     # No errors file, or an empty one. The comment at the CE_COUNT=0 branch says
     # mxbuild ALWAYS writes one; on Mendix 11.13 it does not, so THIS is where
@@ -1071,7 +1086,7 @@ fi
 # is no longer the one anything verified.
 if [ -x ./bin/model-stamp.sh ]; then
   if [ "$GATE_STATE" = "pass" ] && [ "$EXEC_STATUS" -eq 0 ]; then
-    ./bin/model-stamp.sh write pass "exec.sh $([ "$PATCH_MODE" = 1 ] && echo '--patch ')$(basename "$SCRIPT")" || true
+    MXTK_STAMP_ERRORS="$GATE_ERRORS" ./bin/model-stamp.sh write pass "exec.sh $([ "$PATCH_MODE" = 1 ] && echo '--patch ')$(basename "$SCRIPT")" || true
   else
     ./bin/model-stamp.sh clear >/dev/null 2>&1 || true
   fi
diff --git a/project-bin/model-stamp.sh b/project-bin/model-stamp.sh
index e0027882..aaf6d693 100755
--- a/project-bin/model-stamp.sh
+++ b/project-bin/model-stamp.sh
@@ -3,7 +3,8 @@
 #
 #   ./bin/model-stamp.sh fingerprint [--staged]   # print the model fingerprint
 #   ./bin/model-stamp.sh write <state> <source…>  # record that the current model was verified
-#   ./bin/model-stamp.sh check [--staged] [-q]    # exit 0 iff the (staged) model matches a PASS stamp
+#   ./bin/model-stamp.sh check [--staged] [-q] [--clean]  # exit 0 iff the (staged) model matches a PASS stamp
+#                                                          (--clean: and that pass saw 0 mxbuild errors)
 #   ./bin/model-stamp.sh clear                    # forget the stamp (the model changed unverified)
 #   ./bin/model-stamp.sh paths                    # the repo-relative model paths this covers
 #
@@ -219,6 +220,10 @@ case "$cmd" in
     { printf 'fingerprint: %s\n' "$fp"
       printf 'state: %s\n' "$state"
       printf 'source: %s\n' "$*"
+      # mxbuild error count the pass saw. exec.sh's delta gate also passes a model that
+      # still carries pre-existing errors, so "pass" alone does not mean clean; exec.sh
+      # skips its pre-flight mxbuild only on a stamp that says 0 here (check --clean).
+      printf 'errors: %s\n' "${MXTK_STAMP_ERRORS:-?}"
       printf 'at: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
     } > "$STAMP"
     # Machine-local, like the doctor receipt: never let it travel with the repo.
@@ -230,8 +235,8 @@ case "$cmd" in
     ;;
   clear) rm -f "$STAMP"; echo "  verification stamp cleared" ;;
   check)
-    staged=0; quiet=0
-    for a in "$@"; do case "$a" in --staged) staged=1 ;; -q|--quiet) quiet=1 ;; esac; done
+    staged=0; quiet=0; clean=0
+    for a in "$@"; do case "$a" in --staged) staged=1 ;; -q|--quiet) quiet=1 ;; --clean) clean=1 ;; esac; done
     say() { [ "$quiet" = 1 ] || echo "$@"; }
     if [ "$staged" = 1 ]; then
       in_git || exit 0
@@ -263,6 +268,9 @@ case "$cmd" in
     if [ "$st" != "pass" ]; then
       say "  ✗ $what is UNVERIFIED: last verification was '$st' ($src, $at)"; exit 1
     fi
+    if [ "$clean" = 1 ] && [ "$(stamp_field errors)" != "0" ]; then
+      say "  ✗ $what passed with pre-existing errors ($(stamp_field errors)) — not a clean stamp"; exit 1
+    fi
     say "  ✓ $what verified ($src, $at)"
     ;;
   ""|-h|--help) sed -n '2,7p' "$0"; exit 0 ;;
diff --git a/project-bin/verify-model.sh b/project-bin/verify-model.sh
index 865d6e96..816df6f6 100755
--- a/project-bin/verify-model.sh
+++ b/project-bin/verify-model.sh
@@ -84,5 +84,5 @@ for x in [p for p in d.get('problems',[]) if p.get('severity')=='Error'][:15]:
 fi
 echo "✓ mxbuild: 0 errors — model is clean."
 rm -f "$ERR" "$OUT"
-[ "$STAMP" = 1 ] && ./bin/model-stamp.sh write pass "verify-model.sh"
+[ "$STAMP" = 1 ] && MXTK_STAMP_ERRORS=0 ./bin/model-stamp.sh write pass "verify-model.sh"
 exit 0
diff --git a/project-tests/e2e/journey-runner.js b/project-tests/e2e/journey-runner.js
index 0fffb151..14831616 100644
--- a/project-tests/e2e/journey-runner.js
+++ b/project-tests/e2e/journey-runner.js
@@ -33,6 +33,7 @@
 const fs = require('fs');
 const path = require('path');
 const H = require(__dirname + '/helpers.js');
+const { settle } = require(__dirname + '/settle.js');
 const O = require(__dirname + '/otel.js');
 const { cfg } = require(__dirname + '/config.js');
 
@@ -288,7 +289,11 @@ async function act(page, a, vars, note) {
     case 'wait':         await page.waitForTimeout(a.ms || 1000); break;
     default: throw new Error(`unknown action "${a.do}"`);
   }
-  await page.waitForTimeout(a.settleMs ?? 1200);
+  // An explicit settleMs is a fixed wait, as before. Otherwise wait for the page to
+  // finish (settle.js) rather than 1200 ms after every action; SETTLE_MODE=fixed
+  // restores the old 1200 ms for an A/B run.
+  if (a.settleMs != null) await page.waitForTimeout(a.settleMs);
+  else await settle(page, { timeout: 10000, stableMs: 300, networkIdleMs: 0, fallbackMs: 1200 });
 }
 
 // ── Rung 3 helpers ──────────────────────────────────────────────────────────
@@ -575,7 +580,7 @@ function controlMutants(j) {
 // carry-over inside a walk. Here, carry-over between walks is precisely the bug.
 async function resetToStart(page) {
   await page.goto(cfg.baseUrl, { waitUntil: 'domcontentloaded' });
-  await page.waitForTimeout(2500);
+  await settle(page, { fallbackMs: 2500 });
 }
 
 async function runJourney(page, j) {
diff --git a/project-tests/e2e/page-audit.js b/project-tests/e2e/page-audit.js
index d241f655..b8d664f7 100644
--- a/project-tests/e2e/page-audit.js
+++ b/project-tests/e2e/page-audit.js
@@ -11,6 +11,7 @@
 //         tests/e2e/artifacts/page-audit-control.json  (--positive-control; own file —
 //         a control run must never overwrite a real run)
 //         tests/e2e/artifacts/page-audit-<Module.Page>.png  (one screenshot per page)
+//         tests/e2e/artifacts/page-audit-<Module.Page>.top.png  (first screen — read this one)
 //
 // WHAT THIS IS FOR, AND HOW IT DIFFERS FROM design-audit.js
 // `design-audit.js` sweeps the corpus for class correctness, accessibility and
@@ -53,6 +54,7 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 
 const R = require('./page-audit-rules.js');
+const { settle } = require('./settle.js');
 
 // project.config.js is the only project-aware file in tests/e2e/. It is safe to
 // require here where ./config is not: it has NO side effects at require time
@@ -547,8 +549,9 @@ async function liveSweep(pages, perPage) {
           }
           const item = page.locator(`text="${target.item}"`).first();
           await item.click({ timeout: 10000 });
-          await page.waitForLoadState('networkidle', { timeout: 20000 }).catch(() => {});
-          await page.waitForTimeout(600);
+          // Page state, not 'networkidle' (a polling client only ends that by timing out,
+          // up to 20 s per page) plus a fixed 600 ms. settle.js; SETTLE_MODE=fixed = old waits.
+          await settle(page, { timeout: 20000, fallbackMs: 600 });
           navigated = true;
         } catch (e) {
           why = `clicking nav item "${target.item}" failed: ${String(e.message).slice(0, 160)}`;
@@ -570,8 +573,14 @@ async function liveSweep(pages, perPage) {
       }
 
       await page.screenshot({ path: shot, fullPage: true }).catch(() => {});
+      // Plus the first screen (1440x900) — the shot an agent should LOOK at. A tall
+      // full-page shot is downscaled to ~1024 px high before a model sees it, which
+      // leaves text unreadable; the viewport shot stays legible at ~1.7k tokens.
+      const top = shot.replace(/\.png$/, '.top.png');
+      await page.screenshot({ path: top, fullPage: false }).catch(() => {});
       const captured = fs.existsSync(shot);
       if (pp && captured) pp.screenshot = path.relative(ROOT, shot);
+      if (pp && fs.existsSync(top)) pp.screenshotTop = path.relative(ROOT, top);
       rows.push(row({ id: `${INSTRUMENT}/live/screenshot/${qn}`, module: mod, page: qn,
         category: 'live', severity: 'P2', title: 'page screenshot captured',
         verdict: captured ? 'pass' : 'fault',
diff --git a/project-tests/e2e/settle.js b/project-tests/e2e/settle.js
new file mode 100644
index 00000000..2f77889a
--- /dev/null
+++ b/project-tests/e2e/settle.js
@@ -0,0 +1,90 @@
+'use strict';
+// ============================================================================
+// settle.js — wait until a Mendix page has finished, instead of sleeping a fixed time.
+// ----------------------------------------------------------------------------
+// A page counts as SETTLED when, for `stableMs` in a row:
+//   - no visible loading indicator (Mendix progress bar, data view / list view / grid
+//     loading state, spinner, aria-busy) — see BUSY;
+//   - the DOM size (document.body.innerHTML length) did not change;
+// after at most one bounded try at Playwright's 'networkidle' (a Mendix client that
+// polls never idles, so that try is capped and never fatal).
+//
+// settle(page) never throws. It returns { ok, ms, reason, stuck }: ok false means the
+// page was still loading when the time ran out. STUCK: the time ran out with a loading
+// indicator still shown but the DOM unchanged for `stuckMs` (a Data grid 2 with 0 rows
+// can keep its progress bar) — the caller decides what that means.
+//
+// WHY (field run 2026-10-07, requirements-driven build). journey-runner slept 1200 ms
+// after every action and page-audit waited for 'networkidle' up to 20 s per page, which
+// a polling client only ends by timing out. Waiting on the page's own state is faster
+// on a quick page and still correct on a slow one, where a fixed sleep screenshots or
+// asserts on a half-loaded screen. Ported from a field-proven upgrade-test runner,
+// where the fixed 1.5 s sleep had captured a progress bar instead of the page.
+//
+// SETTLE_MODE=fixed restores the old fixed waits (callers pass `fallbackMs`) — keep it
+// for an A/B run: the same journeys must reach the same verdicts either way.
+// ============================================================================
+
+const BUSY = [
+  '.mx-progress', '.mx-progress-indicator', '.mx-progress-line',
+  '.mx-dataview-loading', '.mx-listview-loading', '.mx-templategrid-loading', '.mx-datagrid-loading',
+  '.widget-datagrid-loading', '.widget-gallery-loading', '.mx-loading',
+  '.spinner', '.spinner-border', '.loading-spinner', '[aria-busy="true"]',
+];
+
+// Runs in the browser (page.evaluate). Self-contained: no closure over node values.
+function pageSettled(busySel) {
+  try {
+    const sel = busySel.join(', ');
+    const shown = (e) => {
+      try {
+        if (e.getClientRects && !e.getClientRects().length) return false;
+        const s = getComputedStyle(e);
+        return s.display !== 'none' && s.visibility !== 'hidden' && s.opacity !== '0';
+      } catch (x) { return false; }
+    };
+    const busy = [...document.querySelectorAll(sel)].filter(shown)
+      .map((e) => (e.className && String(e.className).split(/\s+/)[0]) || e.tagName || '?');
+    return { busy, size: document.body ? document.body.innerHTML.length : 0 };
+  } catch (e) {
+    return { busy: ['error: ' + String(e && e.message || e).slice(0, 80)], size: -1 };
+  }
+}
+
+async function settle(page, opts = {}) {
+  if (process.env.SETTLE_MODE === 'fixed' && opts.fallbackMs != null) {
+    await page.waitForTimeout(opts.fallbackMs).catch(() => {});
+    return { ok: true, ms: opts.fallbackMs, reason: 'SETTLE_MODE=fixed' };
+  }
+  const timeout = opts.timeout ?? Number(process.env.SETTLE_MS || 15000);
+  const stableMs = opts.stableMs ?? 500;
+  const minMs = opts.minMs ?? 300;      // let an action's own request start before judging
+  const stuckMs = opts.stuckMs ?? 5000;
+  const idleMs = opts.networkIdleMs ?? 1500;
+  const poll = 150;
+  const t0 = Date.now();
+  let last = null, stableSince = 0, sizeSince = 0, lastBusy = [];
+  if (idleMs > 0) await page.waitForLoadState('networkidle', { timeout: Math.min(idleMs, timeout) }).catch(() => {});
+  while (Date.now() - t0 < timeout) {
+    const s = await page.evaluate(pageSettled, BUSY)
+      .catch((e) => ({ busy: ['evaluate: ' + String(e.message).split('\n')[0]], size: -1 }));
+    lastBusy = s.busy;
+    if (s.size !== last || s.size < 0) sizeSince = Date.now();
+    if (!s.busy.length && s.size === last) {
+      if (!stableSince) stableSince = Date.now();
+      if (Date.now() - stableSince >= stableMs && Date.now() - t0 >= minMs) return { ok: true, ms: Date.now() - t0 };
+    } else {
+      stableSince = 0;
+    }
+    last = s.size;
+    await page.waitForTimeout(poll).catch(() => {});
+  }
+  const ms = Date.now() - t0, still = Date.now() - sizeSince;
+  const busy = [...new Set(lastBusy)].slice(0, 4).join(', ');
+  const real = lastBusy.length && !lastBusy.some((b) => /^(error|evaluate):/.test(b));
+  if (real && sizeSince && still >= stuckMs)
+    return { ok: false, stuck: true, ms, reason: `stuck: ${busy} shown, DOM unchanged for ${still}ms` };
+  return { ok: false, ms, reason: lastBusy.length ? 'still loading: ' + busy : 'DOM still changing' };
+}
+
+module.exports = { BUSY, pageSettled, settle };
diff --git a/skills/journey-examples.md b/skills/journey-examples.md
index 0ebf02ca..72061965 100644
--- a/skills/journey-examples.md
+++ b/skills/journey-examples.md
@@ -123,7 +123,7 @@ row means "the walk did not get there", never "not applicable".
 | `wait` | `ms` | **`ms`, not `settleMs`.** |
 | anything else | — | throws `unknown action` → step `FAIL`. |
 
-Every action also reads `settleMs` (default 1200, applied *after* the action) and `label`
+Every action also reads `settleMs` (a fixed wait *after* the action; when absent the runner waits until the page is idle — no progress bar, DOM still — via `tests/e2e/settle.js`, and `SETTLE_MODE=fixed` restores the old 1200) and `label`
 (**display only** — the walk narrates `Click "Submit for approval"` while keeping `.mx-name-btnSubmit`
 for whoever has to fix it). `widget` is a bare Mendix widget name; the runner prepends `.mx-name-`.
 
@@ -254,7 +254,7 @@ Each of these is either an error path in the runner or a correction recorded in
 | `oql` / `outcome` with no `expect` or `atLeast` | `INVALID` on every run, forever | declare a bar; prefer `atLeast` on a fixture with history |
 | Two independent `LIMIT 1` seeds | the journey selects one row and asserts about another | key the second seed off the first |
 | Unaliased seed SQL | seed resolves to `null` → whole journey `INVALID` | `SELECT Name AS n …` |
-| `wait` with `settleMs` | the wait is 1200ms, not what you wrote | `wait` reads `ms` |
+| `wait` with `settleMs` | the wait is `settleMs` after a 1000ms `wait`, not what you wrote | `wait` reads `ms` |
 | A `_note` object inside `textPresent` / `ordered` / `checks` | the comment becomes an assertion | comment on the parent object, never inside an iterated array |
 | Treating "seeds returned nothing" as a feature failure | someone debugs the app for a fixture gap | `INVALID`; see `fixture-seeding.md`'s four-cause table |
 | `persona` drifting from `TEST_USER` | the report names an identity that never walked | keep them in step; check `usedFallback` in the findings file |
diff --git a/skills/ui-loop.md b/skills/ui-loop.md
index 2151a828..2dd7d075 100644
--- a/skills/ui-loop.md
+++ b/skills/ui-loop.md
@@ -47,7 +47,10 @@ The gate was not missing. Its cadence was too coarse to catch anything early.
 After a script that creates or changes a page:
 
 1. **Run it and open the page** — through real navigation, as a real user role, not a direct URL.
-2. **Screenshot it, then open the PNG** (the Read tool). Name the file after the page —
+2. **Screenshot it, then open the PNG** (the Read tool). Take the viewport (`fullPage: false`,
+   e.g. 1440×900), not the whole page: a tall full-page shot reaches you shrunk to ~1024 px high
+   with unreadable text. Below the fold, scroll and take a second viewport shot.
+   Name the file after the page —
    `order-overview.png` or `Order_Overview_1280.png` for `Orders.Order_Overview`. `bin/exec.sh`
    recorded the page as owed a look when the script landed; opening a screenshot whose name
    contains the page name, taken after that build, is what clears it. Until every built page is

From 85afba1aa880d683b78206faf290523b35de6392 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 12:47:15 +0000
Subject: [PATCH 02/19] perf(ui-loop): reload a stale app, settle journeys,
 worst-first look order

- test-stack-up.sh: record the model the app was built from; on change,
  `mxcli docker reload` (+ --skip-check when exec.sh already passed it),
  restart only on failure. Header carries the measured loop table.
- journey-runner.js: combobox steps wait on page state; the toggle is
  scoped to the named widget (it opened the page's first combobox).
- page-audit.js: click the first nav copy a user can click (a collapsed
  sidebar covered .first()); write page-audit-look-order.txt, all pages
  worst first.
- design-audit.js: drop the fixed 1.2 s wait.
- ui-loop.md / module-review.md: warm-loop table; order, not selection.

Field run 2026-10-07, existing app: same 7-step journey 56 s fixed vs
24 s settle, 11/11 pass both, 3 runs each; reload --skip-check 93 s vs
restart 179 s; run --local --watch ~18 s per page change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                        |   1 +
 project-bin/test-stack-up.sh        | 117 +++++++++++++++++++++++++++-
 project-tests/e2e/design-audit.js   |   4 +-
 project-tests/e2e/journey-runner.js |  22 ++++--
 project-tests/e2e/page-audit.js     |  48 +++++++++++-
 skills/module-review.md             |   7 ++
 skills/ui-loop.md                   |  14 ++++
 7 files changed, 200 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f99f456b..4d65e66e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 ## Unreleased
 
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
+- perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
 - feat(permissions): **intake now picks how much Claude Code may run without a prompt, and `doctor.sh` shows it.** Until now the allow-list covered only the safe wrappers (`bin/exec.sh`, `bin/*.sh`, `./mxcli`, `mx`), so every edit, test run, `npm install` or `git commit` in a project still prompted. New `bin/permission-profile.sh` resolves a profile (env, `.mxtk/permission-profile`, PROJECT.md `Permission profile:`, default `project`; a typo falls back to `wrappers`): `wrappers` is the old list; `project` adds edits anywhere inside the project folder (`Edit(/**)`) and the everyday test/npm/docker/git-add/commit commands, with force-push, `git reset --hard`, `git clean` and `sudo` behind `ask` rules that prompt in every mode; `full` adds bare `Bash`/`Edit`/`Read`/`WebFetch`/`WebSearch` to the per-machine `settings.local.json` only, never the shared file. `install-claude-permissions.sh` / `install-harness-permissions.sh` take `--profile`, and switching to a smaller profile removes only what the script itself added. Intake gains Q12, `init-project.sh` writes `Permission profile: project`, and `doctor.sh <project>` reports the profile, whether the settings files carry it, and warns on a `defaultMode` of auto/bypass in a project file, which Claude Code ignores there. No profile can switch on bypass or auto mode from the project: doctor says how to do that from the user's own settings. `test-install-claude-permissions.sh` gains T5b. — MendixMau
 - fix(small): **five small field defects (#146, #149, #152, #153, #156) and the missing v0.24 ledger entries (#168).** `gate-check.sh --closeout <dir> <stage>` now writes `index.html` when that stage PASSes or is WAIVED, so the board moves at every gate the runbook closes; plain stage queries stay read-only (#146). `journey-runner.js` refuses a journey whose `persona` differs from the signed-in user — INVALID, not walked, naming the `TEST_USER` to use — where before a non-admin journey walked green under admin; `journey-proof.md` says one file, one run per role, and `test-journey-persona.sh` is new (#149). `design-audit.js` rung 7 exempts the three `spacing-outer-bottom*` classes `design-spacing.md` prescribes (still FAIL when the widget also sets the Spacing property), and the skill names the list (#152). `verify-module.sh` runs `REFRESH CATALOG FULL` before the model-side instruments when the catalog is older than the `.mpr`, so `test --attach` then verify no longer reads INCOMPLETE (probed on a scratch model: stale, refreshed, fresh, then a no-op) (#153). `wiring-sweep.md` adds N/A (by design) for a control its own state disables and UNREACHED for a conditional widget the sweep never saw, and enumerates `Visible:`/`Editable:` widgets from `describe page` so the denominator is not the DOM's alone (#156). `mxcli-bugs.md` gains four BUG-DRAFT entries from a field comparison build (2026-09-29): false page-setting warnings, the unwritable pluggable `file` property, `index on createdDate`, and the `describe` replay CE1613; the inbox note is promoted and removed. Upstream asks in #168 stay open. — MendixMau
 - fix(gates): **a red gate under an approval, a `done-` deadlock and unfilled agent slots are now visible.** A field project had Stage 4 CONFIRMED in `PROJECT.md` while its gate FAILED, 47 scripts at gate-pass with none renamed `done-`, and 35 unfilled `{{...}}` slots in its agent stubs, and no instrument said so (a requirements-driven field build, 2026-10-06; #207, #210, #211). `gate-check.sh` now prefixes a FAIL on a CONFIRMED stage with `APPROVED OVER A FAILING GATE` and adds a summary line under Needs attention (verdict and exit code unchanged). `status.sh` gains a `WATCH` line for all three plus a stale `build-plan.html`, and its NEXT names the first one; its not-yet-`done-` list now skips BUILD-LOG rows for scripts no longer on disk. New `bin/lib/placeholders.sh` counts slots (excluding the `{{DOUBLE_BRACE}}` prose); `init-project.sh` and `sync-project.sh` list them per file. Slots stay unfilled until each agent's stage starts, as `agent-roles.md` says: these are reports, not failures. — MendixMau
diff --git a/project-bin/test-stack-up.sh b/project-bin/test-stack-up.sh
index 8d1a0b08..09abf59f 100755
--- a/project-bin/test-stack-up.sh
+++ b/project-bin/test-stack-up.sh
@@ -10,15 +10,43 @@
 #   1. NEVER touches Studio Pro. No force-quit, no kill. It detects SP and reports; that is all.
 #      restart-sp.sh owns crash recovery and warns that unsaved work is lost. This must be safe to
 #      run while someone else is working in SP.
-#   2. NEVER writes to the .mpr. `mxcli docker build` reads the model and writes only build output.
+#   2. Never writes model CONTENT. Measured (field run 2026-10-07, existing app): a `mxcli docker
+#      run` / `docker build` runs `mx update-widgets` first, which rewrites widget definitions in the
+#      .mpr — git showed it modified after a build that failed. That is a widget-definition refresh,
+#      not a change anyone authored, but it IS a write: commit or snapshot before a build, and never
+#      run one while Studio Pro has the model open.
 #   3. Proves liveness with an actual HTTP response. "No error" is not "up".
-#   4. Idempotent. If the app already answers, it does nothing and exits 0.
+#   4. Idempotent, but never STALE. If the app already answers and was built from the current model,
+#      it does nothing and exits 0. If the model changed since this script last built it, an app
+#      that answers is serving the OLD model — every test then measures yesterday's build and a
+#      fixed bug "still fails". So it hot-reloads (`mxcli docker reload`: build + reload_model,
+#      no container restart) and falls back to a restart only if the reload fails. See WARM LOOP.
 #   5. Starts an auxiliary service if it is down; NEVER stops one (another session may be using it).
 #
 # Usage:
 #   bin/test-stack-up.sh --check     # report only, change nothing. Exit 0 iff required deps are up.
 #   bin/test-stack-up.sh             # report, then bring up what is missing (may run a Docker build)
 #   bin/test-stack-up.sh --no-docker # bring up auxiliaries only; never build. "SP is already running it".
+#   bin/test-stack-up.sh --restart   # skip the hot reload; rebuild and restart the container (old path)
+#
+# WARM LOOP. After a model change the old loop was: exec.sh gate (mxbuild) -> `docker run` (mx check +
+# mxbuild again) -> container restart -> boot wait. Now: the app's model is recorded in
+# .claude/loop/served-model (the model-stamp fingerprint at the moment this script built it); when
+# the current fingerprint differs, `mxcli docker reload` rebuilds and swaps the model into the
+# running runtime instead of restarting it, and passes --skip-check when model-stamp says the
+# current model already passed an mxbuild (the exec.sh gate) — that check was the duplicate.
+# Entity/association changes need a DB sync that reload_model may not do; if the reload fails or the
+# app stops answering, it falls back to the restart. MXTK_WARM_RELOAD=off keeps the old idempotent
+# no-op. Measured (field run 2026-10-07, existing app, cloud container, one page change):
+#   docker run --wait, cold                         190 s
+#   restart (docker run --wait over a running app)  179 s
+#   docker reload, with the duplicate check         140 s
+#   docker reload --skip-check                       93 s  (reload_model itself 0.6 s; the build is the rest)
+#   mxcli run --local --watch, page change           ~18 s from exec to applied (security/nav change: ~60 s restart)
+# So the fastest loop is not this script: keep `mxcli run --local --watch` running beside the
+# session and let it apply each exec (skills/ui-loop.md). This script is the Docker path and the
+# proof-of-ownership step. `docker reload --css` is NOT a theme loop: it copies the theme without
+# compiling SCSS, so a main.scss edit does not show.
 #
 # Exit codes: 0 = required stack is up · 1 = not up and could not fix · 2 = usage/env error
 #
@@ -70,8 +98,9 @@ MODE="up"
 case "${1:-}" in
   --check)     MODE="check" ;;
   --no-docker) MODE="nodocker" ;;
+  --restart)   MODE="restart" ;;
   "")          ;;
-  *) echo "usage: $0 [--check|--no-docker]" >&2; exit 2 ;;
+  *) echo "usage: $0 [--check|--no-docker|--restart]" >&2; exit 2 ;;
 esac
 
 ok()   { printf '  \033[32m✓\033[0m %s\n' "$1"; }
@@ -201,6 +230,29 @@ publish_stack_env() {
   } > "$STACK_ENV"
 }
 
+# --- Served model: which model state is the running app built from? ----------
+# Written ONLY by this script, right after it built the app, so it names the model the build read
+# (after mx update-widgets, which can rewrite the .mpr — fingerprint before the build would be
+# stale the moment the build finished). An app started any other way (Studio Pro, a manual
+# `docker run`) has no record: freshness UNKNOWN, reported, never guessed.
+SERVED_FILE="${SERVED_FILE:-$ROOT/.claude/loop/served-model}"
+STAMP_SH="$(dirname "${BASH_SOURCE[0]}")/model-stamp.sh"
+model_fp() { [ -f "$STAMP_SH" ] && bash "$STAMP_SH" fingerprint 2>/dev/null; }
+record_served() {
+  local fp; fp="$(model_fp)" || fp=""
+  [ -n "$fp" ] || return 0
+  mkdir -p "$(dirname "$SERVED_FILE")" 2>/dev/null && printf '%s\n' "$fp" > "$SERVED_FILE"
+}
+# Echoes fresh | stale | unknown.
+served_state() {
+  local want have
+  have="$(head -1 "$SERVED_FILE" 2>/dev/null)"
+  want="$(model_fp)" || want=""
+  if [ -z "$have" ] || [ -z "$want" ]; then echo unknown
+  elif [ "$have" = "$want" ]; then echo fresh
+  else echo stale; fi
+}
+
 echo "── Test stack: $PROJ ──────────────────────────────────"
 
 # --- Studio Pro: report only, never act -------------------------------------
@@ -236,6 +288,15 @@ if [ $APP_FOUND -eq 0 ]; then
 else
   bad "App not serving on any of: $APP_PORTS"
 fi
+SERVED="none"
+if [ $APP_FOUND -eq 0 ]; then
+  SERVED="$(served_state)"
+  case "$SERVED" in
+    fresh)   ok "App serves the current model" ;;
+    stale)   warn "App serves an OLDER model — the model changed since it was built; tests would measure the old build" ;;
+    unknown) warn "App freshness unknown — not built by this script (Studio Pro / manual run); it may serve an old model" ;;
+  esac
+fi
 
 # --- Jaeger (needed only for Trace assertions) ------------------------------
 JAEGER_OK=1
@@ -293,6 +354,10 @@ if [ "$MODE" = "check" ]; then
     echo "APP UP, BUT REST-FED SPECS WILL BE INVALID — see the container warning above"
     exit 1
   fi
+  if [ "$SERVED" = "stale" ] && [ "$APP_OWNERSHIP" = "verified" ]; then
+    echo "APP UP BUT STALE — re-run without --check to hot-reload the current model"
+    exit 1
+  fi
   if [ $APP_FOUND -eq 0 ] && [ $MOCK_OK -eq 0 ]; then
     echo "READY (app :$APP_PORT · jaeger $([ $JAEGER_OK -eq 0 ] && echo up || echo DOWN))"
     exit 0
@@ -317,6 +382,51 @@ if [ $MOCK_REQUIRED -eq 1 ] && [ $MOCK_OK -ne 0 ]; then
   fi
 fi
 
+# --- Warm loop: refresh a running app instead of restarting it --------------
+# Only for OUR container (ownership verified): a reload swaps the model in a runtime, and doing that
+# to an unverified port could be another project's app or a Studio Pro run.
+if [ $APP_FOUND -eq 0 ] && [ "$APP_OWNERSHIP" = "verified" ] && [ -n "$MXCLI" ] \
+   && [ "${MXTK_WARM_RELOAD:-on}" != "off" ] && [ "$MODE" != "nodocker" ] \
+   && { [ "$SERVED" != "fresh" ] || [ "$MODE" = "restart" ]; }; then
+  T0=$(date +%s)
+  RELOADED=1
+  if [ "$MODE" != "restart" ]; then
+    # --skip-check only when this exact model already passed an mxbuild (exec.sh's gate or
+    # verify-model.sh). Otherwise the check is the only build-error report before the build.
+    SKIP=""
+    if [ -f "$STAMP_SH" ] && bash "$STAMP_SH" check -q >/dev/null 2>&1; then SKIP="--skip-check"; fi
+    echo "→ Model changed since the app was built — hot-reloading (build + reload_model${SKIP:+, check skipped: model already gate-verified})..."
+    "$MXCLI" docker reload -p "$MPR" $SKIP >"$DOCKER_LOG" 2>&1
+    RELOADED=$?
+    if [ $RELOADED -eq 0 ]; then
+      # reload_model returned; prove the app still answers before trusting it.
+      for _ in $(seq 1 20); do
+        APP_FIND="$(find_app_port)" && break
+        sleep 1
+      done
+      if mendix_at "${APP_FIND%%|*}"; then
+        record_served
+        ok "Hot reload done in $(( $(date +%s) - T0 ))s — app serves the current model"
+        SERVED=fresh
+      else
+        warn "reload_model returned but the app stopped answering — falling back to a restart"
+        RELOADED=1
+      fi
+    else
+      warn "docker reload failed (rc=$RELOADED) — falling back to a restart. Log: $DOCKER_LOG"
+      tail -5 "$DOCKER_LOG" | sed 's/^/    /'
+    fi
+  fi
+  if [ $RELOADED -ne 0 ]; then
+    echo "→ Rebuilding and restarting the container..."
+    "$MXCLI" docker run -p "$MPR" --wait >"$DOCKER_LOG" 2>&1
+    if [ $? -ne 0 ]; then
+      bad "mxcli docker run failed — see $DOCKER_LOG"; tail -20 "$DOCKER_LOG"; exit 1
+    fi
+    APP_FOUND=1   # re-proved below by the boot-wait loop
+  fi
+fi
+
 # --- Bring up the app -------------------------------------------------------
 if [ $APP_FOUND -ne 0 ]; then
   if [ "$MODE" = "nodocker" ]; then
@@ -374,6 +484,7 @@ if [ $APP_FOUND -ne 0 ]; then
   APP_OWNERSHIP="${APP_FIND##*|}"
 
   if [ $APP_FOUND -eq 0 ]; then
+    record_served
     ok "App serving on :$APP_PORT after ${WAITED}s (ownership $APP_OWNERSHIP)"
   else
     bad "App still not answering after ${BOOT_TIMEOUT}s — see $DOCKER_LOG"
diff --git a/project-tests/e2e/design-audit.js b/project-tests/e2e/design-audit.js
index 4c92d8e4..d66c0598 100644
--- a/project-tests/e2e/design-audit.js
+++ b/project-tests/e2e/design-audit.js
@@ -47,6 +47,7 @@ const os = require('os');
 // project.config.js is the only project-aware file in tests/e2e/, and it has no
 // side effects at require time (unlike ./config, which can process.exit(2)).
 const PROJ = require('./project.config');
+const { settle } = require(__dirname + '/settle.js');
 
 const ROOT = PROJ.root;
 const MPR = PROJ.mprName;
@@ -771,7 +772,8 @@ async function appSweep(pages, navMap, controlNotes) {
     try {
       await page.setViewportSize({ width: 1440, height: 900 });
       await helpers.navTo(page, nav.group, nav.item);
-      await page.waitForTimeout(1200);
+      // wait for the page, not 1200 ms (SETTLE_MODE=fixed keeps the 1200 ms for an A/B run)
+      await settle(page, { timeout: 10000, networkIdleMs: 0, fallbackMs: 1200 });
 
       const st = await checkStructure(page);
       const shot = path.join(ARTIFACTS, `design-audit-${qn}.png`);
diff --git a/project-tests/e2e/journey-runner.js b/project-tests/e2e/journey-runner.js
index 14831616..d0140248 100644
--- a/project-tests/e2e/journey-runner.js
+++ b/project-tests/e2e/journey-runner.js
@@ -115,6 +115,11 @@ const subst = (v, vars) =>
 // meant to stay declarative enough to generate from a module brief's golden-path
 // table.
 const PAUSE = ms => new Promise(r => setTimeout(r, ms));
+// The combobox waits below used to be fixed sleeps (400/1200/120/500 ms per field). Each now
+// waits for the thing it was sleeping for; SETTLE_MODE=fixed keeps the old sleeps for an A/B run.
+const FIXED = process.env.SETTLE_MODE === 'fixed';
+const frames = page => page.evaluate(() => new Promise(r =>
+  requestAnimationFrame(() => requestAnimationFrame(r)))).catch(() => {});
 
 // A human-readable account of what the action WILL do, in the vocabulary a reviewer
 // uses ("click Receive"), not the harness's (".mx-name-bReceive"). Both are kept: the
@@ -200,12 +205,18 @@ async function act(page, a, vars, note) {
       if (!(await box.isVisible({ timeout: 6000 }).catch(() => false)))
         throw new Error(`.mx-name-${a.widget} not visible`);
       await box.scrollIntoViewIfNeeded().catch(() => {});
-      await PAUSE(400);
-      await page.locator('[id^="downshift-"][id$="-toggle-button"]').first()
+      if (FIXED) await PAUSE(400); else await frames(page);
+      // The toggle is INSIDE the widget (only the menu renders outside it). It used to be
+      // looked up page-wide with .first(), which opened the page's FIRST combobox whatever
+      // `widget` said: on a form with three comboboxes every step read the first one's menu
+      // and failed "no option matches" (field run 2026-10-07, existing app).
+      await box.locator('[id^="downshift-"][id$="-toggle-button"]').first()
                 .click({ force: true }).catch(() => {});
-      await PAUSE(1200);
+      if (FIXED) await PAUSE(1200);
       const opts = page.locator('[role="option"]');
       await opts.first().waitFor({ state: 'visible', timeout: 5000 }).catch(() => {});
+      // options can arrive in batches (async datasource): wait until the list stops growing
+      if (!FIXED) await settle(page, { timeout: 3000, stableMs: 200, minMs: 0, networkIdleMs: 0 });
       const texts = await opts.evaluateAll(e => e.map(x => x.textContent.trim())).catch(() => []);
       const want = String(subst(a.match, vars));
       const idx = texts.findIndex(t => t.includes(want));
@@ -261,7 +272,7 @@ async function act(page, a, vars, note) {
         const cur = (await activeText() || '').trim();
         if (cur && cur.includes(want)) { landed = true; break; }
         await page.keyboard.press('ArrowDown');
-        await PAUSE(120);
+        if (FIXED) await PAUSE(120); else await frames(page);
       }
       if (!landed) {
         throw new Error(
@@ -269,7 +280,8 @@ async function act(page, a, vars, note) {
           `"${want}". The option is listed but not reachable by keyboard.`);
       }
       await page.keyboard.press('Enter');
-      await PAUSE(500);
+      if (FIXED) await PAUSE(500);
+      else await settle(page, { timeout: 3000, stableMs: 150, minMs: 0, networkIdleMs: 0 });
 
       // Selecting is not committing. Downshift can close the menu without writing the
       // value back, so the committed input is read and compared to the seed — not
diff --git a/project-tests/e2e/page-audit.js b/project-tests/e2e/page-audit.js
index b8d664f7..7fbf847c 100644
--- a/project-tests/e2e/page-audit.js
+++ b/project-tests/e2e/page-audit.js
@@ -547,8 +547,22 @@ async function liveSweep(pages, perPage) {
             const g = page.locator(`.mx-navigationtree >> text="${target.group}"`).first();
             if (await g.count()) { await g.click({ timeout: 5000 }).catch(() => {}); await page.waitForTimeout(400); }
           }
-          const item = page.locator(`text="${target.item}"`).first();
-          await item.click({ timeout: 10000 });
+          // Try every element carrying the label, not just the first. A layout can render
+          // the same item twice (sidebar tree + top menu bar); with the sidebar collapsed
+          // to its 32 px rail the content placeholder covers it, so .first() timed out on
+          // every page while the menu-bar copy was one click away (field run 2026-10-07,
+          // existing app). A trial click finds the one a user could actually click.
+          const items = page.locator(`text="${target.item}"`);
+          await items.first().waitFor({ state: 'attached', timeout: 10000 });
+          let clicked = false; let lastErr = null;
+          for (let i = 0, n = await items.count(); i < n && !clicked; i++) {
+            try {
+              await items.nth(i).click({ trial: true, timeout: 2000 });
+              await items.nth(i).click({ timeout: 5000 });
+              clicked = true;
+            } catch (err) { lastErr = err; }
+          }
+          if (!clicked) throw lastErr;
           // Page state, not 'networkidle' (a polling client only ends that by timing out,
           // up to 20 s per page) plus a fixed 600 ms. settle.js; SETTLE_MODE=fixed = old waits.
           await settle(page, { timeout: 20000, fallbackMs: 600 });
@@ -911,7 +925,25 @@ function main() {
   });
 }
 
+// Look order: every page, worst first — fault, then fail, then by its P1/P2/P3 finding counts.
+// Triage only changes which screenshot a reviewer opens FIRST; the list always holds all N pages,
+// because a page with zero findings is not a page nobody needs to look at (the rules cannot see
+// layout, and module-review.md stage 4 owes a look at every one).
+const SEV_RANK = ['P1', 'P2', 'P3'];
+function lookOrder(perPage) {
+  const key = (p) => [PRECEDENCE[p.verdict] || 0,
+    ...SEV_RANK.map((s) => p.findings.filter((f) => f.severity === s).length), p.findings.length];
+  return perPage.map((p, i) => ({ p, i, k: key(p) }))
+    .sort((a, b) => { for (let j = 0; j < a.k.length; j++) if (b.k[j] !== a.k[j]) return b.k[j] - a.k[j]; return a.i - b.i; })
+    .map(({ p }, n) => ({
+      rank: n + 1, page: p.page, verdict: p.verdict,
+      findings: SEV_RANK.map((s) => `${s}:${p.findings.filter((f) => f.severity === s).length}`).join(' '),
+      screenshotTop: p.screenshotTop || null, screenshot: p.screenshot || null,
+    }));
+}
+
 function finish({ startedAt, checks, instruments, perPage, coverage, app, controlRows }) {
+  const order = lookOrder(perPage);
   const tally = checks.reduce((a, c) => { a[c.verdict] = (a[c.verdict] || 0) + 1; return a; }, {});
   const artifact = {
     schemaVersion: SCHEMA_VERSION,
@@ -938,6 +970,7 @@ function finish({ startedAt, checks, instruments, perPage, coverage, app, contro
     },
     humanJudgement: R.HUMAN_JUDGEMENT,
     instruments,
+    lookOrder: order,
     perPage,
     checks,
     controls: controlRows,
@@ -948,6 +981,11 @@ function finish({ startedAt, checks, instruments, perPage, coverage, app, contro
   const out = OPT.out
     || path.join(ARTIFACTS, OPT.page ? `page-audit-${OPT.page}.json` : 'page-audit.json');
   fs.writeFileSync(out, JSON.stringify(artifact, null, 2));
+  if (!OPT.page && !OPT.out && order.length) {
+    fs.writeFileSync(path.join(ARTIFACTS, 'page-audit-look-order.txt'),
+      `# Look at ALL ${order.length} pages; this only sets which first (worst first).\n`
+      + order.map((o) => `${o.rank}\t${o.verdict}\t${o.findings}\t${o.page}\t${o.screenshotTop || o.screenshot || '(no screenshot)'}`).join('\n') + '\n');
+  }
 
   // ── console summary ────────────────────────────────────────────────────────
   console.log(`\npage-audit — ${artifact.run.mode} — ${perPage.length} pages, ${checks.length} checks`);
@@ -955,12 +993,14 @@ function finish({ startedAt, checks, instruments, perPage, coverage, app, contro
     console.log(`wireframe coverage: ${coverage.withWireframe}/${coverage.inScopePages} in-scope pages have one `
       + `(${coverage.withoutWireframe} do not: ${coverage.pagesWithNoWireframe.join(', ') || 'none'})`);
   }
-  for (const p of perPage) {
+  const byPage = new Map(perPage.map((p) => [p.page, p]));
+  for (const p of order.map((o) => byPage.get(o.page))) {
     const f = p.findings.length;
     console.log(`  ${p.verdict.toUpperCase().padEnd(5)} ${p.page.padEnd(42)} ${p.checkCount || 0} checks, ${f} finding${f === 1 ? '' : 's'}`
       + (p.wireframe && !p.wireframe.exists ? '  [NO WIREFRAME]' : ''));
   }
   console.log(`\nverdicts: ${JSON.stringify(tally)}  →  ${out}`);
+  if (order.length) console.log(`look order (worst first, all ${order.length} pages): ${path.join(ARTIFACTS, 'page-audit-look-order.txt')}`);
 
   const anyFault = checks.some((c) => c.verdict === 'fault');
   const anyFail = checks.some((c) => c.verdict === 'fail');
@@ -975,4 +1015,4 @@ if (require.main === module) {
   } catch (e) { console.error(e.stack); process.exitCode = 2; }
 }
 
-module.exports = { auditPageStatic, readCompleteness, worst, DOM_PROBE, PAGE_WIREFRAME };
+module.exports = { auditPageStatic, readCompleteness, worst, lookOrder, DOM_PROBE, PAGE_WIREFRAME };
diff --git a/skills/module-review.md b/skills/module-review.md
index fe653082..e2141a69 100644
--- a/skills/module-review.md
+++ b/skills/module-review.md
@@ -80,6 +80,13 @@ Both were invisible to a report that enumerated only what ran.
 Record the page set and its size in the report. `12 of 12 pages reviewed` is a claim.
 `reviewed the module` is not.
 
+**Order, not selection.** When `tests/e2e/page-audit.js` has run, open the screenshots in the
+order of `tests/e2e/artifacts/page-audit-look-order.txt`: worst first (fault, then fail, then by
+P1/P2/P3 finding count), so attention is freshest where the rules already found trouble. The file
+lists **all N pages**, its header says so, and the denominator does not change. A page at the
+bottom with zero findings still gets its look: the rules cannot see layout, and "the audit was
+clean" is exactly the "looked fine" this stage exists to refuse.
+
 ### 4b. Run the mechanical sweep first, then look at what it cannot see
 
 ```bash
diff --git a/skills/ui-loop.md b/skills/ui-loop.md
index 2dd7d075..78b5e64d 100644
--- a/skills/ui-loop.md
+++ b/skills/ui-loop.md
@@ -169,6 +169,20 @@ the "fix" (`Class: 'form-vertical'`) landed in the model, passed the gate, and c
 nothing on screen, because the theme, not the page, decides the form orientation — the
 first row of the table below, met on the first attempt.
 
+**Keep the app current without rebuilding it.** Same measure on an existing app (field run
+2026-10-07, cloud container, one page change), from exec to the change on screen:
+
+| How the app picks up the change | Time |
+|---|---|
+| `mxcli run --local --watch` kept running (page change) | ~18 s |
+| same, security or navigation change (it restarts itself) | ~60 s |
+| `bin/test-stack-up.sh` → `docker reload --skip-check` | 93 s |
+| restart (`docker run --wait`) | 179 s |
+
+So keep `run --local --watch` running beside the session; `test-stack-up.sh` notices a stale
+Docker app and reloads it, but that path is five times slower. `docker reload --css` does not
+compile SCSS: a `main.scss` edit needs the build.
+
 ## When it finds something — which side is actually wrong
 
 The symptom is easy to see. **Where the fix goes is not, and the instinct is usually wrong.**

From a908b4e565678ad3fadb11ae97ebe39b3d1c1325 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 13:19:40 +0000
Subject: [PATCH 03/19] test: journey fixtures copy settle.js with the engine

journey-runner.js now requires settle.js; the two fixtures that copy the
engine into a scratch project listed the files by hand and missed it, so
the require failed (MODULE_NOT_FOUND) before any assertion ran.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 tests/wave2/test-journey-control-exit.sh | 2 +-
 tests/wave2/test-journey-persona.sh      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/wave2/test-journey-control-exit.sh b/tests/wave2/test-journey-control-exit.sh
index 6d5a469f..8cbed98a 100755
--- a/tests/wave2/test-journey-control-exit.sh
+++ b/tests/wave2/test-journey-control-exit.sh
@@ -45,7 +45,7 @@ bad() { FAIL=$((FAIL+1)); echo "  FAIL — $1"; [ -n "${2:-}" ] && echo "
 WORK="$(mktemp -d "${TMPDIR:-/tmp}/journey-exit.XXXXXX")"
 trap 'rm -rf "$WORK"' EXIT
 mkdir -p "$WORK/tests/e2e"; : > "$WORK/Fixture.mpr"
-cp "$SUT" "$E2E/helpers.js" "$E2E/otel.js" "$E2E/config.js" "$WORK/tests/e2e/"
+cp "$SUT" "$E2E/helpers.js" "$E2E/settle.js" "$E2E/otel.js" "$E2E/config.js" "$WORK/tests/e2e/"
 cp "$CFG" "$WORK/tests/e2e/project.config.js"
 
 IFS= read -r -d '' JS <<'EOF' || true
diff --git a/tests/wave2/test-journey-persona.sh b/tests/wave2/test-journey-persona.sh
index 33d3454d..c44e779c 100755
--- a/tests/wave2/test-journey-persona.sh
+++ b/tests/wave2/test-journey-persona.sh
@@ -35,7 +35,7 @@ bad() { FAIL=$((FAIL+1)); echo "  FAIL — $1"; [ -n "${2:-}" ] && echo "
 WORK="$(mktemp -d "${TMPDIR:-/tmp}/journey-persona.XXXXXX")"
 trap 'rm -rf "$WORK"' EXIT
 mkdir -p "$WORK/tests/e2e"; : > "$WORK/Fixture.mpr"
-cp "$SUT" "$E2E/helpers.js" "$E2E/otel.js" "$E2E/config.js" "$WORK/tests/e2e/"
+cp "$SUT" "$E2E/helpers.js" "$E2E/settle.js" "$E2E/otel.js" "$E2E/config.js" "$WORK/tests/e2e/"
 cp "$CFG" "$WORK/tests/e2e/project.config.js"
 
 IFS= read -r -d '' JS <<'JSEOF' || true

From 6444992116dbe4dc9bc506701069ce49db782185 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 13:56:25 +0000
Subject: [PATCH 04/19] perf(ui-loop): test-stack-up recognises mxcli run
 --local; restart builds once

- A live `mxcli run --local` (its .mxcli/run-local.json beside this project's
  .mpr, pid alive) is now published as APP_OWNERSHIP=verified, APP_SOURCE=run-local
  instead of an unverified port-scan hit the e2e harness refuses.
- Staleness knows the loop: with --watch a model edit reads "watch" (ready),
  without it "APP UP BUT STALE - restart with --watch".
- Two-tree checkouts (app/X.mpr, with or without a root symlink) are resolved.
- docker path uses `docker run --wait` instead of the 240s poll; --restart no
  longer runs the build twice.
- Fixture tests/wave2/test-stack-up-local.sh over a golden captured from a real
  run and value-scrubbed (field run 2026-10-07, existing app).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                                  |   1 +
 project-bin/test-stack-up.sh                  | 169 ++++++++++++++----
 project-tests/e2e/config.js                   |   3 +-
 skills/harness-architecture.md                |   6 +-
 skills/report-schema.md                       |   2 +-
 skills/ui-loop.md                             |   6 +
 tests/wave2/fixtures/run-local/run-local.json |  22 +++
 tests/wave2/test-stack-up-local.sh            | 147 +++++++++++++++
 8 files changed, 316 insertions(+), 40 deletions(-)
 create mode 100644 tests/wave2/fixtures/run-local/run-local.json
 create mode 100755 tests/wave2/test-stack-up-local.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d65e66e..5275228f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- perf(ui-loop): **`test-stack-up.sh` recognises a live `mxcli run --local` as this project's app, and `--restart` no longer builds twice.** The script read only Docker labels, so an app started with `./mxcli run --local --watch` (mxcli's own ~20s page loop) was found by port scan, published as `APP_OWNERSHIP=unverified`, and refused by the e2e harness unless `ALLOW_UNVERIFIED_APP=1`. It now reads mxcli's `.mxcli/run-local.json` handshake (v0.24+; beside the `.mpr` or the `-p` path on a two-tree checkout), checks its pid is alive, and publishes `verified` with a new `APP_SOURCE=run-local` line in `stack.env` (`docker` / `scan` otherwise). A model edited after boot reads as applied under `--watch` and as STALE without it — the script never restarts a loop it did not start. Docker bring-up and restart now wait on `mxcli docker run --wait` instead of a 240s poll loop, and still prove HTTP; `--restart` used to fall through into the bring-up block and run `docker run` a second time. New fixture `tests/wave2/test-stack-up-local.sh` over a redacted capture of the handshake. Field run 2026-10-07, existing app: same app, same port, `unverified` → `verified`; a touched model read `watch`; stopping the loop removed the handshake and the script fell back. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
 - feat(permissions): **intake now picks how much Claude Code may run without a prompt, and `doctor.sh` shows it.** Until now the allow-list covered only the safe wrappers (`bin/exec.sh`, `bin/*.sh`, `./mxcli`, `mx`), so every edit, test run, `npm install` or `git commit` in a project still prompted. New `bin/permission-profile.sh` resolves a profile (env, `.mxtk/permission-profile`, PROJECT.md `Permission profile:`, default `project`; a typo falls back to `wrappers`): `wrappers` is the old list; `project` adds edits anywhere inside the project folder (`Edit(/**)`) and the everyday test/npm/docker/git-add/commit commands, with force-push, `git reset --hard`, `git clean` and `sudo` behind `ask` rules that prompt in every mode; `full` adds bare `Bash`/`Edit`/`Read`/`WebFetch`/`WebSearch` to the per-machine `settings.local.json` only, never the shared file. `install-claude-permissions.sh` / `install-harness-permissions.sh` take `--profile`, and switching to a smaller profile removes only what the script itself added. Intake gains Q12, `init-project.sh` writes `Permission profile: project`, and `doctor.sh <project>` reports the profile, whether the settings files carry it, and warns on a `defaultMode` of auto/bypass in a project file, which Claude Code ignores there. No profile can switch on bypass or auto mode from the project: doctor says how to do that from the user's own settings. `test-install-claude-permissions.sh` gains T5b. — MendixMau
diff --git a/project-bin/test-stack-up.sh b/project-bin/test-stack-up.sh
index 09abf59f..01f467ac 100755
--- a/project-bin/test-stack-up.sh
+++ b/project-bin/test-stack-up.sh
@@ -48,6 +48,16 @@
 # proof-of-ownership step. `docker reload --css` is NOT a theme loop: it copies the theme without
 # compiling SCSS, so a main.scss edit does not show.
 #
+# RUN --LOCAL IS RECOGNISED, NOT REPLACED. `mxcli run --local` (v0.24+) publishes
+# <mpr dir>/.mxcli/run-local.json while it serves — pid and app port, written when the app is ready,
+# removed on exit. A live pid in OUR project's directory plus a Mendix answer on its port is the same
+# kind of claim as the compose label: it cannot be true of two projects at once. So that app is
+# ownership `verified` (APP_SOURCE=run-local), where it used to scan as `unverified` and the e2e
+# config refused it — the recommended fast loop was the one the harness would not test. This script
+# never restarts or reloads it (it did not start it): `--watch` applies each change itself, and
+# without --watch a model newer than the handshake is reported stale with the restart to run. Only
+# pid and appPort are read; the file also holds the admin password and boot config, never copied.
+#
 # Exit codes: 0 = required stack is up · 1 = not up and could not fix · 2 = usage/env error
 #
 # PROJECT CONFIGURATION — no project name, port or service path is hardcoded here. Put anything
@@ -176,7 +186,7 @@ EOF
   return 1
 }
 
-# find_app_port emits "<port>|<ownership>" on stdout, NOT a bare port.
+# find_app_port emits "<port>|<ownership>|<source>" on stdout, NOT a bare port.
 #
 # It is called in a command substitution, so it runs in a subshell and cannot set a variable in the
 # parent — the ownership verdict has to travel on stdout with the port or it is lost.
@@ -189,11 +199,13 @@ EOF
 # someone else's software.
 find_app_port() {
   local p owned
+  # 0. A live `mxcli run --local` of this project (its handshake names the port).
+  if owned="$(local_loop_port)" && mendix_at "$owned"; then echo "$owned|verified|run-local"; return 0; fi
   # 1. Ownership: which port does THIS project's container publish?
   if owned="$(owned_app_port)" && [ -n "$owned" ]; then
-    if mendix_at "$owned"; then echo "$owned|verified"; return 0; fi
+    if mendix_at "$owned"; then echo "$owned|verified|docker"; return 0; fi
     warn "our container publishes :$owned but it is not serving Mendix yet" >&2
-    echo "$owned|verified"; return 1
+    echo "$owned|verified|docker"; return 1
   fi
   # 2. No container of ours is running (SP-hosted run, or docker unavailable). Fall back to the
   #    scan — but say so, because a hit here is UNVERIFIED ownership: it proves a Mendix answered,
@@ -203,10 +215,62 @@ find_app_port() {
       warn "no container owned by $ROOT/.docker is running; :$p matched by scan — ownership UNVERIFIED" >&2
       warn "  → recorded as APP_OWNERSHIP=unverified in stack.env. A test harness should REFUSE an" >&2
       warn "    unverified port unless ALLOW_UNVERIFIED_APP=1, because :$p may be another project." >&2
-      echo "$p|unverified"; return 0
+      echo "$p|unverified|scan"; return 0
     fi
   done
-  echo "|none"; return 1
+  echo "|none|none"; return 1
+}
+
+# A live `mxcli run --local` serving THIS project: echoes its app port. See RUN --LOCAL above.
+# Fields are read at MarshalIndent's two-space top level, so a key inside bootConfig cannot match.
+MPR_DIR="$(cd "$(dirname "$MPR")" && pwd)"
+# A two-tree checkout may carry a root symlink to app/X.mpr. mprcontents/ sits beside the real
+# file, and mxcli writes the handshake beside whichever path -p was given — so look in both.
+MODEL_DIR="$MPR_DIR"
+if [ -L "$MPR" ]; then
+  _t="$(readlink "$MPR")"
+  case "$_t" in /*) ;; *) _t="$MPR_DIR/$_t" ;; esac
+  MODEL_DIR="$(cd "$(dirname "$_t")" 2>/dev/null && pwd -P)" || MODEL_DIR="$MPR_DIR"
+fi
+LOCAL_HS="$MPR_DIR/.mxcli/run-local.json"
+pick_local_hs() {
+  local d
+  for d in "$MPR_DIR" "$MODEL_DIR"; do
+    [ -f "$d/.mxcli/run-local.json" ] && { LOCAL_HS="$d/.mxcli/run-local.json"; return 0; }
+  done
+  return 1
+}
+pick_local_hs || true
+hs_field() { sed -n "s/^  \"$1\": *\([0-9][0-9]*\).*/\1/p" "$LOCAL_HS" 2>/dev/null | head -1; }
+pid_alive() {
+  [ -n "$1" ] || return 1
+  case "$(mxtk_platform)" in
+    # mxcli.exe records a Windows pid; Git Bash's kill only knows MSYS pids.
+    windows) tasklist //FI "PID eq $1" //NH 2>/dev/null | grep -q " $1 " ;;
+    *)       kill -0 "$1" 2>/dev/null ;;
+  esac
+}
+local_loop_port() {
+  local pid port
+  pick_local_hs || return 1
+  pid="$(hs_field pid)"; port="$(hs_field appPort)"
+  [ -n "$port" ] && pid_alive "$pid" || return 1
+  echo "$port"
+}
+# yes | no | unknown — was the loop started with --watch? Read from its command line where ps can
+# show one; Windows processes do not expose it to Git Bash.
+local_loop_watch() {
+  local pid args
+  pid="$(hs_field pid)"
+  args="$(ps -o args= -p "$pid" 2>/dev/null)" || { echo unknown; return; }
+  [ -n "$args" ] || { echo unknown; return; }
+  case "$args" in *--watch*) echo yes ;; *) echo no ;; esac
+}
+# Did the model change since the loop booted? The handshake is written when the app is ready, so
+# its mtime is the boot's model; any .mpr or mprcontents file newer than it is a later edit.
+local_model_changed() {
+  [ -n "$(find "$MODEL_DIR" -maxdepth 1 -name '*.mpr' -newer "$LOCAL_HS" 2>/dev/null | head -1)" ] && return 0
+  [ -d "$MODEL_DIR/mprcontents" ] && [ -n "$(find "$MODEL_DIR/mprcontents" -type f -newer "$LOCAL_HS" 2>/dev/null | head -1)" ]
 }
 
 # Single source of truth for the discovered ports. This script is the only thing that PROVES which
@@ -215,7 +279,7 @@ find_app_port() {
 # 8081 and a skill said 8080 — three "truths", and a spec pointed at a dead port reports the app as
 # broken rather than as unreachable.
 STACK_ENV="${STACK_ENV:-$ROOT/.claude/loop/stack.env}"
-# publish_stack_env <port> <jaeger_ok> <ownership>
+# publish_stack_env <port> <jaeger_ok> <ownership> <source>
 # APP_OWNERSHIP is not decoration: it is the difference between "this port is ours" and "a Mendix
 # answered here". Consumers must be able to tell those apart from the file alone, because the stderr
 # warning that distinguishes them is gone by the time anyone reads it.
@@ -225,6 +289,7 @@ publish_stack_env() {
     echo "# written by bin/test-stack-up.sh — $(date -u +%Y-%m-%dT%H:%M:%SZ). Do not edit."
     echo "APP_PORT=$1"
     echo "APP_OWNERSHIP=${3:-unknown}"
+    echo "APP_SOURCE=${4:-unknown}"
     [ -n "$MOCK_PORT" ] && echo "MOCK_PORT=$MOCK_PORT"
     [ "$2" -eq 0 ] && echo "JAEGER_PORT=$JAEGER_PORT" || echo "JAEGER_PORT="
   } > "$STACK_ENV"
@@ -246,6 +311,13 @@ record_served() {
 # Echoes fresh | stale | unknown.
 served_state() {
   local want have
+  # run --local: mxcli rebuilt nothing for us to record; the handshake's mtime is the boot.
+  if [ "${APP_SOURCE:-}" = "run-local" ]; then
+    pick_local_hs || true
+    if ! local_model_changed; then echo fresh
+    else case "$(local_loop_watch)" in yes) echo watch ;; no) echo stale ;; *) echo changed ;; esac; fi
+    return
+  fi
   have="$(head -1 "$SERVED_FILE" 2>/dev/null)"
   want="$(model_fp)" || want=""
   if [ -z "$have" ] || [ -z "$want" ]; then echo unknown
@@ -253,6 +325,19 @@ served_state() {
   else echo stale; fi
 }
 
+# After `docker run --wait` returned: prove over HTTP that OUR app answers (design rule 3). mxcli's
+# wait reads the runtime log, so this normally passes on the first probe. Sets APP_* in this shell.
+prove_app() {
+  local waited=0
+  while :; do
+    APP_FIND="$(find_app_port)" && break
+    [ $waited -ge 30 ] && break
+    sleep 3; waited=$((waited + 3))
+  done
+  IFS='|' read -r APP_PORT APP_OWNERSHIP APP_SOURCE <<<"$APP_FIND"
+  mendix_at "$APP_PORT"
+}
+
 echo "── Test stack: $PROJ ──────────────────────────────────"
 
 # --- Studio Pro: report only, never act -------------------------------------
@@ -277,10 +362,11 @@ fi
 # --- App --------------------------------------------------------------------
 APP_FIND="$(find_app_port)"
 APP_FOUND=$?
-APP_PORT="${APP_FIND%%|*}"
-APP_OWNERSHIP="${APP_FIND##*|}"
+IFS='|' read -r APP_PORT APP_OWNERSHIP APP_SOURCE <<<"$APP_FIND"
 if [ $APP_FOUND -eq 0 ]; then
-  if [ "$APP_OWNERSHIP" = "verified" ]; then
+  if [ "$APP_SOURCE" = "run-local" ]; then
+    ok "App serving on :$APP_PORT (ownership verified — this project's mxcli run --local)"
+  elif [ "$APP_OWNERSHIP" = "verified" ]; then
     ok "App serving on :$APP_PORT (ownership verified — our container)"
   else
     warn "App serving on :$APP_PORT — ownership $APP_OWNERSHIP, this may be another project"
@@ -293,7 +379,10 @@ if [ $APP_FOUND -eq 0 ]; then
   SERVED="$(served_state)"
   case "$SERVED" in
     fresh)   ok "App serves the current model" ;;
-    stale)   warn "App serves an OLDER model — the model changed since it was built; tests would measure the old build" ;;
+    stale)   warn "App serves an OLDER model — the model changed since it was built; tests would measure the old build"
+             [ "$APP_SOURCE" = "run-local" ] && warn "  → run --local was started without --watch: stop it and start ./mxcli run --local --watch -p $(basename "$MPR")" ;;
+    watch)   ok "Model changed since boot — run --local --watch applies it (~20s a page change, ~60s security/navigation)" ;;
+    changed) warn "Model changed since run --local booted; cannot see whether it runs with --watch. Without --watch it serves the old model" ;;
     unknown) warn "App freshness unknown — not built by this script (Studio Pro / manual run); it may serve an old model" ;;
   esac
 fi
@@ -346,7 +435,7 @@ fi
 # Publish as soon as the port is MEASURED, not only when the whole stack is READY. A down mock makes
 # REST-fed specs invalid; it does not change which port the app answers on, and the non-REST specs
 # still need to know it.
-[ $APP_FOUND -eq 0 ] && publish_stack_env "$APP_PORT" "$JAEGER_OK" "$APP_OWNERSHIP"
+[ $APP_FOUND -eq 0 ] && publish_stack_env "$APP_PORT" "$JAEGER_OK" "$APP_OWNERSHIP" "$APP_SOURCE"
 
 if [ "$MODE" = "check" ]; then
   echo "────────────────────────────────────────────────────────"
@@ -354,6 +443,10 @@ if [ "$MODE" = "check" ]; then
     echo "APP UP, BUT REST-FED SPECS WILL BE INVALID — see the container warning above"
     exit 1
   fi
+  if [ "$SERVED" = "stale" ] && [ "$APP_SOURCE" = "run-local" ]; then
+    echo "APP UP BUT STALE — restart mxcli run --local with --watch (this script does not restart a loop it did not start)"
+    exit 1
+  fi
   if [ "$SERVED" = "stale" ] && [ "$APP_OWNERSHIP" = "verified" ]; then
     echo "APP UP BUT STALE — re-run without --check to hot-reload the current model"
     exit 1
@@ -383,9 +476,10 @@ if [ $MOCK_REQUIRED -eq 1 ] && [ $MOCK_OK -ne 0 ]; then
 fi
 
 # --- Warm loop: refresh a running app instead of restarting it --------------
-# Only for OUR container (ownership verified): a reload swaps the model in a runtime, and doing that
-# to an unverified port could be another project's app or a Studio Pro run.
-if [ $APP_FOUND -eq 0 ] && [ "$APP_OWNERSHIP" = "verified" ] && [ -n "$MXCLI" ] \
+# Only for OUR container (ownership verified, source docker): a reload swaps the model in a runtime,
+# and doing that to an unverified port could be another project's app or a Studio Pro run. A
+# run --local loop is never reloaded from here — --watch does that, inside the process that owns it.
+if [ $APP_FOUND -eq 0 ] && [ "$APP_SOURCE" = "docker" ] && [ -n "$MXCLI" ] \
    && [ "${MXTK_WARM_RELOAD:-on}" != "off" ] && [ "$MODE" != "nodocker" ] \
    && { [ "$SERVED" != "fresh" ] || [ "$MODE" = "restart" ]; }; then
   T0=$(date +%s)
@@ -419,18 +513,25 @@ if [ $APP_FOUND -eq 0 ] && [ "$APP_OWNERSHIP" = "verified" ] && [ -n "$MXCLI" ]
   fi
   if [ $RELOADED -ne 0 ]; then
     echo "→ Rebuilding and restarting the container..."
-    "$MXCLI" docker run -p "$MPR" --wait >"$DOCKER_LOG" 2>&1
+    "$MXCLI" docker run -p "$MPR" --wait --wait-timeout "$BOOT_TIMEOUT" >"$DOCKER_LOG" 2>&1
     if [ $? -ne 0 ]; then
       bad "mxcli docker run failed — see $DOCKER_LOG"; tail -20 "$DOCKER_LOG"; exit 1
     fi
-    APP_FOUND=1   # re-proved below by the boot-wait loop
+    # Proved here, not by falling into "Bring up the app" below: that block runs `docker run`
+    # again, and did — every restart built and booted the app twice.
+    if prove_app; then
+      record_served; SERVED=fresh
+      ok "Restarted in $(( $(date +%s) - T0 ))s — app serves the current model"
+    else
+      bad "mxcli reported the runtime started, but no Mendix answers over HTTP — see $DOCKER_LOG"; exit 1
+    fi
   fi
 fi
 
 # --- Bring up the app -------------------------------------------------------
 if [ $APP_FOUND -ne 0 ]; then
   if [ "$MODE" = "nodocker" ]; then
-    bad "App down and --no-docker given. Click Run Locally in Studio Pro (or, with no Studio Pro, ./mxcli run --local), then re-run --check."
+    bad "App down and --no-docker given. Click Run Locally in Studio Pro (or, with no Studio Pro, ./mxcli run --local --watch), then re-run --check."
     exit 1
   fi
   # No reachable Docker (or Podman) daemon: say so and name the Docker-free route, instead of letting
@@ -450,7 +551,8 @@ if [ $APP_FOUND -ne 0 ]; then
     bad "App down and no Docker/Podman reachable, so this script cannot build the app container."
     echo "  Normal in a cloud container, and fine on a desktop without one. Run the app without it:"
     echo "    Studio Pro: Run Locally.  No Studio Pro:"
-    echo "    ./mxcli run --local -p $(basename "$MPR")   # flags: skills/cloud-dev-environment.md"
+    echo "    ./mxcli run --local --watch -p $(basename "$MPR")   # flags: skills/cloud-dev-environment.md"
+    echo "  This script then sees it as yours (verified) and --watch keeps it current."
     echo "  Snapshot first — mxcli run --local consolidates a split-model .mpr. Then re-run with --check."
     exit 1
   fi
@@ -463,9 +565,9 @@ if [ $APP_FOUND -ne 0 ]; then
   echo "  This can take several minutes on a cold build."
 
   # Do NOT pipe mxcli: reading $? through a pipe measures the pipe, not the command.
-  # (this script runs without `set -e` on purpose — the boot-wait loop below relies on
-  #  find_app_port returning non-zero repeatedly without killing the script)
-  "$MXCLI" docker run -p "$MPR" >"$DOCKER_LOG" 2>&1
+  # --wait: mxcli follows the runtime log until it reports started, so the boot wait is mxcli's.
+  # The loop below is the HTTP proof (design rule 3) and normally passes on its first probe.
+  "$MXCLI" docker run -p "$MPR" --wait --wait-timeout "$BOOT_TIMEOUT" >"$DOCKER_LOG" 2>&1
   DOCKER_RC=$?
   if [ $DOCKER_RC -ne 0 ]; then
     bad "mxcli docker run failed (rc=$DOCKER_RC) — see $DOCKER_LOG"
@@ -473,33 +575,28 @@ if [ $APP_FOUND -ne 0 ]; then
     exit 1
   fi
 
-  echo "→ Waiting for the app to answer (timeout ${BOOT_TIMEOUT}s)..."
-  WAITED=0
-  while [ $WAITED -lt "$BOOT_TIMEOUT" ]; do
-    APP_FIND="$(find_app_port)" && { APP_FOUND=0; break; }
-    sleep 3; WAITED=$((WAITED + 3))
-    [ $((WAITED % 30)) -eq 0 ] && echo "  ...${WAITED}s"
-  done
-  APP_PORT="${APP_FIND%%|*}"
-  APP_OWNERSHIP="${APP_FIND##*|}"
-
-  if [ $APP_FOUND -eq 0 ]; then
+  if prove_app; then
+    APP_FOUND=0
     record_served
-    ok "App serving on :$APP_PORT after ${WAITED}s (ownership $APP_OWNERSHIP)"
+    ok "App serving on :$APP_PORT (ownership $APP_OWNERSHIP)"
   else
-    bad "App still not answering after ${BOOT_TIMEOUT}s — see $DOCKER_LOG"
+    bad "mxcli reported the runtime started, but no Mendix answers over HTTP — see $DOCKER_LOG"
     "$MXCLI" docker status -p "$MPR" 2>&1 | tail -5
     exit 1
   fi
 fi
 
 echo "────────────────────────────────────────────────────────"
+if [ "$APP_SOURCE" = "run-local" ] && [ "$SERVED" = "stale" ]; then
+  echo "NOT READY — the run --local app serves an older model; restart it with --watch"
+  exit 1
+fi
 if [ $APP_FOUND -eq 0 ] && [ $MOCK_OK -eq 0 ]; then
   # re-publish: both the port AND the ownership can change across a Docker boot — before the boot no
   # container of ours was running (so any hit was an unverified scan); after it, one is.
-  publish_stack_env "$APP_PORT" "$JAEGER_OK" "$APP_OWNERSHIP"
+  publish_stack_env "$APP_PORT" "$JAEGER_OK" "$APP_OWNERSHIP" "$APP_SOURCE"
   echo "READY — ports published to ${STACK_ENV#$ROOT/}; the e2e config reads them automatically"
-  echo "  app    :$APP_PORT  (ownership $APP_OWNERSHIP)"
+  echo "  app    :$APP_PORT  (ownership $APP_OWNERSHIP, $APP_SOURCE)"
   [ -n "$MOCK_PORT" ] && echo "  mock   :$MOCK_PORT"
   echo "  jaeger $([ $JAEGER_OK -eq 0 ] && echo ":$JAEGER_PORT" || echo 'DOWN — Trace assertions will not run')"
   exit 0
diff --git a/project-tests/e2e/config.js b/project-tests/e2e/config.js
index 8b626a57..23c54cb1 100644
--- a/project-tests/e2e/config.js
+++ b/project-tests/e2e/config.js
@@ -34,7 +34,8 @@ const ROOT = PROJ.root;
 //
 // test-stack-up.sh now records APP_OWNERSHIP: `verified` means the port is published
 // by a container whose compose working_dir is THIS project (the one identity claim
-// that cannot be true of two projects at once); `unverified` means a port scan found
+// that cannot be true of two projects at once), or by a live `mxcli run --local` whose
+// .mxcli/run-local.json sits beside THIS project's .mpr; `unverified` means a port scan found
 // a Mendix and nothing more. We refuse `unverified` rather than warn about it —
 // this whole harness exists because a warning on stderr is not a guard.
 function resolveStack() {
diff --git a/skills/harness-architecture.md b/skills/harness-architecture.md
index 08969e06..59925ca0 100644
--- a/skills/harness-architecture.md
+++ b/skills/harness-architecture.md
@@ -34,11 +34,13 @@ APP_PORT=<port>
 APP_OWNERSHIP=verified | unverified | asserted | unknown
 ```
 
-`verified` means a container owned by this project's `.docker` is serving that port. `unverified`
+`verified` means a container owned by this project's `.docker` is serving that port, or a live
+`mxcli run --local` of this project is (its `.mxcli/run-local.json` names the port; `APP_SOURCE`
+says which: `docker` | `run-local` | `scan`). `unverified`
 means a Mendix answered a port from the `APP_PORTS` fallback scan list — *a* Mendix, not
 necessarily yours. **A harness must refuse an unverified port** unless the operator sets
 `ALLOW_UNVERIFIED_APP=1`, and must record the ownership it acted on. **VERIFIED**
-(`project-bin/test-stack-up.sh:150-198`).
+(`project-bin/test-stack-up.sh`, `owned_app_port` / `local_loop_port` / `find_app_port`).
 
 This is not defensive decoration. On one measured occasion a published `stack.env` named a port
 that belonged to a *different* project's Mendix, which answered 200 with a real login page. Every
diff --git a/skills/report-schema.md b/skills/report-schema.md
index f8054752..b564068e 100644
--- a/skills/report-schema.md
+++ b/skills/report-schema.md
@@ -492,7 +492,7 @@ reported normally.
 
 | Value | Means | Basis |
 |---|---|---|
-| `verified` | a container published this port **and** its compose `working_dir` label is this project — the one identity claim that cannot be true of two projects at once | `APP_OWNERSHIP=verified` in `.claude/loop/stack.env`, written by `bin/test-stack-up.sh` |
+| `verified` | a container published this port **and** its compose `working_dir` label is this project — the one identity claim that cannot be true of two projects at once; or a live `mxcli run --local` whose `.mxcli/run-local.json`, beside this project's `.mpr`, names the port (`APP_SOURCE=run-local`) | `APP_OWNERSHIP=verified` in `.claude/loop/stack.env`, written by `bin/test-stack-up.sh` |
 | `asserted` | an operator said so and nothing checked | an `APP_PORT` env var, or the project's deployment config |
 | `unknown` | a Mendix answered and nothing more | a guess, or a `stack.env` predating the marker |
 
diff --git a/skills/ui-loop.md b/skills/ui-loop.md
index 78b5e64d..2efc2b43 100644
--- a/skills/ui-loop.md
+++ b/skills/ui-loop.md
@@ -183,6 +183,12 @@ So keep `run --local --watch` running beside the session; `test-stack-up.sh` not
 Docker app and reloads it, but that path is five times slower. `docker reload --css` does not
 compile SCSS: a `main.scss` edit needs the build.
 
+`test-stack-up.sh` recognises the watch loop as this project's app: `mxcli run --local` (v0.24+)
+writes `.mxcli/run-local.json` beside the `.mpr` while it serves, and a live pid there plus a
+Mendix answer on its port publishes `APP_OWNERSHIP=verified`, `APP_SOURCE=run-local`, so the e2e
+config tests it without `ALLOW_UNVERIFIED_APP=1`. It never reloads or restarts that loop. Started
+without `--watch`, a model edited since boot is reported stale with the restart to run.
+
 ## When it finds something — which side is actually wrong
 
 The symptom is easy to see. **Where the fix goes is not, and the instinct is usually wrong.**
diff --git a/tests/wave2/fixtures/run-local/run-local.json b/tests/wave2/fixtures/run-local/run-local.json
new file mode 100644
index 00000000..bd343462
--- /dev/null
+++ b/tests/wave2/fixtures/run-local/run-local.json
@@ -0,0 +1,22 @@
+{
+  "project": "/work/Fixture/Fixture.mpr",
+  "pid": 4242,
+  "appPort": 8180,
+  "adminPort": 8190,
+  "adminPass": "REDACTED",
+  "bootConfig": {
+    "BasePath": "/work/Fixture/deployment",
+    "DTAPMode": "D",
+    "DatabaseHost": "",
+    "DatabaseName": "default",
+    "DatabasePassword": "REDACTED",
+    "DatabaseType": "HSQLDB",
+    "DatabaseUserName": "sa",
+    "MicroflowConstants": {
+      "MyFirstModule.LogNode": "REDACTED",
+      "MyFirstModule.ServiceUrl": "REDACTED"
+    },
+    "RuntimePath": "/opt/mendix/runtime"
+  },
+  "started": "2026-10-07T12:27:57Z"
+}
\ No newline at end of file
diff --git a/tests/wave2/test-stack-up-local.sh b/tests/wave2/test-stack-up-local.sh
new file mode 100755
index 00000000..8813e3d9
--- /dev/null
+++ b/tests/wave2/test-stack-up-local.sh
@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Fixtures for test-stack-up.sh recognising a live `mxcli run --local` as THIS project's app.
+#
+# mxcli (v0.24+) writes <dir of -p>/.mxcli/run-local.json when the app is ready and removes it on
+# exit. Before this change the script never read it: a run --local app was found by port scan,
+# published as APP_OWNERSHIP=unverified, and the e2e harness refused it unless the operator set
+# ALLOW_UNVERIFIED_APP=1. Field run 2026-10-07, existing app: same app, same port, now `verified`.
+#
+# The handshake is fixtures/run-local/run-local.json — a real capture from that field run, every
+# value replaced (project path, pid, ports, passwords, constants), byte layout kept. Each case
+# rewrites only pid/appPort/adminPass. The "app" is a python http.server serving a login page with
+# a Mendix marker; the "mxcli" is `sleep` with its argv[0] set, so `ps` shows the command line the
+# script reads --watch from. docker/podman are stubbed out so no real container can answer.
+# Not fixtured: the Windows tasklist branch of pid_alive (CI is Linux).
+#
+# usage: test-stack-up-local.sh /path/to/test-stack-up.sh
+set -uo pipefail
+
+SRC="${1:?usage: test-stack-up-local.sh /path/to/test-stack-up.sh}"
+case "$SRC" in /*) ;; *) SRC="$PWD/$SRC" ;; esac
+GOLDEN="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fixtures/run-local/run-local.json"
+[ -f "$SRC" ] && [ -f "$(dirname "$SRC")/_common.sh" ] && [ -f "$GOLDEN" ] \
+  || { echo "FIXTURE ERROR: need $SRC, its _common.sh, and $GOLDEN"; exit 2; }
+command -v python3 >/dev/null 2>&1 && command -v curl >/dev/null 2>&1 \
+  || { echo "FIXTURE ERROR: needs python3 and curl"; exit 2; }
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/stackup-local.XXXXXX")"
+PIDS=""
+cleanup() { for p in $PIDS; do kill "$p" 2>/dev/null; done; rm -rf "$WORK"; }
+trap cleanup EXIT
+PASS=0; FAIL=0
+ok()  { PASS=$((PASS+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAIL=$((FAIL+1)); printf '  FAIL %s\n' "$1"; [ -n "${2:-}" ] && printf '%s\n' "$2" | sed 's/^/  FAIL-detail: /'; }
+
+# --- no container runtime: only our fake app can answer ----------------------------------
+mkdir -p "$WORK/stubs"
+for t in docker podman; do printf '#!/bin/sh\nexit 1\n' > "$WORK/stubs/$t"; chmod +x "$WORK/stubs/$t"; done
+export PATH="$WORK/stubs:$PATH"
+unset PROJECT_ROOT MPR_FILE STACK_ENV STACK_CONF SERVED_FILE
+
+# --- the fake app -------------------------------------------------------------------------
+mkdir -p "$WORK/www"
+printf '<html><script src="mxclientsystem/mxui/mxui.js"></script></html>\n' > "$WORK/www/login.html"
+python3 -I - "$WORK/www" "$WORK/port" >/dev/null 2>&1 <<'EOF' &
+import functools, http.server, sys
+H = functools.partial(http.server.SimpleHTTPRequestHandler, directory=sys.argv[1])
+s = http.server.ThreadingHTTPServer(("127.0.0.1", 0), H)
+open(sys.argv[2], "w").write(str(s.server_address[1]))
+s.serve_forever()
+EOF
+PIDS="$PIDS $!"
+for _ in $(seq 1 50); do [ -s "$WORK/port" ] && break; sleep 0.1; done
+APP="$(cat "$WORK/port" 2>/dev/null)"
+[ -n "$APP" ] && curl -s --max-time 4 "http://localhost:$APP/login.html" | grep -q mxui \
+  || { echo "FIXTURE ERROR: fake app did not come up"; exit 2; }
+
+# A process whose command line reads like mxcli's: fake_mxcli <var> <args after "mxcli">.
+fake_mxcli() {
+  bash -c "exec -a 'mxcli $2' sleep 600" >/dev/null 2>&1 &
+  PIDS="$PIDS $!"; printf -v "$1" '%s' "$!"
+}
+fake_mxcli WATCH_PID 'run --local --watch -p Fixture.mpr'
+fake_mxcli PLAIN_PID 'run --local -p Fixture.mpr'
+sleep 0.3   # let exec -a replace bash, so ps shows the mxcli command line
+sleep 0 & DEAD_PID=$!; wait "$DEAD_PID" 2>/dev/null
+
+ADMIN_MARK="fixture-admin-marker-7c1"   # stands in for the adminPass value
+OLD=202001010000
+
+# mkproj <name> <root|app|symlink> -> echoes the project root
+mkproj() {
+  local p="$WORK/$1" m
+  mkdir -p "$p/bin" "$p/.claude/loop"
+  cp "$SRC" "$p/bin/test-stack-up.sh"; cp "$(dirname "$SRC")/_common.sh" "$p/bin/"
+  # Nothing scanned or traced may answer: the run --local handshake is the only way in.
+  printf 'APP_PORTS="1"\nJAEGER_PORT="1"\n' > "$p/.claude/loop/stack.conf"
+  case "$2" in
+    root)    m="$p" ;;
+    app)     m="$p/app" ;;
+    symlink) m="$p/app"; ln -s app/Fixture.mpr "$p/Fixture.mpr" ;;
+  esac
+  mkdir -p "$m/mprcontents"; printf 'mpr' > "$m/Fixture.mpr"; printf 'u' > "$m/mprcontents/a.mxunit"
+  touch -t "$OLD" "$m/Fixture.mpr" "$m/mprcontents/a.mxunit"
+  echo "$p"
+}
+# handshake <dir> <pid> -> the golden, pointed at our fake app, written into <dir>/.mxcli/
+handshake() {
+  mkdir -p "$1/.mxcli"
+  sed -e "s/^  \"pid\": [0-9]*/  \"pid\": $2/" \
+      -e "s/^  \"appPort\": [0-9]*/  \"appPort\": $APP/" \
+      -e "s/^  \"adminPass\": \"[^\"]*\"/  \"adminPass\": \"$ADMIN_MARK\"/" "$GOLDEN" > "$1/.mxcli/run-local.json"
+}
+run() { (cd "$1" && bash bin/test-stack-up.sh --check 2>&1); }
+envv() { sed -n "s/^$2=//p" "$1/.claude/loop/stack.env" 2>/dev/null; }
+
+echo "== T0: the golden is what the script's reader expects =="
+grep -q '^  "pid": 4242,$' "$GOLDEN" && grep -q '^  "appPort": 8180,$' "$GOLDEN" \
+  && ok "golden carries pid/appPort at MarshalIndent's two-space top level" || bad "golden shape changed"
+grep -q "$ADMIN_MARK" "$GOLDEN" && bad "golden carries the test secret" || ok "golden carries no live secret"
+
+echo "== T1: live --watch loop, model unchanged -> verified, run-local, fresh =="
+P="$(mkproj t1 root)"; handshake "$P" "$WATCH_PID"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 0 ] && ok "--check exits 0" || bad "--check rc=$RC" "$OUT"
+printf '%s' "$OUT" | grep -q "ownership verified — this project's mxcli run --local" && ok "reported as this project's run --local" || bad "not reported as run --local" "$OUT"
+printf '%s' "$OUT" | grep -q "App serves the current model" && ok "fresh" || bad "not fresh" "$OUT"
+[ "$(envv "$P" APP_PORT)" = "$APP" ] && [ "$(envv "$P" APP_OWNERSHIP)" = verified ] && [ "$(envv "$P" APP_SOURCE)" = run-local ] \
+  && ok "stack.env: APP_PORT=$APP APP_OWNERSHIP=verified APP_SOURCE=run-local" || bad "stack.env wrong" "$(cat "$P/.claude/loop/stack.env" 2>&1)"
+grep -rq "$ADMIN_MARK" "$P/.claude" && bad "adminPass leaked into .claude/" || ok "adminPass not copied anywhere under .claude/"
+printf '%s' "$OUT" | grep -q "$ADMIN_MARK" && bad "adminPass printed" || ok "adminPass not printed"
+
+echo "== T2: dead pid -> the handshake is ignored =="
+P="$(mkproj t2 root)"; handshake "$P" "$DEAD_PID"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -ne 0 ] && printf '%s' "$OUT" | grep -q "App not serving" && ok "not trusted: app reported not serving" || bad "dead-pid handshake trusted (rc=$RC)" "$OUT"
+[ "$(envv "$P" APP_SOURCE)" = run-local ] && bad "stack.env says run-local for a dead loop" || ok "stack.env not claimed for a dead loop"
+
+echo "== T3: model edited, loop without --watch -> stale, exit 1 =="
+P="$(mkproj t3 root)"; handshake "$P" "$PLAIN_PID"; touch "$P/Fixture.mpr"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 1 ] && ok "--check exits 1" || bad "--check rc=$RC" "$OUT"
+printf '%s' "$OUT" | grep -q "APP UP BUT STALE — restart mxcli run --local with --watch" && ok "says restart with --watch" || bad "no stale verdict" "$OUT"
+
+echo "== T4: model edited, loop WITH --watch -> watch applies it, ready =="
+P="$(mkproj t4 root)"; handshake "$P" "$WATCH_PID"; touch "$P/mprcontents/a.mxunit"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q "run --local --watch applies it" && ok "watch state, exit 0" || bad "watch not recognised (rc=$RC)" "$OUT"
+
+echo "== T5: two-tree (app/), handshake beside app/Fixture.mpr =="
+P="$(mkproj t5 app)"; handshake "$P/app" "$PLAIN_PID"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 0 ] && [ "$(envv "$P" APP_SOURCE)" = run-local ] && ok "found under app/" || bad "two-tree handshake missed (rc=$RC)" "$OUT"
+touch "$P/app/mprcontents/a.mxunit"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 1 ] && printf '%s' "$OUT" | grep -q "APP UP BUT STALE" && ok "an app/mprcontents edit reads stale" || bad "app/ edit not seen (rc=$RC)" "$OUT"
+
+echo "== T6: two-tree with a root symlink, run as -p Fixture.mpr from the root =="
+P="$(mkproj t6 symlink)"; handshake "$P" "$PLAIN_PID"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 0 ] && [ "$(envv "$P" APP_SOURCE)" = run-local ] && ok "found beside the symlink" || bad "symlinked handshake missed (rc=$RC)" "$OUT"
+touch "$P/app/mprcontents/a.mxunit"
+OUT="$(run "$P")"; RC=$?
+[ "$RC" -eq 1 ] && printf '%s' "$OUT" | grep -q "APP UP BUT STALE" && ok "edit behind the symlink reads stale" || bad "edit behind symlink not seen (rc=$RC)" "$OUT"
+
+echo
+echo "stack-up-local: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

From 94532e4dddd22fae12ade8eb5e28f3bd3033faf4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 13:59:54 +0000
Subject: [PATCH 05/19] test(stack-up-local): resolve Python via portable.sh
 require_py

check-portability flagged the hard-coded python3; use "$PY" like the other fixtures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 tests/wave2/test-stack-up-local.sh | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/tests/wave2/test-stack-up-local.sh b/tests/wave2/test-stack-up-local.sh
index 8813e3d9..d9c5b761 100755
--- a/tests/wave2/test-stack-up-local.sh
+++ b/tests/wave2/test-stack-up-local.sh
@@ -21,8 +21,9 @@ case "$SRC" in /*) ;; *) SRC="$PWD/$SRC" ;; esac
 GOLDEN="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fixtures/run-local/run-local.json"
 [ -f "$SRC" ] && [ -f "$(dirname "$SRC")/_common.sh" ] && [ -f "$GOLDEN" ] \
   || { echo "FIXTURE ERROR: need $SRC, its _common.sh, and $GOLDEN"; exit 2; }
-command -v python3 >/dev/null 2>&1 && command -v curl >/dev/null 2>&1 \
-  || { echo "FIXTURE ERROR: needs python3 and curl"; exit 2; }
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/bin/lib/portable.sh"
+require_py
+command -v curl >/dev/null 2>&1 || { echo "FIXTURE ERROR: needs curl"; exit 2; }
 
 WORK="$(mktemp -d "${TMPDIR:-/tmp}/stackup-local.XXXXXX")"
 PIDS=""
@@ -41,7 +42,7 @@ unset PROJECT_ROOT MPR_FILE STACK_ENV STACK_CONF SERVED_FILE
 # --- the fake app -------------------------------------------------------------------------
 mkdir -p "$WORK/www"
 printf '<html><script src="mxclientsystem/mxui/mxui.js"></script></html>\n' > "$WORK/www/login.html"
-python3 -I - "$WORK/www" "$WORK/port" >/dev/null 2>&1 <<'EOF' &
+"$PY" -I - "$WORK/www" "$WORK/port" >/dev/null 2>&1 <<'EOF' &
 import functools, http.server, sys
 H = functools.partial(http.server.SimpleHTTPRequestHandler, directory=sys.argv[1])
 s = http.server.ThreadingHTTPServer(("127.0.0.1", 0), H)

From ff83fc8ffc01df758e13f75eba5ff332263f7b5a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 7 Oct 2026 14:10:08 +0000
Subject: [PATCH 06/19] test(stack-up-local): backdate the handshake so a
 same-tick edit still reads newer

CI T3 failed: the handshake write and the model touch landed in one clock tick, so
find -newer saw no edit (reproduced 35/50 locally). The handshake is now dated
between the model and the case's edit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 tests/wave2/test-stack-up-local.sh | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/wave2/test-stack-up-local.sh b/tests/wave2/test-stack-up-local.sh
index d9c5b761..369bbd72 100755
--- a/tests/wave2/test-stack-up-local.sh
+++ b/tests/wave2/test-stack-up-local.sh
@@ -67,6 +67,7 @@ sleep 0 & DEAD_PID=$!; wait "$DEAD_PID" 2>/dev/null
 
 ADMIN_MARK="fixture-admin-marker-7c1"   # stands in for the adminPass value
 OLD=202001010000
+BOOT=202101010000   # the handshake: newer than the model, older than any edit a case makes
 
 # mkproj <name> <root|app|symlink> -> echoes the project root
 mkproj() {
@@ -90,6 +91,9 @@ handshake() {
   sed -e "s/^  \"pid\": [0-9]*/  \"pid\": $2/" \
       -e "s/^  \"appPort\": [0-9]*/  \"appPort\": $APP/" \
       -e "s/^  \"adminPass\": \"[^\"]*\"/  \"adminPass\": \"$ADMIN_MARK\"/" "$GOLDEN" > "$1/.mxcli/run-local.json"
+  # Between the model (OLD) and now: a write and an edit in the same clock tick share an mtime,
+  # so an edit made right after this line would not read as newer (35/50 on a probe here).
+  touch -t "$BOOT" "$1/.mxcli/run-local.json"
 }
 run() { (cd "$1" && bash bin/test-stack-up.sh --check 2>&1); }
 envv() { sed -n "s/^$2=//p" "$1/.claude/loop/stack.env" 2>/dev/null; }

From 00eb9530c6cf7ee6a252127a6c27321a8b03b562 Mon Sep 17 00:00:00 2001
From: MendixMau <mauritscgvisser@gmail.com>
Date: Thu, 8 Oct 2026 07:22:28 +0800
Subject: [PATCH 07/19] fix(sync): sync-project.sh no longer exits 1 silently
 before its bin/ refresh

The CLAUDE.md duplicate-routing check looked up the "mxcli-project-toolkit
Integration" heading with an unguarded grep | head | cut under
set -euo pipefail. A CLAUDE.md that cites query-the-model.md or
learned-mdl-preflight.md without that heading (every mxcli init v0.25
CLAUDE.md) made grep exit 1, and errexit ended the whole sync there:
no bin/ crash-net refresh, no tests/e2e install, no lint-rule restore,
no message. Introduced by 9a0350b (2026-09-18).

Guard it with || true, and ledger_row_prefix too. New fixture
tests/wave2/test-sync-dup-heading-exit.sh: 6/6 on this script, 4 of 6
fail on the pre-fix one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MpdPDrT1dsCR54JrgWmNso
---
 CHANGELOG.md                              |  1 +
 bin/sync-project.sh                       | 11 +++-
 tests/wave2/test-sync-dup-heading-exit.sh | 65 +++++++++++++++++++++++
 3 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100755 tests/wave2/test-sync-dup-heading-exit.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e37d24f0..61b81c44 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(sync): **`sync-project.sh` no longer exits 1, silently, before its `bin/` and `tests/e2e/` refresh.** The CLAUDE.md duplicate-routing check (section 3) looked up the "mxcli-project-toolkit Integration" heading with an unguarded `grep | head | cut` under `set -euo pipefail`; when CLAUDE.md cites `skills/query-the-model.md` or `skills/learned-mdl-preflight.md` without that heading, which is every CLAUDE.md mxcli init v0.25 writes, grep's exit 1 ended the script with no message. Every step after it never ran: the crash-net refresh, the tests/e2e install and the lint-rule restore. Introduced by 9a0350b (2026-09-18). Now `|| true`, and `ledger_row_prefix` gets the same guard. Field: three consuming projects (TramiusECI, TramiusSCR, TramiusSVC, 2026-10-07): the dry run went from exit 1 after "Would rewrite: CLAUDE.md" to exit 0 listing 7 and 8 skipped `bin/` refreshes. New fixture `tests/wave2/test-sync-dup-heading-exit.sh` (4 of 6 fail on the pre-fix script). — TramiusECI session
  perf/faster-ui-loop
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/bin/sync-project.sh b/bin/sync-project.sh
index 0b5be28c..d2cf58ae 100755
--- a/bin/sync-project.sh
+++ b/bin/sync-project.sh
@@ -752,7 +752,10 @@ fi
 LEDGER_ROW_RE='bug-logs/mxcli-bugs\.md'
 # ledger_row_prefix <file> — the path prefix the retired row's cell carried ('' when relative).
 ledger_row_prefix() {
-  grep -m1 "^|.*$LEDGER_ROW_RE" "$1" | sed -n 's/.*[|` ]\([^|` ]*\)bug-logs\/mxcli-bugs\.md.*/\1/p'
+  # `|| true`: both callers only reach here after a grep for the same row matched, but a
+  # no-match under pipefail + errexit would end the whole sync with no message (see the
+  # _dup_from_line note in section 3) — never leave that to the callers.
+  grep -m1 "^|.*$LEDGER_ROW_RE" "$1" | sed -n 's/.*[|` ]\([^|` ]*\)bug-logs\/mxcli-bugs\.md.*/\1/p' || true
 }
 LEDGER_ROWS_BEFORE=0
 [ -f "$CL" ] && LEDGER_ROWS_BEFORE="$(grep -c "^|.*$LEDGER_ROW_RE" "$CL" 2>/dev/null || true)"
@@ -899,7 +902,11 @@ if [ -f "$PROJECT_DIR/CLAUDE.local.md" ]; then
   # a flat assertion. Same rule as the ledger-row warn above: CLAUDE.md is bootstrap-project.md's
   # (an LLM merge), not this script's, so sync never edits it — only names the fix.
   if [ -f "$PROJECT_DIR/CLAUDE.md" ] && grep -qE 'skills/(learned-mdl-preflight|query-the-model)\.md' "$PROJECT_DIR/CLAUDE.md"; then
-    _dup_from_line="$(grep -n 'mxcli-project-toolkit Integration' "$PROJECT_DIR/CLAUDE.md" | head -1 | cut -d: -f1)"
+    # `|| true`: no heading is the COMMON case (every CLAUDE.md mxcli init v0.25 writes cites
+    # the skills without it). Unguarded, grep's exit 1 fails the pipeline under pipefail and
+    # errexit ended the whole sync here, silently, before the bin/ and tests/e2e refresh —
+    # every sync from 9a0350b (2026-09-18) to this fix. Regression: tests/wave2/test-sync-dup-heading-exit.sh.
+    _dup_from_line="$(grep -n 'mxcli-project-toolkit Integration' "$PROJECT_DIR/CLAUDE.md" | head -1 | cut -d: -f1 || true)"
     if [ -n "$_dup_from_line" ]; then
       _dup_words="$(tail -n "+$_dup_from_line" "$PROJECT_DIR/CLAUDE.md" | wc -w | tr -d ' ')"
     else
diff --git a/tests/wave2/test-sync-dup-heading-exit.sh b/tests/wave2/test-sync-dup-heading-exit.sh
new file mode 100755
index 00000000..4aaedd33
--- /dev/null
+++ b/tests/wave2/test-sync-dup-heading-exit.sh
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Fixture for sync-project.sh exiting 1, silently, in its CLAUDE.md duplicate-routing check when
+# CLAUDE.md cites a Baseline-only skill (skills/query-the-model.md) but has NO
+# "mxcli-project-toolkit Integration" heading — the shape every CLAUDE.md written by mxcli init
+# v0.25 has. `grep -n heading | head | cut` returned grep's exit 1 through pipefail, errexit ended
+# the script, and every step after it (bin/ crash-net refresh, tests/e2e install, lint rules)
+# never ran. Field: three consuming projects (TramiusECI/SCR/SVC), every sync since 9a0350b.
+#
+# Run against the pre-fix script and T1-T3 must fail (exit 1, no bin/ line, no summary).
+#
+# Every fixture is built by the REAL bin/init-project.sh, under /tmp. No real project is touched.
+#
+# usage: test-sync-dup-heading-exit.sh /path/to/bin/sync-project.sh
+export MXTK_LEAKGUARD_DENYFILE="${TMPDIR:-/tmp}/mxtk-fixture-denylist.$$"
+export MXTK_SYNC_SKIP_CLONE_CHECK=1
+
+set -uo pipefail
+
+SYNC="${1:?usage: test-sync-dup-heading-exit.sh /path/to/sync-project.sh}"
+case "$SYNC" in /*) ;; *) SYNC="$PWD/$SYNC" ;; esac
+TK="$(cd "$(dirname "$SYNC")/.." && pwd)"
+INIT="$TK/bin/init-project.sh"
+WORK="$(mktemp -d /tmp/dupheading.XXXXXX)"
+trap 'rm -f "$MXTK_LEAKGUARD_DENYFILE"; rm -rf "$WORK"' EXIT
+PASS=0; FAIL=0
+
+ok()  { PASS=$((PASS+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAIL=$((FAIL+1)); printf '  FAIL %s\n' "$1"; [ -n "${2:-}" ] && printf '%s\n' "$2" | sed 's/^/  FAIL-detail: /'; }
+
+mkproj() {
+  d="$WORK/$1"; mkdir -p "$d"; : > "$d/Fixture.mpr"
+  MXTK_NO_GUIDE=1 "$INIT" "$d" >/dev/null 2>&1
+  [ -f "$d/CLAUDE.local.md" ] && [ -f "$d/bin/exec.sh" ] || { echo "FIXTURE ERROR: init did not scaffold $d"; exit 2; }
+  echo "$d"
+}
+
+# --- no heading: the case that died -----------------------------------------------------
+P="$(mkproj noheading)"
+grep -q 'mxcli-project-toolkit Integration' "$P/CLAUDE.md" && { echo "FIXTURE ERROR: init's CLAUDE.md already has the heading"; exit 2; }
+printf '\nRead skills/query-the-model.md before asking the user.\n' >> "$P/CLAUDE.md"
+rm -f "$P/bin/exec.sh"     # something the bin/ step, past the check, must report
+OUT="$("$SYNC" "$P" --dry-run 2>&1)"; RC=$?
+[ "$RC" -eq 0 ] && ok "T1 no heading: sync exits 0" || bad "T1 no heading: sync exits 0 (got $RC)" "$(printf '%s\n' "$OUT" | tail -5)"
+printf '%s\n' "$OUT" | grep -q 'Would install: bin/exec.sh' \
+  && ok "T2 no heading: the bin/ step past the check still runs" \
+  || bad "T2 no heading: the bin/ step past the check still runs" "$(printf '%s\n' "$OUT" | tail -5)"
+printf '%s\n' "$OUT" | grep -qE 'artifact\(s\) would be updated|All copied artifacts up to date' \
+  && ok "T3 no heading: sync reaches its summary line" \
+  || bad "T3 no heading: sync reaches its summary line"
+printf '%s\n' "$OUT" | grep -q 'cites Baseline-only skills' \
+  && ok "T4 no heading: the duplicate-routing warning is still raised" \
+  || bad "T4 no heading: the duplicate-routing warning is still raised"
+
+# --- heading present: the case the check was written for keeps working ------------------
+P2="$(mkproj withheading)"
+printf '\n## mxcli-project-toolkit Integration\n\nRead skills/query-the-model.md first.\n' >> "$P2/CLAUDE.md"
+OUT2="$("$SYNC" "$P2" --dry-run 2>&1)"; RC2=$?
+[ "$RC2" -eq 0 ] && ok "T5 heading: sync exits 0" || bad "T5 heading: sync exits 0 (got $RC2)"
+printf '%s\n' "$OUT2" | grep -qE 'section \(~[0-9]+ word' \
+  && ok "T6 heading: warning sizes the section" \
+  || bad "T6 heading: warning sizes the section"
+
+echo ""
+echo "test-sync-dup-heading-exit: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

From adc2203452bfb58614acb5461cd3f42c2680405f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 11:59:16 +0000
Subject: [PATCH 08/19] fix(init): local by default, park the Dev Container
 mxcli writes

`mxcli new` / `mxcli init` always writes `.devcontainer/`, and VS Code then offers (and
remembers) "Reopen in Container". A first-time user followed the docs on 2026-10-08 and
landed inside that container with "claude: command not found" (the template installs
claude to ~/.local/bin and never adds it to PATH) and a fresh Claude login prompt, then
asked how to get rid of the container. Local use was always the intent.

- init-project.sh moves `.devcontainer/` to `.mxtk-backup/devcontainer-<stamp>` unless
  MXTK_KEEP_DEVCONTAINER=1. Nothing deleted, idempotent, probed on a scratch project.
- README: "say no" to the reopen prompt, how to get back out, the lane stays opt-in.
- CHANGELOG line under Unreleased.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md        |  1 +
 README.md           | 15 ++++++++-------
 bin/init-project.sh | 15 +++++++++++++++
 3 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..a217e483 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(init): **local by default, no Dev Container.** `init-project.sh` now parks the `.devcontainer/` that `mxcli new`/`init` always writes under `.mxtk-backup/` (keep it with `MXTK_KEEP_DEVCONTAINER=1`), and the README says "say no" to VS Code's reopen prompt. Field incident 2026-10-08: a first-time user followed the docs and landed in the container with "claude: command not found" (the template installs `claude` to `~/.local/bin` and never puts it on PATH) and a fresh login prompt. Local use was always the intent. — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/README.md b/README.md
index 120e7d90..04230061 100644
--- a/README.md
+++ b/README.md
@@ -111,13 +111,14 @@ network hop with path translation on every file argument. The toolkit does none
 Git Bash runs where Studio Pro, `mxcli` and your model already live, and ships with Git for
 Windows. `doctor.sh` detects WSL and warns.
 
-**This is about the shell you type in, not about Docker.** Docker Desktop on Windows runs its
-engine on a WSL2 backend, and VS Code will offer to "install Docker on WSL" the first time you
-reopen an `mxcli new` project in its Dev Container — say yes. That is the `devcontainer` lane
-(`CONVERSION-RUNBOOK.md` → *Where you run this*), headless and fully supported; `doctor.sh`
-detects it and records it. The warning above applies only when you run the toolkit's scripts
-*yourself* from a WSL prompt against a Studio Pro on the Windows side. Real question, 2026-09-07:
-"the toolkit says not WSL, but `mxcli new`'s Dev Container wants Docker on WSL — yes or no?" Yes.
+**This is about the shell you type in, not about Docker.** `mxcli new` writes a `.devcontainer/`
+and VS Code then offers to "Reopen in Container" — **say no, work locally.** The container is a
+second machine (no `claude` login, no dotfiles, a fragile install step), and the toolkit's path
+is plain local use: `bin/init-project.sh` parks that folder under `.mxtk-backup/` so the prompt
+stops. If you already clicked yes: F1 → "Dev Containers: Reopen Folder Locally", nothing is lost.
+Real incident, 2026-10-08: a first-time user landed in the container with "claude: command not
+found" and a fresh login prompt. The `devcontainer` lane in `CONVERSION-RUNBOOK.md` stays
+supported for those who want it (`MXTK_KEEP_DEVCONTAINER=1`), it is just not the default.
 
 **The lanes mix freely on one project.** Do the headless stages in the Dev Container, then open
 the same `.mpr` in Studio Pro from Git Bash for the steps MDL cannot express and UI polish, and go back.
diff --git a/bin/init-project.sh b/bin/init-project.sh
index 4c6b2269..f0056183 100755
--- a/bin/init-project.sh
+++ b/bin/init-project.sh
@@ -689,6 +689,21 @@ else
   echo "  $DENYFILE by hand, or this project's name is invisible to the guard."
 fi
 
+# --- no Dev Container ----------------------------------------------------------------
+# `mxcli new` / `mxcli init` always writes `.devcontainer/`, and VS Code then offers (and later
+# remembers) "Reopen in Container". That container is a second machine: no `claude` login, no
+# dotfiles, and its install step is fragile. The toolkit's path is plain local use, so the
+# folder is moved aside here. Real incident, 2026-10-08: a first-time user landed in the
+# container with "claude: command not found" and a fresh login prompt, and asked how to get
+# rid of it. Keep it with MXTK_KEEP_DEVCONTAINER=1. Nothing is deleted: the folder is parked
+# under .mxtk-backup/ so it can be restored by hand.
+if [ -d "$PROJECT_DIR/.devcontainer" ] && [ -z "${MXTK_KEEP_DEVCONTAINER:-}" ]; then
+  mkdir -p "$PROJECT_DIR/.mxtk-backup"
+  mv "$PROJECT_DIR/.devcontainer" "$PROJECT_DIR/.mxtk-backup/devcontainer-$(date +%Y%m%d-%H%M%S)"
+  echo "Moved .devcontainer/ to .mxtk-backup/ — work locally; VS Code will not ask to reopen in a container."
+  echo "  (MXTK_KEEP_DEVCONTAINER=1 keeps it.)"
+fi
+
 GUIDE="$SCRIPT_DIR/../toolkit-guide.html"
 # First-touch sentinel. This is the same file every agent must test before opening the guide
 # (see CLAUDE.md "First-touch rule"); writing it here is what stops the next session — and the

From df42f3b70d8b3a2b7886bdf2980d70e0e7d423a7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 12:40:25 +0000
Subject: [PATCH 09/19] =?UTF-8?q?docs(lint):=20process/lint-backlog.md=20?=
 =?UTF-8?q?=E2=80=94=20the=20lint=20rollout=20plan,=20on=20disk?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Twelve rule candidates mined from skills/, each with the evidence it rests on, the catalog
field it needs and a status; five rollout rules (two or three rules per PR, ship as warning,
one field run before merge, promote after two clean projects, blind rules say so); what is
not lintable and lives in a skill instead; four brain contradictions to settle before the
rules that touch them. Linked from lint-rules/README.md. Until today this plan existed only
in chat.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md            |  1 +
 lint-rules/README.md    |  2 +
 process/lint-backlog.md | 94 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+)
 create mode 100644 process/lint-backlog.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..2d0d412c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- docs(lint): **`process/lint-backlog.md` — the lint rollout plan, on disk.** Twelve rule candidates mined from `skills/` with the evidence each rests on, the catalog field each needs, and five rollout rules (two or three rules per PR, ship as warning, one field run before merge, promote after two clean projects, blind rules say so). Plus what is not lintable and lives in a skill (theme, logging, scheduled events) and four brain contradictions to settle first. Until today this plan existed only in chat. — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/lint-rules/README.md b/lint-rules/README.md
index c6182c00..8d675e63 100644
--- a/lint-rules/README.md
+++ b/lint-rules/README.md
@@ -28,6 +28,8 @@ are excluded at the gate (`bin/lint-gate.sh -e`, from a per-project
 version this directory shipped on 11 Aug: one violation per microflow instead of one per
 activity, plus four action types allowlisted. On PROJECT-C that is 399 rows -> 51 findings.
 
+Candidates that are not rules yet, and the order they ship in: `process/lint-backlog.md`.
+
 ## A rule that matches nothing now says so
 
 `CONV010` and `CONV020` can only identify a page action by its name — `refs_to()` reports the
diff --git a/process/lint-backlog.md b/process/lint-backlog.md
new file mode 100644
index 00000000..e5f0503d
--- /dev/null
+++ b/process/lint-backlog.md
@@ -0,0 +1,94 @@
+# Lint backlog — best practices the brain already knows, turned into rules one batch at a time
+
+**Created:** 2026-10-08
+**Purpose:** the single list of lint-rule candidates, where each came from, what blocks it, and
+where it is in the rollout. Chat is where this plan lived until today; this file is where it lives
+now. Every rule PR links a row here and moves it.
+
+## Why rules at all
+
+A skill is read by whoever happens to load it; a rule runs on every model, every time, and says a
+number. `lint-rules/README.md` has the mechanics (header, blindness finding, how rules reach a
+project). This file has the *what* and the *order*.
+
+## Rollout rules
+
+1. **Two or three rules per PR**, never a pack. Each with Starlark unit fixtures under
+   `tests/lint-rules/` (the UX001/UX002 suite is the template), so the logic is proven before the
+   rule meets a model.
+2. **Ships as a warning.** A new rule runs at warning severity on its first projects. The gate
+   fails only on errors, so a noisy rule produces counts, not blocked sessions.
+3. **One field run before merge.** The rule runs on one real model; the PR cites the count and
+   three sample findings. Vocabulary (field names, type strings) is probed there, never assumed —
+   see "Probe, don't trust" in `lint-rules/README.md`.
+4. **Promote after two clean projects.** Warning becomes error, the README row moves from
+   *candidate* to *proven*.
+5. **Blind rules say so.** Every rule emits a `_rule` finding when its probe fails; the gate reports
+   it. A rule that silently matches nothing is the one defect this whole effort exists to prevent.
+
+## Status legend
+
+`idea` → `drafted` (PR open, fixtures pass) → `warning` (merged, on first projects) → `proven`
+(error severity) · `blocked: <why>` · `skill` (not lintable, lives in a skill instead)
+
+## Batch 1 — incident evidence and known catalog fields
+
+| # | Rule | Category | Evidence | Needs | Status |
+|---|---|---|---|---|---|
+| 1 | Error silently swallowed: activity error handling set to continue/custom and no Log activity in the flow | quality | `learned-microflow-patterns.md` error-handling rules; CONV013/014 cover only the *presence* of handling on external calls | `error_handling_type` value strings (probe) | idea |
+| 2 | Inline `style` on a widget, or a class not present in the compiled design system | design | `learned-css-that-never-applied.md`, `learned-stylegallery.md` (real: an entire app rendered unstyled) | `style`, `class_name`; class list from `themesource/<module>/web/main.scss` via config | idea |
+| 3 | Page or `ACT_` flow with no entry point (QUAL004 exempts `ACT_`) | quality | `wiring-sweep.md`, obligation check "wiring" | `refs_from` / refs table | idea |
+| 4 | Retrieve, delete, REST or Java call inside a loop body (CONV011 covers commit only) | performance | `microflow-loop-antipatterns.md` | `parent_loop_id` / `loop_depth` actually populated (brain says activities were flat 2026-09-15 — probe) | idea |
+
+## Batch 2 — strong evidence, one unconfirmed field each
+
+| # | Rule | Category | Evidence | Needs | Status |
+|---|---|---|---|---|---|
+| 5 | Page-triggered external call left on default rollback handling, no handler | quality | same as 1 | `error_handling_type` | idea |
+| 6 | Custom error handler that neither logs nor gives feedback | quality | `learned-popup-feedback-pattern.md` | `error_handling_type`, `log_*` | idea |
+| 7 | Page-triggered commit or delete without refresh | correctness | `learned-page-patterns.md` | refresh flag on commit (unconfirmed) | blocked: field unconfirmed |
+| 8 | DataGrid 2 database source without a sort | correctness | `learned-dg2-patterns.md` | datasource sort in projection (unconfirmed) | blocked: field unconfirmed |
+| 9 | Page top container missing the shell/page-column class | design | `ui-preflight-pages.md`, `oneshot-page-structure-patterns.md` | `class_name`, `depth`; class name per project config | idea |
+
+## Batch 3 — security and navigation
+
+| # | Rule | Category | Evidence | Needs | Status |
+|---|---|---|---|---|---|
+| 10 | Module role mapped to no user role (CONV008 checks the reverse) | security | `security-is-not-a-later-script.md` | roles in projection | idea |
+| 11 | Widget-bound entity with zero access rules at production level | security | SEC001 variant scoped to entities pages actually touch | entity access in projection | idea |
+| 12 | Navigation item without icon | design | `learned-sidebar-collapse-icons.md` | navigation in projection (unconfirmed) | blocked: field unconfirmed |
+
+## Cheap extras (one afternoon each, when a batch has room)
+
+Microflow not in a folder · non-persistent entity committed to the database · many-to-many
+without a junction entity · `VAL_` flow not returning Boolean · log level ERROR with an empty
+message · error handler that only re-raises.
+
+## Not lintable from the catalog — lives in a skill, maybe a shell check
+
+| Topic | Where | Check |
+|---|---|---|
+| Theme: never edit `themesource/atlas_core`, overrides in the app theme or one UI module; variables over literals in SCSS | `design-artifacts.md` (to add) | grep for hex literals outside `custom-variables.scss`; diff of `atlas_core` against the shipped version |
+| Theme: design properties over free-text classes; must exist in `design-properties.json` (CE6083) | `learned-mdl-preflight.md` row 24 | already a STOP row |
+| Logging conventions: node name = module, message codes | `mdl-cookbook-microflows.md` | prose; rule 1 above covers the absence |
+| Scheduled events: idempotent, batched, disabled per environment | nothing yet | `app-analysis.md` counts them; best practice to write |
+| Localization: hard-coded captions | nothing yet | needs a research pass first |
+
+## Brain contradictions to settle before the rule that touches them
+
+- Sidebar caption-less vs icon+label: `learned-page-patterns.md` vs `learned-sidebar-collapse-icons.md` (blocks 12).
+- Empty state required (`ui-preflight-pages.md`) vs MDL cannot write one (`learned-mdl-cannot-express.md`).
+- `_Dto` suffix standard vs avoid Dto, both in `learned-microflow-patterns.md`.
+- mxbuild blind to grants (`iterative-build-loop.md`) vs CE0106 (`learned-file-upload-widget.md`).
+
+## Still to research (not needed to start)
+
+Mendix's own published rule set (Application Quality Monitor), its performance and
+error-handling pages, naming conventions. Output: a mapping table against the ids above and
+a second backlog section. Forum only to weight by incident frequency.
+
+## History
+
+- 2026-10-08 — file created from the UX001/UX002 work and a brain scan of `skills/`; no rule from
+  this list exists yet. UX001/UX002 themselves are `drafted` (PR open, 35 unit cases, field run
+  pending).

From 1cd17d09561f525852d787e9c34c7049f9885f0f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 13:35:18 +0000
Subject: [PATCH 10/19] new(lint): gate writes a per-run ledger; lint-trend.sh
 reads it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

project-bin/lint-gate.sh appends one row per rule per run to
.claude/loop/lint-ledger.tsv (ts, verdict, rule, count, severity, blind,
plus a _run row with the total). New project-bin/lint-trend.sh prints per
rule: runs fired in, first/last count with dates, best/worst, blind runs,
up/down/flat; --rule <id> for one series, --runs for the run rows.

Why: lint-baseline.json records the count that was accepted, not what each
run saw, so "did the rule we shipped catch anything, and did the count go
down" had no answer. The lint rollout plan's "promote after two clean
projects" step needs exactly that.

Probe: the gate's own parser on a crafted lint result (3 findings, one
blind rule) — ledger rows and trend output as expected, lint-last.json and
the ratchet verdict unchanged. check-portability and check-scripts clean.
Field run on a real model still owed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                      |   1 +
 bin/lib/install-manifest.sh       |   2 +-
 project-bin/lint-gate.sh          |  36 +++++++++-
 project-bin/lint-trend.sh         | 109 ++++++++++++++++++++++++++++++
 skills/lint-that-actually-runs.md |  10 +++
 5 files changed, 156 insertions(+), 2 deletions(-)
 create mode 100755 project-bin/lint-trend.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..2f1aff99 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- new(lint): **the lint gate keeps a ledger, so a rule's history is readable.** `project-bin/lint-gate.sh` appends one row per rule per run to `.claude/loop/lint-ledger.tsv` (ts, verdict, rule, count, severity, blind — plus a `_run` row with the total), and new `project-bin/lint-trend.sh` prints per rule: runs fired in, first/last count with dates, best/worst, blind runs, and up/down/flat (`--rule <id>` for one rule's series, `--runs` for the run rows). Until now the only per-rule history was `lint-baseline.json` in git, which records the count that was accepted, not what each run saw — so "did the rule we shipped catch anything, and did it go down" had no answer. This is the measurement the lint rollout plan's "promote after two clean projects" step depends on. Probed on the gate's own parser with a crafted lint result (3 findings, one blind rule): ledger rows and trend output as expected; `lint-last.json` and the ratchet verdict unchanged. Field run on a real model still owed (laptop). — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/bin/lib/install-manifest.sh b/bin/lib/install-manifest.sh
index 4bb29c67..3b831d7d 100644
--- a/bin/lib/install-manifest.sh
+++ b/bin/lib/install-manifest.sh
@@ -110,7 +110,7 @@ MXTK_AGENTS_STAGE_BUILD="mdl-agent.md gate-agent.md test-agent.md review-agent.m
 # own sibling, and the PostToolUse(Read) hook install-claude-permissions.sh writes runs
 # `bash bin/look-ledger.sh seen`. Two unattended builds built every page and opened no
 # screenshot of one; the Stage 5 gate now joins what this script records.
-MXTK_PROJECT_BIN="assemble-prototype.js prototype-route.js check-prototype-links.js wf-add-path-terminators.py wf-set-call-captions.py mxunit_bson.py _common.sh app-facts.sh _claims.sh snapshot-mpr.sh restore-mpr.sh exec.sh look-ledger.sh save-sp.sh restart-sp.sh check-sp-health.sh verify-module.sh test-stack-up.sh fixture-manifest.sh check-root-clean.sh lint-gate.sh close-task.sh conformance-check.sh coverage-preflight.sh graph-sweep.sh review-module.sh coherence-cadence.sh build-plan-status.sh done-drift-check.sh page-scope.sh render-improvement-register.sh check-design-portability.sh check-design-reaches-app.sh check-page-shell.sh page-fidelity.js model-stamp.sh verify-model.sh install-project-hooks.sh session-check.sh constants-audit.sh context-pack.sh"
+MXTK_PROJECT_BIN="assemble-prototype.js prototype-route.js check-prototype-links.js wf-add-path-terminators.py wf-set-call-captions.py mxunit_bson.py _common.sh app-facts.sh _claims.sh snapshot-mpr.sh restore-mpr.sh exec.sh look-ledger.sh save-sp.sh restart-sp.sh check-sp-health.sh verify-module.sh test-stack-up.sh fixture-manifest.sh check-root-clean.sh lint-gate.sh lint-trend.sh close-task.sh conformance-check.sh coverage-preflight.sh graph-sweep.sh review-module.sh coherence-cadence.sh build-plan-status.sh done-drift-check.sh page-scope.sh render-improvement-register.sh check-design-portability.sh check-design-reaches-app.sh check-page-shell.sh page-fidelity.js model-stamp.sh verify-model.sh install-project-hooks.sh session-check.sh constants-audit.sh context-pack.sh"
 
 # Files in project-bin/ that are deliberately NOT installed into projects. The reverse check
 # below flags anything named by NEITHER list, so a new file in project-bin/ has to be either
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index a2e7069c..dca90311 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -18,7 +18,8 @@
 #
 # Exit codes: 0 clean or unchanged · 1 a rule increased · 2 could not run
 #
-# PRODUCES .claude/loop/lint-last.json on every run that actually gets as far as computing
+# PRODUCES .claude/loop/lint-ledger.tsv (append-only, one row per rule per run; read with
+# project-bin/lint-trend.sh) and .claude/loop/lint-last.json on every run that actually gets as far as computing
 # counts (timestamp, verdict, total, per-rule counts) — the dir is created if absent. This is
 # NOT docs/BUILD-LOG.md (the exec table Studio's parseExecRows / bin/status.sh /
 # project-bin/done-drift-check.sh parse) and must never become another writer of it; it is a
@@ -155,6 +156,39 @@ def write_last(verdict, viol_list, counts_now):
         open(last_path, "a").write("\n")
     except OSError as e:
         print("lint-gate: could not write %s: %s" % (last_path, e), file=sys.stderr)
+    write_ledger(verdict, viol_list, counts_now)
+
+# LEDGER. lint-last.json is overwritten every run, so it can answer "what did lint say last
+# time" and nothing else. The ledger is append-only: one row per rule per run, so a rule's
+# count can be read ACROSS runs — did the thing we shipped ever fire, and did its count go
+# down once people saw it. That is the question the rollout plan in process/lint-backlog.md
+# asks before promoting a warning to an error ("two clean projects"), and until this file
+# existed nobody could answer it without a git archaeology of lint-baseline.json.
+#
+#   .claude/loop/lint-ledger.tsv   ts  verdict  rule  count  severity  blind
+#
+# `blind` is 1 when the rule emitted a `_rule` finding that run (it inspected nothing), so a
+# zero next to a 1 is never read as clean. Rules with zero findings are NOT written: a rule's
+# absence on a date means "ran, found nothing" only if the run row (rule `_run`) is there —
+# which it always is, carrying the total. Read it with project-bin/lint-trend.sh.
+def write_ledger(verdict, viol_list, counts_now):
+    try:
+        loop_dir = os.path.join(os.path.dirname(base_path), "loop")
+        os.makedirs(loop_dir, exist_ok=True)
+        ledger = os.path.join(loop_dir, "lint-ledger.tsv")
+        ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        blind_rules = {v["ruleId"] for v in viol_list if v.get("module") == "_rule"}
+        sev_now = {v["ruleId"]: v.get("severity", "") for v in viol_list}
+        new_file = not os.path.exists(ledger)
+        with open(ledger, "a") as f:
+            if new_file:
+                f.write("ts\tverdict\trule\tcount\tseverity\tblind\n")
+            f.write("%s\t%s\t_run\t%d\t\t%d\n" % (ts, verdict, len(viol_list), 1 if blind_rules else 0))
+            for r in sorted(counts_now):
+                f.write("%s\t%s\t%s\t%d\t%s\t%d\n" % (
+                    ts, verdict, r, counts_now[r], sev_now.get(r, ""), 1 if r in blind_rules else 0))
+    except OSError as e:
+        print("lint-gate: could not append %s: %s" % (ledger, e), file=sys.stderr)
 
 # mxcli prints a plaintext progress banner before the JSON; slice from the first brace.
 raw = open(out_path).read()
diff --git a/project-bin/lint-trend.sh b/project-bin/lint-trend.sh
new file mode 100755
index 00000000..fb22fb67
--- /dev/null
+++ b/project-bin/lint-trend.sh
@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# lint-trend.sh — did a lint rule ever fire here, and is its count going down?
+#
+# Reads the append-only ledger project-bin/lint-gate.sh writes on every run
+# (.claude/loop/lint-ledger.tsv: ts, verdict, rule, count, severity, blind) and prints one
+# line per rule: runs it fired in, first and last count with dates, best and worst, and how
+# many of those runs it was blind (a `_rule` self-check finding — it inspected nothing).
+#
+# This is the evidence the rollout plan (process/lint-backlog.md) asks for before a warning
+# becomes an error: a rule that fired and whose count fell is doing its job; a rule that
+# never fired is either clean here or wrong, and the blind column says which. Without this
+# file the only trace of a rule's history was lint-baseline.json in git, which records the
+# count that was ACCEPTED, not what each run saw.
+#
+# Usage:
+#   project-bin/lint-trend.sh              # one line per rule, worst first
+#   project-bin/lint-trend.sh --rule UX001 # every run's count for one rule, oldest first
+#   project-bin/lint-trend.sh --runs       # the run rows only (ts, verdict, total, blind)
+#
+# Exit 0 with output; 2 when there is no ledger yet (the gate has never run here). Read-only.
+# Keep bash-3.2 compatible.
+
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LEDGER="$ROOT/.claude/loop/lint-ledger.tsv"
+
+if [ -f "$(dirname "${BASH_SOURCE[0]}")/_common.sh" ]; then
+  . "$(dirname "${BASH_SOURCE[0]}")/_common.sh"
+fi
+if ! type require_py >/dev/null 2>&1; then
+  require_py() {
+    _c=""
+    for _c in python3 python py; do  # portability-ok: this IS the interpreter probe
+      case "$(command -v "$_c" 2>/dev/null)" in *[Ww]indows[Aa]pps*) continue ;; esac
+      if "$_c" -c 'import sys; sys.exit(0 if sys.version_info[0] == 3 else 1)' >/dev/null 2>&1; then
+        PY="$_c"; export PY; return 0
+      fi
+    done
+    echo "lint-trend: Python 3 is required and was not found (tried python3, python, py)." >&2  # portability-ok: names in a diagnostic
+    exit 2
+  }
+fi
+require_py
+
+MODE="rules"; RULE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --rule) MODE="one"; RULE="${2:-}"; [ -n "$RULE" ] || { echo "lint-trend: --rule needs an id" >&2; exit 2; }; shift ;;
+    --runs) MODE="runs" ;;
+    -h|--help) sed -n '2,22p' "$0"; exit 0 ;;
+    *) echo "lint-trend: unknown argument $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+if [ ! -f "$LEDGER" ]; then
+  echo "lint-trend: no ledger at $LEDGER — the lint gate has not run here yet (project-bin/lint-gate.sh writes it)." >&2
+  exit 2
+fi
+
+LEDGER="$LEDGER" MODE="$MODE" RULE="$RULE" "$PY" - <<'PY'
+import csv, os, sys
+rows = []
+with open(os.environ["LEDGER"]) as f:
+    for r in csv.DictReader(f, delimiter="\t"):
+        try:
+            r["count"] = int(r["count"]); r["blind"] = int(r.get("blind") or 0)
+        except ValueError:
+            continue
+        rows.append(r)
+mode, want = os.environ["MODE"], os.environ["RULE"]
+
+if mode == "runs":
+    print("%-20s %-18s %6s %s" % ("ts", "verdict", "total", "blind"))
+    for r in rows:
+        if r["rule"] == "_run":
+            print("%-20s %-18s %6d %s" % (r["ts"], r["verdict"], r["count"], "yes" if r["blind"] else ""))
+    sys.exit(0)
+
+runs = [r for r in rows if r["rule"] == "_run"]
+if mode == "one":
+    hits = [r for r in rows if r["rule"] == want]
+    if not hits:
+        print("%s: never fired in %d run(s) here." % (want, len(runs)))
+        sys.exit(0)
+    print("%-20s %6s %-8s %s" % ("ts", "count", "severity", "blind"))
+    for r in hits:
+        print("%-20s %6d %-8s %s" % (r["ts"], r["count"], r["severity"], "yes" if r["blind"] else ""))
+    sys.exit(0)
+
+by = {}
+for r in rows:
+    if r["rule"] == "_run":
+        continue
+    by.setdefault(r["rule"], []).append(r)
+if not by:
+    print("No rule has fired in %d run(s) here." % len(runs))
+    sys.exit(0)
+print("%d run(s), first %s, last %s" % (len(runs), runs[0]["ts"][:10] if runs else "?", runs[-1]["ts"][:10] if runs else "?"))
+print("%-10s %-8s %5s %-18s %-18s %5s %5s %s" % ("rule", "severity", "runs", "first", "last", "best", "worst", "blind"))
+for rule, hs in sorted(by.items(), key=lambda kv: -kv[1][-1]["count"]):
+    counts = [h["count"] for h in hs]
+    trend = "" if len(hs) < 2 else ("  down" if counts[-1] < counts[0] else ("  UP" if counts[-1] > counts[0] else "  flat"))
+    blind = sum(h["blind"] for h in hs)
+    print("%-10s %-8s %5d %-18s %-18s %5d %5d %s%s" % (
+        rule, hs[-1]["severity"], len(hs),
+        "%d @ %s" % (counts[0], hs[0]["ts"][:10]), "%d @ %s" % (counts[-1], hs[-1]["ts"][:10]),
+        min(counts), max(counts), ("%d BLIND" % blind) if blind else "", trend))
+PY
diff --git a/skills/lint-that-actually-runs.md b/skills/lint-that-actually-runs.md
index ed2c7195..ab304477 100644
--- a/skills/lint-that-actually-runs.md
+++ b/skills/lint-that-actually-runs.md
@@ -111,6 +111,16 @@ all the same order of magnitude, and no project produced a single real error-sev
 the ratchet is the *only* mechanism available. `project-bin/lint-gate.sh` implements it
 (`--update-baseline` to accept current counts).
 
+**The ratchet remembers one number per rule; the ledger remembers every run.** Every gate run
+appends one row per rule to `.claude/loop/lint-ledger.tsv` (timestamp, verdict, rule, count,
+severity, blind), and `project-bin/lint-trend.sh` reads it back: runs a rule fired in, first and
+last count with dates, best/worst, and how many runs it was blind. That is the answer to "did
+the rule we shipped ever catch anything here, and did the count go down once people saw it" —
+the evidence `process/lint-backlog.md` asks for before a warning becomes an error. A rule that
+never appears in the ledger is clean here *or* wrong; `--rule <id>` and the blind column say
+which. Before this file existed the only history was `lint-baseline.json` in git, which records
+the count that was *accepted*, not what each run saw.
+
 ## Two false-pass bugs already designed out of `lint-gate.sh` — keep them out
 
 Both were found by testing the gate, not by reading it:

From 5971577b3b462f8058766e723a499066d8ea8347 Mon Sep 17 00:00:00 2001
From: MendixMau <mauritscgvisser@gmail.com>
Date: Thu, 8 Oct 2026 22:07:51 +0800
Subject: [PATCH 11/19] skills: promote e2e-locators-that-lie (four Playwright
 harness defects on Mendix pages)

Four measured defects (2026-09-17, user-group administration module) where
the Playwright harness reported a defect in the app: widget name unique per
page not per DOM, forced click on a tab swallowed without throwing, grid
re-render after the response not the click, fixture literal written by the
reset script. Routed test/review at Stages 5-6 (diagnose), pointer from
e2e-harness-base.md, CHANGELOG line in this commit. The shipped runner does
not yet apply rules 1-3; the skill states that and the runner is unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CHANGELOG.md                    |   1 +
 README.md                       |   1 +
 ROUTING.md                      |   1 +
 agents/review-agent.md          |   1 +
 agents/test-agent.md            |   1 +
 bin/gate-check.sh               |   4 +-
 bin/lib/skill-routing.tsv       |   1 +
 skills/e2e-harness-base.md      |   1 +
 skills/e2e-locators-that-lie.md | 121 ++++++++++++++++++++++++++++++++
 9 files changed, 130 insertions(+), 2 deletions(-)
 create mode 100644 skills/e2e-locators-that-lie.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..33ca0da6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- learn(test): **`skills/e2e-locators-that-lie.md`** — four Playwright harness defects that report a defect in the app: a widget name is unique per page not per DOM (hidden tab pane first, so `.first()` drives or asserts the wrong node), `click({force:true})` on a Mendix tab is swallowed and never throws (so force-then-plain fallback is dead), a grid re-renders on the response not the click (single-read text assertions race), and a fixture literal the reset script writes measures only the reset. Measured 2026-09-17 on a user-group administration module; routed for test/review at Stages 5–6 (diagnose), pointer from `e2e-harness-base.md`. The shipped `project-tests/e2e/journey-runner.js` does not yet apply rules 1–3; the skill says so. — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/README.md b/README.md
index 120e7d90..75a62ce4 100644
--- a/README.md
+++ b/README.md
@@ -674,6 +674,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini
 | Task | Skill to load |
 |---|---|
 | Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words | `bug-logs/mxcli-bugs.md` |
+| An e2e rung reports a UI defect (widget never appeared, click did nothing, screen contradicts the data, fixture count wrong) — check the locator before blaming the app: :visible, click order, poll, derived fixtures | `skills/e2e-locators-that-lie.md` |
 | Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing | `skills/agent-permission-friction.md` |
 | Studio Pro will not load the project, or the .mpr looks gutted — recover before relaunching SP, never git checkout | `skills/mpr-corruption-and-sp-load-errors.md` |
 | Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable | `skills/bug-submission-checklist.md` |
diff --git a/ROUTING.md b/ROUTING.md
index 10bd579b..a595e38f 100644
--- a/ROUTING.md
+++ b/ROUTING.md
@@ -237,6 +237,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
 | Always relevant for | Load this | Agent(s) | Stage(s) | Tier |
 |---|---|---|---|---|
 | Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words | `bug-logs/mxcli-bugs.md` | mdl,gate | 5,6 | ondemand |
+| An e2e rung reports a UI defect (widget never appeared, click did nothing, screen contradicts the data, fixture count wrong) — check the locator before blaming the app: :visible, click order, poll, derived fixtures | `skills/e2e-locators-that-lie.md` | test,review | 5,6 | ondemand |
 | Any time an exit code, a tool's output or a subagent's report is about to become a stated finding — verify before you conclude | `skills/tool-output-is-not-ground-truth.md` | all | - | baseline |
 | Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing | `skills/agent-permission-friction.md` | all | - | ondemand |
 | Studio Pro will not load the project, or the .mpr looks gutted — recover before relaunching SP, never git checkout | `skills/mpr-corruption-and-sp-load-errors.md` | mdl,gate | - | ondemand |
diff --git a/agents/review-agent.md b/agents/review-agent.md
index deff9cbd..bd681c04 100644
--- a/agents/review-agent.md
+++ b/agents/review-agent.md
@@ -70,6 +70,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
 | `skills/fixture-seeding.md` | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness |
 | `skills/journey-proof.md` | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red |
 | `skills/monkey-test.md` | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works |
+| `skills/e2e-locators-that-lie.md` | An e2e rung reports a UI defect (widget never appeared, click did nothing, screen contradicts the data, fixture count wrong) — check the locator before blaming the app: :visible, click order, poll, derived fixtures |
 | `skills/learned-skill-ux-audit.md` | UX audit and screenshot-loop discipline |
 | `skills/learned-skill-scope-delta.md` | Tracking scope delta between the BRD and the built state |
 | `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
diff --git a/agents/test-agent.md b/agents/test-agent.md
index ec92c7ba..70da8dab 100644
--- a/agents/test-agent.md
+++ b/agents/test-agent.md
@@ -51,6 +51,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
 | `skills/fixture-seeding.md` | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness |
 | `skills/journey-proof.md` | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red |
 | `skills/monkey-test.md` | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works |
+| `skills/e2e-locators-that-lie.md` | An e2e rung reports a UI defect (widget never appeared, click did nothing, screen contradicts the data, fixture count wrong) — check the locator before blaming the app: :visible, click order, poll, derived fixtures |
 | `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/report-schema.md` | Writing or reading docs/report.json — the append-only contract every instrument writes to and every renderer reads; open BEFORE building a new instrument or a second renderer |
diff --git a/bin/gate-check.sh b/bin/gate-check.sh
index c1772943..8899bc22 100755
--- a/bin/gate-check.sh
+++ b/bin/gate-check.sh
@@ -1763,8 +1763,8 @@ stage_protocol_paths() {
     2)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-brd.md skills/checkpoints/checkpoint-architecture.md skills/image-transcription.md skills/small-project-tier.md skills/kb-generation.md skills/brd-generation.md skills/brd-validation.md" ;;
     3)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/small-project-tier.md skills/mendix-best-practices-index.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;;
     4)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-build.md skills/agent-roles.md skills/small-project-tier.md skills/module-brief.md skills/module-folder-convention.md skills/brd-to-build-plan.md skills/coverage-ledger.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/learned-constants-and-secrets.md" ;;
-    5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/learned-file-upload-widget.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
-    6)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
+    5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/e2e-locators-that-lie.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/learned-file-upload-widget.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
+    6)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/e2e-locators-that-lie.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
     7)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/close-the-loop.md skills/share-demo-package.md skills/handoff-to-studio-pro.md skills/platform-link.md skills/teamserver-alignment.md skills/deploy-to-sandbox.md" ;;
     *)  echo "" ;;
 # <!-- ROUTING:END -->
diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv
index cd670c84..581b5693 100644
--- a/bin/lib/skill-routing.tsv
+++ b/bin/lib/skill-routing.tsv
@@ -161,6 +161,7 @@ learned-db-assertions	skills/learned-db-assertions.md	Writing DB assertion tests
 fixture-seeding	skills/fixture-seeding.md	Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness	test,review	5,6	ondemand	verify
 journey-proof	skills/journey-proof.md	Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red	test,review	5,6	ondemand	verify
 monkey-test	skills/monkey-test.md	Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works	test,review	5,6	ondemand	verify
+e2e-locators-that-lie	skills/e2e-locators-that-lie.md	An e2e rung reports a UI defect (widget never appeared, click did nothing, screen contradicts the data, fixture count wrong) — check the locator before blaming the app: :visible, click order, poll, derived fixtures	test,review	5,6	ondemand	diagnose
 learned-skill-ux-audit	skills/learned-skill-ux-audit.md	UX audit and screenshot-loop discipline	review	6	ondemand	verify
 learned-skill-scope-delta	skills/learned-skill-scope-delta.md	Tracking scope delta between the BRD and the built state	review	6	ondemand	verify
 company-brain	skills/company-brain.md	Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/	all	-	ondemand	spine
diff --git a/skills/e2e-harness-base.md b/skills/e2e-harness-base.md
index cbbb3d69..30f39d2b 100644
--- a/skills/e2e-harness-base.md
+++ b/skills/e2e-harness-base.md
@@ -385,6 +385,7 @@ Write a gap report in `tests/results/YYYY-MM-DD-gap-report.md`:
 ## Mendix-specific quirks to know
 
 - **`.mx-name-*` selectors are stable** — always use these, never rely on position or text
+- **Stable is not unique in the DOM** — a tabbed page renders hidden panes at zero height, so `.mx-name-x` can match two nodes with the hidden one first. Use `:visible`, plain click before `force`, and poll text — `e2e-locators-that-lie.md` has the four measured defects
 - **Widget names come from MDL** — the name you gave a widget in `CREATE PAGE` is the class
 - **Post-login modal** — Mendix shows a "Welcome" or consent modal after login; always dismiss it
 - **3.5s wait after login** — less and the modal check may race; more is safe
diff --git a/skills/e2e-locators-that-lie.md b/skills/e2e-locators-that-lie.md
new file mode 100644
index 00000000..17e60868
--- /dev/null
+++ b/skills/e2e-locators-that-lie.md
@@ -0,0 +1,121 @@
+# Playwright locators that lie about a Mendix page — four harness defects that accuse the app
+
+**Applies to:** any mxcli project with a Playwright e2e suite against Mendix pages — hand-written specs first (see "Runner status" below).
+**Purpose:** stop an e2e rung from reporting a confident, specific defect **in the app** that is really a defect in the instrument. Three of the four below were false FAILs; one was a false PASS, which is worse.
+**Companion skills:** `e2e-harness-base.md` (widget discovery, `.mx-name-*` selectors), `journey-proof.md` (rung 1 landing guard and the UI text rung), `fixture-seeding.md` (where fixture values come from), `tool-output-is-not-ground-truth.md` (verify before you conclude), `unhappy-path-testing.md` (absence assertions on denied affordances).
+
+Measured 2026-09-17 on a user-group administration module (a tabbed detail page with a members
+grid and a per-row role dropdown). Net effect before the four were found: a module with no UI
+defect looked broken, and an interaction that did nothing looked green.
+
+---
+
+## 1. A widget name is unique per PAGE, not per rendered DOM
+
+Studio Pro guarantees `dataGrid21` is unique in the page model. It guarantees nothing about how many
+times that page renders it. A tabbed page renders each pane's widgets, and the hidden panes are in
+the DOM at zero height.
+
+```
+.mx-name-dataGrid21  →  2 nodes:  [0] hidden, height 0
+                                  [1] visible, height 686   ← the one the user sees
+```
+
+`.first().isVisible()` therefore answered **false** about a grid that was on screen, and the landing
+guard reported "never appeared". Worse, `.first().click()` and `.first()` on a `<select>` drove the
+**hidden** pane: the assertion read its committed value back successfully and passed, while no
+microflow ran and the data assertions three lines later failed.
+
+**Rule:** never `.first()` a Mendix widget class unqualified. Either scope it (`within`, `hasText`)
+or restrict to `:visible`; and for assertions check **every** match, polling until one is visible:
+
+```js
+// interactions: resolve to what a user can actually reach
+page.locator(`.mx-name-${n}:visible`).first()
+
+// assertions (landing guard, widget-present, widget-absent): any match visible, within a deadline
+async function anyVisible(page, sel, timeout) {
+  const deadline = Date.now() + timeout;
+  do {
+    const loc = page.locator(sel);
+    const n = await loc.count().catch(() => 0);
+    for (let k = 0; k < n; k++)
+      if (await loc.nth(k).isVisible().catch(() => false)) return true;
+    await page.waitForTimeout(250);
+  } while (Date.now() < deadline);
+  return false;
+}
+```
+
+For an **absence** assertion this matters more than anywhere else: with `.first()` a hidden first
+node makes an on-screen affordance read as "not rendered", and an authorisation test passes for
+free (`unhappy-path-testing.md`).
+
+## 2. `click({ force: true })` on a Mendix tab does nothing, and does not throw
+
+The tab handler is bound to the inner `<a>`. A forced click dispatches at the `<li>` centre with no
+actionability check, so it is swallowed — the tab never switches and the click reports success.
+
+This also defeats the usual fallback idiom, because the `catch` never fires:
+
+```js
+await el.click({ force: true }).catch(() => el.click());                   // WRONG — force never throws
+await el.click({ timeout: 6000 }).catch(() => el.click({ force: true }));  // right order
+```
+
+Plain click first: it waits for actionability and hits the real target. Force is a fallback for a
+genuinely obstructed element, not a default. (A hit-test before a forced click, as the shipped
+runner does, catches a *cover*; it does not catch a handler bound to a child node.)
+
+## 3. A grid re-renders on the response, not on the click
+
+After a confirmed delete the row was still on screen at 3.5s and gone by 5s. A single text read at
+the step's settle time produced *"the screen contradicts the data"* — an accusation against an app
+that was refreshing correctly.
+
+**Rule:** assert the eventual state. Poll until the property holds, fail only if it never does,
+within a bounded timeout. This is strictly stronger than one read: nothing that passed can start
+failing, and a screen that truly never updates still fails.
+
+```js
+const awaitText = async (needle, wantPresent, deadlineMs = 15000) => {
+  const deadline = Date.now() + deadlineMs;
+  do {
+    const body = await page.locator('body').innerText().catch(() => '');
+    if (body.includes(needle) === wantPresent) return true;
+    await page.waitForTimeout(250);
+  } while (Date.now() < deadline);
+  return false;   // the only FAIL: the screen never reached the claimed state
+};
+```
+
+Apply it in both directions — `textPresent` and `textAbsent` — or the absence check keeps the
+single-read race.
+
+## 4. A fixture constant the fixture script itself writes measures nothing
+
+A check asserted `MemberCount = 6`. The reset script wrote the literal `6`. So the assertion could
+only ever confirm the reset had run — and it broke the day the group's real population changed,
+failing against a correct app.
+
+**Rule:** derive fixture values from the rows, and assert the *property* the test claims rather than
+a magic number. Here "membership must stay single" became a join across both association tables
+looking for anyone present in each — independent of how many people the fixture holds, and stronger,
+since it catches a double membership for any person rather than just the seeded one. See
+`fixture-seeding.md` for where the values should come from in the first place.
+
+## Runner status
+
+`project-tests/e2e/journey-runner.js` (the shipped runner, as of this skill's promotion) does
+**not** yet apply rules 1–3: its widget lookup is `.mx-name-<n>` + `.first()` without `:visible`,
+its click order is force-then-plain, and its `textPresent` / `textAbsent` rungs read the body once.
+So until that lands, the four rules apply to hand-written specs **and** are the first things to check
+when a runner verdict names the app. Rule 4 is about the journey's `sql` checks and fixture script,
+which the runner cannot fix for you.
+
+## The meta-lesson
+
+Every one of these reported a defect in the software under test. When an e2e rung fails, the first
+question is not "what did the app break" but **"did the instrument look at the right thing"** — take
+the screenshot, count the matching nodes, and poll before concluding
+(`tool-output-is-not-ground-truth.md`).

From c3cd9af9fc9caf9734b2216726ff6064c8c0a969 Mon Sep 17 00:00:00 2001
From: MendixMau <mauritscgvisser@gmail.com>
Date: Thu, 8 Oct 2026 22:09:16 +0800
Subject: [PATCH 12/19] skills: promote unhappy-path-testing (requirement-cited
 unhappy-path e2e)

Every unhappy-path case cites a requirement before it runs; results are
PASS / GAP / UNSPECIFIED, and UNSPECIFIED is re-scored against seven house
rules as GAP-HOUSE so a silent requirement cannot hide a user-visible
defect. Measured on a warehouse-management demo project, 2026-09-24/25:
45 cases, 5 modules, 25 -> 27 of 45 PASS, 5 GAP, 13 UNSPECIFIED.

Wired: routing row (test,review; stages 5,6; ondemand; verify) and the
rendered surfaces, a pointer row in testing-shape.md's owner table, and
the CHANGELOG line. testing-shape.md:273 reworded (16-step -> 16 steps)
so the pre-commit numbering check no longer reads a measurement as a
list count.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CHANGELOG.md                   |   1 +
 README.md                      |   1 +
 ROUTING.md                     |   1 +
 agents/review-agent.md         |   1 +
 agents/test-agent.md           |   1 +
 bin/gate-check.sh              |   4 +-
 bin/lib/skill-routing.tsv      |   1 +
 skills/testing-shape.md        |   3 +-
 skills/unhappy-path-testing.md | 126 +++++++++++++++++++++++++++++++++
 9 files changed, 136 insertions(+), 3 deletions(-)
 create mode 100644 skills/unhappy-path-testing.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..a88736ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- learn(skills): **`unhappy-path-testing.md` — requirement-cited unhappy-path e2e.** Every case cites a requirement (BRD rule, entity doc comment, `not null` error, `Visible:` expression, grant) before it runs; results are PASS / GAP / UNSPECIFIED, and UNSPECIFIED is re-scored against seven house rules (whitespace-as-required, silent truncation, no empty-state text, …) as GAP-HOUSE so a silent requirement cannot hide a user-visible defect. Measured on a warehouse-management demo project, 2026-09-24/25: 45 cases over 5 modules, five overnight runs 16 → 25 of 45 PASS (run 2's 17 GAPs were 10 instrument faults from one deep link), fix loop to 27/45 PASS, 5 GAP, 13 UNSPECIFIED, every GAP an open product Decision. Routed `test,review` at stages 5–6 (`verify`, ondemand) and pointed at from `testing-shape.md`'s owner table. — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/README.md b/README.md
index 120e7d90..e724582c 100644
--- a/README.md
+++ b/README.md
@@ -649,6 +649,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini
 | Writing DB assertion tests that cross-check UI state against the database | `skills/learned-db-assertions.md` |
 | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness | `skills/fixture-seeding.md` |
 | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red | `skills/journey-proof.md` |
+| Writing or running e2e cases beyond the happy journeys (blank/whitespace required fields, over-length, duplicates, cancel, double submit, wrong state, wrong role, backend down, stale write, empty search) — every case cites a requirement first, UNSPECIFIED is re-scored against house rules, GAP counts carry the denominator; runs after journey-proof and before monkey-test | `skills/unhappy-path-testing.md` |
 | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works | `skills/monkey-test.md` |
 | UX audit and screenshot-loop discipline | `skills/learned-skill-ux-audit.md` |
 | Tracking scope delta between the BRD and the built state | `skills/learned-skill-scope-delta.md` |
diff --git a/ROUTING.md b/ROUTING.md
index 10bd579b..a3f53cdd 100644
--- a/ROUTING.md
+++ b/ROUTING.md
@@ -211,6 +211,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
 | Writing DB assertion tests that cross-check UI state against the database | `skills/learned-db-assertions.md` | test | 6 | ondemand |
 | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness | `skills/fixture-seeding.md` | test,review | 5,6 | ondemand |
 | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red | `skills/journey-proof.md` | test,review | 5,6 | ondemand |
+| Writing or running e2e cases beyond the happy journeys (blank/whitespace required fields, over-length, duplicates, cancel, double submit, wrong state, wrong role, backend down, stale write, empty search) — every case cites a requirement first, UNSPECIFIED is re-scored against house rules, GAP counts carry the denominator; runs after journey-proof and before monkey-test | `skills/unhappy-path-testing.md` | test,review | 5,6 | ondemand |
 | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works | `skills/monkey-test.md` | test,review | 5,6 | ondemand |
 | UX audit and screenshot-loop discipline | `skills/learned-skill-ux-audit.md` | review | 6 | ondemand |
 | Tracking scope delta between the BRD and the built state | `skills/learned-skill-scope-delta.md` | review | 6 | ondemand |
diff --git a/agents/review-agent.md b/agents/review-agent.md
index deff9cbd..b000fbb6 100644
--- a/agents/review-agent.md
+++ b/agents/review-agent.md
@@ -69,6 +69,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
 | `project-bin/graph-sweep.sh` | Running the wiring rung alone — a module imported but never reached, an element built but wired to nothing, a boundary crossed; mxbuild and e2e are blind to all three |
 | `skills/fixture-seeding.md` | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness |
 | `skills/journey-proof.md` | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red |
+| `skills/unhappy-path-testing.md` | Writing or running e2e cases beyond the happy journeys (blank/whitespace required fields, over-length, duplicates, cancel, double submit, wrong state, wrong role, backend down, stale write, empty search) — every case cites a requirement first, UNSPECIFIED is re-scored against house rules, GAP counts carry the denominator; runs after journey-proof and before monkey-test |
 | `skills/monkey-test.md` | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works |
 | `skills/learned-skill-ux-audit.md` | UX audit and screenshot-loop discipline |
 | `skills/learned-skill-scope-delta.md` | Tracking scope delta between the BRD and the built state |
diff --git a/agents/test-agent.md b/agents/test-agent.md
index ec92c7ba..78cef7c7 100644
--- a/agents/test-agent.md
+++ b/agents/test-agent.md
@@ -50,6 +50,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
 | `skills/learned-db-assertions.md` | Writing DB assertion tests that cross-check UI state against the database |
 | `skills/fixture-seeding.md` | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness |
 | `skills/journey-proof.md` | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red |
+| `skills/unhappy-path-testing.md` | Writing or running e2e cases beyond the happy journeys (blank/whitespace required fields, over-length, duplicates, cancel, double submit, wrong state, wrong role, backend down, stale write, empty search) — every case cites a requirement first, UNSPECIFIED is re-scored against house rules, GAP counts carry the denominator; runs after journey-proof and before monkey-test |
 | `skills/monkey-test.md` | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works |
 | `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
diff --git a/bin/gate-check.sh b/bin/gate-check.sh
index c1772943..c71fb739 100755
--- a/bin/gate-check.sh
+++ b/bin/gate-check.sh
@@ -1763,8 +1763,8 @@ stage_protocol_paths() {
     2)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-brd.md skills/checkpoints/checkpoint-architecture.md skills/image-transcription.md skills/small-project-tier.md skills/kb-generation.md skills/brd-generation.md skills/brd-validation.md" ;;
     3)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/small-project-tier.md skills/mendix-best-practices-index.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;;
     4)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-build.md skills/agent-roles.md skills/small-project-tier.md skills/module-brief.md skills/module-folder-convention.md skills/brd-to-build-plan.md skills/coverage-ledger.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/learned-constants-and-secrets.md" ;;
-    5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/learned-file-upload-widget.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
-    6)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
+    5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/unhappy-path-testing.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/learned-file-upload-widget.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
+    6)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/unhappy-path-testing.md skills/monkey-test.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
     7)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/close-the-loop.md skills/share-demo-package.md skills/handoff-to-studio-pro.md skills/platform-link.md skills/teamserver-alignment.md skills/deploy-to-sandbox.md" ;;
     *)  echo "" ;;
 # <!-- ROUTING:END -->
diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv
index cd670c84..8a2d1d4d 100644
--- a/bin/lib/skill-routing.tsv
+++ b/bin/lib/skill-routing.tsv
@@ -160,6 +160,7 @@ e2e-harness-base	skills/e2e-harness-base.md	Standing up or extending the Playwri
 learned-db-assertions	skills/learned-db-assertions.md	Writing DB assertion tests that cross-check UI state against the database	test	6	ondemand	verify
 fixture-seeding	skills/fixture-seeding.md	Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness	test,review	5,6	ondemand	verify
 journey-proof	skills/journey-proof.md	Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red	test,review	5,6	ondemand	verify
+unhappy-path-testing	skills/unhappy-path-testing.md	Writing or running e2e cases beyond the happy journeys (blank/whitespace required fields, over-length, duplicates, cancel, double submit, wrong state, wrong role, backend down, stale write, empty search) — every case cites a requirement first, UNSPECIFIED is re-scored against house rules, GAP counts carry the denominator; runs after journey-proof and before monkey-test	test,review	5,6	ondemand	verify
 monkey-test	skills/monkey-test.md	Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works	test,review	5,6	ondemand	verify
 learned-skill-ux-audit	skills/learned-skill-ux-audit.md	UX audit and screenshot-loop discipline	review	6	ondemand	verify
 learned-skill-scope-delta	skills/learned-skill-scope-delta.md	Tracking scope delta between the BRD and the built state	review	6	ondemand	verify
diff --git a/skills/testing-shape.md b/skills/testing-shape.md
index c12550c3..471d54d9 100644
--- a/skills/testing-shape.md
+++ b/skills/testing-shape.md
@@ -16,6 +16,7 @@ and the guard for each. Job 2 is why this skill exists; if you shorten it, do no
 | Non-pipeline app, à-la-carte assurance | `existing-app-assurance.md` (shared toolkit) |
 | Why a green UI report can still be lying | **§4a below** — merged in, no longer a separate file |
 | The deep five-rung version of "prove it", with per-rung non-vacuity controls | `journey-proof.md` (shared toolkit) |
+| Unhappy paths after the journeys are green — requirement-cited cases, house-rules fallback for UNSPECIFIED, GAP counts with a denominator | `unhappy-path-testing.md` (shared toolkit) |
 | Requirement traceability the suite asserts against | `coverage-ledger.md` (shared toolkit) |
 | Why `$?` and tool output are not evidence | `tool-output-is-not-ground-truth.md` (shared toolkit) |
 | Does the whole journey hang together, not just each piece — a different axis, not a fifth rung | `process-coherence-pass.md` (shared toolkit) |
@@ -270,7 +271,7 @@ human looking at the screenshot, not by the suite.
   bland **"Sign in failed."** on the login page — indistinguishable from a wrong password, and
   `system$user.failedlogins` stays at **0** because authentication was never reached. Every
   downstream step then reports as a feature failure. Measured 2026-08-31 on a Mendix 11.13 app: a
-  16-step narrated tour scored 0, with each step labelled `(as (not signed in))`, and the only honest
+  narrated tour of 16 steps scored 0, with each step labelled `(as (not signed in))`, and the only honest
   evidence was one line in the runtime log —
   `ERROR - Connector: ... Maximum number of sessions exceeded! (You are currently using a trial
   license)`. Sixteen "defects" that were one leaked session pool.
diff --git a/skills/unhappy-path-testing.md b/skills/unhappy-path-testing.md
new file mode 100644
index 00000000..38bdbf96
--- /dev/null
+++ b/skills/unhappy-path-testing.md
@@ -0,0 +1,126 @@
+# Skill: unhappy-path-testing — every case cites a requirement, or a house rule, before it runs
+
+**Applies to:** any built module with a form, a role-gated action, or a REST backend; any mxcli project.
+**Purpose:** e2e beyond the happy journeys — missing fields, invalid values, wrong state, wrong role,
+a down or slow backend, stale data, double clicks — with every case tied to a cite so its result can
+be *judged*, not just recorded. Also for the moment an agent must decide whether odd behaviour is a defect.
+**Source:** a warehouse-management demo project, 2026-09-24/25 — 45 cases, 5 modules, 5 overnight runs,
+then one fix loop. Promoted 2026-10-08.
+**Companion skills:** `journey-proof.md` (runs first), `monkey-test.md` (runs after), `learned-db-assertions.md`,
+`e2e-harness-base.md`, `testing-shape.md`.
+
+---
+
+## Why it is not fuzzing
+
+`monkey-test.md` measured random input at **0 defects against 9 for scripted journeys**. Unhappy
+paths find defects only when each case asks a *specific* question that a requirement answers.
+Without a requirement, a result cannot be judged. The case then records behaviour and the
+defect hides in plain sight.
+
+## The matrix comes first, the code second
+
+Write `docs/handoffs/unhappy-path-matrix.md` before any spec. One row per case:
+
+| ID | Requirement cite | Scenario | Expected per requirement | Assertion (UI **and** DB) | Status |
+
+- **Cite** is a quote with its source, e.g. a BRD business rule, the entity's own doc comment, a
+  `not null error '…'` in the domain model, a page's `Visible:` expression, or a grant line read
+  with `DESCRIBE`. Read the **live model**, not `mdlsource/`: a committed script is not an
+  executed one (`tool-output-is-not-ground-truth.md`).
+- **Status** is filled by the run, never by hand:
+  - **PASS**: the app does what the cite says.
+  - **GAP**: the app does what the cite forbids, or does not do what it demands. A real finding.
+  - **UNSPECIFIED**: the cite is silent; the behaviour is recorded, not judged.
+- **Reject a source that is about something else.** Check every BRD you cite against the entity
+  it is meant to cover. In the source project a BRD titled "equipment management" turned out to
+  describe a different domain's module that happened to share the word; it was read, rejected in
+  writing at the top of the matrix, and the module's cases were grounded in the live entity's own
+  doc-comment rules instead. Citing it would have produced confident nonsense.
+
+## The categories to cover, per module
+
+For each entity or screen, write at least one case per applicable row:
+
+1. **Required fields**: blank, and a single space (does `not null` stop whitespace?).
+2. **Length and format**: one past the column width, a bad format against a stated pattern.
+3. **Duplicates**: a second record with the same business key.
+4. **Cancel**: fill the form, cancel, check that no row exists.
+5. **Double submit**: two clicks under 300 ms; count the rows.
+6. **Wrong state**: act on a record whose state forbids it (released, closed, retired).
+7. **Wrong role**: log in as a read-only role, then assert the button is absent **and** that the
+   microflow refuses (hiding is not access control).
+8. **Backend errors** (REST modules): down (connection refused), 4xx with problem details,
+   5xx, empty body, slow. Assert the user sees a sentence, not a stack trace or a blank list.
+9. **Concurrency**: two sessions, one stale write; the app should say so, not overwrite.
+10. **Empty results**: a search that matches nothing; is there an empty-state message?
+11. **Security posture**: grants read from the model (anonymous CRUD, over-broad module roles).
+    Report as findings; do not drive them through Playwright.
+
+## The house-rules fallback: UNSPECIFIED must not be a hiding place
+
+In the source project, 13 of 45 cases came back UNSPECIFIED. Reviewing those rows afterwards, at
+least 6 were defects a user would report: whitespace passing "required", silent truncation at the
+20- and 200-character column widths, no empty-state text. Nothing flagged them, because no
+requirement spoke. This is `degrade-to-judgement.md` applied to a test matrix: a missing
+requirement changes what you assess *against*, never *whether* you assess.
+
+So every UNSPECIFIED result is scored a second time against these **house rules**, and a failure
+is reported as **GAP-HOUSE**, a separate count from GAP:
+
+| House rule | Fails when |
+|---|---|
+| H1 Required means non-blank | A value of only spaces passes a required field |
+| H2 Never truncate silently | Stored value is shorter than typed, and no message said so |
+| H3 Empty is explained | A list that matches nothing shows a blank area, with no text |
+| H4 Errors are sentences | The user sees a code, a stack trace, JSON, or nothing |
+| H5 One click, one record | A double submit creates two rows |
+| H6 Cancel leaves nothing | A row exists after Cancel |
+| H7 Hidden is also refused | A role that cannot see a button can still run its microflow |
+
+The house rules are not requirements. Put GAP-HOUSE rows in front of the product owner as
+Decisions ("fix, or accept as designed?"); do not fix them unasked.
+
+## Assertions that cannot pass vacuously
+
+- **UI and DB, both.** "Error text visible" alone passes when the form never saved anyway. Count
+  rows in the DB before and after, with the same filter the case is about
+  (`learned-db-assertions.md` for the mechanics).
+- **Guard the precondition.** Assert that the record under test exists and is in the state the
+  case needs, before acting. A case on a released route passes trivially if the seed has none.
+- **Log in as a real non-admin role, and assert the username on screen.** A harness that falls
+  back to an admin account on a failed login makes every role case pass.
+- **Assert the nav landed** (page title or a page-unique element) before reading anything —
+  see `e2e-locators-that-lie.md` for the locator side of this.
+- **Never count visible rows** as a total; they stop at the page size.
+- For REST modules, **stop or break the backend on purpose** in the down cases, and check that it
+  really was down (a health probe fails) before asserting the message.
+
+## Running and reporting
+
+- One spec per module (`tests/e2e/unhappy/unhappy-<module>.js`), one runner that writes
+  `results.json` with an ID, status, the cite, the observed behaviour, and a screenshot path per
+  case.
+- The report headline is counts **with the denominator**: `27/45 PASS, 5 GAP, 6 GAP-HOUSE,
+  7 UNSPECIFIED, 0 ERROR`. An ERROR (the test itself broke) is never folded into PASS or GAP.
+  A missing `results.json` is reported as missing, never as `0/45` (`measured-claims.md`).
+- Every GAP gets a line: the fix, or the Decision it maps to. In the source project all 5
+  remaining GAPs mapped one-to-one to open product Decisions; that mapping is the useful output.
+- Look at the screenshots of every GAP and GAP-HOUSE before reporting. A GAP whose screenshot
+  shows the previous page is a test defect, not an app defect.
+- Expect the early runs to be dominated by **instrument faults, not app faults**: in the source
+  project run 2 reported 17 GAPs, 10 of which were one module's spec using a deep link the
+  runtime answered with HTTP 404. Triage every GAP cluster that lands on a single module as a
+  harness suspect first.
+
+## Where this came from
+
+A warehouse-management demo project, 2026-09-24 and 25: matrix `docs/handoffs/unhappy-path-matrix.md`,
+specs under `tests/e2e/unhappy/`, run log in the overnight handoff. Five runs went
+16 → 19 → 22 → 21 → 25 of 45 PASS as harness faults and app fixes landed; the next day's fix loop
+took it to **27/45 PASS, 5 GAP, 13 UNSPECIFIED**, with every GAP an open Decision. The house-rules
+fallback is the lesson from reviewing the 13 UNSPECIFIED rows afterwards; it had not yet been run
+as a second scoring pass in that project, so GAP-HOUSE counts above are the shape, not a measurement.
+
+Related: `e2e-locators-that-lie.md`, `measured-claims.md`, `tool-output-is-not-ground-truth.md`,
+`degrade-to-judgement.md`, `testing-shape.md` §4a (why a green UI report can still be lying).

From afeba3c87f28009bb4bf1c3ed555411b80603725 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:09:43 +0000
Subject: [PATCH 13/19] docs(testing-shape): test --local shares the deploy dir
 with run --local (#230)

The skill claimed a warm run --local app keeps serving during mxcli test --local.
Ports and DB are separate but mxbuild writes <app dir>/deployment for both, so a
building test run breaks the live app. Rewrote the passage: restart run --local
after test --local; --attach hot-applies into the live app and its database.
No other contradicting sentences found (--attach mentions at lines 317-333 are consistent).
Checks: check-docs-numbering (nothing staged to examine), leak guard clean,
check-pr-discipline clean. Docs only; no fixture covers this file.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md            |  1 +
 skills/testing-shape.md | 14 +++++++++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..277d564d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(testing-shape): **`mxcli test --local` shares the deploy directory with `run --local`, so a warm app does not keep serving.** The skill said separate ports and database meant a warm `run --local` loop survives a test run; mxbuild writes `<app dir>/deployment` for both, so a building test run breaks the live app (200 with empty bodies, NoClassDefFoundError). Now says to restart `run --local` after `test --local` and that `--attach` hot-applies into the live app. Field run 2026-10-07, existing app (#230) — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/skills/testing-shape.md b/skills/testing-shape.md
index c12550c3..0d1c1b61 100644
--- a/skills/testing-shape.md
+++ b/skills/testing-shape.md
@@ -351,9 +351,17 @@ licence failure. The tell is `404 - file not found for file: dist%2Findex.js` in
 
 **`--hub` is what makes a container-hosted run reachable.** A cloud/devcontainer session has no
 shared filesystem with a laptop and cannot serve `localhost` to one. Before `--hub` the only answer
-was a hand-rolled ngrok/cloudflared tunnel; it is now a flag. `mxcli test --local` likewise boots on
-mxcli's own runtime (ports 8081/8091, its own `<project>_test` database), so a warm `run --local`
-loop can keep serving while tests run.
+was a hand-rolled ngrok/cloudflared tunnel; it is now a flag.
+
+**`mxcli test --local` does NOT leave a warm `run --local` app alone.** It uses its own ports
+(8081/8091) and its own `<project>_test` database, but not its own deployment directory: mxbuild
+always writes `<app dir>/deployment`, so a building test run rewrites `deployment/run/bin` under the
+live app. mxcli warns ("This test run recompiles the project") but does not stop it, and the live
+app then answers 200 with empty bodies or `NoClassDefFoundError` — journeys that follow fail for
+reasons unrelated to the feature. **Restart `run --local` after any `test --local` run; never run a
+journey across one.** `--attach` avoids the second build but hot-applies into the live app and runs
+against its database, so restart before any journey that counts rows.
+(Field case: existing app, mxcli v0.25, Mendix 11.15, 2026-10-07.)
 
 > ### 🔴 Docker is NOT a safe default if the app calls host services by `localhost`
 >

From bec907c37bd1ad4539dd703b4e2c56ab002643d9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:11:52 +0000
Subject: [PATCH 14/19] fix(obligations): LOOK staleness picks the newest VALID
 AT stamp (#155)

_ob_stale and the proof check took `head -c 8000 | ... | head -1`, the first stamp in the
first 8000 bytes, so a review file with dated per-build addenda was judged by its headline
stamp and went false-STALE. Now reads the whole file and takes `tail -1`.

New fixture tests/wave2/test-obligation-valid-at.sh (git scratch repo, synthetic reports):
control old-only stamp -> STALE; old then HEAD stamp -> not STALE; HEAD stamp past 8000 bytes
-> not STALE. Result 3/3 pass post-fix; pre-fix 1/3 (T2, T3 fail). Golden input is not a
tool-output parse here, so hand-built reports are the stamp shape from module-review.md.
Also ran bash -n, check-portability, check-scripts, leak guard, check-pr-discipline: clean.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                            |  1 +
 bin/lib/obligation-check.sh             |  8 ++---
 tests/wave2/test-obligation-valid-at.sh | 48 +++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 4 deletions(-)
 create mode 100755 tests/wave2/test-obligation-valid-at.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..db9fc6c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(obligations): **LOOK staleness reads the newest `VALID AT` stamp, anywhere in the report.** Both pickers took the first stamp inside the first 8000 bytes, so a review file with dated per-build addenda went false-STALE; now `tail -1` over the whole file. Field run 2026-09-26, requirements-driven build (#155) — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/bin/lib/obligation-check.sh b/bin/lib/obligation-check.sh
index 7fde53e1..af7b25ac 100755
--- a/bin/lib/obligation-check.sh
+++ b/bin/lib/obligation-check.sh
@@ -246,9 +246,9 @@ _ob_has_denominator() {
 # "expired".
 _ob_stale() {
   local root="$1" hit="$2" hash n
-  hash="$(head -c 8000 "$hit" 2>/dev/null | tr -d '\r' \
+  hash="$(cat "$hit" 2>/dev/null | tr -d '\r' \
     | grep -oiE 'VALID[[:space:]]+AT:?[[:space:]]*[0-9a-f]{7,40}' \
-    | grep -oiE '[0-9a-f]{7,40}$' | head -1)"
+    | grep -oiE '[0-9a-f]{7,40}$' | tail -1)"
   [ -n "$hash" ] || return 1
   git -C "$root" cat-file -e "${hash}^{commit}" 2>/dev/null || return 1
   n="$(git -C "$root" log --oneline "${hash}..HEAD" -- '*.mpr' mdlsource 2>/dev/null | wc -l | tr -d ' ')"
@@ -303,9 +303,9 @@ _ob_look_proof_broken() {
 
   # VALID AT commit time, for freshness. Unresolvable → freshness unmeasured, not failed.
   local vhash vtime=""
-  vhash="$(head -c 8000 "$hit" 2>/dev/null | tr -d '\r' \
+  vhash="$(cat "$hit" 2>/dev/null | tr -d '\r' \
     | grep -oiE 'VALID[[:space:]]+AT:?[[:space:]]*[0-9a-f]{7,40}' \
-    | grep -oiE '[0-9a-f]{7,40}$' | head -1)"
+    | grep -oiE '[0-9a-f]{7,40}$' | tail -1)"
   [ -n "$vhash" ] && vtime="$(git -C "$root" show -s --format=%ct "${vhash}^{commit}" 2>/dev/null || true)"
 
   reldir="$(dirname "$hit")"
diff --git a/tests/wave2/test-obligation-valid-at.sh b/tests/wave2/test-obligation-valid-at.sh
new file mode 100755
index 00000000..c949bc4a
--- /dev/null
+++ b/tests/wave2/test-obligation-valid-at.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Usage: bash tests/wave2/test-obligation-valid-at.sh [path-to-gate-check.sh | path-to-obligation-check.sh]
+#
+# test-obligation-valid-at.sh — the LOOK obligation's staleness check must judge a review report
+# by its NEWEST "VALID AT: <hash>" stamp, wherever in the file it sits.
+#
+# THE BUG (#155): _ob_stale and the proof check picked `head -c 8000 | grep ... | head -1` — the
+# FIRST stamp in the first 8000 bytes. A report that keeps one dated headline and appends an
+# addendum per build row (each with its own VALID AT) was judged by the headline's original
+# stamp and went STALE after later model commits, though every page was re-looked-at.
+# Subject: obligation-check.sh. Producer of the stamp: module-review.md stage 5 (the reviewer).
+set -uo pipefail
+ARG="${1:?usage: test-obligation-valid-at.sh /path/to/bin/gate-check.sh (or lib/obligation-check.sh)}"
+case "$(basename "$ARG")" in
+  obligation-check.sh) OBCHECK="$ARG" ;;
+  *) OBCHECK="$(cd "$(dirname "$ARG")" && pwd)/lib/obligation-check.sh" ;;
+esac
+[ -r "$OBCHECK" ] || { echo "no obligation-check.sh at $OBCHECK"; exit 2; }
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/ob-validat.XXXXXX")"
+trap '[ -n "${KEEP:-}" ] || rm -rf "$WORK"' EXIT
+PASS=0; FAIL=0
+ok()  { PASS=$((PASS+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAIL=$((FAIL+1)); printf '  FAIL %s\n' "$1"; }
+
+P="$WORK/p"; mkdir -p "$P/architecture/modules/ModuleX" "$P/mdlsource" "$P/design/ui-reviews"
+git -C "$P" init -q . 2>/dev/null
+git -C "$P" config user.email t@t; git -C "$P" config user.name t
+echo a > "$P/mdlsource/a.mdl"; git -C "$P" add -A; git -C "$P" commit -qm one
+OLD="$(git -C "$P" rev-parse --short HEAD)"
+echo b >> "$P/mdlsource/a.mdl"; git -C "$P" commit -qam two
+NEW="$(git -C "$P" rev-parse --short HEAD)"
+REP="$P/design/ui-reviews/ui-review-2026-01-01.html"
+stale() { "$OBCHECK" "$P" 2>&1 | grep -c 'STALE'; }
+
+echo "== T1: only the old stamp, model built past it -> STALE (control) =="
+printf '<p>ModuleX: 1 of 1 pages reviewed</p>\nVALID AT: %s\n' "$OLD" > "$REP"
+[ "$(stale)" -gt 0 ] && ok "old-only stamp reports STALE" || bad "control: expected STALE"
+
+echo "== T2: old stamp, then an addendum stamped at HEAD -> newest wins, not STALE =="
+printf '<p>ModuleX: 1 of 1 pages reviewed</p>\nVALID AT: %s\n<h2>Addendum</h2>\nVALID AT: %s\n' "$OLD" "$NEW" > "$REP"
+[ "$(stale)" -eq 0 ] && ok "later stamp wins" || bad "first stamp was used (STALE)"
+
+echo "== T3: newest stamp sits past byte 8000 -> still seen =="
+{ printf '<p>ModuleX: 1 of 1 pages reviewed</p>\nVALID AT: %s\n' "$OLD"; head -c 9000 /dev/zero | tr '\0' 'x'; printf '\nVALID AT: %s\n' "$NEW"; } > "$REP"
+[ "$(stale)" -eq 0 ] && ok "stamp past 8000 bytes seen" || bad "stamp past 8000 bytes ignored (STALE)"
+
+echo "pass=$PASS fail=$FAIL"
+[ "$FAIL" -eq 0 ]

From 32dab3c8dbdf0efdf742859f08d8ebfab52fe5cd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:11:58 +0000
Subject: [PATCH 15/19] docs(lint-backlog): batch 4 from Mendix quality-source
 review

Adds 19 backlog rows (13-31) plus review notes to process/lint-backlog.md, the review record
process/quality-sources-review-2026-10-08.md, and seven skill-only additions (indexes, scheduled
events, Atlas 4 tokens, accessibility floor, workflow targeting, test isolation, rollback semantics).
Lintability read from mxcli source only; no rule probed on a model yet.
Checks: leak guard clean, render-routing --check exit 0, check-pr-discipline clean,
check-portability clean, check-docs-numbering (0 staged docs).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                                 |   1 +
 process/lint-backlog.md                      |  40 ++++++
 process/quality-sources-review-2026-10-08.md | 143 +++++++++++++++++++
 skills/design-artifacts.md                   |   3 +-
 skills/learned-microflow-patterns.md         |   2 +
 skills/learned-workflow-patterns.md          |   2 +
 skills/mendix-best-practices-index.md        |   2 +-
 skills/microflow-loop-antipatterns.md        |   3 +
 skills/modularize-domain.md                  |   3 +
 skills/testing-shape.md                      |   1 +
 skills/ui-preflight-pages.md                 |   2 +
 11 files changed, 200 insertions(+), 2 deletions(-)
 create mode 100644 process/quality-sources-review-2026-10-08.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d0d412c..de689981 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- docs(lint): **Mendix quality-source review: 19 new lint-backlog rows (Batch 4) plus seven skill additions.** Recommender, QSM/AQM, ATS, Menditect and docs.mendix.com mapped against shipped rules; indexes, scheduled events, Atlas 4 tokens, accessibility floor, workflow targeting, test isolation and rollback semantics added to their skills; record in `process/quality-sources-review-2026-10-08.md`; no rule probed on a model yet — MendixMau
 - docs(lint): **`process/lint-backlog.md` — the lint rollout plan, on disk.** Twelve rule candidates mined from `skills/` with the evidence each rests on, the catalog field each needs, and five rollout rules (two or three rules per PR, ship as warning, one field run before merge, promote after two clean projects, blind rules say so). Plus what is not lintable and lives in a skill (theme, logging, scheduled events) and four brain contradictions to settle first. Until today this plan existed only in chat. — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
diff --git a/process/lint-backlog.md b/process/lint-backlog.md
index e5f0503d..024317ba 100644
--- a/process/lint-backlog.md
+++ b/process/lint-backlog.md
@@ -58,6 +58,46 @@ project). This file has the *what* and the *order*.
 | 11 | Widget-bound entity with zero access rules at production level | security | SEC001 variant scoped to entities pages actually touch | entity access in projection | idea |
 | 12 | Navigation item without icon | design | `learned-sidebar-collapse-icons.md` | navigation in projection (unconfirmed) | blocked: field unconfirmed |
 
+## Batch 4 — Mendix quality-source review
+
+Sources: Mendix Best Practice Recommender, QSM/AQM public docs, ATS public docs, Menditect public docs,
+docs.mendix.com; reviewed 2026-10-08. Rule ids are placeholders. Lintability was read from the mxcli lint
+source (Starlark accessors), and no rule below has been probed on a real model yet, so every "Needs" cell
+is still the vocabulary probe from rollout rule 3. The full review is
+`process/quality-sources-review-2026-10-08.md`. Suggested PR grouping: {13, 14, 15} · {16, 17, 27} ·
+{21, 22} · {18, 23, 28} · {19, 20, 29} · {24, 25, 26}.
+
+| # | Rule | Category | Evidence | Needs | Status |
+|---|---|---|---|---|---|
+| 13 | Anonymous role hygiene: anonymous = admin role; anonymous mapped to an Administration module role; a module role shared by anonymous and another user role (SEC010) | security | Recommender MXS005, MXS008, MXS009 | `project_security()` anonymous/admin role names; `user_roles().is_anonymous`; `role_mappings()` | idea |
+| 14 | Anonymous role can create, delete or write members of a persistable entity (SEC011) | security | Recommender MXS006 | `permissions()` access_type vocabulary (probe) | idea |
+| 15 | Entity access grants default rights to new members (SEC012) | security | General Development Best Practices → Security | `permissions().default_member_access_rights` values (probe) | idea |
+| 16 | Generalization deeper than two levels (PERF001) | performance | Recommender MXP009; General Dev BP; Community perf #9 | `entities().generalization`; how System ancestors count | idea |
+| 17 | Data view / list view nested two or more levels (PERF002) | performance | Recommender MXP011 | `widgets()` widget_type strings, parent_widget_id | idea |
+| 18 | Commit without events on an entity with event handlers or validation rules (CORR001) | correctness | Setting Up Data Validation ("set With events to Yes") | `activities_for()` with_events / commit_type values; `entities().has_event_handlers` | idea |
+| 19 | Page title empty or default (UX003) | design | Accessibility introduction → meaningful page titles | `pages().title` default value (probe) | idea |
+| 20 | Page URL starts with a parameter, or two URLs conflict (CONV021) | correctness | General Dev BP → URLs | `pages().url` | idea |
+| 21 | Microflow prefix outside the Mendix list; MPR001 checks only the leading capital (CONV022) | naming | Naming Conventions BP prefix table | `microflows().name`; prefix list as config | idea |
+| 22 | Event-handler and scheduled-event microflow names match their trigger (CONV023) | naming | Naming Conventions BP (BCO_…ARO_, SCE_) | `entity_event_handlers()` moment/event; `scheduled_events()` microflow_name | idea |
+| 23 | Microflow returns System.Error / HttpResponse / SoapFault (ERR002) | correctness | Error Handling in Microflows | `microflows().return_type` spelling (probe) | idea |
+| 24 | Binary attribute instead of System.Image / FileDocument specialisation (DESIGN002) | design | Configuring a Domain Model | `attributes_for().data_type` value for binary (probe) | idea |
+| 25 | User role holds more than one module role of the same module (SEC013) | security | App Setup BP → user roles | `role_mappings()` | idea |
+| 26 | Exact-duplicate access rules on one entity (PERF003) | performance | Recommender MXP010 | `permissions()` grouped by entity + xpath_constraint | idea |
+| 27 | Non-persistable entity associated with System.User / System.Session (PERF004) | performance | Recommender MXP008 | `associations()` from/to; `entities().entity_type` | idea |
+| 28 | Log node empty or not the module name (LOG001) | quality | General Dev BP → logging; Logging refguide | `activities_for().log_node_expression` shape (literal vs constant) | idea |
+| 29 | Action buttons and inputs left on generated widget names (TEST001) | quality | ATS community + harness locator practice (mx-name) | `widgets().name`, widget_type | idea |
+| 30 | Index on sort / XPath / OData-key attributes | performance | Recommender MXP003, MXP007, MXP016 | an `indexes()` accessor (does not exist; upstream) | blocked: no index accessor |
+| 31 | Scheduled event not in UTC | correctness | Scheduled Events refguide | `scheduled_events().time_zone` values | skill (rule later, maybe) |
+
+### Notes from the 2026-10-08 review
+
+- CONV005 demands a `SNIPPET_` prefix, while Mendix's naming-conventions page says `SNIP_`. Every
+  Mendix-conventional app fails CONV005; settle before touching naming rules 21 and 22.
+- MPR001's prefix regex accepts any capitalised prefix (its prefix list is a comment, not a check), and the
+  list names `SCH_`/`SE_` where Mendix uses `SCE_`.
+- Stock rule ids are now MPR001-012 in the mxcli source; the generated project CLAUDE.md tables still say
+  MDL001-007.
+
 ## Cheap extras (one afternoon each, when a batch has room)
 
 Microflow not in a folder · non-persistent entity committed to the database · many-to-many
diff --git a/process/quality-sources-review-2026-10-08.md b/process/quality-sources-review-2026-10-08.md
new file mode 100644
index 00000000..400645eb
--- /dev/null
+++ b/process/quality-sources-review-2026-10-08.md
@@ -0,0 +1,143 @@
+# Quality-source review — 2026-10-08
+
+Review of Mendix quality-tooling sources (Best Practice Recommender, QSM/AQM public docs, ATS public docs,
+Menditect public docs, docs.mendix.com) against what the toolkit already enforces. Lintability was read from
+the mxcli lint source and no rule has been probed on a real model. Scan quotes were paraphrased, thresholds
+for QSM/Sigrid and Omnext rule text were not captured, and long pages were cut off, so "no source" means
+"not captured". The 19 proposed rows are in `process/lint-backlog.md` (Batch 4); the section letters below
+keep the original review's lettering.
+
+## B. Already covered
+
+| Practice | Source(s) | Covered by |
+|---|---|---|
+| Commit (and create/change-with-commit) inside a loop, batch at 1000 | aqm b1 MXP004/005, b6 #25; men S2 | CONV011 (stock); `microflow-loop-antipatterns.md`, `mdl-cookbook-microflows.md` |
+| Retrieve / delete / REST / Java call inside a loop | aqm b6 #26-27; men S1 | LOOP001 (Batch 1, in-flight); backlog row 4 |
+| Error handling on integration and Java calls | aqm b4; men S1; docs S1 | CONV013 (stock) |
+| Avoid Continue error handling | docs S1 | CONV014 (stock); ERR001 (in-flight) |
+| Always log the error, even when the process continues | aqm b4; men S1; docs S1, S2 | ERR001 (in-flight); backlog rows 1, 5, 6 |
+| Calculated attributes: on pages, unused, in general | aqm b1 MXP001/002, b4, b6 #4; docs S4 | CONV017 bans them outright (stricter than MXP001/002) |
+| Event handlers: use with caution | aqm b4, b6 #5; men S1 | CONV016 |
+| Validation via VAL_ flows, not entity rules | docs S12; aqm b5 VAL_ | CONV015; backlog extra "VAL_ returns Boolean"; `mdl-cookbook-microflows.md` |
+| Microflow size 25 elements / complexity | aqm b4; men S1, S22 | QUAL003 (25), CONV009 (15), QUAL001 McCabe |
+| Annotate complex microflows (>10 activities or >2 decisions) | aqm b4; men S1 | UX002 (in-flight, threshold 8 activities); CONV012 split captions; QUAL002 docs |
+| Unused / excluded documents | aqm b4; men S1 | QUAL004 orphaned elements; backlog row 3 (ACT_/page entry points) |
+| Anonymous users enabled (MXS003) | aqm b2 | SEC004 guest access |
+| Anonymous unconstrained read (MXS010), anonymous read on sensitive entities (MXS004, partly) | aqm b2 | SEC007; SEC008 for PII |
+| Security overview complete / entity without access rules | aqm b4; men S1 | SEC001, MPR007 nav page roles, backlog row 11 |
+| Strict mode / XPath on every access rule | aqm b6 #38 (adjacent) | SEC005, CONV007 |
+| Module role mapping (each module role → one user role) | aqm b7 #10 (reverse direction) | CONV008; backlog row 10 |
+| Naming: PascalCase entities/pages, ENUM_, page suffixes, booleans | aqm b5 | MPR001, CONV003, CONV004, CONV001 (see the SNIP_ conflict in F) |
+| Folder organisation | aqm b5 Folders | CONV018; `module-folder-convention.md` |
+| Domain model size per module, app size | aqm b4 App size | MPR003 per module (app-wide ceiling not checked, see C-29) |
+| ACT_ flows delegate, page actions give feedback | aqm b5 page microflows | CONV010, CONV020 (shipped) |
+| Data changes through microflows; business key | community perf, docs S3 | ARCH002, ARCH003 (shipped) |
+| Cross-module data access, module coupling (QSM "architecture") | men S6/S7 | ARCH001; graph builtins; `module-dependency-review.md`, `layering-review.md` |
+| Writes late in the flow (MXP014) | aqm b1; men S2 | `microflow-preflight.md` (not lintable, see C-30) |
+| Secrets in constant defaults / exposed to client | aqm b7 #11-13 | `project-bin/constants-audit.sh` + `learned-constants-and-secrets.md` |
+| Missing translations, required captions | docs S11 i18n | QUAL005, QUAL006 |
+| Studio Pro warnings, consistency | aqm b4; men S1 | `mx check` in `bin/exec.sh` / gates |
+| Overlapping activities, canvas layout | aqm b4 flow layout | MPR008, MPR011, `microflow-preflight.md` → Layout |
+| Workflow enum branches carry an Empty outcome | docs S10 (adjacent) | `workflow-structure-rules.md` |
+| Confirm before destructive action | docs S9 descriptive buttons (adjacent) | UX001 (in-flight) |
+| Unit testing exists, test levels | ats S24-S26; men S10, S17 | `testing-shape.md`, `learned-db-assertions.md` |
+| REST: log the response, then rethrow | docs S2 | `rest-integration-first-time-right.md` |
+
+## C. Candidates (deduplicated, by priority)
+
+Severity is `warning` for every proposed rule (lint-backlog rule 2). Rule IDs are placeholders.
+
+| id | practice | sources | lintable | proposal | prio | notes |
+|---|---|---|---|---|---|---|
+| C-01 | Anonymous user role is the administrator role | aqm b2 MXS005 | yes: `project_security()` anonymous_user_role, admin_user_role, enable_guest_access | Rule **SEC010 AnonymousRoleHygiene** (security), check 1 of 3 | P1 | Mendix calls it "almost certainly a configuration error"; zero false-positive risk; one comparison |
+| C-02 | Anonymous user role mapped to an Administration module role | aqm b2 MXS009 | yes: `user_roles()` is_anonymous, module_roles | SEC010, check 2 | P1 | Lets visitors manage accounts (also covers most of MXS007, which is not lintable on its own) |
+| C-03 | A non-System module role mapped to both anonymous and another user role | aqm b2 MXS008 | yes: `role_mappings()` + `user_roles().is_anonymous` | SEC010, check 3 | P1 | Granting the logged-in role silently grants the anonymous visitor too; FP only for deliberate public modules → `SKIP_MODULES` |
+| C-04 | Anonymous role can create, delete or write a member of a persistable entity | aqm b2 MXS006 | yes: `permissions()` access_type, member_name; `entities()` entity_type; role mapping | Rule **SEC011 AnonymousWrite** (security) | P1 | Probe the access_type vocabulary (CREATE/DELETE/WRITE spelling). Sign-up forms are the legitimate case, so report and let the project waive |
+| C-05 | Entity access grants default rights to new members | aqm b4 Default rights; men S1 | yes: `permissions()` default_member_access_rights | Rule **SEC012 DefaultMemberRights** (security) | P1 | New attributes silently inherit read/write; probe the value strings (None/ReadOnly/ReadWrite) |
+| C-06 | Generalization deeper than 2 levels | aqm b1 MXP009, b4, b6 #9; men S1/S2; docs S4 | yes: `entities()` generalization (walk the chain) | Rule **PERF001 InheritanceDepth** (performance) | P1 | Decide whether System.User → Administration.Account counts as a level (probably not: count from the first non-System ancestor). Joins grow per level |
+| C-07 | Data view / list view nested 2+ levels deep | aqm b1 MXP011; men S2 | yes: `widgets()` widget_type, parent_widget_id | Rule **PERF002 NestedDataContainers** (performance) | P1 | Mendix's own Recommender check. Probe the widget_type strings (DataView, ListView, Gallery?). `learned-page-patterns.md` already prefers a Context source for nested views, so cite it in the suggestion |
+| C-08 | Commit without events on an entity that has event handlers or validation rules | docs S12 | yes: `activities_for()` action_type, with_events, commit_type, entity_ref; `entities()` has_event_handlers, validation_rule_count | Rule **CORR001 CommitSkipsEntityLogic** (correctness) | P2 | Matters on existing apps (CONV015/016 keep new ones clean). FP: deliberate bulk imports → suggestion text names the trade-off |
+| C-09 | Page title empty or left as default | docs S8 Meaningful page titles | yes: `pages()` title | Rule **UX003 PageTitle** (design) | P2 | Accessibility and the browser tab. Probe what "default" looks like (empty string or "Page"?) |
+| C-10 | Page/microflow URL starts with a parameter, or two URLs conflict (same segment count, parameters in the same places) | aqm b4 URLs; men S1 | yes: `pages()` url | Rule **CONV021 PageUrlShape** (correctness) | P2 | Pairs with CONV019 (navigation pages addressable). Normalise `{x}` to `{}` before comparing |
+| C-11 | Microflow uses an UPPER_ prefix outside the Mendix list | aqm b5 (full prefix table) | yes: `microflows()` name | Rule **CONV022 MicroflowPrefixVocabulary** (naming), list configurable | P2 | MPR001's regex lets any capitalised prefix through: its prefix list is a comment, not a check. Missing from it: SCE_, CAL_, OEN_, OLE_, WFA_/WFS_/WFC_, TEST_/UT_, CWS_/CRS_/POS_, DCM_, BSD_, HCH_ |
+| C-12 | Event-handler microflow prefix matches its moment+event (BCO_/ACO_/BCR_/ACR_/BDE_/ADE_/BRO_/ARO_); scheduled-event microflow is SCE_ and named after its event | aqm b5 | yes: `entity_event_handlers()` moment, event, microflow; `scheduled_events()` name, microflow_name | Rule **CONV023 LifecycleMicroflowNames** (naming) | P2 | Mechanical and precise. Tells a reader that a flow fires implicitly |
+| C-13 | Microflow returns System.Error / HttpResponse / SoapFault | docs S1 | yes: `microflows()` return_type (probe its spelling) | Rule **ERR002 ErrorObjectReturned** (correctness) | P2 | Runtime supports one System.Error instance; returning one to a page/nanoflow breaks. Rare but cheap |
+| C-14 | Binary attribute instead of a System.Image / FileDocument specialisation | docs S3 | yes: `attributes_for()` data_type | Rule **DESIGN002 BinaryAttribute** (design) | P2 | Also a migration smell (legacy BLOB columns). Low FP |
+| C-15 | User role holds more than one module role of the same module | aqm b7 #10 | yes: `role_mappings()` | Rule **SEC013 OneModuleRolePerModule** (security) | P2 | Complements CONV008. FP: marketplace modules with additive roles → vendor exclusion at the gate |
+| C-16 | Duplicate access rules on one entity (same role set and XPath) | aqm b1 MXP010; men S2; docs S4 | yes for exact duplicates; partly for "overly varied" (`permissions()` xpath_constraint) | Rule **PERF003 DuplicateAccessRules** (performance) | P2 | Each rule adds an OR branch to every query |
+| C-17 | Non-persistable entity associated with System.User or System.Session | aqm b1 MXP008; men S2 | yes: `associations()` + `entities()` entity_type | Rule **PERF004 SessionCachedNPE** (performance) | P2 | Recommender check; FP when the NPE really is a per-session cache, which is exactly what Mendix warns about |
+| C-18 | Log node empty, or not the module name | aqm b4 Log node; men S1; docs S7 | yes: `activities_for()` log_node_expression, module_name | Rule **LOG001 LogNodeIsModule** (quality) | P2 | Configurable: accept a constant or `'Module'` literal. Supports ERR001 (a log nobody can filter is half a trace) |
+| C-19 | Widgets left on generated names (`actionButton3`, `textBox12`) | ats community "unique widget names", third-party "mx-name over generated IDs" | yes: `widgets()` name, widget_type | Rule **TEST001 StableWidgetNames** (quality), action buttons and inputs only | P2 | The e2e harness and ATS both locate by mx-name. Existing apps will report many; MDL-built pages report few. Ship scoped to buttons first |
+| C-20 | Index on sort, XPath and OData-key attributes of large entities | aqm b1 MXP003/007/016, b6 #3, #13-17; men S2; docs S4 | **no**: no index accessor, no record counts | Skill (E-1) + upstream ask for `indexes()` | P2 | The most-cited performance item across all scans, and the toolkit has no check at all ("none" in the best-practices index) |
+| C-21 | Scheduled events: chunked commits, idempotent, ≤10 in parallel per node, rename resets enabled state, UTC, no session edits, ProcessedQueueTask cleanup | aqm b6 #33; docs S6 | partly: `scheduled_events()` time_zone, on_overlap, interval_seconds | Skill (E-2); later maybe a rule on time_zone ≠ UTC | P1 (skill) | Backlog already lists "Scheduled events … nothing yet". These scans give the content |
+| C-22 | Atlas 4 theming: `$use-css-variables: true`, globals in `:root`, `var(--x)` not `$x`, color-mix() not darken() | docs S5 | no (SCSS files; shell grep possible) | Skill (E-3) | P2 | `design-artifacts.md` maps tokens to Atlas **SASS** variables (`$brand-primary`). That is Atlas 3 shape and breaks on Atlas 4 apps |
+| C-23 | Accessibility: alt text, no positive tabindex, labels, contrast 4.5:1 text / 3:1 non-text, visible focus, link text | docs S8 | no (no alt, tabindex or caption fields); contrast checkable in ds.css | Skill (E-4); contrast check is a ds.css shell candidate | P2 | No toolkit skill states contrast or focus rules today |
+| C-24 | Workflow targeting: group targeting by default, group tokens not Name, guard empty target lists, return type | docs S10 | no (workflow XPath not in `xpath_expressions()` document types) | Skill (E-5) | P2 | Empty target list fails the workflow at runtime |
+| C-25 | Test design: independent tests, teardown undoes changes, keep rollback on, no fixed sleeps | ats S7, S17, S24, S25, third-party | no | Skill (E-6) | P2 | Only `e2e-harness-base.md` mentions sleeps; nothing states teardown/isolation |
+| C-26 | Error-handling semantics: do not commit rolled-back objects; external calls are not reversed by rollback; Continue only on call/loop | docs S1 | no | Skill (E-7) | P2 | Behaviour facts agents get wrong; they fit the existing rollback section |
+| C-27 | Unit-test microflow shape: UT_/TEST_, returns nothing/Boolean/String, 0 params or one UnitTestContext | ats S24, S27; aqm b5 | partly: name, return_type, parameter_count (no parameter type) | Rule **TEST002 UnitTestShape** (correctness), only when a UnitTesting module exists | P3 | Wrong shape = test silently not discovered |
+| C-28 | More than 9 action buttons on a page | docs S9 | partly: `widgets()` widget_type per container (no visibility) | Rule **UX004 ButtonCount** (design) | P3 | Conditional visibility inflates the count |
+| C-29 | App beyond 3000 microflows / 750 entities | aqm b4; men S1 | yes: counts | Rule **DESIGN003 AppSize** (design), info-level | P3 | One finding per app; useful mainly in `app-analysis.md` |
+| C-30 | CUD activities near the start event | aqm b1 MXP014 | no: no activity order/position | stays in `microflow-preflight.md` | P3 | Upstream ask: expose sequence index |
+| C-31 | Negating access-rule pair (`not()` / `= false()` only difference) | aqm b1 MXP013; docs S4 | partly: `parse_xpath()` on xpath_constraint | Rule PERF005 | P3 | Parser edge cases; low frequency |
+| C-32 | XPath `not` / `!=` and costly parts left of `and` | aqm b1 MXP015, b6 #34; docs S4 | partly: `xpath_expressions()` + `parse_xpath()`; no volumes | Rule PERF006, or skill note | P3 | Only matters at 100k+ rows; noisy without volume data |
+| C-33 | Two associations between the same entity pair | aqm b6 #11 | yes: `associations()` | Rule DESIGN004 | P3 | Many legitimate (CreatedBy/AssignedTo → User); exclude System targets |
+| C-34 | Nested `if` inside one expression | aqm b4; men S1 | partly: split condition_expression only | Rule QUAL007 | P3 | Change/assign expressions not exposed |
+| C-35 | Drop-down for an enum of 2-5 values (use radio buttons) | docs S9 | partly: widget_type + attribute_ref; enum name per attribute unclear | Rule UX005 | P3 | Design preference, not a defect |
+| C-36 | Pop-up opened from a pop-up | docs S9 | partly: `pages()` has no layout; `refs_from()` page→layout may work | Rule UX006 after probing refs | P3 | Real UX defect, but needs a probe first |
+| C-37 | Debug never in production, Critical reserved, own log node names | docs S7 | no (runtime levels are environment config) | Skill note in `mdl-cookbook-microflows.md` logging | P3 | |
+| C-38 | Marketplace modules not modified | aqm b4; men S1 | no (needs a reference MPK) | Skill note in `existing-app-assurance.md` | P3 | |
+
+## E. Skill-only additions (non-lintable P1/P2)
+
+- **E-1 → `modularize-domain.md`** (indexes; also update the "none" cell in `mendix-best-practices-index.md`):
+  "Index every attribute used as a sort item, in an XPath on an entity expected past ~10k rows, or as a
+  published OData key. Lead with the most selective attribute, keep indexes under 3 attributes (max 5),
+  never two indexes with the same leading attribute, and skip Boolean/enum (MXP003/007/016)."
+- **E-2 → `microflow-loop-antipatterns.md` (new 'Scheduled events' section; route from `learned-microflow-patterns.md`)**:
+  "A scheduled-event flow commits in batches, survives a rerun after a crash (idempotent) and finishes
+  well inside its interval. No more than 10 events run at once per node. Renaming an event resets its
+  enabled state per environment, so re-check it after deploy. Use UTC, never change the session object, and
+  clean System.ProcessedQueueTask."
+- **E-3 → `design-artifacts.md`** (Atlas mapping table):
+  "On Atlas 4 (Atlas Core ≥4), map tokens to CSS custom properties in `:root` with
+  `$use-css-variables: true` first in `custom-variables.scss`. Use `var(--x)`, not `$x`, and `color-mix()`, not
+  darken()/lighten(). Declare only the values you override. The SASS-variable table is Atlas 3 only."
+- **E-4 → `ui-preflight-pages.md`** (and the wireframe checklist in `design-artifacts.md`):
+  "Every page has a meaningful title, every input a visible label, every informative image alt text, and every
+  decorative image `alt=''`. Text contrast is ≥4.5:1, buttons and inputs ≥3:1, focus is always visible and never
+  colour-only, there is no positive tabindex, and link text names its destination."
+- **E-5 → `learned-workflow-patterns.md`**:
+  "Target user tasks at workflow groups by default, and constrain on group tokens `[%WorkflowGroup_X%]`, not
+  Name. A targeting XPath or microflow that returns 0 objects fails the workflow, so guard the empty case. A due
+  date is a stored deadline, not a reminder."
+- **E-6 → `testing-shape.md`** (and `e2e-harness-base.md`):
+  "Tests share no data and run in any order. Setup only opens and logs in. Teardown undoes what the test changed.
+  Keep the Unit Testing rollback on. Wait for a condition, never a fixed sleep. Locate by mx-name and nothing else."
+- **E-7 → `learned-microflow-patterns.md`** (rollback section):
+  "A rollback does not undo REST/SOAP/Java calls already made. Do not commit an object the error flow just
+  rolled back, because Mendix no longer sees it as changed. Continue is only allowed on a call-microflow or a
+  loop, and the failing activity's own changes are always lost."
+
+## F. Not worth it / out of scope
+
+| Item | Source | Reason |
+|---|---|---|
+| Convert eligible microflows to nanoflows (MXP006) | aqm b1 | Eligibility needs a client-side call-site analysis; high FP; offline/security trade-offs |
+| Scheduled-event interval divisors, parameter-free flow, unique user-task names | docs S6, S10 | Studio Pro / `mx check` already refuse these; a rule duplicates a CE |
+| Line crossings, left-to-right layout | aqm b4 | Cosmetic; MPR008/MPR011 cover the harmful part |
+| Input validation on all microflow inputs | aqm b4 | Not checkable without data-flow analysis; VAL_/CONV015 route covers intent |
+| Microflow parameter count | aqm b4 | No threshold stated anywhere; would be invented |
+| Technical attributes with leading underscore; entities singular | aqm b5 | "Technical" and "plural" are not decidable from the model |
+| App/config naming, configuration DB passwords | aqm b7 | Settings/Portal concerns; constants-audit covers secrets |
+| Keep up with Mendix releases; community-supported components; open-source health | aqm b4; men S6/S7 | Portfolio/dependency scanning (QSM/Snyk), not model lint; `jar_dependencies()` has no vulnerability data |
+| QSM/Sigrid star ratings, ISO 25010 maintainability metrics | aqm b8; men S7-S9 | No thresholds were published or reachable, and benchmark recalibration makes them unportable |
+| ATS tool mechanics (recorder, selectors, SOAP CI API, schedules, licensing) | ats S3-S22 | About the end-of-sale tool, not the app model |
+| Maia units, network hosts, Logic/Workflow Recommender | docs S13; men S4/S5 | Product usage, not quality practice |
+| Denormalise, archive, more App Engines, proxy in front | aqm b6 #7-8, #43-44 | Architecture/ops judgement, no model signal |
+| Line length ≤9 words, single-column forms, green forward buttons | docs S9 | Style guidance; belongs in the wireframe review loop, not lint |
+
+**Contradictions surfaced (settle before the touching rule):**
+- Snippet prefix: the Mendix Naming Conventions say `SNIP_`, but stock CONV005 enforces `SNIPPET_`. Every Mendix-conventional app fails CONV005.
+- Microflow prefixes: MPR001 lists `SCH_`/`SE_` and its regex accepts any capitalised prefix. Mendix says `SCE_` and has about 15 prefixes that MPR001 does not list (C-11).
+- Size threshold: Mendix says 25 elements, CONV009 says 15 and QUAL003 says 25, and both rules ship. The index explains this, but anyone reading only a finding sees two thresholds.
diff --git a/skills/design-artifacts.md b/skills/design-artifacts.md
index 55661da0..ef7c21a8 100644
--- a/skills/design-artifacts.md
+++ b/skills/design-artifacts.md
@@ -191,7 +191,7 @@ Contents of `ds.css` + what `design-system.html` renders:
 - **Tokens as CSS custom properties:** brand ramp, accent, status (reserved), spacing, radius, type scale, shadow, motion — plus a full **light + dark** set. Dark mode is *selected* (its own steps), never an automatic flip. The selector depends on the theme machinery: on a project using **mxcli's theme system (≥ v0.20.0)**, the dark palette lives at `:root.theme-dark` (Atlas ships that class slot on `<html>`; mxcli's `--variant auto` follows `prefers-color-scheme` before first paint AND honours the class, and `theme switcher install` provides the user toggle) — declare dark *after* Mendix's own `_theme-dark.scss` or the app reverts to stock blue when the class lands. On a hand-themed Atlas project, use `[data-theme="dark"]` and avoid bare `prefers-color-scheme` — Atlas's own toggle conflicts with media-query-only dark mode. Either way the design system's *steps* stay selected, not auto-flipped.
 - **Data colors** come from the `dataviz` skill's validated palette — do not hand-pick chart/KPI colors; run its validator if you swap any.
 - **Components the app actually needs** (derive from the source screens, not a generic kit): buttons, inputs + validation, table/data grid with row actions, KPI/stat tiles, badges/status pills, dialog, toast, nav shell, plus any product-specific pieces.
-- **An Atlas mapping table:** each token → its Atlas SCSS variable (`$brand-primary`, `$background-color`, `$font-color`, `$border-radius-*`, `$spacing-*`, `$font-family-base`, success/warning/danger). This table is what the build phase turns into `theme/web/custom-variables.scss` + design properties.
+- **An Atlas mapping table:** each token → its Atlas SCSS variable (`$brand-primary`, `$background-color`, `$font-color`, `$border-radius-*`, `$spacing-*`, `$font-family-base`, success/warning/danger). This table is what the build phase turns into `theme/web/custom-variables.scss` + design properties. **The SASS-variable table is Atlas 3 only.** On Atlas 4 (Atlas Core >=4), map tokens to CSS custom properties in `:root` with `$use-css-variables: true` first in `custom-variables.scss`; use `var(--x)`, not `$x`, and `color-mix()`, not `darken()`/`lighten()`; declare only the values you override.
 
 **Render it and look at it** (headless-screenshot both light and dark) — the eye catches what code review misses. This is non-negotiable per the `dataviz` procedure.
 
@@ -336,6 +336,7 @@ with failures here does not pass to the build loop.
 
 - **Render every wireframe and look** (both themes).
 - **Coverage check** each faithful wireframe against its source screenshot: every visible field/section present, right widget type, right state. Gaps become explicit sub-tasks — the same discipline as the build loop's Step 11, applied one stage earlier so the spec is complete before building.
+- **Accessibility pass:** see `ui-preflight-pages.md` -> "Accessibility floor"; check it on the wireframe, not after the build.
 
 ---
 
diff --git a/skills/learned-microflow-patterns.md b/skills/learned-microflow-patterns.md
index 8be1f444..82e48a79 100644
--- a/skills/learned-microflow-patterns.md
+++ b/skills/learned-microflow-patterns.md
@@ -113,6 +113,8 @@ broken, and a database assertion alone would have called both working.** Neither
 the check; the pair is. It is the argument for keeping the journey rung and the OQL rung as two
 separate rungs rather than trusting whichever one is cheaper to run.
 
+**Rollback semantics.** A rollback does not undo REST/SOAP/Java calls already made. Do not commit an object the error flow just rolled back, because Mendix no longer sees it as changed. Continue is only allowed on a call-microflow or a loop, and the failing activity's own changes are always lost. Scheduled-event flows: see `microflow-loop-antipatterns.md` -> "Scheduled-event flows".
+
 ---
 
 ## Every Required Attribute Is Set BEFORE the Commit — One COMMIT, as Late as Possible
diff --git a/skills/learned-workflow-patterns.md b/skills/learned-workflow-patterns.md
index aa858660..f9fc6f90 100644
--- a/skills/learned-workflow-patterns.md
+++ b/skills/learned-workflow-patterns.md
@@ -253,6 +253,8 @@ TARGETING MICROFLOW MyModule."SUB_TargetReviewers"
 Such a microflow takes `$Workflow: System.Workflow` and `$Context: <your entity>`, and
 returns `List of System.User`.
 
+**Targeting defaults.** Target user tasks at workflow groups by default, and constrain on group tokens `[%WorkflowGroup_X%]`, not Name. A targeting XPath or microflow that returns 0 objects fails the workflow, so guard the empty case. A due date is a stored deadline, not a reminder.
+
 ---
 
 ## 6. Syntax reference: the workflow definition
diff --git a/skills/mendix-best-practices-index.md b/skills/mendix-best-practices-index.md
index 417addde..d6c2f73e 100644
--- a/skills/mendix-best-practices-index.md
+++ b/skills/mendix-best-practices-index.md
@@ -36,7 +36,7 @@ own Best Practice Recommender rules, which Studio Pro also reports.
 | Validation in `VAL_` flows, not entity rules | [Setting Up Data Validation](https://docs.mendix.com/refguide/setting-up-data-validation/), [Validation Rules](https://docs.mendix.com/refguide/validation-rules/) | §D Maintainability | `mdl-cookbook-microflows.md` | CONV015, MPR004 |
 | Event handlers and calculated attributes | [Best Practice Recommender](https://docs.mendix.com/refguide/performance-best-practices/) MXP001, MXP002 | §E Performance | `modularize-domain.md` | CONV016, CONV017 |
 | Entity access rules and XPath row scoping | [Access Rules](https://docs.mendix.com/refguide/access-rules/), [Implement Best Practices for App Security](https://docs.mendix.com/howto/security/best-practices-security/) | §C Security | `security-is-not-a-later-script.md` | SEC001, SEC004–SEC009, CONV006, CONV007, CONV008 |
-| Indexes for sort and XPath attributes | [Indexes](https://docs.mendix.com/refguide/indexes/), Recommender MXP003, MXP007, MXP016 | §E Performance | `modularize-domain.md` | none |
+| Indexes for sort and XPath attributes | [Indexes](https://docs.mendix.com/refguide/indexes/), Recommender MXP003, MXP007, MXP016 | §E Performance | `modularize-domain.md` | none (backlog 30, blocked: no index accessor) |
 | Module boundaries, cross-module data on pages | [Community Best Practices for App Performance](https://docs.mendix.com/refguide/community-best-practices-for-app-performance/) → Domain Model | §F Architecture | `modularize-domain.md`, `module-dependency-review.md` | ARCH001, ARCH002, ARCH003, MPR003, DESIGN001 |
 | Pages: nesting, grids, forms | [Community Best Practices for App Performance](https://docs.mendix.com/refguide/community-best-practices-for-app-performance/) → Pages, Recommender MXP011 | §I UI Best Practices | `ui-preflight-pages.md`, `learned-dg2-patterns.md`, `learned-page-patterns.md` | MPR005, MPR006, MPR009, MPR010, MPR012 |
 | Navigation page security | [Access Rules](https://docs.mendix.com/refguide/access-rules/) | §C Security | `security-is-not-a-later-script.md` | MPR007 |
diff --git a/skills/microflow-loop-antipatterns.md b/skills/microflow-loop-antipatterns.md
index cf709251..42aa4f91 100644
--- a/skills/microflow-loop-antipatterns.md
+++ b/skills/microflow-loop-antipatterns.md
@@ -111,6 +111,9 @@ finding on an enabled-reachable microflow is written first and sized first. Reac
 never on its own make a finding `high`, because nothing is running it today. Note the event by
 name in the row, so that switching it on is a decision somebody makes with this in front of them.
 
+### Scheduled-event flows (what the flow itself must do)
+A scheduled-event flow commits in batches, survives a rerun after a crash (idempotent) and finishes well inside its interval. No more than 10 events run at once per node. Renaming an event resets its enabled state per environment, so re-check it after deploy. Use UTC, never change the session object, and clean `System.ProcessedQueueTask`.
+
 ## Say what a loop body is, in the section, in words
 
 The reader of section 4 is a Mendix developer who has never seen this tool, or a manager who
diff --git a/skills/modularize-domain.md b/skills/modularize-domain.md
index 93c6693b..ee3f5115 100644
--- a/skills/modularize-domain.md
+++ b/skills/modularize-domain.md
@@ -67,6 +67,9 @@ If a candidate clears **none**, it does **not** get its own module.
 - One module mixing a customer-facing access domain with back-office data.
 - Distinct teams editing the same module and colliding.
 
+### Indexes
+Index every attribute used as a sort item, in an XPath on an entity expected past ~10k rows, or as a published OData key. Lead with the most selective attribute, keep indexes under 3 attributes (max 5), never create two indexes with the same leading attribute, and skip Boolean and enumeration attributes (Recommender MXP003/007/016).
+
 ---
 
 ## Step 3: Default to One Module + Folders
diff --git a/skills/testing-shape.md b/skills/testing-shape.md
index c12550c3..bdbfef12 100644
--- a/skills/testing-shape.md
+++ b/skills/testing-shape.md
@@ -283,6 +283,7 @@ human looking at the screenshot, not by the suite.
 - **Phone viewports:** a target can be attached and rendered but **below the fold**, where
   `isVisible()` is false and the click is skipped. `scrollIntoViewIfNeeded()` before the visibility
   check.
+- **Test isolation.** Tests share no data and run in any order. Setup only opens and logs in. Teardown undoes what the test changed. Keep the Unit Testing rollback on. Wait for a condition, never a fixed sleep. Locate by mx-name and nothing else (`e2e-harness-base.md` applies this to the harness).
 - **Do not scale up a speed multiplier** that divides hand-tuned waits. A pluggable combobox needing
   ~1200 ms to open its dropdown fails at 150 ms, and the resulting failures look completely real.
 
diff --git a/skills/ui-preflight-pages.md b/skills/ui-preflight-pages.md
index 5156845b..cfbf2658 100644
--- a/skills/ui-preflight-pages.md
+++ b/skills/ui-preflight-pages.md
@@ -193,6 +193,8 @@ rule applies and that MCP will handle it as a follow-up.
 
 ---
 
+**Accessibility floor.** Every page has a meaningful title, every input a visible label, every informative image alt text, and every decorative image `alt=''`. Text contrast is >=4.5:1, buttons and inputs >=3:1, focus is always visible and never colour-only, there is no positive tabindex, and link text names its destination.
+
 ### Step 5 — Run the shell check before you exec (mechanical, seconds)
 
 Steps 1–4 are judgement and they are the substance. This step is the part a script can

From ab346f723cbd88ac2949483bfd969ba01c614a4b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:11:58 +0000
Subject: [PATCH 16/19] fix(lint): CONV020 default scope "*" and page actions
 count as feedback (#229, #245)

PROJECT_MODULES defaults to "*" (all modules the lint run includes, vendor
list excluded by lint-gate) so a fresh install is no longer inert.
ShowPage/ClosePage/ShowHomePage count as feedback (presence only; action_type
strings verified against the mxcli catalog builder). lint-gate --update-baseline
drops _rule findings. Install-time module derivation not done: the existing
vendor-exclusion mechanism makes it unnecessary.

Checks: bash -n lint-gate.sh, tests/test-lint-delivery.sh (ALL GREEN, updated
for the new default), test-stock-hashes.sh (16/0), leak guard, portability,
check-scripts. Starlark behaviour fixture NOT added/run: no mxcli binary or
rule runner in this repo.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                                 |  1 +
 lint-rules/README.md                         |  5 +--
 lint-rules/conv020_action_user_feedback.star | 34 ++++++++++++--------
 project-bin/lint-gate.sh                     |  7 ++++
 tests/test-lint-delivery.sh                  |  2 +-
 5 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..56e9c2c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(lint): **CONV020 works out of the box and counts page navigation as feedback.** `PROJECT_MODULES` now defaults to `"*"` (every module the lint run includes, minus `.claude/lint-vendor-modules.txt`) instead of an empty tuple that made a fresh install inert; ShowPage/ClosePage/ShowHomePage actions count as user feedback (presence only; refresh-in-client is not exposed by mxcli, noted in the rule header). `lint-gate.sh --update-baseline` no longer baselines `_rule` (self-reported blindness) findings. Starlark fixture not run: no mxcli binary or rule runner in this repo; installer fixture `test-lint-delivery.sh` green (#229, #245) — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/lint-rules/README.md b/lint-rules/README.md
index c6182c00..3cca40ca 100644
--- a/lint-rules/README.md
+++ b/lint-rules/README.md
@@ -7,7 +7,7 @@ and configure the marked constants — **after** running `mxcli init`, never bef
 | Rule | What it catches | Configure? |
 |---|---|---|
 | `conv010_act_microflow_content.star` | `ACT_` page-action microflows holding business logic instead of delegating to `SUB_` | if your prefixes differ — `ACTION_PREFIX`, `DELEGATE_PREFIX` |
-| `conv020_action_user_feedback.star` | Page-triggered microflows that commit / import / delete but tell the user nothing | **yes** — `PROJECT_MODULES`, and `ACTION_PREFIX` if your prefixes differ |
+| `conv020_action_user_feedback.star` | Page-triggered microflows that commit / import / delete but tell the user nothing | no — `PROJECT_MODULES` defaults to `"*"` (all modules the lint run includes, minus `.claude/lint-vendor-modules.txt`); `ACTION_PREFIX` if your prefixes differ |
 | `data_change_microflows.star` | ARCH002 — persistent entities written from pages instead of microflows | no |
 | `entity_business_key.star` | ARCH003 — persistent entities with no UNIQUE NOT NULL business key | no |
 
@@ -37,7 +37,7 @@ convention: on a project that names things differently both rules matched nothin
 nothing, and reported a clean pass.
 
 Both now emit a `_rule` finding when the prefix matches zero microflows (CONV010 guards on the
-project having any microflows at all; CONV020 on `PROJECT_MODULES` containing any). Verified by
+project having any microflows at all; CONV020 on `PROJECT_MODULES` being non-empty and containing any). Verified by
 fixture on TestCLIApp — setting `ACTION_PREFIX` to an unused string produces the finding, and
 the real prefix produces none. `bin/lint-gate.sh` treats `module == "_rule"` as blindness, so
 this turns a silent pass into a gate failure rather than a line in a report nobody reads.
@@ -149,6 +149,7 @@ If yes, it needs a self-check before it is worth installing.
 
 `CONV020` deliberately ignores retrieves, changes without commit, non-page-reachable
 microflows, and validation-only paths. It flags roughly what a reviewer would flag by hand.
+Show-page, close-page and show-home-page actions count as feedback (presence only, not order). Refresh-in-client is not visible to the Starlark API, so a flow that only refreshes is still flagged until mxcli exposes it.
 A rule that fires on everything gets switched off, and a switched-off rule catches nothing —
 which is how `CONV010` and the lint gate both ended up idle.
 
diff --git a/lint-rules/conv020_action_user_feedback.star b/lint-rules/conv020_action_user_feedback.star
index 5281b454..01d881b5 100644
--- a/lint-rules/conv020_action_user_feedback.star
+++ b/lint-rules/conv020_action_user_feedback.star
@@ -1,7 +1,8 @@
 # mxtk-lint-rule: conv020_action_user_feedback
-# Shipped by mxcli-project-toolkit. UNLIKE the other rules here this one is MEANT to be
-# edited: PROJECT_MODULES must name the modules this project owns, or the rule inspects
-# nothing and says so. sync-project.sh therefore installs it once and never refreshes it;
+# Shipped by mxcli-project-toolkit. UNLIKE the other rules here this one MAY be edited:
+# PROJECT_MODULES defaults to "*" (every module the lint run includes, i.e. all but those
+# in .claude/lint-vendor-modules.txt); narrow it to a tuple to scope the rule down.
+# sync-project.sh installs it once and never refreshes it;
 # when the template changes it reports the change and leaves your configured copy alone.
 # See lint-rules/README.md.
 # --- end mxtk-lint-rule header ---
@@ -41,14 +42,14 @@ SEVERITY = "warning"
 
 REQUIRES = ["full"]
 
-# CONFIGURE ME. Only lint modules this project owns -- everything else is Marketplace
-# or vendor content you do not author and cannot fix. Leaving this empty does not make
-# the rule lint everything; it makes the rule refuse to run (see the guard in check()),
-# because a rule that silently inspects nothing is worse than no rule.
+# "*" (default) = every module this lint run includes. project-bin/lint-gate.sh passes
+# .claude/lint-vendor-modules.txt as an exclusion, so Marketplace/vendor content is already
+# out of scope there. Set a tuple of names to narrow it, e.g. ("Sales", "Orders"); an empty
+# tuple makes the rule refuse to run (see the guard in check()) rather than pass silently.
 #
-# List them with:
+# List modules with:
 #   ./mxcli -p <project>.mpr -c "SHOW MODULES"
-PROJECT_MODULES = ()
+PROJECT_MODULES = "*"
 
 # Work was actually completed and persisted.
 STATE_CHANGE_ACTIONS = (
@@ -61,6 +62,13 @@ STATE_CHANGE_ACTIONS = (
 FEEDBACK_ACTIONS = (
     "ShowMessageAction",
     "ValidationFeedbackAction",
+    # Navigating the user to a page, or closing the current one, is visible feedback.
+    # Presence only: flow order is not visible to this API, so a page opened BEFORE the
+    # commit also counts. Refresh-in-client is NOT detectable (not exposed by mxcli as an
+    # activity field) -- upstream ask; until then a flow that only refreshes is flagged.
+    "ShowPageAction",
+    "ClosePageAction",
+    "ShowHomePageAction",
 )
 
 MAX_CALL_DEPTH = 3
@@ -102,17 +110,17 @@ def check():
     # UNCONFIGURED GUARD. Ships from the toolkit with an empty module list. Without
     # this, an uncustomised copy inspects zero microflows and reports a clean pass --
     # the exact silent-false-pass shape this rule's self-check exists to prevent.
-    if not PROJECT_MODULES:
+    if not PROJECT_MODULES:  # empty tuple/string only; "*" is truthy
         return [violation(
-            message="CONV020 is unconfigured: PROJECT_MODULES is empty, so this rule inspected NOTHING. It was installed from the toolkit template and never customised for this project.",
+            message="CONV020 is unconfigured: PROJECT_MODULES is empty, so this rule inspected NOTHING.",
             location=location(module="_rule", document_type="Microflow", document_name="CONV020"),
-            suggestion="Edit PROJECT_MODULES at the top of this rule to list the modules this project owns (`SHOW MODULES`), excluding Marketplace and vendor modules.",
+            suggestion="Set PROJECT_MODULES at the top of this rule to "*" (all non-vendor modules) or to a tuple of module names.",
         )]
 
     # Which microflows are called directly from a page, and which from a nanoflow.
     # Starlark has no recursion, so the call graph is walked with a bounded frontier.
     for mf in microflows():
-        if mf.module_name not in PROJECT_MODULES:
+        if PROJECT_MODULES != "*" and mf.module_name not in PROJECT_MODULES:
             continue
 
         in_scope += 1
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index a2e7069c..e11b2009 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -189,6 +189,13 @@ if crashed:
     viol = [v for v in viol if v["ruleId"] not in crashed]
     counts = collections.Counter(v["ruleId"] for v in viol)
 
+# Self-reported blindness (module "_rule") is likewise never baselined: a rule that said it
+# inspected nothing would otherwise be ratcheted as accepted debt (#229). Later runs still
+# report it as PASS-BLIND via `blind` above, which was computed before this filter.
+if update:
+    viol = [v for v in viol if v.get("module") != "_rule"]
+    counts = collections.Counter(v["ruleId"] for v in viol)
+
 if update:
     json.dump({"counts": dict(sorted(counts.items())),
                "total": len(viol),
diff --git a/tests/test-lint-delivery.sh b/tests/test-lint-delivery.sh
index 2e0c457d..ec558926 100755
--- a/tests/test-lint-delivery.sh
+++ b/tests/test-lint-delivery.sh
@@ -89,7 +89,7 @@ ls "$R"/*.local-* >/dev/null 2>&1 && grep -q "LOCAL TUNING" "$R"/*.local-* \
 rm -f "$R"/*.local-*
 
 echo "== 8 configured conv020 is left alone, silently =="
-sed 's/^PROJECT_MODULES = ()/PROJECT_MODULES = ("MyModule",)/' "$C" > "$C.t" && mv "$C.t" "$C"
+sed 's/^PROJECT_MODULES = "\*"/PROJECT_MODULES = ("MyModule",)/' "$C" > "$C.t" && mv "$C.t" "$C"
 out=$(mxtk_install_lint_rules "$W/tk" "$P" 0 "" 2>&1)
 [ -z "$out" ] && ok "silent" || no "noisy about the expected state"
 grep -q 'PROJECT_MODULES = ("MyModule",)' "$C" && ok "config survived" || no "CONFIG WIPED"

From 6c84fd2f765ac3bed35deca73a250057c1f1c975 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:13:16 +0000
Subject: [PATCH 17/19] fix(e2e): journey-runner rung 2 runs for
 mustNotFire-only spans (#150)

Rung 2 required a non-empty spans.ordered, so a step proving only that a
microflow did NOT fire was skipped with no output. Gate is now ordered OR
mustNotFire non-empty; assertSequence only runs when ordered is non-empty.
Checks: node --check ok; gate-condition probe over 5 span shapes; no live
Jaeger run available, so no end-to-end execution. Selftest covers otel
assertions only and does not exercise the runner loop.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                        |  1 +
 project-tests/e2e/journey-runner.js | 12 ++++++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..ebedc9c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(e2e): **journey-runner rung 2 now runs for a negative-only span claim.** `spans: { ordered: [], mustNotFire: [...] }` was skipped silently because the rung required a non-empty `ordered`; it now runs when either list is non-empty (sequence assert only when `ordered` is non-empty). Zero captured spans still reports INVALID (a vacuous negative is not proof). Verified by `node --check` and a gate-condition probe, no live Jaeger run (#150) — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/project-tests/e2e/journey-runner.js b/project-tests/e2e/journey-runner.js
index d0140248..b4bd118b 100644
--- a/project-tests/e2e/journey-runner.js
+++ b/project-tests/e2e/journey-runner.js
@@ -740,9 +740,12 @@ async function runJourney(page, j) {
     }
 
     // ── RUNG 2: ordered spans ────────────────────────────────────────────────
-    if (step.spans && step.spans.ordered && step.spans.ordered.length) {
+    // Runs for a positive claim (ordered) OR a negative-only claim (mustNotFire with
+    // ordered empty/absent) — a step whose whole proof is "this did NOT run" (#150).
+    const claimed = (step.spans && step.spans.ordered) || [];
+    const mustNot = (step.spans && step.spans.mustNotFire) || [];
+    if (claimed.length || mustNot.length) {
       // Wait for the claimed microflows, not just any span — see otel.js capture() `until`.
-      const claimed = step.spans.ordered;
       const spans = await O.capture(t0, { min: 1,
         until: sp => { const got = O.microflowNames(sp); return claimed.every(n => got.includes(n)); } });
       if (!spans.length) {
@@ -750,9 +753,10 @@ async function runJourney(page, j) {
                'zero spans captured — Jaeger down or OTel off. Trace rung did NOT run.', req);
       } else {
         O.guard(spans, otelReporter(req), `${step.name}: capture non-empty`);
-        O.assertSequence(spans, step.spans.ordered, otelReporter(req), `${step.name}: ordered`);
+        if (claimed.length)
+          O.assertSequence(spans, claimed, otelReporter(req), `${step.name}: ordered`);
         O.assertNoErrors(spans, otelReporter(req), `${step.name}: no ERROR at any level`);
-        for (const n of step.spans.mustNotFire || []) {
+        for (const n of mustNot) {
           O.assertNotFired(spans, new RegExp(n), otelReporter(req), `${step.name}: ${n} did not run`);
         }
       }

From 9dbe0c26897b39675eff4e21208b3cd549df2499 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:14:02 +0000
Subject: [PATCH 18/19] fix(gates): surface status, realpath source root,
 JOURNEY_DIR token (#233 #234 #235)

#233: new test_surface_hit() in gate-check.sh is the one test behind check_stage_6 and the
Surface column, so the harness pair (docs/verification/report.html + docs/report.json)
no longer reads MISSING while the gate passes.
#234: source-sufficiency report title uses realpath basename, so "." / trailing slash
no longer yield an empty or "." title.
#235: artifact-manifest.tsv accepts a ${JOURNEY_DIR} token; artifact-check.sh resolves it
via project-bin/_common.sh (env > toolkit.env > ~/.mxcli-toolkit.env > journeys/), relative
or absolute. Ad-hoc checked: default, relative env, absolute env, toolkit.env file.
No golden-input capture applies (no parser added).

Checks: bash -n; check-portability, check-no-client-data (leak guard), check-scripts,
check-pr-discipline; fixtures test-source-sufficiency (51/0), test-source-sufficiency-gate
(7/0), test-bug03-gates (31/0), test-wrong-verdicts (20/0).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                  |  1 +
 bin/gate-check.sh             | 32 ++++++++++++++++++++------------
 bin/lib/artifact-check.sh     | 28 +++++++++++++++++++++++++---
 bin/lib/artifact-manifest.tsv |  6 +++++-
 bin/source-sufficiency.sh     |  2 +-
 5 files changed, 52 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df3d67a9..2e93f621 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(gates): **Stage 6 Surface agrees with the gate, source-sufficiency title resolves `.`, journeys artifact row honours `JOURNEY_DIR`.** `test_surface_hit()` is now the one test behind both check_stage_6 and the Surface column (#233); the report title takes the realpath basename (#234); the manifest accepts a `${JOURNEY_DIR}` token resolved like verify-module.sh (#235). Field run 2026-10-08, existing app — MendixMau
 - perf(routing): **CLAUDE.local.md routing carries triggers only.** The `baseline` view (the copy loaded into every session of every project) now cuts each row's "when" cell at its first " — " and replaces the three-paragraph preamble with two lines pointing at `ROUTING.md` for the full text; `readme-baseline` (README, runbook) is unchanged. Fresh scaffold: CLAUDE.local.md 17.5 KB → 11.7 KB (−33%). Field run 2026-10-07 (existing app, one main session per run, 2 runs per side, an entity + 2 microflows + 2 pages): 10/10 steps applied each side, new mx errors 5 vs 5 (the same CE2421 page-binding slip in both), cost $1.39 vs $1.38; the slim lanes opened the MDL pre-flight skill as often or more. Also drops two stray merge-artifact lines from this section. — MendixMau
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/bin/gate-check.sh b/bin/gate-check.sh
index c1772943..d4705782 100755
--- a/bin/gate-check.sh
+++ b/bin/gate-check.sh
@@ -1315,21 +1315,26 @@ EOF
   fi
 }
 
-check_stage_6() {
-  local f test_ok="" review_ok=""
+# The one test for "is there a test surface?" — check_stage_6 and the dashboard's Surface
+# column both call it, so the gate and the column cannot disagree about one file (#233).
+# Accepts test-report.html (root or reports/, project or analysis base) OR the harness pair
+# verify-module.sh's render rung produces: docs/verification/report.html rendered FROM
+# docs/report.json. Both halves must be present — accepting one without the other would accept
+# a surface whose machine half is gone. (Before this, test-report.html was the only accepted
+# name and nothing in the toolkit generated it, so Stage 6 was structurally unpassable —
+# improvement-plan Finding 14 / P9.)
+test_surface_hit() {
+  local f
   for f in "$PROJECT_DIR/test-report.html" "$PROJECT_DIR"/reports/test-report.html \
            "$ANALYSIS_BASE/test-report.html" "$ANALYSIS_BASE"/reports/test-report.html; do
-    [ -s "$f" ] && test_ok=1
+    [ -s "$f" ] && return 0
   done
-  # The harness's own surface also satisfies the test half: verify-module.sh's final render
-  # rung produces docs/verification/report.html from docs/report.json (report-render.js /
-  # report-normalize.js). Both halves must be present — the HTML is rendered FROM the JSON,
-  # and accepting one without the other would accept a surface whose machine half is gone.
-  # Before this, test-report.html was the only accepted name and nothing in the toolkit
-  # generated it, so Stage 6 was structurally unpassable (improvement-plan Finding 14 / P9).
-  if [ -s "$PROJECT_DIR/docs/verification/report.html" ] && [ -s "$PROJECT_DIR/docs/report.json" ]; then
-    test_ok=1
-  fi
+  [ -s "$PROJECT_DIR/docs/verification/report.html" ] && [ -s "$PROJECT_DIR/docs/report.json" ]
+}
+
+check_stage_6() {
+  local test_ok="" review_ok=""
+  test_surface_hit && test_ok=1
   # module-review.md report — any non-empty dated report under a ui-reviews/ dir
   if [ -n "$(find_artifact -path '*/ui-reviews/ui-review-*.html' -size +0c)" ]; then
     review_ok=1
@@ -1706,6 +1711,9 @@ stage_surface_status() {
   fi
   for pat in $pats; do
     hit=0
+    # test-report.html is answered by the same function check_stage_6 uses (#233), so the
+    # harness report pair also discharges it.
+    if [ "$pat" = "test-report.html" ] && test_surface_hit; then continue; fi
     # SURFACE_BASES, not just the project root. §2's Surface cells are inconsistent about
     # paths: some carry one ("architecture/blueprint.html", "docs/report.json") and some name
     # the file bare ("design-system.html", "build-plan.html", "test-report.html"). A bare cell
diff --git a/bin/lib/artifact-check.sh b/bin/lib/artifact-check.sh
index e2f5ee6a..7da2fa3e 100755
--- a/bin/lib/artifact-check.sh
+++ b/bin/lib/artifact-check.sh
@@ -189,9 +189,29 @@ _art_newer() {
 }
 
 # resolve_artifact() already serves.
+
+# Resolve the ${JOURNEY_DIR} manifest token (#235) with verify-module.sh's own precedence
+# (env > <root>/.claude/toolkit.env > ~/.mxcli-toolkit.env > <root>/journeys) by sourcing
+# project-bin/_common.sh in a subshell with PROJECT_ROOT pinned. Prints a path relative to the
+# root when it lies under it, otherwise as given (absolute); falls back to "journeys".
+_art_journey_dir() {
+  local root="$1" common="$_ART_LIB_DIR/../../project-bin/_common.sh" jd=""
+  if [ -f "$common" ]; then
+    jd="$( export PROJECT_ROOT="$root"; . "$common" >/dev/null 2>&1; printf '%s' "${JOURNEY_DIR:-}" )" || jd=""
+  else
+    jd="${JOURNEY_DIR:-}"
+  fi
+  jd="${jd:-journeys}"; jd="${jd%/}"
+  case "$jd" in "$root"/*) jd="${jd#"$root"/}" ;; esac
+  printf '%s' "$jd"
+}
+
 _art_find() {
-  local root="$1" paths="$2" pat base f rest
+  local root="$1" paths="$2" pat base f rest jd
   ART_HIT=""; ART_EMPTY=""
+  case "$paths" in
+    *'${JOURNEY_DIR}'*) jd="$(_art_journey_dir "$root")"; paths="${paths//\$\{JOURNEY_DIR\}/$jd}" ;;
+  esac
   rest="$paths"
   while [ -n "$rest" ]; do
     pat="${rest%%|*}"
@@ -207,8 +227,10 @@ _art_find() {
     # defect, same day, as the one fixed in obligation-check.sh's `_ob_find`, where it DID
     # change the verdict.
     local newest_hit=""
-    for base in "$root" "$root"/analysis/*; do
-      [ -d "$base" ] || continue
+    local bases=("$root" "$root"/analysis/*)
+    case "$pat" in /*) bases=("") ;; esac   # absolute (a JOURNEY_DIR outside the root)
+    for base in "${bases[@]}"; do
+      [ -z "$base" ] || [ -d "$base" ] || continue
       # base quoted, pattern not: the base must survive spaces, the pattern must glob.
       for f in "$base"/$pat; do
         [ -e "$f" ] || continue
diff --git a/bin/lib/artifact-manifest.tsv b/bin/lib/artifact-manifest.tsv
index b830de02..93c912ab 100644
--- a/bin/lib/artifact-manifest.tsv
+++ b/bin/lib/artifact-manifest.tsv
@@ -36,6 +36,10 @@
 #                 ANALYSIS_BASE serves). Alternatives exist where real projects legitimately
 #                 differ (the three ledger shapes of skills/coverage-ledger.md §"Where the
 #                 ledger lives"), never as a hedge against not knowing the convention.
+#                 A path may start with the token ${JOURNEY_DIR}: artifact-check.sh resolves it the
+#                 way verify-module.sh does (env > .claude/toolkit.env > ~/.mxcli-toolkit.env >
+#                 journeys/), so a project keeping journeys elsewhere is judged where its journey
+#                 rung actually reads them (#235).
 #   4 producer    the skill step or script that emits it — the thing a PENDING row tells you
 #                 to run
 #   5 consumers   the citations that earn the row its place (see above)
@@ -92,7 +96,7 @@ build-plan-json	4	architecture/build-plan.json	project-bin/build-plan-status.sh
 module-brief	4	architecture/modules/*/module-brief.md|architecture/modules/*-brief.md	skills/module-brief.md — ba-agent writes the first at Stage 4, the rest just-in-time	bin/gate-check.sh:1121 (build-ready fails without one), project-bin/build-plan-status.sh:109	migration,requirements,existing-app-change	gate
 coverage-ledger	4	architecture/modules/*/coverage-ledger.md|architecture/modules/*-coverage-ledger.md|architecture/coverage-ledger.md	skills/coverage-ledger.md procedure at Stage 4 (BRD leaves × build-plan claims); the three shapes are §"Where the ledger lives", first canonical	project-bin/conformance-check.sh:85-93, project-bin/coverage-preflight.sh:134-137, project-bin/verify-module.sh:299-300, project-bin/review-module.sh:289, conversion-runbook.md:487 (Stage-4 produces row) — the eleven-consumers-no-producer artifact of improvement-plan Finding 12	migration,requirements	report
 ui-reviews	5	design/ui-reviews/ui-review-*.html	skills/module-review.md pass (review-agent), one report per module close-out	bin/gate-check.sh:984 (check_stage_6), bin/lib/obligations.tsv:47 (the look row — per-module coverage and denominators live THERE; this row only asks whether the stage produced any report at all)	migration,requirements,greenfield,existing-app-change	gate
-journeys	5	journeys/*.journey.json	journey authoring per skills/testing-shape.md / skills/journey-proof.md (worked example: project-tests/e2e/example.journey.json)	project-bin/verify-module.sh:376,404 (the journeys rung), project-tests/e2e/journey-runner.js:5	migration,requirements,greenfield,existing-app-change	report
+journeys	5	${JOURNEY_DIR}/*.journey.json	journey authoring per skills/testing-shape.md / skills/journey-proof.md (worked example: project-tests/e2e/example.journey.json)	project-bin/verify-module.sh:376,404 (the journeys rung), project-tests/e2e/journey-runner.js:5	migration,requirements,greenfield,existing-app-change	report
 page-scope	5	.claude/loop/page-scope.json	project-bin/page-scope.sh (the phantom of improvement-plan Finding 15 until 078c7d8 shipped it)	project-tests/e2e/design-audit.js:55, project-tests/e2e/page-audit.js:66, project-tests/e2e/report-normalize.js:112 — without it the LOOK instruments degrade to --static-only	migration,requirements,greenfield,existing-app-change	report
 lint-last	5	.claude/loop/lint-last.json	project-bin/lint-gate.sh (written on every run that reaches a verdict, not only --update-baseline), run as part of skills/module-review.md stage 2 GATE ("bin/exec.sh; gate-agent confirms 0 mxbuild errors, lint clean" — same step named in skills/iterative-build-loop.md's "Gate: BUILD")	bin/status.sh:75-81,129 (the OVERDUE line's lint readout — without it status.sh reports "lint gate never recorded here")	migration,requirements,greenfield,existing-app-change	report
 improvement-register	5	docs/improvement-register.md	skills/improvement-register.md:39 (append-only, one row per finding, written during build/verify passes)	project-bin/build-plan-status.sh:69,148 (the proven-vs-built cross-reference), skills/close-the-loop.md	migration,requirements,greenfield,existing-app-change	report
diff --git a/bin/source-sufficiency.sh b/bin/source-sufficiency.sh
index cb50d41e..016b2218 100755
--- a/bin/source-sufficiency.sh
+++ b/bin/source-sufficiency.sh
@@ -622,7 +622,7 @@ if html_out:
     src_list = ''.join(f'<li><code>{esc(os.path.basename(s))}</code></li>' for s in sources) \
                or '<li>no source files named</li>'
 
-    page = f"""<title>Source sufficiency — {esc(os.path.basename(os.environ.get('PROJECT_DIR','')))}</title>
+    page = f"""<title>Source sufficiency — {esc(os.path.basename(os.path.realpath(os.environ.get('PROJECT_DIR',''))))}</title>
 <style>
   /* Neutrals are slate-biased rather than pure grey so the four semantic hues read as data.
      The accent is used ONLY for the recommendation; severity never borrows it. */

From d3f198535250ea14a3abee6f558efefaa48daf28 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 15:34:33 +0000
Subject: [PATCH 19/19] test(sync): neutral wording for the field evidence in
 the dup-heading fixture

The fixture header named consuming projects by client name; the public
toolkit cites field runs without naming clients.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                              | 2 +-
 tests/wave2/test-sync-dup-heading-exit.sh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61b81c44..28905e8a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(sync): **`sync-project.sh` no longer exits 1, silently, before its `bin/` and `tests/e2e/` refresh.** The CLAUDE.md duplicate-routing check (section 3) looked up the "mxcli-project-toolkit Integration" heading with an unguarded `grep | head | cut` under `set -euo pipefail`; when CLAUDE.md cites `skills/query-the-model.md` or `skills/learned-mdl-preflight.md` without that heading, which is every CLAUDE.md mxcli init v0.25 writes, grep's exit 1 ended the script with no message. Every step after it never ran: the crash-net refresh, the tests/e2e install and the lint-rule restore. Introduced by 9a0350b (2026-09-18). Now `|| true`, and `ledger_row_prefix` gets the same guard. Field: three consuming projects (TramiusECI, TramiusSCR, TramiusSVC, 2026-10-07): the dry run went from exit 1 after "Would rewrite: CLAUDE.md" to exit 0 listing 7 and 8 skipped `bin/` refreshes. New fixture `tests/wave2/test-sync-dup-heading-exit.sh` (4 of 6 fail on the pre-fix script). — TramiusECI session
+- fix(sync): **`sync-project.sh` no longer exits 1, silently, before its `bin/` and `tests/e2e/` refresh.** The CLAUDE.md duplicate-routing check (section 3) looked up the "mxcli-project-toolkit Integration" heading with an unguarded `grep | head | cut` under `set -euo pipefail`; when CLAUDE.md cites `skills/query-the-model.md` or `skills/learned-mdl-preflight.md` without that heading, which is every CLAUDE.md mxcli init v0.25 writes, grep's exit 1 ended the script with no message. Every step after it never ran: the crash-net refresh, the tests/e2e install and the lint-rule restore. Introduced by 9a0350b (2026-09-18). Now `|| true`, and `ledger_row_prefix` gets the same guard. Field: three consuming projects of one organisation (2026-10-07): the dry run went from exit 1 after "Would rewrite: CLAUDE.md" to exit 0 listing 7 and 8 skipped `bin/` refreshes. New fixture `tests/wave2/test-sync-dup-heading-exit.sh` (4 of 6 fail on the pre-fix script). — MendixMau (field run, existing apps)
  perf/faster-ui-loop
 - perf(ui-loop): **fewer mxbuilds, no fixed sleeps, legible screenshots.** Field run 2026-10-07 (a requirements-driven build): `exec.sh` was 22% of tool time at two mxbuilds per exec, journeys and page waits slept a fixed time, and screenshots were 11.5% of re-read tokens. `exec.sh` now skips the pre-flight baseline mxbuild when the model is byte-identical to its last *clean* pass: the verification stamp gains an `errors:` field (`model-stamp.sh check --clean` accepts only `errors: 0`, so a delta-gate pass over pre-existing errors never counts; `SKIP_BASELINE=0` is unchanged). New `tests/e2e/settle.js` waits for the page's own state (no visible Mendix progress/loading indicator, DOM size stable) instead of a fixed time; `journey-runner.js` uses it after each action (an explicit `settleMs` still wins) and `page-audit.js` per page. Probed in a real browser: on a page that loads in 1.8 s the old 1200 ms sleep and networkidle+600 both captured it half-loaded, settle waited for it; on a fast page settle took 775 ms vs 1200. `SETTLE_MODE=fixed` restores the old waits for an A/B run. `page-audit.js` also saves a viewport shot `page-audit-<Page>.top.png` beside the full-page one, and `ui-loop.md` says to look at viewport shots: a tall full-page shot reaches the model at ~1024 px high, text unreadable. `shrink-image-read.sh` now works off macOS (ImageMagick or Pillow, python when jq is absent; it was a silent no-op without `sips`). — MendixMau
 - perf(ui-loop): **a stale app reloads instead of restarting, journeys stop sleeping, worst pages are looked at first.** Field run 2026-10-07, existing app. `test-stack-up.sh` records which model the running app was built from (`.claude/loop/served-model`); when the model has changed since, it hot-reloads with `mxcli docker reload` (adding `--skip-check` when the exec.sh gate already passed this model) and restarts only if that fails: 93 s instead of 179 s. `ui-loop.md` and the script header carry the measured table and point at `mxcli run --local --watch` as the fast loop (~18 s per page change). `journey-runner.js` waits on page state after a combobox action instead of fixed pauses, and a combobox step now opens the widget it names: it used to open the page's first combobox, so on a form with three every step but the first failed. `page-audit.js` clicks the first copy of a nav item a user could actually click, not just the first match: with the sidebar collapsed, every in-nav page faulted while the same item sat in the top menu bar. It also writes `page-audit-look-order.txt`, all pages worst first (`module-review.md` §4a: order, not selection, every page is still looked at). `design-audit.js` drops its fixed 1.2 s wait. Same 7-step journey on the same app: 56 s with `SETTLE_MODE=fixed`, 24 s with settle, 11/11 pass both ways, 3 runs each. — MendixMau
diff --git a/tests/wave2/test-sync-dup-heading-exit.sh b/tests/wave2/test-sync-dup-heading-exit.sh
index 4aaedd33..504c0424 100755
--- a/tests/wave2/test-sync-dup-heading-exit.sh
+++ b/tests/wave2/test-sync-dup-heading-exit.sh
@@ -4,7 +4,7 @@
 # "mxcli-project-toolkit Integration" heading — the shape every CLAUDE.md written by mxcli init
 # v0.25 has. `grep -n heading | head | cut` returned grep's exit 1 through pipefail, errexit ended
 # the script, and every step after it (bin/ crash-net refresh, tests/e2e install, lint rules)
-# never ran. Field: three consuming projects (TramiusECI/SCR/SVC), every sync since 9a0350b.
+# never ran. Field: three consuming projects of one organisation, every sync since 9a0350b.
 #
 # Run against the pre-fix script and T1-T3 must fail (exit 1, no bin/ line, no summary).
 #