omp-conductor 0.18.0 → 0.18.2

package/src/ask.ts

@@ -74,6 +74,25 @@ export type QuestionShape =
  */
 export const AUTO_APPLIED_SUFFIX = "(auto-applied on ask timeout)";
 
+/**
+ * The fixed sentence a decision row carries when the question could not be
+ * posted through a selectable surface and went out as plain text instead
+ * (#722). The row is the record a later reader judges "did the operator answer
+ * this?" from, so it must say plainly that a prose reply is not a selection:
+ * nothing in this pipeline ever maps free text back to an option, and the
+ * marker is what stops a reader from treating a chat reply as the row's
+ * answer. It rides the row's `blocks` free-text slot — the one place a row
+ * carry durable per-row prose that renders in every digest — without
+ * rewriting the archived question (which must stay verbatim, #741).
+ */
+export const DEGRADED_DELIVERY_MARKER =
+  "question delivered as plain text (no selectable surface); a reply does not resolve it — resolve or withdraw the row by hand";
+
+/** The `blocks` text for a degraded ask: the block list plus the marker. */
+export function degradedAskBlocks(blocks: string | undefined): string | undefined {
+  return blocks === undefined ? DEGRADED_DELIVERY_MARKER : `${blocks}; ${DEGRADED_DELIVERY_MARKER}`;
+}
+
 /** How often the bounded wait re-reads the decision row while waiting. */
 export const ASK_POLL_MS = 1_000;
 
@@ -337,6 +356,20 @@ export function askParameterSchema(): Record<string, unknown> {
     },
     required: ["question", "on-timeout"],
     additionalProperties: false,
+    // The one conditional requirement the tool has (#722): an ask that
+    // declares auto-proceed must name the option it would auto-apply, because
+    // the decision row must record what was applied and who applied it. Stated
+    // in the schema (not only at call time) so the model sees it next to the
+    // "on-timeout" property it conditions on.
+    allOf: [
+      {
+        if: {
+          properties: { "on-timeout": { const: "auto-proceed" } },
+          required: ["on-timeout"],
+        },
+        then: { required: ["recommended"] },
+      },
+    ],
   };
 }
 
@@ -378,6 +411,175 @@ export function askMessageFor(request: AskRequest): string {
   return lines.join("\n");
 }
 
