unitbob 0.2.4 → 0.2.7

package/dist/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The published executable (`package.json` bin). It exists only to start the
+// process and end it: no logic lives here, so nothing about how the CLI was
+// invoked can change what it does. npm installs a bin as a symlink, so this file
+// runs under a path that is not its own — an entry point that tried to detect
+// "am I the main module?" silently did nothing once installed.
+import { main } from "./cli.js";
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`${err.message}\n`);
+    process.exit(1);
+});

package/dist/cli.js

@@ -1,7 +1,8 @@
-#!/usr/bin/env node
-// The single entry point. Parse `unitbob <verb> [args]`, dispatch to a hands-verb,
-// and map any thrown error to a non-zero exit with an actionable message — never
-// a raw stack trace. This is the only place that decides process exit codes.
+// Verb dispatch. Parse `unitbob <verb> [args]`, dispatch to a hands-verb, and map
+// any thrown error to an exit code with an actionable message — never a raw stack
+// trace. This module decides exit codes but never acts on them: importing it must
+// stay free of side effects so tests can drive `main` directly. `bin.ts` is the
+// executable that owns process startup and exit.
 import { ensureLinked } from "./link.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
@@ -13,6 +14,7 @@ import { suitePrepare } from "./verbs/suitePrepare.js";
 import { putSuiteBuild } from "./verbs/putSuiteBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
+import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
 
 Usage: unitbob <verb> [args]
@@ -24,6 +26,7 @@ Verbs:
   map-prepare          Internal: keylessly update the graph (no API key) and write the host map-build request.
   put-map-build        Internal: upload the host-built map and graph.
   suite-prepare        Internal: fetch the recipe and capability assignment, write the host suite-build request.
+  suite-review-prepare Internal: bind an independent BDD quality review to the built behavioral candidate.
   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).
   contract-prompt <digest> <test_id> [fix|accept]
