aw-spec-cli 0.1.7 → 0.1.9

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

@@ -0,0 +1,2626 @@
+#!/usr/bin/env bash
+#
+# aw-spec-actions.sh — common action dispatcher for the aw-spec orchestrator.
+#
+# ONE shared script for every integration (.claude / .agents / .kilocode). The
+# orchestrator workflows reach these subcommands through `execute_script` steps.
+# Each subcommand performs deterministic, governance-safe work and prints a single
+# JSON object on stdout. NONE of these actions author spec/code content — content
+# generation is the LLM's job, in the workflow's agent_* steps.
+#
+# Usage:
+#   aw-spec-actions.sh <subcommand> [options]
+#
+# Subcommands:
+#   resolve-domain   --command <name>              -> {domain, rulemap_exists, candidates[]}
+#   resolve-tech     --command <name>              -> {domain, techrulemap_exists, candidates[]}
+#   scaffold         --feature-dir <path> [--allow-existing]
+#                                                  -> {feature_dir, spec_file, template, created, spec_created}
+#   resolve-hooks    --phase <before_specify|after_specify>
+#                                                  -> {phase, hooks[]}
+#   create-checklist --feature-dir <path> [--feature-name <name>]
+#                                                  -> {checklist_file, created}
+#   list-domains                                   -> {domains[]}
+#   set-domain       --domain <name>               -> {domain, map_path, map_exists, written}
+#   stack-list       [--kind backend|frontend|all] [--preselect <text>] [--include-none] [--suggest]
+#                                                  -> {profiles[], ids[], select_options[], count, preselect,
+#                                                      detected_profile, detected_root, root_options[], none_sentinel}
+#                    (--suggest also detects, so the menu opens on what the repo IS)
+#   stack-detect     [--kind <k>] [--exclude-root <p>]…  -> {matches[], backend, frontend, count}
+#                    (matches the repo's OWN files against the profiles; writes nothing)
+#   lane-declare     --profile <id|label|none|detected> [--kind <k>] [--id <lane>] [--source-path|--root <p>]
+#                    [--stack <label>] [--origin declared|reverse-engineered] [--require-existing-root]
+#                    [--build <c>] [--test <c>] [--run <c>] [--prototype-root <p>] [--prototype-run <c>] [--no-prototype]
+#                                                  -> {declared, lane, lanes[], lane_count, source_path, root_exists, prototype, written}
+#                    (SOLE WRITER of .appweaver/stacks.json; callers = select-stack, onboard)
+#   lane-resolve     [--kind <k>] [--id <lane>]    -> {declared, lanes[], found, lane, root, source_path, build, test, run,
+#                                                      backend_*/frontend_* (declared, root, source_path, root_exists, build, test, run), prototype}
+#                    (absence is a valid state: no stacks.json -> declared:false, exit 0)
+#   lane-verify      [--require backend|frontend]… [--allow-missing-root] [--command <phase>]
+#                                                  -> {ok, declared, issues[], issue_count, message, backend_*/frontend_*}
+#                    (the GATE: is the declaration usable for the phase about to run.
+#                     Always exits 0 — the workflow's verify_context owns the stop)
+#   lane-probe       [--kind <k>] [--hint <text>]  -> {declared, declared_profile, hint_profile, hint_terms[], signals[], any, evidence}
+#                    (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>]        -> {feature, version, active_change, created}   (create active_version.json v1.0)
+#   feature-paths                                  -> {feature, feature_dir, spec_file, design_file, spec_exists, design_exists}
+#   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[]}
+#   foundation-list  [--args '<F> <A> [out]']      -> {foundations[], count, preselect_name, preselect_app, out_dir}
+#   foundation-locate --name <F> --app <A> [--out <d>]
+#                                                  -> {ok, reason, name, app, out_dir, pack_file, unpacker, runner, sentinel, file_count, available[]}
+#   foundation-unpack --name <F> --app <A> --out <d> [--dry-run] [--force <yes|no>] [--reference]
+#                                                  -> {ok, mode, written, has_collisions, stdout}
+#   foundation-verify --out <d> --sentinel <s>     -> {clean, residue[]}
+#   list-components                                -> {components[]}  (foundations/dotnet/components/* with integration.md)
+#   find-host-project                              -> {found, program_cs, project_dir, csproj}
+#   setup-constitution [--ui]                      -> {constitution_technical_file, constitution_domain_file, constitution_ui_file, technical_created, domain_created, ui_created}
+#   compose-constitution                           -> {composed_file, ok, domain_included, ui_included, numbering_ok, numbering_checked, issues, technical_last, domain_first}
+#   constitution-verify --file <path> [--template <name>]
+#                                                  -> {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}
+#   (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.)
+#   build-compile    [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail}
+#   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-archive       --cr-id <id> [--feature-dir <path>]
+#                                                  -> {ok, archived_dir, version, previous}
+#
+# All subcommands accept --help.
+
+set -e
+
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=common.sh
+source "$SCRIPT_DIR/common.sh"
+
+# ─────────────────────────── small JSON helpers ────────────────────────────
+# Emit a JSON array of strings from remaining args.
+json_str_array() {
+    local out="[" first=1 s
+    for s in "$@"; do
+        [ $first -eq 1 ] && first=0 || out+=","
+        out+="\"$(json_escape "$s")\""
+    done
+    out+="]"
+    printf '%s' "$out"
+}
+
+# ─────────────────────────────── resolve-domain ────────────────────────────
+cmd_resolve_domain() {
+    local command_name="aw-spec-specify"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --command) command_name="$2"; shift 2 ;;
+            --help|-h) echo "resolve-domain --command <name>"; return 0 ;;
+            *) echo "resolve-domain: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+
+    local repo_root; repo_root=$(get_repo_root)
+    local domain_json="$repo_root/.appweaver/domain.json"
+    local domain=""
+    if [ -f "$domain_json" ]; then
+        if command -v jq >/dev/null 2>&1; then
+            domain=$(jq -r '.domain // ""' "$domain_json" 2>/dev/null || echo "")
+        else
+            domain=$( { grep -E '"domain"[[:space:]]*:' "$domain_json" 2>/dev/null || true; } \
+                | head -n1 | sed -E 's/^[^:]*:[[:space:]]*"([^"]*)".*$/\1/' )
+        fi
+    fi
+
+    local rulemap="$repo_root/guardrails/projects/$domain/domain-rule-bindings.md"
+    local rulemap_exists=false
+    [ -n "$domain" ] && [ -f "$rulemap" ] && rulemap_exists=true
+
+    # Collect bullet paths under "## /<command>" in the domain's domain-rule-bindings.md.
+    local -a candidates=()
+    if [ "$rulemap_exists" = true ]; then
+        # awk: capture "- path" bullets between the target "## <heading>" and the next "## "
+        while IFS= read -r line; do
+            [ -n "$line" ] && candidates+=("$line")
+        done < <(awk -v h="## /$command_name" '
+            $0==h {grab=1; next}
+            /^## / {grab=0}
+            grab && /^[[:space:]]*-[[:space:]]+/ {
+                sub(/^[[:space:]]*-[[:space:]]+/,""); sub(/[[:space:]]+$/,""); print
+            }
+        ' "$rulemap")
+    fi
+
+    printf '{"domain":"%s","rulemap_exists":%s,"candidates":%s}\n' \
+        "$(json_escape "$domain")" "$rulemap_exists" "$(json_str_array "${candidates[@]}")"
+}
+
+# ──────────────────────────────── resolve-tech ─────────────────────────────
+# Technical rule-file mapping — parallel to resolve-domain, but reads
+# guardrails/projects/<project>/tech-rule-bindings.md. The TECHNICAL rule files live in the
+# shared per-stack corpora at guardrails/technology/<stack>/ (rules) and
+# guardrails/technology/<stack>/examples/ (the worked sample for a rule file), and are
+# configured per-command in this map, so they can be tuned per project WITHOUT editing the
+# workflows and a second project can map the same corpus. The technical CONSTITUTION
+# (constitution.technical.md) is NOT mapped — it is still referred to directly by
+# each consumer, as-is.
+#
+# A bullet may name its stack with a PLACEHOLDER — {{stack}} / {{backend_stack}} /
+# {{frontend_stack}} / {{backend_ecosystem}} / {{frontend_ecosystem}} — resolved from
+# the lanes in .appweaver/stacks.json. That is what lets one map serve a Spring repo and
+# a .NET repo without an edit. A bullet that instead spells a stack directory out is kept
+# and USED (it may be a deliberate cross-stack reference) but reported through
+# 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-design"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --command) command_name="$2"; shift 2 ;;
+            --help|-h) echo "resolve-tech --command <name>"; return 0 ;;
+            *) echo "resolve-tech: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+
+    local repo_root; repo_root=$(get_repo_root)
+    local domain_json="$repo_root/.appweaver/domain.json"
+    local domain=""
+    if [ -f "$domain_json" ]; then
+        if command -v jq >/dev/null 2>&1; then
+            domain=$(jq -r '.domain // ""' "$domain_json" 2>/dev/null || echo "")
+        else
+            domain=$( { grep -E '"domain"[[:space:]]*:' "$domain_json" 2>/dev/null || true; } \
+                | head -n1 | sed -E 's/^[^:]*:[[:space:]]*"([^"]*)".*$/\1/' )
+        fi
+    fi
+
+    # The declared stacks, so one map can be written for any of them.
+    local be_prof fe_prof be_eco fe_eco
+    be_prof=$(_aw_lane_field backend profile);  fe_prof=$(_aw_lane_field frontend profile)
+    be_eco=$(_aw_lane_field backend ecosystem); fe_eco=$(_aw_lane_field frontend ecosystem)
+
+    AW_REPO="$repo_root" AW_DOMAIN="$domain" AW_COMMAND="$command_name" \
+    AW_BE_PROFILE="$be_prof" AW_FE_PROFILE="$fe_prof" \
+    AW_BE_ECO="$be_eco" AW_FE_ECO="$fe_eco" python3 - <<'RESOLVE_TECH_PY'
+import json, os, re
+
+repo    = os.environ["AW_REPO"]
+domain  = os.environ.get("AW_DOMAIN", "")
+command = os.environ.get("AW_COMMAND", "")
+
+techmap = os.path.join(repo, "guardrails", "projects", domain, "tech-rule-bindings.md")
+exists  = bool(domain) and os.path.isfile(techmap)
+
+# WHAT A PLACEHOLDER IS FOR. A technical rule corpus is stack-partitioned —
+# guardrails/technology/<stack>/ — so a bullet that spells the stack out is pinned to
+# it, and the same map read from a Spring repo loads .NET rules into the standards the
+# generator obeys. The placeholders let ONE map serve every stack a project declares:
+# they resolve out of .appweaver/stacks.json, already the single answer to "what is
+# this repo built in". Bullets without one are untouched, so every existing map reads
+# exactly as it did.
+subs = {
+    "backend_stack":      os.environ.get("AW_BE_PROFILE", ""),
+    "frontend_stack":     os.environ.get("AW_FE_PROFILE", ""),
+    "backend_ecosystem":  os.environ.get("AW_BE_ECO", ""),
+    "frontend_ecosystem": os.environ.get("AW_FE_ECO", ""),
+}
+subs["stack"] = subs["backend_stack"]          # the unqualified form means the service lane
+declared = set(v for v in subs.values() if v)
+
+HOLE = re.compile(r"\{\{\s*([a-z_]+)\s*\}\}")
+
+def expand(line):
+    """(resolved path, reason) — reason is '' when the line resolved."""
+    for h in HOLE.findall(line):
+        if h not in subs:
+            return "", "unknown placeholder {{%s}}" % h
+        if not subs[h]:
+            # A frontend placeholder in a backend-only repo is not an error: the lane
+            # genuinely does not exist, so its rules genuinely do not apply.
+            return "", "no lane declared for {{%s}}" % h
+    return HOLE.sub(lambda m: subs[m.group(1)], line), ""
+
+bullets = []
+if exists:
+    text = open(techmap, encoding="utf-8").read().splitlines()
+    for heading in ("## /" + command, "## /" + command.replace("decl-", "")):
+        found, grab = [], False
+        for line in text:
+            if line.strip() == heading:
+                grab = True; continue
+            if line.startswith("## "):
+                grab = False; continue
+            if grab:
+                m = re.match(r"^\s*-\s+(.*?)\s*$", line)
+                if m:
+                    found.append(m.group(1))
+        if found:
+            bullets = found
+            break
+
+candidates, missing, skipped, mismatched = [], [], [], []
+for b in bullets:
+    path, why = expand(b)
+    if why:
+        skipped.append({"bullet": b, "why": why}); continue
+    (candidates if os.path.isfile(os.path.join(repo, path)) else missing).append(path)
+    # A LITERAL stack directory that is not one this repo declares. Reported, never
+    # dropped: the file exists and the project chose it, so it may be a deliberate
+    # cross-stack reference — but it is also exactly how a Java repo ends up being
+    # handed C# rules, and that must not be invisible.
+    m = re.match(r"^guardrails/technology/([^/]+)/", path)
+    if m and declared and m.group(1) not in declared and "{{" not in b:
+        if m.group(1) not in mismatched:
+            mismatched.append(m.group(1))
+
+print(json.dumps({
+    "domain": domain,
+    "techrulemap_exists": exists,
+    "candidates": candidates,
+    "missing": missing,
+    "skipped": skipped,
+    "declared_stacks": sorted(declared),
+    "stack_mismatch": bool(mismatched),
+    "mismatched_stacks": mismatched,
+}))
+RESOLVE_TECH_PY
+}
+
+# ─────────────────────────────── derive-names ──────────────────────────────
+# Deterministic naming — NO LLM. Aggregate/Feature token wins; else kebab
+# short-name (stop-word filtered) + General aggregate.
+_pascal() {  # kebab/space -> PascalCase
+    local in="$1" out="" w
+    in="${in//-/ }"
+    for w in $in; do
+        out+="$(tr '[:lower:]' '[:upper:]' <<< "${w:0:1}")${w:1}"
+    done
+    printf '%s' "$out"
+}
+
+_short_name() {
+    local description="$1"
+    local stop='^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$'
+    local clean; clean=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    local -a words=()
+    local word
+    for word in $clean; do
+        [ -z "$word" ] && continue
+        if ! echo "$word" | grep -qiE "$stop"; then
+            [ ${#word} -ge 3 ] && words+=("$word")
+        fi
+    done
+    local max=3 result="" count=0
+    [ ${#words[@]} -eq 4 ] && max=4
+    for word in "${words[@]}"; do
+        [ $count -ge $max ] && break
+        [ -n "$result" ] && result+="-"
+        result+="$word"; count=$((count+1))
+    done
+    [ -z "$result" ] && result="feature"
+    printf '%s' "$result"
+}
+
+
+# ───────────────────────────────── scaffold ────────────────────────────────
+cmd_scaffold() {
+    local feature_dir_arg="" allow_existing=false
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --allow-existing) allow_existing=true; shift ;;
+            --help|-h) echo "scaffold --feature-dir <path> [--allow-existing]"; return 0 ;;
+            *) echo "scaffold: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$feature_dir_arg" ] || { echo "scaffold: --feature-dir is required" >&2; return 1; }
+
+    local repo_root; repo_root=$(get_repo_root)
+    local feature_dir="$feature_dir_arg"
+    [[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
+    local spec_file="$feature_dir/spec.md"
+
+    local dir_existed=false; [ -d "$feature_dir" ] && dir_existed=true
+    if [ "$dir_existed" = true ] && [ "$allow_existing" != true ]; then
+        echo "scaffold: '$feature_dir' already exists (use --allow-existing)" >&2; return 1
+    fi
+    mkdir -p "$feature_dir"
+    local created=true; [ "$dir_existed" = true ] && created=false
+
+    local template="" spec_created=false
+    if [ ! -f "$spec_file" ]; then
+        template=$(resolve_template "spec-template" "$repo_root") || true
+        if [ -n "$template" ] && [ -f "$template" ]; then cp "$template" "$spec_file"; else touch "$spec_file"; fi
+        spec_created=true
+    fi
+    _persist_feature_json "$repo_root" "$feature_dir"
+
+    printf '{"feature_dir":"%s","spec_file":"%s","template":"%s","created":%s,"spec_created":%s}\n' \
+        "$(json_escape "$feature_dir")" "$(json_escape "$spec_file")" \
+        "$(json_escape "$template")" "$created" "$spec_created"
+}
+
+# ─────────────────────────────── resolve-hooks ─────────────────────────────
+# Parse .appweaver/extensions.yml (no PyYAML dependency) and emit the executable
+# hooks for a phase. Governance rules applied here (the agent only dispatches):
+#   - drop hooks with enabled: false (absent enabled => enabled)
+#   - drop hooks with a non-empty condition (leave to HookExecutor)
+#   - normalize command dots to hyphens for the slash form
+cmd_resolve_hooks() {
+    local -a phases=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --phase) phases+=("$2"); shift 2 ;;
+            --help|-h) echo "resolve-hooks --phase <name> [--phase <name> ...]  (multiple phases are merged + deduped by command)"; return 0 ;;
+            *) echo "resolve-hooks: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ ${#phases[@]} -gt 0 ] || { echo "resolve-hooks: at least one --phase is required" >&2; return 1; }
+
+    local repo_root; repo_root=$(get_repo_root)
+    local ext="$repo_root/.appweaver/extensions.yml"
+    local phases_csv; phases_csv=$(IFS=,; echo "${phases[*]}")
+    if [ ! -f "$ext" ]; then
+        printf '{"phases":%s,"hooks":[]}\n' "$(json_str_array "${phases[@]}")"; return 0
+    fi
+
+    if command -v python3 >/dev/null 2>&1; then
+        AW_EXT="$ext" AW_PHASES="$phases_csv" python3 - <<'PY'
+import json, os
+path = os.environ["AW_EXT"]
+phases = [p for p in os.environ["AW_PHASES"].split(",") if p]
+lines = open(path, encoding="utf-8").read().splitlines()
+
+def indent(s): return len(s) - len(s.lstrip(" "))
+
+def parse_phase(phase):
+    # locate "hooks:" then "<phase>:" then its list items (targeted parser for the
+    # known extensions.yml shape; avoids a YAML dependency). List items ("- ") may
+    # sit at the SAME indent as their parent key.
+    i, n = 0, len(lines); hooks = []
+    while i < n:
+        if lines[i].rstrip() == "hooks:":
+            base = indent(lines[i]); i += 1
+            while i < n and (lines[i].strip() == "" or indent(lines[i]) > base):
+                st0 = lines[i].strip()
+                if st0.rstrip(":") == phase and st0.endswith(":") and not st0.startswith("- "):
+                    ph_ind = indent(lines[i]); i += 1; cur = None
+                    while i < n:
+                        l = lines[i]
+                        if l.strip() == "": i += 1; continue
+                        ind = indent(l); st = l.strip()
+                        if ind < ph_ind: break
+                        if ind == ph_ind and st.endswith(":") and not st.startswith("- "): break
+                        if st.startswith("- "):
+                            if cur is not None: hooks.append(cur)
+                            cur = {}; st = st[2:]
+                        if cur is not None and ":" in st and not st.startswith("- "):
+                            k, _, v = st.partition(":"); cur[k.strip()] = v.strip()
+                        i += 1
+                    if cur is not None: hooks.append(cur)
+                    break
+                else: i += 1
+            break
+        i += 1
+    return hooks
+
+def truthy_false(v): return str(v).lower() == "false"
+def empty_cond(v): return v is None or str(v).strip().lower() in ("", "null", "~")
+
+out, seen = [], set()
+for phase in phases:
+    for h in parse_phase(phase):
+        if truthy_false(h.get("enabled", "true")): continue
+        if not empty_cond(h.get("condition")): continue
+        cmd = h.get("command", "")
+        if cmd in seen: continue      # dedupe by command across phases
+        seen.add(cmd)
+        out.append({
+            "extension": h.get("extension", ""),
+            "command": cmd,
+            "slash": "/" + cmd.replace(".", "-") if cmd else "",
+            "optional": str(h.get("optional", "false")).lower() == "true",
+            "description": h.get("description", ""),
+            "prompt": h.get("prompt", ""),
+        })
+print(json.dumps({"phases": phases, "hooks": out}))
+PY
+    else
+        echo "resolve-hooks: python3 unavailable; skipping hook resolution" >&2
+        printf '{"phases":%s,"hooks":[]}\n' "$(json_str_array "${phases[@]}")"
+    fi
+}
+
+# ─────────────────────────────── create-checklist ──────────────────────────
+cmd_create_checklist() {
+    local feature_dir_arg="" feature_name="" kind="master" change_dir_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --feature-name) feature_name="$2"; shift 2 ;;
+            --kind) kind="$2"; shift 2 ;;
+            --change-dir) change_dir_arg="$2"; shift 2 ;;
+            --help|-h) echo "create-checklist --feature-dir <path> [--feature-name <name>] [--kind master|delta] [--change-dir <path>]"; return 0 ;;
+            *) echo "create-checklist: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$feature_dir_arg" ] || { echo "create-checklist: --feature-dir is required" >&2; return 1; }
+    case "$kind" in
+        master|delta) ;;
+        *) echo "create-checklist: --kind must be 'master' or 'delta' (got '$kind')" >&2; return 1 ;;
+    esac
+
+    local repo_root; repo_root=$(get_repo_root)
+    local feature_dir="$feature_dir_arg"
+    [[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
+    [ -n "$feature_name" ] || feature_name="$(basename "$feature_dir")"
+
+    # WHERE the checklist lives and WHAT it grades are decided together here, and both
+    # are reported back, so a caller binds the pair from ONE call and can never point a
+    # checklist at the wrong document. master -> the feature's spec.md; delta -> the
+    # change's delta-spec.md (checklist sits beside it, inside changes/<cr-id>/).
+    local checklist_dir target_file cr_id=""
+    if [ "$kind" = delta ]; then
+        [ -n "$change_dir_arg" ] || { echo "create-checklist: --change-dir is required with --kind delta" >&2; return 1; }
+        local change_dir="$change_dir_arg"
+        [[ "$change_dir" != /* ]] && change_dir="$repo_root/$change_dir"
+        cr_id="$(basename "$change_dir")"
+        checklist_dir="$change_dir/checklists"
+        target_file="$change_dir/delta-spec.md"
+    else
+        checklist_dir="$feature_dir/checklists"
+        target_file="$feature_dir/spec.md"
+    fi
+    local checklist_file="$checklist_dir/requirements.md"
+    mkdir -p "$checklist_dir"
+
+    local created=true; [ -f "$checklist_file" ] && created=false
+    local today; today="$(date +%Y-%m-%d)"
+
+    if [ "$kind" = delta ]; then
+    cat > "$checklist_file" <<EOF
+# Delta-Spec Quality Checklist: $feature_name — $cr_id
+
+**Purpose**: Validate the CHANGE's delta-spec before proceeding to design
+**Created**: $today
+**Change**: [delta-spec.md](../delta-spec.md)
+
+## Content Quality
+
+- [ ] No implementation mechanics (languages, frameworks, code/adapter design; interop obligations named as contracts are fine)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] Change summary states what is changing and why
+
+## Delta Completeness
+
+- [ ] Every item sits under ADDED, MODIFIED or REMOVED (an empty section states None)
+- [ ] MODIFIED items state both sides (was -> now)
+- [ ] New behaviour is a user story (US-n) with priority, Given/When/Then acceptance, and an independent test
+- [ ] New or changed system requirements keep EARS form
+- [ ] Requirements are testable and unambiguous
+- [ ] No [NEEDS CLARIFICATION] markers remain
+
+## Domain Lift (Constraints / Classification / Contracts)
+
+- [ ] Constraint / NFR changes are captured as CN- items, or the section states None
+- [ ] Data sensitivity or exposure changes are captured as DC- items, or the section states None
+- [ ] External interoperability changes are captured as IC- items at contract level, or the section states None
+
+## Experience Lift (UI / UX standards)
+
+- [ ] Experience-standard changes are captured as UX- items, or the section states None
+- [ ] Where UX- deltas exist, each states a project-wide standard checkable on any surface — no screen, page, layout, navigation or component
+- [ ] Where UX- deltas exist, a change to THIS aggregate's own interaction behaviour is an FR- delta, not a UX- one
+- [ ] Where UX- deltas exist, a bound the service must meet stays a CN-, not a UX-
+
+## Merge Readiness
+
+- [ ] Header is complete: aggregate, change type, base version
+- [ ] Impact lists the affected ids (FR / BR / CN / DC / IC / UX / US / SC)
+- [ ] Regression risk names the existing behaviour that must still hold
+- [ ] Scoped to THIS change — the unchanged master is neither restated here nor edited
+
+## Notes
+
+- 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
+EOF
+    else
+    cat > "$checklist_file" <<EOF
+# Specification Quality Checklist: $feature_name
+
+**Purpose**: Validate specification completeness and quality before proceeding to design
+**Created**: $today
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [ ] No implementation mechanics (languages, frameworks, code/adapter design; interop obligations named as contracts are fine)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] All mandatory sections completed
+
+## Requirement Completeness
+
+- [ ] No [NEEDS CLARIFICATION] markers remain
+- [ ] Requirements are testable and unambiguous
+- [ ] Success criteria are measurable
+- [ ] Success criteria are technology-agnostic (no implementation details)
+- [ ] All acceptance scenarios are defined
+- [ ] Edge cases are identified
+- [ ] Scope is clearly bounded
+- [ ] Dependencies and assumptions identified
+
+## Domain Lift (Constraints / Classification / Contracts)
+
+- [ ] Domain-derived constraints are captured in Constraints & NFRs (CN-), or the section states None
+- [ ] Data sensitivity and exposure rules are captured in Data Classification (DC-), or the section states None
+- [ ] External interoperability obligations are captured as Integration Contracts (IC-) at contract level, or the section states None
+
+## Experience Lift (UI / UX standards)
+
+- [ ] Experience Scope states the actors, channels and device / browser / assistive-technology floors, or states None
+- [ ] Project-wide experience standards are captured as UX- items, or the section states None
+- [ ] Where UX- items exist, each is checkable on any surface — no screen, page, layout, navigation or component appears
+- [ ] Where UX- items exist, none of them is a per-feature interaction behaviour — those stay FR-
+- [ ] Where UX- items exist, a bound the SERVICE must meet is a CN-, cross-referenced where the obligation binds both lanes
+
+## Feature Readiness
+
+- [ ] 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
+EOF
+    fi
+
+    printf '{"checklist_file":"%s","kind":"%s","target":"%s","created":%s}\n' \
+        "$(json_escape "$checklist_file")" "$(json_escape "$kind")" \
+        "$(json_escape "$target_file")" "$created"
+}
+
+# ─────────────────────────────── list-domains ──────────────────────────────
+# The selectable projects: immediate subdirs of guardrails/projects/ that carry a rule
+# map. The map is what makes a directory a project, exactly as a *.pack.txt is what makes
+# a foundations/ directory a foundation — without that test any stray sibling would be
+# offered as a governance target. EITHER map qualifies, because onboard writes the domain
+# map several steps before the technical one and a half-built project must stay visible.
+cmd_list_domains() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "list-domains"; return 0 ;;
+            *) echo "list-domains: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local base="$repo_root/guardrails/projects"
+    local -a domains=()
+    if [ -d "$base" ]; then
+        local d
+        for d in "$base"/*/; do
+            [ -d "$d" ] || continue
+            [ -f "$d/tech-rule-bindings.md" ] || [ -f "$d/domain-rule-bindings.md" ] || continue
+            domains+=("$(basename "$d")")
+        done
+    fi
+    printf '{"domains":%s}\n' "$(json_str_array "${domains[@]}")"
+}
+
+# ─────────────────────────────── set-domain ────────────────────────────────
+cmd_set_domain() {
+    local domain=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --domain) domain="$2"; shift 2 ;;
+            --help|-h) echo "set-domain --domain <name>"; return 0 ;;
+            *) echo "set-domain: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$domain" ] || { echo "set-domain: --domain is required" >&2; return 1; }
+
+    local repo_root; repo_root=$(get_repo_root)
+    local map_rel="guardrails/projects/$domain/domain-rule-bindings.md"
+    local map_exists=false
+    [ -f "$repo_root/$map_rel" ] && map_exists=true
+
+    mkdir -p "$repo_root/.appweaver"
+    local dj="$repo_root/.appweaver/domain.json"
+    if command -v jq >/dev/null 2>&1; then
+        jq -cn --arg d "$domain" '{domain:$d}' > "$dj"
+    else
+        printf '{"domain":"%s"}\n' "$(json_escape "$domain")" > "$dj"
+    fi
+
+    printf '{"domain":"%s","map_path":"%s","map_exists":%s,"written":true}\n' \
+        "$(json_escape "$domain")" "$(json_escape "$map_rel")" "$map_exists"
+}
+
+# ────────── stack-list / lane-declare / lane-resolve / lane-probe ──────────
+# The lane model. All four delegate to the shared python core so the bash and
+# powershell twins cannot drift: the JSON contract has one implementation.
+#
+# lane-declare is the SOLE WRITER of .appweaver/stacks.json and has exactly one
+# caller (aw-spec-select-stack). lane-resolve can never write — which is why
+# these are two subcommands rather than one with a mode flag.
+_aw_stack_py() {
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-stack.py"
+    if [ ! -f "$core" ]; then
+        echo "aw-stack: core not found at $core" >&2; return 1
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "aw-stack: python3 is required for the lane model" >&2; return 1
+    fi
+    python3 "$core" --repo "$repo_root" "$@"
+}
+
+# ONE flattened field of a lane kind, empty when none is declared. The shells never
+# parse stacks.json themselves — aw-stack is its one reader — so every command that needs
+# to know something about a lane asks through here instead of assuming `src/` or `dotnet`.
+# Field is the kind_block suffix: root, profile, ecosystem, language, title, build, test,
+# run, migrate.
+_aw_lane_field() {
+    local kind="$1" field="$2"
+    _aw_stack_py resolve --kind "$kind" 2>/dev/null | AW_KEY="${kind}_${field}" python3 -c '
+import json, os, sys
+try:
+    print(json.loads(sys.stdin.readline()).get(os.environ["AW_KEY"]) or "")
+except Exception:
+    print("")
+' 2>/dev/null || echo ""
+}
+
+# The declared SOURCE PATH of a lane kind — the field asked for most often.
+_aw_lane_root() { _aw_lane_field "$1" root; }
+
+# Every ecosystem the declared lanes belong to, one per line, deduped and empty when
+# nothing is declared. This is what keys the stack-partitioned corpora under
+# foundations/<ecosystem>/ — a Java repo has no business being offered a .NET bundle,
+# and the lane model already knows which it is.
+_aw_ecosystems() {
+    _aw_stack_py resolve 2>/dev/null | python3 -c '
+import json, sys
+try:
+    d = json.loads(sys.stdin.readline())
+except Exception:
+    raise SystemExit
+seen = []
+for k in ("backend_ecosystem", "frontend_ecosystem"):
+    v = d.get(k) or ""
+    if v and v not in seen:
+        seen.append(v)
+print("\n".join(seen))
+' 2>/dev/null || true
+}
+
+cmd_stack_list() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --kind) fwd+=("--kind" "$2"); shift 2 ;;
+            --preselect) fwd+=("--preselect" "$2"); shift 2 ;;
+            --include-none) fwd+=("--include-none"); shift ;;
+            --suggest) fwd+=("--suggest"); shift ;;
+            --help|-h) echo "stack-list [--kind backend|frontend|all] [--preselect <text>] [--include-none] [--suggest]"; return 0 ;;
+            *) echo "stack-list: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py list "${fwd[@]}"
+}
+
+cmd_stack_detect() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --kind) fwd+=("--kind" "$2"); shift 2 ;;
+            --exclude-root) fwd+=("--exclude-root" "$2"); shift 2 ;;
+            --help|-h) echo "stack-detect [--kind backend|frontend|all] [--exclude-root <path>]…"; return 0 ;;
+            *) echo "stack-detect: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py detect "${fwd[@]}"
+}
+
+cmd_lane_declare() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            # --source-path is the same field as --root; both spellings reach the core.
+            --profile|--kind|--id|--root|--source-path|--stack|--origin|--build|--test|--run|--prototype-root|--prototype-run)
+                fwd+=("$1" "$2"); shift 2 ;;
+            --no-prototype) fwd+=("--no-prototype"); shift ;;
+            --require-existing-root) fwd+=("--require-existing-root"); shift ;;
+            --help|-h)
+                echo "lane-declare --profile <id|label|none|detected> [--kind backend|frontend] [--id <lane>] [--source-path|--root <path>] [--stack <label>] [--origin declared|reverse-engineered] [--build <cmd>] [--test <cmd>] [--run <cmd>] [--prototype-root <path>] [--prototype-run <cmd>] [--no-prototype] [--require-existing-root]"
+                return 0 ;;
+            *) echo "lane-declare: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py declare "${fwd[@]}"
+}
+
+cmd_lane_resolve() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --kind|--id) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "lane-resolve [--kind backend|frontend] [--id <lane>]"; return 0 ;;
+            *) echo "lane-resolve: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py resolve "${fwd[@]}"
+}
+
+# The gate: is the declaration USABLE for the phase about to run. --require names a
+# lane kind the phase cannot run without and is repeatable; every DECLARED lane is
+# checked for a sound source path whether or not it was required, because a stack
+# named against a directory that is not there is a mistake in every phase.
+# --allow-missing-root is the greenfield state, where select-stack declares a source
+# path before implement creates it.
+cmd_lane_verify() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --require) fwd+=("--require" "$2"); shift 2 ;;
+            # --flag=value: --command carries a phase name that starts with '/'.
+            --command) fwd+=("--command=$2"); shift 2 ;;
+            --allow-missing-root) fwd+=("--allow-missing-root"); shift ;;
+            --help|-h) echo "lane-verify [--require backend|frontend]… [--allow-missing-root] [--command <phase>]"; return 0 ;;
+            *) echo "lane-verify: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py verify "${fwd[@]}"
+}
+
+# Evidence that a lane of this kind exists, from the FILE signals only: a lane in
+# stacks.json, and a stack name appearing in free prose. The authoritative signal
+# — whether the active project's technical map carries `## /aw-spec-<command>` for the
+# lane's phases — is resolve-tech's, and callers OR the two together.
+cmd_lane_probe() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            # --flag=value, not two tokens: --hint carries raw user prose, and a value
+            # that starts with '-' reads as another flag when passed separately.
+            --kind|--hint) fwd+=("$1=$2"); shift 2 ;;
+            --help|-h) echo "lane-probe [--kind backend|frontend] [--hint <text>]"; return 0 ;;
+            *) echo "lane-probe: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py probe "${fwd[@]}"
+}
+
+# ─────────────────────────────── list-features ─────────────────────────────
+# Enumerate the aggregates a user can pick as the active feature. Two sources,
+# MERGED (deduped by feature name, case-insensitive):
+#   1. specs/ sub-folders  — features already scaffolded/adopted (greenfield or
+#      brownfield-post-adopt); annotated with spec + design docs + version.
+#   2. the OKF bundle's Aggregate concepts — the BROWNFIELD FEATURE MAP onboard
+#      reverse-engineers (the discovered aggregates NOT yet under specs/). This is
+#      why select-feature can offer real code features in a brownfield repo before
+#      anything is adopted, instead of an empty specs/ list.
+# On greenfield (no bundle) source 2 is empty → identical to the old specs-only
+# behaviour. `select_options` = merged names + (an injected --preselect that is not
+# yet a feature) + a "create new" sentinel, so select-feature can offer add-new and
+# honour a direct-argument fast path with ONE list.
+cmd_list_features() {
+    local preselect="" bundle=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --preselect) preselect="$2"; shift 2 ;;
+            --bundle)    bundle="$2";    shift 2 ;;
+            --help|-h) echo "list-features [--preselect <name>] [--bundle <dir>]  -> {features[], names[], count, select_options[], sentinel}"; return 0 ;;
+            *) echo "list-features: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    [ -n "$bundle" ] || bundle="knowledge"
+    case "$bundle" in /*) ;; *) bundle="$repo_root/$bundle" ;; esac
+    # Best-effort OKF aggregate list from the shared python core (single source of
+    # truth for OKF parsing; the ps1 twin calls the SAME script). Empty on greenfield.
+    local okf_json="{}" invpy="$SCRIPT_DIR/../python/aw-inventory.py"
+    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'
+import json, os, glob
+base = os.environ["AW_SPECS"]
+pre  = os.environ.get("AW_PRESELECT", "").strip()
+try:
+    okf = json.loads(os.environ.get("AW_OKF", "{}") or "{}")
+except Exception:
+    okf = {}
+sentinel = "+ Create a new feature"
+feats, names = [], []
+seen = set()   # case-insensitive dedup key across both sources
+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
+        ver, active_change = "", ""
+        avf = os.path.join(d, "active_version.json")
+        if os.path.isfile(avf):
+            try:
+                av = json.load(open(avf, encoding="utf-8")) or {}
+                ver = av.get("version", ""); active_change = av.get("active_change", "")
+            except Exception: pass
+        names.append(name); seen.add(name.lower())
+        feats.append({
+            "name": name,
+            "dir": "specs/" + name,
+            "source": "spec",
+            "has_spec": os.path.isfile(os.path.join(d, "spec.md")),
+            # `design*.md`, NOT `design.*.md`: the second dot made this miss the single
+            # `design.md` the framework actually produces (it only matched the retired
+            # design.domain.md / design.technical.md family). Informational count only.
+            "design_docs": len(glob.glob(os.path.join(d, "design*.md"))),
+            "version": ver,
+            "active_change": active_change,
+        })
+# Merge OKF-discovered aggregates NOT already scaffolded under specs/ (a specs/
+# folder is the adopted/created form of the same aggregate — it wins, no dup).
+for agg in (okf.get("aggregates") or []):
+    nm = (agg.get("name") or "").strip()
+    if not nm or nm.lower() in seen:
+        continue
+    names.append(nm); seen.add(nm.lower())
+    feats.append({
+        "name": nm,
+        "dir": "specs/" + nm,          # candidate slice (not yet created)
+        "source": "okf",
+        "has_spec": False,
+        "adopted": False,
+        "concept_path": agg.get("concept_path", ""),
+        "design_docs": 0,
+        "version": "",
+        "active_change": "",
+    })
+opts = list(names)
+# Inject a not-yet-existing --preselect so `preselect_from: USER_INPUT` can
+# create-or-select it without an extra round trip (the direct-arg fast path).
+if pre and pre.lower() not in seen:
+    opts.append(pre)
+opts.append(sentinel)
+print(json.dumps({"features": feats, "names": names, "count": len(names),
+                  "select_options": opts, "sentinel": sentinel}))
+PY
+}
+
+# ─────────────────────────────── set-feature ───────────────────────────────
+# Create-or-select an aggregate under specs/ and persist it as the active feature
+# (.appweaver/feature.json). feature = aggregate: the name is normalized to a
+# PascalCase identifier (e.g. "order management" -> OrderManagement). Idempotent:
+# selecting an existing feature just re-points feature.json; a new one is created.
+cmd_set_feature() {
+    local raw=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature) raw="$2"; shift 2 ;;
+            --help|-h) echo "set-feature --feature <name>   (create-or-select the aggregate under specs/)"; return 0 ;;
+            *) echo "set-feature: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$raw" ] || { echo "set-feature: --feature is required" >&2; return 1; }
+
+    # Normalize to a PascalCase aggregate identifier (feature = aggregate).
+    local cleaned; cleaned=$(echo "$raw" | sed -E 's/[^A-Za-z0-9]+/ /g; s/^ +| +$//g')
+    local feature; feature=$(_pascal "$cleaned")
+    if ! [[ "$feature" =~ ^[A-Za-z][A-Za-z0-9]*$ ]]; then
+        echo "set-feature: '$raw' is not a valid feature name (need a letter-led alphanumeric aggregate, e.g. Order)" >&2
+        return 1
+    fi
+
+    local repo_root; repo_root=$(get_repo_root)
+    local feature_dir_rel="specs/$feature"
+    local feature_dir="$repo_root/$feature_dir_rel"
+    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' \
+        "$(json_escape "$feature")" "$(json_escape "$feature_dir_rel")" \
+        "$(json_escape "$feature_dir_rel/spec.md")" "$existed" "$created" "$spec_exists"
+}
+
+# ═══════════════════════════ active_version.json ════════════════════════════
+# PER-FEATURE state at <feature_dir>/active_version.json:
+#   {feature, version, active_change, updated}
+# Distinct from the GLOBAL .appweaver/feature.json (which only SELECTS the active
+# feature). This is the single source of truth for a feature's version number and
+# its open change — the CR that spans cr-setup (opens) -> cr-archive (closes).
+# "Every applied change bumps" => the close op bumps minor ONLY when a change is
+# open (the initial bootstrap build stays v1.0; it is the baseline, not a change).
+# The open/close OPS are reached solely through cr-setup / cr-archive; the former
+# standalone `version-open` / `version-close` subcommands were unused and removed.
+_resolve_feature_dir() {   # $1 = --feature-dir arg (may be empty), $2 = repo_root; prints ABS dir or fails
+    local arg="$1" repo_root="$2" fd="$1"
+    [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
+    [ -n "$fd" ] || return 1
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    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)
+    AW_FD="$1" AW_OP="$2" AW_CR="${3:-}" AW_FORCE="${4:-}" python3 - <<'PY'
+import json, os, re, datetime, sys
+fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]; cr = os.environ.get("AW_CR", "")
+force = os.environ.get("AW_FORCE", "")
+path = 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 load():
+    if os.path.isfile(path):
+        try: return json.load(open(path, encoding="utf-8")), True
+        except Exception: pass
+    return {"feature": feature, "version": "v1.0", "active_change": "", "updated": now()}, False
+def save(d):
+    d["updated"] = now()
+    open(path, "w", encoding="utf-8").write(json.dumps(d, indent=2) + "\n")
+def bump(v):
+    m = re.match(r'v?(\d+)(?:\.(\d+))?', (v or "v1.0").strip())
+    maj = int(m.group(1)) if m else 1
+    mnr = int(m.group(2)) if (m and m.group(2)) else 0
+    return "v%d.%d" % (maj, mnr + 1)
+
+d, existed = load()
+d.setdefault("feature", feature); d.setdefault("version", "v1.0"); d.setdefault("active_change", "")
+out = {"feature": d["feature"], "version": d["version"], "active_change": d.get("active_change", ""),
+       "exists": existed, "path": "active_version.json", "ok": True}
+if op == "read":
+    pass
+elif op == "init":
+    if not existed: save(d)
+    out["created"] = (not existed)
+elif op == "open":
+    cur = d.get("active_change", "")
+    if cur and cur != cr and force != "1":       # a DIFFERENT change is already open -> refuse
+        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
+elif op == "close":
+    prev = d["version"]; closed = d.get("active_change", "")
+    if closed:                       # a real change was open -> materialized -> bump
+        d["version"] = bump(prev)
+    d["active_change"] = ""; save(d)
+    out["version"] = d["version"]; out["active_change"] = ""
+    out["previous"] = prev; out["closed_change"] = closed
+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
+# finalize-delta (to write the right number into the Change History rows it appends)
+# and close-delta (which actually performs the bump and stamps the two headers), so
+# the two stages can never disagree about the target. Equals `version` when no change
+# is open, mirroring close's "only bump if a change was really open" guard.
+out["next_version"] = bump(out["version"]) if out.get("active_change", "") else out["version"]
+print(json.dumps(out))
+PY
+}
+
+cmd_version_read()  { _version_cmd "read"  "$@"; }
+cmd_version_init()  { _version_cmd "init"  "$@"; }
+_version_cmd() {   # $1 = op (read|init), then --feature-dir arg
+    local op="$1"; shift
+    local fd_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --help|-h) echo "version-$op [--feature-dir <path>]"; return 0 ;;
+            *) echo "version-$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 "version-$op: no feature set and no --feature-dir" >&2; return 1; }
+    _active_version "$fd" "$op"
+}
+
+
+
+# ─────────────────────────────── feature-paths ─────────────────────────────
+cmd_feature_paths() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "feature-paths"; return 0 ;;
+            *) echo "feature-paths: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(read_feature_json_feature_directory "$repo_root")
+    if [ -z "$fd" ]; then
+        echo "feature-paths: no feature set (run /appweaver select-feature first)" >&2
+        return 1
+    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.
+    #
+    # 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 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
+    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s}\n' \
+        "$(json_escape "$feature")" "$(json_escape "$fd")" "$(json_escape "$spec")" "$(json_escape "$design")" \
+        "$(json_escape "$ui_design")" "$spec_exists" "$design_exists" "$ui_design_exists"
+}
+
+# ────────────────────────── checklist-read / -apply ────────────────────────
+# Parse/toggle GitHub task-list checkboxes outside code fences. Python3 does the
+# parsing (robust, fence-aware); toggling changes ONLY the [ ]/[x] marker.
+cmd_checklist_read() {
+    local file=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --file) file="$2"; shift 2 ;;
+            --help|-h) echo "checklist-read --file <path>"; return 0 ;;
+            *) echo "checklist-read: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$file" ] || { echo "checklist-read: --file required" >&2; return 1; }
+    AW_FILE="$file" python3 - <<'PY'
+import json, os
+f = os.environ["AW_FILE"]
+if not os.path.exists(f):
+    print(json.dumps({"exists": False, "total": 0, "checked": 0, "items": []})); raise SystemExit
+items, n, fence = [], 0, False
+for line in open(f, encoding="utf-8").read().splitlines():
+    s = line.strip()
+    if s.startswith("```"): fence = not fence; continue
+    if fence: continue
+    st = line.lstrip()
+    if st[:3] in ("- [",) and len(st) >= 5 and st[3] in " xX" and st[4] == "]":
+        n += 1
+        items.append({"n": n, "checked": st[3] in "xX", "text": st[5:].strip()})
+print(json.dumps({"exists": True, "total": len(items),
+                  "checked": sum(1 for i in items if i["checked"]), "items": items}))
+PY
+}
+
+cmd_checklist_apply() {
+    local file="" results="{}"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --file) file="$2"; shift 2 ;;
+            --results) results="$2"; shift 2 ;;
+            --help|-h) echo "checklist-apply --file <path> --results <json>"; return 0 ;;
+            *) echo "checklist-apply: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$file" ] || { echo "checklist-apply: --file required" >&2; return 1; }
+    AW_FILE="$file" AW_RESULTS="$results" python3 - <<'PY'
+import json, os, re
+f = os.environ["AW_FILE"]
+if not os.path.exists(f):
+    print(json.dumps({"exists": False, "before_checked": 0, "after_checked": 0,
+                      "total": 0, "newly_passing": [], "regressions": []})); raise SystemExit
+try:
+    results = {int(k): bool(v) for k, v in json.loads(os.environ["AW_RESULTS"] or "{}").items()}
+except Exception:
+    results = {}
+lines = open(f, encoding="utf-8").read().splitlines(keepends=True)
+n, fence = 0, False
+before = after = 0
+newly, regress = [], []
+out = []
+for line in lines:
+    s = line.strip()
+    if s.startswith("```"):
+        fence = not fence; out.append(line); continue
+    m = re.match(r'^(\s*- \[)([ xX])(\].*)$', line.rstrip("\n")) if not fence else None
+    if m:
+        n += 1
+        cur = m.group(2) in "xX"
+        before += 1 if cur else 0
+        desired = results.get(n, cur)
+        if desired != cur:
+            if desired: newly.append(n)
+            else: regress.append(n)
+        marker = "x" if desired else " "
+        nl = "\n" if line.endswith("\n") else ""
+        out.append(f"{m.group(1)}{marker}{m.group(3)}{nl}")
+        after += 1 if desired else 0
+    else:
+        out.append(line)
+open(f, "w", encoding="utf-8").write("".join(out))
+print(json.dumps({"exists": True, "before_checked": before, "after_checked": after,
+                  "total": n, "newly_passing": newly, "regressions": regress}))
+PY
+}
+
+
+
+# ─────────────────────────────── detect-project ────────────────────────────
+# Project Structure Gate: is there a scaffolded app (not just framework files)?
+#
+# EVERY ecosystem's manifest is searched to the same depth. A project is where its
+# manifest is, not where the repository root is: a Maven service copied into
+# backend/orderservice/ is as scaffolded as a .sln at the top. Searching *.sln
+# recursively while testing pom.xml and package.json only at the root reported
+# every non-.NET layout that nests its project as no-project-at-all, which reads
+# at the gate as "run /appweaver foundation first" — advice a stack with no
+# foundation bundle cannot take.
+#
+# --root scopes the search to one lane's subtree: the directory the calling phase
+# is about to write into, so the answer is about that lane's project rather than
+# about any project anywhere. It falls back to the whole repository when the
+# subtree holds no manifest of its own, which is the ordinary .NET layout — a
+# lane rooted at src/ under a solution file that sits beside it.
+_project_markers() {
+    local repo_root="$1" start="$2"
+    find "$start" \
+         \( -path "$repo_root/.appweaver" -o -path "$repo_root/guardrails" \
+            -o -path "$repo_root/foundations" -o -path "$repo_root/specs" \
+            -o -path "$repo_root/.git" -o -name node_modules \) -prune -o \
+         \( -name "*.sln" -o -name "*.csproj" -o -name "package.json" \
+            -o -name "pom.xml" -o -name "build.gradle" -o -name "build.gradle.kts" \
+            -o -name "go.mod" -o -name "Cargo.toml" -o -name "pyproject.toml" \) -print 2>/dev/null \
+      | sed "s#^$repo_root/##" | LC_ALL=C sort | head -20
+}
+
+cmd_detect_project() {
+    local scope_root=""
+    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 ;;
+            *) echo "detect-project: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local -a markers=()
+    local scope="repo" start="$repo_root" rel
+    # A lane's source path arrives as the value declare stored, so it may carry a
+    # trailing slash; an option label ("path  — why") never reaches a script argument.
+    rel="${scope_root#./}"; rel="${rel%/}"
+    if [ -n "$rel" ] && [ -d "$repo_root/$rel" ]; then
+        start="$repo_root/$rel"; scope="lane"
+    fi
+    while IFS= read -r m; do [ -n "$m" ] && markers+=("$m"); done < <(_project_markers "$repo_root" "$start")
+    if [ ${#markers[@]} -eq 0 ] && [ "$scope" = "lane" ]; then
+        scope="repo"
+        while IFS= read -r m; do [ -n "$m" ] && markers+=("$m"); done < <(_project_markers "$repo_root" "$repo_root")
+    fi
+    local scaffolded=false
+    [ ${#markers[@]} -gt 0 ] && scaffolded=true
+    printf '{"scaffolded":%s,"markers":%s,"scope":"%s"}\n' "$scaffolded" "$(json_str_array "${markers[@]}")" "$scope"
+}
+
+
+# ───────────────────────── foundation resolution ───────────────────────────
+# Foundations live at foundations/<stack>/<Name>/, grouped by the technology stack
+# they scaffold. Names are unique across stacks, so callers pass a bare <Name> and
+# the lookup searches every stack.
+
+# Echo "<stack>/<Name>" for each foundation directory, one per line. A stack also
+# holds siblings that are not foundations (components/), so carrying a *.pack.txt is
+# what makes a directory one — without that test they surface as bundle-less
+# foundations in every lookup.
+_foundation_dirs() {
+    local repo_root="$1" s d
+    [ -d "$repo_root/foundations" ] || return 0
+    for s in "$repo_root/foundations"/*/; do
+        [ -d "$s" ] || continue
+        for d in "$s"*/; do
+            [ -d "$d" ] || continue
+            ls "$d"*.pack.txt >/dev/null 2>&1 && printf '%s/%s\n' "$(basename "$s")" "$(basename "$d")"
+        done
+    done
+}
+
+# Echo the stack a foundation NAME belongs to; empty when the name is unknown.
+_foundation_stack() {
+    local repo_root="$1" name="$2" rel
+    while IFS= read -r rel; do
+        [ "${rel##*/}" = "$name" ] && { printf '%s' "${rel%%/*}"; return 0; }
+    done < <(_foundation_dirs "$repo_root")
+    return 0
+}
+
+# ──────────────────────────── foundation-list ──────────────────────────────
+# Enumerate available foundations (foundations/<stack>/<Name>/ that carry a real
+# <Name>.pack.txt) so the workflow can let the user PICK one — deterministic, no LLM. An optional
+# --args "<Foundation> <App> [out]" is parsed as a direct-argument fast path:
+# preselect_name is echoed back only when it names a real foundation; preselect_app
+# / out_dir carry any 2nd/3rd tokens through (empty/"." otherwise).
+cmd_foundation_list() {
+    local raw=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --args) raw="$2"; shift 2 ;;
+            --help|-h) echo "foundation-list [--args '<Foundation> <App> [out]']  -> {foundations[], count, preselect_name, preselect_app, out_dir}"; return 0 ;;
+            *) echo "foundation-list: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+
+    # WHICH foundations this repo may be offered. A foundation bundle is a whole
+    # compiling project in one ecosystem's languages and build system, so unpacking
+    # a .NET one into a Spring repo does not produce a scaffold — it produces a
+    # second, foreign project beside the real one. The declared lanes already say
+    # which ecosystems this repo is, so filter to those and let the gate say why
+    # when that leaves nothing. Nothing declared (a bare greenfield repo, before
+    # select-stack) filters nothing: there is no answer yet to filter on.
+    local -a lane_ecos=()
+    local e
+    while IFS= read -r e; do [ -n "$e" ] && lane_ecos+=("$e"); done < <(_aw_ecosystems)
+
+    local -a foundations=() all=() eco_of=()
+    local rel name eco keep
+    while IFS= read -r rel; do
+        name="${rel##*/}"; eco="${rel%%/*}"
+        [ -f "$repo_root/foundations/$rel/$name.pack.txt" ] || continue   # the primary pack (excludes Reference-only dirs)
+        all+=("$name"); eco_of+=("$eco")
+        keep=true
+        if [ ${#lane_ecos[@]} -gt 0 ]; then
+            keep=false
+            for e in "${lane_ecos[@]}"; do [ "$e" = "$eco" ] && keep=true; done
+        fi
+        [ "$keep" = true ] && foundations+=("$name")
+    done < <(_foundation_dirs "$repo_root")
+    # Optional direct-argument fast path: "<FoundationName> <AppName> [OutputDir]".
+    local pre_name="" pre_app="" out_dir="."
+    if [ -n "$raw" ]; then
+        # shellcheck disable=SC2086
+        set -- $raw
+        [ -n "${1:-}" ] && pre_name="$1"; [ -n "${2:-}" ] && pre_app="$2"; [ -n "${3:-}" ] && out_dir="$3"
+    fi
+    # Only preselect a name that actually names an available foundation.
+    local match="" f
+    for f in "${foundations[@]}"; do [ "$f" = "$pre_name" ] && match="$pre_name"; done
+    printf '{"foundations":%s,"count":%s,"all_foundations":%s,"all_count":%s,"ecosystems":%s,"lane_ecosystems":%s,"filtered":%s,"preselect_name":"%s","preselect_app":"%s","out_dir":"%s"}\n' \
+        "$(json_str_array "${foundations[@]}")" "${#foundations[@]}" \
+        "$(json_str_array "${all[@]}")" "${#all[@]}" \
+        "$(json_str_array "${eco_of[@]}")" "$(json_str_array "${lane_ecos[@]}")" \
+        "$([ ${#lane_ecos[@]} -gt 0 ] && echo true || echo false)" \
+        "$(json_escape "$match")" "$(json_escape "$pre_app")" "$(json_escape "$out_dir")"
+}
+
+# ─────────────────────────── foundation-locate ─────────────────────────────
+# Parse/validate args, locate the pack + unpacker, read the pack header (bounded).
+cmd_foundation_locate() {
+    local name="" app="" out="." raw=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --name) name="$2"; shift 2 ;;
+            --app) app="$2"; shift 2 ;;
+            --out) out="$2"; shift 2 ;;
+            --args) raw="$2"; shift 2 ;;
+            --help|-h) echo "foundation-locate (--args '<F> <A> [out]' | --name <F> --app <A> [--out <dir>])"; return 0 ;;
+            *) echo "foundation-locate: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    # positional parse: "<FoundationName> <AppName> [OutputDir]"
+    if [ -n "$raw" ]; then
+        # shellcheck disable=SC2086
+        set -- $raw
+        [ -n "$1" ] && name="$1"; [ -n "$2" ] && app="$2"; [ -n "$3" ] && out="$3"
+    fi
+    local repo_root; repo_root=$(get_repo_root)
+    # available = every foundation dir (_foundation_dirs already requires a *.pack.txt)
+    local -a available=()
+    local rel
+    while IFS= read -r rel; do
+        available+=("${rel##*/}")
+    done < <(_foundation_dirs "$repo_root")
+    _fnd_fail() { printf '{"ok":false,"reason":"%s","available":%s}\n' "$(json_escape "$1")" "$(json_str_array "${available[@]}")"; }
+    if [ -z "$name" ] || [ -z "$app" ]; then
+        _fnd_fail "Usage: /aw-spec-foundation <FoundationName> <AppName> [OutputDirectory]"; return 0
+    fi
+    local stack; stack=$(_foundation_stack "$repo_root" "$name")
+    if [ -z "$stack" ]; then _fnd_fail "Foundation '$name' not found (expected foundations/<stack>/$name/)"; return 0; fi
+    local rel="foundations/$stack/$name"
+    local fdir="$repo_root/$rel"
+    local pack="$fdir/$name.pack.txt"
+    if [ ! -f "$pack" ]; then _fnd_fail "Foundation '$name' has no bundle yet (expected $pack). Build it via the pack scripts in $rel/."; return 0; fi
+    # runner + unpacker
+    local runner unpacker
+    if command -v pwsh >/dev/null 2>&1 && [ -f "$fdir/unpack-foundation.ps1" ]; then
+        runner="pwsh"; unpacker="$rel/unpack-foundation.ps1"
+    elif [ -f "$fdir/unpack-foundation.sh" ]; then
+        runner="sh"; unpacker="$rel/unpack-foundation.sh"
+    else
+        emit_fail "No unpacker found in $rel/ (unpack-foundation.ps1 or .sh)"; return 0
+    fi
+    # bounded header read (never load the pack body)
+    local header sentinel file_count
+    header=$(grep -m 30 '^#' "$pack" 2>/dev/null || true)
+    sentinel=$(printf '%s\n' "$header" | grep -iE 'sentinel' | head -1 | sed -E 's/.*[sS]entinel[^A-Za-z0-9_.]*//; s/[^A-Za-z0-9_.].*$//')
+    file_count=$(printf '%s\n' "$header" | grep -iE 'file' | grep -oE '[0-9]+' | head -1)
+    [ -n "$file_count" ] || file_count="0"
+
+    printf '{"ok":true,"reason":"","name":"%s","stack":"%s","app":"%s","out_dir":"%s","pack_file":"%s","unpacker":"%s","runner":"%s","sentinel":"%s","file_count":%s,"available":%s}\n' \
+        "$(json_escape "$name")" "$(json_escape "$stack")" "$(json_escape "$app")" "$(json_escape "$out")" "$(json_escape "$rel/$name.pack.txt")" \
+        "$(json_escape "$unpacker")" "$runner" "$(json_escape "$sentinel")" "$file_count" "$(json_str_array "${available[@]}")"
+}
+
+# ─────────────────────────── foundation-unpack ─────────────────────────────
+# Run the OS-selected unpacker for the foundation (or reference) pack.
+cmd_foundation_unpack() {
+    local name="" app="" out="." dry=false force="no" reference=false
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --name) name="$2"; shift 2 ;;
+            --app) app="$2"; shift 2 ;;
+            --out) out="$2"; shift 2 ;;
+            --dry-run) dry=true; shift ;;
+            --force) force="$2"; shift 2 ;;
+            --reference) reference=true; shift ;;
+            --help|-h) echo "foundation-unpack --name <F> --app <A> --out <d> [--dry-run] [--force <yes|no>] [--reference]"; return 0 ;;
+            *) echo "foundation-unpack: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$name" ] && [ -n "$app" ] || { echo "foundation-unpack: --name and --app required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local stack; stack=$(_foundation_stack "$repo_root" "$name")
+    local fdir="$repo_root/foundations/$stack/$name"
+    local packbase="$name" script_stem="unpack-foundation"
+    if [ "$reference" = true ]; then packbase="$name.Reference"; script_stem="unpack-reference-foundation"; fi
+    local pack="$fdir/$packbase.pack.txt"
+    if [ ! -f "$pack" ]; then printf '{"ok":false,"mode":"%s","written":0,"has_collisions":false,"stdout":"pack not found: %s"}\n' "$([ "$dry" = true ] && echo dry || echo real)" "$(json_escape "$packbase.pack.txt")"; return 0; fi
+
+    # pick runner
+    local -a cmd=()
+    if command -v pwsh >/dev/null 2>&1 && [ -f "$fdir/$script_stem.ps1" ]; then
+        cmd=(pwsh -NoProfile -File "$fdir/$script_stem.ps1" -PackFile "$pack" -TargetAppName "$app" -OutDir "$out")
+        [ "$dry" = true ] && cmd+=(-DryRun)
+        [ "$force" = "yes" ] && cmd+=(-Force)
+        [ "$reference" = true ] && [ "$force" != "yes" ] && cmd+=(-Force)   # reference always forces
+    elif [ -f "$fdir/$script_stem.sh" ]; then
+        cmd=(bash "$fdir/$script_stem.sh" --pack-file "$pack" --target-app-name "$app" --out-dir "$out")
+        [ "$dry" = true ] && cmd+=(--dry-run)
+        { [ "$force" = "yes" ] || [ "$reference" = true ]; } && cmd+=(--force)
+    else
+        printf '{"ok":false,"mode":"real","written":0,"has_collisions":false,"stdout":"no unpacker script for %s"}\n' "$(json_escape "$name")"; return 0
+    fi
+
+    local outp rc
+    rc=0
+    outp=$("${cmd[@]}" 2>&1) || rc=$?   # set -e safe: a failing unpacker (dry-run collisions) must still yield JSON
+    # unpackers say "Unpacked N file(s) to …" / "DryRun: N file(s) would be written …"
+    local written; written=$(printf '%s' "$outp" | grep -oiE '[0-9]+ +file' | grep -oE '[0-9]+' | head -1)
+    [ -n "$written" ] || written=0
+    local has_coll=false
+    if [ "$dry" = true ] && [ $rc -ne 0 ]; then has_coll=true; fi
+    printf '{"ok":%s,"mode":"%s","written":%s,"has_collisions":%s,"stdout":"%s"}\n' \
+        "$([ $rc -eq 0 ] && echo true || echo false)" "$([ "$dry" = true ] && echo dry || echo real)" \
+        "$written" "$has_coll" "$(json_escape "$(printf '%s' "$outp" | tail -c 800)")"
+}
+
+# ─────────────────────── foundation-stash-dbcontext ────────────────────────
+# Copy the current ApplicationDbContext.cs to a .foundation.bak sibling before a
+# reference unpack overwrites it (so the two can be merged afterward).
+cmd_foundation_stash_dbcontext() {
+    local out="."
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --out) out="$2"; shift 2 ;;
+            --help|-h) echo "foundation-stash-dbcontext --out <dir>"; return 0 ;;
+            *) echo "foundation-stash-dbcontext: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    [[ "$out" != /* ]] && out="$repo_root/$out"
+    local ctx; ctx=$(find "$out/src" -name "ApplicationDbContext.cs" 2>/dev/null | head -1)
+    if [ -z "$ctx" ]; then printf '{"found":false,"dbcontext":"","backup":""}\n'; return 0; fi
+    local bak="$ctx.foundation.bak"
+    cp "$ctx" "$bak"
+    printf '{"found":true,"dbcontext":"%s","backup":"%s"}\n' "$(json_escape "$ctx")" "$(json_escape "$bak")"
+}
+
+# ─────────────────────────── foundation-verify ─────────────────────────────
+# Scan the output tree for leftover sentinel tokens (should be none).
+cmd_foundation_verify() {
+    local out="." sentinel=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --out) out="$2"; shift 2 ;;
+            --sentinel) sentinel="$2"; shift 2 ;;
+            --help|-h) echo "foundation-verify --out <dir> --sentinel <s>"; return 0 ;;
+            *) echo "foundation-verify: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    [[ "$out" != /* ]] && out="$repo_root/$out"
+    local -a residue=()
+    if [ -n "$sentinel" ] && [ -d "$out" ]; then
+        # scan the generated tree only — never the bundle/framework dirs (the
+        # .pack.txt legitimately contains the sentinel).
+        while IFS= read -r m; do [ -n "$m" ] && residue+=("$m"); done < <(
+            grep -rIl --exclude-dir=.git --exclude-dir=guardrails --exclude-dir=foundations --exclude-dir=.appweaver \
+                 --exclude-dir=specs --exclude-dir=node_modules -- "$sentinel" "$out" 2>/dev/null \
+                 | sed "s#^$repo_root/##" | head -50 )
+    fi
+    printf '{"clean":%s,"residue":%s}\n' "$([ ${#residue[@]} -eq 0 ] && echo true || echo false)" "$(json_str_array "${residue[@]}")"
+}
+
+# ─────────────────────────────── setup-constitution ────────────────────────
+# Ensure the split constitution files exist (copy from templates if missing):
+#   .appweaver/memory/constitution.technical.md  (from constitution-technical-template)
+#   .appweaver/memory/constitution.domain.md     (from constitution-domain-template)
+#   .appweaver/memory/constitution.ui.md         (from constitution-ui-template) — ONLY with --ui
+# The composed .appweaver/memory/constitution.md is produced by `compose-constitution`
+# after the halves are authored. Each half is authored + verified independently.
+#
+# The UI half is opt-in because it is the only one whose ABSENCE is meaningful: a
+# backend-only project has no frontend lane and must look exactly as it did before
+# the lane model existed. The other two are always created and left as unauthored
+# templates when unused, which compose-constitution then skips.
+cmd_setup_constitution() {
+    # --ui / --no-technical follow the LANES the project declared. A half is a lane's
+    # standing governance, so a lane the project does not have gets no half — and the
+    # file is not created either, because an empty template left in memory/ is
+    # indistinguishable from a half somebody forgot to author.
+    local want_ui=false want_tech=true
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --ui) want_ui=true; shift ;;
+            --no-technical) want_tech=false; shift ;;
+            # An EMPTY argument is a flag slot the caller left unfilled. The engine
+            # builds a step's `args:` list before it knows which branch it is in, so a
+            # workflow that varies one flag has to choose between duplicating the whole
+            # step and passing "" — and duplicating it is how this call came to recreate
+            # the technical half that the earlier call had just been told to skip.
+            "") shift ;;
+            --help|-h) echo "setup-constitution [--ui] [--no-technical]"; return 0 ;;
+            *) echo "setup-constitution: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    mkdir -p "$repo_root/.appweaver/memory"
+    local tech="$repo_root/.appweaver/memory/constitution.technical.md"
+    local dom="$repo_root/.appweaver/memory/constitution.domain.md"
+    local ui="$repo_root/.appweaver/memory/constitution.ui.md"
+    local tech_created=false dom_created=false ui_created=false ui_path=""
+    if [ "$want_tech" != true ]; then tech=""; fi
+    if [ -n "$tech" ] && [ ! -f "$tech" ]; then
+        local tpl; tpl=$(resolve_template "constitution-technical-template" "$repo_root") || true
+        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$tech"; else touch "$tech"; fi
+        tech_created=true
+    fi
+    if [ ! -f "$dom" ]; then
+        local tpl; tpl=$(resolve_template "constitution-domain-template" "$repo_root") || true
+        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$dom"; else touch "$dom"; fi
+        dom_created=true
+    fi
+    if [ "$want_ui" = true ]; then
+        ui_path="$ui"
+        if [ ! -f "$ui" ]; then
+            local tpl; tpl=$(resolve_template "constitution-ui-template" "$repo_root") || true
+            if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$ui"; else touch "$ui"; fi
+            ui_created=true
+        fi
+    fi
+    printf '{"constitution_technical_file":"%s","constitution_domain_file":"%s","constitution_ui_file":"%s","technical_created":%s,"domain_created":%s,"ui_created":%s}\n' \
+        "$(json_escape "$tech")" "$(json_escape "$dom")" "$(json_escape "$ui_path")" \
+        "$tech_created" "$dom_created" "$ui_created"
+}
+
+# ─────────────────────────────── compose-constitution ──────────────────────
+# Deterministically concatenate the authored halves into the composed
+# .appweaver/memory/constitution.md (human/compat view; NOT loaded by the pipeline
+# phases — they load the halves directly). No model. If a half is absent or still
+# an unauthored template, it is skipped; a technical-only project's composed file
+# mirrors the technical half exactly.
+#
+# Order is technical → domain → ui. The domain half's principles CONTINUE the
+# technical base's roman numerals from wherever that base ended, so those two stay
+# adjacent; the UI half runs a parallel UX-* series and appends without interrupting
+# that run.
+#
+# NUMBERING CHECK. The boundary between the two roman-numeral halves is derived per
+# project — the technical half runs to whatever length its mapped technology base
+# defines — so a base of eighteen principles and a domain half that assumed it could
+# start at XVI would silently produce two Principle XVIs. Composition is the one place
+# both halves are read together, so it is where that is caught. A collision sets
+# numbering_ok=false; the file is still written, because a composed view that shows the
+# clash is more useful for fixing it than no file at all.
+#
+# UNFILLED-PLACEHOLDER TEST. "Still a raw template" is decided by intersecting the
+# half's [TOKEN]s with the TOKENS ITS OWN KIT TEMPLATE DEFINES — never by the shape of
+# the bracket. A constitution is free to write [HIPAA], [ISO_13485] or a [GDPR](url)
+# link; those are project content and match no template token, so they can no longer
+# make a whole ratified half vanish from the composed file.
+cmd_compose_constitution() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "compose-constitution"; return 0 ;;
+            *) echo "compose-constitution: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local tpl_tech tpl_dom tpl_ui
+    tpl_tech=$(resolve_template "constitution-technical-template" "$repo_root") || true
+    tpl_dom=$(resolve_template "constitution-domain-template" "$repo_root") || true
+    tpl_ui=$(resolve_template "constitution-ui-template" "$repo_root") || true
+    AW_MEM="$repo_root/.appweaver/memory" \
+    AW_TPL_TECH="$tpl_tech" AW_TPL_DOM="$tpl_dom" AW_TPL_UI="$tpl_ui" python3 - <<'PY'
+import json, os, re
+
+mem = os.environ["AW_MEM"]
+tech = os.path.join(mem, "constitution.technical.md")
+dom  = os.path.join(mem, "constitution.domain.md")
+ui   = os.path.join(mem, "constitution.ui.md")
+out  = os.path.join(mem, "constitution.md")
+
+include_tech = os.path.exists(tech)
+
+# A project that declared no SERVICE lane authors no technical half, and that is a
+# complete constitution rather than a broken one — a UI-only project's governance is
+# the UI half plus the domain addenda. What is not composable is a project with
+# nothing at all, which means the halves were never authored.
+if not (include_tech or os.path.exists(dom) or os.path.exists(ui)):
+    print(json.dumps({"composed_file": out, "ok": False, "domain_included": False,
+                      "ui_included": False, "technical_included": False,
+                      "numbering_ok": True, "numbering_checked": False,
+                      "issues": ["no constitution half found — run /appweaver constitution"]}))
+    raise SystemExit
+
+TOKEN = re.compile(r"\[([A-Z][A-Z0-9_]*)\]")
+
+def read(p):
+    return open(p, encoding="utf-8").read()
+
+def strip_comments(s):
+    return re.sub(r"<!--.*?-->", "", s, flags=re.S)
+
+def token_family(tokens):
+    # The template's numbered slots are a series the author is told to extend, so
+    # PRINCIPLE_6_NAME is as much an unfilled slot as PRINCIPLE_1_NAME even though the
+    # template only shows five. Digit runs generalise; nothing else does, which is what
+    # keeps a bracketed regulation code out of the family.
+    return {re.compile(r"\A" + re.sub(r"\d+", r"\\d+", re.escape(t)) + r"\Z")
+            for t in tokens if re.search(r"\d", t)}
+
+def template_tokens(env):
+    # The kit template's own token vocabulary. None = template unresolvable.
+    p = os.environ.get(env, "")
+    if not p or not os.path.exists(p):
+        return None
+    return set(TOKEN.findall(read(p)))
+
+def unfilled(found, tokens):
+    fam = token_family(tokens)
+    return sorted({t for t in found
+                   if t in tokens or any(rx.match(t) for rx in fam)})
+
+def authored(p, env):
+    # An unused half stays a raw template. Comments are stripped first so a Sync
+    # Impact Report that NAMES the placeholders it filled ("Removed: [PROJECT_NAME]")
+    # cannot be mistaken for the placeholders themselves.
+    if not (os.path.exists(p) and os.path.getsize(p) > 0):
+        return False
+    tokens = template_tokens(env)
+    if tokens is None:
+        return True     # no template to compare against: never drop a half on a guess
+    return not unfilled(set(TOKEN.findall(strip_comments(read(p)))), tokens)
+
+include_domain = authored(dom, "AW_TPL_DOM")
+include_ui = authored(ui, "AW_TPL_UI")
+
+with open(out, "w", encoding="utf-8") as fh:
+    fh.write("<!-- COMPOSED — generated by `aw-spec-actions compose-constitution`. Do not edit here.\n")
+    fh.write("     Source of truth: the constitution halves — technical + domain + ui (edit those).\n")
+    fh.write("     Pipeline phases load the halves directly; this composed view is for humans/compat. -->\n\n")
+    if include_tech:
+        fh.write(read(tech))
+    if include_domain:
+        fh.write("\n\n---\n\n"); fh.write(read(dom))
+    if include_ui:
+        fh.write("\n\n---\n\n"); fh.write(read(ui))
+
+# ── principle numbering ────────────────────────────────────────────────────
+VALUES = [(1000,"M"),(900,"CM"),(500,"D"),(400,"CD"),(100,"C"),(90,"XC"),
+          (50,"L"),(40,"XL"),(10,"X"),(9,"IX"),(5,"V"),(4,"IV"),(1,"I")]
+
+def to_int(s):
+    total, i = 0, 0
+    for val, sym in VALUES:
+        while s[i:i+len(sym)] == sym:
+            total += val; i += len(sym)
+    return total if i == len(s) else None
+
+def to_roman(n):
+    out_ = ""
+    for val, sym in VALUES:
+        while n >= val:
+            out_ += sym; n -= val
+    return out_
+
+# A principle heading opens with its numeral: "### VII — Name" or "### VII. Name".
+# UX-* is a PARALLEL series belonging to the frontend lane and is deliberately not
+# part of this run, so it is skipped rather than checked against it.
+HEAD = re.compile(r"^#{2,4}\s+(UX-)?([IVXLCDM]+)\s*[—–\-.:)]", re.M)
+
+def principles(path):
+    found = []
+    if not os.path.exists(path):
+        return found
+    body = re.sub(r"<!--.*?-->", "", read(path), flags=re.S)
+    for prefix, roman in HEAD.findall(body):
+        if prefix:            # UX- series — parallel, not this sequence
+            continue
+        n = to_int(roman)
+        # Round-trip + a sane ceiling keep ordinary words made of roman letters
+        # (and stray four-digit numerals) out of the sequence.
+        if n and n <= 100 and to_roman(n) == roman:
+            found.append((n, roman))
+    return found
+
+tech_p = principles(tech)
+dom_p = principles(dom) if include_domain else []
+
+issues, numbering_ok = [], True
+
+# The cross-half check can only run on halves whose principles it can actually read.
+# A half numbered some other way (1., 2. / P-01) parses to nothing, and silence there
+# would look identical to a clean result — so say so instead of reporting all-clear.
+NUMBERING_FORM = ("principles must be headed '### I — Title' or '### I. Title' "
+                  "(the UI half runs its own UX-I, UX-II, … series)")
+numbering_checked = True
+if not include_tech:
+    # No service lane, so no technical half and no boundary to check: the domain
+    # half opens the roman-numeral sequence at I instead of continuing one. Not an
+    # issue, and not a check that silently passed — it is a check with no subject.
+    numbering_checked = False
+elif not tech_p:
+    numbering_ok = False
+    numbering_checked = False
+    issues.append("no roman-numeral principle headings found in the technical half, so "
+                  "numbering could not be verified — " + NUMBERING_FORM)
+if include_domain and not dom_p:
+    numbering_ok = False
+    numbering_checked = False
+    issues.append("no roman-numeral principle headings found in the domain half, so "
+                  "numbering could not be verified — " + NUMBERING_FORM)
+
+def dupes_within(items, label):
+    global numbering_ok
+    seen, dup = set(), []
+    for n, roman in items:
+        if n in seen and roman not in dup:
+            dup.append(roman)
+        seen.add(n)
+    if dup:
+        numbering_ok = False
+        issues.append("%s half reuses principle number(s): %s" % (label, ", ".join(dup)))
+
+dupes_within(tech_p, "technical")
+dupes_within(dom_p, "domain")
+
+if tech_p and dom_p:
+    overlap = sorted({n for n, _ in tech_p} & {n for n, _ in dom_p})
+    if overlap:
+        numbering_ok = False
+        issues.append(
+            "principle number(s) %s appear in BOTH the technical and domain halves — "
+            "the domain half must resume from the number after the technical half's "
+            "last principle (%s), not from a fixed value"
+            % (", ".join(to_roman(n) for n in overlap), to_roman(max(n for n, _ in tech_p))))
+    else:
+        last_tech = max(n for n, _ in tech_p)
+        first_dom = min(n for n, _ in dom_p)
+        if first_dom != last_tech + 1:
+            numbering_ok = False
+            issues.append(
+                "domain half starts at %s but the technical half ends at %s — numbering "
+                "must run unbroken across the two halves (expected %s)"
+                % (to_roman(first_dom), to_roman(last_tech), to_roman(last_tech + 1)))
+
+print(json.dumps({"composed_file": out, "ok": numbering_ok,
+                  "technical_included": include_tech,
+                  "domain_included": include_domain, "ui_included": include_ui,
+                  "numbering_ok": numbering_ok, "numbering_checked": numbering_checked,
+                  "issues": issues,
+                  "technical_last": (to_roman(max(n for n, _ in tech_p)) if tech_p else None),
+                  "domain_first": (to_roman(min(n for n, _ in dom_p)) if dom_p else None)}))
+PY
+}
+
+# ─────────────────────────── constitution-verify ───────────────────────────
+# Deterministic lint of a generated constitution (NO LLM): unfilled template
+# placeholders, body-vs-Sync-Impact-Report version agreement, and non-ISO dates.
+# Consumed by the constitution skill's bounded self-correction loop. ok=false ⇒ the
+# loop asks the model to patch.
+#
+# A placeholder is a token THE KIT TEMPLATE ACTUALLY DEFINES, resolved from the half's
+# own template (override/preset/extension/core, same order as setup-constitution) and
+# intersected with the file. Bracket SHAPE is not evidence: [HIPAA], [ISO_13485] and
+# [GDPR](url) are ordinary constitution content in a regulated domain and must never be
+# reported as unfilled slots. --template overrides the name derived from the filename.
+cmd_constitution_verify() {
+    local file="" template=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --file) file="$2"; shift 2 ;;
+            --template) template="$2"; shift 2 ;;
+            --help|-h) echo "constitution-verify --file <path> [--template <name>]"; return 0 ;;
+            *) echo "constitution-verify: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$file" ] || { echo "constitution-verify: --file required" >&2; return 1; }
+    if [ -z "$template" ]; then
+        case "$(basename "$file")" in
+            constitution.technical.md) template="constitution-technical-template" ;;
+            constitution.domain.md)    template="constitution-domain-template" ;;
+            constitution.ui.md)        template="constitution-ui-template" ;;
+        esac
+    fi
+    local repo_root; repo_root=$(get_repo_root)
+    local tpl_path=""
+    [ -n "$template" ] && { tpl_path=$(resolve_template "$template" "$repo_root") || true; }
+    AW_FILE="$file" AW_TPL="$tpl_path" python3 - <<'PY'
+import json, os, re
+f = os.environ["AW_FILE"]
+if not os.path.exists(f):
+    print(json.dumps({"ok": False, "exists": False,
+                      "issues": ["constitution file not found"], "placeholders": [],
+                      "version_body": None, "version_report": None,
+                      "version_match": None, "bad_dates": []})); raise SystemExit
+text = open(f, encoding="utf-8").read()
+# Strip HTML comments (template guidance + the Sync Impact Report) so they do not
+# trip the body scan; keep the first block as the report for the version check.
+m = re.search(r"<!--.*?-->", text, re.S)
+report = m.group(0) if m else ""
+body = re.sub(r"<!--.*?-->", "", text, flags=re.S)
+# 1. Unfilled slots = the file's [TOKEN]s ∩ the template's own token vocabulary.
+TOKEN = re.compile(r"\[([A-Z][A-Z0-9_]*)\]")
+tpl = os.environ.get("AW_TPL", "")
+template_missing = not (tpl and os.path.exists(tpl))
+if template_missing:
+    placeholders = []
+else:
+    known = set(TOKEN.findall(open(tpl, encoding="utf-8").read()))
+    # Numbered slots generalise — the author is told to extend the series, so an
+    # unfilled PRINCIPLE_6_NAME counts even though the template only shows five.
+    family = {re.compile(r"\A" + re.sub(r"\d+", r"\\d+", re.escape(t)) + r"\Z")
+              for t in known if re.search(r"\d", t)}
+    placeholders = sorted({t for t in TOKEN.findall(body)
+                           if t in known or any(rx.match(t) for rx in family)})
+# 2. Version: the document's own labelled version line vs the report's "new" version.
+#    Anchored to lines that OPEN with the label, so an "OpenAPI version 3.1.0" inside a
+#    principle cannot be mistaken for the constitution's version. The last such line
+#    wins because the templates carry the version in a footer.
+VERSION_LINE = re.compile(r"^[\s>*_#-]*version\b", re.I)
+def labeled(s, last_on_line=False):
+    vals = []
+    for line in s.splitlines():
+        if VERSION_LINE.match(line):
+            sem = re.findall(r"\d+\.\d+\.\d+", line)
+            if sem:
+                vals.append(sem[-1] if last_on_line else sem[0])
+    return vals[-1] if vals else None
+version_body = labeled(body)
+arrow = re.search(r"(\d+\.\d+\.\d+)\s*(?:->|→|=>)\s*(\d+\.\d+\.\d+)", report)
+# On the report line the LAST semver is the new version — which also survives an
+# "old → new" whose arrow was mangled by an encoding round-trip.
+version_report = arrow.group(2) if arrow else labeled(report, last_on_line=True)
+version_match = (version_body == version_report) if (version_body and version_report) else None
+# 3. Obviously non-ISO dates on ratification/amended/date lines (slash forms,
+#    DD-MM-YYYY, US textual). ISO YYYY-MM-DD never matches these patterns.
+bad = []
+for line in body.splitlines():
+    if re.search(r"(?i)ratif|amend|\bdate\b", line):
+        bad += re.findall(r"\b\d{1,2}/\d{1,2}/\d{2,4}\b", line)
+        bad += re.findall(r"\b\d{1,2}-\d{1,2}-\d{4}\b", line)
+        bad += re.findall(r"\b(?:January|February|March|April|May|June|July|August|"
+                          r"September|October|November|December)\s+\d{1,2},?\s+\d{4}\b", line)
+bad = sorted(set(bad))
+issues = []
+if placeholders:
+    issues.append("%d unfilled placeholder(s): %s" % (len(placeholders), ", ".join(placeholders)))
+if template_missing:
+    # Reported, not failed: a missing kit template is an install problem, and blocking
+    # the authoring loop over it would help nobody.
+    issues.append("placeholder check skipped — no kit template resolved for this half")
+if version_match is False:
+    issues.append("version mismatch: body %s vs Sync Impact Report %s" % (version_body, version_report))
+if bad:
+    issues.append("non-ISO date(s) (use YYYY-MM-DD): %s" % ", ".join(bad))
+ok = (not placeholders) and (version_match is not False) and (not bad)
+print(json.dumps({"ok": ok, "exists": True, "issues": issues,
+                  "placeholders": placeholders, "placeholder_check": not template_missing,
+                  "version_body": version_body,
+                  "version_report": version_report, "version_match": version_match,
+                  "bad_dates": bad}))
+PY
+}
+
+# ────────────────────────── agent-context-update ───────────────────────────
+# Run the agent-context extension's updater (refreshes the managed AW-Spec block).
+cmd_agent_context_update() {
+    local plan=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --plan) plan="$2"; shift 2 ;;
+            --help|-h) echo "agent-context-update [--plan <path>]"; return 0 ;;
+            *) echo "agent-context-update: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local script="$repo_root/.appweaver/extensions/agent-context/scripts/bash/update-agent-context.sh"
+    if [ ! -f "$script" ]; then
+        printf '{"ok":true,"ran":false,"message":"agent-context extension not installed; nothing to do"}\n'; return 0
+    fi
+    local out rc
+    if [ -n "$plan" ]; then out=$(bash "$script" "$plan" 2>&1); else out=$(bash "$script" 2>&1); fi
+    rc=$?
+    printf '{"ok":%s,"ran":true,"message":"%s"}\n' \
+        "$([ $rc -eq 0 ] && echo true || echo false)" "$(json_escape "$(printf '%s' "$out" | tail -c 400)")"
+}
+
+
+
+# ─────────────────────────────── list-components ───────────────────────────
+# Immediate subdirs of foundations/<ecosystem>/components/ that contain an integration.md
+# runbook, for the ecosystem the BACKEND lane declares. Components are wired into a host
+# project by editing its build files and its startup registration, so a component only
+# exists for the ecosystem whose build files and startup it knows how to edit — the
+# catalogue is per-ecosystem for the same reason the foundations are.
+cmd_list_components() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "list-components  -> {components[], ecosystem, dir}"; return 0 ;;
+            *) echo "list-components: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local eco; eco=$(_aw_lane_field backend ecosystem)
+    # No backend lane yet: `dotnet` is the only ecosystem that ships components, so it is
+    # what an undeclared repo would have been shown before the lane model and stays the
+    # answer until select-stack says otherwise.
+    [ -z "$eco" ] && eco="dotnet"
+    local base="$repo_root/foundations/$eco/components"
+    local -a comps=()
+    if [ -d "$base" ]; then
+        local d
+        for d in "$base"/*/; do
+            [ -d "$d" ] || continue
+            [ -f "$d/integration.md" ] && comps+=("$(basename "$d")")
+        done
+    fi
+    printf '{"components":%s,"ecosystem":"%s","dir":"foundations/%s/components"}\n' \
+        "$(json_str_array "${comps[@]}")" "$(json_escape "$eco")" "$(json_escape "$eco")"
+}
+
+# ─────────────────────────────── find-host-project ─────────────────────────
+# Locate the .NET host/startup project by finding Program.cs (never assume a name).
+#
+# DELIBERATELY .NET-ONLY, and it reports which stack it looked at so a caller can say
+# so. `Program.cs` is not a cross-stack concept: a Spring lane's entry point is an
+# @SpringBootApplication class, an Express lane's is whatever `main` in package.json
+# names, and neither has the .csproj this returns. Callers that need a LAUNCH COMMAND
+# ask the lane instead (its declared `run`); this exists for the two callers that need
+# the .NET host DIRECTORY — add-component, which edits its registration, and run, which
+# names it for information. found:false on a non-.NET lane is the correct answer, and
+# `ecosystem` is what lets the message say "this is a java lane" instead of "no project".
+cmd_find_host_project() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "find-host-project"; return 0 ;;
+            *) echo "find-host-project: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local prog
+    # WHERE the host lives. The service lane's declared source path when there is one,
+    # `src/` when there is not — the same question run-migrate asks, and the same answer.
+    # A repo whose service sits in `backend/` or `Legacy/App/` is searched where its code
+    # actually is instead of being reported as having no host project at all.
+    local svc_root; svc_root=$(_aw_lane_root backend)
+    [ -z "$svc_root" ] && svc_root="src"
+    local eco; eco=$(_aw_lane_field backend ecosystem)
+    prog=$(find "$repo_root/${svc_root%/}" -name "Program.cs" 2>/dev/null | head -1)
+    [ -z "$prog" ] && prog=$(find "$repo_root" \( -path "$repo_root/.appweaver" -o -path "$repo_root/guardrails" -o -path "$repo_root/foundations" -o -path "$repo_root/specs" -o -path "$repo_root/.git" -o -name obj -o -name bin \) -prune -o -name "Program.cs" -print 2>/dev/null | head -1)
+    if [ -z "$prog" ]; then
+        printf '{"found":false,"program_cs":"","project_dir":"","csproj":"","ecosystem":"%s","searched":"%s"}\n' \
+            "$(json_escape "$eco")" "$(json_escape "${svc_root%/}")"
+        return 0
+    fi
+    local pdir; pdir=$(dirname "$prog")
+    local csproj; csproj=$(find "$pdir" -maxdepth 1 -name "*.csproj" 2>/dev/null | head -1)
+    printf '{"found":true,"program_cs":"%s","project_dir":"%s","csproj":"%s","ecosystem":"%s","searched":"%s"}\n' \
+        "$(json_escape "$prog")" "$(json_escape "$pdir")" "$(json_escape "$csproj")" \
+        "$(json_escape "$eco")" "$(json_escape "${svc_root%/}")"
+}
+
+# ─────────────────────────────── component-catalog ──────────────────────────
+# Deterministic parse of a component's integration.md "Implementation catalog
+# (selection list)" markdown table (NO LLM). Replaces the extract_catalog llm_query.
+# Returns {integrable, impl_keys[], implementations[{key,desc}]}.
+#
+# Delegates to the shared python core so the bash and powershell twins cannot drift:
+# the parse and the JSON contract have one implementation.
+cmd_component_catalog() {
+    local file=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --file) file="$2"; shift 2 ;;
+            --help|-h) echo "component-catalog --file <integration.md>"; return 0 ;;
+            *) echo "component-catalog: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$file" ] || { echo "component-catalog: --file required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-component-catalog.py"
+    if [ ! -f "$core" ]; then
+        echo "component-catalog: core not found at $core" >&2; return 1
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "component-catalog: python3 is required to parse the catalog" >&2; return 1
+    fi
+    python3 "$core" --repo "$repo_root" --file "$file"
+}
+
+# ─────────────────────────────── component-verify ───────────────────────────
+# Post-wiring verification (NO LLM decision): (1) `dotnet build` the host project
+# (graceful skip if the SDK is absent); (2) R0.2a dual-registration guard — when the
+# host has BOTH AddInfrastructure and AddAspireInfrastructure, assert `--marker`
+# appears in both. Returns {ok, ran, build_ok, errors[], dual_registration_ok,
+# fix_target, fix_reason, can_fix} for a bounded fix loop.
+cmd_component_verify() {
+    local host_dir="" host_csproj="" marker=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --host-dir) host_dir="$2"; shift 2 ;;
+            --host-csproj) host_csproj="$2"; shift 2 ;;
+            --marker) marker="$2"; shift 2 ;;
+            --help|-h) echo "component-verify --host-dir <dir> [--host-csproj <path>] [--marker <token>]"; return 0 ;;
+            *) echo "component-verify: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    AW_REPO="$repo_root" AW_HOST_DIR="$host_dir" AW_HOST_CSPROJ="$host_csproj" AW_MARKER="$marker" python3 - <<'PY'
+import json, os, re, shutil, subprocess
+repo   = os.environ.get("AW_REPO", "")
+hostd  = os.environ.get("AW_HOST_DIR", "")
+csproj = os.environ.get("AW_HOST_CSPROJ", "")
+marker = os.environ.get("AW_MARKER", "").strip()
+def relp(p):
+    try: return os.path.relpath(p, repo).replace("\\", "/") if (repo and p) else p
+    except Exception: return p
+# --- (1) build ---
+ran, build_ok, errors, primary = False, True, [], ""
+if shutil.which("dotnet"):
+    target = csproj if csproj else hostd
+    if target and os.path.exists(target):
+        ran = True
+        proc = subprocess.run(["dotnet", "build", target, "-nologo"],
+                              capture_output=True, text=True)
+        seen = set()
+        for line in (proc.stdout + "\n" + proc.stderr).splitlines():
+            if re.search(r':\s*error\s', line):
+                t = line.strip()
+                if t not in seen:
+                    seen.add(t); errors.append(t)
+        errors = errors[:20]
+        build_ok = (proc.returncode == 0)
+        if not build_ok and errors:
+            m = re.match(r'^(.*?)\(\d+,\d+\)', errors[0])
+            if m: primary = relp(m.group(1).strip())
+        if not build_ok and not primary and csproj:
+            primary = relp(csproj)
+# --- (2) R0.2a dual-registration guard ---
+def defining_files(method):
+    root = hostd if (hostd and os.path.isdir(hostd)) else repo
+    hits = []
+    if not root: return hits
+    pat = re.compile(r'\b' + re.escape(method) + r'\s*\(')
+    for dp, dns, fns in os.walk(root):
+        dns[:] = [d for d in dns if d not in ("bin", "obj", ".git")]
+        for fn in fns:
+            if fn.endswith(".cs"):
+                fp = os.path.join(dp, fn)
+                try: txt = open(fp, encoding="utf-8", errors="ignore").read()
+                except Exception: continue
+                if pat.search(txt): hits.append((fp, txt))
+    return hits
+infra, aspire = defining_files("AddInfrastructure"), defining_files("AddAspireInfrastructure")
+dual_app = bool(infra) and bool(aspire)
+dual_ok, dual_note, dual_fix = True, "", ""
+def pick_fix(hits):
+    non_prog = [fp for fp, _ in hits if os.path.basename(fp) != "Program.cs"]
+    if non_prog: return relp(non_prog[0])
+    return relp(hits[0][0]) if hits else ""
+if not dual_app:
+    dual_note = "single registration path (R0.2) — dual-registration check N/A"
+elif not marker:
+    dual_note = "both AddInfrastructure and AddAspireInfrastructure exist; no marker provided to verify the component is in both"
+else:
+    in_infra  = any(marker in txt for _, txt in infra)
+    in_aspire = any(marker in txt for _, txt in aspire)
+    dual_ok = in_infra and in_aspire
+    if not dual_ok:
+        missing  = "AddInfrastructure" if not in_infra else "AddAspireInfrastructure"
+        dual_fix = pick_fix(infra if not in_infra else aspire)
+        dual_note = "marker '%s' missing from %s (R0.2a: register in BOTH paths)" % (marker, missing)
+    else:
+        dual_note = "marker '%s' present in both registration paths" % marker
+ok = build_ok and dual_ok
+fix_target, fix_reason = "", ""
+if not build_ok:
+    fix_target = primary or (relp(csproj) if csproj else "")
+    fix_reason = "build failed: " + " | ".join(errors[:5])
+elif not dual_ok:
+    fix_target, fix_reason = dual_fix, dual_note
+print(json.dumps({"ok": ok, "ran": ran, "build_ok": build_ok, "errors": errors,
+                  "primary_error_file": primary, "dual_applicable": dual_app,
+                  "dual_registration_ok": dual_ok, "dual_note": dual_note,
+                  "dual_fix_file": dual_fix, "fix_target": fix_target,
+                  "fix_reason": fix_reason, "can_fix": bool(fix_target)}))
+PY
+}
+
+# ─────────────────────────────────── main ──────────────────────────────────
+sub="${1:-}"; shift || true
+# ──────────────────────────────── design-scaffold ──────────────────────────
+# The spec-anchored Design phase: ONE high-level design doc per feature
+# (design.md) — a tech-agnostic HLD that `implement` GENERATES code from (not a
+# deterministic extract). See .appweaver/DESIGN-FORMAT.md + design-template.md.
+#
+# The former path-tagged helpers (design-extract / -reconcile / -paths) are GONE.
+# They belonged to a retired four-document model in which design.{domain,application,
+# api,infra}.md carried the source inside ```lang path=… fences. Nothing emits that
+# fence any more, and their glob (`design.*.md`) could not match a single `design.md`
+# even if something did — so all three had been returning nothing, silently, at exit 0.
+# The question they answered ("which files is this slice made of") is now answered by
+# the OKF concept: `aw-xref concept-paths` to read, `concept-upsert --merge` to write.
+
+# Copy the single HLD design template into the feature dir as design.md (idempotent).
+cmd_design_scaffold() {
+    local feature_dir_arg="" template_arg="" lane_arg="service"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            # --lane service|ui: WHOSE design this is. It selects a coherent
+            # (template, document) PAIR rather than two independent flags — service
+            # scaffolds design-template into design.md, ui scaffolds
+            # ui-design-template into design.ui.md — so no caller can write the
+            # service template under the UI lane's filename. Default `service`
+            # leaves every existing caller byte-identical.
+            --lane) lane_arg="$2"; shift 2 ;;
+            # --template <name>: override the TEMPLATE half of that pair (the document
+            # 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.
+            --template) template_arg="$2"; shift 2 ;;
+            --help|-h) echo "design-scaffold --feature-dir <path> [--lane service|ui] [--template <name>]"; return 0 ;;
+            *) echo "design-scaffold: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local doc_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" ;;
+        *) echo "design-scaffold: unknown --lane '$lane_arg' (service|ui)" >&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 "design-scaffold: no feature set (run /appweaver select-feature first) and no --feature-dir" >&2; return 1; }
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    mkdir -p "$fd"
+
+    local target="$fd/$doc_name" created="false" tpl
+    if [ -f "$target" ]; then
+        created="false"
+    else
+        tpl=$(resolve_template "$template_arg" "$repo_root") || true
+        if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$target"; else touch "$target"; fi
+        created="true"
+    fi
+    # override_active: is a PROJECT-level override installed for this template name?
+    # Computed ALWAYS (independent of the idempotent scaffold skip above) so it is a
+    # stable signal on both the bootstrap AND delta paths. In the brownfield-dev flow,
+    # /appweaver onboard GENERATES the code-derived `design-template` override — so
+    # override_active=true means the forward `design` phase should author with the
+    # (code-derived) as-built structure, not the greenfield four-layer layout.
+    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,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+        "$(json_escape "$fd")" "$(json_escape "$target")" "$(json_escape "$lane_arg")" "$created" "$override_active" \
+        "$(json_escape "$template_arg")" "$(json_escape "${template_source:-}")"
+}
+
+# ─────────────────────── build / test / migrate / deploy ────────────────────
+# Detect the project's toolchain, run the phase command, and report structured
+# status. Tolerant: an unrecognized stack is a no-op pass (wire a hook instead).
+# The FIX is an LLM step in the workflow; these only run + report.
+
+# Is a lane declared in .appweaver/stacks.json? The question every shell-out step asks
+# before it starts sniffing. Prints "true"/"" so a caller can test it directly.
+_aw_lanes_declared() {
+    _aw_stack_py resolve 2>/dev/null | python3 -c '
+import json, sys
+try:
+    print("true" if json.loads(sys.stdin.readline()).get("lanes") else "")
+except Exception:
+    print("")
+' 2>/dev/null || echo ""
+}
+
+cmd_build_compile() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) shift 2 ;;
+            --help|-h) echo "build-compile [--feature-dir <path>]"; return 0 ;;
+            *) echo "build-compile: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+
+    # A DECLARED lane model is the answer, and it is a better answer than the
+    # ladder below in exactly the case that matters: a repo with two lanes. The
+    # sniffer takes the first toolchain it finds and silently never builds the
+    # second, which reports green for a frontend that was never compiled.
+    if [ -n "$(_aw_lanes_declared)" ]; then
+        _aw_stack_py run-phase --phase build
+        return $?
+    fi
+
+    # No declaration: the historic first-match-wins ladder, unchanged. A project
+    # that never ran select-stack behaves exactly as it did before the lane model.
+    local repo_root; repo_root=$(get_repo_root)
+    local tool="none" ran=false ok=true cmd="" log; log=$(mktemp)
+    if ls "$repo_root"/*.sln >/dev/null 2>&1 || find "$repo_root/src" -maxdepth 4 -name "*.csproj" 2>/dev/null | grep -q .; then
+        tool="dotnet"
+        if command -v dotnet >/dev/null 2>&1; then
+            cmd="dotnet build --nologo"; ran=true
+            if ( cd "$repo_root" && dotnet build --nologo ) >"$log" 2>&1; then ok=true; else ok=false; fi
+        else ok=false; fi
+    elif [ -f "$repo_root/package.json" ] && command -v npm >/dev/null 2>&1; then
+        tool="npm"; cmd="npm run build --if-present"; ran=true
+        if ( cd "$repo_root" && npm run build --if-present ) >"$log" 2>&1; then ok=true; else ok=false; fi
+    else
+        tool="none"; ran=false; ok=true
+    fi
+    local t; t=$(tail -c 1400 "$log" 2>/dev/null || true); rm -f "$log"
+    printf '{"ok":%s,"tool":"%s","ran":%s,"cmd":"%s","log_tail":"%s"}\n' \
+        "$ok" "$(json_escape "$tool")" "$ran" "$(json_escape "$cmd")" "$(json_escape "$t")"
+}
+
+cmd_test_run() {
+    # --scope repo  (default): run the whole suite — the historic behaviour, every
+    #               existing caller is unaffected.
+    # --scope slice          : run ONLY the tests whose FullyQualifiedName contains the
+    #               feature's aggregate name (feature-dir basename) plus any --also
+    #               referrer names — the per-feature integrity scope. .NET only; npm/none
+    #               ignore it and run the full suite.
+    local feature_dir="" scope="repo" also=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir="$2"; shift 2 ;;
+            --scope)       scope="$2"; shift 2 ;;
+            --also)        also="$2"; shift 2 ;;
+            --help|-h) echo "test-run [--feature-dir <path>] [--scope slice|repo] [--also <csv>]"; return 0 ;;
+            *) echo "test-run: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+
+    # For scope=slice, build the token set = feature aggregate name + --also referrers,
+    # each sanitised to an identifier (VSTest filter operators |&()!=~ are illegal) and
+    # de-duplicated. A token that survives sanitising becomes a `FullyQualifiedName~<tok>`
+    # clause; substring match is deliberate — it over-includes (safe for an integrity
+    # fence) rather than risking an under-scoped miss.
+    local slices="" name tok also_sp
+    if [ "$scope" = "slice" ]; then
+        also_sp=$(printf '%s' "$also" | tr ',' ' ')
+        for name in "$(basename "${feature_dir%/}")" $also_sp; do
+            tok=$(printf '%s' "$name" | tr -cd 'A-Za-z0-9._-')
+            case "$tok" in [A-Za-z]*) ;; *) continue ;; esac      # must start with a letter
+            case " $slices " in *" $tok "*) continue ;; esac       # de-dup
+            slices="${slices:+$slices }$tok"
+        done
+    fi
+
+    local tool="none" ran=false ok=true cmd="" log; log=$(mktemp)
+    local matched=false scoped=false fence_green=false filter="" t2
+
+    local dotnet_present=false
+    if ls "$repo_root"/*.sln >/dev/null 2>&1 || find "$repo_root" -maxdepth 5 -name "*.csproj" 2>/dev/null | grep -q .; then
+        dotnet_present=true
+    fi
+
+    # A DECLARED lane model answers this the same way it answers build-compile, and for
+    # the same reason: the ladder below recognises .NET and npm-at-the-root, and reports
+    # `tool:"none" ran:false ok:true` for everything else. On a repo whose lane declares
+    # `./mvnw test` that is a suite which never ran scoring the integrity fence GREEN —
+    # the vacuous pass this command guards against everywhere else.
+    #
+    # scope=slice keeps the .NET path whenever a .NET toolchain is present, because
+    # VSTest's --filter is the only per-test selector any shipped profile has. Elsewhere a
+    # slice run delegates and widens to the lane's whole suite, which the fence tolerates
+    # by design — it over-includes rather than risking an under-scoped miss — and reports
+    # scoped=false so fence_green comes from `ok` rather than from the zero-match guard.
+    local use_lanes=false
+    if [ -n "$(_aw_lanes_declared)" ]; then
+        if [ "$scope" != "slice" ] || [ "$dotnet_present" = false ]; then use_lanes=true; fi
+    fi
+    if [ "$use_lanes" = true ]; then
+        rm -f "$log"
+        _aw_stack_py run-phase --phase test | AW_SCOPE="$scope" AW_SLICES="$slices" python3 -c '
+import json, os, re, sys
+d = json.loads(sys.stdin.readline() or "{}")
+log, ok = d.get("log_tail", ""), bool(d.get("ok"))
+print(json.dumps({
+    "ok": ok, "tool": d.get("tool", "lanes"), "ran": bool(d.get("ran")),
+    "scope": os.environ.get("AW_SCOPE", "repo"), "slices": os.environ.get("AW_SLICES", ""),
+    "scoped": False, "matched": bool(re.search(r"Total:\s*[1-9]", log)),
+    "fence_green": ok, "cmd": d.get("cmd", ""), "log_tail": log,
+    "lanes_run": d.get("lanes_run", []), "lanes_skipped": d.get("lanes_skipped", []),
+}))
+'
+        return 0
+    fi
+
+    if [ "$dotnet_present" = true ]; then
+        tool="dotnet"
+        if command -v dotnet >/dev/null 2>&1; then
+            if [ "$scope" = "slice" ]; then
+                if [ -z "$slices" ]; then
+                    # scope=slice but nothing valid to filter on — fail loudly, never
+                    # silently fall back to a repo-wide run.
+                    printf 'scope=slice but no valid filter tokens from --feature-dir/--also\n' >"$log"
+                    ok=false; ran=false; cmd="(no filter tokens)"
+                else
+                    for t2 in $slices; do filter="${filter:+$filter|}FullyQualifiedName~$t2"; done
+                    scoped=true; cmd="dotnet test --nologo --filter \"$filter\""; ran=true
+                    if ( cd "$repo_root" && dotnet test --nologo --filter "$filter" ) >"$log" 2>&1; then ok=true; else ok=false; fi
+                fi
+            else
+                cmd="dotnet test --nologo"; ran=true
+                if ( cd "$repo_root" && dotnet test --nologo ) >"$log" 2>&1; then ok=true; else ok=false; fi
+            fi
+        else ok=false; fi
+    elif [ -f "$repo_root/package.json" ] && command -v npm >/dev/null 2>&1; then
+        tool="npm"; cmd="npm test"; ran=true
+        if ( cd "$repo_root" && npm test ) >"$log" 2>&1; then ok=true; else ok=false; fi
+    else
+        tool="none"; ran=false; ok=true
+    fi
+
+    # matched = at least one test was actually selected + run. Read from the LOG, never
+    # the exit code: a .NET --filter that selects ZERO tests still EXITS 0, so trusting
+    # the exit code would report an empty scoped run as green (the vacuous-pass trap).
+    if grep -Eq 'Total:[[:space:]]*[1-9]' "$log" 2>/dev/null; then matched=true; fi
+
+    # fence_green — a green that actually proves something ran.
+    #   scoped run  → ok AND matched (guards the zero-match vacuous pass)
+    #   everything else (repo suite, npm, no test tool, the loud no-token fail) → ok,
+    #   preserving the historic pass-through for a project with no/zero tests.
+    if [ "$scoped" = true ]; then
+        if [ "$ok" = true ] && [ "$matched" = true ]; then fence_green=true; fi
+    else
+        fence_green=$ok
+    fi
+
+    local t; t=$(tail -c 1400 "$log" 2>/dev/null || true); rm -f "$log"
+    printf '{"ok":%s,"tool":"%s","ran":%s,"scope":"%s","slices":"%s","scoped":%s,"matched":%s,"fence_green":%s,"cmd":"%s","log_tail":"%s"}\n' \
+        "$ok" "$(json_escape "$tool")" "$ran" "$(json_escape "$scope")" "$(json_escape "$slices")" \
+        "$scoped" "$matched" "$fence_green" "$(json_escape "$cmd")" "$(json_escape "$t")"
+}
+
+cmd_run_migrate() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) shift 2 ;;
+            --help|-h) echo "run-migrate [--feature-dir <path>]"; return 0 ;;
+            *) echo "run-migrate: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+
+    # A DECLARED migration command wins outright. Schema migration is the phase stacks
+    # answer most differently — Flyway, Liquibase, Alembic, Prisma, golang-migrate — and
+    # no sniffer can pick between tools that happily coexist in one repo. When a lane
+    # declares `migrate` in .appweaver/stacks.json, that IS the answer and it runs in the
+    # lane's own working directory like every other phase command.
+    if [ -n "$(_aw_lane_field backend migrate)$(_aw_lane_field frontend migrate)" ]; then
+        _aw_stack_py run-phase --phase migrate | python3 -c '
+import json, sys
+d = json.loads(sys.stdin.readline() or "{}")
+print(json.dumps({"ok": bool(d.get("ok")), "tool": "lanes", "ran": bool(d.get("ran")),
+                  "cmd": d.get("cmd", ""), "log_tail": d.get("log_tail", ""),
+                  "lanes_run": d.get("lanes_run", [])}))
+'
+        return 0
+    fi
+
+    # WHERE to look for the migration project. The service lane's declared source
+    # path when there is one, `src/` when there is not. Migrations belong to the
+    # backend lane by definition, so a repo whose service code sits in `Legacy/App/`
+    # or `backend/` gets searched where its code actually is instead of being told
+    # it has no .NET project at all.
+    local svc_root; svc_root=$(_aw_lane_root backend)
+    [ -z "$svc_root" ] && svc_root="src"
+    local svc_dir="$repo_root/${svc_root%/}"
+
+    local tool="none" ran=false ok=true cmd="" log; log=$(mktemp)
+    local has_dotnet=false
+    if ls "$repo_root"/*.sln >/dev/null 2>&1 || find "$svc_dir" -maxdepth 4 -name "*.csproj" 2>/dev/null | grep -q .; then has_dotnet=true; fi
+    if [ "$has_dotnet" = true ] && command -v dotnet >/dev/null 2>&1 && ( cd "$repo_root" && dotnet ef --version >/dev/null 2>&1 ); then
+        # Prefer *Service.csproj (API host with ApplicationDbContext); fall back to first
+        # non-AppHost/Web/ServiceDefaults/test project under the service lane's root.
+        local project=""
+        project=$(find "$svc_dir" -maxdepth 3 -name '*.Service.csproj' 2>/dev/null | head -1)
+        if [ -z "$project" ]; then
+            project=$(find "$svc_dir" -maxdepth 3 -name '*.csproj' 2>/dev/null \
+                | grep -vE 'AppHost|ServiceDefaults|\.Web\.|Tests' | head -1)
+        fi
+        if [ -n "$project" ]; then
+            # Multi-context solutions need an explicit context (ApplicationDbContext is the app model).
+            tool="dotnet-ef"
+            cmd="dotnet ef database update --project $project --context ApplicationDbContext"
+            ran=true
+            if ( cd "$repo_root" && dotnet ef database update --project "$project" --context ApplicationDbContext ) >"$log" 2>&1; then
+                ok=true
+            else
+                ok=false
+            fi
+        else
+            tool="dotnet-ef"; cmd="dotnet ef database update"; ran=true
+            if ( cd "$repo_root" && dotnet ef database update ) >"$log" 2>&1; then ok=true; else ok=false; fi
+        fi
+    else
+        # No lane declares `migrate` and there is no dotnet-ef to fall back on, so there
+        # is genuinely nothing to run. ok stays true: a repo with no migrations is a
+        # normal state, not a failure — but `ran:false` says so rather than implying a
+        # migration succeeded.
+        tool="none"; ran=false; ok=true
+    fi
+    local t; t=$(tail -c 1400 "$log" 2>/dev/null || true); rm -f "$log"
+    printf '{"ok":%s,"tool":"%s","ran":%s,"cmd":"%s","log_tail":"%s"}\n' \
+        "$ok" "$(json_escape "$tool")" "$ran" "$(json_escape "$cmd")" "$(json_escape "$t")"
+}
+
+# Deploy is intentionally config-driven: reads .appweaver/deploy.json {"command": "..."}.
+cmd_deploy_dispatch() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "deploy-dispatch"; return 0 ;;
+            *) echo "deploy-dispatch: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local cfg="$repo_root/.appweaver/deploy.json"
+    local configured=false ran=false ok=true cmd="" log; log=$(mktemp)
+    if [ -f "$cfg" ] && command -v python3 >/dev/null 2>&1; then
+        cmd=$(AW_CFG="$cfg" python3 -c "import json,os;print(json.load(open(os.environ['AW_CFG'])).get('command',''))" 2>/dev/null || true)
+    fi
+    if [ -n "$cmd" ]; then
+        configured=true; ran=true
+        if ( cd "$repo_root" && bash -c "$cmd" ) >"$log" 2>&1; then ok=true; else ok=false; fi
+    fi
+    local t; t=$(tail -c 1400 "$log" 2>/dev/null || true); rm -f "$log"
+    printf '{"ok":%s,"configured":%s,"ran":%s,"cmd":"%s","log_tail":"%s"}\n' \
+        "$ok" "$configured" "$ran" "$(json_escape "$cmd")" "$(json_escape "$t")"
+}
+
+# ─────────────────────────────── 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.
+cmd_cr_setup() {
+    local cr_id="" feature_dir_arg="" title="" force=""
+    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 ;;
+            --force) force=1; shift ;;
+            --help|-h) echo "cr-setup --cr-id <id> [--feature-dir <path>] [--title <t>] [--force]"; 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)"
+    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
+    fi
+    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
+    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
+        created=true
+    fi
+    printf '{"cr_id":"%s","cr_dir":"%s","delta_spec":"%s","delta_design":"%s","title":"%s","created":%s}\n' \
+        "$(json_escape "$cr_id")" "$(json_escape "$cr_dir")" "$(json_escape "$dspec")" \
+        "$(json_escape "$ddesign")" "$(json_escape "$title")" "$created"
+}
+
+cmd_cr_archive() {
+    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-archive --cr-id <id> [--feature-dir <path>]"; return 0 ;;
+            *) echo "cr-archive: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$cr_id" ] || { echo "cr-archive: --cr-id required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd="$feature_dir_arg"
+    [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
+    [ -n "$fd" ] || { echo "cr-archive: no feature set and no --feature-dir" >&2; return 1; }
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    local cr_dir="$fd/changes/$cr_id" archive_root="$fd/changes/archive" archived=""
+    if [ -d "$cr_dir" ]; then
+        mkdir -p "$archive_root"
+        rm -rf "$archive_root/$cr_id"
+        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)
+    AW_AV="$av" AW_ARCHIVED="$archived" python3 - <<'PY'
+import json, os
+try: av = json.loads(os.environ.get("AW_AV") or "{}")
+except Exception: av = {}
+print(json.dumps({"ok": True, "archived_dir": os.environ.get("AW_ARCHIVED", ""),
+                  "version": av.get("version", "v1.1"), "previous": av.get("previous", "v1.0"),
+                  "closed_change": av.get("closed_change", "")}))
+PY
+}
+
+# Stamp a version into the MASTER documents' `**Version**:` headers — the
+# deterministic twin of cr-archive's active_version.json bump. close-delta calls
+# this with the version cr-archive just computed, so all THREE carriers of the
+# number (spec.md, design.md, active_version.json) move in ONE stage by ONE
+# mechanism. Before this, design.md's header was bumped by the MODEL at
+# finalize-delta — a stage early, and guessing the target since the number was
+# never passed into the merge prompt — while spec.md's header was bumped by
+# nobody at all and sat at v1.0 forever.
+# Idempotent: re-stamping the same version reports `unchanged`, writes nothing.
+# Only the value moves; any trailing inline comment on the header line is kept.
+cmd_version_stamp() {
+    local version="" feature_dir_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --version) version="$2"; shift 2 ;;
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            --help|-h) echo "version-stamp --version <vX.Y> [--feature-dir <path>]"; return 0 ;;
+            *) echo "version-stamp: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$version" ] || { echo "version-stamp: --version required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd="$feature_dir_arg"
+    [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
+    [ -n "$fd" ] || { echo "version-stamp: no feature set and no --feature-dir" >&2; return 1; }
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    AW_FD="$fd" AW_VER="$version" python3 - <<'PY'
+import json, os, re
+fd = os.environ["AW_FD"]; ver = os.environ["AW_VER"].strip()
+stamped, unchanged, missing, no_header = [], [], [], []
+# First `**Version**: <value>` line only — that is the header. The Change History
+# table's `| Version |` column head does not match this pattern.
+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
+# 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"):
+    p = os.path.join(fd, name)
+    if not os.path.isfile(p):
+        missing.append(name); continue
+    src = open(p, encoding="utf-8").read()
+    m = pat.search(src)
+    if not m:
+        no_header.append(name); continue
+    if m.group(2) == ver:
+        unchanged.append(name); continue
+    open(p, "w", encoding="utf-8").write(
+        src[:m.start()] + m.group(1) + ver + m.group(3) + src[m.end():])
+    stamped.append(name)
+print(json.dumps({"ok": True, "version": ver, "stamped": stamped,
+                  "unchanged": unchanged, "missing": missing,
+                  "no_header": no_header, "count": len(stamped)}))
+PY
+}
+
+case "$sub" in
+    resolve-domain)   cmd_resolve_domain "$@" ;;
+    resolve-tech)     cmd_resolve_tech "$@" ;;
+    scaffold)         cmd_scaffold "$@" ;;
+    resolve-hooks)    cmd_resolve_hooks "$@" ;;
+    create-checklist) cmd_create_checklist "$@" ;;
+    list-domains)     cmd_list_domains "$@" ;;
+    set-domain)       cmd_set_domain "$@" ;;
+    stack-list)       cmd_stack_list "$@" ;;
+    stack-detect)     cmd_stack_detect "$@" ;;
+    lane-declare)     cmd_lane_declare "$@" ;;
+    lane-resolve)     cmd_lane_resolve "$@" ;;
+    lane-verify)      cmd_lane_verify "$@" ;;
+    lane-probe)       cmd_lane_probe "$@" ;;
+    list-features)    cmd_list_features "$@" ;;
+    set-feature)      cmd_set_feature "$@" ;;
+    version-read)     cmd_version_read "$@" ;;
+    version-init)     cmd_version_init "$@" ;;
+    feature-paths)    cmd_feature_paths "$@" ;;
+    design-scaffold)  cmd_design_scaffold "$@" ;;
+    build-compile)    cmd_build_compile "$@" ;;
+    test-run)         cmd_test_run "$@" ;;
+    run-migrate)      cmd_run_migrate "$@" ;;
+    deploy-dispatch)  cmd_deploy_dispatch "$@" ;;
+    cr-setup)         cmd_cr_setup "$@" ;;
+    cr-archive)       cmd_cr_archive "$@" ;;
+    version-stamp)    cmd_version_stamp "$@" ;;
+    checklist-read)   cmd_checklist_read "$@" ;;
+    checklist-apply)  cmd_checklist_apply "$@" ;;
+    detect-project)   cmd_detect_project "$@" ;;
+    foundation-list)  cmd_foundation_list "$@" ;;
+    foundation-locate) cmd_foundation_locate "$@" ;;
+    foundation-unpack) cmd_foundation_unpack "$@" ;;
+    foundation-verify) cmd_foundation_verify "$@" ;;
+    foundation-stash-dbcontext) cmd_foundation_stash_dbcontext "$@" ;;
+    list-components)  cmd_list_components "$@" ;;
+    component-catalog) cmd_component_catalog "$@" ;;
+    component-verify) cmd_component_verify "$@" ;;
+    find-host-project) cmd_find_host_project "$@" ;;
+    setup-constitution) cmd_setup_constitution "$@" ;;
+    compose-constitution) cmd_compose_constitution "$@" ;;
+    constitution-verify) cmd_constitution_verify "$@" ;;
+    agent-context-update) cmd_agent_context_update "$@" ;;
+    ""|--help|-h)
+        sed -n '2,37p' "$0" | sed 's/^#\{0,1\} \{0,1\}//' ;;
+    *)
+        echo "Unknown subcommand: $sub" >&2
+        echo "Run '$0 --help' for usage." >&2
+        exit 1 ;;
+esac