riskrails 3.0.0 → 3.0.1

package/skills/ai-task/state.py

@@ -18,6 +18,8 @@ history[] keeps its exact shape and its original event names beside it.
 Usage:
   state.py start  --goal G --workflow W --files a,b [--tests t] [--declare axis=n:"why"]...
                   [--mode M --by WHO [--why TEXT]] [--steps "id:a,b:t;..." | --plan-file F.json]
+                  [--batch --by WHO | --no-batch]  the batch loop of /rr-build-all (weight.json batch.*);
+                                         a plan-file step may name "after": ["s1", ...]
   state.py start  --amend --files "+c,+d" --why TEXT     widen the task in place (R25)
   state.py verify --scope step|suite|e2e|all [--files a,b] [--expect fail]
                   [--e2e not-applicable WHY] [--after-fix WHAT] [--by WHO]
@@ -25,6 +27,9 @@ Usage:
                   --report -|FILE [--focus security] [--by WHO]  |  review --closes "H1,M2"
   state.py close  [--abandon]            two facts, the mode table, the gate, the archive
   state.py step-done <id>                a multi-step guarded or full task
+  state.py steps  [--ready] [--json]     the steps, their status and after; --ready prints the next wave
+  state.py batch  on|off --by WHO [--why TEXT]   off: the standard loop and budgets from here (anyone);
+                                         on: lowers the rigor — the human's, in their own terminal
   state.py status [--json]               what /rr-status prints
   state.py ask    "<question>" --option "A: text" [--option ...] [--recommend A] [--topic S]
   state.py ask    --batch FILE.json [--topic SLUG]
@@ -55,11 +60,13 @@ it; every other command refuses it.
 import argparse
 import base64
 import contextlib
+import copy
 import decimal
 import hashlib
 import importlib.util
 import json
 import os
+import posixpath
 import re
 import shlex
 import subprocess
@@ -98,6 +105,10 @@ EVENT_TYPES = [
     # R36 (7c): the dialog's decisions and the consent ledger, mirrored by state.py.
     "decision_opened", "consent_recorded", "consent_used", "consent_voided", "decision_declined",
     "decision_settled", "decision_fallback", "plan_drift",
+    # compact-project-memory §D9: a risk recorded with `memory risk`, compacted at close.
+    "risk_recorded",
+    # the batch loop (/rr-build-all): the switch, at start or during the task.
+    "batch_set",
 ]
 # The types `event` will not write: each is the record of an authorization or a
 # lifecycle decision, and is emitted by the transition that made it. `event` is
@@ -106,7 +117,7 @@ FORGEABLE_EVENTS = {"gate_requested", "gate_approved", "gate_rejected",
                     "task_started", "task_closed", "weight_set", "weight_raised", "mode_set",
                     "verify_run", "review_verdict", "decision_opened", "consent_recorded",
                     "consent_used", "consent_voided", "decision_declined", "decision_settled",
-                    "decision_fallback", "plan_drift"}
+                    "decision_fallback", "plan_drift", "risk_recorded", "batch_set"}
 
 # The questions are written by state.py and never by a model (R1). One regex
 # per line (I2), so a hand edit that keeps the shape round-trips exactly. A
@@ -155,14 +166,14 @@ ERROR_MAX = 1000
 RUNTIME = "unknown"
 # The commands that change the task. Only these take ownership of it: reading a
 # task from the other runtime, or writing a note about it, is not a handoff.
-MUTATING_COMMANDS = {"step-done", "ask", "answer", "close", "start", "verify", "review"}
+MUTATING_COMMANDS = {"step-done", "ask", "answer", "close", "start", "verify", "review", "batch"}
 # What prunes decision.json and mirrors consent.jsonl first (R36.14, R36.24):
 # every command that changes something; status and consent stay read-only.
 DIALOG_SYNC_COMMANDS = MUTATING_COMMANDS | {"approve", "reject", "decision"}
 # 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"}
+                 "review", "steps", "batch"}
 MUTATING = False
 
 
@@ -209,12 +220,12 @@ STATE_NAMES = ("state.json", "current.json")
 
 
 def state_path(root):
-    """The task's state file, read and written where it is: state.json when a
-    later version wrote one, else current.json, where every task starts. R34 is
-    expand/contract: this version reads both names and moves nothing, so a
-    revert of the move that comes later still finds the task."""
+    """The task's state file, read and written where it is: state.json, or
+    current.json when that is the file a task in flight sits in. A new task
+    starts in state.json (R34's contract half, migration 0009 moves an old one);
+    both names stay readable, so a revert of that move still finds the task."""
     new, legacy = (os.path.join(root, ".ai", "state", name) for name in STATE_NAMES)
-    return new if os.path.exists(new) else legacy
+    return legacy if not os.path.exists(new) and os.path.exists(legacy) else new
 
 
 def remove_state(root):
@@ -331,7 +342,7 @@ def read_journal(root, task_id):
 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
-    current.json directly — update.py does — sees the file, not these."""
+    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 ""
@@ -443,13 +454,40 @@ def emit(root, state, event, detail="", data=None, legacy=None, actor="agent"):
         state.get("task_id"), event, actor, state.get("current_stage"), detail, data))
 
 
-def next_task_id(root):
-    day = datetime.now(timezone.utc).strftime("%Y-%m-%d")
-    reports = os.path.join(root, ".ai", "reports")
-    existing = []
-    if os.path.isdir(reports):
-        existing = [n for n in os.listdir(reports) if n.startswith("T-%s-" % day)]
-    return "T-%s-%03d" % (day, len(existing) + 1)
+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):
+                        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
+    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
 
 
 # ------------------------------------------------------------------ plan profile (WP5)
@@ -542,7 +580,7 @@ def advise(state):
 
 def cmd_profile(args, _root):
     if args.action == "detect":
-        cmd_profile_detect(args)
+        cmd_profile_detect(args, find_root_quiet(args.root))
         return
     if args.action == "set":
         cmd_profile_set(args)
@@ -717,9 +755,16 @@ def detect_codex():
 SAME_TIER = {"claude": ({"max", "max20"}, {"pro", "team-pro"}, {"max", "team-max"}), "codex": ()}
 
 
-def installer_command(runtime, plan, version):
-    return "npx riskrails%s --target %s %s %s --yes" % (
-        "@%s" % version if version else "", runtime, "--plan" if runtime == "claude" else "--codex-plan", plan)
+def context_mode(prof):
+    """The record's --context: "economy" or None (default, or a record from before it)."""
+    context = (prof or {}).get("context")
+    return "economy" if isinstance(context, dict) and context.get("mode") == "economy" else None
+
+
+def installer_command(runtime, plan, version, context=None):
+    return "npx riskrails%s --target %s %s %s%s --yes" % (
+        "@%s" % version if version else "", runtime, "--plan" if runtime == "claude" else "--codex-plan", plan,
+        " --context %s" % context if context else "")
 
 
 def profile_detect(runtime):
@@ -738,6 +783,8 @@ def profile_detect(runtime):
         status = "no_profile"
     elif have == live["plan"] or (runtime == "claude" and have == "balanced-max" and live["plan"] in ("max", "max20")):
         status = "same"
+    elif acknowledged(runtime, live["fingerprint"], have):
+        status = "acknowledged"           # the human kept this very plan for this very account (R36.18)
     else:
         status = "drift"
         if any({have, live["plan"]} <= pair for pair in SAME_TIER[runtime]):
@@ -746,18 +793,95 @@ def profile_detect(runtime):
                 shlex.quote(os.path.abspath(__file__)), live["plan"], runtime)
         else:
             render = "installer"
-            command = installer_command(runtime, live["plan"], installed.get("plugin_version"))
+            command = installer_command(runtime, live["plan"], installed.get("plugin_version"),
+                                        context_mode(prof))
     return {"runtime": runtime, "status": status, "installed": installed, "live": live,
             "render": render, "command": command, "decision": None}
 
 
