riskrails 4.1.0 → 4.3.0

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))

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

@@ -0,0 +1,178 @@
+"""The project rules: where they come from, how they render, the nested tree, and the rules rows of the plan.
+
+shell: rule_sources, rendered_rules, nested_tree, unwalked_dir, _frozen_block, rules_update
+"""
+
+import os
+
+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
+
+
+def rule_sources(plan):
+    """OQ1: a rule source is not kept. Each `.ai/rules/<slug>.md` is `delete?` behind the gate with its
+    original copied; until it is confirmed the rule stays rendered."""
+    rules = os.path.join(plan.root, paths.RULES_DIR)
+    for name in sorted(os.listdir(rules)) if os.path.isdir(rules) else []:
+        rel = "%s/%s" % (paths.RULES_DIR, name)
+        if name.endswith(".md") and name != "README.md" and os.path.isfile(os.path.join(rules, name)) \
+                and not files.unsafe_path(plan.root, rel):
+            why = "[rules] rule sources are not kept by an update: the rendered blocks go with it"
+            plan.gated("delete", rel, why, reason=why)
+
+
+def rendered_rules(plan):
+    """Every (file, slug) in the project that carries a rule block today, plus
+    every path-scoped copy under .claude/rules/. Walked rather than remembered:
+    a manifest would be one more file to keep true, and the markers already say
+    who wrote them."""
+    blocks, docs = [], []
+    names = set(render_instructions.RULE_FILE.values())
+    for dirpath, dirnames, filenames in os.walk(plan.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")))
+        rel_dir = os.path.relpath(dirpath, plan.root)
+        for name in sorted(filenames):
+            rel = name if rel_dir == "." else os.path.join(rel_dir, name)
+            rel = rel.replace(os.sep, "/")
+            if name in names:
+                text = plan.read(rel)
+                if text is None:
+                    continue
+                for slug in render_instructions.rule_slugs_in(text.decode("utf-8", "replace")):
+                    blocks.append((rel, slug))
+            elif rel.startswith(render_instructions.CLAUDE_RULES_DIR + "/") and name.endswith(".md"):
+                text = plan.read(rel)
+                if text is not None and render_instructions.RULE_GENERATED % name[:-3] in \
+                        text.decode("utf-8", "replace"):
+                    docs.append(rel)
+    return blocks, docs
+
+
+def nested_tree(root, rel_dir):
+    """The first directory below the root on the way to `rel_dir`, `rel_dir`
+    included, that holds a .git entry (a worktree, a nested repository, a
+    submodule), or None. The same predicate rendered_rules() prunes on."""
+    # "." and "" are the root itself (dirs: ["."] reaches here as ""), whose
+    # own .git is not a nested tree.
+    parts = [p for p in rel_dir.split("/") if p not in ("", ".")]
+    for i in range(1, len(parts) + 1):
+        candidate = "/".join(parts[:i])
+        if os.path.lexists(os.path.join(root, candidate, ".git")):
+            return candidate
+    return None
+
+
+def unwalked_dir(root, rel_dir):
+    """Why the take-back walk (rendered_rules) never enters `rel_dir`, or None:
+    a RULES_SKIP name on the way, or a symlinked directory on the way."""
+    here = root
+    for part in (p for p in rel_dir.split("/") if p not in ("", ".")):
+        here = os.path.join(here, part)
+        if part.casefold() in paths.RULES_SKIP_FOLDED:
+            return "%s is under a directory the take-back never walks (%s)" % (rel_dir, part)
+        if os.path.islink(here):
+            return "%s is a symlink, which the take-back never follows" % os.path.relpath(here, root).replace(os.sep, "/")
+    return None
+
+
+def _frozen_block(plan, target, slug):
+    """True when `target` is a readable regular file inside the project, holding a
+    block for `slug`, at a place the take-back walk (rendered_rules) never enters: a
+    RULES_SKIP name or a nested git tree on its real path. A symlink that leads inside
+    the walked part of the project is removed by the same run; one that leads outside
+    the project, a directory, a FIFO or an unreadable file is not read at all."""
+    full = os.path.join(plan.root, target)
+    try:
+        real = os.path.realpath(full)
+        base = os.path.realpath(plan.root)
+        if os.path.commonpath([real, base]) != base or not os.path.isfile(real):
+            return False
+        rel_dir = os.path.relpath(os.path.dirname(real), base).replace(os.sep, "/")
+        parts = [p for p in rel_dir.split("/") if p not in ("", ".")]
+        if not (any(p in paths.RULES_SKIP for p in parts) or nested_tree(base, rel_dir) is not None):
+            return False
+        held = plan.read(target)
+    except (OSError, ValueError):
+        return False
+    return held is not None and slug in render_instructions.rule_slugs_in(held.decode("utf-8", "replace"))
+
+
+def rules_update(plan, runtimes):
+    """Render `.ai/rules/<slug>.md` into the instruction file of every directory
+    it names, and take back what a rule no longer asks for. The text around a
+    block belongs to the project and is never read for meaning, only preserved.
+    A rule whose source this run deletes is no longer rendered."""
+    rules_path = os.path.join(plan.root, paths.RULES_DIR)
+    if not os.path.isdir(rules_path):
+        return
+    try:
+        rules = [r for r in render_instructions.load_rules(rules_path)
+                 if "%s/%s.md" % (paths.RULES_DIR, r.slug) not in plan.removed]
+    except render_instructions.RenderError as exc:
+        plan.hints.append("%s — that rule is not rendered; the rest are" % exc)
+        return
+    wanted = render_instructions.rule_targets(rules, runtimes)
+    managed = {(i["target"], i["slug"]) for i in wanted if i["kind"] == "block"}
+    kept_docs = {i["target"] for i in wanted if i["kind"] == "doc"}
+
+    for item in wanted:
+        source = "%s/%s.md" % (paths.RULES_DIR, item["slug"])
+        target, content = item["target"], item["content"]
+        tree = nested_tree(plan.root, os.path.dirname(target)) if item["kind"] == "block" else None
+        if tree is not None:
+            # Not this project's file, and the take-back never walks there: a
+            # block written there could never be taken back again.
+            plan.hints.append("%s: %s is a nested git tree (worktree, repository or submodule)"
+                              " — rule %s is not rendered there" % (target, tree, item["slug"]))
+            continue
+        skip = unwalked_dir(plan.root, os.path.dirname(target)) if item["kind"] == "block" else None
+        if skip is not None:
+            hint = "%s: %s — rule %s is not rendered there" % (target, skip, item["slug"])
+            if _frozen_block(plan, target, item["slug"]):
+                hint += ("; an earlier rendering of it is still there, the take-back never walks there:"
+                         " remove that block by hand")
+            plan.hints.append(hint)
+            continue
+        current = plan.read(target)
+        if item["kind"] == "doc":
+            new = content.encode()
+            if current is None:
+                plan.add("create", target, "rendered from " + source, content=new)
+            elif current != new:
+                plan.add("regenerate", target, "rendered from " + source, content=new)
+            continue
+        text = "" if current is None else current.decode("utf-8")
+        new = render_instructions.splice_rule(text, item["slug"], content).encode()
+        if current is None:
+            plan.add("create", target, "rule block %s from %s" % (item["slug"], source),
+                     content=new)
+        elif current != new:
+            plan.add("regenerate", target, "rule block %s from %s" % (item["slug"], source),
+                     content=new)
+
+    blocks, docs = rendered_rules(plan)
+    for target, slug in blocks:
+        if (target, slug) in managed:
+            continue
+        text = plan.read(target).decode("utf-8")
+        # The block is ours; the file is not. Take the block, leave the file.
+        plan.add("regenerate", target, "rule block %s removed (%s/%s.md no longer renders here)"
+                 % (slug, paths.RULES_DIR, slug),
+                 content=render_instructions.strip_rule(text, slug).encode())
+    for target in docs:
+        if target in kept_docs:
+            continue
+        # The whole file is a rendered copy, so taking it away is a deletion, and
+        # a deletion waits for a human exactly as a migration's does.
+        slug = os.path.basename(target)[:-3]
+        why = "[rules] %s" % ("%s/%s.md no longer sets paths:" % (paths.RULES_DIR, slug)
+                              if slug in {r.slug for r in rules}
+                              else "source %s/%s.md is gone" % (paths.RULES_DIR, slug))
+        if plan.confirm_delete:
+            plan.add("delete", target, why, reason=why)
+            plan.remove(target)
+        else:
+            plan.add("delete?", target, why, reason=why)

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

@@ -0,0 +1,74 @@
+"""The shared tree: refusing to drop a copy whose fallback is missing, and the shared-copy rows of the plan.
+
+shell: require_shared, shared_update
+"""
+
+import os
+
+from rr_update import files
+from rr_update import history as history_mod
+from rr_update import paths as paths_mod
+
+
+# ---------------------------------------------------------------- shared files, rules, caches
+def require_shared(paths, runtimes):
+    """Refuse, before anything is written, to drop a project copy whose shared fallback is missing:
+    in this plugin's tree, or in another installed home of a runtime the project declares. A home
+    this machine does not have is not checked."""
+    undeclared = sorted(p for p in paths if p not in paths_mod.SHARED_SET)
+    if undeclared:
+        raise history_mod.SchemaError("not in the shared set, never deleted as a shared copy: %s" % ", ".join(undeclared))
+    rels = sorted(p[len(".ai/"):] for p in paths)
+    missing = [r for r in rels if not os.path.isfile(os.path.join(paths_mod.SHARED, r))]
+    if missing:
+        raise history_mod.SchemaError("the plugin's shared tree %s lacks %d file(s) a project copy would fall back to: %s — "
+                          "reinstall the plugin (install.sh), then run this again" % (paths_mod.SHARED, len(missing), ", ".join(missing)))
+    homes = {"claude": os.path.join(os.path.expanduser("~"), ".claude"),
+             "codex": os.environ.get("CODEX_HOME") or os.path.join(os.path.expanduser("~"), ".codex")}
+    mine = os.path.realpath(paths_mod.PLUGIN_HOME)
+    for runtime in runtimes:
+        home = homes.get(runtime)
+        if (not home or os.path.realpath(home) == mine
+                or not os.path.isdir(os.path.join(home, "skills", "project-update"))):
+            continue
+        tree = os.path.join(home, "riskrails", "ai")
+        missing = [r for r in rels if not os.path.isfile(os.path.join(tree, r))]
+        if missing:
+            raise history_mod.SchemaError("%s has this plugin installed for %s, but %d of the %d shared file(s) a project copy "
+                              "would fall back to are missing from %s — run `install.sh --target %s` from this "
+                              "build, then run this again" % (home, runtime, len(missing), len(rels), tree, runtime))
+
+
+def shared_update(plan, history, runtimes):
+    """R17: an unedited copy of a shared file is offered for deletion; an edited one is an
+    override, kept, and named once (OQ8)."""
+    edited, candidates = [], []
+    extra = history_mod.undeclared_shared()
+    if extra:
+        plan.hints.append("the shared tree %s holds %d file(s) outside the shared set, ignored — reinstall the "
+                          "plugin (install.sh) if you did not put them there: %s" % (paths_mod.SHARED, len(extra), ", ".join(extra)))
+    for path in sorted(history_mod.shared_files()):
+        data = plan.read(path)
+        if data is None:
+            continue
+        why = files.unsafe_path(plan.root, path)
+        if why:
+            plan.hints.append("%s: %s, so this update never deletes it — check by hand whether it is still "
+                              "needed" % (path, why))
+        elif not history.shipped("ai-init/" + path, data):
+            edited.append(path)
+        else:
+            candidates.append(path)
+    if candidates:
+        try:
+            require_shared(candidates, runtimes)
+        except history_mod.SchemaError as exc:
+            plan.hints.append("%s — the copies stay until then" % exc)
+            candidates = []
+    for path in candidates:
+        why = "[shared] identical to a shipped version"
+        plan.gated("delete", path, why, reason=why)
+    if edited:
+        plan.hints.append("%d file(s) override the plugin's shared copy and no longer receive its changes: %s — "
+                          "diff each against %s/<path>; `ai-path <path>` shows which applies; delete one when it "
+                          "adds nothing" % (len(edited), ", ".join(edited), paths_mod.SHARED))

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

@@ -0,0 +1,37 @@
+"""Modules of the sibling skills, loaded by path once per run, and the weight files they serve.
+
+shell: _MODULES, sibling, weight_module, weight_overlay, shipped_weight
+"""
+
+import importlib.util
+import os
+
+from rr_update import paths
+
+
+_MODULES = {}
+
+
+def sibling(name, *parts):
+    """A module of another skill, loaded by path once per run (skills are installed independently)."""
+    if name not in _MODULES:
+        spec = importlib.util.spec_from_file_location("riskrails_" + name, os.path.join(paths.SKILLS, *parts))
+        _MODULES[name] = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(_MODULES[name])
+    return _MODULES[name]
+
+
+def weight_module():
+    """skills/ai-task/weight.py, the renderer behind `state.py weight --mirror`."""
+    return sibling("weight", "ai-task", "weight.py")
+
+
+def weight_overlay():
+    """skills/ai-task/weight_overlay.py: the plugin's table with the project's laid over it."""
+    return sibling("weight_overlay", "ai-task", "weight_overlay.py")
+
+
+def shipped_weight():
+    return os.path.join(paths.TEMPLATES["ai-init"], paths.WEIGHT_JSON)
+
+