Skip to content

fix(obligations): quality floor — per-module passes owed by what was built; one must-have list for every build type - #787

Merged
MendixMau merged 6 commits into
masterfrom
claude/quality-floor
Nov 17, 2026
Merged

MendixMau merged 6 commits into
masterfrom
claude/quality-floor

Conversation

@MendixMau

@MendixMau MendixMau commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Review fixes pushed: 911099d (review of 9de09b5, MERGE-AFTER-FIX).

  • Regression fixed. A fresh scaffold with a .mpr no longer reads FAULT. The "pages could not be counted" FAULT now needs build evidence: exec rows in docs/BUILD-LOG.md, *.mdl scripts on disk, or a derived Current stage of 5 or later. A .mpr with no build evidence keeps master's exact line, PASS — no module has been opened for work yet; nothing owed, so bin/status.sh reads modules opened: 0 (checked on a real init-project.sh scaffold). The register's stage line is not the switch, because the field run had none.
  • existing-app-change never takes scope from page-scope.json (it lists the whole model); only the look ledger and *.mdl page statements count, which name pages this change wrote. That mode never takes the FAULT either: "none found" is a measured zero for the change.
  • The mode N/A check now runs after the MXTK_ROWS_UPTO stage limit.
  • Fixture:
    • T5 now carries a BUILD-LOG exec row and gives one FAULT.
    • T6: Stage P + an empty .mpr gives master's PASS on all six module rows and 0 faults; no model at all gives the same.
    • T6b: existing-app-change + .mpr + page-scope.json, no briefs or scripts, gives nothing owed; adding one page script gives that page owed.
  • Sync claim corrected (§3 and in sync-project.sh's comment). Sync does not run gate-check. The stage is the last line gate-check stamped, so a stale or missing stamp gives bound, and the hand edit to advisory covers it.
  • Earlier, b750ff3: the entry mode is read through artifact-check.sh's _art_entry_mode, not a second copy of its mapping.

What changed

1. No per-module obligation reads PASS by absence (bin/lib/obligation-check.sh).
_ob_modules() keys scope to module briefs and verify runs, which only exist if a project ran the planning stages. A project that skipped them got PASS — nothing owed on look, fidelity, sweep and journeys. Now, only when the planned scope is empty, the scope falls back to the modules that hold built pages. The first source that yields pages wins:

  1. the look ledger .claude/loop/look/owed.tsv (col 3)
  2. page statements in the project's *.mdl scripts. This uses the same CREATE/ALTER/DROP shapes as look_pages_in(), skips *.test.mdl, and prunes deployment/, .git, node_modules and similar
  3. the model, via .claude/loop/page-scope.json inScope (never for existing-app-change)

Each source is looked for at <root>, app/ and apps/*/. No mxcli call is made. Every module row then reads PENDING, plus a denominator line:
OWED BY WHAT WAS BUILT: N page(s) built in M module(s) (A 2, B 1), K of M module(s) discharged — … (source: …).

  • Built on, but no source can count the pages → FAULT, counted once and naming bin/page-scope.sh. "Built on" means BUILD-LOG exec rows, *.mdl scripts, or a derived stage of 5 or later. It never reads as "0 pages".
  • No build evidence (a fresh scaffold, with or without a .mpr) → master's PASS line, unchanged.

2. One must-have list for every build type (skills/must-haves.md, new, on demand, verify group).
This is poc-build.md's 12-row checklist made generic, plus row 13: every region the design shows is on the built page, counted K of K. That row targets the missing dashboard tiles, status tiles and side navigation from the field run.

  • poc-build.md now points to the list instead of keeping its own copy.
  • module-review.md stage 5 requires the mark docs/progress/must-haves/<Module>.md, whose first line is 13 of 13 rows ticked or NOT DONE with a reason. The path is tracked on purpose: .claude/loop/ is git-ignored. bin/ready.sh (T3) reads the same path.
  • New obligation row must-haves (module scope, denominator yes, from stage 5). The fallback above applies to it too.

3. Must-haves: bound | advisory, decided once per project (commit cfffffd).

  • init-project.sh writes Must-haves: bound for new projects.
  • sync-project.sh writes one Must-haves: line when PROJECT.md has none, and only then:
    • advisory — joined at stage N before the must-haves row existed, when the last Current stage line gate-check stamped reads 6 or 7, or Adopted at stage: is 6 or 7;
    • otherwise bound.
    • Sync does not run gate-check itself, so a stale or missing stamp gives bound.
  • advisory: the row reads ADVISORY — K of N discharged; NOT DONE: …, keeps the module list visible, and is not counted as pending. On a scratch project the pending count was 10 with advisory and 11 with bound.
  • bound: PENDING as normal.
  • The escape hatch is a hand edit. A project that is past Stage 5 in practice but has no such stamp (and no Adopted at stage: line) gets bound. Its owner edits the line to Must-haves: advisory — <reason>; the sync message says so.
  • Why it is keyed on the written line, not the position. A position check would also silence a new project the day it passed Stage 5 without the marks. --adopt is too broad.

4. Entry-mode column on obligations.tsv (commits 9de09b5 and b750ff3).

  • New column 10 modes, the same column and tokens as artifact-manifest.tsv column 6: migration,requirements,greenfield,existing-app-change.
  • The register's mode is read through artifact-check.sh's own _art_entry_mode. It is called, never copied.
  • A row the declared mode does not list reads N/A — not owed (entry mode …; row modes: …), never PASS.
  • No mode, an unrecognised mode, or an empty column means the row is owed.
  • Every row lists all four modes today, so no verdict changes.
  • Not handled here:

5. Fixtures

  • tests/wave2/test-obligation-quality-floor.sh covers:
    • a multi-app apps/<App>/ layout with page scripts and no briefs;
    • the ledger source and the page-scope source;
    • the FAULT when the model was built on but pages can't be counted;
    • the fresh-scaffold PASS;
    • existing-app-change scope;
    • a briefed project;
    • gate-check at Stage 5;
    • T9, the mode column.
  • tests/wave2/test-must-haves-advisory.sh covers bound and advisory as written by init and sync, the second sync being a no-op, and the pending count.

What changes for existing projects after sync-project.sh

  • One new PROJECT.md line, written once: Must-haves: advisory — … if past Stage 5 (stamped or adopted 6/7), else Must-haves: bound.
  • Every module now owes the must-have mark.
    • Bound projects at a Stage 5+ query, or on a full run, see one new PENDING row, and the roll-up rises by one. It clears by writing docs/progress/must-haves/<Module>.md, or with --waive must-haves/<Module> --reason "…".
    • Advisory projects see the row as ADVISORY, not counted.
  • Projects with briefs keep byte-identical verdicts on every other row.
  • Projects with no briefs and built pages go from PASS — nothing owed to PENDING on look, sweep, journeys, fidelity and dispatch. That is the fix.
  • Fresh or early projects with a .mpr and no build evidence: unchanged (master's PASS line; status.sh modules opened: 0).
  • existing-app-change projects with no briefs: only pages this change wrote (ledger or scripts) are owed; legacy modules owe nothing.
  • New FAULT case: no briefs, a model built on (BUILD-LOG exec rows, scripts or stage 5+), and no countable pages.
  • No change to: stage verdicts, exit codes, or the line formats other tools parse. Obligation rows stay informational.

Field evidence

Two field runs (Nov 2026, unattended, requirements-driven, prototypes and design system supplied, several apps under apps/<App>/). Planning stages were skipped, ~78 pages were built and 0 reviewed, and gate-check.sh <copy> 5 printed Obligation look PASS — no module has been opened for work yet; nothing owed (same for fidelity).

Field run (CLAUDE.md "Shipping an instrument", rule 4)

The maintainer ran bin/gate-check.sh <copy> 5 at 642d1db on a real copy of the field repo: six apps under apps/<App>/, no briefs, no build plan, tracked files only.

  • master: look, sweep, journeys, fidelity and dispatch read PASS — no module has been opened for work yet; nothing owed.
  • this branch: all five read PENDING — 0 of 6 discharged, with OWED BY WHAT WAS BUILT: 78 page(s) built in 6 module(s) (…), 0 of 6 module(s) discharged (source: page statements in *.mdl scripts).
  • The 78-page count matches an independent count.

The later commits keep that path. Pages counted from *.mdl engage the floor exactly as before, and the field copy has no Entry mode: line.

Verdicts, before → after (scratch copies, MXTK_ROWS_UPTO=5)

Case master this branch
multi-app, page scripts, no briefs PASS — nothing owed PENDING 0 of 3 + OWED BY WHAT WAS BUILT: 4 page(s) built in 3 module(s)…
must-haves (no row) PENDING (bound) / ADVISORY, not counted (advisory)
fresh scaffold + .mpr PASS — nothing owed PASS — nothing owed (unchanged)
.mpr + BUILD-LOG exec rows, no countable pages PASS FAULT ×1, remedy bin/page-scope.sh
existing-app-change + .mpr + page-scope.json, no briefs/scripts PASS PASS (unchanged)
a row whose modes omit the declared mode (no column) N/A — not owed (entry mode …)

Regression risk

  • Covered by the sync section above.
  • obligations.tsv went from 9 to 10 columns. Every in-repo reader uses NF>=9 or columns ≤ 9. A 9-column row reads as owed by every mode.
  • obligation-check.sh sources bin/lib/artifact-check.sh, which only defines functions and which gate-check.sh already sources.
  • Multi-app module-name collisions merge into one unit. Follow-up once T4's resolver lands: mxtk_apps in _ob_built_pages.
  • Cost: the scan took 20 ms over the toolkit tree (1,787 files), plus one grep over BUILD-LOG only on the no-pages path.
  • check-portability.sh is clean.

Field-proof gaps (stated honestly)

  • The fixture's golden input is not a verbatim capture. It rebuilds the field layout from the repo's page-script fixtures. The BUILD-LOG row in T5 copies exec.sh's log_build row format but is not captured output.
  • The builder did not run the fixtures. The reviewer ran them at 9de09b5 (floor 24/0, advisory 7/0). Cases changed since, all exercised by hand on scratch projects, including a real init-project.sh scaffold + status.sh: T5, T6, T6b, T9's requirements-driven cases.
  • The advisory path was not field-run.

Earlier work

No open PR covered "LOOK/fidelity passing by absence". claude/first-build-page-quality-3f6d7v shares no merge base with master. This PR is independent.

Word budget

bin/render-routing.sh --check: baseline 64,984 → 65,032 (+48, budget 80,000; later commits add no skill text). The added text is the module-review.md stage 5 paragraph, needed at module close.

Not touched (other sessions): project-bin/exec.sh, bin/status.sh, the runbook and entry-mode rules, bin/ready.sh, bin/lib/_common.sh, bin/lib/entry-mode.sh, bin/lib/artifact-check.sh. sync-project.sh and init-project.sh get one block or line each, for the Must-haves line.

Do not merge without the independent review (CLAUDE.md "Merging a PR").

🤖 Generated with Claude Code

https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8

…built, not only by what was planned; must-haves list for every build type

With no module brief and no verify run, every per-module obligation (look, fidelity,
sweep, journeys) printed "PASS — nothing owed", even on a project that had built ~78
pages and reviewed 0 (field run, requirements-driven, stages 1-4 skipped). An empty
planned scope now falls back to the modules that hold built pages (look ledger, else
*.mdl page statements, else page-scope.json; root, app/, apps/*/), with a denominator
line. A .mpr whose pages cannot be counted is one FAULT naming page-scope.sh.
Projects with briefs keep every earlier verdict.

