unitbob 0.7.8 → 0.7.12

package/dist/cli.js

@@ -25,6 +25,13 @@ import { suitePrepare } from "./verbs/suitePrepare.js";
 import { classifyPublication, putSuiteBuild } from "./verbs/putSuiteBuild.js";
 import { validateBuild } from "./verbs/validateBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
+import { featurePrepare } from "./verbs/featurePrepare.js";
+import { knowledgePrepare } from "./verbs/knowledgePrepare.js";
+import { putKnowledge } from "./verbs/putKnowledge.js";
+import { testsPrepare } from "./verbs/testsPrepare.js";
+import { putTests } from "./verbs/putTests.js";
+import { testsReviewPrepare } from "./verbs/testsReviewPrepare.js";
+import { putFeature } from "./verbs/putFeature.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
 import { acceptWorkerPlan } from "./verbs/acceptWorkerPlan.js";
@@ -62,11 +69,28 @@ Verbs:
                        then run every branch it published and report the server's results. Name a branch
                        to publish that one alone, as soon as it is finished; with no argument both are
                        expected, and one the answer never mentions is reported.
-  run-local [branch]   Internal: run the suite you just wrote, before publishing it, with the same runner
-                       that will run it afterwards. No argument runs every branch the build asked for.
+  run-local [branch] | --feature <id>
+                       Internal: run the suite you just wrote, before publishing it, with the same runner
+                       that will run it afterwards. No argument runs every branch the build asked for;
+                       --feature runs one feature's checks alone, by their tag.
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
-  contract-prompt <digest> <test_id> [fix|accept]
-                       Internal: fetch the fix/accept brief for one red check on either map.
+  contract-prompt <digest>|feature:<id> <test_id> [fix|accept]
+                       Internal: fetch the fix/accept brief for one red check on either map — or, with
+                       feature:<id>, the fix brief for a feature's own failing checks.
+  feature-prepare      Internal: fetch the recipe and the product capabilities, write the host
+                       feature-start request — for naming what a change may touch, before it is made.
+  put-feature          Internal: record the host's feature answer and print the link to its page.
+  knowledge-prepare    Internal: without an id, list the features that can be talked through; with
+                       one, fetch the recipe and the feature's packet and write the host request.
+  put-knowledge        Internal: send the feature's knowledge.md and print the link to its page.
+  tests-prepare <id>   Internal: fetch the feature's assignment and the recipe, put the suites on disk,
+                       and write the host request for its checks.
+  put-tests <id>       Internal: run the feature's checks and save the harness with that run as its
+                       proof (all red at first); with a review file beside the answer — publishes the review.
+                       Files the run under the saved version and prints the link to its page.
+  tests-review-prepare <id>
+                       Internal: write the independent reviewer's request for the feature's checks, once
+                       they all pass; put-tests then publishes the review it writes.
   check                Run every Unitbob contract suite locally and report.
   run                  Alias for check.
 
