riskrails 4.2.0 → 4.3.0

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "A weight-based engineering pipeline for Claude Code and Codex: each change is weighed on six axes, runs light, guarded or full, edits only the files its plan names, and ends at human approval — enforced by hooks, reviewed adversarially, routed to the cheap model tier by default.",
-    "version": "4.2.0"
+    "version": "4.3.0"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
         "source": "url",
         "url": "https://github.com/vanssata/claude-agentic-sdlc-module.git"
       },
-      "version": "4.2.0",
+      "version": "4.3.0",
       "strict": true
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "A weight-based engineering pipeline for Claude Code and Codex: each change is weighed on six axes, runs light, guarded or full, edits only the files its plan names, and ends at human approval — enforced by hooks, reviewed adversarially, routed to the cheap model tier by default.",
   "author": {
     "name": "Ivan Kakurov"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "A weight-based engineering pipeline for Claude Code and Codex: each change is weighed on six axes, runs light, guarded or full, edits only the files its plan names, and ends at human approval — enforced by hooks, reviewed adversarially, routed to the cheap model tier by default.",
   "author": {
     "name": "Ivan Kakurov"

package/README.md

@@ -1,6 +1,6 @@
 # RiskRails
 
-[![Version](https://img.shields.io/badge/version-4.2.0-d2f878?labelColor=101210)](https://github.com/vanssata/claude-agentic-sdlc-module/releases/tag/v4.2.0)
+[![Version](https://img.shields.io/badge/version-4.3.0-d2f878?labelColor=101210)](https://github.com/vanssata/claude-agentic-sdlc-module/releases/tag/v4.3.0)
 [![Runtimes](https://img.shields.io/badge/runtimes-Claude%20Code%20%7C%20Codex-d2f878?labelColor=101210)](docs/routing.md)
 [![Known risks](https://img.shields.io/badge/known%20risks-documented-d2f878?labelColor=101210)](docs/known-risks.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-d2f878?labelColor=101210)](LICENSE)
@@ -18,7 +18,7 @@ approval. Risky actions are stopped by a hook, not by a polite request in a
 prompt.
 
 ```bash
-npx riskrails@4.2.0   # detects Claude Code, Codex or both (Node 18+, Python 3.11+)
+npx riskrails@4.3.0   # detects Claude Code, Codex or both (Node 18+, Python 3.11+)
 ```
 
 Then, in any project: `/rr-setup` once, and `/rr-build <what you want>` for
@@ -50,7 +50,7 @@ Tuned for **one developer who knows the codebase**, on a Claude Pro, Max or
 Team plan, or a ChatGPT Plus or Pro plan, following the
 [AI-native SDLC playbook](https://claude.com/blog/the-ai-native-sdlc-playbook).
 
-**Version 4.2.0.** The guards have limits: read [Known risks](docs/known-risks.md)
+**Version 4.3.0.** The guards have limits: read [Known risks](docs/known-risks.md)
 before relying on them. What is decided but not built is in [ROADMAP.md](ROADMAP.md).
 
 ## Upgrade to 4.0
@@ -64,8 +64,10 @@ the plugin. Step by step, in this order:
    without the conversions it missed. So a project last updated by an older
    riskrails goes through the version that still converts it: install it
    (`npx riskrails@3.1.0`), run `/rr-setup --update` with it, then install 4.0.
-2. **Commit every project's `.ai/`** first; `git restore` is the rollback.
-3. **Update the home** on every machine, for every runtime: `npx riskrails@4.2.0`
+2. **Commit every project's `.ai/`** first; `git restore` is the rollback. From
+   4.2 that commit holds the configuration: `.ai/memory/` and `.ai/reports/` are
+   git-ignored, so copy them aside if you want them back.
+3. **Update the home** on every machine, for every runtime: `npx riskrails@4.3.0`
    (the plugin route and the npm route are separate installs: reinstall both
    if you use both). Restart the runtime. In Codex, open `/hooks` and trust the
    changed entries.
@@ -84,13 +86,13 @@ are removed; use the `/rr-*` commands. Details are in
 ## Install
 
 ```bash
-npx riskrails@4.2.0                       # detects Claude Code, Codex, or both; proposes the detected plan
-npx riskrails@4.2.0 --target codex        # auto | claude | codex | both
-npx riskrails@4.2.0 --plan max --fable no # pro | team-pro | team-max | max | max20 | balanced-max
-npx riskrails@4.2.0 --codex-plan plus     # plus | pro | balanced-max
-npx riskrails@4.2.0 --context economy     # the plan's compaction window; the context guard also blocks
-npx riskrails@4.2.0 --statusline own      # keep your own statusline command (from 3.2.1; default: the plugin's two-line statusline)
-npx riskrails@4.2.0 --dry-run             # print what would be written, write nothing
+npx riskrails@4.3.0                       # detects Claude Code, Codex, or both; proposes the detected plan
+npx riskrails@4.3.0 --target codex        # auto | claude | codex | both
+npx riskrails@4.3.0 --plan max --fable no # pro | team-pro | team-max | max | max20 | balanced-max
+npx riskrails@4.3.0 --codex-plan plus     # plus | pro | balanced-max
+npx riskrails@4.3.0 --context economy     # the plan's compaction window; the context guard also blocks
+npx riskrails@4.3.0 --statusline own      # keep your own statusline command (from 3.2.1; default: the plugin's two-line statusline)
+npx riskrails@4.3.0 --dry-run             # print what would be written, write nothing
 npx -y riskrails@latest --yes             # update in place, keeping the recorded plan
 ```
 
@@ -102,6 +104,9 @@ stop with nothing written. Enter through every menu installs what detection
 proposes. A flag skips its menu; `--yes` or no terminal asks nothing, and
 `RISKRAILS_MENU=off` (or `TERM=dumb`) brings back the typed plan question.
 
+<!-- wizard recording: placeholder until the human records docs/media/wizard.tape (`vhs docs/media/wizard.tape`) and puts the GIF here -->
+*A recording of the installer wizard goes here.*
+
 Pin the version: the hooks it installs see every command an agent runs. It
 installs the managed block, the plan's settings and limits, the five agents
 with their tiers baked in, the hooks, the skills, the shared tree at
@@ -172,11 +177,14 @@ until it passes. After three failed review passes the next verdict is yours.
 
 ### The record
 
-A closed task's who, what, how and why travel as a compact record: `state.py
+A closed task's who, what, how and why are kept as a compact record: `state.py
 memory enable` (yours, in a terminal, or as your pick in the `/rr-setup`
 dialog) switches a project to packages mode, in
 which `close` appends the task's entries to a per-developer batch under
-`.ai/memory/` and a pre-push hook validates them; `state.py recall --files …`
+`.ai/memory/`. From 4.2 the record is local by default (`.ai/memory/` and
+`.ai/reports/` are git-ignored); `state.py memory enable --share git`, in your
+own terminal, shares it through git and installs a pre-push hook that validates
+it, and `--share local` takes it back. `state.py recall --files …`
 gives an agent what the record holds about the files it is about to touch,
 within a token budget. Task ids are `T-YYYY-MM-DD-HHMM-<slug>`
 ([docs/local-memory.md](docs/local-memory.md)).
@@ -243,7 +251,7 @@ python3 -I -m unittest discover -s tests -p 'test_*.py'      # CI's serial oracl
 AI_E2E=1 python3 -I -m unittest discover -s tests -p test_end_to_end.py
 ```
 
-Sixty suites, 1217 tests, about 75 seconds in parallel. The guards against JSON fixtures for both runtimes and a
+Seventy-eight suites, 1569 tests, about 85 seconds in parallel. The guards against JSON fixtures for both runtimes and a
 golden of 1 341 recorded decisions, byte for byte, with timed cases that hold
 the hot path under its budget; the state machine, the weight, the batch loop,
 the dialog contract and the documents rule; the compact record and its
@@ -272,6 +280,8 @@ the developer's real `~/.claude` or `~/.codex`.
 | [docs/local-memory.md](docs/local-memory.md) | the compact record: task ids, packages, recall, the pre-push check, migration |
 | [docs/known-risks.md](docs/known-risks.md) | what the guards do not protect against, and what to do about it |
 | [docs/faq.md](docs/faq.md) | why something was blocked, and how to change it |
+| [docs/glossary.md](docs/glossary.md) | the words the dialog, the statusline and `/rr-status` use, and what still needs a terminal |
+| [docs/dialog-probe.md](docs/dialog-probe.md) | the checklist for Remote Control, the desktop app and the web — not yet filled |
 | [CHANGELOG.md](CHANGELOG.md) | what changed in each release, and the upgrade notes |
 | [docs/sdlc/README.md](docs/sdlc/README.md) | the spec → plan → build artefacts in a project |
 | [ROADMAP.md](ROADMAP.md) | what is decided but not built; the open rows |

package/agents/ai-reviewer.md.tmpl

@@ -76,7 +76,12 @@ previous version · state-machine transitions now reachable that should not be
 API and event contract changes · security problems · missing logging on a
 critical path · a rollback that would not actually work · scope creep and
 refactoring nobody asked for · a test weakened or skipped, or a static-analysis
-level lowered, to make CI pass.
+level lowered, to make CI pass · a new dependency without its line in the plan,
+or one the standard library or a short function would replace · padding, last
+and on a first pass only, in the lines this change added: an abstraction with
+one implementation, an option nobody sets, a block or a test that repeats
+another, lines no requirement and no test asks for — MEDIUM at most, three
+findings at most, each titled `padding:` and naming what to delete.
 
 ## Focus: security
 
@@ -117,6 +122,14 @@ verdict: pass | pass_with_findings | blockers_open
 scope_assessment: <did the change stay inside the approved plan>
 ```
 
+In full mode only, after VERDICT:
+
+```
+## READ FIRST
+- <file:line> — <why a human reads this before approving>   # at most five
+unverified: <what the review could not check, and what would check it>   # or: none
+```
+
 Label each finding with its severity's letter and a number, counted per
 severity from 1; a re-review continues the numbers already in
 `.ai/reports/<task-id>/task.md` §Review, when it has a pass.

package/ai/agents/implementer.md

@@ -37,6 +37,12 @@ do not rename anything to make the change fit.
   `project/known-risks.md`.
 - Do not reformat lines you did not change — it hides the real diff from the
   reviewer.
+- Write the simplest version that passes the step's tests. A branch, an option,
+  a parameter or a layer is added only when a requirement or a failing test
+  asks for it.
+- A new dependency is not yours to add. Ask first whether the standard library
+  or one function of about fifty lines does the job; when it does not, return
+  `SCOPE_CHANGE_REQUIRED` naming the manifest and the reason.
 
 ## Output
 

package/ai/agents/reviewer.md

@@ -20,7 +20,14 @@ usually a review that read the diff instead of the system.
 - missing logging and observability on a critical path;
 - a rollback that would not actually work;
 - scope creep and refactoring that nobody asked for;
-- a test weakened, skipped, or a static-analysis level lowered to make CI pass.
+- a test weakened, skipped, or a static-analysis level lowered to make CI pass;
+- a new dependency without its line in the plan, or one the standard library
+  or a short function would replace;
+- padding, last and on a first pass only, in the lines this change added: an
+  abstraction with one implementation, an option nobody sets, a block or a test
+  that repeats another, lines no requirement and no test asks for — MEDIUM at
+  most, three findings at most, each titled `padding:` and naming what to
+  delete.
 
 ## Boundary
 

package/bin/ansi.js

@@ -0,0 +1,12 @@
+// The installer's colour gate and the few styles the menu uses. Pure: the stream's isTTY and the
+// environment come in as parameters. Colour goes to stderr only (spec ui-first-approvals R14).
+'use strict';
+
+// Colour only on a terminal, with NO_COLOR empty or unset and TERM not dumb.
+const useColor = (isTTY, env) => isTTY === true && !env.NO_COLOR && env.TERM !== 'dumb';
+
+const CODES = { bold: '1', dim: '2', inverse: '7' };
+// text in the style when on is true, else unchanged.
+const paint = (on, style, text) => (on ? `\x1b[${CODES[style]}m${text}\x1b[0m` : text);
+
+module.exports = { useColor, paint };

package/bin/menu.js

@@ -11,10 +11,25 @@
 //   Ctrl-C/Esc/q   erases the menu, exit 130
 //   no terminal    exit 3, nothing drawn: the parent falls back to its typed prompt
 // Keys: ↑/k ↓/j (stop at the ends), Home/End, 1–9 jump to that row, Enter picks.
+//
+// A spec with any of the keys below is drawn as a wizard screen; without them it is the 4.2.0 menu.
+//   step    {"n": 3, "names": ["runtimes", "plan", "context", …]}: the stepper line, step n of names
+//   help    the help line, replacing the default
+//   back    true: ←, h or Backspace exit 4, nothing drawn, nothing on stdout
+//   multi   true: Space toggles a row, Enter confirms the set; stdout is the checked values in
+//           item order joined by "," ("" when none is checked)
+//   checked the values checked at the start (multi)
+//   color   true: styles on stderr, when ansi.useColor allows it
+// Items may carry "desc", shown under the list while the item is highlighted. → also confirms.
+// Exit codes: 0 pick, 3 no terminal, 4 back, 130 abort.
 'use strict';
+const { useColor, paint } = require('./ansi');
+
+const WIZARD_KEYS = ['help', 'multi', 'checked', 'step', 'back', 'color'];
+const isWizard = (spec) => WIZARD_KEYS.some((k) => spec[k] !== undefined);
 
 // The key, as readline's keypress event gives it, as one of the reducer's tokens (or null).
-function token(key) {
+function token(key, wizard) {
   if (!key) return null;
   if (key.ctrl && key.name === 'c') return 'abort';
   if (key.ctrl || key.meta) return null;
@@ -24,11 +39,17 @@ function token(key) {
   if (name === 'home' || name === 'end') return name;
   if (name === 'return' || name === 'enter') return 'enter';
   if (name === 'escape' || name === 'q') return 'abort';
+  if (wizard) {
+    if (name === 'left' || name === 'h' || name === 'backspace') return 'back';
+    if (name === 'right') return 'enter';
+    if (name === 'space' || name === ' ') return 'space';
+  }
   if (/^[1-9]$/.test(String(name))) return String(name);
   return null;
 }
 
-// The pure step: {index, count, done} and a token → the next state. done is null, 'pick' or 'abort'.
+// The pure step: {index, count, done, checked?} and a token → the next state. done is null, 'pick',
+// 'back' or 'abort'. checked, an array of booleans, is there only for a multi-select.
 function reduce(state, tok) {
   const last = state.count - 1;
   switch (tok) {
@@ -38,6 +59,9 @@ function reduce(state, tok) {
     case 'end': return { ...state, index: last };
     case 'enter': return { ...state, done: 'pick' };
     case 'abort': return { ...state, done: 'abort' };
+    case 'back': return { ...state, done: 'back' };
+    case 'space': return state.checked
+      ? { ...state, checked: state.checked.map((c, i) => (i === state.index ? !c : c)) } : state;
     default: {
       const n = /^[1-9]$/.test(String(tok)) ? Number(tok) : 0;
       return n >= 1 && n <= state.count ? { ...state, index: n - 1 } : state;
@@ -57,6 +81,28 @@ function lines(spec, index, columns) {
   })];
 }
 
+// The wizard screen: the stepper, a blank line, the title, the rows, a blank line, the highlighted
+// option's description and the help line. Cut to the terminal's width like lines().
+function wizardLines(spec, state, columns, color) {
+  const fit = (t) => (columns > 1 && [...t].length > columns - 1 ? [...t].slice(0, columns - 2).join('') + '…' : t);
+  const out = [];
+  if (spec.step) {
+    const names = spec.step.names.map((nm, i) => (i + 1 === spec.step.n ? paint(color, 'bold', `[${nm}]`) : nm));
+    out.push(fit(` step ${spec.step.n} of ${spec.step.names.length} · ${names.join(' › ')}`), '');
+  }
+  out.push(fit(`  ${paint(color, 'bold', spec.title)}${spec.why ? ` (${spec.why})` : ''}`));
+  const width = Math.max(...spec.items.map((it) => String(it.label).length));
+  spec.items.forEach((it, i) => {
+    const box = state.checked ? `[${state.checked[i] ? 'x' : ' '}] ` : '';
+    const row = fit(`  ${i === state.index ? '❯' : ' '} ${box}${i + 1}. ${String(it.label).padEnd(width)}${it.note ? `  ${it.note}` : ''}`);
+    out.push(i === state.index ? paint(color, 'inverse', row) : row);
+  });
+  const desc = spec.items[state.index].desc;
+  const keys = spec.help || `↑/↓ move   ${spec.multi ? 'Space toggle   ' : ''}${spec.back ? '← back   ' : ''}Enter next   Esc cancel`;
+  out.push('', ...(desc ? [fit(`  ${paint(color, 'dim', desc)}`)] : []), fit(`  ${paint(color, 'dim', keys)}`));
+  return out;
+}
+
 function main() {
   let spec;
   try { spec = JSON.parse(process.env.RISKRAILS_MENU_SPEC || ''); } catch (e) { process.exit(3); }
@@ -68,9 +114,12 @@ function main() {
   const write = (s) => process.stderr.write(s);
   let drawn = 0;
   const erase = () => { if (drawn) write(`\x1b[${drawn}A\r\x1b[J`); drawn = 0; };
-  const draw = (index) => {
+  const wizard = isWizard(spec);
+  const color = spec.color === true && useColor(process.stderr.isTTY, process.env);
+  const draw = () => {
     erase();
-    const shown = lines(spec, index, process.stderr.columns || 0);
+    const shown = wizard ? wizardLines(spec, state, process.stderr.columns || 0, color)
+      : lines(spec, state.index, process.stderr.columns || 0);
     write(shown.join('\n') + '\n');
     drawn = shown.length;
   };
@@ -83,8 +132,8 @@ function main() {
     erase();
     restore();
     if (code === 0) {
-      const why = state.index === initial && spec.why ? ` (${spec.why})` : '';
-      write(`${spec.title}: ${value}${why}\n`);
+      const why = !spec.multi && state.index === initial && spec.why ? ` (${spec.why})` : '';
+      write(`${spec.title}: ${spec.multi ? value.split(',').join(', ') : value}${why}\n`);
       process.stdout.write(value, () => process.exit(0));
     } else {
       process.exit(code);
@@ -95,22 +144,32 @@ function main() {
   const initial = Number.isInteger(spec.initial) && spec.initial >= 0 && spec.initial < spec.items.length
     ? spec.initial : 0;
   let state = { index: initial, count: spec.items.length, done: null };
+  if (spec.multi) {
+    const on = new Set((Array.isArray(spec.checked) ? spec.checked : []).map(String));
+    state.checked = spec.items.map((it) => on.has(String(it.value)));
+  }
   // A lone Esc: emitKeypressEvents without a readline interface has no escape timeout and would
   // wait for the rest of a sequence. An arrow key arrives as one chunk (ESC [ B), never as ESC alone.
   stdin.on('data', (chunk) => { if (chunk.length === 1 && chunk[0] === 0x1b) finish(130); });
   require('readline').emitKeypressEvents(stdin);
   write('\x1b[?25l');
-  draw(state.index);
+  draw();
   stdin.on('keypress', (_str, key) => {
-    const tok = token(key);
-    if (tok === null) return;
+    const tok = token(key, wizard);
+    if (tok === null || (tok === 'back' && !spec.back)) return;
     const next = reduce(state, tok);
-    if (next.done === 'pick') { state = next; finish(0, String(spec.items[state.index].value)); return; }
+    if (next.done === 'pick') {
+      state = next;
+      const set = spec.items.filter((_it, i) => state.checked && state.checked[i]).map((it) => String(it.value));
+      finish(0, state.checked ? set.join(',') : String(spec.items[state.index].value));
+      return;
+    }
     if (next.done === 'abort') { finish(130); return; }
-    if (next.index !== state.index) { state = next; draw(state.index); }
+    if (next.done === 'back') { finish(4); return; }
+    if (next.index !== state.index || next.checked !== state.checked) { state = next; draw(); }
   });
   stdin.resume();
 }
 
-module.exports = { reduce, token, lines };
+module.exports = { reduce, token, lines, wizardLines };
 if (require.main === module) main();