riskrails 4.1.0 → 4.3.0

package/skills/ai-task/memory_hook.py

@@ -0,0 +1,172 @@
+"""The git hook (R17, §D10): the installed shim and where it points, the policy file, and the enable and
+disable commands that write and remove them."""
+import json
+import os
+import re
+
+import memory_config as mcfg
+import memory_format as mf
+import memory_io as mio
+
+
+# ------------------------------------------------------------------ status, show
+def hook_state(root):
+    code, out, _ = mio.git(root, "config", "--get", "core.hooksPath")
+    if code == 0 and out.strip():
+        return "hookspath"
+    path = hooks_path(root)
+    if not path:
+        return "absent"
+    hook = os.path.join(path, "pre-push")
+    text = mio.read_bytes(hook)
+    if text is None:
+        return "absent"
+    if mio.HOOK_MARKER.encode() in text:
+        decoded = text.decode("utf-8", "replace")
+        if not any(os.path.isfile(p) for p in shim_paths(decoded)):
+            return "installed, validator missing — pushes are NOT checked ('state.py memory enable' rewrites it)"
+        return "current" if decoded == shim_text() else "installed (stale)"
+    return "foreign"
+
+
+# ------------------------------------------------------------------ the git hook (R17, §D10)
+def hooks_path(root):
+    code, out, _ = mio.git(root, "rev-parse", "--git-path", "hooks")
+    if code != 0 or not out.strip():
+        return None
+    path = out.strip()
+    return path if os.path.isabs(path) else os.path.join(root, path)
+
+
+def shim_candidates(validator=None):
+    """Where the shim looks for the validator, in order: the hook beside this
+    module, the hook in either runtime home, then this module itself — a Codex
+    install copies skills/ai-task/ but not every hook."""
+    return [validator or mio.VALIDATOR, "$HOME/.claude/hooks/memory-pre-push.py",
+            "${CODEX_HOME:-$HOME/.codex}/hooks/memory-pre-push.py", mio.SELF,
+            "$HOME/.claude/skills/ai-task/memory_sync.py",
+            "${CODEX_HOME:-$HOME/.codex}/skills/ai-task/memory_sync.py"]
+
+
+def shim_text(validator=None):
+    return ("#!/bin/sh\n%s — written by 'state.py memory enable'; 'state.py memory disable' removes it\n"
+            "for v in %s; do\n"
+            "  [ -f \"$v\" ] && exec python3 -I \"$v\" \"$@\"\n"
+            "done\n"
+            "echo \"riskrails memory: validator not found — this push is not checked\" >&2; exit 0\n"
+            % (mio.HOOK_MARKER, " ".join('"%s"' % c for c in shim_candidates(validator))))
+
+
+def shim_paths(text):
+    """The shim's candidates as paths on this machine."""
+    match = re.search(r"^for v in (.+); do$", text, re.M)
+    home = os.path.expanduser("~")
+    codex = os.environ.get("CODEX_HOME") or os.path.join(home, ".codex")
+    return [c.replace("${CODEX_HOME:-$HOME/.codex}", codex).replace("$HOME", home)
+            for c in re.findall(r'"([^"]+)"', match.group(1) if match else "")]
+
+
+def snippet_text(validator=None):
+    validator = validator or mio.VALIDATOR
+    return ("# riskrails memory: add to your own pre-push hook (stdin can be read only once)\n"
+            "rr_in=$(mktemp) && cat > \"$rr_in\"\n"
+            "python3 -I \"%s\" \"$@\" < \"$rr_in\" || { rr=$?; rm -f \"$rr_in\"; exit $rr; }\n"
+            "# … then your hook, reading \"$rr_in\" where it read stdin …\n"
+            "rm -f \"$rr_in\"\n" % validator)
+
+
+def install_hook(root):
+    """installed | current | foreign | hookspath (R17)."""
+    code, out, _ = mio.git(root, "config", "--get", "core.hooksPath")
+    if code == 0 and out.strip():
+        return "hookspath"
+    path = hooks_path(root)
+    if not path:
+        raise mio.MemoryError_("not a git repository: no hooks path", 2)
+    hook = os.path.join(path, "pre-push")
+    text = mio.read_bytes(hook)
+    if text is not None and mio.HOOK_MARKER.encode() not in text:
+        return "foreign"
+    if text is not None and text.decode("utf-8", "replace") == shim_text():
+        return "current"
+    os.makedirs(path, exist_ok=True)
+    mio.atomic_write(hook, shim_text())
+    os.chmod(hook, 0o755)
+    return "installed"
+
+
+def remove_hook(root):
+    path = hooks_path(root)
+    hook = os.path.join(path, "pre-push") if path else None
+    text = mio.read_bytes(hook) if hook else None
+    if text is not None and mio.HOOK_MARKER.encode() in text:
+        os.remove(hook)
+        return "removed"
+    return "foreign" if text is not None else "absent"
+
+
+def write_policy(root, policy):
+    mio.atomic_write(os.path.join(root, mio.POLICY_REL), json.dumps(policy, indent=2, ensure_ascii=False) + "\n")
+
+
+GITIGNORE_LOCAL = (".ai/memory/", ".ai/reports/")
+GITIGNORE_SHARED = ("!.ai/memory/", "!.ai/reports/")
+
+
+def append_gitignore(root, lines):
+    """Append `lines` to .gitignore (created when absent), after a newline if the file lacks one; never rewrites."""
+    path = os.path.join(root, ".gitignore")
+    current = mio.read_bytes(path) or b""
+    sep = b"\n" if current and not current.endswith(b"\n") else b""
+    with open(path, "ab") as fh:
+        fh.write(sep + "".join(line + "\n" for line in lines).encode())
+
+
+def apply_share(root, share):
+    """--share git: the negations (the record is shared through git); --share local: the ignore lines. Append only."""
+    if share == "git":
+        have = (mio.read_bytes(os.path.join(root, ".gitignore")) or b"").decode("utf-8", "replace").splitlines()
+        add = [line for line in GITIGNORE_SHARED if line not in have]
+        if not add and not mio.shared(root):
+            add = list(GITIGNORE_SHARED)
+        if add:
+            append_gitignore(root, add)
+    elif share == "local" and mio.shared(root):
+        append_gitignore(root, GITIGNORE_LOCAL)
+
+
+def enable(root, author=None, period=None, index=None, share=None):
+    """Packages mode on. The hook is installed only while the record is shared (.ai/memory/ not git-ignored);
+    a local record has no hook of ours and the state is reported as `local`."""
+    cfg = mcfg.load_config(root)
+    policy = dict(mcfg.DEFAULTS)
+    policy.update(cfg.policy if cfg.present else {})
+    policy["mode"] = "packages"
+    if period:
+        if period not in mf.PERIODS:
+            raise mio.MemoryError_("--period takes one of %s" % ", ".join(mf.PERIODS))
+        policy["period"] = period
+    write_policy(root, policy)
+    local = dict(cfg.local)
+    local["schema"] = 1
+    local["author"] = mcfg.author_slug(author) if author else cfg.author
+    if index:
+        if index not in ("none", "sqlite"):
+            raise mio.MemoryError_("--index takes none or sqlite")
+        local["index"] = index
+    local.setdefault("index", "none")
+    mio.atomic_write(mio.local_path(root, "config.json"), json.dumps(local, sort_keys=True) + "\n")
+    if share:
+        apply_share(root, share)
+    if not mio.shared(root):
+        remove_hook(root)
+        return "local"
+    return install_hook(root)
+
+
+def disable(root):
+    cfg = mcfg.load_config(root)
+    policy = dict(cfg.policy)
+    policy["mode"] = "files"
+    write_policy(root, policy)
+    return remove_hook(root)

