dorfl 0.1.1 → 0.2.0

package/src/github.ts

@@ -209,6 +209,26 @@ export class GitHubProvider implements ReviewProvider {
 			return this.parseOpened(input, first);
 		}
 
+		// PR ALREADY EXISTS (task `committed-recovery-completes-existing-pr`): a
+		// re-pushed branch whose PR is still open makes `gh pr create` fail with
+		// "a pull request for branch ... already exists". This is NOT an outage and
+		// NOT a missing/unauth `gh` — retrying is pointless (it fails identically)
+		// and degrading to push-only would DROP the refreshed body + the Gate-2
+		// review comment on a PR that genuinely exists (the committed-recovery re-run
+		// case). Instead RESOLVE the existing PR, UPDATE its title/body to match what
+		// this run would have created, and return it as `opened` so the caller's
+		// review-comment path fires normally. NEVER throws; a failed edit still
+		// returns the resolved PR (the comment is the more important audit trail).
+		if (prAlreadyExists(first)) {
+			const existing = this.updateExistingRequest(input);
+			if (existing !== undefined) {
+				return existing;
+			}
+			// Could not resolve the existing PR's url (e.g. a transient `gh pr view`
+			// failure) — fall through to the degrade path rather than crashing; the
+			// branch is already pushed, so the work is safe.
+		}
+
 		// Failed once — distinguish DETERMINISTIC (missing/unauth) from a TRANSIENT
 		// outage by an availability probe. Missing/unauth ⇒ degrade now (no retry).
 		// Thread the FAILED first attempt so the degrade surfaces the REAL `gh` cause
@@ -246,6 +266,47 @@ export class GitHubProvider implements ReviewProvider {
 		return this.parseOpened(input, attempt.value);
 	}
 
+	/**
+	 * The PR for this branch ALREADY EXISTS (task
+	 * `committed-recovery-completes-existing-pr`): resolve its url, REFRESH its
+	 * title/body via `gh pr edit` (so a committed-recovery re-run's synthesised
+	 * title + task-pointer body replace the earlier run's blank `--fill` ones),
+	 * and return it as `{opened: true, url}` so the caller's review-comment path
+	 * fires on the existing PR. Returns `undefined` when the url cannot be
+	 * resolved (the caller then falls through to the degrade path). The `gh pr
+	 * edit` is best-effort: a failed edit still returns the resolved PR (posting
+	 * the review comment matters more than refreshing the body), and it is only
+	 * attempted when this run actually has explicit title/body to set (else the
+	 * existing PR's content is left untouched).
+	 */
+	private updateExistingRequest(
+		input: OpenRequestInput,
+	): OpenRequestResult | undefined {
+		const url = this.resolvePrUrlForBranch(input.branch, input.cwd, input.env);
+		if (url === undefined) {
+			return undefined;
+		}
+		// Refresh the PR body/title only when this run supplies them (a committed-
+		// recovery re-run does; an unset run leaves the existing content alone).
+		if (input.title !== undefined || input.body !== undefined) {
+			const editArgs = ['pr', 'edit', url];
+			if (input.title !== undefined) {
+				editArgs.push('--title', input.title);
+			}
+			if (input.body !== undefined) {
+				editArgs.push('--body', input.body);
+			}
+			// Best-effort: ignore the result. A failed edit must not lose the PR (or
+			// the upcoming review comment) — NEVER throws (runGh swallows spawn errors).
+			this.runGh(editArgs, input.cwd, input.env);
+		}
+		return {
+			opened: true,
+			url,
+			instruction: `Updated the existing GitHub PR for ${input.branch}: ${url}`,
+		};
+	}
+
 	/** Map a successful `gh pr create` RunResult to an OpenRequestResult. */
 	private parseOpened(
 		input: OpenRequestInput,
@@ -457,6 +518,23 @@ export function prCreateContentArgs(input: {
 	return ['--title', input.title ?? '', '--body', input.body ?? ''];
 }
 
+/**
+ * Does a FAILED `gh pr create` result mean "a PR for this branch already
+ * exists" (task `committed-recovery-completes-existing-pr`)? `gh` exits non-zero
+ * with a message like `a pull request for branch "work/task-x" into branch
+ * "main" already exists: https://github.com/.../pull/357`. We match on the
+ * stable "already exists" phrase in `gh`'s stderr/stdout so a re-pushed branch
+ * whose PR is still open is treated as an UPDATE, not a transient outage. A
+ * missing `gh` (`undefined`) or a success is not this case.
+ */
+function prAlreadyExists(result: RunResult | undefined): boolean {
+	if (result === undefined || result.status === 0) {
+		return false;
+	}
+	const text = `${result.stderr ?? ''}\n${result.stdout ?? ''}`.toLowerCase();
+	return text.includes('already exists');
+}
+
 /**
  * Parse the PR URL `gh pr create` prints to stdout. `gh` prints the PR URL as a
  * line (often the only/last line); we pick the first GitHub PR URL we find. Any

package/src/harness.ts

@@ -61,6 +61,21 @@ export interface LaunchInput {
 	 * `undefined` ⇒ the pi adapter falls back to a generated default for its cwd.
 	 */
 	session?: string;
+	/**
+	 * **Optional agent-session DEADLINE** (absolute epoch-ms wall-clock timestamp)
+	 * for the ASYNC {@link Harness} launch (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). When set AND the future arrives
+	 * before the child exits, the harness sends SIGTERM (a ~10s grace, then
+	 * SIGKILL) and resolves the {@link LaunchResult} with `timedOut: true` — so
+	 * the caller can route the run as a CHECKPOINT (save WIP + auto-continue /
+	 * surface) rather than a generic agent-failure. Ignored on the synchronous
+	 * {@link Harness.launch} path (`spawnSync` cannot be interrupted from the
+	 * same event loop; the async path is where CI's `--watch` legs run and where
+	 * the checkpoint discipline lives). Absent ⇒ no deadline (byte-for-byte the
+	 * pre-task behaviour: a run finishing before its deadline is unchanged; on
+	 * `exit` the timer is cleared).
+	 */
+	deadlineMs?: number;
 	env?: NodeJS.ProcessEnv;
 }
 
@@ -170,6 +185,16 @@ export interface LaunchResult {
 	record: HarnessRecord;
 	/** Failure detail when `ok` is false (the stderr/failure channel). */
 	detail?: string;
+	/**
+	 * **True iff the launch was stopped by the dorfl-internal DEADLINE**
+	 * ({@link LaunchInput.deadlineMs}) rather than exiting on its own (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). Distinct from `ok` (a deadline
+	 * stop is neither a success nor a generic failure — it is a CHECKPOINT the
+	 * caller routes through the save+auto-continue/surface path). Absent/false
+	 * when the child exited before the deadline, so a run that finishes
+	 * normally is byte-for-byte unchanged.
+	 */
+	timedOut?: boolean;
 	/**
 	 * The agent's final ANSWER (task `harness-agent-output`): the concatenated
 	 * `text` of the LAST assistant turn the invocation produced. This is the

package/src/index.ts

@@ -26,6 +26,8 @@ export type {
 } from './repo-config.js';
 export {
 	REPO_CONFIG_FILENAME,
+	REPO_CONFIG_FILENAME_LEGACY,
+	resolveRepoConfigPath,
 	REPO_ALLOWED_KEYS,
 	REPO_REJECTED_KEYS,
 	repoConfigPath,
@@ -783,3 +785,11 @@ export type {
 	InstallCIResult,
 } from './install-ci.js';
 export {installCI, runWizard} from './install-ci.js';
+
+export type {
+	InstallSkillsOptions,
+	InstallSkillsResult,
+	InstalledAgent,
+} from './install-skills.js';
+export {installSkills, resolveSkillsSourceDir} from './install-skills.js';
+export type {Agent} from './vendor/incur/agents.js';

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

@@ -1,5 +1,5 @@
 /**
- * Tier-1 GitHub branch-protection STEP for `install-ci` (prd
+ * Tier-1 GitHub branch-protection STEP for `install-ci` (spec
  * `land-time-reverify-and-parallel-merge-ceiling`, task
  * `install-ci-tier1-branch-protection`; Story 11). Closes the propose-mode
  * PR-merge-time drift window on a GitHub arbiter: a required `verify` check + a
@@ -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-capabilities/advance-lifecycle.ts

@@ -1,5 +1,5 @@
 /**
- * The ADVANCE-LIFECYCLE capability emitter (PRD `runner-in-ci`, task
+ * The ADVANCE-LIFECYCLE capability emitter (SPEC `runner-in-ci`, task
  * `install-ci-advance-lifecycle-workflow`; capability C: auto-triage observations
  * + surface declared blockers + apply committed answers). A SELF-REGISTERING
  * module: it calls {@link registerCapability} at import time, so

package/src/install-ci-capabilities/close-job.ts

@@ -1,5 +1,5 @@
 /**
- * The CLOSE-JOB capability emitter (PRD `runner-in-ci`, task
+ * The CLOSE-JOB capability emitter (SPEC `runner-in-ci`, task
  * `install-ci-close-job-workflow`; capability E: close issues when their work
  * lands). A SELF-REGISTERING module: it calls {@link registerCapability} at import
  * time, so {@link loadCapabilityRegistry} picks it up WITHOUT any edit to a shared

package/src/install-ci-capabilities/example-noop.ts

@@ -1,5 +1,5 @@
 /**
- * REFERENCE capability registration (PRD `runner-in-ci`, task
+ * REFERENCE capability registration (SPEC `runner-in-ci`, task
  * `install-ci-core-and-github-adapter`). This file proves the capability-emitter
  * REGISTRY seam works as a DIRECTORY of self-registering modules: a new capability
  * is a NEW file in `install-ci-capabilities/` that calls {@link registerCapability}

package/src/install-ci-capabilities/intake.ts

@@ -1,7 +1,7 @@
 /**
- * The ISSUE-INTAKE capability emitter (PRD `runner-in-ci`, task
+ * The ISSUE-INTAKE capability emitter (SPEC `runner-in-ci`, task
  * `install-ci-intake-trigger-and-review-surface`; capability D: consider incoming
- * issues → task/PRD, PLUS insertion point E: surface the review verdict into the
+ * issues → task/SPEC, PLUS insertion point E: surface the review verdict into the
  * issue thread). A SELF-REGISTERING module: it calls {@link registerCapability} at
  * import time, so {@link loadCapabilityRegistry} picks it up WITHOUT any edit to a
  * shared central list/switch (the file-orthogonality contract — this task and the

package/src/install-ci-capabilities/verify.ts

@@ -1,5 +1,5 @@
 /**
- * The VERIFY capability emitter (prd
+ * The VERIFY capability emitter (spec
  * `land-time-reverify-and-parallel-merge-ceiling`, task
  * `install-ci-tier1-branch-protection`; Story 11 — Tier-1 GitHub ceiling).
  * A SELF-REGISTERING module: it calls {@link registerCapability} at import