riskrails 4.0.1 → 4.2.0

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

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
+