aw-spec-cli 0.1.18 → 0.1.19

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

@@ -80,7 +80,8 @@
 #   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>]
-#                                                  -> {cr_id, cr_dir, delta_spec, delta_model, wave, open_count, created}
+#                                                  -> {cr_id, cr_dir, delta_spec, delta_model, wave, open_count, created,
+#                                                      created_on, base_version, base_context_version}
 #   cr-list          [--feature-dir <path>] [--preselect <cr-id|main|new>] [--include-main] [--include-new]
 #                                                  -> {changes[], ids[], count, select_options[], matched_label, main_label,
 #                                                      new_label, only_id, active_change}
@@ -93,8 +94,16 @@
 #                                                      sibling_overlaps, successor_overlaps, overlap_report}
 #   cr-activate      --cr-id <id> [--feature-dir <path>]  -> {active_change, activated, open_changes[]}
 #   cr-wave          --cr-id <id> --wave <n> [--feature-dir <path>]  -> {cr_id, wave, stamped}
-#   cr-archive       --cr-id <id> [--feature-dir <path>]
-#                                                  -> {ok, archived_dir, version, previous}
+#   cr-archive       --cr-id <id> [--feature-dir <path>] [--recall] [--reason <text>]
+#                                                  -> {ok, archived_dir, archived_model, recalled,
+#                                                      recall_marker, version, previous,
+#                                                      closed_change, recalled_change, open_changes[]}
+#   cr-recall-check  --cr-id <id> [--feature-dir <path>]
+#                                                  -> {merged, merge_evidence, wave, dependants[],
+#                                                      dependant_ids, dependant_count, has_dependants}
+#   context-version-bump  [--feature-dir <path>] [--cr-id <id>] [--touched-model true|false]
+#                                                  -> {ok, bumped, previous, version, model,
+#                                                      model_exists, context, reason}
 #
 # All subcommands accept --help.
 
@@ -795,7 +804,13 @@ cmd_lane_verify() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
         case "$1" in
-            --require) fwd+=("--require" "$2"); shift 2 ;;
+            # An EMPTY --require is "any lane will do" and is dropped rather than
+            # forwarded: the phase needs a declaration to work from, not a lane of a
+            # particular kind. A workflow that includes lane-gate cannot omit an
+            # argument conditionally — the include's `with` map is rendered whole —
+            # so an empty value is the only way it can say this, and argparse rejects
+            # one against --require's choices. Every other check stays armed.
+            --require) if [ -n "$2" ]; then fwd+=("--require" "$2"); fi; shift 2 ;;
             # --flag=value: --command carries a phase name that starts with '/'.
             --command) fwd+=("--command=$2"); shift 2 ;;
             --allow-missing-root) fwd+=("--allow-missing-root"); shift ;;
@@ -1029,6 +1044,25 @@ open(p, "w", encoding="utf-8").write(text)
 PY
 }
 
+# Read one `**Name**: value` header back out of a document — the counterpart of
+# _stamp_header, for the case where one document's header is the SOURCE of another's.
+# An UNFILLED template placeholder reads as absent: a header still carrying `[vX.Y]` or
+# `[DATE]` states nothing, and copying that bracket forward would spread the placeholder
+# instead of a value. Any trailing `<!-- … -->` the template keeps beside the value is
+# stripped, so the caller gets the value and not the explanation of it.
+_read_header() {   # $1 = file, $2 = header name -> the value, empty when absent/unfilled
+    [ -f "$1" ] || return 0
+    AW_F="$1" AW_NAME="$2" python3 - <<'PY'
+import os, re
+try: text = open(os.environ["AW_F"], encoding="utf-8").read()
+except Exception: raise SystemExit(0)
+m = re.search(r"^\*\*%s\*\*:[ \t]*(.*)$" % re.escape(os.environ["AW_NAME"]), text, re.M)
+if not m: raise SystemExit(0)
+val = re.sub(r"<!--.*", "", m.group(1)).strip()
+print("" if (val.startswith("[") and val.endswith("]")) else val)
+PY
+}
+
 # The highest wave among the delta models currently open in a context, or 1 when none
 # is. This is the DEFAULT for a new delta: parallel with whatever is already in flight,
 # never implicitly sequenced behind it.
@@ -1037,7 +1071,7 @@ _max_open_wave() {   # $1 = abs context dir
 import os, re, glob
 ctx = os.environ["AW_CTX"]
 best = 0
-for f in glob.glob(os.path.join(ctx, "domain-model.*.delta.md")):
+for f in glob.glob(os.path.join(glob.escape(ctx), "domain-model.*.delta.md")):
     try: t = open(f, encoding="utf-8").read()
     except Exception: continue
     m = re.search(r"^\*\*Wave\*\*:\s*(\d+)", t, re.M)
@@ -1105,7 +1139,7 @@ name = os.path.basename(ctx.rstrip("/"))
 context = "" if rel(ctx) == "specs" else name
 master = os.path.join(ctx, "domain-model.md")
 pending, files = [], []
-for f in sorted(glob.glob(os.path.join(ctx, "domain-model.*.delta.md"))):
+for f in sorted(glob.glob(os.path.join(glob.escape(ctx), "domain-model.*.delta.md"))):
     base = os.path.basename(f)
     cr = base[len("domain-model."):-len(".delta.md")]
     wave = 1
@@ -1246,10 +1280,16 @@ if os.path.isdir(base):
             "dir": base_rel + "/" + name,
             "source": "spec",
             "has_spec": os.path.isfile(os.path.join(d, "spec.md")),
-            # `design*.md`, NOT `design.*.md`: the second dot made this miss the single
-            # `design.md` the framework actually produces (it only matched the retired
-            # design.domain.md / design.technical.md family). Informational count only.
-            "design_docs": len(glob.glob(os.path.join(d, "design*.md"))),
+            # HOW MANY LANE PLANS THIS FEATURE HAS. Counted by NAME, not by glob: the
+            # documents are backend-plan.md / frontend-plan.md, and the legacy pair
+            # design.md / design.ui.md that feature-paths still resolves under the same
+            # keys for a tree adopted before the rename. The old `design*.md` glob counted
+            # neither of the current names, so this was structurally 0 on every feature the
+            # framework produces today — a field that could only ever be wrong.
+            # Informational only; no workflow reads it.
+            "plan_docs": sum(1 for n in ("backend-plan.md", "frontend-plan.md",
+                                         "design.md", "design.ui.md")
+                             if os.path.isfile(os.path.join(d, n))),
             "version": ver,
             "active_change": active_change,
         })
