aw-spec-cli 0.1.28 → 0.1.30

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

@@ -37,22 +37,39 @@
 #                    (SOLE WRITER of .appweaver/stacks.json; callers = select-stack, onboard)
 #   lane-resolve     [--kind <k>] [--id <lane>] [--feature-dir <path>]
 #                                                  -> {declared, lanes[], found, lane, root, source_path, build, test, run,
-#                                                      backend_*/frontend_* (declared, root, source_path, root_exists, build, test, run,
-#                                                      feature_excluded), feature_lanes[], prototype}
+#                                                      backend_*/frontend_* (declared, working, root, source_path, root_exists,
+#                                                      build, test, run, feature_excluded), feature_lanes[], prototype,
+#                                                      working_lane, working_kind, working_kinds[], working_root, working_test_path}
 #                    (absence is a valid state: no stacks.json -> declared:false, exit 0;
-#                     --feature-dir reports a lane the feature records no surface in as not declared)
-#   lane-verify      [--require backend|frontend]… [--allow-missing-root] [--command <phase>]
-#                                                  -> {ok, declared, issues[], issue_count, message, backend_*/frontend_*}
+#                     --feature-dir reports a lane the feature records no surface in as not declared;
+#                     *_working = declared AND in this developer's .appweaver/lane.json)
+#   lane-verify      [--require backend|frontend]… [--allow-missing-root] [--working-only] [--command <phase>]
+#                                                  -> {ok, declared, issues[], issue_count, message, backend_*/frontend_*, working_*}
 #                    (the GATE: is the declaration usable for the phase about to run.
-#                     Always exits 0 — the workflow's verify_context owns the stop)
+#                     Always exits 0 — the workflow's verify_context owns the stop;
+#                     --working-only checks on disk only the working lanes' root folders)
+#   lane-select      [--lane backend|frontend|both] [--default] [--preselect <text>]
+#                                                  -> {lane, kinds[], source, note, default, select_options[], preselect, written}
+#                    (the developer's WORKING lane in .appweaver/lane.json, not committed;
+#                     --default = both when both lanes are declared, else the one that is)
 #   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}
+#   contract-draft   --feature-dir <p>             -> {ok, written, removed, path, plan, operations, ids[], ids_csv, unread_count, reason}
+#                    (the feature's api-draft.json, drafted by script from its backend plan's API section)
+#   contract-combine                               -> {ok, doc, export, export_exists, drafts[], added, added_csv, served_csv, clashes_csv, status, reason}
+#                    (.appweaver/contracts/openapi.combined.json: the export plus every drafted operation it does not serve)
+#   contract-requests --feature-dir <p>            -> {count, open_count, open_csv, declined_csv, rebind_csv, backend_text, frontend_text, summary, requests[]}
+#                    (the frontend plan's RQ-n requests and the backend plan's answers)
+#   contract-client  [--doc <d>]                   -> run-phase result for the frontend lane's `client` command ({{contract}} = --doc)
+#   contract-check   --plan <p> [--doc <d>]        -> {ok, cited, ids[], missing[], drafted[], uncited, doc_exists, reason}
+#   contract-impact  --delta-backend <p> --frontend-plan <p> [--delta-frontend <p>]
+#                                                  -> {changes[], affected[], addressed[], unaddressed[], unaddressed_csv, warn}
+#                    (operations a change's service delta changes or removes that the frontend binds to,
+#                     with no matching change in its frontend delta plan)
 #   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}
@@ -114,7 +131,8 @@
 #   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,
+#   test-run         [--feature-dir <path>] [--scope slice|repo] [--also <csv>]… [--kind backend|frontend]
+#                                                  -> {ok, tool, ran, cmd, log_tail,
 #                                                      failing_excerpt, failing_lanes[],
 #                                                      no_setup, setup_reason, setup_missing[]}
 #                    (failing_excerpt = the lines that NAME the failure, per failing lane;
@@ -125,17 +143,32 @@
 #                                                  -> {cr_id, cr_dir, delta_spec, delta_model, wave, open_count, created,
 #                                                      created_on, base_version, base_context_version}
 #   cr-list          [--feature-dir <path>] [--preselect <cr-id|main|new>] [--include-main] [--include-new]
