unitbob 0.3.1 → 0.3.3

package/README.md

@@ -55,6 +55,22 @@ they work only in a terminal session started after the plugin was installed —
 a browser or desktop window they are not recognised at all. The phrasings above
 work everywhere, so they are the ones documented here.
 
+### 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:
+
+```
+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

package/dist/cli.js

@@ -14,6 +14,7 @@ import { ensureLinked } from "./link.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
 import { run, runOnly } from "./verbs/run.js";
+import { runLocal } from "./verbs/runLocal.js";
 import { init } from "./verbs/init.js";
 import { mapPrepare } from "./verbs/mapPrepare.js";
 import { extractSurfaces } from "./verbs/extractSurfaces.js";
@@ -48,6 +49,8 @@ Verbs:
                        uploading. Reports every problem at once; put-suite-build runs it too.
   put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
                        then run every branch it published and report the server's results.
+  run-local [branch]   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.
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
   contract-prompt <digest> <test_id> [fix|accept]
                        Internal: fetch the fix/accept brief for one red check on either map.
@@ -113,6 +116,9 @@ export async function main(argv, deps = { ensureLinked }) {
             case 'contract-prompt':
                 await contractPrompt(await linked(), args);
                 return 0;
+            case 'run-local':
+                await runLocal(await linked(), args);
+                return 0;
             case 'run':
             case 'check':
                 await run(await linked(), args);

package/dist/files/guardrails.js

@@ -29,10 +29,22 @@ export function assertGuardrailPath(path) {
 // own RSpec setup when one exists; boots the Rails test environment directly
 // when none does. Both branches refuse a non-test environment — before boot
 // via ENV (nothing touched yet), after boot via Rails.env (config overrides).
+//
+// `rspec/core` is required first because this file has two callers and only one
+// of them is the `rspec` binary. The run loads it through that binary, which has
+// already required rspec-core by the time it reads a spec file; the boot check
+// of spec 32-6 loads it through a bare `ruby -e`, which has not. A Rails-
+// generated `spec/rails_helper.rb` calls `RSpec.configure` (inside `spec_helper`)
+// before it requires `rspec/rails`, so under the bare interpreter it died on
+// `uninitialized constant RSpec` — a healthy application declared broken, and its
+// owner told to edit a tracked file the recipes forbid touching. That made the
+// check stricter than the run it predicts, which is the one rule 32-6 is built
+// on. Under the binary this line is a no-op. Found on the a2time run 2026-08-04.
 export const UNITBOB_HELPER_RB = `# frozen_string_literal: true
 # Written by the unitbob connector on every materialization — do not edit.
 ENV['RAILS_ENV'] ||= 'test'
 abort 'unitbob_helper: refusing to run against a non-test environment' unless ENV['RAILS_ENV'] == 'test'
+require 'rspec/core'
 root = File.expand_path('../..', __dir__)
 if File.exist?(File.join(root, 'spec', 'rails_helper.rb'))
   # The project has its own RSpec setup — respect it (factories, cleaners…).

package/dist/runner/provision.js

@@ -31,6 +31,25 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     if (!existsSync(sidecarGemfile) || readFileSync(sidecarGemfile, 'utf8') !== sidecarContent) {
         writeFileSync(sidecarGemfile, sidecarContent);
     }
+    // Start the sidecar from the project's own resolution, so bundler adds
+    // cucumber and leaves everything else on the versions the project already
+    // runs. Without a starting lock it resolves the whole graph from scratch: on
+    // a2time that moved 285 gems, handed the sidecar carrierwave 2.2.0 where the
+    // project pins 2.2.6, and Rails then would not load at all (`cannot load such
+    // file -- mimemagic/overlay`). The behavioral branch could not start, and the
+    // boot check of 32-6 had said `ok` — truthfully, because it only ever asks the
+    // structural runner. Found on the a2time run 2026-08-04.
+    //
+    // Copied on every provision rather than only when missing. A lock seeded once
+    // goes stale the moment the project upgrades a gem — the sidecar Gemfile
+    // inherits the project's *Gemfile* through `eval_gemfile`, never its lock, so
+    // nothing would pull the new version through and the drift this exists to
+    // prevent comes back slowly instead of at once. `bundle install` already runs
+    // on every provision, so re-adding cucumber to a fresh copy costs nothing new.
+    const projectLock = join(projectRoot, 'Gemfile.lock');
+    if (existsSync(projectLock)) {
+        writeFileSync(join(behavioralDir, 'Gemfile.lock'), readFileSync(projectLock, 'utf8'));
+    }
     const gemfileRel = '.unitbob/behavioral/Gemfile';
     const env = { BUNDLE_GEMFILE: gemfileRel };
     // Try project local bin/bundle, then bundle

