unitbob 0.7.8 → 0.7.12

package/dist/verbs/runLocal.js

@@ -5,8 +5,10 @@ import { placeAdvice } from "../runner/placeAdvice.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { parseFeatureId, readTestsRequest } from "../files/features.js";
 import { testPathsOf } from "../runner/vitest.js";
 import { runStructuralByRunner } from "./run.js";
+import { outputTail } from "../runner/outputTail.js";
 const OUTPUT_TAIL_CHARS = 4000;
 export async function runLocal(config, args = [], deps) {
     const d = {
@@ -23,6 +25,10 @@ export async function runLocal(config, args = [], deps) {
     const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
     if (unusable)
         throw new Error(unusable);
+    const featureFlag = args.indexOf('--feature');
+    if (featureFlag !== -1) {
+        return runFeature(config, d, parseFeatureId(args[featureFlag + 1], 'run-local --feature'));
+    }
     const request = readSuiteBuildRequest(config.projectRoot);
     const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     const wanted = selectBranches(request, args);
@@ -39,7 +45,7 @@ export async function runLocal(config, args = [], deps) {
             d.stdout.write(`Cannot run this branch — its entry in your answer could not be read: ${broken.message}\n`);
             continue;
         }
-        const ran = await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind));
+        const ran = await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind), { exclude: request.exclude_feature_tags });
         // A branch with no entry written yet, or one the stack cannot execute,
         // produced nothing to compare: it is the ordinary state halfway through a
         // build, not a repair loop going nowhere.
@@ -47,9 +53,54 @@ export async function runLocal(config, args = [], deps) {
             continue;
         if (compareFailures(config, d, suiteKind, ran, previous[suiteKind]))
             stuck = true;
+        // The features' checks, each by its tag, on the same files. No stall
+        // comparison for them: their loop is the feature's own, in `--feature`.
+        if (suiteKind === 'behavioral') {
+            for (const tag of request.exclude_feature_tags)
+                await runTag(config, d, ran.runner, ran.mainPath, tag);
+        }
     }
     return stuck ? 1 : 0;
 }
+async function runTag(config, d, runner, mainPath, tag) {
+    d.stdout.write(`\n── ${tag} ──\n`);
+    let result;
+    try {
+        result = await d.runBehavioral(config.projectRoot, runner, mainPath, { only: tag });
+    }
+    catch (err) {
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
+        return;
+    }
+    d.stdout.write(report(result));
+    d.stdout.write(failureLines(runner, result));
+}
+// One feature's checks, by their tag (spec 52-3, AC 3.3). No stall comparison:
+// the loop here ends on "every scenario red", which the person reads off the
+// failures printed, and the server's proof of red is the connector's own run
+// in `put-tests`, not this one.
+async function runFeature(config, d, featureId) {
+    const request = readTestsRequest(config.projectRoot, featureId);
+    d.stdout.write(`\n── feature ${featureId} ──\n`);
+    const check = d.validateStack(config.projectRoot, request.runner);
+    if (!check.ok) {
+        d.stdout.write(`Cannot run the checks: ${check.message ?? `this project does not match "${request.runner}".`}\n`);
+        return 1;
+    }
+    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` : ''}`);
+        return 1;
+    }
+    d.stdout.write(report(result));
+    d.stdout.write(failureLines(request.runner, result));
+    return 0;
+}
 // Spec 34-6, criterion 3. The whole stop condition, and it stops the branch
 // rather than the worker: the set of failures belongs to the branch, and a
 // repair worker looking only at its own slice cannot see that the branch as a
