aw-spec-cli 0.1.15 → 0.1.17

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

@@ -44,78 +44,11 @@
 #                    (the FILE signals for "does this lane exist"; resolve-tech carries the rule signal)
 #   list-features    [--preselect <name>] [--bundle <dir>]  -> {features[], names[], count, select_options[], sentinel}   (specs/ ∪ OKF aggregates)
 #   set-feature      --feature <name>              -> {feature, feature_dir, spec_file, existed, created, spec_exists}
-#   version-read     [--feature-dir <path>]        -> {feature, version, active_change, exists}
-#   version-init     [--feature-dir <path>] [--bootstrap]
-#                                                  -> {feature, version, active_change, created, bootstrap_pending}
-#                    (create active_version.json v1.0; --bootstrap marks a first draft in progress)
-#   spec-check       [--feature-dir <path>]        -> {ok, state, version, doc_version, body_changed, spec_sha256, error}
-#                    (the ledger tripwire: clean | unstamped | ledgered_edit | header_behind |
-#                     unrowed_edit | unledgered_edit | rollback | no_ledger | delta_open.
-#                     A recorded edit is one with a version ROW above the recorded version — the
-#                     **Version** header is a claim, not evidence. ok:false on an edit that skipped
-#                     the Change History row, which is the ledger's only silent case)
-#   spec-stamp       [--feature-dir <path>]        -> {ok, state, version, spec_sha256, header_rewritten}
-#                    (record spec.md's hash as the new baseline; used after a bootstrap authors it.
-#                     The version recorded is the highest of the recorded one, the document header
-#                     and the newest ledger row, and a header behind that is rewritten up to it)
-#   ledger-append    [--feature-dir <path>] --ids <ids> [--summary <text>]
-#                                                  -> {ok, version, previous, row, spec_sha256}
-#                    (bump, append the Change History row, stamp the **Version** header and
-#                     re-hash — ONE call, so a row can never exist without its hash)
-#   story-refs       [--feature-dir <path>] [--ids <FR-001, BR-002>]
-#   slice-mode       [--input <text>]              -> {strategy, guidance, single, note}
-#                    (the strategy word off the front of the launch line, and the guidance
-#                     left behind it — `single-run` asks for one story over the work set)
-#   backlog-plan     --groups <json> --work <csv> [--strategy single|auto] [--ceiling <n>]
-#                    [--plan --approved <ids> --version <v>]
-#   story-stamp      --story <id> [--ids <csv>] [--version <v>] [--follows <id>]
-#                    [--depends-on <csv>] [--wave <n>]
-#   ledger-read      [--feature-dir <path>]      -> {rows, work_csv, work_source, gap, ...}
-#   story-plan-check [--story <id>] [--input <text>] [--feature-dir <p>]
-#                                                  -> {resolved, needs_pick, open_ids, story, story_open, status_msg,
-#                                                      exercises_csv, constraints_csv, stale_csv, stale_note,
-#                                                      be_doc_path/fe_doc_path, be_doc_exists/fe_doc_exists,
-#                                                      be_next_pass/fe_next_pass, be_last_pass/fe_last_pass,
-#                                                      be_pass_tmp/fe_pass_tmp,
-#                                                      be_doc_spec_version/fe_doc_spec_version, be_doc_stale/fe_doc_stale,
-#                                                      legacy_doc, legacy_doc_exists, if_tmp, adr_path, if_path}
-#                    (resolve WHICH story a story-plan run works on + everything its gates read)
-#   story-plan-doc   --story <id> --pass-file <p> [--lane backend|frontend] [--spec-version <v>]
-#                                                  -> {ok, doc, lane, pass, created}
-#                    (the only writer of stories/<ID>/story-<lane>-plan.md: scaffold on first use, append
-#                     the pass under a script-written '## Design pass N' header, stamp frontmatter)
-#   log-append       --log adr|interfaces --entries-file <p> [--status <s>]
-#                                                  -> {ok, appended, ids_csv, unknown_ids_csv, bad_supersedes_csv}
-#                    (append-only feature logs; the script assigns ADR-nnn/IF-nnn ids, dates and
-#                     status — entries arrive as '## IF-NEW — <title>' blocks, 'none' is a no-op)
-#                                                  -> {covered_csv, affected[], affected_csv, story_csv,
-#                                                      in_flight_csv, any, any_in_flight, story_count}
-#                    (which requirements have OPEN stories against them; no --ids = all of them.
-#                     Read-only frontmatter scan — the backlog's view of what is being built)
-#   spec-coverage    [--feature-dir <path>]        -> {written, requirements, stories, uncovered_csv, delivered_csv}
-#                    (regenerate the spec's AW:COVERAGE block — every FR-/BR- and the stories
-#                     delivering it. Fenced out of the hash and the diff, so writing it is not
-#                     a spec edit. Called by specify, user-story and sync-stories alike)
-#   spec-preserve    --disturbing <csv> --approved <csv>  -> {preserve_csv, preserve_count, approved_csv}
-#                    (the complement: which disturbed requirements were NOT approved for change)
-#   feature-paths                                  -> {feature, feature_dir, spec_file, design_file, spec_exists, design_exists,
-#                                                      backend_plan_file, frontend_plan_file, backend_plan_exists, frontend_plan_exists}
-#   plan-check       --doc <path> [--feature-dir <p>] -> {state, derived_version, current_version, changed_csv, changed_summary, body_changed}
-#                    (the plan doc's derivation record vs the spec ledger: fresh | untracked |
-#                     clean | behind | edited | edited_behind; behind's changed_csv is the update's work list)
-#   plan-stamp       --doc <path> [--feature-dir <p>] [--ids <csv>] [--note <text>] [--no-row]
-#                                                  -> {ok, version, row, warnings[]}
-#                    (the ONLY writer of a plan doc's version identity: **Version** header := the
-#                     spec version derived from, a Change History row unless --no-row, and the body
-#                     hash into the doc's own .aw-plan-track.<doc>.json — refuses, writing no baseline, when the doc has
-#                     no Change History section left)
-#   gate-result      --gate <name> --ok <true|false> [--feature-dir <p>] [--spec-version <v>]
-#                    [--story <id>] [--report <path>] [--out <path>] [--gap-count <n>]
-#                    [--gap-refs <csv>] [--note <text>] [--field k=v]...
-#                                                  -> {ok, result_file, status, gap_count}
-#                    (the machine-readable verdict every analyze gate writes beside its markdown
-#                     report, so CI branches on a value instead of prose. `ok` means the file was
-#                     WRITTEN; the verdict is `status`. Fixed core keys + gate-specific --field)
+#   version-read     [--feature-dir <path>]        -> {feature, version, active_change, exists, bootstrap_pending}
+#   version-init     [--feature-dir <path>] [--bootstrap]  -> {…, created, bootstrap_pending}   (create active_version.json v1.0; --bootstrap marks a FIRST draft in progress)
+#   version-bootstrap-done [--feature-dir <path>]  -> {…, cleared}   (the ONLY clearer of the --bootstrap marker; call it when the first draft is finished)
+#   feature-paths                                  -> {feature, feature_dir, spec_file, backend_plan, frontend_plan, *_exists,
+#                                                      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[]}
 #   detect-project                                 -> {scaffolded, markers[]}
@@ -133,8 +66,12 @@
 #                                                  -> {ok, exists, issues, placeholders, placeholder_check, version_body, version_report, version_match, bad_dates}
 #   agent-context-update [--plan <path>]           -> {ok, ran, message}
 #
-#   design-scaffold  --feature-dir <path> [--template <name>]
-#                                                  -> {feature_dir, design_doc, created, override_active, template, template_source}
+#   plan-scaffold    --feature-dir <path> [--lane backend|frontend|service|ui] [--template <name>]
+#                    (alias: design-scaffold)      -> {feature_dir, plan_doc, design_doc, lane, created, migrated, override_active, template, template_source}
+#                    (backend|frontend write backend-plan.md / frontend-plan.md and MIGRATE a
+#                     legacy design.md / design.ui.md by renaming it; service|ui keep the legacy names)
+#   delta-plan-scaffold --cr-id <id> [--lane backend|frontend] [--feature-dir <path>] [--template <name>]
+#                                                  -> {cr_id, cr_dir, lane, delta_plan, created, migrated, override_active, template}
 #   (design-extract / design-reconcile / design-paths are RETIRED — the path-tagged
 #    four-document model is gone. "Which files is this slice made of" is now an OKF
 #    query: aw-xref concept-paths / concept-upsert --merge.)
@@ -142,8 +79,20 @@
 #   test-run         [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail}
 #   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>]
-#                                                  -> {cr_dir, delta_spec, delta_design, created}
+#   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-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}
+#   cr-paths         --cr-id <id> [--feature-dir <path>]
+#                                                  -> {cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan,
+#                                                      wave, predecessor_files[], predecessor_specs[], predecessor_docs[],
+#                                                      sibling_files[], domain_model}
+#   cr-overlap       --cr-id <id> [--feature-dir <path>]
+#                                                  -> {aggregates[], overlaps[], overlap_count, predecessor_overlaps,
+#                                                      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}
 #
@@ -231,8 +180,7 @@ cmd_resolve_domain() {
 # stack_mismatch when it is not a stack this repo declares, because a map pinned to the
 # wrong corpus is how a Java project ends up being handed C# rules.
 cmd_resolve_tech() {
-    local command_name="aw-spec-plan"   # inert: every caller passes --command. Kept current
-                                        # so a hand-run defaults to a LIVE command, not a dead one.
+    local command_name="aw-spec-design"
     while [ $# -gt 0 ]; do
         case "$1" in
             --command) command_name="$2"; shift 2 ;;
@@ -560,7 +508,7 @@ cmd_create_checklist() {
     cat > "$checklist_file" <<EOF
 # Delta-Spec Quality Checklist: $feature_name — $cr_id
 
-**Purpose**: Validate the CHANGE's delta-spec before proceeding to design
+**Purpose**: Validate the CHANGE's delta-spec before proceeding to plan
 **Created**: $today
 **Change**: [delta-spec.md](../delta-spec.md)
 
@@ -604,14 +552,14 @@ cmd_create_checklist() {
 
 - This checklist grades the DELTA DOCUMENT only. Accuracy against the master spec
   (id continuity, conflicts with existing requirements) is checked downstream by
-  /appweaver analyze-delta-design.
-- Items marked incomplete require delta-spec updates before /appweaver design
+  /appweaver analyze-plan-delta.
+- Items marked incomplete require delta-spec updates before /appweaver plan
 EOF
     else
     cat > "$checklist_file" <<EOF
 # Specification Quality Checklist: $feature_name
 
-**Purpose**: Validate specification completeness and quality before proceeding to design
+**Purpose**: Validate specification completeness and quality before proceeding to plan
 **Created**: $today
 **Feature**: [spec.md](../spec.md)
 
@@ -628,7 +576,7 @@ EOF
 - [ ] Requirements are testable and unambiguous
 - [ ] Success criteria are measurable
 - [ ] Success criteria are technology-agnostic (no implementation details)
-- [ ] Every requirement carries a stable id
+- [ ] All acceptance scenarios are defined
 - [ ] Edge cases are identified
 - [ ] Scope is clearly bounded
 - [ ] Dependencies and assumptions identified
@@ -649,14 +597,14 @@ EOF
 
 ## Feature Readiness
 
-- [ ] Every functional requirement is stated in EARS form, which is its acceptance criterion
-- [ ] The requirements cover the aggregate's primary flows, so a story can be sliced from them without inventing behaviour
+- [ ] All functional requirements have clear acceptance criteria
+- [ ] User scenarios cover primary flows
 - [ ] Feature meets measurable outcomes defined in Success Criteria
 - [ ] No implementation details leak into specification
 
 ## Notes
 
-- Items marked incomplete require spec updates before /appweaver design
+- Items marked incomplete require spec updates before /appweaver plan
 EOF
     fi
 
@@ -876,6 +824,345 @@ cmd_lane_probe() {
     _aw_stack_py probe "${fwd[@]}"
 }
 
+# ─────────────────────────────── list-contexts ─────────────────────────────
+# Enumerate the BOUNDED CONTEXTS a user can pick. A bounded context is a directory
+# under specs/ that holds features rather than being one — so the two are told apart
+# by the only reliable evidence on disk: a directory carrying its OWN spec.md is a
+# feature, one that does not is a context. No marker file, nothing to keep in sync.
+#
+# A pre-context repo has its features flat under specs/, and every one of them
+# therefore reads as a feature, not a context — correct, and reported as
+# `legacy_features` so the caller can say so out loud instead of showing an empty
+# list and looking broken.
+cmd_list_contexts() {
+    local preselect=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --preselect) preselect="$2"; shift 2 ;;
+            --help|-h) echo "list-contexts [--preselect <name>]  -> {contexts[], names[], count, select_options[], sentinel, legacy_features[]}"; return 0 ;;
+            *) echo "list-contexts: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local active_rel; active_rel=$(read_context_json_context_directory "$repo_root")
+    [ -n "$active_rel" ] && [ ! -d "$repo_root/$active_rel" ] && active_rel=""
+    AW_SPECS="$repo_root/specs" AW_PRESELECT="$preselect" AW_ACTIVE="$active_rel" python3 - <<'PY'
+import json, os
+base = os.environ["AW_SPECS"]
+pre  = os.environ.get("AW_PRESELECT", "").strip()
+active_rel = os.environ.get("AW_ACTIVE", "").strip()
+active = os.path.basename(active_rel.rstrip("/")) if active_rel else ""
+sentinel = "+ Create a new bounded context"
+contexts, names, legacy = [], [], []
+seen = set()
+if os.path.isdir(base):
+    for name in sorted(os.listdir(base)):
+        d = os.path.join(base, name)
+        if not os.path.isdir(d):
+            continue
+        # Its own spec.md => this IS a feature, from the pre-context flat layout.
+        if os.path.isfile(os.path.join(d, "spec.md")):
+            legacy.append(name)
+            continue
+        # EVERY subdirectory is a feature of this context, whether or not specify has
+        # run yet — select-feature creates the directory first and spec.md arrives
+        # later, so counting only specified ones would report a feature the user just
+        # created as absent, and disagree with list-features about what exists.
+        feats = sorted(n for n in os.listdir(d) if os.path.isdir(os.path.join(d, n)))
+        specified = [n for n in feats if os.path.isfile(os.path.join(d, n, "spec.md"))]
+        names.append(name); seen.add(name.lower())
+        contexts.append({
+            "name": name,
+            "dir": "specs/" + name,
+            "features": feats,
+            "feature_count": len(feats),
+            "specified_count": len(specified),
+            "has_domain_model": os.path.isfile(os.path.join(d, "domain-model.md")),
+        })
+opts = list(names)
+# Inject a not-yet-existing --preselect so preselect_from can create-or-select in
+# one round trip, exactly as list-features does for the direct-argument fast path.
+if pre and pre.lower() not in seen:
+    opts.append(pre)
+opts.append(sentinel)
+# scope_ok answers ONE question for select-feature: is it safe to resolve a feature
+# directory right now? Two states are safe — a context is active (features nest inside
+# it), or the repo has no contexts at all (the flat pre-context layout). The unsafe
+# state is contexts existing with none selected: the feature would silently land at
+# specs/<Feature>, outside every context, which is the quiet wrongness the lane model
+# exists to prevent. The engine has no compound conditions, so the AND is computed here.
+scope_ok = bool(active) or len(names) == 0
+scope_message = "" if scope_ok else (
+    "%d bounded context(s) exist (%s) but none is selected. Run "
+    "/appweaver select-bounded-context first — without it a new feature is created at "
+    "specs/<Feature>, outside every context and with no domain model to share."
+    % (len(names), ", ".join(names)))
+print(json.dumps({"contexts": contexts, "names": names, "count": len(names),
+                  "select_options": opts, "sentinel": sentinel,
+                  "legacy_features": legacy, "legacy_count": len(legacy),
+                  "active": active, "active_dir": active_rel,
+                  # The specs/ subtree features resolve in — the active context, or
+                  # plain "specs" on a flat repo. Always populated, so a caller can
+                  # name the location without branching on whether a context is set.
+                  "feature_base": active_rel or "specs",
+                  "scope_ok": scope_ok, "scope_message": scope_message}))
+PY
+}
+
+# ─────────────────────────────── set-context ───────────────────────────────
+# Create-or-select a bounded context under specs/ and persist it as the active one
+# (.appweaver/context.json). Idempotent: selecting an existing context re-points the
+# file; a new one is created. The context directory is created but domain-model.md is
+# NOT — that document is authored by specify, which is the only writer of the model,
+# and an empty placeholder would read as "the model exists" to every later gate.
+cmd_set_context() {
+    local raw=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --context) raw="$2"; shift 2 ;;
+            --help|-h) echo "set-context --context <name>   (create-or-select the bounded context under specs/)"; return 0 ;;
+            *) echo "set-context: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$raw" ] || { echo "set-context: --context is required" >&2; return 1; }
+
+    # Same PascalCase normalization as set-feature: these are sibling identifiers in
+    # one path, so "order management" and "Order Management" cannot produce two dirs.
+    local cleaned; cleaned=$(echo "$raw" | sed -E 's/[^A-Za-z0-9]+/ /g; s/^ +| +$//g')
+    local context; context=$(_pascal "$cleaned")
+    if ! [[ "$context" =~ ^[A-Za-z][A-Za-z0-9]*$ ]]; then
+        echo "set-context: '$raw' is not a valid bounded context name (need a letter-led alphanumeric name, e.g. Sales)" >&2
+        return 1
+    fi
+
+    local repo_root; repo_root=$(get_repo_root)
+    local context_dir_rel="specs/$context"
+    local context_dir="$repo_root/$context_dir_rel"
+    # Refuse to shadow a flat feature: specs/Order/spec.md means Order is a feature,
+    # and turning it into a context would put specs/Order/<Feature>/ underneath a
+    # spec.md that already claims that directory.
+    if [ -f "$context_dir/spec.md" ]; then
+        echo "set-context: refusing — 'specs/$context' is a feature (it has its own spec.md), not a bounded context. Pick another name, or move that feature under a context first." >&2
+        return 1
+    fi
+    local existed=false; [ -d "$context_dir" ] && existed=true
+    mkdir -p "$context_dir"
+
+    mkdir -p "$repo_root/.appweaver"
+    local cj="$repo_root/.appweaver/context.json"
+    if command -v jq >/dev/null 2>&1; then
+        jq -cn --arg c "$context" --arg d "$context_dir_rel" '{context:$c,context_directory:$d}' > "$cj"
+    else
+        printf '{"context":"%s","context_directory":"%s"}\n' \
+            "$(json_escape "$context")" "$(json_escape "$context_dir_rel")" > "$cj"
+    fi
+
+    local created=true; [ "$existed" = true ] && created=false
+    local dm_exists=false; [ -f "$context_dir/domain-model.md" ] && dm_exists=true
+    printf '{"context":"%s","context_dir":"%s","domain_model":"%s","existed":%s,"created":%s,"domain_model_exists":%s,"written":true}\n' \
+        "$(json_escape "$context")" "$(json_escape "$context_dir_rel")" \
+        "$(json_escape "$context_dir_rel/domain-model.md")" "$existed" "$created" "$dm_exists"
+}
+
+# ══════════════════════ domain model — context-level helpers ════════════════
+# The bounded context that owns a feature's domain model. specs/<Ctx>/<Feat> puts the
+# model one level up at specs/<Ctx>/; a flat specs/<Feat> falls back to specs/ as the
+# implicit single context, so a pre-context repo still resolves exactly one model
+# rather than none.
+_context_dir_for_feature() {   # $1 = abs feature dir, $2 = repo_root; prints ABS context dir
+    local fd="$1" repo_root="$2"
+    local parent; parent=$(dirname "$fd")
+    # A feature directly under specs/ has no context of its own -> specs/ IS the context.
+    if [ "$parent" = "$repo_root/specs" ] || [ "$parent" = "$repo_root" ]; then
+        printf '%s' "$repo_root/specs"
+    else
+        printf '%s' "$parent"
+    fi
+}
+
+# Four random hex characters, so two changes opened in the same second cannot collide
+# on one id. Falls back through the sources a minimal container might lack.
+_rand_suffix() {
+    if [ -r /dev/urandom ]; then
+        LC_ALL=C tr -dc 'a-f0-9' < /dev/urandom 2>/dev/null | head -c 4 && return 0
+    fi
+    printf '%04x' $(( (RANDOM << 8) ^ RANDOM ^ $$ ))
+}
+
+# Read one top-level field out of a compact JSON object on stdin. Used to pluck a
+# single value from a helper's output without a second parse in every caller.
+_json_field() {   # $1 = key
+    AW_KEY="$1" python3 -c "
+import json,os,sys
+try: d=json.load(sys.stdin)
+except Exception: d={}
+v=d.get(os.environ['AW_KEY'],'')
+print('' if v is None else v)" 2>/dev/null
+}
+
+# Set or insert a '**<Name>**: <value>' header line. Scripts own ids, dates, versions
+# and the wave; the model never writes them, so every one of those lands through here.
+# Idempotent: an existing line is replaced in place, a missing one is inserted after
+# the title so the header block stays together.
+_stamp_header() {   # $1 = file, $2 = header name, $3 = value
+    [ -f "$1" ] || return 0
+    AW_F="$1" AW_NAME="$2" AW_VAL="$3" python3 - <<'PY'
+import os, re
+p = os.environ["AW_F"]; name = os.environ["AW_NAME"]; val = os.environ["AW_VAL"]
+try: text = open(p, encoding="utf-8").read()
+except Exception: raise SystemExit(0)
+line = "**%s**: %s" % (name, val)
+pat = re.compile(r"^\*\*%s\*\*:.*$" % re.escape(name), re.M)
+if pat.search(text):
+    text = pat.sub(lambda _m: line, text, count=1)
+else:
+    lines = text.split("\n")
+    at = 0
+    for i, l in enumerate(lines):
+        if l.startswith("# "):
+            at = i + 1
+            break
+    lines.insert(at, "")
+    lines.insert(at + 1, line)
+    text = "\n".join(lines)
+open(p, "w", encoding="utf-8").write(text)
+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.
+_max_open_wave() {   # $1 = abs context dir
+    AW_CTX="$1" python3 - <<'PY'
+import os, re, glob
+ctx = os.environ["AW_CTX"]
+best = 0
+for f in glob.glob(os.path.join(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)
+    if m: best = max(best, int(m.group(1)))
+print(best if best >= 1 else 1)
+PY
+}
+
+# The change id out of whatever the caller passed. A user_select hands back the whole
+# option LABEL ("CR-… · wave 2 · Add discount tiers"), and a change id never contains
+# whitespace — so the first token is the id whether the caller passed a bare id or a
+# label the user picked off a menu.
+_cr_id_token() {   # $1 = raw --cr-id value
+    printf '%s' "${1%%[[:space:]]*}"
+}
+
+# One change's wave, read from the documents that carry it: the delta-spec first, then
+# the model delta. Both are stamped together, so either answers; 1 is the floor for a
+# change opened before waves existed.
+_wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
+    local fd="$1" cr="$2" repo_root="$3" w=""
+    local dspec="$fd/changes/$cr/delta-spec.md"
+    local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
+    local dmodel="$ctx_dir/domain-model.$cr.delta.md"
+    for f in "$dspec" "$dmodel"; do
+        [ -f "$f" ] || continue
+        w=$(sed -n -E 's/^\*\*Wave\*\*:[[:space:]]*([0-9]+).*$/\1/p' "$f" | head -1)
+        [ -n "$w" ] && break
+    done
+    case "$w" in ''|*[!0-9]*) w=1 ;; esac
+    [ "$w" -ge 1 ] 2>/dev/null || w=1
+    printf '%s' "$w"
+}
+
+# ─────────────────────────────── context-paths ─────────────────────────────
+# Everything specify needs to know about the domain model of the context it is working
+# in: where the master is, whether it exists yet, and EVERY open delta model beside it.
+#
+# The pending list is the point. specify authors against the master PLUS what other open
+# deltas have already proposed, so an overlap is designed around at authoring time rather
+# than discovered at merge time. pending_files is a flat path list for build_context's
+# `context_from:`.
+cmd_context_paths() {
+    local feature_dir_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --help|-h) echo "context-paths [--feature-dir <path>]  -> {context, context_dir, domain_model, domain_model_exists, pending[], pending_files[], max_wave, next_wave}"; return 0 ;;
+            *) echo "context-paths: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    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 "context-paths: 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_CTX="$ctx_dir" AW_ROOT="$repo_root" python3 - <<'PY'
+import json, os, re, glob
+ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
+def rel(p): return os.path.relpath(p, root)
+name = os.path.basename(ctx.rstrip("/"))
+# specs/ itself is the implicit single context of a pre-context repo — it has a model
+# but no context NAME, and saying so is what keeps the flat layout honest.
+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"))):
+    base = os.path.basename(f)
+    cr = base[len("domain-model."):-len(".delta.md")]
+    wave = 1
+    try:
+        m = re.search(r"^\*\*Wave\*\*:\s*(\d+)", open(f, encoding="utf-8").read(), re.M)
+        if m: wave = int(m.group(1))
+    except Exception: pass
+    pending.append({"cr_id": cr, "file": rel(f), "wave": wave})
+    files.append(rel(f))
+waves = [p["wave"] for p in pending]
+print(json.dumps({
+    "context": context,
+    "context_dir": rel(ctx),
+    "domain_model": rel(master),
+    "domain_model_exists": os.path.isfile(master),
+    "pending": pending,
+    "pending_files": files,
+    "pending_count": len(pending),
+    "max_wave": max(waves) if waves else 0,
+    # What a new delta opened right now would be stamped with: alongside whatever is
+    # already in flight, never implicitly behind it.
+    "next_wave": max(waves) if waves else 1,
+}))
+PY
+}
+
+# ─────────────────────────────── model-scaffold ────────────────────────────
+# Copy the domain-model template into the context on the BOOTSTRAP path. Idempotent and
+# non-destructive: an existing model is never overwritten, because after the first
+# specify the model is amended by delta and merge, never re-scaffolded.
+cmd_model_scaffold() {
+    local feature_dir_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --help|-h) echo "model-scaffold [--feature-dir <path>]"; return 0 ;;
+            *) echo "model-scaffold: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    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 "model-scaffold: 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")
+    mkdir -p "$ctx_dir"
+    local model="$ctx_dir/domain-model.md" tpl="" created=false
+    if [ ! -f "$model" ]; then
+        tpl=$(resolve_template "domain-model-template" "$repo_root") || true
+        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$model"; else touch "$model"; fi
+        created=true
+    fi
+    printf '{"context_dir":"%s","domain_model":"%s","template":"%s","created":%s,"exists":true}\n' \
+        "$(json_escape "${ctx_dir#$repo_root/}")" "$(json_escape "${model#$repo_root/}")" \
+        "$(json_escape "$tpl")" "$created"
+}
+
 # ─────────────────────────────── list-features ─────────────────────────────
 # Enumerate the aggregates a user can pick as the active feature. Two sources,
 # MERGED (deduped by feature name, case-insensitive):