-def cmd_profile_detect(args):
-    """Read-only, exit 0 always (R36.16); `--open` belongs to 7c."""
-    if args.open:
-        die("--open opens the plan_drift decision (task 7e)", 1)
+def acknowledged(runtime, fingerprint, installed_plan):
+    """True when drift-ack.json holds this fingerprint AND the plan kept is the installed one."""
+    entry = read_drift_ack(runtime).get(runtime)
+    return isinstance(entry, dict) and entry.get("fingerprint") == fingerprint and \
+        entry.get("kept") == installed_plan
+
+
+def drift_ack_path(runtime):
+    return os.path.join(runtime_home(runtime), "riskrails", "drift-ack.json")
+
+
+def read_drift_ack(runtime):
+    """<home>/riskrails/drift-ack.json, or {}: per user, never per project (D2)."""
+    return read_json_object(drift_ack_path(runtime)) or {}
+
+
+def write_drift_ack(runtime, fingerprint, kept, via):
+    """"Keep" on a plan_drift decision: the fingerprint, the plan kept and when. Plan
+    fields hashed, never an email, an id or a token (R36.16). Atomic."""
+    data = read_drift_ack(runtime)
+    data = {"version": 1, "claude": data.get("claude"), "codex": data.get("codex")}
+    data[runtime] = {"fingerprint": fingerprint, "kept": kept, "at": now(), "via": via}
+    path = drift_ack_path(runtime)
+    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(data, fh, indent=2)
+        fh.write("\n")
+    os.replace(tmp, path)
+
+
+def open_drift(root, found):
+    """`profile detect --open` (R36.18): on drift, with the dialog on, the plan_drift
+    decision — option 1 keeps the installed plan (and writes drift-ack.json when
+    settled), option 2 is the `command` detect prints. The id of the decision, an
+    open one for the same fingerprint included; None when nothing was opened."""
+    runtime = found["runtime"]
+    if not root or runtime != own_runtime():
+        return None
+    fingerprint = found["live"]["fingerprint"]
+    on = dialog_on(root) if found["status"] == "drift" else None
+    session = (on or {}).get("session")
+    reuse = None
+    for decision in read_decisions(root)["open"]:
+        drift = decision.get("drift") or {}
+        if decision.get("kind") != "plan_drift" or drift.get("runtime") != runtime:
+            continue
+        if on and reuse is None and drift.get("fingerprint") == fingerprint and \
+                decision.get("session") == session:
+            reuse = decision["id"]
+        else:
+            # resolved, acknowledged elsewhere, another account or another session's: stale
+            settle_decision(root, decision["id"], "fallback")
+    if not on:
+        return None
+    if reuse:
+        return reuse
+    kept = found["installed"]["plan"]
+    live = found["live"]
+    question = "This %s account is %s (%s); RiskRails is installed for %s.\nKeep %s, or run the command below?" % (
+        runtime, live["plan"], live["from"] or "no detail", kept, kept)
+    state = load(root, required=False, claim=False)
+    state = state if state and is_v7(state) else None
+    options = [{"kind": "choice", "effect": "ack", "label": "Keep %s — do not ask again for this account" % kept},
+               {"kind": "command", "label": found["command"]}]
+    decision, why = open_decision(root, state, "plan_drift", "Plan drift", question, options, "profile detect",
+                                  drift={"runtime": runtime, "fingerprint": fingerprint, "kept": kept})
+    if decision is None:
+        print("state.py: no dialog — %s" % why, file=sys.stderr)
+        return None
+    return decision["id"]
+
+
+def cmd_profile_detect(args, root):
+    """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:
         die("--field, --tier, --other and a plan belong to the profile reader or profile set, not to profile detect")
     found = profile_detect(args.detect_runtime or own_runtime())
+    if args.open:
+        try:
+            found["decision"] = open_drift(root, found)
+        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
@@ -767,6 +891,8 @@ def cmd_profile_detect(args):
         have, live["plan"] or "unknown", " (%s)" % live["from"] if live["from"] else "", found["status"]))
     if found["command"]:
         print("fix: %s" % found["command"])
+    if found["decision"]:
+        print("decision: %s" % found["decision"])
 
 # plan -> (profile, label), as bin/riskrails.js maps --plan and --codex-plan; the
 # installer and `profile set` must resolve a plan to the same profile.json.
@@ -814,7 +940,7 @@ def cmd_profile_set(args):
         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",
-        installer_command(runtime, args.plan, prof.get("plugin_version")))
+        installer_command(runtime, args.plan, prof.get("plugin_version"), context_mode(prof)))
     if have not in plans or not any({have, args.plan} <= pair for pair in SAME_TIER[runtime]):
         die(refusal, 6)
     resolver, src = load_resolver(runtime)
@@ -822,9 +948,12 @@ def cmd_profile_set(args):
         die("no resolve-profile.py under %s/riskrails/scripts or the plugin; npx riskrails installs it"
             % 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 context_mode(prof) else {}
     try:
-        old = resolver.resolve(src, plans[have][0], have, plans[have][1], fable)
-        new = resolver.resolve(src, plans[args.plan][0], args.plan, plans[args.plan][1], fable)
+        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:
         die("cannot resolve the %s profile: %s" % (args.plan, exc))
     key = resolver.KEY
@@ -890,13 +1019,16 @@ def cmd_weight(args, root):
                 % item)
         declared[m.group(1)] = (int(m.group(2)), m.group(3).strip())
     try:
-        result = weight.compute(root, files, declared, args.goal, policy=policy)
+        result = weigh(root, files, declared, args.goal, policy)
     except ValueError as exc:
         die(str(exc))
     except (TypeError, AttributeError) as exc:     # a table whose values have the wrong shape
         die("%s is malformed: %s" % (path, exc))
     if args.json:
-        print(json.dumps(dict(result.as_dict(), policy=path), indent=2, ensure_ascii=False))
+        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))
 
@@ -967,7 +1099,7 @@ def _split_files(text):
 
 def cmd_event(args, root):
     """For hooks and for WP5's model fallback: one journal line, no state write.
-    current.json keeps its two writers; this command is not one of them."""
+    The state file keeps its two writers; this command is not one of them."""
     if args.type not in EVENT_TYPES:
         die("unknown event type '%s' (have: %s)" % (args.type, ", ".join(EVENT_TYPES)))
     if args.type in FORGEABLE_EVENTS:
@@ -1702,6 +1834,15 @@ def handoff_lines(root, state, reason):
     pending = [q["id"] for q in parse_questions(path)[1] if is_pending(q)]
     out.append("Pending questions: %s" % (
         "%s — %s" % (", ".join(pending), os.path.relpath(path, root)) if pending else "none"))
