riskrails 3.0.0 → 3.1.0

package/skills/rr-build/SKILL.md

@@ -38,6 +38,8 @@ $STATE handoff --print
   Trust it over a compaction summary; it is rendered from the state. If
   `$ARGUMENTS` asks for something else, say what is in flight and ask whether to
   finish it, or drop it with `$STATE close --abandon`. Never discard it silently.
+  A handoff line `Batch: on` means the task runs the loop of `/rr-build-all` —
+  parallel implementers and fixers, its own budgets — continue there.
 - **`Handed to <the other runtime>`:** every state change exits 7 until that
   runtime resumes it. Say where to resume; take it back with
   `$STATE handoff --to <this runtime>` only when asked. `Handed to <this
@@ -47,6 +49,11 @@ $STATE handoff --print
 
 ## 2. Edit, inside the task
 
+Before the first edit, recall what the record already holds about the task's
+files — open risks, residual findings, decisions and why, within a token budget,
+read-only: `$STATE recall --files "<the task's files>"` (`memory show <id>` for
+one task in full).
+
 Implement it yourself. The scope guard refuses an edit to a file the task does
 not name. That refusal is the plan being enforced, not an obstacle:
 
@@ -56,8 +63,9 @@ $STATE start --amend --files "+<path>" --why "<why the task needs it>"
 ```
 
 The amendment is journaled; the task is not re-planned. A file that belongs to
-a different change is not amended in — it is written into
-`.ai/project/known-risks.md` and left for its own task.
+a different change is not amended in — it is recorded with `$STATE memory risk
+add --title … --where "file:line" --label RISK --what …` (in files mode that
+writes `.ai/project/known-risks.md`) and left for its own task.
 
 Production behaviour is the source of truth: code that looks wrong may be
 load-bearing. Change only what the task asked for; a refactoring never rides
@@ -94,7 +102,7 @@ at `close` is finished by `close`.
 
 ## 4. Verify once, to the end
 
-After the last edit:
+After the last edit (after the last step: `$STATE step-done <id> && $STATE verify --scope all`):
 
 ```bash
 $STATE verify --scope all
@@ -118,10 +126,11 @@ fixed:
 $STATE verify --scope all --after-fix "<n> regressions: <one line each>"
 ```
 
-- An existing failure is recorded in `.ai/project/known-risks.md`, not fixed.
+- An existing failure is recorded with `$STATE memory risk add`, not fixed.
 - An environment failure gets one more run, not a code change.
 - Never edit a test to make it pass.
-- Two whole-suite runs are the budget (`tests.max_suite_runs`). The third
+- Two whole-suite runs are the budget (`tests.max_suite_runs`; in a batch task
+  `batch.max_suite_runs`). The third
   exits 6 `SUITE_BUDGET`: running it again is the human's decision, from their
   own terminal, with the command it prints — or the pick: with the dialog on it
   also prints `DIALOG_PENDING`, and you run the command the human picks,

