riskrails 4.0.1 → 4.2.0

package/skills/ai-task/memory_verify.py

@@ -0,0 +1,316 @@
+"""Verification (§D6, §D10): the findings of the package and journal checks, verify and its fresh-clone form,
+the git tree reader and the range check the pre-push validator runs."""
+import collections
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+
+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
+
+
+# ------------------------------------------------------------------ verify (§D6)
+Finding = collections.namedtuple("Finding", "check path line what fix")
+
+
+def kept_lines(events, schema=None):
+    """The journal lines V5 requires to be the src of an entry."""
+    out = []
+    for number, event in events:
+        if not event:
+            continue
+        if event.get("event") == "task_started":
+            schema = (event.get("data") or {}).get("schema", schema)
+        rule = mf.classify(event.get("event"), schema)
+        if rule not in ("seal", "summary", "drop", "verify"):
+            out.append(number)
+    return out
+
+
+def check_packages(packages, max_bytes, sizes=None, changed=None, ref_name=None):
+    """V1, V3, V4, V8 over one tree's packages."""
+    findings = []
+    sizes = sizes or {}
+    for name, (_, kept, errors) in sorted(packages.items()):
+        if changed is not None and name not in changed:
+            continue
+        over = {e["_line"]: e for e in kept if "_over" in e}
+        for line, what in errors:
+            fix = ("restore the line from git ('git checkout -- %s') or 'state.py memory verify'"
+                   % os.path.join(mio.MEMORY_REL, name))
+            if line in over and what.startswith("line is "):
+                entry = over[line]
+                sizes_of = {k: len(mf.canonical(v)) for k, v in entry.items()
+                            if k not in mf.ENVELOPE and not k.startswith("_")}
+                field = max(sizes_of, key=sizes_of.get, default="changes")
+                fix = ("shorten it: 'state.py memory redact %s --field %s --why \"…\"' (the human's route)"
+                       % (entry["rid"], field))
+            findings.append(Finding("V1", os.path.join(mio.MEMORY_REL, name), line, what, fix))
+    by_key = collections.defaultdict(list)
+    conflicts = set()
+    redacted = {}
+    for name, (_, entries, _) in packages.items():
+        for e in entries:
+            by_key[mf.key_of(e)].append((name, e))
+            if e.get("kind") == "conflict":
+                conflicts.add((e.get("key"), tuple(e.get("rids") or [])))
+            if e.get("kind") == "redaction" and e.get("replacement"):
+                redacted[e["replacement"]] = e.get("target")
+    for key, items in sorted(by_key.items()):
+        seals = [(n, e) for n, e in items if e.get("kind") == "task"]
+        unique = {e["rid"]: (n, e) for n, e in seals}
+        chained = {e.get("supersedes") for _, e in unique.values() if e.get("supersedes")}
+        live = [rid for rid in unique if rid not in chained]
+        if len(live) > 1:
+            task = key.rsplit("#", 1)[0]
+            recorded = any(k == key and set(live) <= set(r) for k, r in conflicts)
+            if mf.NEW_ID_RE.match(task) and not recorded:
+                findings.append(Finding("V3", os.path.join(mio.MEMORY_REL, unique[live[0]][0]), None,
+                                        "%s has %d seals not chained by supersedes" % (key, len(live)),
+                                        "'state.py memory export %s' records the two as a conflict" % task))
+            elif not recorded:
+                findings.append(Finding("V3", os.path.join(mio.MEMORY_REL, unique[live[0]][0]), None,
+                                        "legacy %s has %d seals and no conflict entry" % (key, len(live)),
+                                        "'state.py memory export %s' records the conflict" % task))
+        rids = {e["rid"] for _, e in items if e.get("kind") not in ("task", "conflict", "redaction")}
+        if len(live) > 1:
+            continue                      # a recorded conflict: which entries are whose is not knowable
+        for rid in live:
+            name, seal = unique[rid]
+            own = sorted({redacted.get(r, r) for r in rids if _belongs(items, r, seal)})
+            if len(own) != seal.get("entries") or mf.seal_digest(own) != seal.get("digest"):
+                findings.append(Finding("V4", os.path.join(mio.MEMORY_REL, name), seal.get("_line"),
+                                        "%s: the seal names %s entries (%s), the package has %d" % (
+                                            key, seal.get("entries"), (seal.get("digest") or "")[:19], len(own)),
+                                        "'state.py memory export %s' re-exports it" % seal.get("task")))
+    for name, size in sorted(sizes.items()):
+        if size > 2 * max_bytes:
+            findings.append(Finding("V8", os.path.join(mio.MEMORY_REL, name), None,
+                                    "%d bytes, over twice package_max_bytes (%d)" % (size, max_bytes),
+                                    "a new batch opens on the next close; 'state.py memory pack' folds old ones"))
+        elif size > max_bytes:
+            findings.append(Finding("V8-warn", os.path.join(mio.MEMORY_REL, name), None,
+                                    "%d bytes, over package_max_bytes (%d)" % (size, max_bytes),
+                                    "nothing to do now; the next close opens a new batch"))
+    del ref_name
+    return findings
+
+
+def _belongs(items, rid, seal):
+    """Entries of a key that came before its seal (seq below the seal's)."""
+    for _, e in items:
+        if e["rid"] == rid:
+            return (e.get("seq") or 0) < (seal.get("seq") or 0)
+    return False
+
+
+def check_journals(read, paths, packages, cleanup_on=False):
+    """V5 (and V7 with cleanup) against the committed journals."""
+    findings = []
+    seals = mpkg.seals_by_key(packages)
+    sealed_tasks = {k.rsplit("#", 1)[0] for k in seals}
+    srcs = collections.defaultdict(set)
+    for _, entries, _ in packages.values():
+        for e in entries:
+            for s in e.get("src") or []:
+                srcs[mf.key_of(e)].add(s)
+    journals = sorted(p for p in paths if re.match(r"^\.ai/reports/[^/]+/events\.jsonl$", p))
+    for path in journals:
+        task = path.split("/")[2]
+        data = read(path) or b""
+        if b'"task_closed"' not in data:
+            continue
+        if not (mf.NEW_ID_RE.match(task) or task in sealed_tasks):
+            continue                       # an unmigrated legacy task: 'memory status' lists it
+        events = mc.parse_journal(data)
+        instances = mc.split_instances(events)
+        for inst, lines in enumerate(instances, 1):
+            key = "%s#%d" % (task, inst)
+            closed = any(e and e.get("event") == "task_closed" for _, e in lines)
+            if not closed and inst == len(instances):
+                continue
+            if key not in seals:
+                findings.append(Finding("V5", path, None, "%s is closed but has no seal" % key,
+                                        "state.py memory export %s" % task))
+                continue
+            missing = [n for n in kept_lines(lines) if "events.jsonl:%d" % n not in srcs[key]]
+            if missing:
+                findings.append(Finding("V5", path, missing[0], "%s: %d kept line(s) are no entry's src" % (
+                    key, len(missing)), "state.py memory export %s" % task))
+        if cleanup_on and task in sealed_tasks:
+            findings.append(Finding("V7", "/".join(path.split("/")[:3]) + "/", None,
+                                    "cleanup is on and %s is sealed" % task, "state.py memory cleanup %s" % task))
+    return findings
+
+
+def verify(root, scope="all", ids=None):
+    """Findings for --all or ids over the working tree; [] is green."""
+    cfg = mcfg.load_config(root)
+    packages = mpkg.load_packages(root)
+    sizes = {n: os.path.getsize(os.path.join(mio.memory_dir(root), n)) for n in packages}
+    findings = check_packages(packages, cfg.package_max_bytes, sizes)
+    reports = os.path.join(root, ".ai", "reports")
+    paths = []
+    for name in sorted(os.listdir(reports)) if os.path.isdir(reports) else []:
+        if ids and name not in ids:
+            continue
+        if os.path.exists(os.path.join(reports, name, "events.jsonl")):
+            paths.append(".ai/reports/%s/events.jsonl" % name)
+    findings += check_journals(lambda rel: mio.read_bytes(os.path.join(root, rel)), paths, packages, False)
+    if ids:
+        findings = [f for f in findings if any(i in (f.path or "") or i in f.what for i in ids)]
+    del scope
+    return findings
+
+
+def verify_fresh_clone(root):
+    """§D6: a local clone of HEAD, rebuilt from packages alone, shows every
+    sealed key as this clone does."""
+    import memory_store  # pylint: disable=import-outside-toplevel
+    findings = []
+    here = memory_store.FileHistory(root, mcfg.load_config(root))
+    keys = sorted({mf.key_of(e) for _, entries, _ in mpkg.load_packages(root).values() for e in entries
+                   if e.get("kind") == "task"})
+    with tempfile.TemporaryDirectory(prefix="ai-memory-clone-") as tmp:
+        clone = os.path.join(tmp, "clone")
+        code, _, err = mio.git(root, "clone", "-q", "--no-hardlinks", root, clone)
+        if code != 0:
+            raise mio.MemoryError_("git clone failed: %s" % err.strip(), 3)
+        there = memory_store.FileHistory(clone, mcfg.load_config(clone))
+        for key in keys:
+            a = "\n".join(mf.render_task_md(here.entries(key)))
+            b = "\n".join(mf.render_task_md(there.entries(key)))
+            if a != b:
+                findings.append(Finding("fresh-clone", key, None, "renders differently in a fresh clone",
+                                        "commit .ai/memory/ (the clone sees HEAD only)"))
+    return findings
+
+
+def format_finding(f, ref=None):
+    where = f.path + (":%s" % f.line if f.line else "")
+    return "%s%s: %s: %s — fix: %s" % ("%s: " % ref if ref else "", f.check, where, f.what, f.fix)
+
+
+# ------------------------------------------------------------------ git trees (§D10)
+class GitTreeReader:
+    """Blobs of one commit, through one `git cat-file --batch`."""
+
+    def __init__(self, repo, sha):
+        self.repo, self.sha = repo, sha
+        self._cache = {}
+        self._paths = None
+
+    def paths(self):
+        if self._paths is None:
+            code, out, _ = mio.git(self.repo, "ls-tree", "-r", "-z", "--name-only", self.sha, binary=True)
+            self._paths = [p.decode("utf-8", "replace") for p in out.split(b"\0") if p] if code == 0 else []
+        return self._paths
+
+    def read_many(self, rels):
+        wanted = [r for r in rels if r not in self._cache]
+        if wanted:
+            stdin = "".join("%s:%s\n" % (self.sha, r) for r in wanted).encode("utf-8")
+            done = subprocess.run(["git", "-C", self.repo, "cat-file", "--batch"], input=stdin,
+                                  capture_output=True, check=False)
+            data, pos = done.stdout, 0
+            for rel in wanted:
+                end = data.find(b"\n", pos)
+                head = data[pos:end].split(b" ")
+                pos = end + 1
+                if len(head) == 2 and head[1] == b"missing" or len(head) < 3:
+                    self._cache[rel] = None
+                    continue
+                size = int(head[2])
+                self._cache[rel] = data[pos:pos + size]
+                pos += size + 1
+        return {r: self._cache.get(r) for r in rels}
+
+    def read(self, rel):
+        return self.read_many([rel])[rel]
+
+    def listdir(self, rel):
+        prefix = rel.rstrip("/") + "/"
+        return sorted({p[len(prefix):].split("/")[0] for p in self.paths() if p.startswith(prefix)})
+
+
+def rev(repo, name):
+    code, out, _ = mio.git(repo, "rev-parse", "--verify", "-q", name + "^{commit}")
+    return out.strip() if code == 0 and out.strip() else None
+
+
+def policy_at(repo, sha):
+    code, out, _ = mio.git(repo, "show", "%s:%s" % (sha, mio.POLICY_REL.replace(os.sep, "/")))
+    if code != 0:
+        return None
+    try:
+        data = json.loads(out)
+    except ValueError:
+        return {"mode": "invalid"}
+    return data if isinstance(data, dict) else {"mode": "invalid"}
+
+
+def validate_range(repo, old, new, local=False):
+    """(findings, stats) for the commits O..T (§D10). O may be None: then only
+    the structure of T is checked."""
+    started = time.time()
+    policy = policy_at(repo, new)
+    if policy is None or policy.get("mode", "files") == "files":
+        return None, {}
+    if policy.get("mode") == "invalid":
+        return [Finding("V1", mio.POLICY_REL, None, "memory.json at %s is not valid JSON" % new[:9],
+                        "fix the file, or 'state.py memory disable'")], {}
+    max_bytes = int(policy.get("package_max_bytes", mcfg.DEFAULTS["package_max_bytes"]))
+    tree = GitTreeReader(repo, new)
+    paths = tree.paths()
+    pkg_paths = [p for p in paths if p.startswith(".ai/memory/") and p.endswith(".jsonl")]
+    blobs = tree.read_many(pkg_paths)
+    packages = {p.split("/", 2)[2]: mf.parse_package(blobs[p] or b"", p.split("/", 2)[2]) for p in pkg_paths}
+    sizes = {p.split("/", 2)[2]: len(blobs[p] or b"") for p in pkg_paths}
+    changed, added = None, []
+    findings = []
+    if old:
+        code, out, _ = mio.git(repo, "diff", "--name-status", "--no-renames", old, new, "--", ".ai")
+        rows = [line.split("\t") for line in out.splitlines() if "\t" in line] if code == 0 else []
+        changed = {r[1].split("/", 2)[2] for r in rows if r[1].startswith(".ai/memory/")}
+        added = [r[1] for r in rows if r[0].startswith("A")]
+        before = GitTreeReader(repo, old)
+        old_pkgs = [p for p in before.paths() if p.startswith(".ai/memory/") and p.endswith(".jsonl")]
+        old_blobs = before.read_many(old_pkgs)
+        old_rids = set()
+        for p in old_pkgs:
+            _, entries, _ = mf.parse_package(old_blobs[p] or b"")
+            old_rids |= {e["rid"] for e in entries}
+        new_rids = mpkg.all_rids(packages)
+        redacted = {e.get("target") for _, entries, _ in packages.values() for e in entries
+                    if e.get("kind") == "redaction"}
+        lost = sorted(old_rids - new_rids - redacted)
+        if lost:
+            findings.append(Finding("V2", ".ai/memory/", None, "%d record(s) of %s are gone (%s…)" % (
+                len(lost), old[:9], lost[0]), "git checkout %s -- .ai/memory/ and merge the lines back" % old[:9]))
+    findings = check_packages(packages, max_bytes, sizes, changed) + findings
+    journals = [p for p in paths if re.match(r"^\.ai/reports/[^/]+/events\.jsonl$", p)]
+    journal_blobs = tree.read_many(journals)   # one cat-file --batch for every journal (§D10)
+    findings += check_journals(journal_blobs.get, journals, packages, bool(policy.get("cleanup")))
+    for path in added:
+        if path.startswith(".ai/reports/") and path.endswith(".log"):
+            findings.append(Finding("V6", path, None, "a log is committed under .ai/reports/",
+                                    "git rm --cached %s (logs live in .ai/state/logs/)" % path))
+    for path in paths:
+        # The index lives under .ai/local/; a project's own SQLite file elsewhere is not ours.
+        if path.startswith(".ai/local/") or path.startswith(".ai/state/logs/") or \
+                (path.startswith(".ai/") and ".sqlite3" in path):
+            findings.append(Finding("V6", path, None, "local data is committed",
+                                    "git rm --cached %s (.ai/local/ and .ai/state/logs/ stay local)" % path))
+    if local:
+        outbox = mio.local_path(repo, "outbox")
+        if os.path.isdir(outbox) and any(n.endswith(".jsonl") for n in os.listdir(outbox)):
+            findings.append(Finding("V9", os.path.join(mio.LOCAL_REL, "outbox"), None, "an export is pending",
+                                    "state.py memory export --pending, commit, push again"))
+    stats = {"packages": len(packages), "tasks": len(journals), "ms": int((time.time() - started) * 1000)}
+    return findings, stats

