unitbob 0.1.11 → 0.2.0

package/dist/cli.js

@@ -12,6 +12,7 @@ import { putMapBuild } from "./verbs/putMapBuild.js";
 import { suitePrepare } from "./verbs/suitePrepare.js";
 import { putSuiteBuild } from "./verbs/putSuiteBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
+import { contractPrompt } from "./verbs/contractPrompt.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
 
 Usage: unitbob <verb> [args]
@@ -25,7 +26,9 @@ Verbs:
   suite-prepare        Internal: fetch the recipe and capability assignment, write the host suite-build request.
   put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata).
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
-  check                Run the guardrail suite locally and report.
+  contract-prompt <digest> <test_id> [fix|accept]
+                       Internal: fetch the fix/accept brief for one red check on either map.
+  check                Run every Unitbob contract suite locally and report.
   run                  Alias for check.
 
 Pipeline: map and suite are built on your machine. \`*-prepare\` writes a request
@@ -69,6 +72,9 @@ async function main(argv) {
             case 'fix-prepare':
                 await fixPrepare(await ensureLinked(), args);
                 return 0;
+            case 'contract-prompt':
+                await contractPrompt(await ensureLinked(), args);
+                return 0;
             case 'run':
             case 'check':
                 await run(await ensureLinked(), args);

package/dist/files/artifactPath.js

@@ -0,0 +1,19 @@
+import { isAbsolute } from 'node:path';
+// The one rule for whether a host-provided suite file path is safe to write:
+// relative, anchored under the given `.unitbob/<kind>/` root, no traversal.
+// Both contract systems (spec 32) share it — structural under
+// `.unitbob/structural/`, behavioral under `.unitbob/behavioral/`. It mirrors
+// the Rails-side check exactly (any `.`/`..` segment is refused outright, not
+// resolved), so a path the brain would refuse can never materialize here.
+export function assertUnitbobPath(path, root) {
+    // The root may arrive with or without a trailing slash (the wire's path_root
+    // carries one, the local constants do not) — normalize to exactly one.
+    const prefix = `${root.replace(/\/+$/, '')}/`;
+    const unsafe = !path ||
+        isAbsolute(path) ||
+        !path.startsWith(prefix) ||
+        path.split('/').some((segment) => segment === '.' || segment === '..');
+    if (unsafe) {
+        throw new Error(`suite file path must be a relative path under ${prefix} with no traversal (got "${path}").`);
+    }
+}

package/dist/files/behavioral.js

@@ -0,0 +1,29 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { assertUnitbobPath } from "./artifactPath.js";
+// The behavioral suite lives under its own root: the main `.feature` plus its
+// step definitions and any helper files, all under `.unitbob/behavioral/`
+// (spec 32). Nothing here is ever written into the project's own `spec/`,
+// `features/`, or `tests/`. Like the structural flow, the host LLM writes and
+// runs the suite to green before upload; the connector materializes the stored
+// blob only so `check` can execute it locally.
+export const BEHAVIORAL_DIR = '.unitbob/behavioral';
+// Write a behavioral artifact envelope (main file + support files) under the
+// behavioral root, after checking every path is safe. The root is wiped first
+// so a stale file from a previous version never lingers. Returns the absolute
+// path of the materialized main file.
+export function materializeBehavioral(projectRoot, artifact) {
+    const files = [artifact, ...(artifact.support_files ?? [])];
+    for (const file of files)
+        assertUnitbobPath(file.path, BEHAVIORAL_DIR);
+    rmSync(join(projectRoot, BEHAVIORAL_DIR), { recursive: true, force: true });
+    let mainPath = '';
+    for (const file of files) {
+        const dest = join(projectRoot, file.path);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, file.content);
+        if (file === artifact)
+            mainPath = dest;
+    }
+    return { mainPath };
+}

package/dist/files/guardrails.js

@@ -1,11 +1,13 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
-// A forward-slash literal, not path.join: suite paths always arrive over the
-// wire with '/', while path.join would render this '.unitbob\guardrails' on
-// Windows and make assertGuardrailPath reject every valid path there. node's
+// The structural suite lives under its own root now that behavioral is its peer
+// (spec 32) — `.unitbob/structural/`, matching the Rails StructuralSuiteVersion
+// path root. A forward-slash literal, not path.join: suite paths always arrive
+// over the wire with '/', while path.join would render this '.unitbob\structural'
+// on Windows and make assertGuardrailPath reject every valid path there. node's
 // path.join still accepts a '/'-joined segment as input on every platform, so
 // filesystem builds below are unaffected.
-export const GUARDRAILS_DIR = '.unitbob/guardrails';
+export const GUARDRAILS_DIR = '.unitbob/structural';
 export const HELPER_FILE = 'unitbob_helper.rb';
 // An always-empty custom options file: pointing rspec's --options here keeps
 // the project's own .rspec (stray --require lines, extra stdout formatters)

package/dist/files/suiteBuild.js

@@ -1,19 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { assertGuardrailPath } from "./guardrails.js";
+import { assertUnitbobPath } from "./artifactPath.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
 }
 export function outputPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'suite_output.json');
 }
-export function writeSuiteBuildRequest(projectRoot, task) {
+export function writeSuiteBuildRequest(projectRoot, branches) {
     const request = {
         project_root: projectRoot,
-        map_digest: task.map_digest,
         output_path: outputPath(projectRoot),
-        recipe: task.recipe,
-        blocks: task.blocks,
+        branches,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -26,62 +24,83 @@ export function readSuiteBuildRequest(projectRoot) {
         throw new Error(`${path} not found — run \`npx unitbob suite-prepare\` first.`);
     }
     const request = parseJson(readFileSync(path, 'utf8'), path);
-    if (!isSuiteBuildRequest(request)) {
-        throw new Error(`${path} is malformed: expected project_root, map_digest, output_path, recipe, and blocks.`);
+    if (!request ||
+        typeof request.project_root !== 'string' ||
+        typeof request.output_path !== 'string' ||
+        !Array.isArray(request.branches)) {
+        throw new Error(`${path} is malformed: expected project_root, output_path, and a branches array.`);
     }
     return request;
 }