@@ -908,9 +1195,14 @@ cmd_list_features() {
     if [ -d "$bundle" ] && [ -f "$invpy" ] && command -v python3 >/dev/null 2>&1; then
         okf_json=$(python3 "$invpy" list-aggregates --bundle "$bundle" 2>/dev/null) || okf_json="{}"
     fi
-    AW_SPECS="$repo_root/specs" AW_PRESELECT="$preselect" AW_OKF="$okf_json" python3 - <<'PY'
+    # Features are enumerated from the ACTIVE BOUNDED CONTEXT's directory when one is
+    # set, and from specs/ itself when none is — so a context scopes the picker to its
+    # own features and a pre-context repo lists exactly what it always did.
+    local base_rel; base_rel=$(feature_base_rel "$repo_root")
+    AW_SPECS="$repo_root/$base_rel" AW_BASE_REL="$base_rel" AW_PRESELECT="$preselect" AW_OKF="$okf_json" python3 - <<'PY'
 import json, os, glob
 base = os.environ["AW_SPECS"]
+base_rel = os.environ.get("AW_BASE_REL", "specs")
 pre  = os.environ.get("AW_PRESELECT", "").strip()
 try:
     okf = json.loads(os.environ.get("AW_OKF", "{}") or "{}")
@@ -919,11 +1211,28 @@ except Exception:
 sentinel = "+ Create a new feature"
 feats, names = [], []
 seen = set()   # case-insensitive dedup key across both sources
+def is_context(d):
+    """A BOUNDED CONTEXT directory, not a feature: it holds features instead of
+    being one. Only reachable with no context active — inside a context, a feature
+    carries its own spec.md and never matches. Without this test a repo that has
+    contexts but has not selected one lists them as pickable features, and picking
+    one would scaffold a spec.md on top of a directory that already holds features."""
+    if os.path.isfile(os.path.join(d, "spec.md")):
+        return False
+    if os.path.isfile(os.path.join(d, "domain-model.md")):
+        return True
+    try:
+        return any(os.path.isfile(os.path.join(d, n, "spec.md")) for n in os.listdir(d))
+    except OSError:
+        return False
+
 if os.path.isdir(base):
     for name in sorted(os.listdir(base)):
         d = os.path.join(base, name)
         if not os.path.isdir(d):
             continue
+        if is_context(d):
+            continue
         ver, active_change = "", ""
         avf = os.path.join(d, "active_version.json")
         if os.path.isfile(avf):
@@ -934,7 +1243,7 @@ if os.path.isdir(base):
         names.append(name); seen.add(name.lower())
         feats.append({
             "name": name,
-            "dir": "specs/" + name,
+            "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
@@ -953,7 +1262,7 @@ for agg in (okf.get("aggregates") or []):
     names.append(nm); seen.add(nm.lower())
     feats.append({
         "name": nm,
-        "dir": "specs/" + nm,          # candidate slice (not yet created)
+        "dir": base_rel + "/" + nm,    # candidate slice (not yet created)
         "source": "okf",
         "has_spec": False,
         "adopted": False,
@@ -998,17 +1307,32 @@ cmd_set_feature() {
     fi
 
     local repo_root; repo_root=$(get_repo_root)
-    local feature_dir_rel="specs/$feature"
+    # The feature is created inside the ACTIVE BOUNDED CONTEXT when one is set, and
+    # directly under specs/ when none is. feature.json stores the resulting path, so
+    # every downstream caller reads a feature directory and never has to know which
+    # layout produced it — the nesting is invisible past this point.
+    local base_rel; base_rel=$(feature_base_rel "$repo_root")
+    local feature_dir_rel="$base_rel/$feature"
     local feature_dir="$repo_root/$feature_dir_rel"
+    # Refuse to scaffold a feature on top of a bounded context — the mirror of
+    # set-context's refusal to shadow a feature. Reachable when a repo has contexts
+    # but none is active, where the target resolves under a bare specs/.
+    if [ ! -f "$feature_dir/spec.md" ] && { [ -f "$feature_dir/domain-model.md" ] || \
+         { [ -d "$feature_dir" ] && [ -n "$(find "$feature_dir" -mindepth 2 -maxdepth 2 -name spec.md -print -quit 2>/dev/null)" ]; }; }; then
+        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
     local existed=false; [ -d "$feature_dir" ] && existed=true
     mkdir -p "$feature_dir"
     _persist_feature_json "$repo_root" "$feature_dir_rel"
 
     local created=true; [ "$existed" = true ] && created=false
     local spec_exists=false; [ -f "$feature_dir/spec.md" ] && spec_exists=true
-    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","existed":%s,"created":%s,"spec_exists":%s}\n' \
+    local context=""; [ "$base_rel" != "specs" ] && context="${base_rel#specs/}"
+    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","existed":%s,"created":%s,"spec_exists":%s,"context":"%s"}\n' \
         "$(json_escape "$feature")" "$(json_escape "$feature_dir_rel")" \
-        "$(json_escape "$feature_dir_rel/spec.md")" "$existed" "$created" "$spec_exists"
+        "$(json_escape "$feature_dir_rel/spec.md")" "$existed" "$created" "$spec_exists" \
+        "$(json_escape "$context")"
 }
 
 # ═══════════════════════════ active_version.json ════════════════════════════
@@ -1029,12 +1353,14 @@ _resolve_feature_dir() {   # $1 = --feature-dir arg (may be empty), $2 = repo_ro
     printf '%s' "$fd"
 }
 
-# Shared reader/mutator: op in {read,init,open,close}. Prints one JSON object.
-# op=open enforces the single-active-change guard: opening a DIFFERENT change while
-# one is already open fails (exit 3, ok:false) unless force ("1") is passed — this
-# stops a second concurrent CR on the same aggregate from silently overwriting the
-# first. (Concurrency is ACROSS features; changes to one feature are serialized.)
-_active_version() {   # $1 = abs feature_dir, $2 = op, $3 = cr_id (open only), $4 = force ("1" overrides open-guard), $5 = bootstrap ("1", init only)
+# Shared reader/mutator: op in {read,init,bootstrap-done,open,activate,close}. Prints one
+# JSON object.
+# MANY CHANGES MAY BE OPEN ON ONE FEATURE. open_changes[] is the record; active_change is
+# the most recently opened OR the one a later stage activated, and is kept correct for
+# every stage that still resolves "the" change through it. `force` is accepted and unused
+# on open — the guard it overrode is gone — and is kept so existing callers do not have to
+# change.
+_active_version() {   # $1 = abs feature_dir, $2 = op, $3 = cr_id (open/close), $4 = force (accepted, inert), $5 = bootstrap ("1", init only)
     AW_FD="$1" AW_OP="$2" AW_CR="${3:-}" AW_FORCE="${4:-}" AW_BOOT="${5:-}" python3 - <<'PY'
 import json, os, re, datetime, sys
 fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]; cr = os.environ.get("AW_CR", "")
@@ -1059,7 +1385,14 @@ def bump(v):
 
 d, existed = load()
 d.setdefault("feature", feature); d.setdefault("version", "v1.0"); d.setdefault("active_change", "")
+# Migrate pre-parallel state forward on read: a file written when only one change could
+# be open carries active_change and no list. Seed the list from it rather than reporting
+# zero open changes on a feature that has one.
+if "open_changes" not in d:
+    d["open_changes"] = [d["active_change"]] if d.get("active_change") else []
 out = {"feature": d["feature"], "version": d["version"], "active_change": d.get("active_change", ""),
+       "open_changes": list(d.get("open_changes") or []),
+       "open_count": len([c for c in (d.get("open_changes") or []) if c]),
        "exists": existed, "path": "active_version.json", "ok": True}
 if op == "read":
     pass
@@ -1067,13 +1400,10 @@ elif op == "init":
     # BOOTSTRAP IN PROGRESS, and ONLY when the caller says it is authoring a first draft
     # (--bootstrap). A first run that dies after writing spec.md but before its ledger row
     # leaves a document that looks, to the next FRESH invocation, exactly like a spec
-    # written before the ledger existed — `unstamped`, which passes. specify then took the
-    # EXTEND path and applied the same input a second time, on top of a v1.0 that was never
-    # finished, and bumped it to v1.1. Checkpoint resume was always fine; a fresh invocation
-    # was not, and nothing distinguished the two. This marker does. Only ledger-ids clears
-    # it, and only once the v1.0 row actually names ids read out of the finished document —
-    # so a bootstrap whose row never landed is re-run and REPAIRED rather than being frozen
-    # behind a v1.1 that can never go back and fix it.
+    # written before the ledger existed — which passes. specify then took the EXTEND path
+    # and applied the same input a second time, on top of a v1.0 that was never finished.
+    # Checkpoint resume was always fine; a fresh invocation was not, and nothing
+    # distinguished the two. This marker does.
     #
     # The flag is the CALLER's, not this primitive's: adopt inits the same file after
     # reversing a spec out of existing code, and a marker raised there would tell the next
@@ -1082,25 +1412,68 @@ elif op == "init":
         d["bootstrap_pending"] = True
     save(d)
     out["created"] = (not existed)
+elif op == "bootstrap-done":
+    # THE ONLY THING THAT CLEARS THE MARKER, called by the phase that raised it once the
+    # first draft is actually finished. It is a separate op, not a side effect of writing
+    # the spec, because "the file exists" is exactly the signal that could not be trusted:
+    # a crashed run leaves one too. Idempotent — clearing a marker that is already down is
+    # the ordinary case on a re-run, and is not an error.
+    was = bool(d.pop("bootstrap_pending", None))
+    save(d)
+    out["cleared"] = was
 elif op == "open":
-    cur = d.get("active_change", "")
-    if cur and cur != cr and force != "1":       # a DIFFERENT change is already open -> refuse
+    # MANY CHANGES MAY BE OPEN AT ONCE. Every specify call on an established feature
+    # opens its own change, so the record is the open_changes LIST; the single-active
+    # guard that used to refuse a second one is gone.
+    #
+    # active_change is still written, and is the MOST RECENTLY OPENED. Every stage
+    # downstream of specify still resolves "the" change through that field, so keeping
+    # it correct is what lets parallel AUTHORING land before those stages learn to take
+    # an explicit --cr-id. Reading open_changes is how a caller sees the rest.
+    opens = [c for c in (d.get("open_changes") or []) if c]
+    if cr and cr not in opens:
+        opens.append(cr)
+    d["open_changes"] = opens
+    d["active_change"] = cr or (opens[-1] if opens else "")
+    save(d)
+    out["active_change"] = d["active_change"]; out["opened"] = cr
+    out["open_changes"] = opens; out["open_count"] = len(opens)
+    if cr in (d.get("open_changes") or [])[:-1]: out["reopened"] = True
+elif op == "activate":
+    # Point active_change at an already-open change. Nothing else moves: no version, no
+    # membership, no dates. This is how a CHOSEN delta reaches the stages that still
+    # resolve "the" change through active_change, without pretending it was just opened.
+    opens = [c for c in (d.get("open_changes") or []) if c]
+    if cr and cr not in opens:
         out["ok"] = False
-        out["error"] = ("change '%s' is already open on this feature; finish it "
-                        "(finalize-delta -> analyze-slice -> close-delta) before opening "
-                        "'%s', or pass --force" % (cur, cr))
-        out["conflict"] = cur; out["requested"] = cr; out["has_change"] = True
-        print(json.dumps(out)); sys.exit(3)
-    d["active_change"] = cr; save(d)
-    out["active_change"] = cr; out["opened"] = cr
-    if cur and cur == cr: out["reopened"] = True   # idempotent re-open of the same CR
+        out["error"] = ("'%s' is not an open change on this feature (open: %s)"
+                        % (cr, ", ".join(opens) or "none"))
+    else:
+        d["active_change"] = cr or d.get("active_change", "")
+        save(d)
+        out["active_change"] = d["active_change"]; out["activated"] = cr
+    out["open_changes"] = opens; out["open_count"] = len(opens)
 elif op == "close":
-    prev = d["version"]; closed = d.get("active_change", "")
-    if closed:                       # a real change was open -> materialized -> bump
+    # 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
+    # active_change falls back to whatever is still open so the downstream stages keep
+    # resolving a real change while others remain in flight.
+    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
+    closed = cr or d.get("active_change", "")
+    if closed and closed in opens:
+        opens.remove(closed)
         d["version"] = bump(prev)
-    d["active_change"] = ""; save(d)
-    out["version"] = d["version"]; out["active_change"] = ""
+    elif closed:                              # not tracked, but a real change was named
+        d["version"] = bump(prev)
+    d["open_changes"] = opens
+    d["active_change"] = opens[-1] if opens else ""
+    save(d)
+    out["version"] = d["version"]; out["active_change"] = d["active_change"]
     out["previous"] = prev; out["closed_change"] = closed
+    out["open_changes"] = opens; out["open_count"] = len(opens)
 out["bootstrap_pending"] = bool(d.get("bootstrap_pending"))
 out["has_change"] = bool(out.get("active_change", ""))   # clean branch signal for design
 # What a close from THIS state would produce. One bump() authority, read by BOTH
@@ -1115,6 +1488,7 @@ PY
 
 cmd_version_read()  { _version_cmd "read"  "$@"; }
 cmd_version_init()  { _version_cmd "init"  "$@"; }
+cmd_version_bootstrap_done() { _version_cmd "bootstrap-done" "$@"; }
 _version_cmd() {   # $1 = op (read|init), then --feature-dir arg
     local op="$1"; shift
     local fd_arg="" boot=""
@@ -1131,1841 +1505,6 @@ _version_cmd() {   # $1 = op (read|init), then --feature-dir arg
     _active_version "$fd" "$op" "" "" "$boot"
 }
 
-# ═════════════════════════════ the spec version ledger ══════════════════════
-# spec.md's `## Change History` is the sync anchor between the spec and its story
-# backlog: each row names the requirement ids that version touched, and each story
-# records the version it last synced at, so "is this story stale" is one integer
-# comparison rather than a diff. sync-stories reads the rows; specify and
-# update-spec append them.
-#
-# The ledger is hand-writable, which is the point — a spec can be edited by hand —
-# and also its one weakness: a body edited with no row leaves every affected story
-# quietly stale and nothing says so. active_version.json therefore carries a sha256
-# of spec.md as of the last kit-authored write, and three states follow from
-# comparing it against the document:
-#
-#   hash matches                    clean — nothing has been hand-edited since
-#   hash differs, version stands    a hand edit that skipped the ledger -> REFUSE
-#   hash differs, version advanced  a hand edit that wrote its own row  -> accept
-#
-# The middle case is the only silent failure the ledger has, which is why it is the
-# one thing checked before any workflow writes.
-_spec_ledger() {   # $1 = abs feature_dir, $2 = op, $3 = ids, $4 = summary, $5 = delta-spec template
-    AW_FD="$1" AW_OP="$2" AW_IDS="${3:-}" AW_SUM="${4:-}" AW_DTPL="${5:-}" python3 - <<'PY'
-import json, os, re, hashlib, datetime, sys
-fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]
-ids = os.environ.get("AW_IDS", "").strip(); summary = os.environ.get("AW_SUM", "").strip()
-spec = os.path.join(fd, "spec.md"); avp = os.path.join(fd, "active_version.json")
-feature = os.path.basename(fd.rstrip("/\\"))
-
-def now(): return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-def vtuple(v):
-    m = re.match(r'v?(\d+)(?:\.(\d+))?', (v or "").strip())
-    return (int(m.group(1)), int(m.group(2) or 0)) if m else (0, 0)
-def bump(v):
-    maj, mnr = vtuple(v or "v1.0")
-    return "v%d.%d" % (maj, mnr + 1)
-
-out = {"feature": feature, "op": op, "ok": True, "spec_exists": os.path.isfile(spec)}
-
-# A non-zero exit is reported by the orchestrator from STDERR alone, so anything that
-# stops a run has to say why there as well as in the JSON — otherwise the operator sees
-# "script failed (ledger-append):" and nothing else.
-def bail(msg, code):
-    out.update(ok=False, error=msg)
-    print(json.dumps(out)); sys.stderr.write(msg + "\n"); sys.exit(code)
-
-if not out["spec_exists"]:
-    bail("no spec.md at %s" % fd, 1)
-
-text = open(spec, encoding="utf-8", errors="replace").read()
-
-# The Story Coverage block is a projection of the backlog, not contract, and it is written
-# by the story workflows rather than by whoever owns the spec. Cutting it out before
-# hashing is what lets both be true at once: creating a story rewrites this document
-# without that reading as an unledgered edit of the requirements.
-COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
-def contract_of(t): return COV.sub("", t)
-actual = hashlib.sha256(contract_of(text).encode("utf-8")).hexdigest()
-av = {}
-if os.path.isfile(avp):
-    try: av = json.load(open(avp, encoding="utf-8"))
-    except Exception: av = {}
-recorded_hash = av.get("spec_sha256", "")
-recorded_ver = av.get("version", "v1.0")
-
-# The document's own header is what a hand edit bumps; active_version.json is what the
-# kit last wrote. They agree except across a hand edit, and the disagreement is the signal.
-m = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', text, re.M)
-doc_ver = m.group(1) if m else ""
-
-# THE LEDGER TABLE, located once: its heading, its separator rule, and the data rows under
-# it. Every op that touches a version row works from this, and `check` refuses a document
-# that has none — because ledger-append discovers a missing table only AFTER the spec has
-# been rewritten, and a rewritten spec with no row is exactly the state the next run's
-# tripwire refuses. Finding it at entry turns a wedged feature into a message.
-lines = text.split("\n")
-hi = next((i for i, l in enumerate(lines)
-           if re.match(r'^##\s+Change History\s*$', l.strip())), -1)
-sec_end = (next((i for i in range(hi + 1, len(lines)) if lines[i].startswith("## ")),
-                len(lines)) if hi >= 0 else -1)
-sep = (next((i for i in range(hi + 1, sec_end)
-             if re.match(r'^\|[\s\-:|]+\|$', lines[i].strip())), -1) if hi >= 0 else -1)
-rows = [i for i in range(sep + 1, sec_end) if lines[i].lstrip().startswith("|")] if sep >= 0 else []
-has_ledger = hi >= 0 and sep >= 0
-# THE VERSIONS THE TABLE ACTUALLY CARRIES, read from the rows located above rather than by
-# an unbounded scan, so a version-looking cell in another section's table cannot be counted
-# as history. This is the EVIDENCE that a change was recorded; the document's **Version**
-# header is only the CLAIM, and hand editing parts the two in both directions.
-row_versions = [m.group(1) for m in
-                (re.match(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', lines[i].lstrip()) for i in rows)
-                if m]
-newest_row = max(row_versions, key=vtuple) if row_versions else ""
-
-def cell(s, limit=160):
-    """One markdown table cell. A newline ENDS a row and a bare pipe STARTS a column, so
-    free text dropped into a cell silently rewrites the row's shape — a summary carrying
-    either one produced a version row whose 'Requirements changed' cell had moved or
-    vanished, which is a change no story can ever be reconciled against."""
-    s = re.sub(r'\s+', ' ', (s or "")).strip().replace("|", "\\|")
-    return (s[:limit - 1] + "\u2026") if len(s) > limit else s
-
-# IS A DELTA ACTUALLY MEASURED AGAINST THIS MASTER. cr-setup scaffolds delta-spec.md AND
-# delta-design.md for EVERY change it opens, so the file existing proves nothing. Since
-# specify lost its delta branch nothing authors a delta-spec at all, and the only changes
-# opened today are design-only ones carrying an untouched copy of the template — for which
-# editing spec.md strands nothing. Authored means the bytes have moved off the template;
-# with no template resolvable, a non-empty file counts.
-cr = av.get("active_change", "")
-dtpl = os.environ.get("AW_DTPL", "")
-dspec = os.path.join(fd, "changes", cr, "delta-spec.md") if cr else ""
-delta_authored = False
-if dspec and os.path.isfile(dspec) and os.path.getsize(dspec) > 0:
-    try:
-        delta_authored = (not (dtpl and os.path.isfile(dtpl))
-                          or open(dspec, "rb").read() != open(dtpl, "rb").read())
-    except Exception:
-        delta_authored = True
-
-out.update(open_change=cr, delta_authored=delta_authored)
-out.update(version=recorded_ver, doc_version=doc_ver, spec_sha256=actual,
-           recorded_sha256=recorded_hash, body_changed=(recorded_hash != actual),
-           has_ledger=has_ledger, ledger_rows=len(rows), newest_row=newest_row,
-           first_stamp=(not recorded_hash))
-
-if op == "check":
-    # An AUTHORED delta-spec was computed against THIS master. Writing the master directly
-    # would leave that delta measured from a baseline that no longer exists, and nothing
-    # downstream re-checks it. The two families overlap only until the delta set is deleted,
-    # so this guard is temporary by design — but while both exist it is the one silent way
-    # they collide. Narrowed to an authored delta on purpose: gating on `active_change`
-    # alone refused every extend for the whole life of a DESIGN-only change, which strands
-    # nothing, and told the operator to finish a chain they may be retiring.
-    if cr and delta_authored:
-        out["state"] = "delta_open"
-        out.update(ok=False, active_change=cr,
-                   error="change '%s' is open on this feature and its delta-spec has been "
-                   "authored, so a delta is measured against this master. Editing spec.md "
-                   "directly would leave that delta computed from a baseline that no longer "
-                   "exists. Either finish the change (finalize-delta -> analyze-slice -> "
-                   "close-delta), or abandon it: "
-                   "`.appweaver/scripts/bash/aw-spec-actions.sh cr-archive --cr-id %s` moves "
-                   "changes/%s/ into changes/archive/ and clears the flag. Abandoning also "
-                   "bumps the minor version, so the number moves even though nothing shipped."
-                   % (cr, cr, cr))
-    elif not has_ledger:
-        out["state"] = "no_ledger"
-        out.update(ok=False,
-                   error="spec.md has no '## Change History' table. That table is where a "
-                   "story learns a requirement it cites has moved, so a spec without one "
-                   "cannot be kept in step with its backlog. Add the section with its "
-                   "header row and separator (see the spec template), then re-run.")
-    elif not recorded_hash:
-        out["state"] = "unstamped"          # pre-ledger spec; stamp adopts it
-    elif recorded_hash == actual:
-        out["state"] = "clean"
-    # THE ROW IS THE EVIDENCE; THE HEADER IS ONLY THE CLAIM. The body has moved since the
-    # kit last stamped, and what makes that edit legible downstream is a version ROW naming
-    # the ids it touched: sync-stories reads rows, story-plan's staleness check reads rows,
-    # and neither ever opens the **Version** header. Taking the header as proof accepted the
-    # commonest hand-edit mistake there is — bump the number, forget the row — and that one
-    # passed every tripwire in the kit, raised no work anywhere, and was then buried for good
-    # by the next run's stamp adopting its hash. So the test is a row ABOVE the version the
-    # kit last recorded, and the header is only asked whether it kept up.
-    elif newest_row and vtuple(newest_row) > vtuple(recorded_ver):
-        out["state"] = ("ledgered_edit" if vtuple(doc_ver) >= vtuple(newest_row)
-                        else "header_behind")   # recorded; stamp reconciles the header
-    elif vtuple(doc_ver) > vtuple(recorded_ver):
-        # The header claims a version the table never recorded. Refused for the same reason
-        # an unrowed edit is: without the row nothing can say WHICH requirements moved, so
-        # every story citing one is stale with nothing able to detect it.
-        out["state"] = "unrowed_edit"
-        out.update(ok=False, error="spec.md's header reads %s but the Change History carries "
-                   "no row above %s — the version was bumped and what it changed was never "
-                   "recorded. The row is what a story reads to learn that a requirement it "
-                   "cites has moved; the header is read by nobody. Add a row naming the ids "
-                   "you changed (keep the header at %s), then re-run."
-                   % (doc_ver or "no version", recorded_ver, doc_ver))
-    elif vtuple(doc_ver) < vtuple(recorded_ver):
-        out["state"] = "rollback"
-        out.update(ok=False, error="spec.md reads %s but the kit last wrote %s — the "
-                   "document is behind its own ledger" % (doc_ver or "no version", recorded_ver))
-    else:
-        out["state"] = "unledgered_edit"
-        out.update(ok=False, error="spec.md has changed since %s but no Change History row "
-                   "was added. Every story citing an edited requirement is now silently "
-                   "stale. Add a row naming the ids you changed, then re-run."
-                   % recorded_ver)
-elif op == "stamp":
-    # THE VERSION IS THE HIGHEST OF THE THREE PLACES ONE IS WRITTEN, and the document's
-    # header is reconciled up to it. Taking the header alone let a hand edit that DID write
-    # its row — without bumping the header — leave the kit recording a version below the
-    # newest row; the next hand edit then read as a `rollback`, the document behind its own
-    # ledger, when nothing had rolled back. Rewriting the header is the authority
-    # ledger-append already exercises: the kit owns the number, the row is what it is
-    # computed from, and re-hashing after the rewrite is what keeps the baseline honest.
-    stamp_ver = max([recorded_ver or "v1.0", doc_ver or "v1.0"] +
-                    ([newest_row] if newest_row else []), key=vtuple)
-    if doc_ver and vtuple(doc_ver) < vtuple(stamp_ver):
-        text = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + stamp_ver,
-                      text, count=1, flags=re.M)
-        open(spec, "w", encoding="utf-8").write(text)
-        actual = hashlib.sha256(contract_of(text).encode("utf-8")).hexdigest()
-        out.update(header_rewritten=True, doc_version=stamp_ver, spec_sha256=actual)
-    av.setdefault("feature", feature); av.setdefault("active_change", "")
-    av["version"] = stamp_ver
-    av["spec_sha256"] = actual; av["updated"] = now()
-    open(avp, "w", encoding="utf-8").write(json.dumps(av, indent=2) + "\n")
-    out.update(version=av["version"], state="stamped")
-elif op == "append":
-    if not ids:
-        # A version that names no ids is a bump nothing can reconcile against: every
-        # story keeps its old stamp and the gap compounds at the next real change.
-        bail("ledger-append: --ids is required — a version row that names no requirement "
-             "ids leaves sync-stories nothing to act on", 2)
-    # The next number comes from the highest of all three places a version is written —
-    # what the kit last recorded, what the document's header claims, and the newest row
-    # actually in the table. A hand edit routinely moves one and not the others, and
-    # taking the maximum is what stops the ledger re-issuing a number it has already used.
-    row_vers = re.findall(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', text, re.M)
-    new_ver = bump(max([recorded_ver, doc_ver] + row_vers, key=vtuple))
-    today = datetime.date.today().isoformat()
-    # Both free-text cells go through cell(): the summary is whatever the operator typed on
-    # the command line, and one newline or one pipe in it destroys the row.
-    row = "| %s | %s | %s | %s | — |" % (
-        new_ver, today, cell(summary) or "Requirements updated", cell(ids))
-
-    # Bounded to the Change History section, not "the last table row in the file". Any
-    # section below it — Story Coverage today — carries its own table, and an unbounded
-    # search would file the version row into whichever one happened to come last.
-    if not has_ledger:
-        bail("spec.md has no '## Change History' table to append to — the ledger is "
-             "where a story learns a requirement moved, so a spec without one cannot be "
-             "kept in step with its backlog. spec.md HAS ALREADY BEEN WRITTEN by this run: "
-             "add the section, then re-run to record what it changed", 2)
-    last = rows[-1] if rows else sep
-    # Duplicate version = two writers reached the same number, which is the collision the
-    # integer buys for free. Refuse rather than append a second row nothing can order.
-    if re.search(r'^\|\s*%s\s*\|' % re.escape(new_ver), text, re.M):
-        bail("the ledger already carries a %s row — another write reached this version "
-             "first; re-read spec.md and retry" % new_ver, 3)
-    lines.insert(last + 1, row)
-
-    stamped = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + new_ver,
-                     "\n".join(lines), count=1, flags=re.M)
-    open(spec, "w", encoding="utf-8").write(stamped)
-
-    av.setdefault("feature", feature); av.setdefault("active_change", "")
-    av["version"] = new_ver
-    av["spec_sha256"] = hashlib.sha256(contract_of(stamped).encode("utf-8")).hexdigest()
-    av["updated"] = now()
-    open(avp, "w", encoding="utf-8").write(json.dumps(av, indent=2) + "\n")
-    out.update(version=new_ver, previous=recorded_ver, row=row, ids=ids,
-               spec_sha256=av["spec_sha256"], state="appended")
-elif op == "rowids":
-    # THE FIRST ROW, COMPUTED. Every other version row is derived from a before/after diff,
-    # for the reason the header of this file gives: a row the model DECLARED can omit an id
-    # it moved, and an omitted id is silent. The v1.0 row was the one exception — written by
-    # the author from a template whose placeholder literally reads "FR-001…FR-00n", which
-    # sync-stories then has to be told not to trust. This op closes that gap: the caller
-    # diffs the finished document against nothing and hands the ids in, exactly as the
-    # extend path does, so the first row is observed like all the rest.
-    if not ids:
-        bail("ledger-ids: --ids is required", 2)
-    if not has_ledger:
-        bail("spec.md has no '## Change History' table to write the initial row into", 2)
-    ver = doc_ver if re.match(r'^v\d+(\.\d+)?$', doc_ver or "") else (recorded_ver or "v1.0")
-    today = datetime.date.today().isoformat()
-    if rows:
-        # Rewrite the newest row's cells in place. A cell split has to respect \| , which is
-        # how cell() escapes a pipe the operator typed — splitting on every pipe would treat
-        # an escaped one as a column break and shift every cell after it.
-        parts = re.split(r'(?<!\\)\|', lines[rows[-1]])
-        body = [c.strip() for c in parts[1:-1]] if len(parts) >= 3 else []
-        while len(body) < 5: body.append("")
-        if not re.match(r'^v\d+(\.\d+)?$', body[0]): body[0] = ver
-        if not re.match(r'^\d{4}-\d{2}-\d{2}$', body[1]): body[1] = today
-        if not body[2] or body[2].startswith("["): body[2] = "Initial specification"
-        body[3] = cell(ids)
-        if not body[4]: body[4] = "—"
-        lines[rows[-1]] = "| " + " | ".join(body[:5]) + " |"
-    else:
-        lines.insert(sep + 1, "| %s | %s | Initial specification | %s | — |"
-                     % (ver, today, cell(ids)))
-    stamped = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + ver,
-                     "\n".join(lines), count=1, flags=re.M)
-    open(spec, "w", encoding="utf-8").write(stamped)
-    # The v1.0 row now names ids read out of the finished document, which is the moment the
-    # bootstrap is complete. Clearing the marker here and NOWHERE else is what makes an
-    # incomplete first run re-runnable: spec-stamp still re-baselines the hash on every path,
-    # so gating on the hash would have frozen a placeholder row as clean forever.
-    av.pop("bootstrap_pending", None)
-    av.setdefault("feature", feature); av.setdefault("active_change", "")
-    av["version"] = ver; av["updated"] = now()
-    open(avp, "w", encoding="utf-8").write(json.dumps(av, indent=2) + "\n")
-    out.update(version=ver, ids=ids, row=lines[rows[-1]] if rows else lines[sep + 1],
-               bootstrap_pending=False, state="rowids")
-print(json.dumps(out))
-PY
-}
-
-# ──────────────────────────────── story-refs ───────────────────────────────
-# Which requirements have live work against them. A read-only scan of the feature's
-# stories/ directory, reading only frontmatter — which is why §6.1 puts everything the
-# gates need there rather than in the body.
-#
-# specify asks this twice, for two different purposes. Before authoring, with no --ids,
-# to tell the author which requirements someone is currently building. After the diff,
-# with the ids the run actually MODIFIED, to decide whether to ask before changing a
-# contract under someone's feet.
-#
-# Only OPEN stories count. A closed story is history and a cancelled one was abandoned;
-# neither is disturbed by the contract moving (E4).
-#
-# in_flight is the narrower set: an open story that already has a stories/<ID>/ directory,
-# so someone has run story-plan and is working from a design of the requirement as it
-# reads today. That is the same directory-existence predicate change-story-id uses for its
-# legality boundary — one test, serving three workflows.
-cmd_story_refs() {
-    local fd_arg="" ids="" ids_given=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --ids) ids="$2"; ids_given=1; shift 2 ;;
-            --help|-h) echo "story-refs [--feature-dir <path>] [--ids <FR-001, BR-002>]"; return 0 ;;
-            *) echo "story-refs: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-refs: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_IDS="$ids" AW_IDS_GIVEN="$ids_given" python3 - <<'PY'
-import json, os, re
-fd = os.environ["AW_FD"]; want = os.environ.get("AW_IDS", "")
-sdir = os.path.join(fd, "stories")
-queried = [s.strip() for s in re.split(r'[,\s]+', want) if s.strip()]
-
-def parse_fm(text):
-    """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
-    a YAML block list under an empty key — both are valid YAML and a hand edit produces
-    either, so a parser that read only the inline form saw a perfectly good story as citing
-    nothing, and a story citing nothing is invisible to every gate that exists to protect
-    it. Block items are folded into the inline shape so every caller stays regex-simple."""
-    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
-    if not m: return {}
-    fm, key, block = {}, None, set()
-    for line in m.group(1).split("\n"):
-        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
-        if km:
-            key = km.group(1); fm[key] = km.group(2).strip(); continue
-        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
-        if im and (key in block or not fm[key]):
-            block.add(key)
-            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
-    return fm
-
-def frontmatter(path):
-    try: return parse_fm(open(path, encoding="utf-8", errors="replace").read())
-    except Exception: return {}
-
-stories = []
-if os.path.isdir(sdir):
-    for name in sorted(os.listdir(sdir)):
-        if not name.endswith(".md"): continue
-        path = os.path.join(sdir, name)
-        if not os.path.isfile(path): continue
-        fm = frontmatter(path)
-        sid = fm.get("id") or name[:-3]
-        # An unparseable story is reported as open rather than skipped: a story the scan
-        # cannot read is exactly the one whose requirements must not move unannounced.
-        status = (fm.get("status") or "open").strip().lower()
-        cites = [c.strip() for c in re.findall(r'[A-Z]{2}-\d+', fm.get("exercises", ""))]
-        stories.append({"id": sid, "status": status, "exercises": cites,
-                        "cites_csv": ", ".join(cites),
-                        "title": (fm.get("title") or "").strip().strip("[]"),
-                        "spec_version": (fm.get("spec_version") or "").strip(),
-                        "type": (fm.get("type") or "functional").strip().lower(),
-                        "follows": (fm.get("follows") or "").strip(),
-                        "in_flight": os.path.isdir(os.path.join(sdir, sid))})
-
-open_stories = [s for s in stories if s["status"] == "open"]
-covered = sorted({c for s in open_stories for c in s["exercises"]})
-
-# ASKING ABOUT NOTHING IS NOT ASKING ABOUT EVERYTHING. `--ids ""` is a caller saying "this
-# run disturbed no requirement" — a pure addition — and the answer is an empty set. Only
-# the absence of the flag means "tell me about the whole backlog". Conflating the two made
-# an enhancement that touched nothing existing prompt about every requirement with a story.
-targets = queried if os.environ.get("AW_IDS_GIVEN") else covered
-
-affected, aff_ids, aff_stories, inflight = [], [], [], []
-for rid in targets:
-    hit = [s for s in open_stories if rid in s["exercises"]]
-    if not hit: continue
-    aff_ids.append(rid)
-    names = [s["id"] for s in hit]
-    flying = [s["id"] for s in hit if s["in_flight"]]
-    aff_stories += names; inflight += flying
-    affected.append({"id": rid, "stories": names, "in_flight": flying})
-
-# THE COMPLEMENT, NAMED. `affected` is "these ids have live work"; its complement is
-# "these ids have nobody on them", and that is the set sync-stories raises new stories for.
-# Derived here rather than in the caller because the orchestrator binds values and never
-# computes them, and a subtraction done in a prompt is a subtraction nothing can check.
-unlinked = [rid for rid in targets if rid not in aff_ids]
-
-# One line per open story, for a prompt that has to ask about them. A story id on its own
-# is not something an author can answer about: what it cites and whether someone is already
-# implementing it are the whole basis of the decision.
-digest = "\n".join(
-    "  %-16s %-9s %-11s cites %s%s" % (
-        s["id"], s["status"], "IN FLIGHT" if s["in_flight"] else "not started",
-        s["cites_csv"] or "nothing",
-        ("  @ " + s["spec_version"]) if s["spec_version"] else "")
-    for s in open_stories) or "  (no open stories)"
-
-print(json.dumps({
-    "ok": True, "stories_dir": sdir, "stories_exist": os.path.isdir(sdir),
-    "story_count": len(stories), "open_count": len(open_stories),
-    "stories": stories, "digest": digest,
-    "queried": queried, "covered": covered, "covered_csv": ", ".join(covered),
-    "affected": affected, "affected_ids": aff_ids, "affected_csv": ", ".join(aff_ids),
-    "unlinked": unlinked, "unlinked_csv": ", ".join(unlinked),
-    "unlinked_count": len(unlinked), "any_unlinked": bool(unlinked),
-    "story_csv": ", ".join(sorted(set(aff_stories))),
-    "in_flight_csv": ", ".join(sorted(set(inflight))),
-    "any": bool(aff_ids), "any_in_flight": bool(inflight),
-}))
-PY
-}
-
-# ────────────────────────────── spec-coverage ──────────────────────────────
-# Rewrite the spec's Story Coverage block from the stories/ directory: every FR- and BR-
-# in the document, and the stories that deliver it. The relation is stored ONCE, in each
-# story's `exercises:` frontmatter; this is that relation read the other way round, which
-# is why the block is regenerated wholesale rather than patched. Hand edits to it are
-# discarded by design — the story is where delivery is declared.
-#
-# Every workflow that changes either side calls this: specify when the requirements move,
-# user-story and sync-stories when the backlog does. It is deterministic and model-free,
-# so calling it more often than necessary costs nothing and drift is not possible.
-#
-# Scoped to FR-/BR- — the ids a story cites. CN-/DC-/IC-/UX- are constraints the design
-# traces, not slices of work, and listing them would show permanent gaps as coverage holes.
-cmd_spec_coverage() {
-    local fd_arg=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --help|-h) echo "spec-coverage [--feature-dir <path>]"; return 0 ;;
-            *) echo "spec-coverage: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-coverage: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" python3 - <<'PY'
-import json, os, re, sys
-fd = os.environ["AW_FD"]
-spec = os.path.join(fd, "spec.md"); sdir = os.path.join(fd, "stories")
-BEGIN, END = "<!-- AW:COVERAGE:BEGIN -->", "<!-- AW:COVERAGE:END -->"
-COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
-def parse_fm(text):
-    """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
-    a YAML block list under an empty key — both are valid YAML and a hand edit produces
-    either, so a parser that read only the inline form saw a perfectly good story as citing
-    nothing, and a story citing nothing is invisible to every gate that exists to protect
-    it. Block items are folded into the inline shape so every caller stays regex-simple."""
-    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
-    if not m: return {}
-    fm, key, block = {}, None, set()
-    for line in m.group(1).split("\n"):
-        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
-        if km:
-            key = km.group(1); fm[key] = km.group(2).strip(); continue
-        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
-        if im and (key in block or not fm[key]):
-            block.add(key)
-            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
-    return fm
-out = {"ok": True, "written": False}
-if not os.path.isfile(spec):
-    out.update(ok=False, error="no spec.md at %s" % fd); print(json.dumps(out)); sys.exit(1)
-text = open(spec, encoding="utf-8", errors="replace").read()
-if not COV.search(text):
-    # A spec from before the block existed, or one whose markers were deleted. Not an
-    # error: the coverage view is an aid, and refusing to run would block the change the
-    # caller actually came to make.
-    out.update(reason="no AW:COVERAGE block in spec.md"); print(json.dumps(out)); sys.exit(0)
-
-body = COV.sub("", text)
-rids = []
-for line in body.split("\n"):
-    m = re.search(r'\*\*((?:FR|BR)-\d+)\*\*', line)
-    if m and m.group(1) not in rids: rids.append(m.group(1))
-rids.sort(key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-
-stories = []
-if os.path.isdir(sdir):
-    for name in sorted(os.listdir(sdir)):
-        if not name.endswith(".md"): continue
-        p = os.path.join(sdir, name)
-        if not os.path.isfile(p): continue
-        d = parse_fm(open(p, encoding="utf-8", errors="replace").read())
-        sid = d.get("id") or name[:-3]
-        stories.append({"id": sid, "status": (d.get("status") or "open").strip().lower(),
-                        "cites": re.findall(r'[A-Z]{2}-\d+', d.get("exercises", "")),
-                        "flying": os.path.isdir(os.path.join(sdir, sid))})
-
-rows, uncovered, delivered = [], [], []
-for rid in rids:
-    live = [s for s in stories if rid in s["cites"] and s["status"] == "open"]
-    done = [s for s in stories if rid in s["cites"] and s["status"] != "open"]
-    if not live and not done: uncovered.append(rid)
-    # DELIVERED is "no OPEN stories", never "a story closed" — a follow-on can still carry
-    # the remainder, and keying on a closed story would read a half-built requirement as done.
-    elif not live: delivered.append(rid)
-    rows.append("| %s | %s | %s |" % (
-        rid,
-        ", ".join(s["id"] + (" (in flight)" if s["flying"] else "") for s in live) or "—",
-        ", ".join(s["id"] for s in done) or "—"))
-
-table = ["| Requirement | Open stories | Closed / cancelled |",
-         "|-------------|--------------|--------------------|"]
-table += rows or ["| _(no FR- or BR- requirements yet)_ | | |"]
-open(spec, "w", encoding="utf-8").write(COV.sub(BEGIN + "\n" + "\n".join(table) + "\n" + END, text, count=1))
-out.update(written=True, requirements=len(rids), stories=len(stories),
-           uncovered=uncovered, uncovered_csv=", ".join(uncovered),
-           delivered=delivered, delivered_csv=", ".join(delivered))
-print(json.dumps(out))
-PY
-}
-
-# ─────────────────────────────── ledger-read ───────────────────────────────
-# THE WORK SET: which requirements this sync has to account for. The ledger records what
-# each version touched and every story records the version it last synced at, so the
-# question "what has moved since the backlog was last in step" is answerable by reading
-# rows — no diffing, no hashing, no model.
-#
-# The set is the union of the ids named by every row ABOVE THE LOWEST spec_version across
-# the OPEN stories, not the ids of the newest row alone. Those are the same set whenever
-# the backlog is one version behind, which is the ordinary case; they diverge only when a
-# sync was skipped, and that is exactly the case worth getting right. Two specify runs
-# without a sync between them leave the middle version named by no row anyone reads, and
-# its requirements would get no story with nothing to say so — a silent gap, in the one
-# mechanism built to make gaps loud.
-#
-# THE v1.0 CASE (E42). At v1.0 nothing has moved yet: there is no "since" to read from. So
-# when no open story carries a readable spec version — an empty backlog, or stories written
-# before the field existed — the work set is every FR-/BR- the DOCUMENT declares, and the
-# per-id four-case table does the rest. A second run over the same spec then creates
-# nothing, because by then every id has a story.
-#
-# Scoped to FR-/BR- throughout, the same scoping spec-coverage applies: those are the only
-# classes a story's `exercises:` can name. CN-/DC-/IC-/UX- move the contract and belong in
-# the ledger row, but they are constraints a story CARRIES, not slices of work it delivers.
-cmd_ledger_read() {
-    local fd_arg=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --help|-h) echo "ledger-read [--feature-dir <path>]"; return 0 ;;
-            *) echo "ledger-read: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "ledger-read: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" python3 - <<'PY'
-import json, os, re, sys
-fd = os.environ["AW_FD"]
-spec = os.path.join(fd, "spec.md"); sdir = os.path.join(fd, "stories")
-
-def bail(msg, code=1):
-    print(json.dumps({"ok": False, "error": msg}))
-    sys.stderr.write(msg + "\n"); sys.exit(code)
-
-if not os.path.isfile(spec): bail("no spec.md at %s" % fd)
-text = open(spec, encoding="utf-8", errors="replace").read()
-
-COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
-
-def vtuple(v):
-    m = re.match(r'v?(\d+)(?:\.(\d+))?', (v or "").strip())
-    return (int(m.group(1)), int(m.group(2) or 0)) if m else (0, 0)
-
-def rids(s):
-    """FR-/BR- ids in order of appearance, deduped, then sorted by class and number so
-    two callers reading the same row always produce the same csv."""
-    seen, out = set(), []
-    for t in re.findall(r'\b(?:FR|BR)-\d+', s or ""):
-        if t not in seen: seen.add(t); out.append(t)
-    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-
-def parse_fm(text):
-    """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
-    a YAML block list under an empty key — both are valid YAML and a hand edit produces
-    either, so a parser that read only the inline form saw a perfectly good story as citing
-    nothing, and a story citing nothing is invisible to every gate that exists to protect
-    it. Block items are folded into the inline shape so every caller stays regex-simple."""
-    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
-    if not m: return {}
-    fm, key, block = {}, None, set()
-    for line in m.group(1).split("\n"):
-        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
-        if km:
-            key = km.group(1); fm[key] = km.group(2).strip(); continue
-        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
-        if im and (key in block or not fm[key]):
-            block.add(key)
-            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
-    return fm
-
-# THE LEDGER TABLE, located the same way _spec_ledger locates it — heading, separator rule,
-# then the rows under it, bounded by the next `## `. Any other section carries its own
-# table (Story Coverage does), and an unbounded search would read one of those as history.
-lines = text.split("\n")
-hi = next((i for i, l in enumerate(lines)
-           if re.match(r'^##\s+Change History\s*$', l.strip())), -1)
-sec_end = (next((i for i in range(hi + 1, len(lines)) if lines[i].startswith("## ")),
-                len(lines)) if hi >= 0 else -1)
-sep = (next((i for i in range(hi + 1, sec_end)
-             if re.match(r'^\|[\s\-:|]+\|$', lines[i].strip())), -1) if hi >= 0 else -1)
-row_lines = [i for i in range(sep + 1, sec_end) if lines[i].lstrip().startswith("|")] if sep >= 0 else []
-has_ledger = hi >= 0 and sep >= 0
-
-def cells(line):
-    parts = re.split(r'(?<!\\)\|', line)
-    return [c.strip().replace("\\|", "|") for c in parts[1:-1]] if len(parts) >= 3 else []
-
-rows = []
-for i in row_lines:
-    c = cells(lines[i]); c += [""] * (5 - len(c))
-    # A row whose first cell is not a version is the template's own placeholder line, or a
-    # note somebody left in the table. It records no version, so it orders against nothing.
-    if not re.match(r'^v\d', c[0]): continue
-    rows.append({"version": c[0], "date": c[1], "change": c[2], "ids_cell": c[3],
-                 "stories": c[4], "requirements": rids(c[3])})
-rows.sort(key=lambda r: vtuple(r["version"]))
-
-# WHAT THE DOCUMENT STILL DECLARES. Read from the requirement's DEFINING line — the bolded
-# id the template gives every requirement — and with the Change History cut away, so the
-# ids named in a row's own cell are never mistaken for requirements the spec carries.
-body = COV.sub("", text).split("\n## Change History")[0]
-declared = []
-for line in body.split("\n"):
-    m = re.search(r'\*\*((?:FR|BR)-\d+)\*\*', line)
-    if m and m.group(1) not in declared: declared.append(m.group(1))
-declared.sort(key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-
-stories = []
-if os.path.isdir(sdir):
-    for name in sorted(os.listdir(sdir)):
-        if not name.endswith(".md"): continue
-        p = os.path.join(sdir, name)
-        if not os.path.isfile(p): continue
-        fm = parse_fm(open(p, encoding="utf-8", errors="replace").read())
-        sid = fm.get("id") or name[:-3]
-        stories.append({"id": sid, "status": (fm.get("status") or "open").strip().lower(),
-                        "spec_version": (fm.get("spec_version") or "").strip(),
-                        "follows": (fm.get("follows") or "").strip(),
-                        "in_flight": os.path.isdir(os.path.join(sdir, sid)),
-                        "cites": rids(fm.get("exercises", ""))})
-open_stories = [s for s in stories if s["status"] == "open"]
-
-# THE FLOOR is the oldest version any open story is still sitting at, and everything above
-# it is unsynced. A story whose spec_version is missing or unreadable counts as v0.0 rather
-# than being skipped: it has demonstrably never synced, and putting the whole ledger above
-# it is the same answer enumerating from the document would give.
-floors = [vtuple(s["spec_version"]) for s in open_stories]
-readable = [s for s in open_stories if re.match(r'^v?\d', s["spec_version"] or "")]
-# A BACKLOG THAT IS ENTIRELY CLOSED IS NOT A BACKLOG THAT NEVER SYNCED. Reading the floor
-# from open stories alone made the last story closing look exactly like a feature nobody has
-# ever sliced: no floor took the enumerate-the-whole-document branch below, so one idle
-# re-run after finishing a feature raised a fresh story for every requirement in the spec —
-# each one reported as work the contract had moved on, when nothing had moved at all. A
-# CLOSED story carries a stamp too, and it records which version its work was measured
-# against. CANCELLED ones are excluded: abandoned work delivered nothing and settles nothing,
-# so it establishes no floor and leaves its requirements to be sliced again.
-closed_stories = [s for s in stories if s["status"] == "closed"]
-floor_source = "open" if floors else ("closed" if closed_stories else "none")
-floor = (min(floors) if floors
-         else (min(vtuple(s["spec_version"]) for s in closed_stories) if closed_stories
-               else None))
-
-latest = rows[-1] if rows else None
-out = {"ok": True, "feature_dir": fd, "has_ledger": has_ledger,
-       "row_count": len(rows), "ledger_empty": len(rows) == 0,
-       "rows": rows,
-       "latest_version": latest["version"] if latest else "",
-       "latest_change": latest["change"] if latest else "",
-       "latest_ids_csv": ", ".join(latest["requirements"]) if latest else "",
-       "spec_ids_csv": ", ".join(declared), "spec_id_count": len(declared),
-       "story_count": len(stories), "open_count": len(open_stories),
-       "unversioned_open": len(open_stories) - len(readable)}
-
-if not has_ledger:
-    out.update(ok=False, error="spec.md has no '## Change History' table. That table is "
-               "where a story learns a requirement it cites has moved, so a spec without "
-               "one cannot be kept in step with its backlog.")
-    print(json.dumps(out)); sys.stderr.write(out["error"] + "\n"); sys.exit(2)
-
-if not rows:
-    # An empty ledger is not corruption — it is a spec that has never been versioned, which
-    # means specify has not finished with it. Reported, not raised: the caller warns and
-    # stops, because there is no "since" to sync from and inventing one would raise a
-    # backlog against a document nobody has committed to.
-    out.update(work_csv="", work_count=0, work_source="none", span_versions_csv="",
-               gap=False, removed_csv="",
-               work_note="the Change History table carries no version row")
-    print(json.dumps(out)); sys.exit(0)
-
-if floor is None:
-    # E42 — nothing has moved because nothing has synced. Enumerate from the document.
-    source, span = "spec", []
-    candidates = list(declared)
-    note = ("nothing has synced against this spec yet — no open story records a version and "
-            "nothing has closed against it — so there is no 'since' to read from: the work "
-            "set is every requirement the document declares, and the per-id rules then "
-            "create only what has no story")
-else:
-    span = [r for r in rows if vtuple(r["version"]) > floor]
-    seen, candidates = set(), []
-    for r in span:
-        for rid in r["requirements"]:
-            if rid not in seen: seen.add(rid); candidates.append(rid)
-    candidates.sort(key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-    source = "ledger"
-    note = ("%d version row(s) above the oldest %s story's v%d.%d: %s"
-            % (len(span), floor_source, floor[0], floor[1],
-               ", ".join(r["version"] for r in span) or "none"))
-
-# THE SPAN IS A PREFILTER; STALENESS IS PER ID. The floor is the oldest version any open
-# story sits at, and a story whose requirements never move sits there forever — Order-001
-# holding v1.0 keeps v1.1 and v1.2 in the span long after everything they named has been
-# synced. Reading the span alone therefore re-offered the same requirements on every run,
-# and each re-offer is a model call rewriting a story that was already in step.
-#
-# So the span says which ids are WORTH CHECKING and this says which have actually moved
-# under someone: an id is stale when it has no open story at all, or when some open story
-# citing it is stamped BELOW the newest version that touched it. An id whose every open
-# story is at or above that version is in step, whatever the floor says.
-moved_at = {}
-for r in rows:
-    for rid in r["requirements"]:
-        v = vtuple(r["version"])
-        if v > moved_at.get(rid, (0, 0)): moved_at[rid] = v
-
-def carried_on(story_id, rid, at):
-    """Has a follow-on already taken this requirement off that story's hands, at or above
-    the version that moved it. The `follows` link is the whole record of that hand-off."""
-    return any(s["follows"] == story_id and rid in s["cites"]
-               and vtuple(s["spec_version"]) >= at for s in open_stories)
-
-work, in_step = [], []
-for rid in candidates:
-    holders = [s for s in open_stories if rid in s["cites"]]
-    at = moved_at.get(rid, (0, 0))
-    behind = []
-    for s in holders:
-        if vtuple(s["spec_version"]) >= at: continue
-        # AN IN-FLIGHT STORY CANNOT BE BROUGHT UP TO DATE, BY DESIGN. It is never rewritten
-        # (§5.5), so its spec_version can never rise, so reading it as a staleness signal
-        # gives a signal that never clears — and a sync that mints a fresh follow-on for the
-        # same requirement on every run. What clears it is the follow-on itself: once one
-        # exists carrying this id at or above the version that moved it, the hand-off has
-        # happened and the original is history in progress, not unfinished business.
-        if s["in_flight"] and carried_on(s["id"], rid, at): continue
-        behind.append(s["id"])
-    # A CLOSED STORY STAMPED AT OR ABOVE THE VERSION THAT LAST MOVED THIS REQUIREMENT
-    # DELIVERED THE WORDING THE SPEC ASKS FOR TODAY, so the requirement is FINISHED rather
-    # than unsliced. Reading "no open story cites it" as work on its own could not tell those
-    # two apart, which is what let a fully delivered feature re-raise its entire backlog.
-    # A closed story stamped BELOW that version is the other case and stays work: the
-    # contract moved after it shipped, so what shipped is no longer what the spec asks for,
-    # and backlog-plan names the closed story it is re-opening against.
-    delivered = any(rid in s["cites"] and vtuple(s["spec_version"]) >= at
-                    for s in closed_stories)
-    (in_step if ((holders and not behind) or (not holders and delivered))
-     else work).append(rid)
-
-# A row names what a version TOUCHED, and that includes ids it REMOVED. A removed
-# requirement has no wording left to write a story from, so it leaves the work set — but it
-# is reported, because every open story citing one is orphaned and that is a decision for a
-# person, not a default (E1).
-removed = [i for i in work if i not in declared]
-work = [i for i in work if i in declared]
-
-out.update(work_csv=", ".join(work), work_count=len(work), work_source=source,
-           work_note=note, work_any=bool(work),
-           candidates_csv=", ".join(candidates), candidate_count=len(candidates),
-           in_step_csv=", ".join(in_step), in_step_count=len(in_step),
-           floor_source=floor_source,
-           span_versions_csv=", ".join(r["version"] for r in span),
-           span_count=len(span), gap=len(span) > 1,
-           removed_csv=", ".join(removed), removed_count=len(removed),
-           synced_floor=("v%d.%d" % floor) if floor else "")
-print(json.dumps(out))
-PY
-}
-
-# ─────────────────────────────── slice-mode ────────────────────────────────
-# Which slicing strategy the launch line asked for, and what is left of the input once that
-# word is taken out of it. Its own op rather than a `condition:` in the workflow, because
-# the engine compares a whole rendered value: `{{USER_INPUT}} == single-run` only matches an
-# input carrying the strategy and no guidance at all, and `sync-stories single-run keep the
-# payment rules together` — the form the launch line documents — would silently slice by
-# default while looking as though it had been told not to.
-#
-# ONLY THE FIRST WORD IS A STRATEGY. Guidance is free prose, and "keep the single sign-on
-# requirements in one story" is a slicing instruction with the token sitting in the middle
-# of it. Reading the token anywhere in the string would turn that sentence into the opposite
-# of what it asks, with nothing to say so.
-cmd_slice_mode() {
-    local input=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --input) input="$2"; shift 2 ;;
-            --help|-h) echo "slice-mode [--input <text>]  -> {strategy, guidance, note}"; return 0 ;;
-            *) echo "slice-mode: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    AW_INPUT="$input" python3 - <<'PY'
-import json, os, re
-raw = (os.environ.get("AW_INPUT", "") or "").strip()
-
-# `single-run` is the spelling the launch line documents; the others are what people write
-# when they mean it. `auto` is the default and is accepted explicitly so a launch line can
-# say so — a strategy nobody can name is one nobody can turn off.
-TOKENS = {"single-run": "single", "single-story": "single", "single": "single",
-          "one-story": "single", "auto": "auto", "per-slice": "auto", "default": "auto"}
-
-strategy, guidance = "auto", raw
-m = re.match(r'^([A-Za-z][A-Za-z0-9_-]*)\s*[:,]?\s*(.*)$', raw, re.S)
-if m and m.group(1).lower() in TOKENS:
-    strategy = TOKENS[m.group(1).lower()]
-    guidance = m.group(2).strip()
-
-if strategy == "single":
-    note = ("one story was asked for (single-run): the whole work set goes into a single "
-            "slice unless it is too heavy to be picked up as one piece of work, in which "
-            "case it is split along its dependencies and the split is reported")
-else:
-    note = "the slicing is decided from the requirements themselves"
-
-print(json.dumps({"ok": True, "strategy": strategy, "guidance": guidance,
-                  "single": strategy == "single", "note": note,
-                  "raw": raw, "tokens": sorted(TOKENS)}))
-PY
-}
-
-# ─────────────────────────────── backlog-plan ──────────────────────────────
-# The grouping is a judgment; everything that follows from it is arithmetic. This op does
-# the arithmetic, in two modes over the same inputs so the two passes cannot disagree about
-# what a group contains:
-#
-#   scan   which OPEN stories already stand in front of a group's requirements — the
-#          candidates the author is asked about, and the wording of that question.
-#   plan   given the author's answer, the flat list of story files to write: one entry per
-#          file, each already carrying its id, its path, and the ids it must end up citing.
-#
-# THE FOUR CASES (§5.4) resolve per group, not per requirement, because a group IS the story:
-#
-#   no open story cites anything in the group        -> create
-#   an open story does, no stories/<ID>/ yet         -> update in place (asked)
-#   an open story does, a story plan already exists  -> mint a follow-on (asked); the
-#                                                       original is never rewritten (§5.5)
-#   the author declines                              -> that story is left alone AND the ids
-#                                                       it covers leave the group; whatever
-#                                                       remains becomes a new story
-#
-# The last line is the one worth reading twice. Declining does not abandon the group — it
-# withdraws the requirements that story is already carrying and creates a story for the
-# rest. A group of three where one id has a story the author will not touch still delivers
-# the other two.
-#
-# ONE GROUP, ONE ABSORBING STORY. Where the author approves two stories in the same group,
-# the first by id takes the group's unclaimed requirements and the others keep exactly the
-# ids they already cite. Two stories both claiming the same new requirement is not a state
-# the completeness rule can read.
-#
-# IN FLIGHT IS TESTED PER STORY, NOT ONLY ON THE FIRST. An approved story that already has
-# a story with a story plan is never rewritten wherever it sits in the group — it gets its own follow-on
-# carrying what it covers, exactly as it would if it were the only story there.
-#
-# AND THE ORDER. Plan mode also resolves the dependency edges the grouping declared between
-# slices, folds in the `depends_on:` an updated story already carries, breaks any cycle, and
-# lays the result out in WAVES: wave N holds the stories whose every dependency sits below N,
-# so one wave is a set with no ordering between its members — they may be picked up in
-# parallel. The plan comes back sorted by wave, which is also the order the stories are
-# written in, so meeting the cap costs the LAST wave rather than an arbitrary slice of the
-# backlog. See the block above the wave computation for why `follows:` is not an edge.
-cmd_backlog_plan() {
-    local fd_arg="" groups="" approved="" work="" version="" mode="scan" cap="" strategy="" ceiling=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --groups)   groups="$2";   shift 2 ;;
-            --approved) approved="$2"; shift 2 ;;
-            --work)     work="$2";     shift 2 ;;
-            --version)  version="$2";  shift 2 ;;
-            --cap)      cap="$2";      shift 2 ;;
-            --strategy) strategy="$2"; shift 2 ;;
-            --ceiling)  ceiling="$2";  shift 2 ;;
-            --plan)     mode="plan";   shift ;;
-            --help|-h) echo "backlog-plan --groups <json> --work <csv> [--strategy single|auto] [--ceiling <n>] [--feature-dir <p>]"; echo "backlog-plan --plan --groups <json> --work <csv> --approved <story ids> --version <v> [--cap <n>] [--strategy single|auto] [--ceiling <n>]"; return 0 ;;
-            *) echo "backlog-plan: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "backlog-plan: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_GROUPS="$groups" AW_OK="$approved" AW_WORK="$work" AW_VER="$version" AW_MODE="$mode" AW_CAP="$cap" AW_STRATEGY="$strategy" AW_CEILING="$ceiling" python3 - <<'PY'
-import json, os, re, sys
-fd = os.environ["AW_FD"]; mode = os.environ.get("AW_MODE", "scan")
-sdir = os.path.join(fd, "stories")
-feature = os.path.basename(fd.rstrip("/\\"))
-
-def bail(msg, code=2):
-    print(json.dumps({"ok": False, "error": msg}))
-    sys.stderr.write(msg + "\n"); sys.exit(code)
-
-def rids(s):
-    seen, out = set(), []
-    for t in re.findall(r'\b(?:FR|BR)-\d+', s or ""):
-        if t not in seen: seen.add(t); out.append(t)
-    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-
-def sids(s):
-    """Story ids out of a csv, a JSON list or a YAML inline list. A story id is a feature
-    name and a number; a template placeholder (`[]`, `[STORY-ID]`) is neither, and must
-    never become a dependency edge nobody can resolve."""
-    seen, out = set(), []
-    for t in re.split(r'[,\s\[\]"\']+', s or ""):
-        t = t.strip()
-        if re.match(r'^[A-Za-z][\w.]*-\d+$', t) and t not in seen:
-            seen.add(t); out.append(t)
-    return out
-
-def wave_of(s):
-    """A story's declared wave. Absent — a story written before the field existed — reads
-    as 1, the conservative floor: nothing is KNOWN to have to land before it."""
-    m = re.match(r'^\s*(\d+)\s*$', (s or "").strip())
-    return int(m.group(1)) if m else 1
-
-def names(s):
-    """Story ids out of a csv or a JSON list. A multi-select answer arrives as the engine's
-    JSON rendering of a list, so both spellings have to read the same."""
-    seen, out = set(), []
-    for t in re.split(r'[,\s\[\]"\']+', s or ""):
-        t = t.strip()
-        if t and t not in seen: seen.add(t); out.append(t)
-    return out
-
-def parse_fm(text):
-    """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
-    a YAML block list under an empty key — both are valid YAML and a hand edit produces
-    either, so a parser that read only the inline form saw a perfectly good story as citing
-    nothing, and a story citing nothing is invisible to every gate that exists to protect
-    it. Block items are folded into the inline shape so every caller stays regex-simple."""
-    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
-    if not m: return {}
-    fm, key, block = {}, None, set()
-    for line in m.group(1).split("\n"):
-        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
-        if km:
-            key = km.group(1); fm[key] = km.group(2).strip(); continue
-        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
-        if im and (key in block or not fm[key]):
-            block.add(key)
-            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
-    return fm
-
-# ---- the backlog -----------------------------------------------------------------
-stories, used_numbers = [], []
-if os.path.isdir(sdir):
-    for name in sorted(os.listdir(sdir)):
-        if not name.endswith(".md"): continue
-        p = os.path.join(sdir, name)
-        if not os.path.isfile(p): continue
-        fm = parse_fm(open(p, encoding="utf-8", errors="replace").read())
-        sid = fm.get("id") or name[:-3]
-        # Numbers come from the FILENAME as well as the id, and from CLOSED and CANCELLED
-        # stories as well as open ones. An id is permanent once minted: re-issuing the
-        # number of a story that shipped re-points its execution artefacts at new work.
-        for cand in (sid, name[:-3]):
-            m = re.search(r'-(\d+)$', cand)
-            if m: used_numbers.append(int(m.group(1)))
-        stories.append({"id": sid, "status": (fm.get("status") or "open").strip().lower(),
-                        "title": (fm.get("title") or "").strip().strip("[]"),
-                        "spec_version": (fm.get("spec_version") or "").strip(),
-                        "cites": rids(fm.get("exercises", "")),
-                        "wave": wave_of(fm.get("wave", "")),
-                        "deps": sids(fm.get("depends_on", "")),
-                        "in_flight": os.path.isdir(os.path.join(sdir, sid)),
-                        "path": p})
-open_stories = [s for s in stories if s["status"] == "open"]
-# Closed and cancelled stories hold no requirement — completeness is "no OPEN stories" —
-# but they are the reason a create can look like duplicated work, so they are read in
-# order to say so. See the create branch below.
-done_stories = [s for s in stories if s["status"] != "open"]
-by_id = {s["id"]: s for s in stories}
-_next = [max(used_numbers) + 1 if used_numbers else 1]
-
-def mint():
-    n = _next[0]; _next[0] += 1
-    return "%s-%03d" % (feature, n)
-
-# ---- the groups ------------------------------------------------------------------
-raw = (os.environ.get("AW_GROUPS") or "").strip()
-try:
-    parsed = json.loads(raw) if raw else []
-except Exception as e:
-    bail("backlog-plan: --groups is not valid JSON (%s)" % e)
-if isinstance(parsed, dict): parsed = parsed.get("groups") or []
-if not isinstance(parsed, list):
-    bail("backlog-plan: --groups must be a JSON list of groups")
-
-# Ids are read from the group's OWN requirements field, never scraped from its prose. A
-# rationale that mentions FR-004 as the reason two others belong together would otherwise
-# pull a third requirement into the story, and nothing downstream would question it.
-work = rids(os.environ.get("AW_WORK", ""))
-groups, dropped = [], []
-for i, g in enumerate(parsed):
-    if not isinstance(g, dict): continue
-    src = g.get("requirements")
-    if isinstance(src, list): src = ", ".join(str(x) for x in src)
-    ids = rids(src if src is not None else g.get("requirements_csv", ""))
-    if work:
-        outside = [x for x in ids if x not in work]
-        dropped += outside
-        ids = [x for x in ids if x in work]
-    if not ids: continue
-    # `depends_on` names OTHER GROUPS by key, or open stories already in the backlog by
-    # id. Kept as raw tokens: a group key only becomes a story id once the plan has minted
-    # one, so resolving here would have to guess at a name that does not exist yet.
-    dep_src = g.get("depends_on")
-    if dep_src is None: dep_src = g.get("depends_on_csv")
-    if isinstance(dep_src, list): dep_src = ", ".join(str(x) for x in dep_src)
-    deps_raw = [x for x in re.split(r'[,\s\[\]"\']+', str(dep_src or "")) if x.strip()]
-    groups.append({"key": g.get("id") or ("g%d" % (i + 1)),
-                   "title": (g.get("title") or "").strip(),
-                   "rationale": (g.get("rationale") or "").strip(),
-                   "complexity": (g.get("complexity") or "").strip().lower(),
-                   "deps_raw": deps_raw,
-                   "ids": ids, "ids_csv": ", ".join(ids)})
-
-# Every work-set id must land in exactly one group. One the model left out gets no story
-# and nothing says so; one it repeated gets two, each claiming the same requirement.
-placed = [x for g in groups for x in g["ids"]]
-repeated = sorted({x for x in placed if placed.count(x) > 1})
-
-# A REPEATED ID IS RESOLVED HERE, not merely reported. Two groups both claiming one
-# requirement become two stories both claiming it, and "does this requirement still have
-# open stories" — the completeness rule — then answers for work that was never really
-# duplicated. The grouping is a judgment; the arithmetic over it is not. So the id stays in
-# the FIRST group that claimed it and leaves the rest, which is deterministic (the same
-# grouping always yields the same slices) and loses no coverage, because the id still
-# reaches exactly one story. repeated_notice reports what that touched.
-if repeated:
-    seen_ids = set()
-    for g in groups:
-        keep_ids = [x for x in g["ids"] if x not in seen_ids]
-        seen_ids.update(keep_ids)
-        g["ids"], g["ids_csv"] = keep_ids, ", ".join(keep_ids)
-    groups = [g for g in groups if g["ids"]]
-    placed = [x for g in groups for x in g["ids"]]
-
-missed = [x for x in work if x not in placed]
-
-def candidates_of(g):
-    """Open stories standing in front of this group, each with what it already covers OF
-    THIS GROUP — the intersection, not its whole citation list, because that is what the
-    author is being asked to move."""
-    out = []
-    for s in open_stories:
-        shared = [x for x in g["ids"] if x in s["cites"]]
-        if not shared: continue
-        out.append({"story": s["id"], "title": s["title"], "in_flight": s["in_flight"],
-                    "spec_version": s["spec_version"], "cites_csv": ", ".join(s["cites"]),
-                    "shared_csv": ", ".join(shared), "shared": shared,
-                    "group": g["key"], "group_title": g["title"], "group_ids_csv": g["ids_csv"],
-                    "action": "followon" if s["in_flight"] else "update"})
-    return sorted(out, key=lambda c: c["story"])
-
-base = {"ok": True, "feature": feature, "feature_dir": fd, "stories_dir": sdir,
-        "group_count": len(groups), "groups": groups,
-        "work_csv": ", ".join(work),
-        "unplaced_csv": ", ".join(missed), "unplaced_count": len(missed),
-        "repeated_csv": ", ".join(repeated), "repeated_count": len(repeated),
-        "dropped_csv": ", ".join(sorted(set(dropped))),
-        "groups_digest": "\n".join(
-            "  [%s] %s\n      requirements: %s%s%s"
-            % (g["key"], g["title"] or "(untitled)", g["ids_csv"],
-               ("\n      stands behind: " + ", ".join(g["deps_raw"])) if g["deps_raw"] else "",
-               ("\n      " + g["rationale"]) if g["rationale"] else "")
-            for g in groups) or "  (no groups)"}
-
-# THE STRATEGY IS THE AUTHOR'S; THE ARITHMETIC OVER IT IS NOT. `single` asked for one story
-# covering the whole work set, and the grouping may still have returned several — because a
-# slice nobody can pick up is not a story, and splitting it is the honest answer. So the
-# split is REPORTED rather than refused or hidden: quietly handing six stories to someone
-# who asked for one is the kind of silent disobedience that makes an option not worth having.
-strategy = (os.environ.get("AW_STRATEGY") or "").strip().lower() or "auto"
-try:
-    ceiling = int((os.environ.get("AW_CEILING") or "").strip() or 8)
-except ValueError:
-    ceiling = 8
-oversized = [g["key"] for g in groups if len(g["ids"]) > ceiling]
-split_note, split_count = "", 0
-if strategy == "single" and len(groups) > 1:
-    split_count = len(groups)
-    split_note = ("one story was asked for and the work set was too heavy for one: it is "
-                  "split into %d, in dependency order — %s" % (len(groups), "; ".join(
-                      "[%s] %s (%s)" % (g["key"], g["title"] or "untitled", g["ids_csv"])
-                      for g in groups)))
-elif strategy == "single" and len(groups) == 1:
-    split_note = ("one story was asked for and one covers the whole work set: %s"
-                  % groups[0]["ids_csv"])
-base.update(strategy=strategy, ceiling=ceiling, split_count=split_count,
-            split_note=split_note, oversized_csv=", ".join(oversized))
-
-if mode == "scan":
-    cands = [c for g in groups for c in candidates_of(g)]
-    lines = []
-    for c in cands:
-        lines.append(
-            "  %s  (%s)\n"
-            "      group [%s] %s covers %s\n"
-            "      this story already covers %s of it, and cites %s in total\n"
-            "      %s"
-            % (c["story"], c["title"] or "untitled",
-               c["group"], c["group_title"] or "", c["group_ids_csv"],
-               c["shared_csv"], c["cites_csv"],
-               ("ALREADY IN FLIGHT (story plan exists) — picking it mints a FOLLOW-ON "
-                "carrying the change; this story is never rewritten"
-                if c["in_flight"] else
-                "not started (no story plan yet) — picking it rewrites this story to "
-                "cover the whole group")))
-    base.update(candidates=cands, candidate_count=len(cands),
-                candidate_ids=[c["story"] for c in cands],
-                candidate_csv=", ".join(c["story"] for c in cands),
-                any_candidates=bool(cands),
-                ask_digest="\n".join(lines) or "  (no existing story covers any of these)")
-    print(json.dumps(base)); sys.exit(0)
-
-# ---- plan ------------------------------------------------------------------------
-approved = set(names(os.environ.get("AW_OK", "")))
-version = (os.environ.get("AW_VER") or "").strip()
-plan, skipped, notes = [], [], []
-for g in groups:
-    cands = candidates_of(g)
-    declined = [c for c in cands if c["story"] not in approved]
-    # A declined story keeps its requirements: the author said do not disturb it, and
-    # raising a second story over the same ids disturbs it just as thoroughly.
-    held = {x for c in declined for x in c["shared"]}
-    skipped += [c["story"] for c in declined]
-    remaining = [x for x in g["ids"] if x not in held]
-    taken = [c for c in cands if c["story"] in approved]
-
-    if taken:
-        # ONE APPROVED STORY ABSORBS THE GROUP'S UNCLAIMED REQUIREMENTS — the first by id.
-        # Every OTHER approved story keeps exactly the ids it already cites, so those ids
-        # are RESERVED out of what the carrier gains: two open stories both claiming one
-        # requirement is not a state the completeness rule can read, and the run would have
-        # created that state itself rather than merely reporting it.
-        carrier = taken[0]; s = by_id[carrier["story"]]
-        reserved = {x for c in taken[1:] for x in c["shared"]}
-        gained = [x for x in remaining if x not in reserved]
-        if carrier["in_flight"]:
-            # §5.5 — the original stays open and unchanged, and closes having delivered
-            # what it was written to deliver. The follow-on carries the remainder.
-            carry = [x for x in g["ids"] if x in s["cites"] or x in gained]
-            carry = [x for x in carry if x not in held]
-            sid = mint()
-            plan.append({"action": "followon", "story": sid, "follows": carrier["story"],
-                         "path": os.path.join(sdir, sid + ".md"),
-                         "requirements_csv": ", ".join(carry), "existing_csv": "",
-                         "prior_csv": ", ".join(s["cites"]), "prior_title": s["title"],
-                         "prior_path": s["path"],
-                         "group": g["key"], "group_title": g["title"],
-                         "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
-                         "rationale": g["rationale"], "spec_version": version})
-        else:
-            keep = sorted(set(s["cites"]) | set(gained),
-                          key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-            plan.append({"action": "update", "story": s["id"], "follows": "",
-                         "path": s["path"],
-                         "requirements_csv": ", ".join(keep),
-                         "existing_csv": ", ".join(s["cites"]),
-                         "prior_csv": ", ".join(s["cites"]), "prior_title": s["title"],
-                         "prior_path": s["path"],
-                         "group": g["key"], "group_title": g["title"],
-                         "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
-                         "rationale": g["rationale"], "spec_version": version})
-        carrier_sid = plan[-1]["story"]
-        for c in taken[1:]:
-            s2 = by_id[c["story"]]
-            if c["in_flight"]:
-                # AN IN-FLIGHT STORY IS NEVER REWRITTEN, whatever position it holds in the
-                # group. Its story plan was derived from this body, and
-                # rewriting the body leaves the three disagreeing with nothing to say so —
-                # which is the whole reason §5.5 exists. Being second in a group is not a
-                # different situation from being first, so it gets the same answer: its own
-                # follow-on, carrying the ids it already covers of this group.
-                #
-                # That link is also what clears its staleness. ledger-read discounts an
-                # in-flight story once an open story whose `follows` names it cites the same
-                # id; skipping it instead would leave it stale forever and re-offered on
-                # every run.
-                carry2 = [x for x in c["shared"] if x not in held]
-                if not carry2:
-                    notes.append("%s was approved and is in flight, but every requirement "
-                                 "it covers of group [%s] is held by a story left "
-                                 "untouched; nothing to carry" % (c["story"], g["key"]))
-                    continue
-                sid2 = mint()
-                notes.append("%s was approved and is IN FLIGHT, so it is not rewritten; "
-                             "%s carries %s forward from it, while %s takes the group's "
-                             "unclaimed requirements"
-                             % (c["story"], sid2, ", ".join(carry2), carrier_sid))
-                plan.append({"action": "followon", "story": sid2, "follows": c["story"],
-                             "path": os.path.join(sdir, sid2 + ".md"),
-                             "requirements_csv": ", ".join(carry2), "existing_csv": "",
-                             "prior_csv": ", ".join(s2["cites"]), "prior_title": s2["title"],
-                             "prior_path": s2["path"],
-                             "group": g["key"], "group_title": g["title"],
-                             "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
-                             "rationale": g["rationale"], "spec_version": version})
-                continue
-            notes.append("%s was approved but %s takes the group's unclaimed requirements; "
-                         "%s is refreshed against the current spec without gaining ids"
-                         % (c["story"], carrier_sid, c["story"]))
-            plan.append({"action": "update", "story": s2["id"], "follows": "",
-                         "path": s2["path"],
-                         "requirements_csv": ", ".join(s2["cites"]),
-                         "existing_csv": ", ".join(s2["cites"]),
-                         "prior_csv": ", ".join(s2["cites"]), "prior_title": s2["title"],
-                         "prior_path": s2["path"],
-                         "group": g["key"], "group_title": g["title"],
-                         "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
-                         "rationale": g["rationale"], "spec_version": version})
-    elif remaining:
-        sid = mint()
-        # A REQUIREMENT WHOSE ONLY STORIES ARE CLOSED RE-ENTERS THE WORK SET, and that is
-        # right: a version row above the closed story's stamp means the contract moved
-        # AFTER it shipped, so what shipped is no longer what the spec asks for. It reads
-        # as duplicated work to anyone who remembers delivering it, so the run names the
-        # story it is re-opening against rather than leaving them to find it.
-        shipped = ["%s (%s)" % (d["id"], ", ".join(x for x in remaining if x in d["cites"]))
-                   for d in done_stories if any(x in d["cites"] for x in remaining)]
-        if shipped:
-            notes.append("%s covers requirements already delivered by %s — the spec moved "
-                         "after those closed, so this is the change, not a repeat"
-                         % (sid, "; ".join(shipped)))
-        plan.append({"action": "create", "story": sid, "follows": "",
-                     "path": os.path.join(sdir, sid + ".md"),
-                     "requirements_csv": ", ".join(remaining), "existing_csv": "",
-                     "prior_csv": "", "prior_title": "", "prior_path": "",
-                     "group": g["key"], "group_title": g["title"],
-                     "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
-                     "rationale": g["rationale"], "spec_version": version})
-    else:
-        notes.append("group [%s] (%s) is entirely covered by stories left untouched; "
-                     "nothing to write" % (g["key"], g["ids_csv"]))
-
-# ---- waves: the order these stories can actually be picked up in -------------------
-# The grouping declared which slices stand behind which; turning that into an order is
-# arithmetic, so it happens here and not in the prompt — the same grouping always yields
-# the same waves.
-#
-# A WAVE IS AN ELIGIBILITY LEVEL, NOT A SCHEDULE. Wave N means every story this one depends
-# on sits in a wave below N. Two stories in the SAME wave therefore have no dependency
-# between them and may be picked up in parallel; it does not say they start together, and
-# nothing waits for a whole wave to finish. That is also why the number is not a priority:
-# wave 1 is "nothing blocks this", not "do this first".
-#
-# THE EDGE SET IS A UNION of what the grouping declared and what an updated story already
-# carries in `depends_on:`. The sync sees one feature's spec; an edge someone added by hand
-# may name work it has no view of, and dropping it would silently un-order real work. Both
-# are claims about CODE ordering, and the union is exactly what the story ends up citing —
-# so the wave and the frontmatter cannot disagree about what stands in front of what.
-#
-# `follows:` is NOT an edge. A follow-on carries the remainder of a story in flight, and the
-# remainder is often buildable alongside it — §5.5 asks the author to say in Notes which
-# half has to land first. Making it an implicit edge would put an ordering in the waves that
-# no frontmatter field explains.
-entries_of, by_story = {}, {}
-for e in plan:
-    entries_of.setdefault(e["group"], []).append(e["story"]); by_story[e["story"]] = e
-preds = {e["story"]: set() for e in plan}
-external, unresolved = {}, []      # stories outside this run, at the wave they declare
-
-for g in groups:
-    tgt = entries_of.get(g["key"], [])
-    if not tgt: continue           # the group wrote nothing; its edges order nothing
-    for tok in g["deps_raw"]:
-        tok = tok.strip()
-        if not tok or tok == g["key"]: continue
-        if tok in entries_of:
-            src = entries_of[tok]
-        elif tok in by_id and by_id[tok]["status"] == "open":
-            external[tok] = by_id[tok]["wave"]; src = [tok]
-        else:
-            unresolved.append("%s (named by group [%s])" % (tok, g["key"])); continue
-        for x in tgt: preds[x].update(s for s in src if s != x)
-
-for e in plan:
-    if e["action"] != "update": continue
-    for d in by_id.get(e["story"], {}).get("deps", []):
-        if d == e["story"] or d in preds[e["story"]]: continue
-        if d not in preds: external[d] = by_id[d]["wave"] if d in by_id else 1
-        preds[e["story"]].add(d)
-
-# A CYCLE IS REJECTED AT AUTHORING TIME (§6.1), and this is where it would be authored.
-# Depth-first over a sorted node order, dropping the one edge that closes each cycle: only
-# edges that actually close one are lost, and the choice is deterministic — the same
-# grouping always breaks the same edge. Reported, because a dropped edge was a real claim
-# about ordering and the cycle it sat in is a fact about the slicing, not a glitch.
-cycles, state = [], {}
-def walk(node):
-    state[node] = 1
-    for m in sorted(preds.get(node, ())):
-        if state.get(m) == 1:
-            preds[node].discard(m); cycles.append("%s -> %s" % (node, m)); continue
-        if state.get(m) != 2 and m in preds: walk(m)
-    state[node] = 2
-for node in sorted(preds):
-    if state.get(node) != 2: walk(node)
-
-# Longest path from a root, relaxed to a fixed point. A story with no dependency is wave 1,
-# which is what puts every independent story in the same wave.
-wave = dict(external)
-for _ in range(len(preds) + 1):
-    moved = False
-    for node in sorted(preds):
-        w = 1 + max([wave.get(m, 1) for m in preds[node]] or [0])
-        if wave.get(node) != w: wave[node] = w; moved = True
-    if not moved: break
-for e in plan:
-    e["wave"] = wave.get(e["story"], 1)
-    e["depends_on_csv"] = ", ".join(sorted(preds.get(e["story"], ())))
-
-# Written in wave order, so a run that meets the cap writes the stories that can be STARTED
-# rather than an arbitrary prefix of them. The story id is not the order — the wave is.
-plan.sort(key=lambda e: (e["wave"], e["story"]))
-for i, e in enumerate(plan): e["seq"] = i + 1
-
-waves = {}
-for e in plan: waves.setdefault(e["wave"], []).append(e["story"])
-wave_digest = "\n".join("  wave %d: %s" % (w, ", ".join(waves[w]))
-                        for w in sorted(waves)) or "  (nothing to write)"
-if unresolved:
-    notes.append("the grouping named dependencies matching no slice and no open story, so "
-                 "they set no order: %s" % "; ".join(sorted(set(unresolved))))
-if cycles:
-    notes.append("slices were declared to depend on each other in a cycle; the edge closing "
-                 "each one is dropped, because a backlog with no order at all is worse than "
-                 "one missing an edge someone can re-add: %s" % ", ".join(cycles))
-
-# THE WRITE LOOP HAS A CEILING AND THE ENGINE DOES NOT SAY WHEN IT HITS IT — `over:` stops
-# at max_iterations with no message, so plan entries past it are simply never written and
-# the run reports success. The caller passes its own ceiling here so the overflow is named
-# while the story ids still exist to name. Nothing is dropped from the plan: the ids are
-# reported and the entries stay, so raising the cap and re-running writes them.
-try:
-    cap = int((os.environ.get("AW_CAP") or "").strip() or 0)
-except ValueError:
-    cap = 0
-overflow = [e["story"] for e in plan[cap:]] if cap > 0 else []
-
-counts = {a: sum(1 for e in plan if e["action"] == a) for a in ("create", "update", "followon")}
-base.update(plan=plan, plan_count=len(plan), any_plan=bool(plan),
-            cap=cap, overflow_csv=", ".join(overflow), overflow_count=len(overflow),
-            create_count=counts["create"], update_count=counts["update"],
-            followon_count=counts["followon"],
-            skipped_csv=", ".join(sorted(set(skipped))),
-            stories_csv=", ".join(e["story"] for e in plan),
-            wave_digest=wave_digest, wave_count=len(waves),
-            max_wave=(max(waves) if waves else 0),
-            cycle_csv=", ".join(cycles),
-            unresolved_deps_csv=", ".join(sorted(set(unresolved))),
-            notes=notes, notes_text="\n".join("  - " + n for n in notes),
-            plan_digest="\n".join(
-                "  w%-3d %-9s %-16s %s%s%s"
-                % (e["wave"], e["action"], e["story"], e["requirements_csv"],
-                   ("  (follows %s)" % e["follows"]) if e["follows"] else "",
-                   ("  [after %s]" % e["depends_on_csv"]) if e["depends_on_csv"] else "")
-                for e in plan) or "  (nothing to write)")
-print(json.dumps(base))
-PY
-}
-
-# ─────────────────────────────── story-stamp ───────────────────────────────
-# The story's frontmatter is the gate surface — `exercises:`, `spec_version:`, `status:`
-# and `follows:` are what spec-coverage, check-stories, analyze-slice and close-story read,
-# and none of them opens the body. So those fields are OBSERVED and written by the kit, not
-# declared by the model that wrote the prose, for the same reason the Change History row is
-# computed rather than announced: a model that drops one id from `exercises:` produces a
-# story that reads perfectly and is invisible to every gate built to protect it. Silent,
-# and in the one field where silence costs the most.
-#
-# Everything else in the block is left exactly as the author wrote it, and a key the file
-# is missing is appended in template order rather than the block being rebuilt — a story
-# carrying a work_item or a depends_on must not lose it to a stamp.
-cmd_story_stamp() {
-    local fd_arg="" story="" ids="" version="" follows="" ids_given="" title="" deps="" wave=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --story)   story="$2";   shift 2 ;;
-            --ids)     ids="$2"; ids_given=1; shift 2 ;;
-            --version) version="$2"; shift 2 ;;
-            --follows) follows="$2"; shift 2 ;;
-            --title)   title="$2";   shift 2 ;;
-            --depends-on) deps="$2"; shift 2 ;;
-            --wave)    wave="$2";    shift 2 ;;
-            --help|-h) echo "story-stamp --story <id> [--ids <csv>] [--version <v>] [--follows <id>] [--title <t>] [--depends-on <csv>] [--wave <n>] [--feature-dir <p>]"; return 0 ;;
-            *) echo "story-stamp: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    [ -n "$story" ] || { echo "story-stamp: --story is required" >&2; return 1; }
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-stamp: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_STORY="$story" AW_IDS="$ids" AW_IDS_GIVEN="$ids_given" \
-    AW_VER="$version" AW_FOLLOWS="$follows" AW_TITLE="$title" \
-    AW_DEPS="$deps" AW_WAVE="$wave" python3 - <<'PY'
-import json, os, re, sys, datetime
-fd = os.environ["AW_FD"]; story = os.environ["AW_STORY"].strip()
-path = os.path.join(fd, "stories", story + ".md")
-
-def bail(msg, code=2):
-    print(json.dumps({"ok": False, "story": story, "path": path, "error": msg}))
-    sys.stderr.write(msg + "\n"); sys.exit(code)
-
-if not os.path.isfile(path):
-    bail("story-stamp: no story file at %s — the authoring step did not write it" % path)
-
-def rids(s):
-    seen, out = set(), []
-    for t in re.findall(r'\b(?:FR|BR)-\d+', s or ""):
-        if t not in seen: seen.add(t); out.append(t)
-    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
-
-def sids(s):
-    """Story ids out of a csv or an inline list. A story id is a feature name and a number;
-    the template's placeholders are neither, and must not become a dependency edge."""
-    seen, out = set(), []
-    for t in re.split(r'[,\s\[\]"\']+', s or ""):
-        t = t.strip()
-        if re.match(r'^[A-Za-z][\w.]*-\d+$', t) and t not in seen:
-            seen.add(t); out.append(t)
-    return out
-
-text = open(path, encoding="utf-8", errors="replace").read()
-m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
-if m:
-    block, body = m.group(1), text[m.end():]
-else:
-    # A model that returned the prose and no frontmatter leaves a story every gate skips.
-    # Synthesised rather than refused: the body is the expensive half and it is already on
-    # disk, and the fields below are exactly the ones this op is authoritative for.
-    block, body = "", text.lstrip("\n")
-
-# The block as an ordered list of (key, rendered line), so an unrecognised key and its
-# continuation lines survive untouched.
-lines = block.split("\n") if block else []
-order, seen_key = [], None
-for line in lines:
-    km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
-    if km:
-        seen_key = km.group(1); order.append([seen_key, [line]])
-    elif order and (line.startswith(" ") or line.startswith("\t")):
-        order[-1][1].append(line)          # a block-list item under the key above
-    elif line.strip():
-        order.append([None, [line]])
-
-def put(key, value):
-    """Set a key to a single-line value, collapsing a block list into the inline form."""
-    line = ("%s: %s" % (key, value)) if value != "" else ("%s:" % key)
-    for entry in order:
-        if entry[0] == key:
-            entry[1] = [line]
-            return "set"
-    order.append([key, [line]])
-    return "added"
-
-TEMPLATE_ORDER = ["id", "type", "status", "title", "exercises", "spec_version",
-                  "depends_on", "wave", "follows", "work_item", "created"]
-def get(key):
-    for entry in order:
-        if entry[0] == key: return entry[1][0].split(":", 1)[1].strip()
-    return ""
-
-changed = {}
-changed["id"] = put("id", story)
-
-if os.environ.get("AW_IDS_GIVEN"):
-    ids = rids(os.environ.get("AW_IDS", ""))
-    changed["exercises"] = put("exercises", "[" + ", ".join(ids) + "]")
-else:
-    ids = rids(get("exercises"))
-
-ver = (os.environ.get("AW_VER") or "").strip()
-if ver: changed["spec_version"] = put("spec_version", ver)
-
-fol = (os.environ.get("AW_FOLLOWS") or "").strip()
-if fol: changed["follows"] = put("follows", fol)
-
-ttl = (os.environ.get("AW_TITLE") or "").strip()
-if ttl and (not get("title") or get("title").startswith("[")):
-    changed["title"] = put("title", ttl)
-
-# Placeholders the template ships. Left alone once a real value is in them, so a story
-# CLOSED between the plan and the write is not quietly re-opened by a stamp.
-if not get("type") or get("type").startswith("["):
-    changed["type"] = put("type", "functional" if ids else "technical")
-if not get("status") or get("status").startswith("["):
-    changed["status"] = put("status", "open")
-# ORDERING IS A UNION, NEVER A REPLACEMENT. The edges passed in are what this run's slicing
-# declared; the ones already in the file may name work outside this feature, which the sync
-# cannot see. Dropping either loses a real claim about what has to land first, and a lost
-# edge is silent — no later stage re-derives it.
-deps = sorted(set(sids(get("depends_on")) + sids(os.environ.get("AW_DEPS", ""))) - {story})
-if deps or not get("depends_on") or get("depends_on").startswith("["):
-    changed["depends_on"] = put("depends_on", "[" + ", ".join(deps) + "]")
-
-# THE WAVE IS AN ELIGIBILITY LEVEL, NOT A PRIORITY: every story this one depends on sits in
-# a lower one, so stories sharing a wave have no ordering between them and may be picked up
-# in parallel. Computed by backlog-plan from `depends_on`, and written here for the same
-# reason `exercises:` is — a field the gates and the listings read is observed, not declared.
-# A story stamped without one floors at 1: nothing is KNOWN to have to land before it.
-wv = (os.environ.get("AW_WAVE") or "").strip()
-if wv.isdigit():
-    changed["wave"] = put("wave", wv)
-elif not get("wave").isdigit():
-    changed["wave"] = put("wave", "1")
-if not get("created") or get("created").startswith("["):
-    changed["created"] = put("created", datetime.date.today().isoformat())
-for k in ("title", "follows", "work_item"):
-    if not any(e[0] == k for e in order): put(k, "")
-
-# Rendered back in template order, with anything unrecognised kept after it in the order it
-# was written. A story is read by people as well as by gates.
-rank = {k: i for i, k in enumerate(TEMPLATE_ORDER)}
-order.sort(key=lambda e: rank.get(e[0], len(TEMPLATE_ORDER)))
-out_block = "\n".join(l for e in order for l in e[1])
-open(path, "w", encoding="utf-8").write("---\n" + out_block + "\n---\n\n" + body.lstrip("\n"))
-
-print(json.dumps({"ok": True, "story": story, "path": path,
-                  "exercises": ids, "exercises_csv": ", ".join(ids),
-                  "spec_version": get("spec_version"), "status": get("status"),
-                  "depends_on": get("depends_on"), "wave": get("wave"),
-                  "follows": get("follows"), "title": get("title"),
-                  "type": get("type"), "had_frontmatter": bool(m),
-                  "fields": sorted(changed)}))
-PY
-}
-
-# ────────────────────────────── spec-preserve ──────────────────────────────
-# Set subtraction with a purpose: of the requirements this run disturbed, which ones was
-# it NOT given permission to change. The approved list comes from a multi-select ask, so
-# the complement is what the re-author has to restore. Kept as its own subcommand because
-# the orchestrator has no expressions — a workflow can bind a value, never compute one.
-cmd_spec_preserve() {
-    local disturbing="" approved="" preserved="" mode="complement"
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --disturbing) disturbing="$2"; shift 2 ;;
-            --approved) approved="$2"; shift 2 ;;
-            --preserved) preserved="$2"; shift 2 ;;
-            --verify) mode="verify"; shift ;;
-            --help|-h) echo "spec-preserve --disturbing <csv> --approved <csv>"; echo "spec-preserve --verify --preserved <csv> --disturbing <csv>"; return 0 ;;
-            *) echo "spec-preserve: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    AW_DIST="$disturbing" AW_OK="$approved" AW_PRE="$preserved" AW_MODE="$mode" python3 - <<'PY'
-import json, os, re
-def ids(s):
-    seen, out = set(), []
-    for t in re.findall(r'[A-Z]{2}-\d+', s or ""):
-        if t not in seen: seen.add(t); out.append(t)
-    return out
-mode = os.environ.get("AW_MODE", "complement")
-dist, ok = ids(os.environ.get("AW_DIST", "")), ids(os.environ.get("AW_OK", ""))
-if mode == "verify":
-    # DID THE RESTORE ACTUALLY HOLD. The re-author is a model asked to put requirements back
-    # to their earlier wording; nothing until now checked that it did. The diff taken after
-    # it is the proof: a requirement the author refused to move must no longer appear in the
-    # disturbing set. One that still does was amended WITHOUT approval — and the run would
-    # otherwise report it, in the same breath, as having been left alone.
-    pre = ids(os.environ.get("AW_PRE", ""))
-    violated = [d for d in pre if d in dist]
-    held = [d for d in pre if d not in dist]
-    print(json.dumps({"ok": not violated, "mode": "verify", "preserved": pre,
-                      "held": held, "held_csv": ", ".join(held), "held_count": len(held),
-                      "violated": violated, "violated_csv": ", ".join(violated),
-                      "violated_count": len(violated), "restore_ok": not violated}))
-else:
-    preserve = [d for d in dist if d not in ok]
-    print(json.dumps({"ok": True, "mode": "complement", "disturbing": dist, "approved": ok,
-                      "preserve": preserve,
-                      "preserve_csv": ", ".join(preserve), "preserve_count": len(preserve),
-                      "approved_csv": ", ".join(ok)}))
-PY
-}
-
-# ────────────────────────────── spec-markers ───────────────────────────────
-# Are there any [NEEDS CLARIFICATION] markers to resolve. Deterministic and free, which is
-# the point: asking a model "are there any markers" costs a full round trip on every run to
-# hear "no" on most of them. The model is still what turns a marker into a question with
-# answerable options — this only decides whether to call it at all.
-cmd_spec_markers() {
-    local fd_arg=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --help|-h) echo "spec-markers [--feature-dir <path>]"; return 0 ;;
-            *) echo "spec-markers: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-markers: no feature set and no --feature-dir" >&2; return 1; }
-    AW_SPEC="$fd/spec.md" python3 - <<'PY'
-import json, os, re
-spec = os.environ["AW_SPEC"]
-text = open(spec, encoding="utf-8", errors="replace").read() if os.path.isfile(spec) else ""
-found = [" ".join(f.split()) for f in re.findall(r'\[NEEDS CLARIFICATION:\s*(.*?)\]', text, re.S)]
-print(json.dumps({"ok": True, "spec_exists": bool(text), "markers": found,
-                  "marker_count": len(found), "any": bool(found)}))
-PY
-}
-
-# ───────────────────────── spec-snapshot / spec-diff ───────────────────────
-# What a run CHANGED, observed rather than declared. specify snapshots spec.md before
-# it authors and diffs after the converge loop has finished with it, so the Change
-# History row is computed from the document's own requirement ids.
-#
-# Deriving the row this way is what makes it trustworthy. A row the model declares can
-# omit a requirement the converge loop rewrote on its way past — and an omitted id is
-# the silent case the whole ledger exists to prevent, since sync-stories would never
-# learn that requirement moved. A row computed from the diff cannot omit one.
-#
-# Ids are read in both shapes the template uses: the bold form of the list sections
-# (`- **FR-001**: …`) and the leading-cell form of the Data Classification table
-# (`| DC-001 | … |`). The line is normalised on whitespace before hashing, so a rewrap
-# is not a change.
-cmd_spec_snapshot() {
-    local fd_arg=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --help|-h) echo "spec-snapshot [--feature-dir <path>]"; return 0 ;;
-            *) echo "spec-snapshot: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-snapshot: no feature set and no --feature-dir" >&2; return 1; }
-    local spec="$fd/spec.md"
-    local snap=""
-    if [ -f "$spec" ]; then
-        # BESIDE THE SPEC, not in the system temp directory. Only the PATH is replay-cached,
-        # and the step is not re-run on resume — so a checkpointed run paused for a human
-        # answer could outlive the temp file. A cleaned temp dir then left spec-diff with no
-        # before-state at all: every id read as ADDED, nothing MODIFIED, so the E38 ask never
-        # fired, the ledger row named every requirement in the document, and every open story
-        # went stale for a change that touched none of them. Beside the spec it shares the
-        # file's lifetime and travels with the repository.
-        #
-        # One snapshot per feature, overwritten each run: a run diffs against it TWICE, once
-        # to see what changed and again after re-authoring a change made additively.
-        snap="$fd/.aw-snapshot.md"
-        cp "$spec" "$snap"
-    fi
-    printf '{"snapshot":"%s","taken":%s}\n' "$(json_escape "$snap")" "$([ -n "$snap" ] && echo true || echo false)"
-}
-
-cmd_spec_diff() {
-    local fd_arg="" snap=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --snapshot) snap="$2"; shift 2 ;;
-            --help|-h) echo "spec-diff --snapshot <path> [--feature-dir <path>]"; return 0 ;;
-            *) echo "spec-diff: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-diff: no feature set and no --feature-dir" >&2; return 1; }
-    AW_SNAP="$snap" AW_SPEC="$fd/spec.md" python3 - <<'PY'
-import json, os, re, hashlib, sys
-snap = os.environ.get("AW_SNAP", ""); spec = os.environ["AW_SPEC"]
-# ASKING FOR NO BEFORE-STATE IS NOT THE SAME AS LOSING ONE. An empty --snapshot is the
-# bootstrap path saying "there was nothing before this run", and every id is legitimately
-# added. A path that was given and is not there is the before-state having been LOST, and
-# answering that with "everything is new" is the loudest possible wrong answer: it marks
-# every story in the feature stale for a change that touched none of them.
-if snap and not os.path.isfile(snap):
-    msg = ("spec-diff: the before-state at %s is gone, so this run cannot tell what it "
-           "changed. spec.md HAS been written. Recover by hand: put the ids you changed "
-           "into a new Change History row, then re-run spec-stamp to re-baseline."
-           % snap)
-    print(json.dumps({"ok": False, "error": msg, "had_snapshot": False, "snapshot": snap}))
-    sys.stderr.write(msg + "\n"); sys.exit(2)
-# An id is keyed to the line that DEFINES it, never to a line that merely mentions it.
-# The four shapes are scored, best wins, earliest line breaks a tie:
-#   3  a leading table cell          | DC-001 | … |
-#   3  a bold id opening a bullet    - **FR-001**: THE SYSTEM SHALL …
-#   2  a bold id opening a line      **FR-001** …            (a definition missing its colon)
-#   1  a bold id anywhere            … narrowing **FR-001**. (a cross-reference)
-# Scoring rather than "first bold id on the line, last line wins": a note that OPENS with
-# a cross-reference — "**FR-005** remains in force; **FR-006** narrows it" — re-keyed
-# FR-005 to that note, so a requirement restored character-for-character was reported as
-# MODIFIED. That is the worst possible misreading here, because the additive path exists
-# precisely to leave such a requirement alone, and its own instructions ask the author to
-# name the id in the new requirement's text.
-DEF_CELL = re.compile(r'^\s*\|\s*([A-Z]{2}-\d+)\s*\|')
-DEF_BULL = re.compile(r'^\s*(?:[-*+]\s+)?\*\*([A-Z]{2}-\d+)\*\*\s*[:\u2014\u2013-]')
-DEF_OPEN = re.compile(r'^\s*(?:[-*+]\s+)?\*\*([A-Z]{2}-\d+)\*\*')
-ANY_BOLD = re.compile(r'\*\*([A-Z]{2}-\d+)\*\*')
-# The Story Coverage block lists requirement ids in a table, so it reads exactly like the
-# Data Classification section to DEF_CELL. Left in, every story raised against FR-003 would
-# show up here as FR-003 having CHANGED — a version row, and every story citing it stale,
-# because somebody wrote a story.
-COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
-# The ledger's own rows name ids in prose cells; they record history, they do not define a
-# requirement, and the table is stripped before the scan for the same reason as coverage.
-HIST = re.compile(r'^##\s+Change History\s*$', re.M)
-def is_def(l):
-    return bool(DEF_CELL.match(l) or DEF_BULL.match(l) or DEF_OPEN.match(l))
-def scan(path):
-    """{id: (score, line_no, hash)} for every id the document mentions."""
-    best = {}
-    if not path or not os.path.isfile(path): return best
-    text = COV.sub("", open(path, encoding="utf-8", errors="replace").read())
-    hm = HIST.search(text)
-    if hm: text = text[:hm.start()]
-    lines = text.split("\n")
-    for n, line in enumerate(lines):
-        hits = []
-        m = DEF_CELL.match(line)
-        if m: hits.append((3, m.group(1)))
-        m = DEF_BULL.match(line)
-        if m: hits.append((3, m.group(1)))
-        else:
-            m = DEF_OPEN.match(line)
-            if m: hits.append((2, m.group(1)))
-        for rid in ANY_BOLD.findall(line):
-            hits.append((1, rid))
-        for score, rid in hits:
-            if rid not in best or score > best[rid][0]:
-                best[rid] = (score, n)
-    # THE WHOLE REQUIREMENT, not the line its id sits on. A requirement that wraps carries
-    # half its meaning on the continuation lines, and hashing only the id's own line made an
-    # edit below the fold invisible: change_count 0, no ledger row appended, and spec-stamp
-    # re-baselining the new body as clean — the ledger's own silent failure, for every story
-    # citing that id. The block runs to the next definition, heading or blank line, and is
-    # whitespace-normalised as ONE string, so a rewrap across lines is still not a change.
-    out = {}
-    for rid, (score, n) in best.items():
-        block = [lines[n]]
-        for m2 in range(n + 1, len(lines)):
-            nxt = lines[m2]
-            if not nxt.strip() or nxt.lstrip().startswith("#") or is_def(nxt): break
-            block.append(nxt)
-        h = hashlib.sha256(" ".join(" ".join(block).split()).encode()).hexdigest()[:16]
-        out[rid] = (score, n, h)
-    return out
-def ids(path):
-    return {k: v[2] for k, v in scan(path).items()}
-# Ids the ledger has already spent. An id is PERMANENT: re-issuing one silently re-points
-# stories, designs and code that have already shipped. Read from the SNAPSHOT's history, so
-# it is what the ledger said before this run, and only meaningful when there is a snapshot.
-def spent(path):
-    if not path or not os.path.isfile(path): return set()
-    text = open(path, encoding="utf-8", errors="replace").read()
-    hm = HIST.search(text)
-    if not hm: return set()
-    return set(re.findall(r'[A-Z]{2}-\d+', text[hm.end():]))
-before, after = ids(snap), ids(spec)
-added    = sorted(k for k in after if k not in before)
-removed  = sorted(k for k in before if k not in after)
-modified = sorted(k for k in after if k in before and before[k] != after[k])
-changed  = sorted(set(added) | set(removed) | set(modified))
-reissued = sorted(set(added) & spent(snap))
-# THE STORY-FACING SUBSET. A story cites FR- and BR- ids and nothing else, so those are the
-# only classes the backlog can act on — the same scoping spec-coverage applies, for the same
-# reason. The scan is deliberately class-blind (CN-/DC-/IC-/UX-/SC- all move the contract and
-# all belong in the ledger row), but handing that whole set to sync-stories as "the
-# requirements this run touched" asks it to raise a story for a success criterion.
-STORY_CLASS = ("FR-", "BR-")
-story_ids = [c for c in changed if c.startswith(STORY_CLASS)]
-print(json.dumps({
-    "ok": True, "had_snapshot": bool(snap and os.path.isfile(snap)),
-    "added": added, "removed": removed, "modified": modified,
-    "changed": changed, "changed_csv": ", ".join(changed),
-    "change_count": len(changed),
-    "added_csv": ", ".join(added),
-    # removed ids orphan every story citing them (E1) — carried out so the caller can say so
-    "removed_csv": ", ".join(removed),
-    "modified_csv": ", ".join(modified),
-    # What an existing story would feel. An ADDED requirement disturbs nobody: no story
-    # cites an id that did not exist a moment ago. Modifying or removing one moves ground
-    # somebody may already be standing on, which is the set worth asking about.
-    "disturbing": sorted(set(modified) | set(removed)),
-    "disturbing_csv": ", ".join(sorted(set(modified) | set(removed))),
-    # An id this run introduced that the ledger has already spent. Detected, not blocked:
-    # the document is written by the time we can see it, and refusing here would leave a
-    # spec on disk that the next run's entry check would refuse too.
-    "reissued": reissued, "reissued_csv": ", ".join(reissued),
-    "reissued_any": bool(reissued),
-    # changed, narrowed to the classes a story can cite — what sync-stories works from.
-    "story_ids": story_ids, "story_ids_csv": ", ".join(story_ids),
-    "story_id_count": len(story_ids),
-}))
-PY
-    return 0
-}
-
-cmd_spec_check()    { _spec_ledger_cmd "check"  "$@"; }
-cmd_spec_stamp()    { _spec_ledger_cmd "stamp"  "$@"; }
-cmd_ledger_append() { _spec_ledger_cmd "append" "$@"; }
-cmd_ledger_ids()    { _spec_ledger_cmd "rowids" "$@"; }
-_spec_ledger_cmd() {   # $1 = op, then --feature-dir / --ids / --summary
-    local op="$1"; shift
-    local fd_arg="" ids="" summary=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --ids) ids="$2"; shift 2 ;;
-            --summary) summary="$2"; shift 2 ;;
-            --help|-h) echo "$op [--feature-dir <path>] [--ids <FR-001, BR-002>] [--summary <text>]"; return 0 ;;
-            *) echo "$op: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "$op: no feature set and no --feature-dir" >&2; return 1; }
-    # The delta-spec template, so `check` can tell an AUTHORED delta from the untouched copy
-    # cr-setup scaffolds for every change it opens.
-    local dtpl; dtpl=$(resolve_template "delta-spec-template" "$repo_root") || true
-    _spec_ledger "$fd" "$op" "$ids" "$summary" "$dtpl"
-}
-
 
 
 # ─────────────────────────────── feature-paths ─────────────────────────────