package/skills/ai-task/rr_state/cli.py

@@ -34,6 +34,7 @@ def memory_parsers(sub):
     m = msub.add_parser("status"); m.add_argument("--json", action="store_true")
     m = msub.add_parser("enable"); m.add_argument("--author"); m.add_argument("--period", choices=["month", "quarter", "year"])
     m.add_argument("--index", choices=["none", "sqlite"])
+    m.add_argument("--share", choices=["git", "local"])
     msub.add_parser("disable")
     m = msub.add_parser("export"); m.add_argument("ids", nargs="*"); m.add_argument("--pending", action="store_true")
     m = msub.add_parser("verify"); m.add_argument("ids", nargs="*"); m.add_argument("--all", action="store_true")
@@ -179,7 +180,7 @@ def main():
 
     p = sub.add_parser("decision"); p.add_argument("action", choices=["show", "open", "settle", "fallback"])
     p.add_argument("--id"); p.add_argument("--kind"); p.add_argument("--command", dest="commands", action="append", default=[])
-    p.add_argument("--pick", type=int); p.add_argument("--why", default="")
+    p.add_argument("--spec"); p.add_argument("--pick", type=int); p.add_argument("--why", default="")
     p.add_argument("--json", action="store_true"); p.set_defaults(func=dialog_cmd.cmd_decision)
 
     p = sub.add_parser("consent"); p.add_argument("action", nargs="?", choices=["audit"])

