fix: compose release document normalization

Systematically harden release-document normalization, immutable evidence binding, archive parity, and the normal release workflow.

Author: tensornull

.github/workflows/publish.yml

@@ -286,6 +286,8 @@ jobs:
         run: uv run python scripts/check_artifacts.py dist/*
       - name: Install and smoke-test each exact artifact
         run: uv run python scripts/check_clean_install.py dist/*
+      - name: Verify the immutable release as a copied standalone repository
+        run: python scripts/check_repository_independence.py
       - name: Record immutable artifact digests
         run: sha256sum dist/* > artifact-sha256.txt
       - name: Retain only the verified release bundle

AGENTS.md

@@ -157,14 +157,17 @@ Post-stable invariants:
 12. Keep `CHANGELOG.md` release-only: do not maintain an unmanaged `Unreleased`
     section. Record changes in Conventional Commits and let Release Please own
     the newest canonical dated release section after the changelog preamble.
-    The version gate must reject any `Unreleased` level-two heading before merge
-    or release.
+    Use only canonical Markdown for level-two changelog headings; raw HTML H2
+    parsing is renderer-dependent and must fail the version gate before merge or
+    release. The same gate must reject any `Unreleased` level-two heading.
 13. A validated release-evidence block binds one canonical publication workflow
-    run to its machine-readable identity marker and may contain no other Actions
-    run URL. Keep preparatory implementation, CI, Release Please, failed-attempt,
+    run URL without an attempt suffix to its machine-readable identity marker and
+    may contain no other Actions run URL. Record attempt provenance as plain
+    text. Keep preparatory implementation, CI, Release Please, failed-attempt,
     and recovery history outside that block. The document gate must reject
-    non-canonical, wrapped, malformed, or contradictory workflow URLs regardless
-    of prose or Markdown labeling.
+    non-canonical, wrapped, encoded, control-obfuscated, malformed, or
+    contradictory workflow URLs regardless of prose or Markdown labeling, and
+    bind each source occurrence to exactly one rendered navigation destination.
 
 ## Repository independence
 
@@ -289,8 +292,10 @@ workflow after maintainer authorization.
 Build wheel and source distribution into a clean output directory. Inspect
 their metadata and file lists, install each exact artifact independently
 outside the source tree, assert version and public imports, and run mocked-call
-smokes. Generated artifacts, local environments, and credentials must never be
-committed.
+smokes. Require every reviewed sdist member to match the release checkout byte
+for byte, and rerun the copied standalone repository verification in the
+immutable-tag build before retaining digests. Generated artifacts, local
+environments, and credentials must never be committed.
 
 ## Release and documentation rules
 

ARCHITECTURE.md

@@ -133,7 +133,9 @@ sdist, and PyPI metadata are immutable, the README uses an unversioned install
 command and publication-neutral release language that remains accurate before
 and after a release. Source-document and artifact checks reject approval,
 unpublished, exact-version installation, and versioned release-link text; each
-artifact long description must also exactly match the source README.
+artifact long description must also exactly match the source README. Artifact
+inspection additionally requires every reviewed source-distribution member to
+match the release checkout byte for byte.
 
 Release Please v5.0.0 is pinned to the immutable commit whose action metadata
 uses `node24`. The workflow semantic contract fixes that SHA and runtime
@@ -146,7 +148,8 @@ Conventional Commits and never maintain an `Unreleased` placeholder. The
 version gate rejects that structurally incompatible placeholder, accepts Release
 Please's native linked form and legacy dated history, and validates repository,
 previous tag, candidate tag, and calendar date without rewriting generated
-history.
+history. Raw HTML level-two headings are rejected rather than interpreted with
+renderer-specific error recovery.
 
 The PyPI publisher remains directly in `publish.yml` and is pinned to its
 reviewed Node 24 maintenance release. Pinning its exact SHA prevents a syntactic
@@ -165,11 +168,14 @@ ambiguous external state and is forbidden.
 Immutable run, tag, commit, registry, and digest records live only in the
 validated release-evidence blocks in `ROADMAP.md` and `RELEASING.md`. Each
 block binds only the canonical publication run through its machine-readable
-identity; preparatory implementation, CI, Release Please, failed-attempt, and
-recovery history stays outside the block. The checker rejects every other run
-identity plus wrapped or malformed Actions URLs, so Markdown wording cannot
-disguise a contradictory workflow. Architecture documents mechanisms and
-boundaries, not a second historical ledger.
+identity, without an attempt suffix; attempt provenance remains plain text.
+Preparatory implementation, CI, Release Please, failed-attempt, and recovery
+history stays outside the block. The checker rejects every other run
+identity and binds every source occurrence to exactly one rendered Markdown or
+HTML navigation destination after bounded normalization. Wrapped, encoded,
+control-obfuscated, malformed, or contradictory Actions URLs fail closed, so
+prose and renderer syntax cannot disguise a workflow identity. Architecture
+documents mechanisms and boundaries, not a second historical ledger.
 
 The scheduled/manual default-branch smoke is an operational canary only; it
 does not prove the release commit. `COMETAPI_KEY` is exposed only to the

RELEASING.md

@@ -202,13 +202,17 @@ authorization failure.
 Conventional Commits carry pending changes, and Release Please owns the newest
 canonical dated section immediately after the preamble. The version gate rejects
 any unmanaged `Unreleased` level-two heading so the generated layout remains
-valid on every patch release.
+valid on every patch release. Use only canonical Markdown for level-two
+headings; raw HTML H2 semantics vary by renderer and therefore fail closed.
 
 Each validated release-evidence block contains the immutable release identity
-and only its canonical publication workflow. Preparatory implementation CI,
-Release Please, failed-publication, and recovery history remains outside the
-block. The document gate rejects every different run identity and every wrapped
-or malformed Actions URL regardless of prose or Markdown labeling.
+and only its canonical publication workflow URL without an attempt suffix.
+Record attempt provenance as plain text. Preparatory implementation CI, Release
+Please, failed-publication, and recovery history remains outside the block. The
+document gate binds every source occurrence to exactly one rendered navigation
+destination and rejects every different run identity plus wrapped, encoded,
+control-obfuscated, or malformed Actions URLs regardless of prose or Markdown
+labeling.
 
 Release mode (`check_version.py --require-releasable-docs`) also fails closed
 until project authorship, the canonical GitHub repository URL, the copyright
@@ -225,7 +229,8 @@ description. The README therefore uses the unpinned
 PRs and post-release evidence changes must not introduce approval, unpublished,
 or exact-version availability statements. Artifact inspection applies the same
 policy to wheel `METADATA` and sdist `PKG-INFO`, so source and registry-facing
-descriptions cannot drift.
+descriptions cannot drift. Artifact inspection also requires every reviewed
+source-distribution member to match the release checkout byte for byte.
 
 ## Workflow responsibilities
 
@@ -290,7 +295,9 @@ descriptions cannot drift.
   against the exact pre-publication digests and Trusted Publisher provenance
   before a clean install explicitly from `https://pypi.org/simple/`. The exact
   release live model is the canonical active model enforced by the workflow
-  checker and cannot be overridden by repository variables.
+  checker and cannot be overridden by repository variables. Before digest
+  retention, the immutable-tag build also copies the checkout into an empty
+  parent and completes the standalone repository verification there.
   Because the unused Release Please or recovery path is intentionally skipped,
   every job after the selector must use `always() && !cancelled()`, reject
   reruns, and require each direct dependency's result to equal `success`. This
@@ -556,8 +563,8 @@ authorized.
   `64c7cb87745032703b3374cc562ea00b979416c54908862dbcebd116b2dc44c8`.
   Both files match the retained pre-publication digest record. PyPI Integrity
   API provenance identifies repository `cometapi-dev/cometapi-python`, workflow
-  `publish.yml`, environment `pypi`, release commit `576e7503`, and release
-  [run attempt 1](https://github.com/cometapi-dev/cometapi-python/actions/runs/30429821548/attempts/1).
+  `publish.yml`, environment `pypi`, release commit `576e7503`, and release run
+  attempt 1.
 - An independent post-workflow verification downloaded both public files,
   verified both provenance records with `pypi-attestations==0.0.29`, installed
   `cometapi==0.1.1` from `https://pypi.org/simple/`, verified the public version
@@ -612,8 +619,8 @@ authorized.
   `21c8edc0586610de1a9a8cd39b54ed23d2b1e20552100f69f53938cb7678da3d`.
   Both files match the retained pre-publication digest record. PyPI Integrity
   API provenance identifies repository `cometapi-dev/cometapi-python`, workflow
-  `publish.yml`, environment `pypi`, release commit `710c5649`, and release
-  [run attempt 1](https://github.com/cometapi-dev/cometapi-python/actions/runs/30515861246/attempts/1).
+  `publish.yml`, environment `pypi`, release commit `710c5649`, and release run
+  attempt 1.
 - An independent post-workflow verification downloaded both public files,
   verified both provenance records with `pypi-attestations==0.0.29`, installed
   `cometapi==0.1.2` from `https://pypi.org/simple/`, verified the public version
@@ -670,8 +677,8 @@ authorized.
   `07ded54606d50f44b689dad38cf93a74e1175370efaa33be84a3c01240d48e66`.
   Both files match the retained pre-publication digest record. PyPI Integrity
   API provenance identifies repository `cometapi-dev/cometapi-python`, workflow
-  `publish.yml`, environment `pypi`, release commit `45429f37`, and release
-  [run attempt 1](https://github.com/cometapi-dev/cometapi-python/actions/runs/30550536000/attempts/1).
+  `publish.yml`, environment `pypi`, release commit `45429f37`, and release run
+  attempt 1.
 - Independent post-workflow verification downloaded both public files,
   verified both provenance records with `pypi-attestations==0.0.29`, installed
   `cometapi==0.1.3` from `https://pypi.org/simple/`, verified the public version

ROADMAP.md

@@ -579,8 +579,8 @@ and source-distribution SHA256
 `64c7cb87745032703b3374cc562ea00b979416c54908862dbcebd116b2dc44c8`.
 Both files matched the retained pre-publication digest record. Their PyPI
 Integrity API provenance names repository `cometapi-dev/cometapi-python`,
-workflow `publish.yml`, environment `pypi`, release commit `576e7503`, and
-[run attempt 1](https://github.com/cometapi-dev/cometapi-python/actions/runs/30429821548/attempts/1).
+workflow `publish.yml`, environment `pypi`, release commit `576e7503`, and run
+attempt 1.
 An independent post-workflow verification downloaded both public files,
 verified their provenance with `pypi-attestations==0.0.29`, installed
 `cometapi==0.1.1` from the public simple index, checked version and public
@@ -651,8 +651,8 @@ and source-distribution SHA256
 `21c8edc0586610de1a9a8cd39b54ed23d2b1e20552100f69f53938cb7678da3d`.
 Both files match the retained pre-publication digest record. Their PyPI
 Integrity API provenance names repository `cometapi-dev/cometapi-python`,
-workflow `publish.yml`, environment `pypi`, release commit `710c5649`, and
-[run attempt 1](https://github.com/cometapi-dev/cometapi-python/actions/runs/30515861246/attempts/1).
+workflow `publish.yml`, environment `pypi`, release commit `710c5649`, and run
+attempt 1.
 An independent post-workflow verification downloaded both public files,
 verified both provenance records with `pypi-attestations==0.0.29`, installed
 `cometapi==0.1.2` from the public simple index, verified the public version and
@@ -716,8 +716,7 @@ and source-distribution SHA256
 Both public files match the retained pre-publication digest record. PyPI
 Integrity API provenance identifies repository
 `cometapi-dev/cometapi-python`, workflow `publish.yml`, environment `pypi`,
-release commit `45429f37`, and release
-[run attempt 1](https://github.com/cometapi-dev/cometapi-python/actions/runs/30550536000/attempts/1).
+release commit `45429f37`, and release run attempt 1.
 An independent post-workflow verification downloaded both public files,
 verified both provenance records with `pypi-attestations==0.0.29`, installed
 `cometapi==0.1.3` from `https://pypi.org/simple/`, verified the public version