riskrails 3.1.0 → 3.2.1

package/skills/project-update/adopt.py

@@ -32,6 +32,12 @@ def test_mode():
     return os.environ.get("RISKRAILS_TEST", os.environ.get("CLAUDE_AGENTIC_TEST")) == "1"
 
 
+def ai_unattended():
+    """AI_UNATTENDED is set when it is non-empty and not 0, false or no (case
+    and blanks ignored): one rule in every reader (risk 0587)."""
+    return os.environ.get("AI_UNATTENDED", "").strip().lower() not in ("", "0", "false", "no")
+
+
 def human_gate():
     """(passed, via, why) for --confirm-delete. A terminal outside any agent
     session is a human: via "terminal". Otherwise a launcher that declared the
@@ -44,7 +50,7 @@ def human_gate():
     markers = [name for name in AGENT_MARKERS if name in os.environ]
     if os.isatty(0) and not markers:
         return True, "terminal", ""
-    if os.environ.get("AI_UNATTENDED"):
+    if ai_unattended():
         return True, "unattended", ""
     if markers:
         return False, None, ("this run is inside an agent session (%s %s set); run it in a terminal "
@@ -175,7 +181,7 @@ def load_table(path=MAP_FILE):
     try:
         with open(path, encoding="utf-8") as fh:
             table = json.load(fh)
-    except (OSError, ValueError) as exc:
+    except (OSError, ValueError, RecursionError) as exc:
         raise TableError("%s: %s" % (path, exc)) from exc
     tools = table.get("tools")
     rows = table.get("rows")
@@ -455,7 +461,7 @@ def load_decisions(root):
     try:
         with open(os.path.join(root, where, "decisions.json"), encoding="utf-8") as fh:
             return json.load(fh)
-    except (OSError, ValueError) as exc:
+    except (OSError, ValueError, RecursionError) as exc:
         raise TableError("%s/decisions.json: %s" % (where, exc)) from exc
 
 
@@ -925,7 +931,7 @@ def state_line(root, shipped_block, skeleton_cap, table=None, instruction_files=
     try:
         return _state_line(root, shipped_block, skeleton_cap, table, instruction_files, shipped_files)
     except (TableError, OSError, ValueError, KeyError, TypeError, AttributeError) as exc:
-        return 1, "adopt state unreadable (%s) — run /project-update --adopt" % exc
+        return 1, "adopt state unreadable (%s) — run /rr-setup --adopt" % exc
 
 
 def _state_line(root, shipped_block, skeleton_cap, table, instruction_files, shipped_files):
@@ -943,11 +949,11 @@ def _state_line(root, shipped_block, skeleton_cap, table, instruction_files, shi
             return 0, "no foreign structure detected"
         bits = ["%s (%d file(s))" % (t, sum(g.values())) for t, g in adoption.detected.items()]
         bits += ["%s (split?)" % c.path for c, _ in adoption.candidates]
-        return 1, "foreign structure detected: %s — run /project-update --adopt" % ", ".join(bits)
+        return 1, "foreign structure detected: %s — run /rr-setup --adopt" % ", ".join(bits)
     try:
         with open(os.path.join(root, where, "adopt.json"), encoding="utf-8") as fh:
             record_data = json.load(fh)
-    except (OSError, ValueError):
+    except (OSError, ValueError, RecursionError):
         return 0, "no foreign structure detected"
     date = where.rsplit("adopt-", 1)[-1]
     regenerated = []
@@ -968,13 +974,13 @@ def _state_line(root, shipped_block, skeleton_cap, table, instruction_files, shi
         if current != src.get("sha"):
             regenerated.append(src["path"])
     if regenerated:
-        return 1, ("foreign files regenerated since the adopt of %s: %s — run /project-update --adopt"
+        return 1, ("foreign files regenerated since the adopt of %s: %s — run /rr-setup --adopt"
                    % (date, ", ".join(sorted(regenerated))))
     checks = record_data.get("checks", {})
     failed = [name for name, c in checks.items() if c.get("status") not in ("pass", "not_applicable")]
     if failed or record_data.get("status") == "partial":
         what = failed[0].replace("_", "-") + " FAIL" if failed else "the apply was interrupted"
-        return 1, "adoption of %s incomplete: %s — run /project-update --adopt" % (date, what)
+        return 1, "adoption of %s incomplete: %s — run /rr-setup --adopt" % (date, what)
     tools = ", ".join(sorted(record_data.get("tools", {})))
     pending = sum(1 for s in record_data.get("sources", []) if s.get("cleanup") and safe_rel(s.get("path"))
                   and os.path.isfile(os.path.join(root, s["path"])))
@@ -1306,7 +1312,7 @@ def read_record(root, where):
     try:
         with open(os.path.join(root, where, "adopt.json"), encoding="utf-8") as fh:
             return json.load(fh)
-    except (OSError, ValueError):
+    except (OSError, ValueError, RecursionError):
         return None
 
 
@@ -1331,7 +1337,7 @@ def task_in_flight(root):
     try:
         with open(path, encoding="utf-8") as fh:
             state = json.load(fh)
-    except (OSError, ValueError):
+    except (OSError, ValueError, RecursionError):
         return None
     stage = state.get("current_stage")
     return None if stage in (None, "done") else "%s at stage %s" % (state.get("task_id", "a task"), stage)
@@ -1340,13 +1346,13 @@ def task_in_flight(root):
 def gates(root, u, planned_writes):
     """R5, in the order a human fixes them. Returns a refusal (reason, how) or None."""
     if not os.path.isdir(os.path.join(root, ".ai")):
-        return "the project has no .ai/", "run /ai-init first, then /project-update --adopt"
+        return "the project has no .ai/", "run /rr-setup first, then /rr-setup --adopt"
     dirty = clean_tree(root)
     if dirty is None:
         return "the project is not a git work tree", "run `git init` and commit, so the adopt can be undone"
     running = task_in_flight(root)
     if running:
-        return "a task is in flight (%s)" % running, "finish or abandon it with /ai-task first"
+        return "a task is in flight (%s)" % running, "finish or abandon it with /rr-build first"
     outside = [p for p in dirty if not p.startswith(ALLOWED_DIRT) and p not in planned_writes]
     if outside:
         more = " and %d more" % (len(outside) - 3) if len(outside) > 3 else ""
@@ -1356,7 +1362,7 @@ def gates(root, u, planned_writes):
                     "commit it or remove it")
         return ("the tree has uncommitted changes: %s%s" % (", ".join(outside[:3]), more), how)
     if u.plain_pending(root, ignore=planned_writes):
-        return "the project is behind the installed plugin", "run /project-update --apply first, then adopt"
+        return "the project is behind the installed plugin", "run /rr-setup --update --apply first, then adopt"
     return None
 
 
@@ -1403,7 +1409,8 @@ def write_json(u, root, rel, data):
 
 def apply_run(plan, args, u, skeleton_cap, instruction_files=frozenset(), shipped_files=None):
     """`update.py --adopt --apply`: gates, originals, phased writes, the checks
