From cf0d2b25c583edfcfd4caa289e7e3dafb166a37d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:23:11 +0000 Subject: [PATCH 01/14] process(exec, entry modes): declared position banner, refuse-once plan rule, design front end With no Entry mode and no Adopted at stage line, status.sh, gate-check.sh's summary and every exec.sh run print one banner. In Entry mode migration or requirements-driven, the first MDL write with no plan evidence is refused once (remedy: run stages 1-4, or gate-check.sh --adopt 5 --reason ...). Outside evidence clears it; a-la-carte (new), greenfield, poc, change-an-existing-app and --patch are never refused. The entry-mode tokeniser moves to project-bin/_position.sh (pure bash, no process starts) so the installed exec.sh can read it; bin/lib/entry-mode.sh is a shim. Runbook greenfield row reuses poc-build steps 1-4 plus a short plan; design-artifacts Step 2a maps supplied prototypes in PAGE-MAP.tsv and ui-preflight-pages' wireframe STOP accepts a mapped prototype. Field evidence: two field runs (2026-11), requirements-driven with a frozen spec and clickable prototypes, built ~78 pages with no plan or target. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8 --- CHANGELOG.md | 1 + bin/gate-check.sh | 9 +- bin/lib/entry-mode.sh | 83 +-------- bin/lib/install-manifest.sh | 4 +- bin/status.sh | 7 + docs/pipeline-walks.html | 2 +- project-bin/_position.sh | 155 ++++++++++++++++ project-bin/exec.sh | 55 +++++- skills/conversion-runbook.md | 8 +- skills/design-artifacts.md | 24 +++ skills/ui-preflight-pages.md | 4 +- .../fixtures/entry-mode-plan-rule/PROJECT.md | 63 +++++++ .../fixtures/entry-mode-plan-rule/README.md | 9 + .../fixtures/entry-mode-plan-rule/intake.md | 161 +++++++++++++++++ tests/wave2/test-entry-mode-plan-rule.sh | 165 ++++++++++++++++++ 15 files changed, 664 insertions(+), 86 deletions(-) create mode 100755 project-bin/_position.sh create mode 100644 tests/wave2/fixtures/entry-mode-plan-rule/PROJECT.md create mode 100644 tests/wave2/fixtures/entry-mode-plan-rule/README.md create mode 100644 tests/wave2/fixtures/entry-mode-plan-rule/intake.md create mode 100755 tests/wave2/test-entry-mode-plan-rule.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 105d7619..cf1ecfe6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m `docs/RELEASE-PROCESS.md` §8. ## Unreleased +- process(exec, entry modes): **the entry mode is a declared fact every tool reads, and a pipeline-mode project no longer builds without a plan by default**: with no `Entry mode:` and no `Adopted at stage:` line (register or intake), `bin/status.sh` (both views, plus a NEXT rule), `bin/gate-check.sh`'s summary and every `bin/exec.sh` run print one banner, and the BUILD-LOG row is tagged `no entry mode declared`; warn-only. In `Entry mode: migration` or `requirements-driven`, the first MDL write with no plan evidence is refused ONCE (nothing locked, snapshotted or written; `verdict=refused`), remedy in one line: run stages 1–4, or `gate-check.sh --adopt 5 --reason ...`. Cleared by outside evidence (guard rule 6): adoption at 5+, a reasoned `Waived stage 4:`, gate-check's readout at Stage 5+, or `architecture/build-plan.md` plus a module brief (root or `apps//`); a re-run after the one refusal goes on, tagged `no plan`. Never refused: `a-la-carte` (new explicit mode: no pipeline, audit or tooling use; gate-check reads its stages WAIVED by mode), `greenfield`, `Build type: poc`, change an existing app, `--patch`. The one entry-mode tokeniser moves to `project-bin/_position.sh` (pure bash, no process starts; installed beside exec.sh, `bin/lib/entry-mode.sh` is now a shim) — identical output on 44 inputs against the old one. Runbook: greenfield's "stages 1–4 collapse to whatever plan the user already has" becomes a design front end (`poc-build.md` steps 1–4, then a short plan with a few lines per module); `design-artifacts.md` Step 2a adopts a supplied prototype by mapping every screen in `design/wireframes/PAGE-MAP.tsv`, and `ui-preflight-pages.md`'s wireframe STOP accepts a mapped prototype. Fixture `tests/wave2/test-entry-mode-plan-rule.sh` (single tree + `apps//`, register and intake captured from `init-project.sh`) — two field runs, Nov 2026, requirements-driven with a frozen spec and clickable prototypes: ~78 pages built with no plan or target - fix(status, agents): **`bin/status.sh` WATCHes an Agent Editor project whose extension module does not travel with the model (#778)**: Studio Pro reads `agenteditor.agent` from `modules/AgentEditor.mxmodule` beside the `.mpr`, and a sync of only `.mpr` + `mprcontents/` left it out of git, so the builder stayed green while every colleague's clone showed `unknown type 'agenteditor.agent'`. Two WATCH items, warn-only (exit code and every verdict unchanged), local files and `git ls-files` only, root and `app/` layouts: a `modules/*.mxmodule` git does not track, and a project using Agent Editor (`AgentEditorCommons` in `analysis/app-facts/inventory.json`, or a `create agent` statement in `mdlsource/`) with no `modules/AgentEditor*.mxmodule`. `skills/mendix-agents.md` (on demand) gains the rule plus the note that the GenAI key, `Encryption.EncryptionKey` and `GenAICommons.StoreTraces` belong in the Default configuration, not a start script. Empty agent references / missing model version (mendixlabs/mxcli#1867) and unset runtime constants are not checked: they need a captured agent document (option 2). Fixture `tests/wave2/test-status-extension-modules.sh` — field report from an Agent Editor project, Nov 2026 - fix(permissions): **exec approval `auto` no longer prompts on every exec's mode check, and `install-claude-hooks.sh` no longer runs unprompted (#782)**: `install-claude-permissions.sh` now allow-lists `exec-approval.sh`, `interview-mode.sh` and `permission-profile.sh`, so their reads run without a prompt, while their only writers, `--set` and `--clear`, prompt through six `ask` rules (`Bash(*exec-approval.sh*--set*)`, …) in the shared settings under every profile (an ask rule beats an allow rule, `full`'s bare `Bash` included). `install-claude-hooks.sh`, which writes `~/.claude/settings.json` for every repo on the machine, gets no allow rule. A re-install adds the ask rules and removes the hooks-installer rule an earlier install added (sidecar); entries someone else wrote are untouched, and `sync-project.sh`'s permission check names both until then. Field run on claude 2.1.325: the read ran, `--set auto` and `--clear` were refused, and with the ask rules removed `--set` ran — from the two independent reviews of #781 - process(skills): **trim PR, moves only: always-loaded words 66,271 -> 64,984 (budget 80,000); Stage 5 test 21,906 -> 20,619, gate 22,954 -> 21,744, review 31,681 -> 30,394 (#783)**: `testing-shape.md` §5's stack and scratch-copy mechanics move verbatim to `e2e-harness-base.md` § Bringing the stack up (the rule and a one-line list of its rules stay in §5); the three new Unit false-green rows move to `unit-test.md` § False-green rows (a pointer row stays in the register); `module-review.md`'s re-shoot mechanics move to `iterative-build-loop.md` § Pipeline mode (the rule, the denominator and the failure example stay) and its MXTK-AI001 sentence to `marketplace-catalogue.md` § Reviewing a built module. Every removed line is in its destination, checked line by line — weekly word-budget audit (#783) diff --git a/bin/gate-check.sh b/bin/gate-check.sh index 4c15089d..22db54a3 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -733,7 +733,7 @@ stage_waiver() { case "$ENTRY_MODE" in greenfield) case "$st" in - 1|2|3|4) printf 'mode|greenfield entry mode — stages 1–4 collapse into the plan the user already has (conversion-runbook.md → Entry Modes)\n'; return 0 ;; + 1|2|3|4) printf 'mode|greenfield entry mode — 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 @@ -743,6 +743,10 @@ stage_waiver() { case "$st" in 7) printf 'mode|existing-app entry mode — the app is live and stays live; there is no cutover (existing-app-change.md → Deliverables)\n'; return 0 ;; esac ;; + a-la-carte) + case "$st" in + [0-7]) printf 'mode|a-la-carte entry mode — no pipeline: audit or tooling use only (existing-app-assurance.md); declare another mode to run the stages\n'; return 0 ;; + esac ;; esac return 1 } @@ -4096,6 +4100,9 @@ echo "not a gate failure and does not affect the exit code — it is a stage nob echo "" printf "Summary: %d passed · %d not started · %d waived · %d need attention · %d manual\n" \ "$N_PASS" "$N_PENDING" "$N_WAIVED" "$N_FAIL" "$N_MANUAL" +# Declared position (project-bin/_position.sh; conversion-runbook.md → Entry Modes). The field runs +# that built with no plan (2026-11) had neither line, and this summary read like any other. +[ -z "$ENTRY_MODE" ] && [ -z "$ADOPTED_AT" ] && printf '⚠ %s\n' "$MXTK_POS_BANNER" # 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/lib/entry-mode.sh b/bin/lib/entry-mode.sh index 2ae14343..de2598fe 100644 --- a/bin/lib/entry-mode.sh +++ b/bin/lib/entry-mode.sh @@ -1,77 +1,6 @@ -# entry-mode.sh — ONE tokeniser for the register's "Entry mode:" line. -# -# WHY THIS EXISTS. Two parsers (bin/gate-check.sh and bin/lib/artifact-check.sh) each -# carried the same unanchored-glob case: -# -# *greenfield*) ... ;; *requirement*) ... ;; *migration*) ... ;; -# -# Unanchored globs plus first-arm-wins means the token that appears EARLIEST IN THE -# CASE wins, not the one the line actually declares. "migration (not greenfield)" -# parsed as greenfield. The consumer stage_waiver() then excuses stages on that label -# with `mode` scope, and the manifest consumer marks rows N/A — so a misread here -# silently switches gates off. bin/status.sh used a third, anchored regex and so -# DISPLAYED the right mode while the gate acted on the wrong one, which is why this -# survived: the screen and the verdict disagreed and only the screen was read. -# -# The rule: match the documented multi-word phrase first, else take the FIRST word of -# the value and exact-match it against the known set. -# A value we do not recognise resolves to empty AND says so on stderr. Silence was -# the second half of the bug — a run could not tell you whether the mode had parsed. -# -# Unknown mode means every row applies and no stage is excused: louder, never quieter. - -# entry_mode_token -> canonical token on stdout, "" if unrecognised. -# -# Canonical set: greenfield | requirements-driven | migration | existing-app-change -entry_mode_token() { - local raw="${1-}" v full - v="$(printf '%s' "$raw" | tr -d '\r' | tr '[:upper:]' '[:lower:]')" - # gate-check.sh's intake fallback passes the WHOLE answer line, not just the value — - # "answered: migration", "decision: requirements-driven", "assumed (2026-09-01): - # greenfield" — because that same line is re-parsed downstream for its qualifier. - # Strip the question-answer prefix (and the qualifier's OWN parenthetical, e.g. the - # date in "assumed (...)") here, before the trailing-parenthetical stripping below — - # doing it after would let that stripping treat "(2026-09-01)" as if it opened at the - # start of the value and eat everything from "assumed (" onward, value included. The - # register's bare value ("migration") has no such prefix and passes through untouched. - v="$(printf '%s' "$v" | sed -E 's/^[[:blank:]>*_-]*(answered|answer|a|decision|assumed)[[:blank:]]*(\([^)]*\))?[[:blank:]]*:[[:blank:]]*//')" - v="${v%%(*}" # drop a trailing parenthetical: "migration (not greenfield)" - v="${v%%,*}" # drop anything after the first comma - v="${v%%;*}" # ...or semicolon - # Trim leading/trailing noise, INCLUDING markdown emphasis markers on both ends - # ("**migration**", "_greenfield_") — the old trailing trim only stripped spaces, - # tabs and a period, so a bolded or italicised value never matched anything. - v="$(printf '%s' "$v" | sed 's/^[[:blank:]>*_-]*//; s/[[:blank:].*_-]*$//')" - full="$v" - # Documented multi-word phrases resolve on the WHOLE value, before the first-word - # truncation below: the runbook's own label for the fourth mode is "Change an existing - # app", whose first word is "change" and matches nothing. Matched as a phrase, not as a - # bare `*existing*` glob, so "Migration from an existing Oracle Forms system" still reads - # as migration (its own first word) rather than being waived as an existing-app change. - case "$full" in - *"change an existing app"*|*"existing app change"*|*"existing-app change"*) - echo "existing-app-change"; return ;; - esac - - # First word only — space, tab, or "/" as a separator ("migration/brownfield" reads - # as migration, its own leading declaration, not as an unrecognised compound value). - v="${v%%[ /]*}" - # ...and trim emphasis/punctuation off THAT word too. The whole-value trim above only - # reaches the value's last character, so "**Migration**. Evidence: 409 .java files" - # (an auto-mode intake answer, #634) left the first word as "migration**." and the mode - # silently vanished. Re-trimming after the cut is what makes the header's "bolded - # values are handled" true for a bolded value with prose after it. - v="$(printf '%s' "$v" | sed 's/^[*_]*//; s/[.:!*_-]*$//')" - - case "$v" in - greenfield) echo "greenfield" ;; - requirements-driven|requirements|requirement) echo "requirements-driven" ;; - migration) echo "migration" ;; - existing-app-change|existing-app|existing) echo "existing-app-change" ;; - "") echo "" ;; - *) - printf 'entry mode "%s" not recognised; no stage is excused\n' "$raw" >&2 - echo "" - ;; - esac -} +# entry-mode.sh — shim. The ONE tokeniser for the register's "Entry mode:" line now lives in +# project-bin/_position.sh, because the installed exec.sh needs it too and cannot reach bin/lib/ +# (2026-11-17). Sourcing this file defines the same entry_mode_token() it always did, plus the +# position reader (mxtk_pos_read) and the banner. Why there is only one tokeniser: the header +# of project-bin/_position.sh. +. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../../project-bin" && pwd)/_position.sh" diff --git a/bin/lib/install-manifest.sh b/bin/lib/install-manifest.sh index d6a962ef..028aee31 100644 --- a/bin/lib/install-manifest.sh +++ b/bin/lib/install-manifest.sh @@ -129,7 +129,9 @@ MXTK_AGENTS_STAGE_BUILD="mdl-agent.md gate-agent.md test-agent.md review-agent.m # runs it per module (informational; see project-bin/mf-canvas-facts.py header). # model-scope.py joined on 2026-10-21: it imports mxpatch.py (and through it mxunit_bson.py) from # its own directory. It puts back units a write changed only in XPath whitespace (mxcli#1596). -MXTK_PROJECT_BIN="reload.sh module-close.sh build-tree.py row-groups.sh process-map.js process-map.template.html app-restart.sh test-scratch.sh script-owners.sh describe-baseline.sh assemble-prototype.js prototype-route.js check-prototype-links.js wf-add-path-terminators.py wf-set-call-captions.py model-scope.py mf-canvas-facts.py mxunit_bson.py mxpatch.py _common.sh app-facts.sh _claims.sh snapshot-mpr.sh restore-mpr.sh exec.sh idempotence-check.sh persona-preflight.sh affected-tests.sh rollback-scan.sh rollback-scan.py rollback-effects.tsv look-ledger.sh look-shots.js save-sp.sh restart-sp.sh check-sp-health.sh verify-module.sh harness-scan.sh test-stack-up.sh fixture-manifest.sh check-root-clean.sh lint-gate.sh lint-trend.sh metrics-ledger.sh metrics-trend.sh close-task.sh conformance-check.sh coverage-preflight.sh graph-sweep.sh review-module.sh coherence-cadence.sh build-plan-status.sh progress-report.py done-drift-check.sh page-scope.sh render-improvement-register.sh check-design-portability.sh check-design-reaches-app.sh check-page-shell.sh page-fidelity.js model-stamp.sh verify-model.sh install-project-hooks.sh mx-metadata-note.py session-check.sh constants-audit.sh context-pack.sh check-staged-secrets.sh project-facts.sh security-check.sh demo-login-tiles.sh" +# _position.sh joined on 2026-11-17: exec.sh sources it as its sibling (the register's position +# lines + the one entry-mode tokeniser; bin/lib/entry-mode.sh is a shim onto the same file). +MXTK_PROJECT_BIN="reload.sh module-close.sh build-tree.py row-groups.sh process-map.js process-map.template.html app-restart.sh test-scratch.sh script-owners.sh describe-baseline.sh assemble-prototype.js prototype-route.js check-prototype-links.js wf-add-path-terminators.py wf-set-call-captions.py model-scope.py mf-canvas-facts.py mxunit_bson.py mxpatch.py _common.sh _position.sh app-facts.sh _claims.sh snapshot-mpr.sh restore-mpr.sh exec.sh idempotence-check.sh persona-preflight.sh affected-tests.sh rollback-scan.sh rollback-scan.py rollback-effects.tsv look-ledger.sh look-shots.js save-sp.sh restart-sp.sh check-sp-health.sh verify-module.sh harness-scan.sh test-stack-up.sh fixture-manifest.sh check-root-clean.sh lint-gate.sh lint-trend.sh metrics-ledger.sh metrics-trend.sh close-task.sh conformance-check.sh coverage-preflight.sh graph-sweep.sh review-module.sh coherence-cadence.sh build-plan-status.sh progress-report.py done-drift-check.sh page-scope.sh render-improvement-register.sh check-design-portability.sh check-design-reaches-app.sh check-page-shell.sh page-fidelity.js model-stamp.sh verify-model.sh install-project-hooks.sh mx-metadata-note.py session-check.sh constants-audit.sh context-pack.sh check-staged-secrets.sh project-facts.sh security-check.sh demo-login-tiles.sh" # Files in project-bin/ that are deliberately NOT installed into projects. The reverse check # below flags anything named by NEITHER list, so a new file in project-bin/ has to be either diff --git a/bin/status.sh b/bin/status.sh index 3fde58bb..276d79f7 100755 --- a/bin/status.sh +++ b/bin/status.sh @@ -72,6 +72,10 @@ ENTRY_RAW="$(awk ' } ' "$REG")" ENTRY="$(entry_mode_token "$ENTRY_RAW" 2>/dev/null)" +# Declared position (project-bin/_position.sh, the reader exec.sh and gate-check.sh share): no +# Entry mode (register or intake) and no adoption line → the one banner, first line of either view. +# Field runs (2026-11) built ~78 pages with neither line, and nothing here said so. +mxtk_pos_read "$PROJECT_DIR"; POS_BANNER=""; mxtk_pos_undeclared && POS_BANNER="$MXTK_POS_BANNER" 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 //')" UNSYNCED="$(grep -c 'UNSYNCED' "$REG" 2>/dev/null)"; UNSYNCED="${UNSYNCED:-0}" @@ -250,6 +254,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 [ -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 esac @@ -379,6 +384,7 @@ for _w in "$STAGE_STALE" "${APPROVED_OVER:+APPROVED OVER A FAILING GATE: $APPROV [ -n "$_w" ] && WATCH="${WATCH:+$WATCH · }$_w" done if [ "$BRIEF" = 1 ]; then + [ -n "$POS_BANNER" ] && echo "⚠ $POS_BANNER" [ -n "$CWD_NOTE" ] && echo "CWD $CWD_NOTE" echo "WHERE $NAME · $STAGE_LINE${ENTRY:+ · $ENTRY}${ADOPTED:+ · joined at $ADOPTED}" [ -n "$ROUND_LINE" ] && echo "ROUND $ROUND_LINE" @@ -390,6 +396,7 @@ if [ "$BRIEF" = 1 ]; then fi printf '\n%s — %s%s%s\n' "$NAME" "$STAGE_LINE" "${ENTRY:+ · $ENTRY}" "${ADOPTED:+ · joined at stage $ADOPTED}" printf '%s\n\n' "$TK" +[ -n "$POS_BANNER" ] && printf '⚠ %s\n\n' "$POS_BANNER" [ -n "$CWD_NOTE" ] && printf 'CWD %s\n' "$CWD_NOTE" [ -n "$ROUND_LINE" ] && printf 'ROUND %s\n' "$ROUND_LINE" printf 'DONE scripts: %s written, %s gate-pass, %s done- · modules opened: %s%s\n' "$N_SCRIPTS" "$N_PASS" "$N_DONE" "$MOD_OPENED" "${SKELETON:+ · skeleton proven $SKELETON}" diff --git a/docs/pipeline-walks.html b/docs/pipeline-walks.html index ad08b7bb..da14e045 100644 --- a/docs/pipeline-walks.html +++ b/docs/pipeline-walks.html @@ -216,7 +216,7 @@

