aw-spec-cli 0.1.26 → 0.1.28

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

@@ -2,7 +2,7 @@
 #
 # aw-spec-actions.sh — common action dispatcher for the aw-spec orchestrator.
 #
-# ONE shared script for every integration (.claude / .agents / .kilocode). The
+# ONE shared script for every integration (.claude / .agents / .kilo). The
 # orchestrator workflows reach these subcommands through `execute_script` steps.
 # Each subcommand performs deterministic, governance-safe work and prints a single
 # JSON object on stdout. NONE of these actions author spec/code content — content
@@ -47,8 +47,16 @@
 #                     Always exits 0 — the workflow's verify_context owns the stop)
 #   lane-probe       [--kind <k>] [--hint <text>]  -> {declared, declared_profile, hint_profile, hint_terms[], signals[], any, evidence}
 #                    (the FILE signals for "does this lane exist"; resolve-tech carries the rule signal)
+#   lane-set         (--id <lane>|--kind <k>) [--set KEY=VALUE]… [--unset KEY]…  -> {ok, lane_id, set, removed, written}
+#                    (KEY: contract_run, contract, client; an empty VALUE changes nothing)
+#   contract-export  [--timeout <s>]               -> {ok, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}
+#                    (start the service lane with contract_run, save the document at contract, stop it)
+#   contract-client                                -> run-phase result for the frontend lane's `client` command
+#   contract-check   --plan <p> [--doc <d>]        -> {ok, cited, ids[], missing[], uncited, doc_exists, reason}
 #   list-features    [--preselect <name>] [--bundle <dir>]  -> {features[], names[], count, select_options[], sentinel}   (specs/ ∪ features the OKF concepts serve)
 #   set-feature      --feature <name>              -> {feature, feature_dir, spec_file, existed, created, spec_exists}
+#   default-scope    --context <name> --feature <name>  -> {created, skipped_reason, context_dir, feature_dir}
+#                    (creates and activates both only on a project with no specs yet)
 #   version-read     [--feature-dir <path>]        -> {feature, version, active_change, exists, bootstrap_pending}
 #   version-init     [--feature-dir <path>] [--bootstrap]  -> {…, created, bootstrap_pending}   (create active_version.json v1.0; --bootstrap marks a FIRST draft in progress)
 #   version-bootstrap-done [--feature-dir <path>]  -> {…, cleared}   (the ONLY clearer of the --bootstrap marker; call it when the first draft is finished)
@@ -63,11 +71,28 @@
 #                                                  -> {ok, total, names[], names_csv, elements[], gaps[], gap_count, gaps_text}
 #                    (which plan elements the lane's code names and the model reported done)
 #   detect-project                                 -> {scaffolded, markers[]}
-#   foundation-list  [--args '<F> <A> [out]']      -> {foundations[], count, preselect_name, preselect_app, out_dir}
+#   foundation-list  [--kind <k>] [--profile <id>] [--ecosystem <e>] [--lane-id <id>] [--args '<F> <A>']
+#                                                  -> {options[], entries[], count, foundations[], specs[], preselect_option, preselect_app, rejected_out}
+#                    (one lane's pick list: its packs + specs, then [manual spec] and [skip])
+#   foundation-choice --selection <option> [same filters as foundation-list]
+#                                                  -> {ok, route (pack|spec|manual|skip), name, file, reason}
+#   foundation-spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>) [--app <A>]
+#                                                  -> {ok, spec_path, source, chars, title, reason, contract_run, contract, client, settings_text}
+#   foundation-lane-files --source <p> [--test <p>] [--workdir <p>] [--profile <id>]
+#                                                  -> {has_files, count, sample[], generated[], root_files[], folders[], workdir, summary}
+#   foundation-snapshot --out <repo-relative file>  -> {ok, snapshot, entries}
+#   foundation-outside --snapshot <file> --lane <lane root folder> [--undo]
+#                                                  -> {clean, created[], changed[], deleted[], removed[], summary}
 #   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}
+#                                                  -> {ok, reason, name, app, out_dir, pack_file, unpacker, runner, sentinel, file_count, has_reference, available[]}
+#   foundation-unpack --name <F> --app <A> --out <d> [--test-path <d>] [--dry-run] [--force <yes|no>] [--reference]
+#                                                  -> {ok, mode, written, has_collisions, tests_moved, tests_message, stdout}
+#   foundation-rules --name <F> --app <A> --out <lane root folder> [--reference] [--state <folder>]
+#                                                  -> {ok, reason, rules_file, rules, merges[], merge_count, stale[], note}
+#                    (what the pack's <pack name>.rules.json asks of this unpack; puts the files to merge aside)
+#   foundation-rules-done [--state <folder>]       -> {ok, removed}
+#   foundation-pack-lane --name <F> --app <A>      -> {found, file, contract_run, contract, client, reason}
+#                    (the lane settings in the pack's <pack name>.lane.json, sentinel renamed)
 #   foundation-verify --out <d> --sentinel <s>     -> {clean, residue[]}
 #   list-components                                -> {components[]}  (foundations/dotnet/components/* with integration.md)
 #   find-host-project                              -> {found, program_cs, project_dir, csproj}
@@ -86,7 +111,9 @@
 #   (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}
