tools(github): poll-pr-gate.ts v0 — promote prose-jq to executable (5-AI convergent)

[AceHack]

Summary

Closes part 1 of task #355 — the highest-leverage hardening item this session. 5-AI peer-reviewer convergence on 2026-04-30 named the recommendation: promote the inline jq snippets in memory/feedback_amara_poll_gate_not_ending_holding_is_not_status_2026_04_30.md into a tested executable. Full attribution at docs/research/2026-04-30-multi-ai-feedback-packets-this-session.md.

Carved blade from that packet:

"If the loop uses it every tick, it deserves tests."

What's in v0

• tools/github/poll-pr-gate.ts — Bun+TS skeleton with happy-path query
• tools/github/fixtures/clean-armed-auto-merge.json — clean gate + auto-merge-armed shape
• tools/github/fixtures/blocked-by-threads.json — clean-CI + 3 unresolved threads shape
• tools/github/fixtures/status-context-error.json — StatusContext ERROR + EXPECTED states
• tools/github/fixtures/behind-needs-rebase.json — BEHIND mergeStateStatus → rebase action

Output shape

{
  "number": 917,
  "state": "OPEN" | "MERGED" | "CLOSED",
  "gate": "CLEAN" | "BLOCKED" | "DIRTY" | "UNSTABLE" | "UNKNOWN",
  "checks": { "ok": N, "inProgress": N, "pending": N, "failed": N },
  "unresolvedThreads": N,
  "autoMerge": "armed" | "none",
  "mergeCommit": "<sha>" | null,
  "nextAction": "wait-ci" | "fix-failed-checks" | "resolve-threads" | "rebase" | "verify-merge" | "none"
}

Required-check semantics

• Merge-satisfying: SUCCESS, NEUTRAL, SKIPPED
• Blocking: FAILURE, CANCELLED, TIMED_OUT, STARTUP_FAILURE, ACTION_REQUIRED, STALE, ERROR
• Pending: QUEUED, PENDING, IN_PROGRESS, EXPECTED, REQUESTED, WAITING

Exit codes

• 0 — query succeeded, JSON emitted
• 1 — invocation / argument / dependency error (bad args, gh missing, fixture missing, PR ≤ 0)
• 2 — gh CLI returned non-zero (auth, rate-limit, PR not found)
• 3 — gh CLI output couldn't be parsed (truncated, non-JSON)

Verification

Tested live against multiple PRs and offline against 4 fixtures. All cases produce the expected report shape.

Why this matters

Aaron's substrate-IS-product framing (2026-04-30) — executable substrate IS substrate-quality work. The factory's tooling-product deserves the same honest-substrate discipline as the substrate-product. The memory file should stop being the implementation and start pointing to it. Slice 22 of B-0086 TS+Bun migration trajectory.

