riskrails 3.0.1 → 3.2.1

package/skills/ai-task/rr_state/task.py

@@ -0,0 +1,396 @@
+"""task: the task record — its schema, defaults, load and save, the task id, the steps and their order, and the old-surface routing.
+
+core: TASK_COMMANDS, apply_defaults, TASK_ID_RE, open_gate, SCHEMA, is_v7, apply_defaults_v7, task_files, _overlap, order_shared_files, ready_steps, old_surface_refusal
+shell: load, claim_runtime, save, sealed_task_ids, next_task_id, valid_task_id, load_v7, parse_steps, check_steps, abandon_old, route_surface, in_flight
+"""
+# pylint: disable=protected-access  # parse_steps calls fs._split_files, which partition.json assigns to fs
+import contextlib
+import json
+import os
+import re
+from datetime import datetime, timezone
+
+from rr_state import fs
+from rr_state import journal
+from rr_state import runtime as rr_runtime
+
+try:
+    import weight                         # pure computation; it writes nothing
+except ImportError:
+    weight = None
+
+
+# The commands that work on the task in flight; a task the old surface started
+# refuses them all but close --abandon (route_surface).
+TASK_COMMANDS = {"step-done", "ask", "answer", "questions", "approve", "reject", "close", "verify",
+                 "review", "steps", "batch"}
+
+
+def apply_defaults(state):
+    """Schema 2 keys (I6) in memory, so a v1 state answers every command before
+    migration 0002 has run; save() then persists them. A reader that opens
+    the state file directly — update.py does — sees the file, not these."""
+    if is_v7(state):
+        return apply_defaults_v7(state)
+    task_id = state.get("task_id") or ""
+    state.setdefault("owner_runtime", None)
+    state.setdefault("resume_point", None)
+    # A hand-edited or half-migrated file may hold null where v1 held an object.
+    # load() promises to be loud about a file it cannot read and silent about one
+    # it can, so the defaults are total rather than assuming the v1 shape.
+    if not isinstance(state.get("questions"), dict):
+        state["questions"] = {"file": ".ai/reports/%s/task.md" % task_id, "pending": []}
+    if not isinstance(state.get("handoff"), dict):
+        state["handoff"] = {"file": ".ai/state/handoff.md", "written_at": None, "reason": None}
+    if not isinstance(state.get("human_approval"), dict):
+        state["human_approval"] = {"required": True, "granted": False,
+                                   "granted_by": None, "granted_at": None}
+    for key, default in (("requested_at", None), ("gate_id", None), ("requested_session", None),
+                         ("rejected_at", None), ("via", None), ("unattended", False)):
+        state["human_approval"].setdefault(key, default)
+    # Schema 4 (WP4 I2): a task that started before the gates existed has no
+    # tree to measure from, and one cannot be invented afterwards.
+    if not isinstance(state.get("diff"), dict):
+        state["diff"] = {}
+    state["diff"].setdefault("base_commit", None)
+    state["diff"].setdefault("base_tree", None)
+    # Schema 5 (WP5 I4): a task handed to the other runtime, and a review asked of it.
+    state["handoff"].setdefault("pending_to", None)
+    state["handoff"].setdefault("pending_since", None)
+    state.setdefault("cross_vendor_review", None)
+    return state
+
+
+def load(root, required=True, claim=None, rt=rr_runtime.Runtime()):
+    path = fs.state_path(root)
+    if not os.path.exists(path):
+        if required:
+            fs.die("no task in flight (%s does not exist). Start one with state.py start." % path)
+        return None
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError, RecursionError) as exc:
+        # Loud on purpose: a corrupt state file must never be silently replaced,
+        # because ai-scope-guard's boundaries are derived from it.
+        fs.die("%s is unreadable (%s). Inspect it by hand; do not delete it blindly." % (path, exc))
+    state = apply_defaults(data)
+    # Ownership is taken before the command's own events, so the journal and
+    # history both show the handoff ahead of the work it covers.
+    if rt.mutating if claim is None else claim:
+        claim_runtime(root, state, rt=rt)
+    return state
+
+
+def claim_runtime(root, state, rt=rr_runtime.Runtime()):
+    """Called from load() for the commands in MUTATING_COMMANDS, so ownership is
+    taken once rather than in fifteen call sites. A task that changes runtime says
+    so in the journal; WP5 is what will move a task on purpose."""
+    pending = (state.get("handoff") or {}).get("pending_to")
+    if pending in rr_runtime.RUNTIMES:
+        if rt.name != pending:
+            back = ("state.py handoff --to %s" % rt.name if rt.name in rr_runtime.RUNTIMES else
+                    "state.py --runtime %s handoff --to %s (this shell is neither runtime; "
+                    "name the one taking it)" % ((rr_runtime.other_runtime(pending, rt=rt),) * 2))
+            fs.die("RUNTIME_HANDOFF_PENDING: task %s was handed to %s at %s. Resume it there "
+                "(/rr-build), or take it back here with: %s"
+                % (state.get("task_id"), pending, state["handoff"].get("pending_since"), back), 7)
+        # The receiving runtime's first change: the handoff is complete. The
+        # move itself was journaled when it was made, so there is no second event.
+        state["handoff"]["pending_to"] = None
+        state["handoff"]["pending_since"] = None
+    previous = state.get("owner_runtime")
+    if rt.name not in rr_runtime.RUNTIMES or previous == rt.name:
+        return
+    if previous in rr_runtime.RUNTIMES:
+        journal.emit(root, state, "runtime_handoff", "%s -> %s" % (previous, rt.name),
+             {"from": previous, "to": rt.name, "via": "resume"}, rt=rt)
+    state["owner_runtime"] = rt.name
+
+
+def save(root, state):
+    state["updated_at"] = fs.now()
+    path = fs.state_path(root)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = "%s.%d.tmp" % (path, os.getpid())
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(state, fh, indent=2, ensure_ascii=False)
+            fh.write("\n")
+        os.replace(tmp, path)
+    except OSError as exc:
+        fs.die("cannot write %s (%s) — the state is the contract, so nothing was recorded" % (path, exc))
+
+
+def sealed_task_ids(root):
+    """The task ids a package under .ai/memory/ seals; empty in files mode."""
+    found = set()
+    base = os.path.join(root, ".ai", "memory")
+    for name in sorted(os.listdir(base)) if os.path.isdir(base) else []:
+        try:
+            with open(os.path.join(base, name), "rb") as fh:
+                for raw in fh:
+                    if b'"kind":"task"' not in raw:
+                        continue
+                    with contextlib.suppress(ValueError, UnicodeDecodeError, AttributeError, RecursionError):
+                        found.add(json.loads(raw.decode("utf-8")).get("task"))
+        except OSError:
+            continue
+    return found
+
+
+def next_task_id(root, goal="", slug=None, at=None):
+    """R1: T-YYYY-MM-DD-HHMM-<slug>, from the clock and the goal alone. A count
+    of the day's report directories gave two clones the same id and handed a
+    deleted directory's id to the next task. A local hit — a report directory,
+    the raw store under .ai/state/logs/, a sealed key — gets -2 … -9."""
+    import memory_format                  # pylint: disable=import-outside-toplevel
+    stamp = at or datetime.now(timezone.utc)
+    base = slug or memory_format.slug_of(goal)
+    sealed = sealed_task_ids(root)
+    for n in range(1, 10):
+        task_id = memory_format.new_task_id(stamp, memory_format.with_suffix(base, n))
+        if not (os.path.exists(os.path.join(root, ".ai", "reports", task_id))
+                or os.path.exists(os.path.join(root, ".ai", "state", "logs", task_id)) or task_id in sealed):
+            return task_id
+    fs.die("%s and -2 … -9 are all taken this minute: start again with another --slug \"<3-24 characters>\""
+        % memory_format.new_task_id(stamp, base), 2)
+    return None
+
+
+TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def valid_task_id(task_id, flag="--task-id"):
+    """A task id is a directory name under .ai/reports/, and everything the
+    journal and the questions file are worth rests on it staying one. A '/' or
+    a '..' in it puts both outside the project — and outside the path guard's
+    `.ai/reports/<id>/` patterns, which is how a writable task.md, and
+    with it a self-granted gate, would come back."""
+    if not isinstance(task_id, str) or not TASK_ID_RE.match(task_id) or ".." in task_id:
+        fs.die("%s takes a directory name — letters, digits, '.', '_' and '-', "
+            "no path separators — not %r" % (flag, task_id))
+    return task_id
+
+
+def open_gate(state):
+    """The one signal that a gate is open, and the one thing that names it.
+
+    R11 words this as "a gate_requested event exists", and the first draft read
+    the journal for one. It must not: events.jsonl is append-only, unprotected,
+    and keyed on a caller-supplied task id, so a single hand-written line — or
+    an `init --task-id` that reuses an old id — satisfied the precondition. The
+    state is the contract and the path guard protects it; `stage human_approval`
+    is the only writer, and approve/reject consume what it wrote.
+    """
+    approval = state.get("human_approval") or {}
+    if approval.get("requested_at") and approval.get("gate_id"):
+        return approval["gate_id"]
+    return None
+
+
+SCHEMA = 7
+
+
+def is_v7(state):
+    return isinstance(state, dict) and state.get("schema") == SCHEMA
+
+
+def apply_defaults_v7(state):
+    """The keys every shared helper reads (questions, handoff, the gate) and the
+    schema-7 ones; none of the old surface's own keys, so a schema-7 file holds
+    only what its commands use."""
+    task_id = state.get("task_id") or ""
+    state.setdefault("owner_runtime", None)
+    state.setdefault("resume_point", None)
+    state.setdefault("cross_vendor_review", None)
+    if not isinstance(state.get("questions"), dict):
+        state["questions"] = {"file": ".ai/reports/%s/task.md" % task_id, "pending": []}
+    if not isinstance(state.get("handoff"), dict):
+        state["handoff"] = {"file": ".ai/state/handoff.md", "written_at": None, "reason": None}
+    state["handoff"].setdefault("pending_to", None)
+    state["handoff"].setdefault("pending_since", None)
+    if not isinstance(state.get("human_approval"), dict):
+        state["human_approval"] = {"required": False, "granted": False,
+                                   "granted_by": None, "granted_at": None}
+    for key, default in (("requested_at", None), ("gate_id", None), ("requested_session", None),
+                         ("rejected_at", None), ("via", None), ("unattended", False)):
+        state["human_approval"].setdefault(key, default)
+    for key, default in (("files", []), ("tests", []), ("steps", []), ("amendments", []),
+                         ("findings", []), ("diff", {}), ("gate", None), ("mode_override", None)):
+        if not isinstance(state.get(key), type(default)) and not (default is None and key in state):
+            state[key] = default
+    for step in state["steps"]:
+        if not isinstance(step.get("after"), list):
+            step["after"] = []                # a step from before the batch loop depends on nothing
+    if not isinstance(state.get("batch"), dict):
+        state["batch"] = {"on": False, "by": None, "why": None, "since": None}
+    if not isinstance(state.get("verify"), dict):
+        state["verify"] = {}
+    for key, default in (("status", "not_run"), ("e2e", "not_run"), ("suite_runs", 0), ("runs", [])):
+        state["verify"].setdefault(key, default)
+    if not isinstance(state.get("review"), dict):
+        state["review"] = {}
+    for key, default in (("status", "not_started"), ("passes", 0), ("tier", None),
+                         ("findings", []), ("tree", None), ("log", []), ("closed", [])):
+        state["review"].setdefault(key, default)
+    return state
+
+
+def load_v7(root, rt=rr_runtime.Runtime()):
+    state = load(root, rt=rt)
+    if not is_v7(state):
+        fs.die(old_surface_refusal(state))
+    return state
+
+
+def task_files(state):
+    """Every file and glob the task may touch: its files, its tests, every step's."""
+    out = list(state.get("files") or []) + list(state.get("tests") or [])
+    for step in state.get("steps") or []:
+        out += list(step.get("files") or []) + list(step.get("tests") or [])
+    return list(dict.fromkeys(out))
+
+
+def parse_steps(text, plan_file):
+    """--steps "id:a,b:t;id2:c" or --plan-file F.json ([{id, files, tests, after}]);
+    `after` (plan-file only) names the steps this one waits for (R2)."""
+    raw = []
+    if plan_file:
+        try:
+            with open(plan_file, encoding="utf-8") as fh:
+                raw = json.load(fh)
+        except (OSError, ValueError, RecursionError) as exc:
+            fs.die("--plan-file %s: %s" % (plan_file, exc))
+        if not isinstance(raw, list) or not all(isinstance(s, dict) for s in raw):
+            fs.die("--plan-file holds a JSON list of {\"id\", \"files\", \"tests\", \"after\"}")
+        for s in raw:
+            after = s.get("after") or []
+            if not isinstance(after, list) or not all(isinstance(a, str) and a.strip() for a in after):
+                fs.die("step %s: \"after\" is a JSON list of step ids" % (s.get("id") or "?"))
+        raw = [(str(s.get("id") or ""), ",".join(s.get("files") or []), ",".join(s.get("tests") or []),
+                [fs.one_line(a, 40) for a in s.get("after") or []]) for s in raw]
+    for chunk in [c for c in (text or "").split(";") if c.strip()]:
+        parts = chunk.split(":")
+        raw.append((parts[0], parts[1] if len(parts) > 1 else "", parts[2] if len(parts) > 2 else "", []))
+    steps = []
+    for step_id, files, tests, after in raw:
+        step_id = fs.one_line(step_id, 40)
+        if not step_id or not fs._split_files(files):
+            fs.die("a step is id:files[:tests], with at least one file: %r" % ":".join((step_id, files, tests)))
+        if step_id in [s["id"] for s in steps]:
+            fs.die("step id %s appears twice" % step_id)
+        steps.append({"id": step_id, "files": fs._split_files(files), "tests": fs._split_files(tests),
+                      "after": list(dict.fromkeys(after)), "status": "pending", "tree_before": None,
+                      "tree_after": None})
+    return steps
+
+
+def _overlap(a, b):
+    """One path or pattern covers the other: equal once normalised, or one
+    matches the other as a glob — so `src/*.py` and `./src/a.py` count as shared."""
+    a, b = os.path.normpath(a), os.path.normpath(b)
+    return a == b or bool(weight and (weight.match(a, [b]) or weight.match(b, [a])))
+
+
+def order_shared_files(steps):
+    """Two steps that name one file or pattern — among their files or their
+    tests — never run side by side: the later one is put after the earlier (R2).
+    Returns the implied edges as (later, earlier, what they share)."""
+    implied = []
+    for n, later in enumerate(steps):
+        for earlier in steps[:n]:
+            shared = [f for f in later["files"] + later["tests"]
+                      if any(_overlap(f, g) for g in earlier["files"] + earlier["tests"])]
+            if shared and earlier["id"] not in later["after"]:
+                later["after"].append(earlier["id"])
+                implied.append((later["id"], earlier["id"], ", ".join(dict.fromkeys(shared))))
+    return implied
+
+
+def check_steps(steps, implied=()):
+    """Every `after` names another, existing step, and the steps form no cycle (R2).
+    A cycle closed by an implied edge (order_shared_files) names that edge."""
+    ids = [s["id"] for s in steps]
+    for step in steps:
+        for dep in step["after"]:
+            if dep == step["id"]:
+                fs.die("step %s lists itself in after" % step["id"])
+            if dep not in ids:
+                fs.die("step %s is after %s, which is not a step (have: %s)" % (step["id"], dep, ", ".join(ids)))
+    by_id = {s["id"]: s for s in steps}
+    seen = {}                                 # id -> "visiting" | "done"
+
+    def visit(step_id, trail):
+        if seen.get(step_id) == "done":
+            return
+        if seen.get(step_id) == "visiting":
+            loop = trail + [step_id]
+            hints = ["%s after %s is implied: they share %s" % edge for edge in implied
+                     if edge[0] in loop and edge[1] in loop]
+            fs.die("the steps' after form a cycle: %s%s" % (
+                " -> ".join(loop), " (%s — list the dependent row after the one it needs)" % "; ".join(hints)
+                if hints else ""))
+        seen[step_id] = "visiting"
+        for dep in by_id[step_id]["after"]:
+            visit(dep, trail + [step_id])
+        seen[step_id] = "done"
+
+    for step in steps:
+        visit(step["id"], [])
+
+
+def ready_steps(state):
+    """The steps not yet done whose `after` are all done, in plan order: the next
+    wave of /rr-build-all, and the step step-done starts next."""
+    steps = state.get("steps") or []
+    done = {s["id"] for s in steps if s.get("status") == "done"}
+    return [s for s in steps if s.get("status") != "done" and all(d in done for d in s.get("after") or [])]
+
+
+def old_surface_refusal(state):
+    return ("task %s runs on the old surface (schema %s), whose commands were removed in redesign 2.6: "
+            "finish it with the plugin version that started it, or drop it with 'state.py close --abandon'"
+            % (state.get("task_id"), state.get("schema") or "<7"))
+
+
+def abandon_old(_args, root, rt=rr_runtime.Runtime()):
+    """close --abandon for a task the old surface started: the record moves to
+    .ai/state/logs/<task>/state.json as it is, and nothing else is measured."""
+    state = load(root, rt=rt)
+    state["result"] = "abandoned"
+    state["closed_at"] = fs.now()
+    journal.emit(root, state, "task_closed", "abandoned", {"abandoned": True, "surface": "old"}, rt=rt)
+    fs.ensure_logs(root, state["task_id"])
+    target = os.path.join(fs.logs_dir(root, state["task_id"]), "state.json")
+    state["updated_at"] = fs.now()
+    tmp = "%s.%d.tmp" % (target, os.getpid())
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(state, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+    os.replace(tmp, target)
+    with contextlib.suppress(OSError):
+        os.remove(fs.handoff_path(root))
+    fs.remove_state(root)
+    print("%s abandoned (old surface)" % state["task_id"])
+    print("state: %s" % os.path.relpath(target, root))
+
+
+def route_surface(root, args, rt=rr_runtime.Runtime()):
+    """A task the old surface started (schema < 7) is read (status, handoff,
+    questions without --sync) or dropped (close --abandon); every command that
+    works on it refuses."""
+    if args.command not in TASK_COMMANDS:
+        return
+    state = load(root, required=False, claim=False, rt=rt)
+    if state is None or is_v7(state) or (args.command == "questions" and not args.sync):
+        return
+    if args.command == "close" and args.abandon:
+        args.func = abandon_old
+        return
+    fs.die(old_surface_refusal(state))
+
+
+def in_flight(root, rt=rr_runtime.Runtime()):
+    state = load(root, required=False, claim=False, rt=rt)
+    return state if state and state.get("current_stage") != "done" and state.get("task_id") else None

package/skills/ai-task/rr_state/verify.py

@@ -0,0 +1,231 @@
+"""verify: the `verify` command -- run one scope's command to the end, record it, re-score; the e2e declarations and the moved-tree detail.
+
+shell: moved_detail, run_v7, e2e_na_refusal, e2e_na, e2e_none, cmd_verify
+core: E2E_NONE
+"""
+# pylint: disable=protected-access  # run_v7 calls fs._split_files, which partition.json assigns to fs
+# pylint: disable=unused-argument  # uniform cli dispatch: cmd_verify takes rt like every command
+import os
+import shlex
+import sys
+
+from rr_state import dialog, fs, handoff, journal, labels, report, task
+from rr_state import policy as rr_policy
+from rr_state import runtime as rr_runtime
+
+# sensors.py sits beside state.py; the entry puts that directory on sys.path.
+try:
+    import sensors                        # measurement only; it never writes this file
+except ImportError:                       # an old install that shipped state.py alone
+    sensors = None
+
+
+def moved_detail(root, before, after, limit=5):
+    """Lines naming what changed between the two snapshots of a run that moved the tree,
+    and saying so when the new paths are untracked (a suite that writes a cache or a
+    coverage file moves the tree on every run). [] when the paths cannot be measured."""
+    diff = fs.safe_sensor(sensors.diff_files, root, before, after)
+    if not diff:
+        return []
+    paths = [d["path"] for d in diff]
+    tracked = set()
+    code, out = fs.safe_sensor(sensors.git, root, ["ls-files", "-z", "--"] + paths) or (1, "")
+    if code == 0:
+        tracked = set(f for f in out.split("\0") if f)
+    new = [d["path"] for d in diff if d["status"] == "A" and d["path"] not in tracked]
+    def esc(path):
+        # A name from `git diff -z` is data: a newline or ESC in it would forge a verify line.
+        return "".join(c if c.isprintable() else repr(c)[1:-1] for c in path)
+    shown = ", ".join("%s (%s)" % (esc(d["path"]), "untracked" if d["path"] in new else
+                                   {"A": "added", "D": "deleted", "T": "type changed"}.get(d["status"], "changed"))
+                      for d in diff[:limit])
+    more = " and %d more" % (len(diff) - limit) if len(diff) > limit else ""
+    lines = ["changed during the run: %s%s" % (shown, more)]
+    if new:
+        lines.append("untracked files written by the suite move the tree on every run: add them to "
+                     ".gitignore or stop the suite writing them")
+    return lines
+
+
+def run_v7(root, state, scope, args, tcfg, rt=rr_runtime.Runtime()):
+    """One scope's command, to the end, logged under .ai/state/logs/; returns the run."""
+    command = fs.safe_sensor(sensors.command_for, root, scope) or ""
+    if not command:
+        fs.die("no command for scope '%s' in .ai/policies/testing.md — write it down first" % scope)
+    files = fs._split_files(args.files)
+    if files:
+        command = fs.safe_sensor(sensors.expand_files, command, files) or command
+    runs = state["verify"]["runs"]
+    n = len(runs) + 1
+    fs.ensure_logs(root, state["task_id"])
+    log = os.path.join(fs.logs_dir(root, state["task_id"]), "%s-%d.log" % (scope, n))
+    before = fs.current_tree(root)
+    result = fs.safe_sensor(sensors.run_command, root, command, log, tcfg.get("timeout_seconds", 1800),
+                         tcfg.get("log_max_bytes", 2097152))
+    if result is None:
+        fs.die("sensors.py is not installed beside state.py — run the project's command yourself")
+    after = fs.current_tree(root)
+    # A tree that moved during the run was not the tree the run tested: the run
+    # is kept in the record, but stands for no tree at all.
+    run = {"n": n, "scope": scope, "exit": result["exit"], "tree": after if after == before else None,
+           "tree_moved": after != before,
+           "log": os.path.relpath(log, root), "ts": fs.now(), "expected_fail": args.expect == "fail",
+           "runtime": rt.name, "command": command, "duration_s": result["duration_s"],
+           "after_fix": args.after_fix or None, "files": files}
+    runs.append(run)
+    if scope == "suite":
+        state["verify"]["suite_runs"] += 1
+        state["verify"]["status"] = ("passing" if run["exit"] == 0 else
+                                     "env_failure" if run["exit"] is None else "failing")
+    elif scope == "e2e":
+        state["verify"]["e2e"] = "passing" if run["exit"] == 0 else "failing"
+        state["verify"]["e2e_tree"] = run["tree"]
+    if run["tree_moved"]:
+        print("tree moved during the run: run %d stands for no tree — run it again on a still tree" % n)
+        for line in moved_detail(root, before, after):
+            print(line)
+    journal.emit(root, state, "verify_run", "%s run %d: exit %s" % (scope, n, run["exit"]),
+         {k: run[k] for k in ("n", "scope", "exit", "tree", "log", "expected_fail")}, rt=rt)
+    if rr_policy.full_suite(run) and run["exit"] is not None and run["tree"]:
+        other = [r for r in runs[:-1] if rr_policy.full_suite(r) and r.get("tree") == run["tree"]
+                 and r.get("runtime") != rt.name and (r.get("exit") == 0) != (run["exit"] == 0)
+                 and r.get("exit") is not None]
+        red, green = (run, other[-1]) if other and run["exit"] != 0 else \
+            (other[-1], run) if other else (None, None)
+        if red:
+            # R19: the same tree green under one runtime and red under the other, in
+            # either order, goes into task.md. A red under Codex is best effort and
+            # never a gate; a red under any other runtime is the change's, and the
+            # green elsewhere does not answer it (two_facts).
+            state["findings"].append("%s: suite red under %s (run %d) and green under %s (run %d) on %s"
+                                     % (fs.now(), red.get("runtime"), red["n"], green.get("runtime"),
+                                        green["n"], run["tree"][:9]))
+            if red.get("runtime") == "codex":
+                print("finding: red under %s on a tree green under %s — recorded in task.md, close is not "
+                      "blocked" % (red.get("runtime"), green.get("runtime")))
+            else:
+                print("red under %s on a tree green under %s — recorded in task.md; the red is the change's "
+                      "and close is blocked until it is green under %s"
+                      % (red.get("runtime"), green.get("runtime"), red.get("runtime")))
+    print("%s run %d: exit %s in %ds" % (scope, n, run["exit"], run["duration_s"]))
+    print("command: %s" % command)
+    print("log: %s" % run["log"])
+    if result.get("detail"):
+        print(result["detail"])
+    return run
+
+
+def e2e_na_refusal(root, state):
+    """Why e2e cannot be declared not applicable now, or None. The last e2e run
+    decides, on whatever tree it ran: a red flow is fixed and run again, never
+    declared away by an edit and a declaration; a run that could not finish
+    (exit None) is run again."""
+    runs = [r for r in state["verify"]["runs"] if r.get("scope") == "e2e"]
+    if not runs or runs[-1].get("exit") == 0:
+        return None
+    last, tree = runs[-1], fs.current_tree(root)
+    if last.get("exit") is None:
+        return ("e2e run %d did not finish: run it again with 'verify --scope e2e' — an environment "
+                "failure is not a reason to declare e2e not applicable" % last["n"])
+    where = "on this tree" if tree and last.get("tree") == tree else \
+        "on %s, and no e2e run since has passed" % (last.get("tree") or "a moving tree")[:9]
+    return ("e2e run %d is red %s: a failing flow is fixed and 'verify --scope e2e' run again, not "
+            "declared not applicable" % (last["n"], where))
+
+
+def e2e_na(root, state, why, rt=rr_runtime.Runtime()):
+    refusal = e2e_na_refusal(root, state)
+    if refusal:
+        fs.die(refusal)
+    tree = fs.current_tree(root)
+    state["verify"]["e2e_tree"] = tree
+    state["verify"]["e2e"] = "not_applicable"
+    state["verify"]["e2e_why"] = why
+    journal.emit(root, state, "verify_run", "e2e not applicable: %s" % fs.one_line(why, 200),
+         {"scope": "e2e", "exit": None, "not_applicable": True, "why": why}, rt=rt)
+    print("e2e: not applicable — %s" % fs.one_line(why, 200))
+
+
+E2E_NONE = "e2e_command: none in .ai/policies/testing.md"
+
+
+def e2e_none(root):
+    return (fs.safe_sensor(sensors.command_for, root, "e2e") or "").strip() == "none"
+
+
+def cmd_verify(args, root, rt=rr_runtime.Runtime()):
+    """Run, record, re-score up; exit 0 green, 1 red, 6 SUITE_BUDGET (R20)."""
+    state = task.load_v7(root, rt=rt)
+    policy = rr_policy.weight_policy(root)
+    tcfg = policy.get("tests") or {}
+    scope = args.scope
+    if args.expect and (scope != "step" or not args.files):
+        fs.die("--expect fail is for one test shown failing before the fix: --scope step --files <test>")
+    if args.e2e and (scope not in ("all", "e2e") or args.e2e[0] != "not-applicable"
+                     or not args.e2e[1].strip()):
+        fs.die('--e2e takes: not-applicable "<why the change cannot reach an e2e flow>", with --scope all or e2e')
+    if scope == "all" and args.files:
+        fs.die("--files narrows one scope; --scope all runs the whole suite and e2e")
+    if args.e2e and e2e_na_refusal(root, state):
+        fs.die(e2e_na_refusal(root, state))         # before the suite runs, not after (N3)
+    max_runs, budget_name = rr_policy.budget(policy, state, "max_suite_runs")
+    if scope in ("suite", "all") and state["verify"]["suite_runs"] >= max_runs:
+        if not args.by:
+            dialog.offer_decision(root, state, "human_set", "Budget",
+                           "%s\nSUITE_BUDGET: %d suite runs; weight.json allows %d%s. Run it once more?"
+                           % (dialog.task_facts(root, state), state["verify"]["suite_runs"], max_runs,
+                              " (%s)" % budget_name if rr_policy.batch_on(state) else ""),
+                           [{"kind": "choice", "effect": "keep", "label": "Keep the budget — stop here"},
+                            {"kind": "command",
+                             "label": labels.state_label(root, sys.argv[1:] + ["--by", labels.human_name(root)])}], "verify", rt=rt)
+            fs.die("SUITE_BUDGET — %d suite runs; weight.json allows %d (%s). Running it "
+                "again is not the next move: the human decides. In their own terminal:\n  python3 %s "
+                "--root %s verify --scope %s --by \"<name>\""
+                % (state["verify"]["suite_runs"], max_runs, budget_name, shlex.quote(fs.ENTRY),
+                   shlex.quote(root), scope), 6)
+        via, why = dialog.human_route(root, allow_dialog=True, rt=rt)
+        if via is None:
+            fs.die("APPROVAL_REFUSED — a run past the suite budget is the human's, from their own terminal."
+                "\nRefused because %s." % why, 5)
+        journal.emit(root, state, "human_set", "suite run %d past the budget by %s via %s"
+             % (state["verify"]["suite_runs"] + 1, args.by, via),
+             dict({"field": "suite_runs", "value": state["verify"]["suite_runs"] + 1, "by": args.by,
+                   "via": via, "unattended": via == "unattended"}, **dialog.pick_data(dialog.DIALOG_PICK[0])),
+             actor="human" if via == "terminal" else "agent", rt=rt)
+    green_before = rr_policy.suite_green(state)
+    state["stage"] = "verify"
+    code = 0
+    if scope == "e2e" and args.e2e:
+        e2e_na(root, state, args.e2e[1], rt=rt)
+    elif scope == "e2e" and e2e_none(root):
+        e2e_na(root, state, E2E_NONE, rt=rt)            # `none` is a declaration, not a command (N1)
+    else:
+        run = run_v7(root, state, "suite" if scope == "all" else scope, args, tcfg, rt=rt)
+        code = run["exit"]
+        if args.expect == "fail":
+            # exit 1 is a failing test; the runner's own usage error (2) is not, unless
+            # testing.md's bite_codes names it (pytest 1,2 — 2 is a collection error)
+            run["bites"] = code in (fs.safe_sensor(sensors.bite_codes, root) or (1,))
+            print("expected fail: %s" % ("the test fails without the fix — it bites" if run["bites"]
+                                         else "the test passes without the fix — it does not bite yet"))
+            code = 0 if run["bites"] else 1
+        elif scope == "all" and code == 0:
+            if args.e2e:
+                e2e_na(root, state, args.e2e[1], rt=rt)
+            elif not rr_policy.mode_setting(policy, state["mode"], "e2e", False):
+                state["verify"]["e2e"] = "not_required"
+                print("e2e: not required in %s mode" % state["mode"])
+            elif e2e_none(root):
+                e2e_na(root, state, E2E_NONE, rt=rt)
+            else:
+                code = run_v7(root, state, "e2e", args, tcfg, rt=rt)["exit"]
+        elif scope == "all":
+            print("e2e: not run — the suite is red")
+    rr_policy.rescore_v7(root, state, policy, "verify", rt=rt)
+    if not green_before and rr_policy.suite_green(state):
+        handoff.write_handoff(root, state, "verify", rt=rt)
+    task.save(root, state)
+    report.write_task_md(root, state)
+    if scope in ("suite", "all"):
+        print("suite runs used: %d of %d" % (state["verify"]["suite_runs"], max_runs))
+    sys.exit(0 if code == 0 else 1)