From 4a60e144451e20ea4f1eb55020135d59f254e89d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 10:08:05 +0000
Subject: [PATCH 1/9] fix(lint-gate): reverted-to-stock rules stop the run as
 BLIND, not a rise (#264); BUG-156 + preflight row 28 (#263)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#264: `mxcli init` re-seeds .claude/lint-rules/ and the toolkit rules lose their header.
lint-gate.sh never read .claude/.mxtk-lint-receipt, so the re-seed showed up as a rise on the
next exec (CONV010 26 -> 169 on a pages-only script), or sat for days while the baseline
absorbed stock counts.

- project-bin/lint-gate.sh: before linting, each rule in the receipt is md5'd; a mismatch with
  the header gone (or a missing file) is named, the remedy `<toolkit>/bin/sync-project.sh
  <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock`.
  lint-last.json gets verdict BLIND-RULES-REVERTED and no total (no stale total for
  metrics-ledger). --update-baseline is refused over reverted rules. A headered edit is left to
  the installer's LOCALLY MODIFIED report; no receipt means no check;
  LINT_RULES_REVERTED_OK=1 lints anyway, with the warning.
- project-bin/exec.sh: run_lint_gate maps that output to LINT_RC 3 / "LINT BLIND: rules
  reverted to stock (<files>) — run sync-project.sh; delta not attributable".
- Guard rules: the receipt is the installer's evidence, not lint-gate's own stamp (rule 6);
  the remedy (sync-project.sh / the installer) is never blocked and clears it — fixture T6
  (rule 7).
- tests/wave2/test-lint-receipt-revert.sh: golden receipt from the real installer run into a
  scratch project; 23/23 here, 11 fail with master's lint-gate.sh.

#263 (learned-rule half): BUG-156 in bug-logs/mxcli-bugs.md (bin/bug-lookup.sh BUG-156 and
"free room" find it) and STOP row 28 in skills/learned-mdl-preflight.md, quoting the issue's
exec error verbatim. Upstream draft prepared, not filed.

Field run: the receipt/installer half was field-checked by the maintainer on a copy of a
v0.25.0 project (#264 comment: installer restores conv010/data_change, md5s then match the
toolkit). lint-gate's new check has not yet run on a live project — fixture only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                            |   2 +
 agents/gate-agent.md                    |   4 +-
 bug-logs/mxcli-bugs.md                  |  27 ++++++
 project-bin/exec.sh                     |  11 ++-
 project-bin/lint-gate.sh                |  76 +++++++++++++++-
 skills/learned-mdl-preflight.md         |   1 +
 skills/lint-that-actually-runs.md       |   3 +
 tests/wave2/test-lint-receipt-revert.sh | 114 ++++++++++++++++++++++++
 8 files changed, 234 insertions(+), 4 deletions(-)
 create mode 100755 tests/wave2/test-lint-receipt-revert.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a28740e2..d5262529 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
 
+- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a rule whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or that is missing, is named, the remedy `bin/sync-project.sh <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer: 23/23 here, 11 fail on master's lint-gate. — AlvinnYeo
+- learn(learned-mdl-preflight): **a microflow change near a `return` in a dense flow is planned as drop + create after `show access`; `check -p --references` does not run exec's free-room test** ([#263](https://github.com/MendixMau/mxcli-project-toolkit/issues/263)). STOP row 28 and BUG-156: on v0.25.0 `check` printed "no flow change exec would refuse" and exec then refused "there is no free room for the fragment". Upstream issue drafted, not filed. — AlvinnYeo
 - 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
 - fix(journeys): **the journey runner preflights the suite: a refused admin credential aborts it before the first journey, missing mock env vars are one SETUP line, and journeys can declare `requires` / `leaves` / `consumes` so order is computed and an unmet precondition is named** ([#286](https://github.com/MendixMau/mxcli-project-toolkit/issues/286), #287 item 1, [#278](https://github.com/MendixMau/mxcli-project-toolkit/issues/278) first half). Field run 2026-10-12, 14 journeys: the runner's literal admin default (`M2EE_ADMIN_PASS || '1'`) was not the app's, every data rung got HTTP 403 and read INVALID, and the suite walked all 14 anyway (first pass 305/339, 2 of 14 green, discarded). Two unset mock vars made 3 journeys INVALID one at a time, and an undeclared order dependency made 6 of 14 INVALID. `tests/e2e/config.js` now resolves the token from `M2EE_ADMIN_PASS` → this app's `.mxcli/run-local.json` (matched on appPort) → `.docker/.env` → a labelled guess, and records the source, never the value. `journey-runner.js` refuses to start with `TEST_PASS` unset, before any login (#278: a run without the env step submitted the config default, then the admin fallback, and locked two demo accounts for ~5 min each; `ALLOW_CONFIG_CREDENTIALS=1` when the default is real). It then probes once through the same `mxcli oql --direct` before opening the browser: 401/403 or unreachable → exit 2 with the source and the remedy (`ALLOW_NO_DATA_RUNG=1` overrides), the live `System.Session` count is reported, and `JOURNEY_SESSION_CAP` refuses a run at the cap. Logout now runs on crash and SIGINT/SIGTERM too, and the findings slot is overwritten on an abort. Journeys without the new fields run in file order exactly as before. `journey-proof.md` / `journey-examples.md` / `learned-db-assertions.md` updated. Fixture `tests/wave2/test-journey-preflight.sh` (54 cases at first commit, including three end-to-end runs of the real runner on a stub mxcli; golden = mxcli v0.26.0's own message and `.docker/.env` template strings read from the binary, plus the captured run-local handshake; 1/2 against master's runner). Second commit, from the skills review: `"resetsData": true` tags a journey that resets or reloads demo data, printed at start and refused under `--protect-state` (#279: one suite run between rehearsal and recording wiped an app's seeded state, and that app never appeared in the film). `"assertLanding": true` / `--assert-landing` records, right after login and before any click, whether any element draws an outline or a focused element draws a box-shadow (#281: ring on landing for 3 of 3 roles while 3 UX asserts stayed green). `journey-proof.md` adds a third rule as text only: a fix to a displayed fact asserts the old text is absent on every page in its `Displayed fact:` row (#283). Fixture now 65 cases; the in-page landing collector needs a browser and is not fixtured. Not yet run against a live app — MendixMau
 - learn(learned-mdl-cannot-express): **a widget for one role only is not writable in MDL; the action-button workaround and its three traps are now written down** ([#277](https://github.com/MendixMau/mxcli-project-toolkit/issues/277)). Grant `execute` on the button's microflow only to the roles that should see it, and Mendix will not render the button for the rest. Three traps from a 2026-10-12 20-task UX-fix run over three apps: a helper sentence naming the button cannot be gated the same way, an admin (or admin-fallback) session proves nothing, and terminal-state demo data hides the button for the wrong reason. The skill gives a per-role absence check with a denominator and a before/after journey step. Its routing row now triggers on "a widget for one role and not another". — MendixMau
diff --git a/agents/gate-agent.md b/agents/gate-agent.md
index 32fa7df8..cbdea4ff 100644
--- a/agents/gate-agent.md
+++ b/agents/gate-agent.md
@@ -104,7 +104,9 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
    the user's decision, made in chat; `--update-baseline` refuses a rise without `--reason`, a
    security-tier rise (SEC*, CONV006) also without `--approved-in-chat`, and logs each one to
    `.claude/lint-acceptances.tsv`. A row reading `LINT BLIND` is an instrument fault (a rule
-   inspected nothing), not a rise: name the rule and its configuration fix. If the row says
+   inspected nothing), not a rise: name the rule and its configuration fix. `LINT BLIND: rules
+   reverted to stock (…)` means `mxcli init` re-seeded the toolkit rules and lint did not run:
+   the fix is the toolkit's `bin/sync-project.sh`, never a re-baseline. If the row says
    `lint not installed`, say so as a finding: nothing has checked shape in this project.
 
 ## A clean result is not automatically a pass
diff --git a/bug-logs/mxcli-bugs.md b/bug-logs/mxcli-bugs.md
index 5bdcbc70..b81fe9fd 100644
--- a/bug-logs/mxcli-bugs.md
+++ b/bug-logs/mxcli-bugs.md
@@ -6029,6 +6029,33 @@ backend's mutator already handles it (the two lists drifted).
 **Not covered by the fix:** `set Content`/`ContentParams` on a dynamic text (parser-level),
 container `RenderMode`, button `RenderType` — all still need `replace`.
 
+## BUG-156: `check -p --references` passes a microflow change that exec then refuses for lack of free room — and says it checked
+
+**Severity:** Medium — loud refusal, nothing written (exec.sh restores the snapshot), but the pre-flight that should have caught it says the opposite, so the failure costs a full exec cycle
+**mxcli version:** v0.25.0 · **Mendix version:** 11.14.0 · **Not filed upstream** (draft prepared, issue #263)
+**Discovered:** 2026-10-11, a consuming project (macOS, toolkit `9dd9be4`), reported by an outside contributor
+**Reproducible:** seen once in the field; no minimal repro yet
+
+`./mxcli check script.mdl -p App.mpr --references` passed the script and printed "no flow change
+exec would refuse". `bin/exec.sh --patch` then refused it:
+
+```
+create or modify microflow Common.IVK_X: this change cannot be spliced into the stored flow ... insert before return $LiveResult: there is no free room for the fragment ... drawn over the ActionActivity at (2025, 200)
+```
+
+`check` does not run the splice / free-room test that exec runs, yet its message reads as if it had.
+Nothing inside ALTER gets round it: `check --help` has no layout or free-room option, `alter microflow`
+insert takes no `@position`, cannot move existing objects, and cannot replace a fragment that returns.
+
+**Workaround (field-used):** `drop microflow` + `create microflow` in the same script, so the flow is
+laid out fresh. Before dropping, `show access on microflow Mod.Name` — the field case had no grants;
+re-granting after a drop + create was not exercised. A dropped-and-restated microflow is also a
+whole-document restatement: `learned-mdl-preflight.md` row 21 (describe first, keep sibling edits)
+applies. The planning rule is row 28 there.
+
+**Upstream ask:** have `check -p` run the same splice/free-room test exec runs, or stop printing
+"no flow change exec would refuse" when it has not.
+
 ## BUG-DRAFT-loop-var-expression-typecheck: the expression type checker is skipped inside a `LOOP` body — the identical expression is caught on a parameter and missed on a loop variable (2026-09-15)
 
 > **FILED UPSTREAM 2026-09-15 — https://github.com/mendixlabs/mxcli/issues/1100**
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index b57430d9..37c9e812 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -738,7 +738,16 @@ run_lint_gate() {
                  | awk '{printf "%s %s ", $1, $6}')
        _blind=$(sed -n '/^!! A RULE COULD NOT READ/,/^$/p' "$_lo" \
                  | grep -oE '^ +[A-Z][A-Z0-9-]*[0-9]+:' | tr -d ' :' | sort -u | paste -sd, -)
-       if [ -z "$_rules" ] && grep -q '^PASS' "$_lo"; then
+       _reverted=$(sed -n '/^!! LINT RULES REVERTED TO STOCK/,/^$/p' "$_lo" \
+                    | grep -oE '^ +[A-Za-z0-9_.-]+\.star:' | tr -d ' :' | paste -sd, -)
+       if grep -q '^BLIND — lint rules reverted to stock' "$_lo"; then
+         # `mxcli init` re-seeded the toolkit rules (#264): lint-gate did not lint. Logging this
+         # as a rise blamed the next script for CONV010 26 -> 169 on flows it never touched.
+         LINT_RC=3
+         LINT_DETAIL="lint BLIND: rules reverted to stock (${_reverted:-see output}) — run sync-project.sh; delta not attributable"
+         echo "  ✗ lint: toolkit rules reverted to stock (${_reverted:-see output}) — not linted, not a rise"
+         sed -n '/^!! LINT RULES REVERTED TO STOCK/,/^BLIND/p' "$_lo" | head -16 | sed 's/^/    /'
+       elif [ -z "$_rules" ] && grep -q '^PASS' "$_lo"; then
          # lint-gate exits 1 for PASS-BLIND too. Logging that as "ROSE: see output" made a rule
          # that inspected nothing look like a rise with no rule named — 20 such rows in two
          # field apps whose CONV020 shipped unconfigured (#229). It is an instrument fault.
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index bac65a4c..ac88c496 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -18,7 +18,24 @@
 #       --approved-in-chat              # ALSO required when a security-tier rule rises
 #   bin/lint-gate.sh --full             # ignore the vendor exclusion (rarely useful)
 #
-# Exit codes: 0 clean or unchanged · 1 a rule increased · 2 could not run (or a refused update)
+# Exit codes: 0 clean or unchanged · 1 a rule increased, or BLIND (a rule inspected nothing,
+#             or the toolkit rules reverted to stock — see below) · 2 could not run (or a
+#             refused update)
+#
+# RULES REVERTED TO STOCK ARE BLIND, NOT A RISE (#264, 2026-10-13). `mxcli init` re-seeds
+# .claude/lint-rules/ and silently overwrites the toolkit's rules with stock ones. Two apps hit
+# it: CONV010 went 26 -> 169 and the next exec — a pages-only script — was logged as the rise;
+# in the other the re-seed sat uncommitted for five days and the baseline absorbed the noisier
+# counts. bin/lib/install-lint-rules.sh already writes .claude/.mxtk-lint-receipt (md5 of each
+# rule AS INSTALLED; it survives `mxcli init`), so before linting this script reads it: a rule
+# whose md5 no longer matches its receipt line AND whose `# mxtk-lint-rule:` header is gone (or
+# whose file is gone) was re-seeded, not edited by a person. The run then prints "BLIND — lint
+# rules reverted to stock", names the files, points at sync-project.sh (which restores them and
+# rewrites the receipt, so the next run is clean) and exits 1 without linting; --update-baseline
+# is refused, since baselining stock counts is how the five-day case went in. A rule that still
+# carries the header but differs is a hand edit — install-lint-rules.sh reports those, this does
+# not. No receipt = nothing to compare (pre-receipt installs) = no check. A deliberate headerless
+# local rule: LINT_RULES_REVERTED_OK=1 runs anyway, with the warning.
 #
 # ACCEPTING DEBT IS RECORDED, NOT SILENT (2026-10-12). Three toolkit-built apps re-baselined
 # 61 times in four days — every acceptance made by the agent whose script caused the rise,
@@ -111,7 +128,7 @@ while [ $# -gt 0 ]; do
               REASON="$2"; shift ;;
     --reason=*) REASON="${1#--reason=}" ;;
     --approved-in-chat) APPROVED=1 ;;
-    -h|--help) sed -n '2,35p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,60p' "$0"; exit 0 ;;
     *) echo "lint-gate: unknown argument '$1'" >&2; exit 2 ;;
   esac
   shift
@@ -133,6 +150,61 @@ if [ "$FULL" -eq 0 ] && [ -f "$VENDOR_FILE" ]; then
   EXCLUDE="$(grep -v '^[[:space:]]*#' "$VENDOR_FILE" | grep -v '^[[:space:]]*$' | paste -sd, -)"
 fi
 
+# Receipt check (#264, see header). Runs before lint, on check AND update runs, and also under
+# LINT_JSON so fixtures exercise it. Reads the receipt bin/lib/install-lint-rules.sh writes;
+# never writes it — only the installer does, and that is the remedy named below.
+RECEIPT="$ROOT/.claude/.mxtk-lint-receipt"
+if [ -f "$RECEIPT" ]; then
+  # Read into a variable first: a heredoc inside $(...) does not parse on bash 3.2.
+  IFS= read -r -d '' _RCHK <<'PY' || true
+import hashlib, os
+rec, d = os.environ["RECEIPT"], os.environ["RULES_DIR"]
+for line in open(rec, encoding="utf-8", errors="replace"):
+    parts = line.split()
+    if len(parts) < 2 or parts[0].startswith("#"):
+        continue
+    name, want = parts[0], parts[1]
+    path = os.path.join(d, name)
+    if not os.path.isfile(path):
+        print("%s\tgone (installed per the receipt, missing now)" % name)
+        continue
+    data = open(path, "rb").read()
+    got = hashlib.md5(data).hexdigest()
+    if got == want:
+        continue
+    if b"# mxtk-lint-rule:" in data:
+        continue  # header kept: a hand edit, which install-lint-rules.sh reports
+    print("%s\theader gone, md5 %s != receipt %s" % (name, got[:8], want[:8]))
+PY
+  REVERTED="$(RECEIPT="$RECEIPT" RULES_DIR="$ROOT/.claude/lint-rules" "$PY" -c "$_RCHK")"
+  if [ -n "$REVERTED" ]; then
+    TKR=""
+    type find_toolkit_root >/dev/null 2>&1 && TKR="$(PROJECT_ROOT="$ROOT" find_toolkit_root 2>/dev/null || true)"
+    echo "!! LINT RULES REVERTED TO STOCK (mxcli init?) — this run's delta is not attributable:"
+    printf '%s\n' "$REVERTED" | while IFS="$(printf '\t')" read -r _f _why; do
+      printf '   %s: %s\n' "$_f" "$_why"; done
+    echo ""
+    echo "   Restore the toolkit rules (rewrites .claude/.mxtk-lint-receipt), then re-run:"
+    echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT"
+    if [ "${LINT_RULES_REVERTED_OK:-}" = "1" ]; then
+      echo "   LINT_RULES_REVERTED_OK=1 — linting anyway; counts below are from the files on disk."
+      echo ""
+    elif [ "$UPDATE" -eq 1 ]; then
+      echo "lint-gate: REFUSED — --update-baseline over reverted rules would baseline stock counts." >&2
+      exit 2
+    else
+      echo "BLIND — lint rules reverted to stock; lint not run, nothing compared against the baseline."
+      # lint-last.json gets the verdict but no total: lint did not run, and a stale total from
+      # the previous run would be read as this run's by metrics-ledger.sh. No ledger row either.
+      mkdir -p "$ROOT/.claude/loop" 2>/dev/null &&
+        printf '{\n  "timestamp": "%s",\n  "verdict": "BLIND-RULES-REVERTED",\n  "reverted": "%s"\n}\n' \
+          "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$(printf '%s\n' "$REVERTED" | cut -f1 | paste -sd, -)" \
+          > "$ROOT/.claude/loop/lint-last.json" 2>/dev/null || true
+      exit 1
+    fi
+  fi
+fi
+
 # LINT_JSON=<file> skips mxcli entirely and reads pre-captured lint output. This makes
 # the comparison logic testable against fixtures with no .mpr, no mxcli and no catalog
 # (a full cold run costs ~12 min on a project whose catalog needs rebuilding).