@@ -40,7 +43,7 @@ host-LLM's job; any semantic graph enrichment is host-LLM work (the /graphify sk
 
 Config: .unitbob.json at your project root, created automatically: the first
 run registers the project on the server by its folder name (spec 28).`;
-async function main(argv) {
+export async function main(argv, deps = { ensureLinked }) {
     const [verb, ...args] = argv;
     if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
         process.stdout.write(`${USAGE}\n`);
@@ -52,32 +55,35 @@ async function main(argv) {
                 await init(args);
                 return 0;
             case 'recipe':
-                await recipe(await ensureLinked(), args);
+                await recipe(await deps.ensureLinked(), args);
                 return 0;
             case 'show':
-                await show(await ensureLinked());
+                await show(await deps.ensureLinked());
                 return 0;
             case 'map-prepare':
-                await mapPrepare(await ensureLinked(), args);
+                await mapPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'put-map-build':
-                await putMapBuild(await ensureLinked(), args);
+                await putMapBuild(await deps.ensureLinked(), args);
                 return 0;
             case 'suite-prepare':
-                await suitePrepare(await ensureLinked(), args);
+                await suitePrepare(await deps.ensureLinked(), args);
+                return 0;
+            case 'suite-review-prepare':
+                await suiteReviewPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'put-suite-build':
-                await putSuiteBuild(await ensureLinked(), args);
+                await putSuiteBuild(await deps.ensureLinked(), args);
                 return 0;
             case 'fix-prepare':
-                await fixPrepare(await ensureLinked(), args);
+                await fixPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'contract-prompt':
-                await contractPrompt(await ensureLinked(), args);
+                await contractPrompt(await deps.ensureLinked(), args);
                 return 0;
             case 'run':
             case 'check':
-                await run(await ensureLinked(), args);
+                await run(await deps.ensureLinked(), args);
                 return 0;
             default:
                 process.stderr.write(`Unknown verb "${verb}".\n\n${USAGE}\n`);
@@ -89,7 +95,3 @@ async function main(argv) {
         return 1;
     }
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
-});

package/dist/files/behavioral.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, 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
@@ -34,6 +34,50 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     }
     return { mainPath };
 }
+// Everything under the behavioral root that the next materialization will
+// delete: it wipes every top-level entry outside the runner environment and
+// writes back only the files the answer listed, so a step file the answer forgot
+// is gone and its steps come back undefined — a harness break reported far from
+// its cause. One file per capability makes forgetting one much easier than a
+// single file for the whole product ever did.
+//
+// The whole root is walked, not just the directories the answer happens to use:
+// the file most likely to be forgotten is the one in a directory the answer
+// never mentions — `features/support/env.rb` is exactly that shape.
+export function filesLostOnMaterialize(projectRoot, artifact, runner) {
+    const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
+    if (!existsSync(behavioralRoot))
+        return [];
+    const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
+    const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
+    return readdirSync(behavioralRoot)
+        .filter((entry) => !runnerEntries.has(entry))
+        .flatMap((entry) => filesUnder(projectRoot, `${BEHAVIORAL_DIR}/${entry}`))
+        .filter((path) => !listed.has(path))
+        .sort();
+}
+// The real files under `relative`. Symlinks are not followed: materialization
+// removes the link, not what it points at, and naming the target here would read
+// as a warning about a file that was never in danger.
+function filesUnder(projectRoot, relative) {
+    const stats = lstatSync(join(projectRoot, relative));
+    if (stats.isFile())
+        return [relative];
+    if (!stats.isDirectory())
+        return [];
+    return readdirSync(join(projectRoot, relative)).flatMap((entry) => filesUnder(projectRoot, `${relative}/${entry}`));
+}
+export function copyBehavioralRunnerEnvironment(sourceRoot, targetRoot, runner) {
+    const entries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
+    for (const entry of entries) {
+        const source = join(sourceRoot, BEHAVIORAL_DIR, entry);
+        if (!existsSync(source))
+            continue;
+        const target = join(targetRoot, BEHAVIORAL_DIR, entry);
+        mkdirSync(dirname(target), { recursive: true });
+        cpSync(source, target, { recursive: true });
+    }
+}
 const EMPTY_ENTRIES = new Set();
 const RUNNER_ENVIRONMENT_ENTRIES = {
     cucumber: new Set(['.bundle', 'Gemfile', 'Gemfile.lock']),

package/dist/files/suiteBuild.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
@@ -7,11 +8,170 @@ export function requestPath(projectRoot) {
 export function outputPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'suite_output.json');
 }
-export function writeSuiteBuildRequest(projectRoot, branches) {
+export function reviewOutputPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'behavioral_review.json');
+}
+export function reviewRequestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'review-request.json');
+}
+export function candidateRunPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'candidate-run.json');
+}
+export function writeBehavioralReviewRequest(projectRoot, output, candidateRun, knownDefectContext = { status: 'not_supplied' }, fixedCandidateRun) {
+    const metadata = output.test_metadata;
+    const candidateDigest = suiteCandidateDigest(output);
+    const evidence = {
+        candidate_digest: candidateDigest,
+        known_defect_context: knownDefectContext,
+        candidate_run: { candidate_digest: candidateDigest, ...candidateRun },
+        ...(fixedCandidateRun ? {
+            fixed_candidate_run: { candidate_digest: candidateDigest, ...fixedCandidateRun },
+        } : {}),
+    };
+    writeArtifact(candidateRunPath(projectRoot), evidence);
+    const request = {
+        candidate_digest: candidateDigest,
+        suite_file: output.suite_file,
+        capabilities: metadata?.capabilities,
+        output_path: reviewOutputPath(projectRoot),
+        known_defect_context: knownDefectContext,
+        // Only a supplied defect gives the reviewer something to read a run for.
+        ...(knownDefectContext.status === 'supplied' ? {
+            candidate_run: evidence.candidate_run,
+            ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
+        } : {}),
+    };
+    writeArtifact(reviewRequestPath(projectRoot), request);
+    return request;
+}
+function writeArtifact(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+// The connector-owned runner strategy this branch selected. Reading it out of
+// the envelope is transport, like every other `runner_manifest` access in this
+// module — callers only ever get back the strategy name they dispatch on.
+export function branchRunner(output) {
+    const manifest = output.runner_manifest;
+    const runner = manifest?.runner;
+    if (typeof runner !== 'string' || !runner) {
+        throw new Error('The behavioral candidate names no runner strategy to execute.');
+    }
+    return runner;
+}
+export function suiteCandidateDigest(output) {
+    return createHash('sha256')
+        .update(stableJson({
+        suite_file: output.suite_file,
+        runner_manifest: output.runner_manifest,
+        test_metadata: output.test_metadata,
+    }))
+        .digest('hex');
+}
+// Everything the server strips back out before it recomputes the candidate
+// digest. The generator owns none of it, and if it writes any of these keys the
+// two sides hash different objects — which surfaces as "this review is about a
+// different candidate", blaming the reviewer for the generator's mistake. Refuse
+// it here, where the real cause can still be named.
+const POST_CANDIDATE_METADATA_KEYS = [
+    'bdd_quality_review',
+    'known_defect_probe',
+    'known_defect_context',
+    'candidate_run',
+    'fixed_candidate_run',
+];
+export function readBehavioralReview(projectRoot, output) {
+    const metadata = output.test_metadata;
+    const embedded = metadata ? POST_CANDIDATE_METADATA_KEYS.filter((key) => key in metadata) : [];
+    if (embedded.length > 0) {
+        throw new Error(`The behavioral suite generator must not embed its own review (found ${embedded.join(', ')} in test_metadata); run \`unitbob suite-review-prepare\` and provide the separate review artifact.`);
+    }
+    const path = reviewOutputPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`unitbob suite-review-prepare\` and have an independent reviewer write it.`);
+    }
+    const review = parseJson(readFileSync(path, 'utf8'), path);
+    if (!review || review.candidate_digest !== suiteCandidateDigest(output)) {
+        throw new Error(`${path} ${staleReviewReason(projectRoot, review, output)}`);
+    }
+    if (!('bdd_quality_review' in review) || !('known_defect_probe' in review)) {
+        throw new Error(`${path} must contain bdd_quality_review and known_defect_probe.`);
+    }
+    const evidence = readCandidateRunEvidence(projectRoot, output);
+    return {
+        ...review,
+        candidate_run: evidence.candidate_run,
+        ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
+    };
+}
+// Why a review does not bind — two different mistakes with one symptom.
+//
+// The likelier one, now that a branch may answer with a bare `{ path }`: the
+// review was right when it was written, and the candidate changed afterwards.
+// Editing one step file is enough, and nothing in the answer has to change for
+// it — so the digest moves with no visible cause, and "this does not review the
+// current candidate" sends the reader off to audit the reviewer instead of their
+// own last edit.
+//
+// The connector's own evidence file settles which mistake it was: it carries the
+// digest of the candidate that was actually run at review time. Agreeing with
+// the review and disagreeing with what is on disk now means the candidate moved
+// after the review. Otherwise the review really is about a different candidate.
+function staleReviewReason(projectRoot, review, output) {
+    const evidencePath = candidateRunPath(projectRoot);
+    if (review && existsSync(evidencePath)) {
+        const evidence = parseJson(readFileSync(evidencePath, 'utf8'), evidencePath);
+        if (evidence && evidence.candidate_digest === review.candidate_digest) {
+            return 'reviewed this suite as it stood at review time, and it has changed since — re-run ' +
+                '`unitbob suite-review-prepare` and have the reviewer look at the changed suite.';
+        }
+    }
+    return 'does not review the current behavioral suite candidate.';
+}
+// The runs the connector made of this exact candidate, and the defect choice
+// they were made under. One file, read on its own: the evidence the upload
+// carries must not depend on what the reviewer was shown, and reaching back into
+// the reviewer's request for the defect choice would have re-created exactly
+// that dependency.
+function readCandidateRunEvidence(projectRoot, output) {
+    const path = candidateRunPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`unitbob suite-review-prepare\` to record the candidate's run.`);
+    }
+    const file = parseJson(readFileSync(path, 'utf8'), path);
+    const digest = suiteCandidateDigest(output);
+    if (!file || file.candidate_digest !== digest || !isRunEvidence(file.candidate_run, digest)) {
+        throw new Error(`${path} has no connector runner evidence for the current behavioral candidate.`);
+    }
+    // Demanded, not defaulted. `readKnownDefectContext` reads a missing field as
+    // `not_supplied`, which is right for a file someone else may have written and
+    // wrong here: the connector writes this one itself, always with the choice it
+    // was given. Missing means the file is damaged, and taking it as "no defect
+    // was supplied" would turn that into a silently skipped fixed-revision check.
+    if (file.known_defect_context === undefined) {
+        throw new Error(`${path} records no known_defect_context — run \`unitbob suite-review-prepare\` again.`);
+    }
+    const context = readKnownDefectContext(file.known_defect_context, path);
+    if (context.status === 'supplied' && context.fixed_revision) {
+        const fixed = file.fixed_candidate_run;
+        if (!isRunEvidence(fixed, digest) || fixed?.revision !== context.fixed_revision) {
+            throw new Error(`${path} has no connector runner evidence for fixed revision ${context.fixed_revision}.`);
+        }
+    }
+    return file;
+}
+function isRunEvidence(value, digest) {
+    const run = value;
+    return Boolean(run && run.candidate_digest === digest &&
+        typeof run.revision === 'string' && run.revision &&
+        typeof run.run_result === 'string' && run.run_result);
+}
+export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }) {
     const request = {
         project_root: projectRoot,
         output_path: outputPath(projectRoot),
         branches,
+        known_defect_context: knownDefectContext,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -30,7 +190,31 @@ export function readSuiteBuildRequest(projectRoot) {
         !Array.isArray(request.branches)) {
         throw new Error(`${path} is malformed: expected project_root, output_path, and a branches array.`);
     }
-    return request;
+    return {
+        ...request,
+        known_defect_context: readKnownDefectContext(request.known_defect_context, path),
+    };
+}
+function readKnownDefectContext(value, path) {
+    if (value === undefined)
+        return { status: 'not_supplied' };
+    if (!value || typeof value !== 'object')
+        throw new Error(`${path}: known_defect_context must be an object.`);
+    const context = value;
+    if (context.status === 'not_supplied')
+        return { status: 'not_supplied' };
+    if (context.status !== 'supplied' || typeof context.defect !== 'string' || !context.defect.trim()) {
+        throw new Error(`${path}: supplied known_defect_context must name a defect.`);
+    }
+    if (context.fixed_revision !== undefined &&
+        (typeof context.fixed_revision !== 'string' || !context.fixed_revision.trim())) {
+        throw new Error(`${path}: fixed_revision must be a non-empty string.`);
+    }
+    return {
+        status: 'supplied',
+        defect: context.defect,
+        ...(context.fixed_revision ? { fixed_revision: context.fixed_revision } : {}),
+    };
 }
 // 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
@@ -47,9 +231,9 @@ export function readHostSuiteOutputs(path, request) {
         throw new Error(`${path} is malformed: expected a branches array, one entry per contract system.`);
     }
     const rootFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.path_root]));