+#   build-compile    [--feature-dir <path>] [--kind backend|frontend]
+#                                                  -> {ok, tool, ran, cmd, log_tail}
+#                    (--kind builds that one declared lane; ignored when no lane is declared)
 #   test-run         [--feature-dir <path>]        -> {ok, tool, ran, cmd, log_tail,
 #                                                      failing_excerpt, failing_lanes[],
 #                                                      no_setup, setup_reason, setup_missing[]}
@@ -163,7 +190,7 @@ cmd_resolve_domain() {
         fi
     fi
 
-    local rulemap="$repo_root/guardrails/projects/$domain/domain-rule-bindings.md"
+    local rulemap="$repo_root/guardrails/$domain/domain-rule-bindings.md"
     local rulemap_exists=false
     [ -n "$domain" ] && [ -f "$rulemap" ] && rulemap_exists=true
 
@@ -188,7 +215,7 @@ cmd_resolve_domain() {
 
 # ──────────────────────────────── resolve-tech ─────────────────────────────
 # Technical rule-file mapping — parallel to resolve-domain, but reads
-# guardrails/projects/<project>/tech-rule-bindings.md. The TECHNICAL rule files live in the
+# guardrails/<project>/tech-rule-bindings.md. The TECHNICAL rule files live in the
 # shared per-stack corpora at guardrails/technology/<stack>/ (rules) and
 # guardrails/technology/<stack>/examples/ (the worked sample for a rule file), and are
 # configured per-command in this map, so they can be tuned per project WITHOUT editing the
@@ -239,7 +266,7 @@ repo    = os.environ["AW_REPO"]
 domain  = os.environ.get("AW_DOMAIN", "")
 command = os.environ.get("AW_COMMAND", "")
 
-techmap = os.path.join(repo, "guardrails", "projects", domain, "tech-rule-bindings.md")
+techmap = os.path.join(repo, "guardrails", domain, "tech-rule-bindings.md")
 exists  = bool(domain) and os.path.isfile(techmap)
 
 # WHAT A PLACEHOLDER IS FOR. A technical rule corpus is stack-partitioned —
@@ -638,11 +665,12 @@ EOF
 }
 
 # ─────────────────────────────── list-domains ──────────────────────────────
-# The selectable projects: immediate subdirs of guardrails/projects/ that carry a rule
-# map. The map is what makes a directory a project, exactly as a *.pack.txt is what makes
-# a foundations/ directory a foundation — without that test any stray sibling would be
-# offered as a governance target. EITHER map qualifies, because onboard writes the domain
-# map several steps before the technical one and a half-built project must stay visible.
+# The projects: immediate subdirs of guardrails/ that carry a rule map. The map is what
+# makes a directory a project, exactly as a *.pack.txt is what makes a foundations/
+# directory a foundation — the shared corpora technology/ and domain/ sit beside the
+# projects and carry no map, so they are never listed. EITHER map qualifies, because
+# onboard writes the domain map several steps before the technical one and a half-built
+# project must stay visible.
 cmd_list_domains() {
     while [ $# -gt 0 ]; do
         case "$1" in
@@ -651,7 +679,7 @@ cmd_list_domains() {
         esac
     done
     local repo_root; repo_root=$(get_repo_root)
-    local base="$repo_root/guardrails/projects"
+    local base="$repo_root/guardrails"
     local -a domains=()
     if [ -d "$base" ]; then
         local d
@@ -677,7 +705,7 @@ cmd_set_domain() {
     [ -n "$domain" ] || { echo "set-domain: --domain is required" >&2; return 1; }
 
     local repo_root; repo_root=$(get_repo_root)
-    local map_rel="guardrails/projects/$domain/domain-rule-bindings.md"
+    local map_rel="guardrails/$domain/domain-rule-bindings.md"
     local map_exists=false
     [ -f "$repo_root/$map_rel" ] && map_exists=true
 
@@ -697,9 +725,10 @@ cmd_set_domain() {
 # The lane model. All four delegate to the shared python core so the bash and
 # powershell twins cannot drift: the JSON contract has one implementation.
 #
-# lane-declare is the SOLE WRITER of .appweaver/stacks.json and has exactly one
-# caller (aw-spec-select-stack). lane-resolve can never write — which is why
-# these are two subcommands rather than one with a mode flag.
+# lane-declare writes WHOLE lanes into .appweaver/stacks.json and has exactly one caller
+# (aw-spec-select-stack); lane-set changes only the API-contract keys on a lane already
+# there (foundation and implement call it). lane-resolve can never write — which is why
+# these are separate subcommands rather than one with a mode flag.
 _aw_stack_py() {
     local repo_root; repo_root=$(get_repo_root)
     local core="$SCRIPT_DIR/../python/aw-stack.py"
@@ -728,7 +757,7 @@ except Exception:
 ' 2>/dev/null || echo ""
 }
 
-# The declared SOURCE PATH of a lane kind — the field asked for most often.
+# The declared LANE ROOT FOLDER of a lane kind — the field asked for most often.
 _aw_lane_root() { _aw_lane_field "$1" root; }
 
 # Every ecosystem the declared lanes belong to, one per line, deduped and empty when
@@ -813,12 +842,66 @@ cmd_lane_resolve() {
     _aw_stack_py resolve "${fwd[@]}"
 }
 
+# Change the API-contract keys (contract_run, contract, client) on a lane already
+# declared, leaving the rest of it alone. `--set KEY=` with an empty value changes
+# nothing; `--unset KEY` removes one. Callers: foundation (a pack's lane settings) and
+# implement (the client command a developer supplies).
+cmd_lane_set() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --id|--kind|--set|--unset) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "lane-set (--id <lane>|--kind backend|frontend) [--set KEY=VALUE]… [--unset KEY]…  (KEY: contract_run, contract, client)"; return 0 ;;
+            *) echo "lane-set: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py set "${fwd[@]}"
+}
+
+# ─────────────── contract-export / contract-client / contract-check ───────────────
+# The API contract between the lanes: export the service lane's API document from the
+# running service, generate the frontend lane's client from it, and check the operation
+# ids a frontend plan cites against it. All three delegate to aw-stack.py.
+cmd_contract_export() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --timeout) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "contract-export [--timeout <seconds>]  -> {ok, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}"; return 0 ;;
+            *) echo "contract-export: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-export "${fwd[@]}"
+}
+
+cmd_contract_client() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "contract-client  -> run-phase --phase client for the frontend lane"; return 0 ;;
+            *) echo "contract-client: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py run-phase --phase client --kind frontend
+}
+
+cmd_contract_check() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --plan|--doc) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "contract-check --plan <frontend plan> [--doc <api document>]  -> {ok, cited, ids, missing, uncited, doc_exists, reason}"; return 0 ;;
+            *) echo "contract-check: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-check "${fwd[@]}"
+}
+
 # The gate: is the declaration USABLE for the phase about to run. --require names a
 # lane kind the phase cannot run without and is repeatable; every DECLARED lane is
-# checked for a sound source path whether or not it was required, because a stack
+# checked for a sound lane root folder whether or not it was required, because a stack
 # named against a directory that is not there is a mistake in every phase.
-# --allow-missing-root is the greenfield state, where select-stack declares a source
-# path before implement creates it.
+# --allow-missing-root is the greenfield state, where select-stack declares a lane root
+# folder before implement creates it.
 cmd_lane_verify() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
@@ -949,6 +1032,13 @@ PY
 # file; a new one is created. The context directory is created but domain-model.md is
 # NOT — that document is authored by specify, which is the only writer of the model,
 # and an empty placeholder would read as "the model exists" to every later gate.
+#
+# The active feature belongs to the context it was created in. When the selected
+# context does not contain it, .appweaver/feature.json is cleared, so the next
+# feature-scoped command stops with "No active feature" instead of writing into the
+# context the developer just left (and adopt with no argument does not recreate that
+# feature's name in the new context). A flat specs/<Feature> is outside every context
+# and is cleared the same way.
 cmd_set_context() {
     local raw=""
     while [ $# -gt 0 ]; do
@@ -991,11 +1081,20 @@ cmd_set_context() {
             "$(json_escape "$context")" "$(json_escape "$context_dir_rel")" > "$cj"
     fi
 
+    local active_fd; active_fd=$(read_feature_json_feature_directory "$repo_root")
+    active_fd="${active_fd#"$repo_root/"}"; active_fd="${active_fd#./}"; active_fd="${active_fd%/}"
+    local feature_cleared=false cleared_feature=""
+    if [ -n "$active_fd" ] && [[ "$active_fd" != "$context_dir_rel/"* ]]; then
+        _persist_feature_json "$repo_root" ""
+        feature_cleared=true; cleared_feature="$active_fd"
+    fi
+
     local created=true; [ "$existed" = true ] && created=false
     local dm_exists=false; [ -f "$context_dir/domain-model.md" ] && dm_exists=true
-    printf '{"context":"%s","context_dir":"%s","domain_model":"%s","existed":%s,"created":%s,"domain_model_exists":%s,"written":true}\n' \
+    printf '{"context":"%s","context_dir":"%s","domain_model":"%s","existed":%s,"created":%s,"domain_model_exists":%s,"feature_cleared":%s,"cleared_feature":"%s","written":true}\n' \
         "$(json_escape "$context")" "$(json_escape "$context_dir_rel")" \
-        "$(json_escape "$context_dir_rel/domain-model.md")" "$existed" "$created" "$dm_exists"
+        "$(json_escape "$context_dir_rel/domain-model.md")" "$existed" "$created" "$dm_exists" \
+        "$feature_cleared" "$(json_escape "$cleared_feature")"
 }
 
 # ══════════════════════ domain model — context-level helpers ════════════════
@@ -1460,6 +1559,47 @@ PY
         "$(json_escape "$context")"
 }
 
+# ─────────────────────────────── default-scope ─────────────────────────────
+# The bounded context and feature a new project starts in, so a simple project goes
+# from /appweaver constitution straight to specify. Acts only on a project with no specs
+# yet: no directory under specs/ (no context, no feature) and no active feature. Every
+# other state is reported as skipped and left untouched, so a re-run of constitution
+# never moves the active feature and an onboarded brownfield tree is never added to.
+# Creation goes through set-context and set-feature, so the folders and both pointer
+# files are written exactly as select-bounded-context and select-feature write them.
+# context_dir / feature_dir report the active pair after the call, created or not.
+cmd_default_scope() {
+    local ctx="" feat=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --context) ctx="$2"; shift 2 ;;
+            --feature) feat="$2"; shift 2 ;;
+            --help|-h) echo "default-scope --context <name> --feature <name>   (create and activate both on a project with no specs yet)"; return 0 ;;
+            *) echo "default-scope: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    { [ -n "$ctx" ] && [ -n "$feat" ]; } || { echo "default-scope: --context and --feature are required" >&2; return 1; }
+
+    local repo_root; repo_root=$(get_repo_root)
+    local reason=""
+    if [ -d "$repo_root/specs" ] && [ -n "$(find "$repo_root/specs" -mindepth 1 -maxdepth 1 -type d -print -quit 2>/dev/null)" ]; then
+        reason="specs/ already holds a bounded context or a feature"
+    elif [ -n "$(read_feature_json_feature_directory "$repo_root")" ]; then
+        reason="a feature is already active in .appweaver/feature.json"
+    fi
+
+    local created=false
+    if [ -z "$reason" ]; then
+        cmd_set_context --context "$ctx" >/dev/null || return 1
+        cmd_set_feature --feature "$feat" >/dev/null || return 1
+        created=true
+    fi
+    printf '{"created":%s,"skipped_reason":"%s","context_dir":"%s","feature_dir":"%s"}\n' \
+        "$created" "$(json_escape "$reason")" \
+        "$(json_escape "$(read_context_json_context_directory "$repo_root")")" \
+        "$(json_escape "$(read_feature_json_feature_directory "$repo_root")")"
+}
+
 # ═══════════════════════════ active_version.json ════════════════════════════
 # PER-FEATURE state at <feature_dir>/active_version.json:
 #   {feature, version, active_change, updated}