diff --git a/skills/learned-mdl-preflight.md b/skills/learned-mdl-preflight.md
index 69993014..2c72f814 100644
--- a/skills/learned-mdl-preflight.md
+++ b/skills/learned-mdl-preflight.md
@@ -60,6 +60,7 @@ Re-probed on mxcli v0.24.0 / Mendix 11.13.0 (2026-09-30); rules that now work or
 | 25 | Write a microflow with any loop, >20 planned activities, or a list built from a list | **STOP → run `microflow-preflight.md` and post its checklist first.** | Lint runs only after exec and counts only top-level activities (a loop body is invisible to CONV009/QUAL003); CONV011 commit-in-loop and MPR008 overlap findings came back on field builds after the write, not before. |
 | 26 | Bind a DataGrid 2 column over an **association** | **STOP → write the column path unquoted.** Use `Attribute: Assoc_A_B/Name`, never `"Assoc_A_B/Name"`. This is the one place a quote-every-identifier convention must break. | A quoted path is stored as one attribute named `Assoc_A_B/Name`. v0.24.0: passes `check --references`, then `[CE1613] attribute 'Mod.Entity."Assoc_A_B/Name"' no longer exists` at `mx check`; the unquoted form builds at 0 errors, and so does `sort by Assoc/Attr`. `BUG-DRAFT-dg2-association-path-bindings` |
 | 27 | *(retired 2026-09-30 — marketplace install by content id and by `--file` both stamp `FromAppStore`, `AppStoreGuid`, `PackageId` and `Version` (BSON-verified; `SHOW MODULES` shows `Marketplace v<version>`); how Studio Pro groups the module was not testable)* | | |
+| 28 | Change an existing microflow **near a `return` in a dense flow** (`create or modify microflow`, or an `alter microflow` insert before the return) | **Plan drop + create in the same script, not a splice — and run `show access on microflow Mod.Name` first.** A passing `check -p --references` is not evidence here: it does not run exec's free-room test, though it prints "no flow change exec would refuse". If `show access` lists grants, restate them after the create (not field-proven: the field case had none). Row 21 applies to the restatement. | v0.25.0, Mendix 11.14.0, 2026-10-11: `check` passed; exec refused with `create or modify microflow Common.IVK_X: this change cannot be spliced into the stored flow ... insert before return $LiveResult: there is no free room for the fragment ... drawn over the ActionActivity at (2025, 200)` and exec.sh restored the snapshot. `alter microflow` insert takes no `@position`, cannot move objects, and cannot replace a fragment that returns, so drop + create was the only write. BUG-156. |
 
 **Default to the CLI for everything in the table above that is not a STOP row** (`./bin/exec.sh`, Studio Pro closed).
 
diff --git a/skills/lint-that-actually-runs.md b/skills/lint-that-actually-runs.md
index 64b1b179..beb2a0d3 100644
--- a/skills/lint-that-actually-runs.md
+++ b/skills/lint-that-actually-runs.md
@@ -191,6 +191,9 @@ telling a human to do it.
   reverted ARCH002/ARCH003 reports a clean pass while inspecting nothing. This is why the install
   receipt lives outside `lint-rules/` and why installing rules **after** `mxcli init` is not a
   style preference.
+  Between syncs, `bin/lint-gate.sh` reads the same receipt before every lint: a rule whose md5
+  no longer matches and whose header is gone stops the run as `BLIND — lint rules reverted to
+  stock` (exit 1, exec.sh logs `LINT BLIND`), not as a rise on the next script (#264).
 - **Registering a file is not enough — register the pointer.** An earlier workstream's scripts sat
   in the toolkit unused for weeks because the routing row naming them existed in 2 of 6 projects.
   Nothing told any agent they existed. A skill without a `bin/lib/skill-routing.tsv` row is
diff --git a/tests/wave2/test-lint-receipt-revert.sh b/tests/wave2/test-lint-receipt-revert.sh
new file mode 100755
index 00000000..85057c28
--- /dev/null
+++ b/tests/wave2/test-lint-receipt-revert.sh
@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Fixture for project-bin/lint-gate.sh's receipt check (#264) and exec.sh's reading of it.
+#
+# Usage: bash test-lint-receipt-revert.sh [path-to-lint-gate.sh]
+#
+# Field case (two toolkit-built apps, mxcli v0.25.0, 2026-10-07 and 2026-10-11): `mxcli init`
+# re-seeded .claude/lint-rules/ and the toolkit rules lost their `# mxtk-lint-rule:` header.
+# CONV010 went 26 -> 169 and the next exec (a pages-only script) was logged as the rise; in the
+# other app the stock rules sat for five days and the baseline absorbed their counts. The
+# installer's receipt (.claude/.mxtk-lint-receipt) already records each rule's md5 as installed;
+# lint-gate never read it.
+#
+# Golden input: the receipt and rules are produced by running the REAL installer
+# (bin/lib/install-lint-rules.sh, the function init-project.sh and sync-project.sh call) into a
+# scratch project — never a hand-written receipt. The re-seed is simulated the way the field
+# showed it: header block gone (entity_business_key's stock body IS the toolkit body minus the
+# header — the installer's "headered" branch), and a rule file removed (init drops rules it does
+# not know). Lint output is read through LINT_JSON; no mxcli or .mpr is needed. exec.sh's
+# run_lint_gate() is extracted from the real file and executed.
+set -uo pipefail
+TK="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+GATE="${1:-$TK/project-bin/lint-gate.sh}"
+EXEC="$TK/project-bin/exec.sh"
+. "$TK/bin/lib/portable.sh"
+require_py
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/lint-receipt.XXXXXX")"
+trap '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/^/       /'; }
+
+P="$WORK/proj"; mkdir -p "$P/bin" "$P/.claude"
+cp "$GATE" "$P/bin/lint-gate.sh"; [ -f "$TK/project-bin/_common.sh" ] && cp "$TK/project-bin/_common.sh" "$P/bin/"
+printf 'mpr' > "$P/App.mpr"; printf '#!/bin/sh\nexit 0\n' > "$P/mxcli"; chmod +x "$P/mxcli" "$P/bin/lint-gate.sh"
+install_rules() { ( . "$TK/bin/lib/install-lint-rules.sh"; mxtk_install_lint_rules "$TK" "$P" 0 "" ) 2>&1; }
+
+v() { i=0; while [ "$i" -lt "$3" ]; do
+  printf '{"ruleId":"%s","severity":"%s","message":"finding %s","module":"Orders","document":"Doc%s","documentType":"microflow","documentId":"id-%s-%s","suggestion":"s"},' \
+    "$1" "$2" "$i" "$i" "$1" "$i"; i=$((i+1)); done; }
+mk() { printf '{"violations":[%s{"ruleId":"MPR001","severity":"warning","message":"m","module":"Orders","document":"E","documentType":"entity","documentId":"x","suggestion":"s"}],"summary":{}}' "$1" > "$WORK/lint.json"; }
+gate() { (cd "$P" && LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh "$@"); }
+fn="$WORK/run_lint_gate.sh"; sed -n '/^run_lint_gate() {/,/^}/p' "$EXEC" > "$fn"
+exec_detail() { (cd "$P" && PROJECT_ROOT="$P" LINT_JSON="$WORK/lint.json" bash -c ". '$fn'; LINT_RC=0; run_lint_gate >/dev/null; echo \"\$LINT_RC|\$LINT_DETAIL\""); }
+strip_header() { sed '1,/^# --- end mxtk-lint-rule header ---$/d' "$1" > "$1.tmp" && mv "$1.tmp" "$1"; }
+
+echo "T0 golden input: the real installer writes the rules and the receipt"
+out=$(install_rules)
+R="$P/.claude/.mxtk-lint-receipt"
+[ -f "$R" ] && ok "receipt written by install-lint-rules.sh" || bad "installer wrote no receipt" "$out"
+n=$(grep -cv '^#' "$R" 2>/dev/null || echo 0)
+[ "$n" -ge 3 ] && ok "receipt lists $n rules" || bad "receipt lists $n rules"
+grep -q '^conv010_act_microflow_content.star  [0-9a-f]\{32\}$' "$R" && ok "conv010 row: name + md5" || bad "conv010 row missing" "$(cat "$R")"
+
+echo "T1 rules as installed: no receipt complaint, normal ratchet"
+mk "$(v CONV010 warning 26)"
+out=$(gate --update-baseline 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "baseline written over installed rules" || bad "rc=$rc" "$out"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "unchanged run passes (rc 0)" || bad "rc=$rc" "$out"
+case "$out" in *REVERTED*) bad "false receipt alarm on untouched rules" "$out" ;; *) ok "no receipt alarm" ;; esac
+
+echo "T2 re-seed: header gone on two rules, one rule removed -> BLIND, not a rise"
+strip_header "$P/.claude/lint-rules/conv010_act_microflow_content.star"
+strip_header "$P/.claude/lint-rules/data_change_microflows.star"
+rm -f "$P/.claude/lint-rules/entity_business_key.star"
+mk "$(v CONV010 warning 169)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 1 ] && ok "exit 1 (the blind code)" || bad "rc=$rc" "$out"
+case "$out" in *"BLIND — lint rules reverted to stock"*) ok "says BLIND, reverted to stock" ;; *) bad "no BLIND verdict" "$out" ;; esac
+case "$out" in *"FAIL —"*|*"got worse"*) bad "reported as a rise" "$out" ;; *) ok "CONV010 26 -> 169 not reported as a rise" ;; esac
+for f in conv010_act_microflow_content.star data_change_microflows.star entity_business_key.star; do
+  case "$out" in *"$f"*) ok "names $f" ;; *) bad "does not name $f" "$out" ;; esac
+done
+case "$out" in *ux001_confirm_before_destructive.star*) bad "names an untouched rule" "$out" ;; *) ok "untouched rules not named" ;; esac
+case "$out" in *"bin/sync-project.sh $P"*) ok "points at the remedy (sync-project.sh <root>)" ;; *) bad "no remedy command" "$out" ;; esac
+"$PY" -c 'import json,sys;d=json.load(open(sys.argv[1]));sys.exit(0 if d["verdict"]=="BLIND-RULES-REVERTED" and "total" not in d else 1)' \
+  "$P/.claude/loop/lint-last.json" 2>/dev/null && ok "lint-last.json: BLIND-RULES-REVERTED, no stale total" \
+  || bad "lint-last.json wrong" "$(cat "$P/.claude/loop/lint-last.json" 2>/dev/null)"
+
+echo "T3 exec.sh logs it as LINT BLIND (rc 3), naming the files"
+d=$(exec_detail)
+case "$d" in "3|lint BLIND: rules reverted to stock (conv010_act_microflow_content.star,data_change_microflows.star,entity_business_key.star)"*) ok "exec detail: ${d#*|}" ;;
+  *) bad "exec did not log a reverted-rules BLIND" "$d" ;; esac
+
+echo "T4 --update-baseline over reverted rules is refused, baseline untouched"
+before=$(cat "$P/.claude/lint-baseline.json")
+out=$(gate --update-baseline --reason "x" 2>&1); rc=$?
+[ "$rc" -eq 2 ] && ok "refused (rc 2)" || bad "stock counts baselined (rc $rc)" "$out"
+[ "$(cat "$P/.claude/lint-baseline.json")" = "$before" ] && ok "baseline unchanged" || bad "baseline rewritten"
+
+echo "T5 LINT_RULES_REVERTED_OK=1 lints anyway, with the warning"
+out=$(cd "$P" && LINT_RULES_REVERTED_OK=1 LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh 2>&1); rc=$?
+case "$out" in *"REVERTED TO STOCK"*"FAIL —"*) ok "warned, then compared (rise visible)" ;; *) bad "override did not lint" "$out" ;; esac
+
+echo "T6 the remedy is not blocked and clears it (the installer sync-project.sh runs)"
+out=$(install_rules)
+case "$out" in *conv010_act_microflow_content.star*) ok "installer restored conv010" ;; *) bad "installer did not touch conv010" "$out" ;; esac
+mk "$(v CONV010 warning 26)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "after the remedy: rc 0, no alarm" || bad "still blocked after the remedy (rc $rc)" "$out"
+
+echo "T7 a hand edit that keeps the header is not called a revert"
+printf '\n# local tweak\n' >> "$P/.claude/lint-rules/data_change_microflows.star"
+out=$(gate 2>&1); rc=$?
+case "$out" in *REVERTED*) bad "hand edit flagged as a revert" "$out" ;; *) ok "headered edit left to the installer's report" ;; esac
+
+echo "T8 no receipt (pre-receipt install): no check"
+rm -f "$R"; strip_header "$P/.claude/lint-rules/conv010_act_microflow_content.star"
+out=$(gate 2>&1); rc=$?
+case "$out" in *REVERTED*) bad "alarm with no receipt to compare" "$out" ;; *) ok "no receipt -> no alarm (rc $rc)" ;; esac
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$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/9] 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/9] =?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 18c9a616da9f2fcf24ab9be5d180dbb9b8a2cfb1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 14:45:22 +0000
Subject: [PATCH 4/9] fix(lint-rules): the remedy lint-gate prints always
 clears it; deliberate opt-out; prune stale receipt rows (#264 review)

Review of #308 (MERGE-AFTER-SMALL-FIX):

1. bin/lib/install-lint-rules.sh: a rule whose receipt row exists and whose `# mxtk-lint-rule:`
   header is gone is restored even when its hash is not in STOCK-HASHES.txt (an mxcli newer
   than the list, then init). It used to fall into the foreign branch -> LOCALLY MODIFIED, never
   written, so lint-gate stayed BLIND forever. Same test lint-gate uses; the found file is kept
   as <rule>.reseeded-<ts>. lint-gate's message adds the fallback
   `sync-project.sh <root> --upgrade-lint-rules all`.
2. Deliberate opt-out: .claude/lint-rules-disabled.txt. The installer never installs/restores a
   listed rule and prunes its receipt row; lint-gate skips it. lint-rules/README.md (txt002 row,
   CONV010 prefix note) now says list-then-delete, with an "Opting out of a rule" section.
3. The installer prunes receipt rows for rules no longer in MXTK_LINT_RULES /
   MXTK_LINT_RULES_CONFIGURABLE, so a retired rule is not "gone" forever.
4. skills/learned-mdl-preflight.md row 28 cut to trigger + rule + one-line failure (60 words,
   was ~230); the narrative stays in BUG-156.

Fixture tests/wave2/test-lint-receipt-revert.sh T9-T11 (INSTALLER= swaps the installer):
T9 uses a genuine stock body (toolkit entity_business_key minus header, md5 d66528c9 = the
v0.24.0/v0.25.0 stock hash in STOCK-HASHES.txt) under a scratch toolkit that does not list the
hash and whose rule has moved off stock. 38/38 here; 9 fail with master's installer, 21 with
master's installer + lint-gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                            |  2 +-
 bin/lib/install-lint-rules.sh           | 65 +++++++++++++++++++++++++
 lint-rules/README.md                    | 14 +++++-
 project-bin/lint-gate.sh                | 23 +++++++--
 skills/learned-mdl-preflight.md         |  2 +-
 tests/wave2/test-lint-receipt-revert.sh | 62 +++++++++++++++++++++++
 6 files changed, 159 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 25201fa2..7c0a17a4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a rule whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or that is missing, is named, the remedy `bin/sync-project.sh <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer: 23/23 here, 11 fail on master's lint-gate. — AlvinnYeo
+- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a rule whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or that is missing, is named, the remedy `bin/sync-project.sh <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the printed remedy always clears it, `bin/lib/install-lint-rules.sh` now restores a rule whose receipt row exists and whose header is gone even when its stock hash is not in `STOCK-HASHES.txt` (an mxcli upgrade, then init; it was reported LOCALLY MODIFIED and never written), prunes receipt rows for rules no longer shipped, and honours a new `.claude/lint-rules-disabled.txt` opt-out that lint-gate also reads (`lint-rules/README.md` told projects to delete txt002, which would now read as a re-seed). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 38/38 here, 21 fail on master's lint-gate and installer. — AlvinnYeo
 - learn(learned-mdl-preflight): **a microflow change near a `return` in a dense flow is planned as drop + create after `show access`; `check -p --references` does not run exec's free-room test** ([#263](https://github.com/MendixMau/mxcli-project-toolkit/issues/263)). STOP row 28 and BUG-156: on v0.25.0 `check` printed "no flow change exec would refuse" and exec then refused "there is no free room for the fragment". Upstream issue drafted, not filed. — AlvinnYeo
 - 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
diff --git a/bin/lib/install-lint-rules.sh b/bin/lib/install-lint-rules.sh
index 9c157891..c864520a 100644
--- a/bin/lib/install-lint-rules.sh
+++ b/bin/lib/install-lint-rules.sh
@@ -114,6 +114,46 @@ _mxtk_lint_receipt_set() {
   } > "$_tmp" && mv "$_tmp" "$_receipt"
 }
 
