riskrails 3.0.0 → 3.1.0

package/hooks/guard/paths.py

@@ -59,21 +59,18 @@ WHY_APPROVE = T(
     "and tells the session to run state.py questions --sync. An unattended run\n"
     "exports AI_UNATTENDED=1 in the launcher's environment, and the journal then\n"
     "records the approval as unattended for ever. See .ai/policies/safety.md.")
-WHY_SET_BY = T(
-    "\n\nA task gets review_rounds_max review verdicts; after that the human decides,\n"
-    "in their own terminal:\n"
-    "  python3 <plugin>/skills/ai-task/state.py --root . set review_status <value> --by \"<name>\"\n"
-    "Show them the findings in .ai/reports/<task-id>/task.md §Review. An unattended\n"
-    "run exports AI_UNATTENDED=1 in the launcher's environment. See .ai/policies/safety.md.")
 WHY_WORK_CAP = T(
     "This command names more paths than the guard can check within its timeout; split it into "
     "smaller commands, or pass the list through a file and xargs.")
 
 TOKEN_END = "([[:space:]\"';&|)<>]|$)"
 
-# The --confirm-delete rule.
+# The --confirm-delete rule, and --confirm-cleanup (the same human gate; any argparse prefix).
 SEP = "(([^|;&]|[<>]&|&>)*[[:space:]])?" + Q
-CONFIRM = "--co(n(f(i(r(m(-(d(e(l(e(t(e)?)?)?)?)?)?)?)?)?)?)?)?(=|[[:space:]]|['\"]|$)"
+CONFIRM_DEL = "d(e(l(e(t(e)?)?)?)?)?"
+CONFIRM_CLEAN = "c(l(e(a(n(u(p)?)?)?)?)?)?"
+CONFIRM = ("--co(n(f(i(r(m(-(" + CONFIRM_DEL + "|" + CONFIRM_CLEAN + ")?)?)?)?)?)?)?"
+           "(=|[[:space:]]|['\"]|$)")
 APPLY = "--ap(p(l(y)?)?)?" + END
 HEAD = "(^|[[:space:]'\"/|;&(`])(update\\.py|-[A-Za-z]*m[[:space:]]*" + Q + "update|" + VAR + ")" + Q + "[[:space:]]"
 CONFIRM_RE = HEAD + SEP + CONFIRM + SEP + APPLY + "|" + HEAD + SEP + APPLY + SEP + CONFIRM
@@ -84,10 +81,49 @@ VERB = "([[:space:]]+--)?[[:space:]]+" + Q + "approve" + END
 BOUND = "(^|[|;&([:space:]`])"
 APPROVE_RE = (BOUND + "(python3?[[:space:]]+)?" + Q + "[^[:space:]'\"]*state\\.py" + Q + ARGS + VERB + "|"
               + BOUND + "(python3?[[:space:]]+)?" + Q + VAR + Q + ARGS + VERB)
