riskrails 4.0.1 → 4.2.0

package/hooks/guard/paths_shell.py

@@ -0,0 +1,288 @@
+"""The awk segmenter of the retired shell guard: shell_segments cuts a command into its segments,
+words and redirections, with the keyword, flag and redirection tables it reads.
+
+R16: every name here is core (no file, clock or subprocess access).
+Moved from paths.py in WP5 (small-oop-modules), unchanged.
+"""
+import re
+from guard.common import chomp_all
+
+
+_KEYWORDS = {"if", "then", "else", "elif", "do", "while", "until", "!", "{", "}", "time", "exec",
+             "command", "nohup", "builtin", "env", "sudo"}
+_FLAGGED = {"time", "exec", "command", "env", "sudo"}
+_ASSIGN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\+?=")
+_SPECIAL_OUT = re.compile(r"""['$"#<(\n`)&;|\\]""")
+_SPECIAL_D = re.compile(r'["$`\n\\]')
+_SPECIAL_A = re.compile(r"['\n\\]")
+
+
+def shell_segments(cmd):
+    """The awk segmenter of shell_segments, character for character: the
+    simple commands of a shell line, verb first, one per output line."""
+    src = cmd + "\n"
+    n = len(src)
+    out = []
+    cur = []
+    stk, qst = [], []
+    q = ""
+    nh = 0
+    hd, hs = [], []
+    i = 0
+
+    def emit():
+        s = "".join(cur)
+        cur.clear()
+        while True:
+            s = s.lstrip(" \t")
+            if s == "":
+                return
+            qq = ""
+            k = 0
+            ln = len(s)
+            while k < ln:
+                c = s[k]
+                if qq:
+                    if c == qq:
+                        qq = ""
+                elif c in "\"'":
+                    qq = c
+                elif c in " \t":
+                    break
+                k += 1
+            w = s[:k]
+            if w in _KEYWORDS:
+                s = s[k:]
+                if w in _FLAGGED:
+                    while True:
+                        s = s.lstrip(" \t")
+                        if not s.startswith("-"):
+                            break
+                        j = 0
+                        while j < len(s) and s[j] not in " \t":
+                            j += 1
+                        s = s[j:]
+                continue
+            if _ASSIGN.match(w):
+                s = s[k:]
+                continue
+            break
+        out.append(s)
+
+    def cur_ends(chars):
+        return bool(cur) and cur[-1][-1:] in chars and cur[-1][-1:] != ""
+
+    while i < n:
+        c = src[i]
+        d = src[i + 1] if i + 1 < n else ""
+        if q == "s":
+            j = src.find("'", i)
+            k = src.find("\n", i)
+            if j < 0:
+                j = n
+            if 0 <= k < j:
+                cur.append(src[i:k] + " ")
+                i = k + 1
+                continue
+            cur.append(src[i:j + 1])
+            i = j + 1
+            if j < n:
+                q = ""
+            continue
+        if q == "a":
+            m = _SPECIAL_A.search(src, i)
+            j = m.start() if m else n
+            if j > i:
+                cur.append(src[i:j])
+                i = j
+                continue
+            if c == "\\":
+                cur.append(c + d)
+                i += 2
+                continue
+            if c == "'":
+                q = ""
+            cur.append(" " if c == "\n" else c)
+            i += 1
+            continue
+        if c == "\\":
+            if d == "\n":
+                i += 2
+                continue
+            cur.append(c + d)
+            i += 2
+            continue
+        if q == "d":
+            m = _SPECIAL_D.search(src, i)
+            j = m.start() if m else n
+            if j > i:
+                cur.append(src[i:j])
+                i = j
+                continue
+            if c == '"':
+                q = ""
+                cur.append(c)
+                i += 1
+                continue
+            if c == "$" and d == "(":
+                stk.append("p")
+                qst.append(q)
+                q = ""
+                emit()
+                i += 2
+                continue
+            if c == "`":
+                stk.append("b")
+                qst.append(q)
+                q = ""
+                emit()
+                i += 1
+                continue
+            if c == "$":
+                cur.append(c)
+                i += 1
+                continue
+            cur.append(" " if c == "\n" else c)
+            i += 1
+            continue
+        # outside quotes
+        m = _SPECIAL_OUT.search(src, i)
+        j = m.start() if m else n
+        if j > i:
+            cur.append(src[i:j])
+            i = j
+            continue
+        if c == "'":
+            q = "s"
+            cur.append(c)
+            i += 1
+            continue
+        if c == "$" and d == "'":
+            q = "a"
+            cur.append(c + d)
+            i += 2
+            continue
+        if c == '"':
+            q = "d"
+            cur.append(c)
+            i += 1
+            continue
+        if c == "#" and (not cur or "".join(cur) == "" or cur_ends(" \t")):
+            k = src.find("\n", i)
+            i = k if k >= 0 else n
+            continue
+        if c == "<" and d == "<" and src[i + 2:i + 3] == "<":
+            cur.append("<<<")
+            i += 3
+            continue
+        if (c == "$" and d == "(" and src[i + 2:i + 3] == "(") or (c == "(" and d == "("):
+            j = i + (3 if c == "$" else 2)
+            depth = 2
+            while j < n and depth > 0:
+                e = src[j]
+                if e == "(":
+                    depth += 1
+                elif e == ")":
+                    depth -= 1
+                j += 1
+            cur.append(src[i:j])
+            i = j
+            continue
+        if c == "<" and d == "<":
+            j = i + 2
+            strip = 0
+            if src[j:j + 1] == "-":
+                strip = 1
+                j += 1
+            while src[j:j + 1] in (" ", "\t") and j < n:
+                j += 1
+            w = []
+            wq = ""
+            while j < n:
+                e = src[j]
+                if wq:
+                    if e == wq:
+                        wq = ""
+                    else:
+                        w.append(e)
+                    j += 1
+                    continue
+                if e in "'\"":
+                    wq = e
+                    j += 1
+                    continue
+                if e == "\\":
+                    w.append(src[j + 1:j + 2])
+                    j += 2
+                    continue
+                if e in " \t\n;&|<>()":
+                    break
+                w.append(e)
+                j += 1
+            word = "".join(w)
+            if word:
+                nh += 1
+                hd.append(word)
+                hs.append(strip)
+            i = j
+            continue
+        if c == "\n":
+            emit()
+            i += 1
+            for h in range(nh):
+                while i < n:
+                    e = src.find("\n", i)
+                    line = src[i:e] if e >= 0 else src[i:]
+                    i = e + 1 if e >= 0 else n
+                    if hs[h]:
+                        line = line.lstrip("\t")
+                    if line == hd[h]:
+                        break
+            nh = 0
+            hd, hs = [], []
+            continue
+        if c == "$" and d == "(":
+            stk.append("p")
+            qst.append(q)
+            emit()
+            i += 2
+            continue
+        if c == "$":
+            cur.append(c)
+            i += 1
+            continue
+        if c == "`":
+            if stk and stk[-1] == "b":
+                stk.pop()
+                q = qst.pop()
+            else:
+                stk.append("b")
+                qst.append(q)
+            emit()
+            i += 1
+            continue
+        if c == "(":
+            stk.append("p")
+            qst.append(q)
+            emit()
+            i += 1
+            continue
+        if c == ")":
+            if stk and stk[-1] == "p":
+                stk.pop()
+                q = qst.pop()
+            emit()
+            i += 1
+            continue
+        if c == "&" and (cur_ends("<>") or d == ">"):
+            cur.append(c)
+            i += 1
+            continue
+        if c in ";|&":
+            emit()
+            i += 1
+            continue
+        cur.append(c)
+        i += 1
+    emit()
+    return chomp_all("".join(s + "\n" for s in out))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "RiskRails: a weight-based engineering pipeline for Claude Code and Codex — scoped steps, enforcement hooks, adversarial review, model routing.",
   "keywords": ["claude-code", "codex", "sdlc", "agents", "guardrails", "code-review"],
   "homepage": "https://github.com/vanssata/claude-agentic-sdlc-module#readme",

package/skills/AGENTS.md

@@ -1,6 +0,0 @@
-<!-- riskrails:rule:skills:start -->
-# Skills rules
-- Weigh a change by what it does to a user project's decisions, never by the skill being a process (constitution C6). The mode is what W gives (`state.py weight`); the rows below set the behaviour axis.
-- behaviour 0: skill or agent text, `usage-report`, no `state.py` refusal moves. behaviour 1: adds a `state.py` check, a sensor or a refusal. behaviour 2: weakens a refusal, changes the approval path (`approve`, `questions --sync`, `AI_UNATTENDED`, the review verdict transitions) or changes install and migration (the `project-update` merge; a migration also raises reversibility through its hint) — declare it, `--declare behaviour=2:"<the effect>"`. Start such a task with `start --mode full --by <name>`: its weight lands in guarded, and these effects keep a STRONG review and the gate.
-- A change to a shipped template or to `ai/` runs `tools/build-template-history.py` in the same task, or `tests/test_project_update.py` (`test_history_covers_every_template`) goes red.
-<!-- riskrails:rule:skills:end -->

package/skills/CLAUDE.md

@@ -1,6 +0,0 @@
-<!-- riskrails:rule:skills:start -->
-# Skills rules
-- Weigh a change by what it does to a user project's decisions, never by the skill being a process (constitution C6). The mode is what W gives (`state.py weight`); the rows below set the behaviour axis.
-- behaviour 0: skill or agent text, `usage-report`, no `state.py` refusal moves. behaviour 1: adds a `state.py` check, a sensor or a refusal. behaviour 2: weakens a refusal, changes the approval path (`approve`, `questions --sync`, `AI_UNATTENDED`, the review verdict transitions) or changes install and migration (the `project-update` merge; a migration also raises reversibility through its hint) — declare it, `--declare behaviour=2:"<the effect>"`. Start such a task with `start --mode full --by <name>`: its weight lands in guarded, and these effects keep a STRONG review and the gate.
-- A change to a shipped template or to `ai/` runs `tools/build-template-history.py` in the same task, or `tests/test_project_update.py` (`test_history_covers_every_template`) goes red.
-<!-- riskrails:rule:skills:end -->

