@davidvornholt/standards 0.15.1 → 0.17.0

package/src/poller-review-output.ts

@@ -1,20 +1,20 @@
 import { Buffer } from 'node:buffer';
 import { createHash } from 'node:crypto';
-import { isRecord } from './github-settings-parse';
 import {
   assertCleanOutputWorktree,
   commitCountBetween,
   isAncestor,
-  isGitObjectId,
   singleParentOf,
 } from './poller-output-integrity';
-import type { DeferredFinding } from './poller-protocol';
+import type { ReviewThreadResolution } from './poller-protocol';
+import { parseReviewPlanValue } from './poller-review-plan-parse';
 import { runGit } from './poller-workspace';
 
 const REVIEW_OUTPUT_MARKER = '<!-- standards-poller:review-output\n';
 const REVIEW_OUTPUT_END = '\n-->';
 const REVIEW_COMMIT_MARKER = 'standards-poller:review-output';
 const OUTPUT_BRANCH_DIGEST_LENGTH = 16;
+const REVIEW_OUTPUT_PROTOCOL_VERSION = 2;
 
 export type ReviewPublicationPlan = {
   readonly repo: string;
@@ -26,16 +26,9 @@ export type ReviewPublicationPlan = {
   readonly baseSha: string;
   readonly report: string;
   readonly commits: number;
-  readonly deferred: ReadonlyArray<DeferredFinding>;
+  readonly threadsToResolve: ReadonlyArray<ReviewThreadResolution>;
 };
 
-const isDeferredFinding = (value: unknown): value is DeferredFinding =>
-  isRecord(value) &&
-  typeof value.title === 'string' &&
-  value.title.length > 0 &&
-  typeof value.body === 'string' &&
-  value.body.length > 0;
-
 export const reviewPlanMarker = (plan: ReviewPublicationPlan): string =>
   `${REVIEW_OUTPUT_MARKER}${Buffer.from(JSON.stringify(plan)).toString('base64url')}${REVIEW_OUTPUT_END}`;
 
@@ -53,28 +46,7 @@ export const parseReviewPlan = (body: string): ReviewPublicationPlan | null => {
     const raw = JSON.parse(
       Buffer.from(body.slice(encodedStart, end), 'base64url').toString('utf8'),
     ) as unknown;
-    if (
-      !isRecord(raw) ||
-      typeof raw.repo !== 'string' ||
-      typeof raw.prNumber !== 'number' ||
-      typeof raw.approvalId !== 'string' ||
-      typeof raw.approvedHead !== 'string' ||
-      typeof raw.publishedHead !== 'string' ||
-      typeof raw.baseRef !== 'string' ||
-      typeof raw.baseSha !== 'string' ||
-      !isGitObjectId(raw.approvedHead) ||
-      !isGitObjectId(raw.publishedHead) ||
-      !isGitObjectId(raw.baseSha) ||
-      typeof raw.report !== 'string' ||
-      typeof raw.commits !== 'number' ||
-      !Number.isInteger(raw.commits) ||
-      raw.commits < 0 ||
-      !Array.isArray(raw.deferred) ||
-      !raw.deferred.every(isDeferredFinding)
-    ) {
-      return null;
-    }
-    return raw as ReviewPublicationPlan;
+    return parseReviewPlanValue(raw);
   } catch {
     return null;
   }
@@ -89,11 +61,18 @@ export const reviewOutputBranch = (
   const { repo, prNumber, baseSha, approvedHead, approvalId } = identity;
   const generation = createHash('sha256')
     .update(
-      JSON.stringify({ repo, prNumber, baseSha, approvedHead, approvalId }),
+      JSON.stringify({
+        protocol: REVIEW_OUTPUT_PROTOCOL_VERSION,
+        repo,
+        prNumber,
+        baseSha,
+        approvedHead,
+        approvalId,
+      }),
     )
     .digest('hex')
     .slice(0, OUTPUT_BRANCH_DIGEST_LENGTH);
-  return `poller/review-pr-${prNumber}-${generation}`;
+  return `poller/review-v${REVIEW_OUTPUT_PROTOCOL_VERSION}-pr-${prNumber}-${generation}`;
 };
 
 const commitMessage = (plan: ReviewPublicationPlan): string =>

package/src/poller-review-plan-parse.ts

@@ -0,0 +1,94 @@
+import { isRecord } from './github-settings-parse';
+import { isGitObjectId } from './poller-output-integrity';
+import type { ReviewThreadResolution } from './poller-protocol';
+import type { ReviewPublicationPlan } from './poller-review-output';
+
+const PLAN_KEYS = [
+  'approvalId',
+  'approvedHead',
+  'baseRef',
+  'baseSha',
+  'commits',
+  'prNumber',
+  'publishedHead',
+  'repo',
+  'report',
+  'threadsToResolve',
+] as const;
+
+const THREAD_KEYS = ['threadId', 'verificationReply'] as const;
+
+const hasExactKeys = (
+  value: Readonly<Record<string, unknown>>,
+  keys: ReadonlyArray<string>,
+): boolean => {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return (
+    actual.length === expected.length &&
+    actual.every((key, index) => key === expected[index])
+  );
+};
+
+const parseThreadsToResolve = (
+  value: unknown,
+): ReadonlyArray<ReviewThreadResolution> | null => {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const threads: Array<ReviewThreadResolution> = [];
+  const ids = new Set<string>();
+  for (const entry of value) {
+    if (
+      !(isRecord(entry) && hasExactKeys(entry, THREAD_KEYS)) ||
+      typeof entry.threadId !== 'string' ||
+      entry.threadId.length === 0 ||
+      typeof entry.verificationReply !== 'string' ||
+      entry.verificationReply.trim().length === 0 ||
+      ids.has(entry.threadId)
+    ) {
+      return null;
+    }
+    ids.add(entry.threadId);
+    threads.push({
+      threadId: entry.threadId,
+      verificationReply: entry.verificationReply,
+    });
+  }
+  return threads;
+};
+
+export const parseReviewPlanValue = (
+  raw: unknown,
+): ReviewPublicationPlan | null => {
+  const threadsToResolve = isRecord(raw)
+    ? parseThreadsToResolve(raw.threadsToResolve)
+    : null;
+  if (
+    !(isRecord(raw) && hasExactKeys(raw, PLAN_KEYS)) ||
+    typeof raw.repo !== 'string' ||
+    raw.repo.length === 0 ||
+    typeof raw.prNumber !== 'number' ||
+    !Number.isInteger(raw.prNumber) ||
+    raw.prNumber < 1 ||
+    typeof raw.approvalId !== 'string' ||
+    raw.approvalId.length === 0 ||
+    typeof raw.approvedHead !== 'string' ||
+    typeof raw.publishedHead !== 'string' ||
+    typeof raw.baseRef !== 'string' ||
+    raw.baseRef.length === 0 ||
+    typeof raw.baseSha !== 'string' ||
+    !isGitObjectId(raw.approvedHead) ||
+    !isGitObjectId(raw.publishedHead) ||
+    !isGitObjectId(raw.baseSha) ||
+    typeof raw.report !== 'string' ||
+    raw.report.trim().length === 0 ||
+    typeof raw.commits !== 'number' ||
+    !Number.isInteger(raw.commits) ||
+    raw.commits < 0 ||
+    threadsToResolve === null
+  ) {
+    return null;
+  }
+  return { ...raw, threadsToResolve } as ReviewPublicationPlan;
+};

package/src/poller-review-publication.ts

@@ -84,7 +84,7 @@ export const finishReviewedJob = async (options: {
   readonly pr: PullRequest;
   readonly claim: ClaimBinding;
   readonly workDir: string;
-  readonly outcome: ReviewOutcome;
+  readonly outcome: Extract<ReviewOutcome, { readonly status: 'reviewed' }>;
 }): Promise<string> => {
   const { deps, labels, pr, claim, workDir, outcome } = options;
   const commits = commitCount(workDir, pr.headSha);
@@ -110,9 +110,9 @@ export const finishReviewedJob = async (options: {
     publishedHead: headSha(workDir),
     baseRef: pr.baseRef,
     baseSha: pr.baseSha,
-    report: outcome.report ?? '',
+    report: outcome.report,
     commits,
-    deferred: outcome.deferred ?? [],
+    threadsToResolve: outcome.threadsToResolve,
   };
   const outputBranch = outputBranchFor(plan);
   const sealedHead = sealReviewPlan(workDir, plan);

package/src/poller-review-run.ts

@@ -1,11 +1,12 @@
 // One review job: a maintainer-approved draft PR gets a full review-fix
 // cycle — lens fan-out inside the Codex run, fixes as new commits — then the
-// poller posts the report, files deferred findings as issues, and flips the
-// PR to ready. GitHub writes stay in deterministic poller code; the agent
-// never holds credentials.
+// Codex maintains the GitHub review ledger and commits fixes, then the poller
+// verifies and pushes those commits, posts the final report, and flips the PR
+// ready.
 
 import { prRevision } from './poller-approval';
 import { acquireClaim } from './poller-claim';
+import { runCodex } from './poller-codex';
 import { getIssue, type IssueItem } from './poller-github';
 import { getPullRequest } from './poller-github-pulls';
 import { addLabels } from './poller-github-write';
@@ -21,6 +22,7 @@ import {
   REVIEW_FAILED,
   REVIEW_IN_PROGRESS,
 } from './poller-protocol';
+import { reviewEligibility } from './poller-review-eligibility';
 import { executeReviewJob } from './poller-review-execution';
 import {
   readSealedReviewPlan,
@@ -28,6 +30,7 @@ import {
 } from './poller-review-output';
 import { resumeReviewedJob } from './poller-review-publication';
 import { publishReviewPlan, readReviewPlan } from './poller-review-state';
+import { acknowledgeQueuedJob } from './poller-status';
 import { ensureCacheClone, localBranchExists } from './poller-workspace';
 
 const REVIEW_LABELS: JobLabels = {
@@ -50,6 +53,7 @@ export const runReviewJob = async (
   deps: JobDeps,
   prItem: IssueItem,
   allowCodex = true,
+  runAgent: typeof runCodex = runCodex,
 ): Promise<JobResult> => {
   const { config, token, repo } = deps;
   const pr = await getPullRequest(token, repo, prItem.number);
@@ -73,30 +77,15 @@ export const runReviewJob = async (
       ranCodex: false,
     };
   }
-  if (!pr.draft && plan === null) {
-    await failJob(
-      deps,
-      REVIEW_LABELS,
-      pr.number,
-      'automated review requires a draft PR',
-    );
-    return {
-      lines: [`PR #${pr.number}: rejected (not draft)`],
-      ranCodex: false,
-    };
-  }
-  // Fork PRs are out of scope: their head branch lives in a repository the
-  // poller must not push to, and pushing a same-named branch to the base repo
-  // would fake a review. Fail explicitly instead of pretending.
-  if (pr.headRepo !== repo) {
-    await failJob(
-      deps,
-      REVIEW_LABELS,
-      pr.number,
-      `this PR's head branch lives in ${pr.headRepo || 'an unknown repository'}; automated review runs only support same-repository branches`,
-    );
+  const eligibility = reviewEligibility({
+    repo,
+    pr,
+    hasPlan: plan !== null,
+  });
+  if (eligibility.kind === 'rejected') {
+    await failJob(deps, REVIEW_LABELS, pr.number, eligibility.message);
     return {
-      lines: [`PR #${pr.number}: rejected (fork head)`],
+      lines: [`PR #${pr.number}: ${eligibility.result}`],
       ranCodex: false,
     };
   }
@@ -113,6 +102,7 @@ export const runReviewJob = async (
     throw new Error(`sealed output on ${outputBranch} is invalid`);
   }
   if (plan === null && sealed === null && !allowCodex) {
+    await acknowledgeQueuedJob(deps, pr.number, preamble.approval, 'review');
     return {
       lines: [`PR #${pr.number}: waiting for run capacity`],
       ranCodex: false,
@@ -156,5 +146,6 @@ export const runReviewJob = async (
     claim,
     cacheClone,
     answers: preamble.answers,
+    runAgent,
   });
 };

package/src/poller-review-thread-api.ts

@@ -0,0 +1,166 @@
+import { apiError, HTTP_OK, request } from './github-api';
+import { isRecord } from './github-settings-parse';
+
+export type ReviewThreadComment = {
+  readonly body: string;
+  readonly viewerDidAuthor: boolean;
+};
+
+export type ReviewThread = {
+  readonly id: string;
+  readonly repo: string;
+  readonly prNumber: number;
+  readonly isResolved: boolean;
+  readonly creation: ReviewThreadComment | null;
+  readonly viewerAuthoredBodies: ReadonlyArray<string>;
+};
+
+const asRecord = (
+  value: unknown,
+  context: string,
+): Readonly<Record<string, unknown>> => {
+  if (!isRecord(value)) {
+    throw new Error(`${context}: expected an object`);
+  }
+  return value;
+};
+
+const stringField = (
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  context: string,
+): string => {
+  const field = value[key];
+  if (typeof field !== 'string') {
+    throw new Error(`${context}: expected "${key}" to be a string`);
+  }
+  return field;
+};
+
+const booleanField = (
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  context: string,
+): boolean => {
+  const field = value[key];
+  if (typeof field !== 'boolean') {
+    throw new Error(`${context}: expected "${key}" to be a boolean`);
+  }
+  return field;
+};
+
+const numberField = (
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  context: string,
+): number => {
+  const field = value[key];
+  if (typeof field !== 'number') {
+    throw new Error(`${context}: expected "${key}" to be a number`);
+  }
+  return field;
+};
+
+const reviewThreadComment = (
+  value: unknown,
+  context: string,
+): ReviewThreadComment => {
+  const comment = asRecord(value, context);
+  return {
+    body: stringField(comment, 'body', context),
+    viewerDidAuthor: booleanField(comment, 'viewerDidAuthor', context),
+  };
+};
+
+const readThreadPage = async (
+  token: string | null,
+  threadId: string,
+  after: string | null,
+): Promise<{
+  readonly thread: ReviewThread;
+  readonly nextCursor: string | null;
+}> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query:
+      'query($id: ID!, $after: String) { node(id: $id) { ... on PullRequestReviewThread { id isResolved pullRequest { number repository { nameWithOwner } } comments(first: 100, after: $after) { nodes { body viewerDidAuthor } pageInfo { hasNextPage endCursor } } } } }',
+    variables: { id: threadId, after },
+  });
+  if (response.status !== HTTP_OK) {
+    throw new Error(apiError(`read review thread ${threadId}`, response));
+  }
+  const context = `read review thread ${threadId}`;
+  const body = asRecord(response.body, context);
+  if (body.errors !== undefined) {
+    throw new Error(apiError(context, response));
+  }
+  const data = asRecord(body.data, context);
+  const node = asRecord(data.node, context);
+  if (stringField(node, 'id', context) !== threadId) {
+    throw new Error(`${context}: GitHub returned a different node`);
+  }
+  const pullRequest = asRecord(node.pullRequest, context);
+  const repository = asRecord(pullRequest.repository, context);
+  const comments = asRecord(node.comments, context);
+  const pageInfo = asRecord(comments.pageInfo, context);
+  if (!Array.isArray(comments.nodes)) {
+    throw new Error(`${context}: expected thread comments`);
+  }
+  const parsedComments = comments.nodes.map((comment) =>
+    reviewThreadComment(comment, context),
+  );
+  const viewerAuthoredBodies: Array<string> = [];
+  for (const comment of parsedComments) {
+    if (comment.viewerDidAuthor) {
+      viewerAuthoredBodies.push(comment.body);
+    }
+  }
+  const hasNextPage = booleanField(pageInfo, 'hasNextPage', context);
+  const { endCursor } = pageInfo;
+  if (hasNextPage && typeof endCursor !== 'string') {
+    throw new Error(`${context}: expected the next comment cursor`);
+  }
+  return {
+    thread: {
+      id: threadId,
+      repo: stringField(repository, 'nameWithOwner', context),
+      prNumber: numberField(pullRequest, 'number', context),
+      isResolved: booleanField(node, 'isResolved', context),
+      creation: parsedComments[0] ?? null,
+      viewerAuthoredBodies,
+    },
+    nextCursor: hasNextPage ? (endCursor as string) : null,
+  };
+};
+
+export const readReviewThread = async (
+  token: string | null,
+  threadId: string,
+): Promise<ReviewThread> => {
+  let after: string | null = null;
+  let combined: ReviewThread | null = null;
+  const viewerAuthoredBodies: Array<string> = [];
+  do {
+    // biome-ignore lint/performance/noAwaitInLoops: all comment pages are required for replay-safe marker lookup.
+    const page = await readThreadPage(token, threadId, after);
+    if (
+      combined !== null &&
+      (combined.repo !== page.thread.repo ||
+        combined.prNumber !== page.thread.prNumber ||
+        combined.isResolved !== page.thread.isResolved)
+    ) {
+      throw new Error(`read review thread ${threadId}: identity changed`);
+    }
+    if (combined === null) {
+      combined = { ...page.thread, viewerAuthoredBodies };
+    } else if (combined.creation === null && page.thread.creation !== null) {
+      const existing = combined as ReviewThread;
+      combined = { ...existing, creation: page.thread.creation };
+    }
+    viewerAuthoredBodies.push(...page.thread.viewerAuthoredBodies);
+    after = page.nextCursor;
+  } while (after !== null);
+  if (combined === null) {
+    throw new Error(`read review thread ${threadId}: no response`);
+  }
+  return combined;
+};

package/src/poller-review-thread-write.ts

@@ -0,0 +1,64 @@
+import { apiError, HTTP_OK, request } from './github-api';
+import { isRecord } from './github-settings-parse';
+
+const REPLY_MUTATION =
+  // biome-ignore lint/security/noSecrets: a GraphQL mutation string, not a credential.
+  'mutation($id: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $id, body: $body }) { comment { id } } }';
+
+const RESOLVE_MUTATION =
+  'mutation($id: ID!) { resolveReviewThread(input: { threadId: $id }) { thread { id isResolved } } }';
+
+const mutationBody = (
+  operation: 'reply' | 'resolve',
+  threadId: string,
+  response: Awaited<ReturnType<typeof request>>,
+): Readonly<Record<string, unknown>> => {
+  const context = `${operation} review thread ${threadId}`;
+  if (
+    response.status !== HTTP_OK ||
+    !isRecord(response.body) ||
+    response.body.errors !== undefined ||
+    !isRecord(response.body.data)
+  ) {
+    throw new Error(apiError(context, response));
+  }
+  return response.body.data;
+};
+
+export const replyToReviewThread = async (
+  token: string | null,
+  threadId: string,
+  body: string,
+): Promise<void> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query: REPLY_MUTATION,
+    variables: { id: threadId, body },
+  });
+  const data = mutationBody('reply', threadId, response);
+  const payload = data.addPullRequestReviewThreadReply;
+  if (
+    !(isRecord(payload) && isRecord(payload.comment)) ||
+    typeof payload.comment.id !== 'string'
+  ) {
+    throw new Error(apiError(`reply review thread ${threadId}`, response));
+  }
+};
+
+export const resolveReviewThread = async (
+  token: string | null,
+  threadId: string,
+): Promise<void> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query: RESOLVE_MUTATION,
+    variables: { id: threadId },
+  });
+  const data = mutationBody('resolve', threadId, response);
+  const payload = data.resolveReviewThread;
+  if (
+    !(isRecord(payload) && isRecord(payload.thread)) ||
+    payload.thread.id !== threadId ||
+    payload.thread.isResolved !== true
+  ) {
+    throw new Error(apiError(`resolve review thread ${threadId}`, response));
+  }
+};

