unitbob 0.6.0 → 0.6.1

package/dist/verbs/validateWorkerCheckpoints.js

@@ -52,6 +52,7 @@ export async function validateWorkerCheckpoints(config, _args = [], deps = { std
             errors.push(`${label}: written path ${pathValue} is not an owned path`);
         }
         validateCompactFacts(checkpoint.facts, label, errors);
+        validateSurfaceCoverage(checkpoint.surface_coverage, item, label, errors);
         stringArray(checkpoint.decisions, `${label}: decisions`, errors);
         stringArray(checkpoint.known_problems, `${label}: known_problems`, errors);
     }
@@ -68,6 +69,16 @@ function stringArray(value, label, errors) {
     }
     return value;
 }
+// A fact says how it was established, and the vocabulary is two words wide:
+// `read` when the `source_refs` are what establishes it, `ran: <command>` when
+// something was executed and its result observed.
+//
+// a2time, 2026-08-17. A seeded fact claimed a dismissed employee cannot sign in.
+// It came from reading one method and remembering another, it reached sixteen
+// workers marked as verified, and it was false. Every fact that run established
+// by running the application held; the one that was not, did not — and nothing in
+// the checkpoint told the two apart, so no reader could weigh them differently.
+const ESTABLISHED_BY = /^(read|ran: \S.*)$/;
 function validateCompactFacts(value, label, errors) {
     if (!Array.isArray(value)) {
         errors.push(`${label}: facts must be an array`);
@@ -75,7 +86,7 @@ function validateCompactFacts(value, label, errors) {
     }
     for (const [index, entry] of value.entries()) {
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-            errors.push(`${label}: $.facts[${index}] must be an object with fact and source_refs; got ${jsonType(entry)}`);
+            errors.push(`${label}: $.facts[${index}] must be an object with fact, source_refs and established_by; got ${jsonType(entry)}`);
             continue;
         }
         const fact = entry;
@@ -84,11 +95,50 @@ function validateCompactFacts(value, label, errors) {
         if (!Array.isArray(fact.source_refs) || fact.source_refs.some((ref) => typeof ref !== 'string' || !ref.trim())) {
             errors.push(`${label}: facts[${index}].source_refs must be compact source references`);
         }
+        if (typeof fact.established_by !== 'string' || !ESTABLISHED_BY.test(fact.established_by)) {
+            errors.push(`${label}: facts[${index}].established_by must be "read" or "ran: <command>"`);
+        }
         if ('source' in fact || 'transcript' in fact || 'suite' in fact) {
             errors.push(`${label}: facts[${index}] may not embed source, transcript, or suite copies`);
         }
     }
 }
+// Which addresses a Scenario drives is knowable in one place — the step file the
+// worker just wrote — and until now it travelled nowhere. The coordinator owes
+// the server one `surface_coverage` entry per Scenario, so on a2time, 2026-08-17,
+// it assembled that join out of the workers' closing prose and its own plan. The
+// independent reviewer read the step code instead, the two disagreed on six
+// Scenarios, and the server refused the publication. The join now rides with the
+// work that produced it, and the coordinator copies it instead of interpreting.
+//
+// Behavioral only: this is a join between Gherkin Scenarios and surfaces, and the
+// structural branch has neither. Requiring the key there would refuse honest
+// slices over a field that would mean nothing if they filled it in.
+function validateSurfaceCoverage(value, item, label, errors) {
+    if (value === undefined && item.branch !== 'behavioral')
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`${label}: surface_coverage must be an array of {capability_id, scenario, surfaces} entries, one per Scenario written`);
+        return;
+    }
+    for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            errors.push(`${label}: surface_coverage[${index}] must be an object with capability_id, scenario and surfaces; got ${jsonType(entry)}`);
+            continue;
+        }
+        const record = entry;
+        if (typeof record.capability_id !== 'string' || !item.capability_ids.includes(record.capability_id)) {
+            errors.push(`${label}: surface_coverage[${index}].capability_id ${String(record.capability_id)} is not in this plan item`);
+        }
+        if (typeof record.scenario !== 'string' || !record.scenario.trim()) {
+            errors.push(`${label}: surface_coverage[${index}].scenario must name the exact Scenario it covers`);
+        }
+        if (!Array.isArray(record.surfaces) || record.surfaces.length === 0
+            || record.surfaces.some((surface) => typeof surface !== 'string' || !surface.trim())) {
+            errors.push(`${label}: surface_coverage[${index}].surfaces must name at least one surface the Scenario drives`);
+        }
+    }
+}
 function jsonType(value) {
     if (value === null)
         return 'null';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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.6.0 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.6.1 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
@@ -48,9 +48,13 @@ No strict JSON handoff is required.
 Update the same checkpoint as promises complete. Keep facts compact and
 source-referenced. The normative JSON shape of one facts entry is:
 ```json
-{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
+{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"],"established_by":"read"}
 ```
-Every facts entry is an object in that shape, never a string. Before handoff,
+Every facts entry is an object in that shape, never a string; `established_by` is
+`read` or `ran: <command>`, and a failure you reproduced is the second kind. On
+the behavioral branch, when you rename a Scenario or change what its steps drive,
+update that Scenario's `surface_coverage` entry in the same breath — the
+coordinator publishes those entries and does not reread your steps. Before handoff,
 make one final read of the checkpoint and confirm every `facts` entry is an
 object in the normative shape above. Do not delegate repair or auto-resume after
 the fuse. Preserve files and checkpoint for the coordinator's existing

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

@@ -21,21 +21,46 @@ nothing to put in them: `written_paths` (only your own `owned_paths`),
 unresolved harness problems). A missing array is not an empty one — the gate
 that reads this checkpoint refuses it either way.
 
