Evidence-tier publishing: contract sibling, latest-evidence.json, builder --evidence-release (#506)

README.md

@@ -135,6 +135,25 @@ by its explicit release id or tag until a separate promotion updates
 `latest.json`. Because Slack alerts are coupled to that production pointer
 update, tag-only publication sends no release alert.
 
+Evidence-tier releases (microcosm#506) are the third lane: the best available
+artifact when terminal gates failed, built with
+`tools/build_us_fiscal_refresh_release.py --evidence-release` (which records
+every gate failure with an owner issue in the release manifest's
+`known_failures` block, or refuses) and published with
+
+```bash
+tools/publish_release.sh releases/<id> --repo-id policyengine/populace-us --evidence
+```
+
+The `--evidence` flag validates against the evidence release contract — a
+certified-shape release is refused under it and vice versa — tags the
+immutable release as usual, and moves only `latest-evidence.json`; the
+certified `latest.json` pointer and the pe.py certification path never see
+evidence artifacts. Each evidence publish supersedes the last, so
+`latest-evidence.json` always names the best current evidence artifact
+(consumers: `microcosm.data.latest_evidence_release`). Its Slack alert is
+labeled as an evidence-tier publish.
+
 The alert is a **no-op unless the channel's incoming-webhook URL is set**, so
 configure it once on the build machine:
 

changelog.d/506-evidence-tier.added.md

@@ -0,0 +1 @@
+Evidence-tier publishing (microcosm#506): `validate_evidence_release_dir` as a structural sibling of the certified contract — same required files plus a mandatory non-empty `known_failures` block whose entries carry owner issue refs and are bound to the artifact's own record (every `gates.calibration` failure verbatim, every recomputed critical-target breach acknowledged by name); `publish_release(evidence=True)` moving only the new `latest-evidence.json` pointer (never `latest.json`, with both pointer paths reserved against manifest-declared artifacts on both tiers); `latest_evidence_release` for consumers plus a `tier` field on `LatestPointer` (defaulting to `certified`); `microcosm-publish-release --evidence`; and builder `--evidence-release` exporting on terminal-gate failure with the recorded failures owned or refused.