riskrails 3.2.1 → 4.0.1

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

@@ -1,295 +0,0 @@
-"""0007: the weight table carries the risk-tier table's edits; a task in flight gets a mode.
-
-The six-axis weight model in .ai/policies/weight.json is what the schema-7
-surface of state.py reads. This migration gives every project one — the shipped
-table, created when the project has none — and converts into it every value the
-project added on top of the risk-tier tables it was installed with:
-
-  tiers.T0-T2.examples -> examples.light, T3-T4 -> guarded, T5-T6 -> full
-  path_scopes money/identity/customer data -> axes.domain.modules
-  path_scopes auth/security -> the domain hint; pipeline -> the behaviour hint;
-              dependencies -> the novelty hint
-  path_scopes infra/k8s/deploy/production -> reversibility.irreversible when the
-              glob names prod, else reversibility.needs_step
-  path_scopes migrations/schema/config -> reversibility.needs_step
-  a scope this table does not know, with min_tier T5 or T6 -> axes.domain.modules
-  sensors.tests.* -> tests.* with max_suite_runs = min(old, 2), and
-  review_rounds_max, remediation_rounds -> carried — each only when the project
-              changed it and weight.json still holds the shipped value
-
-Everything else (diff_budget, sensors, pipeline profiles, model tiers, the
-escalation and downgrade rules) has no place in the weight table; its prose lives
-in docs/weight.md.
-
-risk-tiers.json and its mirror stay where they are, untouched: the old surface
-reads them until it is removed, and the plugin still ships them, so moving or
-deleting them here would only have the next run put them back (a template is
-never shipped at a path a migration moved away). Their retirement belongs with
-the template's.
-
-A task in flight keeps running on the old surface: it gets a `mode` from its
-tier and a `weight` that says it was migrated, never a schema-7 marker —
-state.py decides by that marker.
-"""
-import json
-from collections import OrderedDict
-
-VERSION = 7
-TITLE = "carry the risk-tier table's edits into weight.json, and give a task in flight a mode"
-OLD = ".ai/policies/risk-tiers.json"
-NEW = ".ai/policies/weight.json"
-MOVES = []
-
-TIER_MODE = {"T0": "light", "T1": "light", "T2": "light", "T3": "guarded", "T4": "guarded",
-             "T5": "full", "T6": "full_irreversible"}
-EXAMPLE_MODE = dict(TIER_MODE, T6="full")
-DOMAIN = {"payments", "money", "tax", "invoice", "identity", "customer_data", "personal_data"}
-INFRA = {"infra", "k8s", "deploy", "production"}
-NEEDS_STEP = {"migrations", "schema", "config"}
-HINTS = {"auth": "domain", "security": "domain", "pipeline": "behaviour", "dependencies": "novelty"}
-DROPPED = {"tests", "docs", "source"}
-TEST_KEYS = ("timeout_seconds", "env_retries", "log_max_bytes")
-
-
-def _loads(raw):
-    try:
-        doc = json.loads(raw, object_pairs_hook=OrderedDict)
-    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
-
-
-def _shipped(ctx):
-    """What every shipped risk-tiers.json said — per tier, per scope, and each
-    scalar a run carries — and the shipped weight table: only a value the
-    project changed on top of these is carried."""
-    examples, scopes, scalars = {}, {}, {}
-    for raw in ctx.shipped(OLD):
-        doc = _loads(raw) or {}
-        for key, value in _scalars(doc).items():
-            scalars.setdefault(key, []).append(value)
-        for tier, entry in (doc.get("tiers") or {}).items():
-            if isinstance(entry, dict):
-                examples.setdefault(tier, set()).update(e for e in entry.get("examples") or [] if isinstance(e, str))
-        for scope in doc.get("path_scopes") or []:
-            if isinstance(scope, dict):
-                scopes.setdefault(scope.get("scope"), set()).update(
-                    p for p in scope.get("paths") or [] if isinstance(p, str))
-    return examples, scopes, scalars, _loads(ctx.template(NEW)) or {}
-
-
-def _scalars(old):
-    """{"tests.<key>" | "review_rounds_max" | "remediation_rounds": value} of an old table."""
-    out = {}
-    tests = (old.get("sensors") or {}).get("tests") if isinstance(old.get("sensors"), dict) else None
-    for key in TEST_KEYS + ("max_suite_runs",):
-        if isinstance(tests, dict) and key in tests:
-            out["tests." + key] = tests[key]
-    for key in ("review_rounds_max", "remediation_rounds"):
-        if isinstance(old.get(key), int):
-            out[key] = old[key]
-    return out
-
-
-def _get(doc, dotted):
-    for part in dotted.split("."):
-        doc = doc.get(part) if isinstance(doc, dict) else None
-    return doc
-
-
-def _add(items, values):
-    for value in values:
-        if value not in items:
-            items.append(value)
-
-
-def _hint(doc, axis, paths, note):
-    hint = next((h for h in doc.setdefault("hints", []) if isinstance(h, dict) and h.get("axis") == axis), None)
-    if hint is None:
-        doc["hints"].append(OrderedDict([("paths", list(paths)), ("axis", axis), ("note", note)]))
-    else:
-        _add(hint.setdefault("paths", []), paths)
-
-
-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
-    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:
-                out.append(("list", ("examples", EXAMPLE_MODE[tier]), extra))
-    for scope in old.get("path_scopes") or []:
-        if not isinstance(scope, dict):
-            continue
-        name = scope.get("scope")
-        paths = [p for p in scope.get("paths") or []
-                 if isinstance(p, str) and p not in shipped_scopes.get(name, set())]
-        if not paths or name in DROPPED:
-            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")):
-            out.append(("list", ("axes", "domain", "modules"), paths))
-        elif name in HINTS:
-            out.append(("hint", HINTS[name], (paths, "%s (from risk-tiers.json)" % name)))
-        elif name in INFRA | NEEDS_STEP:
-            two = [p for p in paths if name in INFRA and "prod" in p]
-            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)
-        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:
-            node[path[-1]] = value
-    return new
-
-
-def _mode(state):
-    """The task in flight: a mode from its tier, a weight nobody measured. The
-    schema-7 marker is never added: the task finishes on the surface it began on."""
-    if state.get("schema") == VERSION:
-        return state
-    tier = state.get("risk_tier")
-    if tier in TIER_MODE:
-        state.setdefault("mode", TIER_MODE[tier])
-    state.setdefault("weight", {"w": None, "axes": {}, "unknown": ["migrated"]})
-    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
-        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:
-        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 "
-                 "regenerate weight.md beside it" % NEW)
-    ctx.patch_state(_mode)

