Skip to content

new(multi-app): apps/{App}/{App}.mpr as a supported layout — per-app resolver, gate-check, status, look-ledger, scaffold - #789

Open
MendixMau wants to merge 14 commits into
masterfrom
claude/multi-app-scope
Open

MendixMau wants to merge 14 commits into
masterfrom
claude/multi-app-scope

Conversation

@MendixMau

@MendixMau MendixMau commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

HELD by the maintainer for a field trial in a live multi-app build; do not merge before the trial result.

Status

  • Re-review of 6089d20: MERGE-AFTER-FIX. The multi-app fixture passed 69/0 on the unchanged captured tree, and the neighbouring fixtures are green. The fix it asked for, a fixture case pinning the one-app outer-register behaviour, is in d70a02e (see "Resolving the root" below). The PR stays HELD for the field trial.
  • Review fixes: the first review's HOLD findings and the maintainer's nesting decision are addressed in 40f8125 and 6089d20.
    • An app folder with its own .claude/ and PROJECT.md now resolves to the outer project.
    • mxtk_apps lists one line per app folder.
    • An env MXTK_APP that does not apply is dropped; an explicit --app still errors.
    • The app list is computed once and the LOOK ledger read once; status.sh on six apps went from 1.41 s to 1.03 s.
    • status.sh with no argument finds the project from the current folder.
  • Master merged in as c3d8eec, after fix(obligations): quality floor — per-module passes owed by what was built; one must-have list for every build type #787. Only CHANGELOG.md conflicted, and both sides were kept.
  • Field check of 6089d20 on the six-app copy:
    • from inside an app folder, the root is the outer project;
    • status.sh with no argument, run from an app subfolder, shows all six apps.
  • Scaffold split: not started, by the owner's decision. The trial will show whether it is needed.

Direct lane

What changed and why (one paragraph):
A repo holding several Mendix apps (apps/<App>/<App>.mpr, one mdlsource/ per app) was only partly supported:

  • find_mpr found the models but refused to pick one, so the Marketplace check printed "more than one .mpr; set MPR_FILE to choose, nothing checked";
  • status had no per-app view;
  • the LOOK ledger merged apps;
  • nothing created per-app planning files.

In one field run the project had to hand-write an MPR_FILE workaround into CLAUDE.local.md. In another, the lead dropped per-app intake and triage for one free-form brief, and that brief carried the spec violation that blocked the first grading.

This PR adds a small resolver interface in project-bin/_common.sh, and the shared readers report one line per app when no app is chosen. It never silently picks an app and never reports "nothing checked".

Resolver interface (for T1 claude/quality-floor and T3 claude/ready-command)

Call Result
mxtk_apps [root] one line per app folder, <App>\t<apps/App/X.mpr> (path relative to root); the model is <App>.mpr when the folder holds several, and - when it holds several and none is named for it; prints nothing and returns 1 on single-tree and two-tree projects
mxtk_app_count [root] the number of app folders (0 for any other layout)
mxtk_select_app <App> [root] exports MPR_FILE (absolute) and MXTK_APP; tries the exact name first, then any letter case; returns 1 with the reason when the name is unknown, matches two folders by letter case only, or names a folder whose model is -
mxtk_app_of <path> [root] the <App> when the path is under apps/<App>/
MXTK_APP=<App> the environment form of --app, read when _common.sh is sourced; an MPR_FILE the user set still wins; ignored when the project is not multi-app

Rule for readers: with mxtk_app_count ≥ 2 and no app selected, report one line per app. find_mpr itself still refuses, because it answers "which model do I write".

Readers

  • Resolving the root (refinement of _common.sh: installed and toolkit copies resolve different roots when cwd is inside app/ or apps/<X>/ #489):

  • gate-check: new --app <App> (or MXTK_APP). With no app chosen, it prints Marketplace installs: per app (N apps), then:

    • one [App] line for each app with its own architecture/apps/<App>/fit-gap.md; such an app can FAIL;
    • for apps on the shared fit-gap, one line per distinct finding, naming its apps; a finding that holds for every app prints once, as [all N apps, from the shared architecture/fit-gap.md];
    • a package missing according to the shared fit-gap reads PENDING, because that file does not say which app owes the Buy;
    • build-ready counts a FAIL.

    A full run also prints an Apps: section with each app's model, its mdlsource/ scripts and its LOOK debt. With no ledger, the LOOK part reads LOOK: no ledger here (N page(s) in its scripts), never "no pages owed".

  • status.sh: one APP line per app, in both the full screen and --brief, using the same helper as gate-check (bin/lib/app-scope.sh). With no argument, it finds the project from the current folder.

  • look-ledger: one ledger keyed by app, not one per app folder, because:

    • the Read hook that records "seen" screenshots runs at the project root, and an image does not belong to one app;
    • every app folder resolves to the project root;
    • a ledger per app folder would split seen.tsv.

    Owed rows get a 5th column, the app, and only in a multi-app tree. status --app <App> keeps two apps' pages of the same name apart; status --by-app lists every app's rows in one call.

  • One register:

    • The root PROJECT.md is the register; gate-check never reads an app's.
    • The field repo held seven PROJECT.md files: one per app from mxcli init, plus the root.
    • An app PROJECT.md that holds register lines gets a warn-only ⚠ [App] line in gate-check, a status WATCH item and a sync note.
    • A plain template file stays silent, and app files are never edited.
  • init / sync:

    • They create architecture/apps/<App>/intake.md and triage.md, plus the index architecture/apps/README.md.
    • The index says the build plan is one shared architecture/build-plan.md with a ## App: <App> section per app.
    • The Wiring rows name MXTK_APP / --app. On an existing project, sync prints the replacement rows and does not rewrite them.
  • Convention — please confirm:

    • Planning files live under architecture/apps/<App>/, not apps/<App>/, because apps/<App>/ is the Mendix project folder that Studio Pro commits and mxbuild packages.
    • Module briefs stay in architecture/modules/<Module>/ with an **App:** <App> line, because seven readers look there.
    • Documented in skills/module-folder-convention.md § Several apps in one repo.

Impact

Row Answer
Process No new blocking gate. gate-check takes --app. A multi-app build-ready can now FAIL when a Buy in an app's own fit-gap is not installed; before this it was PENDING "nothing checked". The new planning files appear only in multi-app projects. The app-register warning is warn-only.
Dependencies Shared files: project-bin/_common.sh (new functions, the root-walk refinement, one block that runs when it is sourced), bin/gate-check.sh, bin/lib/marketplace-check.sh, bin/status.sh, project-bin/look-ledger.sh (--app, --by-app), bin/init-project.sh, bin/sync-project.sh, bin/doctor.sh (two hint strings). New: bin/lib/app-scope.sh. Not touched: project-bin/exec.sh (T2), the obligation verdict logic (T1), bin/ready.sh (T3).
Context cost Always-loaded words: 64,984 → 65,155 (budget 80,000), from render-routing.sh --check. All 171 words are in module-folder-convention.md (stages 4 and 5, architect and mdl roles).
Behaviour NOT RUN: no A/B test of the new skill section; it states paths, not a rule that shapes output.
Runtime Single-tree and two-tree: one [ -d apps ] test, 0 s. Multi-app, six apps: status.sh 1.03 s total; the per-app lines take 33 ms and the register notes 16 ms. Time cost: per gate/status run · ~0.05 s on Linux x86-64 container (6 apps) · can force rework: y (a per-app Buy FAIL) · offset: replaces a check that never ran

Byte-for-byte (single-tree, two-tree): master and this branch were run side by side on freshly scaffolded projects, at 6089d20 and again after the merge.

  • Identical, apart from the project name and toolkit sha: the init-project output, CLAUDE.local.md, the scaffolded file tree, status.sh and look-ledger status.

  • Also identical: gate-check --no-html, except for a "toolkit updated" note. That note comes from comparing two separate checkouts against the project's recorded commit.

  • No client data anywhere in the diff (apps anonymised AppA..AppF; script names generated)

  • Size cap: over 400 lines. One PR, per the owner; the scaffold split waits for the trial.

  • Test tier: scenario checks run by hand on the materialised six-app capture, with a stub mxcli replaying captured SHOW MODULES output. The parent session ran a field check on the six-app copy.

  • tests/wave2/test-multi-app-scope.sh: the reviewer ran it at 6089d20, 69/0 on the unchanged captured tree. The one-app case added in d70a02e was checked by hand and still needs one fixture run.

  • Golden input: fixtures/multi-app/tree.txt is the git ls-files shape of the six-app field repo, anonymised (see PROVENANCE.txt); SHOW MODULES output comes from existing captures.

  • Both layouts considered, plus the third. Bash 3.2: globs and builtins only. Git Bash: not run here.

  • CHANGELOG.md lines appended

Do not merge before an independent review (CLAUDE.md "Merging a PR").

🤖 Generated with Claude Code

https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh

…pp, MXTK_APP

First commit of the multi-app scope work, pushed early so the parallel quality-floor and
ready-command branches can read the interface. Readers follow in later commits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
…-app scaffold in init/sync

A repo holding several apps (apps/<App>/<App>.mpr, one mdlsource/ per app) is now reported per
app instead of "more than one .mpr; set MPR_FILE to choose, nothing checked".

- gate-check: --app <App> / MXTK_APP scopes a run; with none, Marketplace installs prints one
  [App] line each (per-app fit-gap may FAIL; a shared fit-gap reads PENDING) and an Apps:
  section with each app's model, scripts and LOOK debt. build-ready counts a FAIL.
- status.sh: one APP line per app (bin/lib/app-scope.sh, shared with gate-check).
- look-ledger: one ledger keyed by app (5th owed column only in a multi-app tree);
  status --app <App>.
- init/sync: architecture/apps/<App>/{intake,triage}.md + architecture/apps/README.md, Wiring
  rows naming the app selection. Module briefs stay in architecture/modules/ (every reader
  looks there).
- skills/module-folder-convention.md § Several apps in one repo (baseline 64,984 -> 65,125).

Single-tree and two-tree: gate-check, status, init output, CLAUDE.local.md, owed.tsv and the
scaffolded tree are byte-identical to master (compared side by side on scratch projects).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
… finding prints once

From the parent session's field run of #789 on a copy of a six-app repo:
- status/gate-check said 'LOOK: no pages owed' per app on a checkout with ~78 built pages,
  because the LOOK ledger is git-ignored. Now: 'LOOK: no ledger here (N page(s) in its
  scripts)', 'no ledger row for this app', or 'no page in its scripts'.
- the Marketplace check repeated one project-level fit-gap finding six times. Apps on the
  shared fit-gap are grouped by identical finding: '[all 6 apps, from the shared ...]'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
@MendixMau MendixMau changed the title new(multi-app): apps/<App>/<App>.mpr is a supported layout — per-app resolver, gate-check, status, look-ledger, scaffold new(multi-app): apps/&lt;App&gt;/&lt;App&gt;.mpr as a supported layout — per-app resolver, gate-check, status, look-ledger, scaffold Nov 17, 2026
…e from a field capture

- bin/lib/app-scope.sh mxtk_app_register_notes: an apps/<App>/PROJECT.md (mxcli init per app)
  holding register lines (Entry mode, Current stage, Adopted at stage, CONFIRMED/ASSUMED rows)
  gets a warn-only line in gate-check's Apps section, status WATCH and a sync note. The root
  PROJECT.md stays the register gate-check reads. A plain template file is silent.
- tests/wave2/fixtures/multi-app/tree.txt: the structural shape of a field repo (git ls-files,
  six apps, anonymised AppA..AppF; script counts 69/34/28/26/27/27; each app carries its own
  PROJECT.md and CLAUDE.md). Fixture adapted to six apps; new case A8.
- skills/module-folder-convention.md: one sentence on app-level PROJECT.md (baseline 65,155).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
@MendixMau MendixMau changed the title new(multi-app): apps/&lt;App&gt;/&lt;App&gt;.mpr as a supported layout — per-app resolver, gate-check, status, look-ledger, scaffold new(multi-app): apps/{App}/{App}.mpr as a supported layout — per-app resolver, gate-check, status, look-ledger, scaffold Nov 17, 2026
…ter project; review fixes