package/skills/ai-task/memory_io.py

@@ -0,0 +1,122 @@
+"""The small I/O of packages mode: the path constants, the refusal type, the clock, fault
+injection, JSON and byte reads, the atomic write, the clone lock and the git runner. It imports no other
+memory module; HERE is the one place that reads its own path (SELF stays the validator entry's path)."""
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+
+
+try:
+    import fcntl
+except ImportError:                       # not POSIX: last writer wins within one clone (docs/local-memory.md)
+    fcntl = None
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+POLICY_REL = os.path.join(".ai", "policies", "memory.json")
+MEMORY_REL = os.path.join(".ai", "memory")
+LOCAL_REL = os.path.join(".ai", "local", "memory")
+PENDING_MAX = 5
+BATCH_CHARS = "0123456789abcdefghjkmnpqrstvwxyz"
+HOOK_MARKER = "# riskrails-memory-pre-push 1"
+VALIDATOR = os.path.normpath(os.path.join(HERE, "..", "..", "hooks", "memory-pre-push.py"))
+SELF = os.path.join(HERE, "memory_sync.py")   # the fallback validator: the entry, run as a script
+FINDINGS_MAX = 40
+ZERO_SHA = "0" * 40
+
+
+class MemoryError_(Exception):            # pylint: disable=invalid-name  # not the builtin MemoryError
+    """A refusal with its exit code (§I4: 1 findings, 2 usage, 3 aborted, 5 human, 6 scope)."""
+
+    def __init__(self, message, code=2):
+        super().__init__(message)
+        self.code = code
+
+
+def now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def crash(point):
+    """Fault injection (A9): AI_MEMORY_CRASH_AT=B2..B6 ends the process here."""
+    if os.environ.get("AI_MEMORY_CRASH_AT") == point:
+        sys.stdout.flush()
+        sys.stderr.flush()
+        os._exit(70)                      # pylint: disable=protected-access  # a crash, not an exit
+
+
+def read_json(path):
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+# ------------------------------------------------------------------ small I/O
+def atomic_write(path, data):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    handle, tmp = tempfile.mkstemp(prefix=".tmp-", dir=os.path.dirname(path))
+    try:
+        with os.fdopen(handle, "wb") as fh:
+            fh.write(data if isinstance(data, bytes) else data.encode("utf-8"))
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.remove(tmp)
+        raise
+
+
+@contextlib.contextmanager
+def locked(root):
+    """flock on .ai/local/memory/lock: two closes in one clone serialise here."""
+    os.makedirs(os.path.join(root, LOCAL_REL), exist_ok=True)
+    fd = os.open(os.path.join(root, LOCAL_REL, "lock"), os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        if fcntl is not None:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        os.close(fd)
+
+
+def git(root, *args, stdin=None, binary=False):
+    done = subprocess.run(["git", "-C", root, *args], input=stdin, capture_output=True, check=False,
+                          text=not binary)
+    return done.returncode, done.stdout, done.stderr
+
+
+def shared(root):
+    """False only when git ignores .ai/memory/ (the record is local, nothing of it travels); True when it does not,
+    and when git cannot answer: the validator then keeps checking."""
+    try:
+        return git(root, "check-ignore", "-q", "--no-index", ".ai/memory/x")[0] != 0
+    except OSError:
+        return True
+
+
+def current_branch(root):
+    code, out, _ = git(root, "symbolic-ref", "--short", "-q", "HEAD")
+    if code == 0 and out.strip():
+        return out.strip()
+    code, out, _ = git(root, "rev-parse", "--short=8", "HEAD")
+    return "HEAD@%s" % (out.strip() if code == 0 and out.strip() else "unborn")
+
+
+def memory_dir(root):
+    return os.path.join(root, MEMORY_REL)
+
+
+def local_path(root, *parts):
+    return os.path.join(root, LOCAL_REL, *parts)
+
+
+def read_bytes(path):
+    try:
+        with open(path, "rb") as fh:
+            return fh.read()
+    except OSError:
+        return None

package/skills/ai-task/memory_migrate.py

@@ -0,0 +1,187 @@
+"""Migration (§D12, R25): the plan and report of a move from files to packages, its backup and apply, the
+risks stub and the move of agent logs."""
+import collections
+import os
+import shutil
+import tarfile
+from datetime import datetime, timezone
+
+import memory_compact as mc
+import memory_config as mcfg
+import memory_format as mf
+import memory_io as mio
+import memory_packages as mpkg
+import memory_risks as mrisks
+import memory_verify as mver
+
+
+# ------------------------------------------------------------------ migration (§D12, R25)
+def migration_plan(root):
+    """What --report shows and --apply does, from HEAD's tracked files only."""
+    head = mver.rev(root, "HEAD")
+    if not head:
+        raise mio.MemoryError_("migration reads HEAD: commit first", 2)
+    tree = mver.GitTreeReader(root, head)
+    packages = mpkg.load_packages(root)
+    sealed = {mf.key_of(e) for _, entries, _ in packages.values() for e in entries if e.get("kind") == "task"}
+    tasks = sorted({p.split("/")[2] for p in tree.paths() if p.startswith(".ai/reports/T-")})
+    plan = []
+    for task in tasks:
+        found = mc.compact_instances(tree, task, "tracked")
+        journal = tree.read(".ai/reports/%s/events.jsonl" % task)
+        names = {e.get("task") for _, e in mc.parse_journal(journal) if e} if journal else set()
+        logs = [(p, len(tree.read(p) or b"")) for p in tree.paths()
+                if p.startswith(".ai/reports/%s/" % task) and p.endswith(".log")]
+        plan.append({"task": task, "compactions": found, "journal": journal is not None,
+                     "names": sorted(n for n in names if n), "logs": logs,
+                     "sealed": [mf.key_of(c.seal) for c in found if c.seal and mf.key_of(c.seal) in sealed]})
+    return head, plan
+
+
+def migrate_report(root):
+    head, plan = migration_plan(root)
+    kinds, dropped = collections.Counter(), collections.Counter()
+    lines = ["# Migration report — %s" % mio.now(), "", "HEAD %s; tracked files only, so every clone gives the same "
+             "rids." % head[:12], "", "## Tasks", "",
+             "| task | instances | journal | name in journal | coverage | result | sealed already |",
+             "|---|---|---|---|---|---|---|"]
+    total_logs = []
+    for item in plan:
+        found = item["compactions"]
+        for c in found:
+            if c.seal:
+                for e in c.entries:
+                    kinds[e["kind"]] += 1
+                dropped.update(c.seal["counts"]["dropped"])
+        cov = ", ".join("%s/%s" % (c.coverage["accounted"], c.coverage["lines"]) for c in found) or "-"
+        names = ", ".join(item["names"]) or "-"
+        mismatch = " ≠ dir" if item["names"] and item["names"] != [item["task"]] else ""
+        lines.append("| %s | %d | %s | %s%s | %s | %s | %s |" % (
+            item["task"], len(found), "yes" if item["journal"] else "no (state-only)", names, mismatch, cov,
+            ", ".join(c.seal["result"] for c in found if c.seal) or "no sources",
+            ", ".join(item["sealed"]) or "-"))
+        total_logs += item["logs"]
+    lines += ["", "## Kept per kind", ""] + ["- %s: %d" % (k, n) for k, n in sorted(kinds.items())]
+    lines += ["", "## Dropped per event (KEEP_RULES v1)", ""] + ["- %s: %d" % (k, n) for k, n in sorted(dropped.items())]
+    lines += ["", "## Committed logs (%d, %s bytes)" % (len(total_logs), mf.fmt_n(sum(s for _, s in total_logs))), ""]
+    lines += ["- %s (%s bytes)" % (p, mf.fmt_n(s)) for p, s in total_logs]
+    text = (mio.read_bytes(os.path.join(root, ".ai", "project", "known-risks.md")) or b"").decode("utf-8")
+    risks, leftovers = mc.parse_known_risks(text)
+    titles = collections.Counter(r["title"] for r in risks)
+    lines += ["", "## known-risks.md", "", "- sections parsed: %d" % len(risks),
+              "- lines outside a section: %d" % len(leftovers["lines"]),
+              "- label derived (no Label line): %d" % sum(1 for r in risks if r["label_derived"]),
+              "- renders byte for byte: %s" % ("yes" if mc.render_known_risks(risks, leftovers) == text else "NO"),
+              "- duplicate titles: %s" % (", ".join(t for t, n in titles.items() if n > 1) or "none")]
+    report = "\n".join(lines) + "\n"
+    mio.atomic_write(mio.local_path(root, "migration-report.md"), report)
+    return report
+
+
+def backup(root):
+    path = mio.local_path(root, "backup-%s.tar" % datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ"))
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with tarfile.open(path, "w") as tar:
+        for rel in (".ai/reports", ".ai/project/known-risks.md"):
+            if os.path.exists(os.path.join(root, rel)):
+                tar.add(os.path.join(root, rel), arcname=rel)
+    return path
+
+
+def migrate_apply(root, risks=False):
+    """Closed legacy tasks into batches by their closed_at period; then, with
+    risks, known-risks.md into risk entries and a stub."""
+    cfg = mcfg.load_config(root)
+    saved = backup(root)
+    out = ["backup: %s" % os.path.relpath(saved, root)]
+    if risks:
+        return out + migrate_risks(root, cfg)
+    _, plan = migration_plan(root)
+    groups = collections.defaultdict(list)
+    skipped, incomplete = [], []
+    for item in plan:
+        for c in item["compactions"]:
+            if not c.seal or c.seal["result"] not in ("closed", "abandoned", "restarted"):
+                continue
+            key = mf.key_of(c.seal)
+            if key in item["sealed"]:
+                skipped.append(key)
+                continue
+            if c.coverage["accounted"] != c.coverage["lines"] or c.coverage["skipped"] or c.problems:
+                incomplete.append((key, c.coverage, c.problems))
+                continue
+            when = c.seal.get("closed_at") or c.seal.get("started_at") or c.seal["ts"]
+            groups[mf.period_of(when, cfg.period)].append(c)
+    written = 0
+    with mio.locked(root):
+        for period in sorted(groups):
+            # Whole tasks per batch, a new batch before package_max_bytes (V8).
+            batches, size = [[]], 0
+            for c in groups[period]:
+                task_bytes = sum(len(mf.canonical(e)) + 1 for e in c.entries + [c.seal])
+                if batches[-1] and size + task_bytes > cfg.package_max_bytes:
+                    batches.append([])
+                    size = 0
+                batches[-1].append(c)
+                size += task_bytes
+            for batch in batches:
+                name = mpkg.new_batch_name(root, period, cfg.author)
+                parts = mf.parse_package_name(name)
+                entries = [e for c in batch for e in c.entries + [c.seal]]
+                mio.atomic_write(os.path.join(mio.memory_dir(root), name),
+                             mf.render_package(mf.package_header(period, cfg.author, parts["batch"], mio.now()),
+                                               entries))
+                written += len(batch)
+                out.append("package: %s (%d tasks, %d entries)" % (os.path.join(mio.MEMORY_REL, name), len(batch),
+                                                                   len(entries)))
+    findings = mver.check_packages(mpkg.load_packages(root), cfg.package_max_bytes)
+    out.append("migrated %d task instance(s); %d already sealed; %d incomplete (reported, not exported)"
+               % (written, len(skipped), len(incomplete)))
+    out += ["incomplete: %s coverage %s/%s %s" % (k, cov["accounted"], cov["lines"], "; ".join(p))
+            for k, cov, p in incomplete]
+    out += [mver.format_finding(f) for f in findings]
+    return out
+
+
+STUB = """# Known risks
+
+<!-- The risks live in the record since {date}: `state.py memory risks --md` renders
+     them, `state.py memory risk add|close` records them (spec compact-project-memory
+     §D9, OQ4). A section written here is still read, as before the migration. -->
+"""
+
+
+def migrate_risks(root, cfg):
+    path = os.path.join(root, ".ai", "project", "known-risks.md")
+    text = (mio.read_bytes(path) or b"").decode("utf-8")
+    import memory_store  # pylint: disable=import-outside-toplevel
+    entries = memory_store.risk_entries_from_md(text)
+    risks, leftovers = mc.parse_known_risks(text)
+    rendered = mc.render_known_risks([{"text": e["text"]} for e in entries], leftovers)
+    if rendered != text:
+        raise mio.MemoryError_("known-risks.md does not render byte for byte from its entries — nothing changed", 3)
+    entries = [dict(e, actor="migration", src=["known-risks.md#%s" % e["rkey"]]) for e in entries]
+    entries = [mf.with_rid(e) for e in entries]
+    name = mrisks.append_entries(root, cfg, entries)
+    mio.atomic_write(path, STUB.format(date=mio.now()[:10]))
+    del risks
+    return ["risks: %d entries into %s; known-risks.md is a stub" % (len(entries), os.path.join(mio.MEMORY_REL, name))]
+
+
+def move_logs(root):
+    head = mver.rev(root, "HEAD")
+    tree = mver.GitTreeReader(root, head) if head else None
+    logs = [p for p in (tree.paths() if tree else []) if p.startswith(".ai/reports/") and p.endswith(".log")]
+    moved = []
+    for rel in logs:
+        task = rel.split("/")[2]
+        src = os.path.join(root, rel)
+        if not os.path.exists(src):
+            continue
+        dest = os.path.join(root, ".ai", "state", "logs", task, "legacy", os.path.basename(rel))
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        shutil.move(src, dest)
+        moved.append(rel)
+    listing = mio.local_path(root, "logs-to-rm.txt")
+    mio.atomic_write(listing, "".join("%s\n" % p for p in moved))
+    return moved, "git rm --cached --quiet --pathspec-from-file=%s" % os.path.relpath(listing, root)

package/skills/ai-task/memory_packages.py

@@ -0,0 +1,83 @@
+"""The packages on disk: loading them, the id and seal lookups over them, the batch ledger and the open
+batch an export writes into."""
+import collections
+import contextlib
+import json
+import os
+import random
+
+import memory_format as mf
+import memory_io as mio
+
+
+# ------------------------------------------------------------------ packages on disk
+def load_packages(root):
+    """{name: (header, entries, errors)} for every package in the working tree."""
+    out = {}
+    base = mio.memory_dir(root)
+    for name in sorted(os.listdir(base)) if os.path.isdir(base) else []:
+        if name.endswith(".jsonl"):
+            out[name] = mf.parse_package(mio.read_bytes(os.path.join(base, name)) or b"", name)
+    return out
+
+
+def all_rids(packages):
+    return {e["rid"] for _, entries, _ in packages.values() for e in entries}
+
+
+def seals_by_key(packages):
+    out = collections.defaultdict(list)
+    for name, (_, entries, _) in packages.items():
+        for e in entries:
+            if e.get("kind") == "task":
+                out[mf.key_of(e)].append((name, e))
+    return out
+
+
+def read_batches(root):
+    with contextlib.suppress(OSError, ValueError):
+        data = mio.read_json(mio.local_path(root, "batches.json"))
+        if isinstance(data, dict) and isinstance(data.get("open"), dict):
+            return data
+    return {"schema": 1, "open": {}}
+
+
+def write_batches(root, data):
+    mio.atomic_write(mio.local_path(root, "batches.json"), json.dumps(data, sort_keys=True, indent=1) + "\n")
+
+
+def new_batch_name(root, period, author):
+    rng = random.SystemRandom()
+    for _ in range(64):
+        batch = "".join(rng.choice(mio.BATCH_CHARS) for _ in range(4))
+        name = mf.package_name(period, author, batch)
+        if not os.path.exists(os.path.join(mio.memory_dir(root), name)):
+            return name
+    raise mio.MemoryError_("no free batch name for %s.%s" % (period, author), 3)
+
+
+def open_batch(root, cfg, stamp=None):
+    """The branch's open batch, reused while it is in the tree, the author's,
+    of the current period and under package_max_bytes; else a new name.
+    Called under the lock."""
+    stamp = stamp or mio.now()
+    period = mf.period_of(stamp, cfg.period)
+    branch = mio.current_branch(root)
+    books = read_batches(root)
+    name = books["open"].get(branch)
+    if name:
+        parts = mf.parse_package_name(name)
+        path = os.path.join(mio.memory_dir(root), name)
+        header = None
+        data = mio.read_bytes(path)
+        if data:
+            header, _, _ = mf.parse_package(data.split(b"\n", 1)[0] + b"\n", name)
+        if parts and data and header and header.get("author") == cfg.author and parts["period"] == period \
+                and parts["batch"] and len(data) < cfg.package_max_bytes:
+            return name, branch, books
+    name = new_batch_name(root, period, cfg.author)
+    return name, branch, books
+
+
+def sealed_task_ids(packages):
+    return {e.get("task") for _, entries, _ in packages.values() for e in entries if e.get("kind") == "task"}

package/skills/ai-task/memory_risks.py

@@ -0,0 +1,84 @@
+"""Risks in the record (§D9): the files-mode and packages-mode writers of a risk entry and the journal
+append they share."""
+import os
+
+import memory_compact as mc
+import memory_format as mf
+import memory_io as mio
+import memory_packages as mpkg
+
+
+# ------------------------------------------------------------------ risks (§D9)
+def risk_add_files(root, title, where, label, what, likely, fix, status, found):
+    """Files mode: append the template section (plus Label) to known-risks.md."""
+    import memory_compact  # pylint: disable=import-outside-toplevel,reimported
+    path = os.path.join(root, ".ai", "project", "known-risks.md")
+    text = mio.read_bytes(path)
+    text = text.decode("utf-8") if text is not None else "# Known risks\n"
+    risks, _ = memory_compact.parse_known_risks(text)
+    rkey = memory_compact.rkey_of(title)
+    if any(r["rkey"] == rkey for r in risks):
+        raise mio.MemoryError_("a risk titled %r is already recorded (%s)" % (title, rkey), 2)
+    section = memory_compact.risk_section(title, where, label, what, likely, fix, status, found)
+    body = text.rstrip("\n") + "\n\n" + "\n".join(section) + "\n"
+    mio.atomic_write(path, body)
+    return rkey
+
+
+def risk_close_files(root, rkey, status, why):
+    import memory_compact  # pylint: disable=import-outside-toplevel,reimported
+    path = os.path.join(root, ".ai", "project", "known-risks.md")
+    text = (mio.read_bytes(path) or b"").decode("utf-8")
+    risks, leftovers = memory_compact.parse_known_risks(text)
+    hit = [r for r in risks if r["rkey"] == rkey]
+    if not hit:
+        raise mio.MemoryError_("no risk %s in known-risks.md ('state.py memory risks --status all')" % rkey, 1)
+    lines = hit[0]["text"].split("\n")
+    for i, line in enumerate(lines):
+        if line.startswith("- **Status**:"):
+            lines[i] = "- **Status**: %s — %s" % (status, why)
+            break
+    else:
+        lines.append("- **Status**: %s — %s" % (status, why))
+    hit[0]["text"] = "\n".join(lines)
+    mio.atomic_write(path, memory_compact.render_known_risks(risks, leftovers))
+
+
+def risk_data(title, where, label, what, likely, fix, status, why=None, supersedes=None, by=None):
+    data = {"rkey": mc.rkey_of(title), "title": title, "where": where, "label": label, "what": what,
+            "likelihood": likely, "fix": fix, "status": status, "status_why": why, "supersedes": supersedes}
+    if by:
+        data["by"] = by
+    return data
+
+
+def standalone_risk(root, cfg, data, runtime="unknown", by=None):
+    """A risk with no task in flight: one entry, straight into the open batch."""
+    entry = {"v": mf.FORMAT, "task": None, "inst": 1, "seq": 0, "kind": "risk", "ts": mio.now(), "actor": "agent",
+             "by": by, "runtime": runtime if runtime in mf.RUNTIMES else "unknown", "src": ["state.py memory risk"]}
+    entry.update({k: data.get(k) for k in ("rkey", "title", "where", "label", "what", "likelihood", "fix",
+                                           "status", "status_why")})
+    entry.update(found_by=None, text=None)
+    if data.get("supersedes"):
+        entry["supersedes"] = data["supersedes"]
+    entry = mf.with_rid(entry)
+    append_entries(root, cfg, [entry])
+    return entry
+
+
+def append_entries(root, cfg, entries):
+    """Entries outside a close (a standalone risk, a redaction) into the open batch."""
+    with mio.locked(root):
+        name, branch, books = mpkg.open_batch(root, cfg)
+        packages = mpkg.load_packages(root)
+        have = mpkg.all_rids(packages)
+        header, current, _ = packages.get(name, (None, [], []))
+        parts = mf.parse_package_name(name)
+        header = header or mf.package_header(parts["period"], cfg.author, parts["batch"], mio.now())
+        new = [e for e in entries if e["rid"] not in have]
+        if new:
+            mio.atomic_write(os.path.join(mio.memory_dir(root), name),
+                         mf.render_package(header, [mf.strip_private(e) for e in current] + new))
+            books["open"][branch] = name
+            mpkg.write_batches(root, books)
+    return name