@davidvornholt/standards 0.10.2 → 0.11.0

package/README.md

@@ -12,14 +12,18 @@ standards dependabot --check
 standards dependabot --write
 standards github --check
 standards github --apply
+standards poller --config <path>
+standards poller --print-units --config <path>
 ```
 
 `dependabot --write` regenerates the composed `.github/dependabot.yml` from the canonical `.github/dependabot.base.yml` and the optional repo-owned `.github/dependabot.local.yml`; `init` and `sync` do the same automatically. `dependabot --check` verifies the generated file still matches its sources, and `doctor`/`check` include the same verification. The overlay is deliberately lean and additive only: new update blocks for repo-specific ecosystems, top-level private registry definitions, and `ignore` or `registries` entries appended by repeating a canonical block's normalized target. Matching blocks cannot add labels, groups, cooldowns, pull-request limits, or other policy.
 
-`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. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its isolated `github-settings` job runs the live comparison with the admin-read token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--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.
+`github --check` compares the live GitHub repository (merge settings, rulesets, and declared labels) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges that declared state. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. `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. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its isolated `github-settings` job runs the live comparison with the admin-read token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--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.
 
+`poller` runs one tick of the fix poller: host-level automation that turns maintainer-approved GitHub issues into verified draft PRs and maintainer-approved draft PRs into completed review-fix cycles, using headless Codex runs. All workflow state lives in GitHub labels, comments, and draft PRs, so ticks are stateless, re-runnable, and safe to schedule from any host. A tick claims work by label (`fix-in-progress` / `review-in-progress`), releases claims stale for longer than `staleClaimHours`, and fails loudly — a red tick means jobs stalled, never silence. Trust is verified per event, not per configuration: the approval labels (`approved-for-fix`, `approved-for-review`) only count when the applying user holds the `admin` or `maintain` role, bind to the exact approved issue revision or PR head, and are revalidated before publication; only admin/maintain comments are treated as answers to agent questions. The poller removes its direct GitHub token variables before launching Codex, but the approved run shares the host service identity and can read its other ambient credentials and logged-in tool state; that accepted visibility must not be treated as credential isolation. The run works in a throwaway git worktree, hands results back through a structured outcome file, and the poller verifies effects (commits exist, no protected paths touched) before pushing, opening the draft PR, or posting the review — the required CI checks on the resulting PR remain the quality gate. Host mutation is declarative-only: `--print-units` emits a correctly escaped systemd service and timer for the polling host's infrastructure repository to adapt and deploy. That repository owns the service identity, writable HOME, PATH, GitHub token environment, lingering, and deployment. The service's tick budget (`TimeoutStartSec`) is derived from `maxJobsPerTick` × `runTimeoutMinutes` plus overhead, so re-render and redeploy the units after changing either value.
+
 `structure --profile source` validates the standards source repository itself, which is deliberately not a consumer. The profile pins its intentional exceptions so they cannot drift silently: exact, ordered root gate scripts that run this CLI from the local checkout (`structure --profile source`, `dependabot --check` or `dependabot --write`, `github --check`, and the Turbo gate) instead of a recursive `standards check`, and a non-private published bin-only CLI workspace that carries a stable release SemVer and exactly maps the `standards` bin to `src/cli.ts` without `exports`. Every other consumer rule still applies.
 
 ## Configuration
@@ -27,6 +31,7 @@ standards github --apply
 - **`.github/dependabot.local.yml`** (optional) — repo-owned Dependabot extension composed with the canonical `.github/dependabot.base.yml` into the generated `.github/dependabot.yml`. May define `updates` and top-level `registries`; a block matching a canonical normalized target may only add `ignore` and/or `registries` entries. Other matching-block policy is rejected deliberately. A missing or comments-only file means no additions. CLI 0.10.1 requires the selected content ref to contain the canonical base and rejects older refs before mutation.
 - **`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.
 - **`.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.
+- **Poller config file** (required for `poller`, passed via `--config`) — host-level JSON, deliberately not repository state. Required: `"repos"` (unique `owner/repo` strings — one poller watches any number of repositories), `"model"` and `"reasoningEffort"` (passed to `codex exec`; the model choice is deliberate and has no default). Optional: `"maxJobsPerTick"` (default 1 — the concurrency and rate-limit guard; subscription-authenticated Codex runs share the interactive rate window), `"staleClaimHours"` (default 6; must exceed `runTimeoutMinutes` so a sweep can never release the claim of a job that is still running), `"runTimeoutMinutes"` (default 240 — the timeout catches wedged agents, not honest multi-hour review runs), `"cacheDir"` (default `~/.cache/standards-poller`; holds bare mirrors and job worktrees; relative paths resolve against the config file), `"extraCodexArgs"` (extra `codex exec` arguments, e.g. enabling the collaboration feature for subagent fan-out). Unknown keys are rejected. The poller needs `git`, `codex` (authenticated — its rotating auth state must live in a writable location), and a GitHub token per the bullet below; the token needs issues, pull-requests, and contents write on the watched repos, and nothing else.
 - **`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.10.2",
