diff --git a/CHANGELOG.md b/CHANGELOG.md index 5aca583f..5693d3b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m - fix(ready, ci, gate-check): **field run of the CI gate and `ready.sh` on a six-app copy (#788)**: a hand-written `# READY FOR BENCH (fix round 6, …)` heading passed the `ready` check (READY followed by words now counts; heading markup stripped); `ready.sh` ran over 300 s with no output (every external step now names itself, has stdin closed and a watchdog, `MXTK_READY_STEP_TIMEOUT`, default 120 s; a killed step is NOT MEASURED); the `order` check counted 0 of 234 per-app scripts (`apps//mdlsource/` now counted); and Stage 5 returned an empty verdict on any project with neither a look ledger nor a summary (`rows` unbound under `set -u`, introduced earlier in this PR); on the re-run, claims in a lowercase root `status.md` were not scanned (root status/progress/resume files now matched in any case), and an annotated `- Interview mode: auto (…)` line, which `interview-mode.sh` resolves to steering, waived the independent review (the raw line's first word now decides whether the review is owed) — parent session's field run - new(ci, ready): **the gate an agent cannot skip, and a READY nobody can hand-write.** `bin/ci-gates.sh` runs in the project's own CI (`.github/workflows/toolkit-gates.yml`, from `templates/ci/`, installed by `init-project.sh` and `sync-project.sh` create-if-absent, never overwritten, beside any existing CI) on every push and PR, over the committed tree at the pinned toolkit commit: the claimed stage's gate FAILs, a READY line `bin/ready.sh` did not write (`bin/lib/ready-claims.sh`, also a Stage 6 FAIL), committed unseen pages under a done-claim, and model work before Stage 4 all fail it (otherwise it prints `look: K of N pages seen` as a visible warning), in seconds, with no Mendix runtime. `ready.sh` now also requires the position (stages P and 0–4 PASS, WAIVED or not owed by the entry mode: a field run wrote READY with Stage P never passed), honours `Waived obligation must-haves`, writes a review packet (`docs/progress/review-packets/.html`: screenshot beside target with the reviewer's score, paths only), reads the must-have mark on its tracked path `docs/progress/must-haves/.md`, and names every app of a multi-app project instead of checking nothing (field runs, 2026-11: agents skip in-session gates; a hand-written READY graded a 0-of-78-looked build done) — two unattended field runs - new(ready, look-ledger, gate-check): **READY is earned through one command, and its evidence is in git.** `bin/ready.sh [--module M | --app A]` runs `gate-check.sh` Stage 5 (Stage 6 once the register is there), the look ledger, the must-have list when present and, under `Interview mode: auto`, an independent reviewer's verdict file (`docs/progress/look-reviews/`, every page scored 1–5 after its last build, below 4 blocks); it prints K of N per check, exits non-zero unless all pass, writes the READY line to `docs/progress/ready.log` itself and commits `docs/progress/ready--.md` with explicit paths. `look-ledger.sh summary --write` puts the git-ignored ledger into a tracked `docs/progress/look-summary.tsv` (written by `ready.sh` and every `close-task.sh`), and `gate-check.sh` Stage 5 reads it when the ledger is absent, so a copy of the repo reports FAIL instead of MANUAL. `dispatching.md` gains the reviewer dispatch rule; the `ready` routing row reaches `CLAUDE.local.md` and every agent stub (field runs, 2026-11: a build wrote READY by hand with 0 of ~78 pages looked at; another marked itself ready 3 hours early with no review pass) — two unattended field runs +- process(entry modes): **greenfield is retired; two doors replace it** (stacked on the mode-contract PR): an idea for a demo is `Build type: poc` (unchanged), an idea for a real app is requirements-driven with the conversation as the source (Stages 1–2 a short interview that writes the BRDs, then 3–6 as usual; the small-project tier and `Pipeline mode: high-speed` keep it light) — no mode skips design and planning any more. `sync-project.sh` maps a register's `Entry mode: greenfield` to `requirements-driven` once (old line kept as a comment), adopted at the stage its readout shows through `gate-check.sh --adopt` (so under `Interview mode: auto` it is a ✋ human-pending decision), with `ENTRY-MODE-MAPPED` and `TOOLKIT-ADOPTED-AT` rows in `docs/BUILD-LOG.md`. `greenfield` is dropped from `artifact-manifest.tsv` column 6 and `obligations.tsv` column 10 (now `migration,requirements,existing-app-change`; `test-mode-contract.sh` V checks both against the reader). Until synced, gate-check, status and exec.sh print one "run sync" line and excuse nothing (the tokeniser reads it as `greenfield-retired`; the artifact check owes every row). A POC that becomes a real app hands its hand-over to a requirements-driven build or starts change-an-existing-app, stated once in the runbook (rule 4). `poc-build.md` gains step 0 "Inputs" (read a supplied spec once, list use cases/rules/must-haves; over POC size, recommend requirements-driven in the same message). Runbook, intake Q1, interview-protocol, README, toolkit-guide, `CONVERSION-RUNBOOK.md`, `pipeline-walks.html` and 12 skills' mode lists updated; the 2026-07-14 misclassification note is kept. Fixture `tests/wave2/test-greenfield-retired.sh` — owner decision, Nov 2026 - 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 diff --git a/CONVERSION-RUNBOOK.md b/CONVERSION-RUNBOOK.md index 33f5a994..85f5b7f2 100644 --- a/CONVERSION-RUNBOOK.md +++ b/CONVERSION-RUNBOOK.md @@ -21,7 +21,8 @@ Then open your agent (Claude Code or equivalent) in `` and say wha |---|---|---| | Legacy source code | Migration | P, 0–7 | | Requirements/specs only, no code | Requirements-driven | P, 1–6 | -| Just an idea / existing plan | Greenfield | P (light), 5–6 | +| Just an idea — a real app | Requirements-driven, the conversation as the source | P, 0–6 | +| Just an idea — a demo | `Build type: poc` (`skills/poc-build.md`) | its own steps 1–9 | | A live Mendix app you are changing | Change an existing app | P, 0–6 per change | ## Running unattended — the kick-off brief diff --git a/README.md b/README.md index 1e22977a..14ba30e4 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ commands that run at every step: `docs/pipeline-walks.html`. |---|---|---| | **Migration** | Legacy source code exists | P, 0 to 7 | | **Requirements-driven** | Specs, BRDs or wireframes, no code | P, 0 to 6 | -| **Greenfield** | Just an idea or a plan | P (light), 0, 5, 6 | +| **Requirements-driven, from a conversation** | Just an idea for a real app (a demo: `Build type: poc`) | P, 0 to 6 | | **Change an existing app** | A live `.mpr` you add to or alter | P, 0 to 6 per change | | **À la carte assurance** | Audit or a test net only | none | diff --git a/bin/ci-gates.sh b/bin/ci-gates.sh index 080d1072..46936394 100755 --- a/bin/ci-gates.sh +++ b/bin/ci-gates.sh @@ -23,7 +23,7 @@ # committed summary behind it fails: the claim cites evidence nobody can read. # (d) order model work before its plan: docs/BUILD-LOG.md has exec rows (or mdlsource/ holds build # scripts outside gallery/) while gate-check Stage 4 is not PASS/WAIVED. gate-check already -# waives Stage 4 for greenfield and for an --adopt point at or after it. +# waives Stage 4 for an --adopt point after it (and Build type: poc, where it is not owed). # # WHAT IT CANNOT SEE (anything not committed): the git-ignored .claude/loop/ ledgers themselves (only # the summary ready.sh / close-task.sh commit), screenshots, chat, a model edited without exec.sh and diff --git a/bin/gate-check.sh b/bin/gate-check.sh index 9a7124df..c3b211fa 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -742,10 +742,6 @@ stage_waiver() { # Entry mode. The runbook's Entry Modes table already says these stages do not run; until now # the gate did not know that, so it demanded artifacts the runbook had excused. case "$ENTRY_MODE" in - greenfield) - case "$st" in - 1|2|3|4) printf 'mode|not owed (mode: greenfield) — stages 1–4 collapse into the design front end and short plan (conversion-runbook.md → Entry Modes)\n'; return 0 ;; - esac ;; requirements-driven) case "$st" in 7) printf 'mode|not owed (mode: requirements-driven) — no legacy system to cut over from; if legacy data turns up, record a Stage-7 decision and this goes back to being checked (conversion-runbook.md → Entry Modes)\n'; return 0 ;; @@ -4186,6 +4182,9 @@ printf "Summary: %d passed · %d not started · %d waived · %d need attention if [ -z "$ENTRY_MODE" ] && [ -z "$ADOPTED_AT" ] && [ -n "${MXTK_POS_BANNER:-}" ]; then printf '⚠ %s\n' "$MXTK_POS_BANNER" fi +if [ "$ENTRY_MODE" = greenfield-retired ] && [ -n "${MXTK_POS_RETIRED:-}" ]; then + printf '⚠ %s\n' "${MXTK_POS_RETIRED//$PROJECT_DIR}" +fi # The stage counts above are about STAGES. They say nothing about the per-module passes and the # per-stage artifacts checked further up, and for a long time nothing down here did either — so diff --git a/bin/init-project.sh b/bin/init-project.sh index c74d3008..85671931 100755 --- a/bin/init-project.sh +++ b/bin/init-project.sh @@ -467,7 +467,7 @@ fi # resolves $ANALYSIS_BASE against it. sources/ was created here from day one; analysis/ was not, # on the unstated assumption that an extraction pipeline would `mkdir -p` it on its way past. # -# That assumption holds for exactly one entry mode. A requirements-driven or greenfield project +# That assumption holds for exactly one entry mode. A requirements-driven project or a POC # runs no pipeline, so nothing ever created the folder, so every surface the runbook promises had # nowhere to be written — reported from a customer round on 2026-08-20, where the absence of # analysis/ was the first visible symptom of a much larger hole (Stage 0 being skipped entirely). @@ -497,7 +497,7 @@ and the honest way to change one is to re-run its producer. | `extraction-report.html` | the extraction pipeline, or `kb-generation.md` for a document corpus | 1 | | `brd-report.html` | `bin/brd-report.sh [--stage N]`: process map, requirements and open questions | 2, any gate | -**This folder exists in every entry mode.** A requirements-driven or greenfield project runs no +**This folder exists in every entry mode.** A requirements-driven project (or a POC) runs no extraction pipeline, but it still produces a sufficiency grade, a scope decision and a BRD report — `bin/brd-report.sh` reads BRDs, not source, so the Stage 2 surface is the same page whatever wrote the BRDs. diff --git a/bin/lib/artifact-check.sh b/bin/lib/artifact-check.sh index 461cb98a..7adf7b8c 100755 --- a/bin/lib/artifact-check.sh +++ b/bin/lib/artifact-check.sh @@ -217,6 +217,7 @@ _art_entry_mode() { local tok; tok="$(entry_mode_token "$raw")" case "$tok" in requirements-driven) echo "requirements" ;; + greenfield-retired) echo "" ;; # retired, not yet synced: every row owed — louder, never quieter *) echo "$tok" ;; esac } diff --git a/bin/lib/artifact-manifest.tsv b/bin/lib/artifact-manifest.tsv index 972093ea..143017c6 100644 --- a/bin/lib/artifact-manifest.tsv +++ b/bin/lib/artifact-manifest.tsv @@ -45,7 +45,8 @@ # 5 consumers the citations that earn the row its place (see above) # 6 modes THE MODE CONTRACT: comma list of the entry modes that owe it, in the tokens # bin/lib/entry-mode.sh produces (shared with obligations.tsv's modes column): -# migration,requirements,greenfield,existing-app-change. A mode not listed reports +# migration,requirements,existing-app-change (greenfield retired 2026-11-17: an +# unsynced register owes every row). A mode not listed reports # "not owed (mode …)", never PASS; a listed one missing reports PENDING as before. # `Build type: poc` is a separate axis, read by gate-check.sh, not a token here. # (conversion-runbook.md §"Entry Modes", its table; existing-app-change runs @@ -76,9 +77,9 @@ # later, not overdue now. # artifact stage paths producer consumers modes absence -intake P intake.md bin/init-project.sh scaffold + the Stage-P kickoff interview (conversion-runbook.md §2 Stage P) bin/gate-check.sh:596 (check_stage_P), bin/gate-check.sh:497 (entry-mode fallback read) migration,requirements,greenfield,existing-app-change gate -register P PROJECT.md bin/init-project.sh (empty register); every checkpoint writes into it (CLAUDE.md §One decision register) bin/gate-check.sh:285 (register resolution feeding every ✋ gate), bin/lib/obligation-check.sh:151 (waivers/adoption read from it) migration,requirements,greenfield,existing-app-change gate -triage 0 triage.md bin/init-project.sh scaffold, filled per skills/source-triage.md; N/A rows recorded, never deleted (conversion-runbook.md:130) bin/gate-check.sh:684 (check_stage_0 sign-off test) migration,requirements,greenfield,existing-app-change gate +intake P intake.md bin/init-project.sh scaffold + the Stage-P kickoff interview (conversion-runbook.md §2 Stage P) bin/gate-check.sh:596 (check_stage_P), bin/gate-check.sh:497 (entry-mode fallback read) migration,requirements,existing-app-change gate +register P PROJECT.md bin/init-project.sh (empty register); every checkpoint writes into it (CLAUDE.md §One decision register) bin/gate-check.sh:285 (register resolution feeding every ✋ gate), bin/lib/obligation-check.sh:151 (waivers/adoption read from it) migration,requirements,existing-app-change gate +triage 0 triage.md bin/init-project.sh scaffold, filled per skills/source-triage.md; N/A rows recorded, never deleted (conversion-runbook.md:130) bin/gate-check.sh:684 (check_stage_0 sign-off test) migration,requirements,existing-app-change gate app-report 0 analysis/app-report.json|analysis/app-report.html project-bin/app-facts.sh (read-only: full catalog build + mxcli graph-report + loop sweep) then bin/app-report.sh — skills/app-analysis.md Procedure steps 1 and 5 skills/existing-app-change.md §"Map the app first" (the findings interview reads analysis/app-report.json) and §"Blast radius" (reads analysis/app-facts/dependencies.json tangles and edges) existing-app-change report extraction-report 1 analysis/*/knowledge-base/extraction-report.html|analysis/knowledge-base/extraction-report.html|knowledge-base/extraction-report.html bin/extraction-report.sh — one renderer for every entry mode bin/gate-check.sh:725 (check_stage_1) migration,requirements,existing-app-change gate source-ledger 1 analysis/source-ledger.html bin/source-ledger.sh report — every inventoried source file and what consumed it (Stage 1 owes a disposition per row; gate-check blocks 1–2 on the check) bin/gate-check.sh (LEDGER block — the check; the html is the human-facing table of the same rows) migration,requirements,existing-app-change report @@ -99,26 +100,26 @@ build-plan-html 4 architecture/progress-report.html project-bin/build-plan-statu build-plan-json 4 architecture/build-plan.json project-bin/build-plan-status.sh --json (derived from build-plan.md's Step-5 Phase headings, row tables and claims: blocks, never hand-edited; not written when the markdown has no Phase headings; --refresh keeps an existing file current but never creates it) MXTK Studio Plan room (a view built from data, not from the HTML); nothing in the toolkit reads it and no verdict may depend on it migration,requirements,existing-app-change report module-brief 4 architecture/modules/*/module-brief.md|architecture/modules/*-brief.md skills/module-brief.md — ba-agent writes the first at Stage 4, the rest just-in-time bin/gate-check.sh:1121 (build-ready fails without one), project-bin/build-plan-status.sh:109 migration,requirements,existing-app-change gate coverage-ledger 4 architecture/modules/*/coverage-ledger/*.md|architecture/modules/*/coverage-ledger.md|architecture/modules/*-coverage-ledger.md|architecture/coverage-ledger.md skills/coverage-ledger.md procedure at Stage 4 (BRD leaves × build-plan claims); the four shapes are §"Where the ledger lives", the per-BRD split form first project-bin/conformance-check.sh:85-93, project-bin/coverage-preflight.sh:134-137, project-bin/verify-module.sh:299-300, project-bin/review-module.sh:289, conversion-runbook.md:487 (Stage-4 produces row) — the eleven-consumers-no-producer artifact of improvement-plan Finding 12 migration,requirements report -ui-reviews 5 design/ui-reviews/ui-review-*.html skills/module-review.md pass (review-agent), one report per module close-out bin/gate-check.sh:984 (check_stage_6), bin/lib/obligations.tsv:47 (the look row — per-module coverage and denominators live THERE; this row only asks whether the stage produced any report at all) migration,requirements,greenfield,existing-app-change gate -journeys 5 ${JOURNEY_DIR}/*.journey.json journey authoring per skills/testing-shape.md / skills/journey-proof.md (worked example: project-tests/e2e/example.journey.json) project-bin/verify-module.sh:376,404 (the journeys rung), project-tests/e2e/journey-runner.js:5 migration,requirements,greenfield,existing-app-change report -page-scope 5 .claude/loop/page-scope.json project-bin/page-scope.sh (the phantom of improvement-plan Finding 15 until 078c7d8 shipped it) project-tests/e2e/design-audit.js:55, project-tests/e2e/page-audit.js:66, project-tests/e2e/report-normalize.js:112 — without it the LOOK instruments degrade to --static-only migration,requirements,greenfield,existing-app-change report -lint-last 5 .claude/loop/lint-last.json project-bin/lint-gate.sh (written on every run that reaches a verdict, not only --update-baseline), run as part of skills/module-review.md stage 2 GATE ("bin/exec.sh; gate-agent confirms 0 mxbuild errors, lint clean" — same step named in skills/iterative-build-loop.md's "Gate: BUILD") bin/status.sh:75-81,129 (the OVERDUE line's lint readout — without it status.sh reports "lint gate never recorded here") migration,requirements,greenfield,existing-app-change report -improvement-register 5 docs/improvement-register.md skills/improvement-register.md:39 (append-only, one row per finding, written during build/verify passes) project-bin/build-plan-status.sh:69,148 (the proven-vs-built cross-reference), skills/close-the-loop.md migration,requirements,greenfield,existing-app-change report -improvement-register-html 5 docs/improvement-register.html project-bin/render-improvement-register.sh (landed 2026-08-22; in MXTK_PROJECT_BIN — bin/lib/install-manifest.sh:81-85) project-bin/render-improvement-register.sh:35 (output contract); human review surface for the register above — report-only by assignment migration,requirements,greenfield,existing-app-change report -report-json 6 docs/report.json project-bin/verify-module.sh:518 (normalize rung → report-normalize.js), run as part of every module verify bin/gate-check.sh:980 (check_stage_6 requires it alongside the HTML), project-tests/e2e/report-render.js (renders from it) migration,requirements,greenfield,existing-app-change gate -verification-html 6 docs/verification/report.html|test-report.html|reports/test-report.html project-bin/verify-module.sh:521 (render rung → report-render.js); the two test-report.html shapes are the legacy names check_stage_6 still accepts bin/gate-check.sh:970-995 (check_stage_6 — the gate that was structurally unpassable before b9c90a4/078c7d8, improvement-plan Finding 14) migration,requirements,greenfield,existing-app-change gate +ui-reviews 5 design/ui-reviews/ui-review-*.html skills/module-review.md pass (review-agent), one report per module close-out bin/gate-check.sh:984 (check_stage_6), bin/lib/obligations.tsv:47 (the look row — per-module coverage and denominators live THERE; this row only asks whether the stage produced any report at all) migration,requirements,existing-app-change gate +journeys 5 ${JOURNEY_DIR}/*.journey.json journey authoring per skills/testing-shape.md / skills/journey-proof.md (worked example: project-tests/e2e/example.journey.json) project-bin/verify-module.sh:376,404 (the journeys rung), project-tests/e2e/journey-runner.js:5 migration,requirements,existing-app-change report +page-scope 5 .claude/loop/page-scope.json project-bin/page-scope.sh (the phantom of improvement-plan Finding 15 until 078c7d8 shipped it) project-tests/e2e/design-audit.js:55, project-tests/e2e/page-audit.js:66, project-tests/e2e/report-normalize.js:112 — without it the LOOK instruments degrade to --static-only migration,requirements,existing-app-change report +lint-last 5 .claude/loop/lint-last.json project-bin/lint-gate.sh (written on every run that reaches a verdict, not only --update-baseline), run as part of skills/module-review.md stage 2 GATE ("bin/exec.sh; gate-agent confirms 0 mxbuild errors, lint clean" — same step named in skills/iterative-build-loop.md's "Gate: BUILD") bin/status.sh:75-81,129 (the OVERDUE line's lint readout — without it status.sh reports "lint gate never recorded here") migration,requirements,existing-app-change report +improvement-register 5 docs/improvement-register.md skills/improvement-register.md:39 (append-only, one row per finding, written during build/verify passes) project-bin/build-plan-status.sh:69,148 (the proven-vs-built cross-reference), skills/close-the-loop.md migration,requirements,existing-app-change report +improvement-register-html 5 docs/improvement-register.html project-bin/render-improvement-register.sh (landed 2026-08-22; in MXTK_PROJECT_BIN — bin/lib/install-manifest.sh:81-85) project-bin/render-improvement-register.sh:35 (output contract); human review surface for the register above — report-only by assignment migration,requirements,existing-app-change report +report-json 6 docs/report.json project-bin/verify-module.sh:518 (normalize rung → report-normalize.js), run as part of every module verify bin/gate-check.sh:980 (check_stage_6 requires it alongside the HTML), project-tests/e2e/report-render.js (renders from it) migration,requirements,existing-app-change gate +verification-html 6 docs/verification/report.html|test-report.html|reports/test-report.html project-bin/verify-module.sh:521 (render rung → report-render.js); the two test-report.html shapes are the legacy names check_stage_6 still accepts bin/gate-check.sh:970-995 (check_stage_6 — the gate that was structurally unpassable before b9c90a4/078c7d8, improvement-plan Finding 14) migration,requirements,existing-app-change gate # ── Opt-in rows (absence = optin) — added 2026-09-02 with the close-out block. Offered at # the stage open, owed only after opting in. Paths are the first-match convention; the second # alternative is the name a real project already used (workflow-design: a field project's # architecture/workflow-definition.md, written unprompted and never tracked by anything). -workflow-design 3 architecture/workflow-definition.md|architecture/workflow-design.md|architecture/workflows/*.md skills/architecture-blueprint.md Step 3b (state diagram per process: states, transitions, who moves it, SLA) + skills/learned-workflow-patterns.md for the native-Workflow shape skills/checkpoints/checkpoint-architecture.md Q3 (asks whether the process is Workflow or enum-driven — either way this is where it is drawn), skills/learned-workflow-patterns.md (the build-time reader), bin/lib/closeout.sh (offers it at the Stage-3 open, lists it at the close) migration,requirements,greenfield,existing-app-change optin -swimlanes 3 architecture/swimlanes.md|architecture/swimlane-*.md|architecture/diagrams/swimlane*.md|design/process-model.json Mermaid per business process, one lane per role from the Stage-3 role model, one section per process; the cross-persona journey diagrams of skills/architecture-blueprint.md Step 3d are the multi-persona case of the same picture; or the process map model of skills/process-map.md Step 2, which draws the same lanes and adds the screens and questions skills/checkpoints/checkpoint-architecture.md (the optional-artifacts question), skills/architecture-blueprint.md Step 3d (journey list it feeds), skills/journey-proof.md (the journeys a swimlane names are the ones Stage 5–6 must prove), bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin +workflow-design 3 architecture/workflow-definition.md|architecture/workflow-design.md|architecture/workflows/*.md skills/architecture-blueprint.md Step 3b (state diagram per process: states, transitions, who moves it, SLA) + skills/learned-workflow-patterns.md for the native-Workflow shape skills/checkpoints/checkpoint-architecture.md Q3 (asks whether the process is Workflow or enum-driven — either way this is where it is drawn), skills/learned-workflow-patterns.md (the build-time reader), bin/lib/closeout.sh (offers it at the Stage-3 open, lists it at the close) migration,requirements,existing-app-change optin +swimlanes 3 architecture/swimlanes.md|architecture/swimlane-*.md|architecture/diagrams/swimlane*.md|design/process-model.json Mermaid per business process, one lane per role from the Stage-3 role model, one section per process; the cross-persona journey diagrams of skills/architecture-blueprint.md Step 3d are the multi-persona case of the same picture; or the process map model of skills/process-map.md Step 2, which draws the same lanes and adds the screens and questions skills/checkpoints/checkpoint-architecture.md (the optional-artifacts question), skills/architecture-blueprint.md Step 3d (journey list it feeds), skills/journey-proof.md (the journeys a swimlane names are the ones Stage 5–6 must prove), bin/lib/closeout.sh migration,requirements,existing-app-change optin process-map 3 design/process-map.html skills/process-map.md Step 4 (project-bin/process-map.js build; generated from design/process-model.json, never hand-edited) bin/gate-check.sh:1162-1181 (check_stage_3 freshness against design/process-model.json and its anchors), skills/checkpoints/checkpoint-design.md:16 (CAC-4 uses it to walk the questions; pass 2 at the Stage 3 gate close-out) migration,requirements,existing-app-change optin -sequence-diagrams 3 architecture/sequence-diagrams.md|architecture/sequence-*.md|architecture/diagrams/sequence*.md Mermaid sequenceDiagram per integration or agent call — caller, Mendix microflow, external system, sync/async, timeout, fallback; the agent-wiring diagram of skills/architecture-blueprint.md Step 3c is one instance skills/checkpoints/checkpoint-architecture.md Q3 agent-wiring half, skills/rest-integration-first-time-right.md (build-time reader for the REST ones), skills/mendix-agents.md, bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin -erd 3 architecture/erd.md|architecture/domain-model.md|architecture/diagrams/erd*.md Mermaid erDiagram of the TARGET domain across modules — entities, associations, ownership per module; the blueprint's layer diagram shows modules, not entities, and .mx-brd.json shows one module at a time skills/checkpoints/checkpoint-architecture.md Q2 (cross-module data strategy — the picture that question is about), skills/modularize-domain.md, bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin -nfr-sheet 3 architecture/nfr.md|architecture/nfrs.md|architecture/non-functional-requirements.md One table: NFR, target, how measured, where in the model it is enforced (XPath, index, batch size, timeout) — the per-NFR expansion of the list CAC-3's open question writes to project-profile.md skills/checkpoints/checkpoint-architecture.md open question (the list), skills/architecture-blueprint.md Step 5 (the register that must not lose them), bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin -integration-contracts 3 architecture/integration-contracts.md|architecture/integrations.md|architecture/integrations/*.md Per integration: endpoint, auth, payload in/out, error handling, owner, test double — written BEFORE the build plan so the plan can sequence it skills/rest-integration-first-time-right.md (reads it first thing at Stage 5), skills/architecture-blueprint.md Step 5 (the integrations register), bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin -test-plan 4 architecture/test-plan.md|docs/test-plan.md Per module: the journeys to prove, the fixtures they need, the DB assertions, the edge cases — the plan-side twin of the coverage ledger, written per skills/testing-shape.md before any MDL skills/checkpoints/checkpoint-build.md (the optional-artifacts question), skills/testing-shape.md, skills/journey-proof.md, skills/fixture-seeding.md (Stage-5 readers), bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin -acceptance-criteria 4 architecture/acceptance-criteria.md|docs/acceptance-criteria.md Per module: what "done" means beyond CE-error-free — the Stage-4 "User defines" row of conversion-runbook.md §2, written down instead of held in chat; each criterion names the journey or check that proves it conversion-runbook.md §2 Stage 4 "User defines" row, skills/module-brief.md (the brief's Done section is where these land per module), skills/module-review.md (the confirm step reads them), bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin -demo-script 5 docs/demo-script.md|docs/demo/script.md The narrated walk-through a human will give — beats, pages, fixtures on screen, what the audience must see happen; written at the Stage-5 open so the build front-loads what the demo needs skills/record-demo-video.md (its input), skills/handoff-to-studio-pro.md §8 (demo data the script depends on), bin/lib/closeout.sh migration,requirements,greenfield,existing-app-change optin +sequence-diagrams 3 architecture/sequence-diagrams.md|architecture/sequence-*.md|architecture/diagrams/sequence*.md Mermaid sequenceDiagram per integration or agent call — caller, Mendix microflow, external system, sync/async, timeout, fallback; the agent-wiring diagram of skills/architecture-blueprint.md Step 3c is one instance skills/checkpoints/checkpoint-architecture.md Q3 agent-wiring half, skills/rest-integration-first-time-right.md (build-time reader for the REST ones), skills/mendix-agents.md, bin/lib/closeout.sh migration,requirements,existing-app-change optin +erd 3 architecture/erd.md|architecture/domain-model.md|architecture/diagrams/erd*.md Mermaid erDiagram of the TARGET domain across modules — entities, associations, ownership per module; the blueprint's layer diagram shows modules, not entities, and .mx-brd.json shows one module at a time skills/checkpoints/checkpoint-architecture.md Q2 (cross-module data strategy — the picture that question is about), skills/modularize-domain.md, bin/lib/closeout.sh migration,requirements,existing-app-change optin +nfr-sheet 3 architecture/nfr.md|architecture/nfrs.md|architecture/non-functional-requirements.md One table: NFR, target, how measured, where in the model it is enforced (XPath, index, batch size, timeout) — the per-NFR expansion of the list CAC-3's open question writes to project-profile.md skills/checkpoints/checkpoint-architecture.md open question (the list), skills/architecture-blueprint.md Step 5 (the register that must not lose them), bin/lib/closeout.sh migration,requirements,existing-app-change optin +integration-contracts 3 architecture/integration-contracts.md|architecture/integrations.md|architecture/integrations/*.md Per integration: endpoint, auth, payload in/out, error handling, owner, test double — written BEFORE the build plan so the plan can sequence it skills/rest-integration-first-time-right.md (reads it first thing at Stage 5), skills/architecture-blueprint.md Step 5 (the integrations register), bin/lib/closeout.sh migration,requirements,existing-app-change optin +test-plan 4 architecture/test-plan.md|docs/test-plan.md Per module: the journeys to prove, the fixtures they need, the DB assertions, the edge cases — the plan-side twin of the coverage ledger, written per skills/testing-shape.md before any MDL skills/checkpoints/checkpoint-build.md (the optional-artifacts question), skills/testing-shape.md, skills/journey-proof.md, skills/fixture-seeding.md (Stage-5 readers), bin/lib/closeout.sh migration,requirements,existing-app-change optin +acceptance-criteria 4 architecture/acceptance-criteria.md|docs/acceptance-criteria.md Per module: what "done" means beyond CE-error-free — the Stage-4 "User defines" row of conversion-runbook.md §2, written down instead of held in chat; each criterion names the journey or check that proves it conversion-runbook.md §2 Stage 4 "User defines" row, skills/module-brief.md (the brief's Done section is where these land per module), skills/module-review.md (the confirm step reads them), bin/lib/closeout.sh migration,requirements,existing-app-change optin +demo-script 5 docs/demo-script.md|docs/demo/script.md The narrated walk-through a human will give — beats, pages, fixtures on screen, what the audience must see happen; written at the Stage-5 open so the build front-loads what the demo needs skills/record-demo-video.md (its input), skills/handoff-to-studio-pro.md §8 (demo data the script depends on), bin/lib/closeout.sh migration,requirements,existing-app-change optin diff --git a/bin/lib/intake-template.sh b/bin/lib/intake-template.sh index f9cc6290..8ce875df 100644 --- a/bin/lib/intake-template.sh +++ b/bin/lib/intake-template.sh @@ -48,14 +48,16 @@ present — is the agent's homework, brought back as "I found X, confirm?" rathe here. Do that homework FIRST: it is what turns each question below into a recommendation with evidence instead of a blank prompt. -## 1. Entry mode: migration, requirements-driven, greenfield, or change an existing app? +## 1. Entry mode: migration, requirements-driven, or change an existing app? _Not yet asked._ The agent proposes with evidence and the user confirms — never a silent inference (conversion-runbook.md "Entry Modes"; classification rules apply in order, first match wins: a live Mendix `.mpr` you are adding to or altering, not rebuilding → change an existing app (record it verbatim as `Change an existing app`; existing-app-change.md); else -any legacy source → migration; else any specs/BRDs/wireframes → requirements-driven; else -greenfield). Auditing or regression-testing an app nobody is changing is not a mode at all — +any legacy source → migration; else specs/BRDs/wireframes, or just an idea for a real app → +requirements-driven, the conversation as the source; an idea for a demo is Q16's POC build. +There is no greenfield mode: retired 2026-11-17, because every mode now designs and plans). +Auditing or regression-testing an app nobody is changing is not a mode at all — that routes to existing-app-assurance.md and skips the pipeline. Getting this wrong skips whole stages: real misrouting, 2026-07-14; and until 2026-09-22 this question listed only three modes, so a session changing a live app had no option to pick. diff --git a/bin/lib/obligations.tsv b/bin/lib/obligations.tsv index 39494b5a..3f6bc207 100644 --- a/bin/lib/obligations.tsv +++ b/bin/lib/obligations.tsv @@ -39,11 +39,12 @@ # 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 +# migration,requirements,existing-app-change (greenfield retired 2026-11-17: an +# unsynced register reads no mode, so every row is owed). 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 +# louder, never quieter. Every row owes all three today (each mode reaches Stage 5 +# and runs the design stage) — 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. @@ -54,11 +55,11 @@ # 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 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 +look review module names design/ui-reviews/ui-review-*.html yes yes 5 skills/module-review.md migration,requirements,existing-app-change +sweep test module path .claude/loop/sweep//sweep.md yes yes 5 skills/wiring-sweep.md migration,requirements,existing-app-change +journeys test module path .claude/loop/verify//summary.tsv no no 5 skills/journey-proof.md migration,requirements,existing-app-change +coherence architect cluster path .claude/loop/coherence/last-cluster-pass.tsv no yes 5 skills/process-coherence-pass.md migration,requirements,existing-app-change +skeleton mdl project path docs/skeleton-proof.md yes no 5 skills/walking-skeleton.md migration,requirements,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 @@ -82,7 +83,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 migration,requirements,greenfield,existing-app-change +workflow-count architect project path architecture/workflow-count.md yes yes 3 skills/workflow-structure-rules.md migration,requirements,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 @@ -114,7 +115,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 migration,requirements,greenfield,existing-app-change +design-reaches-app mdl project path docs/design-reaches-app.md yes yes 5 project-bin/check-design-reaches-app.sh migration,requirements,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 @@ -134,7 +135,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 migration,requirements,greenfield,existing-app-change +fidelity mdl module names docs/PAGE-FIDELITY.tsv no yes 5 skills/ui-loop.md migration,requirements,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". @@ -158,7 +159,7 @@ fidelity mdl module names docs/PAGE-FIDELITY.tsv no yes 5 skills/ui-loop.md migr # ("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 migration,requirements,greenfield,existing-app-change +dispatch mdl module path .claude/loop/dispatch//scripts.tsv no yes 5 skills/agent-roles.md migration,requirements,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 @@ -175,7 +176,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 migration,requirements,greenfield,existing-app-change +final-look review project names design/ui-reviews/final-look-*.html yes yes 6 skills/module-review.md migration,requirements,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 @@ -198,7 +199,7 @@ 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 migration,requirements,greenfield,existing-app-change +prototype-look review project names design/ui-reviews/prototype-look-*.html yes yes 3 skills/design-artifacts.md migration,requirements,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 @@ -216,4 +217,4 @@ prototype-look review project names design/ui-reviews/prototype-look-*.html yes # 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 +must-haves review module path docs/progress/must-haves/.md yes yes 5 skills/must-haves.md migration,requirements,existing-app-change diff --git a/bin/lib/resume-template.sh b/bin/lib/resume-template.sh index bdef30ca..4b57c29d 100644 --- a/bin/lib/resume-template.sh +++ b/bin/lib/resume-template.sh @@ -59,7 +59,8 @@ never this file; a READY line it did not write FAILs Stage 6 and CI. That verdict, not this file, is the answer to "where are we". 2. **If it reports Stage P:** run the kickoff interview against \`intake.md\`. Ask Q16 (which kind of build) FIRST; on POC follow \`$toolkit/skills/poc-build.md\` and do not ask the rest. Otherwise - Q1 is the entry mode (migration / requirements-driven / greenfield) and it decides everything after. + Q1 is the entry mode (migration / requirements-driven / change an existing app; an idea for a real + app is requirements-driven, a demo is the POC build) and it decides everything after. Every question is asked in chat and the turn then ENDS and waits — \`$toolkit/skills/interview-protocol.md\` §3. Record each answer in \`PROJECT.md\` as \`CONFIRMED\` or \`ASSUMED\`. diff --git a/bin/lib/triage-template.sh b/bin/lib/triage-template.sh index cfd20ba0..3d0f3cfb 100644 --- a/bin/lib/triage-template.sh +++ b/bin/lib/triage-template.sh @@ -70,8 +70,8 @@ codebase. What varies by mode: from, not what is in the folder. The Business Capability Map and the Recommended Scope Subset **still apply and still matter** — a document corpus has capabilities and a slice order exactly like a codebase does. Run `bin/source-sufficiency.sh` over the corpus. -- **Greenfield** — mark the extraction rows *and* the coverage matrix `N/A`. The scope subset is - still the deliverable. +- **Requirements-driven from a conversation (no corpus)** — mark the extraction rows *and* the + coverage matrix `N/A`. The scope subset is still the deliverable. **Documents plus a database schema is not a documents-only source.** A table schema, an ORM model or an OpenAPI contract is extractable structure and grades as such, whatever the markdown around diff --git a/bin/status.sh b/bin/status.sh index 34cf1352..f6ff4ffd 100755 --- a/bin/status.sh +++ b/bin/status.sh @@ -78,6 +78,7 @@ ENTRY="$(entry_mode_token "$ENTRY_RAW" 2>/dev/null)" POS_ENTRY=""; POS_BANNER="" if declare -F mxtk_pos_read >/dev/null; then mxtk_pos_read "$PROJECT_DIR"; mxtk_pos_undeclared && POS_BANNER="${MXTK_POS_BANNER:-}" + [ "$POS_ENTRY" = greenfield-retired ] && POS_BANNER="${MXTK_POS_RETIRED//$PROJECT_DIR}" fi ADOPTED="$(grep -m1 -oE '^Adopted at stage: *[0-9P]+' "$REG" | sed 's/^Adopted at stage: *//')" SKELETON="$(grep -m1 -oE '^Skeleton proven [0-9-]+' "$REG" | sed 's/^Skeleton proven //')" @@ -257,6 +258,7 @@ fi next_action() { if [ -n "$APPROVED_OVER" ]; then echo "$APPROVED_OVER is approved in PROJECT.md but its gate FAILS — fix the gate, or re-open the approval with the user (bin/gate-check.sh)"; return; fi # conversion-runbook.md §2 if [ "$N_ATTN" -gt 0 ]; then echo "fix what gate-check flags: $(printf '%s\n' "$NEED_ATTN" | head -1)"; return; fi # conversion-runbook.md §2 + if [ "$POS_ENTRY" = greenfield-retired ]; then echo "bin/sync-project.sh $PROJECT_DIR — Entry mode greenfield is retired and maps to requirements-driven (conversion-runbook.md → Entry Modes)"; return; fi if [ -n "$POS_BANNER" ]; then echo "declare the entry mode (intake Q1, kickoff) or adopt a stage: bin/gate-check.sh $PROJECT_DIR --adopt --reason \"...\""; return; fi # conversion-runbook.md → Entry Modes case "$STAGE_LINE" in *"Stage 5"*|*"Stage 6"*|*"Stage 7"*) if [ -z "$SKELETON" ]; then echo "run the walking skeleton before the first module (skills/walking-skeleton.md)"; return; fi ;; # walking-skeleton.md diff --git a/bin/sync-project.sh b/bin/sync-project.sh index bedd570f..95bdb83a 100755 --- a/bin/sync-project.sh +++ b/bin/sync-project.sh @@ -835,6 +835,41 @@ if [ -f "$PROJECT_DIR/PROJECT.md" ] && [ -n "$(mxtk_register_missing "$PROJECT_D echo "⚠ ${DRY:-}Updated: PROJECT.md had no decision-register structure — appended: $_reg_added (bin/lib/register-skeleton.sh). Review them: the ✋ gates read the Decisions table." CHANGES=$((CHANGES + 1)) fi +# --- 2b0a. Entry mode greenfield was RETIRED (2026-11-17, conversion-runbook.md → Entry Modes, +# "Two doors"): a real app from an idea is requirements-driven with the conversation as the +# source; a demo is Build type: poc. The register line is mapped to requirements-driven, the +# old line kept as a comment, and the project adopted at the stage its readout shows (stages it +# already passed or skipped as greenfield are not re-owed) through gate-check.sh --adopt, so the +# same rules apply: register line, BUILD-LOG row, and under Interview mode: auto a ✋ +# human-pending decision for an adoption past Stage 3 or 4. Said once, here. Read-only on +# anything but PROJECT.md and docs/BUILD-LOG.md. An intake-only "greenfield" answer is not +# rewritten (it is the user's answer): gate-check and status say to re-answer it. +. "$SCRIPT_DIR/lib/entry-mode.sh" +if [ -f "$PROJECT_DIR/PROJECT.md" ]; then + _gf_line="$(awk ' + //) c = 0; next } + { l = $0; gsub(/^[ \t>*_-]+/, "", l); gsub(/\*/, "", l) + if (tolower(l) ~ /^entry mode[ \t]*:/) { print NR "\t" $0; exit } }' "$PROJECT_DIR/PROJECT.md")" + if [ -n "$_gf_line" ] && _gf_v="${_gf_line#* }" && [ "$(entry_mode_token "${_gf_v#*:}" 2>/dev/null)" = greenfield-retired ]; then + mxtk_pos_read "$PROJECT_DIR" + _gf_n="${_gf_line%% *}"; _gf_old="${_gf_line#* }"; _gf_at="" + case "$POS_ADOPTED" in "") case "$POS_READOUT" in [1-7]) _gf_at="$POS_READOUT" ;; esac ;; esac + echo "⚠ ${DRY:-}Mapped: PROJECT.md Entry mode greenfield → requirements-driven (greenfield retired, mapped at sync)${_gf_at:+; adopted at stage $_gf_at, its current stage}. Stages before the adoption point are not re-owed; from here the requirements-driven steps apply (conversion-runbook.md → Entry Modes)." + if [ "$DRY_RUN" -ne 1 ]; then + _gf_tmp="$(mktemp "${TMPDIR:-/tmp}/sync-gf.XXXXXX")" + awk -v n="$_gf_n" -v d="$(date -u +%Y-%m-%d)" ' + NR == n { print "Entry mode: requirements-driven"; gsub(/--/, "-", $0) + print ""; next } { print }' \ + "$PROJECT_DIR/PROJECT.md" > "$_gf_tmp" && cat "$_gf_tmp" > "$PROJECT_DIR/PROJECT.md"; rm -f "$_gf_tmp" + mkdir -p "$PROJECT_DIR/docs" + printf '%s ENTRY-MODE-MAPPED greenfield -> requirements-driven: greenfield retired, mapped at sync%s\n' \ + "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "${_gf_at:+ (adopted at stage $_gf_at)}" >> "$PROJECT_DIR/docs/BUILD-LOG.md" + [ -n "$_gf_at" ] && "$SCRIPT_DIR/gate-check.sh" "$PROJECT_DIR" --adopt "$_gf_at" --reason "greenfield retired, mapped at sync" 2>&1 \ + | grep -E '^(Recorded in|✋)' | sed 's/^/ /' || true + fi + CHANGES=$((CHANGES + 1)) + fi +fi if [ -f "$PROJECT_DIR/PROJECT.md" ] && ! grep -q "Toolkit commit:" "$PROJECT_DIR/PROJECT.md"; then printf '\nToolkit commit: (set at session start — see CLAUDE.local.md ritual)\n' | w_app "$PROJECT_DIR/PROJECT.md" echo "Updated: PROJECT.md — added the Toolkit commit acknowledgement line." diff --git a/docs/pipeline-walks.html b/docs/pipeline-walks.html index da14e045..c9d6b1a5 100644 --- a/docs/pipeline-walks.html +++ b/docs/pipeline-walks.html @@ -84,7 +84,7 @@

Pipeline Walks

Shared spine Migration Requirements-driven - Greenfield + Just an idea Change an existing app À-la-carte assurance Stage 5 module loop @@ -214,33 +214,9 @@

Requirements-driven Specs, BRDs, work
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 a design front end (poc-build.md steps 1 to 4: design questions, wireframes or the supplied prototype, a buildability check, one approval stop) and a short plan, then the normal build. 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
+ +

Just an idea Two doors: a real app, or a demo

+

There is no greenfield mode any more: every mode designs and plans. An idea for a real app is requirements-driven with the conversation as the source: Stages 1 and 2 run as a short interview that writes the BRDs, then Stages 3 to 6 run as in the requirements-driven walk above (the small-project tier and Pipeline mode: high-speed keep it light). An idea for a demo is Build type: poc, answered at kickoff, and follows skills/poc-build.md. A POC that becomes a real app hands its hand-over to a requirements-driven build, or starts a change to the existing app. An old register that still says greenfield is mapped by bin/sync-project.sh.

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

diff --git a/project-bin/_position.sh b/project-bin/_position.sh index 7732b132..bc6330f8 100755 --- a/project-bin/_position.sh +++ b/project-bin/_position.sh @@ -22,7 +22,8 @@ # quieter. # entry_mode_token -> canonical token on stdout, "" if unrecognised. -# Canonical set: greenfield | requirements-driven | migration | existing-app-change | a-la-carte +# Canonical set: requirements-driven | migration | existing-app-change | a-la-carte, plus +# greenfield-retired (a register sync-project.sh has not yet mapped) entry_mode_token() { _mxtk_emt "${1-}"; echo "$_EMT"; } # _mxtk_emt — the tokeniser itself; sets _EMT instead of printing, so exec.sh's reader @@ -57,7 +58,10 @@ _mxtk_emt() { [[ "$v" =~ ^[*_]*(.*)$ ]] && v="${BASH_REMATCH[1]}" if [[ "$v" =~ ^(.*[^.:!*_-])[.:!*_-]*$ ]]; then v="${BASH_REMATCH[1]}"; else v=""; fi local tok="" known=1 - if [[ "$v" == greenfield ]]; then tok="greenfield" + # greenfield was RETIRED on 2026-11-17 (conversion-runbook.md → Entry Modes, "Two doors"): + # it reads as its own token so every caller can say "run sync" instead of either honouring it + # or dropping it in silence. sync-project.sh maps it to requirements-driven. + if [[ "$v" == greenfield ]]; then tok="greenfield-retired" elif [[ "$v" == requirements-driven || "$v" == requirements || "$v" == requirement ]]; then tok="requirements-driven" elif [[ "$v" == migration ]]; then tok="migration" elif [[ "$v" == existing-app-change || "$v" == existing-app || "$v" == existing ]]; then tok="existing-app-change" @@ -142,6 +146,7 @@ mxtk_pos_read() { # The banner (conversion-runbook.md → Entry Modes). One sentence, printed by status.sh, # gate-check.sh's summary and every exec.sh run while the register declares no position. +MXTK_POS_RETIRED='Entry mode greenfield is retired: run bin/sync-project.sh (maps the register line to requirements-driven, adopted at the current stage), or re-answer intake Q1 — Build type: poc for a demo.' MXTK_POS_BANNER='No entry mode declared: the toolkit treats this project as Stage P, not started. Declare the mode (kickoff) or adopt a stage with a reason: gate-check.sh --adopt --reason ...' # mxtk_pos_undeclared — true when nothing in the register (or intake) says where the project is. diff --git a/project-bin/exec.sh b/project-bin/exec.sh index 99de67d8..dcef987a 100755 --- a/project-bin/exec.sh +++ b/project-bin/exec.sh @@ -778,12 +778,24 @@ take_score() { # "no plan" in its BUILD-LOG row, and no second refusal ever comes on that clone; # - under `Interview mode: auto` there is no refuse-once: see the auto branch below; # - never refused: --patch (opaque repair; doctor.sh's recovery path), `Build type: poc`, -# greenfield, change-an-existing-app, a-la-carte, and no declared mode at all. +# change-an-existing-app, a-la-carte, and no declared mode at all (greenfield, retired +# 2026-11-17, prints its own "run sync" line and is not refused either). POS_NOTE="" if [ -f "$_XD/_position.sh" ]; then . "$_XD/_position.sh" mxtk_pos_read "$PROJECT_ROOT" - if mxtk_pos_undeclared; then + # A retired `Entry mode: greenfield` (never synced) says "run sync" — and under Interview mode: + # auto it is held to the requirements-driven plan rule below, or an unattended agent could + # write that one line, or skip sync, and build with no plan (review of #792). The remedy is + # sync-project.sh or the --adopt it performs, neither of which runs through here (guard rule 7). + if [ "$POS_ENTRY" = greenfield-retired ]; then + echo "⚠ ${MXTK_POS_RETIRED//$PROJECT_ROOT}" + POS_NOTE="entry mode greenfield retired, not synced" + [ "$POS_AUTO" = 1 ] && POS_ENTRY=requirements-driven + fi + if [ "$POS_ENTRY" = greenfield-retired ]; then + : + elif mxtk_pos_undeclared; then echo "⚠ $MXTK_POS_BANNER" POS_NOTE="no entry mode declared" elif [ "$PATCH_MODE" != "1" ] && [ "$POS_BUILD" != poc ] && [ "$POS_AUTO" = 1 ] \ diff --git a/project-bin/progress-report.py b/project-bin/progress-report.py index 7f64b779..74c51c01 100755 --- a/project-bin/progress-report.py +++ b/project-bin/progress-report.py @@ -196,7 +196,7 @@ def load_project(proj): "status": st.group(0).lower() if st else "unknown", "status_txt": c[7], "closed": c[8] if len(c) > 8 else ""}) m = re.search(r"Entry mode:\s*\**\s*(\w[\w-]*)", md) em = (m.group(1).lower() if m else "migration") - info["entry_mode"] = "requirements" if em.startswith("requirements") else "existing-app-change" if em.startswith("existing") else em + info["entry_mode"] = "requirements" if em.startswith(("requirements", "greenfield")) else "existing-app-change" if em.startswith("existing") else em info["waived"] = set(re.findall(r"Waived artifact\s+([\w-]+)\s*:", md)) info["waived_stages"] = set(re.findall(r"(?im)^[\s>*_-]*Waived stage\s+([P0-7])\s*\**\s*:", md)) for agg in re.findall(r"(?im)^[\s>*_-]*Waived stages\s*\**\s*:\s*([^\n]*)", md): @@ -1858,7 +1858,6 @@ def skip_reason(s, info, gate): if s in info.get("waived_stages", ()) or gate["rows"].get(s, {}).get("status") == "WAIVED": return "waived in the decision register" ad = info.get("adopted_at") if ad and s != "P" and STAGES.index(s) < STAGES.index(ad): return "this project joined the toolkit at stage %s, so it happened before" % ad - if info.get("entry_mode") == "greenfield" and s in "1234": return "greenfield entry mode collapses stages 1 to 4 into the plan the user already has" return "" def ago(t): diff --git a/skills/agent-roles.md b/skills/agent-roles.md index d4dad075..aa29eb31 100644 --- a/skills/agent-roles.md +++ b/skills/agent-roles.md @@ -130,4 +130,4 @@ module briefs, just-in-time, module N after N−1 gates); having BRDs does not m - **Don't let gate-agent or test-agent run `mxcli exec`, ever** — they exist specifically to check work the main session already committed. - **Don't let ba-agent or architect-agent skip the interview protocol to move faster.** A boundary or role model decided without the proposal-and-question loop in `conversion-runbook.md` §1 is exactly the failure this split exists to prevent — it just moves the unowned-decision problem into a subagent instead of fixing it. - **Don't copy the template shapes (`agents/README.md`) verbatim into a new project.** A gate-agent checking the wrong `.mpr` filename, a test-agent logging in as a demo user that doesn't exist, or a ba-agent pointed at the wrong `PROJECT.md` path will report false confidence instead of failing loudly. -- **Scaffold all six on day one; don't *complete* an agent before its stage starts.** The stubs are inert (refuse-to-run while placeholders remain), so having all six in `.claude/agents/` from kickoff is safe and avoids the "where's my mdl-agent?" confusion. The discipline moves to completion time: fill ba/architect at Stage P, mdl/gate/test/review at Stage 5 kickoff — completing a gate-agent before any build exists means filling its commands from guesses, which is exactly the false-confidence failure the placeholders exist to prevent. (A greenfield build starting at Stage 5 may simply never complete ba/architect — that's fine, they stay inert.) +- **Scaffold all six on day one; don't *complete* an agent before its stage starts.** The stubs are inert (refuse-to-run while placeholders remain), so having all six in `.claude/agents/` from kickoff is safe and avoids the "where's my mdl-agent?" confusion. The discipline moves to completion time: fill ba/architect at Stage P, mdl/gate/test/review at Stage 5 kickoff — completing a gate-agent before any build exists means filling its commands from guesses, which is exactly the false-confidence failure the placeholders exist to prevent. (A build adopted at Stage 5 may simply never complete ba/architect — that's fine, they stay inert.) diff --git a/skills/bootstrap-project.md b/skills/bootstrap-project.md index d5c8bf7f..6ae67d51 100644 --- a/skills/bootstrap-project.md +++ b/skills/bootstrap-project.md @@ -8,7 +8,7 @@ ## When to Use This Skill -- Starting a brand-new mxcli-powered project (migration or greenfield) and setting up its `CLAUDE.md` for the first time +- Starting a brand-new mxcli-powered project (migration, requirements-driven or POC) and setting up its `CLAUDE.md` for the first time - Auditing an existing project's `CLAUDE.md` against the toolkit's current Baseline routing (run this whenever the toolkit's `git pull` brings in a newly-baseline-worthy skill) - Someone says "review the toolkit and build the CLAUDE.md" — that instruction alone is not enough; this skill is what makes it repeatable instead of improvised @@ -31,7 +31,7 @@ None of these live in the toolkit. Ask the user or check the project directly; d | Fact | Why it matters | How to check | |---|---|---| | **mxcli invocation style** | Global binary (`mxcli`) vs. project-local (`./mxcli`) — get this wrong and every command in `CLAUDE.md` is wrong | `which mxcli`; check for a binary committed in the project root | -| **Source platform / stack** | Decides which situational skills apply (`source-os11.md` vs `source-node-express-react.md` vs `pipelines/java-angular/` vs none, if greenfield) | Ask the user, or run `source-triage.md` Step 1 if a migration is already underway | +| **Source platform / stack** | Decides which situational skills apply (`source-os11.md` vs `source-node-express-react.md` vs `pipelines/java-angular/` vs none, if no legacy source) | Ask the user, or run `source-triage.md` Step 1 if a migration is already underway | | **mxbuild / Studio Pro setup** | Whether `mx check` needs `mxcli setup mxbuild` first, and which Studio Pro version | `mxcli setup mxbuild --help`, check `~/.mxcli/mxbuild/` | | **Communication style preferences** | E.g. "never show raw MDL in chat, describe changes in plain language then execute silently" — genuinely project/client-specific, never assume the default | Ask the user directly | | **Migration-input location** (migrations only) | Where BRDs/architecture docs from an upstream analysis project live | Ask the user; this is almost never the toolkit's own `pipelines/` output location | @@ -83,7 +83,7 @@ From the toolkit's `README.md` "When to use which skill" table, include only the - **Oracle Forms source** → mxcli's bundled `.ai-context/skills/migrate-oracle-forms/SKILL.md` — directory-shaped since mxcli v0.20.0, flat `migrate-oracle-forms.md` on older installs (the toolkit owns no Forms extractor; the bundled skill is canonical) - **K2 / Nintex workflow source** → mxcli's bundled `.ai-context/skills/migrate-k2-nintex/SKILL.md`, same shape note (server/database-stored, not file-based — extraction means the K2 DB or SmartObject APIs, so expect no XML-style extractor) - **Any migration, regardless of source** → `migration-pipeline.md`, `source-triage.md` (also Baseline, but worth restating in context), `brd-generation.md`, `brd-validation.md`, `modularize-domain.md`, `architecture-blueprint.md`, `design-artifacts.md`, `brd-to-build-plan.md`, `iterative-build-loop.md` -- **Greenfield (no source migration at all)** → likely none of the migration-pipeline rows; the project probably only needs Baseline plus mxcli's own bundled `.ai-context/skills/` (which this toolkit doesn't own or duplicate) +- **No legacy source (requirements-driven or POC)** → likely none of the migration-pipeline rows; the project probably only needs Baseline plus mxcli's own bundled `.ai-context/skills/` (which this toolkit doesn't own or duplicate) Don't include a row "just in case" — an unused situational row is noise the same way an over-annotated microflow is noise (see `learned-microflow-patterns.md`). diff --git a/skills/change-intake-detail.md b/skills/change-intake-detail.md index 80beed98..69410b16 100644 --- a/skills/change-intake-detail.md +++ b/skills/change-intake-detail.md @@ -1,6 +1,6 @@ # Change Intake — Detail: Why, Worked Example, Apply, Prove, Gate Check -**Applies to:** any mxcli project with a `PROJECT.md` (migration, requirements-driven, greenfield, change an existing app), from Stage 2 onward. +**Applies to:** any mxcli project with a `PROJECT.md` (migration, requirements-driven, POC, change an existing app), from Stage 2 onward. **Purpose:** the on-demand half of `change-intake.md`. That file is the baseline core every lead and ba-agent session reads. Read this one to apply or prove a change request, when a class, size or status is unclear, or to explain the `Change log:` gate line. **Owns:** nothing: `change-intake.md` owns the `## Change log` table and the classes, sizes and statuses. `conversion-runbook.md` §3b (drift-sync) is this loop's BRD-flush step. diff --git a/skills/cloud-dev-environment.md b/skills/cloud-dev-environment.md index 4a64fe27..6e57f1ba 100644 --- a/skills/cloud-dev-environment.md +++ b/skills/cloud-dev-environment.md @@ -1,6 +1,6 @@ # Cloud development environment — setup and loop -**Applies to:** any mxcli project | migration | requirements-driven | greenfield — whenever the +**Applies to:** any mxcli project | migration | requirements-driven | POC — whenever the work happens in an **ephemeral cloud container** (Claude Code on the web/mobile, a devcontainer, a CI runner) instead of a local machine with Studio Pro. diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index ea99ac0f..b13572c3 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -71,11 +71,11 @@ The stages are the same for everyone; what differs is where you enter and which 1. **The app you are changing already exists in Mendix and stays** — a live `.mpr` you are adding to or altering, not rebuilding → **Change an existing app** (`existing-app-change.md`). The knowledge base comes from the model itself (Path D), stages 2–4 run over the slice being changed, and every gate from Stage 5 on is also a regression gate. Auditing or testing an app nobody is changing is not this mode — that is à-la-carte `existing-app-assurance.md`, no pipeline; with a `PROJECT.md`, record `Entry mode: a-la-carte` (no pipeline: audit or tooling use). 2. **Any legacy/source code exists** (even a reference implementation you're not "migrating" — if it encodes behavior you want, it gets analyzed) → **Migration** (or at minimum, Stage 1 Path A runs on it). 3. **Any requirements artifacts exist** — specs, BRDs, context docs, wireframes, workshop outputs → **Requirements-driven**. Having "complete" specs does *not* mean skipping to Stage 5: stages 2–4 are where those specs become validated BRDs, an architecture, module boundaries, a design system, and an ordered plan. Skipping them means improvising all of that mid-build. -4. **None of the above** — you're genuinely starting from a conversation → **Greenfield**. This is the narrowest mode, not the default for "no legacy system." +4. **None of the above — an idea.** Two doors, no third: a demo or proof of concept → **`Build type: poc`** (`poc-build.md`); a real app → **Requirements-driven, with the conversation as the source** — Stages 1–2 run as a short interview that writes the BRDs (`brd-generation.md`, by hand or from the SME), then 3–6 as for any requirements-driven project; `small-project-tier.md` and `Pipeline mode: high-speed` keep it light. No mode skips design and planning. A POC that becomes a real app hands over its hand-over (`poc-build.md` step 9) as the requirements source of a requirements-driven build, or starts `existing-app-change.md` — this is the one statement of that rule. (`greenfield` was retired 2026-11-17; `sync-project.sh` maps an old register line to requirements-driven, adopted at its current stage.) -(Failure: a project with full specs + analyzable source was classified greenfield "because there's nothing to migrate" and proposed skipping 0–4 — `process/baseline-incident-history.md` §R1.) +(Failure: a project with full specs + analyzable source was classified greenfield "because there's nothing to migrate" and proposed skipping 0–4 — `process/baseline-incident-history.md` §R1. Retiring greenfield removes that door: no classification skips 1–4 any more.) -**Declared, or the toolkit says so.** With no `Entry mode:` and no `Adopted at stage:` line, `bin/status.sh`, `bin/gate-check.sh`'s summary and every `bin/exec.sh` run print one banner: *No entry mode declared: the toolkit treats this project as Stage P, not started.* **Plan before build:** in `migration` or `requirements-driven`, the first `exec.sh` model write before Stage 4 has passed or been adopted is refused — once ever per clone, every later write goes on tagged "no plan" — run stages 1–4, or `bin/gate-check.sh

--adopt 5 --reason "..."` (a register line). A build plan plus a module brief, `Waived stage 4:` or adoption at 5+ clears it; never refused: `a-la-carte`, `greenfield`, `Build type: poc`, change an existing app, `--patch`. Under `Interview mode: auto` there is no refuse-once: every write waits for `build-ready` to pass, and an `--adopt` past Stage 3 or 4 is recorded as a ✋ human-pending decision (Stage 6 FAILs until a person confirms it). Unattended kick-off text: `CONVERSION-RUNBOOK.md` → "Running unattended". +**Declared, or the toolkit says so.** With no `Entry mode:` and no `Adopted at stage:` line, `bin/status.sh`, `bin/gate-check.sh`'s summary and every `bin/exec.sh` run print one banner: *No entry mode declared: the toolkit treats this project as Stage P, not started.* **Plan before build:** in `migration` or `requirements-driven`, the first `exec.sh` model write before Stage 4 has passed or been adopted is refused — once ever per clone, every later write goes on tagged "no plan" — run stages 1–4, or `bin/gate-check.sh

--adopt 5 --reason "..."` (a register line). A build plan plus a module brief, `Waived stage 4:` or adoption at 5+ clears it; never refused: `a-la-carte`, `Build type: poc`, change an existing app, `--patch`. Under `Interview mode: auto` there is no refuse-once: every write waits for `build-ready` to pass, and an `--adopt` past Stage 3 or 4 is recorded as a ✋ human-pending decision (Stage 6 FAILs until a person confirms it). Unattended kick-off text: `CONVERSION-RUNBOOK.md` → "Running unattended". **Mode changes are decisions — the single source of this rule.** Each mode (Entry mode + Build type) is a contract: its steps are the rows `bin/lib/artifact-manifest.tsv` lists for it; a step the mode drops reads "not owed (mode)", never PASS. Switching mode after kickoff needs the user to say so, is recorded in `PROJECT.md` as a decision (under auto: ✋ human-pending), and never happens because a step was hard. *Failure: a Stage 5 project whose user mentioned a demo dropped its gates.* *Failure (two field runs, 2026-11): a full frozen spec plus clickable prototypes, "requirements-driven" in the brief, and ~78 pages built with no plan or wireframe target, missing whole sections the prototypes showed; nothing spoke, because nothing was declared.* @@ -83,7 +83,7 @@ The stages are the same for everyone; what differs is where you enter and which |---|---|---|---| | **Legacy source code** (± docs, ± SME) | **Migration** | P, 0–7 (all) | The default everything below describes. Path A (code extractors) always runs. | | **Requirements only** — BRDs, specs, workshop outputs, wireframes; no legacy code | **Requirements-driven** | P, 0–6 (skip 7) | Stage 0 runs. `document-discovery.md` runs over the whole corpus for the inventory, **and** the extraction call runs per extractable structure inside it — a schema, a table dump, a data export or entity tables in a spec each get one; `N/A` is earned on evidence, never on the mode label (`source-triage.md` owns that rule — see "Stage 0 runs in every entry mode" below). Stage 1 runs Path B (`kb-generation.md`) + Path C (SME) only; Path A is declared not-applicable, not "skipped". Stages 2–6 run unchanged — BRDs come from documents instead of extraction; supplied prototypes are adopted, not redrawn (`design-artifacts.md` Step 2a). Stage 7 only if legacy data exists somewhere to cut over. **A text-native corpus — Markdown and HTML pages, no legacy code, no Office/PDF containers — takes the docs-ready fast path below.** | -| **Just an idea / a running start on the model** | **Greenfield** | P (light), 0 (scope only), design front end, 5–6 | Stages 1–4 collapse to a **design front end**: `poc-build.md` steps 1–4 (design questions; wireframes, or the supplied prototype as the wireframe set; buildability check; one approval stop, recorded as the Stage-4 `CONFIRMED` decision), then a short `architecture/build-plan.md` — apps, modules, screen list, and a `## Module brief — ` of a few lines per module — then the normal build. Stage 0 does **not** collapse: with no corpus there is nothing to grade, but the scope conversation is exactly as load-bearing as it is anywhere else, so Stage 0 reduces to CAC-1's brainstorm and its sign-off. If you find yourself inventing requirements mid-build, you're actually in requirements-driven mode — back up to Stage 2. | +| **Just an idea** | **Requirements-driven, conversation as the source** (a real app) — or **`Build type: poc`** (a demo) | P, 0–6 — or `poc-build.md` steps 1–9 | Rule 4 above. Stage 0 has no corpus to grade, so it reduces to CAC-1's brainstorm and its sign-off; Stages 1–2 are the interview that writes the BRDs; Stage 3 is the design front end (questions, wireframes or a supplied prototype, buildability, one approval stop) and Stage 4 the plan with a few lines of brief per module. | | **A live Mendix app you are changing** — a feature or flow is being added or altered, the rest stays as it is | **Change an existing app** | P, 0–6 per change (skip 7 — the app is live) | `existing-app-change.md` owns the mode. Stage 1 runs **Path D** — `mxcli` queries the `.mpr` into the knowledge base, scoped to the change **plus what it touches**, which Stage 0 writes into `triage.md` as its own section. A regression net (Track B baseline) goes under the app before anything changes. Stages 2–4 run over the change only: one as-is/to-be BRD per capability being changed, Stage 3 in full only when the change crosses a module boundary, adds an integration or alters the domain model — otherwise it collapses to "which existing module owns this". Stage 7 is N/A in the register with that reason. The coverage ledger is `mxcli brain plan`, not a hand-kept file. | ### Stage 0 runs in every entry mode @@ -99,7 +99,7 @@ So: **no entry mode may skip Stage 0, because no entry mode may skip the scope c What varies is how much of the stage is applicable, and inapplicability is *recorded*, never inferred: -| Stage 0 component | Migration | Requirements-driven | Greenfield | +| Stage 0 component | Migration | Requirements-driven | Requirements-driven, conversation as the source | |---|---|---|---| | Source inventory + sufficiency grade (`bin/source-sufficiency.sh`) | runs | runs — over the requirements corpus | N/A (no corpus) | | Reuse-vs-build-new extraction call (`source-triage.md`) | runs | **runs per extractable structure in the corpus** — `N/A` only when there is none, on evidence. `source-triage.md` owns this rule; don't decide it from the mode label | **N/A** — record the reason | @@ -146,7 +146,7 @@ Declared, never inferred from a thin sources folder. ## When to Use This Skill -- Starting any conversion (legacy source → Mendix), requirements-driven build, or greenfield mxcli build. +- Starting any conversion (legacy source → Mendix), requirements-driven build (from documents or from a conversation), or POC. - You're not sure whether a stage is "done" — check its gate row in §2, not your own sense of completion. - A decision got made without the user's sign-off and it's now biting — that's this skill's gate being skipped, not a one-off mistake. Fix the gate, don't just redo the decision. @@ -571,7 +571,7 @@ late against the BRD set you already have. |---|---| | **User defines** | Confirms business rules the code implies. Answers `openQuestions` (via SME). Narrative is never invented. | | **Agent produces** | BRD scaffolds → enrichment from `KB.md` → validation. `F{NNN}.brd.json`. Many questions: draft `process-map.md` (pass 1). | -| **Surface** | `analysis/brd-report.html` — `bin/brd-report.sh `. Opens with the pass-1 process map; requirements and open questions are listed under it, a click on a step shows that step's rows (this page replaced `docs/open-questions.html`). One renderer for every entry mode: it reads BRDs, not source, so a requirements-driven or greenfield project gets the same surface as a migration, and so does a BRD no extractor produced. Each section carries a `report-schema.md` verdict, so a section that is empty because this kind of BRD has nothing to put there reads differently from one that is empty because something broke. History: `process/baseline-incident-history.md` §R20. | +| **Surface** | `analysis/brd-report.html` — `bin/brd-report.sh `. Opens with the pass-1 process map; requirements and open questions are listed under it, a click on a step shows that step's rows (this page replaced `docs/open-questions.html`). One renderer for every entry mode: it reads BRDs, not source, so a requirements-driven project — from documents or a conversation — gets the same surface as a migration, and so does a BRD no extractor produced. Each section carries a `report-schema.md` verdict, so a section that is empty because this kind of BRD has nothing to put there reads differently from one that is empty because something broke. History: `process/baseline-incident-history.md` §R20. | | **Gate** | Every BRD validation-clean; `validation-report.md` has 0 issues; **every `openQuestions` entry raised in chat** — `bin/open-questions.sh --stage 2` reports 0 blocking, which `gate-check.sh` enforces. Close-out block pasted (§1b rule 7) — CAC-3 opens with it. "Chased to closure" was the old wording and it was unenforceable: a question logged with a self-answer read as closed. | | **Owner** | `ba-agent` | @@ -609,7 +609,7 @@ The biggest gap before this runbook existed. Module boundaries, wiring diagrams **Stage 5 opens with the walking skeleton — every entry mode, before the first module** (`walking-skeleton.md`): one entity, one microflow, one page, one nav item, one demo user, one journey, one screenshot, proven in the running app. It is the proof that exec, mxbuild, run, look and test all work on this machine and this app; the register line `Skeleton proven : …` is what `gate-check.sh` reads. A build that skipped it once ran 27 scripts against a build gate that could not execute and never ran a test. -**Not migration-specific.** This is the standard Mendix build discipline — greenfield builds start here. Already well codified: layer1 (entities/associations/enums, `security-setup.mdl` last) → layer2 (microflows) → layer3 (pages); the guard chain (uncommitted → SP-open → concurrent-writer → snapshot → exec → mxbuild gate → auto-restore → manual SP reopen); the stale-build protocol; the STOP conditions in `learned-mdl-preflight.md`. +**Not migration-specific.** This is the standard Mendix build discipline — a new app's builds start here. Already well codified: layer1 (entities/associations/enums, `security-setup.mdl` last) → layer2 (microflows) → layer3 (pages); the guard chain (uncommitted → SP-open → concurrent-writer → snapshot → exec → mxbuild gate → auto-restore → manual SP reopen); the stale-build protocol; the STOP conditions in `learned-mdl-preflight.md`. | | | |---|---| @@ -680,7 +680,7 @@ cited as evidence.* ### Stage 7 — Cutover -Migration-specific — greenfield builds have no legacy system to cut over from and skip this stage. Runs **after** Stage 6, deliberately: don't migrate real production data and flip users onto an app that hasn't passed its E2E gate yet. +Migration-specific — a new app has no legacy system to cut over from and skips this stage. Runs **after** Stage 6, deliberately: don't migrate real production data and flip users onto an app that hasn't passed its E2E gate yet. | | | |---|---| diff --git a/skills/design-artifacts.md b/skills/design-artifacts.md index 2ae3add5..d2e19c1b 100644 --- a/skills/design-artifacts.md +++ b/skills/design-artifacts.md @@ -227,7 +227,7 @@ table against `design/wireframes/*.html` and reports `MANUAL wireframes ### Step 2a: Adopt a supplied design — map, do not redraw **Trigger:** the corpus supplies clickable HTML prototypes or a design system (requirements-driven -or migration; greenfield and POC use `poc-build.md` steps 1–4 instead). The prototype is the +or migration; a POC uses `poc-build.md` steps 1–4 instead). The prototype is the target; Stage 3 maps it rather than drawing a second, drifting copy. 1. Screen Inventory rows (Step 2) get Basis `SUPPLIED` and the file in Notes. diff --git a/skills/existing-app-change.md b/skills/existing-app-change.md index b33af28a..62b42080 100644 --- a/skills/existing-app-change.md +++ b/skills/existing-app-change.md @@ -28,7 +28,7 @@ that loop. |---|---| | To understand, audit or lint the app; a regression net; no change planned | `existing-app-assurance.md` | | To rebuild the app on Mendix from a non-Mendix source | `conversion-runbook.md` → Migration | -| A brand-new app | `conversion-runbook.md` → Requirements-driven or Greenfield | +| A brand-new app | `conversion-runbook.md` → Requirements-driven (from documents or a conversation), or a POC | | A one-line fix you would not open a ticket for | Just do it. This skill is overhead for a typo. | The line between "a change" and "a new app inside an old one" is scope, and Stage 0 draws it. If what diff --git a/skills/interaction-model.md b/skills/interaction-model.md index ee697d56..0b7fcb54 100644 --- a/skills/interaction-model.md +++ b/skills/interaction-model.md @@ -1,6 +1,6 @@ # Interaction Model — Who Lands Where, and What Object Each Page Is About -**Applies to:** migration | requirements-driven | greenfield | change an existing app (any project that draws wireframes) +**Applies to:** migration | requirements-driven | POC | change an existing app (any project that draws wireframes) **Purpose:** Before the first wireframe, write down how each role reaches each page and which object each page is about, so the wireframes, the build and the journeys all start from one page-parameter contract instead of one persona looking at one record. diff --git a/skills/interview-protocol.md b/skills/interview-protocol.md index 8db1eb9b..672e560f 100644 --- a/skills/interview-protocol.md +++ b/skills/interview-protocol.md @@ -72,7 +72,7 @@ gates by design with nothing saying so (#624). **No question stays "Not yet asked" under `auto`.** It gets its recommended default, recorded `ASSUMED` as above; in `intake.md` the answer line reads `Assumed (auto-mode): — rejected: `, -colon right after the parenthesis, e.g. `Assumed (auto-mode): greenfield — rejected: requirements-driven` (`Assumed (auto) — greenfield`, no colon, FAILs Stage P). The intake's Marketplace question defaults to *"use the catalogued Marketplace +colon right after the parenthesis, e.g. `Assumed (auto-mode): requirements-driven — rejected: migration` (`Assumed (auto) — requirements-driven`, no colon, FAILs Stage P). The intake's Marketplace question defaults to *"use the catalogued Marketplace component for each capability (`marketplace-catalogue.md`); Build only with a reason in the fit-gap row"*, written to `PROJECT.md`. Failure: an unattended run left it unasked, skipped the fit-gap, and hand-wrote in Java an LLM call the GenAI modules provide. diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md index 31981277..95e45e9e 100644 --- a/skills/iterative-build-loop.md +++ b/skills/iterative-build-loop.md @@ -1,5 +1,5 @@ # Iterative Build Loop — BRD to Running Mendix App -**Applies to:** any mxcli project (migration and greenfield alike). +**Applies to:** any mxcli project (migration and new apps alike). **Requires:** bash and Python 3 — this skill runs toolkit shell scripts. Run `bin/doctor.sh` once on a new machine; it names anything missing and how to get it. Windows: use Git Bash, and see the Prerequisites section of `conversion-runbook.md`. **Purpose:** Per-module build discipline for mxcli-assisted Mendix development. Replaces bulk MDL generation with a verified, iterative gate per module. **Companion skills:** `brd-to-build-plan.md` (upstream — produces the plan this loop executes), `migration-pipeline.md`, `conversion-runbook.md` (Stage 5 — where the coverage checklist below gets confirmed with the user, not just self-extracted), `mdl-cookbook-microflows.md`, `bug-logs/mxcli-bugs.md` diff --git a/skills/poc-build.md b/skills/poc-build.md index 3dcd8687..e1fc2a6b 100644 --- a/skills/poc-build.md +++ b/skills/poc-build.md @@ -11,12 +11,13 @@ **Not a speed setting.** `Pipeline mode: high-speed` is the existing way to make a NORMAL build faster; a POC build is a different shape of build. -**Question moments:** after the build-type answer, ONE message with the prototype question AND the three design questions (step 1; the three apply only if the prototype answer is Nothing), and wait for the reply; then exactly one more stop, the approval (step 4), which ends the turn. The build type was asked at kickoff. +**Question moments:** after the build-type answer, ONE message with the prototype question AND the three design questions (step 1; any size warning from step 0 rides in it; the three apply only if the prototype answer is Nothing), and wait for the reply; then exactly one more stop, the approval (step 4), which ends the turn. The build type was asked at kickoff. ## Order (nothing else) Design artifacts (design system, wireframes, clickable prototype) → one **APPROVAL STOP** → only then model work: security, theme, walking skeleton, pages, journey, hand-over. +0. **Inputs.** A requirements document or spec supplied: read it once and list its use cases, business rules and must-haves; the list feeds the wireframes (step 2), the journey's negative steps (step 8) and the hand-over (step 9). No BRD generation. Over the measured size (3 entities, 5 pages, 2 roles): say so once in the step-1 message and recommend requirements-driven (the document becomes its Stage 1 input); continue as POC only if the user confirms. 1. **Design questions** (per `skills/interview-protocol.md` §3; ONE message, then end the turn and wait for the reply): "Do you have a prototype or a design?" plus the three Nothing-case questions below, so one reply answers all. - **Prototype or design supplied:** reproduce it (`mxcli theme create --from `, `theme apply`; bundled `migrate-design-prototype`). Steps 2 and 3 still run in reduced form: the prototype IS the wireframe set; run the buildability pass on it; the stop (step 4) is on the prototype plus the list of deviations Mendix forces. - **Brand guide only:** tokens from the brand → design system → hi-fi wireframes (step 2) → buildability (step 3) → stop (step 4). @@ -28,7 +29,7 @@ Design artifacts (design system, wireframes, clickable prototype) → one **APPR 6. **Theme**: port the design system into the theme; look at one page at 1280 and 390; run `bin/check-design-reaches-app.sh design/ds.css`. Name the design tokens as the theme names them (`--mxt-*`), or the check sees none (*failure: `FAIL 0 of 10 tokens` on a visibly styled app*); component classes in `ds.css` never ship, the theme does (`ui-preflight-pages.md`). *Failure: stock Atlas pages.* 7. **Build** the walking skeleton (`skills/walking-skeleton.md`) as the first slice, not a separate project; then pages. Write via `bin/exec.sh --commit-first`. Per page: one LOOK at 1280 beside the wireframe, one polish round; 390 on the first page only. A `DataView` per list row for editable inputs. Validate on Save, not blur (a blur message can move Save, swallowing the click): show the message in a gap reserved above Save, so it moves nothing. Order lists as a user reads them (date then time, most urgent first); *failure: tomorrow's visit above today's.* Filter choice lists by the rules; *failure: an out-of-service room was selectable, refused only on save.* 8. **Journey**, once, at the end: one script (not the `journey-proof.md` runner): the happy path, plus one negative step per business rule and per must-have, plus one cross-user refusal per role (reads or writes another user's data, not only a forbidden page; *failure: it caught a role reaching forbidden pages, not one reading every other user's rows*), each asserted by its message text. A rule no screen can trigger is listed in the hand-over "not reachable from the UI" with the reason; *failure: 1 of 6 rules was guarded in the microflow, no screen triggered it, the journey skipped it.* No always-true assertions; *failure: 2 of 22 steps were `ok(true, …)`.* Every session the script opens logs out before its browser context closes, each user switch included, not only the last step; *failure: a journey with no logout passed once, then failed on the trial runtime's 6-session cap.* **2 runs**: warm, then one restart, then cold on the used database; a session leak fails run 2 at login. Then the broken control, no restart: change one expected message, the run must FAIL at that message's step (a sign-in failure does not count), restore it. No documented command resets the database (not `mxcli run`; a harness may refuse deleting the hsqldb files in `deployment/data/database/hsqldb/`): make the journey delete what it creates, or add a demo-reset microflow and list it in the hand-over under "remove before real use". Last, one LOOK pass over every page at 1280 and 390, the main screen included; *failure: rows like "J2595388 Visitor" under the designed screen.* -9. **Hand-over**: markdown, not BRD JSON (no built/not-built, roles or owner fields). One document per use case: data table; roles-by-page matrix; built vs not built; open questions each with an owner; sized backlog. State, do not fix: a page URL a role may not open lands on the bare sign-in page (messageCode=403). Before the app leaves the machine, before any package or deploy: `bin/demo-login-tiles.sh --remove`, then `bin/demo-login-tiles.sh --check --strict` must exit 0; say so in the hand-over. Continue later: `skills/existing-app-change.md`. +9. **Hand-over**: markdown, not BRD JSON (no built/not-built, roles or owner fields). One document per use case: data table; roles-by-page matrix; built vs not built; open questions each with an owner; sized backlog. State, do not fix: a page URL a role may not open lands on the bare sign-in page (messageCode=403). Before the app leaves the machine, before any package or deploy: `bin/demo-login-tiles.sh --remove`, then `bin/demo-login-tiles.sh --check --strict` must exit 0; say so in the hand-over. Continue later: `conversion-runbook.md` → Entry Modes, rule 4 (POC to a real app). **Looks** are judged from screenshots at 1280 and 390, never by `page-fidelity.js`; `check-page-shell.sh` still runs. diff --git a/skills/query-the-model.md b/skills/query-the-model.md index 30e9149c..0f1f762e 100644 --- a/skills/query-the-model.md +++ b/skills/query-the-model.md @@ -1,6 +1,6 @@ # Query the Model — Source-of-Truth Order Before Any Question or Write -**Applies to:** any mxcli project (migration and greenfield alike). +**Applies to:** any mxcli project (migration and new apps alike). **Purpose:** Fix the one rule that makes every other gate in `conversion-runbook.md` work: **query the model → read the source → ask the human, in that order, and never skip to the last one.** An agent that asks the user something it could have derived wastes their attention and teaches them to stop trusting the interviews. An agent that guesses instead of querying produces scripts that look right and fail at `mxbuild`, or silently drift from what the Mendix model actually contains. diff --git a/skills/small-project-tier.md b/skills/small-project-tier.md index dee9ade6..ed971035 100644 --- a/skills/small-project-tier.md +++ b/skills/small-project-tier.md @@ -11,7 +11,7 @@ the cost, not the source. This tier keeps every gate and every interview and bou gate reads — it never removes a thing a gate reads. **Upstream:** the Stage 0 inventory (`bin/source-sufficiency.sh init`, or the intake for -greenfield) and CAC-1 (`checkpoints/checkpoint-scope.md` Q3). +a project whose source is a conversation) and CAC-1 (`checkpoints/checkpoint-scope.md` Q3). **Downstream:** every stage's §1b checklist carries the caps below as its denominators; `bin/gate-check.sh` reads the waiver lines this tier tells you to write. diff --git a/skills/upstream-feedback.md b/skills/upstream-feedback.md index a030bdbc..af787578 100644 --- a/skills/upstream-feedback.md +++ b/skills/upstream-feedback.md @@ -1,6 +1,6 @@ # Upstream Feedback -**Applies to:** any mxcli project — migration, requirements-driven, and greenfield alike. +**Applies to:** any mxcli project — migration, requirements-driven, and POC alike. **Purpose:** Route a finding worth sending upstream — an mxcli command that lied, a gate that let a defect through, a runbook stage that was missing a step — to the right repo and the right diff --git a/skills/walking-skeleton.md b/skills/walking-skeleton.md index ab4a757f..5ec13481 100644 --- a/skills/walking-skeleton.md +++ b/skills/walking-skeleton.md @@ -1,6 +1,6 @@ # Walking skeleton — prove the whole loop on one thin slice before any module -**Applies to:** every entry mode (migration, requirements-driven, greenfield) — the first thing +**Applies to:** every entry mode (migration, requirements-driven, change an existing app; a POC builds it as its first slice) — the first thing Stage 5 does, before the first module of the build plan. À-la-carte work on an existing app skips it. **Purpose:** one entity, one microflow, one page, one nav item, one demo user, one journey, one screenshot — proven end to end in the *running* app. It is not a feature. It is the proof that the @@ -75,7 +75,7 @@ first module fixes, known on day one instead of at module close. - Not the first module. The skeleton entity may be *absorbed* by the first module's script that owns that document (`create or modify`), never deleted. - Not a design review. One page, four questions. `module-review.md` still runs at module close. -- Not optional in greenfield. Greenfield is where the machinery is newest and least proven. +- Not optional for a new app. A new app is where the machinery is newest and least proven. ## Related diff --git a/tests/wave2/test-bug03-gates.sh b/tests/wave2/test-bug03-gates.sh index dcc9597e..f1788ba5 100755 --- a/tests/wave2/test-bug03-gates.sh +++ b/tests/wave2/test-bug03-gates.sh @@ -522,9 +522,9 @@ case "$V" in *'ledger: ;'*|*': ;'*) bad "an empty not-measured reason was printe s4proj t23d; printf '\nWaived stage 4:\n' >> "$P/PROJECT.md" V="$(verdict "$P" 4)" case "$V" in *PASS*'WARN'*'has no reason'*) ok "reasonless waiver on a passing stage: PASS with a WARN" ;; *) bad "reasonless waiver on a passing stage: $V" ;; esac -P="$(mkproj t23e)"; printf 'Entry mode: greenfield\n\nWaived stage 3:\n' >> "$P/PROJECT.md" -V="$(verdict "$P" 3)" -case "$V" in *WAIVED*'greenfield'*'WARN'*) ok "reasonless waiver on a mode-skipped stage: WAIVED by the mode, with a WARN" ;; *) bad "reasonless waiver on a mode-skipped stage: $V" ;; esac +P="$(mkproj t23e)"; printf 'Entry mode: requirements-driven\n\nWaived stage 7:\n' >> "$P/PROJECT.md" +V="$(verdict "$P" 7)" +case "$V" in *WAIVED*'requirements-driven'*'WARN'*) ok "reasonless waiver on a mode-skipped stage: WAIVED by the mode, with a WARN" ;; *) bad "reasonless waiver on a mode-skipped stage: $V" ;; esac # (5) dotted row ids and requirement ids in Depends on s4proj t23f sed -i.bak 's/| 2 | `BUILD` | 010-domain.mdl | domain | 1 |/| 2 | `BUILD` | 010-domain.mdl | domain | 1, US-12, F001 |/; s/| 3 | `BUILD` | 020-approval.mdl | domain | 2 |/| 3.1 | `BUILD` | 020-approval.mdl | domain | 2 |/; s/| 0 errors | 2–3 |/| 0 errors | 2–3.1, 01 |/' "$P/architecture/build-plan.md"; rm -f "$P/architecture/build-plan.md.bak" diff --git a/tests/wave2/test-bug12-sync.sh b/tests/wave2/test-bug12-sync.sh index 4e21c2b7..c6fc6b75 100755 --- a/tests/wave2/test-bug12-sync.sh +++ b/tests/wave2/test-bug12-sync.sh @@ -353,7 +353,7 @@ BEFORE="$(md5 -q "$P10/intake.md" 2>/dev/null || md5sum "$P10/intake.md" | cut - O="$("$SYNC" "$P10" 2>&1)" case "$O" in *"predates the current kickoff question set"*) ok "a plain run REPORTS the old set" ;; *) bad "a plain run REPORTS the old set" ;; esac -case "$O" in *"Entry mode: migration, requirements-driven, greenfield, or change an existing app?"*) +case "$O" in *"Entry mode: migration, requirements-driven, or change an existing app?"*) ok " and names the question that matters most" ;; *) bad " and names the question that matters most" ;; esac case "$O" in *"licence/security constraints"*) diff --git a/tests/wave2/test-ci-gates.sh b/tests/wave2/test-ci-gates.sh index 0136c662..aaa3366f 100755 --- a/tests/wave2/test-ci-gates.sh +++ b/tests/wave2/test-ci-gates.sh @@ -48,9 +48,9 @@ see_all() { commit_all() { G "$1" add -A; G "$1" commit -qm "$2"; } ci() { rm -rf "$WORK/ci"; git clone -q "$1" "$WORK/ci"; out="$(bash "$SUBJECT" "$WORK/ci" 2>&1)"; rc=$?; } -# ── C0: clean — every page seen, READY by ready.sh, greenfield ──────────────────────────── -P="$WORK/c0"; mkproject "$P" greenfield; see_all "$P" -# READY needs P-4 passed or waived: greenfield waives 1-4 but owes 0, so the fixture joins at Build +# ── C0: clean — every page seen, READY by ready.sh, requirements-driven ──────────────────────────── +P="$WORK/c0"; mkproject "$P" requirements-driven; see_all "$P" +# READY needs P-4 passed or waived: no entry mode waives 1-4 (greenfield was retired), so the fixture joins at Build # the way test-ready.sh does (--waive P, --adopt 5) bash "$TK/bin/gate-check.sh" --no-html --waive P --reason "fixture: kickoff held elsewhere" "$P" >/dev/null 2>&1 bash "$TK/bin/gate-check.sh" --no-html --adopt 5 --reason "fixture: joins at build" "$P" >/dev/null 2>&1 @@ -96,7 +96,7 @@ ci "$P" [ "$rc" = 1 ] && printf '%s\n' "$out" | grep -q '^FAIL look look: 3 of 4 pages seen — READY (app) while the committed look summary shows 1 built page(s) never looked at: Approval.Approval_Archive' \ && ok "C2: READY standing over a committed unseen page fails CI" || bad "C2: rc=$rc $out" # the same tree without a done-claim is a warning mid-build, a FAIL when strict -P2="$WORK/c2b"; mkproject "$P2" greenfield; (cd "$P2" && bash bin/look-ledger.sh summary --write >/dev/null); commit_all "$P2" summary +P2="$WORK/c2b"; mkproject "$P2" requirements-driven; bash "$TK/bin/gate-check.sh" --no-html --adopt 5 --reason "fixture: joins at build" "$P2" >/dev/null 2>&1; (cd "$P2" && bash bin/look-ledger.sh summary --write >/dev/null); commit_all "$P2" summary ci "$P2" [ "$rc" = 0 ] && printf '%s\n' "$out" | grep -q '^WARN look look: 0 of 3 pages seen — 3 built page(s) not looked at yet' && ok "C2: no claim → WARN, exit 0 (mid-build)" || bad "C2b: rc=$rc $out" rm -rf "$WORK/ci"; git clone -q "$P2" "$WORK/ci"; out="$(MXTK_CI_STRICT_LOOK=1 bash "$SUBJECT" "$WORK/ci" 2>&1)"; rc=$? diff --git a/tests/wave2/test-entry-mode-plan-rule.sh b/tests/wave2/test-entry-mode-plan-rule.sh index 2e3ad2a7..af482d72 100755 --- a/tests/wave2/test-entry-mode-plan-rule.sh +++ b/tests/wave2/test-entry-mode-plan-rule.sh @@ -13,7 +13,8 @@ # refused ONCE (nothing written, MXTK-RESULT refused); the re-run goes on, row tagged "no plan" # C cleared without a refusal by: gate-check.sh --adopt 5 (the real command), a build plan + # module brief (root, or apps//architecture/), a brief inline in the plan -# N never refused: a-la-carte, greenfield, Build type: poc, Change an existing app, --patch +# N never refused: a-la-carte, Build type: poc, Change an existing app, --patch; a retired +# greenfield line is not refused either and says to run sync-project.sh # # Both layouts: single tree (/Fixture.mpr) and multi-app (/apps/Orders/Orders.mpr, # PROJECT.md at the root). Golden register + intake: fixtures/entry-mode-plan-rule/ (captured from @@ -139,12 +140,22 @@ grep -q '^Answered: migration' "$P/intake.md" || bad "setup: intake answer not w run; refused && ok "R migration via the intake answer is refused once" || bad "R migration via intake" "calls=$CALLS_N" # N — modes that never refuse -for line in "Entry mode: a-la-carte" "Entry mode: greenfield" "Entry mode: Change an existing app"; do +for line in "Entry mode: a-la-carte" "Entry mode: Change an existing app"; do mkproj single "$line" run passed && ok "N '$line' → no refusal" || bad "N '$line' → no refusal" "calls=$CALLS_N" case "$OUT" in *"No entry mode declared"*|*"Plan rule"*) bad "N '$line' → silent" "$(grep -m1 'declared\|Plan rule' "$WORK/out")" ;; *) ok "N '$line' → silent" ;; esac done +# greenfield was retired (2026-11-17): an unsynced register says "run sync", and is not refused +mkproj single "Entry mode: greenfield" +run; passed && ok "N retired greenfield → no refusal" || bad "N retired greenfield → no refusal" "calls=$CALLS_N" +case "$OUT" in *"Entry mode greenfield is retired: run bin/sync-project.sh"*) ok "N retired greenfield → says run sync" ;; *) bad "N retired greenfield → says run sync" ;; esac +# ...but under Interview mode: auto it is held to the requirements-driven plan rule (review of #792) +mkproj single "Entry mode: greenfield" +printf 'Interview mode: auto\n' >> "$P/PROJECT.md" +run +case "$OUT" in *"✗ Plan rule (Interview mode: auto): Entry mode requirements-driven"*) [ "$CALLS_N" = 0 ] && ok "A retired greenfield under auto → refused like requirements-driven" || bad "A retired greenfield under auto reached check" ;; + *) bad "A retired greenfield under auto → refused like requirements-driven" "calls=$CALLS_N" ;; esac mkproj single "Entry mode: requirements-driven" sed -i.bak 's/^Build type: full$/Build type: poc/' "$P/PROJECT.md" && rm -f "$P/PROJECT.md.bak" grep -q '^Build type: poc$' "$P/PROJECT.md" || bad "setup: Build type: poc not written" diff --git a/tests/wave2/test-fitgap-review.sh b/tests/wave2/test-fitgap-review.sh index d6c163f3..5f23bf7e 100755 --- a/tests/wave2/test-fitgap-review.sh +++ b/tests/wave2/test-fitgap-review.sh @@ -18,7 +18,7 @@ # F8 Build row that names the component -> ✓ ("Document Generation ... too rigid") # F9 --waive artifact/fit-gap --reason -> ✓ WAIVED, F1's project # F10 --adopt 5 -> ✓ not owed -# F11 greenfield, no fit-gap -> ✓ not owed; greenfield WITH a bad fit-gap -> ✗ (a file is read) +# F11 a-la-carte, no fit-gap -> ✓ not owed; a-la-carte WITH a bad fit-gap -> ✗ (a file is read) # F12 two-tree layout (app/App.mpr) -> same verdict as F4 # F14 Build row with an ACCIDENTAL keyword ("custom chart widget") -> ✗ naming `charts`; the same # row with a one-sentence "Marketplace: ... not used because ..." reason -> ✓ @@ -121,13 +121,13 @@ gc --adopt 5 --reason "joined at the build" "$P" >/dev/null L="$(fg_line "$(gc "$P" build-ready)")" case "$L" in " ✓ Fit-gap: not owed — project joined the toolkit at stage 5") ok "$L" ;; *) bad "F10: $L" ;; esac -echo "== F11: greenfield ==" -P="$(mkproj f11a root greenfield)" +echo "== F11: a mode that excuses Stage 3 (a-la-carte; greenfield retired 2026-11-17) ==" +P="$(mkproj f11a root a-la-carte)" L="$(fg_line "$(gc "$P" build-ready)")" -case "$L" in " ✓ Fit-gap: not owed — greenfield entry mode"*) ok "greenfield, no fit-gap: not owed" ;; *) bad "F11a: $L" ;; esac -P="$(mkproj f11b root greenfield "$HDR" "$SEP" "$LLM")" +case "$L" in " ✓ Fit-gap: not owed — a-la-carte entry mode"*) ok "a-la-carte, no fit-gap: not owed" ;; *) bad "F11a: $L" ;; esac +P="$(mkproj f11b root a-la-carte "$HDR" "$SEP" "$LLM")" L="$(fg_line "$(gc "$P" build-ready)")" -case "$L" in " ⚠ Fit-gap: ADVISORY —"*genai-llm*) ok "greenfield with a fit-gap: still read" ;; *) bad "F11b: $L" ;; esac +case "$L" in " ⚠ Fit-gap: ADVISORY —"*genai-llm*) ok "a-la-carte with a fit-gap: still read" ;; *) bad "F11b: $L" ;; esac echo "== F12: two-tree layout ==" P="$(mkproj f12 app - "$HDR" "$SEP" "$NATIVE" "$LLM")" diff --git a/tests/wave2/test-greenfield-retired.sh b/tests/wave2/test-greenfield-retired.sh new file mode 100755 index 00000000..1fc6788e --- /dev/null +++ b/tests/wave2/test-greenfield-retired.sh @@ -0,0 +1,79 @@ +#!/usr/bin/env bash +# test-greenfield-retired.sh — greenfield is retired; sync-project.sh maps an old register. +# +# usage: bash tests/wave2/test-greenfield-retired.sh [path-to-sync-project.sh] +# +# Owner decision (2026-11-17): two doors replace greenfield — a real app is requirements-driven +# with the conversation as the source, a demo is Build type: poc. An existing register saying +# `Entry mode: greenfield` is mapped at sync to requirements-driven, adopted at the stage its +# readout shows, with the reason in the register and BUILD-LOG; under Interview mode: auto the +# adoption is a ✋ human-pending decision. An unsynced register is never treated as a valid mode. +# +# U unsynced: gate-check and status print the one "run sync" line; no stage is excused by it +# M sync maps the line (old line kept as a comment), adopts at the readout's stage, writes +# ENTRY-MODE-MAPPED + TOOLKIT-ADOPTED-AT to docs/BUILD-LOG.md, says so once +# A under auto the adoption also writes the ASSUMED consentBy: auto-mode Stage-4 row +# I a second sync maps nothing; a readout at Stage P maps without adopting +# +# Golden register: fixtures/entry-mode-plan-rule/PROJECT.md (captured from init-project.sh). +set -uo pipefail +TOOLKIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +SYNC="${1:-$TOOLKIT/bin/sync-project.sh}" +case "$SYNC" in /*) ;; *) SYNC="$PWD/$SYNC" ;; esac +GOLD="$TOOLKIT/tests/wave2/fixtures/entry-mode-plan-rule" +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/gf-retired.XXXXXX")" && pwd -P)" || exit 2 +trap 'rm -rf "$WORK"' EXIT +PASS=0; FAIL=0 +ok() { PASS=$((PASS+1)); echo " ok - $1"; } +bad() { FAIL=$((FAIL+1)); echo " FAIL - $1${2:+: $2}"; } +echo "== subject: $SYNC" +export MXTK_NO_GUIDE=1 HOME="$WORK/home" + +# mkproj -> P +N=0 +mkproj() { + N=$((N+1)); P="$WORK/p$N"; mkdir -p "$P" + cp "$GOLD/PROJECT.md" "$GOLD/intake.md" "$P/" + awk -v st="$1" '/^\*\*Stage P / { print "**Stage " st " — Build**, in progress."; next } { print }' \ + "$GOLD/PROJECT.md" > "$P/PROJECT.md" + printf '%b' "$2" >> "$P/PROJECT.md" + ( cd "$P" && git init -q . && git add -A && git -c user.email=t@t -c user.name=t commit -qm f ) >/dev/null 2>&1 +} + +echo "-- U: unsynced" +mkproj 5 'Entry mode: greenfield\n' +G="$("$TOOLKIT/bin/gate-check.sh" "$P" 2>&1)" +case "$G" in *"Entry mode greenfield is retired: run bin/sync-project.sh"*) ok "U gate-check says run sync" ;; *) bad "U gate-check says run sync" ;; esac +case "$G" in *"not owed (mode: greenfield)"*) bad "U greenfield excused stages" ;; *) ok "U greenfield excuses no stage" ;; esac +S="$("$TOOLKIT/bin/status.sh" "$P" --brief 2>&1)" +case "$S" in *"Entry mode greenfield is retired"*) ok "U status says so" ;; *) bad "U status says so" ;; esac + +echo "-- M: the mapping" +mkproj 5 'Entry mode: greenfield\n' +"$SYNC" "$P" > "$WORK/s1" 2>&1 +[ "$(grep -c 'Mapped: PROJECT.md Entry mode greenfield → requirements-driven' "$WORK/s1")" = 1 ] && ok "M said once" || bad "M said once" "$(grep -c Mapped "$WORK/s1")" +grep -q '^Entry mode: requirements-driven$' "$P/PROJECT.md" && ok "M register line mapped" || bad "M register line mapped" +grep -q '^