aw-spec-cli 0.1.4 → 0.1.5

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

@@ -0,0 +1,1899 @@
+#!/usr/bin/env bash
+#
+# aw-spec-actions.sh — common action dispatcher for declarative aw-spec skills.
+#
+# ONE shared script for every integration (.claude / .agents / .kilocode). The
+# declarative skill.yaml files reference these subcommands via `execute_script`.
+# 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 (the skill's single `llm_generate` step).
+#
+# 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}
+#   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[]}  (docs/components/* with integration.md)
+#   find-host-project                              -> {found, program_cs, project_dir, csproj}
+#   setup-constitution                             -> {constitution_technical_file, constitution_domain_file, technical_created, domain_created}
+#   compose-constitution                           -> {composed_file, ok, issues}
+#   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/.aw-spec/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/docs/domainspecs/$domain/comandrulemap.md"
+    local rulemap_exists=false
+    [ -n "$domain" ] && [ -f "$rulemap" ] && rulemap_exists=true
+
+    # Collect bullet paths under "## /<command>" in the domain's comandrulemap.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
+# docs/domainspecs/<domain>/commandtechrulemap.md. The TECHNICAL rule files (the
+# docs/architecture · docs/security · docs/interop · docs/governance rule set that
+# used to be hardcoded in each workflow's `standards:` block) are now configured
+# per-command in this map, so they can be tuned per project WITHOUT editing the
+# workflows. The technical CONSTITUTION (constitution.technical.md) is NOT mapped —
+# it is still referred to directly by each consumer, as-is.
+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/.aw-spec/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 techmap="$repo_root/docs/domainspecs/$domain/commandtechrulemap.md"
+    local techmap_exists=false
+    [ -n "$domain" ] && [ -f "$techmap" ] && techmap_exists=true
+
+    # Collect bullet paths under "## /<command>" (try the exact command heading,
+    # then the decl-stripped name, mirroring resolve-domain's fallback).
+    local -a candidates=()
+    if [ "$techmap_exists" = true ]; then
+        local heading
+        for heading in "/$command_name" "/${command_name/decl-/}"; do
+            while IFS= read -r line; do
+                [ -n "$line" ] && candidates+=("$line")
+            done < <(awk -v h="## $heading" '
+                $0==h {grab=1; next}
+                /^## / {grab=0}
+                grab && /^[[:space:]]*-[[:space:]]+/ {
+                    sub(/^[[:space:]]*-[[:space:]]+/,""); sub(/[[:space:]]+$/,""); print
+                }
+            ' "$techmap")
+            [ ${#candidates[@]} -gt 0 ] && break
+        done
+    fi
+
+    printf '{"domain":"%s","techrulemap_exists":%s,"candidates":%s}\n' \
+        "$(json_escape "$domain")" "$techmap_exists" "$(json_str_array "${candidates[@]}")"
+}
+
+# ─────────────────────────────── 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 .aw-spec/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/.aw-spec/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
+
+## Merge Readiness
+
+- [ ] Header is complete: aggregate, change type, base version
+- [ ] Impact lists the affected ids (FR / BR / CN / DC / IC / 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
+  /aw-spec-orch analyze-delta-design.
+- Items marked incomplete require delta-spec updates before /aw-spec-orch 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
+
+## 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 /aw-spec-orch 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 ──────────────────────────────
+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/docs/domainspecs"
+    local -a domains=()
+    if [ -d "$base" ]; then
+        local d
+        for d in "$base"/*/; do
+            [ -d "$d" ] || 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="docs/domainspecs/$domain/comandrulemap.md"
+    local map_exists=false
+    [ -f "$repo_root/$map_rel" ] && map_exists=true
+
+    mkdir -p "$repo_root/.aw-spec"
+    local dj="$repo_root/.aw-spec/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"
+}
+
+# ─────────────────────────────── 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
+# (.aw-spec/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 .aw-spec/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 /aw-spec-orch select-feature first)" >&2
+        return 1
+    fi
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    local feature; feature=$(basename "$fd")   # the aggregate name (feature = specs/<Feature>)
+    # The two-document model: spec.md + design.md ONLY. plan.md / tasks.md belonged to
+    # the retired /aw-spec-plan + /aw-spec-tasks phases and had zero consumers.
+    local spec="$fd/spec.md" design="$fd/design.md"
+    local spec_exists=false;   [ -f "$spec" ]   && spec_exists=true
+    local design_exists=false; [ -f "$design" ] && design_exists=true
+    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","design_file":"%s","spec_exists":%s,"design_exists":%s}\n' \
+        "$(json_escape "$feature")" "$(json_escape "$fd")" "$(json_escape "$spec")" "$(json_escape "$design")" \
+        "$spec_exists" "$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)?
+cmd_detect_project() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "detect-project"; return 0 ;;
+            *) echo "detect-project: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local -a markers=()
+    # .NET solution/project (ignore framework dirs)
+    while IFS= read -r m; do [ -n "$m" ] && markers+=("$m"); done < <(
+        find "$repo_root" \( -path "$repo_root/.aw-spec" -o -path "$repo_root/docs" -o -path "$repo_root/specs" -o -path "$repo_root/.git" -o -name node_modules \) -prune -o \
+             \( -name "*.sln" -o -name "*.csproj" \) -print 2>/dev/null | sed "s#^$repo_root/##" | head -20 )
+    # Other ecosystems at repo root
+    local f
+    for f in package.json pom.xml build.gradle build.gradle.kts go.mod Cargo.toml pyproject.toml; do
+        [ -f "$repo_root/$f" ] && markers+=("$f")
+    done
+    local scaffolded=false
+    [ ${#markers[@]} -gt 0 ] && scaffolded=true
+    printf '{"scaffolded":%s,"markers":%s}\n' "$scaffolded" "$(json_str_array "${markers[@]}")"
+}
+
+
+# ──────────────────────────── foundation-list ──────────────────────────────
+# Enumerate available foundations (docs/<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)
+    local -a foundations=()
+    if [ -d "$repo_root/docs" ]; then
+        local d name
+        for d in "$repo_root/docs"/*/; do
+            [ -d "$d" ] || continue
+            name="$(basename "$d")"
+            [ -f "$d$name.pack.txt" ] && foundations+=("$name")   # the primary pack (excludes Reference-only dirs)
+        done
+    fi
+    # 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,"preselect_name":"%s","preselect_app":"%s","out_dir":"%s"}\n' \
+        "$(json_str_array "${foundations[@]}")" "${#foundations[@]}" \
+        "$(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 = docs subdirs containing a *.pack.txt
+    local -a available=()
+    if [ -d "$repo_root/docs" ]; then
+        local d
+        for d in "$repo_root/docs"/*/; do
+            [ -d "$d" ] || continue
+            ls "$d"*.pack.txt >/dev/null 2>&1 && available+=("$(basename "$d")")
+        done
+    fi
+    _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 fdir="$repo_root/docs/$name"
+    if [ ! -d "$fdir" ]; then _fnd_fail "Foundation '$name' not found (expected docs/$name/)"; return 0; fi
+    local pack="$fdir/$name.pack.txt"
+    if [ ! -f "$pack" ]; then _fnd_fail "Foundation '$name' has no bundle yet (expected $pack). Build it via docs/$name/PACKAGING.md."; 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="docs/$name/unpack-foundation.ps1"
+    elif [ -f "$fdir/unpack-foundation.sh" ]; then
+        runner="sh"; unpacker="docs/$name/unpack-foundation.sh"
+    else
+        emit_fail "No unpacker found in docs/$name/ (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","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 "$app")" "$(json_escape "$out")" "$(json_escape "docs/$name/$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 fdir="$repo_root/docs/$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=docs --exclude-dir=.aw-spec \
+                 --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):
+#   .aw-spec/memory/constitution.technical.md  (from constitution-technical-template)
+#   .aw-spec/memory/constitution.domain.md     (from constitution-domain-template)
+# The composed .aw-spec/memory/constitution.md is produced by `compose-constitution`
+# after both halves are authored. Each half is authored + verified independently.
+cmd_setup_constitution() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "setup-constitution"; 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/.aw-spec/memory"
+    local tech="$repo_root/.aw-spec/memory/constitution.technical.md"
+    local dom="$repo_root/.aw-spec/memory/constitution.domain.md"
+    local tech_created=false dom_created=false
+    if [ ! -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
+    printf '{"constitution_technical_file":"%s","constitution_domain_file":"%s","technical_created":%s,"domain_created":%s}\n' \
+        "$(json_escape "$tech")" "$(json_escape "$dom")" "$tech_created" "$dom_created"
+}
+
+# ─────────────────────────────── compose-constitution ──────────────────────
+# Deterministically concatenate the technical + domain halves into the composed
+# .aw-spec/memory/constitution.md (human/compat view; NOT loaded by the pipeline
+# phases — they load the halves directly). No model. If the domain half is absent
+# or empty (technical-only project), the composed file mirrors the technical half.
+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 tech="$repo_root/.aw-spec/memory/constitution.technical.md"
+    local dom="$repo_root/.aw-spec/memory/constitution.domain.md"
+    local out="$repo_root/.aw-spec/memory/constitution.md"
+    [ -f "$tech" ] || { printf '{"composed_file":"%s","ok":false,"domain_included":false,"issues":["technical half not found"]}\n' "$(json_escape "$out")"; return 0; }
+    # Include the domain half only if it is authored — non-empty AND free of residual
+    # [ALL_CAPS] template placeholders (a technical-only project leaves it as a raw template).
+    local include_domain=false
+    if [ -f "$dom" ] && [ -s "$dom" ] && ! grep -qE '\[[A-Z0-9]+(_[A-Z0-9]+)+\]' "$dom"; then
+        include_domain=true
+    fi
+    {
+        printf '<!-- COMPOSED — generated by `aw-spec-actions compose-constitution`. Do not edit here.\n'
+        printf '     Source of truth: constitution.technical.md + constitution.domain.md (edit those).\n'
+        printf '     Pipeline phases load the halves directly; this composed view is for humans/compat. -->\n\n'
+        cat "$tech"
+        if [ "$include_domain" = true ]; then
+            printf '\n\n---\n\n'
+            cat "$dom"
+        fi
+    } > "$out"
+    printf '{"composed_file":"%s","ok":true,"domain_included":%s,"issues":[]}\n' "$(json_escape "$out")" "$include_domain"
+}
+
+# ─────────────────────────── constitution-verify ───────────────────────────
+# Deterministic lint of a generated constitution (NO LLM): residual
+# [ALL_CAPS_WITH_UNDERSCORE] placeholder tokens, 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.
+cmd_constitution_verify() {
+    local file=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --file) file="$2"; shift 2 ;;
+            --help|-h) echo "constitution-verify --file <path>"; return 0 ;;
+            *) echo "constitution-verify: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$file" ] || { echo "constitution-verify: --file required" >&2; return 1; }
+    AW_FILE="$file" 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. Residual ALL_CAPS_WITH_UNDERSCORE placeholder tokens (the template convention).
+placeholders = sorted(set(re.findall(r"\[([A-Z0-9]+(?:_[A-Z0-9]+)+)\]", body)))
+# 2. Version: labeled body version vs the report's "new" version.
+def labeled(s):
+    mm = re.search(r"(?im)version[^0-9\n]{0,20}v?(\d+\.\d+\.\d+)", s)
+    return mm.group(1) if mm else None
+version_body = labeled(body)
+arrow = re.search(r"(\d+\.\d+\.\d+)\s*(?:->|→|=>)\s*(\d+\.\d+\.\d+)", report)
+version_report = arrow.group(2) if arrow else labeled(report)
+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 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, "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/.aw-spec/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 docs/components/ that contain an integration.md runbook.
+cmd_list_components() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "list-components"; return 0 ;;
+            *) echo "list-components: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local base="$repo_root/docs/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}\n' "$(json_str_array "${comps[@]}")"
+}
+
+# ─────────────────────────────── find-host-project ─────────────────────────
+# Locate the host/startup project by finding Program.cs (never assume a name).
+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
+    # prefer under src/, ignore framework/build dirs
+    prog=$(find "$repo_root/src" -name "Program.cs" 2>/dev/null | head -1)
+    [ -z "$prog" ] && prog=$(find "$repo_root" \( -path "$repo_root/.aw-spec" -o -path "$repo_root/docs" -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":""}\n'; 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"}\n' \
+        "$(json_escape "$prog")" "$(json_escape "$pdir")" "$(json_escape "$csproj")"
+}
+
+# ─────────────────────────────── 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}]}.
+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)
+    [[ "$file" != /* ]] && file="$repo_root/$file"
+    AW_FILE="$file" python3 - <<'PY'
+import json, os, re
+f = os.environ["AW_FILE"]
+if not os.path.exists(f):
+    print(json.dumps({"integrable": False, "impl_keys": [], "implementations": []})); raise SystemExit
+lines = open(f, encoding="utf-8").read().splitlines()
+start = None
+for i, ln in enumerate(lines):
+    if re.match(r'^#{1,6}\s', ln) and re.search(r'(?i)implementation catalog|selection list', ln):
+        start = i + 1; break
+rows = []
+if start is not None:
+    for ln in lines[start:]:
+        if re.match(r'^#{1,6}\s', ln):      # next heading ends the section
+            break
+        s = ln.strip()
+        if s.startswith("|"):
+            rows.append(s)
+        elif rows:                          # blank/non-table after the table => done
+            break
+def cells(row):
+    return [c.strip() for c in row.strip().strip("|").split("|")]
+impl_keys, implementations = [], []
+if len(rows) >= 2:
+    header = cells(rows[0])
+    kidx = 0
+    for j, h in enumerate(header):
+        if h.strip().lower() == "key":
+            kidx = j; break
+    for row in rows[2:]:                     # skip header + separator
+        c = cells(row)
+        if not c or all(re.fullmatch(r':?-{2,}:?', (x or '')) for x in c):
+            continue
+        if kidx >= len(c):
+            continue
+        key = c[kidx].strip("` ").strip()
+        if not key:
+            continue
+        parts = []
+        for j, val in enumerate(c):
+            if j == kidx or not val:
+                continue
+            h = header[j] if j < len(header) else ""
+            parts.append("%s: %s" % (h, val) if h else val)
+        impl_keys.append(key)
+        implementations.append({"key": key, "desc": " · ".join(parts)})
+print(json.dumps({"integrable": len(impl_keys) > 0,
+                  "impl_keys": impl_keys, "implementations": implementations}))
+PY
+}
+
+# ─────────────────────────────── 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 .aw-spec/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="design-template"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) feature_dir_arg="$2"; shift 2 ;;
+            # --template <name>: which template to scaffold (default `design-template`).
+            # In a brownfield repo, /aw-spec-orch onboard GENERATES a code-derived
+            # `design-template` override (resolve_template Priority-1), so the default
+            # already yields the as-built structure for both forward `design` and adopt
+            # (no per-call --template needed). Resolved via resolve_template.
+            --template) template_arg="$2"; shift 2 ;;
+            --help|-h) echo "design-scaffold --feature-dir <path> [--template <name>]"; return 0 ;;
+            *) echo "design-scaffold: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd="$feature_dir_arg"
+    [ -n "$fd" ] || fd=$(read_feature_json_feature_directory "$repo_root")
+    [ -n "$fd" ] || { echo "design-scaffold: no feature set (run /aw-spec-orch select-feature first) and no --feature-dir" >&2; return 1; }
+    [[ "$fd" != /* ]] && fd="$repo_root/$fd"
+    mkdir -p "$fd"
+
+    local target="$fd/design.md" 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,
+    # /aw-spec-orch 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/.aw-spec/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","created":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+        "$(json_escape "$fd")" "$(json_escape "$target")" "$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.
+
+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
+    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
+    if ls "$repo_root"/*.sln >/dev/null 2>&1 || find "$repo_root" -maxdepth 5 -name "*.csproj" 2>/dev/null | grep -q .; 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)
+    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 "$repo_root/src" -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 src/.
+        local project=""
+        project=$(find "$repo_root/src" -maxdepth 3 -name '*.Service.csproj' 2>/dev/null | head -1)
+        if [ -z "$project" ]; then
+            project=$(find "$repo_root/src" -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
+        tool="none"; ran=false; ok=true   # no .NET project / migration tool = nothing to run
+    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 .aw-spec/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/.aw-spec/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)
+for name in ("spec.md", "design.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 "$@" ;;
+    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,34p' "$0" | sed 's/^#\{0,1\} \{0,1\}//' ;;
+    *)
+        echo "Unknown subcommand: $sub" >&2
+        echo "Run '$0 --help' for usage." >&2
+        exit 1 ;;
+esac