@homeflare/alchemy 0.27.4 → 0.29.0

package/src/github/repository-ruleset-narrowing-guards.ts

@@ -0,0 +1,141 @@
+/**
+ * Narrowing refusals — the counterpart to `bypassWideningRefusal`/`undeclaredLiveRuleRefusal` in
+ * repository-ruleset-guards.ts, split into its own file purely to keep both under the 250-line
+ * cap (same reason repository-ruleset-props.ts exists).
+ *
+ * ⛔ WIDENING STAYS UNCONDITIONAL; NARROWING GETS AN ESCAPE HATCH. Widening bypass (granting a
+ *   NEW actor) has no legitimate reason to happen through a deploy — "grant it by hand and adopt
+ *   the change" (repository-ruleset-errors.ts's `BypassActorWidened` message) already covers it,
+ *   and this file does not touch that guard. NARROWING (removing a live bypass actor, or
+ *   dropping a live rule) is different: it is exactly what an EXACT-ADOPT declaration of a repo
+ *   whose live ruleset is narrower than the house baseline needs to express on its very first
+ *   deploy — a caller declaring `taslabs-net/taslabs-net`'s live shape (measured live via `gh
+ *   api repos/taslabs-net/taslabs-net/rulesets/12206080`, 2026-09-23: `bypass_actors:
+ *   [{actor_id: 5, actor_type: "RepositoryRole", bypass_mode: "always"}]`, `rules: [deletion,
+ *   non_fast_forward]`, no `pull_request` rule) is not narrowing anything by declaring exactly
+ *   that shape — it is matching live exactly, and `reconcileRuleset`'s own noop check (comparing
+ *   canonicalized wire forms) makes zero writes for it, same as any other exact match. What
+ *   these guards refuse is a LATER declaration that removes something the CURRENT live state
+ *   still has, without saying why. `acknowledgeBypassNarrowing`/`acknowledgeRuleNarrowing` are
+ *   the "why": a reasoned, deliberate sign-off, not a rubber stamp — see their doc comments on
+ *   `RepositoryRulesetProps` (repository-ruleset-props.ts).
+ *
+ * ⛔ THE TWO ACKNOWLEDGEMENTS ARE DELIBERATELY SEPARATE PROPS, NOT ONE SHARED FLAG (2026-09-23
+ *   review finding). A single `acknowledgeNarrowing` computed once and handed to both guards let
+ *   a reason written for one kind of narrowing silently also excuse the other — a declaration
+ *   dropping BOTH a live rule and a live bypass actor at once needed only one acknowledgement,
+ *   however narrowly worded, to pass both checks. Each guard below now reads its OWN prop.
+ */
+import { bypassKey, liveRuleTypes } from './repository-ruleset-guards.ts';
+import { BypassActorNarrowed, RuleNarrowed } from './repository-ruleset-errors.ts';
+import type { RepositoryRulesetProps, RepositoryRulesetRules } from './repository-ruleset-props.ts';
+import type { RulesetRecord } from './repository-ruleset-probe.ts';
+
+/** `true` only for a non-empty, non-whitespace `reason` on `acknowledgeBypassNarrowing` — a bare
+ * `{}` or a blank string is not an acknowledgement (repository-ruleset.ts's `constraintRefusal`
+ * refuses the latter at plan time; this is the read `bypassNarrowingRefusal` shares). Deliberately
+ * ignorant of `acknowledgeRuleNarrowing` — see the file header. */
+export const isBypassNarrowingAcknowledged = (props: RepositoryRulesetProps): boolean =>
+  props.acknowledgeBypassNarrowing !== undefined &&
+  props.acknowledgeBypassNarrowing.reason.trim().length > 0;
+
+/** The `rules`-side counterpart to `isBypassNarrowingAcknowledged`, reading only
+ * `acknowledgeRuleNarrowing` — see the file header. */
+export const isRuleNarrowingAcknowledged = (props: RepositoryRulesetProps): boolean =>
+  props.acknowledgeRuleNarrowing !== undefined &&
+  props.acknowledgeRuleNarrowing.reason.trim().length > 0;
+
+/**
+ * A live bypass actor the declaration drops, unacknowledged. `undefined` `declared` never
+ * reaches here — same rule as `bypassWideningRefusal`: unmanaged means the live value is
+ * preserved unchanged (repository-ruleset-reconcile.ts), so there is nothing to narrow.
+ */
+export function bypassNarrowingRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly declared: RepositoryRulesetProps['bypassActors'];
+  readonly live: RulesetRecord | undefined;
+  readonly acknowledged: boolean;
+}): BypassActorNarrowed | undefined {
+  if (input.acknowledged) return undefined;
+  if (input.live === undefined) return undefined;
+  const liveActors = (input.live.bypass_actors ?? []) as {
+    actor_type: unknown;
+    actor_id: unknown;
+    bypass_mode?: unknown;
+  }[];
+  const declaredKeys = new Set(
+    (input.declared ?? []).map((a) =>
+      bypassKey({
+        actor_type: a.actorType,
+        actor_id: a.actorId,
+        bypass_mode: a.bypassMode ?? 'always',
+      }),
+    ),
+  );
+  const narrowed = liveActors.map(bypassKey).filter((k) => !declaredKeys.has(k));
+  if (narrowed.length === 0) return undefined;
+  return new BypassActorNarrowed({
+    owner: input.owner,
+    repository: input.repository,
+    name: input.name,
+    narrowed,
+  });
+}
+
+/** The live rule `type` for the first boolean/`pullRequest` rule the declaration marks `false`
+ * while live still has it — `undefined` when none does. `requiredStatusChecks: false` is
+ * checked by the caller directly (its live-side read needs `required_status_checks`'s own
+ * parameters shape, not just presence, elsewhere in this family — kept out of this helper so it
+ * stays a plain type-to-type comparison). */
+function droppedBooleanOrPullRequestType(
+  rules: RepositoryRulesetRules,
+  live: ReadonlySet<string>,
+): string | undefined {
+  const declaredFalse: readonly [boolean | undefined, string][] = [
+    [rules.creation, 'creation'],
+    [rules.update, 'update'],
+    [rules.deletion, 'deletion'],
+    [rules.requiredLinearHistory, 'required_linear_history'],
+    [rules.requiredSignatures, 'required_signatures'],
+    [rules.nonFastForward, 'non_fast_forward'],
+  ];
+  for (const [declared, type] of declaredFalse) {
+    if (declared === false && live.has(type)) return type;
+  }
+  if (rules.pullRequest === false && live.has('pull_request')) return 'pull_request';
+  return undefined;
+}
+
+/**
+ * A rule the declaration explicitly marks absent (a boolean rule or `pullRequest` declared
+ * `false`, or `requiredStatusChecks: false`) while the LIVE ruleset still has it, unacknowledged
+ * — the drop `undeclaredLiveRuleRefusal` (repository-ruleset-guards.ts) never sees, because an
+ * explicit `false` IS "declared" there (see its own `declaredRuleTypes`).
+ */
+export function ruleNarrowingRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly declared: RepositoryRulesetProps['rules'];
+  readonly live: RulesetRecord | undefined;
+  readonly acknowledged: boolean;
+}): RuleNarrowed | undefined {
+  if (input.acknowledged) return undefined;
+  const rules = input.declared;
+  if (rules === undefined) return undefined;
+  const live = liveRuleTypes(input.live);
+  const ruleType =
+    droppedBooleanOrPullRequestType(rules, live) ??
+    (rules.requiredStatusChecks === false && live.has('required_status_checks')
+      ? 'required_status_checks'
+      : undefined);
+  if (ruleType === undefined) return undefined;
+  return new RuleNarrowed({
+    owner: input.owner,
+    repository: input.repository,
+    name: input.name,
+    ruleType,
+  });
+}

