aw-spec-cli 0.1.21 → 0.1.22

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

@@ -1100,9 +1100,12 @@ _cr_id_token() {   # $1 = raw --cr-id value
 }
 
 # One change's wave, read from the documents that carry it: the delta-spec first, then
-# the model delta. Both are stamped together, so either answers; 1 is the floor for a
-# change opened before waves existed.
-_wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
+# the model delta. Both are stamped together, so either answers. EMPTY when neither carries
+# a readable one — `**Wave**: [N]` is the unfilled template line, so "no wave" is a state
+# that happens, and a caller who WRITES the answer somewhere must not write a number nobody
+# derived. A phantom wave is worse than none: the merge and recall fences can see that a
+# wave is missing and say so, but a 1 that was invented downstream reads to them as fact.
+_wave_of_readable() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
     local fd="$1" cr="$2" repo_root="$3" w=""
     local dspec="$fd/changes/$cr/delta-spec.md"
     local ctx_dir; ctx_dir=$(_context_dir_for_feature "$fd" "$repo_root")
@@ -1112,11 +1115,20 @@ _wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
         w=$(sed -n -E 's/^\*\*Wave\*\*:[[:space:]]*([0-9]+).*$/\1/p' "$f" | head -1)
         [ -n "$w" ] && break
     done
-    case "$w" in ''|*[!0-9]*) w=1 ;; esac
-    [ "$w" -ge 1 ] 2>/dev/null || w=1
+    case "$w" in ''|*[!0-9]*) w="" ;; esac
+    if [ -n "$w" ]; then
+        [ "$w" -ge 1 ] 2>/dev/null || w=""
+    fi
     printf '%s' "$w"
 }
 
+# The same reading with the floor applied, for the readers that must show a number — a
+# listing has a column to fill and 1 is the floor for a change opened before waves existed.
+_wave_of() {   # $1 = abs feature dir, $2 = cr id, $3 = repo_root
+    local w; w=$(_wave_of_readable "$1" "$2" "$3")
+    printf '%s' "${w:-1}"
+}
+
 # ─────────────────────────────── context-paths ─────────────────────────────
 # Everything specify needs to know about the domain model of the context it is working
 # in: where the master is, whether it exists yet, and EVERY open delta model beside it.