-    return branches.map((entry) => readBranch(entry, rootFor, path));
+    return branches.map((entry) => readBranch(entry, rootFor, path, request.project_root));
 }
-function readBranch(entry, rootFor, path) {
+function readBranch(entry, rootFor, path, projectRoot) {
     if (!entry || typeof entry !== 'object') {
         throw new Error(`${path} is malformed: each branch must be an object.`);
     }
@@ -75,32 +259,64 @@ function readBranch(entry, rootFor, path) {
     }
     return {
         suite_kind: suiteKind,
-        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind),
+        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind, projectRoot),
         runner_manifest: manifest,
         test_metadata: branch.test_metadata,
     };
 }
-// 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) {
+// Each path is checked safe under this branch's root before anything is
+// accepted. `content` may be inlined, but it does not have to be: the host wrote
+// and ran these files on disk before answering, so a bare `{ path }` means "the
+// file already under that path is the answer". Re-serializing a whole suite into
+// this JSON on every rebuild was the single largest cost in the build loop, and
+// the copy was never more trustworthy than the file that was actually executed.
+function resolveSuiteFile(file, root, path, suiteKind, projectRoot) {
     if (!file || typeof file !== 'object') {
         throw new Error(`${path}: the ${suiteKind} branch is missing suite_file.`);
     }
     const envelope = file;
-    const main = readOneFile(envelope, root, path, suiteKind, false);
+    const main = readOneFile(envelope, root, path, suiteKind, false, projectRoot);
     const support = Array.isArray(envelope.support_files)
-        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true))
+        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true, projectRoot))
         : [];
     return support.length > 0 ? { ...main, support_files: support } : main;
 }
