Skip to content

michael-denyer/pstack-claude / plugins/pstack/skills/poteto-mode

poteto-mode

Verified

poteto's agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work. Use for poteto, /poteto-mode, or requests to work in this style.

FileKindSize
SKILL.mdskill md18.2 KB
playbooks/authoring-a-skill.mdmarkdown852 B
playbooks/autonomous-run.mdmarkdown1.9 KB
playbooks/autopilot-full.mdmarkdown8.3 KB
playbooks/autopilot-stack.mdmarkdown1.3 KB
playbooks/babysit.mdmarkdown2.3 KB
playbooks/bug-fix.mdmarkdown4.8 KB
playbooks/eval.mdmarkdown2.8 KB
playbooks/feature.mdmarkdown3.4 KB
playbooks/hillclimb.mdmarkdown4.4 KB
playbooks/investigation.mdmarkdown920 B
playbooks/multi-phase-plan.mdmarkdown1.6 KB
playbooks/opening-a-pr.mdmarkdown1.0 KB
playbooks/pause-safely.mdmarkdown1.9 KB
playbooks/perf-issue.mdmarkdown1.5 KB
playbooks/prototype.mdmarkdown2.1 KB
playbooks/refactoring.mdmarkdown3.3 KB
playbooks/runtime-forensics.mdmarkdown1.3 KB
playbooks/session-pickup.mdmarkdown2.7 KB
playbooks/shipping.mdmarkdown7.2 KB
playbooks/trace-forensics.mdmarkdown1.8 KB
playbooks/visual-parity.mdmarkdown1.2 KB
playbooks/worktree-cleanup.mdmarkdown4.5 KB
references/agents/comment-sicko.mdmarkdown2.9 KB
references/agy-tools.mdmarkdown10.3 KB
references/bugbot-triage.mdmarkdown9.4 KB
references/codex-tools.mdmarkdown13.6 KB
references/copilot-tools.mdmarkdown20.6 KB
references/dsh-tools.mdmarkdown4.8 KB
references/grok.mdmarkdown3.9 KB
references/kimi-tools.mdmarkdown4.6 KB
references/licenses/LICENSEother1.1 KB
references/licenses/LICENSE-cursor-team-kitother1.0 KB
references/licenses/LICENSE-thermosother1.0 KB
references/licenses/NOTICE.mdmarkdown1.9 KB
references/merge-safety.mdmarkdown5.2 KB
references/minimax-tools.mdmarkdown10.2 KB
references/muse-tools.mdmarkdown12.5 KB
references/omp-tools.mdmarkdown6.8 KB
references/opencode-tools.mdmarkdown3.3 KB
references/pi-tools.mdmarkdown23.5 KB
references/resume-storage.mdmarkdown3.6 KB
scripts/.prettierignoreother652 B
scripts/.prettierrc.jsonconfig29 B
scripts/bootstrap.tsscript2.0 KB
scripts/bun.lockother6.5 KB
scripts/check-playbooks.mjsscript6.8 KB
scripts/codex-session-effort.mjsscript3.9 KB
scripts/package.jsonmanifest320 B
scripts/resume.mjsscript7.2 KB
scripts/tsconfig.jsonconfig304 B
scripts/watch-pr/check-suites.tsscript1.9 KB
scripts/watch-pr/cli.port.test.tsscript2.9 KB
scripts/watch-pr/cli.test.tsscript11.2 KB
scripts/watch-pr/cli.tsscript8.7 KB
scripts/watch-pr/deadline.tsscript522 B
scripts/watch-pr/fakes.test-helper.tsscript4.2 KB
scripts/watch-pr/fresh-install.test.tsscript1.3 KB
scripts/watch-pr/github.port.test.tsscript19.7 KB
scripts/watch-pr/github.test.tsscript16.6 KB
scripts/watch-pr/github.tsscript34.7 KB
scripts/watch-pr/head-checks.tsscript1.3 KB
scripts/watch-pr/integrity.test.tsscript24.3 KB
scripts/watch-pr/landing.tsscript3.0 KB
scripts/watch-pr/live-merge-safety.mjsscript7.4 KB
scripts/watch-pr/policy.port.test.tsscript29.0 KB
scripts/watch-pr/policy.test.tsscript14.8 KB
scripts/watch-pr/policy.tsscript29.6 KB
scripts/watch-pr/render.tsscript9.6 KB
scripts/watch-pr/ship-prexecutablescript220 B
scripts/watch-pr/shipping-cli.test.tsscript5.3 KB
scripts/watch-pr/shipping-cli.tsscript2.3 KB
scripts/watch-pr/shipping.test-helper.tsscript2.1 KB
scripts/watch-pr/shipping.test.tsscript11.0 KB
scripts/watch-pr/shipping.tsscript6.7 KB
scripts/watch-pr/transport.test.tsscript15.2 KB
scripts/watch-pr/tsconfig.jsonconfig270 B
scripts/watch-pr/types.compile.tsscript2.7 KB
scripts/watch-pr/types.tsscript15.0 KB
scripts/watch-pr/watch-prexecutablescript211 B
scripts/watch-pr/wrapper.test.tsscript587 B
scripts/worktree-audit.mjsexecutablescript22.4 KB
worker.mdmarkdown1.3 KB

