Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
`docs/RELEASE-PROCESS.md` §8.

## Unreleased
- fix(exec, ready, gate-check): **unattended mode is recognised by its first word, and an agent cannot approve its own skipped plan** (composition review of the entry-mode PRs): one helper, `mxtk_auto_word` (`project-bin/_position.sh`), now decides "is this Interview mode unattended" for `exec.sh`, `gate-check.sh --adopt` and `ready.sh` — a register line `Interview mode: auto (gate questions go to questions.md …)` was read as attended by the first two, and in a field smoke run the second write of an unattended build got past the plan rule on refuse-once. `ready.sh` reports NOT READY (row `adoption`, named in the evidence file) while any `consentBy: auto-mode` adoption row is unconfirmed — the ✋ only failed Stage 6, which ready.sh does not run before the register reaches Stage 6. Auto is now the STRICTEST of `$CLAUDE_INTERVIEW_MODE`, `.claude/.interview-mode` and the register line, so `CLAUDE_INTERVIEW_MODE=steering` no longer overrides a register that says auto (intended: an override must not quietly switch the unattended guards off). Under auto, a project with no `Entry mode:` is refused like a pipeline mode until build-ready passes or it adopts (attended: banner only, as before). Checkpoint skills no longer describe greenfield as a live mode. Fixtures: `test-mode-contract.sh` W and U, `test-ready.sh` R4 — composition review of #790–#792, Nov 2026
- fix(ci, ready): **review of #788: the toolkit's own text no longer trips its READY check, CI no longer goes red mid-stage, and synced projects start advisory.** The `RESUME.md` starter and `close-task.sh` began a line with READY ("**READY is not written in this file.**"), so every fresh project failed CI and Stage 6 could never pass (now "Only bin/ready.sh writes READY"; a fixture runs init → commit → CI). Check (a) now fails only on stages the register records as passed and warns on the stage in progress (a fresh project at Stage P was red from its first push). `MXTK_CI_ENFORCE` in the workflow: `init-project.sh` installs "1", `sync-project.sh` installs "0" so stage and order checks warn until switched on; the hand-written READY check fails either way — independent review of #788
- fix(ready, ci, gate-check): **field run of the CI gate and `ready.sh` on a six-app copy (#788)**: a hand-written `# READY FOR BENCH (fix round 6, …)` heading passed the `ready` check (READY followed by words now counts; heading markup stripped); `ready.sh` ran over 300 s with no output (every external step now names itself, has stdin closed and a watchdog, `MXTK_READY_STEP_TIMEOUT`, default 120 s; a killed step is NOT MEASURED); the `order` check counted 0 of 234 per-app scripts (`apps/<App>/mdlsource/` now counted); and Stage 5 returned an empty verdict on any project with neither a look ledger nor a summary (`rows` unbound under `set -u`, introduced earlier in this PR); on the re-run, claims in a lowercase root `status.md` were not scanned (root status/progress/resume files now matched in any case), and an annotated `- Interview mode: auto (…)` line, which `interview-mode.sh` resolves to steering, waived the independent review (the raw line's first word now decides whether the review is owed) — parent session's field run
- new(ci, ready): **the gate an agent cannot skip, and a READY nobody can hand-write.** `bin/ci-gates.sh` runs in the project's own CI (`.github/workflows/toolkit-gates.yml`, from `templates/ci/`, installed by `init-project.sh` and `sync-project.sh` create-if-absent, never overwritten, beside any existing CI) on every push and PR, over the committed tree at the pinned toolkit commit: the claimed stage's gate FAILs, a READY line `bin/ready.sh` did not write (`bin/lib/ready-claims.sh`, also a Stage 6 FAIL), committed unseen pages under a done-claim, and model work before Stage 4 all fail it (otherwise it prints `look: K of N pages seen` as a visible warning), in seconds, with no Mendix runtime. `ready.sh` now also requires the position (stages P and 0–4 PASS, WAIVED or not owed by the entry mode: a field run wrote READY with Stage P never passed), honours `Waived obligation must-haves`, writes a review packet (`docs/progress/review-packets/<scope>.html`: screenshot beside target with the reviewer's score, paths only), reads the must-have mark on its tracked path `docs/progress/must-haves/<Module>.md`, and names every app of a multi-app project instead of checking nothing (field runs, 2026-11: agents skip in-session gates; a hand-written READY graded a 0-of-78-looked build done) — two unattended field runs
Expand Down
5 changes: 4 additions & 1 deletion bin/gate-check.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3280,7 +3280,10 @@ if [ -n "$ADOPT_STAGE" ] || [ -n "$WAIVE_STAGE" ]; then
# Stage 6 FAILing until a person puts their name in consentBy. Interactive runs are unchanged.
case "$ADOPT_STAGE" in 4|5|6|7)
case "$ENTRY_MODE" in migration|requirements-driven)
if [ "$(bash "$TOOLKIT_DIR/bin/interview-mode.sh" "$PROJECT_DIR" 2>/dev/null)" = auto ]; then
# Strictest reading (mxtk_auto_word, project-bin/_position.sh): the resolver, or the register
# line's first word — interview-mode.sh reads "auto (questions go to ...)" as steering.
if [ "$(bash "$TOOLKIT_DIR/bin/interview-mode.sh" "$PROJECT_DIR" 2>/dev/null)" = auto ] \
|| { declare -F mxtk_auto_word >/dev/null && mxtk_auto_word "$(reg_field "interview mode" 2>/dev/null || true)"; }; then
_ad_st=4; [ "$ADOPT_STAGE" = 4 ] && _ad_st=3
register_add_decision "$_ad_st" "Adopted at stage $ADOPT_STAGE (skips design/plan): $WAIVER_REASON" "ASSUMED" \
"consentBy: auto-mode · consentAt: $(date -u +%Y-%m-%d) — ✋ human-pending: a person confirms or overturns it (their name in consentBy); Stage 6 FAILs until then" \
Expand Down
28 changes: 22 additions & 6 deletions bin/ready.sh
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@