@@ -2564,6 +2576,25 @@ print(json.dumps({"ok": ok, "exists": True, "issues": issues,
 PY
 }
 
+# ─────────────────────────────── principles-list ───────────────────────────
+# The ratified NON-NEGOTIABLE principles. A thin wrapper: the scan lives in
+# python/aw-principles.py, which BOTH shells invoke, so the list a gate cites cannot
+# differ between them. Defaults to the two halves specify loads; --file overrides.
+cmd_principles_list() {
+    local rest=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "principles-list [--file <path>]...  -> {files[], missing[], principles[], count, titles_csv}"; return 0 ;;
+            *) rest+=("$1"); shift ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-principles.py"
+    if [ ! -f "$core" ]; then echo "principles-list: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "principles-list: python3 is required" >&2; return 1; fi
+    python3 "$core" list --root "$repo_root" "${rest[@]+"${rest[@]}"}"
+}
+
 # ────────────────────────── agent-context-update ───────────────────────────
 # Run the agent-context extension's updater (refreshes the managed AW-Spec block).
 cmd_agent_context_update() {
@@ -2924,7 +2955,14 @@ cmd_delta_plan_scaffold() {
         if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$target"; else touch "$target"; fi
         created="true"
     fi
-    _stamp_header "$target" "Wave" "$(_wave_of "$fd" "$cr_id" "$repo_root")"
+    # The lane plan carries the change's wave so a reader of the plan alone can see where it
+    # sits. It is COPIED from the delta-spec, never decided here — so when the spec has no
+    # readable wave the template's `[N]` is left standing, which is what the merge and recall
+    # fences read as "not ordered yet" and refuse on, with the command that stamps it.
+    local scaffold_wave; scaffold_wave=$(_wave_of_readable "$fd" "$cr_id" "$repo_root")
+    if [ -n "$scaffold_wave" ]; then
+        _stamp_header "$target" "Wave" "$scaffold_wave"
+    fi
     local override_active="false"
     [ -f "$repo_root/.appweaver/templates/overrides/${template_arg}.md" ] && override_active="true"
     local template_source; template_source=$(resolve_template "$template_arg" "$repo_root") || true
@@ -2997,13 +3035,17 @@ cmd_test_run() {
     #               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.
+    # --also is REPEATABLE and the lists UNION. A merge's blast radius has two halves that
+    # 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=""
     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 ;;
+            --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 ;;
             *) echo "test-run: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3493,8 +3535,12 @@ required = max([d["wave"] for d in known], default=0) + 1
 current = wave_of(cr)
 ok = current is not None and current >= required
 
+# A change with NO readable wave is stamped too, not only one sitting too low. The merge
+# and recall fences refuse on an unordered change and send the operator here, so the one
+# command they are given has to be able to write the first wave as well as correct a wrong
+# one — a remedy that declines the case it was named for is no remedy.
 stamped = []
-if stamp and current is not None and current < required:
+if stamp and (current is None or current < required):
     line = "**Wave**: %d" % required
     pat = re.compile(r"^\*\*Wave\*\*:.*$", re.M)
     for p in present:
@@ -3505,13 +3551,16 @@ if stamp and current is not None and current < required:
     if stamped:
         current, ok = required, True
 
-if not deps:
-    msg = "%s declares no predecessor, so wave %d is the floor; it carries %s" % (
-        cr, required, current if current is not None else "no wave")
-elif stamped:
+if stamped and deps:
     msg = "%s depends on %s, so it was raised to wave %d in %s" % (
         cr, ", ".join("%s (wave %s)" % (d["cr_id"], d["wave"]) for d in known),
         required, ", ".join(stamped))
+elif stamped:
+    msg = "%s declares no predecessor, so it was stamped at wave %d — the floor — in %s" % (
+        cr, required, ", ".join(stamped))
+elif not deps:
+    msg = "%s declares no predecessor, so wave %d is the floor; it carries %s" % (
+        cr, required, current if current is not None else "no wave")
 elif ok:
     msg = "%s is at wave %s, at or above the %d its `## Depends on` requires" % (
         cr, current, required)
@@ -4434,7 +4483,7 @@ cmd_cr_merge_check() {
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-merge-check --cr-id <id> [--feature-dir <path>]  -> {rebase_needed, base_version, current_version, blockers[], blocker_count, wave, …}"; return 0 ;;
+            --help|-h) echo "cr-merge-check --cr-id <id> [--feature-dir <path>]  -> {rebase_needed, base_version, current_version, blockers[], blocker_count, wave, wave_ordering_ok, unordered[], …}"; return 0 ;;
             *) echo "cr-merge-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4462,14 +4511,8 @@ def norm(v):
     if not v: return ""
     return v if v.startswith("v") else "v" + v
 
-# THIS change's own spec half and wave.
+# THIS change's own spec half.
 my_spec = os.path.join(fd, "changes", cr, "delta-spec.md")
-def wave_of(p, default=1):
-    try: t = open(p, encoding="utf-8").read()
-    except Exception: return default
-    m = re.search(r"^\*\*Wave\*\*:[ \t]*(\d+)", t, re.M)
-    return int(m.group(1)) if m else default
-wave = wave_of(my_spec)
 base_version = norm(header(my_spec, "Base version"))
 
 # The master's CURRENT version, from the ledger — the same authority version-read reports,
@@ -4486,52 +4529,65 @@ if not current:
 # absence of evidence and is not treated as a move.
 rebase_needed = bool(base_version and current and base_version != current)
 
-# EVERY open change in the context, both halves. changes/<id>/ under each feature is the
-# authority for "open"; the pending model deltas are unioned in so a model-only artifact of
-# a half-built change is still seen.
-opens = {}
-for feat in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
-    ch = os.path.join(ctx, feat, "changes")
-    if not os.path.isdir(ch): continue
-    for name in sorted(os.listdir(ch)):
-        d = os.path.join(ch, name)
-        if name == "archive" or not os.path.isdir(d): continue
-        opens.setdefault(name, {"cr_id": name, "wave": wave_of(os.path.join(d, "delta-spec.md")),
-                                "feature": feat})
-for f in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
-    m = re.match(r"^domain-model\.(.+)\.delta\.md$", f)
-    if not m: continue
-    other = m.group(1)
-    opens.setdefault(other, {"cr_id": other, "wave": wave_of(os.path.join(ctx, f)), "feature": ""})
-
-blockers = [v for k, v in sorted(opens.items()) if k != cr and v["wave"] < wave]
-
-# THE MASTERS CAN MOVE WITHOUT THE VERSION MOVING. finalize-delta merges and close-delta
-# bumps, so between the two the masters carry a change the number does not yet reflect — and
-# a second delta sharing the same base_version would compare equal and merge onto masters
-# that had already shifted under it. The proof is the Change History row finalize-delta
-# appends, carrying the id in its CR cell.
+# BOTH CONTEXT-WIDE QUESTIONS COME FROM aw-crstate, for every reader of them and for both
+# shells: which open changes this one is ordered against, and which of them have already
+# merged. Each was once a copy of the scan living in this payload and another in its
+# PowerShell twin, which is how the two came to answer the same question differently.
+#
+# PREDECESSORS. Every open change in the context, both halves — changes/<id>/ under each
+# feature is the authority for "open", and the pending model deltas are unioned in so a
+# model-only artifact of a half-built change is still seen. A change whose `**Wave**:` is
+# unreadable is reported as unordered rather than assumed to be wave 1, which is what let an
+# unstamped delta pose as a predecessor and let an unstamped SUBJECT skip this fence
+# entirely.
 #
-# aw-crstate owns that test, for every reader of it. It replaces `cr in spec.md` — which
-# fired on an id quoted in prose and matched a prefix of a longer id — and it looks where a
-# merge can actually show: this feature's spec AND the context model every feature shares,
-# so a SIBLING feature's merged-unclosed change is no longer invisible. A sibling blocks
-# only where it touched an aggregate this delta also names (`blocking`); a merge in this
-# feature blocks outright, because it moved this delta's own master.
-merged_open = []
+# MERGED-OPEN. The masters can move without the version moving: finalize-delta merges and
+# close-delta bumps, so between the two the masters carry a change the number does not yet
+# reflect, and a second delta sharing the same base_version would compare equal and merge
+# onto masters that had already shifted under it. The proof is the Change History row
+# finalize-delta appends, carrying the id in its CR cell — which replaced `cr in spec.md`,
+# a test that fired on an id quoted in prose and matched a prefix of a longer id. It looks
+# where a merge can actually show: this feature's spec AND the context model every feature
+# shares, so a SIBLING feature's merged-unclosed change is no longer invisible. A sibling
+# blocks only where it touched an aggregate this delta also names (`blocking`); a merge in
+# this feature blocks outright, because it moved this delta's own master.
+_m, _why = None, ""
 try:
     import importlib.util
     _mod_path = os.path.join(root, ".appweaver", "scripts", "python", "aw-crstate.py")
     _spec = importlib.util.spec_from_file_location("aw_crstate", _mod_path)
-    _m = importlib.util.module_from_spec(_spec)
-    _spec.loader.exec_module(_m)
-    merged_open = [r for r in _m.merged_open(ctx, fd, cr) if r["blocking"]]
+    _loaded = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_loaded)
+    _m = _loaded
 except Exception as _e:
-    # Fail CLOSED on an unreadable helper: report the state as blocking rather than clear.
-    merged_open = [{"cr_id": "(merged-open check failed: %s)" % _e, "blocking": True}]
+    _why = str(_e)
+
+order, merged_open, merged_text = None, None, ""
+if _m is not None:
+    try:
+        order = _m.wave_order(ctx, fd, cr, "lower", "context")
+        merged_open = [r for r in _m.merged_open(ctx, fd, cr) if r["blocking"]]
+        merged_text = _m.merged_open_text(merged_open)
+    except Exception as _e:
+        order, merged_open, _why = None, None, str(_e)
+
+# Fail CLOSED on an unreadable helper: report the state as blocking rather than clear, and
+# say which check could not run rather than which condition was found.
+if order is None:
+    order = {"wave": None, "wave_known": False, "related": [], "related_count": 0,
+             "related_ids": "", "unknown": [], "unknown_count": 0, "unknown_ids": "",
+             "unknown_blocks": True, "wave_ordering_ok": False,
+             "wave_problem": "the wave reader could not be run (%s), so no open change in "
+                             "this context is ordered against %s at all" % (_why, cr)}
+if merged_open is None:
+    merged_open = [{"cr_id": "(merged-open check failed: %s)" % _why, "blocking": True}]
+    merged_text = merged_open[0]["cr_id"]
+blockers = order["related"]
 
 print(json.dumps({
-    "ok": True, "cr_id": cr, "wave": wave,
+    "ok": True, "cr_id": cr,
+    "wave": order["wave"] if order["wave"] is not None else "",
+    "wave_known": order["wave_known"],
     "exists": os.path.isdir(os.path.join(fd, "changes", cr)),
     # REBASE half — the masters moved because a change CLOSED and bumped the number.
     "base_version": base_version, "current_version": current,
@@ -4540,14 +4596,20 @@ print(json.dumps({
     # PREDECESSOR half. Lower wave = committed to land first.
     "blockers": blockers, "blocker_count": len(blockers),
     "has_blockers": len(blockers) > 0,
-    "blocker_ids": ", ".join("%s (wave %d)" % (b["cr_id"], b["wave"]) for b in blockers),
+    "blocker_ids": order["related_ids"],
+    # The changes this one cannot be ordered against at all, in either direction.
+    "unordered": order["unknown"], "unordered_count": order["unknown_count"],
+    "unordered_ids": order["unknown_ids"],
+    "wave_ordering_ok": order["wave_ordering_ok"],
+    "wave_problem": order["wave_problem"],
     # The other way the masters move: a change MERGED and has not closed yet.
     "merged_open": merged_open, "merged_open_count": len(merged_open),
     "has_merged_open": len(merged_open) > 0,
-    "merged_open_ids": ", ".join(m["cr_id"] for m in merged_open),
-    # All three refusals as ONE positive flag, because the engine takes no compound condition
-    # and a gate that must read three booleans would need three passes over one question.
-    "merge_ok": (not rebase_needed) and len(blockers) == 0 and len(merged_open) == 0,
+    "merged_open_ids": merged_text,
+    # All four refusals as ONE positive flag, because the engine takes no compound condition
+    # and a gate that must read four booleans would need four passes over one question.
+    "merge_ok": (not rebase_needed) and order["wave_ordering_ok"] and len(blockers) == 0
+                and len(merged_open) == 0,
 }))
 PY
 }
@@ -4572,7 +4634,7 @@ cmd_cr_recall_check() {
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-recall-check --cr-id <id> [--feature-dir <path>]  -> {merged, dependants[], dependant_count, wave, …}"; return 0 ;;
+            --help|-h) echo "cr-recall-check --cr-id <id> [--feature-dir <path>]  -> {merged, dependants[], dependant_count, wave, wave_ordering_ok, unordered[], …}"; return 0 ;;
             *) echo "cr-recall-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4588,21 +4650,13 @@ root = os.environ.get("AW_ROOT", ""); ctx = os.environ.get("AW_CTX", "")
 changes = os.path.join(fd, "changes")
 cr_dir = os.path.join(changes, cr)
 
-def wave_of(d):
-    for name in ("delta-spec.md",):
-        p = os.path.join(d, name)
-        if os.path.isfile(p):
-            m = re.search(r'^\*\*Wave\*\*:[ \t]*(\d+)', open(p, encoding="utf-8").read(), re.M)
-            if m:
-                return int(m.group(1))
-    return 1
-
 # MERGED = a Change History row whose CR cell IS this change, in this feature's spec or in
 # the context model every feature shares — aw-crstate owns that test for all three readers
 # of it. The old test was `cr in line`, which fired on an id quoted in prose and matched a
 # prefix of a longer id.
 spec = os.path.join(fd, "spec.md")
 merged, evidence, merged_doc = False, "", ""
+order, _why = None, ""
 try:
     import importlib.util
     _mod_path = os.path.join(root, ".appweaver", "scripts", "python", "aw-crstate.py")
@@ -4611,29 +4665,39 @@ try:
     _spec.loader.exec_module(_m)
     evidence, merged_doc = _m.merged_in([spec, os.path.join(ctx, "domain-model.md")], cr)
     merged = bool(evidence)
-except Exception:
+    # DEPENDANTS, from the same reader the merge fence uses in the opposite direction. An
+    # unreadable `**Wave**:` is not wave 1 here either: it used to mean `w > wave` was false
+    # and the change was not counted, so recall withdrew the ground from under a dependant
+    # it could not see. Waves have no ceiling, so any unordered change could sit above this
+    # one and every one of them holds recall.
+    order = _m.wave_order(ctx, fd, cr, "higher", "feature")
+except Exception as _e:
     # Fail CLOSED: an unreadable helper must not report "never merged", which is the
     # answer that lets close-delta archive a change nobody merged.
-    merged, evidence = True, "(merged check unavailable — treated as merged)"
-
-wave = wave_of(cr_dir) if os.path.isdir(cr_dir) else 1
-dependants = []
-if os.path.isdir(changes):
-    for name in sorted(os.listdir(changes)):
-        d = os.path.join(changes, name)
-        if name == cr or name == "archive" or not os.path.isdir(d):
-            continue
-        w = wave_of(d)
-        if w > wave:
-            dependants.append({"cr_id": name, "wave": w})
+    merged, evidence, _why = True, "(merged check unavailable — treated as merged)", str(_e)
+
+if order is None:
+    order = {"wave": None, "wave_known": False, "related": [], "related_count": 0,
+             "related_ids": "", "unknown": [], "unknown_count": 0, "unknown_ids": "",
+             "unknown_blocks": True, "wave_ordering_ok": False,
+             "wave_problem": "the wave reader could not be run (%s), so no open change in "
+                             "this feature is ordered against %s at all" % (_why, cr)}
+dependants = order["related"]
 
 print(json.dumps({
-    "ok": True, "cr_id": cr, "exists": os.path.isdir(cr_dir), "wave": wave,
+    "ok": True, "cr_id": cr, "exists": os.path.isdir(cr_dir),
+    "wave": order["wave"] if order["wave"] is not None else "",
+    "wave_known": order["wave_known"],
     "merged": merged, "merge_evidence": evidence,
     "dependants": dependants,
-    "dependant_ids": ", ".join("%s (wave %d)" % (x["cr_id"], x["wave"]) for x in dependants),
+    "dependant_ids": order["related_ids"],
     "dependant_count": len(dependants),
     "has_dependants": len(dependants) > 0,
+    # The changes this one cannot be ordered against at all, in either direction.
+    "unordered": order["unknown"], "unordered_count": order["unknown_count"],
+    "unordered_ids": order["unknown_ids"],
+    "wave_ordering_ok": order["wave_ordering_ok"],
+    "wave_problem": order["wave_problem"],
 }))
 PY
 }
@@ -4641,6 +4705,12 @@ PY
 # ──────────────────── plan-gate-stamp / plan-gate-check ────────────────────
 # THE RECEIPT THAT analyze-plan PASSED, and over WHICH BYTES.
 #
+# THE RULE ITSELF LIVES IN python/aw-plangate.py, which both shells invoke — these two are
+# thin wrappers that resolve the feature and hand over. It is a set of sha comparisons with
+# three deliberate asymmetries in it, and while it was embedded twice (a heredoc here, a
+# native function there) every change to it had to be re-derived by hand on the other side
+# and kept in step by eye. It changed twice that way. Now there is nothing to keep in step.
+#
 # implement generates from the lane plans and deliberately does NOT read the spec — its
 # own header says "analyze-plan already conformed the plans to it". That sentence was an
 # assumption about the order the operator ran things in, not a fact anything checked: the
@@ -4719,75 +4789,23 @@ PY
 }
 
 cmd_plan_gate_stamp() {
-    local feature_dir_arg="" spec_version="" mode="master" verdict="conformant" plan_gaps="0" routed="[]"
+    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 ;;
+    esac
+    local feature_dir_arg="" rest=()
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --spec-version) spec_version="$2"; shift 2 ;;
-            --mode) mode="$2"; shift 2 ;;
-            --verdict) verdict="$2"; shift 2 ;;
-            --plan-gaps) plan_gaps="$2"; shift 2 ;;
-            --routed) routed="$2"; shift 2 ;;
-            --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 ;;
-            *) echo "plan-gate-stamp: unknown arg '$1'" >&2; return 1 ;;
+            *) rest+=("$1"); shift ;;
         esac
     done
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "plan-gate-stamp: 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_VER="$spec_version" AW_MODE="$mode" \
-    AW_VERDICT="$verdict" AW_PLAN_GAPS="$plan_gaps" AW_ROUTED="$routed" python3 - <<'PY'
-import datetime, hashlib, json, os
-fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
-def sha(p):
-    try:
-        with open(p, "rb") as f: return hashlib.sha256(f.read()).hexdigest()
-    except Exception: return ""
-def rel(p): return os.path.relpath(p, root)
-# Every document the gate READ. A lane that is not declared has no plan on disk and is
-# simply absent from the map — the check treats a name it does not carry as not gated,
-# never as changed, so declaring a second lane later does not read as tampering.
-#
-# THE LEGACY NAMES ARE HERE FOR THE SAME REASON version-stamp CARRIES THEM. feature-paths
-# resolves design.md / design.ui.md under the backend_plan / frontend_plan keys, so a tree
-# that has not been through `plan` since the rename — every brownfield feature `adopt`
-# produces — is GATED on those documents. Hashing only the new names would leave such a
-# feature with an empty plan map: a receipt that looks tracked and fresh while the document
-# implement actually generates from is unwatched.
-plans = {}
-for name in ("backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md"):
-    h = sha(os.path.join(fd, name))
-    if h: plans[name] = h
-# An unrecognised verdict is recorded as `gaps`, the one that refuses.
-verdict = os.environ.get("AW_VERDICT", "").strip()
-if verdict not in ("conformant", "routed-gaps", "gaps"):
-    verdict = "gaps"
-try: plan_gaps = int(os.environ.get("AW_PLAN_GAPS", "0") or 0)
-except ValueError: plan_gaps = 0
-try: routed = [str(x) for x in json.loads(os.environ.get("AW_ROUTED") or "[]")]
-except Exception: routed = []
-rec = {
-    "gated": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-    "gate_mode": os.environ.get("AW_MODE", "master"),
-    "spec_version": os.environ.get("AW_VER", "").strip(),
-    "verdict": verdict,
-    "plan_gaps": plan_gaps,
-    "routed_gaps": routed,
-    "spec_sha": sha(os.path.join(fd, "spec.md")),
-    "model_sha": sha(os.path.join(ctx, "domain-model.md")),
-    "plans": plans,
-    "note": ("Written by every master-mode analyze-plan run. It records the bytes that were "
-             "checked against each other and the verdict on them, not a version — the plans' "
-             "**Version**: headers are stamped in lockstep by close-delta and cannot answer "
-             "this. implement reads it through plan-gate-check: moved bytes or verdict `gaps` "
-             "refuse; `routed-gaps` lists what /appweaver specify still has to lift."),
-}
-p = os.path.join(fd, ".aw-plan-gate.json")
-open(p, "w", encoding="utf-8").write(json.dumps(rec, indent=2) + "\n")
-print(json.dumps({"file": rel(p), "gated": rec["gated"], "spec_version": rec["spec_version"],
-                  "verdict": verdict, "plan_gaps": plan_gaps, "routed_gaps": len(routed),
-                  "hashed": sorted(plans.keys()), "count": len(plans), "ok": True}))
-PY
+    local core="$SCRIPT_DIR/../python/aw-plangate.py"
+    if [ ! -f "$core" ]; then echo "plan-gate-stamp: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "plan-gate-stamp: python3 is required" >&2; return 1; fi
+    python3 "$core" stamp --feature-dir "$fd" --context-dir "$ctx_dir" --root "$repo_root" "${rest[@]+"${rest[@]}"}"
 }
 
 cmd_plan_gate_check() {
@@ -4802,64 +4820,25 @@ cmd_plan_gate_check() {
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "plan-gate-check: 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" python3 - <<'PY'
-import hashlib, json, os
-fd = os.environ["AW_FD"]; ctx = os.environ["AW_CTX"]; root = os.environ["AW_ROOT"]
-def sha(p):
-    try:
-        with open(p, "rb") as f: return hashlib.sha256(f.read()).hexdigest()
-    except Exception: return ""
-p = os.path.join(fd, ".aw-plan-gate.json")
-rec = None
-try: rec = json.load(open(p, encoding="utf-8"))
-except Exception: rec = None
-out = {"file": os.path.relpath(p, root), "tracked": bool(rec), "gate_fresh": False,
-       "verdict": "", "may_generate": True, "plan_gaps": 0, "routed_gaps": [], "routed_csv": "",
-       "spec_moved": False, "model_moved": False, "plans_changed": [],
-       "plans_changed_csv": "", "gated": "", "spec_version": "", "reason": "", "ok": True}
-if not rec:
-    # Never gated. Not a failure and not a stale plan — an unknown, and the only honest
-    # thing to report about a tree that has not run analyze-plan since this op existed.
-    out["reason"] = ("no .aw-plan-gate.json — this feature has not been through analyze-plan "
-                     "in master mode since the gate began leaving a receipt")
-else:
-    out["gated"] = rec.get("gated", "")
-    out["spec_version"] = rec.get("spec_version", "")
-    # A receipt from before the verdict existed was only ever written on a clean pass.
-    out["verdict"] = rec.get("verdict") or "conformant"
-    out["plan_gaps"] = rec.get("plan_gaps") or 0
-    out["routed_gaps"] = [str(x) for x in (rec.get("routed_gaps") or [])]
-    out["routed_csv"] = "; ".join(out["routed_gaps"])
-    out["spec_moved"] = bool(rec.get("spec_sha")) and rec["spec_sha"] != sha(os.path.join(fd, "spec.md"))
-    # A model recorded as absent that is still absent has not moved. A context that
-    # GAINED a domain model since the gate has moved: check 4 never ran against it.
-    out["model_moved"] = rec.get("model_sha", "") != sha(os.path.join(ctx, "domain-model.md"))
-    changed = []
-    for name, was in sorted((rec.get("plans") or {}).items()):
-        if sha(os.path.join(fd, name)) != was:
-            changed.append(name)
-    out["plans_changed"] = changed
-    out["plans_changed_csv"] = ", ".join(changed)
-    out["gate_fresh"] = not (out["spec_moved"] or out["model_moved"] or changed)
-    # Moved bytes refuse whatever the verdict was; unmoved bytes refuse only on `gaps`.
-    out["may_generate"] = out["gate_fresh"] and out["verdict"] != "gaps"
-    if not out["gate_fresh"]:
-        bits = []
-        if out["spec_moved"]:  bits.append("spec.md has changed")
-        if out["model_moved"]: bits.append("domain-model.md has changed")
-        if changed:            bits.append("%s changed (a re-derive by `plan main`, or a hand edit)" % ", ".join(changed))
-        out["reason"] = "since analyze-plan checked them on %s: %s" % (out["gated"], "; ".join(bits))
-    elif out["verdict"] == "gaps":
-        out["reason"] = ("analyze-plan on %s left %s gap(s) a plan rewrite closes, unrepaired"
-                         % (out["gated"], out["plan_gaps"] or "some"))
-    elif out["verdict"] == "routed-gaps":
-        out["reason"] = ("the spec, the model and every gated plan are byte-identical to what "
-                         "analyze-plan checked on %s; it left %d gap(s) only /appweaver specify "
-                         "can close: %s" % (out["gated"], len(out["routed_gaps"]), out["routed_csv"]))
-    else:
-        out["reason"] = "the spec, the model and every gated plan are byte-identical to what analyze-plan passed on %s" % out["gated"]
-print(json.dumps(out))
-PY
+    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"
+}
+
+# ─────────────────────────────── gap-route ─────────────────────────────────
+# Split a gate's findings by the command that CLOSES each one. The checks already tag
+# every finding with `fix`; this turns that tag into the routing a gate message prints,
+# so a plan defect is never sent to `implement` — which generates FROM the plan and would
+# reproduce it. Thin wrapper: the logic is in aw-gaps.py, called identically by both shells.
+cmd_gap_route() {
+    case "${1:-}" in
+        --help|-h) echo "gap-route --gaps '<json>'... [--cr <id>]  -> {total, high_count, <route>_count, <route>_refs, <route>_text, summary, routes}"; return 0 ;;
+    esac
+    local core="$SCRIPT_DIR/../python/aw-gaps.py"
+    if [ ! -f "$core" ]; then echo "gap-route: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "gap-route: python3 is required" >&2; return 1; fi
+    python3 "$core" route "$@"
 }
 
 # ──────────────────────────────── plan-coverage ─────────────────────────────