Requirements-driven Specs, BRDs, work

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

-

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

+

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"] diff --git a/project-bin/_position.sh b/project-bin/_position.sh new file mode 100755 index 00000000..2f9e9e39 --- /dev/null +++ b/project-bin/_position.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash +# _position.sh — where a project says it is: the ONE reader of the register's position lines +# (Entry mode, Adopted at stage, Build type, Waived stage 4, the Current-stage readout) and the +# ONE tokeniser for "Entry mode:". Sourced by project-bin/exec.sh (installed as bin/_position.sh) +# and, through the shim bin/lib/entry-mode.sh, by bin/gate-check.sh, bin/status.sh and +# bin/lib/artifact-check.sh. +# +# PURE BASH, no process starts: exec.sh runs this on every model write and its per-exec budget is +# counted (tests/wave2/test-exec-process-budget.sh). Bash 3.2 safe (macOS): no ${v,,}, no +# associative arrays; case-insensitive matching is `shopt -s nocasematch` inside [[ ]] only, +# restored on every return. +# +# WHY THE TOKENISER LIVES HERE (2026-11-17). It used to be bin/lib/entry-mode.sh, which an +# installed exec.sh cannot reach. exec.sh now has to know the mode (the plan rule below), and a +# second tokeniser is exactly what the old header warned against: two parsers once disagreed on +# "migration (not greenfield)" and the gate excused stages the screen said were owed. +# +# The rule: match the documented multi-word phrase first, else take the FIRST word of the value +# and exact-match it against the known set. A value we do not recognise resolves to empty AND +# says so on stderr. Unknown mode means every row applies and no stage is excused: louder, never +# quieter. + +# entry_mode_token -> canonical token on stdout, "" if unrecognised. +# Canonical set: greenfield | requirements-driven | migration | existing-app-change | a-la-carte +entry_mode_token() { _mxtk_emt "${1-}"; echo "$_EMT"; } + +# _mxtk_emt — the tokeniser itself; sets _EMT instead of printing, so exec.sh's reader +# below needs no command substitution (a fork is ~100 ms on Git Bash). +_mxtk_emt() { + local raw="${1-}" v full _nc=0 + shopt -q nocasematch && _nc=1; shopt -s nocasematch + v="${raw//$'\r'/}" + # gate-check.sh's intake fallback passes the WHOLE answer line ("answered: migration", + # "assumed (2026-09-01): greenfield"). Strip the question-answer prefix and the qualifier's own + # parenthetical first, so the trailing-parenthetical cut below cannot eat the value with it. + if [[ "$v" =~ ^[[:blank:]\>*_-]*(answered|answer|a|decision|assumed)[[:blank:]]*(\([^\)]*\))?[[:blank:]]*:[[:blank:]]*(.*)$ ]]; then + v="${BASH_REMATCH[3]}" + fi + v="${v%%(*}"; v="${v%%,*}"; v="${v%%;*}" # "migration (not greenfield)", "x, y", "x; y" + # Trim markdown emphasis and noise on both ends ("**migration**", "_greenfield_"). + [[ "$v" =~ ^[[:blank:]\>*_-]*(.*)$ ]] && v="${BASH_REMATCH[1]}" + if [[ "$v" =~ ^(.*[^[:blank:].*_-])[[:blank:].*_-]*$ ]]; then v="${BASH_REMATCH[1]}"; else v=""; fi + full="$v" + # Phrases on the WHOLE value, before the first-word cut: "Change an existing app" starts with + # "change", which matches nothing; "a la carte" starts with "a". Phrases, not bare globs, so + # "Migration from an existing Oracle Forms system" still reads as migration. + if [[ "$full" == *"change an existing app"* || "$full" == *"existing app change"* || "$full" == *"existing-app change"* ]]; then + [ "$_nc" = 1 ] || shopt -u nocasematch; _EMT="existing-app-change"; return 0 + fi + if [[ "$full" == "a la carte"* || "$full" == "à la carte"* ]]; then + [ "$_nc" = 1 ] || shopt -u nocasematch; _EMT="a-la-carte"; return 0 + fi + # First word only — space, tab or "/" ("migration/brownfield" reads as migration) — then trim + # emphasis/punctuation off THAT word ("**Migration**. Evidence: 409 .java files", #634). + v="${v%%[ /]*}" + [[ "$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" + 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" + elif [[ "$v" == a-la-carte || "$v" == à-la-carte || "$v" == alacarte || "$v" == ala-carte ]]; then tok="a-la-carte" + elif [ -n "$v" ]; then known=0; fi + [ "$_nc" = 1 ] || shopt -u nocasematch + [ "$known" = 1 ] || printf 'entry mode "%s" not recognised; no stage is excused\n' "$raw" >&2 + _EMT="$tok" +} + +# mxtk_pos_read — reads /PROJECT.md once (HTML comments skipped: the +# scaffold's own comments name these labels) and, when the register has no Entry mode line, the +# intake.md §1 answer. Sets, never prints: +# POS_REG 1 when PROJECT.md exists +# POS_ENTRY canonical token, or "" (none declared / not recognised) +# POS_ADOPTED the "Adopted at stage:" stage (P|0-7), or "" +# POS_BUILD "poc" when "Build type: poc", else "full" +# POS_WAIVED4 1 when a "Waived stage 4:" line carries a reason +# POS_READOUT the stage in gate-check.sh's "## Current stage" readout ("**Stage 5 — ..."), or "" +mxtk_pos_read() { + local root="$1" reg line key val in_c=0 in_cur=0 entry_raw="" ad="" bt="" _nc=0 + POS_REG=0; POS_ENTRY=""; POS_ADOPTED=""; POS_BUILD="full"; POS_WAIVED4=0; POS_READOUT="" + reg="$root/PROJECT.md" + shopt -q nocasematch && _nc=1; shopt -s nocasematch + if [ -f "$reg" ]; then + POS_REG=1 + while IFS= read -r line || [ -n "$line" ]; do + line="${line//$'\r'/}" + if [ "$in_c" = 1 ]; then [[ "$line" == *"-->"* ]] && in_c=0; continue; fi + if [[ "$line" == *""* ]] || in_c=1; continue; fi + if [[ "$line" == "## "* ]]; then [[ "$line" == "## Current stage"* ]] && in_cur=1 || in_cur=0; continue; fi + if [ "$in_cur" = 1 ] && [ -z "$POS_READOUT" ] && [[ "$line" =~ ^\*\*Stage[[:blank:]]+([Pp0-7])([^0-9]|$) ]]; then + POS_READOUT="${BASH_REMATCH[1]}"; continue + fi + [[ "$line" =~ ^[[:blank:]\>*_-]*([^:]+):[[:blank:]]*(.*)$ ]] || continue + key="${BASH_REMATCH[1]}"; val="${BASH_REMATCH[2]}" + key="${key%"${key##*[!*[:blank:]]}"}"; val="${val//\*/}" + [ -n "${val//[[:blank:]]/}" ] || continue + if [ -z "$entry_raw" ] && [[ "$key" == "entry mode" ]]; then entry_raw="$val" + elif [ -z "$ad" ] && [[ "$key" == "adopted at stage" ]]; then ad="$val" + elif [ -z "$bt" ] && [[ "$key" == "build type" ]]; then bt="$val" + elif [[ "$key" == "waived stage 4" ]]; then POS_WAIVED4=1 + fi + done < "$reg" + fi + # The intake answer is where the mode is decided and the only copy a young project has + # (gate-check.sh reads it the same way). + if [ -z "$entry_raw" ] && [ -f "$root/intake.md" ]; then + local in_q=0 + while IFS= read -r line || [ -n "$line" ]; do + if [[ "$line" =~ ^##[[:blank:]]*1\. ]] && [[ "$line" == *"entry mode"* ]]; then in_q=1; continue; fi + [ "$in_q" = 1 ] || continue + [[ "$line" == "##"* ]] && break + if [[ "$line" =~ ^[[:blank:]\>*_-]*(answered|answer|a|decision|assumed)[[:blank:]]*(\([^\)]*\))?[[:blank:]]*: ]]; then + entry_raw="$line"; break + fi + done < "$root/intake.md" + fi + [[ "$bt" =~ ^[[:blank:]]*poc([^a-z]|$) ]] && POS_BUILD="poc" + [[ "$ad" =~ ^[[:blank:]]*([Pp0-7])([^0-9]|$) ]] && POS_ADOPTED="${BASH_REMATCH[1]}" + [ "$_nc" = 1 ] || shopt -u nocasematch + if [ -n "$entry_raw" ]; then _mxtk_emt "$entry_raw" 2>/dev/null; POS_ENTRY="$_EMT"; fi + return 0 +} + +# 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_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. +# The bold Current-stage readout does not count: the scaffold writes it and gate-check rewrites it; +# it is a measurement, not a declaration. +mxtk_pos_undeclared() { [ -z "$POS_ENTRY" ] && [ -z "$POS_ADOPTED" ]; } + +# mxtk_plan_evidence — sets POS_EVIDENCE to what proves a plan exists before a +# pipeline-mode model write, returns 1 when nothing does (no fork: exec.sh calls it per write). Guard rule 6: evidence the toolkit did not create counts. +# - Adopted at stage 5+ (the register line --adopt writes) +# - Waived stage 4, with a reason +# - gate-check's readout at Stage 5+ (every stage before it PASS or WAIVED) +# - a build plan plus at least one module brief (architecture/ at the root or under apps//) +mxtk_plan_evidence() { + local root="$1" d f + POS_EVIDENCE="" + case "$POS_ADOPTED" in 5|6|7) POS_EVIDENCE="Adopted at stage: $POS_ADOPTED"; return 0 ;; esac + [ "$POS_WAIVED4" = 1 ] && { POS_EVIDENCE="Waived stage 4"; return 0; } + case "$POS_READOUT" in 5|6|7) POS_EVIDENCE="gate-check readout: Stage $POS_READOUT"; return 0 ;; esac + for d in "$root/architecture" "$root"/apps/*/architecture; do + [ -s "$d/build-plan.md" ] || continue + for f in "$d"/modules/*/module-brief.md; do + [ -s "$f" ] && { POS_EVIDENCE="${d#"$root"/}/build-plan.md + module briefs"; return 0; } + done + local _bp; IFS= read -r -d '' _bp < "$d/build-plan.md" || true + [[ "$_bp" =~ (^|$'\n')#+[[:blank:]]*[Mm]odule[[:blank:]]+[Bb]rief ]] && { POS_EVIDENCE="${d#"$root"/}/build-plan.md (briefs inline)"; return 0; } + done + return 1 +} diff --git a/project-bin/exec.sh b/project-bin/exec.sh index ccee4d86..77b96c2b 100755 --- a/project-bin/exec.sh +++ b/project-bin/exec.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # exec.sh — the guard chain around a model write. # -# STOP-row scan → concurrent-writer guard → module-brief advisory → mxcli check → snapshot → baseline → exec +# position banner + plan rule → STOP-row scan → concurrent-writer guard → module-brief advisory → mxcli check → snapshot → baseline → exec # → model-scope restore (units changed only in whitespace go back to HEAD; model-scope.py) # → mxbuild delta gate → auto-restore only on a NEW error → lint ratchet → SP reopen # @@ -704,7 +704,7 @@ HDR2 # The gate cell is read from GATE_STATE rather than passed in, so no caller # can omit it — a blank cell in this table reads as "fine", which is the exact # false-green the gate exists to prevent. - _detail="$2${CHANGE_CLASS:+ · change: $CHANGE_CLASS}${CR_ID:+ · cr: $CR_ID}${SCAN_NOTE:+ · $SCAN_NOTE}${ROWS_NOTE:+ · $ROWS_NOTE}${MKT_NOTE:+ · $MKT_NOTE}${RESTATE_NOTE:+ · $RESTATE_NOTE}${GATE_NOTE:+ · $GATE_NOTE}${MXB_LOG_NOTE:+ · $MXB_LOG_NOTE}${HV_NOTE:+ · $HV_NOTE}${SCOPE_NOTE:+ · $SCOPE_NOTE}$_EXEC_APPROVAL_SUFFIX${STEP_TIMES:+ · steps: $STEP_TIMES}" + _detail="$2${CHANGE_CLASS:+ · change: $CHANGE_CLASS}${CR_ID:+ · cr: $CR_ID}${POS_NOTE:+ · $POS_NOTE}${SCAN_NOTE:+ · $SCAN_NOTE}${ROWS_NOTE:+ · $ROWS_NOTE}${MKT_NOTE:+ · $MKT_NOTE}${RESTATE_NOTE:+ · $RESTATE_NOTE}${GATE_NOTE:+ · $GATE_NOTE}${MXB_LOG_NOTE:+ · $MXB_LOG_NOTE}${HV_NOTE:+ · $HV_NOTE}${SCOPE_NOTE:+ · $SCOPE_NOTE}$_EXEC_APPROVAL_SUFFIX${STEP_TIMES:+ · steps: $STEP_TIMES}" if [ -n "${EPOCHSECONDS:-}" ]; then printf -v _when '%(%Y-%m-%dT%H:%M:%S%z)T' -1; else _when="$(date '+%Y-%m-%dT%H:%M:%S%z')"; fi printf '| %s | `%s` | %s | %s | %s |\n' \ "$_when" "$LOG_NAME" \ @@ -755,6 +755,57 @@ take_score() { fi } +# ── Declared position + plan rule (2026-11-17) ────────────────────────────── +# _position.sh reads PROJECT.md (and intake.md §1) once, in-shell: no process starts. +# +# BANNER. No `Entry mode:` and no `Adopted at stage:` → one line on every run and a BUILD-LOG tag, +# so an unattended run cannot miss it. Two field runs (2026-11, requirements-driven, full spec and +# prototypes supplied) built ~78 pages with no BRDs, blueprint, wireframes or plan, and the +# register said nothing about where the project was; every guard stayed silent because the +# project had declared nothing for it to check against. +# +# PLAN RULE — a policy change. The module-brief block below says "exec.sh is not the pipeline's +# gatekeeper", and for an undeclared or a-la-carte project it still is not. But a project that +# DECLARED `Entry mode: migration` or `requirements-driven` has said it runs stages 1-4, so its +# first model write with no plan is refused ONCE (conversion-runbook.md → Entry Modes, "Plan +# before build"). Cheap to clear, never a wall: +# - outside evidence counts (guard rule 6): Adopted at stage 5+, a reasoned `Waived stage 4:`, +# gate-check's readout at Stage 5+, or architecture/build-plan.md plus a module brief (root +# or apps//) — see mxtk_plan_evidence; +# - the clearing commands are gate-check.sh --adopt/--waive and writing the plan, none of which +# goes through here (guard rule 7), and the refusal is ONCE per clone (.mpr-snapshots/ +# .plan-rule-refused): a re-run goes on, tagged "no plan" in every BUILD-LOG row; +# - 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. +POS_NOTE="" +if [ -f "$_XD/_position.sh" ]; then + . "$_XD/_position.sh" + mxtk_pos_read "$PROJECT_ROOT" + if mxtk_pos_undeclared; then + echo "⚠ $MXTK_POS_BANNER" + POS_NOTE="no entry mode declared" + elif [ "$PATCH_MODE" != "1" ] && [ "$POS_BUILD" != poc ] \ + && { [ "$POS_ENTRY" = migration ] || [ "$POS_ENTRY" = requirements-driven ]; } \ + && ! mxtk_plan_evidence "$PROJECT_ROOT"; then + _PLAN_STAMP="$PROJECT_ROOT/.mpr-snapshots/.plan-rule-refused" + _GC="${MXTK_ROOT:-${_TKR:-}}/bin/gate-check.sh" + if [ -f "$_PLAN_STAMP" ]; then + echo "⚠ Plan rule: Entry mode $POS_ENTRY and no plan (Stage 4 not passed or adopted) — refused once already, going on; this row is tagged \"no plan\"." + POS_NOTE="no plan (Entry mode $POS_ENTRY, before Stage 4)" + else + [ -d "$PROJECT_ROOT/.mpr-snapshots" ] || mkdir -p "$PROJECT_ROOT/.mpr-snapshots" + if [ -n "${EPOCHSECONDS:-}" ]; then printf -v _pw '%(%Y-%m-%dT%H:%M:%S%z)T' -1; else _pw="now"; fi + printf '%s %s\n' "$_pw" "$SCRIPT" > "$_PLAN_STAMP" + result_line refused no skipped 1 + echo "✗ Plan rule: Entry mode $POS_ENTRY, and Stage 4 has not passed or been adopted — no build plan, no module briefs. NOTHING was written." + echo " Remedy: run stages 1-4 (conversion-runbook.md), or record why not: $_GC $PROJECT_ROOT --adopt 5 --reason \"...\" (it shows in the register)." + echo " Refused once only: a re-run goes on, and its BUILD-LOG row says \"no plan\"." + log_build "🚫 blocked" "plan rule: Entry mode $POS_ENTRY, no build plan/briefs and Stage 4 not adopted — refused once, nothing written" + exit 1 + fi + fi +fi + # ── STOP-row scan (added 2026-10-14, #349) ─────────────────────────────────── # The toolkit's bin/mdl-scan.sh greps the script for the STOP rows of learned-mdl-preflight.md # that a text pattern identifies — each one a script that passed `mxcli check`, cost a full diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index 9b846294..5d9ed321 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -68,18 +68,20 @@ The stages are the same for everyone; what differs is where you enter and which **The entry mode is a Stage-P interview decision, not a silent inference.** The agent proposes a mode *with evidence* ("you have specs in X and source in Y, so…") and records it `CONFIRMED` in `PROJECT.md` before any stage is skipped. A skipped stage in the wrong mode is a gap; in the confirmed mode it's correct. Classification rules — apply in order, first match wins: -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. +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." (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.) +**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 — 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`. *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.* + | You're starting from… | Mode | Stages that run | What changes | |---|---|---|---| | **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. 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), 5–6 | Stages 1–4 collapse to whatever plan the user already has. 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. | +| **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. | | **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 diff --git a/skills/design-artifacts.md b/skills/design-artifacts.md index cec1c7fc..2ae3add5 100644 --- a/skills/design-artifacts.md +++ b/skills/design-artifacts.md @@ -224,6 +224,30 @@ screen it reuses so a reviewer can trace it. `bin/gate-check.sh`'s Stage-3 gate table against `design/wireframes/*.html` and reports `MANUAL wireframes for inventoried screens` when the build falls short of the inventory. +### 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 +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. +2. Write `design/wireframes/PAGE-MAP.tsv`, one row per page: ``. The path + resolves against `design/wireframes/`, so a supplied file reads + `Orders_List../../prototypes/orders/list.html` (a route form, `…prototype.html#/`, + works too). `check-page-shell.sh`, `page-fidelity.js` (given the mapped file) and + `ui-preflight-pages.md` Step 1 then treat the mapped prototype as the page's wireframe. +3. A supplied design-system stylesheet seeds Step 1 (`mxcli theme create --from `); + do not invent tokens next to it. +4. Buildability pass as `poc-build.md` step 3: each interactive element BUILDABLE or + REDESIGNED/DEVIATION, 0 unchecked; deviations go to the Stage 3 sign-off. +5. A screen with no supplied file is drawn per Step 3; a supplied screen with no requirement goes + to Step 3b. Step 3d's LOOK runs over the supplied prototype. + +**Done when:** "N of N inventoried screens mapped" (every page a row, every row's file on disk: +`check-page-shell.sh` reports a stale row), and the deviation list is in the sign-off. *Failure +(field run, 2026-11): prototypes supplied for every screen, none mapped; ~78 pages built against no +target, missing whole sections the prototypes show.* + --- ## Step 2b: Interaction Model — before the first wireframe diff --git a/skills/ui-preflight-pages.md b/skills/ui-preflight-pages.md index 4ec15e91..fa96d184 100644 --- a/skills/ui-preflight-pages.md +++ b/skills/ui-preflight-pages.md @@ -78,7 +78,9 @@ Read the full wireframe file and extract: | Conditional visibility | Callout notes describing "shown only when…" or "edit mode vs. view mode" states | | Navigation entry point | `.origin` annotation or a nav-link callout stating what opens this page | -**If no wireframe exists:** ⛔ STOP. Report to the main session that the wireframe is missing and that the page script cannot be drafted until one exists. Do not proceed, do not guess layout or bindings, do not ask whether to proceed without one — the wireframe is not optional. See `design-artifacts.md` to produce one first. +**A supplied prototype mapped in `design/wireframes/PAGE-MAP.tsv` IS the wireframe** (`design-artifacts.md` Step 2a): read the mapped file and extract the same table; where it carries no binding annotations, take bindings from the BRD and the module brief. + +**If no wireframe exists** — no `design/wireframes/.html`, and no `PAGE-MAP.tsv` row naming a file or route on disk: ⛔ STOP. Report to the main session that the wireframe is missing and that the page script cannot be drafted until one exists. Do not proceed, do not guess layout or bindings, do not ask whether to proceed without one — the wireframe is not optional. See `design-artifacts.md` to produce one first. **If an annotated `.md` companion exists** (e.g. `item-management.md` alongside `item-management.html`): read it — it often contains the binding table, widget-type decisions, and diff --git a/tests/wave2/fixtures/entry-mode-plan-rule/PROJECT.md b/tests/wave2/fixtures/entry-mode-plan-rule/PROJECT.md new file mode 100644 index 00000000..723fad75 --- /dev/null +++ b/tests/wave2/fixtures/entry-mode-plan-rule/PROJECT.md @@ -0,0 +1,63 @@ +# PROJECT.md — Fixture Decision Register + +Every gate decision lands here as `CONFIRMED` or `ASSUMED`, never silently decided. See +`conversion-runbook.md` §1 for the interview protocol this file supports. + +## Current stage + +**Stage P — Kickoff**, needs attention — gates passed: none yet (derived by gate-check on 2026-11-17; re-run it rather than editing this line). + +Toolkit commit: ff4103b +Exec approval: auto +Permission profile: project +Unit tests default: no +Gate mode: check +Pipeline mode: balanced +Build type: full + + + + + + + + + + + +## Decisions + +| Stage | Decision | Status | Notes | +|---|---|---|---| + +## Change log + +Feedback and change requests, one row each, written BEFORE any edit (`skills/change-intake.md`). Status: open → refined → agreed → applied → proven, or rejected (reason); Closed-by cites the commit, journey or test. Escape a `|` inside the ask as `\|`. + +| CR | Date | Source | Verbatim ask | Class | Size | Entry artifact | Status | Closed-by | +|---|---|---|---|---|---|---|---|---| + +## Open questions + +| # | Question | Raised at | Status | +|---|---|---|---| + +## Assumptions (ASSUMED, unresolved) + +None yet. diff --git a/tests/wave2/fixtures/entry-mode-plan-rule/README.md b/tests/wave2/fixtures/entry-mode-plan-rule/README.md new file mode 100644 index 00000000..34150bc2 --- /dev/null +++ b/tests/wave2/fixtures/entry-mode-plan-rule/README.md @@ -0,0 +1,9 @@ +# entry-mode-plan-rule fixtures + +`PROJECT.md` and `intake.md` are captured verbatim from `bin/init-project.sh` (toolkit commit +`ff4103b`, 2026-11-17) run into an empty git repository with `MXTK_NO_GUIDE=1`; only the project +name in the H1 was changed to `Fixture`. They are the register and intake a project really starts +with, so the position reader is tested against the scaffold's own HTML comments (which name +`--adopt 5` and `Build type`) and the bold `**Stage P — Kickoff**` readout, not against input +written to match the parser. `tests/wave2/test-entry-mode-plan-rule.sh` appends the one line +each case declares. diff --git a/tests/wave2/fixtures/entry-mode-plan-rule/intake.md b/tests/wave2/fixtures/entry-mode-plan-rule/intake.md new file mode 100644 index 00000000..c86bfb23 --- /dev/null +++ b/tests/wave2/fixtures/entry-mode-plan-rule/intake.md @@ -0,0 +1,161 @@ +# intake.md — Stage P Kickoff Interview + +Replace each "_Not yet asked._" line below with a real answer, in one of three forms: + + Answered (CONFIRMED): ... the question was asked and answered + Unverified — how to verify: ... the question WAS asked, the answer is not known yet, + and this line says how it will be established + Assumed (auto-mode): ... Interview mode: auto only — the recommended default; + the full record goes in PROJECT.md + +All three pass gate-check's Stage P (keep the colon right after the parenthesis). +"_Not yet asked._" passes nothing, deliberately: this +file is generated before the interview happens, and a scaffold must never be able to certify +an interview that never took place. Per conversion-runbook.md's interview protocol, every +question is asked in chat and the turn ends to wait for the answer; unknowns the user hands +back ("you decide") are recorded as ASSUMED in PROJECT.md rather than blocking Stage P. + +Question 16 (which kind of build) is asked FIRST, before Q1, at project birth; a project already past kickoff is not asked it. + +**These are the questions only the human can answer.** Anything derivable — where the source +sits, what documents exist, which Mendix version the .mpr targets, whether prior analysis is +present — is the agent's homework, brought back as "I found X, confirm?" rather than asked +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? + +_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 — +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. + +## 2. What is this project, and what is driving it? + +_Not yet asked._ Sets stakes, urgency and the default for Q3 in one answer. (a) POC/demo — +prove feasibility, throwaway output, speed over completeness. (b) Production replacement with +a hard date — licence expiry, platform EOL, contract; fidelity and speed win, improvements +deferred. (c) Production replacement, open-ended — modernisation is part of the goal. Only +the user knows; record the date itself if there is one. + +## 3. Fidelity: port as-is, or improve as we go? + +_Not yet asked._ Default inherited from Q2 — (b) implies as-is, (c) licenses redesign — so +put the inherited default to the user and ask what to override. This decides whether every +Stage 3 fit-gap finding is a gap to close or an opportunity to take. + +## 4. What are we working on: the whole application, or a part of it — and what else does that touch? + +_Not yet asked._ Name the topic in plain words — a feature, a flow, a module, a fix, or the +whole app. Say what else it touches, and name what is explicitly OUT — "out" is the half that +gets forgotten and rebuilt anyway. A module-sized source is the common case and is easy to +mistake for a whole app. Also ask whether there are input documents — user stories, tickets, +a spec: they go in `sources/`, and "none, the app plus my description" is a fine answer. For +an existing app this is settled at Stage 0b, after the map, so +`Unverified — how to verify: named when the change request arrives (Stage 0b)` is a legitimate +kickoff answer. + +## 5. Of what we touch, what must stay exactly as it is? + +_Not yet asked._ Integrations, data contracts, external URLs, scheduled jobs, reports other +systems consume. These are the constraints that invalidate an architecture late and cheaply +if found now; they are rarely visible in the source, because they live in its consumers. For +an existing app the default is that nothing beyond the ask changes — this question names the +things the change must not break. + +## 6. Are there licence/security constraints on storing this client's source in this workspace? + +_Not yet asked._ How to verify: ask the human; not inferable from the code. + +## 7. Is an SME available — who, and at what cadence? + +_Not yet asked._ Availability is not the useful half: an SME who exists but answers in two +weeks reshapes the plan as much as no SME at all. Ask who, for which class of decision, and +what the realistic turnaround is. + +## 8. Anything else — scope, priorities, or worries? + +_Not yet asked._ The standing open-floor question the runbook requires at every checkpoint +(§1). Closed questions capture decisions; they never surface what the user wanted to say +unprompted. "Nothing further" is a valid answer — but it has to be the user's, not assumed. + +## 9. Interview mode: attended (default) or unattended? + +_Not yet asked._ How to verify: ask the user; default is `steering`. Record it as +`Interview mode:` in PROJECT.md: `steering` = every gate question is asked in chat and the agent +waits; `assist` = questions batched at gates, low-consequence ones assumed and reported; `auto` +(opt-in only, explicit request required) = nothing blocks, positions recorded as ASSUMED for +reconciliation. `attended` / `unattended` are accepted aliases for `steering` / `auto`. + +## 10. Is any of this already done outside the toolkit — and where does the pipeline pick up? + +_Not yet asked._ Only relevant when the project did not start here: a build already underway, +analysis that lives in Confluence, a design system someone else owns. Name the stage the toolkit +picks up at and record it — `bin/gate-check.sh --adopt --reason "..."` — so the +earlier stages report WAIVED instead of a red row nobody can ever clear. Answer "starting from +scratch here" and nothing is waived, which is the right answer for most projects. Do NOT infer +this from what happens to be on disk: a missing artifact and an artifact produced elsewhere look +identical, and guessing wrong either nags forever or waives a stage that genuinely still matters. + +## 11. Exec approval: `auto` (default) or `ask`? + +_Not yet asked._ How to verify: ask the user; default is `auto`. Full rule text (what it +gates, the resolution order, the STOP-table carve-out): `bin/lib/wiring-item3.sh` — the same +text every agent's Start-here stamp carries. See `bin/exec-approval.sh --explain` for what is +currently resolved and why; the user switches it, never the agent on its own judgement. + +## 12. Claude Code permissions: `project` (default), `wrappers`, or `full`? + +_Not yet asked._ How to verify: ask the user; default is `project`. `wrappers` = only the +toolkit's safe wrappers run without a prompt. `project` = those plus edits inside this folder and +the everyday test/npm/docker/git-commit commands. `full` = everything, on this person's machine +only (`.claude/settings.local.json`); force-push, `git reset --hard`, `git clean` and `sudo` +still prompt. Record it as `Permission profile:` in PROJECT.md, then run +`bin/install-harness-permissions.sh --profile `; `bin/doctor.sh ` +shows what is in effect. + +## 13. Unit tests (`.test.mdl`): project default `no` (default) or `yes`? + +_Not yet asked._ How to verify: ask the user; default is `no`. Every module already gets UI +journeys and data assertions. Unit tests cost a closed Studio Pro and a snapshot per run, and +agents ran them everywhere when no default was set (toolkit issue #274). With `no`, a module +still flips to `yes` in its brief when it has calculation, mapping or date/money logic, calls Java or REST, or had a bug fixed in that flow (`testing-shape.md` §2). Record it as +`Unit tests default:` in PROJECT.md. + +## 14. Will this project use Marketplace modules — and if so, can you create a Mendix Personal Access Token now? + +_Not yet asked._ `mxcli marketplace install` needs a Mendix PAT, and a confirmed Stage 3 "Buy" +that waits for one at build time tends never to get installed (`gate-check.sh` build-ready +and `exec.sh` now check). If yes or maybe, set the token up now: where to create it, which scope, how to hand +it to mxcli — skills/learned-constants-and-secrets.md § "Creating a PAT for Marketplace +installs". If you cannot create one, name the Mendix admin who can. "No Marketplace modules +expected" is a fine answer; it is revisited at the Stage 3 fit-gap. + +## 15. Pipeline mode: `high-speed`, `balanced` (default) or `high-quality`? + +_Not yet asked._ How to verify: ask the user; default is `balanced`. The trade-off, in plain words: +- **high-speed**: fastest; pages are only polished at module close, so mid-module pages are roughest. +- **balanced**: each changed page gets one quick look and one run of the journeys that reach it; + less time per build row than checking every page after every change (1.4 min less on a 5-page + app in PR #700's experiment; estimated ≥8 min on #686's larger app); pages are polished at + module close. +- **high-quality**: checks every page after every change; slowest, maximum polish while building. +Record it as `Pipeline mode:` in PROJECT.md (no line = balanced). The table is +`skills/iterative-build-loop.md` § "Pipeline mode". + +## 16. Which kind of build — full (default) or POC? + +_Not yet asked._ Ask this FIRST, before Q1, at project birth only; the question is "Which kind of build?" +- **Full build (Recommended)**: the staged pipeline with its gates; for anything that will be maintained or go live. +- **POC build**: a demo-quality app fast: design first, one approval stop, a short must-have list; skips the stage + gates and the heavier checks, and hands over what a full build needs next. Proven on small apps only (`skills/poc-build.md`). + +Record it as `Build type: full | poc` in PROJECT.md, `CONFIRMED` (`ASSUMED` = full, only when the user said "you +decide"; `Interview mode: auto` never picks `poc`). On `poc`: open `skills/poc-build.md` and follow it; the other +intake questions are not asked (its Skipped list). A project already past kickoff is not asked: no line = `full`; if +`--repair-intake` appended this question there, answer it `Unverified — how to verify: began before this question; no line = full`. diff --git a/tests/wave2/test-entry-mode-plan-rule.sh b/tests/wave2/test-entry-mode-plan-rule.sh new file mode 100755 index 00000000..62e4594b --- /dev/null +++ b/tests/wave2/test-entry-mode-plan-rule.sh @@ -0,0 +1,165 @@ +#!/usr/bin/env bash +# test-entry-mode-plan-rule.sh — the declared-position banner and the pipeline-mode plan rule. +# +# usage: bash tests/wave2/test-entry-mode-plan-rule.sh [path-to-exec.sh] +# +# Field (two field runs, 2026-11, unattended, requirements-driven, full spec + prototypes): the +# agent built ~78 pages with no BRDs, blueprint, wireframes or plan; PROJECT.md had no entry-mode +# or position line, and nothing in the toolkit said so. project-bin/_position.sh + exec.sh now: +# +# B no Entry mode and no adoption line → the banner on exec.sh, gate-check.sh's summary and +# status.sh, and "no entry mode declared" in the BUILD-LOG row; the write is NOT refused +# R Entry mode: requirements-driven (or migration, also via the intake answer), no plan → +# 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 +# +# 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 +# init-project.sh, see its README). The stub mxcli REFUSES `check`, so "the write got past the plan +# rule" is observable as exactly one check call, and nothing real is ever written. +set -uo pipefail + +TOOLKIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +SUBJECT="${1:-$TOOLKIT/project-bin/exec.sh}" +case "$SUBJECT" in /*) ;; *) SUBJECT="$PWD/$SUBJECT" ;; esac +GOLD="$TOOLKIT/tests/wave2/fixtures/entry-mode-plan-rule" +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/entry-plan.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: $SUBJECT" + +# mkproj -> sets P +N=0 +mkproj() { + N=$((N+1)); P="$WORK/p$N"; local m="$P" + mkdir -p "$P/bin" "$P/mdlsource" + [ "$1" = multi ] && m="$P/apps/Orders" + mkdir -p "$m/mprcontents" + printf 'not a real model\n' > "$m/$( [ "$1" = multi ] && echo Orders || echo Fixture ).mpr" + printf 'bson\n' > "$m/mprcontents/a.mxunit" + cp "$GOLD/PROJECT.md" "$GOLD/intake.md" "$P/" + [ -n "$2" ] && printf '%s\n' "$2" >> "$P/PROJECT.md" + printf 'CREATE ENTITY Orders.Thing (Name: String);\n' > "$P/mdlsource/01-thing.mdl" + cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/_position.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$P/bin/" + cp "$SUBJECT" "$P/bin/exec.sh" + printf '#!/usr/bin/env bash\necho "Snapshot saved: none"\n' > "$P/bin/snapshot-mpr.sh" + cat > "$P/mxcli" <<'MXCLI' +#!/usr/bin/env bash +case "${1:-}" in + check) echo check >> "$CALLS"; echo "✗ stub refuses [STUB01]" >&2; exit 1 ;; + exec) echo exec >> "$CALLS"; exit 0 ;; +esac +exit 0 +MXCLI + chmod +x "$P/bin/"*.sh "$P/mxcli" + ( cd "$P" && git init -q . && printf '.mpr-snapshots/\ndocs/\n.claude/\n' > .gitignore && git add -A \ + && git -c user.email=t@t -c user.name=t commit -qm fixture ) >/dev/null 2>&1 +} +# run [exec args...] -> OUT, ROW, CALLS_N (check calls) +run() { + rm -rf "$P/docs" "$WORK/calls" + ( cd "$P" && CALLS="$WORK/calls" SP_RESTART=0 MXTK_NO_INSTALL=1 SKIP_DOCTOR=1 TMPDIR="$WORK" \ + ./bin/exec.sh "${@:-mdlsource/01-thing.mdl}" ) >"$WORK/out" 2>&1 + OUT="$(cat "$WORK/out")" + ROW="$(grep '^| ' "$P/docs/BUILD-LOG.md" 2>/dev/null | tail -1)" + CALLS_N="$(grep -c check "$WORK/calls" 2>/dev/null)"; CALLS_N="${CALLS_N:-0}" +} +refused() { case "$OUT" in *"✗ Plan rule"*) [ "$CALLS_N" = 0 ] && case "$OUT" in *"MXTK-RESULT exec verdict=refused applied=no"*) return 0 ;; esac ;; esac; return 1; } +passed() { case "$OUT" in *"✗ Plan rule"*) return 1 ;; esac; [ "$CALLS_N" = 1 ]; } + +for L in single multi; do + echo "-- layout: $L" + # B — nothing declared + mkproj "$L" "" + run + case "$OUT" in *"No entry mode declared: the toolkit treats this project as Stage P, not started."*) ok "B[$L] exec prints the banner" ;; + *) bad "B[$L] exec prints the banner" "$(head -5 "$WORK/out")" ;; esac + passed && ok "B[$L] undeclared is warned, not refused" || bad "B[$L] undeclared is warned, not refused" "calls=$CALLS_N" + case "$ROW" in *"no entry mode declared"*) ok "B[$L] BUILD-LOG row carries the tag" ;; *) bad "B[$L] BUILD-LOG row carries the tag" "$ROW" ;; esac + + # R — requirements-driven, no plan: refused once, then goes on + mkproj "$L" "Entry mode: requirements-driven" + run + refused && ok "R[$L] first write refused, nothing reached check" || bad "R[$L] first write refused" "calls=$CALLS_N $(grep -m2 'Plan rule\|MXTK-RESULT' "$WORK/out")" + case "$OUT" in *"--adopt 5 --reason"*) ok "R[$L] remedy names --adopt 5" ;; *) bad "R[$L] remedy names --adopt 5" ;; esac + case "$ROW" in *"🚫 blocked"*"plan rule"*) ok "R[$L] refusal logged" ;; *) bad "R[$L] refusal logged" "$ROW" ;; esac + case "$OUT" in *"No entry mode declared"*) bad "R[$L] no banner once the mode is declared" ;; *) ok "R[$L] no banner once the mode is declared" ;; esac + run + passed && ok "R[$L] second write goes on (refused once only)" || bad "R[$L] second write goes on" "calls=$CALLS_N" + case "$ROW" in *"no plan (Entry mode requirements-driven"*) ok "R[$L] re-run row tagged no plan" ;; *) bad "R[$L] re-run row tagged no plan" "$ROW" ;; esac + + # C — the real clearing command, on a project that was refused + mkproj "$L" "Entry mode: requirements-driven" + run + "$TOOLKIT/bin/gate-check.sh" "$P" --adopt 5 --reason "plan kept outside the toolkit" >/dev/null 2>&1 + grep -q '^Adopted at stage: 5' "$P/PROJECT.md" && ok "C[$L] --adopt 5 writes the register line" || bad "C[$L] --adopt 5 writes the register line" + rm -f "$P/.mpr-snapshots/.plan-rule-refused" + run + passed && ok "C[$L] adopted at 5 → no refusal" || bad "C[$L] adopted at 5 → no refusal" "calls=$CALLS_N" + case "$ROW" in *"no plan"*) bad "C[$L] no 'no plan' tag after adoption" "$ROW" ;; *) ok "C[$L] no 'no plan' tag after adoption" ;; esac + + # C — a build plan + a module brief (outside evidence, not the toolkit's stamp) + mkproj "$L" "Entry mode: migration" + if [ "$L" = multi ]; then A="$P/apps/Orders/architecture"; else A="$P/architecture"; fi + mkdir -p "$A/modules/Orders" + printf '# Build plan\n\n| # | Step |\n|---|---|\n| 1 | Orders domain |\n' > "$A/build-plan.md" + printf '# Module brief — Orders\n' > "$A/modules/Orders/module-brief.md" + run + passed && ok "C[$L] build plan + brief → no refusal" || bad "C[$L] build plan + brief → no refusal" "calls=$CALLS_N" +done + +echo "-- single tree only" +# C — brief inline in the plan +mkproj single "Entry mode: requirements-driven" +mkdir -p "$P/architecture"; printf '# Build plan\n\n## Module brief — Orders\n\nScreens: list, detail.\n' > "$P/architecture/build-plan.md" +run; passed && ok "C inline '## Module brief' heading → no refusal" || bad "C inline brief heading" "calls=$CALLS_N" +# a build plan without any brief is not a plan the rule accepts +mkproj single "Entry mode: requirements-driven" +mkdir -p "$P/architecture"; printf '# Build plan\n' > "$P/architecture/build-plan.md" +run; refused && ok "R a plan with no brief is still refused" || bad "R a plan with no brief is still refused" "calls=$CALLS_N" + +# R — migration declared only in the intake answer (no register line) +mkproj single "" +awk '{ print } /^## 1\. Entry mode/ { print ""; print "Answered: migration" }' "$P/intake.md" > "$P/intake.new" && mv "$P/intake.new" "$P/intake.md" +grep -q '^Answered: migration' "$P/intake.md" || bad "setup: intake answer not written" +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 + 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 +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" +run; passed && ok "N Build type: poc → no refusal" || bad "N Build type: poc → no refusal" "calls=$CALLS_N" +# --patch: opaque repair path, never the plan rule (the script itself fails; we only look for the rule) +mkproj single "Entry mode: requirements-driven" +printf '#!/usr/bin/env bash\nexit 3\n' > "$P/patch.sh"; chmod +x "$P/patch.sh" +run --patch patch.sh +case "$OUT" in *"Plan rule"*) bad "N --patch never meets the plan rule" "$(grep -m1 'Plan rule' "$WORK/out")" ;; *) ok "N --patch never meets the plan rule" ;; esac +[ -f "$P/.mpr-snapshots/.plan-rule-refused" ] && bad "N --patch left a refusal stamp" || ok "N --patch left no refusal stamp" + +echo "-- gate-check.sh summary and status.sh" +mkproj single "" +GC="$("$TOOLKIT/bin/gate-check.sh" "$P" 2>&1)" +case "$GC" in *"Summary:"*"No entry mode declared"*) ok "B gate-check summary carries the banner" ;; *) bad "B gate-check summary carries the banner" ;; esac +ST="$("$TOOLKIT/bin/status.sh" "$P" --brief 2>&1)" +case "$ST" in *"No entry mode declared"*) ok "B status --brief carries the banner" ;; *) bad "B status --brief carries the banner" ;; esac +case "$ST" in *"NEXT declare the entry mode"*) ok "B status NEXT says declare the mode" ;; *) bad "B status NEXT says declare the mode" "$(printf '%s\n' "$ST" | grep NEXT)" ;; esac +mkproj single "Entry mode: requirements-driven" +GC="$("$TOOLKIT/bin/gate-check.sh" "$P" 2>&1)" +case "$GC" in *"No entry mode declared"*) bad "gate-check silent once declared" ;; *) ok "gate-check silent once declared" ;; esac +mkproj single "Entry mode: a-la-carte" +GC="$("$TOOLKIT/bin/gate-check.sh" "$P" 3 2>&1)" +case "$GC" in *"a-la-carte entry mode — no pipeline"*) ok "a-la-carte stages read WAIVED with the reason" ;; *) bad "a-la-carte stages read WAIVED with the reason" "$(printf '%s\n' "$GC" | grep -m2 '^Stage [0-3]')" ;; esac + +echo "" +echo "== $PASS passed, $FAIL failed" +[ "$FAIL" -eq 0 ] From 1da1d80db62850ea39524de1d218b31d2f7872c1 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:34:25 +0000 Subject: [PATCH 02/14] process(entry modes): mode contract, unattended-first plan rule, register skeleton - artifact-manifest.tsv modes column is the per-mode step list (vocabulary migration, requirements-driven, poc, existing-app, a-la-carte, all); dropped rows read "not owed (mode ...)". Build type: poc mode-waives stages 0-4, 6, 7 in gate-check. - Interview mode: auto: exec.sh refuses every pipeline-mode write until gate-check build-ready has passed (new .build-ready-pass record) or an adoption/stage-4 waiver exists; --adopt 4+ under auto writes an ASSUMED consentBy: auto-mode decision row (Stage 6 FAILs until confirmed). - "Mode changes are decisions": one rule in the runbook; poc-build points. - init/sync append missing register sections to a hand-written PROJECT.md (bin/lib/register-skeleton.sh, one template; fresh scaffold unchanged). - CONVERSION-RUNBOOK.md "Running unattended": the one kick-off brief. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8 --- CHANGELOG.md | 1 + CONVERSION-RUNBOOK.md | 22 ++++ bin/gate-check.sh | 63 +++++++++++- bin/init-project.sh | 114 +++++++-------------- bin/lib/artifact-check.sh | 15 +-- bin/lib/artifact-manifest.tsv | 91 +++++++++-------- bin/lib/closeout.sh | 4 +- bin/lib/register-skeleton.sh | 118 +++++++++++++++++++++ bin/sync-project.sh | 11 ++ project-bin/_position.sh | 13 ++- project-bin/exec.sh | 19 +++- project-bin/progress-report.py | 6 +- skills/conversion-runbook.md | 4 +- skills/poc-build.md | 2 +- tests/wave2/test-closeout.sh | 2 +- tests/wave2/test-entry-mode-plan-rule.sh | 2 +- tests/wave2/test-mode-contract.sh | 124 +++++++++++++++++++++++ 17 files changed, 469 insertions(+), 142 deletions(-) create mode 100755 bin/lib/register-skeleton.sh create mode 100755 tests/wave2/test-mode-contract.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index cf1ecfe6..094d26e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m `docs/RELEASE-PROCESS.md` §8. ## Unreleased +- process(entry modes, unattended): **the mode contract, and unattended as the primary case** (stacked on the plan-rule PR): `bin/lib/artifact-manifest.tsv`'s modes column is now the per-mode step list, vocabulary `migration`, `requirements-driven`, `poc`, `existing-app`, `a-la-carte`, `all` (+ `greenfield` until retired), and a row a mode drops reads "not owed (mode …)", never PASS; `Build type: poc` is its own contract, so gate-check reads Stages 0–4, 6, 7 "not owed (mode: Build type: poc)" instead of PENDING (`poc-build.md` updated). Under `Interview mode: auto`, `exec.sh` refuses EVERY MDL write of a migration/requirements-driven project until `gate-check.sh

build-ready` has passed (its PASS now leaves `.mpr-snapshots/.build-ready-pass`) or the register adopts at 5+ / waives Stage 4 — no refuse-once, and a plan on disk alone does not clear it; interactive runs keep refuse-once. `--adopt` at 4+ under auto on those modes also writes an ASSUMED `consentBy: auto-mode` Stage-3/4 row, so `auto_hand_pending()` lists it and Stage 6 FAILs until a person confirms. "Mode changes are decisions" is stated once, in the runbook's Entry Modes (`poc-build.md` points to it). `init-project.sh` and `sync-project.sh` append the missing register sections (Current stage, Decisions, Open questions, Change log) to a PROJECT.md written by hand before init, loudly, from one template (`bin/lib/register-skeleton.sh`; a fresh scaffold is byte-identical to before), and the generated `CLAUDE.local.md` says init runs before any PROJECT.md or model write. `CONVERSION-RUNBOOK.md` gains "Running unattended", the one kick-off brief a project quotes. Fixture `tests/wave2/test-mode-contract.sh` — owner design input + a research comparison of five field builds that followed the process with the one that did not (Nov 2026) - process(exec, entry modes): **the entry mode is a declared fact every tool reads, and a pipeline-mode project no longer builds without a plan by default**: with no `Entry mode:` and no `Adopted at stage:` line (register or intake), `bin/status.sh` (both views, plus a NEXT rule), `bin/gate-check.sh`'s summary and every `bin/exec.sh` run print one banner, and the BUILD-LOG row is tagged `no entry mode declared`; warn-only. In `Entry mode: migration` or `requirements-driven`, the first MDL write with no plan evidence is refused ONCE (nothing locked, snapshotted or written; `verdict=refused`), remedy in one line: run stages 1–4, or `gate-check.sh --adopt 5 --reason ...`. Cleared by outside evidence (guard rule 6): adoption at 5+, a reasoned `Waived stage 4:`, gate-check's readout at Stage 5+, or `architecture/build-plan.md` plus a module brief (root or `apps//`); a re-run after the one refusal goes on, tagged `no plan`. Never refused: `a-la-carte` (new explicit mode: no pipeline, audit or tooling use; gate-check reads its stages WAIVED by mode), `greenfield`, `Build type: poc`, change an existing app, `--patch`. The one entry-mode tokeniser moves to `project-bin/_position.sh` (pure bash, no process starts; installed beside exec.sh, `bin/lib/entry-mode.sh` is now a shim) — identical output on 44 inputs against the old one. Runbook: greenfield's "stages 1–4 collapse to whatever plan the user already has" becomes a design front end (`poc-build.md` steps 1–4, then a short plan with a few lines per module); `design-artifacts.md` Step 2a adopts a supplied prototype by mapping every screen in `design/wireframes/PAGE-MAP.tsv`, and `ui-preflight-pages.md`'s wireframe STOP accepts a mapped prototype. Fixture `tests/wave2/test-entry-mode-plan-rule.sh` (single tree + `apps//`, register and intake captured from `init-project.sh`) — two field runs, Nov 2026, requirements-driven with a frozen spec and clickable prototypes: ~78 pages built with no plan or target - fix(status, agents): **`bin/status.sh` WATCHes an Agent Editor project whose extension module does not travel with the model (#778)**: Studio Pro reads `agenteditor.agent` from `modules/AgentEditor.mxmodule` beside the `.mpr`, and a sync of only `.mpr` + `mprcontents/` left it out of git, so the builder stayed green while every colleague's clone showed `unknown type 'agenteditor.agent'`. Two WATCH items, warn-only (exit code and every verdict unchanged), local files and `git ls-files` only, root and `app/` layouts: a `modules/*.mxmodule` git does not track, and a project using Agent Editor (`AgentEditorCommons` in `analysis/app-facts/inventory.json`, or a `create agent` statement in `mdlsource/`) with no `modules/AgentEditor*.mxmodule`. `skills/mendix-agents.md` (on demand) gains the rule plus the note that the GenAI key, `Encryption.EncryptionKey` and `GenAICommons.StoreTraces` belong in the Default configuration, not a start script. Empty agent references / missing model version (mendixlabs/mxcli#1867) and unset runtime constants are not checked: they need a captured agent document (option 2). Fixture `tests/wave2/test-status-extension-modules.sh` — field report from an Agent Editor project, Nov 2026 - fix(permissions): **exec approval `auto` no longer prompts on every exec's mode check, and `install-claude-hooks.sh` no longer runs unprompted (#782)**: `install-claude-permissions.sh` now allow-lists `exec-approval.sh`, `interview-mode.sh` and `permission-profile.sh`, so their reads run without a prompt, while their only writers, `--set` and `--clear`, prompt through six `ask` rules (`Bash(*exec-approval.sh*--set*)`, …) in the shared settings under every profile (an ask rule beats an allow rule, `full`'s bare `Bash` included). `install-claude-hooks.sh`, which writes `~/.claude/settings.json` for every repo on the machine, gets no allow rule. A re-install adds the ask rules and removes the hooks-installer rule an earlier install added (sidecar); entries someone else wrote are untouched, and `sync-project.sh`'s permission check names both until then. Field run on claude 2.1.325: the read ran, `--set auto` and `--clear` were refused, and with the ask rules removed `--set` ran — from the two independent reviews of #781 diff --git a/CONVERSION-RUNBOOK.md b/CONVERSION-RUNBOOK.md index 603fb125..33f5a994 100644 --- a/CONVERSION-RUNBOOK.md +++ b/CONVERSION-RUNBOOK.md @@ -24,6 +24,28 @@ Then open your agent (Claude Code or equivalent) in `` and say wha | Just an idea / existing plan | Greenfield | P (light), 5–6 | | A live Mendix app you are changing | Change an existing app | P, 0–6 per change | +## Running unattended — the kick-off brief + +**The single source of the text an unattended run (`Interview mode: auto`) is started with.** A +project brief quotes it, verbatim, instead of writing its own; add the project's own goal and +sources under it, never a different definition of done. + +```text +Follow the toolkit's process: skills/conversion-runbook.md, from Stage P, stage by stage. +1. Run bin/init-project.sh first, before writing PROJECT.md or touching the model. +2. Declare the entry mode and build type at kickoff (intake Q1 and Q16); never switch them later + without a recorded decision (conversion-runbook.md → Entry Modes, "Mode changes are decisions"). +3. Stage 5 only after stages 1-4 pass their gates and bin/gate-check.sh

build-ready passes. +4. Close every stage on a clean gate (bin/gate-check.sh

) and commit its output. +5. Stop at a gate that does not pass; report it, do not route around it. +"Done" is the declared mode's steps done and their gates clean — not only journeys passing. +``` + +*Failure it prevents (two field runs, 2026-11):* the project instructions said "follow the +runbook", but the brief the agent read first defined done as journeys passing under a time +budget and never mentioned stages. The agent built about 78 pages with no plan. Five earlier field +builds, whose briefs said in effect what the lines above say, followed the stages. + ## Where you run this — detected, not asked You do not pick an environment; `bin/doctor.sh` detects it from where the session started, and diff --git a/bin/gate-check.sh b/bin/gate-check.sh index 22db54a3..074a1be8 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -688,6 +688,8 @@ fi # then excused stages on that label. See bin/lib/entry-mode.sh for why. . "$(cd "$(dirname "${BASH_SOURCE[0]}")/lib" && pwd)/entry-mode.sh" ENTRY_MODE="$(entry_mode_token "$ENTRY_RAW")" +BUILD_TYPE="$(reg_field "build type" 2>/dev/null || true)" +case "$(printf '%s' "$BUILD_TYPE" | tr '[:upper:]' '[:lower:]')" in poc|poc[!a-z]*) BUILD_TYPE=poc ;; *) BUILD_TYPE=full ;; esac # stage_waiver — "|", or nothing. Most specific source of truth first. # @@ -728,24 +730,33 @@ stage_waiver() { "$ADOPTED_AT" "${ADOPTED_REASON:+: $ADOPTED_REASON}" return 0 fi + # The mode contract (conversion-runbook.md → Entry Modes; artifact-manifest.tsv column 6). + # `Build type: poc` is its own contract whatever the entry mode: skills/poc-build.md owes its + # steps and must-haves, not stage gates, so 0-4, 6 and 7 read "not owed (mode)" instead of a + # PENDING row nobody may clear. Stage 5 stays checked (MANUAL), and P (the build-type answer). + if [ "$BUILD_TYPE" = poc ]; then + case "$st" in + [0-4]|6|7) printf 'mode|not owed (mode: Build type: poc) — skills/poc-build.md owes steps 1–9 and its must-haves instead\n'; return 0 ;; + esac + fi # 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|greenfield entry mode — stages 1–4 collapse into the design front end and short plan (conversion-runbook.md → Entry Modes)\n'; return 0 ;; + 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|requirements-driven entry mode — 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 ;; + 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 ;; esac ;; existing-app-change) case "$st" in - 7) printf 'mode|existing-app entry mode — the app is live and stays live; there is no cutover (existing-app-change.md → Deliverables)\n'; return 0 ;; + 7) printf 'mode|not owed (mode: existing-app) — the app is live and stays live; there is no cutover (existing-app-change.md → Deliverables)\n'; return 0 ;; esac ;; a-la-carte) case "$st" in - [0-7]) printf 'mode|a-la-carte entry mode — no pipeline: audit or tooling use only (existing-app-assurance.md); declare another mode to run the stages\n'; return 0 ;; + [0-7]) printf 'mode|not owed (mode: a-la-carte) — no pipeline: audit or tooling use only (existing-app-assurance.md); declare another mode to run the stages\n'; return 0 ;; esac ;; esac return 1 @@ -3204,6 +3215,25 @@ register_set_line() { # register_set_line

build-ready` has PASSed (it leaves .mpr-snapshots/.build-ready-pass), or + # the register adopts at 5+ / waives Stage 4 — an adoption under auto is recorded as a ✋ + # human-pending decision that keeps Stage 6 FAILing until a person confirms it. A plan on disk + # alone does not clear it: nobody has checked it. Neither remedy runs through exec.sh. + _GC="${MXTK_ROOT:-${_TKR:-}}/bin/gate-check.sh" + result_line refused no skipped 1 + echo "✗ Plan rule (Interview mode: auto): Entry mode $POS_ENTRY, and the pre-build steps are not done — $_GC $PROJECT_ROOT build-ready has not passed. NOTHING was written." + echo " Remedy: run stages 1-4, then $_GC $PROJECT_ROOT build-ready; or $_GC $PROJECT_ROOT --adopt 5 --reason \"...\" — under auto that is a ✋ human-pending decision, and Stage 6 FAILs until a person confirms it." + log_build "🚫 blocked" "plan rule (auto): Entry mode $POS_ENTRY, build-ready not passed and no adoption — nothing written" + exit 1 + elif [ "$PATCH_MODE" != "1" ] && [ "$POS_BUILD" != poc ] && [ "$POS_AUTO" != 1 ] \ && { [ "$POS_ENTRY" = migration ] || [ "$POS_ENTRY" = requirements-driven ]; } \ && ! mxtk_plan_evidence "$PROJECT_ROOT"; then _PLAN_STAMP="$PROJECT_ROOT/.mpr-snapshots/.plan-rule-refused" diff --git a/project-bin/progress-report.py b/project-bin/progress-report.py index 7f64b779..0f529d8a 100755 --- a/project-bin/progress-report.py +++ b/project-bin/progress-report.py @@ -196,7 +196,9 @@ 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 + # The mode-contract vocabulary of artifact-manifest.tsv column 6 (Build type: poc is its own contract). + info["entry_mode"] = "requirements-driven" if em.startswith("requirements") else "existing-app" if em.startswith(("existing", "change")) else em + if re.search(r"(?im)^[\s>*_-]*Build type\s*\**\s*:\s*\**\s*poc\b", md): info["entry_mode"] = "poc" 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): @@ -342,7 +344,7 @@ def load_manifest(toolkit, mode): for line in txt.splitlines(): if not line.strip() or line.startswith("#"): continue c = line.split("\t") - if len(c) >= 7 and c[1] in STAGES and mode in c[5].split(",") and c[0] not in WAIVED: + if len(c) >= 7 and c[1] in STAGES and (mode in c[5].split(",") or "all" in c[5].split(",")) and c[0] not in WAIVED: rows.append({"id": c[0], "stage": c[1], "paths": c[2].split("|"), "absence": c[6].strip()}) return rows diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index 5d9ed321..ace29668 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -75,7 +75,9 @@ The stages are the same for everyone; what differs is where you enter and which (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.) -**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 — 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`. *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.* +**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 — 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". + +**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.* | You're starting from… | Mode | Stages that run | What changes | |---|---|---|---| diff --git a/skills/poc-build.md b/skills/poc-build.md index c7d63c66..4b096ed5 100644 --- a/skills/poc-build.md +++ b/skills/poc-build.md @@ -5,7 +5,7 @@ **Status: EXPERIMENTAL.** Two builds driven by this text, one model, small apps. First (fictional visitor-pass app, ~36 min): "nearly demo-ready", function 26 of 29, design ~4.1 of 5 (not blind), journey 22/22. Second (kickoff question asked first, answered POC; ~64 min): a blind grader compared it with the same requirements built in plain plan mode with no toolkit: function 25 of 25 against 24 of 24 testable; refusals in-page 7 of 7 against 2 of 6; must-haves 10 of 10 against 5 of 10; visual mean 3.8 against 3.6; hand-over 22 of 24 against 12 of 24; time ~64 against ~27 min (both ran in parallel, inflated). The gain is the must-have list and the hand-over, not the look, and it costs time. NOT proven: a real person answering (answers and approval came from a prepared file). The test cadence (steps 7–8) changed after both builds (#770) and is unmeasured. -**Who asks.** The kickoff interview asks the build type first, at project birth (intake Q16; rendering per `skills/interview-protocol.md` §3). On a POC answer `Build type: poc` is recorded `CONFIRMED` in `PROJECT.md`, and this skill is the flow; the other intake questions are not asked. A missing `Build type:` line means `full`; `Interview mode: auto` never picks `poc`. A project past kickoff whose user only says "we need a demo this week" does NOT switch: the lead says in one line that the build type is chosen at the start and offers to continue the normal build (optionally `Pipeline mode: high-speed`). Switching such a project needs the user to say so explicitly, confirmed once, and is recorded in `PROJECT.md` as a decision. *Failure: a Stage 5 project whose user mentioned a demo dropped its gates.* A POC build does **not** run the nine stage gates. Stage P still checks that every `intake.md` question carries an answer marker, so write them: Q16 `Answered (CONFIRMED): POC build`, and under each of Q1–Q15 exactly `Unverified — how to verify: not asked, POC build (Build type: poc, skills/poc-build.md); ask it if the build continues as a full build`. Then `bin/gate-check.sh` shows Stage P `PASS` (markers present; it says nothing about those answers), Stages 0–4, 6, 7 `PENDING`, Stage 5 `MANUAL`. *Failure: unmarked questions kept Stage P at `FAIL` for the whole build.* No answer: end the turn and wait (`skills/interview-protocol.md` §3); `ASSUMED` only when the user said "you decide" (= `full`). +**Who asks.** The kickoff interview asks the build type first, at project birth (intake Q16; rendering per `skills/interview-protocol.md` §3). On a POC answer `Build type: poc` is recorded `CONFIRMED` in `PROJECT.md`, and this skill is the flow; the other intake questions are not asked. A missing `Build type:` line means `full`; `Interview mode: auto` never picks `poc`. A project past kickoff whose user only says "we need a demo this week" does NOT switch: the lead says in one line that the build type is chosen at the start and offers to continue the normal build (optionally `Pipeline mode: high-speed`). Switching follows the runbook's "Mode changes are decisions" (`conversion-runbook.md` → Entry Modes), the one statement of that rule. A POC build does **not** run the nine stage gates. Stage P still checks that every `intake.md` question carries an answer marker, so write them: Q16 `Answered (CONFIRMED): POC build`, and under each of Q1–Q15 exactly `Unverified — how to verify: not asked, POC build (Build type: poc, skills/poc-build.md); ask it if the build continues as a full build`. Then `bin/gate-check.sh` shows Stage P `PASS` (markers present; it says nothing about those answers), Stages 0–4, 6, 7 `WAIVED` — "not owed (mode: Build type: poc)", the mode contract — and Stage 5 `MANUAL`. *Failure: unmarked questions kept Stage P at `FAIL` for the whole build.* No answer: end the turn and wait (`skills/interview-protocol.md` §3); `ASSUMED` only when the user said "you decide" (= `full`). **Size:** more than 3 entities, 5 pages or 2 roles is unmeasured. Say so once, then continue: a warning, not a refusal (*failure: an agent that refuses, or proceeds without a word*). diff --git a/tests/wave2/test-closeout.sh b/tests/wave2/test-closeout.sh index 4d0cc714..3a51f2d2 100755 --- a/tests/wave2/test-closeout.sh +++ b/tests/wave2/test-closeout.sh @@ -122,7 +122,7 @@ echo "== T8: --closeout without a stage refuses ==" echo "== T9: a row the entry mode does not owe is N/A, never 'still missing' (2026-09-25) ==" P="$(mkproj t9)" OUT="$("$GATE" --closeout "$P" 0 2>&1)" -case "$OUT" in *"⏭ \`app-report\` — N/A: entry mode requirements does not owe it"*) ok "app-report N/A on a requirements-driven register" ;; *) bad "app-report not N/A: $(printf '%s' "$OUT" | grep app-report)" ;; esac +case "$OUT" in *"⏭ \`app-report\` — N/A: not owed (mode requirements-driven)"*) ok "app-report N/A on a requirements-driven register" ;; *) bad "app-report not N/A: $(printf '%s' "$OUT" | grep app-report)" ;; esac if printf '%s\n' "$OUT" | grep 'still missing for this stage' | grep -q 'app-report'; then bad "plain words list app-report as missing"; else ok "plain words do not list a row this mode does not owe"; fi rm -rf "$WORK" diff --git a/tests/wave2/test-entry-mode-plan-rule.sh b/tests/wave2/test-entry-mode-plan-rule.sh index 62e4594b..abf05fcf 100755 --- a/tests/wave2/test-entry-mode-plan-rule.sh +++ b/tests/wave2/test-entry-mode-plan-rule.sh @@ -158,7 +158,7 @@ GC="$("$TOOLKIT/bin/gate-check.sh" "$P" 2>&1)" case "$GC" in *"No entry mode declared"*) bad "gate-check silent once declared" ;; *) ok "gate-check silent once declared" ;; esac mkproj single "Entry mode: a-la-carte" GC="$("$TOOLKIT/bin/gate-check.sh" "$P" 3 2>&1)" -case "$GC" in *"a-la-carte entry mode — no pipeline"*) ok "a-la-carte stages read WAIVED with the reason" ;; *) bad "a-la-carte stages read WAIVED with the reason" "$(printf '%s\n' "$GC" | grep -m2 '^Stage [0-3]')" ;; esac +case "$GC" in *"not owed (mode: a-la-carte) — no pipeline"*) ok "a-la-carte stages read WAIVED with the reason" ;; *) bad "a-la-carte stages read WAIVED with the reason" "$(printf '%s\n' "$GC" | grep -m2 '^Stage [0-3]')" ;; esac echo "" echo "== $PASS passed, $FAIL failed" diff --git a/tests/wave2/test-mode-contract.sh b/tests/wave2/test-mode-contract.sh new file mode 100755 index 00000000..c29f47c9 --- /dev/null +++ b/tests/wave2/test-mode-contract.sh @@ -0,0 +1,124 @@ +#!/usr/bin/env bash +# test-mode-contract.sh — the mode contract under Interview mode: auto, the ✋ adoption, POC's +# "not owed (mode)", and init/sync laying down a register over a hand-written PROJECT.md. +# +# usage: bash tests/wave2/test-mode-contract.sh [path-to-exec.sh] +# +# Owner design input (2026-11-17): unattended is the primary case. Field basis: two field runs +# (2026-11, auto, requirements-driven) built ~78 pages with no plan; one had a hand-written +# 10-line PROJECT.md that init-project.sh then skipped in silence. +# +# A auto + requirements-driven, no build-ready: EVERY write refused (no refuse-once), a plan +# on disk does not clear it, the build-ready stamp does, an --adopt 5 does +# H --adopt 5 under auto writes an ASSUMED consentBy: auto-mode Stage-4 row, and gate-check +# lists it as a ✋ decision to confirm; without auto no row is written +# K Build type: poc → gate-check reads Stages 0-4, 6, 7 "not owed (mode: Build type: poc)"; +# artifact rows not listed for poc read "not owed (mode poc" +# G init-project.sh over a hand-written PROJECT.md appends Current stage, Decisions, Open +# questions and Change log, says so, and keeps the hand-written lines +# +# Golden register + intake: fixtures/entry-mode-plan-rule/ (captured from init-project.sh). +set -uo pipefail + +TOOLKIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +SUBJECT="${1:-$TOOLKIT/project-bin/exec.sh}" +case "$SUBJECT" in /*) ;; *) SUBJECT="$PWD/$SUBJECT" ;; esac +GOLD="$TOOLKIT/tests/wave2/fixtures/entry-mode-plan-rule" +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/mode-contract.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: $SUBJECT" + +# mkproj -> sets P +N=0 +mkproj() { + N=$((N+1)); P="$WORK/p$N"; local m="$P" + mkdir -p "$P/bin" "$P/mdlsource" + [ "$1" = multi ] && m="$P/apps/Orders" + mkdir -p "$m/mprcontents" + printf 'not a real model\n' > "$m/$( [ "$1" = multi ] && echo Orders || echo Fixture ).mpr" + printf 'bson\n' > "$m/mprcontents/a.mxunit" + cp "$GOLD/PROJECT.md" "$GOLD/intake.md" "$P/" + [ -n "$2" ] && printf '%s\n' "$2" >> "$P/PROJECT.md" + printf 'CREATE ENTITY Orders.Thing (Name: String);\n' > "$P/mdlsource/01-thing.mdl" + cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/_position.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$P/bin/" + cp "$SUBJECT" "$P/bin/exec.sh" + printf '#!/usr/bin/env bash\necho "Snapshot saved: none"\n' > "$P/bin/snapshot-mpr.sh" + cat > "$P/mxcli" <<'MXCLI' +#!/usr/bin/env bash +case "${1:-}" in + check) echo check >> "$CALLS"; echo "✗ stub refuses [STUB01]" >&2; exit 1 ;; + exec) echo exec >> "$CALLS"; exit 0 ;; +esac +exit 0 +MXCLI + chmod +x "$P/bin/"*.sh "$P/mxcli" + ( cd "$P" && git init -q . && printf '.mpr-snapshots/\ndocs/\n.claude/\n' > .gitignore && git add -A \ + && git -c user.email=t@t -c user.name=t commit -qm fixture ) >/dev/null 2>&1 +} +# run [exec args...] -> OUT, ROW, CALLS_N (check calls) +run() { + rm -rf "$P/docs" "$WORK/calls" + ( cd "$P" && CALLS="$WORK/calls" SP_RESTART=0 MXTK_NO_INSTALL=1 SKIP_DOCTOR=1 TMPDIR="$WORK" \ + ./bin/exec.sh "${@:-mdlsource/01-thing.mdl}" ) >"$WORK/out" 2>&1 + OUT="$(cat "$WORK/out")" + ROW="$(grep '^| ' "$P/docs/BUILD-LOG.md" 2>/dev/null | tail -1)" + CALLS_N="$(grep -c check "$WORK/calls" 2>/dev/null)"; CALLS_N="${CALLS_N:-0}" +} +refused() { case "$OUT" in *"✗ Plan rule"*) [ "$CALLS_N" = 0 ] && case "$OUT" in *"MXTK-RESULT exec verdict=refused applied=no"*) return 0 ;; esac ;; esac; return 1; } +passed() { case "$OUT" in *"✗ Plan rule"*) return 1 ;; esac; [ "$CALLS_N" = 1 ]; } + + +autorefused() { case "$OUT" in *"✗ Plan rule (Interview mode: auto)"*) [ "$CALLS_N" = 0 ] ;; *) return 1 ;; esac; } +GC="$TOOLKIT/bin/gate-check.sh" + +echo "-- A: auto mode" +mkproj single "Entry mode: requirements-driven" +printf 'Interview mode: auto\n' >> "$P/PROJECT.md" +run; autorefused && ok "A first write refused" || bad "A first write refused" "calls=$CALLS_N" +case "$OUT" in *"✋ human-pending"*) ok "A remedy says an adoption is ✋ human-pending" ;; *) bad "A remedy says an adoption is ✋ human-pending" ;; esac +run; autorefused && ok "A second write refused too (no refuse-once under auto)" || bad "A second write refused too" "calls=$CALLS_N" +mkdir -p "$P/architecture/modules/Orders"; printf '# Build plan\n' > "$P/architecture/build-plan.md"; printf '# Module brief — Orders\n' > "$P/architecture/modules/Orders/module-brief.md" +run; autorefused && ok "A a plan on disk alone does not clear it under auto" || bad "A plan on disk alone" "calls=$CALLS_N" +mkdir -p "$P/.mpr-snapshots"; printf 'x build-ready PASS\n' > "$P/.mpr-snapshots/.build-ready-pass" +run; passed && ok "A the build-ready record clears it" || bad "A the build-ready record clears it" "calls=$CALLS_N" +mkproj single "Entry mode: migration" +printf 'Interview mode: auto\n' >> "$P/PROJECT.md" +CLAUDE_INTERVIEW_MODE= "$GC" "$P" --adopt 5 --reason "plan kept outside the toolkit" > "$WORK/adopt.out" 2>&1 +run; passed && ok "A --adopt 5 clears it" || bad "A --adopt 5 clears it" "calls=$CALLS_N" + +echo "-- H: the ✋ adoption" +grep -qE '^\| 4 \| Adopted at stage 5 .*\| ASSUMED \| consentBy: auto-mode · consentAt: [0-9]' "$P/PROJECT.md" \ + && ok "H ASSUMED auto-mode Stage-4 row written" || bad "H ASSUMED auto-mode Stage-4 row written" "$(grep -n 'Adopted' "$P/PROJECT.md")" +grep -q "human-pending" "$WORK/adopt.out" && ok "H --adopt says it is human-pending" || bad "H --adopt says it is human-pending" +G="$("$GC" "$P" 2>&1)" +case "$G" in *"✋ decision(s) assumed by auto-mode"*"(Stage 4)"*) ok "H gate-check lists it to confirm" ;; *) bad "H gate-check lists it to confirm" ;; esac +mkproj single "Entry mode: migration" +"$GC" "$P" --adopt 5 --reason "plan kept outside the toolkit" >/dev/null 2>&1 +grep -q "consentBy: auto-mode" "$P/PROJECT.md" && bad "H no ✋ row without auto" || ok "H no ✋ row without auto" + +echo "-- K: Build type: poc" +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" +G="$("$GC" "$P" 2>&1)" +n="$(printf '%s\n' "$G" | grep -cE '^Stage [0-4] .*not owed \(mode: Build type: poc\)|^Stage [67] .*not owed \(mode: Build type: poc\)')" +[ "$n" = 7 ] && ok "K stages 0-4, 6, 7 not owed (mode) — 7 of 7" || bad "K stages 0-4, 6, 7 not owed (mode)" "$n of 7" +case "$G" in *"not owed (mode poc"*) ok "K artifact rows say not owed (mode poc)" ;; *) bad "K artifact rows say not owed (mode poc)" ;; esac + +echo "-- G: init over a hand-written PROJECT.md" +Q="$WORK/hand"; mkdir -p "$Q"; ( cd "$Q" && git init -q . ) +printf '# My project\n\nEntry mode: requirements-driven\nRequirements live in specs/.\n' > "$Q/PROJECT.md" +MXTK_NO_GUIDE=1 HOME="$WORK/home" "$TOOLKIT/bin/init-project.sh" "$Q" > "$WORK/init.out" 2>&1 +case "$(cat "$WORK/init.out")" in *"PROJECT.md already existed WITHOUT the decision-register structure — appended: Current stage, Decisions, Open questions, Change log"*) ok "G init says what it appended" ;; + *) bad "G init says what it appended" "$(grep -m1 PROJECT.md "$WORK/init.out")" ;; esac +for h in "## Current stage" "## Decisions" "## Open questions" "## Change log"; do + grep -q "^$h" "$Q/PROJECT.md" && ok "G $h present" || bad "G $h present"; done +grep -q '^Requirements live in specs/\.$' "$Q/PROJECT.md" && ok "G hand-written lines kept" || bad "G hand-written lines kept" +MXTK_NO_GUIDE=1 HOME="$WORK/home" "$TOOLKIT/bin/init-project.sh" "$Q" 2>&1 | grep -q "Skip: PROJECT.md already exists" \ + && ok "G a second init appends nothing" || bad "G a second init appends nothing" + +echo "" +echo "== $PASS passed, $FAIL failed" +[ "$FAIL" -eq 0 ] From c4ad4d7485e457568bacd61fef4b73662f2b5949 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:42:21 +0000 Subject: [PATCH 03/14] process(entry modes): retire greenfield; two doors (POC or requirements-driven from a conversation) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An idea for a demo is Build type: poc; an idea for a real app is requirements-driven with the conversation as the source. No mode skips design and planning. sync-project.sh maps Entry mode: greenfield to requirements-driven, adopted at the readout's stage via gate-check --adopt (✋ human-pending under auto), with BUILD-LOG rows; unsynced registers get one "run sync" line from gate-check/status/exec and excuse nothing. poc-build.md gains step 0 Inputs; POC-to-real-app stated once (runbook). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8 --- CHANGELOG.md | 1 + CONVERSION-RUNBOOK.md | 3 +- README.md | 2 +- bin/gate-check.sh | 5 +- bin/init-project.sh | 4 +- bin/lib/artifact-check.sh | 1 + bin/lib/artifact-manifest.tsv | 42 ++++++------- bin/lib/intake-template.sh | 8 ++- bin/lib/triage-template.sh | 4 +- bin/status.sh | 2 + bin/sync-project.sh | 35 +++++++++++ docs/pipeline-walks.html | 32 ++-------- project-bin/_position.sh | 9 ++- project-bin/exec.sh | 8 ++- project-bin/progress-report.py | 3 +- skills/agent-roles.md | 2 +- skills/bootstrap-project.md | 6 +- skills/change-intake-detail.md | 2 +- skills/cloud-dev-environment.md | 2 +- skills/conversion-runbook.md | 18 +++--- skills/design-artifacts.md | 2 +- skills/existing-app-change.md | 2 +- skills/interaction-model.md | 2 +- skills/interview-protocol.md | 2 +- skills/iterative-build-loop.md | 2 +- skills/poc-build.md | 5 +- skills/query-the-model.md | 2 +- skills/small-project-tier.md | 2 +- skills/upstream-feedback.md | 2 +- skills/walking-skeleton.md | 4 +- tests/wave2/test-entry-mode-plan-rule.sh | 9 ++- tests/wave2/test-greenfield-retired.sh | 79 ++++++++++++++++++++++++ toolkit-guide.html | 6 +- 33 files changed, 208 insertions(+), 100 deletions(-) create mode 100755 tests/wave2/test-greenfield-retired.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 094d26e5..e92991ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m `docs/RELEASE-PROCESS.md` §8. ## Unreleased +- 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`. 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(entry modes, unattended): **the mode contract, and unattended as the primary case** (stacked on the plan-rule PR): `bin/lib/artifact-manifest.tsv`'s modes column is now the per-mode step list, vocabulary `migration`, `requirements-driven`, `poc`, `existing-app`, `a-la-carte`, `all` (+ `greenfield` until retired), and a row a mode drops reads "not owed (mode …)", never PASS; `Build type: poc` is its own contract, so gate-check reads Stages 0–4, 6, 7 "not owed (mode: Build type: poc)" instead of PENDING (`poc-build.md` updated). Under `Interview mode: auto`, `exec.sh` refuses EVERY MDL write of a migration/requirements-driven project until `gate-check.sh

build-ready` has passed (its PASS now leaves `.mpr-snapshots/.build-ready-pass`) or the register adopts at 5+ / waives Stage 4 — no refuse-once, and a plan on disk alone does not clear it; interactive runs keep refuse-once. `--adopt` at 4+ under auto on those modes also writes an ASSUMED `consentBy: auto-mode` Stage-3/4 row, so `auto_hand_pending()` lists it and Stage 6 FAILs until a person confirms. "Mode changes are decisions" is stated once, in the runbook's Entry Modes (`poc-build.md` points to it). `init-project.sh` and `sync-project.sh` append the missing register sections (Current stage, Decisions, Open questions, Change log) to a PROJECT.md written by hand before init, loudly, from one template (`bin/lib/register-skeleton.sh`; a fresh scaffold is byte-identical to before), and the generated `CLAUDE.local.md` says init runs before any PROJECT.md or model write. `CONVERSION-RUNBOOK.md` gains "Running unattended", the one kick-off brief a project quotes. Fixture `tests/wave2/test-mode-contract.sh` — owner design input + a research comparison of five field builds that followed the process with the one that did not (Nov 2026) - process(exec, entry modes): **the entry mode is a declared fact every tool reads, and a pipeline-mode project no longer builds without a plan by default**: with no `Entry mode:` and no `Adopted at stage:` line (register or intake), `bin/status.sh` (both views, plus a NEXT rule), `bin/gate-check.sh`'s summary and every `bin/exec.sh` run print one banner, and the BUILD-LOG row is tagged `no entry mode declared`; warn-only. In `Entry mode: migration` or `requirements-driven`, the first MDL write with no plan evidence is refused ONCE (nothing locked, snapshotted or written; `verdict=refused`), remedy in one line: run stages 1–4, or `gate-check.sh --adopt 5 --reason ...`. Cleared by outside evidence (guard rule 6): adoption at 5+, a reasoned `Waived stage 4:`, gate-check's readout at Stage 5+, or `architecture/build-plan.md` plus a module brief (root or `apps//`); a re-run after the one refusal goes on, tagged `no plan`. Never refused: `a-la-carte` (new explicit mode: no pipeline, audit or tooling use; gate-check reads its stages WAIVED by mode), `greenfield`, `Build type: poc`, change an existing app, `--patch`. The one entry-mode tokeniser moves to `project-bin/_position.sh` (pure bash, no process starts; installed beside exec.sh, `bin/lib/entry-mode.sh` is now a shim) — identical output on 44 inputs against the old one. Runbook: greenfield's "stages 1–4 collapse to whatever plan the user already has" becomes a design front end (`poc-build.md` steps 1–4, then a short plan with a few lines per module); `design-artifacts.md` Step 2a adopts a supplied prototype by mapping every screen in `design/wireframes/PAGE-MAP.tsv`, and `ui-preflight-pages.md`'s wireframe STOP accepts a mapped prototype. Fixture `tests/wave2/test-entry-mode-plan-rule.sh` (single tree + `apps//`, register and intake captured from `init-project.sh`) — two field runs, Nov 2026, requirements-driven with a frozen spec and clickable prototypes: ~78 pages built with no plan or target - fix(status, agents): **`bin/status.sh` WATCHes an Agent Editor project whose extension module does not travel with the model (#778)**: Studio Pro reads `agenteditor.agent` from `modules/AgentEditor.mxmodule` beside the `.mpr`, and a sync of only `.mpr` + `mprcontents/` left it out of git, so the builder stayed green while every colleague's clone showed `unknown type 'agenteditor.agent'`. Two WATCH items, warn-only (exit code and every verdict unchanged), local files and `git ls-files` only, root and `app/` layouts: a `modules/*.mxmodule` git does not track, and a project using Agent Editor (`AgentEditorCommons` in `analysis/app-facts/inventory.json`, or a `create agent` statement in `mdlsource/`) with no `modules/AgentEditor*.mxmodule`. `skills/mendix-agents.md` (on demand) gains the rule plus the note that the GenAI key, `Encryption.EncryptionKey` and `GenAICommons.StoreTraces` belong in the Default configuration, not a start script. Empty agent references / missing model version (mendixlabs/mxcli#1867) and unset runtime constants are not checked: they need a captured agent document (option 2). Fixture `tests/wave2/test-status-extension-modules.sh` — field report from an Agent Editor project, Nov 2026 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 9da2cf91..4127d823 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/gate-check.sh b/bin/gate-check.sh index 074a1be8..ade30849 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 ;; @@ -4152,6 +4148,7 @@ printf "Summary: %d passed · %d not started · %d waived · %d need attention # Declared position (project-bin/_position.sh; conversion-runbook.md → Entry Modes). The field runs # that built with no plan (2026-11) had neither line, and this summary read like any other. [ -z "$ENTRY_MODE" ] && [ -z "$ADOPTED_AT" ] && printf '⚠ %s\n' "$MXTK_POS_BANNER" +[ "$ENTRY_MODE" = greenfield-retired ] && printf '⚠ %s\n' "${MXTK_POS_RETIRED//$PROJECT_DIR}" # 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 cb552fe4..101223b2 100755 --- a/bin/init-project.sh +++ b/bin/init-project.sh @@ -460,7 +460,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). @@ -490,7 +490,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 3c201e16..4c68f889 100755 --- a/bin/lib/artifact-check.sh +++ b/bin/lib/artifact-check.sh @@ -220,6 +220,7 @@ _art_entry_mode() { local tok; tok="$(entry_mode_token "$raw")" case "$tok" in existing-app-change) echo "existing-app" ;; + 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 1ed206ee..00e5ec19 100644 --- a/bin/lib/artifact-manifest.tsv +++ b/bin/lib/artifact-manifest.tsv @@ -46,7 +46,7 @@ # 6 modes THE MODE CONTRACT (2026-11-17): comma list of the modes that owe it. Vocabulary, # shared with obligations.tsv's mode column: migration, requirements-driven, # poc (`Build type: poc`, whatever the entry mode), existing-app, a-la-carte, -# all — plus greenfield until it is retired. A mode not listed reports +# all (greenfield was 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. # (conversion-runbook.md §"Entry Modes", its table; existing-app runs # P–6 per slice, so it owes every row but coverage-ledger — that mode's ledger @@ -76,9 +76,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-driven,greenfield,existing-app,poc 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-driven,greenfield,existing-app,poc 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-driven,greenfield,existing-app 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-driven,existing-app,poc 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-driven,existing-app,poc 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-driven,existing-app 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 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-driven,existing-app 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-driven,existing-app report @@ -99,26 +99,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-driven,existing-app 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-driven,existing-app 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-driven 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,greenfield,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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-driven,existing-app 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/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 276d79f7..c572d488 100755 --- a/bin/status.sh +++ b/bin/status.sh @@ -76,6 +76,7 @@ ENTRY="$(entry_mode_token "$ENTRY_RAW" 2>/dev/null)" # Entry mode (register or intake) and no adoption line → the one banner, first line of either view. # Field runs (2026-11) built ~78 pages with neither line, and nothing here said so. mxtk_pos_read "$PROJECT_DIR"; POS_BANNER=""; mxtk_pos_undeclared && POS_BANNER="$MXTK_POS_BANNER" +[ "$POS_ENTRY" = greenfield-retired ] && POS_BANNER="${MXTK_POS_RETIRED//$PROJECT_DIR}" 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 //')" UNSYNCED="$(grep -c 'UNSYNCED' "$REG" 2>/dev/null)"; UNSYNCED="${UNSYNCED:-0}" @@ -254,6 +255,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 705a6456..28de5f5e 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 273b45f1..9cd0ae99 100755 --- a/project-bin/_position.sh +++ b/project-bin/_position.sh @@ -21,7 +21,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 @@ -56,7 +57,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" @@ -133,6 +137,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 b1434601..a2c3931b 100755 --- a/project-bin/exec.sh +++ b/project-bin/exec.sh @@ -777,12 +777,16 @@ take_score() { # .plan-rule-refused): a re-run goes on, tagged "no plan" in every BUILD-LOG row; # - 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 + if [ "$POS_ENTRY" = greenfield-retired ]; then + echo "⚠ ${MXTK_POS_RETIRED//$PROJECT_ROOT}" + POS_NOTE="entry mode greenfield retired, not synced" + 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 0f529d8a..ad5f2ccb 100755 --- a/project-bin/progress-report.py +++ b/project-bin/progress-report.py @@ -197,7 +197,7 @@ def load_project(proj): m = re.search(r"Entry mode:\s*\**\s*(\w[\w-]*)", md) em = (m.group(1).lower() if m else "migration") # The mode-contract vocabulary of artifact-manifest.tsv column 6 (Build type: poc is its own contract). - info["entry_mode"] = "requirements-driven" if em.startswith("requirements") else "existing-app" if em.startswith(("existing", "change")) else em + info["entry_mode"] = "requirements-driven" if em.startswith(("requirements", "greenfield")) else "existing-app" if em.startswith(("existing", "change")) else em if re.search(r"(?im)^[\s>*_-]*Build type\s*\**\s*:\s*\**\s*poc\b", md): info["entry_mode"] = "poc" 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)) @@ -1860,7 +1860,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 ace29668..f7d74950 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 — 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 — 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 4b096ed5..b8bfb803 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-entry-mode-plan-rule.sh b/tests/wave2/test-entry-mode-plan-rule.sh index abf05fcf..620a7052 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 @@ -129,12 +130,16 @@ 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 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-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 '^