+    if batch_on(state):
+        try:
+            policy = weight.load_policy(root)[0] if weight else {}
+        except (OSError, ValueError):
+            policy = {}                       # best effort: the handoff never fails a command
+        out.append("Batch: on · ready %s · review %d/%d · suite %d/%d" % (
+            ", ".join(one_line(s["id"], 40) for s in ready_steps(state)) or "none",
+            (state.get("review") or {}).get("passes", 0), budget(policy, state, "review_rounds_max")[0],
+            (state.get("verify") or {}).get("suite_runs", 0), budget(policy, state, "max_suite_runs")[0]))
 
     notes = recent_notes(root, state)
     for kind, heading in (("decision", "Decisions"), ("rejected", "Rejected"),
@@ -1749,7 +1890,7 @@ def write_handoff(root, state, reason):
     nothing validates.
 
     It mutates `state` in memory only. The caller that is already changing the
-    task persists it; `handoff` on its own never writes current.json, because
+    task persists it; `handoff` on its own never writes the state file, because
     the hook calls it while another command may be mid-write."""
     path = handoff_path(root)
     try:
@@ -1826,7 +1967,7 @@ def handoff_to(args, root):
     emit(root, state, "runtime_handoff", "%s -> %s (%s)" % (source, args.to, via), data)
     write_handoff(root, state, "manual")
     save(root, state)
-    print("Handed %s to %s (%s). In %s, run /ai-task: it resumes from .ai/state/current.json."
+    print("Handed %s to %s (%s). In %s, run /ai-task: it resumes from the state file in .ai/state/."
           % (state.get("task_id"), args.to, via, args.to))
     print("headless (not run): cd %s && %s" % (shlex.quote(root), RESUME_COMMAND[args.to]))
 
@@ -2170,7 +2311,7 @@ INTERPRETER_RE = re.compile(r"^python3?$")   # a bare name: a path could be any
 PUSH_REF_RE = re.compile(r"^[A-Za-z0-9._/-]+$")  # no '+' (a force push), no ':' (a refspec), no option
 INTERPRETER_FLAG_RE = re.compile(r"^-[IS]+$")
 NPX_PACKAGE_RE = re.compile(r"^riskrails@[0-9A-Za-z.+-]+$")
-SETTLE_EFFECT = {"defer": "defer", "keep": "ack", "answer": "answered"}
+SETTLE_EFFECT = {"defer": "defer", "keep": "ack", "ack": "ack", "answer": "answered"}
 DIALOG_PICK = None                        # the pick human_route() consumed in this process
 
 
@@ -2490,7 +2631,8 @@ def open_decision(root, state, kind, header, question, options, opened_by, multi
         return None, "CONSENT_LABEL_INVALID — two options carry the same label"
     decision = dict({
         "id": next_decision_id(data, read_ledger(root)), "kind": kind, "task": (state or {}).get("task_id"),
-        "runtime": own_runtime(), "tree": current_tree(root), "opened_at": now(), "opened_by": opened_by,
+        "runtime": own_runtime(), "session": (dialog_on(root) or {}).get("session"),
+        "tree": current_tree(root), "opened_at": now(), "opened_by": opened_by,
         "header": one_line(header, HEADER_MAX), "multi_select": bool(multi),
         "question": (question or "").strip()[:QUESTION_MAX],
         "options": [dict(option, n=n) for n, option in enumerate(options, 1)],
@@ -2564,7 +2706,8 @@ def settle_decision(root, decision_id, effect, pick=None):
 
 def prune_decisions(root):
     """On every run: a decision with a settle line, or whose latest round's
-    command picks are all used, leaves decision.json (R36.14)."""
+    command picks are all used, leaves decision.json (R36.14); with the
+    project's dialog switch off, every open one falls back (R36.15)."""
     try:
         with open(decision_path(root), encoding="utf-8") as fh:
             data = json.load(fh)
@@ -2575,11 +2718,17 @@ def prune_decisions(root):
     settled = {e.get("decision") for e in ledger if e["type"] == "settle"}
     used = {e.get("id") for e in ledger if e["type"] == "use"}
     rounds = latest_rounds(ledger)
+    off = dialog_policy(root) is None
     for decision in list(keep):
         commands = {o.get("n") for o in decision.get("options") or [] if o.get("kind") == "command"}
         picks = [e for e in rounds.get(decision.get("id"), []) if e.get("option") in commands]
         if decision.get("id") in settled:
             keep.remove(decision)
+        elif off:
+            with contextlib.suppress(OSError), ledger_lock(root):
+                ledger_append(root, {"type": "settle", "decision": decision["id"], "pick": None,
+                                     "effect": "fallback"})
+            keep.remove(decision)
         elif picks and all(p.get("id") in used for p in picks):
             parsed = label_argv(picks[-1].get("label") or "")
             effect = "declined" if parsed and subcommand(parsed[1])[:1] == ["reject"] else "approved"
@@ -2727,7 +2876,11 @@ def cmd_decision(args, root):
         return
     data = read_decisions(root)
     if args.action == "show":
-        chosen = [d for d in data["open"] if not args.id or d["id"] == args.id]
+        # A session sees the decisions it opened (and those that name none):
+        # the hooks' gate and Stop reminder hold only the opener to them.
+        session = os.environ.get(SESSION_ENV.get(own_runtime(), ""))
+        chosen = [d for d in data["open"] if (not args.id or d["id"] == args.id) and (
+            not session or (d.get("session") in (None, "", session) and d.get("runtime") in (None, "", own_runtime())))]
         if not chosen:
             die("no open decision%s" % (" " + args.id if args.id else ""))
         if args.json:
@@ -2823,6 +2976,9 @@ def decision_settle(args, root, decision):
 
 def apply_choice(root, decision, option, pick_id, by, via):
     effect = SETTLE_EFFECT.get(option.get("effect"), "defer")
+    drift = decision.get("drift") or {}
+    if decision.get("kind") == "plan_drift" and effect == "ack" and drift.get("fingerprint"):
+        write_drift_ack(drift.get("runtime") or own_runtime(), drift["fingerprint"], drift.get("kept"), via)
     if effect == "answered":
         cmd_answer(argparse.Namespace(topic=None, prose=None, by=by, via=via,
                                       assignment=["%s=%s" % (decision.get("question_id"), option["answer"])]),
@@ -2919,6 +3075,11 @@ def apply_defaults_v7(state):
                          ("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", [])):
@@ -2978,6 +3139,60 @@ def mode_setting(policy, mode, key, default=None):
     return default
 
 
+# The batch loop of /rr-build-all: one task for a whole plan, its own budgets.
+BATCH_DEFAULTS = {"default": False, "review_rounds_max": 3, "max_suite_runs": 8, "parallel": 3, "tier": "BALANCED"}
+
+
+BATCH_TIERS = ["FAST", "BALANCED", "STRONG", "EXPERT"]
+
+
+def batch_policy(policy, strict=False):
+    """weight.json's batch section with every key filled in and checked. A table
+    from before the section runs with the shipped numbers (R13). A bad value is
+    refused where the task starts or the loop is switched (strict); a reader —
+    status, the handoff — falls back to the shipped value and never crashes."""
+    section = policy.get("batch") if isinstance(policy.get("batch"), dict) else {}
+    out, problems = dict(BATCH_DEFAULTS), []
+    for key, value in section.items():
+        if key not in BATCH_DEFAULTS:
+            continue
+        if key == "default":
+            if isinstance(value, bool):
+                out[key] = value
+            else:
+                problems.append("batch.default must be true or false, not %r" % (value,))
+        elif key == "tier":
+            if isinstance(value, str) and value.upper() in BATCH_TIERS:
+                out[key] = value.upper()
+            else:
+                problems.append("batch.tier must be one of %s, not %r" % ("/".join(BATCH_TIERS), value))
+        elif isinstance(value, bool) or not isinstance(value, int) or value < 1:
+            problems.append("batch.%s must be a whole number of at least 1, not %r" % (key, value))
+        else:
+            out[key] = value
+    if out["parallel"] >= 3 and out["tier"] not in ("FAST", "BALANCED"):
+        problems.append("batch.tier %s with batch.parallel %d: three or more parallel agents run at FAST or "
+                        "BALANCED (model-routing.md, Fan-out)" % (out["tier"], out["parallel"]))
+    if problems and strict:
+        die("weight.json: " + "; ".join(problems))
+    return out
+
+
+def batch_on(state):
+    return bool((state.get("batch") or {}).get("on"))
+
+
+def budget(policy, state, key):
+    """(limit, the table key the refusal names) for review_rounds_max or
+    max_suite_runs: the batch section's while the batch loop is on, else the
+    standard one — a task switched off mid-way keeps what it already spent."""
+    if batch_on(state):
+        return int(batch_policy(policy)[key]), "batch.%s" % key
+    if key == "max_suite_runs":
+        return int((policy.get("tests") or {}).get(key, 2)), "tests.max_suite_runs"
+    return int(policy.get(key, 2)), key
+
+
 def read_text(root, rel):
     try:
         with open(os.path.join(root, rel), "rb") as fh:
@@ -3108,7 +3323,8 @@ def task_md_path(root, state):
 
 
 def parse_steps(text, plan_file):
-    """--steps "id:a,b:t;id2:c" or --plan-file F.json ([{id, files, tests}])."""
+    """--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:
@@ -3117,24 +3333,91 @@ def parse_steps(text, plan_file):
         except (OSError, ValueError) as exc:
             die("--plan-file %s: %s" % (plan_file, exc))
         if not isinstance(raw, list) or not all(isinstance(s, dict) for s in raw):
-            die("--plan-file holds a JSON list of {\"id\", \"files\", \"tests\"}")
-        raw = [(str(s.get("id") or ""), ",".join(s.get("files") or []), ",".join(s.get("tests") or []))
-               for s in raw]
+            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):
+                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 []),
+                [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 ""))
+        raw.append((parts[0], parts[1] if len(parts) > 1 else "", parts[2] if len(parts) > 2 else "", []))
     steps = []
-    for step_id, files, tests in raw:
+    for step_id, files, tests, after in raw:
         step_id = one_line(step_id, 40)
         if not step_id or not _split_files(files):
             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]:
             die("step id %s appears twice" % step_id)
         steps.append({"id": step_id, "files": _split_files(files), "tests": _split_files(tests),
-                      "status": "pending", "tree_before": None, "tree_after": None})
+                      "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"]:
+                die("step %s lists itself in after" % step["id"])
+            if dep not in ids:
+                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]
+            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 parse_declares(items):
     declared = {}
     for item in items or []:
@@ -3147,6 +3430,10 @@ def parse_declares(items):
 
 
 def next_action_for(state):
+    if batch_on(state):
+        return ("batch loop: 'steps --ready' → implementers, step-done each; 'verify --scope all', red fixed "
+                "as one batch; review, findings fixed as one batch; again until it passes; the pass past the "
+                "batch budget is the human's")
     return {
         "light": "edit, then 'state.py verify --scope all', then 'state.py close'",
         "guarded": "edit, 'state.py verify --scope all', one review ('state.py review'), then 'state.py close'",
@@ -3180,9 +3467,23 @@ def cmd_start(args, root):
         die("start needs a git repository: the two facts close decides by are measured on its tree")
     steps = parse_steps(args.steps, args.plan_file)
     policy = weight_policy(root)
+    table = batch_policy(policy, strict=True)      # a malformed section is refused here, not at status
+    if args.batch and args.no_batch:
+        die("--batch and --no-batch exclude each other")
+    if args.batch and not args.by:
+        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": now()}
+    elif not args.no_batch and table["default"]:
+        batch = {"on": True, "by": "weight.json batch.default", "why": None, "since": 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 = order_shared_files(steps) if batch["on"] else []
+    check_steps(steps, implied)
     concrete = [f for f in files if not any(c in f for c in "*?[")]
     try:
-        result = weight.compute(root, concrete, parse_declares(args.declare), args.goal, policy=policy)
+        result = weigh(root, concrete, parse_declares(args.declare), args.goal, policy)
     except ValueError as exc:
         die(str(exc))
     except (TypeError, AttributeError) as exc:
@@ -3211,24 +3512,33 @@ def cmd_start(args, root):
                        args.mode, shlex.quote(args.by), why), 5)
         override = {"from": mode, "to": args.mode, "by": args.by, "why": args.why, "ts": now()}
         mode = args.mode
-    task_id = valid_task_id(args.task_id) if args.task_id else next_task_id(root)
+    if args.slug is not None:
+        import memory_format              # pylint: disable=import-outside-toplevel
+        if args.task_id:
+            die("--slug and --task-id both name the id: pass one", 2)
+        if not memory_format.SLUG_RE.match(args.slug):
+            die("--slug takes 3-24 characters of [a-z0-9] words joined by '-', not %r" % args.slug, 2)
+    task_id = valid_task_id(args.task_id) if args.task_id else next_task_id(root, args.goal, args.slug)
     base_tree = current_tree(root)
     state = {
         "schema": 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=now(), rescores=[], operations=[]),
         "mode_override": override, "stage": "build", "files": files, "tests": tests,
-        "steps": steps, "amendments": [], "findings": [],
+        "steps": steps, "amendments": [], "findings": [], "batch": batch,
         "diff": {"base_tree": base_tree, "base_commit": safe_sensor(sensors.head_commit, root)},
         "gate": None, "owner_runtime": RUNTIME if RUNTIME in RUNTIMES else None,
         "created": now(), "created_at": now(), "history": [],
     }
+    if result.documents_only is not None:
+        state["weight"]["documents_only"] = result.documents_only
     if os.path.exists(ledger_path(root)):
         # The ledger is per project: a task mirrors only the lines after its start.
         state["dialog"] = {"ledger_pos": os.path.getsize(ledger_path(root))}
     apply_defaults_v7(state)
     if steps:
-        steps[0].update(status="in_progress", tree_before=base_tree)
+        # The first step whose dependencies are done — steps[0] in a plan without `after`.
+        next(iter(ready_steps(state)), steps[0]).update(status="in_progress", tree_before=base_tree)
     arm_scope(state)
     state["next_action"] = next_action_for(state)
     emit(root, state, "task_started", one_line(args.goal, 200),
@@ -3243,6 +3553,9 @@ def cmd_start(args, root):
              actor="human" if MODES.index(mode) < MODES.index(override["from"]) else "agent")
     emit(root, state, "tier_set", "%s (mode %s, compat)" % (MODE_TIER[mode], mode),
          {"tier": MODE_TIER[mode], "mode": mode, "w": result.w})
+    if batch["on"]:
+        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})
     set_resume_point(state)
     write_handoff(root, state, "start")
     save(root, state)
@@ -3250,6 +3563,11 @@ def cmd_start(args, root):
     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)"
@@ -3291,6 +3609,18 @@ def rescore_v7(root, state, policy, at):
         return
     current = state["weight"].get("axes") or {}
     got = rescore_weight(root, state["diff"].get("base_tree"), [d["path"] for d in diff], current, policy)
+    # The documents rule (faster-task-cycle (c)): the axes it zeroed come back, upward, once the
+    # diff holds a path that is neither a document nor a test — `start --amend` does not re-weigh.
+    zeroed = (state["weight"].get("documents_only") or {}).get("zeroed") or {}
+    tests = ((policy.get("axes") or {}).get("coverage") or {}).get("test_globs")
+    outside = next((d["path"] for d in diff if not is_document(d["path"], policy)
+                    and not weight.match(d["path"], tests)), None)
+    if outside:
+        for axis, value in zeroed.items():
+            if int(got["axes"].get(axis) or 0) < int(value):
+                got["raised"].append({"axis": axis, "from": int(got["axes"].get(axis) or 0), "to": int(value),
+                                      "evidence": "a non-document changed (%s)" % outside})
+                got["axes"][axis] = int(value)
     before = state["mode"]
     ops = sorted(set(state["weight"].get("operations") or []) | set(got["operations"]))
     # Only what the diff moved can move the mode: an unchanged measurement must
@@ -3327,6 +3657,86 @@ def suite_green(state):
     return any(full_suite(r) and r.get("exit") == 0 for r in state["verify"]["runs"])
 
 
+# Never a document, whatever weight.json's `documents` says: the policies and the per-directory rules bind the agents.
+NEVER_DOCUMENTS = (".ai/policies/**", ".ai/rules/**")
+
+
+def is_document(path, policy):
+    """The one definition of a document (faster-task-cycle D4): `documents.globs`, minus
+    `documents.except`, NEVER_DOCUMENTS, code and tests; no `documents` key, no document."""
+    docs = policy.get("documents") or {}
+    cov = (policy.get("axes") or {}).get("coverage") or {}
+    return bool(weight.match(path, docs.get("globs"))
+                and not any(weight.match(path, pats) for pats in (
+                    docs.get("except"), NEVER_DOCUMENTS, cov.get("code_globs"), cov.get("test_globs"))))
+
+
+DOCUMENTS_ZEROED = ("behaviour", "domain", "novelty")
+
+
+def weigh(root, files, declared, goal, policy):
+    """weight.compute, plus the documents rule (faster-task-cycle (c), in state.py because
+    weight.py is at its line cap). Predicate P: at least one concrete file, every file a
+    document (is_document) or a test, at least one a document. When P holds, file text no
+    longer scores behaviour (the goal's keyword still does, exactly as in compute), and
+    behaviour, domain and novelty still UNKNOWN become 0 with the evidence "documents only"; hints and
+    declarations were applied inside compute. `documents_only` is {"zeroed": {axis: what it
+    would have scored}}, None when P does not hold or the policy has no `documents` key."""
+    concrete = [posixpath.normpath(f.strip().replace(os.sep, "/")) for f in files if f.strip()]
+    tests = ((policy.get("axes") or {}).get("coverage") or {}).get("test_globs")
+    inside = all(not f.startswith(("/", "../")) and f != ".." for f in concrete)
+    if not (inside and any(is_document(f, policy) for f in concrete)
+            and all(is_document(f, policy) or weight.match(f, tests) for f in concrete)):
+        result = weight.compute(root, files, declared, goal, policy=policy)
+        result.documents_only = None
+        return result
+    scored = copy.deepcopy(policy)
+    keywords = list(((policy.get("axes") or {}).get("behaviour") or {}).get("keywords") or [])
+    if not (goal and any(re.search(r"\b%s\b" % re.escape(k), goal, re.I) for k in keywords)):
+        # No goal keyword: file text must not score. With one, compute reads the goal first
+        # (value 1 whatever the files hold), so keeping the list scores exactly as plain compute does.
+        scored["axes"]["behaviour"] = dict(scored["axes"].get("behaviour") or {}, keywords=[])
+    result = weight.compute(root, files, declared, goal, policy=scored)
+    zeroed = {}
+    for axis in DOCUMENTS_ZEROED:
+        if axis not in result.unknown:
+            continue
+        if result.axes[axis] != 0:
+            zeroed[axis] = result.axes[axis]
+        result.axes[axis], result.evidence[axis] = 0, "documents only"
+        result.unknown.remove(axis)
+    result.w = sum(result.axes.values())
+    result.mode = mode_for(result.axes, policy)
+    result.documents_only = {"zeroed": zeroed}
+    return result
+
+
+def documents_cover(root, state, policy, tree):
+    """Fact (a) through the documents rule (faster-task-cycle D1-D5): (ok, why, facts).
+    why is "" when the rule is off or does not apply: today's refusal text stands."""
+    off = (False, "", None)
+    tests = (safe_sensor(sensors.read_commands, root) or {}).get("doc_tests", "").split()
+    if not (policy.get("documents") or {}).get("globs") or not tests or tests == ["none"]:
+        return off                                                              # D1
+    runs = [r for r in state["verify"]["runs"] if full_suite(r) and r.get("exit") is not None and r.get("tree")]
+    g = runs[-1] if runs else None
+    if not g or g["exit"] != 0 or any(r["tree"] == g["tree"] and r["exit"] != 0 for r in runs):
+        return off                                                              # D2
+    diff = safe_sensor(sensors.diff_files, root, g["tree"], tree)
+    if not diff or not all(is_document(d["path"], policy) for d in diff):
+        return off                                                              # D3, D4
+    paths = [d["path"] for d in diff]
+    steps = [r for r in state["verify"]["runs"] if r.get("scope") == "step" and not r.get("expected_fail")
+             and r.get("tree") == tree]
+    s = steps[-1] if steps else None                                            # D5
+    if not (s and s["n"] > g["n"] and s.get("exit") == 0 and all(t in (s.get("files") or []) for t in tests)):
+        return (False, "only documents changed since run %d (%d files): 'verify --scope step --files \"%s\"'"
+                % (g["n"], len(paths), ",".join(tests)), None)
+    return (True, "documents only since run %d (%d files: %s); doc_tests green in run %d on %s"
+            % (g["n"], len(paths), ", ".join(paths[:5]) + (", …" if len(paths) > 5 else ""), s["n"], tree[:9]),
+            {"since_run": g["n"], "since_tree": g["tree"], "run": s["n"], "paths": paths[:20], "tests": tests})
+
+
 def run_v7(root, state, scope, args, tcfg):
     """One scope's command, to the end, logged under .ai/state/logs/; returns the run."""
     command = safe_sensor(sensors.command_for, root, scope) or ""
@@ -3446,19 +3856,20 @@ def cmd_verify(args, root):
         die("--files narrows one scope; --scope all runs the whole suite and e2e")
     if args.e2e and e2e_na_refusal(root, state):
         die(e2e_na_refusal(root, state))         # before the suite runs, not after (N3)
-    max_runs = int(tcfg.get("max_suite_runs", 2))
+    max_runs, budget_name = budget(policy, state, "max_suite_runs")
     if scope in ("suite", "all") and state["verify"]["suite_runs"] >= max_runs:
         if not args.by:
             offer_decision(root, state, "human_set", "Budget",
-                           "%s\nSUITE_BUDGET: %d suite runs; weight.json allows %d. Run it once more?"
-                           % (task_facts(root, state), state["verify"]["suite_runs"], max_runs),
+                           "%s\nSUITE_BUDGET: %d suite runs; weight.json allows %d%s. Run it once more?"
+                           % (task_facts(root, state), state["verify"]["suite_runs"], max_runs,
+                              " (%s)" % budget_name if batch_on(state) else ""),
                            [{"kind": "choice", "effect": "keep", "label": "Keep the budget — stop here"},
                             {"kind": "command",
                              "label": state_label(root, sys.argv[1:] + ["--by", human_name(root)])}], "verify")
-            die("SUITE_BUDGET — %d suite runs; weight.json allows %d (tests.max_suite_runs). Running it "
+            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, shlex.quote(os.path.abspath(__file__)),
+                % (state["verify"]["suite_runs"], max_runs, budget_name, shlex.quote(os.path.abspath(__file__)),
                    shlex.quote(root), scope), 6)
         via, why = human_route(root, allow_dialog=True)
         if via is None:
@@ -3555,6 +3966,20 @@ def verdict_matches_findings(verdict, text):
             % ", ".join(highs))
 
 
+def review_next_action(state):
+    """What follows the last verdict — also after `batch off`, which changes what
+    a blockers_open verdict asks for: a full pass in batch, a scoped re-review outside."""
+    status = state["review"].get("status")
+    if status == "blockers_open":
+        if batch_on(state):
+            return ("fix every BLOCKER and HIGH as one parallel batch, 'state.py verify --scope all "
+                    "--after-fix \"…\"', then a full review pass again")
+        return "fix the blockers, 'state.py verify --scope all --after-fix \"…\"', one scoped re-review"
+    if status in VERDICT_STATUS.values():
+        return "'state.py close'"
+    return next_action_for(state)
+
+
 def cmd_review(args, root):
     """One pass recorded; the pass past review_rounds_max is the human's (exit 6)."""
     state = load_v7(root)
@@ -3565,22 +3990,23 @@ def cmd_review(args, root):
         return
     if not args.verdict or not args.tier:
         die("review needs --verdict pass|pass_with_findings|blockers_open and --tier BALANCED|STRONG")
-    rounds = int(policy.get("review_rounds_max", 2))
+    rounds, budget_name = 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 []
             offer_decision(root, state, "human_set", "Review",
-                           "%s\nREVIEW_BUDGET: %d review passes; weight.json allows %d. The next verdict is yours."
-                           % (task_facts(root, state), review["passes"], rounds),
+                           "%s\nREVIEW_BUDGET: %d review passes; weight.json allows %d%s. The next verdict is yours."
+                           % (task_facts(root, state), review["passes"], rounds,
+                              " (%s)" % budget_name if batch_on(state) else ""),
                            [{"kind": "choice", "effect": "keep", "label": "Keep it open — no verdict now"}] +
                            [{"kind": "command",
                              "label": state_label(root, ["review", "--verdict", verdict, "--tier", args.tier] +
                                                   report + ["--by", human_name(root)])}
                             for verdict in ("pass", "pass_with_findings", "blockers_open")], "review")
-            die("REVIEW_BUDGET — %d review passes; weight.json allows %d (review_rounds_max). The next "
+            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,
+                "<verdict> --tier %s --by \"<name>\"" % (review["passes"], rounds, budget_name,
                                                          shlex.quote(os.path.abspath(__file__)),
                                                          shlex.quote(root), args.tier), 6)
         via, why = human_route(root, allow_dialog=True)
@@ -3613,8 +4039,7 @@ def cmd_review(args, root):
     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})