package/skills/ai-task/rr_state/close.py

@@ -165,7 +165,7 @@ def memory_after_close(root, task_id):
     if not os.path.exists(os.path.join(root, ".ai", "policies", "memory.json")):
         return
     try:
-        import memory_sync                # pylint: disable=import-outside-toplevel
+        import memory_export              # pylint: disable=import-outside-toplevel
     except ImportError:
         return
-    memory_sync.after_close(root, task_id)
+    memory_export.after_close(root, task_id)

package/skills/ai-task/rr_state/dialog_cmd.py

@@ -1,19 +1,27 @@
 """dialog_cmd: the consent and decision commands -- decision open/show/settle/fallback, the pick applied, and the read-only consent view.
 
-core: SETTLE_EFFECT
-shell: cmd_decision, decision_open, decision_settle, apply_choice, cmd_consent
+core: SETTLE_EFFECT, SETUP_VALUES, SETUP_VALUE_MAX, SETUP_SPEC_MAX, setup_option_why, setup_decision_why, setup_spec_why
+shell: cmd_decision, decision_open, read_setup_spec, setup_command_why, check_setup_labels, setup_open, decision_settle, apply_choice, cmd_consent
 """
 # pylint: disable=unused-argument  # uniform cli dispatch: cmd_consent takes rt like every command
 import argparse
 import json
 import os