@@ -2984,19 +1523,27 @@ cmd_feature_paths() {
     fi
     [[ "$fd" != /* ]] && fd="$repo_root/$fd"
     local feature; feature=$(basename "$fd")   # the aggregate name (feature = specs/<Feature>)
-    # The master documents of a feature: spec.md (WHAT/WHY) + design.md (the service
-    # lane's HOW) + design.ui.md (the frontend lane's HOW, where the feature has a UI
-    # half). plan.md / tasks.md belonged to the retired /aw-spec-plan + /aw-spec-tasks
-    # phases and had zero consumers.
+    # The master documents of a feature: spec.md (WHAT/WHY) + one LANE PLAN per declared
+    # lane (each lane's HOW) — backend-plan.md for the service lane, frontend-plan.md for
+    # the frontend lane. `plan` writes them; nothing else does.
+    #
+    # LEGACY NAMES RESOLVE TOO. A feature authored before the lane split carries design.md
+    # / design.ui.md, so each lane resolves to its plan document when that exists and to
+    # the legacy name while it does not. Every reader therefore finds the document that is
+    # actually on disk, and plan-scaffold renames it into the plan name on the next `plan`
+    # run — which is what keeps the rename incremental instead of a flag day.
+    # design_file / ui_design_file are kept as ALIASES of the same two resolved paths, so
+    # a stage that has not been repointed yet reads the right document under its old key.
     #
     # ui_design_exists IS THE UI-HALF SIGNAL for the whole CR loop. Every delta stage
     # asks the same question — is there a UI master to keep in sync? — and the master's
     # own presence answers it without re-deriving the lane declaration and the slice's
-    # UI file count at each stage. It is also self-correcting: whatever authors
-    # design.ui.md (adopt today) enrolls the feature in the UI half of the delta loop
-    # by the act of writing the file.
-    local spec="$fd/spec.md" design="$fd/design.md" ui_design="$fd/design.ui.md"
-    local backend_plan="$fd/backend-plan.md" frontend_plan="$fd/frontend-plan.md"
+    # UI file count at each stage. It is also self-correcting: whatever authors the
+    # frontend plan enrolls the feature in the UI half of the delta loop by the act of
+    # writing the file.
+    local spec="$fd/spec.md" design="$fd/backend-plan.md" ui_design="$fd/frontend-plan.md"
+    [ ! -f "$design" ]    && [ -f "$fd/design.md" ]    && design="$fd/design.md"
+    [ ! -f "$ui_design" ] && [ -f "$fd/design.ui.md" ] && ui_design="$fd/design.ui.md"
     # needs_bootstrap, not spec_exists, is what picks specify's branch. A crashed first run
     # leaves spec.md on disk with the marker still up, and branching on the file alone read
     # that as a spec to EXTEND — re-applying the same input over an unfinished v1.0.
@@ -3005,15 +1552,13 @@ cmd_feature_paths() {
     local spec_exists=false;      [ -f "$spec" ]      && spec_exists=true
     local design_exists=false;    [ -f "$design" ]    && design_exists=true
     local ui_design_exists=false; [ -f "$ui_design" ] && ui_design_exists=true
-    local backend_plan_exists=false;  [ -f "$backend_plan" ]  && backend_plan_exists=true
-    local frontend_plan_exists=false; [ -f "$frontend_plan" ] && frontend_plan_exists=true
     local needs_bootstrap=false
     [ "$spec_exists" = false ] && needs_bootstrap=true
     [ "$bootstrap_pending" = true ] && needs_bootstrap=true
-    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","design_file":"%s","ui_design_file":"%s","backend_plan_file":"%s","frontend_plan_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"backend_plan_exists":%s,"frontend_plan_exists":%s,"bootstrap_pending":%s,"needs_bootstrap":%s}\n' \
-        "$(json_escape "$feature")" "$(json_escape "$fd")" "$(json_escape "$spec")" "$(json_escape "$design")" \
-        "$(json_escape "$ui_design")" "$(json_escape "$backend_plan")" "$(json_escape "$frontend_plan")" \
-        "$spec_exists" "$design_exists" "$ui_design_exists" "$backend_plan_exists" "$frontend_plan_exists" \
+    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","backend_plan":"%s","frontend_plan":"%s","backend_plan_exists":%s,"frontend_plan_exists":%s,"design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"bootstrap_pending":%s,"needs_bootstrap":%s}\n' \
+        "$(json_escape "$feature")" "$(json_escape "$fd")" "$(json_escape "$spec")" \
+        "$(json_escape "$design")" "$(json_escape "$ui_design")" "$design_exists" "$ui_design_exists" \
+        "$(json_escape "$design")" "$(json_escape "$ui_design")" "$spec_exists" "$design_exists" "$ui_design_exists" \
         "$bootstrap_pending" "$needs_bootstrap"
 }
 
@@ -3136,12 +1681,33 @@ _project_markers() {
       | sed "s#^$repo_root/##" | LC_ALL=C sort | head -20
 }
 
+# Does a manifest belong to the ecosystem the caller asked about. The repo-scope fallback
+# below is deliberate — a .NET solution legitimately sits ABOVE the lane it scaffolds — but
+# it answers with whatever manifest it finds, so in a two-lane repo where only the frontend
+# is scaffolded the service lane's gate passes on the frontend's package.json. Knowing the
+# lane's ecosystem is what turns that hit back into a miss.
+_marker_ecosystem() {
+    case "${1##*/}" in
+        *.sln|*.csproj)                       printf 'dotnet' ;;
+        package.json)                         printf 'node' ;;
+        pom.xml|build.gradle|build.gradle.kts) printf 'java' ;;
+        go.mod)                               printf 'go' ;;
+        Cargo.toml)                           printf 'rust' ;;
+        pyproject.toml)                       printf 'python' ;;
+        *)                                    printf '' ;;
+    esac
+}
+
 cmd_detect_project() {
-    local scope_root=""
+    local scope_root="" ecosystem=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --root|--source-path) scope_root="$2"; shift 2 ;;
-            --help|-h) echo "detect-project [--root <dir>]  -> {scaffolded, markers[], scope}"; return 0 ;;
+            # The lane's ecosystem, passed in by the caller that already resolved it.
+            # NOT re-derived here: the caller binds it from stacks.json before this op
+            # runs, and a second guess is a second thing to keep in step with that file.
+            --ecosystem) ecosystem="$2"; shift 2 ;;
+            --help|-h) echo "detect-project [--root <dir>] [--ecosystem <name>]  -> {scaffolded, markers[], scope, ecosystem_match}"; return 0 ;;
             *) echo "detect-project: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3161,7 +1727,18 @@ cmd_detect_project() {
     fi
     local scaffolded=false
     [ ${#markers[@]} -gt 0 ] && scaffolded=true
-    printf '{"scaffolded":%s,"markers":%s,"scope":"%s"}\n' "$scaffolded" "$(json_str_array "${markers[@]}")" "$scope"
+    # UNASKED IS NOT UNMATCHED. With no --ecosystem the caller has told us nothing to
+    # judge against, and answering false there would fail every existing call site.
+    local match=true m_eco
+    if [ -n "$ecosystem" ] && [ "$scaffolded" = true ]; then
+        match=false
+        for m in "${markers[@]}"; do
+            m_eco=$(_marker_ecosystem "$m")
+            [ "$m_eco" = "$ecosystem" ] && { match=true; break; }
+        done
+    fi
+    printf '{"scaffolded":%s,"markers":%s,"scope":"%s","ecosystem":"%s","ecosystem_match":%s}\n' \
+        "$scaffolded" "$(json_str_array "${markers[@]}")" "$scope" "$ecosystem" "$match"
 }
 
 
@@ -4061,23 +2638,24 @@ cmd_design_scaffold() {
             # name still follows --lane). In a brownfield repo /appweaver onboard
             # GENERATES a code-derived override for both names (resolve_template
             # Priority-1), so the defaults already yield the as-built structure for
-            # forward `design` and adopt alike, and this is rarely needed.
+            # forward `plan` and adopt alike, and this is rarely needed.
             --template) template_arg="$2"; shift 2 ;;
-            --help|-h) echo "design-scaffold --feature-dir <path> [--lane service|ui|backend|frontend] [--template <name>]"; return 0 ;;
+            --help|-h) echo "plan-scaffold --feature-dir <path> [--lane backend|frontend|service|ui] [--template <name>]"; return 0 ;;
             *) echo "design-scaffold: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    # backend/frontend are the PLAN-phase pairs: the same templates, the plan document