-SETBY_VERB = ("([[:space:]]+--)?[[:space:]]+" + Q + "set" + END + "([^|;&`]*[[:space:]])?" + Q + "--by?"
-              + Q + "(=|[[:space:]]|$)")
-SETBY_RE = (BOUND + "(python3?[[:space:]]+)?" + Q + "[^[:space:]'\"]*state\\.py" + Q + ARGS + SETBY_VERB + "|"
-            + BOUND + "(python3?[[:space:]]+)?" + Q + VAR + Q + ARGS + SETBY_VERB)
+# R36.11: the other human-only state.py commands — `profile set` (dialog on only)
+# and the --by forms of verify, review and reject (dialog on or off) — run from an
+# agent session only as the next live pick, like approve. `start --mode light --by`
+# is denied with the dialog off only: `light` is the one --mode value that can
+# never raise a mode; with the dialog on it reaches state.py, which opens the
+# lowering decision (review H1, T-2026-10-28-010); any other `start --mode X --by`
+# reaches state.py too (T-2026-10-30-0758 Q1, Q2).
+PROFILE_SET_VERB = "([[:space:]]+--)?[[:space:]]+" + Q + "profile" + Q + "[[:space:]]+" + Q + "set" + END
+PROFILE_SET_RE = (BOUND + "(python3?[[:space:]]+)?" + Q + "[^[:space:]'\"]*state\\.py" + Q + ARGS + PROFILE_SET_VERB
+                  + "|" + BOUND + "(python3?[[:space:]]+)?" + Q + VAR + Q + ARGS + PROFILE_SET_VERB)
+BY_TOK = Q + "--by?" + Q + "(=|[[:space:]]|$)"
+MODE_LIGHT = Q + "--m(o(d(e)?)?)?" + Q + "(=|[[:space:]]+)" + Q + "light" + END
+SKIP = "([^|;&`]*[[:space:]])?"
+HUMAN_BY_VERB = ("([[:space:]]+--)?[[:space:]]+" + Q + "(verify|review|reject)" + END + SKIP + BY_TOK)
+START_LIGHT_VERB = ("([[:space:]]+--)?[[:space:]]+" + Q + "start" + END + SKIP + "("
+                    + MODE_LIGHT + SKIP + BY_TOK + "|" + BY_TOK + SKIP + MODE_LIGHT + ")")
+
+
+def state_verb_re(verb):
+    """The state.py command whose verb part is `verb`, as an ERE: by path or by a variable."""
+    return (BOUND + "(python3?[[:space:]]+)?" + Q + "[^[:space:]'\"]*state\\.py" + Q + ARGS
+            + "(" + verb + ")|" + BOUND + "(python3?[[:space:]]+)?" + Q + VAR + Q + ARGS + "(" + verb + ")")
+
+
+HUMAN_BY_RE = state_verb_re(HUMAN_BY_VERB)
+START_LIGHT_RE = state_verb_re(START_LIGHT_VERB)
+WHY_HUMAN = T(
+    "\n\nThis command is the human's, whether or not the dialog is on. A human runs it in their\n"
+    "own terminal, outside the agent session; an unattended run exports AI_UNATTENDED=1 in the\n"
+    "launcher's environment. See .ai/policies/safety.md.")
+WHY_PICK = T(
+    "\n\nWith the dialog on, this command runs from an agent session only as the human's pick.\n"
+    "The command that needs it opened a decision: 'state.py decision show' prints the dialog;\n"
+    "send it and run the picked command verbatim, once. Otherwise the human runs it in their\n"
+    "own terminal. See .ai/policies/safety.md.")
+# R36.11: running the dialog's recorder by hand would forge the human's answer.
+# dialog-gate.py in command position — the program itself, or the script a
+# python runs — after a separator, a quote, exec/env/command/nohup/time/sudo
+# and their words; naming it as an argument (grep, git diff, chmod) is not running it.
+DIALOG_GATE_RE = ("(^|[|;&(`{'\"]|\\$\\()[[:space:]]*((exec|env|command|nohup|time|sudo)([[:space:]]+[^[:space:]|;&]+)*"
+                  "[[:space:]]+)?(" + Q + "[^[:space:]'\"|;&]*python[0-9.]*" + Q
+                  + "([[:space:]]+-[^[:space:]]+)*[[:space:]]+)?" + Q + "[^[:space:]'\"|;&]*dialog-gate\\.py" + Q
+                  + "([[:space:]|;&)<>]|$)")
 VERBS_RE = ("(^|[^A-Za-z0-9_.-])(cp|mv|install|rsync|rm|rmdir|unlink|tee|truncate|shred|touch|ln|chmod|chown|"
             "dd|sed|perl|ruby)([^A-Za-z0-9_.-]|$)")
 SEGMENT = "^[[:space:]]*"
@@ -112,7 +148,7 @@ LN_SRC_RE = ".*(^|[|;&[:space:]])ln([[:space:]]+-[^[:space:]]+)*[[:space:]]+([^[
 LONG_CMD = 4096
 # Whole words only, so --cov, --config and approve_invoice do not trip it.
 LONG_TRIGGER_RE = ("(^|[^A-Za-z0-9_])approve([^A-Za-z0-9_]|$)|--by(=|[[:space:]]|$)|"
-                   "--con?f?i?r?m?-?d?e?l?e?t?e?(=|[[:space:]]|$)|state\\.py|update\\.py")
+                   "--con?f?i?r?m?-?(d?e?l?e?t?e?|c?l?e?a?n?u?p?)(=|[[:space:]]|$)|state\\.py|update\\.py")
 # Tools that write a file named on their command line without a redirect; the
 # movers do not parse them, so any protected path they name is refused (H1).
 FETCHERS = "(^|[|;&[:space:]])(scp|tar|zip|unzip|curl|wget)([[:space:]]+[^;&|[:space:]]+)*[[:space:]]+"
@@ -206,7 +242,7 @@ def realpath_m(path):
 
 def find_print(start, maxdepth, prune):
     """`find START -maxdepth N \\( -name A -o … \\) -prune -o -print`, in
-    readdir order, links not followed, errors silent."""
+    name order (not find's readdir order), links not followed, errors silent."""
     def walk(path, name, depth):
         if name in prune:
             return
@@ -218,7 +254,9 @@ def find_print(start, maxdepth, prune):
                 entries = list(it)
         except OSError:
             return
-        for e in entries:
+        # by name, not readdir order: which held file a refusal names must not depend
+        # on the filesystem (ext4 here put .ai/policies first, the CI runner .ai/state)
+        for e in sorted(entries, key=lambda e: e.name):
             try:
                 is_d = e.is_dir(follow_symlinks=False)
             except OSError:
@@ -1168,6 +1206,27 @@ class PathGuard:                            # pylint: disable=too-many-instance-
             return
         self.check_bash(unattended)
 
+    def dialog_consent(self, cmd):
+        """(the dialog is on for this call, the command is the next live pick
+        of this session) — R36.11's pass-through. state.py spends the pick
+        after its own argv check (R36.10); the guard only lets it reach it."""
+        if not self.root or not exists(self.root + "/.ai/policies/dialog.json"):
+            return False, False
+        from datetime import datetime, timezone  # pylint: disable=import-outside-toplevel
+        from guard import dialog            # pylint: disable=import-outside-toplevel
+        root = os.fsdecode(b_bytes(self.root))
+        values = self.p.values
+        raw = values[0] if len(values) == 1 and isinstance(values[0], dict) else None
+        hook_file = os.path.join(os.fsdecode(b_bytes(self.ctx.hook_dir)), "ai-guard.py")
+        try:
+            if raw is None or not dialog.effective_switch(root, dialog.payload_runtime(raw, hook_file), raw):
+                return False, False
+            pick = dialog.next_live_pick(root, raw.get("session_id"), datetime.now(timezone.utc))
+        except Exception:                   # pylint: disable=broad-exception-caught
+            return True, False
+        command = b_bytes(cmd).decode("utf-8", "replace").strip()
+        return True, bool(pick and pick.get("label") == command)
+
     def interpreter_text(self, cmd):
         """The text of an interpreter one-liner or an eval, scanned whole (H3)."""
         m = self.m
@@ -1199,11 +1258,22 @@ class PathGuard:                            # pylint: disable=too-many-instance-
         if length(cmd) > LONG_CMD and (m.search_c(LONG_TRIGGER_RE, cmd) or m.matches_joined(cmd, self.loose)):
             raise Deny("Refusing a %d-character shell command that names a guarded path or a state.py or "
                        "update.py verb: write it to a file and run that, or split it." % length(cmd))
-        if m.ere_match(APPROVE_RE, cmd_joined) and not unattended and self.task_in_flight():
+        if m.ere_match(DIALOG_GATE_RE, cmd_joined):
+            raise Deny("Refusing to run hooks/dialog-gate.py from a shell: it records the human's answer to "
+                       "the dialog, and only the runtime calls it, after the dialog tool. To answer a decision, "
+                       "send the dialog ('state.py decision show'); a human settles one in their own terminal "
+                       "('state.py decision settle --id D<n> --pick <n>'). See .ai/policies/safety.md.")
+        on, picked = self.dialog_consent(cmd)
+        if m.ere_match(APPROVE_RE, cmd_joined) and not unattended and self.task_in_flight() and not picked:
             raise Deny("Refusing 'state.py approve' from an agent session." + WHY_APPROVE)
-        if m.ere_match(SETBY_RE, cmd_joined) and not unattended and self.task_in_flight():
-            raise Deny(T("Refusing 'state.py set \u2026 --by' from an agent session: a verdict with --by is the "
-                         "human's, given when the review budget is spent.") + WHY_SET_BY)
+        if on and not picked and not unattended and m.ere_match(PROFILE_SET_RE, cmd_joined):
+            raise Deny("Refusing 'state.py profile set' from an agent session." + WHY_PICK)
+        if not picked and not unattended and m.ere_match(HUMAN_BY_RE, cmd_joined):
+            raise Deny(T("Refusing a verdict with 'state.py … --by' from an agent session.")
+                       + (WHY_PICK if on else WHY_HUMAN))
+        if not on and not picked and not unattended and m.ere_match(START_LIGHT_RE, cmd_joined):
+            raise Deny(T("Refusing 'state.py start --mode light … --by' from an agent session: lowering the "
+                         "mode is the human's.") + WHY_HUMAN)
         self.interpreter_text(cmd)
 
         # Top-level splitting only: the string a sh -c or an eval runs is not

package/hooks/hooks.json

@@ -14,13 +14,13 @@
         ]
       },
       {
-        "matcher": "Read|Edit|Write|MultiEdit|NotebookEdit|Bash",
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
             "command": "python3 -I -S \"${CLAUDE_PLUGIN_ROOT}/hooks/ai-guard.py\"",
             "timeout": 15,
-            "statusMessage": "Checking git, paths and scope"
+            "statusMessage": "Checking git, paths, scope and open decisions"
           }
         ]
       },