@@ -1938,7 +2078,7 @@ cmd_detect_project() {
     local repo_root; repo_root=$(get_repo_root)
     local -a markers=()
     local scope="repo" start="$repo_root" rel
-    # A lane's source path arrives as the value declare stored, so it may carry a
+    # A lane root folder arrives as the value declare stored, so it may carry a
     # trailing slash; an option label ("path  — why") never reaches a script argument.
     rel="${scope_root#./}"; rel="${rel%/}"
     if [ -n "$rel" ] && [ -d "$repo_root/$rel" ]; then
@@ -1971,10 +2111,12 @@ cmd_detect_project() {
 # they scaffold. Names are unique across stacks, so callers pass a bare <Name> and
 # the lookup searches every stack.
 
-# Echo "<stack>/<Name>" for each foundation directory, one per line. A stack also
-# holds siblings that are not foundations (components/), so carrying a *.pack.txt is
-# what makes a directory one — without that test they surface as bundle-less
-# foundations in every lookup.
+# Echo "<stack>/<Name>" for each PACK foundation directory, one per line — the scan
+# foundation-locate and foundation-unpack resolve a pack name through. A stack also holds
+# siblings that are not foundations (components/), so carrying a *.pack.txt is what makes
+# a directory one here — without that test they surface as bundle-less foundations in
+# every lookup. A directory carrying only *.spec.txt is listed by foundation-list
+# (aw-foundation.py) and never unpacked, so it is deliberately absent from this scan.
 _foundation_dirs() {
     local repo_root="$1" s d
     [ -d "$repo_root/foundations" ] || return 0
@@ -1997,98 +2139,147 @@ _foundation_stack() {
 }
 
 # ──────────────────────────── foundation-list ──────────────────────────────
-# Enumerate available foundations (foundations/<stack>/<Name>/ that carry a real
-# <Name>.pack.txt) so the workflow can let the user PICK one — deterministic, no LLM. An optional
-# --args "<Foundation> <App>" is parsed as a direct-argument fast path:
-# preselect_name is echoed back only when it names a real foundation; preselect_app
-# carries any 2nd token through (empty otherwise).
+# What ONE lane can be scaffolded from, as a pick list — deterministic, no LLM. Every
+# pack (<Name>.pack.txt) and every spec (*.spec.txt) under foundations/<ecosystem>/<Name>/
+# that fits the lane, then "[manual spec]" and "[skip]". The scan, the header filters
+# (# kind / # profiles) and the option labels live in aw-foundation.py so the two shells
+# answer from one implementation.
+#
+# WHICH entries a lane may be offered. A pack is a whole compiling project in one
+# ecosystem's build system, and an ecosystem is shared by stacks that cannot use each
+# other's scaffold, so three filters apply: --ecosystem (the lane's), --kind (backend |
+# frontend; an entry with no `# kind:` is backend) and --profile (only when the entry
+# names profiles). Without --ecosystem the filter falls back to every declared lane's
+# ecosystem, and to nothing at all on a bare repo; an EMPTY --ecosystem filters to none.
 #
-# A THIRD token is no longer an output directory. A scaffold lands in the source path of
-# the lane it is scaffolding, which is the only thing that keeps generated code inside a
-# declared lane, so there is no caller-chosen destination left to accept. It comes back as
-# `rejected_out` for the workflow to refuse by name rather than be silently ignored —
-# a path argument that is quietly dropped is how someone believes they scaffolded a
-# sandbox and finds they overwrote their service.
+# --args "<Foundation> <App>" is the direct-argument fast path: preselect_option is the
+# option for that name when this lane offers it; preselect_app carries the 2nd token. A
+# THIRD token comes back as `rejected_out` — a scaffold lands in its lane root folder,
+# so there is no caller-chosen destination to accept, and the workflow refuses it by name.
 cmd_foundation_list() {
-    local raw="" eco_filter=""
+    local -a fwd=()
+    local eco_given=false
     while [ $# -gt 0 ]; do
         case "$1" in
-            --args) raw="$2"; shift 2 ;;
-            --ecosystem) eco_filter="$2"; shift 2 ;;
-            --help|-h) echo "foundation-list [--args '<Foundation> <App>'] [--ecosystem <eco>]  -> {foundations[], count, preselect_name, preselect_app, rejected_out}"; return 0 ;;
+            --args|--kind|--profile|--lane-id) fwd+=("$1" "$2"); shift 2 ;;
+            --ecosystem) fwd+=(--ecosystem "$2"); eco_given=true; shift 2 ;;
+            --help|-h) echo "foundation-list [--kind backend|frontend] [--profile <id>] [--ecosystem <eco>] [--lane-id <id>] [--args '<Foundation> <App>']  -> {options[], entries[], count, foundations[], specs[], all_foundations[], preselect_option, preselect_name, preselect_app, rejected_out}"; return 0 ;;
             *) echo "foundation-list: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    local repo_root; repo_root=$(get_repo_root)
