unitbob 0.7.13 → 0.7.15

package/dist/verbs/validateWorkerCheckpoints.js

@@ -1,5 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { assignedSurfaces, checkpointPath, readWorkerPlan, requestDigest, validateWorkerPlanFiles, workerPlanDigest, } from "../files/workerPlan.js";
+import { join } from 'node:path';
+import { assignedMarkers, assignedSurfaces, checkpointPath, readWorkerPlan, requestDigest, sliceDigest, validateWorkerPlanFiles, workerPlanDigest, } from "../files/workerPlan.js";
+// Spec 55-1, §3. The verdict is per slice. One list of every slice's errors,
+// thrown as one exception, made one bad checkpoint out of 43 a refusal of the
+// whole branch — and the workflow turned that into a `build_error` for 37
+// capabilities on repo 139. A slice is the unit of work here: the ones that
+// pass go on to the build, the ones that do not go back to their worker with
+// exactly the lines printed under their name. The exception stays for the one
+// thing that is not a slice's fault: a plan that does not validate.
 export async function validateWorkerCheckpoints(config, _args = [], deps = { stdout: process.stdout }) {
     const planErrors = validateWorkerPlanFiles(config.projectRoot);
     if (planErrors.length > 0)
@@ -8,61 +16,188 @@ export async function validateWorkerCheckpoints(config, _args = [], deps = { std
     const expectedRequestDigest = requestDigest(config.projectRoot);
     const expectedPlanDigest = workerPlanDigest(config.projectRoot);
     const assigned = assignedSurfaces(config.projectRoot);
-    const errors = [];
+    const markers = assignedMarkers(config.projectRoot);
+    const valid_workers = [];
+    const invalid_workers = [];
     for (const item of plan.workers) {
         const label = `${item.branch}:${item.worker_id}`;
-        const path = checkpointPath(config.projectRoot, item);
-        if (!existsSync(path)) {
-            errors.push(`${label}: checkpoint is missing at ${path}`);
-            continue;
+        const errors = sliceErrors(config.projectRoot, item, expectedRequestDigest, expectedPlanDigest, assigned, markers);
+        if (errors.length === 0)
+            valid_workers.push(label);
+        else
+            invalid_workers.push({ worker: label, errors });
+    }
+    if (valid_workers.length > 0)
+        deps.stdout.write(`Worker checkpoints valid for ${valid_workers.join(', ')}.\n`);
+    for (const { worker, errors } of invalid_workers) {
+        deps.stdout.write(`\n${worker}:\n${errors.map((line) => `  ${line}\n`).join('')}`);
+    }
+    if (invalid_workers.length > 0) {
+        deps.stdout.write(`\n${invalid_workers.length} of ${plan.workers.length} checkpoints invalid — ` +
+            'relaunch those workers once with the lines above.\n');
+    }
+    return { valid_workers, invalid_workers };
+}
+// Everything one slice can be wrong about, without the slice's label: the
+// caller prints the errors under it.
+function sliceErrors(projectRoot, item, expectedRequestDigest, expectedPlanDigest, assigned, markers) {
+    const errors = [];
+    const path = checkpointPath(projectRoot, item);
+    if (!existsSync(path))
+        return [`checkpoint is missing at ${path}`];
+    let checkpoint;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return ['checkpoint must be an object'];
+        checkpoint = parsed;
+    }
+    catch (error) {
+        return [`checkpoint is not valid JSON: ${error.message}`];
+    }
+    if (checkpoint.request_digest !== expectedRequestDigest)
+        errors.push('request_digest is stale');
+    if (checkpoint.plan_digest !== expectedPlanDigest)
+        errors.push('plan_digest is stale');
+    // Fresh by construction after a carry-over, which is why the next line exists:
+    // `plan_digest` says "the plan on disk", `slice_digest` says "this slice of it".
+    if (checkpoint.slice_digest !== sliceDigest(item))
+        errors.push('slice_digest does not match its plan item');
+    if (checkpoint.branch !== item.branch)
+        errors.push('branch does not match its plan item');
+    if (checkpoint.worker_id !== item.worker_id)
+        errors.push('worker_id does not match its plan item');
+    const completed = stringArray(checkpoint.completed_promises, 'completed_promises', errors);
+    const unresolved = stringArray(checkpoint.unresolved_promises, 'unresolved_promises', errors);
+    const accounted = [...completed, ...unresolved];
+    for (const promise of item.promises) {
+        const count = accounted.filter((candidate) => candidate === promise).length;
+        if (count !== 1)
+            errors.push(`promise ${promise} must appear exactly once across completed/unresolved promises`);
+    }
+    // With the plan's own text next to it: a promise a worker annotated — "(done)",
+    // a trailing note — is the common way this fails, and the exact string it
+    // should have carried is the whole fix. When no one promise stands out, all
+    // of them are listed.
+    for (const promise of accounted.filter((candidate) => !item.promises.includes(candidate))) {
+        const expected = closestPromise(promise, item.promises);
+        const hint = expected
+            ? `expected exactly: ${expected}`
+            : `the plan item's promises are: ${item.promises.map((text) => JSON.stringify(text)).join(', ')}`;
+        errors.push(`checkpoint names promise ${promise} outside its plan item — ${hint}`);
+    }
+    const writtenPaths = stringArray(checkpoint.written_paths, 'written_paths', errors);
+    for (const pathValue of writtenPaths.filter((candidate) => !item.owned_paths.includes(candidate))) {
+        errors.push(`written path ${pathValue} is not an owned path`);
+    }
+    for (const pathValue of writtenPaths.filter((candidate) => item.owned_paths.includes(candidate) && !existsSync(join(projectRoot, candidate)))) {
+        errors.push(`written path ${pathValue} is not on disk`);
+    }
+    validateCompactFacts(checkpoint.facts, errors);
+    validateMarkers(projectRoot, item, writtenPaths, markers, errors);
+    validateSurfaceCoverage(checkpoint.surface_coverage, item, assigned, errors);
+    validateUnreachableSurfaces(checkpoint.unreachable_surfaces, item, checkpoint.surface_coverage, assigned, errors);
+    stringArray(checkpoint.decisions, 'decisions', errors);
+    stringArray(checkpoint.known_problems, 'known_problems', errors);
+    return errors;
+}
+// The plan promise a rewritten one most likely started as: the one it contains
+// or is contained by, else the one sharing the longest prefix. A hint, never a
+// judgement — the error is the same either way.
+//
+// A shared prefix shorter than `PREFIX_TO_MEAN_IT` is what any two English
+// sentences share ("A signed-in", "The user "); below it the guess would be
+// noise, and the caller lists every promise instead.
+const PREFIX_TO_MEAN_IT = 8;
+function closestPromise(candidate, promises) {
+    const contained = promises.find((promise) => candidate.includes(promise) || promise.includes(candidate));
+    if (contained)
+        return contained;
+    let best = null;
+    let bestPrefix = 0;
+    for (const promise of promises) {
+        let shared = 0;
+        while (shared < promise.length && shared < candidate.length && promise[shared] === candidate[shared])
+            shared += 1;
+        if (shared > bestPrefix) {
+            best = promise;
+            bestPrefix = shared;
         }
-        let checkpoint;
-        try {
-            const parsed = JSON.parse(readFileSync(path, 'utf8'));
-            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-                errors.push(`${label}: checkpoint must be an object`);
+    }
+    if (bestPrefix >= PREFIX_TO_MEAN_IT)
+        return best;
+    return promises.length === 1 ? promises[0] : null;
+}
+// Spec 55-1, §4. The files this slice wrote, read for the one thing the server
+// will refuse them for and nothing checked before the build: the marker. A
+// behavioral Scenario carries exactly one `@ubc_…` tag; a structural file names
+// a marker at least once, anywhere — the server counts occurrences per file,
+// and this gate counts no finer. On repo 139, 31 of 37 feature files reached
+// `validate-build` with no tag at all, after the workers were gone.
+//
+// Where this gate is narrower than the server, on purpose: the marker must be
+// one of *this slice's*. The server accepts any marker of the assignment,
+// because it has no idea slices exist; a Scenario a worker tagged with its
+// neighbour's marker would pass there and count for the wrong capability. The
+// same narrowing `unreachable_surfaces` already has for addresses — see
+// `test/architecture.test.ts`, which records both.
+//
+// A file that is not on disk is its neighbour's error, reported once, above.
+function validateMarkers(projectRoot, item, writtenPaths, markers, errors) {
+    const mine = item.capability_ids.flatMap((id) => markers.get(id) ?? []);
+    if (mine.length === 0)
+        return;
+    const oneOf = `(one of ${mine.map((marker) => item.branch === 'behavioral' ? `@${marker}` : marker).join(', ')})`;
+    for (const relative of writtenPaths) {
+        if (!item.owned_paths.includes(relative))
+            continue;
+        const path = join(projectRoot, relative);
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, 'utf8');
+        if (item.branch === 'behavioral') {
+            if (!relative.endsWith('.feature'))
                 continue;
+            for (const scenario of scenarios(text)) {
+                const tags = scenario.tags.filter((tag) => MARKER_TAG.test(tag));
+                const own = tags.filter((tag) => mine.includes(tag.slice(1)));
+                if (tags.length === 1 && own.length === 1)
+                    continue;
+                const has = tags.length === 0
+                    ? 'none'
+                    : tags.length > 1 ? `${tags.length}` : `${tags[0]}, which is not`;
+                errors.push(`${relative}:${scenario.line}: ${scenario.keyword} "${scenario.name}" needs exactly one @ubc_… tag of this slice ${oneOf}; it has ${has}`);
             }
-            checkpoint = parsed;
         }
-        catch (error) {
-            errors.push(`${label}: checkpoint is not valid JSON: ${error.message}`);
+        else if (!mine.some((marker) => text.includes(marker))) {
+            errors.push(`${relative}: no ubc_… marker of this slice ${oneOf} appears in the file`);
+        }
+    }
+}
+const MARKER_TAG = /^@ubc_[0-9a-f]{12}$/;
+const SCENARIO_LINE = /^\s*(Scenario Outline|Scenario Template|Scenario|Example):\s*(.*)$/;
+// Gherkin, read only as far as tags go: the tag lines immediately above a
+// Scenario, across blank lines and comments. `Feature:` and `Examples:` reset
+// the pile so a feature-level tag or one over Examples never counts as the
+// Scenario's. Anything else — steps, docstrings, tables — clears it too, so a
+// tag can only ever belong to the container right below it.
+function scenarios(text) {
+    const found = [];
+    let pending = [];
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        if (line.startsWith('@')) {
+            pending.push(...line.split(/\s+/).filter((tag) => tag.startsWith('@')));
             continue;
         }
-        if (checkpoint.request_digest !== expectedRequestDigest)
-            errors.push(`${label}: request_digest is stale`);
-        if (checkpoint.plan_digest !== expectedPlanDigest)
-            errors.push(`${label}: plan_digest is stale`);
-        if (checkpoint.branch !== item.branch)
-            errors.push(`${label}: branch does not match its plan item`);
-        if (checkpoint.worker_id !== item.worker_id)
-            errors.push(`${label}: worker_id does not match its plan item`);
-        const completed = stringArray(checkpoint.completed_promises, `${label}: completed_promises`, errors);
-        const unresolved = stringArray(checkpoint.unresolved_promises, `${label}: unresolved_promises`, errors);
-        const accounted = [...completed, ...unresolved];
-        for (const promise of item.promises) {
-            const count = accounted.filter((candidate) => candidate === promise).length;
-            if (count !== 1)
-                errors.push(`${label}: promise ${promise} must appear exactly once across completed/unresolved promises`);
-        }
-        for (const promise of accounted.filter((candidate) => !item.promises.includes(candidate))) {
-            errors.push(`${label}: checkpoint names promise ${promise} outside its plan item`);
-        }
-        const writtenPaths = stringArray(checkpoint.written_paths, `${label}: written_paths`, errors);
-        for (const pathValue of writtenPaths.filter((candidate) => !item.owned_paths.includes(candidate))) {
-            errors.push(`${label}: written path ${pathValue} is not an owned path`);
-        }
-        validateCompactFacts(checkpoint.facts, label, errors);
-        validateSurfaceCoverage(checkpoint.surface_coverage, item, label, errors);
-        validateUnreachableSurfaces(checkpoint.unreachable_surfaces, item, checkpoint.surface_coverage, assigned, label, errors);
-        stringArray(checkpoint.decisions, `${label}: decisions`, errors);
-        stringArray(checkpoint.known_problems, `${label}: known_problems`, errors);
-    }
-    if (errors.length > 0)
-        throw new Error(`Worker checkpoints are invalid:\n- ${errors.join('\n- ')}`);
-    const validWorkers = plan.workers.map((item) => `${item.branch}:${item.worker_id}`);
-    deps.stdout.write(`Worker checkpoints valid for ${validWorkers.join(', ')}.\n`);
-    return { valid_workers: validWorkers };
+        const match = SCENARIO_LINE.exec(line);
+        if (match)
+            found.push({ line: index + 1, keyword: match[1], name: match[2].trim(), tags: pending });
+        pending = [];
+    }
+    return found;
 }
 function stringArray(value, label, errors) {
     if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
@@ -81,27 +216,27 @@ function stringArray(value, label, errors) {
 // 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) {
+function validateCompactFacts(value, errors) {
     if (!Array.isArray(value)) {
-        errors.push(`${label}: facts must be an array`);
+        errors.push('facts must be an array');
         return;
     }
     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, source_refs and established_by; got ${jsonType(entry)}`);
+            errors.push(`$.facts[${index}] must be an object with fact, source_refs and established_by; got ${jsonType(entry)}`);
             continue;
         }
         const fact = entry;
         if (typeof fact.fact !== 'string' || !fact.fact.trim())
-            errors.push(`${label}: facts[${index}].fact must be non-empty`);
+            errors.push(`facts[${index}].fact must be non-empty`);
         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`);
+            errors.push(`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>"`);
+            errors.push(`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`);
+            errors.push(`facts[${index}] may not embed source, transcript, or suite copies`);
         }
     }
 }