scripts/watch-pr/policy.port.test.ts

View on GitHub
import { describe, expect, it } from "bun:test";
import { WatchDeadline } from "./deadline.ts";
import {
  classifyPr,
  noChecksConfirmer,
  readSnapshot,
  runQueued,
  runSimple,
  selectTierMajorStackDecision,
} from "./policy.ts";
import { fakeReader, failedCheck, pendingCheck } from "./fakes.test-helper.ts";
import { unsettledSuiteChecks } from "./github.ts";
import type {
  GitHubReader,
  NonEmpty,
  PollingOptions,
  PrContext,
  ProgressVerdict,
} from "./types.ts";
import { parsePrNumber } from "./types.ts";

const context = (number: number): PrContext => ({
  owner: "owner",
  repo: "repo",
  number: parsePrNumber(number),
});
const options = {
  interval: 10,
  sweepInterval: 300,
  timeout: 0,
  maxQueryErrors: 5,
  allowDraft: false,
} satisfies PollingOptions;

describe("review gate", () => {
  it("blocks on a required review instead of reporting a blocked PR ready", async () => {
    const snapshot = await readSnapshot({
      reader: fakeReader({
        facts: {
          reviewDecision: "REVIEW_REQUIRED",
          mergeStateStatus: "BLOCKED",
        },
      }),
      context: context(23),
      pendingHistory: "omit",
      allowDraft: false,
    });
    expect(classifyPr(snapshot)).toEqual({
      kind: "blocker",
      blocker: {
        kind: "merge-gate",
        pr: context(23),
        reason: "review-required",
      },
    });
    expect(
      selectTierMajorStackDecision([snapshot] as NonEmpty<typeof snapshot>)
    ).toMatchObject({
      kind: "blocker",
      blocker: { kind: "merge-gate", reason: "review-required" },
    });
  });

  it("blocks when branch protection holds an approved PR with clean CI", async () => {
    const snapshot = await readSnapshot({
      reader: fakeReader({ facts: { mergeStateStatus: "BLOCKED" } }),
      context: context(24),
      pendingHistory: "omit",
      allowDraft: false,
    });
    expect(classifyPr(snapshot)).toMatchObject({
      kind: "blocker",
      blocker: { kind: "merge-gate", reason: "merge-blocked" },
    });
  });

  it("waits for pending checks before reporting the review gate", async () => {
    const snapshot = await readSnapshot({
      reader: fakeReader({
        facts: {
          reviewDecision: "REVIEW_REQUIRED",
          mergeStateStatus: "BLOCKED",
        },
        fastPath: { kind: "checks", checks: [pendingCheck()] },
      }),
      context: context(26),
      pendingHistory: "omit",
      allowDraft: false,
    });
    expect(classifyPr(snapshot)).toMatchObject({ kind: "waiting" });
  });

  it("still reports changes requested as a merge-gate blocker", async () => {
    const snapshot = await readSnapshot({
      reader: fakeReader({
        facts: {
          reviewDecision: "CHANGES_REQUESTED",
          mergeStateStatus: "BLOCKED",
        },
      }),
      context: context(25),
      pendingHistory: "omit",
      allowDraft: false,
    });
    expect(classifyPr(snapshot)).toMatchObject({
      kind: "blocker",
      blocker: { kind: "merge-gate", reason: "changes-requested" },
    });
  });
});