package/skills/project-update/migrations/0008_renames.py

@@ -1,43 +0,0 @@
-"""0008: the plugin is RiskRails.
-
-A refactoring (R35); every decision the guards take stays the same.
-
-  * The state file does not move here. R34 is expand/contract: this version's
-    guards and state.py read `.ai/state/state.json` first and `current.json`
-    otherwise, and write the file where it is; a later migration moves it, once
-    a version that reads both names has shipped, so reverting the move still
-    leaves every task guarded.
-  * The markers of the managed block (`<!-- claude-agentic:start -->` / `:end`)
-    and of each rule block (`claude-agentic:rule:<slug>:start` / `:end`) in the
-    project's root instruction files take the name `riskrails`. Only the word
-    inside a marker changes: the text around the block, and the spacing inside
-    the marker, are left byte for byte as they are. Rule blocks in other
-    directories are renamed by the renderer the next time it splices them.
-  * `.ai/AGENTS.md` routes to `<home>/riskrails/ai` and `<home>/riskrails/ai-path`
-    instead of `<home>/claude-agentic/...`; the installer leaves a symlink at the
-    old home for one version.
-"""
-import re
-
-VERSION = 8
-TITLE = "rename the plugin's markers and routes to RiskRails"
-MOVES = []
-
-ROUTER = ".ai/AGENTS.md"
-MARKER = re.compile(
-    rb"(<!--\s*)claude-agentic(:(?:start|end|rule:[a-z0-9][a-z0-9-]*:(?:start|end))\s*-->)")
-ROUTE = re.compile(rb"(?<=/)claude-agentic(?=/ai(?:-path)?\b)")
-
-
-def rename_markers(data):
-    return MARKER.sub(rb"\1riskrails\2", data)
-
-
-def rename_routes(data):
-    return ROUTE.sub(b"riskrails", data)
-
-
-def plan(ctx):
-    for path in ctx.instruction_files():
-        ctx.edit_text(path, rename_markers, "claude-agentic markers renamed to riskrails")
-    ctx.edit_text(ROUTER, rename_routes, "routes to the riskrails home")