skills/must-haves.md is the single source of poc-build.md's must-have checklist,
generalised to every build type plus a design-regions row; module-review.md stage 5
requires its mark, and obligations.tsv owes it per module.

Baseline words 64,984 -> 65,032 (budget 80,000).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8
…haves/<Module>.md

.claude/loop/ is git-ignored, so a mark there is invisible to CI, to reviewers
and to a fresh clone, which is how the field run's look ledger stayed hidden.
Line 1 is unchanged: "13 of 13 rows ticked or NOT DONE with a reason".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8
…e 5 when the row arrived

sync-project.sh writes one Must-haves: line when none exists: advisory if the
derived Current stage or Adopted at stage is 6/7, else bound; init-project.sh
writes bound. An advisory project's must-haves row reads ADVISORY and is not
counted as pending. Keyed on the written line, never on position, so a new
project cannot go quiet by passing Stage 5 without the marks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8
…rtifact-manifest.tsv

Column 10 `modes` uses the manifest's tokens and entry_mode_token. A row the
declared Entry mode does not list reads "N/A — not owed (entry mode ...)",
never PASS; no or unrecognised mode means owed. Every row lists all four modes
today, so no verdict changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8
MendixMau pushed a commit that referenced this pull request Nov 17, 2026
…wn axis