@@ -4870,7 +4849,7 @@ PY
 # (python/aw-plan-coverage.py), called identically by both shells.
 cmd_plan_coverage() {
     case "${1:-}" in
-        --help|-h) echo "plan-coverage --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--source-path <p>] [--test-path <p>] [--reported <json list>]... [--list-only]  -> {ok, total, names[], names_csv, elements[], gaps[], gap_names[], gap_count, gaps_text, message}"; return 0 ;;
+        --help|-h) echo "plan-coverage --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--source-path <p>] [--test-path <p>] [--reported <json list>]... [--generated <json list>] [--list-only]  -> {ok, outcome, total, names[], names_csv, elements[], gaps[], gap_names[], gap_count, gaps_text, message}"; return 0 ;;
     esac
     local repo_root; repo_root=$(get_repo_root)
     local core="$SCRIPT_DIR/../python/aw-plan-coverage.py"
@@ -5039,6 +5018,7 @@ case "$sub" in
     plan-gate-stamp)  cmd_plan_gate_stamp "$@" ;;
     plan-gate-check)  cmd_plan_gate_check "$@" ;;
     plan-coverage)    cmd_plan_coverage "$@" ;;
+    gap-route)        cmd_gap_route "$@" ;;
     checklist-read)   cmd_checklist_read "$@" ;;
     checklist-apply)  cmd_checklist_apply "$@" ;;
     detect-project)   cmd_detect_project "$@" ;;
