aw-spec-cli 0.1.21 → 0.1.22

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

@@ -17,6 +17,15 @@ in the bounded context: a sibling feature's merge moves a master THIS delta was
 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.
 
@@ -24,7 +33,14 @@ 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}], …}
+      -> {"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
@@ -36,6 +52,13 @@ 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):
@@ -127,6 +150,91 @@ def open_changes(ctx):
     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.
@@ -166,6 +274,13 @@ def merged_open(ctx, feature_dir, cr_id):
     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)
@@ -176,17 +291,27 @@ def main():
     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_ids": ", ".join(r["cr_id"] for r in blocking),
+               "blocking_text": merged_open_text(blocking)}
     sys.stdout.write(json.dumps(out, separators=(",", ":")) + "\n")
 
 

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

@@ -54,13 +54,29 @@ ACCEPTED_BASH_ONLY = {
     # 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, beside its native plan-gate-stamp / plan-gate-check.
+    # 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",

package/assets/.appweaver/scripts/python/aw-plan-coverage.py

@@ -297,6 +297,29 @@ def norm_name(s):
     return re.sub(r"\s+", " ", s).strip().lower()
 
 
+def parse_generated(raw):
+    """The files a generation pass wrote, as a list. `None` means the caller did not say.
+
+    The engine renders a list variable as JSON, so this normally arrives as `[]` or
+    `["a.cs", …]`; a bare comma-separated string is accepted for a caller driving the op
+    by hand. Unparseable input is treated as "did not say" rather than as "wrote nothing",
+    because reading a corrupt list as an empty one would turn a failed pass into an
+    already-implemented verdict.
+    """
+    if raw is None:
+        return None
+    raw = (raw or "").strip()
+    if raw in ("", "[]", "None", "null"):
+        return []
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return [p.strip() for p in raw.split(",") if p.strip()]
+    if isinstance(data, list):
+        return [str(x).strip() for x in data if str(x).strip()]
+    return None
+
+
 def load_reports(raw_list):
     """{normalised name: (status, reason)} — later reports win. Unreadable input counts as
     no report, which leaves every report-only element unconfirmed."""
@@ -337,6 +360,13 @@ def main():
     ap.add_argument("--source-path", default="")
     ap.add_argument("--test-path", default="")
     ap.add_argument("--reported", action="append", default=[])
+    ap.add_argument("--generated", default=None,
+                    help="the files the generation pass wrote. An EMPTY list is the "
+                         "already-implemented probe: coverage is then judged on the code "
+                         "alone. Omitted entirely, every element is judged both ways.")
+    ap.add_argument("--reserved", default="",
+                    help="comma-separated names the lane's stack already defines in ambient "
+                         "scope. Element names matching one are reported as collisions.")
     ap.add_argument("--list-only", action="store_true")
     args = ap.parse_args()
 
@@ -346,7 +376,8 @@ def main():
             "test_path": args.test_path}
 
     if not os.path.isfile(plan):