-// Read and parse the host's answer. The host wrote and ran the whole guardrail
-// file; the connector verifies the answer parses, carries `suite_file` (with a
-// safe path under .unitbob/guardrails/), `runner_manifest`, and
-// `test_metadata`, then relays it untouched. Anything unparseable or
-// incomplete means nothing is uploaded (all-or-nothing).
-export function readHostSuiteOutput(path, projectRoot) {
+// Read the host's answers, one per branch. The connector verifies each built
+// branch parses, carries a safe-path artifact envelope under its own root, and
+// has a runner_manifest and test_metadata. A branch may instead carry a
+// build_error, which the connector relays. Anything unparseable throws and
+// nothing is uploaded.
+export function readHostSuiteOutputs(path, request) {
     if (!existsSync(path)) {
         throw new Error(`${path} not found — the host suite builder did not write its output.`);
     }
     const parsed = parseJson(readFileSync(path, 'utf8'), path);
-    if (!parsed || typeof parsed !== 'object') {
-        throw new Error(`${path} is malformed: expected an object with suite_file, runner_manifest, and test_metadata.`);
+    const branches = parsed && Array.isArray(parsed.branches) ? parsed.branches : null;
+    if (!branches) {
+        throw new Error(`${path} is malformed: expected a branches array, one entry per contract system.`);
     }
-    if ('spec_rb' in parsed || 'spec_rb_path' in parsed) {
-        throw new Error(`${path} uses the legacy spec_rb shape — emit suite_file { path, content } instead (spec 30).`);
+    const rootFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.path_root]));
+    return branches.map((entry) => readBranch(entry, rootFor, path));
+}
+function readBranch(entry, rootFor, path) {
+    if (!entry || typeof entry !== 'object') {
+        throw new Error(`${path} is malformed: each branch must be an object.`);
+    }
+    const branch = entry;
+    const suiteKind = String(branch.suite_kind ?? '');
+    const root = rootFor.get(suiteKind);
+    if (!root) {
+        throw new Error(`${path}: unknown suite_kind "${suiteKind}" — it was not in the build request.`);
+    }
+    if ('spec_rb' in branch || 'spec_rb_path' in branch) {
+        throw new Error(`${path}: the ${suiteKind} branch uses the legacy spec_rb shape — emit suite_file instead.`);
+    }
+    if (branch.build_error && typeof branch.build_error === 'object') {
+        const message = String(branch.build_error.message ?? 'the host could not build this suite');
+        return { suite_kind: suiteKind, build_error: { message } };
     }
-    if (!('test_metadata' in parsed)) {
-        throw new Error(`${path} is malformed: missing test_metadata.`);
+    if (!('test_metadata' in branch)) {
+        throw new Error(`${path}: the ${suiteKind} branch is missing test_metadata.`);
     }
-    const manifest = parsed.runner_manifest;
+    const manifest = branch.runner_manifest;
     if (!manifest || typeof manifest !== 'object') {
-        throw new Error(`${path} is malformed: missing runner_manifest.`);
+        throw new Error(`${path}: the ${suiteKind} branch is missing runner_manifest.`);
     }
     return {
-        suite_file: resolveSuiteFile(parsed, projectRoot, path),
+        suite_kind: suiteKind,
+        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind),
         runner_manifest: manifest,
-        test_metadata: parsed.test_metadata,
+        test_metadata: branch.test_metadata,
     };
 }
