dorfl 0.1.2 → 0.2.0

package/src/install-ci-branch-protection.ts

@@ -34,28 +34,44 @@
  * change can flip it knowingly; the spec calls this "pick the cheaper of the
  * two and record the choice."
  *
- * DEADLOCK GUARD — a NEVER-RUN required check would block every merge (GitHub
- * treats an unreported required check as pending). install-ci ORDERS the steps
- * to avoid that:
+ * DEFAULT BRANCH — NOT hardcoded to `main`. The GitHub adapter resolves the
+ * repo's real default branch ({@link CIProviderContext.getDefaultBranch}, via
+ * `gh repo view --json defaultBranchRef`); the orchestrator threads it into
+ * BOTH the classic PUT and the printed `gh api` fallback so a `master`-defaulted
+ * (or otherwise-renamed) repo is protected on the correct branch instead of
+ * 404-ing a hardcoded `main`. The lookup falls back to {@link
+ * DEFAULT_PROTECTED_BRANCH} (`main`) only when it fails/empties, and that
+ * fallback is LOGGED so it is visible. An explicit `branch` option still wins
+ * over auto-detection (a repo whose protected branch is not its default).
  *
- *   1. write the verify workflow artifact (the `verify.yml` whose job is named
- *      exactly {@link VERIFY_CHECK_CONTEXT}); the human commits + pushes it to
- *      `main` so the workflow file lands BEFORE the next PR;
- *   2. THEN (this step) set the branch-protection rule.
+ * DEADLOCK GUARD — a required check that has NEVER reported blocks every merge
+ * (GitHub treats an unreported required check as pending), so a PR opened before
+ * `verify.yml` first ran would deadlock. The guard is a RUNTIME MECHANISM, not a
+ * log line: the required-`verify` check is enforced through a branch RULESET
+ * ({@link buildBranchProtectionRuleset}, `POST /repos/{owner}/{repo}/rulesets`)
+ * whose `required_status_checks` rule carries `do_not_enforce_on_create: true` —
+ * GitHub's native "require this check, but do not fail refs created before the
+ * rule / before the check first ran" toggle. The ruleset targets the resolved
+ * default branch via `conditions.ref_name`.
  *
- * Because the verify workflow uses `on: pull_request`, every PR opened AFTER
- * `verify.yml` is on `main` triggers the workflow and produces the required
- * `verify` check — the protection never deadlocks new PRs. The only edge case
- * is an IN-FLIGHT PR opened BEFORE `verify.yml` landed on `main`: it has no
- * `verify` check waiting; installCI prints exactly that re-trigger remediation
- * in the success log. We chose this "run-the-check-once-by-construction-of-the-
- * trigger" ordering over the ruleset `do_not_enforce_on_create` toggle because
- * (a) one PUT against the existing branch-protection endpoint is simpler than
- * minting a ruleset shape this spec otherwise does not need, AND (b) the
- * `merge_queue` Tier-2 forward seam already lives in the verify workflow's
- * `on:` trigger (so the ruleset seam is not needed here either — it is the
- * follow-on spec's lever). Trade-off RECORDED so a future merge-queue task can
- * flip to rulesets knowingly without re-deciding why we did not now.
+ * WHY RULESET FOR THE GUARD BUT CLASSIC PUT FOR THE BASE (nit-a preserved).
+ * The base protection stays a single classic PUT
+ * ({@link buildBranchProtectionSpec}: `strict: true` = "require branches up to
+ * date before merging") because that endpoint is the simplest way to express
+ * up-to-date-ness and nit-a ratified the classic-PUT choice. ONLY the deadlock-
+ * prone piece — the required-status-check gate — moves to a ruleset, because the
+ * `do_not_enforce_on_create` create-exemption exists ONLY on rulesets, not on
+ * the classic `required_status_checks` object. Keeping the required check in the
+ * classic PUT AND adding the ruleset would double-enforce it and NULLIFY the
+ * exemption (the classic copy has no exemption), so the required check lives in
+ * the ruleset ALONE; the classic PUT keeps `strict` with an EMPTY `checks`
+ * array (valid: "require up to date", no named required check at the classic
+ * layer). This is exactly "only the deadlock-guard aspect needs the ruleset" —
+ * not a full base-protection migration. Chosen over the pre-run mechanism
+ * (`gh workflow run` + wait) because `writeArtifacts` writes `verify.yml`
+ * LOCALLY and does NOT push, so at install time the workflow is not yet on the
+ * default branch and a pre-run has nothing to dispatch. The ruleset toggle needs
+ * no pushed workflow and no wait, so it is the only viable runtime guard here.
  */
 
 import {VERIFY_CHECK_CONTEXT} from './verify-workflow-template.js';
@@ -64,15 +80,17 @@ import type {CIProviderContext} from './install-ci-core.js';
 export {VERIFY_CHECK_CONTEXT};
 
 /**
- * The branch-protection request body the GitHub adapter PUTs at
+ * The BASE branch-protection request body the GitHub adapter PUTs at
  * `/repos/{owner}/{repo}/branches/{branch}/protection`. Shape mirrors the REST
  * docs (the GitHub PUT REQUIRES `enforce_admins`, `required_pull_request_reviews`,
  * and `restrictions` to be present; `null` for "not configured"). We set only
- * the two fields the spec names — the required `${VERIFY_CHECK_CONTEXT}` check
- * AND `strict: true` (= "require branches up to date before merging") — and
- * leave the others `null` so install-ci does not silently impose unrelated
- * gates (reviews, admin enforcement, push restrictions) the user did not opt
- * into.
+ * `strict: true` (= "require branches up to date before merging") with an EMPTY
+ * `checks` array — the required `${VERIFY_CHECK_CONTEXT}` check is NOT here; it
+ * lives in the deadlock-guard RULESET ({@link buildBranchProtectionRuleset}) so
+ * its `do_not_enforce_on_create` create-exemption is meaningful (see module
+ * header). The other required fields stay `null` so install-ci does not silently
+ * impose unrelated gates (reviews, admin enforcement, push restrictions) the
+ * user did not opt into.
  */
 export interface BranchProtectionSpec {
 	required_status_checks: {
@@ -85,16 +103,15 @@ export interface BranchProtectionSpec {
 }
 
 /**
- * Build the Tier-1 branch-protection spec the GitHub adapter PUTs. The required
- * `context` is the SAME constant the emitted verify workflow names its job
- * after ({@link VERIFY_CHECK_CONTEXT}) — by construction, not by hand-typed
- * agreement, so the two cannot drift.
+ * Build the Tier-1 BASE branch-protection spec the GitHub adapter PUTs
+ * (`strict: true`, no named required check — the required check is the ruleset's
+ * job, see {@link buildBranchProtectionRuleset} and the module header).
  */
 export function buildBranchProtectionSpec(): BranchProtectionSpec {
 	return {
 		required_status_checks: {
 			strict: true,
-			checks: [{context: VERIFY_CHECK_CONTEXT}],
+			checks: [],
 		},
 		enforce_admins: null,
 		required_pull_request_reviews: null,
@@ -102,6 +119,70 @@ export function buildBranchProtectionSpec(): BranchProtectionSpec {
 	};
 }
 
+/** The name the deadlock-guard ruleset is created under (stable/idempotent-ish). */
+export const BRANCH_PROTECTION_RULESET_NAME = 'dorfl-verify-required';
+
+/**
+ * The deadlock-guard RULESET body the GitHub adapter POSTs at
+ * `/repos/{owner}/{repo}/rulesets`. It carries the required-`${VERIFY_CHECK_CONTEXT}`
+ * status-check rule with `do_not_enforce_on_create: true` — GitHub's native
+ * "require this check, but do not fail refs that predate the rule / the check's
+ * first run" toggle (the runtime deadlock guard). `enforcement: 'active'` +
+ * `conditions.ref_name` scope it to the resolved default branch. The required
+ * `context` is the SAME {@link VERIFY_CHECK_CONTEXT} constant the emitted verify
+ * workflow names its job after — by construction, so the two cannot drift.
+ */
+export interface BranchProtectionRuleset {
+	name: string;
+	target: 'branch';
+	enforcement: 'active';
+	conditions: {
+		ref_name: {
+			include: string[];
+			exclude: string[];
+		};
+	};
+	rules: {
+		type: 'required_status_checks';
+		parameters: {
+			strict_required_status_checks_policy: boolean;
+			do_not_enforce_on_create: true;
+			required_status_checks: {context: string}[];
+		};
+	}[];
+}
+
+/**
+ * Build the deadlock-guard ruleset for `branch` (the resolved default branch).
+ * The `ref_name` include uses the exact-ref form (`refs/heads/<branch>`) so the
+ * rule targets only that branch. `do_not_enforce_on_create: true` is the guard.
+ */
+export function buildBranchProtectionRuleset(
+	branch: string = DEFAULT_PROTECTED_BRANCH,
+): BranchProtectionRuleset {
+	return {
+		name: BRANCH_PROTECTION_RULESET_NAME,
+		target: 'branch',
+		enforcement: 'active',
+		conditions: {
+			ref_name: {
+				include: [`refs/heads/${branch}`],
+				exclude: [],
+			},
+		},
+		rules: [
+			{
+				type: 'required_status_checks',
+				parameters: {
+					strict_required_status_checks_policy: true,
+					do_not_enforce_on_create: true,
+					required_status_checks: [{context: VERIFY_CHECK_CONTEXT}],
+				},
+			},
+		],
+	};
+}
+
 /**
  * The repo's default branch the protection rule targets (the rule the spec
  * names: protect `main` so a propose-mode PR cannot be merged stale). Exposed
@@ -132,6 +213,26 @@ export function formatManualBranchProtectionCommand(
 	);
 }
 
+/**
+ * The exact `gh api` command the user runs themselves to create the deadlock-
+ * guard RULESET when install-ci cannot auto-configure (no admin scope). Quoted
+ * body is the same {@link BranchProtectionRuleset} the auto path POSTs, so
+ * reproducing the call by copy-paste is byte-equivalent to a successful auto
+ * run. Pure string, no I/O.
+ */
+export function formatManualBranchRulesetCommand(
+	repo: string,
+	branch: string = DEFAULT_PROTECTED_BRANCH,
+): string {
+	const body = JSON.stringify(buildBranchProtectionRuleset(branch));
+	return (
+		`echo '${body}' | gh api -X POST ` +
+		`-H "Accept: application/vnd.github+json" ` +
+		`repos/${repo}/rulesets ` +
+		`--input -`
+	);
+}
+
 /** Options for {@link installCIBranchProtectionStep}. */
 export interface BranchProtectionStepOptions {
 	/** The CI-provider seam (GitHub adapter in production; stub in tests). */
@@ -140,7 +241,13 @@ export interface BranchProtectionStepOptions {
 	fake?: boolean;
 	/** Sink for human-facing progress lines. */
 	log: (line: string) => void;
-	/** The branch the rule targets (default `main`). */
+	/**
+	 * Explicitly override the branch the rule targets. When OMITTED, the step
+	 * auto-detects the repo's default branch via
+	 * {@link CIProviderContext.getDefaultBranch}, falling back to
+	 * {@link DEFAULT_PROTECTED_BRANCH} (`main`) and logging the fallback. An
+	 * explicit value always wins over auto-detection.
+	 */
 	branch?: string;
 }
 
@@ -168,41 +275,105 @@ export interface BranchProtectionStepResult {
 	error?: string;
 	/** The branch the step targeted (echoed for tests / logs). */
 	branch: string;
+	/**
+	 * Whether the branch was AUTO-DETECTED (`true`) or came from an explicit
+	 * `branch` option / the `main` fallback (`false`). Echoed for tests / logs.
+	 */
+	branchAutoDetected?: boolean;
+	/**
+	 * The deadlock-guard RULESET outcome (only on the admin auto path):
+	 * - `set` — the ruleset POST succeeded;
+	 * - `failed` — the ruleset POST was rejected (detail in `rulesetError`);
+	 * - `skipped-no-seam` — the provider does not implement the ruleset seam.
+	 * Absent on the non-admin / skipped paths.
+	 */
+	rulesetStatus?: 'set' | 'failed' | 'skipped-no-seam';
+	/** The ruleset failure detail when `rulesetStatus === 'failed'`. */
+	rulesetError?: string;
+}
+
+/**
+ * Resolve the branch the protection targets. An EXPLICIT `branch` option always
+ * wins; otherwise auto-detect the repo's default branch via
+ * {@link CIProviderContext.getDefaultBranch}, falling back to `main` (LOGGED)
+ * when the lookup fails/empties. Returns the branch + whether it was
+ * auto-detected (for the result / log lines).
+ */
+async function resolveTargetBranch(
+	ctx: CIProviderContext,
+	explicit: string | undefined,
+	log: (line: string) => void,
+): Promise<{branch: string; autoDetected: boolean}> {
+	if (explicit !== undefined) {
+		return {branch: explicit, autoDetected: false};
+	}
+	const detected = ctx.getDefaultBranch
+		? await ctx.getDefaultBranch().catch(() => undefined)
+		: undefined;
+	if (detected) {
+		return {branch: detected, autoDetected: true};
+	}
+	log(
+		`branch protection: could not detect the default branch; ` +
+			`falling back to \`${DEFAULT_PROTECTED_BRANCH}\`.`,
+	);
+	return {branch: DEFAULT_PROTECTED_BRANCH, autoDetected: false};
 }
 
 /**
  * The orchestrator install-ci calls AFTER artifacts are written + secrets are
- * orchestrated: detect admin scope (cheapest path: {@link
- * CIProviderContext.getRepoAdminScope}), then EITHER call
- * {@link CIProviderContext.setBranchProtection} (admin) OR print the exact
- * ready-to-run `gh api` command + the one-liner manual fallback (non-admin).
+ * orchestrated:
+ *
+ *   1. RESOLVE the target branch (explicit option > auto-detected default
+ *      branch > `main` fallback), so the PUT + printed fallback target the real
+ *      default branch (see module header, "DEFAULT BRANCH");
+ *   2. detect admin scope (cheapest path: {@link
+ *      CIProviderContext.getRepoAdminScope});
+ *   3. ADMIN: PUT the base protection ({@link
+ *      CIProviderContext.setBranchProtection}) AND create the deadlock-guard
+ *      ruleset ({@link CIProviderContext.setBranchRuleset}); NON-ADMIN: print
+ *      the exact ready-to-run `gh api` commands (PUT + ruleset POST) + the
+ *      manual UI fallback.
  *
- * Never throws — a `setBranchProtection` rejection is reported as `failed` so
- * install-ci's later steps still run, and the user sees both the failure detail
- * AND the manual command to retry by hand.
+ * Never throws — a `setBranchProtection` rejection is reported as `failed`, a
+ * `setBranchRuleset` rejection as `rulesetStatus: 'failed'`, so install-ci's
+ * later steps still run and the user sees the failure detail AND the manual
+ * command to retry by hand.
  */
 export async function installCIBranchProtectionStep(
 	options: BranchProtectionStepOptions,
 ): Promise<BranchProtectionStepResult> {
-	const branch = options.branch ?? DEFAULT_PROTECTED_BRANCH;
 	const {ctx, log, fake} = options;
 
 	if (fake) {
-		log(`branch protection: skipped (--fake; would have targeted ${branch})`);
-		return {status: 'skipped-fake', branch};
+		const target = options.branch ?? DEFAULT_PROTECTED_BRANCH;
+		log(`branch protection: skipped (--fake; would have targeted ${target})`);
+		return {status: 'skipped-fake', branch: target};
 	}
 	if (!ctx.setBranchProtection) {
 		log(
 			'branch protection: skipped (provider does not implement the seam — non-GitHub host).',
 		);
-		return {status: 'skipped-no-seam', branch};
+		return {
+			status: 'skipped-no-seam',
+			branch: options.branch ?? DEFAULT_PROTECTED_BRANCH,
+		};
 	}
 	if (!ctx.repo) {
 		log('branch protection: skipped (repo unknown — pass --repo to enable).');
-		return {status: 'skipped-no-repo', branch};
+		return {
+			status: 'skipped-no-repo',
+			branch: options.branch ?? DEFAULT_PROTECTED_BRANCH,
+		};
 	}
 
 	const repo = ctx.repo;
+	const {branch, autoDetected} = await resolveTargetBranch(
+		ctx,
+		options.branch,
+		log,
+	);
+
 	// Cheapest scope-detection: one repo-permissions read (see module header).
 	// `undefined` ⇒ unknown ⇒ treat as non-admin (instruct, never silently
 	// attempt a call that would fail with 403 anyway).
@@ -213,20 +384,30 @@ export async function installCIBranchProtectionStep(
 	if (adminScope !== true) {
 		log('branch protection: no admin-scoped credential detected.');
 		log(
-			`  install-ci will NOT call the GitHub API. Run this yourself (admin token required):`,
+			`  install-ci will NOT call the GitHub API. Run these yourself (admin token required):`,
 		);
 		log(`    ${formatManualBranchProtectionCommand(repo, branch)}`);
+		log(
+			`  Then create the deadlock-guard ruleset (required check \`${VERIFY_CHECK_CONTEXT}\`, ` +
+				`do_not_enforce_on_create):`,
+		);
+		log(`    ${formatManualBranchRulesetCommand(repo, branch)}`);
 		log(
 			`  Manual UI fallback: https://github.com/${repo}/settings/branches ` +
 				`→ "Add branch protection rule" → branch name pattern \`${branch}\` ` +
-				`→ enable "Require status checks to pass" + "Require branches to be up to date" ` +
-				`→ add required check \`${VERIFY_CHECK_CONTEXT}\`.`,
+				`→ enable "Require branches to be up to date", then add a RULESET ` +
+				`requiring \`${VERIFY_CHECK_CONTEXT}\` with "Do not require ... on creation".`,
 		);
 		log(
 			`  (The ambient CI \`GITHUB_TOKEN\` is NEVER admin; a human admin's \`gh\` ` +
 				`or a configured PAT/App token with "Administration: write" is required.)`,
 		);
-		return {status: 'instructed', adminScope, branch};
+		return {
+			status: 'instructed',
+			adminScope,
+			branch,
+			branchAutoDetected: autoDetected,
+		};
 	}
 
 	const spec = buildBranchProtectionSpec();
@@ -234,15 +415,8 @@ export async function installCIBranchProtectionStep(
 		await ctx.setBranchProtection(branch, spec);
 		log(
 			`branch protection: set on ${repo}@${branch} ` +
-				`(required check \`${VERIFY_CHECK_CONTEXT}\`, strict: true).`,
+				`(strict: true = require branches up to date).`,
 		);
-		log(
-			`  NOTE: PRs opened BEFORE \`verify.yml\` lands on \`${branch}\` have ` +
-				`no \`${VERIFY_CHECK_CONTEXT}\` check waiting. Push/merge \`verify.yml\` ` +
-				`to \`${branch}\` first; existing in-flight PRs may need a no-op push ` +
-				`(or close/reopen) to re-trigger the check.`,
-		);
-		return {status: 'set', adminScope, branch};
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
 		log(`branch protection: FAILED (${error})`);
@@ -250,6 +424,57 @@ export async function installCIBranchProtectionStep(
 			`  Retry by hand (admin token required):\n` +
 				`    ${formatManualBranchProtectionCommand(repo, branch)}`,
 		);
-		return {status: 'failed', adminScope, error, branch};
+		return {
+			status: 'failed',
+			adminScope,
+			error,
+			branch,
+			branchAutoDetected: autoDetected,
+		};
 	}
+
+	// The deadlock guard: the required `verify` check lives in a RULESET with
+	// `do_not_enforce_on_create: true` (see module header), NOT in the classic
+	// PUT above — so a ref that predates the rule / the check's first run is not
+	// deadlocked by a never-reported required check.
+	let rulesetStatus: 'set' | 'failed' | 'skipped-no-seam';
+	let rulesetError: string | undefined;
+	if (!ctx.setBranchRuleset) {
+		rulesetStatus = 'skipped-no-seam';
+		log(
+			`  deadlock guard: provider does not implement the ruleset seam; ` +
+				`required check \`${VERIFY_CHECK_CONTEXT}\` NOT enforced.`,
+		);
+	} else {
+		try {
+			await ctx.setBranchRuleset(buildBranchProtectionRuleset(branch));
+			rulesetStatus = 'set';
+			log(
+				`deadlock-guard ruleset: created on ${repo}@${branch} ` +
+					`(required check \`${VERIFY_CHECK_CONTEXT}\`, do_not_enforce_on_create: true).`,
+			);
+			log(
+				`  NOTE: still push/merge \`verify.yml\` to \`${branch}\` so the check ` +
+					`can report on new PRs; the ruleset's create-exemption keeps existing ` +
+					`in-flight refs from deadlocking on the not-yet-run check.`,
+			);
+		} catch (err) {
+			rulesetError = err instanceof Error ? err.message : String(err);
+			rulesetStatus = 'failed';
+			log(`deadlock-guard ruleset: FAILED (${rulesetError})`);
+			log(
+				`  Retry by hand (admin token required):\n` +
+					`    ${formatManualBranchRulesetCommand(repo, branch)}`,
+			);
+		}
+	}
+
+	return {
+		status: 'set',
+		adminScope,
+		branch,
+		branchAutoDetected: autoDetected,
+		rulesetStatus,
+		rulesetError,
+	};
 }

package/src/install-ci-core.ts

@@ -152,7 +152,7 @@ export const DEFAULT_HARNESS: HarnessAdapter = 'pi';
  * draining steadily rather than stampeding the model-provider rate limit + the
  * arbiter CAS. Tunable via `install-ci --max-parallel <n>` / the config file.
  */
-export const DEFAULT_MAX_PARALLEL = 4;
+export const DEFAULT_MAX_PARALLEL = 2;
 
 /** The default install source: the published CLI via `npm install -g`. */
 export const DEFAULT_INSTALL_SOURCE: InstallSource = 'registry';
@@ -212,6 +212,26 @@ export interface CIProviderContext {
 	 * Throws on failure (caller catches + logs).
 	 */
 	setBranchProtection?(branch: string, spec: unknown): Promise<void>;
+	/**
+	 * OPTIONALLY report the repo's DEFAULT BRANCH name (GitHub:
+	 * `gh repo view --json defaultBranchRef`). Used by the Tier-1 branch-
+	 * protection step so the PUT and the printed `gh api` fallback both target
+	 * the repo's real default branch (a `master`-defaulted repo would 404 a
+	 * hardcoded `main`). Returns `undefined` when the lookup fails / is empty
+	 * (caller falls back to `main` and logs it). Absent on a provider that has
+	 * no default-branch concept.
+	 */
+	getDefaultBranch?(): Promise<string | undefined>;
+	/**
+	 * OPTIONALLY create/replace a branch RULESET (GitHub:
+	 * `POST /repos/{owner}/{repo}/rulesets`) carrying the deadlock-guard
+	 * `required_status_checks` rule with `do_not_enforce_on_create: true`. The
+	 * `ruleset` body (`BranchProtectionRuleset` in
+	 * `install-ci-branch-protection.ts`) is typed as `unknown` here to keep this
+	 * core seam free of the branch-protection module's import. Absent on a non-
+	 * GitHub provider. Throws on failure (caller catches + logs).
+	 */
+	setBranchRuleset?(ruleset: unknown): Promise<void>;
 	/**
 	 * OPTIONALLY render the user's project-setup payload (the value of
 	 * {@link CIConfigFile.projectSetup}[providerId]) to the NATIVE-SYNTAX
@@ -787,7 +807,7 @@ ${indent(modelsJsonStr, 8)}
 	if (config.installSource === 'workspace') {
 		installSteps = `\
     - name: Setup pnpm
-      uses: pnpm/action-setup@v4
+      uses: pnpm/action-setup@v5
 
     - name: Add pnpm global bin to PATH
       shell: bash
@@ -903,9 +923,16 @@ runs:
   using: composite
   steps:
 ${projectSetupBlock}    - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v5
       with:
         node-version: '22'
+        # setup-node@v5 auto-enables package-manager caching, which probes the
+        # project package manager DURING its own run when a lockfile is present,
+        # before that manager is on PATH, so the probe crashes ("Unable to
+        # locate executable file"). dorfl provisions ONLY its own runtime and
+        # leaves the project package-manager cache to the project (toolchain
+        # boundary), so disable it explicitly.
+        package-manager-cache: false
 
     - name: Configure git identity
       shell: bash

package/src/install-ci-github.ts

@@ -239,6 +239,66 @@ export class GitHubCIContext implements CIProviderContext {
 		return undefined;
 	}
 
+	/**
+	 * Detect the repo's DEFAULT BRANCH via
+	 * `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. Returns
+	 * `undefined` when `gh` is unavailable / the repo is unknown / the call fails
+	 * / the name is empty — the caller falls back to `main` (and logs it) so a
+	 * `master`-defaulted repo is never silently protected on a hardcoded `main`.
+	 */
+	async getDefaultBranch(): Promise<string | undefined> {
+		if (!this.repo) {
+			return undefined;
+		}
+		const result = this.runGh([
+			'repo',
+			'view',
+			'--json',
+			'defaultBranchRef',
+			'--jq',
+			'.defaultBranchRef.name',
+		]);
+		if (result === undefined || result.status !== 0) {
+			return undefined;
+		}
+		const name = result.stdout.trim();
+		return name === '' ? undefined : name;
+	}
+
+	/**
+	 * Create the deadlock-guard RULESET via
+	 * `POST /repos/{owner}/{repo}/rulesets`. The `ruleset` body is JSON-piped on
+	 * stdin (`gh api --input -`) so the nested rule shape carries cleanly. Throws
+	 * on a non-zero exit; caller logs + falls back. See the module header of
+	 * `install-ci-branch-protection.ts` for why the required-check guard uses a
+	 * ruleset while base protection stays a classic PUT.
+	 */
+	async setBranchRuleset(ruleset: unknown): Promise<void> {
+		if (!this.repo) {
+			throw new Error('cannot create branch ruleset: repo unknown');
+		}
+		const args = [
+			'api',
+			'-X',
+			'POST',
+			'-H',
+			'Accept: application/vnd.github+json',
+			`repos/${this.repo}/rulesets`,
+			'--input',
+			'-',
+		];
+		const result = this.runGhWithInput(args, JSON.stringify(ruleset));
+		if (result === undefined) {
+			throw new Error('gh not available; cannot create branch ruleset');
+		}
+		if (result.status !== 0) {
+			throw new Error(
+				`gh api POST repos/${this.repo}/rulesets failed: ` +
+					(result.stderr.trim() || 'unknown error'),
+			);
+		}
+	}
+
 	/**
 	 * Configure Tier-1 branch protection via
 	 * `PUT /repos/{owner}/{repo}/branches/{branch}/protection`. The `spec` body
@@ -322,10 +382,16 @@ export class MemoryCIProviderContext implements CIProviderContext {
 	readonly repoSettings = new Map<string, boolean>();
 	/** Branch-protection spec recorded in memory (branch → spec). */
 	readonly branchProtections = new Map<string, unknown>();
+	/** Deadlock-guard rulesets recorded in memory (append-only). */
+	readonly rulesets: unknown[] = [];
 	/** What `getRepoAdminScope()` should return (tests configure). */
 	private readonly adminScope: boolean | undefined;
+	/** What `getDefaultBranch()` should return (tests configure). */
+	private readonly defaultBranch: string | undefined;
 	/** Whether `setBranchProtection` should throw (tests configure). */
 	private readonly branchProtectionError: string | undefined;
+	/** Whether `setBranchRuleset` should throw (tests configure). */
+	private readonly branchRulesetError: string | undefined;
 
 	constructor(options: {
 		workDir: string;
@@ -333,8 +399,15 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		ghAvailable?: boolean;
 		/** Fixture admin-scope verdict; `undefined` ⇒ unknown. */
 		adminScope?: boolean;
+		/**
+		 * Fixture default-branch name; `undefined` ⇒ lookup "fails" so the caller
+		 * exercises its `main` fallback (models a `gh` that could not resolve it).
+		 */
+		defaultBranch?: string;
 		/** When set, `setBranchProtection` throws with this message (failure path). */
 		branchProtectionError?: string;
+		/** When set, `setBranchRuleset` throws with this message (failure path). */
+		branchRulesetError?: string;
 		/**
 		 * The provider id this stub claims (default `github`). Tests of the
 		 * project-setup seam may override to assert the orchestrator's
@@ -347,7 +420,9 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		this.repo = options.repo;
 		this.ghAvailable = options.ghAvailable ?? false;
 		this.adminScope = options.adminScope;
+		this.defaultBranch = options.defaultBranch;
 		this.branchProtectionError = options.branchProtectionError;
+		this.branchRulesetError = options.branchRulesetError;
 		this.providerId = options.providerId ?? GITHUB_PROVIDER_ID;
 	}
 
@@ -367,10 +442,21 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		return this.adminScope;
 	}
 
+	async getDefaultBranch(): Promise<string | undefined> {
+		return this.defaultBranch;
+	}
+
 	async setBranchProtection(branch: string, spec: unknown): Promise<void> {
 		if (this.branchProtectionError !== undefined) {
 			throw new Error(this.branchProtectionError);
 		}
 		this.branchProtections.set(branch, spec);
 	}
+
+	async setBranchRuleset(ruleset: unknown): Promise<void> {
+		if (this.branchRulesetError !== undefined) {
+			throw new Error(this.branchRulesetError);
+		}
+		this.rulesets.push(ruleset);
+	}
 }