Per the vocabulary correction: artifact-manifest.tsv column 6 keeps
migration,requirements,greenfield,existing-app-change (the tokens
entry_mode_token produces, copied by obligations.tsv column 10 in #787).
No poc or all token; Build type: poc is read by gate-check.sh only. Only
the N/A wording changes ("not owed (mode ...)").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
…t_entry_mode

obligation-check carried its own copy of the requirements-driven -> requirements
translation. It now calls the one artifact-check.sh uses, so the two tables cannot
drift apart. Fixture T9 adds: Entry mode requirements-driven, a row omitting
requirements is not owed; a row listing it is owed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8
…page-scope scope for existing-app-change

Review of #787: a fresh scaffold with a .mpr read FAULT on six rows, and
status.sh's "modules opened: 0" became "≥1". The FAULT now needs build
evidence (BUILD-LOG exec rows, *.mdl scripts, or a derived stage at 5+); a .mpr
alone keeps master's PASS line. existing-app-change never takes scope from
page-scope.json, which lists the whole model. The entry-mode check now runs
after the stage limit. sync-project.sh's comment states that the stage is the
last gate-check stamp. Fixture T5/T6/T6b updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQShKoiXaG1kwz64TtJ8
@MendixMau
MendixMau merged commit afa7e16 into master Nov 17, 2026
2 checks passed
MendixMau added a commit that referenced this pull request Nov 17, 2026
…n rule, design front end (#790)

With no declared entry mode or adoption, every exec.sh run, status.sh and the gate-check summary print one warn-only banner: the toolkit treats the project as Stage P, not started. In migration and requirements-driven projects, the first MDL write with no plan evidence is refused once per clone, before any lock, snapshot or write. It clears with an adoption at stage 5 or later, a reasoned stage-4 waiver (including the aggregate `Waived stages: … 4 — reason`), a Stage 5+ readout, or a build plan plus a brief. Never refused: a-la-carte (new), poc, existing-app, --patch and undeclared projects. Documentation adds the greenfield design front end (poc-build steps 1–4) and mapping a supplied prototype as the wireframe (design-artifacts Step 2a; the ui-preflight STOP accepts it). project-bin/_position.sh is the shared, process-free tokeniser.

Field evidence: two unattended requirements-driven field runs built about 78 pages with no plan while every guard stayed silent.

Review: MERGE — refuse-once plan rule and banner verified (46/46, bug06 64/0, 0 process starts added); composes with #787 and #788 (65,373 words); CI red once on unrelated flaky test-app-restart.sh (mktemp suffix vs "zqx"), green on re-run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MendixMau added a commit that referenced this pull request Nov 17, 2026
…ion check (#793)

The composition check of #787/#788/#790/#791/#792 found three ways an unattended agent could still get past the plan gate. This closes them:
- Auto detection uses one first-word rule (mxtk_auto_word in project-bin/_position.sh) shared by exec.sh, gate-check.sh's --adopt check and ready.sh. `Interview mode: auto (…)` and `unattended — …` now count as auto, and the strictest of env, state file and register wins.
- ready.sh reports NOT READY while any `consentBy: auto-mode` adoption row is unconfirmed, so an agent cannot approve its own plan skip and reach READY.
- Under auto, an undeclared Entry mode is refused before build-ready. Attended behaviour is unchanged.
- The checkpoint skills no longer describe greenfield as a live mode.

Review: MERGE — no findings (the H/K/W/U order fix restores test-mode-contract to 28/0; the strictest-wins change is now in the CHANGELOG; CI green on d3c4ced)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MendixMau MendixMau mentioned this pull request Nov 17, 2026
MendixMau added a commit that referenced this pull request Nov 17, 2026
This is the output of bin/cut-release.sh. The 24 entries under `## Unreleased` become `## v2026.11.17`. Included: #787, #788, #790, #791, #792 and #793. #789 is held.

Review: MERGE — no findings (CHANGELOG heading only; the release section has no client names; CI green on 072e417)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants