diff --git a/CHANGELOG.md b/CHANGELOG.md index c25acdb..51ab053 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- docs(pipeline-walks): **`docs/pipeline-walks.html` — a process diagram per entry mode, with the scripts run at every step.** Shared spine, migration, requirements-driven (incl. the docs-ready fast path), greenfield, change-an-existing-app (opening with the app-mapping step: `SHOW STRUCTURE`, `graph-report`, `lint`, `report`, security matrix, `marketplace diff`), à-la-carte tracks A/A2/B, and the Stage 5 BUILD→GATE→PROVE→LOOK→CONFIRM loop, each as a mermaid flowchart plus a stage/what/scripts table. Linked from the README entry-modes paragraph — Maurits Visser - fix(bin/doctor.sh): **doctor told every Podman user "docker is not installed"** — the section advertised Podman in its advice text ("Rancher Desktop or Podman … are common substitutes") while all four probes ran `docker` only: `docker info`, the `command -v docker` gate, the not-installed warning, and a start hint that said `open -a Docker`. So a machine fully able to run the container lane on Podman, but without the docker shim, was reported broken — and on a team that cannot licence Docker Desktop that reads as "go install software you are not allowed to have" (a colleague's machine-ready status carried "Docker not installed" as a known issue; they may have had Podman all along). Detection is now docker-then-podman (`MXTK_CONTAINER_RUNTIME` forces one), the runtime is **named** in the report (`podman responding — …`), the start hint knows `podman machine start` / `podman.socket`, and the not-installed warning names Podman as the licence-free option instead of implying Docker Desktop is required. Same bounded background/poll/kill probe for both, same 0/1/2 exit contract; `mxcli docker check` invocation deliberately untouched (different repo). **Not field-run** — no container runtime in the authoring container; needs one run on a Mac with Podman and no `docker` on PATH. Driver: the Mendix migration team's Docker Desktop licensing constraint — Maurits Visser - learn(skills/doctor-triage.md): **"doctor.sh says red — what now?" is now on disk instead of in a Slack thread.** Three failures that render identically get separated: my environment is wrong / the toolkit's own self-check is wrong / this line does not apply in my lane. Check the machine before naming a fix — a wrong-arch binary, a missing one and a broken self-check all read the same, which is how *"install Studio Pro 10.24.18"* became the first confident answer to a Linux-ELF mxbuild on a Mac, and how a false `fail (unreadable error file)` (the self-test bug fixed in `c0ea53c`) sent people to audit their own machines. Also: the three toolchain lanes (bundled `mx` — macOS ships one only from Mendix 11 — the Linux-only CDN toolchain, and the container lane, runtime-agnostic although doctor still probes only `docker`), a derivation for which FAILs block rather than a list that rots, the N+M-lines-dispositioned bound, and the VM/arch caveat. From the macOS onboarding thread of 2026-09-22 — Yvann, and the four people in it - fix(bin/doctor.sh): **the gate self-test renamed the model in its scratch dir to `model.mpr` while copying `mprcontents/` verbatim beside it, so mxbuild bailed before writing any error file and the self-test reported `fail (unreadable error file)` — the F-042-class string that means "the gate itself is broken" — on a perfectly healthy gate.** `mprcontents/` carries an internal record of the model's real basename; the rename breaks the pair. The scratch copy now keeps the real basename (`$scratch/$(basename "$MPR")`), threaded through all four later references (baseline count, injection `exec -p`, known-bad count). **Not field-run** — reasoned and inspected only; needs one run of `doctor.sh --gate-selftest ` on a macOS machine with Studio Pro 11 and a real `.mpr` before the team is told to pull. Found by Yvann during Mac/sandbox onboarding — Yvann diff --git a/README.md b/README.md index 5629526..1528a9e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Shared skills, prompt templates, and learnings for **Mendix migration and develo Serves five ways in — four pipeline entry modes that share the same stages, plus one route with no pipeline at all (see `skills/conversion-runbook.md` "Entry Modes"; the mode is a **confirmed Stage-P decision**, never silently inferred — if source code exists it gets analyzed, if specs exist stages 2–4 run, and greenfield is only for starting from a conversation): +**Which scripts run at each step of each walk:** `docs/pipeline-walks.html` — one process diagram per entry mode (plus the shared spine and the Stage 5 module loop), each with a stage-by-stage table of the commands executed. A browser page, like the guide. + - **Migrations** (legacy source code) — all stages. - **Requirements-driven builds** (specs/BRDs/SME input, no legacy code) — stages 1–6; document discovery replaces source triage, extraction Path B/C replaces code extractors. - **Greenfield mxcli builds** — Stage 5 onward; the standard Mendix build discipline is not migration-specific. diff --git a/docs/pipeline-walks.html b/docs/pipeline-walks.html new file mode 100644 index 0000000..604c2a3 --- /dev/null +++ b/docs/pipeline-walks.html @@ -0,0 +1,360 @@ + + + + + +Pipeline Walks + + + + + +
+
mxcli-project-toolkit
+

Pipeline Walks

+

One process diagram per entry mode: which stages run, what each step does, and which scripts the agent executes there. The stages are the same everywhere; the modes differ in where you enter and which steps are declared not applicable in the register.

+ +
+ ✋ hard stop, the agent asks in chat and ends its turn + CAC-n checkpoint file in skills/checkpoints/, writes to PROJECT.md + N/A declared in the register with a reason, never silently skipped +
+ + +

Shared spine every mode walks the same stages

+

Every stage closes with bin/gate-check.sh <project> <stage>, which regenerates the dashboard and runs the obligation check, the artifact-manifest check and the source ledger. Hard-stop stages end the agent's turn until the user answers.

+ 
+flowchart LR
+  P["P Kickoff
init-project.sh"] --> S0["0 Triage and Scope ✋
CAC-1"]
+  S0 --> S1["1 Analysis
Path A / B / C / D
CAC-1b"]
+  S1 --> S2["2 Requirements
BRDs, CAC-2, CAC-3"]
+  S2 --> S3["3 Architecture and Design ✋
CAC-4"]
+  S3 --> S4["4 Build Plan ✋
CAC-5"]
+  S4 --> BR{"gate-check
build-ready"}
+  BR --> S5["5 Build
module loop x N"]
+  S5 --> S6["6 Test
app-wide"]
+  S6 --> S7["7 Cutover ✋
CAC-6, migration only"]
+  S7 --> WU["Wrap-up
harvest-learnings.sh"]
+  classDef stop fill:#f8dedb,stroke:#b3261e,color:#1d2430
+  class S0,S3,S4,S7 stop
+
+
+ + + + + + +
AlwaysWhat it doesScript
Once per machineChecks prerequisites (Node, Python, git, Bash flavour, mxcli, WSL warning). Windows runs under Git Bash, not WSL.bin/doctor.sh
Each session startPull the toolkit, compare the commit with the register's Toolkit commit: line, re-read the runbook on mismatch.git pull --ff-only in the toolkit clone
bin/sync-project.sh <project> after any pull
Where am IReads the register and the real files; never inferred from memory.bin/status.sh <project>
bin/gate-check.sh <project>
Stage closeMechanical verdict per stage: PASS / PENDING / FAIL / WAIVED / MANUAL. Blocks on any UNSYNCED drift marker.bin/gate-check.sh <project> <stage>
--waive look/<Module> --reason "…"
Wrap-upDrafts inbox learnings from the project's bug logs, register promotions and locally patched scripts.bin/harvest-learnings.sh <project>
+ + +

Migration Legacy source code exists

+

The full walk, P through 7. Path A extractors always run; Path B and C run when documents or subject-matter experts exist too.

+ 
+flowchart TD
+  P["P Kickoff"] --> P1["init-project.sh
intake.md answered
mode CONFIRMED in PROJECT.md"]
+  P1 --> S0["0 Triage and Scope ✋"]
+  S0 --> S0a["source-sufficiency.sh init
every-file inventory"]
+  S0a --> S0b["fill inventory + dimensions
source-sufficiency.sh report
band + interview mode"]
+  S0b --> S0c["extract-or-not per structure
coverage matrix
document-discovery"]
+  S0c --> S0d["triage-report.sh
CAC-1 scope brainstorm
sign-off in triage.md"]
+  S0d --> S1["1 Analysis"]
+  S1 --> A["Path A code
pipelines/<platform>
node run.js 1 / 2 / 3"]
+  S1 --> B["Path B docs
html-to-md.sh, images-to-md.sh
kb-generation"]
+  S1 --> C["Path C SME interview"]
+  A --> S1x["source-ledger.sh report + check
extraction-report.sh
CAC-1b"]
+  B --> S1x
+  C --> S1x
+  S1x --> S2["2 Requirements"]
+  S2 --> S2a["BRD scaffolds → enrich from KB → validate
F{NNN}.brd.json"]
+  S2a --> S2b["brd-report.sh
open-questions.sh --stage 2 = 0 blocking
facts-lock.sh, question-kinds.sh"]
+  S2b --> S2c["CAC-2 BRD sign-off
CAC-3 architecture entry"]
+  S2c --> S3["3 Architecture and Design ✋"]
+  S3 --> S3a["modularize-domain → blueprint.md + html
fit-gap, .mx-brd.json"]
+  S3a --> S3b["design-system.html, ds.css
one wireframe per screen
CAC-4"]
+  S3b --> S4["4 Build Plan ✋"]
+  S4 --> S4a["brd-to-build-plan → build-plan.md
coverage-check.sh
module briefs, CAC-5"]
+  S4a --> BR{"gate-check build-ready"}
+  BR --> S5["5 Build"]
+  S5 --> S5a["walking skeleton first"]
+  S5a --> S5b["per module: BUILD → GATE → PROVE → LOOK → CONFIRM
check --references, exec.sh, lint,
verify-module.sh, design-audit.js, ui-review"]
+  S5b --> S5c["every 2-3 modules
coherence pass: lint QUAL004, graph-report"]
+  S5c --> S6["6 Test"]
+  S6 --> S6a["Playwright golden path + edge cases
DB assertions
test-report.html, docs/report.json"]
+  S6a --> S7["7 Cutover ✋"]
+  S7 --> S7a["data migration scripts
cutover checklist, CAC-6"]
+  S7a --> WU["Wrap-up
harvest-learnings.sh"]
+  classDef stop fill:#f8dedb,stroke:#b3261e,color:#1d2430
+  class S0,S3,S4,S7 stop
+  classDef mode fill:#dde8f6,stroke:#2f5f9e,color:#1d2430
+  class P,S1,S2,S5,S6 mode
+
+
+ + + + + + + + + + +
StageStepsScripts and commands
P KickoffScaffold the project. Answer every intake question. Propose the entry mode with evidence and record it CONFIRMED. Gate: every intake question answered. Owner ba-agent.bin/init-project.sh <project>
bin/init-agents.sh <session-root>
bin/gate-check.sh <project> P
0 Triage ✋Inventory every source file. Grade sufficiency (SPECIFICATION / OUTLINE / SKETCH). Decide extract-or-not per structure and fill the coverage matrix. Scan documents. Run the CAC-1 scope brainstorm, order the slices, get sign-off in triage.md. Owner ba-agent.bin/source-sufficiency.sh init <project>
bin/source-sufficiency.sh report <project>
bin/interview-mode.sh --set … (only after the user agrees)
bin/triage-report.sh <project>
bin/source-sufficiency.sh --refresh for late files
bin/gate-check.sh <project> 0
1 AnalysisPath A: run the platform pipeline (extract, knowledge base, BRD scaffolds, reports). Path B: convert documents to Markdown and build the KB. Path C: interview the SME. Every source file must name the artifact that consumed it. Gate: source ledger clean, four extraction quality checks. CAC-1b.cd pipelines/<platform>/pipeline && npm install
node run.js · node run.js 2 · node run.js 3 · npm run reports
bin/html-to-md.sh <project> · bin/images-to-md.sh
bin/source-ledger.sh report <project>
bin/source-ledger.sh check <project>
bin/extraction-report.sh <project>
bin/gate-check.sh <project> 1
2 RequirementsTurn scaffolds into validated BRDs, one per feature. Drive blocking open questions to zero. Lock facts. CAC-2 BRD sign-off, CAC-3 architecture entry.bin/brd-report.sh <project>
bin/open-questions.sh <project> --stage 2
bin/questions-report.sh · bin/facts-lock.sh · bin/question-kinds.sh
bin/gate-check.sh <project> 2
3 Design ✋Module boundaries, blueprint, fit-gap, security model, integrations. Design system and one wireframe per screen. CAC-4. Owner architect-agent, interviews by ba-agent.skills: modularize-domain.md, architecture-blueprint.md, design-artifacts.md
outputs: architecture/blueprint.html, design/design-system.html, design/wireframes/*.html
bin/gate-check.sh <project> 3
4 Build plan ✋Dependency-ordered script sequence, coverage ledger, one brief per module. CAC-5, then the build-ready wiring check.bin/coverage-check.sh
bin/gate-check.sh <project> 4
bin/gate-check.sh <project> build-ready
5 BuildWalking skeleton, then the five-stage module loop per module (see below). Coherence pass every two or three modules../mxcli check s.mdl -p app.mpr --references
bin/exec.sh s.mdl · ./mxcli lint -p app.mpr
project-bin/verify-module.sh <Module>
./mxcli graph-report -p app.mpr
bin/gate-check.sh <project> 5
6 TestGolden path, edge cases and database assertions across the whole app. Zero open P1 in the app-wide review. Owner test-agent and review-agent.Playwright suite per e2e-harness-base.md
outputs: test-report.html, docs/report.json
bin/gate-check.sh <project> 6
7 Cutover ✋Legacy data migration scripts and the cutover checklist. Runs after Stage 6 on purpose. CAC-6.bin/gate-check.sh <project> 7
bin/harvest-learnings.sh <project>
+ + +

Requirements-driven Specs, BRDs, workshop output, no legacy code

+

Same spine, Stage 7 dropped. Path A is declared N/A with evidence, never skipped. A text-native corpus (Markdown and HTML only) takes the docs-ready fast path.

+ 
+flowchart TD
+  P["P Kickoff
init-project.sh"] --> S0["0 Triage and Scope ✋"]
+  S0 --> S0a["source-sufficiency.sh init + report
document-discovery over the corpus
extraction call per extractable structure"]
+  S0a --> S0b["triage-report.sh
CAC-1, sign-off"]
+  S0b --> Q{"corpus text-native?
no Office / PDF"}
+  Q -- "no" --> S1["1 Analysis
Path B kb-generation
Path C SME
Path A = N/A"]
+  Q -- "yes: docs-ready" --> F1["1 html-to-md.sh once
text/*.md + documents-index.md"]
+  S1 --> S1x["source-ledger.sh, extraction-report.sh
CAC-1b"]
+  F1 --> F2["2 thin BRD transform
one use case per section, sourceRef"]
+  S1x --> S2["2 Requirements
BRDs from KB
brd-report.sh, open-questions.sh"]
+  S2 --> S3
+  F2 --> S3["3 Architecture and Design ✋
CAC-4"]
+  S3 --> S4["4 Build Plan ✋
CAC-5, build-ready"]
+  S4 --> S5["5 Build
module loop"]
+  S5 --> S6["6 Test"]
+  S6 --> S7["7 Cutover
N/A unless legacy data exists"]
+  classDef stop fill:#f8dedb,stroke:#b3261e,color:#1d2430
+  class S0,S3,S4 stop
+  classDef mode fill:#f6e9cf,stroke:#8a5a10,color:#1d2430
+  class P,S1,S2,S5,S6,F1,F2 mode
+  classDef na fill:#ece9e2,stroke:#c6beae,color:#7c8494
+  class S7 na
+
+
+ + + + + + +
StageWhat changes versus migrationScripts and commands
0 Triage ✋Runs in full. Document inventory always runs. The extraction call runs per extractable structure inside the docs (a schema, a table dump, an export). N/A is earned on evidence.bin/source-sufficiency.sh init <project>
bin/source-sufficiency.sh report <project>
bin/triage-report.sh <project>
bin/gate-check.sh <project> 0
1 AnalysisPath B and C only. The source ledger still has to account for every document, including embedded images and pages.bin/html-to-md.sh <project>
bin/images-to-md.sh
bin/source-ledger.sh report | check
bin/extraction-report.sh <project>
1–2 docs-readyFast path: one conversion run, then a thin BRD transform with one use case per section and a sourceRef back to the text. Stages 3 and 4 unchanged.bin/html-to-md.sh <project> (once)
outputs: analysis/knowledge-base/text/*.md, documents-index.md
2–6Unchanged. Same reports, same gates, same module loop.as migration
7N/A in the register unless legacy data exists somewhere to cut over.register line only
+
Small project tier (one module, up to 8 screens, 25 use cases): set Size tier: small in the register and follow small-project-tier.md. The stages still run, the artifacts shrink.
+ + +

Greenfield Just an idea, or a running start on the model

+

The narrowest mode. Stages 1 to 4 collapse to whatever plan the user already has. Stage 0 does not collapse: the scope conversation still runs. If you find yourself inventing requirements mid-build, you are in requirements-driven mode and should back up to Stage 2.

+ 
+flowchart TD
+  P["P Kickoff light
init-project.sh
intake answered"] --> S0["0 Scope only ✋
CAC-1 brainstorm
sign-off in triage.md"]
+  S0 --> S0a["inventory, extraction, documents
rows = N/A in the register"]
+  S0a --> C["1–4 collapse
to the plan the user brings"]
+  C --> BR{"gate-check build-ready"}
+  BR --> S5["5 Build
walking skeleton, then module loop"]
+  S5 --> S6["6 Test"]
+  S6 --> S7["7 Cutover N/A"]
+  S6 --> WU["Wrap-up
harvest-learnings.sh"]
+  classDef stop fill:#f8dedb,stroke:#b3261e,color:#1d2430
+  class S0 stop
+  classDef mode fill:#dfeedc,stroke:#3f7b3a,color:#1d2430
+  class P,S5,S6 mode
+  classDef na fill:#ece9e2,stroke:#c6beae,color:#7c8494
+  class S0a,C,S7 na
+
+
+ + + + + +
StageStepsScripts and commands
P lightScaffold, answer intake, register Greenfield CONFIRMED.bin/init-project.sh <project>
0 Scope ✋CAC-1 brainstorm and slice ordering. Inventory, extraction and document rows are written N/A with the reason "no corpus".bin/gate-check.sh <project> 0
5 BuildWalking skeleton first, then the module loop. Same discipline as every other mode../mxcli check s.mdl -p app.mpr --references
bin/exec.sh s.mdl · ./mxcli lint -p app.mpr
project-bin/verify-module.sh <Module>
6 TestGolden path, edge cases, DB assertions, app-wide review.bin/gate-check.sh <project> 6
+ + +

Change an existing app A live .mpr you are altering, not rebuilding

+

The knowledge base comes from the model itself (Path D). The first real step is mapping the app for the agent: structure, quality, security, marketplace drift. Stage 0 adds the blast radius of the slice. A regression net goes under the app before anything changes, and every gate from Stage 5 on is also a regression gate.

+ 
+flowchart TD
+  P["P Kickoff light
init-project.sh, intake from the model
register: Change an existing app CONFIRMED"] --> M["Map the app for the agent"]
+  M --> M1["structure
SHOW MODULES / ENTITIES / ASSOCIATIONS
mxcli graph-report"]
+  M --> M2["quality
mxcli lint + Starlark rules
mxcli report (assess-quality)"]
+  M --> M3["security and drift
SHOW SECURITY MATRIX
mxcli marketplace diff"]
+  M1 --> S0
+  M2 --> S0
+  M3 --> S0
+  S0["0 Triage ✋ two questions:
which slice, what is its blast radius"] --> S0a["blast radius into triage.md
associations, microflows (SEARCH),
pages (SHOW PAGES IN), module tangle,
published / consumed services"]
+  S0a --> S0b["capability map from SHOW MODULES
extraction rows N/A
CAC-1, sign-off"]
+  S0b --> RN["Regression net under the app
Track B baseline from existing-app-assurance"]
+  RN --> S1["1 Analysis Path D
DESCRIBE ENTITY, SHOW MICROFLOWS IN,
graph-report scoped to slice + blast radius
counts recorded, Path A = N/A, CAC-1b"]
+  S1 --> S2["2 Requirements
slice-only BRDs, as-is / to-be
CAC-2, CAC-3"]
+  S2 --> Q{"crosses a module boundary,
adds an integration,
alters the domain model?"}
+  Q -- "yes" --> S3["3 Architecture and Design ✋ in full
wireframes for changed screens only
design system = captured existing styling"]
+  Q -- "no" --> S3b["3 collapses to:
which existing module owns this"]
+  S3 --> S4
+  S3b --> S4["4 Build Plan ✋ slice only
respects live data
coverage ledger = mxcli brain plan
CAC-5, build-ready"]
+  S4 --> S5["5 Build
module loop + regression net must stay green
mxcli brain capture per leaf"]
+  S5 --> S6["6 Test
slice journeys + full regression suite"]
+  S6 --> S7["7 Cutover N/A: the app is live"]
+  classDef stop fill:#f8dedb,stroke:#b3261e,color:#1d2430
+  class S0,S3,S4 stop
+  classDef mode fill:#f3dfe8,stroke:#8a3a5e,color:#1d2430
+  class P,M,M1,M2,M3,RN,S1,S2,S5,S6 mode
+  classDef na fill:#ece9e2,stroke:#c6beae,color:#7c8494
+  class S3b,S7 na
+
+
+ + + + + + + + + + + +
StepWhat it doesScripts and commands
P lightScaffold. Intake answers come from the model, not from the user's memory. Run the machine check once.bin/doctor.sh
bin/init-project.sh <project>
Map the appGive the agent a picture of the whole app before scoping: module graph and dependency tangle, current quality score, lint findings, security matrix, marketplace modules that drifted from their published version. The findings feed the blast-radius answer and the regression baseline../mxcli -p app.mpr -c "SHOW MODULES"
./mxcli -p app.mpr -c "SHOW STRUCTURE DEPTH 2"
./mxcli graph-report -p app.mpr (graph-analysis.md)
./mxcli lint -p app.mpr
./mxcli report -p app.mpr --format html
./mxcli -p app.mpr -c "SHOW SECURITY MATRIX"
./mxcli marketplace diff <content-id> -p app.mpr (v0.18+)
0 Triage ✋Two questions: which slice, and what is its blast radius. The radius is written into triage.md as its own section, with counts. Capability map from the module list. CAC-1 and sign-off.SHOW ASSOCIATIONS IN <Module> · DESCRIBE ENTITY M.E
SEARCH '<entity>' · SHOW PAGES IN <Module>
SHOW REFERENCES OF M.E · SHOW IMPACT OF M.E
./mxcli graph-report for the tangle
bin/gate-check.sh <project> 0
Regression netTrack B from the assurance skill, before any change: harness, action inventory, one journey per action, DB assertions, wiring sweep, LOOK pass, committed baseline.see Track B below
project-bin/coverage-preflight.sh --assess --module <M>
1 Path DQuery the model into the knowledge base, scoped to slice plus blast radius. Record counts. Path A declared N/A with attribution. Path C matters most here: the people who know why the app is the way it is.SHOW ENTITIES IN · DESCRIBE ENTITY · SHOW MICROFLOWS IN
DESCRIBE MICROFLOW · DESCRIBE PAGE
bin/extraction-report.sh <project>
bin/gate-check.sh <project> 1
2 RequirementsOne as-is / to-be BRD per capability being changed. Nothing for the untouched rest.bin/brd-report.sh · bin/open-questions.sh --stage 2
3 DesignFull only when the change crosses a module boundary, adds an integration or alters the domain model. Otherwise "which module owns this". Wireframes for changed screens only.bin/gate-check.sh <project> 3
4 Build plan ✋Slice-only plan that respects live data. Coverage ledger lives in the brain, not a hand-kept file../mxcli brain init · ./mxcli brain plan
bin/gate-check.sh <project> build-ready
5–6Module loop unchanged. Every gate also re-runs the regression net. Each finished leaf is captured in the brain.bin/exec.sh s.mdl · project-bin/verify-module.sh <M>
./mxcli brain capture "<leaf>" · ./mxcli brain check
7N/A in the register: the app is already live.register line only
+ + +

À-la-carte assurance Audit or test an app nobody is changing

+

No pipeline, no intake, no gates, no register. Read-only against the model. Three tracks, pick what the user asked for. Track B is also the regression baseline the change mode needs.

+ 
+flowchart LR
+  E["existing-app-assurance.md"] --> A["Track A audit"]
+  E --> A2["Track A2 design-system audit"]
+  E --> B["Track B regression net"]
+  A --> A1["query the model
SHOW MODULES / ENTITIES / ASSOCIATIONS
DESCRIBE ENTITY, SEARCH"]
+  A1 --> A3["structure
mxcli graph-report"]
+  A3 --> A4["best practices
mxcli lint + Starlark"]
+  A4 --> A5["security
manage-security, sec_* rules"]
+  A5 --> A6["overall score
mxcli report"]
+  A6 --> A7["marketplace
mxcli marketplace diff"]
+  A7 --> AR["findings report
dispositions triaged with the user"]
+  A2 --> A2a["9 steps: theme.compiled.css root size,
check-design-portability.sh"]
+  B --> B1["1 harness
e2e-harness-base"]
+  B1 --> B2["2 action inventory per module
SHOW PAGES IN, SHOW MICROFLOWS IN"]
+  B2 --> B3["3 journeys/<Module>.journey.json
5 rungs, --positive-control"]
+  B3 --> B4["4 DB assertions"]
+  B4 --> B5["5 wiring sweep"]
+  B5 --> B6["6 LOOK + design-audit.js"]
+  B6 --> B7["7 commit suite + baseline"]
+  B7 --> B8["8 optional test-agent
init-agents.sh build"]
+  classDef mode fill:#e4e5ea,stroke:#5b5e69,color:#1d2430
+  class E,A,A2,B mode
+
+
+ + + + +
TrackWhat it doesScripts and commands
A auditMap, then score. Structure and tangle, best practices, security posture, overall quality, marketplace drift. Deliverable is a findings report whose dispositions are triaged with the user, never applied silently../mxcli -p app.mpr -c "SHOW STRUCTURE"
./mxcli graph-report -p app.mpr
./mxcli lint -p app.mpr --list-rules
./mxcli report -p app.mpr --format html
./mxcli marketplace diff <id> -p app.mpr --json
A2 designNine-step design-system audit of the deployed theme, including the root font size and portability of the design tokens.grep on deployment/web/theme.compiled.css
bin/check-design-portability.sh
B regression netEight steps, each with a recorded denominator: one journey per page action, database assertions, wiring sweep, LOOK pass, then commit the suite as the baseline. On an existing app verify-module.sh is never expected to come back clean, so run the preflight first.project-bin/coverage-preflight.sh --assess --module <M>
project-bin/verify-module.sh <Module>
design-audit.js
bin/init-agents.sh <session-root> build (test-agent only)
+ + +

Stage 5 module loop shared by every mode that builds

+

Five stages per module from module-review.md. Each stage owes a mark with a denominator; the obligation check reports a pass nobody performed as PENDING, never green.

+ 
+flowchart LR
+  WS["walking skeleton
one thin end-to-end path"] --> L1
+  subgraph mod["per module, entities → microflows → pages, security-setup.mdl last"]
+    L1["1 BUILD mdl-agent
mxcli check --references"] --> L2["2 GATE gate-agent
exec.sh: snapshot → exec → mxbuild → auto-restore
mxcli lint"]
+    L2 --> L3["3 PROVE
verify-module.sh
Playwright + OQL + wiring sweep + monkey"]
+    L3 --> L4["4 LOOK every screen
design-audit.js, check-page-shell.sh,
page-fidelity.js"]
+    L4 --> L5["5 CONFIRM
ui-review-<date>.html with denominator"]
+  end
+  L5 --> N{"2-3 modules done?"}
+  N -- "yes" --> CP["coherence pass
lint QUAL004
graph-report GRAPH_DEAD_ASSETS, GRAPH_INTEGRATION_SURFACE"]
+  N -- "no" --> L1
+  CP --> L1
+  L2 -. "mxbuild fails" .-> R["restore-mpr.sh"]
+  R --> L1
+
+
+ + + + + + +
StageWhat it provesScripts and commands
1 BUILDScript parses and every referenced module, entity and association exists../mxcli check s.mdl -p app.mpr --references
2 GATESnapshot, execute, run mxbuild, auto-restore on failure. Lint the result.bin/exec.sh mdlsource/s.mdl
bin/exec-approval.sh where approval is wired
./mxcli lint -p app.mpr
bin/restore-mpr.sh on a bad build
3 PROVEJourneys click through, database rows match, no dead wiring, monkey run survives.project-bin/verify-module.sh <Module>
fixtures per fixture-seeding.md
4 LOOKEvery screen viewed against its wireframe, design tokens reach the running app.node design-audit.js
project-bin/check-design-reaches-app.sh
project-bin/check-page-shell.sh
node project-bin/page-fidelity.js
5 CONFIRMWritten review with the denominator: N of N screens looked at, N journeys run.output: design/ui-reviews/ui-review-<date>.html
bin/gate-check.sh <project> 5
+ +
Sources: skills/conversion-runbook.md (stage tables and entry modes), skills/existing-app-change.md (Path D and blast radius), skills/existing-app-assurance.md (Tracks A, A2, B), skills/module-review.md. Script names are the toolkit's own; replace <project> and app.mpr with yours.
+
+ + + +