unitbob 0.7.12 → 0.7.13

package/README.md

@@ -1,134 +1,142 @@
 # Unitbob
 
-A living map of your app's business parts. Each important seam gets an automatic
-test — a "lamp" on the map. Green means fine, red means something broke.
+Unitbob draws a map of what your app does for people — signing in, paying,
+sending messages — and puts a lamp on each part. Behind every lamp is an
+automatic check. Green means that part still works. Red means something you
+changed broke it.
 
-Works with Ruby on Rails (RSpec), JavaScript/TypeScript (Vitest), and Python
-(pytest) projects — the guardrail tests are generated in your project's own
-language and run with its native test runner.
+You do not write the checks. Your coding assistant — Claude Code or Codex —
+does, and Unitbob keeps them honest. Your code stays on your computer; only
+the checks and their results go to Unitbob.
 
-You work through a coding agent — Claude Code or Codex both work. You need:
-Node 18+, Python 3.10+.
+Works with apps written in Ruby on Rails, JavaScript/TypeScript and Python.
+You need Node 18 or newer and Python 3.10 or newer installed.
 
 ---
 
 ## Install (once)
 
-**With a prompt:**
+Tell your assistant:
+
 ```
 Add the Unitbob plugin marketplace: sergeygershun/unitbob-connector
 Install the unitbob plugin
 ```
 
-**Claude Code (in the terminal):**
+Or, if you prefer the terminal — Claude Code:
+
 ```
 claude plugin marketplace add sergeygershun/unitbob-connector
 claude plugin install unitbob@unitbob
 ```
 
-**Codex (in the terminal):**
+Codex:
+
 ```
 codex plugin marketplace add sergeygershun/unitbob-connector
 codex plugin add unitbob@unitbob
-npx -y unitbob@0.4.4 codex-install
+npx -y unitbob@0.7.13 codex-install
 ```
 
-Start a new Claude Code or Codex thread so the installed skill and named agents
-load. After setup, the phrasings and Unitbob flow below are the same on both
-hosts.
+Then start a new chat. A chat opened before the install does not know about
+Unitbob yet. Everything below works the same in Claude Code and Codex.
 
-Codex compatibility: version 0.145.0 accepts the Unitbob custom-agent TOML files,
-but its experimental rollout budget is shared by the root and subagents rather
-than enforced separately for each named agent. No Codex version is currently
-qualified by Unitbob for a native per-agent ceiling. Before the first bounded
-role, Unitbob therefore asks whether to continue this invocation without that
-mechanical ceiling; approval is never persisted. The definitions keep the native
-budget values so a future Codex release can be qualified without introducing a
-Unitbob supervisor.
+On Codex, the assistant may ask once whether it can continue without a spending
+limit for its helpers. Answer yes; Codex cannot enforce that limit yet.
 
 ---
 
-## Full cycle
+## Protect what your app already does
 
-Just type it in the chat. There is nothing to memorise and no command to get right.
+Just say it in the chat. Nothing to memorise, no command to get right.
 
 | Step | Say this |
 |------|----------|
-| 1. Build the map | `Build my Unitbob map` |
-| 2. Generate the tests | `Generate the guardrail tests` |
-| 3. Fix a red lamp | `Fix guardrail <id>` |
-| 4. Open the map | `Open my Unitbob map` |
+| 1. Draw the map | `Build my Unitbob map` |
+| 2. Write the checks | `Generate the guardrail tests` |
+| 3. Look at the map | `Open my Unitbob map` |
+| 4. Fix a red lamp | `Fix guardrail <id>` — the id is written on the lamp |
 
-Step 2 lights the lamps by itself: generating the tests also runs them and sends
-the results. You do not have to ask for a run to see the first result.
+Step 2 also runs the checks, so the lamps light up right away. Later, whenever
+you want to know whether your latest changes broke anything, say `Run the
+checks`.
 
-Say `Run the checks` later, whenever you want the lamps refreshed against your
-current code — or to finish the job if a generation was interrupted after the
-tests were saved but before they ran.
+Your project connects itself to Unitbob the first time. There is nothing to
+set up by hand.
 