package/skills/project-update/migrations/0009_state_file.py

@@ -1,25 +0,0 @@
-"""0009: the task's state file is `.ai/state/state.json`.
-
-R34's contract half. 0008 shipped the expand half: the guards and state.py of
-3.4b read `.ai/state/state.json` first and `current.json` otherwise, and write
-the file where it is. This migration, run once such a version is installed,
-moves a task in flight from `current.json` to `state.json`, and `state.py start`
-opens every new task in `state.json`.
-
-  * The move goes through MOVES like any other: no task in flight means no
-    file, and nothing happens; a project that already holds `state.json` keeps
-    it (a `current.json` beside it is a conflict for a human, not overwritten).
-  * The file's bytes are not touched: every field of the task survives.
-  * Reverting to 3.4b after the move still guards the task, because that
-    version reads `state.json`.
-"""
-
-VERSION = 9
-TITLE = "the task's state file is state.json"
-STATE_LEGACY = ".ai/state/current.json"
-STATE_NEW = ".ai/state/state.json"
-MOVES = [(STATE_LEGACY, STATE_NEW)]
-
-
-def plan(ctx):
-    ctx.move(STATE_LEGACY, STATE_NEW)

package/skills/project-update/migrations/0010_dialog_switch.py

@@ -1,30 +0,0 @@
-"""0010: the command-choice dialog is on (R36.1).
-
-`.ai/policies/dialog.json` is the project's switch for the dialog: the human
-picks a commit, push or approval command in the runtime's dialog and the agent
-runs that command, verbatim and once. This migration writes the switch, on, as
-the scaffold does for a new project.
-
-  * A project that already has the file keeps it, whatever it says: `create`
-    does not overwrite, and a human's `"enabled": false` stays off.
-  * A second run finds the file and does nothing, and prints nothing.
-  * The task's state is not touched: a task in flight survives.
-"""
-
-VERSION = 10
-TITLE = "the command-choice dialog switch"
-SWITCH = ".ai/policies/dialog.json"
-MOVES = []
-
-
-def plan(ctx):
-    if ctx.exists(SWITCH):
-        return
-    ctx.create(SWITCH, ctx.template(SWITCH))
-    ctx.hint("%s is new and the command-choice dialog is on; set \"enabled\": false in it to turn the dialog off"
-             % SWITCH)
-    ctx.hint("docs/sdlc/constitution.md C5 still says no agent commits, merges or deploys: if you keep the dialog "
-             "on, amend C5 to the new sentence (skills/project-init/templates/constitution.md, C5)")
-    if ctx.state is not None:
-        ctx.hint("a task is in flight: the dialog switch takes effect for it too; set \"enabled\": false in %s "
-                 "to turn it off" % SWITCH)

package/skills/project-update/migrations/0011_retire_risk_tiers.py

