aw-spec-cli 0.1.20 → 0.1.22

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

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""
+aw-plangate — the analyze-plan receipt, written and read in one place.
+
+THE RECEIPT. `analyze-plan` records which bytes it checked against each other — spec.md,
+the context's domain-model.md and every lane plan on disk — and the verdict it reached.
+`implement` generates from the plans and deliberately does NOT read the spec, on the
+strength of that receipt, so the pair of operations that write and read it is the hinge the
+whole bootstrap path turns on.
+
+WHY IT LIVES HERE. Both halves were embedded twice, as a bash heredoc and as a natively
+re-written PowerShell function, and the rule they implement is a set of sha comparisons
+with three deliberate asymmetries in it — an absent spec sha does not block, an absent
+model sha does, and an unrecognised verdict records as `gaps`. That rule changed twice
+(MF-19, then MF-20) and each time it had to be re-derived by hand on the PowerShell side
+and kept in step by eye. One module both shells invoke removes the question: there is
+nothing left to keep in step. Same reason aw-crstate.py owns "has this change merged".
+
+NO BASELINE IS NOT "NOTHING MOVED". `spec_moved` / `model_moved` report "" where there is
+nothing to compare against — no receipt, or a receipt that hashed nothing for that
+document. "" is falsy in Python, in PowerShell and to the engine's require_true, so every
+flag computed from them reads exactly as a false did; what it buys is that a reader can
+tell "unchanged" from "unknown", which a bare false cannot express.
+
+Usage:
+  aw-plangate.py stamp --feature-dir <p> --context-dir <p> --root <p>
+                       [--spec-version <v>] [--mode <text>]
+                       [--verdict conformant|routed-gaps|gaps] [--plan-gaps <n>]
+                       [--routed <json list>]
+      -> {file, gated, spec_version, verdict, plan_gaps, routed_gaps, hashed[], count}
+  aw-plangate.py check --feature-dir <p> --context-dir <p> --root <p>
+      -> {file, tracked, gate_fresh, verdict, may_generate, plan_gaps, routed_gaps[],
+          routed_csv, spec_moved, model_moved, plans_changed[], plans_changed_csv,
+          gated, spec_version, reason}
+"""
+
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import sys
+
+RECEIPT = ".aw-plan-gate.json"
+VERDICTS = ("conformant", "routed-gaps", "gaps")
+
+# 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.
+PLAN_NAMES = ("backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md")
+
+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.")
+
+
+def sha(path):
+    try:
+        with open(path, "rb") as fh:
+            return hashlib.sha256(fh.read()).hexdigest()
+    except Exception:
+        return ""
+
+
+def stamp(fd, ctx, root, spec_version="", mode="master", verdict="conformant",
+          plan_gaps=0, routed=None):
+    plans = {}
+    for name in PLAN_NAMES:
+        h = sha(os.path.join(fd, name))
+        if h:
+            plans[name] = h
+    # An unrecognised verdict is recorded as `gaps`, the one that refuses.
+    verdict = (verdict or "").strip()
+    if verdict not in VERDICTS:
+        verdict = "gaps"
+    try:
+        plan_gaps = int(plan_gaps or 0)
+    except (TypeError, ValueError):
+        plan_gaps = 0
+    routed = [str(x) for x in (routed or [])]
+    rec = {
+        "gated": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "gate_mode": mode or "master",
+        "spec_version": (spec_version or "").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": NOTE,
+    }
+    path = os.path.join(fd, RECEIPT)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(json.dumps(rec, indent=2) + "\n")
+    return {"file": os.path.relpath(path, root), "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}
+
+
+def check(fd, ctx, root):
+    path = os.path.join(fd, RECEIPT)
+    try:
+        rec = json.load(open(path, encoding="utf-8"))
+    except Exception:
+        rec = None
+    out = {"file": os.path.relpath(path, root), "tracked": bool(rec), "gate_fresh": False,
+           "verdict": "", "may_generate": True, "plan_gaps": 0, "routed_gaps": [],
+           "routed_csv": "", "spec_moved": "", "model_moved": "", "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")
+        return out
+
+    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"])
+
+    # A receipt that hashed nothing for a document has no baseline for it either, so the
+    # question is unanswerable for that one document and says so.
+    spec_base = rec.get("spec_sha") or ""
+    out["spec_moved"] = (spec_base != sha(os.path.join(fd, "spec.md"))) if spec_base else ""
+    # 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 — that stays a
+    # move, including for a receipt predating model_sha, because a model nothing has been
+    # checked against is the condition this field exists to catch. Only a receipt carrying
+    # no model_sha with no model on disk either leaves nothing to compare.
+    model_base = rec.get("model_sha")
+    model_now = sha(os.path.join(ctx, "domain-model.md"))
+    out["model_moved"] = ((model_base or "") != model_now
+                          if (model_base is not None or model_now) else "")
+
+    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"])
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="the analyze-plan receipt, written and read")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name in ("stamp", "check"):
+        p = sub.add_parser(name)
+        p.add_argument("--feature-dir", required=True)
+        p.add_argument("--context-dir", required=True)
+        p.add_argument("--root", required=True)
+        if name == "stamp":
+            p.add_argument("--spec-version", default="")
+            p.add_argument("--mode", default="master")
+            p.add_argument("--verdict", default="conformant")
+            p.add_argument("--plan-gaps", default="0")
+            p.add_argument("--routed", default="[]")
+    args = ap.parse_args()
+
+    if args.cmd == "stamp":
+        try:
+            routed = json.loads(args.routed or "[]")
+        except Exception:
+            routed = []
+        if not isinstance(routed, list):
+            routed = []
+        out = stamp(args.feature_dir, args.context_dir, args.root, args.spec_version,
+                    args.mode, args.verdict, args.plan_gaps, routed)
+    else:
+        out = check(args.feature_dir, args.context_dir, args.root)
+    sys.stdout.write(json.dumps(out) + "\n")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+aw-principles — enumerate the ratified NON-NEGOTIABLE principles.
+
+WHY A SCRIPT AND NOT A JUDGEMENT. `specify` settles [NEEDS CLARIFICATION] markers by
+asking, and a non-interactive run answers with the FIRST option offered — so an agent's
+option ordering becomes project policy unattended. The gate that checks those answers
+against the constitution has to name the principle it is invoking, and an agent asked to
+both find the principle and judge the contradiction can invent the principle it then
+objects to. Splitting it means the factual half is checkable: this module reads the
+headings and nothing else, the agent judges only whether a settled answer departs from
+one of THESE, and a citation outside the list is visibly wrong.
+
+It also answers "are there any?" deterministically. A project whose constitution ratifies
+no NON-NEGOTIABLE principle has nothing for the gate to check, and `count` is what lets
+the workflow skip it rather than asking an agent to confirm an empty set.
+
+WHAT COUNTS. A principle heading of the form `### <id>. <title> (NON-NEGOTIABLE)`, which
+is what all three constitution templates emit. The id is whatever precedes the first
+period — roman numerals in the domain and technical halves, `UX-`-prefixed in the UI half
+— so a project that renumbers or re-prefixes its series needs no change here.
+
+HTML comments are stripped first. The Sync Impact Report at the top of every constitution
+quotes principle headings while recording what a ratification changed, and counting those
+would report principles that are not in force.
+
+Usage:
+  aw-principles.py list --root <p> [--file <p> ...]
+      -> {files[], missing[], principles[{file, id, title, line}], count, titles_csv, ok}
+
+  Default files are the two halves `specify` loads — constitution.domain.md and
+  constitution.ui.md. The technical half is NOT a default: specify never loads it (a
+  spec is WHAT, not HOW), so a gate there could cite a principle the authoring agent was
+  never shown. A caller that loads it passes --file.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+DEFAULT_FILES = (".appweaver/memory/constitution.domain.md",
+                 ".appweaver/memory/constitution.ui.md")
+
+# `### XXIII. Clinical Meaning is Bound, Never Free Text (NON-NEGOTIABLE)`
+# `### UX-I. Accessibility Floor (NON-NEGOTIABLE)`
+HEADING = re.compile(r"^###\s+([^.]+)\.\s+(.+?)\s*\(NON-NEGOTIABLE\)\s*$")
+COMMENT = re.compile(r"<!--.*?-->", re.S)
+
+
+def read(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except Exception:
+        return None
+
+
+def principles_in(path, rel):
+    """[{file, id, title, line}] for one constitution half, in document order."""
+    text = read(path)
+    if text is None:
+        return None
+    # Blank the comments rather than deleting them, so reported line numbers still
+    # point at the heading in the file a reader opens.
+    text = COMMENT.sub(lambda m: "\n" * m.group(0).count("\n"), text)
+    out = []
+    for n, line in enumerate(text.split("\n"), 1):
+        m = HEADING.match(line)
+        if m:
+            out.append({"file": rel, "id": m.group(1).strip(),
+                        "title": m.group(2).strip(), "line": n})
+    return out
+
+
+def listing(root, files):
+    seen, missing, found = [], [], []
+    for rel in files:
+        path = rel if os.path.isabs(rel) else os.path.join(root, rel)
+        got = principles_in(path, rel)
+        if got is None:
+            missing.append(rel)
+            continue
+        seen.append(rel)
+        found.extend(got)
+    return {"files": seen, "missing": missing, "principles": found,
+            "count": len(found),
+            "titles_csv": "; ".join("%s (%s %s)" % (p["title"], os.path.basename(p["file"]),
+                                                    p["id"]) for p in found),
+            "ok": True}
+
+
+def main():
+    ap = argparse.ArgumentParser(description="enumerate ratified NON-NEGOTIABLE principles")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("list")
+    p.add_argument("--root", required=True)
+    p.add_argument("--file", action="append", default=[],
+                   help="a constitution half to scan (repeatable; defaults to domain + ui)")
+    args = ap.parse_args()
+
+    out = listing(args.root, args.file or list(DEFAULT_FILES))
+    sys.stdout.write(json.dumps(out) + "\n")
+
+
+if __name__ == "__main__":
+    main()