set -u
TOOLKIT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
. "$TOOLKIT_ROOT/bin/lib/entry-mode.sh" # mxtk_auto_word: the one first-word reading of Interview mode

usage() { echo "usage: ready.sh <project-root> [--module <M> | --app <A>] [--no-commit]" >&2; exit 2; }

Expand Down Expand Up @@ -157,6 +158,20 @@ done
if [ -z "$pbad" ]; then row ok position "6 of 6 stages before Build PASS or WAIVED (P, 0-4)"
else row fail position "$pk of 6 stages before Build PASS or WAIVED — not: $pbad. Pass them, or record where this project joined (gate-check.sh --adopt 5 --reason \"...\")"; fi

# --- ✋ adoptions an unattended agent recorded itself ---------------------------------------------
# Under Interview mode: auto, `gate-check.sh --adopt` past Stage 3/4 writes an ASSUMED Decisions row
# stamped `consentBy: auto-mode`. That adoption clears the position row above, exec.sh's plan rule
# and the CI order check — so without this row an agent could approve its own skip of the design and
# the plan and still reach READY (the ✋ only failed Stage 6, which this script runs only once the
# register says Stage 6). A person confirms by putting their name in consentBy; until then: NOT READY.
ah_lines=""
[ -f "$REG" ] && ah_lines="$(grep -niE '^[[:space:]]*\|.*adopted at stage.*consentby[[:space:]]*:[[:space:]]*[`*]*auto-mode' "$REG" | cut -d: -f1 | tr '\n' ' ' | sed 's/ *$//')"
if [ -n "$ah_lines" ]; then
row fail adoption "$(printf '%s\n' $ah_lines | grep -c .) unconfirmed ✋ adoption(s) an agent recorded under Interview mode: auto — PROJECT.md line(s) $ah_lines. A person confirms (their name in consentBy) or overturns each"
else
row info adoption "no unconfirmed ✋ auto-mode adoption in PROJECT.md"
fi

