Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
cf0d2b2
process(exec, entry modes): declared position banner, refuse-once pla…
claude Nov 17, 2026
1da1d80
process(entry modes): mode contract, unattended-first plan rule, regi…
claude Nov 17, 2026
86114c5
fix(mode contract): keep master's mode-column tokens; poc stays its o…
claude Nov 17, 2026
038c1cd
test(mode contract): drift guard — every modes-column token is one th…
claude Nov 17, 2026
cb7c0fa
fix(plan rule): review fixes — aggregate stage-4 waiver, ignore the s…
claude Nov 17, 2026
573f9df
Merge branch 'claude/entry-mode-plan-rule' into claude/mode-contract
claude Nov 17, 2026
1d68ffd
fix(gate-check, status): banner is warn-only even without bin/lib; CW…
claude Nov 17, 2026
fda6faf
Merge branch 'claude/entry-mode-plan-rule' into claude/mode-contract
claude Nov 17, 2026
01e0c7a
Merge remote-tracking branch 'origin/master' into claude/mode-contract
claude Nov 17, 2026
dac0e6e
Merge remote-tracking branch 'origin/master' into claude/entry-mode-p…
claude Nov 17, 2026
5e3d8d7
Merge branch 'claude/entry-mode-plan-rule' into claude/mode-contract
claude Nov 17, 2026
9d566a2
fix(tests): POSIX leading paren on the drift guard's case inside $(..…
claude Nov 17, 2026
b148b8d
fix(mode contract): review fixes — fit-gap wording, build-ready stamp…
claude Nov 17, 2026
e57fc4c
Merge remote-tracking branch 'origin/master' into claude/entry-mode-p…
claude Nov 17, 2026
d8e52ed
Merge branch 'claude/entry-mode-plan-rule' into claude/mode-contract
claude Nov 17, 2026
a918bd2
fix(tests): the Bug filing opt-in lives in bin/lib/register-skeleton.…
claude Nov 17, 2026
0c7795d
Merge master bf1d2e9 (#790 squash) into claude/mode-contract: #791's …
claude Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
- fix(obligations): **`Must-haves: advisory` for projects already past Stage 5 when the must-haves row arrived (follow-up to #787)**: `sync-project.sh` writes one `Must-haves:` line into `PROJECT.md` when none exists, and only then: `advisory — joined at stage N before the must-haves row existed` when gate-check's derived Current stage or `Adopted at stage:` is 6 or 7, else `bound`. `init-project.sh` writes `bound` for new projects. An advisory project's `Obligation must-haves` row reads `ADVISORY` and is left out of the pending count; `bound` keeps PENDING. It is keyed on the written line, not the project's position: a position check would silence a new project the day it passed Stage 5 without the marks. Fixture `tests/wave2/test-must-haves-advisory.sh` — owner request at the review of #787
- fix(obligations): **a quality floor in every entry mode: no per-module obligation reads PASS by absence, and a new `must-haves` row owes one mode-independent checklist per module**: with no module brief and no verify run, `obligation-check.sh` printed `Obligation look PASS — no module has been opened for work yet; nothing owed` (and the same for fidelity, sweep, journeys) on a project that had built ~78 pages and reviewed 0. Now an empty planned scope falls back to the modules that hold built pages, read from the look ledger (`.claude/loop/look/owed.tsv`), else page statements in the project's `*.mdl` scripts, else `.claude/loop/page-scope.json`, each looked for at the root, `app/` and `apps/*/`; every module row reads PENDING with an `OWED BY WHAT WAS BUILT: N page(s) built in M module(s) (...), K of M module(s) discharged` line. A model that has been built on (exec rows in `docs/BUILD-LOG.md`, `*.mdl` scripts, or a derived stage at 5+) with no countable pages is one FAULT naming `bin/page-scope.sh`, never "0 pages"; a `.mpr` with no build evidence (a fresh scaffold) keeps master's PASS line, so `bin/status.sh` still reads `modules opened: 0`. `existing-app-change` never takes scope from `page-scope.json`, which lists the whole model. A project with briefs keeps every earlier verdict. `skills/must-haves.md` (new, on demand) is the single source of poc-build.md's 12-row must-have checklist, generalised to every build type, plus row 13: every region the design shows is on the built page, counted; `poc-build.md` points to it, `module-review.md` stage 5 requires its mark `docs/progress/must-haves/<Module>.md` (first line `13 of 13 rows ticked or NOT DONE with a reason`). Informational, like every obligation row: no gate verdict or exit code changes; synced projects at Stage 5+ gain one `must-haves` PENDING row per module. Always-loaded words 64,984 -> 65,032 (budget 80,000). Fixture `tests/wave2/test-obligation-quality-floor.sh` — two field runs, unattended and requirements-driven, Nov 2026
- process(exec, entry modes): **the entry mode is a declared fact every tool reads, and a pipeline-mode project no longer builds without a plan by default**: with no `Entry mode:` and no `Adopted at stage:` line (register or intake), `bin/status.sh` (both views, plus a NEXT rule), `bin/gate-check.sh`'s summary and every `bin/exec.sh` run print one banner, and the BUILD-LOG row is tagged `no entry mode declared`; warn-only. In `Entry mode: migration` or `requirements-driven`, the first MDL write with no plan evidence is refused ONCE (nothing locked, snapshotted or written; `verdict=refused`), remedy in one line: run stages 1–4, or `gate-check.sh --adopt 5 --reason ...`. Cleared by outside evidence (guard rule 6): adoption at 5+, a reasoned `Waived stage 4:`, gate-check's readout at Stage 5+, or `architecture/build-plan.md` plus a module brief (root or `apps/<App>/`); a re-run after the one refusal goes on, tagged `no plan`. Never refused: `a-la-carte` (new explicit mode: no pipeline, audit or tooling use; gate-check reads its stages WAIVED by mode), `greenfield`, `Build type: poc`, change an existing app, `--patch`. The one entry-mode tokeniser moves to `project-bin/_position.sh` (pure bash, no process starts; installed beside exec.sh, `bin/lib/entry-mode.sh` is now a shim) — identical output on 44 inputs against the old one. Runbook: greenfield's "stages 1–4 collapse to whatever plan the user already has" becomes a design front end (`poc-build.md` steps 1–4, then a short plan with a few lines per module); `design-artifacts.md` Step 2a adopts a supplied prototype by mapping every screen in `design/wireframes/PAGE-MAP.tsv`, and `ui-preflight-pages.md`'s wireframe STOP accepts a mapped prototype. Fixture `tests/wave2/test-entry-mode-plan-rule.sh` (single tree + `apps/<App>/`, register and intake captured from `init-project.sh`) — two field runs, Nov 2026, requirements-driven with a frozen spec and clickable prototypes: ~78 pages built with no plan or target
- process(entry modes, unattended): **the mode contract, and unattended as the primary case** (stacked on the plan-rule PR): `bin/lib/artifact-manifest.tsv`'s existing modes column (tokens unchanged: `migration`, `requirements`, `greenfield`, `existing-app-change`, as `entry_mode_token` produces them; shared with `obligations.tsv`'s column 10) is documented as the per-mode step list, and a row a mode drops reads "not owed (mode …)" instead of "entry mode … does not owe it"; `Build type: poc` is a separate axis, so gate-check reads Stages 0–4, 6, 7 "not owed (mode: Build type: poc)" instead of PENDING (`poc-build.md` updated). Under `Interview mode: auto`, `exec.sh` refuses EVERY MDL write of a migration/requirements-driven project until `gate-check.sh <p> build-ready` has passed (its PASS now leaves `.mpr-snapshots/.build-ready-pass`) or the register adopts at 5+ / waives Stage 4 — no refuse-once, and a plan on disk alone does not clear it; interactive runs keep refuse-once. `--adopt` at 4+ under auto on those modes also writes an ASSUMED `consentBy: auto-mode` Stage-3/4 row, so `auto_hand_pending()` lists it and Stage 6 FAILs until a person confirms. "Mode changes are decisions" is stated once, in the runbook's Entry Modes (`poc-build.md` points to it). `init-project.sh` and `sync-project.sh` append the missing register sections (Current stage, Decisions, Open questions, Change log) to a PROJECT.md written by hand before init, loudly, from one template (`bin/lib/register-skeleton.sh`; a fresh scaffold is byte-identical to before), and the generated `CLAUDE.local.md` says init runs before any PROJECT.md or model write. `CONVERSION-RUNBOOK.md` gains "Running unattended", the one kick-off brief a project quotes. Fixture `tests/wave2/test-mode-contract.sh` — owner design input + a research comparison of five field builds that followed the process with the one that did not (Nov 2026)
- fix(status, agents): **`bin/status.sh` WATCHes an Agent Editor project whose extension module does not travel with the model (#778)**: Studio Pro reads `agenteditor.agent` from `modules/AgentEditor.mxmodule` beside the `.mpr`, and a sync of only `.mpr` + `mprcontents/` left it out of git, so the builder stayed green while every colleague's clone showed `unknown type 'agenteditor.agent'`. Two WATCH items, warn-only (exit code and every verdict unchanged), local files and `git ls-files` only, root and `app/` layouts: a `modules/*.mxmodule` git does not track, and a project using Agent Editor (`AgentEditorCommons` in `analysis/app-facts/inventory.json`, or a `create agent` statement in `mdlsource/`) with no `modules/AgentEditor*.mxmodule`. `skills/mendix-agents.md` (on demand) gains the rule plus the note that the GenAI key, `Encryption.EncryptionKey` and `GenAICommons.StoreTraces` belong in the Default configuration, not a start script. Empty agent references / missing model version (mendixlabs/mxcli#1867) and unset runtime constants are not checked: they need a captured agent document (option 2). Fixture `tests/wave2/test-status-extension-modules.sh` — field report from an Agent Editor project, Nov 2026
- fix(permissions): **exec approval `auto` no longer prompts on every exec's mode check, and `install-claude-hooks.sh` no longer runs unprompted (#782)**: `install-claude-permissions.sh` now allow-lists `exec-approval.sh`, `interview-mode.sh` and `permission-profile.sh`, so their reads run without a prompt, while their only writers, `--set` and `--clear`, prompt through six `ask` rules (`Bash(*exec-approval.sh*--set*)`, …) in the shared settings under every profile (an ask rule beats an allow rule, `full`'s bare `Bash` included). `install-claude-hooks.sh`, which writes `~/.claude/settings.json` for every repo on the machine, gets no allow rule. A re-install adds the ask rules and removes the hooks-installer rule an earlier install added (sidecar); entries someone else wrote are untouched, and `sync-project.sh`'s permission check names both until then. Field run on claude 2.1.325: the read ran, `--set auto` and `--clear` were refused, and with the ask rules removed `--set` ran — from the two independent reviews of #781
- process(skills): **trim PR, moves only: always-loaded words 66,271 -> 64,984 (budget 80,000); Stage 5 test 21,906 -> 20,619, gate 22,954 -> 21,744, review 31,681 -> 30,394 (#783)**: `testing-shape.md` §5's stack and scratch-copy mechanics move verbatim to `e2e-harness-base.md` § Bringing the stack up (the rule and a one-line list of its rules stay in §5); the three new Unit false-green rows move to `unit-test.md` § False-green rows (a pointer row stays in the register); `module-review.md`'s re-shoot mechanics move to `iterative-build-loop.md` § Pipeline mode (the rule, the denominator and the failure example stay) and its MXTK-AI001 sentence to `marketplace-catalogue.md` § Reviewing a built module. Every removed line is in its destination, checked line by line — weekly word-budget audit (#783)
Expand Down
22 changes: 22 additions & 0 deletions CONVERSION-RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,28 @@ Then open your agent (Claude Code or equivalent) in `<project-root>` and say wha
| Just an idea / existing plan | Greenfield | P (light), 5–6 |
| A live Mendix app you are changing | Change an existing app | P, 0–6 per change |

## Running unattended — the kick-off brief

**The single source of the text an unattended run (`Interview mode: auto`) is started with.** A
project brief quotes it, verbatim, instead of writing its own; add the project's own goal and
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.
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.
```

*Failure it prevents (two field runs, 2026-11):* the project instructions said "follow the
runbook", but the brief the agent read first defined done as journeys passing under a time
budget and never mentioned stages. The agent built about 78 pages with no plan. Five earlier field
builds, whose briefs said in effect what the lines above say, followed the stages.

## Where you run this — detected, not asked

You do not pick an environment; `bin/doctor.sh` detects it from where the session started, and
Expand Down
Loading
Loading