package/skills/ai-init/scaffold-ai.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # Idempotent .ai/ scaffold for RiskRails.
-#   scaffold-ai.sh [project-dir] [--runtime auto|claude|codex|both]   (default: $PWD, auto)
+#   scaffold-ai.sh [project-dir] [--runtime auto|claude|codex|both|none]   (default: $PWD, auto)
+#   none: .ai/ and .gitignore only, no instruction file; a whole value, never part of a comma list
 #
 # A shim: the scaffold lives in skills/rr-setup/scaffold_ai.py and reads its
 # templates from this directory. This file keeps every caller's command working.

package/skills/ai-init/templates/.ai/policies/safety.md

@@ -29,9 +29,10 @@ section, and the human decides whether they become their own task.
 
 The compact record is the human's to switch: `state.py memory enable`, `disable`,
 `cleanup`, `pack`, `redact` and `migrate --move-logs` take the human route, as
-`approve` does, and `.ai/memory/` and `.ai/local/memory/` are written by
-`state.py` alone — an agent never edits them (`state.py memory --help`; the
-plugin's `docs/local-memory.md`).
+`approve` does. `enable` may also run as the command the human picked in the
+`/rr-setup` dialog; the rest have no dialog route. `.ai/memory/` and
+`.ai/local/memory/` are written by `state.py` alone — an agent never edits them
+(`state.py memory --help`; the plugin's `docs/local-memory.md`).
 
 ## Scope
 

package/skills/ai-init/templates/gitignore.snippet

@@ -4,3 +4,5 @@
 .ai/state/*.tmp
 .ai/state/*.jsonl
 .ai/local/
+.ai/memory/
+.ai/reports/

package/skills/ai-task/memory_cleanup.py

@@ -0,0 +1,213 @@
+"""Cleanup, restore, redaction (§D6, §D13) and pack (§D4, R7): the writers that remove, bring back, blank
+or archive what a package holds."""
+import json
+import os
+import re
+import shutil
+
+import memory_config as mcfg
+import memory_format as mf
+import memory_io as mio
+import memory_packages as mpkg
+import memory_verify as mver
+
+
+# ------------------------------------------------------------------ cleanup, restore, redact (§D6, §D13)
+def cleanup_ready(root, task_id, cfg, packages=None):
+    """The R22 conditions for one task, or the first that fails."""
+    packages = packages if packages is not None else mpkg.load_packages(root)
+    seals = [(n, e) for n, (_, entries, _) in packages.items() for e in entries
+             if e.get("kind") == "task" and e.get("task") == task_id]
+    if not cfg.cleanup:
+        return "cleanup is off in %s" % mio.POLICY_REL
+    if not seals:
+        return "no seal for %s in a package in the working tree" % task_id
+    findings = mver.check_packages({n: packages[n] for n, _ in seals}, cfg.package_max_bytes)
+    if findings:
+        return "its package does not verify (%s)" % findings[0].what
+    for _, seal in seals:
+        if (seal.get("counts") or {}).get("skipped"):
+            return "%s has %s torn journal line(s)" % (mf.key_of(seal), seal["counts"]["skipped"])
+    journal = mio.read_bytes(os.path.join(root, ".ai", "reports", task_id, "events.jsonl"))
+    if journal is not None:
+        found = mver.check_journals(lambda rel: journal if rel.endswith("events.jsonl") else None,
+                               [".ai/reports/%s/events.jsonl" % task_id], packages)
+        found = [f for f in found if f.check == "V5"]
+        if found:
+            return "coverage is incomplete (%s)" % found[0].what
+    return None
+
+
+def cleanup_task(root, task_id, cfg):
+    """B6: .ai/reports/<id> → .ai/state/logs/<id>/report; copy, verify,
+    remove when the two are on different filesystems."""
+    why = cleanup_ready(root, task_id, cfg)
+    if why:
+        raise mio.MemoryError_(why, 1)
+    src = os.path.join(root, ".ai", "reports", task_id)
+    dest = os.path.join(root, ".ai", "state", "logs", task_id, "report")
+    if not os.path.isdir(src):
+        return "%s already cleaned up" % task_id
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    if os.path.exists(dest):
+        raise mio.MemoryError_("%s exists: 'state.py memory restore %s' first" % (os.path.relpath(dest, root), task_id), 3)
+    try:
+        if os.environ.get("AI_MEMORY_FORCE_EXDEV"):
+            raise OSError(18, "Invalid cross-device link (forced)")
+        os.replace(src, dest)
+    except OSError as exc:
+        if exc.errno != 18:
+            raise
+        shutil.copytree(src, dest)
+        if tree_digest(src) != tree_digest(dest):
+            shutil.rmtree(dest, ignore_errors=True)
+            raise mio.MemoryError_("the copy of %s does not match its source — nothing removed" % task_id, 3) \
+                from exc
+        shutil.rmtree(src)
+    return "%s → %s" % (os.path.relpath(src, root), os.path.relpath(dest, root))
+
+
+def tree_digest(path):
+    import hashlib  # pylint: disable=import-outside-toplevel
+    h = hashlib.sha256()
+    for dirpath, dirs, names in os.walk(path):
+        dirs.sort()
+        for name in sorted(names):
+            full = os.path.join(dirpath, name)
+            h.update(os.path.relpath(full, path).encode() + b"\0" + (mio.read_bytes(full) or b"") + b"\0")
+    return h.hexdigest()
+
+
+def cleanup(root, ids):
+    cfg = mcfg.load_config(root)
+    if not cfg.packages:
+        raise mio.MemoryError_("files mode: cleanup needs packages mode", 2)
+    if not cfg.cleanup:
+        raise mio.MemoryError_("cleanup is off: set \"cleanup\": true in %s once 'memory verify --all' and "
+                           "'--fresh-clone' are green (§D6)" % mio.POLICY_REL, 2)
+    findings = [f for f in mver.verify(root) if not f.check.endswith("-warn")]
+    if findings:
+        raise mio.MemoryError_("'memory verify --all' is not green: %s" % mver.format_finding(findings[0]), 1)
+    packages = mpkg.load_packages(root)
+    if ids == "all":
+        ids = sorted(mpkg.sealed_task_ids(packages) & set(os.listdir(os.path.join(root, ".ai", "reports"))))
+    out = []
+    for task_id in ids:
+        try:
+            out.append(cleanup_task(root, task_id, cfg))
+        except mio.MemoryError_ as exc:
+            out.append("%s kept: %s" % (task_id, exc))
+    return out
+
+
+def restore(root, ids):
+    import memory_store  # pylint: disable=import-outside-toplevel
+    logs = os.path.join(root, ".ai", "state", "logs")
+    if ids == "all":
+        ids = sorted(n for n in os.listdir(logs) if os.path.isdir(os.path.join(logs, n, "report"))) \
+            if os.path.isdir(logs) else []
+        history = memory_store.FileHistory(root, mcfg.load_config(root))
+        ids = sorted(set(ids) | {s.get("task") for s in history.seals().values()
+                                 if not os.path.isdir(os.path.join(root, ".ai", "reports", s.get("task") or "-"))
+                                 and mf.NEW_ID_RE.match(s.get("task") or "")})
+    out = []
+    history = None
+    for task_id in ids:
+        dest = os.path.join(root, ".ai", "reports", task_id)
+        raw = os.path.join(logs, task_id, "report")
+        if os.path.isdir(dest):
+            out.append("%s is in .ai/reports/ already" % task_id)
+            continue
+        if os.path.isdir(raw):
+            os.replace(raw, dest)
+            out.append("%s restored from %s" % (task_id, os.path.relpath(raw, root)))
+            continue
+        history = history or memory_store.FileHistory(root, mcfg.load_config(root))
+        entries = history.entries(task_id)
+        if not entries:
+            out.append("%s: nothing recorded" % task_id)
+            continue
+        os.makedirs(dest)
+        md = ["<!-- restored from record %s — a reconstruction, not the original task.md -->" % mio.now()]
+        md += mf.render_task_md(entries)
+        mio.atomic_write(os.path.join(dest, "task.md"), "\n".join(md) + "\n")
+        lines = []
+        for e in entries:
+            data = {k: v for k, v in e.items() if k not in mf.ENVELOPE}
+            data["restored"] = True
+            data["rid"] = e["rid"]
+            lines.append(json.dumps({"ts": e["ts"], "task": task_id, "event": "restored_%s" % e["kind"],
+                                     "actor": e["actor"], "runtime": e["runtime"], "stage": "",
+                                     "detail": "restored from record", "data": data}, ensure_ascii=False))
+        mio.atomic_write(os.path.join(dest, "events.jsonl"), "\n".join(lines) + "\n")
+        out.append("%s restored from record (task.md marked, events.jsonl with data.restored)" % task_id)
+    return out
+
+
+def redact(root, rid, field, why, by=None):
+    """The one exception to append-only (R8): the field becomes "[redacted]",
+    the line gets a new rid, a redaction entry names the old one."""
+    cfg = mcfg.load_config(root)
+    with mio.locked(root):
+        packages = mpkg.load_packages(root)
+        for name, (header, entries, _) in packages.items():
+            hit = [e for e in entries if e["rid"] == rid]
+            if not hit:
+                continue
+            entry = mf.strip_private(hit[0])
+            if field in mf.ENVELOPE or field not in entry:
+                raise mio.MemoryError_("%s has no redactable field %r" % (rid, field), 2)
+            new = dict(entry, **{field: "[redacted]"})
+            new = mf.with_rid(new)
+            note = mf.with_rid({"v": mf.FORMAT, "task": entry.get("task"), "inst": entry.get("inst") or 1,
+                                "seq": entry.get("seq") or 0, "kind": "redaction", "ts": mio.now(), "actor": "human",
+                                "by": by, "runtime": "unknown", "src": ["state.py memory redact"],
+                                "target": rid, "field": field, "why": why, "replacement": new["rid"]})
+            rest = [mf.strip_private(e) for e in entries if e["rid"] != rid]
+            mio.atomic_write(os.path.join(mio.memory_dir(root), name), mf.render_package(header, rest + [new, note]))
+            del cfg
+            return new["rid"], name
+    raise mio.MemoryError_("no entry %s in .ai/memory/" % rid, 1)
+
+
+# ------------------------------------------------------------------ pack (§D4, R7)
+def pack(root, period):
+    cfg = mcfg.load_config(root)
+    if not re.match(r"^\d{4}(?:-\d{2}|-Q[1-4])?$", period or ""):
+        raise mio.MemoryError_("--period takes YYYY-MM, YYYY-Qn or YYYY", 2)
+    grain = "quarter" if "-Q" in period else ("month" if "-" in period else "year")
+    current = mf.period_of(mio.now(), grain)
+    if period >= current:
+        raise mio.MemoryError_("period %s has not ended (now %s)" % (period, current), 2)
+    with mio.locked(root):
+        packages = mpkg.load_packages(root)
+        mine = [n for n in packages if (mf.parse_package_name(n) or {}).get("period") == period
+                and (mf.parse_package_name(n) or {}).get("author") == cfg.author]
+        if not mine:
+            raise mio.MemoryError_("no package of %s for %s" % (cfg.author, period), 1)
+        target = mf.package_name(period, cfg.author)
+        before = set()
+        entries = {}
+        for name in mine:
+            for e in packages[name][1]:
+                before.add(e["rid"])
+                entries[e["rid"]] = mf.strip_private(e)
+        seals = {mf.key_of(e): e for e in entries.values() if e.get("kind") == "task"}
+
+        def order(e):
+            seal = seals.get(mf.key_of(e)) or {}
+            return (seal.get("closed_at") or e.get("ts") or "", mf.key_of(e), e.get("seq") or 0, e["rid"])
+        ordered = sorted(entries.values(), key=order)
+        header = mf.package_header(period, cfg.author, None, mio.now())
+        data = b"\n".join([mf.canonical(header)] + [mf.canonical(e) for e in ordered]) + b"\n"
+        mio.atomic_write(os.path.join(mio.memory_dir(root), target), data)
+        _, check, errors = mf.parse_package(data, target)
+        if errors or {e["rid"] for e in check} != before:
+            raise mio.MemoryError_("the pack does not hold the batches' rid set — batches kept", 3)
+        removed = [n for n in mine if n != target]
+        for name in removed:
+            os.remove(os.path.join(mio.memory_dir(root), name))
+        books = mpkg.read_batches(root)
+        books["open"] = {b: n for b, n in books["open"].items() if n not in removed}
+        mpkg.write_batches(root, books)
+    return target, removed, len(before)

package/skills/ai-task/memory_compact.py

@@ -872,9 +872,34 @@ def _seal(ctx, entries, inst, last, state, started, closed, seal_src, summary, d
     if truncated:
         seal["truncated"] = truncated
     seal["unrecorded"] = sorted(set(unrecorded))
+    _fit_changes(seal)
     return mf.with_rid(seal)
 
 
+def _fit_changes(seal):
+    """GitHub #74: a seal line over mf.LINE_MAX_BYTES (a task that changed ~1200 files) is unreadable to
+    parse_package. Keep the longest prefix of `changes` whose line fits, say so in `truncated` and
+    `changes_truncated`. A seal that fits is untouched; the result depends only on the seal's own fields."""
+    rows = seal.get("changes")
+    if not isinstance(rows, list) or not rows or len(mf.canonical(mf.with_rid(seal))) <= mf.LINE_MAX_BYTES:
+        return
+    total = {k: sum(r[k] for r in rows if isinstance(r, dict) and isinstance(r.get(k), int)
+                    and not isinstance(r.get(k), bool)) for k in ("added", "deleted")}
+    seal["changes_truncated"] = {"rows": len(rows), "added": total["added"], "deleted": total["deleted"]}
+    seal["truncated"] = sorted(set(seal.get("truncated") or []) | {"changes"})
+    seal["changes"] = []
+    room = mf.LINE_MAX_BYTES - len(mf.canonical(mf.with_rid(seal)))
+    keep = 0
+    for row in rows:
+        room -= len(mf.canonical(row)) + (1 if keep else 0)
+        if room < 0:
+            break
+        keep += 1
+    seal["changes"] = rows[:keep]
+    while seal["changes"] and len(mf.canonical(mf.with_rid(seal))) > mf.LINE_MAX_BYTES:
+        seal["changes"] = seal["changes"][:-1]
+
+
 # ------------------------------------------------------------------ known-risks.md (§D9, R24)
 RISK_HEAD_RE = re.compile(r"^## (.+)$")
 RISK_FIELD_RE = re.compile(r"^- \*\*([^*]+)\*\*:\s?(.*)$")