aw-spec-cli 0.1.20 → 0.1.22

package/assets/.appweaver/scripts/bash/aw-spec-actions.sh

@@ -22,10 +22,12 @@
 #                                                  -> {checklist_file, created}
 #   list-domains                                   -> {domains[]}
 #   set-domain       --domain <name>               -> {domain, map_path, map_exists, written}
-#   stack-list       [--kind backend|frontend|all] [--preselect <text>] [--include-none] [--suggest]
+#   stack-list       [--kind backend|frontend|all] [--preselect <text>] [--profile <id|label>] [--include-none] [--suggest]
 #                                                  -> {profiles[], ids[], select_options[], count, preselect,
-#                                                      detected_profile, detected_root, root_options[], none_sentinel}
-#                    (--suggest also detects, so the menu opens on what the repo IS)
+#                                                      detected_profile, detected_root, detected_summary,
+#                                                      root_options[], none_sentinel}
+#                    (--suggest also detects, so the menu opens on what the repo IS;
+#                     --profile builds root_options for the stack already chosen)
 #   stack-detect     [--kind <k>] [--exclude-root <p>]…  -> {matches[], backend, frontend, count}
 #                    (matches the repo's OWN files against the profiles; writes nothing)
 #   lane-declare     --profile <id|label|none|detected> [--kind <k>] [--id <lane>] [--source-path|--root <p>]
@@ -51,6 +53,10 @@
 #                                                      design_file/ui_design_file (aliases of the two plans), spec_exists, bootstrap_pending, needs_bootstrap}
 #   checklist-read   --file <path>                 -> {exists, total, checked, items[]}
 #   checklist-apply  --file <path> --results <json>-> {exists, before_checked, after_checked, total, newly_passing[], regressions[]}
+#   plan-coverage    --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--source-path <p>]
+#                    [--test-path <p>] [--reported <json list>]... [--list-only]
+#                                                  -> {ok, total, names[], names_csv, elements[], gaps[], gap_count, gaps_text}
+#                    (which plan elements the lane's code names and the model reported done)
 #   detect-project                                 -> {scaffolded, markers[]}
 #   foundation-list  [--args '<F> <A> [out]']      -> {foundations[], count, preselect_name, preselect_app, out_dir}
 #   foundation-locate --name <F> --app <A> [--out <d>]
@@ -76,7 +82,11 @@
 #    four-document model is gone. "Which files is this slice made of" is now an OKF
 #    query: aw-xref concept-paths / concept-upsert --merge.)
 #   build-compile    [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail}
-#   test-run         [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail}
+#   test-run         [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail,
+#                                                      failing_excerpt, failing_lanes[],
+#                                                      no_setup, setup_reason, setup_missing[]}
+#                    (failing_excerpt = the lines that NAME the failure, per failing lane;
+#                     no_setup = no suite ran because no test command is wired up, with why)
 #   run-migrate      [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail}
 #   deploy-dispatch                                -> {ok, configured, ran, cmd, log_tail}
 #   cr-setup         --cr-id <id> [--feature-dir <path>] [--title <t>] [--wave <n>]
@@ -742,9 +752,10 @@ cmd_stack_list() {
         case "$1" in
             --kind) fwd+=("--kind" "$2"); shift 2 ;;
             --preselect) fwd+=("--preselect" "$2"); shift 2 ;;
+            --profile) fwd+=("--profile" "$2"); shift 2 ;;
             --include-none) fwd+=("--include-none"); shift ;;
             --suggest) fwd+=("--suggest"); shift ;;
-            --help|-h) echo "stack-list [--kind backend|frontend|all] [--preselect <text>] [--include-none] [--suggest]"; return 0 ;;
+            --help|-h) echo "stack-list [--kind backend|frontend|all] [--preselect <text>] [--profile <id|label>] [--include-none] [--suggest]"; return 0 ;;
             *) echo "stack-list: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -1089,9 +1100,12 @@ _cr_id_token() {   # $1 = raw --cr-id value
 }
 
 # One change's wave, read from the documents that carry it: the delta-spec first, then
-# the model delta. Both are stamped together, so either answers; 1 is the floor for a
-# change opened before waves existed.
-_wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
+# the model delta. Both are stamped together, so either answers. EMPTY when neither carries
+# a readable one — `**Wave**: [N]` is the unfilled template line, so "no wave" is a state
+# that happens, and a caller who WRITES the answer somewhere must not write a number nobody
+# derived. A phantom wave is worse than none: the merge and recall fences can see that a
+# wave is missing and say so, but a 1 that was invented downstream reads to them as fact.
+_wave_of_readable() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
     local fd="$1" cr="$2" repo_root="$3" w=""
     local dspec="$fd/changes/$cr/delta-spec.md"
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
@@ -1101,11 +1115,20 @@ _wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
         w=$(sed -n -E 's/^\*\*Wave\*\*:[[:space:]]*([0-9]+).*$/\1/p' "$f" | head -1)
         [ -n "$w" ] && break
     done
-    case "$w" in ''|*[!0-9]*) w=1 ;; esac
-    [ "$w" -ge 1 ] 2>/dev/null || w=1
+    case "$w" in ''|*[!0-9]*) w="" ;; esac
+    if [ -n "$w" ]; then
+        [ "$w" -ge 1 ] 2>/dev/null || w=""
+    fi
     printf '%s' "$w"
 }
 
+# The same reading with the floor applied, for the readers that must show a number — a
+# listing has a column to fill and 1 is the floor for a change opened before waves existed.
+_wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
+    local w; w=$(_wave_of_readable "$1" "$2" "$3")
+    printf '%s' "${w:-1}"
+}
+
 # ─────────────────────────────── context-paths ─────────────────────────────
 # Everything specify needs to know about the domain model of the context it is working
 # in: where the master is, whether it exists yet, and EVERY open delta model beside it.
@@ -1905,15 +1928,23 @@ _foundation_stack() {
 # ──────────────────────────── foundation-list ──────────────────────────────
 # Enumerate available foundations (foundations/<stack>/<Name>/ that carry a real
 # <Name>.pack.txt) so the workflow can let the user PICK one — deterministic, no LLM. An optional
-# --args "<Foundation> <App> [out]" is parsed as a direct-argument fast path:
+# --args "<Foundation> <App>" is parsed as a direct-argument fast path:
 # preselect_name is echoed back only when it names a real foundation; preselect_app
-# / out_dir carry any 2nd/3rd tokens through (empty/"." otherwise).
+# carries any 2nd token through (empty otherwise).
+#
+# A THIRD token is no longer an output directory. A scaffold lands in the source path of
+# the lane it is scaffolding, which is the only thing that keeps generated code inside a
+# declared lane, so there is no caller-chosen destination left to accept. It comes back as
+# `rejected_out` for the workflow to refuse by name rather than be silently ignored —
+# a path argument that is quietly dropped is how someone believes they scaffolded a
+# sandbox and finds they overwrote their service.
 cmd_foundation_list() {
-    local raw=""
+    local raw="" eco_filter=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --args) raw="$2"; shift 2 ;;
-            --help|-h) echo "foundation-list [--args '<Foundation> <App> [out]']  -> {foundations[], count, preselect_name, preselect_app, out_dir}"; return 0 ;;
+            --ecosystem) eco_filter="$2"; shift 2 ;;
+            --help|-h) echo "foundation-list [--args '<Foundation> <App>'] [--ecosystem <eco>]  -> {foundations[], count, preselect_name, preselect_app, rejected_out}"; return 0 ;;
             *) echo "foundation-list: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -1922,13 +1953,19 @@ cmd_foundation_list() {
     # WHICH foundations this repo may be offered. A foundation bundle is a whole
     # compiling project in one ecosystem's languages and build system, so unpacking
     # a .NET one into a Spring repo does not produce a scaffold — it produces a
-    # second, foreign project beside the real one. The declared lanes already say
-    # which ecosystems this repo is, so filter to those and let the gate say why
-    # when that leaves nothing. Nothing declared (a bare greenfield repo, before
-    # select-stack) filters nothing: there is no answer yet to filter on.
+    # second, foreign project beside the real one.
+    #
+    # --ecosystem narrows to the ONE lane being scaffolded, which is stricter than the
+    # union of every declared lane: a repo with a .NET service and a Node UI must not be
+    # offered its .NET bundle while the UI lane is the target. Without it the filter falls
+    # back to every declared lane's ecosystem, and to nothing at all on a bare repo.
     local -a lane_ecos=()
     local e
-    while IFS= read -r e; do [ -n "$e" ] && lane_ecos+=("$e"); done < <(_aw_ecosystems)
+    if [ -n "$eco_filter" ]; then
+        lane_ecos=("$eco_filter")
+    else
+        while IFS= read -r e; do [ -n "$e" ] && lane_ecos+=("$e"); done < <(_aw_ecosystems)
+    fi
 
     local -a foundations=() all=() eco_of=()
     local rel name eco keep