# --- gate 5 ---------------------------------------------------------------------------------
step "gate5: gate-check stage 5" "$TMP/g5" env MXTK_LOOK_MODULE="$MOD" bash "$GC" --no-html "$ROOT" 5; rc5=$?
g5="$(cat "$TMP/g5")"
Expand Down Expand Up @@ -271,15 +286,16 @@ MODE="$(grep -E '^(steering|assist|auto)$' "$TMP/mode" 2>/dev/null | tail -1)"
# register read `- Interview mode: auto (gate questions go to questions.md ...)`, the resolver said
# steering, and this script said "a human sees the screens" for a run nobody watched. So the raw
# line's first word decides too: auto / unattended means owed, whatever the resolver concluded.
# The first-word rule lives in ONE place, mxtk_auto_word (project-bin/_position.sh, through the
# bin/lib/entry-mode.sh shim), shared with exec.sh's plan rule and gate-check.sh's --adopt ✋ check.
RAWMODE=""
[ -f "$REG" ] && RAWMODE="$(grep -m1 -iE '^[-*>[:space:]]*(\*\*)?Interview mode(\*\*)?[[:space:]]*:' "$REG" | sed 's/^[^:]*:[[:space:]`*]*//' | awk '{print tolower($1)}' | tr -cd 'a-z')"
case "$RAWMODE" in
auto|unattended)
[ -f "$REG" ] && RAWMODE="$(grep -m1 -iE '^[-*>[:space:]]*(\*\*)?Interview mode(\*\*)?[[:space:]]*:' "$REG" | sed 's/^[^:]*:[[:space:]`*]*//')"
if [ -n "$RAWMODE" ] && mxtk_auto_word "$RAWMODE"; then
if [ "$MODE" != auto ]; then
echo " note review owed: PROJECT.md's Interview mode line starts with \"$RAWMODE\"; interview-mode.sh resolved ${MODE:-nothing} — the stricter reading decides whether a person saw the screens" >&2
echo " note review owed: PROJECT.md's Interview mode line starts with \"$(printf '%s' "$RAWMODE" | awk '{print $1}')\"; interview-mode.sh resolved ${MODE:-nothing} — the stricter reading decides whether a person saw the screens" >&2
MODE=auto
fi ;;
esac
fi
fi
RV_DIR="$ROOT/docs/progress/look-reviews"
: > "$TMP/scores"
# Review files are read in every mode (the packet shows them); only auto mode requires them.
Expand Down
30 changes: 22 additions & 8 deletions project-bin/_position.sh
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,20 @@ _mxtk_emt() {
_EMT="$tok"
}

# mxtk_auto_word <text> — 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:
# exec.sh (through mxtk_pos_read), gate-check.sh's --adopt ✋ check and ready.sh all call it, so the
# three cannot drift apart again (ready.sh had the first-word rule; the other two read exact values).
mxtk_auto_word() {
local w="${1-}"
w="${w//[\`*_]/}"
[[ "$w" =~ ^[[:blank:]\>-]*([A-Za-z]+) ]] || return 1
w="${BASH_REMATCH[1]}"
case "$w" in [Aa][Uu][Tt][Oo]|[Uu][Nn][Aa][Tt][Tt][Ee][Nn][Dd][Ee][Dd]) return 0 ;; esac
return 1
}

# mxtk_pos_read <project-root> — reads <root>/PROJECT.md once (HTML comments skipped: the
# scaffold's own comments name these labels) and, when the register has no Entry mode line, the
# intake.md §1 answer. Sets, never prints:
Expand All @@ -82,9 +96,11 @@ _mxtk_emt() {
# 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 ""
# POS_AUTO 1 when the interview mode resolves to auto (unattended): $CLAUDE_INTERVIEW_MODE,
# else .claude/.interview-mode, else the register line — bin/interview-mode.sh's
# order. A value with trailing text is not auto there either (it reads steering).
# POS_AUTO 1 when ANY of $CLAUDE_INTERVIEW_MODE, .claude/.interview-mode or the register's
# "Interview mode:" line starts with auto / unattended (mxtk_auto_word). The strictest
# reading wins, as in ready.sh: a field register read `Interview mode: auto (gate
# questions go to questions.md ...)`, the exact-value read called that attended, and the
# 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
Expand Down Expand Up @@ -133,11 +149,9 @@ mxtk_pos_read() {
done < "$root/intake.md"
fi
[[ "$bt" =~ ^[[:blank:]]*poc([^a-z]|$) ]] && POS_BUILD="poc"
if [ -n "${CLAUDE_INTERVIEW_MODE:-}" ]; then im="$CLAUDE_INTERVIEW_MODE"
elif [ -f "$root/.claude/.interview-mode" ]; then IFS= read -r im < "$root/.claude/.interview-mode" || true
fi
im="${im//\`/}"; im="${im%.}"
[[ "$im" =~ ^[[:blank:]]*(auto|unattended)[[:blank:]]*$ ]] && POS_AUTO=1
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
Expand Down
44 changes: 27 additions & 17 deletions project-bin/exec.sh
Original file line number Diff line number Diff line change
Expand Up @@ -793,28 +793,38 @@ if [ -f "$_XD/_position.sh" ]; then
POS_NOTE="entry mode greenfield retired, not synced"
[ "$POS_AUTO" = 1 ] && POS_ENTRY=requirements-driven
fi
if [ "$POS_ENTRY" = greenfield-retired ]; then
:
elif mxtk_pos_undeclared; then
echo "⚠ $MXTK_POS_BANNER"
POS_NOTE="no entry mode declared"
elif [ "$PATCH_MODE" != "1" ] && [ "$POS_BUILD" != poc ] && [ "$POS_AUTO" = 1 ] \
&& { [ "$POS_ENTRY" = migration ] || [ "$POS_ENTRY" = requirements-driven ]; } \
&& [ ! -f "$PROJECT_ROOT/.mpr-snapshots/.build-ready-pass" ] && [ "$POS_WAIVED4" != 1 ] \
&& case "$POS_ADOPTED" in 5|6|7) false ;; *) true ;; esac; then
# UNATTENDED (Interview mode: auto) — the primary case. No refuse-once here: an agent re-runs
# what refused it, so every write is refused until the mode's pre-build steps are done, i.e.
# `gate-check.sh <p> build-ready` has PASSed (it leaves .mpr-snapshots/.build-ready-pass), or
# the register adopts at 5+ / waives Stage 4 — an adoption under auto is recorded as a ✋
# human-pending decision that keeps Stage 6 FAILing until a person confirms it. A plan on disk
# alone does not clear it: nobody has checked it. Neither remedy runs through exec.sh.
# UNATTENDED (Interview mode: auto) — the primary case. No refuse-once here: an agent re-runs
# what refused it, so every write is refused until the mode's pre-build steps are done, i.e.
# `gate-check.sh <p> build-ready` has PASSed (it leaves .mpr-snapshots/.build-ready-pass), or
# the register adopts at 5+ / waives Stage 4 — an adoption under auto is recorded as a ✋
# human-pending decision that keeps Stage 6 FAILing, and ready.sh NOT READY, until a person
# confirms it. A plan on disk alone does not clear it: nobody has checked it. Neither remedy runs
# through exec.sh. _plan_auto_hold says whether this write is held; _plan_auto_refuse refuses it.
_plan_auto_hold() {
[ "$PATCH_MODE" != "1" ] && [ "$POS_BUILD" != poc ] && [ "$POS_AUTO" = 1 ] \
&& [ ! -f "$PROJECT_ROOT/.mpr-snapshots/.build-ready-pass" ] && [ "$POS_WAIVED4" != 1 ] \
&& case "$POS_ADOPTED" in 5|6|7) false ;; *) true ;; esac
}
_plan_auto_refuse() { # $1 = what the register says, for the message
_GC="${MXTK_ROOT:-${_TKR:-<toolkit>}}/bin/gate-check.sh"
result_line refused no skipped 1
echo "✗ Plan rule (Interview mode: auto): Entry mode $POS_ENTRY, and the pre-build steps are not done — $_GC $PROJECT_ROOT build-ready has not passed. NOTHING was written."
echo "✗ Plan rule (Interview mode: auto): $1, and the pre-build steps are not done — $_GC $PROJECT_ROOT build-ready has not passed. NOTHING was written."
echo " Remedy: run stages 1-4, then $_GC $PROJECT_ROOT build-ready; or $_GC $PROJECT_ROOT --adopt 5 --reason \"...\" — under auto that is a ✋ human-pending decision, and Stage 6 FAILs until a person confirms it."
echo " Already building past Stage 5? One build-ready pass clears it: its record is kept per clone (.mpr-snapshots/), so each fresh clone runs it once."
log_build "🚫 blocked" "plan rule (auto): Entry mode $POS_ENTRY, build-ready not passed and no adoption — nothing written"
log_build "🚫 blocked" "plan rule (auto): $1, build-ready not passed and no adoption — nothing written"
exit 1
}
if [ "$POS_ENTRY" = greenfield-retired ]; then
:
elif mxtk_pos_undeclared; then
echo "⚠ $MXTK_POS_BANNER"
POS_NOTE="no entry mode declared"
# Unattended with nothing declared is refused like a pipeline mode: the banner alone is what the
# field runs scrolled past. Attended keeps the banner only. Declaring `Entry mode: a-la-carte`
# (or greenfield's two doors: Build type: poc) is a register line, outside exec.sh.
if _plan_auto_hold; then _plan_auto_refuse "no Entry mode declared (declare it at kickoff: intake Q1; a-la-carte for audit or tooling use)"; fi
elif { [ "$POS_ENTRY" = migration ] || [ "$POS_ENTRY" = requirements-driven ]; } && _plan_auto_hold; then
_plan_auto_refuse "Entry mode $POS_ENTRY"
elif [ "$PATCH_MODE" != "1" ] && [ "$POS_BUILD" != poc ] && [ "$POS_AUTO" != 1 ] \
&& { [ "$POS_ENTRY" = migration ] || [ "$POS_ENTRY" = requirements-driven ]; } \
&& ! mxtk_plan_evidence "$PROJECT_ROOT"; then
Expand Down
2 changes: 1 addition & 1 deletion skills/checkpoints/checkpoint-cutover.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
**Template:** See `checkpoint-template.md` for format rules.
**Hard gate:** Stage 7 is a `✋` gate — every answer here must land in `PROJECT.md` as `CONFIRMED`. No `ASSUMED` defaults past this checkpoint; if the user can't answer yet, the pipeline waits.