-In Claude Code there are also `/unitbob:map`, `/unitbob:suite` and friends, but
-they work only in a terminal session started after the plugin was installed — in
-a browser or desktop window they are not recognised at all. The phrasings above
-work everywhere, so they are the ones documented here.
+---
+
+## Build something new
+
+The steps above protect what your app does today. When you want to add
+something new, Unitbob can protect the new part too — before it exists. Then
+"done" is not a feeling; it is the checks turning green.
+
+Do steps 1 and 2 above first. Then, in the chat, in this order:
+
+| Step | Say this | What happens |
+|------|----------|--------------|
+| 1. Name it | `I want to add <feature>` | Unitbob writes down what you want and which parts of the map it may touch. You get a link to the feature's page. |
+| 2. Talk it through | `Let's talk through <feature>` | The assistant asks a few numbered questions about how the feature should behave — in plain words, with options and a recommendation. Answer with a letter, a word, or `do as you recommend`. Then it shows you the list of things that will be true when the feature is done and asks: is this it? Say `yes`. |
+| 3. Write the checks | `Write the checks for <feature>` | Each item from that list becomes a check. They are all red now — on purpose, the feature is not built yet. |
+| 4. Build it | `Build <feature>` | Ordinary work in the same chat. Say `Run the checks` at any time to see how many of the feature's checks already pass, and whether anything else broke. |
+| 5. Wrap up | `I'm done with <feature>` | The checks run once more, a second assistant reads them over, and you get the link to the feature's page. |
+| 6. Finish | Press **Finish this feature** on that page | Only you can press it, and only when everything is green. The feature gets its own lamp on the map, already green. |
+
+Good to know:
+
+- **If the button is grey, the page says why** — a check of the feature still
+  fails, the checks have not been read over yet, or something you said must
+  keep working is red.
+- **A red lamp you expected is fine.** If in step 2 you said a part would
+  change, its row on the feature page is amber, not red, with a button
+  `Accept the new behaviour`. Press it and it is green again. A red lamp you
+  did not expect is shown too, with the usual `Fix this`.
+- **The checks say exactly what you agreed to in step 2.** Nobody can quietly
+  bend them to fit the code. If you change your mind about the feature, say
+  `Let's talk through <feature>` again and the checks are rewritten.
+- **Work in your project's main folder.** Unitbob keeps the checks in a folder
+  called `.unitbob` next to your code. A copy of the project in another folder
+  does not have it.
+- **After Finish, nothing more to do.** From now on the feature's checks run
+  with all the others.
 
 ### If the assistant says it cannot find the Unitbob instructions
 
-A session that started *before* the plugin was installed does not pick up the
-skill, so the assistant has nothing to follow. Restarting the session is the
-clean fix. If that is inconvenient, the instructions are ordinary files on disk
-and the assistant can read them directly — tell it:
+The chat was started before the plugin was installed. Start a new chat. If you
+would rather not, tell the assistant:
 
 ```
 Read ~/.claude/plugins/cache/unitbob/unitbob/<version>/skills/unitbob/SKILL.md
 and follow the workflow it names for this job.
 ```
 
-`<version>` is whatever `claude plugin list` reports (for example `0.3.2`). The
-workflow files sit next to it under `workflows/`, one per job, and each is
-self-contained — that is what they are designed for.
-
----
-
-## How to read it
-
-- **Green lamp** — the behavior works.
-- **Red lamp** — something the structure relied on broke. Copy its `id` and run
-  step 3.
-- The project links itself by folder name — nothing to set up by hand.
+`<version>` is the number that `claude plugin list` shows.
 
 ---
 
-## If your tests only run inside Docker
+## If your app only runs inside Docker
 
-Some projects keep the code on this machine and everything that runs it — the
-interpreter, the packages, the database — inside a container. Name that
-container in `.unitbob.json` and Unitbob starts the project's own commands in
-there:
+Some projects keep the code on your computer but run it inside a Docker
+container. Tell Unitbob the container's name in the file `.unitbob.json` in
+your project folder:
 
 ```json
 { "server": "…", "repo_id": 3, "token": "…",
   "exec": { "docker": { "container": "myapp-web-1" } } }
 ```
 
-Nothing else changes. Files are still read and written here, and the path inside
-the container is worked out from the container's own mounts, so there is nothing
-else to configure. Leave the field out and everything runs on this machine,
-exactly as before.
-
-The project folder has to be **mounted** into the container rather than copied
-into the image — which it already is in any setup where you can edit a file and
-see the change. If it is not, Unitbob says so and stops before writing anything.
-
-Known limits of running in a container, all of them deliberate for now:
-
-- **A run that times out can leave a process alive inside the container.** The
-  timeout stops the `docker exec`, not necessarily what it started. A report
-  such a process writes afterwards is never counted as a later run's result.
-- **On a Linux host, files the container writes belong to `root`.** Unitbob does
-  not map users: guessing there breaks images that installed their packages as a
-  user of their own.
-- **Only a container that is already running.** A project whose tests go through
-  `docker compose run --rm` is not supported yet.
-- **Review at a fixed revision is not supported with a container.** It works in
-  a git worktree under the system's temporary directory, which is outside the
-  mount. Ordinary review works in the project itself and is unaffected.
+Keep the other three values as they are; Unitbob wrote them. Now the checks
+run inside the container. Without that line everything runs on your computer,
+as before.
+
+This works only when the project folder is shared with the container — which
+it already is if editing a file on your computer changes the running app. If
+it is not, Unitbob tells you and stops.
+
+A few things Unitbob does not do in a container yet:
+
+- The container has to be running already; Unitbob does not start it.
+- On Linux, files written from inside the container belong to `root`.
+- If a check takes too long and is stopped, the container may keep running it
+  in the background for a while.