-    on disk, the record. Exit 0, 3 (aborted), 4 (incomplete) or 5 (refused)."""
+    on disk, the record. Exit 0, 2 (the routing table or a migration could not be
+    read), 3 (aborted), 4 (incomplete) or 5 (refused)."""
     root = plan.root
     try:
         table = load_table()
@@ -1413,7 +1420,11 @@ def apply_run(plan, args, u, skeleton_cap, instruction_files=frozenset(), shippe
     tools = [t.strip() for t in args.tool.split(",")] if args.tool else None
     resume_dir, resume = partial_record(root)
     planned_writes = set(resume.get("planned_writes", [])) if resume else set()
-    refusal = gates(root, u, planned_writes)
+    try:
+        refusal = gates(root, u, planned_writes)
+    except u.SchemaError as exc:  # plain_pending builds the plan: a migration's error is exit 2, as in update.py
+        print("project-update: %s" % exc, file=sys.stderr)
+        return 2
     if refusal:
         return refuse(*refusal)
     plan.report_dir = plan.adopt_report_dir = resume_dir or ".ai/reports/adopt-%s" % today()
@@ -1577,7 +1588,9 @@ def report_md(plan, adoption, record):
 # ---------------------------------------------------------------------------
 
 CLEANUP_HEADING = "## Cleanup"
-REVIEW_LINE = "Run `/project-update --adopt --cleanup` to review; a human confirms the deletion."
+REVIEW_LINE = "Run `/rr-setup --adopt --cleanup` to review; a human confirms the deletion."
+# Reports written by v2.0.2-v3.1.0 carry this text; cleanup still replaces it.
+LEGACY_REVIEW_LINE = "Run `/project-update --adopt --cleanup` to review; a human confirms the deletion."
 
 
 def plan_cleanup(plan, args, u, table, skeleton_cap, instruction_files, shipped_files):
@@ -1589,21 +1602,21 @@ def plan_cleanup(plan, args, u, table, skeleton_cap, instruction_files, shipped_
     def no(reason, how, adoption=None):
         return (reason, how), None, None, None, adoption
     if not os.path.isdir(os.path.join(root, ".ai")):
-        return no("the project has no .ai/", "run /ai-init first")
+        return no("the project has no .ai/", "run /rr-setup first")
     where = latest_with(root, "adopt.json")
     record = read_record(root, where) if where else None
     if record is None:
-        return no("no adopt record to clean up", "run /project-update --adopt --apply first")
+        return no("no adopt record to clean up", "run /rr-setup --adopt --apply first")
     if args.mode == "coexist" or record.get("mode") == "coexist":
         return no("coexist keeps the foreign files",
-                  "to move them, run /project-update --adopt --apply (mode migrate), then --cleanup")
+                  "to move them, run /rr-setup --adopt --apply (mode migrate), then --cleanup")
     checks = record.get("checks", {})
     if record.get("status") != "applied" or any(c.get("status") != "pass" for c in checks.values()):
         return no("the adopt of %s is not complete (R12)" % where.rsplit("adopt-", 1)[-1],
-                  "run /project-update --adopt --apply until both checks pass")
+                  "run /rr-setup --adopt --apply until both checks pass")
     running = task_in_flight(root)
     if running:
