Skip to content

Commit 978ecbf

Browse files
committed
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).
2 parents 171ee77 + 0ca1dbd commit 978ecbf

2 files changed

Lines changed: 75 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
1818
## Unreleased
1919

2020
- 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
2123
- 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
2224
- 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
2325
- 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

‎CLAUDE.md‎

Lines changed: 73 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,72 @@ checkpoint script, and an expert user's reaction was "I can't even compact?":
160160
7. **A guard must never block the action that resolves it.** Blocking the remedy is
161161
perverse: warn once, then let it through.
162162

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+
163229
## Changelog and contributions
164230

165231
**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
172238

173239
Contributions arrive through three lanes (`CONTRIBUTING.md`): the `contrib/inbox/` drop
174240
(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),
176242
`bin/harvest-learnings.sh <project-root>` (drafts inbox files from a project's bug logs,
177243
register promotion tables, and locally-patched installed scripts — run it at project wrap-up),
178244
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
277343
`bin/lib/skill-routing.tsv` and its re-render (README.md, ROUTING.md, every agent template, and
278344
`gate-check.sh`'s stage map at once) that check is `bin/render-routing.sh --check`.
279345

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.
281352

282353
Where a fixture's assertions are greps over a file you changed, prefer verifying by inspection:
283354
read the fixture, replicate its greps against the changed file, and report that. Same signal, no

0 commit comments

Comments
 (0)