diff --git a/CHANGELOG.md b/CHANGELOG.md
index d5b5c38..f162315 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob
 Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
+- new(skills/microflow-preflight.md): **a microflow with a loop, a list built from a list, or more than 20 activities now gets a posted checklist before its first MDL line.** Lint runs only after exec. CONV009/QUAL003 count top-level activities only, so 20 activities inside one loop count as 3. Retrieve, REST and Java calls inside a loop have no lint rule at all. The skill maps each Mendix microflow best practice to the rule that catches it afterwards, or marks it "preflight is the only check". It sets the layout rule to "omit `@position`", which upstream now states too, and adds STOP row 25, a baseline routing row and an mdl-agent bullet. It corrects the stale `reset layout` advice (BUG-28), the commit-in-loop cookbook recipe and the 30–50-activity guideline. Field evidence: measured on mxcli v0.24.0 on a scratch copy of a real model — CONV011 on a commit in a loop, MPR008 on partial and 100 px hand placement, MPR011 on negative loop-body coordinates, and a v0.24.0 auto-layout defect where a loop followed by an activity in an `if` branch puts the merge on that activity (MPR008 on a correct script) — Maurits Visser
 - fix(project-bin/exec.sh): **the lint ratchet now runs after every clean mxbuild, and its verdict lands in the same BUILD-LOG row.** mxbuild proves the model compiles, not how it is built: on a field project a migration microflow shipped three commits inside loops (`mxcli lint` CONV011) under "✅ applied · mxbuild clean", because lint lived only in the gate-agent definition as an optional step and that agent had been spawned 0 times against 21 `exec.sh` runs. `exec.sh` now calls `bin/lint-gate.sh` after a clean build; a rise vs the committed baseline writes `⚠️ applied, LINT ROSE: <rules>` and exits 1 while keeping the write (shape, not corruption), `SKIP_LINT=<reason>` is the only override and is recorded in the row, and a project without `lint-gate.sh` gets `lint not installed` rather than a blank cell. `agents/gate-agent.md` and `agents/agent-roles.md` now read the row instead of treating lint as optional; `learned-detection-gaps.md` gains the register row. Field run: a marketplace guest-group migration, 2026-09-24, ~13 s per run on a 10k-finding project — Maurits Visser
 - learn(ui-loop, learned-detection-gaps): **the screenshot harness is an instrument, and nobody
   scores it.** Two harness defects on the PRD benchmark's Arm A produced screenshots that were
diff --git a/README.md b/README.md
index d207470..3e3932b 100644
--- a/README.md
+++ b/README.md
@@ -778,6 +778,7 @@ Read a row when its Stage(s) cell says *every stage* or names the stage the regi
 | Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations | `skills/learned-mdl-preflight.md` | 5 |
 | Placing any document in a module — before the first `create`. Feature group, then Pages/Microflows/Services/Resources; the path comes from the brief's folder plan, and the table says which types mxcli can actually place | `skills/module-folder-convention.md` | 4,5 |
 | Writing or fixing any microflow — MDL gotchas plus annotation discipline | `skills/learned-microflow-patterns.md` | 5 |
+| Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line | `skills/microflow-preflight.md` | 5 |
 | Building any page or snippet — before the first widget. Wireframe, tokens, gallery reuse, cross-check; no wireframe means STOP | `skills/ui-preflight-pages.md` | 5 |
 | Writing or reviewing any page or snippet — the spacing scale (8/16/24/32/48), section rhythm, and the page-header scaffold every full page starts with; sections at 0px apart and pages with no H1 are the defects it retires | `skills/design-spacing.md` | 5 |
 | After every page-building script, and any time the UI looks wrong — the cheap repeatable look during the build: one page, one screenshot, four questions, scored when a wireframe exists. Feeds Gate: UI, never replaces it | `skills/ui-loop.md` | 5 |
diff --git a/ROUTING.md b/ROUTING.md
index 6bcf33a..5ebad4d 100644
--- a/ROUTING.md
+++ b/ROUTING.md
@@ -150,6 +150,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
 |---|---|---|---|---|
 | Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations | `skills/learned-mdl-preflight.md` | mdl | 5 | baseline |
 | Writing or fixing any microflow — MDL gotchas plus annotation discipline | `skills/learned-microflow-patterns.md` | mdl | 5 | baseline |
+| Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line | `skills/microflow-preflight.md` | mdl | 5 | baseline |
 | Choosing CLI vs MCP+MDL vs hand-rolled MCP, or any MCP write session — three co-equal write modes, not CLI-only | `skills/learned-mcp-patterns.md` | mdl | 5 | baseline |
 | Reading what loop bodies do (LOOP_TQ, deferred commit, nested loop, REST in loop, transaction control per item, scheduled-event reachability) from described MDL; the catalog holds top-level activities only and cannot see inside a loop | `skills/microflow-loop-antipatterns.md` | architect,review,mdl | 0,5,6 | ondemand |
 | Writing MDL microflow scripts — worked recipes | `skills/mdl-cookbook-microflows.md` | mdl | 5 | ondemand |
diff --git a/agents/mdl-agent.md b/agents/mdl-agent.md
index 3385121..f27caf7 100644
--- a/agents/mdl-agent.md
+++ b/agents/mdl-agent.md
@@ -42,6 +42,7 @@ a rule below names an asset (e.g. "the wireframe", "the brief"), it means the pa
 | `skills/learned-mdl-preflight.md` | Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations |
 | `skills/module-folder-convention.md` | Placing any document in a module — before the first `create`. Feature group, then Pages/Microflows/Services/Resources; the path comes from the brief's folder plan, and the table says which types mxcli can actually place |
 | `skills/learned-microflow-patterns.md` | Writing or fixing any microflow — MDL gotchas plus annotation discipline |
+| `skills/microflow-preflight.md` | Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line |
 | `skills/ui-preflight-pages.md` | Building any page or snippet — before the first widget. Wireframe, tokens, gallery reuse, cross-check; no wireframe means STOP |
 | `skills/design-spacing.md` | Writing or reviewing any page or snippet — the spacing scale (8/16/24/32/48), section rhythm, and the page-header scaffold every full page starts with; sections at 0px apart and pages with no H1 are the defects it retires |
 | `skills/ui-loop.md` | After every page-building script, and any time the UI looks wrong — the cheap repeatable look during the build: one page, one screenshot, four questions, scored when a wireframe exists. Feeds Gate: UI, never replaces it |
@@ -137,6 +138,7 @@ this summary. The hard STOPs below are inline on purpose; never route around the
   overrides that pick for corrupting ops. State the mode per op in your report. On any STOP → MCP,
   hand back the **filled** confirmed JSON pattern from `learned-mcp-patterns.md`, not just the label.
 - Annotate selectively (`learned-microflow-patterns.md`); always annotate a CE-error fix.
+- **Loops / long flows — run `microflow-preflight.md`** and post its checklist before the first MDL line; `microflow-preflight: no trigger` otherwise.
 - **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
diff --git a/bin/gate-check.sh b/bin/gate-check.sh
index 82a2086..dc7fe19 100755
--- a/bin/gate-check.sh
+++ b/bin/gate-check.sh
@@ -1609,7 +1609,7 @@ stage_protocol_paths() {
     2)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-brd.md skills/checkpoints/checkpoint-architecture.md skills/image-transcription.md skills/small-project-tier.md skills/kb-generation.md skills/brd-generation.md skills/brd-validation.md" ;;
     3)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/small-project-tier.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;;
     4)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-build.md skills/agent-roles.md skills/small-project-tier.md skills/module-brief.md skills/module-folder-convention.md skills/brd-to-build-plan.md skills/coverage-ledger.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/learned-constants-and-secrets.md" ;;
-    5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/learned-mcp-patterns.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
+    5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/learned-mcp-patterns.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
     6)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;;
     7)  echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/close-the-loop.md skills/share-demo-package.md skills/handoff-to-studio-pro.md skills/platform-link.md skills/teamserver-alignment.md skills/deploy-to-sandbox.md" ;;
     *)  echo "" ;;
diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv
index 44876f1..ce38ff6 100644
--- a/bin/lib/skill-routing.tsv
+++ b/bin/lib/skill-routing.tsv
@@ -93,6 +93,7 @@ module-brief	skills/module-brief.md	Building any module — before the first scr
 learned-mdl-preflight	skills/learned-mdl-preflight.md	Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations	mdl	5	baseline	build/mdl
 module-folder-convention	skills/module-folder-convention.md	Placing any document in a module — before the first `create`. Feature group, then Pages/Microflows/Services/Resources; the path comes from the brief's folder plan, and the table says which types mxcli can actually place	architect,mdl	4,5	baseline	architecture
 learned-microflow-patterns	skills/learned-microflow-patterns.md	Writing or fixing any microflow — MDL gotchas plus annotation discipline	mdl	5	baseline	build/mdl
+microflow-preflight	skills/microflow-preflight.md	Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line	mdl	5	baseline	build/mdl
 ui-preflight-pages	skills/ui-preflight-pages.md	Building any page or snippet — before the first widget. Wireframe, tokens, gallery reuse, cross-check; no wireframe means STOP	mdl	5	baseline	design
 design-spacing	skills/design-spacing.md	Writing or reviewing any page or snippet — the spacing scale (8/16/24/32/48), section rhythm, and the page-header scaffold every full page starts with; sections at 0px apart and pages with no H1 are the defects it retires	mdl,review	5	baseline	design
 learned-stylegallery	skills/learned-stylegallery.md	Building or using the in-app design gallery	mdl	5	ondemand	design
diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md
index 56935b3..7f8c030 100644
--- a/skills/conversion-runbook.md
+++ b/skills/conversion-runbook.md
@@ -39,6 +39,7 @@ Read a row when its Stage(s) cell says *every stage* or names the stage the regi
 | Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations | `skills/learned-mdl-preflight.md` | 5 |
 | Placing any document in a module — before the first `create`. Feature group, then Pages/Microflows/Services/Resources; the path comes from the brief's folder plan, and the table says which types mxcli can actually place | `skills/module-folder-convention.md` | 4,5 |
 | Writing or fixing any microflow — MDL gotchas plus annotation discipline | `skills/learned-microflow-patterns.md` | 5 |
+| Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line | `skills/microflow-preflight.md` | 5 |
 | Building any page or snippet — before the first widget. Wireframe, tokens, gallery reuse, cross-check; no wireframe means STOP | `skills/ui-preflight-pages.md` | 5 |
 | Writing or reviewing any page or snippet — the spacing scale (8/16/24/32/48), section rhythm, and the page-header scaffold every full page starts with; sections at 0px apart and pages with no H1 are the defects it retires | `skills/design-spacing.md` | 5 |
 | After every page-building script, and any time the UI looks wrong — the cheap repeatable look during the build: one page, one screenshot, four questions, scored when a wireframe exists. Feeds Gate: UI, never replaces it | `skills/ui-loop.md` | 5 |
diff --git a/skills/learned-mdl-preflight.md b/skills/learned-mdl-preflight.md
index f416985..bd6c33b 100644
--- a/skills/learned-mdl-preflight.md
+++ b/skills/learned-mdl-preflight.md
@@ -66,6 +66,7 @@ Once you've picked a mode per operation, run the STOP table below against every
 | 22 | Write a script containing ANY non-idempotent statement — `alter entity … add attribute`, bare `CREATE ASSOCIATION`, bare `CREATE MICROFLOW`/`CREATE PAGE` on a name that may already exist | **STOP → use the `create or modify` form for every statement, and give every document exactly ONE owning script.** mxcli is **not transactional across statements**: the first failure stops the script and every statement below it is **silently skipped**, while the mxbuild gate reports 0 errors — the model is valid, it is merely missing work nobody asked it to skip. The property to hold is that `mdlsource/` replays cleanly against an EMPTY app; that is one command and it is the only thing that proves it. | Confirmed 2026-08-31 (a dashboard-publishing migration, mxcli v0.20.0). Script `09b` added two attributes with `alter entity … add attribute` and then defined two microflows. Re-running it after the attributes existed died on statement 1 with "attribute already exists" — and the two microflows at the end were never applied. It surfaced days later as `ACT_Version_Delete` quietly missing a call it had had an hour earlier, found by `DESCRIBE MICROFLOW` on a hunch; no gate saw it, because a microflow that no longer calls a sub-microflow is a perfectly valid model. Compounded by rule 21's defect one level up: six scripts held a grant on the same three entities, so whichever ran last decided their security. **The fix that makes both go away is the same one:** one owner per document, `create or modify` throughout, and a from-empty replay in CI or at wrap-up. Worked example incl. the before/after comparison: the project's `docs/REBUILD.md` pattern — 23/23 scripts replay, `BUILD SUCCEEDED`, rebuilt model identical to the live one element for element. |
 | 23 | Name any document or entity that **might already exist** — `create or modify` on an entity, or any `create or replace` on a page, layout or microflow | **STOP → run `mxcli diff -p <app>.mpr <script>.mdl --format struct` FIRST.** It is read-only, it takes a second, and it prints exactly what the script would add and what it would REMOVE. Read the `-` lines before you exec, every time. Rules 21 and 22 tell you to write `create or modify` and to give each document one owner; this is the check that the name you chose is actually free. | Confirmed 2026-09-01 (a dashboard-publishing migration, mxcli v0.20.0). A new script declared `create or modify non-persistent entity DashboardPublishing."ViewerContext"` with one attribute, believing the name unused. The entity already existed, owned by an earlier page script, carrying four attributes — `VersionLabel`, `HasContent`, `Html`, `DashboardTitle` — which are the entire datasource of the app's viewing page. `diff --format struct` reported `+ Attribute SharedCount` and **four `- Attribute` lines**, i.e. `create or modify` on an entity does not merge into the attribute set, it **replaces** it. Renaming the new entity took ten seconds; the alternative was a page that renders nothing, on a model that would have passed `mx check` and mxbuild clean, since an entity losing four attributes is a perfectly valid model. **This is the cheapest guard in the file — the whole rule is `diff` before `exec`.** |
 | 24 | Put a `DesignProperties: [...]` entry on a widget (Form orientation, Label width, Spacing, …) in an app scaffolded by `mxcli new` (any `--theme`) | **STOP → grep the theme first: `grep -l '<property name>' themesource/*/web/design-properties.json`. If it is not there, use the Atlas class instead (`Class: 'form-vertical'`, `spacing-outer-bottom-large`).** `mxcli new`'s theme layer ships a `design-properties.json` that does not carry Atlas's FormBase entries, so mxbuild rejects the property with CE6083 "not supported by your theme" — after `check --references` passed it. `design-spacing.md` says design properties and classes write the identical model; that holds only when the theme declares the property. | Greenfield pilot 2026-09-04, mxcli v0.20.0, Mendix 11.13.0, signal theme: `DesignProperties: ['Form orientation': 'Vertical']` on a DataView → exec ok, CE6083 at the gate, auto-restored. `Class: 'form-vertical'` built clean — and then changed nothing on screen, because in that theme the form layout is decided by the theme's own dataview rules, not the class (ui-loop.md "which side is wrong", row 1). The look caught it; no gate could. |
+| 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. |
 
 **Default to mxcli for:** entities/attributes/enums, associations (after SHOW ASSOCIATIONS check), microflows (without inline assoc-sets), demo users, module roles/grants, navigation.
 
diff --git a/skills/learned-microflow-patterns.md b/skills/learned-microflow-patterns.md
index 1868adc..8a25e7e 100644
--- a/skills/learned-microflow-patterns.md
+++ b/skills/learned-microflow-patterns.md
@@ -12,15 +12,16 @@ microflow (`PLM_GetExclusiveParts`, a PLM parts-flow project, 2026-07-23) before
 made an MCP-mode exec (see `learned-mdl-preflight.md` STOP rule 9) slow enough to hit the 5-minute
 default timeout.
 