+# DELIBERATE OPT-OUT. .claude/lint-rules-disabled.txt, one rule file per line ('#' comments).
+# A rule listed there is never installed or restored, and its receipt row is pruned, so
+# deleting it is not undone by the next sync and lint-gate.sh (which reads the same file) does
+# not report the deletion as a re-seed. Deleting a rule without listing it is what `mxcli init`
+# does, and is treated as such.
+_mxtk_lint_is_disabled() {
+  # Own variable names: callers loop with _n/_m/_f, and these are not `local` (POSIX sh).
+  _dis_file="$1"; _dis_want="$2"
+  [ -f "$_dis_file" ] || return 1
+  while read -r _dis_n _dis_rest; do
+    case "$_dis_n" in ''|'#'*) continue ;; esac
+    [ "$_dis_n" = "$_dis_want" ] && return 0
+  done < "$_dis_file"
+  return 1
+}
+
+# Drop receipt rows for rules this toolkit no longer ships, or that the project disabled.
+# A stale row would make lint-gate.sh report the rule "gone" on every run, forever.
+_mxtk_lint_receipt_prune() {
+  _receipt="$1"; _keep=" $2 "; _dis="$3"
+  [ -f "$_receipt" ] || return 0
+  _pruned=""; _tmp="$_receipt.tmp.$$"
+  {
+    printf '# md5 of each toolkit lint rule AS INSTALLED. Written by bin/lib/install-lint-rules.sh.\n'
+    printf '# Do not edit. Deleting this file makes a revert-to-stock look like a first install.\n'
+    while read -r _n _m _r; do
+      case "$_n" in ''|'#'*) continue ;; esac
+      case "$_keep" in *" $_n "*) ;; *) _pruned="$_pruned $_n"; continue ;; esac
+      if _mxtk_lint_is_disabled "$_dis" "$_n"; then _pruned="$_pruned $_n"; continue; fi
+      printf '%s  %s\n' "$_n" "$_m"
+    done < "$_receipt"
+  } > "$_tmp"
+  if [ -n "$_pruned" ]; then
+    mv "$_tmp" "$_receipt"
+    echo "Lint receipt: dropped row(s) for rules no longer shipped or disabled here:$_pruned"
+  else
+    rm -f "$_tmp"
+  fi
+}
+
 mxtk_install_lint_rules() {
   _tk="$1"; _proj="$2"; _dry="${3:-0}"; _upg="${4:-}"
 
@@ -123,6 +163,7 @@ mxtk_install_lint_rules() {
   _dst_dir="$_proj/.claude/lint-rules"
   _hashes="$_src_dir/STOCK-HASHES.txt"
   _receipt="$_proj/.claude/.mxtk-lint-receipt"
+  _disabled="$_proj/.claude/lint-rules-disabled.txt"
 
   if [ ! -d "$_src_dir" ]; then
     _mxtk_lint_warn "Toolkit has no lint-rules/ — this project's lint rules were not checked."
@@ -157,6 +198,7 @@ mxtk_install_lint_rules() {
     for _f in $_list; do
       _src="$_src_dir/$_f"; _dst="$_dst_dir/$_f"
       [ -f "$_src" ] || continue
+      _mxtk_lint_is_disabled "$_disabled" "$_f" && continue
       _srcmd5="$(portable_md5 "$_src")" || continue
       _rec="$(_mxtk_lint_receipt_get "$_receipt" "$_f" 2>/dev/null || true)"
 
@@ -240,6 +282,27 @@ mxtk_install_lint_rules() {
         continue
       fi
 
+      # ---- installed by us, header gone, stock hash not on file -----------------------
+      # The receipt says we installed this file, and the provenance header is gone. That is
+      # a re-seed by an mxcli version STOCK-HASHES.txt does not list yet (an upgrade, then
+      # init), not a hand edit: a hand edit keeps the header. The same test lint-gate.sh uses
+      # to declare the run BLIND, so the remedy it prints (sync) actually clears it (#264
+      # review: without this branch the file was reported LOCALLY MODIFIED and never written,
+      # and lint stayed BLIND forever). The found file is kept beside it, not loaded by lint.
+      if [ -n "$_rec" ] && ! grep -q '^# mxtk-lint-rule:' "$_dst"; then
+        _why="REVERTED TO STOCK — header gone and its hash is not in STOCK-HASHES.txt (newer mxcli?). Restoring it"
+        if [ "$_dry" -eq 1 ]; then
+          echo "Would install: .claude/lint-rules/$_f ($_why)"
+        else
+          _bak="$_dst.reseeded-$(date +%Y%m%d%H%M%S)"
+          cp "$_dst" "$_bak"
+          cp "$_src" "$_dst" && _mxtk_lint_receipt_set "$_receipt" "$_f" "$_srcmd5"
+          echo "Lint rule: $_why — .claude/lint-rules/$_f (found copy kept at $(basename "$_bak"); md5 $_dstmd5 — add it to STOCK-HASHES.txt if it is a stock seed)"
+        fi
+        MXTK_LINT_CHANGES=$((MXTK_LINT_CHANGES + 1))
+        continue
+      fi
+
       # ---- configurable and edited: this is the EXPECTED state, not drift ------------
       # conv020 ships with PROJECT_MODULES empty and refuses to run until it is filled in.
       # Refreshing it would silently un-configure the rule and send it back to inspecting
@@ -283,5 +346,7 @@ mxtk_install_lint_rules() {
   if [ -n "$_drifted" ] && [ -z "$_upg" ]; then
     echo "   (upgrade every drifted lint rule at once with: --upgrade-lint-rules all)"
   fi
+  [ "$_dry" -eq 1 ] || _mxtk_lint_receipt_prune "$_receipt" \
+    "${MXTK_LINT_RULES:-} ${MXTK_LINT_RULES_CONFIGURABLE:-}" "$_disabled"
   return 0
 }
diff --git a/lint-rules/README.md b/lint-rules/README.md
index 81b2cfd4..672e033a 100644
--- a/lint-rules/README.md
+++ b/lint-rules/README.md
@@ -18,7 +18,7 @@ and configure the marked constants — **after** running `mxcli init`, never bef
 | `perf002_nested_data_widgets.star` | PERF002 — a data view / list view / data grid / gallery nested inside two or more other data widgets on the same page: re-queries per row at every level | `MAX_NESTING`, `DATA_WIDGET_CANDIDATES`, `EXCLUDE` (widget_type vocabulary: probe first) |
 | `perf004_npe_system_user_assoc.star` | PERF004 — an association between a non-persistable entity and System.User / System.Session (or an entity generalizing them), which pins session objects to the shared side | `NON_PERSISTABLE_CANDIDATES`, `SYSTEM_TARGETS` (entity_type vocabulary: probe first) |
 | `txt001_build_words_in_user_text.star` | TXT001 — user-visible text (titles, captions, templates, messages, menu items) holding build-process words: `Stage N`, `BR-10`, `F004`, TODO, a version tag, "(local, …)" | `PROJECT_WORDS` (sibling-app and project code names); `LEAK_PATTERNS` if "Stage N" is a real domain word |
-| `txt002_non_iso_date_in_user_text.star` | TXT002 — user-visible text holding a non-ISO literal date (10/12/2026, 12 Oct 2026) or a day/month format pattern (dd MMM, MM/dd); blind to format strings inside expressions | no — delete it deliberately if the project's display standard is not ISO |
+| `txt002_non_iso_date_in_user_text.star` | TXT002 — user-visible text holding a non-ISO literal date (10/12/2026, 12 Oct 2026) or a day/month format pattern (dd MMM, MM/dd); blind to format strings inside expressions | no — to opt out (display standard is not ISO), list it in `.claude/lint-rules-disabled.txt`, then delete it |
 | `ui001_widget_layout_traps.star` | UI001 — a list view inside a Data grid 2 column (its own "Load more" / "No items found" in every cell); an inline `width` on an Atlas input without `flex` (ignored) | `DATAGRID_TYPES`, `LISTVIEW_TYPES`, `INPUT_TYPES` (widget_type vocabulary: probe first) |
 
 `err001` and `loop001` first field count (2026-10-12, mxcli 0.26.0, 21-module Mendix 11.12 model,
@@ -107,7 +107,17 @@ the real prefix produces none. `bin/lint-gate.sh` treats `module == "_rule"` as
 this turns a silent pass into a gate failure rather than a line in a report nobody reads.
 
 Set `ACTION_PREFIX` / `DELEGATE_PREFIX` to your project's prefixes. If the project has no such
-convention, delete the rule deliberately rather than leaving it inert.
+convention, opt out deliberately rather than leaving it inert: list the file in
+`.claude/lint-rules-disabled.txt`, then delete it (see "Opting out of a rule" below).
+
+## Opting out of a rule
+
+List the rule file, one per line, in `.claude/lint-rules-disabled.txt`, then delete it from
+`.claude/lint-rules/`. A bare delete does not stick: `sync-project.sh` restores a rule it
+installed before, and `bin/lint-gate.sh` reads a rule that its receipt lists but that is missing
+as a `mxcli init` re-seed, so every exec reports `LINT BLIND` (#264). With the rule listed,
+the installer neither installs nor restores it and drops its receipt row, and lint-gate
+skips it.
 
 ## How these reach a project
 
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index ac88c496..eca387c1 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -34,8 +34,10 @@
 # rewrites the receipt, so the next run is clean) and exits 1 without linting; --update-baseline
 # is refused, since baselining stock counts is how the five-day case went in. A rule that still
 # carries the header but differs is a hand edit — install-lint-rules.sh reports those, this does
-# not. No receipt = nothing to compare (pre-receipt installs) = no check. A deliberate headerless
-# local rule: LINT_RULES_REVERTED_OK=1 runs anyway, with the warning.
+# not. No receipt = nothing to compare (pre-receipt installs) = no check. A rule removed on
+# purpose is listed in .claude/lint-rules-disabled.txt (the installer honours the same file and
+# prunes its receipt row). A deliberate headerless local rule: LINT_RULES_REVERTED_OK=1 runs
+# anyway, with the warning.
 #
 # ACCEPTING DEBT IS RECORDED, NOT SILENT (2026-10-12). Three toolkit-built apps re-baselined
 # 61 times in four days — every acceptance made by the agent whose script caused the rise,
@@ -128,7 +130,7 @@ while [ $# -gt 0 ]; do
               REASON="$2"; shift ;;
     --reason=*) REASON="${1#--reason=}" ;;
     --approved-in-chat) APPROVED=1 ;;
-    -h|--help) sed -n '2,60p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,62p' "$0"; exit 0 ;;
     *) echo "lint-gate: unknown argument '$1'" >&2; exit 2 ;;
   esac
   shift
@@ -158,12 +160,20 @@ if [ -f "$RECEIPT" ]; then
   # Read into a variable first: a heredoc inside $(...) does not parse on bash 3.2.
   IFS= read -r -d '' _RCHK <<'PY' || true
 import hashlib, os
-rec, d = os.environ["RECEIPT"], os.environ["RULES_DIR"]
+rec, d, dis = os.environ["RECEIPT"], os.environ["RULES_DIR"], os.environ["DISABLED"]
+disabled = set()
+if os.path.isfile(dis):
+    for line in open(dis, encoding="utf-8", errors="replace"):
+        w = line.split()
+        if w and not w[0].startswith("#"):
+            disabled.add(w[0])
 for line in open(rec, encoding="utf-8", errors="replace"):
     parts = line.split()
     if len(parts) < 2 or parts[0].startswith("#"):
         continue
     name, want = parts[0], parts[1]
+    if name in disabled:
+        continue  # deliberate opt-out, .claude/lint-rules-disabled.txt
     path = os.path.join(d, name)
     if not os.path.isfile(path):
         print("%s\tgone (installed per the receipt, missing now)" % name)
@@ -176,7 +186,7 @@ for line in open(rec, encoding="utf-8", errors="replace"):
         continue  # header kept: a hand edit, which install-lint-rules.sh reports
     print("%s\theader gone, md5 %s != receipt %s" % (name, got[:8], want[:8]))
 PY
-  REVERTED="$(RECEIPT="$RECEIPT" RULES_DIR="$ROOT/.claude/lint-rules" "$PY" -c "$_RCHK")"
+  REVERTED="$(RECEIPT="$RECEIPT" RULES_DIR="$ROOT/.claude/lint-rules" DISABLED="$ROOT/.claude/lint-rules-disabled.txt" "$PY" -c "$_RCHK")"
   if [ -n "$REVERTED" ]; then
     TKR=""
     type find_toolkit_root >/dev/null 2>&1 && TKR="$(PROJECT_ROOT="$ROOT" find_toolkit_root 2>/dev/null || true)"
@@ -186,6 +196,9 @@ PY
     echo ""
     echo "   Restore the toolkit rules (rewrites .claude/.mxtk-lint-receipt), then re-run:"
     echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT"
+    echo "   If sync reports a rule LOCALLY MODIFIED instead of restoring it:"
+    echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT --upgrade-lint-rules all"
+    echo "   Removed one on purpose? List it in .claude/lint-rules-disabled.txt and this stops."
     if [ "${LINT_RULES_REVERTED_OK:-}" = "1" ]; then
       echo "   LINT_RULES_REVERTED_OK=1 — linting anyway; counts below are from the files on disk."
       echo ""
diff --git a/skills/learned-mdl-preflight.md b/skills/learned-mdl-preflight.md
index 2c72f814..8acf7c76 100644
--- a/skills/learned-mdl-preflight.md
+++ b/skills/learned-mdl-preflight.md
@@ -60,7 +60,7 @@ Re-probed on mxcli v0.24.0 / Mendix 11.13.0 (2026-09-30); rules that now work or
 | 25 | Write a microflow with any loop, >20 planned activities, or a list built from a list | **STOP → run `microflow-preflight.md` and post its checklist first.** | Lint runs only after exec and counts only top-level activities (a loop body is invisible to CONV009/QUAL003); CONV011 commit-in-loop and MPR008 overlap findings came back on field builds after the write, not before. |
 | 26 | Bind a DataGrid 2 column over an **association** | **STOP → write the column path unquoted.** Use `Attribute: Assoc_A_B/Name`, never `"Assoc_A_B/Name"`. This is the one place a quote-every-identifier convention must break. | A quoted path is stored as one attribute named `Assoc_A_B/Name`. v0.24.0: passes `check --references`, then `[CE1613] attribute 'Mod.Entity."Assoc_A_B/Name"' no longer exists` at `mx check`; the unquoted form builds at 0 errors, and so does `sort by Assoc/Attr`. `BUG-DRAFT-dg2-association-path-bindings` |
 | 27 | *(retired 2026-09-30 — marketplace install by content id and by `--file` both stamp `FromAppStore`, `AppStoreGuid`, `PackageId` and `Version` (BSON-verified; `SHOW MODULES` shows `Marketplace v<version>`); how Studio Pro groups the module was not testable)* | | |
-| 28 | Change an existing microflow **near a `return` in a dense flow** (`create or modify microflow`, or an `alter microflow` insert before the return) | **Plan drop + create in the same script, not a splice — and run `show access on microflow Mod.Name` first.** A passing `check -p --references` is not evidence here: it does not run exec's free-room test, though it prints "no flow change exec would refuse". If `show access` lists grants, restate them after the create (not field-proven: the field case had none). Row 21 applies to the restatement. | v0.25.0, Mendix 11.14.0, 2026-10-11: `check` passed; exec refused with `create or modify microflow Common.IVK_X: this change cannot be spliced into the stored flow ... insert before return $LiveResult: there is no free room for the fragment ... drawn over the ActionActivity at (2025, 200)` and exec.sh restored the snapshot. `alter microflow` insert takes no `@position`, cannot move objects, and cannot replace a fragment that returns, so drop + create was the only write. BUG-156. |
+| 28 | Change an existing microflow near a `return` in a dense flow | **Plan drop + create in one script, after `show access on microflow` (re-grant what it lists).** A passing `check -p --references` skips exec's free-room test. | v0.25.0: `check` passed, exec refused `insert before return $LiveResult: there is no free room for the fragment`. BUG-156 |
 
 **Default to the CLI for everything in the table above that is not a STOP row** (`./bin/exec.sh`, Studio Pro closed).
 
diff --git a/tests/wave2/test-lint-receipt-revert.sh b/tests/wave2/test-lint-receipt-revert.sh
index 85057c28..5223d4f7 100755
--- a/tests/wave2/test-lint-receipt-revert.sh
+++ b/tests/wave2/test-lint-receipt-revert.sh
@@ -2,6 +2,7 @@
 # Fixture for project-bin/lint-gate.sh's receipt check (#264) and exec.sh's reading of it.
 #
 # Usage: bash test-lint-receipt-revert.sh [path-to-lint-gate.sh]
+#   INSTALLER=<install-lint-rules.sh> swaps the installer under test in T9-T11.
 #
 # Field case (two toolkit-built apps, mxcli v0.25.0, 2026-10-07 and 2026-10-11): `mxcli init`
 # re-seeded .claude/lint-rules/ and the toolkit rules lost their `# mxtk-lint-rule:` header.
@@ -109,6 +110,67 @@ rm -f "$R"; strip_header "$P/.claude/lint-rules/conv010_act_microflow_content.st
 out=$(gate 2>&1); rc=$?
 case "$out" in *REVERTED*) bad "alarm with no receipt to compare" "$out" ;; *) ok "no receipt -> no alarm (rc $rc)" ;; esac
 
+# ---- review follow-ups: an mxcli newer than STOCK-HASHES, deliberate opt-out, manifest drops ----
+# A scratch toolkit copy: lint-rules/ + bin/lib/. INSTALLER=<file> swaps in another
+# install-lint-rules.sh (used to prove these cases fail on master's installer).
+TK2="$WORK/tk2"; mkdir -p "$TK2/bin"
+cp -R "$TK/lint-rules" "$TK2/lint-rules"; cp -R "$TK/bin/lib" "$TK2/bin/lib"
+[ -n "${INSTALLER:-}" ] && cp "$INSTALLER" "$TK2/bin/lib/install-lint-rules.sh"
+newproj() { _p="$WORK/$1"; mkdir -p "$_p/bin" "$_p/.claude"; cp "$P/bin/lint-gate.sh" "$_p/bin/"
+  [ -f "$P/bin/_common.sh" ] && cp "$P/bin/_common.sh" "$_p/bin/"
+  cp "$P/.claude/lint-baseline.json" "$_p/.claude/"; printf 'mpr' > "$_p/App.mpr"; cp "$P/mxcli" "$_p/mxcli"; echo "$_p"; }
+inst2() { ( [ -n "${2:-}" ] && MXTK_LINT_RULES="$2"; . "$TK2/bin/lib/install-lint-rules.sh"; mxtk_install_lint_rules "$TK2" "$1" 0 "" ) 2>&1; }
+gate2() { (cd "$1" && LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh); }
+mk "$(v CONV010 warning 26)"
+
+echo "T9 a genuine stock body whose hash STOCK-HASHES does not list (mxcli upgrade, then init)"
+EBK=entity_business_key.star
+STOCK="$WORK/ebk-stock.star"; sed '1,/^# --- end mxtk-lint-rule header ---$/d' "$TK/lint-rules/$EBK" > "$STOCK"
+# Genuine: this body's md5 is the v0.24.0/v0.25.0 stock hash recorded in the REAL STOCK-HASHES.txt.
+sm=$(portable_md5 "$STOCK")
+grep -q "^$EBK  *$sm " "$TK/lint-rules/STOCK-HASHES.txt" && ok "stock body is genuine (md5 $sm is in STOCK-HASHES.txt)" \
+  || bad "stock body md5 $sm not a recorded stock hash"
+# Unknown version: the scratch toolkit forgets that hash, and its rule has moved off stock (as
+# conv010 and data_change have), so neither the stock nor the "headered" branch can match.
+grep -v "^$EBK " "$TK/lint-rules/STOCK-HASHES.txt" > "$TK2/lint-rules/STOCK-HASHES.txt"
+printf '# toolkit fix, not in stock\n' >> "$TK2/lint-rules/$EBK"
+P9=$(newproj p9); inst2 "$P9" >/dev/null
+cp "$STOCK" "$P9/.claude/lint-rules/$EBK"
+out=$(gate2 "$P9" 2>&1); rc=$?
+[ "$rc" -eq 1 ] && case "$out" in *"BLIND — lint rules reverted"*"$EBK"*|*"$EBK"*"BLIND — lint rules reverted"*) true ;; *) false ;; esac \
+  && ok "lint-gate: BLIND, names $EBK" || bad "lint-gate did not flag the unknown-hash re-seed (rc $rc)" "$out"
+case "$out" in *"--upgrade-lint-rules all"*) ok "message carries the LOCALLY MODIFIED fallback" ;; *) bad "no --upgrade-lint-rules fallback" "$out" ;; esac
+out=$(inst2 "$P9")
+case "$out" in *"REVERTED TO STOCK"*"$EBK"*) ok "installer restores it (not LOCALLY MODIFIED)" ;; *) bad "installer did not restore it" "$out" ;; esac
+cmp -s "$TK2/lint-rules/$EBK" "$P9/.claude/lint-rules/$EBK" && ok "file is the toolkit version again" || bad "file not restored"
+ls "$P9/.claude/lint-rules/$EBK".reseeded-* >/dev/null 2>&1 && ok "found copy kept beside it" || bad "found copy not kept"
+out=$(gate2 "$P9" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "after sync: rc 0 (remedy clears it)" || bad "still blind after sync (rc $rc)" "$out"
+
+echo "T10 a rule removed on purpose (listed in .claude/lint-rules-disabled.txt) is not a re-seed"
+P10=$(newproj p10); inst2 "$P10" >/dev/null
+printf '# display standard is dd/MM/yyyy\ntxt002_non_iso_date_in_user_text.star\n' > "$P10/.claude/lint-rules-disabled.txt"
+rm -f "$P10/.claude/lint-rules/txt002_non_iso_date_in_user_text.star"
+out=$(gate2 "$P10" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "lint-gate: rc 0, no alarm before any sync" || bad "deliberate removal read as a re-seed (rc $rc)" "$out"
+out=$(inst2 "$P10")
+[ ! -f "$P10/.claude/lint-rules/txt002_non_iso_date_in_user_text.star" ] && ok "sync does not restore a disabled rule" || bad "sync restored a disabled rule" "$out"
+grep -q '^txt002_non_iso_date_in_user_text.star ' "$P10/.claude/.mxtk-lint-receipt" && bad "disabled rule's receipt row kept" || ok "disabled rule's receipt row pruned"
+rm -f "$P10/.claude/lint-rules/txt001_build_words_in_user_text.star"
+out=$(gate2 "$P10" 2>&1); rc=$?
+case "$out" in *txt001_build_words_in_user_text.star*) ok "an unlisted removal is still caught" ;; *) bad "unlisted removal missed" "$out" ;; esac
+
+echo "T11 a rule the toolkit stops shipping: its receipt row is pruned, no permanent 'gone'"
+P11=$(newproj p11); inst2 "$P11" >/dev/null
+rm -f "$P11/.claude/lint-rules/ui001_widget_layout_traps.star"   # project tidies the retired rule away
+FEWER=$(printf '%s\n' $(. "$TK2/bin/lib/install-manifest.sh" >/dev/null 2>&1; echo "$MXTK_LINT_RULES") | grep -v '^ui001_widget_layout_traps.star$' | paste -sd' ' -)
+out=$(inst2 "$P11" "$FEWER")
+grep -q '^ui001_widget_layout_traps.star ' "$P11/.claude/.mxtk-lint-receipt" && bad "row for a dropped rule kept" "$out" || ok "row for the dropped rule pruned"
+case "$out" in *"dropped row"*ui001*) ok "installer says so" ;; *) bad "prune not reported" "$out" ;; esac
+[ ! -f "$P11/.claude/lint-rules/ui001_widget_layout_traps.star" ] && ok "dropped rule not reinstalled" || bad "dropped rule reinstalled"
+out=$(gate2 "$P11" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "lint-gate: rc 0 after the prune" || bad "permanent 'gone' (rc $rc)" "$out"
+
 echo ""
 echo "PASS=$PASS FAIL=$FAIL"
 [ "$FAIL" -eq 0 ]

From 543234526bc01c2bb553e24ef6c6c028ac23bf6c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 14:55:42 +0000
Subject: [PATCH 5/9] fix(lint-gate): a Starlark rule installed after the
 baseline is FIRST-SEEN, not a rise (#305 review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rule sync-project.sh installs after the baseline has no baseline count, so its first hit
compared against 0: every exec logged LINT ROSE and exited 1 until someone re-baselined, and
the Lint Batch 3 rules fire on ordinary text (TBD, XXX, v1.2, "12 Oct 2026").

- project-bin/lint-gate.sh: a rule absent from the baseline counts is FIRST-SEEN when it is a
  .star rule in .claude/lint-rules/ (RULE_ID = "...") the baseline did not know: not in the new
  `star_rules` list --update-baseline now writes, or, for an older baseline, its .star file is
  newer than the baseline. Printed as `FIRST-SEEN <rule> N finding(s) — new rule, first seen:
  review and re-baseline with --reason`; exit 0 when nothing else rose; verdict
  PASS-FIRST-SEEN. Re-baselining it needs --reason (it raises a count), after which it is an
  ordinary ratcheted rule. Built-in mxcli rules and .star rules known at baseline with zero
  findings still count as a rise (a baseline omits zero-count rules).
- project-bin/exec.sh: the rc-0 row carries `FIRST-SEEN: <rule> (N) — review, re-baseline with
  --reason`.
- tests/wave2/test-lint-gate-first-seen.sh: real toolkit .star files, LINT_JSON input; 17/17
  here, 8 fail on master's lint-gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                             |   1 +
 project-bin/exec.sh                      |  10 ++-
 project-bin/lint-gate.sh                 |  56 ++++++++++--
 tests/wave2/test-lint-gate-first-seen.sh | 103 +++++++++++++++++++++++
 4 files changed, 163 insertions(+), 7 deletions(-)
 create mode 100755 tests/wave2/test-lint-gate-first-seen.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c0a17a4..9509a509 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(lint-gate): **a Starlark rule installed after the baseline is reported as FIRST-SEEN, not as a rise** ([#305](https://github.com/MendixMau/mxcli-project-toolkit/pull/305) review). A rule sync installs has no baseline count, so its first hit compared against 0: every exec logged `LINT ROSE` and exited 1 until someone re-baselined, and the Lint Batch 3 rules fire on ordinary text (TBD, XXX, v1.2, "12 Oct 2026"). Now a `.star` rule (`RULE_ID = "..."` in `.claude/lint-rules/`) that the baseline did not know prints `FIRST-SEEN <rule> N finding(s) — new rule, first seen: review and re-baseline with --reason`, exits 0 (verdict `PASS-FIRST-SEEN`, exec.sh row `FIRST-SEEN: <rule> (N)`), and is an ordinary ratcheted rule after the next `--update-baseline --reason`. `--update-baseline` now records `star_rules`; for an older baseline the `.star` file being newer than it decides. Built-in rules and `.star` rules known at baseline with zero findings still rise. Fixture `tests/wave2/test-lint-gate-first-seen.sh`: 17/17 here, 8 fail on master's lint-gate. — MendixMau (review of #305)
 - fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a rule whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or that is missing, is named, the remedy `bin/sync-project.sh <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the printed remedy always clears it, `bin/lib/install-lint-rules.sh` now restores a rule whose receipt row exists and whose header is gone even when its stock hash is not in `STOCK-HASHES.txt` (an mxcli upgrade, then init; it was reported LOCALLY MODIFIED and never written), prunes receipt rows for rules no longer shipped, and honours a new `.claude/lint-rules-disabled.txt` opt-out that lint-gate also reads (`lint-rules/README.md` told projects to delete txt002, which would now read as a re-seed). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 38/38 here, 21 fail on master's lint-gate and installer. — AlvinnYeo
 - learn(learned-mdl-preflight): **a microflow change near a `return` in a dense flow is planned as drop + create after `show access`; `check -p --references` does not run exec's free-room test** ([#263](https://github.com/MendixMau/mxcli-project-toolkit/issues/263)). STOP row 28 and BUG-156: on v0.25.0 `check` printed "no flow change exec would refuse" and exec then refused "there is no free room for the fragment". Upstream issue drafted, not filed. — AlvinnYeo
 - 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/project-bin/exec.sh b/project-bin/exec.sh
index a84446de..09043ac9 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -753,7 +753,15 @@ run_lint_gate() {
   LINT_RC=0
   bash "$PROJECT_ROOT/bin/lint-gate.sh" >"$_lo" 2>&1 || LINT_RC=$?
   case "$LINT_RC" in
-    0) LINT_DETAIL="lint unchanged vs baseline"; echo "  ✓ lint: no rule rose vs baseline" ;;
+    0) LINT_DETAIL="lint unchanged vs baseline"; echo "  ✓ lint: no rule rose vs baseline"
+       # A rule installed after the baseline is FIRST-SEEN, not a rise (#305 review): say it on
+       # the row, so the count is reviewed and re-baselined rather than found later.
+       _new=$(grep -E '^ +FIRST-SEEN [A-Z][A-Z0-9-]*[0-9]+ ' "$_lo" | awk '{printf "%s%s (%s)", (n++?", ":""), $2, $4}')
+       if [ -n "$_new" ]; then
+         LINT_DETAIL="lint unchanged vs baseline; FIRST-SEEN: $_new — review, re-baseline with --reason"
+         echo "  ⚠ lint: new rule(s) first seen, not counted as a rise: $_new"
+         echo "    Review the findings, then: bin/lint-gate.sh --update-baseline --reason \"<why>\""
+       fi ;;
     1) # Rule ids are matched as [A-Z][A-Z0-9-]*[0-9]+, not [A-Z]+[0-9]+: mxcli's built-in
        # rules include hyphenated ids (MDL-FLOW01), and the old pattern dropped them from every
        # row — three field apps logged 475 ROSE rows and not one named MDL-FLOW01 (2026-10-12).
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index eca387c1..f761fe0e 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -18,7 +18,8 @@
 #       --approved-in-chat              # ALSO required when a security-tier rule rises
 #   bin/lint-gate.sh --full             # ignore the vendor exclusion (rarely useful)
 #
-# Exit codes: 0 clean or unchanged · 1 a rule increased, or BLIND (a rule inspected nothing,
+# Exit codes: 0 clean, unchanged, or only FIRST-SEEN rules (a .star rule installed after the
+#             baseline: reported, not a rise — #305 review) · 1 a rule increased, or BLIND (a rule inspected nothing,
 #             or the toolkit rules reverted to stock — see below) · 2 could not run (or a
 #             refused update)
 #
@@ -130,7 +131,7 @@ while [ $# -gt 0 ]; do
               REASON="$2"; shift ;;
     --reason=*) REASON="${1#--reason=}" ;;
     --approved-in-chat) APPROVED=1 ;;
-    -h|--help) sed -n '2,62p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,63p' "$0"; exit 0 ;;
     *) echo "lint-gate: unknown argument '$1'" >&2; exit 2 ;;
   esac
   shift
@@ -308,6 +309,28 @@ except (ValueError, IndexError):
     sys.exit(2)
 
 viol = data.get("violations") or []
+
+# FIRST-SEEN (#305 review). A rule sync-project.sh installs AFTER the baseline was taken has no
+# baseline count, so it compared against 0 and its first hit was a "rise": every exec logged
+# LINT ROSE and exited 1 until someone re-baselined (Lint Batch 3's TXT001/TXT002 fire on TBD,
+# XXX, v1.2, "12 Oct 2026"). A rule absent from the baseline counts is FIRST-SEEN, not a rise,
+# when it is a Starlark rule in .claude/lint-rules/ (`RULE_ID = "..."`) that the baseline did not
+# know: listed in neither its counts nor its `star_rules` (written by --update-baseline from now
+# on); for an older baseline without `star_rules`, its .star file is newer than the baseline.
+# Built-in mxcli rules are never first-seen: a baseline omits a rule with zero findings, so
+# "absent" there means "was clean" and a hit is a real rise.
+import re, glob
+def star_rules():
+    out = {}
+    rdir = os.path.join(os.path.dirname(base_path), "lint-rules")
+    for f in glob.glob(os.path.join(rdir, "*.star")):
+        try:
+            m = re.search(r'^RULE_ID\s*=\s*"([^"]+)"', open(f, encoding="utf-8", errors="replace").read(), re.M)
+        except OSError:
+            continue
+        if m:
+            out[m.group(1)] = os.path.getmtime(f)
+    return out
 counts = collections.Counter(v["ruleId"] for v in viol)
 sev    = {v["ruleId"]: v["severity"] for v in viol}
 
@@ -397,6 +420,7 @@ if update:
             sys.exit(2)
     json.dump({"counts": dict(sorted(counts.items())),
                "total": len(viol),
+               "star_rules": sorted(star_rules()),
                "note": "Per-rule finding counts on OUR modules. Gate fails when any rises."},
               open(base_path, "w"), indent=2)
     open(base_path, "a").write("\n")
@@ -412,11 +436,22 @@ if not os.path.exists(base_path):
     write_last("ERROR-NO-BASELINE", viol, counts)
     sys.exit(2)
 
-base = json.load(open(base_path)).get("counts", {})
-rose, fell = [], []
+base_doc = json.load(open(base_path))
+base = base_doc.get("counts", {})
+known = base_doc.get("star_rules")
+stars = star_rules()
+base_mtime = os.path.getmtime(base_path)
+def first_seen(r):
+    if r in base or r not in stars:
+        return False
+    if known is not None:
+        return r not in known
+    return stars[r] > base_mtime
+rose, fell, new = [], [], []
 for r in sorted(set(counts) | set(base)):
     now, was = counts.get(r, 0), base.get(r, 0)
-    if now > was: rose.append((r, was, now))
+    if now > was and first_seen(r): new.append((r, now))
+    elif now > was: rose.append((r, was, now))
     elif now < was: fell.append((r, was, now))
 
 print("==> %d findings on our modules (baseline %d)" % (len(viol), sum(base.values())))
@@ -453,11 +488,20 @@ if collapsed:
     write_last("FAIL-COLLAPSE", viol, counts)
     sys.exit(1)
 
+if new:
+    print("\n!! NEW RULE(S), FIRST SEEN — not in the baseline, so not counted as a rise:")
+    for r, now in new:
+        print("   FIRST-SEEN %-8s %-8s %d finding(s) — new rule, first seen: review and re-baseline with --reason"
+              % (r, sev.get(r, "?"), now))
+        for v in [x for x in viol if x["ruleId"] == r][:3]:
+            print("        %s | %s" % (v.get("module") or "(project)", v["message"][:120]))
+    print("   Review them, then: bin/lint-gate.sh --update-baseline --reason \"<why these are accepted>\"")
+
 if not rose:
     print("\nPASS — nothing got worse.")
     if fell:
         print("       %d rule(s) improved. Run --update-baseline to lock the gain in." % len(fell))
-    write_last("PASS-BLIND" if blind else "PASS", viol, counts)
+    write_last("PASS-BLIND" if blind else ("PASS-FIRST-SEEN" if new else "PASS"), viol, counts)
     sys.exit(1 if blind else 0)
 
 print("\nFAIL — %d rule(s) got worse:\n" % len(rose))
diff --git a/tests/wave2/test-lint-gate-first-seen.sh b/tests/wave2/test-lint-gate-first-seen.sh
new file mode 100755
index 00000000..1142841e
--- /dev/null
+++ b/tests/wave2/test-lint-gate-first-seen.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Fixture for project-bin/lint-gate.sh FIRST-SEEN handling and exec.sh's row for it.
+#
+# Usage: bash test-lint-gate-first-seen.sh [path-to-lint-gate.sh]
+#
+# Review of #305 (Lint Batch 3), 2026-10-13: a rule sync-project.sh installs after the baseline
+# has no baseline count, so lint-gate compared it against 0 and its first hit was a "rise" —
+# every exec logged LINT ROSE and exited 1 until someone re-baselined, and TXT001/TXT002 fire on
+# ordinary text (TBD, XXX, v1.2, "12 Oct 2026"). Now such a rule is FIRST-SEEN: reported, rc 0.
+#
+# Rules under test are the toolkit's real .star files (their `RULE_ID = "..."` line is what
+# lint-gate reads). Lint output goes through LINT_JSON, using the key set of a real
+# `mxcli lint --format json` capture (same builder as test-lint-gate-accept.sh). No mxcli/.mpr.
+set -uo pipefail
+TK="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+GATE="${1:-$TK/project-bin/lint-gate.sh}"
+EXEC="$TK/project-bin/exec.sh"
+. "$TK/bin/lib/portable.sh"
+require_py
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/lint-first-seen.XXXXXX")"
+trap '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/^/       /'; }
+
+P="$WORK/proj"; mkdir -p "$P/bin" "$P/.claude/lint-rules"
+cp "$GATE" "$P/bin/lint-gate.sh"; [ -f "$TK/project-bin/_common.sh" ] && cp "$TK/project-bin/_common.sh" "$P/bin/"
+printf 'mpr' > "$P/App.mpr"; printf '#!/bin/sh\nexit 0\n' > "$P/mxcli"; chmod +x "$P/mxcli" "$P/bin/lint-gate.sh"
+R="$P/.claude/lint-rules"
+cp "$TK/lint-rules/conv010_act_microflow_content.star" "$TK/lint-rules/ux001_confirm_before_destructive.star" "$R/"
+
+v() { i=0; while [ "$i" -lt "$3" ]; do
+  printf '{"ruleId":"%s","severity":"%s","message":"finding %s","module":"Orders","document":"Doc%s","documentType":"microflow","documentId":"id-%s-%s","suggestion":"s"},' \
+    "$1" "$2" "$i" "$i" "$1" "$i"; i=$((i+1)); done; }
+mk() { printf '{"violations":[%s{"ruleId":"MPR001","severity":"warning","message":"m","module":"Orders","document":"E","documentType":"entity","documentId":"x","suggestion":"s"}],"summary":{}}' "$1" > "$WORK/lint.json"; }
+gate() { (cd "$P" && LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh "$@"); }
+fn="$WORK/run_lint_gate.sh"; sed -n '/^run_lint_gate() {/,/^}/p' "$EXEC" > "$fn"
+exec_detail() { (cd "$P" && PROJECT_ROOT="$P" LINT_JSON="$WORK/lint.json" bash -c ". '$fn'; LINT_RC=0; run_lint_gate >/dev/null; echo \"\$LINT_RC|\$LINT_DETAIL\""); }
+verdict() { "$PY" -c 'import json,sys;print(json.load(open(sys.argv[1]))["verdict"])' "$P/.claude/loop/lint-last.json"; }
+
+echo "F0 baseline before the new rule is installed (UX001 installed, zero findings)"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)"
+out=$(gate --update-baseline 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "baseline written" || bad "rc=$rc" "$out"
+"$PY" -c 'import json,sys;d=json.load(open(sys.argv[1]));sys.exit(0 if d.get("star_rules")==["CONV010","UX001"] else 1)' "$P/.claude/lint-baseline.json" \
+  && ok "baseline records star_rules [CONV010, UX001]" || bad "star_rules wrong" "$(cat "$P/.claude/lint-baseline.json")"
+
+echo "F1 sync installs TXT001; its findings are FIRST-SEEN, rc 0"
+cp "$TK/lint-rules/txt001_build_words_in_user_text.star" "$R/"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 5)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "rc 0" || bad "first-seen rule treated as a failure (rc $rc)" "$out"
+case "$out" in *"FIRST-SEEN TXT001"*"5 finding(s) — new rule, first seen: review and re-baseline with --reason"*) ok "first-seen line names TXT001 and its count" ;; *) bad "no first-seen line" "$out" ;; esac
+case "$out" in *"FAIL —"*) bad "reported as a rise" "$out" ;; *) ok "not reported as a rise" ;; esac
+[ "$(verdict)" = PASS-FIRST-SEEN ] && ok "lint-last verdict PASS-FIRST-SEEN" || bad "verdict $(verdict)"
+d=$(exec_detail)
+case "$d" in "0|lint unchanged vs baseline; FIRST-SEEN: TXT001 (5)"*) ok "exec row: ${d#*|}" ;; *) bad "exec row does not carry FIRST-SEEN" "$d" ;; esac
+
+echo "F2 an existing rule rising next to it is still a rise"
+mk "$(v CONV010 warning 6)$(v CONV009 info 2)$(v TXT001 info 5)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 1 ] && ok "rc 1" || bad "rc=$rc" "$out"
+case "$out" in *"CONV010  warning  4 -> 6"*) ok "CONV010 4 -> 6 reported" ;; *) bad "rise missing" "$out" ;; esac
+case "$(printf '%s\n' "$out" | sed -n '/^FAIL/,$p')" in *TXT001*) bad "TXT001 listed among the rises" "$out" ;; *) ok "TXT001 not listed as a rise" ;; esac
+
+echo "F3 a built-in rule absent from the baseline (was clean) is a rise, not first-seen"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v MDL001 info 1)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 1 ] && case "$out" in *"MDL001"*"0 -> 1"*) true ;; *) false ;; esac && ok "MDL001 0 -> 1 is a rise" || bad "built-in hit not a rise (rc $rc)" "$out"
+
+echo "F4 a .star rule known at baseline with zero findings is a rise when it fires"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v UX001 warning 1)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 1 ] && case "$out" in *"UX001"*"0 -> 1"*) true ;; *) false ;; esac && ok "UX001 0 -> 1 is a rise" || bad "known clean rule not ratcheted (rc $rc)" "$out"
+
+echo "F5 re-baselining a first-seen rule needs --reason; afterwards it is a normal rule"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 5)"
+out=$(gate --update-baseline 2>&1); rc=$?
+[ "$rc" -eq 2 ] && ok "refused without --reason" || bad "accepted without a reason (rc $rc)" "$out"
+out=$(gate --update-baseline --reason "TXT001 reviewed: 5 placeholder labels, fixed in slice 4" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "accepted with --reason" || bad "rc=$rc" "$out"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 7)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 1 ] && case "$out" in *"TXT001"*"5 -> 7"*) true ;; *) false ;; esac && ok "TXT001 5 -> 7 is now a rise" || bad "baselined rule not ratcheted (rc $rc)" "$out"
+
+echo "F6 a baseline written before star_rules existed: file mtime decides"
+"$PY" - "$P/.claude/lint-baseline.json" <<'PY'
+import json,sys
+d=json.load(open(sys.argv[1])); d.pop("star_rules",None); d["counts"].pop("TXT001",None)
+json.dump(d,open(sys.argv[1],"w"))
+PY
+"$PY" -c 'import os,sys,time;t=time.time();os.utime(sys.argv[1],(t-3600,t-3600));os.utime(sys.argv[2],(t-60,t-60));os.utime(sys.argv[3],(t-7200,t-7200))' \
+  "$P/.claude/lint-baseline.json" "$R/txt001_build_words_in_user_text.star" "$R/ux001_confirm_before_destructive.star"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 3)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 0 ] && case "$out" in *"FIRST-SEEN TXT001"*) true ;; *) false ;; esac && ok "star newer than baseline -> first-seen" || bad "legacy newer star not first-seen (rc $rc)" "$out"
+mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v UX001 warning 1)"
+out=$(gate 2>&1); rc=$?
+[ "$rc" -eq 1 ] && ok "star older than baseline -> rise" || bad "legacy older star not ratcheted (rc $rc)" "$out"
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

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 6/9] 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 456fe738f1875f87ec271a8e3bba8bf8ea055a7c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:02:51 +0000
Subject: [PATCH 7/9] Revert FIRST-SEEN (5432345): unsafe as built, redesign in
 a separate PR

Review put #308 on hold over it: the legacy fallback compares .star mtimes, which checkout,
sync and the #264 remedy all refresh, so real rises (bundled SEC004-SEC009 included) passed
rc 0; and even with star_rules a first-seen rule stayed rc 0 at any count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                             |   1 -
 project-bin/exec.sh                      |  10 +--
 project-bin/lint-gate.sh                 |  56 ++----------
 tests/wave2/test-lint-gate-first-seen.sh | 103 -----------------------
 4 files changed, 7 insertions(+), 163 deletions(-)
 delete mode 100755 tests/wave2/test-lint-gate-first-seen.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9509a509..7c0a17a4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,6 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(lint-gate): **a Starlark rule installed after the baseline is reported as FIRST-SEEN, not as a rise** ([#305](https://github.com/MendixMau/mxcli-project-toolkit/pull/305) review). A rule sync installs has no baseline count, so its first hit compared against 0: every exec logged `LINT ROSE` and exited 1 until someone re-baselined, and the Lint Batch 3 rules fire on ordinary text (TBD, XXX, v1.2, "12 Oct 2026"). Now a `.star` rule (`RULE_ID = "..."` in `.claude/lint-rules/`) that the baseline did not know prints `FIRST-SEEN <rule> N finding(s) — new rule, first seen: review and re-baseline with --reason`, exits 0 (verdict `PASS-FIRST-SEEN`, exec.sh row `FIRST-SEEN: <rule> (N)`), and is an ordinary ratcheted rule after the next `--update-baseline --reason`. `--update-baseline` now records `star_rules`; for an older baseline the `.star` file being newer than it decides. Built-in rules and `.star` rules known at baseline with zero findings still rise. Fixture `tests/wave2/test-lint-gate-first-seen.sh`: 17/17 here, 8 fail on master's lint-gate. — MendixMau (review of #305)
 - fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a rule whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or that is missing, is named, the remedy `bin/sync-project.sh <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the printed remedy always clears it, `bin/lib/install-lint-rules.sh` now restores a rule whose receipt row exists and whose header is gone even when its stock hash is not in `STOCK-HASHES.txt` (an mxcli upgrade, then init; it was reported LOCALLY MODIFIED and never written), prunes receipt rows for rules no longer shipped, and honours a new `.claude/lint-rules-disabled.txt` opt-out that lint-gate also reads (`lint-rules/README.md` told projects to delete txt002, which would now read as a re-seed). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 38/38 here, 21 fail on master's lint-gate and installer. — AlvinnYeo
 - learn(learned-mdl-preflight): **a microflow change near a `return` in a dense flow is planned as drop + create after `show access`; `check -p --references` does not run exec's free-room test** ([#263](https://github.com/MendixMau/mxcli-project-toolkit/issues/263)). STOP row 28 and BUG-156: on v0.25.0 `check` printed "no flow change exec would refuse" and exec then refused "there is no free room for the fragment". Upstream issue drafted, not filed. — AlvinnYeo
 - 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/project-bin/exec.sh b/project-bin/exec.sh
index 09043ac9..a84446de 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -753,15 +753,7 @@ run_lint_gate() {
   LINT_RC=0
   bash "$PROJECT_ROOT/bin/lint-gate.sh" >"$_lo" 2>&1 || LINT_RC=$?
   case "$LINT_RC" in
-    0) LINT_DETAIL="lint unchanged vs baseline"; echo "  ✓ lint: no rule rose vs baseline"
-       # A rule installed after the baseline is FIRST-SEEN, not a rise (#305 review): say it on
-       # the row, so the count is reviewed and re-baselined rather than found later.
-       _new=$(grep -E '^ +FIRST-SEEN [A-Z][A-Z0-9-]*[0-9]+ ' "$_lo" | awk '{printf "%s%s (%s)", (n++?", ":""), $2, $4}')
-       if [ -n "$_new" ]; then
-         LINT_DETAIL="lint unchanged vs baseline; FIRST-SEEN: $_new — review, re-baseline with --reason"
-         echo "  ⚠ lint: new rule(s) first seen, not counted as a rise: $_new"
-         echo "    Review the findings, then: bin/lint-gate.sh --update-baseline --reason \"<why>\""
-       fi ;;
+    0) LINT_DETAIL="lint unchanged vs baseline"; echo "  ✓ lint: no rule rose vs baseline" ;;
     1) # Rule ids are matched as [A-Z][A-Z0-9-]*[0-9]+, not [A-Z]+[0-9]+: mxcli's built-in
        # rules include hyphenated ids (MDL-FLOW01), and the old pattern dropped them from every
        # row — three field apps logged 475 ROSE rows and not one named MDL-FLOW01 (2026-10-12).
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index f761fe0e..eca387c1 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -18,8 +18,7 @@
 #       --approved-in-chat              # ALSO required when a security-tier rule rises
 #   bin/lint-gate.sh --full             # ignore the vendor exclusion (rarely useful)
 #
-# Exit codes: 0 clean, unchanged, or only FIRST-SEEN rules (a .star rule installed after the
-#             baseline: reported, not a rise — #305 review) · 1 a rule increased, or BLIND (a rule inspected nothing,
+# Exit codes: 0 clean or unchanged · 1 a rule increased, or BLIND (a rule inspected nothing,
 #             or the toolkit rules reverted to stock — see below) · 2 could not run (or a
 #             refused update)
 #
@@ -131,7 +130,7 @@ while [ $# -gt 0 ]; do
               REASON="$2"; shift ;;
     --reason=*) REASON="${1#--reason=}" ;;
     --approved-in-chat) APPROVED=1 ;;
-    -h|--help) sed -n '2,63p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,62p' "$0"; exit 0 ;;
     *) echo "lint-gate: unknown argument '$1'" >&2; exit 2 ;;
   esac
   shift