@@ -84,7 +84,30 @@
         ]
       }
     ],
+    "Notification": [
+      {
+        "matcher": "auth_success",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/context-guard.py\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -I -S \"${CLAUDE_PLUGIN_ROOT}/hooks/dialog-gate.py\"",
+            "timeout": 5,
+            "statusMessage": "Recording the dialog's answer"
+          }
+        ]
+      },
       {
         "matcher": "Agent",
         "hooks": [
@@ -117,6 +140,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -I -S \"${CLAUDE_PLUGIN_ROOT}/hooks/dialog-gate.py\"",
+            "timeout": 5,
+            "statusMessage": "Checking for an open decision"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/memory-pre-push.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""riskrails memory pre-push validator (spec compact-project-memory §D10, §I5).
+
+  memory-pre-push.py <remote> <url>  < "<lref> <lsha> <rref> <rsha>"…   git hook
+  memory-pre-push.py --range OLD..NEW [--repo DIR]                       CI or server
+  memory-pre-push.py --tree REV [--repo DIR]                             structure only
+
+Checks the pushed commits' blobs, never the working tree. stderr carries one
+line per finding; exit 0 clean, 1 findings (the push stops), 3 the validator
+itself failed (fail closed). It writes no file, uses no network and imports
+no state.py. A git hook, not a runtime hook: no tool call ever runs it. The
+logic is memory_sync.pre_push, which the shim also runs directly where an
+install copied skills/ai-task/ but not this file.
+"""
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(os.path.dirname(HERE), "skills", "ai-task"))
+
+if __name__ == "__main__":
+    try:
+        import memory_sync  # pylint: disable=import-outside-toplevel
+    except ImportError as exc:
+        print("memory-pre-push: validator error: %s — run 'state.py memory verify --all'; a human may push "
+              "with 'git push --no-verify'" % exc, file=sys.stderr)
+        sys.exit(3)
+    sys.exit(memory_sync.pre_push_cli(sys.argv[1:]))

package/hooks/project-scaffold.py

@@ -236,12 +236,8 @@ def main(argv):
     on = runtimes(runtime, root)
     s = Scaffold(tpl, root)
 
-    # shared SDLC
+    # shared SDLC (the intent/spec/plan/adr templates ship with the plugin; a project TEMPLATE.md is only an override)
     s.put("sdlc-README.md", "docs/sdlc/README.md")
-    s.put("intent.md", "docs/sdlc/intent/TEMPLATE.md")
-    s.put("spec.md", "docs/sdlc/specs/TEMPLATE.md")
-    s.put("plan.md", "docs/sdlc/plans/TEMPLATE.md")
-    s.put("adr.md", "docs/sdlc/adr/TEMPLATE.md")
     s.put("constitution.md", "docs/sdlc/constitution.md", render=True)
 
     # per runtime

package/hooks/runtime-gate.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
-"""Runtime gate: one hook for both runtimes, replacing fable-gate.py and
-codex-model-gate.py (which remain as shims that exec this file).
+"""Runtime gate: one hook for both runtimes (Claude Code and Codex). The older
+fable-gate.py and codex-model-gate.py remain only as shims that exec this file.
 
 The most capable model of a plan can stop serving an account — a rate limit, a
 used-up usage limit, a model the account cannot reach — and the runtime's own
@@ -12,8 +12,9 @@ Claude Code (model: fable -> opus):
   StopFailure (rate_limit|model_not_found)  records that Fable is unavailable
   PostToolUse:Agent                         records a Fable agent that fell back (overload), briefly
   PreToolUse:Agent                          while a record is live, rewrites model fable -> opus
-  statusline [--then <command>]             records it when the weekly limit is nearly used, then
-                                            runs the user's own statusline command on the same input
+  statusline [--context] [--then <command>] records it when the weekly limit is nearly used, prints
+                                            the model and the context use with --context, then runs
+                                            the user's own statusline command on the same input
 
 Codex (EXPERT model -> STRONG model); an agent launch is `spawn_agent`, or
 `collaborationspawn_agent` under multi-agent v2:
@@ -43,7 +44,7 @@ A record expires on its own. The gate never denies, always exits 0, and any
 error inside it fails open: the call goes through unchanged.
 
   runtime-gate.py status | quota [--json] | clear | set <seconds> [reason]
-                  | statusline [--then <cmd>]
+                  | statusline [--context] [--then <cmd>]
 
 Quota (advice only, it never refuses anything): Claude Code's comes from the
 statusline payload, Codex's from the newest rollout's token_count event. Both
@@ -414,10 +415,10 @@ def claude_pre_tool_use(payload):
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "allow",
-            "permissionDecisionReason": f"fable-gate: {why}; {name} runs on {FALLBACK}",
+            "permissionDecisionReason": f"runtime-gate: {why}; {name} runs on {FALLBACK}",
             "updatedInput": {**tool_input, "model": FALLBACK},
             "additionalContext": (
-                f"fable-gate routed this {name} agent to {FALLBACK}: {why}. "
+                f"runtime-gate routed this {name} agent to {FALLBACK}: {why}. "
                 f"Its answer is {FALLBACK}'s, not Fable's. "
                 "`~/.claude/hooks/runtime-gate.py clear` re-enables Fable early."
             ),
@@ -800,10 +801,10 @@ def codex_pre_tool_use(payload):
         journal_fallback(payload, label, model, to, rec)
         out["hookSpecificOutput"]["permissionDecision"] = "allow"
         out["hookSpecificOutput"]["updatedInput"] = updated
-        context = (f"codex-model-gate: {why}. {label} runs on {to}{via} instead, so its answer is "
+        context = (f"runtime-gate: {why}. {label} runs on {to}{via} instead, so its answer is "
                    f"{to}'s, not {EXPERT}'s. Say so when you report it. ")
     else:
-        context = (f"codex-model-gate: {why}. {label} is not rerouted ({not_why}): it runs on {EXPERT} "
+        context = (f"runtime-gate: {why}. {label} is not rerouted ({not_why}): it runs on {EXPERT} "
                    "and may fail the same way. Say so when you report it. ")
     out["hookSpecificOutput"]["additionalContext"] = context + "`runtime-gate.py clear` re-enables the expert model early."
     respond(out)
@@ -1102,7 +1103,7 @@ def cli(argv):
     if cmd == "set" and len(argv) >= 2 and argv[1].isdigit():
         mark(time.time() + int(argv[1]), " ".join(argv[2:]) or "manual", "cli")
         return cli(["status"])
-    print("usage: runtime-gate.py status | quota [--json] | clear | set <seconds> [reason] | statusline [--then <cmd>] < json",
+    print("usage: runtime-gate.py status | quota [--json] | clear | set <seconds> [reason] | statusline [--context] [--then <cmd>] < json",
           file=sys.stderr)
     return 2
 
@@ -1115,17 +1116,63 @@ def disabled():
     return False
 
 
+def context_line(payload):
+    """`Opus 5.5 [1m] · 123k/1000k (12%)` 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 ""
+    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
+
+    size = number(window.get("context_window_size"))
+    pct = number(window.get("used_percentage"))
+    usage = window.get("current_usage")
+    used = None
+    if isinstance(usage, dict):
+        parts = [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)
+    if used is None and pct is not None and size:
+        used = size * pct / 100
+    if pct is None and used is not None and size:
+        pct = used * 100 / size
+    context = ""
+    if used is not None and size:
+        context = f"{round(used / 1000)}k/{round(size / 1000)}k ({round(pct)}%)"
+    return " · ".join(part for part in (name, context) if part)
+
+
 def statusline_main(argv):
-    """`statusline [--then <command>]`: check the weekly limit, then hand the same
-    input to the user's own statusline command and pass its output and exit code
-    through. The check never gets in the way of the statusline."""
+    """`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."""
     data = sys.stdin.buffer.read()
-    if not disabled() and RUNTIME == "claude":
+    show_context = argv[1:2] == ["--context"]
+    if show_context:
+        argv = argv[:1] + argv[2:]
+    payload = None
+    try:
+        payload = json.loads(data.decode("utf-8", "replace"))
+    except Exception:  # pylint: disable=broad-exception-caught  # fail open: a bad payload never breaks the statusline
+        pass
+    if isinstance(payload, dict) and not disabled() and RUNTIME == "claude":
+        try:
+            statusline(payload)
+        except Exception:  # pylint: disable=broad-exception-caught  # fail open, as above
+            pass
+    if show_context and isinstance(payload, dict):
         try:
-            payload = json.loads(data.decode("utf-8", "replace"))
-            if isinstance(payload, dict):
-                statusline(payload)
-        except Exception:  # pylint: disable=broad-exception-caught  # fail open: a bad payload never breaks the statusline
+            line = context_line(payload)
+            if line:
+                print(line)
+        except Exception:  # pylint: disable=broad-exception-caught  # fail open, as above
             pass
     if len(argv) >= 3 and argv[1] == "--then" and argv[2].strip():
         shell = shutil.which("bash") or "/bin/sh"

package/hooks/update_notice.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Update notice: tell the user at session start when npm has a newer `riskrails`.
+
+Imported by context-guard.py (SessionStart) and run as a script for the refresh:
+
+    update_notice.py --refresh <cache path>
+
+The hook itself never touches the network. It reads <home>/riskrails/update-check.json
+({"checked_at": epoch, "latest": "x.y.z"}); when that file is missing or older than a
+day it starts the refresh as a detached child and answers from the cache as it is, so
+the first session after an install says nothing and a later one does. The child asks
+the registry (3 s timeout) and writes the cache atomically; any error is silent, and a
+failed fetch only moves checked_at, so the next try waits a day.
+
+Environment:
+    RISKRAILS_NO_UPDATE_CHECK   non-empty turns the check off (no read, no spawn)
+    CI                          non-empty turns it off as well
+    RISKRAILS_REGISTRY_URL      instead of https://registry.npmjs.org/riskrails/latest (file:// works)
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.request
+
+REGISTRY_URL = "https://registry.npmjs.org/riskrails/latest"
+MAX_AGE = 24 * 3600
+TIMEOUT = 3
+MAX_BODY = 65536
+COMMAND = "npx -y riskrails@latest --yes"
+VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")   # no prerelease, no build metadata
+
+
+def parse(version):
+    """(major, minor, patch) of a plain X.Y.Z, else None."""
+    match = VERSION_RE.match(version.strip()) if isinstance(version, str) else None
+    return tuple(int(n) for n in match.groups()) if match else None
+
+
+def installed_version(runtime, plugin_root, home=None):
+    """The installed release: profile.json's plugin_version (written by the installer into
+    <home>/riskrails/), else the plugin manifest beside the hooks (plugin-cache layout).
+    Only a plain X.Y.Z counts; anything else is None."""
+    manifest = ".codex-plugin" if runtime == "codex" else ".claude-plugin"
+    sources = [(os.path.join(plugin_root, manifest, "plugin.json"), "version")]
+    if home:
+        sources.insert(0, (os.path.join(home, "riskrails", "profile.json"), "plugin_version"))
+    for path, key in sources:
+        try:
+            with open(path, encoding="utf-8") as fh:
+                version = json.load(fh).get(key)
+        except (OSError, ValueError, AttributeError):
+            continue
+        if parse(version):
+            return version
+    return None
+
+
+def read_cache(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def disabled():
+    return bool(os.environ.get("RISKRAILS_NO_UPDATE_CHECK") or os.environ.get("CI"))
+
+
+def spawn_refresh(path):
+    try:
+        subprocess.Popen([sys.executable, "-I", os.path.abspath(__file__), "--refresh", path],  # pylint: disable=consider-using-with
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                         stderr=subprocess.DEVNULL, start_new_session=True)
+    except OSError:
+        pass
+
+
+def notice(runtime, home, plugin_root, now):
+    """(systemMessage, additionalContext) when the cache knows a newer release, else ("", "")."""
+    if disabled():
+        return "", ""
+    riskrails = os.path.join(home, "riskrails")
+    path = os.path.join(riskrails, "update-check.json")
+    cache = read_cache(path)
+    checked = cache.get("checked_at")
+    fresh = isinstance(checked, (int, float)) and 0 <= now - checked < MAX_AGE
+    if not fresh and os.path.isdir(riskrails):
+        spawn_refresh(path)
+    installed, latest = installed_version(runtime, plugin_root, home), cache.get("latest")
+    have, new = parse(installed), parse(latest)
+    if not have or not new or new <= have:
+        return "", ""
+    message = (f"RiskRails {latest} is available (installed {installed}). Update: {COMMAND} "
+               f"— inside Claude Code or Codex CLI: ! {COMMAND} — then /rr-setup --update in each project.")
+    context = (f"RiskRails {latest} is available on npm; {installed} is installed. The user updates it "
+               f"with `{COMMAND}` in a terminal, or `! {COMMAND}` inside Claude Code or Codex CLI, "
+               "then `/rr-setup --update` in each project. Mention this once to the user if it is "
+               "relevant; never run the update yourself — installing is the user's act.")
+    return message, context
+
+
+def write_cache(path, latest):
+    tmp = f"{path}.{os.getpid()}.tmp"
+    try:
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump({"checked_at": int(time.time()), "latest": latest}, fh)
+        os.replace(tmp, path)
+    except OSError:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+
+
+def refresh(path):
+    """Ask the registry and write the cache; checked_at moves first, so a fetch that hangs
+    or is killed still costs one spawn a day, and a failed fetch keeps the previous latest."""
+    previous = read_cache(path).get("latest")
+    previous = previous if isinstance(previous, str) else None
+    write_cache(path, previous)
+    latest = None
+    try:
+        url = os.environ.get("RISKRAILS_REGISTRY_URL") or REGISTRY_URL
+        with urllib.request.urlopen(url, timeout=TIMEOUT) as resp:  # nosec: the registry, or a test's file URL
+            version = json.loads(resp.read(MAX_BODY).decode("utf-8")).get("version")
+        if parse(version):
+            latest = version
+    except (OSError, ValueError, AttributeError):
+        pass
+    write_cache(path, latest if latest is not None else previous)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 3 and sys.argv[1] == "--refresh" and not disabled():
+        refresh(sys.argv[2])
+    sys.exit(0)

package/instructions/routing.md

@@ -38,7 +38,7 @@ Facts are collected cheaply; thinking is paid for. Session model {{SESSION_MODEL
 - One subagent returning twenty lines beats five tool calls whose output stays in context all session.
 - Deterministic tools first: `rg`, `git`, `jq`, the framework CLI, the test runner.
 - `/clear` between tasks, and after every task that ran a review. Compaction near {{COMPACT_WINDOW}} tokens is a summary of the old task, not a clean start; until then every turn re-reads the whole history.
-- `context-guard` measures the context on every prompt: a one-line warning from {{CONTEXT_WARN}} tokens, and from {{CONTEXT_BLOCK}} the prompt is held back once — sending it again goes through. When its note says the prompt starts a different task, suggest `/clear` before doing the work. Before a compaction it saves the edited files, the latest instructions verbatim, the todo list and the git state, and hands them back afterwards as "Session state before compaction": trust that block over the summary where they differ, and re-read a file before editing it rather than relying on what the summary says it contains.
+- `context-guard` measures the context on every prompt: a one-line warning from {{CONTEXT_WARN}} tokens, {{CONTEXT_BLOCK}}. When its note says the prompt starts a different task, suggest `/clear` before doing the work. Before a compaction it saves the edited files, the latest instructions verbatim, the todo list and the git state, and hands them back afterwards as "Session state before compaction": trust that block over the summary where they differ, and re-read a file before editing it rather than relying on what the summary says it contains.
 - Run tests once, to the end, and fix every failure as one batch. Never one failure, one fix, one run.
 - `/usage-report` shows where the tokens went, at zero model cost; `--provider both` puts Codex next to Claude Code.
 
@@ -46,8 +46,8 @@ Facts are collected cheaply; thinking is paid for. Session model {{SESSION_MODEL
 # Guards
 
 <!-- stub: runtime=claude -->
-- `ai-git-guard` runs in every repository: no force push, history rewrite, push or merge to a protected branch, `--no-verify`, staged secret or production deploy. `ai-path-guard` and `ai-scope-guard` arm only where `.ai/` exists. No agent commits, merges or deploys on its own; the pipeline ends at human approval.
-- `context-guard` measures the context on every prompt and holds a prompt back once at the block threshold above; its "Session state before compaction" block and `.ai/state/handoff.md` are what a resumed session trusts over the summary.
+- `ai-git-guard` runs in every repository: no force push, history rewrite, push or merge to a protected branch, `--no-verify`, staged secret or production deploy. `ai-path-guard` and `ai-scope-guard` arm only where `.ai/` exists. No agent merges or deploys; commit, push and approval run only as the command the human picked in the dialog, as the harness recorded — verbatim, once — or the human runs them outside the agent.
+- `context-guard` measures the context on every prompt and holds a prompt back once at the block threshold above, when there is one; its "Session state before compaction" block and `.ai/state/handoff.md` are what a resumed session trusts over the summary.
 
 <!-- stub: runtime=codex -->
 # Model allocation by task and scope (host-wide, ChatGPT {{CODEX_PLAN}} plan)
@@ -130,7 +130,7 @@ The main session re-reads its whole context every turn, so context length — mo
 # Guards
 
 <!-- stub: runtime=codex -->
-- `ai-git-guard` runs in every repository: no force push, history rewrite, push or merge to a protected branch, `--no-verify`, staged secret or production deploy. `ai-path-guard` and `ai-scope-guard` arm only where `.ai/` exists. All three see `Bash` and `apply_patch`; run `/hooks` once after installing to review and trust them, or they are skipped. No agent commits, merges or deploys on its own; the pipeline ends at human approval.
+- `ai-git-guard` runs in every repository: no force push, history rewrite, push or merge to a protected branch, `--no-verify`, staged secret or production deploy. `ai-path-guard` and `ai-scope-guard` arm only where `.ai/` exists. All three see `Bash` and `apply_patch`; run `/hooks` once after installing to review and trust them, or they are skipped. No agent merges or deploys; commit, push and approval run only as the command the human picked in the dialog — verbatim, once — or the human runs them outside the agent.
 - `architect` is for design questions outside a task, in a repository without `.ai/`, and in a full-mode task whose design is open (`/rr-plan`). Otherwise the session plans, and an EXPERT spawn is the escalation.
 
 <!-- stub: runtime=claude,codex -->

package/instructions/stub.md

@@ -24,7 +24,7 @@ Rules for every repository; everything else loads on demand. `{{HOME}}/riskrails
 - With `.ai/`: read `.ai/AGENTS.md` first, run every change through `/rr-build <request>`, treat `.ai/policies/` as binding; `/rr-setup --update` after a plugin reinstall. Without `.ai/`: `/rr-setup` first.
 - Production behaviour is the source of truth: document problems outside the task, do not fix them. Never mix a refactoring with a feature change.
 - Each step names the files it may touch; an edit outside them is refused — answer `SCOPE_CHANGE_REQUIRED`, do not widen the step.{{MULTI_EDIT}}
-- No agent commits, pushes, merges or deploys; the pipeline ends at human approval, given outside the agent. A guard's refusal is not a hint to reword.{{TRUST}}
+- No agent merges or deploys. Commit, push and approval run only as the command the human picked in the dialog, as the harness recorded — verbatim, once — or the human runs them outside the agent. A guard's refusal is not a hint to reword.{{TRUST}}
 - Verify before reporting done: the verification command once, to the end, every failure fixed as one batch, output shown.
 - Context: `grep -n`, then read the hits; never `cat` logs, lockfiles or generated code; a file over ~{{READ_LINES}} lines is read by a FAST reader (`Explore`, `log-reader`) that returns `file:line` excerpts, never the file. Deterministic tools first. {{NEW_CONTEXT}} between tasks. `/rr-status --cost` shows where tokens went.
 - Models are tiers, not names: runners and verbatim extraction on FAST at `low`, readers that judge on BALANCED; the session implements; STRONG and EXPERT only on a named trigger, one agent at a time, never a fleet on the top tier; a failed thinking task is never retried on a cheaper model.
@@ -47,8 +47,8 @@ This repository runs an agentic pipeline under `.ai/`. Read `.ai/AGENTS.md` firs
 
 <!-- stub: scope=project runtime=* -->
 - Verify before reporting done: `verify_command` from `.ai/policies/testing.md` once, to the end, then `e2e_command` once; every failure fixed as one batch; show the output.
-- No agent commits, merges or deploys; approval is given by a human outside the agent. When a review flags the same mistake twice, the correction goes into this file.
-- Files, not chat, carry decisions: `.ai/reports/<task-id>/task.md` (answer by filling `[Answer]:`), `.ai/state/handoff.md` (read first when resuming), `docs/sdlc/constitution.md` (this project's principles).
+- No agent merges or deploys; commit, push, approval only as the dialog picks and the harness records, else a human outside. When a review flags the same mistake twice, the correction goes into this file.
+- Files, not chat, carry decisions: `.ai/reports/<task-id>/task.md` (answer by filling `[Answer]:`), `.ai/state/handoff.md` (read first when resuming), `docs/sdlc/constitution.md`.
 
 <!-- stub: scope=skeleton,skeleton-sdlc runtime=* -->
 # {{PROJECT}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "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/profiles/max.json

@@ -10,12 +10,14 @@
     "claude-sonnet-5": { "effortLevel": "medium" },
     "claude-haiku-4-5-20251001": { "effortLevel": "low" }
   },
-  "autoCompactWindow": 800000,
   "riskrails": {
     "inherits": null,
     "plan": "max",
     "label": "Max",
     "runtime": "claude",
+    "economy": {
+      "autoCompactWindow": 800000
+    },
     "tiers": {
       "FAST": {
         "model": "haiku",