-    # names, and a MIGRATION — a legacy design.md / design.ui.md is RENAMED into the
-    # plan name so a feature never carries both spellings of the same master.
-    # service/ui stay byte-identical for their existing callers (adopt, the delta chain).
+    # backend / frontend are the PLAN-phase pairs: the same templates, the plan document
+    # names, and a MIGRATION — a legacy design.md / design.ui.md is RENAMED into the plan
+    # name, so a feature never carries two spellings of one master and the rename costs
+    # no flag day. service / ui stay byte-identical for the callers that still write the
+    # legacy names (adopt's reverse pass).
     local doc_name legacy_name=""
     case "$lane_arg" in
-        service)  doc_name="design.md";         [ -n "$template_arg" ] || template_arg="design-template" ;;
-        ui)       doc_name="design.ui.md";      [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
-        backend)  doc_name="backend-plan.md";   legacy_name="design.md";    [ -n "$template_arg" ] || template_arg="design-template" ;;
-        frontend) doc_name="frontend-plan.md";  legacy_name="design.ui.md"; [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
-        *) echo "design-scaffold: unknown --lane '$lane_arg' (service|ui|backend|frontend)" >&2; return 1 ;;
+        service)  doc_name="design.md";        [ -n "$template_arg" ] || template_arg="design-template" ;;
+        ui)       doc_name="design.ui.md";     [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
+        backend)  doc_name="backend-plan.md";  legacy_name="design.md";    [ -n "$template_arg" ] || template_arg="design-template" ;;
+        frontend) doc_name="frontend-plan.md"; legacy_name="design.ui.md"; [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
+        *) echo "design-scaffold: unknown --lane '$lane_arg' (backend|frontend|service|ui)" >&2; return 1 ;;
     esac
     local repo_root; repo_root=$(get_repo_root)
     local fd="$feature_dir_arg"
@@ -4087,6 +2665,9 @@ cmd_design_scaffold() {
     mkdir -p "$fd"
 
     local target="$fd/$doc_name" created="false" tpl migrated="false"
+    # A feature that predates the lane split carries the legacy name. Rename it rather
+    # than scaffolding an empty plan beside it: the content IS this lane's plan, and two
+    # files would leave every reader guessing which one is current.
     if [ ! -f "$target" ] && [ -n "$legacy_name" ] && [ -f "$fd/$legacy_name" ]; then
         mv "$fd/$legacy_name" "$target"; migrated="true"
     fi
@@ -4106,8 +2687,67 @@ cmd_design_scaffold() {
     local override_active="false"
     [ -f "$repo_root/.appweaver/templates/overrides/${template_arg}.md" ] && override_active="true"
     local template_source; template_source=$(resolve_template "$template_arg" "$repo_root") || true
-    printf '{"feature_dir":"%s","design_doc":"%s","lane":"%s","created":%s,"migrated":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
-        "$(json_escape "$fd")" "$(json_escape "$target")" "$(json_escape "$lane_arg")" "$created" "$migrated" "$override_active" \
+    printf '{"feature_dir":"%s","design_doc":"%s","plan_doc":"%s","lane":"%s","created":%s,"migrated":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+        "$(json_escape "$fd")" "$(json_escape "$target")" "$(json_escape "$target")" "$(json_escape "$lane_arg")" \
+        "$created" "$migrated" "$override_active" \
+        "$(json_escape "$template_arg")" "$(json_escape "${template_source:-}")"
+}
+
+# ─────────────────────────────── delta-plan-scaffold ───────────────────────
+# One change's LANE PLAN, inside the change directory beside its delta-spec:
+#   changes/<cr-id>/delta-backend-plan.md   (service lane)
+#   changes/<cr-id>/delta-frontend-plan.md  (frontend lane)
+# The plan phase calls this per DECLARED lane, so a backend-only project never grows an
+# orphan frontend delta plan and a frontend-only one is planned without a service half.
+# It is deliberately NOT cr-setup's job: cr-setup runs in the spec phase, which knows
+# nothing about lanes, and a document scaffolded there would exist for a lane that was
+# never declared.
+#
+# Same MIGRATION as the master: a change opened before the lane split carries
+# delta-design.md, which is renamed into the backend name rather than duplicated.
+cmd_delta_plan_scaffold() {
+    local cr_id="" feature_dir_arg="" lane_arg="backend" template_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --lane) lane_arg="$2"; shift 2 ;;
+            --template) template_arg="$2"; shift 2 ;;
+            --help|-h) echo "delta-plan-scaffold --cr-id <id> [--lane backend|frontend] [--feature-dir <path>] [--template <name>]"; return 0 ;;
+            *) echo "delta-plan-scaffold: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "delta-plan-scaffold: --cr-id is required" >&2; return 1; }
+    local doc_name legacy_name=""
+    case "$lane_arg" in
+        backend)  doc_name="delta-backend-plan.md";  legacy_name="delta-design.md"
+                  [ -n "$template_arg" ] || template_arg="delta-design-template" ;;
+        frontend) doc_name="delta-frontend-plan.md"; legacy_name="delta-design.ui.md"
+                  [ -n "$template_arg" ] || template_arg="ui-delta-design-template" ;;
+        *) echo "delta-plan-scaffold: unknown --lane '$lane_arg' (backend|frontend)" >&2; return 1 ;;
+    esac
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "delta-plan-scaffold: no feature set and no --feature-dir" >&2; return 1; }
+    local cr_dir="$fd/changes/$cr_id"
+    [ -d "$cr_dir" ] || { echo "delta-plan-scaffold: no such open change '$cr_id' (looked in $cr_dir)" >&2; return 1; }
+
+    local target="$cr_dir/$doc_name" created="false" migrated="false" tpl
+    if [ ! -f "$target" ] && [ -f "$cr_dir/$legacy_name" ]; then
+        mv "$cr_dir/$legacy_name" "$target"; migrated="true"
+    fi
+    if [ ! -f "$target" ]; then
+        tpl=$(resolve_template "$template_arg" "$repo_root") || true
+        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$target"; else touch "$target"; fi
+        created="true"
+    fi
+    _stamp_header "$target" "Wave" "$(_wave_of "$fd" "$cr_id" "$repo_root")"
+    local override_active="false"
+    [ -f "$repo_root/.appweaver/templates/overrides/${template_arg}.md" ] && override_active="true"
+    local template_source; template_source=$(resolve_template "$template_arg" "$repo_root") || true
+    printf '{"cr_id":"%s","cr_dir":"%s","lane":"%s","delta_plan":"%s","created":%s,"migrated":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+        "$(json_escape "$cr_id")" "$(json_escape "$cr_dir")" "$(json_escape "$lane_arg")" "$(json_escape "$target")" \
+        "$created" "$migrated" "$override_active" \
         "$(json_escape "$template_arg")" "$(json_escape "${template_source:-}")"
 }
 
