riskrails 3.1.0 → 3.2.1

package/hooks/runtime-gate.py

@@ -138,7 +138,7 @@ def profile_tier(home, tier, field, default):
         with open(profile_file(home), encoding="utf-8") as fh:
             value = json.load(fh)["tiers"][tier][field]
         return value if isinstance(value, str) and value else default
-    except (OSError, ValueError, KeyError, TypeError):
+    except (OSError, ValueError, KeyError, TypeError, RecursionError):
         return default
 
 
@@ -148,7 +148,7 @@ def profile_fable(home):
     try:
         with open(profile_file(home), encoding="utf-8") as fh:
             return bool(json.load(fh).get("fable", True))
-    except (OSError, ValueError, AttributeError):
+    except (OSError, ValueError, AttributeError, RecursionError):
         return True
 
 
@@ -205,7 +205,7 @@ def load(path=None):
         return data if isinstance(data, dict) else {}
     except OSError:
         return import_legacy() if path in (None, STATE) else {}
-    except ValueError:
+    except (ValueError, RecursionError):
         return {}
 
 
@@ -218,7 +218,7 @@ def import_legacy():
     try:
         with open(LEGACY_STATE, encoding="utf-8") as fh:
             old = json.load(fh)
-    except (OSError, ValueError):
+    except (OSError, ValueError, RecursionError):
         return {}
     data = {"imported_from": os.path.basename(LEGACY_STATE)}
     if isinstance(old, dict) and isinstance(old.get("unavailable"), dict):
@@ -341,7 +341,7 @@ def claude_code_version(path):
             continue
         try:
             version = json.loads(line).get("version")
-        except (ValueError, AttributeError):
+        except (ValueError, AttributeError, RecursionError):
             continue
         m = re.match(r"(\d+)\.(\d+)\.(\d+)", version) if isinstance(version, str) else None
         if m:
@@ -444,7 +444,7 @@ def last_transcript_model(path):
     for line in reversed(transcript_tail(path)):
         try:
             model = (json.loads(line).get("message") or {}).get("model")
-        except (ValueError, AttributeError):
+        except (ValueError, AttributeError, RecursionError):
             continue
         if isinstance(model, str) and model and not model.startswith("<"):
             return model
@@ -504,9 +504,10 @@ ROLLOUT_TAIL = 64 * 1024
 
 def number(value):
     try:
-        return None if value is None else float(value)
+        x = None if value is None else float(value)
     except (TypeError, ValueError):
         return None
+    return x if x is None or math.isfinite(x) else None   # NaN/Infinity is no reading
 
 
 def record_quota(weekly, five_hour, resets_at, source, seen_at=None):
@@ -564,7 +565,7 @@ def rollout_limits(path):
             continue
         try:
             event = json.loads(line)
-        except ValueError:
+        except (ValueError, RecursionError):
             continue
         limits = (event.get("payload") or {}).get("rate_limits") or {}
         weekly = five = None
@@ -864,7 +865,7 @@ def profile():
         with open(profile_file(HOME), encoding="utf-8") as fh:
             data = json.load(fh)
         return data if isinstance(data, dict) else {}
-    except (OSError, ValueError):
+    except (OSError, ValueError, RecursionError):
         return {}
 
 
@@ -919,7 +920,7 @@ def project_task(cwd):
             try:
                 with open(path, encoding="utf-8") as fh:
                     task = json.load(fh).get("task_id")
-            except (OSError, ValueError, AttributeError):
+            except (OSError, ValueError, AttributeError, RecursionError):
                 return None, None
             return (here, task) if task else (None, None)
         parent = os.path.dirname(here)
@@ -985,11 +986,18 @@ def codex_missed_reroute(payload):
         "or an unavailable model, stop and say so instead of retrying.")}})
 
 
+def ai_unattended():
+    """AI_UNATTENDED is set when it is non-empty and not 0, false or no (case
+    and blanks ignored): one rule in every reader (risk 0587)."""
+    return os.environ.get("AI_UNATTENDED", "").strip().lower() not in ("", "0", "false", "no")
+
+
 def unattended():
