unitbob 0.1.11 → 0.2.1

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,138 @@
+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 sidecarGemfile = join(projectRoot, BEHAVIORAL_ROOT, 'Gemfile');
+    const hasSidecarGemfile = existsSync(sidecarGemfile);
+    const command = executable(localBin) ? localBin : 'bundle';
+    const base = executable(localBin) ? [] : ['exec', 'cucumber'];
+    const args = [...base, features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
+    const env = {
+        ...process.env,
+        RAILS_ENV: 'test',
+        UNITBOB_REPO_ROOT: projectRoot,
+    };
+    if (hasSidecarGemfile) {
+        env.BUNDLE_GEMFILE = join(BEHAVIORAL_ROOT, 'Gemfile');
+    }
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: BDD_TIMEOUT_MS,
+        env,
+    });
+    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 sidecarBin = join(projectRoot, BEHAVIORAL_ROOT, 'node_modules', '.bin', 'cucumber-js');
+    const command = executable(sidecarBin) ? sidecarBin : 'npx';
+    const baseArgs = executable(sidecarBin) ? [] : ['cucumber-js'];
+    const args = [
+        ...baseArgs,
+        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 isVenvPytest = command.endsWith('/pytest');
+    const args = isVenvPytest
+        ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot]
+        : ['-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 sidecarVenvPytest = join(projectRoot, BEHAVIORAL_ROOT, '.venv', 'bin', 'pytest');
+    if (executable(sidecarVenvPytest)) {
+        return sidecarVenvPytest;
+    }
+    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 {