[Vivswan]

What this specifies

page                                     the page said                               what 3.0.0 does
---------------------------------------  ------------------------------------------  ----------------------------------------------------
README, start/cli, reference/library     ask for @next until the first stable        latest is the release, and the documented install
                                         release, latest is a 0.0.0 placeholder      next is the pre-release of main
CONTRIBUTING                             compat for a pre-3 shape is marked v3       a marker at or below the current major is rejected
CONTRIBUTING                             every dependency is compiled into the       the bundle inlines them, the library keeps them
                                         bundle and the library                      external
schema.docs.yml (the _layering hover)    ignored "like any _ key"                    any other underscore key is refused
operate/check-mode                       a ruleset entry with fewer fields narrows   check sweeps for values the write would remove
                                         on apply without drift                      a key omitted inside a rule is not compared
operate/snapshot                         custom role "push": the file is written     the target fails and no file is written
                                         without collaborators
operate/snapshot, reference/architecture export $NAME before an apply or check       check resolves no reference, apply resolves
                                                                                     what the sections it runs reference
reference/forward-compatibility          nine closed sections, three nested shapes   ten closed sections, seven closed nested shapes
upgrading/v2-to-v3                       62 breaks                                   63: SettingsFile applies a section's schema as the
                                                                                     action does
reference/secrets-and-vaults             debug traces show ***                       the whole payload is withheld
reference/library                        skipped is a verb result, SingleOutcome     skipped is runMulti's alone, SingleOutcome is
                                         carries outcomes                            {result, display, detail}

How

• The closed-shape test reads the schema, so the outermost mapping a section closes fails until the page names it.
• The upgrade guide gains section 63, with the parse captured before and after the break.
• Pages state what the code does in the present tense, and only the upgrade guide speaks of the change.
• reference/semantics.md changes one sentence: the omission sweep stops inside a rule, its parameters included, and inside a bypass actor.

Proof

• Gate, red first: the widened test failed with Expected to contain: "Ten sections are closed" on the old page.
• Docs tests: bun test test/docs ends 340 pass, 0 fail.
• Static gates: typecheck, lint, lint:arch, knip, check:compat, and build:check pass.

Technical details

• Registry: curl -s https://registry.npmjs.org/-/package/@vivswan%2Fgithub-settings-as-code/dist-tags returns latest: 3.0.0, the version the pages document as the default install.
• Compat rule: .github/scripts/check-compat-markers.ts fails a marker whose major is at or below package.json's, and bun run check:compat prints no COMPAT markers (package.json 3.0.0).
• Dependencies: tsdown.config.ts names every package.json dependency in neverBundle, and build:bundle inlines them into lib/index.js.
• Underscore key: the CLI's validate on a file holding _note: hello prints unknown underscore key: _note, and a check over _layering beside one label reads clean.
• Ruleset blind spot: replaceSweep(RulesetConfig) stops the omission sweep at rules[] and bypass_actors[].
• Ruleset run: a check of a pull_request rule that omits a live allowed_merge_methods reads clean, and the PUT a second drifted key triggers carries the rule without it.
• Bypass actor: an actor declared without bypass_mode beside a live pull_request mode reads drift, "always" != "pull_request", so every field the schema names there is compared.
• Replacing writes: test/sections/{rulesets,environments,branches}/scenarios each hold a check scenario that names an omitted live value as drift.
• Signature toggle: replacingPutDrift() in src/sections/branches/index.ts leaves required_signatures out of the sweep, since the protection PUT never touches it.
• Custom role: a snapshot over a collaborator whose live role is push exits 1 with result: failed, and src/flows/snapshot.ts returns before the write.
• References: a check with the referenced variable unset reads clean after one GET, and the same apply fails naming the variable.
• Preflight order: under on-missing-permission: fail two preflight GETs precede the unset-reference failure, and under warn the apply fails with zero requests.
• Applied sections only: with sections: labels, an apply over an unset reference under actions_secrets ends applied, and over all sections it fails naming the variable.
• Closed shapes: the CLI's validate refuses an unknown key in interaction_limits and in each of the seven nested shapes, and accepts one on a label.
• Nested shape beyond the page's old list: branches[].protection.required_deployments is strict too, and the test found it.
• Section 63: SettingsFile.safeParse was run on the tree before the parser change and on this branch, and the guide quotes both.
• Beside the schema: SettingsFile.safeParse accepts a closed section's unknown entry key, a duplicate label, a literal secret value, and a wildcard branch's restrictions, and validateSettings refuses each.
• Payload trace: the webhooks-apply-converges scenario prints payload: <withheld: the request carried a resolved secret> for the config PATCH.
• Results: repoResult() in src/engine/orchestrate.ts returns five words and never skipped, which src/flows/multi.ts alone produces.
• Gate control: with one table row removed the nested-shape test fails naming branches[].protection.required_deployments.
• Scratch scenarios ran through parseScenario and runScenario of test/e2e, the same runner bun test/e2e/run.ts uses.
• Also corrected in the touched pages: check-mode's opening rule names the three replacing writes, the library reference limits SettingsFile to the section's schema, and the guide's changelog sentence is in the present tense.
• Secrets guide: its run-time paragraph limits up-front resolution to the sections the run applies.
• Files: README.md, CONTRIBUTING.md, docs/{schema.docs.yml,start/cli.md}, docs/operate/{check-mode,snapshot}.md, docs/reference/{architecture,forward-compatibility,library,secrets-and-vaults,semantics}.md, docs/upgrading/{v2-to-v3.md,v2-to-v3/library.md}, test/docs/readme.test.ts.

[github-actions]

File size check

0 over a hard cap (fails), 6 warning(s).

File	Size	Tier	Cap
src/engine/diff.ts:56	11 comment lines	warn	10
src/github/api-error.ts:9	11 comment lines	warn	10
src/problem.ts:73	18 comment lines	warn	10
src/sections/contract/errors.ts:13	11 comment lines	warn	10
src/sections/contract/module.ts:55	12 comment lines	warn	10
src/sections/shared/list/decl.ts:265	14 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

[github-actions]

Member shape check

1 finding(s).

File	Line	Rule
test/sections/contract/validate-hook.test.ts	80	all-or-none

Add the blank lines, make the comment one line directly above the item, comment every field or none, or list the path in .member-shape-allow.local with a # reason.

4 generated file(s) skipped.

[Copilot]

🟢 Approval recommended

No active review issues block the documentation and schema-test updates.

No open issues 🎉

What changed in this PR

Aligns GitHub Settings as Code documentation with released 3.0.0 behavior and expands tests that keep the documented schema boundaries accurate.

Changes:

• Updates installation guidance to use stable releases and clarifies the next channel.
• Corrects documentation for validation, check mode, snapshots, secret handling, and library results.
• Adds upgrade section 63 and schema-driven checks for closed sections and nested shapes.

File	Description
test/​docs/​readme.test.ts	Checks documented closed sections and nested shapes against schemas.
README.md	Uses stable installation commands and clarifies next.
docs/​upgrading/​v2-to-v3/​library.md	Adds section 63 on SettingsFile parsing behavior.
docs/​upgrading/​v2-to-v3.md	Updates the break count and indexes section 63.
docs/​start/​cli.md	Switches CLI installation examples to stable releases.
docs/​schema.docs.yml	Clarifies accepted top-level underscore keys.
docs/​reference/​secrets-and-vaults.md	Documents whole-payload withholding in debug traces.
docs/​reference/​library.md	Corrects installation, validation, and result contracts.
docs/​reference/​forward-compatibility.md	Lists ten closed sections and seven closed nested shapes.
docs/​reference/​architecture.md	Separates secret-reference validation from apply-time resolution.
docs/​operate/​snapshot.md	Corrects placeholder requirements and snapshot failure behavior.
docs/​operate/​check-mode.md	Explains omission drift and the ruleset comparison blind spot.
CONTRIBUTING.md	Clarifies dependency packaging and compatibility-marker rules.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the documentation updates and schema-driven documentation tests.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues block the documentation updates and accompanying schema-consistency tests.

No open issues 🎉

_{Review effort: Balanced}