-#                                                  -> {changes[], ids[], count, select_options[], matched_label, main_label,
-#                                                      new_label, only_id, active_change}
+#                    [--lane backend|frontend|both]
+#                                                  -> {changes[] (each with lanes[], lanes_recorded), ids[], count,
+#                                                      select_options[], matched_label, main_label, new_label, only_id,
+#                                                      active_change, lane_filter[], hidden_ids[], hidden_count,
+#                                                      hidden_ids_csv, preselect_hidden}
+#                    (--lane lists only the changes touching one of those lanes; none = every open change)
 #   cr-paths         --cr-id <id> [--feature-dir <path>]
 #                                                  -> {cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan,
-#                                                      wave, predecessor_files[], predecessor_specs[], predecessor_docs[],
-#                                                      sibling_files[], domain_model}
+#                                                      wave, lanes[], lanes_csv, lanes_recorded, touches_backend,
+#                                                      touches_frontend, predecessor_files[], predecessor_specs[],
+#                                                      predecessor_docs[], sibling_files[], domain_model}
 #   cr-overlap       --cr-id <id> [--feature-dir <path>]
 #                                                  -> {aggregates[], overlaps[], overlap_count, predecessor_overlaps,
 #                                                      sibling_overlaps, successor_overlaps, overlap_report}
 #   cr-activate      --cr-id <id> [--feature-dir <path>]  -> {active_change, activated, open_changes[]}
 #   cr-wave          --cr-id <id> --wave <n> [--feature-dir <path>]  -> {cr_id, wave, stamped}
+#   cr-lanes         [--cr-id <id> [--feature-dir <path>] [--stamp] [--set both|backend|frontend]]
+#                                                  -> {select_options[], has_options, default, recorded, recorded_kinds[],
+#                                                      lanes[], lanes_csv, backend, frontend, source, stamped}
+#                    (the lanes a change touches, on its delta-spec's **Lanes** line; no line = every declared lane)
+#   slice-gate-stamp --cr-id <id> --lane backend|frontend [--feature-dir <path>] [--tests-green true|false]
+#                    [--tests-ran true|false] [--requirements-ok true|false] [--findings <json list>]
+#                                                  -> {file, lane, cr_id, verdict, tests_green, tests_ran,
+#                                                      requirements_ok, findings, high_findings, gated}
+#                    (one lane's analyze-slice-delta result, as changes/<id>/.aw-slice-gate.<lane>.json;
+#                     pass = no test failed and the requirements met, tests_ran = a suite actually ran)
 #   cr-archive       --cr-id <id> [--feature-dir <path>] [--recall] [--reason <text>]
 #                                                  -> {ok, archived_dir, archived_model, recalled,
 #                                                      recall_marker, version, previous,
@@ -858,10 +891,11 @@ cmd_lane_set() {
     _aw_stack_py set "${fwd[@]}"
 }
 
-# ─────────────── contract-export / contract-client / contract-check ───────────────
+# ─────────────── contract-export / -draft / -combine / -requests / -client / -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.
+# running service, draft a feature's document from its backend plan, combine the two for
+# the frontend, read the request ledger between the plans, generate the frontend lane's
+# client, and check the operation ids a frontend plan cites. All delegate to aw-stack.py.
 cmd_contract_export() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
@@ -874,14 +908,53 @@ cmd_contract_export() {
     _aw_stack_py contract-export "${fwd[@]}"
 }
 
+cmd_contract_draft() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --help|-h) echo "contract-draft --feature-dir <path>  -> {ok, written, removed, path, plan, operations, ids, ids_csv, unread_count, reason}"; return 0 ;;
+            *) echo "contract-draft: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-draft "${fwd[@]+"${fwd[@]}"}"
+}
+
+cmd_contract_combine() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "contract-combine  -> {ok, doc, export, export_exists, drafts, added, added_csv, served_csv, clashes_csv, status, reason}"; return 0 ;;
+            *) echo "contract-combine: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-combine
+}
+
+cmd_contract_requests() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --help|-h) echo "contract-requests --feature-dir <path>  -> {count, open_count, open_csv, declined_csv, rebind_csv, backend_text, frontend_text, summary, requests}"; return 0 ;;
+            *) echo "contract-requests: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-requests "${fwd[@]+"${fwd[@]}"}"
+}
+
+# --doc names the document `{{contract}}` stands for in the lane's `client` command — the
+# combined document, from implement. Without it, the exported one. An empty --doc is
+# dropped, so a workflow can render the argument whole.
 cmd_contract_client() {
+    local -a fwd=()
     while [ $# -gt 0 ]; do
         case "$1" in
-            --help|-h) echo "contract-client  -> run-phase --phase client for the frontend lane"; return 0 ;;
+            --doc) if [ -n "$2" ]; then fwd+=("--contract" "$2"); fi; shift 2 ;;
+            --help|-h) echo "contract-client [--doc <api document>]  -> 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
+    _aw_stack_py run-phase --phase client --kind frontend "${fwd[@]+"${fwd[@]}"}"
 }
 
 cmd_contract_check() {
@@ -896,6 +969,21 @@ cmd_contract_check() {
     _aw_stack_py contract-check "${fwd[@]}"
 }
 
+# What a change's service delta changes or removes that the frontend master plan binds to,
+# and whether the change's frontend delta plan carries it. Each path is forwarded only when
+# it is not empty.
+cmd_contract_impact() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --delta-backend|--frontend-plan|--delta-frontend) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --help|-h) echo "contract-impact --delta-backend <p> --frontend-plan <p> [--delta-frontend <p>]  -> {changes[], changed_csv, affected[], addressed[], unaddressed[], unaddressed_count, unaddressed_csv, warn}"; return 0 ;;
+            *) echo "contract-impact: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-impact "${fwd[@]+"${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 lane root folder whether or not it was required, because a stack
@@ -916,13 +1004,32 @@ cmd_lane_verify() {
             # --flag=value: --command carries a phase name that starts with '/'.
             --command) fwd+=("--command=$2"); shift 2 ;;
             --allow-missing-root) fwd+=("--allow-missing-root"); shift ;;
-            --help|-h) echo "lane-verify [--require backend|frontend]… [--allow-missing-root] [--command <phase>]"; return 0 ;;
+            --working-only) fwd+=("--working-only"); shift ;;
+            --help|-h) echo "lane-verify [--require backend|frontend]… [--allow-missing-root] [--working-only] [--command <phase>]"; return 0 ;;
             *) echo "lane-verify: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     _aw_stack_py verify "${fwd[@]}"
 }
 
+# The developer's WORKING lane, in .appweaver/lane.json (not committed). No argument
+# reads it and lists the answers the declared stacks offer; --lane writes one of them;
+# --default writes the default for the declared stacks (select-stack's call).
+cmd_lane_select() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            # --flag=value: --preselect carries raw user prose, and a value that starts
+            # with '-' reads as another flag when passed separately.
+            --lane|--preselect) fwd+=("$1=$2"); shift 2 ;;
+            --default) fwd+=("--default"); shift ;;
+            --help|-h) echo "lane-select [--lane backend|frontend|both] [--default] [--preselect <text>]  -> {lane, kinds[], source, note, default, select_options[], preselect, written}"; return 0 ;;
+            *) echo "lane-select: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py lane-select "${fwd[@]}"
+}
+
 # Evidence that a lane of this kind exists, from the FILE signals only: a lane in
 # stacks.json, and a stack name appearing in free prose. The authoritative signal
 # — whether the active project's technical map carries `## /aw-spec-<command>` for the
@@ -3338,13 +3445,17 @@ cmd_test_run() {
     # are computed separately — the referrer closure and the features that co-own the
     # aggregates the change touches — and the dialect cannot concatenate two variables into
     # one argument, so the caller passes each list as its own --also.
-    local feature_dir="" scope="repo" also=""
+    # --kind runs ONE declared lane's suite — the developer's working lane, so a backend
+    # developer's gate is not failed by the frontend's tests, nor its fix loop sent into
+    # the frontend's code. Empty means every declared lane, as before.
+    local feature_dir="" scope="repo" also="" kind=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir="$2"; shift 2 ;;
             --scope)       scope="$2"; shift 2 ;;
             --also)        also="${also:+$also,}$2"; shift 2 ;;
-            --help|-h) echo "test-run [--feature-dir <path>] [--scope slice|repo] [--also <csv>]...  (--also repeatable; lists union)"; return 0 ;;
+            --kind)        kind="$2"; shift 2 ;;
+            --help|-h) echo "test-run [--feature-dir <path>] [--scope slice|repo] [--also <csv>]... [--kind backend|frontend]  (--also repeatable; lists union)"; return 0 ;;
             *) echo "test-run: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3387,13 +3498,17 @@ cmd_test_run() {
     # slice run delegates and widens to the lane's whole suite, which the fence tolerates
     # by design — it over-includes rather than risking an under-scoped miss — and reports
     # scoped=false so fence_green comes from `ok` rather than from the zero-match guard.
+    # A FRONTEND-only run always delegates: the .NET path below runs the service's suite,
+    # which is not the lane being asked about.
     local use_lanes=false
+    local -a kind_args=()
+    if [ -n "$kind" ]; then kind_args=("--kind" "$kind"); fi
     if [ -n "$(_aw_lanes_declared)" ]; then