@@ -4289,189 +2929,6 @@ print(json.dumps({
         "$scoped" "$matched" "$fence_green" "$(json_escape "$cmd")" "$(json_escape "$t")"
 }
 
-# ─────────────────────────────── test-diff ─────────────────────────────────
-# The TECHNICAL-STORY ORACLE. A technical story delivers no requirement, so there is no
-# FR- to trace it to and the existing test suite is the only thing that can say whether
-# it changed behaviour: a test that HAD to be edited means behaviour moved, and the work
-# was a functional story citing a requirement. This reports the suite's diff against a
-# baseline and lets the caller decide — it never judges.
-#
-# Read-only, always exits 0, and reports `checked` so an unreadable oracle (no git) is
-# distinguishable from a clean one. A gate that treats "could not look" as "nothing
-# found" is the exact false green the kit refuses everywhere else.
-cmd_test_diff() {
-    local fd_arg="" base=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --base) base="$2"; shift 2 ;;
-            --help|-h) echo "test-diff [--feature-dir <path>] [--base <git ref>]"; return 0 ;;
-            *) echo "test-diff: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || fd=""
-    AW_ROOT="$repo_root" AW_FD="$fd" AW_BASE="$base" python3 - <<'PY'
-import json, os, re, subprocess
-root = os.environ.get("AW_ROOT") or "."
-fd   = os.environ.get("AW_FD", "")
-want = (os.environ.get("AW_BASE") or "").strip()
-agg  = os.path.basename(fd.rstrip("/\\"))
-
-def git(*a):
-    """A git read that never raises. A working copy this command cannot interrogate is a
-    FACT TO REPORT — the caller decides what an unreadable oracle means — never a crash
-    that takes the gate down with it."""
-    try:
-        p = subprocess.run(["git", "-C", root] + list(a), capture_output=True, text=True)
-    except Exception:
-        return 1, ""
-    return p.returncode, (p.stdout or "").strip()
-
-DIR_RE = re.compile(r'(^|/)(tests?|specs?|__tests__|testing|test-suite)(/|$)', re.I)
-
-# The kit's OWN trees, which hold documents and configuration and never tests. The spec
-# tree is derived rather than assumed: `specs/` matches the RSpec directory convention
-# exactly, so without this every requirement document — and this gate's own verdict file,
-# written before the diff is taken — counted as a modified test.
-SKIP = [".appweaver/"]
-if fd:
-    _rel = os.path.relpath(fd, root).replace("\\", "/")
-    SKIP.append((_rel.rsplit("/", 1)[0] if "/" in _rel else _rel).rstrip("/") + "/")
-
-def is_test(path):
-    """A path is a TEST when a directory on it says so, or its own filename does — the
-    four conventions every shipped stack uses between them: a tests/ directory, a
-    Name.Tests.cs / NameTest.java suffix, a test_name.py / name_test.go affix, and a
-    name.test.ts / name.spec.ts infix. Deliberately GENEROUS: over-calling a file a test
-    costs a louder message, under-calling one costs a technical story that changed
-    behaviour and passed its own oracle."""
-    p = path.replace("\\", "/")
-    if any(p.startswith(s) for s in SKIP):
-        return False
-    stem, ext = os.path.splitext(os.path.basename(p))
-    # Prose is never a test, wherever it sits. A tests/ directory holds its own README
-    # and a docs tree holds files named for testing; counting either would fail a
-    # technical story over a paragraph.
-    if ext.lower() in (".md", ".markdown", ".txt", ".rst", ".adoc"):
-        return False
-    if DIR_RE.search(os.path.dirname(p)):
-        return True
-    stem = stem.lower()
-    if stem.startswith(("test", "spec")) or stem.endswith(("test", "tests", "spec", "specs")):
-        return True
-    return any(k in stem for k in (".test", ".spec", "_test", "_spec", "-test", "-spec"))
-
-out = {"ok": True, "aggregate": agg, "git": False, "checked": False,
-       "base": "", "base_ref": "", "base_kind": "none", "files_changed": 0,
-       "tests_changed": [], "tests_changed_csv": "", "tests_changed_count": 0,
-       "tests_deleted": [], "tests_deleted_csv": "",
-       "tests_added": [], "tests_added_csv": "", "tests_added_count": 0,
-       "slice_tests_changed": [], "slice_tests_changed_csv": "", "slice_tests_changed_count": 0,
-       "any_test_changed": False, "clean": True, "oracle": "clean",
-       "note": "", "digest": ""}
-
-if git("rev-parse", "--is-inside-work-tree")[1] != "true":
-    out["oracle"] = "unverified"
-    out["note"] = ("Not a git working copy, so the test suite's history cannot be read. The "
-                   "unchanged-suite oracle is UNVERIFIED for this run — not passed.")
-    out["digest"] = out["note"]
-    print(json.dumps(out)); raise SystemExit(0)
-out["git"] = out["checked"] = True
-
-# WHICH BASELINE. An explicit --base wins. Otherwise the fork point from the integration
-# branch, which is what a story's work sits on top of; falling back to HEAD, which sees
-# the working tree alone. The kind is reported because it changes what the answer MEANS:
-# a `head` baseline cannot see a test modified in a commit this branch already made.
-head = git("rev-parse", "HEAD")[1]
-if want and git("rev-parse", "--verify", want + "^{commit}")[0] == 0:
-    out["base"], out["base_ref"], out["base_kind"] = git("rev-parse", want)[1], want, "given"
-if not out["base"]:
-    cands = []
-    rc, ref = git("symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
-    if rc == 0 and ref:
-        cands.append(ref.split("refs/remotes/", 1)[-1])
-    cands += ["origin/main", "origin/master", "main", "master"]
-    seen = set()
-    for c in cands:
-        if c in seen:
-            continue
-        seen.add(c)
-        if git("rev-parse", "--verify", c + "^{commit}")[0] != 0:
-            continue
-        rc, mb = git("merge-base", "HEAD", c)
-        if rc != 0 or not mb:
-            continue
-        out["base"], out["base_ref"] = mb, c
-        out["base_kind"] = "head" if mb == head else "merge-base"
-        break
-if not out["base"]:
-    out["base"], out["base_kind"] = head or "HEAD", "head"
-
-rc, diff = git("diff", "--name-status", "--find-renames", out["base"])
-changed, added, deleted, files = [], [], [], 0
-for line in diff.splitlines():
-    parts = line.split("\t")
-    if len(parts) < 2:
-        continue
-    code, paths = parts[0].strip(), parts[1:]
-    files += 1
-    hits = [p for p in paths if is_test(p)]
-    if not hits:
-        continue
-    p = hits[-1]
-    if code.startswith("A") or code.startswith("C"):
-        # A NEW test is not a changed one. A refactor that adds characterisation tests is
-        # exactly the work a technical story exists to do.
-        added.append(p)
-    elif code.startswith("R"):
-        # A pure rename moves a test without changing what it asserts; anything less than
-        # a 100% match carries an edit inside it.
-        (added if code == "R100" else changed).append(p)
-    elif code.startswith("D"):
-        deleted.append(p); changed.append(p)
-    else:
-        changed.append(p)
-
-# Untracked files are ADDITIONS the diff cannot see — reported as such so a new test
-# written in the working tree is not mistaken for a missing one.
-for p in git("ls-files", "--others", "--exclude-standard")[1].splitlines():
-    p = p.strip()
-    if p and is_test(p) and p not in added:
-        added.append(p); files += 1
-
-changed = sorted(set(changed)); added = sorted(set(added)); deleted = sorted(set(deleted))
-low = agg.lower()
-slice_changed = [p for p in changed if low and low in p.lower()]
-out.update(files_changed=files,
-           tests_changed=changed, tests_changed_csv=", ".join(changed),
-           tests_changed_count=len(changed),
-           tests_deleted=deleted, tests_deleted_csv=", ".join(deleted),
-           tests_added=added, tests_added_csv=", ".join(added), tests_added_count=len(added),
-           slice_tests_changed=slice_changed, slice_tests_changed_csv=", ".join(slice_changed),
-           slice_tests_changed_count=len(slice_changed),
-           any_test_changed=bool(changed), clean=not changed,
-           # The DIFF's state in one word — clean | changed | unverified — so a caller can
-           # branch on it without recombining a boolean with a "could I even look" flag.
-           # It says what the suite did, never what that means for a story.
-           oracle="changed" if changed else "clean")
-
-kindnote = {"given": "the ref given on the command line",
-            "merge-base": "the fork point from %s — every commit this branch added is in view" % out["base_ref"],
-            "head": "HEAD — only uncommitted work is in view, so a test modified in a commit "
-                    "already made on this branch is NOT counted"}[out["base_kind"]]
-lines = ["Test-suite diff against %s (%s): %s" % (out["base"][:12], out["base_kind"], kindnote),
-         "  files changed: %d" % files,
-         "  tests MODIFIED or DELETED (%d): %s" % (len(changed), ", ".join(changed) or "none"),
-         "  tests ADDED (%d): %s" % (len(added), ", ".join(added) or "none")]
-if slice_changed:
-    lines.append("  of those, on this aggregate (%s): %s" % (agg, ", ".join(slice_changed)))
-out["note"] = kindnote
-out["digest"] = "\n".join(lines)
-print(json.dumps(out))
-PY
-}
-
 cmd_run_migrate() {
     while [ $# -gt 0 ]; do
         case "$1" in
@@ -4569,53 +3026,467 @@ cmd_deploy_dispatch() {
 }
 
 # ─────────────────────────────── cr-setup / cr-archive ──────────────────────
-# Change-request scaffolding: a delta lives under <feature>/changes/<cr-id>/,
-# archives to <feature>/changes/archive/<cr-id>/, and bumps the version on close.
-# Single-active-change guard: cr-setup refuses to open a 2nd concurrent change on
-# the same aggregate (design must close the open one first) unless --force.
+# Change-request scaffolding. A delta is TWO-PART:
+#   • feature level  — <feature>/changes/<cr-id>/delta-spec.md
+#   • context level  — <context>/domain-model.<cr-id>.delta.md
+# The model half sits BESIDE the master model, not inside the change directory, so
+# every other open delta can see it while planning and design around it instead of
+# discovering the overlap at merge time. Both halves are created here, together.
+# The change's LANE PLANS (delta-backend-plan.md / delta-frontend-plan.md) are NOT:
+# they are scaffolded per declared lane by delta-plan-scaffold, in the plan phase.
+#
+# MANY CHANGES MAY BE OPEN. Every specify call on an established feature opens its
+# own; the single-active guard is gone. WAVE is what orders them: deltas sharing a
+# wave are independent and may be developed in parallel, a wave-N+1 delta is
+# implemented after every wave-N delta lands. The default is the wave of the changes
+# already open (parallel by default) — a delta that genuinely builds on one of them
+# is raised explicitly with --wave, or later with cr-wave.
 cmd_cr_setup() {
-    local cr_id="" feature_dir_arg="" title="" force=""
+    local cr_id="" feature_dir_arg="" title="" force="" wave=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
             --title) title="$2"; shift 2 ;;
+            --wave) wave="$2"; shift 2 ;;
             --force) force=1; shift ;;
-            --help|-h) echo "cr-setup --cr-id <id> [--feature-dir <path>] [--title <t>] [--force]"; return 0 ;;
+            --help|-h) echo "cr-setup [--cr-id <id>] [--feature-dir <path>] [--title <t>] [--wave <n>]"; return 0 ;;
             *) echo "cr-setup: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    [ -n "$cr_id" ] || cr_id="CR-$(date +%Y%m%d-%H%M%S)"
