riskrails 4.0.1 → 4.2.0

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

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

@@ -0,0 +1,108 @@
+"""Where things are: the skill's directories, the environment's overrides, and the literal path tables the update reads.
+
+shell: env, HERE, SKILLS, TEMPLATES, HISTORY, PLUGIN_HOME, SHARED
+core: LAST_MIGRATING_VERSION, EXIT_KEPT_UNREADABLE, REFUSED, VERSION_FILE, ROUTER_FILE, STALE_DAYS, STATE_FILE, TESTING_MD, VERIFICATION_MD, WEIGHT_JSON, WEIGHT_MD, WEIGHT_PROJECT, LOCAL_CACHE, GENERATED, CREATE_ONLY, CREATE_ONLY_DIRS, NOT_COPIED, KEPT, is_kept, SHARED_SET, RULES_DIR, RULES_SKIP, RULES_SKIP_FOLDED, RUNTIME_MAP, SDLC_CREATE, INSTRUCTION_FILE
+"""
+
+import os
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # the skill directory, one above this package
+SKILLS = os.path.dirname(HERE)
+LAST_MIGRATING_VERSION = "3.1.0"  # the last riskrails that converts older trees; I3 names it
+EXIT_KEPT_UNREADABLE = 6
+REFUSED = "CONFIRM_REFUSED"
+
+
+def env(name, default=None):
+    """RISKRAILS_<name>."""
+    return os.environ.get("RISKRAILS_" + name, default)
+
+
+
+TEMPLATES = {
+    "ai-init": env("TEMPLATES", os.path.join(SKILLS, "ai-init", "templates")),
+    "project-init": os.environ.get("CLAUDE_ROUTING_TEMPLATES", os.path.join(SKILLS, "project-init", "templates")),
+}
+HISTORY = env("HISTORY", os.path.join(HERE, "history"))
+# The shared tree every project reads unless it keeps its own copy: installed
+# beside the skills as riskrails/ai, or ai/ at the root of a checkout.
+PLUGIN_HOME = os.path.dirname(SKILLS)
+SHARED = env("SHARED") or next(
+    (p for p in (os.path.join(PLUGIN_HOME, "riskrails", "ai"), os.path.join(PLUGIN_HOME, "ai"))
+     if os.path.isdir(p)), os.path.join(PLUGIN_HOME, "riskrails", "ai"))
+VERSION_FILE = ".ai/VERSION"
+ROUTER_FILE = ".ai/AGENTS.md"
+STALE_DAYS = 7  # an unclosed task whose last event is older is proposed for cleanup
+STATE_FILE = ".ai/state/state.json"
+TESTING_MD = ".ai/policies/testing.md"
+VERIFICATION_MD = ".ai/policies/verification.md"
+WEIGHT_JSON, WEIGHT_MD = ".ai/policies/weight.json", ".ai/policies/weight.md"
+WEIGHT_PROJECT = ".ai/policies/weight.project.json"
+LOCAL_CACHE = ".ai/local/plugin-update"
+
+# D2. GENERATED targets copied from a template as they are. weight.md is rendered,
+# .ai/VERSION is written last, the managed blocks and the runtimes' memory READMEs
+# come from the maps below.
+GENERATED = (ROUTER_FILE, ".ai/policies/path-guard.json", ".ai/policies/coding.md", ".ai/policies/safety.md",
+             ".ai/policies/security.md", TESTING_MD, ".ai/rules/README.md", ".ai/state/README.md")
+# Template files created when missing and never touched again: the project's own from then on.
+CREATE_ONLY = (VERIFICATION_MD, WEIGHT_PROJECT, ".ai/reports/.gitkeep")
+CREATE_ONLY_DIRS = (".ai/project/",)
+# Template files that are not copied: written last, the plugin's own table, the human's switch.
+NOT_COPIED = (VERSION_FILE, WEIGHT_JSON, WEIGHT_MD, ".ai/policies/dialog.json")
+KEPT = (".ai/project/", ".ai/reports/", ".ai/memory/", ".ai/state/", "docs/sdlc/", ".ai/local/memory/",
+        WEIGHT_PROJECT, VERIFICATION_MD, ".ai/policies/dialog.json", ".ai/policies/memory.json",
+        ".claude/settings.json", ".codex/config.toml", ".gitignore")
+
+
+def is_kept(path):
+    """True for a path update.py never rewrites. A GENERATED path under a KEPT
+    directory (.ai/state/README.md) is generated: the two sets are disjoint."""
+    if path in GENERATED:
+        return False
+    return any(path == k or (k.endswith("/") and path.startswith(k)) for k in KEPT)
+
+
+# The shared set, literally: the plugin's tree must equal it (tested). A project
+# copy identical to a shipped version is offered for deletion; an edited one is an override.
+SHARED_SET = frozenset((
+    ".ai/policies/production.md", ".ai/policies/database.md", ".ai/policies/git.md", ".ai/policies/release.md",
+    ".ai/policies/context-management.md", ".ai/policies/tooling.md", ".ai/policies/model-routing.md",
+    ".ai/policies/review-economy.md",
+    ".ai/agents/context.md", ".ai/agents/discovery.md", ".ai/agents/implementer.md",
+    ".ai/agents/planner.md", ".ai/agents/release.md", ".ai/agents/reviewer.md", ".ai/agents/risk.md",
+    ".ai/agents/security.md", ".ai/agents/tester.md",
+    ".ai/templates/task-context.md", ".ai/templates/impact-report.md", ".ai/templates/review-report.md",
+    ".ai/templates/release-report.md", ".ai/templates/architecture-decision.md",
+    ".ai/templates/implementation-plan.md",
+    ".ai/using-riskrails.md", ".ai/workflows.md",
+))
+RULES_DIR = ".ai/rules"
+# Directories a stale rule block is never hunted in: a dependency's instruction
+# file is not ours (the path guard refuses it too), and .git is not text.
+# A child holding a .git entry (worktree, nested repository, submodule) is pruned
+# too, by the take-back walk (rendered_rules) and by the writer (nested_tree). The
+# writer also skips a RULES_SKIP name or a symlinked directory (unwalked_dir), so it
+# never writes where the take-back never walks.
+RULES_SKIP = {".git", ".ai", "vendor", "node_modules", "bower_components",
+              "third_party", "Pods", "site-packages", ".venv", ".pnpm", ".yarn"}
+# Compared case-insensitively: on a case-insensitive filesystem `Vendor/` is `vendor/`.
+RULES_SKIP_FOLDED = frozenset(n.casefold() for n in RULES_SKIP)
+
+RUNTIME_MAP = {  # the per-runtime layer of the project-init scaffold: template, target, kind
+    "claude": [("memory-README.md", ".claude/memory/README.md", "regenerate"),
+               ("project-settings.json", ".claude/settings.json", "create")],
+    "codex":  [("memory-README.md", ".codex/memory/README.md", "regenerate"),
+               ("project-config.toml", ".codex/config.toml", "create")],
+    "gemini": [("memory-README.md", ".gemini/memory/README.md", "regenerate")],
+    "junie":  [("memory-README.md", ".junie/memory/README.md", "regenerate")],
+}
+SDLC_CREATE = (("sdlc-README.md", "docs/sdlc/README.md"), ("constitution.md", "docs/sdlc/constitution.md"))
+INSTRUCTION_FILE = {  # runtime -> (file, block template, minimal template)
+    "claude": ("CLAUDE.md", "CLAUDE.block.md", "CLAUDE.minimal.md"),
+    "codex":  ("AGENTS.md", "AGENTS.block.md", "AGENTS.minimal.md"),
+    "gemini": ("GEMINI.md", "GEMINI.block.md", "GEMINI.minimal.md"),
+    "junie":  (".junie/guidelines.md", "junie-guidelines.block.md",
+               "junie-guidelines.minimal.md"),
+}
+

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

