@davidvornholt/standards 0.8.0 → 0.10.0

package/README.md

@@ -12,7 +12,7 @@ standards github --check
 standards github --apply
 ```
 
-`github --check` compares the live GitHub repository (merge settings and rulesets) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges the live repository to exactly the declared state. `check` runs the same comparison whenever `.github/settings.json` is present.
+`github --check` compares the live GitHub repository (merge settings and rulesets) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges the live repository to exactly the declared state. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
 
 `structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
 
@@ -21,6 +21,7 @@ standards github --apply
 ## Configuration
 
 - **`sync-standards.local.json`** (optional) — consumer-owned sync policy at the repo root, validated by `doctor`/`check` and every `init`/`sync` even when an explicit ref or local source makes its `"ref"` irrelevant. All fields optional; a missing file means the defaults. `"ref"` is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of `main` (an explicit `--ref` overrides it; a local-path `--from` source is used as-is and ignores only the validated pin). `"autoSync": false` is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run. Version 0.7.0 removes the legacy `STANDARDS_AUTO_SYNC` and `STANDARDS_SYNC_REF` variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.
-- **`GH_TOKEN` / `GITHUB_TOKEN`** (optional) — GitHub API token for the `github` command and the GitHub portion of `check`. When neither is set, the token from the local `gh` CLI is used; with no token at all, reads still work on public repositories. `--apply` and private-repo reads need an authenticated token, and repo merge settings are only visible (and thus verifiable) to admin tokens — non-admin runs report them as unverifiable.
+- **`.github/settings.local.json` `"rulesetEnforcement": "unavailable-on-plan"`** (optional) — declares that the repository's GitHub plan cannot enforce rulesets (private repositories on GitHub Free, both personal accounts and organizations). `github --check` and `--apply` then skip rulesets instead of comparing them, because a comparison cannot be trusted there: personal accounts answer ruleset reads with HTTP 403, and free-plan organizations report declared rulesets as active while silently not enforcing them. Plan-gated repository settings that only function alongside branch protection (`allow_auto_merge`) are skipped for the same reason — GitHub accepts a PATCH for them with HTTP 200 and silently keeps the old value. The remaining repository merge settings are still checked and converged, and both commands print an unprotected-branch notice on every run. The only accepted value is `"unavailable-on-plan"` (enforcement is the default; omit the key on paid plans), and combining the opt-out with additional local rulesets is rejected. After upgrading the plan, remove the declaration and run `bun standards github --apply` to restore enforcement.
+- **`GH_TOKEN` / `GITHUB_TOKEN`** (optional) — GitHub API token for the `github` command and the GitHub portion of `check`. When neither is set, the token from the local `gh` CLI is used; with no token at all, reads still work on public repositories. `--apply` needs an admin token. GitHub's REST API reveals repo merge settings only to write-capable viewers — `check` retries REST-hidden keys over GraphQL, which serves them to read-only tokens — and ruleset `bypass_actors` requires repository Administration read; a token that still cannot see declared state fails the check rather than passing unverified. In CI, where the workflow token can never hold that permission, the canonical workflow decrypts `ci.github_settings_read_token` from the SOPS-encrypted `secrets/ci.yaml` — a fine-grained PAT with read-only "Administration" access to the repository.
 
 See the standards repository README for the ownership model and adoption workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,11 @@
     "src/cli.ts",
     "src/github-api.ts",
     "src/github-apply.ts",
+    "src/github-command-shared.ts",
     "src/github-commands.ts",
     "src/github-diff.ts",
+    "src/github-live-drift.ts",
+    "src/github-settings-parse.ts",
     "src/github-settings.ts",
     "src/structure-check.ts",
     "src/structure-profile.ts",

package/src/cli.ts

@@ -493,7 +493,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
   const problems = results.filter((p): p is string => p !== null);
   if (problems.length > 0) {
     console.error(
-      `standards: ${problems.length} canonical file(s) drifted from upstream:`,
+      `standards: ${problems.length} canonical file(s) drifted from the last synced state:`,
     );
     console.error(problems.join('\n'));
     console.error(
@@ -502,7 +502,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
     return false;
   }
   console.log(
-    `standards: ${Object.keys(lock.files).length} canonical file(s) match upstream`,
+    `standards: ${Object.keys(lock.files).length} canonical file(s) match the last synced state`,
   );
   return true;
 };

package/src/github-api.ts

@@ -8,10 +8,10 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import process from 'node:process';
 import {
-  isRecord,
   type LoadedGithubSettings,
   loadGithubSettings,
 } from './github-settings';
+import { isRecord } from './github-settings-parse';
 
 const API_ROOT = 'https://api.github.com';
 