@@ -138,6 +162,30 @@ export async function main(argv, deps = { ensureLinked }) {
             case 'contract-prompt':
                 await contractPrompt(await linked(), args);
                 return 0;
+            case 'feature-prepare':
+                await featurePrepare(await linked(), args);
+                return 0;
+            case 'put-feature':
+                await putFeature(await linked(), args);
+                return 0;
+            case 'knowledge-prepare':
+                await knowledgePrepare(await linked(), args);
+                return 0;
+            case 'put-knowledge':
+                await putKnowledge(await linked(), args);
+                return 0;
+            case 'tests-prepare':
+                await testsPrepare(await linked(), args);
+                return 0;
+            case 'put-tests':
+                // Non-zero when the runner could not start or produced no report:
+                // nothing was sent, and the host has to read why (spec 52-3, AC 3.5).
+                // And when a review lies beside a run that is not all green (spec
+                // 52-4, AC 1.10) — nothing was sent then either.
+                return await putTests(await linked(), args);
+            case 'tests-review-prepare':
+                await testsReviewPrepare(await linked(), args);
+                return 0;
             case 'run-local':
                 // The one verb whose non-zero exit is not an error: a branch that failed
                 // the same set of cases twice in a row (spec 34-6, criterion 3). Red

package/dist/files/behavioral.js

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 import { BDD_RUN_ARTIFACTS } from "../runner/bdd.js";
@@ -290,14 +290,27 @@ export function materializeBehavioralWorld(projectRoot, runner = 'cucumber') {
 // behavioral root, after checking every path is safe. Stale suite artifacts are
 // removed while the separately provisioned runner environment is preserved.
 // Returns the absolute path of the materialized main file.
-export function materializeBehavioral(projectRoot, artifact, runner) {
-    const files = [artifact, ...(artifact.support_files ?? [])];
+//
+// `extras` are further envelopes written in the same pass (spec 52-3, AC 3.1):
+// the checks of every red feature, beside the main suite. One clearing, then
+// every file of every envelope; a path two envelopes both hold is refused by
+// name before anything is written — the server does not issue such a union,
+// and the disk could not carry it if it did.
+export function materializeBehavioral(projectRoot, artifact, runner, extras = []) {
+    const files = [artifact, ...extras].flatMap((envelope) => [envelope, ...(envelope.support_files ?? [])]);
     for (const file of files)
         assertUnitbobPath(file.path, BEHAVIORAL_DIR);
     const world = behavioralWorldFor(runner);
     if (world && files.some((file) => file.path === world.path)) {
         throw new Error(`${world.path} is the connector-owned World and cannot be supplied by the host artifact.`);
     }
+    const seen = new Set();
+    for (const file of files) {
+        if (seen.has(file.path)) {
+            throw new Error(`${file.path} is listed twice across the suites to materialize — one path, one file.`);
+        }
+        seen.add(file.path);
+    }
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     mkdirSync(behavioralRoot, { recursive: true });
@@ -317,6 +330,60 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     materializeBehavioralWorld(projectRoot, runner);
     return { mainPath };
 }
+// The main suite and the checks of every red feature, as one union on disk
+// (spec 52-3, AC 3.1), and the tags the ordinary run leaves out (3.2). The
+// main file is the main suite's when it is built, else the first feature's —
+// a union of checks alone, on a machine where the main suite is not built, is
+// legal. Null when there is nothing at all to write.
+//
+// Before anything is cleared, the feature files on disk are compared with the
+// ones the server holds (spec 52-4, AC 1.8): while a feature is being built
+// the host rewires its steps against the real code, and a union that wrote
+// the saved version over that work would lose it without a word. A difference
+// stops here, disk untouched, with the one command that saves it.
+export function materializeBehavioralUnion(projectRoot, index, runner) {
+    const changed = changedFeatureFiles(projectRoot, index.feature_suites);
+    if (changed.length > 0)
+        throw new FeatureFilesChangedError(changed[0].feature_id, changed[0].title);
+    const main = index.suites.find((item) => item.suite_kind === 'behavioral' && item.status === 'ready' && item.suite_file);
+    const envelopes = [...(main?.suite_file ? [main.suite_file] : []), ...index.feature_suites.map((item) => item.suite_file)];
+    if (envelopes.length === 0)
+        return null;
+    const [first, ...rest] = envelopes;
+    const { mainPath } = materializeBehavioral(projectRoot, first, runner, rest);
+    return { mainPath, excludeTags: index.feature_suites.map((item) => item.feature_tag) };
+}
+// The features whose checks on disk differ from the saved ones, with the
+// paths that differ: every file of the feature's envelope that is on disk,
+// compared by content. A file that is not on disk is not a change — the union
+// writes it, as it always has — and a feature with nothing on disk is not
+// listed at all.
+export function changedFeatureFiles(projectRoot, items) {
+    return items.flatMap((item) => {
+        const paths = [item.suite_file, ...(item.suite_file.support_files ?? [])]
+            .filter((file) => {
+            const onDisk = join(projectRoot, file.path);
+            return existsSync(onDisk) && readFileSync(onDisk, 'utf8') !== file.content;
+        })
+            .map((file) => file.path);
+        return paths.length > 0 ? [{ feature_id: item.feature_id, title: featureTitle(item), paths }] : [];
+    });
+}
+// The one sentence of AC 1.8, worded here and printed wherever the union is
+// materialised — `check`, `tests-prepare` — by the shared catch in `cli.ts`.
+export class FeatureFilesChangedError extends Error {
+    featureId;
+    constructor(featureId, title) {
+        super(`The checks for “${title}” changed on disk since they were saved. ` +
+            `Run \`npx unitbob put-tests ${featureId}\` to save them, then try again.`);
+        this.featureId = featureId;
+    }
+}
+// A server from spec 52-3 sends the item without a title; the id still names
+// the feature the command below takes.
+function featureTitle(item) {
+    return item.title ?? `feature ${item.feature_id}`;
+}
 // 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
@@ -327,11 +394,11 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
 // 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) {
+export function filesLostOnMaterialize(projectRoot, artifact, runner, extras = []) {
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     if (!existsSync(behavioralRoot))
         return [];
-    const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
+    const listed = new Set([artifact, ...extras].flatMap((envelope) => [envelope.path, ...(envelope.support_files ?? []).map((file) => file.path)]));
     const kept = behavioralKeptByConnector(runner);
     return readdirSync(behavioralRoot)
         .filter((entry) => !kept.has(entry))

package/dist/files/featureStart.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function requestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'feature-start', 'request.json');
+}
+export function outputPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'feature-start', 'feature.json');
+}
+export function writeFeatureStartRequest(projectRoot, recipe, capabilities) {
+    const request = {
+        project_root: projectRoot,
+        recipe,
+        capabilities,
+        behavioral_suite_path: presentDir(join(projectRoot, '.unitbob', 'behavioral')),
+        map_documents_path: presentDir(join(projectRoot, '.unitbob', 'map-build')),
+        output_path: outputPath(projectRoot),
+    };
+    const path = requestPath(projectRoot);
+    if (!existsSync(dirname(path)))
+        mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}
+// The host's answer in the wire shape, and nothing else: a field it added is
+// dropped here rather than sent on. Each check names the field it failed, so
+// the host corrects the file instead of guessing what was wrong with it.
+export function readFeatureAnswer(projectRoot) {
+    const path = outputPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`No feature answer at ${path}. Write it as the recipe describes, then run \`unitbob put-feature\`.`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err.message}`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`${path} must hold a JSON object with "title", "intent" and "affected".`);
+    }
+    const body = raw;
+    const title = nonEmptyString(body.title, 'title', path);
+    const intent = nonEmptyString(body.intent, 'intent', path);
+    if (!Array.isArray(body.affected)) {
+        throw new Error(`${path}: "affected" must be an array of { id, why } (it may be empty).`);
+    }
+    const affected = body.affected.map((entry, index) => {
+        const item = (typeof entry === 'object' && entry !== null ? entry : {});
+        return {
+            id: nonEmptyString(item.id, `affected[${index}].id`, path),
+            why: typeof item.why === 'string' ? item.why : '',
+        };
+    });
+    return { title, intent, affected };
+}
+function nonEmptyString(value, field, path) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${path}: "${field}" must be a non-empty string.`);
+    }
+    return value;
+}
+function presentDir(path) {
+    return existsSync(path) ? path : null;
+}