-    """Nobody can answer an ask: AI_UNATTENDED=1, or Claude Code's own
-    CLAUDE_CODE_SESSION_ATTENDED=0 (set by `claude -p` and the SDK). Unset —
-    an older Claude Code — still asks."""
-    return os.environ.get("AI_UNATTENDED") == "1" or os.environ.get("CLAUDE_CODE_SESSION_ATTENDED") == "0"
+    """Nobody can answer an ask: AI_UNATTENDED set (ai_unattended), or Claude
+    Code's own CLAUDE_CODE_SESSION_ATTENDED=0 (set by `claude -p` and the SDK).
+    Unset — an older Claude Code — still asks. dialog.json background_sessions
+    is the dialog's opt-in only: this gate still treats ATTENDED=0 as unattended."""
+    return ai_unattended() or os.environ.get("CLAUDE_CODE_SESSION_ATTENDED") == "0"
 
 
 def will_ask():
@@ -1117,24 +1125,31 @@ def disabled():
 
 
 def context_line(payload):
-    """`Opus 5.5 [1m] · 123k/1000k (12%)` from a Claude Code statusline payload, or ""
+    """`Opus 5.5 [1m] high · 123k/1000k (12%)` (the effort right after the model,
+    when the payload names one) from a Claude Code statusline payload, or ""
     when it names neither the model nor the context. The context_window fields differ
     between Claude Code versions: the tokens come from current_usage (input plus cache
     reads and writes, what the next turn re-reads), else from used_percentage."""
     model = payload.get("model")
     name = str(model.get("display_name") or model.get("id") or "") if isinstance(model, dict) else ""
+    effort = payload.get("effort")
+    effort = effort.get("level") if isinstance(effort, dict) else None
+    if name and isinstance(effort, str) and effort.strip():
+        name = "%s %s" % (name, effort.strip())
     window = payload.get("context_window")
     window = window if isinstance(window, dict) else {}
 
-    def number(value):
-        return value if isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0 else None
+    def finite_number(value):
+        # finite only: Infinity makes round() raise and the whole line would be lost
+        return (value if isinstance(value, (int, float)) and not isinstance(value, bool)
+                and math.isfinite(value) and value >= 0 else None)
 
-    size = number(window.get("context_window_size"))
-    pct = number(window.get("used_percentage"))
+    size = finite_number(window.get("context_window_size"))
+    pct = finite_number(window.get("used_percentage"))
     usage = window.get("current_usage")
     used = None
     if isinstance(usage, dict):
-        parts = [number(usage.get(k)) for k in
+        parts = [finite_number(usage.get(k)) for k in
                  ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")]
         if any(p is not None for p in parts):
             used = sum(p or 0 for p in parts)
@@ -1148,15 +1163,96 @@ def context_line(payload):
     return " · ".join(part for part in (name, context) if part)
 
 
+SL_RESET, SL_SEP = "\033[00m", " \033[02m|\033[00m "
+
+
+def reset_text(value, fmt):
+    """A rate-limit window's resets_at (epoch seconds or an ISO timestamp) as
+    local time in `fmt`, or ""."""
+    try:
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            when = dt.datetime.fromtimestamp(value)
+        elif isinstance(value, str) and value.strip():
+            text = value.strip()
+            when = (dt.datetime.fromtimestamp(float(text)) if re.fullmatch(r"\d+(\.\d+)?", text)
+                    else dt.datetime.fromisoformat(text.replace("Z", "+00:00")).astimezone())
+        else:
+            return ""
+        return when.strftime(fmt)
+    except (ValueError, OverflowError, OSError):
+        return ""
+
+
+def git_branch(cwd):
+    """The branch checked out in cwd, else the short commit, else ""."""
+    for args in (["symbolic-ref", "--short", "-q", "HEAD"], ["rev-parse", "--short", "HEAD"]):
+        try:
+            done = subprocess.run(["git", "--no-optional-locks", "-C", cwd] + args, capture_output=True,
+                                  text=True, timeout=2, check=False)
+        except (OSError, subprocess.SubprocessError):
+            return ""
+        if done.returncode == 0 and done.stdout.strip():
+            return done.stdout.strip()
+    return ""
+
+
+def second_line(payload):
+    """`user@host:cwd | branch | 5h:12% (↻14:00) 7d:41% (↻Fri 03:04) | $1.23`, the
+    colours of a Debian colour PS1; each part after the prompt is skipped when its
+    data is missing."""
+    workspace = payload.get("workspace")
+    cwd = workspace.get("current_dir") if isinstance(workspace, dict) else None
+    cwd = cwd if isinstance(cwd, str) and cwd else os.getcwd()
+    user = os.environ.get("USER") or os.environ.get("LOGNAME") or ""
+    if not user:
+        try:
+            import getpass  # pylint: disable=import-outside-toplevel
+            user = getpass.getuser()
+        except (ImportError, KeyError, OSError):
+            user = "?"
+    import socket  # pylint: disable=import-outside-toplevel
+    host = socket.gethostname().split(".")[0]
+    out = "\033[01;32m%s@%s%s:\033[01;34m%s%s" % (user, host, SL_RESET, cwd, SL_RESET)
+    branch = git_branch(cwd) if os.path.isdir(cwd) else ""
+    if branch:
+        out += "%s\033[35m%s%s" % (SL_SEP, branch, SL_RESET)
+    limits = payload.get("rate_limits")
+    limits = limits if isinstance(limits, dict) else {}
+    parts = []
+    for key, label, fmt in (("five_hour", "5h", "%H:%M"), ("seven_day", "7d", "%a %H:%M")):
+        window = limits.get(key)
+        pct = window.get("used_percentage") if isinstance(window, dict) else None
+        if isinstance(pct, (int, float)) and not isinstance(pct, bool) and math.isfinite(pct):
+            reset = reset_text(window.get("resets_at"), fmt)
+            parts.append("%s:%d%%%s" % (label, round(pct), " (↻%s)" % reset if reset else ""))
+    if parts:
+        out += "%s\033[33m%s%s" % (SL_SEP, " ".join(parts), SL_RESET)
+    cost = payload.get("cost")
+    cost = cost.get("total_cost_usd") if isinstance(cost, dict) else None
+    if isinstance(cost, (int, float)) and not isinstance(cost, bool) and math.isfinite(cost):
+        out += "%s\033[32m$%.2f%s" % (SL_SEP, cost, SL_RESET)
+    return out
+
+
+def emit(text):
+    """One statusline line as UTF-8 whatever the locale (`·` and `↻` are not ASCII)."""
+    sys.stdout.flush()
+    sys.stdout.buffer.write((text + "\n").encode("utf-8", "replace"))
+    sys.stdout.buffer.flush()
+
+
 def statusline_main(argv):
-    """`statusline [--context] [--then <command>]`: check the weekly limit, print the
-    model and the context use with --context, then hand the same input to the user's
-    own statusline command and pass its output and exit code through. Neither the
-    check nor the line ever gets in the way of the statusline."""
+    """`statusline [--context] [--line] [--then <command>]`: check the weekly limit,
+    print the model, effort and context use with --context (cyan), the prompt line
+    (user@host:cwd | branch | limits | cost) with --line, then hand the same input
+    to the user's own statusline command and pass its output and exit code through.
+    Neither the check nor the lines ever get in the way of the statusline."""
     data = sys.stdin.buffer.read()
-    show_context = argv[1:2] == ["--context"]
-    if show_context:
+    flags = set()
+    while argv[1:2] in (["--context"], ["--line"]):
+        flags.add(argv[1])
         argv = argv[:1] + argv[2:]
+    show_context = "--context" in flags
     payload = None
     try:
         payload = json.loads(data.decode("utf-8", "replace"))
@@ -1171,7 +1267,12 @@ def statusline_main(argv):
         try:
             line = context_line(payload)
             if line:
-                print(line)
+                emit("\033[36m%s%s" % (line, SL_RESET))
+        except Exception:  # pylint: disable=broad-exception-caught  # fail open, as above
+            pass
+    if "--line" in flags and isinstance(payload, dict):
+        try:
+            emit(second_line(payload))
         except Exception:  # pylint: disable=broad-exception-caught  # fail open, as above
             pass
     if len(argv) >= 3 and argv[1] == "--then" and argv[2].strip():

package/hooks/update_notice.py

@@ -51,7 +51,7 @@ def installed_version(runtime, plugin_root, home=None):
         try:
             with open(path, encoding="utf-8") as fh:
                 version = json.load(fh).get(key)
-        except (OSError, ValueError, AttributeError):
+        except (OSError, ValueError, AttributeError, RecursionError):
             continue
         if parse(version):
             return version
@@ -63,7 +63,7 @@ def read_cache(path):
         with open(path, encoding="utf-8") as fh:
             data = json.load(fh)
         return data if isinstance(data, dict) else {}
-    except (OSError, ValueError):
+    except (OSError, ValueError, RecursionError):
         return {}
 
 
@@ -130,7 +130,7 @@ def refresh(path):
             version = json.loads(resp.read(MAX_BODY).decode("utf-8")).get("version")
         if parse(version):
             latest = version
-    except (OSError, ValueError, AttributeError):
+    except (OSError, ValueError, AttributeError, RecursionError):
         pass
     write_cache(path, latest if latest is not None else previous)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "RiskRails: a weight-based engineering pipeline for Claude Code and Codex — scoped steps, enforcement hooks, adversarial review, model routing.",
   "keywords": ["claude-code", "codex", "sdlc", "agents", "guardrails", "code-review"],
   "homepage": "https://github.com/vanssata/claude-agentic-sdlc-module#readme",

package/skills/ai-init/templates/.ai/state/README.md

@@ -1,12 +1,12 @@
 # Task state
 
 `state.json` is the machine-readable record of the task in flight. It is
-written by `skills/ai-task/state.py` (atomically), read by `/ai-status`, and
+written by `skills/ai-task/state.py` (atomically), read by `/rr-status`, and
 enforced by `ai-scope-guard`, which derives the files the current step may touch
 from it.
 
 Two other writers exist, and only these two. A schema migration in
-`/project-update` may change the state through `ctx.patch_state()`, with the
+`/rr-setup --update` may change the state through `ctx.patch_state()`, with the
 same atomic write and a `schema_migrated` history entry — that is how a task in
 flight survives a change to the shape of this file. And `hooks/context-guard.py`
 writes `session.json`, the sidecar beside this file, and nothing else: it never
@@ -14,7 +14,7 @@ touches `state.json`. Nothing else writes any of it — an agent never edits
 them by hand, and the path guard refuses when one tries.
 
 It is **not committed**: it describes a session, not the repository. The
-`.gitignore` entry added by `/ai-init` keeps it out of git.
+`.gitignore` entry added by `/rr-setup` keeps it out of git.
 
 When a task closes, `state.py close` writes the final state to
 `.ai/state/logs/<task-id>/state.json`, beside the task's verify logs — local,
@@ -37,7 +37,7 @@ created_at, updated_at, history[]
 ```
 
 `state.py` applies the schema-2 keys in memory as it loads, so a project that has
-not run `/project-update` yet still answers every command; `save()` then writes
+not run `/rr-setup --update` yet still answers every command; `save()` then writes
 them. A reader that opens this file directly sees what is on disk, not those
 defaults.
 

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

@@ -0,0 +1 @@
+"""rr_state: the task state machine behind skills/ai-task/state.py."""

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

@@ -0,0 +1,210 @@
+"""cli: the argument parser and the dispatch -- the one place that resolves the runtime and builds the Runtime every command receives.
+
+shell: BLOCKING_COMMANDS, MUTATING_COMMANDS, DIALOG_SYNC_COMMANDS, memory_parsers, main
+"""
+import argparse
+import os
+
+from rr_state import close, dialog, dialog_cmd, fs, gate, gate_cmd, memory_cmd, policy, questions_cmd
+from rr_state import report_cmd, review, start, steps, task, verify
+from rr_state import runtime as rr_runtime
+
+# A pending question stops a stage from moving; it never stops a command that
+# records, reads or answers (R3). close --abandon is exempt: abandoning a task is
+# how an unanswerable question is closed.
+BLOCKING_COMMANDS = {"step-done", "approve", "close", "verify"}
+
+# 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", "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"}
+
+
+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=memory_cmd.cmd_recall)
+    p = sub.add_parser("memory", help="the compact project record (docs/local-memory.md)")
+    p.set_defaults(func=memory_cmd.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():
+    # description: the first line of state.py's docstring, which argparse printed as __doc__ before the split
+    parser = argparse.ArgumentParser(
+        description="Task state for /ai-task — the small, machine-readable record of one task.")
+    parser.add_argument("--root", default=".", help="project directory (default: search upwards for .ai/)")
+    parser.add_argument("--runtime", choices=rr_runtime.RUNTIMES,
+                        help="overrides AI_RUNTIME and detection for this call")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("step-done"); p.add_argument("step_id")
+    p.add_argument("--force", action="store_true",
+                   help="accepted for older callers; it forces nothing")
+    p.set_defaults(func=steps.cmd_step_done_v7)
+
+    who = os.environ.get("USER") or "unknown"
+    p = sub.add_parser("ask"); p.add_argument("question", nargs="?")
+    p.add_argument("--option", action="append", default=[]); p.add_argument("--recommend")
+    p.add_argument("--context", default=""); p.add_argument("--gate")
+    p.add_argument("--batch"); p.add_argument("--topic"); p.add_argument("--by", default="")
+    p.set_defaults(func=questions_cmd.cmd_ask)
+
+    p = sub.add_parser("answer"); p.add_argument("assignment", nargs="*")
+    p.add_argument("--prose"); p.add_argument("--by", default=who)
+    # `file` is not offered: it is what --sync writes, and it is the one route
+    # that is recorded as a human's.
+    p.add_argument("--via", choices=["picker", "prose"], default="prose")
+    p.add_argument("--topic"); p.set_defaults(func=questions_cmd.cmd_answer)
+
+    p = sub.add_parser("questions"); p.add_argument("--pending", action="store_true")
+    p.add_argument("--sync", action="store_true"); p.add_argument("--topic")
+    p.add_argument("--by", default=who)
+    p.add_argument("--format", choices=["md", "prose", "json"], default="prose")
+    p.set_defaults(func=questions_cmd.cmd_questions)
+
+    p = sub.add_parser("handoff")
+    p.add_argument("--print", dest="print_it", action="store_true")
+    p.add_argument("--reason", choices=["stage", "precompact", "manual", "session-start"],
+                   default="manual")
+    p.add_argument("--to", choices=rr_runtime.RUNTIMES)
+    p.add_argument("--for", dest="for_", choices=["continue", "review"], default="continue")
+    p.add_argument("--why", default="")
+    p.set_defaults(func=report_cmd.cmd_handoff)
+
+    p = sub.add_parser("profile"); p.add_argument("action", nargs="?", choices=["detect", "set", "ack"])
+    p.add_argument("plan", nargs="?")
+    p.add_argument("--field")
+    p.add_argument("--runtime", dest="detect_runtime", choices=rr_runtime.RUNTIMES)
+    p.add_argument("--open", action="store_true")
+    p.add_argument("--tier", choices=["FAST", "BALANCED", "STRONG", "EXPERT"])
+    p.add_argument("--other", action="store_true"); p.add_argument("--json", action="store_true")
+    p.set_defaults(func=report_cmd.cmd_profile)
+
+    p = sub.add_parser("weight"); p.add_argument("--files", default="")
+    p.add_argument("--goal", default=""); p.add_argument("--declare", action="append", default=[])
+    out = p.add_mutually_exclusive_group()
+    out.add_argument("--json", action="store_true"); out.add_argument("--long", action="store_true")
+    out.add_argument("--mirror", action="store_true"); p.set_defaults(func=start.cmd_weight)
+
+    p = sub.add_parser("event"); p.add_argument("type"); p.add_argument("--detail", default="")
+    p.add_argument("--data"); p.set_defaults(func=report_cmd.cmd_event)
+
+    p = sub.add_parser("approve"); p.add_argument("--by", required=True)
+    p.add_argument("--note", default="")
+    p.add_argument("--confirm", default="", help="the operation a full_irreversible task performs")
+    p.set_defaults(func=gate_cmd.cmd_approve_v7)
+
+    p = sub.add_parser("reject"); p.add_argument("--by", required=True)
+    p.add_argument("--why", required=True); p.set_defaults(func=gate_cmd.cmd_reject)
+
+    p = sub.add_parser("close")
+    p.add_argument("--abandon", action="store_true", help="archive without the checks")
+    p.set_defaults(func=close.cmd_close_v7)
+
+    p = sub.add_parser("start"); p.add_argument("--goal", default="")
+    p.add_argument("--workflow", default=""); p.add_argument("--files", default="")
+    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", 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=start.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=steps.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=steps.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"])
+    p.add_argument("--e2e", nargs=2, metavar=("not-applicable", "WHY"))
+    p.add_argument("--after-fix", dest="after_fix", default="")
+    p.add_argument("--by", default=""); p.set_defaults(func=verify.cmd_verify)
+
+    p = sub.add_parser("review"); p.add_argument("--verdict", choices=sorted(policy.VERDICT_STATUS))
+    p.add_argument("--tier", choices=review.REVIEW_TIERS); p.add_argument("--focus", choices=["security"])
+    p.add_argument("--report", default=""); p.add_argument("--closes", default="")
+    p.add_argument("--by", default=""); p.set_defaults(func=review.cmd_review)
+
+    p = sub.add_parser("status"); p.add_argument("--json", action="store_true")
+    p.set_defaults(func=report_cmd.cmd_status)
+
+    p = sub.add_parser("decision"); p.add_argument("action", choices=["show", "open", "settle", "fallback"])
+    p.add_argument("--id"); p.add_argument("--kind"); p.add_argument("--command", dest="commands", action="append", default=[])
+    p.add_argument("--pick", type=int); p.add_argument("--why", default="")
+    p.add_argument("--json", action="store_true"); p.set_defaults(func=dialog_cmd.cmd_decision)
+
+    p = sub.add_parser("consent"); p.add_argument("action", nargs="?", choices=["audit"])
+    p.add_argument("--json", action="store_true"); p.set_defaults(func=dialog_cmd.cmd_consent)
+
+    memory_parsers(sub)
+
+    args = parser.parse_args()
+    if getattr(args, "topic", None):
+        # Topic mode never touches .ai/: it must work where there is none (I11).
+        args.func(args, fs.find_docs_root(args.root), rt=rr_runtime.Runtime())
+        return
+    if args.command == "profile":
+        # Read-only and task-free: it answers where there is no .ai/ at all.
+        name = args.runtime or os.environ.get("AI_RUNTIME") or \
+            ("claude" if os.environ.get("CLAUDECODE") else "unknown")
+        args.func(args, None, rt=rr_runtime.Runtime(name=name))
+        return
+    root = fs.find_root(args.root)
+    rt = rr_runtime.Runtime(name=rr_runtime.detect_runtime(args.runtime, root),
+                            mutating=args.command in MUTATING_COMMANDS)
+    task.route_surface(root, args, rt=rt)
+    if args.command in BLOCKING_COMMANDS and not getattr(args, "abandon", False):
+        gate.guard_pending(root, args.command, rt=rt)
+    # After the guard: an exit-4 refusal leaves every file as it was.
+    if args.command in DIALOG_SYNC_COMMANDS:
+        dialog.sync_dialog(root, rt=rt)
+    args.func(args, root, rt=rt)