-**Guideline, not a hard cap:** aim to keep a freshly-drafted microflow under ~30-50 activities. If a
+**Guideline, not a hard cap:** the Mendix docs limit is 25 elements; lint's `QUAL003` warns at 25 and
+`CONV009` (mxcli-bundled `assess-quality` skill) flags at 15 — but both count **top-level activities
+only**, so loop bodies are invisible to them: count those by hand (`microflow-preflight.md`). If a
 task naturally produces more (bulk seed data, a long linear pipeline), prefer splitting into
 sub-microflows by responsibility — e.g. one sub-microflow per entity/record-type being created,
 called in sequence from a thin orchestrating microflow — over one flat monolith. But some
 microflows genuinely can't be meaningfully shrunk (a single cohesive validation/decision sequence
 with real branching, for instance) — don't force an artificial split that just adds indirection
-without improving anything. The lint layer's own threshold (`CONV009`, `assess-quality.md`: max 15
-activities) is stricter still and will flag most things in this range anyway — treat both numbers
-as signals to *consider* a split, not a rule to satisfy mechanically.
+without improving anything — treat the numbers as signals to *consider* a split, not a rule to
+satisfy mechanically.
 
 **Bonus when a STOP-rule-9 (inline association-set) split is also needed:** if only part of the
 work needs MCP mode (setting associations) while the rest is plain attribute creation, split along
@@ -397,11 +398,9 @@ end;
 - **`not expr` → CE0117:** Mendix requires parentheses: `not(expr)`. `not $IsValid` is rejected. Always write `not($IsValid)`.
 - **LESSON-03:** Always use fully-qualified `Module.EntityName` in the `returns` clause. Unqualified entity names (e.g. `returns OrderDetail as $Var`) cause CE1613 "entity no longer exists" because the model checker cannot resolve the type. Always write `returns OrderRegistration.OrderDetail as $OrderDetail`.
 - **LESSON-04 — `retrieve $X from $obj/Assoc limit 1` → CE0018 + CE0136 (mxcli BUG):** mxcli generates a "Retrieve by Association" BSON activity with empty `Association` and `Entity` properties. Mendix rejects these with CE0018 ("Association property required") and CE0136 ("Entity property required"). **Fix:** replace with XPath DB retrieve: `retrieve $X from Module.Entity where [AssocPath/Module.Entity/Attr = $var] limit 1;`. **Pre-flight before using XPath:** (1) target entity is persistent (not an NPE), (2) all entities in the XPath path are persistent, (3) all objects being filtered on are committed to the DB — XPath queries the database, not in-memory objects. If any condition fails, use a different approach (pass as parameter, loop retrieve, etc.).
-- **Microflow canvas layout — RESET LAYOUT, not @position (LESSON-01+02):**
-  - `@position(x, y)` stores coordinates for individual activities but does NOT position the start event, end events, or merge nodes. Those are placed by mxcli at default coordinates that conflict with manual @position values, producing stacked or misaligned flows. `@position` is effectively useless for controlling visual layout.
-  - **Correct approach:** add `reset layout` between the signature and `begin`. This clears all `relativeMiddlePoint` positions. Studio Pro re-runs its auto-layout on next open, producing a clean horizontal flow automatically.
-  - **Syntax:** `create or modify microflow Module.Name (...) returns ... reset layout begin ... end;`
-  - **Rule:** always add `reset layout` to any `create or replace` / `create or modify` microflow script. Never rely on `@position` for layout control.
+- **Microflow canvas layout — omit layout annotations (LESSON-01+02, corrected 2026-09-25):**
+  - **Rule:** write no `@position` at all; mxcli's auto-layout places every statement (start, merges and ends included — `@start`/`@merge` exist and `describe` emits them). Partial hand placement is what breaks: auto-placed neighbours are not measured against hand-placed ones (MPR008/MPR011). If repairing a described flow by hand, annotate every canvas statement or none.
+  - **`reset layout` is a parse error** (`mismatched input 'RESET'`, still on v0.24.0) — BUG-28: never implemented upstream. Never write it. Measurements and the v0.24.0 if-branch defect: `microflow-preflight.md`.
   - **If/else branch geometry (for future reference when @position is fixed):** true branch (abort) → X > decision, Y < decision (goes up); false branch (main path) → X > decision, Y > decision (goes down). Both branches must have X > the decision diamond's X.
 
 ---