@@ -1943,22 +1980,22 @@ cmd_foundation_list() {
         fi
         [ "$keep" = true ] && foundations+=("$name")
     done < <(_foundation_dirs "$repo_root")
-    # Optional direct-argument fast path: "<FoundationName> <AppName> [OutputDir]".
-    local pre_name="" pre_app="" out_dir="."
+    # Optional direct-argument fast path: "<FoundationName> <AppName>".
+    local pre_name="" pre_app="" rejected_out=""
     if [ -n "$raw" ]; then
         # shellcheck disable=SC2086
         set -- $raw
-        [ -n "${1:-}" ] && pre_name="$1"; [ -n "${2:-}" ] && pre_app="$2"; [ -n "${3:-}" ] && out_dir="$3"
+        [ -n "${1:-}" ] && pre_name="$1"; [ -n "${2:-}" ] && pre_app="$2"; [ -n "${3:-}" ] && rejected_out="$3"
     fi
     # Only preselect a name that actually names an available foundation.
     local match="" f
     for f in "${foundations[@]}"; do [ "$f" = "$pre_name" ] && match="$pre_name"; done
-    printf '{"foundations":%s,"count":%s,"all_foundations":%s,"all_count":%s,"ecosystems":%s,"lane_ecosystems":%s,"filtered":%s,"preselect_name":"%s","preselect_app":"%s","out_dir":"%s"}\n' \
+    printf '{"foundations":%s,"count":%s,"all_foundations":%s,"all_count":%s,"ecosystems":%s,"lane_ecosystems":%s,"filtered":%s,"preselect_name":"%s","preselect_app":"%s","rejected_out":"%s"}\n' \
         "$(json_str_array "${foundations[@]}")" "${#foundations[@]}" \
         "$(json_str_array "${all[@]}")" "${#all[@]}" \
         "$(json_str_array "${eco_of[@]}")" "$(json_str_array "${lane_ecos[@]}")" \
         "$([ ${#lane_ecos[@]} -gt 0 ] && echo true || echo false)" \
-        "$(json_escape "$match")" "$(json_escape "$pre_app")" "$(json_escape "$out_dir")"
+        "$(json_escape "$match")" "$(json_escape "$pre_app")" "$(json_escape "$rejected_out")"
 }
 
 # ─────────────────────────── foundation-locate ─────────────────────────────
@@ -2021,17 +2058,23 @@ cmd_foundation_locate() {
 
 # ─────────────────────────── foundation-unpack ─────────────────────────────
 # Run the OS-selected unpacker for the foundation (or reference) pack.
+#
+# --out is the LANE'S SOURCE PATH, so every file a pack carries lands inside the subtree
+# its lane owns. --test-path is the lane's other subtree: a pack that carries its own test
+# project puts it under the source path like everything else, and aw-foundation.py lifts it
+# onto the path the lane actually keeps tests in. See that module for when it is a no-op.
 cmd_foundation_unpack() {
-    local name="" app="" out="." dry=false force="no" reference=false
+    local name="" app="" out="." dry=false force="no" reference=false test_path=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --name) name="$2"; shift 2 ;;
             --app) app="$2"; shift 2 ;;
             --out) out="$2"; shift 2 ;;
+            --test-path) test_path="$2"; shift 2 ;;
             --dry-run) dry=true; shift ;;
             --force) force="$2"; shift 2 ;;
             --reference) reference=true; shift ;;
-            --help|-h) echo "foundation-unpack --name <F> --app <A> --out <d> [--dry-run] [--force <yes|no>] [--reference]"; return 0 ;;
+            --help|-h) echo "foundation-unpack --name <F> --app <A> --out <d> [--test-path <d>] [--dry-run] [--force <yes|no>] [--reference]"; return 0 ;;
             *) echo "foundation-unpack: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -2067,9 +2110,29 @@ cmd_foundation_unpack() {
     [ -n "$written" ] || written=0
     local has_coll=false
     if [ "$dry" = true ] && [ $rc -ne 0 ]; then has_coll=true; fi
-    printf '{"ok":%s,"mode":"%s","written":%s,"has_collisions":%s,"stdout":"%s"}\n' \
+
+    # Put the pack's test tree on the lane's test path. Only after a REAL unpack that
+    # worked: a dry run has written nothing to lift, and a failed one leaves a tree
+    # nobody should be rearranging.
+    local tests_moved=0 tests_msg="" redirect=""
+    if [ "$dry" != true ] && [ $rc -eq 0 ] && [ -n "$test_path" ]; then
+        local aw_fnd="$SCRIPT_DIR/../python/aw-foundation.py"
+        if [ -f "$aw_fnd" ] && command -v python3 >/dev/null 2>&1; then
+            local -a rargs=(--repo "$repo_root" redirect-tests --out "$out" --test-path "$test_path")
+            { [ "$force" = "yes" ] || [ "$reference" = true ]; } && rargs+=(--force)
+            redirect=$(python3 "$aw_fnd" "${rargs[@]}" 2>/dev/null | tail -1)
+            if [ -n "$redirect" ]; then
+                tests_moved=$(printf '%s' "$redirect" | python3 -c 'import json,sys; print(json.loads(sys.stdin.readline()).get("moved",0))' 2>/dev/null || echo 0)
+                tests_msg=$(printf '%s' "$redirect" | python3 -c 'import json,sys; print(json.loads(sys.stdin.readline()).get("message",""))' 2>/dev/null || echo "")
+            fi
+        fi
+    fi
+    [ -n "$tests_moved" ] || tests_moved=0
+
+    printf '{"ok":%s,"mode":"%s","written":%s,"has_collisions":%s,"tests_moved":%s,"tests_message":"%s","stdout":"%s"}\n' \
         "$([ $rc -eq 0 ] && echo true || echo false)" "$([ "$dry" = true ] && echo dry || echo real)" \
-        "$written" "$has_coll" "$(json_escape "$(printf '%s' "$outp" | tail -c 800)")"
+        "$written" "$has_coll" "$tests_moved" "$(json_escape "$tests_msg")" \
+        "$(json_escape "$(printf '%s' "$outp" | tail -c 800)")"
 }
 
 # ─────────────────────── foundation-stash-dbcontext ────────────────────────