-        return no("a task is in flight (%s)" % running, "finish or abandon it with /ai-task first")
+        return no("a task is in flight (%s)" % running, "finish or abandon it with /rr-build first")
     dirty = clean_tree(root)
     if dirty is None:
         return no("the project is not a git work tree", "cleanup deletes only what git can restore")
@@ -1642,7 +1655,7 @@ def plan_cleanup(plan, args, u, table, skeleton_cap, instruction_files, shipped_
         what.append("%d unmapped, %d split(s) waiting" % (len(adoption.unmapped), len(adoption.split)))
     if what:
         return no("the adopt no longer holds on the current tree: %s" % "; ".join(what),
-                  "run /project-update --adopt to see why, settle it, then --cleanup", adoption)
+                  "run /rr-setup --adopt to see why, settle it, then --cleanup", adoption)
     # Only what the adopt finds again as a cleanup source, and only what git
     # can restore: an ignored file skipped from original/ would be gone for good.
     found = {path for path, _t, _tr, _n, cleanup in adoption.sources if cleanup}
@@ -1773,7 +1786,8 @@ def cleanup_report_md(u, root, where, record):
     except OSError:
         text = ""
     text = text.split("\n" + CLEANUP_HEADING + "\n", 1)[0].rstrip("\n") + "\n"
-    text = text.replace(REVIEW_LINE, "The deletion is recorded under Cleanup below.")
+    for line in (REVIEW_LINE, LEGACY_REVIEW_LINE):
+        text = text.replace(line, "The deletion is recorded under Cleanup below.")
     c = record["cleanup"]
     runs = list(c.get("history") or []) + [c]
 
@@ -1900,7 +1914,7 @@ def find_proposal(root, cand, stale=False):
             try:
                 with open(os.path.join(base, d, name), encoding="utf-8") as fh:
                     data = json.load(fh)
-            except (OSError, ValueError):
+            except (OSError, ValueError, RecursionError):
                 continue
             if isinstance(data, dict) and data.get("source") == cand.path and (stale or data.get("source_sha") == cand.sha):
                 return ".ai/reports/%s/%s" % (d, name), data

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

