riskrails 4.1.0 → 4.3.0

package/skills/project-update/rr_update/cli.py

@@ -0,0 +1,102 @@
+"""Bring a project's RiskRails files up to date with the installed plugin.
+
+shell: main
+"""
+# argparse's description is the first line of this docstring, which is the entry's first line.
+import argparse
+import os
+import sys
+
+import render_instructions  # next to the entry, whose directory the entry puts on sys.path
+from rr_update import apply, build, gate, hints, history, kept, paths, report
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("root", nargs="?", default=".")
+    ap.add_argument("--apply", action="store_true")
+    ap.add_argument("--check", action="store_true")
+    ap.add_argument("--budget", action="store_true",
+                    help="with --check: exit 1 when a root instruction file is over its byte budget")
+    ap.add_argument("--confirm-delete", metavar="NAME",
+                    help="a human confirms this run's gated rows (regenerate?, delete?), and is recorded in "
+                         "the migration report; only with --apply")
+    ap.add_argument("--confirm-cleanup", metavar="NAME",
+                    help="a human confirms this run's [cleanup] deletions (run logs and stale task files, "
+                         "git-ignored and not recoverable through git); only with --apply. "
+                         "--confirm-delete does not settle them")
+    args = ap.parse_args()
+    confirm_via = cleanup_via = None
+    for flag, name in (("--confirm-delete", args.confirm_delete), ("--confirm-cleanup", args.confirm_cleanup)):
+        if name is None:
+            continue
+        if not args.apply:
+            ap.error("%s only makes sense with --apply" % flag)
+        if not name.strip():
+            ap.error("%s needs the name of the human who confirmed the change" % flag)
+        if gate.placeholder_name(name):
+            ap.error("%s got the placeholder %r; type your own name, it is the audit trail"
+                     % (flag, name.strip()))
+        passed, via, why = gate.human_gate()
+        if not passed:
+            # Under an agent-session marker the AI_UNATTENDED route is the launcher's
+            # to declare, not the agent's to type: the hint names it only otherwise.
+            hint = "run the same command yourself in a terminal outside Claude Code or Codex"
+            if "agent session" not in why:
+                hint += ", or set AI_UNATTENDED=1 if a launcher runs it unattended on your behalf"
+            return gate.refuse("%s is typed by a human, and %s" % (flag, why), hint)
+        if flag == "--confirm-delete":
+            confirm_via = via
+        else:
+            cleanup_via = via
+    if args.budget and not args.check:
+        ap.error("--budget only makes sense with --check")
+    root = os.path.abspath(args.root)
+    if args.check and args.budget:
+        offenders = hints.budget_offenders(
+            root, [paths.INSTRUCTION_FILE[rt][0] for rt in history.project_runtimes(root)],
+            render_instructions.budgets(render_instructions.DEFAULT_SOURCE), render_instructions.block_of)
+        for line in offenders:
+            print(line)
+        return 1 if offenders else 0
+    for name, tpl in paths.TEMPLATES.items():
+        if not os.path.isdir(tpl):
+            print("project-update: %s templates not found at %s (run riskrails/install.sh)" % (name, tpl), file=sys.stderr)
+            return 2
+    if not (os.path.isdir(os.path.join(root, ".ai")) or os.path.isdir(os.path.join(root, "docs", "sdlc"))):
+        print("project-update: %s has neither .ai/ nor docs/sdlc/ — run /rr-setup first" % root, file=sys.stderr)
+        return 2
+    try:
+        if os.path.isdir(os.path.join(root, ".ai")):
+            history.project_version(root)
+        bad = kept.check_kept(root)
+        if bad:
+            return kept.kept_refusal(bad)
+        plan = build.build_plan(root, confirm_delete=args.confirm_delete, confirm_via=confirm_via,
+                          confirm_cleanup=args.confirm_cleanup, cleanup_via=cleanup_via)
+    except history.SchemaError as exc:
+        # --check is read by /rr-status, which reads stdout: it must see the reason.
+        print("project-update: %s" % exc, file=sys.stdout if args.check else sys.stderr)
+        return 2
+    if args.check:
+        pending = [i for i in plan.items if not i["action"].endswith("?")]
+        waiting = [i for i in plan.items if i["action"].endswith("?") and not (i["reason"] or "").startswith("[cleanup]")]
+        if pending:
+            bits = ["%d file(s) to update" % len(pending)]
+            if waiting:
+                bits.append("%d change(s) a human must confirm" % len(waiting))
+            print("project is behind the installed plugin: %s — run /rr-setup --update" % ", ".join(bits))
+            return 1
+        print("project matches the installed plugin"
+              + (" (%d change(s) wait for --confirm-delete)" % len(waiting) if waiting else ""))
+        return 0
+    if args.apply:
+        try:
+            apply.apply(plan)
+        except apply.Abort as exc:
+            where = "%s %s" % (exc.item["action"], exc.item["target"]) if exc.item else "the update"
+            print("project-update: aborted at %s: %s — nothing after it was written; "
+                  "run the dry run again" % (where, exc.why), file=sys.stderr)
+            return 3
+    report.report(plan, args.apply)
+    return 0