package/dist/surfaces/routeInventory.js

@@ -25,7 +25,7 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
     const asked = await askTheRouter(projectRoot, deps);
     if ('reason' in asked)
         return silent(projectRoot, asked.reason, asked.detail);
-    const rows = parseExpandedRoutes(asked.result.stdout);
+    const rows = parseRouterAnswer(asked.result.stdout);
     // Zero rows is far likelier to mean "this output is not what we know how to
     // read" than "this application has no addresses". Claiming the second would
     // hand the map a confident, empty answer, so we claim neither.
@@ -43,7 +43,7 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
     const path = routeInventoryPath(projectRoot);
     try {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, `${JSON.stringify({ declared_by: 'rails routes', environment: asked.environment, surfaces }, null, 2)}\n`);
+        writeFileSync(path, `${JSON.stringify({ declared_by: 'rails router', environment: asked.environment, surfaces }, null, 2)}\n`);
     }
     catch (err) {
         // A read-only checkout or a full disk is not a reason to take the whole map
@@ -63,21 +63,13 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
 // first answer is decided there; only "this environment refused to load" is
 // worth asking again, because that is the one failure an environment can own.
 async function askTheRouter(projectRoot, deps) {
-    const first = await runRailsRoutes(projectRoot, deps, 'test');
+    const first = await askRouterOnce(projectRoot, deps, 'test');
     if (first === null) {
         // The command is not on this machine. A second environment cannot conjure it.
         return { reason: 'app_did_not_load', detail: 'the command did not run on this machine' };
     }
     if (first.code === 0)
         return { result: first, environment: 'test' };
-    // Rails learned `--expanded` in 5.1. Older ones reject the flag before they
-    // load anything, and saying "your application did not load" there sends
-    // somebody to debug an application that is perfectly fine — the same reason
-    // the boot check grew `runner_too_old` rather than calling vitest missing.
-    // The flag is refused the same way in every environment, so there is nothing
-    // to retry.
-    if (rejectedTheFlag(first))
-        return { reason: 'router_too_old' };
     // No exit code at all means the process was stopped rather than finished —
     // our own timeout, or a signal from outside. An application too large to
     // enumerate its routes in the time we allow has told us nothing about whether
@@ -85,12 +77,12 @@ async function askTheRouter(projectRoot, deps) {
     // Retrying would spend the same budget twice for the same silence.
     if (first.code === null)
         return { reason: 'did_not_finish' };
-    const second = await runRailsRoutes(projectRoot, deps, 'default');
+    const second = await askRouterOnce(projectRoot, deps, 'default');
     if (second !== null && second.code === 0)
         return { result: second, environment: 'default' };
     if (second !== null && second.code === null)
         return { reason: 'did_not_finish' };
-    // `rails routes` loads the application, so running it *is* the check: an app
+    // Asking the router loads the application, so asking it *is* the check: an app
     // that will not boot cannot print its routes. We do not ask the boot check
     // from spec 32-6 first — that would boot the app twice to learn the same
     // thing — but we do answer in its currency, quoting the runner's own first
@@ -139,21 +131,18 @@ function becauseOf(result) {
     switch (result.reason) {
         case 'unsupported_stack':
             return 'this project has no router Unitbob can ask yet (Rails is the only one so far)';
-        case 'router_too_old':
-            return '`rails routes --expanded` needs Rails 5.1 or newer, and this Rails refused the flag ' +
-                '(nothing is wrong with the application)';
         case 'app_did_not_load':
-            return `\`rails routes\` did not get through — ${result.detail}`;
+            return `the router could not be asked — ${result.detail}`;
         case 'did_not_finish':
             // No exit code means stopped, and we do not know by whom: our own
             // ${minutes}-minute limit, or something outside this process. Naming only
             // the timeout would put a duration on a run that may have been killed in
             // ten seconds — a claim we cannot make.
-            return `\`rails routes\` was stopped before it finished — either it ran past the ` +
+            return `the router was not done answering — either it ran past the ` +
                 `${ROUTES_TIMEOUT_MS / 60_000}-minute limit or something else killed it (nothing here says the ` +
                 'application is unhealthy)';
         case 'no_routes':
-            return '`rails routes` printed nothing this version knows how to read';
+            return 'the router answered in a shape this connector could not read';
         case 'could_not_write':
             return `the inventory could not be written — ${result.detail}`;
     }
@@ -164,17 +153,47 @@ function plural(count, one, many) {
 function looksLikeRails(projectRoot) {
     return existsSync(join(projectRoot, 'config', 'routes.rb'));
 }
-// `--expanded` rather than the default table: one field per line, so nothing
-// depends on guessing column widths, and a long URI pattern cannot run into its
-// neighbour. `test` is asked first because that is the environment the guardrail
-// suite boots in, so the routes read there are the routes the suite would see;
+// The question, asked of the router object rather than of the `rails routes`
+// command line. `--expanded` was the earlier reading, and it cost this project
+// its whole inventory on the a2time run: the flag arrived in Rails 5.1, that
+// application runs 5.0, and 194 addresses went back to being typed out by hand —
+// the exact work this module exists to remove. `routes` also prints for people,
+// so its field names move between versions (`URI` in Rails 7, `URI Pattern`
+// before it) and the reader had to know both.
+//
+// `Rails.application.routes.routes` has been the same object since Rails 3 and
+// answers in a shape we choose. Nothing here is version-specific except the one
+// thing that genuinely changed: `verb` was a Regexp before Rails 5 and is a
+// String after, so both are reduced to the same letters.
+//
+// The answer is printed behind a sentinel because an application is free to
+// write to stdout while it boots — an initializer with a banner, a deprecation
+// notice — and none of that is ours to parse.
+const ROUTES_SENTINEL = 'UNITBOB_ROUTES ';
+// One address per line rather than one array holding all of them: a project with
+// five hundred routes should not be a single line, and a line cut in half loses
+// one address instead of every address. That cannot lose addresses quietly —
+// output is only ever cut short when the process was killed, and a run that did
+// not exit cleanly is refused before anyone reads what it printed.
+const ROUTES_SCRIPT = `require 'json'
+Rails.application.routes.routes.each do |r|
+  next if r.respond_to?(:internal) && r.internal
+  STDOUT.print("${ROUTES_SENTINEL}" + JSON.generate(
+    'verb' => r.verb.is_a?(String) ? r.verb : r.verb.to_s.gsub(%r{[$^/]}, ''),
+    'path' => r.path.spec.to_s,
+    'controller' => r.defaults[:controller],
+    'action' => r.defaults[:action]
+  ) + "\\n")
+end`;
+// `test` is asked first because that is the environment the guardrail suite
+// boots in, so the routes read there are the routes the suite would see;
 // `default` means we leave RAILS_ENV alone and take whatever the project's own
 // setup chooses.
-async function runRailsRoutes(projectRoot, deps, environment) {
+async function askRouterOnce(projectRoot, deps, environment) {
     const local = join(projectRoot, 'bin', 'rails');
     const [command, args] = existsSync(local)
-        ? [local, ['routes', '--expanded']]
-        : ['bundle', ['exec', 'rails', 'routes', '--expanded']];
+        ? [local, ['runner', ROUTES_SCRIPT]]
+        : ['bundle', ['exec', 'rails', 'runner', ROUTES_SCRIPT]];
     try {
         return await deps.runCmd(command, args, {
             cwd: projectRoot,
@@ -187,33 +206,23 @@ async function runRailsRoutes(projectRoot, deps, environment) {
         return null; // the command is not on this machine
     }
 }
-// Ruby's own OptionParser wording, and Thor's — whichever layer of the `rails`
-// command line sees the flag first. Both name the flag they refused, and the
-// name has to be part of the match: "invalid option" is ordinary Ruby wording
-// that also turns up inside a failing initializer, and reading that as an old
-// Rails would tell somebody their application is fine while it is broken —
-// exactly the wrong-errand this reason exists to prevent, pointing the other way.
-function rejectedTheFlag(result) {
-    return /(?:invalid option|unknown switches?|unrecognized option)[^\n]*expanded/i.test(`${result.stdout}\n${result.stderr}`);
-}
-// The `--expanded` record:
-//
-//   --[ Route 1 ]------------------------------
-//   Prefix            | settings
-//   Verb              | GET
-//   URI               | /settings(.:format)
-//   Controller#Action | settings#index
-//
-// The path field is `URI` on Rails 7 and `URI Pattern` on older versions — both
-// are read, because which one we get is decided by the user's Gemfile. Fields we
-// do not use (Prefix, Source Location) are ignored rather than rejected, so a
-// newer Rails printing more of them still reads.
-export function parseExpandedRoutes(stdout) {
+// The router's answer: the sentinel lines, in among whatever the application
+// printed while booting. Lines are picked out by their prefix rather than by
+// position, so a banner or a deprecation notice costs nothing.
+export function parseRouterAnswer(stdout) {
     const rows = [];
     const seen = new Set();
-    let record = {};
-    const flush = () => {
-        for (const row of rowsFrom(record)) {
+    for (const line of stdout.split('\n')) {
+        if (!line.startsWith(ROUTES_SENTINEL))
+            continue;
+        let declared;
+        try {
+            declared = JSON.parse(line.slice(ROUTES_SENTINEL.length));
+        }
+        catch {
+            continue; // not the shape we know how to read
+        }
+        for (const row of rowsFrom((declared ?? {}))) {
             const key = `${row.verb} ${row.path}`;
             // The same address can be drawn under several prefixes. It is one address.
             if (seen.has(key))
@@ -221,37 +230,26 @@ export function parseExpandedRoutes(stdout) {
             seen.add(key);
             rows.push(row);
         }
-        record = {};
-    };
-    for (const line of stdout.split('\n')) {
-        if (/^--\[ Route /.test(line)) {
-            flush();
-            continue;
-        }
-        const separator = line.indexOf('|');
-        if (separator === -1)
-            continue;
-        record[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
     }
-    flush();
     return rows;
 }
 function rowsFrom(record) {
-    const pattern = record.URI ?? record['URI Pattern'];
-    const verb = record.Verb ?? '';
+    const pattern = typeof record.path === 'string' ? record.path : '';
+    const verb = typeof record.verb === 'string' ? record.verb : '';
     // No verb means a mounted Rack application (`mount Sidekiq::Web at: '/sidekiq'`),
     // not an address of this application. Its own routes live in its own router.
     if (!pattern || !verb)
         return [];
-    const handler = /^([A-Za-z0-9_/]+)#([A-Za-z0-9_]+)$/.exec(record['Controller#Action'] ?? '');
+    const controller = typeof record.controller === 'string' ? record.controller : undefined;
+    const action = typeof record.action === 'string' ? record.action : undefined;
     const path = pattern.replace(/\(\.:format\)$/, '');
-    // `match via: [:get, :post]` prints one record with both verbs. They are two
-    // addresses, and the map should say so.
+    // `match via: [:get, :post]` is one route object carrying both verbs. They are
+    // two addresses, and the map should say so.
     return verb.split('|').map((one) => ({
         verb: one.trim(),
         path,
-        controller: handler?.[1],
-        action: handler?.[2],
+        controller,
+        action,
     }));
 }
 function graphNodes(projectRoot) {
@@ -405,7 +403,7 @@ export function inventoryProblems(inventory, surfaces) {
 // either printed by the router or copied out of the graph. A blank is not a gap
 // to be helpfully filled — an invented `source_file` is the same failure as an
 // invented address, one field over, and a `handler_symbol` swapped for another
-// node that happens to exist passes the host's check while sending spec 35's
+// node that happens to exist passes the host's check while sending spec 36's
 // trace into the wrong code.
 const LINK_FIELDS = ['source_file', 'handler_symbol'];
 // Not a link and nothing downstream reads it — but spec 32-7 took the authoring

package/dist/verbs/putSuiteBuild.js

@@ -46,11 +46,12 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // batch. That also bounds what a false positive in a local check can cost —
     // one branch, with the peer still going up and the server still the authority.
     const problemsFor = new Map();
-    for (const problem of collectBuildProblems(request, outputs)) {
+    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
         problemsFor.set(problem.branch, [...(problemsFor.get(problem.branch) ?? []), problem.message]);
     }
     for (const output of outputs) {
         const failed = problemsFor.get(output.suite_kind);
+        problemsFor.delete(output.suite_kind);
         if (failed) {
             blocked.push({ suite_kind: output.suite_kind, status: BLOCKED_STATUS, error: formatBranchProblems(failed) });
             continue;
@@ -80,6 +81,14 @@ export async function putSuiteBuild(config, _args = [], deps) {
             },
         });
     }
+    // What is left in `problemsFor` belongs to a branch the loop above never
+    // reached, because the answer has no entry for it at all. It has nothing to
+    // upload and nothing to roll back, so it costs its peer nothing — but it is
+    // exactly the branch that used to leave no trace anywhere, and the one line it
+    // prints here is the whole point of noticing it (spec 32-6, a2time 2026-08-04).
+    for (const [suiteKind, messages] of problemsFor) {
+        blocked.push({ suite_kind: suiteKind, status: BLOCKED_STATUS, error: formatBranchProblems(messages) });
+    }
     // Every branch is blocked, so there is nothing to upload. Asking the server to
     // publish an empty batch would turn a local, already-explained problem into a
     // wire error with a worse message.

package/dist/verbs/run.js

@@ -118,7 +118,10 @@ async function buildRunPayload(config, d, item) {
     }
     return { suite_digest: item.suite_digest, run_result: report };
 }
-function runStructuralByRunner(projectRoot, runner, suitePath) {
+// Exported for `run-local`, which runs these same strategies against the files
+// the host just wrote rather than against a published suite. One dispatch table,
+// so the command the loop iterates on is the command that runs after publishing.
+export function runStructuralByRunner(projectRoot, runner, suitePath) {
     switch (runner) {
         case 'rspec':
             return runRspecSuite(projectRoot, suitePath);

package/dist/verbs/runLocal.js

@@ -0,0 +1,129 @@
+import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { validateStack } from "../runner/precheck.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { runStructuralByRunner } from "./run.js";
+const OUTPUT_TAIL_CHARS = 4000;
+export async function runLocal(config, args = [], deps) {
+    const d = {
+        runStructural: runStructuralByRunner,
+        runBehavioral: runBddSuite,
+        validateStack,
+        stdout: process.stdout,
+        ...deps,
+    };
+    const request = readSuiteBuildRequest(config.projectRoot);
+    const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
+    const wanted = selectBranches(request, args);
+    for (const suiteKind of wanted) {
+        d.stdout.write(`\n── ${suiteKind} ──\n`);
+        // An entry that exists but will not parse is a different problem from an
+        // entry that is not there, and it is the one worth catching early: the file
+        // it names is usually missing from disk, which the runner would otherwise
+        // discover as a confusing "no tests" halfway through the loop.
+        const broken = unreadable.find((entry) => entry.suite_kind === suiteKind);
+        if (broken) {
+            d.stdout.write(`Cannot run this branch — its entry in your answer could not be read: ${broken.message}\n`);
+            continue;
+        }
+        await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind));
+    }
+}
+// Which branches to run. No argument runs every branch the request asked for —
+// the same "one suite, one run" shape both recipes insist on, so the default
+// never teaches the habit the recipes forbid. A named branch is for the repair
+// loop, where re-running the finished peer is pure cost.
+function selectBranches(request, args) {
+    const all = request.branches.map((branch) => branch.suite_kind);
+    const named = args.filter((arg) => !arg.startsWith('-'));
+    if (named.length === 0)
+        return all;
+    const unknown = named.filter((name) => !all.includes(name));
+    if (unknown.length > 0) {
+        throw new Error(`This suite build has no branch called ${unknown.join(', ')}. It asked for: ${all.join(', ')}.`);
+    }
+    return named;
+}
+async function runOneBranch(config, d, suiteKind, output) {
+    // Nothing written for this branch yet. That is the ordinary state halfway
+    // through a build, not an error — say what is missing and move to the peer.
+    if (!output) {
+        d.stdout.write(`Nothing to run: your answer has no entry for this branch yet. Write its suite under ` +
+            `${branchRoot(config, suiteKind)} and add its entry to the answer, then run this again.\n`);
+        return;
+    }
+    if (output.build_error) {
+        d.stdout.write(`Not built, by your own answer: ${output.build_error.message}\n`);
+        return;
+    }
+    let runner;
+    let suitePath;
+    try {
+        runner = branchRunner(output);
+        suitePath = mainPathOf(output);
+    }
+    catch (err) {
+        d.stdout.write(`Cannot run this branch: ${err.message}\n`);
+        return;
+    }
+    const check = d.validateStack(config.projectRoot, runner);
+    if (!check.ok) {
+        d.stdout.write(`Cannot run this branch: ${check.message ?? `this project does not match "${runner}".`}\n`);
+        return;
+    }
+    let result;
+    try {
+        result =
+            suiteKind === 'behavioral'
+                ? await d.runBehavioral(config.projectRoot, runner, suitePath)
+                : await d.runStructural(config.projectRoot, runner, suitePath);
+    }
+    catch (err) {
+        d.stdout.write(`The runner could not start: ${err.message}\n`);
+        return;
+    }
+    d.stdout.write(report(result));
+}
+// The command first, and always — including on a green run. It is the answer to
+// "how do I run just this one file again", which is the question the whole
+// iteration loop is made of, and printing it only on failure would hide it at
+// exactly the moment someone starts trusting the loop.
+function report(result) {
+    const lines = [
+        `ran: ${[result.command, ...result.args].join(' ')}`,
+        `exit code: ${result.code}`,
+    ];
+    if (result.report) {
+        lines.push(`machine-readable report: ${result.resultPath}` +
+            ' — the whole run in one file, if the console output is too long to read.');
+    }
+    else {
+        lines.push(`no report at ${result.resultPath} — the run produced none, which usually means it died before` +
+            ' the first test rather than that the tests failed.');
+    }
+    const tail = outputTail(result);
+    if (tail)
+        lines.push('', tail);
+    return `${lines.join('\n')}\n`;
+}
+function outputTail(result) {
+    const bits = [];
+    if (result.stderr.trim())
+        bits.push(result.stderr.trim());
+    if (result.stdout.trim())
+        bits.push(result.stdout.trim());
+    const joined = bits.join('\n');
+    return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
+}
+// The suite blob's own project-relative path, exactly as the runners expect it.
+function mainPathOf(output) {
+    const file = output.suite_file;
+    const path = file?.path;
+    if (typeof path !== 'string' || !path) {
+        throw new Error('this branch names no suite file to run.');
+    }
+    return path;
+}
+function branchRoot(config, suiteKind) {
+    const request = readSuiteBuildRequest(config.projectRoot);
+    return request.branches.find((branch) => branch.suite_kind === suiteKind)?.path_root ?? `.unitbob/${suiteKind}/`;
+}

package/dist/verbs/suitePrepare.js

@@ -147,7 +147,9 @@ export async function suitePrepare(config, args = [], deps) {
         : '`unitbob put-suite-build`';
     actual.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
     actual.stdout.write(`Next: build ${branches.length === 1 ? 'the' : 'both'} peer ${branches.length === 1 ? 'suite' : 'suites'} (${kinds}) following each branch's \`recipe\` and \`assignment\`, ` +
-        `write your answer to ${request.output_path} as a branches array, run each locally, repair broken harness steps while application failures remain red, ` +
+        `write your answer to ${request.output_path} as a branches array — one entry per branch named above, and a branch you cannot ` +
+        `finish says so in its own entry rather than being left out of the array. Run each locally with \`unitbob run-local\` (the same ` +
+        `runner that runs after publishing, so you never have to guess the command), repair broken harness steps while application failures remain red, ` +
         `then run ${nextCommand}.\n`);
     // A fixable runner blocker is not a failure: the structural suite still builds this run. Tell the
     // vibecoder the one command that unblocks the behavioral peer, then re-run suite-prepare.

package/dist/verbs/validateBuild.js

@@ -4,7 +4,7 @@ import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/
 // both sides copy verbatim — so nothing here has to know whether this branch's
 // ids are called `interface_id` or `capability_id`.
 const CONTRACT_PREFIX = 'contract:';
-export function collectBuildProblems(request, outputs) {
+export function collectBuildProblems(request, outputs, unreadable = []) {
     const problems = [];
     const branchFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch]));
     for (const output of outputs) {
@@ -19,8 +19,51 @@ export function collectBuildProblems(request, outputs) {
         checkRunnerManifest(branch, output, add);
         checkAssignment(branch, output, add);
     }
+    problems.push(...unansweredBranches(request, outputs, unreadable));
     return problems;
 }
+// The branch that is not there at all. Every check above reads the answer and
+// asks whether it is well-formed; none of them can see a branch the answer never
+// mentions, because there is no entry to walk. So this one walks the request
+// instead — the only list that knows what was asked for.
+//
+// The a2time run of 2026-08-04 is the whole reason. Its behavioral branch was
+// prepared, half-built and abandoned for budget; the answer went up carrying the
+// structural branch alone; this check said "well-formed"; the upload published
+// one branch and said nothing about the other. Nothing anywhere recorded that a
+// second branch had ever been asked for, so the cost of the work already done on
+// it was not merely wasted, it was invisible.
+//
+// ADR 1 names this shape: a pre-check must not be *narrower* than the thing it
+// predicts. The server checks each branch it receives; what it cannot check is a
+// branch nobody sent it. That gap belongs here, where the request is still in
+// hand.
+//
+// `build_error` is the answer for a branch that could not be built, and it is
+// deliberately cheap to give — one line, no suite, never blocks the peer. This
+// does not demand the branch be built. It demands only that its absence be
+// stated rather than left as a silence that reads like success.
+//
+// A branch whose entry existed but could not be parsed is already reported as
+// unreadable by the caller; naming it "missing" too would be two complaints
+// about one mistake, and the second would send the reader looking for a second
+// problem that is not there.
+function unansweredBranches(request, outputs, unreadable) {
+    const accounted = new Set([
+        ...outputs.map((output) => output.suite_kind),
+        ...unreadable.map((entry) => entry.suite_kind),
+    ]);
+    return request.branches
+        .filter((branch) => !accounted.has(branch.suite_kind))
+        .map((branch) => ({
+        branch: branch.suite_kind,
+        message: 'the request asked for this branch and the answer has no entry for it — it is neither built nor ' +
+            'declared unbuildable. Every branch in the request gets one entry: the suite you built, or ' +
+            `{ "suite_kind": "${branch.suite_kind}", "build_error": { "message": "why not" } }. ` +
+            'Leaving it out is not the same as declining it: nothing records that this branch was ever asked ' +
+            'for, so the work already spent on it disappears without a trace.',
+    }));
+}
 // After spec 32-5 the envelope comes down from the server inside the request, so
 // there is nothing here to derive — only to confirm the host copied it. This is
 // the field most likely to be rejected after all the work is done, which is
@@ -106,7 +149,139 @@ function checkOneCase(row, id, expected, suiteText, add) {
     // as a mismatch rather than as the green it claims.
     if (suiteText && !suiteText.includes(expected.case_marker)) {
         add(`${id} is answered "covered", but its marker ${expected.case_marker} appears nowhere in the suite files.`);
+        return;
+    }
+    checkSurfaceCoverage(row, id, expected, suiteText, add);
+}
+// Which scenario reached which address. The a2time run of 2026-08-04 published
+// 97 coverage rows against 99 Scenarios: one Scenario had no row, another had a
+// row naming no address. Both mean the same thing — a Scenario that ran and
+// whose result reaches nothing on the map — and both were found by the
+// independent reviewer, hours later, doing a different job. This check was the
+// cheap place to find them and it was not looking.
+//
+// Only asked when the answer is already speaking this language: an answer with
+// no `surface_coverage` anywhere is an older map's shape, and refusing it here
+// would refuse what the server accepts. Within a branch that does declare it,
+// the rules below are the server's own, in the server's own order.
+function checkSurfaceCoverage(row, id, expected, suiteText, add) {
+    if (expected.surfaces.length === 0)
+        return;
+    const coverage = row.surface_coverage;
+    if (coverage === undefined)
+        return; // not this map's shape — the server decides
+    if (!Array.isArray(coverage)) {
+        add(`${id} is answered "covered", so its surface_coverage must be an array of {scenario, surfaces}.`);
+        return;
+    }
+    const named = new Set();
+    const reached = new Set();
+    for (const [index, item] of coverage.entries()) {
+        const entry = (item ?? {});
+        const scenario = String(entry.scenario ?? '').trim();
+        const surfaces = entry.surfaces;
+        if (!scenario || !Array.isArray(surfaces)) {
+            add(`${id} surface_coverage[${index}] must name a scenario and its surfaces.`);
+            continue;
+        }
+        if (surfaces.length === 0) {
+            add(`${id} surface_coverage names no surface for "${scenario}" — that scenario's result reaches nothing on the map.`);
+        }
+        if (suiteText && !suiteText.includes(scenario)) {
+            add(`${id} surface_coverage names "${scenario}", which appears nowhere in the suite files.`);
+        }
+        named.add(scenario);
+        surfaces.filter((s) => typeof s === 'string').forEach((s) => reached.add(s));
+    }
+    // Spec 34, decision 15: an address the suite genuinely cannot drive — a
+    // third-party OAuth callback, a vendor webhook — is declared rather than
+    // faked, and satisfies coverage without being claimed as reached. Mirrored
+    // here in the server's own shape; refusing it locally would refuse an answer
+    // the server takes, which is the one direction of drift that costs a branch.
+    const declaredUnreachable = collectUnreachable(row, id, reached, add);
+    const missed = expected.surfaces.filter((surface) => !reached.has(surface) && !declaredUnreachable.has(surface));
+    if (missed.length > 0) {
+        add(`${id} surface_coverage accounts for no scenario at ${missed.join(', ')}` +
+            ' — drive it, or declare it unreachable with a business reason.');
+    }
+    // No check here for "declares everything unreachable and drives nothing": the
+    // caller already returned when the capability's marker appears in no suite
+    // file, so a capability with no Scenario never reaches this function at all.
+    // The server refuses that state for the same reason, one rule earlier.
+    const foreign = [...reached, ...declaredUnreachable].filter((surface) => !expected.surfaces.includes(surface));
+    if (foreign.length > 0) {
+        add(`${id} surface_coverage names ${foreign.join(', ')}, which this branch's assignment does not carry.`);
+    }
+    // The other direction, and the one that found nothing on a2time because
+    // nobody asked it: a Scenario that carries the marker but appears in no row.
+    //
+    // Read off the file rather than parsed: a tag line carrying this marker, then
+    // the next line that has a colon in it, whose name is whatever follows the
+    // first colon. That holds for any Gherkin dialect, because only the keyword is
+    // translated and the colon is not. When the shape is not recognised the answer
+    // is silence — the server does parse this properly, and a guess here that says
+    // "you forgot a Scenario" about a Scenario that does not exist would cost the
+    // branch its publication.
+    const unlisted = scenarioNamesTagged(suiteText, expected.case_marker).filter((name) => !named.has(name));
+    if (unlisted.length > 0) {
+        add(`${id} surface_coverage does not account for ${unlisted.map((n) => `"${n}"`).join(', ')}.`);
+    }
+}
+// The addresses this capability says it cannot drive, each with its own reason.
+// A blanket reason covering a list is exactly the boilerplate the rule exists to
+// stop, so the reason is per address and its absence is the whole complaint.
+function collectUnreachable(row, id, reached, add) {
+    const declared = row.unreachable_surfaces;
+    if (declared === undefined)
+        return new Set();
+    if (!Array.isArray(declared) || declared.length === 0) {
+        add(`${id} unreachable_surfaces must be a non-empty array of {surface, reason} when it is present.`);
+        return new Set();
+    }
+    const surfaces = new Set();
+    for (const [index, item] of declared.entries()) {
+        const entry = (item ?? {});
+        const surface = String(entry.surface ?? '').trim();
+        if (!surface) {
+            add(`${id} unreachable_surfaces[${index}] names no surface.`);
+            continue;
+        }
+        if (!String(entry.reason ?? '').trim()) {
+            add(`${id} declares ${surface} unreachable but gives no business reason for it.`);
+            continue;
+        }
+        if (reached.has(surface)) {
+            add(`${id} both drives ${surface} in a scenario and declares it unreachable — it is one or the other.`);
+            continue;
+        }
+        if (surfaces.has(surface)) {
+            add(`${id} declares ${surface} unreachable more than once.`);
+            continue;
+        }
+        surfaces.add(surface);
+    }
+    return surfaces;
+}
+// Scenario names carrying one marker, by shape rather than by grammar. See the
+// caller for why this stays deliberately timid.
+function scenarioNamesTagged(suiteText, marker) {
+    if (!suiteText)
+        return [];
+    const lines = suiteText.split('\n');
+    const names = [];
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('@') || !trimmed.split(/\s+/).includes(`@${marker}`))
+            continue;
+        const next = lines.slice(index + 1).find((candidate) => candidate.trim().length > 0) ?? '';
+        const colon = next.indexOf(':');
+        if (colon === -1)
+            continue;
+        const name = next.slice(colon + 1).trim();
+        if (name)
+            names.push(name);
     }
+    return names;
 }
 // Which field names the id. Read off the *assignment*, where the answer is
 // exact: the id is already known (it is `contract_key` minus its prefix), so the
@@ -169,7 +344,14 @@ function assignedCases(assignment) {
         const key = row.contract_key;
         const marker = row.case_marker;
         if (typeof key === 'string' && key.startsWith(CONTRACT_PREFIX) && typeof marker === 'string') {
-            found.push({ id: key.slice(CONTRACT_PREFIX.length), contract_key: key, case_marker: marker });
+            found.push({
+                id: key.slice(CONTRACT_PREFIX.length),
+                contract_key: key,
+                case_marker: marker,
+                // Only the behavioral assignment carries addresses. Its absence is what
+                // tells the coverage check below there is nothing of that kind here.
+                surfaces: Array.isArray(row.surfaces) ? row.surfaces.filter((s) => typeof s === 'string') : [],
+            });
         }
         Object.values(row).forEach(walk);
     };
@@ -208,7 +390,7 @@ export function validateBuildProblems(config) {
     const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     return [
         ...unreadable.map((entry) => ({ branch: entry.suite_kind, message: entry.message })),
-        ...collectBuildProblems(request, outputs),
+        ...collectBuildProblems(request, outputs, unreadable),
     ];
 }
 // One branch's problems, for the line that reports it unpublished alongside its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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": {
@@ -15,7 +15,9 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
-    "test": "node --test test/*.test.ts"
+    "test": "node --test test/*.test.ts",
+    "check:release": "node scripts/check-release.mjs",
+    "hooks:install": "git config core.hooksPath hooks"
   },
   "publishConfig": {
     "access": "public"