@@ -2086,7 +2149,9 @@ cmd_foundation_stash_dbcontext() {
     done
     local repo_root; repo_root=$(get_repo_root)
     [[ "$out" != /* ]] && out="$repo_root/$out"
-    local ctx; ctx=$(find "$out/src" -name "ApplicationDbContext.cs" 2>/dev/null | head -1)
+    # Searched from the unpack root itself, which IS the lane's source path — a `src/`
+    # segment underneath it is the old repo-root layout and is not there any more.
+    local ctx; ctx=$(find "$out" -name "ApplicationDbContext.cs" 2>/dev/null | head -1)
     if [ -z "$ctx" ]; then printf '{"found":false,"dbcontext":"","backup":""}\n'; return 0; fi
     local bak="$ctx.foundation.bak"
     cp "$ctx" "$bak"
@@ -2511,6 +2576,25 @@ print(json.dumps({"ok": ok, "exists": True, "issues": issues,
 PY
 }
 
+# ─────────────────────────────── principles-list ───────────────────────────
+# The ratified NON-NEGOTIABLE principles. A thin wrapper: the scan lives in
+# python/aw-principles.py, which BOTH shells invoke, so the list a gate cites cannot
+# differ between them. Defaults to the two halves specify loads; --file overrides.
+cmd_principles_list() {
+    local rest=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "principles-list [--file <path>]...  -> {files[], missing[], principles[], count, titles_csv}"; return 0 ;;
+            *) rest+=("$1"); shift ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-principles.py"
+    if [ ! -f "$core" ]; then echo "principles-list: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "principles-list: python3 is required" >&2; return 1; fi
+    python3 "$core" list --root "$repo_root" "${rest[@]+"${rest[@]}"}"
+}
+
 # ────────────────────────── agent-context-update ───────────────────────────
 # Run the agent-context extension's updater (refreshes the managed AW-Spec block).
 cmd_agent_context_update() {
@@ -2871,7 +2955,14 @@ cmd_delta_plan_scaffold() {
         if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$target"; else touch "$target"; fi
         created="true"
     fi
-    _stamp_header "$target" "Wave" "$(_wave_of "$fd" "$cr_id" "$repo_root")"
+    # The lane plan carries the change's wave so a reader of the plan alone can see where it
+    # sits. It is COPIED from the delta-spec, never decided here — so when the spec has no
+    # readable wave the template's `[N]` is left standing, which is what the merge and recall
+    # fences read as "not ordered yet" and refuse on, with the command that stamps it.
+    local scaffold_wave; scaffold_wave=$(_wave_of_readable "$fd" "$cr_id" "$repo_root")
+    if [ -n "$scaffold_wave" ]; then
+        _stamp_header "$target" "Wave" "$scaffold_wave"
+    fi
     local override_active="false"
     [ -f "$repo_root/.appweaver/templates/overrides/${template_arg}.md" ] && override_active="true"
     local template_source; template_source=$(resolve_template "$template_arg" "$repo_root") || true
@@ -2944,13 +3035,17 @@ cmd_test_run() {
     #               feature's aggregate name (feature-dir basename) plus any --also
     #               referrer names — the per-feature integrity scope. .NET only; npm/none
     #               ignore it and run the full suite.
+    # --also is REPEATABLE and the lists UNION. A merge's blast radius has two halves that
+    # are computed separately — the referrer closure and the features that co-own the
+    # aggregates the change touches — and the dialect cannot concatenate two variables into
+    # one argument, so the caller passes each list as its own --also.
     local feature_dir="" scope="repo" also=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir="$2"; shift 2 ;;
             --scope)       scope="$2"; shift 2 ;;
-            --also)        also="$2"; shift 2 ;;
-            --help|-h) echo "test-run [--feature-dir <path>] [--scope slice|repo] [--also <csv>]"; return 0 ;;
+            --also)        also="${also:+$also,}$2"; shift 2 ;;
+            --help|-h) echo "test-run [--feature-dir <path>] [--scope slice|repo] [--also <csv>]...  (--also repeatable; lists union)"; return 0 ;;
             *) echo "test-run: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -2973,7 +3068,9 @@ cmd_test_run() {
     fi
 
     local tool="none" ran=false ok=true cmd="" log; log=$(mktemp)
-    local matched=false scoped=false fence_green=false filter="" t2
+    # The runner's exit code, kept because 126/127 is every shell's way of saying the
+    # command itself could not be executed — a missing runner, not a failing suite.
+    local matched=false scoped=false fence_green=false filter="" t2 rc=0
 
     local dotnet_present=false
     if ls "$repo_root"/*.sln >/dev/null 2>&1 || find "$repo_root" -maxdepth 5 -name "*.csproj" 2>/dev/null | grep -q .; then
@@ -3006,6 +3103,16 @@ print(json.dumps({
     "scope": os.environ.get("AW_SCOPE", "repo"), "slices": os.environ.get("AW_SLICES", ""),
     "scoped": False, "matched": bool(re.search(r"Total:\s*[1-9]", log)),
     "fence_green": ok, "cmd": d.get("cmd", ""), "log_tail": log,
+    # The failing lines of EVERY failing lane, budgeted per lane by run-phase — what the
+    # fix loop reads, in place of a tail that may belong to a lane that passed.
+    "failing_excerpt": d.get("failing_excerpt", ""),
+    "failing_lanes": d.get("failing_lanes", []),
+    # NOTHING ran a suite, because no lane has a test command wired up — a different
+    # state from a red suite, and the one a fix loop cannot help with. (No apostrophes
+    # in this block: it is a single-quoted python3 -c program.)
+    "no_setup": bool(d.get("no_setup")),
+    "setup_reason": d.get("setup_reason", ""),
+    "setup_missing": d.get("setup_missing", []),
     "lanes_run": d.get("lanes_run", []), "lanes_skipped": d.get("lanes_skipped", []),
 }))
 '
@@ -3024,16 +3131,16 @@ print(json.dumps({
                 else
                     for t2 in $slices; do filter="${filter:+$filter|}FullyQualifiedName~$t2"; done
                     scoped=true; cmd="dotnet test --nologo --filter \"$filter\""; ran=true
-                    if ( cd "$repo_root" && dotnet test --nologo --filter "$filter" ) >"$log" 2>&1; then ok=true; else ok=false; fi
+                    if ( cd "$repo_root" && dotnet test --nologo --filter "$filter" ) >"$log" 2>&1; then ok=true; else rc=$?; ok=false; fi
                 fi
             else
                 cmd="dotnet test --nologo"; ran=true
-                if ( cd "$repo_root" && dotnet test --nologo ) >"$log" 2>&1; then ok=true; else ok=false; fi
+                if ( cd "$repo_root" && dotnet test --nologo ) >"$log" 2>&1; then ok=true; else rc=$?; ok=false; fi
             fi
         else ok=false; fi
     elif [ -f "$repo_root/package.json" ] && command -v npm >/dev/null 2>&1; then
         tool="npm"; cmd="npm test"; ran=true
-        if ( cd "$repo_root" && npm test ) >"$log" 2>&1; then ok=true; else ok=false; fi
+        if ( cd "$repo_root" && npm test ) >"$log" 2>&1; then ok=true; else rc=$?; ok=false; fi
     else
         tool="none"; ran=false; ok=true
     fi
@@ -3053,10 +3160,30 @@ print(json.dumps({
         fence_green=$ok
     fi
 
-    local t; t=$(tail -c 1400 "$log" 2>/dev/null || true); rm -f "$log"
-    printf '{"ok":%s,"tool":"%s","ran":%s,"scope":"%s","slices":"%s","scoped":%s,"matched":%s,"fence_green":%s,"cmd":"%s","log_tail":"%s"}\n' \
+    local t; t=$(tail -c 1400 "$log" 2>/dev/null || true)
+    # The lines that NAME the failure, which a positional tail does not reliably contain:
+    # a .NET run opens with its restore banner and a runner closes with a summary, so the
+    # last 1400 characters can be entirely green while the failure sits above them.
+    local excerpt="" label no_setup=false setup_reason="" helper_out=""
+    label=$(printf '%s' "$tool${cmd:+ · $cmd}" | tr '\n' ' ' | cut -c1-80)
+    if [ "$fence_green" != true ]; then
+        helper_out=$(python3 "$SCRIPT_DIR/../python/aw-testlog.py" --file "$log" \
+                         --label "$label" --exit "$rc" 2>/dev/null || true)
+        excerpt=$(printf '%s' "$helper_out" | python3 -c 'import json,sys
+try: sys.stdout.write(json.load(sys.stdin).get("excerpt", ""))
+except Exception: pass' 2>/dev/null || true)
+        # "The command never ran" — no test script, no runner, no test project. Not a red
+        # suite, and the callers gate on it rather than sending a fix loop after nothing.
+        setup_reason=$(printf '%s' "$helper_out" | python3 -c 'import json,sys
+try: sys.stdout.write(json.load(sys.stdin).get("reason", ""))
+except Exception: pass' 2>/dev/null || true)
+        [ -n "$setup_reason" ] && no_setup=true
+    fi
+    rm -f "$log"
+    printf '{"ok":%s,"tool":"%s","ran":%s,"scope":"%s","slices":"%s","scoped":%s,"matched":%s,"fence_green":%s,"cmd":"%s","log_tail":"%s","failing_excerpt":"%s","failing_lanes":[],"no_setup":%s,"setup_reason":"%s","setup_missing":[]}\n' \
         "$ok" "$(json_escape "$tool")" "$ran" "$(json_escape "$scope")" "$(json_escape "$slices")" \
-        "$scoped" "$matched" "$fence_green" "$(json_escape "$cmd")" "$(json_escape "$t")"
+        "$scoped" "$matched" "$fence_green" "$(json_escape "$cmd")" "$(json_escape "$t")" \
+        "$(json_escape "$excerpt")" "$no_setup" "$(json_escape "$setup_reason")"
 }
 
 cmd_run_migrate() {
@@ -3312,6 +3439,356 @@ cmd_cr_wave() {
         "$(json_escape "$dspec")" "$(json_escape "$dmodel")"
 }
 
+# ──────────────────────────── cr-wave-derive ───────────────────────────────
+# THE WAVE A CHANGE'S OWN DOCUMENTS IMPLY, from their `## Depends on` sections.
+#
+# cr-setup stamps a new change at the highest wave already open, which is right for a
+# change that stands alone and wrong for one that builds on another: a chained delta lands
+# at its predecessor's wave, where the blocker fence reads the two as independent and lets
+# them merge in either order. The delta documents already say otherwise — an author writes
+# the predecessor under `## Depends on`, with a reason — and nothing acted on it.
+#
+# This makes that declaration the ordering authority: required wave = the highest wave
+# among the changes named there, plus one; 1 when it names none. `specify` stamps it once
+# the model delta is authored, and the merge fence checks it, so the number and the prose
+# cannot drift apart. A change sitting HIGHER than required is fine and left alone — that
+# is deliberate slack, not a contradiction.
+cmd_cr_wave_derive() {
+    local cr_id="" feature_dir_arg="" stamp=false
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --stamp) stamp=true; shift ;;
+            --help|-h) echo "cr-wave-derive --cr-id <id> [--feature-dir <path>] [--stamp]  -> {wave, required_wave, ok, depends_on[], unknown[], stamped, message}"; return 0 ;;
+            *) echo "cr-wave-derive: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "cr-wave-derive: --cr-id is required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd="$feature_dir_arg"
+    [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
+    [ -n "$fd" ] || { echo "cr-wave-derive: no feature set and no --feature-dir" >&2; return 1; }
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
+    AW_CR="$cr_id" AW_FD="$fd" AW_CTX="$ctx_dir" AW_STAMP="$stamp" python3 - <<'PY'
+import glob, json, os, re
+
+cr = os.environ["AW_CR"]
+fd = os.environ["AW_FD"]
+ctx = os.environ["AW_CTX"]
+stamp = os.environ.get("AW_STAMP", "") == "true"
+
+CR_RX = re.compile(r"CR-\d{8}-\d{6}-[0-9A-Za-z]+")
+WAVE_RX = re.compile(r"^\*\*Wave\*\*:\s*(\d+)", re.M)
+
+
+def read(path):
+    try:
+        return open(path, encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def wave_of(cr_id):
+    """A change states its wave in the header of its own delta documents."""
+    for p in (os.path.join(ctx, "domain-model.%s.delta.md" % cr_id),
+              os.path.join(fd, "changes", cr_id, "delta-spec.md")):
+        m = WAVE_RX.search(read(p))
+        if m:
+            return int(m.group(1))
+    for p in glob.glob(os.path.join(glob.escape(os.path.join(fd, "changes", cr_id)), "delta-*.md")):
+        m = WAVE_RX.search(read(p))
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def depends_ids(text):
+    """The CR ids named under `## Depends on`, up to the next heading of that level."""
+    m = re.search(r"^##\s+Depends on\s*$(.*?)(?=^##\s|\Z)", text, re.M | re.S)
+    if not m:
+        return []
+    body = re.sub(r"<!--.*?-->", " ", m.group(1), flags=re.S)
+    return [i for i in CR_RX.findall(body) if i != cr]
+
+
+change_dir = os.path.join(fd, "changes", cr)
+docs = [os.path.join(ctx, "domain-model.%s.delta.md" % cr),
+        os.path.join(change_dir, "delta-spec.md")]
+docs += sorted(glob.glob(os.path.join(glob.escape(change_dir), "delta-*plan*.md")))
+present = [p for p in docs if os.path.isfile(p)]
+
+deps, seen = [], set()
+for p in present:
+    for i in depends_ids(read(p)):
+        if i not in seen:
+            seen.add(i)
+            deps.append(i)
+
+known, unknown = [], []
+for d in deps:
+    w = wave_of(d)
+    (known if w is not None else unknown).append({"cr_id": d, "wave": w})
+required = max([d["wave"] for d in known], default=0) + 1
+current = wave_of(cr)
+ok = current is not None and current >= required
+
+# A change with NO readable wave is stamped too, not only one sitting too low. The merge
+# and recall fences refuse on an unordered change and send the operator here, so the one
+# command they are given has to be able to write the first wave as well as correct a wrong
+# one — a remedy that declines the case it was named for is no remedy.
+stamped = []
+if stamp and (current is None or current < required):
+    line = "**Wave**: %d" % required
+    pat = re.compile(r"^\*\*Wave\*\*:.*$", re.M)
+    for p in present:
+        text = read(p)
+        if pat.search(text):
+            open(p, "w", encoding="utf-8").write(pat.sub(lambda _m: line, text, count=1))
+            stamped.append(os.path.basename(p))
+    if stamped:
+        current, ok = required, True
+
+if stamped and deps:
+    msg = "%s depends on %s, so it was raised to wave %d in %s" % (
+        cr, ", ".join("%s (wave %s)" % (d["cr_id"], d["wave"]) for d in known),
+        required, ", ".join(stamped))
+elif stamped:
+    msg = "%s declares no predecessor, so it was stamped at wave %d — the floor — in %s" % (
+        cr, required, ", ".join(stamped))
+elif not deps:
+    msg = "%s declares no predecessor, so wave %d is the floor; it carries %s" % (
+        cr, required, current if current is not None else "no wave")
+elif ok:
+    msg = "%s is at wave %s, at or above the %d its `## Depends on` requires" % (
+        cr, current, required)
+else:
+    msg = ("%s is at wave %s but depends on %s, so it must sit at wave %d — a predecessor "
+           "at the same or a higher wave is not ordered behind it at all" % (
+               cr, current, ", ".join("%s (wave %s)" % (d["cr_id"], d["wave"]) for d in known),
+               required))
+if unknown:
+    msg += ". Named but not found open: %s" % ", ".join(u["cr_id"] for u in unknown)
+
+print(json.dumps({
+    "cr_id": cr, "wave": current, "required_wave": required, "ok": ok,
+    "depends_on": known, "unknown": unknown, "depends_count": len(deps),
+    "stamped": stamped, "documents": [os.path.basename(p) for p in present],
+    "message": msg,
+}))
+PY
+}
+
+# ────────────────────────────── cr-rebase ──────────────────────────────────
+# RE-STAMP a change's base versions onto the masters it is being merged into — but only
+# when nothing that landed in between touched what this delta touches.
+#
+# `**Base version**` is written once, by cr-setup, and the merge fence refuses when it no
+# longer matches the master. Nothing could ever update it: every other site reads it, and
+# every authoring prompt forbids the model from writing it, so the only documented way out
+# of that refusal was hand-editing the delta-spec in the middle of an automated loop.
+#
+# WHAT "APPLIES CLEANLY" MEANS HERE, because a stamp that is not earned is worse than a
+# refusal: the masters moved, and every change that landed since this delta was stamped
+# touched OTHER aggregates than the ones this delta names. Then the delta still describes
+# the document it was written against, and the stamp is bookkeeping. A landed change
+# sharing an aggregate — or one whose own model delta cannot be read — leaves it refused,
+# and a human rebases. `**Base context version**` is compared and re-stamped the same way,
+# which is the first time anything reads it.
+cmd_cr_rebase() {
+    local cr_id="" feature_dir_arg="" stamp=false
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --stamp) stamp=true; shift ;;
+            --help|-h) echo "cr-rebase --cr-id <id> [--feature-dir <path>] [--stamp]  -> {ok, clean, moved, context_moved, base_version, current_version, landed_since[], conflicts[], stamped[], message}"; return 0 ;;
+            *) echo "cr-rebase: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "cr-rebase: --cr-id is required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "cr-rebase: no feature set and no --feature-dir" >&2; return 1; }
+    local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
+    AW_CR="$cr_id" AW_FD="$fd" AW_CTX="$ctx_dir" AW_STAMP="$stamp" python3 - <<'PY'
+import glob, json, os, re
+
+cr = os.environ["AW_CR"]
+fd = os.environ["AW_FD"]
+ctx = os.environ["AW_CTX"]
+stamp = os.environ.get("AW_STAMP", "") == "true"
+
+CR_RX = re.compile(r"CR-\d{8}-\d{6}-[0-9A-Za-z]+")
+TICK_RX = re.compile(r"`([^`]+)`")
+
+
+def read(path):
+    try:
+        return open(path, encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def header(text, name):
+    m = re.search(r"^\*\*%s\*\*:[ \t]*(.+?)[ \t]*(?:<!--.*)?$" % re.escape(name), text, re.M)
+    if not m:
+        return ""
+    v = m.group(1).strip()
+    return "" if (v.startswith("[") and v.endswith("]")) else v
+
+
+def norm(v):
+    v = (v or "").strip()
+    return "" if not v else (v if v.startswith("v") else "v" + v)
+
+
+def as_tuple(v):
+    parts = re.findall(r"\d+", v or "")
+    return tuple(int(p) for p in parts) if parts else None
+
+
+def aggregates(text):
+    """The `**Aggregates touched**:` header — the list finalize-delta opens sections for."""
+    m = re.search(r"^[ \t]*(?:[-*][ \t]+)?\*\*Aggregates touched(?:\*\*:|:\*\*)[ \t]*(.*)$", text, re.M)
+    if not m:
+        return set()
+    value = re.sub(r"<!--.*?(?:-->|$)", "", m.group(1)).strip()
+    names = TICK_RX.findall(value)
+    if not names:
+        names = [p.strip() for p in re.split(r"[,;/&]|\band\b", value) if p.strip()]
+        names = [re.match(r"[A-Za-z_][A-Za-z0-9_]*", n).group(0)
+                 for n in names if re.match(r"[A-Za-z_][A-Za-z0-9_]*", n)]
+    return {n for n in names if not n.startswith(("<", "[")) and not re.match(r"(?i)none\b", n)}
+
+
+def landed_since(text, base):
+    """CR ids in Change History rows whose version is ABOVE `base` — what moved the master
+    since this delta was stamped. A row with no readable version counts, because a row this
+    cannot place is one it cannot prove is older."""
+    ids, base_t = [], as_tuple(base)
+    for line in text.split("\n"):
+        if not line.strip().startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 2 or set("".join(cells)) <= set("-: "):
+            continue
+        row_t = as_tuple(cells[0]) if re.match(r"^v?\d", cells[0]) else None
+        if row_t is None:
+            continue
+        if base_t is not None and row_t <= base_t:
+            continue
+        for i in CR_RX.findall(line):
+            if i != cr and i not in ids:
+                ids.append(i)
+    return ids
+
+
+def model_delta_of(cr_id):
+    """A change's model half: beside the master while open, in its archive once closed."""
+    p = os.path.join(ctx, "domain-model.%s.delta.md" % cr_id)
+    if os.path.isfile(p):
+        return read(p)
+    for feat in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
+        a = os.path.join(ctx, feat, "changes", "archive", cr_id, "domain-model.delta.md")
+        if os.path.isfile(a):
+            return read(a)
+    return ""
+
+
+my_spec = os.path.join(fd, "changes", cr, "delta-spec.md")
+my_model = os.path.join(ctx, "domain-model.%s.delta.md" % cr)
+spec_master = os.path.join(fd, "spec.md")
+model_master = os.path.join(ctx, "domain-model.md")
+
+spec_text, model_text = read(my_spec), read(my_model)
+base_version = norm(header(spec_text, "Base version"))
+base_ctx = norm(header(model_text, "Base context version"))
+
+current = ""
+try:
+    current = norm(json.load(open(os.path.join(fd, "active_version.json"), encoding="utf-8")).get("version", ""))
+except Exception:
+    current = ""
+if not current:
+    current = norm(header(read(spec_master), "Version"))
+current_ctx = norm(header(read(model_master), "Version"))
+
+moved = bool(base_version and current and base_version != current)
+ctx_moved = bool(base_ctx and current_ctx and base_ctx != current_ctx)
+
+# WHAT LANDED IN BETWEEN, and whether any of it touched what this delta touches. A delta
+# whose aggregates nobody else moved still applies to the master it was written against;
+# one whose aggregates a landed change rewrote does not, and no stamp can make it.
+mine = aggregates(model_text)
+intervening = landed_since(read(spec_master), base_version) if moved else []
+if ctx_moved:
+    for i in landed_since(read(model_master), base_ctx):
+        if i not in intervening:
+            intervening.append(i)
+
+rows, conflicts = [], []
+for i in intervening:
+    theirs = aggregates(model_delta_of(i))
+    shared = sorted(mine & theirs) if (mine and theirs) else []
+    # Unknown aggregates fail CLOSED: a change this cannot read is one it cannot clear.
+    unknown = not theirs
+    rows.append({"cr_id": i, "aggregates": sorted(theirs), "shared": shared, "unknown": unknown})
+    if shared or unknown:
+        conflicts.append({"cr_id": i, "shared": shared, "unknown": unknown})
+
+clean = (moved or ctx_moved) and not conflicts
+stamped = []
+if stamp and clean:
+    if moved and os.path.isfile(my_spec):
+        open(my_spec, "w", encoding="utf-8").write(
+            re.sub(r"^\*\*Base version\*\*:.*$", "**Base version**: %s" % current,
+                   spec_text, count=1, flags=re.M))
+        stamped.append({"file": os.path.basename(my_spec), "header": "Base version",
+                        "from": base_version, "to": current})
+    if ctx_moved and os.path.isfile(my_model):
+        open(my_model, "w", encoding="utf-8").write(
+            re.sub(r"^\*\*Base context version\*\*:.*$", "**Base context version**: %s" % current_ctx,
+                   model_text, count=1, flags=re.M))
+        stamped.append({"file": os.path.basename(my_model), "header": "Base context version",
+                        "from": base_ctx, "to": current_ctx})
+    if stamped:
+        moved = ctx_moved = False
+
+ok = not (moved or ctx_moved)
+if not (base_version or base_ctx):
+    msg = "%s carries no base stamp, so there is nothing to compare — treated as not moved" % cr
+elif ok and not stamped:
+    msg = "%s is stamped against the current masters (%s, context %s)" % (cr, current or "—", current_ctx or "—")
+elif stamped:
+    msg = "%s was re-stamped: %s. Nothing that landed in between (%s) touched its aggregates (%s)" % (
+        cr, "; ".join("%s %s → %s" % (s["header"], s["from"], s["to"]) for s in stamped),
+        ", ".join(r["cr_id"] for r in rows) or "no recorded change", ", ".join(sorted(mine)) or "none named")
+else:
+    parts = []
+    for c in conflicts:
+        parts.append("%s (%s)" % (c["cr_id"], "aggregates unreadable" if c["unknown"]
+                                  else "also touched " + ", ".join(c["shared"])))
+    msg = ("%s was authored against %s%s but the masters are at %s%s, and what landed in "
+           "between overlaps it: %s" % (
+               cr, base_version or "—", "" if not base_ctx else " (context %s)" % base_ctx,
+               current or "—", "" if not current_ctx else " (context %s)" % current_ctx,
+               "; ".join(parts)))
+
+print(json.dumps({
+    "cr_id": cr, "ok": ok, "clean": clean, "moved": moved, "context_moved": ctx_moved,
+    "base_version": base_version, "current_version": current,
+    "base_context_version": base_ctx, "current_context_version": current_ctx,
+    "aggregates": sorted(mine), "landed_since": rows,
+    "conflicts": conflicts, "conflict_count": len(conflicts),
+    "conflict_ids": ", ".join(c["cr_id"] for c in conflicts),
+    "stamped": stamped, "message": msg,
+}))
+PY
+}
+
 # ─────────────────────────────── cr-list ───────────────────────────────────
 # The changes currently OPEN on a feature, in wave order. This is what lets a delta
 # stage ASK which change it is working on instead of inferring one: many may be open at
@@ -3555,11 +4032,12 @@ PY
 
 # ─────────────────────────────── cr-overlap ────────────────────────────────
 # Which OTHER open changes touch the same aggregates as this one — read off the
-# `## Aggregate: <Name>` headers of the pending model deltas, which is the merge unit
-# domain-model.md is organised by.
+# `**Aggregates touched**:` header of each pending model delta. That header names the
+# `## Aggregate: <Name>` sections of domain-model.md the delta merges into; the delta
+# itself carries no such headings, the master does.
 #
 # DETERMINISTIC ON PURPOSE. Two deltas collide when they change the same aggregate, and
-# that is a fact about two files' headings — a regex answers it exactly, at no cost, and
+# that is a fact about two files' headers — a regex answers it exactly, at no cost, and
 # the same way every run. Handing the question to a model instead would make the one
 # check that can be exact the one check that can hallucinate.
 #
@@ -3602,14 +4080,27 @@ def read(p):
 def wave_of(text, default=1):
     m = re.search(r"^\*\*Wave\*\*:\s*(\d+)", text, re.M)
     return int(m.group(1)) if m else default
-# The merge unit. A placeholder heading left by the template names no aggregate, so an
-# unfilled model delta reports none rather than colliding with every other change on
-# "<Name>".
+# The aggregates a model delta declares, from its `**Aggregates touched**:` header — the
+# same list finalize-delta opens master sections for. Backticked names are the template's
+# form and win when present, so prose around them ("`Appointment` (lifecycle), `Patient`
+# (read)") adds nothing; a value with no backticks is split on , ; / & "and" and each
+# piece's leading name is taken. The template placeholder (`[Root]`) and "None — behaviour
+# only" name no aggregate, so an unfilled or model-free delta reports none rather than
+# colliding with every other change.
 def aggregates_of(text):
+    m = re.search(r"^[ \t]*(?:[-*][ \t]+)?\*\*Aggregates touched(?:\*\*:|:\*\*)[ \t]*(.*)$", text, re.M)
+    if not m:
+        return []
+    value = re.sub(r"<!--.*?(?:-->|$)", "", m.group(1)).strip()
+    names = re.findall(r"`([^`]+)`", value)
+    if not names:
+        names = [p.group(0) for p in
+                 (re.match(r"[A-Za-z][A-Za-z0-9_]*", piece.strip())
+                  for piece in re.split(r"[,;/&]|\band\b", value)) if p]
     out = []
-    for m in re.finditer(r"^##\s*Aggregate:\s*(.+?)\s*$", text, re.M):
-        name = m.group(1).strip().strip("`")
-        if not name or name.startswith("<") or name.startswith("["):
+    for name in names:
+        name = name.strip()
+        if not name or name[0] in "<[" or re.match(r"none\b", name, re.I):
             continue
         if name not in out:
             out.append(name)
@@ -3992,7 +4483,7 @@ cmd_cr_merge_check() {
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-merge-check --cr-id <id> [--feature-dir <path>]  -> {rebase_needed, base_version, current_version, blockers[], blocker_count, wave, …}"; return 0 ;;
+            --help|-h) echo "cr-merge-check --cr-id <id> [--feature-dir <path>]  -> {rebase_needed, base_version, current_version, blockers[], blocker_count, wave, wave_ordering_ok, unordered[], …}"; return 0 ;;
             *) echo "cr-merge-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4020,14 +4511,8 @@ def norm(v):
     if not v: return ""
     return v if v.startswith("v") else "v" + v
 
-# THIS change's own spec half and wave.
+# THIS change's own spec half.
 my_spec = os.path.join(fd, "changes", cr, "delta-spec.md")
-def wave_of(p, default=1):
-    try: t = open(p, encoding="utf-8").read()
-    except Exception: return default
-    m = re.search(r"^\*\*Wave\*\*:[ \t]*(\d+)", t, re.M)
-    return int(m.group(1)) if m else default
-wave = wave_of(my_spec)
 base_version = norm(header(my_spec, "Base version"))
 
 # The master's CURRENT version, from the ledger — the same authority version-read reports,
@@ -4044,41 +4529,65 @@ if not current:
 # absence of evidence and is not treated as a move.
 rebase_needed = bool(base_version and current and base_version != current)
 
-# EVERY open change in the context, both halves. changes/<id>/ under each feature is the
-# authority for "open"; the pending model deltas are unioned in so a model-only artifact of
-# a half-built change is still seen.
-opens = {}
-for feat in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
-    ch = os.path.join(ctx, feat, "changes")
-    if not os.path.isdir(ch): continue
-    for name in sorted(os.listdir(ch)):
-        d = os.path.join(ch, name)
-        if name == "archive" or not os.path.isdir(d): continue
-        opens.setdefault(name, {"cr_id": name, "wave": wave_of(os.path.join(d, "delta-spec.md")),
-                                "feature": feat})
-for f in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
-    m = re.match(r"^domain-model\.(.+)\.delta\.md$", f)
-    if not m: continue
-    other = m.group(1)
-    opens.setdefault(other, {"cr_id": other, "wave": wave_of(os.path.join(ctx, f)), "feature": ""})
-
-blockers = [v for k, v in sorted(opens.items()) if k != cr and v["wave"] < wave]
-
-# THE MASTERS CAN MOVE WITHOUT THE VERSION MOVING. finalize-delta merges and close-delta
-# bumps, so between the two spec.md carries a change the number does not yet reflect — and a
-# second delta sharing the same base_version would compare equal and merge onto masters that
-# had already shifted under it. An id appearing in spec.md is the on-disk proof that the
-# merge ran (it is the Change History row finalize-delta appends), which is the same
-# evidence cr-recall-check reads for the same question.
-spec_text = ""
+# BOTH CONTEXT-WIDE QUESTIONS COME FROM aw-crstate, for every reader of them and for both
+# shells: which open changes this one is ordered against, and which of them have already
+# merged. Each was once a copy of the scan living in this payload and another in its
+# PowerShell twin, which is how the two came to answer the same question differently.
+#
+# PREDECESSORS. Every open change in the context, both halves — changes/<id>/ under each
+# feature is the authority for "open", and the pending model deltas are unioned in so a
+# model-only artifact of a half-built change is still seen. A change whose `**Wave**:` is
+# unreadable is reported as unordered rather than assumed to be wave 1, which is what let an
+# unstamped delta pose as a predecessor and let an unstamped SUBJECT skip this fence
+# entirely.
+#
+# MERGED-OPEN. The masters can move without the version moving: finalize-delta merges and
+# close-delta bumps, so between the two the masters carry a change the number does not yet
+# reflect, and a second delta sharing the same base_version would compare equal and merge
+# onto masters that had already shifted under it. The proof is the Change History row
+# finalize-delta appends, carrying the id in its CR cell — which replaced `cr in spec.md`,
+# a test that fired on an id quoted in prose and matched a prefix of a longer id. It looks
+# where a merge can actually show: this feature's spec AND the context model every feature
+# shares, so a SIBLING feature's merged-unclosed change is no longer invisible. A sibling
+# blocks only where it touched an aggregate this delta also names (`blocking`); a merge in
+# this feature blocks outright, because it moved this delta's own master.
+_m, _why = None, ""
 try:
-    spec_text = open(os.path.join(fd, "spec.md"), encoding="utf-8").read()
-except Exception:
-    pass
-merged_open = [v for k, v in sorted(opens.items()) if k != cr and k in spec_text]
+    import importlib.util
+    _mod_path = os.path.join(root, ".appweaver", "scripts", "python", "aw-crstate.py")
+    _spec = importlib.util.spec_from_file_location("aw_crstate", _mod_path)
+    _loaded = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_loaded)
+    _m = _loaded
+except Exception as _e:
+    _why = str(_e)
+
+order, merged_open, merged_text = None, None, ""
+if _m is not None:
+    try:
+        order = _m.wave_order(ctx, fd, cr, "lower", "context")
+        merged_open = [r for r in _m.merged_open(ctx, fd, cr) if r["blocking"]]
+        merged_text = _m.merged_open_text(merged_open)
+    except Exception as _e:
+        order, merged_open, _why = None, None, str(_e)
+
+# Fail CLOSED on an unreadable helper: report the state as blocking rather than clear, and
+# say which check could not run rather than which condition was found.
+if order is None:
+    order = {"wave": None, "wave_known": False, "related": [], "related_count": 0,
+             "related_ids": "", "unknown": [], "unknown_count": 0, "unknown_ids": "",
+             "unknown_blocks": True, "wave_ordering_ok": False,
+             "wave_problem": "the wave reader could not be run (%s), so no open change in "
+                             "this context is ordered against %s at all" % (_why, cr)}
+if merged_open is None:
+    merged_open = [{"cr_id": "(merged-open check failed: %s)" % _why, "blocking": True}]
+    merged_text = merged_open[0]["cr_id"]
+blockers = order["related"]
 
 print(json.dumps({
-    "ok": True, "cr_id": cr, "wave": wave,
+    "ok": True, "cr_id": cr,
+    "wave": order["wave"] if order["wave"] is not None else "",
+    "wave_known": order["wave_known"],
     "exists": os.path.isdir(os.path.join(fd, "changes", cr)),
     # REBASE half — the masters moved because a change CLOSED and bumped the number.
     "base_version": base_version, "current_version": current,
@@ -4087,14 +4596,20 @@ print(json.dumps({
     # PREDECESSOR half. Lower wave = committed to land first.
     "blockers": blockers, "blocker_count": len(blockers),
     "has_blockers": len(blockers) > 0,
-    "blocker_ids": ", ".join("%s (wave %d)" % (b["cr_id"], b["wave"]) for b in blockers),
+    "blocker_ids": order["related_ids"],
+    # The changes this one cannot be ordered against at all, in either direction.
+    "unordered": order["unknown"], "unordered_count": order["unknown_count"],
+    "unordered_ids": order["unknown_ids"],
+    "wave_ordering_ok": order["wave_ordering_ok"],
+    "wave_problem": order["wave_problem"],
     # The other way the masters move: a change MERGED and has not closed yet.
     "merged_open": merged_open, "merged_open_count": len(merged_open),
     "has_merged_open": len(merged_open) > 0,
-    "merged_open_ids": ", ".join(m["cr_id"] for m in merged_open),
-    # All three refusals as ONE positive flag, because the engine takes no compound condition
-    # and a gate that must read three booleans would need three passes over one question.
-    "merge_ok": (not rebase_needed) and len(blockers) == 0 and len(merged_open) == 0,
+    "merged_open_ids": merged_text,
+    # All four refusals as ONE positive flag, because the engine takes no compound condition
+    # and a gate that must read four booleans would need four passes over one question.
+    "merge_ok": (not rebase_needed) and order["wave_ordering_ok"] and len(blockers) == 0
+                and len(merged_open) == 0,
 }))
 PY
 }
@@ -4119,7 +4634,7 @@ cmd_cr_recall_check() {
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-recall-check --cr-id <id> [--feature-dir <path>]  -> {merged, dependants[], dependant_count, wave, …}"; return 0 ;;
+            --help|-h) echo "cr-recall-check --cr-id <id> [--feature-dir <path>]  -> {merged, dependants[], dependant_count, wave, wave_ordering_ok, unordered[], …}"; return 0 ;;
             *) echo "cr-recall-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4127,47 +4642,62 @@ cmd_cr_recall_check() {
     [ -n "$cr_id" ] || { echo "cr-recall-check: --cr-id required" >&2; return 1; }
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "cr-recall-check: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_CR="$cr_id" python3 - <<'PY'
+    local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
+    AW_FD="$fd" AW_CR="$cr_id" AW_ROOT="$repo_root" AW_CTX="$ctx_dir" python3 - <<'PY'
 import json, os, re
 fd = os.environ["AW_FD"]; cr = os.environ["AW_CR"]
+root = os.environ.get("AW_ROOT", ""); ctx = os.environ.get("AW_CTX", "")
 changes = os.path.join(fd, "changes")
 cr_dir = os.path.join(changes, cr)
 
-def wave_of(d):
-    for name in ("delta-spec.md",):
-        p = os.path.join(d, name)
-        if os.path.isfile(p):
-            m = re.search(r'^\*\*Wave\*\*:[ \t]*(\d+)', open(p, encoding="utf-8").read(), re.M)
-            if m:
-                return int(m.group(1))
-    return 1
-
+# MERGED = a Change History row whose CR cell IS this change, in this feature's spec or in
+# the context model every feature shares — aw-crstate owns that test for all three readers
+# of it. The old test was `cr in line`, which fired on an id quoted in prose and matched a
+# prefix of a longer id.
 spec = os.path.join(fd, "spec.md")
-merged, evidence = False, ""
-if os.path.isfile(spec):
-    for line in open(spec, encoding="utf-8").read().splitlines():
-        if cr in line:
-            merged, evidence = True, line.strip()
-            break
-
-wave = wave_of(cr_dir) if os.path.isdir(cr_dir) else 1
-dependants = []
-if os.path.isdir(changes):
-    for name in sorted(os.listdir(changes)):
-        d = os.path.join(changes, name)
-        if name == cr or name == "archive" or not os.path.isdir(d):
-            continue
-        w = wave_of(d)
-        if w > wave:
-            dependants.append({"cr_id": name, "wave": w})
+merged, evidence, merged_doc = False, "", ""
+order, _why = None, ""
+try:
+    import importlib.util
+    _mod_path = os.path.join(root, ".appweaver", "scripts", "python", "aw-crstate.py")
+    _spec = importlib.util.spec_from_file_location("aw_crstate", _mod_path)
+    _m = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_m)
+    evidence, merged_doc = _m.merged_in([spec, os.path.join(ctx, "domain-model.md")], cr)
+    merged = bool(evidence)
+    # DEPENDANTS, from the same reader the merge fence uses in the opposite direction. An
+    # unreadable `**Wave**:` is not wave 1 here either: it used to mean `w > wave` was false
+    # and the change was not counted, so recall withdrew the ground from under a dependant
+    # it could not see. Waves have no ceiling, so any unordered change could sit above this
+    # one and every one of them holds recall.
+    order = _m.wave_order(ctx, fd, cr, "higher", "feature")
+except Exception as _e:
+    # Fail CLOSED: an unreadable helper must not report "never merged", which is the
+    # answer that lets close-delta archive a change nobody merged.
+    merged, evidence, _why = True, "(merged check unavailable — treated as merged)", str(_e)
+
+if order is None:
+    order = {"wave": None, "wave_known": False, "related": [], "related_count": 0,
+             "related_ids": "", "unknown": [], "unknown_count": 0, "unknown_ids": "",
+             "unknown_blocks": True, "wave_ordering_ok": False,
+             "wave_problem": "the wave reader could not be run (%s), so no open change in "
+                             "this feature is ordered against %s at all" % (_why, cr)}
+dependants = order["related"]
 
 print(json.dumps({
-    "ok": True, "cr_id": cr, "exists": os.path.isdir(cr_dir), "wave": wave,
+    "ok": True, "cr_id": cr, "exists": os.path.isdir(cr_dir),
+    "wave": order["wave"] if order["wave"] is not None else "",
+    "wave_known": order["wave_known"],
     "merged": merged, "merge_evidence": evidence,
     "dependants": dependants,
-    "dependant_ids": ", ".join("%s (wave %d)" % (x["cr_id"], x["wave"]) for x in dependants),
+    "dependant_ids": order["related_ids"],
     "dependant_count": len(dependants),
     "has_dependants": len(dependants) > 0,
+    # The changes this one cannot be ordered against at all, in either direction.
+    "unordered": order["unknown"], "unordered_count": order["unknown_count"],
+    "unordered_ids": order["unknown_ids"],
+    "wave_ordering_ok": order["wave_ordering_ok"],
+    "wave_problem": order["wave_problem"],
 }))
 PY
 }
@@ -4175,6 +4705,12 @@ PY
 # ──────────────────── plan-gate-stamp / plan-gate-check ────────────────────
 # THE RECEIPT THAT analyze-plan PASSED, and over WHICH BYTES.
 #
+# THE RULE ITSELF LIVES IN python/aw-plangate.py, which both shells invoke — these two are
+# thin wrappers that resolve the feature and hand over. It is a set of sha comparisons with
+# three deliberate asymmetries in it, and while it was embedded twice (a heredoc here, a
+# native function there) every change to it had to be re-derived by hand on the other side
+# and kept in step by eye. It changed twice that way. Now there is nothing to keep in step.
+#
 # implement generates from the lane plans and deliberately does NOT read the spec — its
 # own header says "analyze-plan already conformed the plans to it". That sentence was an
 # assumption about the order the operator ran things in, not a fact anything checked: the
@@ -4190,69 +4726,86 @@ PY
 # WHY THE GATE AND NOT THE AUTHOR. Stamping at `plan` would record "this plan was authored
 # from that spec". The question implement depends on is stronger — "were these plans PROVEN
 # against this spec" — and a plan authored from the current spec can still be wrong. So the
-# receipt is written where the proof happens, by analyze-plan, on green, and it hashes every
-# document the gate actually read: the spec, the context's domain model (check 4 reads it)
-# and each lane plan that was present.
+# receipt is written where the proof happens, by analyze-plan, and it hashes every document
+# the gate actually read: the spec, the context's domain model (check 4 reads it) and each
+# lane plan that was present.
+#
+# THE RECEIPT CARRIES THE VERDICT, and every master-mode run writes one. A receipt written
+# only on a clean pass is never written on a feature whose spec misses a domain constraint —
+# a LIFT-FAILURE analyze-plan may not close — and then the staleness check has nothing to
+# compare. The verdict splits the gaps by who can close them (plan-gaps):
+#   conformant   no gaps
+#   routed-gaps  only gaps /appweaver specify must close — implement warns and generates
+#   gaps         at least one gap a plan rewrite closes — implement refuses
 #
 # The absence of a receipt is INFORMATION, not an error: it means this feature has never
 # been through the gate, which every tree that predates this op is true of. It is reported
-# as untracked and blocks nothing. Only a receipt that EXISTS and no longer matches is a
-# refusal, because that tree has been gated once and the bytes have moved since.
+# as untracked and blocks nothing. A receipt that EXISTS refuses when the bytes have moved
+# since, or when its verdict is `gaps`. A receipt written before the verdict existed was
+# written on a clean pass, and reads as `conformant`.
 _plan_gate_file() { printf '%s/.aw-plan-gate.json' "$1"; }
 
+# Which analyze-plan gaps a plan rewrite can close, and which only /appweaver specify can.
+# A gap routes to specify when the analyze pass tagged it `route: specify` (a constraint the
+# spec never lifted, structure domain-model.md does not define, behaviour the spec does not
+# describe), or when its text opens with LIFT-FAILURE whatever the tag says. Anything else —
+# an untagged gap included — is a plan gap. Unreadable input is one plan gap: a verdict that
+# could not be read must not pass.
+cmd_plan_gaps() {
+    local gaps=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --gaps) gaps="$2"; shift 2 ;;
+            --help|-h) echo "plan-gaps --gaps <json list>  -> {verdict, plan_ok, plan_gaps, routed_gaps, routed[], routed_csv}"; return 0 ;;
+            *) echo "plan-gaps: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    AW_GAPS="$gaps" python3 - <<'PY'
+import json, os
+raw = (os.environ.get("AW_GAPS") or "").strip()
+try:
+    gaps = json.loads(raw) if raw else []
+    if not isinstance(gaps, list):
+        raise ValueError("not a list")
+    readable = True
+except Exception:
+    gaps, readable = [], False
+plan, routed = 0, []
+for g in gaps:
+    d = g if isinstance(g, dict) else {"gap": str(g)}
+    text = str(d.get("gap", "")).strip()
+    if text.upper().startswith("LIFT-FAILURE") or str(d.get("route", "")).strip().lower() == "specify":
+        ref = str(d.get("spec_ref", "") or "").strip()
+        routed.append(("%s: %s" % (ref, text)) if ref and ref != "—" else text)
+    else:
+        plan += 1
+if not readable:
+    plan += 1
+verdict = "gaps" if plan else ("routed-gaps" if routed else "conformant")
+print(json.dumps({"ok": True, "readable": readable, "verdict": verdict, "plan_ok": plan == 0,
+                  "plan_gaps": plan, "routed_gaps": len(routed), "routed": routed,
+                  "routed_csv": "; ".join(routed)}))
+PY
+}
+
 cmd_plan_gate_stamp() {
-    local feature_dir_arg="" spec_version="" mode="master"
+    case "${1:-}" in
+        --help|-h) echo "plan-gate-stamp [--feature-dir <path>] [--spec-version <v>] [--mode <text>] [--verdict conformant|routed-gaps|gaps] [--plan-gaps <n>] [--routed <json list>]  -> {file, gated, verdict, hashed[], count}"; return 0 ;;
+    esac
+    local feature_dir_arg="" rest=()
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --spec-version) spec_version="$2"; shift 2 ;;
-            --mode) mode="$2"; shift 2 ;;
-            --help|-h) echo "plan-gate-stamp [--feature-dir <path>] [--spec-version <v>] [--mode <text>]  -> {file, gated, hashed[], count}"; return 0 ;;
-            *) echo "plan-gate-stamp: unknown arg '$1'" >&2; return 1 ;;
+            *) rest+=("$1"); shift ;;
         esac
     done
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "plan-gate-stamp: no feature set and no --feature-dir" >&2; return 1; }
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
-    AW_FD="$fd" AW_CTX="$ctx_dir" AW_ROOT="$repo_root" AW_VER="$spec_version" AW_MODE="$mode" python3 - <<'PY'
-import datetime, hashlib, json, os
-fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
-def sha(p):
-    try:
-        with open(p, "rb") as f: return hashlib.sha256(f.read()).hexdigest()
-    except Exception: return ""
-def rel(p): return os.path.relpath(p, root)
-# Every document the gate READ. A lane that is not declared has no plan on disk and is
-# simply absent from the map — the check treats a name it does not carry as not gated,
-# never as changed, so declaring a second lane later does not read as tampering.
-#
-# THE LEGACY NAMES ARE HERE FOR THE SAME REASON version-stamp CARRIES THEM. feature-paths
-# resolves design.md / design.ui.md under the backend_plan / frontend_plan keys, so a tree
-# that has not been through `plan` since the rename — every brownfield feature `adopt`
-# produces — is GATED on those documents. Hashing only the new names would leave such a
-# feature with an empty plan map: a receipt that looks tracked and fresh while the document
-# implement actually generates from is unwatched.
-plans = {}
-for name in ("backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md"):
-    h = sha(os.path.join(fd, name))
-    if h: plans[name] = h
-rec = {
-    "gated": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-    "gate_mode": os.environ.get("AW_MODE", "master"),
-    "spec_version": os.environ.get("AW_VER", "").strip(),
-    "spec_sha": sha(os.path.join(fd, "spec.md")),
-    "model_sha": sha(os.path.join(ctx, "domain-model.md")),
-    "plans": plans,
-    "note": ("Written by analyze-plan when it PASSED. It records the bytes that were "
-             "proven against each other, not a version — the plans' **Version**: headers "
-             "are stamped in lockstep by close-delta and cannot answer this. implement "
-             "reads it through plan-gate-check."),
-}
-p = os.path.join(fd, ".aw-plan-gate.json")
-open(p, "w", encoding="utf-8").write(json.dumps(rec, indent=2) + "\n")
-print(json.dumps({"file": rel(p), "gated": rec["gated"], "spec_version": rec["spec_version"],
-                  "hashed": sorted(plans.keys()), "count": len(plans), "ok": True}))
-PY
+    local core="$SCRIPT_DIR/../python/aw-plangate.py"
+    if [ ! -f "$core" ]; then echo "plan-gate-stamp: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "plan-gate-stamp: python3 is required" >&2; return 1; fi
+    python3 "$core" stamp --feature-dir "$fd" --context-dir "$ctx_dir" --root "$repo_root" "${rest[@]+"${rest[@]}"}"
 }
 
 cmd_plan_gate_check() {
@@ -4260,56 +4813,53 @@ cmd_plan_gate_check() {
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "plan-gate-check [--feature-dir <path>]  -> {tracked, gate_fresh, spec_moved, model_moved, plans_changed[], plans_changed_csv, gated, reason}"; return 0 ;;
+            --help|-h) echo "plan-gate-check [--feature-dir <path>]  -> {tracked, gate_fresh, verdict, may_generate, plan_gaps, routed_gaps[], routed_csv, spec_moved, model_moved, plans_changed[], plans_changed_csv, gated, reason}"; return 0 ;;
             *) echo "plan-gate-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "plan-gate-check: no feature set and no --feature-dir" >&2; return 1; }
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
-    AW_FD="$fd" AW_CTX="$ctx_dir" AW_ROOT="$repo_root" python3 - <<'PY'
-import hashlib, json, os
-fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
-def sha(p):
-    try:
-        with open(p, "rb") as f: return hashlib.sha256(f.read()).hexdigest()
-    except Exception: return ""
-p = os.path.join(fd, ".aw-plan-gate.json")
-rec = None
-try: rec = json.load(open(p, encoding="utf-8"))
-except Exception: rec = None
-out = {"file": os.path.relpath(p, root), "tracked": bool(rec), "gate_fresh": False,
-       "spec_moved": False, "model_moved": False, "plans_changed": [],
-       "plans_changed_csv": "", "gated": "", "spec_version": "", "reason": "", "ok": True}
-if not rec:
-    # Never gated. Not a failure and not a stale plan — an unknown, and the only honest
-    # thing to report about a tree that has not run analyze-plan since this op existed.
-    out["reason"] = ("no .aw-plan-gate.json — this feature has not passed analyze-plan "
-                     "since the gate began leaving a receipt")
-else:
-    out["gated"] = rec.get("gated", "")
-    out["spec_version"] = rec.get("spec_version", "")
-    out["spec_moved"] = bool(rec.get("spec_sha")) and rec["spec_sha"] != sha(os.path.join(fd, "spec.md"))
-    # A model recorded as absent that is still absent has not moved. A context that
-    # GAINED a domain model since the gate has moved: check 4 never ran against it.
-    out["model_moved"] = rec.get("model_sha", "") != sha(os.path.join(ctx, "domain-model.md"))
-    changed = []
-    for name, was in sorted((rec.get("plans") or {}).items()):
-        if sha(os.path.join(fd, name)) != was:
-            changed.append(name)
-    out["plans_changed"] = changed
-    out["plans_changed_csv"] = ", ".join(changed)
-    out["gate_fresh"] = not (out["spec_moved"] or out["model_moved"] or changed)
-    if out["gate_fresh"]:
-        out["reason"] = "the spec, the model and every gated plan are byte-identical to what analyze-plan passed on %s" % out["gated"]
-    else:
-        bits = []
-        if out["spec_moved"]:  bits.append("spec.md has changed")
-        if out["model_moved"]: bits.append("domain-model.md has changed")
-        if changed:            bits.append("%s changed (a re-derive by `plan main`, or a hand edit)" % ", ".join(changed))
-        out["reason"] = "since analyze-plan passed on %s: %s" % (out["gated"], "; ".join(bits))
-print(json.dumps(out))
-PY
+    local core="$SCRIPT_DIR/../python/aw-plangate.py"
+    if [ ! -f "$core" ]; then echo "plan-gate-check: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "plan-gate-check: python3 is required" >&2; return 1; fi
+    python3 "$core" check --feature-dir "$fd" --context-dir "$ctx_dir" --root "$repo_root"
+}
+
+# ─────────────────────────────── gap-route ─────────────────────────────────
+# Split a gate's findings by the command that CLOSES each one. The checks already tag
+# every finding with `fix`; this turns that tag into the routing a gate message prints,
+# so a plan defect is never sent to `implement` — which generates FROM the plan and would
+# reproduce it. Thin wrapper: the logic is in aw-gaps.py, called identically by both shells.
+cmd_gap_route() {
+    case "${1:-}" in
+        --help|-h) echo "gap-route --gaps '<json>'... [--cr <id>]  -> {total, high_count, <route>_count, <route>_refs, <route>_text, summary, routes}"; return 0 ;;
+    esac
+    local core="$SCRIPT_DIR/../python/aw-gaps.py"
+    if [ ! -f "$core" ]; then echo "gap-route: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "gap-route: python3 is required" >&2; return 1; fi
+    python3 "$core" route "$@"
+}
+
+# ──────────────────────────────── plan-coverage ─────────────────────────────
+# Which of a lane plan's elements the generated code realises: each element the plan
+# names, whether the lane's code names it, and whether the generating model reported it
+# done. implement runs it after each lane generates, so a pass that stopped part-way is
+# caught instead of looking like a finished one. One implementation
+# (python/aw-plan-coverage.py), called identically by both shells.
+cmd_plan_coverage() {
+    case "${1:-}" in
+        --help|-h) echo "plan-coverage --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--source-path <p>] [--test-path <p>] [--reported <json list>]... [--generated <json list>] [--list-only]  -> {ok, outcome, total, names[], names_csv, elements[], gaps[], gap_names[], gap_count, gaps_text, message}"; return 0 ;;
+    esac
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-plan-coverage.py"
+    if [ ! -f "$core" ]; then
+        echo "plan-coverage: core not found at $core" >&2; return 1
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "plan-coverage: python3 is required" >&2; return 1
+    fi
+    python3 "$core" --repo "$repo_root" "$@"
 }
 
 # Stamp a version into the MASTER documents' `**Version**:` headers — the
@@ -4454,6 +5004,8 @@ case "$sub" in
     cr-overlap)       cmd_cr_overlap "$@" ;;
     cr-activate)      cmd_cr_activate "$@" ;;
     cr-wave)          cmd_cr_wave "$@" ;;
+    cr-wave-derive)   cmd_cr_wave_derive "$@" ;;
+    cr-rebase)        cmd_cr_rebase "$@" ;;
     cr-archive)       cmd_cr_archive "$@" ;;
     cr-recall-check)  cmd_cr_recall_check "$@" ;;
     cr-merge-check)   cmd_cr_merge_check "$@" ;;
@@ -4462,8 +5014,11 @@ case "$sub" in
     context-paths)    cmd_context_paths "$@" ;;
     model-scaffold)   cmd_model_scaffold "$@" ;;
     version-stamp)    cmd_version_stamp "$@" ;;
+    plan-gaps)        cmd_plan_gaps "$@" ;;
     plan-gate-stamp)  cmd_plan_gate_stamp "$@" ;;
     plan-gate-check)  cmd_plan_gate_check "$@" ;;
+    plan-coverage)    cmd_plan_coverage "$@" ;;
+    gap-route)        cmd_gap_route "$@" ;;
     checklist-read)   cmd_checklist_read "$@" ;;
     checklist-apply)  cmd_checklist_apply "$@" ;;
     detect-project)   cmd_detect_project "$@" ;;
@@ -4479,6 +5034,7 @@ case "$sub" in
     setup-constitution) cmd_setup_constitution "$@" ;;
     compose-constitution) cmd_compose_constitution "$@" ;;
     constitution-verify) cmd_constitution_verify "$@" ;;
+    principles-list) cmd_principles_list "$@" ;;
     agent-context-update) cmd_agent_context_update "$@" ;;
     ""|--help|-h)
         sed -n '2,37p' "$0" | sed 's/^#\{0,1\} \{0,1\}//' ;;