riskrails 3.0.1 → 3.2.1

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

@@ -0,0 +1,165 @@
+"""review: the `review` command -- one reviewer pass recorded, the verdict checked against the findings block, the findings closed by a green suite.
+
+core: REVIEW_TIERS, FINDING_RE, OUT_OF_SCOPE_RE, open_findings, VERDICT_LINE_RE
+shell: read_report, verdict_matches_findings, cmd_review, review_closes
+"""
+# pylint: disable=protected-access  # cmd_review calls fs._split_files, which partition.json assigns to fs
+import os
+import re
+import shlex
+import sys
+
+from rr_state import dialog, fs, handoff, journal, task
+from rr_state import labels as rr_labels
+from rr_state import policy as rr_policy
+from rr_state import report as rr_report
+from rr_state import runtime as rr_runtime
+
+REVIEW_TIERS = ["BALANCED", "STRONG"]
+FINDING_RE = re.compile(r"\[(BLOCKER|HIGH|MEDIUM|LOW|INFO)\]\s+([A-Z][0-9]+)\b")
+OUT_OF_SCOPE_RE = re.compile(r"in_scope:\s*no\b", re.I)
+
+
+def read_report(source):
+    if not source:
+        return ""
+    if source == "-":
+        return sys.stdin.read()
+    try:
+        with open(source, encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        fs.die("--report %s: %s" % (source, exc))
+    return ""                             # unreachable: die() exits
+
+
+def open_findings(text, severities=("BLOCKER", "HIGH")):
+    """Labels of `severities` whose block does not say in_scope: no."""
+    hits = list(FINDING_RE.finditer(text or ""))
+    out = []
+    for i, m in enumerate(hits):
+        block = text[m.start():hits[i + 1].start() if i + 1 < len(hits) else len(text)]
+        if m.group(1) in severities and not OUT_OF_SCOPE_RE.search(block):
+            out.append(m.group(2))
+    return out
+
+
+# "VERDICT pass", "VERDICT: pass", "## VERDICT pass" and the shipped reviewer's
+# "## VERDICT" section with its "verdict: pass" line (ai/agents/reviewer.md).
+VERDICT_LINE_RE = re.compile(r"^(?:#+[ \t]*)?verdict[ \t]*:?[ \t]*(pass_with_findings|blockers_open|pass)\b",
+                             re.M | re.I)
+
+
+def verdict_matches_findings(verdict, text):
+    """The verdict a reviewer's FINDINGS block allows: an in-scope BLOCKER is
+    blockers_open, an in-scope HIGH is not a pass, and a VERDICT line in the
+    block is the verdict. The block is the evidence; a verdict without it is a
+    claim nobody can audit."""
+    if not (text or "").strip() or "FINDINGS" not in text:
+        fs.die("review needs the reviewer's FINDINGS block: --report - (stdin) or --report FILE")
+    blockers, highs = (open_findings(text, (sev,)) for sev in ("BLOCKER", "HIGH"))
+    said = VERDICT_LINE_RE.search(text)
+    if said and said.group(1) != verdict:
+        fs.die("--verdict %s, but the report's VERDICT line says %s" % (verdict, said.group(1)))
+    if blockers and verdict != "blockers_open":
+        fs.die("the report has an in-scope BLOCKER (%s): the verdict is blockers_open, not %s"
+            % (", ".join(blockers), verdict))
+    if highs and verdict == "pass":
+        fs.die("the report has an in-scope HIGH (%s): the verdict is pass_with_findings or blockers_open"
+            % ", ".join(highs))
+
+
+def cmd_review(args, root, rt=rr_runtime.Runtime()):
+    """One pass recorded; the pass past review_rounds_max is the human's (exit 6)."""
+    state = task.load_v7(root, rt=rt)
+    policy = rr_policy.weight_policy(root)
+    review = state["review"]
+    if args.closes:
+        review_closes(root, state, fs._split_files(args.closes), rt=rt)
+        return
+    if not args.verdict or not args.tier:
+        fs.die("review needs --verdict pass|pass_with_findings|blockers_open and --tier BALANCED|STRONG")
+    rounds, budget_name = rr_policy.budget(policy, state, "review_rounds_max")
+    by_human = None
+    if review["passes"] >= rounds:
+        if not args.by:
+            report = ["--report", os.path.abspath(args.report)] if args.report and os.path.isfile(args.report) else []
+            dialog.offer_decision(root, state, "human_set", "Review",
+                           "%s\nREVIEW_BUDGET: %d review passes; weight.json allows %d%s. The next verdict is yours."
+                           % (dialog.task_facts(root, state), review["passes"], rounds,
+                              " (%s)" % budget_name if rr_policy.batch_on(state) else ""),
+                           [{"kind": "choice", "effect": "keep", "label": "Keep it open — no verdict now"}] +
+                           [{"kind": "command",
+                             "label": rr_labels.state_label(root, ["review", "--verdict", verdict, "--tier", args.tier] +
+                                                     report + ["--by", rr_labels.human_name(root)])}
+                            for verdict in ("pass", "pass_with_findings", "blockers_open")], "review", rt=rt)
+            fs.die("REVIEW_BUDGET — %d review passes; weight.json allows %d (%s). The next "
+                "verdict is the human's, in their own terminal:\n  python3 %s --root %s review --verdict "
+                "<verdict> --tier %s --by \"<name>\"" % (review["passes"], rounds, budget_name,
+                                                         shlex.quote(fs.ENTRY),
+                                                         shlex.quote(root), args.tier), 6)
+        via, why = dialog.human_route(root, allow_dialog=True, rt=rt)
+        if via is None:
+            fs.die("APPROVAL_REFUSED — a verdict past the review budget is the human's, from their own "
+                "terminal.\nRefused because %s." % why, 5)
+        by_human = (args.by, via)
+    wanted = rr_policy.mode_setting(policy, state["mode"], "reviewer", "BALANCED")
+    if wanted in REVIEW_TIERS and REVIEW_TIERS.index(args.tier) < REVIEW_TIERS.index(wanted):
+        fs.die("%s mode needs a %s review (weight.json modes.%s.reviewer); this one was %s"
+            % (state["mode"], wanted, state["mode"], args.tier))
+    text = read_report(args.report)
+    if not by_human:
+        verdict_matches_findings(args.verdict, text)
+    labels = [m.group(2) for m in FINDING_RE.finditer(text)]
+    status = rr_policy.VERDICT_STATUS[args.verdict]
+    tree = fs.current_tree(root)
+    review.update(status=status, passes=review["passes"] + (0 if by_human else 1), tier=args.tier,
+                  findings=open_findings(text), tree=tree, ts=fs.now(),
+                  runs_at=len(state["verify"]["runs"]))
+    review["log"].append({"n": len(review["log"]) + 1, "tier": args.tier, "verdict": args.verdict,
+                          "focus": args.focus, "text": text[:20000], "tree": tree, "ts": fs.now(),
+                          "runtime": rt.name, "by": by_human[0] if by_human else None})
+    state["stage"] = "review"
+    if by_human:
+        journal.emit(root, state, "human_set", "review %s by %s via %s" % (args.verdict, by_human[0], by_human[1]),
+             dict({"field": "review", "value": status, "by": by_human[0], "via": by_human[1],
+                   "unattended": by_human[1] == "unattended"}, **dialog.pick_data(dialog.DIALOG_PICK[0])),
+             actor="human" if by_human[1] == "terminal" else "agent", rt=rt)
+    journal.emit(root, state, "review_verdict", "%s on %s (pass %d)" % (args.verdict, args.tier, review["passes"]),
+         {"verdict": args.verdict, "tier": args.tier, "pass_n": review["passes"], "labels": labels,
+          "focus": args.focus}, rt=rt)
+    state["next_action"] = rr_policy.review_next_action(state)
+    handoff.write_handoff(root, state, "review", rt=rt)
+    task.save(root, state)
+    rr_report.write_task_md(root, state)
+    print("review: %s (%s, pass %d of %d)%s" % (status, args.tier, review["passes"], rounds,
+                                               " — open: %s" % ", ".join(review["findings"])
+                                               if review["findings"] else ""))
+
+
+def review_closes(root, state, labels, rt=rr_runtime.Runtime()):
+    """passed_with_findings → passed once a green suite run after the verdict, on
+    a tree the fix changed, is the tree now (§3a, without a second review)."""
+    review = state["review"]
+    if review["status"] != "passed_with_findings":
+        fs.die("--closes is for a passed_with_findings review; this one is %s" % review["status"])
+    unknown = [l for l in labels if l not in review["findings"]]
+    if not labels or unknown:
+        fs.die("--closes names open findings (%s); not open: %s"
+            % (", ".join(review["findings"]) or "none", ", ".join(unknown) or "none given"))
+    tree = fs.current_tree(root)
+    runs = [r for r in state["verify"]["runs"][review.get("runs_at") or 0:]
+            if rr_policy.full_suite(r) and r.get("exit") == 0]
+    if not runs or runs[-1].get("tree") != tree or tree == review.get("tree"):
+        fs.die("findings %s stay open: they close on a green 'state.py verify --scope suite|all --after-fix "
+            "\"…\"' after the verdict, on a tree the fix changed, which is the tree now" % ", ".join(labels))
+    review["findings"] = [l for l in review["findings"] if l not in labels]
+    review["closed"] = list(review.get("closed") or []) + labels
+    if not review["findings"]:
+        review["status"] = "passed"
+    journal.emit(root, state, "findings_closed", "%s closed by suite run %d on %s"
+         % (", ".join(labels), runs[-1]["n"], tree[:9]),
+         {"labels": labels, "run": runs[-1]["n"], "tree": tree}, rt=rt)
+    task.save(root, state)
+    rr_report.write_task_md(root, state)
+    print("findings closed: %s; review %s" % (", ".join(labels), review["status"]))

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

@@ -0,0 +1,80 @@
+"""The runtime: which runtime (claude or codex) this process acts as, where each one is installed, and the agent markers in the environment.
+
+shell: Runtime, installed_runtime, detect_runtime, runtime_home, own_runtime, other_runtime, installed, agent_markers
+core: RUNTIMES, AGENT_MARKERS
+"""
+
+import dataclasses
+import os
+
+from rr_state import fs
+
+RUNTIMES = ["claude", "codex"]
+
+
+@dataclasses.dataclass(frozen=True)
+class Runtime:
+    """The runtime this process acts as and whether the command mutates state; built once by cli.main from the three resolutions, never changed (R4)."""
+    name: str = "unknown"
+    mutating: bool = False
+
+
+def installed_runtime():
+    """The runtime whose home this copy is installed in, or None for a checkout.
+    Both skills call state.py from their own home ($AI_HOME), so this answers
+    for every call a runtime makes."""
+    here = fs.ENTRY
+    for runtime in ("codex", "claude"):
+        home = os.path.abspath(runtime_home(runtime)).rstrip(os.sep) + os.sep
+        if here.startswith(home):
+            return runtime
+    return None
+
+
+def detect_runtime(explicit, root):
+    """--runtime > AI_RUNTIME > install location > CLAUDECODE > session.json >
+    unknown (I10). session.json names whichever runtime was prompted last, so it
+    comes after everything the process itself can tell: read first, it let one
+    runtime's change pass as the other's while both were working. The install
+    location outranks CLAUDECODE because an environment variable is inherited:
+    codex started from a Claude Code shell carries CLAUDECODE=1 (seen live)."""
+    for candidate in (explicit, os.environ.get("AI_RUNTIME"), installed_runtime(),
+                      "claude" if os.environ.get("CLAUDECODE") else None,
+                      fs.read_session(root).get("runtime")):
+        if candidate in RUNTIMES:
+            return candidate
+    return "unknown"
+
+
+def runtime_home(runtime):
+    if runtime == "codex":
+        return os.environ.get("CODEX_HOME") or os.path.join(os.path.expanduser("~"), ".codex")
+    return os.environ.get("CLAUDE_CONFIG_DIR") or os.path.join(os.path.expanduser("~"), ".claude")
+
+
+def own_runtime(runtime="unknown"):
+    """This process's runtime; an undetected one is read from where this file
+    is installed, so a plain shell under ~/.codex still reads the Codex plan."""
+    if runtime in RUNTIMES:
+        return runtime
+    return "codex" if "%s.codex%s" % (os.sep, os.sep) in fs.ENTRY else "claude"
+
+
+def other_runtime(runtime=None, rt=Runtime()):
+    return "codex" if (runtime or own_runtime(runtime=rt.name)) == "claude" else "claude"
+
+
+def installed(runtime):
+    return os.path.isfile(os.path.join(runtime_home(runtime), "skills", "ai-task", "state.py"))
+
+
+# Set by the runtimes in every process they start, the `!` prefix's shell
+# included. Duplicated on purpose from skills/project-update/adopt.py
+# (AGENT_MARKERS): the two skills are installed independently and neither
+# imports the other.
+AGENT_MARKERS = ("CLAUDECODE", "CODEX_THREAD_ID", "CODEX_SESSION_ID", "CODEX_CI",
+                 "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_VERSION")
+
+
+def agent_markers():
+    return [name for name in AGENT_MARKERS if name in os.environ]

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

@@ -0,0 +1,257 @@
+"""start: the `weight` and `start` commands -- the six axes and a mode from weight.json, and the task started under them with the scope guard armed.
+
+shell: cmd_weight, parse_declares, cmd_start, start_amend
+core: WORKFLOWS, arm_scope
+"""
+# pylint: disable=protected-access  # cmd_weight, cmd_start and start_amend call fs._split_files, which partition.json assigns to fs
+# pylint: disable=unused-argument  # cmd_weight takes the same arguments as every command, rt included (uniform cli dispatch)
+import contextlib
+import json
+import os
+import re
+import shlex
+import sys
+
+from rr_state import fs, journal, task, dialog, labels, report, profile, handoff
+from rr_state import policy as rr_policy
+from rr_state import runtime as rr_runtime
+
+# sensors.py and weight.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
+
+WORKFLOWS = ["feature", "bugfix", "refactoring", "hotfix", "investigation"]
+
+
+def cmd_weight(args, root, rt=rr_runtime.Runtime()):
+    """Six axes and a mode from weight.json. Read-only, and it needs no task:
+    the weight is what decides how a task is run, so it comes before one."""
+    if weight is None:
+        fs.die("weight.py is missing beside state.py: reinstall the plugin")
+    try:
+        policy, path = weight.load_policy(root)
+    except (OSError, ValueError, RecursionError) as exc:
+        fs.die("cannot read the weight table: %s" % exc)
+    if args.mirror:
+        own = os.path.join(root, ".ai", "policies", "weight.json")
+        if path != own:
+            fs.die("%s has no .ai/policies/weight.json: the mirror is written beside the project's own table"
+                % root)
+        target = os.path.join(os.path.dirname(own), "weight.md")
+        tmp = "%s.%d.tmp" % (target, os.getpid())
+        try:
+            with open(tmp, "w", encoding="utf-8") as fh:
+                fh.write(weight.mirror(own))
+            os.replace(tmp, target)
+        except OSError as exc:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            fs.die("cannot write %s: %s" % (target, exc))
+        print(target)
+        return
+    files = fs._split_files(args.files)
+    if not files:
+        fs.die("weight needs --files: the declared files are what it measures")
+    declared = {}
+    for item in args.declare:
+        m = re.match(r"^(\w+)=(\d{1,3}):(.*\S.*)$", item, re.S)
+        if not m:
+            fs.die("--declare %r: write axis=n:\"evidence\" — a declaration without its evidence is not one"
+                % item)
+        declared[m.group(1)] = (int(m.group(2)), m.group(3).strip())
+    try:
+        result = rr_policy.weigh(root, files, declared, args.goal, policy)
+    except ValueError as exc:
+        fs.die(str(exc))
+    except (TypeError, AttributeError) as exc:     # a table whose values have the wrong shape
+        fs.die("%s is malformed: %s" % (path, exc))
+    if args.json:
+        out = dict(result.as_dict(), policy=path)
+        if result.documents_only is not None:
+            out["documents_only"] = result.documents_only
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print(weight.render(result, long=args.long))
+
+
+def arm_scope(state):
+    """The legacy view the scope guard (hooks/guard/scope.py) reads (D2): stage implementation and one
+    step holding every file of the task, for as long as the task is open."""
+    state["current_stage"] = "implementation"
+    state["approved_plan"] = {"ref": "inline", "current_step_id": "task", "steps": [{
+        "step_id": "task", "description": state.get("goal"), "allowed_files": task.task_files(state),
+        "forbidden_files": [], "forbidden_reason": "not part of this task",
+        "required_tests": list(state.get("tests") or []), "status": "in_progress"}]}
+
+
+def parse_declares(items):
+    declared = {}
+    for item in items or []:
+        m = re.match(r"^(\w+)=(\d{1,3}):(.*\S.*)$", item, re.S)
+        if not m:
+            fs.die("--declare %r: write axis=n:\"evidence\" — a declaration without its evidence is not one"
+                % item)
+        declared[m.group(1)] = (int(m.group(2)), m.group(3).strip())
+    return declared
+
+
+def cmd_start(args, root, rt=rr_runtime.Runtime()):
+    """The task, its weight and its mode in one call; the scope guard is armed."""
+    if args.amend:
+        start_amend(args, root, rt=rt)
+        return
+    missing = [flag for flag, value in (("--goal", args.goal), ("--workflow", args.workflow),
+                                        ("--files", args.files)) if not value]
+    if missing:
+        fs.die("start needs %s (or --amend to widen the task in flight)" % ", ".join(missing))
+    if args.workflow not in WORKFLOWS:
+        fs.die("workflow must be one of: %s" % ", ".join(WORKFLOWS))
+    existing = task.load(root, required=False, claim=False, rt=rt)
+    if existing and existing.get("current_stage") != "done":
+        fs.die("task %s is in flight: finish it with 'state.py close' (or 'close --abandon'), or widen it "
+            "with 'state.py start --amend --files \"+a\" --why \"…\"'" % existing.get("task_id"))
+    files, tests = fs._split_files(args.files), fs._split_files(args.tests)
+    if not files:
+        # An empty list would arm a scope guard that allows everything.
+        fs.die("--files must name at least one file or glob the task may touch")
+    if fs.current_tree(root) is None:
+        fs.die("start needs a git repository: the two facts close decides by are measured on its tree")
+    steps = task.parse_steps(args.steps, args.plan_file)
+    policy = rr_policy.weight_policy(root)
+    table = rr_policy.batch_policy(policy, strict=True)      # a malformed section is refused here, not at status
+    if args.batch and args.no_batch:
+        fs.die("--batch and --no-batch exclude each other")
+    if args.batch and not args.by:
+        fs.die("--batch needs --by \"<who asked for the batch loop>\": it is journaled with its author")
+    batch = {"on": False, "by": None, "why": None, "since": None}
+    if args.batch:
+        batch = {"on": True, "by": args.by, "why": args.why or None, "since": fs.now()}
+    elif not args.no_batch and table["default"]:
+        batch = {"on": True, "by": "weight.json batch.default", "why": None, "since": fs.now()}
+    # Shared files order steps only in a batch task, where steps run side by
+    # side; a standard task's steps run one after another, as before.
+    implied = task.order_shared_files(steps) if batch["on"] else []
+    task.check_steps(steps, implied)
+    concrete = [f for f in files if not any(c in f for c in "*?[")]
+    try:
+        result = rr_policy.weigh(root, concrete, parse_declares(args.declare), args.goal, policy,
+                       [f for f in files if f not in concrete])
+    except ValueError as exc:
+        fs.die(str(exc))
+    except (TypeError, AttributeError) as exc:
+        fs.die("the weight table is malformed: %s" % exc)
+    mode, override = result.mode, None
+    if args.mode:
+        if args.mode not in rr_policy.MODES:
+            fs.die("--mode takes one of: %s" % ", ".join(rr_policy.MODES))
+        if not args.by:
+            fs.die("--mode needs --by \"<who>\": an override is journaled with its author")
+        if args.mode == mode:
+            args.mode = None              # the weight already says so: nothing to override
+    via = None
+    if args.mode:
+        if rr_policy.MODES.index(args.mode) < rr_policy.MODES.index(mode):
+            via, why = dialog.human_route(root, allow_dialog=True, rt=rt)
+            if via is None:
+                dialog.offer_decision(root, None, "human_set", "Mode",
+                               "%s — W %s, the weight says %s.\nLower the mode from %s to %s (by %s)?"
+                               % (fs.one_line(args.goal, 300), result.w, mode, mode, args.mode, args.by),
+                               [{"kind": "choice", "effect": "keep", "label": "Keep mode %s" % mode},
+                                {"kind": "command", "label": labels.state_label(root, sys.argv[1:])}], "start --mode", rt=rt)
+                fs.die("APPROVAL_REFUSED — lowering the mode from %s to %s is a human's decision. Run it in "
+                    "your own terminal:\n  python3 %s --root %s start … --mode %s --by %s\nRefused because %s."
+                    % (mode, args.mode, shlex.quote(fs.ENTRY), shlex.quote(root),
+                       args.mode, shlex.quote(args.by), why), 5)
+        override = {"from": mode, "to": args.mode, "by": args.by, "why": args.why, "ts": fs.now()}
+        mode = args.mode
+    if args.slug is not None:
+        import memory_format              # pylint: disable=import-outside-toplevel
+        if args.task_id:
+            fs.die("--slug and --task-id both name the id: pass one", 2)
+        if not memory_format.SLUG_RE.match(args.slug):
+            fs.die("--slug takes 3-24 characters of [a-z0-9] words joined by '-', not %r" % args.slug, 2)
+    task_id = task.valid_task_id(args.task_id) if args.task_id else task.next_task_id(root, args.goal, args.slug)
+    base_tree = fs.current_tree(root)
+    state = {
+        "schema": task.SCHEMA, "task_id": task_id, "goal": args.goal, "workflow": args.workflow,
+        "mode": mode, "weight": dict(result.as_dict(), lines=weight.render(result).split("\n"),
+                                     tree=base_tree, computed_at=fs.now(), rescores=[], operations=[]),
+        "mode_override": override, "stage": "build", "files": files, "tests": tests,
+        "steps": steps, "amendments": [], "findings": [], "batch": batch,
+        "diff": {"base_tree": base_tree, "base_commit": fs.safe_sensor(sensors.head_commit, root)},
+        "gate": None, "owner_runtime": rt.name if rt.name in rr_runtime.RUNTIMES else None,
+        "created": fs.now(), "created_at": fs.now(), "history": [],
+    }
+    if result.documents_only is not None:
+        state["weight"]["documents_only"] = result.documents_only
+    if os.path.exists(fs.ledger_path(root)):
+        # The ledger is per project: a task mirrors only the lines after its start.
+        state["dialog"] = {"ledger_pos": os.path.getsize(fs.ledger_path(root))}
+    task.apply_defaults_v7(state)
+    if steps:
+        # The first step whose dependencies are done — steps[0] in a plan without `after`.
+        next(iter(task.ready_steps(state)), steps[0]).update(status="in_progress", tree_before=base_tree)
+    arm_scope(state)
+    state["next_action"] = rr_policy.next_action_for(state)
+    journal.emit(root, state, "task_started", fs.one_line(args.goal, 200),
+         {"goal": args.goal, "workflow": args.workflow, "mode": mode, "schema": task.SCHEMA}, rt=rt)
+    journal.emit(root, state, "weight_set", "W %d → %s" % (result.w, result.mode),
+         {"w": result.w, "mode": result.mode, "axes": result.axes, "hints": result.hints,
+          "unknown": result.unknown}, rt=rt)
+    if override:
+        journal.emit(root, state, "mode_set", "%s -> %s by %s" % (override["from"], mode, args.by),
+             dict({"from": override["from"], "to": mode, "by": args.by, "why": args.why},
+                  **(dict(via=via, **dialog.pick_data(dialog.DIALOG_PICK[0])) if via else {})),
+             actor="human" if rr_policy.MODES.index(mode) < rr_policy.MODES.index(override["from"]) else "agent", rt=rt)
+    journal.emit(root, state, "tier_set", "%s (mode %s, compat)" % (rr_policy.MODE_TIER[mode], mode),
+         {"tier": rr_policy.MODE_TIER[mode], "mode": mode, "w": result.w}, rt=rt)
+    if batch["on"]:
+        journal.emit(root, state, "batch_set", "on by %s" % batch["by"],
+             {"on": True, "by": batch["by"], "why": batch["why"], "via": None, "review_passes": 0, "suite_runs": 0}, rt=rt)
+    handoff.set_resume_point(state, rt=rt)
+    handoff.write_handoff(root, state, "start", rt=rt)
+    task.save(root, state)
+    report.write_task_md(root, state)
+    print(weight.render(result))
+    if override:
+        print("mode: %s (override of %s by %s)" % (mode, override["from"], args.by))
+    for later, earlier, shared in implied:
+        print("ordered: %s after %s (shares %s)" % (later, earlier, shared))
+    if batch["on"]:
+        print("batch: on by %s · review %s passes · suite %s runs · %s at once on %s"
+              % (batch["by"], table["review_rounds_max"], table["max_suite_runs"], table["parallel"], table["tier"]))
+    advice = int((policy.get("rules") or {}).get("steps_advice_over", 8))
+    if len(steps) > advice:
+        print("advice: %d steps, over %d — fewer, larger steps cost fewer handoffs (not a gate)"
+              % (len(steps), advice))
+    print("%s started: %s · %d files in scope · %s"
+          % (task_id, mode, len(task.task_files(state)), os.path.relpath(fs.task_md_path(root, state), root)))
+    print("next: %s" % state["next_action"])
+    profile.advise(state, rt=rt)
+
+
+def start_amend(args, root, rt=rr_runtime.Runtime()):
+    """R25: the task's files grow in place, journaled, never back to a plan."""
+    state = task.load_v7(root, rt=rt)
+    added = [f.lstrip("+").strip() for f in fs._split_files(args.files)]
+    added = [f for f in added if f]
+    if not added or not (args.why or "").strip():
+        fs.die("--amend needs --files \"+a,+b\" and --why \"<why the task needs them>\"")
+    new = [f for f in added if f not in state["files"]]
+    if not new:
+        print("scope unchanged: %s already in the task" % ", ".join(added))
+        return
+    state["files"] += new
+    state["amendments"].append({"ts": fs.now(), "added": new, "why": args.why})
+    arm_scope(state)
+    journal.emit(root, state, "scope_change", "+%s — %s" % (", ".join(new), fs.one_line(args.why, 200)),
+         {"added": new, "why": args.why}, rt=rt)
+    task.save(root, state)
+    report.write_task_md(root, state)
+    print("scope amended: +%s (%d files in scope)" % (", ".join(new), len(task.task_files(state))))

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

@@ -0,0 +1,131 @@
+"""steps: the `steps`, `step-done` and `batch` commands -- a multi-step task's steps and the batch loop's switch.
+
+shell: cmd_step_done_v7, cmd_steps, cmd_batch
+"""
+# pylint: disable=unused-argument
+# (uniform cli dispatch: every cmd_* takes rt last, whether it uses it or not)
+import json
+import shlex
+
+from rr_state import dialog, fs, handoff, journal, report, task
+from rr_state import policy as rr_policy   # cmd_batch binds a local `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 cmd_step_done_v7(args, root, rt=rr_runtime.Runtime()):
+    """A multi-step task's step is done when its diff stays inside the task."""
+    state = task.load_v7(root, rt=rt)
+    steps = state["steps"]
+    if not steps:
+        fs.die("step-done is for a multi-step guarded or full task; this one is one scope — verify, then close")
+    step = next((s for s in steps if s["id"] == args.step_id), None)
+    if step is None:
+        fs.die("no step %s (have: %s)" % (args.step_id, ", ".join(s["id"] for s in steps)))
+    if step["status"] == "done":
+        print("step %s already done" % step["id"])
+        return
+    tree = fs.current_tree(root)
+    diff = fs.safe_sensor(sensors.diff_files, root, step.get("tree_before") or state["diff"].get("base_tree"), tree)
+    outside = [d["path"] for d in diff or [] if not sensors.scope_any(d["path"], task.task_files(state))]
+    if outside:
+        fs.die("SCOPE_CHANGE_REQUIRED — step %s changed %s, outside the task's files. Widen the task in "
+            "place: state.py start --amend --files \"%s\" --why \"…\""
+            % (step["id"], ", ".join(outside), ",".join("+" + p for p in outside)), 6)
+    # In a wave the diff since the step began holds other steps' work too. The
+    # journal says which changed paths were this step's own (its files and
+    # tests) and which were not, so a step that strayed into another's files is
+    # visible; `unready` names dependencies it was recorded ahead of.
+    own_scope = list(step.get("files") or []) + list(step.get("tests") or [])
+    own = [d["path"] for d in diff or [] if sensors.scope_any(d["path"], own_scope)]
+    others = [d["path"] for d in diff or [] if d["path"] not in own]
+    unready = [dep for dep in step.get("after") or [] if any(s["id"] == dep and s["status"] != "done" for s in steps)]
+    step.update(status="done", tree_after=tree)
+    journal.emit(root, state, "step_done", "%s: %d files changed" % (step["id"], len(diff or [])),
+         {"step_id": step["id"], "files": len(diff or []), "own": own, "others": others, "unready": unready},
+         legacy="step_completed", rt=rt)
+    # The first pending step whose dependencies are done — the first pending one
+    # when no step has `after`, as before the batch loop.
+    following = next((s for s in task.ready_steps(state) if s["status"] == "pending"), None)
+    if following:
+        following.update(status="in_progress", tree_before=tree)
+        journal.emit(root, state, "step_started", following["id"], {"step_id": following["id"], "kind": "step"}, rt=rt)
+    task.save(root, state)
+    report.write_task_md(root, state)
+    open_steps = [s["id"] for s in steps if s["status"] != "done"]
+    if unready:
+        print("note: %s was done before %s, which it is after" % (step["id"], ", ".join(unready)))
+    if others and rr_policy.batch_on(state):
+        print("note: the diff also holds %d file(s) outside this step's own — %s"
+              % (len(others), ", ".join(others[:4]) + (" …" if len(others) > 4 else "")))
+    print("step %s done%s" % (step["id"], "; next: %s" % following["id"] if following
+                              else "; %d still open: %s" % (len(open_steps), ", ".join(open_steps)) if open_steps
+                              else "; all steps done"))
+
+
+def cmd_steps(args, root, rt=rr_runtime.Runtime()):
+    """Read-only: the steps, their status and `after`; --ready prints the next
+    wave (R3), nothing when there is none."""
+    state = task.load_v7(root, rt=rt)
+    steps = state.get("steps") or []
+    ready = [s["id"] for s in task.ready_steps(state)]
+    if args.json:
+        print(json.dumps({"task_id": state["task_id"], "batch": rr_policy.batch_on(state), "ready": ready, "steps": steps,
+                          "batch_policy": rr_policy.batch_policy(rr_policy.weight_policy(root))}, indent=2, ensure_ascii=False))
+        return
+    if args.ready:
+        for step_id in ready:
+            print(step_id)
+        return
+    if not steps:
+        print("steps: one scope — no plan-file steps")
+        return
+    for s in steps:
+        print("%s · %s · after %s · %s" % (s["id"], s["status"], ", ".join(s.get("after") or []) or "-",
+                                            "ready" if s["id"] in ready else "waiting" if s["status"] != "done" else "-"))
+
+
+def cmd_batch(args, root, rt=rr_runtime.Runtime()):
+    """The batch loop's switch during a task (R9). `off` raises the rigor — the
+    standard budgets from here, counting what was spent — and is anyone's with
+    --by and --why. `on` lowers it, so it takes the human route or exits 5."""
+    state = task.load_v7(root, rt=rt)
+    want = args.action == "on"
+    if not args.by:
+        fs.die("batch %s needs --by \"<who>\"" % args.action)
+    if want == rr_policy.batch_on(state):
+        print("batch is already %s" % args.action)
+        return
+    via = None
+    if want:
+        via, why = dialog.human_route(root, rt=rt)
+        if via is None:
+            fs.die("APPROVAL_REFUSED — turning the batch loop on during a task lowers the rigor, so it is the "
+                "human's. In their own terminal:\n  python3 %s --root %s batch on --by \"<name>\"\nRefused "
+                "because %s." % (shlex.quote(fs.ENTRY), shlex.quote(root), why), 5)
+    elif not (args.why or "").strip():
+        fs.die("batch off needs --why \"<why the standard loop from here>\"")
+    policy = rr_policy.weight_policy(root)
+    if want:
+        rr_policy.batch_policy(policy, strict=True)          # a malformed section is refused before the loop starts
+    state["batch"] = {"on": want, "by": args.by, "why": args.why or None, "since": fs.now()}
+    if state.get("stage") in ("build", "verify", "review"):
+        # At the gate (stage ship) the next action is the human's and stays so.
+        state["next_action"] = rr_policy.review_next_action(state)
+    journal.emit(root, state, "batch_set", "%s by %s%s" % (args.action, args.by, " via %s" % via if via else ""),
+         {"on": want, "by": args.by, "why": args.why or None, "via": via,
+          "review_passes": state["review"]["passes"], "suite_runs": state["verify"]["suite_runs"]},
+         actor="human" if via == "terminal" else "agent", rt=rt)
+    handoff.set_resume_point(state, rt=rt)
+    handoff.write_handoff(root, state, "batch", rt=rt)
+    task.save(root, state)
+    report.write_task_md(root, state)
+    print("batch %s by %s · review %d/%d · suite %d/%d" % (
+        args.action, args.by, state["review"]["passes"], rr_policy.budget(policy, state, "review_rounds_max")[0],
+        state["verify"]["suite_runs"], rr_policy.budget(policy, state, "max_suite_runs")[0]))
+    print("next: %s" % state["next_action"])