riskrails 4.1.0 → 4.2.0

package/skills/project-update/history/blobs/fa0cb370b024e1a30e1355912032657b08f609e47773a603c193b1e609b0f997

@@ -0,0 +1,8 @@
+# claude-agentic (.ai)
+.ai/state/*.json
+.ai/state/handoff.md
+.ai/state/*.tmp
+.ai/state/*.jsonl
+.ai/local/
+.ai/memory/
+.ai/reports/

package/skills/project-update/history/index.json

@@ -395,7 +395,8 @@
  "ai-init/gitignore.snippet": [
   "5c0619c1ee059477c9d92cf70b72da5d238d9176fc27ab0d38104ecba795624c",
   "a00db51859bb7943174017a34b4a100f98e53d6c3b32f73d8f87d6072016a709",
-  "5a93f78b4ed4d416c171139b2ce610a117f9c1dd46fbb56ca86729cb4c53d10c"
+  "5a93f78b4ed4d416c171139b2ce610a117f9c1dd46fbb56ca86729cb4c53d10c",
+  "fa0cb370b024e1a30e1355912032657b08f609e47773a603c193b1e609b0f997"
  ],
  "ai-init/junie-guidelines.block.md": [
   "e8df28f07cb784d768bcafbced70fd15771afa61dbec7dc4c1c3f858f9002fec",

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

@@ -0,0 +1 @@
+"""rr_update: the pieces of skills/project-update/update.py, one module per concern, lower layers first."""

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

@@ -0,0 +1,188 @@
+"""Writing the plan: the preconditions, the atomic write, the record of what was taken away, and the abort.
+
+shell: current_sha, check, default_mode, write_file, keep_original, record_run, apply, apply_item, prune_empty
+core: Abort
+"""
+
+import json
+import os
+import tempfile
+from collections import OrderedDict
+
+from rr_update import files
+from rr_update import paths
+
+
+class Abort(Exception):
+    """A precondition failed: the project is not what the dry run described."""
+
+    def __init__(self, item, why):
+        super().__init__(why)
+        self.item, self.why = item, why
+
+
+def current_sha(root, target):
+    """The sha of a target now, or None when it is absent. A path that is not a
+    regular file has no content this tool may replace."""
+    path = os.path.join(root, target)
+    if os.path.islink(path) or (os.path.exists(path) and not os.path.isfile(path)):
+        raise Abort(None, "%s is not a regular file" % target)
+    return files.sha(files.read(path)) if os.path.isfile(path) else None
+
+
+def check(plan, item, target, expect, written):
+    """The target must still be what the dry run read, or what this run wrote."""
+    try:
+        now_sha = current_sha(plan.root, target)
+    except Abort as exc:
+        raise Abort(item, exc.why) from exc
+    want = written.get(target, expect)
+    if now_sha != want:
+        raise Abort(item, "%s changed since the dry run read it" % target)
+
+
+def default_mode():
+    mask = os.umask(0)
+    os.umask(mask)
+    return 0o666 & ~mask
+
+
+def write_file(root, target, content, mode=None):
+    """Atomic, like state.py: a crash leaves the old file or the new one, never
+    half of one. The temp file is created with mkstemp in the target's directory,
+    so a planted name cannot redirect the write, and a symlinked target is
+    refused rather than followed. The target keeps the mode it had. A symlinked
+    *directory* on the way to it is still followed, as every writer here always
+    has."""
+    path = os.path.join(root, target)
+    if os.path.islink(path) or (os.path.exists(path) and not os.path.isfile(path)):
+        raise Abort(None, "%s is not a regular file" % target)
+    parent = os.path.dirname(path) or "."
+    os.makedirs(parent, exist_ok=True)
+    if mode is None:
+        mode = os.stat(path).st_mode & 0o7777 if os.path.isfile(path) else default_mode()
+    fd, tmp = tempfile.mkstemp(dir=parent, prefix=os.path.basename(path) + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(content)
+        os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def keep_original(plan, target):
+    """A faithful copy of what a move or a delete takes away, mode included.
+    Nothing else is ever lost, so nothing else is copied."""
+    path = os.path.join(plan.root, target)
+    write_file(plan.root, os.path.join(plan.report_dir, "original", target),
+               files.read(path), mode=os.stat(path).st_mode & 0o7777)
+
+
+
+def record_run(plan, ops, deletions):
+    """The record of what was taken away or overwritten, rewritten after every such operation:
+    an abort must not lose the note of a change a human approved. A second run on the same
+    day appends to the record instead of replacing it."""
+    path = os.path.join(plan.report_dir, "migration.json")
+    existing = {}
+    full = os.path.join(plan.root, path)
+    if os.path.isfile(full):
+        try:
+            existing = json.loads(files.read(full), object_pairs_hook=OrderedDict)
+        except (ValueError, RecursionError):  # too deep reads as malformed
+            existing = {}
+        if not isinstance(existing, dict):  # hand-edited into another shape
+            existing = {}
+    record = OrderedDict()
+    record["from"] = existing.get("from", plan.version_from)
+    # The version the project is actually at now, read from the disk: this record is
+    # written before the files change, and an aborted run never reaches the template's.
+    version_path = os.path.join(plan.root, paths.VERSION_FILE)
+    on_disk = files.read(version_path).decode().strip() if os.path.isfile(version_path) else ""
+    record["to"] = int(on_disk) if on_disk.isdigit() else record["from"]
+    record["applied_at"] = files.utc_now()
+    # A recovery re-run replays the same operation: record it once.
+    record["ops"] = list(existing.get("ops", []))
+    record["ops"] += [o for o in ops if o not in record["ops"]]
+    record["deletions"] = list(existing.get("deletions", []))
+    record["deletions"] += [d for d in deletions
+                            if not any(e.get("path") == d["path"] for e in record["deletions"])]
+    if existing and all(existing.get(k) == record[k] for k in ("from", "to", "ops", "deletions")):
+        return  # a run that changed nothing leaves the record as it was
+    write_file(plan.root, path, files.dump_json(record))
+
+
+def apply(plan):
+    """Write the plan, in order. Every item checks its target first; a violation
+    or a failed write aborts before the next item, leaving everything after it
+    unwritten. Every operation is idempotent, so the re-run is the recovery."""
+    written, recorded = {}, []
+    for item in plan.items:
+        try:
+            apply_item(plan, item, written, recorded)
+        except Abort as exc:
+            raise Abort(exc.item or item, exc.why) from exc
+        except OSError as exc:
+            raise Abort(item, str(exc)) from exc
+    # The run finished: say which version it actually reached.
+    try:
+        if recorded or os.path.isfile(os.path.join(plan.root, plan.report_dir, "migration.json")):
+            record_run(plan, [], [])
+    except OSError as exc:
+        raise Abort(None, str(exc)) from exc
+
+
+def apply_item(plan, item, written, recorded):
+    target, action = item["target"], item["action"]
+    reason = item.get("reason") or ""
+    cleanup = reason.startswith("[cleanup]")
+    if action in ("delete?", "regenerate?"):  # listed only, until a human confirms it
+        return
+    by = dict(confirmed_by=plan.confirm_cleanup if cleanup else plan.confirm_delete,
+              via=plan.cleanup_via if cleanup else plan.confirm_via, at=files.utc_now())
+    if action == "delete":
+        # the plan-time symlink check is repeated: a path swapped since is refused
+        why = files.unsafe_path(plan.root, target)
+        if why:
+            raise Abort(item, why)
+        check(plan, item, target, item["expect"], written)
+        # git-ignored task state: a [cleanup] deletion of it is NOT recoverable through git, and
+        # copying what it removes would defeat the cleanup, so no original/ copy is kept. A report
+        # file git tracks, or should, is kept like any other deletion.
+        if not target.startswith(".ai/state/") and (not cleanup or target in plan.git_kept):
+            keep_original(plan, target)
+        recorded.append(target)
+        # Recorded before the file is gone: an abort later must not lose the note
+        # of what was taken away, or of who approved it.
+        record_run(plan, [dict(action=action, path=target)], [dict(path=target, **by)])
+        os.remove(os.path.join(plan.root, target))
+        written[target] = None
+        if reason.startswith(("[cleanup]", "[local]")):
+            prune_empty(plan.root, target)
+        return
+    check(plan, item, target, item["expect"], written)
+    if item["keep"] and item["expect"] is not None and target not in written:
+        # A change a human confirmed overwrites what they wrote: keep it, so it can be read back.
+        if not os.path.exists(os.path.join(plan.root, plan.original_of(target))):
+            keep_original(plan, target)
+        recorded.append(target)
+        record_run(plan, [dict(action=action, path=target, **by)], [])
+    write_file(plan.root, target, item["content"])
+    written[target] = files.sha(item["content"])
+
+
+def prune_empty(root, target):
+    """The directories a cleanup or cache deletion left empty, up to (not including)
+    .ai/reports, .ai/state/logs and .ai/local; a directory with anything in it stays."""
+    top = ".ai/state/logs" if target.startswith(".ai/state/logs/") else \
+        ".ai/local" if target.startswith(paths.LOCAL_CACHE + "/") else ".ai/reports"
+    here = os.path.dirname(target)
+    while here.startswith(top + "/"):
+        try:
+            os.rmdir(os.path.join(root, here))
+        except OSError:
+            return
+        here = os.path.dirname(here)

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

@@ -0,0 +1,38 @@
+"""The managed block of one instruction file.
+
+shell: block_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
+from rr_update import plan as plan_mod
+
+
+def block_update(plan, history, runtime):
+    """R15, D5: the managed block of one instruction file. Rewritten between its markers; no block
+    -> appended; no file -> a minimal one with the block. Text outside the markers is never touched."""
+    name, block_tpl, minimal_tpl = paths.INSTRUCTION_FILE[runtime]
+    tpl = files.read(os.path.join(paths.TEMPLATES["ai-init"], block_tpl))
+    text = plan.read(name)
+    if text is None:
+        created = files.read(os.path.join(paths.TEMPLATES["ai-init"], minimal_tpl)).replace(
+            b"{{PROJECT}}", os.path.basename(plan.root).encode())
+        plan.add("create", name, "with the managed block", content=created.rstrip(b"\n") + b"\n\n" + tpl)
+        return
+    found = render_instructions.find_block(text)
+    if found is None:
+        plan.add("regenerate", name, "managed block appended", content=text.rstrip(b"\n") + b"\n\n" + tpl)
+        return
+    s, e = found[0], found[1]
+    ours = text[s:e] + b"\n"
+    if ours == tpl:
+        return
+    content = text[:s] + tpl.rstrip(b"\n") + text[e:]
+    if history.shipped("ai-init/" + block_tpl, ours):
+        plan.add("regenerate", name, "managed block replaced (unchanged since it was installed)", content=content)
+    else:
+        plan.gated("regenerate", name, "managed block " + plan_mod.edited_note(plan, name, ours, tpl), content=content)

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

@@ -0,0 +1,96 @@
+"""The plan of one run: every rule, in the order D3 sets, collected into one Plan.
+
+shell: build_plan
+core: PHASE
+"""
+
+import os
+
+from rr_update import blocks
+from rr_update import cleanup
+from rr_update import files as files_mod
+from rr_update import hints
+from rr_update import history as history_mod
+from rr_update import paths
+from rr_update import plan as plan_mod
+from rr_update import rules
+from rr_update import shared
+from rr_update import weights
+
+
+PHASE = {"split": 0, "delete": 2, "delete?": 2}
+
+
+def build_plan(root, confirm_delete=None, confirm_via=None, confirm_cleanup=None, cleanup_via=None):
+    """D3: split_once -> regenerate -> shared -> block per runtime -> rules -> local -> gitignore, cleanup, hints.
+    The caller has run check_kept: nothing here reads a kept file for meaning."""
+    plan = plan_mod.Plan(root)
+    plan.confirm_cleanup = confirm_cleanup
+    plan.cleanup_via = cleanup_via
+    plan.confirm_delete = confirm_delete
+    plan.confirm_via = confirm_via
+    has_ai = os.path.isdir(os.path.join(root, ".ai"))
+    has_sdlc = os.path.isdir(os.path.join(root, "docs", "sdlc"))
+    if not (has_ai or has_sdlc):
+        return None
+    history = history_mod.History(paths.HISTORY)
+    runtimes = history_mod.project_runtimes(root)
+    plan.version_from = history_mod.project_version(root) if has_ai else None
+
+    if has_sdlc:
+        tpl = paths.TEMPLATES["project-init"]
+        for src, target in paths.SDLC_CREATE:  # the project's own from then on
+            if not plan.exists(target):
+                plan.add("create", target, content=files_mod.read(os.path.join(tpl, src)).replace(
+                    b"{{PROJECT}}", os.path.basename(root).encode()))
+        for rt in runtimes:
+            for src, target, kind in paths.RUNTIME_MAP[rt]:
+                content = files_mod.read(os.path.join(tpl, src))
+                if kind == "create":
+                    if not plan.exists(target):
+                        plan.add("create", target, content=content)
+                else:
+                    plan_mod.regenerate(plan, history, "project-init/" + src, target, content)
+        hints.gitignore_update(plan, os.path.join(tpl, "gitignore.snippet"))
+
+    if has_ai:
+        tpl = paths.TEMPLATES["ai-init"]
+        weights.split_once(plan, history)
+        files = []
+        for dirpath, _, names in os.walk(os.path.join(tpl, ".ai")):
+            for n in names:
+                files.append(os.path.relpath(os.path.join(dirpath, n), tpl).replace(os.sep, "/"))
+        for rel in sorted(files):
+            if rel in paths.NOT_COPIED or rel in (paths.VERIFICATION_MD, paths.WEIGHT_PROJECT):
+                continue
+            content = files_mod.read(os.path.join(tpl, rel))
+            if rel in paths.CREATE_ONLY or rel.startswith(paths.CREATE_ONLY_DIRS):
+                if not plan.exists(rel):
+                    plan.add("create", rel, content=content)
+            else:
+                plan_mod.regenerate(plan, history, "ai-init/" + rel, rel, content)
+        weights.weight_md(plan, history)
+        shared.shared_update(plan, history, runtimes)
+        rules.rule_sources(plan)
+        cleanup.local_cache(plan)
+        cleanup.cleanup_update(plan)
+        for rt in runtimes:
+            blocks.block_update(plan, history, rt)
+        rules.rules_update(plan, runtimes)
+        cleanup.deletion_hint(plan)
+        hints.gitignore_update(plan, os.path.join(tpl, "gitignore.snippet"))
+        cleanup.tracked_ignored_hint(plan)
+        hints.verification_hints(plan)
+        hints.budget_hints(plan, runtimes)
+        if plan.items and plan.exists(paths.STATE_FILE):
+            plan.hints.append("%s: a task is in flight while files are regenerated — check that the files "
+                              "its current step may touch still exist afterwards" % paths.STATE_FILE)
+        # Last of the items: an apply that stops short leaves the version alone, and the next run plans the rest again.
+        ours = history_mod.template_version()
+        if plan.version_from != ours:
+            plan.add("regenerate" if plan.exists(paths.VERSION_FILE) else "create", paths.VERSION_FILE,
+                     "schema %d" % ours, content=b"%d\n" % ours)
+    if has_sdlc:
+        hints.constitution_hint(plan)
+    plan.items.sort(key=lambda i: 3 if i["target"] == paths.VERSION_FILE else PHASE.get(i["action"], 1))
+    return plan

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

@@ -0,0 +1,194 @@
+"""The cleanup proposals: the local cache, the task journals, the [cleanup] rows and the hints about deletion and tracked ignored files.
+
+shell: local_cache, task_journal, cleanup_update, deletion_hint, tracked_ignored_hint
+core: TRACKED_IGNORED_SHOWN
+"""
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+
+from rr_update import files
+from rr_update import paths
+
+
+def local_cache(plan):
+    """R18: .ai/local/plugin-update/ (the old merge's conflict copies) is removed; .ai/local/memory/ is never touched."""
+    for here, _dirs, names in os.walk(os.path.join(plan.root, paths.LOCAL_CACHE)):
+        for name in sorted(names):
+            rel = os.path.relpath(os.path.join(here, name), plan.root).replace(os.sep, "/")
+            if not files.unsafe_path(plan.root, rel):
+                why = "[local] the old merge's cache, not written any more"
+                plan.gated("delete", rel, why, reason=why)
+
+
+def task_journal(root, task_id):
+    """(finished, abandoned, last event as a datetime) from the task's journal,
+    or None when it holds no readable event. A task is finished when its journal
+    has task_closed or gate_approved, or when logs/<id>/state.json records a
+    result (so a torn task_closed line does not make a closed task look unclosed)."""
+    closed = abandoned = False
+    last = None
+    try:
+        with open(os.path.join(root, ".ai", "reports", task_id, "events.jsonl"), encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return None
+    for line in lines:
+        try:
+            ev = json.loads(line)
+            when = datetime.strptime(ev["ts"][:19], "%Y-%m-%dT%H:%M:%S").replace(tzinfo=timezone.utc)
+        except (ValueError, KeyError, TypeError, RecursionError):
+            continue
+        if last is None or when > last:
+            last = when
+        if ev.get("event") == "task_closed":
+            closed = True
+            data = ev.get("data")
+            abandoned = (isinstance(data, dict) and data.get("abandoned") is True) or ev.get("detail") == "abandoned"
+        elif ev.get("event") == "gate_approved":
+            closed = True
+    try:
+        with open(os.path.join(root, ".ai", "state", "logs", task_id, "state.json"), encoding="utf-8") as fh:
+            result = json.load(fh).get("result")
+    except (OSError, ValueError, AttributeError, UnicodeDecodeError, RecursionError):
+        result = None
+    if isinstance(result, str) and result:
+        closed = True
+        abandoned = abandoned or result == "abandoned"
+    return None if last is None else (closed, abandoned, last)
+
+
+def cleanup_update(plan, now=None):
+    """Old run logs and stale unclosed tasks, proposed for deletion and never
+    deleted unasked (only with --confirm-cleanup). A closed task's `*.log` files
+    go (its state.json stays); an abandoned task loses every file under
+    .ai/reports/<id>/ and .ai/state/logs/<id>/ except that state.json; an unclosed
+    one idle for STALE_DAYS loses every file in both. The task in flight is
+    never touched. `now` is a datetime; RISKRAILS_NOW (ISO, Z) overrides it."""
+    if now is None:
+        try:
+            now = datetime.strptime(paths.env("NOW") or files.utc_now(), "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+        except ValueError:
+            print("project-update: RISKRAILS_NOW %r is not a UTC time like 2026-01-31T12:00:00Z" % paths.env("NOW"),
+                  file=sys.stderr)
+            raise SystemExit(2) from None
+    flight = None
+    raw = plan.read(paths.STATE_FILE)
+    if raw is not None:
+        try:
+            flight = json.loads(raw).get("task_id")
+        except (ValueError, AttributeError, RecursionError):
+            return  # unreadable: a task may be in flight, so no task is proposed as stale
+    reports =os.path.join(plan.root, ".ai", "reports")
+    logs = os.path.join(plan.root, ".ai", "state", "logs")
+
+    def files_of(base, rel, only_logs=False, keep=()):
+        out = []
+        for here, _dirs, names in os.walk(os.path.join(base, rel)):
+            for n in names:
+                full = os.path.join(here, n)
+                if os.path.isfile(full) and not os.path.islink(full) and (not only_logs or n.endswith(".log")) \
+                        and n not in keep:
+                    out.append(os.path.relpath(full, plan.root).replace(os.sep, "/"))
+        return out
+
+    for task_id in sorted(os.listdir(reports)) if os.path.isdir(reports) else []:
+        journal = task_journal(plan.root, task_id)
+        if journal is None or task_id == flight:
+            continue
+        closed, abandoned, last = journal
+        if abandoned:
+            why, targets = "[cleanup] abandoned task %s" % task_id, \
+                files_of(reports, task_id) + files_of(logs, task_id, keep=("state.json",))
+        elif not closed and now - last > timedelta(days=paths.STALE_DAYS):
+            why = "[cleanup] unclosed task %s, last event %s" % (task_id, last.strftime("%Y-%m-%d"))
+            targets = files_of(reports, task_id) + files_of(logs, task_id)
+        elif closed:
+            why, targets = "[cleanup] log of closed task %s" % task_id, files_of(logs, task_id, only_logs=True)
+        else:
+            continue
+        # .ai/reports/ is usually git-tracked; only .ai/state/ is git-ignored run state
+        held = files.git_states(plan.root, ".ai/reports/" + task_id)
+        skipped = set()
+        for target in sorted(targets):
+            unsafe = files.unsafe_path(plan.root, target)
+            if unsafe:     # --apply would abort on it: say so instead of proposing it
+                if unsafe not in skipped:
+                    skipped.add(unsafe)
+                    plan.hints.append("%s: not proposed for deletion, %s — remove it yourself if it should go"
+                                      % (target, unsafe))
+                continue
+            note = why
+            state = held(target) if target.startswith(".ai/reports/") else None
+            if state == "tracked":
+                note += "; tracked: git can restore a committed copy"
+            elif state == "uncommitted":
+                note += "; uncommitted: git holds no copy of it"
+            elif state == "ignored":
+                note += "; git-ignored: not recoverable through git"
+            if state in ("tracked", "uncommitted"):
+                plan.git_kept.add(target)
+            if plan.confirm_cleanup:
+                plan.add("delete", target, note, reason=why)
+                plan.remove(target)
+            else:
+                plan.add("delete?", target, note, reason=why)
+
+
+def deletion_hint(plan):
+    """M4: git is the rollback of a deletion or an overwrite; it must hold .ai/ first.
+    A [cleanup] deletion of git-ignored run state is not counted: git does not roll it back;
+    one under .ai/reports/ that git tracks, or should, is."""
+    if any(i["action"] in ("delete?", "delete", "regenerate?") and i["target"].startswith(".ai/")
+           and (not (i.get("reason") or "").startswith("[cleanup]") or i["target"] in plan.git_kept)
+           for i in plan.items) \
+            and files.git_dirty_ai(plan.root):
+        plan.hints.append("commit .ai/ first: git is this update's rollback "
+                          "(`git status -- .ai` lists what it does not hold yet)")
+
+
+TRACKED_IGNORED_SHOWN = 10  # per-file hints before tracked_ignored_hint counts the rest
+
+
+def tracked_ignored_hint(plan):
+    """A file under .ai/state that git tracks although an ignore rule lists it: the rule
+    has no effect on it. Read-only: the human untracks it; nothing is planned.
+    At most TRACKED_IGNORED_SHOWN files get their own hint; one more line counts the rest."""
+    try:
+        res = subprocess.run(["git", "-C", plan.root, "ls-files", "-z", "-ci", "--exclude-standard",
+                              "--", ".ai/state"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                             timeout=30, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return
+    if res.returncode != 0:
+        return
+    # --literal-pathspecs: a * ? [ ] in a name is that name, not a pattern that matches its neighbours.
+    all_cmd = "git ls-files -z -ci --exclude-standard -- .ai/state | xargs -0 -r git --literal-pathspecs rm --cached --"
+    names = [os.fsdecode(raw) for raw in res.stdout.split(b"\0") if raw]
+    for path in names[:TRACKED_IGNORED_SHOWN]:
+        # A control character (or a byte that is not UTF-8, which fsdecode keeps as a lone
+        # surrogate) in the name would forge a report line or break the copy-paste command:
+        # show it escaped, and untrack by the NUL-safe listing.
+        shown = "".join(c if c.isprintable() else repr(c)[1:-1] for c in path)
+        if shown == path:
+            plan.hints.append("%s: tracked by git but ignored by an ignore rule — the rule has no "
+                              "effect on a tracked file, so every run leaves the tree dirty and "
+                              "`git commit -a` sweeps it in; untrack it yourself, from the project root: "
+                              "`git --literal-pathspecs rm --cached -- %s` and commit (the file stays on disk)"
+                              % (shown, shlex.quote(path)))
+        else:
+            plan.hints.append("%s: tracked by git but ignored by an ignore rule — the rule has no "
+                              "effect on a tracked file, so every run leaves the tree dirty and "
+                              "`git commit -a` sweeps it in; this name cannot be typed safely, so "
+                              "untrack it, from the project root, with `%s`, which untracks EVERY tracked, ignored file "
+                              "under .ai/state, not only this one, and commit (the files stay on disk)"
+                              % (shown, all_cmd))
+    if len(names) > TRACKED_IGNORED_SHOWN:
+        plan.hints.append(".ai/state: %d more file(s) tracked by git but ignored by an ignore rule, "
+                          "not listed; untrack ALL tracked, ignored files under .ai/state "
+                          "(the ones listed above too), from the project root, with `%s` and commit (the files stay on disk)"
+                          % (len(names) - TRACKED_IGNORED_SHOWN, all_cmd))

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

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