Skip to content
Draft
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
`docs/RELEASE-PROCESS.md` §8.

## Unreleased
- new(kickoff): **`bin/kickoff.sh <project> --mode <poc|requirements-driven|migration|change> [--build-type full|poc] [--interview steering|assist|auto] [--answers file] [--by who]` writes the kickoff in the parsed form (#821 point 3)**: the `Entry mode:` / `Build type:` / `Interview mode:` register lines, one Stage-P Decisions row each (CONFIRMED only with `--by <person>`, the person who answered; otherwise ASSUMED "no person named", upgraded by a later `--by` run), and one answer marker per intake section — Q1/Q9/Q16 from the flags, `--answers` lines verbatim, poc-build.md's verbatim markers for a POC, the template's stated defaults `Assumed (auto-mode)` (plus an Assumptions line) under auto, and under steering/assist the unasked questions listed, never invented, an unstated build type (Q16) included (a POC's unstated Q9 takes poc-build.md's marker) — then prints `gate-check.sh <p> P`'s verdict. Idempotent (a second run changes no byte); unknown values exit 2 with the accepted list; a declared mode that differs exits 3 (a mode change is a decision a person records). The kick-off brief (run it after the user answers, with `--by`) and `poc-build.md` name it; it needs the `Entry mode: poc` token (#819 commit) for `--mode poc`. Fixture `tests/wave2/test-kickoff.sh` (real `init-project.sh` scaffold and gate; 31 of 31; master has no kickoff.sh) — two simulated builds, 2026-11-20 (kickoff hand-assembled with Python heredocs in 11-13 turns)
- fix(gate-check, obligations): **a FAIL on a format the toolkit parses prints the whole accepted shape, once per run (#821 point 1)**: new `bin/lib/format-hints.sh` holds one minimal passing example per parsed format — intake answer markers (Stage P), the build plan's numbered rows, Kind cells and three closing rows (Stage 4), the coverage ledger's two tables (Stage 4, incl. the one-element wildcard rule), the LOOK report (`VALID AT`, `PROOF-OF-LOOK`, Stage 5 look and the look/final-look obligations), the prototype LOOK (`PROTOTYPE-SHA`, obligation `prototype-look`) and the improvement-register row report-disposition wants. `gate-check.sh` prints the shapes its FAILs owe after the stage list; obligation FAULTs print theirs after the obligation block. Informational: no verdict or exit code changes. Every example is run through its real parser by the fixture (a hand-drafted coverage example failed SECTION-WIDE and a prototype example failed its own denominator before this). Fixture `tests/wave2/test-fast-lane-format-hints.sh` (real `init-project.sh` scaffold; 13 of 13 on the branch, 7 of 13 on master, whose 6 failures are the missing shapes) — two simulated builds, 2026-11-20 (a prototype LOOK took 5 gate runs; 10 and 19 calls read gate source before the first write)
- fix(gate-check): **build-ready WARNs, not FAILs, on `{{…}}` slots in agent stubs no role was dispatched with (#821 point 2)**: the slot line is now `⚠ agent(s) still have unfilled placeholders: …` and still names every slot (multi-line ones as `{{NAME…}}`); it FAILs again for mdl-agent once mdl-agent's dispatch log exists (`.claude/loop/dispatch/<Module>/scripts.tsv`, agents/README.md step 8a), the only dispatch record the toolkit keeps. Each stub still refuses to run while a slot is left (its line 11), so a dispatched role cannot run unfilled. Supersedes the 2026-11-13 decision that any unfilled slot FAILs. `bin/status.sh`'s WATCH item is unchanged. Fixture `tests/wave2/test-fast-lane-agent-slots.sh` (stubs from a real `init-project.sh`; 8 of 8 on the branch, 3 of 8 on master) — two simulated builds, 2026-11-20 (0 subagents dispatched; 3 and 6 calls spent filling slots before the first write)
- fix(gate-check, poc): **a POC build owes no build-ready, Stage 5 reads MANUAL, and `Entry mode: poc` is a declared mode (#819 options 1 and 3)**: under `Build type: poc`, `gate-check.sh <p> build-ready` still prints its checklist but ends `BUILD-READY: N/A (Build type: poc)` with exit 0, no open-questions escalation and no `.build-ready-pass` stamp (exec.sh's plan rule already exempted poc); Stage 5's look check reads MANUAL with the unseen pages still named, as `skills/poc-build.md` promised; the tokeniser (`project-bin/_position.sh`) accepts `poc`, which sets the build type to poc and silences the "No entry mode declared" banner (artifact and obligation rows stay owed exactly as for `Build type: poc`), unless a `Build type:` line names full: then full wins and gate-check and exec.sh print the conflict (under auto exec.sh holds it to the requirements-driven plan rule), and `Build type: poc → full (CR-01)` now reads as full, with the same warning (only the WORD full counts: `poc (fullscreen kiosk)` stays poc, `mxtk_bt_names_full`); `bin/ready.sh` names a POC's unseen pages (it parses the MANUAL line's `look: N of M … never looked at` text); the kick-off brief's line 3 applies build-ready to full builds only. Full builds unchanged. Fixture `tests/wave2/test-fast-lane-poc.sh` (real `init-project.sh` scaffold; 25 of 25 on the branch, 6 of 15 on master before the review cases) — simulated unattended POC build, 2026-11-20 (it fabricated an sme-questions.md to clear build-ready)
- new(doctor, bug ledger): **a guard for mxcli's silent MxBuild fallback**: when the project's Mendix version is not in `~/.mxcli/mxbuild/` (and no Studio Pro of that version exists), `mxcli docker build` / `docker check` fall back to the newest cached MxBuild and print its path but no version warning (`run --local` is exact-or-refuse); `bin/doctor.sh` now warns, naming the model version, the cached ones and `./mxcli setup mxbuild -p <app>.mpr` (`mxtk_mxbuild_cache_gap`, warning only, never changes a gate). Ledger entry `BUG-DRAFT-mxbuild-silent-version-fallback`; upstream issue not filed. — a four-app Mendix build (field run), independent review
- fix(gate-check): **a fresh clone no longer FAILs Stage 3 as "stale render"**: `blueprint.html` / `process-map.html` freshness used `[ render -ot source ]`, a nanosecond mtime compare, and a checkout stamps files in directory order (`process-map.html` lands before `process-model.json`), so an unedited project read stale on every clone (reproduced: 200-wireframe checkout, 10 of 10 clones). New `bin/lib/render-fresh.sh` keeps `-ot` as the first test (a pass never flips, no git call) and, only where `-ot` would FAIL, asks git once per render (one `log`, one `status`) whether the source was committed after the render's commit; measured 0.19 s for 200 sources all `-ot`-stale on a 300-commit history (a per-source git version cost 12.9 s). Limit: a depth-1 clone cannot see a genuinely stale render. Field run: a four-app Mendix build checked out on a second machine. — a four-app Mendix build (field run), independent review
- fix(test-stack-up, e2e-harness-base): **the app port follows the app's configured port, and a multi-app start is no longer pinned to 8080**: with no `APP_PORTS`, `test-stack-up.sh` puts `RUN_LOCAL_APP_PORT`, then `APP_PORT` from the `.docker/.env` beside the `.mpr` (`apps/<App>/.docker/.env`; the project-root one as fallback) first, ahead of the old fixed `8080 8081 8084` tail. A fresh `run --local` start for a model under `apps/` with no handshake and no configured port used to fall back to 8080 for every app (`--app-port 8080`); it now exits 4 naming `RUN_LOCAL_APP_PORT`. `e2e-harness-base.md` states that a PAD/Docker runtime listens on 8080 *inside* the container only. Fixtures T28–T32 added. Field run: a four-app Mendix build on 8081–8084 whose fresh start failed with every app pinned to 8080. — a four-app Mendix build (field run), independent review
Expand Down
9 changes: 6 additions & 3 deletions CONVERSION-RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,12 @@ sources under it, never a different definition of done.
```text
Follow the toolkit's process: skills/conversion-runbook.md, from Stage P, stage by stage.
1. Run bin/init-project.sh <project-root> first, before writing PROJECT.md or touching the model.
2. Declare the entry mode and build type at kickoff (intake Q1 and Q16); never switch them later
without a recorded decision (conversion-runbook.md → Entry Modes, "Mode changes are decisions").
3. Stage 5 only after stages 1-4 pass their gates and bin/gate-check.sh <p> build-ready passes.
2. Ask the entry mode and build type at kickoff (intake Q16 first, then Q1); after the user answers,
record them with bin/kickoff.sh <p> --mode <m> --build-type <b> --interview <i> --by <name>; never
switch them later without a recorded decision (conversion-runbook.md → Entry Modes, "Mode changes
are decisions").
3. Full build: Stage 5 only after stages 1-4 pass their gates and bin/gate-check.sh <p> build-ready
passes. Build type: poc: follow skills/poc-build.md instead (no build-ready; Stage 5 is MANUAL).
4. Close every stage on a clean gate (bin/gate-check.sh <p> <stage>) and commit its output.
5. Stop at a gate that does not pass; report it, do not route around it.
"Done" is the declared mode's steps done and their gates clean — not only journeys passing.
Expand Down
Loading
Loading