-        if [ "$scope" != "slice" ] || [ "$dotnet_present" = false ]; then use_lanes=true; fi
+        if [ "$scope" != "slice" ] || [ "$dotnet_present" = false ] || [ "$kind" = "frontend" ]; then use_lanes=true; fi
     fi
     if [ "$use_lanes" = true ]; then
         rm -f "$log"
-        _aw_stack_py run-phase --phase test | AW_SCOPE="$scope" AW_SLICES="$slices" python3 -c '
+        _aw_stack_py run-phase --phase test "${kind_args[@]}" | AW_SCOPE="$scope" AW_SLICES="$slices" python3 -c '
 import json, os, re, sys
 d = json.loads(sys.stdin.readline() or "{}")
 log, ok = d.get("log_tail", ""), bool(d.get("ok"))
@@ -3738,6 +3853,63 @@ cmd_cr_wave() {
         "$(json_escape "$dspec")" "$(json_escape "$dmodel")"
 }
 
+# ─────────────────────────────── cr-lanes ───────────────────────────────────
+# The lanes a change touches, on its delta-spec's `**Lanes**:` line. No --cr-id lists the
+# answers the declared stacks offer (both first); with --cr-id it reads that change's line,
+# and --set / --stamp write it — the way specify and plan record their answer, and the way
+# to widen or narrow an open change afterwards. The lane logic is aw-stack.py's; this
+# resolves the change to its delta-spec.
+cmd_cr_lanes() {
+    local cr_id="" fd_arg="" answer="" stamp=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --set) answer="$2"; shift 2 ;;
+            --stamp) stamp=1; shift ;;
+            --help|-h) echo "cr-lanes [--cr-id <id> [--feature-dir <path>] [--stamp] [--set both|backend|frontend]]  -> {select_options[], has_options, default, recorded, lanes[], lanes_csv, backend, frontend, source, stamped}"; return 0 ;;
+            *) echo "cr-lanes: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    local -a fwd=()
+    if [ -n "$cr_id" ]; then
+        local repo_root; repo_root=$(get_repo_root)
+        local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "cr-lanes: no feature set and no --feature-dir" >&2; return 1; }
+        fwd+=("--delta-spec" "$fd/changes/$cr_id/delta-spec.md")
+    elif [ -n "$stamp$answer" ]; then
+        echo "cr-lanes: --set and --stamp need --cr-id" >&2; return 1
+    fi
+    [ -n "$stamp" ] && fwd+=("--stamp")
+    # --flag=value: the answer may arrive as a whole option line, spaces and all.
+    [ -n "$answer" ] && fwd+=("--set=$answer")
+    _aw_stack_py cr-lanes "${fwd[@]+"${fwd[@]}"}"
+}
+
+# ─────────────────────────── slice-gate-stamp ──────────────────────────────
+# analyze-slice-delta's result for ONE lane, written into the change's directory as
+# .aw-slice-gate.<lane>.json and committed with it. The rule lives in python/aw-stack.py;
+# this resolves the change's directory and hands over.
+cmd_slice_gate_stamp() {
+    local cr_id="" fd_arg=""
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cr-id) cr_id="$2"; shift 2 ;;
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            # --flag=value: the findings are a JSON list, and any value may be empty.
+            --lane|--tests-green|--tests-ran|--requirements-ok|--findings) fwd+=("$1=$2"); shift 2 ;;
+            --help|-h) echo "slice-gate-stamp --cr-id <id> --lane backend|frontend [--feature-dir <path>] [--tests-green true|false] [--tests-ran true|false] [--requirements-ok true|false] [--findings <json list>]  -> {file, lane, cr_id, verdict, tests_green, tests_ran, requirements_ok, findings, high_findings, gated}"; return 0 ;;
+            *) echo "slice-gate-stamp: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    cr_id=$(_cr_id_token "$cr_id")
+    [ -n "$cr_id" ] || { echo "slice-gate-stamp: --cr-id is required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "slice-gate-stamp: no feature set and no --feature-dir" >&2; return 1; }
+    _aw_stack_py slice-gate-stamp --cr-dir "$fd/changes/$cr_id" --cr-id "$cr_id" "${fwd[@]+"${fwd[@]}"}"
+}
+
 # ──────────────────────────── cr-wave-derive ───────────────────────────────
 # THE WAVE A CHANGE'S OWN DOCUMENTS IMPLY, from their `## Depends on` sections.
 #
@@ -4114,15 +4286,24 @@ PY
 #                   new` resolves to it.
 # `count` and `has_changes` keep counting REAL open changes, so a caller that gates on
 # them is unaffected by either flag.
