riskrails 4.1.0 → 4.2.0

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

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

@@ -0,0 +1,171 @@
+"""The weight files: the effective table, weight.md, and the one-time split of the mixed testing.md and weight.json.
+
+shell: effective_weight, weight_md, split_weight, unwritten, split_once
+core: GENERATED_HEADER, FIELD_LINE, SPECIFICS_RE, split_testing, leaves, listed
+"""
+
+import json
+import os
+import re
+import tempfile
+from collections import OrderedDict
+
+from rr_update import files
+from rr_update import paths
+from rr_update import plan as plan_mod
+from rr_update import siblings
+
+
+def effective_weight(plan):
+    """The weight table as this run leaves it: the plugin's with weight.project.json laid over it."""
+    own = plan.read(paths.WEIGHT_PROJECT)
+    with tempfile.TemporaryDirectory() as tmp:
+        path = os.path.join(tmp, "weight.project.json")
+        if own is not None:
+            with open(path, "wb") as fh:
+                fh.write(own)
+        return siblings.weight_overlay().load(siblings.shipped_weight(), path)
+
+
+GENERATED_HEADER = b"generated by `state.py weight --mirror`"
+
+
+def weight_md(plan, history):
+    """weight.md is always rendered from the shipped table and the overlay (spec :161). A file that is
+    a rendering or a shipped version is replaced; one a human wrote is gated."""
+    try:
+        theirs = siblings.weight_module().mirror(effective_weight(plan)).encode("utf-8")
+    except (ValueError, OSError, KeyError, TypeError, AttributeError, RecursionError) as exc:
+        plan.hints.append("%s: not rendered (%s: %s); fix %s, then run this again"
+                          % (paths.WEIGHT_MD, type(exc).__name__, exc, paths.WEIGHT_PROJECT))
+        return
+    ours = plan.read(paths.WEIGHT_MD)
+    if ours is None:
+        plan.add("create", paths.WEIGHT_MD, "rendered from the weight table", content=theirs)
+    elif ours == theirs:
+        return
+    elif GENERATED_HEADER in ours[:600] or history.shipped("ai-init/" + paths.WEIGHT_MD, ours):
+        plan.add("regenerate", paths.WEIGHT_MD, "rendered from the weight table", content=theirs)
+    else:
+        plan.gated("regenerate", paths.WEIGHT_MD, plan_mod.edited_note(plan, paths.WEIGHT_MD, ours, theirs), content=theirs)
+
+
+# ---------------------------------------------------------------- the one-time split
+FIELD_LINE = re.compile(r"(?:%s):" % "|".join(
+    ("verify_command", "step_test_command", "e2e_command", "lint_command", "typecheck_command",
+     "single_test", "doc_tests", "bite_codes", "healthy_output", "runtime")))
+
+
+SPECIFICS_RE = re.compile(r"(?m)^## Project specifics[ \t]*$")
+
+
+def split_testing(testing, template):
+    """R11: verification.md from testing.md. The field lines are copied verbatim with their continuation
+    lines (indented, after a field line), then `## Project specifics` to the end of the file."""
+    lines = testing.decode("utf-8").splitlines(keepends=True)
+    fields, taking = [], False
+    for line in lines:
+        if FIELD_LINE.match(line):
+            fields.append(line)
+            taking = True
+        elif taking and line[:1] in (" ", "\t") and line.strip():
+            fields.append(line)
+        else:
+            taking = False
+    text = template.decode("utf-8")
+    if not fields:
+        return template, 0
+    head = text[:re.search(r"(?m)^verify_command:", text).start()]
+    tail = SPECIFICS_RE.search(testing.decode("utf-8"))
+    specifics = testing.decode("utf-8")[tail.start():] if tail else text[SPECIFICS_RE.search(text).start():]
+    body = "".join(fields)
+    return (head + body + ("" if body.endswith("\n") else "\n") + "\n" + specifics).encode("utf-8"), len(fields)
+
+
+def leaves(value, prefix=()):
+    """{path tuple: leaf} — objects are walked, a list or scalar (or an empty object) is one leaf."""
+    if isinstance(value, dict) and value:
+        out = {}
+        for k, v in value.items():
+            out.update(leaves(v, prefix + (k,)))
+        return out
+    return {prefix: value}
+
+
+def split_weight(old, history, template):
+    """R11: weight.project.json from the old weight.json: the leaves that differ from that leaf in every
+    version the plugin shipped (lists whole). -> (bytes, carried paths, uncarried paths that differ from today's table)."""
+    mine = json.loads(old.decode("utf-8"), object_pairs_hook=OrderedDict)
+    tables = []
+    for blob in history.versions("ai-init/" + paths.WEIGHT_JSON) + [files.read(siblings.shipped_weight())]:
+        try:
+            tables.append(leaves(json.loads(blob.decode("utf-8"))))
+        except (ValueError, RecursionError):
+            continue
+    today = tables[-1] if tables else {}
+    carried, uncarried = OrderedDict(), []
+    for path, value in leaves(mine).items():
+        if path[:1] in (("version",), ("_comment",)) or not path:
+            continue
+        if any(path in t and t[path] == value for t in tables):
+            if today.get(path, ...) != value:
+                uncarried.append(".".join(map(str, path)))
+            continue
+        here = carried
+        for part in path[:-1]:
+            here = here.setdefault(part, OrderedDict())
+        here[path[-1]] = value
+    doc = json.loads(template.decode("utf-8"), object_pairs_hook=OrderedDict)
+    doc.update(carried)
+    leaf_paths = [".".join(map(str, p)) for p in leaves(carried) if p]
+    return files.dump_json(doc), leaf_paths, uncarried
+
+
+def listed(names, limit=6):
+    shown = ", ".join(names[:limit])
+    return shown + (" and %d more" % (len(names) - limit) if len(names) > limit else "")
+
+
+def unwritten(plan, history, target, template):
+    """True when the new file is absent, or is still a shipped template (today's or any in the history index):
+    a scaffold run over an old tree can leave one, and it carries nothing of the project."""
+    if not plan.exists(target):
+        return True
+    data = plan.read(target)
+    return data is not None and (data.replace(b"\r\n", b"\n") == template.replace(b"\r\n", b"\n")
+                                 or history.shipped("ai-init/" + target, data))
+
+
+def split_once(plan, history):
+    """R11: when verification.md / weight.project.json are absent (or only a shipped template), make them from
+    testing.md / weight.json (once); with a project's own file present the old file is not read again.
+    The old weight.json is then REMOVED, gated."""
+    tpl = paths.TEMPLATES["ai-init"]
+    template = files.read(os.path.join(tpl, paths.VERIFICATION_MD))
+    if unwritten(plan, history, paths.VERIFICATION_MD, template):
+        absent = not plan.exists(paths.VERIFICATION_MD)
+        testing = plan.read(paths.TESTING_MD)
+        content, count = split_testing(testing, template) if testing is not None else (template, 0)
+        if count:
+            plan.add("split", paths.VERIFICATION_MD, "%d command line(s) of testing.md copied verbatim, with its "
+                     "Project specifics" % count, content=content)
+        elif absent:
+            plan.add("create", paths.VERIFICATION_MD, content=content)
+    template = files.read(os.path.join(tpl, paths.WEIGHT_PROJECT))
+    if unwritten(plan, history, paths.WEIGHT_PROJECT, template):
+        absent = not plan.exists(paths.WEIGHT_PROJECT)
+        old = plan.read(paths.WEIGHT_JSON)
+        if old is None:
+            if absent:
+                plan.add("create", paths.WEIGHT_PROJECT, content=template)
+        else:
+            content, carried, uncarried = split_weight(old, history, template)
+            if absent or content != plan.read(paths.WEIGHT_PROJECT):
+                note = "%d leaf/leaves of weight.json that differ from the plugin's table carried (%s)" % (
+                    len(carried), listed(carried) or "none")
+                if uncarried:
+                    note += "; %d not carried, equal to an older shipped value: %s" % (len(uncarried), listed(uncarried))
+                plan.add("split", paths.WEIGHT_PROJECT, note, content=content)
+    if plan.exists(paths.WEIGHT_JSON):
+        why = "[split] superseded by %s; the plugin's table is read from the plugin" % paths.WEIGHT_PROJECT
+        plan.gated("delete", paths.WEIGHT_JSON, why, reason=why)