@@ -309,28 +308,6 @@ except (ValueError, IndexError):
     sys.exit(2)
 
 viol = data.get("violations") or []
-
-# FIRST-SEEN (#305 review). A rule sync-project.sh installs AFTER the baseline was taken has no
-# baseline count, so it compared against 0 and its first hit was a "rise": every exec logged
-# LINT ROSE and exited 1 until someone re-baselined (Lint Batch 3's TXT001/TXT002 fire on TBD,
-# XXX, v1.2, "12 Oct 2026"). A rule absent from the baseline counts is FIRST-SEEN, not a rise,
-# when it is a Starlark rule in .claude/lint-rules/ (`RULE_ID = "..."`) that the baseline did not
-# know: listed in neither its counts nor its `star_rules` (written by --update-baseline from now
-# on); for an older baseline without `star_rules`, its .star file is newer than the baseline.
-# Built-in mxcli rules are never first-seen: a baseline omits a rule with zero findings, so
-# "absent" there means "was clean" and a hit is a real rise.
-import re, glob
-def star_rules():
-    out = {}
-    rdir = os.path.join(os.path.dirname(base_path), "lint-rules")
-    for f in glob.glob(os.path.join(rdir, "*.star")):
-        try:
-            m = re.search(r'^RULE_ID\s*=\s*"([^"]+)"', open(f, encoding="utf-8", errors="replace").read(), re.M)
-        except OSError:
-            continue
-        if m:
-            out[m.group(1)] = os.path.getmtime(f)
-    return out
 counts = collections.Counter(v["ruleId"] for v in viol)
 sev    = {v["ruleId"]: v["severity"] for v in viol}
 