package/src/github/repository-ruleset-narrowing.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Narrowing refusals (repository-ruleset-narrowing-guards.ts), split out of
+ * repository-ruleset-write-refusals.test.ts purely to keep both files under the 250-line cap.
+ * `acknowledgeRuleNarrowing`/`acknowledgeBypassNarrowing` are the escape hatches: without the
+ * matching one, dropping a live rule or a live bypass actor is refused; with a non-empty reason
+ * on the RIGHT prop, it writes exactly what was declared. The two are intentionally separate
+ * props, not one shared flag — see the 'mixed narrowing' describe block below and the file
+ * header on repository-ruleset-narrowing-guards.ts for the 2026-09-23 finding this fixes. The
+ * dedicated exact-adopt fixtures (all 5 live non-empty-bypass shapes, none of which are
+ * "narrowing" — they match live exactly) are repository-ruleset-exact-adopt.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeGetOnlyFake, makeRecordingFake } from './repository-ruleset-fake-octokit.ts';
+import {
+  BASE_PULL_REQUEST,
+  fails,
+  props,
+  reconcileAgainst,
+  reconcileWithOctokit,
+  tagOf,
+} from './repository-ruleset-test-helpers.ts';
+
+describe('rule narrowing', () => {
+  // Regression for the gap the exact-adopt pass-through work closed 2026-09-23: an explicit
+  // `false` alone used to be enough to drop a live rule, with no record of WHY. It is now also
+  // gated on `acknowledgeRuleNarrowing` — see repository-ruleset-narrowing-guards.ts.
+  test('dropping a live rule (deletion declared false) without acknowledgeRuleNarrowing is refused', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RuleNarrowed');
+  });
+
+  test('the SAME drop, acknowledged with a reason, is a deliberate removal and writes once', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeRecordingFake({ widgets: live });
+    fake.reportedContexts.add('ci');
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeRuleNarrowing: { reason: 'Tim approved dropping delete-protection 2026-09-23' },
+    });
+    await reconcileAgainst(fake, declaration, { rulesetId: 1 }).pipe(Effect.runPromise);
+    expect(fake.writes).toHaveLength(1);
+    expect(fake.writes[0]?.op).toBe('update');
+    const sentTypes = fake.writes[0]?.body?.rules?.map((r) => r.type);
+    expect(sentTypes).not.toContain('deletion');
+  });
+
+  // A blank (or whitespace-only) reason is not an acknowledgement —
+  // `isRuleNarrowingAcknowledged` (repository-ruleset-narrowing-guards.ts) requires a
+  // non-empty, TRIMMED reason, so this is indistinguishable from omitting
+  // `acknowledgeRuleNarrowing` entirely and gets the same refusal.
+  test('acknowledgeRuleNarrowing with a blank reason does not count as acknowledged', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeRuleNarrowing: { reason: '   ' },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RuleNarrowed');
+  });
+
+  // Scoping regression (2026-09-23 review finding): an acknowledgement reasoned for the RULE
+  // drop must not also excuse a bypass-actor drop declared in the SAME declaration.
+  test('acknowledgeRuleNarrowing does not excuse an unrelated bypass-actor drop', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeRuleNarrowing: { reason: 'Tim approved dropping delete-protection 2026-09-23' },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('BypassActorNarrowed');
+  });
+});
+
+describe('bypass narrowing', () => {
+  test('dropping a live bypass actor without acknowledgeBypassNarrowing is refused', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [{ type: 'deletion' }, { type: 'non_fast_forward' }],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: true, nonFastForward: true },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('BypassActorNarrowed');
+  });
+
+  test('the SAME drop, acknowledged with a reason, writes the narrowed list', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [{ type: 'deletion' }, { type: 'non_fast_forward' }],
+    };
+    const fake = makeRecordingFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: true, nonFastForward: true },
+      acknowledgeBypassNarrowing: { reason: 'Tim revoked admin bypass 2026-09-23' },
+    });
+    await reconcileAgainst(fake, declaration, { rulesetId: 1 }).pipe(Effect.runPromise);
+    expect(fake.writes).toHaveLength(1);
+    expect(fake.writes[0]?.body?.bypass_actors).toEqual([]);
+  });
+
+  // Widening stays refused even alongside an acknowledgement — `acknowledgeBypassNarrowing`
+  // gates ONLY narrowing (repository-ruleset-narrowing-guards.ts's file header explains why).
+  test('acknowledgeBypassNarrowing does not excuse widening', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [{ actorType: 'OrganizationAdmin' }],
+      acknowledgeBypassNarrowing: { reason: 'irrelevant to widening' },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('BypassActorWidened');
+  });
+
+  // Scoping regression (2026-09-23 review finding), the mirror of the rule-narrowing case
+  // above: an acknowledgement reasoned for the BYPASS drop must not also excuse an unrelated
+  // rule drop declared in the SAME declaration.
+  test('acknowledgeBypassNarrowing does not excuse an unrelated rule drop', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeBypassNarrowing: { reason: 'Tim revoked admin bypass 2026-09-23' },
+    });
+    // The bypass drop is acknowledged (so `bypassNarrowingRefusal` passes), but the rule drop
+    // is not — `reconcileRuleset` checks bypass narrowing before rule narrowing, so a REFUSED
+    // rule drop under a bypass-only acknowledgement surfaces as `RuleNarrowed`, proving the
+    // bypass acknowledgement did not also cover it.
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RuleNarrowed');
+  });
+});