@@ -1267,10 +1307,15 @@ for agg in (okf.get("aggregates") or []):
         "has_spec": False,
         "adopted": False,
         "concept_path": agg.get("concept_path", ""),
-        "design_docs": 0,
+        "plan_docs": 0,
         "version": "",
         "active_change": "",
     })
+# `design_docs` is kept as a same-value ALIAS of plan_docs. The key is part of this op's
+# published shape, so dropping it would break a reader outside the kit for no gain; what
+# it reports is now the plan pair rather than a glob that matched nothing.
+for _f in feats:
+    _f["design_docs"] = _f["plan_docs"]
 opts = list(names)
 # Inject a not-yet-existing --preselect so `preselect_from: USER_INPUT` can
 # create-or-select it without an extra round trip (the direct-arg fast path).
@@ -1322,6 +1367,39 @@ cmd_set_feature() {
         echo "set-feature: refusing — '$feature_dir_rel' is a bounded context, not a feature. Run /appweaver select-bounded-context $feature first, then select-feature." >&2
         return 1
     fi
+    # AND THE SAME REFUSAL FOR A CONTEXT THAT IS MERELY EMPTY. The test above asks what a
+    # directory CONTAINS, so a context created by select-bounded-context and not yet
+    # populated — no domain-model.md, no feature inside it — passes it and is taken as a
+    # feature, which writes spec.md into it and orphans every feature meant to live there.
+    # Emptiness cannot be told from "a new feature directory" by looking at the directory,
+    # so the question asked here is the one list-contexts asks instead: is this repo USING
+    # bounded contexts, and is none of them active? In that state a target directly under
+    # specs/ is outside every context and cannot be the feature the caller meant — which is
+    # exactly the state `select-feature` refuses via scope_ok, restated at the point of the
+    # write so no other caller can walk past it.
+    if [ "$base_rel" = "specs" ] && [ ! -f "$feature_dir/spec.md" ]; then
+        local other_contexts
+        other_contexts=$(AW_SPECS="$repo_root/specs" AW_TARGET="$feature" python3 - <<'PY'
+import os
+base = os.environ["AW_SPECS"]; target = os.environ["AW_TARGET"]
+names = []
+if os.path.isdir(base):
+    for n in sorted(os.listdir(base)):
+        d = os.path.join(base, n)
+        if not os.path.isdir(d) or n == target:
+            continue
+        # A directory with its own spec.md is a FEATURE (the flat pre-context layout);
+        # one without is a context. Only the latter means contexts are in use here.
+        if not os.path.isfile(os.path.join(d, "spec.md")):
+            names.append(n)
+print(", ".join(names))
+PY
+)
+        if [ -n "$other_contexts" ]; then
+            echo "set-feature: refusing — this repository uses bounded contexts ($other_contexts) and none is active, so '$feature_dir_rel' would be created outside every one of them. If $feature is itself a bounded context, run /appweaver select-bounded-context $feature. If it is a feature, run /appweaver select-bounded-context to choose the context that owns it first, then select-feature $feature." >&2
+            return 1
+        fi
+    fi
     local existed=false; [ -d "$feature_dir" ] && existed=true
     mkdir -p "$feature_dir"
     _persist_feature_json "$repo_root" "$feature_dir_rel"
@@ -1453,6 +1531,42 @@ elif op == "activate":
         save(d)
         out["active_change"] = d["active_change"]; out["activated"] = cr
     out["open_changes"] = opens; out["open_count"] = len(opens)
+elif op == "recall":
+    # WITHDRAWS one change: drop it from open_changes and move active_change off it,
+    # WITHOUT bumping the version. That is the whole difference from `close`, and it is
+    # the reason the two are separate ops rather than one with a flag. A version is what a
+    # change SHIPPED as; a recalled change shipped nothing, so bumping would burn a number
+    # on work that was never merged and leave the spine claiming a release that does not
+    # exist. Everything else is identical — the same membership edit, the same fallback
+    # for active_change — so a recall and a close leave the ledger in the same SHAPE and
+    # only the number tells them apart.
+    #
+    # Refusing an untracked id is the point of this op, not a nicety: recall archives
+    # documents, so acting on an id the ledger does not know would move a directory on the
+    # strength of a typo. `close` cannot afford the same strictness (it is also the
+    # migration path for state written before open_changes existed); recall can, because
+    # every change it can reach was opened by specify.
+    prev = d["version"]
+    opens = [c for c in (d.get("open_changes") or []) if c]
+    if not opens and d.get("active_change"):
+        opens = [d["active_change"]]          # state written before open_changes existed
+    target = cr or d.get("active_change", "")
+    if not target:
+        out["ok"] = False
+        out["error"] = "no change named and none is active on this feature"
+    elif target not in opens:
+        out["ok"] = False
+        out["error"] = ("'%s' is not an open change on this feature (open: %s)"
+                        % (target, ", ".join(opens) or "none"))
+    else:
+        opens.remove(target)
+        d["open_changes"] = opens
+        d["active_change"] = opens[-1] if opens else ""
+        save(d)
+        out["recalled_change"] = target
+    out["version"] = d["version"]; out["previous"] = prev
+    out["active_change"] = d.get("active_change", "")
+    out["open_changes"] = opens; out["open_count"] = len(opens)
 elif op == "close":
     # Closes ONE change by id (falling back to active_change when none is named, which
     # is the pre-parallel caller). The version bumps once per change materialized, and
@@ -3056,6 +3170,9 @@ cmd_cr_setup() {
     done
     # A random suffix, not the bare timestamp: two changes opened in the same second
     # would otherwise collide on one id, and with parallel deltas that is reachable.
+    # Before the generated default, so a menu LABEL passed as --cr-id becomes its id
+    # rather than a directory name with spaces in it. Empty stays empty and is generated.
+    cr_id=$(_cr_id_token "$cr_id")
     [ -n "$cr_id" ] || cr_id="CR-$(date -u +%Y%m%d-%H%M%S)-$(_rand_suffix)"
     local repo_root; repo_root=$(get_repo_root)
     local fd="$feature_dir_arg"
@@ -3098,15 +3215,47 @@ cmd_cr_setup() {
         if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$dmodel"; else touch "$dmodel"; fi
         created=true
     fi
-    # Scripts stamp ids, dates and the wave — the model never writes them.
+    # Scripts stamp ids, dates and versions — the model never writes them, and the delta
+    # quality checklists REQUIRE a complete header, so every placeholder the templates
+    # carry has to be filled here or it ships as a literal `[DATE]` / `[vX.Y]`.
+    #
+    # BASE VERSION is the master version this delta is being authored AGAINST, read from
+    # the ledger that was just updated — `open` does not move the number, so what comes
+    # back is the current one. It is what a rebase check compares against later: a master
+    # that moved between the opening of a change and its merge is a change authored on a
+    # document that no longer exists in that form.
+    #
+    # BASE CONTEXT VERSION is the same idea one level up, and its source is the master
+    # model's own `**Context version**:` header rather than any ledger — there is no
+    # context-level version file (⌛ that, and the close-delta bump that would move the
+    # number, are still to build). While nothing bumps it, every delta reads the same
+    # v1.0; the field is still correct, and it starts carrying real information the moment
+    # something stamps the master.
+    local created_on; created_on=$(date -u +%Y-%m-%d)
+    local base_version; base_version=$(printf '%s' "$av_open" | _json_field version)
+    [ -n "$base_version" ] || base_version="v1.0"
+    case "$base_version" in v*) ;; *) base_version="v$base_version" ;; esac
+    local base_ctx; base_ctx=$(_read_header "$ctx_dir/domain-model.md" "Context version")
+    [ -n "$base_ctx" ] || base_ctx="v1.0"
+    # Both version fields are normalised to the same `vX.Y` shape. base_version comes from
+    # a machine ledger and base_ctx from a markdown header a human may have written as
+    # "1.0", and a rebase check compares these as strings — two spellings of one version
+    # would read as a move that never happened.
+    case "$base_ctx" in v*) ;; *) base_ctx="v$base_ctx" ;; esac
+
     _stamp_header "$dspec"  "Wave" "$wave"