-    state["next_action"] = ("fix the blockers, 'state.py verify --scope all --after-fix \"…\"', one scoped "
-                            "re-review" if status == "blockers_open" else "'state.py close'")
+    state["next_action"] = review_next_action(state)
     write_handoff(root, state, "review")
     save(root, state)
     write_task_md(root, state)
@@ -3657,6 +4082,7 @@ def two_facts(root, state, tree):
     runs = [r for r in state["verify"]["runs"] if 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:
@@ -3664,6 +4090,9 @@ def two_facts(root, state, tree):
     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 = documents_cover(root, state, 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:
@@ -3696,7 +4125,7 @@ def two_facts(root, state, tree):
              + (" (+%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}
+    return {"a": a, "b": b, "diff": diff or [], "outside": outside, "documents": documents}
 
 
 def close_owed(state, facts, tree, policy):
@@ -3713,7 +4142,8 @@ def close_owed(state, facts, tree, policy):
                                    "'start --amend' for a file the task needs)" % "; ".join(red)))
         return owed
     if review["status"] == "blockers_open":
-        owed.append(("review", "the blockers fixed, 'verify --scope all --after-fix \"…\"', one scoped re-review"))
+        owed.append(("review", "the blockers fixed, 'verify --scope all --after-fix \"…\"', %s"
+                               % ("a full review pass again" if batch_on(state) else "one scoped re-review")))
     elif not reviewed:
         owed.append(("review", "one review verdict (%s mode: %s)"
                                % (mode, mode_setting(policy, mode, "reviewer", "BALANCED"))))
@@ -3780,6 +4210,7 @@ def cmd_close_v7(args, root):
     state = load_v7(root)
     if args.abandon:
         archive_v7(root, state, current_tree(root), "abandoned")
+        memory_after_close(root, state["task_id"])
         return
     policy = weight_policy(root)
     tree = current_tree(root)
@@ -3799,6 +4230,8 @@ def cmd_close_v7(args, root):
     rescore_v7(root, state, policy, "close")
     facts = two_facts(root, state, tree)
     state["facts"] = {"a": list(facts["a"]), "b": list(facts["b"]), "tree": tree, "at": now()}
+    if facts["documents"]:
+        state["facts"]["documents"] = facts["documents"]
     owed = close_owed(state, facts, tree, policy)
     if owed:
         state["next_action"] = owed[0][1]
@@ -3842,6 +4275,7 @@ def cmd_close_v7(args, root):
         state["gate"].update(approved_by=approval.get("granted_by"), approved_at=approval.get("granted_at"),
                              via=approval.get("via"), approved_tree=state["gate"].get("tree"))
     archive_v7(root, state, tree, "closed", facts)
+    memory_after_close(root, state["task_id"])
 
 
 def archive_v7(root, state, tree, result, facts=None):
@@ -3895,16 +4329,98 @@ def cmd_step_done_v7(args, root):
         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)
     emit(root, state, "step_done", "%s: %d files changed" % (step["id"], len(diff or [])),
-         {"step_id": step["id"], "files": len(diff or [])}, legacy="step_completed")
-    following = next((s for s in steps if s["status"] == "pending"), None)
+         {"step_id": step["id"], "files": len(diff or []), "own": own, "others": others, "unready": unready},
+         legacy="step_completed")
+    # 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 ready_steps(state) if s["status"] == "pending"), None)
     if following:
         following.update(status="in_progress", tree_before=tree)
         emit(root, state, "step_started", following["id"], {"step_id": following["id"], "kind": "step"})
     save(root, state)
     write_task_md(root, state)
