diff --git a/CHANGELOG.md b/CHANGELOG.md index e9e148df..5dd02ab8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m `docs/RELEASE-PROCESS.md` §8. ## Unreleased +- new(kickoff): **`bin/kickoff.sh --mode [--build-type full|poc] [--interview steering|assist|auto] [--answers file] [--by who]` writes the kickoff in the parsed form (#821 point 3)**: the `Entry mode:` / `Build type:` / `Interview mode:` register lines, one Stage-P Decisions row each (CONFIRMED only with `--by `, the person who answered; otherwise ASSUMED "no person named", upgraded by a later `--by` run), and one answer marker per intake section — Q1/Q9/Q16 from the flags, `--answers` lines verbatim, poc-build.md's verbatim markers for a POC, the template's stated defaults `Assumed (auto-mode)` (plus an Assumptions line) under auto, and under steering/assist the unasked questions listed, never invented, an unstated build type (Q16) included (a POC's unstated Q9 takes poc-build.md's marker) — then prints `gate-check.sh

P`'s verdict. Idempotent (a second run changes no byte); unknown values exit 2 with the accepted list; a declared mode that differs exits 3 (a mode change is a decision a person records). The kick-off brief (run it after the user answers, with `--by`) and `poc-build.md` name it; it needs the `Entry mode: poc` token (#819 commit) for `--mode poc`. Fixture `tests/wave2/test-kickoff.sh` (real `init-project.sh` scaffold and gate; 31 of 31; master has no kickoff.sh) — two simulated builds, 2026-11-20 (kickoff hand-assembled with Python heredocs in 11-13 turns) +- fix(gate-check, obligations): **a FAIL on a format the toolkit parses prints the whole accepted shape, once per run (#821 point 1)**: new `bin/lib/format-hints.sh` holds one minimal passing example per parsed format — intake answer markers (Stage P), the build plan's numbered rows, Kind cells and three closing rows (Stage 4), the coverage ledger's two tables (Stage 4, incl. the one-element wildcard rule), the LOOK report (`VALID AT`, `PROOF-OF-LOOK`, Stage 5 look and the look/final-look obligations), the prototype LOOK (`PROTOTYPE-SHA`, obligation `prototype-look`) and the improvement-register row report-disposition wants. `gate-check.sh` prints the shapes its FAILs owe after the stage list; obligation FAULTs print theirs after the obligation block. Informational: no verdict or exit code changes. Every example is run through its real parser by the fixture (a hand-drafted coverage example failed SECTION-WIDE and a prototype example failed its own denominator before this). Fixture `tests/wave2/test-fast-lane-format-hints.sh` (real `init-project.sh` scaffold; 13 of 13 on the branch, 7 of 13 on master, whose 6 failures are the missing shapes) — two simulated builds, 2026-11-20 (a prototype LOOK took 5 gate runs; 10 and 19 calls read gate source before the first write) +- fix(gate-check): **build-ready WARNs, not FAILs, on `{{…}}` slots in agent stubs no role was dispatched with (#821 point 2)**: the slot line is now `⚠ agent(s) still have unfilled placeholders: …` and still names every slot (multi-line ones as `{{NAME…}}`); it FAILs again for mdl-agent once mdl-agent's dispatch log exists (`.claude/loop/dispatch//scripts.tsv`, agents/README.md step 8a), the only dispatch record the toolkit keeps. Each stub still refuses to run while a slot is left (its line 11), so a dispatched role cannot run unfilled. Supersedes the 2026-11-13 decision that any unfilled slot FAILs. `bin/status.sh`'s WATCH item is unchanged. Fixture `tests/wave2/test-fast-lane-agent-slots.sh` (stubs from a real `init-project.sh`; 8 of 8 on the branch, 3 of 8 on master) — two simulated builds, 2026-11-20 (0 subagents dispatched; 3 and 6 calls spent filling slots before the first write) +- fix(gate-check, poc): **a POC build owes no build-ready, Stage 5 reads MANUAL, and `Entry mode: poc` is a declared mode (#819 options 1 and 3)**: under `Build type: poc`, `gate-check.sh

build-ready` still prints its checklist but ends `BUILD-READY: N/A (Build type: poc)` with exit 0, no open-questions escalation and no `.build-ready-pass` stamp (exec.sh's plan rule already exempted poc); Stage 5's look check reads MANUAL with the unseen pages still named, as `skills/poc-build.md` promised; the tokeniser (`project-bin/_position.sh`) accepts `poc`, which sets the build type to poc and silences the "No entry mode declared" banner (artifact and obligation rows stay owed exactly as for `Build type: poc`), unless a `Build type:` line names full: then full wins and gate-check and exec.sh print the conflict (under auto exec.sh holds it to the requirements-driven plan rule), and `Build type: poc → full (CR-01)` now reads as full, with the same warning (only the WORD full counts: `poc (fullscreen kiosk)` stays poc, `mxtk_bt_names_full`); `bin/ready.sh` names a POC's unseen pages (it parses the MANUAL line's `look: N of M … never looked at` text); the kick-off brief's line 3 applies build-ready to full builds only. Full builds unchanged. Fixture `tests/wave2/test-fast-lane-poc.sh` (real `init-project.sh` scaffold; 25 of 25 on the branch, 6 of 15 on master before the review cases) — simulated unattended POC build, 2026-11-20 (it fabricated an sme-questions.md to clear build-ready) - new(doctor, bug ledger): **a guard for mxcli's silent MxBuild fallback**: when the project's Mendix version is not in `~/.mxcli/mxbuild/` (and no Studio Pro of that version exists), `mxcli docker build` / `docker check` fall back to the newest cached MxBuild and print its path but no version warning (`run --local` is exact-or-refuse); `bin/doctor.sh` now warns, naming the model version, the cached ones and `./mxcli setup mxbuild -p .mpr` (`mxtk_mxbuild_cache_gap`, warning only, never changes a gate). Ledger entry `BUG-DRAFT-mxbuild-silent-version-fallback`; upstream issue not filed. — a four-app Mendix build (field run), independent review - fix(gate-check): **a fresh clone no longer FAILs Stage 3 as "stale render"**: `blueprint.html` / `process-map.html` freshness used `[ render -ot source ]`, a nanosecond mtime compare, and a checkout stamps files in directory order (`process-map.html` lands before `process-model.json`), so an unedited project read stale on every clone (reproduced: 200-wireframe checkout, 10 of 10 clones). New `bin/lib/render-fresh.sh` keeps `-ot` as the first test (a pass never flips, no git call) and, only where `-ot` would FAIL, asks git once per render (one `log`, one `status`) whether the source was committed after the render's commit; measured 0.19 s for 200 sources all `-ot`-stale on a 300-commit history (a per-source git version cost 12.9 s). Limit: a depth-1 clone cannot see a genuinely stale render. Field run: a four-app Mendix build checked out on a second machine. — a four-app Mendix build (field run), independent review - fix(test-stack-up, e2e-harness-base): **the app port follows the app's configured port, and a multi-app start is no longer pinned to 8080**: with no `APP_PORTS`, `test-stack-up.sh` puts `RUN_LOCAL_APP_PORT`, then `APP_PORT` from the `.docker/.env` beside the `.mpr` (`apps//.docker/.env`; the project-root one as fallback) first, ahead of the old fixed `8080 8081 8084` tail. A fresh `run --local` start for a model under `apps/` with no handshake and no configured port used to fall back to 8080 for every app (`--app-port 8080`); it now exits 4 naming `RUN_LOCAL_APP_PORT`. `e2e-harness-base.md` states that a PAD/Docker runtime listens on 8080 *inside* the container only. Fixtures T28–T32 added. Field run: a four-app Mendix build on 8081–8084 whose fresh start failed with every app pinned to 8080. — a four-app Mendix build (field run), independent review diff --git a/CONVERSION-RUNBOOK.md b/CONVERSION-RUNBOOK.md index 85f5b7f2..25b5b339 100644 --- a/CONVERSION-RUNBOOK.md +++ b/CONVERSION-RUNBOOK.md @@ -34,9 +34,12 @@ 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. +2. Ask the entry mode and build type at kickoff (intake Q16 first, then Q1); after the user answers, + record them with bin/kickoff.sh

--mode --build-type --interview --by ; never + switch them later without a recorded decision (conversion-runbook.md → Entry Modes, "Mode changes + are decisions"). +3. Full build: Stage 5 only after stages 1-4 pass their gates and bin/gate-check.sh

build-ready + passes. Build type: poc: follow skills/poc-build.md instead (no build-ready; Stage 5 is MANUAL). 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. diff --git a/bin/gate-check.sh b/bin/gate-check.sh index a299c58e..de4bbadd 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -688,9 +688,35 @@ 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" . "$(cd "$(dirname "${BASH_SOURCE[0]}")/lib" && pwd)/render-fresh.sh" +# The accepted shape of each parsed format, printed with its FAIL (#821 point 1; bin/lib/format-hints.sh). +. "$(cd "$(dirname "${BASH_SOURCE[0]}")/lib" && pwd)/format-hints.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 +BUILD_TYPE_RAW="$(reg_field "build type" 2>/dev/null || true)" +# poc only when the value starts with the word poc AND never names full: "poc → full (CR-01)" is a +# switch to full, and reading it as poc excused every stage of a build that left POC (review of #828). +# "Names full" is the WORD full (mxtk_bt_names_full, project-bin/_position.sh): "fullscreen" is not. +_bt_l="$(printf '%s' "$BUILD_TYPE_RAW" | tr '[:upper:]' '[:lower:]')" +POC_CONFLICT="" +case "$_bt_l" in + poc|poc[!a-z]*) + if mxtk_bt_names_full "$_bt_l"; then + BUILD_TYPE=full + POC_CONFLICT="Build type: $BUILD_TYPE_RAW starts with poc but names full — read as a FULL build (stages owed); write Build type: poc or Build type: full" + else BUILD_TYPE=poc; fi ;; + *) BUILD_TYPE=full ;; +esac +# `Entry mode: poc` (#819 option 3) is the same contract as `Build type: poc` (project-bin/_position.sh) +# — unless a Build type line says full: then full wins, loudly (POC_CONFLICT, printed in the summary). +# The louder reading: a POC switched to full by editing only its Build type line keeps its gates. +if [ "$ENTRY_MODE" = poc ]; then + case "$BUILD_TYPE:$_bt_l" in + full:*) mxtk_bt_names_full "$_bt_l" || { BUILD_TYPE=poc; _bt_l=poc; } ;; + esac + case "$BUILD_TYPE" in + full) POC_CONFLICT="Entry mode: poc but Build type: $BUILD_TYPE_RAW — read as a FULL build (stages owed); make the two lines agree (a POC: Build type: poc; a full build: the real Entry mode)" ;; + *) BUILD_TYPE=poc ;; + esac +fi # stage_waiver — "|", or nothing. Most specific source of truth first. # @@ -2285,7 +2311,12 @@ EOF local how="$n_seen opened" [ "$n_proof" -gt 0 ] && how="$how, $n_proof by PROOF-OF-LOOK" [ "$n_waived" -gt 0 ] && how="$how, $n_waived waived" - if [ "$n_unseen" -gt 0 ]; then + if [ "$n_unseen" -gt 0 ] && [ "$BUILD_TYPE" = poc ]; then + # Build type: poc (#819): skills/poc-build.md owes its LOOK in steps 7-8 and promises Stage 5 + # MANUAL, not a gate. The count stays in the line, so an unseen page is still visible. + # The "look: N of M ... never looked at ... — screenshot" wording is what bin/ready.sh parses. + echo "MANUAL|look: $n_unseen of $n built page(s)${scope:+ in $scope} never looked at since their last build$src: $unseen — screenshot each and compare it to its wireframe; MANUAL, not FAIL, under Build type: poc (skills/poc-build.md steps 7-8 own the LOOK)" + elif [ "$n_unseen" -gt 0 ]; then echo "FAIL|look: $n_unseen of $n built page(s)${scope:+ in $scope} never looked at since their last build$src: $unseen — screenshot each, open the PNG (a file name containing the page name, or the journey screenshot bin/look-ledger.sh shots lists), compare it to its wireframe (skills/ui-loop.md); or --waive look/ --reason \"...\"" else echo "MANUAL|look: $n of $n built page(s)${scope:+ in $scope} accounted for ($how)$src; the rest of Stage 5 is manual" @@ -2456,6 +2487,10 @@ check_stage_manual() { check_build_ready() { local fails=0 f found echo "Build-ready check for: $PROJECT_DIR" + # Build type: poc (#819 option 1): skills/poc-build.md owes no build-ready, and exec.sh's plan rule + # already exempts it. The list below still prints, informational, so a POC that continues as a + # full build sees what it would owe; the verdict line says N/A and the exit is 0. + [ "$BUILD_TYPE" = poc ] && echo " (Build type: poc — informational only: skills/poc-build.md owes its own steps, not build-ready)" echo "" # 1. Project wired: CLAUDE.local.md with a Wiring block @@ -2504,17 +2539,25 @@ check_build_ready() { # ended up with zero occurrences of "refuse to proceed", because a false # positive made deleting the safety net the cheapest way to get a green gate. # A check that punishes the correct state trains people to break it. - local remaining + # _br_slots — the unfilled slots in those stubs, one space-separated line. # tr joins each file's lines first so a placeholder wrapped over several lines counts (#509); # per file, and the body excludes `{`, so the `'{{'` quoted in prose on line 11 of every stub # cannot run on to a later slot's `}}` (see bin/lib/placeholders.sh). # A slot longer than 80 characters (a wrapped one carries its whole hint text) is printed as - # {{NAME…}} so the failure line stays readable; shorter slots print unchanged. - remaining=$(for _af in "$agents_dir"/*.md; do - [ -f "$_af" ] && sed 's/{{DOUBLE_BRACE}}//g' "$_af" 2>/dev/null | tr '\n' ' '; echo - done | grep -o '{{[^{}]*}}' | sort -u \ - | awk '{ if (length($0) > 80) { n=$0; sub(/^\{\{/, "", n); sub(/[^A-Za-z0-9_].*$/, "", n); print "{{" n "…}}" } else print }' \ - | tr '\n' ' ') + # {{NAME…}} so the line stays readable; shorter slots print unchanged. The perl scan adds the + # one shape the count cannot match, a slot whose own text contains a single `{`. + _br_slots() { + local _af + { for _af in "$@"; do + [ -f "$_af" ] && sed 's/{{DOUBLE_BRACE}}//g' "$_af" 2>/dev/null | tr '\n' ' '; echo + done | grep -o '{{[^{}]*}}' \ + | awk '{ if (length($0) > 80) { n=$0; sub(/^\{\{/, "", n); sub(/[^A-Za-z0-9_].*$/, "", n); print "{{" n "…}}" } else print }' + sed 's/{{DOUBLE_BRACE}}//g' "$@" 2>/dev/null \ + | perl -0777 -ne 'while (/\{\{([A-Z][A-Z0-9_]+)[^}\n]*\n.*?\}\}/sg) { print "{{$1…}}\n" }' 2>/dev/null + } | sort -u | tr '\n' ' ' + } + local remaining + remaining="$(_br_slots "$agents_dir"/*.md)" if [ -n "$missing_agents" ]; then echo " ✗ missing agent(s):$missing_agents — run bin/init-agents.sh" fails=$((fails+1)) @@ -2524,24 +2567,26 @@ check_build_ready() { # bytes into the variable NAME on byte-oriented bash 3.2, and set -u then # aborts the whole run. Only the failure branch ever built that string, so # a pass-path-only test would have shipped it. - echo " ✗ agent(s) still have unfilled placeholders: ${remaining}— complete them (agent-roles.md)" - fails=$((fails+1)) - else - # Decision (maintainer, 2026-11-13, supersedes the #509 warning): an unfilled multi-line - # placeholder FAILs build-ready, like any other unfilled slot. The joined-lines count above - # already catches it; this perl scan is kept only for the one shape that count cannot match, - # a slot whose own text contains a single `{` (the count's body is `[^{}]*`). - local multi="" - multi=$(sed 's/{{DOUBLE_BRACE}}//g' "$agents_dir"/*.md 2>/dev/null \ - | perl -0777 -ne 'while (/\{\{([A-Z][A-Z0-9_]+)[^}\n]*\n.*?\}\}/sg) { print "{{$1…}}\n" }' 2>/dev/null \ - | sort -u | tr '\n' ' ') - if [ -n "$multi" ]; then - echo " ✗ agent(s) still have unfilled multi-line placeholders: ${multi}— complete them (agent-roles.md)" + # + # WARN, not FAIL, unless the role is dispatched (#821 point 2; supersedes the 2026-11-13 + # decision that any unfilled slot FAILs). Two simulated builds (2026-11-20) dispatched 0 + # subagents and still spent 3 and 6 calls filling ~12 slots across six stubs only to clear this + # line, and exec.sh's auto-mode plan rule holds every write until build-ready passes. A stub + # guards itself at dispatch: line 11 of every template says to refuse while a slot remains. + # The one dispatch record the toolkit keeps is mdl-agent's (.claude/loop/dispatch// + # scripts.tsv, agents/README.md step 8a): once it exists, mdl-agent's own slots FAIL again. + local _br_mdl="" + ls "$PROJECT_DIR"/.claude/loop/dispatch/*/scripts.tsv >/dev/null 2>&1 \ + && _br_mdl="$(_br_slots "$agents_dir/mdl-agent.md")" + if [ -n "$_br_mdl" ]; then + echo " ✗ mdl-agent is dispatched (.claude/loop/dispatch/ has its log) and still has unfilled placeholders: ${_br_mdl}— complete them (agent-roles.md)" fails=$((fails+1)) - else - echo " ✓ all 6 agents present, no unfilled placeholders" fi + echo " ⚠ agent(s) still have unfilled placeholders: ${remaining}— not counted while that role is never dispatched (each stub refuses to run with a slot left); fill a role's stub before you dispatch it (agent-roles.md)" + else + echo " ✓ all 6 agents present, no unfilled placeholders" fi + unset -f _br_slots # 3b. Crash net present. Stage 5 writes to a binary .mpr that Studio Pro holds # open; without snapshot/restore a bad exec is recovered from git or not at all. @@ -2619,14 +2664,13 @@ check_build_ready() { # `full` in the copies it printed the ADVISORY 'no architecture/fit-gap.md' line on both and the # fail count stayed 2 (other items); waived it read 'Fit-gap: WAIVED'. Exit 1 each time, from # the other items. The has-a-fit-gap case was fixture-only: no real app had one. - local fg_path fg_w="" bt_raw + local fg_path fg_w="" fg_path="$(resolve_artifact_nonempty "architecture/fit-gap.md")" - bt_raw="$(reg_field "build type" 2>/dev/null || true)" if [ -n "$ADOPTED_AT" ] && [ "$(stage_rank "$ADOPTED_AT")" -gt "$(stage_rank 3)" ]; then echo " ✓ Fit-gap: not owed — project joined the toolkit at stage $ADOPTED_AT" elif fg_w="$(artifact_waived fit-gap)"; then echo " ✓ Fit-gap: WAIVED — $fg_w" - elif [ -z "$fg_path" ] && case "$(printf '%s' "$bt_raw" | tr '[:upper:]' '[:lower:]')" in poc|poc[!a-z]*) true ;; *) false ;; esac; then + elif [ -z "$fg_path" ] && [ "$BUILD_TYPE" = poc ]; then # Before stage_waiver: that now also excuses Stage 3 for poc, in its own words. echo " ✓ Fit-gap: not owed — Build type: poc (skills/poc-build.md) and no fit-gap exists" elif [ -z "$fg_path" ] && fg_w="$(stage_waiver 3)" && [ "${fg_w%%|*}" != "noreason" ]; then @@ -2654,6 +2698,10 @@ check_build_ready() { fi echo "" + if [ "$BUILD_TYPE" = poc ]; then + echo "BUILD-READY: N/A (Build type: poc) — not owed (skills/poc-build.md); $fails item(s) above would block a full build" + return 0 + fi if [ "$fails" -eq 0 ]; then echo "BUILD-READY: PASS — all wiring checks passed" return 0 @@ -4112,6 +4160,7 @@ if ! reg_unavailable; then [ -n "$AUTO_HAND" ] && AUTO_HAND_N=$(printf '%s\n' "$AUTO_HAND" | wc -l | tr -d ' ') fi AUTO_HAND_IDS="$(printf '%s' "$AUTO_HAND" | tr '\n' ',' | sed 's/,/, /g')" +FH_QUEUE="" # format-hint ids owed by this run's FAILs, printed once after the stage list for stage in "${STAGE_NAMES[@]}"; do case "$stage" in 0) result="$(check_stage_0)" ;; @@ -4161,7 +4210,23 @@ for stage in "${STAGE_NAMES[@]}"; do tbl_add NOTES_TBL "$stage" "$note" tbl_get "$stage" "$STAGE_TITLES_TBL" || TBL_VALUE="(untitled stage)" printf "Stage %s (%s): %s%s — %s\n" "$stage" "$TBL_VALUE" "$status" "$(stage_surface_suffix "$stage")" "$note" + # A FAIL on a format this script parses owes the reader its whole accepted shape (#821 point 1). + if [ "$status" = FAIL ]; then + case "$stage:$note" in + 5:*"look: "*) FH_QUEUE="$FH_QUEUE look-report" ;; + esac + case "$stage:$note" in + 4:*"closing rows"*|4:*"depend on rows"*|4:*"no module brief"*) FH_QUEUE="$FH_QUEUE build-plan" ;; + esac + case "$stage:$note" in 4:*"coverage ledger"*) FH_QUEUE="$FH_QUEUE coverage-ledger" ;; esac + fi done +# Stage P is evaluated before the loop (P_STATUS); its FAIL is about the intake markers. +[ "${P_STATUS:-}" = FAIL ] && FH_QUEUE="intake$FH_QUEUE" +if [ -n "$FH_QUEUE" ]; then + echo "Accepted shapes for the FAIL(s) above — a minimal example that passes, so no gate source needs reading:" + for _fh in $FH_QUEUE; do mxtk_format_hint_once "$_fh"; done +fi # Said once, after the list, because it calibrates every line above it. A reader who # does not know that a missing Surface left the exit code alone will read the first one # they see as a failure the gate somehow let through. @@ -4186,6 +4251,7 @@ printf "Summary: %d passed · %d not started · %d waived · %d need attention if [ -z "$ENTRY_MODE" ] && [ -z "$ADOPTED_AT" ] && [ -n "${MXTK_POS_BANNER:-}" ]; then printf '⚠ %s\n' "$MXTK_POS_BANNER" fi +[ -n "$POC_CONFLICT" ] && echo "⚠ $POC_CONFLICT" if [ "$ENTRY_MODE" = greenfield-retired ] && [ -n "${MXTK_POS_RETIRED:-}" ]; then printf '⚠ %s\n' "${MXTK_POS_RETIRED//$PROJECT_DIR}" fi @@ -4645,6 +4711,7 @@ if [ -n "$REQUESTED_STAGE" ]; then echo "Gate BLOCKED by report-disposition-check: $DISP_NOTE" >&2 echo "Route the findings via skills/close-the-loop.md into docs/improvement-register.md" >&2 echo "(skills/finding-disposition.md), then re-run this gate." >&2 + mxtk_format_hint_once report-disposition >&2 exit 1 fi # No gate passes while questions this stage owns were never put to the user. @@ -4711,6 +4778,10 @@ if [ -n "$REQUESTED_STAGE" ]; then if [ "$REQUESTED_STAGE" = "build-ready" ]; then echo "" if check_build_ready; then + # POC: N/A, exit 0, no open-questions escalation (a POC has no BRDs to collect them from; a + # field run fabricated an sme-questions.md to clear it) and no stamp (it would clear the + # auto-mode plan rule if the build type later became full). + [ "$BUILD_TYPE" = poc ] && exit 0 enforce_open_questions build-ready # The record exec.sh's plan rule reads under Interview mode: auto (project-bin/exec.sh, # "Declared position + plan rule"): exec cannot afford a gate-check per write. Sticky on diff --git a/bin/kickoff.sh b/bin/kickoff.sh new file mode 100755 index 00000000..0beb3066 --- /dev/null +++ b/bin/kickoff.sh @@ -0,0 +1,321 @@ +#!/usr/bin/env bash +# kickoff.sh — write a project's kickoff declarations in the exact form the gates parse. +# +# usage: bin/kickoff.sh --mode +# [--build-type ] [--interview ] +# [--answers ] [--by ] [--dry-run] +# +# WHY (#821 point 3; two simulated builds, 2026-11-20). Kickoff was hand-assembled from prose: both +# agents wrote the 16 intake answer markers and the register lines with ad-hoc Python heredocs, and +# the POC agent read three scripts to find an `Entry mode:` value it could legally write (there was +# none). That was 13-15 calls before any project content. This writes, in one call: +# - PROJECT.md: `Entry mode:`, `Build type:` and `Interview mode:` lines and one Stage-P Decisions +# row each — CONFIRMED (consentBy · consentAt ) ONLY with --by , the person +# who gave the answers; without --by the row is ASSUMED, "no person named", because nobody's +# consent can be inferred from a command line (review of #828) — and under `Interview mode: auto` +# one Assumptions line per intake default it assumed. Re-running with --by upgrades kickoff's +# own rows and markers; +# - intake.md: one answer marker per '## N.' section, in a form check_stage_P accepts — +# Q1 (mode), Q9 (interview) and Q16 (build type) from the flags; any question in --answers as +# answers; an unstated --build-type / --interview is left UNANSWERED under steering/assist (Q16 is +# the question asked first; it is listed, never assumed) and assumed (full / steering) under auto +# only; under a POC build the rest get poc-build.md's verbatim +# `Unverified — how to verify: not asked, POC build ...`; under auto the rest get +# `Assumed (auto-mode): ` where the template states one, else +# `Unverified — how to verify: not asked at kickoff (Interview mode: auto) ...`; under +# steering/assist the rest stay unanswered and are listed (they must be asked in chat); +# then runs `gate-check.sh P` and prints its verdict. +# +# IDEMPOTENT: the same call twice changes nothing the second time. It never overwrites a real +# answer with a default, and it REFUSES (exit 3) to change an Entry mode, Build type or Interview +# mode the register already declares differently: a mode change is a decision (conversion- +# runbook.md → Entry Modes, "Mode changes are decisions"), recorded by a person, not a re-run. +# (init-project.sh's `Build type: full` default line is not a declaration: it is replaced.) +# +# --answers : one answer per line, `Q: ` or `: ` (N = 2-8, 10-15; Q1, Q9 and +# Q16 come from the flags); blank lines and #-comments ignored. +# +# Exit: 0 written (or nothing to change) · 2 usage: an unknown flag or value, with the accepted list, +# or no init-project.sh scaffold · 3 refused: it would change a declared mode. +# Producer of what it reads: PROJECT.md and intake.md come from bin/init-project.sh (mandatory first +# step of the kick-off brief, CONVERSION-RUNBOOK.md). Bash 3.2 safe; awk only, no GNU-only flags. +set -uo pipefail + +TOOLKIT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +MODES="poc requirements-driven migration change" +BUILDS="full poc" +INTERVIEWS="steering assist auto (aliases: attended = steering, unattended = auto)" + +usage() { sed -n '3,6p' "$0" | sed 's/^# \{0,1\}//' >&2; exit 2; } +die2() { echo "kickoff: $1" >&2; exit 2; } + +PROJECT=""; MODE=""; BUILD=""; IVIEW=""; ANSWERS=""; BY=""; DRY=0 +BUILD_SET=0; IVIEW_SET=0 # given on the command line (CONFIRMED) or defaulted (ASSUMED) +while [ $# -gt 0 ]; do + case "$1" in + --mode) [ $# -ge 2 ] || die2 "--mode needs a value: $MODES"; MODE="$2"; shift 2 ;; + --build-type) [ $# -ge 2 ] || die2 "--build-type needs a value: $BUILDS"; BUILD="$2"; BUILD_SET=1; shift 2 ;; + --interview) [ $# -ge 2 ] || die2 "--interview needs a value: $INTERVIEWS"; IVIEW="$2"; IVIEW_SET=1; shift 2 ;; + --answers) [ $# -ge 2 ] || die2 "--answers needs a file"; ANSWERS="$2"; shift 2 ;; + --by) [ $# -ge 2 ] || die2 "--by needs a name"; BY="$2"; shift 2 ;; + --dry-run) DRY=1; shift ;; + -h|--help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -*) die2 "unknown option '$1' — accepted: --mode --build-type --interview --answers --by --dry-run --help" ;; + *) [ -z "$PROJECT" ] || die2 "one project root only (got '$PROJECT' and '$1')"; PROJECT="$1"; shift ;; + esac +done +[ -n "$PROJECT" ] || usage +[ -n "$MODE" ] || die2 "--mode is required — accepted: $MODES" +case "$MODE" in poc|requirements-driven|migration|change) ;; *) die2 "unknown --mode '$MODE' — accepted: $MODES" ;; esac +case "$BUILD" in "") if [ "$MODE" = poc ]; then BUILD=poc; BUILD_SET=1; fi ;; full|poc) ;; *) die2 "unknown --build-type '$BUILD' — accepted: $BUILDS" ;; esac +[ "$MODE" = poc ] && [ "$BUILD" = full ] && die2 "--mode poc is a POC build; --build-type full contradicts it (a full build declares requirements-driven, migration or change)" +case "$IVIEW" in + "") ;; steering|attended) IVIEW=steering ;; assist) ;; auto|unattended) IVIEW=auto ;; + *) die2 "unknown --interview '$IVIEW' — accepted: $INTERVIEWS" ;; +esac +[ -d "$PROJECT" ] || die2 "not a directory: $PROJECT" +PROJECT="$(cd "$PROJECT" && pwd)" +REG="$PROJECT/PROJECT.md"; INTAKE="$PROJECT/intake.md" +[ -f "$REG" ] && [ -f "$INTAKE" ] || die2 "no PROJECT.md / intake.md in $PROJECT — run bin/init-project.sh $PROJECT first" +case "$BY" in *"|"*|*"("*|*")"*) die2 "--by must not contain '|', '(' or ')' (it lands in a table cell and an intake marker)" ;; esac +# Under auto an unstated build type is the toolkit default, full (auto never picks poc, poc-build.md). +[ -z "$BUILD" ] && [ "$IVIEW" = auto ] && BUILD=full + +case "$MODE" in + poc) ENTRY="poc" ;; requirements-driven) ENTRY="requirements-driven" ;; migration) ENTRY="migration" ;; + change) ENTRY="Change an existing app" ;; # verbatim, as intake Q1 asks it to be recorded +esac +TODAY="$(date -u +%Y-%m-%d)" + +# ── answers file → ANS_ ───────────────────────────────────────────────────────────────── +if [ -n "$ANSWERS" ]; then + [ -f "$ANSWERS" ] || die2 "--answers file not found: $ANSWERS" + while IFS= read -r line || [ -n "$line" ]; do + line="${line%$'\r'}" + case "$line" in ''|'#'*) continue ;; esac + if [[ "$line" =~ ^[[:blank:]]*[Qq]?([0-9]+)[[:blank:]]*[:.][[:blank:]]*(.+)$ ]]; then + n="${BASH_REMATCH[1]}"; v="${BASH_REMATCH[2]}"; n=$((10#$n)) + case "$n" in + 1|9|16) die2 "--answers line '$line': Q$n is set by $( [ "$n" = 1 ] && echo --mode || { [ "$n" = 9 ] && echo --interview || echo --build-type; } )" ;; + 2|3|4|5|6|7|8|10|11|12|13|14|15) eval "ANS_$n=\$v" ;; + *) die2 "--answers line '$line': no intake question $n (questions 2-8 and 10-15)" ;; + esac + else + die2 "--answers line not understood: '$line' — write 'Q: '" + fi + done < "$ANSWERS" +fi + +# ── the register: read what is declared ─────────────────────────────────────────────────── +# reg_get → the first uncommented ": value" line's value (emphasis stripped), or empty. +reg_get() { + awk -v k="$1" ' + //) inc = 1; next } + inc { if ($0 ~ /-->/) inc = 0; next } + { l = $0; gsub(/\r/, "", l); sub(/^[ \t>*_-]+/, "", l); gsub(/\*/, "", l) + i = index(l, ":"); if (i == 0) next + key = tolower(substr(l, 1, i - 1)); gsub(/^[ \t]+|[ \t]+$/, "", key) + if (key != tolower(k)) next + v = substr(l, i + 1); gsub(/^[ \t]+|[ \t]+$/, "", v); if (v == "") next + print v; exit }' "$REG" +} +has_kick_row() { grep -qE "^\\|[[:blank:]]*P[[:blank:]]*\\|[[:blank:]]*$1:" "$REG"; } + +. "$TOOLKIT_DIR/bin/lib/entry-mode.sh" +cur_entry="$(reg_get "entry mode")"; cur_build="$(reg_get "build type")"; cur_iv="$(reg_get "interview mode")" +refuse="" +if [ -n "$cur_entry" ] && [ "$(entry_mode_token "$cur_entry" 2>/dev/null)" != "$(entry_mode_token "$ENTRY" 2>/dev/null)" ]; then + refuse="${refuse} Entry mode: the register says '$cur_entry', this call says '$ENTRY'"$'\n' +fi +cb="$(printf '%s' "$cur_build" | tr '[:upper:]' '[:lower:]')"; cb="${cb%%[!a-z]*}" +if [ -n "$BUILD" ] && [ -n "$cb" ] && [ "$cb" != "$BUILD" ] && has_kick_row "Build type"; then + refuse="${refuse} Build type: the register says '$cur_build' (a Decisions row records it), this call says '$BUILD'"$'\n' +fi +civ="$(printf '%s' "$cur_iv" | tr '[:upper:]' '[:lower:]')"; civ="${civ%%[!a-z]*}" +case "$civ" in attended) civ=steering ;; unattended) civ=auto ;; esac +if [ -n "$IVIEW" ] && [ -n "$civ" ] && [ "$civ" != "$IVIEW" ]; then + refuse="${refuse} Interview mode: the register says '$cur_iv', this call says '$IVIEW'"$'\n' +fi +if [ -n "$refuse" ]; then + echo "kickoff: REFUSED — $REG already declares something else; nothing was written:" >&2 + printf '%s' "$refuse" >&2 + echo " A mode change is a decision (conversion-runbook.md → Entry Modes, \"Mode changes are decisions\"): a person" >&2 + echo " records it in PROJECT.md (the line and a Decisions row with the reason); kickoff.sh only writes a first declaration." >&2 + exit 3 +fi + +# ── edits, applied to temp copies, then moved in one go ─────────────────────────────────── +TMP="$(mktemp -d "${TMPDIR:-/tmp}/kickoff.XXXXXX")" || exit 2 +trap 'rm -rf "$TMP"' EXIT +cp "$REG" "$TMP/reg"; cp "$INTAKE" "$TMP/intake" +CHANGES="" + +# set_line — replace the first uncommented ":" line, else insert after the +# "Build type:" line (init writes it), else after "Toolkit commit:", else before "## Decisions". +set_line() { + local k="$1" v="$2" + [ "$(reg_get_tmp "$k")" = "$v" ] && return 0 + KO_K="$k" KO_V="$v" awk ' + BEGIN { k = ENVIRON["KO_K"]; v = ENVIRON["KO_V"]; lk = tolower(k) } + //) inc = 1; print; next } + inc { if ($0 ~ /-->/) inc = 0; print; next } + { l = tolower($0); sub(/^[ \t>*_-]+/, "", l); gsub(/\*/, "", l) } + !done && index(l, lk ":") == 1 { print k ": " v; done = 1; next } + { print } + ' "$TMP/reg" > "$TMP/reg.1" + if [ "$(REG="$TMP/reg.1" reg_get "$k")" != "$v" ]; then + # Not there yet: after "Build type:" (init writes it), else "Toolkit commit:", else before "## Decisions". + KO_K="$k" KO_V="$v" awk ' + BEGIN { k = ENVIRON["KO_K"]; v = ENVIRON["KO_V"] + while ((getline l < ARGV[1]) > 0) { if (l ~ /^Build type:/) a = "b"; else if (!a && l ~ /^Toolkit commit:/) t = 1 } + close(ARGV[1]); if (!a) a = (t ? "t" : "d") } + !done && a == "b" && /^Build type:/ { print; print k ": " v; done = 1; next } + !done && a == "t" && /^Toolkit commit:/ { print; print k ": " v; done = 1; next } + !done && a == "d" && /^## Decisions/ { print k ": " v; print ""; done = 1 } + { print }' "$TMP/reg.1" > "$TMP/reg.2" + mv "$TMP/reg.2" "$TMP/reg.1" + fi + mv "$TMP/reg.1" "$TMP/reg" + CHANGES="${CHANGES} PROJECT.md: $k: $v"$'\n' +} +reg_get_tmp() { REG="$TMP/reg" reg_get "$1"; } + +# add_row — a Stage-P row in the Decisions table. A row with the +# same decision and status is left alone (idempotent, whatever its date); a different row that +# kickoff.sh wrote for the same key is replaced (an ASSUMED row upgraded by --by); a row a person +# wrote for that key is never touched. +add_row() { + local d="$1" st="$2" notes="$3" key="${1%%:*}" old + grep -qF "| P | $d | $st |" "$TMP/reg" && return 0 + old="$(grep -E "^\\|[[:blank:]]*P[[:blank:]]*\\|[[:blank:]]*$key:" "$TMP/reg" | head -1)" + if [ -n "$old" ]; then + case "$old" in *"(bin/kickoff.sh)"*) ;; *) return 0 ;; esac + KO_OLD="$old" awk 'BEGIN { o = ENVIRON["KO_OLD"] } $0 == o && !d { d = 1; next } { print }' "$TMP/reg" > "$TMP/reg.0" && mv "$TMP/reg.0" "$TMP/reg" + fi + KO_ROW="| P | $d | $st | $notes |" awk ' + BEGIN { row = ENVIRON["KO_ROW"] } + /^\| *Stage *\| *Decision/ { intab = 1; print; next } + intab && /^\|/ { print; next } + intab { print row; intab = 0; added = 1 } + { print } + END { if (intab && !added) print row }' "$TMP/reg" > "$TMP/reg.1" + grep -qF "| P | $d |" "$TMP/reg.1" || { echo "kickoff: no '| Stage | Decision | Status | Notes |' table in PROJECT.md — run bin/sync-project.sh $PROJECT (it appends the register sections)" >&2; exit 2; } + mv "$TMP/reg.1" "$TMP/reg" + CHANGES="${CHANGES} PROJECT.md: Decisions row P — $d ($st)"$'\n' +} + +# add_assumption — one line under "## Assumptions (ASSUMED, unresolved)", by id. +add_assumption() { + grep -qF -- "- $1:" "$TMP/reg" && return 0 + KO_LINE="- $1: $2" awk ' + BEGIN { line = ENVIRON["KO_LINE"] } + /^## Assumptions/ { print; ina = 1; next } + ina && /^None yet\.?[ \t]*$/ { next } + ina && /^## / { print line; print ""; ina = 0; done = 1 } + { print } + END { if (ina && !done) print line }' "$TMP/reg" > "$TMP/reg.1" + if grep -qF -- "- $1:" "$TMP/reg.1"; then mv "$TMP/reg.1" "$TMP/reg" + else { cat "$TMP/reg"; printf '\n## Assumptions (ASSUMED, unresolved)\n\n- %s: %s\n' "$1" "$2"; } > "$TMP/reg.1"; mv "$TMP/reg.1" "$TMP/reg"; fi + CHANGES="${CHANGES} PROJECT.md: assumption $1"$'\n' +} + +# mark — the answer marker of intake section N. A section that +# already carries a marker keeps it unless force=1 (an explicit flag or --answers line) and it +# differs; "_Not yet asked._ " is dropped from the section once it has an answer. +# marker_of → section N's first marker line (lower-cased), by check_stage_P's own test. +marker_of() { + awk -v n="$1" ' + $0 ~ "^## " n "\\." { ins = 1; next } ins && /^## / { exit } + ins { l = $0; gsub(/^[ \t>*_-]+/, "", l); gsub(/\*/, "", l); l = tolower(l) + if (l ~ /^(answered|answer|a|decision|assumed)[ \t]*(\([^)]*\))?[ \t]*:/ || (l ~ /^unverified/ && l ~ /how to verify/)) { print l; exit } }' "$TMP/intake" +} +mark() { + local n="$1" m="$2" force="$3" have + have="$(marker_of "$n")" + if [ -n "$have" ]; then + [ "$force" = 1 ] || return 0 + [ "$have" = "$(printf '%s' "$m" | tr '[:upper:]' '[:lower:]')" ] && return 0 + fi + KO_M="$m" awk -v n="$n" ' + BEGIN { m = ENVIRON["KO_M"] } + $0 ~ "^## " n "\\." { print; print ""; print m; ins = 1; next } + ins && /^## / { ins = 0 } + ins { l = $0; gsub(/^[ \t>*_-]+/, "", l); gsub(/\*/, "", l); l = tolower(l) + if (l ~ /^(answered|answer|a|decision|assumed)[ \t]*(\([^)]*\))?[ \t]*:/ || (l ~ /^unverified/ && l ~ /how to verify/)) next + sub(/^_Not yet asked\._ ?/, "") } + { print }' "$TMP/intake" > "$TMP/intake.1" + # The blank line the insert adds is not doubled on a re-run: squeeze runs of blank lines. + awk 'NF == 0 { if (blank) next; blank = 1; print; next } { blank = 0; print }' "$TMP/intake.1" > "$TMP/intake" + CHANGES="${CHANGES} intake.md Q$n: $m"$'\n' +} + +# CONFIRMED needs a person: --by names who gave these answers. Without it a stated value is still +# recorded, ASSUMED, "no person named" — never consent nobody gave (review of #828). +if [ -n "$BY" ]; then + ST=CONFIRMED; NOTE="kickoff (bin/kickoff.sh) — consentBy: $BY · consentAt: $TODAY"; ANS="Answered (CONFIRMED by $BY)" +else + ST=ASSUMED; NOTE="kickoff (bin/kickoff.sh), stated in the kickoff call, no person named — consentBy: none yet · consentAt: $TODAY; re-run with --by once a person has answered" + ANS="Answered (kickoff call, no person named)" +fi +# Under auto only: a build type the call did not state is the default, full, ASSUMED by auto-mode. +DEF="kickoff (bin/kickoff.sh), the default because the call did not state it — consentBy: auto-mode · consentAt: $TODAY; a person confirms or overturns it" +set_line "Entry mode" "$ENTRY" +[ -n "$BUILD" ] && set_line "Build type" "$BUILD" +[ -n "$IVIEW" ] && set_line "Interview mode" "$IVIEW" +add_row "Entry mode: $ENTRY" "$ST" "$NOTE" +if [ "$BUILD_SET" = 1 ]; then add_row "Build type: $BUILD" "$ST" "$NOTE" +elif [ -n "$BUILD" ]; then add_row "Build type: $BUILD" ASSUMED "$DEF"; fi +[ -n "$IVIEW" ] && add_row "Interview mode: $IVIEW" "$ST" "$NOTE" + +case "$MODE" in poc) Q1="poc — a demo (Build type: poc, skills/poc-build.md)" ;; *) Q1="$ENTRY" ;; esac +mark 1 "$ANS: $Q1" 1 +POC_MARK="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" +# A POC asks no question but Q16 (poc-build.md "Who asks"): an unstated Q9 takes the POC marker. +if [ -n "$IVIEW" ]; then mark 9 "$ANS: $IVIEW" 1 +elif [ "$BUILD" = poc ]; then mark 9 "$POC_MARK" 0; fi +if [ "$BUILD" = poc ]; then mark 16 "$ANS: POC build" 1 +elif [ "$BUILD_SET" = 1 ]; then mark 16 "$ANS: Full build" 1 +elif [ -n "$BUILD" ]; then mark 16 "Assumed (auto-mode): Full build (the default; not stated at kickoff)" 0; fi + +# Defaults the intake template states (bin/lib/intake-template.sh): assumed under auto only. +default_for() { + case "$1" in + 10) echo "starting from scratch here — nothing done outside the toolkit" ;; + 11) echo "auto" ;; 12) echo "project" ;; 13) echo "no" ;; 15) echo "balanced" ;; + *) echo "" ;; + esac +} +UNASKED="" +for n in 2 3 4 5 6 7 8 10 11 12 13 14 15; do + eval "a=\${ANS_$n:-}" + if [ -n "$a" ]; then mark "$n" "$ANS: $a" 1; continue; fi + if [ "$BUILD" = poc ]; then mark "$n" "$POC_MARK" 0; continue; fi + if [ "$IVIEW" = auto ]; then + d="$(default_for "$n")" + if [ -n "$d" ]; then + mark "$n" "Assumed (auto-mode): $d (the intake template's default)" 0 + add_assumption "Intake Q$n" "$d — ASSUMED at kickoff under Interview mode: auto (the template's default); consentBy: auto-mode · consentAt: $TODAY; a person confirms or overturns it" + else + mark "$n" "Unverified — how to verify: not asked at kickoff (Interview mode: auto); a person answers it before Stage 6" 0 + fi + continue + fi + [ -n "$(marker_of "$n")" ] || UNASKED="$UNASKED Q$n" +done + +# Q9 / Q16 not stated (steering/assist only): asked first, listed first, never assumed. +[ -n "$BUILD" ] || [ -n "$(marker_of 16)" ] || UNASKED=" Q16$UNASKED" +[ -n "$IVIEW" ] || [ -n "$(marker_of 9)" ] || UNASKED=" Q9$UNASKED" +if [ -z "$CHANGES" ]; then + echo "kickoff: nothing to change — $PROJECT already declares Entry mode: $ENTRY, Build type: ${BUILD:-(not stated)}, Interview mode: ${IVIEW:-(not stated)}" +else + if [ "$DRY" = 1 ]; then echo "kickoff: DRY RUN — would write:"; printf '%s' "$CHANGES"; exit 0; fi + cp "$TMP/reg" "$REG"; cp "$TMP/intake" "$INTAKE" + echo "kickoff: wrote"; printf '%s' "$CHANGES" +fi +if [ -n "$UNASKED" ]; then + echo "Still to ask in chat (Interview mode: ${IVIEW:-not stated, so steering}):$UNASKED — record each answer in intake.md, or put them in a file and re-run with --answers ." +fi +GC_OUT="$(bash "$TOOLKIT_DIR/bin/gate-check.sh" --no-html "$PROJECT" P 2>&1)"; GC_RC=$? +echo "Stage P: $(printf '%s\n' "$GC_OUT" | grep -m1 '^Stage P ' | sed 's/^Stage P ([^)]*): //' | cut -c1-200) (bin/gate-check.sh $PROJECT P exit $GC_RC)" +exit 0 diff --git a/bin/lib/artifact-check.sh b/bin/lib/artifact-check.sh index 7adf7b8c..dfef745f 100755 --- a/bin/lib/artifact-check.sh +++ b/bin/lib/artifact-check.sh @@ -218,6 +218,7 @@ _art_entry_mode() { case "$tok" in requirements-driven) echo "requirements" ;; greenfield-retired) echo "" ;; # retired, not yet synced: every row owed — louder, never quieter + poc) echo "" ;; # Entry mode: poc = Build type: poc, whose rows are owed as before (#819) *) echo "$tok" ;; esac } diff --git a/bin/lib/format-hints.sh b/bin/lib/format-hints.sh new file mode 100644 index 00000000..f973567c --- /dev/null +++ b/bin/lib/format-hints.sh @@ -0,0 +1,113 @@ +#!/usr/bin/env bash +# format-hints.sh — the full accepted shape of every format a gate PARSES, printed with the FAIL. +# +# WHY (#821 point 1, two simulated builds 2026-11-20). Each gate FAIL named what was missing but +# not the line it would accept, so the next run revealed the next requirement: a prototype LOOK +# took five gate runs (no PROTOTYPE-SHA → no PROOF-OF-LOOK → shots not on disk → no register row), +# the build-plan row ids were rewritten by sed after a FAIL, and the agents read gate source 10 +# and 19 times before their first model write. A FAIL now prints, once per run and per format, a +# minimal example that passes — every line the parser wants, at once. +# +# THE RULE FOR THIS FILE: an example here must pass the parser it describes. Each one is checked +# against the real parser by tests/wave2/test-fast-lane-format-hints.sh, which writes the example +# into a project scaffolded by bin/init-project.sh and runs the gate on it; change a parser, change +# its example, and that fixture says which. +# +# Sourced by bin/gate-check.sh (and the obligation check it sources). Bash 3.2 safe. +# +# mxtk_format_hint print the shape (ids: intake, build-plan, coverage-ledger, +# look-report, prototype-look, report-disposition) +# mxtk_format_hint_once the same, at most once per process (MXTK_FH_SHOWN) + +MXTK_FH_SHOWN="${MXTK_FH_SHOWN:-}" + +mxtk_format_hint_once() { + case " $MXTK_FH_SHOWN " in *" $1 "*) return 0 ;; esac + MXTK_FH_SHOWN="$MXTK_FH_SHOWN $1" + mxtk_format_hint "$1" +} + +mxtk_format_hint() { + case "$1" in + intake) cat <<'EOF' + Accepted shape — intake.md (Stage P): every '## N.' section carries ONE marker line, at the start of a line: + ## 1. Entry mode: migration, requirements-driven, or change an existing app? + Answered (CONFIRMED): requirements-driven + ## 7. Is an SME available — who, and at what cadence? + Unverified — how to verify: ask the sponsor at the Stage 0 checkpoint + ## 15. Pipeline mode: `high-speed`, `balanced` (default) or `high-quality`? + Assumed (auto-mode): balanced + Also accepted: Answer: / A: / Decision: (a qualifier in parentheses is fine). Not accepted: "_Not yet + asked._", "Status: Not Answered", a bare "Unverified". +EOF + ;; + build-plan) cat <<'EOF' + Accepted shape — architecture/build-plan.md (Stage 4), a minimal plan for one module that passes: + | # | Kind | Step | Depends on | + |---|---|---|---| + | 1 | BRIEF | Module brief — Rooms (architecture/modules/Rooms/module-brief.md) | — | + | 2 | BUILD | Rooms domain model and access rules | 1 | + | 3 | BUILD | Rooms pages | 2 | + | 4 | HARNESS | bin/verify-module.sh Rooms, then LOOK + CONFIRM (module-review.md) | 3 | + | 5 | RUN | bin/gate-check.sh 5 | 4 | + Row ids are numbers (1, 01, 3a, 1.1), never R03. Kind is BRIEF, BUILD, PROVE, RUN or HARNESS. Owed: one + `verify-module.sh ` row per module; one HARNESS/RUN row naming process-coherence-pass per 3 modules + once there are 2 or more (2-4 modules: 1, 5-7: 2, ...); the LAST numbered row is `gate-check.sh 5`; + every Depends-on number is a row of the plan. The first BRIEF row's module needs its brief: + architecture/modules//module-brief.md, architecture/modules/-brief.md, or '## Module brief — ' in the plan. + Then a Decisions row in PROJECT.md: | 4 | Build plan approved | CONFIRMED | ... | +EOF + ;; + coverage-ledger) cat <<'EOF' + Accepted shape — a coverage ledger (architecture/coverage-ledger.md, or architecture/modules//coverage-ledger.md): + | pointer | type | title | slice | writeMode | acceptance | status | + |---|---|---|---|---|---|---| + | /domainEntities/0/name | entity | Room | 1 | create | Room exists | claimed by row 2 | + | /useCases/0/* (3) | useCase | Book a room | 1 | create | journey passes | claimed by row 3 | + + | pointer | category | reason | + |---|---|---| + | /id | provenance | the BRD's own id, not a requirement | + One row per BRD leaf pointer (never one per model element). A wildcard or a comma list carries the count of + leaves it covers in "(N)", and claims ONE element (/useCases/0/*), never a whole section (/useCases/*). Every + leaf is claimed exactly once (7-column table) or ledgered with a category and a reason (3-column table). + The BRDs it is measured against: analysis//knowledge-base/brd/*.brd.json. List every leaf: + project-bin/coverage-preflight.sh --summary (run from the project root) +EOF + ;; + look-report) cat <<'EOF' + Accepted shape — a LOOK report, design/ui-reviews/ui-review--.html (module-review.md stage 5): + Rooms · 2 of 2 pages reviewed + VALID AT: 1a2b3c4 + PROOF-OF-LOOK: Rooms.Room_Overview = shots/2026-11-20/Rooms.Room_Overview.png + PROOF-OF-LOOK: Rooms.Booking_New = shots/2026-11-20/Rooms.Booking_New.png + The first line counts "N of M". VALID AT is the model commit the shots were taken on. One PROOF-OF-LOOK per + reviewed page (at least N), the path relative to the report; each file on disk, at least 10 KB, newer than the + VALID AT commit, committed with the report. The report names the module. A page with no review needs + --waive look/ --reason "...". +EOF + ;; + prototype-look) cat <<'EOF' + Accepted shape — design/ui-reviews/prototype-look-.html (design-artifacts.md Step 3d): + 4 of 4 screen-widths captured + PROTOTYPE-SHA: + PROOF-OF-LOOK: rooms@390 = shots/2026-11-20/rooms-390.png + PROOF-OF-LOOK: rooms@360 = shots/2026-11-20/rooms-360.png + PROOF-OF-LOOK: rooms@320 = shots/2026-11-20/rooms-320.png + PROOF-OF-LOOK: rooms@1280 = shots/2026-11-20/rooms-1280.png + That is one screen. M = screens x 4 widths (390, 360, 320, 1280); one PROOF-OF-LOOK per screen-width (at least + N), the path relative to the report, each file on disk and at least 10 KB. Re-assembling the prototype changes + its sha and makes the report STALE. +EOF + ;; + report-disposition) cat <<'EOF' + Accepted shape — docs/improvement-register.md, one row per finding of the newest report, dated that report's day: + | Date | Module/Cluster | Source pass | Defect class | Severity | Finding | Disposition | + |---|---|---|---|---|---|---| + | 2026-11-20 | Rooms | module-review stage 4 | layout | P2 | Booking list overflows at 390 | fixed same session | + (skills/finding-disposition.md; project-bin/report-disposition-check.sh says which report and date.) +EOF + ;; + *) return 1 ;; + esac +} diff --git a/bin/lib/obligation-check.sh b/bin/lib/obligation-check.sh index 5df9a9ae..3ee554a4 100755 --- a/bin/lib/obligation-check.sh +++ b/bin/lib/obligation-check.sh @@ -693,6 +693,7 @@ mxtk_obligations_report() { fi fi local ob performer scope match artifact denom degradable from_stage skill + local _ob_fh="" # format-hint ids owed by a FAULT (#821 point 1, bin/lib/format-hints.sh) # Stage limit (#583): rows owed from a stage AFTER the one asked about are not evaluated — # they cannot change the requested stage's verdict, and each one walks every module's @@ -861,6 +862,13 @@ mxtk_obligations_report() { printf 'Obligation %-10s FAULT — %d of %d discharged%s; %s (%s)\n' \ "$ob" "$done_n" "$scoped" "$tail" "$why_bits" "$skill" MXTK_OB_STATUS="FAULT"; MXTK_OB_N_FAULT=$((MXTK_OB_N_FAULT+1)) + # The whole accepted report shape, once per run (#821 point 1, bin/lib/format-hints.sh): a + # prototype LOOK took five gate runs to learn one requirement at a time. + # Printed after the obligation lines (below), not between a row and its detail lines. + case "$ob" in + prototype-look) _ob_fh="$_ob_fh prototype-look" ;; + look|final-look) _ob_fh="$_ob_fh look-report" ;; + esac elif [ -n "$pending" ]; then printf 'Obligation %-10s PENDING — %d of %d discharged%s; NOT DONE:%s — owner: %s-agent, governed by %s\n' \ "$ob" "$done_n" "$scoped" "$tail" "$pending" "$performer" "$skill" @@ -888,6 +896,9 @@ mxtk_obligations_report() { [ -n "$noproof" ] && printf 'Obligation %-10s NO PROOF-OF-LOOK:%s — the pixel rule, made mechanical (module-review.md stage 5, PROOF-OF-LOOK)\n' \ "$ob" "$noproof" done < "$OBLIGATIONS_TSV" + if [ -n "$_ob_fh" ] && type mxtk_format_hint_once >/dev/null 2>&1; then + local _h; for _h in $_ob_fh; do mxtk_format_hint_once "$_h"; done + fi if [ "$skipped_n" -gt 0 ]; then printf 'Obligations: %s row(s) owed from stages after %s not evaluated — a stage query reads its own stage and earlier; run without a stage for every row\n' \ diff --git a/bin/ready.sh b/bin/ready.sh index 2a559022..604894b5 100755 --- a/bin/ready.sh +++ b/bin/ready.sh @@ -182,6 +182,9 @@ case "$rc5" in 124) row fail gate5 "NOT MEASURED — gate-check stage 5 did not finish in ${STEP_T}s (MXTK_READY_STEP_TIMEOUT)" ;; 0) row ok gate5 "Stage 5 $v5" ;; 2) if printf '%s' "$look5" | grep -q 'accounted for'; then row ok gate5 "Stage 5 MANUAL with the look accounted for (its sign-off is a Decisions row)" + # Build type: poc reports unseen pages as MANUAL, not FAIL (gate-check.sh check_stage_5); the + # look row below names them, and ready is still not ready while one is unseen. + elif printf '%s' "$look5" | grep -q 'never looked at'; then row fail gate5 "Stage 5 MANUAL (Build type: poc) with page(s) never looked at — see the look row" else row fail gate5 "Stage 5 MANUAL with nothing measured — no page recorded as built"; fi ;; *) row fail gate5 "Stage 5 ${v5:-exit $rc5}: $(printf '%s' "$l5" | sed 's/^[A-Z]* · //; s/^Surface MISSING: [^—]*— //' | cut -c1-200)" ;; esac diff --git a/project-bin/_position.sh b/project-bin/_position.sh index 101d4cc7..e86a6e2e 100755 --- a/project-bin/_position.sh +++ b/project-bin/_position.sh @@ -22,8 +22,10 @@ # quieter. # entry_mode_token -> canonical token on stdout, "" if unrecognised. -# Canonical set: requirements-driven | migration | existing-app-change | a-la-carte, plus -# greenfield-retired (a register sync-project.sh has not yet mapped) +# Canonical set: requirements-driven | migration | existing-app-change | a-la-carte | poc, plus +# greenfield-retired (a register sync-project.sh has not yet mapped). `poc` (#819 option 3) is +# the same contract as `Build type: poc` (mxtk_pos_read sets POS_BUILD=poc for it): a demo from a +# brief has no other mode to borrow, and an agent read three scripts looking for one. entry_mode_token() { _mxtk_emt "${1-}"; echo "$_EMT"; } # _mxtk_emt — the tokeniser itself; sets _EMT instead of printing, so exec.sh's reader @@ -66,12 +68,21 @@ _mxtk_emt() { 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 [[ "$v" == poc ]]; then tok="poc" 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_bt_names_full — true when the value names `full` as a WORD ("full", +# "poc → full (CR-01)", "full build"), never as part of one ("fullscreen kiosk demo"). The one test +# both mxtk_pos_read and gate-check.sh use for "this Build type line says full" (re-review of #828: +# a substring test flipped `poc — CONFIRMED (user, fullscreen kiosk)` to a full build, silently). +mxtk_bt_names_full() { + [[ "${1-}" =~ (^|[^A-Za-z])[Ff][Uu][Ll][Ll]([^A-Za-z]|$) ]] +} + # mxtk_auto_word — true when the text's first word is `auto` or `unattended`, any case, with # markdown emphasis, backticks and trailing punctuation ignored ("**Auto** (questions to # questions.md)", "unattended — logged"). THE one reading of an Interview mode value as unattended: @@ -92,7 +103,8 @@ mxtk_auto_word() { # 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_BUILD "poc" when "Build type: poc" or "Entry mode: poc", else "full" (a Build type naming +# full — as a word — wins over Entry mode: poc or a poc prefix; POS_POC_CONFLICT=1 then) # 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 "" @@ -103,7 +115,7 @@ mxtk_auto_word() { # second write of an unattended run got past the plan rule on refuse-once. mxtk_pos_read() { local root="$1" reg line key val in_c=0 in_cur=0 entry_raw="" ad="" bt="" im="" _nc=0 - POS_REG=0; POS_ENTRY=""; POS_ADOPTED=""; POS_BUILD="full"; POS_WAIVED4=0; POS_READOUT=""; POS_AUTO=0 + POS_REG=0; POS_ENTRY=""; POS_ADOPTED=""; POS_BUILD="full"; POS_POC_CONFLICT=0; POS_WAIVED4=0; POS_READOUT=""; POS_AUTO=0 reg="$root/PROJECT.md" shopt -q nocasematch && _nc=1; shopt -s nocasematch if [ -f "$reg" ]; then @@ -148,13 +160,22 @@ mxtk_pos_read() { fi done < "$root/intake.md" fi - [[ "$bt" =~ ^[[:blank:]]*poc([^a-z]|$) ]] && POS_BUILD="poc" + # poc only when the value starts with poc and never names the WORD full ("poc → full (CR-01)" is + # full; "poc (fullscreen kiosk)" is poc). A poc-prefixed line read as full sets POS_POC_CONFLICT. + POS_POC_CONFLICT=0 + if [[ "$bt" =~ ^[[:blank:]]*poc([^a-z]|$) ]]; then + if mxtk_bt_names_full "$bt"; then POS_POC_CONFLICT=1; else POS_BUILD="poc"; fi + fi local _imf="" [ -f "$root/.claude/.interview-mode" ] && { IFS= read -r _imf < "$root/.claude/.interview-mode" || true; } if mxtk_auto_word "${CLAUDE_INTERVIEW_MODE:-}" || mxtk_auto_word "$_imf" || mxtk_auto_word "$im"; then POS_AUTO=1; fi [[ "$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 + # Entry mode: poc implies poc, unless a Build type line says full: full wins, and POS_POC_CONFLICT says so. + if [ "$POS_ENTRY" = poc ]; then + if mxtk_bt_names_full "$bt"; then POS_POC_CONFLICT=1; else POS_BUILD="poc"; fi + fi return 0 } diff --git a/project-bin/exec.sh b/project-bin/exec.sh index c4a721a7..516af8c7 100755 --- a/project-bin/exec.sh +++ b/project-bin/exec.sh @@ -799,6 +799,18 @@ if [ -f "$_XD/_position.sh" ]; then # auto it is held to the requirements-driven plan rule below, or an unattended agent could # write that one line, or skip sync, and build with no plan (review of #792). The remedy is # sync-project.sh or the --adopt it performs, neither of which runs through here (guard rule 7). + # `Entry mode: poc` with a Build type line naming full (review of #828): a full build that kept its + # POC entry line. Read as full, said once per run, and under auto held to the requirements-driven + # plan rule like a retired greenfield register, so editing one line cannot drop every pre-build step. + if [ "${POS_POC_CONFLICT:-0}" = 1 ]; then + if [ "$POS_ENTRY" = poc ]; then + echo "⚠ Entry mode: poc but the Build type line names full — read as a full build; make the two lines agree (gate-check.sh prints the same)." + else + echo "⚠ Build type starts with poc but names full — read as a full build; write Build type: poc or Build type: full (gate-check.sh prints the same)." + fi + POS_NOTE="poc vs build type full" + [ "$POS_AUTO" = 1 ] && [ "$POS_ENTRY" = poc ] && POS_ENTRY=requirements-driven + fi if [ "$POS_ENTRY" = greenfield-retired ]; then echo "⚠ ${MXTK_POS_RETIRED//$PROJECT_ROOT}" POS_NOTE="entry mode greenfield retired, not synced" diff --git a/skills/poc-build.md b/skills/poc-build.md index e1fc2a6b..653869eb 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 (the list now in `skills/must-haves.md`); 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 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`). +**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`; `build-ready` reads `N/A (Build type: poc)` and exits 0, so no module brief or open-questions file is written for it. `Entry mode: poc` is the same declaration; after the user's POC answer, `bin/kickoff.sh --mode poc --by ` writes all of the above. *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-bug03-gates.sh b/tests/wave2/test-bug03-gates.sh index f1788ba5..38c89137 100755 --- a/tests/wave2/test-bug03-gates.sh +++ b/tests/wave2/test-bug03-gates.sh @@ -364,6 +364,8 @@ echo "== T18: build-ready names a multi-line {{PLACEHOLDER}} left in an agent st # per-line grep never saw it, so an untouched stub read "no unfilled placeholders". Counted as a # FAIL like any other unfilled slot since the joined-lines count (was a WARN while only the perl scan saw it). # Decision: an unfilled multi-line placeholder fails build-ready (maintainer, 2026-11-13; supersedes the #509 warning). +# Since #821 point 2 every unfilled slot is a ⚠ until its role is dispatched; it must still be NAMED +# (tests/wave2/test-fast-lane-agent-slots.sh covers WARN vs FAIL). TK="$(cd "$(dirname "$GATE")/.." && pwd)" P="$(mkproj t18)"; mkdir -p "$P/.claude/agents" for a in ba-agent architect-agent mdl-agent gate-agent test-agent review-agent; do @@ -371,7 +373,7 @@ for a in ba-agent architect-agent mdl-agent gate-agent test-agent review-agent; sed -E 's/\{\{[A-Z][A-Z0-9_]*[^}]*\}\}/filled/g' "$TK/agents/$a.md" > "$P/.claude/agents/$a.md" done OUT="$("$GATE" --no-html "$P" build-ready 2>&1)" -case "$OUT" in *'still have unfilled placeholders: {{PROJECT_LOCAL_SOURCES_OF_TRUTH'*) ok "names the multi-line placeholder as a FAIL" ;; +case "$OUT" in *'still have unfilled placeholders: {{PROJECT_LOCAL_SOURCES_OF_TRUTH'*) ok "names the multi-line placeholder" ;; *) bad "multi-line placeholder not named as unfilled: $(printf '%s' "$OUT" | grep -i placeholder)" ;; esac case "$OUT" in *'no unfilled placeholders'*) bad "still claims no unfilled placeholders" ;; *) ok "does not claim the stubs are complete" ;; esac # Filled: the failure is gone. diff --git a/tests/wave2/test-fast-lane-agent-slots.sh b/tests/wave2/test-fast-lane-agent-slots.sh new file mode 100755 index 00000000..6f8aa7fa --- /dev/null +++ b/tests/wave2/test-fast-lane-agent-slots.sh @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# test-fast-lane-agent-slots.sh — build-ready WARNs on {{…}} slots in agent stubs no role was +# dispatched with, and FAILs on mdl-agent's own slots once its dispatch log exists (#821 point 2). +# +# usage: bash tests/wave2/test-fast-lane-agent-slots.sh [path-to-gate-check.sh] +# pass a master checkout's bin/gate-check.sh to see S1 fail there. +# +# Field basis: two simulated builds, 2026-11-20 (claude -p, stubbed Mendix tools): 0 subagents +# dispatched in either, yet build-ready FAILed on the six stubs' slots (POC once, requirements- +# driven twice, the second for a multi-line slot), costing 3 and 6 calls before the first write. +# The stubs are the real ones bin/init-project.sh installs. +# +# S1 a scaffold whose only open build-ready item is the stubs' slots: verdict PASS, the slot +# line is a ⚠ that still names the slots (multi-line {{PROJECT_LOCAL_SOURCES_OF_TRUTH…}} too) +# S2 mdl-agent's dispatch log exists (.claude/loop/dispatch//scripts.tsv): FAIL naming +# mdl-agent and its slots +# S3 mdl-agent filled, log present, the other five still unfilled: PASS, ⚠ for the rest +# S4 every stub filled: the ✓ line, unchanged +set -uo pipefail + +TK0="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +GATE="${1:-$TK0/bin/gate-check.sh}" +case "$GATE" in /*) ;; *) GATE="$PWD/$GATE" ;; esac +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/fast-lane-slots.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: $GATE" + +printf 'zz-no-client-name-zz\n' > "$WORK/deny" +MXTK_NO_GUIDE=1 MXTK_LEAKGUARD_DENYFILE="$WORK/deny" bash "$TK0/bin/init-project.sh" "$WORK/seed" >/dev/null 2>&1 "$WORK/seed/architecture/modules/Rooms/module-brief.md" +printf 'Rooms\n' > "$WORK/seed/design/wireframes/Rooms_Overview.html" +printf ':root { --mxt-accent: #0a5; }\n' > "$WORK/seed/design/ds.css" + +N=0 +mkp() { N=$((N+1)); P="$WORK/p$N"; cp -R "$WORK/seed" "$P"; } +gc() { out="$(bash "$GATE" --no-html "$P" build-ready 2>&1)"; rc=$?; slot="$(printf '%s\n' "$out" | grep 'unfilled')"; } +fill() { perl -0777 -pi -e 's/\{\{(?!DOUBLE_BRACE\}\})[A-Z][^{}]*?\}\}/filled/sg' "$@"; } +log_dispatch() { mkdir -p "$P/.claude/loop/dispatch/Rooms"; printf '2026-11-20\tmdlsource/01-domain.mdl\tcheck ok\n' > "$P/.claude/loop/dispatch/Rooms/scripts.tsv"; } + +echo "-- S1: no role dispatched" +mkp; gc +grep -q '^BUILD-READY: PASS' <<<"$out" && ok "S1 verdict PASS with only the stubs' slots open" || bad "S1 verdict PASS" "$(printf '%s\n' "$out" | grep '^BUILD-READY')" +case "$slot" in *"⚠ agent(s) still have unfilled placeholders: {{"*) ok "S1 the slot line is a warning" ;; *) bad "S1 the slot line is a warning" "$slot" ;; esac +case "$slot" in *"{{PROJECT_LOCAL_SOURCES_OF_TRUTH…}}"*) ok "S1 the multi-line slot is still named" ;; *) bad "S1 the multi-line slot is still named" "$slot" ;; esac + +echo "-- S2: mdl-agent dispatched, its stub unfilled" +mkp; log_dispatch; gc +grep -q '^BUILD-READY: FAIL' <<<"$out" && ok "S2 verdict FAIL once mdl-agent's dispatch log exists" || bad "S2 verdict FAIL" "$(printf '%s\n' "$out" | grep '^BUILD-READY')" +case "$slot" in *"✗ mdl-agent is dispatched"*"{{PROJECT_LOCAL_SOURCES_OF_TRUTH…}}"*) ok "S2 the FAIL names mdl-agent and its slots" ;; *) bad "S2 the FAIL names mdl-agent" "$slot" ;; esac + +echo "-- S3: mdl-agent filled, the rest not" +mkp; log_dispatch; fill "$P/.claude/agents/mdl-agent.md"; gc +grep -q '^BUILD-READY: PASS' <<<"$out" && ok "S3 PASS: the dispatched role is filled" || bad "S3 PASS" "$(printf '%s\n' "$out" | grep -E '^BUILD-READY|✗')" +case "$slot" in *"⚠ agent(s) still have unfilled"*) ok "S3 the other roles' slots still warn" ;; *) bad "S3 the other roles' slots still warn" "$slot" ;; esac + +echo "-- S4: every stub filled" +mkp; fill "$P"/.claude/agents/*.md; gc +case "$out" in *"✓ all 6 agents present, no unfilled placeholders"*) ok "S4 a filled set reads clean" ;; *) bad "S4 a filled set reads clean" "$slot" ;; esac + +echo "" +echo "PASS=$PASS FAIL=$FAIL" +[ "$FAIL" = 0 ] diff --git a/tests/wave2/test-fast-lane-format-hints.sh b/tests/wave2/test-fast-lane-format-hints.sh new file mode 100755 index 00000000..2cfcd762 --- /dev/null +++ b/tests/wave2/test-fast-lane-format-hints.sh @@ -0,0 +1,131 @@ +#!/usr/bin/env bash +# test-fast-lane-format-hints.sh — a gate FAIL on a format the toolkit parses prints the whole +# accepted shape, and every shape printed passes its own parser (#821 point 1). +# +# usage: bash tests/wave2/test-fast-lane-format-hints.sh [toolkit-root] +# toolkit-root defaults to this checkout; a master worktree shows the H*a cases failing there +# (the subject is bin/gate-check.sh + bin/lib/obligation-check.sh + bin/lib/format-hints.sh). +# +# Field basis: two simulated builds, 2026-11-20 (claude -p, stubbed Mendix tools): a prototype +# LOOK took 5 gate runs, one new requirement per FAIL; build-plan row ids were rewritten by sed +# after a FAIL; 10 and 19 calls read gate source before the first model write. +# +# Each case has two halves: (a) the FAIL prints the shape — fails on master; (b) the example +# lines printed are written into a project scaffolded by the real bin/init-project.sh and the +# same gate passes them — so an example can never drift from its parser unnoticed. +# H1 intake markers (Stage P) H2 build plan (Stage 4) H3 coverage ledger (engine) +# H4 LOOK report (Stage 5) H5 prototype LOOK (obligation) H6 each shape once per run +set -uo pipefail + +TK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}" +TK="$(cd "$TK" && pwd)" +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" # the examples always come from this checkout +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/fast-lane-hints.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 "== toolkit: $TK" +. "$HERE/bin/lib/format-hints.sh" +ex() { mxtk_format_hint "$1" | sed -n 's/^ //p'; } # the example lines, indentation stripped + +printf 'zz-no-client-name-zz\n' > "$WORK/deny" +MXTK_NO_GUIDE=1 MXTK_LEAKGUARD_DENYFILE="$WORK/deny" bash "$TK/bin/init-project.sh" "$WORK/seed" >/dev/null 2>&1 /dev/null; git add -A >/dev/null 2>&1 \ + && git -c user.email=t@t -c user.name=t commit -qm scaffold ) >/dev/null 2>&1 +N=0 +mkp() { N=$((N+1)); P="$WORK/p$N"; cp -R "$WORK/seed" "$P"; } +gc() { out="$(bash "$TK/bin/gate-check.sh" --no-html "$@" 2>&1)"; rc=$?; } +stage() { printf '%s\n' "$out" | grep -m1 "^Stage $1 "; } +# answer_all — one marker line under every '## N.' heading, round-robin +answer_all() { + local p="$1"; shift + printf '%s\n' "$@" > "$WORK/markers" + awk -v mf="$WORK/markers" 'BEGIN { while ((getline l < mf) > 0) m[n++] = l } + /^## [0-9]+\./ { print; print ""; print m[i++ % n]; next } { print }' "$p/intake.md" > "$p/intake.tmp" && mv "$p/intake.tmp" "$p/intake.md" +} +shot() { head -c 20000 /dev/urandom > "$1"; } # a capture-sized file (the gate checks >= 10 KB) + +echo "-- H1: intake markers" +mkp; gc "$P" +case "$out" in *"Accepted shape — intake.md"*) ok "H1a Stage P FAIL prints the intake shape" ;; *) bad "H1a Stage P FAIL prints the intake shape" ;; esac +markers=(); while IFS= read -r l; do case "$l" in Answered*|Unverified*|Assumed*) markers+=("$l") ;; esac; done <<<"$(ex intake)" +[ "${#markers[@]}" = 3 ] || bad "H1b three example markers in the hint" "${#markers[@]}" +answer_all "$P" "${markers[@]}"; gc "$P" P +[ "$rc" = 0 ] && ok "H1b the example markers pass Stage P (rc=0)" || bad "H1b the example markers pass Stage P" "rc=$rc $(stage P)" + +echo "-- H2: build plan" +mkp; mkdir -p "$P/architecture/modules/Rooms" +printf '# Module brief — Rooms\n' > "$P/architecture/modules/Rooms/module-brief.md" +printf '| # | Kind | Step | Depends on |\n|---|---|---|---|\n| R01 | BUILD | Rooms domain model | — |\n| 2 | BUILD | Rooms pages | 1 |\n' > "$P/architecture/build-plan.md" +printf '| 4 | Build plan approved | CONFIRMED | |\n' >> "$P/PROJECT.md" +gc "$P" +case "$(stage 4)" in *FAIL*) ;; *) bad "H2 setup: Stage 4 should FAIL" "$(stage 4)" ;; esac +case "$out" in *"Accepted shape — architecture/build-plan.md"*) ok "H2a Stage 4 FAIL prints the build-plan shape" ;; *) bad "H2a Stage 4 FAIL prints the build-plan shape" ;; esac +{ printf '# Build plan\n\n'; ex build-plan | grep '^|'; } > "$P/architecture/build-plan.md" +awk '/^\| Stage \| Decision/ { print; getline; print; print "| 4 | Build plan approved | CONFIRMED | reviewed in chat |"; next } { print }' "$P/PROJECT.md" | grep -v '^| 4 | Build plan approved | CONFIRMED | |$' > "$P/PROJECT.tmp" && mv "$P/PROJECT.tmp" "$P/PROJECT.md" +gc "$P" +case "$(stage 4)" in *"PASS"*) ok "H2b the example plan passes Stage 4" ;; *) bad "H2b the example plan passes Stage 4" "$(stage 4)" ;; esac + +echo "-- H3: coverage ledger" +mkp; mkdir -p "$P/architecture/modules/Rooms" "$P/analysis/rooms/knowledge-base/brd" +printf '# Module brief — Rooms\n' > "$P/architecture/modules/Rooms/module-brief.md" +{ printf '# Build plan\n\n'; ex build-plan | grep '^|'; } > "$P/architecture/build-plan.md" +awk '/^\| Stage \| Decision/ { print; getline; print; print "| 4 | Build plan approved | CONFIRMED | reviewed in chat |"; next } { print }' "$P/PROJECT.md" > "$P/PROJECT.tmp" && mv "$P/PROJECT.tmp" "$P/PROJECT.md" +printf '{"id":"F001","domainEntities":[{"name":"Room"}],"useCases":[{"id":"UC1","name":"Book","actor":"Staff"}]}\n' > "$P/analysis/rooms/knowledge-base/brd/F001.brd.json" +printf '| pointer | type | title | slice | writeMode | acceptance | status |\n|---|---|---|---|---|---|---|\n| /domainEntities/0/name | entity | Room | 1 | create | Room exists | row 2 |\n' > "$P/architecture/coverage-ledger.md" +gc "$P" +case "$(stage 4)" in *FAIL*"coverage ledger has findings"*) ;; *) bad "H3 setup: Stage 4 should FAIL on coverage" "$(stage 4)" ;; esac +case "$out" in *"Accepted shape — a coverage ledger"*) ok "H3a a coverage FAIL prints the ledger shape" ;; *) bad "H3a a coverage FAIL prints the ledger shape" ;; esac +ex coverage-ledger > "$P/architecture/coverage-ledger.md" +gc "$P" +case "$(stage 4)" in *PASS*"coverage ledger clean"*) ok "H3b the example ledger passes Stage 4's coverage measurement" ;; *) bad "H3b example ledger passes Stage 4" "$(stage 4)" ;; esac +mkdir -p "$WORK/cov" +printf '{"id":"F001","domainEntities":[{"name":"Room"}],"useCases":[{"id":"UC1","name":"Book","actor":"Staff"}]}\n' > "$WORK/cov/F001.brd.json" +ex coverage-ledger > "$WORK/cov/ledger.md" +bash "$TK/bin/coverage-check.sh" "$WORK/cov/F001.brd.json" "$WORK/cov/ledger.md" > "$WORK/cov/out" 2>&1 \ + && ok "H3c the same, straight through bin/coverage-check.sh (rc=0)" || bad "H3b example ledger clean" "$(cat "$WORK/cov/out")" +grep -q 'claims ONE element' <<<"$(mxtk_format_hint coverage-ledger)" && ok "H3 the shape states the one-element wildcard rule (SECTION-WIDE)" || bad "H3 one-element rule stated" + +echo "-- H4: LOOK report" +mkp; mkdir -p "$P/docs/progress" +printf 'as-of\t2026-11-20T10:00:00Z\nmodule\tRooms\t2\t0\nunseen\tRooms.Room_Overview\t1000000000\nunseen\tRooms.Booking_New\t1000000000\n' > "$P/docs/progress/look-summary.tsv" +gc "$P" +case "$(stage 5)" in *FAIL*) ;; *) bad "H4 setup: Stage 5 should FAIL" "$(stage 5)" ;; esac +case "$out" in *"Accepted shape — a LOOK report"*) ok "H4a Stage 5 look FAIL prints the LOOK-report shape" ;; *) bad "H4a Stage 5 look FAIL prints the LOOK-report shape" ;; esac +mkdir -p "$P/design/ui-reviews/shots/2026-11-20" +head_sha="$(git -C "$P" rev-parse --short HEAD 2>/dev/null)" +ex look-report | sed "s/1a2b3c4/$head_sha/" | sed 's/$/
/' > "$P/design/ui-reviews/ui-review-2026-11-20-Rooms.html" +for f in $(ex look-report | sed -n 's/^PROOF-OF-LOOK:.*= *//p'); do shot "$P/design/ui-reviews/$f"; done +gc "$P" +case "$(stage 5)" in *"MANUAL"*"2 of 2 built page(s) accounted for"*"2 by PROOF-OF-LOOK"*) ok "H4b the example report clears both pages" ;; *) bad "H4b the example report clears both pages" "$(stage 5)" ;; esac + +echo "-- H5: prototype LOOK" +mkp; mkdir -p "$P/design/ui-reviews/shots/2026-11-20" +printf 'prototype

rooms

\n' > "$P/design/prototype.html" +printf '4 of 4 screen-widths captured\nPROOF-OF-LOOK: rooms@390 = shots/2026-11-20/rooms-390.png\n' > "$P/design/ui-reviews/prototype-look-2026-11-20.html" +gc "$P" +ob="$(printf '%s\n' "$out" | grep -m1 '^Obligation prototype-look')" +case "$ob" in *FAULT*) ;; *) bad "H5 setup: prototype-look should FAULT" "$ob" ;; esac +case "$out" in *"Accepted shape — design/ui-reviews/prototype-look"*) ok "H5a the prototype-look FAULT prints its shape" ;; *) bad "H5a the prototype-look FAULT prints its shape" "$ob" ;; esac +sha="$(tr -d '\r' < "$P/design/prototype.html" | { sha256sum 2>/dev/null || shasum -a 256; } | awk '{print $1}')" +ex prototype-look | sed "s/]*>/$sha/" > "$P/design/ui-reviews/prototype-look-2026-11-20.html" +for f in $(ex prototype-look | sed -n 's/^PROOF-OF-LOOK:.*= *//p'); do shot "$P/design/ui-reviews/$f"; done +gc "$P" +ob="$(printf '%s\n' "$out" | grep -m1 '^Obligation prototype-look')" +case "$ob" in *"PASS — 1 of 1"*) ok "H5b the example prototype report discharges the obligation" ;; *) bad "H5b the example prototype report discharges" "$ob" ;; esac + +echo "-- H6: once per run" +mkp; mkdir -p "$P/docs/progress" "$P/design/ui-reviews" "$P/architecture/modules/Rooms" +printf '# Module brief — Rooms\n' > "$P/architecture/modules/Rooms/module-brief.md" # opens Rooms: the look obligation FAULTs too +printf 'as-of\t2026-11-20T10:00:00Z\nunseen\tRooms.Room_Overview\t1000000000\n' > "$P/docs/progress/look-summary.tsv" +printf 'Rooms · 1 of 1 pages reviewed\n' > "$P/design/ui-reviews/ui-review-2026-11-20-Rooms.html" +gc "$P" +grep -q '^Obligation look .*FAULT' <<<"$out" || bad "H6 setup: the look obligation should FAULT" "$(printf '%s\n' "$out" | grep -m1 '^Obligation look')" +n="$(printf '%s\n' "$out" | grep -c 'Accepted shape — a LOOK report')" +[ "$n" = 1 ] && ok "H6 the LOOK-report shape prints once although Stage 5 and the look obligation both fail on it" || bad "H6 printed once" "n=$n" + +echo "" +echo "PASS=$PASS FAIL=$FAIL" +[ "$FAIL" = 0 ] diff --git a/tests/wave2/test-fast-lane-poc.sh b/tests/wave2/test-fast-lane-poc.sh new file mode 100755 index 00000000..1beb382c --- /dev/null +++ b/tests/wave2/test-fast-lane-poc.sh @@ -0,0 +1,139 @@ +#!/usr/bin/env bash +# test-fast-lane-poc.sh — a POC build owes no build-ready, Stage 5 reads MANUAL, `Entry mode: poc` +# is a declared mode (#819 options 1 and 3). +# +# usage: bash tests/wave2/test-fast-lane-poc.sh [toolkit-root] +# toolkit-root defaults to the checkout this fixture sits in; pass a master worktree to see the +# cases fail there (the subject is gate-check.sh + project-bin/_position.sh + the kick-off brief). +# +# Field basis: simulated unattended POC build, 2026-11-20 (claude -p, stubbed Mendix tools): the +# agent wrote a module brief and fabricated analysis/sme-questions.md only to get build-ready to +# exit 0, read three scripts looking for an Entry mode a POC could declare, and ended with Stage 5 +# FAIL where skills/poc-build.md promises MANUAL. +# +# P1 Build type: poc + Interview mode: auto on a real init-project.sh scaffold: build-ready +# exits 0, says N/A (Build type: poc), never escalates open questions, writes no +# .build-ready-pass stamp; the same scaffold as a full build still FAILs (control) +# P2 Entry mode: poc (no Build type line): tokeniser emits poc; mxtk_pos_read sets +# POS_BUILD=poc and the project is not "undeclared"; gate-check prints no "No entry mode +# declared" banner and reads Stage 1 "not owed (mode: Build type: poc)" +# P3 Stage 5 under poc, with an unseen built page in docs/progress/look-summary.tsv: MANUAL and +# the page still named; the full build FAILs on the same summary (control) +# P4 the kick-off brief (CONVERSION-RUNBOOK.md) no longer demands build-ready of a POC +# P5 Entry mode: poc with Build type: full reads as FULL, loudly (gate-check, exec.sh's reader); +# `Build type: poc → full (CR-01)` reads as full (review of #828) +# P7 a word merely containing "full" ("fullscreen") does not flip a POC (re-review of #828) +# P6 bin/ready.sh on a POC with an unseen page names the page (it parses Stage 5's look text) +set -uo pipefail + +TK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}" +TK="$(cd "$TK" && pwd)" +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/fast-lane-poc.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 "== toolkit: $TK" + +# One real scaffold (init-project.sh), copied per case. +printf 'zz-no-client-name-zz\n' > "$WORK/deny" +MXTK_NO_GUIDE=1 MXTK_LEAKGUARD_DENYFILE="$WORK/deny" bash "$TK/bin/init-project.sh" "$WORK/seed" >/dev/null 2>&1 "$1/intake.tmp" && mv "$1/intake.tmp" "$1/intake.md" +} +N=0 +mkp() { N=$((N+1)); P="$WORK/p$N"; cp -R "$WORK/seed" "$P"; mark_poc_intake "$P"; } +setline() { # setline — replace or drop ": ..." (drop when value empty) + awk -v k="$2" -v v="$3" 'index($0, k ": ") == 1 { if (v != "") print k ": " v; done = 1; next } { print } + END { if (!done && v != "") print k ": " v }' "$1" > "$1.tmp" && mv "$1.tmp" "$1" +} +gc() { out="$(bash "$TK/bin/gate-check.sh" --no-html "$@" 2>&1)"; rc=$?; } + +echo "-- P1: Build type: poc, auto: build-ready is N/A, exit 0" +mkp; setline "$P/PROJECT.md" "Build type" poc; setline "$P/PROJECT.md" "Interview mode" auto +gc "$P" build-ready +[ "$rc" = 0 ] && ok "P1 build-ready exits 0 under Build type: poc" || bad "P1 build-ready exits 0" "rc=$rc" +case "$out" in *"BUILD-READY: N/A (Build type: poc)"*) ok "P1 verdict line says N/A (Build type: poc)" ;; *) bad "P1 verdict line says N/A" "$(printf '%s\n' "$out" | grep BUILD-READY)" ;; esac +case "$out" in *"NOT EVALUATED for open questions"*|*"Gate BLOCKED"*) bad "P1 no open-questions escalation" ;; *) ok "P1 no open-questions escalation (no sme-questions.md needed)" ;; esac +[ ! -f "$P/.mpr-snapshots/.build-ready-pass" ] && ok "P1 no build-ready stamp written for a POC" || bad "P1 no build-ready stamp written" +case "$out" in *"agent(s) still have unfilled"*) ok "P1 the checklist still prints (informational)" ;; *) bad "P1 the checklist still prints" ;; esac +mkp; setline "$P/PROJECT.md" "Build type" full; setline "$P/PROJECT.md" "Interview mode" auto +gc "$P" build-ready +[ "$rc" != 0 ] && case "$out" in *"BUILD-READY: FAIL"*) true ;; *) false ;; esac \ + && ok "P1 control: the same scaffold as a full build still FAILs build-ready" || bad "P1 control: full build FAILs" "rc=$rc" + +echo "-- P2: Entry mode: poc" +. "$TK/project-bin/_position.sh" +[ "$(entry_mode_token "poc" 2>/dev/null)" = poc ] && [ "$(entry_mode_token "**POC** build (demo)" 2>/dev/null)" = poc ] \ + && ok "P2 tokeniser: poc and '**POC** build (demo)' read as poc" || bad "P2 tokeniser emits poc" "$(entry_mode_token poc 2>&1)" +[ "$(entry_mode_token "proof of concept" 2>/dev/null)" = "" ] && ok "P2 tokeniser: other words unchanged ('proof of concept' is not a token)" || bad "P2 tokeniser over-matches" +mkp; setline "$P/PROJECT.md" "Build type" ""; setline "$P/PROJECT.md" "Entry mode" poc +mxtk_pos_read "$P" +[ "$POS_BUILD" = poc ] && ! mxtk_pos_undeclared && ok "P2 mxtk_pos_read: POS_BUILD=poc, position declared" || bad "P2 mxtk_pos_read" "build=$POS_BUILD entry=$POS_ENTRY" +gc "$P" +case "$out" in *"No entry mode declared"*) bad "P2 no 'No entry mode declared' banner" ;; *) ok "P2 no 'No entry mode declared' banner" ;; esac +grep -q '^Stage 1 (Analysis): WAIVED.* not owed (mode: Build type: poc)' <<<"$out" \ + && ok "P2 Stage 1 reads not owed (mode: Build type: poc)" || bad "P2 Stage 1 not owed" "$(printf '%s\n' "$out" | grep '^Stage 1')" +gc "$P" build-ready +[ "$rc" = 0 ] && ok "P2 build-ready N/A under Entry mode: poc too" || bad "P2 build-ready N/A under Entry mode: poc" "rc=$rc" + +echo "-- P3: Stage 5 under poc reads MANUAL, the unseen page still named" +look_summary() { + mkdir -p "$1/docs/progress" + printf 'as-of\t2026-11-20T10:00:00Z\nmodule\tRooms\t2\t1\nunseen\tRooms.Booking_Overview\t1763632800\n' > "$1/docs/progress/look-summary.tsv" +} +mkp; setline "$P/PROJECT.md" "Build type" poc; look_summary "$P" +gc "$P" +grep -q '^Stage 5 (Build): MANUAL.* look: 1 of 2 built page(s) never looked at.*Rooms.Booking_Overview.*Build type: poc' <<<"$out" \ + && ok "P3 Stage 5 MANUAL under poc, page named" || bad "P3 Stage 5 MANUAL under poc" "$(printf '%s\n' "$out" | grep '^Stage 5')" +mkp; setline "$P/PROJECT.md" "Build type" full; look_summary "$P" +gc "$P" +grep -q '^Stage 5 (Build): FAIL.* look: 1 of' <<<"$out" \ + && ok "P3 control: full build FAILs Stage 5 on the same summary" || bad "P3 control: full build FAILs" "$(printf '%s\n' "$out" | grep '^Stage 5')" + +echo "-- P4: kick-off brief" +brief="$(awk '/^```text/{f=1;next} /^```/{f=0} f' "$TK/CONVERSION-RUNBOOK.md")" +grep -q 'Build type: poc: follow skills/poc-build.md instead (no build-ready' <<<"$brief" \ + && ok "P4 the kick-off brief exempts a POC from build-ready" || bad "P4 the kick-off brief exempts a POC" "$(printf '%s\n' "$brief" | grep -n 'build-ready')" + +echo "-- P5: a Build type line naming full wins over Entry mode: poc" +mkp; setline "$P/PROJECT.md" "Build type" full; setline "$P/PROJECT.md" "Entry mode" poc +mxtk_pos_read "$P" +[ "$POS_BUILD" = full ] && [ "$POS_POC_CONFLICT" = 1 ] && ok "P5 mxtk_pos_read: full, conflict flagged" || bad "P5 mxtk_pos_read" "build=$POS_BUILD conflict=${POS_POC_CONFLICT:-}" +gc "$P" +case "$out" in *"⚠ Entry mode: poc but Build type: full — read as a FULL build"*) ok "P5 gate-check prints the conflict" ;; *) bad "P5 gate-check prints the conflict" ;; esac +grep -q '^Stage 1 (Analysis): WAIVED.* not owed (mode: Build type: poc)' <<<"$out" && bad "P5 Stage 1 must be owed again" || ok "P5 Stage 1 is owed again (not excused as poc)" +gc "$P" build-ready +case "$out" in *"BUILD-READY: N/A"*) bad "P5 build-ready is not N/A for the full build" ;; *) ok "P5 build-ready is checked again" ;; esac +mkp; setline "$P/PROJECT.md" "Build type" "poc → full (CR-01)" +mxtk_pos_read "$P"; gc "$P" build-ready +[ "$POS_BUILD" = full ] && case "$out" in *"BUILD-READY: N/A"*) false ;; *) true ;; esac \ + && ok "P5 'Build type: poc → full (CR-01)' reads as full (exec reader and gate-check)" || bad "P5 poc → full reads as full" "build=$POS_BUILD" +case "$out" in *"⚠ Build type: poc → full (CR-01) starts with poc but names full"*) ok "P5 gate-check warns when a poc-prefixed line reads as full" ;; *) bad "P5 gate-check warns on poc → full" ;; esac + +echo "-- P7: 'fullscreen' is not 'full'" +mkp; setline "$P/PROJECT.md" "Build type" "poc — CONFIRMED (user, fullscreen kiosk)"; setline "$P/PROJECT.md" "Interview mode" auto +mxtk_pos_read "$P"; gc "$P" build-ready +[ "$POS_BUILD" = poc ] && [ "$POS_POC_CONFLICT" = 0 ] && ok "P7 exec's reader keeps it poc, no conflict" || bad "P7 exec reader" "build=$POS_BUILD conflict=$POS_POC_CONFLICT" +[ "$rc" = 0 ] && case "$out" in *"BUILD-READY: N/A (Build type: poc)"*) true ;; *) false ;; esac && ! grep -q 'names full\|read as a FULL' <<<"$out" \ + && ok "P7 gate-check keeps it poc (build-ready N/A), no warning" || bad "P7 gate-check" "rc=$rc $(grep -E 'BUILD-READY|FULL' <<<"$out")" +mkp; setline "$P/PROJECT.md" "Entry mode" poc; setline "$P/PROJECT.md" "Build type" "poc (fullscreen kiosk)" +mxtk_pos_read "$P" +[ "$POS_BUILD" = poc ] && [ "$POS_POC_CONFLICT" = 0 ] && ok "P7 Entry mode: poc + 'poc (fullscreen kiosk)' stays poc" || bad "P7 entry poc + fullscreen" "build=$POS_BUILD conflict=$POS_POC_CONFLICT" + +echo "-- P6: ready.sh names a POC's unseen page" +mkp; setline "$P/PROJECT.md" "Build type" poc; look_summary "$P" +( cd "$P" && git init -q . && git add -A && git -c user.email=t@t -c user.name=t commit -qm s ) >/dev/null 2>&1 +r="$(bash "$TK/bin/ready.sh" "$P" 2>&1)" +grep -q 'unseen: Rooms.Booking_Overview' <<<"$r" && ! grep -q 'nothing measured' <<<"$r" \ + && ok "P6 ready.sh names the unseen page, not 'nothing measured'" || bad "P6 ready.sh names the unseen page" "$(grep -E 'gate5|look ' <<<"$r")" + +echo "" +echo "PASS=$PASS FAIL=$FAIL" +[ "$FAIL" = 0 ] diff --git a/tests/wave2/test-kickoff.sh b/tests/wave2/test-kickoff.sh new file mode 100755 index 00000000..79a0a069 --- /dev/null +++ b/tests/wave2/test-kickoff.sh @@ -0,0 +1,137 @@ +#!/usr/bin/env bash +# test-kickoff.sh — bin/kickoff.sh writes the kickoff declarations in the form the gates parse, +# idempotently, and refuses what it does not know (#821 point 3). +# +# usage: bash tests/wave2/test-kickoff.sh [path-to-kickoff.sh] +# on master there is no bin/kickoff.sh, so every case fails there. +# +# Field basis: two simulated builds, 2026-11-20 (claude -p, stubbed Mendix tools): both agents wrote +# the 16 intake markers and the register lines with ad-hoc Python heredocs (POC turns 6-18, +# requirements-driven turns 1-11); the POC agent read three scripts looking for a legal Entry mode. +# The scaffold is the real bin/init-project.sh output; the verdicts are the real gate-check.sh's. +# +# K1 unknown --mode / --build-type / --interview / option: exit 2 naming the accepted values, +# nothing written; no scaffold: exit 2 naming init-project.sh +# K2 requirements-driven + auto: Stage P PASS; register lines and Stage-P rows written; the +# template's defaults ASSUMED (intake + Assumptions); a second run changes no byte +# K3 --mode poc: Build type: poc and poc-build.md's verbatim markers; Stage P PASS; Stage 1 not owed; +# without --interview too (Q9 takes the POC marker, re-review of #828) +# K4 requirements-driven + steering: the unasked questions are listed and Stage P stays FAIL; an +# --answers file for them makes it PASS, each answer verbatim; Q1 in --answers is refused +# K5 a declared mode is never changed by a re-run: exit 3, files byte-identical +# K7 no --by: nothing is CONFIRMED (rows ASSUMED "no person named", markers say so); a re-run +# with --by upgrades kickoff's own rows and markers to CONFIRMED, then is idempotent +# K8 steering with no --build-type: Q16 is left unanswered and listed first, no Build type row +# K6 --mode change records `Change an existing app`, which the shared tokeniser reads as +# existing-app-change +set -uo pipefail + +TK="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +KO="${1:-$TK/bin/kickoff.sh}" +case "$KO" in /*) ;; *) KO="$PWD/$KO" ;; esac +WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/kickoff.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: $KO" +[ -f "$KO" ] || { bad "bin/kickoff.sh exists"; echo "PASS=$PASS FAIL=$FAIL"; exit 1; } + +printf 'zz-no-client-name-zz\n' > "$WORK/deny" +MXTK_NO_GUIDE=1 MXTK_LEAKGUARD_DENYFILE="$WORK/deny" bash "$TK/bin/init-project.sh" "$WORK/seed" >/dev/null 2>&1 &1)"; rc=$?; } +gcP() { bash "$TK/bin/gate-check.sh" --no-html "$1" P >/dev/null 2>&1; } +same() { cmp -s "$1/PROJECT.md" "$2/PROJECT.md" && cmp -s "$1/intake.md" "$2/intake.md"; } +sec() { awk -v n="$2" '$0 ~ "^## " n "\\." { s = 1; next } s && /^## / { exit } s' "$1/intake.md"; } + +echo "-- K1: refusals" +mkp; cp -R "$P" "$WORK/k1-before" +ko "$P" --mode greenfield; [ "$rc" = 2 ] && case "$out" in *"accepted: poc requirements-driven migration change"*) true ;; *) false ;; esac && ok "K1 unknown --mode: exit 2 with the accepted list" || bad "K1 unknown --mode" "rc=$rc $out" +ko "$P" --mode migration --interview loud; [ "$rc" = 2 ] && case "$out" in *"accepted: steering assist auto"*) true ;; *) false ;; esac && ok "K1 unknown --interview: exit 2 with the accepted list" || bad "K1 unknown --interview" "rc=$rc $out" +ko "$P" --mode migration --build-type mvp; [ "$rc" = 2 ] && case "$out" in *"accepted: full poc"*) true ;; *) false ;; esac && ok "K1 unknown --build-type: exit 2 with the accepted list" || bad "K1 unknown --build-type" "rc=$rc $out" +ko "$P" --mode poc --build-type full; [ "$rc" = 2 ] && ok "K1 --mode poc with --build-type full: exit 2 (contradiction)" || bad "K1 poc + full" "rc=$rc" +ko "$P" --mode migration --fast; [ "$rc" = 2 ] && case "$out" in *"accepted: --mode"*) true ;; *) false ;; esac && ok "K1 unknown option: exit 2 listing the options" || bad "K1 unknown option" "rc=$rc $out" +ko "$P"; [ "$rc" = 2 ] && ok "K1 no --mode: exit 2" || bad "K1 no --mode" "rc=$rc" +same "$P" "$WORK/k1-before" && ok "K1 nothing was written by any refusal" || bad "K1 nothing written" +mkdir -p "$WORK/bare"; ko "$WORK/bare" --mode migration +[ "$rc" = 2 ] && case "$out" in *"init-project.sh"*) true ;; *) false ;; esac && ok "K1 no scaffold: exit 2 naming init-project.sh" || bad "K1 no scaffold" "rc=$rc $out" + +echo "-- K2: requirements-driven, auto" +mkp; ko "$P" --mode requirements-driven --interview auto --by "the sponsor" +[ "$rc" = 0 ] && gcP "$P" && ok "K2 exit 0 and Stage P PASS (gate-check.sh P exit 0)" || bad "K2 Stage P PASS" "rc=$rc $(printf '%s\n' "$out" | tail -2)" +grep -q '^Entry mode: requirements-driven$' "$P/PROJECT.md" && grep -q '^Interview mode: auto$' "$P/PROJECT.md" && grep -q '^Build type: full$' "$P/PROJECT.md" \ + && ok "K2 register lines written" || bad "K2 register lines" "$(grep -E '^(Entry mode|Interview mode|Build type):' "$P/PROJECT.md")" +grep -q '^| P | Entry mode: requirements-driven | CONFIRMED | .*consentBy: the sponsor · consentAt: 20' "$P/PROJECT.md" \ + && grep -q '^| P | Build type: full | ASSUMED | .*consentBy: auto-mode' "$P/PROJECT.md" \ + && ok "K2 Stage-P rows: stated values CONFIRMED, the defaulted build type ASSUMED" || bad "K2 decision rows" "$(grep '^| P |' "$P/PROJECT.md")" +grep -q '^Assumed (auto-mode): balanced' <<<"$(sec "$P" 15)" && grep -q '^- Intake Q15: balanced — ASSUMED' "$P/PROJECT.md" \ + && ok "K2 a template default is ASSUMED in intake and listed under Assumptions" || bad "K2 default assumed" "$(sec "$P" 15 | head -3)" +grep -q '^Unverified — how to verify: not asked at kickoff (Interview mode: auto)' <<<"$(sec "$P" 7)" && ok "K2 a question with no default is Unverified, saying how" || bad "K2 no-default question" "$(sec "$P" 7 | head -3)" +cp -R "$P" "$WORK/k2-after1"; ko "$P" --mode requirements-driven --interview auto --by "the sponsor" +[ "$rc" = 0 ] && same "$P" "$WORK/k2-after1" && case "$out" in *"nothing to change"*) true ;; *) false ;; esac \ + && ok "K2 idempotent: the second run changes no byte and says so" || bad "K2 idempotent" "rc=$rc $(diff "$WORK/k2-after1/PROJECT.md" "$P/PROJECT.md"; diff "$WORK/k2-after1/intake.md" "$P/intake.md")" + +echo "-- K3: poc" +mkp; ko "$P" --mode poc --interview auto +[ "$rc" = 0 ] && gcP "$P" && ok "K3 Stage P PASS" || bad "K3 Stage P PASS" "rc=$rc" +grep -q '^Build type: poc$' "$P/PROJECT.md" && ok "K3 Build type: poc written" || bad "K3 Build type: poc" +grep -qx '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' <<<"$(sec "$P" 4)" \ + && grep -qx 'Answered (kickoff call, no person named): POC build' <<<"$(sec "$P" 16)" && ok "K3 poc-build.md's verbatim markers" || bad "K3 poc markers" "$(sec "$P" 4 | head -3)" +g="$(bash "$TK/bin/gate-check.sh" --no-html "$P" 2>&1)" +grep -q '^Stage 1 (Analysis): WAIVED.* not owed (mode: Build type: poc)' <<<"$g" && ok "K3 Stage 1 not owed (mode: Build type: poc)" || bad "K3 Stage 1 not owed" + +mkp; ko "$P" --mode poc --by "the sponsor" +[ "$rc" = 0 ] && gcP "$P" && grep -qx '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' <<<"$(sec "$P" 9)" \ + && ok "K3 --mode poc without --interview: Q9 gets the POC marker, Stage P PASS" || bad "K3 poc without --interview" "rc=$rc $(sec "$P" 9 | head -3)" + +echo "-- K4: steering, then --answers" +mkp; ko "$P" --mode requirements-driven --build-type full --interview steering --by "the sponsor" +[ "$rc" = 0 ] && case "$out" in *"Still to ask in chat (Interview mode: steering): Q2 Q3 Q4 Q5 Q6 Q7 Q8 Q10 Q11 Q12 Q13 Q14 Q15"*) true ;; *) false ;; esac \ + && ok "K4 steering: the 13 unasked questions are listed, none invented" || bad "K4 unasked listed" "$(printf '%s\n' "$out" | tail -3)" +gcP "$P" && bad "K4 Stage P must still FAIL with questions unasked" || ok "K4 Stage P stays FAIL until they are answered" +{ echo "# answers given in chat"; for n in 2 3 4 5 6 7 8 10 11 12 13 14 15; do echo "Q$n: answer $n | from chat"; done; } > "$WORK/answers" +ko "$P" --mode requirements-driven --build-type full --interview steering --by "the sponsor" --answers "$WORK/answers" +[ "$rc" = 0 ] && gcP "$P" && ok "K4 --answers: Stage P PASS" || bad "K4 --answers Stage P" "rc=$rc $(printf '%s\n' "$out" | tail -2)" +grep -qx 'Answered (CONFIRMED by the sponsor): answer 12 | from chat' <<<"$(sec "$P" 12)" && ok "K4 each answer written verbatim" || bad "K4 verbatim" "$(sec "$P" 12 | head -3)" +printf 'Q1: migration\n' > "$WORK/bad-answers"; ko "$P" --mode requirements-driven --interview steering --answers "$WORK/bad-answers" +[ "$rc" = 2 ] && ok "K4 Q1 in --answers refused (it is --mode)" || bad "K4 Q1 refused" "rc=$rc" + +echo "-- K5: a declared mode is not changed by a re-run" +cp -R "$WORK/k2-after1" "$WORK/k5"; P="$WORK/k5"; cp -R "$P" "$WORK/k5-before" +ko "$P" --mode migration --interview auto +[ "$rc" = 3 ] && same "$P" "$WORK/k5-before" && case "$out" in *"Mode changes are decisions"*) true ;; *) false ;; esac \ + && ok "K5 exit 3, nothing written, the rule named" || bad "K5 refused" "rc=$rc $out" +ko "$P" --mode requirements-driven --interview steering --by "the sponsor" +[ "$rc" = 3 ] && ok "K5 an Interview mode change is refused too" || bad "K5 interview change" "rc=$rc" + +echo "-- K7: no --by, then --by" +mkp; ko "$P" --mode requirements-driven --interview auto +[ "$rc" = 0 ] && ! grep -q 'CONFIRMED' <<<"$(grep '^| P |' "$P/PROJECT.md")" \ + && grep -q '^| P | Interview mode: auto | ASSUMED | .*no person named' "$P/PROJECT.md" \ + && grep -qx 'Answered (kickoff call, no person named): auto' <<<"$(sec "$P" 9)" \ + && ok "K7 without --by nothing is CONFIRMED (Interview mode: auto included)" || bad "K7 no CONFIRMED without --by" "$(grep '^| P |' "$P/PROJECT.md")" +ko "$P" --mode requirements-driven --interview auto --by "the sponsor" +[ "$rc" = 0 ] && grep -q '^| P | Interview mode: auto | CONFIRMED | .*consentBy: the sponsor' "$P/PROJECT.md" \ + && [ "$(grep -c '^| P | Interview mode:' "$P/PROJECT.md")" = 1 ] && grep -qx 'Answered (CONFIRMED by the sponsor): auto' <<<"$(sec "$P" 9)" \ + && ok "K7 --by upgrades kickoff's own row (one row, CONFIRMED) and marker" || bad "K7 --by upgrade" "$(grep '^| P |' "$P/PROJECT.md")" +cp -R "$P" "$WORK/k7"; ko "$P" --mode requirements-driven --interview auto --by "the sponsor" +same "$P" "$WORK/k7" && ok "K7 then idempotent" || bad "K7 idempotent after upgrade" + +echo "-- K8: steering, build type not stated" +mkp; ko "$P" --mode requirements-driven --interview steering --by "the sponsor" +[ "$rc" = 0 ] && case "$out" in *"Still to ask in chat (Interview mode: steering): Q16 Q2"*) true ;; *) false ;; esac \ + && [ -z "$(sec "$P" 16 | grep -iE '^(answered|assumed|unverified)')" ] && ! grep -q '^| P | Build type' "$P/PROJECT.md" \ + && ok "K8 Q16 unanswered and listed first, no Build type row" || bad "K8 Q16 unanswered" "$(printf '%s\n' "$out" | grep 'Still'; grep '^| P |' "$P/PROJECT.md")" + +echo "-- K6: change an existing app" +mkp; ko "$P" --mode change --build-type full --interview assist +. "$TK/bin/lib/entry-mode.sh" +grep -q '^Entry mode: Change an existing app$' "$P/PROJECT.md" && [ "$(entry_mode_token "Change an existing app")" = existing-app-change ] && [ "$rc" = 0 ] \ + && ok "K6 'Change an existing app' recorded verbatim, read as existing-app-change" || bad "K6 change mode" "rc=$rc $(grep '^Entry mode' "$P/PROJECT.md")" + +echo "" +echo "PASS=$PASS FAIL=$FAIL" +[ "$FAIL" = 0 ]