win11-release-guard 0.3.0

Windows 11 broad-fleet release compliance guard.

Windows 11 Release Guard

Windows release policy guard for broad-fleet Windows 11 version checks.

Windows 11 Release Guard tells administrators whether an existing Windows 11 device is on the current broad-fleet release and quality baseline, using a signed public policy feed plus local build evidence. The repository, distribution package, installed console command, and Python import package use the same win11_release_guard name.

At A Glance

Question	Answer
Current broad target	Windows 11 25H2 for existing broad-fleet devices
Special release handling	26H1 is treated as new-devices-only / excluded for existing 24H2 or 25H2 devices
Trust source	Public JSON policy plus detached Ed25519 signature
Local truth model	Build-first evidence; display labels are diagnostics
WUA role	Optional read-only secondary evidence
Output	Pretty console, JSON, JSON-pretty, file output
Version	0.3.0
License	GPL-3.0-only, see LICENSE.txt

Project Identity

• GitHub repo: https://github.com/Avnsx/win11_release_guard
• GitHub releases: https://github.com/Avnsx/win11_release_guard/releases
• Changelog: CHANGELOG.md
• Python package metadata: win11_release_guard version 0.3.0, README.md long description, LICENSE.txt, package data data/*.json and data/*.sig.
• PyPI project name: win11_release_guard; Trusted Publisher values are owner Avnsx, repository win11_release_guard, workflow pypi-publish.yml, environment pypi. Publishing uses GitHub Actions OIDC only, not a PyPI API token.
• Public feed: https://avnsx.github.io/win11_release_guard/windows-release-policy.json
• Python entry point: python -m win11_release_guard
• Console script: win11_release_guard

Do not reintroduce the old prototype script named by joining windows, releases, and info with underscores and adding .py; do not revert naming back to earlier project identities.

Quick Start

python -m pip install -e ".[test]"
python -m win11_release_guard --pretty
python -m win11_release_guard --json-pretty --no-wua
python -m win11_release_guard --check-policy-source
python -m win11_release_guard --check-public-pages

For production compliance jobs, prefer:

python -m win11_release_guard --strict-production --json-pretty --no-wua

Exit codes:

Code	Meaning
0	compliant or source check passed
1	feature or quality update required
2	unknown, incomplete, or source/policy problem
3	above broad target or special release
10	CLI argument error

Public Feed / Dashboard

Artifact	Link
Pages dashboard	https://avnsx.github.io/win11_release_guard/
Signed policy JSON	https://avnsx.github.io/win11_release_guard/windows-release-policy.json
Detached signature	https://avnsx.github.io/win11_release_guard/windows-release-policy.json.sig
Policy manifest	https://avnsx.github.io/win11_release_guard/policy-manifest.json
API v1 policy	https://avnsx.github.io/win11_release_guard/api/v1/policy.json
API v1 signature	https://avnsx.github.io/win11_release_guard/api/v1/policy.sig
API v1 manifest	https://avnsx.github.io/win11_release_guard/api/v1/manifest.json

GitHub Pages is regenerated by .github/workflows/publish-policy.yml from workflow-created site/ output. Do not commit local site/; use workflow_dispatch to refresh Pages manually. Docs/wiki-only changes do not need a Pages rebuild unless they change dashboard-rendered content, generated metadata, public URLs, or workflow path filters.

Workflow Badge Semantics

Dependency freshness is checked by a scheduled workflow. Dependency freshness is a scheduled direct-dependency check over direct dependency specifiers; it is not an always-current dependency guarantee. The Pylint badge reports the workflow for the current --fail-under=8.0 gate, not a permanent quality certificate.

Core Concepts

• Runtime clients fetch public JSON plus .sig; they do not authenticate to GitHub.
• Ed25519 verification, schema validation, hash checks, and source status decide whether policy evidence is usable.
• Local Windows evidence is build-first: RtlGetVersion, DISM, kernel file version, registry, and WMI/CIM are weighted signals.
• ProductName, WMI Caption, and DisplayVersion are display-only diagnostics and must not override build and policy evidence.
• WUA is optional read-only secondary evidence; it explains offers/history but never changes the signed policy target.
• 25H2 is the current broad target for existing devices; 26H1 is excluded for existing devices.
• baseline_build / required_baseline_build is the required B-release baseline; latest_observed_build can include newer observed preview/current-table builds.
• B-release baselines are the default quality policy; D-preview builds can be compliant with preview warnings unless disallowed.
• The Pages dashboard avoids static-age drift by embedding generated_at_epoch_s and recalculating feed age with browser Date.now().
• --strict-production returns production-green only from fresh live signed remote JSON; cache and bundled fallback are degraded evidence.
• Public /api/v1 aliases and signing-key overlap rules are maintained for at least 24 months unless a documented last-resort trust break is required.

The production generator uses public Microsoft Release Health and Atom sources only; it does not use token-authenticated Microsoft APIs. Runtime clients do not authenticate to GitHub and do not need GitHub tokens, private repository access, or a paid signing certificate. WUA diagnostics never override the policy verdict.

Wiki Deep Dive

Topic	Link
Wiki home	https://github.com/Avnsx/win11_release_guard/wiki
Quick Start	https://github.com/Avnsx/win11_release_guard/wiki/Quick-Start
Architecture	https://github.com/Avnsx/win11_release_guard/wiki/Architecture
Policy Feed & Trust Model	https://github.com/Avnsx/win11_release_guard/wiki/Policy-Feed-and-Trust-Model
Local Windows Detection	https://github.com/Avnsx/win11_release_guard/wiki/Local-Windows-Detection
GitHub Pages Dashboard	https://github.com/Avnsx/win11_release_guard/wiki/GitHub-Pages-Dashboard
Source Diagnostics	https://github.com/Avnsx/win11_release_guard/wiki/Source-Diagnostics
Anti-Static Freshness	https://github.com/Avnsx/win11_release_guard/wiki/Anti-Static-Freshness
CLI & RMM Usage	https://github.com/Avnsx/win11_release_guard/wiki/CLI-and-RMM-Usage
Build, Test & Release	https://github.com/Avnsx/win11_release_guard/wiki/Build-Test-and-Release
Tagged Release Lane	https://github.com/Avnsx/win11_release_guard/wiki/Tagged-Release-Lane
Safe Exports & Clean Archives	https://github.com/Avnsx/win11_release_guard/wiki/Safe-Exports-and-Clean-Archives
Release v0.3.0	https://github.com/Avnsx/win11_release_guard/wiki/Release-v0.3.0
Troubleshooting	https://github.com/Avnsx/win11_release_guard/wiki/Troubleshooting
Agent Chokepoints	https://github.com/Avnsx/win11_release_guard/wiki/Agent-Chokepoints
FAQ	https://github.com/Avnsx/win11_release_guard/wiki/FAQ

Maintainer Commands

python -m compileall -q win11_release_guard tools
python tools/check_project_identity.py
python tools/check_version_consistency.py
python tools/check_github_action_versions.py
pytest -q
python tools/scan_for_secret_material.py site win11_release_guard tests tools docs wiki README.md CHANGELOG.md AGENTS.md pyproject.toml .github
python -m build
python -m twine check dist/*
python tools/export_clean_archive.py --output dist/win11_release_guard-source.zip
python tools/export_clean_archive.py --validate dist/win11_release_guard-source.zip

Workflow JavaScript actions opt into Node 24 with FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true.

Deployment-affecting changes require the live Pages gate before handover. Deployment-affecting changes include workflow changes, policy generator changes, signing changes, Pages landing page changes, manifest/API alias changes, source URL or published URL changes, CLI changes to --check-policy-source, and --check-public-pages. If live network is unavailable, run local/mocked gates and do not claim live success. If a live check fails, record the exact failing URL, status, and error.

Required live-gate command set:

python -m compileall -q win11_release_guard tools
pytest -q
python tools/generate_policy.py --release-health-html tests/fixtures/windows11-release-health.html --atom-feed tests/fixtures/windows11-atom.xml --output-dir site --write-index --write-robots --write-sitemap --write-manifest
python tools/scan_for_secret_material.py site win11_release_guard tests tools docs wiki README.md CHANGELOG.md AGENTS.md pyproject.toml .github
python -m win11_release_guard --check-policy-source
python -m win11_release_guard --check-public-pages

See docs/README.md for maintainer documentation and the local wiki source folder under wiki/Home.md. The repository wiki/ folder is source/staging for the GitHub Wiki; it does not auto-publish to the live wiki. Maintainer deep links: v0.3.0 release notes, Tagged release lane, policy signing, security automation.

Contribution And Security Notes

Do not commit GitHub tokens, private signing keys, raw worktree ZIPs, local handover notes, generated site/, generated dist/, .tmp/, dependency-freshness.json, package metadata folders, pycache, generated caches, or private key scratch files. Generated policy feed data is public non-secret data, but trust comes from the detached signature and committed public verification keys.

This project is independent open-source software, licensed under GPL-3.0 in LICENSE.txt, and is not affiliated with Microsoft.