package/skills/rr-build-all/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: rr-build-all
+description: Run a whole programme plan as one task in a repository that has .ai/ — every row of docs/sdlc/plans/<slug>.md becomes a step with its files, tests and dependencies; the ready steps go to parallel implementer subagents on the BALANCED tier, serialized where one depends on another; after the last step the suite runs once to the end, every failure is recorded and fixed by parallel fixers as one batch, then one review at the mode's tier, its findings fixed by parallel fixers as one batch, then tests and the review again until it passes; the pass past the batch budget (three failed reviews) is the human's. Use on "/rr-build-all", "run the whole plan", "all points in one task", "sdlc-lite", "batch build".
+argument-hint: [<path to docs/sdlc/plans/<slug>.md>] | --resume
+---
+
+# /rr-build-all $ARGUMENTS
+
+One task for the whole plan — the loop a developer otherwise runs by hand: implement every
+row, test once, fix everything, review, fix everything, again, until the review passes. The
+mode (light, guarded, full) is still the weight's; batch only changes who implements, how
+failures are fixed, and how many rounds run before the human. Resolve the install root once:
+
+```bash
+for AI_HOME in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${CODEX_HOME:-$HOME/.codex}"; do
+  [ -d "$AI_HOME/skills/rr-build-all" ] && break
+done
+STATE="python3 $AI_HOME/skills/ai-task/state.py"
+```
+
+Shared files resolve through `"$AI_HOME/riskrails/ai-path" <path>`. Read `policies/safety.md`
+and `using-riskrails.md` once per session. Every rule of `/rr-build` holds here: nothing outside
+the task's files, no commit, a refusal names the way out and is never reworded around.
+
+## 1. Resume or start
+
+```bash
+$STATE handoff --print
+```
+
+- **A task in flight whose handoff says `Batch: on`:** continue at its stage — §3 while
+  `steps --ready` prints a step, §4 after the last `step-done`, §5 after a green verify.
+- **A task in flight without that line:** it runs the standard way — say so and hand over to
+  `/rr-build`. Only the human turns the loop on mid-task (`batch on`, §Switching).
+- **No task in flight:** §2.
+
+## 2. The plan → one task
+
+`$ARGUMENTS` is a programme plan (default: the newest `docs/sdlc/plans/*.md`). Its spec's
+**Flagged concerns** are resolved or accepted, as `/rr-plan` demands; a plan with an open
+blocking question is not started.
+
+1. **Rows → steps.** Every row of **Order of work** that an agent does becomes one step
+   `{"id", "files", "tests", "after"}`: the row's files, the tests it names, and in `after` the
+   rows it depends on — its *Consumes* line, a stated dependency, or an earlier row it builds
+   on. A refactoring row stays its own task (C3): leave it out and say so. A human row (G1, …)
+   is not a step: every row after it names in `after` every step before it, so nothing past
+   the human row is ready until the rows before it are done — and its question (3.) answered.
+2. **Weigh and start** — `/rr-plan`'s "A task" section, on the union of the steps' files, then:
+
+   ```bash
+   $STATE start --goal "<the plan's title>" --workflow feature --files "<every file of every step>" \
+     --tests "<every test>" [--declare …] --plan-file /path/steps.json \
+     --batch --by "<the human's name>" --why "/rr-build-all docs/sdlc/plans/<slug>.md" \
+     [--mode <higher> --by "<name>"]
+   ```
+
+   An `after` id must exist and form no cycle; two steps that name one file are ordered by
+   `start` itself (`ordered: s4 after s1 (shares …)`), so two implementers never hold one file.
+   In full mode the written plan is the programme plan the human already accepted. With
+   `batch.default` true in `.ai/policies/weight.json` the flag is implied; `--no-batch` opts out.
+3. **A human row** becomes a question the moment every step before it is done — asked
+   **before** the next wave is dispatched:
+   `$STATE ask "G1 is yours: <what>" --option "A: done" --option "B: not yet" --recommend A`,
+   then **stop**. Never dispatch while a question is pending (`step-done` and `close` exit 4;
+   `steps --ready` still answers); `/rr-build-all --resume` goes on once the human answered.
+
+## 3. Implement, by waves
+
+```bash
+$STATE steps --ready               # the next wave: the steps whose dependencies are done, one id per line
+$STATE steps --json                # batch_policy.tier and .parallel: the implementers' tier, how many at once
+$STATE profile --tier <that tier>  # the tier's model in this runtime (BALANCED as shipped)
+```
+
+**Resuming mid-wave** (after a compaction or a stop): before dispatching, compare
+`git status --short` with each ready step's files. A ready step whose files already changed
+was dispatched before and never recorded — do not send it again blind: brief its implementer
+with that partial diff to finish, or `step-done` it if its tests pass.
+
+Dispatch one subagent per ready step, at most `batch.parallel` (shipped 3) at once — under
+Claude Code a `general-purpose` agent with `model:` set to that tier's model; under Codex a
+spawn with no agent named, on that model. Its brief is the implementer contract,
+`agents/implementer.md` in the shared tree, filled in:
+
+- **Goal** — the row's text from the plan. **Allowed files** — the step's files, nothing else.
+  **Forbidden files** — every other step's files, "another implementer holds them".
+  **Required behaviour / behaviour that must not change** — from the row and the spec.
+  **Required tests** — the step's tests.
+- Its own tests, run directly: `step_test_command` from `.ai/policies/testing.md` with the
+  step's tests in place of `{files}`. **A subagent never calls `state.py`** — one state file,
+  one writer, this session.
+- It returns `## RESULT`, or `## SCOPE_CHANGE_REQUIRED`, or `## QUESTIONS_NEEDED`.
+
+After the wave, in this session:
+
+- `RESULT` → `$STATE step-done <id>` for each step. Exit 6 names a file outside the task:
+  `$STATE start --amend --files "+<path>" --why "…"`, then `step-done` again.
+- `SCOPE_CHANGE_REQUIRED` → amend as above and send the same step again. A file that belongs
+  to another change goes into `.ai/project/known-risks.md`, not into the task.
+- `QUESTIONS_NEEDED` → `$STATE ask --batch /path/questions.json`, show the questions, **stop**;
+  the human answers, and `/rr-build-all --resume` goes on from the handoff.
+
+Then `steps --ready` again. Nothing ready and nothing pending: §4. Keep this session small:
+read `## RESULT` blocks, never a subagent's diff; `git status --short` is the only view of the
+tree you need between waves.
+
+## 4. Tests once, failures fixed as one parallel batch
+
+After the last wave, `$STATE step-done <id> && $STATE verify --scope all`:
+
+```bash
+$STATE verify --scope all
+$STATE verify --scope all --e2e not-applicable "<why the change reaches no e2e flow>"
+```
+
+Green: §5. **Red:** a FAST `log-reader` reads the log by path and returns every failure
+classified — new regression, existing failure, environment, unknown (`testing.md`, "Reading a
+failure") — each with `file:line`. Then:
+
+- an existing failure → one entry in `.ai/project/known-risks.md`; an environment failure →
+  one more run, no code change;
+- the new regressions, grouped by the file they point at → one fixer subagent per group, in
+  parallel, at most `batch.parallel`, on the batch tier, briefed with the failures' excerpts
+  and the files it may touch (that group's files, inside the task's). Fix the code, never the
+  test; report `files_changed` and what stayed unfixed;
+- one run: `$STATE verify --scope all --after-fix "<n> regressions: <one line each>"`.
+
+Red again → the same once more. Exit 6 `SUITE_BUDGET` — past `batch.max_suite_runs`
+(shipped 8) — is the human's run: the pick in the dialog, or the command it prints, in their
+own terminal. **Stop.**
+
+## 5. Review, findings fixed as one parallel batch, again until it passes
+
+One `ai-reviewer` at the mode's tier, briefed as `/rr-review` §2 says: the whole diff since the
+task's base, the task's files, the tests, the last verify log; unbounded "look for" in full
+mode, the security focus when the domain axis is 2. Record it verbatim:
+
+```bash
+$STATE review --verdict <pass|pass_with_findings|blockers_open> --tier <BALANCED|STRONG> \
+  [--focus security] --report - <<'EOF'
+<the reviewer's FINDINGS and VERDICT, unchanged>
+EOF
+```
+
+- **pass** → §6.
+- **pass_with_findings** → the in-scope HIGHs, grouped by file, one fixer per group in
+  parallel; `$STATE verify --scope all --after-fix "H1,H2: …"`; `$STATE review --closes "H1,H2"`
+  → §6. MEDIUM and LOW: `memory risk add` as `/rr-review` §4 says, for every verdict; only a
+  BLOCKER, a HIGH or a regression buys an `--after-fix` run.
+- **blockers_open** → every in-scope BLOCKER and HIGH, grouped by file, one fixer per group in
+  parallel; `$STATE verify --scope all --after-fix "B1,H1: …"` (red: §4's batch); then
+  **§5 again, a full pass** — a fix batch across many files is a new change, not a scoped one.
+
+Exit 6 `REVIEW_BUDGET` after `batch.review_rounds_max` passes (shipped 3 — three failed
+reviews) — the next verdict is the human's: the pick in the dialog, or the command it prints,
+in their own terminal. Show the open findings and **stop**. A `verify` past its budget inside
+this loop is `SUITE_BUDGET`, handled the same way.
+
+## 6. Ship
+
+`/rr-ship` — `close` measures the two facts and, in full mode, asks the human to approve,
+exactly as for any task; for a documents-only change since the green suite it is
+`$STATE verify --scope step --files "<doc_tests>" && $STATE verify --scope e2e && $STATE close`. Suggest `/clear` after it.
+
+## Switching
+
+- **To the standard loop ("full" from here):** `$STATE batch off --by "<name>" --why "<why>"`.
+  The standard budgets apply from now, counting what was spent — with two passes behind you,
+  the next verdict is already the human's. The session implements the remaining steps itself;
+  continue with `/rr-build`, `/rr-review`, `/rr-ship`. Anyone may do this: it raises the rigor.
+- **To batch, mid-task:** lowers the rigor — the human's, in their own terminal:
+  `python3 <AI_HOME>/skills/ai-task/state.py --root <project> batch on --by "<name>"`. Never
+  from a tool call; the refusal (`APPROVAL_REFUSED`) prints that command.
+- **The project's default:** `batch.default` in `.ai/policies/weight.json`, beside
+  `batch.review_rounds_max`, `batch.max_suite_runs`, `batch.parallel` and `batch.tier`
+  (`/rr-setup --update` adds the section). A policy is the human's and is frozen during a task.
+
+## Rules
+
+- The mode is the weight's and only rises; the scope guard, the two facts, the gate and the
+  three nevers are untouched by batch.
+- Three or more parallel agents run at BALANCED, never above — `start` refuses `batch.tier`
+  above it when `batch.parallel` is three or more; one reviewer per pass, at the mode's tier;
+  the session writes every conclusion (`model-routing.md`).
+- One writer of the state: a subagent never calls `state.py`; this session records every step,
+  run and verdict.
+- Failures and findings are fixed as batches, never one at a time; a test is never edited to
+  make it pass; what is outside the task is written down, not fixed.
+- No commit, push, merge or deploy. The task ends at `/rr-ship`; approval is the human's.

package/skills/rr-plan/SKILL.md

@@ -24,7 +24,9 @@ first: a task already in flight is finished or abandoned before another starts.
 
 When `$ARGUMENTS` is a spec (default: the newest `docs/sdlc/specs/*.md`):
 
-1. `docs/sdlc/plans/TEMPLATE.md` exists, else `/rr-setup`. If the spec's
+1. `docs/sdlc/constitution.md` exists, else `/rr-setup`. The template is
+   `docs/sdlc/plans/TEMPLATE.md` when the project overrides it, else
+   `$AI_HOME/skills/project-init/templates/plan.md`. If the spec's
    **Flagged concerns** holds unresolved items, list them and have the human
    resolve or explicitly accept each one before planning.
 2. If `superpowers:writing-plans` is available, use it for the step
@@ -38,7 +40,11 @@ When `$ARGUMENTS` is a spec (default: the newest `docs/sdlc/specs/*.md`):
 4. Copy the template to `docs/sdlc/plans/<slug>.md`, fill **Files that change /
    Order of work / Risks / Proof / Rollback**; Proof maps every requirement R<n>
    to a test or command. One round of corrections; suggest the commit
-   `plan: <title>`. Each row of the plan is later one task, planned below.
+   `plan: <title>`. Each row of the plan is later one task, planned below —
+   unless the whole plan runs as one task through `/rr-build-all` (the project's
+   `batch.default` in `weight.json`, or the developer's call): then every row
+   becomes one step of that task, so give each row its files and its *Consumes*
+   line (the rows it depends on) — that is what `/rr-build-all` reads.
 
 ## A task → weight, mode, plan, start
 
@@ -48,7 +54,10 @@ investigation — say which and why. `using-riskrails.md` in the shared tree
 `workflows.md#<kind>` say what each kind requires. A refactoring and a feature
 are never one task.
 
-**2. Name the files** from the request, confirmed with `grep -n`. Then weigh:
+**2. Name the files** from the request, confirmed with `grep -n`. Recall what
+the record holds about them — `$STATE recall --files "<a>,<b>"`: open risks,
+residual findings and earlier decisions are evidence for the weight and the
+plan. Then weigh:
 
 ```bash
 $STATE weight --files "<a>,<b>" --goal "<one sentence>" \
@@ -64,7 +73,7 @@ The table is `.ai/policies/weight.json` (`weight.md` mirrors it).
 
 **3. The mode is the weight's**, not yours: raising it is free
 (`--mode <m> --by "<name>"` on `start`); lowering it is the human's, from their
-own terminal. Shape the plan by it:
+own terminal, or the command they picked in the dialog. Shape the plan by it:
 
 | Mode | Plan | Who sees it before the first edit |
 |---|---|---|
@@ -92,6 +101,9 @@ $STATE start --goal "<one sentence>" --workflow <kind> --files "<a>,<b>" \
 
 `--plan-file` is a JSON list `[{"id": "s1", "files": [...], "tests": [...]}]`
 for a guarded or full plan with steps; a light task is one scope and needs none.
+A step may add `"after": ["s0"]`, the steps it waits for — `/rr-build-all` runs
+the rest in parallel — and `--batch --by "<name>"` (or `--no-batch`) sets that
+loop for the task; the default is `batch.default` in `weight.json`.
 `--files` lists every file of every step — the guard refuses an edit outside
 them. `--tests` names the task's own tests; a bugfix names its failing test. At
 guarded and full, run `start` only after the human accepted the plan.

package/skills/rr-review/SKILL.md

@@ -30,7 +30,10 @@ STATE="python3 $AI_HOME/skills/ai-task/state.py"
 (`review_rounds_max`): one full review and one scoped re-review. The pass past
 it exits 6 `REVIEW_BUDGET` — the next verdict is the human's, from their own
 terminal, with the command it prints, or the pick in the dialog (`DIALOG_PENDING`,
-then the picked command verbatim, once). Never a third pass.
+then the picked command verbatim, once). Never a third pass. A batch task
+(`/rr-build-all`) has its own budget, `batch.review_rounds_max` full passes
+(shipped three): after a `blockers_open` fix batch the next pass is a full one,
+and the pass past the budget is the human's the same way.
 
 ## 2. Brief one `ai-reviewer`
 
@@ -49,14 +52,18 @@ the tier, so name the tier in the brief. Give it paths, not pasted text:
 **Bounded inputs in light and guarded:** the goal, the diff, the named tests,
 and the project's own threat model (`.ai/policies/safety.md`, the guards'
 defaults, the test fixtures). A finding that needs anything outside them comes
-back `[INFO]` with `in_scope: no`; write it into `.ai/project/known-risks.md`
+back `[INFO]` with `in_scope: no`; record it with `$STATE memory risk add`
 as one entry — it never opens a fix. You may move a finding to
 `in_scope: yes`, never the other way. **In full mode** the reviewer's own "look
-for" list applies unbounded.
+for" list applies unbounded. Tell it the cap: about 40 tool calls in light and
+guarded, about 80 in full, then FINDINGS and VERDICT.
 
 Before you delegate, probe the change yourself for a minute: the few inputs its
 own threat model makes interesting, through the real code, and hand the
-reviewer what you saw — it starts where you stopped.
+reviewer what you saw — it starts where you stopped. When the change touches a
+guard regex's running time, run the timed probe yourself (`/usr/bin/grep -E`,
+or Python `timeit` on inputs of at most 4096 chars) and hand over the
+measurement: the bounded reviewer may not run timing loops.
 
 ## 3. Record the verdict
 
@@ -77,12 +84,18 @@ task's record (`task.md`), so there is no separate report to write.
 
 ## 4. After the verdict
 
-- **pass:** `/rr-ship`.
-- **pass_with_findings:** fix every in-scope HIGH (and the MEDIUMs worth it) in
-  one batch, then
+Continue from the verdict §3 recorded; do not record it again. Whatever the
+verdict, each MEDIUM and LOW is one `$STATE memory risk add`
+(`.ai/project/known-risks.md` amended into the task if missing), not a fix.
+
+- **pass:** `/rr-ship`, i.e. `$STATE close` directly: the verdict is already
+  recorded. (To record and close in one call, §3's `review --verdict pass … <<'EOF' && $STATE close`;
+  `review` exits 0 for every verdict, so that chain is for `pass` only.)
+- **pass_with_findings:** fix every in-scope HIGH in one batch, then
   `$STATE verify --scope all --after-fix "H1,H2: <one line>"` and
   `$STATE review --closes "H1,H2"`. The findings close on that green run, on a
-  tree the fix changed — no second review.
+  tree the fix changed — no second review. MEDIUM and LOW: `memory risk add`
+  as above; only a BLOCKER, a HIGH or a regression buys an `--after-fix` run.
 - **blockers_open:** fix every BLOCKER and HIGH together, `verify --scope all
   --after-fix "…"`, then **one scoped re-review** (`/rr-review B1,H1`): brief a fresh `ai-reviewer`
   with the named findings and the fix's diff only — do they close, and what did
@@ -94,6 +107,8 @@ The `verify` after a fix is often the task's third whole-suite run: past
 from their own terminal, with the command it prints, or the pick in the dialog.
 
 A finding whose cause is the plan goes back to `/rr-plan` for that part only. A
-real problem outside the task goes into `.ai/project/known-risks.md`. A mistake
+real problem outside the task is recorded with `$STATE memory risk add`; a
+fix in this task closes its risk with `$STATE memory risk close <rkey> --status
+fixed --why "…"`. A mistake
 this repository has seen before — the second time a review flags it — gets one
 line in the project instruction file, in this task.

package/skills/rr-setup/SKILL.md

@@ -133,12 +133,25 @@ it cannot.
    each in one plain sentence and ask, unless `$ARGUMENTS` holds `--apply`.
 4. `$UPDATE --apply`. Exit 3 stopped on a changed, non-regular or unwritable
    file and names it; nothing after it was written — run the dry run again.
-   **A `delete?` is the human's.** Never pass `--confirm-delete`, not even with
+   **A `delete?` is the human's.** Never pass `--confirm-delete` or `--confirm-cleanup`, not even with
    `--apply`. Give them, with `$AI_HOME` and `$PWD` substituted, for their own
    terminal (the `!` prefix is refused):
    `python3 "<home>/skills/project-update/update.py" "<project>" --apply --confirm-delete "<your name>"`.
    The schema stays put until it is settled — that command, or deleting the
-   file by hand; there is no third way. For 0006 (shared files) the order is:
+   file by hand; there is no third way. Two kinds are housekeeping, not
+   migrations: `[sdlc]` — an unedited `docs/sdlc/*/TEMPLATE.md`, which the plugin
+   now supplies (an edited one stays as the project's override); `[cleanup]` —
+   the `*.log` files of closed tasks, and the report and log files of an
+   abandoned task (its `state.json` stays) or of one unclosed for more than seven
+   days (never the task in flight; and none when `.ai/state/state.json` is unreadable).
+   `--confirm-delete` does not settle `[cleanup]` rows, and the rows differ by kind:
+   files under `.ai/state/logs/` are git-ignored and git cannot restore them; files
+   under `.ai/reports/` are usually tracked, and the row says "tracked: git can restore
+   a committed copy" or, when git holds no committed copy, "uncommitted" — then
+   commit `.ai/` first (the hint says so), and an `original/` copy is kept as for any
+   other deletion. They have their own command, the human's too, never passed by the agent:
+   `python3 "<home>/skills/project-update/update.py" "<project>" --apply --confirm-cleanup "<your name>"`.
+   Show both groups as printed. For 0006 (shared files) the order is:
    `install.sh` for every runtime used, commit `.ai/`, read the `delete?` list,
    then the command with no task in flight. Rollback is git:
    `git restore --source=<commit before> --staged --worktree -- .ai`, before

package/skills/rr-setup/setup.py

@@ -182,7 +182,11 @@ def comment_purpose(lines):
 
 
 def purpose_of(root, rel):
-    text = read_text(os.path.join(root, rel))
+    full = os.path.join(root, rel)
+    real, base = os.path.realpath(full), os.path.realpath(root)
+    if os.path.commonpath([real, base]) != base:
+        return None  # a link out of the project: listed UNKNOWN, never read into toolbox.md
+    text = read_text(full)
     if text is None:
         return None
     lines = text.splitlines()
@@ -225,6 +229,8 @@ def inventory(root, table):
         for rel in paths:
             if rel in seen or not pattern.match(rel):
                 continue
+            if "/hooks/" in rel and os.path.basename(rel).startswith("."):
+                continue
             seen.add(rel)
             if row["kind"] == "make":
                 for n, target, purpose in make_targets(root, rel):

package/skills/rr-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rr-ship
-description: Close the task — state.py close measures the two facts (a green whole-suite verify on the tree as it is now; every changed file inside the task's files), applies the mode table and either archives the task or, in full mode, requests the human's approval and prints the exact approve command for their own terminal. Writes the commit message body and suggests the commit; never commits, pushes or approves. Use on "/rr-ship", "close the task", "ship it", "ready for approval", after /rr-build or /rr-review.
+description: Close the task — state.py close measures the two facts (a green whole-suite verify on the tree as it is now; every changed file inside the task's files), applies the mode table and either archives the task or, in full mode, requests the human's approval and prints the exact approve command for their own terminal. Writes the commit message body and suggests the commit; never merges or deploys, and commits, pushes or approves only as the command the human picked in the dialog, verbatim, once. Use on "/rr-ship", "close the task", "ship it", "ready for approval", after /rr-build or /rr-review.
 argument-hint: [--abandon]
 ---
 
@@ -33,7 +33,8 @@ Then the mode table decides:
 |---|---|---|
 | 0, `closed` | archived: `task.md` holds the changes and the verdict | §3 |
 | 0, `ready for approval` | full mode: the gate is requested | §2 |
-| 2 `review required` | light with a red fact, or guarded/full without its review | `/rr-review` |
+| 2 `review required` whose text holds `only documents changed since run …` (read this row first) | a green suite, then documents only | `$STATE verify --scope step --files "<doc_tests>" && $STATE verify --scope e2e && $STATE close` — `close` prints the files comma-joined; use its text |
+| 2 `review required`, any other reason | light with a red fact, or guarded/full without its review | `/rr-review` |
 | 2 `verify required` | e2e owed, or not on this tree | `$STATE verify --scope all` (or `--scope e2e`, or `--e2e not-applicable "<why>"`) |
 | 4 | a question is pending | show it; §4 |
 | 5 `APPROVAL_REFUSED` | rejected, and nothing changed since | address the rejection, `verify --scope all`, close again |
@@ -54,9 +55,13 @@ Show the human the summary (§3), the open findings, the rollback, and that
 command **verbatim** — paths absolute and quoted, because they paste it into
 their own shell, where `$AI_HOME` is not set. Then **stop**.
 
-- **You cannot approve.** `approve` refuses without a terminal on stdin or
-  `AI_UNATTENDED` in its own environment — neither of which a tool call from this
-  session has — and the path guard denies it. Never try another route.
+- **You approve only through the dialog.** With `.ai/policies/dialog.json`
+  `enabled: true`, `close` offers the `approve` command in the runtime's dialog;
+  once the human picks it, run exactly that command, verbatim and once. With the
+  switch off, or no pick, you cannot approve: `approve` refuses without a terminal
+  on stdin or `AI_UNATTENDED` in its own environment — neither of which a tool
+  call from this session has — and the path guard denies it. Never try another
+  route.
 - **full_irreversible:** the command carries
   `--confirm "<what it does, naming DROP …>"`; the human names every operation
   the re-score found, in their own words.
@@ -91,11 +96,14 @@ Write the body from `.ai/reports/<task-id>/task.md` — no new opinion:
 - the verification command and its result (suite and e2e);
 - the review verdict, with any finding left open and why;
 - the rollback: `git revert <commit>`, plus anything a revert does not undo;
-- open risks, pointing at `.ai/project/known-risks.md`.
+- open risks: the ones this task recorded or closed with `state.py memory risk
+  add|close`, by rkey (`state.py memory risks` lists them).
 
 Suggest the commit command — `git add` of the task's files and its
-`.ai/reports/<task-id>/`, then `git commit` with that body — for the human to
-run. You never commit, push, merge or deploy.
+`.ai/reports/<task-id>/` (in packages mode also `.ai/memory/`, which holds the
+task's record — the pre-push check refuses a closed task without it), then
+`git commit` with that body — for the human to run. You never merge or deploy; you commit, push or
+approve only as the command the human picked in the dialog (§2), verbatim, once.
 
 ## 4. Pending questions
 

package/skills/rr-spec/SKILL.md

@@ -19,7 +19,9 @@ STATE="python3 $AI_HOME/skills/ai-task/state.py"
 
 ## 1. Prerequisites
 
-`docs/sdlc/specs/TEMPLATE.md` exists, else run `/rr-setup` first. Derive
+`docs/sdlc/constitution.md` exists, else run `/rr-setup` first. The template is
+`docs/sdlc/specs/TEMPLATE.md` when the project overrides it, else
+`$AI_HOME/skills/project-init/templates/spec.md`. Derive
 `<slug>` from the topic (kebab-case, at most five words). If
 `docs/sdlc/specs/<slug>.md` exists, offer to refine it instead of starting over.
 When `$ARGUMENTS` is a path to an intent file, read it fully — it is small by
@@ -75,7 +77,7 @@ decision — moves this to the top tier.
 
 ## 5. Write
 
-Copy `docs/sdlc/specs/TEMPLATE.md` to `docs/sdlc/specs/<slug>.md`, replace
+Copy the template (§1) to `docs/sdlc/specs/<slug>.md`, creating the folder, replace
 `{{TITLE}}` and `{{SLUG}}`. Replace the template's `Intent:` line with:
 
 ```markdown

package/skills/rr-status/SKILL.md

@@ -24,8 +24,8 @@ After the output, at most one line, and only when a line asks for it:
 - `questions: N pending` with N > 0: the task is halted until they are
   answered — `/rr-build` shows them. The count can lag an `[Answer]:` line the
   human filled in the file; `state.py handoff --print` re-reads the file.
-- `gate: requested`: the human runs the `approve` command `/rr-ship` printed,
-  in their own terminal; you cannot.
+- `gate: requested`: the `approve` command `/rr-ship` printed is run by the human in their
+  own terminal, or by you only if they picked it in the dialog (verbatim, once).
 
 Exit 1 with `root: none` means no `.ai/` governs this directory: `/rr-setup`
 sets one up.

package/skills/usage-report/usage-report.py

@@ -637,27 +637,61 @@ def find_project(start: str) -> str | None:
         d = parent
 
 
+def seal_events(project: str, task: str) -> list:
+    """R20 (compact-project-memory): after cleanup only the record knows the
+    task — its seal's started_at, closed_at, mode and runtimes stand in for
+    the journal's first and last lines."""
+    base = os.path.join(project, ".ai", "memory")
+    seal = None
+    for name in sorted(os.listdir(base)) if os.path.isdir(base) else []:
+        if not name.endswith(".jsonl"):
+            continue
+        with open(os.path.join(base, name), encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                rec = _record(line)
+                if rec and rec.get("kind") == "task" and rec.get("task") == task:
+                    if seal is None or (rec.get("inst") or 0) >= (seal.get("inst") or 0):
+                        seal = rec
+    if not seal or not seal.get("started_at"):
+        return []
+    runtimes = [rt for rt in seal.get("runtimes") or [] if rt in RUNTIMES]
+    out = [{"ts": seal["started_at"], "event": "task_started", "runtime": rt} for rt in runtimes or [None]]
+    out.append({"ts": seal["started_at"], "event": "tier_set",
+                "data": {"tier": seal.get("legacy_tier") or "untiered", "mode": seal.get("mode")}})
+    if seal.get("closed_at"):
+        out.append({"ts": seal["closed_at"], "event": "task_closed"})
+    return out
+
+
 def task_report(args) -> int:
     """One task's window from its journal, the tokens each runtime spent in it,
     and each involved runtime's budget for the task's final tier."""
     project = find_project(args.project or os.getcwd())
     journal = os.path.join(project or "", ".ai", "reports", args.task, "events.jsonl")
-    if not project or not os.path.isfile(journal):
-        print(f"no journal for {args.task} (looked for {journal})")
-        return 1
+    moved = os.path.join(project or "", ".ai", "state", "logs", args.task, "report", "events.jsonl")
     events = []
-    with open(journal, encoding="utf-8", errors="replace") as fh:
-        for line in fh:
-            rec = _record(line)
-            if rec is not None:
-                events.append(rec)
+    if project and not os.path.isfile(journal) and os.path.isfile(moved):
+        journal = moved                   # cleanup moved the report directory into the local raw store
+    if not project or not os.path.isfile(journal):
+        events = seal_events(project, args.task) if project else []
+        if not events:
+            print(f"no journal for {args.task} (looked for {journal})")
+            return 1
+        print(f"(no journal: the window is the record's seal for {args.task})")
+    else:
+        with open(journal, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                rec = _record(line)
+                if rec is not None:
+                    events.append(rec)
     stamps = [parse_ts(e.get("ts")) for e in events if parse_ts(e.get("ts"))]
     if not stamps:
         print(f"the journal of {args.task} has no timestamps")
         return 1
     start = min(stamps)
     closed = [parse_ts(e.get("ts")) for e in events if e.get("event") == "task_closed"]
-    end = max(c for c in closed if c) if any(closed) else dt.datetime.now(dt.timezone.utc)
+    unclosed = not any(closed)
+    end = max(stamps) if unclosed else max(c for c in closed if c)   # unclosed: the last event, not now
     tier, mode = "untiered", None
     involved = []
     for e in events:
@@ -696,7 +730,8 @@ def task_report(args) -> int:
 
     label = f"mode {mode} (tier {tier})" if mode else f"tier {tier}"
     print(f"task {args.task} {label} window {start.isoformat(timespec='seconds')}"
-          f"..{end.isoformat(timespec='seconds')}")
+          f"..{end.isoformat(timespec='seconds')}"
+          + (" (unclosed: window ends at the last event)" if unclosed else ""))
     print("  (by time window: any other session in this project inside it is counted too)")
     for rt in involved or sorted(used):
         inp, cache, out = used.get(rt, [0, 0, 0])