+import shlex
 import sys
 
 from rr_state import dialog, fs, labels, profile, questions_cmd, task
 from rr_state import ledger as rr_ledger
 from rr_state import runtime as rr_runtime
 
-SETTLE_EFFECT = {"defer": "defer", "keep": "ack", "ack": "ack", "answer": "answered"}
+SETTLE_EFFECT = {"defer": "defer", "keep": "ack", "ack": "ack", "answer": "answered", "set": "set"}
+# What `decision open --kind setup` accepts (R11): the questions /rr-setup asks, each with the words a choice may set
+# (what the skill applies is what the human read: one of these words, or, for verify only, a command shown verbatim
+# in its own label), the longest value, and the most characters of a spec it reads.
+SETUP_VALUES = {"memory": ("off", "keep"), "runtime": ("auto", "claude", "codex", "both"),
+                "survey": ("light", "full", "keep"), "verify": ("", "other", "keep", "edit")}
+SETUP_VALUE_MAX = 200
+SETUP_SPEC_MAX = 262144
 
 
 def cmd_decision(args, root, rt=rr_runtime.Runtime()):
@@ -53,10 +61,16 @@ def cmd_decision(args, root, rt=rr_runtime.Runtime()):
 
 
 def decision_open(args, root, rt=rr_runtime.Runtime()):