@@ -420,7 +397,6 @@ if update:
             sys.exit(2)
     json.dump({"counts": dict(sorted(counts.items())),
                "total": len(viol),
-               "star_rules": sorted(star_rules()),
                "note": "Per-rule finding counts on OUR modules. Gate fails when any rises."},
               open(base_path, "w"), indent=2)
     open(base_path, "a").write("\n")
@@ -436,22 +412,11 @@ if not os.path.exists(base_path):
     write_last("ERROR-NO-BASELINE", viol, counts)
     sys.exit(2)
 
-base_doc = json.load(open(base_path))
-base = base_doc.get("counts", {})
-known = base_doc.get("star_rules")
-stars = star_rules()
-base_mtime = os.path.getmtime(base_path)
-def first_seen(r):
-    if r in base or r not in stars:
-        return False
-    if known is not None:
-        return r not in known
-    return stars[r] > base_mtime
-rose, fell, new = [], [], []
+base = json.load(open(base_path)).get("counts", {})
+rose, fell = [], []
 for r in sorted(set(counts) | set(base)):
     now, was = counts.get(r, 0), base.get(r, 0)
-    if now > was and first_seen(r): new.append((r, now))
-    elif now > was: rose.append((r, was, now))
+    if now > was: rose.append((r, was, now))
     elif now < was: fell.append((r, was, now))
 
 print("==> %d findings on our modules (baseline %d)" % (len(viol), sum(base.values())))
@@ -488,20 +453,11 @@ if collapsed:
     write_last("FAIL-COLLAPSE", viol, counts)
     sys.exit(1)
 
-if new:
-    print("\n!! NEW RULE(S), FIRST SEEN — not in the baseline, so not counted as a rise:")
-    for r, now in new:
-        print("   FIRST-SEEN %-8s %-8s %d finding(s) — new rule, first seen: review and re-baseline with --reason"
-              % (r, sev.get(r, "?"), now))
-        for v in [x for x in viol if x["ruleId"] == r][:3]:
-            print("        %s | %s" % (v.get("module") or "(project)", v["message"][:120]))
-    print("   Review them, then: bin/lint-gate.sh --update-baseline --reason \"<why these are accepted>\"")
-
 if not rose:
     print("\nPASS — nothing got worse.")
     if fell:
         print("       %d rule(s) improved. Run --update-baseline to lock the gain in." % len(fell))
-    write_last("PASS-BLIND" if blind else ("PASS-FIRST-SEEN" if new else "PASS"), viol, counts)
+    write_last("PASS-BLIND" if blind else "PASS", viol, counts)
     sys.exit(1 if blind else 0)
 
 print("\nFAIL — %d rule(s) got worse:\n" % len(rose))
diff --git a/tests/wave2/test-lint-gate-first-seen.sh b/tests/wave2/test-lint-gate-first-seen.sh
deleted file mode 100755
index 1142841e..00000000
--- a/tests/wave2/test-lint-gate-first-seen.sh
+++ /dev/null
@@ -1,103 +0,0 @@
-#!/usr/bin/env bash
-# Fixture for project-bin/lint-gate.sh FIRST-SEEN handling and exec.sh's row for it.
-#
-# Usage: bash test-lint-gate-first-seen.sh [path-to-lint-gate.sh]
-#
-# Review of #305 (Lint Batch 3), 2026-10-13: a rule sync-project.sh installs after the baseline
-# has no baseline count, so lint-gate compared it against 0 and its first hit was a "rise" —
-# every exec logged LINT ROSE and exited 1 until someone re-baselined, and TXT001/TXT002 fire on
-# ordinary text (TBD, XXX, v1.2, "12 Oct 2026"). Now such a rule is FIRST-SEEN: reported, rc 0.
-#
-# Rules under test are the toolkit's real .star files (their `RULE_ID = "..."` line is what
-# lint-gate reads). Lint output goes through LINT_JSON, using the key set of a real
-# `mxcli lint --format json` capture (same builder as test-lint-gate-accept.sh). No mxcli/.mpr.
-set -uo pipefail
-TK="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-GATE="${1:-$TK/project-bin/lint-gate.sh}"
-EXEC="$TK/project-bin/exec.sh"
-. "$TK/bin/lib/portable.sh"
-require_py
-WORK="$(mktemp -d "${TMPDIR:-/tmp}/lint-first-seen.XXXXXX")"
-trap '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/^/       /'; }
-
-P="$WORK/proj"; mkdir -p "$P/bin" "$P/.claude/lint-rules"
-cp "$GATE" "$P/bin/lint-gate.sh"; [ -f "$TK/project-bin/_common.sh" ] && cp "$TK/project-bin/_common.sh" "$P/bin/"
-printf 'mpr' > "$P/App.mpr"; printf '#!/bin/sh\nexit 0\n' > "$P/mxcli"; chmod +x "$P/mxcli" "$P/bin/lint-gate.sh"
-R="$P/.claude/lint-rules"
-cp "$TK/lint-rules/conv010_act_microflow_content.star" "$TK/lint-rules/ux001_confirm_before_destructive.star" "$R/"
-
-v() { i=0; while [ "$i" -lt "$3" ]; do
-  printf '{"ruleId":"%s","severity":"%s","message":"finding %s","module":"Orders","document":"Doc%s","documentType":"microflow","documentId":"id-%s-%s","suggestion":"s"},' \
-    "$1" "$2" "$i" "$i" "$1" "$i"; i=$((i+1)); done; }
-mk() { printf '{"violations":[%s{"ruleId":"MPR001","severity":"warning","message":"m","module":"Orders","document":"E","documentType":"entity","documentId":"x","suggestion":"s"}],"summary":{}}' "$1" > "$WORK/lint.json"; }
-gate() { (cd "$P" && LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh "$@"); }
-fn="$WORK/run_lint_gate.sh"; sed -n '/^run_lint_gate() {/,/^}/p' "$EXEC" > "$fn"
-exec_detail() { (cd "$P" && PROJECT_ROOT="$P" LINT_JSON="$WORK/lint.json" bash -c ". '$fn'; LINT_RC=0; run_lint_gate >/dev/null; echo \"\$LINT_RC|\$LINT_DETAIL\""); }
-verdict() { "$PY" -c 'import json,sys;print(json.load(open(sys.argv[1]))["verdict"])' "$P/.claude/loop/lint-last.json"; }
-
-echo "F0 baseline before the new rule is installed (UX001 installed, zero findings)"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)"
-out=$(gate --update-baseline 2>&1); rc=$?
-[ "$rc" -eq 0 ] && ok "baseline written" || bad "rc=$rc" "$out"
-"$PY" -c 'import json,sys;d=json.load(open(sys.argv[1]));sys.exit(0 if d.get("star_rules")==["CONV010","UX001"] else 1)' "$P/.claude/lint-baseline.json" \
-  && ok "baseline records star_rules [CONV010, UX001]" || bad "star_rules wrong" "$(cat "$P/.claude/lint-baseline.json")"
-
-echo "F1 sync installs TXT001; its findings are FIRST-SEEN, rc 0"
-cp "$TK/lint-rules/txt001_build_words_in_user_text.star" "$R/"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 5)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 0 ] && ok "rc 0" || bad "first-seen rule treated as a failure (rc $rc)" "$out"
-case "$out" in *"FIRST-SEEN TXT001"*"5 finding(s) — new rule, first seen: review and re-baseline with --reason"*) ok "first-seen line names TXT001 and its count" ;; *) bad "no first-seen line" "$out" ;; esac
-case "$out" in *"FAIL —"*) bad "reported as a rise" "$out" ;; *) ok "not reported as a rise" ;; esac
-[ "$(verdict)" = PASS-FIRST-SEEN ] && ok "lint-last verdict PASS-FIRST-SEEN" || bad "verdict $(verdict)"
-d=$(exec_detail)
-case "$d" in "0|lint unchanged vs baseline; FIRST-SEEN: TXT001 (5)"*) ok "exec row: ${d#*|}" ;; *) bad "exec row does not carry FIRST-SEEN" "$d" ;; esac
-
-echo "F2 an existing rule rising next to it is still a rise"
-mk "$(v CONV010 warning 6)$(v CONV009 info 2)$(v TXT001 info 5)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 1 ] && ok "rc 1" || bad "rc=$rc" "$out"
-case "$out" in *"CONV010  warning  4 -> 6"*) ok "CONV010 4 -> 6 reported" ;; *) bad "rise missing" "$out" ;; esac
-case "$(printf '%s\n' "$out" | sed -n '/^FAIL/,$p')" in *TXT001*) bad "TXT001 listed among the rises" "$out" ;; *) ok "TXT001 not listed as a rise" ;; esac
-
-echo "F3 a built-in rule absent from the baseline (was clean) is a rise, not first-seen"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v MDL001 info 1)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 1 ] && case "$out" in *"MDL001"*"0 -> 1"*) true ;; *) false ;; esac && ok "MDL001 0 -> 1 is a rise" || bad "built-in hit not a rise (rc $rc)" "$out"
-
-echo "F4 a .star rule known at baseline with zero findings is a rise when it fires"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v UX001 warning 1)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 1 ] && case "$out" in *"UX001"*"0 -> 1"*) true ;; *) false ;; esac && ok "UX001 0 -> 1 is a rise" || bad "known clean rule not ratcheted (rc $rc)" "$out"
-
-echo "F5 re-baselining a first-seen rule needs --reason; afterwards it is a normal rule"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 5)"
-out=$(gate --update-baseline 2>&1); rc=$?
-[ "$rc" -eq 2 ] && ok "refused without --reason" || bad "accepted without a reason (rc $rc)" "$out"
-out=$(gate --update-baseline --reason "TXT001 reviewed: 5 placeholder labels, fixed in slice 4" 2>&1); rc=$?
-[ "$rc" -eq 0 ] && ok "accepted with --reason" || bad "rc=$rc" "$out"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 7)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 1 ] && case "$out" in *"TXT001"*"5 -> 7"*) true ;; *) false ;; esac && ok "TXT001 5 -> 7 is now a rise" || bad "baselined rule not ratcheted (rc $rc)" "$out"
-
-echo "F6 a baseline written before star_rules existed: file mtime decides"
-"$PY" - "$P/.claude/lint-baseline.json" <<'PY'
-import json,sys
-d=json.load(open(sys.argv[1])); d.pop("star_rules",None); d["counts"].pop("TXT001",None)
-json.dump(d,open(sys.argv[1],"w"))
-PY
-"$PY" -c 'import os,sys,time;t=time.time();os.utime(sys.argv[1],(t-3600,t-3600));os.utime(sys.argv[2],(t-60,t-60));os.utime(sys.argv[3],(t-7200,t-7200))' \
-  "$P/.claude/lint-baseline.json" "$R/txt001_build_words_in_user_text.star" "$R/ux001_confirm_before_destructive.star"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v TXT001 info 3)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 0 ] && case "$out" in *"FIRST-SEEN TXT001"*) true ;; *) false ;; esac && ok "star newer than baseline -> first-seen" || bad "legacy newer star not first-seen (rc $rc)" "$out"
-mk "$(v CONV010 warning 4)$(v CONV009 info 2)$(v UX001 warning 1)"
-out=$(gate 2>&1); rc=$?
-[ "$rc" -eq 1 ] && ok "star older than baseline -> rise" || bad "legacy older star not ratcheted (rc $rc)" "$out"
-
-echo ""
-echo "PASS=$PASS FAIL=$FAIL"
-[ "$FAIL" -eq 0 ]