Follow-ups (queued under task #355)

• Matrix fixture coverage (mixed-rollup, missing-conclusion, pagination edges)
• Test runner integration with existing TS test harness
• Top-of-memory-file pointer addition (after this PR merges)
• Loop integration: replace inline jq calls in the autonomous-loop tick close

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 251a3a7cb1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds an initial Bun+TypeScript implementation of the “poll PR gate” logic used by the autonomous loop, moving the previously-prose/jq approach toward an executable tool with fixture inputs.

Changes:

• Introduces tools/github/poll-pr-gate.ts to query PR state/checks/threads via gh and emit a normalized JSON report.
• Adds two JSON fixtures to support offline iteration of the classification logic.
• Documents intended output shape and required-check conclusion semantics in the script header.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 9 comments.

File	Description
tools/github/poll-pr-gate.ts	New Bun/TS CLI that queries GitHub PR gate signals and emits a JSON report.
tools/github/fixtures/clean-armed-auto-merge.json	Fixture representing a clean-checks + auto-merge-armed PR shape.
tools/github/fixtures/blocked-by-threads.json	Fixture representing a PR blocked by unresolved review threads.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 27e63d6243

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 9 comments.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cc3f4551ef

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ecb4585e6d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Prioritize CLEAN merge state over raw failed-check count

classifyGate marks any PR with checks.failed > 0 as BLOCKED before honoring mergeStateStatus === "CLEAN". GitHub’s MergeStateStatus.CLEAN explicitly means the PR is mergeable even when some commit statuses are non-passing, so this path misclassifies PRs that only have non-required failing checks and drives nextAction into fix-failed-checks unnecessarily. In those cases the loop can keep working a non-blocking failure while the PR is already mergeable.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Report actionable state when gate is BLOCKED

nextAction falls back to "none" whenever a PR is not merged/closed/dirty and has no failed checks, unresolved threads, or pending checks. That creates a dead-end for valid mergeStateStatus: "BLOCKED" cases caused by other protections (e.g., required Copilot review/ruleset gates), where the PR is still unmergeable but this tool reports no next step. In this repo’s documented protection model, that state exists, so returning none here can stall the autonomous loop on still-blocked PRs.

Useful? React with 👍 / 👎.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

[Copilot]

P0: classifyGate can return CLEAN based solely on mergeStateStatus === "CLEAN" even when checks are still pending/in-progress (since checks.inProgress/checks.pending aren’t considered here). That can yield a contradictory report like gate=CLEAN but nextAction=wait-ci. Consider factoring pending/in-progress into the gate classification (or returning UNSTABLE/UNKNOWN until all required checks are terminal+OK).

Suggested change

	if (mergeStateStatus === "BLOCKED") return "BLOCKED";
	if (mergeStateStatus === "BLOCKED") return "BLOCKED";
	// A PR is not clean while required checks are still non-terminal; otherwise
	// we can report gate=CLEAN while nextAction=wait-ci, which is contradictory.
	if (checks.inProgress > 0 || checks.pending > 0) return "UNKNOWN";

[Copilot]

P1: runGhOrExit doesn’t distinguish spawnSync termination-without-exit (result.status === null, possibly with result.signal) from a normal non-zero exit. Right now that path reports gh exited null and exits 2, which hides the real failure mode. Consider mirroring the repo’s common classifySpawnFailure pattern (ENOENT vs signal vs non-zero) and emitting an accurate message + exit code.

[Copilot]

P2: parseArgs (and requireValue) call process.exit(...) directly. Since main is exported, this makes the module hard to test/compose (callers can’t recover from parse errors). Consider having parseArgs return a typed {kind:"ok"|"help"|"error"} result and letting main decide the final exit code/output, consistent with other tools/ scripts.

Suggested change

	function parseArgs(argv: string[]): ParsedArgs {
	const out: ParsedArgs = {
	owner: "Lucent-Financial-Group",
	repo: "Zeta",
	};
	const requireValue = (flag: string, v: string | undefined): string => {
	if (v === undefined || v.startsWith("--")) {
	process.stderr.write(`${flag} requires a value\n`);
	process.exit(1);
	}
	return v;
	};
	for (let i = 0; i < argv.length; i++) {
	const arg = argv[i];
	if (arg === undefined) continue;
	if (arg === "--fixture") {
	out.fixture = requireValue("--fixture", argv[++i]);
	} else if (arg === "--owner") {
	out.owner = requireValue("--owner", argv[++i]);
	} else if (arg === "--repo") {
	out.repo = requireValue("--repo", argv[++i]);
	} else if (/^\d+$/.test(arg)) {
	const parsed = Number.parseInt(arg, 10);
	if (parsed <= 0) {
	process.stderr.write("PR number must be a positive integer\n");
	process.exit(1);
	}
	out.number = parsed;
	} else if (arg === "--help" || arg === "-h") {
	process.stdout.write(
	"Usage: poll-pr-gate.ts <PR_NUMBER> [--owner X] [--repo Y]\n" +
	" poll-pr-gate.ts --fixture path/to/fixture.json\n",
	);
	process.exit(0);
	} else {
	process.stderr.write(`unknown arg: ${arg}\n`);
	process.exit(1);
	}
	}
	return out;
	}
	export function main(argv: string[]): number {
	const args = parseArgs(argv);
	type ParseArgsResult =
	| { kind: "ok"; args: ParsedArgs }
	| { kind: "help"; message: string }
	| { kind: "error"; message: string };
	type RequireValueResult =
	| { kind: "ok"; value: string }
	| { kind: "error"; message: string };
	function parseArgs(argv: string[]): ParseArgsResult {
	const out: ParsedArgs = {
	owner: "Lucent-Financial-Group",
	repo: "Zeta",
	};
	const requireValue = (
	flag: string,
	v: string | undefined,
	): RequireValueResult => {
	if (v === undefined || v.startsWith("--")) {
	return { kind: "error", message: `${flag} requires a value` };
	}
	return { kind: "ok", value: v };
	};
	for (let i = 0; i < argv.length; i++) {
	const arg = argv[i];
	if (arg === undefined) continue;
	if (arg === "--fixture") {
	const fixture = requireValue("--fixture", argv[++i]);
	if (fixture.kind === "error") return fixture;
	out.fixture = fixture.value;
	} else if (arg === "--owner") {
	const owner = requireValue("--owner", argv[++i]);
	if (owner.kind === "error") return owner;
	out.owner = owner.value;
	} else if (arg === "--repo") {
	const repo = requireValue("--repo", argv[++i]);
	if (repo.kind === "error") return repo;
	out.repo = repo.value;
	} else if (/^\d+$/.test(arg)) {
	const parsed = Number.parseInt(arg, 10);
	if (parsed <= 0) {
	return { kind: "error", message: "PR number must be a positive integer" };
	}
	out.number = parsed;
	} else if (arg === "--help" || arg === "-h") {
	return {
	kind: "help",
	message:
	"Usage: poll-pr-gate.ts <PR_NUMBER> [--owner X] [--repo Y]\n" +
	" poll-pr-gate.ts --fixture path/to/fixture.json\n",
	};
	} else {
	return { kind: "error", message: `unknown arg: ${arg}` };
	}
	}
	return { kind: "ok", args: out };
	}
	export function main(argv: string[]): number {
	const parsedArgs = parseArgs(argv);
	if (parsedArgs.kind === "help") {
	process.stdout.write(parsedArgs.message);
	return 0;
	}
	if (parsedArgs.kind === "error") {
	process.stderr.write(`${parsedArgs.message}\n`);
	return 1;
	}
	const args = parsedArgs.args;

[Copilot]

P2: PENDING_STATUSES includes EXPECTED, but StatusContext EXPECTED is normalized in normalizeRollup into status: "PENDING" (and only state carries EXPECTED). Keeping EXPECTED here is dead/ambiguous and suggests a state-vs-status mixup; consider removing it or renaming the sets to make the distinction explicit.

Suggested change

	// StatusContext-class pending state (per Codex P1):
	"EXPECTED",
	// CheckRun non-terminal states (per Codex P1, second pass):
	// Normalized pending statuses plus CheckRun non-terminal states
	// surfaced in `status` (per Codex P1, second pass):