-    """The one opener the model may call: commit and push, nothing else."""
+    """The openers the model may call: --kind commit (git commit and git push) and --kind setup (the /rr-setup
+    questions: choices that set a value, and this project's `memory enable`); nothing else."""
+    if args.kind == "setup":
+        setup_open(args, root, rt=rt)
+        return
     if args.kind != "commit":
-        fs.die("decision open takes --kind commit; every other decision is opened by the command that "
-            "needs it (close, ask, the budgets, start --mode)")
+        fs.die("decision open takes --kind commit or --kind setup; every other decision is opened by the "
+            "command that needs it (close, ask, the budgets, start --mode)")
+    if args.spec is not None:
+        fs.die("decision open --kind commit takes --command, not --spec", 2)
     if not args.commands:
         fs.die("decision open --kind commit needs --command \"git commit …\" [--command \"git push <remote> <branch>\"]")
     for command in args.commands:
@@ -83,6 +97,165 @@ def decision_open(args, root, rt=rr_runtime.Runtime()):
     dialog.print_dialog([decision], rt=rt)
 
 
+def read_setup_spec(path):
+    """--spec FILE|- as JSON: a spec that cannot be read, is longer than SETUP_SPEC_MAX characters, is not JSON or
+    nests deeper than the dialog's own cap is a bad spec (exit 2)."""
+    try:
+        if path == "-":
+            text = sys.stdin.read(SETUP_SPEC_MAX + 1)
+        else:
+            with open(path, encoding="utf-8") as fh:
+                text = fh.read(SETUP_SPEC_MAX + 1)
+        if len(text) > SETUP_SPEC_MAX:
+            fs.die("bad spec — more than %d characters" % SETUP_SPEC_MAX, 2)
+        spec = dialog.json_loads_capped(text)
+        # A lone surrogate ("\ud800") parses, yet no file can hold it: refused here, not after a first decision is written.
+        json.dumps(spec, ensure_ascii=False).encode("utf-8")
+        return spec
+    except (OSError, ValueError, RecursionError) as exc:
+        fs.die("bad spec — %s" % exc, 2)
+
+
+def setup_option_why(option, key):
+    """Why one option of the decision `key` is not {kind: choice, label, value[, description]} or {kind: command,
+    label[, description]}, else None. A choice sets one of its key's words (SETUP_VALUES); a verify choice may also
+    set a command, and check_setup_labels (exit 6) makes its label show it, like every rule of the labels."""
+    if not isinstance(option, dict) or option.get("kind") not in ("choice", "command"):
+        return "an option is an object whose kind is choice or command"
+    need = {"kind", "label", "value"} if option["kind"] == "choice" else {"kind", "label"}
+    if not need <= set(option) <= need | {"description"}:
+        return "a %s option holds %s, and a description if it has one" % (option["kind"], ", ".join(sorted(need)))
+    text, value = option.get("description", ""), option.get("value", "")
+    if not isinstance(option["label"], str) or not isinstance(text, str) or len(text) > dialog.QUESTION_MAX:
+        return "a label and a description are text, a description at most %d characters" % dialog.QUESTION_MAX
+    if not isinstance(value, str) or len(value) > SETUP_VALUE_MAX or not value.isprintable():
+        return "a choice value is at most %d printable characters (empty is allowed)" % SETUP_VALUE_MAX
+    if option["kind"] == "choice" and key != "verify" and value not in SETUP_VALUES[key]:
+        return "a %s choice sets one of: %s" % (key, ", ".join(SETUP_VALUES[key]))
+    return None
+
+
+def setup_decision_why(item):
+    """Why one decision of a spec is not {key, header, question, options}, else None."""
+    if not isinstance(item, dict) or set(item) != {"key", "header", "question", "options"}:
+        return "a decision is an object holding exactly key, header, question and options"
+    if not isinstance(item["key"], str) or item["key"] not in SETUP_VALUES:
+        return "a decision key is one of %s" % ", ".join(SETUP_VALUES)
+    if not all(isinstance(item[name], str) and item[name].strip() for name in ("header", "question")):
+        return "a header and a question are text and not empty"
+    if not isinstance(item["options"], list) or not 2 <= len(item["options"]) <= 4:
+        return "a decision has 2 to 4 options"
+    for number, option in enumerate(item["options"], 1):
+        why = setup_option_why(option, item["key"])
+        if why:
+            return "option %d: %s" % (number, why)
+    return None
+
+
+def setup_spec_why(spec):
+    """Why a parsed spec is not {"schema": 1, "decisions": [...]} with 1 to DECISIONS_MAX decisions, each key
+    once, else None (R11)."""
+    if not isinstance(spec, dict) or set(spec) != {"schema", "decisions"}:
+        return "a spec is an object holding exactly schema and decisions"
+    schema, decisions = spec["schema"], spec["decisions"]
+    if not isinstance(schema, int) or isinstance(schema, bool) or schema != 1:
+        return "schema is 1"
+    if not isinstance(decisions, list) or not 1 <= len(decisions) <= dialog.DECISIONS_MAX:
+        return "decisions is a list of 1 to %d decisions" % dialog.DECISIONS_MAX
+    for number, item in enumerate(decisions, 1):
+        why = setup_decision_why(item)
+        if why:
+            return "decision %d: %s" % (number, why)
+    keys = [item["key"] for item in decisions]
+    return None if len(set(keys)) == len(keys) else "a decision key is used once"
+
+
+def setup_command_why(root, label):
+    """Why `label` is not exactly `python3 <this state.py> --root <this project> memory enable [options]`, else
+    None. validate_label alone also passes another --root, a --runtime, interpreter flags, approve and git commit
+    (R11, B1); the paths must be absolute, as the labels state_label writes."""
+    why = labels.validate_label(label)
+    if why:
+        return why
+    words = shlex.split(label)
+    if len(words) >= 6 and words[0] == "python3" and words[2] == "--root" and words[4:6] == ["memory", "enable"] \
+            and os.path.isabs(words[1]) and os.path.realpath(words[1]) == os.path.realpath(fs.ENTRY) \
+            and os.path.isabs(words[3]) and os.path.realpath(words[3]) == os.path.realpath(root):
+        return None
+    return ("a setup command is exactly python3 <this state.py> --root <this project> memory enable "
+            "[--author S] [--period P] [--index none|sqlite]")
+
+
+def check_setup_labels(root, decisions):
+    """Every label of the spec, before anything is written (exit 6): only the memory decision offers a command, and
+    that is setup_command_why's; a choice never reads as a command, because the gate passes a Bash command equal
+    to any pick and dialog_pick runs a pick that is a state.py label; and a verify choice that sets a command
+    shows it, whole, as one `span` of its label, because the skill applies the value and the human reads the
+    label (R11, B1)."""
+    for item in decisions:
+        options = item["options"]
+        if len({option["label"] for option in options}) != len(options):
+            fs.die("CONSENT_LABEL_INVALID — two options of the %s decision carry the same label" % item["key"], 6)
+        for option in options:
+            label = option["label"]
+            if option["kind"] == "command":
+                why = setup_command_why(root, label) if item["key"] == "memory" else \
+                    "only the memory decision offers a command"
+            elif not 0 < len(label) <= labels.LABEL_MAX or not label.isprintable():
+                why = "a choice label is 1 to %d printable characters" % labels.LABEL_MAX
+            elif label.startswith(("python3", "git", "npx")) or labels.label_argv(label) \
+                    or labels.validate_label(label) is None:
+                why = "a choice label never reads as a command"
+            elif item["key"] == "verify" and option["value"] not in SETUP_VALUES["verify"] \
+                    and option["value"] not in label.split("`")[1:-1:2]:
+                why = "a verify command is shown verbatim in its label, inside backticks"
+            else:
+                why = None
+            if why:
+                fs.die("CONSENT_LABEL_INVALID — %s: %s" % (why, label[:120]), 6)
+
+
+def setup_open(args, root, rt=rr_runtime.Runtime()):
+    """decision open --kind setup --spec FILE|-: every check runs for every decision of the spec before the first
+    write, then all are opened in the spec's order, or none (R11). The caller sends the one dialog."""
+    if args.commands or args.spec is None:
+        fs.die("decision open --kind setup takes --spec FILE|- and no --command", 2)
+    spec = read_setup_spec(args.spec)
+    why = setup_spec_why(spec)
+    if why:
+        fs.die("bad spec — %s" % why, 2)
+    decisions = spec["decisions"]
+    check_setup_labels(root, decisions)
+    if not dialog.dialog_on(root, runtime=rt.name):
+        fs.die("the dialog is off here (.ai/policies/dialog.json, the runtime's dialog tool, a session id): "
+            "suggest the commands; the human runs them outside the agent")
+    data = rr_ledger.read_decisions(root)
+    questions = [item["question"].strip()[:dialog.QUESTION_MAX] for item in decisions]   # as open_decision stores them
+    if len(set(questions)) != len(questions):
+        fs.die("DECISION_DUPLICATE — two decisions of the spec carry one question text", 6)
+    twin = next((d for d in data["open"] if d.get("question") in questions), None)
+    if twin:
+        fs.die("DECISION_DUPLICATE — %s is open with this very question; settle it, or 'state.py decision fallback "
+            "--id %s --why …', before opening it again" % (twin.get("id"), twin.get("id")), 6)
+    open_questions = sum(len(dialog.dialog_questions(d)) for d in data["open"])
+    if open_questions + len(decisions) > dialog.DECISIONS_MAX:
+        fs.die("DECISION_LIMIT — %d questions are open and the spec adds %d; one dialog call carries %d"
+            % (open_questions, len(decisions), dialog.DECISIONS_MAX), 6)
+    state = task.load(root, required=False, claim=False, rt=rt)
+    state = state if state and task.is_v7(state) else None
+    opened = []
+    for item in decisions:
+        options = [dict(o, effect="set") if o["kind"] == "choice" else o for o in item["options"]]
+        decision, why = dialog.open_decision(root, state, "setup", item["header"], item["question"], options,
+                                      "decision open --kind setup", rt=rt, setup_key=item["key"])
+        if decision is None:
+            for done in opened:               # a race since the checks above: none of this call stays open
+                dialog.settle_decision(root, done["id"], "withdrawn")
+            fs.die(why, 6)
+        opened.append(decision)
+    dialog.print_dialog(opened, rt=rt)
+
+
 def decision_settle(args, root, decision, rt=rr_runtime.Runtime()):
     """(b) apply what the recorder wrote — a choice pick or a decline; (c) a
     human in a terminal picks an option by number (R36.14)."""