+#
+# EACH CHANGE'S LANES, from its delta-spec's `**Lanes**:` line (`lanes[]`, and
+# `lanes_recorded` false when there is no line, which means every lane). `--lane backend |
+# frontend | both` lists only the changes that touch one of those lanes; every count, id,
+# option and preselect above then covers that list alone, and `hidden_ids[]` names the open
+# changes it left out. No `--lane`, or an empty one, lists every open change. A change that
+# touches one lane only says so in its option label; the label of one touching both is
+# unchanged.
 cmd_cr_list() {
-    local feature_dir_arg="" preselect="" inc_main="" inc_new=""
+    local feature_dir_arg="" preselect="" inc_main="" inc_new="" lane=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
             --preselect) preselect="$2"; shift 2 ;;
             --include-main) inc_main="1"; shift ;;
             --include-new) inc_new="1"; shift ;;
-            --help|-h) echo "cr-list [--feature-dir <path>] [--preselect <cr-id|main|new>] [--include-main] [--include-new]  -> {changes[], ids[], count, select_options[], matched_label, main_label, new_label, active_change}"; return 0 ;;
+            --lane) lane="$2"; shift 2 ;;
+            --help|-h) echo "cr-list [--feature-dir <path>] [--preselect <cr-id|main|new>] [--include-main] [--include-new] [--lane backend|frontend|both]  -> {changes[], ids[], count, select_options[], matched_label, main_label, new_label, active_change, lane_filter[], hidden_ids[], hidden_count}"; return 0 ;;
             *) echo "cr-list: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4130,8 +4311,9 @@ cmd_cr_list() {
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "cr-list: no feature set and no --feature-dir" >&2; return 1; }
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
     AW_FD="$fd" AW_CTX="$ctx_dir" AW_ROOT="$repo_root" AW_PRE="$(_cr_id_token "$preselect")" \
-    AW_PRE_RAW="$preselect" AW_INC_MAIN="$inc_main" AW_INC_NEW="$inc_new" python3 - <<'PY'
-import json, os, re
+    AW_PRE_RAW="$preselect" AW_INC_MAIN="$inc_main" AW_INC_NEW="$inc_new" AW_LANE="$lane" \
+    AW_STACK_PY="$SCRIPT_DIR/../python/aw-stack.py" python3 - <<'PY'
+import json, os, re, sys
 fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
 pre = os.environ.get("AW_PRE", "").strip()
 # The WHOLE argument, not its first token. A cr id is matched on the token because a
@@ -4158,6 +4340,27 @@ def title_of(path):
     m = re.match(r"^#\s+.*?:\s*(.+)$", first)
     t = m.group(1).strip() if m else ""
     return "" if (not t or t.startswith("[")) else t
+# The lanes a change touches: read_change_lanes in python/aw-stack.py, the one reader of a
+# delta-spec's **Lanes** line. None when the line is missing or still the template
+# placeholder — a change touching every lane.
+import importlib.util
+try:
+    _spec = importlib.util.spec_from_file_location("aw_stack", os.environ["AW_STACK_PY"])
+    _aw_stack = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_aw_stack)
+except Exception as _e:
+    sys.stderr.write("cr-list: cannot load %s: %s\n" % (os.environ.get("AW_STACK_PY", ""), _e))
+    sys.exit(1)
+lanes_of = _aw_stack.read_change_lanes
+want = []
+for tok in re.split(r"[\s,]+", os.environ.get("AW_LANE", "").strip().lower()):
+    if not tok: continue
+    if tok == "both": want += ["backend", "frontend"]
+    elif tok in ("backend", "frontend"): want.append(tok)
+    else:
+        sys.stderr.write("cr-list: --lane takes backend, frontend or both, not '%s'\n" % tok)
+        sys.exit(1)
+want = [k for k in ("backend", "frontend") if k in want]
 tracked = []
 avp = os.path.join(fd, "active_version.json")
 active = ""
@@ -4181,6 +4384,7 @@ if os.path.isdir(changes_dir):
         wave = header(dspec, "Wave") or header(dmodel, "Wave") or "1"
         try: wave = int(re.sub(r"\D", "", wave) or 1)
         except Exception: wave = 1