+    _stamp_header "$dspec"  "Created" "$created_on"
+    _stamp_header "$dspec"  "Base version" "$base_version"
     _stamp_header "$dmodel" "Wave" "$wave"
+    _stamp_header "$dmodel" "Created" "$created_on"
+    _stamp_header "$dmodel" "Base context version" "$base_ctx"
 
     local open_count; open_count=$(printf '%s' "$av_open" | _json_field open_count)
-    printf '{"cr_id":"%s","cr_dir":"%s","delta_spec":"%s","delta_model":"%s","context_dir":"%s","wave":%s,"open_count":%s,"title":"%s","created":%s}\n' \
+    printf '{"cr_id":"%s","cr_dir":"%s","delta_spec":"%s","delta_model":"%s","context_dir":"%s","wave":%s,"open_count":%s,"title":"%s","created":%s,"created_on":"%s","base_version":"%s","base_context_version":"%s"}\n' \
         "$(json_escape "$cr_id")" "$(json_escape "$cr_dir")" "$(json_escape "$dspec")" \
         "$(json_escape "$dmodel")" "$(json_escape "$ctx_rel")" \
-        "$wave" "${open_count:-1}" "$(json_escape "$title")" "$created"
+        "$wave" "${open_count:-1}" "$(json_escape "$title")" "$created" \
+        "$(json_escape "$created_on")" "$(json_escape "$base_version")" "$(json_escape "$base_ctx")"
 }
 
 # ─────────────────────────────── cr-wave ────────────────────────────────────
@@ -3124,6 +3273,9 @@ cmd_cr_wave() {
             *) echo "cr-wave: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
+    # The whole LABEL arrives when a caller picked from a menu; every cr-* op takes its
+    # first token. A bare id is unchanged by this.
+    cr_id=$(_cr_id_token "$cr_id")
     [ -n "$cr_id" ] || { echo "cr-wave: --cr-id is required" >&2; return 1; }
     case "$wave" in ''|*[!0-9]*) echo "cr-wave: --wave must be a positive integer" >&2; return 1 ;; esac
     local repo_root; repo_root=$(get_repo_root)