+  "version": "0.11.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -29,9 +29,45 @@
     "src/github-command-shared.ts",
     "src/github-commands.ts",
     "src/github-diff.ts",
+    "src/github-labels.ts",
+    "src/github-label-identity.ts",
     "src/github-live-drift.ts",
+    "src/github-paginate.ts",
+    "src/github-settings-merge.ts",
     "src/github-settings-parse.ts",
     "src/github-settings.ts",
+    "src/poller-approval.ts",
+    "src/poller-claim.ts",
+    "src/poller-codex.ts",
+    "src/poller-commands.ts",
+    "src/poller-config.ts",
+    "src/poller-fix-outcome.ts",
+    "src/poller-fix-output.ts",
+    "src/poller-fix-publication.ts",
+    "src/poller-fix-run.ts",
+    "src/poller-fix-validation.ts",
+    "src/poller-github-pulls.ts",
+    "src/poller-github-publication.ts",
+    "src/poller-github-write.ts",
+    "src/poller-github.ts",
+    "src/poller-job-shared.ts",
+    "src/poller-outcome.ts",
+    "src/poller-output-integrity.ts",
+    "src/poller-prompts.ts",
+    "src/poller-protected-paths.ts",
+    "src/poller-protocol.ts",
+    "src/poller-review-publication.ts",
+    "src/poller-review-output.ts",
+    "src/poller-review-artifacts.ts",
+    "src/poller-review-execution.ts",
+    "src/poller-review-state.ts",
+    "src/poller-review-validation.ts",
+    "src/poller-schedule.ts",
+    "src/poller-review-run.ts",
+    "src/poller-tick.ts",
+    "src/poller-trust.ts",
+    "src/poller-units.ts",
+    "src/poller-workspace.ts",
     "src/structure-check.ts",
     "src/structure-profile.ts",
     "src/structure-script.ts",

package/src/cli.ts

@@ -44,6 +44,7 @@ import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
 import { runGithubApply, runGithubCheck } from './github-commands';
 import { loadGithubSettings } from './github-settings';
 import { isNonEmptyString, isRecord } from './github-settings-parse';
+import { runPollerCommand } from './poller-commands';
 import { collectStructureProblems } from './structure-check';
 import type { StructureProfile } from './structure-profile';
 import { hasSafeCommand } from './structure-script';
@@ -92,6 +93,7 @@ type Command =
   | 'github'
   | 'help'
   | 'init'
+  | 'poller'
   | 'structure'
   | 'sync';
 
@@ -104,6 +106,8 @@ type CliOptions = {
   readonly apply: boolean;
   readonly write: boolean;
   readonly profile: StructureProfile;
+  readonly config: string | undefined;
+  readonly printUnits: boolean;
 };
 
 const sha256 = (buf: Buffer): string =>
@@ -779,17 +783,20 @@ Commands:
   structure   Validate monorepo structure rules only
   dependabot  Verify (--check) or regenerate (--write) the composed .github/dependabot.yml
   github      Compare (--check) or converge (--apply) live GitHub settings
