riskrails 4.1.0 → 4.2.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

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"),
+}
+