omp-conductor 0.19.7 → 0.20.1

package/src/to-spec.ts

@@ -12,8 +12,9 @@
  * The five contract verdicts map onto it — PROMOTABLE → `promotable`;
  * ALREADY DONE and NEEDS DECOMPOSITION → `considered`; BLOCKED and NEEDS
  * PRODUCT DECISION → `blocked` — and a result that cannot be trusted
- * (malformed JSON, a schema violation, no authoritative source, or a stale
- * source) persists as `blocked` and never as `promotable`/`considered`.
+ * (no answer at all, malformed JSON, a schema violation, no authoritative
+ * source, or a stale source) persists as `blocked` and never as
+ * `promotable`/`considered`.
  * Reprocessing the same candidate is deterministic: the same input at the
  * same observation time produces the same row, and malformed output never
  * erases a prior valid (promotable/considered) result. Stale or source-less
@@ -34,6 +35,28 @@
  * returned before persisting, because the harness is permissive by design
  * and the store vets only what this module hands it.
  *
+ * Who stamps the observation time (#1000): the dispatcher, never the agent.
+ * A to-spec groomer runs with reading tools only and therefore has no clock,
+ * so the `source.freshAt` it used to be asked for was always a guess — and a
+ * guess landing ahead of the daemon's clock discarded the whole verdict as a
+ * clock lie, twice in one afternoon on verdicts that were otherwise correct.
+ * The schema still accepts the key (it is `.strict()`, so refusing an older
+ * prompt's output would recreate exactly that discard) but ignores its value:
+ * `parseToSpecResult` stamps the batch's launch time — or the settle time
+ * when no launch time is known — and that stamp is what persists.
+ *
+ * Sizing is evidence, not a feeling (#1041): a `PROMOTABLE` verdict carries
+ * `sizingEvidence`, and a `NEEDS DECOMPOSITION` verdict carries an ordered
+ * `decomposition`. #1035 was persisted `PROMOTABLE` with nine acceptance
+ * criteria across four lifecycle files totalling 28,812 lines; attempt 1
+ * exhausted 181 of its 180 turns. The verdict had asserted one-budget fit —
+ * what was missing was anything that could falsify the assertion. So the
+ * contract now asks for the falsifier itself (distinct behaviours, the
+ * production modules and test surfaces each needs, shared-file sequencing)
+ * and there is deliberately no numeric threshold anywhere: a line or
+ * criterion count that decided verdicts would be gamed by splitting prose,
+ * and the judgement is the groomer's.
+ *
  * One contract, every surface (#883): this Zod schema is the single source of
  * truth. `TO_SPEC_SCHEMA` generated from it stamps the native task launch,
  * `parseToSpecResult` persists against it, and the drift test pins the
@@ -65,6 +88,11 @@ export type ToSpecVerdict = (typeof TO_SPEC_VERDICTS)[number];
  * never read as promotable/considered. 24 hours: a groomed candidate must
  * have looked at the code within a day, and a re-grooming pass a day later
  * re-reads the live source anyway.
+ *
+ * Since #1000 the observation time is the dispatcher's own stamp, so this
+ * ceiling can only fire for a batch that genuinely ran longer than a day —
+ * a real signal about the batch rather than a verdict on the agent's
+ * arithmetic.
  */
 export const TO_SPEC_MAX_SOURCE_AGE_MS = 24 * 60 * 60 * 1000;
 
@@ -78,10 +106,47 @@ const ToSpecSourceSchema = z
     freshAt: z
       .number()
       .int()
-      .describe("Epoch milliseconds when the source was observed — required so staleness is judgeable without trusting prose."),
+      .optional()
+      .describe(
+        "Ignored — do not send it. Conductor stamps the observation time itself from the batch window (#1000); a groomer has reading tools only and no clock, so any value here is a guess. The key is still accepted so an older prompt's output is never refused for sending one.",
+      ),
   })
   .strict()
-  .describe("The authoritative source/ref/freshness every verdict must stand on.");
+  .describe("The authoritative source and ref every verdict must stand on; conductor stamps its freshness (#1000).");
+
+/**
+ * One ordered child of a decomposition proposal (#1041). A `NEEDS
+ * DECOMPOSITION` verdict used to be free to say "split this up" in prose,
+ * which is a verdict nobody can act on: the operator still has to do the
+ * decomposition. Each child therefore carries exactly what filing it as an
+ * issue needs — a title, the exact write lane it owns, what it waits on, the
+ * silent fake it invites, and the commands that prove it — so the proposal is
+ * a filing instruction rather than an opinion.
+ */
+const ToSpecDecompositionChildSchema = z
+  .object({
+    title: z.string().trim().min(1).describe("The child issue's title — one slice, stated as the behaviour it lands."),
+    writeLane: z
+      .array(z.string().trim().min(1))
+      .min(1)
+      .describe("The files/dirs this child alone writes — its `## Exact write lane`."),
+    dependsOn: z
+      .array(z.union([z.string().trim().min(1), z.number().int().min(1)]))
+      .describe(
+        "What this child waits on: an earlier child's title, or an existing issue number. Children sharing a file in their write lanes must be serialised here — two concurrent slices writing one core module is the collision the file lane exists to prevent. `[]` for the first child.",
+      ),
+    likelySilentFake: z
+      .string()
+      .trim()
+      .min(1)
+      .describe("The one thing most likely to be silently faked in this child, and how to prove it is not."),
+    proofCommands: z
+      .array(z.string().trim().min(1))
+      .min(1)
+      .describe("The focused commands that prove this child, each with its cwd when it matters."),
+  })
+  .strict()
+  .describe("One ordered child slice a decomposition proposal names (#1041).");
 
 /**
  * The one strict contract a grooming result must satisfy before it may
@@ -143,6 +208,21 @@ const ToSpecResultSchema = z
       .describe(
         'Open prerequisites this work is blocked on, as bare issue numbers (875) or strings ("875"); empty when none.',
       ),
+    sizingEvidence: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe(
+        "Required for PROMOTABLE: the source-backed one-budget analysis — the distinct behaviours/state transitions this slice introduces, the production modules and focused test surfaces each of them needs, the shared-file sequencing between them, and why that fits one configured worker attempt. A small file count is not this evidence when the files are high-fanout lifecycle modules with large integration suites (#1041).",
+      ),
+    decomposition: z
+      .array(ToSpecDecompositionChildSchema)
+      .min(2)
+      .optional()
+      .describe(
+        "Required for NEEDS DECOMPOSITION and accepted on no other verdict: the ordered children this candidate splits into, first to last, each naming its title, write lane, dependencies, silent fake and proof commands. Children sharing a write-lane path must serialise through `dependsOn` (#1041).",
+      ),
     proposedBrief: z
       .string()
       .trim()
@@ -166,6 +246,15 @@ const ToSpecResultSchema = z
       if (value.reasonNotToPromote !== undefined) {
         ctx.addIssue({ code: "custom", message: "PROMOTABLE must not carry reasonNotToPromote" });
       }
+      // #1041: the one-budget claim is only a claim until something could
+      // falsify it. #1035 asserted it and burned 181 of 180 turns.
+      if (value.sizingEvidence === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "PROMOTABLE requires sizingEvidence: the distinct behaviours, their production modules and test surfaces, the shared-file sequencing, and why that fits one worker attempt",
+        });
+      }
     } else {
       if (value.reasonNotToPromote === undefined) {
         ctx.addIssue({ code: "custom", message: `${verdict} requires reasonNotToPromote` });
@@ -180,6 +269,40 @@ const ToSpecResultSchema = z
         message: "ALREADY DONE requires evidence naming the file/symbol that already does the work",
       });
     }
+    // A decomposition proposal is a filing instruction or it is nothing
+    // (#1041): NEEDS DECOMPOSITION owes ordered children, and every other
+    // verdict owes none — children beside PROMOTABLE would mean the verdict
+    // contradicts itself.
+    if (verdict === "NEEDS DECOMPOSITION") {
+      if (value.decomposition === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "NEEDS DECOMPOSITION requires decomposition: the ordered children, each with its title, write lane, dependsOn, likelySilentFake and proofCommands",
+        });
+      }
+    } else if (value.decomposition !== undefined) {
+      ctx.addIssue({ code: "custom", message: `decomposition is only valid with verdict "NEEDS DECOMPOSITION", not ${verdict}` });
+    }
+    // Two children writing one core module concurrently is the collision the
+    // file lane exists to prevent, so the later of any file-sharing pair must
+    // name what it waits on. Order is the array's order — child n may only
+    // depend on something before it.
+    const children = value.decomposition ?? [];
+    for (let i = 1; i < children.length; i++) {
+      const child = children[i]!;
+      if (child.dependsOn.length > 0) continue;
+      const own = new Set(child.writeLane.map((path) => path.trim()));
+      for (let j = 0; j < i; j++) {
+        const shared = children[j]!.writeLane.map((path) => path.trim()).find((path) => own.has(path));
+        if (shared === undefined) continue;
+        ctx.addIssue({
+          code: "custom",
+          message: `decomposition child ${i + 1} shares ${shared} with child ${j + 1} and must serialise on it through dependsOn`,
+        });
+        break;
+      }
+    }
     if (value.routing === MULTI_ROUTING && value.routingSplit === undefined) {
       ctx.addIssue({ code: "custom", message: 'routing "MULTI" requires routingSplit' });
     }
@@ -193,11 +316,27 @@ const ToSpecResultSchema = z
  *  output with (`outputSchema` + `schemaMode: "strict"`, #772). */
 export const TO_SPEC_SCHEMA: object = z.toJSONSchema(ToSpecResultSchema) as object;
 
-export type ToSpecResult = z.infer<typeof ToSpecResultSchema>;
+/**
+ * The validated result every reader gets. `source.freshAt` is a required
+ * number here even though the schema no longer asks the agent for one:
+ * {@link parseToSpecResult} stamps the dispatcher's own observation time onto
+ * every result it returns (#1000), so a persisted verdict always carries a
+ * freshness witness — just never the agent's guess.
+ */
+export type ToSpecResult = Omit<z.infer<typeof ToSpecResultSchema>, "source"> & {
+  source: { name: string; ref: string; freshAt: number };
+};
 
-/** Why a result could not be trusted; each persists as a blocked record. */
+/** Why a result could not be trusted; each persists as a blocked record.
+ *
+ * `no-answer` is the session-level refusal (#1064): the pass produced no
+ * payload at all — the scout was killed at its turn ceiling, or the session
+ * ended without ever yielding. It is a property of the session, never of
+ * output, so it is decided by the pass before anything is parsed and is never
+ * `malformed`. */
 export type ToSpecFailure =
   | { kind: "malformed"; detail: string }
+  | { kind: "no-answer"; detail: string }
   | { kind: "missing-source"; detail: string }
   | { kind: "stale-source"; detail: string };
 
@@ -207,6 +346,28 @@ export type ParseToSpecOutcome = { ok: true; result: ToSpecResult } | { ok: fals
 export interface ToSpecEvidence {
   kind: "to-spec";
   result: ToSpecResult;
+  /**
+   * How the answer arrived (#1064): through the `yield` tool, or recovered
+   * from the session's text because it never yielded. `"text"` is the record's
+   * admission that the verdict did not come through the yield contract — the
+   * answer was complete and valid, so it stands, but a later reader can tell
+   * the two apart. Absent (or `"yield"`) means it came through the contract.
+   */
+  via?: "yield" | "text";
+  /**
+   * Whether the one bounded repair round produced the answer (#1064): the
+   * first answer parsed but violated the contract, the validation error was
+   * handed back, and the re-answer is what this record carries.
+   */
+  repaired?: boolean;
+  /**
+   * What the ready gate found missing when a valid PROMOTABLE verdict was
+   * refused mechanical promotion (#1041). A sibling of `result`, never a
+   * replacement for it: the verdict stays recoverable, so the candidate reads
+   * as groomed-but-rejected rather than ungroomed, and the tick can name what
+   * an operator must fix. Absent on every promoted or unjudged row.
+   */
+  readyGate?: { missing: string[]; checkedAt: number };
 }
 
 /** The row's `evidence` when a result was refused. */
@@ -217,12 +378,21 @@ export interface ToSpecFailureEvidence {
   input: string;
 }
 
-/** How much raw agent output a failure record may carry. */
-export const TO_SPEC_INPUT_SAMPLE_MAX = 2_000;
+/**
+ * How much raw agent output a failure record may carry (#1064).
+ *
+ * Sized for the whole refused payload, not a sample of it: a complete verdict
+ * with a proposed brief and sizing analysis routinely exceeds 2 KB, and a
+ * discarded verdict should be recoverable from the row rather than
+ * re-derived at full session cost. 8 KB holds a full payload with headroom
+ * while still keeping a single refused row bounded.
+ */
+export const TO_SPEC_INPUT_SAMPLE_MAX = 8_000;
 
 /** Refused results always land on the same store surface, named by failure. */
 const FAILURE_REASON: Record<ToSpecFailure["kind"], string> = {
   malformed: "malformed",
+  "no-answer": "no-answer",
   "missing-source": "missing-source",
   "stale-source": "stale-source",
 };
@@ -272,17 +442,82 @@ function extractJson(input: string): string {
   return (fenced?.[1] ?? input).trim();
 }
 
+/**
+ * The three-way gate the scout runner decides a payload against (#1064):
+ * whether a string is a payload at all, and whether that payload already
+ * conforms to the contract or is a single re-answer away from it.
+ *
+ *  - `conforming` — a JSON object that satisfies the strict contract. For
+ *    text-recovered blocks this is the criterion that separates "a complete
+ *    verdict written outside the yield tool" from mere narration.
+ *  - `repairable` — a JSON object that violates the contract (the #1062
+ *    shape: every required field present, one key misnamed). The failure
+ *    carries the first validation issue, which is what the repair round hands
+ *    back to the scout.
+ *  - `not-a-payload` — prose, truncated JSON, a non-object: nothing a
+ *    re-answer can repair, so the pass records no answer rather than grading
+ *    it.
+ *
+ * Same parser as {@link parseToSpecResult}, deliberately: the runner probes
+ * with the one contract so its repair decision can never drift from what the
+ * persistence layer will accept — this is the one validator used twice, not a
+ * second, weaker one.
+ */
+export type ToSpecPayloadGate =
+  | { state: "conforming"; body: string }
+  | { state: "repairable"; body: string; failure: ToSpecFailure }
+  | { state: "not-a-payload" };
+
+export function gateToSpecPayload(payload: string): ToSpecPayloadGate {
+  const body = extractJson(payload);
+  if (body.length === 0) return { state: "not-a-payload" };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return { state: "not-a-payload" };
+  }
+  if (!isObject(raw)) return { state: "not-a-payload" };
+  const parsed = ToSpecResultSchema.safeParse(raw);
+  if (!parsed.success) {
+    // The field path rides in front of the message: zod says "Required" for a
+    // missing field and "Unrecognized key(s)…" for an extra one, and the
+    // repair round's whole value is that the scout sees WHICH field failed.
+    const first = parsed.error.issues[0];
+    const detail =
+      first === undefined
+        ? "schema violation"
+        : first.path.length === 0
+          ? first.message
+          : `${first.path.join(".")}: ${first.message}`;
+    return { state: "repairable", body, failure: { kind: "malformed", detail } };
+  }
+  return { state: "conforming", body };
+}
+
 /**
  * Parse and validate a groomer's raw output against the to-spec contract.
- * `now` is explicit so staleness and determinism are testable: the same
- * input at the same observation time always yields the same outcome. On
- * failure the outcome says *why* in one of the three refusal classes:
- * unparseable/schema-breaking output is `malformed`, output that never names
- * an authoritative source (or lacks name/ref/freshAt) is `missing-source`,
- * and a source observed more than `TO_SPEC_MAX_SOURCE_AGE_MS` ago is
- * `stale-source`. A `freshAt` in the future is a clock lie, hence malformed.
+ * `now` is the settle time, explicit so staleness and determinism are
+ * testable: the same input over the same batch window always yields the same
+ * outcome. On failure the outcome says *why* in one of the three refusal
+ * classes: unparseable/schema-breaking output is `malformed`, output that
+ * never names an authoritative source (or lacks name/ref) is
+ * `missing-source`, and a batch whose window is wider than
+ * `TO_SPEC_MAX_SOURCE_AGE_MS` is `stale-source`.
+ *
+ * The observation time is the dispatcher's, never the agent's (#1000).
+ * `opts.launchedAt` is when the batch was launched — the conservative (older)
+ * end of its wall-clock window, so staleness is never understated — and
+ * `now` stands in when no launch time is known. Whatever the agent put in
+ * `source.freshAt` is overwritten by that stamp before the result is
+ * returned, so the persisted evidence carries the dispatcher's own witness
+ * and a guessed timestamp can no longer discard a correct verdict.
  */
-export function parseToSpecResult(input: string, now: number): ParseToSpecOutcome {
+export function parseToSpecResult(
+  input: string,
+  now: number,
+  opts?: { launchedAt?: number },
+): ParseToSpecOutcome {
   const body = extractJson(input);
   if (body.length === 0) {
     return { ok: false, failure: { kind: "malformed", detail: "empty answer — no JSON found" } };
@@ -300,25 +535,31 @@ export function parseToSpecResult(input: string, now: number): ParseToSpecOutcom
   if (!parsed.success) {
     const detail = parsed.error.issues[0]?.message ?? "schema violation";
     const source = raw.source;
-    if (!isObject(source) || source.name === undefined || source.ref === undefined || source.freshAt === undefined) {
+    // `freshAt` is no longer part of this test: the dispatcher stamps it, so
+    // a source is complete when it names what was read and at which ref.
+    if (!isObject(source) || source.name === undefined || source.ref === undefined) {
       return { ok: false, failure: { kind: "missing-source", detail: `no authoritative source — ${detail}` } };
     }
     return { ok: false, failure: { kind: "malformed", detail } };
   }
-  const freshAt = parsed.data.source.freshAt;
-  if (freshAt > now) {
-    return { ok: false, failure: { kind: "malformed", detail: `source freshAt ${freshAt} lies in the future of ${now}` } };
-  }
-  if (now - freshAt > TO_SPEC_MAX_SOURCE_AGE_MS) {
+  // The launch bound when the dispatcher knows it and it precedes the settle
+  // time — a launch stamped after `now` is clock skew, not evidence, so the
+  // settle time stands in rather than producing a negative age (#1000).
+  const launchedAt = opts?.launchedAt;
+  const observedAt =
+    launchedAt !== undefined && Number.isFinite(launchedAt) && launchedAt <= now ? launchedAt : now;
+  if (now - observedAt > TO_SPEC_MAX_SOURCE_AGE_MS) {
     return {
       ok: false,
       failure: {
         kind: "stale-source",
-        detail: `source observed at ${freshAt} is ${now - freshAt}ms old — older than the ${TO_SPEC_MAX_SOURCE_AGE_MS}ms ceiling`,
+        detail:
+          `the batch that read the source launched at ${observedAt}, ${now - observedAt}ms before this item ` +
+          `settled — older than the ${TO_SPEC_MAX_SOURCE_AGE_MS}ms ceiling`,
       },
     };
   }
-  return { ok: true, result: parsed.data };
+  return { ok: true, result: { ...parsed.data, source: { ...parsed.data.source, freshAt: observedAt } } };
 }
 
 /** What one grooming pass did to the row, so the caller can report it. */
@@ -330,11 +571,38 @@ export type ToSpecGroomingOutcome =
 export interface ToSpecGroomingRequest {
   project: string;
   issue: number;
-  /** The agent's raw output, exactly as returned. */
+  /** The agent's structured answer, exactly as returned: the yield payload,
+   *  or a conforming block recovered from its text. Empty when the pass
+   *  produced no answer at all — which is its own refusal class, decided here
+   *  before anything is parsed (#1064). */
   input: string;
+  /** How the answer arrived: through the yield tool, or recovered from the
+   *  session's text because it never yielded. `"text"` marks the record so it
+   *  stays visible that the verdict did not come through the yield contract;
+   *  omitted reads as a yield, and an empty `input` with no `via` reads as no
+   *  answer. */
+  via?: "yield" | "text";
+  /** The session's last narration, recorded as the refusal's context when no
+   *  answer arrived — never parsed as a verdict (#1064). */
+  report?: string;
+  /** Whether the one bounded repair round produced the carried answer
+   *  (#1064); recorded on the row so a repaired verdict is distinguishable. */
+  repaired?: boolean;
+  /** Whether the session was killed at its turn ceiling before it answered
+   *  (#1064) — half of the no-answer shape naming. */
+  killedAtCeiling?: boolean;
+  /** The turn ceiling the pass ran under, and the turns it took: the other
+   *  half of the no-answer shape naming (`turns >= maxTurns` reads as a cap
+   *  kill even when the runner did not flag it). */
+  maxTurns?: number;
+  turns?: number;
   /** Observation time for staleness and the recorded row; `Date.now()` when
    *  omitted (tests pass it to keep reprocessing deterministic). */
   now?: number;
+  /** When the batch that produced this output was launched, on the
+   *  dispatcher's own clock (#1000). It becomes the source observation time in
+   *  preference to `now`; omit it and the settle time stands in. */
+  launchedAt?: number;
 }
 
 function failureEvidence(failure: ToSpecFailure, input: string): string {
@@ -354,25 +622,56 @@ function failureEvidence(failure: ToSpecFailure, input: string): string {
  * `evidence` (`to-spec-failure`) — never as promotable/considered — except
  * when a prior valid result exists: malformed reprocessing then keeps that
  * prior row instead of erasing it. Nothing here touches labels or issues.
+ *
+ * `request.launchedAt` is the dispatcher's launch stamp for the batch (#1000);
+ * it, not anything the agent wrote, becomes the recorded source observation
+ * time.
  */
-export function recordToSpecGrooming(store: Store, request: ToSpecGroomingRequest): ToSpecGroomingOutcome {
-  const now = request.now ?? Date.now();
-  const parsed = parseToSpecResult(request.input, now);
-  if (parsed.ok) {
-    const evidence: ToSpecEvidence = { kind: "to-spec", result: parsed.result };
-    store.upsertGrooming({
-      project: request.project,
-      issue: request.issue,
-      verdict: mapStoreVerdict(parsed.result.verdict),
-      reason: mapStoreReason(parsed.result.verdict),
-      evidence: JSON.stringify(evidence),
-      at: now,
-    });
-    return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
+/**
+ * The reason a via-text verdict carries: the groomer's own label with a
+ * visible marker that the answer arrived outside the yield contract (#1064),
+ * so `status` reads `#13 promotable via text` instead of hiding the
+ * distinction in an evidence string. Yielded verdicts keep the bare label.
+ */
+function mapStoreReasonWithVia(verdict: ToSpecVerdict, via: "yield" | "text" | undefined): string {
+  const label = mapStoreReason(verdict);
+  return via === "text" ? `${label} via text` : label;
+}
+
+/**
+ * The no-answer detail names which of the two session shapes produced it
+ * (#1064): a turn-ceiling kill (`killedAtCeiling`, or `turns >= maxTurns`
+ * when the runner did not flag it) or a session that ended without ever
+ * yielding.
+ */
+function noAnswerDetail(request: ToSpecGroomingRequest): string {
+  const killed =
+    request.killedAtCeiling === true ||
+    (request.maxTurns !== undefined && request.turns !== undefined && request.turns >= request.maxTurns);
+  const turns = request.turns === undefined ? "" : ` after ${request.turns} turn(s)`;
+  if (killed) {
+    const ceiling = request.maxTurns === undefined ? "its turn ceiling" : `its ${request.maxTurns}-turn ceiling`;
+    return `the scout was killed at ${ceiling}${turns} and never yielded an answer`;
   }
+  return `the scout session ended${turns} without yielding an answer`;
+}
+
+/**
+ * Persist one refusal, or keep a prior valid verdict when the new pass
+ * produced something no-answer-like or malformed. `input` is what the failure
+ * record carries: the raw payload of the refused pass — or, for a no-answer
+ * pass, the session's narration as context (#1064).
+ */
+function persistGroomingRefusal(
+  store: Store,
+  request: ToSpecGroomingRequest,
+  failure: ToSpecFailure,
+  input: string,
+  now: number,
+): ToSpecGroomingOutcome {
   const prior = store.grooming(request.project, request.issue);
   if (
-    parsed.failure.kind === "malformed" &&
+    (failure.kind === "malformed" || failure.kind === "no-answer") &&
     prior !== undefined &&
     (prior.verdict === "promotable" || prior.verdict === "considered")
   ) {
@@ -382,13 +681,83 @@ export function recordToSpecGrooming(store: Store, request: ToSpecGroomingReques
     project: request.project,
     issue: request.issue,
     verdict: "blocked",
-    reason: FAILURE_REASON[parsed.failure.kind],
-    evidence: failureEvidence(parsed.failure, request.input),
+    reason: FAILURE_REASON[failure.kind],
+    evidence: failureEvidence(failure, input),
     at: now,
   });
   return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
 }
 
+/**
+ * The only way a groomer's output becomes a durable grooming verdict: parse
+ * and validate, then upsert through the existing store — no second store, no
+ * `GroomingRecord` extension. Valid results map to the store's verdict
+ * surface with the full structured result serialized into `evidence`
+ * (`{"kind":"to-spec","result":…}`), which is what survives a restart. A
+ * refused result persists as `blocked` with the failure named in
+ * `evidence` (`to-spec-failure`) — never as promotable/considered — except
+ * when a prior valid result exists: malformed and no-answer reprocessing then
+ * keep that prior row instead of erasing it. Nothing here touches labels or
+ * issues.
+ *
+ * The refusal classes come from the whole pass, not just its output (#1064):
+ *
+ *  - `no-answer` — the session produced no payload at all (no yield, no
+ *    conforming text block): a turn-ceiling kill or a session end without a
+ *    yield, recorded by shape, never as `malformed`. The narration is kept as
+ *    context only. A text-carried block that fails validation is also
+ *    `no-answer` — such a session never yielded, and the block is not an
+ *    answer — except a batch-window staleness, which is a property of the
+ *    pass rather than the answer.
+ *  - `malformed` / `missing-source` — a *yielded* payload (or an unjudged
+ *    one) that violates the contract, with the raw payload persisted so the
+ *    discarded verdict stays recoverable.
+ *  - `stale-source` — the batch window outlived the freshness ceiling.
+ *
+ * `request.launchedAt` is the dispatcher's launch stamp for the batch (#1000);
+ * it, not anything the agent wrote, becomes the recorded source observation
+ * time.
+ */
+export function recordToSpecGrooming(store: Store, request: ToSpecGroomingRequest): ToSpecGroomingOutcome {
+  const now = request.now ?? Date.now();
+  if (request.input === "") {
+    return persistGroomingRefusal(
+      store,
+      request,
+      { kind: "no-answer", detail: noAnswerDetail(request) },
+      request.report ?? "",
+      now,
+    );
+  }
+  const parsed = parseToSpecResult(request.input, now, { launchedAt: request.launchedAt });
+  if (parsed.ok) {
+    const evidence: ToSpecEvidence = {
+      kind: "to-spec",
+      result: parsed.result,
+      ...(request.via === undefined ? {} : { via: request.via }),
+      ...(request.repaired === true ? { repaired: true } : {}),
+    };
+    store.upsertGrooming({
+      project: request.project,
+      issue: request.issue,
+      verdict: mapStoreVerdict(parsed.result.verdict),
+      reason: mapStoreReasonWithVia(parsed.result.verdict, request.via),
+      evidence: JSON.stringify(evidence),
+      at: now,
+    });
+    return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
+  }
+  // A text-carried answer that fails validation was never yielded and does
+  // not conform: that is a no-answer pass, with the block kept as the
+  // failure's context — never malformed (#1064). The one exception is a
+  // batch-window staleness, whose class is about the pass, not the answer.
+  const failure =
+    request.via === "text" && parsed.failure.kind !== "stale-source"
+      ? { kind: "no-answer" as const, detail: noAnswerDetail(request) }
+      : parsed.failure;
+  return persistGroomingRefusal(store, request, failure, request.input, now);
+}
+
 /**
  * Recover the validated result from a record's evidence (the restart
  * round-trip). Returns undefined for anything that is not a `to-spec`
@@ -404,7 +773,15 @@ export function parseToSpecEvidence(evidence: string): ToSpecResult | undefined
   }
   if (!isObject(raw) || raw.kind !== "to-spec") return undefined;
   const parsed = ToSpecResultSchema.safeParse(raw.result);
-  return parsed.success ? parsed.data : undefined;
+  if (!parsed.success) return undefined;
+  const freshAt = parsed.data.source.freshAt;
+  // A row with no stamped observation time cannot have its staleness judged,
+  // and freshness is precisely the field nobody may forge (#1000) — so the row
+  // reads as not-durably-groomed and becomes re-groomable, rather than
+  // carrying a fabricated timestamp that would read fresh forever. Every row
+  // `recordToSpecGrooming` writes is stamped; this is the hand-edited case.
+  if (freshAt === undefined) return undefined;
+  return { ...parsed.data, source: { ...parsed.data.source, freshAt } };
 }
 
 /**
@@ -428,7 +805,12 @@ export function parseToSpecFailureEvidence(evidence: string): ToSpecFailure | un
   if (!isObject(raw) || raw.kind !== "to-spec-failure") return undefined;
   const failure = raw.failure;
   if (!isObject(failure) || typeof failure.detail !== "string") return undefined;
-  if (failure.kind !== "malformed" && failure.kind !== "missing-source" && failure.kind !== "stale-source") {
+  if (
+    failure.kind !== "malformed" &&
+    failure.kind !== "no-answer" &&
+    failure.kind !== "missing-source" &&
+    failure.kind !== "stale-source"
+  ) {
     return undefined;
   }
   return { kind: failure.kind, detail: failure.detail };