+  poller      Run one fix-poller tick over the configured repositories (host automation)
   help        Show this help
 
 Options:
-  --dir <path>   Consumer directory to operate on (default: current directory)
-  --profile <p>  With structure: validate as a "consumer" (default) or as the standards "source" repository itself
-  --from <src>   Upstream override for init/sync (GitHub repo or local path)
-  --ref <ref>    Upstream tag, branch, or full commit sha for init/sync (remote Git/GitHub sources only; default: main)
-  --dry-run      Preview a sync without writing anything
-  --check        With github/dependabot: compare against the declared sources (default)
-  --apply        With github: converge the live repository (needs admin auth)
-  --write        With dependabot: regenerate the composed .github/dependabot.yml`;
+  --dir <path>     Consumer directory to operate on (default: current directory)
+  --profile <p>    With structure: validate as a "consumer" (default) or as the standards "source" repository itself
+  --from <src>     Upstream override for init/sync (GitHub repo or local path)
+  --ref <ref>      Upstream tag, branch, or full commit sha for init/sync (remote Git/GitHub sources only; default: main)
+  --dry-run        Preview a sync without writing anything
+  --check          With github/dependabot: compare against the declared sources (default)
+  --apply          With github: converge the live repository (needs admin auth)
+  --write          With dependabot: regenerate the composed .github/dependabot.yml
+  --config <path>  With poller: the host-level poller config file (required)
+  --print-units    With poller: print declarative systemd unit content without touching the host`;
 
 const commandFromArg = (arg: string): Command => {
   if (
@@ -799,6 +806,7 @@ const commandFromArg = (arg: string): Command => {
     arg === 'github' ||
     arg === 'help' ||
     arg === 'init' ||
+    arg === 'poller' ||
     arg === 'structure' ||
     arg === 'sync'
   ) {
@@ -841,12 +849,24 @@ type ParsedFlags = {
   readonly write: boolean;
   readonly ref: string | undefined;
   readonly profile: StructureProfile | undefined;
+  readonly config: string | undefined;
+  readonly printUnits: boolean;
+};
+
+const assertPollerOptionUsage = (flags: ParsedFlags): void => {
+  if (flags.config !== undefined && flags.command !== 'poller') {
+    throw new Error('--config is only valid with the poller command');
+  }
+  if (flags.printUnits && flags.command !== 'poller') {
+    throw new Error('--print-units is only valid with the poller command');
+  }
 };
 
 // Every option is only meaningful with specific commands; reject the rest so a
 // typo fails loudly instead of silently doing the default thing.
 const assertOptionUsage = (flags: ParsedFlags): void => {
   const { command, checkFlag, apply, write, ref, profile } = flags;
+  assertPollerOptionUsage(flags);
   if (checkFlag && command !== 'github' && command !== 'dependabot') {
     throw new Error(
       '--check is only valid with the github and dependabot commands',
@@ -882,6 +902,8 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let apply = false;
   let write = false;
   let profile: StructureProfile | undefined;
+  let config: string | undefined;
+  let printUnits = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -889,6 +911,13 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
       case '--apply':
         apply = true;
         break;
+      case '--config':
+        config = nextOptionValue(argv, index);
+        index += 1;
+        break;
+      case '--print-units':
+        printUnits = true;
+        break;
       case '--check':
         checkFlag = true;
         break;
@@ -923,7 +952,16 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
     }
   }
 
-  assertOptionUsage({ command, checkFlag, apply, write, ref, profile });
+  assertOptionUsage({
+    command,
+    checkFlag,
+    apply,
+    write,
+    ref,
+    profile,
+    config,
+    printUnits,
+  });
 
   return {
     command,
@@ -934,6 +972,8 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
     apply,
     write,
     profile: profile ?? 'consumer',
+    config,
+    printUnits,
   };
 };
 
@@ -1135,8 +1175,18 @@ const runGateCommand = (
 };
 
 const main = async (): Promise<void> => {
-  const { command, consumer, dryRun, from, ref, apply, write, profile } =
-    parseArgs(process.argv.slice(2));
+  const {
+    command,
+    consumer,
+    dryRun,
+    from,
+    ref,
+    apply,
+    write,
+    profile,
+    config,
+    printUnits,
+  } = parseArgs(process.argv.slice(2));
 
   if (command === undefined) {
     console.error('standards: a command is required\n');
@@ -1165,6 +1215,13 @@ const main = async (): Promise<void> => {
     return;
   }
 
+  if (command === 'poller') {
+    if (!(await runPollerCommand({ configPath: config, printUnits }))) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (!(await runGateCommand(command, consumer, apply, profile))) {
     process.exitCode = 1;
   }

package/src/github-commands.ts

@@ -20,6 +20,7 @@ import {
   enforceableRepositorySettings,
   optOutEligibilityProblem,
 } from './github-command-shared';
+import { applyLabels } from './github-labels';
 import { collectLiveDrift } from './github-live-drift';
 import { isRecord } from './github-settings-parse';
 
@@ -108,6 +109,7 @@ export const runGithubApply = async (consumer: string): Promise<boolean> => {
     if (!rulesetsSkipped) {
       actions.push(...(await applyRulesets(token, repo, declared.merged)));
     }
+    actions.push(...(await applyLabels(token, repo, declared.merged.labels)));
     for (const action of actions) {
       console.log(`  ${action}`);
     }

package/src/github-label-identity.ts

@@ -0,0 +1,9 @@
+export const labelIdentity = (name: string): string => name.toLowerCase();
+
+export const hasLabel = (
+  labels: ReadonlyArray<string>,
+  expected: string,
+): boolean => {
+  const identity = labelIdentity(expected);
+  return labels.some((label) => labelIdentity(label) === identity);
+};

package/src/github-labels.ts

@@ -0,0 +1,123 @@
+// Live issue-label reading, drift, and convergence. Labels are an additive
+// floor: every declared label must exist with the declared color and
+// description; undeclared live labels (GitHub defaults, ad-hoc triage labels)
+// are ignored. Any token that can read the repository can verify labels, so
+// unlike merge settings there are no unverifiable states.
+
+import { apiError, HTTP_CREATED, HTTP_OK, request } from './github-api';
+import { labelIdentity } from './github-label-identity';
+import { listAllPages } from './github-paginate';
+import { isRecord, type LabelDeclaration } from './github-settings-parse';
+
+type LiveLabel = {
+  readonly name: string;
+  readonly color: string;
+  readonly description: string;
+};
+
+export const fetchLiveLabels = async (
+  token: string | null,
+  repo: string,
+): Promise<ReadonlyArray<LiveLabel>> => {
+  const items = await listAllPages(
+    token,
+    `/repos/${repo}/labels`,
+    `reading labels for ${repo}`,
+  );
+  return items.filter(isRecord).map((label) => ({
+    name: typeof label.name === 'string' ? label.name : '',
+    color: typeof label.color === 'string' ? label.color : '',
+    description: typeof label.description === 'string' ? label.description : '',
+  }));
+};
+
+const labelDrift = (
+  declared: LabelDeclaration,
+  live: LiveLabel | undefined,
+): string | null => {
+  if (live === undefined) {
+    return `label "${declared.name}" is declared but missing on GitHub`;
+  }
+  // GitHub reports colors in varying case; declarations are lowercase.
+  const liveColor = live.color.toLowerCase();
+  if (liveColor !== declared.color) {
+    return `label "${declared.name}" has color "${liveColor}" on GitHub, declared "${declared.color}"`;
+  }
+  if (live.description !== declared.description) {
+    return `label "${declared.name}" has a different description on GitHub than declared`;
+  }
+  return null;
+};
+
+export const diffLabels = (
+  declared: ReadonlyArray<LabelDeclaration>,
+  live: ReadonlyArray<LiveLabel>,
+): ReadonlyArray<string> => {
+  const liveByName = new Map(
+    live.map((label) => [labelIdentity(label.name), label]),
+  );
+  return declared.flatMap((label) => {
+    const drift = labelDrift(label, liveByName.get(labelIdentity(label.name)));
+    return drift === null ? [] : [drift];
+  });
+};
+
+const convergeLabel = async (
+  token: string,
+  repo: string,
+  declared: LabelDeclaration,
+  live: LiveLabel | undefined,
+): Promise<string | null> => {
+  if (labelDrift(declared, live) === null) {
+    return null;
+  }
+  if (live === undefined) {
+    const created = await request(token, 'POST', `/repos/${repo}/labels`, {
+      name: declared.name,
+      color: declared.color,
+      description: declared.description,
+    });
+    if (created.status !== HTTP_CREATED) {
+      throw new Error(apiError(`creating label "${declared.name}"`, created));
+    }
+    return `created label "${declared.name}"`;
+  }
+  const updated = await request(
+    token,
+    'PATCH',
+    `/repos/${repo}/labels/${encodeURIComponent(live.name)}`,
+    { color: declared.color, description: declared.description },
+  );
+  if (updated.status !== HTTP_OK) {
+    throw new Error(apiError(`updating label "${declared.name}"`, updated));
+  }
+  return `updated label "${declared.name}"`;
+};
+
+export const applyLabels = async (
+  token: string,
+  repo: string,
+  declared: ReadonlyArray<LabelDeclaration>,
+): Promise<ReadonlyArray<string>> => {
+  if (declared.length === 0) {
+    return [];
+  }
+  const live = await fetchLiveLabels(token, repo);
+  const liveByName = new Map(
+    live.map((label) => [labelIdentity(label.name), label]),
+  );
+  const actions: Array<string> = [];
+  for (const label of declared) {
+    // biome-ignore lint/performance/noAwaitInLoops: GitHub advises against concurrent write requests (secondary rate limits); mutations run sequentially on purpose.
+    const action = await convergeLabel(
+      token,
+      repo,
+      label,
+      liveByName.get(labelIdentity(label.name)),
+    );
+    if (action !== null) {
+      actions.push(action);
+    }
+  }
+  return actions;
+};

package/src/github-live-drift.ts

@@ -17,6 +17,7 @@ import {
   unverifiableProblem,
 } from './github-command-shared';
 import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { diffLabels, fetchLiveLabels } from './github-labels';
 import { type GithubSettings, isRecord } from './github-settings-parse';
 
 const repositoryDrift = async (
@@ -87,9 +88,16 @@ export const collectLiveDrift = async (
   }
   const token = resolveToken();
   try {
+    // No declared labels means nothing to verify — skipping the fetch is
+    // exact, not lenient.
+    const labelDrift =
+      declared.labels.length === 0
+        ? []
+        : diffLabels(declared.labels, await fetchLiveLabels(token, repo));
     return [
       ...(await repositoryDrift(token, repo, declared)),
       ...(await rulesetDrift(token, repo, declared)),
+      ...labelDrift,
     ];
   } catch (error) {
     return [

package/src/github-paginate.ts

@@ -0,0 +1,37 @@
+// Exhaustive pagination for GitHub list endpoints. Single-page reads are a
+// correctness hazard everywhere the caller needs "the latest" or "all" of
+// something: a truncated timeline mis-attributes label approvals, truncated
+// comments break answer detection, and truncated label lists read as drift.
+// Overflow past the page cap fails loudly instead of silently truncating.
+
+import { apiError, HTTP_OK, request } from './github-api';
+
+const PAGE_SIZE = 100;
+const MAX_PAGES = 30;
+
+export const listAllPages = async (
+  token: string | null,
+  path: string,
+  context: string,
+): Promise<ReadonlyArray<unknown>> => {
+  const items: Array<unknown> = [];
+  const separator = path.includes('?') ? '&' : '?';
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    // biome-ignore lint/performance/noAwaitInLoops: pages are sequential by definition; the next request needs to know the previous page was full.
+    const response = await request(
+      token,
+      'GET',
+      `${path}${separator}per_page=${PAGE_SIZE}&page=${page}`,
+    );
+    if (response.status !== HTTP_OK || !Array.isArray(response.body)) {
+      throw new Error(apiError(context, response));
+    }
+    items.push(...response.body);
+    if (response.body.length < PAGE_SIZE) {
+      return items;
+    }
+  }
+  throw new Error(
+    `${context}: more than ${MAX_PAGES * PAGE_SIZE} items; refusing to act on a truncated list`,
+  );
+};

package/src/github-settings-merge.ts

@@ -0,0 +1,167 @@
+// Merge logic for the canonical settings file and its repo-owned extension.
+// The seam may only add. Overriding a canonical repository key or redefining a
+// canonical ruleset or label could weaken the canonical floor; GitHub layers
+// multiple rulesets strictest-wins, so adding 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.
+
+import { labelIdentity } from './github-label-identity';
+import {
+  ENFORCEMENT_OPT_OUT,
+  type GithubSettings,
+  isLabelDeclaration,
+  isNamedRuleset,
+  type ParsedGithubSettings,
+} from './github-settings-parse';
+
+const completeSettings = (
+  parsed: ParsedGithubSettings | null,
+): GithubSettings | null => {
+  if (
+    parsed === null ||
+    parsed.repository === null ||
+    parsed.rulesets === null ||
+    parsed.labels === null ||
+    parsed.rulesetEnforcement === null
+  ) {
+    return null;
+  }
+  const rulesets = parsed.rulesets.filter(isNamedRuleset);
+  const labels = parsed.labels.filter(isLabelDeclaration);
+  if (
+    rulesets.length !== parsed.rulesets.length ||
+    labels.length !== parsed.labels.length
+  ) {
+    return null;
+  }
+  return {
+    repository: parsed.repository,
+    rulesets,
+    labels,
+    rulesetEnforcement: parsed.rulesetEnforcement,
+  };
+};
+
+const enforcementMergeProblems = (
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    local?.rulesetEnforcement !== ENFORCEMENT_OPT_OUT ||
+    local.rulesets === null ||
+    local.rulesets.length === 0
+  ) {
+    return [];
+  }
+  return [
+    `.github/settings.local.json declares additional rulesets while "rulesetEnforcement" is "${ENFORCEMENT_OPT_OUT}"; remove the rulesets or the opt-out`,
+  ];
+};
+
+const repositoryMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.repository === null ||
+    local === null ||
+    local.repository === null
+  ) {
+    return [];
+  }
+  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`,
+    );
+};
+
+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`,
+    );
+};
+
+const labelMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.labels === null ||
+    local === null ||
+    local.labels === null
+  ) {
+    return [];
+  }
+  const canonicalNames = new Set(
+    canonical.labels
+      .filter(isLabelDeclaration)
+      .map((label) => labelIdentity(label.name)),
+  );
+  return local.labels
+    .filter(isLabelDeclaration)
+    .filter((label) => canonicalNames.has(labelIdentity(label.name)))
+    .map(
+      (label) =>
+        `.github/settings.local.json label "${label.name}" collides with a canonical label; canonical labels are read-only`,
+    );
+};
+
+export type MergedSettings = {
+  readonly merged: GithubSettings | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export const mergeSettings = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): MergedSettings => {
+  const problems = [
+    ...enforcementMergeProblems(local),
+    ...repositoryMergeProblems(canonical, local),
+    ...rulesetMergeProblems(canonical, local),
+    ...labelMergeProblems(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: {
+        ...completeCanonical.repository,
+        ...completeLocal.repository,
+      },
+      rulesets: [...completeCanonical.rulesets, ...completeLocal.rulesets],
+      labels: [...completeCanonical.labels, ...completeLocal.labels],
+      rulesetEnforcement: completeLocal.rulesetEnforcement,
+    },
+    problems: [],
+  };
+};