diff --git a/skills/mdl-cookbook-microflows.md b/skills/mdl-cookbook-microflows.md
index f46f131..5a20062 100644
--- a/skills/mdl-cookbook-microflows.md
+++ b/skills/mdl-cookbook-microflows.md
@@ -260,7 +260,9 @@ begin
   -- Check after exec and restore manually if missing.
   retrieve $SalesAreaDtoList from $Dto/OrderRegistration.SalesAreaData_Dto_OrderDetail_Dto;
 
-  -- PATTERN: LOOP over list — create + wire + commit each row inside the loop body.
+  -- PATTERN: LOOP over list — create + wire each row, collect it, ONE commit after the loop
+  -- (a commit inside the body is lint CONV011; see microflow-preflight.md).
+  $SalesAreaData_CommitList = create list of OrderRegistration.SalesAreaData;
   loop $SalesAreaDtoRow in $SalesAreaDtoList
   begin
     $SalesAreaData = create OrderRegistration.SalesAreaData (
@@ -273,8 +275,9 @@ begin
       CreatedBy = $currentUser/Name
     );
     change $SalesAreaData (OrderRegistration.SalesAreaData_OrderDetail = $OrderDetail);
-    commit $SalesAreaData on error rollback;
+    add $SalesAreaData to $SalesAreaData_CommitList;
   end loop;
