riskrails 3.0.1 → 3.1.0

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "A weight-based engineering pipeline for Claude Code and Codex: each change is weighed on six axes, runs light, guarded or full, edits only the files its plan names, and ends at human approval — enforced by hooks, reviewed adversarially, routed to the cheap model tier by default.",
-    "version": "3.0.1"
+    "version": "3.1.0"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
         "source": "url",
         "url": "https://github.com/vanssata/claude-agentic-sdlc-module.git"
       },
-      "version": "3.0.1",
+      "version": "3.1.0",
       "strict": true
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A weight-based engineering pipeline for Claude Code and Codex: each change is weighed on six axes, runs light, guarded or full, edits only the files its plan names, and ends at human approval — enforced by hooks, reviewed adversarially, routed to the cheap model tier by default.",
   "author": {
     "name": "Ivan Kakurov"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A weight-based engineering pipeline for Claude Code and Codex: each change is weighed on six axes, runs light, guarded or full, edits only the files its plan names, and ends at human approval — enforced by hooks, reviewed adversarially, routed to the cheap model tier by default.",
   "author": {
     "name": "Ivan Kakurov"

package/README.md

@@ -1,6 +1,6 @@
 # RiskRails
 
-[![Version](https://img.shields.io/badge/version-3.0.1-d2f878?labelColor=101210)](https://github.com/vanssata/claude-agentic-sdlc-module/releases/tag/v3.0.1)
+[![Version](https://img.shields.io/badge/version-3.1.0-d2f878?labelColor=101210)](https://github.com/vanssata/claude-agentic-sdlc-module/releases/tag/v3.1.0)
 [![Runtimes](https://img.shields.io/badge/runtimes-Claude%20Code%20%7C%20Codex-d2f878?labelColor=101210)](docs/routing.md)
 [![Known risks](https://img.shields.io/badge/known%20risks-documented-d2f878?labelColor=101210)](docs/known-risks.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-d2f878?labelColor=101210)](LICENSE)
@@ -18,7 +18,7 @@ approval. Risky actions are stopped by a hook, not by a polite request in a
 prompt.
 
 ```bash
-npx riskrails@3.0.1   # detects Claude Code, Codex or both (Node 18+, python3)
+npx riskrails@3.1.0   # detects Claude Code, Codex or both (Node 18+, Python 3.11+)
 ```
 
 Then, in any project: `/rr-setup` once, and `/rr-build <what you want>` for
@@ -50,9 +50,21 @@ Tuned for **one developer who knows the codebase**, on a Claude Pro, Max or
 Team plan, or a ChatGPT Plus or Pro plan, following the
 [AI-native SDLC playbook](https://claude.com/blog/the-ai-native-sdlc-playbook).
 
-**Version 3.0.1.** The guards have limits: read [Known risks](docs/known-risks.md)
+**Version 3.1.0.** The guards have limits: read [Known risks](docs/known-risks.md)
 before relying on them. What is decided but not built is in [ROADMAP.md](ROADMAP.md).
 
+## Upgrade to 3.1
+
+From 3.0.x: update the home (`npx riskrails@3.1.0`, restart the runtime), then
+in each project `/rr-setup --update` (dry run first, then `--apply`). Schema 10
+becomes **11**: migration `0011` proposes deleting `.ai/policies/risk-tiers.json`
+and `risk-tiers.md`, which `weight.json` and `weight.md` replaced; confirm with
+`--apply --confirm-delete <name>` in a terminal of your own. The update now
+renders `weight.md` from `weight.json` instead of merging it, reads the
+`docs/sdlc/*/TEMPLATE.md` files from the plugin (an unedited project copy is
+offered for deletion), and proposes cleanup of old run logs and stale tasks.
+See [CHANGELOG.md](CHANGELOG.md).
+
 ## Upgrade to 3.0
 
 3.0 renames the plugin from `claude-agentic` to `riskrails`, replaces the risk
@@ -70,7 +82,7 @@ version. Step by step, in this order:
 3. **Update the home** on every machine, for every runtime:
 
    ```bash
-   npx riskrails@3.0.1              # or: npx -y riskrails@latest --yes
+   npx riskrails@3.1.0              # or: npx -y riskrails@latest --yes
    ```
 
    It moves `<home>/claude-agentic/` to `<home>/riskrails/` and leaves a
@@ -85,22 +97,22 @@ version. Step by step, in this order:
    /rr-setup --update               # dry run first; read it; then --apply
    ```
 
-   Four migrations run inside the dry run, in order, before the merge:
+   Migrations `0007` to `0010` (and `0011`, see Upgrade to 3.1) run inside the dry run, in order, before the merge:
    `0007` creates `.ai/policies/weight.json`, carrying over the project's
    edits to its risk-tier table; `0008` renames the managed-block markers and
    the router's routes; `0009` moves `current.json` to `state.json`; `0010`
    creates `.ai/policies/dialog.json` with the dialog on. Edited markdown is
    three-way merged, JSON policies key by key with a confirmation per key;
-   `delete?` proposals are left for you to confirm. The schema becomes 10.
+   `delete?` proposals are left for you to confirm. The schema becomes 10 with a 3.0 plugin, 11 with 3.1.
 5. **Decide two things the migrations cannot.** Keep the dialog (then amend
    constitution C5 as `0010` hints) or set `"enabled": false`; and tune the
    weight table — `domain.modules`, `customer_visible`, `hot_paths`,
    `needs_step`, `irreversible` — then `state.py weight --mirror`.
-6. **Verify**: `/rr-status` shows schema 10 and no task in flight; a
+6. **Verify**: `/rr-status` shows schema 11 and no task in flight; a
    `/rr-build` on a small change runs light and closes on the two facts.
    Commit `.ai/`.
 
-Every machine of a team upgrades the plugin before a project at schema 10 is
+Every machine of a team upgrades the plugin before a project at schema 11 is
 committed; an older plugin refuses such a project. Rollback and the full
 migration table are in [docs/project-update.md](docs/project-update.md); the
 home-side details in [docs/installation.md](docs/installation.md).
@@ -108,12 +120,12 @@ home-side details in [docs/installation.md](docs/installation.md).
 ## Install
 
 ```bash
-npx riskrails@3.0.1                       # detects Claude Code, Codex, or both; proposes the detected plan
-npx riskrails@3.0.1 --target codex        # auto | claude | codex | both
-npx riskrails@3.0.1 --plan max --fable no # pro | team-pro | team-max | max | max20 | balanced-max
-npx riskrails@3.0.1 --codex-plan plus     # plus | pro | balanced-max
-npx riskrails@3.0.1 --context economy     # the plan's compaction window; the context guard also blocks
-npx riskrails@3.0.1 --dry-run             # print what would be written, write nothing
+npx riskrails@3.1.0                       # detects Claude Code, Codex, or both; proposes the detected plan
+npx riskrails@3.1.0 --target codex        # auto | claude | codex | both
+npx riskrails@3.1.0 --plan max --fable no # pro | team-pro | team-max | max | max20 | balanced-max
+npx riskrails@3.1.0 --codex-plan plus     # plus | pro | balanced-max
+npx riskrails@3.1.0 --context economy     # the plan's compaction window; the context guard also blocks
+npx riskrails@3.1.0 --dry-run             # print what would be written, write nothing
 npx -y riskrails@latest --yes             # update in place, keeping the recorded plan
 ```
 
@@ -263,7 +275,7 @@ python3 -I -m unittest discover -s tests -p 'test_*.py'      # CI's serial oracl
 AI_E2E=1 python3 -I -m unittest discover -s tests -p test_end_to_end.py
 ```
 
-Fifty-six suites, 979 tests, about 75 seconds in parallel. The guards against JSON fixtures for both runtimes and a
+Fifty-nine suites, 1045 tests, about 75 seconds in parallel. The guards against JSON fixtures for both runtimes and a
 golden of 1 341 recorded decisions, byte for byte, with timed cases that hold
 the hot path under its budget; the state machine, the weight, the batch loop,
 the dialog contract and the documents rule; the compact record and its
@@ -293,6 +305,7 @@ the developer's real `~/.claude` or `~/.codex`.
 | [docs/local-memory.md](docs/local-memory.md) | the compact record: task ids, packages, recall, the pre-push check, migration |
 | [docs/known-risks.md](docs/known-risks.md) | what the guards do not protect against, and what to do about it |
 | [docs/faq.md](docs/faq.md) | why something was blocked, and how to change it |
+| [CHANGELOG.md](CHANGELOG.md) | what changed in each release, and the upgrade notes |
 | [docs/sdlc/README.md](docs/sdlc/README.md) | the spec → plan → build artefacts in a project |
 | [ROADMAP.md](ROADMAP.md) | what is decided but not built; the open rows |
 

package/ai/policies/model-routing.md

@@ -19,16 +19,16 @@ not settle — never for fact collection.
 
 Which model a tier is depends on the plan and the runtime: the installed profile
 decides it, `state.py profile --tier <TIER>` prints it for the runtime you are in,
-and `/ai-status` shows all four. This file names tiers only, so it is true on
+and `/rr-status` shows the plan's budget. This file names tiers only, so it is true on
 every plan.
 
 The main session runs the model the installed profile sets and does the
 implementation itself. Planning, the weight, the test run and the release are
 its work too, not an agent's: `/rr-plan`, `state.py weight`, `state.py verify`,
 `/rr-ship`. Which stages spawn an agent at all
-is decided by `pipeline_profile` in `risk-tiers.json`: in `solo`, T0–T4 run in
-direct mode — nothing on STRONG below T4, a BALANCED review at T2/T3 only when
-a sensor is red, one STRONG review at T4 — and tests run once
+is decided by the mode `state.py weight` gives: light runs direct — no review
+unless `close` reports a red fact — guarded has one BALANCED review, full one
+STRONG review, and nothing runs on STRONG below full — and tests run once
 after the last step, to the end, with every failure fixed as one batch.
 
 **Reading by difficulty.** A lookup — where X is, one route, service id, config
@@ -65,12 +65,12 @@ depends on a local model; if one becomes available it slots in at the FAST tier.
 
 ## EXPERT triggers
 
-1. The task is T6: migration, infrastructure, production architecture.
+1. The task is full and irreversible: migration, infrastructure, production architecture.
 2. STRONG could not settle it: `confidence: uncertain`, or two STRONG results
    contradict each other.
 3. An irreversible design with several viable options — core data model, public
    API or event contract, service split.
-4. The final check of a T6 plan or of a production-incident root cause before a
+4. The final check of a full-and-irreversible plan or of a production-incident root cause before a
    human acts on it.
 
 ## Escalation
@@ -104,7 +104,7 @@ the model `state.py profile --tier STRONG` printed — because a tier alone does
 cost or how much weight to give it. Report the model that **ran**, not the one
 that was requested: a gate may have sent an EXPERT agent down one tier during a
 rate limit, and a Codex agent file may have overridden the spawn-time model. Both
-runtimes expose the current state through `/ai-status`.
+runtimes expose the current state through `/rr-status`.
 
 ## What never gets delegated
 

package/ai/policies/production.md

@@ -7,8 +7,8 @@ is reached by a real customer until you have evidence it is not.
 
 1. Find the callers. `grep`/`rg` for the method, the service id, the route, the
    event name, the template.
-2. Find the tests that pin the current behaviour. If none exist and the tier is
-   T3 or above, write a characterization test **first** — one that passes against
+2. Find the tests that pin the current behaviour. If none exist and the mode is
+   guarded or full, write a characterization test **first** — one that passes against
    the code as it is today.
 3. Check the history for why it looks like this: `git log -L`, `git log -S`,
    `git blame`. A workaround with a ticket number in the message is a constraint,
@@ -37,6 +37,6 @@ named in the release report. "It worked locally" is not observability.
 
 ## Rollback
 
-Every T3+ change states how to undo it. If undoing it is impossible — a data
+Every guarded or full change states how to undo it. If undoing it is impossible — a data
 migration, an external system call, a fiscal record — say so plainly in the
 release report, because that changes who has to approve it.

package/ai/policies/release.md

@@ -29,7 +29,7 @@ It exists so that the human approving the change can see, in one page, what
 changed, what deliberately did not, what was tested, what was reviewed, what
 could go wrong, and how to undo it.
 
-A report that says "no known risks" for a T4 change is a report that was not
+A report that says "no known risks" for a guarded or full change is a report that was not
 written carefully.
 
 ## What blocks a release
@@ -38,7 +38,7 @@ written carefully.
   `focus: security` pass;
 - a new regression in the last `state.py verify` run;
 - a destructive database operation without its own named approval;
-- a T3+ change with no rollback section;
+- a guarded or full change with no rollback section;
 - an unanswered blocking question in the plan.
 
 ## Project specifics

package/ai/policies/review-economy.md

@@ -72,8 +72,8 @@ The ledger is what replaces agent memory. Without it, every pass is pass one.
 ## 3. Findings are fixed as one batch, and re-review is scoped, not repeated
 
 A review returns all its findings at once, and they are fixed at once: one
-`state.py remediate` step whose scope is the finished steps plus what the
-findings name, every BLOCKER and HIGH addressed in it, then the verification
+fix batch (`state.py start --amend` widens the task to the finished steps plus
+what the findings name), every BLOCKER and HIGH addressed in it, then the verification
 command once. Never one fix, one run, one re-review per finding — that is the
 serial loop the measurements below describe, and the remediation of one finding
 is where the next regression comes from.
@@ -98,13 +98,12 @@ shipped), each after a fix batch — before the same stop: the pass past that
 number is the human's. The reviewer's verdict says which closing rule applies:
 `blockers_open` (a BLOCKER) takes the remediation and the scoped re-review;
 `pass_with_findings` (a HIGH, no BLOCKER) takes the remediation and a green
-verification run, no re-review; `pass` closes. `state.py` has no value of its
-own for `pass_with_findings` yet: it is recorded as `blockers_open`, stays so
-after the green run, and the close summary names the labels that run closed.
+verification run, no re-review; `pass` closes. `state.py review --verdict`
+takes all three values.
 
-## 3a. The boundary of a direct-mode review
+## 3a. The boundary of a light or guarded review
 
-Below T5 the review is bounded. Its inputs are the task goal, the diff, the
+In light and guarded the review is bounded. Its inputs are the task goal, the diff, the
 tests the step names, and the project's own fixture corpus and threat model —
 `.ai/policies/safety.md`, the guards' `*-defaults.json`, the test fixtures.
 The reviewer works its whole list inside that corpus; what it may not do is
@@ -117,8 +116,8 @@ it only towards `yes`.
 
 A guard whose input is any shell line is a bottomless well for an unbounded
 reviewer: every pass finds a new input nobody will type, and every fix for one
-is the next pass's target. The boundary is what lets a review end. At T5 and
-T6 there is none — the reviewer's list applies unbounded, as the cost of being
+is the next pass's target. The boundary is what lets a review end. In full
+mode there is none — the reviewer's list applies unbounded, as the cost of being
 wrong there warrants.
 
 ## 4. Split one pass into parallel dimensions, not serial rounds
@@ -174,37 +173,35 @@ script, or run it yourself:
 A review pass spent on a self-contradictory risk register is a pass not spent on
 the code. When a task closes a gap that a register entry calls open, the entry is
 corrected **in the same step as the fix**, not later. When the plan gains a
-remediation, the plan gains a section — at T4 and above the artefact a human
+remediation, the plan gains a section — in guarded and full the artefact a human
 approves must describe the change that exists, and a diff wider than the plan is
 invisible to the path guard, because the file set never changed.
 
 ## 8. The one thing the sensors may replace
 
-At T3 and below, when every sensor in `risk-tiers.json` `required_for_skip` is
-green or explicitly not applicable **on the tree as it is now**, the model
-review is replaced by the sensor set and `state.py review-gate` records
-`review_status: skipped_green`. This is the intent's decision 6, and it is an
-exception to the rule below, written here so the two do not contradict each
-other.
+In light mode, when the two facts `close` measures are green **on the tree as
+it is now** — a green whole-suite `verify` and every changed file inside the
+task's files — the model review is replaced by the sensor set and the task
+closes without one. This is the intent's decision 6, and it is an exception to
+the rule below, written here so the two do not contradict each other.
 
 It is narrow on purpose. The skip requires that the suite passed on this exact
-tree, that the tests the plan named **fail without the change** (`bite` — a
-green suite that never reaches the diff is not evidence), that the diff is
-inside its budget — the budget is advisory for the tier, never for the skip —
-and that the tier re-scored from the real diff is still T3 or lower. A missing
-linter is not green: `unavailable` keeps the review, and only a human writing
-`lint_command: none` says the project has no linter. No
-sensor writes `skipped_green` by asserting it — `review-gate` reaches it from
-measurements, and `state.py set review_status skipped_green` is refused.
-
-From T4 the review always runs. What the sensors change there is where it
-starts: their rows are in the ledger, CONFIRMED, before the reviewer plans its
-work.
+tree, and that the tests the plan named **fail without the change** (`bite` — a
+green suite that never reaches the diff is not evidence). The mode is the one
+re-scored from the real diff: a diff that raises it to guarded or full keeps the
+review. A missing linter is not green: `unavailable` keeps the review, and only
+a human writing `lint_command: none` says the project has no linter. No
+sensor skips the review by asserting it — `close` reaches it from
+measurements.
+
+In guarded and full the review always runs. What the sensors change there is
+where it starts: their rows are in the ledger, CONFIRMED, before the reviewer
+plans its work.
 
 ## What this policy will not trade away
 
-- No review stage the tier requires is skipped, shortened, or merged — except
-  the T2/T3 model review, and only under §8's measured conditions.
+- No review stage the mode requires is skipped, shortened, or merged — except
+  the light-mode model review, and only under §8's measured conditions.
 - No reviewer is moved to a cheaper model to go faster. Narrow the surface, never
   the mind.
 - A blocker still returns to implementation, however late it arrives. Past the

package/bin/riskrails.js

@@ -1205,9 +1205,9 @@ function claudeSummary() {
     'Restart Claude Code, then:',
     '  /config        model and effort match the profile',
     `  /hooks         lists cap-large-read, ai-guard, project-scaffold and context-guard, plus runtime-gate on PreToolUse, PostToolUse, SubagentStart, SubagentStop${C.GATE === 'on' ? ' and StopFailure' : ''}`,
-    '  /skills        lists ai-init, ai-audit, ai-task, ai-status, project-init, sdlc-*, usage-report',
-    '  /ai-init       in a project, to survey it and build .ai/',
-    '  /project-update in a project that already has .ai/ or docs/sdlc/, to pull in these rules',
+    '  /skills        lists rr-setup, rr-spec, rr-plan, rr-build, rr-build-all, rr-review, rr-ship, rr-status',
+    '  /rr-setup      in a project, to survey it and build .ai/',
+    '  /rr-setup --update in a project that already has .ai/ or docs/sdlc/, to pull in these rules',
   ];
   out(lines.join('\n'));
 }
@@ -1411,8 +1411,8 @@ function codexSummary() {
     '',
     'Restart Codex, then:',
     '  /hooks         review and trust the guard, gate and context hooks — until you do, Codex skips them',
-    '  /skills        lists ai-init, ai-audit, ai-task, ai-status, project-init, sdlc-*, usage-report',
-    '  /ai-init       in a project, to survey it and build .ai/',
+    '  /skills        lists rr-setup, rr-spec, rr-plan, rr-build, rr-build-all, rr-review, rr-ship, rr-status',
+    '  /rr-setup      in a project, to survey it and build .ai/',
     '',
     `Your previous default model was replaced. backups/${BACKUP_DATE}/config.toml holds the old one.`,
   ].join('\n'));

package/hooks/context-guard.py

@@ -552,7 +552,7 @@ def task_frame(root, reason):
         tail.append(f"## Pending questions ({count}) — answer with `state.py answer …` "
                     "or fill the file")
         tail.append(prose or ids)
-    tail.append("Resume with: /ai-task --resume")
+    tail.append("Resume with: /rr-build --resume")
     if len("\n".join([head] + tail)) > HANDOFF_INJECT_MAX_CHARS and len(tail) > 1:
         tail[1] = ids                     # the questions collapse to their ids
     return head[:HANDOFF_INJECT_MAX_CHARS], "\n".join(tail)

package/hooks/guard/common.py

@@ -165,6 +165,8 @@ _WS = " \t\n\r"
 def parse_stream(text):
     """(values, ok): every JSON value of a jq input stream, and False when a
     parse error ended it (the values before the error are kept)."""
+    if text.startswith("\ufeff"):                  # jq skips one leading UTF-8 BOM
+        text = text[1:]
     values, i, n = [], 0, len(text)
     while True:
         while i < n and text[i] in _WS:

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,22 +81,36 @@ 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, with the dialog on only: the other human-only state.py commands —
-# `profile set` and the --by forms of verify, review and reject — run from an
-# agent session only as the next live pick, like approve. `start --mode --by`
-# reaches state.py: raising a mode needs no human, and a lowering opens its own
-# decision there before human_route() refuses it (review H1, T-2026-10-28-010).
+# 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)
-HUMAN_BY_VERB = ("([[:space:]]+--)?[[:space:]]+" + Q + "(verify|review|reject)" + END + "([^|;&`]*[[:space:]])?"
-                 + Q + "--by?" + Q + "(=|[[:space:]]|$)")
-HUMAN_BY_RE = (BOUND + "(python3?[[:space:]]+)?" + Q + "[^[:space:]'\"]*state\\.py" + Q + ARGS + HUMAN_BY_VERB + "|"
-               + BOUND + "(python3?[[:space:]]+)?" + Q + VAR + Q + ARGS + HUMAN_BY_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"
@@ -137,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:]]+"
@@ -1255,14 +1266,14 @@ class PathGuard:                            # pylint: disable=too-many-instance-
         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 on and not picked and not unattended:
-            if m.ere_match(PROFILE_SET_RE, cmd_joined):
-                raise Deny("Refusing 'state.py profile set' from an agent session." + WHY_PICK)
-            if m.ere_match(HUMAN_BY_RE, cmd_joined):
-                raise Deny(T("Refusing a 'state.py … --by' verdict from an agent session.") + WHY_PICK)
-        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/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
@@ -415,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."
             ),
@@ -801,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)

package/hooks/update_notice.py

@@ -28,6 +28,7 @@ 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
 
@@ -103,20 +104,7 @@ def notice(runtime, home, plugin_root, now):
     return message, context
 
 
-def refresh(path):
-    """Ask the registry and write the cache; on failure only move checked_at."""
-    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().decode("utf-8")).get("version")
-        if parse(version):
-            latest = version
-    except (OSError, ValueError, AttributeError):
-        pass
-    if latest is None:
-        previous = read_cache(path).get("latest")
-        latest = previous if isinstance(previous, str) else None
+def write_cache(path, latest):
     tmp = f"{path}.{os.getpid()}.tmp"
     try:
         with open(tmp, "w", encoding="utf-8") as fh:
@@ -129,6 +117,24 @@ def refresh(path):
             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])

package/instructions/routing.md

@@ -46,7 +46,7 @@ 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 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.
+- `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 -->