describe("facts that change while the snapshot is read", () => {
  const read = (options: Parameters<typeof fakeReader>[0]) =>
    readSnapshot({
      reader: fakeReader(options),
      context: context(29),
      pendingHistory: "include",
      allowDraft: false,
    });

  it("retries instead of reporting a merge gate the checks read has already cleared", async () => {
    await expect(
      read({
        facts: { mergeStateStatus: "BLOCKED" },
        factsOnReread: { mergeStateStatus: "CLEAN" },
      })
    ).rejects.toMatchObject({
      failure: { kind: "snapshot-changed", retryable: true },
    });
  });

  it("retries instead of reporting ready when a review lands after the facts read", async () => {
    for (const factsOnReread of [
      { reviewDecision: "CHANGES_REQUESTED" },
      { mergeable: "CONFLICTING" },
      { mergeable: "UNKNOWN" },
      { isDraft: true },
    ] as const)
      await expect(read({ factsOnReread })).rejects.toMatchObject({
        failure: { kind: "snapshot-changed", retryable: true },
      });
  });

  it("retries when the PR closes, merges, or renames its head branch between the two reads", async () => {
    for (const factsOnReread of [
      { state: "CLOSED" },
      { mergedAt: "2026-07-26T00:00:00Z" },
      { headRefName: "renamed" },
    ] as const)
      await expect(read({ factsOnReread })).rejects.toMatchObject({
        failure: { kind: "snapshot-changed", retryable: true },
      });
  });

  it("keeps an unknown first read when GitHub computes mergeability before the re-read", async () => {
    const unknown = {
      mergeable: "UNKNOWN",
      mergeStateStatus: "UNKNOWN",
    } as const;
    expect(
      await read({
        facts: unknown,
        factsOnReread: { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" },
      })
    ).toMatchObject({ kind: "open", facts: unknown });
    await expect(
      read({
        facts: unknown,
        factsOnReread: { reviewDecision: "CHANGES_REQUESTED" },
      })
    ).rejects.toMatchObject({ failure: { kind: "snapshot-changed" } });
  });
});

const ticking = (onSleep = () => {}) => {
  let now = 0;
  return {
    now: () => now,
    async sleep(seconds: number) {
      now += seconds;
      // A wait that never ends would spin on this clock without yielding to
      // the test runner's own timeout.
      if (now > 3600) throw new Error("no verdict within an hour of polling");
      onSleep();
    },
  };
};
const dependencies = (
  reader: GitHubReader,
  clock: { now: () => number; sleep: (seconds: number) => Promise<void> },
  emitted: ProgressVerdict[],
  timeout = 0
) => ({
  reader,
  emit: (verdict: ProgressVerdict) => {
    emitted.push(verdict);
  },
  clock: { ...clock, observedAt: () => "2026-07-26T00:00:00.000Z" },
  deadline: new WatchDeadline(timeout, clock.now),
});
const kinds = (emitted: readonly ProgressVerdict[]) =>
  emitted.map((verdict) =>
    verdict.kind === "WAITING"
      ? `${verdict.kind}:${verdict.reason.kind}`
      : verdict.kind
  );

describe("mergeability", () => {
  const unknown = {
    mergeable: "UNKNOWN",
    mergeStateStatus: "UNKNOWN",
  } as const;
  const read = (options: Parameters<typeof fakeReader>[0]) =>
    readSnapshot({
      reader: fakeReader(options),
      context: context(27),
      pendingHistory: "include",
      allowDraft: false,
    });
  // One query error ends the run, so a wait that spent the budget would exit 7.
  const watch = async (
    reader: GitHubReader,
    polling: Partial<PollingOptions> = {},
    statusOnly = false
  ) => {
    const clock = ticking();
    const emitted: ProgressVerdict[] = [];
    const verdict = await runSimple({
      dependencies: dependencies(reader, clock, emitted, polling.timeout),
      contexts: [context(27)],
      mode: "single",
      statusOnly,
      options: { ...options, maxQueryErrors: 1, ...polling },
    });
    return { verdict, emitted: kinds(emitted), elapsed: clock.now() };
  };

  it("waits while GitHub has not computed mergeability instead of reporting ready", async () => {
    for (const facts of [
      { mergeable: "UNKNOWN" },
      { mergeStateStatus: "UNKNOWN" },
    ] as const) {
      const snapshot = await read({ facts });
      const waiting = {
        kind: "waiting",
        frontier: context(27),
        reason: { kind: "mergeability-unknown" },
      } as const;
      expect(classifyPr(snapshot)).toEqual(waiting);
      expect(selectTierMajorStackDecision([snapshot])).toEqual(waiting);
    }
  });

  it("re-polls at the interval after an unknown first read, without spending the query-error budget", async () => {
    const { verdict, emitted, elapsed } = await watch(
      fakeReader({
        facts: unknown,
        factsOnReread: { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" },
      })
    );
    expect(emitted).toEqual(["WAITING:mergeability-unknown"]);
    expect(elapsed).toBe(options.interval);
    expect(verdict).toMatchObject({ kind: "READY", exitCode: 0 });
  });

  it("times out at the caller's deadline when GitHub never computes it", async () => {
    const { verdict, emitted, elapsed } = await watch(
      fakeReader({ facts: unknown }),
      { timeout: 25 }
    );
    expect(emitted).toEqual([
      "WAITING:mergeability-unknown",
      "WAITING:mergeability-unknown",
      "WAITING:mergeability-unknown",
    ]);
    expect(elapsed).toBe(25);
    expect(verdict).toMatchObject({
      kind: "TIMEOUT",
      exitCode: 5,
      reason: { kind: "mergeability-unknown" },
    });
  });

  it("reports an unknown row on a status-only pass and exits 0 without waiting", async () => {
    const { verdict, emitted, elapsed } = await watch(
      fakeReader({ facts: unknown }),
      {},
      true
    );
    expect(emitted).toEqual([]);
    expect(elapsed).toBe(0);
    expect(verdict).toMatchObject({
      kind: "STATUS",
      exitCode: 0,
      rows: [{ kind: "open", facts: unknown, ci: { kind: "ci-clean" } }],
    });
  });

  it("still stops at once on a blocker that does not depend on mergeability", async () => {
    const thread = {
      id: "thread",
      firstComment: null,
      isBugbot: false,
      bugbotReviewPasses: 0,
    };
    const cases = [
      [{ threads: [thread] }, { kind: "review-threads" }],
      [
        {
          fastPath: { kind: "checks", checks: [failedCheck()] },
          commitRollups: [{ oid: "head", state: "FAILURE" }],
        },
        { kind: "failing-checks" },
      ],
      [
        { facts: { ...unknown, reviewDecision: "CHANGES_REQUESTED" } },
        { kind: "merge-gate", reason: "changes-requested" },
      ],
    ] as const;
    for (const [overrides, blocker] of cases)
      expect(
        classifyPr(await read({ facts: unknown, ...overrides }))
      ).toMatchObject({ kind: "blocker", blocker });
  });

  it("defers a required review, and names pending checks first, while mergeability is unknown", async () => {
    expect(
      classifyPr(
        await read({ facts: { ...unknown, reviewDecision: "REVIEW_REQUIRED" } })
      )
    ).toMatchObject({
      kind: "waiting",
      reason: { kind: "mergeability-unknown" },
    });
    expect(
      classifyPr(
        await read({
          facts: unknown,
          fastPath: { kind: "checks", checks: [pendingCheck()] },
        })
      )
    ).toMatchObject({ kind: "waiting", reason: { kind: "pending-checks" } });
  });

  it("does not report a queued frontier blocker-free while its mergeability is unknown", async () => {
    let sleeps = 0;
    const emitted: ProgressVerdict[] = [];
    const running = runQueued({
      dependencies: dependencies(
        fakeReader({ facts: unknown }),
        ticking(() => {
          if (++sleeps === 2) throw new Error("stop after two polls");
        }),
        emitted
      ),
      contexts: [context(27)],
      options,
    });
    await expect(running).rejects.toThrow("stop after two polls");
    expect(kinds(emitted)).toEqual([
      "QUEUE",
      "STATUS",
      "WAITING:mergeability-unknown",
    ]);
  });

  it("gates a branch that is behind its base instead of reporting it ready", async () => {
    const snapshot = await readSnapshot({
      reader: fakeReader({ facts: { mergeStateStatus: "BEHIND" } }),
      context: context(28),
      pendingHistory: "include",
      allowDraft: false,
    });
    expect(classifyPr(snapshot)).toEqual({
      kind: "blocker",
      blocker: { kind: "merge-gate", pr: context(28), reason: "behind-base" },
    });
  });

  it("stops at once on a branch behind its base, without waiting for checks that are pending or unreported", async () => {
    for (const checks of [
      { fastPath: { kind: "checks", checks: [pendingCheck()] } },
      {
        fastPath: { kind: "none-reported" },
        rollupPages: [{ kind: "no-rollup" }],
        commitRollups: [{ oid: "head", state: null }],
      },
    ] as const)
      expect(
        classifyPr(
          await read({ facts: { mergeStateStatus: "BEHIND" }, ...checks })
        )
      ).toEqual({
        kind: "blocker",
        blocker: { kind: "merge-gate", pr: context(27), reason: "behind-base" },
      });
  });

  it("reports requested changes before a behind base, and a behind base before a required review", async () => {
    for (const [reviewDecision, reason] of [
      ["CHANGES_REQUESTED", "changes-requested"],
      ["REVIEW_REQUIRED", "behind-base"],
    ] as const)
      expect(
        classifyPr(
          await read({
            facts: { mergeStateStatus: "BEHIND", reviewDecision },
            fastPath: { kind: "checks", checks: [pendingCheck()] },
          })
        )
      ).toMatchObject({ kind: "blocker", blocker: { reason } });
  });
});

describe("a PR with no checks configured", () => {
  const noChecks = {
    fastPath: { kind: "none-reported" },
    rollupPages: [{ kind: "no-rollup" }],
    commitRollups: [{ oid: "head", state: null }],
  } as const;
  const read = (
    overrides: Parameters<typeof fakeReader>[0] = {},
    confirmNoChecks = () => true
  ) =>
    readSnapshot({
      reader: fakeReader({ ...noChecks, ...overrides }),
      context: context(30),
      pendingHistory: "omit",
      allowDraft: false,
      confirmNoChecks,
    });
  const run = (...args: Parameters<typeof dependencies>) =>
    runSimple({
      dependencies: dependencies(...args),
      contexts: [context(30)],
      mode: "single",
      statusOnly: false,
      options,
    });
  // The suite polls every 10 seconds, so the 60 second floor is six polls.
  const sixPolls = (...perPoll: string[]) =>
    Array.from({ length: 6 }, () => perPoll).flat();

  it("is ready once the no-checks reading is confirmed and GitHub reports it mergeable", async () => {
    const snapshot = await read({ facts: { reviewDecision: null } });
    expect(classifyPr(snapshot)).toMatchObject({
      kind: "ready",
      pr: { proof: { ci: { kind: "ci-none" } } },
    });
  });

  it("waits on a first sighting instead of reporting ready or a merge gate", async () => {
    for (const facts of [
      { reviewDecision: null },
      { mergeStateStatus: "BLOCKED" },
      { reviewDecision: "REVIEW_REQUIRED" },
    ] as const) {
      const snapshot = await read({ facts }, () => false);
      expect(snapshot).toMatchObject({
        kind: "open",
        ci: { kind: "ci-unreported" },
      });
      expect(classifyPr(snapshot)).toEqual({
        kind: "waiting",
        frontier: context(30),
        reason: { kind: "checks-unreported" },
      });
    }
  });

  it("confirms no checks only once the same head has shown none for 60 seconds", () => {
    let now = 0;
    const confirm = noChecksConfirmer({ now: () => now });
    const head = { context: context(30), headRefOid: "head" };
    expect(confirm(head)).toBe(false);
    now = 59;
    expect(confirm(head)).toBe(false);
    now = 60;
    expect(confirm(head)).toBe(true);
    expect(confirm({ ...head, headRefOid: "pushed" })).toBe(false);
    now = 119;
    expect(confirm({ ...head, headRefOid: "pushed" })).toBe(false);
    now = 120;
    expect(confirm({ ...head, headRefOid: "pushed" })).toBe(true);
  });

  it("times each PR from its own first sighting, not from another PR's", () => {
    let now = 0;
    const confirm = noChecksConfirmer({ now: () => now });
    const first = { context: context(30), headRefOid: "head" };
    const second = { context: context(31), headRefOid: "head" };
    expect(confirm(first)).toBe(false);
    now = 60;
    expect(confirm(second)).toBe(false);
    expect(confirm(first)).toBe(true);
    now = 120;
    expect(confirm(second)).toBe(true);
  });

  it("reads no checks as unreported when the caller supplies no confirmation", async () => {
    expect(
      await readSnapshot({
        reader: fakeReader(noChecks),
        context: context(30),
        pendingHistory: "omit",
        allowDraft: false,
      })
    ).toMatchObject({ kind: "open", ci: { kind: "ci-unreported" } });
  });

  it("reports a repository with no CI ready 60 seconds after the first sighting, however short the interval", async () => {
    const clock = ticking();
    const emitted: ProgressVerdict[] = [];
    const verdict = await run(
      fakeReader({ ...noChecks, facts: { reviewDecision: null } }),
      clock,
      emitted
    );
    expect(kinds(emitted)).toEqual(sixPolls("WAITING:checks-unreported"));
    expect(clock.now()).toBe(60);
    expect(verdict).toMatchObject({
      kind: "READY",
      scope: { pr: { proof: { ci: { kind: "ci-none" } } } },
    });
  });

  it("stops at the merge gate only once a blocked PR has shown no checks for 60 seconds", async () => {
    const clock = ticking();
    const emitted: ProgressVerdict[] = [];
    const verdict = await run(
      fakeReader({
        ...noChecks,
        facts: { mergeStateStatus: "BLOCKED", reviewDecision: null },
      }),
      clock,
      emitted
    );
    expect(kinds(emitted)).toEqual(sixPolls("WAITING:checks-unreported"));
    expect(clock.now()).toBe(60);
    expect(verdict).toMatchObject({
      kind: "BLOCKER",
      exitCode: 6,
      blocker: { kind: "merge-gate", reason: "merge-blocked" },
    });
  });

  it("waits through a first sighting and honours checks that register on the next poll", async () => {
    const base = fakeReader({
      ...noChecks,
      facts: { mergeStateStatus: "BLOCKED", reviewDecision: null },
    });
    let polls = 0;
    const reader = {
      ...base,
      async checksFastPath() {
        polls += 1;
        return polls === 1
          ? { kind: "none-reported" as const }
          : { kind: "checks" as const, checks: [pendingCheck("required-ci")] };
      },
    } satisfies GitHubReader;
    let sleeps = 0;
    const emitted: ProgressVerdict[] = [];
    const running = run(
      reader,
      ticking(() => {
        if (++sleeps === 2) throw new Error("stop after two polls");
      }),
      emitted
    );
    await expect(running).rejects.toThrow("stop after two polls");
    expect(kinds(emitted)).toEqual([
      "WAITING:checks-unreported",
      "WAITING:pending-checks",
    ]);
  });

  it("times out unconfirmed when the deadline is shorter than the interval or than the 60 seconds", async () => {
    for (const [timeout, polls] of [
      [options.interval / 2, 1],
      [30, 3],
    ] as const) {
      const emitted: ProgressVerdict[] = [];
      const verdict = await run(
        fakeReader({ ...noChecks, facts: { reviewDecision: null } }),
        ticking(),
        emitted,
        timeout
      );
      expect(kinds(emitted)).toEqual(
        Array.from({ length: polls }, () => "WAITING:checks-unreported")
      );
      expect(verdict).toMatchObject({
        kind: "TIMEOUT",
        exitCode: 5,
        reason: { kind: "checks-unreported" },
      });
    }
  });

  it("confirms each PR of a stack on its own sightings", async () => {
    const clock = ticking();
    const emitted: ProgressVerdict[] = [];
    const verdict = await runSimple({
      dependencies: dependencies(
        fakeReader({ ...noChecks, facts: { reviewDecision: null } }),
        clock,
        emitted
      ),
      contexts: [context(30), context(31)],
      mode: "stack",
      statusOnly: false,
      options,
    });
    expect(kinds(emitted)).toEqual([
      ...sixPolls("STATUS", "WAITING:checks-unreported"),
      "STATUS",
    ]);
    expect(clock.now()).toBe(60);
    expect(verdict).toMatchObject({
      kind: "READY",
      scope: {
        kind: "stack",
        prs: [
          { context: context(30), proof: { ci: { kind: "ci-none" } } },
          { context: context(31), proof: { ci: { kind: "ci-none" } } },
        ],
      },
    });
  });

  it("holds a queued frontier for the 60 seconds before reporting it blocker-free", async () => {
    const emitted: ProgressVerdict[] = [];
    const emittedAt: number[] = [];
    const clock = ticking(() => {
      if (clock.now() > 60) throw new Error("stop after the confirmation");
    });
    const queued = dependencies(
      fakeReader({ ...noChecks, facts: { reviewDecision: null } }),
      clock,
      emitted
    );
    const running = runQueued({
      dependencies: {
        ...queued,
        emit(verdict) {
          emittedAt.push(clock.now());
          queued.emit(verdict);
        },
      },
      contexts: [context(30)],
      options,
    });
    await expect(running).rejects.toThrow("stop after the confirmation");
    expect(kinds(emitted)).toEqual([
      "QUEUE",
      "STATUS",
      "WAITING:checks-unreported",
      "WAITING:merge-queue",
    ]);
    expect(emittedAt).toEqual([0, 0, 0, 60]);
  });

  it("still stops on conflicts, review threads, and merge gates", async () => {
    const thread = {
      id: "thread",
      firstComment: null,
      isBugbot: false,
      bugbotReviewPasses: 0,
    };
    const cases = [
      [{ facts: { mergeable: "CONFLICTING" } }, { kind: "merge-conflicts" }],
      [{ threads: [thread] }, { kind: "review-threads" }],
      [
        { facts: { reviewDecision: "REVIEW_REQUIRED" } },
        { kind: "merge-gate", reason: "review-required" },
      ],
      [
        { facts: { mergeStateStatus: "BLOCKED" } },
        { kind: "merge-gate", reason: "merge-blocked" },
      ],
      [
        { facts: { isDraft: true } },
        { kind: "merge-gate", reason: "draft-pr" },
      ],
    ] as const;
    for (const [overrides, blocker] of cases)
      expect(classifyPr(await read(overrides))).toMatchObject({
        kind: "blocker",
        blocker,
      });
  });

  it("fails closed while the head may not have reported yet", async () => {
    const unsettled = [
      {
        commitRollups: [
          { oid: "earlier", state: "SUCCESS" },
          { oid: "head", state: null },
        ],
      },
      { commitRollups: [{ oid: "head", state: "PENDING" }] },
    ] as const;
    for (const overrides of unsettled)
      await expect(read(overrides)).rejects.toMatchObject({
        failure: { kind: "checks-unavailable", retryable: true },
      });
  });
});

describe("check suites that no check read shows", () => {
  const gated = {
    source: "check-suites",
    kind: "failed",
    name: "GitHub Actions check suite",
    reportedState: "ACTION_REQUIRED",
    description:
      "waits for maintainer approval to run; approve the workflows on the pull request",
    link: "",
    workflow: "",
  } as const;
  const noChecks = {
    fastPath: { kind: "none-reported" },
    rollupPages: [{ kind: "no-rollup" }],
    commitRollups: [{ oid: "head", state: null }],
  } as const;
  const read = (options: Parameters<typeof fakeReader>[0]) =>
    readSnapshot({
      reader: fakeReader(options),
      context: context(40),
      pendingHistory: "include",
      allowDraft: false,
      confirmNoChecks: () => true,
    });

  it("blocks on approval-gated Actions beside another app's passing check", async () => {
    const snapshot = await read({ unsettledSuites: [gated] });
    expect(snapshot).toMatchObject({
      kind: "open",
      ci: { kind: "ci-failing", source: "gh-pr-checks", failed: [gated] },
    });
    expect(classifyPr(snapshot)).toMatchObject({
      kind: "blocker",
      blocker: { kind: "failing-checks" },
    });
  });

  it("blocks on approval-gated Actions when no check is reported", async () => {
    const snapshot = await read({ ...noChecks, unsettledSuites: [gated] });
    expect(snapshot).toMatchObject({
      kind: "open",
      ci: { kind: "ci-failing", source: "check-suites", failed: [gated] },
    });
  });

  it("waits on an Actions suite that has not started its runs", async () => {
    const queued = {
      ...gated,
      kind: "pending",
      reportedState: "QUEUED",
      description: "has not finished",
    } as const;
    for (const options of [{}, noChecks])
      expect(
        await read({ ...options, unsettledSuites: [queued] })
      ).toMatchObject({ ci: { kind: "ci-pending", pending: [queued] } });
  });

  it("keeps clean CI and no CI when the head has no unsettled suite", async () => {
    expect(await read({ unsettledSuites: [] })).toMatchObject({
      ci: { kind: "ci-clean" },
    });
    expect(await read({ ...noChecks, unsettledSuites: [] })).toMatchObject({
      ci: { kind: "ci-none" },
    });
  });

  it("reads suites while review threads are outstanding and rereads facts after both", async () => {
    const reader = fakeReader();
    const threads = Promise.withResolvers<void>();
    reader.reviewThreadPage = async () => {
      await threads.promise;
      return { threads: [], endCursor: null };
    };
    const snapshot = readSnapshot({
      reader,
      context: context(40),
      pendingHistory: "include",
      allowDraft: false,
    });
    await new Promise<void>((resolve) => setImmediate(resolve));
    const beforeRelease = [...reader.calls];
    threads.resolve();
    await snapshot;
    expect(beforeRelease).toContain("unsettledSuites:head:reported");
    expect(beforeRelease.filter((call) => call === "pullRequest")).toHaveLength(
      1
    );
    expect(reader.calls.at(-1)).toBe("pullRequest");
  });

  it("reads the head's suites only when no check has failed or is pending", async () => {
    const suiteReads = async (options: Parameters<typeof fakeReader>[0]) => {
      const reader = fakeReader(options);
      await readSnapshot({
        reader,
        context: context(40),
        pendingHistory: "include",
        allowDraft: false,
      });
      return reader.calls.filter((call) => call.startsWith("unsettledSuites"));
    };
    expect(await suiteReads({})).toEqual(["unsettledSuites:head:reported"]);
    expect(await suiteReads(noChecks)).toEqual([
      "unsettledSuites:head:no-checks",
    ]);
    for (const check of [pendingCheck(), failedCheck()])
      expect(
        await suiteReads({ fastPath: { kind: "checks", checks: [check] } })
      ).toEqual([]);
  });
});

describe("apps named with --expect-app", () => {
  const queuedSuite = (slug: string, name: string) => ({
    head_sha: "head",
    status: "queued",
    conclusion: null,
    app: { slug, name },
    latest_check_runs_count: 0,
  });
  const azure = queuedSuite("azure-pipelines", "Azure Pipelines");
  const noChecks = {
    fastPath: { kind: "none-reported" },
    rollupPages: [{ kind: "no-rollup" }],
    commitRollups: [{ oid: "head", state: null }],
  } as const;
  // The suite read goes through the real parser, so the slugs travel from
  // the polling options to the classification.
  const headWith = (
    reported: Parameters<typeof fakeReader>[0],
    ...suites: unknown[]
  ): GitHubReader => {
    const reader = fakeReader({ ...reported, facts: { reviewDecision: null } });
    reader.unsettledSuites = async (_context, head, checksRead, expectedApps) =>
      unsettledSuiteChecks(
        [{ total_count: suites.length, check_suites: suites }],
        head,
        checksRead,
        expectedApps
      );
    return reader;
  };
  const watch = async (
    reader: GitHubReader,
    expectedApps?: readonly string[]
  ) => {
    const emitted: ProgressVerdict[] = [];
    const verdict = await runSimple({
      dependencies: dependencies(reader, ticking(), emitted, 120),
      contexts: [context(50)],
      mode: "single",
      statusOnly: false,
      options: { ...options, expectedApps },
    });
    return { verdict, emitted: kinds(emitted) };
  };

  it("waits on a named app's queued suite with no runs, with or without another app's check", async () => {
    for (const reported of [{}, noChecks]) {
      const { verdict, emitted } = await watch(headWith(reported, azure), [
        "azure-pipelines",
      ]);
      expect(new Set(emitted)).toEqual(new Set(["WAITING:pending-checks"]));
      expect(verdict).toMatchObject({
        kind: "TIMEOUT",
        exitCode: 5,
        reason: { kind: "pending-checks" },
      });
    }
  });

  it("waits on a named app's queued suite in a queued stack too", async () => {
    const waits = async (expectedApps?: readonly string[]) => {
      const emitted: ProgressVerdict[] = [];
      await runQueued({
        dependencies: dependencies(
          headWith({}, azure),
          ticking(),
          emitted,
          120
        ),
        contexts: [context(50)],
        options: { ...options, expectedApps },
      });
      return kinds(emitted);
    };
    expect(await waits(["azure-pipelines"])).toContain(
      "WAITING:pending-checks"
    );
    expect(await waits()).not.toContain("WAITING:pending-checks");
  });

  it("names each app whose suite it did not count in the ready proof", async () => {
    const claude = queuedSuite("claude", "Claude");
    for (const [reported, ci] of [
      [{}, "ci-clean"],
      [noChecks, "ci-none"],
    ] as const) {
      expect(
        (await watch(headWith(reported, azure, claude))).verdict
      ).toMatchObject({
        kind: "READY",
        scope: {
          pr: {
            proof: {
              ci: {
                kind: ci,
                queuedWithoutRuns: [
                  { name: "Azure Pipelines", slug: "azure-pipelines" },
                  { name: "Claude", slug: "claude" },
                ],
              },
            },
          },
        },
      });
      expect(
        (await watch(headWith(reported, claude), ["azure-pipelines"])).verdict
      ).toMatchObject({
        kind: "READY",
        scope: {
          pr: {
            proof: {
              ci: {
                kind: ci,
                queuedWithoutRuns: [{ name: "Claude", slug: "claude" }],
              },
            },
          },
        },
      });
    }
  });
});
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall