docs: Finalize the migration guide and test the AI migration prompt

[tablackburn]

Closes #159

Three deliverables: the guide's completeness pass, the first exercise of the AI migration prompt, and the 1.0.0 changelog summary.

The prompt had never been run. It has now, four times.

I built two sample consumers — a psake one and an Invoke-Build one, each a realistic 0.8.x repository with a removed setting, stale dependency pins, a committed 0.14.x docs tree with hand-written prose, and a coverage threshold — then handed the prompt verbatim to fresh agents on two model families with no other context. That is the only honest way to test a prompt aimed at "a consumer's agent."

The finding I could not have got by reading

Agent web-fetch tools commonly do not return the page. They run a small model over it and hand back a summary. This harness's own tool documents it plainly:

Fetches a URL, converts the page to markdown, and answers prompt against it using a small fast model.

One run measured the damage: three entries silently absent — ParseError, the module landing page, the committed-docs conversion — with the result still reading as complete. It only got the real text via gh api ... | base64 -d.

The prompt now demands the raw file and gives a structural self-check the agent can actually run: the guide ends with a Related section, so a copy without one is partial. Do not proceed on a summary.

Two more defects, both found by agents doing exactly what it said

• It never told the agent to update the PowerShellBuild version. No entry covers the pin, and every task step was scoped to entries. Followed literally, an agent removes AlphabeticParamsOrder, changes nothing else, and leaves a build still running 0.8.2 while reporting success. For a psake consumer, -FromModule PowerShellBuild -Version '0.8.2' is the upgrade.
• requirements.psd1 was out of scope as written — inputs were "my build file" and "psake or Invoke-Build files it references." But the psake, Pester, and PlatyPS floors are only actionable there. Both agents treated it as in scope anyway, correctly, against the prompt's own wording.

The re-test

Same fixture, same model, after fixing the above. All three failures gone: version pin updated, dependency manifest handled, a 13-item advisory checklist produced, and the baseline test run taken before the pin change rather than after — because a correct migration pins a version that cannot be installed yet.

It then found six more, all fixed here. The two that matter:

• Correcting the ScriptAnalysisEnabled name is a behavior change, not a typo fix. With the wrong name, analysis has been running all along. Fixing it turns analysis off for real — and if the CI job the consumer believed was running analysis has quietly gone away, the guide just told them to delete their only coverage. The entry now says to look before deciding.
• "Cannot newly fail your build" was true and misleading. A consumer with a coverage threshold has never once seen a real number; 1.0.0 is where they find out it is under half what they set. The gate is not newly stricter, it is newly working, and that feels identical from outside.

Also: the docs-conversion entry assumed GenerateMarkdown runs (it skips silently in three common cases, and then converts nothing); and "roughly half" of entries need no code change was wrong in the flattering direction — 13 of 16 for one sample consumer. Saying half makes an accurate checklist look padded.

Guide: 12 entries → 17

Four the changelog carried and the guide did not, each able to require action on upgrade — the setting name that never existed (#191), coverage percentages truncated to zero (#138), Invoke-Build coverage reporting (#178), and signing validation that now has an effect (#193).

Two the agents proved were missing. The guide speaks in floors while requirements.psd1 takes exact pins, and platyPS is replaced rather than upgraded — leaving both PlatyPS modules pinned is worse than leaving neither, since their YamlDotNet assemblies collide. And a consumer manifest declaring below 5.1 is now an untested claim, because nothing in their pipeline can exercise it.

TOC verified programmatically: 17 headings, 17 links, no dangling anchors, no unlinked entries. Five bare #nnn references made clickable.

Changelog

A 1.0.0 summary heading the section: what the release is, the breaks that require action as a table, and the three fixes that mean a setting the consumer configured was doing nothing. Left under ## Unreleased for #160 to rename at release.

Verification

• Full suite 503 passed, 0 failed, 3 skipped throughout; Analyze clean.
• Both files verified CRLF-only, no lone LF, no \r\r\n.
• Sample consumers were scratch fixtures outside the repository; nothing here depends on them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Test Results

    4 files  ±0    785 suites  ±0   2m 42s ⏱️ +20s
  508 tests ±0    505 ✅ ±0   3 💤 ±0  0 ❌ ±0 
2 015 runs  ±0  1 943 ✅ ±0  72 💤 ±0  0 ❌ ±0 

Results for commit 85a40df. ± Comparison against base commit a4fa998.