package/skills/project-update/rr_update/files.py

@@ -0,0 +1,106 @@
+"""Files and the two outside readers: the clock, a hash, a read, git's view of a tree, JSON bytes, a path safe to delete.
+
+shell: utc_now, read, git_dirty_ai, git_states, unsafe_path
+core: sha, dump_json
+"""
+
+import hashlib
+import json
+import os
+import subprocess
+from datetime import datetime, timezone
+
+
+def utc_now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def sha(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def read(path):
+    with open(path, "rb") as fh:
+        return fh.read()
+
+
+
+def git_dirty_ai(root):
+    """True when .ai/ has changes git does not hold yet: git is the rollback of
+    a migration that deletes, so it must hold them first. False outside a work
+    tree, where there is nothing to say."""
+    try:
+        res = subprocess.run(["git", "-C", root, "status", "--porcelain", "--", ".ai"],
+                             stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=30, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return res.returncode == 0 and bool(res.stdout.strip())
+
+
+def git_states(root, rel_dir):
+    """A function path -> how git holds a file under `rel_dir` (project-relative):
+    "tracked" (committed and unchanged), "uncommitted" (changed, staged or not yet
+    tracked, so git has no copy to restore) or "ignored"; None outside a work tree
+    or for a path git does not know."""
+    def run(*args):
+        res = subprocess.run(["git", "-C", root] + list(args), stdout=subprocess.PIPE,
+                             stderr=subprocess.DEVNULL, timeout=30, check=False)
+        return res.stdout.decode("utf-8", "replace") if res.returncode == 0 else None
+    try:
+        prefix = run("rev-parse", "--show-prefix")
+        tracked = run("ls-files", "-z", "--", rel_dir)
+        status = run("status", "--porcelain=v1", "-z", "--ignored", "-uall", "--", rel_dir)
+    except (OSError, subprocess.SubprocessError):
+        return lambda path: None
+    if prefix is None or tracked is None or status is None:
+        return lambda path: None
+    prefix = prefix.strip()
+    tracked = set(tracked.split("\0"))
+    dirty, ignored = set(), []
+    entries = status.split("\0")
+    skip = False
+    for entry in entries:
+        if skip:  # the origin path of a rename
+            skip = False
+            continue
+        if len(entry) < 4:
+            continue
+        xy, path = entry[:2], entry[3:]
+        if prefix and path.startswith(prefix):
+            path = path[len(prefix):]
+        if "R" in xy or "C" in xy:
+            skip = True
+        if xy == "!!":
+            ignored.append(path)
+        else:
+            dirty.add(path)
+
+    def classify(path):
+        if path in dirty:
+            return "uncommitted"
+        if any(path == i or (i.endswith("/") and path.startswith(i)) for i in ignored):
+            return "ignored"
+        return "tracked" if path in tracked else None
+    return classify
+
+
+def dump_json(value):
+    return (json.dumps(value, indent=2, ensure_ascii=False) + "\n").encode()
+
+
+def unsafe_path(root, path):
+    """Why a project-relative path must not be deleted: a symlink on the way to it,
+    or a real path outside the project; None when it is safe. Run at plan time and
+    again right before the delete."""
+    real_root = os.path.realpath(root)
+    here = root
+    for part in path.split("/"):
+        here = os.path.join(here, part)
+        if os.path.islink(here):
+            return "%s is a symlink" % os.path.relpath(here, root).replace(os.sep, "/")
+    real = os.path.realpath(os.path.join(root, path))
+    if real != real_root and not real.startswith(real_root + os.sep):
+        return "%s resolves outside the project (%s)" % (path, real)
+    return None
+
+# ---------------------------------------------------------------- the one gate

package/skills/project-update/rr_update/gate.py

@@ -0,0 +1,60 @@
+"""The one gate: who is at the keyboard, the audit-trail name, and the refusal every gate prints.
+
+shell: ai_unattended, human_gate, refuse
+core: AGENT_MARKERS, PLACEHOLDER_NAME_RE, placeholder_name
+"""
+
+import os
+import re
+
+from rr_update import paths
+
+# Set in the environment of a shell an agent runs: Claude Code's CLAUDECODE,
+# and the names Codex gives its tool calls. Present counts, an empty value too.
+AGENT_MARKERS = ("CLAUDECODE", "CODEX_THREAD_ID", "CODEX_SESSION_ID", "CODEX_CI",
+                 "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_VERSION")
+
+
+def ai_unattended():
+    """AI_UNATTENDED is set when it is non-empty and not 0, false or no (case
+    and blanks ignored): one rule in every reader (risk 0587)."""
+    return os.environ.get("AI_UNATTENDED", "").strip().lower() not in ("", "0", "false", "no")
+
+
+def human_gate():
+    """(passed, via, why) for --confirm-delete. A terminal outside any agent
+    session is a human: via "terminal". Otherwise a launcher that declared the
+    run unattended (AI_UNATTENDED) passes: via "unattended", as state.py's
+    approve records it. Anything else is refused, and `why` says what was seen —
+    a terminal alone is not enough, since an agent can open a pty (F3).
+
+    Duplicated in spirit from skills/ai-task/state.py (human_present) on purpose:
+    the two skills are installed independently and neither imports the other."""
+    markers = [name for name in AGENT_MARKERS if name in os.environ]
+    if os.isatty(0) and not markers:
+        return True, "terminal", ""
+    if ai_unattended():
+        return True, "unattended", ""
+    if markers:
+        return False, None, ("this run is inside an agent session (%s %s set); run it in a terminal "
+                             "outside Claude Code or Codex, not through the `!` prefix"
+                             % (", ".join(markers), "is" if len(markers) == 1 else "are"))
+    return False, None, "this run has no terminal"
+
+
+# The name typed into --confirm-delete is the audit trail; the template's own
+# "<your name>" copied verbatim names no one. The whole value, not a substring.
+PLACEHOLDER_NAME_RE = re.compile(r"\A\s*(?:<[^>]*>|your\s+name)\s*\Z", re.IGNORECASE)
+
+
+def placeholder_name(name):
+    return bool(PLACEHOLDER_NAME_RE.match(name or ""))
+
+
+def refuse(reason, how):
+    """Print the refusal the way every gate does — the marker on the first
+    stdout line, then what to do — and return exit code 5."""
+    print("%s: %s" % (paths.REFUSED, reason))
+    print("  %s" % how)
+    return 5
+

package/skills/project-update/rr_update/hints.py

@@ -0,0 +1,128 @@
+"""The hints of a run: budget offenders and hints, the .gitignore rows, the constitution and verification hints.
+
+shell: budget_offenders, gitignore_update, budget_hints, constitution_hint, verification_hints
+"""
+
+import contextlib
+import io
+import os
+import re
+
+import render_instructions  # next to the entry, whose directory the entry puts on sys.path
+
+from rr_update import files as files_mod
+from rr_update import paths
+
+
+def budget_offenders(root, files, caps, block_of):
+    """R21: one line per root instruction file over budget — its managed block
+    over `caps["project"]`, or the whole file over `caps["skeleton"]`. Files that
+    do not exist are skipped; a file under both budgets prints nothing."""
+    out = []
+    for name in files:
+        path = os.path.join(root, name)
+        if not os.path.isfile(path):
+            continue
+        with open(path, encoding="utf-8") as fh:
+            text = fh.read()
+        block = block_of(text)
+        size = len(text.encode("utf-8"))
+        if block is not None and caps.get("project") and len(block.encode("utf-8")) > caps["project"]:
+            out.append("%s block %d B over the project budget of %d B"
+                       % (name, len(block.encode("utf-8")), caps["project"]))
+        if caps.get("skeleton") and size > caps["skeleton"]:
+            out.append("%s file %d B over the skeleton budget of %d B" % (name, size, caps["skeleton"]))
+    return out
+
+
+RECORD_HINT = (".ai/memory/ and .ai/reports/ are local now. Files git already tracks stay tracked: "
+               "'git rm -r --cached --ignore-unmatch .ai/memory .ai/reports' untracks them (yours to run); "
+               "'state.py memory enable --share git' keeps sharing them.")
+
+
+GITIGNORE_NOTE = "entries appended: "
+
+
+def gitignore_update(plan, snippet_path):
+    snippet = files_mod.read(snippet_path).decode().splitlines()
+    current = plan.read(".gitignore") or b""
+    have = set(current.decode().splitlines())
+    missing = [l for l in snippet if l.strip() and not l.startswith("#") and l not in have
+               and "!" + l not in have]
+    if not missing:
+        return
+    header = [l for l in snippet if l.startswith("#") and l not in have]
+    add = "\n".join(header + missing) + "\n"
+    sep = b"\n" if current and not current.endswith(b"\n") else b""
+    new = current + sep + add.encode()
+    # Replace an earlier .gitignore item from this run instead of stacking two.
+    earlier = [i["note"][len(GITIGNORE_NOTE):] for i in plan.items
+               if i["target"] == ".gitignore" and i["note"].startswith(GITIGNORE_NOTE)]
+    plan.items = [i for i in plan.items if i["target"] != ".gitignore"]
+    plan.add("regenerate", ".gitignore", GITIGNORE_NOTE + ", ".join(earlier + missing), content=new)
+    if {".ai/memory/", ".ai/reports/"} & set(missing) and RECORD_HINT not in plan.hints:
+        plan.hints.append(RECORD_HINT)
+
+
+def budget_hints(plan, runtimes):
+    """What the always-loaded block costs this project after this run.
+
+    Downstream the budget is advisory (R4): the plugin measures its own block
+    and says what it costs, but a project's own file is never refused. A block
+    that is over budget and still the one the plugin installed is the plugin's
+    to trim; an edited one is the project's."""
+    try:
+        cap = render_instructions.budgets(render_instructions.DEFAULT_SOURCE).get("project")
+    except render_instructions.RenderError:
+        return
+    if not cap:
+        return
+    for rt in runtimes:
+        name, block_tpl, _ = paths.INSTRUCTION_FILE[rt]
+        text = plan.read(name)
+        if text is None:
+            continue
+        block = render_instructions.block_of(text.decode("utf-8", "replace"))
+        if block is None:
+            continue
+        size = len(block.encode("utf-8"))
+        if size <= cap:
+            continue
+        shipped = files_mod.read(os.path.join(paths.TEMPLATES["ai-init"], block_tpl)).rstrip(b"\n")
+        whose = ("the plugin ships it that size — report it"
+                 if block.encode("utf-8").rstrip() == shipped
+                 else "it was edited here, so the plugin will not rewrite it: trimming it is yours")
+        plan.hints.append("%s: the managed block is %d B, budget %d B — %s"
+                          % (name, size, cap, whose))
+
+
+def constitution_hint(plan):
+    """R10: the cap is hard for the shipped template and advisory for a project.
+    The rule lives in render_instructions; this only relays what it says."""
+    rel = "docs/sdlc/constitution.md"
+    path = os.path.join(plan.root, rel)
+    if not os.path.isfile(path):
+        return
+    err = io.StringIO()
+    with contextlib.redirect_stderr(err):
+        render_instructions.constitution(path, out=io.StringIO())
+    for line in err.getvalue().splitlines():
+        plan.hints.append(line.replace(path, rel))
+
+
+def verification_hints(plan):
+    """R10: update's empty-field hints read verification.md."""
+    text = plan.read(paths.VERIFICATION_MD)
+    if text is None:
+        return
+    for field, why in (
+        ("verify_command", "the feedback loop needs it"),
+        ("step_test_command", "a step runs only its own tests"),
+        ("e2e_command", "e2e runs once at the end of a task; write 'none' if there is no suite"),
+        ("lint_command", "a sensor reads it; read the project's config files for it, and write 'none' if there is none"),
+        ("typecheck_command", "a sensor reads it; read the project's config files for it, and write 'none' if there is none"),
+    ):
+        if re.search(rb"(?m)^" + field.encode() + rb":[ \t]*(#.*)?$", text):
+            plan.hints.append("%s: %s is empty — %s" % (paths.VERIFICATION_MD, field, why))
+        elif not re.search(rb"(?m)^" + field.encode() + rb":", text):
+            plan.hints.append("%s: %s is missing — %s" % (paths.VERIFICATION_MD, field, why))

package/skills/project-update/rr_update/history.py

@@ -0,0 +1,117 @@
+"""What the plugin shipped and what a project declares: the schema error, the project's runtimes, the shipped-template history, the shared tree, the schema numbers.
+
+shell: project_runtimes, History, shared_files, undeclared_shared, template_version, project_version
+core: SchemaError
+"""
+
+import json
+import os
+import re
+
+from rr_update import files
+from rr_update import paths
+
+
+class SchemaError(Exception):
+    """The project's schema cannot be read or is newer than this plugin."""
+
+
+
+def project_runtimes(root):
+    """The runtimes a project declares, or the one this plugin copy serves."""
+    out = []
+    if os.path.exists(os.path.join(root, "CLAUDE.md")) or os.path.isdir(os.path.join(root, ".claude")):
+        out.append("claude")
+    if os.path.exists(os.path.join(root, "AGENTS.md")) or os.path.isdir(os.path.join(root, ".codex")):
+        out.append("codex")
+    if os.path.exists(os.path.join(root, "GEMINI.md")) or os.path.isdir(os.path.join(root, ".gemini")):
+        out.append("gemini")
+    if os.path.isdir(os.path.join(root, ".junie")):
+        out.append("junie")
+    if not out:
+        out.append("codex" if "/.codex/" in paths.HERE + "/" else "claude")
+    return out
+
+
+
+class History:
+    """index.json answers "was this ever shipped" from hashes alone; the blobs
+    give the one-time split its base values."""
+
+    def __init__(self, root):
+        try:
+            with open(os.path.join(root, "index.json"), encoding="utf-8") as fh:
+                self.index = json.load(fh)
+        except (OSError, ValueError, RecursionError):
+            self.index = {}
+        self.root = root
+
+    def versions(self, key):
+        """Every shipped version of a template, oldest first, as bytes."""
+        out = []
+        for h in self.index.get(key, []):
+            try:
+                out.append(files.read(os.path.join(self.root, "blobs", h)))
+            except OSError:
+                pass
+        return out
+
+    def hashes(self, key):
+        """The sha of every version shipped under this key; a version whose blob is gone still counts."""
+        return set(self.index.get(key, []))
+
+    def shipped(self, key, data):
+        """True when these bytes are a version the plugin shipped, also after a checkout turned its line endings into CRLF."""
+        known = self.hashes(key)
+        return files.sha(data) in known or files.sha(data.replace(b"\r\n", b"\n")) in known
+
+
+def shared_files():
+    """{".ai/<rel>": bytes} for every shared file the shared tree holds; empty when the tree is not installed."""
+    out = {}
+    for path in sorted(paths.SHARED_SET):
+        full = os.path.join(paths.SHARED, path[len(".ai/"):])
+        if os.path.isfile(full):
+            out[path] = files.read(full)
+    return out
+
+
+def undeclared_shared():
+    """Files in the shared tree outside the shared set, as .ai/ paths."""
+    out = []
+    for here, _dirs, names in os.walk(paths.SHARED):
+        for name in names:
+            rel = ".ai/" + os.path.relpath(os.path.join(here, name), paths.SHARED).replace(os.sep, "/")
+            if rel not in paths.SHARED_SET:
+                out.append(rel)
+    return sorted(out)
+
+
+
+def template_version():
+    """The schema number this plugin ships (its .ai/VERSION template)."""
+    return int(files.read(os.path.join(paths.TEMPLATES["ai-init"], paths.VERSION_FILE)).decode().strip())
+
+
+def project_version(root):
+    """The project's .ai/VERSION: 0 when there is none; SchemaError when it cannot
+    be read, is not a number, or is newer than this plugin's."""
+    path = os.path.join(root, paths.VERSION_FILE)
+    try:
+        raw = files.read(path) if os.path.lexists(path) else None
+    except OSError as exc:  # a directory, a mode-000 file, a dangling link
+        raise SchemaError("%s cannot be read: %s" % (paths.VERSION_FILE, exc)) from exc
+    if raw is None:
+        return 0
+    try:
+        text = raw.decode("utf-8").strip()
+    except UnicodeDecodeError:
+        text = ""
+    if not re.fullmatch(r"\d+", text):
+        raise SchemaError("%s is not a schema number: %r" % (paths.VERSION_FILE, raw[:40]))
+    ours = template_version()
+    if int(text) > ours:
+        raise SchemaError("%s says schema %s, this plugin ships schema %d — update the plugin "
+                          "(riskrails/install.sh)" % (paths.VERSION_FILE, text, ours))
+    return int(text)
+

package/skills/project-update/rr_update/kept.py

@@ -0,0 +1,120 @@
+"""What a regenerate must not overwrite: the old markers, the kept-file check, the old file shapes, the refusal text.
+
+shell: check_kept, old_shapes, kept_refusal
+core: tomllib, OLD_MARKERS
+"""
+
+import json
+import os
+
+try:
+    import tomllib
+except ImportError:  # Python before 3.11: .codex/config.toml is not checked
+    tomllib = None
+
+import render_instructions  # next to the entry, whose directory the entry puts on sys.path
+
+from rr_update import files
+from rr_update import paths
+from rr_update import siblings
+
+
+# Old shapes the update no longer converts: literal checks, nothing parsed (D4).
+OLD_MARKERS = (b"<!-- claude-agentic:", b"<!-- Codex-agentic:")
+
+
+def check_kept(root):
+    """[(path, reason)] for every kept file its own reader cannot take and every old
+    shape this version no longer converts. Reads only: the caller refuses on a
+    non-empty answer before anything is written (R12)."""
+    bad = []
+
+    def raw_of(rel):
+        path = os.path.join(root, rel)
+        if not os.path.lexists(path):
+            return None
+        try:
+            return files.read(path)
+        except OSError as exc:
+            bad.append((rel, "cannot be read: %s" % (exc.strerror or exc)))
+            return None
+
+    def json_object(rel, data):
+        try:
+            doc = json.loads(data.decode("utf-8"))
+        except (ValueError, RecursionError) as exc:  # UnicodeDecodeError is a ValueError
+            bad.append((rel, "is not valid JSON (%s)" % (type(exc).__name__ if isinstance(exc, RecursionError) else exc)))
+            return None
+        if not isinstance(doc, dict):
+            bad.append((rel, "is not a JSON object"))
+            return None
+        return doc
+
+    for rel in (paths.STATE_FILE, ".ai/policies/dialog.json", ".ai/policies/memory.json", ".claude/settings.json"):
+        data = raw_of(rel)
+        if data is not None:
+            json_object(rel, data)
+    data = raw_of(paths.WEIGHT_PROJECT)
+    if data is not None:
+        doc = json_object(paths.WEIGHT_PROJECT, data)
+        if doc is not None and doc.get("version") != 1:
+            bad.append((paths.WEIGHT_PROJECT, "has no \"version\": 1"))
+        elif doc is not None:
+            try:
+                siblings.weight_overlay().load(siblings.shipped_weight(), os.path.join(root, paths.WEIGHT_PROJECT))
+            except ValueError as exc:
+                bad.append((paths.WEIGHT_PROJECT, str(exc).split(": ", 1)[-1]))
+    data = raw_of(paths.VERIFICATION_MD)
+    if data is not None:
+        try:
+            data.decode("utf-8")
+        except UnicodeDecodeError:
+            bad.append((paths.VERIFICATION_MD, "is not UTF-8 text"))
+    data = raw_of(".codex/config.toml")
+    if data is not None and tomllib is not None:
+        try:
+            tomllib.loads(data.decode("utf-8"))
+        except ValueError as exc:  # TOMLDecodeError and UnicodeDecodeError
+            bad.append((".codex/config.toml", "is not valid TOML (%s)" % exc))
+    # the old weight.json is read once, by the split, so it must parse then
+    if not os.path.lexists(os.path.join(root, paths.WEIGHT_PROJECT)):
+        data = raw_of(paths.WEIGHT_JSON)
+        if data is not None:
+            json_object(paths.WEIGHT_JSON, data)
+    old_shapes(root, bad)
+    return bad
+
+
+def old_shapes(root, bad):
+    """The four literal detectors of an older riskrails' files (D4)."""
+    exists = lambda rel: os.path.lexists(os.path.join(root, rel))  # noqa: E731
+    if exists(".ai/state/current.json") and not exists(paths.STATE_FILE):
+        bad.append((".ai/state/current.json", "is the task state of a riskrails before 3.4b (there is no state.json)"))
+    if exists(".ai/policies/risk-tiers.json") and not exists(paths.WEIGHT_JSON) and not exists(paths.WEIGHT_PROJECT):
+        bad.append((".ai/policies/risk-tiers.json", "is the risk-tier policy of a riskrails before 2.2 (there is no weight table)"))
+    names = set(render_instructions.RULE_FILE.values()) | {e[0] for e in paths.INSTRUCTION_FILE.values()}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in paths.RULES_SKIP
+                             and not os.path.lexists(os.path.join(dirpath, d, ".git")))
+        for name in filenames:
+            rel = os.path.relpath(os.path.join(dirpath, name), root).replace(os.sep, "/")
+            if name not in names and rel not in names:
+                continue
+            try:
+                data = files.read(os.path.join(root, rel))
+            except OSError:
+                continue  # an unreadable instruction file is the plan's to report, not an old shape
+            found = next((m for m in OLD_MARKERS if m in data), None)
+            if found:
+                bad.append((rel, "carries %s of a riskrails before 3.4b" % found.decode()))
+
+
+def kept_refusal(bad):
+    """I3, verbatim: one line per failing file, then the rest."""
+    for rel, why in bad:
+        print("KEPT_UNREADABLE: %s: %s" % (rel, why))
+    print("project-update: nothing was deleted or written. This version regenerates its own files and no longer "
+          "converts older ones.")
+    print("Install riskrails@%s (npx riskrails@%s), run /rr-setup --update with it, then install this version "
+          "and run /rr-setup --update again." % (paths.LAST_MIGRATING_VERSION, paths.LAST_MIGRATING_VERSION))
+    return paths.EXIT_KEPT_UNREADABLE