omp-conductor 0.18.1 → 0.18.2

package/README.md

@@ -316,7 +316,7 @@ Two words, and one of them takes a flag:
 | `stop` | paused | disarmed | stopped (systemctl-aware) | left running |
 | `stop --pane` | paused | disarmed | stopped | stopped + recovery pinned off |
 
-`resume` clears pause **and** any `stop --pane` recovery pin, and **never re-arms**. `arm` is proof-gated: it sends a Telegram challenge and writes the arm marker only after your reply appears as a *user* turn in the orchestrator transcript. `stop --pane` targets the configured conductor agent only — it does **not** run `systemctl stop herdr-fleet`. To bounce the daemon without stopping the fleet, use `restart`.
+`resume` clears pause **and** any `stop --pane` recovery pin, and **never re-arms**. `arm` is proof-gated: it sends a Telegram challenge and writes the arm marker only after the orchestrator's inbound adapter has acknowledged your reply in conductor's own state — no transcript is read, so where (or whether) a session file lives does not matter (#614). `stop --pane` targets the configured conductor agent only — it does **not** run `systemctl stop herdr-fleet`. To bounce the daemon without stopping the fleet, use `restart`.
 
 **Removed in 0.15.0**, each exiting `2` with a pointer: `halt` (now `stop`), `pause` (use `hold`), `release-pane` (now part of `resume`), and `graph-setup` (now [`setup graph`](https://github.com/TerrifiedBug/conductor/blob/main/omp/REFERENCE.md#code-graph-discovery)). Dropping `pause` cost one real capability, "stop claiming but keep ticking", which is now `hold --keep-ticks` rather than a fifth verb. It matters because disarming is the expensive half of a hold: re-arming sends a Telegram challenge and blocks until you answer it in the chat, so stopping claims for ten minutes otherwise costs a manual round trip to get the heartbeat back — while the workers a hold deliberately leaves running have nothing shepherding them.
 

package/REFERENCE.md

@@ -2317,7 +2317,7 @@ omp-conductor help
 | `hold [--keep-ticks] [--project NAME]` | fleet | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this when the intent is "stop the conductor" without killing processes. `--keep-ticks` pauses claiming but leaves the arm marker, so the heartbeat keeps reporting and `resume` alone restores the fleet — no fresh arm challenge. See [Stop the conductor](README.md#stop-the-conductor-hold--stop). |
 | `drain start --until ISO\|DURATION [--reason TEXT]` / `drain status` / `drain cancel` | project | Start, inspect, or cancel the project's self-expiring admission fence (#484): a durable, bounded alternative to queue-label churn before a release. `start` writes the project's drain record through the landed `createDrain` — new claims pause while active runs settle, and admission resumes automatically at the absolute deadline even if the orchestrator dies. A successful mediated `conductor_release` also clears the drain once the terminal release act completes — version-bump preparation stays latched until the tag is actually cut — so the release window ends with the release itself rather than latching until the deadline (#791). `--until` takes an ISO instant or a relative duration (`90s`, `45m`, `2h`, `1d`) that must be bounded and in the future; a missing, unparseable, unbounded, or past expiry exits `2` before any state changes. `--reason` (1–500 characters) is persisted on the record. `status` reports inactive, or the active drain's creation time, absolute expiry, reason, and remaining active runs from the structured status snapshot. `cancel` removes only the named project's drain and is idempotent. The drain never touches the pause sentinel, the arm marker, or any queue label — it is a file record, not a hold. |
 | `stop [--pane] [--project NAME]` | fleet | Stop the conductor: pause claiming, disarm ticks, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `stop --pane` also pins herdr-conductor recovery off for the conductor agent only — it does **not** stop `herdr-fleet.service` or any other herdr session. Fail-closed: exits nonzero unless the agent is proven gone. To bounce the daemon without stopping the fleet, use `restart`. |
-| `arm [--project NAME]` | fleet | Proof-gated: send a Telegram challenge and write this project's arm marker only after your reply appears as a user turn in the orchestrator transcript. The challenge names the project, so a host running two fleets is not ambiguous. Never auto-armed by `resume` / `hold`. |
+| `arm [--project NAME]` | fleet | Proof-gated: send a Telegram challenge and write this project's arm marker only after the orchestrator's inbound adapter has acknowledged your reply in conductor's own state — no transcript is read, so where (or whether) a session file lives does not matter (#614). The challenge names the project, so a host running two fleets is not ambiguous. Never auto-armed by `resume` / `hold`. |
 | `disarm [--project NAME]` | fleet | Remove this project's arm marker so its ticks skip; another project's ticks keep running. Also clears a pre-per-project shared `armed` marker while that marker is still what holds this fleet's gate open — otherwise the disarm would not disarm. Processes untouched. |
 | `tail <issue>` | project | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
 | `extend <issue> --turns N [--project NAME]` | project | Raise a live worker's effective turn ceiling through its owning daemon without restarting its session. If the latest run is failed, killed, orphaned, or blocked and has no live controller, store a one-shot ceiling for that issue's next claimed attempt instead. A next-attempt value must exceed the project base, every extension must stay at or below `workerMaxTurnsCeiling`, and live extensions remain monotonic. The pending value appears in `status`, is recorded in `ledger`, and is consumed atomically by one claim. |

package/agents/to-spec.md

@@ -50,6 +50,9 @@ required and no extra keys are accepted:
   exact ref, and `freshAt` = epoch milliseconds when you actually observed it.
   Conductor refuses results whose source is older than 24 hours or missing
   name/ref/freshAt — an unsourced verdict is not grooming, it is prose.
+- `evidence` — the files/symbols that prove the verdict. Required for
+  `ALREADY DONE`: name the symbol/file that already does the work, never a
+  title match. Welcome on every other verdict.
 - `laterWorkInvalidates` — boolean: did later work (an epic committed after
   this candidate was filed) retire its premise?
 - `laterWorkNote` — what you searched for that check and what you found. Even
@@ -63,8 +66,9 @@ required and no extra keys are accepted:
   implementing, and how to prove it is not.
 - `proofCommands` — the focused commands that prove the work, each with its
   `cwd` when it matters.
-- `fileLane` — the files and directories this slice writes; `dependencies` —
-  open prerequisites, `[]` when none.
+- `fileLane` — the files and directories this slice writes.
+- `dependencies` — open prerequisite issue numbers, each a bare number
+  (`875`) or a string (`"875"`); `[]` when none.
 - `proposedBrief` — required iff `verdict` is `PROMOTABLE`: the brief a worker
   would be dispatched with, including the silent fake and the proof commands.
 - `reasonNotToPromote` — required for every other verdict: why this must not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/schema/config.schema.json

@@ -387,10 +387,15 @@
                 "type": "integer",
                 "minimum": 1,
                 "maximum": 6
+              },
+              "adjudicator": {
+                "default": "task",
+                "type": "string",
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
               }
             },
             "additionalProperties": false,
-            "description": "Review strictness and round ceiling for green PRs"
+            "description": "Review strictness, round ceiling and adjudicator role for green PRs"
           },
           "authority": {
             "type": "object",

package/src/arm-challenge.ts

@@ -1,69 +1,154 @@
 /**
  * Authenticated pending-challenge state for the arming handshake (conductor
- * #415).
+ * #415, transaction reworked by #614, storage hardened by review of #896).
  *
  * `armTicks` (fleet.ts) sends a short-lived `FLEET-…` code to the operator and
- * proves the reply by scanning the orchestrator session transcript. That reply
- * also lands in the orchestrator as an ordinary user turn, where the model once
- * ad-libbed pairing-safety prose because it had no trusted way to recognise it.
+ * waits for the orchestrator to acknowledge it. The acknowledgement is
+ * conductor-owned state: the orchestrator's inbound user-turn adapter
+ * (orchestrator-tick.ts) writes it the moment the real reply arrives as a user
+ * turn — never the model, and never a transcript scan, so the proof no longer
+ * depends on where (or whether) a session file lives.
  *
  * This module is the bridge between the two roles without an import cycle:
  * `fleet.ts` imports `daemon.ts`, `daemon.ts` imports `orchestrator-tick.ts`,
  * so `orchestrator-tick.ts` can never import `fleet.ts`. Both already import
- * `config.ts`, so the pending-challenge record lives next to the other state
- * under `stateDir()` and both sides reach it through *this* leaf module.
+ * `config.ts`, so the state lives next to the other state under `stateDir()`
+ * and both sides reach it through *this* leaf module.
+ *
+ * The handshake keeps no shared mutable state at all — every file is named by
+ * its own key, and every deletion is id-addressed, so two processes can
+ * neither lose each other's updates nor delete each other's proofs:
+ *
+ * - `arm-challenges/<project key>.json` — one pending challenge per project:
+ *   `{ project, id, hash, sentAt, expiresAt }`. Host-owned: only `armTicks`
+ *   writes it (record before the send, settle on consumption/timeout/send
+ *   failure), always through the atomic tmp+rename write the admission ack
+ *   uses. A re-armed project overwrites its own file — pruning only its own
+ *   prior id's acknowledgement; a concurrent arm for a different project
+ *   touches a different file.
+ * - `arm-challenge-acks/<challenge id>.json` — one file per acknowledgement:
+ *   `{ challengeId, acknowledgedAt }`. The adapter's acknowledgement is a
+ *   single-file create/overwrite via rename — it never reads or rewrites
+ *   another transaction's record. Files that outlive their transaction (a
+ *   crash between the adapter's write and the host's settle) are inert by
+ *   construction and removed only by age, never by membership in any
+ *   directory snapshot (see {@link gcAgedAcks}).
  *
  * Only the sha-256 of the code is ever persisted — never the code, whose
  * plaintext appearance in the protected session transcript is already the
- * backend proof and must not leak into a durable report, an issue comment, or a
- * diagnostic line the way a new artifact could. The orchestrator classifies a
- * reply by hashing its tokens against this record, so nothing on the east side
- * of the boundary trusts a `FLEET-` prefix.
+ * backend proof and must not leak into a durable report, an issue comment, or
+ * a diagnostic line the way a new artifact could. The id is a random UUID cut
+ * with the challenge, so acknowledgement records are challenge-specific
+ * without carrying anything guessable. Neither side trusts a `FLEET-` prefix:
+ * a reply is classified by hashing its whitespace-separated tokens against
+ * the pending record, so nothing on the east side of the boundary can arm a
+ * fleet with a lookalike.
  */
 
-import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stateDir } from "./config.ts";
 
-const ARM_CHALLENGE_FILE = "arm-challenge.json";
+const ARM_CHALLENGES_DIR = "arm-challenges";
+const ARM_ACKS_DIR = "arm-challenge-acks";
 
 interface PendingChallenge {
+  /** The project key this pending belongs to, mirrored for read-back checks. */
+  project: string;
+  /** Random transaction id, cut when this challenge was recorded. */
+  id: string;
   /** sha-256 hex of the challenge code — never the code itself. */
   hash: string;
+  /** Unix ms the challenge was recorded, just before the send. */
+  sentAt: number;
   /** Unix ms after which a matching reply is no longer an active proof. */
   expiresAt: number;
 }
 
-/** Keyed by project name; `""` is the pre-multi-project (un-named) spelling. */
-type PendingChallenges = Record<string, PendingChallenge>;
+interface ArmAcknowledgement {
+  /** The exact challenge id this record satisfies. */
+  challengeId: string;
+  /** Unix ms the inbound adapter acknowledged the reply. */
+  acknowledgedAt: number;
+}
+
+function challengesDir(): string {
+  return join(stateDir(), ARM_CHALLENGES_DIR);
+}
+
+function acksDir(): string {
+  return join(stateDir(), ARM_ACKS_DIR);
+}
 
-function challengesPath(): string {
-  return join(stateDir(), ARM_CHALLENGE_FILE);
+function ackPath(challengeId: string): string {
+  return join(acksDir(), `${challengeId}.json`);
 }
 
 function projectKey(project?: string): string {
   return project ?? "";
 }
 
-function readChallenges(): PendingChallenges {
+/**
+ * Filesystem-safe, injective encoding of a project key. Raw names that need
+ * no escaping are used verbatim; everything else (including the empty key of
+ * an unstamped config) becomes `=` plus hex bytes — `=` never appears in the
+ * raw class, so the two namespaces cannot collide.
+ */
+function encodeProjectKey(key: string): string {
+  if (/^[A-Za-z0-9._-]{1,64}$/.test(key) && key !== "." && key !== "..") return key;
+  return `=${[...Buffer.from(key, "utf8")].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function pendingPath(key: string): string {
+  return join(challengesDir(), `${encodeProjectKey(key)}.json`);
+}
+
+/**
+ * Atomic durable write, exactly like the admission ack: content lands at a
+ * unique temp path and is renamed into place, so every reader — including the
+ * one-shot inbound adapter racing the host — sees either the old file or the
+ * new one, never a mid-truncate parse.
+ */
+function writeFileAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`;
   try {
-    const parsed: unknown = JSON.parse(readFileSync(challengesPath(), "utf8"));
-    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as PendingChallenges;
-    }
-  } catch {
-    /* absent or unreadable — no active challenge */
+    // 0600 like the other conductor state an operator never shares; the
+    // records are hashes and random ids, but there is no reason to be less
+    // careful.
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
   }
-  return {};
 }
 
-function writeChallenges(map: PendingChallenges): void {
-  const path = challengesPath();
-  mkdirSync(dirname(path), { recursive: true });
-  // 0600 like the other conductor state an operator never shares; the record is
-  // only a hash, but there is no reason to be less careful with it.
-  writeFileSync(path, `${JSON.stringify(map)}\n`, { mode: 0o600 });
+/**
+ * This project's pending challenge parsed from its own file, with every field
+ * validated. Anything absent, torn, garbage, pre-#614, or naming another
+ * project reads as none — fail closed until the host's next transaction
+ * rewrites the file wholesale.
+ */
+function readPendingFor(key: string): PendingChallenge | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(pendingPath(key), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const pending = parsed as Partial<PendingChallenge>;
+  if (
+    pending.project !== key ||
+    typeof pending.id !== "string" ||
+    typeof pending.hash !== "string" ||
+    typeof pending.expiresAt !== "number"
+  ) {
+    return undefined;
+  }
+  return pending as PendingChallenge;
 }
 
 /** sha-256 hex of the challenge code — the persisted token, never the code. */
@@ -71,42 +156,150 @@ function challengeHash(code: string): string {
   return createHash("sha256").update(code).digest("hex");
 }
 
-/** Register a new active arming challenge, replacing any prior one for the project. */
-export function recordArmChallenge(project: string | undefined, code: string, expiresAt: number): void {
-  const map = readChallenges();
-  map[projectKey(project)] = { hash: challengeHash(code), expiresAt };
-  writeChallenges(map);
+/**
+ * Acknowledgement files outliving their transaction — a crash between the
+ * adapter's write and the host's settle — are inert by construction: no
+ * waiter ever polls their id again, and ids are UUIDs, so no future
+ * transaction can collide with one. They are therefore not swept by
+ * membership (a directory listing captured before another process records is
+ * stale the moment it is taken, and acting on it deletes on-time proofs),
+ * only by age: a file older than {@link ACK_ORPHAN_GC_AFTER_MS} cannot belong
+ * to a live handshake under any configured window, so its mtime alone decides
+ * removal.
+ */
+const ACK_ORPHAN_GC_AFTER_MS = 24 * 60 * 60 * 1000;
+
+function gcAgedAcks(now: number): void {
+  let names: string[] = [];
+  try {
+    names = readdirSync(acksDir());
+  } catch {
+    return; /* no acknowledgements yet */
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(acksDir(), name);
+    try {
+      if (statSync(path).mtimeMs >= now - ACK_ORPHAN_GC_AFTER_MS) continue;
+    } catch {
+      continue; /* raced away */
+    }
+    rmSync(path, { force: true });
+  }
 }
 
-/** Drop the active challenge for a project once arming completed or timed out. */
-export function clearArmChallenge(project: string | undefined): void {
-  const map = readChallenges();
+/**
+ * Register a new active arming challenge for the project — overwriting the
+ * project's own pending file — and return the transaction id. Before the
+ * overwrite, the project's PRIOR id is read back and exactly that id's
+ * acknowledgement is pruned: project-local cleanup with no directory
+ * snapshot, so another project's handshake cannot lose its proof here no
+ * matter how the calls interleave.
+ */
+export function recordArmChallenge(
+  project: string | undefined,
+  code: string,
+  sentAt: number,
+  expiresAt: number,
+): string {
   const key = projectKey(project);
-  if (!(key in map)) return;
-  delete map[key];
-  writeChallenges(map);
+  // Read the prior record BEFORE the overwrite shadows it.
+  const prior = readPendingFor(key);
+  const id = randomUUID();
+  const record: PendingChallenge = { project: key, id, hash: challengeHash(code), sentAt, expiresAt };
+  writeFileAtomic(pendingPath(key), `${JSON.stringify(record)}\n`);
+  if (prior !== undefined) rmSync(ackPath(prior.id), { force: true });
+  gcAgedAcks(sentAt);
+  return id;
 }
 
 /**
- * Authenticated classification for the orchestrator's turn adapter: a reply is
- * an active arming proof iff the project has a non-expired pending challenge
- * and one of the reply's whitespace-separated tokens hashes to it. The code is
- * matched by hash — matching `transcriptHasUserCode`'s leniency (the code
- * appears as a token) without ever trusting a `FLEET-` prefix or exposing the
- * code to the model's other reads. An unsolicited lookalike that matches no
- * active challenge, and a reply in the wrong project, both stay inert.
+ * The inbound adapter's acknowledgement (conductor #614): classify the reply
+ * against the project's non-expired pending challenge and, on a match,
+ * atomically write the challenge-id-specific acknowledgement record the host
+ * waits on. Returns whether the reply is an active arming proof, driving the
+ * existing deterministic UX path.
  *
- * Clears nothing: the host (`armTicks`) owns clearance once its transcript
- * proof lands, so the two sides cannot race for the record.
+ * Writes only this challenge's own file — it never reads or rewrites any other
+ * record — so a wrong token, wrong project, expired challenge, or a racing
+ * host settle all fail closed without touching anyone else's handshake, and
+ * two projects acknowledging concurrently cannot clobber each other.
  */
-export function isActiveArmProof(project: string | undefined, replyText: string, now: number): boolean {
-  const pending = readChallenges()[projectKey(project)];
-  if (pending === undefined || now >= pending.expiresAt) return false;
-  const targetHash = pending.hash;
+export function acknowledgeArmReply(project: string | undefined, replyText: string, now: number): boolean {
+  const pending = readPendingFor(projectKey(project));
+  if (pending === undefined) return false;
+  if (now >= pending.expiresAt) return false;
   // Challenge codes contain no whitespace, so tokenising on whitespace never
   // splits one; empty replies simply yield no token.
+  const targetHash = pending.hash;
+  let matched = false;
   for (const token of replyText.trim().split(/\s+/)) {
-    if (token.length > 0 && challengeHash(token) === targetHash) return true;
+    if (token.length > 0 && challengeHash(token) === targetHash) {
+      matched = true;
+      break;
+    }
   }
-  return false;
+  if (!matched) return false;
+  // Keyed by the challenge id, so replays overwrite the one record the single
+  // live waiter consumes; a stale id's file can never be created here.
+  const record: ArmAcknowledgement = { challengeId: pending.id, acknowledgedAt: now };
+  writeFileAtomic(ackPath(pending.id), `${JSON.stringify(record)}\n`);
+  return true;
+}
+
+/** The acknowledgement record for one exact challenge id, or undefined. */
+export function readArmAcknowledgement(challengeId: string): ArmAcknowledgement | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(ackPath(challengeId), "utf8"));
+  } catch {
+    return undefined; /* absent, torn or garbage — not an acknowledgement */
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const ack = parsed as { challengeId?: unknown; acknowledgedAt?: unknown };
+  if (ack.challengeId !== challengeId || typeof ack.acknowledgedAt !== "number") return undefined;
+  return { challengeId, acknowledgedAt: ack.acknowledgedAt };
+}
+
+/**
+ * Settle one arm transaction — consumption, timeout, or send failure: remove
+ * the project's pending file iff it still names this transaction, and drop
+ * its acknowledgement. Deletion is id-addressed only, so another project's
+ * records are untouchable by construction, and a same-project replacement
+ * (different id) survives the stale settle.
+ */
+export function clearArmTransaction(project: string | undefined, challengeId: string): void {
+  const key = projectKey(project);
+  const pending = readPendingFor(key);
+  if (pending !== undefined && pending.id === challengeId) rmSync(pendingPath(key), { force: true });
+  rmSync(ackPath(challengeId), { force: true });
+}
+
+export interface ArmChallengeSighting {
+  /** The pending transaction's id — random, not the challenge code. */
+  id: string;
+  /** Unix ms the challenge was recorded, when the record carries it. */
+  sentAt?: number;
+  /** Unix ms the challenge expires, when the record carries it. */
+  expiresAt?: number;
+  /** Present once the inbound adapter acknowledged this challenge id. */
+  acknowledgedAt?: number;
+}
+
+/**
+ * Doctor's view of the project's open transaction, or undefined when none is
+ * recorded. An expired-but-uncleared record is reported, not hidden: it is
+ * inert (a reply past expiry is refused) but lingers until the project's next
+ * arm replaces it.
+ */
+export function observeArmChallenge(project: string | undefined): ArmChallengeSighting | undefined {
+  const pending = readPendingFor(projectKey(project));
+  if (pending === undefined || typeof pending.id !== "string") return undefined;
+  const ack = readArmAcknowledgement(pending.id);
+  return {
+    id: pending.id,
+    ...(typeof pending.sentAt === "number" ? { sentAt: pending.sentAt } : {}),
+    ...(typeof pending.expiresAt === "number" ? { expiresAt: pending.expiresAt } : {}),
+    ...(ack === undefined ? {} : { acknowledgedAt: ack.acknowledgedAt }),
+  };
 }

package/src/briefs/orchestrator.md

@@ -254,18 +254,31 @@ Keep the queue worth draining.
   source/ref/freshness is refused as blocked, never groomed. The quality bar
   above does not move.
 - **Every to-spec agent answers the same return contract**, or its output is
-  refused: the strict schema carries
-  - verdict — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
+  refused: the strict schema carries exactly these fields — the generated task
+  schema and the persistence parser are that one contract, so an extra or
+  missing field is refused as malformed:
+  - `verdict` — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
     `NEEDS PRODUCT DECISION`
-  - routing — exactly one repo, or `MULTI` with the split
-  - evidence — the file or symbol proving `ALREADY DONE`, never a title match
-  - entry points — the 3-6 files to change or read first
-  - existing tests covering the behaviour, by path
-  - the one thing most likely to be silently faked
-  - source — where the code was read: the clone/ref and how fresh it is. A
+  - `routing` — exactly one `owner/repo`, or `MULTI`
+  - `routingSplit` — required iff `routing` is `MULTI`: what each slice goes to
+  - `source` — where the code was read: the clone/ref and how fresh it is. A
     scout that cannot reach a source it trusts returns `BLOCKED` and says so;
     silent fallback to an unnamed source is the failure mode of delegated
     research — stale evidence reads exactly like good evidence.
+  - `evidence` — the files/symbols proving the verdict; required for
+    `ALREADY DONE` (the file or symbol that already does the work, never a
+    title match)
+  - `laterWorkInvalidates` — whether later work retired the premise
+  - `laterWorkNote` — what that check searched and found
+  - `entryPoints` — the 3-6 files to change or read first
+  - `existingTests` — existing tests covering the behaviour, by path
+  - `likelySilentFake` — the one thing most likely to be silently faked
+  - `proofCommands` — the focused commands that prove the work
+  - `fileLane` — the files and directories this slice writes
+  - `dependencies` — open prerequisite issue numbers, bare (`875`) or string
+    (`"875"`); `[]` when none
+  - `proposedBrief` — required iff `verdict` is `PROMOTABLE`
+  - `reasonNotToPromote` — required for every other verdict
 - **Disqualifying an issue is a successful grooming outcome.** Measured on this
   package's own fleet: four scouts over sixteen backlog issues promoted four and
   *disqualified six* that looked promotable from their titles — four written

package/src/briefs/to-spec.md

@@ -44,6 +44,9 @@ required field and no extra keys. The fields are:
   the exact ref, and `freshAt` = epoch milliseconds when you actually observed
   it. Conductor refuses results whose source is older than 24 hours or missing
   name/ref/freshAt — an unsourced verdict is not grooming, it is prose.
+- `evidence` — the files/symbols that prove the verdict. Required for
+  `ALREADY DONE`: name the symbol/file that already does the work, never a
+  title match. Welcome on every other verdict.
 - `laterWorkInvalidates` — boolean: did later work (an epic or issue committed
   after this candidate was filed) retire its premise?
 - `laterWorkNote` — what you searched for that check and what you found. Even
@@ -57,8 +60,9 @@ required field and no extra keys. The fields are:
   implementing, and how to prove it is not.
 - `proofCommands` — the focused commands that prove the work, each with its
   `cwd` when it matters.
-- `fileLane` — the files and directories this slice writes; `dependencies` —
-  open prerequisites, `[]` when none.
+- `fileLane` — the files and directories this slice writes.
+- `dependencies` — open prerequisite issue numbers, each a bare number
+  (`875`) or a string (`"875"`); `[]` when none.
 - `proposedBrief` — required iff `verdict` is `PROMOTABLE`: the brief a worker
   would be dispatched with, including the silent fake and the proof commands.
 - `reasonNotToPromote` — required for every other verdict: why this must not