package/dist/cli.js

@@ -73,7 +73,9 @@ Verbs:
                        Internal: run the suite you just wrote, before publishing it, with the same runner
                        that will run it afterwards. No argument runs every branch the build asked for;
                        --feature runs one feature's checks alone, by their tag.
-  fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
+  fix-prepare [<id>]   Without an id: every red guard on both maps, with its suite digest and history — the
+                       list a fix starts from. With an id: the per-capability repair packet for one
+                       structural guard (spec 26).
   contract-prompt <digest>|feature:<id> <test_id> [fix|accept]
                        Internal: fetch the fix/accept brief for one red check on either map — or, with
                        feature:<id>, the fix brief for a feature's own failing checks.

package/dist/verbs/fixPrepare.js

@@ -1,20 +1,32 @@
 import { writeFixRequest } from "../files/fix.js";
 import { Wire } from "../wire.js";
-// Fetch the per-capability repair packet and write the host's task to
-// `.unitbob/fix/request.json`. No recipe fetch, no upload — the host reads its own
-// source and the local spec file, then either fixes code (next `/unitbob check`
-// shows the result) or accepts the change and republishes the suite (spec 26). A
-// 422 from the server (non-failed / stale / no suite) surfaces via WireError;
-// nothing is written.
+// Two forms, one verb.
+//
+// Without an id (spec 54-1): print the list a fix starts from — every red guard
+// of both maps under the digest it is red on, with the line that says whether
+// it ever passed on that suite. The server words it; the connector prints it
+// as it is. Nothing is written: the list is read, the brief comes next from
+// `contract-prompt` with the digest copied off this list.
+//
+// With an id (spec 26): fetch the per-capability repair packet and write the
+// host's task to `.unitbob/fix/request.json`. No recipe fetch, no upload — the
+// host reads its own source and the local spec file, then either fixes code
+// (next `/unitbob check` shows the result) or accepts the change and
+// republishes the suite. A 422 from the server (non-failed / stale / no suite)
+// surfaces via WireError; nothing is written.
 export async function fixPrepare(config, args = [], deps) {
-    const interfaceId = (args[0] ?? '').trim();
-    if (!interfaceId)
-        throw new Error('Usage: unitbob fix-prepare <interface_id>');
     const d = {
+        getRedList: () => new Wire(config).getRedList(),
         getFixPacket: (id) => new Wire(config).getFixPacket(id),
         stdout: process.stdout,
         ...deps,
     };
+    const interfaceId = (args[0] ?? '').trim();
+    if (!interfaceId) {
+        const list = await d.getRedList();
+        d.stdout.write(`${list.message}\n`);
+        return;
+    }
     const packet = await d.getFixPacket(interfaceId);
     writeFixRequest(config.projectRoot, interfaceId, packet);
     d.stdout.write(`${packet.message}\n`);

package/dist/wire.js

@@ -159,6 +159,15 @@ export class Wire {
         await this.ensureOk(res, `PUT ${this.repoPath('suite_build')}`);
         return (await res.json());
     }
+    // GET /repos/:id/red_lamps — the red list (spec 54-1). No parameters: the
+    // server names the current version of each map itself, which is the whole
+    // point — a fix no longer guesses a digest.
+    async getRedList() {
+        const url = this.repoPath('red_lamps');
+        const res = await this.send('GET', url);
+        await this.ensureOk(res, `GET ${url}`);
+        return (await res.json());
+    }
     // GET /repos/:id/fix_packet?interface_id= — the per-capability repair packet.
     // Relayed down for the host to fix code or accept the change; 422 (non-failed /
     // stale / no suite) surfaces as a WireError carrying the server's business reason.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.7.12",
+  "version": "0.7.13",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {

package/plugin/codex/agents/suite-repair-worker.toml

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.7.12 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.13 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded