PlatyPS 2a: baseline the help building functions #149

Part of #120 (Phase 2 — PlatyPS migration, #105).

Re-scoped 2026-08-24. This ticket was "add Microsoft.PowerShell.PlatyPS 1.x
alongside the existing platyPS 0.14.2 so the two can coexist while the three
Build-PSBuild*Help functions are migrated one at a time."

They cannot coexist, and the functions cannot be migrated one at a time. Both modules
load their own YamlDotNet.dll through NestedModules with different assembly
identities, so whichever imports second fails with "Assembly with same name is already
loaded" — in either order, on PowerShell 7. Independently, 2b changes the on-disk
markdown schema that an unmigrated Build-PSBuildMAMLHelp would be handed. The three
migrations are atomic.

With an atomic migration there is no window in which both modules are needed. The code
references exactly one PlatyPS at a time — requirements.psd1, the RequiredModules
manifest entry, and six Get-Module platyPS -ListAvailable PreConditions across
psakeFile.ps1 and IB.tasks.ps1 — and all of them flip in one commit. So the
dependency swap moved into the migration itself, and #153 folded into it.

What remains here is the half that has to happen first either way: the tests.

Scope

Baseline test coverage for Build-PSBuildMarkdown, Build-PSBuildMAMLHelp, and
Build-PSBuildUpdatableHelp, written against current platyPS 0.14.2 behavior, so the
migration has something to regress against.

This matters more than it looks. None of the three functions has ever had a test, and the
repository does not run its own docs tasks either — the root psakeFile.ps1 goes Init →
Clean → Build → Analyze → Pester → Publish and never invokes GenerateMarkdown,
GenerateMAML, or GenerateUpdatableHelp. Three functions about to be rewritten have
nothing observing them.

Watch for

• Subprocess isolation is mandatory, not stylistic. Because the two modules cannot share
  a session, old and new behavior can only be compared across processes. Build the harness
  that way now rather than retrofitting it at 2b.
• Time out the jobs. A hung job stalls CI with no output — the failure mode Windows builds hang when the HEAD commit message is large (Invoke-Git deadlock) #167
  produced.

Done when

The three functions have baseline coverage that passes on every CI leg, and 2b/2c/2d have a
red-before-green target.

Found while doing this

#169 — Build-PSBuildUpdatableHelp cannot succeed as wired: the module landing page it
needs is never generated, $moduleOutDir is undefined, and -Module is never passed. Now a
sub-issue of #152, which is a port plus those fixes rather than a port.