@@ -0,0 +1,67 @@
+# Task state
+
+`state.json` is the machine-readable record of the task in flight. It is
+written by `skills/ai-task/state.py` (atomically), read by `/rr-status`, and
+enforced by `ai-scope-guard`, which derives the files the current step may touch
+from it.
+
+Two other writers exist, and only these two. A schema migration in
+`/rr-setup --update` may change the state through `ctx.patch_state()`, with the
+same atomic write and a `schema_migrated` history entry — that is how a task in
+flight survives a change to the shape of this file. And `hooks/context-guard.py`
+writes `session.json`, the sidecar beside this file, and nothing else: it never
+touches `state.json`. Nothing else writes any of it — an agent never edits
+them by hand, and the path guard refuses when one tries.
+
+It is **not committed**: it describes a session, not the repository. The
+`.gitignore` entry added by `/rr-setup` keeps it out of git.
+
+When a task closes, `state.py close` writes the final state to
+`.ai/state/logs/<task-id>/state.json`, beside the task's verify logs — local,
+**not** committed. What is committed is `.ai/reports/<task-id>/events.jsonl`
+and `task.md`, and in packages mode the task's compact record under
+`.ai/memory/` — that is the audit trail: which stages ran, in what order, who
+approved what, and when (the plugin's `docs/local-memory.md`).
+
+It holds facts, never transcripts:
+
+```
+task_id, goal, workflow, risk_tier, current_stage, affected_modules,
+context_summary_ref, approved_plan { ref, current_step_id, steps[] },
+completed_steps, test_status, e2e_status, review_status, security_status, open_risks,
+next_action, owner_runtime, resume_point { stage, step_id, next_action, at, runtime },
+questions { file, pending[] }, handoff { file, written_at, reason },
+human_approval { required, granted, granted_by, granted_at,
+                 requested_at, gate_id, requested_session, rejected_at, via, unattended },
+created_at, updated_at, history[]
+```
+
+`state.py` applies the schema-2 keys in memory as it loads, so a project that has
+not run `/rr-setup --update` yet still answers every command; `save()` then writes
+them. A reader that opens this file directly sees what is on disk, not those
+defaults.
+
+## The other files beside it
+
+| File | Written by | Committed |
+|---|---|---|
+| `state.json` (legacy `current.json`, still read) | `state.py`, and `update.py` during a migration | no |
+| `session.json` | `context-guard.py`, on SessionStart and each prompt | no |
+| `handoff.md` | `state.py handoff` — never a model | no |
+| `../reports/<task-id>/task.md` §Questions | `state.py ask/answer/questions` | yes |
+| `../reports/<task-id>/events.jsonl` | `state.py` (`emit`), append-only | yes |
+
+`handoff.md` is the ≤ 30-line frame a session that lost its context reads first:
+the goal, the next action and its resume point, the pending questions, the latest
+decisions, rejected options and failed attempts, and the user's last instruction
+verbatim. It is rendered from the four sources above, so deleting it loses
+nothing — the next stage-moving command writes it again.
+
+`events.jsonl` is the journal: one line per state change, `history[]`'s facts
+with types beside them. It is best effort by contract — a line that cannot be
+written never fails the command that emitted it — so nothing depends on it being
+complete, and readers skip a line they cannot parse.
+
+If this file is corrupt, `state.py` refuses to read it rather than replacing it.
+Inspect it by hand: the scope guard's boundaries come from here, and a silently
+regenerated state file means an unbounded implementer.

package/skills/project-update/history/index.json

@@ -244,7 +244,8 @@
   "ad4c4f81855725f7fe6e0e3d8f557df0de5fc063465d428546f69c54020c69d9",
   "19b1a6390e96136619d23bc2ef9afed8f15e62107de7c1052bc5ea23e5bb5692",
   "23a42febbacaa7b52a802d428033a99c0694391c81d51fe3b6e1dff608a641d5",
-  "7ee99edafe7cec45ff577376c0d0178fdb2690134d4656488f46e129aba3cc5a"
+  "7ee99edafe7cec45ff577376c0d0178fdb2690134d4656488f46e129aba3cc5a",
+  "a51517e13e57420d2d88a6bcfb4055d762d4a0d10a8f88450929c5c4572213a9"
  ],
  "ai-init/.ai/templates/architecture-decision.md": [
   "78619b522826ba8f5f0422e9deb7359c8002553d1aeb29a3719da5ab11ff13a1"

package/skills/project-update/migrations/0003_context_diet.py

@@ -61,5 +61,5 @@ def plan(ctx):
                      "the managed block below it now says the same thing" % path)
         if ctx.block_status(path) == "edited":
             ctx.hint("%s: the managed block was edited here, so the plugin's stub cannot "
-                     "replace it — move your lines below the block and run /project-update "
+                     "replace it — move your lines below the block and run /rr-setup --update "
                      "again" % path)