-function readOneFile(file, root, path, suiteKind, support) {
+function readOneFile(file, root, path, suiteKind, support, projectRoot) {
     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 };
     }
-    const label = support ? 'support file' : 'suite_file';
-    throw new Error(`${path}: the ${suiteKind} ${label} at "${filePath}" has no inline content.`);
+    if (file.content !== undefined) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" has empty content.`);
+    }
+    const onDisk = join(projectRoot, filePath);
+    if (!existsSync(onDisk)) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} names "${filePath}", but no such file exists — write it before answering, or inline its content.`);
+    }
+    // `assertUnitbobPath` judges the path text; it cannot see that a safe-looking
+    // name is a link out of the suite root — nor that the directory holding it is.
+    // Inlined content could never reach outside the answer, so reading from disk
+    // is where that check has to be made: these bytes are uploaded.
+    //
+    // Only the project root is resolved, and the suite root is then joined onto it
+    // as text. Resolving the suite root too would let a linked `.unitbob/<kind>/`
+    // vouch for itself — every file under it resolves neatly under the link's own
+    // target. Resolving nothing at all would fail honest projects instead, because
+    // a macOS temp or home path is itself reached through a link.
+    // The wire's `path_root` carries a trailing slash; `join` keeps it.
+    const suiteRoot = join(realpathSync(projectRoot), root).replace(/[\\/]+$/, '');
+    if (!realpathSync(onDisk).startsWith(`${suiteRoot}${sep}`)) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" resolves outside the suite root — suite files must be real files under it.`);
+    }
+    const content = readFileSync(onDisk, 'utf8');
+    if (!content.trim()) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" is empty.`);
+    }
+    return { path: filePath, content };
+}
+function fileLabel(support) {
+    return support ? 'support file' : 'suite_file';
 }
 function parseJson(raw, path) {
     try {
@@ -110,6 +326,15 @@ function parseJson(raw, path) {
         throw new Error(`${path} is not valid JSON (${err.message})`);
     }
 }
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
 // Turn a branch's assignment packet into its recipe name: structural uses the
 // unit-guardrail recipe, behavioral the Gherkin one.
 export function recipeNameFor(packet) {

package/dist/verbs/putSuiteBuild.js

@@ -1,4 +1,4 @@
-import { readHostSuiteOutputs, readSuiteBuildRequest } from "../files/suiteBuild.js";
+import { readBehavioralReview, readHostSuiteOutputs, readSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { Wire } from "../wire.js";
 // 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
@@ -20,13 +20,36 @@ export async function putSuiteBuild(config, _args = [], deps) {
         if (output.build_error) {
             return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
         }
+        let testMetadata = output.test_metadata;
+        if (output.suite_kind === 'behavioral') {
+            const review = readBehavioralReview(config.projectRoot, output);
+            const probe = review.known_defect_probe;
+            const qualityReview = review.bdd_quality_review;
+            if (!qualityReview || typeof qualityReview !== 'object') {
+                throw new Error('The separate behavioral review must contain a bdd_quality_review object.');
+            }
+            if (request.known_defect_context.status === 'supplied' && probe?.status === 'not_supplied') {
+                throw new Error('A known defect was supplied to suite-prepare, but the behavioral review marked it not_supplied.');
+            }
+            testMetadata = {
+                ...output.test_metadata,
+                bdd_quality_review: {
+                    ...qualityReview,
+                    candidate_digest: review.candidate_digest,
+                },
+                known_defect_probe: review.known_defect_probe,
+                known_defect_context: request.known_defect_context,
+                candidate_run: review.candidate_run,
+                ...(review.fixed_candidate_run ? { fixed_candidate_run: review.fixed_candidate_run } : {}),
+            };
+        }
         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,
+                test_metadata: testMetadata,
             },
         };
     });