+  commit $SalesAreaData_CommitList on error rollback;
 
   -- Set status to 01 (Draft editing) via shared header microflow.
   $UpdateOk = call microflow BusinessApp_Common.ACT_ApplicationCommonHeader_UpdateStatus(
@@ -564,7 +567,7 @@ end;
 | $currentUser | `$currentUser/Name`, `$currentUser/Email` | Built-in, no retrieve needed |
 | Log with concat | `log warning node 'N' '{1}' with ({1} = 'prefix' + $Var)` | Use {1} placeholder, not + in main string |
 | Inline conditional | `Attr = if $Dto != empty then $Dto/Attr else ''` | In CREATE parameter list |
-| Loop with persist | `loop $Row in $List begin ... create ... change ... commit ... end loop` | commit inside loop body |
+| Loop with persist | `loop $Row in $List begin ... create ... change ... add $X to $X_CommitList; end loop; commit $X_CommitList` | collect, then ONE commit after the loop — never inside (CONV011) |
 | STUB_ call | `$Result = call microflow Module.STUB_OpName(Param = $val) on error rollback` | Identical signature to real op |
 | Navigate after action | `show page Module.Page($Param = $var)` | After last commit, before return |
 | Safe sub-call | `... on error rollback` | On every CALL MICROFLOW that modifies data |
diff --git a/skills/microflow-loop-antipatterns.md b/skills/microflow-loop-antipatterns.md
index a351ad0..cf70925 100644
--- a/skills/microflow-loop-antipatterns.md
+++ b/skills/microflow-loop-antipatterns.md
@@ -176,5 +176,7 @@ Keep the reading honest:
 
 `skills/app-analysis.md` (owner), `skills/module-dependency-review.md`,
 `skills/existing-app-change.md` (a slice that touches a listed microflow inherits its
-finding), `skills/lint-that-actually-runs.md` (the lint-rule form of LOOP_TQ is a follow-up:
-it needs loop containment, which the Starlark API does not expose today).
+finding), `skills/lint-that-actually-runs.md` (a commit inside a loop is already caught by the
+Go built-in rule CONV011 NoCommitInLoop; retrieve, delete, REST and call inside a loop still have
+no lint rule, since the Starlark API does not expose loop containment — `skills/microflow-preflight.md`
+is the pre-write check for those).
diff --git a/skills/microflow-preflight.md b/skills/microflow-preflight.md
new file mode 100644
index 0000000..47bc6d4
--- /dev/null
+++ b/skills/microflow-preflight.md
@@ -0,0 +1,137 @@
+# Microflow Pre-flight — Loops, Size and Layout Before the First MDL Line
+**Applies to:** any mxcli project.
+
+**Purpose:** Decide a microflow's shape — what runs inside each loop, how many activities it
+really has, whether it carries layout annotations — before drafting it. Lint only sees the
+result after `exec`, and it cannot see inside a loop. Measured on **mxcli v0.24.0**
+(released 2026-09-24) on a scratch copy of a real model. Older binaries lay out differently;
+the advice is the same.
+
+---
+
+## Trigger — run this if ANY of these hold for the microflow you are about to write
+
+1. It has **any loop** (`loop … in`, or `while`).
+2. A **retrieve, commit, delete, REST call, Java action or sub-microflow call** is planned inside a loop.
+3. It has **more than one loop**, or a **nested loop**.
+4. Planned total is **more than 20 activities, counting loop bodies**. Why 20: CONV009 (15)
+   and QUAL003 (25) read the catalog's top-level `ActivityCount` only. A microflow with 20
+   activities inside one loop plus 2 outside counts as **3** and fires neither. This
+   preflight counts what lint cannot, and stops at 20 because drafts grow before they shrink.
+5. It **builds a list from a list** (create list + `add` in a loop).
+6. It **retrieves and commits the same entity** in one flow.
+
+None applies → post `microflow-preflight: no trigger` in chat and proceed.
+
+## The checklist — post it in chat before the first MDL line
+
+```
+microflow-preflight: <Module.Microflow>
+- Loops: N. Per loop: retrieve y/n · commit/delete y/n · call y/n · batch strategy · expected list size
+- Retrieves inside loops: 0 (else: moved before the loop, find/filter inside)
+- Commits/deletes inside loops: 0 — collected into <Entity>_CommitList, one commit after the loop
+- REST/Java/web-service calls inside loops: 0, or the batch endpoint / task queue named
+- Nested loops: N — each replaced by find/filter, or justified in one line
+- Lists built from lists: N — each a list operation, not loop + add
+- Activities: top-level T + all loop bodies B = T+B (≤ 20, else the SUB_ split named)
+- Top-level activities: T (≤ 15, else SUB_ flows named)
+- Decisions + loops: D (≤ 9, else guard chain moved to a VAL_)
+- Layout: no @position   (or: every canvas statement annotated, and why)
+```
+
+## Best practice → what catches it → how to write it first time
+
+| Practice (Mendix docs) | Caught after the fact by | Write it so |
+|---|---|---|
+| No commit inside a loop | **CONV011** NoCommitInLoop. Delete in a loop: **no lint rule — preflight is the only check** | `$Order_CommitList = create list of Sales.Order;` · in the loop `add $Order to $Order_CommitList;` · after it `commit $Order_CommitList;`. If every item changed, `commit $Orders;` after the loop |
+| Commit late, events on purpose | `mxcli check` **MDL067** (info): a bare `commit` is WITH EVENTS, so a commit in a loop fires every handler once per item | One commit at the end; write `without events` only when you mean it |
+| No database retrieve inside a loop | **no lint rule — preflight is the only check** | Retrieve once before the loop; inside, `$Match = find($List, Name = $Item/Name);` |
+| No REST / Java / web-service call per iteration | **no lint rule — preflight is the only check** (CONV013 checks error handling on the call, not where it sits) | Batch endpoint, or a task queue where the loop only enqueues. No `on error` inside a loop body — CE0644, see `learned-microflow-patterns.md` |
+| Bounded lists | **no lint rule — preflight is the only check** (`mxcli check` MDL068 catches only an unbounded `range`) | `retrieve … sort by … limit 1000 offset $Offset;`, one batch per iteration or per `SUB_…_Batch` call |
+| Nested loop used as a lookup | `mxcli check` **MDL001** nested-loop warning (before exec). After exec: none. Each loop adds 1 to QUAL001 | Replace the inner loop with `find`/`filter`; a genuine N×M aggregation stays, with an annotation |
+| List built from a list | **no lint rule — preflight is the only check** | `filter`, `sort`, `range`, `union`, `subtract` list operations |
+| At most 25 elements per microflow | **CONV009** at 15 (info), **QUAL003** at 25 (warning), both top-level only | Split by responsibility: `ACT_` = UI + calls, `VAL_` returns Boolean, `SUB_` persists |
+| Keep decision logic simple | **QUAL001** McCabe > 10 (1 + decisions + loops) | Move a guard chain into a `VAL_` |
+
+Counting in an expression uses `length($List)`, never `count()` (`learned-mdl-preflight.md` STOP row 10).
+
+## Layout — omit `@position` entirely
+
+Upstream now states the toolkit's rule. `mxcli syntax microflow.layout` on v0.24.0 says:
+*"Prefer no @position at all to a few: hand-placed statements are not measured against what
+the builder puts around them."* A statement with `@position` is never moved. Every statement
+without one is placed by the builder, which does not look at your hand-placed coordinates.
+
+**The failure. Every one of these partial-annotation probes raised a lint finding on v0.24.0:**
+
+| Probe | What was hand-written | Result |
+|---|---|---|
+| Only the loop annotated | `@position(970, 200)` on the loop, nothing else | **MPR008**: an auto-placed neighbour lands on the loop |
+| Hand spacing | activities 100 px apart | **MPR008** overlap (the engine's own pitch is 160) |
+| Negative body coordinates | `@position(-100, 80)` inside the loop | **MPR011** ×2: the child escapes its loop box |
+
+**The clean version** is the same loop with no annotations. `describe` on it shows the layout
+the builder produced (abbreviated):
+
+```
+@position(360, 200)   retrieve $Items from ProbeMF.Item;
+@position(520, 200)   $Item_CommitList = create list of ProbeMF.Item;
+@position(940, 200) @anchor(from: right, to: left)
+loop $Item in $Items begin
+  @position(210, 80)  …   @position(370, 80)  …   @position(530, 80)  …
+end loop;
+@position(1360, 200)  commit $Item_CommitList;
+```
+
+The builder re-lays-out every unannotated `create or modify`. v0.24.0 geometry, for reading `describe` output (centres; body
+coordinates are relative to the loop box's top-left corner; n = activities in the body):
+
+| Element | Position |
+|---|---|
+| Body child *i* (0-based) | (210 + 160·i, 80) |
+| Loop centre | previous centre + 80·n + 180 |
+| Next activity after the loop | loop centre + 80·n + 180 |
+| Sequential pitch | 160 |
+
+**`RESET LAYOUT` does not parse** on v0.24.0: `mismatched input 'RESET'` (BUG-28, never
+implemented upstream). Never write it. If you have to repair a flow by hand, annotate **every**
+canvas statement or none.
+
+## Known v0.24.0 defect — loop followed by an activity inside an `if` branch
+
+The script below is correct, and the engine still lays it out wrong:
+
+```
+if … then
+  loop $Item in $Items begin … end loop;
+  commit $Item_CommitList;
+else … end if;
+```
+
+The builder places the merge at (1230, 200) and the commit at (1210, 200). `mxcli lint` reports
+**MPR008** `Activities '(merge)' (1230,200) and '(unnamed)' (1210,200) overlap`. The lint
+ratchet then rises on a script with nothing wrong in it. Plain if/else and a loop-only branch are clean.
+
+**Remedy (not `@position`):** move the loop into its own `SUB_` microflow, which the size
+table asks for anyway. Or move the following activity to after `end if`. Name the chosen
+remedy on the checklist's Layout line.
+
+## Verify — read the BUILD-LOG row
+
+After `./bin/exec.sh`, the lint ratchet writes its verdict into the same BUILD-LOG row:
+`lint unchanged vs baseline`, or `⚠️ applied, LINT ROSE` with `lint ROSE: <rules>`.
+
+If the rules listed include CONV011, CONV009, QUAL003, QUAL001, MPR008 or MPR011 after a posted
+checklist, **the preflight failed. Say so in chat**, fix the script and re-run. Do not accept
+the rise with `--update-baseline`. Lint cannot see a retrieve or REST call inside a loop, so a
+clean row proves only the rows lint covers. The checklist is the record for the rest.
+
+## Not verified
+
+- That `mx check` passes a flow whose loop child escaped its box (MPR011). This comes from the
+  rule's source comment only.
+- CONV013 / CONV014 firing on a REST or Java call.
+- The `while` + `limit … offset` batch recipe run end to end. `while` itself executes on v0.24.0.
+- Whether a `/** … */` doc comment round-trips into the microflow's Documentation.
+- Nanoflow-vs-microflow guidance. No current Mendix docs page was found.
+- Whether upstream fixes the if-branch merge overlap in a later release.