Skip to content

Commit 4b2afa6

Browse files
committed
Restatement guards: review fixes (done- order, applied record, in-order replay, STOP 29 command)
Review of #311 (held): 1. script-owners.sh orders and matches scripts with a leading done- removed: a raw sort put an executed done-05-x.mdl after 09-y.mdl and called the NEW 09 a replay; `-- supersedes: 05-x.mdl` stopped matching after the rename. 2. describe-baseline.sh record-applied <script> records each document's live hash after a write; verify reads SAME when the live body is the script's own recorded write (a re-run) or when a baselined document is absent (a rebuild onto a fresh model). exec.sh is not changed here: the one call it needs after a gate pass is proposed in the PR; the fixture runs that case only when exec.sh carries it (NOT RUN otherwise) and passes 67/67 with the patch applied. 3. Replaying older co-owned scripts in run order is quiet: the "replaying reverts O" verdicts ask the model first (document absent, or live body applied by this script or an older one). No ./mxcli to ask stays a conflict. 4. "Not found" matching follows recorded mxcli output (entity/constant not-found, rc 1) by shape: non-zero exit, no body, "not found: <Doc>"; "no describable document" and parse errors fail the call instead. No capture of a missing MICROFLOW/PAGE exists in the repo. 5. STOP 29 gives a pipe-free grep over mprcontents/ instead of the codec library. 6. Cut the Step 0 line that repeated STOP 22. Fixture tests/wave2/test-restatement-guard.sh: 65 ok + 1 NOT RUN on this branch. Refs #261 Refs #269 Refs #309 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
1 parent 4294759 commit 4b2afa6

5 files changed

Lines changed: 243 additions & 38 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
1717

1818
## Unreleased
1919

20-
- feat(exec): **restatement guards before every MDL write — a stale `-- baseline:` DESCRIBE (`bin/describe-baseline.sh`) and a document another `mdlsource/` script also owns (`bin/script-owners.sh`) — warn by default, refuse under `MXTK_RESTATE_GUARD=refuse` or exec approval `ask`; `gate-check.sh` prints the co-owned count; preflight STOP 21 covers draft-ahead batches and script ownership.** A script drafted from a DESCRIBE taken before an earlier script ran put four old messages back with check, mxbuild and lint green ([#261](https://github.com/MendixMau/mxcli-project-toolkit/issues/261)); three apps had 99/579, 130/357 and 38/159 documents created by more than one script, so every replay of an older one reverts the newer ([#269](https://github.com/MendixMau/mxcli-project-toolkit/issues/269)). The owner parser was run over real MDL (mxcli v0.23.0 DESCRIBE captures, the StyleGallery tree: 0 of 20 co-owned, the agent examples), where a string literal spanning lines hid a microflow from a per-line lexer; field run on a project still owed. — AlvinnYeo, MendixMau
20+
- feat(exec): **restatement guards before every MDL write — a stale `-- baseline:` DESCRIBE (`bin/describe-baseline.sh`) and a document another `mdlsource/` script also owns (`bin/script-owners.sh`) — warn by default, refuse under `MXTK_RESTATE_GUARD=refuse` or exec approval `ask`; `gate-check.sh` prints the co-owned count; preflight STOP 21 covers draft-ahead batches and script ownership.** A script drafted from a DESCRIBE taken before an earlier script ran put four old messages back with check, mxbuild and lint green ([#261](https://github.com/MendixMau/mxcli-project-toolkit/issues/261)); three apps had 99/579, 130/357 and 38/159 documents created by more than one script, so every replay of an older one reverts the newer ([#269](https://github.com/MendixMau/mxcli-project-toolkit/issues/269)). Executed scripts renamed `done-` keep their run order and header names; a re-run after a clean exec (`describe-baseline.sh record-applied`), a rebuild onto a fresh model, and an in-order replay with `-- supersedes:` headers stay quiet. The owner parser was run over real MDL (mxcli v0.23.0 DESCRIBE captures, the StyleGallery tree: 0 of 20 co-owned, the agent examples), where a string literal spanning lines hid a microflow from a per-line lexer; field run on a project still owed. — AlvinnYeo, MendixMau
2121
- fix(exec): **when mxbuild ran on the baseline and then crashes on the written model (no errors file, non-zero exit), the write is rolled back like a failed gate; the kept-write message now says STOP and names `restore-mpr.sh`; preflight STOP 29: DESCRIBE omits module-role and layout-row visibility, so a page restated from it silently loses them.** Field: a two-hop data source passed check, mxbuild's loader crashed, the write was kept and the next script ran on a model nothing could load; one page had 19 role-locked widgets DESCRIBE did not print, a snippet 56 row-visibility rules (refs [#309](https://github.com/MendixMau/mxcli-project-toolkit/pull/309)). — AlvinnYeo
2222
- feat(lint): **Lint Batch 3 — TXT001 build-process words in user-visible text, TXT002 non-ISO dates in user-visible text, UI001 Data grid 2 / Atlas input layout traps.** From the 2026-10-12 UX-fix retros ([#280](https://github.com/MendixMau/mxcli-project-toolkit/issues/280), [#282](https://github.com/MendixMau/mxcli-project-toolkit/issues/282), [#276](https://github.com/MendixMau/mxcli-project-toolkit/issues/276)): leaked words reached 3 of 3 apps and non-ISO dates 2 of 3, each past a one-off glossary grep; a list view in a grid column and a width on an Atlas input each cost fix rounds. Warning severity, `_rule` finding on a missing field, an empty `strings()` under a FULL-catalog rule, or vocabulary that matches nothing; 23 cases in `tests/lint-rules/test-batch3-rules.sh` (harness gained a `strings()` mock). Field run (mxcli 0.26.0, 21-module Mendix 11.12 model): 0/0/0 over 478 user-visible strings and 271 widgets, with loosened positive controls returning 27/50/17 through the same accessors. TXT002 cannot see format strings inside expressions — that half is a blocked row. `process/lint-backlog.md` Batch 5 lists all 17 candidates from the three issues (rows 32–48) — MendixMau
2323
- new(process): **feedback typed mid-build gets a change log in `PROJECT.md`, written before any edit, and the BRD/decision/architecture/wireframe is edited before the MDL.** Across 12 mid-build changes on real projects, 12 went straight into MDL and 0 updated a BRD, build plan or wireframe; the drift-sync `UNSYNCED` marker was never written once, and its absence is invisible, so every gate passed on silence. At the other extreme, one already-settled entity change cost ~270k tokens through two helper agents, and one screenshot-driven fix took 4 rounds because it regressed twice. New `skills/change-intake.md` (baseline, lead+ba, Stages 2–7; routing trigger "the user gives feedback or asks for a change mid-project"): one `## Change log` row per ask (`CR | Date | Source | Verbatim ask | Class | Size | Entry artifact | Status | Closed-by`), six classes, each mapped to its entry artifact (a decision is superseded by a new row, never edited; a built page's visual change is recorded as a before/after screenshot pair instead of wireframe upkeep; impl/bug need only a regression journey). Ceremony is proportional: a small change the user typed gets a one-line receipt and no question, a medium one gets one batched question at the next module gate, a large one or one that contradicts a CONFIRMED decision is asked and stopped on, and stakeholder asks wait for the user. Statuses run open → refined → agreed → applied → proven, or rejected. `bin/lib/change-log.sh` holds the one template and the parser: `init-project.sh` writes the section, `sync-project.sh` appends it once to older projects, and `gate-check.sh` prints a **warn-only** `Change log:` line plus a dashboard row (rows not yet applied, N of M; applied/proven rows with no Closed-by; unrecognised statuses). It becomes blocking only after two projects' counts match a hand count. `project-bin/exec.sh --cr CR-NN` tags the BUILD-LOG detail cell (metrics-ledger columns unchanged). Ownership contradiction fixed: the lead marks; ba-agent flushes BRDs and briefs; architect-agent flushes wireframes and `architecture/` (runbook §3b, `iterative-build-loop.md`, `agent-roles.md`, both stubs, `close-the-loop.md`). Inbox TD-04's change-loop half is promoted here, and its row is narrowed to the two unpromoted items. Fixture `tests/wave2/test-change-log.sh` (39 cases, PROJECT.md built by the real init) — MendixMau

‎project-bin/describe-baseline.sh‎

Lines changed: 94 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,18 @@
1111
# bin/describe-baseline.sh verify <script.mdl> re-DESCRIBE each baselined document and compare.
1212
# exit 0 all match · 1 drift (one DRIFT row each)
1313
# · 2 no baseline header · 3 could not DESCRIBE
14+
# bin/describe-baseline.sh record-applied <script.mdl>
15+
# after a gate pass: record each document's live
16+
# hash as written BY this script (applied.tsv)
17+
# bin/describe-baseline.sh live <KIND> <Doc> prints sha256=<hex> or absent
18+
# bin/describe-baseline.sh applied-by <Doc> <sha256=hex>
19+
# the scripts whose recorded write left that hash
20+
#
21+
# verify reads SAME — not DRIFT — in the two cases that are not a stale draft:
22+
# the live body is this script's own recorded write (a re-run after a clean exec), and
23+
# a baselined document is absent (a rebuild onto a fresh model: the script creates it).
24+
# Without the applied record a re-run of a stamped script read DRIFT, and under exec approval
25+
# `ask` that refused every re-run and every from-empty rebuild.
1426
#
1527
# "Restates" = `create or modify|create or replace microflow|nanoflow|page|snippet` — the
1628
# statements whose body replaces whatever is live (script-owners.sh docs, one parser). A plain
@@ -33,7 +45,14 @@
3345
# them with the hash unchanged — learned-mdl-preflight.md has the STOP row for that.
3446
#
3547
# DESCRIBE runs through the project's own ./mxcli: `mxcli -p <app>.mpr -c "DESCRIBE <KIND> <Doc>"`.
36-
# A document that does not exist exits non-zero ("... not found"), recorded as `absent`.
48+
# A missing document: exit non-zero and "<kind> not found: <Doc>", recorded as `absent`. That
49+
# text is real mxcli output recorded in this repo, never imagined: `Error: entity not found:
50+
# ZKT35.Widget (duration: 1.022958ms)`, EXIT 1 (a 2026-08-07 retest log under bug-logs/)
51+
# and `Error: constant not found: Nope.X`, rc 1 (v0.24.0, project-bin/conformance-check.sh). No
52+
# capture for a missing MICROFLOW/PAGE exists here, so the match is on the shape — non-zero exit,
53+
# no DESCRIBE body, "not found:" followed by this document's name — and never on a parse error
54+
# or "no describable document named" (both verbatim v0.24.0, conformance-check.sh), which say
55+
# nothing about the model and fail the call (exit 3).
3756
# Golden DESCRIBE output: mxcli v0.23.0 captures in tests/wave2/fixtures/context-pack/capture/.
3857
# Consumer: exec.sh runs `verify` before every MDL write that carries a baseline header
3958
# (warn-first; MXTK_RESTATE_GUARD=refuse or exec approval `ask` makes drift a refusal).
@@ -42,20 +61,41 @@
4261
set -u
4362

4463
usage() {
45-
sed -n '3,14p' "$0" | sed 's/^# \{0,1\}//' >&2
64+
sed -n '3,20p' "$0" | sed 's/^# \{0,1\}//' >&2
4665
exit 2
4766
}
4867

4968
HERE="$(cd "$(dirname "$0")" && pwd)"
5069
. "$HERE/_common.sh"
5170

5271
CMD="${1:-}"; SCRIPT="${2:-}"
53-
case "$CMD" in stamp|verify) ;; *) usage ;; esac
54-
[ -f "$SCRIPT" ] || usage
72+
case "$CMD" in
73+
stamp|verify|record-applied) [ -f "$SCRIPT" ] || usage ;;
74+
live) [ $# -eq 3 ] || usage ;;
75+
applied-by) [ $# -eq 3 ] || usage ;;
76+
*) usage ;;
77+
esac
5578
OWNERS="$HERE/script-owners.sh"
5679
[ -f "$OWNERS" ] || { echo "describe-baseline: $OWNERS is not installed (run sync-project.sh)" >&2; exit 3; }
5780

5881
CACHE="$PROJECT_ROOT/.claude/loop/describe-baseline"
82+
APPLIED="$CACHE/applied.tsv" # epoch <tab> script key <tab> Doc <tab> sha256=<hex>
83+
84+
# A script's key: its path relative to the project root with a leading done- taken off the file
85+
# name (iterative-build-loop.md renames an executed script done-<name>); script-owners.sh sorts
86+
# and matches on the same key.
87+
script_key() { # $1 = script path
88+
local abs rel b
89+
abs="$(cd "$(dirname "$1")" 2>/dev/null && pwd)/$(basename "$1")"
90+
rel="${abs#"$PROJECT_ROOT"/}"
91+
b="$(basename "$rel" | sed 's/^done-//')"
92+
printf '%s/%s\n' "$(dirname "$rel")" "$b"
93+
}
94+
# applied_keys <Doc> <sha256=hex> → every script key whose recorded write left that hash.
95+
applied_keys() {
96+
[ -f "$APPLIED" ] || return 0
97+
awk -F'\t' -v d="$1" -v h="$2" '$3 == d && $4 == h && !seen[$2]++ { print $2 }' "$APPLIED"
98+
}
5999

60100
# KIND <tab> Doc for every restated document, first occurrence order, unique.
61101
restated() {
@@ -73,19 +113,57 @@ need_mxcli() {
73113
# Prints the hash (or "absent") of DESCRIBE <kind> <doc>; keeps the text in the cache.
74114
# Returns 1 when DESCRIBE failed for a reason other than "not found".
75115
describe_hash() { # $1 = KIND, $2 = Doc
76-
local out err rc h
116+
local out err rc h all body
77117
err="$(mktemp "${TMPDIR:-/tmp}/dbl-err.XXXXXX")"
78-
out="$("$MXCLI" -p "$MPR" -c "DESCRIBE $1 $2" 2>"$err")"; rc=$?
118+
rc=0
119+
out="$("$MXCLI" -p "$MPR" -c "DESCRIBE $1 $2" 2>"$err")" || rc=$?
120+
# Which stream carries "Error: ..." is not recorded in the captures, so read both. The
121+
# "Connected to: <path>" line seen in the recorded REPL-style output is not part of the body.
122+
body="$(printf '%s\n' "$out" | tr -d '\r' | grep -v '^Connected to:' || true)"
79123
if [ "$rc" -ne 0 ]; then
80-
if grep -qi 'not found' "$err"; then rm -f "$err"; echo absent; return 0; fi
81-
sed 's/^/ mxcli: /' "$err" >&2; rm -f "$err"; return 1
124+
all="$(printf '%s\n' "$out"; cat "$err")"
125+
if [ -z "$(printf '%s' "$body" | grep -v '^Error:' | tr -d '[:space:]')" ] \
126+
&& ! printf '%s\n' "$all" | grep -qE 'Parse error|no describable document' \
127+
&& printf '%s\n' "$all" | grep -qiF "not found: $2"; then
128+
rm -f "$err"; echo absent; return 0
129+
fi
130+
printf '%s\n' "$all" | sed 's/^/ mxcli: /' >&2; rm -f "$err"; return 1
82131
fi
83132
rm -f "$err"
84-
h="$(printf '%s\n' "$out" | tr -d '\r' | mxtk_sha256)"
85-
mkdir -p "$CACHE" 2>/dev/null && printf '%s\n' "$out" | tr -d '\r' > "$CACHE/$h.mdl" 2>/dev/null
133+
h="$(printf '%s\n' "$body" | mxtk_sha256)"
134+
mkdir -p "$CACHE" 2>/dev/null && printf '%s\n' "$body" > "$CACHE/$h.mdl" 2>/dev/null
86135
echo "sha256=$h"
87136
}
88137

138+
if [ "$CMD" = live ]; then
139+
need_mxcli || exit 3
140+
describe_hash "$2" "$3" || exit 3
141+
exit 0
142+
fi
143+
if [ "$CMD" = applied-by ]; then
144+
applied_keys "$2" "$3"
145+
exit 0
146+
fi
147+
if [ "$CMD" = record-applied ]; then
148+
# Every document the script names (create too: a re-run of a plain create is refused by
149+
# mxcli anyway, but its body is still the script's own write for a later co-owner).
150+
need_mxcli || exit 3
151+
KEY="$(script_key "$SCRIPT")"
152+
mkdir -p "$CACHE" 2>/dev/null || exit 3
153+
n=0
154+
while IFS=' ' read -r kind doc; do
155+
[ -n "$doc" ] || continue
156+
v="$(describe_hash "$kind" "$doc")" || continue
157+
[ "$v" = absent ] && continue
158+
printf '%s\t%s\t%s\t%s\n' "$(date +%s)" "$KEY" "$doc" "$v" >> "$APPLIED"
159+
n=$((n + 1))
160+
done <<EOF
161+
$(bash "$OWNERS" docs "$SCRIPT" | awk -F'\t' '{ k = $1 "\t" $2; if (!(k in s)) { s[k] = 1; print k } }')
162+
EOF
163+
echo "describe-baseline: recorded $n applied document(s) for $KEY"
164+
exit 0
165+
fi
166+
89167
if [ "$CMD" = stamp ]; then
90168
need_mxcli || exit 3
91169
DOCS="$(restated)"
@@ -115,17 +193,19 @@ if [ -z "$LINES" ]; then
115193
fi
116194
need_mxcli || exit 3
117195
KINDS="$(restated)"
196+
KEY="$(script_key "$SCRIPT")"
118197
RC=0
119198
while read -r doc want; do
120199
[ -n "$doc" ] || continue
121200
kind="$(printf '%s\n' "$KINDS" | awk -F'\t' -v d="$doc" '$2 == d { print $1; exit }')"
122201
if [ -z "$kind" ]; then echo "STALEHEADER $doc the script no longer restates it — re-stamp"; continue; fi
123202
have="$(describe_hash "$kind" "$doc")" || { echo "UNKNOWN $doc DESCRIBE failed"; [ "$RC" -eq 0 ] && RC=3; continue; }
124203
if [ "$have" = "$want" ]; then echo "SAME $doc"; continue; fi
125-
case "$want/$have" in
126-
absent/*) why="created since the script was drafted" ;;
127-
*/absent) why="deleted since the script was drafted" ;;
128-
*) why="changed since the script was drafted" ;;
204+
if [ "$have" = absent ]; then echo "SAME $doc absent: this script creates it (a rebuild)"; continue; fi
205+
if applied_keys "$doc" "$have" | grep -qxF "$KEY"; then echo "SAME $doc live body is this script's own recorded write"; continue; fi
206+
case "$want" in
207+
absent) why="created since the script was drafted" ;;
208+
*) why="changed since the script was drafted" ;;
129209
esac
130210
echo "DRIFT $doc $why"
131211
old="$CACHE/${want#sha256=}.mdl"; new="$CACHE/${have#sha256=}.mdl"

0 commit comments

Comments
 (0)