fix(core): a coverage figure is the union across a tree's supported hosts (#521)

[SUaDtL]

Closes #521. Implements DECISION-0031.

The claim that was wrong

tech-stack.md said the coverage script "takes no arguments so it is identical on every platform." True of the command. Misleading about the report — which is what a reader decides with, and what tdd Phase 5 gates on.

Code behind a platform fork cannot execute off its own platform, so a single-host report scores the other platform's arm as uncovered no matter how well tested it is:

	Windows	Linux	gap
plugins/ca/tools branches	66.18%	65.35%	—
exec.ts branches	87.50%	76.38%	11 points

That 11 points is entirely awaitTaskkill plus the win32 treeKill arm on one side, and the POSIX arm on the other. Neither number is wrong; both are incomplete.

It matters beyond arithmetic. treeKill is a process-containment path — so under a single-host rule a genuine gap in it is indistinguishable from the platform artifact. The figure stops measuring test quality and starts measuring how much of the tree is POSIX.

The rule (AC-2)

A quoted coverage figure is the union across a tree's supported hosts. Any figure quoted in an issue, ADR, or phase record names the host it came from.

Per tree, because it only earns its cost where code actually forks:

tree	forks on platform	union in CI
plugins/ca/tools	yes — exec.ts on process.platform	ubuntu + windows, merged
plugins/ca-pi/tools	yes — Windows supervisor / process-tree	not yet — #537
plugins/ca-sandbox/tools	no	single-host
site/	no	single-host

A union of two identical reports is the same report.

#511's closing measurement is restated, not silently reinterpreted: the single-host baseline table is now labelled windows-only and marked superseded as a basis for a threshold decision.

AC-1 and AC-3

• tech-stack.md separates the identical command from the host-dependent result.
• includes/maturity-coverage.md carries the rule; tdd Phase 5 defers to it and now requires the measuring host to be named. Those are the two places that describe how the threshold is applied, and they agree.

Both are generated surface, so ca-codex and ca-pi receive identical text.

The union is real, not assumed

I verified --merge-reports genuinely recomputes coverage across blobs rather than letting the last one win — two disjoint suites, measured separately and merged:

redactor.test.ts      Branches:  7/982    Lines: 18/1206
worktree-fs.test.ts   Branches: 65/982    Lines: 69/1206
MERGED                Branches: 72/982    Lines: 87/1206

7 + 65 = 72, 18 + 69 = 87. Exactly additive.

The merge job reports how many hosts contributed and says so when only one did, so a partial figure is never mistaken for the union.

Advisory by design

DECISION-0031 weighed Available explicitly. The coverage gate is orchestrator-run; these jobs only produce the figure it quotes. Enforcing them would let a Windows runner flake — #535 is live — block a merge on a number no check consumes.

So they are awaited by ci-passed (a hang stays visible) and never enforced. The sanctioned-advisory assertion is extended to name them, which is a deliberate contract change with the reason written down, not a fix for a red build. A new test asserts they never become required.

Why ca-pi split out (#537)

Mechanical, not a design question. The audited-graph contract attributes a job's dependency graph by its working directory, which only resolves when that directory is literal — a matrix.tree-templated one resolves to ., which nothing audits. Compensating with extra npm audit steps breaks a second contract pinning the exact audit inventory across ci.yml and docs.yml.

Both contracts are right, and satisfying them means one job per tree. tech-stack.md says ca-pi has no union job yet rather than implying coverage it does not have.

Verification

• test_ci_impact.py 52 pass, including two new contracts: the union must measure on both hosts and actually merge; and it must never become a required check.
• build-surface --check in sync across claude/codex/pi; build-host-packages --check consistent.
• Badge/count/catalog consistent; test_release_lib 83, test_public_codex_docs 3, test_public_pi_docs 13 — all pass.
• All four payload gates verified locally against origin/main: ca 2.10.1 → 2.10.2, ca-codex 0.3.0 → 0.3.1, ca-pi 0.1.38 → 0.1.39 with root metadata regenerated, ca-sandbox unchanged.

Note on the diff

The two contracts above rejected my first two designs before this one — a templated matrix over trees, then compensating audit steps. Both were caught by existing tests rather than by review, which is the outcome those tests were written for.