[Vivswan]

What this changes

before   docs/upgrading/v2-to-v3.md                        1298 lines, two under the 1300-line cap

after    docs/upgrading/v2-to-v3.md                         142   index: intro, summary table grouped by area, order of operations
         docs/upgrading/v2-to-v3/run.md                     242   sections 1, 4, 5, 6, 7, 8, 10, 13, 18, 22, 25, 26, 33, 34, 61
         docs/upgrading/v2-to-v3/settings-file.md           107   sections 2, 16, 32, 53
         docs/upgrading/v2-to-v3/layering.md                253   sections 3, 24, 28, 29, 30, 31
         docs/upgrading/v2-to-v3/sections.md                 76   sections 11, 12, 14, 15, 17, 19, 20
         docs/upgrading/v2-to-v3/refusals-repository.md     125   sections 37, 38, 39, 40, 44, 45
         docs/upgrading/v2-to-v3/refusals-lists.md          266   sections 36, 41, 42, 43, 46, 47, 48, 49, 50, 51, 52, 55, 57
         docs/upgrading/v2-to-v3/library.md                 196   sections 9, 23, 27, 35, 54, 56, 58, 60
         docs/upgrading/v2-to-v3/releases.md                 37   sections 21, 59

One summary row, before and after:

before   | `defaults-file` is a fallback | ... | ... under [section 1](#1-the-defaults-file-fallback) |

after    ## Run inputs and outputs

         The detail is in [v2-to-v3/run.md](v2-to-v3/run.md).

         | Break | v2 | v3 | What the old form does now |
         | `defaults-file` is a fallback | ... | ... under [section 1](v2-to-v3/run.md#1-the-defaults-file-fallback) |

How

• Each numbered section moves verbatim to one area page, keeping its number, title, and anchor.
• The index keeps the intro, the grouped summary table, and the order of operations.
• Only links moved: a cross-page section link gains its page, a ../ link gains a level.
• Two over-cap paragraphs are reshaped into bullets, a table, and quoted output.
• The docs tests walk docs/ recursively, so one path change covers the new pages.

Proof

• Heading census: 61 numbered headings before and after, identical; ## headings 62 -> 70.
• Line census: every old non-blank line lands on exactly one page after link normalization, bar the two reshaped paragraphs; new lines are structural, plus the row for 61.
• Tests: docs guides and readme suites green, 265 pass.
• Probe: docs-probe clean over all nine pages.

Technical details

• Grant: one region of test/docs/guides.test.ts, the readFileSync path in the wrapper-key fence assertion, repointed to docs/upgrading/v2-to-v3/settings-file.md.
• Typos allowance: the [type.layering-guide] glob in _typos.toml gains refusals-lists.md, the page the split moved the quoted declares "permision" refusal to, since typos matches type globs by file name only.
• Corrected, forced by the move: the intro's total (sixty-one), its library-consumer count and list (eleven, adding section 61, whose text changes DiscoveryFilters.exclude for library callers), and the missing summary row for section 61, which the base added without one.
• Reshaped paragraphs: section 60's opening paragraph (110 words) is five bullets with bold lead-ins; section 61's opening paragraph (263 words) is a short paragraph, a grammar table, and its two output lines quoted in text fences; every fact kept.
• Area headings are plain text with the page link in the line under them, since the heading test refuses links in headings.
• The 8 area headings are the only ## headings added; the 62 old ones are kept with their text.
• Width: markdown is exempt from the fleet's 256 line cap; the old page carried 156 lines over it, the pages carry 159.
• Anchor census: the 61 section anchors are unchanged and each resolves on its page; the 6 cross-page section links and 16 ../../ links resolve (the anchor test).
• Front matter: every area page quotes its title, since two carry a colon.
• Line census detail: 966 non-blank lines before the split, 1045 after it; the one old line not carried over by the split is the count sentence, replaced by its sixty-one form; the reshape then replaced the two paragraphs with their devices.
• Probe cap: 70 words per paragraph or list item.
• Line accounting: docs/upgrading/v2-to-v3.md +98 -1254; the eight pages +1302 -0; test/docs/guides.test.ts +1 -1; _typos.toml +5 -4; total +1406 -1259.
• Files: docs/upgrading/v2-to-v3.md, docs/upgrading/v2-to-v3/{run,settings-file,layering,sections,refusals-repository,refusals-lists,library,releases}.md, test/docs/guides.test.ts, _typos.toml.
• Stack: built on the branch that added section 61 (feat(discovery)!: match exclude patterns with picomatch under an owned glob grammar #462); rebased onto main after it merged, so the base is main.

[github-actions]

File size check

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

File	Size	Tier	Cap
.github/scripts/gen-inputs-table.ts:54	11 comment lines	warn	10
.github/scripts/release-pipeline.ts:1	34 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:453	14 comment lines	warn	10
src/discovery/discover.ts:91	11 comment lines	warn	10
src/github/secret-scan.ts:45	11 comment lines	warn	10
src/sections/contract/errors.ts:13	14 comment lines	warn	10
src/sections/shared/roles.ts:43	13 comment lines	warn	10
test/e2e/generators.ts	2641 lines	warn	2560
test/sections/refusal-messages.test.ts:61	19 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.

[Copilot]

Copilot review overview

🟡 Changes recommended

The library-section count is outdated, and the moved intentional typo is no longer allowlisted for the typography gate.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Allowlist moved permision examples in refusals-lists.md · New
• Add section 61 to the library-consumer count · New

What changed in this PR

Splits the v2-to-v3 upgrade guide into a concise index and eight focused area pages.

Changes:

• Groups all 61 migration sections by subject.
• Preserves section anchors and updates cross-page links.
• Repoints the documentation assertion to the moved content.

File	Description
docs/​upgrading/​v2-to-v3.md	Becomes the grouped index and summary.
docs/​upgrading/​v2-to-v3/​run.md	Covers run inputs and outputs.
docs/​upgrading/​v2-to-v3/​settings-file.md	Covers settings-file directives.
docs/​upgrading/​v2-to-v3/​layering.md	Covers layering and rendering.
docs/​upgrading/​v2-to-v3/​sections.md	Covers per-section behavior.
docs/​upgrading/​v2-to-v3/​refusals-repository.md	Covers repository-level refusals.
docs/​upgrading/​v2-to-v3/​refusals-lists.md	Covers list-section refusals.
docs/​upgrading/​v2-to-v3/​library.md	Covers library API migrations.
docs/​upgrading/​v2-to-v3/​releases.md	Covers releases and tags.
test/​docs/​guides.test.ts	Reads the moved validation example.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

The split removes the original numbered fragments, breaking existing deep links to the guide.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Allowlist moved permision examples in refusals-lists.md
• Add section 61 to the library-consumer count

[Copilot]

Copilot review overview

🟢 Approval recommended

The split preserves all 61 numbered sections and updates the affected links, configuration, and test path consistently.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Allowlist moved permision examples in refusals-lists.md
• Add section 61 to the library-consumer count

[Copilot]

Copilot review overview

🔵 Needs a closer look

The section 3 summary row lacks the direct migration-detail link present for every other numbered break.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Allowlist moved permision examples in refusals-lists.md
• Add section 61 to the library-consumer count