-// The host may inline `content` or point at the file it already wrote at
-// `suite_file.path` — either way the path must be safe before anything is read.
-function resolveSuiteFile(parsed, projectRoot, path) {
-    const file = parsed.suite_file;
+// The host inlines every file's `content`; each path is checked safe under this
+// branch's root before anything is accepted.
+function resolveSuiteFile(file, root, path, suiteKind) {
     if (!file || typeof file !== 'object') {
-        throw new Error(`${path} is malformed: expected suite_file { path, content }.`);
+        throw new Error(`${path}: the ${suiteKind} branch is missing suite_file.`);
     }
-    const suiteFile = file;
-    const suitePath = typeof suiteFile.path === 'string' ? suiteFile.path : '';
-    assertGuardrailPath(suitePath);
-    if (typeof suiteFile.content === 'string' && suiteFile.content.trim()) {
-        return { path: suitePath, content: suiteFile.content };
-    }
-    const onDisk = join(projectRoot, suitePath);
-    if (!existsSync(onDisk)) {
-        throw new Error(`${path}: suite_file has no content and "${suitePath}" does not exist in the project.`);
-    }
-    const content = readFileSync(onDisk, 'utf8');
-    if (!content.trim()) {
-        throw new Error(`${path}: suite_file content at "${suitePath}" is empty.`);
+    const envelope = file;
+    const main = readOneFile(envelope, root, path, suiteKind, false);
+    const support = Array.isArray(envelope.support_files)
+        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true))
+        : [];
+    return support.length > 0 ? { ...main, support_files: support } : main;
+}
+function readOneFile(file, root, path, suiteKind, support) {
+    const filePath = typeof file.path === 'string' ? file.path : '';
+    assertUnitbobPath(filePath, root);
+    if (typeof file.content === 'string' && file.content.trim()) {
+        return { path: filePath, content: file.content };
     }
-    return { path: suitePath, content };
+    const label = support ? 'support file' : 'suite_file';
+    throw new Error(`${path}: the ${suiteKind} ${label} at "${filePath}" has no inline content.`);
 }
 function parseJson(raw, path) {
     try {
@@ -91,19 +110,8 @@ function parseJson(raw, path) {
         throw new Error(`${path} is not valid JSON (${err.message})`);
     }
 }
-function isSuiteBuildRequest(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const request = value;
-    return (typeof request.project_root === 'string' &&
-        typeof request.map_digest === 'string' &&
-        typeof request.output_path === 'string' &&
-        isRecipe(request.recipe) &&
-        Array.isArray(request.blocks));
-}
-function isRecipe(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const recipe = value;
-    return typeof recipe.name === 'string' && typeof recipe.version === 'string' && typeof recipe.text === 'string';
+// Turn a branch's assignment packet into its recipe name: structural uses the
+// unit-guardrail recipe, behavioral the Gherkin one.
+export function recipeNameFor(packet) {
+    return packet.suite_kind === 'behavioral' ? 'generate_behavioral' : 'generate';
 }

package/dist/runner/bdd.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProcess } from "../proc.js";
+import { readReport } from "./types.js";
+import { PYTEST_BDD_PLUGIN } from "./pytestBddPlugin.js";
+export const BDD_TIMEOUT_MS = 10 * 60 * 1000;
+// The behavioral suite lives under one root; the report is written inside it so
+// the app under test cannot pollute it and it travels with the suite.
+const BEHAVIORAL_ROOT = '.unitbob/behavioral';
+const CUCUMBER_REPORT = join(BEHAVIORAL_ROOT, 'cucumber_messages.ndjson');
+const PYTEST_BDD_REPORT = join(BEHAVIORAL_ROOT, 'pytest_bdd_report.json');
+const PYTEST_BDD_PLUGIN_FILE = join(BEHAVIORAL_ROOT, 'unitbob_pytest_bdd_plugin.py');
+const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, 'pytest.ini');
+const PYTEST_INI = '[pytest]\naddopts =\n';
+// The connector-owned BDD strategy table (spec 32): the `runner` enum names one
+// of these; the connector never executes a host-provided command string. Each
+// strategy runs the whole behavioral bundle and returns the raw machine-readable
+// report verbatim — the connector does no marker join and no aggregation.
+export function runBddSuite(projectRoot, runner, mainPath) {
+    switch (runner) {
+        case 'cucumber':
+            return runCucumberRuby(projectRoot);
+        case 'cucumber-js':
+            return runCucumberJs(projectRoot);
+        case 'pytest-bdd':
+            return runPytestBdd(projectRoot, mainPath);
+        default:
+            return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
+    }
+}
+// Ruby: `cucumber` with the built-in message formatter. The features and step
+// definitions both live under the behavioral root; --require points at the step
+// definitions so only the Unitbob bundle loads.
+async function runCucumberRuby(projectRoot) {
+    const features = join(BEHAVIORAL_ROOT, 'features');
+    const steps = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const localBin = join(projectRoot, 'bin', 'cucumber');
+    const command = executable(localBin) ? localBin : 'bundle';
+    const base = executable(localBin) ? [] : ['exec', 'cucumber'];
+    const args = [...base, features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: BDD_TIMEOUT_MS,
+        env: { ...process.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+    });
+    return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
+}
+// JS/TS: `@cucumber/cucumber` (cucumber-js) with the message formatter written
+// to a file.
+async function runCucumberJs(projectRoot) {
+    const features = join(BEHAVIORAL_ROOT, 'features');
+    const steps = join(BEHAVIORAL_ROOT, 'step_definitions', '**', '*');
+    const command = 'npx';
+    const args = [
+        'cucumber-js',
+        features,
+        '--require',
+        steps,
+        '--format',
+        `message:${CUCUMBER_REPORT}`,
+    ];
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: BDD_TIMEOUT_MS,
+        env: { ...process.env, NODE_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+    });
+    return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
+}
+// Python: pytest driving pytest-bdd, with the connector's reporter plugin. The
+// plugin writes the JSON report; `-c` isolates the run from the project's own
+// addopts. The runner command is connector-owned.
+async function runPytestBdd(projectRoot, mainPath) {
+    mkdirSync(join(projectRoot, BEHAVIORAL_ROOT), { recursive: true });
+    writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
+    writeFileSync(join(projectRoot, PYTEST_BDD_PLUGIN_FILE), PYTEST_BDD_PLUGIN);
+    const command = await pickPython(projectRoot);
+    const stepsDir = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p',
+        pluginModule(), stepsDir, '--rootdir', projectRoot];
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: BDD_TIMEOUT_MS,
+        env: {
+            ...process.env,
+            UNITBOB_REPO_ROOT: projectRoot,
+            UNITBOB_PYTEST_BDD_REPORT: join(projectRoot, PYTEST_BDD_REPORT),
+            PYTHONPATH: [join(projectRoot, BEHAVIORAL_ROOT), process.env.PYTHONPATH ?? ''].filter(Boolean).join(':'),
+        },
+    });
+    return finalize(result, command, args, projectRoot, PYTEST_BDD_REPORT);
+    // mainPath is accepted for symmetry with the structural runners; pytest-bdd
+    // discovers scenarios from the step-definition modules, not the .feature path.
+}
+function pluginModule() {
+    return 'unitbob_pytest_bdd_plugin';
+}
+function finalize(result, command, args, projectRoot, reportRel) {
+    return {
+        ...result,
+        command,
+        args,
+        resultPath: reportRel,
+        report: readReport(join(projectRoot, reportRel)),
+    };
+}
+async function pickPython(projectRoot) {
+    const probe = await runProcess('python3', ['-m', 'pytest', '--version'], {
+        cwd: projectRoot,
+        timeoutMs: 10_000,
+    }).catch(() => ({ stdout: '', stderr: '', code: 1 }));
+    return probe.code === 0 ? 'python3' : 'python';
+}
+function executable(path) {
+    try {
+        return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runner/boundReport.js

@@ -0,0 +1,107 @@
+// Size-bound the raw machine-readable report before transport (spec 26/30/32).
+// This is a size limit only, not a privacy filter: application values in failure
+// messages are accepted, not scrubbed. `null` means "no usable report" — the
+// caller takes the structured suite-error path.
+//
+// Structural JSON/XML reports are parsed only to bound per-failure text, then
+// re-serialized. Behavioral reports (Cucumber Messages NDJSON, pytest-bdd JSON)
+// are bounded by whole-document size and shipped verbatim — Rails owns every bit
+// of their interpretation.
+const MAX_FAILURE_CHARS = 8000;
+const MAX_REPORT_CHARS = 4_000_000;
+export function boundReport(runner, result) {
+    switch (runner) {
+        case 'pytest':
+            return result.report.trim() ? boundJunitXml(result.report) : null;
+        case 'rspec':
+        case 'vitest': {
+            const parsed = parseJsonObject(result.report) ?? (runner === 'rspec' ? parseJsonObject(result.stdout) : null);
+            if (!parsed)
+                return null;
+            const bounded = runner === 'rspec' ? boundRspecFailures(parsed) : boundVitestFailures(parsed);
+            return JSON.stringify(bounded);
+        }
+        case 'cucumber':
+        case 'cucumber-js':
+        case 'pytest-bdd':
+            return boundWhole(result.report);
+        default:
+            return boundWhole(result.report);
+    }
+}
+// A behavioral report is shipped whole. An empty one is "no usable report" so
+// the caller reports a suite error rather than an empty green.
+function boundWhole(report) {
+    if (!report.trim())
+        return null;
+    return report.length > MAX_REPORT_CHARS ? report.slice(0, MAX_REPORT_CHARS) : report;
+}
+function boundRspecFailures(rspecJson) {
+    const examples = rspecJson.examples;
+    if (!Array.isArray(examples))
+        return rspecJson;
+    const bounded = examples.map((example) => {
+        if (!example || typeof example !== 'object')
+            return example;
+        const ex = example;
+        const exception = ex.exception;
+        if (!exception || typeof exception !== 'object')
+            return ex;
+        const exc = exception;
+        const next = { ...exc };
+        if (typeof exc.message === 'string')
+            next.message = truncate(exc.message);
+        if (Array.isArray(exc.backtrace))
+            next.backtrace = exc.backtrace.slice(0, 20);
+        return { ...ex, exception: next };
+    });
+    return { ...rspecJson, examples: bounded };
+}
+function boundVitestFailures(vitestJson) {
+    const testResults = vitestJson.testResults;
+    if (!Array.isArray(testResults))
+        return vitestJson;
+    const bounded = testResults.map((fileResult) => {
+        if (!fileResult || typeof fileResult !== 'object')
+            return fileResult;
+        const file = fileResult;
+        const assertions = file.assertionResults;
+        if (!Array.isArray(assertions))
+            return file;
+        const next = assertions.map((assertion) => {
+            if (!assertion || typeof assertion !== 'object')
+                return assertion;
+            const a = assertion;
+            if (!Array.isArray(a.failureMessages))
+                return a;
+            return { ...a, failureMessages: a.failureMessages.map((m) => (typeof m === 'string' ? truncate(m) : m)) };
+        });
+        return { ...file, assertionResults: next };
+    });
+    return { ...vitestJson, testResults: bounded };
+}
+function truncate(text) {
+    return text.length > MAX_FAILURE_CHARS ? `${text.slice(0, MAX_FAILURE_CHARS)}… (truncated)` : text;
+}
+function boundJunitXml(xml) {
+    const boundedBodies = xml.replace(/(<(failure|error|skipped|system-out|system-err)\b[^>]*>)([\s\S]*?)(<\/\2>)/g, (_match, open, _tag, body, close) => `${boundXmlMessageAttr(open)}${boundXmlText(body)}${close}`);
+    return boundedBodies.replace(/<(failure|error|skipped)\b[^>]*\/>/g, (tag) => boundXmlMessageAttr(tag));
+}
+function boundXmlMessageAttr(tag) {
+    return tag.replace(/(\bmessage=")([\s\S]*?)(")/, (_m, pre, value, post) => value.length > MAX_FAILURE_CHARS ? `${pre}${boundXmlText(value)}… (truncated)${post}` : `${pre}${value}${post}`);
+}
+function boundXmlText(text) {
+    return text.length > MAX_FAILURE_CHARS ? `${truncateXml(text)}… (truncated)` : text;
+}
+function truncateXml(text) {
+    return text.slice(0, MAX_FAILURE_CHARS).replace(/&[^;]*$/, '');
+}
+function parseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/runner/precheck.js

@@ -17,6 +17,14 @@ export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
 }
 // Confirm the host-selected runner against local markers. A mismatch fails
 // closed: the caller writes no files and uploads nothing.
+//
+// Both contract systems route through here (spec 32). The structural runners
+// (rspec/vitest/pytest) confirm the exact test framework is present, because the
+// host writes and runs against it. The behavioral BDD runners
+// (cucumber/cucumber-js/pytest-bdd) confirm only the base language: `check` never
+// installs anything, so a missing BDD runner is left to surface as a suite error
+// from the actual run — the precheck just replaces "bundle: command not found"
+// with an early, clear "this project isn't Ruby".
 export function validateStack(projectRoot, runner, deps = defaultDeps) {
     switch (runner) {
         case 'rspec':
@@ -25,13 +33,64 @@ export function validateStack(projectRoot, runner, deps = defaultDeps) {
             return vitestPrecheck(projectRoot);
         case 'pytest':
             return pytestPrecheck(projectRoot, deps);
+        case 'cucumber':
+            return rubyBehavioralPrecheck(projectRoot);
+        case 'cucumber-js':
+            return jsBehavioralPrecheck(projectRoot);
+        case 'pytest-bdd':
+            return pythonBehavioralPrecheck(projectRoot, deps);
         default:
             return {
                 ok: false,
-                message: `Unsupported runner "${runner}" — Unitbob supports rspec, vitest, and pytest only.`,
+                message: `Unsupported runner "${runner}" — Unitbob supports ` +
+                    'rspec, vitest, pytest, cucumber, cucumber-js, and pytest-bdd only.',
             };
     }
 }
+// The behavioral suite boots the app in its test environment, so a Ruby project
+// is the marker — but not rspec-rails (the behavioral runner is cucumber, not
+// rspec), and not the cucumber gem itself (check never installs; a missing
+// runner surfaces as a suite error from the run).
+function rubyBehavioralPrecheck(projectRoot) {
+    if (hasGemfileWith(projectRoot, /\brails\b/))
+        return { ok: true };
+    return {
+        ok: false,
+        message: 'The behavioral (Gherkin) suite selected the Ruby stack, but this project does not look ' +
+            'like Rails (no `rails` gem found in Gemfile).',
+    };
+}
+function jsBehavioralPrecheck(projectRoot) {
+    if (existsSync(join(projectRoot, 'package.json')))
+        return { ok: true };
+    return {
+        ok: false,
+        message: 'The behavioral (Gherkin) suite selected the JavaScript/TypeScript stack, but this project has no package.json.',
+    };
+}
+// pytest-bdd runs under pytest, so the harness must be importable — same probe
+// and message shape as the structural pytest precheck; pytest-bdd itself, if
+// missing, surfaces as a suite error from the run.
+function pythonBehavioralPrecheck(projectRoot, deps) {
+    const markers = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
+    if (!markers.some((name) => existsSync(join(projectRoot, name)))) {
+        return {
+            ok: false,
+            message: 'The behavioral (Gherkin) suite selected the Python stack, but this project has none of ' +
+                `${markers.join(', ')} — it does not look like a Python project.`,
+        };
+    }
+    const available = ['python3', 'python'].some((python) => deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot));
+    if (!available) {
+        return {
+            ok: false,
+            message: 'The behavioral (Gherkin) suite selected the Python stack, but pytest is not importable in ' +
+                'the current Python environment. If your dependencies live in a virtualenv, activate it ' +
+                '(e.g. `source .venv/bin/activate`) before running Unitbob, then retry.',
+        };
+    }
+    return { ok: true };
+}
 function rubyPrecheck(projectRoot) {
     if (!hasGemfileWith(projectRoot, /\brails\b/)) {
         return {

package/dist/runner/pytestBddPlugin.js

@@ -0,0 +1,62 @@
+// The connector-owned pytest-bdd reporter (spec 32). Python has no Cucumber
+// Messages emitter, so the connector ships this small deterministic plugin. It
+// hangs off pytest-bdd's public scenario/step hooks and writes one JSON document
+// the Rails PytestBddJson parser reads:
+//
+//   { "version": 1, "scenarios": [ { name, tags, status, failure, steps: [...] } ] }
+//
+// It only records — it never reconciles markers or aggregates capabilities. It
+// is connector-owned and never part of the LLM-generated step definitions.
+export const PYTEST_BDD_PLUGIN = `# Written by the unitbob connector — do not edit.
+import json
+import os
+
+_UNITBOB_REPORT = {"version": 1, "scenarios": []}
+_UNITBOB_CURRENT = {}
+
+
+def pytest_bdd_before_scenario(request, feature, scenario):
+    _UNITBOB_CURRENT[id(scenario)] = {
+        "name": scenario.name,
+        "tags": sorted(scenario.tags),
+        "status": "passed",
+        "failure": "",
+        "steps": [],
+    }
+
+
+def _record_step(scenario, step, status):
+    entry = _UNITBOB_CURRENT.get(id(scenario))
+    if entry is None:
+        return
+    entry["steps"].append({
+        "keyword": getattr(step, "keyword", "").strip(),
+        "text": step.name,
+        "status": status,
+    })
+
+
+def pytest_bdd_after_step(request, feature, scenario, step, step_func):
+    _record_step(scenario, step, "passed")
+
+
+def pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func_args, exception):
+    entry = _UNITBOB_CURRENT.get(id(scenario))
+    if entry is not None:
+        entry["status"] = "failed"
+        entry["failure"] = "{}: {}".format(type(exception).__name__, exception)
+    _record_step(scenario, step, "failed")
+
+
+def pytest_bdd_after_scenario(request, feature, scenario):
+    entry = _UNITBOB_CURRENT.pop(id(scenario), None)
+    if entry is not None:
+        _UNITBOB_REPORT["scenarios"].append(entry)
+
+
+def pytest_sessionfinish(session, exitstatus):
+    out = os.environ.get("UNITBOB_PYTEST_BDD_REPORT")
+    if out:
+        with open(out, "w") as handle:
+            json.dump(_UNITBOB_REPORT, handle)
+`;

package/dist/verbs/contractPrompt.js

@@ -0,0 +1,25 @@
+import { Wire } from "../wire.js";
+// Fetch the contract action brief for one red check (spec 32). One operation for
+// both maps and both intents: the digest names the exact current version (and so
+// its contract system), `test_id` is that kind's own id, `intent` is fix|accept.
+// The server composes the whole prompt; the connector prints its plain-language
+// `message` and the copy-ready `prompt`. A 422 (not current / not failing /
+// unknown intent) surfaces via WireError; nothing is fabricated.
+export async function contractPrompt(config, args = [], deps) {
+    const suiteDigest = (args[0] ?? '').trim();
+    const testId = (args[1] ?? '').trim();
+    const intent = (args[2] ?? 'fix').trim();
+    if (!suiteDigest || !testId) {
+        throw new Error('Usage: unitbob contract-prompt <suite_digest> <test_id> [fix|accept]');
+    }
+    if (intent !== 'fix' && intent !== 'accept') {
+        throw new Error(`intent must be "fix" or "accept" (got "${intent}").`);
+    }
+    const d = {
+        getContractPrompt: (digest, id, action) => new Wire(config).getContractPrompt(digest, id, action),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const packet = await d.getContractPrompt(suiteDigest, testId, intent);
+    d.stdout.write(`${packet.message}\n\n${packet.prompt}\n`);
+}

package/dist/verbs/putSuiteBuild.js

@@ -1,35 +1,49 @@
-import { readHostSuiteOutput, readSuiteBuildRequest } from "../files/suiteBuild.js";
-import { validateStack } from "../runner/precheck.js";
+import { readHostSuiteOutputs, readSuiteBuildRequest } from "../files/suiteBuild.js";
 import { Wire } from "../wire.js";
-// Read the task and the host's answer, verify the answer parses and carries the
-// whole suite artifact, confirm the host-selected stack against local project
-// markers (fail closed — a mismatch uploads nothing), then upload
-// `{ map_digest, suite_file, runner_manifest, test_metadata }`. `map_digest`
-// comes from the task — never the host's answer — so the host cannot claim a
-// different map than it was given. If the answer is unparseable or incomplete,
-// nothing is uploaded and the previous suite stands.
+// Read the task and the host's answers, verify each branch parses and carries a
+// safe-path artifact envelope, then upload both peer branches in one batch
+// (spec 32). `source_digest` comes from the task — never the host's answer — so
+// the host cannot claim a different map than each branch was given. A branch the
+// host could not build is uploaded as a `build_error`, which never rolls back the
+// peer branch. If a branch's answer is unparseable, nothing is uploaded.
 export async function putSuiteBuild(config, _args = [], deps) {
     const request = readSuiteBuildRequest(config.projectRoot);
-    const output = readHostSuiteOutput(request.output_path, config.projectRoot);
-    const actual = {
-        putSuiteBuild: (payload) => new Wire(config).putSuiteBuild(payload),
-        validateStack,
+    const outputs = readHostSuiteOutputs(request.output_path, request);
+    const d = {
+        putSuiteBuilds: (items) => new Wire(config).putSuiteBuilds(items),
+        stdout: process.stdout,
         ...deps,
     };
-    const runner = String(output.runner_manifest.runner ?? '');
-    const check = actual.validateStack(config.projectRoot, runner);
-    if (!check.ok) {
-        throw new Error(check.message ?? `Local project does not match the selected runner "${runner}".`);
-    }
-    const result = await actual.putSuiteBuild({
-        map_digest: request.map_digest,
-        suite_file: output.suite_file,
-        runner_manifest: output.runner_manifest,
-        test_metadata: output.test_metadata,
+    const digestFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.source_digest]));
+    const items = outputs.map((output) => {
+        const sourceDigest = digestFor.get(output.suite_kind) ?? '';
+        if (output.build_error) {
+            return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
+        }
+        return {
+            suite_kind: output.suite_kind,
+            source_digest: sourceDigest,
+            artifacts: {
+                suite_file: output.suite_file,
+                runner_manifest: output.runner_manifest,
+                test_metadata: output.test_metadata,
+            },
+        };
     });
-    const tallies = Object.entries(result.counts)
-        .map(([name, value]) => `${value} ${name}`)
-        .join(', ');
-    process.stdout.write(`Suite uploaded (${result.suite_digest}) as version ${result.suite_version_id}` +
-        `${tallies ? ` — ${tallies}` : ''}.\n${result.map_url}\n`);
+    const results = await d.putSuiteBuilds(items);
+    for (const result of results) {
+        d.stdout.write(`${printResult(result)}\n`);
+    }
+}
+function printResult(result) {
+    if (result.status === 'error' || result.status === 'build_error') {
+        return `${result.suite_kind}: not published — ${result.error ?? 'the host could not build this suite'}.`;
+    }
+    const tallies = result.counts
+        ? Object.entries(result.counts)
+            .map(([name, value]) => `${value} ${name}`)
+            .join(', ')
+        : '';
+    const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
+    return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
 }

package/dist/verbs/run.js

@@ -1,59 +1,90 @@
 import { materializeGuardrails } from "../files/guardrails.js";
+import { materializeBehavioral } from "../files/behavioral.js";
 import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
 import { runVitestSuite } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
-// Bound failure text for transport/storage hygiene (spec 26). This is a size
-// limit only, not a privacy filter — application values in failure messages are
-// accepted, not scrubbed.
-const MAX_FAILURE_CHARS = 8000;
 const OUTPUT_TAIL_CHARS = 2000;
-// The check flow (spec 30): fetch the current suite blob, confirm the local
-// project matches its runner, materialize the guardrail file, execute the
-// connector-owned strategy named by `runner_manifest.runner`, and ship the raw
-// machine-readable report (or a structured runner error) to Rails.
 export async function run(config, _args, deps) {
     const wire = new Wire(config);
     const d = {
-        getSuite: () => wire.getSuite(),
-        postRun: (payload) => wire.postRun(payload),
-        materializeGuardrails,
-        runSuite: runSuiteByRunner,
+        getSuites: () => wire.getSuites(),
+        postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
+            suite_digest: item.suite_digest,
+            suite_file: { path: item.suite_file.path, content: item.suite_file.content },
+            runner_manifest: item.runner_manifest,
+        }),
+        materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file).mainPath,
+        runStructural: runStructuralByRunner,
+        runBehavioral: runBddSuite,
         validateStack,
         stdout: process.stdout,
         ...deps,
     };
-    const suite = await d.getSuite();
-    if (suite === null) {
-        d.stdout.write('No Unitbob suite exists yet. Generate the test suite first, then run /unitbob check again.\n');
+    const suites = await d.getSuites();
+    const ready = suites.filter((item) => item.status === 'ready');
+    if (ready.length === 0) {
+        d.stdout.write('No Unitbob suites exist yet. Generate them first, then run the Unitbob checks again.\n');
         return;
     }
-    // Fail closed before touching the working tree: a stack mismatch writes no files.
-    const runner = suite.runner_manifest.runner;
+    const runs = [];
+    for (const item of ready) {
+        runs.push(await buildRunPayload(config, d, item));
+    }
+    const { results, map_url } = await d.postRunsBatch(runs);
+    for (const result of results)
+        d.stdout.write(`${result.summary}\n`);
+    if (map_url)
+        d.stdout.write(`${map_url}\n`);
+}
+// One branch's run payload. A stack mismatch, a materialize failure, or a runner
+// that produced no report all become this branch's structured suite error — the
+// peer branch is unaffected. This connector never installs anything: a missing
+// or broken runner surfaces here as a suite error, not an install.
+async function buildRunPayload(config, d, item) {
+    const runner = item.runner_manifest.runner;
+    const behavioral = item.suite_kind === 'behavioral';
+    // Confirm the local stack before touching the tree, for both contract systems.
+    // A mismatch is this branch's suite error — reported and left for the peer
+    // branch to run regardless. The behavioral check confirms only the base
+    // language; a missing BDD runner still surfaces from the run itself, since
+    // check installs nothing.
     const check = d.validateStack(config.projectRoot, runner);
     if (!check.ok)
-        throw new Error(check.message ?? `Local project does not match the suite runner "${runner}".`);
-    d.materializeGuardrails(config.projectRoot, suite);
-    const result = await d.runSuite(config.projectRoot, runner, suite.suite_file.path).catch((err) => ({
-        stdout: '',
-        stderr: err.message,
-        code: null,
-        command: runner,
-        args: [],
-        resultPath: '',
-        report: '',
-    }));
-    const payload = rawRunPayload(suite.suite_digest, runner, result);
-    const summary = await d.postRun(payload);
-    d.stdout.write(`${summary.summary}\n`);
-    if (summary.map_url)
-        d.stdout.write(`${summary.map_url}\n`);
+        return suiteError(item.suite_digest, check.message ?? `Local project does not match "${runner}".`);
+    let result;
+    try {
+        if (behavioral) {
+            const mainPath = d.materializeBehavioral(config.projectRoot, item);
+            result = await d.runBehavioral(config.projectRoot, runner, mainPath);
+        }
+        else {
+            d.materializeStructural(config.projectRoot, item);
+            result = await d.runStructural(config.projectRoot, runner, item.suite_file.path);
+        }
+    }
+    catch (err) {
+        return suiteError(item.suite_digest, err.message);
+    }
+    const report = boundReport(runner, result);
+    if (report === null) {
+        return {
+            suite_digest: item.suite_digest,
+            suite_error: {
+                command: [result.command, ...result.args].join(' '),
+                exit_code: result.code,
+                result_path: result.resultPath,
+                output_tail: outputTail(result),
+            },
+        };
+    }
+    return { suite_digest: item.suite_digest, run_result: report };
 }
-// The connector-owned strategy table: `runner_manifest.runner` names one of
-// these; only suite and result paths vary. Host-provided command strings are
-// never executed.
-function runSuiteByRunner(projectRoot, runner, suitePath) {
+function runStructuralByRunner(projectRoot, runner, suitePath) {
     switch (runner) {
         case 'rspec':
             return runRspecSuite(projectRoot, suitePath);
@@ -62,119 +93,15 @@ function runSuiteByRunner(projectRoot, runner, suitePath) {
         case 'pytest':
             return runPytestSuite(projectRoot, suitePath);
         default:
-            return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite with /unitbob suite.`));
+            return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite.`));
     }
 }
-// The machine-readable report comes from the runner's own output file, which
-// the app under test cannot pollute. A run that produced no report is a
-// structured suite error — command, exit code, expected result path, output
-// tail — which Rails records without repainting capabilities.
-function rawRunPayload(suiteDigest, runner, result) {
-    const report = boundedReport(runner, result);
-    if (report !== null)
-        return { suite_digest: suiteDigest, run_result: report };
+function suiteError(suiteDigest, message) {
     return {
         suite_digest: suiteDigest,
-        suite_error: {
-            command: [result.command, ...result.args].join(' '),
-            exit_code: result.code,
-            result_path: result.resultPath,
-            output_tail: outputTail(result),
-        },
+        suite_error: { command: '', exit_code: null, result_path: '', output_tail: message },
     };
 }
-// JSON reports (rspec, vitest) are parsed only to size-bound failure text, then
-// re-serialized; the XML report is bounded per failure element the same way.
-// `null` means "no usable report" — the suite-error path. Stdout is only a
-// fallback for an rspec double that emits its report there.
-function boundedReport(runner, result) {
-    if (runner === 'pytest')
-        return result.report.trim() ? boundJunitXml(result.report) : null;
-    const parsed = parseJsonObject(result.report) ?? (runner === 'rspec' ? parseJsonObject(result.stdout) : null);
-    if (!parsed)
-        return null;
-    const bounded = runner === 'rspec' ? boundRspecFailures(parsed) : boundVitestFailures(parsed);
-    return JSON.stringify(bounded);
-}
-// Truncate long per-example failure message/backtrace before transport. Other
-// fields pass through untouched; Rails owns the capability join and status mapping.
-function boundRspecFailures(rspecJson) {
-    const examples = rspecJson.examples;
-    if (!Array.isArray(examples))
-        return rspecJson;
-    const bounded = examples.map((example) => {
-        if (!example || typeof example !== 'object')
-            return example;
-        const ex = example;
-        const exception = ex.exception;
-        if (!exception || typeof exception !== 'object')
-            return ex;
-        const exc = exception;
-        const next = { ...exc };
-        if (typeof exc.message === 'string')
-            next.message = truncate(exc.message);
-        if (Array.isArray(exc.backtrace))
-            next.backtrace = exc.backtrace.slice(0, 20);
-        return { ...ex, exception: next };
-    });
-    return { ...rspecJson, examples: bounded };
-}
-function boundVitestFailures(vitestJson) {
-    const testResults = vitestJson.testResults;
-    if (!Array.isArray(testResults))
-        return vitestJson;
-    const bounded = testResults.map((fileResult) => {
-        if (!fileResult || typeof fileResult !== 'object')
-            return fileResult;
-        const file = fileResult;
-        const assertions = file.assertionResults;
-        if (!Array.isArray(assertions))
-            return file;
-        const next = assertions.map((assertion) => {
-            if (!assertion || typeof assertion !== 'object')
-                return assertion;
-            const a = assertion;
-            if (!Array.isArray(a.failureMessages))
-                return a;
-            return { ...a, failureMessages: a.failureMessages.map((m) => (typeof m === 'string' ? truncate(m) : m)) };
-        });
-        return { ...file, assertionResults: next };
-    });
-    return { ...vitestJson, testResults: bounded };
-}
-function truncate(text) {
-    return text.length > MAX_FAILURE_CHARS ? `${text.slice(0, MAX_FAILURE_CHARS)}… (truncated)` : text;
-}
-// pytest's JUnit XML has no size bound of its own: one failing assertion can
-// carry a multi-megabyte diff plus captured stdout/stderr. Bound the two things
-// Rails reads (the failure/error/skipped `message` attribute and the element
-// body) plus the captured-output blocks, keeping the document well-formed so
-// Rails' strict XML parse still succeeds.
-function boundJunitXml(xml) {
-    const boundedBodies = xml.replace(/(<(failure|error|skipped|system-out|system-err)\b[^>]*>)([\s\S]*?)(<\/\2>)/g, (_match, open, _tag, body, close) => `${boundXmlMessageAttr(open)}${boundXmlText(body)}${close}`);
-    // Self-closing forms (e.g. <failure message="…"/>) carry everything in the attr.
-    return boundedBodies.replace(/<(failure|error|skipped)\b[^>]*\/>/g, (tag) => boundXmlMessageAttr(tag));
-}
-function boundXmlMessageAttr(tag) {
-    // Attribute values escape their own quotes, so matching to the next `"` is safe.
-    return tag.replace(/(\bmessage=")([\s\S]*?)(")/, (_m, pre, value, post) => value.length > MAX_FAILURE_CHARS ? `${pre}${boundXmlText(value)}… (truncated)${post}` : `${pre}${value}${post}`);
-}
-function boundXmlText(text) {
-    return text.length > MAX_FAILURE_CHARS ? `${truncateXml(text)}… (truncated)` : text;
-}
-// Slice without cutting inside an XML entity, which would break a strict parse.
-function truncateXml(text) {
-    return text.slice(0, MAX_FAILURE_CHARS).replace(/&[^;]*$/, '');
-}
-function parseJsonObject(text) {
-    try {
-        const parsed = JSON.parse(text);
-        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
 function outputTail(result) {
     const bits = [];
     if (result.stderr.trim())

package/dist/verbs/suitePrepare.js

@@ -1,35 +1,40 @@
 import { materializeHelper } from "../files/guardrails.js";
-import { writeSuiteBuildRequest } from "../files/suiteBuild.js";
+import { recipeNameFor, writeSuiteBuildRequest } from "../files/suiteBuild.js";
 import { anyStackPrecheck } from "../runner/precheck.js";
 import { Wire } from "../wire.js";
-// Confirm at least one supported stack is present (Rails+RSpec, Vitest, or
-// pytest — the host LLM picks the primary one during generation), materialize
-// the Ruby boot helper a generated RSpec suite would require, then fetch the
-// generate recipe and the per-block capability assignment and write the host's
-// task to `.unitbob/suite-build/request.json`. No model is called and no
-// source is read here — that is the host's job, framed by
-// ai/agents/suite_builder.md. An unsupported project stops with one actionable
-// message and writes nothing; a no-current-map error from the server surfaces
-// (via WireError) with guidance to run `/unitbob map` first.
+// Confirm at least one supported stack is present, materialize the Ruby boot
+// helper a generated RSpec suite would require, then fetch both peer assignments
+// (spec 32) and each branch's recipe, and write the host's task to
+// `.unitbob/suite-build/request.json`. No model is called and no source is read
+// here — that is the host's job, framed by the two generation recipes. An
+// unsupported project stops with one actionable message and writes nothing; a
+// no-current-map error from the server surfaces (via WireError) with guidance to
+// rebuild the map first.
 export async function suitePrepare(config, _args = [], deps) {
     const wire = new Wire(config);
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
-        getSuitePackets: () => wire.getSuitePackets(),
+        getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
+        stdout: process.stdout,
         ...deps,
     };
     const check = actual.precheck(config.projectRoot);
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
     materializeHelper(config.projectRoot);
-    const [recipe, packets] = await Promise.all([actual.getRecipe('generate'), actual.getSuitePackets()]);
-    const request = writeSuiteBuildRequest(config.projectRoot, {
-        map_digest: packets.map_digest,
-        recipe,
-        blocks: packets.blocks,
-    });
-    process.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
-    process.stdout.write(`Next: write the complete guardrail spec and ${request.output_path} following \`recipe\` and the ` +
-        'per-block capability `blocks` inside that request, run it locally to green, then run `unitbob put-suite-build`.\n');
+    const packets = await actual.getSuitePacketsBatch();
+    const branches = await Promise.all(packets.map(async (packet) => ({
+        suite_kind: packet.suite_kind,
+        source_digest: packet.source_digest,
+        path_root: packet.path_root,
+        recipe: await actual.getRecipe(recipeNameFor(packet)),
+        assignment: packet.assignment,
+    })));
+    const request = writeSuiteBuildRequest(config.projectRoot, branches);
+    const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
+    actual.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
+    actual.stdout.write(`Next: build both peer suites (${kinds}) following each branch's \`recipe\` and \`assignment\`, ` +
+        `write your answer to ${request.output_path} as a branches array, run each locally to green, ` +
+        'then run `unitbob put-suite-build`.\n');
 }

package/dist/wire.js

@@ -49,9 +49,64 @@ export class Wire {
         await this.ensureOk(res, `PUT ${this.repoPath('map_build')}`);
         return (await res.json());
     }
-    // GET /repos/:id/suite_packets — the host's assignment (the capabilities to
-    // guard). Relayed opaque; 409 (no current map) surfaces as a WireError carrying
-    // the server's "run /unitbob map first" guidance.
+    // GET /repos/:id/suite_packets — the two peer assignments (spec 32), exactly
+    // one per contract system. Relayed opaque; 409 (no current map) surfaces as a
+    // WireError carrying the server's "run the Unitbob map first" guidance.
+    async getSuitePacketsBatch() {
+        const res = await this.send('GET', this.repoPath('suite_packets'));
+        await this.ensureOk(res, `GET ${this.repoPath('suite_packets')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.suite_packets)) {
+            throw new WireError(`GET ${this.repoPath('suite_packets')} returned no suite_packets array.`);
+        }
+        return body.suite_packets;
+    }
+    // PUT /repos/:id/suite_builds — upload both peer branches in one batch (spec
+    // 32). Each item is validated and published independently; the response
+    // carries one result per suite_kind.
+    async putSuiteBuilds(items) {
+        const res = await this.send('PUT', this.repoPath('suite_builds'), { suite_builds: items });
+        await this.ensureOk(res, `PUT ${this.repoPath('suite_builds')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.results)) {
+            throw new WireError(`PUT ${this.repoPath('suite_builds')} returned no results array.`);
+        }
+        return body.results;
+    }
+    // GET /repos/:id/suites — both current suites (spec 32), exactly two peer
+    // items. A `ready` item carries its blob; a `not_built` item is skipped.
+    async getSuites() {
+        const res = await this.send('GET', this.repoPath('suites'));
+        await this.ensureOk(res, `GET ${this.repoPath('suites')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.suites)) {
+            throw new WireError(`GET ${this.repoPath('suites')} returned no suites array.`);
+        }
+        return body.suites;
+    }
+    // POST /repos/:id/runs/batch — ship each branch's raw report (or suite error)
+    // in one batch; the server parses each against the exact stored version and
+    // returns one summary per branch plus one shared map URL.
+    async postRunsBatch(runs) {
+        const res = await this.send('POST', this.repoPath('runs/batch'), { runs });
+        await this.ensureOk(res, `POST ${this.repoPath('runs/batch')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.results)) {
+            throw new WireError(`POST ${this.repoPath('runs/batch')} returned no results array.`);
+        }
+        return { results: body.results, map_url: String(body.map_url ?? '') };
+    }
+    // GET /repos/:id/contract_prompt?suite_digest=&test_id=&intent= — the one
+    // contract action operation for both maps and both intents (spec 32).
+    async getContractPrompt(suiteDigest, testId, intent) {
+        const query = new URLSearchParams({ suite_digest: suiteDigest, test_id: testId, intent });
+        const url = `${this.repoPath('contract_prompt')}?${query}`;
+        const res = await this.send('GET', url);
+        await this.ensureOk(res, `GET ${url}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/suite_packets — the legacy singular assignment (spec 26),
+    // kept for the structural-only flow. Relayed opaque.
     async getSuitePackets() {
         const res = await this.send('GET', this.repoPath('suite_packets'));
         await this.ensureOk(res, `GET ${this.repoPath('suite_packets')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "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": {