Migration-mode only. Greenfield and requirements-driven builds with no legacy data skip Stage 7 entirely — record that skip in `PROJECT.md` as a one-line decision ("no legacy system, no cutover"), don't leave it implicit.
Migration-mode only. Requirements-driven builds (from documents or a conversation) and POC builds with no legacy data skip Stage 7 entirely — record that skip in `PROJECT.md` as a one-line decision ("no legacy system, no cutover"), don't leave it implicit.

---

Expand Down
2 changes: 1 addition & 1 deletion skills/checkpoints/checkpoint-extraction.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ the title is about the *output*, not about whether an AST extractor ran.
|---|---|
| Migration | Path A extractor output, plus anything Paths B/C added. |
| Requirements-driven | The KB that `kb-generation.md` built from the document corpus. The same over-reach happens — a document set covers more ground than the slice under discussion, and an LLM extraction pass will happily represent all of it. |
| Greenfield | No KB, no checkpoint. Scope was settled at CAC-1 and there is no extraction result to diff it against. |
| Requirements-driven from a conversation, or a POC (greenfield was retired) | No KB, no checkpoint. Scope was settled at CAC-1 and there is no extraction result to diff it against. |

---

Expand Down
2 changes: 1 addition & 1 deletion skills/checkpoints/checkpoint-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ What varies is only where the capability map comes from:
|---|---|
| Migration | `triage.md`'s Business Capability Map, from the codebase. |
| Requirements-driven | The same table in `triage.md`, built from the document corpus and any DB schema — `document-discovery.md` and `bin/source-sufficiency.sh`'s pass-1 inventory feed it. A spec pack has capabilities exactly like a codebase does. |
| Greenfield | There is no corpus. Run the brainstorm anyway, off the user's own description, and record the result — it is the only scope statement the project will have. |
| Requirements-driven from a conversation (greenfield was retired) | There is no corpus. Run the brainstorm anyway, off the user's own description, and record the result — it is the only scope statement the project will have. |
| Change an existing app | The app map (`analysis/app-report.json`, run at Stage 0a) plus the user's own answers to *what do you want to work on* and *do you have input documents*. The brainstorm is about what the change touches, not about ordering the whole app. |

**Do not skip the brainstorm because the map was easy to build.** A short capability list makes
Expand Down
Loading
Loading