loopagent-gate 0.4.2__py3-none-any.whl

loopgate/gates/check_visual.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Visual checks — what an operator *sees*, not only what the JSON says.
+
+Why a separate script: the product and technical gates read machine reports. A person reads a page. The
+difference matters — a page can be technically correct and visually wrong (a FAIL row rendered green, a
+verdict buried below the fold, an empty queue table that looks like a broken page). Those are user-facing
+defects that no JSON assertion catches, and they are exactly what the `qa` role is for.
+
+Mechanism: render the operator status page, serve it locally, capture a screenshot and the DOM with headless
+Chrome, then judge the DOM against the scenario's required/forbidden text. The screenshot is kept as an
+artefact for the vision review step (a human or the agent looks at it; a text assertion cannot see layout).
+
+Requires Google Chrome (headless); fail-closed when it is absent — a visual check that silently skips is
+worse than no visual check.
+
+Usage
+-----
+    python3 -m loopgate.gates.check_visual --list
+    python3 -m loopgate.gates.check_visual                     # capture + judge every scenario
+    python3 -m loopgate.gates.check_visual --strict            # SKIP becomes FAIL
+    python3 -m loopgate.gates.check_visual --scenario V01 --verbose
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import datetime as dt
+import functools
+import http.server
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+
+ROOT = project_root()
+
+from loopgate.gates import render_status_page  # noqa: E402  (sibling script: the page under test)
+
+PASS_MARKER = "VISUAL_CHECK_PASS_0001"
+STOP_MARKER = "VISUAL_CHECK_STOP_0001"
+SCENARIOS_REL = "configs/visual_scenarios.json"
+SHOT_DIR_REL = "artifacts/visual_checks"
+CHROME_CANDIDATES = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium",
+]
+
+
+def load_scenarios(root: str = ROOT) -> dict:
+    with open(os.path.join(root, SCENARIOS_REL), encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def chrome_binary() -> str | None:
+    for candidate in CHROME_CANDIDATES:
+        if os.path.exists(candidate):
+            return candidate
+    return shutil.which("google-chrome") or shutil.which("chromium") or None
+
+
+# ---------------------------------------------------------------- evaluation (pure)
+
+def evaluate(scenario: dict, observation: dict) -> list[str]:
+    """Reasons the observed page violates the scenario; empty list = the page passes.
+
+    Pure so the technical gate can attack it (D13) with falsified DOM snapshots.
+    """
+    exp = scenario.get("expect") or {}
+    dom = observation.get("dom") or ""
+    reasons: list[str] = []
+    for needle in exp.get("require_text") or []:
+        if needle not in dom:
+            reasons.append(f"a user would not see {needle!r} on the page")
+    for needle in exp.get("forbid_text") or []:
+        if needle in dom:
+            reasons.append(f"the page shows {needle!r}, which must not be visible to a user")
+    if exp.get("visible_cell_truncation"):
+        import re as _re
+        width = int(exp.get("cell_width", 70))
+        for cell in _re.findall(r"<td[^>]*>([^<>]+)</td>", dom):
+            text = cell.strip()
+            # The renderer clips long cells to `width` characters, ending with an ellipsis. A cell at or over
+            # that width without the ellipsis is text cut mid-word — visible to a user, invisible to a JSON check.
+            if len(text) >= width and not text.endswith("…"):
+                reasons.append(f"a table cell is cut mid-word without an ellipsis: {text[-28:]!r}")
+    shot = observation.get("screenshot")
+    if exp.get("screenshot_required") and not (shot and os.path.exists(shot)):
+        reasons.append("no screenshot was captured, so nobody can look at the page")
+    if exp.get("min_bytes") and observation.get("screenshot_bytes", 0) < exp["min_bytes"]:
+        reasons.append(f"the screenshot is {observation.get('screenshot_bytes', 0)} bytes "
+                       f"(< {exp['min_bytes']}), so the page most likely rendered blank")
+    return reasons
+
+
+# ---------------------------------------------------------------- capture
+
+class _Handler(http.server.SimpleHTTPRequestHandler):
+    def log_message(self, *args):  # keep the check output readable
+        pass
+
+
+def serve(directory: str) -> tuple[http.server.ThreadingHTTPServer, int]:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        port = int(sock.getsockname()[1])
+    handler = functools.partial(_Handler, directory=directory)
+    server = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server, port
+
+
+def capture(chrome: str, url: str, shot_path: str, width: int = 1280, height: int = 1400) -> tuple[str, int]:
+    """Return (dom, screenshot bytes). Both come from one headless Chrome run each."""
+    os.makedirs(os.path.dirname(shot_path), exist_ok=True)
+    shot = subprocess.run([chrome, "--headless=new", "--disable-gpu", "--hide-scrollbars",
+                           f"--window-size={width},{height}", f"--screenshot={shot_path}", url],
+                          capture_output=True, text=True, timeout=60)
+    if shot.returncode != 0 or not os.path.exists(shot_path):
+        return "", 0
+    dom_proc = subprocess.run([chrome, "--headless=new", "--disable-gpu", "--dump-dom", url],
+                              capture_output=True, text=True, timeout=60)
+    dom = dom_proc.stdout if dom_proc.returncode == 0 else ""
+    return dom, os.path.getsize(shot_path)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Visual checks over the operator status page.")
+    ap.add_argument("--root", default=ROOT)
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--scenario", action="append")
+    ap.add_argument("--strict", action="store_true")
+    ap.add_argument("--verbose", action="store_true")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    try:
+        config = load_scenarios(args.root)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        print(STOP_MARKER)
+        return 2
+
+    scenarios = config["scenarios"]
+    if args.list:
+        for sc in scenarios:
+            flag = "optional" if sc.get("optional") else "mandatory"
+            print(f"  {sc['id']}  [{flag}] {sc['page']:<22} {sc['title']}")
+        return 0
+    if args.scenario:
+        wanted = set(args.scenario)
+        scenarios = [s for s in scenarios if s["id"] in wanted] or []
+
+    chrome = chrome_binary()
+    print("VISUAL CHECK — loopgate/gates/check_visual.py")
+    print(f"page: {config['page']}   chrome: {chrome or '(not found)'}")
+    print()
+    if chrome is None:
+        print("[FAIL] no headless Chrome/Chromium on this machine: a visual check that silently skips is "
+              "worse than none")
+        print(STOP_MARKER)
+        return 1
+
+    render_status_page.main(["--root", args.root])
+    server, port = serve(os.path.join(args.root, "artifacts"))
+    results, failures, skips = [], [], []
+    try:
+        for sc in scenarios:
+            shot = os.path.join(args.root, SHOT_DIR_REL, f"{sc['id']}_{sc['page'].replace('/', '_')}.png")
+            dom, size = capture(chrome, f"http://127.0.0.1:{port}/{sc['page']}", shot)
+            observation = {"dom": dom, "screenshot": shot, "screenshot_bytes": size}
+            if not dom:
+                observation["skip"] = "the page did not render (Chrome returned no DOM)"
+            reasons = evaluate(sc, observation)
+            status = "SKIP" if observation.get("skip") else ("OK" if not reasons else "FAIL")
+            if status == "SKIP" and args.strict:
+                status, reasons = "FAIL", [f"prerequisite missing: {observation['skip']}"]
+            results.append({"id": sc["id"], "title": sc["title"], "page": sc["page"], "status": status,
+                            "reasons": reasons, "screenshot": os.path.relpath(shot, args.root),
+                            "screenshot_bytes": size})
+            print(f"{sc['id']} [{status}] {sc['title']}")
+            if observation.get("skip"):
+                print(f"       - SKIP: {observation['skip']}")
+            for reason in reasons:
+                print(f"       - {reason}")
+            if args.verbose and size:
+                print(f"       - screenshot {os.path.relpath(shot, args.root)} ({size} bytes)")
+            if status == "FAIL":
+                failures.append(sc["id"])
+            if status == "SKIP":
+                skips.append(sc["id"])
+    finally:
+        server.shutdown()
+
+    ok = not failures
+    print()
+    print(f"visual scenarios: {len(results) - len(failures) - len(skips)} ok, {len(failures)} fail, "
+          f"{len(skips)} skip")
+    report = {"marker": PASS_MARKER if ok else STOP_MARKER, "page": config["page"],
+              "generated_at": dt.datetime.now().astimezone().isoformat(timespec="seconds"),
+              "scenarios": results, "failures": failures, "skips": skips}
+    report_path = os.path.join(args.root, config.get("report", "artifacts/visual_check_report.json"))
+    os.makedirs(os.path.dirname(report_path), exist_ok=True)
+    with open(report_path, "w", encoding="utf-8") as fh:
+        json.dump(report, fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+    print(f"report: {os.path.relpath(report_path, args.root)}")
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    if ok:
+        print(PASS_MARKER)
+        return 0
+    print(STOP_MARKER)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgate/gates/doctor.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Report what this machine can and cannot run, before a failure is mistaken for a code defect.
+
+Why: the gates silently degrade when an input is missing — a product scenario SKIPs without jsonschema, a
+visual check fails without Chrome, the queue needs git and (optionally) `gh`. Every one of those is a
+one-line answer to "why is this yellow?", and without this script the answer is an afternoon of reading.
+It also pins the interpreter question: `#!/usr/bin/env python3` resolves to whatever the PATH holds, so
+two interpreters on one machine can give two verdicts for the same tree.
+
+    python3 -m loopgate.gates.doctor
+    python3 -m loopgate.gates.doctor --json
+
+Exit 0 always: this is a report, not a gate. The gates decide.
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+ROOT = project_root()
+MARKER = "DOCTOR_REPORT_0001"
+
+
+def probe_jsonschema() -> tuple[str, str]:
+    """('ok' | 'missing' | 'damaged', detail) — the distinction the product gate makes."""
+    try:
+        import jsonschema  # noqa: F401
+        import referencing  # noqa: F401
+        import referencing.jsonschema  # noqa: F401
+    except ImportError as exc:
+        detail = str(exc)
+        if "rpds" in detail or "referencing" in detail:
+            return "damaged", detail
+        return "missing", detail
+    return "ok", ""
+
+
+def which(binary: str) -> str | None:
+    return shutil.which(binary)
+
+
+def git_status() -> str:
+    try:
+        proc = subprocess.run(["git", "-C", ROOT, "status", "--porcelain"], capture_output=True, text=True)
+    except OSError as exc:
+        return f"unavailable ({exc})"
+    if proc.returncode != 0:
+        return f"error: {proc.stderr.strip()}"
+    changed = len([line for line in proc.stdout.splitlines() if line.strip()])
+    return "clean" if changed == 0 else f"{changed} changed path(s)"
+
+
+def gh_auth() -> str:
+    if not which("gh"):
+        return "gh not installed (issue bridge unavailable; --issues-file and --target backlog still work)"
+    try:
+        proc = subprocess.run(["gh", "auth", "status"], capture_output=True, text=True)
+    except OSError as exc:
+        return f"unavailable ({exc})"
+    return "authenticated" if proc.returncode == 0 else "not authenticated (run `gh auth login`)"
+
+
+def chrome() -> str:
+    candidates = [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    ]
+    for path in candidates:
+        if os.path.exists(path):
+            return path
+    for name in ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser"):
+        found = which(name)
+        if found:
+            return found
+    return "not found (visual checks will fail closed)"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Report interpreter and optional inputs.")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    jsonschema_state, jsonschema_detail = probe_jsonschema()
+    report = {
+        "marker": MARKER,
+        "python": {"version": sys.version.split()[0], "executable": sys.executable,
+                   "meets_floor_3_9": sys.version_info >= (3, 9)},
+        "optional": {
+            "jsonschema": {"state": jsonschema_state, "detail": jsonschema_detail,
+                           "repair": ("python3 -m pip install --force-reinstall rpds-py referencing"
+                                      if jsonschema_state == "damaged"
+                                      else "python3 -m pip install jsonschema")},
+            "chrome": chrome(),
+            "gh": gh_auth(),
+        },
+        "repo": {"root": ROOT, "git": which("git") or "missing", "working_tree": git_status()},
+    }
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
+    else:
+        print("doctor — what this machine can run")
+        print()
+        print(f"  python       {report['python']['version']}  ({report['python']['executable']})")
+        if not report["python"]["meets_floor_3_9"]:
+            print("               WARNING: below the supported floor (3.9)")
+        state = jsonschema_state
+        detail = f" — {jsonschema_detail}" if jsonschema_detail else ""
+        print(f"  jsonschema   {state}{detail}")
+        if state != "ok":
+            print(f"               repair: {report['optional']['jsonschema']['repair']}")
+            print("               effect: product scenario P08 (published contracts) reports SKIP")
+        print(f"  chrome       {report['optional']['chrome']}")
+        print(f"  gh           {report['optional']['gh']}")
+        print(f"  git          {report['repo']['git']}; working tree {report['repo']['working_tree']}")
+        print()
+        print("Interpreters disagree: `python3` on PATH is what `make gate` uses, so if this report is "
+              "not the verdict you expected, run with `make gate PYTHON=<path>`.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgate/gates/estimate_task.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Task timeboxes from measured history (the answer to "how long will this take, and who decides?").
+
+Why this file exists
+--------------------
+Nobody should guess a task's duration, and the supervisor is the worst possible estimator: it is the party
+whose optimism is being tested. The queue already produces the data — every kanban run records when it
+started and when it finished — so the estimate is *measured*, not promised:
+
+    p50 = what a task of this kind usually costs
+    p90 = what it costs when it goes badly
+    cap = 2 x p90, rounded up, passed to the dispatcher as ``--max-runtime``
+
+The cap is not a prediction: it is the point where the dispatcher SIGTERMs the worker and re-queues the
+task, which turns "it ran forever" into a visible failure. Per-assignee, because a reviewer's p90 and an
+implementer's p90 have nothing to do with each other.
+
+Who estimates: the queue, from its own history (this script), and the operator approves the proposal by
+committing ``configs/task_estimates.json``. The bridge then applies the cap to every queued task.
+
+Usage
+-----
+    python3 -m loopgate.gates.estimate_task                 # show the measured distribution and the proposal
+    python3 -m loopgate.gates.estimate_task --write         # write configs/task_estimates.json (review, then commit)
+    python3 -m loopgate.gates.estimate_task --json
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import datetime as dt
+import json
+import os
+import subprocess
+import sys
+
+ROOT = project_root()
+ESTIMATES_REL = "configs/task_estimates.json"
+MIN_CAP_MINUTES = 15
+ROUNDING_MINUTES = 5
+# Below this many finished runs a percentile is noise, so the proposal stays at the floor and says so.
+MIN_SAMPLES = 3
+
+
+def kanban_tasks() -> list[dict]:
+    proc = subprocess.run(["hermes", "kanban", "list", "--json", "--archived"],
+                          capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError(f"hermes kanban list failed ({proc.returncode}): {proc.stderr.strip()}")
+    return json.loads(proc.stdout or "[]")
+
+
+def durations_minutes(tasks: list[dict]) -> dict[str, list[float]]:
+    out: dict[str, list[float]] = {}
+    for task in tasks:
+        started, completed = task.get("started_at"), task.get("completed_at")
+        assignee = task.get("assignee") or "(unassigned)"
+        if not started or not completed or completed < started:
+            continue
+        out.setdefault(assignee, []).append((completed - started) / 60.0)
+    return out
+
+
+def percentile(values: list[float], fraction: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    index = min(len(ordered) - 1, max(0, int(round(fraction * (len(ordered) - 1)))))
+    return ordered[index]
+
+
+def round_up(value: float, step: int = ROUNDING_MINUTES) -> int:
+    return int(step * -(-value // step))
+
+
+def propose(measured: dict[str, list[float]]) -> dict:
+    proposal = {"generated_at": dt.datetime.now().astimezone().isoformat(timespec="seconds"),
+                "rule": f"cap = max({MIN_CAP_MINUTES} min, round_up(2 x p90, {ROUNDING_MINUTES} min)); "
+                        f"needs >= {MIN_SAMPLES} finished runs before the percentiles mean anything",
+                "assignees": {}}
+    for assignee, values in sorted(measured.items()):
+        p50, p90 = percentile(values, 0.5), percentile(values, 0.9)
+        if len(values) < MIN_SAMPLES:
+            cap = MIN_CAP_MINUTES
+            basis = f"floor: only {len(values)} finished run(s)"
+        else:
+            cap = max(MIN_CAP_MINUTES, round_up(2 * p90))
+            basis = f"2 x p90({p90:.1f} min) over {len(values)} run(s)"
+        proposal["assignees"][assignee] = {"samples": len(values), "p50_minutes": round(p50, 1),
+                                           "p90_minutes": round(p90, 1), "max_runtime": f"{cap}m",
+                                           "basis": basis}
+    return proposal
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Derive per-assignee task timeboxes from kanban history.")
+    ap.add_argument("--root", default=ROOT)
+    ap.add_argument("--write", action="store_true", help=f"write {ESTIMATES_REL}")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    try:
+        measured = durations_minutes(kanban_tasks())
+    except (OSError, RuntimeError, json.JSONDecodeError) as exc:
+        print(f"cannot read the queue history: {exc}", file=sys.stderr)
+        return 1
+    if not measured:
+        print("no finished runs yet: nothing to measure, every cap stays at the floor")
+        return 1
+
+    proposal = propose(measured)
+    if args.json:
+        print(json.dumps(proposal, ensure_ascii=False, indent=2))
+    else:
+        print("measured task durations (finished kanban runs)")
+        print(f"{'assignee':<14}{'runs':>6}{'p50':>9}{'p90':>9}{'cap':>8}  basis")
+        for assignee, row in proposal["assignees"].items():
+            print(f"{assignee:<14}{row['samples']:>6}{row['p50_minutes']:>9.1f}{row['p90_minutes']:>9.1f}"
+                  f"{row['max_runtime']:>8}  {row['basis']}")
+        print()
+        print("a cap is not a promise: at the cap the dispatcher SIGTERMs the worker and re-queues the task,")
+        print("so 'it ran forever' becomes a visible failure instead of a silent one.")
+
+    if args.write:
+        path = os.path.join(args.root, ESTIMATES_REL)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(proposal, fh, ensure_ascii=False, indent=2)
+            fh.write("\n")
+        print(f"wrote {ESTIMATES_REL} — review it and commit; the bridge applies it to queued tasks")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())