@@ -116,28 +251,49 @@ function validateCompactFacts(value, label, errors) {
 // 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) {
+//
+// Spec 55-1, §3 and §4. Two rules here are the server's, taken as they are.
+// An empty `surfaces` is refused only when the capability was given addresses
+// at all (`assigned_any` in behavioral_suite_metadata_validator.rb) — a
+// Scenario over a capability with no addresses has nothing to name, and
+// refusing it here while the server accepts it made the connector stricter than
+// the side that decides. And every address named must be one this capability
+// was assigned — the mirror of the membership check `unreachable_surfaces`
+// already had, and the check that would have caught the neighbours' routes and
+// server actions repo 139's workers wrote down on their role's own advice.
+function validateSurfaceCoverage(value, item, assigned, 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`);
+        errors.push('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)}`);
+            errors.push(`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`);
+        const capabilityId = typeof record.capability_id === 'string' ? record.capability_id : null;
+        if (capabilityId === null || !item.capability_ids.includes(capabilityId)) {
+            errors.push(`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`);
+            errors.push(`surface_coverage[${index}].scenario must name the exact Scenario it covers`);
+        }
+        const known = capabilityId === null ? [] : assigned.get(capabilityId) ?? [];
+        if (!Array.isArray(record.surfaces) || record.surfaces.some((surface) => typeof surface !== 'string' || !surface.trim())) {
+            errors.push(`surface_coverage[${index}].surfaces must be an array of the addresses the Scenario drives`);
+            continue;
+        }
+        if (known.length === 0)
+            continue;
+        if (record.surfaces.length === 0) {
+            errors.push(`surface_coverage[${index}].surfaces must name at least one surface the Scenario drives`);
         }
-        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`);
+        for (const surface of record.surfaces) {
+            if (!known.includes(surface))
+                errors.push(`${surface} was not assigned to ${capabilityId}`);
         }
     }
 }
@@ -155,11 +311,11 @@ function validateSurfaceCoverage(value, item, label, errors) {
 //
 // Behavioral only, for the same reason as its neighbour: the structural branch
 // has no addresses to account for.
-function validateUnreachableSurfaces(value, item, coverage, assigned, label, errors) {
+function validateUnreachableSurfaces(value, item, coverage, assigned, errors) {
     if (value === undefined && item.branch !== 'behavioral')
         return;
     if (!Array.isArray(value)) {
-        errors.push(`${label}: unreachable_surfaces must be an array of {surface, reason} entries, empty when the slice can drive everything it was given`);
+        errors.push('unreachable_surfaces must be an array of {surface, reason} entries, empty when the slice can drive everything it was given');
         return;
     }
     const driven = new Set(drivenSurfaces(coverage));
@@ -171,13 +327,13 @@ function validateUnreachableSurfaces(value, item, coverage, assigned, label, err
     const seen = new Set();
     for (const [index, entry] of value.entries()) {
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-            errors.push(`${label}: unreachable_surfaces[${index}] must be an object with surface and reason; got ${jsonType(entry)}`);
+            errors.push(`unreachable_surfaces[${index}] must be an object with surface and reason; got ${jsonType(entry)}`);
             continue;
         }
         const record = entry;
         const surface = record.surface;
         if (typeof surface !== 'string' || !surface.trim()) {
-            errors.push(`${label}: unreachable_surfaces[${index}].surface must name one address`);
+            errors.push(`unreachable_surfaces[${index}].surface must name one address`);
             continue;
         }
         // A reason per address, never one reason for a list. A sentence you cannot
@@ -185,19 +341,19 @@ function validateUnreachableSurfaces(value, item, coverage, assigned, label, err
         // which is the whole guard, and the reason this bucket stays narrow while
         // its neighbour widened.
         if (typeof record.reason !== 'string' || !record.reason.trim()) {
-            errors.push(`${label}: unreachable_surfaces[${index}].reason must say what has to happen elsewhere for ${surface} to be called`);
+            errors.push(`unreachable_surfaces[${index}].reason must say what has to happen elsewhere for ${surface} to be called`);
         }
         if (driven.has(surface)) {
-            errors.push(`${label}: ${surface} is driven by a Scenario and declared unreachable — it is one or the other`);
+            errors.push(`${surface} is driven by a Scenario and declared unreachable — it is one or the other`);
         }
         // Only when the assignment actually listed addresses for this capability.
         // An assignment that says nothing cannot say a surface is foreign, and
         // refusing there would refuse honest slices over an absence.
         if (known.size > 0 && !known.has(surface)) {
-            errors.push(`${label}: ${surface} was not assigned to this slice`);
+            errors.push(`${surface} was not assigned to this slice`);
         }
         if (seen.has(surface))
-            errors.push(`${label}: unreachable_surfaces names ${surface} more than once`);
+            errors.push(`unreachable_surfaces names ${surface} more than once`);
         else
             seen.add(surface);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.7.13",
+  "version": "0.7.15",
   "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.13 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.15 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
@@ -51,7 +51,10 @@ source-referenced. The normative JSON shape of one facts entry is:
 {"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; `established_by` is
-`read` or `ran: <command>`, and a failure you reproduced is the second kind. On
+`read` or `ran: <command>`, and a failure you reproduced is the second kind.
+`known_problems` and `decisions` are arrays of plain strings. A promise moves
+between `unresolved_promises` and `completed_promises` by its exact plan text —
+never rewritten, never annotated. 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,

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

@@ -188,6 +188,10 @@ A reviewer who improves the thing under review has reviewed its own work.
 by the connector and travels with the upload; a run started here lands on the
 shared test database and proves nothing about the candidate that was bound.
 
+**Do not delegate.** Read every Scenario yourself, in this context, and write the
+one file. A review split across helpers comes back as their notifications to
+whoever launched you, and the file you owe is assembled by nobody.
+
 **Do not rewrite anybody's verdict, including on a second pass.** If you find
 yourself weighing whether an objection is worth the trouble, the answer is that
 it costs this run nothing at all. A second pass that arrives with a

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

@@ -38,14 +38,22 @@ 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
+`surfaces` names the **assigned** addresses the Scenario's `When` really reaches —
+not the ones you meant to reach. An address of another capability, a server
+action, a private function — none of these is a surface: say it in `decisions`
+and leave it out of `surfaces`. Only you can know what the `When` reaches: 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.
 
+A Scenario that reaches none of the addresses assigned to its capability — dead
+code, a private function, a job nothing on the map calls — is not a Scenario of
+this suite. Delete it, or fold what it checks into a Scenario that does reach
+one, and write the reason in `decisions`. There is no honest
+`surface_coverage` row for it, and the server has no place for it either.
+
 Your checkpoint also carries `unreachable_surfaces`, and it is usually empty. An
 address goes there only when *nothing you can do* makes that request happen — a
 third party's callback, a vendor's webhook, a redirect a real account has to
@@ -98,10 +106,13 @@ copy it into an owned file.
 
 Never run the suite, boot the application, or perform branch-global duplicate,
 marker, metadata, or surface validation. You may make one final read of your
-owned files before handoff. During that final read, confirm every `facts` entry
-is an object in the normative shape above and correct the checkpoint if it is
-not. Do not create temporary self-validation scripts or
-loop over repeated rereads.
+owned files before handoff. During that final read, confirm three things and
+correct what is not so: every `facts` entry is an object in the normative shape
+above; every `Scenario` and `Scenario Outline` carries exactly one `@ubc_…` tag,
+the `case_marker` of its capability (on the structural branch: every file you
+wrote names the marker of its interface at least once); every address in
+`surface_coverage` is one assigned to that capability in the request. Do not
+create temporary self-validation scripts or loop over repeated rereads.
 
 Your ceiling is an emergency fuse, not a budget to spend. It sits far above the
 work one plan item takes, so reaching it means this run is broken rather than