-
-    # WHICH foundations this repo may be offered. A foundation bundle is a whole
-    # compiling project in one ecosystem's languages and build system, so unpacking
-    # a .NET one into a Spring repo does not produce a scaffold — it produces a
-    # second, foreign project beside the real one.
-    #
-    # --ecosystem narrows to the ONE lane being scaffolded, which is stricter than the
-    # union of every declared lane: a repo with a .NET service and a Node UI must not be
-    # offered its .NET bundle while the UI lane is the target. Without it the filter falls
-    # back to every declared lane's ecosystem, and to nothing at all on a bare repo.
-    local -a lane_ecos=()
-    local e
-    if [ -n "$eco_filter" ]; then
-        lane_ecos=("$eco_filter")
-    else
-        while IFS= read -r e; do [ -n "$e" ] && lane_ecos+=("$e"); done < <(_aw_ecosystems)
+    if [ "$eco_given" = false ]; then
+        local e
+        while IFS= read -r e; do [ -n "$e" ] && fwd+=(--ecosystem "$e"); done < <(_aw_ecosystems)
     fi
+    _aw_foundation_py list "${fwd[@]}"
+}
 
-    local -a foundations=() all=() eco_of=()
-    local rel name eco keep
-    while IFS= read -r rel; do
-        name="${rel##*/}"; eco="${rel%%/*}"
-        [ -f "$repo_root/foundations/$rel/$name.pack.txt" ] || continue   # the primary pack (excludes Reference-only dirs)
-        all+=("$name"); eco_of+=("$eco")
-        keep=true
-        if [ ${#lane_ecos[@]} -gt 0 ]; then
-            keep=false
-            for e in "${lane_ecos[@]}"; do [ "$e" = "$eco" ] && keep=true; done
-        fi
-        [ "$keep" = true ] && foundations+=("$name")
-    done < <(_foundation_dirs "$repo_root")
-    # Optional direct-argument fast path: "<FoundationName> <AppName>".
-    local pre_name="" pre_app="" rejected_out=""
-    if [ -n "$raw" ]; then
-        # shellcheck disable=SC2086
-        set -- $raw
-        [ -n "${1:-}" ] && pre_name="$1"; [ -n "${2:-}" ] && pre_app="$2"; [ -n "${3:-}" ] && rejected_out="$3"
+# ─────────────────────────── foundation-choice ─────────────────────────────
+# Resolve the option picked from foundation-list back to its entry: route (pack | spec |
+# manual | skip), name and file. Takes the same filters as the list, so a numbered answer
+# counts the same rows the operator saw.
+cmd_foundation_choice() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --selection|--kind|--profile|--ecosystem) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-choice --selection <option> [--kind <k>] [--profile <id>] [--ecosystem <eco>]  -> {ok, route, name, file, ecosystem, title, reason}"; return 0 ;;
+            *) echo "foundation-choice: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py choice "${fwd[@]}"
+}
+
+# ────────────────────────── foundation-spec-capture ────────────────────────
+# Copy the spec a lane is about to be built from to .appweaver/foundation/<lane>.spec.md
+# — from a bundle's *.spec.txt (--file), or from what the operator gave (--input: a path
+# when it names a file, the spec text otherwise). Always exits 0; `ok` carries the verdict.
+# Also returns the lane settings the spec's header gives (contract_run, contract, client),
+# with `<App>` replaced by --app.
+cmd_foundation_spec_capture() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --lane|--kind|--file|--input|--app) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>) [--app <App>]  -> {ok, spec_path, source, chars, title, reason, contract_run, contract, client, settings_text}"; return 0 ;;
+            *) echo "foundation-spec-capture: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py spec-capture "${fwd[@]}"
+}
+
+# ─────────────────────────── foundation-lane-files ─────────────────────────
+# What a lane already holds: its lane root folder, its test path when that is another
+# subtree, and its build files where its commands run when that is outside the lane (the
+# profile's `detect` entries with no `/`). Build output and dependency directories are
+# named, not walked. Asked before anything is scaffolded into the lane.
+cmd_foundation_lane_files() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --source|--test|--workdir|--profile) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-lane-files --source <p> [--test <p>] [--workdir <p>] [--profile <id>]  -> {has_files, count, sample[], generated[], root_files[], folders[], workdir, summary}"; return 0 ;;
+            *) echo "foundation-lane-files: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py lane-files "${fwd[@]}"
+}
+
+# ─────────────────────── foundation-snapshot / -outside ────────────────────
+# A spec build is told to write only inside its lane root folder; these check that it did.
+# `snapshot` records every file in the repo before the build; `outside` lists what was
+# created, changed or deleted anywhere else afterwards and, with --undo, removes what was
+# created. Build output and dependency folders are one entry each, not walked.
+cmd_foundation_snapshot() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --out) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-snapshot --out <repo-relative file>  -> {ok, snapshot, entries}"; return 0 ;;
+            *) echo "foundation-snapshot: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py snapshot "${fwd[@]}"
+}
+
+cmd_foundation_outside() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --snapshot|--lane) fwd+=("$1" "$2"); shift 2 ;;
+            --undo) fwd+=("$1"); shift ;;
+            --help|-h) echo "foundation-outside --snapshot <file> --lane <lane root folder> [--undo]  -> {clean, created[], changed[], deleted[], removed[], summary}"; return 0 ;;
+            *) echo "foundation-outside: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py outside "${fwd[@]}"
+}
+
+_aw_foundation_py() {
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-foundation.py"
+    if [ ! -f "$core" ]; then
+        echo "aw-foundation: core not found at $core" >&2; return 1
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "aw-foundation: python3 is required to list foundations" >&2; return 1
     fi
-    # Only preselect a name that actually names an available foundation.
-    local match="" f
-    for f in "${foundations[@]}"; do [ "$f" = "$pre_name" ] && match="$pre_name"; done
-    printf '{"foundations":%s,"count":%s,"all_foundations":%s,"all_count":%s,"ecosystems":%s,"lane_ecosystems":%s,"filtered":%s,"preselect_name":"%s","preselect_app":"%s","rejected_out":"%s"}\n' \
-        "$(json_str_array "${foundations[@]}")" "${#foundations[@]}" \
-        "$(json_str_array "${all[@]}")" "${#all[@]}" \
-        "$(json_str_array "${eco_of[@]}")" "$(json_str_array "${lane_ecos[@]}")" \
-        "$([ ${#lane_ecos[@]} -gt 0 ] && echo true || echo false)" \
-        "$(json_escape "$match")" "$(json_escape "$pre_app")" "$(json_escape "$rejected_out")"
+    python3 "$core" --repo "$repo_root" "$@"
 }
 
 # ─────────────────────────── foundation-locate ─────────────────────────────
 # Parse/validate args, locate the pack + unpacker, read the pack header (bounded).
 cmd_foundation_locate() {
-    local name="" app="" out="." raw=""
+    local name="" app="" out="."
     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 ;;
+            --help|-h) echo "foundation-locate --name <F> --app <A> [--out <dir>]"; return 0 ;;
             *) echo "foundation-locate: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    # positional parse: "<FoundationName> <AppName> [OutputDir]"