@@ -3274,6 +3426,9 @@ if not matched and pre_raw:
     elif inc_new and pre_raw == "new": matched = NEW_LABEL
 print(json.dumps({
     "changes": rows, "ids": [r["cr_id"] for r in rows], "count": len(rows),
+    # The same ids as one readable string, for an operator message. A list renders as its
+    # JSON in a rendered string, which is right for a payload and wrong for a sentence.
+    "ids_csv": ", ".join(r["cr_id"] for r in rows),
     "select_options": opts, "matched_label": matched,
     "main_label": MAIN_LABEL if inc_main else "",
     "new_label": NEW_LABEL if inc_new else "",
@@ -3331,11 +3486,11 @@ wave = wave_of(dspec, wave_of(dmodel, 1))
 # spec of another open change is found by walking the context's features rather than
 # assuming it belongs to this one — two features of one context can both have changes open.
 def spec_of(other):
-    for c in sorted(glob.glob(os.path.join(ctx, "*", "changes", other, "delta-spec.md"))):
+    for c in sorted(glob.glob(os.path.join(glob.escape(ctx), "*", "changes", glob.escape(other), "delta-spec.md"))):
         return c
     return ""
 pred, sib, pred_rows, sib_rows, pred_specs = [], [], [], [], []
-for f in sorted(glob.glob(os.path.join(ctx, "domain-model.*.delta.md"))):
+for f in sorted(glob.glob(os.path.join(glob.escape(ctx), "domain-model.*.delta.md"))):
     base = os.path.basename(f)
     other = base[len("domain-model."):-len(".delta.md")]
     if other == cr:
@@ -3367,6 +3522,17 @@ print(json.dumps({
     "predecessor_docs": pred + pred_specs,
     # Same or higher wave = nothing orders it against this one. Visible, never assumed.
     "sibling_files": sib, "siblings": sib_rows, "sibling_count": len(sib),
+    # EVERYTHING A PLANNER SHOULD SEE, in one list, for the same one-var reason. Siblings
+    # belong in it as much as predecessors do: a planner told "do not assume a same-wave
+    # delta, and say so where one touches the same aggregate" cannot name an overlap it
+    # was never shown, and the gate one stage later raises a finding for the silence.
+    # Their MODEL deltas only — the aggregate a sibling touches is what makes it an
+    # overlap, and their delta-specs would double the payload to say nothing more about it.
+    "related_docs": pred + pred_specs + sib,
+    # Who is who, as text for a prompt. The file list alone cannot say which entries are
+    # committed to landing first and which are merely open beside this one.
+    "predecessor_ids": ", ".join("%s (wave %d)" % (r["cr_id"], r["wave"]) for r in pred_rows),
+    "sibling_ids": ", ".join("%s (wave %d)" % (r["cr_id"], r["wave"]) for r in sib_rows),
 }))
 PY
 }
@@ -3384,8 +3550,9 @@ PY
 # EARLY WARNING, NOT ENFORCEMENT. An overlap is not an error: two changes to one
 # aggregate are ordinary, and expand-then-contract is the way through. What matters is
 # that the second one is PLANNED knowing about the first instead of discovering it at
-# merge time, which is why this runs at the gate and finalize-delta still holds the
-# base_version check.
+# merge time, which is why this runs at the gate while the HARD refusals stay at the merge:
+# cr-merge-check holds the base_version comparison, the merged-not-closed test and the
+# lower-wave predecessor test, and finalize-delta stops on each.
 #
 # The relation follows the wave: a LOWER wave is a predecessor (committed to land first —
 # an overlap with it is a dependency to declare), the SAME wave is a sibling (nothing
@@ -3436,7 +3603,7 @@ wave = wave_of(read(os.path.join(fd, "changes", cr, "delta-spec.md")), wave_of(m
 mine = aggregates_of(mine_txt)
 mine_set = set(mine)
 rows, parts, npred, nsib, nsucc = [], [], 0, 0, 0
-for f in sorted(glob.glob(os.path.join(ctx, "domain-model.*.delta.md"))):
+for f in sorted(glob.glob(os.path.join(glob.escape(ctx), "domain-model.*.delta.md"))):
     other = os.path.basename(f)[len("domain-model."):-len(".delta.md")]
     if other == cr:
         continue
@@ -3453,6 +3620,9 @@ for f in sorted(glob.glob(os.path.join(ctx, "domain-model.*.delta.md"))):
     parts.append("%s (wave %d, %s): %s" % (other, w, relation, ", ".join(shared)))
 print(json.dumps({
     "cr_id": cr, "wave": wave, "aggregates": mine,
+    # The same names as one readable string, for a prompt. A list renders as its JSON in a
+    # rendered string, which is right for a payload and wrong for a sentence.
+    "aggregates_csv": ", ".join(mine),
     "overlaps": rows, "overlap_count": len(rows),
     "predecessor_overlaps": npred, "sibling_overlaps": nsib,
     "successor_overlaps": nsucc,
@@ -3486,27 +3656,72 @@ cmd_cr_activate() {
     [ -n "$cr_id" ] || { echo "cr-activate: --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-activate: no feature set and no --feature-dir" >&2; return 1; }
-    _active_version "$fd" activate "$cr_id"
+    local out; out=$(_active_version "$fd" activate "$cr_id") || return 1
+    printf '%s\n' "$out"
+    # A REFUSAL IS AN ERROR, NOT A RESULT — so it leaves through the exit code, like
+    # every other way this command can fail. When the id is not in the ledger nothing
+    # moves and the JSON reports active_change: "", which is precisely what the calling
+    # step binds; an empty active change then reads as "no change" in every condition
+    # downstream, and the run continues against a target it never selected. Refusing
+    # here turns that into the engine's own stop, carrying the message to the operator.
+    #
+    # THIS IS REACHABLE, not defensive: cr-list offers what is on DISK (changes/<id>/ is
+    # the authority for "open") and reports `tracked` separately, so a change whose
+    # directory survived a crashed run is still offered while the ledger has forgotten it.
+    # `ok` starts True and is flipped only by a refusal, so an EXPLICIT False is the test.
+    local ok; ok=$(printf '%s' "$out" | _json_field ok)
+    if [ "$ok" = "False" ] || [ "$ok" = "false" ]; then
+        printf 'cr-activate: %s\n' "$(printf '%s' "$out" | _json_field error)" >&2
+        return 1
+    fi
 }
 
+# ARCHIVE, in either of the two ways a change leaves the open set.
+#
+#   default   CLOSED — it shipped. The directory is archived and the version bumps, which
+#             is close-delta's whole job and the behaviour every existing caller gets.
+#   --recall  WITHDRAWN — it never shipped. The same archive, and NO version bump: a
+#             version records what a change shipped as, and a recalled change shipped
+#             nothing, so bumping would burn a number on work that was never merged.
+#
+# The two were fused until recall-delta needed the archive half on its own, which is why
+# withdrawing a change could not be "archive alone". Splitting them here rather than in
+# each caller keeps ONE place that knows how a change's documents are put away — the
+# directory, and the model delta that lives beside the master rather than inside it.
 cmd_cr_archive() {
-    local cr_id="" feature_dir_arg=""
+    local cr_id="" feature_dir_arg="" recall="" reason=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-archive --cr-id <id> [--feature-dir <path>]"; return 0 ;;
+            --recall) recall="1"; shift ;;
+            --reason) reason="$2"; shift 2 ;;
+            --help|-h) echo "cr-archive --cr-id <id> [--feature-dir <path>] [--recall] [--reason <text>]"; return 0 ;;
             *) echo "cr-archive: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
+    # A caller that picked from a user_select menu hands over the whole LABEL
+    # ("CR-… · wave 2 · title"), not the id. Every other cr-* op takes the first token;
+    # this one did not, so a label arrived here as a directory name that does not exist
+    # and the archive silently moved nothing.
+    cr_id=$(_cr_id_token "$cr_id")
     [ -n "$cr_id" ] || { echo "cr-archive: --cr-id 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-archive: no feature set and no --feature-dir" >&2; return 1; }
     [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    # THE LEDGER EDIT COMES FIRST, because it is the only step that can REFUSE. `recall`
+    # will not withdraw a change active_version.json does not carry, and a refusal has to
+    # be a no-op: archiving before asking would move the directory and only then report
+    # that the change was never open. `close` cannot refuse, so its side effects are
+    # unchanged by the ordering.
+    local op="close"; [ -n "$recall" ] && op="recall"
+    local av; av=$(_active_version "$fd" "$op" "$cr_id")
+    local ledger_ok; ledger_ok=$(printf '%s' "$av" | python3 -c 'import json,sys; print("1" if json.load(sys.stdin).get("ok", True) else "")' 2>/dev/null || echo "1")
+
     local cr_dir="$fd/changes/$cr_id" archive_root="$fd/changes/archive" archived=""
-    if [ -d "$cr_dir" ]; then
+    if [ -n "$ledger_ok" ] && [ -d "$cr_dir" ]; then
         mkdir -p "$archive_root"
         rm -rf "$archive_root/$cr_id"
         mv "$cr_dir" "$archive_root/$cr_id"
@@ -3519,21 +3734,565 @@ cmd_cr_archive() {
     # in-flight to every other open delta.
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
     local dmodel="$ctx_dir/domain-model.$cr_id.delta.md" model_archived=""
-    if [ -f "$dmodel" ]; then
+    if [ -n "$ledger_ok" ] && [ -f "$dmodel" ]; then
         mkdir -p "$archive_root/$cr_id"
         mv -f "$dmodel" "$archive_root/$cr_id/domain-model.delta.md"
         model_archived="$archive_root/$cr_id/domain-model.delta.md"
     fi
-    # Close THIS change in active_version.json (single version source): bump minor +
-    # drop it from open_changes. Other changes on the feature stay open.
-    local av; av=$(_active_version "$fd" close "$cr_id")
-    AW_AV="$av" AW_ARCHIVED="$archived" python3 - <<'PY'
+    # A RECALLED change is marked as such where the evidence will be looked for — inside
+    # its own archive — and the marker is written by the script, not by a model, because
+    # everything on it is a fact the script already holds: the id, the date, and the
+    # reason the caller passed.
+    local marker=""
+    if [ -n "$recall" ] && [ -n "$archived" ]; then
+        marker="$archived/RECALLED.md"
+        AW_MARK="$marker" AW_CR="$cr_id" AW_REASON="$reason" python3 - <<'PY'
+import datetime, os
+when = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d")
+cr, reason = os.environ["AW_CR"], os.environ.get("AW_REASON", "").strip()
+open(os.environ["AW_MARK"], "w", encoding="utf-8").write(
+    "# RECALLED — %s\n\n"
+    "**Recalled**: %s\n"
+    "**Reason**: %s\n\n"
+    "This change was WITHDRAWN before it was merged. Its delta documents are archived here\n"
+    "unchanged; the feature's spec.md and the context's domain-model.md never carried it,\n"
+    "and the version was not bumped — no release shipped this work.\n\n"
+    "Any code /appweaver implement generated for this change is NOT reverted by a recall.\n"
+    "Revert it with git if it should not stay.\n"
+    % (cr, when, reason or "(not stated)"))
+PY
+    fi
+    AW_AV="$av" AW_ARCHIVED="$archived" AW_MODEL="$model_archived" AW_MARK="$marker" \
+    AW_RECALL="$recall" AW_CR="$cr_id" python3 - <<'PY'
 import json, os
 try: av = json.loads(os.environ.get("AW_AV") or "{}")
 except Exception: av = {}
-print(json.dumps({"ok": True, "archived_dir": os.environ.get("AW_ARCHIVED", ""),
-                  "version": av.get("version", "v1.1"), "previous": av.get("previous", "v1.0"),
-                  "closed_change": av.get("closed_change", "")}))
+recalled = bool(os.environ.get("AW_RECALL"))
+out = {
+    # The ledger edit is what can refuse (recall will not touch a change the ledger does
+    # not carry), so its verdict is this command's verdict.
+    "ok": av.get("ok", True),
+    "archived_dir": os.environ.get("AW_ARCHIVED", ""),
+    "archived_model": os.environ.get("AW_MODEL", ""),
+    "recalled": recalled,
+    "recall_marker": os.environ.get("AW_MARK", ""),
+    "version": av.get("version", "v1.1"),
+    "previous": av.get("previous", "v1.0"),
+    # Which of the two ways it left the open set. Exactly one is ever non-empty.
+    "closed_change": av.get("closed_change", ""),
+    "recalled_change": av.get("recalled_change", ""),
+    "active_change": av.get("active_change", ""),
+    "open_changes": av.get("open_changes", []),
+    "open_count": av.get("open_count", 0),
+}
+if av.get("error"): out["error"] = av["error"]
+print(json.dumps(out))
+PY
+}
+
+# ──────────────────────────── context-version-bump ─────────────────────────
+# Move the BOUNDED CONTEXT's version, the way version-stamp moves a feature's.
+#
+# The model's header has always declared itself script-stamped — `**Context version**:
+# v1.0   <!-- script-stamped; close-delta bumps it when a closing delta touched the
+# model -->` — and specify tells the authoring model not to write it. Nothing wrote it,
+# so every context sat at the template's v1.0 for its whole life and the one instruction
+# the model was given about that field was the only thing keeping it accurate.
+#
+# WHY IT IS A CONTEXT-LEVEL NUMBER. A feature's version says what that feature shipped;
+# the model is shared by every feature in the context, so a change to it is a change to
+# all of them and no single feature's version can record it. The two spines move
+# independently and neither is derived from the other.
+#
+# ONLY WHEN THE MODEL ACTUALLY CHANGED. The caller passes --touched-model; a behaviour-only
+# change closes without moving this number, exactly as it leaves domain-model.md alone.
+# Refusing to bump is reported, not an error — most changes never touch the model.
+cmd_context_version_bump() {
+    local feature_dir_arg="" touched="" cr_id=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --cr-id) cr_id="$2"; shift 2 ;;
+            # Takes a VALUE rather than being a bare flag: a workflow cannot omit an
+            # argument conditionally (an include's arg list is rendered whole), so the
+            # caller always passes it and says true or false. Anything but `true` is false.
+            --touched-model) [ "$2" = "true" ] && touched="1" || touched=""; shift 2 ;;
+            --help|-h) echo "context-version-bump [--feature-dir <path>] [--cr-id <id>] [--touched-model true|false]  -> {ok, bumped, previous, version, model, context}"; return 0 ;;
+            *) echo "context-version-bump: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    # The whole LABEL arrives when a caller picked from a menu; every cr-* op takes its
+    # first token. Here the id only reaches the Change History row, so a label would have
+    # been recorded verbatim rather than failing loudly — the quietest of the family's
+    # inconsistencies, and the reason to close it rather than wait for a caller to hit it.
+    cr_id=$(_cr_id_token "$cr_id")
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "context-version-bump: no feature set and no --feature-dir" >&2; return 1; }
+    local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
+    local model="$ctx_dir/domain-model.md"
+    local ctx_rel="${ctx_dir#$repo_root/}"
+    local model_rel="${model#$repo_root/}"
+
+    local current; current=$(_read_header "$model" "Context version")
+    [ -n "$current" ] || current="v1.0"
+    case "$current" in v*) ;; *) current="v$current" ;; esac
+
+    local bumped=false next="$current" reason=""
+    if [ ! -f "$model" ]; then
+        reason="this feature's context has no domain-model.md, so there is no context version to move"
+    elif [ -z "$touched" ]; then
+        reason="the closing change carried no model delta, so the context is unchanged"
+    else
+        next=$(AW_CUR="$current" python3 -c '
+import os, re
+m = re.match(r"v?(\d+)(?:\.(\d+))?", os.environ["AW_CUR"].strip())
+maj = int(m.group(1)) if m else 1
+mnr = int(m.group(2)) if (m and m.group(2)) else 0
+print("v%d.%d" % (maj, mnr + 1))')
+        _stamp_header "$model" "Context version" "$next"
+        bumped=true
+        reason="the closing change merged a model delta into this context"
+    fi
+    printf '{"ok":true,"bumped":%s,"previous":"%s","version":"%s","model":"%s","model_exists":%s,"context":"%s","reason":"%s"}\n' \
+        "$bumped" "$(json_escape "$current")" "$(json_escape "$next")" \
+        "$(json_escape "$model_rel")" "$([ -f "$model" ] && echo true || echo false)" \
+        "$(json_escape "$ctx_rel")" "$(json_escape "$reason")"
+}
+
+# ───────────────────────────── cr-snapshot ─────────────────────────────────
+# Copy the two MASTERS into changes/<id>/pre-merge/ immediately before finalize-delta
+# rewrites them. The merge is the one act of the CR loop that edits a long-lived
+# hand-curated document in place, and until this existed the only record of what those
+# documents said beforehand was git — which is a different tool's answer to the question,
+# and unavailable at all if the merge and the commit are not interleaved.
+#
+# WHAT IT IS FOR. A recall after a merge has to put the masters back, and it may only do so
+# when nothing else landed in between — the `pre-merge` copy is the content to restore and
+# cr-merge-check's base_version comparison is what answers whether restoring is still safe.
+# Taken together they are the difference between "un-merge" and "hope".
+#
+# IT IS A COPY, NOT A MOVE, and it is overwritten on a re-run: finalize-delta may be
+# attempted more than once (a red downstream fence aborts it), and the snapshot that matters
+# is the one taken by the attempt that actually merged. The manifest records the version and
+# the date so a reader can tell which.
+#
+# The snapshot travels WITH the change — changes/<id>/ is what cr-archive moves — so a
+# closed change carries the before-image of the masters it moved, in the archive, forever.
+cmd_cr_snapshot() {
+    local cr_id="" feature_dir_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --help|-h) echo "cr-snapshot --cr-id <id> [--feature-dir <path>]  -> {ok, dir, files[], count, version}"; return 0 ;;
+            *) echo "cr-snapshot: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "cr-snapshot: --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-snapshot: 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_CR="$cr_id" python3 - <<'PY'
+import json, os, re, shutil, datetime
+fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]; cr = os.environ["AW_CR"]
+def rel(p): return os.path.relpath(p, root)
+def header(path, name, default=""):
+    try: t = open(path, encoding="utf-8").read()
+    except Exception: return default
+    m = re.search(r"^\*\*%s\*\*:[ \t]*(.+?)[ \t]*(?:<!--.*)?$" % re.escape(name), t, re.M)
+    return m.group(1).strip() if m else default
+
+snap = os.path.join(fd, "changes", cr, "pre-merge")
+os.makedirs(snap, exist_ok=True)
+spec  = os.path.join(fd, "spec.md")
+model = os.path.join(ctx, "domain-model.md")
+copied = []
+# Flat names, not the source tree's shape: there are exactly two masters and they live at
+# different levels, so a nested copy would encode the layout of the day it was taken.
+for src, name in ((spec, "spec.md"), (model, "domain-model.md")):
+    if os.path.isfile(src):
+        shutil.copy2(src, os.path.join(snap, name))
+        copied.append(name)
+
+version = ""
+try:
+    version = json.load(open(os.path.join(fd, "active_version.json"), encoding="utf-8")).get("version", "")
+except Exception:
+    pass
+
+manifest = {
+    "cr_id": cr,
+    "taken": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    "version": version,
+    "context_version": header(model, "Context version"),
+    "files": copied,
+    "sources": {"spec.md": rel(spec), "domain-model.md": rel(model)},
+    # Stated in the file itself, because the restore is the reader's whole reason for
+    # opening it and the condition on it is not obvious from the content.
+    "note": ("Masters as they stood immediately before finalize-delta merged %s. "
+             "Restoring is only safe while no other change finalized afterwards — "
+             "cr-merge-check's base_version comparison is what answers that." % cr),
+}
+with open(os.path.join(snap, "manifest.json"), "w", encoding="utf-8") as f:
+    json.dump(manifest, f, indent=2)
+    f.write("\n")
+
+print(json.dumps({"ok": True, "cr_id": cr, "dir": rel(snap), "files": copied,
+                  "count": len(copied), "version": version,
+                  "manifest": rel(os.path.join(snap, "manifest.json"))}))
+PY
+}
+
+# ───────────────────────────── cr-merge-check ──────────────────────────────
+# The two mechanical refusals finalize-delta needs, answered in one call from evidence on
+# disk — the merge-side twin of cr-recall-check below, and shaped the same way so the two
+# gates of the CR loop read alike.
+#
+# REBASE. `cr-setup` stamps `**Base version**:` into the delta-spec at the moment the change
+# opens: the master version the delta was authored AGAINST. If spec.md has moved since —
+# because another change finalized and closed in between — then the delta's MODIFIED items
+# name a BEFORE the master no longer says, and merging them is last-writer-wins against work
+# that already landed. Both sides are normalised to `vX.Y` by cr-setup, so this is an exact
+# string comparison and never a judgement. A delta with no stamped header (authored before
+# the field existed, or hand-made) reports `base_version: ""` and does NOT block — an absent
+# stamp is no evidence of a move, and refusing on it would strand every legacy change.
+#
+# PREDECESSORS. A wave is a dependency level: a LOWER wave is committed to landing first, and
+# `plan` puts exactly those deltas in the planner's context as the base this one builds on.
+# Merging out of wave order therefore folds in behaviour that assumes a predecessor the
+# masters do not yet carry. `depends_on` is stamped nowhere, so the wave is the only
+# dependency signal that exists; same-wave changes are independent by definition and are
+# never counted.
+#
+# THE SCAN IS CONTEXT-WIDE, matching cr-paths' definition of a predecessor: two features of
+# one bounded context share domain-model.md, so a lower-wave change on a sibling feature is
+# as much a predecessor as one on this feature. Both halves are read — the changes/<id>/
+# directories AND the pending model deltas — because a behaviour-only change has no model
+# delta and would be invisible to a scan of those alone.
+cmd_cr_merge_check() {
+    local cr_id="" feature_dir_arg=""
+    while [ $# -gt 0 ]; do
+        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 ;;
+            *) echo "cr-merge-check: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "cr-merge-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-merge-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" AW_CR="$cr_id" python3 - <<'PY'
+import json, os, re
+fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]; cr = os.environ["AW_CR"]
+def rel(p): return os.path.relpath(p, root)
+
+def header(path, name, default=""):
+    try: t = open(path, encoding="utf-8").read()
+    except Exception: return default
+    m = re.search(r"^\*\*%s\*\*:[ \t]*(.+?)[ \t]*(?:<!--.*)?$" % re.escape(name), t, re.M)
+    if not m: return default
+    v = m.group(1).strip()
+    # An unfilled template placeholder is not a value. `[vX.Y]` means the stamp never ran.
+    return "" if (v.startswith("[") and v.endswith("]")) else v
+
+def norm(v):
+    v = (v or "").strip()
+    if not v: return ""
+    return v if v.startswith("v") else "v" + v
+
+# THIS change's own spec half and wave.
+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,
+# so the two can never disagree about what the number is.
+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(os.path.join(fd, "spec.md"), "Version"))
+
+# Only a STAMPED base that DISAGREES blocks. No stamp, or no readable current version, is
+# 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 = ""
+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]
+
+print(json.dumps({
+    "ok": True, "cr_id": cr, "wave": wave,
+    "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,
+    "rebase_needed": rebase_needed,
+    "base_stamped": bool(base_version),
+    # 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),
+    # 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,
+}))
+PY
+}
+
+# ───────────────────────────── cr-recall-check ─────────────────────────────
+# The two mechanical refusals recall-delta needs, answered in one call from evidence on
+# disk rather than from anything a model read.
+#
+# MERGED. finalize-delta appends a Change History row carrying the CR id to spec.md, so
+# the id appearing in that file is the on-disk proof the merge ran. A merged change is
+# not recallable: the masters describe behaviour that includes it, and taking it back is
+# document surgery — the remedy is a NEW change that reverses it.
+#
+# DEPENDANTS. A wave is a dependency level: a higher wave is planned and built ON TOP of
+# the lower ones. Withdrawing a lower-wave change therefore strands every open change
+# above it. `depends_on` is stamped nowhere yet, so the wave is the only dependency signal
+# that actually exists, and it is the conservative one — same-wave changes are independent
+# by definition and are never counted here.
+cmd_cr_recall_check() {
+    local cr_id="" feature_dir_arg=""
+    while [ $# -gt 0 ]; do
+        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 ;;
+            *) echo "cr-recall-check: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -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'
+import json, os, re
+fd = os.environ["AW_FD"]; cr = os.environ["AW_CR"]
+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
+
+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})
+
+print(json.dumps({
+    "ok": True, "cr_id": cr, "exists": os.path.isdir(cr_dir), "wave": wave,
+    "merged": merged, "merge_evidence": evidence,
+    "dependants": dependants,
+    "dependant_ids": ", ".join("%s (wave %d)" % (x["cr_id"], x["wave"]) for x in dependants),
+    "dependant_count": len(dependants),
+    "has_dependants": len(dependants) > 0,
+}))
+PY
+}
+
+# ──────────────────── plan-gate-stamp / plan-gate-check ────────────────────
+# THE RECEIPT THAT analyze-plan PASSED, and over WHICH BYTES.
+#
+# 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
+# lane gates test that the plan FILE EXISTS and nothing more, so `plan` → edit spec.md →
+# `implement` generated from a plan that was never held against the spec it now contradicts.
+#
+# WHY NOT COMPARE THE PLANS' `**Version**:` HEADERS. They cannot answer this. version-stamp
+# moves spec.md, backend-plan.md and frontend-plan.md to the same number in LOCKSTEP at
+# close-delta, whether or not a plan was re-derived — close-delta says so itself ("a plan
+# header stamped here is stating the version the slice ships as, not that the plan was
+# re-derived for it"). Comparing them reads equal always, which is worse than not checking.
+#
+# 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.
+#
+# 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.
+_plan_gate_file() { printf '%s/.aw-plan-gate.json' "$1"; }
+
+cmd_plan_gate_stamp() {
+    local feature_dir_arg="" spec_version="" mode="master"
+    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 ;;
+        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
+}
+
+cmd_plan_gate_check() {
+    local feature_dir_arg=""
+    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 ;;
+            *) 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
 }
 
