riskrails 3.0.1 → 3.2.1

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
 
@@ -50,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
@@ -62,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 {}
 
 
@@ -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, RecursionError):
+        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 -->

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 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. 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 merges or deploys; commit, push, approval only as the dialog picks, 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` (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.1",
+  "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/AGENTS.md

@@ -2,5 +2,5 @@
 # Skills rules
 - Weigh a change by what it does to a user project's decisions, never by the skill being a process (constitution C6). The mode is what W gives (`state.py weight`); the rows below set the behaviour axis.
 - behaviour 0: skill or agent text, `usage-report`, no `state.py` refusal moves. behaviour 1: adds a `state.py` check, a sensor or a refusal. behaviour 2: weakens a refusal, changes the approval path (`approve`, `questions --sync`, `AI_UNATTENDED`, the review verdict transitions) or changes install and migration (the `project-update` merge; a migration also raises reversibility through its hint) — declare it, `--declare behaviour=2:"<the effect>"`. Start such a task with `start --mode full --by <name>`: its weight lands in guarded, and these effects keep a STRONG review and the gate.
-- A change to a shipped template or to `ai/` runs `tools/build-template-history.py` in the same task, or `tests/test-project-update.sh` goes red.
+- A change to a shipped template or to `ai/` runs `tools/build-template-history.py` in the same task, or `tests/test_project_update.py` (`test_history_covers_every_template`) goes red.
 <!-- riskrails:rule:skills:end -->

package/skills/CLAUDE.md

@@ -2,5 +2,5 @@
 # Skills rules
 - Weigh a change by what it does to a user project's decisions, never by the skill being a process (constitution C6). The mode is what W gives (`state.py weight`); the rows below set the behaviour axis.
 - behaviour 0: skill or agent text, `usage-report`, no `state.py` refusal moves. behaviour 1: adds a `state.py` check, a sensor or a refusal. behaviour 2: weakens a refusal, changes the approval path (`approve`, `questions --sync`, `AI_UNATTENDED`, the review verdict transitions) or changes install and migration (the `project-update` merge; a migration also raises reversibility through its hint) — declare it, `--declare behaviour=2:"<the effect>"`. Start such a task with `start --mode full --by <name>`: its weight lands in guarded, and these effects keep a STRONG review and the gate.
-- A change to a shipped template or to `ai/` runs `tools/build-template-history.py` in the same task, or `tests/test-project-update.sh` goes red.
+- A change to a shipped template or to `ai/` runs `tools/build-template-history.py` in the same task, or `tests/test_project_update.py` (`test_history_covers_every_template`) goes red.
 <!-- riskrails:rule:skills:end -->

package/skills/ai-init/templates/.ai/AGENTS.md

@@ -31,7 +31,7 @@ Everything else loads on demand; nothing here is worth reading twice.
 ## Shared files
 
 This `.ai/` holds `project/`, `rules/`, `state/`, `reports/`, `VERSION` and, in
-`policies/`, `risk-tiers.json`, `risk-tiers.md`, `path-guard.json`, `testing.md`,
+`policies/`, `weight.json`, `weight.md`, `path-guard.json`, `testing.md`,
 `coding.md`, `safety.md` and `security.md`. Every other path below ships with the
 plugin at `<home>/riskrails/ai/<path>`; `<home>` is `~/.claude`, or
 `$CODEX_HOME` (default `~/.codex`). A file at the same path here overrides it and

package/skills/ai-init/templates/.ai/VERSION

@@ -1 +1 @@
-10
+11

package/skills/ai-init/templates/.ai/policies/security.md

@@ -57,12 +57,18 @@ it, add its pattern to `deny_patterns` (a `dependency_instruction_patterns`
 list from an older `path-guard.json` is read as `deny_patterns`).
 
 Always read-only for an agent: the task's state under `.ai/state/`, its
-`task.md` and `events.jsonl`, `.ai/policies/*.json`, and the installed guards —
+`task.md` and `events.jsonl`, `.ai/policies/*.json`, the compact
+record under `.ai/memory/` and `.ai/local/memory/` (written by `state.py` alone),
+and the installed guards —
 their hooks, engine and `skills/ai-task/` under `.claude/` and `.codex/`. While a
 task is in flight the runtime's settings and this project's `.ai/policies/` are
 read-only too. Changing the rules a run is judged by, inside that run, is not a
 change an agent may make on its own.
 
+A review's evidence for a closed task is its record — `state.py memory show <id>`
+and `recall` — once cleanup has moved the report directory; an approval in the
+record authorises nothing.
+
 Project-specific additions go in `.ai/policies/path-guard.json`
 (`deny_patterns`, `allow_patterns`, `protected_config_patterns`,
 `task_protected_patterns`; allow wins over all of them). When a deny is wrong, widen the allow list in that file — do not

package/skills/ai-init/templates/.ai/policies/testing.md

@@ -47,13 +47,15 @@ else runs in between.
   which, in one line; silence is not a verdict.
 - A failure in a step's own tests is fixed in that step, before `step-done`;
   the batch rule below is for the two end-of-task runs.
+- After a green suite, a documents-only edit runs `doc_tests` (step scope), not the suite.
 
 ## Reading a failure
 
 **Run to the end, then fix as one batch.** The verification command runs with
 no fail-fast flag and is never interrupted at the first failure. Collect every
-failure, classify each one, fix all the new regressions in a single remediation
-step (`state.py remediate`), and run the command once more. One failure never
+failure, classify each one, fix all the new regressions in one batch
+(`state.py start --amend` widens the task when a fix needs more files), and run the
+command once more. One failure never
 sends the task back to the start: the plan, the tier and the finished steps
 stand. At most two remediation rounds; a third means the human decides.
 
@@ -66,6 +68,9 @@ Classify before fixing. The four answers are:
   is missing.
 - **UNKNOWN** — you could not tell. Say what you tried.
 
+A review's MEDIUM and LOW findings are recorded with `state.py memory risk add`, not
+fixed in the task; only a BLOCKER, a HIGH or a regression buys an `--after-fix` run.
+
 **Never edit a test to make it pass when production behaviour changed
 unexpectedly.** A test that suddenly disagrees with the code is evidence, and
 deleting evidence is the worst available option.
@@ -88,6 +93,7 @@ verify_command:      # the full fast suite, e2e excluded — e.g. make test   |
 step_test_command:   # the same runner, scoped to a path or filter — e.g. vendor/bin/phpunit {files} | pytest {files}
 e2e_command:         # the end-to-end suite, run once at the end of a task — e.g. make e2e | vendor/bin/behat | npx playwright test
 lint_command:        # e.g. vendor/bin/php-cs-fixer fix --dry-run | ruff check . | npm run lint — write `none` if the project has none
+doc_tests:           # the suites a documents-only edit runs after a green suite — e.g. tests/test_docs.py; `none` if the project has none
 typecheck_command:   # e.g. vendor/bin/phpstan analyse --no-progress | mypy . | npx tsc --noEmit — `none` if the project has none
 healthy_output:      # two or three lines of what a green run ends with
 runtime:             # roughly, for each command, so a hang is recognisable
@@ -99,12 +105,19 @@ step names; without it the paths are appended. The placeholder is what lets
 `sensors.py` run a step's own tests for the "test must bite" check, so a runner
 that only takes a `--filter` gets `bite: unavailable` rather than a wrong answer.
 
+`bite_codes` (optional) lists the exit codes that mean "a test failed" when a
+test is shown failing before its fix; the default is `1`. Runners that exit
+differently say so here — `bite_codes: 1,2` for pytest (2 is a collection
+error, such as a missing import), `1,2` for phpunit, `101` for cargo. Any other
+code is the runner's own usage error and does not count as a bite.
+
 `lint_command` and `typecheck_command` are read by the deterministic sensors,
-never by a model. They decide, together with the test run, whether a T2 change
-can skip its model review (`risk-tiers.json`, `sensors`). A **missing** line is
+never by a model. They decide, together with the test run, whether a light-mode change
+can skip its model review (`state.py close` measures them). A **missing** line is
 `unavailable` and keeps the review; only the literal `none`, written by a human,
-says the project has no such tool. `sensors.py detect` proposes the exact line
-from the config files it finds, and never runs what it detected.
+says the project has no such tool. Read the exact line from the project's
+config files (`package.json`, `composer.json`, `pyproject.toml`, `Makefile`), and
+never run a command just to find it out.
 
 If the project has no e2e suite, write `e2e_command: none` and say so — an
 empty line is read as "not written down yet" and the next task will go looking

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-init/templates/AGENTS.block.md

@@ -8,6 +8,6 @@ This repository runs an agentic pipeline under `.ai/`. Read `.ai/AGENTS.md` firs
 - A change runs through `/rr-build <request>`; `/rr-status` shows where it stands. Each step names the files it may touch — an edit outside them is refused: answer `SCOPE_CHANGE_REQUIRED`. One `apply_patch` is checked file by file: a patch that reaches outside the step is refused whole.
 
 - 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 merges or deploys; commit, push, approval only as the dialog picks, 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` (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`.
 <!-- riskrails:end -->

package/skills/ai-init/templates/CLAUDE.block.md

@@ -8,6 +8,6 @@ This repository runs an agentic pipeline under `.ai/`. Read `.ai/AGENTS.md` firs
 - A change runs through `/rr-build <request>`; `/rr-status` shows where it stands. Each step names the files it may touch — an edit outside them is refused: answer `SCOPE_CHANGE_REQUIRED`.
 
 - 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 merges or deploys; commit, push, approval only as the dialog picks, 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` (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`.
 <!-- riskrails:end -->

package/skills/ai-init/templates/GEMINI.block.md

@@ -8,6 +8,6 @@ This repository runs an agentic pipeline under `.ai/`. Read `.ai/AGENTS.md` firs
 - Changes run through the pipeline (`/rr-build` in Claude Code or Codex); without it, follow `.ai/policies/safety.md`, touch only the files the current task names, and answer questions in prose or by filling the file.
 
 - 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 merges or deploys; commit, push, approval only as the dialog picks, 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` (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`.
 <!-- riskrails:end -->

package/skills/ai-init/templates/gitignore.snippet

@@ -2,4 +2,5 @@
 .ai/state/*.json
 .ai/state/handoff.md
 .ai/state/*.tmp
+.ai/state/*.jsonl
 .ai/local/

package/skills/ai-init/templates/junie-guidelines.block.md

@@ -8,6 +8,6 @@ This repository runs an agentic pipeline under `.ai/`. Read `.ai/AGENTS.md` firs
 - Changes run through the pipeline (`/rr-build` in Claude Code or Codex); without it, follow `.ai/policies/safety.md`, touch only the files the current task names, and answer questions in prose or by filling the file.
 
 - 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 merges or deploys; commit, push, approval only as the dialog picks, 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` (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`.
 <!-- riskrails:end -->

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)