-    if [ -n "$raw" ]; then
-        # shellcheck disable=SC2086
-        set -- $raw
-        [ -n "$1" ] && name="$1"; [ -n "$2" ] && app="$2"; [ -n "$3" ] && out="$3"
-    fi
     local repo_root; repo_root=$(get_repo_root)
     # available = every foundation dir (_foundation_dirs already requires a *.pack.txt)
     local -a available=()
@@ -2098,7 +2289,7 @@ cmd_foundation_locate() {
     done < <(_foundation_dirs "$repo_root")
     _fnd_fail() { printf '{"ok":false,"reason":"%s","available":%s}\n' "$(json_escape "$1")" "$(json_str_array "${available[@]}")"; }
     if [ -z "$name" ] || [ -z "$app" ]; then
-        _fnd_fail "Usage: /aw-spec-foundation <FoundationName> <AppName> [OutputDirectory]"; return 0
+        _fnd_fail "foundation-locate needs --name <FoundationName> and --app <AppName>"; return 0
     fi
     local stack; stack=$(_foundation_stack "$repo_root" "$name")
     if [ -z "$stack" ]; then _fnd_fail "Foundation '$name' not found (expected foundations/<stack>/$name/)"; return 0; fi
@@ -2113,7 +2304,7 @@ cmd_foundation_locate() {
     elif [ -f "$fdir/unpack-foundation.sh" ]; then
         runner="sh"; unpacker="$rel/unpack-foundation.sh"
     else
-        emit_fail "No unpacker found in $rel/ (unpack-foundation.ps1 or .sh)"; return 0
+        _fnd_fail "No unpacker found in $rel/ (unpack-foundation.ps1 or .sh)"; return 0
     fi
     # bounded header read (never load the pack body)
     local header sentinel file_count
@@ -2122,17 +2313,21 @@ cmd_foundation_locate() {
     file_count=$(printf '%s\n' "$header" | grep -iE 'file' | grep -oE '[0-9]+' | head -1)
     [ -n "$file_count" ] || file_count="0"
 
-    printf '{"ok":true,"reason":"","name":"%s","stack":"%s","app":"%s","out_dir":"%s","pack_file":"%s","unpacker":"%s","runner":"%s","sentinel":"%s","file_count":%s,"available":%s}\n' \
+    # A reference sample is offered only when its pack is there to unpack.
+    local has_reference=false
+    [ -f "$fdir/$name.Reference.pack.txt" ] && has_reference=true
+
+    printf '{"ok":true,"reason":"","name":"%s","stack":"%s","app":"%s","out_dir":"%s","pack_file":"%s","unpacker":"%s","runner":"%s","sentinel":"%s","file_count":%s,"has_reference":%s,"available":%s}\n' \
         "$(json_escape "$name")" "$(json_escape "$stack")" "$(json_escape "$app")" "$(json_escape "$out")" "$(json_escape "$rel/$name.pack.txt")" \
-        "$(json_escape "$unpacker")" "$runner" "$(json_escape "$sentinel")" "$file_count" "$(json_str_array "${available[@]}")"
+        "$(json_escape "$unpacker")" "$runner" "$(json_escape "$sentinel")" "$file_count" "$has_reference" "$(json_str_array "${available[@]}")"
 }
 
 # ─────────────────────────── foundation-unpack ─────────────────────────────
 # Run the OS-selected unpacker for the foundation (or reference) pack.
 #
-# --out is the LANE'S SOURCE PATH, so every file a pack carries lands inside the subtree
+# --out is the LANE ROOT FOLDER, so every file a pack carries lands inside the subtree
 # its lane owns. --test-path is the lane's other subtree: a pack that carries its own test
-# project puts it under the source path like everything else, and aw-foundation.py lifts it
+# project puts it under the lane root folder like everything else, and aw-foundation.py lifts it
 # onto the path the lane actually keeps tests in. See that module for when it is a no-op.
 cmd_foundation_unpack() {
     local name="" app="" out="." dry=false force="no" reference=false test_path=""
@@ -2206,27 +2401,49 @@ cmd_foundation_unpack() {
         "$(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="."
+# ───────────────────── foundation-rules / -rules-done ──────────────────────
+# A pack's rule file (<pack name>.rules.json beside it) names the files and folders that
+# are merged with, or replaced over, what the lane already holds; every other pack file is
+# written as packed. `rules` runs before an unpack: it lists the merges and puts the files
+# they merge with aside under --state; `rules-done` removes them once merged. Both
+# delegate to aw-foundation.py.
+cmd_foundation_rules() {
+    local -a fwd=()
     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 ;;
+            --name|--app|--out|--state) fwd+=("$1" "$2"); shift 2 ;;
+            --reference) fwd+=("$1"); shift ;;
+            --help|-h) echo "foundation-rules --name <F> --app <A> --out <lane root folder> [--reference] [--state <folder>]  -> {ok, reason, rules_file, rules, merges[], merge_count, stale[], note}"; return 0 ;;
+            *) echo "foundation-rules: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    local repo_root; repo_root=$(get_repo_root)
-    [[ "$out" != /* ]] && out="$repo_root/$out"
-    # Searched from the unpack root itself, which IS the lane's source path — a `src/`
-    # segment underneath it is the old repo-root layout and is not there any more.
-    local ctx; ctx=$(find "$out" -name "ApplicationDbContext.cs" 2>/dev/null | head -1)
-    if [ -z "$ctx" ]; then printf '{"found":false,"dbcontext":"","backup":""}\n'; return 0; fi
-    local bak="$ctx.foundation.bak"
-    cp "$ctx" "$bak"
-    printf '{"found":true,"dbcontext":"%s","backup":"%s"}\n' "$(json_escape "$ctx")" "$(json_escape "$bak")"
+    _aw_foundation_py rules "${fwd[@]}"
+}
+
+cmd_foundation_rules_done() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --state) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-rules-done [--state <folder>]  -> {ok, removed}"; return 0 ;;
+            *) echo "foundation-rules-done: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py rules-done "${fwd[@]}"
+}
+
+# A pack's lane settings (<pack name>.lane.json beside it), sentinel renamed — what
+# foundation records on the lane with lane-set once the pack is unpacked.
+cmd_foundation_pack_lane() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --name|--app) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-pack-lane --name <F> --app <A>  -> {found, file, contract_run, contract, client, reason}"; return 0 ;;
+            *) echo "foundation-pack-lane: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py pack-lane "${fwd[@]}"
 }
 
 # ─────────────────────────── foundation-verify ─────────────────────────────
@@ -2246,9 +2463,11 @@ cmd_foundation_verify() {
     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).
+        # .pack.txt legitimately contains the sentinel). -F: the sentinel is literal
+        # text, and as a pattern its dots match any character ("AppWeaver Foo" would
+        # count as AppWeaver.Foo) — the PowerShell twin uses -SimpleMatch for the same.
         while IFS= read -r m; do [ -n "$m" ] && residue+=("$m"); done < <(
-            grep -rIl --exclude-dir=.git --exclude-dir=guardrails --exclude-dir=foundations --exclude-dir=.appweaver \
+            grep -rIlF --exclude-dir=.git --exclude-dir=guardrails --exclude-dir=foundations --exclude-dir=.appweaver \
                  --exclude-dir=specs --exclude-dir=node_modules -- "$sentinel" "$out" 2>/dev/null \
                  | sed "s#^$repo_root/##" | head -50 )
     fi
@@ -2743,7 +2962,7 @@ cmd_find_host_project() {
     done
     local repo_root; repo_root=$(get_repo_root)
     local prog
-    # WHERE the host lives. The service lane's declared source path when there is one,
+    # WHERE the host lives. The declared lane root folder of the service lane when there is one,
     # `src/` when there is not — the same question run-migrate asks, and the same answer.
     # A repo whose service sits in `backend/` or `Legacy/App/` is searched where its code
     # actually is instead of being reported as having no host project at all.
@@ -3061,10 +3280,15 @@ except Exception:
 }
 
 cmd_build_compile() {
+    # --kind builds ONE declared lane — what `foundation` uses to check the lane it just
+    # created without compiling a lane it did not touch. Ignored on the undeclared ladder
+    # below, which has no lanes to choose between.
+    local kind=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) shift 2 ;;
-            --help|-h) echo "build-compile [--feature-dir <path>]"; return 0 ;;
+            --kind) kind="$2"; shift 2 ;;
+            --help|-h) echo "build-compile [--feature-dir <path>] [--kind backend|frontend]"; return 0 ;;
             *) echo "build-compile: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3074,7 +3298,11 @@ cmd_build_compile() {
     # sniffer takes the first toolchain it finds and silently never builds the
     # second, which reports green for a frontend that was never compiled.
     if [ -n "$(_aw_lanes_declared)" ]; then
-        _aw_stack_py run-phase --phase build
+        if [ -n "$kind" ]; then
+            _aw_stack_py run-phase --phase build --kind "$kind"
+        else
+            _aw_stack_py run-phase --phase build
+        fi
         return $?
     fi
 
@@ -3283,8 +3511,8 @@ print(json.dumps({"ok": bool(d.get("ok")), "tool": "lanes", "ran": bool(d.get("r
         return 0
     fi
 
-    # WHERE to look for the migration project. The service lane's declared source
-    # path when there is one, `src/` when there is not. Migrations belong to the
+    # WHERE to look for the migration project. The declared lane root folder of the
+    # service lane when there is one, `src/` when there is not. Migrations belong to the
     # backend lane by definition, so a repo whose service code sits in `Legacy/App/`
     # or `backend/` gets searched where its code actually is instead of being told
     # it has no .NET project at all.
@@ -3297,7 +3525,7 @@ print(json.dumps({"ok": bool(d.get("ok")), "tool": "lanes", "ran": bool(d.get("r
     if ls "$repo_root"/*.sln >/dev/null 2>&1 || find "$svc_dir" -maxdepth 4 -name "*.csproj" 2>/dev/null | grep -q .; then has_dotnet=true; fi
     if [ "$has_dotnet" = true ] && command -v dotnet >/dev/null 2>&1 && ( cd "$repo_root" && dotnet ef --version >/dev/null 2>&1 ); then
         # Prefer *Service.csproj (API host with ApplicationDbContext); fall back to first
-        # non-AppHost/Web/ServiceDefaults/test project under the service lane's root.
+        # non-AppHost/Web/ServiceDefaults/test project under the service lane root folder.
         local project=""
         project=$(find "$svc_dir" -maxdepth 3 -name '*.Service.csproj' 2>/dev/null | head -1)
         if [ -z "$project" ]; then
@@ -5051,10 +5279,15 @@ case "$sub" in
     lane-resolve)     cmd_lane_resolve "$@" ;;
     lane-verify)      cmd_lane_verify "$@" ;;
     lane-probe)       cmd_lane_probe "$@" ;;
+    lane-set)         cmd_lane_set "$@" ;;
+    contract-export)  cmd_contract_export "$@" ;;
+    contract-client)  cmd_contract_client "$@" ;;
+    contract-check)   cmd_contract_check "$@" ;;
     list-contexts)    cmd_list_contexts "$@" ;;
     set-context)      cmd_set_context "$@" ;;
     list-features)    cmd_list_features "$@" ;;
     set-feature)      cmd_set_feature "$@" ;;
+    default-scope)    cmd_default_scope "$@" ;;
     version-read)     cmd_version_read "$@" ;;
     version-init)     cmd_version_init "$@" ;;
     version-bootstrap-done) cmd_version_bootstrap_done "$@" ;;
@@ -5095,10 +5328,17 @@ case "$sub" in
     checklist-apply)  cmd_checklist_apply "$@" ;;
     detect-project)   cmd_detect_project "$@" ;;
     foundation-list)  cmd_foundation_list "$@" ;;
+    foundation-choice) cmd_foundation_choice "$@" ;;
+    foundation-spec-capture) cmd_foundation_spec_capture "$@" ;;
+    foundation-lane-files) cmd_foundation_lane_files "$@" ;;
+    foundation-snapshot) cmd_foundation_snapshot "$@" ;;
+    foundation-outside) cmd_foundation_outside "$@" ;;
     foundation-locate) cmd_foundation_locate "$@" ;;
     foundation-unpack) cmd_foundation_unpack "$@" ;;
     foundation-verify) cmd_foundation_verify "$@" ;;
-    foundation-stash-dbcontext) cmd_foundation_stash_dbcontext "$@" ;;
+    foundation-rules) cmd_foundation_rules "$@" ;;
+    foundation-rules-done) cmd_foundation_rules_done "$@" ;;
+    foundation-pack-lane) cmd_foundation_pack_lane "$@" ;;
     list-components)  cmd_list_components "$@" ;;
     component-catalog) cmd_component_catalog "$@" ;;
     component-verify) cmd_component_verify "$@" ;;