+/**
+ * The interactive surface a bounded ask posts through when one is available
+ * (#722): the same Bot API `reply_markup` `telegram_ask` posts, whose taps are
+ * routed by the running omp-telegram bridge. The bridge acknowledges the tap
+ * and writes an answer envelope into the shared prompts directory; this handle
+ * exists only to post the question, translate inbound envelopes into a decision
+ * row resolution, and clean up. It is optional by design — a caller without
+ * one degrades exactly as before, to the durable plain-text path with the
+ * degraded marker on the row.
+ */
+export interface AskInteractiveDelivery {
+  /**
+   * Why no interactive surface is available for this ask, or undefined when it
+   * can post. Pure: no files, no network, no side effects — the caller decides
+   * the row note before it creates the row.
+   */
+  unavailableReason(request: AskRequest): string | undefined;
+  /**
+   * Post the selectable question to the operator. Never throws: every failure
+   * comes back as `{ ok: false, reason }` so the caller can fall back to the
+   * durable text path. `decisionId` is the row id and the protocol nonce, so
+   * the pending request and its answer are addressable by the row.
+   */
+  post(request: AskRequest, decisionId: string): Promise<{ ok: true } | { ok: false; reason: string }>;
+  /**
+   * Translate an inbound answer (a button tap, or a reply to a free-text ask)
+   * into the decision row. Called on every poll while the ask waits; no-op
+   * until an answer exists, idempotent afterwards (the row's double-resolve
+   * guard makes the second write a no-op anyway).
+   */
+  collect(decisionId: string): void;
+  /**
+   * Best-effort cleanup once the wait ends, any outcome: remove the prompt
+   * request and its answer from the shared dir, and strip the keyboard off the
+   * posted message so a stale tap reads as expired rather than live.
+   */
+  close(decisionId: string): void;
+}
+
+/** One inline-keyboard button, as the Bot API renders it. */
+export interface AskKeyboardButton {
+  text: string;
+  callback_data: string;
+}
+
+/** The `reply_markup` of one interactive ask, one option per row plus Cancel. */
+export type AskKeyboardMarkup = { inline_keyboard: AskKeyboardButton[][] };
+
+/** The rendered interactive ask: the message text and its keyboard. */
+export interface AskInteractiveRender {
+  text: string;
+  markup: AskKeyboardMarkup;
+}
+
+/** Shorten a button label to Telegram's inline-button limit, like omp-telegram. */
+function clipButton(text: string, max: number): string {
+  const clean = text.replace(/[\r\n]+/g, " ").trim();
+  return clean.length <= max ? clean : `${clean.slice(0, max - 1)}…`;
+}
+
+/**
+ * The interactive render of one bounded ask: the question as a normal ask
+ * message (numbered options with their consequences when descriptions exist,
+ * the same shape `telegram_ask` posts), and a keyboard whose callbacks speak
+ * the shared `qa:<nonce>:<action>[:<index>]` protocol (`prompts.ts` in
+ * omp-telegram), so the bridge answers the ask with the *label* of the tapped
+ * option — never an index and never the model's numbering. Cancel closes the
+ * ask as withdrawn, exactly like a `decision withdraw`.
+ */
+export function renderInteractiveAsk(request: AskRequest, nonce: string): AskInteractiveRender {
+  const options = request.options ?? [];
+  const lines = [request.question.trim()];
+  if (options.length === 0) {
+    lines.push("", "Reply with your answer as the next message, or /cancel.");
+  } else if (options.some((option) => option.description !== undefined)) {
+    lines.push("");
+    options.forEach((option, index) => {
+      const recommended = option.label === request.recommended ? " (recommended)" : "";
+      const description = option.description === undefined ? "" : ` — ${option.description}`;
+      lines.push(`${index + 1}. ${option.label}${recommended}${description}`);
+    });
+  }
+  const rows = options.map((option, index) => [
+    { text: clipButton(option.label, 60), callback_data: `qa:${nonce}:s:${index}` },
+  ]);
+  rows.push([{ text: "Cancel", callback_data: `qa:${nonce}:x` }]);
+  return { text: lines.join("\n"), markup: { inline_keyboard: rows } };
+}
+
+/** One answer within an answered envelope — the bridge's prompt answer shape. */
+export interface AskAnswer {
+  id: string;
+  question: string;
+  /** The chosen option labels — the tap resolves the row with these, verbatim. */
+  selectedOptions: string[];
+  /** The reply to a free-text ask, when the question had no options. */
+  customInput?: string;
+}
+
+/** One answer envelope from the shared prompts dir (`<nonce>.answer.json`). */
+export interface AskAnswerEnvelope {
+  outcome:
+    | { status: "answered"; answers: AskAnswer[] }
+    | { status: "cancelled" | "expired" | "aborted" };
+}
+
+/**
+ * Parse one prompt answer envelope. Malformed or unreadable input is
+ * undefined — "no answer yet" is never a crash.
+ */
+export function parseAskAnswerEnvelope(raw: unknown): AskAnswerEnvelope | undefined {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const outcome = (raw as Record<string, unknown>)["outcome"];
+  if (outcome === null || typeof outcome !== "object" || Array.isArray(outcome)) return undefined;
+  const record = outcome as Record<string, unknown>;
+  const status = record["status"];
+  if (status === "answered") {
+    const answers = record["answers"];
+    if (!Array.isArray(answers)) return undefined;
+    const parsed: AskAnswer[] = [];
+    for (const answer of answers) {
+      if (answer === null || typeof answer !== "object" || Array.isArray(answer)) return undefined;
+      const a = answer as Record<string, unknown>;
+      if (typeof a["id"] !== "string" || typeof a["question"] !== "string") return undefined;
+      const selected = a["selectedOptions"];
+      if (!Array.isArray(selected) || selected.some((label) => typeof label !== "string")) {
+        return undefined;
+      }
+      const customInput = a["customInput"];
+      if (customInput !== undefined && typeof customInput !== "string") return undefined;
+      parsed.push({
+        id: a["id"],
+        question: a["question"],
+        selectedOptions: selected as string[],
+        ...(customInput === undefined ? {} : { customInput }),
+      });
+    }
+    return { outcome: { status: "answered", answers: parsed } };
+  }
+  if (status === "cancelled" || status === "expired" || status === "aborted") {
+    return { outcome: { status } as AskAnswerEnvelope["outcome"] };
+  }
+  return undefined;
+}
+
+/**
+ * The decision-row write one envelope calls for, or none. An answer becomes a
+ * row resolution carrying the option *label* (or the free-text reply to a
+ * free-text ask) — the identity the operator actually chose; cancel becomes a
+ * withdrawal, so a deliberate close is never an answer; expiry/abort mean
+ * "nobody answered yet" and leave the row open for the bounded wait to decide.
+ */
+export function askAnswerRowWrite(
+  envelope: AskAnswerEnvelope,
+): { state: "answered" | "withdrawn"; resolution: string } | undefined {
+  if (envelope.outcome.status === "cancelled") {
+    return { state: "withdrawn", resolution: "Question cancelled by the operator" };
+  }
+  if (envelope.outcome.status !== "answered") return undefined;
+  const first = envelope.outcome.answers[0];
+  if (first === undefined) return undefined;
+  const resolution =
+    first.customInput !== undefined && first.customInput.trim() !== ""
+      ? first.customInput.trim()
+      : first.selectedOptions.join(", ");
+  if (resolution.trim() === "") return undefined;
+  return { state: "answered", resolution };
+}
+
 /** One read of the decision row; `undefined` means the id is unknown. */
 export type DecisionReader = (id: string) => DecisionRecord | undefined;
 
@@ -388,6 +590,14 @@ export interface BoundedAskDeps {
   /** Advance one poll; injected so tests stay deterministic. */
   wait: (ms: number) => Promise<void>;
   now: () => number;
+  /**
+   * Called once per poll, before the row read: the seam through which an
+   * interactive delivery surface (a Telegram button tap, #722) translates an
+   * inbound answer into a decision-row write the read then sees. Optional and
+   * synchronous on purpose — the wait must never depend on anything slower
+   * than the row itself.
+   */
+  settle?: () => void;
 }
 
 export type BoundedAskOutcome =
@@ -404,6 +614,7 @@ export type BoundedAskOutcome =
 export async function runBoundedAsk(deps: BoundedAskDeps): Promise<BoundedAskOutcome> {
   const deadline = deps.now() + deps.ceilingMs;
   for (;;) {
+    deps.settle?.();
     const row = deps.read(deps.decisionId);
     if (row !== undefined && row.state !== "open") {
       return row.state === "answered"
@@ -438,6 +649,13 @@ export interface AskDeps {
   turnBudgetSeconds?: number;
   /** Delivers the question through the sanctioned durable path. */
   deliver(questionText: string, category: InterruptCategory): Promise<AskDeliveryResult>;
+  /**
+   * The selectable delivery surface (#722): the same Bot API buttons
+   * `telegram_ask` uses, whose taps resolve the decision row with the chosen
+   * option label. Absent or unavailable → the ask degrades to the durable
+   * text path, and the row records the degraded delivery.
+   */
+  interactive?: AskInteractiveDelivery;
   wait?: (ms: number) => Promise<void>;
   now?: () => number;
 }
@@ -459,14 +677,43 @@ export async function performAsk(request: AskRequest, deps: AskDeps): Promise<As
   const now = deps.now ?? Date.now;
   const wait = deps.wait ?? sleep;
 
+  // The delivery mode is decided before the row exists: the degraded marker
+  // must ride the row's `blocks` from birth, and the row must exist before any
+  // delivery attempt (a crash at any point leaves a recorded question). The
+  // interactive preview is pure — no files, no network — so it can run here
+  // without violating that ordering.
+  const degradedReason =
+    deps.interactive === undefined
+      ? "no interactive delivery surface is mounted for this session"
+      : deps.interactive.unavailableReason(request);
+  const degraded = degradedReason !== undefined;
+
   const row = deps.store.createDecision({
     project: deps.project,
     question: request.question,
-    ...(request.blocks === undefined ? {} : { blocks: request.blocks }),
+    ...(request.blocks === undefined && !degraded
+      ? {}
+      : { blocks: degraded ? degradedAskBlocks(request.blocks) : request.blocks }),
     at: now(),
   });
 
-  const delivery = await deps.deliver(askMessageFor(request), request.category ?? "decision-needed");
+  // Interactive first: posting selectable options is the whole fix (#722).
+  // A preview that passed but a post that failed falls back to the durable
+  // text path below, and the result names the failure — the row keeps its
+  // clean blocks in that rare race, because the note is decided at birth and
+  // the row has no update surface by design.
+  let interactivePosted = false;
+  let postFailure: string | undefined;
+  if (!degraded) {
+    const posted = await deps.interactive!.post(request, row.id);
+    interactivePosted = posted.ok;
+    if (!posted.ok) postFailure = posted.reason;
+  }
+
+  let delivery: AskDeliveryResult | undefined;
+  if (!interactivePosted) {
+    delivery = await deps.deliver(askMessageFor(request), request.category ?? "decision-needed");
+  }
 
   const ceilingSeconds = resolveAskCeilingSeconds(
     request.timeoutSeconds,
@@ -479,7 +726,9 @@ export async function performAsk(request: AskRequest, deps: AskDeps): Promise<As
     read: (id) => deps.store.decision(id),
     wait,
     now,
+    settle: interactivePosted ? () => deps.interactive!.collect(row.id) : undefined,
   });
+  if (interactivePosted) deps.interactive!.close(row.id);
 
   let text: string;
   if (outcome.kind === "answered") {
@@ -507,11 +756,23 @@ export async function performAsk(request: AskRequest, deps: AskDeps): Promise<As
       `state (e.g. unlabel it or move it to a parked state), then note it in your report.`;
   }
 
-  const delivered =
-    delivery.kind === "sent"
-      ? `The question went to the operator as a ${delivery.category} message.`
-      : `The question is durably held (notice ${delivery.noticeId ?? "?"}, ${delivery.category}); the ` +
-        "daemon releases it with the next digest or working-hours catch-up.";
+  const deliveryLine =
+    delivery === undefined
+      ? ""
+      : delivery.kind === "sent"
+        ? ` The question went to the operator as a ${delivery.category} message.`
+        : ` The question is durably held (notice ${delivery.noticeId ?? "?"}, ${delivery.category}); the ` +
+          "daemon releases it with the next digest or working-hours catch-up.";
+  const delivered = interactivePosted
+    ? "The question went to the operator as selectable options (button taps); a tap resolves " +
+      "the decision row with the chosen option, and a free-text ask is answered by replying."
+    : degraded
+      ? `The interactive surface is unavailable for this call (${degradedReason}), so the decision row ` +
+        `records the degraded delivery: the operator's prose reply is NOT an answer to this row and ` +
+        `does not resolve it — if they answer in prose, resolve or withdraw the row by hand ` +
+        `(omp-conductor decision resolve|withdraw ${row.id}).${deliveryLine}`
+      : `The interactive question could not be posted (${postFailure}) and the ask fell back to the ` +
+        `durable text path.${deliveryLine}`;
 
   return { outcome, decisionId: row.id, text: `${delivered}\n${text}` };
 }

package/src/board.ts

@@ -11,7 +11,7 @@ import {
   workerPhasesFromHealthz,
 } from "./fleet.ts";
 import type { FleetLayers, TelegramHealth } from "./status-render.ts";
-import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
+import { probeCodeGraph, DEFAULT_DEPS, type CodeGraphHealth } from "./graph-health.ts";
 import { healthCheck, livingDaemon } from "./lifecycle.ts";
 import type { WorkerPausePhase } from "./worker.ts";
 import { dbPath, openStore } from "./store.ts";
@@ -109,7 +109,7 @@ function isLastRun(run: RunRecord, labels: BoardLabels): boolean {
   return false;
 }
 
-type DaemonBoardState = "stopped" | "ok" | "unreachable" | "other-project";
+type DaemonBoardState = "stopped" | "ok" | "unreachable" | "unresponsive" | "other-project";
 
 /**
  * A card the board can only describe from tracker state, because the store has
@@ -940,12 +940,26 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealthProb
   const classified = classifyDaemonProjectHealth(record, health, project.name);
   const daemon: DaemonBoardState = classified.kind;
   const cachedGraph = daemon === "ok" ? codeGraphFromHealthz(health?.body, project.name) : undefined;
+  const store = openStore(dbPath());
+  let codeGraph: CodeGraphHealth;
+  try {
+    codeGraph =
+      cachedGraph ??
+      (await probeCodeGraph(project, {
+        ...DEFAULT_DEPS,
+        // The runtime half of the code-graph finding (#726): grounded in
+        // dispatched runs' own observations, never in the daemon's process.
+        graphToolsObservations: () => store.graphToolsObservationCounts(project.name),
+      }));
+  } finally {
+    store.close();
+  }
   return {
     health: {
       layers,
       telegram,
       daemon,
-      codeGraph: cachedGraph ?? (await probeCodeGraph(project)),
+      codeGraph,
     },
     pausedPhases:
       daemon === "ok"

package/src/briefs/orchestrator.md

@@ -212,10 +212,12 @@ Keep the queue worth draining.
   spent proving what the second one already proved.
 - **A decomposition has a required output.** When an issue is too big for one
   budget, do not re-file it smaller and hope. Produce an epic plus children, and
-  give every child, in its body: the files it writes, its acceptance criteria,
-  the one thing most likely to be silently faked, and the commands that prove
-  it. A child missing any of those is not a slice, it is the same issue with a
-  smaller title.
+  give every child, in its body: the files it writes — under an
+  `## Exact write lane` heading, one backticked path per bullet
+  (`- \`omp/src/a.ts\` — why it changes`), the spelling admission parses
+  (#825) — its acceptance criteria, the one thing most likely to be silently
+  faked, and the commands that prove it. A child missing any of those is not a
+  slice, it is the same issue with a smaller title.
 - **Record the decomposition on the parent, not in a chat turn.** The parent
   carries the child list, the order they must land in, and one sentence per
   child saying why it is a separate slice — a shared file lane, a dependency,
@@ -233,24 +235,50 @@ Keep the queue worth draining.
   has to produce roughly three well-specced issues in the time one worker takes
   to finish one. Auditing candidates serially cannot keep up, and the board then
   reads "0 ready / workers idle" while you are doing exactly what this duty asks.
-  When the queue is below the grooming trigger, fan out read-only `scout`
-  subagents over backlog clusters **in one batch** rather than auditing one issue
-  at a time. Scouts do the finding; you still do the deciding and you still write
-  the brief. Name the authoritative source in every scout brief and forbid
-  unnamed fallbacks. The quality bar above does not move.
-- **Give every scout the same return contract**, or it comes back with prose
-  nobody can act on:
-  - verdict — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
+  When the queue is below the grooming trigger, the tick's **bounded to-spec
+  batch** block (#777) carries the mechanical contract: it names the launch
+  token, the candidates the conductor selected mechanically from the live
+  open-issue snapshot (parked, parent/epic, already-groomed, in-flight,
+  lane/dependency-blocked and dispatched issues were excluded by code, never
+  by your judgement), the exclusions that selection applied, and the item
+  shape. Do exactly what it says — those candidates are the only batch this
+  tick authorizes: render `omp/src/briefs/to-spec.md` for each of them with
+  the current source head, launch exactly one `task` batch through the
+  `to-spec` agent with the listed items and no substitutes, and persist every
+  returned result with the `conductor_to_spec_result` tool. The `tool_call`
+  gate stamps the strict schema, records in-flight rows and refuses any item
+  that is not on the list; the strict parser and the grooming table decide
+  what persists. Agents research and specify; you still decide and you still
+  write the brief. Name the authoritative source (the repo and the exact
+  ref) in every item and forbid unnamed fallbacks — a verdict without a
+  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 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
@@ -440,6 +468,13 @@ neither target — then return to the duty you were in the
 middle of and finish it. Never abandon or restart the tick because a message
 arrived, and never batch the answer "for the report" — the person is waiting now.
 
+The answer itself can make previously blocked work actionable immediately: if
+it resolves a parked decision row, finish the newly reachable approved work in
+this same turn — resolve the row, apply what it approved — then return to the
+standing duty and finish it. Never defer that work to a later tick: executing
+an approved answer is not proposing a new amendment, and the
+at-most-one-proposal-per-autonomous-tick throttle does not apply to it.
+
 ## Escalation tiers
 
 | Tier | Meaning | Handled by |
@@ -738,6 +773,12 @@ your next report as `pending amendment: <one-liner> — say 'apply it' or 'drop
 it'`, and never re-open the yes/no dialog.
 
 Two limits. You never propose relaxing **Hard boundaries** — that section changes
-only in the shipped package floor, never via this loop. And at most one proposal
-per tick: an amendment waits for the three duties to finish, it never interrupts
-them.
+only in the shipped package floor, never via this loop. And at most one new
+orchestrator-originated amendment proposal per autonomous tick: a fresh proposal
+waits for the three duties to finish, it never interrupts them.
+
+The proposal cap throttles originating proposals, never executing approved work.
+Resolving and applying multiple already-approved decision rows, and
+operator-directed work in an interactive terminal session, are not proposal
+creation and are not serialized by it. An amendment still never auto-applies:
+"already approved" means a recorded yes — never anything less.

package/src/briefs/to-spec.md

@@ -0,0 +1,88 @@
+# to-spec — groom one backlog candidate into a verified, to-spec result
+
+You are grooming exactly ONE backlog candidate for a conductor fleet: you read
+candidate and source, and you return one strict JSON verdict. You never change
+anything. You have reading tools only — no shell, no editor, no GitHub verbs,
+no task spawning, no label changes. The whole of your work is the structured
+result below, and the fleet treats anything else as a failed grooming pass.
+
+## The candidate
+
+- **Tracker:** {{TRACKER_REPO}} issue **#{{ISSUE_NUMBER}}** — {{CANDIDATE_TITLE}}
+- **Issue body:** {{ISSUE_BODY}}
+- **Authoritative source:** {{SOURCE}} at ref `{{SOURCE_REF}}`. Read the issue's
+  premise against the code *in that source, at that ref* — never from memory,
+  never from another checkout, never from the issue alone.
+
+## The verdict
+
+Exactly one of these five strings, nothing else:
+
+- `ALREADY DONE` — the work already exists in the source (a later epic retired
+  the issue's premise counts as done; prove it with the symbol/file, never the
+  title).
+- `PROMOTABLE` — well-specified, fits one worker budget, and the acceptance
+  criteria are checkable; carries the proposed brief.
+- `NEEDS DECOMPOSITION` — the plan is real but too big for one budget; say what
+  slices it splits into and why each is a separate slice.
+- `BLOCKED` — a named open prerequisite, lane, or credential gap stands in the
+  way. If you could not reach a source you trust, this is the verdict, with the
+  reason naming what failed — never an invented fallback source.
+- `NEEDS PRODUCT DECISION` — the issue cannot proceed until a human decides
+  product shape, slice order, or scope; state the one question that unblocks it.
+
+## The return contract
+
+Answer in **one fenced JSON block, nothing else after it**, matching the
+JSON Schema this invocation validates against exactly — strict means every
+required field and no extra keys. The fields are:
+
+- `verdict` — one of the five strings above.
+- `routing` — exactly one `owner/repo`, or `"MULTI"`.
+- `routingSplit` — required iff `routing` is `"MULTI"`: what each slice goes to.
+- `source` — `{ name, ref, freshAt }`: the authoritative source you read,
+  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
+  when false this must name the search, so "false" cannot be written without
+  looking.
+- `entryPoints` — 3–6 files to change or read first, the discovery a worker's
+  budget dies on when absent.
+- `existingTests` — tests that already exercise the behaviour, by path; `[]`
+  when you found none.
+- `likelySilentFake` — the one thing most likely to be silently faked while
+  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 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
+  be promoted.
+
+## Three traps, each of which produces a confidently wrong verdict
+
+- **Prose is not evidence.** A verdict without the source-backed contract is
+  refused as malformed: every field above is required, and `source` must name
+  the ref you read and when.
+- **Stale source reads like good source.** Judge the candidate against the
+  stated ref as it is now; a verdict drawn from memory of a different clone is
+  stale and will be refused.
+- **A later epic retires the premise.** On anything old, check whether later
+  open work invalidated the candidate before concluding anything else. That
+  check is mechanical, read-only, and exactly what you are cheap at —
+  `laterWorkNote` must name what you searched.
+
+## Answer
+
+One fenced JSON block, nothing else after it. Anything unparseable or
+off-schema is persisted as `blocked(malformed)` and the candidate counts as
+not groomed — a refusal is a failed grooming, not a free pass to skip it.

package/src/briefs/worker.md

@@ -47,7 +47,7 @@ files are canonical; your priors are not.
 
 {{ACCEPTANCE_CRITERIA}}
 
-{{ISSUE_COMMENTS}}{{FILE_LANE}}## How to work
+{{ISSUE_COMMENTS}}{{FILE_LANE}}{{MODEL}}## How to work
 
 1. **Understand before editing — and ask the graph before you grep.** Your turns
    are mostly spent finding code, not writing it, and running out of turns
@@ -111,6 +111,7 @@ These are the exact gates for `{{REPO}}`:
 {{GATES}}
 
 {{SHARED_HOST_NOTICE}}
+{{HOST_CONSTRAINTS}}
 
 Run every one of them, from the directory listed, over the **whole tree** — not
 just the directory you edited. Linting only the source dir is how an error in a