package/src/github/repository-ruleset-octokit.test.ts

@@ -0,0 +1,141 @@
+/**
+ * K2 (2026-09-24): MEASURES `contextReportedSuccess` (repository-ruleset-octokit.ts) against a
+ * real `@octokit/rest` instance with a fetch shim (no network) — the same pattern
+ * repository-ruleset-wire.test.ts uses for H15, applied here to the "which ref did we check"
+ * question instead of "did the wire field survive". The shim routes by URL path, not by call
+ * order, so these tests exercise the SAME sequencing the real implementation performs: default
+ * branch tip first, then (only if the tip has nothing) recent merged PR heads, bounded.
+ *
+ * Both sides the guard exists to hold: accept a context that reports only on a recent merged PR
+ * head (the case K2 fixes — CI runs on `pull_request` only, never the tip), and still refuse one
+ * that reports nowhere, tip or any recent merged head, INCLUDING one whose only success is
+ * older than `RECENT_MERGED_PR_LIMIT` merges ago (the bound is real, not decorative).
+ */
+import { describe, expect, test } from 'bun:test';
+import { Octokit } from '@octokit/rest';
+import * as Effect from 'effect/Effect';
+import { RECENT_MERGED_PR_LIMIT, contextReportedSuccess } from './repository-ruleset-octokit.ts';
+
+interface CheckRun {
+  readonly name: string;
+  readonly conclusion: string | null;
+}
+interface Status {
+  readonly context: string;
+  readonly state: string;
+}
+interface MergedPull {
+  readonly merged_at: string | null;
+  readonly head: { readonly sha: string };
+}
+
+interface Fixture {
+  readonly defaultBranch: string;
+  readonly checkRuns?: Readonly<Record<string, readonly CheckRun[]>>;
+  readonly statuses?: Readonly<Record<string, readonly Status[]>>;
+  /** Already in the order GitHub's `sort: updated, direction: desc` would return — most
+   * recently updated first. */
+  readonly closedPulls?: readonly MergedPull[];
+}
+
+/** Routes by URL path, not call order — GET .../pulls, GET .../commits/{ref}/check-runs, GET
+ * .../commits/{ref}/statuses, else the bare repo GET (`default_branch`). `captured` records
+ * every URL so a test can assert a ref was — or, for boundedness, was NEVER — looked up. */
+function makeServingFetch(fx: Fixture, captured: string[]): typeof fetch {
+  const respond = (body: unknown) =>
+    new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  return (async (input: Parameters<typeof fetch>[0]) => {
+    const url = String(input);
+    captured.push(url);
+    if (/\/pulls(\?|$)/.test(url)) return respond(fx.closedPulls ?? []);
+    const commits = /\/commits\/([^/?]+)\/(check-runs|statuses)/.exec(url);
+    if (commits) {
+      const [, ref, kind] = commits;
+      if (kind === 'check-runs') {
+        const runs = fx.checkRuns?.[ref as string] ?? [];
+        return respond({ total_count: runs.length, check_runs: runs });
+      }
+      return respond(fx.statuses?.[ref as string] ?? []);
+    }
+    return respond({ default_branch: fx.defaultBranch });
+  }) as typeof fetch;
+}
+
+const octokitOver = (fx: Fixture, captured: string[] = []) =>
+  new Octokit({
+    auth: 'fake-token-not-a-real-credential',
+    request: { fetch: makeServingFetch(fx, captured) },
+  });
+
+const run = (eff: Effect.Effect<boolean, Error>): Promise<boolean> => Effect.runPromise(eff);
+
+describe('contextReportedSuccess', () => {
+  test('accepts a context that reports only on a recent merged PR head, not the tip', async () => {
+    const octokit = octokitOver({
+      defaultBranch: 'main',
+      checkRuns: { sha2: [{ name: 'ci', conclusion: 'success' }] },
+      closedPulls: [
+        { merged_at: '2026-09-20T00:00:00Z', head: { sha: 'sha3' } },
+        { merged_at: '2026-09-19T00:00:00Z', head: { sha: 'sha2' } },
+        { merged_at: '2026-09-18T00:00:00Z', head: { sha: 'sha1' } },
+      ],
+    });
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-builds', 'ci'),
+    );
+    expect(reported).toBe(true);
+  });
+
+  test('refuses a context that reports nowhere — tip or any recent merged head', async () => {
+    const octokit = octokitOver({
+      defaultBranch: 'main',
+      closedPulls: [
+        { merged_at: '2026-09-20T00:00:00Z', head: { sha: 'sha3' } },
+        { merged_at: '2026-09-19T00:00:00Z', head: { sha: 'sha2' } },
+      ],
+    });
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-builds', 'ci'),
+    );
+    expect(reported).toBe(false);
+  });
+
+  test('a success older than RECENT_MERGED_PR_LIMIT merges ago is still refused — the bound is real', async () => {
+    // RECENT_MERGED_PR_LIMIT (10) merged PRs report nothing; only the 11th (oldest returned,
+    // outside the bound) reports `ci` — proves the function stops at the limit rather than
+    // scanning everything the list call happened to return.
+    const closedPulls: MergedPull[] = Array.from({ length: RECENT_MERGED_PR_LIMIT }, (_, i) => ({
+      merged_at: `2026-09-${String(20 - i)}T00:00:00Z`,
+      head: { sha: `within-bound-${String(i)}` },
+    }));
+    closedPulls.push({ merged_at: '2026-08-01T00:00:00Z', head: { sha: 'beyond-bound' } });
+    const captured: string[] = [];
+    const octokit = octokitOver(
+      {
+        defaultBranch: 'main',
+        checkRuns: { 'beyond-bound': [{ name: 'ci', conclusion: 'success' }] },
+        closedPulls,
+      },
+      captured,
+    );
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-builds', 'ci'),
+    );
+    expect(reported).toBe(false);
+    expect(captured.some((url) => url.includes('/commits/beyond-bound/'))).toBe(false);
+  });
+
+  test('the default branch tip alone is still enough — no fallback needed', async () => {
+    const octokit = octokitOver({
+      defaultBranch: 'main',
+      statuses: { main: [{ context: 'secret scan', state: 'success' }] },
+    });
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-kit', 'secret scan'),
+    );
+    expect(reported).toBe(true);
+  });
+});