@@ -0,0 +1,123 @@
+"""The plan one run builds and the decisions about one file: lost lines, patterns, the note on an edited copy, the regenerate rule.
+
+shell: Plan, regenerate
+core: lost_lines, patterns_of, edited_note
+"""
+
+import json
+import os
+from datetime import datetime, timezone
+
+from rr_update import files
+
+
+# ---------------------------------------------------------------- planning
+class Plan:
+    def __init__(self, root):
+        self.root = root
+        self.items = []   # dicts: action, target, note, content, reason, keep, expect
+        self.hints = []
+        self.confirm_delete = None  # the human who confirmed this run's gated rows
+        self.confirm_via = None  # why that gate passed: "terminal" or "unattended"
+        self.confirm_cleanup = None  # the human who confirmed this run's [cleanup] deletions
+        self.cleanup_via = None
+        self.version_from = None  # the .ai/VERSION this run started from
+        self.final = {}   # target -> bytes after this run (for cross-file fixes)
+        self.removed = set()  # targets this run takes away
+        self.seen = {}    # target -> sha of what was on disk when it was first read,
+        #                   or None when nothing was there: apply's precondition
+        self.git_kept = set()  # [cleanup] targets git holds or should hold: a hint and an original/ copy
+        self.report_dir = ".ai/reports/project-update-%s" % datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    # The project as this run leaves it: planned content first, then the disk.
+    # File readers in the planning path go through these, not the disk.
+    def exists(self, target):
+        if target in self.final:
+            return True
+        return target not in self.removed and os.path.exists(os.path.join(self.root, target))
+
+    def read(self, target):
+        if target in self.final:
+            return self.final[target]
+        if not self.exists(target):
+            return None
+        data = files.read(os.path.join(self.root, target))
+        self.seen.setdefault(target, files.sha(data))  # what apply must find there
+        return data
+
+    def remove(self, target):
+        self.final.pop(target, None)
+        self.removed.add(target)
+
+    def before(self, target):
+        """The sha of the target as this run first read it, None when it was
+        absent. Recorded by the read that planned the change, so the precondition
+        and the planning input are the same bytes."""
+        if target not in self.seen:
+            path = os.path.join(self.root, target)
+            self.seen[target] = files.sha(files.read(path)) if os.path.isfile(path) and not os.path.islink(path) else None
+        return self.seen[target]
+
+    def add(self, action, target, note="", content=None, reason=None, keep=False):
+        self.items.append(dict(action=action, target=target, note=note, content=content,
+                               reason=reason, keep=keep, expect=self.before(target)))
+        if content is not None:
+            self.final[target] = content
+            self.removed.discard(target)  # planned content wins over an earlier removal
+
+    def original_of(self, target):
+        return "%s/original/%s" % (self.report_dir, target)
+
+    def gated(self, action, target, note, content=None, reason=None):
+        """A change that waits for a human: `regenerate?` / `delete?` until
+        --apply --confirm-delete NAME, then `regenerate` / `delete` with the original kept
+        under original/ (R7)."""
+        if self.confirm_delete:
+            self.add(action, target, note, content=content, reason=reason, keep=True)
+            if action == "delete":
+                self.remove(target)
+        else:
+            self.add(action + "?", target, note, reason=reason)
+
+
+# ---------------------------------------------------------------- regenerate
+def lost_lines(ours, theirs):
+    """The lines of the project's copy that the plugin's version does not have."""
+    kept = set(theirs.decode("utf-8", "replace").splitlines())
+    return [line.strip() for line in ours.decode("utf-8", "replace").splitlines()
+            if line.strip() and line not in kept]
+
+
+def patterns_of(data):
+    """The count of non-empty deny and allow patterns in a path-guard.json, or None when it is not one."""
+    try:
+        doc = json.loads(data)
+        return sum(1 for key in ("deny_patterns", "allow_patterns") for p in doc.get(key) or []
+                   if isinstance(p, str) and p.strip())
+    except (ValueError, AttributeError, TypeError, RecursionError):
+        return None
+
+
+def edited_note(plan, target, ours, theirs):
+    """What a gated regenerate would lose, and where the original goes (R6)."""
+    lost = lost_lines(ours, theirs)
+    shown = "; ".join("`%s`" % (line[:48] + ("…" if len(line) > 48 else "")) for line in lost[:3])
+    note = "edited here: %d line(s) of yours are not in the plugin's version%s" % (len(lost), " (" + shown + ")" if shown else "")
+    if target.endswith("path-guard.json"):
+        count = patterns_of(ours)
+        note += "; drops %s deny/allow pattern(s)" % ("an unreadable number of" if count is None else count)
+    return "%s; original kept at %s" % (note, plan.original_of(target))
+
+
+def regenerate(plan, history, key, target, theirs):
+    """D5: absent -> create; equal -> nothing; a version the plugin once shipped -> regenerate;
+    anything else is the human's edit -> regenerate? behind the gate."""
+    ours = plan.read(target)
+    if ours is None:
+        plan.add("create", target, content=theirs)
+    elif ours == theirs:
+        return
+    elif history.shipped(key, ours):
+        plan.add("regenerate", target, "unchanged since it was installed", content=theirs)
+    else:
+        plan.gated("regenerate", target, edited_note(plan, target, ours, theirs), content=theirs)

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

