riskrails 3.1.0 → 3.2.1

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

@@ -0,0 +1,271 @@
+"""report: the text the state is rendered to — the two close facts, the status lines, the schema line, task.md and its writer.
+
+core: md_cell
+shell: two_facts, status_lines, schema_line, task_md_lines, write_task_md
+"""
+import contextlib
+import os
+import re
+import sys
+
+from rr_state import fs, journal, locks, questions, task
+from rr_state import policy as rr_policy   # status_lines names a local `policy`, as state.py does
+
+# weight.py and sensors.py sit 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
+try:
+    import weight                         # pure computation; it writes nothing
+except ImportError:
+    weight = None
+
+
+def two_facts(root, state, tree):
+    """R6: (a) a green suite on the tree as it is now; (b) the diff since the base
+    tree inside the task's files. Each is (green, why)."""
+    runs = [r for r in state["verify"]["runs"] if rr_policy.full_suite(r)]
+    here = [r for r in runs if tree and r.get("tree") == tree]
+    green = [r for r in here if r.get("exit") == 0]
+    documents = None
+    if not tree:
+        a = (False, "the tree cannot be measured (not a git repository)")
+    elif not runs:
+        a = (False, "no whole-suite 'verify --scope suite|all' has run")
+    elif not here:
+        a = (False, "the tree changed after the last verify (run %d on %s, now %s)"
+             % (runs[-1]["n"], (runs[-1].get("tree") or "?")[:9], tree[:9]))
+        ok, why, documents = rr_policy.documents_cover(root, state, rr_policy.weight_policy(root), tree)
+        if ok or why:
+            a = (ok, why)
+    elif not green:
+        a = (False, "the suite is red on this tree (run %d, exit %s)" % (here[-1]["n"], here[-1].get("exit")))
+    else:
+        # R19: a red under Codex on a tree green under another runtime is waived,
+        # in either order (Codex is best effort). Any other red stands until a
+        # later green under its own runtime: a green elsewhere does not answer it.
+        others = any(g.get("runtime") != "codex" for g in green)
+
+        def answered(r):
+            return (r.get("runtime") == "codex" and others) or any(
+                g["n"] > r["n"] and g.get("runtime") == r.get("runtime") for g in green)
+        unwaived = [r for r in here if r.get("exit") != 0 and not answered(r)]
+        before = [g for g in green if unwaived and g["n"] < unwaived[-1]["n"]]
+        if unwaived and before:
+            a = (False, "the suite went red on this tree after run %d (run %d under %s)"
+                 % (before[-1]["n"], unwaived[-1]["n"], unwaived[-1].get("runtime")))
+        elif unwaived:
+            a = (False, "the suite is red on this tree under %s (run %d); green under %s (run %d) does "
+                        "not answer it" % (unwaived[-1].get("runtime"), unwaived[-1]["n"],
+                                           green[-1].get("runtime"), green[-1]["n"]))
+        else:
+            a = (True, "suite green on %s (run %d)" % (tree[:9], green[-1]["n"]))
+    diff = fs.safe_sensor(sensors.diff_files, root, state["diff"].get("base_tree"), tree)
+    allowed = task.task_files(state)
+    outside = [d["path"] for d in diff or [] if not sensors.scope_any(d["path"], allowed)]
+    if diff is None:
+        b = (False, "the diff since the base tree cannot be measured")
+    elif outside:
+        b = (False, "outside the task's files: %s" % ", ".join(outside[:5])
+             + (" (+%d more)" % (len(outside) - 5) if len(outside) > 5 else ""))
+    else:
+        b = (True, "%d changed files, all in the task's files" % len(diff))
+    return {"a": a, "b": b, "diff": diff or [], "outside": outside, "documents": documents}
+
+def status_lines(root, state):
+    """≤ 20 lines; read-only (the facts are measured, nothing is written)."""
+    lines = ["root: %s" % root]
+    if not state or not state.get("task_id"):
+        return lines + ["task: none — no task in flight", schema_line(root)]
+    events, _ = journal.read_journal(root, state["task_id"])
+    last = events[-1] if events else {}
+    pending = (state.get("questions") or {}).get("pending") or []
+    if task.is_v7(state):
+        # The cache lags a hand-filled [Answer]:; the file is the truth, as guard_pending reads it.
+        with contextlib.suppress(OSError, ValueError, KeyError):
+            _, asked = questions.parse_questions(fs.questions_path(root, state, None))
+            gate_id = task.open_gate(state)
+            pending = [q["id"] for q in asked if (q["kind"] != "G" and questions.is_pending(q)) or q["id"] == gate_id]
+    lines.append("task: %s — %s" % (state["task_id"], fs.one_line(state.get("goal"), 140)))
+    if not task.is_v7(state):
+        lines += ["tier: %s · workflow %s · stage %s" % (state.get("risk_tier") or "?", state.get("workflow"),
+                                                        state.get("current_stage")),
+                  "next: %s" % (fs.one_line(state.get("next_action"), 160) or "?"),
+                  "old surface (schema < 7): /status reads it directly"]
+    else:
+        w = state.get("weight") or {}
+        policy = rr_policy.weight_policy(root)
+        tree = fs.current_tree(root)
+        facts = two_facts(root, state, tree)
+        steps = state.get("steps") or []
+        cur = next((s for s in steps if s.get("status") == "in_progress"), None)
+        review, ver, gate = state["review"], state["verify"], state.get("gate") or {}
+        override = state.get("mode_override") or {}
+        lines += [
+            "mode: %s · W %s · workflow %s%s" % (state["mode"], w.get("w"), state.get("workflow"),
+                                                 " · override %s → %s by %s" % (override.get("from"),
+                                                                               override.get("to"),
+                                                                               override.get("by"))
+                                                 if override else ""),
+            "axes: %s" % " ".join("%s %s" % (a, (w.get("axes") or {}).get(a, "?")) for a in weight.AXES),
+            "stage: %s · next: %s" % (state.get("stage"), fs.one_line(state.get("next_action"), 140)),
+            ("steps: %d of %d done — current %s" % (len([s for s in steps if s["status"] == "done"]), len(steps),
+                                                    cur["id"] if cur else "none")
+             if steps else "steps: one scope"),
+            "files: %d in scope — %s" % (len(task.task_files(state)), ", ".join(task.task_files(state)[:4])
+                                         + (" (+%d more)" % (len(task.task_files(state)) - 4)
+                                            if len(task.task_files(state)) > 4 else "")),
+            "verify: suite %s · runs %d/%s · e2e %s" % (ver["status"], ver["suite_runs"],
+                                                        rr_policy.budget(policy, state, "max_suite_runs")[0],
+                                                        ver.get("e2e")),
+            "facts: (a) %s — %s" % ("green" if facts["a"][0] else "RED", facts["a"][1]),
+            "       (b) %s — %s" % ("green" if facts["b"][0] else "RED", facts["b"][1]),
+            "review: %s (%d of %s) · tier %s%s" % (review["status"], review["passes"],
+                                                   rr_policy.budget(policy, state, "review_rounds_max")[0],
+                                                   review.get("tier") or "-",
+                                                   " · open %s" % ", ".join(review["findings"])
+                                                   if review["findings"] else ""),
+            "gate: %s" % ("approved by %s%s" % (gate["approved_by"], " · confirm \"%s\"" % gate["confirm"]
+                                                if gate.get("confirm") else "")
+                          if gate.get("approved_by") else "requested %s, waiting for the human" % gate.get("gate_id")
+                          if task.open_gate(state) else "not requested"
+                          if state["mode"] in ("full", "full_irreversible") else "none in %s mode" % state["mode"]),
+            "findings: %d recorded in task.md" % len(state.get("findings") or []),
+        ]
+        if rr_policy.batch_on(state):
+            # Before the truncation point, so the 20-line cap never cuts it.
+            lines.insert(3, "batch: on by %s · review %d/%d · suite %d/%d · ready %s" % (
+                fs.one_line(state["batch"].get("by"), 40), review["passes"],
+                rr_policy.budget(policy, state, "review_rounds_max")[0], ver["suite_runs"],
+                rr_policy.budget(policy, state, "max_suite_runs")[0],
+                ", ".join(s["id"] for s in task.ready_steps(state)) or "none"))
+    lines += ["questions: %d pending%s" % (len(pending), " — %s" % ", ".join(map(str, pending[:4])) if pending else ""),
+              schema_line(root),
+              "last event: %s" % (" ".join(fs.one_line(last.get(k), 80) for k in ("ts", "event", "detail")
+                                           if last.get(k)) or "none")]
+    return lines[:20]
+
+def schema_line(root):
+    try:
+        with open(os.path.join(root, ".ai", "VERSION"), encoding="utf-8") as fh:
+            project = fh.read().strip() or "0"
+    except OSError:
+        project = "0"
+    here = os.path.dirname(os.path.dirname(fs.ENTRY))
+    try:
+        names = os.listdir(os.path.join(here, "project-update", "migrations"))
+    except OSError:
+        names = []
+    numbers = [int(n[:4]) for n in names if re.match(r"\d{4}_", n)]
+    plugin = str(max(numbers)) if numbers else "?"
+    behind = project.isdigit() and plugin.isdigit() and int(project) < int(plugin)
+    return "schema: project %s · plugin %s%s" % (project, plugin, " — behind: run /rr-setup --update" if behind else "")
+
+def md_cell(text):
+    return fs.one_line(text, 200).replace("|", "\\|")
+
+def task_md_lines(root, state):
+    """A pure function of the state and the journal: eight sections (§Interfaces).
+    §Questions is "none" here; write_task_md keeps the section already on disk."""
+    events, _ = journal.read_journal(root, state["task_id"])
+    w = state.get("weight") or {}
+    override = state.get("mode_override")
+    out = ["# %s — %s" % (state["task_id"], fs.one_line(state.get("goal"))), "",
+           "%s · %s · started %s · %s" % (state.get("workflow"), state.get("mode"), state.get("created"),
+                                          state.get("owner_runtime") or "unknown"), "",
+           "## Weight", "", "```"] + list(w.get("lines") or []) + ["```"]
+    if override:
+        out.append("override: %s → %s by %s at %s%s" % (override.get("from"), override.get("to"),
+                                                        override.get("by"), override.get("ts"),
+                                                        " — %s" % fs.one_line(override["why"])
+                                                        if override.get("why") else ""))
+    out += ["re-score %s" % fs.one_line(line, 300) for line in w.get("rescores") or []]
+    if rr_policy.batch_on(state):
+        batch = state["batch"]
+        out.append("batch: on by %s at %s%s" % (fs.one_line(batch.get("by"), 80), batch.get("since"),
+                                                " — %s" % fs.one_line(batch["why"]) if batch.get("why") else ""))
+    out += ["", "## Plan", "", "files: %s" % (", ".join(state.get("files") or []) or "none"),
+            "tests: %s" % (", ".join(state.get("tests") or []) or "none")]
+    for step in state.get("steps") or []:
+        out.append("- %s · %s · %s · %s%s" % (step["id"], ", ".join(step["files"]),
+                                              ", ".join(step["tests"]) or "no tests", step["status"],
+                                              " · after %s" % ", ".join(step["after"]) if step.get("after") else ""))
+    out += ["amended %s: +%s — %s" % (a["ts"], ", ".join(a["added"]), fs.one_line(a["why"]))
+            for a in state.get("amendments") or []]
+    out += ["", questions.QUESTIONS_SECTION, "", "none"]
+    out += ["", "## Verify", "", "| n | scope | exit | tree | log | expected_fail |", "|---|---|---|---|---|---|"]
+    for r in state["verify"]["runs"]:
+        out.append("| %s | %s | %s | %s | %s | %s |" % (r["n"], r["scope"], r.get("exit"),
+                                                        (r.get("tree") or "-")[:9], md_cell(r.get("log")),
+                                                        "yes" if r.get("expected_fail") else "no"))
+    out.append("")
+    out.append("suite %s · e2e %s%s · suite runs %d" % (
+        state["verify"]["status"], state["verify"].get("e2e"),
+        " (%s)" % fs.one_line(state["verify"]["e2e_why"]) if state["verify"].get("e2e_why") else "",
+        state["verify"]["suite_runs"]))
+    out += ["finding: %s" % fs.one_line(f, 300) for f in state.get("findings") or []]
+    out += ["", "## Review", ""]
+    for p in state["review"]["log"]:
+        out += ["### Pass %d — %s, %s%s%s" % (p["n"], p["tier"], p["verdict"],
+                                             " (focus %s)" % p["focus"] if p.get("focus") else "",
+                                             " by %s" % p["by"] if p.get("by") else ""), ""]
+        # A fence longer than any backtick run in the text, so a report quoting
+        # code cannot close it early.
+        fence = "`" * max([3] + [len(run) + 1 for run in re.findall(r"`+", p.get("text") or "")])
+        out += ([fence] + p["text"].rstrip("\n").split("\n") + [fence]) if p.get("text", "").strip() \
+            else ["no FINDINGS block"]
+        out.append("")
+    if not state["review"]["log"]:
+        out += ["none yet", ""]
+    if state["review"].get("closed"):
+        out += ["closed by a green run: %s" % ", ".join(state["review"]["closed"]), ""]
+    out += ["## Changes", ""]
+    changes = state.get("changes")
+    if changes is None:
+        out.append("measured at close")
+    else:
+        kind = {"A": "New", "D": "Delete"}
+        out += ["| File | Change | New/Edit/Delete |", "|---|---|---|"]
+        out += ["| %s | %s | %s |" % (md_cell(c["path"]), "binary" if c.get("binary") else
+                                      "+%d −%d" % (c["added"], c["deleted"]), kind.get(c["status"], "Edit"))
+                for c in changes]
+        out += ["", "+%d −%d lines, %d files" % (sum(c["added"] for c in changes),
+                                                 sum(c["deleted"] for c in changes), len(changes))]
+    gate, facts = state.get("gate") or {}, state.get("facts") or {}
+    handoffs = len([e for e in events if e.get("event") == "handoff_written"])
+    out += ["", "## Verdict", "",
+            "close: %s" % (state.get("result") or "open — %s" % fs.one_line(state.get("next_action"))),
+            "facts: (a) %s · (b) %s" % tuple(
+                "%s — %s" % ("green" if facts[k][0] else "RED", facts[k][1]) if facts.get(k) else "not measured"
+                for k in ("a", "b")),
+            "gate: %s" % ("requested %s at %s; approved by %s at %s via %s" % (
+                gate.get("gate_id"), gate.get("requested_at"), gate.get("approved_by") or "-",
+                gate.get("approved_at") or "-", gate.get("via") or "-") if gate else "none"),
+            "confirm: %s" % (gate.get("confirm") or "none"),
+            "handoffs: %d · suite runs: %d · review passes: %d" % (handoffs, state["verify"]["suite_runs"],
+                                                                   state["review"]["passes"])]
+    return out
+
+def write_task_md(root, state):
+    """Rewritten whole and atomically after every change; best effort, because
+    the state is the contract and task.md is rendered from it — except
+    §Questions, which is read back from disk under the questions lock, so an
+    [Answer]: line a human filled survives until `questions --sync` reads it."""
+    path = fs.task_md_path(root, state)
+    tmp = "%s.%d.tmp" % (path, os.getpid())
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with locks.question_lock(path):
+            before, _, after = questions.split_task_md(task_md_lines(root, state))
+            section = questions.question_lines(path)
+            if not any(questions.HEADING_RE.match(line) for line in section):
+                section = ["", "none"]
+            text = "\n".join(before + section + ([""] if section[-1] else []) + after) + "\n"
+            with open(tmp, "w", encoding="utf-8") as fh:
+                fh.write(text)
+            os.replace(tmp, path)
+    except Exception as exc:  # pylint: disable=broad-exception-caught  # derived artefact: never fatal
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        print("state.py: task.md not written (%s)" % exc, file=sys.stderr)

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

