You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 978ecbf
Browse filesBrowse the repository at this point in the historyBrowse files
Merge #316: process — independent review before every merge; move-don't-delete word budget
Review: MERGE-AFTER-FIX (3 rounds) — last fixes applied verbatim as specified by the reviewer (CHANGELOG trigger wording, testing-section exception wording, re-measured word count, inbox wording).
Copy file name to clipboardExpand all lines: CHANGELOG.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,6 +18,8 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
18
18
## Unreleased
19
19
20
20
- chore(context): **baseline word budget freed — 79,997 → 76,259 words (−3,738) without dropping a rule.** The always-on tier sat 3 words under its 80,000 cap, so three open PRs could not all merge. Long incident narratives in `conversion-runbook.md`, `source-triage.md` and `interview-protocol.md` became one-line failure examples pointing at new on-demand `process/baseline-incident-history.md`, where the original text is kept verbatim per section (R1–R20, AR1, ST1–ST4, IP1–IP3); the runbook's copy of the open-questions status table now defers to `interview-protocol.md` §4; `agent-roles.md`'s six template shapes (setup-only, ~2,300 words) moved verbatim to `agents/README.md`, which the installers never copy (explicit `MXTK_AGENTS` list). Every STOP, rule, denominator and gate cell stays in place; files touched by open PRs were left alone. — MendixMau
21
+
- process(merging): **every PR gets an independent review before it merges — a merge go is not a review.** A reviewer that did not write the PR returns MERGE / MERGE-AFTER-FIX / HOLD on value, regression risk after sync, correctness and context cost; builder self-reports and green CI no longer count. Nine PRs merged on 2026-10-13 without one. — MendixMau
22
+
- process(context): **the baseline word budget is made room for by moving text, never by deleting rules.** Rules, STOP rows, denominators and failure examples are protected; stories and examples move behind pointers in a separate, independently reviewed trim PR; a trim PR lands first when a PR would take the baseline within 2,000 words of the cap. — MendixMau
21
23
- learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
22
24
- learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
23
25
- fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo
Copy file name to clipboardExpand all lines: CLAUDE.md
+73-2Lines changed: 73 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -160,6 +160,72 @@ checkpoint script, and an expert user's reaction was "I can't even compact?":
160
160
7.**A guard must never block the action that resolves it.** Blocking the remedy is
161
161
perverse: warn once, then let it through.
162
162
163
+
## Merging a PR — independent review before every merge
164
+
165
+
**A merge go from the maintainer is not a review.** Before any PR merges, an agent that did
166
+
**not** write it reviews the diff and returns a verdict. The builder's own report and green CI
167
+
never count: the builder grades its own work, and CI proves only the tests the builder wrote.
168
+
169
+
1.**Who reviews, and with what.** A fresh agent given the PR diff, the linked issues and the PR
170
+
body's description of *what* changed — never the builder's verdict, risk assessment or "all
171
+
checks pass" claims. One reviewer per PR, plus one composition check when several PRs in a
172
+
batch touch the same files. The reviewer may run the fixtures the PR adds or that target its
173
+
changed files, in a detached worktree — that is part of the review the maintainer asked for, not
174
+
a free-standing test run (see "Testing this toolkit").
175
+
2.**What it answers, each with file:line.***Value*: does it fix the issue as reported, and is
176
+
anything overbuilt? *Regression risk*: what changes for an existing project after
177
+
`sync-project.sh` (new FAIL / BLIND / refusals, exit codes, output another tool parses, gate
178
+
verdicts that flip), across both layouts and macOS / Git Bash? *Correctness*: real bugs, tests
179
+
that do not test what they claim, hand-written golden input where a capture was required.
180
+
*Context cost*: words added to always-loaded skill files — re-measured by the reviewer, not taken
181
+
from the PR body.
182
+
3.**Verdict.**`MERGE`, `MERGE-AFTER-FIX` (exact fixes listed; the fixes are pushed and
183
+
re-reviewed before merge) or `HOLD` (goes back to the maintainer with the reason). Only `MERGE`
184
+
merges.
185
+
4.**Record the verdict durably.** The squash commit body carries a line
186
+
`Review: MERGE — <one-line top finding or "no findings">`, and the merge announcement repeats it
187
+
next to CI. A merge with no `Review:` line was not reviewed.
188
+
5.**No exceptions for size.** A one-line fix, a docs-only PR and an outside contributor's PR all
189
+
get the same review. "Small", "only skill text" and "CI is green" are how the exceptions start.
190
+
The one exception is guard rule 7's: a fix whose only purpose is to unblock master (a broken CI
191
+
check, a leak guard that blocks every commit) may merge first, with its review within 24 hours
192
+
and a `Review: PENDING (unblock)` line; the follow-up verdict is recorded as a comment on the
193
+
merged PR (and a follow-up fix PR if it finds anything), since a squash commit cannot be edited.
194
+
195
+
**Why (real incident, 2026-10-13).** Nine PRs merged in one day on the builders' own reports and
196
+
green CI, each carrying its builder's "all checks pass". When the maintainer asked whether value
197
+
and regression risk had been checked, the honest answer was no: nobody who had not written the
198
+
code had read it. The after-the-fact reviews found, among others, a journey preflight that made
199
+
every synced project's journey rung FAULT, and an exec lock that let three writers in at once. The same day showed the cost of unread diffs in another form — the always-loaded
200
+
skill text hit its 80,000-word cap because each PR added words that nobody outside the PR weighed.
201
+
202
+
## Always-loaded skill text — the word budget
203
+
204
+
`bin/render-routing.sh --check` caps the always-loaded (baseline) skill set at
205
+
`MXTK_BASELINE_BUDGET_WORDS` — a ratchet, explained in that script's header: lowered as text moves
206
+
out, never raised to admit growth. Room is made by **moving** text, never by deleting the text
207
+
that does the work.
208
+
209
+
1.**Protected — never removed to make room:** rules, STOP rows, denominators / completion
210
+
criteria, and the one-line failure example each rule is paired with. Removing one needs its own
211
+
PR that argues the rule itself is obsolete, with an independent review.
212
+
2.**Movable:** incident narratives, worked examples, tables of past numbers, and a rule stated a
213
+
second time in another baseline file. Each moves to an on-demand file and leaves a one-line
214
+
pointer (path) at the same spot. A move keeps the text; nothing is lost.
215
+
3.**Every PR that adds baseline words** states the before/after count from
216
+
`render-routing.sh --check` in its body, and why each addition is needed at the trigger moment.
217
+
The independent reviewer checks that (see "Merging a PR").
218
+
4.**At the cap, a feature PR never squeezes other text to fit.** Room comes from a separate trim
219
+
PR that only moves movable text; its reviewer compares removed against moved line by line, and
220
+
any protected line that disappeared is a HOLD.
221
+
5.**Trim before the cap, not at it:** when a PR would take the baseline (measured after the PR)
222
+
within 2,000 words of the budget, a trim PR lands first. A trim PR does not lower the ratchet by
223
+
itself; lowering it is a separate one-line change once the trimmed total has held for a release.
224
+
225
+
**Why (2026-10-13).** One feature PR pushed the baseline to 80,466 words against the 80,000 budget
226
+
while six other open PRs each added words; to fit, it merged two sentences in a testing skill and
227
+
landed at 79,997. That one was harmless, but nothing stopped the next one from cutting a STOP row.
228
+
163
229
## Changelog and contributions
164
230
165
231
**Every user-visible change appends its `CHANGELOG.md` line in the same commit.** That is the
@@ -172,7 +238,7 @@ and tag every few days — the release cycle is defined at the top of `CHANGELOG
172
238
173
239
Contributions arrive through three lanes (`CONTRIBUTING.md`): the `contrib/inbox/` drop
174
240
(no quality bar — triage promotes into `skills/`/`bug-logs/`/`bin/` and deletes the inbox file
175
-
in the same commit; inbox files are unreviewed and nothing may cite them),
241
+
in the same commit; inbox files are unreviewed — their content is not vetted for promotion — and nothing may cite them; a PR that adds one still gets the merge review below),
176
242
`bin/harvest-learnings.sh <project-root>` (drafts inbox files from a project's bug logs,
177
243
register promotion tables, and locally-patched installed scripts — run it at project wrap-up),
178
244
and direct PRs held to the full field-proof bar. CI (`.github/workflows/checks.yml`) runs
@@ -277,7 +343,12 @@ to. Wide blast radius is a reason to pick the right *scoped* check, not to run e
277
343
`bin/lib/skill-routing.tsv` and its re-render (README.md, ROUTING.md, every agent template, and
278
344
`gate-check.sh`'s stage map at once) that check is `bin/render-routing.sh --check`.
279
345
280
-
**Asking is also required for a single fixture** — name it, say what it will tell us, and wait.
346
+
**One standing exception: the independent reviewer of a PR** (see "Merging a PR") may run the
347
+
fixtures the PR adds or that target its changed files, without asking, in a detached worktree of
348
+
the PR branch. That isolation is what avoids the shared-tree problem above; the reviewer still
349
+
never runs the full suites.
350
+
351
+
**Outside that reviewer exception, asking is also required for a single fixture** — name it, say what it will tell us, and wait.
281
352
282
353
Where a fixture's assertions are greps over a file you changed, prefer verifying by inspection:
283
354
read the fixture, replicate its greps against the changed file, and report that. Same signal, no
0 commit comments