aw-spec-cli 0.1.20 → 0.1.22

package/assets/.appweaver/scripts/powershell/aw-xref.ps1

@@ -8,7 +8,10 @@
 #   aw-xref.ps1 list           --aggregate Y [--root DIR] [--bundle knowledge]
 #   aw-xref.ps1 concept-upsert   --aggregate X [--source-files a,b,c] [--description D] [--origin ...] [--root DIR]
 #   aw-xref.ps1 concept-overview --aggregate X (--text PROSE | --text-file F) [--root DIR]
-#   aw-xref.ps1 concept-paths    --aggregate X | --feature-dir <dir> [--root DIR] [--bundle knowledge]
+#   aw-xref.ps1 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.ps1 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)

package/assets/.appweaver/scripts/python/aw-crstate.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+"""
+aw-crstate — ONE definition of "this change has been merged", for every reader of it.
+
+Three places ask the question and each answered it differently: cr-merge-check's
+merged-open fence, cr-recall-check's already-merged guard, and close-delta through it.
+All three tested `cr_id in spec.md` — the id ANYWHERE in the file, including quoted in a
+rationale, and matching a prefix (`CR-001` inside `CR-0011`). A guard that fires on prose
+is a guard nobody can trust, and three copies of it drift.
+
+THE EVIDENCE IS A CHANGE HISTORY ROW. finalize-delta appends one when it merges, carrying
+the change's id in the row's CR cell. So a change is merged when its id is a CELL of such a
+row — matched whole, in a table row, never as a substring of a paragraph.
+
+WHERE IT LOOKS. `spec.md` is per feature, but `domain-model.md` is shared by every feature
+in the bounded context: a sibling feature's merge moves a master THIS delta was authored
+against and leaves nothing in this feature's spec. So the scan covers the context's model
+and every feature's spec, and reports which document carried the evidence.
+
+It also owns the WAVE ORDERING the two gates of the CR loop read in opposite directions —
+merge refuses a change with an open predecessor below it, recall refuses one with an open
+dependant above it. Both asked the question with their own copy of the reader, in each of
+two shells, and every copy answered "wave 1" when it could not read a `**Wave**:` header.
+That default is not a neutral one: the shipped template line is `**Wave**: [N]`, so an
+UNSTAMPED delta reads as wave 1, and a subject at wave 1 can have no predecessor at all —
+the fence quietly switches itself off for exactly the change being merged. Here an
+unreadable wave is None, and a caller is told which changes it could not order.
+
+Importable (the bash payloads load it by path) and a CLI (the PowerShell twins call it), so
+both shells answer from the same code.
+
+Usage:
+  aw-crstate.py merged --cr <id> --doc <path> [--doc <path>…]
+      -> {"merged": bool, "evidence": "<the row>", "document": "<path>"}
+  aw-crstate.py merged-open --cr <id> --feature-dir <p> --context-dir <p>
+      -> {"merged_open": [{cr_id, feature, document, evidence, aggregates, shared, same_feature}],
+          "blocking": [...], "blocking_count": n, "blocking_ids": "…", "blocking_text": "…"}
+  aw-crstate.py wave-order --cr <id> --feature-dir <p> --context-dir <p>
+                           [--direction lower|higher] [--scope context|feature]
+      -> {"wave": int|null, "wave_known": bool, "related": [{cr_id, wave, feature}],
+          "related_count": n, "related_ids": "…", "unknown": [...], "unknown_count": n,
+          "unknown_ids": "…", "unknown_blocks": bool, "wave_ordering_ok": bool,
+          "wave_problem": "…"}
+"""
+
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+
+CR_RX = re.compile(r"CR-\d{8}-\d{6}-[0-9A-Za-z]+")
+TICK_RX = re.compile(r"`([^`]+)`")
+WAVE_RX = re.compile(r"^\*\*Wave\*\*:[ \t]*(\d+)", re.M)
+
+# The lowest wave a change can legitimately carry. cr-wave-derive computes a change's
+# required wave as `max(predecessor waves, default 0) + 1`, so wave 1 is the floor: nothing
+# sits below it, and a change AT it can have no predecessor. That is what makes an
+# unreadable neighbour harmless to a wave-1 merge and ambiguous to every other one.
+FLOOR = 1
+
+
+def read(path):
+    try:
+        return open(path, encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def _cells(line):
+    s = line.strip()
+    if not s.startswith("|"):
+        return []
+    return [c.strip() for c in s.strip("|").split("|")]
+
+
+def merged_row(text, cr_id):
+    """The Change History row whose CR cell IS this change, or "" when there is none.
+
+    The cell may carry the bare id or the id with a link or a note beside it, so the test is
+    "the cell contains this id as a whole token" — not "the row mentions it", which is what
+    made a cited id in prose read as a merge.
+    """
+    if not text or not cr_id:
+        return ""
+    for line in text.split("\n"):
+        cells = _cells(line)
+        if len(cells) < 2 or set("".join(cells)) <= set("-: "):
+            continue
+        for cell in cells[1:]:                      # never the leading Version cell
+            if cr_id in CR_RX.findall(cell):
+                return line.strip()
+    return ""
+
+
+def merged_in(paths, cr_id):
+    """(row, document) for the first document whose Change History records this change."""
+    for p in paths:
+        row = merged_row(read(p), cr_id)
+        if row:
+            return row, p
+    return "", ""
+
+
+def aggregates(text):
+    """The `**Aggregates touched**:` header — the list finalize-delta opens sections for."""
+    m = re.search(r"^[ \t]*(?:[-*][ \t]+)?\*\*Aggregates touched(?:\*\*:|:\*\*)[ \t]*(.*)$",
+                  text or "", re.M)
+    if not m:
+        return set()
+    value = re.sub(r"<!--.*?(?:-->|$)", "", m.group(1)).strip()
+    names = TICK_RX.findall(value)
+    if not names:
+        parts = [p.strip() for p in re.split(r"[,;/&]|\band\b", value) if p.strip()]
+        names = [re.match(r"[A-Za-z_][A-Za-z0-9_]*", n).group(0)
+                 for n in parts if re.match(r"[A-Za-z_][A-Za-z0-9_]*", n)]
+    return {n for n in names if not n.startswith(("<", "[")) and not re.match(r"(?i)none\b", n)}
+
+
+def model_delta_of(ctx, cr_id):
+    """A change's model half: beside the master while open, in its archive once closed."""
+    p = os.path.join(ctx, "domain-model.%s.delta.md" % cr_id)
+    if os.path.isfile(p):
+        return read(p)
+    for feat in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
+        a = os.path.join(ctx, feat, "changes", "archive", cr_id, "domain-model.delta.md")
+        if os.path.isfile(a):
+            return read(a)
+    return ""
+
+
+def open_changes(ctx):
+    """{cr_id: feature} for every change OPEN in the context — the directory is the
+    authority, and a model delta with no change directory still counts."""
+    found = {}
+    if not os.path.isdir(ctx):
+        return found
+    for feat in sorted(os.listdir(ctx)):
+        ch = os.path.join(ctx, feat, "changes")
+        if not os.path.isdir(ch):
+            continue
+        for name in sorted(os.listdir(ch)):
+            if name != "archive" and os.path.isdir(os.path.join(ch, name)):
+                found.setdefault(name, feat)
+    for f in sorted(os.listdir(ctx)):
+        m = re.match(r"^domain-model\.(.+)\.delta\.md$", f)
+        if m:
+            found.setdefault(m.group(1), "")
+    return found
+
+
+def wave_of(ctx, feature, cr_id):
+    """The wave a change states in its own delta documents, or None when none of them
+    carries a readable `**Wave**:` header.
+
+    The documents are read in the order cr-wave-derive stamps them, so a change cannot be
+    ordered one way by the wave fence and another by the derivation that sets it.
+    """
+    paths = [os.path.join(ctx, "domain-model.%s.delta.md" % cr_id)]
+    if feature:
+        d = os.path.join(ctx, feature, "changes", cr_id)
+        paths.append(os.path.join(d, "delta-spec.md"))
+        paths.extend(sorted(glob.glob(os.path.join(glob.escape(d), "delta-*.md"))))
+    for p in paths:
+        m = WAVE_RX.search(read(p))
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def _whose(rec, show_feature):
+    """Which feature a change belongs to, for a reader who has never opened it. The scan is
+    context-wide, so the id alone names something the operator may have no way to find — and
+    finalize-delta resolves a change under the ACTIVE feature, so the feature is the step
+    between reading the refusal and acting on it, not a courtesy."""
+    if not show_feature:
+        return ""
+    if rec.get("feature"):
+        return ", feature %s" % rec["feature"]
+    return ", model delta only — no changes/ directory in this context"
+
+
+def wave_order(ctx, feature_dir, cr_id, direction="lower", scope="context"):
+    """The open changes this one is ordered against, and the ones it cannot be ordered against.
+
+    `direction` is which side of this change matters: "lower" for the merge fence (a
+    predecessor lands first) and "higher" for the recall fence (a dependant was built on
+    top). `scope` is how wide the scan runs — context-wide for merge, because two features
+    of one context share domain-model.md, and this feature only for recall.
+
+    A change whose wave cannot be read is NOT ordered and never silently counted as either.
+    It blocks where it is genuinely ambiguous: for the merge fence only above the floor,
+    since nothing can precede a wave-1 change; for the recall fence always, because waves
+    have no ceiling and any unreadable change could sit above this one.
+    """
+    this_feat = os.path.basename(os.path.normpath(feature_dir))
+    wave = wave_of(ctx, this_feat, cr_id)
+    show_feature = scope == "context"
+    rows, unknown = [], []
+    for other, feat in sorted(open_changes(ctx).items()):
+        if other == cr_id or (scope == "feature" and feat != this_feat):
+            continue
+        w = wave_of(ctx, feat, other)
+        rec = {"cr_id": other, "wave": w, "feature": feat}
+        if w is None:
+            unknown.append(rec)
+        elif wave is not None and (w < wave if direction == "lower" else w > wave):
+            rows.append(rec)
+
+    unknown_blocks = bool(unknown) and (direction == "higher" or
+                                        (wave is not None and wave > FLOOR))
+    problem = ""
+    if wave is None:
+        problem = ("change %s carries no readable `**Wave**:` header of its own, so it "
+                   "cannot be ordered against anything: every open change reads as neither "
+                   "above nor below it, and this fence has nothing left to check" % cr_id)
+    elif unknown_blocks:
+        problem = ("%d open change(s) carry no readable `**Wave**:` header, so they cannot "
+                   "be placed above or below change %s (wave %d): %s"
+                   % (len(unknown), cr_id, wave,
+                      ", ".join("%s%s" % (u["cr_id"], _whose(u, show_feature))
+                                for u in unknown)))
+    return {
+        "wave": wave, "wave_known": wave is not None,
+        "related": rows, "related_count": len(rows),
+        "related_ids": ", ".join("%s (wave %d%s)" % (r["cr_id"], r["wave"],
+                                                     _whose(r, show_feature)) for r in rows),
+        "unknown": unknown, "unknown_count": len(unknown),
+        "unknown_ids": ", ".join("%s%s" % (u["cr_id"], _whose(u, show_feature))
+                                 for u in unknown),
+        "unknown_blocks": unknown_blocks,
+        "wave_ordering_ok": wave is not None and not unknown_blocks,
+        "wave_problem": problem,
+    }
+
+
+def merged_open(ctx, feature_dir, cr_id):
+    """Changes that are MERGED into a master and still OPEN — the state in which the masters
+    carry a change the version does not yet reflect.
+
+    A merge in THIS feature moved this delta's own spec, so it blocks whatever it touched.
+    A SIBLING feature's merge moved the shared context model, so it blocks only where it
+    touched an aggregate this delta also names; `shared` carries that answer and a reader
+    that cannot read a delta's aggregates is told so (`unknown`) rather than cleared.
+    """
+    this_feat = os.path.basename(os.path.normpath(feature_dir))
+    mine = aggregates(model_delta_of(ctx, cr_id))
+    docs = {}
+    model_master = os.path.join(ctx, "domain-model.md")
+    if os.path.isfile(model_master):
+        docs[model_master] = ""
+    for spec in sorted(glob.glob(os.path.join(glob.escape(ctx), "*", "spec.md"))):
+        docs[spec] = os.path.basename(os.path.dirname(spec))
+
+    out = []
+    for other, feat in sorted(open_changes(ctx).items()):
+        if other == cr_id:
+            continue
+        row, doc = merged_in(list(docs), other)
+        if not row:
+            continue
+        theirs = aggregates(model_delta_of(ctx, other))
+        same_feature = (feat or docs.get(doc, "")) == this_feat
+        shared = sorted(mine & theirs)
+        out.append({
+            "cr_id": other, "feature": feat or docs.get(doc, ""),
+            "document": os.path.relpath(doc, ctx), "evidence": row,
+            "aggregates": sorted(theirs), "shared": shared,
+            "unknown": not theirs, "same_feature": same_feature,
+            # A sibling's merge blocks only where it moved something this delta also names.
+            "blocking": same_feature or bool(shared) or not theirs,
+        })
+    return out
+
+
+def merged_open_text(rows):
+    """Merged-but-open changes as a reader can act on them. The feature is what turns an id
+    into somewhere to go: a sibling's merge is counted here, and close-delta runs under the
+    feature that owns the change."""
+    return ", ".join("%s%s" % (r["cr_id"], _whose(r, True)) for r in rows)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="one definition of a merged change")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    m = sub.add_parser("merged")
+    m.add_argument("--cr", required=True)
+    m.add_argument("--doc", action="append", default=[])
+    o = sub.add_parser("merged-open")
+    o.add_argument("--cr", required=True)
+    o.add_argument("--feature-dir", required=True)
+    o.add_argument("--context-dir", required=True)
+    w = sub.add_parser("wave-order")
+    w.add_argument("--cr", required=True)
+    w.add_argument("--feature-dir", required=True)
+    w.add_argument("--context-dir", required=True)
+    w.add_argument("--direction", choices=["lower", "higher"], default="lower")
+    w.add_argument("--scope", choices=["context", "feature"], default="context")
+    args = ap.parse_args()
+
+    if args.cmd == "merged":
+        row, doc = merged_in(args.doc, args.cr)
+        out = {"merged": bool(row), "evidence": row, "document": doc}
+    elif args.cmd == "wave-order":
+        out = wave_order(args.context_dir, args.feature_dir, args.cr,
+                         args.direction, args.scope)
+    else:
+        rows = merged_open(args.context_dir, args.feature_dir, args.cr)
+        blocking = [r for r in rows if r["blocking"]]
+        out = {"merged_open": rows, "blocking": blocking,
+               "blocking_count": len(blocking),
+               "blocking_ids": ", ".join(r["cr_id"] for r in blocking),
+               "blocking_text": merged_open_text(blocking)}
+    sys.stdout.write(json.dumps(out, separators=(",", ":")) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/assets/.appweaver/scripts/python/aw-foundation.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+aw-foundation — the part of scaffolding that depends on the LANE MODEL.
+
+A foundation pack is a tree of files and an unpacker that writes it under one output
+directory. That output directory is now a LANE'S SOURCE PATH, so everything a pack
+carries lands inside the subtree its lane owns, and nothing a scaffold produces can
+appear outside a declared lane.
+
+A lane owns TWO subtrees, though — its source path and its test path — and for most
+backend stacks they are siblings rather than nested: .NET keeps `tests/` beside `src/`,
+not inside it. A pack that carries its own test project therefore has one directory
+that does NOT belong under the source path, and unpacking it verbatim would bury the
+tests at `src/tests/`, where the lane does not own them, `dotnet test` does not look for
+them, and every later phase that resolves the lane's test path finds nothing.
+
+So the test tree is LIFTED: whatever the pack placed at `<source path>/<test dir>` is
+merged into the lane's declared test path. The directory name comes from the lane's own
+test path rather than from a list here, which is what makes a lane with a custom
+`test_root` work and a stack whose tests live inside its source a no-op — the two paths
+are then the same subtree and there is nothing to lift.
+
+Called as a CLI by both the bash and the PowerShell actions, so the two answer from one
+implementation rather than from two that have to be kept in step.
+
+Usage:
+  aw-foundation.py redirect-tests --out <lane source path> --test-path <lane test path>
+                                  [--repo <root>] [--force]
+      -> {"moved": n, "conflicts": [...], "from": "...", "to": "...", "message": "..."}
+"""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+
+
+def norm(path):
+    """A repo-relative directory, '/'-separated and '/'-terminated; "" when absent.
+
+    Mirrors aw-stack's `norm_root` for the shapes this reads, so the paths compared here
+    are the same strings the lane model stores. "./" — the repo root as a source path —
+    normalises to "" so that joining it yields the repo itself.
+    """
+    p = (path or "").replace("\\", "/").strip()
+    while p.startswith("./"):
+        p = p[2:]
+    p = p.lstrip("/")
+    if p in ("", "."):
+        return ""
+    return p if p.endswith("/") else p + "/"
+
+
+def emit(payload):
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def merge_move(src, dest, force):
+    """Move every file under `src` to the matching place under `dest`, keeping what is
+    already there unless `force`. Returns (moved, conflicts) as repo-relative-ish names.
+
+    A merge rather than a rename because the destination legitimately already exists: a
+    second foundation unpacked into the same lane, or a reference pack following the
+    primary one, both add to a test tree rather than replace it.
+    """
+    moved, conflicts = [], []
+    for dirpath, _dirnames, filenames in os.walk(src):
+        for name in sorted(filenames):
+            s = os.path.join(dirpath, name)
+            rel = os.path.relpath(s, src).replace("\\", "/")
+            d = os.path.join(dest, rel)
+            if os.path.exists(d):
+                if not force:
+                    conflicts.append(rel)
+                    continue
+                try:
+                    os.remove(d)
+                except OSError:
+                    conflicts.append(rel)
+                    continue
+            os.makedirs(os.path.dirname(d) or ".", exist_ok=True)
+            shutil.move(s, d)
+            moved.append(rel)
+    # Leave nothing behind but the directories a conflict kept a file in.
+    for dirpath, _dirnames, _filenames in sorted(os.walk(src), reverse=True):
+        try:
+            os.rmdir(dirpath)
+        except OSError:
+            pass
+    return moved, conflicts
+
+
+def redirect_tests(repo, out, test_path, force=False):
+    out_rel, test_rel = norm(out), norm(test_path)
+
+    def skip(why):
+        return {"moved": 0, "conflicts": [], "from": "", "to": test_rel,
+                "redirected": False, "message": why}
+
+    if not test_rel:
+        return skip("the lane declares no test path, so nothing is lifted")
+    # Nested or identical paths mean the pack's own layout is already the lane's: the
+    # tests it carries are inside the subtree they belong in, and moving them would
+    # take them out of it.
+    if out_rel and (test_rel == out_rel or test_rel.startswith(out_rel)):
+        return skip("this lane keeps its tests inside its source path (%s), "
+                    "so the pack's layout is already right" % out_rel)
+
+    # WHAT the pack would have called its test tree, had it placed one: the last segment
+    # of the path the lane keeps tests in. Reading it from the lane rather than from a
+    # fixed list is what makes a custom `test_root` work.
+    seg = test_rel.rstrip("/").rsplit("/", 1)[-1]
+    src = os.path.join(repo, out_rel, seg) if out_rel else os.path.join(repo, seg)
+    dest = os.path.join(repo, test_rel)
+
+    if os.path.abspath(src) == os.path.abspath(dest):
+        return skip("the pack already writes its tests to %s" % test_rel)
+    if not os.path.isdir(src):
+        return skip("this pack carries no %s/ directory, so there are no tests to lift" % seg)
+
+    os.makedirs(dest, exist_ok=True)
+    moved, conflicts = merge_move(src, dest, force)
+    src_rel = "%s%s/" % (out_rel, seg)
+    if conflicts:
+        msg = ("lifted %d test file(s) from %s to the lane's test path %s; %d left in place "
+               "because %s already holds them" % (len(moved), src_rel, test_rel,
+                                                  len(conflicts), test_rel))
+    else:
+        msg = ("lifted %d test file(s) from %s to the lane's test path %s"
+               % (len(moved), src_rel, test_rel))
+    return {"moved": len(moved), "conflicts": conflicts, "from": src_rel, "to": test_rel,
+            "redirected": bool(moved), "message": msg}
+
+
+def main():
+    ap = argparse.ArgumentParser(description="lane-aware scaffolding helpers")
+    ap.add_argument("--repo", default=os.getcwd())
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("redirect-tests")
+    r.add_argument("--out", required=True, help="the lane's source path, where the pack was unpacked")
+    r.add_argument("--test-path", default="", help="the lane's declared test path")
+    r.add_argument("--force", action="store_true")
+    args = ap.parse_args()
+
+    if args.cmd == "redirect-tests":
+        emit(redirect_tests(args.repo, args.out, args.test_path, args.force))
+
+
+if __name__ == "__main__":
+    main()

package/assets/.appweaver/scripts/python/aw-gaps.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+aw-gaps — split a gate's findings by WHO CAN CLOSE THEM.
+
+A conformance gate returns findings that look alike and are not: one says the code does not
+do what the change asked, another says the delta PLAN asked for the wrong thing, a third
+says the delta spec or the model never said it. They read the same in a list and they are
+closed by three different commands — and sending a plan defect to `implement` cannot work,
+because implement generates FROM the plan and will faithfully reproduce it.
+
+The checks already tag each finding with the command that closes it (`fix`). This turns that
+tag into the routing the caller reports: per-route counts, the ids involved, and a line of
+prose per route that a gate message can print without assembling it itself.
+
+A finding whose `fix` is missing or unrecognised is NOT quietly folded into the biggest
+bucket. It goes to `review` and is counted there, because a finding nobody can be told to
+close is worse than one routed to the wrong place: the first is visible, the second is not.
+
+Usage:
+  aw-gaps.py route --gaps '<json>' [--gaps '<json>']...
+      -> {total, implement_count/_refs/_text, plan_count/…, specify_count/…,
+          review_count/…, high_count, summary, routes}
+"""
+
+import argparse
+import json
+import sys
+
+# The commands a finding can be routed to, in the order a reader should act on them:
+# fix the spec before the plan that realises it, and the plan before the code it maps to.
+ROUTES = ["specify", "plan", "implement", "review"]
+
+HOW = {
+    "specify": "/appweaver specify {cr} — the delta spec or the model delta is what is missing",
+    "plan": "/appweaver plan {cr} — the delta PLAN is what is wrong, so re-derive it "
+            "(then /appweaver analyze-plan-delta {cr} and /appweaver implement {cr})",
+    "implement": "/appweaver implement {cr} — the code is missing or does not do what the "
+                 "change asked",
+    "review": "no `fix` command was recorded for these — read them in the report and decide",
+}
+
+
+def load(raw_list):
+    """Every findings list the caller passed, flattened. Accepts the list itself or the
+    whole `{ok, gaps}` envelope, and ignores what it cannot parse rather than failing the
+    gate that called it — a router that crashes turns a reportable red into a stack trace."""
+    out = []
+    for raw in raw_list or []:
+        raw = (raw or "").strip()
+        if raw in ("", "[]", "None", "null"):
+            continue
+        try:
+            data = json.loads(raw)
+        except ValueError:
+            continue
+        if isinstance(data, dict):
+            data = data.get("gaps") or []
+        if isinstance(data, list):
+            out.extend(d for d in data if isinstance(d, dict))
+    return out
+
+
+def route_of(gap):
+    fix = str(gap.get("fix") or "").strip().lower()
+    # The tag may arrive as a whole command line ("/appweaver plan CR-…"); the verb is what
+    # routes, and anything else is unrecognised rather than guessed at.
+    for r in ("specify", "plan", "implement"):
+        if fix == r or fix.startswith(r + " ") or fix.endswith("/" + r) or ("appweaver " + r) in fix:
+            return r
+    return "review"
+
+
+def describe(gap):
+    ref = str(gap.get("ref") or "").strip() or "(no id)"
+    where = str(gap.get("where") or "").strip()
+    what = str(gap.get("gap") or "").strip()
+    sev = str(gap.get("severity") or "").strip()
+    check = str(gap.get("check") or "").strip()
+    head = "%s%s" % (ref, " [%s%s]" % (sev, "/" + check if check else "") if sev or check else "")
+    tail = " at %s" % where if where and where.lower() != "absent" else ""
+    return "%s%s — %s" % (head, tail, what or "no detail recorded")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="split gate findings by the command that closes them")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("route")
+    r.add_argument("--gaps", action="append", default=[])
+    r.add_argument("--cr", default="<CR-id>", help="woven into each route's command line")
+    args = ap.parse_args()
+
+    gaps = load(args.gaps)
+    buckets = {k: [] for k in ROUTES}
+    for g in gaps:
+        buckets[route_of(g)].append(g)
+
+    out = {"total": len(gaps),
+           "high_count": sum(1 for g in gaps
+                             if str(g.get("severity") or "").lower() == "high"),
+           "routes": {k: buckets[k] for k in ROUTES}}
+    parts = []
+    for k in ROUTES:
+        rows = buckets[k]
+        refs = [str(g.get("ref") or "").strip() for g in rows if str(g.get("ref") or "").strip()]
+        out[k + "_count"] = len(rows)
+        out[k + "_refs"] = ", ".join(dict.fromkeys(refs))
+        out[k + "_text"] = ("%s:\n%s" % (HOW[k].format(cr=args.cr),
+                                         "\n".join("  - " + describe(g) for g in rows))
+                            if rows else "none")
+        if rows:
+            parts.append("%d → %s" % (len(rows), HOW[k].format(cr=args.cr).split(" — ")[0]))
+    out["summary"] = ("%d finding(s), %d high. Routed: %s"
+                      % (len(gaps), out["high_count"], "; ".join(parts))) if gaps else \
+                     "no findings"
+    sys.stdout.write(json.dumps(out, separators=(",", ":")) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/assets/.appweaver/scripts/python/aw-payload-parity.py

@@ -53,11 +53,30 @@ ACCEPTED_BASH_ONLY = {
     # Aggregate overlap between open model deltas: two markdown regexes over a directory
     # listing. Native on both sides for the same reason as the pair above.
     "cmd_cr_overlap",
+    # analyze-plan gap routing: one pass over a JSON list and two string tests. PowerShell
+    # parses the list natively. (plan-gate-stamp / plan-gate-check are no longer beside it:
+    # their rule moved into python/aw-plangate.py, which both shells invoke.)
+    "cmd_plan_gaps",
     # Header stamping and wave discovery are a few lines of regex over a markdown header.
     # PowerShell does that natively at a fraction of the cost of spawning python, and both
     # sides are short enough to review as a pair — which is the bar for this list.
     "_stamp_header",
     "_max_open_wave",
+    # Reading ONE `**Name**:` header out of a markdown file: the read half of _stamp_header
+    # above, and native on the PowerShell side as Get-MdHeader for the same reason. 11 lines
+    # against 8.
+    "_read_header",
+    # Writing .appweaver/feature.json and echoing what it now points at — a JSON write and a
+    # path join. PowerShell does both natively rather than spawning python to write six keys.
+    "cmd_set_feature",
+    # The pre-merge snapshot: copy a change's documents into changes/<id>/pre-merge/ and
+    # count them. Directory walk plus file copy, which is native territory in both shells.
+    "cmd_cr_snapshot",
+    # The two merge-fence readers. Their hard questions — has this change merged, what is
+    # ordered against it — were moved into python/aw-crstate.py, which BOTH shells call, so
+    # what is dual-authored here is argument parsing and JSON assembly around a shared core.
+    "cmd_cr_merge_check",
+    "cmd_cr_recall_check",
     "cmd_checklist_read",
     "cmd_checklist_apply",
     "cmd_compose_constitution",