From b5b73e47d849517c3947d1bcd79951c52e3b5c3a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:13:03 +0000
Subject: [PATCH 8/9] fix(lint-rules): re-seed check scoped to stock-seeded
 rules; opt-out needs a reason and refuses stock rules (#264 review 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The REVERTED path (installer restore and lint-gate BLIND) applies only to
  MXTK_LINT_RULES_STOCK, the file names `mxcli init` seeds. A headerless toolkit-only rule
  (ux001, txt*) or configurable conv020 is a local edit: still LOCALLY MODIFIED / configured,
  never overwritten, not BLIND. The receipt row gains a kind column (stock | toolkit |
  configurable) so lint-gate, which has no manifest, can tell; rows without one are healed by
  the next sync and not checked until then. A receipt-listed rule that is missing is still
  reported for every kind.
- One header test in both: anchored `^# mxtk-lint-rule:` (lint-gate used a substring match).
- .claude/lint-rules-disabled.txt: each line needs `# reason: …` (a user decision, asked in chat
  and recorded in PROJECT.md); a line with no reason, or naming a stock-seeded rule, is ignored
  with a warning by both the installer and lint-gate. The BLIND message no longer suggests
  opting out. lint-rules/README.md rewritten to match (CONV010 cannot be opted out).
- The installer no longer advises adding a project's hash to STOCK-HASHES.txt.
- tests/wave2/test-lint-receipt-revert.sh: kinds in the receipt (T0), reasonless and reasoned
  opt-out (T10), stock opt-out refused (T12), headerless ux001 and configured headerless conv020
  not overwritten and not BLIND (T13, T14). 51/51 here; 14 fail with master's installer, 25 with
  master's installer and lint-gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                            |   2 +-
 bin/lib/install-lint-rules.sh           | 104 +++++++++++++++++-------
 lint-rules/README.md                    |  37 ++++++---
 project-bin/lint-gate.sh                |  61 +++++++++-----
 skills/lint-that-actually-runs.md       |   2 +-
 tests/wave2/test-lint-receipt-revert.sh |  55 +++++++++++--
 6 files changed, 190 insertions(+), 71 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c0a17a4..3ef833cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a rule whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or that is missing, is named, the remedy `bin/sync-project.sh <project>` is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the printed remedy always clears it, `bin/lib/install-lint-rules.sh` now restores a rule whose receipt row exists and whose header is gone even when its stock hash is not in `STOCK-HASHES.txt` (an mxcli upgrade, then init; it was reported LOCALLY MODIFIED and never written), prunes receipt rows for rules no longer shipped, and honours a new `.claude/lint-rules-disabled.txt` opt-out that lint-gate also reads (`lint-rules/README.md` told projects to delete txt002, which would now read as a re-seed). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 38/38 here, 21 fail on master's lint-gate and installer. — AlvinnYeo
+- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a stock-seeded rule (the file names `mxcli init` writes, now marked `stock` in the receipt) whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or any receipt-listed rule that is missing, is named, the remedy `bin/sync-project.sh <project>` (fallback `--upgrade-lint-rules all`) is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the remedy always clears it, `bin/lib/install-lint-rules.sh` restores such a stock-seeded rule even when this mxcli's stock hash is not in `STOCK-HASHES.txt` yet (it was reported LOCALLY MODIFIED and never written); a headerless toolkit-only or configurable rule is still a local edit, never overwritten. The installer also writes each receipt row's kind, prunes rows for rules no longer shipped, and honours `.claude/lint-rules-disabled.txt`: one line per rule with `# reason: …`, a user decision recorded in `PROJECT.md`; a line with no reason, or naming a stock-seeded rule, is ignored with a warning (`lint-rules/README.md` had told projects to just delete txt002). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 51/51 here, 25 fail on master's lint-gate and installer. — AlvinnYeo
 - learn(learned-mdl-preflight): **a microflow change near a `return` in a dense flow is planned as drop + create after `show access`; `check -p --references` does not run exec's free-room test** ([#263](https://github.com/MendixMau/mxcli-project-toolkit/issues/263)). STOP row 28 and BUG-156: on v0.25.0 `check` printed "no flow change exec would refuse" and exec then refused "there is no free room for the fragment". Upstream issue drafted, not filed. — AlvinnYeo
 - 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
diff --git a/bin/lib/install-lint-rules.sh b/bin/lib/install-lint-rules.sh
index c864520a..633fd1b9 100644
--- a/bin/lib/install-lint-rules.sh
+++ b/bin/lib/install-lint-rules.sh
@@ -95,63 +95,106 @@ _mxtk_lint_receipt_get() {
   return 1
 }
 
+# The receipt row is `<rule-file>  <md5>  <kind>`. kind is where the rule comes from, read from
+# install-manifest.sh: `stock` (MXTK_LINT_RULES_STOCK — `mxcli init` also seeds this file name,
+# so a headerless copy is a re-seed), `toolkit` (toolkit-only; init never writes it, so a
+# headerless copy is a person's edit) or `configurable` (edited by design). lint-gate.sh reads the
+# kind, since a project has no manifest; a row without one (written before kinds existed) is
+# healed by the next sync and is not checked by lint-gate until then.
+_mxtk_lint_kind() {
+  case " ${MXTK_LINT_RULES_STOCK:-} " in *" $1 "*) echo stock; return ;; esac
+  case " ${MXTK_LINT_RULES_CONFIGURABLE:-} " in *" $1 "*) echo configurable; return ;; esac
+  echo toolkit
+}
+
 # Rewrite one receipt line. Read-all/write-all rather than append, so re-installing a rule
 # does not leave two rows for it and let a stale one win the lookup above.
 _mxtk_lint_receipt_set() {
   _receipt="$1"; _f="$2"; _md5="$3"
   _tmp="$_receipt.tmp.$$"
   {
-    printf '# md5 of each toolkit lint rule AS INSTALLED. Written by bin/lib/install-lint-rules.sh.\n'
+    printf '# md5 of each toolkit lint rule AS INSTALLED, and its kind. Written by bin/lib/install-lint-rules.sh.\n'
     printf '# Do not edit. Deleting this file makes a revert-to-stock look like a first install.\n'
     if [ -f "$_receipt" ]; then
       while read -r _n _m _r; do
         case "$_n" in ''|'#'*) continue ;; esac
         [ "$_n" = "$_f" ] && continue
-        printf '%s  %s\n' "$_n" "$_m"
+        printf '%s  %s%s\n' "$_n" "$_m" "${_r:+  $_r}"
       done < "$_receipt"
     fi
-    printf '%s  %s\n' "$_f" "$_md5"
+    printf '%s  %s  %s\n' "$_f" "$_md5" "$(_mxtk_lint_kind "$_f")"
   } > "$_tmp" && mv "$_tmp" "$_receipt"
 }
 
-# DELIBERATE OPT-OUT. .claude/lint-rules-disabled.txt, one rule file per line ('#' comments).
-# A rule listed there is never installed or restored, and its receipt row is pruned, so
-# deleting it is not undone by the next sync and lint-gate.sh (which reads the same file) does
-# not report the deletion as a re-seed. Deleting a rule without listing it is what `mxcli init`
-# does, and is treated as such.
+# DELIBERATE OPT-OUT — a user decision, not an agent's. .claude/lint-rules-disabled.txt holds
+# one rule per line, each WITH its reason:
+#     txt002_non_iso_date_in_user_text.star  # reason: display standard is dd/MM/yyyy (PROJECT.md D-14)
+# The decision is asked in chat and recorded in PROJECT.md; the line here is what the tools
+# read. A listed rule is never installed or restored and its receipt row is pruned, and
+# lint-gate.sh does not report it gone. Refused, with a warning, and the line ignored:
+#   - a line with no `# reason:` text;
+#   - a stock-seeded rule (MXTK_LINT_RULES_STOCK). `mxcli init` writes a stock copy of that file
+#     name back, and the stock rules report a clean pass while inspecting nothing — an opt-out
+#     would turn that into a permanent silent green.
+# _mxtk_lint_is_disabled answers for one rule; _mxtk_lint_disabled_audit warns once per bad line.
+_mxtk_lint_dis_ok() {  # $1 = rule, $2 = rest of the line -> 0 when the line is a valid opt-out
+  case " ${MXTK_LINT_RULES_STOCK:-} " in *" $1 "*) return 1 ;; esac
+  _dis_why="${2#*# reason:}"
+  [ "$_dis_why" != "$2" ] || return 1
+  [ -n "$(printf '%s' "$_dis_why" | tr -d '[:space:]')" ]
+}
 _mxtk_lint_is_disabled() {
   # Own variable names: callers loop with _n/_m/_f, and these are not `local` (POSIX sh).
   _dis_file="$1"; _dis_want="$2"
   [ -f "$_dis_file" ] || return 1
   while read -r _dis_n _dis_rest; do
     case "$_dis_n" in ''|'#'*) continue ;; esac
-    [ "$_dis_n" = "$_dis_want" ] && return 0
+    [ "$_dis_n" = "$_dis_want" ] && _mxtk_lint_dis_ok "$_dis_n" "$_dis_rest" && return 0
   done < "$_dis_file"
   return 1
 }
+_mxtk_lint_disabled_audit() {
+  _dis_file="$1"
+  [ -f "$_dis_file" ] || return 0
+  while read -r _dis_n _dis_rest; do
+    case "$_dis_n" in ''|'#'*) continue ;; esac
+    _mxtk_lint_dis_ok "$_dis_n" "$_dis_rest" && continue
+    case " ${MXTK_LINT_RULES_STOCK:-} " in
+      *" $_dis_n "*) _mxtk_lint_warn \
+        ".claude/lint-rules-disabled.txt: $_dis_n cannot be disabled — IGNORED." \
+        "\`mxcli init\` re-seeds a stock copy of it, which reports a clean pass while inspecting" \
+        "nothing. The rule stays installed. Remove the line." ;;
+      *) _mxtk_lint_warn \
+        ".claude/lint-rules-disabled.txt: $_dis_n has no '# reason: …' — IGNORED, the rule stays installed." \
+        "Disabling a rule is the user's decision: ask in chat, record it in PROJECT.md, then write" \
+        "  $_dis_n  # reason: <why, and where it is recorded>" ;;
+    esac
+  done < "$_dis_file"
+}
 
-# Drop receipt rows for rules this toolkit no longer ships, or that the project disabled.
-# A stale row would make lint-gate.sh report the rule "gone" on every run, forever.
-_mxtk_lint_receipt_prune() {
+# Rewrite the receipt to the current manifest: rows for rules no longer shipped, or validly
+# disabled here, are dropped (a stale row would make lint-gate.sh report the rule "gone" on every
+# run, forever), and every kept row carries its kind. Written only when something changed.
+_mxtk_lint_receipt_finalize() {
   _receipt="$1"; _keep=" $2 "; _dis="$3"
   [ -f "$_receipt" ] || return 0
   _pruned=""; _tmp="$_receipt.tmp.$$"
   {
-    printf '# md5 of each toolkit lint rule AS INSTALLED. Written by bin/lib/install-lint-rules.sh.\n'
+    printf '# md5 of each toolkit lint rule AS INSTALLED, and its kind. Written by bin/lib/install-lint-rules.sh.\n'
     printf '# Do not edit. Deleting this file makes a revert-to-stock look like a first install.\n'
     while read -r _n _m _r; do
       case "$_n" in ''|'#'*) continue ;; esac
       case "$_keep" in *" $_n "*) ;; *) _pruned="$_pruned $_n"; continue ;; esac
       if _mxtk_lint_is_disabled "$_dis" "$_n"; then _pruned="$_pruned $_n"; continue; fi
-      printf '%s  %s\n' "$_n" "$_m"
+      printf '%s  %s  %s\n' "$_n" "$_m" "$(_mxtk_lint_kind "$_n")"
     done < "$_receipt"
   } > "$_tmp"
-  if [ -n "$_pruned" ]; then
-    mv "$_tmp" "$_receipt"
-    echo "Lint receipt: dropped row(s) for rules no longer shipped or disabled here:$_pruned"
-  else
+  if cmp -s "$_tmp" "$_receipt"; then
     rm -f "$_tmp"
+  else
+    mv "$_tmp" "$_receipt"
   fi
