[CI/Compliance] Enforce the reusable final-package gate

[KeyffMS]

Completed state

SightAdapt now has one reusable final-package gate for every maintained binary producer. The maintained format is the Windows x64 portable ZIP; active channels are registered in release/distribution-channels.json.

Reusable gate

tools/new-verified-release-package.ps1 is the maintained package-creation entry point. It creates the ZIP and calls tools/verify-final-package.ps1, which consumes the existing focused validators rather than duplicating legal/SBOM/component logic.

The gate validates:

• the distribution channel is registered as maintained;
• the canonical required-file manifest;
• staged directory and final ZIP path equality;
• SHA-256 equality for every staged file and corresponding ZIP entry;
• exact .NET notice and component evidence;
• complete SBOM and license-report invariants;
• project/artifact metadata consistency;
• source commit SHA against checked-out repository HEAD;
• source ref and optional release-tag consistency;
• required workflow/run identity;
• final archive filename, size and SHA-256.

Schema-3 report

The final report records:

• channel and distribution format;
• source commit, repository HEAD, ref and optional tag;
• workflow name, run ID and attempt;
• archive name, size and SHA-256;
• one staged/archive SHA-256 evidence record per file;
• base compliance, component coverage and hash-comparison results;
• SBOM/license package counts and failures.

The ZIP and report are uploaded together only after a passing gate.

Maintained and planned channels

Maintained:

• github-actions-artifact;
• local-portable-zip.

Planned/inactive:

• github-release — tracked by [Release] Publish canonical GitHub Releases and immutable version tags #98;
• installer;
• store package — tracked by [Distribution] Publish SightAdapt in WinGet #107;
• official mirror — tracked by [Mirror] Create and maintain a SourceForge project mirror #109.

A planned channel is rejected until its implementation activates the registry entry and uses the reusable gate.

Negative validation

CI proves rejection of:

• unknown-license transitive dependency;
• incomplete legal bundle;
• stale redistribution notice;
• unmapped runtime component;
• modified archive bytes despite unchanged paths;
• incorrect source commit provenance;
• inconsistent tag/source-ref provenance;
• inactive GitHub Release channel.

Acceptance criteria

• Define one canonical required-file manifest.
• Validate the final staged directory and ZIP.
• Require all legal, privacy, SBOM and dependency artifacts.
• Reject empty or unresolved required files.
• Validate exact notice/build metadata.
• Validate complete SBOM/file coverage.
• Validate project, notice and artifact identity.
• Fail before artifact upload.
• Test deliberately incomplete, stale and unmapped packages.
• Compare every staged/archive file by SHA-256.
• Record commit/ref/tag/workflow/run provenance and archive checksum.
• Invoke one reusable gate from every maintained producer.
• Retain the schema-3 compliance report with the artifact.
• Formally separate maintained and planned channels.

Verified result

GitHub Actions run 30544829871 passed the complete pipeline. The schema-3 report recorded:

• result: pass;
• 17 staged/archive SHA-256 matches;
• channel github-actions-artifact;
• format portable-zip;
• source commit equal to repository HEAD;
• workflow run 30544829871;
• archive SHA-256 BCCDAB8135DE1D539DFE8A750E13F6B603C1B2870CE36AC5E7042DF2495471D0.

PR #144 was merged as e5ce7c1d44af152b480173f303fb7a4b41c01b75.

Re-review triggers

Reopen or create channel-specific work when adding a GitHub Release, installer, store package, mirror or different container format. The implementation must define the final unpacked/installed tree, activate the channel registry, call the reusable gate and add format-specific tests.

[KeyffMS]

Wynik audytu uzupełniającego — 2026-07-30

Ocena: kompletne dla obecnego GitHub Actions ZIP, niekompletne dla pełnego deklarowanego zakresu; ponownie otwarte.

Aktualna bramka poprawnie sprawdza staged directory, ZIP, notice metadata, wynik licencji, SBOM i niekompletną paczkę. Nie jest jednak wdrożona jako jedna reusable kontrola dla GitHub Releases, instalatorów, store packages i mirrorów. Porównanie staged directory z ZIP-em obejmuje listę ścieżek, ale nie zgodność hashy każdego pliku. Raport nie zapisuje source commit SHA ani release tagu.

Pozostałe prace

• wyodrębnić reusable final-package gate wywoływany przez każdy utrzymywany workflow dystrybucji;
• walidować finalne installed/unpacked tree instalatora i store package;
• porównywać hash każdego pliku staged directory z odpowiadającym wpisem archiwum/kontenera;
• zapisywać w raporcie source commit SHA, tag, workflow/run, artifact checksum i format dystrybucji;
• dodać negatywne testy dla starego notice’u, niepełnego SBOM, zmienionego pliku w ZIP-ie oraz błędnego commit/tag provenance;
• publikować ten sam raport z GitHub Release i każdym mirrorem.

Issue można zamknąć po technicznym objęciu wszystkich deklarowanych formatów albo po formalnym ograniczeniu jego zakresu.

[KeyffMS]

Triage priority — P1

Reason: the current Actions ZIP has a working staged-directory/final-archive gate, but the same enforcement is not implemented for GitHub Releases, installers or store containers. The report also lacks source commit/tag provenance, and staged/archive equality is checked by path list rather than per-file hashes.

Close only when:

• one reusable gate is invoked by every maintained release format;
• staged and packaged files are compared by cryptographic hash;
• the report records source commit, tag, workflow/run identity and outer-container checksum;
• GitHub Release publication cannot proceed without the verified package and report.

Escalation: move to P0 before publishing through a new release channel.