+        lanes = lanes_of(dspec)
         rows.append({
             "cr_id": name, "cr_dir": rel(d), "wave": wave,
             "title": title_of(dspec),
@@ -4193,11 +4397,17 @@ if os.path.isdir(changes_dir):
             "legacy_delta_design": os.path.isfile(legacy),
             "tracked": name in tracked,
             "active": name == active,
+            "lanes": lanes or ["backend", "frontend"],
+            "lanes_recorded": lanes is not None,
         })
 rows.sort(key=lambda r: (r["wave"], r["cr_id"]))
+hidden = [r for r in rows if want and not set(r["lanes"]) & set(want)]
+hidden_set = set(r["cr_id"] for r in hidden)
+rows = [r for r in rows if r["cr_id"] not in hidden_set]
 def label(r):
     bits = [r["cr_id"], "wave %d" % r["wave"]]
     bits.append(r["title"] or "(delta-spec not authored yet)")
+    if len(r["lanes"]) == 1: bits.append("%s only" % r["lanes"][0])
     planned = [k for k, v in (("backend", r["delta_backend_plan_exists"]), ("frontend", r["delta_frontend_plan_exists"])) if v]
     if planned: bits.append("planned: " + "+".join(planned))
     return " · ".join(bits)
@@ -4229,6 +4439,12 @@ print(json.dumps({
     # The lone open change, so a caller can take it without a prompt when there is
     # nothing to choose between.
     "only_id": rows[0]["cr_id"] if len(rows) == 1 else "",
+    # What --lane left out: open changes that touch none of the lanes asked for.
+    "lane_filter": want,
+    "hidden_ids": [r["cr_id"] for r in hidden], "hidden_count": len(hidden),
+    "hidden_ids_csv": ", ".join("%s (%s only)" % (r["cr_id"], "+".join(r["lanes"])) for r in hidden),
+    # A --preselect naming one of those, so a caller can say why it was not selected.
+    "preselect_hidden": pre if (pre and not matched and pre in hidden_set) else "",
 }))
 PY
 }
@@ -4249,7 +4465,7 @@ cmd_cr_paths() {
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-paths --cr-id <id> [--feature-dir <path>]  -> {cr_id, cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan, wave, predecessor_files[], predecessor_specs[], predecessor_docs[], sibling_files[], domain_model}"; return 0 ;;
+            --help|-h) echo "cr-paths --cr-id <id> [--feature-dir <path>]  -> {cr_id, cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan, wave, lanes[], lanes_csv, lanes_recorded, touches_backend, touches_frontend, predecessor_files[], predecessor_specs[], predecessor_docs[], sibling_files[], domain_model}"; return 0 ;;
             *) echo "cr-paths: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4258,8 +4474,9 @@ cmd_cr_paths() {
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "cr-paths: no feature set and no --feature-dir" >&2; return 1; }
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
-    AW_FD="$fd" AW_CTX="$ctx_dir" AW_ROOT="$repo_root" AW_CR="$cr_id" python3 - <<'PY'
-import json, os, re, glob
+    AW_FD="$fd" AW_CTX="$ctx_dir" AW_ROOT="$repo_root" AW_CR="$cr_id" \
+    AW_STACK_PY="$SCRIPT_DIR/../python/aw-stack.py" python3 - <<'PY'
+import json, os, re, glob, sys
 fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]; cr = os.environ["AW_CR"]
 def rel(p): return os.path.relpath(p, root)
 def wave_of(path, default=1):
@@ -4274,6 +4491,19 @@ be     = os.path.join(cr_dir, "delta-backend-plan.md")
 fe     = os.path.join(cr_dir, "delta-frontend-plan.md")
 master = os.path.join(ctx, "domain-model.md")
 wave = wave_of(dspec, wave_of(dmodel, 1))
+# The lanes a change touches: read_change_lanes in python/aw-stack.py, the one reader of a
+# delta-spec's **Lanes** line. None when the line is missing or still the template
+# placeholder — a change touching every lane.
+import importlib.util
+try:
+    _spec = importlib.util.spec_from_file_location("aw_stack", os.environ["AW_STACK_PY"])
+    _aw_stack = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_aw_stack)
+except Exception as _e:
+    sys.stderr.write("cr-paths: cannot load %s: %s\n" % (os.environ.get("AW_STACK_PY", ""), _e))
+    sys.exit(1)
+recorded = _aw_stack.read_change_lanes(dspec)
+lanes = recorded or ["backend", "frontend"]
 # A change's model delta sits at CONTEXT level and its delta-spec at FEATURE level, so the
 # spec of another open change is found by walking the context's features rather than
 # assuming it belongs to this one — two features of one context can both have changes open.