+  [ -z "$_pruned" ] || echo "Lint receipt: dropped row(s) for rules no longer shipped or disabled here:$_pruned"
 }
 
 mxtk_install_lint_rules() {
@@ -192,6 +235,7 @@ mxtk_install_lint_rules() {
     fi
   fi
 
+  _mxtk_lint_disabled_audit "$_disabled"
   _drifted=""
   for _kind in managed configurable; do
     if [ "$_kind" = managed ]; then _list="${MXTK_LINT_RULES:-}"; else _list="${MXTK_LINT_RULES_CONFIGURABLE:-}"; fi
@@ -282,22 +326,24 @@ mxtk_install_lint_rules() {
         continue
       fi
 
-      # ---- installed by us, header gone, stock hash not on file -----------------------
-      # The receipt says we installed this file, and the provenance header is gone. That is
-      # a re-seed by an mxcli version STOCK-HASHES.txt does not list yet (an upgrade, then
-      # init), not a hand edit: a hand edit keeps the header. The same test lint-gate.sh uses
-      # to declare the run BLIND, so the remedy it prints (sync) actually clears it (#264
-      # review: without this branch the file was reported LOCALLY MODIFIED and never written,
-      # and lint stayed BLIND forever). The found file is kept beside it, not loaded by lint.
-      if [ -n "$_rec" ] && ! grep -q '^# mxtk-lint-rule:' "$_dst"; then
-        _why="REVERTED TO STOCK — header gone and its hash is not in STOCK-HASHES.txt (newer mxcli?). Restoring it"
+      # ---- stock-seedable, installed by us, header gone, stock hash not on file --------
+      # Only for MXTK_LINT_RULES_STOCK: `mxcli init` seeds those file names, so with the receipt
+      # saying we installed it and the provenance header gone, this is a re-seed by an mxcli
+      # version STOCK-HASHES.txt does not list yet (an upgrade, then init) — not a hand edit.
+      # Without this branch it was reported LOCALLY MODIFIED and never written, and lint-gate.sh,
+      # which applies the same test, stayed BLIND forever (#264 review). Toolkit-only and
+      # configurable rules are never seeded by init: a headerless copy of one is a person's edit
+      # and falls through to the LOCALLY MODIFIED / configured branches below, never overwritten.
+      # The found file is kept beside it; lint loads *.star only.
+      if [ -n "$_rec" ] && [ "$(_mxtk_lint_kind "$_f")" = stock ] && ! grep -q '^# mxtk-lint-rule:' "$_dst"; then
+        _why="REVERTED TO STOCK — header gone; this mxcli's stock hash is not in STOCK-HASHES.txt yet. Restoring it"
         if [ "$_dry" -eq 1 ]; then
           echo "Would install: .claude/lint-rules/$_f ($_why)"
         else
           _bak="$_dst.reseeded-$(date +%Y%m%d%H%M%S)"
           cp "$_dst" "$_bak"
           cp "$_src" "$_dst" && _mxtk_lint_receipt_set "$_receipt" "$_f" "$_srcmd5"
-          echo "Lint rule: $_why — .claude/lint-rules/$_f (found copy kept at $(basename "$_bak"); md5 $_dstmd5 — add it to STOCK-HASHES.txt if it is a stock seed)"
+          echo "Lint rule: $_why — .claude/lint-rules/$_f (the file found is kept at $(basename "$_bak"))"
         fi
         MXTK_LINT_CHANGES=$((MXTK_LINT_CHANGES + 1))
         continue
@@ -346,7 +392,7 @@ mxtk_install_lint_rules() {
   if [ -n "$_drifted" ] && [ -z "$_upg" ]; then
     echo "   (upgrade every drifted lint rule at once with: --upgrade-lint-rules all)"
   fi
-  [ "$_dry" -eq 1 ] || _mxtk_lint_receipt_prune "$_receipt" \
+  [ "$_dry" -eq 1 ] || _mxtk_lint_receipt_finalize "$_receipt" \
     "${MXTK_LINT_RULES:-} ${MXTK_LINT_RULES_CONFIGURABLE:-}" "$_disabled"
   return 0
 }
diff --git a/lint-rules/README.md b/lint-rules/README.md
index 672e033a..f8e5118b 100644
--- a/lint-rules/README.md
+++ b/lint-rules/README.md
@@ -18,7 +18,7 @@ and configure the marked constants — **after** running `mxcli init`, never bef
 | `perf002_nested_data_widgets.star` | PERF002 — a data view / list view / data grid / gallery nested inside two or more other data widgets on the same page: re-queries per row at every level | `MAX_NESTING`, `DATA_WIDGET_CANDIDATES`, `EXCLUDE` (widget_type vocabulary: probe first) |
 | `perf004_npe_system_user_assoc.star` | PERF004 — an association between a non-persistable entity and System.User / System.Session (or an entity generalizing them), which pins session objects to the shared side | `NON_PERSISTABLE_CANDIDATES`, `SYSTEM_TARGETS` (entity_type vocabulary: probe first) |
 | `txt001_build_words_in_user_text.star` | TXT001 — user-visible text (titles, captions, templates, messages, menu items) holding build-process words: `Stage N`, `BR-10`, `F004`, TODO, a version tag, "(local, …)" | `PROJECT_WORDS` (sibling-app and project code names); `LEAK_PATTERNS` if "Stage N" is a real domain word |
-| `txt002_non_iso_date_in_user_text.star` | TXT002 — user-visible text holding a non-ISO literal date (10/12/2026, 12 Oct 2026) or a day/month format pattern (dd MMM, MM/dd); blind to format strings inside expressions | no — to opt out (display standard is not ISO), list it in `.claude/lint-rules-disabled.txt`, then delete it |
+| `txt002_non_iso_date_in_user_text.star` | TXT002 — user-visible text holding a non-ISO literal date (10/12/2026, 12 Oct 2026) or a day/month format pattern (dd MMM, MM/dd); blind to format strings inside expressions | no — if the display standard is not ISO, the user may opt out: see "Opting out of a rule" |
 | `ui001_widget_layout_traps.star` | UI001 — a list view inside a Data grid 2 column (its own "Load more" / "No items found" in every cell); an inline `width` on an Atlas input without `flex` (ignored) | `DATAGRID_TYPES`, `LISTVIEW_TYPES`, `INPUT_TYPES` (widget_type vocabulary: probe first) |
 
 `err001` and `loop001` first field count (2026-10-12, mxcli 0.26.0, 21-module Mendix 11.12 model,
@@ -106,18 +106,31 @@ fixture on TestCLIApp — setting `ACTION_PREFIX` to an unused string produces t
 the real prefix produces none. `bin/lint-gate.sh` treats `module == "_rule"` as blindness, so
 this turns a silent pass into a gate failure rather than a line in a report nobody reads.
 
-Set `ACTION_PREFIX` / `DELEGATE_PREFIX` to your project's prefixes. If the project has no such
-convention, opt out deliberately rather than leaving it inert: list the file in
-`.claude/lint-rules-disabled.txt`, then delete it (see "Opting out of a rule" below).
+Set `ACTION_PREFIX` / `DELEGATE_PREFIX` to your project's prefixes. CONV010 cannot be opted out
+(`mxcli init` seeds that file name, see below), so on a project without the `ACT_` convention set
+`ACTION_PREFIX` to the prefix its page-action microflows do use. CONV020 can be opted out, as a
+user decision, if the project has no such convention (see "Opting out of a rule").
 
 ## Opting out of a rule
 
-List the rule file, one per line, in `.claude/lint-rules-disabled.txt`, then delete it from
-`.claude/lint-rules/`. A bare delete does not stick: `sync-project.sh` restores a rule it
-installed before, and `bin/lint-gate.sh` reads a rule that its receipt lists but that is missing
-as a `mxcli init` re-seed, so every exec reports `LINT BLIND` (#264). With the rule listed,
-the installer neither installs nor restores it and drops its receipt row, and lint-gate
-skips it.
+Disabling a rule is **the user's decision**, never an agent's: ask in chat, record the answer in
+`PROJECT.md`, then write one line per rule in `.claude/lint-rules-disabled.txt`, with its reason,
+and delete the file from `.claude/lint-rules/`:
+
+```
+txt002_non_iso_date_in_user_text.star  # reason: display standard is dd/MM/yyyy (PROJECT.md D-14)
+```
+
+A listed rule is never installed or restored by `sync-project.sh`, its receipt row is dropped,
+and `bin/lint-gate.sh` does not report it. Two kinds of line are **ignored, with a warning**:
+
+- a line with no `# reason:` text;
+- a stock-seeded rule (`conv010`, `data_change_microflows`, `entity_business_key` —
+  `MXTK_LINT_RULES_STOCK` in `bin/lib/install-manifest.sh`). `mxcli init` writes a stock copy of
+  those file names back, and the stock versions report a clean pass while inspecting nothing.
+
+A bare delete does not stick either: sync restores a rule it installed before, and lint-gate
+reads a receipt-listed rule that is missing as a re-seed, so every exec reports `LINT BLIND` (#264).
 
 ## How these reach a project
 
@@ -126,7 +139,9 @@ on every sync; both call `mxtk_install_lint_rules` in `bin/lib/install-lint-rule
 is one implementation rather than two that drift. Nothing a human edited is ever overwritten
 without `--upgrade-lint-rules <rule|all>`, which backs the local copy up first.
 
-A project's `.claude/.mxtk-lint-receipt` records the md5 of each rule *as installed*. Because
+A project's `.claude/.mxtk-lint-receipt` records the md5 of each rule *as installed*, and its
+kind (`stock`, `toolkit` or `configurable`, from the manifest) so that `bin/lint-gate.sh`, which
+runs in a project with no manifest, checks for a re-seed only where `mxcli init` can cause one. Because
 rules are copied verbatim, that one hash answers both questions the copy path needs: if the
 project's file still matches it, nobody here edited it; if the toolkit's file still matches it,
 the template has not moved. The receipt lives outside `lint-rules/`, which is what makes it
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index eca387c1..740c563f 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -28,16 +28,18 @@
 # in the other the re-seed sat uncommitted for five days and the baseline absorbed the noisier
 # counts. bin/lib/install-lint-rules.sh already writes .claude/.mxtk-lint-receipt (md5 of each
 # rule AS INSTALLED; it survives `mxcli init`), so before linting this script reads it: a rule
-# whose md5 no longer matches its receipt line AND whose `# mxtk-lint-rule:` header is gone (or
-# whose file is gone) was re-seeded, not edited by a person. The run then prints "BLIND — lint
+# whose md5 no longer matches its receipt line AND whose `# mxtk-lint-rule:` header is gone was
+# re-seeded, not edited by a person — checked only for rules the receipt marks `stock` (the file
+# names init seeds; toolkit-only and configurable rules are never seeded, so a headerless copy
+# of one is an edit). A receipt-listed rule whose file is gone is reported for every kind. The run then prints "BLIND — lint
 # rules reverted to stock", names the files, points at sync-project.sh (which restores them and
 # rewrites the receipt, so the next run is clean) and exits 1 without linting; --update-baseline
 # is refused, since baselining stock counts is how the five-day case went in. A rule that still
 # carries the header but differs is a hand edit — install-lint-rules.sh reports those, this does
-# not. No receipt = nothing to compare (pre-receipt installs) = no check. A rule removed on
-# purpose is listed in .claude/lint-rules-disabled.txt (the installer honours the same file and
-# prunes its receipt row). A deliberate headerless local rule: LINT_RULES_REVERTED_OK=1 runs
-# anyway, with the warning.
+# not. No receipt, or a row without a kind = no check (the next sync writes kinds). A non-stock
+# rule removed by the user's decision is listed, with a reason, in .claude/lint-rules-disabled.txt
+# (see lint-rules/README.md "Opting out of a rule"). LINT_RULES_REVERTED_OK=1 runs anyway, with
+# the warning.
 #
 # ACCEPTING DEBT IS RECORDED, NOT SILENT (2026-10-12). Three toolkit-built apps re-baselined
 # 61 times in four days — every acceptance made by the agent whose script caused the rise,
@@ -130,7 +132,7 @@ while [ $# -gt 0 ]; do
               REASON="$2"; shift ;;
     --reason=*) REASON="${1#--reason=}" ;;
     --approved-in-chat) APPROVED=1 ;;
-    -h|--help) sed -n '2,62p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,64p' "$0"; exit 0 ;;
     *) echo "lint-gate: unknown argument '$1'" >&2; exit 2 ;;
   esac
   shift
@@ -159,31 +161,49 @@ RECEIPT="$ROOT/.claude/.mxtk-lint-receipt"
 if [ -f "$RECEIPT" ]; then
   # Read into a variable first: a heredoc inside $(...) does not parse on bash 3.2.
   IFS= read -r -d '' _RCHK <<'PY' || true
-import hashlib, os
+import hashlib, os, re, sys
 rec, d, dis = os.environ["RECEIPT"], os.environ["RULES_DIR"], os.environ["DISABLED"]
+# Receipt rows: <rule-file> <md5> <kind>. kind (stock | toolkit | configurable) is written by
+# bin/lib/install-lint-rules.sh from install-manifest.sh, which a project does not have. A row
+# with no kind predates kinds and is not checked; the next sync writes it.
+rows = []
+for line in open(rec, encoding="utf-8", errors="replace"):
+    parts = line.split()
+    if len(parts) < 3 or parts[0].startswith("#"):
+        continue
+    rows.append((parts[0], parts[1], parts[2]))
+kind = {n: k for n, _, k in rows}
+# Opt-out: `<rule>  # reason: <text>` — the same rule the installer applies. No reason, or a
+# stock-seeded rule (init writes a stock copy back that passes clean while inspecting nothing):
+# the line is ignored, with a warning.
 disabled = set()
 if os.path.isfile(dis):
     for line in open(dis, encoding="utf-8", errors="replace"):
-        w = line.split()
-        if w and not w[0].startswith("#"):
+        w = line.split(None, 1)
+        if not w or w[0].startswith("#"):
+            continue
+        rest = w[1] if len(w) > 1 else ""
+        m = re.search(r"#\s*reason:\s*(\S.*)", rest)
+        if kind.get(w[0]) == "stock":
+            print("lint-gate: lint-rules-disabled.txt: %s is stock-seeded and cannot be disabled — ignored" % w[0], file=sys.stderr)
+        elif not m:
+            print("lint-gate: lint-rules-disabled.txt: %s has no '# reason: ...' — ignored" % w[0], file=sys.stderr)
+        else:
             disabled.add(w[0])
-for line in open(rec, encoding="utf-8", errors="replace"):
-    parts = line.split()
-    if len(parts) < 2 or parts[0].startswith("#"):
-        continue
-    name, want = parts[0], parts[1]
+HEADER = re.compile(rb"^# mxtk-lint-rule:", re.M)   # the installer's test: grep '^# mxtk-lint-rule:'
+for name, want, k in rows:
     if name in disabled:
-        continue  # deliberate opt-out, .claude/lint-rules-disabled.txt
+        continue
     path = os.path.join(d, name)
     if not os.path.isfile(path):
         print("%s\tgone (installed per the receipt, missing now)" % name)
         continue
+    if k != "stock":
+        continue  # init never seeds toolkit-only or configurable rules: an edit, the installer reports it
     data = open(path, "rb").read()
     got = hashlib.md5(data).hexdigest()
-    if got == want:
-        continue
-    if b"# mxtk-lint-rule:" in data:
-        continue  # header kept: a hand edit, which install-lint-rules.sh reports
+    if got == want or HEADER.search(data):
+        continue  # unchanged, or header kept: a hand edit, which install-lint-rules.sh reports
     print("%s\theader gone, md5 %s != receipt %s" % (name, got[:8], want[:8]))
 PY
   REVERTED="$(RECEIPT="$RECEIPT" RULES_DIR="$ROOT/.claude/lint-rules" DISABLED="$ROOT/.claude/lint-rules-disabled.txt" "$PY" -c "$_RCHK")"
@@ -198,7 +218,6 @@ PY
     echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT"
     echo "   If sync reports a rule LOCALLY MODIFIED instead of restoring it:"
     echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT --upgrade-lint-rules all"
-    echo "   Removed one on purpose? List it in .claude/lint-rules-disabled.txt and this stops."
     if [ "${LINT_RULES_REVERTED_OK:-}" = "1" ]; then
       echo "   LINT_RULES_REVERTED_OK=1 — linting anyway; counts below are from the files on disk."
       echo ""
diff --git a/skills/lint-that-actually-runs.md b/skills/lint-that-actually-runs.md
index beb2a0d3..dae239fb 100644
--- a/skills/lint-that-actually-runs.md
+++ b/skills/lint-that-actually-runs.md
@@ -191,7 +191,7 @@ telling a human to do it.
   reverted ARCH002/ARCH003 reports a clean pass while inspecting nothing. This is why the install
   receipt lives outside `lint-rules/` and why installing rules **after** `mxcli init` is not a
   style preference.
-  Between syncs, `bin/lint-gate.sh` reads the same receipt before every lint: a rule whose md5
+  Between syncs, `bin/lint-gate.sh` reads the same receipt before every lint: a stock-seeded rule whose md5
   no longer matches and whose header is gone stops the run as `BLIND — lint rules reverted to
   stock` (exit 1, exec.sh logs `LINT BLIND`), not as a rise on the next script (#264).
 - **Registering a file is not enough — register the pointer.** An earlier workstream's scripts sat
diff --git a/tests/wave2/test-lint-receipt-revert.sh b/tests/wave2/test-lint-receipt-revert.sh
index 5223d4f7..3321c333 100755
--- a/tests/wave2/test-lint-receipt-revert.sh
+++ b/tests/wave2/test-lint-receipt-revert.sh
@@ -50,7 +50,9 @@ R="$P/.claude/.mxtk-lint-receipt"
 [ -f "$R" ] && ok "receipt written by install-lint-rules.sh" || bad "installer wrote no receipt" "$out"
 n=$(grep -cv '^#' "$R" 2>/dev/null || echo 0)
 [ "$n" -ge 3 ] && ok "receipt lists $n rules" || bad "receipt lists $n rules"
-grep -q '^conv010_act_microflow_content.star  [0-9a-f]\{32\}$' "$R" && ok "conv010 row: name + md5" || bad "conv010 row missing" "$(cat "$R")"
+grep -q '^conv010_act_microflow_content.star  [0-9a-f]\{32\}  stock$' "$R" && ok "conv010 row: name + md5 + kind stock" || bad "conv010 row missing" "$(cat "$R")"
+grep -q '^ux001_confirm_before_destructive.star  [0-9a-f]\{32\}  toolkit$' "$R" && ok "ux001 row: kind toolkit" || bad "ux001 row kind wrong" "$(cat "$R")"
+grep -q '^conv020_action_user_feedback.star  [0-9a-f]\{32\}  configurable$' "$R" && ok "conv020 row: kind configurable" || bad "conv020 row kind wrong" "$(cat "$R")"
 
 echo "T1 rules as installed: no receipt complaint, normal ratchet"
 mk "$(v CONV010 warning 26)"
@@ -147,25 +149,62 @@ ls "$P9/.claude/lint-rules/$EBK".reseeded-* >/dev/null 2>&1 && ok "found copy ke
 out=$(gate2 "$P9" 2>&1); rc=$?
 [ "$rc" -eq 0 ] && ok "after sync: rc 0 (remedy clears it)" || bad "still blind after sync (rc $rc)" "$out"
 
-echo "T10 a rule removed on purpose (listed in .claude/lint-rules-disabled.txt) is not a re-seed"
+echo "T10 opt-out: a non-stock rule removed by the user's decision, with a reason"
 P10=$(newproj p10); inst2 "$P10" >/dev/null
-printf '# display standard is dd/MM/yyyy\ntxt002_non_iso_date_in_user_text.star\n' > "$P10/.claude/lint-rules-disabled.txt"
-rm -f "$P10/.claude/lint-rules/txt002_non_iso_date_in_user_text.star"
+T2F=txt002_non_iso_date_in_user_text.star
+printf '%s\n' "$T2F" > "$P10/.claude/lint-rules-disabled.txt"     # no reason
+rm -f "$P10/.claude/lint-rules/$T2F"
 out=$(gate2 "$P10" 2>&1); rc=$?
-[ "$rc" -eq 0 ] && ok "lint-gate: rc 0, no alarm before any sync" || bad "deliberate removal read as a re-seed (rc $rc)" "$out"
+case "$out" in *"$T2F has no '# reason: ...' — ignored"*"BLIND — lint rules reverted"*) ok "no reason: line ignored with a warning, removal still BLIND" ;; *) bad "reasonless opt-out honoured (rc $rc)" "$out" ;; esac
 out=$(inst2 "$P10")
-[ ! -f "$P10/.claude/lint-rules/txt002_non_iso_date_in_user_text.star" ] && ok "sync does not restore a disabled rule" || bad "sync restored a disabled rule" "$out"
-grep -q '^txt002_non_iso_date_in_user_text.star ' "$P10/.claude/.mxtk-lint-receipt" && bad "disabled rule's receipt row kept" || ok "disabled rule's receipt row pruned"
+case "$out" in *"$T2F has no '# reason: …' — IGNORED"*) ok "installer warns about the reasonless line" ;; *) bad "no installer warning" "$out" ;; esac
+[ -f "$P10/.claude/lint-rules/$T2F" ] && ok "reasonless opt-out: sync restores the rule" || bad "reasonless opt-out honoured by sync"
+printf '# decided with the user 2026-10-13\n%s  # reason: display standard is dd/MM/yyyy (PROJECT.md decision D-14)\n' "$T2F" > "$P10/.claude/lint-rules-disabled.txt"
+rm -f "$P10/.claude/lint-rules/$T2F"
+out=$(gate2 "$P10" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "with a reason: lint-gate rc 0, no alarm before any sync" || bad "reasoned opt-out read as a re-seed (rc $rc)" "$out"
+out=$(inst2 "$P10")
+[ ! -f "$P10/.claude/lint-rules/$T2F" ] && ok "sync does not restore it" || bad "sync restored a disabled rule" "$out"
+if grep -q "^$T2F " "$P10/.claude/.mxtk-lint-receipt"; then bad "disabled rule's receipt row kept"; else ok "disabled rule's receipt row pruned"; fi
 rm -f "$P10/.claude/lint-rules/txt001_build_words_in_user_text.star"
 out=$(gate2 "$P10" 2>&1); rc=$?
 case "$out" in *txt001_build_words_in_user_text.star*) ok "an unlisted removal is still caught" ;; *) bad "unlisted removal missed" "$out" ;; esac
