loopagent-gate 0.4.2__py3-none-any.whl

loopgate/gates/anchor_witness.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Anchor witness — the gate's verdict leaves the machine, so a silent rewrite is detectable.
+
+The residual risk this closes (``risk=4`` in ``artifacts/loop_state.json``)
+-----------------------------------------------------------------------
+Every input the technical gate reads is authored on this machine, so a fabricated anchor is *detectable by
+a command* but not *impossible*. Two things change that:
+
+1. **Signature.** The binding anchor (``artifacts/loop_gate_pass.json``) is signed with a dedicated,
+   purpose-limited SSH key (``~/.ssh/loop_anchor_ed25519``; its public half is committed in
+   ``configs/allowed_signers``). Any later edit of the anchor without that key fails verification, so the
+   anchor cannot be quietly re-minted to describe a run that did not happen.
+2. **External timestamp.** ``publish`` writes the anchor digest + signature as a comment on a GitHub issue,
+   where the timestamp is the platform's, not ours. A coordinated rewrite now has to contradict a record we
+   do not control.
+
+Honest boundary: the signing key lives on the same machine, so the signature alone proves "written by the
+holder of this key", not "written by an independent party". The external publication is what makes a
+*coordinated* rewrite visible. The gate checks the signature locally (no network); ``check-external`` is the
+operator-run step that verifies the published copy.
+
+Usage
+-----
+    python3 -m loopgate.gates.anchor_witness sign              # sign the current anchor
+    python3 -m loopgate.gates.anchor_witness verify            # local: signature over the current anchor
+    python3 -m loopgate.gates.anchor_witness publish           # post digest+signature to the witness log
+    python3 -m loopgate.gates.anchor_witness check-external    # read the log back and compare digests
+    python3 -m loopgate.gates.anchor_witness status
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+
+ROOT = project_root()
+ANCHOR_REL = "artifacts/loop_gate_pass.json"
+VERDICT_REL = "artifacts/loop_gate_verdict.txt"
+# ssh-keygen writes <message>.sig next to the message, so the signature lives beside the signed payload.
+SIG_REL = "artifacts/loop_gate_verdict.txt.sig"
+WITNESS_REL = "artifacts/anchor_witness.json"
+CONFIG_REL = "configs/anchor_witness.json"
+PASS_MARKER = "ANCHOR_WITNESS_PASS_0001"
+STOP_MARKER = "ANCHOR_WITNESS_STOP_0001"
+
+
+def load_config(root: str = ROOT) -> dict:
+    with open(os.path.join(root, CONFIG_REL), encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def digest_of(path: str) -> str:
+    with open(path, "rb") as fh:
+        return hashlib.sha256(fh.read()).hexdigest()
+
+
+def verdict_payload(anchor_path: str) -> bytes:
+    """What gets signed: the verdict, not the file.
+
+    The anchor carries a fresh ``generated_at`` on every run, so signing the file would invalidate the
+    witness after each gate run. The verdict (marker + verdict hash) is stable while the verdict set is
+    stable, which is exactly what a witness should pin.
+    """
+    with open(anchor_path, encoding="utf-8") as fh:
+        payload = json.load(fh)
+    return f"marker={payload.get('marker')}\nverdict_hash={payload.get('verdict_hash')}\n".encode()
+
+
+def sign(root: str, config: dict) -> tuple[bool, str]:
+    anchor = os.path.join(root, ANCHOR_REL)
+    sig = os.path.join(root, SIG_REL)
+    message = os.path.join(root, VERDICT_REL)
+    key = os.path.expanduser(config["signing_key"])
+    with open(message, "wb") as fh:
+        fh.write(verdict_payload(anchor))
+    # ssh-keygen -Y sign silently keeps an existing signature file (exit 0, old signature left in place),
+    # so a stale signature would verify the *previous* verdict while looking freshly signed. Remove it first.
+    if os.path.exists(sig):
+        os.remove(sig)
+    proc = subprocess.run(["ssh-keygen", "-Y", "sign", "-f", key, "-n", config["namespace"], message],
+                          capture_output=True, text=True)
+    if proc.returncode != 0:
+        return False, f"ssh-keygen sign failed: {proc.stderr.strip()[:200]}"
+    stale = os.path.join(root, "artifacts", "loop_gate_pass.json.sig")
+    if os.path.exists(stale):  # an earlier file-based signature would shadow the verdict one
+        os.remove(stale)
+    record = {"anchor": ANCHOR_REL, "signed_message": VERDICT_REL,
+              "verdict_hash": json.load(open(anchor, encoding="utf-8")).get("verdict_hash"),
+              "payload_sha256": digest_of(message), "namespace": config["namespace"],
+              "identity": config["identity"], "signature_file": SIG_REL,
+              "signer_fingerprint": signer_fingerprint(key)}
+    with open(os.path.join(root, WITNESS_REL), "w", encoding="utf-8") as fh:
+        json.dump(record, fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+    return True, (f"signed the verdict of {ANCHOR_REL} -> {SIG_REL} "
+                  f"(verdict_hash {record['verdict_hash']}, payload sha256 {record['payload_sha256'][:16]}…)")
+
+
+def signer_fingerprint(key: str) -> str:
+    proc = subprocess.run(["ssh-keygen", "-l", "-f", key + ".pub"], capture_output=True, text=True)
+    parts = proc.stdout.split()
+    return parts[1] if len(parts) > 1 else "unknown"
+
+
+def verify(root: str, config: dict, anchor_path: str | None = None, sig_path: str | None = None) -> tuple[bool, str]:
+    """Verify the signature over the *verdict* reconstructed from the anchor on disk.
+
+    Passing a doctored anchor (``anchor_path``) changes the reconstructed message, so a rewrite cannot ride
+    on an old signature.
+    """
+    anchor = anchor_path or os.path.join(root, ANCHOR_REL)
+    sig = sig_path or os.path.join(root, SIG_REL)
+    signers = os.path.join(root, config["allowed_signers"])
+    for path in (anchor, sig, signers):
+        if not os.path.exists(path):
+            return False, f"{os.path.relpath(path, root)} missing (run `sign` first)"
+    proc = subprocess.run(["ssh-keygen", "-Y", "verify", "-f", signers, "-I", config["identity"],
+                           "-n", config["namespace"], "-s", sig],
+                          input=verdict_payload(anchor), capture_output=True)
+    if proc.returncode != 0:
+        note = (proc.stdout or proc.stderr or b"").decode("utf-8", "replace").strip()
+        return False, note[:200] or "signature does not match this verdict"
+    return True, (proc.stdout or b"").decode("utf-8", "replace").strip() + \
+        f" (verdict_hash {json.load(open(anchor, encoding='utf-8')).get('verdict_hash')})"
+
+
+def gh(args: list[str], token: str | None = None) -> tuple[int, str]:
+    env = dict(os.environ)
+    if token:
+        env["GH_TOKEN"] = token
+    proc = subprocess.run(["gh"] + args, capture_output=True, text=True, env=env)
+    return proc.returncode, (proc.stdout or proc.stderr).strip()
+
+
+def github_token() -> str | None:
+    """The token lives in the operator's env or in ~/.dsh/.env; never echoed."""
+    if os.environ.get("GH_TOKEN"):
+        return os.environ["GH_TOKEN"]
+    env_file = os.path.expanduser("~/.dsh/.env")
+    if os.path.exists(env_file):
+        for line in open(env_file, encoding="utf-8"):
+            if line.startswith(("GITHUB_TOKEN=", "GH_TOKEN=")):
+                return line.split("=", 1)[1].strip().strip('"')
+    return None
+
+
+def publish(root: str, config: dict, verbose: bool = False) -> tuple[bool, str]:
+    dest = config["destination"]
+    repo, issue = dest["repo"], str(dest["issue"])
+    witness = json.load(open(os.path.join(root, WITNESS_REL), encoding="utf-8"))
+    # The entry carries the exact bytes that were signed, not a path into this checkout: a reader of the
+    # journal has no tree to resolve, and a digest nobody can recompute is an assertion, not a check. The
+    # payload on disk is re-hashed first, so publishing cannot describe a signature that is no longer the
+    # one that was made.
+    with open(os.path.join(root, VERDICT_REL), "rb") as fh:
+        payload = fh.read()
+    if hashlib.sha256(payload).hexdigest() != witness["payload_sha256"]:
+        return False, (f"{VERDICT_REL} no longer hashes to the signed digest "
+                       f"({witness['payload_sha256'][:16]}…) — re-sign before publishing")
+    body = (f"<!-- {config['marker']} -->\n"
+            f"**{config['marker']}**\n\n"
+            f"- verdict_hash: `{witness['verdict_hash']}`\n"
+            f"- signed message, verbatim:\n\n"
+            f"```text\n{payload.decode('utf-8').strip()}\n```\n\n"
+            f"- payload sha256: `{witness['payload_sha256']}`\n"
+            f"- signer: `{witness['signer_fingerprint']}` ({witness['identity']}, namespace "
+            f"`{witness['namespace']}`)\n"
+            f"- signature: `{witness['signature_file']}` (verify against `{config['allowed_signers']}`)\n")
+    token = github_token()
+    code, existing = gh(["api", f"repos/{repo}/issues/{issue}/comments", "--paginate",
+                         "--jq", ".[].body"], token)
+    if code != 0:
+        return False, f"cannot read the witness log: {existing[:160]}"
+    if witness["verdict_hash"] in existing:
+        return True, f"already published to {repo}#{issue} (verdict already witnessed, nothing to do)"
+    code, out = gh(["issue", "comment", issue, "-R", repo, "--body", body], token)
+    if code != 0:
+        return False, f"cannot publish: {out[:160]}"
+    return True, f"published to {repo}#{issue}: {out.strip()}"
+
+
+def check_external(root: str, config: dict) -> tuple[bool, str]:
+    dest = config["destination"]
+    witness = json.load(open(os.path.join(root, WITNESS_REL), encoding="utf-8"))
+    code, out = gh(["api", f"repos/{dest['repo']}/issues/{dest['issue']}/comments", "--paginate",
+                    "--jq", ".[].body"], github_token())
+    if code != 0:
+        return False, f"cannot read the witness log: {out[:160]}"
+    if witness["verdict_hash"] not in out:
+        return False, (f"the current verdict {witness['verdict_hash']} is not published in "
+                       f"{dest['repo']}#{dest['issue']} — run `publish`")
+    current = json.load(open(os.path.join(root, ANCHOR_REL), encoding="utf-8")).get("verdict_hash")
+    if current != witness["verdict_hash"]:
+        return False, (f"the anchor now carries verdict {current} but the published witness describes "
+                       f"{witness['verdict_hash']} — re-sign and re-publish")
+    return True, f"witnessed: {dest['repo']}#{dest['issue']} carries verdict {witness['verdict_hash']}"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Anchor witness: sign the gate anchor, publish its digest.")
+    ap.add_argument("--root", default=ROOT)
+    ap.add_argument("--verify-anchor", help="verify this anchor file instead of the current one (attack mode)")
+    ap.add_argument("--verify-signature", help="verify this signature file instead of the current one")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("sign")
+    sub.add_parser("verify")
+    sub.add_parser("publish")
+    sub.add_parser("check-external")
+    sub.add_parser("status")
+    args = ap.parse_args(argv)
+
+    try:
+        config = load_config(args.root)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        print(STOP_MARKER)
+        return 2
+
+    if args.cmd == "sign":
+        ok, note = sign(args.root, config)
+    elif args.cmd == "verify":
+        ok, note = verify(args.root, config, args.verify_anchor, args.verify_signature)
+    elif args.cmd == "publish":
+        ok, note = publish(args.root, config)
+    elif args.cmd == "check-external":
+        ok, note = check_external(args.root, config)
+    else:
+        anchor = os.path.join(args.root, ANCHOR_REL)
+        witness_path = os.path.join(args.root, WITNESS_REL)
+        note = (f"anchor {'present' if os.path.exists(anchor) else 'missing'}, "
+                f"signature {'present' if os.path.exists(os.path.join(args.root, SIG_REL)) else 'missing'}, "
+                f"witness {'present' if os.path.exists(witness_path) else 'missing'}; "
+                f"destination {config['destination']['repo']}#{config['destination']['issue']}")
+        ok = True
+        if os.path.exists(witness_path):
+            note += f"; signed verdict {json.load(open(witness_path))['verdict_hash']}"
+    print(note)
+    print(PASS_MARKER if ok else STOP_MARKER)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgate/gates/assert_dims.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Assert that named dimensions are OK in a technical-gate run.
+
+Why this exists: the technical gate's own verdict is `LOOP_ENGINEERING_PASS_0001` only when every
+mandatory dimension is green — and several dimensions read *state* (`artifacts/`, `handoff/`, the signed
+anchor) that a fresh clone does not have by design. CI therefore cannot honestly demand the PASS marker
+from a clone; it can honestly demand that the dimensions which depend only on the code are green.
+
+This script makes that distinction executable instead of a sentence in a README:
+
+    python3 -m loopgate.gates.assert_dims --require D01 D02 D06 D07 D08 D10 D11 D13
+    python3 -m loopgate.gates.assert_dims --require-all      # only where the loop state exists
+
+Exit 0 prints ``CI_DIMS_PASS_0001``; a missing or red dimension prints ``CI_DIMS_STOP_0001`` naming it.
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+ROOT = project_root()
+PASS_MARKER = "CI_DIMS_PASS_0001"
+STOP_MARKER = "CI_DIMS_STOP_0001"
+LINE_RE = re.compile(r"^(D\d\d)\s+\S+\s+\[(OK|FAIL|SKIP)\]")
+
+
+def gate_output(root: str, extra: list[str]) -> tuple[int, str]:
+    # Run the packaged gate as a module from the judged root: a file path would put loopgate/gates/ first on
+    # sys.path and the package import (loopgate.paths) would fail.
+    proc = subprocess.run([sys.executable, "-m", "loopgate.gates.check_loop", *extra],
+                          capture_output=True, text=True, cwd=root)
+    return proc.returncode, proc.stdout + proc.stderr
+
+
+def parse(output: str) -> dict[str, str]:
+    seen: dict[str, str] = {}
+    for line in output.splitlines():
+        m = LINE_RE.match(line.strip())
+        if m:
+            seen[m.group(1)] = m.group(2)
+    return seen
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Assert that named gate dimensions are OK.")
+    ap.add_argument("--root", default=ROOT)
+    ap.add_argument("--require", nargs="*", default=[], metavar="DIM")
+    ap.add_argument("--require-all", action="store_true",
+                    help="require every dimension the gate prints (only where loop state exists)")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args(argv)
+
+    code, output = gate_output(args.root, ["--strict"])
+    dims = parse(output)
+    if not dims:
+        print("the gate printed no dimensions at all — the gate itself is broken", file=sys.stderr)
+        print(output, file=sys.stderr)
+        print(STOP_MARKER)
+        return 1
+
+    required = sorted(dims) if args.require_all else list(args.require)
+    if not required:
+        print("nothing required: pass --require D01 ... or --require-all", file=sys.stderr)
+        print(STOP_MARKER)
+        return 2
+
+    bad = [(d, dims.get(d, "MISSING")) for d in required if dims.get(d) != "OK"]
+    if not args.quiet:
+        print(f"gate exit={code}; dimensions seen: {len(dims)}; required: {len(required)}")
+        for d in required:
+            print(f"  {d} [{dims.get(d, 'MISSING')}]")
+    if bad:
+        for d, status in bad:
+            print(f"required dimension not OK: {d} [{status}]", file=sys.stderr)
+        print(STOP_MARKER)
+        return 1
+    print(PASS_MARKER)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgate/gates/bootstrap_state.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Give a fresh clone the one thing it can honestly have: a declaration that the loop has not run here yet.
+
+`artifacts/` and `handoff/` are gitignored state, so a clone starts without them and the strict gate is red
+on D03/D04/D05/D12 — not because the code is broken, but because there is no history to prove. Copying a
+history out of this machine would be a fake; a fake is the one thing this project cannot ship.
+
+So the tree says so out loud:
+
+    python3 -m loopgate.gates.bootstrap_state --init          # writes artifacts/loop_state.json, state = cold
+    python3 -m loopgate.gates.check_loop --strict             # -> LOOP_ENGINEERING_COLD_0001, exit 0
+    ...run the loop once (a round artifact + a state update)...
+    python3 -m loopgate.gates.check_loop --strict             # -> LOOP_ENGINEERING_PASS_0001, exit 0
+
+The cold marker is not a pass: it says the code dimensions are green and four state dimensions could not
+be measured. The gate refuses the declaration as soon as round or handoff artifacts appear, so it cannot
+be used to hide a broken loop behind an empty directory.
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import datetime
+import json
+import os
+import sys
+
+ROOT = project_root()
+STATE_REL = "artifacts/loop_state.json"
+ROUNDS_REL = "artifacts/rounds"
+HANDOFF_REL = "handoff"
+COLD_MARKER = "LOOP_STATE_COLD_0001"
+STOP_MARKER = "LOOP_STATE_STOP_0001"
+
+
+def cold_state() -> dict:
+    now = datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+    return {
+        "state": "cold",
+        "round": 0,
+        "readiness": 0,
+        "evidence": 0,
+        "risk": 100,
+        "blockers": [
+            "cold start: no round artifact exists in this tree, so the loop's history is unproven",
+            "no handoff has been written; roles have not run against a real gate verdict",
+            "no signed anchor exists: a signature is produced by a run, not by a clone",
+        ],
+        "phase": "build",
+        "updated_at": now,
+        "marker": None,
+        "history": [],
+        "note": ("Written by loopgate/gates/bootstrap_state.py. This is a declaration, not evidence: it exists so "
+                 "the gate can name what a fresh clone cannot prove instead of pretending either way."),
+    }
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Initialize an honest cold-start state for a fresh tree.")
+    ap.add_argument("--init", action="store_true", help="write artifacts/loop_state.json with state=cold")
+    ap.add_argument("--force", action="store_true", help="overwrite an existing cold state file (never a real one)")
+    ap.add_argument("--root", default=ROOT)
+    args = ap.parse_args(argv)
+
+    root = os.path.abspath(args.root)
+    state_path = os.path.join(root, STATE_REL)
+    rounds_dir = os.path.join(root, ROUNDS_REL)
+    handoff_dir = os.path.join(root, HANDOFF_REL)
+
+    rounds = [n for n in (os.listdir(rounds_dir) if os.path.isdir(rounds_dir) else []) if n.startswith("round_")]
+    handoff = []
+    if os.path.isdir(handoff_dir):
+        for _dirpath, _dirnames, filenames in os.walk(handoff_dir):
+            handoff.extend(n for n in filenames if n.endswith(".md"))
+
+    if rounds or handoff:
+        print(f"refusing to declare a cold start: {len(rounds)} round artifact(s) and {len(handoff)} "
+              f"handoff file(s) prove this tree has run the loop")
+        print(STOP_MARKER)
+        return 1
+
+    if os.path.exists(state_path) and not args.force:
+        try:
+            with open(state_path, encoding="utf-8") as fh:
+                existing = json.load(fh)
+        except (OSError, json.JSONDecodeError):
+            existing = {}
+        if existing.get("state") != "cold":
+            print(f"refusing to overwrite {STATE_REL}: it holds a real state (round "
+                  f"{existing.get('round')!r}, marker {existing.get('marker')!r})")
+            print(STOP_MARKER)
+            return 1
+        print(f"{STATE_REL} is already a cold state; nothing to do")
+
+    if not args.init:
+        ap.error("--init is required (this script never writes without being asked)")
+
+    os.makedirs(os.path.dirname(state_path), exist_ok=True)
+    with open(state_path, "w", encoding="utf-8") as fh:
+        json.dump(cold_state(), fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+    print(f"wrote {STATE_REL}: state=cold, round=0 — the gate will name the unprovable dimensions")
+    print("next: python3 -m loopgate.gates.check_loop --strict")
+    print(COLD_MARKER)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())