@@ -3547,25 +4306,39 @@ PY
 # nobody at all and sat at v1.0 forever.
 # Idempotent: re-stamping the same version reports `unchanged`, writes nothing.
 # Only the value moves; any trailing inline comment on the header line is kept.
+#
+# WITH --cr-id IT ALSO COMPLETES THAT CHANGE'S CHANGE HISTORY ROW. finalize-delta appends
+# the row when it MERGES, one stage before the number exists — so it writes `(pending)` in
+# the Version cell and this fills it in, at the same instant and by the same mechanism as
+# the headers. The alternative, which this replaces, was for the merge to write
+# version-read's `next_version`: a PREDICTION of what close-delta would bump to. A change
+# that merged and never closed — an abandoned run, a red analyze-slice, an un-merge — then
+# left spec.md permanently asserting a version that was never issued, in the document the
+# kit calls living truth. domain-model.md was always held to the rule this now applies to
+# spec.md: the row and its version land together, or the row carries a number nothing else
+# agrees with.
 cmd_version_stamp() {
-    local version="" feature_dir_arg=""
+    local version="" feature_dir_arg="" cr_id=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --version) version="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "version-stamp --version <vX.Y> [--feature-dir <path>]"; return 0 ;;
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --help|-h) echo "version-stamp --version <vX.Y> [--feature-dir <path>] [--cr-id <id>]"; return 0 ;;
             *) echo "version-stamp: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     [ -n "$version" ] || { echo "version-stamp: --version required" >&2; return 1; }
