@codedrifters/configulator 0.0.350 → 0.0.351

package/lib/index.mjs

@@ -17445,12 +17445,18 @@ var pnpmBundle = {
 var DEFAULT_PATHS_EXEMPT_FROM_SIZE = [
   "docs/**"
 ];
+var DEFAULT_REQUIRED_WORKFLOWS = [];
 function resolvePrReviewPolicy(config) {
   const pathsExemptFromSize = config?.autoMerge?.pathsExemptFromSize ?? DEFAULT_PATHS_EXEMPT_FROM_SIZE;
+  const requiredWorkflows = config?.ciVerification?.requiredWorkflows ?? DEFAULT_REQUIRED_WORKFLOWS;
   assertValidPathsExemptFromSize(pathsExemptFromSize);
+  assertValidRequiredWorkflows(requiredWorkflows);
   return {
     autoMerge: {
       pathsExemptFromSize: [...pathsExemptFromSize]
+    },
+    ciVerification: {
+      requiredWorkflows: [...requiredWorkflows]
     }
   };
 }
@@ -17466,6 +17472,15 @@ function assertValidPathsExemptFromSize(paths) {
     }
   }
 }
+function assertValidRequiredWorkflows(workflows) {
+  for (const workflow of workflows) {
+    if (typeof workflow !== "string" || workflow.trim().length === 0) {
+      throw new Error(
+        "prReviewPolicy.ciVerification.requiredWorkflows entries must be non-empty strings"
+      );
+    }
+  }
+}
 
 // src/agent/bundles/pr-review.ts
 var prReviewerSubAgent = {
@@ -17507,6 +17522,125 @@ var prReviewerSubAgent = {
     "",
     "---",
     "",
+    "## CI Verification (primary read + Actions-runs fallback)",
+    "",
+    "Every CI-status decision in this agent \u2014 the Phase 1.5 eligibility",
+    "filter, the Phase 3 checklist, the Phase 4 merge gate, the Phase 4",
+    "step (h) re-enable condition, and the Phase 4.5 sticky `CI status`",
+    "field \u2014 resolves CI through the procedure below. It yields one of",
+    "three verdicts: **green** (every required check succeeded),",
+    "**pending** (no failures, but at least one required check is still",
+    "running or queued), or **red** (at least one required check",
+    "failed). Never enable auto-merge unless the verdict is **green**.",
+    "",
+    "### Step 1: Primary read \u2014 check-runs / statusCheckRollup",
+    "",
+    "Read CI from the GitHub check-runs rollup, the canonical source",
+    "GitHub itself uses to gate branch protection:",
+    "",
+    "```bash",
+    "gh pr checks <pr-number>",
+    "# equivalently, the rollup field:",
+    "gh pr view <pr-number> --json statusCheckRollup",
+    "```",
+    "",
+    "This read aggregates **every** check context \u2014 GitHub Actions,",
+    "third-party CI, GitHub Apps, and commit statuses. When it returns",
+    "one or more readable contexts, it is authoritative: map each",
+    "required context's conclusion with the table in Step 4 and do",
+    "**not** fall back. It is strictly more complete than the",
+    "Actions-runs view in Step 3.",
+    "",
+    "### Step 2: Detect the fine-grained-PAT 403",
+    "",
+    "The primary read fails closed for one specific credential: a",
+    "**fine-grained personal access token**. GitHub exposes no `Checks`",
+    "permission for fine-grained PATs (it is GitHub-App-only), so the",
+    "check-runs / `statusCheckRollup` request returns:",
+    "",
+    "```",
+    "HTTP 403: Resource not accessible by personal access token",
+    "```",
+    "",
+    "Trigger the Step 3 fallback **only** when the primary read either:",
+    "",
+    "- returns an explicit **403** (`Resource not accessible by personal",
+    "  access token`) on the check-runs / `statusCheckRollup` request,",
+    "  **or**",
+    "- returns **no readable check contexts at all** (an empty rollup)",
+    "  for a head SHA that does have CI configured.",
+    "",
+    "A primary read that returns one or more readable contexts is",
+    "authoritative \u2014 **never** fall back in that case (GitHub-App and",
+    "classic-PAT consumers keep the complete check-runs view). **Never**",
+    "treat a 403 or an unreadable check as green: the 403 is a",
+    "visibility failure, not a passing signal.",
+    "",
+    "### Step 3: Fallback read \u2014 Actions runs API",
+    "",
+    "A fine-grained PAT with `Actions: Read-only` (which **is**",
+    "grantable) can read workflow-run conclusions even when check-runs",
+    "is denied. Read every workflow run for the PR's head SHA:",
+    "",
+    "```bash",
+    "head_sha=$(gh pr view <pr-number> --json headRefOid --jq '.headRefOid')",
+    'gh api "repos/{{repository.owner}}/{{repository.name}}/actions/runs?head_sha=${head_sha}&per_page=100"',
+    "```",
+    "",
+    "Each run carries a `name`, `status`, and `conclusion`. **Collapse",
+    "re-runs:** when a workflow `name` appears more than once for the",
+    "same head SHA, keep only the most recent run (highest",
+    "`run_number` / latest `created_at`) for that name.",
+    "",
+    "This fallback only sees GitHub Actions runs. It is sound for repos",
+    "whose CI is entirely GitHub Actions; if a consumer adds a",
+    "non-Actions required check, a fine-grained-PAT credential cannot",
+    "see it and the consumer must move the reviewer to a GitHub App /",
+    "classic PAT to regain the complete check-runs view.",
+    "",
+    "### Step 4: Map conclusions to a verdict",
+    "",
+    "Apply this mapping to the set of required checks (Step 5 defines",
+    '"required"):',
+    "",
+    "| status / conclusion | Treatment |",
+    "|---------------------|-----------|",
+    "| `completed` / `success` | pass |",
+    "| `completed` / `skipped` | non-blocking (ignore) |",
+    "| `completed` / `neutral` | non-blocking (ignore) |",
+    "| `completed` / `failure` | **block \u2192 red** |",
+    "| `completed` / `cancelled` | **block \u2192 red** |",
+    "| `completed` / `timed_out` | **block \u2192 red** |",
+    "| `completed` / `action_required` | **block \u2192 red** |",
+    "| `in_progress` / `queued` / `requested` / `waiting` / null conclusion | not-yet-green (pending) |",
+    "",
+    "- If any required check is **red**, the verdict is **red**.",
+    "- Else if any required check is **pending**, the verdict is",
+    "  **pending**.",
+    "- Else (every required check passed or was non-blocking) the",
+    "  verdict is **green**.",
+    "",
+    '### Step 5: Which workflows are "required"',
+    "",
+    'In the **Step 1 primary path**, "required" means the contexts',
+    "GitHub marks required under branch protection \u2014 the rollup already",
+    "reflects this.",
+    "",
+    "In the **Step 3 fallback path**, the Actions runs API does not say",
+    "which workflows are required, so consult the policy's",
+    "`ci-verification.required-workflows` list (rendered in the",
+    "`PR Review Policy` block in CLAUDE.md):",
+    "",
+    "- **Non-empty list** \u2014 gate only on the workflow `name`s in the",
+    "  list. A listed workflow with **no** run for the head SHA is",
+    "  treated as not-yet-green (pending), never green.",
+    "- **Empty list (default)** \u2014 treat **every** workflow run observed",
+    "  for the head SHA as required. This is the conservative",
+    "  zero-config default: an unknown failing workflow blocks rather",
+    "  than slips through.",
+    "",
+    "---",
+    "",
     "## Phase 1: Identify the PR",
     "",
     "If a PR number was provided in your instructions, use that. Otherwise stop",
@@ -17525,7 +17659,12 @@ var prReviewerSubAgent = {
     '1. `mergeable == "MERGEABLE"` (no merge conflicts).',
     "2. No **failing** required checks in `statusCheckRollup` \u2014 CI must be",
     "   green or still pending. Any `FAILURE`, `TIMED_OUT`, `CANCELLED`, or",
-    "   `ERROR` conclusion on a required check disqualifies the PR.",
+    "   `ERROR` conclusion on a required check disqualifies the PR. If the",
+    "   `statusCheckRollup` read returns a 403 `Resource not accessible by",
+    "   personal access token` (fine-grained PAT) or an empty rollup,",
+    "   resolve CI via the **CI Verification** section's Actions-runs",
+    "   fallback before deciding eligibility \u2014 do **not** treat the 403 as",
+    "   either a pass or an automatic disqualification.",
     "3. The PR body contains a linked issue via one of the closing keywords:",
     "   `Closes #N`, `Fixes #N`, or `Resolves #N` (case-insensitive).",
     "",
@@ -17743,7 +17882,9 @@ var prReviewerSubAgent = {
     "- **Convention compliance** \u2014 PR title uses a conventional commit prefix,",
     "  body includes a closing keyword, branch name follows project conventions",
     "- **Test coverage** \u2014 new or changed behavior has tests",
-    "- **CI status** \u2014 `gh pr checks` reports all required checks passing",
+    "- **CI status** \u2014 resolve CI via the **CI Verification** section",
+    "  (primary check-runs read, with the Actions-runs fallback on a",
+    "  fine-grained-PAT 403). The verdict must be **green**.",
     "- **Scope creep** \u2014 diff stays within the issue's stated scope",
     "",
     "## Phase 3.5: Classify Comments",
@@ -18118,7 +18259,9 @@ var prReviewerSubAgent = {
     "   pushbacks added in step (a) and the failure pushbacks added in",
     "   step (f).",
     "4. CI is green or still pending (any failing required check",
-    "   disqualifies re-enablement).",
+    "   disqualifies re-enablement). Resolve CI via the **CI",
+    "   Verification** section, including the Actions-runs fallback on a",
+    "   fine-grained-PAT 403.",
     "",
     "When all four hold, re-enable auto-merge with the same command used",
     "in the auto-merge branch below:",
@@ -18517,7 +18660,9 @@ var prReviewerSubAgent = {
     "- **AC status** \u2014 the checklist produced in Phase 3 (met, partial,",
     "  or missing), with links to the files or tests that provide the",
     "  evidence.",
-    "- **CI status** \u2014 derived from `gh pr checks`.",
+    "- **CI status** \u2014 the verdict from the **CI Verification** section",
+    "  (primary check-runs read, or the Actions-runs fallback when",
+    "  check-runs returns a fine-grained-PAT 403).",
     "- **Outstanding** \u2014 the comments still carrying a non-terminal",
     "  reviewer reaction from Phase 3.5 (typically `eyes` for queued",
     "  in-scope items and `nit` / `question` items that remain open).",
@@ -18642,7 +18787,11 @@ var prReviewerSubAgent = {
     "2. **Never merge without a linked issue.** If the PR body has no",
     "   `Closes #N` / `Fixes #N` / `Resolves #N`, comment and stop.",
     "3. **Never merge with failing CI.** Even if every criterion is met,",
-    "   block on red checks.",
+    "   block on red checks. Resolve CI status via the **CI",
+    "   Verification** section: read check-runs first, and only on a",
+    "   fine-grained-PAT 403 (or an empty rollup) fall back to the",
+    "   Actions runs API. A 403 is a visibility failure, **never** a",
+    "   passing check \u2014 do not treat an unreadable check as green.",
     "4. **Never bypass review conventions.** Always use `--squash`, `--auto`,",
     "   and `--delete-branch` for merges. Do not force-merge.",
     "5. **Never auto-merge a `human-required` PR.** When Phase 2.75 resolves",
@@ -18824,7 +18973,10 @@ var reviewPrsSkill = {
     '2. `mergeable == "MERGEABLE"` (no conflicts).',
     "3. No required check in `statusCheckRollup` has a failing conclusion",
     "   (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ERROR`). CI green or still",
-    "   pending is fine.",
+    "   pending is fine. When `statusCheckRollup` is empty or denied with",
+    "   a fine-grained-PAT 403, keep the PR in the queue \u2014 the per-PR",
+    "   pipeline resolves CI authoritatively via the reviewer's CI",
+    "   Verification Actions-runs fallback.",
     "4. The PR body contains a linked issue (`Closes #N` / `Fixes #N` /",
     "   `Resolves #N`, case-insensitive).",
     "",
@@ -18943,6 +19095,12 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
           ...renderPathsExemptFromSizeYaml(
             policy.autoMerge.pathsExemptFromSize
           ),
+          "",
+          "ci-verification:",
+          "  required-workflows:",
+          ...renderRequiredWorkflowsYaml(
+            policy.ciVerification.requiredWorkflows
+          ),
           "```",
           "",
           "## Precedence",
@@ -19024,7 +19182,69 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
           "out only kicks in for **code-heavy** PRs that legitimately trip",
           "rule #6 (mixed-content diffs whose non-doc paths fail the",
           "`paths-exempt-from-size` check, or consumers that disable the",
-          "doc-only carve-out entirely)."
+          "doc-only carve-out entirely).",
+          "",
+          "## CI Verification",
+          "",
+          "Before enabling auto-merge the reviewer confirms CI is green.",
+          "The **primary** read is the GitHub check-runs rollup",
+          "(`gh pr checks` / `statusCheckRollup`) \u2014 the same source",
+          "GitHub uses for branch protection, covering **every** check",
+          "context (Actions, third-party CI, GitHub Apps, commit",
+          "statuses). It stays primary for every consumer because it is",
+          "strictly more complete than the Actions-only fallback below.",
+          "",
+          "### Fine-grained-PAT fallback to the Actions runs API",
+          "",
+          "When the reviewer authenticates with a **fine-grained personal",
+          "access token**, the check-runs read returns",
+          "`HTTP 403: Resource not accessible by personal access token`.",
+          "This is not grantable away: GitHub exposes **no `Checks`",
+          "permission for fine-grained tokens** (it is GitHub-App-only),",
+          "so the token permission picker has no entry to add. On that",
+          "specific 403 (or when the rollup returns no readable contexts",
+          "at all), the reviewer falls back to the **Actions runs API**:",
+          "",
+          "```",
+          "GET /repos/{owner}/{repo}/actions/runs?head_sha={head_sha}&per_page=100",
+          "```",
+          "",
+          "which a fine-grained PAT with `Actions: Read-only` **can**",
+          "read. Auto-merge is then gated on the required workflows'",
+          "latest run per workflow name concluding `success`",
+          "(`skipped` / `neutral` are non-blocking; `failure` /",
+          "`cancelled` / `timed_out` / `action_required` block; a run",
+          "still `in_progress` / `queued`, or a required workflow with no",
+          "run at all, counts as not-yet-green). The 403 is detected",
+          "explicitly and is **never** treated as a passing check \u2014 it is",
+          "a visibility failure, not a green signal.",
+          "",
+          "The fallback fires **only** when the primary check-runs read",
+          "is denied, so GitHub-App and classic-PAT consumers (which can",
+          "read check-runs) are unaffected and keep the complete view.",
+          "The fallback only sees GitHub Actions runs; a consumer whose",
+          "CI includes a non-Actions required check cannot verify it on a",
+          "fine-grained PAT and must move the reviewer to a GitHub App /",
+          "classic PAT to regain the complete check-runs view.",
+          "",
+          "### Configuring required workflows",
+          "",
+          "The `ci-verification.required-workflows` list in the policy",
+          "YAML names the workflows the fallback gates on:",
+          "",
+          "- **Non-empty list** \u2014 gate only on those workflow `name`s.",
+          "  A listed workflow with no run for the head SHA is treated as",
+          "  not-yet-green (pending), never green.",
+          "- **Empty list (the default)** \u2014 treat **every** workflow run",
+          "  observed for the head SHA as required. This is the",
+          "  conservative zero-config default so an unknown failing",
+          "  workflow blocks rather than slips through.",
+          "",
+          "Consumers tune the list via",
+          "`agentConfig.prReviewPolicy.ciVerification.requiredWorkflows`.",
+          "The list governs **only** the fallback path; the primary",
+          'check-runs read derives "required" from branch protection',
+          "directly."
         ].join("\n"),
         tags: ["policy", "review"]
       },
@@ -19310,6 +19530,12 @@ function renderPathsExemptFromSizeYaml(paths) {
   }
   return paths.map((path8) => `    - "${path8}"`);
 }
+function renderRequiredWorkflowsYaml(workflows) {
+  if (workflows.length === 0) {
+    return ["    []"];
+  }
+  return workflows.map((workflow) => `    - "${workflow}"`);
+}
 var prReviewBundle = buildPrReviewBundle();
 
 // src/agent/bundles/projen.ts