omp-conductor 0.18.0 → 0.18.2

package/src/to-spec.ts

@@ -0,0 +1,408 @@
+/**
+ * The to-spec grooming contract (#679, #772): the one structured result a
+ * groomer agent must answer in before anything it says may become a durable
+ * grooming verdict. #735 landed the durable grooming table, but no shipped
+ * agent contract, strict result parser, or persistence path. This module
+ * ships all three: the prompt lives in `briefs/to-spec.md`, the strict JSON
+ * Schema the task agent is invoked through is `TO_SPEC_SCHEMA`, and
+ * `recordToSpecGrooming` is the only persistence path — parse and validate
+ * first, then write through the existing `Store.upsertGrooming`.
+ *
+ * The store's verdict surface is `promotable | blocked | considered` (#735).
+ * 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`.
+ * 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
+ * output does replace it — as blocked, because a judgeable refusal is
+ * information: the latest pass could not ground a verdict, so the candidate
+ * must not keep reading as groomed.
+ *
+ * The structured result survives a process/tick restart inside the record's
+ * existing `evidence` field — a JSON payload with a `kind` discriminator
+ * (`to-spec` | `to-spec-failure`) — so no `GroomingRecord` extension and no
+ * second store is needed. Nothing here launches a task, edits an issue,
+ * creates decomposition children, or touches the queue label: the
+ * orchestrator remains the only promotion authority.
+ *
+ * The invocation contract is OMP's native task-agent output schema: the
+ * later tick passes `outputSchema: TO_SPEC_SCHEMA` with `schemaMode:
+ * "strict"` to the task tool. Conductor re-validates whatever the agent
+ * returned before persisting, because the harness is permissive by design
+ * and the store vets only what this module hands it.
+ *
+ * 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
+ * rendered brief, the shipped agent role, and the floor's return contract to
+ * exactly these fields — a field the prose asks for that the schema refuses
+ * is a candidate recorded blocked for following instructions.
+ */
+
+import { z } from "zod";
+
+import type { GroomingRecord, GroomingVerdict, Store } from "./types.ts";
+
+/** The five verdicts a to-spec groomer may return (#772). */
+export const TO_SPEC_VERDICTS = [
+  "ALREADY DONE",
+  "PROMOTABLE",
+  "NEEDS DECOMPOSITION",
+  "BLOCKED",
+  "NEEDS PRODUCT DECISION",
+] as const;
+
+export type ToSpecVerdict = (typeof TO_SPEC_VERDICTS)[number];
+
+/**
+ * How old an authoritative source may be before a result drawn from it no
+ * longer counts. A verdict computed over a default branch that has moved on
+ * may have missed a landing that invalidates it, so a result whose source was
+ * observed longer ago than this persists as `blocked(stale-source)` and can
+ * 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.
+ */
+export const TO_SPEC_MAX_SOURCE_AGE_MS = 24 * 60 * 60 * 1000;
+
+/** `routing: "MULTI"` requires `routingSplit` naming one repo per slice. */
+const MULTI_ROUTING = "MULTI" as const;
+
+const ToSpecSourceSchema = z
+  .object({
+    name: z.string().trim().min(1).describe("The authoritative source that was read: repo or tracker, e.g. `TerrifiedBug/conductor`."),
+    ref: z.string().trim().min(1).describe("The exact ref (commit/branch/tag) that was reviewed."),
+    freshAt: z
+      .number()
+      .int()
+      .describe("Epoch milliseconds when the source was observed — required so staleness is judgeable without trusting prose."),
+  })
+  .strict()
+  .describe("The authoritative source/ref/freshness every verdict must stand on.");
+
+/**
+ * The one strict contract a grooming result must satisfy before it may
+ * persist as promotable or considered (and everything else maps onto blocked
+ * or is refused). `proposedBrief` and `reasonNotToPromote` are exactly one of
+ * the two, chosen by verdict: PROMOTABLE carries the brief, every other
+ * verdict states why it must not be promoted.
+ */
+const ToSpecResultSchema = z
+  .object({
+    verdict: z.enum(TO_SPEC_VERDICTS).describe("Exactly one of the five to-spec verdicts."),
+    routing: z
+      .string()
+      .trim()
+      .min(1)
+      .describe("Exactly one `owner/repo`, or `MULTI` with `routingSplit` naming the split."),
+    routingSplit: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe("Required when `routing` is `MULTI`: what each slice goes to."),
+    source: ToSpecSourceSchema,
+    evidence: z
+      .array(z.string().trim().min(1))
+      .optional()
+      .describe(
+        "The files/symbols proving the verdict — required for ALREADY DONE (the code that already does the work, never a title match); welcome on every verdict.",
+      ),
+    laterWorkInvalidates: z
+      .boolean()
+      .describe("Whether later work (an epic committed after this candidate was filed) invalidated its premise."),
+    laterWorkNote: z
+      .string()
+      .trim()
+      .min(1)
+      .describe("What was searched for the invalidating-later-work check and what was found — the check's evidence."),
+    entryPoints: z
+      .array(z.string().trim().min(1))
+      .min(3)
+      .max(6)
+      .describe("3-6 files to change or read first, the discovery a worker budget dies on when absent."),
+    existingTests: z
+      .array(z.string().trim().min(1))
+      .describe("Tests that already exercise the behaviour, by path; empty when none exist."),
+    likelySilentFake: z
+      .string()
+      .trim()
+      .min(1)
+      .describe("The single thing most likely to be silently faked while implementing and how to prove it is not."),
+    proofCommands: z
+      .array(z.string().trim().min(1))
+      .min(1)
+      .describe("Focused commands that prove the work, each with its cwd when relevant."),
+    fileLane: z
+      .array(z.string().trim().min(1))
+      .min(1)
+      .describe("The files/dirs this slice writes — the file lane that serialises concurrent work."),
+    dependencies: z
+      .array(z.union([z.string().trim().min(1), z.number().int().min(1)]))
+      .describe(
+        'Open prerequisites this work is blocked on, as bare issue numbers (875) or strings ("875"); empty when none.',
+      ),
+    proposedBrief: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe("Required for PROMOTABLE: the brief a worker would be dispatched with."),
+    reasonNotToPromote: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe("Required for every verdict except PROMOTABLE: why this must not be promoted."),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const verdict = value.verdict;
+    if (verdict === "PROMOTABLE") {
+      if (value.proposedBrief === undefined) {
+        ctx.addIssue({ code: "custom", message: "PROMOTABLE requires proposedBrief" });
+      }
+      if (value.reasonNotToPromote !== undefined) {
+        ctx.addIssue({ code: "custom", message: "PROMOTABLE must not carry reasonNotToPromote" });
+      }
+    } else {
+      if (value.reasonNotToPromote === undefined) {
+        ctx.addIssue({ code: "custom", message: `${verdict} requires reasonNotToPromote` });
+      }
+      if (value.proposedBrief !== undefined) {
+        ctx.addIssue({ code: "custom", message: `${verdict} must not carry proposedBrief` });
+      }
+    }
+    if (verdict === "ALREADY DONE" && (value.evidence === undefined || value.evidence.length === 0)) {
+      ctx.addIssue({
+        code: "custom",
+        message: "ALREADY DONE requires evidence naming the file/symbol that already does the work",
+      });
+    }
+    if (value.routing === MULTI_ROUTING && value.routingSplit === undefined) {
+      ctx.addIssue({ code: "custom", message: 'routing "MULTI" requires routingSplit' });
+    }
+    if (value.routing !== MULTI_ROUTING && value.routingSplit !== undefined) {
+      ctx.addIssue({ code: "custom", message: "routingSplit is only valid with routing `MULTI`" });
+    }
+  })
+  .describe("A complete, to-spec grooming result; nothing outside this shape is accepted.");
+
+/** The strict JSON Schema the OMP task tool validates the agent's structured
+ *  output with (`outputSchema` + `schemaMode: "strict"`, #772). */
+export const TO_SPEC_SCHEMA: object = z.toJSONSchema(ToSpecResultSchema) as object;
+
+export type ToSpecResult = z.infer<typeof ToSpecResultSchema>;
+
+/** Why a result could not be trusted; each persists as a blocked record. */
+export type ToSpecFailure =
+  | { kind: "malformed"; detail: string }
+  | { kind: "missing-source"; detail: string }
+  | { kind: "stale-source"; detail: string };
+
+export type ParseToSpecOutcome = { ok: true; result: ToSpecResult } | { ok: false; failure: ToSpecFailure };
+
+/** The row's `evidence` when a result passed validation. */
+export interface ToSpecEvidence {
+  kind: "to-spec";
+  result: ToSpecResult;
+}
+
+/** The row's `evidence` when a result was refused. */
+export interface ToSpecFailureEvidence {
+  kind: "to-spec-failure";
+  failure: ToSpecFailure;
+  /** The raw agent output, bounded, so a refusal is diagnosable. */
+  input: string;
+}
+
+/** How much raw agent output a failure record may carry. */
+export const TO_SPEC_INPUT_SAMPLE_MAX = 2_000;
+
+/** Refused results always land on the same store surface, named by failure. */
+const FAILURE_REASON: Record<ToSpecFailure["kind"], string> = {
+  malformed: "malformed",
+  "missing-source": "missing-source",
+  "stale-source": "stale-source",
+};
+
+/** The five contract verdicts onto the store's three (#735). */
+function mapStoreVerdict(verdict: ToSpecVerdict): GroomingVerdict {
+  switch (verdict) {
+    case "PROMOTABLE":
+      return "promotable";
+    case "ALREADY DONE":
+    case "NEEDS DECOMPOSITION":
+      return "considered";
+    case "BLOCKED":
+    case "NEEDS PRODUCT DECISION":
+      return "blocked";
+  }
+}
+
+/** The groomer's own label the record carries (the #679 half of `reason`). */
+function mapStoreReason(verdict: ToSpecVerdict): string {
+  switch (verdict) {
+    case "ALREADY DONE":
+      return "already-done";
+    case "PROMOTABLE":
+      return "promotable";
+    case "NEEDS DECOMPOSITION":
+      return "needs-decomposition";
+    case "BLOCKED":
+      return "blocked";
+    case "NEEDS PRODUCT DECISION":
+      return "needs-product-decision";
+  }
+}
+
+/** True for a JSON object value (null and arrays excluded). */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Pulls one fenced JSON block out of an agent answer, exactly like the setup
+ * probes: a model's text, parsed as JSON. Anything unparseable is malformed —
+ * no seed at all, and the candidate persists as blocked rather than groomed.
+ */
+function extractJson(input: string): string {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(input);
+  return (fenced?.[1] ?? input).trim();
+}
+
+/**
+ * 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.
+ */
+export function parseToSpecResult(input: string, now: number): ParseToSpecOutcome {
+  const body = extractJson(input);
+  if (body.length === 0) {
+    return { ok: false, failure: { kind: "malformed", detail: "empty answer — no JSON found" } };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return { ok: false, failure: { kind: "malformed", detail: "output is not valid JSON" } };
+  }
+  if (!isObject(raw)) {
+    return { ok: false, failure: { kind: "malformed", detail: "output is not a JSON object" } };
+  }
+  const parsed = ToSpecResultSchema.safeParse(raw);
+  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) {
+      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) {
+    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`,
+      },
+    };
+  }
+  return { ok: true, result: parsed.data };
+}
+
+/** What one grooming pass did to the row, so the caller can report it. */
+export type ToSpecGroomingOutcome =
+  | { kind: "persisted"; record: GroomingRecord }
+  | { kind: "kept-prior"; record: GroomingRecord };
+
+/** One candidate's grooming pass. */
+export interface ToSpecGroomingRequest {
+  project: string;
+  issue: number;
+  /** The agent's raw output, exactly as returned. */
+  input: string;
+  /** Observation time for staleness and the recorded row; `Date.now()` when
+   *  omitted (tests pass it to keep reprocessing deterministic). */
+  now?: number;
+}
+
+function failureEvidence(failure: ToSpecFailure, input: string): string {
+  const sample =
+    input.length > TO_SPEC_INPUT_SAMPLE_MAX ? `${input.slice(0, TO_SPEC_INPUT_SAMPLE_MAX)}…[truncated]` : input;
+  const payload: ToSpecFailureEvidence = { kind: "to-spec-failure", failure, input: sample };
+  return JSON.stringify(payload);
+}
+
+/**
+ * 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 reprocessing then keeps that
+ * prior row instead of erasing it. Nothing here touches labels or issues.
+ */
+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)! };
+  }
+  const prior = store.grooming(request.project, request.issue);
+  if (
+    parsed.failure.kind === "malformed" &&
+    prior !== undefined &&
+    (prior.verdict === "promotable" || prior.verdict === "considered")
+  ) {
+    return { kind: "kept-prior", record: prior };
+  }
+  store.upsertGrooming({
+    project: request.project,
+    issue: request.issue,
+    verdict: "blocked",
+    reason: FAILURE_REASON[parsed.failure.kind],
+    evidence: failureEvidence(parsed.failure, request.input),
+    at: now,
+  });
+  return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
+}
+
+/**
+ * Recover the validated result from a record's evidence (the restart
+ * round-trip). Returns undefined for anything that is not a `to-spec`
+ * payload or fails validation again, so a hand-edited row cannot read back
+ * as groomed.
+ */
+export function parseToSpecEvidence(evidence: string): ToSpecResult | undefined {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(evidence);
+  } catch {
+    return undefined;
+  }
+  if (!isObject(raw) || raw.kind !== "to-spec") return undefined;
+  const parsed = ToSpecResultSchema.safeParse(raw.result);
+  return parsed.success ? parsed.data : undefined;
+}

package/src/tracker/github.ts

@@ -132,6 +132,30 @@ export class GhError extends Error {
   }
 }
 
+/**
+ * The one classified failure {@link Tracker.prState} throws (#779): the named
+ * pull request definitively does not exist. It is thrown only for an
+ * individual REST 404 that a same-repository pulls-list read has corroborated
+ * (see {@link repoPullReadUnavailable}) — a deleted or never-created PR number
+ * in a repository the credential can still read. A repository hidden from the
+ * credential (private, lost token scope, SSO enforcement) also answers 404,
+ * so without that corroboration a 404 stays "could not tell".
+ *
+ * Distinct from a plain {@link GhError} because a corroborated 404 is an
+ * answer, not an outage: retrying can never conjure the PR, so the settle
+ * sweep releases the stranded row — over its preserved branch — instead of
+ * re-asking a nonexistent PR forever. Every other failure (a revoked token, a
+ * flaky network, a server 5xx, an opaque 404) still resolves to `undefined`
+ * from `prState`, and the port's "could not tell, ask again for free" callers
+ * never see it.
+ */
+export class GhPrMissingError extends GhError {
+  constructor(cause: GhError) {
+    super(cause.argv, cause.code, cause.stderr, cause.stdout);
+    this.name = "GhPrMissingError";
+  }
+}
+
 /**
  * The single execution path for this adapter. `stdin` is written to the child
  * and closed, which is how bodies containing newlines, backticks or a leading
@@ -1308,6 +1332,20 @@ export function isTransientServerError(err: unknown): boolean {
   return err instanceof GhError && isTransientServer5xx(err.stderr);
 }
 
+/**
+ * True when a `gh` failure is the REST layer answering 404 for the requested
+ * resource. The raw status is deliberately not the definitive verdict: GitHub
+ * returns the same 404 for a PR number absent from a readable repository and
+ * for a whole repository hidden from the credential, so the caller must
+ * corroborate against a same-repository pull-read (see
+ * {@link repoPullReadUnavailable}) before a 404 means "the PR is gone". What a
+ * 404 does always mean is that it is not a 5xx ("ask later") and not a 401/403
+ * credential refusal. gh's stderr renders the status as `HTTP 404: Not Found`.
+ */
+export function isMissingPr404(err: unknown): err is GhError {
+  return err instanceof GhError && /HTTP 404\b/i.test(err.stderr);
+}
+
 /**
  * True when a `gh` argv rides the GraphQL API surface rather than core REST.
  *
@@ -1403,6 +1441,35 @@ export class GhRateLimitError extends GhError {
  *  rate-limit refusal opens and the GraphQL-only gate a 5xx opens. */
 export const RATE_LIMIT_COOLDOWN_MS = 60_000;
 
+/**
+ * The control that makes an individual PR read's 404 definitive (#781 review
+ * round 1): whether the repository named by `parts` answers a Pull Requests
+ * list read to the current credential.
+ *
+ * GitHub returns the same 404 bytes in two opposite situations — a PR number
+ * that does not exist in a repository this credential can read, and a whole
+ * repository hidden from the credential (private, lost token scope, SSO
+ * enforcement) — so a bare 404 on the individual read says nothing. Asking
+ * the same-repository pulls surface splits them: a 200, even `[]`, proves
+ * pull-read access and makes the individual 404 a genuinely missing PR; a
+ * control that is itself unavailable leaves the question open and the caller
+ * must keep its row retryable. Returns true when pull-read access cannot be
+ * proven.
+ */
+async function repoPullReadUnavailable(
+  runGh: typeof gh,
+  parts: { owner: string; repo: string },
+): Promise<boolean> {
+  // `--jq length` bounds the payload to one integer while still exercising the
+  // exact pull-read surface; `gh api` returns the first page only by default.
+  try {
+    await runGh(["api", `repos/${parts.owner}/${parts.repo}/pulls`, "--jq", "length"]);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
 /** Instrumentation hooks the daemon binds the tracker to (#198). */
 export interface TrackerHooks {
   /** Fired immediately before each `gh` spawn, so the daemon can count its own
@@ -1734,12 +1801,41 @@ export function makeTracker(
             "{state, merged_at}",
           ]),
         );
+      } catch (err) {
+        // One classified throw, and only one: an individual REST 404 that the
+        // same-repository pulls read corroborates. 404 alone is ambiguous —
+        // GitHub hides a whole repository the credential cannot read as the
+        // same 404, so a lost token scope or SSO change would otherwise
+        // terminalize every real run (#781 review round 1). Only a PR number
+        // that is genuinely gone while the repo still answers pull-read access
+        // is definitively missing. Everything else — a hidden/private repo, a
+        // revoked token, a flaky network, a server 5xx — stays undefined per
+        // the port's fail-closed contract, and the row retries for free.
+        if (isMissingPr404(err) && !(await repoPullReadUnavailable(runGh, parts))) {
+          throw new GhPrMissingError(err);
+        }
+        return undefined;
+      }
+    },
+
+    async prHead(url: string): Promise<string | undefined> {
+      if (!PR_URL.test(url)) return undefined;
+      const parts = prUrlParts(url);
+      if (parts === undefined) return undefined;
+      try {
+        // The REST pull-request projection carries the head at `.head.sha` —
+        // there is no top-level `head_sha` (verified live on #812). The jq
+        // renames it, the same idiom `verifyPrRest` uses, so the shared
+        // `restPrHeadFrom` parser sees the shape it is tested against.
+        return restPrHeadFrom(
+          await runGh([
+            "api",
+            `repos/${parts.owner}/${parts.repo}/pulls/${parts.number}`,
+            "--jq",
+            "{head_sha: .head.sha}",
+          ]),
+        );
       } catch {
-        // Never throws, per the port's contract. A deleted PR, a revoked token
-        // and a flaky network all mean "could not tell", and the caller's whole
-        // job is to leave the row alone on that — so classifying them here would
-        // buy nothing but a way to get the classification wrong. The next tick
-        // asks again for free.
         return undefined;
       }
     },
@@ -2076,15 +2172,9 @@ export function makeTracker(
     },
 
     async childrenOf(issue: number): Promise<{ number: number; state: IssueState }[]> {
-      try {
-        return labeledIssuesFrom(
-          await runGh(["api", `repos/${repo}/issues/${issue}/sub_issues`, "--jq", "[.[] | {number, state}]"]),
-        );
-      } catch {
-        // Also the answer on a repo without the sub-issues API, or an issue that
-        // was never decomposed. All three mean the same thing to the caller.
-        return [];
-      }
+      return labeledIssuesFrom(
+        await runGh(["api", `repos/${repo}/issues/${issue}/sub_issues`, "--jq", "[.[] | {number, state}]"]),
+      );
     },
   };