aw-spec-cli 0.1.15 → 0.1.17

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

@@ -6,10 +6,9 @@
 #
 #   aw-xref.ps1 record         --using X --design <design.md> [--origin ...] [--date YYYY-MM-DD] [--root DIR]
 #   aw-xref.ps1 list           --aggregate Y [--root DIR] [--bundle knowledge]
-#   aw-xref.ps1 concept-upsert   --aggregate X [--source-files a,b,c] [--lane backend|frontend] [--merge] [--description D] [--origin ...] [--root DIR]
+#   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-coverage --aggregate X | --feature-dir <dir> [--ids "FR-001,BR-002"] [--max-list N] [--root DIR] [--bundle knowledge]
 $ErrorActionPreference = "Stop"
 $core = Join-Path $PSScriptRoot "..\python\aw-xref.py"
 & python3 $core @args

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""aw-payload-parity.py — prove the two shells run the SAME python.
+
+Most of aw-spec-actions is one python program embedded twice: as a `<<'PY'` heredoc in
+aw-spec-actions.sh and as a `$PyName = @'…'@` here-string in aw-spec-actions.ps1. The
+contract is that each pair is BYTE-IDENTICAL, and nothing checked it — so a fix applied to
+one shell and forgotten in the other is a gate that behaves differently on Windows, in
+silence. Three of the ops with no twin at all are on the forward chain (resolve-hooks, with
+call sites in 21 of the workflows, and checklist-read / checklist-apply, which produce the
+analyze phases' LIFT-FAILURE findings), and every one of them was read in bash when the
+workflows were reviewed.
+
+WHAT IT CHECKS
+  1. Every bash payload has a byte-identical PowerShell twin.
+  2. Every PowerShell payload has a byte-identical bash twin.
+Payloads with no twin are listed, not counted against a hard-coded number: the split is
+whatever the files say today, and pinning it would need editing on every legitimate change.
+
+DUAL-AUTHORED BY DECISION. The ops in ACCEPTED_BASH_ONLY are bash-only on purpose (their
+PowerShell path is written natively rather than shared) and are reported separately, so the
+exit code reacts only to a NEW divergence. Moving one out of that list means it gained a
+shared payload; adding one means the decision was taken to dual-author it — and either way
+the reviewer has to say so in the same commit.
+
+  exit 0  every payload is paired, or unpaired only by accepted decision
+  exit 1  a new unpaired payload, or a pair that has drifted apart
+
+Usage:  aw-payload-parity.py [--root DIR] [--verbose]
+"""
+
+import argparse
+import hashlib
+import os
+import re
+import sys
+
+SH_REL = ".appweaver/scripts/bash/aw-spec-actions.sh"
+PS_REL = ".appweaver/scripts/powershell/aw-spec-actions.ps1"
+
+# Bash payloads with no shared PowerShell twin BY DECISION, not by oversight. Each is
+# implemented natively on the PowerShell side and the two must be reviewed in pairs.
+ACCEPTED_BASH_ONLY = {
+    "cmd_resolve_hooks",
+    "cmd_list_contexts",
+    "cmd_context_paths",
+    "cmd_list_features",
+    # The two change-listing ops. Both walk changes/<cr-id>/ and read a header line out of
+    # each delta document — directory enumeration and a regex, which PowerShell does
+    # natively without paying for a python spawn per invocation. Short enough to review as
+    # a pair, which is the bar for this list.
+    "cmd_cr_list",
+    "cmd_cr_paths",
+    # 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",
+    # 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",
+    "cmd_checklist_read",
+    "cmd_checklist_apply",
+    "cmd_compose_constitution",
+    "cmd_constitution_verify",
+    "cmd_component_verify",
+    "cmd_cr_archive",
+    "cmd_version_stamp",
+}
+
+
+def bash_payloads(text):
+    """[(owning function, payload, first line, last line)] in file order."""
+    out, owner, lines, i = [], "(top level)", text.split("\n"), 0
+    while i < len(lines):
+        m = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\(\)\s*\{", lines[i])
+        if m:
+            owner = m.group(1)
+        if re.search(r"<<'PY'\s*$", lines[i]):
+            j, body = i + 1, []
+            while j < len(lines) and lines[j] != "PY":
+                body.append(lines[j])
+                j += 1
+            out.append((owner, "\n".join(body), i + 2, j))
+            i = j
+        i += 1
+    return out
+
+
+def ps_payloads(text):
+    """[(variable name, payload, first line, last line)] in file order."""
+    out, lines, i = [], text.split("\n"), 0
+    while i < len(lines):
+        m = re.match(r"^\$(Py[A-Za-z0-9_]*)\s*=\s*@'\s*$", lines[i])
+        if m:
+            j, body = i + 1, []
+            while j < len(lines) and lines[j] != "'@":
+                body.append(lines[j])
+                j += 1
+            out.append((m.group(1), "\n".join(body), i + 2, j))
+            i = j
+        i += 1
+    return out
+
+
+def digest(s):
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def main():
+    ap = argparse.ArgumentParser(description="check bash/PowerShell python-payload parity")
+    ap.add_argument("--root", default="", help="kit root (default: this script's kit)")
+    ap.add_argument("--verbose", action="store_true", help="list every matched pair too")
+    args = ap.parse_args()
+
+    root = args.root or os.path.normpath(
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", ".."))
+    sh_path, ps_path = os.path.join(root, SH_REL), os.path.join(root, PS_REL)
+    for p in (sh_path, ps_path):
+        if not os.path.isfile(p):
+            print("aw-payload-parity: not found: %s" % p, file=sys.stderr)
+            return 2
+
+    sh = bash_payloads(open(sh_path, encoding="utf-8").read())
+    ps = ps_payloads(open(ps_path, encoding="utf-8").read())
+
+    ps_by_hash = {}
+    for name, body, a, b in ps:
+        ps_by_hash.setdefault(digest(body), []).append((name, a, b))
+    sh_by_hash = {}
+    for owner, body, a, b in sh:
+        sh_by_hash.setdefault(digest(body), []).append((owner, a, b))
+
+    paired, accepted, unpaired_sh, unpaired_ps = [], [], [], []
+    for owner, body, a, b in sh:
+        twin = ps_by_hash.get(digest(body))
+        if twin:
+            paired.append((owner, twin[0][0]))
+        elif owner in ACCEPTED_BASH_ONLY:
+            accepted.append((owner, a, b))
+        else:
+            unpaired_sh.append((owner, a, b))
+    for name, body, a, b in ps:
+        if not sh_by_hash.get(digest(body)):
+            unpaired_ps.append((name, a, b))
+
+    print("payload parity: %d bash, %d powershell, %d byte-identical pair(s)"
+          % (len(sh), len(ps), len(paired)))
+    if args.verbose:
+        for owner, name in paired:
+            print("  ok  %-34s == $%s" % (owner, name))
+    if accepted:
+        print("\ndual-authored by decision (%d) — PowerShell implements these natively, so a "
+              "change to one must be mirrored by hand:" % len(accepted))
+        for owner, a, b in accepted:
+            print("  --  %-34s %s:%d-%d" % (owner, os.path.basename(sh_path), a, b))
+
+    failed = bool(unpaired_sh or unpaired_ps)
+    if unpaired_sh:
+        print("\nFAIL — bash payloads with no byte-identical PowerShell twin:")
+        for owner, a, b in unpaired_sh:
+            print("  !!  %-34s %s:%d-%d" % (owner, os.path.basename(sh_path), a, b))
+    if unpaired_ps:
+        print("\nFAIL — PowerShell payloads with no byte-identical bash twin:")
+        for name, a, b in unpaired_ps:
+            print("  !!  $%-33s %s:%d-%d" % (name, os.path.basename(ps_path), a, b))
+    if failed:
+        print("\nA payload changed in one shell and not the other, or a new op shipped to one "
+              "shell only. Copy the payload verbatim into its twin — they are byte-identical "
+              "by contract — or, if the op is deliberately dual-authored, add its function to "
+              "ACCEPTED_BASH_ONLY in this file and say why in the commit.")
+    return 1 if failed else 0
+
+
+sys.exit(main())

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

@@ -901,9 +901,13 @@ def cmd_resolve(args):
 # when implement writes into it. Every phase that READS the subtree — implement,
 # build, run, onboard — leaves the check on.
 
+# Named in the "no <kind> lane is declared, and %s needs one" message, for a caller that
+# passed --require but no --command of its own. `implement` covers both lanes in one
+# command and requires neither kind, so it passes no --require at all and never reaches
+# these.
 KIND_PHASES = {
-    "backend": "implement / implement-delta / build / run",
-    "frontend": "ui-implement / ui-implement-delta",
+    "backend": "implement's service lane / build / run",
+    "frontend": "implement's frontend lane",
 }