package/src/github/repository-ruleset-octokit.ts

@@ -8,14 +8,22 @@
  * should reach the wire. repository-ruleset-wire.test.ts MEASURES this against a real Octokit
  * instance with a fetch shim rather than asserting it from reading the source.
  *
- * ⚠️ "Reported success" is checked at the default branch's CURRENT TIP only, not its full
- *   history — a context that reported success three merges ago and has since started failing
- *   reads as reported (true), and one that has only ever run on a branch nobody has merged
- *   since reads as never-reported (false) until the next merge updates the tip. A full-history
- *   search is disproportionate to what this guard protects against (adding a context that
- *   plainly cannot report), and GitHub's check-runs/statuses APIs are themselves scoped to a
- *   single ref, not "ever, anywhere" — there is no cheaper vendor call that answers the wider
- *   question.
+ * ★ K2 (2026-09-24): "REPORTED SUCCESS" IS THE DEFAULT BRANCH'S TIP, THEN RECENT MERGED PR
+ *   HEADS — NOT FULL HISTORY. The rendered CI (`packages/config/src/repo-shape/ci.ts`) triggers
+ *   on `pull_request` ONLY, deliberately (measured 2026-09-15..22: 613 of 619 main-push runs
+ *   duplicated an already-green PR run, ~41% of the mini's CI load) — so `ci`/`secret scan`/
+ *   `CodeQL` NEVER report on the default branch's tip itself, only on PR heads. Checking the tip
+ *   alone therefore refused adding any of them everywhere, including homeflare-builds' pending
+ *   first ruleset. `contextReportedSuccess` now falls back to `recentMergedHeadShas` — bounded
+ *   (`RECENT_MERGED_PR_LIMIT` heads, from one `per_page`-bounded list call, never the repo's
+ *   full PR history) — so a context that only ever reports on PR heads is no longer refused
+ *   everywhere, while a context that has never reported ANYWHERE (not the tip, not any recent
+ *   merged head) still is: `NeverReportedContext`'s whole purpose survives unchanged.
+ * ⚠️ Still not full history: a context whose only successful run predates
+ *   `RECENT_MERGED_PR_LIMIT` merges ago reads as never-reported until it runs again. Widening
+ *   the bound trades this guard's cost (more vendor calls per newly-required context) against
+ *   its reach; `RECENT_MERGED_PR_LIMIT` is a deliberate, named number for exactly that reason,
+ *   not a magic constant.
  */
 import type { Octokit as OctokitClient } from '@octokit/rest';
 import { GitHubCredentials } from 'alchemy/GitHub';
@@ -37,6 +45,110 @@ const octokitFor = (
 
 const is404 = (e: unknown): boolean => (e as { status?: number } | undefined)?.status === 404;
 
+/** How many of the most-recently-updated MERGED pull requests' head SHAs to check, once the
+ * default branch's own tip has no reported success — see the file header (K2). */
+export const RECENT_MERGED_PR_LIMIT = 10;
+/** How many closed PRs to list (in one bounded call) to find up to `RECENT_MERGED_PR_LIMIT`
+ * merged ones among them — larger than the limit because `state: 'closed'` also returns PRs
+ * closed without merging, sorted by `updated_at`, not `merged_at` (the REST API has no
+ * merged-only list). A GitHub API list call has no `merged` filter, so this is `100` — GitHub's
+ * own per-page maximum, not a smaller round number — to keep unmerged churn (e.g. Dependabot
+ * PRs closed without merging, which still bump `updated_at`) from crowding out real merges in a
+ * repo with heavy PR traffic (2026-09-24 review finding: a smaller page risked under-reaching in
+ * exactly the kind of repo this fix targets). Still bounded, still one call, still never the
+ * repo's full history — a repo whose last `RECENT_MERGED_PR_LIMIT` merges don't even fit in the
+ * last 100 closed PRs is treated the same as one with too little history: fewer heads found,
+ * same "still refused" fallback. */
+const RECENT_CLOSED_PR_PAGE_SIZE = 100;
+
+/** Whether `context` reported success for a single ref — a branch tip or a PR head SHA, both
+ * checked the same way (checks + statuses, exactly as GitHub's own UI does). Takes a plain
+ * `OctokitClient`, not an Effect service, so it and its caller below are testable directly
+ * against a real `@octokit/rest` instance with a fetch shim (repository-ruleset-octokit.test.ts)
+ * — no `GitHubCredentials` layer needed, mirroring `desiredWireRuleset`'s pure-function seam. */
+export const hasRefReportedSuccess = (
+  octokit: OctokitClient,
+  owner: string,
+  repo: string,
+  ref: string,
+  context: string,
+): Effect.Effect<boolean, Error> =>
+  Effect.gen(function* () {
+    const [checkRuns, statuses] = yield* Effect.all([
+      Effect.tryPromise({
+        try: () => octokit.rest.checks.listForRef({ owner, repo, ref, check_name: context }),
+        catch: asError,
+      }),
+      Effect.tryPromise({
+        try: () => octokit.rest.repos.listCommitStatusesForRef({ owner, repo, ref }),
+        catch: asError,
+      }),
+    ]);
+    const checkReported = checkRuns.data.check_runs.some(
+      (run) => run.name === context && run.conclusion === 'success',
+    );
+    const statusReported = statuses.data.some(
+      (status) => status.context === context && status.state === 'success',
+    );
+    return checkReported || statusReported;
+  });
+
+/** The head SHAs of up to `RECENT_MERGED_PR_LIMIT` most-recently-updated MERGED pull requests
+ * against `base` — one bounded list call (`RECENT_CLOSED_PR_PAGE_SIZE` closed PRs), filtered to
+ * merged, then capped. Never paginates further: a repo whose last `RECENT_MERGED_PR_LIMIT`
+ * merges are all older than its last `RECENT_CLOSED_PR_PAGE_SIZE` closed PRs simply yields fewer
+ * than the limit, same as a repo with too little history — both are the "still refused" case. */
+export const recentMergedHeadShas = (
+  octokit: OctokitClient,
+  owner: string,
+  repo: string,
+  base: string,
+): Effect.Effect<readonly string[], Error> =>
+  Effect.gen(function* () {
+    const closed = yield* Effect.tryPromise({
+      try: () =>
+        octokit.rest.pulls.list({
+          owner,
+          repo,
+          state: 'closed',
+          base,
+          sort: 'updated',
+          direction: 'desc',
+          per_page: RECENT_CLOSED_PR_PAGE_SIZE,
+        }),
+      catch: asError,
+    });
+    return closed.data
+      .filter((pr) => pr.merged_at !== null)
+      .slice(0, RECENT_MERGED_PR_LIMIT)
+      .map((pr) => pr.head.sha);
+  });
+
+/** The full K2 answer: the default branch's tip, then (only if the tip has no success) up to
+ * `RECENT_MERGED_PR_LIMIT` recent merged PR heads, short-circuiting on the first success. `false`
+ * only once every one of those has been checked and none reported — the case
+ * `NeverReportedContext` exists to refuse. */
+export const contextReportedSuccess = (
+  octokit: OctokitClient,
+  owner: string,
+  repo: string,
+  context: string,
+): Effect.Effect<boolean, Error> =>
+  Effect.gen(function* () {
+    const repository = yield* Effect.tryPromise({
+      try: () => octokit.rest.repos.get({ owner, repo }),
+      catch: asError,
+    });
+    const ref = repository.data.default_branch;
+    if (yield* hasRefReportedSuccess(octokit, owner, repo, ref, context)) return true;
+
+    const heads = yield* recentMergedHeadShas(octokit, owner, repo, ref);
+    for (const sha of heads) {
+      if (yield* hasRefReportedSuccess(octokit, owner, repo, sha, context)) return true;
+    }
+    return false;
+  });
+
 export const makeRulesetOctokit = (baseUrl: string | undefined): RealRulesetOctokit => ({
   list: ({ owner, repo }) =>
     Effect.gen(function* () {
@@ -114,27 +226,6 @@ export const makeRulesetOctokit = (baseUrl: string | undefined): RealRulesetOcto
   hasContextReportedSuccess: ({ owner, repo, context }) =>
     Effect.gen(function* () {
       const octokit = yield* octokitFor(baseUrl);
-      const repository = yield* Effect.tryPromise({
-        try: () => octokit.rest.repos.get({ owner, repo }),
-        catch: asError,
-      });
-      const ref = repository.data.default_branch;
-      const [checkRuns, statuses] = yield* Effect.all([
-        Effect.tryPromise({
-          try: () => octokit.rest.checks.listForRef({ owner, repo, ref, check_name: context }),
-          catch: asError,
-        }),
-        Effect.tryPromise({
-          try: () => octokit.rest.repos.listCommitStatusesForRef({ owner, repo, ref }),
-          catch: asError,
-        }),
-      ]);
-      const checkReported = checkRuns.data.check_runs.some(
-        (run) => run.name === context && run.conclusion === 'success',
-      );
-      const statusReported = statuses.data.some(
-        (status) => status.context === context && status.state === 'success',
-      );
-      return checkReported || statusReported;
+      return yield* contextReportedSuccess(octokit, owner, repo, context);
     }),
 });

package/src/github/repository-ruleset-probe.ts

@@ -71,7 +71,8 @@ export interface RulesetOctokit<R = never> {
     readonly repo: string;
     readonly rulesetId: number;
   }) => Effect.Effect<void, Error, R>;
-  /** Whether `context` has ever reported success against the repository's default branch —
+  /** Whether `context` has reported success against the repository's default branch tip OR a
+   * recent merged PR head (K2, bounded — see repository-ruleset-octokit.ts's file header) —
    * backs the `NeverReportedContext` guard. */
   readonly hasContextReportedSuccess: (input: {
     readonly owner: string;