@@ -97,7 +148,7 @@ function selectBranches(request, args) {
 // Non-null when the runner actually executed the branch. Everything else — no
 // entry, a declared `build_error`, a stack that cannot run it — is a branch that
 // produced no result to compare against.
-async function runOneBranch(config, d, suiteKind, output) {
+async function runOneBranch(config, d, suiteKind, output, filter) {
     // Nothing written for this branch yet. That is the ordinary state halfway
     // through a build, not an error — say what is missing and move to the peer.
     if (!output) {
@@ -128,7 +179,7 @@ async function runOneBranch(config, d, suiteKind, output) {
     try {
         result =
             suiteKind === 'behavioral'
-                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0])
+                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0], filter)
                 : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
@@ -142,7 +193,7 @@ async function runOneBranch(config, d, suiteKind, output) {
     }
     d.stdout.write(report(result));
     d.stdout.write(failureLines(runner, result));
-    return { runner, result };
+    return { runner, mainPath: suitePaths[0], result };
 }
 // How many lines of one failure's message are worth printing here. Enough for an
 // assertion diff and the frame under it; not the whole backtrace, which is in
@@ -224,20 +275,11 @@ function report(result) {
         lines.push(`no report at ${result.resultPath} — the run produced none, which usually means it died before` +
             ' the first test rather than that the tests failed.');
     }
-    const tail = outputTail(result);
+    const tail = outputTail(result, OUTPUT_TAIL_CHARS);
     if (tail)
         lines.push('', tail);
     return `${lines.join('\n')}\n`;
 }
-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;
-}
 // The suite blob's own project-relative paths, exactly as the runners expect
 // them: the main file first, then every other file of the branch. The main file
 // stopped being the whole suite in spec one-place-per-rule, §6 — a branch is one file per

package/dist/verbs/suitePrepare.js

@@ -66,6 +66,7 @@ export async function suitePrepare(config, args = [], deps) {
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         precheck: anyStackPrecheck,
         confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
         bootCheck: (projectRoot, runner, sourceFiles) => bootCheck(projectRoot, runner, sourceFiles),
@@ -314,7 +315,8 @@ export async function suitePrepare(config, args = [], deps) {
         const why = [...bootNotices, ...blockedNotices, ...fixableNotices].join('\n');
         throw new Error(`No suite branch can be built this run:\n${why}\nNothing was written and nothing was uploaded.`);
     }
-    const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
+    const excludeFeatureTags = (await actual.getSuiteIndex()).feature_suites.map((item) => item.feature_tag);
+    const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext, excludeFeatureTags);
     // Spec 37-1. The assignment names entrypoints; the packets are the files
     // behind them, resolved from this machine's own graph and copied where a
     // worker can open them. Built here because the entrypoints are known from the

package/dist/verbs/suiteReviewPrepare.js

