riskrails 3.0.1 → 3.1.0

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.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/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/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/sensors.py

@@ -135,8 +135,10 @@ def snapshot_tree(root):
 def numstat(root, from_tree, to_tree):
     """[{path, added, deleted, binary}] between two trees, NUL-separated so a
     path with a space, a quote or a newline survives. Renames are off: a rename
-    is an add plus a delete, as diff_files reports it."""
-    code, out = git(root, ["diff", "--numstat", "--no-renames", "-z",
+    is an add plus a delete, as diff_files reports it. --relative (git runs in
+    root): paths are relative to the project root, as task files and policy globs
+    are, and a change outside root, below the git top level, is left out."""
+    code, out = git(root, ["diff", "--relative", "--numstat", "--no-renames", "-z",
                            from_tree, to_tree])
     if code != 0:
         return None
@@ -170,7 +172,8 @@ def diff_files(root, from_tree, to_tree):
     None when either tree is missing: an unmeasured diff is not an empty one."""
     if not from_tree or not to_tree:
         return None
-    code, out = git(root, ["diff", "--name-status", "--no-renames", "-z", from_tree, to_tree])
+    code, out = git(root, ["diff", "--relative", "--name-status", "--no-renames", "-z",
+                           from_tree, to_tree])
     if code != 0:
         return None
     fields = [f for f in out.split("\0") if f != ""]
@@ -202,7 +205,8 @@ def scope_any(path, patterns):
 # ------------------------------------------------------------------- running
 
 TESTING_FIELDS = ("verify_command", "step_test_command", "e2e_command",
-                  "lint_command", "typecheck_command", "single_test", "doc_tests")
+                  "lint_command", "typecheck_command", "single_test", "doc_tests",
+                  "bite_codes")
 
 SCOPE_FIELD = {"suite": "verify_command", "step": "step_test_command",
                "e2e": "e2e_command", "single": "single_test"}
@@ -232,10 +236,26 @@ def read_commands(root):
         value = match.group(1).strip()
         if value.startswith("#"):
             value = ""
+        # A trailing `  # comment` is not part of `none` or of the code list; a
+        # command value is left exactly as written (a `#` can be part of it).
+        bare = re.sub(r"\s+#.*$", "", value)
+        if field == "bite_codes" or bare.lower() == "none":
+            value = bare
         commands[field] = value
     return commands
 
 
+def bite_codes(root):
+    """The exit codes that count as "the test fails" under --expect fail: the
+    testing.md `bite_codes` list of integers, 1 when absent or not a clean list."""
+    raw = read_commands(root).get("bite_codes", "")
+    try:
+        codes = tuple(int(part) for part in raw.split(","))
+    except ValueError:
+        return (1,)
+    return codes or (1,)
+
+
 def command_for(root, scope):
     return (read_commands(root).get(SCOPE_FIELD.get(scope, ""), "") or "").strip()
 

package/skills/ai-task/state.py

@@ -194,7 +194,7 @@ def find_root(start):
             return d
         parent = os.path.dirname(d)
         if parent == d:
-            die("no .ai/ directory found above %s — run /ai-init first" % start)
+            die("no .ai/ directory found above %s — run /rr-setup first" % start)
         d = parent
 
 
@@ -405,7 +405,7 @@ def claim_runtime(root, state):
                     "state.py --runtime %s handoff --to %s (this shell is neither runtime; "
                     "name the one taking it)" % ((other_runtime(pending),) * 2))
             die("RUNTIME_HANDOFF_PENDING: task %s was handed to %s at %s. Resume it there "
-                "(/ai-task), or take it back here with: %s"
+                "(/rr-build), or take it back here with: %s"
                 % (state.get("task_id"), pending, state["handoff"].get("pending_since"), back), 7)
         # The receiving runtime's first change: the handoff is complete. The
         # move itself was journaled when it was made, so there is no second event.
@@ -1120,7 +1120,8 @@ def cmd_event(args, root):
             die("--data must be a JSON object")
     state = load(root)
     append_journal(root, state["task_id"], journal_line(
-        state["task_id"], args.type, "hook", state.get("current_stage"), args.detail, data))
+        state["task_id"], args.type, "agent" if args.type == "note" else "hook",
+        state.get("current_stage"), args.detail, data))
     print("%s recorded" % args.type)
 
 
