aw-spec-cli 0.1.20 → 0.1.21

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
@@ -1905,15 +1916,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 +1941,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 +1968,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 +2046,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 +2098,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 +2137,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"
@@ -2973,7 +3026,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 +3061,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 +3089,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 +3118,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 +3397,349 @@ 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
+
+stamped = []
+if stamp and current is not None and 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 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 stamped:
+    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 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 +3983,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 +4031,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)
@@ -4065,17 +4507,28 @@ for f in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
 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 = ""
+# 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.
+#
+# aw-crstate owns that test, for every reader of it. It replaces `cr in spec.md` — which
+# fired on an id quoted in prose and matched a prefix of a longer id — and 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.
+merged_open = []
 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)
+    _m = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_m)
+    merged_open = [r for r in _m.merged_open(ctx, fd, cr) if r["blocking"]]
+except Exception as _e:
+    # Fail CLOSED on an unreadable helper: report the state as blocking rather than clear.
+    merged_open = [{"cr_id": "(merged-open check failed: %s)" % _e, "blocking": True}]
 
 print(json.dumps({
     "ok": True, "cr_id": cr, "wave": wave,
@@ -4127,9 +4580,11 @@ 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)
 
@@ -4142,13 +4597,24 @@ def wave_of(d):
                 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
+merged, evidence, merged_doc = False, "", ""
+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)
+except Exception:
+    # 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 = True, "(merged check unavailable — treated as merged)"
 
 wave = wave_of(cr_dir) if os.path.isdir(cr_dir) else 1
 dependants = []
@@ -4190,31 +4656,87 @@ 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"
+    local feature_dir_arg="" spec_version="" mode="master" verdict="conformant" plan_gaps="0" routed="[]"
     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 ;;
+            --verdict) verdict="$2"; shift 2 ;;
+            --plan-gaps) plan_gaps="$2"; shift 2 ;;
+            --routed) routed="$2"; shift 2 ;;
+            --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 ;;
             *) echo "plan-gate-stamp: 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-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'
+    AW_FD="$fd" AW_CTX="$ctx_dir" AW_ROOT="$repo_root" AW_VER="$spec_version" AW_MODE="$mode" \
+    AW_VERDICT="$verdict" AW_PLAN_GAPS="$plan_gaps" AW_ROUTED="$routed" 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):
@@ -4236,21 +4758,34 @@ 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
+# An unrecognised verdict is recorded as `gaps`, the one that refuses.
+verdict = os.environ.get("AW_VERDICT", "").strip()
+if verdict not in ("conformant", "routed-gaps", "gaps"):
+    verdict = "gaps"
+try: plan_gaps = int(os.environ.get("AW_PLAN_GAPS", "0") or 0)
+except ValueError: plan_gaps = 0
+try: routed = [str(x) for x in json.loads(os.environ.get("AW_ROUTED") or "[]")]
+except Exception: routed = []
 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(),
+    "verdict": verdict,
+    "plan_gaps": plan_gaps,
+    "routed_gaps": routed,
     "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."),
+    "note": ("Written by every master-mode analyze-plan run. It records the bytes that were "
+             "checked against each other and the verdict on them, 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: moved bytes or verdict `gaps` "
+             "refuse; `routed-gaps` lists what /appweaver specify still has to lift."),
 }
 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"],
+                  "verdict": verdict, "plan_gaps": plan_gaps, "routed_gaps": len(routed),
                   "hashed": sorted(plans.keys()), "count": len(plans), "ok": True}))
 PY
 }
@@ -4260,7 +4795,7 @@ 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
@@ -4279,16 +4814,22 @@ 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,
+       "verdict": "", "may_generate": True, "plan_gaps": 0, "routed_gaps": [], "routed_csv": "",
        "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")
+    out["reason"] = ("no .aw-plan-gate.json — this feature has not been through analyze-plan "
+                     "in master mode since the gate began leaving a receipt")
 else:
     out["gated"] = rec.get("gated", "")
     out["spec_version"] = rec.get("spec_version", "")
+    # A receipt from before the verdict existed was only ever written on a clean pass.
+    out["verdict"] = rec.get("verdict") or "conformant"
+    out["plan_gaps"] = rec.get("plan_gaps") or 0
+    out["routed_gaps"] = [str(x) for x in (rec.get("routed_gaps") or [])]
+    out["routed_csv"] = "; ".join(out["routed_gaps"])
     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.
@@ -4300,18 +4841,48 @@ else:
     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:
+    # Moved bytes refuse whatever the verdict was; unmoved bytes refuse only on `gaps`.
+    out["may_generate"] = out["gate_fresh"] and out["verdict"] != "gaps"
+    if not out["gate_fresh"]:
         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))
+        out["reason"] = "since analyze-plan checked them on %s: %s" % (out["gated"], "; ".join(bits))
+    elif out["verdict"] == "gaps":
+        out["reason"] = ("analyze-plan on %s left %s gap(s) a plan rewrite closes, unrepaired"
+                         % (out["gated"], out["plan_gaps"] or "some"))
+    elif out["verdict"] == "routed-gaps":
+        out["reason"] = ("the spec, the model and every gated plan are byte-identical to what "
+                         "analyze-plan checked on %s; it left %d gap(s) only /appweaver specify "
+                         "can close: %s" % (out["gated"], len(out["routed_gaps"]), out["routed_csv"]))
+    else:
+        out["reason"] = "the spec, the model and every gated plan are byte-identical to what analyze-plan passed on %s" % out["gated"]
 print(json.dumps(out))
 PY
 }
 
+# ──────────────────────────────── 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>]... [--list-only]  -> {ok, 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
 # deterministic twin of cr-archive's active_version.json bump. close-delta calls
 # this with the version cr-archive just computed, so all THREE carriers of the
@@ -4454,6 +5025,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 +5035,10 @@ 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 "$@" ;;
     checklist-read)   cmd_checklist_read "$@" ;;
     checklist-apply)  cmd_checklist_apply "$@" ;;
     detect-project)   cmd_detect_project "$@" ;;