+    cr_id=$(_cr_id_token "$cr_id")
     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 "version-stamp: no feature set and no --feature-dir" >&2; return 1; }
     [[ "$fd" != /* ]] && fd="$repo_root/$fd"
-    AW_FD="$fd" AW_VER="$version" python3 - <<'PY'
+    AW_FD="$fd" AW_VER="$version" AW_CR="$cr_id" python3 - <<'PY'
 import json, os, re
 fd = os.environ["AW_FD"]; ver = os.environ["AW_VER"].strip()
+cr = os.environ.get("AW_CR", "").strip()
 stamped, unchanged, missing, no_header = [], [], [], []
 # First `**Version**: <value>` line only — that is the header. The Change History
 # table's `| Version |` column head does not match this pattern.
@@ -3589,9 +4362,41 @@ for name in ("spec.md", "backend-plan.md", "frontend-plan.md", "design.md", "des
     open(p, "w", encoding="utf-8").write(
         src[:m.start()] + m.group(1) + ver + m.group(3) + src[m.end():])
     stamped.append(name)
+
+# THE CHANGE HISTORY ROW, completed with the number the headers just took. The row is
+# found by its CR cell, not by position: rows are appended newest-last and a feature may
+# carry many, so "the last row" would be right only until two changes were open at once.
+# Only a cell still reading `(pending)` is written — a row already carrying a version
+# belongs to a change that closed, and re-stamping it would rewrite history.
+row_filled = False
+row_version = ""
+if cr:
+    p = os.path.join(fd, "spec.md")
+    if os.path.isfile(p):
+        src = open(p, encoding="utf-8").read()
+        out_lines, changed = [], False
+        for line in src.splitlines(True):
+            # A table row mentioning this CR whose FIRST cell is the pending marker.
+            if (not changed) and cr in line and line.lstrip().startswith("|"):
+                cells = line.split("|")
+                if len(cells) > 2 and cells[1].strip().lower() in ("(pending)", "pending", "—", "-", ""):
+                    row_version = cells[1].strip()
+                    cells[1] = " %s " % ver
+                    line = "|".join(cells)
+                    changed = True
+            out_lines.append(line)
+        if changed:
+            open(p, "w", encoding="utf-8").write("".join(out_lines))
+            row_filled = True
+
 print(json.dumps({"ok": True, "version": ver, "stamped": stamped,
                   "unchanged": unchanged, "missing": missing,
-                  "no_header": no_header, "count": len(stamped)}))
+                  "no_header": no_header, "count": len(stamped),
+                  # Whether the merge's pending row was completed. False with a --cr-id is
+                  # the ordinary outcome for a re-run (already filled) and for a change
+                  # whose merge predates the pending convention.
+                  "cr_id": cr, "history_row_filled": row_filled,
+                  "history_row_was": row_version}))
 PY
 }
 
@@ -3634,9 +4439,15 @@ case "$sub" in
     cr-activate)      cmd_cr_activate "$@" ;;
     cr-wave)          cmd_cr_wave "$@" ;;
     cr-archive)       cmd_cr_archive "$@" ;;
+    cr-recall-check)  cmd_cr_recall_check "$@" ;;
+    cr-merge-check)   cmd_cr_merge_check "$@" ;;
+    cr-snapshot)      cmd_cr_snapshot "$@" ;;
+    context-version-bump) cmd_context_version_bump "$@" ;;
     context-paths)    cmd_context_paths "$@" ;;
     model-scaffold)   cmd_model_scaffold "$@" ;;
     version-stamp)    cmd_version_stamp "$@" ;;
+    plan-gate-stamp)  cmd_plan_gate_stamp "$@" ;;
+    plan-gate-check)  cmd_plan_gate_check "$@" ;;
     checklist-read)   cmd_checklist_read "$@" ;;
     checklist-apply)  cmd_checklist_apply "$@" ;;
     detect-project)   cmd_detect_project "$@" ;;