@@ -0,0 +1,230 @@
+"""report_cmd: the commands that report -- the plan profile (read, detect, ack, set), the journal event line, the handoff and the status.
+
+shell: cmd_profile, cmd_profile_detect, cmd_profile_ack, cmd_profile_set, cmd_event, cmd_handoff, cmd_status
+"""
+# pylint: disable=unused-argument  # uniform cli dispatch: every cmd_* takes rt
+import contextlib
+import json
+import os
+import sys
+
+from rr_state import dialog, fs, handoff, journal, profile, report, task
+from rr_state import runtime as rr_runtime
+
+
+def cmd_profile(args, _root, rt=rr_runtime.Runtime()):
+    if args.action == "detect":
+        cmd_profile_detect(args, fs.find_root_quiet(args.root), rt=rt)
+        return
+    if args.action == "set":
+        cmd_profile_set(args, rt=rt)
+        return
+    if args.action == "ack":
+        cmd_profile_ack(args, rt=rt)
+        return
+    if args.plan:
+        fs.die("unrecognized argument %r: profile takes detect, set or ack" % args.plan, 2)
+    if args.open or args.detect_runtime:
+        fs.die("--open and --runtime after profile belong to profile detect")
+    runtime = rr_runtime.other_runtime(rt=rt) if args.other else rr_runtime.own_runtime(runtime=rt.name)
+    prof = profile.read_profile(runtime, rt=rt)
+    if not prof:
+        fs.die("no plan profile for %s (%s/riskrails/profile.json); npx riskrails writes it"
+            % (runtime, rr_runtime.runtime_home(runtime)))
+    if args.tier:
+        model = ((prof.get("tiers") or {}).get(args.tier) or {}).get("model")
+        if not model:
+            fs.die("the %s profile has no %s tier" % (runtime, args.tier))
+        print(model)
+        return
+    value = prof
+    if args.field:
+        for part in args.field.split("."):
+            if not isinstance(value, dict) or part not in value:
+                fs.die("the %s profile has no %s" % (runtime, args.field))
+            value = value[part]
+    if args.json or isinstance(value, (dict, list)):
+        print(json.dumps(value, indent=None if args.field else 2, ensure_ascii=False))
+    else:
+        print(value)
+
+
+def cmd_profile_detect(args, root, rt=rr_runtime.Runtime()):
+    """Read-only, exit 0 always (R36.16); `--open` also opens the plan_drift decision (R36.18)."""
+    if args.field or args.tier or args.other or args.plan:
+        fs.die("--field, --tier, --other and a plan belong to the profile reader or profile set, not to profile detect")
+    found = profile.profile_detect(args.detect_runtime or rr_runtime.own_runtime(runtime=rt.name), rt=rt)
+    if args.open:
+        try:
+            found["decision"] = profile.open_drift(root, found, rt=rt)
+        except SystemExit:               # decision.json unreadable: stay read-only, exit 0 (R36.16)
+            found["decision"] = None
+    if args.json:
+        print(json.dumps(found, ensure_ascii=False))
+        return
+    have = (found["installed"] or {}).get("plan") or "none"
+    live = found["live"]
+    print("plan: installed %s · account %s%s → %s" % (
+        have, live["plan"] or "unknown", " (%s)" % live["from"] if live["from"] else "", found["status"]))
+    if found["command"]:
+        print("fix: %s" % found["command"])
+    if found["ack"]:
+        print("keep: %s" % found["ack"])
+    if found["decision"]:
+        print("decision: %s" % found["decision"])
+
+
+def cmd_profile_ack(args, rt=rr_runtime.Runtime()):
+    """32ee: the terminal route to "Keep" — with the dialog off no plan_drift decision
+    opens, so this is the only way to silence a drift the human chose to stay on. The
+    same drift-ack.json the decision's Keep writes; any plan_drift decision still open
+    is settled as stale by the next `detect --open`."""
+    if args.open or args.field or args.tier or args.other or args.json or args.plan:
+        fs.die("profile ack takes --runtime only")
+    runtime = args.detect_runtime or rr_runtime.own_runtime(runtime=rt.name)
+    via, why = dialog.human_route(None, rt=rt)
+    if not via:
+        fs.die("profile ack is the human's: %s" % why, 5)
+    found = profile.profile_detect(runtime, rt=rt)
+    status = found["status"]
+    if status == "same":
+        print("no drift: nothing to acknowledge")
+        return
+    if status == "acknowledged":
+        print("already acknowledged; nothing written")
+        return
+    if status != "drift":
+        fs.die("nothing to acknowledge: plan %s" % status)
+    kept = found["installed"]["plan"]
+    profile.write_drift_ack(runtime, found["live"]["fingerprint"], kept, via)
+    print("drift-ack.json: keep %s for this %s account (%s); delete %s to be asked again"
+          % (kept, runtime, found["live"]["plan"], profile.drift_ack_path(runtime)))
+
+
+def cmd_profile_set(args, rt=rr_runtime.Runtime()):
+    """R36.17: the human route only. A same-tier plan rewrites profile.json alone;
+    one whose settings or tiers differ is the installer's (exit 6)."""
+    if args.open or args.field or args.tier or args.other or args.json:
+        fs.die("profile set takes a plan and --runtime only")
+    runtime = args.detect_runtime or rr_runtime.own_runtime(runtime=rt.name)
+    plans = profile.PLAN_PROFILES.get(runtime) or {}
+    if args.plan not in plans:
+        fs.die("profile set needs a %s plan: %s (got %r)" % (runtime, ", ".join(plans), args.plan or ""))
+    via, why = dialog.human_route(fs.find_root_quiet(args.root), allow_dialog=True, rt=rt)
+    if not via:
+        fs.die("profile set is the human's: %s" % why, 5)
+    prof = profile.read_profile(runtime, rt=rt)
+    if not prof:
+        fs.die("no plan profile for %s (%s/riskrails/profile.json); npx riskrails writes it"
+            % (runtime, rr_runtime.runtime_home(runtime)))
+    have = prof.get("plan")
+    if have == args.plan:
+        print("profile.json: already %s (%s); nothing written" % (have, runtime))
+        return
+    refusal = "PROFILE_NEEDS_INSTALLER — %s → %s also changes %s: %s" % (
+        have, args.plan, "settings.json and the agents" if runtime == "claude" else "config.toml and the agents",
+        profile.installer_command(runtime, args.plan, prof.get("plugin_version"), profile.context_mode(prof)))
+    if have not in plans or not any({have, args.plan} <= pair for pair in profile.SAME_TIER[runtime]):
+        fs.die(refusal, 6)
+    resolver, src = profile.load_resolver(runtime)
+    if resolver is None:
+        fs.die("no resolve-profile.py under %s/riskrails/scripts or the plugin; npx riskrails installs it"
+            % rr_runtime.runtime_home(runtime))
+    fable = bool(prof.get("fable"))
+    # Only an economy record passes context: a resolver installed before --context
+    # has no such parameter, and only a later one writes an economy record.
+    extra = {"context": "economy"} if profile.context_mode(prof) else {}
+    try:
+        old = resolver.resolve(src, plans[have][0], have, plans[have][1], fable, **extra)
+        new = resolver.resolve(src, plans[args.plan][0], args.plan, plans[args.plan][1], fable, **extra)
+    except (OSError, ValueError) as exc:
+        fs.die("cannot resolve the %s profile: %s" % (args.plan, exc))
+    key = resolver.KEY
+
+    def rendered(data):
+        return ({k: v for k, v in data.items() if k != key}, data[key].get("tiers"))
+    if rendered(old) != rendered(new):
+        fs.die(refusal, 6)
+    out = dict(new[key], runtime=runtime, written_at=fs.now(), set_by={"via": via, "at": fs.now()})
+    for kept in ("plugin_version", "dialog"):
+        if kept in prof:
+            out[kept] = prof[kept]
+    target = os.path.join(rr_runtime.runtime_home(runtime), "riskrails", "profile.json")
+    tmp = "%s.%d.tmp" % (target, os.getpid())
+    try:
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(out, fh, indent=2, ensure_ascii=False)
+            fh.write("\n")
+        os.replace(tmp, target)
+    except OSError as exc:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        fs.die("cannot write %s: %s" % (target, exc))
+    print("profile.json: %s → %s (%s); settings and agents unchanged; the managed block and routing.md "
+          "keep the label '%s' until the next npx riskrails" % (have, args.plan, runtime, plans[have][1]))
+
+
+def cmd_event(args, root, rt=rr_runtime.Runtime()):
+    """For hooks and for WP5's model fallback: one journal line, no state write.
+    The state file keeps its two writers; this command is not one of them."""
+    if args.type not in journal.EVENT_TYPES:
+        fs.die("unknown event type '%s' (have: %s)" % (args.type, ", ".join(journal.EVENT_TYPES)))
+    if args.type in journal.FORGEABLE_EVENTS:
+        # The journal is the compensating control for every route the gate
+        # cannot block, so the actor it audits may not author its lines. These
+        # types are emitted by the state transition that earns them, and by
+        # nothing else: an agent that took the unattended route could otherwise
+        # append a second, honest-looking gate_approved next to it.
+        fs.die("'%s' is emitted by the state transition that earns it, not by 'event'. "
+            "A journal the agent can write is not an audit trail." % args.type, 5)
+    data = {}
+    if args.data:
+        try:
+            data = json.loads(args.data)
+        except (ValueError, RecursionError) as exc:
+            fs.die("--data must be a JSON object (%s)" % exc)
+        if not isinstance(data, dict):
+            fs.die("--data must be a JSON object")
+    state = task.load(root, rt=rt)
+    journal.append_journal(root, state["task_id"], journal.journal_line(
+        state["task_id"], args.type, "agent" if args.type == "note" else "hook",
+        state.get("current_stage"), args.detail, data, runtime=rt.name))
+    print("%s recorded" % args.type)
+
+
+def cmd_handoff(args, root, rt=rr_runtime.Runtime()):
+    if args.to:
+        handoff.handoff_to(args, root, rt=rt)
+        return
+    state = task.load(root, rt=rt)
+    lines = handoff.write_handoff(root, state, args.reason, rt=rt)
+    if lines is None:
+        print("state.py: could not write %s" % os.path.relpath(fs.handoff_path(root), root),
+              file=sys.stderr)
+        # --print still answers from the render the caller asked for.
+        lines = handoff.handoff_lines(root, state, args.reason, rt=rt)
+    if args.print_it:
+        for line in lines:
+            print(line)
+    else:
+        print(os.path.relpath(fs.handoff_path(root), root))
+
+
+def cmd_status(args, root, rt=rr_runtime.Runtime()):
+    state = task.load(root, required=False, claim=False, rt=rt)
+    if args.json:
+        out = {"root": root, "task_id": (state or {}).get("task_id"), "schema": (state or {}).get("schema")}
+        if task.is_v7(state):
+            tree = fs.current_tree(root)
+            facts = report.two_facts(root, state, tree)
+            out.update({k: state.get(k) for k in ("goal", "workflow", "mode", "stage", "next_action",
+                                                  "files", "tests", "steps", "verify", "review", "gate",
+                                                  "mode_override", "findings")})
+            out["weight"] = {k: (state.get("weight") or {}).get(k) for k in ("w", "axes", "hints", "unknown",
+                                                                            "operations")}
+            out["facts"] = {"a": list(facts["a"]), "b": list(facts["b"]), "tree": tree}
+            out["questions_pending"] = len((state.get("questions") or {}).get("pending") or [])
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+        return
+    print("\n".join(report.status_lines(root, state)))