-    print("step %s done%s" % (step["id"], "; next: %s" % following["id"] if following else "; all steps done"))
+    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 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):
+    """Read-only: the steps, their status and `after`; --ready prints the next
+    wave (R3), nothing when there is none."""
+    state = load_v7(root)
+    steps = state.get("steps") or []
+    ready = [s["id"] for s in ready_steps(state)]
+    if args.json:
+        print(json.dumps({"task_id": state["task_id"], "batch": batch_on(state), "ready": ready, "steps": steps,
+                          "batch_policy": batch_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):
+    """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 = load_v7(root)
+    want = args.action == "on"
+    if not args.by:
+        die("batch %s needs --by \"<who>\"" % args.action)
+    if want == batch_on(state):
+        print("batch is already %s" % args.action)
+        return
+    via = None
+    if want:
+        via, why = human_route(root)
+        if via is None:
+            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(os.path.abspath(__file__)), shlex.quote(root), why), 5)
+    elif not (args.why or "").strip():
+        die("batch off needs --why \"<why the standard loop from here>\"")
+    policy = weight_policy(root)
+    if want:
+        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": 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"] = review_next_action(state)
+    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")
+    set_resume_point(state)
+    write_handoff(root, state, "batch")
+    save(root, state)
+    write_task_md(root, state)
+    print("batch %s by %s · review %d/%d · suite %d/%d" % (
+        args.action, args.by, state["review"]["passes"], budget(policy, state, "review_rounds_max")[0],
+        state["verify"]["suite_runs"], budget(policy, state, "max_suite_runs")[0]))
+    print("next: %s" % state["next_action"])
 
 
 def cmd_approve_v7(args, root):
@@ -3975,12 +4491,13 @@ def status_lines(root, state):
                                          + (" (+%d more)" % (len(task_files(state)) - 4)
                                             if len(task_files(state)) > 4 else "")),
             "verify: suite %s · runs %d/%s · e2e %s" % (ver["status"], ver["suite_runs"],
-                                                        (policy.get("tests") or {}).get("max_suite_runs", 2),
+                                                        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"],
-                                                   policy.get("review_rounds_max", 2), review.get("tier") or "-",
+                                                   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"]
@@ -3990,6 +4507,13 @@ def status_lines(root, state):
                           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 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" % (
+                one_line(state["batch"].get("by"), 40), review["passes"],
+                budget(policy, state, "review_rounds_max")[0], ver["suite_runs"],
+                budget(policy, state, "max_suite_runs")[0],
+                ", ".join(s["id"] for s in 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(one_line(last.get(k), 80) for k in ("ts", "event", "detail")
@@ -4053,11 +4577,16 @@ def task_md_lines(root, state):
                                                         " — %s" % one_line(override["why"])
                                                         if override.get("why") else ""))
     out += ["re-score %s" % one_line(line, 300) for line in w.get("rescores") or []]
+    if batch_on(state):
+        batch = state["batch"]
+        out.append("batch: on by %s at %s%s" % (one_line(batch.get("by"), 80), batch.get("since"),
+                                                " — %s" % 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" % (step["id"], ", ".join(step["files"]),
-                                            ", ".join(step["tests"]) or "no tests", step["status"]))
+        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"]), one_line(a["why"]))
             for a in state.get("amendments") or []]
     out += ["", QUESTIONS_SECTION, "", "none"]
@@ -4180,6 +4709,360 @@ def route_surface(root, args):
     die(old_surface_refusal(state))
 
 
+# ------------------------------------------------------------------ the compact record (compact-project-memory)
+def memory_modules():
+    """memory_sync and memory_store, imported only by the commands that use them."""
+    try:
+        import memory_store               # pylint: disable=import-outside-toplevel
+        import memory_sync                # pylint: disable=import-outside-toplevel
+    except ImportError as exc:
+        die("the memory modules are not installed beside state.py (%s)" % exc, 2)
+    return memory_sync, memory_store
+
+
+def memory_after_close(root, task_id):
+    """§D5: packages mode exports the closed task. Files mode (no memory.json)
+    imports nothing and prints nothing (R15)."""
+    if not os.path.exists(os.path.join(root, ".ai", "policies", "memory.json")):
+        return
+    try:
+        import memory_sync                # pylint: disable=import-outside-toplevel
+    except ImportError:
+        return
+    memory_sync.after_close(root, task_id)
+
+
+def memory_config(sync, root):
+    try:
+        return sync.load_config(root)
+    except sync.MemoryError_ as exc:
+        die(str(exc), exc.code)
+    return None
+
+
+def memory_human(root, what):
+    """R16: enable, disable, cleanup, pack, redact and move-logs take the human's route, as approve does."""
+    via, why = human_route(root)
+    if via is None:
+        die("APPROVAL_REFUSED — 'memory %s' is the human's, from their own terminal:\n  python3 %s --root %s "
+            "%s\nRefused because %s." % (what, shlex.quote(os.path.abspath(__file__)), shlex.quote(root),
+                                         " ".join(shlex.quote(a) for a in sys.argv[sys.argv.index("memory"):]
+                                                  if "memory" in sys.argv), why), 5)
+    return via
+
+
+def memory_confirm(cfg, name, what):
+    if not name:
+        die("'memory %s' deletes or moves files: add --confirm-delete %s" % (what, cfg.author), 2)
+    if name != cfg.author:
+        die("--confirm-delete names %r; this clone's author is %r (.ai/local/memory/config.json)"
+            % (name, cfg.author), 2)
+
+
+def in_flight(root):
+    state = load(root, required=False, claim=False)
+    return state if state and state.get("current_stage") != "done" and state.get("task_id") else None
+
+
+def cmd_recall(args, root):
+    """R10: the open risks, residual findings, decisions, scope changes and task
+    one-liners that touch these files, within the budget. Read-only."""
+    sync, store = memory_modules()
+    cfg = memory_config(sync, root)
+    files = _split_files(args.files)
+    if not files:
+        die("recall needs --files \"a,b,dir/**\"", 2)
+    kinds = _split_files(args.kinds) or None
+    history = store.open_history(root, cfg)
+    budget = args.budget if args.budget is not None else cfg.recall_budget
+    text, result = history.recall(files, budget, cfg.recall_max_items, kinds, args.all_risks, args.offset)
+    if args.json:
+        print(json.dumps({"schema": 1, "files": files, "budget": budget, "used": result["used"],
+                          "items": [{k: i[k] for k in ("rid", "kind", "task", "ts", "line", "src")}
+                                    for i in result["items"]],
+                          "more": result["more"], "next": result["next"], "source": history.source()},
+                         ensure_ascii=False, sort_keys=True))
+        return
+    sys.stdout.write(text)
+
+
+def cmd_memory(args, root):
+    sync, store = memory_modules()
+    action = args.memory_action
+    try:
+        MEMORY_ACTIONS[action](args, root, sync, store)
+    except sync.MemoryError_ as exc:
+        die(str(exc), exc.code)
+
+
+def memory_status(args, root, sync, _store):
+    lines = sync.status_lines(root)
+    if args.json:
+        print(json.dumps(dict(line.split(": ", 1) for line in lines), ensure_ascii=False, sort_keys=True))
+        return
+    print("\n".join(lines))
+
+
+def memory_enable(args, root, sync, _store):
+    memory_human(root, "enable")
+    hook = sync.enable(root, args.author, args.period, args.index)
+    print("memory: packages mode on (%s); every teammate's next close exports" % sync.POLICY_REL)
+    print("pre-push: %s" % hook)
+    if hook in ("foreign", "hookspath"):
+        print("not written — %s. Add these lines to your own pre-push hook:\n%s" % (
+            "core.hooksPath is set" if hook == "hookspath" else "a pre-push hook exists", sync.snippet_text()))
+    print("\n".join(sync.status_lines(root)))
+
+
+def memory_disable(_args, root, sync, _store):
+    memory_human(root, "disable")
+    print("memory: files mode; packages and local data kept; pre-push: %s" % sync.disable(root))
+
+
+def memory_export(args, root, sync, _store):
+    cfg = memory_config(sync, root)
+    ids = "pending" if args.pending or not args.ids else [valid_task_id(t, "ID") for t in args.ids]
+    result = sync.export(root, ids, cfg)
+    for line in sync.record_lines(result):
+        print(line)
+    print("exported: +%d entries%s" % (result.added, "" if result.added else " — nothing pending"))
+    for task_id, why in result.failures:
+        print("memory: export of %s failed (%s)" % (task_id, why))
+    if result.failures:
+        sys.exit(1)
+
+
+def memory_verify(args, root, sync, _store):
+    stats = None
+    if args.range:
+        if ".." not in args.range:
+            die("--range takes OLD..NEW", 2)
+        old, new = args.range.split("..", 1)
+        findings, stats = sync.validate_range(root, sync.rev(root, old), sync.rev(root, new) or new, local=False)
+        findings = findings or []
+    elif args.fresh_clone:
+        findings = sync.verify_fresh_clone(root)
+    else:
+        findings = sync.verify(root, "all", [valid_task_id(t, "ID") for t in args.ids] or None)
+    failing = [f for f in findings if not f.check.endswith("-warn")]
+    if args.json:
+        print(json.dumps({"findings": [f._asdict() for f in findings], "ok": not failing, "stats": stats},
+                         ensure_ascii=False, sort_keys=True))
+    else:
+        for f in findings:
+            print(sync.format_finding(f))
+        print("memory verify: %s" % ("ok" if not failing else "%d finding(s)" % len(failing)))
+    if failing:
+        sys.exit(1)
+
+
+def memory_show(args, root, sync, _store):
+    print("\n".join(sync.show(root, valid_task_id(args.id, "ID"), "json" if args.json else "md", args.entry)))
+
+
+def memory_search(args, root, sync, store):
+    cfg = memory_config(sync, root)
+    filters = {"kind": args.kind, "by": args.by, "task": args.task, "since": args.since, "until": args.until,
+               "files": _split_files(args.file) or None}
+    history = store.open_history(root, cfg)
+    hits, total = history.search(args.query or "", filters, args.limit, args.offset)
+    if args.json:
+        print(json.dumps({"schema": 1, "query": args.query or "", "total": total, "offset": args.offset,
+                          "items": [{"rid": e["rid"], "kind": e["kind"], "task": e.get("task"), "ts": e.get("ts"),
+                                     "line": store.mf.search_line(e)} for e in hits],
+                          "source": history.source()}, ensure_ascii=False, sort_keys=True))
+        return
+    print("# Search — \"%s\" · %d of %d matches · offset %d · index %s" % (
+        args.query or "", len(hits), total, args.offset, history.source()["index"]))
+    for e in hits:
+        print("- %s" % store.mf.search_line(e))
+    if args.offset + len(hits) < total:
+        print("… %d more: --offset %d" % (total - args.offset - len(hits), args.offset + len(hits)))
+
+
+def risk_scope(state):
+    """C4 (§D9): with a task in flight, files mode edits known-risks.md only
+    when the task names it."""
+    rel = ".ai/project/known-risks.md"
+    if state and not sensors.scope_any(rel, task_files(state)):
+        die("SCOPE_CHANGE_REQUIRED — 'memory risk' writes %s, which task %s does not name:\n"
+            "  state.py start --amend --files \"+%s\" --why \"<the risk you record>\"" % (rel, state["task_id"], rel),
+            6)
+
+
+def memory_risk(args, root, sync, store):
+    cfg = memory_config(sync, root)
+    state = in_flight(root)
+    if args.risk_action == "add":
+        where = _split_files(args.where)
+        if args.label not in store.mf.LABELS:
+            die("--label takes one of: %s" % ", ".join(store.mf.LABELS), 2)
+        if args.status not in store.mf.RISK_STATUS:
+            die("--status takes one of: %s" % ", ".join(store.mf.RISK_STATUS), 2)
+        if not cfg.packages:
+            risk_scope(state)
+            found = "%s, by %s" % (now()[:10], state["task_id"] if state else "no task")
+            rkey = sync.risk_add_files(root, args.title, where, args.label, args.what, args.likely, args.fix,
+                                       args.status, found)
+            print("risk: %s added to .ai/project/known-risks.md" % rkey)
+            return
+        data = sync.risk_data(args.title, where, args.label, args.what, args.likely, args.fix, args.status)
+    else:
+        if args.status not in ("fixed", "accepted", "ticketed"):
+            die("--status takes fixed, accepted or ticketed", 2)
+        if not cfg.packages:
+            risk_scope(state)
+            sync.risk_close_files(root, args.rkey, args.status, args.why)
+            print("risk: %s is %s" % (args.rkey, args.status))
+            return
+        history = store.FileHistory(root, cfg)
+        found = [e for e in history.risks("all") if e.get("rkey") == args.rkey]
+        if not found:
+            die("no risk %s ('state.py memory risks --status all')" % args.rkey, 1)
+        last = found[0]
+        data = sync.risk_data(last["title"], last.get("where"), last.get("label"), last.get("what"),
+                              last.get("likelihood"), last.get("fix"), args.status, args.why, last["rid"])
+    if state:
+        state = load(root)
+        emit(root, state, "risk_recorded", "%s: %s" % (data["rkey"], one_line(data["title"], 200)), data)
+        save(root, state)
+        print("risk: %s recorded in %s's journal (exported at close)" % (data["rkey"], state["task_id"]))
+        return
+    entry = sync.standalone_risk(root, cfg, data, RUNTIME)
+    print("risk: %s recorded (%s)" % (data["rkey"], entry["rid"]))
+
+
+def memory_risks(args, root, sync, store):
+    cfg = memory_config(sync, root)
+    risks = store.open_history(root, cfg).risks(args.status)
+    if args.json:
+        for e in risks:
+            print(store.mf.canonical(e).decode("utf-8"))
+        return
+    if args.md:
+        out = ["# Known risks", ""]
+        for e in risks:
+            out += (e["text"].split("\n") if e.get("text") else store.mc.risk_section(
+                e.get("title"), store.mf.where_list(e.get("where")), e.get("label"), e.get("what"),
+                e.get("likelihood"), e.get("fix"), "%s%s" % (e.get("status"), " — %s" % e["status_why"]
+                                                             if e.get("status_why") else ""),
+                e.get("found_by") or "-")) + [""]
+        print("\n".join(out).rstrip("\n"))
+        return
+    print("# Risks — %s · %d" % (args.status, len(risks)))
+    for e in risks:
+        where = store.mf.where_list(e.get("where"))
+        print("- [%s %s] %s — %s (%s)" % (e.get("status"), e.get("label"), where[0] if where else "-",
+                                          e.get("title"), e.get("rkey")))
+
+
+def memory_migrate(args, root, sync, _store):
+    cfg = memory_config(sync, root)
+    if args.move_logs:
+        memory_human(root, "migrate --move-logs")
+        memory_confirm(cfg, args.confirm_delete, "migrate --move-logs")
+        moved, command = sync.move_logs(root)
+        print("moved %d committed log(s) into .ai/state/logs/<id>/legacy/; now, as its own commit (C3):\n  %s"
+              % (len(moved), command))
+        return
+    if args.apply:
+        print("\n".join(sync.migrate_apply(root, risks=args.risks)))
+        return
+    report = sync.migrate_report(root)
+    print("report: %s (%d lines) — read it, then 'state.py memory migrate --apply'"
+          % (os.path.join(sync.LOCAL_REL, "migration-report.md"), report.count("\n")))
+
+
+def memory_rebuild(_args, root, sync, store):
+    cfg = memory_config(sync, root)
+    print("index: rebuilt from %d sources (%s)" % (store.SqliteHistory(root, cfg).rebuild(), store.INDEX_REL))
+
+
+def memory_cleanup(args, root, sync, _store):
+    cfg = memory_config(sync, root)
+    memory_human(root, "cleanup")
+    memory_confirm(cfg, args.confirm_delete, "cleanup")
+    if not args.all and not args.ids:
+        die("memory cleanup takes IDs or --all", 2)
+    print("\n".join(sync.cleanup(root, "all" if args.all else [valid_task_id(t, "ID") for t in args.ids])))
+
+
+def memory_restore(args, root, sync, _store):
+    if not args.all and not args.ids:
+        die("memory restore takes IDs or --all", 2)
+    print("\n".join(sync.restore(root, "all" if args.all else [valid_task_id(t, "ID") for t in args.ids])))
+
+
+def memory_pack(args, root, sync, _store):
+    cfg = memory_config(sync, root)
+    memory_human(root, "pack")
+    memory_confirm(cfg, args.confirm_delete, "pack")
+    target, removed, count = sync.pack(root, args.period)
+    print("pack: %s (%d records; %d batch(es) removed)" % (os.path.join(sync.MEMORY_REL, target), count,
+                                                          len(removed)))
+
+
+def memory_redact(args, root, sync, _store):
+    via = memory_human(root, "redact")
+    rid, name = sync.redact(root, args.rid, args.field, args.why, by="%s via %s" % (os.environ.get("USER") or
+                                                                                   "unknown", via))
+    print("redacted: %s in %s (new rid %s)" % (args.field, os.path.join(sync.MEMORY_REL, name), rid))
+
+
+MEMORY_ACTIONS = {"status": memory_status, "enable": memory_enable, "disable": memory_disable,
+                  "export": memory_export, "verify": memory_verify, "show": memory_show, "search": memory_search,
+                  "risk": memory_risk, "risks": memory_risks, "migrate": memory_migrate, "rebuild": memory_rebuild,
+                  "cleanup": memory_cleanup, "restore": memory_restore, "pack": memory_pack,
+                  "redact": memory_redact}
+
+
+def memory_parsers(sub):
+    p = sub.add_parser("recall", help="what the record holds about these files, within a token budget")
+    p.add_argument("--files", default=""); p.add_argument("--budget", type=int)
+    p.add_argument("--kinds", default=""); p.add_argument("--all-risks", dest="all_risks", action="store_true")
+    p.add_argument("--offset", type=int, default=0); p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_recall)
+    p = sub.add_parser("memory", help="the compact project record (docs/local-memory.md)")
+    p.set_defaults(func=cmd_memory)
+    msub = p.add_subparsers(dest="memory_action", required=True)
+    m = msub.add_parser("status"); m.add_argument("--json", action="store_true")
+    m = msub.add_parser("enable"); m.add_argument("--author"); m.add_argument("--period", choices=["month", "quarter", "year"])
+    m.add_argument("--index", choices=["none", "sqlite"])
+    msub.add_parser("disable")
+    m = msub.add_parser("export"); m.add_argument("ids", nargs="*"); m.add_argument("--pending", action="store_true")
+    m = msub.add_parser("verify"); m.add_argument("ids", nargs="*"); m.add_argument("--all", action="store_true")
+    m.add_argument("--range"); m.add_argument("--fresh-clone", dest="fresh_clone", action="store_true")
+    m.add_argument("--json", action="store_true")
+    m = msub.add_parser("show"); m.add_argument("id"); m.add_argument("--md", action="store_true")
+    m.add_argument("--json", action="store_true"); m.add_argument("--entry")
+    m = msub.add_parser("search"); m.add_argument("query", nargs="?", default="")
+    for flag in ("--kind", "--by", "--file", "--task", "--since", "--until"):
+        m.add_argument(flag)
+    m.add_argument("--limit", type=int, default=20); m.add_argument("--offset", type=int, default=0)
+    m.add_argument("--json", action="store_true")
+    m = msub.add_parser("risk"); rsub = m.add_subparsers(dest="risk_action", required=True)
+    r = rsub.add_parser("add"); r.add_argument("--title", required=True); r.add_argument("--where", default="")
+    r.add_argument("--label", required=True); r.add_argument("--what", required=True)
+    r.add_argument("--likely"); r.add_argument("--fix"); r.add_argument("--status", default="open")
+    r = rsub.add_parser("close"); r.add_argument("rkey"); r.add_argument("--status", required=True)
+    r.add_argument("--why", required=True)
+    m = msub.add_parser("risks"); m.add_argument("--status", choices=["open", "ticketed", "accepted", "fixed", "all"],
+                                                 default="open")
+    m.add_argument("--md", action="store_true"); m.add_argument("--json", action="store_true")
+    m = msub.add_parser("migrate"); g = m.add_mutually_exclusive_group(required=True)
+    g.add_argument("--report", action="store_true"); g.add_argument("--apply", action="store_true")
+    g.add_argument("--move-logs", dest="move_logs", action="store_true")
+    m.add_argument("--risks", action="store_true"); m.add_argument("--confirm-delete", dest="confirm_delete")
+    msub.add_parser("rebuild")
+    m = msub.add_parser("cleanup"); m.add_argument("ids", nargs="*"); m.add_argument("--all", action="store_true")
+    m.add_argument("--confirm-delete", dest="confirm_delete")
+    m = msub.add_parser("restore"); m.add_argument("ids", nargs="*"); m.add_argument("--all", action="store_true")
+    m = msub.add_parser("pack"); m.add_argument("--period", required=True)
+    m.add_argument("--confirm-delete", dest="confirm_delete")
+    m = msub.add_parser("redact"); m.add_argument("rid"); m.add_argument("--field", required=True)
+    m.add_argument("--why", required=True)
+
+
 def main():
     parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
     parser.add_argument("--root", default=".", help="project directory (default: search upwards for .ai/)")
@@ -4256,9 +5139,21 @@ def main():
     p.add_argument("--tests", default=""); p.add_argument("--declare", action="append", default=[])
     p.add_argument("--mode"); p.add_argument("--by", default=""); p.add_argument("--why", default="")
     p.add_argument("--steps", default=""); p.add_argument("--plan-file", dest="plan_file")
-    p.add_argument("--task-id"); p.add_argument("--amend", action="store_true")
+    p.add_argument("--task-id", help="an id of your own; a legacy T-YYYY-MM-DD-NNN id is still accepted")
+    p.add_argument("--slug", help="3-24 characters of [a-z0-9] words joined by '-': the id becomes "
+                                  "T-YYYY-MM-DD-HHMM-<slug> (UTC). Default: derived from --goal")
+    p.add_argument("--amend", action="store_true")
+    p.add_argument("--batch", action="store_true", help="the batch loop of /rr-build-all (needs --by)")
+    p.add_argument("--no-batch", dest="no_batch", action="store_true", help="opt out of weight.json batch.default")
     p.set_defaults(func=cmd_start)
 
+    p = sub.add_parser("steps"); p.add_argument("--ready", action="store_true")
+    p.add_argument("--json", action="store_true"); p.set_defaults(func=cmd_steps)
+
+    p = sub.add_parser("batch"); p.add_argument("action", choices=["on", "off"])
+    p.add_argument("--by", default=""); p.add_argument("--why", default="")
+    p.set_defaults(func=cmd_batch)
+
     p = sub.add_parser("verify")
     p.add_argument("--scope", required=True, choices=["step", "suite", "e2e", "all"])
     p.add_argument("--files", default=""); p.add_argument("--expect", choices=["fail"])
@@ -4282,6 +5177,8 @@ def main():
     p = sub.add_parser("consent"); p.add_argument("action", nargs="?", choices=["audit"])
     p.add_argument("--json", action="store_true"); p.set_defaults(func=cmd_consent)
 
+    memory_parsers(sub)
+
     global RUNTIME, MUTATING              # pylint: disable=global-statement
     args = parser.parse_args()
     if getattr(args, "topic", None):