From cf0d2b25c583edfcfd4caa289e7e3dafb166a37d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:23:11 +0000 Subject: [PATCH 1/3] 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 cb7c0fa1f545bd1449cf0b75b4ae800a53059007 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:55:38 +0000 Subject: [PATCH 2/3] =?UTF-8?q?fix(plan=20rule):=20review=20fixes=20?= =?UTF-8?q?=E2=80=94=20aggregate=20stage-4=20waiver,=20ignore=20the=20stam?= =?UTF-8?q?p=20dir,=20rendered=20rules=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - mxtk_pos_read honours "Waived stages: ..., 4 — reason" as gate-check does (was a false refusal on a project gate-check reads WAIVED at stage 4). - .mpr-snapshots/ is git-ignored before the refuse-once stamp is written, so "once per clone" cannot become once per repository; docs say plainly it is one refusal ever per clone. - skills/generated/rules-page.md re-rendered (bin/mdl-rules.sh --render) after the ui-preflight-pages.md STOP-row edit; CI was DRIFTED. - fixture: the status NEXT case accepts the intake-§1 needs-attention line that outranks the banner rule; aggregate-waiver and .gitignore cases. - _position.sh header: the shared tokeniser plus exec.sh's reader, not the only register reader. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8 --- project-bin/_position.sh | 21 +++++++++++++++------ project-bin/exec.sh | 10 +++++++--- skills/conversion-runbook.md | 2 +- skills/generated/rules-page.md | 4 +++- tests/wave2/test-entry-mode-plan-rule.sh | 15 ++++++++++++++- 5 files changed, 40 insertions(+), 12 deletions(-) diff --git a/project-bin/_position.sh b/project-bin/_position.sh index 2f9e9e39..c1e35ff7 100755 --- a/project-bin/_position.sh +++ b/project-bin/_position.sh @@ -1,9 +1,10 @@ #!/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. +# _position.sh — the ONE shared tokeniser for "Entry mode:" (entry_mode_token), plus exec.sh's +# in-shell reader of the register's position lines (mxtk_pos_read: Entry mode, Adopted at stage, +# Build type, the Stage-4 waivers, the Current-stage readout). gate-check.sh and status.sh keep +# their own register readers and use only the tokeniser and the banner text from here. 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 @@ -74,7 +75,8 @@ _mxtk_emt() { # 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_WAIVED4 1 when a "Waived stage 4:" line carries a reason, or a "Waived stages:" line lists 4 +# before its dash with a reason after it (the two spellings gate-check.sh reads) # 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 @@ -99,6 +101,13 @@ mxtk_pos_read() { 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 + elif [[ "$key" == "waived stages" ]]; then + # The aggregate spelling gate-check.sh also honours ("Waived stages: 1, 2, 3, 4 — reason"): + # 4 must be listed BEFORE the dash, and a reason must follow it (no reason, no waiver). + local _wh="" _wr="" + case "$val" in *—*) _wh="${val%%—*}"; _wr="${val#*—}" ;; *–*) _wh="${val%%–*}"; _wr="${val#*–}" ;; + *" - "*) _wh="${val%% - *}"; _wr="${val#* - }" ;; esac + [[ ",${_wh//[[:blank:]]/}," == *",4,"* && -n "${_wr//[[:blank:]]/}" ]] && POS_WAIVED4=1 fi done < "$reg" fi diff --git a/project-bin/exec.sh b/project-bin/exec.sh index 77b96c2b..6c626021 100755 --- a/project-bin/exec.sh +++ b/project-bin/exec.sh @@ -773,8 +773,9 @@ take_score() { # 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; +# goes through here (guard rule 7), and the refusal is ONCE EVER per clone (.mpr-snapshots/ +# .plan-rule-refused, git-ignored before it is written): every later write goes on, tagged +# "no plan" in its BUILD-LOG row, and no second refusal ever comes on that clone; # - 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="" @@ -794,12 +795,15 @@ if [ -f "$_XD/_position.sh" ]; then POS_NOTE="no plan (Entry mode $POS_ENTRY, before Stage 4)" else [ -d "$PROJECT_ROOT/.mpr-snapshots" ] || mkdir -p "$PROJECT_ROOT/.mpr-snapshots" + # Ignore the folder BEFORE the stamp lands in it: on a fresh repo snapshot-mpr.sh has not run + # yet, and a committed stamp would make "once per clone" once per repository. + mxtk_gitignore_ensure "$PROJECT_ROOT/.gitignore" ".mpr-snapshots" "/.mpr-snapshots/" || true 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\"." + echo " This is the one refusal this clone will ever get: every later write goes on, its BUILD-LOG row tagged \"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 diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index 5d9ed321..e059dcb5 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -75,7 +75,7 @@ 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 ever per clone, every later write goes on tagged "no plan" — run stages 1–4, or `bin/gate-check.sh

--adopt 5 --reason "..."` (a register line). A build plan plus a module brief, `Waived stage 4:` or adoption at 5+ clears it; never refused: `a-la-carte`, `greenfield`, `Build type: poc`, change an existing app, `--patch`. *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/generated/rules-page.md b/skills/generated/rules-page.md index 21401d69..e91217eb 100644 --- a/skills/generated/rules-page.md +++ b/skills/generated/rules-page.md @@ -173,7 +173,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/test-entry-mode-plan-rule.sh b/tests/wave2/test-entry-mode-plan-rule.sh index 62e4594b..1b30abba 100755 --- a/tests/wave2/test-entry-mode-plan-rule.sh +++ b/tests/wave2/test-entry-mode-plan-rule.sh @@ -117,6 +117,16 @@ echo "-- single tree only" 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" +# the aggregate waiver gate-check honours clears it too; one without a reason does not +mkproj single "Entry mode: requirements-driven" +printf 'Waived stages: 1, 2, 3, 4 — analysis and plan were done in the client workshop\n' >> "$P/PROJECT.md" +run; passed && ok "C 'Waived stages: 1, 2, 3, 4 — reason' → no refusal" || bad "C aggregate waiver with a reason" "calls=$CALLS_N" +mkproj single "Entry mode: requirements-driven" +printf 'Waived stages: 1, 2, 3\n' >> "$P/PROJECT.md" +printf 'docs/\n.claude/\n' > "$P/.gitignore" # as a fresh repo has it: .mpr-snapshots/ not yet ignored +run; refused && ok "R 'Waived stages' without 4 or a reason still refuses" || bad "R aggregate waiver without 4" "calls=$CALLS_N" +# the stamp folder is git-ignored before the stamp is written +grep -qx '/.mpr-snapshots/' "$P/.gitignore" && ok "R .mpr-snapshots/ ignored before the stamp" || bad "R .mpr-snapshots/ ignored before the stamp" # 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" @@ -152,7 +162,10 @@ 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 +# On a fresh scaffold gate-check already flags intake §1 "Entry mode", and that needs-attention rule +# outranks the banner rule in status.sh's NEXT order; either line names the entry mode. +case "$ST" in *"NEXT declare the entry mode"*|*"NEXT fix what gate-check flags"*"Entry mode"*) ok "B status NEXT names the entry mode" ;; + *) bad "B status NEXT names the entry 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 From 1d68ffd32099bfea43ee02e8f149b8c4a1d407d8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 05:02:58 +0000 Subject: [PATCH 3/3] fix(gate-check, status): banner is warn-only even without bin/lib; CWD line stays first CI (wave2, run 44013599260): test-bug06-freshness copies gate-check.sh alone into a scratch toolkit, so the shim's banner text was never defined and `set -u` aborted the summary with exit 1 (reproduced: master 0, cb7c0fa 1, this 0). The banner is now an `if` with a defaulted variable. status.sh guards the reader the same way and prints the banner after the CWD line (test-status-session-cwd A: the CWD line must be first). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8 --- bin/gate-check.sh | 7 ++++++- bin/status.sh | 9 ++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/bin/gate-check.sh b/bin/gate-check.sh index 22db54a3..2a185a6e 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -4102,7 +4102,12 @@ printf "Summary: %d passed · %d not started · %d waived · %d need attention "$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" +# Warn-only, and never the script's last status: an `if`, not an `&&` chain, and the text read with +# a default — a scratch copy of this script without bin/lib/ (tests/wave2/test-bug06-freshness.sh) +# has no banner text, and an unbound variable under `set -u` aborted the run with exit 1. +if [ -z "$ENTRY_MODE" ] && [ -z "$ADOPTED_AT" ] && [ -n "${MXTK_POS_BANNER:-}" ]; then + printf '⚠ %s\n' "$MXTK_POS_BANNER" +fi # The stage counts above are about STAGES. They say nothing about the per-module passes and the # per-stage artifacts checked further up, and for a long time nothing down here did either — so diff --git a/bin/status.sh b/bin/status.sh index 276d79f7..34cf1352 100755 --- a/bin/status.sh +++ b/bin/status.sh @@ -75,7 +75,10 @@ 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" +POS_ENTRY=""; POS_BANNER="" +if declare -F mxtk_pos_read >/dev/null; then + mxtk_pos_read "$PROJECT_DIR"; mxtk_pos_undeclared && POS_BANNER="${MXTK_POS_BANNER:-}" +fi ADOPTED="$(grep -m1 -oE '^Adopted at stage: *[0-9P]+' "$REG" | sed 's/^Adopted at stage: *//')" SKELETON="$(grep -m1 -oE '^Skeleton proven [0-9-]+' "$REG" | sed 's/^Skeleton proven //')" UNSYNCED="$(grep -c 'UNSYNCED' "$REG" 2>/dev/null)"; UNSYNCED="${UNSYNCED:-0}" @@ -384,8 +387,8 @@ 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" + [ -n "$POS_BANNER" ] && echo "⚠ $POS_BANNER" echo "WHERE $NAME · $STAGE_LINE${ENTRY:+ · $ENTRY}${ADOPTED:+ · joined at $ADOPTED}" [ -n "$ROUND_LINE" ] && echo "ROUND $ROUND_LINE" echo "STATE scripts $N_SCRIPTS written / $N_PASS gate-pass / $N_DONE done- · modules opened $MOD_OPENED${SKELETON:+ · skeleton $SKELETON} · UNSYNCED $UNSYNCED · open questions $OPEN_Q${MANUAL:+ · $MANUAL}${APPMAP:+ · $APPMAP}" @@ -396,8 +399,8 @@ 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 "$POS_BANNER" ] && printf '⚠ %s\n\n' "$POS_BANNER" [ -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}" printf 'OVERDUE %s · %s · %s · UNSYNCED markers: %s · open questions: %s\n' "$DOCTOR" "$LINT" "${COH:-coherence: cadence script not installed}" "$UNSYNCED" "$OPEN_Q"