diff --git a/CHANGELOG.md b/CHANGELOG.md index 105d7619..96185415 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,9 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m `docs/RELEASE-PROCESS.md` §8. ## Unreleased +- process(obligations): **`bin/lib/obligations.tsv` gains column 10 `modes`, the same column, tokens and tokeniser as `artifact-manifest.tsv` (`migration,requirements,greenfield,existing-app-change`, read through artifact-check.sh's own `_art_entry_mode`, never a second copy of its mapping)**: a row the register's `Entry mode:` does not list reads `N/A — not owed (entry mode …)`, never PASS; no or unrecognised mode = owed. Every row lists all four modes today, so no verdict changes; the column lets a mode that genuinely skips a pass be excused by data instead of by absence. Fixture `test-obligation-quality-floor.sh` T9 — follow-up to #787 +- fix(obligations): **`Must-haves: advisory` for projects already past Stage 5 when the must-haves row arrived (follow-up to #787)**: `sync-project.sh` writes one `Must-haves:` line into `PROJECT.md` when none exists, and only then: `advisory — joined at stage N before the must-haves row existed` when gate-check's derived Current stage or `Adopted at stage:` is 6 or 7, else `bound`. `init-project.sh` writes `bound` for new projects. An advisory project's `Obligation must-haves` row reads `ADVISORY` and is left out of the pending count; `bound` keeps PENDING. It is keyed on the written line, not the project's position: a position check would silence a new project the day it passed Stage 5 without the marks. Fixture `tests/wave2/test-must-haves-advisory.sh` — owner request at the review of #787 +- fix(obligations): **a quality floor in every entry mode: no per-module obligation reads PASS by absence, and a new `must-haves` row owes one mode-independent checklist per module**: with no module brief and no verify run, `obligation-check.sh` printed `Obligation look PASS — no module has been opened for work yet; nothing owed` (and the same for fidelity, sweep, journeys) on a project that had built ~78 pages and reviewed 0. Now an empty planned scope falls back to the modules that hold built pages, read from the look ledger (`.claude/loop/look/owed.tsv`), else page statements in the project's `*.mdl` scripts, else `.claude/loop/page-scope.json`, each looked for at the root, `app/` and `apps/*/`; every module row reads PENDING with an `OWED BY WHAT WAS BUILT: N page(s) built in M module(s) (...), K of M module(s) discharged` line. A model that has been built on (exec rows in `docs/BUILD-LOG.md`, `*.mdl` scripts, or a derived stage at 5+) with no countable pages is one FAULT naming `bin/page-scope.sh`, never "0 pages"; a `.mpr` with no build evidence (a fresh scaffold) keeps master's PASS line, so `bin/status.sh` still reads `modules opened: 0`. `existing-app-change` never takes scope from `page-scope.json`, which lists the whole model. A project with briefs keeps every earlier verdict. `skills/must-haves.md` (new, on demand) is the single source of poc-build.md's 12-row must-have checklist, generalised to every build type, plus row 13: every region the design shows is on the built page, counted; `poc-build.md` points to it, `module-review.md` stage 5 requires its mark `docs/progress/must-haves/.md` (first line `13 of 13 rows ticked or NOT DONE with a reason`). Informational, like every obligation row: no gate verdict or exit code changes; synced projects at Stage 5+ gain one `must-haves` PENDING row per module. Always-loaded words 64,984 -> 65,032 (budget 80,000). Fixture `tests/wave2/test-obligation-quality-floor.sh` — two field runs, unattended and requirements-driven, Nov 2026 - fix(status, agents): **`bin/status.sh` WATCHes an Agent Editor project whose extension module does not travel with the model (#778)**: Studio Pro reads `agenteditor.agent` from `modules/AgentEditor.mxmodule` beside the `.mpr`, and a sync of only `.mpr` + `mprcontents/` left it out of git, so the builder stayed green while every colleague's clone showed `unknown type 'agenteditor.agent'`. Two WATCH items, warn-only (exit code and every verdict unchanged), local files and `git ls-files` only, root and `app/` layouts: a `modules/*.mxmodule` git does not track, and a project using Agent Editor (`AgentEditorCommons` in `analysis/app-facts/inventory.json`, or a `create agent` statement in `mdlsource/`) with no `modules/AgentEditor*.mxmodule`. `skills/mendix-agents.md` (on demand) gains the rule plus the note that the GenAI key, `Encryption.EncryptionKey` and `GenAICommons.StoreTraces` belong in the Default configuration, not a start script. Empty agent references / missing model version (mendixlabs/mxcli#1867) and unset runtime constants are not checked: they need a captured agent document (option 2). Fixture `tests/wave2/test-status-extension-modules.sh` — field report from an Agent Editor project, Nov 2026 - fix(permissions): **exec approval `auto` no longer prompts on every exec's mode check, and `install-claude-hooks.sh` no longer runs unprompted (#782)**: `install-claude-permissions.sh` now allow-lists `exec-approval.sh`, `interview-mode.sh` and `permission-profile.sh`, so their reads run without a prompt, while their only writers, `--set` and `--clear`, prompt through six `ask` rules (`Bash(*exec-approval.sh*--set*)`, …) in the shared settings under every profile (an ask rule beats an allow rule, `full`'s bare `Bash` included). `install-claude-hooks.sh`, which writes `~/.claude/settings.json` for every repo on the machine, gets no allow rule. A re-install adds the ask rules and removes the hooks-installer rule an earlier install added (sidecar); entries someone else wrote are untouched, and `sync-project.sh`'s permission check names both until then. Field run on claude 2.1.325: the read ran, `--set auto` and `--clear` were refused, and with the ask rules removed `--set` ran — from the two independent reviews of #781 - process(skills): **trim PR, moves only: always-loaded words 66,271 -> 64,984 (budget 80,000); Stage 5 test 21,906 -> 20,619, gate 22,954 -> 21,744, review 31,681 -> 30,394 (#783)**: `testing-shape.md` §5's stack and scratch-copy mechanics move verbatim to `e2e-harness-base.md` § Bringing the stack up (the rule and a one-line list of its rules stay in §5); the three new Unit false-green rows move to `unit-test.md` § False-green rows (a pointer row stays in the register); `module-review.md`'s re-shoot mechanics move to `iterative-build-loop.md` § Pipeline mode (the rule, the denominator and the failure example stay) and its MXTK-AI001 sentence to `marketplace-catalogue.md` § Reviewing a built module. Every removed line is in its destination, checked line by line — weekly word-budget audit (#783) diff --git a/README.md b/README.md index 9da2cf91..bd3d799c 100644 --- a/README.md +++ b/README.md @@ -788,6 +788,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini | Running lint as a gate rather than a report — per-rule ratchet against a committed baseline, plus the crash and collapse guards that stop a blind rule passing | `project-bin/lint-gate.sh` | | Reading a lint result, or writing/repairing any .star rule — lint's failure mode is a confident clean pass, so 0 findings is a claim needing evidence | `skills/lint-that-actually-runs.md` | | Every module before it is called done; buttons, links or actions that do nothing when clicked — does every clickable thing actually do something; run AFTER the happy-path journey is green, never before | `skills/wiring-sweep.md` | +| Closing any module with pages, any build type — empty states, friendly refusals, active nav on first landing, list caps, 1280 and 390, every region the design shows; the floor owed even when planning was skipped | `skills/must-haves.md` | | The user asks for a full end-to-end test, a click-through proof, or does-everything-actually-work — or you are unsure which harness skill applies; this one routes you | `skills/full-harness-audit.md` | | End of any build+test cycle that wrote docs/report.json — did the testing itself hold up, not just get filed; one level up from finding-disposition | `skills/test-result-audit.md` | | Any report from a test/review run is about to be published — no report ends without a disposition for every finding | `skills/finding-disposition.md` | diff --git a/ROUTING.md b/ROUTING.md index 5fe4877d..8fabfa57 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -251,6 +251,7 @@ picks the row up. That is the whole procedure — there is no second list to rem | Running lint as a gate rather than a report — per-rule ratchet against a committed baseline, plus the crash and collapse guards that stop a blind rule passing | `project-bin/lint-gate.sh` | mdl,gate | 5,6 | ondemand | | Reading a lint result, or writing/repairing any .star rule — lint's failure mode is a confident clean pass, so 0 findings is a claim needing evidence | `skills/lint-that-actually-runs.md` | gate,review | 5,6 | ondemand | | Every module before it is called done; buttons, links or actions that do nothing when clicked — does every clickable thing actually do something; run AFTER the happy-path journey is green, never before | `skills/wiring-sweep.md` | mdl,test,review | 5,6 | ondemand | +| Closing any module with pages, any build type — empty states, friendly refusals, active nav on first landing, list caps, 1280 and 390, every region the design shows; the floor owed even when planning was skipped | `skills/must-haves.md` | mdl,test,review | 5,6 | ondemand | | The user asks for a full end-to-end test, a click-through proof, or does-everything-actually-work — or you are unsure which harness skill applies; this one routes you | `skills/full-harness-audit.md` | test,review | 5,6 | ondemand | | End of any build+test cycle that wrote docs/report.json — did the testing itself hold up, not just get filed; one level up from finding-disposition | `skills/test-result-audit.md` | test,review | 5,6 | ondemand | | Any report from a test/review run is about to be published — no report ends without a disposition for every finding | `skills/finding-disposition.md` | test,review,gate | 5,6 | ondemand | diff --git a/agents/mdl-agent.md b/agents/mdl-agent.md index 33be1bb0..7e04c7be 100644 --- a/agents/mdl-agent.md +++ b/agents/mdl-agent.md @@ -93,6 +93,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local. | `project-bin/lint-gate.sh` | Running lint as a gate rather than a report | | `skills/improvement-register.md` | Any review pass that runs more than once | | `skills/wiring-sweep.md` | Every module before it is called done; buttons, links or actions that do nothing when clicked | +| `skills/must-haves.md` | Closing any module with pages, any build type | | `skills/learned-workflow-patterns.md` | Writing or debugging a Mendix native Workflow (CREATE WORKFLOW/USER TASK/OUTCOMES) | | `skills/workflow-structure-rules.md` | Designing or reviewing a Workflow's SHAPE before or after the MDL | | `skills/rest-integration-first-time-right.md` | Building a REST integration (consumed or published) for the first time on a project | diff --git a/agents/review-agent.md b/agents/review-agent.md index d7be6d65..d0e1487f 100644 --- a/agents/review-agent.md +++ b/agents/review-agent.md @@ -94,6 +94,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local. | `skills/improvement-register.md` | Any review pass that runs more than once | | `skills/journey-examples.md` | Writing an actual .journey.json | | `skills/wiring-sweep.md` | Every module before it is called done; buttons, links or actions that do nothing when clicked | +| `skills/must-haves.md` | Closing any module with pages, any build type | | `skills/workflow-structure-rules.md` | Designing or reviewing a Workflow's SHAPE before or after the MDL | | `skills/rest-between-mendix-apps.md` | App-to-app REST or microservices: two or more Mendix apps you build that read each other over REST | | `skills/multi-app-release.md` | Releasing or deploying a change that CROSSES apps | diff --git a/agents/test-agent.md b/agents/test-agent.md index 14e3eee4..4403acee 100644 --- a/agents/test-agent.md +++ b/agents/test-agent.md @@ -74,6 +74,7 @@ This table is your whole list. The baseline table in the project's CLAUDE.local. | `skills/improvement-register.md` | Any review pass that runs more than once | | `skills/journey-examples.md` | Writing an actual .journey.json | | `skills/wiring-sweep.md` | Every module before it is called done; buttons, links or actions that do nothing when clicked | +| `skills/must-haves.md` | Closing any module with pages, any build type | | `skills/rest-between-mendix-apps.md` | App-to-app REST or microservices: two or more Mendix apps you build that read each other over REST | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit | | `skills/empty-widget-triage.md` | A page/grid/list/combobox renders or shows empty ('0 to 0 of 0', blank cells, zero rows, zero options) during UI review or an e2e run | diff --git a/bin/gate-check.sh b/bin/gate-check.sh index 4c15089d..1065b9dd 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -2871,8 +2871,8 @@ stage_protocol_paths() { 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/dispatching.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/dispatching.md skills/small-project-tier.md skills/mendix-best-practices-index.md skills/decompose-app.md skills/mendix-service-seam.md skills/layering-review.md skills/architecture-blueprint.md skills/marketplace-catalogue.md skills/modularize-domain.md skills/design-artifacts.md skills/process-map.md skills/interaction-model.md skills/brd-to-build-plan.md skills/learned-multilingual-app.md skills/workflow-structure-rules.md skills/rest-between-mendix-apps.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/dispatching.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/rest-between-mendix-apps.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/dispatching.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/decompose-app.md skills/mendix-service-seam.md skills/microflow-loop-antipatterns.md skills/rehost-app.md skills/marketplace-catalogue.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/learned-multilingual-app.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/load-test.md skills/unit-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/rest-between-mendix-apps.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/dispatching.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/decompose-app.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/rehost-app.md skills/qa-loop-goal-pattern.md skills/learned-multilingual-app.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/load-test.md skills/unit-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/demo-recording-polish.md skills/live-demo-autopilot.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/rest-between-mendix-apps.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" ;; + 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/dispatching.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/decompose-app.md skills/mendix-service-seam.md skills/microflow-loop-antipatterns.md skills/rehost-app.md skills/marketplace-catalogue.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/learned-multilingual-app.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/load-test.md skills/unit-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/must-haves.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/rest-between-mendix-apps.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/dispatching.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/decompose-app.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/rehost-app.md skills/qa-loop-goal-pattern.md skills/learned-multilingual-app.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/load-test.md skills/unit-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/demo-recording-polish.md skills/live-demo-autopilot.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/must-haves.md skills/workflow-structure-rules.md skills/rest-between-mendix-apps.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 "" ;; # diff --git a/bin/init-project.sh b/bin/init-project.sh index 70f9f89c..6141025e 100755 --- a/bin/init-project.sh +++ b/bin/init-project.sh @@ -200,6 +200,7 @@ Unit tests default: no Gate mode: check Pipeline mode: balanced Build type: full +Must-haves: bound diff --git a/bin/lib/obligation-check.sh b/bin/lib/obligation-check.sh index 3c7b8908..5df9a9ae 100755 --- a/bin/lib/obligation-check.sh +++ b/bin/lib/obligation-check.sh @@ -21,11 +21,19 @@ # ADOPTED the project joined the pipeline above this obligation's stage # NOT YET DUE final-look only: gate-check's derived Current stage has not reached its from-stage # N/A this project is not running the pipeline at all (a-la-carte; existing-app-assurance.md) +# ADVISORY must-haves only: the register says `Must-haves: advisory` (written once by +# sync-project.sh for a project already past Stage 5); shown, never counted set -uo pipefail _OB_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)" OBLIGATIONS_TSV="${OBLIGATIONS_TSV:-$_OB_LIB_DIR/obligations.tsv}" +# Entry mode: artifact-check.sh's _art_entry_mode() — its register read, entry_mode_token, and its +# requirements-driven → requirements translation at the boundary. Called, never copied: a second +# copy of that mapping is how the two tables would drift apart. Sourcing it only defines +# functions (its direct-invocation block is guarded), and gate-check.sh sources it anyway. +# shellcheck source=artifact-check.sh +[ -r "$_OB_LIB_DIR/artifact-check.sh" ] && . "$_OB_LIB_DIR/artifact-check.sh" # Skills in the `verify` group that deliberately owe no per-module artifact. The reverse check # warns about any verify-group skill NOT named by an obligation; anything listed here is an @@ -162,6 +170,25 @@ _ob_adopted_stage() { return 1 } +# _ob_must_haves_advisory → prints the reason and returns 0 when the register says +# `Must-haves: advisory — `. sync-project.sh writes that line ONCE, for a project already +# past Stage 5 when the must-haves row arrived (it could not have owed the mark while it built); +# every other project gets `Must-haves: bound`, from init-project.sh or that same first sync. +# Keyed on a written line, never on the project's position: "advisory once past Stage 5" would +# also silence a NEW project the moment it reached Stage 6 without the marks — absence-renders-green. +_ob_must_haves_advisory() { + local reg="$1" line key val + _ob_register_norm "$reg" + local IFS=$'\n' + for line in $_OB_REG_NORM; do + key="${line%%$'\t'*}"; val="${line#*$'\t'}" + [ "$key" = "must-haves" ] || continue + case "$val" in [Aa][Dd][Vv][Ii][Ss][Oo][Rr][Yy]*) printf '%s\n' "$val"; return 0 ;; esac + return 1 + done + return 1 +} + _ob_rank() { case "$1" in P|p) echo 0 ;; [0-7]) echo $(( $1 + 1 )) ;; *) echo 99 ;; esac; } # _ob_current_stage → prints P or 0-7 from the register's "## Current stage" line, or @@ -203,6 +230,122 @@ _ob_modules() { } 2>/dev/null | sed '/^$/d' | sort -u } +# ── the floor: owed by what was BUILT when nothing was planned ────────────── +# +# WHY (two field runs, 2026-11). Both were unattended requirements-driven builds with a full spec, +# clickable prototypes and a design system supplied. Run 1 skipped stages 1-4 outright: no BRDs, +# no blueprint, no build plan, no module briefs. It built about 78 pages across several apps, +# wrote 0 UI review reports, never ran page-fidelity.js, and the gate printed +# Obligation look PASS — no module has been opened for work yet; nothing owed +# for look, fidelity, sweep and journeys alike, because _ob_modules() keys scope to briefs and +# verify runs — artifacts of exactly the stages the run skipped. The screens missed whole sections +# the prototypes show. Run 2, another kit, the same: one glance at the prototypes, no per-screen +# look. The more stages a project skips, the quieter this check got; that inversion is the bug. +# +# So when the planned scope is EMPTY, the built scope is owed: every module that holds a page. +# A planned scope, when there is one, is left exactly as it was (a project with briefs keeps +# today's verdicts; an app that predates the toolkit still owes nothing for unbriefed modules). +# +# Where built pages are read from, first source that yields any page wins: +# 1. the look ledger .claude/loop/look/owed.tsv, column 3 (Module.Page) — written by exec.sh +# 2. page statements in the project's *.mdl scripts (CREATE / CREATE OR REPLACE|MODIFY / ALTER +# PAGE, the shapes look-ledger.sh's look_pages_in() was captured from; *.test.mdl skipped) +# 3. the model, via .claude/loop/page-scope.json "inScope" — written by bin/page-scope.sh +# Each is looked for at , /app and /apps/* — single-tree, two-tree and the +# several-apps-in-one-repo layout of the field run. (When the multi-app resolver lands in +# bin/lib/_common.sh, this list should defer to it.) No mxcli call: the gate stays read-only and +# fork-cheap; page-scope.sh is the remedy named when nothing can be read. +# +# Entry mode existing-app-change ($2): source 3 is never read. page-scope.json lists the WHOLE +# model, so it would make every legacy module owe every row — against this table's own rule that +# an app owes nothing for modules nobody is building. The ledger and the scripts name only pages +# this change wrote (review of #787). +# +# Sets _OB_BUILT_PAGES (Module.Page lines, unique) and _OB_BUILT_SRC (where they came from), or +# _OB_BUILT_SRC="" with _OB_BUILT_MPR=1 when a model exists but no source could count its pages. +# _OB_BUILT_SCRIPTS is the number of *.mdl build scripts found (build evidence, see below). +_OB_BUILT_PAGES=""; _OB_BUILT_SRC=""; _OB_BUILT_MPR=0; _OB_BUILT_DONE=""; _OB_BUILT_SCRIPTS=0; _OB_BUILT_ROOTS="" +_ob_built_pages() { + local root="$1" mode="${2:-}" t f roots + [ "$_OB_BUILT_DONE" = "$root|$mode" ] && return 0 + _OB_BUILT_DONE="$root|$mode"; _OB_BUILT_PAGES=""; _OB_BUILT_SRC=""; _OB_BUILT_MPR=0; _OB_BUILT_SCRIPTS=0 + roots="$root"$'\n'"$root/app" + for t in "$root"/apps/*/; do [ -d "$t" ] && roots="$roots"$'\n'"${t%/}"; done + _OB_BUILT_ROOTS="$roots" + + # 1. look ledger + local IFS=$'\n' + for t in $roots; do + f="$t/.claude/loop/look/owed.tsv" + [ -s "$f" ] && _OB_BUILT_PAGES="$_OB_BUILT_PAGES$(awk -F'\t' '$3 ~ /^[A-Za-z0-9_]+\.[A-Za-z0-9_]+$/ {print $3}' "$f" 2>/dev/null)"$'\n' + done + _OB_BUILT_PAGES="$(printf '%s' "$_OB_BUILT_PAGES" | sed '/^$/d' | LC_ALL=C sort -u)" + if [ -n "$_OB_BUILT_PAGES" ]; then _OB_BUILT_SRC=".claude/loop/look/owed.tsv"; return 0; fi + + # 2. page statements in *.mdl scripts. Pruned: VCS, dependencies, Mendix build output and the + # toolkit's own loop state — none of them is a build script, and deployment/ can be huge. + local scripts + scripts="$(find "$root" -maxdepth 7 \( -name .git -o -name node_modules -o -name deployment \ + -o -name .claude -o -name javasource -o -name vendorlib -o -name widgets -o -name themesource \ + -o -name theme -o -name resources \) -prune -o -type f -name '*.mdl' ! -name '*.test.mdl' -print 2>/dev/null \ + | LC_ALL=C sort)" + [ -n "$scripts" ] && _OB_BUILT_SCRIPTS="$(printf '%s\n' "$scripts" | wc -l | tr -d ' ')" + if [ -n "$scripts" ]; then + # Same statement shapes and comment rules as look_pages_in() (project-bin/look-ledger.sh); + # the last statement on a page across the scripts, in path order, decides (DROP removes). + _OB_BUILT_PAGES="$(printf '%s\n' "$scripts" | tr '\n' '\0' | xargs -0 awk ' + FNR == 1 { inc = 0 } + /^[[:space:]]*\/\*/ { inc=1 } + inc { if ($0 ~ /\*\//) inc=0; next } + /^[[:space:]]*--/ { next } + { l=toupper($0); act="" } + l ~ /^[[:space:]]*(CREATE([[:space:]]+OR[[:space:]]+(REPLACE|MODIFY))?|ALTER)[[:space:]]+PAGE[[:space:]]/ { act="owe" } + l ~ /^[[:space:]]*DROP[[:space:]]+PAGE[[:space:]]/ { act="drop" } + act != "" { + s=$0; sub(/^[[:space:]]*/, "", s) + n=split(s, w, /[[:space:]]+/); j=0 + for (i=1; i<=n; i++) if (toupper(w[i])=="PAGE") { j=i+1; break } + if (act=="drop" && toupper(w[j])=="IF" && toupper(w[j+1])=="EXISTS") j+=2 + name=w[j]; sub(/[(;{].*$/, "", name); gsub(/"/, "", name) + if (name ~ /^[A-Za-z0-9_]+\.[A-Za-z0-9_]+$/) last[name]=act + } + END { for (p in last) if (last[p]=="owe") print p }' 2>/dev/null | LC_ALL=C sort -u)" + if [ -n "$_OB_BUILT_PAGES" ]; then _OB_BUILT_SRC="page statements in *.mdl scripts"; return 0; fi + fi + + # 3. the model, as page-scope.sh recorded it — never for existing-app-change (header above) + [ "$mode" = "existing-app-change" ] && roots="" + for t in $roots; do + f="$t/.claude/loop/page-scope.json" + [ -s "$f" ] || continue + _OB_BUILT_PAGES="$_OB_BUILT_PAGES$(tr -d '\r' < "$f" | awk ' + /"inScope"[[:space:]]*:/ { on=1 } + on { s=$0; while (match(s, /"[A-Za-z0-9_]+\.[A-Za-z0-9_]+"/)) { print substr(s, RSTART+1, RLENGTH-2); s=substr(s, RSTART+RLENGTH) } + if ($0 ~ /\]/) exit }')"$'\n' + done + _OB_BUILT_PAGES="$(printf '%s' "$_OB_BUILT_PAGES" | sed '/^$/d' | LC_ALL=C sort -u)" + if [ -n "$_OB_BUILT_PAGES" ]; then _OB_BUILT_SRC=".claude/loop/page-scope.json (the model)"; return 0; fi + + # Nothing readable. A model on disk means pages may exist uncounted: say so, never "0 pages". + for t in $_OB_BUILT_ROOTS; do + for f in "$t"/*.mpr; do [ -f "$f" ] && { _OB_BUILT_MPR=1; break 2; }; done + done + return 0 +} + +# " pages in modules (A 30, B 12, ...)" for the built scope; modules on stdout via _OB_BUILT_MODS. +_OB_BUILT_MODS=""; _OB_BUILT_SUMMARY="" +_ob_built_scope() { + _ob_built_pages "$1" "${2:-}" + _OB_BUILT_MODS=""; _OB_BUILT_SUMMARY="" + [ -n "$_OB_BUILT_PAGES" ] || return 0 + _OB_BUILT_MODS="$(printf '%s\n' "$_OB_BUILT_PAGES" | awk -F. '{print $1}' | LC_ALL=C sort -u)" + # Sorted by module name before the count, so the line is the same on every run and platform. + _OB_BUILT_SUMMARY="$(printf '%s\n' "$_OB_BUILT_PAGES" | awk -F. '{print $1}' | LC_ALL=C sort | uniq -c | awk ' + { t += $1; m++; o = o (m > 1 ? ", " : "") $2 " " $1 } + END { printf "%d page(s) built in %d module(s) (%s)", t, m, o }')" +} + # Does the artifact exist for this unit? Echoes the file that discharges it, or nothing. _ob_find() { local root="$1" match="$2" pattern="$3" unit="$4" resolved f @@ -473,6 +616,29 @@ _ob_look_proof_broken() { return 0 } +# _ob_build_evidence → prints what shows the model has been BUILT ON, or +# nothing. A .mpr alone is not that: init-project.sh scaffolds projects that have one from day +# one, and an existing app arrives with one. The "pages could not be counted" FAULT fires only +# with this evidence; with none, the honest reading is "no module has been opened" (review of +# #787: every Stage P project with a .mpr read FAULT on six rows, and bin/status.sh's +# "modules opened: 0" turned into "≥1"). Evidence, any of: +# - an exec row in docs/BUILD-LOG.md (exec.sh's "| | `script` |" table rows) +# - *.mdl build scripts on disk (counted by _ob_built_pages) +# - gate-check's derived Current stage at 5 or later +# Not the register's stage alone as the switch: the field run had no Current stage line at all. +_ob_build_evidence() { + local cur_rank="$1" t f + local IFS=$'\n' + for t in $_OB_BUILT_ROOTS; do + f="$t/docs/BUILD-LOG.md" + [ -s "$f" ] && grep -qE '^\| [0-9]{4}-[0-9]{2}-[0-9]{2}T[^|]*\| `' "$f" 2>/dev/null \ + && { printf 'exec rows in %s' "${f#"$t"/}"; return 0; } + done + [ "${_OB_BUILT_SCRIPTS:-0}" -gt 0 ] && { printf '%s *.mdl script(s) with no page statement' "$_OB_BUILT_SCRIPTS"; return 0; } + [ "$cur_rank" -ge 6 ] && [ "$cur_rank" -lt 99 ] && { printf 'derived Current stage is 5 or later'; return 0; } + return 1 +} + # ── the forward check ─────────────────────────────────────────────────────── # mxtk_obligations_report [register-path] # Prints one line per obligation. Sets MXTK_OB_STATUS to the worst verdict seen. @@ -503,11 +669,29 @@ mxtk_obligations_report() { local adopted_rank=0 [ -n "$adopted" ] && adopted_rank="$(_ob_rank "$adopted")" + # Entry mode, in the manifest's tokens, via artifact-check.sh's own reader (see the source line + # at the top). Unknown or absent = every row owed; reader missing = every row owed, never N/A. + local mode="" + if command -v _art_entry_mode >/dev/null 2>&1; then + mode="$(_art_entry_mode "$reg" 2>/dev/null || true)" + fi + local current; current="$(_ob_current_stage "$reg")" local current_rank=99 [ -n "$current" ] && current_rank="$(_ob_rank "$current")" local modules; modules="$(_ob_modules "$root")" + # The floor (see _ob_built_pages): an empty planned scope falls back to the built one. + local floor=0 floor_fault_counted=0 build_ev="" + if [ -z "$modules" ]; then + _ob_built_scope "$root" "$mode" + if [ -n "$_OB_BUILT_MODS" ]; then modules="$_OB_BUILT_MODS"; floor=1 + # existing-app-change never takes the FAULT: its sources are this change's own writes, so + # "none found" is a measured zero for the change, and page-scope.sh would not be the remedy. + elif [ "$_OB_BUILT_MPR" = 1 ] && [ "$mode" != "existing-app-change" ]; then + build_ev="$(_ob_build_evidence "$current_rank" || true)" + fi + fi local ob performer scope match artifact denom degradable from_stage skill # Stage limit (#583): rows owed from a stage AFTER the one asked about are not evaluated — @@ -516,13 +700,23 @@ mxtk_obligations_report() { local limit_rank=99 skipped_n=0 from_rank [ -n "${MXTK_ROWS_UPTO:-}" ] && limit_rank="$(_ob_rank "$MXTK_ROWS_UPTO")" - while IFS=$'\t' read -r ob performer scope match artifact denom degradable from_stage skill; do + local modes + while IFS=$'\t' read -r ob performer scope match artifact denom degradable from_stage skill modes; do case "$ob" in ''|'#'*|obligation) continue ;; esac # _ob_rank inline: it was a command substitution (a fork) three times per row. case "$from_stage" in P|p) from_rank=0 ;; [0-7]) from_rank=$(( from_stage + 1 )) ;; *) from_rank=99 ;; esac if [ "$from_rank" -gt "$limit_rank" ]; then skipped_n=$((skipped_n+1)); continue; fi + # Entry mode (column 10): a row the declared mode does not owe is said out loud, never PASS. + if [ -n "$mode" ] && [ -n "$modes" ]; then + case ",$modes," in + *",$mode,"*) ;; + *) printf 'Obligation %-10s N/A — not owed (entry mode %s; row modes: %s) (%s)\n' "$ob" "$mode" "$modes" "$skill" + continue ;; + esac + fi + if [ "$from_rank" -lt "$adopted_rank" ]; then printf 'Obligation %-10s ADOPTED — project joined at stage %s, above this pass'"'"'s stage %s (%s)\n' \ "$ob" "$adopted" "$from_stage" "$skill" @@ -555,7 +749,17 @@ mxtk_obligations_report() { esac if [ -z "$units" ]; then - printf 'Obligation %-10s PASS — no module has been opened for work yet; nothing owed (%s)\n' "$ob" "$skill" + if [ "$scope" = "module" ] && [ -n "$build_ev" ]; then + # The model has been built on (build_ev) and nothing could count its pages: "could not + # measure" is FAULT, never "0 pages built". Counted once for all module rows, not per row. + printf 'Obligation %-10s FAULT — no module brief or verify run, and the built pages could not be counted (no look ledger, no page statements in *.mdl, no .claude/loop/page-scope.json) though the model has been built on (%s); run bin/page-scope.sh (%s)\n' "$ob" "$build_ev" "$skill" + if [ "$floor_fault_counted" = 0 ]; then + MXTK_OB_STATUS="FAULT"; MXTK_OB_N_FAULT=$((MXTK_OB_N_FAULT+1)); floor_fault_counted=1 + fi + else + # "no module has been opened" is parsed by bin/status.sh (MOD_OPENED): keep that phrase. + printf 'Obligation %-10s PASS — no module has been opened for work yet; nothing owed (%s)\n' "$ob" "$skill" + fi continue fi @@ -642,7 +846,13 @@ mxtk_obligations_report() { local scoped=$((total - waived_n)) tail="" [ "$waived_n" -gt 0 ] && tail=" ($waived_n waived)" - if [ -n "$faulted" ] || [ -n "$noproof" ] || [ -n "$unstamped" ] || [ -n "$noproto" ]; then + local advisory="" + if [ "$ob" = "must-haves" ] && { [ -n "$pending" ] || [ -n "$faulted" ]; } \ + && advisory="$(_ob_must_haves_advisory "$reg")"; then + # Reported, not counted: the module list stays visible, the pending total does not move. + printf 'Obligation %-10s ADVISORY — %d of %d discharged%s; NOT DONE:%s%s — register: Must-haves: %s (%s)\n' \ + "$ob" "$done_n" "$scoped" "$tail" "$pending" "${faulted:+; NO DENOMINATOR:$faulted}" "$advisory" "$skill" + elif [ -n "$faulted" ] || [ -n "$noproof" ] || [ -n "$unstamped" ] || [ -n "$noproto" ]; then local why_bits="" [ -n "$faulted" ] && why_bits="NO DENOMINATOR:$faulted — a pass that cannot say what it covered has not covered it" [ -n "$unstamped" ] && why_bits="${why_bits:+$why_bits; }NO VALID AT:$unstamped — an unstamped final LOOK can never go stale, so it is treated as no report (stamp it with the commit it was true at)" @@ -659,6 +869,11 @@ mxtk_obligations_report() { else printf 'Obligation %-10s PASS — %d of %d discharged%s (%s)\n' "$ob" "$done_n" "$scoped" "$tail" "$skill" fi + # The floor's denominator, under whichever verdict won: what the scope was taken from. + if [ "$floor" = 1 ] && [ "$scope" = "module" ]; then + printf 'Obligation %-10s OWED BY WHAT WAS BUILT: %s, %d of %d module(s) discharged — no module brief or verify run exists, so the scope is the modules that hold pages (source: %s)\n' \ + "$ob" "$_OB_BUILT_SUMMARY" "$done_n" "$scoped" "$_OB_BUILT_SRC" + fi # Printed under whichever verdict won: a stale unit is counted in NOT DONE above, and this # line says WHY it is owed again rather than letting it read as never-reviewed. if [ -n "$stale" ] && [ "$needs_proto" = 1 ]; then diff --git a/bin/lib/obligations.tsv b/bin/lib/obligations.tsv index 6e9e36ae..39494b5a 100644 --- a/bin/lib/obligations.tsv +++ b/bin/lib/obligations.tsv @@ -18,7 +18,7 @@ # # Read by bin/lib/obligation-check.sh, sourced from bin/gate-check.sh. # -# Format: TAB-separated, nine columns. Blank lines and #-comments ignored. +# Format: TAB-separated, ten columns. Blank lines and #-comments ignored. # 1 obligation stable id, used in waiver lines # 2 performer which agent owes it (agents/-agent.md) # 3 scope module — once per module that has been opened for work @@ -37,18 +37,28 @@ # 8 from-stage conversion-runbook stage at which this first becomes owed. A project that # ran `gate-check.sh --adopt ` owes nothing below its adoption point. # 9 skill the skill that governs the pass and holds every verdict +# 10 modes comma list of entry modes that owe it — the SAME column, tokens and reader as +# bin/lib/artifact-manifest.tsv column 6 (entry_mode_token in bin/lib/entry-mode.sh): +# migration,requirements,greenfield,existing-app-change. A register whose +# `Entry mode:` is not listed reads `N/A — not owed (entry mode …)`, said out loud, +# never PASS. No `Entry mode:` line, an unrecognised one, or an empty column = owed: +# louder, never quieter. Every row owes all four today (each mode reaches Stage 5; +# greenfield runs the design front end, so it reaches the Stage 3 rows too) — the +# column exists so a row a mode genuinely skips is excused by data, not by absence. +# À-la-carte projects are excused wholesale (no register and no briefs → N/A). +# Build type (poc) is not an entry mode and is not read here. # # WHAT THIS TABLE MUST NOT DO: force a back-fill. A project that joined at Stage 5 does not owe # Stage-1 artifacts, and an app that predates the toolkit does not owe anything for modules # nobody is building. Scope resolves against modules OPENED FOR WORK, never modules in the MPR. # An obligation is owed by the pass you are performing now, never by the app's history. # -obligation performer scope match artifact denominator degradable from-stage skill -look review module names design/ui-reviews/ui-review-*.html yes yes 5 skills/module-review.md -sweep test module path .claude/loop/sweep//sweep.md yes yes 5 skills/wiring-sweep.md -journeys test module path .claude/loop/verify//summary.tsv no no 5 skills/journey-proof.md -coherence architect cluster path .claude/loop/coherence/last-cluster-pass.tsv no yes 5 skills/process-coherence-pass.md -skeleton mdl project path docs/skeleton-proof.md yes no 5 skills/walking-skeleton.md +obligation performer scope match artifact denominator degradable from-stage skill modes +look review module names design/ui-reviews/ui-review-*.html yes yes 5 skills/module-review.md migration,requirements,greenfield,existing-app-change +sweep test module path .claude/loop/sweep//sweep.md yes yes 5 skills/wiring-sweep.md migration,requirements,greenfield,existing-app-change +journeys test module path .claude/loop/verify//summary.tsv no no 5 skills/journey-proof.md migration,requirements,greenfield,existing-app-change +coherence architect cluster path .claude/loop/coherence/last-cluster-pass.tsv no yes 5 skills/process-coherence-pass.md migration,requirements,greenfield,existing-app-change +skeleton mdl project path docs/skeleton-proof.md yes no 5 skills/walking-skeleton.md migration,requirements,greenfield,existing-app-change # workflow-count is the FIRST obligation below stage 5, and that gap is why it exists. Every row # above is from-stage 5: look, sweep, journeys, coherence, skeleton. So this table — the only @@ -72,7 +82,7 @@ skeleton mdl project path docs/skeleton-proof.md yes no 5 skills/walking-skeleto # nothing to count" alone reports NO-DENOM (#684). # That is deliberately NOT an optin row: an artifact a project must think of in order to owe is # an artifact nobody owes, which is the disease this whole table was built for. -workflow-count architect project path architecture/workflow-count.md yes yes 3 skills/workflow-structure-rules.md +workflow-count architect project path architecture/workflow-count.md yes yes 3 skills/workflow-structure-rules.md migration,requirements,greenfield,existing-app-change # design-reaches-app owes a mark for something no other pass can see: whether the design system # arrived in the built app at all. It was owed from stage 3 until #627 (2026-11-05): its only @@ -104,7 +114,7 @@ workflow-count architect project path architecture/workflow-count.md yes yes 3 s # # It is owed by mdl rather than review deliberately: the agent that performed the port is the # one that must show it landed. A producer for every consumer, in the same hands. -design-reaches-app mdl project path docs/design-reaches-app.md yes yes 5 project-bin/check-design-reaches-app.sh +design-reaches-app mdl project path docs/design-reaches-app.md yes yes 5 project-bin/check-design-reaches-app.sh migration,requirements,greenfield,existing-app-change # fidelity — the third row here, and the second time the same gap was found in the field (#109). # On a requirements-driven app replacement, project-bin/page-fidelity.js existed and was cited by @@ -124,7 +134,7 @@ design-reaches-app mdl project path docs/design-reaches-app.md yes yes 5 project # wireframe is waived explicitly: `--waive fidelity/ --reason "no wireframe"`. Owed by mdl # for the same reason as design-reaches-app: the hands that built the page are the hands that must # show it matches. -fidelity mdl module names docs/PAGE-FIDELITY.tsv no yes 5 skills/ui-loop.md +fidelity mdl module names docs/PAGE-FIDELITY.tsv no yes 5 skills/ui-loop.md migration,requirements,greenfield,existing-app-change # dispatch is the THIRD obligation below stage 5, and it is here because it is the only mark # that answers a different question from the others: not "was the pass any good" but "did the # work go through the agent that owns it at all". @@ -148,7 +158,7 @@ fidelity mdl module names docs/PAGE-FIDELITY.tsv no yes 5 skills/ui-loop.md # ("owes no denominator, just the line") — that is the governing text this column exists to # point at. The agent stub is the performer named in column 2 (mdl); it is not itself a skill # and holds no verdict of its own to point to (review of PR #99, 2026-09). -dispatch mdl module path .claude/loop/dispatch//scripts.tsv no yes 5 skills/agent-roles.md +dispatch mdl module path .claude/loop/dispatch//scripts.tsv no yes 5 skills/agent-roles.md migration,requirements,greenfield,existing-app-change # final-look is the whole-app LOOK, run last. The per-module `look` row above judges each # module as it was when that module was reviewed. It cannot see a later task undoing an earlier @@ -165,7 +175,7 @@ dispatch mdl module path .claude/loop/dispatch//scripts.tsv no yes 5 ski # stamped before the last model commit is stale (_ob_stale), so the pass is owed again after # any later change. Denominator required ("N of N pages, M of M roles"). Governed by # module-review.md § "The final LOOK". -final-look review project names design/ui-reviews/final-look-*.html yes yes 6 skills/module-review.md +final-look review project names design/ui-reviews/final-look-*.html yes yes 6 skills/module-review.md migration,requirements,greenfield,existing-app-change # prototype-look is the Stage 3 LOOK: the assembled design/prototype.html, the page the user # actually clicks, opened in a real browser at device widths before the Stage 3 sign-off @@ -188,4 +198,22 @@ final-look review project names design/ui-reviews/final-look-*.html yes yes 6 sk # LOOK is owed again — a v1 LOOK cannot discharge v2. With no design/prototype.html in either # layout the row reads N/A (a project with no UI owes no prototype LOOK); one that has screens but # never assembled them is caught by the Stage 3 wireframe gate, not here. -prototype-look review project names design/ui-reviews/prototype-look-*.html yes yes 3 skills/design-artifacts.md +prototype-look review project names design/ui-reviews/prototype-look-*.html yes yes 3 skills/design-artifacts.md migration,requirements,greenfield,existing-app-change + +# must-haves owes, per module, the ticked list in skills/must-haves.md: the build-type-independent +# floor (empty states, friendly refusals, active nav on first landing, no silent list cap, 1280 and +# 390, every region the design shows, ...). It started as poc-build.md's 12-row checklist, the one +# part a blind grader credited (10 of 10 against 5 of 10 for a plain build); a full build owed +# nothing like it, so a build that skipped planning skipped it too. +# +# Measured, two field runs, 2026-11 (unattended, requirements-driven, prototypes supplied): about +# 78 pages built, 0 reviewed, and the screens missed whole sections the prototypes show — +# dashboard tiles, status tiles, the side navigation. Row 13 ("every region the design shows is +# on the page") is the check that would have named each one. +# +# Producer: module-review.md stage 5 (review-agent writes the file with the report). Under docs/, +# tracked, not .claude/loop/ (git-ignored): a mark CI, reviewers and a fresh clone cannot see is +# how the field run's look ledger stayed hidden. Denominator +# on the first line: "N of N rows ticked or NOT DONE with a reason". Owed by built modules when no +# brief exists (the floor in obligation-check.sh), like every module row. +must-haves review module path docs/progress/must-haves/.md yes yes 5 skills/must-haves.md migration,requirements,greenfield,existing-app-change diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv index 7564a388..ce88bef5 100644 --- a/bin/lib/skill-routing.tsv +++ b/bin/lib/skill-routing.tsv @@ -205,6 +205,7 @@ lint-that-actually-runs skills/lint-that-actually-runs.md Reading a lint result, improvement-register skills/improvement-register.md Any review pass that runs more than once — module-review, coherence, monkey, wiring-sweep: findings accumulate across runs, a per-run report cannot show a trend mdl,gate,test,review 5,6 ondemand spine journey-examples skills/journey-examples.md Writing an actual .journey.json — the worked field-by-field reference for the contract journey-proof.md argues for test,review 5,6 ondemand requirements wiring-sweep skills/wiring-sweep.md Every module before it is called done; buttons, links or actions that do nothing when clicked — does every clickable thing actually do something; run AFTER the happy-path journey is green, never before mdl,test,review 5,6 ondemand verify +must-haves skills/must-haves.md Closing any module with pages, any build type — empty states, friendly refusals, active nav on first landing, list caps, 1280 and 390, every region the design shows; the floor owed even when planning was skipped mdl,test,review 5,6 ondemand verify learned-workflow-patterns skills/learned-workflow-patterns.md Writing or debugging a Mendix native Workflow (CREATE WORKFLOW/USER TASK/OUTCOMES) — syntax, the 11 workflow microflow statements, DECISION vs CALL MICROFLOW, and the two corruption classes (binary-version $Type, and create-before-reference) mdl 5 ondemand build/workflow workflow-structure-rules skills/workflow-structure-rules.md Designing or reviewing a Workflow's SHAPE before or after the MDL — where a path may end, boundary event vs event sub-process, parallel-split limits, outcome minimums, targeting from the sentence, multi-user decision methods, which edits break running instances; and any CE6689/CE1844/CE1845/MW0012 after a clean mxcli check architect,mdl,review 3,4,5,6 ondemand build/workflow rest-integration-first-time-right skills/rest-integration-first-time-right.md Building a REST integration (consumed or published) for the first time on a project — the checks that avoid a rebuild after the first live call mdl 4,5 ondemand build/integration diff --git a/bin/sync-project.sh b/bin/sync-project.sh index 8e74371e..d725f735 100755 --- a/bin/sync-project.sh +++ b/bin/sync-project.sh @@ -842,6 +842,33 @@ if [ -f "$PROJECT_DIR/PROJECT.md" ] && ! mxtk_change_log_has_section "$PROJECT_D CHANGES=$((CHANGES + 1)) fi +# --- 2b1a2. PROJECT.md: one-time `Must-haves:` line (the must-haves obligation, #787) ------------- +# The must-haves row (bin/lib/obligations.tsv, skills/must-haves.md) owes a per-module mark from +# Stage 5. A project already past Stage 5 when it arrived built every module without it, so it is +# recorded once as advisory: its row is shown, never counted. Every other project is bound. Written +# only when no `Must-haves:` line exists, so it is decided ONCE, on the first sync after the row +# landed — never re-derived from the project's position, or a new project would turn advisory the +# day it passed Stage 5 without the marks. init-project.sh writes `bound` for new projects. +# "Past Stage 5" = gate-check's derived Current stage is 6 or 7, or the register adopted at 6/7. +# The stage is the LAST line gate-check stamped into PROJECT.md; sync does not run gate-check. A +# stale or missing stamp therefore reads as bound, and the printed note names the hand edit. +# A stage nobody can read is not "past": bound, with the one line that changes it. +if [ -f "$PROJECT_DIR/PROJECT.md" ] && ! grep -qiE '^[*_ >-]*Must-haves:' "$PROJECT_DIR/PROJECT.md" \ + && [ -r "$TOOLKIT_ROOT/bin/lib/obligation-check.sh" ]; then + _mh_stage="$( . "$TOOLKIT_ROOT/bin/lib/obligation-check.sh" + c="$(_ob_current_stage "$PROJECT_DIR/PROJECT.md")"; a="$(_ob_adopted_stage "$PROJECT_DIR/PROJECT.md" || true)" + case "$c" in (6|7) printf '%s' "$c"; exit 0 ;; esac + case "$a" in (6|7) printf '%s' "$a" ;; esac )" + if [ -n "$_mh_stage" ]; then + printf '\nMust-haves: advisory — joined at stage %s before the must-haves row existed (skills/must-haves.md; change to `bound` to owe it)\n' "$_mh_stage" | w_app "$PROJECT_DIR/PROJECT.md" + echo "${DRY:-}Updated: PROJECT.md — Must-haves: advisory (past Stage 5 before the row existed; the must-haves row is shown, not counted)." + else + printf '\nMust-haves: bound\n' | w_app "$PROJECT_DIR/PROJECT.md" + echo "${DRY:-}Updated: PROJECT.md — Must-haves: bound (each module with pages owes docs/progress/must-haves/.md; already past Stage 5? set \`Must-haves: advisory — \`)." + fi + CHANGES=$((CHANGES + 1)) +fi + # --- 2b1b. PROJECT.md: say out loud what a missing `Pipeline mode:` line means (#686) -------- # No line = balanced (project-bin/_common.sh mxtk_pipeline_mode), which moved journeys, the # 390 + 1280 LOOK and the pre-push full build from per row to module close. Report only: the diff --git a/skills/module-review.md b/skills/module-review.md index 200d22b2..d453c45f 100644 --- a/skills/module-review.md +++ b/skills/module-review.md @@ -395,6 +395,11 @@ summed them until a systematic sweep. **A fix found faster in Studio Pro than the root cause was found is not a closed bug.** Record it as unexplained or it will return. +**Before closing the pass, tick `skills/must-haves.md`** (13 rows, every build type) and write +`docs/progress/must-haves/.md`, first line `13 of 13 rows ticked or NOT DONE with a reason`. +No file, no close: `Obligation must-haves` reads PENDING. *Failure: screens missing the tiles and +side navigation the prototype showed, called done.* + **Before closing the pass, append every P1/P2 to `docs/improvement-register.md`** (`improvement-register.md`) — one row per finding, with its defect class from that skill's fixed vocabulary. This is what turns "did this recur" from an archaeology project across dated HTML diff --git a/skills/must-haves.md b/skills/must-haves.md new file mode 100644 index 00000000..41af9734 --- /dev/null +++ b/skills/must-haves.md @@ -0,0 +1,44 @@ +# Must-haves — the floor every built module owes, whatever the build type + +**Applies to:** every module with pages, in every entry mode and build type (full, POC, high-speed, change an existing app). Single source of this list: `skills/poc-build.md` and `skills/module-review.md` point here. +**Purpose:** The checks a user notices in the first minute, owed even when planning was skipped. Skipping stages must never also switch off these. + +**When:** at module close, with the module-review report (stage 5). Owed per module by `bin/lib/obligations.tsv` row `must-haves`; with no module brief, the modules that hold built pages owe it. + +## The list (every row ticked, or NOT DONE with a reason; never silently left out) + +| # | Check | Failure it prevents | +|---|---|---| +| 1 | User name, role and logout visible in the top bar (or the layout's equivalent) | Nobody can tell who is signed in | +| 2 | An empty state on every list | A blank white area reads as broken | +| 3 | Seed data visible to the user who should see it | "My requests" empty: seeded rows had no owner | +| 4 | Every refusal is a friendly in-page message, never the default error dialog | Refusal showed the stock error box | +| 5 | The active navigation item is the current page, checked on first landing after login and on a deep link, not after a menu click | Item bold only after a click; first page seen had none active | +| 6 | No list silently capped: visible pager or count | Gallery stopped at 20 items; journey run 3 failed | +| 7 | Every page checked at 1280 and at 390, and every role reaches each of its pages at 390 | Nav clipped, modal buttons below the fold; menu toggle hidden at phone width, one role lost its second page | +| 8 | Journey re-runnable on a used database: unique data, cleans up or tolerates leftovers | Run 1's test rows broke run 2 | +| 9 | No debug or demo affordance over the designed pages (Mendix's `.mx-demouserswitcher`: hide it in the theme) | Debug button on the finished design | +| 10 | Every cross-page flow has one owner and is run once end to end by a user who starts with NO data | List stayed empty after the first filing; journey passed with a seeded user | +| 11 | Every empty state seen in the browser once (a no-data user, or a filter that returns none); a state no role can reach is marked "not reachable" with the reason | Empty states were built and never seen | +| 12 | Data clean at hand-over: no journey or test leftovers on the main screen | Random-named test rows under the designed screen | +| 13 | Every region the design shows (wireframe, prototype or design-system page) is on the built page: count regions per page, `K of K present`, each missing one named | Field run: dashboard tiles, status tiles and the side navigation absent from screens whose prototypes showed them; 78 pages built, 0 reviewed | + +Row 3: `System.owner` cannot be set from a microflow; give the entity an association to `System.User`, filter on it `= '[%CurrentUser%]'`, seed that (`bin/bug-lookup.sh owner` first). +Row 13 with no design supplied: the yardstick is the module brief or the use case; write `13 NOT DONE — no design to count against` only when neither exists. + +## The mark + +Write `docs/progress/must-haves/.md`. **First line, the denominator:** + +``` + · 13 of 13 rows ticked or NOT DONE with a reason · pages 6 of 6 +``` + +then one line per row: `<#> TICKED — ` or `<#> NOT DONE — `. A row with neither is not ticked. `bin/gate-check.sh` reads only that the file exists and states its denominator (`Obligation must-haves`); whether the evidence holds is the reviewer's judgement. + +*Failure it prevents:* a module called done with `13 of 13` claimed and row 13 resting on "matches the prototype", no region counted. Name the regions. + +## Done when + +- `docs/progress/must-haves/.md` exists for every module that holds a page, first line `13 of 13 rows ticked or NOT DONE with a reason`. +- Every NOT DONE carries its reason, and the module's report or hand-over repeats it. diff --git a/skills/poc-build.md b/skills/poc-build.md index c7d63c66..2ceb492c 100644 --- a/skills/poc-build.md +++ b/skills/poc-build.md @@ -3,7 +3,7 @@ **Applies to:** a project whose kickoff answer (intake Q16) is the POC build, or whose user explicitly asks for one past kickoff; `PROJECT.md` says `Build type: poc`. **Purpose:** A clickable, good-looking, working app in front of people fast, continuable by a normal build. -**Status: EXPERIMENTAL.** Two builds driven by this text, one model, small apps. First (fictional visitor-pass app, ~36 min): "nearly demo-ready", function 26 of 29, design ~4.1 of 5 (not blind), journey 22/22. Second (kickoff question asked first, answered POC; ~64 min): a blind grader compared it with the same requirements built in plain plan mode with no toolkit: function 25 of 25 against 24 of 24 testable; refusals in-page 7 of 7 against 2 of 6; must-haves 10 of 10 against 5 of 10; visual mean 3.8 against 3.6; hand-over 22 of 24 against 12 of 24; time ~64 against ~27 min (both ran in parallel, inflated). The gain is the must-have list and the hand-over, not the look, and it costs time. NOT proven: a real person answering (answers and approval came from a prepared file). The test cadence (steps 7–8) changed after both builds (#770) and is unmeasured. +**Status: EXPERIMENTAL.** Two builds driven by this text, one model, small apps. First (fictional visitor-pass app, ~36 min): "nearly demo-ready", function 26 of 29, design ~4.1 of 5 (not blind), journey 22/22. Second (kickoff question asked first, answered POC; ~64 min): a blind grader compared it with the same requirements built in plain plan mode with no toolkit: function 25 of 25 against 24 of 24 testable; refusals in-page 7 of 7 against 2 of 6; must-haves 10 of 10 against 5 of 10 (the list now in `skills/must-haves.md`); visual mean 3.8 against 3.6; hand-over 22 of 24 against 12 of 24; time ~64 against ~27 min (both ran in parallel, inflated). The gain is the must-have list and the hand-over, not the look, and it costs time. NOT proven: a real person answering (answers and approval came from a prepared file). The test cadence (steps 7–8) changed after both builds (#770) and is unmeasured. **Who asks.** The kickoff interview asks the build type first, at project birth (intake Q16; rendering per `skills/interview-protocol.md` §3). On a POC answer `Build type: poc` is recorded `CONFIRMED` in `PROJECT.md`, and this skill is the flow; the other intake questions are not asked. A missing `Build type:` line means `full`; `Interview mode: auto` never picks `poc`. A project past kickoff whose user only says "we need a demo this week" does NOT switch: the lead says in one line that the build type is chosen at the start and offers to continue the normal build (optionally `Pipeline mode: high-speed`). Switching such a project needs the user to say so explicitly, confirmed once, and is recorded in `PROJECT.md` as a decision. *Failure: a Stage 5 project whose user mentioned a demo dropped its gates.* A POC build does **not** run the nine stage gates. Stage P still checks that every `intake.md` question carries an answer marker, so write them: Q16 `Answered (CONFIRMED): POC build`, and under each of Q1–Q15 exactly `Unverified — how to verify: not asked, POC build (Build type: poc, skills/poc-build.md); ask it if the build continues as a full build`. Then `bin/gate-check.sh` shows Stage P `PASS` (markers present; it says nothing about those answers), Stages 0–4, 6, 7 `PENDING`, Stage 5 `MANUAL`. *Failure: unmarked questions kept Stage P at `FAIL` for the whole build.* No answer: end the turn and wait (`skills/interview-protocol.md` §3); `ASSUMED` only when the user said "you decide" (= `full`). @@ -40,31 +40,16 @@ Design artifacts (design system, wireframes, clickable prototype) → one **APPR STILL BINDING in a POC build: access rules and grants in the same script that creates the entity or microflow (`skills/security-is-not-a-later-script.md`), every model write through `bin/exec.sh` (`--commit-first`), exec approval mode, the Production security level, ask-then-stop for every question, explicit-path commits (`git commit -- `, never `git add -A` or `git add .`), and saying in chat before a destructive or security-level change. -## Must-have checklist (all 12 rows ticked or listed as NOT DONE with a reason) - -| # | Check | Failure it prevents | -|---|---|---| -| 1 | User name, role and logout visible in the top bar | Demo cannot show who is signed in | -| 2 | An empty state on every list | A blank white area reads as broken | -| 3 | Seed data visible to the demo user who should see it | "My requests" empty: seeded rows had no owner | -| 4 | Every refusal is a friendly in-page message, never the default error dialog | Refusal showed the stock error box | -| 5 | The active navigation item is the current page, checked on first landing after login and on a deep link, not after a menu click | Item bold only after a click; first page seen had none active | -| 6 | No list silently capped: visible pager or count | Gallery stopped at 20 items; journey run 3 failed | -| 7 | Every page checked at 1280 and at 390, and every role reaches each of its pages at 390 | Nav clipped, modal buttons below the fold; menu toggle hidden at phone width, one role lost its second page | -| 8 | Journey re-runnable on a used database: unique data, cleans up or tolerates leftovers | Run 1's test rows broke run 2 | -| 9 | No demo-user switcher floating over the designed pages (Mendix's own `.mx-demouserswitcher`; hide it in the theme) | Debug button on the finished design | -| 10 | Every cross-page flow has one owner and is run once end to end by a user who starts with NO data | List stayed empty after the first filing; journey passed with a seeded user | -| 11 | Every empty state seen in the browser once (the no-data demo user, or a filter that returns none); a state no role can reach is marked "not reachable" in the hand-over | Empty states were built and never seen | -| 12 | Demo data clean at hand-over: no journey leftovers on the main screen | Random-named test rows under the designed screen | +## Must-have checklist -Before hand-over, run `bin/security-check.sh`: show the person its security findings and `docs/security/access-snapshot.txt`, and record their approval (`--approve --reason`, `--accept` per finding; an agent never approves). +`skills/must-haves.md` — the one list for every build type (13 rows; empty states, friendly refusals, active nav on first landing, no silent list cap, 1280 and 390, regions the design shows, ...). Read it before the first page and tick it before hand-over; write its mark, `docs/progress/must-haves/.md`. Row 9: hide the demo-user switcher; row 12: demo data clean. -Row 3: `System.owner` cannot be set from a microflow; give the entity an association to `System.User`, filter on that association `= '[%CurrentUser%]'`, seed that (`bin/bug-lookup.sh owner` first). +Before hand-over, run `bin/security-check.sh`: show the person its security findings and `docs/security/access-snapshot.txt`, and record their approval (`--approve --reason`, `--accept` per finding; an agent never approves). ## Done when - The approval stop is answered and recorded in `PROJECT.md`. -- Checklist: 12 of 12 ticked or listed under NOT DONE with a reason. +- Checklist (`skills/must-haves.md`): 13 of 13 ticked or listed under NOT DONE with a reason, per module. - Journey: 2 of 2 runs pass (warm, then cold after one restart), output pasted, not summarised; every session it opens logs out; one deliberately broken control run fails at the changed step; every negative and cross-user step of step 8 present or listed unreachable. - Screenshots: the final pass at 1280 and 390 for every page, each compared with its wireframe or the prototype; demo data clean afterwards. - Hand-over documents exist (one per use case, all 5 sections); the final message lists what is NOT built. Claim no unrun pass. diff --git a/tests/wave2/test-must-haves-advisory.sh b/tests/wave2/test-must-haves-advisory.sh new file mode 100755 index 00000000..5449d9e2 --- /dev/null +++ b/tests/wave2/test-must-haves-advisory.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +# Usage: bash tests/wave2/test-must-haves-advisory.sh /path/to/bin/sync-project.sh +# (bin/init-project.sh and bin/lib/obligation-check.sh are derived from its directory) +# +# The must-haves row (#787) owes a per-module mark from Stage 5. A project already past Stage 5 +# when the row arrived is recorded ONCE as `Must-haves: advisory` by sync-project.sh: the row is +# shown, never counted. Everyone else is `Must-haves: bound` (init-project.sh, or the first sync). +# Keyed on the written line, never on position — a position check would silence a NEW project the +# day it passed Stage 5 without the marks. +# +# Positive control: against #787 without this change, T1-T4 fail (no line written, no ADVISORY). +set -uo pipefail +SYNC="${1:?usage: test-must-haves-advisory.sh /path/to/bin/sync-project.sh}" +SYNC="$(cd "$(dirname "$SYNC")" && pwd)/$(basename "$SYNC")" +INIT="$(dirname "$SYNC")/init-project.sh" +OBCHECK="$(dirname "$SYNC")/lib/obligation-check.sh" +for f in "$INIT" "$OBCHECK"; do [ -r "$f" ] || { echo "missing $f"; exit 2; }; done +WORK="$(mktemp -d "${TMPDIR:-/tmp}/mh-adv.XXXXXX")" +trap '[ -n "${KEEP:-}" ] || rm -rf "$WORK"' EXIT +export MXTK_NO_GUIDE=1 +PASS=0; FAIL=0 +ok() { PASS=$((PASS+1)); printf ' ok %s\n' "$1"; } +bad() { FAIL=$((FAIL+1)); printf ' FAIL %s\n' "$1"; } +mhline() { grep -E '^Must-haves:' "$1/PROJECT.md"; } + +echo "== T1: a new project is bound from birth ==" +bash "$INIT" "$WORK/fresh" /dev/null 2>&1 +case "$(mhline "$WORK/fresh")" in "Must-haves: bound") ok "init writes bound" ;; *) bad "init: $(mhline "$WORK/fresh")" ;; esac + +echo "== T2: a project adopted at Stage 6 with no line is made advisory, once ==" +bash "$INIT" "$WORK/old" /dev/null 2>&1 +sed -i.bak '/^Must-haves:/d' "$WORK/old/PROJECT.md" && rm -f "$WORK/old/PROJECT.md.bak" +printf '\nAdopted at stage: 6\n' >> "$WORK/old/PROJECT.md" +bash "$SYNC" "$WORK/old" /dev/null 2>&1 +case "$(mhline "$WORK/old")" in "Must-haves: advisory"*"stage 6"*) ok "sync writes advisory" ;; *) bad "sync: $(mhline "$WORK/old")" ;; esac +bash "$SYNC" "$WORK/old" /dev/null 2>&1 +[ "$(mhline "$WORK/old" | wc -l | tr -d ' ')" = 1 ] && ok "second sync writes nothing more" || bad "line duplicated" + +echo "== T3: a project not past Stage 5 with no line is made bound ==" +bash "$INIT" "$WORK/mid" /dev/null 2>&1 +sed -i.bak '/^Must-haves:/d' "$WORK/mid/PROJECT.md" && rm -f "$WORK/mid/PROJECT.md.bak" +bash "$SYNC" "$WORK/mid" /dev/null 2>&1 +case "$(mhline "$WORK/mid")" in "Must-haves: bound") ok "sync writes bound" ;; *) bad "sync: $(mhline "$WORK/mid")" ;; esac + +echo "== T4: advisory is shown, not counted; bound is PENDING and counted ==" +Q="$WORK/q"; mkdir -p "$Q/architecture/modules/Orders" +printf 'Must-haves: advisory — joined at stage 6 before the must-haves row existed\n' > "$Q/PROJECT.md" +l="$(MXTK_ROWS_UPTO=5 "$OBCHECK" "$Q" 2>/dev/null | grep '^Obligation must-haves ')" +case "$l" in *ADVISORY*"0 of 1"*Orders*) ok "$l" ;; *) bad "expected ADVISORY: $l" ;; esac +a="$( . "$OBCHECK"; mxtk_obligations_report "$Q" >/dev/null; echo "$MXTK_OB_N_PENDING")" +printf 'Must-haves: bound\n' > "$Q/PROJECT.md" +l="$(MXTK_ROWS_UPTO=5 "$OBCHECK" "$Q" 2>/dev/null | grep '^Obligation must-haves ')" +case "$l" in *PENDING*"0 of 1"*) ok "bound reads PENDING" ;; *) bad "expected PENDING: $l" ;; esac +b="$( . "$OBCHECK"; mxtk_obligations_report "$Q" >/dev/null; echo "$MXTK_OB_N_PENDING")" +[ "$b" = $((a+1)) ] && ok "advisory row not in the pending count ($a vs $b)" || bad "counts: advisory $a, bound $b" + +echo "pass=$PASS fail=$FAIL" +[ "$FAIL" -eq 0 ] diff --git a/tests/wave2/test-obligation-quality-floor.sh b/tests/wave2/test-obligation-quality-floor.sh new file mode 100755 index 00000000..978b1c91 --- /dev/null +++ b/tests/wave2/test-obligation-quality-floor.sh @@ -0,0 +1,149 @@ +#!/usr/bin/env bash +# Usage: bash tests/wave2/test-obligation-quality-floor.sh /path/to/bin/gate-check.sh +# (bin/lib/obligation-check.sh is derived from its directory) +# +# The quality floor: no per-module obligation reads PASS by absence. Two field runs (2026-11, +# unattended, requirements-driven, several Mendix apps in one repo under apps//) skipped +# stages 1-4, so no module brief and no build plan existed; about 78 pages were built and 0 +# reviewed, and gate-check printed +# Obligation look PASS — no module has been opened for work yet; nothing owed +# for look, fidelity, sweep and journeys. With no planned scope, the built scope is now owed. +# +# Layout: apps//.mpr + apps//mdlsource/*.mdl, no architecture/, no build plan — +# the shape of field run 1. The page scripts are the repo's captured page scripts +# (fixtures/page-fidelity-mocks/demo-*.mdl) under the apps' module names. +# +# Positive control: against master's obligation-check.sh, T1 (look PASS by absence) and T5 fail; +# against 9de09b5, T6 fails (FAULT on a fresh scaffold with a .mpr) and T6b fails. +set -uo pipefail +GATE="${1:?usage: test-obligation-quality-floor.sh /path/to/bin/gate-check.sh}" +GATE="$(cd "$(dirname "$GATE")" && pwd)/$(basename "$GATE")" +OBCHECK="$(dirname "$GATE")/lib/obligation-check.sh" +[ -r "$OBCHECK" ] || { echo "no obligation-check.sh at $OBCHECK"; exit 2; } +HERE="$(cd "$(dirname "$0")" && pwd)" +CAP="$HERE/fixtures/page-fidelity-mocks" +[ -r "$CAP/demo-list.mdl" ] && [ -r "$CAP/demo-overview.mdl" ] || { echo "captured page scripts missing under $CAP"; exit 2; } +WORK="$(mktemp -d "${TMPDIR:-/tmp}/ob-floor.XXXXXX")" +trap '[ -n "${KEEP:-}" ] || rm -rf "$WORK"' EXIT +PASS=0; FAIL=0 +ok() { PASS=$((PASS+1)); printf ' ok %s\n' "$1"; } +bad() { FAIL=$((FAIL+1)); printf ' FAIL %s\n' "$1"; } + +register() { printf 'Toolkit commit: none\n\n| Stage | Decision | Status | Notes |\n|---|---|---|---|\n' > "$1/PROJECT.md"; } +# A captured page script, re-homed into module as page . +page_script() { sed "s/Demo\.Demo_List/$1.$2/; s/Demo\.Demo_Overview/$1.$2/; s/Demo\.App_Default/$1.Layout/" "$CAP/$3"; } + +P="$WORK/multi"; mkdir -p "$P/apps/Portal/mdlsource" "$P/apps/Backoffice/mdlsource" +register "$P" +: > "$P/apps/Portal/Portal.mpr"; : > "$P/apps/Backoffice/Backoffice.mpr" +page_script Dashboard Home demo-overview.mdl > "$P/apps/Portal/mdlsource/10-dashboard.mdl" +page_script Dashboard Status demo-list.mdl >> "$P/apps/Portal/mdlsource/10-dashboard.mdl" +page_script Requests Request_List demo-list.mdl > "$P/apps/Portal/mdlsource/20-requests.mdl" +page_script Cases Case_Overview demo-overview.mdl > "$P/apps/Backoffice/mdlsource/10-cases.mdl" +# A commented-out page and a dropped page are not built. +printf -- '-- CREATE PAGE Cases.Old_Page\nDROP PAGE IF EXISTS Cases.Case_Overview;\n' > "$P/apps/Backoffice/mdlsource/50-drop.mdl" +page_script Cases Case_Overview demo-overview.mdl > "$P/apps/Backoffice/mdlsource/98-cases-again.mdl" +# Test scripts are not build scripts. +page_script Testing Ignored demo-list.mdl > "$P/apps/Portal/mdlsource/x.test.mdl" + +row() { MXTK_ROWS_UPTO=5 "$OBCHECK" "$1" 2>&1 | grep -E "^Obligation $2 " ; } + +echo "== T1: no briefs, page scripts in apps// — look is owed by the built modules ==" +l="$(row "$P" look | head -1)" +case "$l" in *PENDING*"0 of 3 discharged"*) ok "look PENDING, 0 of 3 modules: $l" ;; *) bad "expected look PENDING 0 of 3, got: $l" ;; esac +case "$l" in *Cases*Dashboard*Requests*) ok "names every built module" ;; *) bad "modules not named: $l" ;; esac +case "$l" in *Testing*) bad "a *.test.mdl page was counted" ;; *) ok "*.test.mdl not counted" ;; esac +d="$(row "$P" look | grep 'OWED BY WHAT WAS BUILT')" +case "$d" in *"4 page(s) built in 3 module(s) (Cases 1, Dashboard 2, Requests 1)"*"0 of 3 module(s) discharged"*"*.mdl"*) ok "denominator line: $d" ;; + *) bad "denominator line wrong: $d" ;; esac + +echo "== T2: the same floor reaches sweep, journeys, fidelity and must-haves ==" +for ob in sweep journeys fidelity must-haves; do + l="$(row "$P" "$ob" | head -1)" + case "$l" in *PENDING*"of 3 discharged"*) ok "$ob owed by built modules" ;; *) bad "$ob: $l" ;; esac +done +case "$(MXTK_ROWS_UPTO=5 "$OBCHECK" "$P" 2>&1)" in *"nothing owed"*) bad "a module row still says nothing owed" ;; *) ok "no module row reads PASS by absence" ;; esac + +echo "== T3: the look ledger wins over scripts when present ==" +mkdir -p "$P/.claude/loop/look" +printf '1700000000\t2026-11-01T00:00:00Z\tLedger.Only_Page\tmdlsource/x.mdl\n' > "$P/.claude/loop/look/owed.tsv" +d="$(row "$P" look | grep 'OWED BY WHAT WAS BUILT')" +case "$d" in *"1 page(s) built in 1 module(s) (Ledger 1)"*owed.tsv*) ok "ledger source: $d" ;; *) bad "ledger not used: $d" ;; esac +rm -f "$P/.claude/loop/look/owed.tsv" + +echo "== T4: the model's page-scope.json is the last source ==" +M="$WORK/model"; mkdir -p "$M/.claude/loop"; register "$M"; : > "$M/App.mpr" +cp "$HERE/fixtures/verify-446/page-scope.json" "$M/.claude/loop/page-scope.json" +d="$(row "$M" look | grep 'OWED BY WHAT WAS BUILT')" +case "$d" in *"1 page(s) built in 1 module(s) (MyFirstModule 1)"*page-scope.json*) ok "page-scope source: $d" ;; *) bad "page-scope not used: $d" ;; esac + +echo "== T5: a model that has been built on, with no countable pages, is FAULT once — never 0 pages ==" +U="$WORK/uncounted"; mkdir -p "$U/app/docs"; register "$U"; : > "$U/app/App.mpr" +# exec.sh's BUILD-LOG table row shape (project-bin/exec.sh log_build), under the two-tree app/. +printf '| when (ISO-8601 local) | script | gate | result | detail |\n|---|---|---|---|---|\n| 2026-11-01T10:00:00+0100 | `10-domain.mdl` | pass | OK | applied |\n' > "$U/app/docs/BUILD-LOG.md" +out="$(MXTK_ROWS_UPTO=5 "$OBCHECK" "$U" 2>&1)" +case "$(printf '%s\n' "$out" | grep '^Obligation look ')" in *FAULT*"could not be counted"*BUILD-LOG*page-scope.sh*) ok "look FAULT with the evidence and the remedy" ;; + *) bad "expected FAULT: $(printf '%s\n' "$out" | grep '^Obligation look ')" ;; esac +n="$( . "$OBCHECK"; mxtk_obligations_report "$U" >/dev/null; echo "$MXTK_OB_N_FAULT")" +[ "$n" = 1 ] && ok "one fault for all module rows" || bad "expected 1 fault, got $n" + +echo "== T6: a .mpr and NO build evidence (fresh scaffold, Stage P) keeps master's PASS line ==" +# Review of #787: a .mpr alone made every Stage P project FAULT on six rows, and bin/status.sh's +# "modules opened: 0" (it greps "no module has been opened") turned into "≥1". +E="$WORK/scaffold"; mkdir -p "$E"; register "$E"; : > "$E/App.mpr" +for ob in look sweep journeys fidelity dispatch must-haves; do + l="$(row "$E" "$ob" | head -1)" + case "$l" in *"PASS — no module has been opened for work yet; nothing owed"*) ok "$ob: master's PASS line" ;; *) bad "$ob: $l" ;; esac +done +n="$( . "$OBCHECK"; mxtk_obligations_report "$E" >/dev/null; echo "$MXTK_OB_N_FAULT")" +[ "$n" = 0 ] && ok "no fault on a fresh scaffold" || bad "expected 0 faults, got $n" +N="$WORK/nothing"; mkdir -p "$N"; register "$N" +case "$(row "$N" look | head -1)" in *"PASS — no module has been opened for work yet; nothing owed"*) ok "no model at all: same PASS" ;; *) bad "no model: $(row "$N" look)" ;; esac + +echo "== T6b: existing-app-change never takes scope from page-scope.json (it lists the whole model) ==" +X="$WORK/eac"; mkdir -p "$X/.claude/loop"; printf 'Entry mode: change an existing app\n' > "$X/PROJECT.md"; : > "$X/App.mpr" +cp "$HERE/fixtures/verify-446/page-scope.json" "$X/.claude/loop/page-scope.json" +case "$(row "$X" look)" in *"PASS — no module has been opened for work yet; nothing owed"*) ok "legacy modules owe nothing" ;; *) bad "eac: $(row "$X" look)" ;; esac +mkdir -p "$X/mdlsource"; page_script Orders Order_Edit demo-list.mdl > "$X/mdlsource/10-orders.mdl" +case "$(row "$X" look | grep 'OWED BY')" in *"1 page(s) built in 1 module(s) (Orders 1)"*) ok "a page this change wrote is owed" ;; *) bad "eac script: $(row "$X" look)" ;; esac + +echo "== T7: a project WITH briefs keeps today's verdicts (no floor, no extra modules) ==" +B="$WORK/briefed"; mkdir -p "$B/architecture/modules/Orders" "$B/mdlsource"; register "$B" +page_script Other Unbriefed_Page demo-list.mdl > "$B/mdlsource/10.mdl" +l="$(row "$B" look | head -1)" +case "$l" in *PENDING*"0 of 1 discharged"*Orders*) ok "briefed scope unchanged: $l" ;; *) bad "briefed scope changed: $l" ;; esac +case "$(row "$B" look)" in *"OWED BY WHAT WAS BUILT"*|*Other*) bad "floor applied to a briefed project" ;; *) ok "no floor line, unbriefed module not added" ;; esac +mkdir -p "$B/.claude/loop/sweep/Orders" +printf 'Orders · 4 of 4 interactive elements swept across 2 of 2 pages\n' > "$B/.claude/loop/sweep/Orders/sweep.md" +mkdir -p "$B/docs/progress/must-haves" +printf 'Orders · 13 of 13 rows ticked or NOT DONE with a reason · pages 2 of 2\n' > "$B/docs/progress/must-haves/Orders.md" +case "$(row "$B" sweep | head -1)" in *PASS*"1 of 1"*) ok "a real sweep still discharges" ;; *) bad "sweep: $(row "$B" sweep)" ;; esac +case "$(row "$B" must-haves | head -1)" in *PASS*"1 of 1"*) ok "a ticked must-have list discharges" ;; *) bad "must-haves: $(row "$B" must-haves)" ;; esac +printf 'Orders · all rows ticked\n' > "$B/docs/progress/must-haves/Orders.md" +case "$(row "$B" must-haves | head -1)" in *FAULT*"NO DENOMINATOR"*) ok "a must-have list with no denominator is FAULT" ;; *) bad "must-haves no-denom: $(row "$B" must-haves)" ;; esac + +echo "== T8: gate-check Stage 5 on the multi-app copy shows the floor ==" +out="$("$GATE" --no-html "$P" 5 2>&1)" +case "$out" in *"Obligation look"*PENDING*) ok "gate-check prints look PENDING" ;; *) bad "gate-check: $(printf '%s\n' "$out" | grep -m1 'Obligation look')" ;; esac + +echo "== T9: entry-mode column — a mode a row does not list reads N/A, never PASS; unknown mode owes ==" +Q="$WORK/mode"; mkdir -p "$Q/architecture/modules/Orders" +awk -F'\t' 'BEGIN{OFS="\t"} !/^#/ && NF==10 && $1=="look"{$10="migration"} {print}' "$(dirname "$OBCHECK")/obligations.tsv" > "$WORK/ob-mode.tsv" +mrow() { OBLIGATIONS_TSV="$WORK/ob-mode.tsv" MXTK_ROWS_UPTO=5 "$OBCHECK" "$Q" 2>/dev/null | grep '^Obligation look ' | head -1; } +printf 'Entry mode: greenfield\n' > "$Q/PROJECT.md" +case "$(mrow)" in *"N/A — not owed (entry mode greenfield"*) ok "greenfield not owed a migration-only row" ;; *) bad "greenfield: $(mrow)" ;; esac +printf 'Entry mode: migration\n' > "$Q/PROJECT.md" +case "$(mrow)" in *PENDING*) ok "migration still owes it" ;; *) bad "migration: $(mrow)" ;; esac +printf 'Toolkit commit: none\n' > "$Q/PROJECT.md" +case "$(mrow)" in *PENDING*) ok "no Entry mode line owes it" ;; *) bad "no mode: $(mrow)" ;; esac +printf 'Entry mode: greenfield\n' > "$Q/PROJECT.md" +case "$(MXTK_ROWS_UPTO=5 "$OBCHECK" "$Q" 2>/dev/null | grep '^Obligation look ')" in *PENDING*) ok "shipped table: greenfield owes look" ;; *) bad "shipped table changed a verdict" ;; esac +# requirements-driven is translated to the table's `requirements` token by the SAME reader +# artifact-check.sh uses (_art_entry_mode), not by a second copy of the mapping. +printf 'Entry mode: requirements-driven\n' > "$Q/PROJECT.md" +case "$(mrow)" in *"N/A — not owed (entry mode requirements"*) ok "requirements-driven, row omits requirements: not owed" ;; *) bad "rd omit: $(mrow)" ;; esac +awk -F'\t' 'BEGIN{OFS="\t"} !/^#/ && NF==10 && $1=="look"{$10="migration,requirements"} {print}' "$(dirname "$OBCHECK")/obligations.tsv" > "$WORK/ob-mode.tsv" +case "$(mrow)" in *PENDING*) ok "requirements-driven, row lists requirements: owed" ;; *) bad "rd list: $(mrow)" ;; esac + +echo "pass=$PASS fail=$FAIL" +[ "$FAIL" -eq 0 ]