package/dist/files/features.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveSuiteFile } from "./suiteBuild.js";
+// A feature's folder on disk (spec 52-2): `.unitbob/features/<id>/`. This is
+// the first spec that gives a feature a folder; the talk's request and the
+// file it folds into live here, and spec 52-3 puts its own request beside them.
+export function featureDir(projectRoot, featureId) {
+    return join(projectRoot, '.unitbob', 'features', String(featureId));
+}
+// The id as the list printed it and the folder is named: a number. A word
+// ("refunds") is the person's, not the server's, and the verb says so.
+export function parseFeatureId(raw, verb) {
+    if (raw === undefined)
+        throw new Error(`Usage: unitbob ${verb} <feature_id>`);
+    if (!/^\d+$/.test(raw))
+        throw new Error(`unitbob ${verb}: the feature id must be a number, got "${raw}".`);
+    return Number(raw);
+}
+export function knowledgeRequestPath(projectRoot, featureId) {
+    return join(featureDir(projectRoot, featureId), 'request.json');
+}
+export function knowledgePath(projectRoot, featureId) {
+    return join(featureDir(projectRoot, featureId), 'knowledge.md');
+}
+export function writeKnowledgeRequest(projectRoot, featureId, recipe, packet) {
+    const request = {
+        project_root: projectRoot,
+        recipe,
+        feature: packet.feature,
+        affected: packet.affected,
+        knowledge: packet.knowledge,
+        behavioral_suite_path: presentDir(join(projectRoot, '.unitbob', 'behavioral')),
+        map_documents_path: presentDir(join(projectRoot, '.unitbob', 'map-build')),
+        output_path: knowledgePath(projectRoot, featureId),
+    };
+    const path = knowledgeRequestPath(projectRoot, featureId);
+    if (!existsSync(dirname(path)))
+        mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}
+// The file as text, and nothing else: the server is the one place that checks
+// its shape (spec 52-2, Non-Goals), so the connector only refuses to send
+// nothing.
+export function readKnowledge(projectRoot, featureId) {
+    const path = knowledgePath(projectRoot, featureId);
+    if (!existsSync(path)) {
+        throw new Error(`No knowledge file at ${path}. Write it as the recipe describes, then run \`unitbob put-knowledge\`.`);
+    }
+    const text = readFileSync(path, 'utf8');
+    if (text.trim() === '')
+        throw new Error(`${path} is empty. Write it as the recipe describes, then run \`unitbob put-knowledge\`.`);
+    return text;
+}
+function presentDir(path) {
+    return existsSync(path) ? path : null;
+}
+// --- the checks (spec 52-3) -------------------------------------------------
+export function testsRequestPath(projectRoot, featureId) {
+    return join(featureDir(projectRoot, featureId), 'tests-request.json');
+}
+export function testsOutputPath(projectRoot, featureId) {
+    return join(featureDir(projectRoot, featureId), 'tests-output.json');
+}
+// Where the checks go, beside the main suite (spec 52-3, AC 3.4): one
+// `.feature` and one step file, both named after the feature so that they can
+// never take a path of the main suite's.
+export function featureFeaturePath(featureId) {
+    return `.unitbob/behavioral/features/feature_${featureId}.feature`;
+}
+export function featureStepsPath(featureId, runner) {
+    return `.unitbob/behavioral/step_definitions/${stepsFileName(featureId, runner)}`;
+}
+// Named as the runner collects it: pytest only picks up `test_*.py`, and a
+// file named otherwise loads nothing (`bdd.ts` says so at length).
+function stepsFileName(featureId, runner) {
+    switch (runner) {
+        case 'pytest-bdd': return `test_feature_${featureId}_steps.py`;
+        case 'cucumber-js': return `feature_${featureId}_steps.js`;
+        default: return `feature_${featureId}_steps.rb`;
+    }
+}
+export function writeTestsRequest(projectRoot, featureId, request) {
+    const path = testsRequestPath(projectRoot, featureId);
+    if (!existsSync(dirname(path)))
+        mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}
+export function readTestsRequest(projectRoot, featureId) {
+    const path = testsRequestPath(projectRoot, featureId);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`npx unitbob tests-prepare ${featureId}\` first.`);
+    }
+    const request = JSON.parse(readFileSync(path, 'utf8'));
+    if (!request || typeof request.feature_tag !== 'string' || typeof request.runner !== 'string' ||
+        typeof request.feature_path !== 'string' || typeof request.output_path !== 'string') {
+        throw new Error(`${path} is malformed — run \`npx unitbob tests-prepare ${featureId}\` again.`);
+    }
+    return request;
+}
+export function readTestsOutput(projectRoot, featureId) {
+    const path = testsOutputPath(projectRoot, featureId);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — write the answer as the recipe describes, then run \`unitbob put-tests\`.`);
+    }
+    const answer = JSON.parse(readFileSync(path, 'utf8'));
+    if (!answer || typeof answer !== 'object')
+        throw new Error(`${path} is malformed: expected an object.`);
+    const manifest = answer.runner_manifest;
+    if (!manifest || typeof manifest !== 'object' || typeof manifest.runner !== 'string') {
+        throw new Error(`${path} is missing runner_manifest.`);
+    }
+    if (!answer.test_metadata || typeof answer.test_metadata !== 'object') {
+        throw new Error(`${path} is missing test_metadata.`);
+    }
+    return {
+        suite_file: resolveSuiteFile(answer.suite_file, '.unitbob/behavioral/', path, 'feature', projectRoot),
+        runner_manifest: manifest,
+        test_metadata: answer.test_metadata,
+    };
+}
+// --- the review of the checks (spec 52-4, AC 1.11) ---------------------------
+export function testsReviewRequestPath(projectRoot, featureId) {
+    return join(featureDir(projectRoot, featureId), 'tests-review-request.json');
+}
+export function testsReviewOutputPath(projectRoot, featureId) {
+    return join(featureDir(projectRoot, featureId), 'tests-review-output.json');
+}
+export function writeTestsReviewRequest(projectRoot, featureId, request) {
+    const path = testsReviewRequestPath(projectRoot, featureId);
+    if (!existsSync(dirname(path)))
+        mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}
+export function readTestsReviewOutput(projectRoot, featureId) {
+    const path = testsReviewOutputPath(projectRoot, featureId);
+    if (!existsSync(path))
+        return null;
+    let review;
+    try {
+        review = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON (${err.message})`);
+    }
+    const record = review;
+    if (!record || typeof record !== 'object' || typeof record.candidate_digest !== 'string') {
+        throw new Error(`${path} must carry candidate_digest at the top level, copied from tests-review-request.json.`);
+    }
+    if (!record.bdd_quality_review || typeof record.bdd_quality_review !== 'object') {
+        throw new Error(`${path} must contain a bdd_quality_review object.`);
+    }
+    return { candidate_digest: record.candidate_digest, bdd_quality_review: record.bdd_quality_review };
+}

package/dist/files/mapBuild.js

@@ -28,7 +28,7 @@ export function readFreshGraph(projectRoot) {
     parseJson(rawGraphJson, path);
     return rawGraphJson;
 }
-export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath) {
+export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath, existingCapabilities = []) {
     const packet = {
         project_root: projectRoot,
         graph_path: graphPath(projectRoot),
@@ -37,6 +37,7 @@ export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath) {
         surface_output_path: surfaceOutputPath(projectRoot),
         ...(routeInventoryPath ? { route_inventory_path: routeInventoryPath } : {}),
         recipes,
+        existing_capabilities: existingCapabilities,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });

package/dist/files/suiteBuild.js

@@ -369,12 +369,13 @@ function isRunEvidence(value, digest) {
         typeof run.revision === 'string' && run.revision &&
         typeof run.run_result === 'string' && run.run_result);
 }
-export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }) {
+export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }, excludeFeatureTags = []) {
     const request = {
         project_root: projectRoot,
         output_path: outputPath(projectRoot),
         branches,
         known_defect_context: knownDefectContext,
+        exclude_feature_tags: excludeFeatureTags,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -421,6 +422,9 @@ export function readSuiteBuildRequest(projectRoot) {
     return {
         ...request,
         known_defect_context: readKnownDefectContext(request.known_defect_context, path),
+        exclude_feature_tags: Array.isArray(request.exclude_feature_tags)
+            ? request.exclude_feature_tags.filter((tag) => typeof tag === 'string')
+            : [],
     };
 }
 function readKnownDefectContext(value, path) {
@@ -533,7 +537,10 @@ function readBranch(entry, rootFor, path, projectRoot) {
 // 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) {
+//
+// Exported for a feature's answer (spec 52-3), which is one branch of the same
+// shape read from its own file.
+export function resolveSuiteFile(file, root, path, suiteKind, projectRoot) {
     if (!file || typeof file !== 'object') {
         throw new Error(`${path}: the ${suiteKind} branch is missing suite_file.`);
     }

package/dist/runner/bdd.js

@@ -56,7 +56,7 @@ const CUCUMBER_LOAD_ORDER = 'Files load in filename order, and the shared file i
 // fourth runner cannot be added with only half of itself stated.
 const BDD_STRATEGIES = {
     cucumber: {
-        run: (projectRoot) => runCucumberRuby(projectRoot),
+        run: (projectRoot, _mainPath, filter) => runCucumberRuby(projectRoot, filter),
         loading: {
             step_files: '*.rb',
             requirements: [
@@ -68,7 +68,7 @@ const BDD_STRATEGIES = {
         },
     },
     'cucumber-js': {
-        run: (projectRoot) => runCucumberJs(projectRoot),
+        run: (projectRoot, _mainPath, filter) => runCucumberJs(projectRoot, filter),
         loading: {
             step_files: '*.js',
             requirements: [
@@ -84,7 +84,7 @@ const BDD_STRATEGIES = {
         },
     },
     'pytest-bdd': {
-        run: (projectRoot, mainPath) => runPytestBdd(projectRoot, mainPath),
+        run: (projectRoot, mainPath, filter) => runPytestBdd(projectRoot, mainPath, filter),
         loading: {
             step_files: 'test_*.py',
             requirements: [
@@ -100,12 +100,26 @@ const BDD_STRATEGIES = {
         },
     },
 };
-export function runBddSuite(projectRoot, runner, mainPath) {
+export function runBddSuite(projectRoot, runner, mainPath, filter) {
     const strategy = strategyFor(runner);
     if (!strategy) {
         return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
     }
-    return strategy.run(projectRoot, mainPath);
+    return strategy.run(projectRoot, mainPath, filter);
+}
+// The filter as a tag expression. Both Cucumbers read `@tag`; pytest-bdd turns
+// a tag into a marker of the same name and reads `-m`, where the `@` would be
+// a syntax error. Empty for no filter, so the caller adds no flag at all.
+function tagExpression(filter, prefix) {
+    if (!filter)
+        return '';
+    if ('only' in filter)
+        return `${prefix}${filter.only}`;
+    return filter.exclude.map((tag) => `not ${prefix}${tag}`).join(' and ');
+}
+function tagArgs(filter, flag, prefix) {
+    const expression = tagExpression(filter, prefix);
+    return expression ? [flag, expression] : [];
 }
 // How this runner loads step files, for whoever has to write one. Null for a
 // runner this connector does not run, which is the same answer `runBddSuite`
@@ -122,7 +136,7 @@ function strategyFor(runner) {
 // 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) {
+async function runCucumberRuby(projectRoot, filter) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const sidecarGemfile = join(projectRoot, BEHAVIORAL_GEMFILE);
@@ -130,7 +144,10 @@ async function runCucumberRuby(projectRoot) {
         throw missingRunner('Cucumber');
     }
     const command = 'bundle';
-    const args = ['exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
+    const args = [
+        'exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT,
+        ...tagArgs(filter, '--tags', '@'),
+    ];
     const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
     const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
@@ -147,7 +164,7 @@ function missingRunner(name) {
 }
 // JS/TS: `@cucumber/cucumber` (cucumber-js) with the message formatter written
 // to a file.
-async function runCucumberJs(projectRoot) {
+async function runCucumberJs(projectRoot, filter) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS, '**', '*');
     const command = `${BEHAVIORAL_ROOT}/node_modules/.bin/cucumber-js`;
@@ -160,6 +177,7 @@ async function runCucumberJs(projectRoot) {
         steps,
         '--format',
         `message:${CUCUMBER_REPORT}`,
+        ...tagArgs(filter, '--tags', '@'),
     ];
     const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
     const run = await runInProject(projectRoot, command, args, {
@@ -171,7 +189,7 @@ async function runCucumberJs(projectRoot) {
 // 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) {
+async function runPytestBdd(projectRoot, mainPath, filter) {
     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);
@@ -186,7 +204,15 @@ async function runPytestBdd(projectRoot, mainPath) {
     // `--rootdir .`, not the absolute root: the working directory is the project
     // root in every place, and an absolute host path would name a directory that
     // does not exist wherever the run actually happens.
-    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.'];
+    // The marker filter goes after `--rootdir`, so the two arguments the harness
+    // loading depends on keep their place at the end of the unfiltered command.
+    // pytest-bdd hangs a marker named after each tag on the scenario; the
+    // connector's ini registers none, and an unregistered marker is a warning,
+    // not an error (spec 52-3, non-goal).
+    const args = [
+        '-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.',
+        ...tagArgs(filter, '-m', ''),
+    ];
     const survivor = clearReport(join(projectRoot, PYTEST_BDD_REPORT));
     const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,

package/dist/runner/failureDigest.js

@@ -24,6 +24,65 @@ export function reportedFailures(runner, report) {
         return null;
     return extract(runner, report);
 }
+// Spec 52-4, AC 1.10. The same parse, read for a third question: how many of
+// a feature's scenarios passed and how many did not. `put-tests` decides from
+// it which proof to attach — all red is the red run, all green with a review
+// is the review, anything else is no proof — and whether a review may be sent
+// at all. The number reaches a sentence on this machine and the choice of a
+// field; the server checks whatever proof it is sent against the report
+// itself. Only the two behavioral shapes have scenarios to count; a report
+// that cannot be read is no tally, never a green one.
+export function scenarioTally(runner, report) {
+    if (!report.trim())
+        return null;
+    const outcomes = scenarioOutcomes(runner, report);
+    if (outcomes === null)
+        return null;
+    const failed = outcomes.filter((passed) => !passed).length;
+    return { passed: outcomes.length - failed, failed };
+}
+// One entry per scenario, true when it passed. Cucumber emits one
+// `testCaseStarted` per attempt when a scenario is retried, so the rows are
+// keyed by the test case and the last attempt is the one that counts — the
+// one the run ended on.
+function scenarioOutcomes(runner, report) {
+    switch (runner) {
+        case 'cucumber':
+        case 'cucumber-js': {
+            const envelopes = [];
+            for (const line of report.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const parsed = parseObject(line);
+                if (!parsed)
+                    return null;
+                envelopes.push(parsed);
+            }
+            const failedRuns = new Set();
+            for (const envelope of envelopes) {
+                const finished = envelope.testStepFinished;
+                const status = text(finished?.testStepResult?.status);
+                if (finished && status !== 'PASSED' && status !== 'SKIPPED')
+                    failedRuns.add(text(finished.testCaseStartedId));
+            }
+            const lastAttempt = new Map();
+            for (const envelope of envelopes) {
+                const started = envelope.testCaseStarted;
+                if (started)
+                    lastAttempt.set(text(started.testCaseId), text(started.id));
+            }
+            return [...lastAttempt.values()].map((startedId) => !failedRuns.has(startedId));
+        }
+        case 'pytest-bdd': {
+            const data = parseObject(report);
+            if (!Array.isArray(data?.scenarios))
+                return null;
+            return rows(data.scenarios).map((scenario) => text(scenario.status) === 'passed');
+        }
+        default:
+            return null;
+    }
+}
 // One hash for one set. Same set, same hash, on any machine and in any order.
 export function digestOf(failures) {
     return createHash('sha256').update(JSON.stringify(failures)).digest('hex');