@@ -1,37 +0,0 @@
-"""0011: the old tier policy is retired (register #20, #50, #58, #62).
-
-`.ai/policies/risk-tiers.json` and its generated mirror `risk-tiers.md` were
-replaced by `.ai/policies/weight.json` (migration 0007 converted the project's
-edits) and nothing in the plugin reads them any more. The plugin stops shipping
-both, and this migration proposes deleting the project's copies.
-
-  * Each file the project has is proposed for deletion: a `delete?` item that
-    waits for --apply --confirm-delete NAME, with the original kept under
-    `.ai/reports/project-update-<date>/original/`. Git is the rollback.
-  * A copy the project edited is proposed too, and the reason says it was
-    edited: the human decides, and may keep the file by never confirming (the
-    schema then stays at 10) or by copying what they need into weight.json first.
-  * A project without the files gets nothing, and so does a second run.
-  * The templates are retired in `migrations.RETIRED`, so the template walk never
-    re-creates a deleted file.
-"""
-
-VERSION = 11
-TITLE = "retire risk-tiers.json and risk-tiers.md (weight.json replaced them)"
-MOVES = []
-
-PATHS = (".ai/policies/risk-tiers.json", ".ai/policies/risk-tiers.md")
-REASON = "replaced by .ai/policies/weight.json; nothing reads it any more"
-EDITED = REASON + " — your project edited this copy, check weight.json holds what you need"
-
-
-def plan(ctx):
-    for path in PATHS:
-        if not ctx.exists(path):
-            continue
-        why = ctx.unsafe_target(path)
-        if why:
-            ctx.hint("%s: %s, so this update never deletes it — remove it by hand once weight.json holds "
-                     "what you need" % (path, why))
-            continue
-        ctx.delete(path, REASON if ctx.is_shipped(path, ctx.read(path)) else EDITED)

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

@@ -1,76 +0,0 @@
-# Writing a migration
-
-For plugin developers; `/rr-setup --update` runs them. One module per version in
-this directory, named `NNNN_slug.py`, numbered contiguously from `0001`, with
-`VERSION` equal to the prefix, a one-line `TITLE`, a static `MOVES` list and
-`plan(ctx)`.
-
-- Every rename a migration performs belongs in `MOVES`, so the template history
-  follows the file and the project's edits merge at the new path. `ctx.move`
-  refuses a pair that is not there.
-- A template renamed under `skills/project-init/templates/` changes its history
-  key without moving any project path; record it in `RETIRED` as
-  `{"project-init/old-name.md": "project-init/new-name.md"}`. `RETIRED` also
-  takes `None` for a template that is simply gone. The test suite fails on a
-  history key that is neither current, nor a `MOVES` source, nor listed there.
-- A migration that deletes must retire the template in the same release,
-  otherwise the next run re-creates the file.
-- `ctx.patch_state` is the only way to change a task in flight, and the only
-  writer of the task's state file (`.ai/state/state.json`, `current.json` in a
-  project not yet at schema 9) other than `state.py`. A migration that
-  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`; 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
-  appends it again.
-
-## What a migration can ask the plugin
-
-`ctx` carries what the plugin knows about itself, so a migration recognises its
-own text instead of matching a pattern against the human's prose:
-
-- `ctx.instruction_files()` — the root instruction files this project actually
-  has, one per runtime it declares (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
-  `.junie/guidelines.md`).
-- `ctx.shipped(path)` — every version of every template the plugin ever
-  installed at that path, oldest first, following renames. A migration that
-  removes shipped text matches it **verbatim against one of these**; a regular
-  expression over the project's prose is how a migration eats a paragraph
-  somebody wrote.
-- `ctx.block_status(path)` — `"none"`, `"shipped"` or `"edited"` for the managed
-  block. An edited block is never written over, by a migration or by anything
-  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).
-- `ctx.require_shared(paths)` — refuse (exit 2, nothing written) when a shared
-  file those copies fall back to is missing from an installed home.
-  `ctx.unsafe_target(path)` — why a path must not be deleted (a symlink, or
-  outside the project). `ctx.override_note(path)` — the wording for an edited
-  shared copy. Words that name a runtime live in `update.py`, never in a
-  migration.
-
-A migration that edits a file **outside `.ai/`** is editing the project's own
-file: `apply` copies the original to
-`.ai/reports/project-update-<date>/original/<path>` before the first write, so
-what was there is recoverable without git.