clud-bug 0.7.0-rc.21 → 0.7.0-rc.23

package/dist/core/configure-github.js

@@ -1,9 +1,33 @@
 // SPEC §7 canonical-ruleset applier — pure core half of `configure-github`.
 //
+// `configure-github` is the one-stop repo-setup command. It does two things,
+// in order, for the selected PRESET:
+//   1. Repo conveniences (universal hygiene, ALL presets): squash-only merges,
+//      auto-merge + delete-branch-on-merge on, PR title/body as the squash
+//      commit message. These live on the REPOSITORY (v2 rulesets can't express
+//      them), so they're diffed + PATCHed via repos.get / repos.update.
+//   2. The canonical branch RULESET for the chosen preset.
+//
+// Presets are the purpose-named taxonomy vendored from reporulez (the canonical
+// source) into `data/rulesets/<name>.json`:
+//   - baseline      structural hygiene only (no required checks)
+//   - clud-bug      baseline + the `clud-bug-review` merge-gate check
+//   - skdd          clud-bug + SkDD derived-docs checks  (DEFAULT)
+//   - public-guard  stricter posture: 1 approval + code-owner + last-push
+//
 // External users installing the App expect "best practice branch protection"
 // applied automatically. This module diffs the current GitHub state against
-// the canonical ruleset (bundled at `data/canonical-v1.json`) and emits the
-// minimal set of PATCH calls to converge.
+// the selected preset (bundled under `data/rulesets/`) and emits the minimal
+// set of repo-settings + rulesets-API calls to converge.
+//
+// v2 (SPEC §7): the canonical migrated from the RETIRED classic
+// branch-protection API (`PUT …/branches/{b}/protection`, 1 required approval,
+// a required `test` status context) to GitHub's RULESETS API
+// (`GET/POST/PUT …/repos/{o}/{r}/rulesets`, 0 approvals, the `clud-bug-review`
+// check as the merge gate). Rulesets layer, are org-portable, and are the
+// modern mechanism; classic protection is legacy. The reference applier is
+// reporulez `bin/apply.sh` (list existing rulesets → find by name →
+// create-if-absent / update-if-present).
 //
 // Architectural shape mirrors `formal-review.ts` and `review-writeback.ts`:
 // the pure rule-table + diff logic lives in core (no Octokit dep at compile
@@ -19,27 +43,34 @@
 //   // b.alreadyCanonical === true; b.changes.length === 0
 //
 // A second `apply()` call against a freshly-converged repo MUST produce
-// `alreadyCanonical: true` with `changes: []` and zero PATCH calls. This
-// lets external automation (CI, dispatch loops, dashboard probes) call
+// `alreadyCanonical: true` with `changes: []` and zero create/update calls.
+// This lets external automation (CI, dispatch loops, dashboard probes) call
 // `apply()` defensively without rate-limiting itself out of the API.
 //
-// SPEC pins honored here:
-//   - canonical-v1.json schema (frozen at v1; major bumps require coordinated
-//     tool releases per the `$comment` field).
-//   - `required_status_checks.contexts` are TREATED AS A SUPERSET: if the
+// SPEC pins honored here (SPEC §7.4):
+//   - The canonical ruleset is sourced from `canonical-v1.json` (frozen at
+//     `version: v2`; the filename is a stable fetch path, the `version` field
+//     is the authority). Tools MUST NOT redefine the ruleset in-tool.
+//   - `required_status_checks` contexts are TREATED AS A SUPERSET: if the
 //     repo already requires MORE contexts than the canonical list, we leave
 //     them alone (a repo that runs additional CI gates legitimately needs
 //     them in the required set). We only ADD the canonical contexts that
 //     are missing.
-//   - `required_approving_review_count`: canonical floor is 1. If the repo
-//     already requires MORE than 1, we leave it alone (only raise to floor).
+//   - `required_approving_review_count`: canonical is 0 (the `clud-bug-review`
+//     CHECK is the gate). Owners MAY raise it; tools MUST NOT raise it by
+//     default and MUST NOT lower an owner-raised floor. We treat it as a
+//     floor of the canonical value (only ever raise, never lower).
+//   - `bypass_actors`: the Repository-admin bypass (always) is the self-mod
+//     escape hatch. Treated as a superset — extra bypass actors the repo
+//     already has are preserved.
 //
-// Offline-resilient bundling: the canonical ruleset ships in `data/` at
+// Offline-resilient bundling: the preset rulesets ship in `data/rulesets/` at
 // the package root (alongside `bin/`, `templates/`, etc., per package.json
-// `files`). We read it at runtime via fs.readFile so the build stays out
+// `files`). We read them at runtime via fs.readFile so the build stays out
 // of TypeScript's `rootDir` constraint, and so callers that re-bundle
 // clud-bug into a single file can override the ruleset by passing one
-// explicitly to `applyCanonicalRuleset({ ruleset })`.
+// explicitly to `applyCanonicalRuleset({ ruleset })` (or a preset name via
+// `{ preset }`).
 import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -49,241 +80,408 @@ import { fileURLToPath } from 'node:url';
  * `<pkg>`, parallel to the package.json `files` map entry for `data`.
  */
 const PKG_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
-/** Memoized canonical ruleset — loaded once per process. */
-let CANONICAL_V1_CACHE = null;
 /**
- * Loads the bundled canonical-v1 ruleset from `data/canonical-v1.json`.
- * Memoized so repeated calls don't re-hit the filesystem.
+ * The purpose-named preset taxonomy, vendored from reporulez (the canonical
+ * source) into `data/rulesets/<name>.json`. Ordered least → most strict.
+ */
+export const PRESET_NAMES = [
+    'baseline',
+    'clud-bug',
+    'skdd',
+    'public-guard',
+];
+/**
+ * Default preset — `skdd` (the four-check SkDD ruleset). Preserves the prior
+ * single-canonical behavior when `--preset` isn't passed.
+ */
+export const DEFAULT_PRESET = 'skdd';
+/** Type guard: is `name` one of the known presets? */
+export function isPresetName(name) {
+    return PRESET_NAMES.includes(name);
+}
+/** Memoized presets — each variant loaded at most once per process. */
+const PRESET_CACHE = new Map();
+/**
+ * Loads a vendored ruleset preset from `data/rulesets/<name>.json`. The four
+ * variants (baseline · clud-bug · skdd · public-guard) are vendored verbatim
+ * from reporulez (the canonical source); consumers ignore the `$comment`
+ * header. Memoized per-name so repeated calls don't re-hit the filesystem.
  *
- * Throws a wrapped error if the JSON file is missing — that's an
- * install-time defect (package.json `files` excluded `data/`), not a
- * runtime concern, and the loud failure surfaces it immediately.
+ * Throws a wrapped error if the name is unknown or the JSON is missing —
+ * an unknown preset is a caller bug; a missing file is an install-time
+ * defect (package.json `files` excluded `data/`). Both surface loudly.
  */
-export async function loadCanonicalV1() {
-    if (CANONICAL_V1_CACHE)
-        return CANONICAL_V1_CACHE;
-    const path = join(PKG_ROOT, 'data', 'canonical-v1.json');
+export async function loadPreset(name) {
+    if (!isPresetName(name)) {
+        throw new Error(`configure-github: unknown preset "${name}" (valid: ${PRESET_NAMES.join(', ')})`);
+    }
+    const cached = PRESET_CACHE.get(name);
+    if (cached)
+        return cached;
+    const path = join(PKG_ROOT, 'data', 'rulesets', `${name}.json`);
     try {
         const raw = await readFile(path, 'utf-8');
-        CANONICAL_V1_CACHE = JSON.parse(raw);
-        return CANONICAL_V1_CACHE;
+        const parsed = JSON.parse(raw);
+        PRESET_CACHE.set(name, parsed);
+        return parsed;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`configure-github: failed to load bundled canonical-v1.json at ${path}: ${msg}`);
+        throw new Error(`configure-github: failed to load ruleset preset "${name}" at ${path}: ${msg}`);
     }
 }
 /**
- * Applies the canonical ruleset to a GitHub repo. Reads current state via
- * the Octokit-like instance, diffs against `ruleset` (default
- * `CANONICAL_V1`), and PATCHes only what differs. Idempotent: second call
- * returns `alreadyCanonical: true` with no PATCH side effects.
+ * Back-compat alias: the historical `loadCanonicalV1()` entry point now
+ * resolves the DEFAULT (`skdd`) preset. `data/canonical-v1.json` is retained
+ * on disk as a copy of the skdd preset for the stable external fetch path,
+ * but the loader reads `data/rulesets/skdd.json`.
+ */
+export async function loadCanonicalV1() {
+    return loadPreset(DEFAULT_PRESET);
+}
+/** The canonical repo-conveniences every preset converges the repo to. */
+export const CANONICAL_REPO_CONVENIENCES = {
+    delete_branch_on_merge: true,
+    allow_auto_merge: true,
+    allow_squash_merge: true,
+    allow_merge_commit: false,
+    allow_rebase_merge: false,
+    squash_merge_commit_title: 'PR_TITLE',
+    squash_merge_commit_message: 'PR_BODY',
+};
+/**
+ * Applies the selected preset to a GitHub repo: repo conveniences FIRST
+ * (universal hygiene for every preset), then the canonical ruleset via the
+ * rulesets API.
  *
- * Behavior on partial mismatch:
+ * Conveniences: diffs repo-level settings (squash-only merges, auto-merge,
+ * delete-branch-on-merge, PR title/body squash message) and PATCHes only
+ * what drifted (`repos.update`), before the ruleset write.
  *
- *   - `required_status_checks.contexts`: canonical contexts that are
- *     missing get added; extra contexts on the repo are preserved (superset
- *     contract — a repo that runs more CI gates legitimately needs them).
- *   - `required_approving_review_count`: canonical floor is 1; if the repo
- *     already requires more, we don't lower (raise-only contract).
- *   - All booleans (allow_force_pushes, allow_deletions, etc.): converge
- *     to the canonical value exactly.
+ * Ruleset: lists the repo's rulesets, finds the canonical one by name, and:
+ *   - creates it (POST) if absent, or
+ *   - diffs the existing one against canonical and updates it (PUT) only
+ *     when it doesn't already satisfy the canonical contract.
+ * Idempotent: a second call against a converged repo returns
+ * `alreadyCanonical: true` with no repo-update / create / update side effects.
  *
- * Throws on Octokit transport failure (auth, network, 403). The CLI
- * wraps these with a friendly error message.
+ * Behavior on partial mismatch (SPEC §7.4):
+ *   - `required_status_checks` contexts: canonical contexts that are missing
+ *     get added; extra contexts on the repo are preserved (superset contract).
+ *   - `required_approving_review_count`: treated as a floor (only raise, never
+ *     lower an owner-raised value).
+ *   - `bypass_actors`: superset — extra actors the repo already has survive.
+ *   - repo conveniences + everything else converge to the canonical value.
+ *
+ * Throws on Octokit transport failure (auth, network, 403). The CLI wraps
+ * these with a friendly error message.
  */
 export async function applyCanonicalRuleset(octokit, params) {
-    const { owner, repo, branch = 'main', dryRun = false, } = params;
-    const ruleset = params.ruleset ?? (await loadCanonicalV1());
-    const target = ruleset.branch_protection;
-    const changes = [];
-    // ----- Read current branch protection state ---------------------------
-    // 404 → no base protection rule. We treat that as "every canonical
-    // setting differs" so the apply path creates the rule. Other errors
-    // bubble up — callers can't recover from a 403.
-    let current = {};
-    let hasBaseProtection = true;
-    try {
-        const resp = await octokit.repos.getBranchProtection({
+    const { owner, repo, branch = 'main', dryRun = false } = params;
+    const ruleset = params.ruleset ?? (await loadPreset(params.preset ?? DEFAULT_PRESET));
+    const desired = toRulesetWritePayload(ruleset, branch);
+    // ----- Repo conveniences (universal hygiene — every preset) -----------
+    // These live on the REPOSITORY, not the ruleset. Diff first so a repo
+    // that already matches is a true no-op (idempotency contract); the PATCH
+    // below fires BEFORE the ruleset write.
+    const repoResp = await octokit.repos.get({ owner, repo });
+    const conveniences = diffRepoConveniences(repoResp.data ?? {}, CANONICAL_REPO_CONVENIENCES);
+    // ----- Read current rulesets ------------------------------------------
+    // The list endpoint returns 200 with `[]` for a repo that has no rulesets
+    // (no 404 to special-case). Transport errors (403/network) bubble up.
+    // `includes_parents:false` keeps us to repo-level rulesets so we don't
+    // mistake an inherited org ruleset (which we can't update at repo level)
+    // for ours.
+    const listResp = await octokit.repos.getRepoRulesets({
+        owner,
+        repo,
+        includes_parents: false,
+    });
+    const existingSummary = (listResp.data ?? []).find((r) => r.name === desired.name) ?? null;
+    let rulesetChanges;
+    let existingFull = null;
+    if (existingSummary) {
+        const fullResp = await octokit.repos.getRepoRuleset({
             owner,
             repo,
-            branch,
+            ruleset_id: existingSummary.id,
         });
-        current = resp.data;
+        existingFull = fullResp.data;
+        rulesetChanges = diffExistingRuleset(existingFull, desired);
     }
-    catch (err) {
-        if (isBranchNotProtected(err)) {
-            hasBaseProtection = false;
-        }
-        else {
-            throw err;
-        }
-    }
-    // ----- Diff: required_status_checks -----------------------------------
-    // Behavior: contexts are a SUPERSET. Strict mode must match exactly.
-    const currentChecks = current.required_status_checks ?? null;
-    const currentContexts = new Set(currentChecks?.contexts ?? []);
-    const targetContexts = new Set(target.required_status_checks.contexts);
-    const missingContexts = [...targetContexts].filter((c) => !currentContexts.has(c));
-    const strictMismatch = (currentChecks?.strict ?? false) !== target.required_status_checks.strict;
-    let needsChecksPatch = !hasBaseProtection;
-    if (missingContexts.length > 0) {
-        changes.push(`required_status_checks.contexts: add ${JSON.stringify(missingContexts)}`);
-        needsChecksPatch = true;
-    }
-    if (strictMismatch) {
-        changes.push(`required_status_checks.strict: ${currentChecks?.strict ?? false} → ${target.required_status_checks.strict}`);
-        needsChecksPatch = true;
-    }
-    // The merged context list: keep extras the repo already required.
-    const mergedContexts = [
-        ...new Set([
-            ...(currentChecks?.contexts ?? []),
-            ...target.required_status_checks.contexts,
-        ]),
-    ];
-    // ----- Diff: required_pull_request_reviews ----------------------------
-    // Behavior: approving_review_count is a FLOOR (only raise). Booleans
-    // converge exactly.
-    const currentReviews = current.required_pull_request_reviews ?? null;
-    const currentCount = currentReviews?.required_approving_review_count ?? 0;
-    const targetCount = target.required_pull_request_reviews.required_approving_review_count;
-    const effectiveCount = Math.max(currentCount, targetCount);
-    const targetDismiss = target.required_pull_request_reviews.dismiss_stale_reviews;
-    const targetCodeOwner = target.required_pull_request_reviews.require_code_owner_reviews;
-    let needsReviewsPatch = !hasBaseProtection;
-    if (effectiveCount !== currentCount) {
-        changes.push(`required_pull_request_reviews.required_approving_review_count: ${currentCount} → ${effectiveCount}`);
-        needsReviewsPatch = true;
+    else {
+        rulesetChanges = describeCreate(desired);
     }
-    if ((currentReviews?.dismiss_stale_reviews ?? false) !== targetDismiss) {
-        changes.push(`required_pull_request_reviews.dismiss_stale_reviews: ${currentReviews?.dismiss_stale_reviews ?? false} → ${targetDismiss}`);
-        needsReviewsPatch = true;
-    }
-    if ((currentReviews?.require_code_owner_reviews ?? false) !== targetCodeOwner) {
-        changes.push(`required_pull_request_reviews.require_code_owner_reviews: ${currentReviews?.require_code_owner_reviews ?? false} → ${targetCodeOwner}`);
-        needsReviewsPatch = true;
-    }
-    // ----- Diff: single-flag branch protection booleans -------------------
-    const conv = current.required_conversation_resolution?.enabled ?? false;
-    const enforceAdmins = current.enforce_admins?.enabled ?? false;
-    const allowFP = current.allow_force_pushes?.enabled ?? false;
-    const allowDel = current.allow_deletions?.enabled ?? false;
-    const linearHistory = current.required_linear_history?.enabled ?? false;
-    if (conv !== target.required_conversation_resolution) {
-        changes.push(`required_conversation_resolution: ${conv} → ${target.required_conversation_resolution}`);
-    }
-    if (enforceAdmins !== target.enforce_admins) {
-        changes.push(`enforce_admins: ${enforceAdmins} → ${target.enforce_admins}`);
+    // Conveniences reported first (they're applied first).
+    const changes = [...conveniences.changes, ...rulesetChanges];
+    const alreadyCanonical = changes.length === 0;
+    if (alreadyCanonical || dryRun) {
+        return { changes, alreadyCanonical, ruleset: 'canonical-v1' };
     }
-    if (allowFP !== target.allow_force_pushes) {
-        changes.push(`allow_force_pushes: ${allowFP} → ${target.allow_force_pushes}`);
+    // ----- Apply conveniences FIRST (before the ruleset write) ------------
+    if (conveniences.needsPatch) {
+        await octokit.repos.update({ owner, repo, ...conveniences.patch });
     }
-    if (allowDel !== target.allow_deletions) {
-        changes.push(`allow_deletions: ${allowDel} → ${target.allow_deletions}`);
+    // ----- Apply ruleset (only when the ruleset itself drifted) -----------
+    // Gate on `rulesetChanges`, not the combined `changes`: a repo whose
+    // ruleset is already canonical but whose conveniences drifted must NOT
+    // incur a spurious ruleset PUT (idempotency at the ruleset layer).
+    if (rulesetChanges.length > 0) {
+        if (existingSummary && existingFull) {
+            // PUT: merge to preserve the repo's extras (superset contexts / bypass
+            // actors / owner-raised approval floor) instead of clobbering them.
+            const merged = mergeForPut(existingFull, desired);
+            await octokit.repos.updateRepoRuleset({
+                owner,
+                repo,
+                ruleset_id: existingSummary.id,
+                ...merged,
+            });
+        }
+        else {
+            await octokit.repos.createRepoRuleset({ owner, repo, ...desired });
+        }
     }
-    if (linearHistory !== target.required_linear_history) {
-        changes.push(`required_linear_history: ${linearHistory} → ${target.required_linear_history}`);
+    return { changes, alreadyCanonical: false, ruleset: 'canonical-v1' };
+}
+/**
+ * Diffs the repo's current conveniences against the canonical set. Returns
+ * one human-readable line per drifted field plus the minimal PATCH body.
+ * `needsPatch` is false when the repo already matches (idempotency contract).
+ * Only keys present in `desired` are compared, so extra repo settings GitHub
+ * echoes back never produce a spurious diff.
+ */
+function diffRepoConveniences(current, desired) {
+    const changes = [];
+    const patch = {};
+    for (const key of Object.keys(desired)) {
+        const want = desired[key];
+        const have = current[key] ?? (typeof want === 'boolean' ? false : '');
+        if (have !== want) {
+            changes.push(`${key}: ${have === '' ? '(unset)' : have} → ${want}`);
+            patch[key] = want;
+        }
     }
-    // ----- Diff: repo-level settings --------------------------------------
-    // delete_branch_on_merge / allow_auto_merge / squash commit shape live
-    // on the REPO, not the branch protection rule. Fetched separately.
-    const repoResp = await octokit.repos.get({ owner, repo });
-    const repoData = repoResp.data;
-    const repoPatch = {
-        owner,
-        repo,
+    return {
+        changes,
+        patch: patch,
+        needsPatch: changes.length > 0,
     };
-    let needsRepoPatch = false;
-    if ((repoData.delete_branch_on_merge ?? false) !== target.delete_branch_on_merge) {
-        changes.push(`delete_branch_on_merge: ${repoData.delete_branch_on_merge ?? false} → ${target.delete_branch_on_merge}`);
-        repoPatch.delete_branch_on_merge = target.delete_branch_on_merge;
-        needsRepoPatch = true;
+}
+/**
+ * Builds the GitHub rulesets write payload from the canonical file, stripping
+ * the vendored-only metadata (`$comment`, `$notes`, `version`, `spec_version`)
+ * that the rulesets API doesn't accept. When an explicit non-default branch
+ * is requested, narrows the ref condition to `refs/heads/<branch>` (the
+ * canonical otherwise targets the repo default branch via `~DEFAULT_BRANCH`).
+ */
+function toRulesetWritePayload(ruleset, branch) {
+    const conditions = branch && branch !== 'main'
+        ? { ref_name: { include: [`refs/heads/${branch}`], exclude: [] } }
+        : ruleset.conditions;
+    return {
+        name: ruleset.name,
+        target: ruleset.target,
+        enforcement: ruleset.enforcement,
+        bypass_actors: ruleset.bypass_actors,
+        conditions,
+        rules: ruleset.rules,
+    };
+}
+/** Human-readable change lines for the create (no existing ruleset) path. */
+function describeCreate(desired) {
+    const changes = [
+        `ruleset "${desired.name}": create (target=${desired.target}, enforcement=${desired.enforcement})`,
+    ];
+    for (const rule of desired.rules)
+        changes.push(`+ rule ${summarizeRule(rule)}`);
+    return changes;
+}
+/** One-line summary of a rule for human-readable diff output. */
+function summarizeRule(rule) {
+    const p = rule.parameters ?? {};
+    if (rule.type === 'pull_request') {
+        return `pull_request (approvals=${p.required_approving_review_count}, thread_resolution=${p.required_review_thread_resolution}, merge=${JSON.stringify(p.allowed_merge_methods)})`;
     }
-    if ((repoData.allow_auto_merge ?? false) !== target.allow_auto_merge) {
-        changes.push(`allow_auto_merge: ${repoData.allow_auto_merge ?? false} → ${target.allow_auto_merge}`);
-        repoPatch.allow_auto_merge = target.allow_auto_merge;
-        needsRepoPatch = true;
+    if (rule.type === 'required_status_checks') {
+        const contexts = statusCheckContexts(p);
+        return `required_status_checks (strict=${p.strict_required_status_checks_policy}, contexts=${JSON.stringify(contexts)})`;
     }
-    if ((repoData.squash_merge_commit_title ?? '') !==
-        target.squash_merge_commit_title) {
-        changes.push(`squash_merge_commit_title: ${repoData.squash_merge_commit_title ?? '(unset)'} → ${target.squash_merge_commit_title}`);
-        repoPatch.squash_merge_commit_title = target.squash_merge_commit_title;
-        needsRepoPatch = true;
+    return rule.type;
+}
+/** Extracts the `context` strings from a required_status_checks params blob. */
+function statusCheckContexts(params) {
+    const list = params.required_status_checks;
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .map((c) => (c && typeof c === 'object' ? c.context : undefined))
+        .filter((c) => typeof c === 'string');
+}
+/**
+ * Diffs an existing ruleset against the canonical desired payload. Returns
+ * one human-readable line per difference the apply path would fix; an empty
+ * array means the existing ruleset already satisfies the canonical (no-op).
+ */
+function diffExistingRuleset(existing, desired) {
+    const changes = [];
+    if ((existing.enforcement ?? '') !== desired.enforcement) {
+        changes.push(`enforcement: ${existing.enforcement ?? '(unset)'} → ${desired.enforcement}`);
     }
-    if ((repoData.squash_merge_commit_message ?? '') !==
-        target.squash_merge_commit_message) {
-        changes.push(`squash_merge_commit_message: ${repoData.squash_merge_commit_message ?? '(unset)'} → ${target.squash_merge_commit_message}`);
-        repoPatch.squash_merge_commit_message = target.squash_merge_commit_message;
-        needsRepoPatch = true;
+    if ((existing.target ?? '') !== desired.target) {
+        changes.push(`target: ${existing.target ?? '(unset)'} → ${desired.target}`);
     }
-    const alreadyCanonical = changes.length === 0;
-    if (alreadyCanonical || dryRun) {
-        return {
-            changes,
-            alreadyCanonical,
-            ruleset: 'canonical-v1',
-        };
+    // conditions: the desired ref-includes must all be present on the existing.
+    const existingInclude = new Set(existing.conditions?.ref_name?.include ?? []);
+    const missingInclude = desired.conditions.ref_name.include.filter((r) => !existingInclude.has(r));
+    if (missingInclude.length > 0) {
+        changes.push(`conditions.ref_name.include: add ${JSON.stringify(missingInclude)}`);
     }
-    // ----- Apply: branch protection ---------------------------------------
-    // The REST API requires a PUT (not PATCH) with the full settings object.
-    // We always send a complete envelope; the diff above gates whether we
-    // call PUT at all.
-    if (needsChecksPatch || needsReviewsPatch || !hasBaseProtection || hasBranchProtectionLevelDiff(changes)) {
-        await octokit.repos.updateBranchProtection({
-            owner,
-            repo,
-            branch,
-            required_status_checks: {
-                strict: target.required_status_checks.strict,
-                contexts: mergedContexts,
-            },
-            enforce_admins: target.enforce_admins,
-            required_pull_request_reviews: {
-                required_approving_review_count: effectiveCount,
-                dismiss_stale_reviews: targetDismiss,
-                require_code_owner_reviews: targetCodeOwner,
-            },
-            restrictions: null,
-            required_conversation_resolution: target.required_conversation_resolution,
-            required_linear_history: target.required_linear_history,
-            allow_force_pushes: target.allow_force_pushes,
-            allow_deletions: target.allow_deletions,
-        });
+    // bypass_actors: superset — report only actors the existing set lacks.
+    const missingActors = desired.bypass_actors.filter((d) => !(existing.bypass_actors ?? []).some((e) => e.actor_type === d.actor_type &&
+        e.actor_id === d.actor_id &&
+        e.bypass_mode === d.bypass_mode));
+    if (missingActors.length > 0) {
+        changes.push(`bypass_actors: add ${JSON.stringify(missingActors)}`);
     }
-    // ----- Apply: repo-level settings -------------------------------------
-    if (needsRepoPatch) {
-        await octokit.repos.update(repoPatch);
+    // rules: for each desired rule, ensure the existing set has a matching one.
+    const existingByType = new Map();
+    for (const r of existing.rules ?? [])
+        existingByType.set(r.type, r);
+    for (const rule of desired.rules) {
+        const ex = existingByType.get(rule.type);
+        if (!ex) {
+            changes.push(`rules: add "${rule.type}"`);
+            continue;
+        }
+        if (rule.parameters) {
+            changes.push(...diffRuleParams(rule.type, ex.parameters ?? {}, rule.parameters));
+        }
     }
-    return {
-        changes,
-        alreadyCanonical: false,
-        ruleset: 'canonical-v1',
-    };
+    return changes;
 }
 /**
- * Octokit (and gh's wrapping adapter) report a missing branch protection
- * rule as a 404. We catch on the structural shape of the error so the
- * downstream Octokit version doesn't matter.
+ * Diffs a single rule's parameters (existing vs desired). Applies the SPEC
+ * §7.4 semantics per parameter:
+ *   - `required_status_checks` (array of {context}): superset — only report
+ *     the canonical contexts the existing set is missing.
+ *   - `required_approving_review_count`: floor — only report when the existing
+ *     is BELOW the canonical (never lower an owner-raised value).
+ *   - array params (e.g. `allowed_merge_methods`): set-equality.
+ *   - scalars/booleans: exact match.
+ * Only keys present in `desired` are compared, so GitHub echoing extra
+ * default parameters never produces a spurious diff.
  */
-function isBranchNotProtected(err) {
-    if (!err || typeof err !== 'object')
-        return false;
-    const e = err;
-    if (e.status === 404)
-        return true;
-    if (typeof e.message === 'string') {
-        return /Branch not protected|Not Found|404/i.test(e.message);
+function diffRuleParams(type, existing, desired) {
+    const changes = [];
+    for (const [key, want] of Object.entries(desired)) {
+        if (key === 'required_status_checks') {
+            const wantCtx = statusCheckContexts({ required_status_checks: want });
+            const haveCtx = new Set(statusCheckContexts({ required_status_checks: existing[key] }));
+            const missing = wantCtx.filter((c) => !haveCtx.has(c));
+            if (missing.length > 0) {
+                changes.push(`${type}.required_status_checks: add ${JSON.stringify(missing)}`);
+            }
+            continue;
+        }
+        if (key === 'required_approving_review_count') {
+            const have = Number(existing[key] ?? 0);
+            const eff = Math.max(have, Number(want));
+            if (eff !== have) {
+                changes.push(`${type}.required_approving_review_count: ${have} → ${eff}`);
+            }
+            continue;
+        }
+        if (Array.isArray(want)) {
+            if (!arraysEqualAsSet(want, existing[key])) {
+                changes.push(`${type}.${key}: ${JSON.stringify(existing[key])} → ${JSON.stringify(want)}`);
+            }
+            continue;
+        }
+        if (existing[key] !== want) {
+            changes.push(`${type}.${key}: ${existing[key] ?? '(unset)'} → ${want}`);
+        }
     }
-    return false;
+    return changes;
 }
 /**
- * Detect whether any of the per-branch protection settings (conversation
- * resolution / force-pushes / deletions / linear-history / enforce-admins)
- * appeared in the change list. Used to decide whether the branch protection
- * PUT needs to fire when status_checks + reviews are both in sync.
+ * Builds the PUT payload for an update, preserving the repo's legitimate
+ * extras rather than clobbering them:
+ *   - union the existing + canonical bypass_actors,
+ *   - union the existing + canonical required_status_checks contexts,
+ *   - keep the higher of the existing / canonical approving-review count.
+ * Every other parameter converges to the canonical value.
  */
-function hasBranchProtectionLevelDiff(changes) {
-    return changes.some((c) => /^(required_conversation_resolution|enforce_admins|allow_force_pushes|allow_deletions|required_linear_history):/.test(c));
+function mergeForPut(existing, desired) {
+    // Union bypass_actors by (actor_type, actor_id).
+    const bypass = [...desired.bypass_actors];
+    for (const e of existing.bypass_actors ?? []) {
+        const already = bypass.some((d) => d.actor_type === e.actor_type && d.actor_id === e.actor_id);
+        if (!already && e.actor_type && typeof e.actor_id === 'number' && e.bypass_mode) {
+            bypass.push({
+                actor_type: e.actor_type,
+                actor_id: e.actor_id,
+                bypass_mode: e.bypass_mode,
+            });
+        }
+    }
+    const existingByType = new Map();
+    for (const r of existing.rules ?? [])
+        existingByType.set(r.type, r);
+    const rules = desired.rules.map((rule) => {
+        const ex = existingByType.get(rule.type);
+        if (rule.type === 'required_status_checks' && rule.parameters) {
+            const merged = unionContexts(statusCheckContexts(ex?.parameters ?? {}), statusCheckContexts(rule.parameters));
+            return {
+                ...rule,
+                parameters: {
+                    ...rule.parameters,
+                    required_status_checks: merged.map((context) => ({ context })),
+                },
+            };
+        }
+        if (rule.type === 'pull_request' && rule.parameters) {
+            const have = Number(ex?.parameters?.required_approving_review_count ?? 0);
+            const want = Number(rule.parameters.required_approving_review_count ?? 0);
+            return {
+                ...rule,
+                parameters: {
+                    ...rule.parameters,
+                    required_approving_review_count: Math.max(have, want),
+                },
+            };
+        }
+        return rule;
+    });
+    return {
+        name: desired.name,
+        target: desired.target,
+        enforcement: desired.enforcement,
+        bypass_actors: bypass,
+        conditions: desired.conditions,
+        rules,
+    };
+}
+/** Union of two context lists, preserving existing order then appending new. */
+function unionContexts(existing, desired) {
+    const seen = new Set();
+    const out = [];
+    for (const c of [...existing, ...desired]) {
+        if (!seen.has(c)) {
+            seen.add(c);
+            out.push(c);
+        }
+    }
+    return out;
+}
+/** Compares two values as sets (order-insensitive). Non-arrays fall back to ===. */
+function arraysEqualAsSet(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    const sa = a.map((x) => JSON.stringify(x)).sort();
+    const sb = b.map((x) => JSON.stringify(x)).sort();
+    return sa.every((v, i) => v === sb[i]);
 }
 //# sourceMappingURL=configure-github.js.map