package/skills/project-update/migrations/0007_weight_model.py

@@ -54,7 +54,7 @@ TEST_KEYS = ("timeout_seconds", "env_retries", "log_max_bytes")
 def _loads(raw):
     try:
         doc = json.loads(raw, object_pairs_hook=OrderedDict)
-    except (TypeError, ValueError):
+    except (TypeError, ValueError, RecursionError):  # nested past the parser's limit: edit_json holds the schema
         return None
     return doc if isinstance(doc, dict) else None
 
@@ -111,21 +111,17 @@ def _hint(doc, axis, paths, note):
         _add(hint.setdefault("paths", []), paths)
 
 
-def convert(old, base, shipped):
-    """The weight table `base` plus what the old table `old` added on top of the
-    `shipped` (examples, scopes, scalars, weight template) it was installed
-    with. A scalar is carried only when the old table changed it and `base`
-    still holds the shipped weight value — a project's own weight.json edit
-    wins. `base` is not changed, and converting twice adds nothing new."""
+def _writes(old, base, shipped):
+    """What converting `old` into `base` writes, in order: ("list", path, values) appends to a list,
+    ("set", path, value) sets a scalar, ("hint", axis, (paths, note)) adds to a hint."""
     shipped_examples, shipped_scopes, shipped_scalars, template = shipped
-    new = json.loads(json.dumps(base), object_pairs_hook=OrderedDict)
-    axes = new.setdefault("axes", OrderedDict())
+    out = []
     for tier, entry in (old.get("tiers") or {}).items():
         if tier in EXAMPLE_MODE and isinstance(entry, dict):
             extra = [e for e in entry.get("examples") or []
                      if isinstance(e, str) and e not in shipped_examples.get(tier, set())]
             if extra:
-                _add(new.setdefault("examples", OrderedDict()).setdefault(EXAMPLE_MODE[tier], []), extra)
+                out.append(("list", ("examples", EXAMPLE_MODE[tier]), extra))
     for scope in old.get("path_scopes") or []:
         if not isinstance(scope, dict):
             continue
@@ -136,23 +132,41 @@ def convert(old, base, shipped):
             continue
         if name in DOMAIN or (name not in HINTS and name not in INFRA | NEEDS_STEP
                               and scope.get("min_tier") in ("T5", "T6")):
-            _add(axes.setdefault("domain", OrderedDict()).setdefault("modules", []), paths)
+            out.append(("list", ("axes", "domain", "modules"), paths))
         elif name in HINTS:
-            _hint(new, HINTS[name], paths, "%s (from risk-tiers.json)" % name)
+            out.append(("hint", HINTS[name], (paths, "%s (from risk-tiers.json)" % name)))
         elif name in INFRA | NEEDS_STEP:
-            rev = axes.setdefault("reversibility", OrderedDict())
             two = [p for p in paths if name in INFRA and "prod" in p]
-            _add(rev.setdefault("irreversible", []), two)
-            _add(rev.setdefault("needs_step", []), [p for p in paths if p not in two])
+            out.append(("list", ("axes", "reversibility", "irreversible"), two))
+            out.append(("list", ("axes", "reversibility", "needs_step"), [p for p in paths if p not in two]))
     for key, value in _scalars(old).items():
         if value in shipped_scalars.get(key, []) or _get(base, key) != _get(template, key):
             continue
         if key == "tests.max_suite_runs" and isinstance(value, int):
             value = min(value, 2)
