riskrails 3.2.1 → 4.0.1

package/skills/ai-task/sensors.py

@@ -3,7 +3,7 @@
 
 Why a separate module: state.py owns every write to state.json and has no
 subprocess use at all; this module shells out to git and to the commands written
-in .ai/policies/testing.md, imports nothing from state.py, and never opens
+in .ai/policies/verification.md, imports nothing from state.py, and never opens
 state.json for writing. state.py imports it, not the reverse. Since redesign
 2.6 it measures nothing else: the size budget, the re-score and the static
 sensors (bite, duplicates, traceability, plan sections, lint, typecheck, detect)
@@ -213,11 +213,11 @@ SCOPE_FIELD = {"suite": "verify_command", "step": "step_test_command",
 
 
 def testing_path(root):
-    return os.path.join(root, ".ai", "policies", "testing.md")
+    return os.path.join(root, ".ai", "policies", "verification.md")
 
 
 def read_commands(root):
-    """The project's own commands, as a human wrote them into testing.md.
+    """The project's own commands, as a human wrote them into verification.md.
 
     A line's value is everything after the colon, minus a trailing comment; the
     template ships the fields with an explanatory comment and no value, and that
@@ -253,7 +253,7 @@ def _escaped(text):
 
 def bite_codes(root):
     """The exit codes that count as "the test fails" under --expect fail: the
-    testing.md `bite_codes` list of integers 1-255, 1 when absent or not a clean list
+    verification.md `bite_codes` list of integers 1-255, 1 when absent or not a clean list
     (an empty part, a non-integer, 0, a negative or a value over 255 all fall back)."""
     raw = read_commands(root).get("bite_codes", "")
     try:
@@ -349,8 +349,6 @@ def resolve_trees(root, args):
     from_tree = args.from_tree
     if not from_tree:
         state = os.path.join(root, ".ai", "state", "state.json")
-        if not os.path.isfile(state):
-            state = os.path.join(root, ".ai", "state", "current.json")  # R34: legacy name, one version
         try:
             with open(state, encoding="utf-8") as fh:
                 from_tree = ((json.load(fh) or {}).get("diff") or {}).get("base_tree")
@@ -387,11 +385,12 @@ def cmd_diff(args, root):
 
 
 def tests_config(root):
-    """The runner's caps from weight.json `tests`, the template's numbers otherwise."""
+    """The runner's caps from the weight table's `tests` (the plugin's, the project's
+    weight.project.json over it), {} when the table cannot be read."""
     try:
-        with open(os.path.join(root, ".ai", "policies", "weight.json"), encoding="utf-8") as fh:
-            config = (json.load(fh) or {}).get("tests") or {}
-    except (OSError, ValueError, AttributeError):
+        import weight  # pylint: disable=import-outside-toplevel  # sits beside this file; only cmd_run needs it
+        config = weight.load_policy(root)[0].get("tests") or {}
+    except (ImportError, OSError, ValueError, AttributeError):
         config = {}
     return config if isinstance(config, dict) else {}
 
@@ -400,7 +399,7 @@ def cmd_run(args, root):
     config = tests_config(root)
     command = command_for(root, args.scope)
     if not command:
-        print("%-13s UNAVAIL  %s is not written down in .ai/policies/testing.md"
+        print("%-13s UNAVAIL  %s is not written down in .ai/policies/verification.md"
               % (args.scope, SCOPE_FIELD.get(args.scope, args.scope)))
         return UNKNOWNCODE
     files = [f.strip() for f in (args.files or "").split(",") if f.strip()]

package/skills/ai-task/state.py

@@ -1,16 +1,16 @@
 #!/usr/bin/env python3
-"""Task state for /ai-task — the small, machine-readable record of one task.
+"""Task state for /rr-build — the small, machine-readable record of one task.
 
 Why a file and not the conversation: a conversation is expensive to re-read and
 impossible for a hook to consult. This file is what ai-scope-guard enforces
-against, what /ai-status reports, and what lets a task survive a /clear or a
+against, what /rr-status reports, and what lets a task survive a /clear or a
 crash. It holds facts, never transcripts.
 
 Everything is stdlib. Writes are atomic (temp file + os.replace), so a hook that
 reads the file while a stage is being recorded never sees half a document.
 
 Every state change is also appended to .ai/reports/<task-id>/events.jsonl, the
-append-only journal /ai-status and /usage-report read at zero model cost. The
+append-only journal /rr-status and /rr-status --cost read at zero model cost. The
 journal is best effort by contract: a line that cannot be written never fails
 the command that emitted it, and nothing here depends on it being lossless.
 history[] keeps its exact shape and its original event names beside it.
@@ -57,8 +57,7 @@ redesign 2.6) answers status, handoff and questions, and close --abandon drops
 it; every other command refuses it.
 """
 
-# pylint: disable=unused-import,wrong-import-position
-import json
+# pylint: disable=wrong-import-position
 import os
 import sys
 
@@ -68,26 +67,7 @@ try:
 except ImportError:
     sys.exit("rr_state/ is missing beside state.py: re-run `npx riskrails`")
 fs.ENTRY = os.path.abspath(__file__)    # R6a: the one path the package prints and compares
-
-# The names the suites reach as state_mod.<name> (R6) and json_loads_capped, which
-# tests/test_dialog_contract.py:176,189 reach as module.json_loads_capped over (dialog, state_mod);
-# json and os are imported above for the same reason: the suites patch state_mod.json.dump and state_mod.os.
 from rr_state.cli import main
-from rr_state.fs import current_tree, read_session, session_path, state_path
-from rr_state.runtime import AGENT_MARKERS
-from rr_state.journal import append_journal, journal_line, read_journal
-from rr_state.task import TASK_ID_RE, abandon_old, load, next_task_id, sealed_task_ids, valid_task_id
-from rr_state.policy import NEVER_DOCUMENTS, is_document, mode_for, rescore_weight
-from rr_state.locks import LOCK_STALE
-from rr_state.questions import parse_questions
-from rr_state.questions_cmd import close_gate_from_file, sync_answers
-from rr_state.ledger import LEDGER_LINE_MAX, LEDGER_TYPES, live_picks, read_ledger
-from rr_state.dialog import DIALOG_TOOL, JSON_DEPTH_MAX, QUESTION_MAX, SESSION_ENV, json_loads_capped
-from rr_state.dialog import dialog_on, dialog_payload, dialog_policy, dialog_tool_verified, task_facts
-from rr_state.labels import LABEL_MAX, validate_label
-from rr_state.gate import confirm_names
-from rr_state.profile import jwt_plan_type, read_json_object, read_profile, read_quota
-from rr_state.close import archive_v7
 
 if __name__ == "__main__":
     main()

package/skills/ai-task/weight.py

@@ -1,4 +1,4 @@
-"""Weight — six axes, 0 to 2 each, from .ai/policies/weight.json.
+"""Weight — six axes, 0 to 2 each, from the plugin's weight table with .ai/policies/weight.project.json laid over it.
 
 Pure computation: it reads the declared files, the tree listing and `git grep`,
 and writes nothing. A measured value is a floor: the session may raise an axis
@@ -39,15 +39,10 @@ class Weight:
 
 
 def load_policy(root):
-    """(policy, path): the project's table, else the one this plugin ships.
-    A broken table raises ValueError, never a silent default."""
-    own = os.path.join(root, ".ai", "policies", "weight.json")
-    path = own if os.path.isfile(own) else SHIPPED
-    with open(path, encoding="utf-8") as fh:
-        policy = json.load(fh)
-    if not isinstance(policy, dict) or not all(isinstance(policy.get(k), dict) for k in ("axes", "modes")):
-        raise ValueError("%s has no axes or modes table" % path)
-    return policy, path
+    """(policy, [shipped, project]): the shipped table with the project's weight.project.json laid over it."""
+    import weight_overlay  # pylint: disable=import-outside-toplevel  # beside this file; update.py loads this file by path
+    own = os.path.join(root, ".ai", "policies", "weight.project.json")
+    return weight_overlay.load(SHIPPED, own), [SHIPPED, own]
 
 
 @functools.lru_cache(maxsize=None)
@@ -268,14 +263,19 @@ def render(result, long=False):
     return "\n".join(lines)
 
 
-def mirror(path):
-    """weight.md for the JSON at `path`, carrying its sha256."""
-    with open(path, "rb") as fh:
-        raw = fh.read()
-    policy = json.loads(raw.decode("utf-8"))
+def mirror(source):
+    """weight.md for `source`: a policy dict (the effective table, sha256 of its canonical JSON) or
+    the path of one JSON file (sha256 of its bytes)."""
+    if isinstance(source, dict):
+        policy, origin = source, "the plugin's weight table plus weight.project.json"
+        raw = json.dumps(source, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    else:
+        with open(source, "rb") as fh:
+            raw = fh.read()
+        policy, origin = json.loads(raw.decode("utf-8")), "weight.json"
     out = ["# Weight table", "",
-           "<!-- generated by `state.py weight --mirror` from weight.json; edit the JSON and regenerate."
-           " sha256: %s -->" % hashlib.sha256(raw).hexdigest(), "",
+           "<!-- generated by `state.py weight --mirror` from %s; edit the JSON and regenerate."
+           " sha256: %s -->" % (origin, hashlib.sha256(raw).hexdigest()), "",
            "Six axes, 0–2 each; W is their sum. Why each rule is what it is: the plugin's `docs/weight.md`.", "",
            "| Axis | Measured by | Table |", "|---|---|---|"]
     for axis in AXES:

package/skills/ai-task/weight_overlay.py

@@ -0,0 +1,38 @@
+"""The weight table a project sees: the plugin's shipped table with the project's
+weight.project.json laid over it (R9). weight.py's `load_policy` calls `load`.
+
+Objects merge recursively, any other value (a list too) replaces. A file that is not
+a JSON object, or a result without the axes and modes tables, raises ValueError
+naming the file; nothing falls back to a default.
+"""
+import json
+import os
+
+
+def _table(path):
+    """One JSON object from `path`; ValueError naming the file when it is not one."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            table = json.load(fh)
+        if isinstance(table, dict):
+            return table
+        raise ValueError("not a JSON object")
+    except ValueError as exc:
+        raise ValueError("%s: %s" % (path, exc)) from exc
+
+
+def _overlay(base, top):
+    """`top` laid over `base`: dicts merge, any other value (a list too) replaces."""
+    for key, value in top.items():
+        base[key] = _overlay(base[key], value) if isinstance(value, dict) and isinstance(base.get(key), dict) else value
+    return base
+
+
+def load(shipped, own):
+    """The table at `shipped`, with `own` laid over it when that file exists."""
+    policy = _table(shipped)
+    if os.path.isfile(own):
+        _overlay(policy, _table(own))
+    if not all(isinstance(policy.get(k), dict) for k in ("axes", "modes")):
+        raise ValueError("%s has no axes or modes table" % own)
+    return policy

package/skills/project-init/templates/constitution.md

@@ -1,14 +1,14 @@
 # Constitution — {{PROJECT}}
 
 <!-- The 10–15 principles this project does not negotiate, one line each, numbered C1…;
-     /sdlc-spec and the planner cite them. Under 15: what is not here lives in .ai/policies/. -->
+     /rr-spec and the planner cite them. Under 15: what is not here lives in .ai/policies/. -->
 
 C1. Production behaviour is the source of truth; what looks wrong may be load-bearing.
 C2. A bugfix starts with the failing test; legacy behaviour gets a characterization test before it changes.
 C3. A refactoring changes no behaviour and is never mixed with a feature.
 C4. Every step names its files; scope grows only by amending the plan.
 C5. No agent merges or deploys; an agent commits, pushes or approves only by running, verbatim and once, a command a human picked in the dialog, as the harness recorded; else a human runs it outside.
-C6. <!-- project principle — filled by /ai-init from the survey, confirmed by you -->
+C6. <!-- project principle — filled by /rr-setup from the survey, confirmed by you -->
 C7. <!-- project principle -->
 C8. <!-- project principle -->
 C9. <!-- project principle -->

package/skills/project-update/history/blobs/00f5e27ce2d66e3a1d8b222b013ae8fa1fed32612d91a551e0c661cee3ef9c2d

@@ -0,0 +1,34 @@
+# Workflow: bugfix
+
+Something behaves wrongly. The goal is the smallest change that fixes it without
+changing anything else.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated; in the default `solo`
+> profile the session does the stage inline up to the tier where the profile
+> delegates it.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | reproduce first: find the exact path that produces the symptom |
+| CONTEXT | `ai-context` | include the *correct* behaviour and where it is defined |
+| IMPACT ANALYSIS | `ai-discovery` | who else depends on the current, wrong behaviour |
+| RISK CLASSIFICATION | `ai-risk` | a bug in a payment path is still T4 |
+| PLAN | `ai-planner` | failing test first, then the fix |
+| IMPLEMENTATION | the session | the failing test is its own step |
+| TEST | `ai-tester` | the new test fails before the fix and passes after |
+| ADVERSARIAL REVIEW | `ai-reviewer` | T2 and above |
+| SECURITY REVIEW | `ai-security` | if the bug was a security bug, always |
+| RELEASE REPORT | `ai-release` | |
+| HUMAN APPROVAL | the human | |
+
+## Specific to this workflow
+
+- **Write the failing test first.** A bugfix without a test that failed before it
+  is a bugfix nobody can prove.
+- Find out *why* the bug exists before fixing it. A bug that is deliberate
+  behaviour somebody depends on is not a bug; it is a requirements conflict, and
+  it goes back to the human.
+- Resist the urge to fix the surrounding code. Note it, fix the bug.
+- If the same bug exists in three places, fix the one that was reported and list
+  the other two in `project/known-risks.md`.

package/skills/project-update/history/blobs/0a6b1b6dd06a35582b2e9989a1f41c40abc29254b8e482714fcc6f0a7b16c406

@@ -0,0 +1,32 @@
+# Workflow: feature
+
+New behaviour that someone asked for. The default workflow.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated; in the default `solo`
+> profile the session does the stage inline up to the tier where the profile
+> delegates it.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-indexer` then `ai-discovery` | where the feature lands, what it will touch |
+| CONTEXT | `ai-context` | the structured summary everything downstream reads |
+| IMPACT ANALYSIS | `ai-discovery` (second pass) | callers, data, contracts, other environments |
+| RISK CLASSIFICATION | `ai-risk` | one tier, from `policies/risk-tiers.json` |
+| PLAN | `ai-planner` | steps with `allowed_files`; STRONG for T3/T4, `ai-expert` for T5 |
+| PLAN REVIEW | `ai-reviewer` | T3 and above |
+| IMPLEMENTATION | the session, one step at a time | scope-guarded |
+| TEST | `ai-tester` | after every step, not only at the end |
+| ADVERSARIAL REVIEW | `ai-reviewer` | T2 and above |
+| SECURITY REVIEW | `ai-security` | T4, T5, and anything touching auth or personal data |
+| RELEASE REPORT | `ai-release` | full report from T2 up |
+| HUMAN APPROVAL | the human | the pipeline stops here |
+
+## Specific to this workflow
+
+- The plan states what stays the same, not only what changes. A feature that
+  quietly alters an existing behaviour is the most common source of regressions.
+- New code paths need their negative cases tested: not authorized, not found,
+  invalid input, external system down.
+- If the feature needs a new dependency, that is a decision worth its own line in
+  the plan.

package/skills/project-update/history/blobs/0aeb04b04262683cac6513545683486a73dc473b447bba43b5aaab18403957a6

@@ -0,0 +1,34 @@
+# Manager
+
+The manager is the main session, not a subagent. It orchestrates; it does not
+collect facts itself, and it keeps its own context small so it can stay in the
+task until the end.
+
+## Responsibilities
+
+- Understand the request and restate it in one sentence the human can correct.
+- Classify the task: which workflow, which risk tier.
+- Establish scope, and defend it.
+- Choose the stages the tier requires, and the agent for each.
+- Delegate every reading and analysis stage. Never read logs, test output or
+  large files into its own context.
+- Split the work into steps small enough that each one names the files it touches.
+- Track state through `state.py` after every stage. The state file, not the
+  conversation, is what survives.
+- Decide when to escalate a model tier, one task at a time, against the triggers
+  in `policies/risk-tiers.json`.
+- Write the final summary the human reads.
+
+## What the manager must not do
+
+- Skip a stage because the task looks easy. Make it lightweight instead, and
+  record that it happened.
+- Expand scope. A discovered problem goes into `project/known-risks.md`.
+- Delegate the conclusion. The synthesis a human reads is written by the session.
+- Commit, push, merge or deploy. The pipeline ends at human approval.
+
+## Implementation
+
+The manager implements approved steps itself, under this policy and under
+`ai-scope-guard`. `ai-implementer` exists for mechanical, pattern-copying steps
+and for when the human asks for it — not as the default.

package/skills/project-update/history/blobs/0ce913a28996f546f72d570b0e5a376362e993ce4d805bc4aae57d38caa44212

@@ -0,0 +1,41 @@
+# Workflow: refactoring
+
+Changing the shape of code without changing what it does. The most dangerous
+workflow in a legacy codebase, because success is invisible.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated. In the default `solo`
+> profile T0–T2 run in direct mode — the session does every stage itself, in a
+> few lines, with cheap readers and one `sonnet` review at T2 — and T3+ run the
+> full pipeline with the delegations below.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | every caller, every test, every dynamic reference |
+| CONTEXT | `ai-context` | with `legacy_constraints` filled properly |
+| IMPACT ANALYSIS | `ai-discovery` | serialized data, cache keys, service ids, event names |
+| RISK CLASSIFICATION | `ai-risk` | shared code is T3 minimum |
+| PLAN | `ai-planner` | characterization tests as their own steps, before anything moves |
+| PLAN REVIEW | `ai-reviewer` | always, whatever the tier |
+| IMPLEMENTATION | the session | one mechanical transformation per step |
+| TEST | the session (`ai-tester` in `team`) | the same tests, unchanged, must still pass — the characterization tests for the moved code run inside their step, the full suite once at the end, then the e2e suite once; failures fixed as one batch |
+| ADVERSARIAL REVIEW | `ai-reviewer` | looking specifically for behaviour drift |
+| RELEASE REPORT | `ai-release` | |
+| HUMAN APPROVAL | the human | |
+
+## The order, which is not negotiable
+
+```
+characterization test → refactor → verify identical behaviour → (a different task) feature change
+```
+
+## Rules
+
+- **Never** combine a refactoring with a feature change. If the plan contains
+  both, it is two tasks.
+- A test that has to be modified during a refactoring is a signal that behaviour
+  changed. Stop and say so.
+- Renaming something that appears in a string — a service id, a template name, a
+  queue name, a route name, a column — is not a rename, it is a migration.
+- If the only justification is "this is cleaner", the task needs a human to
+  confirm it is worth the risk before it starts.

package/skills/project-update/history/blobs/0ea9e36446b624b73b2a821231b2ee66a357b43d584a5b23da48b3c800855e65

@@ -0,0 +1,41 @@
+# Workflow: refactoring
+
+Changing the shape of code without changing what it does. The most dangerous
+workflow in a legacy codebase, because success is invisible.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated. In the default `solo`
+> profile T0–T2 run in direct mode — the session does every stage itself, in a
+> few lines, with cheap readers and one `sonnet` review at T2 — and T3+ run the
+> full pipeline with the delegations below.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | every caller, every test, every dynamic reference |
+| CONTEXT | `ai-context` | with `legacy_constraints` filled properly |
+| IMPACT ANALYSIS | `ai-discovery` | serialized data, cache keys, service ids, event names |
+| RISK CLASSIFICATION | `ai-risk` | shared code is T3 minimum |
+| PLAN | `ai-planner` | characterization tests as their own steps, before anything moves |
+| PLAN REVIEW | `ai-reviewer` | always, whatever the tier |
+| IMPLEMENTATION | the session | one mechanical transformation per step |
+| TEST | the session (`ai-tester` in `team`) | the same tests, unchanged, must still pass; one full run at the end, failures fixed as one batch |
+| ADVERSARIAL REVIEW | `ai-reviewer` | looking specifically for behaviour drift |
+| RELEASE REPORT | `ai-release` | |
+| HUMAN APPROVAL | the human | |
+
+## The order, which is not negotiable
+
+```
+characterization test → refactor → verify identical behaviour → (a different task) feature change
+```
+
+## Rules
+
+- **Never** combine a refactoring with a feature change. If the plan contains
+  both, it is two tasks.
+- A test that has to be modified during a refactoring is a signal that behaviour
+  changed. Stop and say so.
+- Renaming something that appears in a string — a service id, a template name, a
+  queue name, a route name, a column — is not a rename, it is a migration.
+- If the only justification is "this is cleaner", the task needs a human to
+  confirm it is worth the risk before it starts.

package/skills/project-update/history/blobs/0fb1d68678a1349195b2e79433bb20174d25874e3bfd0b70410bb4e428b4e4b8

@@ -0,0 +1,35 @@
+# Workflow: hotfix
+
+Production is broken now. Stages get shorter; none of them disappears.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated. In the default `solo`
+> profile T0–T3 run in direct mode — the session does every stage itself, in a
+> few lines, with cheap readers and one review (BALANCED at T2; STRONG at T3,
+> whose plan the human approves in plan mode) — and T4+ run the full pipeline
+> with the delegations below.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | narrow: the failing path only |
+| CONTEXT | the session, inline | a paragraph, recorded in the state file |
+| RISK CLASSIFICATION | `ai-risk` | the tier of the code being touched, not of the urgency |
+| PLAN | `ai-planner` or the session | the smallest change that stops the bleeding |
+| IMPLEMENTATION | the session | one step |
+| TEST | the session (`ai-tester` in `team`) | at minimum, a test that reproduces the incident, run scoped; the full command once after the fix, then e2e only if the incident is in a flow it covers; failures fixed as one batch |
+| ADVERSARIAL REVIEW | `ai-reviewer` | short, focused on "what else does this touch" |
+| SECURITY REVIEW | `ai-security` | if the incident is a security incident |
+| RELEASE REPORT | `ai-release` | short form, but rollback is mandatory |
+| HUMAN APPROVAL | the human | always, and usually faster than the rest |
+
+## Rules
+
+- Urgency lowers the *depth* of a stage, never its existence. The risk tier is a
+  property of the code, not of how loudly someone is asking.
+- A hotfix is the smallest possible change. Everything else — the real fix, the
+  cleanup, the missing test — becomes a follow-up task, written down before the
+  hotfix is approved so it does not evaporate when the incident closes.
+- Record what actually happened in `project/known-risks.md`: the trigger, the
+  detection, and what would have caught it earlier.
+- Never disable a test or a check to get a hotfix out. If CI is the obstacle, a
+  human decides that, explicitly.

package/skills/project-update/history/blobs/119b2b9d0f9c647a243540724edac6b29afa020c69aa205797bcfa9eb06bc021

@@ -0,0 +1,35 @@
+# Workflow: bugfix
+
+Something behaves wrongly. The goal is the smallest change that fixes it without
+changing anything else.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated. In the default `solo`
+> profile T0–T2 run in direct mode — the session does every stage itself, in a
+> few lines, with cheap readers and one BALANCED review at T2 — and T3+ run the
+> full pipeline with the delegations below.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | reproduce first: find the exact path that produces the symptom |
+| CONTEXT | `ai-context` | include the *correct* behaviour and where it is defined |
+| IMPACT ANALYSIS | `ai-discovery` | who else depends on the current, wrong behaviour |
+| RISK CLASSIFICATION | `ai-risk` | a bug in a payment path is still T4 |
+| PLAN | `ai-planner` | failing test first, then the fix |
+| IMPLEMENTATION | the session | the failing test is its own step |
+| TEST | the session (`ai-tester` in `team`) | the new test is shown failing before the fix; each step runs only its own scoped tests; the full verification command runs once after the last step, to the end, then the e2e suite once; every failure fixed as one batch |
+| ADVERSARIAL REVIEW | `ai-reviewer` | T2 and above |
+| SECURITY REVIEW | `ai-security` | if the bug was a security bug, always |
+| RELEASE REPORT | `ai-release` | |
+| HUMAN APPROVAL | the human | |
+
+## Specific to this workflow
+
+- **Write the failing test first.** A bugfix without a test that failed before it
+  is a bugfix nobody can prove.
+- Find out *why* the bug exists before fixing it. A bug that is deliberate
+  behaviour somebody depends on is not a bug; it is a requirements conflict, and
+  it goes back to the human.
+- Resist the urge to fix the surrounding code. Note it, fix the bug.
+- If the same bug exists in three places, fix the one that was reported and list
+  the other two in `project/known-risks.md`.

package/skills/project-update/history/blobs/1d0fe3ee5fb8260ba610942d4bbdfff7410fbe80ed826ac07f32985031dc2b3f

@@ -0,0 +1,34 @@
+# Workflow: hotfix
+
+Production is broken now. Stages get shorter; none of them disappears.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated. In the default `solo`
+> profile T0–T2 run in direct mode — the session does every stage itself, in a
+> few lines, with cheap readers and one BALANCED review at T2 — and T3+ run the
+> full pipeline with the delegations below.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | narrow: the failing path only |
+| CONTEXT | the session, inline | a paragraph, recorded in the state file |
+| RISK CLASSIFICATION | `ai-risk` | the tier of the code being touched, not of the urgency |
+| PLAN | `ai-planner` or the session | the smallest change that stops the bleeding |
+| IMPLEMENTATION | the session | one step |
+| TEST | the session (`ai-tester` in `team`) | at minimum, a test that reproduces the incident, run scoped; the full command once after the fix, then e2e only if the incident is in a flow it covers; failures fixed as one batch |
+| ADVERSARIAL REVIEW | `ai-reviewer` | short, focused on "what else does this touch" |
+| SECURITY REVIEW | `ai-security` | if the incident is a security incident |
+| RELEASE REPORT | `ai-release` | short form, but rollback is mandatory |
+| HUMAN APPROVAL | the human | always, and usually faster than the rest |
+
+## Rules
+
+- Urgency lowers the *depth* of a stage, never its existence. The risk tier is a
+  property of the code, not of how loudly someone is asking.
+- A hotfix is the smallest possible change. Everything else — the real fix, the
+  cleanup, the missing test — becomes a follow-up task, written down before the
+  hotfix is approved so it does not evaporate when the incident closes.
+- Record what actually happened in `project/known-risks.md`: the trigger, the
+  detection, and what would have caught it earlier.
+- Never disable a test or a check to get a hotfix out. If CI is the obstacle, a
+  human decides that, explicitly.

package/skills/project-update/history/blobs/1de9a37ed6402893dcab6e61ddbf15ffd35f15a6d84b18e675a0c5bf4e981f85

@@ -0,0 +1,42 @@
+# Workflow: refactoring
+
+Changing the shape of code without changing what it does. The most dangerous
+workflow in a legacy codebase, because success is invisible.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated. In the default `solo`
+> profile T0–T4 run in direct mode — the session does every stage itself, in a
+> few lines, with cheap readers and one review (BALANCED at T2/T3, and only
+> when a sensor is red; STRONG at T4, whose plan the human approves in plan
+> mode) — and T5+ run the full pipeline with the delegations below.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | every caller, every test, every dynamic reference |
+| CONTEXT | `ai-context` | with `legacy_constraints` filled properly |
+| IMPACT ANALYSIS | `ai-discovery` | serialized data, cache keys, service ids, event names |
+| RISK CLASSIFICATION | `ai-risk` | shared code is T4 minimum |
+| PLAN | `ai-planner` | characterization tests as their own steps, before anything moves |
+| PLAN REVIEW | `ai-reviewer` | always, whatever the tier |
+| IMPLEMENTATION | the session | one mechanical transformation per step |
+| TEST | the session (`ai-tester` in `team`) | the same tests, unchanged, must still pass — the characterization tests for the moved code run inside their step, the full suite once at the end, then the e2e suite once; failures fixed as one batch |
+| ADVERSARIAL REVIEW | `ai-reviewer` | looking specifically for behaviour drift |
+| RELEASE REPORT | `ai-release` | |
+| HUMAN APPROVAL | the human | |
+
+## The order, which is not negotiable
+
+```
+characterization test → refactor → verify identical behaviour → (a different task) feature change
+```
+
+## Rules
+
+- **Never** combine a refactoring with a feature change. If the plan contains
+  both, it is two tasks.
+- A test that has to be modified during a refactoring is a signal that behaviour
+  changed. Stop and say so.
+- Renaming something that appears in a string — a service id, a template name, a
+  queue name, a route name, a column — is not a rename, it is a migration.
+- If the only justification is "this is cleaner", the task needs a human to
+  confirm it is worth the risk before it starts.

package/skills/project-update/history/blobs/1f44e1a236233dcbab58064f39b69f798b35d1d9a29f8c615b5b12854ce633cb

@@ -0,0 +1,15 @@
+# Constitution — {{PROJECT}}
+
+<!-- The 10–15 principles this project does not negotiate, one line each, numbered C1…;
+     /rr-spec and the planner cite them. Under 15: what is not here lives in .ai/policies/. -->
+
+C1. Production behaviour is the source of truth; what looks wrong may be load-bearing.
+C2. A bugfix starts with the failing test; legacy behaviour gets a characterization test before it changes.
+C3. A refactoring changes no behaviour and is never mixed with a feature.
+C4. Every step names its files; scope grows only by amending the plan.
+C5. No agent merges or deploys; an agent commits, pushes or approves only by running, verbatim and once, a command a human picked in the dialog, as the harness recorded; else a human runs it outside.
+C6. <!-- project principle — filled by /rr-setup from the survey, confirmed by you -->
+C7. <!-- project principle -->
+C8. <!-- project principle -->
+C9. <!-- project principle -->
+C10. <!-- project principle -->

package/skills/project-update/history/blobs/1f824645299579cbdd8141642ddbb4bca9fd5fe9d3112f036d8221f0811e0abf

@@ -0,0 +1,40 @@
+# Workflow: refactoring
+
+Changing the shape of code without changing what it does. The most dangerous
+workflow in a legacy codebase, because success is invisible.
+
+> Who runs a stage is set by `pipeline_profile` in `policies/risk-tiers.json`.
+> The table names the agent for when a stage is delegated; in the default `solo`
+> profile the session does the stage inline up to the tier where the profile
+> delegates it.
+
+| Stage | Who | Notes |
+|---|---|---|
+| DISCOVERY | `ai-discovery` | every caller, every test, every dynamic reference |
+| CONTEXT | `ai-context` | with `legacy_constraints` filled properly |
+| IMPACT ANALYSIS | `ai-discovery` | serialized data, cache keys, service ids, event names |
+| RISK CLASSIFICATION | `ai-risk` | shared code is T3 minimum |
+| PLAN | `ai-planner` | characterization tests as their own steps, before anything moves |
+| PLAN REVIEW | `ai-reviewer` | always, whatever the tier |
+| IMPLEMENTATION | the session | one mechanical transformation per step |
+| TEST | `ai-tester` | the same tests, unchanged, must still pass |
+| ADVERSARIAL REVIEW | `ai-reviewer` | looking specifically for behaviour drift |
+| RELEASE REPORT | `ai-release` | |
+| HUMAN APPROVAL | the human | |
+
+## The order, which is not negotiable
+
+```
+characterization test → refactor → verify identical behaviour → (a different task) feature change
+```
+
+## Rules
+
+- **Never** combine a refactoring with a feature change. If the plan contains
+  both, it is two tasks.
+- A test that has to be modified during a refactoring is a signal that behaviour
+  changed. Stop and say so.
+- Renaming something that appears in a string — a service id, a template name, a
+  queue name, a route name, a column — is not a rename, it is a migration.
+- If the only justification is "this is cleaner", the task needs a human to
+  confirm it is worth the risk before it starts.