@homeflare/alchemy 0.27.4 → 0.29.0

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

@@ -0,0 +1,95 @@
+/**
+ * `GitHub.RepositoryRuleset`'s declared shape — split out of repository-ruleset.ts purely to
+ * keep that file (the provider wiring) under the 250-line cap; nothing here is provider logic.
+ */
+import type { RulesetProps } from 'alchemy/GitHub';
+
+type UpstreamRules = NonNullable<RulesetProps['rules']>;
+
+export interface RepositoryRulesetReviewerRule {
+  readonly filePatterns: readonly string[];
+  readonly minimumApprovals: number;
+  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
+}
+
+export interface RepositoryRulesetPullRequestRule extends NonNullable<
+  UpstreamRules['pullRequest']
+> {
+  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
+  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
+  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
+  /** `require_extra_approval_for_unattributed_changes` — see repository-ruleset.ts's H15.
+   * Both values are modeled (K1, 2026-09-23): 8 live rulesets carry `true` (aop, cloudflareforms,
+   * doesthishelp-workeropen, homeflare-anyauth, homeflare-desktop, loggarr, magictransit,
+   * proxmox-tb4 — re-read live via `gh api repos/taslabs-net/<repo>/rulesets/<id>`,
+   * 2026-09-23), and this resource declares exactly what is live or it cannot adopt them —
+   * `undefined` stays "no opinion" (GitHub defaults an absent key to `true`). */
+  readonly extraApprovalForUnattributedChanges?: boolean;
+}
+
+export interface RepositoryRulesetStatusChecksRule extends NonNullable<
+  UpstreamRules['requiredStatusChecks']
+> {
+  readonly doNotEnforceOnCreate?: boolean;
+}
+
+export interface RepositoryRulesetRules extends Omit<
+  UpstreamRules,
+  'pullRequest' | 'requiredStatusChecks'
+> {
+  /** `undefined`: no opinion (refused if the live ruleset already has one and this is not an
+   * exact-adopt pass-through — see repository-ruleset-guards.ts's `undeclaredLiveRuleRefusal`).
+   * `false`: declare its ABSENCE — either "this repo never had one" (a create, or an adopt
+   * where live already has none, both no-ops) or a deliberate removal of a live rule, which
+   * `ruleNarrowingRefusal` gates behind `acknowledgeRuleNarrowing` (see below). Added 2026-09-23 for
+   * exact-adopt pass-through: `requiredStatusChecks` already had this `false` escape; `deletion`/
+   * `nonFastForward`/etc already have it implicitly (plain `boolean`, so `false` is already a
+   * value); `pullRequest` was the one modeled rule with NO way to express "not present at all" —
+   * a repo like `taslabs-net/taslabs-net` (measured live 2026-09-23: `rules = [deletion,
+   * non_fast_forward]`, no `pull_request`) could not be adopted through this resource without
+   * either refusing to omit the key (a type error) or silently declaring a brand-new rule. */
+  readonly pullRequest?: RepositoryRulesetPullRequestRule | false;
+  /** `undefined`: no opinion (refused if the live ruleset already has one — see
+   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
+  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
+}
+
+export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
+  readonly rules?: RepositoryRulesetRules;
+  /**
+   * An explicit, reasoned sign-off that THIS declaration deliberately drops a live bypass actor
+   * (`bypassActors` is a strict subset of what is live). Without this, `reconcile` refuses the
+   * write rather than silently loosen a ruleset that already protects something — see
+   * `bypassNarrowingRefusal` in repository-ruleset-narrowing-guards.ts. `reason` is not logged or
+   * sent to GitHub; it exists so the declaration's own diff carries WHY, for the next reader
+   * (S21: a refusal names the fact it checked — this is the human-authored counterpart for the
+   * one case a fact alone cannot settle: "is this narrowing intentional?").
+   *
+   * ⛔ SEPARATE FROM `acknowledgeRuleNarrowing` ON PURPOSE (2026-09-23 review finding: a single
+   *   shared `acknowledgeNarrowing` let one reason worded for a rule drop silently also rubber-
+   *   stamp an unrelated bypass-actor drop in the SAME declaration — a `bypassActors: []` left
+   *   over from an unrelated edit slipped through under a reason that never mentioned bypass at
+   *   all). Each prop authorizes only the narrowing its own guard checks; a declaration that
+   *   narrows both needs both, each with its own reason.
+   *
+   * ⛔ ALSO A STANDING PROP, NOT A ONE-TIME TOKEN — remove it from the declaration once the
+   *   narrowing it describes has landed. Left in place, it keeps disabling the bypass-narrowing
+   *   guard for every future `reconcile` of this resource, not only the change it was written
+   *   for — the same way `rules: { deletion: false }` stays a standing "this rule stays absent"
+   *   fact rather than a one-time action, only here the standing fact is "bypass narrowing needs
+   *   no review", which is a fact you want true for as short a window as possible. A reviewer
+   *   reading a diff that adds a SECOND, unrelated bypass drop under an OLD
+   *   `acknowledgeBypassNarrowing` left over from a prior change is the failure mode this note
+   *   exists to head off.
+   */
+  readonly acknowledgeBypassNarrowing?: { readonly reason: string };
+  /**
+   * The `rules`-side counterpart to `acknowledgeBypassNarrowing` above — an explicit, reasoned
+   * sign-off that THIS declaration deliberately drops a live rule (a modeled rule type declared
+   * `false`/boolean-`false` while the live ruleset still has it). Without this, `reconcile`
+   * refuses the write — see `ruleNarrowingRefusal` in repository-ruleset-narrowing-guards.ts.
+   * Same standing-prop caution as `acknowledgeBypassNarrowing`: remove it once the rule drop it
+   * describes has landed, or it keeps excusing every later rule drop on this resource too.
+   */
+  readonly acknowledgeRuleNarrowing?: { readonly reason: string };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * `repoPolicyProviders` — the documented stack wiring for `RepositoryRuleset` (directly, or
+ * through `declareRepoPolicy` / `declareRepoBaseline`): `GitHub.providers()` and
+ * `RepositoryRulesetProvider()`, composed so the whole thing typechecks and needs nothing
+ * further from the stack.
+ *
+ *     providers: repoPolicyProviders()
+ *
+ * ⛔ WHY THIS EXISTS — MEASURED 2026-09-24 (homeflare-builds bump PR 6, tsc). Writing the two
+ *   providers side by side, `Layer.mergeAll(GitHub.providers(), RepositoryRulesetProvider())`,
+ *   type-errors: `RepositoryRulesetProvider()`'s handlers call `octokitFor`, which needs
+ *   `GitHubCredentials` — a requirement of the PROVIDER's layer, correctly inferred by
+ *   `Provider.succeed` from `repositoryRulesetHandlers` in repository-ruleset.ts. Merging two
+ *   layers does not thread one's output into the other's requirement; `RepositoryRulesetProvider()`
+ *   still needs `GitHubCredentials` fed in. `GitHub.providers()` is the only thing here that
+ *   resolves credentials (env, stored PAT, `gh` CLI, or OAuth — see `alchemy/src/GitHub/
+ *   Providers.ts`), and — because it chains `Layer.provideMerge(Credentials.fromAuthProvider(…))`
+ *   internally rather than `Layer.provide` — its own OUTPUT includes `GitHubCredentials`
+ *   alongside `GitHub.Providers`. `Layer.provideMerge(github)` on `RepositoryRulesetProvider()`
+ *   both supplies that requirement AND keeps `github`'s own output merged in for any
+ *   `GitHub.Repository`/`GitHub.Ruleset` the caller also declares. `github` is built once and
+ *   referenced twice below — Effect's layer memoization (by reference) builds it once, not
+ *   twice, not twice against the auth provider either.
+ *
+ * ★ THIS IS ONLY HALF OF 2026-09-24's FIX. The other half — `RepositoryRuleset`'s own `Resource<>`
+ *   declaration no longer naming `GitHubCredentials` in its 5th (`Providers`) slot — lives in
+ *   repository-ruleset.ts's file header; that half is what let a stack BODY calling
+ *   `declareRepoPolicy`/`declareRepoBaseline` typecheck at all. Composing the providers
+ *   correctly, as this function does, does not by itself fix a body that still requires
+ *   `GitHubCredentials` directly.
+ *
+ * ⚠️ DON'T ALSO MERGE A SEPARATE `GitHub.providers()` CALL IN. `github` here is one Layer
+ *   object referenced twice, which Effect's layer memoization (by reference, ADVERSARIAL
+ *   REVIEW 2026-09-24: confirmed against `effect@4.0.0-rc.115`'s own `MemoMap`) builds once. A
+ *   stack that ALSO writes its own `GitHub.providers()` alongside this function's result is a
+ *   second, distinct Layer object — a genuine second credential resolution, not shared with
+ *   this one. Get every GitHub resource's providers from this one call.
+ */
+import * as GitHub from 'alchemy/GitHub';
+import * as Layer from 'effect/Layer';
+import { RepositoryRulesetProvider } from './repository-ruleset.ts';
+
+export const repoPolicyProviders = (options?: GitHub.ProvidersOptions) => {
+  const github = GitHub.providers(options);
+  return Layer.mergeAll(github, RepositoryRulesetProvider().pipe(Layer.provideMerge(github)));
+};

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

@@ -20,6 +20,12 @@ import {
   requiredChecksOmissionRefusal,
   undeclaredLiveRuleRefusal,
 } from './repository-ruleset-guards.ts';
+import {
+  bypassNarrowingRefusal,
+  isBypassNarrowingAcknowledged,
+  isRuleNarrowingAcknowledged,
+  ruleNarrowingRefusal,
+} from './repository-ruleset-narrowing-guards.ts';
 import {
   type RulesetOctokit,
   type RulesetRecord,
@@ -104,6 +110,12 @@ export const reconcileRuleset = <R = never>(input: {
       observed = yield* probeByName(octokit, { owner, repo, name: news.name, target });
     }
 
+    // Deliberately TWO separate reads, not one shared flag — each guard below is authorized
+    // only by the acknowledgement scoped to what it checks (see the file header on
+    // repository-ruleset-narrowing-guards.ts for the 2026-09-23 finding this fixes).
+    const bypassAcknowledged = isBypassNarrowingAcknowledged(news);
+    const ruleAcknowledged = isRuleNarrowingAcknowledged(news);
+
     const bypassRefusal =
       news.bypassActors === undefined
         ? undefined
@@ -116,6 +128,19 @@ export const reconcileRuleset = <R = never>(input: {
           });
     if (bypassRefusal !== undefined) return yield* Effect.fail(bypassRefusal);
 
+    const bypassNarrowRefusal =
+      news.bypassActors === undefined
+        ? undefined
+        : bypassNarrowingRefusal({
+            owner,
+            repository: repo,
+            name: news.name,
+            declared: news.bypassActors,
+            live: observed,
+            acknowledged: bypassAcknowledged,
+          });
+    if (bypassNarrowRefusal !== undefined) return yield* Effect.fail(bypassNarrowRefusal);
+
     const ruleRefusal = undeclaredLiveRuleRefusal({
       owner,
       repository: repo,
@@ -125,6 +150,16 @@ export const reconcileRuleset = <R = never>(input: {
     });
     if (ruleRefusal !== undefined) return yield* Effect.fail(ruleRefusal);
 
+    const ruleNarrowRefusal = ruleNarrowingRefusal({
+      owner,
+      repository: repo,
+      name: news.name,
+      declared: news.rules,
+      live: observed,
+      acknowledged: ruleAcknowledged,
+    });
+    if (ruleNarrowRefusal !== undefined) return yield* Effect.fail(ruleNarrowRefusal);
+
     const checksRefusal = requiredChecksOmissionRefusal({
       owner,
       repository: repo,

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

@@ -32,35 +32,46 @@ function makeCapturingFetch(captured: CapturedRequest[]): typeof fetch {
 }
 
 describe('does Octokit forward an untyped extra body field to the wire?', () => {
-  test('require_extra_approval_for_unattributed_changes survives createRepoRuleset', async () => {
-    const captured: CapturedRequest[] = [];
-    const octokit = new Octokit({
-      auth: 'fake-token-not-a-real-credential',
-      request: { fetch: makeCapturingFetch(captured) },
-    });
+  // K1 (2026-09-23): both values are modeled now, not only `false` — 8 live rulesets (aop,
+  // cloudflareforms, doesthishelp-workeropen, homeflare-anyauth, homeflare-desktop, loggarr,
+  // magictransit, proxmox-tb4; re-read live 2026-09-23) carry `true`, so this measurement needs
+  // both, not just the one value this resource used to be able to send.
+  test.each([false, true])(
+    'require_extra_approval_for_unattributed_changes: %p survives createRepoRuleset',
+    async (value) => {
+      const captured: CapturedRequest[] = [];
+      const octokit = new Octokit({
+        auth: 'fake-token-not-a-real-credential',
+        request: { fetch: makeCapturingFetch(captured) },
+      });
 
-    const body = desiredWireRuleset({
-      owner: 'taslabs-net',
-      repository: 'widgets',
-      name: 'main',
-      rules: {
-        pullRequest: {
-          requiredApprovingReviewCount: 0,
-          allowedMergeMethods: ['squash'],
-          extraApprovalForUnattributedChanges: false,
+      const body = desiredWireRuleset({
+        owner: 'taslabs-net',
+        repository: 'widgets',
+        name: 'main',
+        rules: {
+          pullRequest: {
+            requiredApprovingReviewCount: 0,
+            allowedMergeMethods: ['squash'],
+            extraApprovalForUnattributedChanges: value,
+          },
         },
-      },
-    });
+      });
 
-    await octokit.rest.repos.createRepoRuleset({ owner: 'taslabs-net', repo: 'widgets', ...body });
+      await octokit.rest.repos.createRepoRuleset({
+        owner: 'taslabs-net',
+        repo: 'widgets',
+        ...body,
+      });
 
-    expect(captured).toHaveLength(1);
-    const sent = captured[0]?.body as {
-      rules?: { type: string; parameters?: Record<string, unknown> }[];
-    };
-    const pr = sent?.rules?.find((r) => r.type === 'pull_request');
-    // MEASURED: this is what actually crossed the wire, not what Octokit's types say is legal.
-    expect(pr?.parameters?.require_extra_approval_for_unattributed_changes).toBe(false);
-    expect(pr?.parameters?.allowed_merge_methods).toEqual(['squash']);
-  });
+      expect(captured).toHaveLength(1);
+      const sent = captured[0]?.body as {
+        rules?: { type: string; parameters?: Record<string, unknown> }[];
+      };
+      const pr = sent?.rules?.find((r) => r.type === 'pull_request');
+      // MEASURED: this is what actually crossed the wire, not what Octokit's types say is legal.
+      expect(pr?.parameters?.require_extra_approval_for_unattributed_changes).toBe(value);
+      expect(pr?.parameters?.allowed_merge_methods).toEqual(['squash']);
+    },
+  );
 });

package/src/github/repository-ruleset-write-refusals.test.ts

@@ -1,8 +1,12 @@
 /**
  * (ii) The write-recording fake, refusals: duplicate names, bypass widening, an undeclared live
  * rule, required checks omitted, and a never-reported context each make ZERO writes; and a
- * readback mismatch fails even though the write itself "succeeded" (S10). The happy paths
- * (create, noop, update) are repository-ruleset-write.test.ts.
+ * readback mismatch fails even though the write itself "succeeded" (S10). Bypass/rule narrowing
+ * without the matching `acknowledge{Bypass,Rule}Narrowing` are their own file,
+ * repository-ruleset-narrowing.test.ts (split out purely for the 250-line cap). The happy paths
+ * (create, noop, update) are repository-ruleset-write.test.ts; exact-adopt pass-through's own
+ * dedicated fixtures (all 5 live non-empty-bypass shapes) are
+ * repository-ruleset-exact-adopt.test.ts.
  */
 import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
@@ -94,30 +98,6 @@ describe('refusals make zero writes', () => {
     expect(tagOf(error)).toBe('UndeclaredLiveRule');
   });
 
-  test('the SAME live ruleset with deletion explicitly declared false is a deliberate removal, not 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 = makeRecordingFake({ widgets: live });
-    fake.reportedContexts.add('ci');
-    const declaration = props({
-      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
-    });
-    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');
-  });
-
   test('required checks omitted while the live ruleset has them', async () => {
     const live = {
       id: 1,

package/src/github/repository-ruleset.ts

@@ -38,11 +38,33 @@
  *   meant to allow. `octokitFor`/`GitHubCredentials` are upstream's own EXPORTED building
  *   blocks (S23's second clause: reuse Alchemy's own client construction), so the client itself
  *   is not hand-rolled — only the choice of Octokit over distilled is a recorded divergence.
+ *
+ * ⛔ CREDENTIALS BELONG TO THE PROVIDER'S LAYER, NOT THE RESOURCE'S DECLARATION — MEASURED
+ *   2026-09-24 (homeflare-builds bump PR 6, tsc TS2345). The `Resource<Type, Props, Attributes,
+ *   Binding, Providers>` 5th type parameter had `GitHubCredentials` here; that puts the
+ *   credential requirement on every `yield* RepositoryRuleset(...)` CALL SITE (see
+ *   `alchemy/src/Resource.ts#ResourceClass`: `Req = R["Providers"] extends undefined ?
+ *   Provider<R> : R["Providers"]`), so a STACK BODY that merely declares the resource would
+ *   itself need `GitHubCredentials` in its own effect context — which a stack body cannot
+ *   produce (`Alchemy.Stack`'s own type, `alchemy/src/Stack.ts#ProviderServices`, is a closed
+ *   union of tagged marker interfaces — `ProviderCollectionLike | Provider<any> |
+ *   EnvironmentLike | CredentialsLike | DockerLike` — and `GitHubCredentials` matches none of
+ *   them structurally). VERIFIED against upstream `Ruleset` (`node_modules/alchemy/src/GitHub/
+ *   Ruleset.ts`): its 5th slot is `GitHub.Providers`, the ProviderCollection tag `GitHub.
+ *   providers()` OUTPUTS — never the raw `GitHubCredentials` service upstream's OWN provider
+ *   handlers pull in via `octokitFor`. `GitHubCredentials` stays confined to the PROVIDER's
+ *   layer requirement (`Provider.succeed`'s inferred `ReadReq | DiffReq | ReconcileReq |
+ *   DeleteReq`, below), never the declaration's. Omitting the 5th parameter here defaults it to
+ *   `undefined`, so the declaration's own requirement becomes `Provider<RepositoryRuleset>` —
+ *   itself a `Provider<any>`, a real `ProviderServices` member — matching the pattern a
+ *   standalone (non-collection) resource actually needs. See `repoPolicyProviders()` in
+ *   repository-ruleset-providers.ts for the layer composition this now requires (the provider
+ *   still needs `GitHubCredentials` fed in — that half of the fix was already correct, per
+ *   `docs/repository-ruleset.md`).
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
-import type { GitHubCredentials, RulesetProps } from 'alchemy/GitHub';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import {
@@ -52,46 +74,16 @@ import {
 import { RulesetConstraintRefused } from './repository-ruleset-errors.ts';
 import { makeRulesetOctokit } from './repository-ruleset-octokit.ts';
 import { type RulesetRecord, probeByName } from './repository-ruleset-probe.ts';
+import type { RepositoryRulesetProps } from './repository-ruleset-props.ts';
 import { reconcileRuleset } from './repository-ruleset-reconcile.ts';
 
-type UpstreamRules = NonNullable<RulesetProps['rules']>;
-
-export interface RepositoryRulesetReviewerRule {
-  readonly filePatterns: readonly string[];
-  readonly minimumApprovals: number;
-  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
-}
-
-export interface RepositoryRulesetPullRequestRule extends NonNullable<
-  UpstreamRules['pullRequest']
-> {
-  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
-  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
-  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
-  /** `require_extra_approval_for_unattributed_changes` — see H15 above. Only `false` is
-   * modeled: sending `true` has no house use, and GitHub already defaults absent to `true`. */
-  readonly extraApprovalForUnattributedChanges?: false;
-}
-
-export interface RepositoryRulesetStatusChecksRule extends NonNullable<
-  UpstreamRules['requiredStatusChecks']
-> {
-  readonly doNotEnforceOnCreate?: boolean;
-}
-
-export interface RepositoryRulesetRules extends Omit<
-  UpstreamRules,
-  'pullRequest' | 'requiredStatusChecks'
-> {
-  readonly pullRequest?: RepositoryRulesetPullRequestRule;
-  /** `undefined`: no opinion (refused if the live ruleset already has one — see
-   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
-  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
-}
-
-export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
-  readonly rules?: RepositoryRulesetRules;
-}
+export type {
+  RepositoryRulesetProps,
+  RepositoryRulesetPullRequestRule,
+  RepositoryRulesetReviewerRule,
+  RepositoryRulesetRules,
+  RepositoryRulesetStatusChecksRule,
+} from './repository-ruleset-props.ts';
 
 export interface RepositoryRulesetAttributes {
   readonly rulesetId: number;
@@ -105,8 +97,10 @@ export interface RepositoryRuleset extends Resource<
   'GitHub.RepositoryRuleset',
   RepositoryRulesetProps,
   RepositoryRulesetAttributes,
-  never,
-  GitHubCredentials
+  never
+  // ⛔ NO 5th (`Providers`) ARGUMENT — see the file header. Defaulting it to `undefined` makes
+  // a `yield* RepositoryRuleset(...)` call site require `Provider<RepositoryRuleset>`, not
+  // `GitHubCredentials`; the credential requirement lives on the PROVIDER below instead.
 > {}
 
 export const RepositoryRuleset = Resource<RepositoryRuleset>('GitHub.RepositoryRuleset', {
@@ -124,7 +118,11 @@ export const attrsOf = (r: RulesetRecord): RepositoryRulesetAttributes => ({
 /** Plan-time-only refusals — no live data needed, so these run before any read (schema-codegen's
  * rule: check the form before the "no previous state" branch, never after it). */
 function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefused | undefined {
-  const approvals = props.rules?.pullRequest?.requiredApprovingReviewCount;
+  // `=== false` narrows `pullRequest` out of the `| false` half added for exact-adopt
+  // pass-through (see `RepositoryRulesetRules` above) — a declared absence has no fields to
+  // constrain.
+  const pr = props.rules?.pullRequest === false ? undefined : props.rules?.pullRequest;
+  const approvals = pr?.requiredApprovingReviewCount;
   if (approvals !== undefined) {
     const reason = approvalCountRefusal(approvals);
     if (reason !== undefined) {
@@ -134,7 +132,7 @@ function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefu
       });
     }
   }
-  const methods = props.rules?.pullRequest?.allowedMergeMethods;
+  const methods = pr?.allowedMergeMethods;
   if (methods !== undefined) {
     const reason = allowedMergeMethodsRefusal(methods);
     if (reason !== undefined) {
@@ -144,6 +142,18 @@ function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefu
       });
     }
   }
+  // ⚠️ NO SEPARATE PLAN-TIME CHECK FOR A BLANK `acknowledge{Bypass,Rule}Narrowing.reason` HERE.
+  //   A blank reason is already indistinguishable from "not acknowledged at all" —
+  //   `isBypassNarrowingAcknowledged`/`isRuleNarrowingAcknowledged`
+  //   (repository-ruleset-narrowing-guards.ts) each require a non-empty, trimmed `reason` on
+  //   their OWN prop, and the matching narrowing guard reads that, not presence alone. Adding a
+  //   SECOND check here would refuse with `RulesetConstraintRefused` instead of the more
+  //   specific `BypassActorNarrowed`/`RuleNarrowed` the caller actually needs to act on — and,
+  //   unlike those two (exercised directly through `reconcileRuleset`, injected-octokit fakes
+  //   included), this function is wired only through the real `RepositoryRuleset.Provider`
+  //   (`makeRulesetOctokit` needs live `GitHubCredentials`), which this family's own test
+  //   helpers do not exercise (see `repository-ruleset-test-helpers.ts`'s stub
+  //   `constraintRefusal`) — a check that lives only here would ship untested.
   return undefined;
 }