@@ -2,13 +2,21 @@ 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 { changedFeatureFiles, copyBehavioralRunnerEnvironment, FeatureFilesChangedError, filesLostOnMaterialize, materializeBehavioralUnion, } from "../files/behavioral.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { placeOf } from "../runner/place.js";
+import { gitRevision } from "../runner/gitRevision.js";
+import { Wire } from "../wire.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
+// The candidate is run on disk as the same union `check` writes (spec 52-4,
+// AC 1.8): the candidate plus the checks of every red feature the server
+// holds, with their tags left out of the run. Written as the candidate alone,
+// the review wiped those checks from the disk — and with them any steps the
+// host had rewired against the real code and not yet saved.
 export async function suiteReviewPrepare(config, _args = [], deps) {
     const actual = {
+        getSuiteIndex: () => new Wire(config).getSuiteIndex(),
         runCandidate: runCandidate,
         stdout: process.stdout,
         ...deps,
@@ -21,40 +29,63 @@ export async function suiteReviewPrepare(config, _args = [], deps) {
     if (behavioral.build_error) {
         throw new Error(`The behavioral candidate could not be reviewed: ${behavioral.build_error.message}`);
     }
+    // Before anything else is said or run: a feature's checks rewired on disk
+    // and not saved stop the review here, disk untouched, with the command that
+    // saves them — the same stop `check` makes.
+    const features = (await actual.getSuiteIndex()).feature_suites;
+    const changed = changedFeatureFiles(config.projectRoot, features);
+    if (changed.length > 0)
+        throw new FeatureFilesChangedError(changed[0].feature_id, changed[0].title);
     // 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));
+    const lost = filesLostOnMaterialize(config.projectRoot, behavioral.suite_file, branchRunner(behavioral), features.map((item) => item.suite_file));
     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 candidateRun = await actual.runCandidate(config.projectRoot, behavioral, features);
     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)
+        ? await actual.runCandidate(config.projectRoot, behavioral, features, 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) {
+async function runCandidate(projectRoot, output, features, revision) {
     if (revision)
-        return runCandidateAtRevision(projectRoot, output, revision);
-    return runCandidateInProject(projectRoot, output, gitRevision(projectRoot));
+        return runCandidateAtRevision(projectRoot, output, features, revision);
+    return runCandidateInProject(projectRoot, output, features, gitRevision(projectRoot));
 }
-async function runCandidateInProject(projectRoot, output, revision) {
+async function runCandidateInProject(projectRoot, output, features, 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 { mainPath, excludeTags } = candidateUnion(projectRoot, output, features);
+    const result = await runBddSuite(projectRoot, runner, mainPath, { exclude: excludeTags });
     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) {
+// The candidate on disk as `check` would write it: the union of the candidate
+// and every feature's checks, one clearing, the feature tags to leave out.
+// Through `materializeBehavioralUnion` rather than beside it, so the stop on
+// a changed feature file is the same one, made before the disk is touched.
+export function candidateUnion(projectRoot, output, features) {
+    const index = {
+        suites: [{
+                suite_kind: 'behavioral',
+                status: 'ready',
+                suite_file: output.suite_file,
+                runner_manifest: output.runner_manifest,
+            }],
+        feature_suites: [...features],
+    };
+    // Never null: the candidate itself is in the union.
+    return materializeBehavioralUnion(projectRoot, index, branchRunner(output));
+}
+async function runCandidateAtRevision(projectRoot, output, features, revision) {
     // Spec 36, Non-Goals. The worktree below is created under the system's
     // temporary directory — outside anything a container has mounted, so in there
     // it does not exist at all. Said plainly rather than run into. The obvious
@@ -78,9 +109,9 @@ async function runCandidateAtRevision(projectRoot, output, revision) {
         execFileSync('git', ['worktree', 'add', '--detach', worktree, resolved], { cwd: projectRoot, stdio: 'pipe' });
         added = true;
         const runner = branchRunner(output);
-        materializeBehavioral(worktree, output.suite_file, runner);
+        candidateUnion(worktree, output, features);
         copyBehavioralRunnerEnvironment(projectRoot, worktree, runner);
-        return await runCandidateInProject(worktree, output, revision);
+        return await runCandidateInProject(worktree, output, features, revision);
     }
     finally {
         if (added) {
@@ -105,18 +136,3 @@ async function runCandidateAtRevision(projectRoot, output, revision) {
         }
     }
 }
-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/verbs/testsPrepare.js

@@ -0,0 +1,77 @@
+import { materializeBehavioralUnion, materializeBehavioralWorld } from "../files/behavioral.js";
+import { featureFeaturePath, featureStepsPath, knowledgePath, parseFeatureId, testsOutputPath, testsRequestPath, writeTestsRequest, } from "../files/features.js";
+import { installedRunnerVersion, selectRunnerEnvelope } from "../runner/manifest.js";
+import { placeProblem } from "../runner/place.js";
+import { detectBddRunner } from "../runner/precheck.js";
+import { ensureRunner } from "../runner/provision.js";
+import { ToolchainUnavailableError } from "../runner/toolchain.js";
+import { Wire } from "../wire.js";
+import { assertKnowledgeUnchanged } from "./putTests.js";
+// `tests-prepare <feature_id>` (spec 52-3, AC 3.4): the host's task for writing
+// a feature's checks. The packet (a 409 before the talk is the server's own
+// sentence, let through), then the knowledge file on disk held to the server's
+// digest — the checks are written from that file, and a file edited after the
+// talk would put text under seal the person never confirmed — then the recipe,
+// the union of the main suite and every red feature's checks on disk (the
+// shared steps to reuse, the base for rewriting the wiring at `red`), the
+// runner provisioned as `suite-prepare` provisions it, the World in place, and
+// `tests-request.json` beside the talk's request. No model is called, nothing
+// is uploaded.
+export async function testsPrepare(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        getTestsPacket: (id) => wire.getTestsPacket(id),
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuiteIndex: () => wire.getSuiteIndex(),
+        detectRunner: detectBddRunner,
+        ensureRunner,
+        installedVersion: installedRunnerVersion,
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'tests-prepare');
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
+    const packet = await d.getTestsPacket(featureId);
+    assertKnowledgeUnchanged(config.projectRoot, featureId, packet.knowledge_digest);
+    const [recipe, index] = await Promise.all([d.getRecipe('feature_tests'), d.getSuiteIndex()]);
+    // The main suite's runner when it is built — the checks share its directory
+    // and its steps, so they cannot run on another — else the one this stack
+    // selects, as `suite-prepare` does.
+    const runner = packet.main_suite === 'not_built' ? d.detectRunner(config.projectRoot) : packet.main_suite.runner;
+    if (!runner) {
+        throw new Error('This project matches no BDD runner the connector can run — the checks cannot be written on it.');
+    }
+    const provisioned = await d.ensureRunner(config.projectRoot, runner);
+    if (provisioned.status === 'fixable') {
+        const steps = provisioned.checklist?.length ? `\n  - ${provisioned.checklist.join('\n  - ')}` : '';
+        throw new ToolchainUnavailableError(`The "${runner}" runner could not be installed under .unitbob/, and the checks cannot run without it: ` +
+            `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written.`, config.projectRoot);
+    }
+    const selected = selectRunnerEnvelope(packet.runner_manifests, runner);
+    const version = d.installedVersion(runner, config.projectRoot);
+    if (!selected || !version) {
+        throw new Error(`The version of "${runner}" installed under .unitbob/behavioral/ could not be read, and the server requires it. ` +
+            'Re-run `unitbob suite-prepare` so the runner is provisioned again.');
+    }
+    materializeBehavioralUnion(config.projectRoot, index, runner);
+    materializeBehavioralWorld(config.projectRoot, runner);
+    writeTestsRequest(config.projectRoot, featureId, {
+        project_root: config.projectRoot,
+        recipe,
+        feature: packet.feature,
+        feature_tag: packet.feature_tag,
+        assignment: packet.assignment,
+        scenarios: packet.scenarios,
+        knowledge_path: knowledgePath(config.projectRoot, featureId),
+        knowledge_digest: packet.knowledge_digest,
+        runner,
+        runner_manifest: { ...selected, runner_version: version },
+        main_suite: packet.main_suite,
+        feature_path: featureFeaturePath(featureId),
+        steps_path: featureStepsPath(featureId, runner),
+        output_path: testsOutputPath(config.projectRoot, featureId),
+    });
+    d.stdout.write(`Tests request written to ${testsRequestPath(config.projectRoot, featureId)}\n`);
+}

package/dist/verbs/testsReviewPrepare.js

@@ -0,0 +1,40 @@
+import { knowledgePath, parseFeatureId, readTestsOutput, readTestsRequest, testsReviewOutputPath, testsReviewRequestPath, writeTestsReviewRequest, } from "../files/features.js";
+import { suiteCandidateDigest } from "../files/suiteBuild.js";
+import { Wire } from "../wire.js";
+// `tests-review-prepare <feature_id>` (spec 52-4, AC 1.11): the independent
+// reviewer's task for a feature's checks, once they all pass. The packet
+// first — a 409 is the server's own sentence, at `intent` (nothing to review)
+// and at `done` (the checks are guardrails now), let through as it is — then
+// the files from disk exactly as `put-tests` will send them, bound by the same
+// candidate digest the upload carries, and the request written in the shape
+// of the main suite's `review-request.json` so the same role reads it: plus
+// where `knowledge.md` is, because the promise each scenario protects is
+// written there, and the scenarios as the server sealed them. No model is
+// called, nothing is uploaded; `put-tests` publishes the review.
+export async function testsReviewPrepare(config, args = [], deps) {
+    const d = {
+        getTestsPacket: (id) => new Wire(config).getTestsPacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'tests-review-prepare');
+    // An existence guard only: the request is what `put-tests` will read after
+    // the review, and its absence names the verb that writes it — better said
+    // here than as a missing answer two steps later.
+    readTestsRequest(config.projectRoot, featureId);
+    const packet = await d.getTestsPacket(featureId);
+    const output = readTestsOutput(config.projectRoot, featureId);
+    writeTestsReviewRequest(config.projectRoot, featureId, {
+        candidate_digest: suiteCandidateDigest({
+            suite_kind: 'behavioral', suite_file: output.suite_file, runner_manifest: output.runner_manifest,
+        }),
+        suite_file: output.suite_file,
+        capabilities: output.test_metadata.capabilities,
+        knowledge_path: knowledgePath(config.projectRoot, featureId),
+        scenarios: packet.scenarios,
+        output_path: testsReviewOutputPath(config.projectRoot, featureId),
+    });
+    d.stdout.write(`Feature review request written to ${testsReviewRequestPath(config.projectRoot, featureId)}\n`);
+    d.stdout.write(`Next: have the independent reviewer write bdd_quality_review to ${testsReviewOutputPath(config.projectRoot, featureId)}, ` +
+        `then run \`unitbob put-tests ${featureId}\`.\n`);
+}

package/dist/wire.js

@@ -7,11 +7,17 @@ import { proxyHint } from "./proxyHint.js";
 // that reads an absence as a verdict either invents a rejection or invents an
 // approval. `validate-build` is the caller that needs the difference: with no
 // server it succeeds, and says out loud which questions went unasked.
+//
+// `status` is the HTTP status the server answered with, when there was one:
+// for the one caller that treats a 404 — a server older than the route — as
+// an absence rather than a verdict (`map-prepare`, spec 52-4).
 export class WireError extends Error {
     unreachable;
+    status;
     constructor(message, options = {}) {
         super(message);
         this.unreachable = options.unreachable ?? false;
+        this.status = options.status ?? null;
     }
 }
 // POST /repos/register — the linking bootstrap (spec 28). A standalone function
@@ -102,15 +108,19 @@ export class Wire {
         return body.results;
     }
     // GET /repos/:id/suites — both current suites (spec 32), exactly two peer
-    // items. A `ready` item carries its blob; a `not_built` item is skipped.
-    async getSuites() {
+    // items, and since spec 52-3 the checks of every red feature beside them. A
+    // `ready` item carries its blob; a `not_built` item is skipped.
+    async getSuiteIndex() {
         const res = await this.send('GET', this.repoPath('suites'));
         await this.ensureOk(res, `GET ${this.repoPath('suites')}`);
         const body = (await res.json());
         if (!Array.isArray(body.suites)) {
             throw new WireError(`GET ${this.repoPath('suites')} returned no suites array.`);
         }
-        return body.suites;
+        return {
+            suites: body.suites,
+            feature_suites: Array.isArray(body.feature_suites) ? body.feature_suites : [],
+        };
     }
     // POST /repos/:id/runs/batch — ship each branch's raw report (or suite error)
     // in one batch; the server parses each against the exact stored version and
@@ -158,6 +168,69 @@ export class Wire {
         await this.ensureOk(res, `GET ${url}`);
         return (await res.json());
     }
+    // POST /repos/:id/features — record a feature (spec 52-1). A 409 (no current
+    // map) and a 422 (an id not on the map, with both sides named in the body)
+    // surface as a WireError carrying the server's text, so the host reads what
+    // the map knows and corrects its file.
+    async postFeature(payload) {
+        const res = await this.send('POST', this.repoPath('features'), payload);
+        if (res.status === 422)
+            throw new WireError(await unknownCapabilitiesRefusal(res));
+        await this.ensureOk(res, `POST ${this.repoPath('features')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/features — every feature of the project, newest first, and
+    // the server's words for an empty list (spec 52-2, AC 1.2).
+    async listFeatures() {
+        const res = await this.send('GET', this.repoPath('features'));
+        await this.ensureOk(res, `GET ${this.repoPath('features')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/features/:feature_id/knowledge_packet (spec 52-2, AC 1.3).
+    async getKnowledgePacket(featureId) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/knowledge_packet`);
+        const res = await this.send('GET', path);
+        await this.ensureOk(res, `GET ${path}`);
+        return (await res.json());
+    }
+    // PUT /repos/:id/features/:feature_id/knowledge (spec 52-2, AC 1.4). The
+    // server checks the file's shape; a 422 carries `problems`, and they are
+    // relaid whole, one line per problem with both sides — the host fixes the
+    // file from those lines, and cutting them at 500 characters would hide the
+    // ones at the end.
+    async putKnowledge(featureId, knowledge) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/knowledge`);
+        const res = await this.send('PUT', path, { knowledge });
+        if (res.status === 422)
+            throw new WireError(await problemsRefusal(res, 'PUT knowledge failed: 422'));
+        await this.ensureOk(res, `PUT ${path}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/features/:feature_id/tests_packet (spec 52-3, AC 2.1). A
+    // 409 is the server's own sentence (talk the feature through first) and is
+    // relaid as it is.
+    async getTestsPacket(featureId) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/tests_packet`);
+        const res = await this.send('GET', path);
+        if (res.status === 409)
+            throw new WireError(await wordedRefusal(res, `GET tests_packet failed: 409`));
+        await this.ensureOk(res, `GET ${path}`);
+        return (await res.json());
+    }
+    // PUT /repos/:id/features/:feature_id/suite (spec 52-3, AC 2.2). Every
+    // refusal is worded by the server: a 409 in one sentence, a 422 in one
+    // sentence or, for a broken seal, with one problem per difference — relaid
+    // whole, both sides per line, like the knowledge file's.
+    async putFeatureSuite(featureId, upload) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/suite`);
+        const res = await this.send('PUT', path, upload);
+        if (res.status === 409)
+            throw new WireError(await wordedRefusal(res, 'PUT suite failed: 409'));
+        if (res.status === 422)
+            throw new WireError(await problemsRefusal(res, 'PUT suite failed: 422'));
+        await this.ensureOk(res, `PUT ${path}`);
+        return (await res.json());
+    }
     // GET /recipes/:name — fetch a recipe at call time. Recipes live on Rails so
     // the connector and Skill carry no recipe text (spec 15, acceptance criteria).
     async getRecipe(name) {
@@ -244,7 +317,7 @@ export class Wire {
         if (res.status === 404) {
             throw new WireError(`This project is linked to a repository the server at ${this.config.server} does not have, ` +
                 'or the token in .unitbob.json does not open it. Delete .unitbob.json to link again ' +
-                '(the old project, along with its map and checks, stays where it is).');
+                '(the old project, along with its map and checks, stays where it is).', { status: 404 });
         }
         let detail = '';
         try {
@@ -253,8 +326,55 @@ export class Wire {
         catch {
             // ignore — the status alone is actionable enough
         }
-        throw new WireError(statusRefusal(what, res, detail, this.config.server));
+        throw new WireError(statusRefusal(what, res, detail, this.config.server), { status: res.status });
+    }
+}
+// The 422 of POST /features carries two lists, and the host corrects its file by
+// reading both (spec 52-1, AC 1.3). `ensureOk` keeps 500 characters of a body,
+// which is a line of context for every other refusal and, on a map of twenty
+// capabilities or more, cuts `known_ids` in half — the list the correction is
+// made from, on exactly the projects that have the most ids to get wrong. So
+// the two lists are relaid whole, one per line; any other 422 body keeps the
+// ordinary shape.
+async function unknownCapabilitiesRefusal(res) {
+    const { text, body } = await readBody(res);
+    if (!Array.isArray(body.unknown_ids) || !Array.isArray(body.known_ids)) {
+        return `POST features failed: 422 — ${text.slice(0, 500)}`;
+    }
+    return (`POST features failed: 422 — ${String(body.error ?? 'These capabilities are not on the current map.')}\n` +
+        `unknown_ids: ${JSON.stringify(body.unknown_ids)}\n` +
+        `known_ids: ${JSON.stringify(body.known_ids)}`);
+}
+// A refusal the server worded in one sentence: that sentence, whole.
+async function wordedRefusal(res, prefix) {
+    const { text, body } = await readBody(res);
+    return `${prefix} — ${typeof body.error === 'string' ? body.error : text.slice(0, 500)}`;
+}
+// A refusal that may carry `problems` — the knowledge file's shape (spec 52-2,
+// AC 5.3) or a broken seal (spec 52-3): the sentence, then one problem per line
+// with both sides, relaid whole because the host fixes the file from all of
+// them; without problems, the sentence.
+async function problemsRefusal(res, prefix) {
+    const { text, body } = await readBody(res);
+    const head = `${prefix} — ${typeof body.error === 'string' ? body.error : text.slice(0, 500)}`;
+    if (!Array.isArray(body.problems))
+        return head;
+    const lines = body.problems.map((problem) => `expected: ${String(problem.expected)}\n     got: ${String(problem.got)}`);
+    return [head, ...lines].join('\n');
+}
+// A refusal body as text and, when it is JSON, as an object; when it is not,
+// the text itself is the detail.
+async function readBody(res) {
+    let text = '';
+    let body = {};
+    try {
+        text = await res.text();
+        body = JSON.parse(text);
+    }
+    catch {
+        // not JSON — the text itself is the detail
     }
+    return { text, body };
 }
 // The two statuses that prove somebody else answered.
 //

package/package.json

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

package/plugin/codex/agents/suite-repair-worker.toml

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.7.8 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.12 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded

package/plugin/codex/agents/suite-reviewer.toml

@@ -160,6 +160,24 @@ genuinely holds a promise and holds less of it than its name suggests. Nothing
 mechanical can tell those two apart; what makes the difference is that your
 sentence is specific enough to act on.
 
+## A feature's checks
+
+The same review, for a smaller candidate: the checks of one feature being
+built (spec 52-4). Then the request is
+`.unitbob/features/<id>/tests-review-request.json`, with the same keys as the
+main suite's plus two — `knowledge_path` and `scenarios` — and the review goes
+to the `output_path` it names, in the same form: `candidate_digest` at the top
+level, `bdd_quality_review` with one entry per Scenario by `case_marker` and
+name. There is no `known_defect_probe` and no `selection_review` here; write
+neither.
+
+When the request carries `knowledge_path`, the promise each Scenario protects
+is written in that `knowledge.md`, in its `Scenarios` section — read it there,
+not from the capability description, which for a feature is one line. The
+Scenario text is the user's and sealed; the steps behind it are what you
+judge, exactly as above. Do not read the feature's implementation: whether the
+code is right is the run's question, and the run was made by the connector.
+
 ## What is not yours
 
 **Do not edit the suite.** Not the `.feature` files, not the step definitions,