@@ -112,6 +285,8 @@ def decision_settle(args, root, decision, rt=rr_runtime.Runtime()):
         dialog.settle_decision(root, decision["id"], "declined")
         print("%s settled: declined in the dialog (%s); nothing runs"
               % (decision["id"], mine[-1].get("why") or "no answer"))
+        if decision.get("kind") == "setup":
+            print("SETUP_PICK %s=" % decision.get("setup_key"))
         return
     live = [p for p in rr_ledger.live_picks(ledger, (dialog.dialog_on(root, runtime=rt.name) or {}).get("session"))
             if p.get("decision") == decision["id"]]
@@ -132,6 +307,8 @@ def apply_choice(root, decision, option, pick_id, by, via, rt=rr_runtime.Runtime
                    root, rt=rt)
     dialog.settle_decision(root, decision["id"], effect, pick_id)
     print("%s settled: %s (%s)" % (decision["id"], option["label"], effect))
+    if decision.get("kind") == "setup":
+        print("SETUP_PICK %s=%s" % (decision.get("setup_key"), option.get("value", "")))
 
 
 def cmd_consent(args, root, rt=rr_runtime.Runtime()):

package/skills/ai-task/rr_state/labels.py

@@ -43,12 +43,23 @@ def subcommand(argv):
 
 
 def state_label_ok(argv):