+inst2 "$P10" >/dev/null
+
+echo "T12 opt-out is refused for a stock-seeded rule"
+C10=conv010_act_microflow_content.star
+printf '%s  # reason: we do not use ACT_ prefixes\n' "$C10" >> "$P10/.claude/lint-rules-disabled.txt"
+rm -f "$P10/.claude/lint-rules/$C10"
+out=$(gate2 "$P10" 2>&1); rc=$?
+case "$out" in *"$C10 is stock-seeded and cannot be disabled — ignored"*"$C10: gone"*"BLIND — lint rules reverted"*) ok "lint-gate: refused, still BLIND" ;; *) bad "stock opt-out honoured by lint-gate (rc $rc)" "$out" ;; esac
+out=$(inst2 "$P10")
+case "$out" in *"$C10 cannot be disabled — IGNORED"*) ok "installer refuses it with a warning" ;; *) bad "no refusal from the installer" "$out" ;; esac
+[ -f "$P10/.claude/lint-rules/$C10" ] && ok "sync restores the stock-seeded rule" || bad "stock-seeded rule left missing"
+
+echo "T13 a headerless toolkit-only rule (ux001) is a local edit: never overwritten, not BLIND"
+P13=$(newproj p13); inst2 "$P13" >/dev/null
+U1="$P13/.claude/lint-rules/ux001_confirm_before_destructive.star"
+strip_header "$U1"; printf '# local tweak\n' >> "$U1"; um=$(portable_md5 "$U1")
+out=$(gate2 "$P13" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "lint-gate: rc 0, no BLIND for a toolkit-only rule" || bad "headerless ux001 called a re-seed (rc $rc)" "$out"
+out=$(inst2 "$P13")
+case "$out" in *"ux001_confirm_before_destructive.star is LOCALLY MODIFIED"*) ok "installer reports LOCALLY MODIFIED" ;; *) bad "not reported as a local edit" "$out" ;; esac
+[ "$(portable_md5 "$U1")" = "$um" ] && ok "ux001 not overwritten" || bad "ux001 overwritten"
+
+echo "T14 a configured, headerless conv020 is not overwritten and not BLIND"
+C2="$P13/.claude/lint-rules/conv020_action_user_feedback.star"
+strip_header "$C2"; printf 'PROJECT_MODULES = "Orders"\n' >> "$C2"; cm=$(portable_md5 "$C2")
+out=$(gate2 "$P13" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "lint-gate: rc 0 for a configured conv020" || bad "configured conv020 called a re-seed (rc $rc)" "$out"
+out=$(inst2 "$P13")
+[ "$(portable_md5 "$C2")" = "$cm" ] && ok "conv020 not overwritten" || bad "conv020 overwritten" "$out"
 
 echo "T11 a rule the toolkit stops shipping: its receipt row is pruned, no permanent 'gone'"
 P11=$(newproj p11); inst2 "$P11" >/dev/null
 rm -f "$P11/.claude/lint-rules/ui001_widget_layout_traps.star"   # project tidies the retired rule away
 FEWER=$(printf '%s\n' $(. "$TK2/bin/lib/install-manifest.sh" >/dev/null 2>&1; echo "$MXTK_LINT_RULES") | grep -v '^ui001_widget_layout_traps.star$' | paste -sd' ' -)
 out=$(inst2 "$P11" "$FEWER")
-grep -q '^ui001_widget_layout_traps.star ' "$P11/.claude/.mxtk-lint-receipt" && bad "row for a dropped rule kept" "$out" || ok "row for the dropped rule pruned"
+if grep -q '^ui001_widget_layout_traps.star ' "$P11/.claude/.mxtk-lint-receipt"; then bad "row for a dropped rule kept" "$out"; else ok "row for the dropped rule pruned"; fi
 case "$out" in *"dropped row"*ui001*) ok "installer says so" ;; *) bad "prune not reported" "$out" ;; esac
 [ ! -f "$P11/.claude/lint-rules/ui001_widget_layout_traps.star" ] && ok "dropped rule not reinstalled" || bad "dropped rule reinstalled"
 out=$(gate2 "$P11" 2>&1); rc=$?

From 34cd4ec2b6d5221374d33a297b1e1baa26ce8f68 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:26:01 +0000
Subject: [PATCH 9/9] fix(lint-rules): one opt-out syntax, override never
 baselines, capped backups, honest restore label (#264 re-review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Opt-out reason: the installer now accepts `#\s*reason:` like lint-gate (it required
  `# reason:` exactly, so `#reason: x` was honoured by one tool and ignored by the other).
- LINT_RULES_REVERTED_OK=1 no longer gets past the --update-baseline refusal: the override is
  for looking at counts, and baselining stock counts is how the five-day field case went in.
- `.reseeded-<ts>` backups are capped at the newest 3 per rule.
- A stock-seeded rule restored because its header is gone and its body matches no known stock
  hash is labelled "header missing — restored from toolkit, your copy kept as <file>", not
  "REVERTED TO STOCK": a newer mxcli's seed and a hand edit that lost the header look the same.
- tests/wave2/test-lint-receipt-revert.sh: `#reason:` case, override + --update-baseline,
  backup cap, label. 55/55 here; each new case fails on the previous commit's scripts; 28 fail
  on master's installer + lint-gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                            |  2 +-
 bin/lib/install-lint-rules.sh           | 15 ++++++++++-----
 project-bin/lint-gate.sh                | 12 +++++++-----
 tests/wave2/test-lint-receipt-revert.sh | 17 +++++++++++++++--
 4 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ef833cf..ac1876fb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a stock-seeded rule (the file names `mxcli init` writes, now marked `stock` in the receipt) whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or any receipt-listed rule that is missing, is named, the remedy `bin/sync-project.sh <project>` (fallback `--upgrade-lint-rules all`) is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the remedy always clears it, `bin/lib/install-lint-rules.sh` restores such a stock-seeded rule even when this mxcli's stock hash is not in `STOCK-HASHES.txt` yet (it was reported LOCALLY MODIFIED and never written); a headerless toolkit-only or configurable rule is still a local edit, never overwritten. The installer also writes each receipt row's kind, prunes rows for rules no longer shipped, and honours `.claude/lint-rules-disabled.txt`: one line per rule with `# reason: …`, a user decision recorded in `PROJECT.md`; a line with no reason, or naming a stock-seeded rule, is ignored with a warning (`lint-rules/README.md` had told projects to just delete txt002). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 51/51 here, 25 fail on master's lint-gate and installer. — AlvinnYeo
+- fix(lint-gate): **rules that `mxcli init` reverted to stock now stop the lint run as BLIND instead of showing up as a rise on the next script** ([#264](https://github.com/MendixMau/mxcli-project-toolkit/issues/264)). `bin/lint-gate.sh` reads `.claude/.mxtk-lint-receipt` (written by `bin/lib/install-lint-rules.sh`) before linting: a stock-seeded rule (the file names `mxcli init` writes, now marked `stock` in the receipt) whose md5 no longer matches and whose `# mxtk-lint-rule:` header is gone, or any receipt-listed rule that is missing, is named, the remedy `bin/sync-project.sh <project>` (fallback `--upgrade-lint-rules all`) is printed, and the run exits 1 with `BLIND — lint rules reverted to stock` (exec.sh logs `LINT BLIND`, not `LINT ROSE`); `--update-baseline` is refused over reverted rules, also under the `LINT_RULES_REVERTED_OK=1` look-anyway override. Field cases: CONV010 26 -> 169 blamed on a pages-only exec, and a re-seed that sat five days while the baseline absorbed stock counts. So the remedy always clears it, `bin/lib/install-lint-rules.sh` restores such a stock-seeded rule even when its body matches no known stock hash (a newer mxcli's seed, or a hand edit that also lost the header: it was reported LOCALLY MODIFIED and never written), labelled `header missing — restored from toolkit, your copy kept as <rule>.reseeded-<ts>` with the newest 3 copies kept; a headerless toolkit-only or configurable rule is still a local edit, never overwritten. The installer also writes each receipt row's kind, prunes rows for rules no longer shipped, and honours `.claude/lint-rules-disabled.txt`: one line per rule with `# reason: …` (`#\s*reason:` in both tools), a user decision recorded in `PROJECT.md`; a line with no reason, or naming a stock-seeded rule, is ignored with a warning (`lint-rules/README.md` had told projects to just delete txt002). Fixture `tests/wave2/test-lint-receipt-revert.sh` builds its receipt with the real installer and uses a genuine v0.25.0 stock body: 55/55 here, 28 fail on master's lint-gate and installer. — AlvinnYeo
 - learn(learned-mdl-preflight): **a microflow change near a `return` in a dense flow is planned as drop + create after `show access`; `check -p --references` does not run exec's free-room test** ([#263](https://github.com/MendixMau/mxcli-project-toolkit/issues/263)). STOP row 28 and BUG-156: on v0.25.0 `check` printed "no flow change exec would refuse" and exec then refused "there is no free room for the fragment". Upstream issue drafted, not filed. — AlvinnYeo
 - 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
diff --git a/bin/lib/install-lint-rules.sh b/bin/lib/install-lint-rules.sh
index 633fd1b9..42f6560b 100644
--- a/bin/lib/install-lint-rules.sh
+++ b/bin/lib/install-lint-rules.sh
@@ -139,8 +139,9 @@ _mxtk_lint_receipt_set() {
 # _mxtk_lint_is_disabled answers for one rule; _mxtk_lint_disabled_audit warns once per bad line.
 _mxtk_lint_dis_ok() {  # $1 = rule, $2 = rest of the line -> 0 when the line is a valid opt-out
   case " ${MXTK_LINT_RULES_STOCK:-} " in *" $1 "*) return 1 ;; esac
-  _dis_why="${2#*# reason:}"
-  [ "$_dis_why" != "$2" ] || return 1
+  # Same syntax lint-gate.sh accepts (Python `#\s*reason:\s*(\S.*)`): `#`, optional blanks,
+  # `reason:`, then non-blank text.
+  _dis_why="$(printf '%s\n' "$2" | sed -n 's/^.*#[[:space:]]*reason:[[:space:]]*//p')"
   [ -n "$(printf '%s' "$_dis_why" | tr -d '[:space:]')" ]
 }
 _mxtk_lint_is_disabled() {
@@ -336,14 +337,18 @@ mxtk_install_lint_rules() {
       # and falls through to the LOCALLY MODIFIED / configured branches below, never overwritten.
       # The found file is kept beside it; lint loads *.star only.
       if [ -n "$_rec" ] && [ "$(_mxtk_lint_kind "$_f")" = stock ] && ! grep -q '^# mxtk-lint-rule:' "$_dst"; then
-        _why="REVERTED TO STOCK — header gone; this mxcli's stock hash is not in STOCK-HASHES.txt yet. Restoring it"
+        # Not "REVERTED TO STOCK": its body matches no known stock hash, so it is either a
+        # newer mxcli's seed or a hand edit that also lost the header. The two look the same
+        # from here, which is why the copy is kept. Backups are capped at the newest 3 per rule
+        # (the name sorts by time), so a project that re-seeds on every init does not pile up.
         if [ "$_dry" -eq 1 ]; then
-          echo "Would install: .claude/lint-rules/$_f ($_why)"
+          echo "Would install: .claude/lint-rules/$_f (header missing — would restore from toolkit and keep your copy)"
         else
           _bak="$_dst.reseeded-$(date +%Y%m%d%H%M%S)"
           cp "$_dst" "$_bak"
           cp "$_src" "$_dst" && _mxtk_lint_receipt_set "$_receipt" "$_f" "$_srcmd5"
-          echo "Lint rule: $_why — .claude/lint-rules/$_f (the file found is kept at $(basename "$_bak"))"
+          ls "$_dst".reseeded-* 2>/dev/null | sort -r | sed -n '4,$p' | while IFS= read -r _old; do rm -f "$_old"; done
+          echo "Lint rule: .claude/lint-rules/$_f — header missing — restored from toolkit, your copy kept as $(basename "$_bak")"
         fi
         MXTK_LINT_CHANGES=$((MXTK_LINT_CHANGES + 1))
         continue
diff --git a/project-bin/lint-gate.sh b/project-bin/lint-gate.sh
index 740c563f..39a15c6a 100755
--- a/project-bin/lint-gate.sh
+++ b/project-bin/lint-gate.sh
@@ -39,7 +39,7 @@
 # not. No receipt, or a row without a kind = no check (the next sync writes kinds). A non-stock
 # rule removed by the user's decision is listed, with a reason, in .claude/lint-rules-disabled.txt
 # (see lint-rules/README.md "Opting out of a rule"). LINT_RULES_REVERTED_OK=1 runs anyway, with
-# the warning.
+# the warning (a check run only: --update-baseline stays refused).
 #
 # ACCEPTING DEBT IS RECORDED, NOT SILENT (2026-10-12). Three toolkit-built apps re-baselined
 # 61 times in four days — every acceptance made by the agent whose script caused the rise,
@@ -218,12 +218,14 @@ PY
     echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT"
     echo "   If sync reports a rule LOCALLY MODIFIED instead of restoring it:"
     echo "     ${TKR:-<toolkit-root>}/bin/sync-project.sh $ROOT --upgrade-lint-rules all"
-    if [ "${LINT_RULES_REVERTED_OK:-}" = "1" ]; then
-      echo "   LINT_RULES_REVERTED_OK=1 — linting anyway; counts below are from the files on disk."
-      echo ""
-    elif [ "$UPDATE" -eq 1 ]; then
+    if [ "$UPDATE" -eq 1 ]; then
+      # Refused even under LINT_RULES_REVERTED_OK: the override is for looking at counts, and
+      # baselining stock counts is exactly how the five-day field case went in.
       echo "lint-gate: REFUSED — --update-baseline over reverted rules would baseline stock counts." >&2
       exit 2
+    elif [ "${LINT_RULES_REVERTED_OK:-}" = "1" ]; then
+      echo "   LINT_RULES_REVERTED_OK=1 — linting anyway; counts below are from the files on disk."
+      echo ""
     else
       echo "BLIND — lint rules reverted to stock; lint not run, nothing compared against the baseline."
       # lint-last.json gets the verdict but no total: lint did not run, and a stale total from
diff --git a/tests/wave2/test-lint-receipt-revert.sh b/tests/wave2/test-lint-receipt-revert.sh
index 3321c333..2a8a046d 100755
--- a/tests/wave2/test-lint-receipt-revert.sh
+++ b/tests/wave2/test-lint-receipt-revert.sh
@@ -94,6 +94,10 @@ out=$(gate --update-baseline --reason "x" 2>&1); rc=$?
 echo "T5 LINT_RULES_REVERTED_OK=1 lints anyway, with the warning"
 out=$(cd "$P" && LINT_RULES_REVERTED_OK=1 LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh 2>&1); rc=$?
 case "$out" in *"REVERTED TO STOCK"*"FAIL —"*) ok "warned, then compared (rise visible)" ;; *) bad "override did not lint" "$out" ;; esac
+before=$(cat "$P/.claude/lint-baseline.json")
+out=$(cd "$P" && LINT_RULES_REVERTED_OK=1 LINT_JSON="$WORK/lint.json" bash bin/lint-gate.sh --update-baseline --reason "x" 2>&1); rc=$?
+[ "$rc" -eq 2 ] && [ "$(cat "$P/.claude/lint-baseline.json")" = "$before" ] && ok "override does not get past the --update-baseline refusal" \
+  || bad "stock counts baselined under the override (rc $rc)" "$out"
 
 echo "T6 the remedy is not blocked and clears it (the installer sync-project.sh runs)"
 out=$(install_rules)
@@ -143,11 +147,19 @@ out=$(gate2 "$P9" 2>&1); rc=$?
   && ok "lint-gate: BLIND, names $EBK" || bad "lint-gate did not flag the unknown-hash re-seed (rc $rc)" "$out"
 case "$out" in *"--upgrade-lint-rules all"*) ok "message carries the LOCALLY MODIFIED fallback" ;; *) bad "no --upgrade-lint-rules fallback" "$out" ;; esac
 out=$(inst2 "$P9")
-case "$out" in *"REVERTED TO STOCK"*"$EBK"*) ok "installer restores it (not LOCALLY MODIFIED)" ;; *) bad "installer did not restore it" "$out" ;; esac
+case "$out" in *"$EBK — header missing — restored from toolkit, your copy kept as $EBK.reseeded-"*) ok "installer restores it, labelled 'header missing', copy named" ;; *) bad "installer did not restore it" "$out" ;; esac
+case "$out" in *"REVERTED TO STOCK"*) bad "a body matching no known stock hash called REVERTED TO STOCK" "$out" ;; *) ok "not labelled REVERTED TO STOCK (body matches no known stock hash)" ;; esac
 cmp -s "$TK2/lint-rules/$EBK" "$P9/.claude/lint-rules/$EBK" && ok "file is the toolkit version again" || bad "file not restored"
 ls "$P9/.claude/lint-rules/$EBK".reseeded-* >/dev/null 2>&1 && ok "found copy kept beside it" || bad "found copy not kept"
 out=$(gate2 "$P9" 2>&1); rc=$?
 [ "$rc" -eq 0 ] && ok "after sync: rc 0 (remedy clears it)" || bad "still blind after sync (rc $rc)" "$out"
+# Backups are capped: with 5 older copies already there, one more re-seed leaves the newest 3.
+for i in 1 2 3 4 5; do printf 'old %s\n' "$i" > "$P9/.claude/lint-rules/$EBK.reseeded-2020010100000$i"; done
+cp "$STOCK" "$P9/.claude/lint-rules/$EBK"; inst2 "$P9" >/dev/null
+n=$(ls "$P9/.claude/lint-rules/$EBK".reseeded-* 2>/dev/null | wc -l | tr -d ' ')
+[ "$n" -eq 3 ] && ok "backups capped at 3" || bad "backups not capped ($n)"
+kept_old=""; for i in 1 2 3; do [ -f "$P9/.claude/lint-rules/$EBK.reseeded-2020010100000$i" ] && kept_old="$kept_old $i"; done
+[ -z "$kept_old" ] && ok "the oldest backups are the ones removed" || bad "oldest backups kept:$kept_old"
 
 echo "T10 opt-out: a non-stock rule removed by the user's decision, with a reason"
 P10=$(newproj p10); inst2 "$P10" >/dev/null
@@ -159,7 +171,8 @@ case "$out" in *"$T2F has no '# reason: ...' — ignored"*"BLIND — lint rules
 out=$(inst2 "$P10")
 case "$out" in *"$T2F has no '# reason: …' — IGNORED"*) ok "installer warns about the reasonless line" ;; *) bad "no installer warning" "$out" ;; esac
 [ -f "$P10/.claude/lint-rules/$T2F" ] && ok "reasonless opt-out: sync restores the rule" || bad "reasonless opt-out honoured by sync"
-printf '# decided with the user 2026-10-13\n%s  # reason: display standard is dd/MM/yyyy (PROJECT.md decision D-14)\n' "$T2F" > "$P10/.claude/lint-rules-disabled.txt"
+# `#reason:` with no blank: both tools must accept the same syntax.
+printf '# decided with the user 2026-10-13\n%s  #reason: display standard is dd/MM/yyyy (PROJECT.md decision D-14)\n' "$T2F" > "$P10/.claude/lint-rules-disabled.txt"
 rm -f "$P10/.claude/lint-rules/$T2F"
 out=$(gate2 "$P10" 2>&1); rc=$?
 [ "$rc" -eq 0 ] && ok "with a reason: lint-gate rc 0, no alarm before any sync" || bad "reasoned opt-out read as a re-seed (rc $rc)" "$out"