unitbob 0.3.2 → 0.3.4

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/surfaces/routeInventory.js

@@ -403,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
@@ -150,11 +193,22 @@ function checkSurfaceCoverage(row, id, expected, suiteText, add) {
         named.add(scenario);
         surfaces.filter((s) => typeof s === 'string').forEach((s) => reached.add(s));
     }
-    const missed = expected.surfaces.filter((surface) => !reached.has(surface));
+    // 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(', ')}.`);
+        add(`${id} surface_coverage accounts for no scenario at ${missed.join(', ')}` +
+            ' — drive it, or declare it unreachable with a business reason.');
     }
-    const foreign = [...reached].filter((surface) => !expected.surfaces.includes(surface));
+    // 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.`);
     }
@@ -173,6 +227,41 @@ function checkSurfaceCoverage(row, id, expected, suiteText, add) {
         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) {
@@ -301,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.2",
+  "version": "0.3.4",
   "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": {