-    """approve | reject | profile set | verify --by | review --by | start --mode … --by."""
+    """approve | reject | profile set | verify --by | review --by | start --mode … --by |
+    memory enable [--author S] [--period month|quarter|year] [--index none|sqlite]: each option at most
+    once, as two words, in any order, and no other memory verb. hooks/guard/dialog.py keeps the same
+    rule; tests/test_dialog_contract.py pins the two equal."""
     rest = subcommand(argv)
     if rest[:1] in (["approve"], ["reject"]) or rest[:2] == ["profile", "set"]:
         return True
     if rest[:1] in (["verify"], ["review"]):
         return "--by" in rest
+    if rest[:2] == ["memory", "enable"]:
+        # The pick is the exact command the human read: no `--opt=value`, no abbreviation argparse would
+        # take, no positional, an option once, a value of its own kind (an author never starts with '-').
+        names, values = rest[2::2], rest[3::2]
+        kinds = {"--author": None, "--period": ("month", "quarter", "year"), "--index": ("none", "sqlite")}
+        return (len(names) == len(values) == len(set(names)) and set(names) <= set(kinds)
+                and all((v[:1] not in ("", "-")) if kinds[n] is None else v in kinds[n]
+                        for n, v in zip(names, values)))
     return rest[:1] == ["start"] and "--mode" in rest and "--by" in rest
 
 
@@ -78,7 +89,8 @@ def validate_label(label):
             and state_label_ok(script[1]):
         return None
     return ("a label starts with git commit, git push <remote> <branch>, state.py approve|reject|"
-            "profile set|verify --by|review --by|start --mode --by, or npx riskrails@<v> … --yes")
+            "profile set|verify --by|review --by|start --mode --by|memory enable [--author S] "
+            "[--period P] [--index none|sqlite], or npx riskrails@<v> … --yes")
 
 
 def human_name(root):