omp-conductor 0.19.6 → 0.20.0

package/src/to-spec.ts

@@ -34,6 +34,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 +87,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 +105,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 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("The authoritative source/ref/freshness every verdict must stand on.");
+  .describe("One ordered child slice a decomposition proposal names (#1041).");
 
 /**
  * The one strict contract a grooming result must satisfy before it may
@@ -143,6 +207,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 +245,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 +268,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,7 +315,16 @@ 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. */
 export type ToSpecFailure =
@@ -207,6 +338,14 @@ export type ParseToSpecOutcome = { ok: true; result: ToSpecResult } | { ok: fals
 export interface ToSpecEvidence {
   kind: "to-spec";
   result: ToSpecResult;
+  /**
+   * 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. */
@@ -274,15 +413,27 @@ function extractJson(input: string): string {
 
 /**
  * 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 +451,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. */
@@ -335,6 +492,10 @@ export interface ToSpecGroomingRequest {
   /** 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,10 +515,14 @@ 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);
+  const parsed = parseToSpecResult(request.input, now, { launchedAt: request.launchedAt });
   if (parsed.ok) {
     const evidence: ToSpecEvidence = { kind: "to-spec", result: parsed.result };
     store.upsertGrooming({
@@ -404,7 +569,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 } };
 }
 
 /**

package/src/tracker/github.ts

@@ -486,6 +486,40 @@ export function prVerificationFrom(
   return { status: "green", reason: `${checks.length} checks succeeded or were skipped`, headSha };
 }
 
+/**
+ * Whether one raw `gh pr view --json ...statusCheckRollup` payload collected
+ * zero rollup contexts (#999).
+ *
+ * {@link prVerificationFrom} maps zero collected checks to `pending` — "GitHub
+ * has not reported any checks yet" — which is the right refusal when it is
+ * true, and a silent stall when it is not. It is not always true: a head whose
+ * PR was opened by `github-actions[bot]` carries a second, empty
+ * `action_required` check suite beside the completed one, and the rollup read
+ * can resolve that empty suite and collect nothing while 18 check-runs
+ * (one of them failed) sit on the same SHA. So the caller uses this to treat
+ * an empty rollup as *unresolvable* and re-prove from the REST plane, which
+ * flattens every page of both `check_runs` and `statuses` for the exact head
+ * and sees all of them.
+ *
+ * A missing rollup counts as zero collected, exactly as
+ * {@link prVerificationFrom}'s `?? []` does. A body this predicate cannot read
+ * — unparseable, not a JSON object (a bare list is not a `pr view` payload),
+ * or a rollup that is not a list — is not its problem: it answers false so the
+ * existing verdict stands unchanged.
+ */
+export function rollupCollectedNoChecks(raw: string): boolean {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return false;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+  const rollup = (parsed as GhPrVerification).statusCheckRollup;
+  if (rollup === undefined || rollup === null) return true;
+  return Array.isArray(rollup) && rollup.length === 0;
+}
+
 function failedCheck(raw: string): GhCheck | undefined {
   const checks = (JSON.parse(raw) as GhPrVerification).statusCheckRollup ?? [];
   return checks.find((check) => checkVerdict(check) === "failed");
@@ -2024,6 +2058,22 @@ export function makeTracker(
           "state,isDraft,headRefOid,statusCheckRollup",
         ]);
         const verification = prVerificationFrom(raw, expectedHead, opts);
+        if (verification.status === "pending" && rollupCollectedNoChecks(raw)) {
+          // An empty rollup is not proof that the head has no checks (#999):
+          // a PR opened by `github-actions[bot]` carries a second, empty
+          // `action_required` suite beside the completed one, the rollup read
+          // resolves that suite, collects nothing, and this verdict reads
+          // "GitHub has not reported any checks yet" over a head with 18
+          // check-runs and a failure among them. A commit that carries an
+          // empty suite beside a completed one is not a commit with no
+          // checks, so zero collected contexts is unresolvable rather than
+          // decisive: re-prove from REST, which flattens every page of both
+          // `check_runs` and `statuses` for the exact head. REST that cannot
+          // answer leaves this pending exactly as it stands — fail-closed,
+          // never green by omission.
+          const rest = await verifyPrRest(runGh, cache, url, expectedHead, opts, hooks.onNotModified);
+          return rest ?? verification;
+        }
         if (verification.status !== "failed") return verification;
 
         const detailsUrl = failedCheck(raw)?.detailsUrl;