From 235df514c7c56f13bdcc9a3b8bb071660f5da252 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 13:30:21 +0000 Subject: [PATCH 1/2] fix(routing): learned-mcp-patterns.md loads before the first MCP write, not on every build It was in the Stage 5 baseline pack and mdl-agent's always-read rows, so every build session and MDL helper agent carried ~4,900 tokens of MCP rules, including cloud sessions where MCP does not exist. The write-mode choice is Step 0 of learned-mdl-preflight.md, which stays always-on. Stage 5 pack 74,055 -> 71,443 words; baseline 79,752 -> 77,140. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw --- CHANGELOG.md | 1 + CLAUDE.md | 2 +- README.md | 2 +- ROUTING.md | 2 +- agents/mdl-agent.md | 2 +- bin/lib/skill-routing.tsv | 2 +- skills/conversion-runbook.md | 1 - 7 files changed, 6 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 526bbf9..ac65655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- fix(routing): **`learned-mcp-patterns.md` is no longer always-on in the build stage; it loads before the first MCP write in a session.** It sat in the Stage 5 baseline pack and in `mdl-agent`'s always-read rows, so every build session and every MDL helper agent carried ~4,900 tokens of MCP save/handoff rules and JSON payloads, including sessions that never open Studio Pro and cloud containers where MCP does not exist. Choosing the write mode is already Step 0 of `learned-mdl-preflight.md`, which stays always-on, so nothing is lost at the moment of choice; the MCP skill's trigger now names the moment it is needed (`mxcli --mcp` exec or a `pg_*`/`ped_*` call). Stage 5 pack: 74,055 → 71,443 words, 23 → 22 files; baseline 79,752 → 77,140 words. Found by the context report (`bin/context-audit.sh`, `bin/render-routing.sh --check`). — MendixMau - fix(doctor, test-stack-up): **in a cloud container, a missing Docker daemon is now reported as normal, with the Docker-free route, instead of a warning that says to start it.** The Claude Code on the web container has the docker CLI but no daemon, and the agent cannot start one. Doctor used to WARN "docker daemon is not responding … sudo systemctl start docker", so sessions tried, failed, and reported "cannot start the docker daemon" as a blocker, until the user said to use `mxcli run --local`. Now the cloud lane prints: no Docker here, normal, do not try to start it; build check = exec.sh's mxbuild gate; run the app = `./mxcli run --local`. On a desktop (Docker or Podman, stopped or absent) the warning and start hint stay, plus one line saying a container is optional: the mxbuild gate needs none, and Studio Pro's Run Locally or `mxcli run --local` runs the app. The no-runtime text no longer says the build check needs Docker. `test-stack-up.sh` with the app down and no reachable Docker/Podman now stops with the Docker-free route instead of failing inside `mxcli docker run`. — MendixMau - fix(gate-check): **the stage-decision readers now read only the Decisions table, and Stage 7 accepts a dated CONFIRMED.** `has_confirmed_decision` (Stages 3 and 4) and the Stage 7 cutover check scanned every pipe row in the register, so an Open-questions row numbered 4 or 7 with Status CONFIRMED passed that stage with no decision behind it. Both now count only rows under a header whose first cell is `Stage`; a register with no such header keeps the old every-row scan. Stage 7 also matched the status string-exactly, so `CONFIRMED 2026-08-10` failed there while passing every other stage (TD-07); it now uses the same word-anchored match. Positive control: the pre-fix script passes Stages 4 and 7 on an Open-questions-only register and fails Stage 7 on the dated status. Fixture T13–T15 in `test-bug03-gates.sh` — MendixMau - learn(bug-logs): **`BUG-DRAFT-grant-association-generalization-member`** — a member association owned by another module's entity cannot be named in a `grant` statement, so `revoke` + `re-grant` silently drops that member access and `mx check` reports CE0066; patch-only workaround provided. Found fixing a guest-groups association in a Mendix app (mxcli v0.23.0, Mendix 11.12.2). — MendixMau diff --git a/CLAUDE.md b/CLAUDE.md index c9ed08b..8a6292e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,7 +32,7 @@ All gate decisions land in the consuming project's `PROJECT.md`, marked `CONFIRM ## Key skills and when to load them -Load skill files **on demand when the task calls for it** — not all upfront. Full routing table: `README.md` → "When to use which skill". The always-on set (`README.md` → "Baseline routing"): `query-the-model.md`, `learned-mdl-preflight.md`, `learned-microflow-patterns.md`, `learned-mcp-patterns.md`, and `bin/bug-lookup.sh` (a CE code, BUG-n or keyword → the matching ledger entries; `bug-logs/mxcli-bugs.md` itself is read on demand — it outgrew the always-on budget). +Load skill files **on demand when the task calls for it** — not all upfront. Full routing table: `README.md` → "When to use which skill". The always-on set (`README.md` → "Baseline routing"): `query-the-model.md`, `learned-mdl-preflight.md`, `learned-microflow-patterns.md`, and `bin/bug-lookup.sh` (a CE code, BUG-n or keyword → the matching ledger entries; `bug-logs/mxcli-bugs.md` itself is read on demand — it outgrew the always-on budget). `learned-mcp-patterns.md` is on demand too: read it before the first MCP write in a session, not on every build. | Task | Read this file | |------|---------------| diff --git a/README.md b/README.md index a3cdd5b..4399fa6 100644 --- a/README.md +++ b/README.md @@ -608,6 +608,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini | Task | Skill to load | |---|---| +| Before the first MCP write in a session (Studio Pro open: `mxcli --mcp` exec, or pg_*/ped_* calls) — save after every write, the handoff sequence, confirmed JSON payloads. Choosing the write mode itself is Step 0 of learned-mdl-preflight.md | `skills/learned-mcp-patterns.md` | | Reading what loop bodies do (LOOP_TQ, deferred commit, nested loop, REST in loop, transaction control per item, scheduled-event reachability) from described MDL; the catalog holds top-level activities only and cannot see inside a loop | `skills/microflow-loop-antipatterns.md` | | Writing MDL microflow scripts — worked recipes | `skills/mdl-cookbook-microflows.md` | | Writing a single MDL script that takes a project from nothing to a working vertical slice — execution order, why it is deliberately non-idempotent, the instrument hierarchy, and the silent failures that pass every check | `skills/build/mdl/oneshot-mdl-method.md` | @@ -787,7 +788,6 @@ Read a row when its Stage(s) cell says *every stage* or names the stage the regi | 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 | `project-bin/check-design-reaches-app.sh` | 3,5 | | Before exec'ing ANY page script — compares the drafted MDL's shell against the wireframe's: page column, layout/nav shell, one H1. Measured 0/10 pages on a real first build, repaired wholesale 47 scripts later | `project-bin/check-page-shell.sh` | 5 | | 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) | `project-bin/page-fidelity.js` | 5 | -| Choosing CLI vs MCP+MDL vs hand-rolled MCP, or any MCP write session — three co-equal write modes, not CLI-only | `skills/learned-mcp-patterns.md` | 5 | | Reviewing any module before calling it done — the ONE pass: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated | `skills/module-review.md` | 5,6 | | Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides | `bin/exec-approval.sh` | 5,6 | | Before calling any module tested — what testing a module means, and the false-green register of confirmed ways a test reports green over a broken feature | `skills/testing-shape.md` | 5,6 | diff --git a/ROUTING.md b/ROUTING.md index 8ff018e..bac15e8 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -151,7 +151,7 @@ picks the row up. That is the whole procedure — there is no second list to rem | Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations | `skills/learned-mdl-preflight.md` | mdl | 5 | baseline | | Writing or fixing any microflow — MDL gotchas plus annotation discipline | `skills/learned-microflow-patterns.md` | mdl | 5 | baseline | | Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line | `skills/microflow-preflight.md` | mdl | 5 | baseline | -| Choosing CLI vs MCP+MDL vs hand-rolled MCP, or any MCP write session — three co-equal write modes, not CLI-only | `skills/learned-mcp-patterns.md` | mdl | 5 | baseline | +| Before the first MCP write in a session (Studio Pro open: `mxcli --mcp` exec, or pg_*/ped_* calls) — save after every write, the handoff sequence, confirmed JSON payloads. Choosing the write mode itself is Step 0 of learned-mdl-preflight.md | `skills/learned-mcp-patterns.md` | mdl | 5 | ondemand | | Reading what loop bodies do (LOOP_TQ, deferred commit, nested loop, REST in loop, transaction control per item, scheduled-event reachability) from described MDL; the catalog holds top-level activities only and cannot see inside a loop | `skills/microflow-loop-antipatterns.md` | architect,review,mdl | 0,5,6 | ondemand | | Writing MDL microflow scripts — worked recipes | `skills/mdl-cookbook-microflows.md` | mdl | 5 | ondemand | | Writing a single MDL script that takes a project from nothing to a working vertical slice — execution order, why it is deliberately non-idempotent, the instrument hierarchy, and the silent failures that pass every check | `skills/build/mdl/oneshot-mdl-method.md` | mdl | 5 | ondemand | diff --git a/agents/mdl-agent.md b/agents/mdl-agent.md index abcc840..6e1a210 100644 --- a/agents/mdl-agent.md +++ b/agents/mdl-agent.md @@ -49,7 +49,6 @@ a rule below names an asset (e.g. "the wireframe", "the brief"), it means the pa | `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 | | `project-bin/check-page-shell.sh` | Before exec'ing ANY page script — compares the drafted MDL's shell against the wireframe's: page column, layout/nav shell, one H1. Measured 0/10 pages on a real first build, repaired wholesale 47 scripts later | | `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) | -| `skills/learned-mcp-patterns.md` | Choosing CLI vs MCP+MDL vs hand-rolled MCP, or any MCP write session — three co-equal write modes, not CLI-only | | `skills/module-review.md` | Reviewing any module before calling it done — the ONE pass: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated | | `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 | @@ -66,6 +65,7 @@ a rule below names an asset (e.g. "the wireframe", "the brief"), it means the pa | `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `skills/learned-stylegallery.md` | Building or using the in-app design gallery | | `project-bin/check-design-portability.sh` | Before porting ds.css into SCSS, and at the Stage-3 gate — greps the stylesheet for rules that cannot match the HTML Mendix emits (rem against the real root, table/th/td selectors, positional row selectors). mx check, mxcli check and mxcli lint are all blind to CSS | +| `skills/learned-mcp-patterns.md` | Before the first MCP write in a session (Studio Pro open: `mxcli --mcp` exec, or pg_*/ped_* calls) — save after every write, the handoff sequence, confirmed JSON payloads. Choosing the write mode itself is Step 0 of learned-mdl-preflight.md | | `bug-logs/mxcli-bugs.md` | Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words | | `skills/cloud-dev-environment.md` | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | | `skills/microflow-loop-antipatterns.md` | Reading what loop bodies do (LOOP_TQ, deferred commit, nested loop, REST in loop, transaction control per item, scheduled-event reachability) from described MDL; the catalog holds top-level activities only and cannot see inside a loop | diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv index 98ed218..d1f4289 100644 --- a/bin/lib/skill-routing.tsv +++ b/bin/lib/skill-routing.tsv @@ -105,7 +105,7 @@ check-page-shell project-bin/check-page-shell.sh Before exec'ing ANY page script page-fidelity 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) mdl,gate,review 5 baseline design assemble-prototype project-bin/assemble-prototype.js After every wireframe edit: assembles design/wireframes/*.html into design/prototype.html, one hash-routed page a stakeholder can click through instead of twenty separate files. Generated, never edited (design-artifacts.md Step 3) architect,review 3 ondemand design check-prototype-links project-bin/check-prototype-links.js Before wireframes pass to the build loop, and with --brd before a BRD is signed off: dead #/route links, orphan screens, controls with no data-bind and no data-cut, BRD routes no screen has, screens no use case walks (design-artifacts.md Step 3c, brd-validation.md check 8) architect,review 3 ondemand design -learned-mcp-patterns skills/learned-mcp-patterns.md Choosing CLI vs MCP+MDL vs hand-rolled MCP, or any MCP write session — three co-equal write modes, not CLI-only mdl 5 baseline build/mdl +learned-mcp-patterns skills/learned-mcp-patterns.md Before the first MCP write in a session (Studio Pro open: `mxcli --mcp` exec, or pg_*/ped_* calls) — save after every write, the handoff sequence, confirmed JSON payloads. Choosing the write mode itself is Step 0 of learned-mdl-preflight.md mdl 5 ondemand build/mdl module-review skills/module-review.md Reviewing any module before calling it done — the ONE pass: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated mdl,review,test 5,6 baseline build exec-approval bin/exec-approval.sh Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides mdl,gate 5,6 baseline build testing-shape skills/testing-shape.md Before calling any module tested — what testing a module means, and the false-green register of confirmed ways a test reports green over a broken feature test,gate,review 5,6 baseline verify diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index 18f58c3..3ea98b4 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -48,7 +48,6 @@ Read a row when its Stage(s) cell says *every stage* or names the stage the regi | 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 | `project-bin/check-design-reaches-app.sh` | 3,5 | | Before exec'ing ANY page script — compares the drafted MDL's shell against the wireframe's: page column, layout/nav shell, one H1. Measured 0/10 pages on a real first build, repaired wholesale 47 scripts later | `project-bin/check-page-shell.sh` | 5 | | 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) | `project-bin/page-fidelity.js` | 5 | -| Choosing CLI vs MCP+MDL vs hand-rolled MCP, or any MCP write session — three co-equal write modes, not CLI-only | `skills/learned-mcp-patterns.md` | 5 | | Reviewing any module before calling it done — the ONE pass: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated | `skills/module-review.md` | 5,6 | | Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides | `bin/exec-approval.sh` | 5,6 | | Before calling any module tested — what testing a module means, and the false-green register of confirmed ways a test reports green over a broken feature | `skills/testing-shape.md` | 5,6 | From 4d9d2b060cfb033c7b3ec33b68fd51a41a372b8e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 13:52:09 +0000 Subject: [PATCH 2/2] fix(routing): routing tables are trigger lists; setup no longer says read the whole runbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rule line above every baseline table told a session to read every row of its stage (23 files, ~121k tokens at Stage 5), agent templates were headed 'must load', and init-project/sync-project told sessions to read the runbook first and in full, although the runbook says not whole. Now a row's file is opened when its trigger happens; the runbook is read as §1b plus the stage's own section. No tier changes, so every trigger stays visible. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw --- CHANGELOG.md | 1 + README.md | 4 ++-- ROUTING.md | 2 +- agents/architect-agent.md | 6 ++++-- agents/ba-agent.md | 6 ++++-- agents/gate-agent.md | 6 ++++-- agents/mdl-agent.md | 6 ++++-- agents/review-agent.md | 6 ++++-- agents/test-agent.md | 6 ++++-- bin/init-project.sh | 5 +++-- bin/lib/skill-routing.sh | 4 +++- bin/lib/skill-routing.tsv | 2 +- bin/sync-project.sh | 2 +- skills/conversion-runbook.md | 4 ++-- 14 files changed, 38 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ac65655..90362db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- fix(routing, init-project, sync-project, agents): **routing tables are trigger lists now, not reading lists, and no setup file tells a session to read the whole runbook any more.** The line above every baseline table said "read a row when its Stage(s) cell names your stage", so a build session was told to read all 23 Stage 5 files, about 121k tokens, before touching the project, and every agent template was headed "Skills this agent must load". The runbook already said "How to read this file: not whole", but the `CLAUDE.local.md` that `init-project.sh` writes said "Read conversion-runbook.md FIRST — every session", and the ritual `sync-project.sh` appends said "re-read it in full" (~24k tokens, carried on every later call). Now: open a row's file when its trigger happens in this session and stage, never the table ahead, and a page task never opens the microflow rows; agent templates say the same above their table; the runbook row, `init-project.sh` and the ritual say "§1b plus your own stage's section, not the whole file". No row changed tier, so every trigger stays visible to the main session and to each agent. Found by the context report behind `bin/context-audit.sh`. Existing projects pick the new wording up through `bin/sync-project.sh` where the block is marked; a hand-written `CLAUDE.local.md` needs the two lines edited by hand. — MendixMau - fix(routing): **`learned-mcp-patterns.md` is no longer always-on in the build stage; it loads before the first MCP write in a session.** It sat in the Stage 5 baseline pack and in `mdl-agent`'s always-read rows, so every build session and every MDL helper agent carried ~4,900 tokens of MCP save/handoff rules and JSON payloads, including sessions that never open Studio Pro and cloud containers where MCP does not exist. Choosing the write mode is already Step 0 of `learned-mdl-preflight.md`, which stays always-on, so nothing is lost at the moment of choice; the MCP skill's trigger now names the moment it is needed (`mxcli --mcp` exec or a `pg_*`/`ped_*` call). Stage 5 pack: 74,055 → 71,443 words, 23 → 22 files; baseline 79,752 → 77,140 words. Found by the context report (`bin/context-audit.sh`, `bin/render-routing.sh --check`). — MendixMau - fix(doctor, test-stack-up): **in a cloud container, a missing Docker daemon is now reported as normal, with the Docker-free route, instead of a warning that says to start it.** The Claude Code on the web container has the docker CLI but no daemon, and the agent cannot start one. Doctor used to WARN "docker daemon is not responding … sudo systemctl start docker", so sessions tried, failed, and reported "cannot start the docker daemon" as a blocker, until the user said to use `mxcli run --local`. Now the cloud lane prints: no Docker here, normal, do not try to start it; build check = exec.sh's mxbuild gate; run the app = `./mxcli run --local`. On a desktop (Docker or Podman, stopped or absent) the warning and start hint stay, plus one line saying a container is optional: the mxbuild gate needs none, and Studio Pro's Run Locally or `mxcli run --local` runs the app. The no-runtime text no longer says the build check needs Docker. `test-stack-up.sh` with the app down and no reachable Docker/Podman now stops with the Docker-free route instead of failing inside `mxcli docker run`. — MendixMau - fix(gate-check): **the stage-decision readers now read only the Decisions table, and Stage 7 accepts a dated CONFIRMED.** `has_confirmed_decision` (Stages 3 and 4) and the Stage 7 cutover check scanned every pipe row in the register, so an Open-questions row numbered 4 or 7 with Status CONFIRMED passed that stage with no decision behind it. Both now count only rows under a header whose first cell is `Stage`; a register with no such header keeps the old every-row scan. Stage 7 also matched the status string-exactly, so `CONFIRMED 2026-08-10` failed there while passing every other stage (TD-07); it now uses the same word-anchored match. Positive control: the pre-fix script passes Stages 4 and 7 on an Open-questions-only register and fails Stage 7 on the dated status. Fixture T13–T15 in `test-bug03-gates.sh` — MendixMau diff --git a/README.md b/README.md index 4399fa6..3694cca 100644 --- a/README.md +++ b/README.md @@ -757,7 +757,7 @@ The "When to use which skill" table above is *situational* — load a skill when -Read a row when its Stage(s) cell says *every stage* or names the stage the register (PROJECT.md) says you are in. Rows for other stages are not this session's reading. +Each row is a trigger, not a reading list: open a row's file when the first column happens in this session, and only rows whose Stage(s) cell says *every stage* or names the stage the register (PROJECT.md) says you are in. Do not read the table ahead — a build session that only writes pages never opens the microflow rows. | Always relevant for | Reference this | Stage(s) | |---|---|---| @@ -765,7 +765,7 @@ Read a row when its Stage(s) cell says *every stage* or names the stage the regi | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | `skills/degrade-to-judgement.md` | every stage | | 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/tool-output-is-not-ground-truth.md` | every stage | | 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 | `skills/retesting-learned-rules.md` | every stage | -| Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | `skills/conversion-runbook.md` | P,0,1,2,3,4,5,6,7 | +| Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | `skills/conversion-runbook.md` | P,0,1,2,3,4,5,6,7 | | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | `skills/query-the-model.md` | P,0,1,2,3,4,5,6,7 | | Putting a question TO the user — any gate, any stage: ask in chat not in a file, two named options plus your recommendation, one batch per gate then end the turn | `skills/interview-protocol.md` | P,0,1,2,3,4,5,6,7 | | 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/checkpoints/checkpoint-template.md` | 0,1,2,3,4,6,7 | diff --git a/ROUTING.md b/ROUTING.md index bac15e8..c9e7af5 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -32,7 +32,7 @@ picks the row up. That is the whole procedure — there is no second list to rem | Always relevant for | Load this | Agent(s) | Stage(s) | Tier | |---|---|---|---|---| -| Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | `skills/conversion-runbook.md` | all | P,0,1,2,3,4,5,6,7 | baseline | +| Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | `skills/conversion-runbook.md` | all | P,0,1,2,3,4,5,6,7 | baseline | | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | `skills/query-the-model.md` | all | P,0,1,2,3,4,5,6,7 | baseline | | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | `skills/skills-over-scripts.md` | all | - | baseline | | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | `skills/degrade-to-judgement.md` | all | - | baseline | diff --git a/agents/architect-agent.md b/agents/architect-agent.md index b91b31b..b516779 100644 --- a/agents/architect-agent.md +++ b/agents/architect-agent.md @@ -22,14 +22,16 @@ You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you ne - **Domain glossary (5–10 terms):** {{GLOSSARY}} - **Where the truth lives:** BRDs at {{BRD_PATH}}, decisions in {{PROJECT_MD_PATH}}, architecture artifacts in {{ARCHITECTURE_DIR}} -## Skills this agent must load +## Skills — open each one when its trigger fires +Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows. + | Load this | When | |---|---| -| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | +| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | | `skills/query-the-model.md` | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | | `skills/skills-over-scripts.md` | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | | `skills/degrade-to-judgement.md` | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | diff --git a/agents/ba-agent.md b/agents/ba-agent.md index 4aa7046..fe26e19 100644 --- a/agents/ba-agent.md +++ b/agents/ba-agent.md @@ -28,13 +28,15 @@ You run discovery and the interview gates for {{PROJECT}}. You never touch the ` ## Ground rules -## Skills this agent must load +## Skills — open each one when its trigger fires +Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows. + | Load this | When | |---|---| -| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | +| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | | `skills/query-the-model.md` | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | | `skills/skills-over-scripts.md` | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | | `skills/degrade-to-judgement.md` | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | diff --git a/agents/gate-agent.md b/agents/gate-agent.md index da87938..ea9c3fb 100644 --- a/agents/gate-agent.md +++ b/agents/gate-agent.md @@ -19,14 +19,16 @@ back to v1 and deleting `mprcontents/`, and `test` writes too. Two consecutive r comparable, and the project's write-approval rule applies to them. Confirm against the project's own bug log before running anything you have not run here before. -## Skills this agent must load +## Skills — open each one when its trigger fires +Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows. + | Load this | When | |---|---| -| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | +| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | | `skills/query-the-model.md` | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | | `skills/skills-over-scripts.md` | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | | `skills/degrade-to-judgement.md` | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | diff --git a/agents/mdl-agent.md b/agents/mdl-agent.md index 6e1a210..999bbce 100644 --- a/agents/mdl-agent.md +++ b/agents/mdl-agent.md @@ -25,14 +25,16 @@ architecture, build plan, BRDs) live in the **`## Wiring` block of the project-r the single source of truth. Read that block at the start of every task and resolve paths from it. When a rule below names an asset (e.g. "the wireframe", "the brief"), it means the path from that block. -## Skills this agent must load +## Skills — open each one when its trigger fires +Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows. + | Load this | When | |---|---| -| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | +| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | | `skills/query-the-model.md` | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | | `skills/skills-over-scripts.md` | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | | `skills/degrade-to-judgement.md` | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | diff --git a/agents/review-agent.md b/agents/review-agent.md index 8caaaed..478c9a8 100644 --- a/agents/review-agent.md +++ b/agents/review-agent.md @@ -26,13 +26,15 @@ protects: you have no Write or Edit tool, and you never run `mxcli exec`. ## Why you exist -## Skills this agent must load +## Skills — open each one when its trigger fires +Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows. + | Load this | When | |---|---| -| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | +| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | | `skills/query-the-model.md` | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | | `skills/skills-over-scripts.md` | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | | `skills/degrade-to-judgement.md` | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | diff --git a/agents/test-agent.md b/agents/test-agent.md index 9120497..caf8c9f 100644 --- a/agents/test-agent.md +++ b/agents/test-agent.md @@ -18,14 +18,16 @@ changes and are out of scope regardless of what a test failure seems to call for proves the model is wrong, that is a finding you report, not a fix you make. `mxcli -c "SHOW ..."` and `"DESCRIBE ..."` reads are always fine, and are how you ground every name you use. -## Skills this agent must load +## Skills — open each one when its trigger fires +Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows. + | Load this | When | |---|---| -| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | +| `skills/conversion-runbook.md` | Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | | `skills/query-the-model.md` | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | | `skills/skills-over-scripts.md` | Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot | | `skills/degrade-to-judgement.md` | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | diff --git a/bin/init-project.sh b/bin/init-project.sh index 307fe99..463a1e0 100755 --- a/bin/init-project.sh +++ b/bin/init-project.sh @@ -325,8 +325,9 @@ someone else pushed to a shared repo. CI that genuinely wants the old behaviour This project uses the shared toolkit at \`$TOOLKIT_ROOT\`. For ANY pipeline work (analysis, BRDs, architecture, design, build plan, build, test, cutover): -1. **Read \`$TOOLKIT_ROOT/skills/conversion-runbook.md\` FIRST — every session.** It is the - executable spec. The toolkit README and toolkit-guide.html are orientation only; stage +1. **Read \`$TOOLKIT_ROOT/skills/conversion-runbook.md\` §1b plus your own stage's section FIRST — + every session; not the whole file** (\`bin/gate-check.sh \` prints the line + spans). It is the executable spec. The toolkit README and toolkit-guide.html are orientation only; stage summaries anywhere are routing, not deliverable lists. 2. **Before producing any stage artifact, open that stage's owning skill** and follow its full output list (e.g. Stage 3 design work = \`design-artifacts.md\`, incl. one wireframe diff --git a/bin/lib/skill-routing.sh b/bin/lib/skill-routing.sh index 4c9b095..c776ea8 100644 --- a/bin/lib/skill-routing.sh +++ b/bin/lib/skill-routing.sh @@ -192,7 +192,7 @@ routing_render() { done ;; readme-baseline|baseline) - echo "Read a row when its Stage(s) cell says *every stage* or names the stage the register (PROJECT.md) says you are in. Rows for other stages are not this session's reading." + echo "Each row is a trigger, not a reading list: open a row's file when the first column happens in this session, and only rows whose Stage(s) cell says *every stage* or names the stage the register (PROJECT.md) says you are in. Do not read the table ahead — a build session that only writes pages never opens the microflow rows." echo "" if [ "$view" = "baseline" ]; then echo "| Always relevant for | Reference this (under \`${prefix%/}/\`) | Stage(s) |" @@ -236,6 +236,8 @@ routing_render() { ;; agent:*) local who="${view#agent:}" + echo "Open a file when its When cell happens in your task, not all of them at the start. A page task never opens the microflow rows; a microflow task never opens the page rows." + echo "" echo "| Load this | When |" echo "|---|---|" local t diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv index d1f4289..fad34c6 100644 --- a/bin/lib/skill-routing.tsv +++ b/bin/lib/skill-routing.tsv @@ -62,7 +62,7 @@ # protocol-staleness ack on every routing edit. # # name path when agents stages tier group -conversion-runbook skills/conversion-runbook.md Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only all P,0,1,2,3,4,5,6,7 baseline spine +conversion-runbook skills/conversion-runbook.md Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only all P,0,1,2,3,4,5,6,7 baseline spine query-the-model skills/query-the-model.md Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order all P,0,1,2,3,4,5,6,7 baseline spine skills-over-scripts skills/skills-over-scripts.md Before writing any .js or .sh for a check, gate or report — and before adding a rule to an existing one: judgement goes in a skill, code only fetches facts a reader cannot all - baseline spine degrade-to-judgement skills/degrade-to-judgement.md Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict all - baseline spine diff --git a/bin/sync-project.sh b/bin/sync-project.sh index 879c9ad..9133e15 100755 --- a/bin/sync-project.sh +++ b/bin/sync-project.sh @@ -631,7 +631,7 @@ if [ -f "$CL" ] && ! grep -q "Session-start ritual" "$CL"; then 3. \`$TOOLKIT_ROOT/bin/status.sh --brief\` — where, done/overdue, next action; post it as the session's first message (same step as init-project writes for new projects). 4. If the commit differs from \`PROJECT.md\`'s \`Toolkit commit:\` line: re-read - \`$TOOLKIT_ROOT/skills/conversion-runbook.md\` in full, then update that line. + \`$TOOLKIT_ROOT/skills/conversion-runbook.md\` §1b plus your stage's section, then update that line. 5. State in chat which commit you're working from. gate-check blocks all gates on a mismatch. EOF echo "Updated: CLAUDE.local.md — appended the session-start ritual." diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index 3ea98b4..9eb993e 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -17,7 +17,7 @@ table; a skill missing here is a skill no agent will find. -Read a row when its Stage(s) cell says *every stage* or names the stage the register (PROJECT.md) says you are in. Rows for other stages are not this session's reading. +Each row is a trigger, not a reading list: open a row's file when the first column happens in this session, and only rows whose Stage(s) cell says *every stage* or names the stage the register (PROJECT.md) says you are in. Do not read the table ahead — a build session that only writes pages never opens the microflow rows. | Always relevant for | Reference this | Stage(s) | |---|---|---| @@ -25,7 +25,7 @@ Read a row when its Stage(s) cell says *every stage* or names the stage the regi | Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict | `skills/degrade-to-judgement.md` | every stage | | 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/tool-output-is-not-ground-truth.md` | every stage | | 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 | `skills/retesting-learned-rules.md` | every stage | -| Any pipeline work at all — every session, before producing any stage artifact (not just "when unsure"); READMEs and the guide are orientation only | `skills/conversion-runbook.md` | P,0,1,2,3,4,5,6,7 | +| Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only | `skills/conversion-runbook.md` | P,0,1,2,3,4,5,6,7 | | Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order | `skills/query-the-model.md` | P,0,1,2,3,4,5,6,7 | | Putting a question TO the user — any gate, any stage: ask in chat not in a file, two named options plus your recommendation, one batch per gate then end the turn | `skills/interview-protocol.md` | P,0,1,2,3,4,5,6,7 | | 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/checkpoints/checkpoint-template.md` | 0,1,2,3,4,6,7 |