-        if key.startswith("tests."):
-            new.setdefault("tests", OrderedDict())[key[len("tests."):]] = value
+        out.append(("set", tuple(key.split(".")), value))
+    return out
+
+
+def convert(old, base, shipped):
+    """The weight table `base` plus what the old table `old` added on top of the
+    `shipped` (examples, scopes, scalars, weight template) it was installed
+    with. A scalar is carried only when the old table changed it and `base`
+    still holds the shipped weight value — a project's own weight.json edit
+    wins. `base` is not changed, and converting twice adds nothing new."""
+    new = json.loads(json.dumps(base), object_pairs_hook=OrderedDict)
+    new.setdefault("axes", OrderedDict())
+    for kind, path, value in _writes(old, base, shipped):
+        if kind == "hint":
+            _hint(new, path, *value)
+            continue
+        node = new
+        for part in path[:-1]:
+            node = node.setdefault(part, OrderedDict())
+        if kind == "list":
+            _add(node.setdefault(path[-1], []), value)
         else:
-            new[key] = value
+            node[path[-1]] = value
     return new
 
 
@@ -168,19 +182,112 @@ def _mode(state):
     return state
 
 
+def _kind(value):
+    """the JSON name of a value's type"""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):  # before int: True is an int
+        return "boolean"
+    for types, name in (((int, float), "number"), (str, "string"), (list, "list"), (dict, "object")):
+        if isinstance(value, types):
+            return name
+    return type(value).__name__
+
+
+def _an(word):
+    return word if word == "null" else ("an " if word[0] in "aeiou" else "a ") + word
+
+
+def _bad(doc, key, want, what):
+    """A reason when `doc[key]`, present and not null, is not a `want`; else None."""
+    value = doc.get(key)
+    if value is not None and not isinstance(value, want):
+        return "%s is %s, not %s" % (what, _an(_kind(value)), _an("object" if want is dict else "list"))
+    return None
+
+
+def _old_problem(old):
+    """Why the old table cannot be converted (a wrong type where convert reads), or None."""
+    if not isinstance(old, dict):
+        return "risk-tiers.json is %s, not an object" % _an(_kind(old))
+    why = _bad(old, "tiers", dict, "tiers") if old.get("tiers") else None  # falsy: convert reads no tiers
+    for tier, entry in (old.get("tiers") or {}).items() if why is None else ():
+        if tier in EXAMPLE_MODE and isinstance(entry, dict) and entry.get("examples"):  # convert reads only these
+            why = why or _bad(entry, "examples", (list, dict), "tiers.%s.examples" % tier)  # an object iterates by key
+    scopes = old.get("path_scopes")
+    if scopes and not isinstance(scopes, (list, dict, str)):  # an object or a string iterates, its members skipped
+        why = why or "path_scopes is %s, not a list" % _an(_kind(scopes))
+    for scope in scopes if isinstance(scopes, list) and not why else ():
+        if isinstance(scope, dict):
+            name = scope.get("scope")
+            if scope.get("paths"):
+                why = _bad(scope, "paths", (list, dict), "a path scope's paths")  # an object iterates by key
+            # the name is hashed only against a str path
+            if not why and isinstance(name, (list, dict)) and any(isinstance(p, str) for p in scope.get("paths") or []):
+                why = "a path scope's name is %s, not a string" % _an(_kind(name))
+            if why:
+                break
+    return why
+
+
+def _new_problem(doc, writes):
+    """Why the weight table `doc` cannot take the `writes` of convert (a wrong type where convert writes), or None."""
+    if not isinstance(doc, dict):
+        return "weight.json is %s, not an object" % _an(_kind(doc))
+    for kind, path, value in writes:
+        if kind == "hint":
+            if "hints" not in doc:
+                continue
+            if not isinstance(doc["hints"], list):
+                return "hints is %s, not a list" % _an(_kind(doc["hints"]))
+            for i, hint in enumerate(doc["hints"]):
+                if isinstance(hint, dict) and hint.get("axis") == path:
+                    if "paths" in hint and not isinstance(hint["paths"], list):
+                        return "hints[%d].paths is %s, not a list" % (i, _an(_kind(hint["paths"])))
+                    break
+            continue
+        node = doc
+        for i, part in enumerate(path):
+            if part not in node:
+                break
+            node = node[part]
+            what = ".".join(path[:i + 1])
+            if i < len(path) - 1:
+                if not isinstance(node, dict):
+                    return "%s is %s, not an object" % (what, _an(_kind(node)))
+            elif kind == "list" and value and not isinstance(node, list):
+                return "%s is %s, not a list" % (what, _an(_kind(node)))
+    return None
+
+
 def plan(ctx):
     old = ctx.read_json(OLD)