package/src/poller-review-threads.ts

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import type { ClaimBinding } from './poller-claim';
+import type { PullRequest } from './poller-github-pulls';
+import type { JobDeps } from './poller-job-shared';
+import type { ReviewThreadResolution } from './poller-protocol';
+import type { ReviewPublicationPlan } from './poller-review-output';
+import { validateReviewClaim } from './poller-review-state';
+import {
+  type ReviewThread,
+  readReviewThread,
+} from './poller-review-thread-api';
+import {
+  replyToReviewThread,
+  resolveReviewThread,
+} from './poller-review-thread-write';
+
+const AGENT_REVIEW_THREAD_MARKER =
+  /<!-- standards-poller:review-thread approval=(?<approval>[a-f0-9]{64}) operation=(?:[a-f0-9]{64}) -->/gu;
+
+export const agentReviewThreadMarker = (
+  approvalId: string,
+  operationId: string,
+): string =>
+  `<!-- standards-poller:review-thread approval=${approvalId} operation=${operationId} -->`;
+
+const hasAgentCreationMarker = (body: string, approvalId: string): boolean =>
+  [...body.matchAll(AGENT_REVIEW_THREAD_MARKER)].some(
+    (marker) => marker.groups?.approval === approvalId,
+  );
+
+export const threadResolutionMarker = (
+  plan: ReviewPublicationPlan,
+  resolution: ReviewThreadResolution,
+): string => {
+  const digest = createHash('sha256')
+    .update(
+      JSON.stringify({
+        repo: plan.repo,
+        prNumber: plan.prNumber,
+        approvalId: plan.approvalId,
+        threadId: resolution.threadId,
+        verificationReply: resolution.verificationReply,
+      }),
+    )
+    .digest('hex');
+  return `<!-- standards-poller:thread-resolution approval=${plan.approvalId} operation=${digest} -->`;
+};
+
+const assertThreadTarget = (
+  thread: ReviewThread,
+  plan: ReviewPublicationPlan,
+): void => {
+  if (thread.repo !== plan.repo || thread.prNumber !== plan.prNumber) {
+    throw new Error(
+      `publication blocked: review thread ${thread.id} belongs to ${thread.repo}#${thread.prNumber}`,
+    );
+  }
+  if (
+    thread.creation === null ||
+    !thread.creation.viewerDidAuthor ||
+    !hasAgentCreationMarker(thread.creation.body, plan.approvalId)
+  ) {
+    throw new Error(
+      `publication blocked: review thread ${thread.id} was not created by this approval generation`,
+    );
+  }
+};
+
+export const publishReviewThreadResolutions = async (options: {
+  readonly deps: JobDeps;
+  readonly pr: PullRequest;
+  readonly claim: ClaimBinding;
+  readonly plan: ReviewPublicationPlan;
+}): Promise<void> => {
+  const { deps, pr, claim, plan } = options;
+  for (const resolution of plan.threadsToResolve) {
+    const marker = threadResolutionMarker(plan, resolution);
+    const reply = `${resolution.verificationReply}\n\n${marker}`;
+    // biome-ignore lint/performance/noAwaitInLoops: each thread write has its own immediate claim revalidation.
+    let thread = await readReviewThread(deps.token, resolution.threadId);
+    assertThreadTarget(thread, plan);
+    if (!thread.viewerAuthoredBodies.includes(reply)) {
+      await validateReviewClaim({
+        deps,
+        pr,
+        claim,
+        plan,
+        expectedHead: plan.publishedHead,
+        requireDraft: true,
+      });
+      await replyToReviewThread(deps.token, resolution.threadId, reply);
+    }
+    thread = await readReviewThread(deps.token, resolution.threadId);
+    assertThreadTarget(thread, plan);
+    if (!thread.viewerAuthoredBodies.includes(reply)) {
+      throw new Error(
+        `publication blocked: verification reply missing from review thread ${resolution.threadId}`,
+      );
+    }
+    if (!thread.isResolved) {
+      await validateReviewClaim({
+        deps,
+        pr,
+        claim,
+        plan,
+        expectedHead: plan.publishedHead,
+        requireDraft: true,
+      });
+      await resolveReviewThread(deps.token, resolution.threadId);
+    }
+    thread = await readReviewThread(deps.token, resolution.threadId);
+    assertThreadTarget(thread, plan);
+    if (!thread.isResolved) {
+      throw new Error(
+        `publication blocked: review thread ${resolution.threadId} remained unresolved`,
+      );
+    }
+  }
+};