Release: finalize the migration guide, test the AI prompt, write the 1.0.0 changelog

[tablackburn]

Part of #120 (Phase 5 — Release).

Scope

Finalize the consumer-facing release documentation, once the full break surface is known and soaking.

• docs/migration-v0.8-to-v1.0.md — review end to end. Per-PR entries have been accumulating throughout the cycle by design, so this is a coherence and completeness pass, not a writeup from scratch. Confirm the scope decision holds: breaking changes plus behavioral changes that can require action on upgrade.
• Test the AI migration prompt. The guide's top-of-file prompt is a v1.0.0 deliverable and has never been exercised. Run it against a real sample consumer build.ps1 with an agent and fix what it gets wrong. An untested prompt that produces a broken build.ps1 is worse than no prompt.
• CHANGELOG.md — write the 1.0.0 entry, summarizing the breaks and linking to the migration guide.

Gate

Blocked on every other v1.0.0 pull request being merged — the break surface must be complete before the guide can be called finished. Re-gated 2026-09-04: the preview and rc were dropped from the plan, so the gate is now the merge of #224, #225, #226, #227 and #228. This issue must close before 1.0.0 is tagged.

Done when

The migration guide is complete, the AI prompt has been verified against a sample consumer build, and the changelog entry is written.

[tablackburn]

Unblocked. This is now the only thing between the repository and 1.0.0.

Its gate read "blocked on 1.0.0-preview2 — the break surface must be complete before the guide can be called finished." That condition is satisfied, but by scope rather than by a release: #83 and #156 are deferred to 1.1.0, so Phase 3 is empty and nothing further is going into 1.0.0 that breaks anything. #157 and #158 are closed as superseded; the cycle cuts one prerelease, the rc1 in #160.

So the guide can be finished now, and it should be — the prerelease goes out after this, so soakers get finished documentation telling them what changed rather than an unfinished one.

Current state of the work:

• docs/migration-v0.8-to-v1.0.md is 747 lines across 12 sections. As this issue anticipated, the per-PR entries accumulated through the cycle, so this is a coherence and completeness pass rather than a writeup.
• The AI migration prompt has still never been run. That is the substantive item here: it is a v1.0.0 deliverable that rewrites a consumer's build.ps1, and shipping it untested is worse than shipping no prompt at all.
• The 1.0.0 changelog entry is unwritten. ## Unreleased has accumulated the full break surface and needs summarizing.

One addition to the completeness pass, since the guide predates them: the cycle picked up several changes after most of those entries were written — the Pester 6.0.0 floor (#172), the psake 5.0.4 floor (#166), Sign.SkipCertificateValidation actually working (#193), and the localized-string fix (#185). Worth checking each has an entry if it can require action on upgrade.

[tablackburn]

PR #200 is merged, but this stays open deliberately.

Done

• Guide coherence pass. 12 entries → 17. Four the changelog carried and the guide did not (README examples assign a setting that does not exist: $PSBPreference.Test.ScriptAnalysisEnabled #191, Test-PSBuildPester coverage threshold math truncates every percentage to zero #138, IB.tasks.ps1 reads a nonexistent CodeCoverage.OutputFormat setting, so Invoke-Build users get $null #178, $PSBPreference.Sign.SkipCertificateValidation has no effect on the Store and Thumbprint sources it is documented for #193), plus two the prompt test proved were missing: exact-version pinning (the guide speaks in floors while requirements.psd1 takes exact pins, and platyPS is replaced rather than upgraded) and the consumer's own manifest floor now being an untested claim. Table of contents verified programmatically — 17 headings, 17 links, no dangling anchors.
• The AI prompt has been tested, four runs across two sample consumers and two model families. It found three defects that reading could never have surfaced, the worst being that agent web-fetch tools commonly return a summary rather than the document — one run lost three entries silently. Details in docs: Finalize the migration guide and test the AI migration prompt #200.
• Changelog 1.0.0 summary written, under ## Unreleased for Release: bump to 1.0.0 and publish to PSGallery #160 to rename.

Why this is not closed

The gate on this issue was that the break surface must be complete before the guide can be called finished. That was true this morning. It stopped being true this afternoon, when #98 and #103 came back into the 1.0.0 milestone.

Those are test-writing tickets, and on this project test-writing has found a defect every single time: #169 (updatable help had never worked — three of them), the Get-PSBuildCertificate mocks that never reached the module, #197 (22 tests silently skipped on 5.1), #201 (found by accident). #98's own scope says to expect more. Any of those fixes that are user-facing need a guide entry, and #201 already looks like one.

What is left here

A final coherence pass once #98 and #103 close:

• Re-check the changelog's ## Unreleased entries against the guide's entries, the same way the first pass did — anything that can require action on upgrade needs an entry.
• Re-verify the table of contents against the headings.
• Re-check the 1.0.0 changelog summary's "breaks that require action" table, since it was written against today's surface.

That is a short pass, not a rewrite. It exists so that #160's "blocked on the release documentation being final" means something.