@homeflare/alchemy 0.28.0 → 0.29.1

package/src/caddy/providers.ts

@@ -6,12 +6,28 @@
  * ★ launchdProviders() TOO when the stack uses caddyWithFile(): the file is a launchd-subpath
  *   HostFile, written through that subpath's HostRunner.
  * ⚠️ The default is localCaddyAdmin(): `http://127.0.0.1:2019`, Caddy's default admin listener.
- *   Pass another CaddyAdmin for a unix socket, a narrowed `admin { origins }`, or an SSH forward.
+ *   Pass another CaddyTransport for a unix socket, a narrowed `admin { origins }`, or an SSH
+ *   forward — `localCaddyAdmin({ address, hostHeader })` builds one; a consumer can provide any
+ *   other `{ endpoint, listener, layer }` reaching `@distilled.cloud/caddy`'s own `Credentials`
+ *   and `HttpClient.HttpClient`.
+ *
+ * ⚠️ `Layer.provideMerge`, NEVER PLAIN `Layer.provide`, for `caddyAdminLayer`. `CaddyConfigProvider()`'s
+ *   `read`/`diff`/`reconcile` handlers each still need `CaddyAdminService` and
+ *   `@distilled.cloud/caddy`'s `Credentials`/`HttpClient` — Alchemy's own `Provider.effect` types
+ *   those as part of the LAYER's overall requirement (`ProviderService`'s per-handler `Req` type
+ *   parameters, `alchemy/Provider.ts`), for exactly this reason. Plain `Layer.provide` SEALS a
+ *   layer — it satisfies `CaddyConfigProvider()`'s requirement only for BUILDING the `Provider`
+ *   value (the `admin` in its outer `Effect.gen`), then hides those services from anything that
+ *   runs LATER, when the returned `read`/`diff`/`reconcile` FUNCTIONS actually execute. MEASURED
+ *   2026-09-23: with plain `Layer.provide`, `caddyProviders()`'s own `reconcile` handler dies with
+ *   "Service not found: homeflare/caddy/CaddyAdmin" the moment the ENGINE calls it. `provideMerge`
+ *   feeds `caddyAdminLayer`'s output into `CaddyConfigProvider()`'s requirement AND keeps that same
+ *   output live in the result, so every later handler call still runs with it in context.
  */
 import * as Layer from 'effect/Layer';
-import { type CaddyAdmin, caddyAdminLayer } from './admin.ts';
+import { type CaddyTransport, caddyAdminLayer } from './admin.ts';
 import { CaddyConfigProvider } from './config.ts';
 import { localCaddyAdmin } from './local-admin.ts';
 
-export const caddyProviders = (admin: CaddyAdmin = localCaddyAdmin()) =>
-  CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin)));
+export const caddyProviders = (transport: CaddyTransport = localCaddyAdmin()) =>
+  CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(transport)));

package/src/github/declare-repo-baseline-apply-order.test.ts

@@ -0,0 +1,86 @@
+/**
+ * `declareRepoBaseline` through Alchemy's own Plan+Apply (repo-apply-order-fake-stack.ts) — not
+ * the pure form functions — proving the K5 apply-ordering fix (repo-auto-merge-gate.ts) actually
+ * changes what the ENGINE schedules, the same reasoning `litellm/pass-through-endpoint-replace.
+ * test.ts`'s header gives for driving the engine instead of asserting a `diff` answer.
+ *
+ * ★ THE "TURNING ON" TESTS DEPLOY TWICE, ON PURPOSE. K5's own scenario is literally "a repo
+ *   MOVES from checks:[] to checks:['x']" — an UPDATE to an already-live repo and ruleset, not a
+ *   cold create. A first version of this file proved the ordering fix with a single deploy from
+ *   empty state instead (an ADVERSARIAL REVIEW, 2026-09-24, caught this: that single-deploy
+ *   shape is a cold create, and the fake ruleset provider back then had no notion that a real
+ *   ruleset create 404s against a repository that does not exist yet — so the test could not
+ *   have caught the ordering fix forcing exactly that impossible order on a genuine cold create).
+ *   Deploying `checks: []` first, then `checks: ['ci']`, makes both resources already live by
+ *   the time the gate kicks in — the actual K5 shape, and no longer a cold create.
+ */
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { declareRepoBaseline } from './declare-repo-baseline.ts';
+import { type World, fakeGithubProviders, makeWorld } from './repo-apply-order-fake-providers.ts';
+import { fakeStack } from './repo-apply-order-fake-stack.ts';
+
+let world: World;
+let stack: ReturnType<typeof fakeStack>;
+beforeEach(() => {
+  world = makeWorld();
+  stack = fakeStack(fakeGithubProviders(world));
+});
+
+const declare = (checks: readonly string[]) =>
+  declareRepoBaseline('acme', {
+    owner: 'taslabs-net',
+    repository: 'acme',
+    checks,
+    visibility: 'private',
+  });
+
+describe('an existing repo moving from checks: [] to checks: ["ci"]', () => {
+  beforeEach(async () => {
+    // Establish both as already-live, exactly like a repo baselined with no checks yet.
+    await stack.deploy(declare([]));
+    world.calls.length = 0;
+  });
+
+  test('the update that turns auto-merge on applies the ruleset before the repository', async () => {
+    const planned = await stack.deploy(declare(['ci']));
+
+    expect(planned).toEqual({ acme: 'update', 'acme-ruleset': 'update' });
+    expect(world.calls).toEqual(['ruleset', 'repository']);
+    // The value sent is still exactly `true` — only the ordering changed.
+    expect(world.repositoryAllowAutoMerge).toBe(true);
+  });
+
+  test('a ruleset apply failure leaves allowAutoMerge untouched', async () => {
+    world.rulesetShouldFail = true;
+
+    await expect(stack.deploy(declare(['ci']))).rejects.toBeDefined();
+
+    // The repository's `reconcile` never ran at all — blocked on the ruleset's Output, which
+    // never resolved — so `allowAutoMerge` was never even sent, let alone turned on with no
+    // required check live. It is still `false` from the first deploy above.
+    expect(world.calls).toEqual(['ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBe(false);
+  });
+});
+
+describe('auto-merge already/staying off (checks: [])', () => {
+  test('declares both with no ordering edge forced between them', async () => {
+    const planned = await stack.deploy(declare([]));
+
+    expect(planned).toEqual({ acme: 'create', 'acme-ruleset': 'create' });
+    expect(world.calls.sort()).toEqual(['repository', 'ruleset']);
+    // `allowAutoMerge` was sent as a plain `false`, never gated on the ruleset.
+    expect(world.repositoryAllowAutoMerge).toBe(false);
+  });
+});
+
+describe('a repo and ruleset created together for the first time, checks from day one', () => {
+  test('fails clearly instead of silently fail-open (known, documented limit — see file header)', async () => {
+    await expect(stack.deploy(declare(['ci']))).rejects.toThrow(/does not exist yet/);
+
+    // The ruleset's own create is what refuses — never the repository's, and never a state
+    // where allowAutoMerge went live with nothing to wait on.
+    expect(world.calls).toEqual(['ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBeUndefined();
+  });
+});

package/src/github/declare-repo-baseline.ts

@@ -8,16 +8,34 @@
  *       visibility: 'private',
  *     });
  *
- * Provide `GitHub.providers()` AND `RepositoryRulesetProvider()` — this subpath ships no
- * provider of its own, the same as `declareRepoPolicy`. Both resources are `retain` and
- * `adopt(true)` ALWAYS, unlike `declareRepoPolicy`'s optional `adopt` — a baseline this widely
- * shared is meant for a checkout adopting the estate's existing repository and ruleset by name,
- * never for creating one out from under a caller who forgot the flag (H1: a name match is not
- * ours until adopted).
+ * Provide `repoPolicyProviders()` (repository-ruleset-providers.ts) — this subpath ships no
+ * provider of its own beyond the ruleset bridge, the same as `declareRepoPolicy`. Both resources
+ * are `retain` and `adopt(true)` ALWAYS, unlike `declareRepoPolicy`'s optional `adopt` — a
+ * baseline this widely shared is meant for a checkout adopting the estate's existing repository
+ * and ruleset by name, never for creating one out from under a caller who forgot the flag (H1: a
+ * name match is not ours until adopted).
  *
  * ⛔ NO IMPORT FROM `@homeflare/config`, either direction — see `renderRepoShape`'s own header
  *   in `packages/config/src/repo-shape/render.ts`. A caller spreads `renderRepoShape(shape)
  *   .policy` into these options itself; `checks` only needs to be `readonly string[]`.
+ *
+ * ⛔ APPLY ORDER: `allowAutoMerge` NEVER GOES LIVE BEFORE THE RULESET IT WAITS ON. When `checks`
+ *   is non-empty, the ruleset is declared and applied FIRST, and the repository's `allowAutoMerge`
+ *   is threaded through `gateAutoMergeOnRuleset` (repo-auto-merge-gate.ts) so Alchemy's own
+ *   Output-in-props ordering — not declaration order — makes the engine wait for it. See that
+ *   file's header for the full mechanism, the K5 hazard it closes, and why the reverse direction
+ *   (checks removed) needs no matching edge.
+ * ⚠️ A REPOSITORY THAT DOES NOT YET EXIST: `adopt(true)` above does NOT refuse to create — with
+ *   nothing live to adopt, Alchemy creates from scratch regardless (`AdoptPolicy`'s own contract:
+ *   `undefined` observed state means create, adopt policy or not). The paragraph above says this
+ *   baseline is "never for creating one out from under a caller who forgot the flag", but nothing
+ *   enforces that; it is the caller's discipline, not this function's. If it IS ever called for a
+ *   repo+ruleset that do not exist yet with `checks` non-empty from day one, the forced
+ *   ruleset-first order above now makes the ruleset's create fail — GitHub's own ruleset API
+ *   404s on a repository that does not exist — instead of racing. That failure is explicit and
+ *   tested (declare-repo-baseline-apply-order.test.ts's "created together" case), not a silent
+ *   fail-open, but it is still a real usability regression for that one scenario: create the bare
+ *   repository first (a prior deploy, or a separate `GitHub.Repository` call).
  */
 import { adopt } from 'alchemy/AdoptPolicy';
 import * as GitHub from 'alchemy/GitHub';
@@ -28,6 +46,7 @@ import {
   repoBaselineRuleset,
   repoBaselineSettings,
 } from './repo-baseline-data.ts';
+import { gateAutoMergeOnRuleset } from './repo-auto-merge-gate.ts';
 import { RepositoryRuleset } from './repository-ruleset.ts';
 
 export interface DeclareRepoBaselineOptions extends RepoBaselineInput {}
@@ -36,7 +55,21 @@ export const declareRepoBaseline = (id: string, options: DeclareRepoBaselineOpti
   Effect.gen(function* () {
     const owned = <A, R>(resource: Effect.Effect<A, never, R>) =>
       resource.pipe(RemovalPolicy.retain(), adopt(true));
-    const repository = yield* owned(GitHub.Repository(id, repoBaselineSettings(options)));
+    const settings = repoBaselineSettings(options);
+
+    // Auto-merge is turning on (or staying on): declare and apply the ruleset FIRST, so its
+    // rulesetId is available to gate the repository's allowAutoMerge — see the file header.
+    if (settings.allowAutoMerge) {
+      const ruleset = yield* owned(
+        RepositoryRuleset(`${id}-ruleset`, repoBaselineRuleset(options)),
+      );
+      const repository = yield* owned(
+        GitHub.Repository(id, gateAutoMergeOnRuleset(settings, ruleset)),
+      );
+      return { repository, ruleset };
+    }
+
+    const repository = yield* owned(GitHub.Repository(id, settings));
     const ruleset = yield* owned(RepositoryRuleset(`${id}-ruleset`, repoBaselineRuleset(options)));
     return { repository, ruleset };
   });

package/src/github/index.ts

@@ -3,10 +3,13 @@
  * one bridge resource this house builds atop upstream GitHub: `GitHub.RepositoryRuleset`.
  *
  * ⚠️ `declareRepoPolicy`/`declareRepoBaseline` COMPOSE UPSTREAM `GitHub.Repository` PLUS THIS
- *   SUBPATH'S OWN `RepositoryRulesetProvider()` — provide BOTH `GitHub.providers()` and
- *   `RepositoryRulesetProvider()`. Before 2026-09-23 this subpath shipped no provider at all,
- *   composing only vendor resources; `RepositoryRuleset` is the one exception, and
- *   repository-ruleset.ts's header says why upstream's own `Ruleset` cannot fill the gap.
+ *   SUBPATH'S OWN `RepositoryRulesetProvider()` — provide `repoPolicyProviders()`
+ *   (repository-ruleset-providers.ts), the composed `GitHub.providers()` +
+ *   `RepositoryRulesetProvider()` layer that actually typechecks (2026-09-24: writing the two
+ *   side by side leaves `RepositoryRulesetProvider()`'s own `GitHubCredentials` requirement
+ *   unfed). Before 2026-09-23 this subpath shipped no provider at all, composing only vendor
+ *   resources; `RepositoryRuleset` is the one exception, and repository-ruleset.ts's header
+ *   says why upstream's own `Ruleset` cannot fill the gap.
  * ★ WHY THE POLICY HELPERS EXIST. "Open a pull request, let auto-merge land it" is safe only
  *   when five repository properties and four ruleset rules all agree, and every way of getting
  *   one of them wrong is silent — an auto-merge that lands on red, a force push that rewrites
@@ -42,6 +45,7 @@ export {
   type RepositoryRulesetRules,
   type RepositoryRulesetStatusChecksRule,
 } from './repository-ruleset.ts';
+export { repoPolicyProviders } from './repository-ruleset-providers.ts';
 export { RULE_TYPE_COVERAGE, type RepositoryRuleType } from './repository-ruleset-constraints.ts';
 export {
   BypassActorNarrowed,

package/src/github/repo-apply-order-fake-providers.ts

@@ -0,0 +1,119 @@
+/**
+ * Fully in-memory `Provider.succeed(...)` fakes for `GitHub.Repository` and `RepositoryRuleset`
+ * — no octokit, no `GitHubCredentials`, no network. Unlike `repository-ruleset-fake-octokit.ts`
+ * (a fake HTTP client fed into the REAL provider's `reconcile`), these fakes replace the provider
+ * entirely, because what `declare-repo-baseline-apply-order.test.ts` and
+ * `repo-policy-apply-order.test.ts` measure is the ENGINE's own scheduling — which resource's
+ * `reconcile` runs first, and whether one's failure reaches the other — not GitHub's wire
+ * protocol. `Provider.succeed`'s runtime lookup (`tryFindProviderRegistrationByType`,
+ * `node_modules/alchemy/src/Provider.ts`) checks the INDIVIDUAL `Provider<R>` tag before falling
+ * back to a `GitHub.Providers` collection, so registering these two standalone providers is
+ * enough regardless of `GitHub.Repository`'s own declared `Providers` slot — the same shortcut
+ * `RepositoryRulesetProvider()` already relies on.
+ *
+ * ⚠️ NO LIVE NETWORK, EVER. Nothing here imports `octokit`/`GitHubCredentials`, so a test built
+ *   on this file cannot make a real GitHub call even by accident — required by this PR's own
+ *   "no live GitHub writes" rule.
+ *
+ * ⚠️ THE FAKE RULESET REFUSES A REPO THAT DOESN'T EXIST YET, ON PURPOSE — mirroring GitHub's own
+ *   `POST /repos/{owner}/{repo}/rulesets`, which 404s on a repo that hasn't been created. A first
+ *   ADVERSARIAL REVIEW pass (2026-09-24) on this PR found that the ordering fix forces the
+ *   ruleset to apply before the repository whenever auto-merge turns on — safe for an UPDATE
+ *   (the repo already exists), but a real hazard for a repo+ruleset created together for the
+ *   FIRST time with checks set from day one, and the original version of this fake modeled no
+ *   such constraint, so its own tests could not have caught that regression. It now can — see
+ *   `declare-repo-baseline-apply-order.test.ts`'s "a repo and ruleset created together" test.
+ */
+import * as GitHub from 'alchemy/GitHub';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { RepositoryRuleset, type RepositoryRulesetProps } from './repository-ruleset.ts';
+
+/** One resource type's name, in the order its fake `reconcile` was actually invoked. */
+export type CallLog = ('repository' | 'ruleset')[];
+
+export interface World {
+  readonly calls: CallLog;
+  /** `owner/name` of every repository the fake repository provider has reconciled at least
+   * once — what the fake ruleset provider checks before allowing a create. */
+  readonly liveRepositories: Set<string>;
+  /** Set before `deploy` to make the ruleset's `reconcile` fail instead of succeeding, even
+   * against a repository already in `liveRepositories`. */
+  rulesetShouldFail: boolean;
+  /** `news.allowAutoMerge` as the repository's fake `reconcile` last observed it — `undefined`
+   * until (unless) the repository's `reconcile` actually runs. */
+  repositoryAllowAutoMerge: boolean | undefined;
+}
+
+export const makeWorld = (): World => ({
+  calls: [],
+  liveRepositories: new Set(),
+  rulesetShouldFail: false,
+  repositoryAllowAutoMerge: undefined,
+});
+
+let sequence = 0;
+const nextId = () => {
+  sequence += 1;
+  return sequence;
+};
+
+const fakeRepositoryProvider = (world: World) =>
+  Provider.succeed(GitHub.Repository, {
+    list: () => Effect.succeed([]),
+    reconcile: ({ news }: { readonly news: GitHub.RepositoryProps }) =>
+      Effect.sync(() => {
+        world.calls.push('repository');
+        world.repositoryAllowAutoMerge = news.allowAutoMerge;
+        const id = nextId();
+        const fullName = `${news.owner}/${news.name}`;
+        world.liveRepositories.add(fullName);
+        return {
+          repoId: id,
+          nodeId: `repo-node-${id}`,
+          fullName,
+          htmlUrl: `https://github.com/${fullName}`,
+          gitUrl: `git://github.com/${fullName}.git`,
+          sshUrl: `git@github.com:${fullName}.git`,
+          cloneUrl: `https://github.com/${fullName}.git`,
+          defaultBranch: 'main',
+          createdAt: new Date(0).toISOString(),
+          updatedAt: new Date(0).toISOString(),
+        };
+      }),
+    delete: () => Effect.void,
+  });
+
+const fakeRulesetProvider = (world: World) =>
+  Provider.succeed(RepositoryRuleset, {
+    list: () => Effect.succeed([]),
+    reconcile: ({ news }: { readonly news: RepositoryRulesetProps }) =>
+      Effect.gen(function* () {
+        world.calls.push('ruleset');
+        if (world.rulesetShouldFail) {
+          return yield* Effect.fail(new Error('fake ruleset apply failure'));
+        }
+        const fullName = `${news.owner}/${news.repository}`;
+        if (!world.liveRepositories.has(fullName)) {
+          // The real `POST /repos/{owner}/{repo}/rulesets` 404s here — the target repository
+          // does not exist yet. See this file's header.
+          return yield* Effect.fail(
+            new Error(`fake GitHub 404: repository '${fullName}' does not exist yet`),
+          );
+        }
+        const id = nextId();
+        return {
+          rulesetId: id,
+          nodeId: `ruleset-node-${id}`,
+          name: news.name,
+          createdAt: new Date(0).toISOString(),
+          updatedAt: new Date(0).toISOString(),
+        };
+      }),
+    delete: () => Effect.void,
+  });
+
+/** Both fakes, merged — everything `declareRepoBaseline`/`declareRepoPolicy` need. */
+export const fakeGithubProviders = (world: World) =>
+  Layer.mergeAll(fakeRepositoryProvider(world), fakeRulesetProvider(world));

package/src/github/repo-apply-order-fake-stack.ts

@@ -0,0 +1,74 @@
+/**
+ * Alchemy's own `Plan.make`/`apply`, run in-process over an in-memory state store, for
+ * `declare-repo-baseline-apply-order.test.ts` and `repo-policy-apply-order.test.ts`.
+ *
+ * ★ SAME SHAPE AS `litellm/fake-stack.ts` AND `openbao/fake-stack.ts` — copied, not
+ *   reinvented: those two files' own headers explain why the ENGINE has to run (a `diff`/`props`
+ *   answer proves nothing about what Apply actually schedules) rather than calling provider
+ *   handlers directly, which is exactly what this PR needs to prove about apply ORDER. The casts
+ *   below sit at the same typed boundary theirs do — `Alchemy.Stack` types its body against
+ *   every service a CLI run provides; this harness's body only ever needs the providers given.
+ */
+import * as Alchemy from 'alchemy';
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import { provideFreshArtifactStore } from 'alchemy/Artifacts';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+export type Planned = Readonly<Record<string, string>>;
+export type StackBody = Effect.Effect<unknown, unknown, unknown>;
+export type DeployOptions = { readonly adopt?: boolean };
+
+export interface FakeStack {
+  /** Plan, then apply, `body`. Resolves to the plan; rejects with the apply's failure. */
+  readonly deploy: (body: StackBody, options?: DeployOptions) => Promise<Planned>;
+}
+
+type Node = { readonly action: string };
+type PlanView = {
+  readonly resources: Readonly<Record<string, Node>>;
+  readonly deletions: Readonly<Record<string, Node | undefined>>;
+};
+
+const actionsOf = (plan: PlanView): Planned => {
+  const out: Record<string, string> = {};
+  for (const [fqn, node] of Object.entries(plan.resources)) out[fqn] = node.action;
+  for (const [fqn, node] of Object.entries(plan.deletions)) {
+    if (node !== undefined) out[fqn] = node.action;
+  }
+  return out;
+};
+
+export const fakeStack = <ROut, E, RIn>(
+  providers: Layer.Layer<ROut, E, RIn>,
+  name = 'RepoApplyOrderStack',
+): FakeStack => {
+  const state = Alchemy.inMemoryState();
+  const stack = Alchemy.Stack as unknown as (
+    stackName: string,
+    options: { providers: typeof providers; state: typeof state },
+    body: StackBody,
+  ) => Effect.Effect<{ readonly services: never }, unknown, never>;
+  const plan = Alchemy.Plan.make as unknown as (
+    compiled: unknown,
+  ) => Effect.Effect<PlanView, unknown, never>;
+  const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+
+  const deploy = (body: StackBody, options: DeployOptions = {}) =>
+    Effect.gen(function* () {
+      const compiled = yield* stack(name, { providers, state }, body);
+      return yield* Effect.gen(function* () {
+        const planned = yield* plan(compiled);
+        yield* apply(planned);
+        return actionsOf(planned);
+      }).pipe(provideFreshArtifactStore, Effect.provide(Layer.succeedContext(compiled.services)));
+    }).pipe(
+      options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.scoped,
+    );
+
+  return {
+    deploy: (body, options) => Effect.runPromise(deploy(body, options) as Effect.Effect<Planned>),
+  };
+};

package/src/github/repo-auto-merge-gate.ts

@@ -0,0 +1,57 @@
+/**
+ * `gateAutoMergeOnRuleset` — the one place `declareRepoBaseline` and `declareRepoPolicy` thread
+ * a real apply-ordering edge from `GitHub.Repository`'s `allowAutoMerge` to the sibling
+ * `RepositoryRuleset`, so a deploy can never turn auto-merge on before the ruleset's required
+ * checks/approvals are actually live.
+ *
+ * ⛔ K5 (kit PR 216, 2026-09-24): both callers declare `GitHub.Repository` and `RepositoryRuleset`
+ *   as two INDEPENDENT resources with no dependency edge between them. When a repo moves from
+ *   `checks:[]` to `checks:['x']`, `allowAutoMerge` flips to `true` in the very same deploy that
+ *   adds the required check. If the Repository apply lands before the Ruleset apply — or the
+ *   Ruleset apply fails outright — the repo ends up with auto-merge on and nothing required: `gh
+ *   pr merge --auto` merges a CLEAN pull request immediately (memory `gh-auto-merge-merges-now`).
+ *   That fail-open state is exactly what K5 exists to prevent.
+ *
+ * ★ THE MECHANISM — ALCHEMY ORDERS BY OUTPUT REFERENCES IN PROPS, NOT DECLARATION ORDER.
+ *   `Plan.ts` (~l.1031-1038): a resource's upstream deps are `Output.upstreamAny(resource.Props)`.
+ *   `Apply.ts` (~l.760-762, ~l.909): `waitForDeps(allUpstreamFqns())` — built the same way from
+ *   `Output.resolveUpstream(node.props)` — runs before `reconcile`. See the kit's own
+ *   `alchemy-output-refs-order-resources` memory. `GitHub.Repository`'s upstream `RepositoryProps`
+ *   has no spare field: `reconcile` (`node_modules/alchemy/src/GitHub/Repository.ts`) sends every
+ *   declared prop straight to Octokit's create/update calls, so there is nothing to smuggle an
+ *   unrelated Output into. `allowAutoMerge` itself is the vehicle instead: its value is still
+ *   exactly `true` whenever this function is called with it already `true` — only now computed
+ *   AFTER `ruleset.rulesetId` resolves via `Output.map`, instead of written as a literal. That
+ *   single Output reference is enough for `Output.upstreamAny` to record the ruleset as this
+ *   Repository's upstream dependency, so the engine applies the ruleset first.
+ *
+ * ★ WHY THIS NEEDS NO REVERSE-DIRECTION EDGE. The opposite transition — checks/approvals
+ *   REMOVED, so `allowAutoMerge` turns off — cannot silently race the other way. Neither caller
+ *   ever declares `rules.requiredStatusChecks: false` or omits `rules.pullRequest` on purpose;
+ *   dropping `checks`/`requiredApprovals` from the options just OMITS the corresponding rule key.
+ *   `requiredChecksOmissionRefusal` and `undeclaredLiveRuleRefusal` (repository-ruleset-guards.ts)
+ *   both refuse — unconditionally, regardless of apply order — to drop a rule that is still LIVE
+ *   by omission. So the worst reachable state, whichever resource applies first, is: Repository
+ *   succeeds (auto-merge off, the correct direction anyway) and Ruleset refuses (the live rule
+ *   stays required) — never fail-open. Proved by the ordering/failure tests beside this file.
+ */
+import * as Output from 'alchemy/Output';
+
+/** The one attribute this gate needs from a declared `RepositoryRuleset`. */
+export interface AutoMergeGateSource {
+  readonly rulesetId: Output.Output<number, never>;
+}
+
+/**
+ * Returns `settings` unchanged when `allowAutoMerge` is falsy — nothing to gate, and every
+ * existing declaration with auto-merge off keeps its exact prior props (no diff, no replan).
+ * Otherwise returns `settings` with `allowAutoMerge` recomputed as an Output.map over
+ * `ruleset.rulesetId` — still resolves to `true`, now with a real dependency edge attached.
+ */
+export function gateAutoMergeOnRuleset<P extends { readonly allowAutoMerge?: boolean }>(
+  settings: P,
+  ruleset: AutoMergeGateSource,
+): P | (Omit<P, 'allowAutoMerge'> & { readonly allowAutoMerge: Output.Output<boolean, never> }) {
+  if (!settings.allowAutoMerge) return settings;
+  return { ...settings, allowAutoMerge: Output.map(ruleset.rulesetId, () => true) };
+}

package/src/github/repo-baseline-data.test.ts

@@ -36,6 +36,19 @@ describe('repoBaselineSettings', () => {
       visibility: undefined,
     });
   });
+
+  // K5 (2026-09-24): zero required checks means `gh pr merge --auto` has nothing to wait for —
+  // GitHub merges a CLEAN pull request immediately, with no review and no green run. Regression
+  // for repoBaselineSettings hardcoding `allowAutoMerge: true` regardless of `checks`.
+  test('zero checks turns auto-merge off — nothing would ever hold a merge back', () => {
+    const settings = repoBaselineSettings({ ...input, checks: [] });
+    expect(settings.allowAutoMerge).toBe(false);
+  });
+
+  test('at least one check keeps auto-merge on', () => {
+    const settings = repoBaselineSettings({ ...input, checks: ['ci'] });
+    expect(settings.allowAutoMerge).toBe(true);
+  });
 });
 
 describe('repoBaselineRuleset', () => {

package/src/github/repo-baseline-data.ts

@@ -21,7 +21,16 @@ export interface RepoBaselineInput {
 
 /** `GitHub.Repository` fields this baseline owns. Every merge-automation caller across the 17
  * tray checkouts uses `--squash` (measured 2026-09-23; the only non-squash mentions are
- * GitLab-era comments in cliff.toml), so squash-only is not a per-repo choice. */
+ * GitLab-era comments in cliff.toml), so squash-only is not a per-repo choice.
+ *
+ * ⛔ K5 (2026-09-24): `allowAutoMerge` FOLLOWS `checks.length`, NOT A HARDCODED `true`. `gh pr
+ *   merge --auto` (and the ruleset's own auto-merge) is a queue only while something is
+ *   outstanding — with zero required status checks there is nothing to wait for, so GitHub
+ *   merges a CLEAN pull request on the spot, with no review and no green run. This is the same
+ *   failure `repo-policy-guards.ts`'s `assertAutoMergeWaits` refuses on the sibling `repoPolicy`
+ *   path (five doors to the same "nothing outstanding" state); this baseline has no `autoMerge`
+ *   opt-out prop to refuse WITH, so the fix here is unconditional rather than a thrown refusal —
+ *   a repo with an empty `checks` list simply never gets auto-merge turned on by this baseline. */
 export function repoBaselineSettings(input: RepoBaselineInput) {
   return {
     owner: input.owner,
@@ -31,7 +40,7 @@ export function repoBaselineSettings(input: RepoBaselineInput) {
     allowSquashMerge: true,
     allowMergeCommit: false,
     allowRebaseMerge: false,
-    allowAutoMerge: true,
+    allowAutoMerge: input.checks.length > 0,
     deleteBranchOnMerge: true,
     hasWiki: false,
   };

package/src/github/repo-policy-apply-order.test.ts

@@ -0,0 +1,72 @@
+/**
+ * `declareRepoPolicy` through Alchemy's own Plan+Apply (repo-apply-order-fake-stack.ts) — the
+ * same K5 apply-ordering proof as declare-repo-baseline-apply-order.test.ts, for the OTHER
+ * caller of `gateAutoMergeOnRuleset`. See that file's header for why the "turning on" tests
+ * deploy twice (K5's own scenario is an update to an already-live repo+ruleset, not a cold
+ * create) and for the cold-create limitation this suite also tests explicitly.
+ */
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { type World, fakeGithubProviders, makeWorld } from './repo-apply-order-fake-providers.ts';
+import { fakeStack } from './repo-apply-order-fake-stack.ts';
+import { declareRepoPolicy } from './repo-policy.ts';
+
+let world: World;
+let stack: ReturnType<typeof fakeStack>;
+beforeEach(() => {
+  world = makeWorld();
+  stack = fakeStack(fakeGithubProviders(world));
+});
+
+const declare = (checks: readonly string[]) =>
+  declareRepoPolicy('api', { owner: 'taslabs-net', repository: 'api', checks });
+
+const declareOff = () =>
+  declareRepoPolicy('api', {
+    owner: 'taslabs-net',
+    repository: 'api',
+    checks: [],
+    autoMerge: false,
+  });
+
+describe('an existing repo moving from checks: [] to checks: ["ci"]', () => {
+  beforeEach(async () => {
+    await stack.deploy(declareOff());
+    world.calls.length = 0;
+  });
+
+  test('the update that turns auto-merge on applies the ruleset before the repository', async () => {
+    const planned = await stack.deploy(declare(['ci']));
+
+    expect(planned).toEqual({ api: 'update', 'api-ruleset': 'update' });
+    expect(world.calls).toEqual(['ruleset', 'repository']);
+    expect(world.repositoryAllowAutoMerge).toBe(true);
+  });
+
+  test('a ruleset apply failure leaves allowAutoMerge untouched', async () => {
+    world.rulesetShouldFail = true;
+
+    await expect(stack.deploy(declare(['ci']))).rejects.toBeDefined();
+
+    expect(world.calls).toEqual(['ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBe(false);
+  });
+});
+
+describe('auto-merge off (autoMerge: false, no checks)', () => {
+  test('declares both with no ordering edge forced between them', async () => {
+    const planned = await stack.deploy(declareOff());
+
+    expect(planned).toEqual({ api: 'create', 'api-ruleset': 'create' });
+    expect(world.calls.sort()).toEqual(['repository', 'ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBe(false);
+  });
+});
+
+describe('a repo and ruleset created together for the first time, checks from day one', () => {
+  test('fails clearly instead of silently fail-open (known, documented limit)', async () => {
+    await expect(stack.deploy(declare(['ci']))).rejects.toThrow(/does not exist yet/);
+
+    expect(world.calls).toEqual(['ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBeUndefined();
+  });
+});

package/src/github/repo-policy-stack.test.ts

@@ -0,0 +1,59 @@
+/**
+ * TYPE-LEVEL test — a real `Alchemy.Stack(...)` whose body calls `declareRepoPolicy` AND
+ * `declareRepoBaseline`, wired with the documented `repoPolicyProviders()`. This is the test
+ * that would have caught 2026-09-24's bug (homeflare-builds bump PR 6, tsc TS2345):
+ * `RepositoryRuleset`'s `Resource<>` declaration put `GitHubCredentials` — not
+ * `Provider<RepositoryRuleset>` — in its 5th type parameter, so a stack BODY that only ever
+ * calls `declareRepoPolicy`/`declareRepoBaseline` failed `tsc`, and nothing in this repo's own
+ * `bun run check` exercised that path before now: every existing test in this family drives the
+ * resource's CRUD handlers directly (repository-ruleset-*.test.ts) or the pure form functions
+ * (repo-policy-form.test.ts), never a real `Alchemy.Stack(...)` body.
+ *
+ * ⚠️ BUILT, NEVER RUN. `Alchemy.Stack(...)` returns an unexecuted `Effect` — every combinator
+ *   between here and a runtime (`.pipe`, `Effect.gen`, `Effect.flatMap`, `Object.assign`) is
+ *   itself lazy (MEASURED by reading `alchemy/src/Stack.ts`'s own `Stack`/`make`: no
+ *   `Effect.runSync`/`runPromise` anywhere in the construction path). Building the value is
+ *   enough to make `tsc` check the body's inferred requirement type against `Stack`'s own
+ *   `Req extends StackServices | ProviderServices` constraint — see repository-ruleset.ts's
+ *   file header for what that constraint is and why `GitHubCredentials` used to fail it. This
+ *   test never calls `Effect.runPromise`/`runSync`: no network, no `GitHubCredentials`
+ *   resolved, no state written.
+ *
+ * ⚠️ `.pipe(Effect.orDie)` ON `declareRepoPolicy` IS UNRELATED TO WHAT THIS TEST CHECKS.
+ *   `declareRepoPolicy` refuses a bad policy through `Effect.try`'s `catch`, so its error
+ *   channel is `Error`, not `never` — a separate, pre-existing type surface (present since its
+ *   original PR #98) that `Alchemy.Stack`'s own `eff: Effect.Effect<A, ConfigError, Req>` does
+ *   not accept regardless of the `Req`/`Providers` bug this test targets. Dying on it here keeps
+ *   that surface out of the way without papering over it — a real caller still has to decide how
+ *   to handle a refused policy, which this test deliberately does not answer.
+ */
+import { expect, test } from 'bun:test';
+import * as Alchemy from 'alchemy';
+import * as Effect from 'effect/Effect';
+import { declareRepoBaseline } from './declare-repo-baseline.ts';
+import { declareRepoPolicy } from './repo-policy.ts';
+import { repoPolicyProviders } from './repository-ruleset-providers.ts';
+
+test('declareRepoPolicy and declareRepoBaseline typecheck as one Alchemy.Stack body', () => {
+  const stack = Alchemy.Stack(
+    'repo-policy-typecheck',
+    { providers: repoPolicyProviders(), state: Alchemy.inMemoryState() },
+    Effect.gen(function* () {
+      const policy = yield* declareRepoPolicy('api', {
+        owner: 'taslabs-net',
+        repository: 'api',
+        checks: ['ci', 'secret scan'],
+      }).pipe(Effect.orDie);
+      const baseline = yield* declareRepoBaseline('widgets', {
+        owner: 'taslabs-net',
+        repository: 'widgets',
+        checks: ['ci'],
+        visibility: 'private',
+      });
+      return { policy, baseline };
+    }),
+  );
+  // Not run — see file header. This only proves construction didn't throw synchronously; the
+  // real assertion is `tsc`'s, over the whole expression above.
+  expect(stack).toBeDefined();
+});