Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
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
- fix(ci, ready): **review of #788: the toolkit's own text no longer trips its READY check, CI no longer goes red mid-stage, and synced projects start advisory.** The `RESUME.md` starter and `close-task.sh` began a line with READY ("**READY is not written in this file.**"), so every fresh project failed CI and Stage 6 could never pass (now "Only bin/ready.sh writes READY"; a fixture runs init → commit → CI). Check (a) now fails only on stages the register records as passed and warns on the stage in progress (a fresh project at Stage P was red from its first push). `MXTK_CI_ENFORCE` in the workflow: `init-project.sh` installs "1", `sync-project.sh` installs "0" so stage and order checks warn until switched on; the hand-written READY check fails either way — independent review of #788
- fix(ready, ci, gate-check): **field run of the CI gate and `ready.sh` on a six-app copy (#788)**: a hand-written `# READY FOR BENCH (fix round 6, …)` heading passed the `ready` check (READY followed by words now counts; heading markup stripped); `ready.sh` ran over 300 s with no output (every external step now names itself, has stdin closed and a watchdog, `MXTK_READY_STEP_TIMEOUT`, default 120 s; a killed step is NOT MEASURED); the `order` check counted 0 of 234 per-app scripts (`apps/<App>/mdlsource/` now counted); and Stage 5 returned an empty verdict on any project with neither a look ledger nor a summary (`rows` unbound under `set -u`, introduced earlier in this PR); on the re-run, claims in a lowercase root `status.md` were not scanned (root status/progress/resume files now matched in any case), and an annotated `- Interview mode: auto (…)` line, which `interview-mode.sh` resolves to steering, waived the independent review (the raw line's first word now decides whether the review is owed) — parent session's field run
- new(ci, ready): **the gate an agent cannot skip, and a READY nobody can hand-write.** `bin/ci-gates.sh` runs in the project's own CI (`.github/workflows/toolkit-gates.yml`, from `templates/ci/`, installed by `init-project.sh` and `sync-project.sh` create-if-absent, never overwritten, beside any existing CI) on every push and PR, over the committed tree at the pinned toolkit commit: the claimed stage's gate FAILs, a READY line `bin/ready.sh` did not write (`bin/lib/ready-claims.sh`, also a Stage 6 FAIL), committed unseen pages under a done-claim, and model work before Stage 4 all fail it (otherwise it prints `look: K of N pages seen` as a visible warning), in seconds, with no Mendix runtime. `ready.sh` now also requires the position (stages P and 0–4 PASS, WAIVED or not owed by the entry mode: a field run wrote READY with Stage P never passed), honours `Waived obligation must-haves`, writes a review packet (`docs/progress/review-packets/<scope>.html`: screenshot beside target with the reviewer's score, paths only), reads the must-have mark on its tracked path `docs/progress/must-haves/<Module>.md`, and names every app of a multi-app project instead of checking nothing (field runs, 2026-11: agents skip in-session gates; a hand-written READY graded a 0-of-78-looked build done) — two unattended field runs
- new(ready, look-ledger, gate-check): **READY is earned through one command, and its evidence is in git.** `bin/ready.sh <project-root> [--module M | --app A]` runs `gate-check.sh` Stage 5 (Stage 6 once the register is there), the look ledger, the must-have list when present and, under `Interview mode: auto`, an independent reviewer's verdict file (`docs/progress/look-reviews/`, every page scored 1–5 after its last build, below 4 blocks); it prints K of N per check, exits non-zero unless all pass, writes the READY line to `docs/progress/ready.log` itself and commits `docs/progress/ready-<date>-<scope>.md` with explicit paths. `look-ledger.sh summary --write` puts the git-ignored ledger into a tracked `docs/progress/look-summary.tsv` (written by `ready.sh` and every `close-task.sh`), and `gate-check.sh` Stage 5 reads it when the ledger is absent, so a copy of the repo reports FAIL instead of MANUAL. `dispatching.md` gains the reviewer dispatch rule; the `ready` routing row reaches `CLAUDE.local.md` and every agent stub (field runs, 2026-11: a build wrote READY by hand with 0 of ~78 pages looked at; another marked itself ready 3 hours early with no review pass) — two unattended field runs
- process(obligations): **`bin/lib/obligations.tsv` gains column 10 `modes`, the same column, tokens and tokeniser as `artifact-manifest.tsv` (`migration,requirements,greenfield,existing-app-change`, read through artifact-check.sh's own `_art_entry_mode`, never a second copy of its mapping)**: a row the register's `Entry mode:` does not list reads `N/A — not owed (entry mode …)`, never PASS; no or unrecognised mode = owed. Every row lists all four modes today, so no verdict changes; the column lets a mode that genuinely skips a pass be excused by data instead of by absence. Fixture `test-obligation-quality-floor.sh` T9 — follow-up to #787
- 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
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -915,6 +915,7 @@ Then filter by Role(s). A helper dispatched with a role stub (ba, architect, mdl
| Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides | `bin/exec-approval.sh` | 5,6 | mdl, gate |
| Before calling any module tested, or before re-running tests after a change — what testing a module means, which re-runs a change owes (UI-only vs logic lane), and the false-green register of confirmed ways a test reports green over a broken feature | `skills/testing-shape.md` | 5,6 | test, gate, review |
| 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 | `project-bin/verify-module.sh` | 5,6 | mdl, gate, test, review |
| Claiming READY or done for a module or the app — the only way to write READY: `bin/ready.sh <project-root> [--module M]` runs the Stage 5/6 gates, the look ledger, the must-have list and (unattended) the independent review, prints K of N for each and commits the evidence; a READY line it did not write is not READY and FAILs Stage 6 and CI | `bin/ready.sh` | 5,6 | every role |
| A CSS/SCSS or style change that appears to have done nothing (a colour or class that won't show), a focus ring or outline that paints on every page landing or load, or an app still grey after a design port every instrument called green — the three ways a correct rule paints nothing (matches nothing / matches chrome / loses the cascade), the two reads that tell them apart, and the class that arrived in the stylesheet and is bound to no widget | `skills/learned-css-that-never-applied.md` | 5,6 | review, gate (mdl: on demand) |
| Before trusting a green check/exec/DESCRIBE result as proof, or when a runtime symptom appears over a fully green model — the register of constructs that pass early rungs and fail later ones | `skills/learned-detection-gaps.md` | 5,6 | gate, review (mdl: on demand) |
| Creating any entity, or calling a module security-ready — entity and grants land in one script, and ready means SHOW SECURITY MATRIX proves it | `skills/security-is-not-a-later-script.md` | 5 | gate, review (mdl: on demand) |
Expand Down
1 change: 1 addition & 0 deletions ROUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
|---|---|---|---|---|
| Before calling any module tested, or before re-running tests after a change — what testing a module means, which re-runs a change owes (UI-only vs logic lane), and the false-green register of confirmed ways a test reports green over a broken feature | `skills/testing-shape.md` | test,gate,review | 5,6 | baseline |
| 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 | `project-bin/verify-module.sh` | mdl,gate,test,review | 5,6 | baseline |
| Claiming READY or done for a module or the app — the only way to write READY: `bin/ready.sh <project-root> [--module M]` runs the Stage 5/6 gates, the look ledger, the must-have list and (unattended) the independent review, prints K of N for each and commits the evidence; a READY line it did not write is not READY and FAILs Stage 6 and CI | `bin/ready.sh` | all | 5,6 | baseline |
| Auditing or regression/e2e-testing an EXISTING app — no intake, no stages, no gates | `skills/existing-app-assurance.md` | test,review | 6 | ondemand |
| Running the ledger rung alone — recompute every stored ledger status against the live model and catch the STALE rows that claim built for something the model no longer has | `project-bin/conformance-check.sh` | gate,review | 5,6 | ondemand |
| Running the wiring rung alone — a module imported but never reached, an element built but wired to nothing, a boundary crossed; mxbuild and e2e are blind to all three | `project-bin/graph-sweep.sh` | review,gate | 5,6 | ondemand |
Expand Down
1 change: 1 addition & 0 deletions agents/architect-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
| `skills/checkpoints/checkpoint-template.md` | Any stage transition — the 2+1 format every CAC uses, and the one-register rule (answers land in PROJECT.md, never in a separate state file). The seven CACs themselves are routed per stage in the situational table |
| `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 |
| `project-bin/check-design-reaches-app.sh` | After the FIRST build that follows any design-system port, and before any page is built on it — reads the BUILT stylesheet and reports how many framework knobs point at a design token, how many tokens arrived, how many component classes arrived, each with its denominator. Measured on a real run: 55 tokens ported correctly into the right file, 0 of 35 knobs bound and 0 of 20 classes present, two build phases shipped in the framework's default blue with mx check, mxcli lint, the MDL suite and two e2e journeys all green |
| `bin/ready.sh` | Claiming READY or done for a module or the app — the only way to write READY: `bin/ready.sh <project-root> [--module M]` runs the Stage 5/6 gates, the look ledger, the must-have list and (unattended) the independent review, prints K of N for each and commits the evidence; a READY line it did not write is not READY and FAILs Stage 6 and CI |
| `skills/tool-output-is-not-ground-truth.md` | Any time an exit code, a tool's output or a subagent's report is about to become a stated finding — verify before you conclude |
| `bin/status.sh` | The first command of every session, and any time someone asks "where are we" or "what next" — one screen: stage, done/overdue, the ONE next action, from the instruments, never from memory |
| `skills/retesting-learned-rules.md` | Before obeying any learned-* STOP or workaround that costs a detour — probe the binary you actually have, then stamp the verdict back into the rule |
Expand Down
1 change: 1 addition & 0 deletions agents/ba-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
| `bin/question-kinds.sh` | Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127 |
| `bin/facts-lock.sh` | Writing BRDs, especially several in parallel — "build" before the fan-out, "check" before any BRD is called done |
| `skills/module-brief.md` | Building any module — before the first script. The mdl-agent's single per-module input |
| `bin/ready.sh` | Claiming READY or done for a module or the app — the only way to write READY: `bin/ready.sh <project-root> [--module M]` runs the Stage 5/6 gates, the look ledger, the must-have list and (unattended) the independent review, prints K of N for each and commits the evidence; a READY line it did not write is not READY and FAILs Stage 6 and CI |
| `skills/tool-output-is-not-ground-truth.md` | Any time an exit code, a tool's output or a subagent's report is about to become a stated finding — verify before you conclude |
| `bin/status.sh` | The first command of every session, and any time someone asks "where are we" or "what next" — one screen: stage, done/overdue, the ONE next action, from the instruments, never from memory |
| `skills/retesting-learned-rules.md` | Before obeying any learned-* STOP or workaround that costs a detour — probe the binary you actually have, then stamp the verdict back into the rule |
Expand Down
1 change: 1 addition & 0 deletions agents/gate-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
| `bin/exec-approval.sh` | Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides |
| `skills/testing-shape.md` | Before calling any module tested, or before re-running tests after a change — what testing a module means, which re-runs a change owes (UI-only vs logic lane), and the false-green register of confirmed ways a test reports green over a broken feature |
| `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 |
| `bin/ready.sh` | Claiming READY or done for a module or the app — the only way to write READY: `bin/ready.sh <project-root> [--module M]` runs the Stage 5/6 gates, the look ledger, the must-have list and (unattended) the independent review, prints K of N for each and commits the evidence; a READY line it did not write is not READY and FAILs Stage 6 and CI |
| `skills/tool-output-is-not-ground-truth.md` | Any time an exit code, a tool's output or a subagent's report is about to become a stated finding — verify before you conclude |
| `skills/learned-css-that-never-applied.md` | A CSS/SCSS or style change that appears to have done nothing (a colour or class that won't show), a focus ring or outline that paints on every page landing or load, or an app still grey after a design port every instrument called green — the three ways a correct rule paints nothing (matches nothing / matches chrome / loses the cascade), the two reads that tell them apart, and the class that arrived in the stylesheet and is bound to no widget |
| `skills/learned-detection-gaps.md` | Before trusting a green check/exec/DESCRIBE result as proof, or when a runtime symptom appears over a fully green model — the register of constructs that pass early rungs and fail later ones |
Expand Down
1 change: 1 addition & 0 deletions agents/mdl-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local.
| `project-bin/page-fidelity.js` | After drafting and again after exec'ing any page script — scores the page MDL (or `mxcli describe` output on stdin) against its wireframe: headings/actions/content/classes, weighted. The scored companion to check-page-shell's binary gate; 32% median measured without it, 90% first-draft with it. Every run is appended to the project's docs/PAGE-FIDELITY.tsv — first non-stub row per page = first-build score of record vs the ≥80% target (forward-reference stubs score with --stub, exempt) |
| `bin/exec-approval.sh` | Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides |
| `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 |
| `bin/ready.sh` | Claiming READY or done for a module or the app — the only way to write READY: `bin/ready.sh <project-root> [--module M]` runs the Stage 5/6 gates, the look ledger, the must-have list and (unattended) the independent review, prints K of N for each and commits the evidence; a READY line it did not write is not READY and FAILs Stage 6 and CI |
| `skills/tool-output-is-not-ground-truth.md` | Any time an exit code, a tool's output or a subagent's report is about to become a stated finding — verify before you conclude |
| `bin/bug-lookup.sh` | A CE error (mx check or mxbuild: CE0066, CE0117…), a cited BUG-n, or behavior that looks like a known mxcli quirk rather than a modeling mistake — `bin/bug-lookup.sh CE0117` / `BUG-102` / "keyword" / the whole pasted error message (ranked top 3) prints the matching ledger entries, so the session reads one entry, not the whole ledger |
| `bin/file-bugs.sh` | You hit, or worked around, a bug in mxcli or the toolkit, or log a FINDINGS.md entry about either — `bin/file-bugs.sh` (the `--add` line is in learned-detection-gaps.md) keeps docs/bugs.jsonl, redacts, shows duplicates, files with `--auto` when PROJECT.md says `Bug filing: auto`, else only a human files (`!`, `--file PBUG-NN`, y/N, denied to agents), or prints new-issue links (`--links`, `--json`) |
Expand Down
Loading
Loading