@@ -32,6 +32,7 @@ const quietExec = (
   try {
     const out = execFileSync(file, [...args], {
       encoding: 'utf8',
+      env: process.env,
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
     return out.length > 0 ? out : null;
@@ -110,6 +111,53 @@ export const loadDeclared = async (
   );
 };
 
+const GRAPHQL_MERGE_FIELDS: ReadonlyMap<string, string> = new Map([
+  ['allow_auto_merge', 'autoMergeAllowed'],
+  ['allow_merge_commit', 'mergeCommitAllowed'],
+  ['allow_rebase_merge', 'rebaseMergeAllowed'],
+  ['allow_squash_merge', 'squashMergeAllowed'],
+  ['delete_branch_on_merge', 'deleteBranchOnMerge'],
+  ['merge_commit_message', 'mergeCommitMessage'],
+  ['merge_commit_title', 'mergeCommitTitle'],
+  ['squash_merge_commit_message', 'squashMergeCommitMessage'],
+  ['squash_merge_commit_title', 'squashMergeCommitTitle'],
+]);
+
+// REST omits repository merge settings for read-only viewers (they surface
+// only with write access — community discussion #153258), but GraphQL serves
+// the same values, with identical enum spellings, to any token that can read
+// the repository. This keeps a read-only PAT sufficient for the check.
+// Returns only the keys GraphQL answered; the rest stay unverifiable.
+export const fetchMergeSettingsViaGraphql = async (
+  token: string | null,
+  repo: string,
+  keys: ReadonlyArray<string>,
+): Promise<Readonly<Record<string, unknown>>> => {
+  const mapped = keys.filter((key) => GRAPHQL_MERGE_FIELDS.has(key));
+  const [owner, name] = repo.split('/');
+  if (mapped.length === 0 || owner === undefined || name === undefined) {
+    return {};
+  }
+  const fields = mapped.map((key) => GRAPHQL_MERGE_FIELDS.get(key)).join(' ');
+  const response = await request(token, 'POST', '/graphql', {
+    query: `query { repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { ${fields} } }`,
+  });
+  if (response.status !== HTTP_OK || !isRecord(response.body)) {
+    return {};
+  }
+  const data = isRecord(response.body.data) ? response.body.data : null;
+  const repository =
+    data !== null && isRecord(data.repository) ? data.repository : null;
+  if (repository === null) {
+    return {};
+  }
+  return Object.fromEntries(
+    mapped
+      .map((key) => [key, repository[GRAPHQL_MERGE_FIELDS.get(key) ?? '']])
+      .filter(([, value]) => value !== undefined && value !== null),
+  );
+};
+
 export type LiveRulesets = {
   readonly rulesets: ReadonlyArray<Record<string, unknown>> | null;
   readonly problem: string | null;

package/src/github-apply.ts

@@ -10,8 +10,56 @@ import {
   HTTP_OK,
   request,
 } from './github-api';
-import { diffRuleset } from './github-diff';
-import type { GithubSettings } from './github-settings';
+import { diffRepositorySettings, diffRuleset } from './github-diff';
+import { type GithubSettings, isRecord } from './github-settings-parse';
+
+// GitHub answers a PATCH containing a plan-unavailable setting with HTTP 200
+// and the old value, so the response body — the updated repository — is
+// diffed again instead of trusting the status code.
+export const applyRepositorySettings = async (
+  token: string,
+  repo: string,
+  repository: Readonly<Record<string, unknown>>,
+  liveRepository: Readonly<Record<string, unknown>>,
+): Promise<ReadonlyArray<string>> => {
+  const diff = diffRepositorySettings(repository, liveRepository);
+  if (diff.drifted.length === 0 && diff.unverifiable.length === 0) {
+    return [];
+  }
+  const patched = await request(token, 'PATCH', `/repos/${repo}`, repository);
+  if (patched.status !== HTTP_OK || !isRecord(patched.body)) {
+    throw new Error(apiError('updating repository settings', patched));
+  }
+  const persisted = diffRepositorySettings(repository, patched.body);
+  const ignored = [
+    ...persisted.drifted,
+    ...persisted.unverifiable.map(
+      (key) =>
+        `repository setting "${key}" is missing from the update response`,
+    ),
+  ];
+  if (ignored.length > 0) {
+    throw new Error(
+      `GitHub returned HTTP 200 but ignored part of the update: ${ignored.join('; ')}. A silently ignored setting is usually unavailable on this GitHub plan; if this plan cannot protect branches, declare the ruleset-enforcement opt-out instead`,
+    );
+  }
+  return ['updated repository merge settings'];
+};
+
+export const applySummary = (
+  repo: string,
+  actions: ReadonlyArray<string>,
+  rulesetsSkipped: boolean,
+): string => {
+  if (rulesetsSkipped) {
+    return actions.length === 0
+      ? `standards github: enforceable settings already converged for ${repo}; plan-gated settings skipped`
+      : `standards github: enforceable settings apply complete for ${repo}; plan-gated settings skipped`;
+  }
+  return actions.length === 0
+    ? 'standards github: already converged; no changes'
+    : `standards github: apply complete for ${repo}`;
+};
 
 const reconcileRuleset = async (
   token: string,

package/src/github-command-shared.ts

@@ -0,0 +1,45 @@
+import {
+  ENFORCEMENT_OPT_OUT,
+  type GithubSettings,
+} from './github-settings-parse';
+
+// Repository settings that only function alongside branch protection, which
+// the ruleset-enforcement opt-out declares unavailable on the plan. GitHub
+// answers a PATCH for them with HTTP 200 and silently keeps the old value, so
+// they must be skipped, never applied-and-trusted.
+export const PLAN_GATED_REPOSITORY_KEYS: ReadonlySet<string> = new Set([
+  'allow_auto_merge',
+]);
+
+export const enforceableRepositorySettings = (
+  declared: GithubSettings,
+): Readonly<Record<string, unknown>> =>
+  declared.rulesetEnforcement === ENFORCEMENT_OPT_OUT
+    ? Object.fromEntries(
+        Object.entries(declared.repository).filter(
+          ([key]) => !PLAN_GATED_REPOSITORY_KEYS.has(key),
+        ),
+      )
+    : declared.repository;
+
+export const optOutEligibilityProblem = (
+  repo: string,
+  declared: GithubSettings,
+  liveRepository: Readonly<Record<string, unknown>>,
+): string | null =>
+  declared.rulesetEnforcement === ENFORCEMENT_OPT_OUT &&
+  liveRepository.private !== true
+    ? `.github/settings.local.json "rulesetEnforcement" may only be declared for a private repository; ${repo} is public`
+    : null;
+
+// Declared state the token cannot see is a gate failure, not a pass with a
+// log line: a gate that cannot perform its comparison fails closed.
+export const unverifiableProblem = (
+  scope: string,
+  items: ReadonlyArray<string>,
+): ReadonlyArray<string> =>
+  items.length === 0
+    ? []
+    : [
+        `${scope} not visible to this token, so the gate cannot verify: ${items.join('; ')}. Use a token with read access to repository administration (in CI: ci.github_settings_read_token in secrets/ci.yaml), or verify locally with admin auth`,
+      ];

package/src/github-commands.ts

@@ -1,20 +1,32 @@
 // `standards github --check` verifies the live GitHub repository against the
-// declared settings and fails closed on any drift or API error. `standards
-// github --apply` converges the live repository; it needs an admin token, so
-// it runs locally rather than in CI.
+// declared settings and fails closed on any drift, API error, or declared
+// state the token cannot see. `standards github --apply` converges the live
+// repository; it needs an admin token, so it runs locally rather than in CI.
 
 import {
   apiError,
-  fetchLiveRulesets,
   HTTP_OK,
   loadDeclared,
   request,
   resolveGithubRepo,
   resolveToken,
 } from './github-api';
-import { applyRulesets } from './github-apply';
-import { diffRepositorySettings, diffRulesets } from './github-diff';
-import { type GithubSettings, isRecord } from './github-settings';
+import {
+  applyRepositorySettings,
+  applyRulesets,
+  applySummary,
+} from './github-apply';
+import {
+  enforceableRepositorySettings,
+  optOutEligibilityProblem,
+} from './github-command-shared';
+import { collectLiveDrift } from './github-live-drift';
+import { isRecord } from './github-settings-parse';
+
+// Printed on every check and apply while the opt-out is declared: the skip
+// must stay louder than the comfort of a green gate.
+const UNENFORCEABLE_NOTICE =
+  'standards github: rulesets are declared unenforceable on this GitHub plan (.github/settings.local.json "rulesetEnforcement"); the default branch is NOT protected, and plan-gated repository settings ("allow_auto_merge") are skipped. After upgrading the plan, remove the declaration, then run `bun standards github --apply`.';
 
 const reportProblems = (problems: ReadonlyArray<string>): void => {
   console.error(
@@ -23,54 +35,11 @@ const reportProblems = (problems: ReadonlyArray<string>): void => {
   console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
 };
 
-const collectLiveDrift = async (
-  consumer: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  const repo = resolveGithubRepo(consumer);
-  if (repo === null) {
-    return ['cannot determine the GitHub repository from the origin remote'];
-  }
-  const token = resolveToken();
-  const problems: Array<string> = [];
-  try {
-    const repoResponse = await request(token, 'GET', `/repos/${repo}`);
-    if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
-      problems.push(apiError(`reading repository ${repo}`, repoResponse));
-    } else {
-      const diff = diffRepositorySettings(
-        declared.repository,
-        repoResponse.body,
-      );
-      problems.push(...diff.drifted);
-      if (diff.unverifiable.length > 0) {
-        console.log(
-          `standards github: repository setting(s) not visible to this token, verify with admin auth: ${diff.unverifiable.join(', ')}`,
-        );
-      }
-    }
-    const live = await fetchLiveRulesets(token, repo);
-    if (live.rulesets === null) {
-      problems.push(live.problem ?? 'unable to read rulesets');
-    } else {
-      const rulesetDiff = diffRulesets(declared.rulesets, live.rulesets);
-      problems.push(...rulesetDiff.drifted);
-      if (rulesetDiff.unverifiable.length > 0) {
-        console.log(
-          `standards github: ruleset field(s) not visible to this token, verify with admin auth: ${rulesetDiff.unverifiable.join('; ')}`,
-        );
-      }
-    }
-  } catch (error) {
-    problems.push(
-      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-  return problems;
-};
-
 export const runGithubCheck = async (consumer: string): Promise<boolean> => {
   const declared = await loadDeclared(consumer);
+  if (declared.merged?.rulesetEnforcement === 'unavailable-on-plan') {
+    console.log(UNENFORCEABLE_NOTICE);
+  }
   const problems = [...declared.problems];
   if (declared.merged !== null) {
     problems.push(...(await collectLiveDrift(consumer, declared.merged)));
@@ -83,13 +52,18 @@ export const runGithubCheck = async (consumer: string): Promise<boolean> => {
     return false;
   }
   console.log(
-    'standards github: live GitHub settings match the declared configuration',
+    declared.merged?.rulesetEnforcement === 'unavailable-on-plan'
+      ? 'standards github: live repository settings match the declared configuration (plan-gated settings skipped)'
+      : 'standards github: live GitHub settings match the declared configuration',
   );
   return true;
 };
 
 export const runGithubApply = async (consumer: string): Promise<boolean> => {
   const declared = await loadDeclared(consumer);
+  if (declared.merged?.rulesetEnforcement === 'unavailable-on-plan') {
+    console.log(UNENFORCEABLE_NOTICE);
+  }
   if (declared.merged === null || declared.problems.length > 0) {
     reportProblems(declared.problems);
     return false;
@@ -109,36 +83,35 @@ export const runGithubApply = async (consumer: string): Promise<boolean> => {
     return false;
   }
   try {
-    const actions: Array<string> = [];
     const repoResponse = await request(token, 'GET', `/repos/${repo}`);
     if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
       throw new Error(apiError(`reading repository ${repo}`, repoResponse));
     }
-    const diff = diffRepositorySettings(
-      declared.merged.repository,
+    const eligibilityProblem = optOutEligibilityProblem(
+      repo,
+      declared.merged,
       repoResponse.body,
     );
-    if (diff.drifted.length > 0 || diff.unverifiable.length > 0) {
-      const patched = await request(
+    if (eligibilityProblem !== null) {
+      throw new Error(eligibilityProblem);
+    }
+    const actions = [
+      ...(await applyRepositorySettings(
         token,
-        'PATCH',
-        `/repos/${repo}`,
-        declared.merged.repository,
-      );
-      if (patched.status !== HTTP_OK) {
-        throw new Error(apiError('updating repository settings', patched));
-      }
-      actions.push('updated repository merge settings');
+        repo,
+        enforceableRepositorySettings(declared.merged),
+        repoResponse.body,
+      )),
+    ];
+    const rulesetsSkipped =
+      declared.merged.rulesetEnforcement === 'unavailable-on-plan';
+    if (!rulesetsSkipped) {
+      actions.push(...(await applyRulesets(token, repo, declared.merged)));
     }
-    actions.push(...(await applyRulesets(token, repo, declared.merged)));
     for (const action of actions) {
       console.log(`  ${action}`);
     }
-    console.log(
-      actions.length === 0
-        ? 'standards github: already converged; no changes'
-        : `standards github: apply complete for ${repo}`,
-    );
+    console.log(applySummary(repo, actions, rulesetsSkipped));
     return true;
   } catch (error) {
     console.error(

package/src/github-diff.ts

@@ -1,7 +1,7 @@
 // Drift comparison between declared GitHub settings (github-settings.ts) and
 // the live state returned by the GitHub API. Pure logic; no network.
 
-import { isRecord } from './github-settings';
+import { isRecord } from './github-settings-parse';
 
 export type SettingsDiff = {
   readonly drifted: ReadonlyArray<string>;
@@ -89,8 +89,8 @@ const diffRules = (
 // Some ruleset fields — bypass_actors in particular — are only included in
 // API responses for admin viewers. A declared key that is absent on the live
 // side is unverifiable for this token, not drift: the same policy as
-// repository merge settings, so a non-admin CI token does not fail the gate
-// on state it cannot see.
+// repository merge settings, so callers can fail with a targeted
+// missing-visibility message instead of a bogus value mismatch.
 export const diffRuleset = (
   declared: Readonly<Record<string, unknown>>,
   live: Readonly<Record<string, unknown>>,
@@ -150,9 +150,9 @@ export const diffRulesets = (
 };
 
 // Repo merge settings are only visible to admin tokens; report invisible keys
-// as unverifiable instead of drifted so a non-admin CI token does not fail the
-// gate, while still surfacing that only a local admin check gives full
-// coverage.
+// as unverifiable instead of drifted so callers fail the gate with a
+// missing-visibility message that names the token fix, not a bogus value
+// mismatch.
 export const diffRepositorySettings = (
   declared: Readonly<Record<string, unknown>>,
   live: Readonly<Record<string, unknown>>,

package/src/github-live-drift.ts

@@ -0,0 +1,99 @@
+// Drift collection for `standards github --check`: compares the live GitHub
+// repository against the merged declaration and fails closed on state the
+// token cannot see. Command wiring lives in github-commands.ts.
+
+import {
+  apiError,
+  fetchLiveRulesets,
+  fetchMergeSettingsViaGraphql,
+  HTTP_OK,
+  request,
+  resolveGithubRepo,
+  resolveToken,
+} from './github-api';
+import {
+  enforceableRepositorySettings,
+  optOutEligibilityProblem,
+  unverifiableProblem,
+} from './github-command-shared';
+import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { type GithubSettings, isRecord } from './github-settings-parse';
+
+const repositoryDrift = async (
+  token: string | null,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const repoResponse = await request(token, 'GET', `/repos/${repo}`);
+  if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
+    return [apiError(`reading repository ${repo}`, repoResponse)];
+  }
+  const eligibilityProblem = optOutEligibilityProblem(
+    repo,
+    declared,
+    repoResponse.body,
+  );
+  if (eligibilityProblem !== null) {
+    return [eligibilityProblem];
+  }
+  const declaredRepository = enforceableRepositorySettings(declared);
+  const diff = diffRepositorySettings(declaredRepository, repoResponse.body);
+  if (diff.unverifiable.length === 0) {
+    return diff.drifted;
+  }
+  // REST hides merge settings from read-only tokens; retry the invisible
+  // keys over GraphQL before failing the gate.
+  const fallback = await fetchMergeSettingsViaGraphql(
+    token,
+    repo,
+    diff.unverifiable,
+  );
+  const rediff = diffRepositorySettings(declaredRepository, {
+    ...repoResponse.body,
+    ...fallback,
+  });
+  return [
+    ...rediff.drifted,
+    ...unverifiableProblem('repository setting(s)', rediff.unverifiable),
+  ];
+};
+
+const rulesetDrift = async (
+  token: string | null,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  if (declared.rulesetEnforcement === 'unavailable-on-plan') {
+    return [];
+  }
+  const live = await fetchLiveRulesets(token, repo);
+  if (live.rulesets === null) {
+    return [live.problem ?? 'unable to read rulesets'];
+  }
+  const diff = diffRulesets(declared.rulesets, live.rulesets);
+  return [
+    ...diff.drifted,
+    ...unverifiableProblem('ruleset field(s)', diff.unverifiable),
+  ];
+};
+
+export const collectLiveDrift = async (
+  consumer: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const repo = resolveGithubRepo(consumer);
+  if (repo === null) {
+    return ['cannot determine the GitHub repository from the origin remote'];
+  }
+  const token = resolveToken();
+  try {
+    return [
+      ...(await repositoryDrift(token, repo, declared)),
+      ...(await rulesetDrift(token, repo, declared)),
+    ];
+  } catch (error) {
+    return [
+      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
+    ];
+  }
+};

package/src/github-settings-parse.ts

@@ -0,0 +1,120 @@
+// Shape parsing for a single declarative GitHub settings file: the canonical
+// `.github/settings.json` or the repo-owned `.github/settings.local.json`
+// extension. Seam merging lives in github-settings.ts, drift comparison in
+// github-diff.ts, and the API interaction in github-api.ts. Like cli.ts, this
+// module is zero-dependency so `bunx` can execute the published package.
+
+// GitHub only enforces rulesets on private repositories on paid plans. The
+// seam can declare that fact so the gate skips rulesets loudly instead of
+// failing closed forever (personal accounts) or trusting rulesets the API
+// reports as active but a free-plan organization silently does not enforce.
+export type RulesetEnforcement = 'enforced' | 'unavailable-on-plan';
+
+export type GithubSettings = {
+  readonly repository: Readonly<Record<string, unknown>>;
+  readonly rulesets: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  readonly rulesetEnforcement: RulesetEnforcement;
+};
+
+export type ParsedGithubSettings = {
+  readonly repository: Readonly<Record<string, unknown>> | null;
+  readonly rulesets: ReadonlyArray<unknown> | null;
+  readonly rulesetEnforcement: RulesetEnforcement | null;
+};
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+export const isNamedRuleset = (
+  value: unknown,
+): value is Readonly<Record<string, unknown>> & { readonly name: string } =>
+  isRecord(value) && typeof value.name === 'string' && value.name.length > 0;
+
+export const SETTINGS_KEYS: ReadonlySet<string> = new Set([
+  'repository',
+  'rulesets',
+]);
+export const LOCAL_SETTINGS_KEYS: ReadonlySet<string> = new Set([
+  ...SETTINGS_KEYS,
+  'rulesetEnforcement',
+]);
+
+export const ENFORCEMENT_OPT_OUT = 'unavailable-on-plan';
+
+export type ParseResult = {
+  readonly settings: ParsedGithubSettings | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const parseRulesetEnforcement = (value: unknown): RulesetEnforcement | null => {
+  if (value === undefined) {
+    return 'enforced';
+  }
+  return value === ENFORCEMENT_OPT_OUT ? ENFORCEMENT_OPT_OUT : null;
+};
+
+const rulesetListProblems = (
+  rulesets: ReadonlyArray<unknown>,
+  label: string,
+): ReadonlyArray<string> => {
+  const problems: Array<string> = [];
+  const names = new Set<string>();
+  for (const [index, ruleset] of rulesets.entries()) {
+    if (!isNamedRuleset(ruleset)) {
+      problems.push(
+        `${label} rulesets[${index}] must be an object with a non-empty "name"`,
+      );
+    } else if (names.has(ruleset.name)) {
+      problems.push(
+        `${label} declares ruleset "${ruleset.name}" more than once`,
+      );
+    } else {
+      names.add(ruleset.name);
+    }
+  }
+  return problems;
+};
+
+export const parseSettings = (
+  raw: unknown,
+  label: string,
+  allowedKeys: ReadonlySet<string>,
+): ParseResult => {
+  if (!isRecord(raw)) {
+    return { settings: null, problems: [`${label} must be a JSON object`] };
+  }
+  const problems: Array<string> = [];
+  for (const key of Object.keys(raw)) {
+    if (!allowedKeys.has(key)) {
+      problems.push(`${label} has unknown key "${key}"`);
+    }
+  }
+  const repository = raw.repository ?? {};
+  if (!isRecord(repository)) {
+    problems.push(`${label} "repository" must be an object`);
+  }
+  const rulesets = raw.rulesets ?? [];
+  if (Array.isArray(rulesets)) {
+    problems.push(...rulesetListProblems(rulesets, label));
+  } else {
+    problems.push(`${label} "rulesets" must be an array`);
+  }
+  // Only the opt-out value is accepted: enforcement is the default, and an
+  // explicit "enforced" would be a second way to spell the same state.
+  if (
+    raw.rulesetEnforcement !== undefined &&
+    raw.rulesetEnforcement !== ENFORCEMENT_OPT_OUT
+  ) {
+    problems.push(
+      `${label} "rulesetEnforcement" must be "${ENFORCEMENT_OPT_OUT}" when present; omit it on plans where GitHub enforces rulesets`,
+    );
+  }
+  return {
+    settings: {
+      repository: isRecord(repository) ? repository : null,
+      rulesets: Array.isArray(rulesets) ? rulesets : null,
+      rulesetEnforcement: parseRulesetEnforcement(raw.rulesetEnforcement),
+    },
+    problems,
+  };
+};

package/src/github-settings.ts

@@ -1,125 +1,134 @@
-// Declarative GitHub repository settings: parsing and seam merging for the
-// canonical `.github/settings.json` and the repo-owned
-// `.github/settings.local.json` extension. Pure logic only; drift comparison
-// lives in github-diff.ts and the API interaction in github-api.ts. Like
-// cli.ts, this module is zero-dependency so `bunx` can execute the published
-// package.
+// Merge canonical GitHub settings with the repo-owned extension. Parsing,
+// drift, and API work live in named modules; this stays dependency-free.
 
-export type GithubSettings = {
-  readonly repository: Readonly<Record<string, unknown>>;
-  readonly rulesets: ReadonlyArray<Readonly<Record<string, unknown>>>;
-};
+import {
+  ENFORCEMENT_OPT_OUT,
+  type GithubSettings,
+  isNamedRuleset,
+  LOCAL_SETTINGS_KEYS,
+  type ParsedGithubSettings,
+  parseSettings,
+  SETTINGS_KEYS,
+} from './github-settings-parse';
 
 export type LoadedGithubSettings = {
   readonly merged: GithubSettings | null;
   readonly problems: ReadonlyArray<string>;
 };
 
-export const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-const SETTINGS_KEYS = new Set(['repository', 'rulesets']);
-
-type ParseResult = {
-  readonly settings: GithubSettings | null;
-  readonly problems: ReadonlyArray<string>;
+const completeSettings = (
+  parsed: ParsedGithubSettings | null,
+): GithubSettings | null => {
+  if (
+    parsed === null ||
+    parsed.repository === null ||
+    parsed.rulesets === null ||
+    parsed.rulesetEnforcement === null
+  ) {
+    return null;
+  }
+  const rulesets = parsed.rulesets.filter(isNamedRuleset);
+  if (rulesets.length !== parsed.rulesets.length) {
+    return null;
+  }
+  return {
+    repository: parsed.repository,
+    rulesets,
+    rulesetEnforcement: parsed.rulesetEnforcement,
+  };
 };
 
-const rulesetListProblems = (
-  rulesets: ReadonlyArray<unknown>,
-  label: string,
+const enforcementMergeProblems = (
+  local: ParsedGithubSettings | null,
 ): ReadonlyArray<string> => {
-  const problems: Array<string> = [];
-  const names = new Set<string>();
-  for (const [index, ruleset] of rulesets.entries()) {
-    if (
-      !(
-        isRecord(ruleset) &&
-        typeof ruleset.name === 'string' &&
-        ruleset.name.length > 0
-      )
-    ) {
-      problems.push(
-        `${label} rulesets[${index}] must be an object with a non-empty "name"`,
-      );
-    } else if (names.has(ruleset.name)) {
-      problems.push(
-        `${label} declares ruleset "${ruleset.name}" more than once`,
-      );
-    } else {
-      names.add(ruleset.name);
-    }
+  if (
+    local?.rulesetEnforcement !== ENFORCEMENT_OPT_OUT ||
+    local.rulesets === null ||
+    local.rulesets.length === 0
+  ) {
+    return [];
   }
-  return problems;
+  return [
+    `.github/settings.local.json declares additional rulesets while "rulesetEnforcement" is "${ENFORCEMENT_OPT_OUT}"; remove the rulesets or the opt-out`,
+  ];
 };
 
-const parseSettings = (raw: unknown, label: string): ParseResult => {
-  if (!isRecord(raw)) {
-    return { settings: null, problems: [`${label} must be a JSON object`] };
-  }
-  const problems: Array<string> = [];
-  for (const key of Object.keys(raw)) {
-    if (!SETTINGS_KEYS.has(key)) {
-      problems.push(`${label} has unknown key "${key}"`);
-    }
-  }
-  const repository = raw.repository ?? {};
-  if (!isRecord(repository)) {
-    problems.push(`${label} "repository" must be an object`);
-  }
-  const rulesets = raw.rulesets ?? [];
-  if (Array.isArray(rulesets)) {
-    problems.push(...rulesetListProblems(rulesets, label));
-  } else {
-    problems.push(`${label} "rulesets" must be an array`);
-  }
-  if (problems.length > 0) {
-    return { settings: null, problems };
+const repositoryMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.repository === null ||
+    local === null ||
+    local.repository === null
+  ) {
+    return [];
   }
-  return {
-    settings: {
-      repository: repository as Record<string, unknown>,
-      rulesets: rulesets as ReadonlyArray<Record<string, unknown>>,
-    },
-    problems: [],
-  };
+  const canonicalRepository = canonical.repository;
+  return Object.keys(local.repository)
+    .filter((key) => key in canonicalRepository)
+    .map(
+      (key) =>
+        `.github/settings.local.json repository."${key}" would override a canonical value; canonical settings are read-only`,
+    );
 };
 
-type MergeResult = {
-  readonly merged: GithubSettings | null;
-  readonly problems: ReadonlyArray<string>;
+const rulesetMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.rulesets === null ||
+    local === null ||
+    local.rulesets === null
+  ) {
+    return [];
+  }
+  const canonicalNames = new Set(
+    canonical.rulesets.filter(isNamedRuleset).map((ruleset) => ruleset.name),
+  );
+  return local.rulesets
+    .filter(isNamedRuleset)
+    .filter((ruleset) => canonicalNames.has(ruleset.name))
+    .map(
+      (ruleset) =>
+        `.github/settings.local.json ruleset "${ruleset.name}" collides with a canonical ruleset; add a separately named ruleset to tighten further`,
+    );
 };
 
 // The seam may only add. Overriding a canonical repository key or redefining a
 // canonical ruleset could weaken the canonical floor; GitHub layers multiple
-// rulesets strictest-wins, so adding a ruleset is always safe.
+// rulesets strictest-wins, so adding a ruleset is always safe. The one
+// subtractive declaration is the ruleset-enforcement opt-out, which skips the
+// ruleset gate entirely rather than weakening any single rule.
 const mergeSettings = (
-  canonical: GithubSettings,
-  local: GithubSettings,
-): MergeResult => {
-  const problems: Array<string> = [];
-  for (const key of Object.keys(local.repository)) {
-    if (key in canonical.repository) {
-      problems.push(
-        `.github/settings.local.json repository."${key}" would override a canonical value; canonical settings are read-only`,
-      );
-    }
-  }
-  const canonicalNames = new Set(canonical.rulesets.map((r) => r.name));
-  for (const ruleset of local.rulesets) {
-    if (canonicalNames.has(ruleset.name)) {
-      problems.push(
-        `.github/settings.local.json ruleset "${ruleset.name}" collides with a canonical ruleset; add a separately named ruleset to tighten further`,
-      );
-    }
-  }
-  if (problems.length > 0) {
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+) => {
+  const problems = [
+    ...enforcementMergeProblems(local),
+    ...repositoryMergeProblems(canonical, local),
+    ...rulesetMergeProblems(canonical, local),
+  ];
+  const completeCanonical = completeSettings(canonical);
+  const completeLocal = completeSettings(local);
+  if (
+    problems.length > 0 ||
+    completeCanonical === null ||
+    completeLocal === null
+  ) {
     return { merged: null, problems };
   }
   return {
     merged: {
-      repository: { ...canonical.repository, ...local.repository },
-      rulesets: [...canonical.rulesets, ...local.rulesets],
+      repository: {
+        ...completeCanonical.repository,
+        ...completeLocal.repository,
+      },
+      rulesets: [...completeCanonical.rulesets, ...completeLocal.rulesets],
+      rulesetEnforcement: completeLocal.rulesetEnforcement,
     },
     problems: [],
   };
@@ -160,15 +169,32 @@ export const loadGithubSettings = (
   if (localJson !== null && localJson.problem !== null) {
     problems.push(localJson.problem);
   }
-  if (problems.length > 0) {
-    return { merged: null, problems };
+  const canonical =
+    canonicalJson.problem === null
+      ? parseSettings(
+          canonicalJson.value,
+          '.github/settings.json',
+          SETTINGS_KEYS,
+        )
+      : null;
+  const local =
+    localJson?.problem === null
+      ? parseSettings(
+          localJson.value,
+          '.github/settings.local.json',
+          LOCAL_SETTINGS_KEYS,
+        )
+      : null;
+  if (canonical !== null) {
+    problems.push(...canonical.problems);
   }
-  const canonical = parseSettings(canonicalJson.value, '.github/settings.json');
-  const local = parseSettings(localJson?.value, '.github/settings.local.json');
-  problems.push(...canonical.problems, ...local.problems);
-  if (canonical.settings === null || local.settings === null) {
-    return { merged: null, problems };
+  if (local !== null) {
+    problems.push(...local.problems);
   }
-  const merged = mergeSettings(canonical.settings, local.settings);
-  return { merged: merged.merged, problems: [...problems, ...merged.problems] };
+  const merged = mergeSettings(
+    canonical?.settings ?? null,
+    local?.settings ?? null,
+  );
+  problems.push(...merged.problems);
+  return { merged: problems.length === 0 ? merged.merged : null, problems };
 };

package/src/structure-check.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
-import { isRecord } from './github-settings';
+import { isRecord } from './github-settings-parse';
 import {
   missingPublishedCliProblems,
   rootScriptExpectations,

package/src/structure-profile.ts

@@ -1,4 +1,4 @@
-import { isRecord } from './github-settings';
+import { isRecord } from './github-settings-parse';
 
 // Structure validation profiles. `consumer` is the contract every downstream
 // repo satisfies. `source` is the standards template repository itself, which

package/src/structure-workspace.ts

@@ -1,6 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isRecord } from './github-settings';
+import { isRecord } from './github-settings-parse';
 import {
   inspectVersionAndExports,
   type StructureProfile,