Add context-pack.sh: one file per build step, brain wired into the build loop

CHANGELOG.md

@@ -16,6 +16,11 @@ 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
+- fix(project-bin/context-pack.sh): **the pack finds the brief in both layouts.** It looked only for `architecture/modules/<Module>-brief.md`; the toolkit's own convention (`iterative-build-loop.md`) and two real specs use `architecture/modules/<Module>/module-brief.md`, so every dispatch there exited 2 ("no brief") and the helper fell back to a reading list. The folder form is tried first, then the flat form; `--brief` still overrides. Probed on a real app's scratch copy in both layouts: identical packs, exit 0; an unknown module still exits 2 and names both paths. — MendixMau
+- fix(project-bin/context-pack.sh): **the pack names the rule files a step must read, and an entity step no longer stops to ask for a folder.** A new "Rules" section lists the files by step kind: the preflight STOP table always, microflow patterns for logic, page pre-flight plus the widget syntax skill for pages, and the domain-model skill for entities. Both mxcli skill layouts resolve (`<name>.md` and `<name>/SKILL.md`). Why: in a five-step module bench on a real app's scratch copy (pack vs no pack, two lanes each), helpers given a pack skipped skill reads the pack did not mention, and one reported the preflight skill "not available" although it was installed. An entity step whose name is not in the folder plan was told "escalate", and the helper stopped; the cell now says entities, associations and enumerations live in the domain model. — MendixMau
+- new(project-bin/context-pack.sh): **a helper gets one file for its build step instead of a reading list.** The module brief gains a `### Build steps` table (one row per dispatch: what the step builds, which existing elements it reads, the app's own example to copy, and the `mxcli brain` slice). `bin/context-pack.sh <Module> <Step>` turns that row into one pack: the folder from the brief's folder plan, the *why* from `mxcli brain brief`, the brief's arch constraints, and a live `DESCRIBE` of every element it reads, of the example, and of anything the step changes rather than creates. Nothing is copied into the brief; the pack is regenerated per dispatch and never committed. A name the model does not have exits 1 and is listed, so a typo in the brief fails at dispatch, not inside the helper's script. `iterative-build-loop.md` now turns the project brain on at build start (`brain init`, capture with forward anchors, `brain plan` as the progress measure) and has each dispatch carry a pack; `mdl-agent` reads the pack first and captures a *why* it learned with `mxcli brain capture`. Field run: a real app's scratch copy, one bulk-accept microflow, 3 helper runs with a pack vs 3 without, same brief and brain: ~9% fewer tokens (130k vs 144k), ~40% fewer tool calls (13 vs 21) and ~40% less time (60 s vs 101 s); every run passed `mxcli check`, exec'd with 0 new mx errors and used the planned folder. Probed on single-tree and two-tree (`app/`) layouts; not yet run on Windows. — MendixMau
+- fix(project-bin/context-pack.sh): **the pack now names the traps a step walks into.** A page step lists the attributes of every entity it reads that a `TEXTBOX` cannot bind (DateTime, Boolean, enumeration) — `mxcli check` passes them, mx check fails with CE2421. A step that changes an existing element gets its `mxcli impact` list, so the helper keeps its callers' contract without looking them up. The brain brief's headings now nest under the pack's own. Field run on a real app's scratch copy, 10 helper runs across five step kinds (new page, change an existing microflow, a misspelt name in the brief row, a 5k-token pack, no brain yet): the two page runs with the earlier pack each hit CE2421 (1 and 3 errors) although the types were in the pack; the two re-runs with the watch-out had 0, as did the two runs with no pack. Page runs with a pack used ~25% fewer tool calls and ~30% less time than without (n=2 each; token counts too noisy at n=2 to quote). The change run moved the microflow into its planned folder and kept both roles' execute rights; the misspelt-name run reported the typo and used the real association; microflow packs are byte-identical to before. — MendixMau
+- learn(process/context-pack-bench-2026-10-01.md): **the context-pack A/B bench is written up, with where the pack should live.** 16 scored helper runs on a scratch copy of a real app: all pass check and exec; pages lost CE2421 errors (4 to 0) once the watch-out landed; tool calls about 25-38% fewer and time about 30-40% less; tokens -9% on microflows but not proven on pages (noise 69k to 173k). Proposes the split: mxcli owns turning names into one context document (the read-side twin of folding `mx check` into `mxcli check`), the toolkit keeps the brief row, folder plan and dispatch. — MendixMau
 - fix(bin/context-audit.sh): **a Read `offset` or `limit` stored as a string no longer crashes the audit, and the script now exits 0 as its header promises.** Older transcripts store these as strings, sometimes as junk like `'30, 90'`, and `offset - 1` raised a TypeError in the embedded reader, which stopped the whole run. They are now read as numbers when they parse and fall back to the Read tool's defaults (offset 1, limit 2000) when they do not; if the reader ever dies on an unseen transcript shape, the script says the numbers are partial and still exits 0. Field run: 1,300 sessions and 724 subagent runs on a Mac (2026-08-27 to 2026-09-30), which crashed on the old version. — MendixMau
 - fix(routing): **`learned-mcp-patterns.md` is no longer always-on in the build stage; it loads before the first MCP write in a session.** It sat in the Stage 5 baseline pack and in `mdl-agent`'s always-read rows, so every build session and every MDL helper agent carried ~4,900 tokens of MCP save/handoff rules and JSON payloads, including sessions that never open Studio Pro and cloud containers where MCP does not exist. Choosing the write mode is already Step 0 of `learned-mdl-preflight.md`, which stays always-on, so nothing is lost at the moment of choice; the MCP skill's trigger now names the moment it is needed (`mxcli --mcp` exec or a `pg_*`/`ped_*` call). Stage 5 pack: 74,055 → 71,443 words, 23 → 22 files; baseline 79,752 → 77,140 words. Found by the context report (`bin/context-audit.sh`, `bin/render-routing.sh --check`). — MendixMau
 - new(bin/context-audit.sh): **what fills the context window, per file, from the real Claude Code transcripts on this machine.** `token-burn.sh` says how many tokens a project burned; this says which files burned them, so decisions about splitting, trimming or un-routing a skill rest on measured runs instead of `wc` on the skill files. It reports: the context size before any work (first call, input + cache, for sessions and for subagents separately); the instruction files loaded every run (CLAUDE.md, CLAUDE.local.md) and their size; every file read (Read tool and simple shell reads like `cat`, `sed -n`, `git show REV:path`, following `cd` and `VAR=`) with reads, sessions, total and per-read size, and re-reads within a session (paging through a file is not a re-read; asking for the same part again is); other tool output by tool; and each compaction with the files read before it. Project names are masked by default (`project-1/architecture/modules/*.md`), so the output is safe to paste; `--names` shows them locally. First field numbers, from a captured pipeline-start subagent: it starts at 52,503 tokens before reading anything, then reads the runbook in 6 pages with 2 repeats. Fixture: `tests/wave2/test-context-audit.sh` over a scrubbed real capture. — MendixMau

README.md

@@ -596,6 +596,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini
 
 | Task | Skill to load |
 |---|---|
+| Dispatching a build step to a helper — generate its one-file pack (the brief's Build steps row, mxcli brain brief, live DESCRIBEs, example, folder) and hand over the path instead of a reading list. Measured: ~9% fewer tokens, ~40% fewer tool calls, same quality | `project-bin/context-pack.sh` |
 | Building a module with mxcli — verified, iterative, coverage-checklist gated | `skills/iterative-build-loop.md` |
 | After marking a module done, or any time "how much is built vs proven" is asked — renders build-plan.html from done- prefixes and verify-module.sh/improvement-register.md, kept as two honestly separate views; --json writes architecture/build-plan.json parsed from build-plan.md's Phase headings (a plan with no Phase headings gets no file) | `project-bin/build-plan-status.sh` |
 | Turning a client-derived Mendix app into a clean, shareable demo with zero client fingerprint — branding, data, custom widgets | `skills/anonymize-client-app-for-demo.md` |

ROUTING.md

@@ -134,6 +134,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
 |---|---|---|---|---|
 | Reviewing any module before calling it done — the ONE pass: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated | `skills/module-review.md` | mdl,review,test | 5,6 | baseline |
 | Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides | `bin/exec-approval.sh` | mdl,gate | 5,6 | baseline |
+| Dispatching a build step to a helper — generate its one-file pack (the brief's Build steps row, mxcli brain brief, live DESCRIBEs, example, folder) and hand over the path instead of a reading list. Measured: ~9% fewer tokens, ~40% fewer tool calls, same quality | `project-bin/context-pack.sh` | mdl | 5 | ondemand |
 | Building a module with mxcli — verified, iterative, coverage-checklist gated | `skills/iterative-build-loop.md` | mdl,gate | 5 | ondemand |
 | After marking a module done, or any time "how much is built vs proven" is asked — renders build-plan.html from done- prefixes and verify-module.sh/improvement-register.md, kept as two honestly separate views; --json writes architecture/build-plan.json parsed from build-plan.md's Phase headings (a plan with no Phase headings gets no file) | `project-bin/build-plan-status.sh` | architect,gate,review | 4,5,6 | ondemand |
 | Turning a client-derived Mendix app into a clean, shareable demo with zero client fingerprint — branding, data, custom widgets | `skills/anonymize-client-app-for-demo.md` | mdl,review | 6 | ondemand |

agents/mdl-agent.md

@@ -68,6 +68,7 @@ Open a file when its When cell happens in your task, not all of them at the star
 | `skills/learned-stylegallery.md` | Building or using the in-app design gallery |
 | `project-bin/check-design-portability.sh` | Before porting ds.css into SCSS, and at the Stage-3 gate — greps the stylesheet for rules that cannot match the HTML Mendix emits (rem against the real root, table/th/td selectors, positional row selectors). mx check, mxcli check and mxcli lint are all blind to CSS |
 | `skills/learned-mcp-patterns.md` | Before the first MCP write in a session (Studio Pro open: `mxcli --mcp` exec, or pg_*/ped_* calls) — save after every write, the handoff sequence, confirmed JSON payloads. Choosing the write mode itself is Step 0 of learned-mdl-preflight.md |
+| `project-bin/context-pack.sh` | Dispatching a build step to a helper — generate its one-file pack (the brief's Build steps row, mxcli brain brief, live DESCRIBEs, example, folder) and hand over the path instead of a reading list. Measured: ~9% fewer tokens, ~40% fewer tool calls, same quality |
 | `bug-logs/mxcli-bugs.md` | Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words |
 | `skills/cloud-dev-environment.md` | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim |
 | `skills/microflow-loop-antipatterns.md` | 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 |
@@ -125,6 +126,12 @@ this summary. The hard STOPs below are inline on purpose; never route around the
   the Wiring block; format in `module-brief.md`): roles/access, screens, validation, write-mode plan,
   and pointers to wireframes/domain MDL. **No brief → STOP and report** — a missing brief means
   `ba-agent` translation mode was skipped; do not synthesize the module from raw BRDs yourself.
+- **Got a context pack?** If the dispatch names one (`.mxcli/packs/<Module>-<Step>.md`), read it
+  right after this file: it already holds the brief's row for this step, the brain brief, live
+  DESCRIBEs of what the step reads, the app's example to copy and the target folder. Don't
+  re-DESCRIBE what it shows; open the brief or BRD only for what it lacks.
+- **Learned a *why* worth keeping?** (a pattern chosen, a trap hit) `mxcli brain capture "<why>" -a
+  @Module.Element` — capture only and name the id in your report; a person promotes it.
 - **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

bin/lib/install-manifest.sh

@@ -106,7 +106,7 @@ MXTK_AGENTS_STAGE_BUILD="mdl-agent.md gate-agent.md test-agent.md review-agent.m
 # directory. prototype-route.js is the one reader and writer of design/prototype.html's section
 # format, so page-fidelity.js, check-page-shell.sh and check-prototype-links.js resolve it as a
 # sibling too.
-MXTK_PROJECT_BIN="assemble-prototype.js prototype-route.js check-prototype-links.js wf-add-path-terminators.py wf-set-call-captions.py mxunit_bson.py _common.sh app-facts.sh _claims.sh snapshot-mpr.sh restore-mpr.sh exec.sh save-sp.sh restart-sp.sh check-sp-health.sh verify-module.sh test-stack-up.sh fixture-manifest.sh check-root-clean.sh lint-gate.sh close-task.sh conformance-check.sh coverage-preflight.sh graph-sweep.sh review-module.sh coherence-cadence.sh build-plan-status.sh done-drift-check.sh page-scope.sh render-improvement-register.sh check-design-portability.sh check-design-reaches-app.sh check-page-shell.sh page-fidelity.js model-stamp.sh verify-model.sh install-project-hooks.sh session-check.sh constants-audit.sh"
+MXTK_PROJECT_BIN="assemble-prototype.js prototype-route.js check-prototype-links.js wf-add-path-terminators.py wf-set-call-captions.py mxunit_bson.py _common.sh app-facts.sh _claims.sh snapshot-mpr.sh restore-mpr.sh exec.sh save-sp.sh restart-sp.sh check-sp-health.sh verify-module.sh test-stack-up.sh fixture-manifest.sh check-root-clean.sh lint-gate.sh close-task.sh conformance-check.sh coverage-preflight.sh graph-sweep.sh review-module.sh coherence-cadence.sh build-plan-status.sh done-drift-check.sh page-scope.sh render-improvement-register.sh check-design-portability.sh check-design-reaches-app.sh check-page-shell.sh page-fidelity.js model-stamp.sh verify-model.sh install-project-hooks.sh session-check.sh constants-audit.sh context-pack.sh"
 
 # Files in project-bin/ that are deliberately NOT installed into projects. The reverse check
 # below flags anything named by NEITHER list, so a new file in project-bin/ has to be either

bin/lib/skill-routing.tsv

@@ -108,6 +108,7 @@ check-prototype-links	project-bin/check-prototype-links.js	Before wireframes pas
 learned-mcp-patterns	skills/learned-mcp-patterns.md	Before the first MCP write in a session (Studio Pro open: `mxcli --mcp` exec, or pg_*/ped_* calls) — save after every write, the handoff sequence, confirmed JSON payloads. Choosing the write mode itself is Step 0 of learned-mdl-preflight.md	mdl	5	ondemand	build/mdl
 module-review	skills/module-review.md	Reviewing any module before calling it done — the ONE pass: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated	mdl,review,test	5,6	baseline	build
 exec-approval	bin/exec-approval.sh	Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides	mdl,gate	5,6	baseline	build
+context-pack	project-bin/context-pack.sh	Dispatching a build step to a helper — generate its one-file pack (the brief's Build steps row, mxcli brain brief, live DESCRIBEs, example, folder) and hand over the path instead of a reading list. Measured: ~9% fewer tokens, ~40% fewer tool calls, same quality	mdl	5	ondemand	build
 testing-shape	skills/testing-shape.md	Before calling any module tested — what testing a module means, and the false-green register of confirmed ways a test reports green over a broken feature	test,gate,review	5,6	baseline	verify
 verify-module	project-bin/verify-module.sh	Finishing any module — before calling it done. One command that runs every instrument and keeps "instrument faulted" apart from "feature failed"; in a wired project run the installed copy at bin/verify-module.sh	mdl,gate,test,review	5,6	baseline	verify
 mxcli-bugs	bug-logs/mxcli-bugs.md	Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words	mdl,gate	5,6	ondemand	diagnose