-Facts are short statements with source references.
-The normative JSON shape of one facts entry is:
+Facts are short statements with source references, and each one says how it was
+established. The normative JSON shape of one facts entry is:
 ```json
-{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
+{"fact":"The route creates an order.","source_refs":["app/orders.rb:12"],"established_by":"read"}
 ```
-Every facts entry is an object in that shape, never a string. Never embed source
-files, suite copies, or transcript.
+Every facts entry is an object in that shape, never a string. `established_by` is
+`read` when the references are what establishes it, or `ran: <command>` when
+something was executed and its result observed. You run nothing, so every fact
+you add yourself is `read`; a `ran:` fact is one the coordinator established
+before fan-out, and that is exactly what makes it worth more than a fact anybody
+read. Never embed source files, suite copies, or transcript.
+
+On the behavioral branch your checkpoint also carries `surface_coverage`: one
+entry per Scenario you write, recorded as you write it.
+```json
+{"capability_id":"<one of your plan item's ids>","scenario":"<exact Scenario name>","surfaces":["POST /orders"]}
+```
+`surfaces` names the addresses and jobs the Scenario's `When` really reaches — not
+the ones its capability was assigned, and not the ones you meant to reach. Only
+you can know this: the coordinator publishes this join and never reopens your step
+files. On a2time, 2026-08-17, it had to reconstruct the join from what the workers
+said about their work; the independent reviewer read the steps instead, six
+Scenarios claimed addresses their steps never drove, and the server refused the
+publication.
 
 Write first, then find out. Start with the planned cases your seeded facts
 already support and get them onto disk; go reading only for what you still lack
 after that. The opposite order — survey the sources, then write — is what spent
 seven of eight workers' entire ceilings on a2time, 2026-08-10, and produced no
-file at all. A fact already in your checkpoint is settled: do not establish it a
-second time. Nothing mechanical enforces that rule; it holds because you keep
-it.
+file at all.
+
+A fact already in your checkpoint is settled: do not establish it a second time.
+A `read` fact is settled the same way — until a file you had to open anyway says
+otherwise. Then check that one fact against its own `source_refs`, which is two
+or three lines and not a fresh survey; if it is wrong, correct the entry and say
+so in `known_problems`. On a2time, 2026-08-17, a seeded fact said a dismissed
+employee cannot sign in — one method read, another remembered — and sixteen
+workers got it as verified. One of them looked, disagreed, and kept its scenario
+honest, which is the only reason that access hole came back red instead of green.
+Nothing mechanical enforces any of this; it holds because you keep it.
 
 Read only the `source_paths` and dependencies your finite planned cases need.
 Ask closed questions with the files to look in. For a closed missing fact, use