@@ -4302,6 +4532,10 @@ print(json.dumps({
     "delta_backend_plan": rel(be), "delta_backend_plan_exists": os.path.isfile(be),
     "delta_frontend_plan": rel(fe), "delta_frontend_plan_exists": os.path.isfile(fe),
     "wave": wave,
+    # The lanes this change touches, from its delta-spec's **Lanes** line — every lane when
+    # it records none (lanes_recorded false).
+    "lanes": lanes, "lanes_csv": ",".join(lanes), "lanes_recorded": recorded is not None,
+    "touches_backend": "backend" in lanes, "touches_frontend": "frontend" in lanes,
     "context_dir": rel(ctx),
     "domain_model": rel(master), "domain_model_exists": os.path.isfile(master),
     # Lower wave = committed to landing first, so this delta may plan on top of it.
@@ -5051,17 +5285,24 @@ _plan_gate_file() { printf '%s/.aw-plan-gate.json' "$1"; }
 # an untagged gap included — is a plan gap. Unreadable input is one plan gap: a verdict that
 # could not be read must not pass.
 cmd_plan_gaps() {
-    local gaps=""
+    # --lanes is the developer's WORKING lanes (csv). A plan-route gap tagged with a lane
+    # outside it belongs to the developer who owns that lane: it is listed under `other`
+    # and neither drives this run's repair nor its stop. A gap routed to specify stays
+    # routed whatever lane it was found in — the spec is shared. With no --lanes every
+    # lane is worked, which is the behaviour from before the option existed.
+    local gaps="" lanes=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --gaps) gaps="$2"; shift 2 ;;
-            --help|-h) echo "plan-gaps --gaps <json list>  -> {verdict, plan_ok, plan_gaps, routed_gaps, routed[], routed_csv}"; return 0 ;;
+            --lanes) lanes="$2"; shift 2 ;;
+            --help|-h) echo "plan-gaps --gaps <json list> [--lanes backend,frontend]  -> {verdict, plan_ok, plan_gaps, routed_gaps, routed[], routed_csv, other_gaps, other[], other_csv, backend_verdict, backend_plan_gaps, backend_routed[], frontend_verdict, frontend_plan_gaps, frontend_routed[]}"; return 0 ;;
             *) echo "plan-gaps: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    AW_GAPS="$gaps" python3 - <<'PY'
+    AW_GAPS="$gaps" AW_LANES="$lanes" python3 - <<'PY'
 import json, os
 raw = (os.environ.get("AW_GAPS") or "").strip()
+lanes = [l.strip().lower() for l in (os.environ.get("AW_LANES") or "").split(",") if l.strip()]
 try:
     gaps = json.loads(raw) if raw else []
     if not isinstance(gaps, list):
@@ -5069,27 +5310,46 @@ try:
     readable = True
 except Exception:
     gaps, readable = [], False
-plan, routed = 0, []
+plan, routed, other = 0, [], []
+per = {"backend": [0, []], "frontend": [0, []]}
 for g in gaps:
     d = g if isinstance(g, dict) else {"gap": str(g)}
     text = str(d.get("gap", "")).strip()
+    lane = str(d.get("lane", "") or "").strip().lower()
+    ref = str(d.get("spec_ref", "") or "").strip()
+    line = ("%s: %s" % (ref, text)) if ref and ref != "—" else text
+    targets = [lane] if lane in per else list(per)
     if text.upper().startswith("LIFT-FAILURE") or str(d.get("route", "")).strip().lower() == "specify":
-        ref = str(d.get("spec_ref", "") or "").strip()
-        routed.append(("%s: %s" % (ref, text)) if ref and ref != "—" else text)
+        routed.append(line)
+        for t in targets:
+            per[t][1].append(line)
+    elif lanes and lane in per and lane not in lanes:
+        other.append("%s: %s" % (lane, line))
     else:
         plan += 1
+        for t in targets:
+            per[t][0] += 1
 if not readable:
     plan += 1