package/dist/verbs/suitePrepare.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { materializeHelper } from "../files/guardrails.js";
-import { recipeNameFor, writeSuiteBuildRequest } from "../files/suiteBuild.js";
+import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { anyStackPrecheck } from "../runner/precheck.js";
 import { ensureRunner } from "../runner/provision.js";
 import { Wire } from "../wire.js";
@@ -13,7 +13,8 @@ import { Wire } from "../wire.js";
 // 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) {
+export async function suitePrepare(config, args = [], deps) {
+    const defectContext = knownDefectContext(args);
     const wire = new Wire(config);
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
@@ -55,12 +56,15 @@ export async function suitePrepare(config, _args = [], deps) {
         recipe: await actual.getRecipe(recipeNameFor(packet)),
         assignment: packet.assignment,
     })));
-    const request = writeSuiteBuildRequest(config.projectRoot, branches);
+    const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
     const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
+    const nextCommand = branches.some((branch) => branch.suite_kind === 'behavioral')
+        ? '`unitbob suite-review-prepare` before upload'
+        : '`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 to green, ` +
-        'then run `unitbob put-suite-build`.\n');
+        `write your answer to ${request.output_path} as a branches array, run each locally, 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.
     if (fixableNotices.length > 0) {
@@ -70,6 +74,32 @@ export async function suitePrepare(config, _args = [], deps) {
             '\nFix the above, then re-run `unitbob suite-prepare` to build the behavioral peer.\n');
     }
 }
+function knownDefectContext(args) {
+    const defect = option(args, '--known-defect=');
+    const fixedRevision = option(args, '--fixed-revision=');
+    const explicitlyAbsent = args.includes('--no-known-defect');
+    if ((defect && explicitlyAbsent) || (!defect && !explicitlyAbsent)) {
+        throw new Error('Choose exactly one of --known-defect or --no-known-defect (use --known-defect=<description>).');
+    }
+    if (fixedRevision && !defect)
+        throw new Error('--fixed-revision requires --known-defect.');
+    if (explicitlyAbsent)
+        return { status: 'not_supplied' };
+    if (!defect)
+        throw new Error('--known-defect requires a value.');
+    return {
+        status: 'supplied',
+        defect,
+        ...(fixedRevision ? { fixed_revision: fixedRevision } : {}),
+    };
+}
+function option(args, prefix) {
+    const match = args.find((arg) => arg.startsWith(prefix));
+    const value = match?.slice(prefix.length).trim();
+    if (match && !value)
+        throw new Error(`${prefix.slice(0, -1)} requires a value.`);
+    return value || undefined;
+}
 function inferBddRunner(projectRoot) {
     if (existsSync(join(projectRoot, 'package.json')))
         return 'cucumber-js';

package/dist/verbs/suiteReviewPrepare.js

@@ -0,0 +1,108 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBehavioral, } from "../files/behavioral.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { boundReport } from "../runner/boundReport.js";
+import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
+export async function suiteReviewPrepare(config, _args = [], deps) {
+    const actual = {
+        runCandidate: runCandidate,
+        stdout: process.stdout,
+        ...deps,
+    };
+    const buildRequest = readSuiteBuildRequest(config.projectRoot);
+    const behavioral = readHostSuiteOutputs(buildRequest.output_path, buildRequest)
+        .find((branch) => branch.suite_kind === 'behavioral');
+    if (!behavioral)
+        throw new Error('The suite build has no behavioral candidate to review.');
+    if (behavioral.build_error) {
+        throw new Error(`The behavioral candidate could not be reviewed: ${behavioral.build_error.message}`);
+    }
+    // Say this before the run, not after: the run materializes the answer, and
+    // that is where a forgotten file turns into undefined steps — by then it is
+    // already gone.
+    const lost = filesLostOnMaterialize(config.projectRoot, behavioral.suite_file, branchRunner(behavioral));
+    if (lost.length > 0) {
+        actual.stdout.write(`Warning: these files sit with the suite but are not in its answer, and running it will delete them: ${lost.join(', ')}.\n`);
+    }
+    const candidateRun = await actual.runCandidate(config.projectRoot, behavioral);
+    const fixedRevision = buildRequest.known_defect_context.status === 'supplied'
+        ? buildRequest.known_defect_context.fixed_revision
+        : undefined;
+    const fixedCandidateRun = fixedRevision
+        ? await actual.runCandidate(config.projectRoot, behavioral, fixedRevision)
+        : undefined;
+    const request = writeBehavioralReviewRequest(config.projectRoot, behavioral, candidateRun, buildRequest.known_defect_context, fixedCandidateRun);
+    actual.stdout.write(`Behavioral review request written to ${reviewRequestPath(config.projectRoot)}\n`);
+    actual.stdout.write(`Next: have an independent reviewer inspect this exact candidate and write bdd_quality_review and known_defect_probe to ${request.output_path}, then run \`unitbob put-suite-build\`.\n`);
+}
+async function runCandidate(projectRoot, output, revision) {
+    if (revision)
+        return runCandidateAtRevision(projectRoot, output, revision);
+    return runCandidateInProject(projectRoot, output, gitRevision(projectRoot));
+}
+async function runCandidateInProject(projectRoot, output, revision) {
+    const runner = branchRunner(output);
+    const suiteFile = output.suite_file;
+    const mainPath = materializeBehavioral(projectRoot, suiteFile, runner).mainPath;
+    const result = await runBddSuite(projectRoot, runner, mainPath);
+    const report = boundReport(runner, result);
+    if (report === null)
+        throw new Error('The behavioral candidate produced no machine-readable runner report.');
+    return { revision, run_result: report };
+}
+async function runCandidateAtRevision(projectRoot, output, revision) {
+    const resolved = execFileSync('git', ['rev-parse', '--verify', revision], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+    }).trim();
+    const worktree = mkdtempSync(join(tmpdir(), 'unitbob-fixed-review-'));
+    let added = false;
+    try {
+        execFileSync('git', ['worktree', 'add', '--detach', worktree, resolved], { cwd: projectRoot, stdio: 'pipe' });
+        added = true;
+        const runner = branchRunner(output);
+        materializeBehavioral(worktree, output.suite_file, runner);
+        copyBehavioralRunnerEnvironment(projectRoot, worktree, runner);
+        return await runCandidateInProject(worktree, output, revision);
+    }
+    finally {
+        if (added) {
+            try {
+                execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd: projectRoot, stdio: 'pipe' });
+            }
+            catch {
+                // The temporary directory cleanup below is still safe and bounded.
+            }
+        }
+        rmSync(worktree, { recursive: true, force: true });
+        if (added) {
+            try {
+                // `remove` can fail while the directory still goes away just above,
+                // which leaves a dangling entry under .git/worktrees in the user's own
+                // checkout. Reviewing a suite must not litter the repository it reads.
+                execFileSync('git', ['worktree', 'prune'], { cwd: projectRoot, stdio: 'pipe' });
+            }
+            catch {
+                // Housekeeping only — never fail a finished review run over it.
+            }
+        }
+    }
+}
+function gitRevision(projectRoot) {
+    try {
+        const options = {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        const head = execFileSync('git', ['rev-parse', 'HEAD'], options).trim();
+        const dirty = execFileSync('git', ['status', '--porcelain'], options).trim();
+        return dirty ? `${head}-dirty` : head;
+    }
+    catch {
+        return 'working-tree';
+    }
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "unitbob",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "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": {
-    "unitbob": "dist/cli.js"
+    "unitbob": "dist/bin.js"
   },
   "files": [
     "dist"
@@ -13,7 +13,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
     "test": "node --test test/*.test.ts"
   },