chore(main): release 3.0.0

[github-actions]

🤖 I have created a release beep boop

3.0.0 (2026-09-17)

⚠ BREAKING CHANGES

• sections: a GET or GraphQL body off GitHub's documented shape now fails the section with returned a body outside the documented shape naming the endpoint and field, where before it flowed into the comparison or a section's own message; a reading section without snapshot() no longer compiles; the teams and custom_properties owner probe runs ahead of their own validation.
• sections: teams, workflows, the environment listing and its pins, the protected-branch listing, the GraphQL protection rules, and the protection-rule Apps now fail plan and snapshot when GitHub holds two items under one identity, naming both; before, one was picked silently. The protection-rule Apps list is read at plan for an existing environment and after the PUT for one the run creates.
• sections: the teams, collaborators, and inherited interaction-limit snapshot notes read <label>: left out of the snapshot - <reason>; the interaction_limits.expiry and repository toggle notes use the cannot-verify template; a personal account under teams or custom_properties reads one note (docs/upgrading/v2-to-v3.md section 13).
• library: the merged file is the fold in the layers' key order, so a merged file committed under v2 reorders once. A top-level null on a section nothing below declares drops without a notice (pages and interaction_limits keep it), where v2 refused the merge.
• flows: parseConfig(read, env, capabilities) owns the private-report: artifact refusal (input-artifact-unsupported); artifact-uploader-missing and the flows' uploader check are gone. executeRun returns RunEnd { exitCode, fatal? } and RunDeps has no describe; failRun(io, problem) takes no wording hook. validateSettingsDoc and validateSettings take a SectionSelection where they took a ReadonlySet<SectionKey>. parseSnapshotFileConfig(read, env, "settings-file") reads the destination itself; SettingsFileRole gains central-file. The action and the command line print one wording per problem; remedies name the input and its flag and say "re-run" without "the workflow".
• release: the build branch gets nothing new and is deleted once every consumer has repinned; packaged commits live under build/. tags, the ten newest kept, so a sha pinned from one lives until ten newer commits are packaged. A rerun of an older release's retag-major leaves a newer release's major in place instead of failing; the verify subcommand is gone.
• sections: check mode no longer reads a secret family's sealing key (a malformed key fails the first PUT at apply); the environment secret and variable lines use the engines' wording (docs/upgrading/v2-to-v3.md sections 19-20).
• settings: an unknown underscore key at the document root fails validation naming _layering and _undeclared, where v2 dropped it as a private note; move notes into YAML comments. teams takes the {_undeclared, entries} wrapper (default keep): every run lists the repository's teams (repository Administration read) and notes undeclared direct grants, _undeclared: delete revokes them, and snapshots write the wrapper form. The retry-timing knob is read from GSAC_RETRY_BASE_MS; RETRY_BASE_MS is ignored.
• sections: two live items under one identity fail every list section, in plan and snapshot; the webhook snapshot placeholder is $SECRET_WEBHOOK_; webhooks manage web hooks only and never write name; a ruleset without source_type is repository-owned, a repeated rule type a settings-file error; one wording per concept in drift lines and notes (docs/upgrading/v2-to-v3.md sections 11-15).
• library: the npm library's entry exports the 118 documented names; 88 of its v2 names leave it: 83 move to the ./internal subpath with no semver promise and 5 are renamed below. GithubApi, GithubApiOptions, GithubClient are GitHubApi, GitHubApiOptions, GitHubClient; MissingPermissionPolicy is OnMissingPermission. checkRepository and applyRepository take (client, repo, settings, options?); RepoRunReport is CheckReport and ApplyReport; SnapshotLibraryOptions is SnapshotOptions. validateSettings returns { settings, log } and takes sections as a SectionSelection; mergeSettings(layers, options?) replaces the public foldLayers.
• flows: one redaction seal for every target kind (#204)
• flows: one run outcome model for every mode (#201)
• upgrading: two more v3 breaks. (1) A settings-file path may no longer contain a comma or a newline in any mode (they are the list separators mode: merge splits on); apply and check reject such a path with an input error naming the rule; rename the file. (2) defaults-file is no longer merged under every multi-repo target: it is applied whole to a target that has no settings file of its own (previously skipped), and a target's own file is applied as written; build layered documents with mode: merge and apply its output; run mode: check first, since with repos: "*" every discovered repository without a settings file now receives the defaults.
• the knobbed list wrapper's policy key is _undeclared; a settings file still writing undeclared fails validation with an error naming the new key.

Features

• add mode: merge with a layered settings-file (#104) (d50e70b)
• add the plan-returning section contract and migrate the workflows section (8a65765)
• ci: gate kept backward-compatibility code behind COMPAT markers (#173) (bf9f482)
• cli: github-settings-as-code and gsac commands over the library (#152) (364a9c6)
• cli: gsac init writes the live settings to .github/settings.yml and prints its PAT grant (#178) (3fad2b2)
• cli: under GitHub Actions the CLI emits the action's workflow commands (#223) (de75a22)
• contract: extend the plan contract for every migrating section (9ae375c)
• derive list sections from a declarative factory, piloted on labels (71859b5)
• generate action.yml, the inputs table, and the policy and permissions references from declarations (d062cf1)
• generate COVERAGE.md from section declarations (51068cd)
• generate the README sections table, outputs, and PAT form from section declarations (83f3c84)
• library: export the section contexts so a consumer can call a section module directly (#191) (ed6143a)
• library: package @vivswan/github-settings-as-code (#142) (cbeb56f)
• publish packaged commits on a build branch, with latest and the version tags on it (#122) (db45c7d)
• release: carry the library build on the packaged branch and publish to npm (#150) (8eb5897)
• render: the snapshot and the merged file render one canonical order, and the snapshot carries no timestamp (#237) (9d16e15)
• report: a delivered report issue is announced in the log (#235) (7e85572)
• snapshot: branches and environments read back (#147) (5f03322)
• snapshot: collaborators and teams read back (#148) (3b4f753)
• snapshot: mode snapshot writes live settings to a file or a per-repo directory (#146) (9233a14)
• snapshot: read back the GraphQL-only branch rules and environment pins (#185) (63435fc)
• snapshot: repository, actions, and rulesets read back (#143) (3d256b8)
• snapshot: section snapshot contract, engine, round-trip harness, and the first sections (#140) (f721bb1)

Bug Fixes

• action: the YAML parser never prints a settings file's source lines as warnings (#123) (54a50a0)
• adopt zod 4.5's native root $ref emission and own-proto rejection (#67) (44dab3b)
• apply review fixes to the docs and tooling sweep (73b6b4a)
• apply review fixes to the harness audit batch (ceb9f46)
• apply review fixes to the src-side audit batch (b9de617)
• attest build provenance and attach the sigstore bundle to releases (b5db672)
• branches: a denied branch probe no longer reads as a missing branch (#149) (c1d6243)
• branches: seal GraphQL node-id lookups at execution so check mode never issues them (#75) (feaf279), closes #73
• centralize the token-leak sweep in the runner (7dcc225)
• ci: name the fuzz-issue inputs the action no longer defaults (#186) (fded5f5)
• classify rate limits structurally on every path (65f97a2)
• cli: each command's help names only the flags it accepts (#182) (51a75e7)
• contract: classify definitive 404 rejections ahead of the permission branch (#164) (8be6b7d)
• contract: the plainData refusal names what JSON does with each bad item; the grant comment points at the generated docs; the validate truncation arms get their relation (#231) (0118807)
• correct mock identity minting and the pages resurrect bug (9152a91)
• cover every faultable section in the fuzz fault battery (e41aa99)
• derive owner-kind sensitivity from the section declaration (0181f01)
• dev: a fresh checkout runs bun run check green; the trimmed OpenAPI file regenerates when absent (#219) (7468741)
• discover schema-corpus scenarios across all scenario roots (d34d031)
• e2e: oracle never predicts a preflight abort for teams on a personal account (#114) (152c7d9)
• e2e: path param accessors read own keys only (#158) (89c8ee8)
• engine: withhold a secret-carrying request's failure for any client (#175) (14a5c72)
• every count in a user-facing message takes the singular or the plural, never "(s)" (#236) (5523d38)
• flows: the fleet summary says one repository; a duplicate private target is deduped under its redacted name (#233) (d23fea1)
• github: keep the throttling plugin on under the test knob via an injected scheduler (#161) (dbdcd7b)
• github: pace every throttling group by the client's own scheduler (#165) (d70d315)
• github: refuse a cyclic payload at its field instead of exhausting the stack (#171) (9dc8e42)
• hand sections the parsed settings document instead of the raw one (1ddc2f3)
• harden release boundary checks and decouple the schema id from the release manifest (f5c4c59)
• harden the CI tooling (6fb2603)
• io: collectingIo masks captured text with the shared redactor (#163) (a0faf1c)
• keep spec-pinned gaps out of automatic graduation (ae278c9)
• library: gate findings on the packaging PR (#156) (e4e8b4c)
• library: mergeSettings renders the fold the action writes; a null over nothing drops (e725c08)
• nightly: file the curated e2e issue through the fleet action (#160) (8ef9747)
• nightly: replay a fuzz artifact with the command its run wrote (#157) (339e002)
• parse live bodies through parseLive in the seven asserting sections (56ca3e4)
• pass zod's schema layout through instead of guarding it (#68) (64aad27)
• reject required-sections entries excluded by the sections allowlist (c1fc169)
• release: follow the attestation bundle rename in the repo-owned asset check and SECURITY.md (#76) (3704176)
• release: keep next from moving back on a publish the registry has not yet shown (#190) (c247bab)
• release: order pre-release versions by main's commit count, not the run number (#197) (131780e)
• release: read the major line in one advertisement and publish latest from the whole chain (#172) (1312f3f)
• release: refuse a build tip whose Source trailer is not a full sha and fix the post-green coalescing note (#176) (ee6c725)
• report: match report issues by their own body, open over closed, newest first (#170) (8d5c1a8)
• report: paginate the report-issue lookups and scan by title, not creator (#159) (631e1da)
• rulesets: bypass_actors hidden from a non-admin token is not drift (#137) (b8df084)
• scripts: the permission count in the generated docs takes the helper; the npm-confirm line is pinned with an injectable pause (#239) (e6897d8)
• sections: make the impossible literal-with-routed-keys branch entry unrepresentable and declare the sealing-key read's phase (#195) (95d081d)
• sections: require the deploy key read_only flag, carry the label brands through the list section, deep-freeze the registries (#187) (15ef0c9)
• settings: unknown underscore keys fail everywhere; teams gets the _undeclared knob; GSAC_RETRY_BASE_MS (05e6d41)
• single-tag releases - version tags live only on packaged commits (08d5585)
• size the harness kill cap for the directed fuzz battery (8543af8)
• snapshot: a denied sub-read fails the section under on-missing-permission: fail (#184) (04d8d35)
• snapshot: refuse a destination the filesystem carries onto an authored file (#179) (5b24963)
• strengthen the remaining per-section representations (3fc0f85)
• test: match private-report heading markers without an HTML-comment regex (#106) (33ff405)

Documentation

• upgrading: link the v3 breaks to their guides (8541b3d)

Miscellaneous Chores

• drop the release-as pin and the machinery that retired it (a2cc999)

Code Refactoring

• flows: one owner per refusal, read, and write; one wording for both faces (bd9b6dd)
• flows: one redaction seal for every target kind (#204) (f1f938e)
• flows: one run outcome model for every mode (#201) (033a9c6)
• library: a documented public entry and an internal one; one naming family per layer (d92b738)
• release: one immutable packaged commit per main sha; latest and vN move only forward; the build chain retires (eac7de6)
• sections: environments plan through the secrets and variables engines; the sealing key is read at apply (5dfc10a)
• sections: milestones, webhooks, and rulesets join listSection; duplicate live items fail loudly everywhere (2cb5c8a)
• sections: one duplicate-live guard and identity rendering over every live list (f7c72ff)
• sections: one helper per repeated concept; the snapshot notes teams and collaborators leave out use the shared template (aa1f86f)
• sections: the read port parses every live body, and the registry owns the owner probe (cb772c5)

---

This PR was generated with Release Please. See documentation.