-verdict = "gaps" if plan else ("routed-gaps" if routed else "conformant")
-print(json.dumps({"ok": True, "readable": readable, "verdict": verdict, "plan_ok": plan == 0,
-                  "plan_gaps": plan, "routed_gaps": len(routed), "routed": routed,
-                  "routed_csv": "; ".join(routed)}))
+    for t in per:
+        per[t][0] += 1
+def verdict(p, r):
+    return "gaps" if p else ("routed-gaps" if r else "conformant")
+out = {"ok": True, "readable": readable, "verdict": verdict(plan, routed), "plan_ok": plan == 0,
+       "plan_gaps": plan, "routed_gaps": len(routed), "routed": routed,
+       "routed_csv": "; ".join(routed), "lanes": lanes,
+       "other_gaps": len(other), "other": other, "other_csv": "; ".join(other)}
+for k in ("backend", "frontend"):
+    out[k + "_verdict"] = verdict(per[k][0], per[k][1])
+    out[k + "_plan_gaps"] = per[k][0]
+    out[k + "_routed"] = per[k][1]
+print(json.dumps(out))
 PY
 }
 
 cmd_plan_gate_stamp() {
     case "${1:-}" in
-        --help|-h) echo "plan-gate-stamp [--feature-dir <path>] [--spec-version <v>] [--mode <text>] [--verdict conformant|routed-gaps|gaps] [--plan-gaps <n>] [--routed <json list>]  -> {file, gated, verdict, hashed[], count}"; return 0 ;;
+        --help|-h) echo "plan-gate-stamp [--feature-dir <path>] [--lane backend|frontend] [--spec-version <v>] [--mode <text>] [--verdict conformant|routed-gaps|gaps] [--plan-gaps <n>] [--routed <json list>]  -> {file, lane, gated, verdict, hashed[], count}"; return 0 ;;
     esac
     local feature_dir_arg="" rest=()
     while [ $# -gt 0 ]; do
@@ -5108,11 +5368,12 @@ cmd_plan_gate_stamp() {
 }
 
 cmd_plan_gate_check() {
-    local feature_dir_arg=""
+    local feature_dir_arg="" lane=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "plan-gate-check [--feature-dir <path>]  -> {tracked, gate_fresh, verdict, may_generate, plan_gaps, routed_gaps[], routed_csv, spec_moved, model_moved, plans_changed[], plans_changed_csv, gated, reason}"; return 0 ;;
+            --lane) lane="$2"; shift 2 ;;
+            --help|-h) echo "plan-gate-check [--feature-dir <path>] [--lane backend|frontend]  -> {lane, shared, tracked, gate_fresh, verdict, may_generate, plan_gaps, routed_gaps[], routed_csv, spec_moved, model_moved, plans_changed[], plans_changed_csv, gated, reason}"; return 0 ;;
             *) echo "plan-gate-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -5122,7 +5383,9 @@ cmd_plan_gate_check() {
     local core="$SCRIPT_DIR/../python/aw-plangate.py"
     if [ ! -f "$core" ]; then echo "plan-gate-check: core not found at $core" >&2; return 1; fi
     if ! command -v python3 >/dev/null 2>&1; then echo "plan-gate-check: python3 is required" >&2; return 1; fi
-    python3 "$core" check --feature-dir "$fd" --context-dir "$ctx_dir" --root "$repo_root"
+    local -a lane_args=()
+    if [ -n "$lane" ]; then lane_args=("--lane" "$lane"); fi
+    python3 "$core" check --feature-dir "$fd" --context-dir "$ctx_dir" --root "$repo_root" "${lane_args[@]+"${lane_args[@]}"}"
 }
 
 # ─────────────────────────────── gap-route ─────────────────────────────────
@@ -5280,9 +5543,14 @@ case "$sub" in
     lane-verify)      cmd_lane_verify "$@" ;;
     lane-probe)       cmd_lane_probe "$@" ;;
     lane-set)         cmd_lane_set "$@" ;;
+    lane-select)      cmd_lane_select "$@" ;;
     contract-export)  cmd_contract_export "$@" ;;
+    contract-draft)   cmd_contract_draft "$@" ;;
+    contract-combine) cmd_contract_combine "$@" ;;
+    contract-requests) cmd_contract_requests "$@" ;;
     contract-client)  cmd_contract_client "$@" ;;
     contract-check)   cmd_contract_check "$@" ;;
+    contract-impact)  cmd_contract_impact "$@" ;;
     list-contexts)    cmd_list_contexts "$@" ;;
     set-context)      cmd_set_context "$@" ;;
     list-features)    cmd_list_features "$@" ;;
@@ -5309,6 +5577,8 @@ case "$sub" in
     cr-overlap)       cmd_cr_overlap "$@" ;;
     cr-activate)      cmd_cr_activate "$@" ;;
     cr-wave)          cmd_cr_wave "$@" ;;
+    cr-lanes)         cmd_cr_lanes "$@" ;;
+    slice-gate-stamp) cmd_slice_gate_stamp "$@" ;;
     cr-wave-derive)   cmd_cr_wave_derive "$@" ;;
     cr-rebase)        cmd_cr_rebase "$@" ;;
     cr-archive)       cmd_cr_archive "$@" ;;