From cd187a4a83938e850ec5856d6adcbe97845715bb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 13:13:25 +0000
Subject: [PATCH 1/6] feat(doctor, sync-project): wire mxcli fix property-sets
 into the upgrade path, report first; name a pre-fix model-stamp.sh

#295. mxcli up to v0.25 wrote units without Studio Pro's full property
set. mx check, the build and the runtime stay green, and Studio Pro's
merge/diff throws once it has saved such a document. No gate saw it.

- bin/doctor.sh --property-sets <dir>: read-only `mxcli fix property-sets
  --dry-run`, result plus mxcli version in .claude/.property-sets-receipt
  (gitignored). Exit 0 clean / 1 needs or unclassified / 2 not run /
  3 mxcli < v0.26.0. --if-stale skips when already run for this mxcli.
- bin/doctor.sh --fix-property-sets <dir>: the repair, only through
  bin/exec.sh --patch (snapshot, mxbuild gate, restore); refused on an
  exec.sh without --patch. doctor.sh is its own patch script.
- doctor --quick (run by exec.sh when the mxcli version changes) warns
  while the check is owed; a full doctor runs it.
- sync-project.sh runs the check with --if-stale (never the repair).
- Support is read from `mxcli fix --help`: `fix property-sets --help`
  exits 0 on v0.24/v0.25 too (cobra prints the parent's help).
- learned-detection-gaps.md row; platform-link.md "Before a Team Server
  merge" (fix property-sets, fix hashes, git note).

#236 remainder: known_fix_note gains the model-stamp.sh arm keyed on
GIT_WORK_TREE (patch 0004); test-model-stamp.sh T9 adds the unstaged
worktree `commit -a` and `commit -- app` cases.

Golden input: `--version`, `fix --help`, `fix property-sets --help` and
a not-found dry-run, captured from the official v0.24.0/v0.25.0/v0.26.0
linux-amd64 release binaries (never run against a model). The clean /
NEEDS / FAILED reports follow mxcli v0.26.0's source format strings.
tests/wave2/test-property-sets.sh: 43 passed here, 26 fail on master's
doctor.sh/sync-project.sh. Field run on a real model still owed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                                  |   2 +
 bin/doctor.sh                                 | 200 ++++++++++++++++
 bin/sync-project.sh                           |  29 +++
 skills/learned-detection-gaps.md              |   1 +
 skills/platform-link.md                       |  27 +++
 .../dry-run-not-found-v0.26.0.exit            |   1 +
 .../dry-run-not-found-v0.26.0.txt             |   2 +
 .../property-sets/fix-help-v0.24.0.txt        |  21 ++
 .../property-sets/fix-help-v0.25.0.txt        |  22 ++
 .../property-sets/fix-help-v0.26.0.txt        |  23 ++
 .../fix-property-sets-help-v0.25.0.txt        |  22 ++
 .../property-sets/version-v0.24.0.txt         |   1 +
 .../property-sets/version-v0.25.0.txt         |   1 +
 .../property-sets/version-v0.26.0.txt         |   1 +
 tests/wave2/test-model-stamp.sh               |   6 +
 tests/wave2/test-property-sets.sh             | 219 ++++++++++++++++++
 16 files changed, 578 insertions(+)
 create mode 100644 tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.exit
 create mode 100644 tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/fix-help-v0.24.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/fix-help-v0.25.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/fix-help-v0.26.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/fix-property-sets-help-v0.25.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/version-v0.24.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/version-v0.25.0.txt
 create mode 100644 tests/wave2/fixtures/property-sets/version-v0.26.0.txt
 create mode 100755 tests/wave2/test-property-sets.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b46921d3..3390a0ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,8 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- feat(doctor, sync-project): **`mxcli fix property-sets` is wired into the upgrade path, report first: the Studio Pro merge break no gate could see.** mxcli up to v0.25 wrote units without Studio Pro's full property set. `mx check`, the build and the runtime stay green, and Studio Pro's merge/diff throws ("Objects with ID … do not have the same properties") once it has saved such a document. New `bin/doctor.sh --property-sets <project>` runs the read-only `--dry-run` and records the result with the mxcli version in `.claude/.property-sets-receipt` (machine-local, gitignored). It exits 0 clean, 1 needs repair or could not classify (never green by absence), 2 not run, 3 for an mxcli before v0.26.0. `sync-project.sh` runs it with `--if-stale`, once per installed mxcli version, and `doctor --quick` (which exec.sh runs when the mxcli version changes) warns while it is owed. The repair is `bin/doctor.sh --fix-property-sets <project>`, which runs `mxcli fix property-sets` only through `exec.sh --patch` (snapshot, mxbuild gate, restore). It refuses on an exec.sh without `--patch`. Support is probed from `mxcli fix --help`, because `mxcli fix property-sets --help` exits 0 on v0.24/v0.25 too, printing the parent's help. New row in `learned-detection-gaps.md`; `platform-link.md` gains "Before a Team Server merge", covering `fix property-sets`, `fix hashes` and `git note`. Golden input is captured from the v0.24.0/v0.25.0/v0.26.0 release binaries. The clean/NEEDS/FAILED reports follow mxcli's source format strings, because no model was run. `tests/wave2/test-property-sets.sh` (43 cases, 26 fail on master). Field run still owed. `fix hashes` as an `exec.sh --patch` post-step is pending (Refs #295) — jopterhorst
+- fix(sync-project): **sync names a `bin/model-stamp.sh` that predates the worktree hook blind-spot fix.** `known_fix_note` gains the `model-stamp.sh` arm from the #236 patch, keyed on `GIT_WORK_TREE`, which the fixed script pins. The arm says to upgrade `model-stamp.sh` and `_common.sh` together. `tests/wave2/test-model-stamp.sh` T9 adds the unstaged worktree `commit -a` and `commit -- app` cases. The silent rc 1 half of #236 landed earlier. The new note is asserted by `test-property-sets.sh` P10, which fails on master. — MendixMau (card-disbursement requirements-driven build, field task 21)
 - feat(lint): **Lint Batch 3 — TXT001 build-process words in user-visible text, TXT002 non-ISO dates in user-visible text, UI001 Data grid 2 / Atlas input layout traps.** From the 2026-10-12 UX-fix retros ([#280](https://github.com/MendixMau/mxcli-project-toolkit/issues/280), [#282](https://github.com/MendixMau/mxcli-project-toolkit/issues/282), [#276](https://github.com/MendixMau/mxcli-project-toolkit/issues/276)): leaked words reached 3 of 3 apps and non-ISO dates 2 of 3, each past a one-off glossary grep; a list view in a grid column and a width on an Atlas input each cost fix rounds. Warning severity, `_rule` finding on a missing field, an empty `strings()` under a FULL-catalog rule, or vocabulary that matches nothing; 23 cases in `tests/lint-rules/test-batch3-rules.sh` (harness gained a `strings()` mock). Field run (mxcli 0.26.0, 21-module Mendix 11.12 model): 0/0/0 over 478 user-visible strings and 271 widgets, with loosened positive controls returning 27/50/17 through the same accessors. TXT002 cannot see format strings inside expressions — that half is a blocked row. `process/lint-backlog.md` Batch 5 lists all 17 candidates from the three issues (rows 32–48) — MendixMau
 - new(process): **feedback typed mid-build gets a change log in `PROJECT.md`, written before any edit, and the BRD/decision/architecture/wireframe is edited before the MDL.** Across 12 mid-build changes on real projects, 12 went straight into MDL and 0 updated a BRD, build plan or wireframe; the drift-sync `UNSYNCED` marker was never written once, and its absence is invisible, so every gate passed on silence. At the other extreme, one already-settled entity change cost ~270k tokens through two helper agents, and one screenshot-driven fix took 4 rounds because it regressed twice. New `skills/change-intake.md` (baseline, lead+ba, Stages 2–7; routing trigger "the user gives feedback or asks for a change mid-project"): one `## Change log` row per ask (`CR | Date | Source | Verbatim ask | Class | Size | Entry artifact | Status | Closed-by`), six classes, each mapped to its entry artifact (a decision is superseded by a new row, never edited; a built page's visual change is recorded as a before/after screenshot pair instead of wireframe upkeep; impl/bug need only a regression journey). Ceremony is proportional: a small change the user typed gets a one-line receipt and no question, a medium one gets one batched question at the next module gate, a large one or one that contradicts a CONFIRMED decision is asked and stopped on, and stakeholder asks wait for the user. Statuses run open → refined → agreed → applied → proven, or rejected. `bin/lib/change-log.sh` holds the one template and the parser: `init-project.sh` writes the section, `sync-project.sh` appends it once to older projects, and `gate-check.sh` prints a **warn-only** `Change log:` line plus a dashboard row (rows not yet applied, N of M; applied/proven rows with no Closed-by; unrecognised statuses). It becomes blocking only after two projects' counts match a hand count. `project-bin/exec.sh --cr CR-NN` tags the BUILD-LOG detail cell (metrics-ledger columns unchanged). Ownership contradiction fixed: the lead marks; ba-agent flushes BRDs and briefs; architect-agent flushes wireframes and `architecture/` (runbook §3b, `iterative-build-loop.md`, `agent-roles.md`, both stubs, `close-the-loop.md`). Inbox TD-04's change-loop half is promoted here, and its row is narrowed to the two unpromoted items. Fixture `tests/wave2/test-change-log.sh` (39 cases, PROJECT.md built by the real init) — MendixMau
 - feat(exec): **per-project exec lock with stale takeover, opt-in `--commit-first`, a post-exec "restart needed / watch can apply this" verdict, a scoped `bin/app-restart.sh`, and `bin/test-scratch.sh` for `mxcli test` on a locked copy** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287) items 3-4, [#284](https://github.com/MendixMau/mxcli-project-toolkit/issues/284), [#275](https://github.com/MendixMau/mxcli-project-toolkit/issues/275), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289) items 1-2, [#285](https://github.com/MendixMau/mxcli-project-toolkit/issues/285), [#278](https://github.com/MendixMau/mxcli-project-toolkit/issues/278) recipe half). In a 20-task UX-fix field run over three apps (2026-10-12), 57 of 148 `exec.sh` runs applied nothing (26 refused on uncommitted model changes, 15 gate failures, 16 mxbuild exit 1), a machine-wide `pgrep "mxcli exec"` guard blocked an exec because another project was writing, watch mode silently missed recreated microflows, grants, attributes, pages, page URLs and theme SCSS/JS (~26 restarts), and 24 implementer restart-resumes cost 41.6M tokens because only the lead could restart apps. `exec.sh` now locks per project (atomic, `<pid> <epoch> <script>`, a dead or reused pid is taken over with a note; another project never blocks), `--commit-first` commits only the `.mpr` + `mprcontents/` (refused while Studio Pro holds the model; the refusal names the flag), and every applied script ends with the watch verdict (`--watch-compat` alone). `app-restart.sh` stops only the pid `run --local` recorded for THIS project, restarts it with the same command and returns when the port serves a Mendix page and its JS bundle; no record, or a record from another project, refuses. `ui-loop.md` gains the covers / does-not-cover table and the stale-runtime symptom list (incl. the `IO_PathNotFound deployment/web/pages` rebuild crash); `agent-roles.md` lets implementers run that one helper. Fixtures: `test-exec-lock-watch.sh` (45), `test-app-restart.sh` (30), `test-test-scratch.sh` (20) — MendixMau
diff --git a/bin/doctor.sh b/bin/doctor.sh
index 38e0d47a..a6ef1b24 100755
--- a/bin/doctor.sh
+++ b/bin/doctor.sh
@@ -42,6 +42,16 @@
 #                                           # (search "Gate self-test") for what it proves and
 #                                           # why: mxbuild/java being PRESENT does not mean the
 #                                           # mxbuild gate can actually SEE an error.
+#   bin/doctor.sh --property-sets <dir>     # ONLY the Studio Pro merge-safety check: runs
+#                                           # `mxcli fix property-sets --dry-run` (read-only)
+#                                           # and records the result. Add --if-stale to skip
+#                                           # the run when it already ran for this mxcli
+#                                           # version (sync-project.sh does). Exit 0 clean,
+#                                           # 1 units need repair or the run failed, 2 not run,
+#                                           # 3 this mxcli predates the command (v0.26.0).
+#   bin/doctor.sh --fix-property-sets <dir> # the same check, then the repair — and only
+#                                           # through bin/exec.sh --patch (snapshot, mxbuild
+#                                           # gate, restore on failure). See "Property sets".
 #
 # --install never downloads silently: it prints the plan first — what, from where, how big,
 # why, and the detected OS/arch — then asks [y/N] at a terminal, or requires --yes when there
@@ -56,12 +66,22 @@
 
 set -u
 
+# The repair step of --fix-property-sets, run BY bin/exec.sh --patch, never by hand: exec.sh
+# calls a .sh patch as `bash <script> <model.mpr> [args...]`, so this file is its own patch
+# script and the repair inherits exec.sh's snapshot, mxbuild gate and restore.
+if [ "${2:-}" = "--property-sets-apply-step" ]; then
+  { [ -n "${3:-}" ] && [ -x "$3" ]; } || { echo "--property-sets-apply-step: no runnable mxcli given" >&2; exit 2; }
+  exec "$3" fix property-sets -p "$1"
+fi
+
 TOOLKIT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 PROJECT_DIR=""
 INSTALL=0
 ASSUME_YES=0
 QUICK=0
 GATE_SELFTEST=0
+PS_MODE=""
+PS_IF_STALE=0
 NO_DOCKER="${MXTK_DOCTOR_SKIP_DOCKER:-0}"
 DOCKER_PROBE_SECS="${MXTK_DOCKER_PROBE_SECS:-8}"
 for _arg in "$@"; do
@@ -71,6 +91,9 @@ for _arg in "$@"; do
     --quick)   QUICK=1 ;;
     --gate-selftest) GATE_SELFTEST=1 ;;
     --no-docker) NO_DOCKER=1 ;;
+    --property-sets)     PS_MODE=check ;;
+    --fix-property-sets) PS_MODE=fix ;;
+    --if-stale)          PS_IF_STALE=1 ;;
     *)         PROJECT_DIR="$_arg" ;;
   esac
 done
@@ -141,6 +164,155 @@ probe_runs() {
   return "$_pr_exit"
 }
 
+# --- property sets: Studio Pro merge safety (mxcli v0.26.0+) ----------------------------------
+#
+# WHY THIS EXISTS (#295). Studio Pro's merge and diff compare two revisions of an element by its
+# property NAMES, and throw when they differ ("Objects with ID … of type … do not have the same
+# properties"). mxcli up to v0.25 wrote units without Studio Pro's full property set. Such a
+# model passes `mx check`, the build and the runtime — every rung exec.sh has — and breaks the
+# first diff or Team Server merge after Studio Pro has saved one of those documents. mxcli
+# v0.26.0 completes the set on every write it makes, but only for the units it rewrites; units
+# an older mxcli wrote keep their gaps until `mxcli fix property-sets` normalizes them. Field
+# case: 78 changed units written with v0.24 on a production app, and no gate could see it.
+#
+# REPORT FIRST. The check is always the --dry-run (read-only; mxcli opens the model with its
+# reader, not its writer). The repair runs only on --fix-property-sets, and only through
+# bin/exec.sh --patch, so it gets the snapshot, the mxbuild gate and the auto-restore every
+# other model write gets. A repair that leaves units FAILED (a value in a key the project's
+# Mendix version does not declare) exits 1, and exec.sh then restores the whole run — fix
+# those units by hand first.
+#
+# What the dry-run prints and how it exits is mxcli's cmd/mxcli/cmd_fix_property_sets.go at
+# v0.26.0: exit 0 = nothing to do; exit 1 = a `  NEEDS ` or `  FAILED ` row per unit, OR an
+# error such as "project not found" (both exit 1, so the rows decide, never the code alone).
+# Anything else is "could not classify", never clean. Support is read from `mxcli fix --help`
+# listing the subcommand: `mxcli fix property-sets --help` exits 0 on v0.24/v0.25 too (cobra
+# prints the parent's help for an unknown subcommand), so it cannot be the probe. Golden
+# captures of all three versions: tests/wave2/fixtures/property-sets/.
+#
+# The result is recorded in <project>/.claude/.property-sets-receipt (machine-local, like the
+# doctor receipt): line 1 "<date> <time> <result> <detail>", line 2 "mxcli: <--version line>".
+# Line 2 is what --if-stale and --quick compare: the check is owed again when mxcli changes.
+PS_RESULT=""
+PS_DETAIL=""
+PS_OUT=""
+PS_VER=""
+ps_receipt() { printf '%s/.claude/.property-sets-receipt' "$PROJECT_DIR"; }
+ps_version() { probe_capture _ps_v "$1" --version || true; printf '%s\n' "$_ps_v" | grep -v '^[[:space:]]*$' | head -1; }
+ps_supported() {
+  probe_capture _ps_help "$1" fix --help || return 1
+  printf '%s\n' "$_ps_help" | grep -qE '^[[:space:]]+property-sets[[:space:]]'
+}
+# ps_classify <exit> <output> — sets PS_RESULT (clean|needs|failed|error) and PS_DETAIL.
+ps_classify() {
+  _psc_checked="$(printf '%s\n' "$2" | grep -m1 -E '^Checked [0-9]+ unit' || true)"
+  _psc_needs="$(printf '%s\n' "$2" | grep -c '^  NEEDS ' || true)"
+  _psc_failed="$(printf '%s\n' "$2" | grep -c '^  FAILED ' || true)"
+  if [ "$1" -eq 0 ] && printf '%s\n' "$2" | grep -q 'no readable Mendix version'; then
+    PS_RESULT=error; PS_DETAIL="mxcli read no Mendix version from the model, so nothing was checked"
+  elif [ "$1" -eq 0 ]; then
+    PS_RESULT=clean; PS_DETAIL="${_psc_checked:-exit 0}"
+  elif [ "$1" -eq 1 ] && [ "$_psc_needs" -gt 0 ]; then
+    PS_RESULT=needs; PS_DETAIL="$_psc_needs unit(s) need their property set completed, $_psc_failed cannot be normalized"
+  elif [ "$1" -eq 1 ] && [ "$_psc_failed" -gt 0 ]; then
+    PS_RESULT=failed; PS_DETAIL="$_psc_failed unit(s) hold a value in a key this Mendix version does not declare"
+  else
+    PS_RESULT=error
+    PS_DETAIL="exit $1: $(printf '%s\n' "$2" | grep -v -e '^[[:space:]]*$' -e '^WARNING: This is a' | head -1)"
+  fi
+}
+ps_write_receipt() {
+  [ -n "$PROJECT_DIR" ] && [ -d "$PROJECT_DIR" ] || return 0
+  mkdir -p "$PROJECT_DIR/.claude" 2>/dev/null || return 0
+  { printf '%s %s %s\n' "$(date '+%Y-%m-%d %H:%M')" "$PS_RESULT" "$PS_DETAIL"
+    printf 'mxcli: %s\n' "$PS_VER"
+  } > "$(ps_receipt)" 2>/dev/null || true
+  if [ -d "$PROJECT_DIR/.git" ] && ! git -C "$PROJECT_DIR" check-ignore -q .claude/.property-sets-receipt 2>/dev/null; then
+    printf '\n# Machine-local toolkit marker (doctor.sh property-set check)\n/.claude/.property-sets-receipt\n' \
+      >> "$PROJECT_DIR/.gitignore" 2>/dev/null || true
+  fi
+}
+# ps_stale — 0 when no check has been recorded for the mxcli that is installed now.
+ps_stale() { [ ! -f "$(ps_receipt)" ] || [ "$(sed -n '2s/^mxcli: //p' "$(ps_receipt)")" != "$PS_VER" ]; }
+# ps_check — needs MPR and PMXCLI_PROBE (empty is fine: reported NOT RUN). Sets PS_RESULT.
+ps_check() {
+  PS_RESULT=not-run; PS_DETAIL=""
+  if [ -z "${MPR:-}" ]; then note "property sets: NOT RUN — no .mpr in the project root or app/"; return 0; fi
+  if [ -z "${PMXCLI_PROBE:-}" ]; then note "property sets: NOT RUN — no runnable project mxcli"; return 0; fi
+  PS_VER="$(ps_version "$PMXCLI_PROBE")"
+  if ! ps_supported "$PMXCLI_PROBE"; then
+    PS_RESULT=unsupported; PS_DETAIL="${PS_VER:-this mxcli} has no 'fix property-sets'"
+    warn "property sets: ${PS_VER:-this mxcli} cannot check them — 'mxcli fix property-sets' arrived in v0.26.0"
+    note "Units an mxcli before v0.26 wrote can make Studio Pro's merge/diff throw although mx check,"
+    note "the build and the runtime all pass. Upgrade the project's mxcli, then run this check."
+    ps_write_receipt; return 0
+  fi
+  _psk_rc=0
+  probe_capture PS_OUT "$PMXCLI_PROBE" fix property-sets -p "$MPR" --dry-run || _psk_rc=$?
+  ps_classify "$_psk_rc" "$PS_OUT"
+  case "$PS_RESULT" in
+    clean) ok "property sets: $PS_DETAIL — every unit has the property names Studio Pro writes" ;;
+    needs|failed)
+      warn "property sets: $PS_DETAIL — Studio Pro's merge/diff can throw on these"
+      printf '%s\n' "$PS_OUT" | grep -E '^  (NEEDS|FAILED) ' | head -10 | while IFS= read -r l; do note "$l"; done
+      _psk_rows="$(printf '%s\n' "$PS_OUT" | grep -cE '^  (NEEDS|FAILED) ' || true)"
+      [ "$_psk_rows" -gt 10 ] && note "  … $((_psk_rows - 10)) more"
+      [ "$PS_RESULT" = needs ] && note "repair (snapshot + mxbuild gate + restore): bin/doctor.sh --fix-property-sets ${PROJECT_DIR:-<project>}"
+      [ "$(printf '%s\n' "$PS_OUT" | grep -c '^  FAILED ' || true)" -gt 0 ] && \
+        note "FAILED units are left alone by mxcli and make the guarded repair roll back — resolve them first." ;;
+    *) warn "property sets: could not classify the check — $PS_DETAIL"
+       printf '%s\n' "$PS_OUT" | grep -v '^[[:space:]]*$' | head -5 | while IFS= read -r l; do note "  $l"; done ;;
+  esac
+  ps_write_receipt
+}
+ps_apply() {
+  _psa_ex="$PROJECT_DIR/bin/exec.sh"
+  if [ ! -x "$_psa_ex" ] || ! grep -q 'PATCH_MODE' "$_psa_ex" 2>/dev/null; then
+    bad "property sets: not repaired — this project's bin/exec.sh has no --patch, and the repair is only run through it"
+    note "upgrade it first: bin/sync-project.sh $PROJECT_DIR --upgrade-bin exec.sh"
+    return 0
+  fi
+  note "repairing through bin/exec.sh --patch (snapshot, fix, mxbuild gate, kept only on a verified gate)…"
+  _psa_rc=0
+  ( cd "$PROJECT_DIR" && ./bin/exec.sh --patch "$TOOLKIT_ROOT/bin/doctor.sh" --property-sets-apply-step "$PMXCLI_PROBE" ) || _psa_rc=$?
+  if [ "$_psa_rc" -ne 0 ]; then
+    bad "property sets: exec.sh --patch exited $_psa_rc — the repair was not kept (its output above says why)"
+    return 0
+  fi
+  note "re-checking…"
+  ps_check
+}
+ps_exit_code() {
+  case "$PS_RESULT" in clean) echo 0 ;; not-run) echo 2 ;; unsupported) echo 3 ;; *) echo 1 ;; esac
+}
+
+# --property-sets / --fix-property-sets: only this check, then exit. Stands alone so
+# sync-project.sh and an agent about to merge can run it without waiting through the rest.
+if [ -n "$PS_MODE" ]; then
+  if [ -z "$PROJECT_DIR" ] || [ ! -d "$PROJECT_DIR" ]; then
+    echo "usage: $0 --property-sets|--fix-property-sets [--if-stale] <project-dir>" >&2; exit 2
+  fi
+  PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"
+  PROJECT_ROOT="$PROJECT_DIR"
+  # shellcheck disable=SC1091
+  . "$TOOLKIT_ROOT/project-bin/_common.sh"
+  MPR="$(ls "$PROJECT_DIR"/*.mpr 2>/dev/null | head -1)"
+  [ -n "$MPR" ] || MPR="$(ls "$PROJECT_DIR"/app/*.mpr 2>/dev/null | head -1)"
+  PMXCLI_PROBE="$(find_project_mxcli 2>/dev/null || true)"
+  head_ "Property sets (Studio Pro merge safety): $PROJECT_DIR"
+  if [ "$PS_IF_STALE" = 1 ] && [ "$PS_MODE" = check ] && [ -n "$PMXCLI_PROBE" ]; then
+    PS_VER="$(ps_version "$PMXCLI_PROBE")"
+    if ! ps_stale; then
+      PS_RESULT="$(sed -n '1s/^[^ ]* [^ ]* \([^ ]*\).*/\1/p' "$(ps_receipt)")"
+      ok "already checked for $PS_VER: $(sed -n 1p "$(ps_receipt)")"
+      exit "$(ps_exit_code)"
+    fi
+  fi
+  ps_check
+  [ "$PS_MODE" = fix ] && [ "$PS_RESULT" = needs ] && ps_apply
+  exit "$(ps_exit_code)"
+fi
+
 # --- platform -------------------------------------------------------------------------------
 
 head_ "Platform"
