unitbob 0.7.8 → 0.7.12

package/dist/runner/gitRevision.js

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+// The revision a connector-made run was taken at, for the server's record:
+// `git rev-parse HEAD`, with `-dirty` when the tree has changes, or a word
+// when there is no git to ask. Read by the known-defect probe (the review)
+// and by the proof of red of a feature's checks (spec 52-3), from one place.
+export 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/dist/runner/manifest.js

@@ -24,7 +24,9 @@ export function withInstalledRunnerVersion(envelope, runner, projectRoot) {
 const BEHAVIORAL_DIR = '.unitbob/behavioral';
 // Matches the server's own PINNED_VERSION: a digit, then version characters.
 const PINNED_VERSION = /^[0-9][0-9A-Za-z.\-+]*$/;
-function installedRunnerVersion(runner, projectRoot) {
+// Exported for a feature's checks (spec 52-3), which take the runner from the
+// main suite rather than from a selection and still owe the server its version.
+export function installedRunnerVersion(runner, projectRoot) {
     const root = join(projectRoot, BEHAVIORAL_DIR);
     const found = readInstalledVersion(runner, root);
     return found && PINNED_VERSION.test(found) ? found : null;

package/dist/runner/outputTail.js

@@ -0,0 +1,13 @@
+// The end of what a run printed, stderr first: enough to see why a runner
+// died, not the whole log. One place for the three verbs that print it
+// (`check`, `run-local`, `put-tests`); `run-local` asks for more because the
+// person is reading it in a loop, `check` files it into a suite error.
+export function outputTail(result, limit) {
+    const bits = [];
+    if (result.stderr.trim())
+        bits.push(result.stderr.trim());
+    if (result.stdout.trim())
+        bits.push(result.stdout.trim());
+    const joined = bits.join('\n');
+    return joined.length > limit ? joined.slice(-limit) : joined;
+}

package/dist/runner/pytestBddPlugin.js

@@ -7,6 +7,13 @@
 //
 // It only records — it never reconciles markers or aggregates capabilities. It
 // is connector-owned and never part of the LLM-generated step definitions.
+//
+// A step with no definition is recorded too (spec 52-3, AC 3.7): pytest-bdd
+// calls `pytest_bdd_step_func_lookup_error` for it and never `after_step`, so
+// without this hook the scenario went into the report as `passed` with no
+// steps — and a feature's checks, which have to prove they are red, could
+// have passed that proof on wiring nobody wrote. The server's parser refuses
+// an `undefined` step as a broken suite, which is the honest answer.
 export const PYTEST_BDD_PLUGIN = `# Written by the unitbob connector — do not edit.
 import json
 import os
@@ -62,6 +69,14 @@ def pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func
     _record_step(scenario, step, "failed")
 
 
+def pytest_bdd_step_func_lookup_error(request, feature, scenario, step, 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, "undefined")
+
+
 def pytest_bdd_after_scenario(request, feature, scenario):
     entry = _UNITBOB_CURRENT.pop(id(scenario), None)
     if entry is not None:

package/dist/verbs/contractPrompt.js

@@ -5,21 +5,40 @@ import { Wire } from "../wire.js";
 // 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.
+//
+// `feature:<id>` stands in for the digest (spec 52-4, AC 1.3): a feature's
+// checks are not on the map to copy one from, so the id is resolved to
+// the digest of the feature's current checks through the same index `check`
+// runs from. The server words the brief itself, and answers 422 to `accept` —
+// a feature's scenarios change through the talk, not through an accept.
 export async function contractPrompt(config, args = [], deps) {
-    const suiteDigest = (args[0] ?? '').trim();
+    const selector = (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 (!selector || !testId) {
+        throw new Error('Usage: unitbob contract-prompt <suite_digest>|feature:<id> <test_id> [fix|accept]');
     }
     if (intent !== 'fix' && intent !== 'accept') {
         throw new Error(`intent must be "fix" or "accept" (got "${intent}").`);
     }
+    const wire = new Wire(config);
     const d = {
-        getContractPrompt: (digest, id, action) => new Wire(config).getContractPrompt(digest, id, action),
+        getContractPrompt: (digest, id, action) => wire.getContractPrompt(digest, id, action),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         stdout: process.stdout,
         ...deps,
     };
+    const suiteDigest = selector.startsWith(FEATURE_SELECTOR) ? await featureDigest(d, selector.slice(FEATURE_SELECTOR.length)) : selector;
     const packet = await d.getContractPrompt(suiteDigest, testId, intent);
     d.stdout.write(`${packet.message}\n\n${packet.prompt}\n`);
 }
+const FEATURE_SELECTOR = 'feature:';
+// The digest of the feature's current checks. Only a feature being built has
+// them in the index: before the checks are written there is nothing to act on,
+// and after Finish they are part of the main suite, on the map like the rest.
+async function featureDigest(d, id) {
+    const item = (await d.getSuiteIndex()).feature_suites.find((entry) => String(entry.feature_id) === id);
+    if (!item)
+        throw new Error(`No feature ${id} has checks to act on — it is not being built, or it is finished.`);
+    return item.suite_digest;
+}

package/dist/verbs/featurePrepare.js

@@ -0,0 +1,49 @@
+import { requestPath, writeFeatureStartRequest } from "../files/featureStart.js";
+import { Wire } from "../wire.js";
+// Fetch the recipe and the behavioral assignment — the product capabilities of
+// the current map, with what each promises and where in the checkout it lives —
+// and write the host's task to `.unitbob/feature-start/request.json` (spec
+// 52-1). One request for the list, the same one `suite-prepare` makes; today's
+// check statuses are not asked for, because they belong on the feature's page
+// and not in the judgement of what the work may touch. No model is called,
+// no source is read, nothing is uploaded. A 409 (no current map) surfaces as a
+// WireError with the server's guidance and nothing is written.
+export async function featurePrepare(config, _args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const [recipe, packets] = await Promise.all([d.getRecipe('feature_intent'), d.getSuitePacketsBatch()]);
+    const behavioral = packets.find((packet) => packet.suite_kind === 'behavioral');
+    if (!behavioral) {
+        throw new Error('The Unitbob server sent no behavioral assignment with the suite packets — it is older than this connector. ' +
+            'Update the server (or the connector) so the two agree, then retry.');
+    }
+    writeFeatureStartRequest(config.projectRoot, recipe, capabilitiesOf(behavioral));
+    d.stdout.write(`Feature request written to ${requestPath(config.projectRoot)}\n`);
+}
+// The six fields the recipe names, in the shape it names them. The contract
+// identity (`contract_key`, `case_marker`) rides in the assignment for the
+// suite recipe and is not copied: the host is naming what may be touched, not
+// writing tests.
+function capabilitiesOf(packet) {
+    const assignment = (packet.assignment ?? {});
+    const list = Array.isArray(assignment.capabilities) ? assignment.capabilities : [];
+    return list.map((entry) => {
+        const item = (typeof entry === 'object' && entry !== null ? entry : {});
+        return {
+            capability_id: String(item.capability_id ?? ''),
+            title: String(item.title ?? ''),
+            description: String(item.description ?? ''),
+            surfaces: strings(item.surfaces),
+            tables: strings(item.tables),
+            externals: strings(item.externals),
+        };
+    });
+}
+function strings(value) {
+    return Array.isArray(value) ? value.map((one) => String(one)) : [];
+}

package/dist/verbs/knowledgePrepare.js

@@ -0,0 +1,39 @@
+import { knowledgeRequestPath, parseFeatureId, writeKnowledgeRequest } from "../files/features.js";
+import { Wire } from "../wire.js";
+// The statuses a feature can be talked through in: not yet talked through,
+// talked through and open to a second talk (spec 52-2, AC 2.1), or its checks
+// written — a talk then withdraws them, out loud (spec 52-3, AC 2.9).
+const TALKABLE = new Set(['intent', 'knowledge', 'red']);
+// Two forms (spec 52-2, AC 2.1). Without an id, the list: one line per feature
+// the talk can start on, so the host finds the one the person means by its
+// words — and the server's own sentence when there is none; the connector
+// words no state of its own. With an id, the host's task: the recipe and the
+// packet the server built, written to `.unitbob/features/<id>/request.json`
+// next to where `knowledge.md` will go. No model is called, nothing is
+// uploaded.
+export async function knowledgePrepare(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        listFeatures: () => wire.listFeatures(),
+        getRecipe: (name) => wire.getRecipe(name),
+        getKnowledgePacket: (id) => wire.getKnowledgePacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    if (args.length === 0) {
+        const list = await d.listFeatures();
+        const talkable = list.features.filter((feature) => TALKABLE.has(feature.status));
+        if (talkable.length === 0) {
+            d.stdout.write(`${list.empty_text}\n`);
+            return;
+        }
+        for (const feature of talkable) {
+            d.stdout.write(`${feature.feature_id}  ${feature.title} (${feature.status})\n`);
+        }
+        return;
+    }
+    const featureId = parseFeatureId(args[0], 'knowledge-prepare');
+    const [recipe, packet] = await Promise.all([d.getRecipe('feature_grill'), d.getKnowledgePacket(featureId)]);
+    writeKnowledgeRequest(config.projectRoot, featureId, recipe, packet);
+    d.stdout.write(`Knowledge request written to ${knowledgeRequestPath(config.projectRoot, featureId)}\n`);
+}

package/dist/verbs/mapPrepare.js

@@ -1,7 +1,7 @@
 import { ensureUnitbobIgnored, ignoreExclusions, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
 import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
 import { describeRouteInventory, extractRouteInventory, } from "../surfaces/routeInventory.js";
-import { Wire } from "../wire.js";
+import { Wire, WireError } from "../wire.js";
 export async function mapPrepare(config, _args = [], deps) {
     const wire = new Wire(config);
     const actual = {
@@ -10,7 +10,9 @@ export async function mapPrepare(config, _args = [], deps) {
         runGraphifyExtractKeyless,
         extractRouteInventory,
         getRecipe: (name) => wire.getRecipe(name),
+        listFeatures: () => wire.listFeatures(),
         stdout: process.stdout,
+        stderr: process.stderr,
         ...deps,
     };
     actual.ensureUnitbobIgnored(config.projectRoot);
@@ -44,18 +46,19 @@ export async function mapPrepare(config, _args = [], deps) {
     // us there reads as a hang.
     actual.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
     const inventory = await actual.extractRouteInventory(config.projectRoot);
-    const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
+    const [decompose, relate, extractSurfaces, decomposeSurfaces, existing] = await Promise.all([
         actual.getRecipe('decompose'),
         actual.getRecipe('relate'),
         actual.getRecipe('extract_surfaces'),
         actual.getRecipe('decompose_surfaces'),
+        existingCapabilities(actual),
     ]);
     const packet = writeMapBuildRequest(config.projectRoot, {
         decompose,
         relate,
         extract_surfaces: extractSurfaces,
         decompose_surfaces: decomposeSurfaces,
-    }, inventory.status === 'written' ? inventory.path : undefined);
+    }, inventory.status === 'written' ? inventory.path : undefined, existing);
     actual.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
     actual.stdout.write(`${describeRouteInventory(inventory)}\n`);
     actual.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
@@ -63,3 +66,26 @@ export async function mapPrepare(config, _args = [], deps) {
         `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
         'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');
 }
+// The capabilities finished features added to the map (spec 52-4, AC 5.1):
+// by id, title and the intent as said — no addresses, the recipe matches by
+// meaning. Only finished features: an open one is not on the map yet. A
+// server older than the fields sends rows without a capability id, and one
+// older than the route answers 404; both read as none, quietly, and the
+// recipe skips its paragraph (AC 7.3). Any other failure of the list is not
+// a reason to stop a map build either — but it is said, on stderr, because a
+// map built without the finished features' ids is one that may redraw them.
+async function existingCapabilities(d) {
+    let features;
+    try {
+        features = (await d.listFeatures()).features;
+    }
+    catch (err) {
+        if (!(err instanceof WireError && err.status === 404)) {
+            d.stderr.write(`Could not list finished features — the map is built without them: ${err.message}\n`);
+        }
+        return [];
+    }
+    return features
+        .filter((feature) => feature.status === 'done' && typeof feature.capability_id === 'string')
+        .map((feature) => ({ id: feature.capability_id, title: feature.title, description: feature.intent ?? '' }));
+}

package/dist/verbs/putFeature.js

@@ -0,0 +1,21 @@
+import { readFeatureAnswer } from "../files/featureStart.js";
+import { enterUrl } from "../links.js";
+import { Wire } from "../wire.js";
+// Read the host's answer and record the feature (spec 52-1). The server checks
+// every id against the current map and words the sentence; this prints it and
+// the link to the feature's page through the exchanger, like every link a
+// person gets from the terminal (spec 33). A 422 — an id not on the map — is
+// let through as a WireError with both id lists in its text, so the host
+// corrects its file and runs this again. Nothing is created locally: the
+// feature's folder, its knowledge file and its tests belong to later specs.
+export async function putFeature(config, _args = [], deps) {
+    const d = {
+        postFeature: (payload) => new Wire(config).postFeature(payload),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const answer = readFeatureAnswer(config.projectRoot);
+    const recorded = await d.postFeature(answer);
+    d.stdout.write(`${recorded.message}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+}

package/dist/verbs/putKnowledge.js

@@ -0,0 +1,21 @@
+import { parseFeatureId, readKnowledge } from "../files/features.js";
+import { enterUrl } from "../links.js";
+import { Wire } from "../wire.js";
+// Send `knowledge.md` as text (spec 52-2, AC 2.2) and print the server's
+// sentence and the link to the feature's page through the exchanger, like
+// every link a person gets from the terminal (spec 33). The shape is checked
+// on the server only (Non-Goals); a 422 comes back through the wire as a
+// WireError whose text already holds one line per problem, both sides, and
+// this lets it through so the host fixes the file and runs this again.
+export async function putKnowledge(config, args = [], deps) {
+    const d = {
+        putKnowledge: (id, knowledge) => new Wire(config).putKnowledge(id, knowledge),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'put-knowledge');
+    const text = readKnowledge(config.projectRoot, featureId);
+    const recorded = await d.putKnowledge(featureId, text);
+    d.stdout.write(`${recorded.message}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+}

package/dist/verbs/putTests.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { knowledgePath, parseFeatureId, readKnowledge, readTestsOutput, readTestsRequest, readTestsReviewOutput, testsReviewOutputPath, } from "../files/features.js";
+import { suiteCandidateDigest } from "../files/suiteBuild.js";
+import { enterUrl } from "../links.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { boundReport } from "../runner/boundReport.js";
+import { scenarioTally } from "../runner/failureDigest.js";
+import { gitRevision } from "../runner/gitRevision.js";
+import { placeAdvice } from "../runner/placeAdvice.js";
+import { placeProblem } from "../runner/place.js";
+import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
+import { outputTail } from "../runner/outputTail.js";
+import { Wire } from "../wire.js";
+const OUTPUT_TAIL_CHARS = 2000;
+// The digest of `knowledge.md` on disk against the one the request was written
+// from — both named when they differ, so the reader sees which side moved.
+export function assertKnowledgeUnchanged(projectRoot, featureId, expected) {
+    const got = createHash('sha256').update(readKnowledge(projectRoot, featureId)).digest('hex');
+    if (got === expected)
+        return;
+    throw new Error(`${knowledgePath(projectRoot, featureId)}: knowledge.md on disk differs from what the server has — ` +
+        `run put-knowledge first, or restore the file, then run this again.\nexpected: ${expected}\n     got: ${got}`);
+}
+// `put-tests <feature_id>` (spec 52-3, AC 3.5). The answer is read with its
+// files from disk; the candidate digest is the one the review uses; then the
+// connector runs the feature's tag itself — a report the host already has may
+// be from earlier and over other files, and the proof has to be over these
+// bytes. A runner that could not start or produced no report sends nothing:
+// what it said is printed, and the exit code is non-zero. A 409 or 422 comes
+// back as a WireError already worded by the server, one line per side, and is
+// let through as it is.
+//
+// What the run proves decides what travels with it (spec 52-4, AC 1.10). All
+// red: the run itself as `red_run`, revision and all, the way the known-defect
+// probe sends its own. All green with the reviewer's file beside the answer:
+// that file as `bdd_quality_review`, bound to this candidate. Anything else:
+// no proof — the harness was saved mid-build. A review over a run that is not
+// all green is not sent at all; a review of an older candidate is ignored out
+// loud. And once the server has taken the version, the same run is filed
+// under its digest, so the feature's page shows "N of M checks pass" on it at
+// once rather than on the version before.
+export async function putTests(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        runBehavioral: runBddSuite,
+        gitRevision,
+        putFeatureSuite: (id, upload) => wire.putFeatureSuite(id, upload),
+        postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'put-tests');
+    const request = readTestsRequest(config.projectRoot, featureId);
+    const output = readTestsOutput(config.projectRoot, featureId);
+    // The same check `tests-prepare` made, made again here: the file may have
+    // been edited in between, and the checks are sealed to the text the server
+    // has, not to the text on disk (spec 52-3, edge cases).
+    assertKnowledgeUnchanged(config.projectRoot, featureId, request.knowledge_digest);
+    const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
+    // The review file, before the run: one the connector cannot read is a
+    // stop, said in one line, and a run before it would be a run for nothing.
+    const candidateDigest = suiteCandidateDigest({
+        suite_kind: 'behavioral', suite_file: output.suite_file, runner_manifest: output.runner_manifest,
+    });
+    let review;
+    try {
+        review = readTestsReviewOutput(config.projectRoot, featureId);
+    }
+    catch (err) {
+        d.stdout.write(`${err.message}\n`);
+        d.stdout.write('Nothing was sent.\n');
+        return 1;
+    }
+    if (review && review.candidate_digest !== candidateDigest) {
+        d.stdout.write(`${testsReviewOutputPath(config.projectRoot, featureId)} is for an older candidate — ignored.\n`);
+        review = null;
+    }
+    let result;
+    try {
+        result = await d.runBehavioral(config.projectRoot, request.runner, request.feature_path, { only: request.feature_tag });
+    }
+    catch (err) {
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
+        d.stdout.write('Nothing was sent.\n');
+        return 1;
+    }
+    const report = boundReport(request.runner, result);
+    if (report === null) {
+        d.stdout.write(`The run produced no machine-readable report at ${result.resultPath} (exit code ${result.code}) — ` +
+            'it died before the first scenario rather than failing them.\n');
+        const tail = outputTail(result, OUTPUT_TAIL_CHARS);
+        if (tail)
+            d.stdout.write(`${tail}\n`);
+        d.stdout.write('Nothing was sent.\n');
+        return 1;
+    }
+    const tally = scenarioTally(request.runner, result.report);
+    const allRed = tally !== null && tally.passed === 0 && tally.failed > 0;
+    const allGreen = tally !== null && tally.failed === 0 && tally.passed > 0;
+    if (review && !allGreen) {
+        d.stdout.write(`Review the checks when they all pass — ${stillFailing(tally)}.\n`);
+        return 1;
+    }
+    const proof = review
+        ? { bdd_quality_review: { ...review.bdd_quality_review, candidate_digest: candidateDigest } }
+        : allRed
+            ? { red_run: { candidate_digest: candidateDigest, revision: d.gitRevision(config.projectRoot), run_result: report } }
+            : {};
+    const recorded = await d.putFeatureSuite(featureId, {
+        suite_file: output.suite_file,
+        runner_manifest: output.runner_manifest,
+        test_metadata: { ...output.test_metadata, ...proof },
+        knowledge_digest: request.knowledge_digest,
+    });
+    // Said before the run is filed: the upload is done whatever happens next,
+    // and a filing that fails leaves the run to the next `check`.
+    d.stdout.write(`${recorded.message}\n`);
+    const { results } = await d.postRunsBatch([{ suite_digest: recorded.suite_digest, run_result: report }]);
+    for (const item of results)
+        d.stdout.write(`${item.summary}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+    return 0;
+}
+// "2 of 5 still fail" — or, for a report the connector could not count, only
+// that it could not.
+function stillFailing(tally) {
+    if (tally === null)
+        return 'the run’s report could not be read scenario by scenario';
+    return `${tally.failed} of ${tally.passed + tally.failed} still fail`;
+}

package/dist/verbs/run.js

@@ -1,5 +1,5 @@
 import { materializeGuardrails } from "../files/guardrails.js";
-import { materializeBehavioral } from "../files/behavioral.js";
+import { FeatureFilesChangedError, materializeBehavioralUnion } from "../files/behavioral.js";
 import { placeProblem } from "../runner/place.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
@@ -7,6 +7,7 @@ import { runRspecSuite } from "../runner/rspec.js";
 import { runVitestSuite, testPathsOf } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { outputTail } from "../runner/outputTail.js";
 import { enterUrl } from "../links.js";
 import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
@@ -27,7 +28,7 @@ export async function runOnly(config, digests, deps) {
 function resolve(config, deps) {
     const wire = new Wire(config);
     return {
-        getSuites: () => wire.getSuites(),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         // The whole envelope, support files and all: a branch is a set of files
         // since spec one-place-per-rule, §6, and picking `path` and `content` out of it here was
@@ -37,7 +38,9 @@ function resolve(config, deps) {
             suite_file: item.suite_file,
             runner_manifest: item.runner_manifest,
         }),
-        materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file, item.runner_manifest.runner).mainPath,
+        // The union is never empty here: the caller only asks once the behavioral
+        // peer is ready or a feature has checks, so at least one envelope is in it.
+        materializeBehavioral: (projectRoot, index, runner) => materializeBehavioralUnion(projectRoot, index, runner),
         runStructural: runStructuralByRunner,
         runBehavioral: runBddSuite,
         validateStack,
@@ -52,16 +55,24 @@ async function execute(config, d, only) {
     const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
     if (unusable)
         throw new Error(`${unusable}\nNothing was run and no results were filed.`);
-    const suites = await d.getSuites();
-    const ready = suites.filter((item) => item.status === 'ready');
+    const index = await d.getSuiteIndex();
+    const ready = index.suites.filter((item) => item.status === 'ready');
     const selected = only === null ? ready : select(ready, only);
-    if (selected.length === 0) {
+    // The features' checks ride with the behavioral branch: every run of `check`
+    // has them, and the first run after publishing has them when the behavioral
+    // branch is what was published — structural alone has no union to run on.
+    const features = only === null || selected.some((item) => item.suite_kind === 'behavioral') ? index.feature_suites : [];
+    if (selected.length === 0 && features.length === 0) {
         d.stdout.write('No Unitbob suites exist yet. Generate them first, then run the Unitbob checks again.\n');
         return;
     }
+    const unionFor = unionOnce(config, d, index);
     const runs = [];
     for (const item of selected) {
-        runs.push(await buildRunPayload(config, d, item));
+        runs.push(await buildRunPayload(config, d, item, unionFor));
+    }
+    for (const item of features) {
+        runs.push(await buildFeatureRunPayload(config, d, item, unionFor));
     }
     const { results, map_url } = await d.postRunsBatch(runs);
     for (const result of results)
@@ -86,48 +97,88 @@ function select(ready, wanted) {
     }
     return wanted.map((digest) => byDigest.get(digest));
 }
+function unionOnce(config, d, index) {
+    let union = null;
+    return (runner) => {
+        if (union)
+            return union;
+        try {
+            union = d.materializeBehavioral(config.projectRoot, index, runner);
+        }
+        catch (err) {
+            // Not a branch's error to file and move past: the union refused to wipe
+            // a feature's rewired checks (spec 52-4, AC 1.8). Nothing was run,
+            // nothing is posted, and the sentence reaches the terminal through
+            // `cli.ts`.
+            if (err instanceof FeatureFilesChangedError)
+                throw err;
+            union = { error: err.message };
+        }
+        return union;
+    };
+}
 // 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) {
+async function buildRunPayload(config, d, item, unionFor) {
     const runner = item.runner_manifest.runner;
-    const behavioral = item.suite_kind === 'behavioral';
+    const digest = item.suite_digest;
     // 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)
+        return suiteError(digest, check.message ?? `Local project does not match "${runner}".`);
+    if (item.suite_kind !== 'behavioral') {
+        return filed(runner, digest, async () => {
+            d.materializeStructural(config.projectRoot, item);
+            return d.runStructural(config.projectRoot, runner, artifactPaths(item.suite_file));
+        });
+    }
+    const union = unionFor(runner);
+    if ('error' in union)
+        return suiteError(digest, union.error);
+    return filed(runner, digest, () => d.runBehavioral(config.projectRoot, runner, union.mainPath, { exclude: union.excludeTags }));
+}
+// One feature's run payload (spec 52-4, AC 1.1): the same checks a branch
+// gets, the same union, only its own tag — and its own suite error when it
+// cannot run, which stops nothing else.
+async function buildFeatureRunPayload(config, d, item, unionFor) {
+    const runner = item.runner_manifest.runner;
+    const check = d.validateStack(config.projectRoot, runner);
     if (!check.ok)
         return suiteError(item.suite_digest, check.message ?? `Local project does not match "${runner}".`);
+    const union = unionFor(runner);
+    if ('error' in union)
+        return suiteError(item.suite_digest, union.error);
+    return filed(runner, item.suite_digest, () => d.runBehavioral(config.projectRoot, runner, union.mainPath, { only: item.feature_tag }));
+}
+// The run itself, filed as this branch's payload: a runner that could not
+// start or a report that cannot be read is its structured suite error.
+async function filed(runner, digest, execute) {
     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, artifactPaths(item.suite_file));
-        }
+        result = await execute();
     }
     catch (err) {
-        return suiteError(item.suite_digest, err.message);
+        return suiteError(digest, err.message);
     }
     const report = boundReport(runner, result);
     if (report === null) {
         return {
-            suite_digest: item.suite_digest,
+            suite_digest: digest,
             suite_error: {
                 command: [result.command, ...result.args].join(' '),
                 exit_code: result.code,
                 result_path: result.resultPath,
-                output_tail: outputTail(result),
+                output_tail: outputTail(result, OUTPUT_TAIL_CHARS),
             },
         };
     }
-    return { suite_digest: item.suite_digest, run_result: report };
+    return { suite_digest: digest, run_result: report };
 }
 // Exported for `run-local`, which runs these same strategies against the files
 // the host just wrote rather than against a published suite. One dispatch table,
@@ -159,12 +210,3 @@ function suiteError(suiteDigest, message) {
         suite_error: { command: '', exit_code: null, result_path: '', output_tail: message },
     };
 }
-function outputTail(result) {
-    const bits = [];
-    if (result.stderr.trim())
-        bits.push(result.stderr.trim());
-    if (result.stdout.trim())
-        bits.push(result.stdout.trim());
-    const joined = bits.join('\n');
-    return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
-}