docs(upgrading): count every public-entry break among the library sections

[Vivswan]

Before

Sixty-one breaks. Eleven are for library consumers (sections 9, 23, 24, 27, 34, 35, 54, 56, 58, 60, and 61), and two are for anyone pinning a sha or installing `@next` (sections 21 and 59).

[section 51] For library consumers, `DeploymentBranchPolicyConfig.type` narrows from `string` to `"branch" | "tag"`.

After

Sixty-one breaks. Twenty-six are for library consumers (sections 9, 22 to 29, 34, 35, 37 to 41, 45, 47, 49, 51, 54 to 56, 58, 60, and 61), ten of those also refusals below, and two are for anyone pinning a sha or installing `@next` (sections 21 and 59).

[section 51] For `@vivswan/github-settings-as-code` consumers, a policy's `type` under `SectionInput<"environments">` (and so `SettingsFile`) is `"branch" | "tag"`, where the pre-release v3 builds typed `string`; a `string` there no longer compiles.

How

• Section 22: parseConfig (library.md line 203) takes RunCapabilities as a third argument.
• Section 25: SectionModule.snapshot() (line 294) is required once an endpoint declares a read.
• Section 26: SnapshotReport.yaml (line 185) reorders and drops its dated line.
• Section 28: Layering (line 74) loses "merge".
• Section 29: runRender, RenderConfig, FinishedRender, concludeRender (lines 213 to 220) replace the merge names.
• Sections 37, 38, 39, 40, 41, 45, 47, 49, 51, 55: each narrows a type under SettingsFile (line 107) and SectionInput (line 298), so a literal that compiled against the pre-release entry fails now.

Proof

• Tests: bun test test/docs/guides.test.ts test/docs/readme.test.ts, 265 pass.
• Probes: docs-probe.mts over the nine pages, clean; a tsc probe fails each of the ten narrowings at head and compiles the same literal against the pre-release entry.

Technical details

• Heading census: every heading text and anchor is the same on the five edited pages (v2-to-v3.md 10, run.md 16, layering.md 7, refusals-lists.md 14, refusals-repository.md 7); the other four area pages have no diff.
• Line accounting (git diff --numstat origin/main...HEAD): v2-to-v3.md 1 added, 1 removed; run.md 4 added; layering.md 2 added; refusals-lists.md 9 added, 1 removed; refusals-repository.md 10 added.
• Longest added line: 255 characters.
• Baseline: v2.0.0's package was private, so the old type is the pre-release public entry's (the tree at aa43d3e^, published as 2.0.1-main.* from 2026-09-12 on), and every refusal commit landed on 2026-09-20 or later.
• Probe method: the TypeScript compiler API expanded every section's type under SettingsFile at aa43d3e^ and at head; one @ts-expect-error literal per claimed break fails at head and compiles against the pre-release entry; a control with one marker removed reports that line.
• Judged not a compile break, type unchanged: 36 labels (hex and length checks on string), 42 collaborators and teams (permission and slug checks on string), 43 secret and variable names (regex and byte cap on string), 44 check-suite app_id (positivity and uniqueness on number), 46 deploy keys (key format on string), 48 secret scanning patterns (regex compile on string), 52 autolinks (charset, placeholder, and prefix checks on string).
• Judged a widening, not a break: 50 milestones, whose pre-release type carried no due_on, so due_on: null never compiled and the day form compiles now.
• GET-only keys still compile: repository and branches[].protection keep an index signature, so has_downloads: false or a protection url compiles and is refused at parse; the sentences in 37 and 41 name only the enum and shape narrowings.
• Section 49: a known rule type with mis-cased parameters still compiles through the unknown-type arm of the rule union, so only enforcement and actor_type are stated.
• Section 39: the sentence names two of its three narrowings; the include_claim_keys discriminant is in the table row above it.
• Section 9's rename table already carries the parseConfig(read, env) to parseConfig(read, env, { artifactUpload }) row, so section 22's sentence links nothing new there.
• Index tables: the summary rows for the fifteen sections state no library status, so they stand as they are.
• Pre-release forms, for the record: parseConfig(read, env) had two arguments before refactor(flows)!: one owner per refusal, read, and write; one wording for both faces #208; snapshot? was optional on SectionModule before cb772c5; Layering was "merge" | "replace" before 8133147; DeploymentBranchPolicyConfig.type was z.string() before feat(environments)!: declared-off protection converges, and the schema refuses what GitHub never accepts #266.
• Cross-model review: sections 36 to 52 and 55 were swept against the pre-release schema and the expanded types; none outside the ten narrows a type under the public entry.
• Files: docs/upgrading/{v2-to-v3.md,v2-to-v3/run.md,v2-to-v3/layering.md,v2-to-v3/refusals-repository.md,v2-to-v3/refusals-lists.md}.

[github-actions]

File size check

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

File	Size	Tier	Cap
test/e2e/generators.ts	2641 lines	warn	2560

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.

[Copilot]

Copilot review overview

🟡 Changes recommended

Section 51 remains a public break through the exported SettingsFile and SectionInput shapes, making the new count inaccurate.

Review effort: Balanced
Findings: 1

Open (1)

• Public type narrowing breaks wildcard consumers and omits section 51 · New

What changed in this PR

Updates the v2-to-v3 guide’s accounting of library-consumer breaks.

Changes:

• Expands the library-impact section list.
• Removes the section 51 library note.

File	Description
docs/​upgrading/​v2-to-v3.md	Updates the library-break count and section list.
docs/​upgrading/​v2-to-v3/​refusals-lists.md	Removes the section 51 library-impact statement.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Section 51 remains a public break through the exported SectionInput type, making the revised count and deletion incorrect.

Review effort: Balanced
Findings: 2

Open (2)

• Document public SectionInput type break from narrowed policy type · New
• Public type narrowing breaks wildcard consumers and omits section 51

[Copilot]

Copilot review overview

🔵 Needs a closer look

Section 51 remains a public break through the exported SettingsFile type and must remain documented and counted.

Review effort: Balanced
Findings: 2

Open (2)

• Document public SectionInput type break from narrowed policy type
• Public type narrowing breaks wildcard consumers and omits section 51

[Copilot]

Copilot review overview

🟡 Changes recommended

The PR description still claims sixteen library breaks and four changed files, contradicting the expanded diff.

Review effort: Balanced
Findings: 1

Open (1)

• PR description conflicts with diff scope and consumer count · New

Resolved since last review (2)

• Document public SectionInput type break from narrowed policy type
• Public type narrowing breaks wildcard consumers and omits section 51