@@ -958,6 +1130,34 @@ if [ -n "$PROJECT_DIR" ]; then
     note "your own default mode (~/.claude/settings.json): ${_um:-not set, so the Claude Code built-in default applies}"
     note "No prompts at all is your call, not the project's: set it in ~/.claude/settings.json, or start"
     note "'claude --dangerously-skip-permissions' only inside a container/VM. Deny/ask rules still apply."
+
+    # Property sets (#295) — see the header above ps_check. A full run checks (read-only);
+    # --quick (what exec.sh runs when the mxcli version changes) only compares the receipt
+    # with the installed mxcli, so an upgrade surfaces as a WARN at the next exec.
+    head_ "Property sets (Studio Pro merge safety): $PROJECT_DIR"
+    if [ "$QUICK" != 1 ]; then
+      ps_check
+    elif [ -n "${MPR:-}" ] && [ -n "${PMXCLI_PROBE:-}" ]; then
+      PS_VER="$(ps_version "$PMXCLI_PROBE")"
+      if ps_stale; then
+        if ps_supported "$PMXCLI_PROBE"; then
+          warn "property sets not checked for this mxcli (${PS_VER:-?}) — Studio Pro merge/diff can throw on units an older mxcli wrote"
+          note "read-only check: bin/doctor.sh --property-sets $PROJECT_DIR"
+        else
+          note "${PS_VER:-this mxcli} predates 'mxcli fix property-sets' (v0.26.0) — upgrade before a Team Server merge"
+        fi
+      else
+        _psq="$(sed -n 1p "$(ps_receipt)")"
+        case "$_psq" in
+          *" clean "*|*" clean") ok "property sets: last check for this mxcli was clean ($_psq)" ;;
+          *" unsupported "*) note "property sets: this mxcli cannot check them (v0.26.0+ needed)" ;;
+          *) warn "property sets: last check for this mxcli: $_psq"
+             note "repair: bin/doctor.sh --fix-property-sets $PROJECT_DIR" ;;
+        esac
+      fi
+    else
+      note "property sets: NOT RUN — no .mpr or no runnable project mxcli (see above)"
+    fi
   fi
 fi
 
diff --git a/bin/sync-project.sh b/bin/sync-project.sh
index d0101698..1730fb2b 100755
--- a/bin/sync-project.sh
+++ b/bin/sync-project.sh
@@ -992,6 +992,12 @@ known_fix_note() {
   case "$1" in
     verify-module.sh)
       echo "bin/verify-module.sh is missing the design-audit wiring fix (toolkit, 2026-08-21) — wires tests/e2e/design-audit.js (rungs 6-7, UI/a11y) into the composed pass as an informational, non-gating rung — and/or the page-scope wiring fix (F-042, 2026-08-28), which generates .claude/loop/page-scope.json right before the audit reads it; before that fix the scope file's producer was wired into no step and the audit measured against a stale or missing denominator. Recommended upgrade." ;;
+    model-stamp.sh)
+      # Keyed on GIT_WORK_TREE: the fixed script pins it (with GIT_DIR/GIT_INDEX_FILE) before
+      # any git call; a copy without it is the pre-fix one (#162, #236).
+      if ! grep -q 'GIT_WORK_TREE' "$PROJECT_DIR/bin/model-stamp.sh" 2>/dev/null; then
+        echo "bin/model-stamp.sh predates the HOOK BLIND-SPOT fix (toolkit, 2026-09-29, card-disbursement requirements-driven build): a commit made from a git worktree, or with --git-dir, runs the pre-commit hook with GIT_DIR exported, and on a two-tree checkout (.mpr under app/) 'check --staged' then looked for the model at the wrong top, printed 'no model files staged' and PASSED a model change nobody had verified. The project root it checks comes from _common.sh, which learned the app/ probe in the same fix. Upgrade BOTH: --upgrade-bin model-stamp.sh --upgrade-bin _common.sh."; return
+      fi ;;
     page-scope.sh)
       echo "bin/page-scope.sh predates the HEADER_WORDS fix (F-042, 2026-08-28): SHOW PAGES header columns Excluded/Folder/Params were parsed as page rows, inflating the page denominator (measured: 6 real pages counted as 13), so every consumer of page-scope.json graded against furniture. One-line fix — recommended upgrade." ;;
     _common.sh)
@@ -1446,6 +1452,29 @@ if [ "$WIRED" -eq 1 ]; then
   CHANGES=$((CHANGES + ${MXTK_LINT_CHANGES:-0}))
 fi
 
+# --- 4d. Studio Pro merge safety: property sets, once per mxcli version (#295) -------------
+# Units an mxcli before v0.26 wrote can lack Studio Pro's full property set; the model passes
+# mx check, the build and the runtime, and Studio Pro's merge/diff throws. Sync is the step a
+# project runs after an upgrade, so it runs the READ-ONLY check (`doctor.sh --property-sets
+# --if-stale`: skipped when it already ran for the installed mxcli) and never the repair —
+# that is `doctor.sh --fix-property-sets`, through exec.sh's gate, on the user's say-so.
+if [ "$WIRED" -eq 1 ] && [ -x "$SCRIPT_DIR/doctor.sh" ] \
+   && { [ -x "$PROJECT_DIR/mxcli" ] || [ -x "$PROJECT_DIR/mxcli.exe" ]; }; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    echo "Would run: bin/doctor.sh --property-sets --if-stale (read-only model check; skipped when it already ran for this mxcli)"
+  else
+    _ps_rc=0
+    _ps_out="$("$SCRIPT_DIR/doctor.sh" --property-sets --if-stale "$PROJECT_DIR" 2>&1)" || _ps_rc=$?
+    printf '%s\n' "$_ps_out" | grep -v '^[[:space:]]*$' | sed 's/^/   /'
+    case "$_ps_rc" in
+      0|2) ;;
+      3) echo "   (the project's mxcli predates 'fix property-sets', v0.26.0 — upgrade it before a Team Server merge)" ;;
+      *) warn "property sets: Studio Pro's merge/diff can throw on this model (see above). Repair, gated:" \
+              "bin/doctor.sh --fix-property-sets '$PROJECT_DIR'" ;;
+    esac
+  fi
+fi
+
 # ── Script smoke — do the refreshed copies actually load on THIS machine? ────────────────
 # A sync can install or refresh scripts that then cannot run here (CRLF from a Windows
 # editor, a bashism this bash rejects) and nothing would say so until a stage depends on
diff --git a/skills/learned-detection-gaps.md b/skills/learned-detection-gaps.md
index 109ee26d..bb6858b2 100644
--- a/skills/learned-detection-gaps.md
+++ b/skills/learned-detection-gaps.md
@@ -54,6 +54,7 @@ verification rungs form a ladder, and a green result only certifies what that ru
 | A `commit` (or `create … commit`) **inside a loop** — and every other shape defect `mxcli lint` has a rule for (CONV011, empty container MPR006, empty nanoflow MPR002) | rungs 1–4 **including exec.sh's mxbuild gate**, and `mxcli check` (whose MDL001/MDL067 hints are not lint, however the script header labels them) | `mxcli lint` — but only if something *runs* it | On a 2026-09-24 field project the gate-agent, where lint was an optional step, had been spawned 0 times against 21 `exec.sh` runs and 234 raw `mxcli exec` runs; `lint-gate.sh` had run twice, by hand, to seed a baseline. A migration flow shipped three commits-in-a-loop under "✅ applied · mxbuild clean". Fix: `exec.sh` runs `lint-gate.sh` after every clean mxbuild and writes the lint verdict into the BUILD-LOG row (`LINT ROSE` exits 1, write kept, `SKIP_LINT=<reason>` recorded). **An instrument that lives only in an agent definition is a suggestion; count its BUILD-LOG rows before claiming coverage** | a marketplace guest-group migration, 2026-09-24 |
 | `Title = null` (or any `= null`) as an **XPath retrieve constraint** | rungs 1–3 — `check --references` clean, exec succeeds, and mxcli's **own OQL engine evaluates the query** and returns rows, so even a read-back looks right | native `mx check` / mxbuild: CE0161 | XPath has no `= null`; write `not(Title)` / `Title != ''` for the empty test. Note what makes this one expensive: mxcli's query engine is more permissive than the model loader, so "I ran the query and it worked" is **not** evidence the constraint is legal | field build (Maurits Visser), 2026-09 |
 | A page layout migrated with `ALTER PAGES … WHERE LAYOUT = X`, in a project whose page scripts **hardcode** `Layout:` inside `create or replace page` | rungs 1–6 — every rung, including live runtime: the app loads, every page renders, every journey passes. There is no error anywhere | a screenshot **of the nav shell** on every page, or `grep -l 'Layout: <old>' mdlsource/` after the migration | `create or replace page` rewrites the page **wholesale**, layout included — so re-running any older page script silently reverts that page to the old shell, and the app ships **two navigation shells at once**. Found when 4 of 7 screens had no navigation at all, just a bare hamburger, after a UI fix loop re-ran five page scripts. A layout migration is not done until the `Layout:` literal is fixed **in the source scripts**; the `ALTER` is a one-shot, the scripts are the repeat offender | field build (Maurits Visser), 2026-09 |
