unitbob 0.7.8 → 0.7.13

package/README.md

@@ -1,134 +1,142 @@
 # Unitbob
 
-A living map of your app's business parts. Each important seam gets an automatic
-test — a "lamp" on the map. Green means fine, red means something broke.
+Unitbob draws a map of what your app does for people — signing in, paying,
+sending messages — and puts a lamp on each part. Behind every lamp is an
+automatic check. Green means that part still works. Red means something you
+changed broke it.
 
-Works with Ruby on Rails (RSpec), JavaScript/TypeScript (Vitest), and Python
-(pytest) projects — the guardrail tests are generated in your project's own
-language and run with its native test runner.
+You do not write the checks. Your coding assistant — Claude Code or Codex —
+does, and Unitbob keeps them honest. Your code stays on your computer; only
+the checks and their results go to Unitbob.
 
-You work through a coding agent — Claude Code or Codex both work. You need:
-Node 18+, Python 3.10+.
+Works with apps written in Ruby on Rails, JavaScript/TypeScript and Python.
+You need Node 18 or newer and Python 3.10 or newer installed.
 
 ---
 
 ## Install (once)
 
-**With a prompt:**
+Tell your assistant:
+
 ```
 Add the Unitbob plugin marketplace: sergeygershun/unitbob-connector
 Install the unitbob plugin
 ```
 
-**Claude Code (in the terminal):**
+Or, if you prefer the terminal — Claude Code:
+
 ```
 claude plugin marketplace add sergeygershun/unitbob-connector
 claude plugin install unitbob@unitbob
 ```
 
-**Codex (in the terminal):**
+Codex:
+
 ```
 codex plugin marketplace add sergeygershun/unitbob-connector
 codex plugin add unitbob@unitbob
-npx -y unitbob@0.4.4 codex-install
+npx -y unitbob@0.7.13 codex-install
 ```
 
-Start a new Claude Code or Codex thread so the installed skill and named agents
-load. After setup, the phrasings and Unitbob flow below are the same on both
-hosts.
+Then start a new chat. A chat opened before the install does not know about
+Unitbob yet. Everything below works the same in Claude Code and Codex.
 
-Codex compatibility: version 0.145.0 accepts the Unitbob custom-agent TOML files,
-but its experimental rollout budget is shared by the root and subagents rather
-than enforced separately for each named agent. No Codex version is currently
-qualified by Unitbob for a native per-agent ceiling. Before the first bounded
-role, Unitbob therefore asks whether to continue this invocation without that
-mechanical ceiling; approval is never persisted. The definitions keep the native
-budget values so a future Codex release can be qualified without introducing a
-Unitbob supervisor.
+On Codex, the assistant may ask once whether it can continue without a spending
+limit for its helpers. Answer yes; Codex cannot enforce that limit yet.
 
 ---
 
-## Full cycle
+## Protect what your app already does
 
-Just type it in the chat. There is nothing to memorise and no command to get right.
+Just say it in the chat. Nothing to memorise, no command to get right.
 
 | Step | Say this |
 |------|----------|
-| 1. Build the map | `Build my Unitbob map` |
-| 2. Generate the tests | `Generate the guardrail tests` |
-| 3. Fix a red lamp | `Fix guardrail <id>` |
-| 4. Open the map | `Open my Unitbob map` |
+| 1. Draw the map | `Build my Unitbob map` |
+| 2. Write the checks | `Generate the guardrail tests` |
+| 3. Look at the map | `Open my Unitbob map` |
+| 4. Fix a red lamp | `Fix guardrail <id>` — the id is written on the lamp |
 
-Step 2 lights the lamps by itself: generating the tests also runs them and sends
-the results. You do not have to ask for a run to see the first result.
+Step 2 also runs the checks, so the lamps light up right away. Later, whenever
+you want to know whether your latest changes broke anything, say `Run the
+checks`.
 
-Say `Run the checks` later, whenever you want the lamps refreshed against your
-current code — or to finish the job if a generation was interrupted after the
-tests were saved but before they ran.
+Your project connects itself to Unitbob the first time. There is nothing to
+set up by hand.
 
-In Claude Code there are also `/unitbob:map`, `/unitbob:suite` and friends, but
-they work only in a terminal session started after the plugin was installed — in
-a browser or desktop window they are not recognised at all. The phrasings above
-work everywhere, so they are the ones documented here.
+---
+
+## Build something new
+
+The steps above protect what your app does today. When you want to add
+something new, Unitbob can protect the new part too — before it exists. Then
+"done" is not a feeling; it is the checks turning green.
+
+Do steps 1 and 2 above first. Then, in the chat, in this order:
+
+| Step | Say this | What happens |
+|------|----------|--------------|
+| 1. Name it | `I want to add <feature>` | Unitbob writes down what you want and which parts of the map it may touch. You get a link to the feature's page. |
+| 2. Talk it through | `Let's talk through <feature>` | The assistant asks a few numbered questions about how the feature should behave — in plain words, with options and a recommendation. Answer with a letter, a word, or `do as you recommend`. Then it shows you the list of things that will be true when the feature is done and asks: is this it? Say `yes`. |
+| 3. Write the checks | `Write the checks for <feature>` | Each item from that list becomes a check. They are all red now — on purpose, the feature is not built yet. |
+| 4. Build it | `Build <feature>` | Ordinary work in the same chat. Say `Run the checks` at any time to see how many of the feature's checks already pass, and whether anything else broke. |
+| 5. Wrap up | `I'm done with <feature>` | The checks run once more, a second assistant reads them over, and you get the link to the feature's page. |
+| 6. Finish | Press **Finish this feature** on that page | Only you can press it, and only when everything is green. The feature gets its own lamp on the map, already green. |
+
+Good to know:
+
+- **If the button is grey, the page says why** — a check of the feature still
+  fails, the checks have not been read over yet, or something you said must
+  keep working is red.
+- **A red lamp you expected is fine.** If in step 2 you said a part would
+  change, its row on the feature page is amber, not red, with a button
+  `Accept the new behaviour`. Press it and it is green again. A red lamp you
+  did not expect is shown too, with the usual `Fix this`.
+- **The checks say exactly what you agreed to in step 2.** Nobody can quietly
+  bend them to fit the code. If you change your mind about the feature, say
+  `Let's talk through <feature>` again and the checks are rewritten.
+- **Work in your project's main folder.** Unitbob keeps the checks in a folder
+  called `.unitbob` next to your code. A copy of the project in another folder
+  does not have it.
+- **After Finish, nothing more to do.** From now on the feature's checks run
+  with all the others.
 
 ### If the assistant says it cannot find the Unitbob instructions
 
-A session that started *before* the plugin was installed does not pick up the
-skill, so the assistant has nothing to follow. Restarting the session is the
-clean fix. If that is inconvenient, the instructions are ordinary files on disk
-and the assistant can read them directly — tell it:
+The chat was started before the plugin was installed. Start a new chat. If you
+would rather not, tell the assistant:
 
 ```
 Read ~/.claude/plugins/cache/unitbob/unitbob/<version>/skills/unitbob/SKILL.md
 and follow the workflow it names for this job.
 ```
 
-`<version>` is whatever `claude plugin list` reports (for example `0.3.2`). The
-workflow files sit next to it under `workflows/`, one per job, and each is
-self-contained — that is what they are designed for.
-
----
-
-## How to read it
-
-- **Green lamp** — the behavior works.
-- **Red lamp** — something the structure relied on broke. Copy its `id` and run
-  step 3.
-- The project links itself by folder name — nothing to set up by hand.
+`<version>` is the number that `claude plugin list` shows.
 
 ---
 
-## If your tests only run inside Docker
+## If your app only runs inside Docker
 
-Some projects keep the code on this machine and everything that runs it — the
-interpreter, the packages, the database — inside a container. Name that
-container in `.unitbob.json` and Unitbob starts the project's own commands in
-there:
+Some projects keep the code on your computer but run it inside a Docker
+container. Tell Unitbob the container's name in the file `.unitbob.json` in
+your project folder:
 
 ```json
 { "server": "…", "repo_id": 3, "token": "…",
   "exec": { "docker": { "container": "myapp-web-1" } } }
 ```
 
-Nothing else changes. Files are still read and written here, and the path inside
-the container is worked out from the container's own mounts, so there is nothing
-else to configure. Leave the field out and everything runs on this machine,
-exactly as before.
-
-The project folder has to be **mounted** into the container rather than copied
-into the image — which it already is in any setup where you can edit a file and
-see the change. If it is not, Unitbob says so and stops before writing anything.
-
-Known limits of running in a container, all of them deliberate for now:
-
-- **A run that times out can leave a process alive inside the container.** The
-  timeout stops the `docker exec`, not necessarily what it started. A report
-  such a process writes afterwards is never counted as a later run's result.
-- **On a Linux host, files the container writes belong to `root`.** Unitbob does
-  not map users: guessing there breaks images that installed their packages as a
-  user of their own.
-- **Only a container that is already running.** A project whose tests go through
-  `docker compose run --rm` is not supported yet.
-- **Review at a fixed revision is not supported with a container.** It works in
-  a git worktree under the system's temporary directory, which is outside the
-  mount. Ordinary review works in the project itself and is unaffected.
+Keep the other three values as they are; Unitbob wrote them. Now the checks
+run inside the container. Without that line everything runs on your computer,
+as before.
+
+This works only when the project folder is shared with the container — which
+it already is if editing a file on your computer changes the running app. If
+it is not, Unitbob tells you and stops.
+
+A few things Unitbob does not do in a container yet:
+
+- The container has to be running already; Unitbob does not start it.
+- On Linux, files written from inside the container belong to `root`.
+- If a check takes too long and is stopped, the container may keep running it
+  in the background for a while.

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,30 @@ 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.
-  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.
+  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>]   Without an id: every red guard on both maps, with its suite digest and history — the
+                       list a fix starts from. With an id: the per-capability repair packet for one
+                       structural guard (spec 26).
+  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 +164,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 };
+}