riskrails 4.1.0 → 4.3.0

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

@@ -0,0 +1,41 @@
+# Coding policy
+
+<!-- /ai-init fills the project-specific half of this file from the repository.
+     The rules above the line are general and apply everywhere. -->
+
+## General
+
+- Follow the conventions already in the file you are editing, even when they are
+  not the conventions you would choose. Consistency inside a file beats
+  correctness in the abstract.
+- One logical change per step. If you find yourself writing "and also", stop.
+- No new abstraction until there are three call sites that need it.
+- Extend through the framework's own extension points before writing a new
+  mechanism: decorators, event subscribers, form extensions, template overrides,
+  compiler passes, configuration.
+- Never modify `vendor/` or `node_modules/`. A needed change to a third-party
+  package becomes a decorator, an event listener, or a patch that is applied on
+  install and reviewable in git.
+- Dead code is deleted only in a task that is about deleting it, with evidence
+  that it is dead.
+- A function does one thing and its name says which. When the name needs
+  "and", split it.
+- Inputs come in as parameters and the result goes out as the return value;
+  files, the network and the clock stay at the edge, in the caller.
+- An error message says what failed, what was expected, what was found, and
+  the way out.
+
+In existing code the file's conventions win; the last three lines hold for the
+functions you add.
+
+## Comments
+
+Write the comment that explains *why*, and only when the reason is not visible in
+the code. Do not narrate what the next line does. Do not leave commented-out
+code; git remembers it.
+
+## Project specifics
+
+<!-- KNOWN FACT entries only: the linters that actually run, the static-analysis
+     level actually configured, the naming and layering the code actually uses.
+     Cite the config file for each. -->

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

@@ -40,7 +40,8 @@
  "ai-init/.ai/agents/implementer.md": [
   "7e5c824bb71fe5353ec8a67827145b8fbc22ecd902ade1ad3005fafeed4ffb71",
   "94da08ac6945d5614cc7918d450aab94f3aa8a929a1c8f9fa9a0a9ac51176287",
-  "1fe2f3d3bfe2d1b671aa759b89ac1d88ae73eefed2208a485c9e972fa7b079e6"
+  "1fe2f3d3bfe2d1b671aa759b89ac1d88ae73eefed2208a485c9e972fa7b079e6",
+  "71364f3e392fe460b5b32cfec8de047a0aae8f88f144d110f90a329163677d42"
  ],
  "ai-init/.ai/agents/manager.md": [
   "0aeb04b04262683cac6513545683486a73dc473b447bba43b5aaab18403957a6",
@@ -67,7 +68,8 @@
   "e71abd1823fbbe6e635b141f04a301c3d24c2cdd56c7a5c2b25c7ea1898be54f",
   "be34ab013c39ace1e1ec902b9bcfe9653ba6aaeddb9df63fde2d2aa17bfb2263",
   "6956a4c991262b5733645f29d7067c091c1126721623b07275b4f276560ec28e",
-  "707e67834ec3295705c4e391b794d8600a3fbc3c02dda16db50035f84e6b47c9"
+  "707e67834ec3295705c4e391b794d8600a3fbc3c02dda16db50035f84e6b47c9",
+  "499e51e1a393f776aa425aeb2be575f0a58eb483d83bc9f1c7da94ff38c3fb0e"
  ],
  "ai-init/.ai/agents/risk.md": [
   "d7146a591898984115124c83174a2c93cc080ad594f132f3d89c8b41b006c805",
@@ -83,7 +85,8 @@
   "7f713c6ecd00bc2379deda511d8bda786341dbe5f5187f3b899302d904fed6bc"
  ],
  "ai-init/.ai/policies/coding.md": [
-  "3dd55bf5f9d9471c68af3353166da11593a11e639f7557397ce46787291fa629"
+  "3dd55bf5f9d9471c68af3353166da11593a11e639f7557397ce46787291fa629",
+  "dac90781793b8a1c8e5f3e0307665b6394d922140c3831c5508d019f79e1ed0a"
  ],
  "ai-init/.ai/policies/context-management.md": [
   "230df2220e9c73c563c3c926d26f5c6dbe249df26a56fa43b7b321cdee2d5783",
@@ -395,7 +398,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))