+| Any document an **mxcli before v0.26** wrote and nothing has rewritten since — it lacks part of the property set Studio Pro writes for that Mendix version | rungs 1–6, **all of them**: `mx check`, exec.sh's mxbuild gate, the build and the runtime are clean, and Studio Pro opens the project | Studio Pro's **merge or diff**, once Studio Pro has saved the document: *"Objects with ID … of type Microflows$RestOperationCallAction do not have the same properties"*, and the Version Control panel fails | No rung on the ladder compares property **names**. Run the read-only check after every mxcli upgrade and before any Team Server merge: `bin/doctor.sh --property-sets <project>` (it wraps `mxcli fix property-sets --dry-run`; sync-project.sh runs it once per mxcli version, and `doctor --quick` warns while it is owed). Repair only through the gate: `bin/doctor.sh --fix-property-sets <project>` runs `mxcli fix property-sets` under `exec.sh --patch`. mxcli v0.26.0+ completes the set on every unit it writes; an older mxcli cannot check at all | a 127-module production app, 78 units written with v0.24 (#295); mxcli v0.26.0 changelog |
 
 ## Operating rules that fall out of this table
 
diff --git a/skills/platform-link.md b/skills/platform-link.md
index 7059c227..ab5da582 100644
--- a/skills/platform-link.md
+++ b/skills/platform-link.md
@@ -450,6 +450,33 @@ cause, in the same output. A smoke test that quietly omits them reads as full co
 
 ---
 
+## Before a Team Server merge — three mxcli v0.25/v0.26 checks
+
+A model can be valid everywhere the toolkit looks and still break the first time Studio Pro
+compares two revisions. Three mxcli commands see what `mx check` and exec.sh's gate cannot.
+Each has a read-only form; run that first and read it before anything writes.
+
+| When | Read-only check | Repair |
+|---|---|---|
+| After every mxcli upgrade, and before any merge or Studio Pro pull of CLI-written history | `bin/doctor.sh --property-sets <project>` — wraps `mxcli fix property-sets -p <app>.mpr --dry-run` (v0.26.0+) | `bin/doctor.sh --fix-property-sets <project>` — runs `mxcli fix property-sets` through `exec.sh --patch` (snapshot, mxbuild gate, restore) |
+| After a `git checkout`, `git restore` or merge touched `mprcontents/` | `./mxcli fix hashes -p <app>.mpr` (v0.25.0+; exits 1 on any mismatch) | `./mxcli fix hashes -p <app>.mpr --repair` — rewrites the `.mpr` hash index from the files, never the files |
+| After committing model changes with git | `./mxcli git note -p <app>.mpr` (v0.26.0+) prints the `mx_metadata` note per unpushed commit | `--write` attaches it; push `refs/notes/mx_metadata` with the branch (trap 6c) |
+
+**Property sets, the one no gate sees.** mxcli up to v0.25 wrote units without part of the
+property set Studio Pro writes for the project's Mendix version. `mx check`, the build and the
+runtime all pass. Studio Pro's merge and diff then throw — *"Objects with ID … do not have the
+same properties"* — once Studio Pro has saved such a document, and the Version Control panel
+fails. Field case: 78 changed units written with v0.24 on a production app, with no gate able to
+see them. mxcli v0.26.0 completes the set on every unit it writes, but only on units it rewrites,
+so a project upgraded mid-flight still carries the old ones until the repair runs.
+`sync-project.sh` runs the read-only check once per installed mxcli version, and `doctor --quick`,
+which exec.sh runs when the mxcli version changes, warns while that check is owed. A unit the
+check reports `FAILED` has a value in a key the project's Mendix version does not declare. mxcli
+leaves such units alone, and its exit 1 makes `exec.sh --patch` roll the whole repair back, so
+resolve those units first. An mxcli older than v0.26.0 cannot run this check: upgrade it first.
+
+---
+
 ## Which repository is authoritative
 
 Decide once and write it down. The answer differs by route. (A project laid out per step 3's
diff --git a/tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.exit b/tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.exit
new file mode 100644
index 00000000..379a4c98
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.exit
@@ -0,0 +1 @@
+exit 1
diff --git a/tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.txt b/tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.txt
new file mode 100644
index 00000000..b8f84994
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/dry-run-not-found-v0.26.0.txt
@@ -0,0 +1,2 @@
+WARNING: This is a vibe-coded PoC, alpha quality, use with caution.
+project not found: /nonexistent/App.mpr
diff --git a/tests/wave2/fixtures/property-sets/fix-help-v0.24.0.txt b/tests/wave2/fixtures/property-sets/fix-help-v0.24.0.txt
new file mode 100644
index 00000000..26e0c257
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/fix-help-v0.24.0.txt
@@ -0,0 +1,21 @@
+Run Mendix's own model-fixing tools and keep the project's storage format.
+
+'mx update-widgets' and 'mx rename-design-properties' both do work that only
+Mendix can do, and both rewrite an MPR v2 project into the single-file v1 format
+as a side effect — measured on 11.12.1, rename-design-properties turned 1,866
+.mxunit files into 0 and a 69 KB index into 39 MB.
+
+These subcommands run the tool, read its result back out, restore the v2
+storage, and write the changed units into it with mxcli's own writer. The fix
+persists; the format survives. An MPR v1 project is passed straight through.
+
+Usage:
+  mxcli fix [command]
+
+Available Commands:
+  design-properties Update renamed design properties (clears CE6087) without collapsing MPR v2
+  widgets           Resync widget definitions (clears CE0463) without collapsing MPR v2
+
+Flags:
+  -h, --help   help for fix
+
diff --git a/tests/wave2/fixtures/property-sets/fix-help-v0.25.0.txt b/tests/wave2/fixtures/property-sets/fix-help-v0.25.0.txt
new file mode 100644
index 00000000..252a3052
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/fix-help-v0.25.0.txt
@@ -0,0 +1,22 @@
+Run Mendix's own model-fixing tools and keep the project's storage format.
+
+'mx update-widgets' and 'mx rename-design-properties' both do work that only
+Mendix can do, and both rewrite an MPR v2 project into the single-file v1 format
+as a side effect — measured on 11.12.1, rename-design-properties turned 1,866
+.mxunit files into 0 and a 69 KB index into 39 MB.
+
+These subcommands run the tool, read its result back out, restore the v2
+storage, and write the changed units into it with mxcli's own writer. The fix
+persists; the format survives. An MPR v1 project is passed straight through.
+
+Usage:
+  mxcli fix [command]
+
+Available Commands:
+  design-properties Update renamed design properties (clears CE6087) without collapsing MPR v2
+  hashes            Verify (and with --repair, rewrite) the MPR v2 ContentsHash index
+  widgets           Resync widget definitions (clears CE0463) without collapsing MPR v2
+
+Flags:
+  -h, --help   help for fix
+
diff --git a/tests/wave2/fixtures/property-sets/fix-help-v0.26.0.txt b/tests/wave2/fixtures/property-sets/fix-help-v0.26.0.txt
new file mode 100644
index 00000000..46222917
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/fix-help-v0.26.0.txt
@@ -0,0 +1,23 @@
+Run Mendix's own model-fixing tools and keep the project's storage format.
+
+'mx update-widgets' and 'mx rename-design-properties' both do work that only
+Mendix can do, and both rewrite an MPR v2 project into the single-file v1 format
+as a side effect — measured on 11.12.1, rename-design-properties turned 1,866
+.mxunit files into 0 and a 69 KB index into 39 MB.
+
+These subcommands run the tool, read its result back out, restore the v2
+storage, and write the changed units into it with mxcli's own writer. The fix
+persists; the format survives. An MPR v1 project is passed straight through.
+
+Usage:
+  mxcli fix [command]
+
+Available Commands:
+  design-properties Update renamed design properties (clears CE6087) without collapsing MPR v2
+  hashes            Verify (and with --repair, rewrite) the MPR v2 ContentsHash index
+  property-sets     Give every stored unit the property names Studio Pro writes (unblocks mx diff / merge)
+  widgets           Resync widget definitions (clears CE0463) without collapsing MPR v2
+
+Flags:
+  -h, --help   help for fix
+
diff --git a/tests/wave2/fixtures/property-sets/fix-property-sets-help-v0.25.0.txt b/tests/wave2/fixtures/property-sets/fix-property-sets-help-v0.25.0.txt
new file mode 100644
index 00000000..252a3052
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/fix-property-sets-help-v0.25.0.txt
@@ -0,0 +1,22 @@
+Run Mendix's own model-fixing tools and keep the project's storage format.
+
+'mx update-widgets' and 'mx rename-design-properties' both do work that only
+Mendix can do, and both rewrite an MPR v2 project into the single-file v1 format
+as a side effect — measured on 11.12.1, rename-design-properties turned 1,866
+.mxunit files into 0 and a 69 KB index into 39 MB.
+
+These subcommands run the tool, read its result back out, restore the v2
+storage, and write the changed units into it with mxcli's own writer. The fix
+persists; the format survives. An MPR v1 project is passed straight through.
+
+Usage:
+  mxcli fix [command]
+
+Available Commands:
+  design-properties Update renamed design properties (clears CE6087) without collapsing MPR v2
+  hashes            Verify (and with --repair, rewrite) the MPR v2 ContentsHash index
+  widgets           Resync widget definitions (clears CE0463) without collapsing MPR v2
+
+Flags:
+  -h, --help   help for fix
+
diff --git a/tests/wave2/fixtures/property-sets/version-v0.24.0.txt b/tests/wave2/fixtures/property-sets/version-v0.24.0.txt
new file mode 100644
index 00000000..4d0d7fd5
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/version-v0.24.0.txt
@@ -0,0 +1 @@
+mxcli version v0.24.0 (2026-09-24T05:44:35Z)
diff --git a/tests/wave2/fixtures/property-sets/version-v0.25.0.txt b/tests/wave2/fixtures/property-sets/version-v0.25.0.txt
new file mode 100644
index 00000000..b6c63865
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/version-v0.25.0.txt
@@ -0,0 +1 @@
+mxcli version v0.25.0 (2026-10-05T09:18:28Z)
diff --git a/tests/wave2/fixtures/property-sets/version-v0.26.0.txt b/tests/wave2/fixtures/property-sets/version-v0.26.0.txt
new file mode 100644
index 00000000..238a08d7
--- /dev/null
+++ b/tests/wave2/fixtures/property-sets/version-v0.26.0.txt
@@ -0,0 +1 @@
+mxcli version v0.26.0 (2026-10-11T18:37:07Z)
diff --git a/tests/wave2/test-model-stamp.sh b/tests/wave2/test-model-stamp.sh
index fca0e6c5..14ad910e 100755
--- a/tests/wave2/test-model-stamp.sh
+++ b/tests/wave2/test-model-stamp.sh
@@ -98,6 +98,12 @@ git --git-dir=.git commit -qm x 2>/dev/null && bad "--git-dir commit waved an un
 git reset -q
 cd "$WORK/q-wt" && printf u1c > app/mprcontents/a.mxunit && git add app
 git commit -qm x 2>/dev/null && bad "worktree commit waved an unverified model through" || ok "worktree commit refused the unverified model"
+# The same change left UNSTAGED, committed the two other ways git builds a temporary index
+# (GIT_INDEX_FILE = .git/worktrees/<name>/index.lock or next-index-*.lock).
+git reset -q
+git commit -qam x 2>/dev/null && bad "worktree commit -a waved an unverified model through" || ok "worktree commit -a refused the unverified model"
+git commit -qm x -- app 2>/dev/null && bad "worktree commit -- app waved an unverified model through" || ok "worktree commit -- app refused the unverified model"
+git add app
 ./bin/model-stamp.sh write pass "fixture" >/dev/null
 git commit -qm x 2>/dev/null && ok "worktree commit of the verified model accepted" || bad "worktree refused its verified model"
 
diff --git a/tests/wave2/test-property-sets.sh b/tests/wave2/test-property-sets.sh
new file mode 100755
index 00000000..e4d4a0d4
--- /dev/null
+++ b/tests/wave2/test-property-sets.sh
@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# Fixture for #295: `mxcli fix property-sets` wired into the upgrade path, report first.
+#   bin/doctor.sh --property-sets [--if-stale] <dir>   read-only check + receipt
+#   bin/doctor.sh --fix-property-sets <dir>            the repair, only through exec.sh --patch
+#   bin/doctor.sh --quick <dir>                        receipt vs installed mxcli -> WARN
+#   bin/sync-project.sh <dir>                          runs the --if-stale check
+# and, for #236, sync-project.sh's known-fix note for a pre-fix bin/model-stamp.sh.
+#
+# Golden input (tests/wave2/fixtures/property-sets/), captured from the official
+# mendixlabs/mxcli linux-amd64 release binaries, never run against a model:
+#   version-v0.2{4,5,6}.0.txt              `mxcli --version`
+#   fix-help-v0.2{4,5,6}.0.txt             `mxcli fix --help`, verbatim up to "Global Flags:"
+#                                          (the global-flags block is identical on every
+#                                          subcommand and is not read)
+#   fix-property-sets-help-v0.25.0.txt     `mxcli fix property-sets --help` on v0.25.0: exit 0,
+#                                          and it is the PARENT's help — why the support probe
+#                                          reads `fix --help` instead
+#   dry-run-not-found-v0.26.0.{txt,exit}   `fix property-sets -p <missing> --dry-run`: exit 1
+#                                          with no unit rows — why exit 1 alone is not "needs"
+# NOT captured: the clean / NEEDS / FAILED reports, which need a real model. The stub below
+# prints them from the format strings in mxcli v0.26.0 cmd/mxcli/cmd_fix_property_sets.go
+# (fixPropertySets: "Checked %d unit(s) in %s against the Mendix %d.%d.%d property sets.",
+# "  %-9s %s%s: +%d key(s), -%d key(s)", "  FAILED    %s%s: %v"). A field run owes the real ones.
+#
+# Every project is built under /tmp. No real project is touched; no real mxcli runs.
+#
+# usage: test-property-sets.sh /path/to/bin/doctor.sh
+export MXTK_LEAKGUARD_DENYFILE="${TMPDIR:-/tmp}/mxtk-fixture-denylist.$$"
+export MXTK_SYNC_SKIP_CLONE_CHECK=1
+export MXTK_DOCTOR_SKIP_DOCKER=1
+
+set -uo pipefail
+
+DOCTOR="${1:?usage: test-property-sets.sh /path/to/bin/doctor.sh}"
+case "$DOCTOR" in /*) ;; *) DOCTOR="$PWD/$DOCTOR" ;; esac
+TK="$(cd "$(dirname "$DOCTOR")/.." && pwd)"
+SYNC="$TK/bin/sync-project.sh"
+FIX="$TK/tests/wave2/fixtures/property-sets"
+WORK="$(mktemp -d /tmp/propsets.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: /'; }
+
+# The stub mxcli. STUB_VER picks the captured version; the model state lives in .stub-state.
+mkstub() {
+  cat > "$1/mxcli" <<'STUB'
+#!/usr/bin/env bash
+D="$(cd "$(dirname "$0")" && pwd)"
+F="$STUB_FIX"; V="$(cat "$D/.stub-ver" 2>/dev/null || echo v0.26.0)"
+echo "$*" >> "$D/.stub-log"
+case "${1:-}" in
+  --version) cat "$F/version-$V.txt"; exit 0 ;;
+  --help)    echo "mxcli (stub)"; exit 0 ;;
+  fix) shift
+    case "${1:-}" in
+      --help) cat "$F/fix-help-$V.txt"; exit 0 ;;
+      property-sets)
+        dry=0; mpr=""; prev=""
+        for a in "$@"; do [ "$a" = --dry-run ] && dry=1; [ "$prev" = -p ] && mpr="$a"; prev="$a"; done
+        b="$(basename "$mpr")"
+        echo "WARNING: This is a vibe-coded PoC, alpha quality, use with caution." >&2
+        if [ "$dry" = 0 ]; then
+          echo "Checked 3 unit(s) in $b against the Mendix 11.12.1 property sets."
+          echo "  FIXED     0d6c3a3e-0000-4000-8000-000000000001 [Microflows\$Microflow Orders.ACT_Save]: +4 key(s), -0 key(s)"
+          echo ""; echo "Completed 1 unit(s): 4 key(s) added, 0 stripped."
+          echo clean > "$D/.stub-state"; exit 0
+        fi
+        case "$(cat "$D/.stub-state")" in
+          clean) echo "Checked 3 unit(s) in $b against the Mendix 11.12.1 property sets."
+                 echo "Every unit already has the property names Studio Pro writes."; exit 0 ;;
+          needs) echo "Checked 3 unit(s) in $b against the Mendix 11.12.1 property sets."
+                 echo "  NEEDS     0d6c3a3e-0000-4000-8000-000000000001 [Microflows\$Microflow Orders.ACT_Save]: +4 key(s), -0 key(s)"
+                 echo ""; echo "Would complete 1 unit(s): 4 key(s) added, 0 stripped."
+                 echo "Run 'mxcli fix property-sets -p $mpr' to write them."; exit 1 ;;
+          failed) echo "Checked 3 unit(s) in $b against the Mendix 11.12.1 property sets."
+                  echo "  FAILED    0d6c3a3e-0000-4000-8000-000000000002 [Pages\$Page Orders.Order_Edit]: key Foo holds a value"
+                  echo "1 unit(s) could not be normalized and were left as they are."; exit 1 ;;
+          notfound) cat "$F/dry-run-not-found-v0.26.0.txt"; exit 1 ;;
+          noversion) echo "$b has no readable Mendix version; nothing is normalized without one."; exit 0 ;;
+        esac ;;
+    esac ;;
+esac
+exit 0
+STUB
+  chmod +x "$1/mxcli"
+}
+mkproj() {   # <name> [app]  — a bare project dir: .mpr (root or app/), stub mxcli, git
+  d="$WORK/$1"; mkdir -p "$d"
+  if [ "${2:-}" = app ]; then mkdir -p "$d/app"; : > "$d/app/App.mpr"; else : > "$d/App.mpr"; fi
+  mkstub "$d"; echo needs > "$d/.stub-state"
+  git -C "$d" init -q . 2>/dev/null
+  echo "$d"
+}
+export STUB_FIX="$FIX"
+
+echo "== P1 support probe reads 'fix --help', from the real captures =="
+grep -qE '^[[:space:]]+property-sets[[:space:]]' "$FIX/fix-help-v0.26.0.txt" && ok "v0.26.0 capture lists property-sets" || bad "v0.26.0 capture lacks property-sets"
+grep -q 'property-sets' "$FIX/fix-help-v0.25.0.txt" && bad "v0.25.0 capture lists property-sets" || ok "v0.25.0 capture does not list it"
+head -1 "$FIX/fix-property-sets-help-v0.25.0.txt" | grep -q "model-fixing tools" && ok "v0.25.0 'fix property-sets --help' is the parent's help (why it is not the probe)" || bad "capture shape changed"
+for v in v0.24.0 v0.25.0; do
+  P="$(mkproj old-$v)"; echo "$v" > "$P/.stub-ver"
+  OUT="$("$DOCTOR" --property-sets "$P" 2>&1)"; RC=$?
+  [ "$RC" -eq 3 ] && printf '%s' "$OUT" | grep -q "arrived in v0.26.0" && ok "$v: exit 3, says v0.26.0 is needed" || bad "$v: rc=$RC" "$OUT"
+  grep -q -- '--dry-run' "$P/.stub-log" && bad "$v: ran the dry-run on a binary without the command" || ok "$v: no dry-run attempted"
+done
+
+echo "== P2 clean model =="
+P="$(mkproj clean)"; echo clean > "$P/.stub-state"
+OUT="$("$DOCTOR" --property-sets "$P" 2>&1)"; RC=$?
+[ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q "ok    property sets: Checked 3 unit(s)" && ok "clean: exit 0 with the Checked line" || bad "clean: rc=$RC" "$OUT"
+R="$P/.claude/.property-sets-receipt"
+sed -n 1p "$R" 2>/dev/null | grep -q " clean " && sed -n 2p "$R" | grep -qx "mxcli: mxcli version v0.26.0 (2026-10-11T18:37:07Z)" \
+  && ok "receipt records result and mxcli version" || bad "receipt wrong" "$(cat "$R" 2>&1)"
+grep -qx '/.claude/.property-sets-receipt' "$P/.gitignore" 2>/dev/null && ok "receipt is gitignored (machine-local)" || bad "receipt not gitignored"
+grep -q -- 'property-sets -p .*/App.mpr --dry-run' "$P/.stub-log" && ok "the check is the --dry-run" || bad "dry-run not used" "$(cat "$P/.stub-log")"
+
+echo "== P3 units need completing =="
+P="$(mkproj needs)"
+OUT="$("$DOCTOR" --property-sets "$P" 2>&1)"; RC=$?
+[ "$RC" -eq 1 ] && ok "needs: exit 1" || bad "needs: rc=$RC" "$OUT"
+printf '%s' "$OUT" | grep -q "WARN  property sets: 1 unit(s) need" && ok "needs: WARN with the count" || bad "needs: no WARN" "$OUT"
+printf '%s' "$OUT" | grep -q "NEEDS     0d6c3a3e" && ok "needs: unit row shown" || bad "needs: row missing" "$OUT"
+printf '%s' "$OUT" | grep -q -- "--fix-property-sets" && ok "needs: names the gated repair" || bad "needs: no repair hint" "$OUT"
+grep -v -- '--dry-run' "$P/.stub-log" | grep -q 'property-sets' && bad "needs: the check WROTE (ran without --dry-run)" || ok "needs: nothing written"
+
+echo "== P4 failed / error / no version — never clean =="
+for st in failed notfound noversion; do
+  P="$(mkproj st-$st)"; echo "$st" > "$P/.stub-state"
+  OUT="$("$DOCTOR" --property-sets "$P" 2>&1)"; RC=$?
+  [ "$RC" -eq 1 ] && ! printf '%s' "$OUT" | grep -q "ok    property sets" && ok "$st: exit 1, no ok line" || bad "$st: rc=$RC" "$OUT"
+done
+printf '%s' "$OUT" | grep -q "no Mendix version" && ok "noversion: says nothing was checked" || bad "noversion wording" "$OUT"
+
+echo "== P5 --if-stale: once per mxcli version =="
+P="$(mkproj stale)"; echo clean > "$P/.stub-state"
+"$DOCTOR" --property-sets --if-stale "$P" >/dev/null 2>&1
+n1="$(grep -c -- '--dry-run' "$P/.stub-log")"
+OUT="$("$DOCTOR" --property-sets --if-stale "$P" 2>&1)"; RC=$?
+n2="$(grep -c -- '--dry-run' "$P/.stub-log")"
+[ "$n1" -eq 1 ] && [ "$n2" -eq 1 ] && [ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q "already checked" \
+  && ok "same mxcli: not re-run, exit from the receipt" || bad "same mxcli: n1=$n1 n2=$n2 rc=$RC" "$OUT"
+sed -i.bak '2s/.*/mxcli: mxcli version v0.25.0 (2026-10-05T09:18:28Z)/' "$P/.claude/.property-sets-receipt"
+"$DOCTOR" --property-sets --if-stale "$P" >/dev/null 2>&1
+n3="$(grep -c -- '--dry-run' "$P/.stub-log")"
+[ "$n3" -eq 2 ] && ok "mxcli changed since the receipt: re-run" || bad "after a version change n3=$n3"
+
+echo "== P6 two-tree checkout (.mpr under app/) =="
+P="$(mkproj twotree app)"; echo clean > "$P/.stub-state"
+"$DOCTOR" --property-sets "$P" >/dev/null 2>&1; RC=$?
+[ "$RC" -eq 0 ] && grep -q -- "-p $P/app/App.mpr --dry-run" "$P/.stub-log" && ok "checks app/App.mpr" || bad "two-tree rc=$RC" "$(cat "$P/.stub-log")"
+
+echo "== P7 --fix-property-sets writes only through exec.sh --patch =="
+P="$(mkproj fix-noexec)"
+OUT="$("$DOCTOR" --fix-property-sets "$P" 2>&1)"; RC=$?
+[ "$RC" -eq 1 ] && printf '%s' "$OUT" | grep -q "FAIL  property sets: not repaired" && ok "no exec.sh: refused, exit 1" || bad "no exec.sh: rc=$RC" "$OUT"
+grep -v -- '--dry-run' "$P/.stub-log" | grep -q 'property-sets' && bad "no exec.sh: wrote anyway" || ok "no exec.sh: nothing written"
+mkdir -p "$P/bin"; printf '#!/usr/bin/env bash\n# pre---patch exec.sh\nexit 0\n' > "$P/bin/exec.sh"; chmod +x "$P/bin/exec.sh"
+OUT="$("$DOCTOR" --fix-property-sets "$P" 2>&1)"; RC=$?
+[ "$RC" -eq 1 ] && printf '%s' "$OUT" | grep -q "upgrade-bin exec.sh" && ok "exec.sh without --patch: refused, names the upgrade" || bad "old exec.sh: rc=$RC" "$OUT"
+# An exec.sh with the --patch contract (project-bin/exec.sh: `bash <script> <model.mpr> [args...]`).
+cat > "$P/bin/exec.sh" <<'EX'
+#!/usr/bin/env bash
+# stub of the --patch contract; PATCH_MODE
+echo "exec.sh $*" >> .exec-log
+[ "$1" = --patch ] || exit 9
+shift; s="$1"; shift
+bash "$s" "$(pwd)/App.mpr" "$@"
+EX
+chmod +x "$P/bin/exec.sh"
+OUT="$("$DOCTOR" --fix-property-sets "$P" 2>&1)"; RC=$?
+grep -q -- "--patch $TK/bin/doctor.sh --property-sets-apply-step $P/mxcli" "$P/.exec-log" 2>/dev/null \
+  && ok "repair dispatched as exec.sh --patch doctor.sh --property-sets-apply-step <mxcli>" || bad "dispatch" "$(cat "$P/.exec-log" 2>&1)"
+grep -qx "fix property-sets -p $P/App.mpr" "$P/.stub-log" && ok "the patch step ran the write form on the model" || bad "write form" "$(cat "$P/.stub-log")"
+[ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q "re-checking" && sed -n 1p "$P/.claude/.property-sets-receipt" | grep -q " clean " \
+  && ok "re-checked after the repair: clean, exit 0" || bad "post-repair rc=$RC" "$OUT"
+P="$(mkproj fix-clean)"; echo clean > "$P/.stub-state"; mkdir -p "$P/bin"; cp "$WORK/fix-noexec/bin/exec.sh" "$P/bin/"
+"$DOCTOR" --fix-property-sets "$P" >/dev/null 2>&1; RC=$?
+[ "$RC" -eq 0 ] && [ ! -f "$P/.exec-log" ] && ok "clean model: no repair dispatched" || bad "clean model dispatched a repair (rc=$RC)"
+
+echo "== P8 --quick compares the receipt with the installed mxcli =="
+P="$(mkproj quick)"; echo clean > "$P/.stub-state"
+OUT="$("$DOCTOR" --quick "$P" 2>&1)"
+printf '%s' "$OUT" | grep -q "WARN  property sets not checked for this mxcli" && ok "no receipt: WARN (exec.sh surfaces it)" || bad "no receipt" "$(printf '%s' "$OUT" | grep -i -A2 'property')"
+grep -q -- '--dry-run' "$P/.stub-log" && bad "--quick ran the model check" || ok "--quick did not run the model check"
+"$DOCTOR" --property-sets "$P" >/dev/null 2>&1
+OUT="$("$DOCTOR" --quick "$P" 2>&1)"
+printf '%s' "$OUT" | grep -q "ok    property sets: last check for this mxcli was clean" && ok "receipt current + clean: ok line" || bad "current receipt" "$(printf '%s' "$OUT" | grep -i -A2 'property')"
+echo needs > "$P/.stub-state"; "$DOCTOR" --property-sets "$P" >/dev/null 2>&1
+OUT="$("$DOCTOR" --quick "$P" 2>&1)"
+printf '%s' "$OUT" | grep -q "WARN  property sets: last check for this mxcli:.* needs " && ok "receipt says needs: WARN persists" || bad "needs receipt" "$(printf '%s' "$OUT" | grep -i -A2 'property')"
+
+echo "== P9 sync-project.sh runs the check, never the repair =="
+S="$WORK/syncp"; mkdir -p "$S"; : > "$S/App.mpr"
+MXTK_NO_GUIDE=1 "$TK/bin/init-project.sh" "$S" >/dev/null 2>&1
+[ -f "$S/CLAUDE.local.md" ] || { echo "FIXTURE ERROR: init did not scaffold $S"; exit 2; }
+mkstub "$S"; echo needs > "$S/.stub-state"
+OUT="$("$SYNC" "$S" --dry-run 2>&1)"
+printf '%s' "$OUT" | grep -q "Would run: bin/doctor.sh --property-sets --if-stale" && ok "--dry-run: says it would run the check" || bad "dry-run line" "$(printf '%s' "$OUT" | tail -5)"
+[ ! -f "$S/.stub-log" ] || ! grep -q property-sets "$S/.stub-log" && ok "--dry-run: did not run it" || bad "--dry-run ran mxcli"
+OUT="$("$SYNC" "$S" 2>&1)"; RC=$?
+[ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q "WARN  property sets: 1 unit(s) need" && ok "plain sync: check runs, its WARN shown" || bad "plain sync rc=$RC" "$(printf '%s' "$OUT" | grep -i -B1 -A3 'property')"
+printf '%s' "$OUT" | grep -q "⚠️  property sets: Studio Pro's merge/diff can throw" && ok "plain sync: counted as a sync warning with the repair command" || bad "sync warning" "$(printf '%s' "$OUT" | grep -i 'property')"
+grep -v -- '--dry-run' "$S/.stub-log" | grep -q 'property-sets' && bad "sync wrote to the model" || ok "sync did not repair"
+n1="$(grep -c -- '--dry-run' "$S/.stub-log")"; "$SYNC" "$S" >/dev/null 2>&1; n2="$(grep -c -- '--dry-run' "$S/.stub-log")"
+[ "$n1" -eq "$n2" ] && ok "second sync, same mxcli: check not re-run" || bad "re-ran: $n1 -> $n2"
+
+echo "== P10 (#236) sync names a pre-fix bin/model-stamp.sh =="
+grep -v 'GIT_WORK_TREE' "$TK/project-bin/model-stamp.sh" > "$S/bin/model-stamp.sh"; chmod +x "$S/bin/model-stamp.sh"
+OUT="$("$SYNC" "$S" --dry-run --no-refresh 2>&1)"
+printf '%s' "$OUT" | grep -q "bin/model-stamp.sh is LOCALLY MODIFIED" && ok "pre-fix copy reported as modified" || bad "not reported" "$(printf '%s' "$OUT" | grep model-stamp)"
+printf '%s' "$OUT" | grep -q "predates the HOOK BLIND-SPOT fix.*--upgrade-bin model-stamp.sh --upgrade-bin _common.sh" && ok "known-fix note names the blind spot and both files" || bad "no HOOK BLIND-SPOT note" "$(printf '%s' "$OUT" | grep -A1 model-stamp)"
+{ cat "$TK/project-bin/model-stamp.sh"; echo "# local edit"; } > "$S/bin/model-stamp.sh"
+OUT="$("$SYNC" "$S" --dry-run --no-refresh 2>&1)"
+printf '%s' "$OUT" | grep -q "HOOK BLIND-SPOT" && bad "a fixed-but-edited copy got the note" || ok "a fixed-but-edited copy gets no note"
+
+echo ""
+echo "property-sets: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

From dc951263f2e25006e26d01bfd2958f227cdfa5ed Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 14:17:59 +0000
Subject: [PATCH 2/6] chore(context): free baseline word budget without
 dropping rules

The always-on baseline tier counted by bin/render-routing.sh --check was
at 79,735 of its 80,000-word cap. This frees 3,772 words (now 75,964)
by moving narrative and setup-only text out of baseline files, keeping
every rule, STOP, denominator and gate cell in place, each rule still
paired with a one-line failure example plus a pointer to the full text.

- conversion-runbook.md, source-triage.md, interview-protocol.md: long
  incident narratives -> one line + pointer; originals verbatim in new
  on-demand process/baseline-incident-history.md (R1-R20, AR1, ST1-ST4,
  IP1-IP3). Runbook's duplicate open-questions status table now defers
  to interview-protocol.md section 4.
- agent-roles.md: the six template shapes (setup-only) moved to
  agents/README.md, which installers never copy (explicit MXTK_AGENTS).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                         |   1 +
 agents/README.md                     | 258 +++++++++++++++++++++++++
 process/baseline-incident-history.md | 270 +++++++++++++++++++++++++++
 skills/agent-roles.md                | 262 ++------------------------
 skills/conversion-runbook.md         | 122 ++++--------
 skills/interview-protocol.md         |  34 ++--
 skills/source-triage.md              |  57 ++----
 7 files changed, 607 insertions(+), 397 deletions(-)
 create mode 100644 agents/README.md
 create mode 100644 process/baseline-incident-history.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b46921d3..982e7f1e 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
 
+- chore(context): **baseline word budget freed — 79,735 → 75,963 words (−3,772) without dropping a rule.** The always-on tier sat 265 words under its 80,000 cap, so three open PRs could not all merge. Long incident narratives in `conversion-runbook.md`, `source-triage.md` and `interview-protocol.md` became one-line failure examples pointing at new on-demand `process/baseline-incident-history.md`, where the original text is kept verbatim per section (R1–R20, AR1, ST1–ST4, IP1–IP3); the runbook's copy of the open-questions status table now defers to `interview-protocol.md` §4; `agent-roles.md`'s six template shapes (setup-only, ~2,300 words) moved verbatim to `agents/README.md`, which the installers never copy (explicit `MXTK_AGENTS` list). Every STOP, rule, denominator and gate cell stays in place; files touched by open PRs were left alone. — MendixMau
 - feat(lint): **Lint Batch 3 — TXT001 build-process words in user-visible text, TXT002 non-ISO dates in user-visible text, UI001 Data grid 2 / Atlas input layout traps.** From the 2026-10-12 UX-fix retros ([#280](https://github.com/MendixMau/mxcli-project-toolkit/issues/280), [#282](https://github.com/MendixMau/mxcli-project-toolkit/issues/282), [#276](https://github.com/MendixMau/mxcli-project-toolkit/issues/276)): leaked words reached 3 of 3 apps and non-ISO dates 2 of 3, each past a one-off glossary grep; a list view in a grid column and a width on an Atlas input each cost fix rounds. Warning severity, `_rule` finding on a missing field, an empty `strings()` under a FULL-catalog rule, or vocabulary that matches nothing; 23 cases in `tests/lint-rules/test-batch3-rules.sh` (harness gained a `strings()` mock). Field run (mxcli 0.26.0, 21-module Mendix 11.12 model): 0/0/0 over 478 user-visible strings and 271 widgets, with loosened positive controls returning 27/50/17 through the same accessors. TXT002 cannot see format strings inside expressions — that half is a blocked row. `process/lint-backlog.md` Batch 5 lists all 17 candidates from the three issues (rows 32–48) — MendixMau
 - new(process): **feedback typed mid-build gets a change log in `PROJECT.md`, written before any edit, and the BRD/decision/architecture/wireframe is edited before the MDL.** Across 12 mid-build changes on real projects, 12 went straight into MDL and 0 updated a BRD, build plan or wireframe; the drift-sync `UNSYNCED` marker was never written once, and its absence is invisible, so every gate passed on silence. At the other extreme, one already-settled entity change cost ~270k tokens through two helper agents, and one screenshot-driven fix took 4 rounds because it regressed twice. New `skills/change-intake.md` (baseline, lead+ba, Stages 2–7; routing trigger "the user gives feedback or asks for a change mid-project"): one `## Change log` row per ask (`CR | Date | Source | Verbatim ask | Class | Size | Entry artifact | Status | Closed-by`), six classes, each mapped to its entry artifact (a decision is superseded by a new row, never edited; a built page's visual change is recorded as a before/after screenshot pair instead of wireframe upkeep; impl/bug need only a regression journey). Ceremony is proportional: a small change the user typed gets a one-line receipt and no question, a medium one gets one batched question at the next module gate, a large one or one that contradicts a CONFIRMED decision is asked and stopped on, and stakeholder asks wait for the user. Statuses run open → refined → agreed → applied → proven, or rejected. `bin/lib/change-log.sh` holds the one template and the parser: `init-project.sh` writes the section, `sync-project.sh` appends it once to older projects, and `gate-check.sh` prints a **warn-only** `Change log:` line plus a dashboard row (rows not yet applied, N of M; applied/proven rows with no Closed-by; unrecognised statuses). It becomes blocking only after two projects' counts match a hand count. `project-bin/exec.sh --cr CR-NN` tags the BUILD-LOG detail cell (metrics-ledger columns unchanged). Ownership contradiction fixed: the lead marks; ba-agent flushes BRDs and briefs; architect-agent flushes wireframes and `architecture/` (runbook §3b, `iterative-build-loop.md`, `agent-roles.md`, both stubs, `close-the-loop.md`). Inbox TD-04's change-loop half is promoted here, and its row is narrowed to the two unpromoted items. Fixture `tests/wave2/test-change-log.sh` (39 cases, PROJECT.md built by the real init) — MendixMau
 - feat(exec): **per-project exec lock with stale takeover, opt-in `--commit-first`, a post-exec "restart needed / watch can apply this" verdict, a scoped `bin/app-restart.sh`, and `bin/test-scratch.sh` for `mxcli test` on a locked copy** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287) items 3-4, [#284](https://github.com/MendixMau/mxcli-project-toolkit/issues/284), [#275](https://github.com/MendixMau/mxcli-project-toolkit/issues/275), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289) items 1-2, [#285](https://github.com/MendixMau/mxcli-project-toolkit/issues/285), [#278](https://github.com/MendixMau/mxcli-project-toolkit/issues/278) recipe half). In a 20-task UX-fix field run over three apps (2026-10-12), 57 of 148 `exec.sh` runs applied nothing (26 refused on uncommitted model changes, 15 gate failures, 16 mxbuild exit 1), a machine-wide `pgrep "mxcli exec"` guard blocked an exec because another project was writing, watch mode silently missed recreated microflows, grants, attributes, pages, page URLs and theme SCSS/JS (~26 restarts), and 24 implementer restart-resumes cost 41.6M tokens because only the lead could restart apps. `exec.sh` now locks per project (atomic, `<pid> <epoch> <script>`, a dead or reused pid is taken over with a note; another project never blocks), `--commit-first` commits only the `.mpr` + `mprcontents/` (refused while Studio Pro holds the model; the refusal names the flag), and every applied script ends with the watch verdict (`--watch-compat` alone). `app-restart.sh` stops only the pid `run --local` recorded for THIS project, restarts it with the same command and returns when the port serves a Mendix page and its JS bundle; no record, or a record from another project, refuses. `ui-loop.md` gains the covers / does-not-cover table and the stale-runtime symptom list (incl. the `IO_PathNotFound deployment/web/pages` rebuild crash); `agent-roles.md` lets implementers run that one helper. Fixtures: `test-exec-lock-watch.sh` (45), `test-app-restart.sh` (30), `test-test-scratch.sh` (20) — MendixMau
diff --git a/agents/README.md b/agents/README.md
new file mode 100644
index 00000000..e5b9b46c
--- /dev/null
+++ b/agents/README.md
@@ -0,0 +1,258 @@
+# Agent template shapes — illustrative bodies for the six dev-process agents
+
+**Not an agent.** This file is documentation that sits next to the six stubs; the installers copy
+the named list in `bin/lib/install-manifest.sh` (`MXTK_AGENTS`), never a glob over this folder, so
+it is never installed into a project's `.claude/agents/`.
+
+**Read it at setup only** — when completing a stub per `skills/agent-roles.md` → "How to generate
+these for a new project". The shipped stubs (`agents/<name>-agent.md`) are what `bin/init-agents.sh`
+copies and what `bin/sync-project.sh` refreshes; where a stub and a shape below disagree, the stub
+wins. The shapes are kept because they state the role's rules compactly (for example ba-agent's
+extraction vs translation mode, and which half of a module brief each role writes).
+
+Moved out of `skills/agent-roles.md` (2026-10-13; verbatim except the `model:` lines, which now name the tier and defer to the stub that pins it) so the always-on baseline does not carry
+setup-time text every session (CLAUDE.md skill-authoring rule 6).
+
+## Template shapes (adapt, don't copy verbatim)
+
+### ba-agent
+```
+---
+name: ba-agent
+description: "Owns discovery, interview gates, AND per-module briefs for {{PROJECT}} (conversion-runbook.md Stages P, 0-2, 4, 7). Two modes: EXTRACTION (P-2, no spec yet -> produce BRDs) and TRANSLATION (Stage 4 -> turn validation-clean BRDs into module briefs). Use for intake, triage, requirements, any proposal-with-evidence interview, and authoring module briefs."
+model: <mid tier — copy the alias the shipped stub pins>
+tools: Read, Grep, Glob, Bash
+---
+
+You run discovery, the interview gates, and module-brief authoring for {{PROJECT}}. You never touch the `.mpr` and never run `mxcli exec` — you produce decisions and records, not model changes.
+
+**Paths:** resolve all project paths (KB, BRDs, wireframes, briefs, architecture, stage HTML) from the **`## Wiring` block of the project-root `CLAUDE.local.md`** — the single source of truth. Read it at task start; don't hardcode paths.
+
+## Your two modes
+- **Extraction (Stages P–2):** no spec exists yet. Produce BRDs from source/SME via the interview protocol.
+- **Translation (Stage 4, per module):** BRDs exist. Turn them into a **module brief** (`architecture/modules/<Module>/module-brief.md`, per `module-brief.md`) — the `mdl-agent`'s single entry point. **Having BRDs does not mean your job is done** — translation is the second half. If briefs don't exist, this mode was skipped.
+
+## Ground rules
+- Follow `query-the-model.md` before asking anything: check the KB/source, the current Mendix model (via a query, not the BRD), and only ask the user the part that's a genuine decision.
+- Run the full interview protocol from `conversion-runbook.md` §1 at every gate: homework first, 2-4 options with evidence, assumptions stated out loud, user answers in the terminal, decision written to the stage HTML *and* `PROJECT.md`, unknowns default + `ASSUMED` + proceed.
+- Never invent legacy intent from code alone — that's what Path C (the SME interview) is for. Log it as an open question if no SME is available, don't guess.
+- `✋` gates (Stage 0 Triage) do not resolve to `ASSUMED` — they need an explicit `CONFIRMED` answer before the run proceeds.
+- **Module briefs (translation mode):** you own the brief file and write the business layer (roles/journeys, screens-per-role, the access table, field-level validation, edge cases, open questions). Pull `architect-agent` for the technical layer (domain summary, write-mode plan, cross-module deps). Point to source artifacts — never duplicate wireframe or domain-model content into the brief. Produce briefs just-in-time (module N after N−1 gates), not all upfront.
+
+## Workflow (extraction / gate mode)
+1. Identify which stage's gate you're running (from `conversion-runbook.md` §2).
+2. Do the homework: read {{KB_PATH}}, {{SOURCE_PATH}}, and query the live model if the question touches it.
+3. Draft the proposal (options + evidence + assumptions) and the stage HTML surface at {{STAGE_HTML_PATH}}.
+4. Ask the user; record the answer in {{STAGE_HTML_PATH}} and `PROJECT.md` as `CONFIRMED`, or apply the recommendation and mark it `ASSUMED` with the risk if the user has no answer yet (non-✋ gates only).
+5. Update `PROJECT.md`'s open-questions register.
+
+## Workflow (translation mode — authoring a module brief)
+1. Read `module-brief.md` for the format and ownership rules.
+2. Read the module's BRDs, wireframes, and the build-plan access-table slice. Query the live model for exact names.
+3. Write the business layer of `architecture/modules/<Module>/module-brief.md`; request the technical layer from `architect-agent`.
+4. Run the brief's ready-check. Any unresolved item stays an open question the `mdl-agent` must escalate — do not paper over it.
+
+## Report back
+Which gate or brief you produced, the decision(s) recorded, which are `CONFIRMED` vs `ASSUMED`, and what's still open.
+```
+
+### architect-agent
+```
+---
+name: architect-agent
+description: "Owns Stage 3 (Architecture & Design) and Stage 4 (Build Plan) for {{PROJECT}} — module boundaries, blueprint, fit-gap, build plan. Use once BRDs are validation-clean. Never touches mxcli."
+model: <strong tier — copy the alias the shipped stub pins>
+tools: Read, Grep, Glob, Bash
+---
+
+You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you never run `mxcli exec` and never write MDL — that's `mdl-agent`'s job, downstream of your build plan.
+
+**Paths:** resolve all project paths (BRDs, architecture, design, briefs, build plan) from the **`## Wiring` block of the project-root `CLAUDE.local.md`** — the single source of truth. Read it at task start; don't hardcode paths.
+
+## Ground rules
+- Follow `modularize-domain.md`'s boundary criteria; default to one module + folders unless a candidate clears >=1 criterion.
+- Run the Stage 3/4 interview gates from `conversion-runbook.md` §2 — module boundaries, buy/build/stub per fit-gap item, target security model, data volumes/NFRs, integration contracts, branding, acceptance criteria, environment/DTAP. These are `✋` gates: no `ASSUMED` past them, only `CONFIRMED`.
+- Query the live model (`query-the-model.md`) before referencing any marketplace module in the build plan — `SHOW ENTITIES IN <module>` first, always.
+- **Module briefs — you contribute the technical layer when `ba-agent` requests it** (`ba-agent` owns the file and drives; see `module-brief.md`). Your layer: domain summary (pointer to the domain MDL for exact names, not a copy), the write-mode plan per element (CLI / MCP+MDL / hand-rolled MCP, per `learned-mdl-preflight.md` Step 0), cross-module dependencies, stub-vs-real integrations, and any arch constraint that applies to this module. Point to source artifacts; never duplicate them into the brief.
+
+## Workflow
+1. Read the validation-clean BRDs and any existing `architecture/`, `design/` artifacts.
+2. Propose module boundaries / fit-gap decisions with evidence; run the interview protocol.
+3. Write `.mx-brd.json`, `architecture/` (blueprint, wiring diagrams, fit-gap.md), and once approved, `architecture/build-plan.md` — numbered, dependency-ordered.
+4. Record every decision in `PROJECT.md`.
+
+## Report back
+Boundaries/decisions proposed vs. confirmed, the build plan's pending-decisions count, and anything still blocking Stage 5.
+```
+
+### mdl-agent
+```
+---
+name: mdl-agent
+description: "Drafts and syntax-validates mxcli MDL scripts for {{PROJECT}}. Use when a microflow/page/domain-model script needs to be written or fixed, before it's executed against the real .mpr."
+model: <mid tier — copy the alias the shipped stub pins>
+tools: Read, Grep, Glob, Bash
+---
+
+You write MDL scripts for {{PROJECT}}. You draft and validate — you never execute against the real `.mpr`.
+
+## Paths — read the Wiring block, don't hardcode them here
+All project paths (MPR, `mdlsource/`, module briefs, wireframes, design system, StyleGallery,
+architecture, build plan, BRDs) live in the **`## Wiring` block of the project-root `CLAUDE.local.md`** —
+the single source of truth. Read it at the start of every task and resolve paths from it. When a rule
+below names an asset ("the wireframe", "the brief"), it means the path from that block.
+
+## Ground rules
+This file is a **router**: the detailed rules live in the skills it names — open them, don't rely on
+this summary. The hard STOPs below are inline on purpose; never route around them.
+
+- **Read the module brief first — your single entry point.** Read the module's brief (briefs path in
+  the Wiring block; format in `module-brief.md`): roles/access, screens, validation, write-mode plan,
+  pointers. **No brief → STOP and report** — a missing brief means `ba-agent` translation mode was
+  skipped; do not synthesize the module from raw BRDs yourself.
+- **An unchecked open question in the brief is a stop sign.** If one touches what you're building,
+  surface that specific question to the main session (for `ba-agent`) — never fill it from training data.
+- Business rules come from the brief and {{BUSINESS_RULES_SOURCE}}; read the domain-model script
+  (Wiring block) for exact, case-sensitive names. Don't guess names or rules.
+- **Write mode, per operation, up front:** run `learned-mdl-preflight.md` Step 0 — the default is the
+  CLI through `bin/exec.sh`; its STOP table overrides that for operations mxcli corrupts or cannot
+  express, which go to Studio Pro by hand. State the mode per op in your report, and flag any op that
+  needs Studio Pro so the main session sequences the handoff.
+- Annotate selectively (`learned-microflow-patterns.md`); always annotate a CE-error fix.
+- **Pages/snippets — run the full pre-flight in `ui-preflight-pages.md`** (wireframe → tokens →
+  gallery reuse → cross-check) and include its UI cross-reference block in your report. **No wireframe
+  → STOP** — do not guess layout or bindings. Reuse existing gallery components; don't reimplement
+  them as plain text.
+- **Complex microflows:** confirm alignment against the brief's technical layer + the architecture
+  blueprint (Wiring block) before drafting. Report any mismatch.
+- **Grants co-located** with the element (per the brief's access table): `grant execute` ends the
+  microflow script, `grant view` ends the page script, entity grants end the domain script.
+
+### Trivial-change fast path
+For a genuinely mechanical script — a forward-reference stub, an added enum value, a rename, a
+constant, a pure domain-attribute add with no page — skip the UI pre-flight and per-page review
+(there's no rendered surface to verify). Still required: read the brief for names, the
+`learned-mdl-preflight.md` STOP check, `mxcli check`, and the mxbuild gate. Anything that adds/alters
+a page, widget, or user-facing microflow is **not** trivial — treat as full-discipline when unsure.
+
+## Workflow
+1. **Read the `## Wiring` block** in the project-root `CLAUDE.local.md` — resolve all paths from it.
+2. **Read the module brief** (briefs path from Wiring) — if missing, STOP and report.
+3. Read the task spec (which elements this build unit covers) against the brief.
+4. Read the necessary skill file(s) and existing MDL for exact names (the brief points to them).
+5. For pages/snippets: locate the wireframe (named in the brief) — if missing, STOP. Then complete `ui-preflight-pages.md` in full.
+6. For complex microflows: confirm alignment against the brief + architecture blueprint.
+7. Write the script to the requested path (under the mdlsource dir from Wiring) — grants co-located.
+8. Run `mxcli check <path> -p <MPR from Wiring> --references` and iterate until clean.
+8a. **Log the dispatch** (discharges the `dispatch` obligation, `bin/lib/obligations.tsv`): under the
+    project root, `mkdir -p .claude/loop/dispatch/<Module>/` (Module from the brief) then append one
+    TAB-separated line to `.claude/loop/dispatch/<Module>/scripts.tsv`:
+    `<date>	<script path from step 7>	<check result from step 8>` — date as `YYYY-MM-DD`. This is the
+    only record that this module's scripting went through mdl-agent's preflight rather than being
+    drafted in the main session; it owes no denominator, just the line.
+9. Do NOT run `mxcli exec` — that stays in the main session under the user's confirmation.
+
+## Report back
+Plain-language summary of what the script does, the file path, the check result, and any open questions or unverified-syntax risks. For page scripts, include the full UI cross-reference block.
+```
+
+### gate-agent
+```
+---
+name: gate-agent
+description: "Runs {{PROJECT}}'s build/quality gates after a script has been executed against the .mpr, and reports pass/fail with a digested error list. Use after any mxcli exec, not before."
+model: <mid tier — copy the alias the shipped stub pins>
+tools: Read, Grep, Glob, Bash
+---
+
+You verify {{PROJECT}} after changes have already been applied to the `.mpr`. Read-only / verification-only — never write files, never run `mxcli exec`.
+
+## Gates to run (in order)
+1. **Model check**: {{MODEL_CHECK_COMMAND}}. Expect 0 CE errors.
+2. **Compile gate** (if applicable): {{COMPILE_GATE_COMMAND}}.
+3. **Lint, always**: read the lint cell `bin/exec.sh` wrote into the BUILD-LOG row (it runs
+   `bin/lint-gate.sh` after every clean mxbuild); a `LINT ROSE` cell fails the script. Re-run
+   {{LINT_COMMAND}} only for the per-document list. Never re-baseline to make a row green.
+
+## Known gotchas
+{{PROJECT_SPECIFIC_GOTCHAS — e.g. stale .mpr.lock files, access-grant drops after CREATE OR REPLACE, stale proxy folders after a module rename}}
+
+## Report back
+Pass/fail per gate, the exact error list if any, and whether failures match a known-gotcha pattern. Terse — a status report, not a narrative.
+```
+
+### test-agent
+```
+---
+name: test-agent
+description: "Walks happy-path and edge-case UI tests against the running {{PROJECT}} app and reports pass/fail per scenario. Use after a gate-agent pass, once a feature is expected to be clickable end-to-end."
+model: <mid tier — copy the alias the shipped stub pins>
+tools: Read, Grep, Glob, Bash
+---
+
+You test {{PROJECT}}'s running UI. Verification-only — never edit MDL, never touch the `.mpr`, never run `mxcli exec`.
+
+## Before you start
+- Read {{TEST_SETUP_SKILL_REFS}} for this project's exact test setup (demo user, how the app is started, DB assertion pattern).
+- Confirm the app is actually running before testing; if it isn't, that's a blocker to report, not something to silently work around.
+
+## Workflow
+1. Take the scenario list you were given.
+2. Log in as {{DEMO_USER}}, not the admin account, unless the scenario specifically calls for admin.
+3. Walk each scenario step, capturing what happened.
+4. Cross-check state-changing results against the database rather than trusting the UI alone.
+
+## Report back
+Per-scenario pass/fail, the exact failing step (if any) with expected vs. observed, and any UI/data mismatches. Don't narrate every click.
+```
+
+### review-agent
+```
+---
+name: review-agent
+description: "Closes a module in {{PROJECT}}: runs the model-side review instruments, then LOOKS at every page in the module and says whether it is logical, whether it looks right, and whether it matches the design. Use when a module's build and gate stages are done. Diagnostic only — never fixes anything."
+model: <mid tier — copy the alias the shipped stub pins>
+tools: Read, Grep, Glob, Bash
+---
+
+You run `skills/module-review.md` for {{PROJECT}}. Read that skill in full before you start; this
+file only tells you where things are.
+
+## What you own
+Stage 3's model-side instruments, and **stage 4 — the LOOK**. Stage 4 is the reason you exist.
+Stages 1–3 are already covered by mdl-agent, gate-agent, test-agent and `bin/verify-module.sh`;
+none of them can answer "is this screen logical, does it look right, does it match our design",
+and a module has repeatedly shipped broken because nobody asked.
+
+## The page set is every page in the module
+```
+{{MXCLI}} -p {{MPR}} -c "SHOW PAGES IN <Module>"
+```
+Not the pages a journey visited. A page no test touches is the highest-risk page in the module.
+Report the denominator: `12 of 12 pages reviewed`, never "reviewed the module".
+
+## Order
+1. `bin/verify-module.sh <Module>` results — read them, do not re-run them.
+2. `node tests/e2e/design-audit.js` — the mechanical sweep (classes, a11y, overflow). Where it
+   and your eye overlap, it wins.
+3. **Then look**, page by page, per module-review.md §4c/§4d/§4e. Navigate via the nav menu or a
+   button, never a direct URL.
+4. Write the report to `design/ui-reviews/ui-review-<YYYY-MM-DD>.html` and append every P1/P2 to
+   `docs/improvement-register.md`.
+
+## When an input is missing, you assess anyway
+A missing wireframe, an absent design system, an uninstalled `design-audit.js`, a module with no
+brief — none of these is permission to skip a page. Follow module-review.md's
+**"Degrade to judgement, never to silence"** table: name what is missing, name what you assessed
+against instead, and still deliver a verdict per page. Reduced fidelity is reported as reduced
+fidelity. It is never reported as a pass, and never reported as nothing.
+
+## You never fix
+No MDL, no `mxcli exec`, no edits to the model or the theme. You have no Write or Edit tool. End
+by asking which P1/P2 findings should be fixed — the fix routes back through mdl-agent.
+
+## Project specifics
+- MPR: {{MPR}} · app URL: {{APP_URL}} · demo user: {{DEMO_USER}}
+- Wireframes: {{WIREFRAME_DIR}} · design system: {{DESIGN_SYSTEM}} · StyleGallery: {{STYLEGALLERY}}
+- All of the above resolve from the `## Wiring` block of `CLAUDE.local.md` — read it at task start.
+```
diff --git a/process/baseline-incident-history.md b/process/baseline-incident-history.md
new file mode 100644
index 00000000..9a3fe133
--- /dev/null
+++ b/process/baseline-incident-history.md
@@ -0,0 +1,270 @@
+# Baseline incident history — the full stories behind the always-on rules
+
+**Read on demand, never at session start.** The always-on (baseline) skills state each rule
+with a one-line failure example and a pointer here. This file holds the long form: the
+incident narratives, measurements and design history that used to sit inline in those skills,
+moved verbatim so the evidence survives while the baseline stays inside the
+`bin/render-routing.sh --check` word budget (CLAUDE.md skill-authoring rule 6, "write for the
+trigger, then stop").
+
+Each section id (`R1`, `AR2`, …) is what the pointer in the skill cites. The section text is
+the original wording, unedited — when a rule's justification is challenged, cite from here.
+Nothing in this file is a rule on its own; the rule lives in the skill that points here.
+
+## R1 — Entry-mode misrouting incidents
+
+_From `skills/conversion-runbook.md`._
+
+(Real misrouting incident, 2026-07-14: a project with full specs + analyzable source was classified greenfield "because there's nothing to migrate," proposing to skip 0–4 — exactly what rules 2–3 exist to prevent. Second incident, 2026-09-22: `intake.md` Q1 offered only three modes, so a session changing a live app could not pick the fourth even though `gate-check.sh` already recognised it — rule 1 and the table row below are the fix.)
+
+## R2 — Why Stage 0 runs in every entry mode (2026-08-20)
+
+_From `skills/conversion-runbook.md`._
+
+This distinction was implicit until 2026-08-20, when a customer round made the cost of leaving it
+implicit measurable. A project whose source was markdown files plus database tables was classified
+requirements-driven — reasonably, given the rules above. The mode's row then said "skip 0", so
+Stage 0 was skipped **whole**: no source characterisation, no `analysis/` folder, no triage
+artifact, and — the expensive one — **no scope conversation**, because CAC-1 fires after Stage 0
+and Stage 0 never ran. Extraction was then run anyway and pulled in far more than the subsystems
+under discussion, which nothing downstream was positioned to notice: Stage 2's gate checks that
+BRDs are *validation-clean*, and a hundred clean BRDs describing things nobody asked for pass it.
+
+## R3 — Why the docs-ready path exists (2026-09-09)
+
+_From `skills/conversion-runbook.md`._
+
+**Why this path exists (2026-09-09).** A project of exactly this shape was slow and token-hungry
+through Stages 1–4, for measured reasons: every session read the raw HTML (3–10× the tokens of
+its text), and the ledger asked for one disposition per file — every sidecar `.png`, `.css` and
+`.js` included — for a corpus nothing extracts. Nothing below skips a gate; it names the shortest
+honest route through them, and every command here was run against the gates before it was written.
+
+## R4 — The accumulated open-questions stream that rotted (2026-08-12)
+
+_From `skills/conversion-runbook.md`._
+
+**The gate's own questions are not the only questions — raise the accumulated batch too.** Steps 1–6 govern the questions the *gate* asks. But the pipeline generates a second stream all the time: every `openQuestions` entry a BRD records, every row added to `analysis/sme-questions.md`. Those were never wired to anything, and they rotted. Measured on one real project (2026-08-12): 46 rows in `sme-questions.md` against 7 mentions of an answer, ~35 unresolved BRD `openQuestions`, one status reading *"Open — routed to sme-questions.md F1/F2"* — routed to a file nobody opens. Several were not merely unasked but already **decided**: *"ASSUMED drafting position (a), hardcode — taken to keep this BRD buildable… NOT a settled product decision"* is a real product choice (hardcode vs. build a configurable rules engine) taken unilaterally and never shown to anyone. And 23 distinct free-text status strings meant nothing could count them, which is why nothing ever surfaced them.
+
+## R5 — Attended run with no questions (2026-07-14)
+
+_From `skills/conversion-runbook.md`._
+
+(Real incident, 2026-07-14: an attended run produced architecture diagrams and a design system through Stage 3 without a single question reaching the user — "a solo run never stalls" was read as "never ask." It means "an *authorized* solo run doesn't deadlock," nothing more.)
+
+## R8 — Settled change routed through three subagents (2026-07-23)
+
+_From `skills/conversion-runbook.md`._
+
+(Real incident, 2026-07-23: a "flip 2 entities to persistent + add 2 new entities" change — already fully settled in conversation — was routed through ba-agent twice and architect-agent once, ~270k combined tokens, for what was fundamentally a handful of document edits. The user called it out directly. The fix isn't skipping the record, it's skipping the dispatch when there's nothing left to decide.)
+
+## R9 — Gate script never run through a full Stage 5 (2026-09-19)
+
+_From `skills/conversion-runbook.md`._
+
+**Why (measured, 2026-09-19, two field builds of the same app).** A full Stage-5 build closed with all seven screens built, a green mxbuild
+   gate, and 11 of 37 acceptance rows confirmed. `gate-check.sh` had run exactly once, at
+   scaffold time. The `look` obligation, the wiring sweep, journeys and coherence were all
+   `PENDING` and nobody saw it, because nothing asked. When the gate was finally run as a
+   deliberate second pass, the seven screens scored 0, 18, 40, 40, 58, 58 and 69 percent against
+   their own wireframes on an element checklist — one screen matched none of its wireframe's
+   elements at all. Every one of those defects was visible to a gate that never ran.
+
+## R10 — Why dispatch is written down (2026-09-14)
+
+_From `skills/conversion-runbook.md`._
+
+**Why this is written down (2026-09-14).** The six agent stubs have carried model tiers since
+they were generated (`architect-agent` on the strong tier, the other five on the mid tier), and
+§2's Owner rows name who is accountable for each stage. Nothing said *when* the main session
+hands work over — so in the token-path A/B (nine runs, Stages P–4) the main session did nearly
+everything itself, at its own model's price, and only two skills (`brd-generation.md`,
+`image-transcription.md`) ever asked for a fan-out. Owner is accountability; this table is the
+runtime rule.
+
+## R12 — Checkpoints named nowhere in the runbook (until 2026-08-20)
+
+_From `skills/conversion-runbook.md`._
+
+**Every stage transition has a packaged checkpoint. Here is where they attach.** The `skills/checkpoints/`
+CAC files run the §1 interview protocol at the busiest transitions; they write to `PROJECT.md`,
+never to a separate state file. Until 2026-08-20 this runbook — the file every session is required
+to read — **named none of them**, and they were reachable only from `skills/migration-pipeline.md`.
+A requirements-driven session never loads that skill, so it never fired a single checkpoint, and
+CAC-1's scope brainstorm silently did not exist outside migration mode. Checkpoints are wired to
+*stages* here, not to pipeline phases, precisely so that a project running no pipeline still gets
+them.
+
+## R16 — Grade before inventory: a rubric question instead of a scope conversation (2026-08-19)
+
+_From `skills/conversion-runbook.md`._
+
+Doing this out of order is a real, reported failure (2026-08-19): a Stage 0 run on a four-file
+documents-only corpus produced a correct ten-dimension grade and then asked the user a closed,
+rubric-shaped gate question — because the grade was the only artifact in front of it. The
+instruction to present a source map already existed here; nothing produced the map, so the agent
+asked what the tooling gave it something to ask about.
+
+## R17 — Documents plus a database misrouted as prose (2026-08-20)
+
+_From `skills/conversion-runbook.md`._
+
+(The paragraph below followed "Does not apply stops at the extraction rows" and restated the rule of the preceding "Decide that on evidence" paragraph; it was merged into that paragraph.)
+
+**A source that is documents plus a database is not a documents-only source.** A schema, a table
+dump, or an ORM model file is extractable structure and grades as such — the presence of markdown
+alongside it does not downgrade it. This is the shape that misroutes most often in presales
+(2026-08-20): the corpus *reads* like requirements, so it gets treated as prose, and the entities
+that were sitting right there in the schema get re-derived by hand later.
+
+## R18 — Why CAC-1b exists: extraction over-reach (2026-08-20)
+
+_From `skills/conversion-runbook.md`._
+
+**Closes with CAC-1b** (`skills/checkpoints/checkpoint-extraction.md`) — the scope-out
+confirmation. It is a checkpoint you run, not a gate that stops you, and the reason is worth
+keeping in front of you.
+
+Stage 0 confirms scope *in*: what we intend to cover. It cannot confirm scope *out*, because
+nobody knows what extraction will actually produce until it has produced it. On the customer round
+that prompted this, extraction ran across the whole corpus rather than the subsystems under
+discussion, and the over-reach was invisible until modules were being built — every downstream
+gate measured *quality*, and the output was perfectly good BRDs about the wrong things. A
+validation-clean BRD for a subsystem nobody asked for is a clean pass at every remaining gate in
+this runbook.
+
+So before any BRD is written: put the extraction result next to the Stage 0 scope decision, name
+the delta, and get a decision on it. Do it before the BRDs rather than after — writing them first
+makes narrowing feel expensive, which is exactly when people stop narrowing.
+
+**Nothing enforces this and nothing should.** A script can only check that a `CONFIRMED` row
+exists in `PROJECT.md`, and an agent can type that row without asking anyone — so the check
+cannot tell the conversation from the string, which is the only thing worth telling apart. (A
+blocking version of this gate existed for part of 2026-08-20 and was removed the same day; see
+`skills/skills-over-scripts.md`.) If the checkpoint gets skipped, run it late against the BRD set
+you already have — with the extraction report in hand you can see what actually came out, which
+is better input than the triage map ever was.
+
+## R19 — Stage 1 surface history (until 2026-08-20)
+
+_From `skills/conversion-runbook.md`._
+
+Until 2026-08-20 this was `node generate-report.js` inside each pipeline, so requirements-driven and greenfield projects could not produce the file their own Stage 1 gate requires, despite this row promising it.
+
+## R20 — Stage 2 surface history (until 2026-08-19)
+
+_From `skills/conversion-runbook.md`._
+
+Until 2026-08-19 this was `enrichment-summary.html`, built three times inside three pipelines against three different BRD key shapes — each copy rendered blanks for the other two’s output, and non-migration projects got no surface at all despite this row promising one.
+
+## AR1 — "Five" agents, and the review that never looked (2026-08-20)
+
+_From `skills/agent-roles.md`._
+
+> **This file said "five" until 2026-08-20, and that cost the review.** `review-agent` — the owner
+> of `module-review.md` stage 4, the LOOK — has been scaffolded by `bin/lib/install-manifest.sh`
+> and routed to its skills for some time, but this file never listed it. So every session that set
+> agents up "per `agent-roles.md`" completed five, left the sixth an inert stub, and then ran a
+> module review with no configured owner for the one stage that finds the escaped defects.
+> Measured consequence: an end-to-end run that executed journeys, DB/OQL assertions and the monkey
+> pass, reported them, and never looked at a single page. **The count is load-bearing. It is six.**
+
+## ST1 — "Already used as triage input" — the deck nobody read (2026-09-02)
+
+_From `skills/source-triage.md`._
+
+> **A claim that another document already handled a file is a claim to verify, not an
+> answer.** Real incident, 2026-09-02, a VBA migration: intake Q4 ("documents not yet accounted
+> for?") was closed with *"the .pptx is already inside `source/` and was already used as triage
+> input by the Group A–D triage pass"*. The triage was derived from the `.cls` exports and never
+> named the deck; its 22 diagrams — the only place the workflow engine's X/M/E semantics were
+> written down — went unread for two months of BRDs, blueprint and build plan, and a `CONFIRMED`
+> architecture decision had to be reversed. The wrong answer *reads* right because it cites a
+> document. The right form is the ledger's: **name the artifact, and let the gate grep it.** A
+> text read of a deck is not the deck either — a 25-slide, 22-image container is consumed when
+> the disposition says `--pages 25 --media 22`, not when its title appears in a summary.
+
+## ST2 — Mixed corpora routed wholesale down the document path
+
+_From `skills/source-triage.md`._
+
+Mixed corpora are where this goes wrong, and they are the normal case in presales. The folder
+*reads* like requirements, so the whole thing is sent down the document path (`kb-generation.md`,
+Path B) and comes back as prose — including the entities that were sitting in the schema, which
+then get re-derived by hand three stages later. Prose is the right reading method for prose and
+the wrong one for structure. Choosing per artifact is this step's job; routing a whole corpus by
+how it looks at a glance is the failure it exists to prevent.
+
+## ST3 — Field evidence for read-vs-parse: one export, one spec, one inventory (2026-09-07)
+
+_From `skills/source-triage.md`._
+
+**Field evidence, 2026-09-07** — a no-code app replacement whose corpus was one data export
+(`.ods`), one 3.5 MB reverse-engineering spec (`.html`) and one workflow inventory (`.md`):
+
+- The **export parser corrected the documents written about it**: 53 stored columns against
+  128–175 documented (~120 are computed in the platform — neither attributes to model nor data to
+  migrate), four different spellings of one foreign key across four sheets, 15 sheets where the
+  spec documented 17, plus per-sheet volumes. No reading of any document produces one of those.
+- A **regex classifier over the spec's prose scored ~50% precision and ~50% recall** against a
+  user-confirmed sample, and was deleted the same day. It read the spec's "what the recording
+  covered" bullets as requirements, truncated sentences at inline HTML tags, and matched none of
+  the negative-form statements ("there is no role model", "no reminders, no escalation") that
+  carried some of the sharpest requirements in the document. The same agent's plain read of the
+  same file, at intake, was better in one pass.
+- The user's question is the rule in one line: *"do we need an extractor for html & md files?
+  Can't we just analyse and conclude what it should be? But when it's ppt and images better yes?"*
+
+## ST4 — Why "both, not either" is spelled out (2026-09-07)
+
+_From `skills/source-triage.md`._
+
+**Why this is spelled out (2026-09-07).** `conversion-runbook.md`'s Stage-0 applicability table
+said the extraction call was **`N/A` for requirements-driven**, flatly — while this skill and the
+shipped `triage.md` header said `N/A` only where the corpus holds no extractable structure, "on
+evidence, never on the entry-mode label". The runbook is the file every session is required to
+read first, so the unconditional version was the one that got followed. On the project that
+surfaced it — requirements-driven, corpus of one spec, one workflow inventory and **one platform
+data export** — following the runbook literally would have marked extraction `N/A` and left the
+export unparsed. That parser went on to correct the very documents written about the app: 53
+stored columns against 128–175 documented, four spellings of one foreign key across four sheets,
+15 sheets where the spec said 17. Same shape as the `toolkit-guide.html` first-touch incident in
+`CLAUDE.md`: a rule stated conditionally in its owning file and unconditionally in the front
+door, where the front door wins. The runbook now defers here.
+
+## IP1 — Branding question batch-approved as a recommended default (2026-08-19)
+
+_From `skills/interview-protocol.md`._
+
+*Real incident, 2026-08-19 (PROJECT-B).* "Are there branding inputs?" went in as line 7
+of a seven-item Stage 3 gate batch, carrying the recommended default *"no branding assets
+provided — use Atlas defaults."* The user approved the batch. There was in fact a real art
+direction — top-bar layout, industrial look, grey background, cool colours, the client wordmark in
+the shell — and a WCAG 2.1 AA target, and neither had ever been asked for. Both surfaced only
+when the user challenged the finished design system and asked why nobody had checked. The
+question had been treated as a `gap`. The recommendation was the entire defect: it converted
+"I don't know" into "I've decided", and a batch approval swallowed it.
+
+## IP2 — "AskUserQuestion doesn't seem installed" — the Copilot dry run (2026-08-19)
+
+_From `skills/interview-protocol.md`._
+
+*Why this is spelled out (real incident, 2026-08-19).* A dry run of this toolkit on GitHub
+Copilot on Windows produced the question *"AskUserQuestion doesn't seem installed, is that
+something we can include in the setup?"* It cannot be. Until then every call site here named
+the tool as **the** mechanism, so on a non-Claude agent the instruction was simply
+unfollowable — and an unfollowable gate is not a loud failure, it is a silent skip. Same shape
+as the Stage P false-green: the enforcement quietly evaporates and nothing says so.
+
+## IP3 — "X already covers this" — the verbatim intake answer (2026-09-02)
+
+_From `skills/interview-protocol.md`._
+
+Verbatim, from a real intake (2026-09-02, Q4 "documents not yet accounted for?"):
+
+> the `.pptx` is already inside `source/<track>/` and was already used as triage input by the
+> Group A–D triage pass (see `<track>-triage.md`) — nothing additional exists outside the folder.
+
+The triage never named the deck. Two months of downstream artifacts inherited the gap, because
+once Q4 read "answered" nothing had a reason to look again. The answer *cited a document*, which
+is exactly why it was believed.
diff --git a/skills/agent-roles.md b/skills/agent-roles.md
index 01ba7ba4..d9aca394 100644
--- a/skills/agent-roles.md
+++ b/skills/agent-roles.md
@@ -18,19 +18,15 @@
 
 **Mechanical scaffolding exists:** `bin/init-agents.sh <session-root> [p|build|all]` copies stub versions of all **six** agents (from the toolkit's `agents/` folder) into the project's `.claude/agents/` — `p` for the Stage-P pair (ba/architect), `build` for the Stage-5 quartet (mdl/gate/test/**review**). The stubs are safe by construction: each refuses to run while `{{PLACEHOLDER}}`s remain, so "downloaded but never configured" fails loudly instead of verifying nothing. Your job after scaffolding is Steps 1–4 below: fill every placeholder from the *actual* project, including the **Domain context** block.
 
-> **This file said "five" until 2026-08-20, and that cost the review.** `review-agent` — the owner
-> of `module-review.md` stage 4, the LOOK — has been scaffolded by `bin/lib/install-manifest.sh`
-> and routed to its skills for some time, but this file never listed it. So every session that set
-> agents up "per `agent-roles.md`" completed five, left the sixth an inert stub, and then ran a
-> module review with no configured owner for the one stage that finds the escaped defects.
-> Measured consequence: an end-to-end run that executed journeys, DB/OQL assertions and the monkey
-> pass, reported them, and never looked at a single page. **The count is load-bearing. It is six.**
+> **The count is load-bearing. It is six.** Failure when this file said "five": sessions left
+> `review-agent` an inert stub, and a module review ran journeys, DB assertions and the monkey pass
+> but never looked at a single page (2026-08-20, `process/baseline-incident-history.md` §AR1).
 
 ---
 
 **When to dispatch, in what batch, on which tier:** `conversion-runbook.md` §1c is the single source. **How to dispatch** — the four harness defaults to override on every call — is the next section. The rest of this file is the setup.
 
-The `model:` line in each template below is pinned to match the shipped stub at `agents/<name>-agent.md` — see `conversion-runbook.md` §1c for the why.
+The `model:` line of every completed agent is pinned to the shipped stub at `agents/<name>-agent.md` (never inherited) — see `conversion-runbook.md` §1c for the tiers.
 
 ## Dispatching — override four defaults on every call
 
@@ -170,247 +166,13 @@ works.
 
 ## Template shapes (adapt, don't copy verbatim)
 
-### ba-agent
-```
----
-name: ba-agent
-description: "Owns discovery, interview gates, AND per-module briefs for {{PROJECT}} (conversion-runbook.md Stages P, 0-2, 4, 7). Two modes: EXTRACTION (P-2, no spec yet -> produce BRDs) and TRANSLATION (Stage 4 -> turn validation-clean BRDs into module briefs). Use for intake, triage, requirements, any proposal-with-evidence interview, and authoring module briefs."
-model: sonnet
-tools: Read, Grep, Glob, Bash
----
-
-You run discovery, the interview gates, and module-brief authoring for {{PROJECT}}. You never touch the `.mpr` and never run `mxcli exec` — you produce decisions and records, not model changes.
-
-**Paths:** resolve all project paths (KB, BRDs, wireframes, briefs, architecture, stage HTML) from the **`## Wiring` block of the project-root `CLAUDE.local.md`** — the single source of truth. Read it at task start; don't hardcode paths.
-
-## Your two modes
-- **Extraction (Stages P–2):** no spec exists yet. Produce BRDs from source/SME via the interview protocol.
-- **Translation (Stage 4, per module):** BRDs exist. Turn them into a **module brief** (`architecture/modules/<Module>/module-brief.md`, per `module-brief.md`) — the `mdl-agent`'s single entry point. **Having BRDs does not mean your job is done** — translation is the second half. If briefs don't exist, this mode was skipped.
-
-## Ground rules
-- Follow `query-the-model.md` before asking anything: check the KB/source, the current Mendix model (via a query, not the BRD), and only ask the user the part that's a genuine decision.
-- Run the full interview protocol from `conversion-runbook.md` §1 at every gate: homework first, 2-4 options with evidence, assumptions stated out loud, user answers in the terminal, decision written to the stage HTML *and* `PROJECT.md`, unknowns default + `ASSUMED` + proceed.
-- Never invent legacy intent from code alone — that's what Path C (the SME interview) is for. Log it as an open question if no SME is available, don't guess.
-- `✋` gates (Stage 0 Triage) do not resolve to `ASSUMED` — they need an explicit `CONFIRMED` answer before the run proceeds.
-- **Module briefs (translation mode):** you own the brief file and write the business layer (roles/journeys, screens-per-role, the access table, field-level validation, edge cases, open questions). Pull `architect-agent` for the technical layer (domain summary, write-mode plan, cross-module deps). Point to source artifacts — never duplicate wireframe or domain-model content into the brief. Produce briefs just-in-time (module N after N−1 gates), not all upfront.
-
-## Workflow (extraction / gate mode)
-1. Identify which stage's gate you're running (from `conversion-runbook.md` §2).
-2. Do the homework: read {{KB_PATH}}, {{SOURCE_PATH}}, and query the live model if the question touches it.
-3. Draft the proposal (options + evidence + assumptions) and the stage HTML surface at {{STAGE_HTML_PATH}}.
-4. Ask the user; record the answer in {{STAGE_HTML_PATH}} and `PROJECT.md` as `CONFIRMED`, or apply the recommendation and mark it `ASSUMED` with the risk if the user has no answer yet (non-✋ gates only).
-5. Update `PROJECT.md`'s open-questions register.
-
-## Workflow (translation mode — authoring a module brief)
-1. Read `module-brief.md` for the format and ownership rules.
-2. Read the module's BRDs, wireframes, and the build-plan access-table slice. Query the live model for exact names.
-3. Write the business layer of `architecture/modules/<Module>/module-brief.md`; request the technical layer from `architect-agent`.
-4. Run the brief's ready-check. Any unresolved item stays an open question the `mdl-agent` must escalate — do not paper over it.
-
-## Report back
-Which gate or brief you produced, the decision(s) recorded, which are `CONFIRMED` vs `ASSUMED`, and what's still open.
-```
-
-### architect-agent
-```
----
-name: architect-agent
-description: "Owns Stage 3 (Architecture & Design) and Stage 4 (Build Plan) for {{PROJECT}} — module boundaries, blueprint, fit-gap, build plan. Use once BRDs are validation-clean. Never touches mxcli."
-model: opus
-tools: Read, Grep, Glob, Bash
----
-
-You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you never run `mxcli exec` and never write MDL — that's `mdl-agent`'s job, downstream of your build plan.
-
-**Paths:** resolve all project paths (BRDs, architecture, design, briefs, build plan) from the **`## Wiring` block of the project-root `CLAUDE.local.md`** — the single source of truth. Read it at task start; don't hardcode paths.
-
-## Ground rules
-- Follow `modularize-domain.md`'s boundary criteria; default to one module + folders unless a candidate clears >=1 criterion.
-- Run the Stage 3/4 interview gates from `conversion-runbook.md` §2 — module boundaries, buy/build/stub per fit-gap item, target security model, data volumes/NFRs, integration contracts, branding, acceptance criteria, environment/DTAP. These are `✋` gates: no `ASSUMED` past them, only `CONFIRMED`.
-- Query the live model (`query-the-model.md`) before referencing any marketplace module in the build plan — `SHOW ENTITIES IN <module>` first, always.
-- **Module briefs — you contribute the technical layer when `ba-agent` requests it** (`ba-agent` owns the file and drives; see `module-brief.md`). Your layer: domain summary (pointer to the domain MDL for exact names, not a copy), the write-mode plan per element (CLI / MCP+MDL / hand-rolled MCP, per `learned-mdl-preflight.md` Step 0), cross-module dependencies, stub-vs-real integrations, and any arch constraint that applies to this module. Point to source artifacts; never duplicate them into the brief.
-
-## Workflow
-1. Read the validation-clean BRDs and any existing `architecture/`, `design/` artifacts.
-2. Propose module boundaries / fit-gap decisions with evidence; run the interview protocol.
-3. Write `.mx-brd.json`, `architecture/` (blueprint, wiring diagrams, fit-gap.md), and once approved, `architecture/build-plan.md` — numbered, dependency-ordered.
-4. Record every decision in `PROJECT.md`.
-
-## Report back
-Boundaries/decisions proposed vs. confirmed, the build plan's pending-decisions count, and anything still blocking Stage 5.
-```
-
-### mdl-agent
-```
----
-name: mdl-agent
-description: "Drafts and syntax-validates mxcli MDL scripts for {{PROJECT}}. Use when a microflow/page/domain-model script needs to be written or fixed, before it's executed against the real .mpr."
-model: sonnet
-tools: Read, Grep, Glob, Bash
----
-
-You write MDL scripts for {{PROJECT}}. You draft and validate — you never execute against the real `.mpr`.
-
-## Paths — read the Wiring block, don't hardcode them here
-All project paths (MPR, `mdlsource/`, module briefs, wireframes, design system, StyleGallery,
-architecture, build plan, BRDs) live in the **`## Wiring` block of the project-root `CLAUDE.local.md`** —
-the single source of truth. Read it at the start of every task and resolve paths from it. When a rule
-below names an asset ("the wireframe", "the brief"), it means the path from that block.
-
-## Ground rules
-This file is a **router**: the detailed rules live in the skills it names — open them, don't rely on
-this summary. The hard STOPs below are inline on purpose; never route around them.
-
-- **Read the module brief first — your single entry point.** Read the module's brief (briefs path in
-  the Wiring block; format in `module-brief.md`): roles/access, screens, validation, write-mode plan,
-  pointers. **No brief → STOP and report** — a missing brief means `ba-agent` translation mode was
-  skipped; do not synthesize the module from raw BRDs yourself.
-- **An unchecked open question in the brief is a stop sign.** If one touches what you're building,
-  surface that specific question to the main session (for `ba-agent`) — never fill it from training data.
-- Business rules come from the brief and {{BUSINESS_RULES_SOURCE}}; read the domain-model script
-  (Wiring block) for exact, case-sensitive names. Don't guess names or rules.
-- **Write mode, per operation, up front:** run `learned-mdl-preflight.md` Step 0 — the default is the
-  CLI through `bin/exec.sh`; its STOP table overrides that for operations mxcli corrupts or cannot
-  express, which go to Studio Pro by hand. State the mode per op in your report, and flag any op that
-  needs Studio Pro so the main session sequences the handoff.
-- Annotate selectively (`learned-microflow-patterns.md`); always annotate a CE-error fix.
-- **Pages/snippets — run the full pre-flight in `ui-preflight-pages.md`** (wireframe → tokens →
-  gallery reuse → cross-check) and include its UI cross-reference block in your report. **No wireframe
-  → STOP** — do not guess layout or bindings. Reuse existing gallery components; don't reimplement
-  them as plain text.
-- **Complex microflows:** confirm alignment against the brief's technical layer + the architecture
-  blueprint (Wiring block) before drafting. Report any mismatch.
-- **Grants co-located** with the element (per the brief's access table): `grant execute` ends the
-  microflow script, `grant view` ends the page script, entity grants end the domain script.
-
-### Trivial-change fast path
-For a genuinely mechanical script — a forward-reference stub, an added enum value, a rename, a
-constant, a pure domain-attribute add with no page — skip the UI pre-flight and per-page review
-(there's no rendered surface to verify). Still required: read the brief for names, the
-`learned-mdl-preflight.md` STOP check, `mxcli check`, and the mxbuild gate. Anything that adds/alters
-a page, widget, or user-facing microflow is **not** trivial — treat as full-discipline when unsure.
-
-## Workflow
-1. **Read the `## Wiring` block** in the project-root `CLAUDE.local.md` — resolve all paths from it.
-2. **Read the module brief** (briefs path from Wiring) — if missing, STOP and report.
-3. Read the task spec (which elements this build unit covers) against the brief.
-4. Read the necessary skill file(s) and existing MDL for exact names (the brief points to them).
-5. For pages/snippets: locate the wireframe (named in the brief) — if missing, STOP. Then complete `ui-preflight-pages.md` in full.
-6. For complex microflows: confirm alignment against the brief + architecture blueprint.
-7. Write the script to the requested path (under the mdlsource dir from Wiring) — grants co-located.
-8. Run `mxcli check <path> -p <MPR from Wiring> --references` and iterate until clean.
-8a. **Log the dispatch** (discharges the `dispatch` obligation, `bin/lib/obligations.tsv`): under the
-    project root, `mkdir -p .claude/loop/dispatch/<Module>/` (Module from the brief) then append one
-    TAB-separated line to `.claude/loop/dispatch/<Module>/scripts.tsv`:
-    `<date>	<script path from step 7>	<check result from step 8>` — date as `YYYY-MM-DD`. This is the
-    only record that this module's scripting went through mdl-agent's preflight rather than being
-    drafted in the main session; it owes no denominator, just the line.
-9. Do NOT run `mxcli exec` — that stays in the main session under the user's confirmation.
-
-## Report back
-Plain-language summary of what the script does, the file path, the check result, and any open questions or unverified-syntax risks. For page scripts, include the full UI cross-reference block.
-```
-
-### gate-agent
-```
----
-name: gate-agent
-description: "Runs {{PROJECT}}'s build/quality gates after a script has been executed against the .mpr, and reports pass/fail with a digested error list. Use after any mxcli exec, not before."
-model: sonnet
-tools: Read, Grep, Glob, Bash
----
-
-You verify {{PROJECT}} after changes have already been applied to the `.mpr`. Read-only / verification-only — never write files, never run `mxcli exec`.
-
-## Gates to run (in order)
-1. **Model check**: {{MODEL_CHECK_COMMAND}}. Expect 0 CE errors.
-2. **Compile gate** (if applicable): {{COMPILE_GATE_COMMAND}}.
-3. **Lint, always**: read the lint cell `bin/exec.sh` wrote into the BUILD-LOG row (it runs
-   `bin/lint-gate.sh` after every clean mxbuild); a `LINT ROSE` cell fails the script. Re-run
-   {{LINT_COMMAND}} only for the per-document list. Never re-baseline to make a row green.
-
-## Known gotchas
-{{PROJECT_SPECIFIC_GOTCHAS — e.g. stale .mpr.lock files, access-grant drops after CREATE OR REPLACE, stale proxy folders after a module rename}}
-
-## Report back
-Pass/fail per gate, the exact error list if any, and whether failures match a known-gotcha pattern. Terse — a status report, not a narrative.
-```
-
-### test-agent
-```
----
-name: test-agent
-description: "Walks happy-path and edge-case UI tests against the running {{PROJECT}} app and reports pass/fail per scenario. Use after a gate-agent pass, once a feature is expected to be clickable end-to-end."
-model: sonnet
-tools: Read, Grep, Glob, Bash
----
-
-You test {{PROJECT}}'s running UI. Verification-only — never edit MDL, never touch the `.mpr`, never run `mxcli exec`.
-
-## Before you start
-- Read {{TEST_SETUP_SKILL_REFS}} for this project's exact test setup (demo user, how the app is started, DB assertion pattern).
-- Confirm the app is actually running before testing; if it isn't, that's a blocker to report, not something to silently work around.
-
-## Workflow
-1. Take the scenario list you were given.
-2. Log in as {{DEMO_USER}}, not the admin account, unless the scenario specifically calls for admin.
-3. Walk each scenario step, capturing what happened.
-4. Cross-check state-changing results against the database rather than trusting the UI alone.
-
-## Report back
-Per-scenario pass/fail, the exact failing step (if any) with expected vs. observed, and any UI/data mismatches. Don't narrate every click.
-```
-
-### review-agent
-```
----
-name: review-agent
-description: "Closes a module in {{PROJECT}}: runs the model-side review instruments, then LOOKS at every page in the module and says whether it is logical, whether it looks right, and whether it matches the design. Use when a module's build and gate stages are done. Diagnostic only — never fixes anything."
-model: sonnet
-tools: Read, Grep, Glob, Bash
----
-
-You run `skills/module-review.md` for {{PROJECT}}. Read that skill in full before you start; this
-file only tells you where things are.
-
-## What you own
-Stage 3's model-side instruments, and **stage 4 — the LOOK**. Stage 4 is the reason you exist.
-Stages 1–3 are already covered by mdl-agent, gate-agent, test-agent and `bin/verify-module.sh`;
-none of them can answer "is this screen logical, does it look right, does it match our design",
-and a module has repeatedly shipped broken because nobody asked.
-
-## The page set is every page in the module
-```
-{{MXCLI}} -p {{MPR}} -c "SHOW PAGES IN <Module>"
-```
-Not the pages a journey visited. A page no test touches is the highest-risk page in the module.
-Report the denominator: `12 of 12 pages reviewed`, never "reviewed the module".
-
-## Order
-1. `bin/verify-module.sh <Module>` results — read them, do not re-run them.
-2. `node tests/e2e/design-audit.js` — the mechanical sweep (classes, a11y, overflow). Where it
-   and your eye overlap, it wins.
-3. **Then look**, page by page, per module-review.md §4c/§4d/§4e. Navigate via the nav menu or a
-   button, never a direct URL.
-4. Write the report to `design/ui-reviews/ui-review-<YYYY-MM-DD>.html` and append every P1/P2 to
-   `docs/improvement-register.md`.
-
-## When an input is missing, you assess anyway
-A missing wireframe, an absent design system, an uninstalled `design-audit.js`, a module with no
-brief — none of these is permission to skip a page. Follow module-review.md's
-**"Degrade to judgement, never to silence"** table: name what is missing, name what you assessed
-against instead, and still deliver a verdict per page. Reduced fidelity is reported as reduced
-fidelity. It is never reported as a pass, and never reported as nothing.
-
-## You never fix
-No MDL, no `mxcli exec`, no edits to the model or the theme. You have no Write or Edit tool. End
-by asking which P1/P2 findings should be fixed — the fix routes back through mdl-agent.
-
-## Project specifics
-- MPR: {{MPR}} · app URL: {{APP_URL}} · demo user: {{DEMO_USER}}
-- Wireframes: {{WIREFRAME_DIR}} · design system: {{DESIGN_SYSTEM}} · StyleGallery: {{STYLEGALLERY}}
-- All of the above resolve from the `## Wiring` block of `CLAUDE.local.md` — read it at task start.
-```
+The illustrative body for each of the six roles — frontmatter, ground rules, workflow, report-back —
+is in **`agents/README.md`**; read it when completing a stub (step 2 above). The shipped stubs
+`agents/<name>-agent.md` are the live templates and win where the two disagree. The rules every
+completed agent must keep regardless of shape are in this file: the tool scoping (step 3), the one
+rule on `.mpr` mutation, and the anti-patterns below. ba-agent works in two modes — **extraction**
+(Stages P–2: produce BRDs via the interview protocol) and **translation** (Stage 4: turn BRDs into
+module briefs, just-in-time, module N after N−1 gates); having BRDs does not mean its job is done.
 
 ---
 
@@ -419,5 +181,5 @@ by asking which P1/P2 findings should be fixed — the fix routes back through m
 - **Don't give any of these six agents `Write`/`Edit` directly.** File writes happen via `Bash` so the mutation boundary stays visible in the tool list, not buried in a general-purpose write permission.
 - **Don't let gate-agent or test-agent run `mxcli exec`, ever** — they exist specifically to check work the main session already committed.
 - **Don't let ba-agent or architect-agent skip the interview protocol to move faster.** A boundary or role model decided without the proposal-and-question loop in `conversion-runbook.md` §1 is exactly the failure this split exists to prevent — it just moves the unowned-decision problem into a subagent instead of fixing it.
-- **Don't copy the template shapes above verbatim into a new project.** A gate-agent checking the wrong `.mpr` filename, a test-agent logging in as a demo user that doesn't exist, or a ba-agent pointed at the wrong `PROJECT.md` path will report false confidence instead of failing loudly.
+- **Don't copy the template shapes (`agents/README.md`) verbatim into a new project.** A gate-agent checking the wrong `.mpr` filename, a test-agent logging in as a demo user that doesn't exist, or a ba-agent pointed at the wrong `PROJECT.md` path will report false confidence instead of failing loudly.
 - **Scaffold all six on day one; don't *complete* an agent before its stage starts.** The stubs are inert (refuse-to-run while placeholders remain), so having all six in `.claude/agents/` from kickoff is safe and avoids the "where's my mdl-agent?" confusion. The discipline moves to completion time: fill ba/architect at Stage P, mdl/gate/test/review at Stage 5 kickoff — completing a gate-agent before any build exists means filling its commands from guesses, which is exactly the false-confidence failure the placeholders exist to prevent. (A greenfield build starting at Stage 5 may simply never complete ba/architect — that's fine, they stay inert.)
diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md
index cc80daa8..852f3ff2 100644
--- a/skills/conversion-runbook.md
+++ b/skills/conversion-runbook.md
@@ -123,7 +123,7 @@ The stages are the same for everyone; what differs is where you enter and which
 3. **Any requirements artifacts exist** — specs, BRDs, context docs, wireframes, workshop outputs → **Requirements-driven**. Having "complete" specs does *not* mean skipping to Stage 5: stages 2–4 are where those specs become validated BRDs, an architecture, module boundaries, a design system, and an ordered plan. Skipping them means improvising all of that mid-build.
 4. **None of the above** — you're genuinely starting from a conversation → **Greenfield**. This is the narrowest mode, not the default for "no legacy system."
 
-(Real misrouting incident, 2026-07-14: a project with full specs + analyzable source was classified greenfield "because there's nothing to migrate," proposing to skip 0–4 — exactly what rules 2–3 exist to prevent. Second incident, 2026-09-22: `intake.md` Q1 offered only three modes, so a session changing a live app could not pick the fourth even though `gate-check.sh` already recognised it — rule 1 and the table row below are the fix.)
+(Failure: a project with full specs + analyzable source was classified greenfield "because there's nothing to migrate" and proposed skipping 0–4 — `process/baseline-incident-history.md` §R1.)
 
 | You're starting from… | Mode | Stages that run | What changes |
 |---|---|---|---|
@@ -137,14 +137,9 @@ The stages are the same for everyone; what differs is where you enter and which
 **Stage 0 is the scope stage. It is not the extractor stage.** Reuse-vs-build-new is one question
 *inside* it, and it is the only part that needs a codebase.
 
-This distinction was implicit until 2026-08-20, when a customer round made the cost of leaving it
-implicit measurable. A project whose source was markdown files plus database tables was classified
-requirements-driven — reasonably, given the rules above. The mode's row then said "skip 0", so
-Stage 0 was skipped **whole**: no source characterisation, no `analysis/` folder, no triage
-artifact, and — the expensive one — **no scope conversation**, because CAC-1 fires after Stage 0
-and Stage 0 never ran. Extraction was then run anyway and pulled in far more than the subsystems
-under discussion, which nothing downstream was positioned to notice: Stage 2's gate checks that
-BRDs are *validation-clean*, and a hundred clean BRDs describing things nobody asked for pass it.
+Failure it prevents: a requirements-driven project skipped Stage 0 whole — no triage, and no
+scope conversation, since CAC-1 never fired — then extracted far beyond the subsystems in scope; a
+hundred validation-clean BRDs about things nobody asked for passed Stage 2 (2026-08-20, `process/baseline-incident-history.md` §R2).
 
 So: **no entry mode may skip Stage 0, because no entry mode may skip the scope conversation.**
 What varies is how much of the stage is applicable, and inapplicability is *recorded*, never
@@ -171,11 +166,9 @@ their `_files/` sidecars), no legacy code, no Office/PDF containers. A corpus wi
 `.pdf` in it takes the ordinary requirements-driven row above, because those containers carry
 embedded images that owe their own accounting (`bin/lib/source-formats.tsv`, `media = yes`).
 
-**Why this path exists (2026-09-09).** A project of exactly this shape was slow and token-hungry
-through Stages 1–4, for measured reasons: every session read the raw HTML (3–10× the tokens of
-its text), and the ledger asked for one disposition per file — every sidecar `.png`, `.css` and
-`.js` included — for a corpus nothing extracts. Nothing below skips a gate; it names the shortest
-honest route through them, and every command here was run against the gates before it was written.
+**Why (2026-09-09):** a project of this shape read raw HTML every session (3–10× the tokens) and
+owed a ledger disposition per sidecar file (`process/baseline-incident-history.md` §R3). Nothing below skips a gate; it is the
+shortest honest route through them, each command run against the gates before it was written.
 
 | Stage | Docs-ready form |
 |---|---|
@@ -216,7 +209,7 @@ Every gate in §2 runs the same six-step shape. This is the thing that should be
 5. **The decision is written to two places**: the stage's HTML proposal doc (the artifact, customer-showable) and `PROJECT.md` (the register), marked `CONFIRMED`.
 6. **`ASSUMED` is earned by asking, never by skipping.** An answer may be recorded `ASSUMED` only after the question was actually posed and the user said "don't know" / "you decide" — that is delegation-by-consent, recorded with the risk if wrong. Deriving an answer yourself and not asking is a protocol violation, not an `ASSUMED`.
 
-**The gate's own questions are not the only questions — raise the accumulated batch too.** Steps 1–6 govern the questions the *gate* asks. But the pipeline generates a second stream all the time: every `openQuestions` entry a BRD records, every row added to `analysis/sme-questions.md`. Those were never wired to anything, and they rotted. Measured on one real project (2026-08-12): 46 rows in `sme-questions.md` against 7 mentions of an answer, ~35 unresolved BRD `openQuestions`, one status reading *"Open — routed to sme-questions.md F1/F2"* — routed to a file nobody opens. Several were not merely unasked but already **decided**: *"ASSUMED drafting position (a), hardcode — taken to keep this BRD buildable… NOT a settled product decision"* is a real product choice (hardcode vs. build a configurable rules engine) taken unilaterally and never shown to anyone. And 23 distinct free-text status strings meant nothing could count them, which is why nothing ever surfaced them.
+**The gate's own questions are not the only questions — raise the accumulated batch too.** Steps 1–6 govern the questions the *gate* asks; the pipeline also accumulates a second stream — every BRD `openQuestions` entry, every `analysis/sme-questions.md` row — and unwired, it rots. Failure: 46 SME rows with 7 answered, ~35 unresolved BRD questions, and a hardcode-vs-rules-engine product choice taken as a "drafting position" nobody was shown (2026-08-12, `process/baseline-incident-history.md` §R4).
 
 So, **as a required step at every gate, before the gate's own questions**:
 
@@ -234,16 +227,9 @@ bin/questions-report.sh <project-root> --stage <N>    # → docs/open-questions.
 
 `gate-check.sh` writes it for you whenever the open-questions row blocks a gate. Give the user the path — it is openable, sortable and forwardable to a customer SME in a way a terminal dump is not, and it flags every question that arrived without a proposed answer.
 
-The vocabulary is controlled, and only these six values are legal in a `status`:
-
-| State | Meaning | Blocks a gate? |
-|---|---|---|
-| `UNRAISED` | never put in front of the user — the default for anything not positively past it | **yes** |
-| `RAISED` | put to the user at a named gate, awaiting their reply | no |
-| `ANSWERED` | the user decided; requires a non-empty `answer` | no |
-| `ASSUMED` | agent took a position **and** the user consented after seeing it; requires `consentBy` + `consentAt` | no |
-| `MOOT` | descoped by another decision; the reason is in the text | no |
-| `UNRECOGNISED` | the normaliser could not place it — counts as **not done** | **yes** |
+The `status` vocabulary is controlled: six legal values — `UNRAISED` and `UNRECOGNISED` block a
+gate; `RAISED`, `ANSWERED`, `ASSUMED`, `MOOT` do not. Their meanings are the table in
+`interview-protocol.md` §4, the single source.
 
 An `ASSUMED` with no `consentBy`/`consentAt` is not an assumption, it is the defect: it normalises to `UNRAISED` and blocks. `bin/gate-check.sh <project-root> <N>` enforces this and will not pass a stage carrying unraised questions. Unlike protocol staleness (which notifies), this one blocks — it is the project's own state, and an architecture built on decisions the customer never saw is exactly what §1 exists to prevent.
 
@@ -251,7 +237,7 @@ Note the ruling this encodes, from the user, 2026-08-12: *"At each gate, also gi
 
 A proposal beats a questionnaire because it asks the user to **correct** something rather than supply it cold — and by the time each gate arrives, the agent has read the source and has evidence to put behind its recommendation.
 
-**Unattended mode is opt-in, never inferred.** The "default + record + proceed" behavior (skipping the wait, not the question — questions still get logged in `PROJECT.md` open-questions) is only legal when the user explicitly said to run unattended, recorded at Stage P in `PROJECT.md` (`Interview mode: unattended`). Default is **attended**: every gate question is asked in chat and the turn ends there. (Real incident, 2026-07-14: an attended run produced architecture diagrams and a design system through Stage 3 without a single question reaching the user — "a solo run never stalls" was read as "never ask." It means "an *authorized* solo run doesn't deadlock," nothing more.)
+**Unattended mode is opt-in, never inferred.** The "default + record + proceed" behavior (skipping the wait, not the question — questions still get logged in `PROJECT.md` open-questions) is only legal when the user explicitly said to run unattended, recorded at Stage P in `PROJECT.md` (`Interview mode: unattended`). Default is **attended**: every gate question is asked in chat and the turn ends there. (Failure: an attended run reached Stage 3 with zero questions asked, reading "a solo run never stalls" as "never ask" — `process/baseline-incident-history.md` §R5.)
 
 **Unattended runs keep a Ruling ledger.** Nobody can be asked, so the register alone is not
 enough: an `ASSUMED` line records the decision and sometimes the reason, never the blast
@@ -281,7 +267,7 @@ obra/superpowers, adapted; the ledger is the compensating control for the fact t
 
 And at **every** checkpoint, after the 2+1 questions: one standing open-floor question — "anything else you want changed, added, or worried about — scope, priorities, anything?" — before the gate closes.
 
-**Lightweight-change carve-out — small, unambiguous, already-decided changes skip dispatch, never skip the record.** Not every BRD/architecture edit needs the six-step protocol or a `ba-agent`/`architect-agent` round-trip. If the change is small in scope (renaming a field, adding one or two entities/attributes whose shape was already settled in the current conversation, fixing a stale line that contradicts an already-CONFIRMED decision) *and* unambiguous (no real alternatives to weigh, nothing left for the user to correct), the acting agent may edit the BRD/architecture doc directly instead of dispatching a subagent. It still MUST: (a) log the change in `PROJECT.md` — a `## Change log` row when the user asked for it (`change-intake.md`: an S change the user typed needs no question, only that row), a decision row when it settles a choice — (b) set or flip the drift-sync marker on any BRD/wireframe it touched and did not flush in the same session, per §3b. What this carve-out buys back is the interview/dispatch overhead, not the paper trail — a change made without a recorded decision or marker is exactly the drift this runbook exists to catch, however small the diff. Anything touching module boundaries, the security model, a new integration, or requiring a judgment call between real alternatives still runs the full protocol. (Real incident, 2026-07-23: a "flip 2 entities to persistent + add 2 new entities" change — already fully settled in conversation — was routed through ba-agent twice and architect-agent once, ~270k combined tokens, for what was fundamentally a handful of document edits. The user called it out directly. The fix isn't skipping the record, it's skipping the dispatch when there's nothing left to decide.)
+**Lightweight-change carve-out — small, unambiguous, already-decided changes skip dispatch, never skip the record.** Not every BRD/architecture edit needs the six-step protocol or a `ba-agent`/`architect-agent` round-trip. If the change is small in scope (renaming a field, adding one or two entities/attributes whose shape was already settled in the current conversation, fixing a stale line that contradicts an already-CONFIRMED decision) *and* unambiguous (no real alternatives to weigh, nothing left for the user to correct), the acting agent may edit the BRD/architecture doc directly instead of dispatching a subagent. It still MUST: (a) log the change in `PROJECT.md` — a `## Change log` row when the user asked for it (`change-intake.md`: an S change the user typed needs no question, only that row), a decision row when it settles a choice — (b) set or flip the drift-sync marker on any BRD/wireframe it touched and did not flush in the same session, per §3b. What this carve-out buys back is the interview/dispatch overhead, not the paper trail — a change made without a recorded decision or marker is exactly the drift this runbook exists to catch, however small the diff. Anything touching module boundaries, the security model, a new integration, or requiring a judgment call between real alternatives still runs the full protocol. (Failure: a settled 4-entity edit took three subagent round-trips, ~270k tokens — `process/baseline-incident-history.md` §R8.)
 
 **The packaged form of this protocol is a checkpoint — and checkpoints are mandatory where they exist.** `skills/checkpoints/` ships ready-made Context-Aware Checkpoints (CAC) for the six busiest transitions (scope, BRD, architecture, design, build, cutover) — each runs the protocol above as a "2 predefined questions + 1 open question" script, derived from what the pipeline actually found. Run the raw six steps only where no checkpoint exists. **A checkpoint fires *before* the next stage's artifacts are produced** — creating architecture diagrams or a design system before their checkpoint ran is a protocol violation: stop, run the checkpoint, and be prepared to throw the premature artifact away. Either way the decisions land in `PROJECT.md` — checkpoints keep no state file of their own.
 
@@ -352,13 +338,9 @@ Rules — these apply to every stage and every per-module build loop:
    item that makes the obligation check bite: it reports a pass nobody performed, but only on
    a run, and nothing before this rule required one.
 
-   **Why (measured, 2026-09-19, two field builds of the same app).** A full Stage-5 build closed with all seven screens built, a green mxbuild
-   gate, and 11 of 37 acceptance rows confirmed. `gate-check.sh` had run exactly once, at
-   scaffold time. The `look` obligation, the wiring sweep, journeys and coherence were all
-   `PENDING` and nobody saw it, because nothing asked. When the gate was finally run as a
-   deliberate second pass, the seven screens scored 0, 18, 40, 40, 58, 58 and 69 percent against
-   their own wireframes on an element checklist — one screen matched none of its wireframe's
-   elements at all. Every one of those defects was visible to a gate that never ran.
+   **Why:** a full Stage-5 build closed green with `gate-check.sh` run once, at scaffold; run
+   late, it showed LOOK, wiring, journeys and coherence all `PENDING` and the seven screens at
+   0–69% of their wireframes (2026-09-19, `process/baseline-incident-history.md` §R9).
 
 The final full-checklist repost before a gate doubles as the gate's evidence: the user should
 be able to approve the gate by reading that one message. The close-out block is what the
@@ -368,13 +350,9 @@ reader approves the *transition* on — checklist for the work, block for the ha
 
 ## 1c. Dispatch — what leaves the main session, in what batch, on which model
 
-**Why this is written down (2026-09-14).** The six agent stubs have carried model tiers since
-they were generated (`architect-agent` on the strong tier, the other five on the mid tier), and
-§2's Owner rows name who is accountable for each stage. Nothing said *when* the main session
-hands work over — so in the token-path A/B (nine runs, Stages P–4) the main session did nearly
-everything itself, at its own model's price, and only two skills (`brd-generation.md`,
-`image-transcription.md`) ever asked for a fan-out. Owner is accountability; this table is the
-runtime rule. It is the single source; `agent-roles.md` (setup) defers here. *How* to dispatch —
+**Why (2026-09-14):** with no rule for *when* to hand work over, the main session did nearly all
+of Stages P–4 itself at its own model's price (`process/baseline-incident-history.md` §R10). Owner is accountability; this table is
+the runtime rule. It is the single source; `agent-roles.md` (setup) defers here. *How* to dispatch —
 model named on every call, fresh agent not fork, fix rounds, notices — is `agent-roles.md` →
 "Dispatching".
 
@@ -444,12 +422,9 @@ Eight stages (plus Stage P kickoff). For each: what the user co-defines, what th
 
 **Every stage transition has a packaged checkpoint. Here is where they attach.** The `skills/checkpoints/`
 CAC files run the §1 interview protocol at the busiest transitions; they write to `PROJECT.md`,
-never to a separate state file. Until 2026-08-20 this runbook — the file every session is required
-to read — **named none of them**, and they were reachable only from `skills/migration-pipeline.md`.
-A requirements-driven session never loads that skill, so it never fired a single checkpoint, and
-CAC-1's scope brainstorm silently did not exist outside migration mode. Checkpoints are wired to
-*stages* here, not to pipeline phases, precisely so that a project running no pipeline still gets
-them.
+never to a separate state file. They are wired to *stages*, not pipeline phases, so a project
+running no pipeline still gets them (failure: reachable only from `migration-pipeline.md`, they
+never fired in requirements-driven mode — `process/baseline-incident-history.md` §R12).
 
 | Fires at the close of | Checkpoint | The question it exists to force |
 |---|---|---|
@@ -565,11 +540,9 @@ Then, and only then, **the open scope question** ("Scope brainstorm", further do
 present the overview, say what the corpus appears to cover versus what the user described at Stage
 P, and discuss it openly. No option lists.
 
-Doing this out of order is a real, reported failure (2026-08-19): a Stage 0 run on a four-file
-documents-only corpus produced a correct ten-dimension grade and then asked the user a closed,
-rubric-shaped gate question — because the grade was the only artifact in front of it. The
-instruction to present a source map already existed here; nothing produced the map, so the agent
-asked what the tooling gave it something to ask about. **An uncovered dimension is an open question
+Failure out of order: a four-file corpus got a correct ten-dimension grade, then a closed,
+rubric-shaped gate question — the grade was the only artifact in front of the agent (2026-08-19,
+`process/baseline-incident-history.md` §R16). **An uncovered dimension is an open question
 for a human. A low rating is a closed one. Reach the first list before the second.**
 
 Three things come out of pass 2, and each changes what you do next:
@@ -596,20 +569,15 @@ shape-changing gaps to the gate, and mark the extraction rows N/A rather than un
 **Decide that on evidence, and decide it per artifact — not off the entry-mode label.** Open the
 folder first. A schema, a table dump, an ORM model, an OpenAPI contract or entity/field tables
 inside a spec are extractable structure, and each earns a Coverage Matrix row and the two-way
-reuse-or-build call exactly as a codebase would. A mode-shaped `N/A` is precisely how the misroute
-in the next paragraph happens: the corpus reads like requirements, the whole of it goes down Path
-B, and the entities that were sitting in the schema are re-typed out of prose three stages later.
+reuse-or-build call exactly as a codebase would. A mode-shaped `N/A` is precisely how the most
+common presales misroute happens: the corpus reads like requirements, the whole of it goes down
+Path B, and the entities that were sitting in the schema are re-typed out of prose three stages
+later (`process/baseline-incident-history.md` §R17). Markdown alongside a schema does not downgrade the schema.
 
 **"Does not apply" stops at the extraction rows. It never reaches the scope brainstorm.** Read
 that sentence as licence to move on to Stage 1 and you have skipped the one thing Stage 0 exists
 for. Finish the stage: run CAC-1, get the slice ordering, sign `triage.md` off.
 
-**A source that is documents plus a database is not a documents-only source.** A schema, a table
-dump, or an ORM model file is extractable structure and grades as such — the presence of markdown
-alongside it does not downgrade it. This is the shape that misroutes most often in presales
-(2026-08-20): the corpus *reads* like requirements, so it gets treated as prose, and the entities
-that were sitting right there in the schema get re-derived by hand later.
-
 | | |
 |---|---|
 | **User defines** | Reuse-vs-build-new extraction pipeline (agent proposes with a coverage matrix — two-way call, not three-way, made per extractable structure found in the source and never off the entry-mode label; see `source-triage.md`). Policy per missing dependency: acquire / stub / declare-not-implemented. Slice ordering if the source is too big for one pass — **a slice is an ordering, not an exclusion**. |
@@ -623,34 +591,24 @@ that were sitting right there in the schema get re-derived by hand later.
 Three extraction methods, not two. Each is either **done** or **explicitly declared unavailable by a named person** — never silently skipped.
 
 **Closes with CAC-1b** (`skills/checkpoints/checkpoint-extraction.md`) — the scope-out
-confirmation. It is a checkpoint you run, not a gate that stops you, and the reason is worth
-keeping in front of you.
-
-Stage 0 confirms scope *in*: what we intend to cover. It cannot confirm scope *out*, because
-nobody knows what extraction will actually produce until it has produced it. On the customer round
-that prompted this, extraction ran across the whole corpus rather than the subsystems under
-discussion, and the over-reach was invisible until modules were being built — every downstream
-gate measured *quality*, and the output was perfectly good BRDs about the wrong things. A
-validation-clean BRD for a subsystem nobody asked for is a clean pass at every remaining gate in
-this runbook.
+confirmation; a checkpoint you run, not a gate that stops you. Stage 0 confirms scope *in*; it
+cannot confirm scope *out*, because nobody knows what extraction produces until it has. Failure:
+extraction ran across the whole corpus, and validation-clean BRDs about unrequested subsystems
+passed every remaining gate until modules were being built (`process/baseline-incident-history.md` §R18).
 
 So before any BRD is written: put the extraction result next to the Stage 0 scope decision, name
-the delta, and get a decision on it. Do it before the BRDs rather than after — writing them first
-makes narrowing feel expensive, which is exactly when people stop narrowing.
+the delta, and get a decision on it — writing BRDs first makes narrowing feel expensive, which is
+exactly when people stop narrowing.
 
-**Nothing enforces this and nothing should.** A script can only check that a `CONFIRMED` row
-exists in `PROJECT.md`, and an agent can type that row without asking anyone — so the check
-cannot tell the conversation from the string, which is the only thing worth telling apart. (A
-blocking version of this gate existed for part of 2026-08-20 and was removed the same day; see
-`skills/skills-over-scripts.md`.) If the checkpoint gets skipped, run it late against the BRD set
-you already have — with the extraction report in hand you can see what actually came out, which
-is better input than the triage map ever was.
+**Nothing enforces this and nothing should** — a script can see a `CONFIRMED` row, never the
+conversation behind it (`skills/skills-over-scripts.md`). If the checkpoint gets skipped, run it
+late against the BRD set you already have.
 
 | | |
 |---|---|
 | **User defines** | Do documents exist that aren't in the folder (specs, manuals, field-label sheets, screenshots)? DB schema? Sample data? Who has them? SME access for what neither code nor docs answer. **Then, at CAC-1b: does the extraction output match the intended scope — accept, narrow, or re-extract.** |
 | **Agent produces** | **Path A — code → AST extractors** (always runs *in migration mode*; N/A with attribution otherwise). **Path B — documents → LLM extraction** (`kb-generation.md`). **Path C — SME interview** (closes `openQuestions` that neither code nor docs answer). Plus CAC-1b's scope-out surface — the delta table when CAC-1 recorded a slice to diff against, otherwise the one-line statement of what extraction covers (a single app dropped in a folder needs stating, not interrogating). |
-| **Surface** | `analysis/source-ledger.html` — `bin/source-ledger.sh report <project-root>`: every inventoried file, its verdict, and what consumed it. `<kb>/extraction-report.html` — `bin/extraction-report.sh <project-root>`. One renderer for every entry mode: it reads the knowledge base, not the source, so a Path B document corpus gets the same surface as a Path A extraction, one page per knowledge base at the path the gate looks for. Each section carries a `report-schema.md` verdict, and no zero is printed unless a second record (the pre-merge `extracted/*.json`, or `reports/summary.md`) agrees with it — one method returning zero renders `manual`, not a green. Until 2026-08-20 this was `node generate-report.js` inside each pipeline, so requirements-driven and greenfield projects could not produce the file their own Stage 1 gate requires, despite this row promising it. |
+| **Surface** | `analysis/source-ledger.html` — `bin/source-ledger.sh report <project-root>`: every inventoried file, its verdict, and what consumed it. `<kb>/extraction-report.html` — `bin/extraction-report.sh <project-root>`. One renderer for every entry mode: it reads the knowledge base, not the source, so a Path B document corpus gets the same surface as a Path A extraction, one page per knowledge base at the path the gate looks for. Each section carries a `report-schema.md` verdict, and no zero is printed unless a second record (the pre-merge `extracted/*.json`, or `reports/summary.md`) agrees with it — one method returning zero renders `manual`, not a green. History: `process/baseline-incident-history.md` §R19. |
 | **Gate** | 4 extraction quality checks pass with evidence. Paths B and C are done or declared-unavailable, with attribution (who declared it, when). **Every row of the Stage 0 inventory has a disposition that holds up** — `bin/source-ledger.sh check <project>`: an artifact that exists, is non-empty and *names* the file (with one specific finding as evidence, and for a container its images and pages accounted for: `mark <rel> --artifact <path> --evidence "<finding → where>" --pages N --media N --by <who>`; a mention is not a reading, post-mortem 2026-09-02 F3), or a person's waiver (`bin/gate-check.sh <project> --waive source/<rel> --reason "..."`), and no file on disk without an inventory row. This part **blocks** — `bin/gate-check.sh <project> 1` exits 1 on it, and so does Stage 2 — because it is a file test, not a conversation test: "the triage already used the deck" is grepped, not believed (the 2026-09-02 miss). The rest stays advisory. Record CAC-1b's outcome as a Stage-1 `Extraction scope:` decision naming what is in and what is out, so the next session isn't guessing. |
 | **Owner** | `ba-agent` |
 
@@ -660,7 +618,7 @@ is better input than the triage map ever was.
 |---|---|
 | **User defines** | Confirms business rules the code implies. Answers `openQuestions` (via SME). Narrative is never invented. |
 | **Agent produces** | BRD scaffolds → enrichment from `KB.md` → validation to clean. `F{NNN}.brd.json`. |
-| **Surface** | `analysis/brd-report.html` — `bin/brd-report.sh <project-root>`. One renderer for every entry mode: it reads BRDs, not source, so a requirements-driven or greenfield project gets the same surface as a migration, and so does a BRD no extractor produced. Each section carries a `report-schema.md` verdict, so a section that is empty because this kind of BRD has nothing to put there reads differently from one that is empty because something broke. Until 2026-08-19 this was `enrichment-summary.html`, built three times inside three pipelines against three different BRD key shapes — each copy rendered blanks for the other two’s output, and non-migration projects got no surface at all despite this row promising one. |
+| **Surface** | `analysis/brd-report.html` — `bin/brd-report.sh <project-root>`. One renderer for every entry mode: it reads BRDs, not source, so a requirements-driven or greenfield project gets the same surface as a migration, and so does a BRD no extractor produced. Each section carries a `report-schema.md` verdict, so a section that is empty because this kind of BRD has nothing to put there reads differently from one that is empty because something broke. History: `process/baseline-incident-history.md` §R20. |
 | **Gate** | Every BRD validation-clean; `validation-report.md` has 0 issues; **every `openQuestions` entry raised in chat** — `bin/open-questions.sh <root> --stage 2` reports 0 blocking, which `gate-check.sh` enforces. Close-out block pasted (§1b rule 7) — CAC-3 opens with it. "Chased to closure" was the old wording and it was unenforceable: a question logged with a self-answer read as closed. |
 | **Owner** | `ba-agent` |
 
diff --git a/skills/interview-protocol.md b/skills/interview-protocol.md
index 19302a9a..93394e80 100644
--- a/skills/interview-protocol.md
+++ b/skills/interview-protocol.md
@@ -113,14 +113,10 @@ Typical `user-only` questions, none of which a source can answer:
 2. **Never batch-approvable.** It cannot be one line of a batch that can be cleared with "approve
    all as recommended", because there is no recommendation to approve. Ask it on its own.
 
-*Real incident, 2026-08-19 (PROJECT-B).* "Are there branding inputs?" went in as line 7
-of a seven-item Stage 3 gate batch, carrying the recommended default *"no branding assets
-provided — use Atlas defaults."* The user approved the batch. There was in fact a real art
-direction — top-bar layout, industrial look, grey background, cool colours, the client wordmark in
-the shell — and a WCAG 2.1 AA target, and neither had ever been asked for. Both surfaced only
-when the user challenged the finished design system and asked why nobody had checked. The
-question had been treated as a `gap`. The recommendation was the entire defect: it converted
-"I don't know" into "I've decided", and a batch approval swallowed it.
+*Failure:* "Are there branding inputs?" rode in a seven-item batch with the default *"use Atlas
+defaults"*; the batch was approved, and a real art direction plus a WCAG AA target surfaced only
+after the design system was built. The recommendation converted "I don't know" into "I've
+decided" (2026-08-19, `process/baseline-incident-history.md` §IP1).
 
 **Design-system questions specifically.** Branding and accessibility are `user-only` on every
 project and are asked plainly and separately at the design step — not folded into a batched
@@ -248,12 +244,9 @@ tool-specific at all — it is the half that actually enforces the gate, and the
 without `AskUserQuestion` will drop first, because "I can't call that tool" reads as "skip this
 step" rather than "render it differently".
 
-*Why this is spelled out (real incident, 2026-08-19).* A dry run of this toolkit on GitHub
-Copilot on Windows produced the question *"AskUserQuestion doesn't seem installed, is that
-something we can include in the setup?"* It cannot be. Until then every call site here named
-the tool as **the** mechanism, so on a non-Claude agent the instruction was simply
-unfollowable — and an unfollowable gate is not a loud failure, it is a silent skip. Same shape
-as the Stage P false-green: the enforcement quietly evaporates and nothing says so.
+*Failure:* a Copilot dry run asked *"AskUserQuestion doesn't seem installed, is that something
+we can include in the setup?"* — while the tool was named as **the** mechanism, the gate was
+unfollowable off Claude Code, which is a silent skip, not a loud failure (2026-08-19, `process/baseline-incident-history.md` §IP2).
 
 ### 4. Record the answer where the collector can see it.
 
@@ -272,7 +265,7 @@ States the collector recognises — anything else normalises to `UNRECOGNISED` a
 |---|---|
 | `UNRAISED` | never put to the user. **Blocks.** |
 | `RAISED` | asked, awaiting the answer. Does not block. |
-| `ANSWERED` | settled, answer recorded. |
+| `ANSWERED` | settled; requires a non-empty `answer`. |
 | `ASSUMED` | you took a position **and the user consented** to you taking it. Requires `consentBy` and `consentAt`. Without both it normalises to `UNRAISED` and blocks — a position the user never saw is not an assumption they made. |
 | `MOOT` | descoped. Genuinely dead, not quietly dropped. |
 | `UNRECOGNISED` | an unparseable status. **Blocks**, on purpose. |
@@ -285,14 +278,9 @@ from `raisedAt` and the collector reads both.
 ## An answer that points at another document is a claim, not an answer
 
 The one form of answer that reads as settled and cannot be trusted: *"X already covers this."*
-Verbatim, from a real intake (2026-09-02, Q4 "documents not yet accounted for?"):
-
-> the `.pptx` is already inside `source/<track>/` and was already used as triage input by the
-> Group A–D triage pass (see `<track>-triage.md`) — nothing additional exists outside the folder.
-
-The triage never named the deck. Two months of downstream artifacts inherited the gap, because
-once Q4 read "answered" nothing had a reason to look again. The answer *cited a document*, which
-is exactly why it was believed.
+Failure: *"the `.pptx` … was already used as triage input by the Group A–D triage pass"* — the
+triage never named the deck, and two months of artifacts inherited the gap; the answer *cited a
+document*, which is exactly why it was believed (2026-09-02, `process/baseline-incident-history.md` §IP3; also `source-triage.md`).
 
 **Rule.** Before recording an answer of the form "X already handled Y": open X and find Y in it —
 `grep -il "<Y's name>" X`. Zero hits means the answer is "not yet accounted for", whatever the
diff --git a/skills/source-triage.md b/skills/source-triage.md
index 0fab3763..42555a37 100644
--- a/skills/source-triage.md
+++ b/skills/source-triage.md
@@ -31,15 +31,11 @@ the file), or a person's waiver (`bin/gate-check.sh <project> --waive source/<re
 un-inventoried. Added files re-enter through `init --refresh` — never through memory.
 
 > **A claim that another document already handled a file is a claim to verify, not an
-> answer.** Real incident, 2026-09-02, a VBA migration: intake Q4 ("documents not yet accounted
-> for?") was closed with *"the .pptx is already inside `source/` and was already used as triage
-> input by the Group A–D triage pass"*. The triage was derived from the `.cls` exports and never
-> named the deck; its 22 diagrams — the only place the workflow engine's X/M/E semantics were
-> written down — went unread for two months of BRDs, blueprint and build plan, and a `CONFIRMED`
-> architecture decision had to be reversed. The wrong answer *reads* right because it cites a
-> document. The right form is the ledger's: **name the artifact, and let the gate grep it.** A
-> text read of a deck is not the deck either — a 25-slide, 22-image container is consumed when
-> the disposition says `--pages 25 --media 22`, not when its title appears in a summary.
+> answer.** Failure: *"the .pptx … was already used as triage input"* closed an intake question;
+> the triage never named the deck, its 22 diagrams went unread for two months, and a `CONFIRMED`
+> architecture decision was reversed (2026-09-02, `process/baseline-incident-history.md` §ST1). The right form is the ledger's:
+> **name the artifact, and let the gate grep it.** A text read of a deck is not the deck — a
+> 25-slide, 22-image container is consumed when the disposition says `--pages 25 --media 22`.
 
 **Always stand up an extractor — reuse where one already covers this stack, build new otherwise.** Field finding: reading source without an extractor missed information even on small, cleanly structured apps — manual reading is not a substitute for the coverage an extractor gives you, it's a different (weaker) tool. The extractor *is* the coverage gate: it's what lets Step 3 below actually answer "is this reliable enough to trust," instead of relying on how thorough a manual read happened to be. There is no manual-only path anymore.
 
@@ -56,12 +52,10 @@ OpenAPI/GraphQL contract, or entity/field table definitions inside a spec docume
 extractable structure, each gets its own Coverage Matrix row in Step 3, and each gets its own
 verdict.
 
-Mixed corpora are where this goes wrong, and they are the normal case in presales. The folder
-*reads* like requirements, so the whole thing is sent down the document path (`kb-generation.md`,
-Path B) and comes back as prose — including the entities that were sitting in the schema, which
-then get re-derived by hand three stages later. Prose is the right reading method for prose and
-the wrong one for structure. Choosing per artifact is this step's job; routing a whole corpus by
-how it looks at a glance is the failure it exists to prevent.
+Mixed corpora — the normal case in presales — are where this goes wrong: the folder *reads*
+like requirements, all of it goes down Path B, and the schema's entities are re-derived by hand
+three stages later (anti-patterns below). Prose is the right reading method for prose and the
+wrong one for structure.
 
 **This does not reopen the two-way call.** Path B is not "read the code by hand" — it is the
 correct method for genuine prose. For every *extractable structure* the answer is still
@@ -83,21 +77,9 @@ file" was never the manual-only path it forbids — that rule is about *structur
 exports), where a human skim demonstrably drops the tail. Nothing here lets a codebase, a schema
 or a data export past without an extractor.
 
-**Field evidence, 2026-09-07** — a no-code app replacement whose corpus was one data export
-(`.ods`), one 3.5 MB reverse-engineering spec (`.html`) and one workflow inventory (`.md`):
-
-- The **export parser corrected the documents written about it**: 53 stored columns against
-  128–175 documented (~120 are computed in the platform — neither attributes to model nor data to
-  migrate), four different spellings of one foreign key across four sheets, 15 sheets where the
-  spec documented 17, plus per-sheet volumes. No reading of any document produces one of those.
-- A **regex classifier over the spec's prose scored ~50% precision and ~50% recall** against a
-  user-confirmed sample, and was deleted the same day. It read the spec's "what the recording
-  covered" bullets as requirements, truncated sentences at inline HTML tags, and matched none of
-  the negative-form statements ("there is no role model", "no reminders, no escalation") that
-  carried some of the sharpest requirements in the document. The same agent's plain read of the
-  same file, at intake, was better in one pass.
-- The user's question is the rule in one line: *"do we need an extractor for html & md files?
-  Can't we just analyse and conclude what it should be? But when it's ppt and images better yes?"*
+**Field evidence (2026-09-07, `process/baseline-incident-history.md` §ST3):** the export parser corrected the spec written about
+it (53 stored columns against 128–175 documented); a regex classifier over the spec's prose scored
+~50% precision and recall and was deleted the same day — the agent's plain read was better.
 
 **Large text-native files still need a denominator.** A 3.5 MB HTML spec is legible but not
 readable in one pass, so the parser that takes its tables should also emit its **section list**.
@@ -123,18 +105,9 @@ For a **requirements-driven** project the two are not alternatives and the seque
 So: **document discovery is unconditional; extractors are conditional on there being structure;
 `N/A` is a finding about the folder, never a property of the entry mode.**
 
-**Why this is spelled out (2026-09-07).** `conversion-runbook.md`'s Stage-0 applicability table
-said the extraction call was **`N/A` for requirements-driven**, flatly — while this skill and the
-shipped `triage.md` header said `N/A` only where the corpus holds no extractable structure, "on
-evidence, never on the entry-mode label". The runbook is the file every session is required to
-read first, so the unconditional version was the one that got followed. On the project that
-surfaced it — requirements-driven, corpus of one spec, one workflow inventory and **one platform
-data export** — following the runbook literally would have marked extraction `N/A` and left the
-export unparsed. That parser went on to correct the very documents written about the app: 53
-stored columns against 128–175 documented, four spellings of one foreign key across four sheets,
-15 sheets where the spec said 17. Same shape as the `toolkit-guide.html` first-touch incident in
-`CLAUDE.md`: a rule stated conditionally in its owning file and unconditionally in the front
-door, where the front door wins. The runbook now defers here.
+**This skill owns the rule; the runbook defers here.** Failure: the runbook once said `N/A` for
+requirements-driven flatly, and following it would have left a data export unparsed — the parser
+that later corrected the spec (`process/baseline-incident-history.md` §ST4).
 
 | Signal | Lean toward |
 |---|---|

From 76075d8a08d9daf243a7ec03aca5e39373a44de1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 14:44:55 +0000
Subject: [PATCH 3/6] =?UTF-8?q?fix(trim):=20review=20follow-ups=20?=
 =?UTF-8?q?=E2=80=94=20dispatch=20obligation=20pointer,=20stale=20"below",?=
 =?UTF-8?q?=20ST1=20id?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Independent review of #315: obligations.tsv still pointed at agent-roles.md for
step 8a, which moved to agents/README.md; agent-roles.md said the example bodies
are "below"; the history header cited a non-existent section id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 bin/lib/obligations.tsv              | 5 +++--
 process/baseline-incident-history.md | 2 +-
 skills/agent-roles.md                | 4 +++-
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/bin/lib/obligations.tsv b/bin/lib/obligations.tsv
index 3bbb40c8..3c912083 100644
--- a/bin/lib/obligations.tsv
+++ b/bin/lib/obligations.tsv
@@ -137,8 +137,9 @@ fidelity	mdl	module	names	docs/PAGE-FIDELITY.tsv	no	yes	5	skills/ui-loop.md
 # module's own dispatch history. It is owed by mdl because mdl-agent is the one that knows, at
 # the moment of writing, whether it is the one writing.
 #
-# Column 9 names skills/agent-roles.md, not agents/mdl-agent.md: agent-roles.md's "Workflow"
-# step 8a is what actually specifies the log line, its path and format, and the discharge rule
+# Column 9 names skills/agent-roles.md, not agents/mdl-agent.md: the mdl-agent "Workflow" step 8a
+# (its full text now lives in agents/README.md, pointed to from agent-roles.md) specifies the log
+# line, its path and format, and the discharge rule
 # ("owes no denominator, just the line") — that is the governing text this column exists to
 # point at. The agent stub is the performer named in column 2 (mdl); it is not itself a skill
 # and holds no verdict of its own to point to (review of PR #99, 2026-09).
diff --git a/process/baseline-incident-history.md b/process/baseline-incident-history.md
index 9a3fe133..c863ea2d 100644
--- a/process/baseline-incident-history.md
+++ b/process/baseline-incident-history.md
@@ -7,7 +7,7 @@ moved verbatim so the evidence survives while the baseline stays inside the
 `bin/render-routing.sh --check` word budget (CLAUDE.md skill-authoring rule 6, "write for the
 trigger, then stop").
 
-Each section id (`R1`, `AR2`, …) is what the pointer in the skill cites. The section text is
+Each section id (`R1`, `ST1`, …) is what the pointer in the skill cites. The section text is
 the original wording, unedited — when a rule's justification is challenged, cite from here.
 Nothing in this file is a rule on its own; the rule lives in the skill that points here.
 
diff --git a/skills/agent-roles.md b/skills/agent-roles.md
index d9aca394..ba9c2e2a 100644
--- a/skills/agent-roles.md
+++ b/skills/agent-roles.md
@@ -14,7 +14,9 @@
 - You're asked to "set up agents for this project" or "create dev-process agents" on a fresh repo.
 - An existing project's agents feel ad hoc or over-permissioned (e.g. one agent can both write MDL and run `mxcli exec`).
 
-**This is a generation guide, not a copy-paste template.** The example bodies below are illustrative shapes — read the target project's own CLAUDE.md and skills first, then write agent files that match *that* project's actual commands, paths, and tooling. A gate-agent pointed at the wrong `.mpr` filename or a stale compile-gate command silently verifies nothing.
+**This is a generation guide, not a copy-paste template.** The example bodies (in `agents/README.md`) are illustrative shapes — read the target project's own CLAUDE.md and skills first, then write agent files that match *that* project's actual commands, paths, and tooling. A gate-agent pointed at the wrong `.mpr` filename or a stale compile-gate command silently verifies nothing.
+
+**Discharging the `dispatch` obligation:** the mdl-agent logs every dispatch per Workflow step 8a — the log line, path (`.claude/loop/dispatch/<Module>/scripts.tsv`) and format are in `agents/README.md` step 8a; one line per dispatch, no denominator owed.
 
 **Mechanical scaffolding exists:** `bin/init-agents.sh <session-root> [p|build|all]` copies stub versions of all **six** agents (from the toolkit's `agents/` folder) into the project's `.claude/agents/` — `p` for the Stage-P pair (ba/architect), `build` for the Stage-5 quartet (mdl/gate/test/**review**). The stubs are safe by construction: each refuses to run while `{{PLACEHOLDER}}`s remain, so "downloaded but never configured" fails loudly instead of verifying nothing. Your job after scaffolding is Steps 1–4 below: fill every placeholder from the *actual* project, including the **Domain context** block.
 

From cd67a7c33c391cb69e1c8bed24305e2641adcf6f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 14:59:35 +0000
Subject: [PATCH 4/6] chore(trim): correct the measured word counts in the
 CHANGELOG line

Measured with LC_ALL=C on the branch after master (#313) was merged in:
79,997 -> 76,259 (-3,738); the old line used pre-#313 figures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bad77127..507ad9ed 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
 
-- chore(context): **baseline word budget freed — 79,735 → 75,963 words (−3,772) without dropping a rule.** The always-on tier sat 265 words under its 80,000 cap, so three open PRs could not all merge. Long incident narratives in `conversion-runbook.md`, `source-triage.md` and `interview-protocol.md` became one-line failure examples pointing at new on-demand `process/baseline-incident-history.md`, where the original text is kept verbatim per section (R1–R20, AR1, ST1–ST4, IP1–IP3); the runbook's copy of the open-questions status table now defers to `interview-protocol.md` §4; `agent-roles.md`'s six template shapes (setup-only, ~2,300 words) moved verbatim to `agents/README.md`, which the installers never copy (explicit `MXTK_AGENTS` list). Every STOP, rule, denominator and gate cell stays in place; files touched by open PRs were left alone. — MendixMau
+- chore(context): **baseline word budget freed — 79,997 → 76,259 words (−3,738) without dropping a rule.** The always-on tier sat 3 words under its 80,000 cap, so three open PRs could not all merge. Long incident narratives in `conversion-runbook.md`, `source-triage.md` and `interview-protocol.md` became one-line failure examples pointing at new on-demand `process/baseline-incident-history.md`, where the original text is kept verbatim per section (R1–R20, AR1, ST1–ST4, IP1–IP3); the runbook's copy of the open-questions status table now defers to `interview-protocol.md` §4; `agent-roles.md`'s six template shapes (setup-only, ~2,300 words) moved verbatim to `agents/README.md`, which the installers never copy (explicit `MXTK_AGENTS` list). Every STOP, rule, denominator and gate cell stays in place; files touched by open PRs were left alone. — MendixMau
 - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
 - learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
 - fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo

From 56d5530a5d6ddc185e0c4614d8431d4711d038fe Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:13:31 +0000
Subject: [PATCH 5/6] revert(detection-gaps): restore the intro tightened to
 fit the budget

A feature PR does not squeeze other text to make room (the rule in #316).
Room comes from the baseline trim in #315, merged next. This branch's own
row stays trimmed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 skills/learned-detection-gaps.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/skills/learned-detection-gaps.md b/skills/learned-detection-gaps.md
index a4055417..18706b8c 100644
--- a/skills/learned-detection-gaps.md
+++ b/skills/learned-detection-gaps.md
@@ -3,10 +3,12 @@
 **Applies to:** any mxcli project
 **Purpose:** the cross-project register of MDL constructs that pass one or more verification
 rungs and still fail later — with, for each, the **first oracle that actually catches it**.
-Use it before trusting a green result, and when a runtime symptom appears over a green model.
+Use it two ways: before trusting a green result ("what is this rung known to miss?"), and
+when a runtime symptom appears over a fully green model ("which known gap looks like this?").
 
-Every row was found in the field, most in more than one project. The pattern matters more
-than the bugs: **the rungs form a ladder, and a green result certifies only what its rung sees.**
+Every row here was found in the field, most of them independently in more than one project.
+The point is not the individual bugs (each has its own entry) — it is the pattern: **the
+verification rungs form a ladder, and a green result only certifies what that rung can see.**
 
 ## The ladder
 

From d7804c5706eca95abe9fc9a9cc0f067d6ef29baa Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:46:49 +0000
Subject: [PATCH 6/6] fix(doctor, sync-project): property-set check errors get
 their own exit code; sync announces its bound
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Confirmation review of #314:
1. Sync captures doctor's output, so it now prints "checking property
   sets (read-only, up to Ns)…" first. Sync uses its own shorter default:
   MXTK_PROPSETS_TIMEOUT=${MXTK_PROPSETS_TIMEOUT:-120}.
2. A check that could not run is exit 4 now, not exit 1. That covers an
   error, unclassified output, a crashed `fix --help` probe or no Mendix
   version. Exit 1 is only NEEDS/FAILED rows. On exit 4, sync prints a
   neutral "could not check property sets: <reason>" line, with no
   warning and no --fix-property-sets advice, because the repair would
   fail the same way.
3. When the probe crashed, --quick says "could not probe", not that the
   mxcli "predates" the command.
4. The fixture stub's slow state now execs sleep, so a timeout kills the
   process itself and leaves no child behind.

test-property-sets.sh: 61 passed. New cases: exit 4 for errors, --quick
on a crashed probe, sync's bound announcement, and sync's neutral line
on exit 4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                      |  2 +-
 bin/doctor.sh                     | 21 ++++++++++++---------
 bin/sync-project.sh               | 17 ++++++++++++-----
 skills/platform-link.md           |  2 +-
 tests/wave2/test-property-sets.sh | 21 +++++++++++++++++----
 5 files changed, 43 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6f720d0..69b53a04 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
 
-- feat(doctor, sync-project): **`mxcli fix property-sets` is wired into the upgrade path, report first: the Studio Pro merge break no gate could see.** mxcli up to v0.25 wrote units without Studio Pro's full property set. `mx check`, the build and the runtime stay green, and Studio Pro's merge/diff throws ("Objects with ID … do not have the same properties") once it has saved such a document. New `bin/doctor.sh --property-sets <project>` runs the read-only `--dry-run` and records the result with the mxcli version in `.claude/.property-sets-receipt` (machine-local, gitignored). It exits 0 clean, 1 needs repair or could not classify (never green by absence), 2 not run, 3 for an mxcli before v0.26.0. `sync-project.sh` runs it with `--if-stale`, which skips only a recorded clean or unsupported result for the installed mxcli (errors and timeouts are never recorded; the dry-run is bounded by `MXTK_PROPSETS_TIMEOUT`, default 300 s), and `doctor --quick` (which exec.sh runs when the mxcli version changes) warns while it is owed. The repair is `bin/doctor.sh --fix-property-sets <project>`, which runs `mxcli fix property-sets` only through `exec.sh --patch` (snapshot, mxbuild gate, restore). It refuses on an exec.sh without `--patch`. Support is probed from `mxcli fix --help`, because `mxcli fix property-sets --help` exits 0 on v0.24/v0.25 too, printing the parent's help. New row in `learned-detection-gaps.md`; `platform-link.md` gains "Before a Team Server merge", covering `fix property-sets`, `fix hashes` and `git note`. Golden input is captured from the v0.24.0/v0.25.0/v0.26.0 release binaries. The clean/NEEDS/FAILED reports follow mxcli's source format strings, because no model was run. `tests/wave2/test-property-sets.sh` (58 cases). Field run still owed. `fix hashes` as an `exec.sh --patch` post-step is pending (Refs #295) — jopterhorst
+- feat(doctor, sync-project): **`mxcli fix property-sets` is wired into the upgrade path, report first: the Studio Pro merge break no gate could see.** mxcli up to v0.25 wrote units without Studio Pro's full property set. `mx check`, the build and the runtime stay green, and Studio Pro's merge/diff throws ("Objects with ID … do not have the same properties") once it has saved such a document. New `bin/doctor.sh --property-sets <project>` runs the read-only `--dry-run` and records the result with the mxcli version in `.claude/.property-sets-receipt` (machine-local, gitignored). It exits 0 clean, 1 needs repair, 2 not run, 3 for an mxcli before v0.26.0, and 4 when the check itself failed or its output could not be classified (never green by absence; a repair would not help). `sync-project.sh` runs it with `--if-stale`, which skips only a recorded clean or unsupported result for the installed mxcli (errors and timeouts are never recorded; the dry-run is bounded by `MXTK_PROPSETS_TIMEOUT`, default 300 s, 120 s under sync, which announces the bound first), and `doctor --quick` (which exec.sh runs when the mxcli version changes) warns while it is owed. The repair is `bin/doctor.sh --fix-property-sets <project>`, which runs `mxcli fix property-sets` only through `exec.sh --patch` (snapshot, mxbuild gate, restore). It refuses on an exec.sh without `--patch`. Support is probed from `mxcli fix --help`, because `mxcli fix property-sets --help` exits 0 on v0.24/v0.25 too, printing the parent's help. New row in `learned-detection-gaps.md`; `platform-link.md` gains "Before a Team Server merge", covering `fix property-sets`, `fix hashes` and `git note`. Golden input is captured from the v0.24.0/v0.25.0/v0.26.0 release binaries. The clean/NEEDS/FAILED reports follow mxcli's source format strings, because no model was run. `tests/wave2/test-property-sets.sh` (61 cases). Field run still owed. `fix hashes` as an `exec.sh --patch` post-step is pending (Refs #295) — jopterhorst
 - fix(sync-project): **sync names a `bin/model-stamp.sh` that predates the worktree hook blind-spot fix.** `known_fix_note` gains the `model-stamp.sh` arm from the #236 patch, keyed on `GIT_WORK_TREE`, which the fixed script pins. The arm says to upgrade `model-stamp.sh` and `_common.sh` together. `tests/wave2/test-model-stamp.sh` T9 adds the unstaged worktree `commit -a` and `commit -- app` cases. The silent rc 1 half of #236 landed earlier. The new note is asserted by `test-property-sets.sh` P10, which fails on master. — MendixMau (card-disbursement requirements-driven build, field task 21)
 - chore(context): **baseline word budget freed — 79,997 → 76,259 words (−3,738) without dropping a rule.** The always-on tier sat 3 words under its 80,000 cap, so three open PRs could not all merge. Long incident narratives in `conversion-runbook.md`, `source-triage.md` and `interview-protocol.md` became one-line failure examples pointing at new on-demand `process/baseline-incident-history.md`, where the original text is kept verbatim per section (R1–R20, AR1, ST1–ST4, IP1–IP3); the runbook's copy of the open-questions status table now defers to `interview-protocol.md` §4; `agent-roles.md`'s six template shapes (setup-only, ~2,300 words) moved verbatim to `agents/README.md`, which the installers never copy (explicit `MXTK_AGENTS` list). Every STOP, rule, denominator and gate cell stays in place; files touched by open PRs were left alone. — MendixMau
 - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
diff --git a/bin/doctor.sh b/bin/doctor.sh
index 9151a9e6..703c2b3d 100755
--- a/bin/doctor.sh
+++ b/bin/doctor.sh
@@ -47,8 +47,10 @@
 #                                           # and records the result. Add --if-stale to skip
 #                                           # the run when it already ran for this mxcli
 #                                           # version (sync-project.sh does). Exit 0 clean,
-#                                           # 1 units need repair or the run failed, 2 not run,
-#                                           # 3 this mxcli predates the command (v0.26.0).
+#                                           # 1 units need repair (NEEDS/FAILED rows), 2 not run
+#                                           # (incl. timeout), 3 this mxcli predates the command
+#                                           # (v0.26.0), 4 could not check (error, unclassified
+#                                           # output, a crashed probe) — a repair would not help.
 #   bin/doctor.sh --fix-property-sets <dir> # the same check, then the repair — and only
 #                                           # through bin/exec.sh --patch (snapshot, mxbuild
 #                                           # gate, restore on failure). See "Property sets".
@@ -330,7 +332,7 @@ ps_apply() {
   ps_check
 }
 ps_exit_code() {
-  case "$PS_RESULT" in clean) echo 0 ;; not-run) echo 2 ;; unsupported) echo 3 ;; *) echo 1 ;; esac
+  case "$PS_RESULT" in clean) echo 0 ;; not-run) echo 2 ;; unsupported) echo 3 ;; needs|failed) echo 1 ;; *) echo 4 ;; esac
 }
 
 # --property-sets / --fix-property-sets: only this check, then exit. Stands alone so
@@ -1191,12 +1193,13 @@ if [ -n "$PROJECT_DIR" ]; then
     elif [ -n "${MPR:-}" ] && [ -n "${PMXCLI_PROBE:-}" ]; then
       PS_VER="$(ps_version "$PMXCLI_PROBE")"
       if ps_stale; then
-        if ps_supported "$PMXCLI_PROBE"; then
-          warn "property sets not checked for this mxcli (${PS_VER:-?}) — Studio Pro merge/diff can throw on units an older mxcli wrote"
-          note "read-only check: bin/doctor.sh --property-sets $PROJECT_DIR"
-        else
-          note "${PS_VER:-this mxcli} predates 'mxcli fix property-sets' (v0.26.0) — upgrade before a Team Server merge"
-        fi
+        _psq_rc=0; ps_supported "$PMXCLI_PROBE" || _psq_rc=$?
+        case "$_psq_rc" in
+          0) warn "property sets not checked for this mxcli (${PS_VER:-?}) — Studio Pro merge/diff can throw on units an older mxcli wrote"
+             note "read-only check: bin/doctor.sh --property-sets $PROJECT_DIR" ;;
+          1) note "${PS_VER:-this mxcli} predates 'mxcli fix property-sets' (v0.26.0) — upgrade before a Team Server merge" ;;
+          *) warn "property sets: could not probe this mxcli for 'fix property-sets' ('mxcli fix --help' failed)" ;;
+        esac
       else
         _psq="$(sed -n 1p "$(ps_receipt)")"
         case "$_psq" in
diff --git a/bin/sync-project.sh b/bin/sync-project.sh
index 296bef70..37b68966 100755
--- a/bin/sync-project.sh
+++ b/bin/sync-project.sh
@@ -1464,10 +1464,14 @@ if [ "$WIRED" -eq 1 ] && [ -x "$SCRIPT_DIR/doctor.sh" ] \
     echo "Would run: bin/doctor.sh --property-sets --if-stale (read-only model check; skipped when it already ran for this mxcli)"
   else
     _ps_rc=0
-    _ps_out="$("$SCRIPT_DIR/doctor.sh" --property-sets --if-stale "$PROJECT_DIR" 2>&1)" || _ps_rc=$?
-    # rc 3 (an mxcli before v0.26 cannot check) is informational here, not a sync warning, so
-    # doctor's own WARN line for it is relabelled rather than shown as one.
-    if [ "$_ps_rc" -eq 3 ]; then
+    # Sync's own, shorter bound (doctor's default is 300 s): the output is captured, so say
+    # up front how long this may sit quiet.
+    _ps_t="${MXTK_PROPSETS_TIMEOUT:-120}"
+    echo "   checking property sets (read-only, up to ${_ps_t}s)…"
+    _ps_out="$(MXTK_PROPSETS_TIMEOUT="$_ps_t" "$SCRIPT_DIR/doctor.sh" --property-sets --if-stale "$PROJECT_DIR" 2>&1)" || _ps_rc=$?
+    # rc 3 (an mxcli before v0.26 cannot check) and rc 4 (the check itself failed) are not
+    # findings about the model, so doctor's WARN line for them is relabelled, not shown as one.
+    if [ "$_ps_rc" -eq 3 ] || [ "$_ps_rc" -eq 4 ]; then
       printf '%s\n' "$_ps_out" | grep -v '^[[:space:]]*$' | sed -e 's/^  WARN  /  info  /' -e 's/^/   /'
     else
       printf '%s\n' "$_ps_out" | grep -v '^[[:space:]]*$' | sed 's/^/   /'
@@ -1475,8 +1479,11 @@ if [ "$WIRED" -eq 1 ] && [ -x "$SCRIPT_DIR/doctor.sh" ] \
     case "$_ps_rc" in
       0|2) ;;
       3) echo "   (the project's mxcli predates 'fix property-sets', v0.26.0 — upgrade it before a Team Server merge)" ;;
-      *) warn "property sets: Studio Pro's merge/diff can throw on this model (see above). Repair, gated:" \
+      4) _ps_why="$(printf '%s\n' "$_ps_out" | sed -n 's/^  WARN  property sets: //p' | head -1)"
+         echo "   could not check property sets: ${_ps_why:-see above} — not recorded; the next sync re-checks" ;;
+      1) warn "property sets: Studio Pro's merge/diff can throw on this model (see above). Repair, gated:" \
               "bin/doctor.sh --fix-property-sets '$PROJECT_DIR'" ;;
+      *) echo "   property-set check exited $_ps_rc — see above" ;;
     esac
   fi
 fi
diff --git a/skills/platform-link.md b/skills/platform-link.md
index 50aff144..52039d05 100644
--- a/skills/platform-link.md
+++ b/skills/platform-link.md
@@ -473,7 +473,7 @@ so a project upgraded mid-flight still carries the old ones until the repair run
 for the installed mxcli. After that it runs again only when mxcli changes. Errors and timeouts
 are never recorded, so the next run re-checks. `doctor --quick`, which exec.sh runs when the mxcli
 version changes, warns while the check is owed. The check reads every unit, so it is bounded by
-`MXTK_PROPSETS_TIMEOUT` (default 300 s), and a timeout reports NOT RUN. A unit the
+`MXTK_PROPSETS_TIMEOUT` (default 300 s, 120 s under sync), and a timeout reports NOT RUN. A unit the
 check reports `FAILED` has a value in a key the project's Mendix version does not declare. mxcli
 leaves such units alone, and its exit 1 makes `exec.sh --patch` roll the whole repair back, so
 resolve those units first. An mxcli older than v0.26.0 cannot run this check: upgrade it first.
diff --git a/tests/wave2/test-property-sets.sh b/tests/wave2/test-property-sets.sh
index d240c9e4..21206b4f 100755
--- a/tests/wave2/test-property-sets.sh
+++ b/tests/wave2/test-property-sets.sh
@@ -79,7 +79,7 @@ case "${1:-}" in
                   echo "1 unit(s) could not be normalized and were left as they are."; exit 1 ;;
           notfound) cat "$F/dry-run-not-found-v0.26.0.txt"; exit 1 ;;
           noversion) echo "$b has no readable Mendix version; nothing is normalized without one."; exit 0 ;;
-          slow) sleep 6; echo "Checked 3 unit(s) in $b against the Mendix 11.12.1 property sets."; exit 0 ;;
+          slow) exec sleep 6; echo "Checked 3 unit(s) in $b against the Mendix 11.12.1 property sets."; exit 0 ;;
         esac ;;
     esac ;;
 esac
@@ -131,7 +131,8 @@ echo "== P4 failed / error / no version — never clean =="
 for st in failed notfound noversion; do
   P="$(mkproj st-$st)"; echo "$st" > "$P/.stub-state"
   OUT="$("$DOCTOR" --property-sets "$P" 2>&1)"; RC=$?
-  [ "$RC" -eq 1 ] && ! printf '%s' "$OUT" | grep -q "ok    property sets" && ok "$st: exit 1, no ok line" || bad "$st: rc=$RC" "$OUT"
+  want=4; [ "$st" = failed ] && want=1
+  [ "$RC" -eq "$want" ] && ! printf '%s' "$OUT" | grep -q "ok    property sets" && ok "$st: exit $want, no ok line" || bad "$st: rc=$RC (want $want)" "$OUT"
 done
 printf '%s' "$OUT" | grep -q "no Mendix version" && ok "noversion: says nothing was checked" || bad "noversion wording" "$OUT"
 for st in notfound noversion; do
@@ -141,8 +142,11 @@ P="$WORK/st-notfound"; "$DOCTOR" --property-sets --if-stale "$P" >/dev/null 2>&1
 [ "$(grep -c -- '--dry-run' "$P/.stub-log")" -eq 2 ] && ok "notfound: --if-stale re-checks after an error" || bad "notfound: --if-stale skipped after an error"
 P="$(mkproj helpfail)"; touch "$P/.stub-helpfail"
 OUT="$("$DOCTOR" --property-sets "$P" 2>&1)"; RC=$?
-[ "$RC" -eq 1 ] && printf '%s' "$OUT" | grep -q "support is unknown" && [ ! -f "$P/.claude/.property-sets-receipt" ] \
-  && ok "failed 'fix --help' probe: error (exit 1), not unsupported, not recorded" || bad "helpfail rc=$RC" "$OUT"
+[ "$RC" -eq 4 ] && printf '%s' "$OUT" | grep -q "support is unknown" && [ ! -f "$P/.claude/.property-sets-receipt" ] \
+  && ok "failed 'fix --help' probe: error (exit 4), not unsupported, not recorded" || bad "helpfail rc=$RC" "$OUT"
+OUT="$("$DOCTOR" --quick "$P" 2>&1)"
+printf '%s' "$OUT" | grep -q "could not probe this mxcli" && ! printf '%s' "$OUT" | grep -q "predates 'mxcli fix property-sets'" \
+  && ok "--quick, crashed probe: says 'could not probe', not 'predates'" || bad "quick helpfail" "$(printf '%s' "$OUT" | grep -i property)"
 
 echo "== P5 --if-stale: once per mxcli version =="
 P="$(mkproj stale)"; echo clean > "$P/.stub-state"
@@ -247,6 +251,15 @@ psl="$(printf '%s\n' "$OUT" | grep -i 'property' )"
 printf '%s' "$psl" | grep -q "info  property sets: .*arrived in v0.26.0" && ! printf '%s' "$psl" | grep -q "WARN  \|⚠️" \
   && ok "sync, mxcli < v0.26: informational line, no WARN, no sync warning" || bad "sync old mxcli" "$psl"
 
+printf '%s' "$OUT" | grep -q "checking property sets (read-only, up to 120s)" && ok "sync announces the check and its 120 s bound" || bad "no announcement" "$(printf '%s' "$OUT" | grep -i property)"
+S4="$WORK/syncerr"; mkdir -p "$S4"; : > "$S4/App.mpr"
+MXTK_NO_GUIDE=1 "$TK/bin/init-project.sh" "$S4" >/dev/null 2>&1
+mkstub "$S4"; echo notfound > "$S4/.stub-state"
+OUT="$("$SYNC" "$S4" 2>&1)"
+psl="$(printf '%s\n' "$OUT" | grep -i 'property')"
+printf '%s' "$psl" | grep -q "could not check property sets: could not classify" && ! printf '%s' "$psl" | grep -q "fix-property-sets\|⚠️\|WARN  " \
+  && ok "sync, check errored (exit 4): neutral line, no repair advice, no warning" || bad "sync error case" "$psl"
+
 echo "== P10 (#236) sync names a pre-fix bin/model-stamp.sh =="
 grep -v 'GIT_WORK_TREE' "$TK/project-bin/model-stamp.sh" > "$S/bin/model-stamp.sh"; chmod +x "$S/bin/model-stamp.sh"
 OUT="$("$SYNC" "$S" --dry-run --no-refresh 2>&1)"