From the independent review of #789 (HOLD) and the maintainer's decision:
- project-bin/_common.sh: refinement of #489. An apps/<App>/ that is a project folder of its own
  (mxcli init: .claude/ + PROJECT.md) resolves to the OUTER project when that holds a register
  (## Current stage / ## Decisions / Entry mode), no root or app/ model, and the app folder holds
  a model. One register, one LOOK ledger, one set of gates. Any other nested project keeps its
  own root. No subshell on the walk's common path.
- mxtk_apps: one line per app folder (<App>.mpr preferred, '-' when ambiguous); select refuses
  an ambiguous folder; a case-only clash gets its own message.
- gate-check: an env MXTK_APP that does not apply is dropped; only --app errors.
- app-scope.sh: app list computed once (mxtk_scope_init / MXTK_SCOPE_*), one find + one awk +
  one look-ledger call (new 'status --by-app'), register notes in one awk; np local; no global
  helper defined inside a function. Status on six apps 1.41 s -> 1.03 s.
- marketplace-check: '-' apps reported, no 'from the shared' label without a shared fit-gap.
- fixture: outer-project walk, no ledger split, per-folder dedupe, env MXTK_APP on single tree,
  no-fit-gap label.

Single-tree and two-tree gate-check, status and look-ledger status: byte-identical to master.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
…; status.sh infers the project

Field run of 40f8125 on the six-app copy: the root PROJECT.md is hand-written ('- Mode:
requirements-driven'), so the register-lines test never fired and app folders kept their own
roots. The outer folder now qualifies with any PROJECT.md beside two or more app folders holding
a model (no root or app/ model); the register test stays as the one-app alternative. Nested
projects elsewhere keep #489. status.sh with no project argument now finds the project from the
current folder (mxtk_walk_root) instead of printing usage. Fixture: hand-written outer register
from an app cwd; status.sh with no argument from apps/AppB/docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
…ge from #489)

A single apps/X/ with its own .claude/ + PROJECT.md under an outer folder whose PROJECT.md holds
a register (## Current stage) resolves to the outer folder; master keeps apps/X. Kept on purpose
(one register), pinned per the #789 re-review.

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

Copy link
Copy Markdown
Owner Author

Review: MERGE-AFTER-FIX. This PR conflicts with master in project-bin/look-ledger.sh (from #788), not only in CHANGELOG. If that conflict is resolved by taking this PR's status) case, status --shots breaks, and bin/ready.sh:209 loses its screenshot evidence.

Value: Fixes the field gap as reported. Without an app chosen, gate-check now reports per app (bin/gate-check.sh:3756-3762, bin/lib/marketplace-check.sh:233-288) instead of "nothing checked". Status, look-ledger and the scaffold now cover the third layout.

This is DISCUSS-worthy. It adds a layout, overrides the #489 root rule for app folders (project-bin/_common.sh:71-88,94), and adds a new build-ready FAIL path through a per-app fit-gap. Entry modes are unchanged. It is not overbuilt, and the maintainer's field-trial hold stands.

Regression risk:

  • Both layouts, probed: single-tree and two-tree, at base and at head, each with a decoy apps/Other/Other.mpr. The init output, tree, CLAUDE.local.md, status (and --brief) and gate-check --no-html are identical after normalising paths. sync-project differs only by the expected refreshes.
  • Existing multi-app projects: after sync, a session inside apps/<X>/ resolves to the outer root. Any apps/<X>/.claude/loop/ state already written there (owed LOOK rows, exec logs, marketplace-ok) stops being read, and nothing warns about it.
  • status.sh with no argument now infers the project instead of exiting 1. I found no caller that relies on the old exit.
  • Bash 3.2: safe. Git Bash was not run.

Correctness:

  • Fixtures, run in a detached worktree:
Fixture Result
test-multi-app-scope 70/0
test-common-root-multiapp 67/0
test-look-ledger 35/0
test-marketplace-install 57/0
test-status-session-cwd 10/0
test-status-bare-var 3/0
test-status-existing-app 27/27
  • Golden input: captured and anonymised.
  • bin/lib/app-scope.sh:44-56 is a second page parser alongside look_pages_in, so the two can drift apart.
  • The comment at look-ledger.sh:9,241 says "6th column", but --by-app prints the app in column 4.
  • Rule 5 (a producer for every consumer): nothing produces architecture/apps/<App>/fit-gap.md. skills/architecture-blueprint.md:294 is unchanged, so multi-app Marketplace checks stay PENDING.

Context cost: 65,032 → 65,203 (+171 baseline, in module-folder-convention.md). On top of master that is about 65,319 of 80,000. The PR body's figures are stale. This is baseline text, so RELEASE-PROCESS.md §4a item 4 requires a Behaviour A/B; it is NOT RUN.

Time cost: about 0 ms per build row. Sourcing _common.sh takes 19.8 ms on base against 20.5 ms on head, and 19.3 ms against 19.3 ms on a rerun. gate-check takes 1013 ms against 1016 ms.

Exact fixes required:

  1. Merge master, keeping new(ready, ci): READY only via bin/ready.sh, evidence in git, and a CI gate an agent cannot skip #788's --shots, summary and usage text next to --app/--by-app. Re-run test-look-ledger.sh and test-ready.sh.
  2. Warn when apps/<X>/.claude/loop/look/owed.tsv exists, since those rows are no longer read, and add a fixture case.
  3. Run the §4a Behaviour A/B, or move the new section to an on-demand file.
  4. In architecture-blueprint.md Step 4, add: a multi-app project writes architecture/apps/<App>/fit-gap.md.
  5. Fix the "6th column" comment.

Generated by Claude Code

# Conflicts:
#	CHANGELOG.md
#	project-bin/look-ledger.sh
@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>
…v2026.11.17 release merge

The release (#794) turned ## Unreleased into ## v2026.11.17; the merge left #789's unreleased
lines inside the released section. #789 is held and not in that release.

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

Copy link
Copy Markdown
Owner Author

Review: MERGE-AFTER-FIX (re-review at 9cbe111). Fix 1 landed through the master merges. Fixes 2–5 from the prior review have not: the commits since then are only merges and a CHANGELOG move. An orphaned apps/<X>/.claude/loop/look/owed.tsv is still ignored without a warning.

Value: Unchanged; multi-app projects are now reported per app. It merges cleanly with origin/master (#788–#794, Release v2026.11.17).

Regression risk:

Correctness: All fixtures were run in a detached worktree and all pass.

Fixture Result
multi-app-scope 70/0
common-root-multiapp 67/0
look-ledger 35/0
ready 29/0
marketplace-install 57/0
status-session-cwd 10/0
status-bare-var 3/0
status-existing-app 27/27
mode-contract 28/0
entry-mode-plan-rule 47/0

Still open: look-ledger.sh:244 still says "6th column", and architecture-blueprint.md Step 4 (:294-298) is unchanged.

Context cost: 65,568 → 65,739 always-loaded words (+171, baseline). The Behaviour A/B is still NOT RUN.

Time cost: ≈0 ms per row. On 9cbe111, authoring-audit passed and checks was still in progress.

Exact fixes required:

  1. Merge master, keeping --shots/summary — done.
  2. Warn about an orphaned apps/<X>/.claude/loop/ state, in gate-check's Apps section or as a sync note, plus a test-multi-app-scope.sh case.
  3. Run the §4a Behaviour A/B, or move the section to an on-demand file and leave a one-line pointer.
  4. In architecture-blueprint.md Step 4, add that a multi-app project writes architecture/apps/<App>/fit-gap.md.
  5. Fix the column comment at look-ledger.sh:244.
  6. checks must be green.

Generated by Claude Code

…each READY

ready.sh marked every app NOT MEASURED ('the look ledger is not kept per app yet'), so a four-app
build could never be READY. A whole-project run now prints one app:<App> row per app from
look-ledger.sh status --by-app (K of N seen, unseen pages named) and needs every app's row;
--app <App> scopes the gate-check stage 5 and ledger steps to that app via MXTK_APP. Single-tree
output is byte-identical to 8aa2ac6. Fixture: test-ready.sh R11 (two apps).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
…after the cd

_XD="${0%/*}" stayed relative (../../bin); after exec.sh's cd to the project root the guard
[ -f "$_XD/_position.sh" ] failed in silence, so 'cd apps/Orders && ../../bin/exec.sh
../../mdlsource/x.mdl' wrote under Interview mode: auto while the same call by absolute path
was refused. A relative MDL script path broke every [ -f "$SCRIPT" ] guard the same way. Both
are made absolute before the cd, only when the caller is not at the project root, so a run from
the root is unchanged. Fixture: test-mode-contract.sh X.

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

Tier 2 of the root resolver returned the app folder for a copy installed inside it, so
apps/<App>/bin/exec.sh read the app's own PROJECT.md and the outer register's plan rule never
fired under auto. It now applies _mxtk_outer_project, the same rule as the root walk; an install
in a nested project elsewhere keeps its own root (#489 R17g, checked). Fixture:
test-mode-contract.sh X (in-app copy refused).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSmcGH9hcq6GdHyLxdh
MendixMau added a commit that referenced this pull request Nov 17, 2026
… rule (#795)

`_XD="${0%/*}"` stayed relative (e.g. `../../bin`), and exec.sh then ran `cd "$PROJECT_ROOT"`. After the cd, the plan-rule guard `[ -f "$_XD/_position.sh" ]` failed silently, so under Interview mode auto a write before build-ready was not refused when exec.sh was called by a relative path from an app folder. `_XD` and a relative MDL script path are now made absolute before the cd, which also fixes the later `[ -f "$SCRIPT" ]` guards. A run from the project root is unchanged. The fixture is test-mode-contract case X. It was found by the independent review of #789.

Review: MERGE — the fix is correct and complete; case X step 1 fails on unfixed master and passes here; the root path is unchanged (CI green on a2692c6)

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