diff --git a/CHANGELOG.md b/CHANGELOG.md index 20342404..30f396af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- fix(process): **follow-ups to the change log (#306): baseline cost, CRLF registers, gate wording.** (1) `skills/change-intake.md` went baseline for lead+ba at Stages 2–7 at 1,804 words without paying for it, against `render-routing.sh`'s "a new baseline row is paid for elsewhere" rule. It is now a 331-word core (trigger plus its one-line failure case, row columns, class → entry artifact, size → ask, Owners — now the single source the runbook and `agent-roles.md` point to, with the inline-edit/no-`UNSYNCED` rule — and Done when); the why-table, the wrong-vs-right example, the full tables, apply/prove steps, the owners table and the gate-check explanation moved verbatim to new on-demand `skills/change-intake-detail.md` (lead, ba, architect; Stages 2–7). Baseline tier 79,997 → 78,524 words (`render-routing.sh --check`, `LC_ALL=C`). (2) A `PROJECT.md` saved with CRLF line endings hid the section: `mxtk_change_log_has_section` never matched `## Change log\r`, so gate-check warned "no section", `sync-project.sh` appended a second empty one, and the scan counted 0 rows. Both readers in `bin/lib/change-log.sh` now drop a trailing `\r`; new fixture case T9 in `tests/wave2/test-change-log.sh` (CRLF copy scans, gates and syncs identically to the LF one; 5 of its cases fail on the previous code). The fixture also drops `pipefail`, which let an early-matching `grep -q` SIGPIPE its `printf` and fail T7 intermittently. (3) The skill's "Done when" expected `0 of M … not yet applied`, a string gate-check never prints; it now names the `PASS` line gate-check actually prints — MendixMau - 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 : 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 - 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 - 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 diff --git a/README.md b/README.md index 50f41d55..299231b6 100644 --- a/README.md +++ b/README.md @@ -511,6 +511,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini | Task | Skill to load | |---|---| +| Applying or proving a change request (CR row), a change whose class, size or status is unclear, or a "Change log:" gate line to explain: full class/size/ask tables, the wrong-vs-right example, apply and prove steps, the owners table and what the warn-only gate check counts | `skills/change-intake-detail.md` | | Deep, adaptive interview on one topic, on demand, when a checkpoint's 2+1 or a single question batch isn't enough | `skills/grill-mode.md` | | CAC-1, closing Stage 0 in EVERY entry mode — scope IN: full scope or a slice, and in what order. Opens with a brainstorm, not options | `skills/checkpoints/checkpoint-scope.md` | | CAC-1b, after Stage 1 — scope OUT: is what extraction produced what you meant. No gate stops you; run it late against the BRDs if it was skipped | `skills/checkpoints/checkpoint-extraction.md` | diff --git a/ROUTING.md b/ROUTING.md index 2c55707c..a2c3d1da 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -38,6 +38,7 @@ picks the row up. That is the whole procedure — there is no second list to rem | 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 | | 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` | lead,ba,architect | P,0,1,2,3,4,5,6,7 | baseline | | The user gives feedback or asks for a change mid-project — "change X", "it also needs Y", a remark on a screenshot or the running app, a stakeholder's ask relayed in chat: log a CR row in PROJECT.md ## Change log BEFORE any edit, size it, then edit the highest artifact it alters (BRD, decision, architecture, wireframe), never the MDL first | `skills/change-intake.md` | lead,ba | 2,3,4,5,6,7 | baseline | +| Applying or proving a change request (CR row), a change whose class, size or status is unclear, or a "Change log:" gate line to explain: full class/size/ask tables, the wrong-vs-right example, apply and prove steps, the owners table and what the warn-only gate check counts | `skills/change-intake-detail.md` | lead,ba,architect | 2,3,4,5,6,7 | ondemand | | Deep, adaptive interview on one topic, on demand, when a checkpoint's 2+1 or a single question batch isn't enough | `skills/grill-mode.md` | ba,architect | P,0,1,2,3,4,5,6,7 | ondemand | | 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` | lead,ba,architect | 0,1,2,3,4,6,7 | baseline | | CAC-1, closing Stage 0 in EVERY entry mode — scope IN: full scope or a slice, and in what order. Opens with a brainstorm, not options | `skills/checkpoints/checkpoint-scope.md` | ba,architect | 0 | ondemand | diff --git a/agents/architect-agent.md b/agents/architect-agent.md index 5e6927a3..bada50f3 100644 --- a/agents/architect-agent.md +++ b/agents/architect-agent.md @@ -44,6 +44,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local. | `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 | +| `skills/change-intake-detail.md` | Applying or proving a change request (CR row), a change whose class, size or status is unclear, or a "Change log:" gate line to explain: full class/size/ask tables, the wrong-vs-right example, apply and prove steps, the owners table and what the warn-only gate check counts | | `skills/grill-mode.md` | Deep, adaptive interview on one topic, on demand, when a checkpoint's 2+1 or a single question batch isn't enough | | `skills/checkpoints/checkpoint-scope.md` | CAC-1, closing Stage 0 in EVERY entry mode | | `skills/checkpoints/checkpoint-architecture.md` | CAC-3, after BRD validation and before architecture locks | diff --git a/agents/ba-agent.md b/agents/ba-agent.md index 92ef81ee..67383caf 100644 --- a/agents/ba-agent.md +++ b/agents/ba-agent.md @@ -56,6 +56,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local. | `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 | +| `skills/change-intake-detail.md` | Applying or proving a change request (CR row), a change whose class, size or status is unclear, or a "Change log:" gate line to explain: full class/size/ask tables, the wrong-vs-right example, apply and prove steps, the owners table and what the warn-only gate check counts | | `skills/grill-mode.md` | Deep, adaptive interview on one topic, on demand, when a checkpoint's 2+1 or a single question batch isn't enough | | `skills/checkpoints/checkpoint-scope.md` | CAC-1, closing Stage 0 in EVERY entry mode | | `skills/checkpoints/checkpoint-extraction.md` | CAC-1b, after Stage 1 | diff --git a/bin/gate-check.sh b/bin/gate-check.sh index d24a021c..3c7e26e1 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -1768,12 +1768,12 @@ stage_protocol_paths() { P) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/bootstrap-project.md skills/cloud-dev-environment.md skills/existing-app-change.md skills/app-analysis.md skills/mendix-epics-api.md skills/corpus-extraction-integrity.md skills/platform-link.md" ;; 0) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-scope.md skills/source-triage.md skills/image-transcription.md skills/small-project-tier.md skills/existing-app-change.md skills/app-analysis.md skills/layering-review.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/assess-migration.md skills/migration-pipeline.md skills/migrate-general.md skills/migrate-outsystems.md skills/source-os11.md skills/os-xml-schema.md skills/source-node-express-react.md skills/document-discovery.md skills/extractor-quality-loop.md skills/qa-loop-goal-pattern.md skills/mendix-epics-api.md skills/corpus-extraction-integrity.md skills/gate-check-file-locations.md" ;; 1) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-extraction.md skills/agent-roles.md skills/image-transcription.md skills/small-project-tier.md skills/migration-pipeline.md skills/source-os11.md skills/os-xml-schema.md skills/source-node-express-react.md skills/document-discovery.md skills/extractor-quality-loop.md skills/kb-generation.md skills/corpus-extraction-integrity.md" ;; - 2) echo "skills/interview-protocol.md skills/change-intake.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-brd.md skills/checkpoints/checkpoint-architecture.md skills/agent-roles.md skills/image-transcription.md skills/small-project-tier.md skills/kb-generation.md skills/brd-generation.md skills/brd-validation.md" ;; - 3) echo "skills/interview-protocol.md skills/change-intake.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/agent-roles.md skills/small-project-tier.md skills/mendix-best-practices-index.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;; - 4) echo "skills/interview-protocol.md skills/change-intake.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-build.md skills/agent-roles.md skills/small-project-tier.md skills/module-brief.md skills/module-folder-convention.md skills/brd-to-build-plan.md skills/coverage-ledger.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/learned-constants-and-secrets.md" ;; - 5|build-ready) echo "skills/interview-protocol.md skills/change-intake.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/unhappy-path-testing.md skills/monkey-test.md skills/e2e-locators-that-lie.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/learned-file-upload-widget.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; - 6) echo "skills/interview-protocol.md skills/change-intake.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/agent-roles.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/unhappy-path-testing.md skills/monkey-test.md skills/e2e-locators-that-lie.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; - 7) echo "skills/interview-protocol.md skills/change-intake.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/close-the-loop.md skills/share-demo-package.md skills/handoff-to-studio-pro.md skills/platform-link.md skills/teamserver-alignment.md skills/deploy-to-sandbox.md" ;; + 2) echo "skills/interview-protocol.md skills/change-intake.md skills/change-intake-detail.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-brd.md skills/checkpoints/checkpoint-architecture.md skills/agent-roles.md skills/image-transcription.md skills/small-project-tier.md skills/kb-generation.md skills/brd-generation.md skills/brd-validation.md" ;; + 3) echo "skills/interview-protocol.md skills/change-intake.md skills/change-intake-detail.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/agent-roles.md skills/small-project-tier.md skills/mendix-best-practices-index.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;; + 4) echo "skills/interview-protocol.md skills/change-intake.md skills/change-intake-detail.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-build.md skills/agent-roles.md skills/small-project-tier.md skills/module-brief.md skills/module-folder-convention.md skills/brd-to-build-plan.md skills/coverage-ledger.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/learned-constants-and-secrets.md" ;; + 5|build-ready) echo "skills/interview-protocol.md skills/change-intake.md skills/change-intake-detail.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/unhappy-path-testing.md skills/monkey-test.md skills/e2e-locators-that-lie.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/learned-file-upload-widget.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; + 6) echo "skills/interview-protocol.md skills/change-intake.md skills/change-intake-detail.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/agent-roles.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/unhappy-path-testing.md skills/monkey-test.md skills/e2e-locators-that-lie.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; + 7) echo "skills/interview-protocol.md skills/change-intake.md skills/change-intake-detail.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/close-the-loop.md skills/share-demo-package.md skills/handoff-to-studio-pro.md skills/platform-link.md skills/teamserver-alignment.md skills/deploy-to-sandbox.md" ;; *) echo "" ;; # esac @@ -2333,7 +2333,7 @@ fi # never written once, and a gate cannot see a marker nobody wrote. A change log makes the ask # countable; whether its counts are right on real projects is not yet known, and a blocking # guard built on an unproven count is how this repo has shipped false FAILs before. -# change-intake.md names the condition under which this becomes blocking. +# change-intake-detail.md "The mechanical check" names the condition under which this becomes blocking. CR_STATUS="PASS"; CR_NOTE=""; CR_ROWS="" if [ "$REG_AMBIGUOUS" = "1" ] || [ -z "$REGISTER" ] || [ ! -f "$REGISTER" ]; then CR_STATUS="MANUAL" diff --git a/bin/lib/change-log.sh b/bin/lib/change-log.sh index 6aefe476..783dc1d8 100644 --- a/bin/lib/change-log.sh +++ b/bin/lib/change-log.sh @@ -17,7 +17,7 @@ # toolkit pull) — both mandatory chain steps. Rows are written by the lead per change-intake.md. # # WARN-ONLY. gate-check.sh reports what mxtk_change_log_scan counts as a WARN line and never -# blocks on it. change-intake.md says when that changes, and why not yet. +# blocks on it. change-intake-detail.md "The mechanical check" says when that changes, and why not yet. # # Sourced, never executed. Callers are `set -euo pipefail`, so keep this side-effect free. @@ -33,9 +33,17 @@ Feedback and change requests, one row each, written BEFORE any edit (`skills/cha EOF } +# CRLF (2026-10-13 review of #306): a PROJECT.md saved on Windows ends every line in \r, so +# '^## +change log *$' never matched — gate-check reported "no section" and sync-project.sh +# appended a SECOND empty one; the scan likewise read 0 rows. Both readers drop a trailing \r +# first, as gate-check.sh does for every table it reads (tr -d '\r'). awk, not tr | grep -q: +# under the callers' pipefail an early-exiting grep -q can SIGPIPE the producer and turn a hit +# into a miss. +# # Usage: mxtk_change_log_has_section — rc 0 when the heading is present mxtk_change_log_has_section() { - [ -f "$1" ] && grep -qiE '^## +change log *$' "$1" + [ -f "$1" ] || return 1 + awk '{ sub(/\r$/, "") } tolower($0) ~ /^## +change log *$/ { found = 1; exit } END { exit !found }' "$1" } # Usage: mxtk_change_log_scan @@ -53,6 +61,7 @@ mxtk_change_log_scan() { function trim(s) { gsub(/^[ \t]+|[ \t]+$/, "", s); return s } function clean(s) { gsub(/[*`]/, "", s); return trim(s) } function owe(id, st, why) { rows = rows sprintf("ROW\t%s\t%s\t%s\t%s\n", id, st, why, ask) } + { sub(/\r$/, "") } # CRLF register: see mxtk_change_log_has_section //) incomment = 0; next } /^## / { insec = (tolower($0) ~ /^## +change log *$/); next } diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv index 200b80e4..2299fa62 100644 --- a/bin/lib/skill-routing.tsv +++ b/bin/lib/skill-routing.tsv @@ -74,6 +74,7 @@ skills-over-scripts skills/skills-over-scripts.md Before writing any .js or .sh 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 interview-protocol skills/interview-protocol.md 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 lead,ba,architect P,0,1,2,3,4,5,6,7 baseline spine change-intake skills/change-intake.md The user gives feedback or asks for a change mid-project — "change X", "it also needs Y", a remark on a screenshot or the running app, a stakeholder's ask relayed in chat: log a CR row in PROJECT.md ## Change log BEFORE any edit, size it, then edit the highest artifact it alters (BRD, decision, architecture, wireframe), never the MDL first lead,ba 2,3,4,5,6,7 baseline spine +change-intake-detail skills/change-intake-detail.md Applying or proving a change request (CR row), a change whose class, size or status is unclear, or a "Change log:" gate line to explain: full class/size/ask tables, the wrong-vs-right example, apply and prove steps, the owners table and what the warn-only gate check counts lead,ba,architect 2,3,4,5,6,7 ondemand spine grill-mode skills/grill-mode.md Deep, adaptive interview on one topic, on demand, when a checkpoint's 2+1 or a single question batch isn't enough ba,architect P,0,1,2,3,4,5,6,7 ondemand spine checkpoints 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 lead,ba,architect 0,1,2,3,4,6,7 baseline spine checkpoint-scope skills/checkpoints/checkpoint-scope.md CAC-1, closing Stage 0 in EVERY entry mode — scope IN: full scope or a slice, and in what order. Opens with a brainstorm, not options ba,architect 0 ondemand spine diff --git a/skills/agent-roles.md b/skills/agent-roles.md index 01ba7ba4..c730f06e 100644 --- a/skills/agent-roles.md +++ b/skills/agent-roles.md @@ -111,7 +111,7 @@ A single do-everything agent has no natural place to stop before mutating the re | **test-agent** | Walk UI test scenarios against the running app, cross-check against the database | No | No — read-only/verification-only | | **review-agent** | Owns `module-review.md` — the one pass that closes a module. Stage 3's model-side instruments (`bin/review-module.sh`: conformance + graph sweep) **and stage 4, the LOOK**: every page in the module assessed against wireframe, design system and plain design judgement. Diagnostic only — never fixes what it finds | No — never | Yes, but only its own report under `design/ui-reviews/`, via `Bash` | -**Who records a change, who flushes it.** A mid-build change or decision is *marked* by the lead: the `PROJECT.md` `## Change log` row, the decision row, any `[sync:]` marker. `mdl-agent` and `gate-agent` report it and never write `PROJECT.md`. `ba-agent` flushes BRDs and module briefs, and `architect-agent` flushes wireframes and `architecture/`. The single source is the Owners table in `change-intake.md`. +**Who records a change, who flushes it.** A mid-build change or decision is *marked* by the lead: the `PROJECT.md` `## Change log` row, the decision row, any `[sync:]` marker. `mdl-agent` and `gate-agent` report it and never write `PROJECT.md`. `ba-agent` flushes BRDs and module briefs, and `architect-agent` flushes wireframes and `architecture/`. The single source is the Owners section in `change-intake.md`. **The one rule that matters more than any other: only the main session (the one talking to the user) ever runs the command that mutates the real `.mpr`.** All six subagents get `tools: Read, Grep, Glob, Bash` — never `Write`/`Edit`. Agents that need to produce files (`ba-agent`, `architect-agent`, `mdl-agent`) do so via `Bash` (shell redirection/heredoc), not the `Write` tool — that keeps "can this agent silently overwrite something outside its lane" a visible, auditable choice in its tool list rather than an assumption. diff --git a/skills/change-intake-detail.md b/skills/change-intake-detail.md new file mode 100644 index 00000000..fca1c690 --- /dev/null +++ b/skills/change-intake-detail.md @@ -0,0 +1,150 @@ +# Change Intake — Detail: Why, Worked Example, Apply, Prove, Gate Check + +**Applies to:** any mxcli project with a `PROJECT.md` (migration, requirements-driven, greenfield, change an existing app), from Stage 2 onward. +**Purpose:** the on-demand half of `change-intake.md`. That file is the baseline core every lead and ba-agent session reads (trigger, row format, class → entry artifact, size → ask, owners, Done when). Read this one when you apply or prove a change request, when a class, size or status is unclear, or when the `Change log:` gate line needs explaining. +**Owns:** nothing on its own: `change-intake.md` owns the `## Change log` table in `PROJECT.md` and the classes, sizes and statuses. `conversion-runbook.md` §3b (drift-sync) is the BRD-flush step of this loop; `iterative-build-loop.md`, `close-the-loop.md` and `agent-roles.md` point at `change-intake.md`. + +**Trigger:** any message from the user that asks for something to be different from what the artifacts say or what was built, typed, pasted, relayed ("the finance lead wants..."), or said while looking at a screenshot or the running app. Not a trigger: answering a question you asked at a gate (that is `interview-protocol.md`), or a finding from a review pass (that is `finding-disposition.md`). + +--- + +## Why this exists: the change went into MDL, every time + +Across 12 mid-build changes on real projects: + +| What happened | Count | +|---|---| +| Change applied straight in an MDL script | 12 of 12 | +| BRD, build plan or wireframe updated for it | 0 of 12 | +| `[sync: … UNSYNCED]` drift markers ever written | 0 | +| One screenshot-driven fix: rounds before it stuck | 4 (it regressed twice, and every gate was green both times) | +| One settled entity change sent through ba-agent twice and architect-agent once | ~270k tokens for a handful of document edits | + +The drift gate passed on all 12, because it looks for a marker and nobody wrote one. A missing marker looks the same as nothing to sync. The second failure is the opposite one: too much ceremony for a change that was already settled. This skill fixes the first with a row you write *before* the edit. It fixes the second by scaling the ceremony to the size of the change. + +### Wrong vs right, same request + +The user, looking at the running app: *"The customer form also needs a VAT number."* + +**Wrong (what happened 12 times):** +``` +Sure — adding it now. + → mdlsource/0412-customer-vat.mdl ALTER ENTITY + ALTER PAGE, exec, green +PROJECT.md: no row. F003.brd.json: no VAT. wireframe: no field. build plan: no step. +Two sessions later a BRD-driven rebuild of the Customer page drops the field. Every gate is green. +``` + +**Right:** +``` +Logged CR-07: requirement, small → F003.brd.json + Customer_Edit, then MDL. + 1. PROJECT.md ## Change log: CR-07 row, status agreed (user typed it, small) + 2. F003.brd.json: VATNumber attribute + its validation, a one-leaf edit by the lead + 3. Customer_Edit page built → before/after screenshot pair in design/ui-reviews/ + 4. ./bin/exec.sh --cr CR-07 mdlsource/0412-customer-vat.mdl + 5. Journey customer-edit asserts the field; CR-07 → proven, Closed-by: , journey customer-edit +``` +The extra cost is two lines of text and one BRD leaf. The next agent that reads F003 gets VAT. + +--- + +## Step 1 — Capture: one row, before any edit + +Append a row to `PROJECT.md` → `## Change log` (the one decision register; no separate file). If the section is missing, `bin/sync-project.sh ` adds it. + +``` +| CR | Date | Source | Verbatim ask | Class | Size | Entry artifact | Status | Closed-by | +|---|---|---|---|---|---|---|---|---| +| CR-07 | 2026-10-13 | user | The customer form also needs a VAT number | requirement | S | F003.brd.json | agreed | | +``` + +- **CR**: `CR-` plus the next number. Never reuse a number. +- **Source**: `user`, or the stakeholder's name and role as the user gave it (`stakeholder (finance lead)`). +- **Verbatim ask**: the words as typed, not your summary. Your restatement goes in the reply (Step 3). Escape a pipe as `\|`. +- One ask, one row. "Also make the button blue and add a VAT field" is two rows. + +## Step 2 — Classify and size + +**Class → entry artifact.** The entry artifact is the highest layer the change alters. It is never the MDL. + +| Class | What changed | Entry artifact | +|---|---|---| +| `requirement` | what the app must do or store | the BRD (`*.brd.json`), plus a decision row if it settles a choice | +| `decision` | a choice recorded in `PROJECT.md` | a **new** `CONFIRMED` Decisions row whose Notes say `supersedes D-NN`, or `supersedes : ` if the register does not number its decisions. The old row's Status becomes `SUPERSEDED by CR-NN`. Its text is never edited | +| `structure` | module boundary, entity ownership, integration, security model | `architecture/` blueprint or the module brief | +| `visual` | how a page looks or flows | the wireframe while the page is unbuilt. Once it is built: a before/after screenshot pair in `design/ui-reviews/`, and the wireframe gets a "BUILT, see ui-reviews" stamp instead of upkeep | +| `impl` | how something is built, with no behaviour change | none: a regression journey only | +| `bug` | the build does not do what an artifact already says | none: the artifact was right. Add a regression journey that fails before the fix | + +**Size.** + +| Size | Test (all must hold for S) | +|---|---| +| **S** | one artifact per layer, one module, contradicts no `CONFIRMED` decision | +| **M** | several artifacts in a layer, or 2+ modules. Still contradicts nothing `CONFIRMED` | +| **L** | a new feature or module, or it contradicts a `CONFIRMED` decision | + +## Step 3 — Who is asked, and when (ask, then stop) + +Asking follows `interview-protocol.md` §3. On Claude Code use `AskUserQuestion`. On any other agent use numbered markdown, as §3 "Asking on a non-Claude agent" describes. Either way, end the turn and wait. + +| Situation | Ask? | Status path | Who edits | +|---|---|---|---| +| **S**, typed by the user themselves | **No question.** Reply with a one-line receipt: `Logged CR-07: visual, small → wireframe + page` | straight to `agreed` | the lead, inline. No subagent | +| **M** | Restate it in your reply (`refined`). Then **one batched question at the next module gate**: "Apply these N changes? CR-08, CR-09, CR-11" | `open` → `refined` → `agreed` at the gate | one `ba-agent` pass at the gate for the whole batch | +| **L**, or it contradicts a `CONFIRMED` decision | **Ask and stop now**, before anything is built: the proposal, two named options, your recommendation | `refined` → `agreed` / `rejected` | re-enter the pipeline at the owning stage for that slice (Stage 2 for a new BRD, Stage 3 for structure) | +| Stakeholder or relayed feedback, any size | Not on its own. It stays `open` until the user agrees or rejects. All such rows are surfaced together at the next gate | `open` → `agreed` / `rejected` | as for its size, after agreement | +| The meaning is ambiguous | **One** "A or B?" question. It is the only mid-stream interruption this skill allows | `open` until answered | — | + +A row the user rejects is kept, with Status `rejected — `. A rejected ask that nobody can find gets asked for again. + +## Step 4 — Apply: top down, as far down as needed + +1. Edit the entry artifact (Step 2). +2. Cascade down only to layers that *restate* what changed. Module briefs point to the BRD and do not copy it (`module-brief.md`), so most BRD edits need no brief edit. If the change adds or retires a build step, add or edit that row in the build plan. +3. Then write the MDL and run it with `./bin/exec.sh --cr CR-NN