+    # 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.
+    [ -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"
     [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
     [ -n "$fd" ] || { echo "cr-setup: no feature set and no --feature-dir" >&2; return 1; }
     [[ "$fd" != /* ]] && fd="$repo_root/$fd"
-    # Single-active-change guard: open the change FIRST so a second concurrent CR on
-    # the same aggregate is refused BEFORE any changes/<cr>/ dir is scaffolded (no
-    # orphan left behind). Re-opening the same cr_id is a no-op. --force overrides.
-    local av_open
-    if ! av_open=$(_active_version "$fd" open "$cr_id" "$force"); then
-        echo "cr-setup: refusing to open '$cr_id' — a change is already open on this feature; finish it (finalize-delta -> analyze-slice -> close-delta) first, or pass --force." >&2
-        printf '%s\n' "$av_open"
-        return 1
+
+    # The context that owns the domain model. A feature at specs/<Ctx>/<Feat> has its
+    # model one level up; a flat specs/<Feat> falls back to specs/ as the implicit
+    # single context, so a pre-context repo still gets exactly one model.
+    local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
+    local ctx_rel="${ctx_dir#$repo_root/}"
+
+    # Wave default = the highest wave among the changes already open, so a new delta is
+    # parallel with them unless it says otherwise.
+    if [ -z "$wave" ]; then
+        wave=$(_max_open_wave "$ctx_dir")
     fi
+    case "$wave" in ''|*[!0-9]*) echo "cr-setup: --wave must be a positive integer" >&2; return 1 ;; esac
+    [ "$wave" -ge 1 ] 2>/dev/null || wave=1
+
+    local av_open; av_open=$(_active_version "$fd" open "$cr_id" "$force")
     local cr_dir="$fd/changes/$cr_id"
     mkdir -p "$cr_dir"
-    local dspec="$cr_dir/delta-spec.md" ddesign="$cr_dir/delta-design.md" tpl created=false
+    # The SPEC half. The change's LANE PLANS are not scaffolded here: cr-setup runs in the
+    # spec phase, which knows nothing about which lanes are declared, and a plan document
+    # created for an undeclared lane would sit empty in the change directory for the rest
+    # of its life. `plan` scaffolds them per declared lane (delta-plan-scaffold).
+    local dspec="$cr_dir/delta-spec.md" tpl created=false
     if [ ! -f "$dspec" ]; then
         tpl=$(resolve_template "delta-spec-template" "$repo_root") || true
         if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$dspec"; else touch "$dspec"; fi
         created=true
     fi
-    if [ ! -f "$ddesign" ]; then
-        tpl=$(resolve_template "delta-design-template" "$repo_root") || true
-        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$ddesign"; else touch "$ddesign"; fi
+    # The model half, beside the master model.
+    local dmodel="$ctx_dir/domain-model.$cr_id.delta.md"
+    if [ ! -f "$dmodel" ]; then
+        mkdir -p "$ctx_dir"
+        tpl=$(resolve_template "delta-domain-model-template" "$repo_root") || true
+        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$dmodel"; else touch "$dmodel"; fi
         created=true
     fi
-    printf '{"cr_id":"%s","cr_dir":"%s","delta_spec":"%s","delta_design":"%s","title":"%s","created":%s}\n' \
+    # Scripts stamp ids, dates and the wave — the model never writes them.
+    _stamp_header "$dspec"  "Wave" "$wave"
+    _stamp_header "$dmodel" "Wave" "$wave"
+
+    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' \
         "$(json_escape "$cr_id")" "$(json_escape "$cr_dir")" "$(json_escape "$dspec")" \
-        "$(json_escape "$ddesign")" "$(json_escape "$title")" "$created"
+        "$(json_escape "$dmodel")" "$(json_escape "$ctx_rel")" \
+        "$wave" "${open_count:-1}" "$(json_escape "$title")" "$created"
+}
+
+# ─────────────────────────────── cr-wave ────────────────────────────────────
+# Change a delta's wave after the fact — the ONLY supported way to move one, because
+# the wave is stamped into two documents that must agree. Raise a delta's wave when
+# it turns out to build on another open delta; lower it when that dependency goes away.
+cmd_cr_wave() {
+    local cr_id="" feature_dir_arg="" wave=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --wave) wave="$2"; shift 2 ;;
+            --help|-h) echo "cr-wave --cr-id <id> --wave <n> [--feature-dir <path>]"; return 0 ;;
+            *) echo "cr-wave: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -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)
+    local fd="$feature_dir_arg"
+    [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
+    [ -n "$fd" ] || { echo "cr-wave: 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")
+    local dspec="$fd/changes/$cr_id/delta-spec.md" dmodel="$ctx_dir/domain-model.$cr_id.delta.md"
+    local stamped=0
+    [ -f "$dspec" ]  && { _stamp_header "$dspec"  "Wave" "$wave"; stamped=$((stamped+1)); }
+    [ -f "$dmodel" ] && { _stamp_header "$dmodel" "Wave" "$wave"; stamped=$((stamped+1)); }
+    if [ "$stamped" -eq 0 ]; then
+        echo "cr-wave: no delta documents found for '$cr_id'" >&2; return 1
+    fi
+    printf '{"cr_id":"%s","wave":%s,"stamped":%s,"delta_spec":"%s","delta_model":"%s"}\n' \
+        "$(json_escape "$cr_id")" "$wave" "$stamped" \
+        "$(json_escape "$dspec")" "$(json_escape "$dmodel")"
+}
+
+# ─────────────────────────────── 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
+# once, and "the most recently opened" is a guess that is wrong as soon as two people
+# are working in parallel.
+#
+# THE EVIDENCE IS THE DIRECTORY. changes/<cr-id>/ exists while the change is open and
+# moves to changes/archive/<cr-id>/ when it closes, so the tree already answers "what is
+# open" without trusting a ledger that a crashed run could have left stale.
+# active_version.json is read alongside it and reported as `tracked`, so a disagreement
+# between the two is visible rather than silently resolved.
+#
+# select_options carries a LABEL per change (id · wave · title). `matched_label` resolves
+# a --preselect (a cr id, or any unique fragment of one) to the whole label, so a caller
+# can pass a change id straight through to user_select's preselect_from and skip the
+# prompt — the engine matches a preselection against the option text exactly.
+#
+# TWO SYNTHETIC OPTIONS, off by default. A caller that offers more than "which open
+# change" asks for them by flag, and gets each one's exact label back so it can test the
+# selection against it (the engine compares rendered strings; there is no prefix match):
+#   --include-main  prepends MAIN — "not a change at all, the feature's own master".
+#                   `--preselect main` (or `master`) resolves to it.
+#   --include-new   appends NEW — "open a change that has no spec delta". `--preselect
+#                   new` resolves to it.
+# `count` and `has_changes` keep counting REAL open changes, so a caller that gates on
+# them is unaffected by either flag.
+cmd_cr_list() {
+    local feature_dir_arg="" preselect="" inc_main="" inc_new=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --preselect) preselect="$2"; shift 2 ;;
+            --include-main) inc_main="1"; shift ;;
+            --include-new) inc_new="1"; shift ;;
+            --help|-h) echo "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, active_change}"; return 0 ;;
+            *) echo "cr-list: 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 "cr-list: 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_PRE="$(_cr_id_token "$preselect")" \
+    AW_PRE_RAW="$preselect" AW_INC_MAIN="$inc_main" AW_INC_NEW="$inc_new" python3 - <<'PY'
+import json, os, re
+fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
+pre = os.environ.get("AW_PRE", "").strip()
+# The WHOLE argument, not its first token. A cr id is matched on the token because a
+# selection label starts with one; the synthetic words are matched on the whole string
+# so that guidance prose like "new caching layer" — which plan passes here verbatim —
+# cannot silently resolve to the NEW option.
+pre_raw = os.environ.get("AW_PRE_RAW", "").strip().lower()
+inc_main = bool(os.environ.get("AW_INC_MAIN"))
+inc_new = bool(os.environ.get("AW_INC_NEW"))
+MAIN_LABEL = "main · the feature's own spec — re-plan the master (not a change)"
+NEW_LABEL = "new · open a plan-only change — a refactor or architectural decision, no spec delta"
+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\*\*:\s*(.+?)\s*$" % re.escape(name), t, re.M)
+    return m.group(1).strip() if m else default
+def title_of(path):
+    # "# Delta Spec — CR-…: Add discount tiers" -> the part after the id. An unfilled
+    # template still carries the placeholder, which is reported as such rather than
+    # offered to the user as a title.
+    try: first = open(path, encoding="utf-8").readline().strip()
+    except Exception: return ""
+    m = re.match(r"^#\s+.*?:\s*(.+)$", first)
+    t = m.group(1).strip() if m else ""
+    return "" if (not t or t.startswith("[")) else t
+tracked = []
+avp = os.path.join(fd, "active_version.json")
+active = ""
+try:
+    av = json.load(open(avp, encoding="utf-8"))
+    tracked = [c for c in (av.get("open_changes") or []) if c] or ([av["active_change"]] if av.get("active_change") else [])
+    active = av.get("active_change", "")
+except Exception: pass
+changes_dir = os.path.join(fd, "changes")
+rows = []
+if os.path.isdir(changes_dir):
+    for name in sorted(os.listdir(changes_dir)):
+        d = os.path.join(changes_dir, name)
+        if name == "archive" or not os.path.isdir(d):
+            continue
+        dspec = os.path.join(d, "delta-spec.md")
+        dmodel = os.path.join(ctx, "domain-model.%s.delta.md" % name)
+        be = os.path.join(d, "delta-backend-plan.md")
+        fe = os.path.join(d, "delta-frontend-plan.md")
+        legacy = os.path.join(d, "delta-design.md")
+        wave = header(dspec, "Wave") or header(dmodel, "Wave") or "1"
+        try: wave = int(re.sub(r"\D", "", wave) or 1)
+        except Exception: wave = 1
+        rows.append({
+            "cr_id": name, "cr_dir": rel(d), "wave": wave,
+            "title": title_of(dspec),
+            "delta_spec": rel(dspec), "delta_spec_exists": os.path.isfile(dspec),
+            "delta_model": rel(dmodel), "delta_model_exists": os.path.isfile(dmodel),
+            "delta_backend_plan": rel(be), "delta_backend_plan_exists": os.path.isfile(be),
+            "delta_frontend_plan": rel(fe), "delta_frontend_plan_exists": os.path.isfile(fe),
+            # A change opened before the lane split; plan-scaffold renames it into the
+            # backend plan on the next planning run.
+            "legacy_delta_design": os.path.isfile(legacy),
+            "tracked": name in tracked,
+            "active": name == active,
+        })
+rows.sort(key=lambda r: (r["wave"], r["cr_id"]))
+def label(r):
+    bits = [r["cr_id"], "wave %d" % r["wave"]]
+    bits.append(r["title"] or "(delta-spec not authored yet)")
+    planned = [k for k, v in (("backend", r["delta_backend_plan_exists"]), ("frontend", r["delta_frontend_plan_exists"])) if v]
+    if planned: bits.append("planned: " + "+".join(planned))
+    return " · ".join(bits)
+cr_opts = [label(r) for r in rows]
+matched = ""
+if pre:
+    exact = [l for l, r in zip(cr_opts, rows) if r["cr_id"] == pre]
+    part  = [l for l, r in zip(cr_opts, rows) if pre in r["cr_id"]]
+    if exact: matched = exact[0]
+    elif len(part) == 1: matched = part[0]
+# The synthetic options bracket the real ones: MAIN first (it is the default reading of
+# "plan this feature"), NEW last (it CREATES something, so it sits away from the choices
+# that only select). Their words are also accepted as a --preselect, which is how a bare
+# `plan main` on the command line skips the prompt.
+opts = ([MAIN_LABEL] if inc_main else []) + cr_opts + ([NEW_LABEL] if inc_new else [])
+if not matched and pre_raw:
+    if inc_main and pre_raw in ("main", "master"): matched = MAIN_LABEL
+    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),
+    "select_options": opts, "matched_label": matched,
+    "main_label": MAIN_LABEL if inc_main else "",
+    "new_label": NEW_LABEL if inc_new else "",
+    "active_change": active, "tracked": tracked,
+    "has_changes": len(rows) > 0,
+    # The lone open change, so a caller can take it without a prompt when there is
+    # nothing to choose between.
+    "only_id": rows[0]["cr_id"] if len(rows) == 1 else "",
+}))
+PY
+}
+
+# ─────────────────────────────── cr-paths ──────────────────────────────────
+# Everything one change needs to be PLANNED: its own documents, its wave, and the model
+# deltas that come BEFORE it.
+#
+# PREDECESSORS ARE THE LOWER WAVES. A wave is a dependency level — same wave means
+# independent and developable in parallel, a higher wave means "after those have landed".
+# So the deltas a plan may build on are exactly the open ones in a LOWER wave: they are
+# the ones committed to landing first. Same-wave deltas are reported separately as
+# siblings: visible, so an overlap is designed around, but never assumed, because nothing
+# orders them against each other.
+cmd_cr_paths() {
+    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-paths --cr-id <id> [--feature-dir <path>]  -> {cr_id, cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan, wave, predecessor_files[], predecessor_specs[], predecessor_docs[], sibling_files[], domain_model}"; return 0 ;;
+            *) echo "cr-paths: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "cr-paths: --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-paths: 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, glob
+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 wave_of(path, default=1):
+    try: t = open(path, encoding="utf-8").read()
+    except Exception: return default
+    m = re.search(r"^\*\*Wave\*\*:\s*(\d+)", t, re.M)
+    return int(m.group(1)) if m else default
+cr_dir = os.path.join(fd, "changes", cr)
+dspec  = os.path.join(cr_dir, "delta-spec.md")
+dmodel = os.path.join(ctx, "domain-model.%s.delta.md" % cr)
+be     = os.path.join(cr_dir, "delta-backend-plan.md")
+fe     = os.path.join(cr_dir, "delta-frontend-plan.md")
+master = os.path.join(ctx, "domain-model.md")
+wave = wave_of(dspec, wave_of(dmodel, 1))
+# A change's model delta sits at CONTEXT level and its delta-spec at FEATURE level, so the
+# 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"))):
+        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"))):
+    base = os.path.basename(f)
+    other = base[len("domain-model."):-len(".delta.md")]
+    if other == cr:
+        continue
+    w = wave_of(f)
+    s = spec_of(other)
+    row = {"cr_id": other, "file": rel(f), "wave": w, "delta_spec": rel(s) if s else ""}
+    if w < wave:
+        pred.append(rel(f)); pred_rows.append(row)
+        if s: pred_specs.append(rel(s))
+    else:
+        sib.append(rel(f)); sib_rows.append(row)
+print(json.dumps({
+    "cr_id": cr, "cr_dir": rel(cr_dir), "exists": os.path.isdir(cr_dir),
+    "delta_spec": rel(dspec), "delta_spec_exists": os.path.isfile(dspec),
+    "delta_model": rel(dmodel), "delta_model_exists": os.path.isfile(dmodel),
+    "delta_backend_plan": rel(be), "delta_backend_plan_exists": os.path.isfile(be),
+    "delta_frontend_plan": rel(fe), "delta_frontend_plan_exists": os.path.isfile(fe),
+    "wave": wave,
+    "context_dir": rel(ctx),
+    "domain_model": rel(master), "domain_model_exists": os.path.isfile(master),
+    # Lower wave = committed to landing first, so this delta may plan on top of it.
+    "predecessor_files": pred, "predecessors": pred_rows, "predecessor_count": len(pred),
+    # Each predecessor's SPEC half. The model delta says what the domain becomes; the
+    # delta-spec says what behaviour asked for it, and a gate that checks one without the
+    # other cannot tell a realisation of a predecessor from an invention.
+    "predecessor_specs": pred_specs,
+    # Both halves in one list, for a build_context `context_from:` (which takes one var).
+    "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),
+}))
+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.
+#
+# 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
+# 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.
+#
+# 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.
+#
+# 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
+# orders the two — an overlap with it is a conflict to design around), a HIGHER wave is a
+# successor (it lands after this change and plans on top of it — an overlap with it is
+# information, not an obligation). cr-paths splits at the same line but only two ways,
+# because for CONTEXT the question is only "may I build on this"; here the three-way
+# answer is the advice itself.
+cmd_cr_overlap() {
+    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-overlap --cr-id <id> [--feature-dir <path>]  -> {cr_id, wave, aggregates[], overlaps[], overlap_count, predecessor_overlaps, sibling_overlaps, successor_overlaps, overlap_report}"; return 0 ;;
+            *) echo "cr-overlap: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "cr-overlap: --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-overlap: 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, glob
+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 read(p):
+    try: return open(p, encoding="utf-8").read()
+    except Exception: return ""
+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>".
+def aggregates_of(text):
+    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("["):
+            continue
+        if name not in out:
+            out.append(name)
+    return out
+mine_txt = read(os.path.join(ctx, "domain-model.%s.delta.md" % cr))
+wave = wave_of(read(os.path.join(fd, "changes", cr, "delta-spec.md")), wave_of(mine_txt, 1))
+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"))):
+    other = os.path.basename(f)[len("domain-model."):-len(".delta.md")]
+    if other == cr:
+        continue
+    t = read(f)
+    w = wave_of(t)
+    shared = [a for a in aggregates_of(t) if a in mine_set]
+    if not shared:
+        continue
+    if w < wave:    relation = "predecessor"; npred += 1
+    elif w == wave: relation = "sibling";     nsib  += 1
+    else:           relation = "successor";   nsucc += 1
+    rows.append({"cr_id": other, "wave": w, "relation": relation,
+                 "file": rel(f), "aggregates": shared})
+    parts.append("%s (wave %d, %s): %s" % (other, w, relation, ", ".join(shared)))
+print(json.dumps({
+    "cr_id": cr, "wave": wave, "aggregates": mine,
+    "overlaps": rows, "overlap_count": len(rows),
+    "predecessor_overlaps": npred, "sibling_overlaps": nsib,
+    "successor_overlaps": nsucc,
+    # One line for a prompt: the model is told the fact, never asked to derive it.
+    "overlap_report": ("; ".join(parts) if parts
+                       else "none — no other open change touches these aggregates"),
+}))
+PY
+}
+
+# ─────────────────────────────── cr-activate ───────────────────────────────
+# Point active_version.json.active_change at an OPEN change, changing nothing else — no
+# version bump, no wave restamp, no scaffold.
+#
+# WHY IT EXISTS. Every delta stage after the plan phase still resolves "the" change
+# through active_change. Once the plan phase lets a user CHOOSE which open delta to plan,
+# that choice has to reach those stages or they would act on a different change than the
+# one just planned. Activating the chosen change is what keeps the chain pointed at one
+# delta while --cr-id is threaded through the rest of it.
+cmd_cr_activate() {
+    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-activate --cr-id <id> [--feature-dir <path>]"; return 0 ;;
+            *) echo "cr-activate: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -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"
 }
 
 cmd_cr_archive() {
@@ -4641,9 +3512,21 @@ cmd_cr_archive() {
         mv "$cr_dir" "$archive_root/$cr_id"
         archived="$archive_root/$cr_id"
     fi
-    # Close the change in active_version.json (single version source): bump minor +
-    # clear active_change. (Supersedes the old bare <feature>/VERSION file.)
-    local av; av=$(_active_version "$fd" close)
+    # The delta's model half lives beside the context's master model, not inside the
+    # change directory, so archiving the directory does not carry it along. It is moved
+    # into the same archive: a merged delta's model changes are in domain-model.md by
+    # now, and leaving the pending file behind would keep showing a landed change as
+    # 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
+        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'
 import json, os
 try: av = json.loads(os.environ.get("AW_AV") or "{}")
@@ -4687,10 +3570,13 @@ 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.
 pat = re.compile(r'^(\*\*Version\*\*:[ \t]*)(\S+)(.*)$', re.M)
-# design.ui.md joins the spine where the feature has a UI half: the masters move in
+# Each declared lane's plan joins the spine beside the spec: the masters move in
 # LOCKSTEP, so a document left behind at the old number is the one lie the version
-# spine cannot tolerate. A feature without one reports it `missing` and nothing fails.
-for name in ("spec.md", "design.md", "design.ui.md"):
+# spine cannot tolerate. A lane the feature does not have reports `missing` and nothing
+# fails, which is also how the legacy names are carried — a feature not yet migrated to
+# the plan names still gets stamped, and one that has been migrated reports the legacy
+# pair missing.
+for name in ("spec.md", "backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md"):
     p = os.path.join(fd, name)
     if not os.path.isfile(p):
         missing.append(name); continue
@@ -4709,701 +3595,6 @@ print(json.dumps({"ok": True, "version": ver, "stamped": stamped,
 PY
 }
 
-
-# ─────────────────────────── plan-check / plan-stamp ────────────────────────
-# The plan documents' derivation tracking. Each plan doc (backend-plan.md /
-# frontend-plan.md) derives from ONE spec version and carries its OWN track file
-# beside the spec — .aw-plan-track.backend-plan.json / .aw-plan-track.frontend-plan.json
-# — recording {spec_version, sha256}, so the two lanes' stamps never share a write.
-# plan-check reads the record back against the spec's Change History ledger;
-# plan-stamp is the only writer.
-# Both always exit 0 with an ok/state field — the workflow's verify_context owns
-# the stop (the lane-verify convention).
-cmd_plan_check() {
-    local fd_arg="" doc=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --doc) doc="$2"; shift 2 ;;
-            --help|-h) echo "plan-check --doc <path> [--feature-dir <path>]"; return 0 ;;
-            *) echo "plan-check: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    [ -n "$doc" ] || { echo "plan-check: --doc required" >&2; return 1; }
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "plan-check: no feature set and no --feature-dir" >&2; return 1; }
-    AW_DOC="$doc" AW_FD="$fd" python3 - <<'PY'
-import json, os, re, sys, hashlib
-doc = os.environ["AW_DOC"]; fd = os.environ["AW_FD"]
-spec = os.path.join(fd, "spec.md")
-# One track file per plan document (.aw-plan-track.backend-plan.json /
-# .aw-plan-track.frontend-plan.json) — parallel lane stamps never contend on a shared file.
-stem = os.path.splitext(os.path.basename(doc))[0]
-track_path = os.path.join(fd, ".aw-plan-track.%s.json" % stem)
-def vtuple(v):
-    try: return tuple(int(x) for x in v.lstrip("vV").split("."))
-    except Exception: return (0,)
-out = {"doc": doc, "doc_exists": os.path.isfile(doc), "state": "", "derived_version": "",
-       "current_version": "", "changed_csv": "", "changed_summary": "", "body_changed": False}
-# Current version = the widest of the ledger's rows and the **Version** header — the
-# same widest-wins rule ledger-append uses, so a hand-moved header cannot hide a row.
-rows = []; cur = ""; idcol = -1
-if os.path.isfile(spec):
-    text = open(spec, encoding="utf-8", errors="replace").read()
-    m = re.search(r'^##\s+Change History\s*$', text, re.M)
-    if m:
-        for line in text[m.end():].splitlines():
-            if idcol < 0 and line.lstrip().startswith("|") and "requirements changed" in line.lower():
-                hdr = [c.strip().lower() for c in line.strip().strip("|").split("|")]
-                idcol = next((i for i, c in enumerate(hdr) if "requirements changed" in c), -1)
-            rm = re.match(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', line)
-            if rm: rows.append((rm.group(1), line))
-    hv = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', text, re.M)
-    cands = [r[0] for r in rows] + ([hv.group(1)] if hv else [])
-    if cands: cur = max(cands, key=vtuple)
-out["current_version"] = cur
-if not out["doc_exists"]:
-    out["state"] = "fresh"; print(json.dumps(out)); sys.exit(0)
-try: track = json.load(open(track_path, encoding="utf-8"))
-except Exception: track = {}
-entry = track.get(os.path.basename(doc))
-if not entry:
-    # A document with no derivation record — a migrated legacy master, or a baseline
-    # lost by hand. There is no stamp to diff against, so the caller reconciles the
-    # WHOLE document once and plan-stamp baselines it.
-    out["state"] = "untracked"; print(json.dumps(out)); sys.exit(0)
-derived = entry.get("spec_version", "")
-out["derived_version"] = derived
-body = open(doc, encoding="utf-8", errors="replace").read()
-out["body_changed"] = hashlib.sha256(body.encode("utf-8")).hexdigest() != entry.get("sha256", "")
-moved = [r for r in rows if vtuple(r[0]) > vtuple(derived)]
-# Scrape ONLY the ledger's "Requirements changed" cell when it names one. The
-# Stories cell holds ids of the form <Aggregate>-nnn, which read as requirement ids
-# whenever the aggregate is spelled in caps (EDI-001, HR-002) — those would arrive
-# as requirements for the plan to conform, and there is no such requirement.
-def _scope(line):
-    if idcol >= 0:
-        cells = [c.strip() for c in line.strip().strip("|").split("|")]
-        if idcol < len(cells): return cells[idcol]
-    return line
-ids = sorted({i for _v, line in moved for i in re.findall(r'[A-Z]{2}-\d+', _scope(line))})
-out["changed_csv"] = ", ".join(ids)
-out["changed_summary"] = "  //  ".join(line.strip() for _v, line in moved)
-behind = bool(moved) or bool(cur and vtuple(cur) > vtuple(derived))
-if out["body_changed"] and behind: out["state"] = "edited_behind"
-elif out["body_changed"]:          out["state"] = "edited"
-elif behind:                       out["state"] = "behind"
-else:                              out["state"] = "clean"
-print(json.dumps(out))
-PY
-}
-
-cmd_plan_stamp() {
-    local fd_arg="" doc="" ids="" note="" no_row="false"
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --doc) doc="$2"; shift 2 ;;
-            --ids) ids="$2"; shift 2 ;;
-            --note) note="$2"; shift 2 ;;
-            --no-row) no_row="true"; shift ;;
-            --help|-h) echo "plan-stamp --doc <path> [--feature-dir <path>] [--ids <csv>] [--note <text>] [--no-row]"; return 0 ;;
-            *) echo "plan-stamp: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    [ -n "$doc" ] || { echo "plan-stamp: --doc required" >&2; return 1; }
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "plan-stamp: no feature set and no --feature-dir" >&2; return 1; }
-    AW_DOC="$doc" AW_FD="$fd" AW_IDS="$ids" AW_NOTE="$note" AW_NOROW="$no_row" python3 - <<'PY'
-import json, os, re, sys, hashlib, datetime
-doc = os.environ["AW_DOC"]; fd = os.environ["AW_FD"]
-ids = os.environ.get("AW_IDS", "").strip(); note = os.environ.get("AW_NOTE", "").strip()
-no_row = os.environ.get("AW_NOROW", "false") == "true"
-spec = os.path.join(fd, "spec.md")
-# One track file per plan document (.aw-plan-track.backend-plan.json /
-# .aw-plan-track.frontend-plan.json) — parallel lane stamps never contend on a shared file.
-stem = os.path.splitext(os.path.basename(doc))[0]
-track_path = os.path.join(fd, ".aw-plan-track.%s.json" % stem)
-def vtuple(v):
-    try: return tuple(int(x) for x in v.lstrip("vV").split("."))
-    except Exception: return (0,)
-if not os.path.isfile(doc):
-    print(json.dumps({"ok": False, "error": "plan document %s does not exist" % doc, "version": ""})); sys.exit(0)
-cur = ""
-if os.path.isfile(spec):
-    st = open(spec, encoding="utf-8", errors="replace").read()
-    m = re.search(r'^##\s+Change History\s*$', st, re.M)
-    rows = re.findall(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', st[m.end():] if m else "", re.M)
-    hv = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', st, re.M)
-    cands = rows + ([hv.group(1)] if hv else [])
-    if cands: cur = max(cands, key=vtuple)
-text = open(doc, encoding="utf-8", errors="replace").read()
-# The ledger-survival fence: a plan whose update dropped the Change History section is
-# NOT baselined — a lost ledger silently baselined over could never be noticed again.
-hist = re.search(r'^##+\s*(?:\d+\.\s*)?Change History\s*$', text, re.M)
-if not hist:
-    print(json.dumps({"ok": False, "version": cur,
-        "error": "the plan document has no 'Change History' section — the write dropped the ledger; nothing was baselined"}))
-    sys.exit(0)
-warnings = []
-if not re.search(r'^##+.*Assumptions', text, re.M):
-    warnings.append("no 'Assumptions' section found")
-if not re.search(r'^##+.*(Workarounds|Deviations)', text, re.M):
-    warnings.append("no 'Workarounds/Deviations' section found")
-row_txt = ""
-if not no_row:
-    # Bounded to the Change History section; the row's cell count follows the section's
-    # own table so the append fits the greenfield, UI and onboard-generated shapes alike.
-    lines = text.split("\n")
-    hline = text[:hist.start()].count("\n")
-    end = len(lines)
-    for i in range(hline + 1, len(lines)):
-        if re.match(r'^##', lines[i]): end = i; break
-    tbl = [i for i in range(hline + 1, end) if lines[i].lstrip().startswith("|")]
-    ncells = 5
-    if tbl: ncells = max(3, lines[tbl[0]].strip().strip("|").count("|") + 1)
-    change = note or ("Conformed to spec %s" % (cur or "(unversioned)"))
-    if ids: change = "%s — %s" % (change, ids)
-    change = change.replace("|", "/").replace("\n", " ")
-    cells = [cur or "v?", datetime.date.today().isoformat(), change] + ["—"] * (ncells - 3)
-    row_txt = "| " + " | ".join(cells[:ncells]) + " |"
-    lines.insert((tbl[-1] + 1) if tbl else end, row_txt)
-    text = "\n".join(lines)
-if cur:
-    text = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + cur, text, count=1, flags=re.M)
-open(doc, "w", encoding="utf-8").write(text)
-try: track = json.load(open(track_path, encoding="utf-8"))
-except Exception: track = {}
-track[os.path.basename(doc)] = {
-    "spec_version": cur,
-    "sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
-    "updated": datetime.datetime.now().isoformat(timespec="seconds")}
-open(track_path, "w", encoding="utf-8").write(json.dumps(track, indent=2) + "\n")
-print(json.dumps({"ok": True, "version": cur, "row": row_txt, "warnings": warnings}))
-PY
-}
-
-
-# ───────────────────────────────── gate-result ──────────────────────────────
-# The machine-readable verdict every analyze gate writes beside its markdown
-# report. CI cannot branch on prose, and a verdict is exactly the kind of dated,
-# derived record the model must never write — so the script writes it.
-#
-# Shared by design: analyze-design writes one per feature, and analyze-slice /
-# analyze-code will write one per story and per run. The CORE keys are fixed
-# (gate, status, feature, spec_version, story, gap_count, gap_refs, report,
-# generated_at) so a pipeline can read any gate's result with one expression;
-# everything gate-specific arrives through repeatable --field k=v and lands under
-# "fields", where it cannot destabilise that core.
-#
-# NOTE the returned `ok` means THE FILE WAS WRITTEN. The pass/fail verdict is
-# `status` — binding a workflow gate to `ok` would pass on every run.
-cmd_gate_result() {
-    local fd_arg="" gate="" ok="" version="" story="" report="" out="" gaps="" refs="" note="" fields=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --gate) gate="$2"; shift 2 ;;
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --ok) ok="$2"; shift 2 ;;
-            --spec-version) version="$2"; shift 2 ;;
-            --story) story="$2"; shift 2 ;;
-            --report) report="$2"; shift 2 ;;
-            --out) out="$2"; shift 2 ;;
-            --gap-count) gaps="$2"; shift 2 ;;
-            --gap-refs) refs="$2"; shift 2 ;;
-            --note) note="$2"; shift 2 ;;
-            --field) fields="${fields}$2"$'\n'; shift 2 ;;
-            --help|-h) echo "gate-result --gate <name> --ok <true|false> [--feature-dir <p>] [--spec-version <v>] [--story <id>] [--report <path>] [--out <path>] [--gap-count <n>] [--gap-refs <csv>] [--note <text>] [--field k=v]..."; return 0 ;;
-            *) echo "gate-result: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    [ -n "$gate" ] || { echo "gate-result: --gate required" >&2; return 1; }
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "gate-result: no feature set and no --feature-dir" >&2; return 1; }
-    AW_GATE="$gate" AW_FD="$fd" AW_OK="$ok" AW_VERSION="$version" AW_STORY="$story" \
-    AW_REPORT="$report" AW_OUT="$out" AW_GAPS="$gaps" AW_REFS="$refs" AW_NOTE="$note" \
-    AW_FIELDS="$fields" python3 - <<'PY'
-import json, os, sys, datetime
-gate   = (os.environ.get("AW_GATE", "") or "").strip() or "gate"
-fd     = os.environ.get("AW_FD", "")
-report = (os.environ.get("AW_REPORT", "") or "").strip()
-out    = (os.environ.get("AW_OUT", "") or "").strip()
-# "pass" only on an explicit affirmative. An absent or unreadable verdict is a FAIL,
-# because a result that defaults green turns every broken run into a passing one.
-ok = (os.environ.get("AW_OK", "") or "").strip().lower() in ("true", "1", "yes", "pass", "ok")
-# Written BESIDE the markdown report and named after it, so a job holding either path
-# holds the other. --out overrides; with no report named at all it falls back to a
-# dotfile in the feature directory under the gate's own name.
-if not out:
-    out = (os.path.splitext(report)[0] + ".json") if report else os.path.join(fd, ".aw-gate-%s.json" % gate)
-try: gap_count = int((os.environ.get("AW_GAPS", "") or "").strip() or 0)
-except ValueError: gap_count = 0
-refs = [r.strip() for r in (os.environ.get("AW_REFS", "") or "").replace(";", ",").split(",") if r.strip()]
-# A fail reporting zero findings reads as green to anything that sums the number
-# rather than reading the status, so a red verdict always carries at least one.
-if not ok and gap_count < 1: gap_count = max(1, len(refs))
-# --field k=v, repeatable, arriving newline-separated. Keeps the CORE schema below
-# fixed for every gate while each one carries its own detail underneath.
-fields = {}
-for line in (os.environ.get("AW_FIELDS", "") or "").splitlines():
-    k, sep, v = line.partition("=")
-    if sep and k.strip(): fields[k.strip()] = v.strip()
-res = {"gate": gate,
-       "status": "pass" if ok else "fail",
-       "feature": os.path.basename(fd.rstrip("/\\")),
-       "feature_dir": fd,
-       "spec_version": (os.environ.get("AW_VERSION", "") or "").strip(),
-       "story": (os.environ.get("AW_STORY", "") or "").strip(),
-       "gap_count": gap_count,
-       "gap_refs": refs,
-       "report": report,
-       "note": (os.environ.get("AW_NOTE", "") or "").strip(),
-       "fields": fields,
-       "generated_at": datetime.datetime.now().isoformat(timespec="seconds")}
-d = os.path.dirname(out)
-if d and not os.path.isdir(d): os.makedirs(d, exist_ok=True)
-open(out, "w", encoding="utf-8").write(json.dumps(res, indent=2) + "\n")
-print(json.dumps({"ok": True, "result_file": out, "status": res["status"], "gap_count": gap_count}))
-PY
-}
-
-# ─────────────── story-plan-check / story-plan-doc / log-append ───────────────
-# The per-story execution design ("story design") — SHORT-LIVED scaffolding, ONE
-# DOCUMENT PER LANE beside the story: stories/<ID>/story-backend-plan.md and
-# stories/<ID>/story-frontend-plan.md. Every /appweaver story-plan run
-# APPENDS a dated "## Design pass N" section; the LATEST pass wins and nothing is
-# edited in place, so a manual edit to an earlier pass survives a re-run. The
-# document's identity is positional (its directory): no story id appears in its
-# text. Writing into stories/<ID>/ is what flips the story IN-FLIGHT for
-# sync-stories' follow-on rule — the same isdir test story-spec's projection used
-# to trip.
-#
-# story-plan-check resolves WHICH story (an explicit --story, an id found in the
-# free-text input, or the open backlog for an ask), and reports everything the
-# workflow gates on: status, cited ids, the Constraints section's bound ids, ledger
-# rows above the story's stamp (staleness), doc/pass state and the feature's
-# append-only log paths. Always exits 0 with ok/flag fields — the workflow's
-# verify_context owns every stop (the lane-verify convention).
-#
-# story-plan-doc is the ONLY writer of either lane's design: --lane picks the file,
-# and it scaffolds the shell (frontmatter + contract comment) on first use, appends
-# the authored pass under a SCRIPT-written header (the model writes no pass number,
-# date or version), stamps the frontmatter and removes the temp pass file. Pass
-# numbers are per lane. A pre-split story-plan.md is reported by story-plan-check as
-# legacy_doc and touched by nothing.
-#
-# log-append owns the feature's two append-only logs: interfaces.md (IF-nnn — the
-# FE/BE contract anchor; BE design appends status:proposed, story close verifies
-# against the as-built and flips to live) and adr.md (ADR-nnn — ratified decisions).
-# The script assigns ids, dates and status; entries are never edited afterwards,
-# only superseded by later entries naming `supersedes:`.
-cmd_story_plan_check() {
-    local fd_arg="" input="" story=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir) fd_arg="$2"; shift 2 ;;
-            --input) input="$2"; shift 2 ;;
-            --story) story="$2"; shift 2 ;;
-            --help|-h) echo "story-plan-check [--story <id>] [--input <free text>] [--feature-dir <path>]"; return 0 ;;
-            *) echo "story-plan-check: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-plan-check: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_INPUT="$input" AW_STORY="$story" python3 - <<'PY'
-import json, os, re, sys
-fd = os.environ["AW_FD"]
-sdir = os.path.join(fd, "stories")
-spec = os.path.join(fd, "spec.md")
-
-def parse_fm(text):
-    """Frontmatter as a flat dict — inline and block-list values both fold to the
-    inline shape (same reader story-refs uses, for the same reason)."""
-    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
-    if not m: return {}
-    fm, key, block = {}, None, set()
-    for line in m.group(1).split("\n"):
-        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
-        if km:
-            key = km.group(1); fm[key] = km.group(2).strip(); continue
-        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
-        if im and (key in block or not fm[key]):
-            block.add(key)
-            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
-    return fm
-
-def vtuple(v):
-    try: return tuple(int(x) for x in v.lstrip("vV").split("."))
-    except Exception: return (0,)
-
-# ---- the backlog ------------------------------------------------------------
-stories = []
-if os.path.isdir(sdir):
-    for name in sorted(os.listdir(sdir)):
-        # stories.md is the GENERATED index beside the stories, not a story
-        if not name.endswith(".md") or name == "stories.md": continue
-        p = os.path.join(sdir, name)
-        if not os.path.isfile(p): continue
-        text = open(p, encoding="utf-8", errors="replace").read()
-        fm = parse_fm(text)
-        sid = fm.get("id") or name[:-3]
-        stories.append({"id": sid, "file_id": name[:-3],
-                        "status": (fm.get("status") or "open").strip().lower(),
-                        "type": (fm.get("type") or "functional").strip().lower(),
-                        "title": (fm.get("title") or "").strip().strip("[]"),
-                        "spec_version": (fm.get("spec_version") or "").strip(),
-                        "cites": re.findall(r'\b(?:FR|BR)-\d+', fm.get("exercises", "")),
-                        "path": p, "text": text})
-open_stories = [s for s in stories if s["status"] == "open"]
-open_ids = [s["id"] for s in open_stories]
-digest = "\n".join("  %-16s %s%s" % (s["id"], s["title"] or "(untitled)",
-                                     ("  cites " + ", ".join(s["cites"])) if s["cites"] else "")
-                   for s in open_stories) or "  (no open stories)"
-
-# ---- which story ------------------------------------------------------------
-want = (os.environ.get("AW_STORY") or "").strip()
-free = os.environ.get("AW_INPUT") or ""
-target, reason = None, ""
-if want:
-    hit = [s for s in stories if s["id"] == want or s["file_id"] == want]
-    target = hit[0] if hit else None
-    if not target: reason = "not-found"
-else:
-    # every known story id appearing as a whole token in the free text; one match
-    # resolves, several is a question, none is a question
-    named = [s for s in stories
-             if re.search(r'(?<![\w-])' + re.escape(s["id"]) + r'(?![\w-])', free)]
-    if len(named) == 1: target = named[0]
-    else: reason = "ambiguous" if named else "none-given"
-
-out = {"ok": True, "stories_dir": sdir, "stories_exist": os.path.isdir(sdir),
-       "open_count": len(open_stories), "any_open": bool(open_stories),
-       "open_ids": open_ids, "open_ids_csv": ", ".join(open_ids), "digest": digest,
-       "resolved": bool(target), "needs_pick": not target, "pick_reason": reason,
-       "story": "", "story_path": "", "story_status": "", "story_open": False,
-       "story_type": "", "is_technical": False,
-       "status_msg": "", "story_title": "", "exercises_csv": "", "constraints_csv": "",
-       "story_spec_version": "", "current_version": "", "stale_csv": "", "stale_note": "",
-       "story_dir": "", "if_tmp": "", "legacy_doc": "", "legacy_doc_exists": False,
-       "be_doc_path": "", "be_doc_exists": False, "be_next_pass": 1, "be_pass_tmp": "",
-       "be_last_pass": 0, "be_doc_spec_version": "", "be_doc_stale": False,
-       "fe_doc_path": "", "fe_doc_exists": False, "fe_next_pass": 1, "fe_pass_tmp": "",
-       "fe_last_pass": 0, "fe_doc_spec_version": "", "fe_doc_stale": False,
-       "adr_path": os.path.join(fd, "adr.md"), "adr_exists": os.path.isfile(os.path.join(fd, "adr.md")),
-       "if_path": os.path.join(fd, "interfaces.md"), "if_exists": os.path.isfile(os.path.join(fd, "interfaces.md")),
-       "spec_exists": os.path.isfile(spec)}
-
-# ---- the ledger (widest-wins current version, same rule ledger-append uses) --
-rows, cur = [], ""
-if os.path.isfile(spec):
-    stext = open(spec, encoding="utf-8", errors="replace").read()
-    m = re.search(r'^##\s+Change History\s*$', stext, re.M)
-    if m:
-        for line in stext[m.end():].splitlines():
-            rm = re.match(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', line)
-            if rm: rows.append((rm.group(1), line))
-    hv = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', stext, re.M)
-    cands = [r[0] for r in rows] + ([hv.group(1)] if hv else [])
-    if cands: cur = max(cands, key=vtuple)
-out["current_version"] = cur
-
-if not target:
-    print(json.dumps(out)); sys.exit(0)
-
-# ---- the resolved story -----------------------------------------------------
-status = target["status"]
-out.update(story=target["id"], story_path=target["path"], story_status=status,
-           story_open=(status == "open"), story_title=target["title"],
-           story_type=target["type"], is_technical=(target["type"] == "technical"),
-           exercises_csv=", ".join(target["cites"]),
-           story_spec_version=target["spec_version"])
-if status != "open":
-    verb = {"closed": "was closed — its plan is history. Remaining work needs its own story "
-                      "(sync-stories mints a follow-on when the spec moves)",
-            "cancelled": "was cancelled — cancelled work is not planned; open a new story if the need returns",
-            "draft": "is a draft proposal — run /appweaver sync-spec to merge it into the contract first; "
-                     "story-plan designs only against merged requirements"}
-    out["status_msg"] = "Story %s %s." % (
-        target["id"], verb.get(status, "has status '%s', not open" % status))
-
-# bound constraint ids come from the story BODY's ## Constraints section (they are
-# barred from exercises: by design — met, not delivered)
-cm = re.search(r'^##\s+Constraints\s*$(.*?)(?=^##\s|\Z)', target["text"], re.M | re.S)
-cons = sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', cm.group(1)))) if cm else []
-out["constraints_csv"] = ", ".join(cons)
-
-# staleness: ledger rows ABOVE the story's stamp naming an id the story carries —
-# exercises: AND the Constraints section, so a moved bound is announced too
-sv = target["spec_version"]
-if sv:
-    carried = set(target["cites"]) | set(cons)
-    moved = [r for r in rows if vtuple(r[0]) > vtuple(sv)]
-    stale = sorted({i for _v, l in moved for i in re.findall(r'[A-Z]{2}-\d+', l) if i in carried})
-    out["stale_csv"] = ", ".join(stale)
-    if stale:
-        out["stale_note"] = (
-            "CAUTION: the spec moved above this story's stamp (%s -> %s) on ids this story "
-            "carries: %s. Design against the CURRENT spec text, record the divergence under "
-            "Risks, and consider /appweaver sync-stories to bring the backlog back in step."
-            % (sv, cur or "?", ", ".join(stale)))
-
-# doc / pass state + the temp paths the workflow writes through. ONE DOCUMENT PER
-# LANE: the service design and the UI design are authored by different steps, under
-# different rule sets, from different code, and are read by different implement
-# commands — folded into one file, every one of those becomes a section boundary the
-# next reader has to trust. Pass numbers are per file, so a run that designs only the
-# backend leaves the frontend's count exactly where it was.
-#
-# legacy_doc is the pre-split story-plan.md. It is REPORTED, never read and never
-# written: a design nobody consumes must not sit silently beside two that are.
-stdir = os.path.join(sdir, target["id"])
-legacy = os.path.join(stdir, "story-plan.md")
-out.update(story_dir=stdir, if_tmp=os.path.join(stdir, ".if-entries.tmp.md"),
-           legacy_doc=legacy, legacy_doc_exists=os.path.isfile(legacy))
-for lane, stem in (("be", "backend"), ("fe", "frontend")):
-    doc = os.path.join(stdir, "story-%s-plan.md" % stem)
-    out[lane + "_doc_path"] = doc
-    out[lane + "_doc_exists"] = os.path.isfile(doc)
-    out[lane + "_pass_tmp"] = os.path.join(stdir, ".%s-pass.tmp.md" % stem)
-    if out[lane + "_doc_exists"]:
-        d = open(doc, encoding="utf-8", errors="replace").read()
-        nums = [int(n) for n in re.findall(r'^##\s+Design pass\s+(\d+)', d, re.M)]
-        out[lane + "_next_pass"] = (max(nums) + 1) if nums else 1
-        # What implement needs on top of the path: WHICH pass it builds from (the last
-        # one — earlier passes are superseded history) and the spec version that pass was
-        # designed against. A design behind the current spec is ANNOUNCED at implement,
-        # never refused: the story is legitimately in flight, and the spec may well have
-        # moved on ids this story does not carry. stale_csv is the sharper signal and it
-        # is already computed above.
-        out[lane + "_last_pass"] = max(nums) if nums else 0
-        dv = (parse_fm(d).get("spec_version") or "").strip().strip('"')
-        out[lane + "_doc_spec_version"] = dv
-        out[lane + "_doc_stale"] = bool(dv and cur and vtuple(dv) < vtuple(cur))
-print(json.dumps(out))
-PY
-}
-
-cmd_story_plan_doc() {
-    local fd_arg="" story="" pass_file="" spec_version="" lane="backend"
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir)   fd_arg="$2"; shift 2 ;;
-            --story)         story="$2"; shift 2 ;;
-            --lane)          lane="$2"; shift 2 ;;
-            --pass-file)     pass_file="$2"; shift 2 ;;
-            --spec-version)  spec_version="$2"; shift 2 ;;
-            --help|-h) echo "story-plan-doc --story <id> --pass-file <path> [--lane backend|frontend] [--spec-version <v>] [--feature-dir <path>]"; return 0 ;;
-            *) echo "story-plan-doc: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    [ -n "$story" ] || { echo "story-plan-doc: --story is required" >&2; return 1; }
-    [ -n "$pass_file" ] || { echo "story-plan-doc: --pass-file is required" >&2; return 1; }
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-plan-doc: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_STORY="$story" AW_LANE="$lane" AW_PASS="$pass_file" AW_VER="$spec_version" python3 - <<'PY'
-import json, os, re, sys, datetime
-fd = os.environ["AW_FD"]; story = os.environ["AW_STORY"].strip()
-pf = os.environ["AW_PASS"]; ver = (os.environ.get("AW_VER") or "").strip()
-lane = (os.environ.get("AW_LANE") or "backend").strip().lower()
-sdir = os.path.join(fd, "stories", story)
-doc = os.path.join(sdir, "story-%s-plan.md" % lane)
-
-def bail(msg, code=2):
-    print(json.dumps({"ok": False, "doc": doc, "error": msg}))
-    sys.stderr.write(msg + "\n"); sys.exit(code)
-
-if lane not in ("backend", "frontend"):
-    bail("story-plan-doc: --lane must be backend or frontend, not '%s'" % lane)
-if not os.path.isfile(os.path.join(fd, "stories", story + ".md")):
-    bail("story-plan-doc: no story file for '%s' — the plan lives beside a story that exists" % story)
-if not os.path.isfile(pf):
-    bail("story-plan-doc: pass file missing at %s — the authoring step wrote nothing" % pf)
-content = open(pf, encoding="utf-8", errors="replace").read().strip()
-if not content:
-    bail("story-plan-doc: the authored pass is empty — nothing appended")
-# the pass header is SCRIPT-written; strip one the model wrote anyway rather than
-# letting the doc double-number
-content = re.sub(r'^##\s+Design pass\b[^\n]*\n+', '', content, count=1)
-
-LANE_WORD = "SERVICE" if lane == "backend" else "UI"
-LANE_READER = "/appweaver implement" if lane == "backend" else "/appweaver implement-ui"
-os.makedirs(sdir, exist_ok=True)
-today = datetime.date.today().isoformat()
-created = not os.path.isfile(doc)
-if created:
-    open(doc, "w", encoding="utf-8").write("""---
-created: %s
-updated: %s
-passes: 0
-spec_version: ""
----
-
-<!--
-  STORY DESIGN (%s LANE) — the ephemeral execution design for ONE story, read by
-  %s.
-
-  Identity is positional: the file lives in the story's directory and carries no
-  story id in its text. Every /appweaver story-plan run APPENDS a "## Design pass N"
-  section to THIS lane's file — nothing is edited in place, so a manual edit to an
-  earlier pass survives a re-run. THE LATEST PASS WINS; earlier passes are the
-  iteration history.
-
-  EDIT IT BEFORE YOU IMPLEMENT. This is the document a design is corrected in by
-  hand: change the latest pass and implement builds what you changed. Re-running
-  story-plan instead appends a fresh pass that supersedes it, so hand-edit to
-  adjust, re-run to redesign.
-
-  It is scaffolding for confirming the implementation strategy — archived with the
-  story at close, never maintained afterwards. Durable decisions do not live here:
-  the latest pass PROPOSES ADRs (ratified into the feature's adr.md at close), and
-  published-surface changes are appended to the feature's interfaces.md as proposed
-  entries at design time. spec_version below is the spec the LATEST pass was
-  designed against. The other lane's design, where the project has one, sits beside
-  this file — the two are written apart on purpose and neither restates the other.
--->
-""" % (today, today, LANE_WORD, LANE_READER))
-text = open(doc, encoding="utf-8", errors="replace").read()
-nums = [int(n) for n in re.findall(r'^##\s+Design pass\s+(\d+)', text, re.M)]
-n = (max(nums) + 1) if nums else 1
-header = "## Design pass %d — %s%s" % (n, today, (" (spec %s)" % ver) if ver else "")
-text = text.rstrip("\n") + "\n\n" + header + "\n\n" + content + "\n"
-# frontmatter stamps — first match only, which is the frontmatter by position
-text = re.sub(r'^(updated:).*$', r'\g<1> ' + today, text, count=1, flags=re.M)
-text = re.sub(r'^(passes:).*$', r'\g<1> %d' % n, text, count=1, flags=re.M)
-if ver:
-    text = re.sub(r'^(spec_version:).*$', r'\g<1> %s' % ver, text, count=1, flags=re.M)
-open(doc, "w", encoding="utf-8").write(text)
-os.remove(pf)
-print(json.dumps({"ok": True, "doc": doc, "lane": lane, "pass": n, "created": created,
-                  "spec_version": ver, "story_dir": sdir}))
-PY
-}
-
-cmd_log_append() {
-    local fd_arg="" log="" entries_file="" status=""
-    while [ $# -gt 0 ]; do
-        case "$1" in
-            --feature-dir)  fd_arg="$2"; shift 2 ;;
-            --log)          log="$2"; shift 2 ;;
-            --entries-file) entries_file="$2"; shift 2 ;;
-            --status)       status="$2"; shift 2 ;;
-            --help|-h) echo "log-append --log adr|interfaces --entries-file <path> [--status <s>] [--feature-dir <path>]"; return 0 ;;
-            *) echo "log-append: unknown arg '$1'" >&2; return 1 ;;
-        esac
-    done
-    case "$log" in adr|interfaces) ;; *) echo "log-append: --log must be adr or interfaces" >&2; return 1 ;; esac
-    [ -n "$entries_file" ] || { echo "log-append: --entries-file is required" >&2; return 1; }
-    local repo_root; repo_root=$(get_repo_root)
-    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "log-append: no feature set and no --feature-dir" >&2; return 1; }
-    AW_FD="$fd" AW_LOG="$log" AW_ENTRIES="$entries_file" AW_STATUS="$status" python3 - <<'PY'
-import json, os, re, sys, datetime
-fd = os.environ["AW_FD"]; log = os.environ["AW_LOG"]
-ef = os.environ["AW_ENTRIES"]; status = (os.environ.get("AW_STATUS") or "").strip()
-fname, prefix, default_status, title = {
-    "interfaces": ("interfaces.md", "IF", "proposed", "Interface Log"),
-    "adr":        ("adr.md", "ADR", "accepted", "Architecture Decision Log")}[log]
-status = status or default_status
-path = os.path.join(fd, fname)
-
-def bail(msg, code=2):
-    print(json.dumps({"ok": False, "log": path, "error": msg}))
-    sys.stderr.write(msg + "\n"); sys.exit(code)
-
-if not os.path.isfile(ef):
-    bail("log-append: entries file missing at %s — the authoring step wrote nothing" % ef)
-raw = open(ef, encoding="utf-8", errors="replace").read().strip()
-if not raw or raw.lower().rstrip(".") == "none":
-    os.remove(ef)
-    print(json.dumps({"ok": True, "log": path, "appended": 0, "ids_csv": "",
-                      "unknown_ids_csv": "", "bad_supersedes_csv": "", "none": True}))
-    sys.exit(0)
-
-# every entry must arrive as '## <PREFIX>-NEW — <title>': the script is the only id
-# authority, so a model-numbered entry is refused rather than trusted
-blocks = [b.strip() for b in re.split(r'(?=^##\s)', raw, flags=re.M) if b.strip()]
-bad = [b.splitlines()[0] for b in blocks
-       if not re.match(r'^##\s+%s-NEW\s+[—-]+\s+\S' % prefix, b)]
-if bad:
-    bail("log-append: every entry must start '## %s-NEW — <title>' (the script assigns "
-         "ids); got: %s" % (prefix, " | ".join(bad[:3])))
-
-SCAFFOLD = {
-    "interfaces": """<!--
-  INTERFACE LOG — this feature's published-surface contract. APPEND-ONLY.
-
-  WHO WRITES: /appweaver plan publishes this feature's surface whenever it authors or
-  conforms backend-plan.md; a BE story plan appends an entry only where its slice
-  changes that surface. Both land as status: proposed, and story close verifies each
-  against the as-built and flips it to live.
-  WHO READS: /appweaver plan-ui and the FE story designs — this log is the BE-to-FE
-  contract anchor, and the plan documents CITE these ids rather than restating them.
-  The current surface per interface is the LATEST entry — one that names an earlier
-  id in `supersedes:` replaces it. Never edit an existing entry; publish a
-  superseding one. status: proposed -> live -> superseded | retired.
-  `serves:` cites the FR-/BR- ids the interface exists for, so a spec change to
-  those ids flags the contract for review.
--->
-
-# Interface Log
-""",
-    "adr": """<!--
-  ADR LOG — this feature's durable decisions. APPEND-ONLY.
-
-  A story plan PROPOSES ADRs in its latest design pass; they are ratified into this
-  log at story close, or the architect appends directly. Never rewrite an entry —
-  supersede it with a new one naming `supersedes:`. An ADR records ONLY what neither
-  the code nor the rules can say: a deliberate choice among rule-compliant
-  alternatives, a rejected alternative and why, or a trade-off with its revisit
-  trigger. It never restates what code shows or a rule mandates.
--->
-
-# Architecture Decision Log
-"""}
-created = not os.path.isfile(path)
-if created:
-    open(path, "w", encoding="utf-8").write(SCAFFOLD[log])
-text = open(path, encoding="utf-8", errors="replace").read()
-existing = set(re.findall(r'^##\s+(%s-\d+)' % prefix, text, re.M))
-nums = [int(i.split("-")[1]) for i in existing]
-nxt = (max(nums) + 1) if nums else 1
-today = datetime.date.today().isoformat()
-
-spec = os.path.join(fd, "spec.md")
-known = set(re.findall(r'\b[A-Z]{2}-\d+\b',
-                       open(spec, encoding="utf-8", errors="replace").read())) \
-        if os.path.isfile(spec) else set()
-
-assigned, unknown, badsup, out_blocks = [], [], [], []
-for b in blocks:
-    bid = "%s-%03d" % (prefix, nxt); nxt += 1
-    lines = b.splitlines()
-    lines[0] = lines[0].replace("%s-NEW" % prefix, bid, 1)
-    body = "\n".join(lines[1:]).strip("\n")
-    # status and date are script-stamped, whatever the model wrote
-    body = re.sub(r'^status:.*\n?', '', body, flags=re.M)
-    body = re.sub(r'^date:.*\n?', '', body, flags=re.M)
-    body = ("status: %s\ndate: %s" % (status, today)) + ("\n" + body if body else "")
-    for line in body.splitlines():
-        if line.startswith("serves:"):
-            unknown += [i for i in re.findall(r'\b[A-Z]{2}-\d+\b', line)
-                        if known and i not in known]
-        if line.startswith("supersedes:"):
-            badsup += [i for i in re.findall(r'\b%s-\d+\b' % prefix, line)
-                       if i not in existing]
-    out_blocks.append(lines[0] + "\n\n" + body)
-    assigned.append(bid)
-
-text = text.rstrip("\n") + "\n\n" + "\n\n".join(out_blocks) + "\n"
-open(path, "w", encoding="utf-8").write(text)
-os.remove(ef)
-print(json.dumps({"ok": True, "log": path, "appended": len(assigned),
-                  "ids_csv": ", ".join(assigned),
-                  "unknown_ids_csv": ", ".join(sorted(set(unknown))),
-                  "bad_supersedes_csv": ", ".join(sorted(set(badsup))),
-                  "none": False, "created_log": created}))
-PY
-}
-
 case "$sub" in
     resolve-domain)   cmd_resolve_domain "$@" ;;
     resolve-tech)     cmd_resolve_tech "$@" ;;
@@ -5418,39 +3609,33 @@ case "$sub" in
     lane-resolve)     cmd_lane_resolve "$@" ;;
     lane-verify)      cmd_lane_verify "$@" ;;
     lane-probe)       cmd_lane_probe "$@" ;;
+    list-contexts)    cmd_list_contexts "$@" ;;
+    set-context)      cmd_set_context "$@" ;;
     list-features)    cmd_list_features "$@" ;;
     set-feature)      cmd_set_feature "$@" ;;
     version-read)     cmd_version_read "$@" ;;
     version-init)     cmd_version_init "$@" ;;
-    spec-check)       cmd_spec_check "$@" ;;
-    spec-stamp)       cmd_spec_stamp "$@" ;;
-    ledger-append)    cmd_ledger_append "$@" ;;
-    ledger-ids)       cmd_ledger_ids "$@" ;;
-    spec-snapshot)    cmd_spec_snapshot "$@" ;;
-    spec-diff)        cmd_spec_diff "$@" ;;
-    story-refs)       cmd_story_refs "$@" ;;
-    slice-mode)       cmd_slice_mode "$@" ;;
-    backlog-plan)     cmd_backlog_plan "$@" ;;
-    story-stamp)      cmd_story_stamp "$@" ;;
-    story-plan-check) cmd_story_plan_check "$@" ;;
-    story-plan-doc)   cmd_story_plan_doc "$@" ;;
-    log-append)       cmd_log_append "$@" ;;
-    ledger-read)      cmd_ledger_read "$@" ;;
-    spec-coverage)    cmd_spec_coverage "$@" ;;
-    spec-preserve)    cmd_spec_preserve "$@" ;;
-    spec-markers)     cmd_spec_markers "$@" ;;
+    version-bootstrap-done) cmd_version_bootstrap_done "$@" ;;
     feature-paths)    cmd_feature_paths "$@" ;;
     design-scaffold)  cmd_design_scaffold "$@" ;;
-    plan-check)       cmd_plan_check "$@" ;;
-    plan-stamp)       cmd_plan_stamp "$@" ;;
-    gate-result)      cmd_gate_result "$@" ;;
+    # The plan phase's name for the same op. Both spellings reach one implementation:
+    # --lane backend|frontend writes the plan documents, --lane service|ui the legacy
+    # names the brownfield reverse pass still authors.
+    plan-scaffold)    cmd_design_scaffold "$@" ;;
+    delta-plan-scaffold) cmd_delta_plan_scaffold "$@" ;;
     build-compile)    cmd_build_compile "$@" ;;
     test-run)         cmd_test_run "$@" ;;
-    test-diff)        cmd_test_diff "$@" ;;
     run-migrate)      cmd_run_migrate "$@" ;;
     deploy-dispatch)  cmd_deploy_dispatch "$@" ;;
     cr-setup)         cmd_cr_setup "$@" ;;
+    cr-list)          cmd_cr_list "$@" ;;
+    cr-paths)         cmd_cr_paths "$@" ;;
+    cr-overlap)       cmd_cr_overlap "$@" ;;
+    cr-activate)      cmd_cr_activate "$@" ;;
+    cr-wave)          cmd_cr_wave "$@" ;;
     cr-archive)       cmd_cr_archive "$@" ;;
+    context-paths)    cmd_context_paths "$@" ;;
+    model-scaffold)   cmd_model_scaffold "$@" ;;
     version-stamp)    cmd_version_stamp "$@" ;;
     checklist-read)   cmd_checklist_read "$@" ;;
     checklist-apply)  cmd_checklist_apply "$@" ;;