@@ -0,0 +1,51 @@
+"""The report of a run: one line per item, the hints and the summary.
+
+shell: report
+"""
+
+
+def report(plan, applied):
+    auto = [i for i in plan.items if i["action"] not in ("delete?", "regenerate?")]
+    gated = [i for i in plan.items if i["action"] in ("delete?", "regenerate?")]
+    head = "applied" if applied else "dry run, nothing written; --apply to write"
+    print("project-update: %s (%s)" % (plan.root, head))
+    if not plan.items:
+        print("  up to date with the installed plugin")
+    # a cleanup is one line per directory, however many files it holds
+    rows, groups = [], {}
+    for i in plan.items:
+        if (i["reason"] or "").startswith("[cleanup]"):
+            parts = i["target"].split("/")
+            where = "/".join(parts[:4] if i["target"].startswith(".ai/state/logs/") else parts[:3])
+            key = (where, i["action"], i["note"])
+            if key in groups:
+                groups[key]["count"] += 1
+                continue
+            row = dict(i, count=1)
+            groups[key] = row
+            row["target"] = where
+            i = row
+        rows.append(i)
+    for (where, _action, _note), row in groups.items():
+        row["target"] = "%s/ (%d file%s)" % (where, row["count"], "" if row["count"] == 1 else "s")
+    width = max([len(i["target"]) for i in rows] + [10])
+    for i in rows:
+        note = i["note"]
+        if i["action"] in ("delete?", "regenerate?"):
+            if (i["reason"] or "").startswith("[cleanup]"):
+                note += "; needs --apply --confirm-cleanup NAME"
+                if i["target"].startswith(".ai/state/"):
+                    note += " (git-ignored: not recoverable through git)"
+            else:
+                note += "; needs --apply --confirm-delete NAME"
+        print("  %-9s %-*s  %s" % (i["action"], width, i["target"], note))
+    for h in plan.hints:
+        print("  hint      " + h)
+    tail = ""
+    # the summary names the flag each row names: [cleanup] rows settle with --confirm-cleanup only
+    cleanups = [i for i in gated if (i["reason"] or "").startswith("[cleanup]")]
+    if len(gated) > len(cleanups):
+        tail += ", %d change(s) awaiting --confirm-delete" % (len(gated) - len(cleanups))
+    if cleanups:
+        tail += ", %d cleanup file(s) awaiting --confirm-cleanup" % len(cleanups)
+    print("%d automatic%s" % (len(auto), tail))