-        base.update({"ok": False, "plan_exists": False, "mode": args.mode, "total": 0,
+        base.update({"ok": False, "outcome": "no-plan",
+                     "plan_exists": False, "mode": args.mode, "total": 0,
                      "names": [], "names_csv": "", "names_text": "(the plan does not exist)",
                      "elements": [], "gaps": [], "gap_names": [], "gap_names_csv": "",
                      "gap_count": 1,
@@ -360,15 +391,35 @@ def main():
         "delta" if any(l.strip().upper().startswith("## ADDED") for l in lines) else "bootstrap")
     elements = extract(lines, args.kind, mode)
     names = [n for n, _, _ in elements]
+    # NAMES THE STACK ALREADY DEFINES. A plan element called `Route` or `Task` is not a
+    # naming mistake — the plan carries the ubiquitous language and the generator spells it
+    # verbatim — but on a stack whose ambient scope defines the same name, writing it bare
+    # is ambiguous and does not compile (C# CS0104). The conflict is invisible in the file,
+    # because the framework name arrives through an implicit using and appears in no line
+    # of it, so the generator is TOLD which of its own element names are affected.
+    reserved = {r.strip() for r in (args.reserved or "").replace(";", ",").split(",") if r.strip()}
+    collisions = []
+    for n in names:
+        leaf = n.split(".")[-1]
+        if leaf in reserved and leaf not in collisions:
+            collisions.append(leaf)
     base.update({"plan_exists": True, "mode": mode, "total": len(elements),
                  "names": names, "names_csv": ", ".join(names),
+                 "collisions": collisions, "collisions_csv": ", ".join(collisions),
+                 "collision_count": len(collisions),
+                 # Prompt-ready: never empty, so the sentence around it still reads.
+                 "collisions_text": (
+                     "%s — each of these is also a type this stack defines in ambient scope, "
+                     "so write it QUALIFIED at every use site" % ", ".join(collisions))
+                 if collisions else "none — no plan element collides with a framework type",
                  # For a prompt: never empty, so the sentence around it still reads.
                  "names_text": ", ".join(names) if names else
                  "(none could be read from the plan — report each element you realise by "
                  "the name the plan gives it)"})
 
     if args.list_only:
-        base.update({"ok": True, "message": "%d plan element(s) listed" % len(elements)})
+        base.update({"ok": True, "outcome": "listed",
+                     "message": "%d plan element(s) listed" % len(elements)})
         emit(base)
         return
 
@@ -380,6 +431,15 @@ def main():
     hits = scan(repo, norm_path(args.source_path), args.test_path, probe)
     reports, readable = load_reports(args.reported)
 
+    # A pass that wrote NOTHING is either a lane that is already built or one that failed,
+    # and the difference is written in the code, not in what the pass said about itself. So
+    # the report requirement is dropped for that probe: an element no scan can confirm — a
+    # port, an adapter — was confirmed by the run that created it and cannot be confirmed
+    # again without generating. An element the pass explicitly called blocked still counts
+    # against it either way.
+    generated = parse_generated(args.generated)
+    code_only = generated is not None and not generated
+
     rows, gaps, gap_names = [], [], []
     for name, ekind, is_checked in elements:
         files = hits.get(probe_key(name, ekind), []) if is_checked else []
@@ -390,7 +450,7 @@ def main():
             why.append("no code under %s names it" % (args.source_path or "the repo"))
         if status and not done:
             why.append("reported %s%s" % (status, (": " + reason) if reason else ""))
-        elif not status and not is_checked:
+        elif not status and not is_checked and not code_only:
             why.append("not reported done")
         rows.append({"element": name, "kind": ekind, "checked": is_checked,
                      "found": bool(files) if is_checked else None, "files": files,
@@ -402,16 +462,36 @@ def main():
     total_checked = len(checked)
     found = sum(1 for r in rows if r["checked"] and r["found"])
     ok = not gaps
+
+    # WHAT HAPPENED TO THIS LANE, as one word a caller can branch on. "no-plan-elements" is
+    # kept apart from "already-implemented" because they look identical from the file count
+    # and mean opposite things: a plan nothing can be read from proves nothing about the
+    # code, and a pass that wrote no files against one is unexplained, not finished.
     if not elements:
+        outcome = "no-plan-elements"
+    elif gaps:
+        outcome = "gaps"
+    elif code_only:
+        outcome = "already-implemented"
+    else:
+        outcome = "complete"
+
+    if outcome == "no-plan-elements":
         msg = ("no plan element could be read from %s — its layout does not follow the "
                "plan template, so coverage was not checked" % args.plan)
+    elif outcome == "already-implemented":
+        msg = ("this pass wrote no files and every one of the %d plan element(s) is already "
+               "realised under %s — there was nothing left to write"
+               % (len(elements), args.source_path or "the repo"))
     elif ok:
         msg = "all %d plan element(s) realised (%d found in code, %d reported done)" % (
             len(elements), found, len(elements) - total_checked)
     else:
         msg = "%d of %d plan element(s) not realised: %s" % (
             len(gaps), len(elements), "; ".join(gaps))
-    base.update({"ok": ok, "reported": readable, "checked_on_disk": total_checked,
+    base.update({"ok": ok, "outcome": outcome, "wrote_files": bool(generated),
+                 "judged_on": "code" if code_only else "code and report",
+                 "reported": readable, "checked_on_disk": total_checked,
                  "found_on_disk": found, "elements": rows, "gaps": gaps,
                  "gap_names": gap_names, "gap_names_csv": ", ".join(gap_names),
                  "gap_count": len(gaps),