@@ -5054,6 +5034,7 @@ case "$sub" in
     setup-constitution) cmd_setup_constitution "$@" ;;
     compose-constitution) cmd_compose_constitution "$@" ;;
     constitution-verify) cmd_constitution_verify "$@" ;;
+    principles-list) cmd_principles_list "$@" ;;
     agent-context-update) cmd_agent_context_update "$@" ;;
     ""|--help|-h)
         sed -n '2,37p' "$0" | sed 's/^#\{0,1\} \{0,1\}//' ;;

package/assets/.appweaver/scripts/bash/aw-xref.sh

@@ -9,7 +9,10 @@
 #   aw-xref.sh list           --aggregate Y [--root DIR] [--bundle knowledge]
 #   aw-xref.sh concept-upsert   --aggregate X [--source-files a,b,c] [--description D] [--origin ...] [--root DIR]
 #   aw-xref.sh concept-overview --aggregate X (--text PROSE | --text-file F) [--root DIR]
-#   aw-xref.sh concept-paths    --aggregate X | --feature-dir <dir> [--root DIR] [--bundle knowledge]
+#   aw-xref.sh concept-paths    --aggregate X | --feature-dir <dir> [--under <subtree>]...
+#                                [--root DIR] [--bundle knowledge]
+#                                (--under keeps only paths inside that subtree, so a caller
+#                                generating ONE lane is not handed another lane's files)
 #   aw-xref.sh feature-aggregates --feature-dir <dir> [--root DIR]
 #                               (the aggregate(s) a feature acts on: its spec's Acts-on line,
 #                               then the boundary map, then the feature name itself)