+    why = _old_problem(old) if old is not None else None
+    if why:
+        ctx.conflict(OLD, "%s, so this migration could not run" % why)
+        old = None
     shipped = _shipped(ctx)
     before = ctx.read(NEW)
     if before is None:
         template = ctx.template(NEW)
         doc = convert(old, _loads(template), shipped) if old is not None else None
-        if doc is None or doc == _loads(template):
-            ctx.create(NEW, template)
-        else:
-            ctx.create(NEW, (json.dumps(doc, indent=2, ensure_ascii=False) + "\n").encode())
+        try:
+            body = None if doc is None or doc == _loads(template) else \
+                (json.dumps(doc, indent=2, ensure_ascii=False) + "\n").encode()
+        except RecursionError:  # a deep value carried from the old table: the default beside it holds the schema
+            ctx.conflict(OLD, "nested too deeply, so this migration could not run")
+            body = None
+        ctx.create(NEW, template if body is None else body)
     elif old is not None:
-        ctx.edit_json(NEW, lambda new: convert(old, new, shipped))
+        try:
+            current = json.loads(before)
+        except (ValueError, RecursionError):  # invalid or too deep: edit_json holds the schema
+            current = {}
+        why = _new_problem(current, _writes(old, current, shipped))
+        if why:
+            ctx.conflict(NEW, "%s, so this migration could not run" % why)
+        else:
+            ctx.edit_json(NEW, lambda new: convert(old, new, shipped))
     after = ctx.read(NEW)
     if old is not None and _loads(after) != _loads(before or ctx.template(NEW)):
         ctx.hint("%s now carries this project's risk-tier edits: run `state.py weight --mirror` to "

package/skills/project-update/migrations/README.md

@@ -21,7 +21,17 @@ this directory, named `NNNN_slug.py`, numbered contiguously from `0001`, with
   moves a path a task's step may touch must patch it, or the scope guard will
   stop that task on a file that no longer exists.
 - Operations are planned, never written: the dry run must list everything.
-  Paths are project-relative and normalised, and content is `bytes`.
+  Paths are project-relative and normalised, and content is `bytes`; the
+  `note` of `ctx.conflict` / `ctx.edit_text` and the `reason` of `ctx.delete` are
+  `str`. The type is checked when the operation is planned: any other type stops
+  the update with a SchemaError (exit 2). A call that changes nothing (an
+  `edit_text` whose `fn` returns its input, a `delete` of a path that is not
+  there) plans nothing and is not checked.
+- `ctx.edit_json(path, fn)` hands `fn` a deep copy of the document and takes the
+  new one back. `fn` must not recurse in Python over the document (a file that
+  passed the deep copy can still be ~470-490 levels deep), or it guards
+  `RecursionError` itself; an unguarded `fn`'s `RecursionError` fails the run as
+  the migration's own bug, naming no file.
 - `plan(ctx)` runs again on every run until the schema version advances, and a
   conflict or an unconfirmed deletion holds it back. Every `fn` must therefore be
   idempotent: append a line only when it is not already there, or the next run
@@ -45,6 +55,11 @@ own text instead of matching a pattern against the human's prose:
   else.
 - `ctx.hint(text)` — say something to the human that is not an operation on a
   file. The right answer whenever the text is no longer the plugin's.
+- `ctx.conflict(path, note)` — a file the migration cannot handle (wrong JSON
+  types, say) is a conflict: it holds the schema version, so the next run tries
+  again. `note` says why, and must be `str`: any other type stops the update
+  with a SchemaError (`%04d: <path> note must be str, not <type>`, exit 2), as
+  content that is not `bytes` does.
 - `ctx.template(path)` — the bytes the plugin ships today at that path, from the
   scaffold or the shared tree. `ctx.is_shipped(path, data)` — whether these bytes
   are a version ever shipped there (CRLF counts; `index.json` alone answers).