@@ -1134,7 +1135,7 @@ def find_docs_root(start):
             return d
         parent = os.path.dirname(d)
         if parent == d:
-            die("no docs/sdlc/ directory found above %s — run /sdlc-intent first" % start)
+            die("no docs/sdlc/ directory found above %s — run /rr-spec first" % start)
         d = parent
 
 
@@ -1863,7 +1864,7 @@ def handoff_lines(root, state, reason):
     pending_to = (state.get("handoff") or {}).get("pending_to")
     if pending_to:
         review = state.get("cross_vendor_review") or {}
-        out.append("Handed to %s at %s%s — resume there with /ai-task" % (
+        out.append("Handed to %s at %s%s — resume there with /rr-build" % (
             pending_to, (state.get("handoff") or {}).get("pending_since"),
             " for the cross-vendor review" if review.get("status") == "requested" else ""))
     advice = advisory_line(state)
@@ -1967,7 +1968,7 @@ def handoff_to(args, root):
     emit(root, state, "runtime_handoff", "%s -> %s (%s)" % (source, args.to, via), data)
     write_handoff(root, state, "manual")
     save(root, state)
-    print("Handed %s to %s (%s). In %s, run /ai-task: it resumes from the state file in .ai/state/."
+    print("Handed %s to %s (%s). In %s, run /rr-build: it resumes from the state file in .ai/state/."
           % (state.get("task_id"), args.to, via, args.to))
     print("headless (not run): cd %s && %s" % (shlex.quote(root), RESUME_COMMAND[args.to]))
 
@@ -3251,7 +3252,10 @@ def rescore_weight(root, base_tree, files, current, policy):
                 if line is not None:
                     # The operation's keyword (DROP, ALTER …), not the pattern's
                     # source: it is what a human names in approve --confirm.
-                    operations.append(rx.search(line).group(0).split()[0].upper())
+                    # The first word of the match; a match of only blanks or punctuation
+                    # is named IRREVERSIBLE, never an IndexError.
+                    word = re.search(r"[A-Za-z]+", rx.search(line).group(0))
+                    operations.append(word.group(0).upper() if word else "IRREVERSIBLE")
                     if found.get("reversibility", (0,))[0] < 2:
                         found["reversibility"] = (2, "%s adds %r (irreversible_content %r)"
                                                   % (rel, line.strip()[:60], pattern))
@@ -3483,7 +3487,8 @@ def cmd_start(args, root):
     check_steps(steps, implied)
     concrete = [f for f in files if not any(c in f for c in "*?[")]
     try:
-        result = weigh(root, concrete, parse_declares(args.declare), args.goal, policy)
+        result = weigh(root, concrete, parse_declares(args.declare), args.goal, policy,
+                       [f for f in files if f not in concrete])
     except ValueError as exc:
         die(str(exc))
     except (TypeError, AttributeError) as exc:
@@ -3674,18 +3679,21 @@ def is_document(path, policy):
 DOCUMENTS_ZEROED = ("behaviour", "domain", "novelty")
 
 
-def weigh(root, files, declared, goal, policy):
+def weigh(root, files, declared, goal, policy, globs=()):
     """weight.compute, plus the documents rule (faster-task-cycle (c), in state.py because
     weight.py is at its line cap). Predicate P: at least one concrete file, every file a
     document (is_document) or a test, at least one a document. When P holds, file text no
     longer scores behaviour (the goal's keyword still does, exactly as in compute), and
     behaviour, domain and novelty still UNKNOWN become 0 with the evidence "documents only"; hints and
     declarations were applied inside compute. `documents_only` is {"zeroed": {axis: what it
-    would have scored}}, None when P does not hold or the policy has no `documents` key."""
+    would have scored}}, None when P does not hold or the policy has no `documents` key.
+    `globs` are the task's glob entries, which score nothing themselves: P fails when one is
+    not itself a document or test glob."""
     concrete = [posixpath.normpath(f.strip().replace(os.sep, "/")) for f in files if f.strip()]
     tests = ((policy.get("axes") or {}).get("coverage") or {}).get("test_globs")
     inside = all(not f.startswith(("/", "../")) and f != ".." for f in concrete)
-    if not (inside and any(is_document(f, policy) for f in concrete)
+    if not (inside and all(is_document(g, policy) or weight.match(g, tests) for g in globs)
+            and any(is_document(f, policy) for f in concrete)
             and all(is_document(f, policy) or weight.match(f, tests) for f in concrete)):
         result = weight.compute(root, files, declared, goal, policy=policy)
         result.documents_only = None
@@ -3722,6 +3730,9 @@ def documents_cover(root, state, policy, tree):
     g = runs[-1] if runs else None
     if not g or g["exit"] != 0 or any(r["tree"] == g["tree"] and r["exit"] != 0 for r in runs):
         return off                                                              # D2
+    # A full-suite run after G that is not green stops the rule, whatever its tree (it may be None).
+    if any(full_suite(r) and r["n"] > g["n"] and r.get("exit") != 0 for r in state["verify"]["runs"]):
+        return off
     diff = safe_sensor(sensors.diff_files, root, g["tree"], tree)
     if not diff or not all(is_document(d["path"], policy) for d in diff):
         return off                                                              # D3, D4
@@ -3891,7 +3902,9 @@ def cmd_verify(args, root):
         run = run_v7(root, state, "suite" if scope == "all" else scope, args, tcfg)
         code = run["exit"]
         if args.expect == "fail":
-            run["bites"] = code not in (0, None)
+            # exit 1 is a failing test; the runner's own usage error (2) is not, unless
+            # testing.md's bite_codes names it (pytest 1,2 — 2 is a collection error)
+            run["bites"] = code in (safe_sensor(sensors.bite_codes, root) or (1,))
             print("expected fail: %s" % ("the test fails without the fix — it bites" if run["bites"]
                                          else "the test passes without the fix — it does not bite yet"))
             code = 0 if run["bites"] else 1
@@ -4299,9 +4312,11 @@ def archive_v7(root, state, tree, result, facts=None):
     ensure_logs(root, state["task_id"])
     target = os.path.join(logs_dir(root, state["task_id"]), "state.json")
     state["updated_at"] = now()
-    with open(target, "w", encoding="utf-8") as fh:
+    tmp = "%s.%d.tmp" % (target, os.getpid())
+    with open(tmp, "w", encoding="utf-8") as fh:
         json.dump(state, fh, indent=2, ensure_ascii=False)
         fh.write("\n")
+    os.replace(tmp, target)
     with contextlib.suppress(OSError):
         os.remove(handoff_path(root))
     remove_state(root)
@@ -4461,6 +4476,12 @@ def status_lines(root, state):
     events, _ = read_journal(root, state["task_id"])
     last = events[-1] if events else {}
     pending = (state.get("questions") or {}).get("pending") or []
+    if is_v7(state):
+        # The cache lags a hand-filled [Answer]:; the file is the truth, as guard_pending reads it.
+        with contextlib.suppress(OSError, ValueError, KeyError):
+            _, asked = parse_questions(questions_path(root, state, None))
+            gate_id = open_gate(state)
+            pending = [q["id"] for q in asked if (q["kind"] != "G" and is_pending(q)) or q["id"] == gate_id]
     lines.append("task: %s — %s" % (state["task_id"], one_line(state.get("goal"), 140)))
     if not is_v7(state):
         lines += ["tier: %s · workflow %s · stage %s" % (state.get("risk_tier") or "?", state.get("workflow"),
@@ -4684,9 +4705,11 @@ def abandon_old(_args, root):
     ensure_logs(root, state["task_id"])
     target = os.path.join(logs_dir(root, state["task_id"]), "state.json")
     state["updated_at"] = now()
-    with open(target, "w", encoding="utf-8") as fh:
+    tmp = "%s.%d.tmp" % (target, os.getpid())
+    with open(tmp, "w", encoding="utf-8") as fh:
         json.dump(state, fh, indent=2, ensure_ascii=False)
         fh.write("\n")
+    os.replace(tmp, target)
     with contextlib.suppress(OSError):
         os.remove(handoff_path(root))
     remove_state(root)

package/skills/project-init/templates/constitution.md

@@ -7,7 +7,7 @@ C1. Production behaviour is the source of truth; what looks wrong may be load-be
 C2. A bugfix starts with the failing test; legacy behaviour gets a characterization test before it changes.
 C3. A refactoring changes no behaviour and is never mixed with a feature.
 C4. Every step names its files; scope grows only by amending the plan.
-C5. No agent merges or deploys; an agent commits, pushes or approves only by running, verbatim and once, a command a human picked in the dialog; otherwise a human runs it outside the agent.
+C5. No agent merges or deploys; an agent commits, pushes or approves only by running, verbatim and once, a command a human picked in the dialog, as the harness recorded; else a human runs it outside.
 C6. <!-- project principle — filled by /ai-init from the survey, confirmed by you -->
 C7. <!-- project principle -->
 C8. <!-- project principle -->

package/skills/project-init/templates/sdlc-README.md

@@ -1,24 +1,30 @@
 # SDLC artefacts
 
-Feature work in this repo follows the AI-Native SDLC flow: **intent → spec → plan → build**.
-Each stage has a skill that produces one file here, and the next stage reads it.
+Work that needs a written intent and design before any code follows
+**spec → plan → build**. Each stage has a skill that produces one file here,
+and the next stage reads it.
 
 ```
- /sdlc-intent <topic>        →  docs/sdlc/intent/<slug>.md   (problem, outcome, constraints)
+ /rr-spec <idea | intent/<slug>.md>  →  docs/sdlc/specs/<slug>.md    (## Intent, requirements, design, Flagged concerns)
+        │                               docs/sdlc/intent/<slug>.questions.md  (the brainstorm, recorded by state.py)
+ /rr-plan specs/<slug>.md            →  docs/sdlc/plans/<slug>.md    (files that change, order, risks, proof, rollback)
         │
- /sdlc-spec  intent/<slug>.md →  docs/sdlc/specs/<slug>.md    (requirements, design, flagged concerns)
-        │
- /sdlc-plan  specs/<slug>.md  →  docs/sdlc/plans/<slug>.md    (files, order, risks, proof)
-        │
-      build (main session, one plan step at a time; `ai-reviewer` before commit)
+ /rr-build  — one row at a time (each row is one task, weighed and started by /rr-plan)
+ /rr-build-all plans/<slug>.md — the whole plan as one task: parallel implementers, one review loop
 ```
 
 | Folder | Produced by | Contains |
 |---|---|---|
-| `intent/` | `/sdlc-intent` | one file per idea; what and why, not how |
-| `specs/` | `/sdlc-spec` | requirements + design; ends with **Flagged concerns** |
-| `plans/` | `/sdlc-plan` | ordered implementation steps with verification |
-| `adr/` | you / `architect` | Architecture Decision Records (MADR style) |
+| `intent/` | `/rr-spec`'s brainstorm (`state.py ask --topic`) | `<slug>.questions.md`, one question at a time with the answer on record; an `intent/<slug>.md` written by hand is accepted instead of the brainstorm |
+| `specs/` | `/rr-spec`, `architect` on STRONG | `## Intent` (problem, outcome, affected users and systems, constraints, decisions taken), requirements, design; ends with **Flagged concerns**, which a human resolves or accepts before planning |
+| `plans/` | `/rr-plan` | Files that change / Order of work / Risks / Proof (every requirement to a test or command) / Rollback; each row carries its files and its *Consumes* line |
+| `adr/` | you, or `architect` | Architecture Decision Records (MADR style) |
+| `constitution.md` | `/rr-setup`, then you | the principles the project does not negotiate, cited as `C<n>` in specs, plans and reviews; at most 15 lines |
 
-Each folder holds a `TEMPLATE.md`; the skills copy it and fill it in. Commit the artefacts with the
-code they describe so the reasoning survives the pull request.
+The skills fill in the plugin's templates
+(`$AI_HOME/skills/project-init/templates/{intent,spec,plan,adr}.md`, in the
+installed plugin); to override one, copy it to `docs/sdlc/<folder>/TEMPLATE.md`
+and edit it — the skills read that one first. Commit the artefacts with the code they describe, so the
+reasoning survives the pull request. A task's own record — weight, plan, questions, verify runs, review,
+verdict — is not here but in `.ai/reports/<task-id>/task.md`, written by
+`state.py`.

package/skills/project-update/history/blobs/00289f98434fed230eebe768dfb3425f83d737866a3aebc97aa95167c4fa0c6e

@@ -0,0 +1,131 @@
+# Testing policy
+
+Tests describe behaviour. Coverage percentage is a side effect, not a goal.
+
+## Characterization first
+
+Before changing behaviour that is not covered by a test — which is most legacy
+behaviour — write a test that passes against the code **as it is today**. That
+test is the definition of what must not break. Only then change the code.
+
+```
+characterization test → refactor → verify identical behaviour → feature change
+```
+
+Never do those in one step, and never in one commit.
+
+## What to consider, by kind of change
+
+| Change touches | Also test |
+|---|---|
+| a shared service | the existing callers, not only the new one |
+| money, tax, fiscal | rounding, currency, negative and zero amounts, refunds |
+| a state machine | every transition that is now reachable, and the ones that must stay unreachable |
+| an async consumer | retry, double delivery, out-of-order delivery, poison message |
+| an external integration | timeout, 500, malformed response, partial write |
+| a write path | idempotency, concurrency, transaction boundaries |
+| authorization | the negative case, for every role |
+| a public API or event | the old shape still works |
+
+## Three scopes, three moments
+
+A task runs tests three times at most, and each run has its own scope. Nothing
+else runs in between.
+
+| When | What runs | Command |
+|---|---|---|
+| after each implementation step, before `step-done` | **only the tests the plan named for that step** — the files it touched, their direct callers' tests | `step_test_command` |
+| once, after the **last** step | the full fast suite — unit and integration, no e2e | `verify_command` |
+| once, at the **end of the task**, after the full suite is green | the end-to-end suite | `e2e_command` |
+
+- A step never runs the full suite, and **never** runs e2e. If the plan named
+  no test for a step, nothing runs for it.
+- A step's tests are scoped by path or filter, not by `--stop-on-failure`: the
+  scoped run still goes to the end, and its failures are fixed inside that step.
+- The e2e suite runs **once per task**, at the very end, never per step. Skip it
+  at T0/T1, and when the change cannot reach a flow the e2e suite covers — say
+  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 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.
+
+Classify before fixing. The four answers are:
+
+- **EXISTING TEST FAILURE** — it failed before this change too. Say so, do not
+  fix it inside this task.
+- **NEW REGRESSION** — this change broke it. Fix the code, not the test.
+- **TEST ENVIRONMENT FAILURE** — database, fixtures, network, container. Say what
+  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.
+
+## Verification
+
+Three commands, one per scope. `verify_command` proves the project is healthy;
+`step_test_command` proves one step is; `e2e_command` proves the whole flow
+still works. Keep each to one command — chain the pieces in a Makefile or
+composer script if there are several — and make sure none of them stops at the
+first failure (`--stop-on-failure`, `-x`, `--bail`, `failfast` are off).
+
+`verify_command` must **exclude** the e2e suite: it is the fast loop run after
+the last step and again after a remediation batch. `e2e_command` runs once, at
+the end of the task. A bugfix still shows its new failing test first — that one
+test only, through `single_test`.
+
+```
+verify_command:      # the full fast suite, e2e excluded — e.g. make test   |   composer qa && vendor/bin/phpunit --exclude-group e2e
+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
+single_test:         # how to run one test, for the failing-test-first step of a bugfix
+```
+
+`step_test_command` may contain `{files}`, which is replaced by the paths the
+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 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. 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
+for it. Say which group, tag or directory marks the e2e tests and how
+`verify_command` excludes them, so a step's scoped run and the fast suite stay
+free of them.
+
+## Project specifics
+
+<!-- The real commands: how to run unit tests, integration tests, a single test.
+     Where fixtures live. What the CI runs. Cite the config. -->