@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/gate.py

@@ -0,0 +1,591 @@
+"""Completion is a run, not a claim.
+
+Two holes closed here, and unattended they are the same hole. `verify.*` named this
+repo's test and lint commands and was *printed, never executed* — a session was
+**told** to run them, which under a person is a reasonable division of labour and
+with nobody watching means "sometimes". And `move <name> complete` only **warned**
+on unchecked acceptance criteria — a line of output in a run nobody reads until
+morning, by which point the task is in `complete/` and the board says done.
+
+So an unattended instance could mark work complete having run nothing and proven
+nothing, and the tree would agree with it. That one fact makes every other number
+the harness reports unusable, which is the thing an autonomous system cannot
+afford.
+
+`verify` now EXECUTES — and that changes `verify.*` from a printed string into a
+value that reaches execution, so `P-7` applies to it: the command is split with
+`shlex` and run with `shell=False`, never interpolated into a shell. A repo can
+still put anything it likes in its own config; what it cannot do is get a `;` to
+mean `;`.
+
+The gate refuses rather than warns. `--accept` exists for the case a human
+genuinely takes the risk, and it is an EVENT with an owner's name on it — never a
+silent flag.
+"""
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+from .tree import die, find_work_root
+from .frontmatter import as_list, parse_frontmatter, rewrite_file, split_frontmatter
+from .model import locate
+from .shard import _load_run
+from . import events, git, peers
+from .autonomy import tier_of
+
+#: `verify.*` from config — bound by `config.apply`, same as everywhere else.
+VERIFY: dict = {}
+
+#: The run in flight, beside the board it is proving. Never enters git — it names a
+#: pid on one machine at one moment, exactly like `.claim`, and `git.py` drops it by
+#: filename for the same reason.
+RUN = ".verify"
+
+
+def _head(repo) -> str:
+    """The commit the evidence belongs to. Empty when this is not a git repo,
+    which is a supported mode: the gate then falls back to "verified today"."""
+    try:
+        out = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo,
+                             capture_output=True, text=True, timeout=10)
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _now():
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def _run_file(root) -> Path:
+    return root / RUN
+
+
+def _alive(pid) -> bool:
+    """Whether the process that started a run is still there.
+
+    Liveness is the PID and never a clock. A lease would have to guess how long a
+    verify takes, and this repo's own set spans 174 seconds warm and far more cold —
+    a guess short enough to be useful would strand a real run, and one long enough to
+    be safe would not guard anything.
+    """
+    try:
+        os.kill(int(pid), 0)
+    except (OSError, TypeError, ValueError):
+        return False
+    return True
+
+
+def read_run(root):
+    """The verify run in flight, or None.
+
+    An unreadable or half-written file is treated as absent, for the reason a claim
+    is: a run nobody can parse must not be able to block every future verify in the
+    checkout. Failing closed here would turn one corrupt file into a repo that can
+    never prove anything again.
+    """
+    p = _run_file(root)
+    if not p.is_file():
+        return None
+    try:
+        data = json.loads(p.read_text())
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def live_run(root):
+    """The run that is ACTUALLY executing right now, or None — the guard's one
+    question. A finished run stays on disk so its result can be read back; it is not
+    live, and it does not stop the next one."""
+    data = read_run(root)
+    if not data or data.get("finished"):
+        return None
+    return data if _alive(data.get("pid")) else None
+
+
+def _write_run(root, data) -> None:
+    """Write the run file atomically.
+
+    A reader polls this while a writer updates it after every gate, so a torn read is
+    not a rare case — it is the normal case done at the wrong instant. `read_run`
+    tolerates one, and this makes them not happen.
+    """
+    p = _run_file(root)
+    tmp = p.with_suffix(".tmp")
+    try:
+        tmp.write_text(json.dumps(data, indent=2) + "\n")
+        os.replace(tmp, p)
+    except OSError:
+        pass
+
+
+def _elapsed(data) -> int:
+    try:
+        return max(0, int((_now() - datetime.fromisoformat(str(data["started"]))).total_seconds()))
+    except (KeyError, ValueError, TypeError):
+        return 0
+
+
+def run_verify(root, names=None, progress=None) -> tuple:
+    """Run the configured verify commands. Returns (results, ok).
+
+    A SKIP is reported separately and never counts as a pass — "there was no lint
+    configured" and "lint passed" are different facts, and collapsing them is how a
+    gate quietly stops gating.
+
+    `progress` is called with (gate about to run, results so far) before each one, so
+    a detached run can say where it has got to. It is optional because the blocking
+    door has a terminal to print at and needs nothing recorded.
+    """
+    repo = root.parent
+    results = []
+    for name, cmd in sorted(VERIFY.items()):
+        if names and name not in names:
+            continue
+        if progress:
+            progress(name, results)
+        try:
+            argv = shlex.split(cmd)
+        except ValueError as e:
+            results.append((name, "SKIP", f"unparseable command: {e}"))
+            continue
+        if not argv:
+            results.append((name, "SKIP", "empty command"))
+            continue
+        try:
+            proc = subprocess.run(argv, cwd=repo, capture_output=True, text=True,
+                                  timeout=1800)
+        except FileNotFoundError:
+            results.append((name, "SKIP", f"{argv[0]}: not found"))
+            continue
+        except subprocess.TimeoutExpired:
+            results.append((name, "FAIL", "timed out after 30m"))
+            continue
+        except OSError as e:
+            results.append((name, "SKIP", str(e)))
+            continue
+        tail = (proc.stderr or proc.stdout or "").strip().splitlines()
+        results.append((name, "PASS" if proc.returncode == 0 else "FAIL",
+                        tail[-1][:160] if tail else f"exit {proc.returncode}"))
+    ok = bool(results) and all(r[1] == "PASS" for r in results)
+    return results, ok
+
+
+def _record(root, name, results, ok, sha) -> bool:
+    """Write the outcome onto the task. False when there is no such task."""
+    task = locate(root, name)
+    if not task:
+        return False
+    entry = (f"{date.today().isoformat()}  {'pass' if ok else 'FAIL'}  "
+             f"{sha[:12] or 'no-git'}  "
+             + " ".join(f"{n}={s}" for n, s, _ in results))
+
+    def mutate(d):
+        d["verified"] = as_list(d.get("verified")) + [entry]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(task.folder / "task.md", mutate)
+    events.append(root, "verified", name, ok=ok, sha=sha[:12] or None,
+                  results={n: s for n, s, _ in results})
+    return True
+
+
+def _execute(root, name) -> tuple:
+    """Run the gates, tracking them in the run file, and record the outcome.
+
+    **Both doors go through here**, which is what makes the guard mean anything: a
+    blocking run that wrote no run file would be invisible to the next caller, and
+    the overlap this exists to prevent is exactly the one nobody declared.
+    """
+    data = {
+        "task": name,
+        "pid": os.getpid(),
+        "machine": peers.here(),
+        "started": _now().isoformat(),
+        "gates": sorted(VERIFY),
+        "current": "",
+        "done": [],
+        "finished": None,
+        "passed": False,
+        "sha": "",
+        "results": [],
+        # Whether a finished result has already been handed to a caller. Reading one
+        # is what retires it: an agent that fixed something and asked again wants a
+        # fresh run, not the answer to the question it asked before the fix.
+        "read": False,
+    }
+    _write_run(root, data)
+
+    def progress(gate, so_far):
+        data["current"] = gate
+        data["done"] = [n for n, _, _ in so_far]
+        _write_run(root, data)
+
+    results, ok = run_verify(root, progress=progress)
+    sha = _head(root.parent)
+    data.update(current="", done=[n for n, _, _ in results],
+                finished=_now().isoformat(), passed=ok, sha=sha,
+                results=[{"name": n, "status": s, "said": d} for n, s, d in results])
+    _write_run(root, data)
+
+    if name and not _record(root, name, results, ok, sha):
+        die(f"no task named '{name}' found")
+    return results, ok, sha
+
+
+def _print_report(results, sha) -> None:
+    for n, status, detail in results:
+        mark = {"PASS": "✓", "FAIL": "✗"}.get(status, "·")
+        print(f"  {mark} {status:5} {n:14} {detail}")
+    print(f"\n  {sum(1 for r in results if r[1] == 'PASS')}/{len(results)} passed"
+          + (f" · at {sha[:8]}" if sha else ""))
+
+
+def _busy(running) -> str:
+    """Why a caller cannot start a verify, in the words the refused caller needs.
+
+    Never phrased as a failure. Two runs in one checkout corrupt each other's
+    result — one gate's build cleans the directory another's log check is about to
+    read — and the message a person meets has to say *that*, because the alternative
+    reads as a broken build and teaches them to re-run until it goes green.
+    """
+    return (f"a verify is already running here — '{running.get('task') or 'no task'}' "
+            f"on {running.get('machine') or 'this machine'}, "
+            f"{_elapsed(running)}s ago (pid {running.get('pid')}). "
+            f"Two at once corrupt each other's result, so this one did not start. "
+            f"Wait for it, or ask again.")
+
+
+def _describe(data) -> str:
+    """A finished run, as one line a model can act on. The gate's OWN words, per
+    gate — a caller told `6/7` has to leave the surface to find out which."""
+    results = data.get("results") or []
+    failed = [r for r in results if r.get("status") != "PASS"]
+    sha = (data.get("sha") or "")[:8]
+    if data.get("passed"):
+        return f"All {len(results)} gates passed{f' at {sha}' if sha else ''}."
+    head = (f"{len(failed)} of {len(results)} gates did not pass"
+            f"{f' at {sha}' if sha else ''} — fix these, then ask again:")
+    return "\n".join([head] + [f"  {r.get('name')}: {r.get('said') or 'no output'}"
+                               for r in failed])
+
+
+def _still_current(repo, sha: str) -> bool:
+    """Whether a result proven at `sha` still describes the code in front of us.
+
+    The same question the completion gate asks, answered the same way — a board
+    commit is not the code moving. Two answers to "is this evidence current" is
+    exactly the second opinion every write here exists to avoid.
+
+    Outside git there is no sha to pin anything to, and a result is current because
+    nothing can be shown to have changed. The gate's own day-old check still applies
+    when the evidence is actually used.
+    """
+    head = _head(repo)
+    if not head or not sha or sha == "no-git":
+        return True
+    return head.startswith(sha) or sha.startswith(head) or git.only_board_moved(repo, sha)
+
+
+def _answer(state, message, data=None) -> int:
+    """One JSON object on stdout, and nothing else.
+
+    **`--async` speaks JSON because its caller is a program.** The blocking door
+    prints a table for the person reading it; this one is what a tool relays, and
+    handing prose to a parser would mean the surface's answer depended on a
+    sentence's wording. `message` rides inside it so the human line and the
+    structured payload are the same computation rather than two.
+    """
+    out = {"state": state, "gate": "", "elapsedSeconds": 0, "gates": [], "done": [],
+           "passed": False, "commit": "", "results": [], "message": message}
+    out.update(data or {})
+    print(json.dumps(out))
+    return 0
+
+
+def _results_out(data) -> list:
+    return [{"name": r.get("name", ""), "passed": r.get("status") == "PASS",
+             "skipped": r.get("status") == "SKIP", "said": r.get("said") or ""}
+            for r in (data.get("results") or [])]
+
+
+def _verify_async(root, name) -> int:
+    """Start the gates, or say where the run already in flight has got to.
+
+    One call with three answers, because a verify takes minutes and a relayed tool
+    call cannot. Which answer comes back is never the caller's to choose: it is
+    whatever is true about this checkout right now.
+    """
+    running = live_run(root)
+    if running:
+        gate = running.get("current") or "starting"
+        done, gates = running.get("done") or [], running.get("gates") or []
+        for_task = running.get("task") or ""
+        whose = "" if for_task == name else f" (started for '{for_task or 'no task'}')"
+        return _answer(
+            "running",
+            f"running {_elapsed(running)}s: {gate}. {len(done)} of {len(gates)} done.{whose}",
+            {"gate": gate, "elapsedSeconds": _elapsed(running), "gates": gates,
+             "done": done, "results": _results_out(running)})
+
+    done = read_run(root)
+    # A finished run answers for the commit it ran at and no other. Once the CODE
+    # moves, or once its answer has been read, it is history — and the next ask is a
+    # new run rather than yesterday's verdict handed over again.
+    #
+    # "Moved" is the completion gate's own definition, not string equality, and the
+    # difference is not academic: recording a result is itself a board commit, so a
+    # run in a repo with `git.commit` on always ends at a different HEAD than it
+    # started. Comparing shas directly meant every finished run looked stale to the
+    # very caller waiting for it, and `--async` answered "started" forever.
+    if (done and done.get("finished") and not done.get("read")
+            and done.get("task") == name
+            and _still_current(root.parent, done.get("sha") or "")):
+        done["read"] = True
+        _write_run(root, done)
+        return _answer(
+            "finished", _describe(done),
+            {"elapsedSeconds": _elapsed(done), "gates": done.get("gates") or [],
+             "done": done.get("done") or [], "passed": bool(done.get("passed")),
+             "commit": done.get("sha") or "", "results": _results_out(done)})
+
+    child = subprocess.Popen(
+        [sys.executable, os.path.abspath(sys.argv[0]), "verify", "--task", name,
+         "--detached"],
+        cwd=root.parent, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL, start_new_session=True)
+    return _answer(
+        "started",
+        f"Gates started ({len(VERIFY)}): {', '.join(sorted(VERIFY))}. They take "
+        f"minutes, not seconds — ask again for progress, and again for the result.",
+        {"gates": sorted(VERIFY)})
+
+
+def cmd_verify(args) -> int:
+    """Execute the verify commands and RECORD the result against the task.
+
+    Three doors onto one run. Blocking is the person's and is unchanged. `--async`
+    is the tool surface's, because a call that takes 174 seconds cannot be a relayed
+    round trip. `--detached` is the child the second one starts and is nobody's to
+    type.
+    """
+    root = find_work_root()
+    name = (args.get("task") or "").strip()
+    if not VERIFY:
+        print("no `verify` commands configured — set them in "
+              ".claude/work.config.json so completion has something to prove "
+              "against. The gate treats an unconfigured repo as unproven.")
+        return 1
+
+    if args.get("detached"):
+        _execute(root, name)
+        return 0
+
+    running = live_run(root)
+    if running:
+        if args.get("async"):
+            return _verify_async(root, name)
+        print(f"error: {_busy(running)}", file=sys.stderr)
+        return 1
+
+    if args.get("async"):
+        return _verify_async(root, name)
+
+    results, ok, sha = _execute(root, name)
+    _print_report(results, sha)
+    if name:
+        print(f"  recorded on '{name}'")
+    return 0 if ok else 1
+
+
+def cmd_observed(args) -> int:
+    """Record an eyes-on: what was actually SEEN, against one criterion.
+
+    Not a checkbox. The whole reason this exists is that a checkbox records that
+    someone claimed something, and a sentence records what they claimed — and only
+    the second one can be disagreed with later.
+    """
+    root = find_work_root()
+    name = args["name"]
+    ac = (args.get("ac") or "").strip()
+    saw = (args.get("saw") or "").strip()
+    if not ac or not saw:
+        die("usage: jarvis work observed <task> --ac AC-01 --saw \"what you actually saw\"")
+    if not re.match(r"^AC-\d+$", ac):
+        die(f"--ac must look like 'AC-01' (got '{ac}')")
+    task = locate(root, name)
+    if not task:
+        die(f"no task named '{name}' found")
+    entry = f"{date.today().isoformat()}  {ac}  {saw}"
+    md = task.folder / "task.md"
+
+    def mutate(d):
+        d["observed"] = as_list(d.get("observed")) + [entry]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(md, mutate)
+    events.append(root, "observed", name, ac=ac, saw=saw)
+    print(f"recorded on '{name}': {ac} — {saw}")
+    return 0
+
+
+def _observed_acs(task) -> set:
+    out = set()
+    for entry in as_list(task.fm.get("observed")):
+        m = re.search(r"\b(AC-\d+)\b", str(entry))
+        if m:
+            out.add(m.group(1))
+    return out
+
+
+def _last_verify(task) -> tuple:
+    """(passed, sha, when) from the newest recorded verify run, or (False, "", "")."""
+    entries = as_list(task.fm.get("verified"))
+    if not entries:
+        return False, "", ""
+    parts = str(entries[-1]).split()
+    when = parts[0] if parts else ""
+    passed = len(parts) > 1 and parts[1] == "pass"
+    sha = parts[2] if len(parts) > 2 else ""
+    return passed, sha, when
+
+
+def gate(root, task, accept: str = "", owner: str = "") -> list:
+    """Every reason this task may NOT be called complete. Empty means it may.
+
+    Returns strings rather than raising so the caller can print all of them at
+    once: a gate that reveals one failure per run is a gate an unattended shift
+    walks into four times.
+    """
+    reasons = []
+
+    body = split_frontmatter((task.folder / "task.md").read_text())[1]
+    unchecked = re.findall(r"^\s*-\s*\[ \]\s*(.+)$", body, re.MULTILINE)
+    # A scaffold's placeholder criterion is a template line, not an unmet promise —
+    # refusing on it would mean every task that never edited its brief is
+    # permanently incompletable, which trains people to pass `--accept`.
+    unchecked = [u for u in unchecked if not u.strip().startswith("<!--")]
+    if unchecked:
+        reasons.append(f"{len(unchecked)} unchecked acceptance criterion/criteria: "
+                       + "; ".join(u[:60] for u in unchecked[:3]))
+
+    if VERIFY:
+        passed, sha, when = _last_verify(task)
+        if not when:
+            reasons.append("verify has never run for this task — `jarvis work verify "
+                           f"--task {task.name}`")
+        elif not passed:
+            reasons.append(f"the last verify run FAILED ({when}) — fix it, then "
+                           f"`jarvis work verify --task {task.name}`")
+        else:
+            head = _head(root.parent)
+            if (head and sha not in ("no-git", "") and not head.startswith(sha)
+                    and not git.only_board_moved(root.parent, sha)):
+                reasons.append(f"code moved since verify passed (proven at {sha}, "
+                               f"HEAD is {head[:12]}) — re-run `jarvis work verify "
+                               f"--task {task.name}`")
+            elif not head and when != date.today().isoformat():
+                reasons.append(f"verify last passed on {when}, not today, and there "
+                               f"is no git sha to pin it to — re-run it")
+    else:
+        reasons.append("no `verify` commands configured — an unconfigured repo "
+                       "cannot prove anything, so nothing in it can complete. Set "
+                       "`verify.*` in .claude/work.config.json")
+
+    # Every criterion this task promised to move needs evidence a RUN produced, or
+    # a recorded sentence saying what a human saw. A `covers:` with neither is the
+    # exact shape of "done on the model's say-so".
+    if task.covers:
+        proven, _, _ = _load_run(root.parent)
+        seen = _observed_acs(task)
+        feature = (task.owner or "").split("/")[-1]
+        for ac in task.covers:
+            cid = f"{feature}/{ac}" if feature else ac
+            if proven.get(cid) == "passed" or ac in seen:
+                continue
+            reasons.append(f"{ac} has no evidence — no passing coverage binding "
+                           f"and no `jarvis work observed {task.name} --ac {ac} --saw \"…\"`")
+
+    if tier_of(task) >= 3 and not accept:
+        reasons.append("tier 3 (irreversible, or money/secrets/personal data/law) "
+                       "— a human signs this off: `--accept \"<reason>\" --owner <name>`")
+
+    if accept and not owner:
+        reasons.append("--accept needs --owner: an override with nobody's name on "
+                       "it is the silent completion this gate exists to prevent")
+    return reasons
+
+
+def delivery_gate(delivered: str, not_included: str) -> list:
+    """The forwardable line. Separate from `gate` because it is about what a task
+    CLAIMS rather than what it proved — and it is the one thing the harness cannot
+    infer, which is exactly why it is required rather than warned about.
+
+    `not_included` is mandatory. Overpromising is not a proof failure — every gate
+    above can pass while the summary still reads as more than was built — and the
+    only reliable fix is a field somebody has to fill in.
+    """
+    out = []
+    if not delivered:
+        out.append('--delivered is required: one line on what a user can now DO. '
+                   'A completed task nobody can describe is one nobody can use.')
+    if not not_included:
+        out.append('--not-included is required: what this deliberately leaves out. '
+                   'Every gate above can pass while the summary still reads as more '
+                   'than was built, and this is the only field that stops it. '
+                   'Write "nothing" only if that is true.')
+    return out
+
+
+def signer(repo) -> str:
+    """Whose name goes on a waiver when the caller did not type one.
+
+    **The tool surface supplies a reason and never a name.** `--owner` is fine from a
+    terminal, where the person typing it is the person accepting; through a tool it
+    would let a run waive every gate under any name it liked. So the name comes from
+    the checkout's git identity — the same one the board already reads off a commit to
+    say who is on an item, which means a waiver and a hold cannot name different
+    people on one machine.
+
+    Empty when git has no identity configured, and the gate then refuses for want of
+    an owner exactly as it always did. Guessing a name here would be inventing the
+    one fact this whole arrangement exists to keep honest.
+    """
+    try:
+        out = subprocess.run(["git", "config", "user.name"], cwd=repo,
+                             capture_output=True, text=True, timeout=10)
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def report_gate(root, task, accept: str, owner: str) -> bool:
+    """Run the gate and print it. True when the task may complete."""
+    if accept and not owner:
+        owner = signer(root.parent)
+    reasons = gate(root, task, accept, owner)
+    if accept and owner and reasons:
+        # An override clears the gate but never the record — and it prints what it
+        # cleared, so a person reading the log sees exactly what was waived.
+        print(f"        ACCEPTED by {owner}: {accept}", file=sys.stderr)
+        for r in reasons:
+            print(f"        waived: {r}", file=sys.stderr)
+        events.append(root, "completed", task.name, accepted_by=owner,
+                      reason=accept, waived=len(reasons))
+        return True
+    if reasons:
+        print(f"error: '{task.name}' is not complete — {len(reasons)} gate(s) held:",
+              file=sys.stderr)
+        for r in reasons:
+            print(f"       · {r}", file=sys.stderr)
+        print("       Fix them, or record a human's decision with "
+              "`--accept \"<reason>\" --owner <name>`.", file=sys.stderr)
+        events.append(root, "gate-refused", task.name, why="; ".join(reasons)[:300])
+        return False
+    return True