win11-release-guard 0.3.1

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 fleet release and quality baseline, using a signed JSON feed, build-first local evidence, a static GitHub Pages dashboard/API, and a PyPI package for sysadmin/RMM automation. The repository, distribution package, installed console command, and Python import package use the same win11_release_guard name.

Fact	Value
Project / package	win11_release_guard
Version	0.3.1
Console script	win11_release_guard
Python entry point	python -m win11_release_guard
Repository	https://github.com/Avnsx/win11_release_guard
PyPI	https://pypi.org/project/win11_release_guard/
Public feed	https://avnsx.github.io/win11_release_guard/windows-release-policy.json

What This Does

• Checks Windows 11 release/build/baseline compliance from a signed public JSON release policy feed.
• Uses build-first local evidence; ProductName, WMI Caption, and DisplayVersion stay diagnostic.
• Keeps Windows Update Agent data optional and secondary; WUA diagnostics never override the policy verdict.
• Compacts local Panther/setup log tails in JSON by default while keeping raw bounded local diagnostics available through an explicit CLI opt-in.
• Keeps Panther reads narrow and fast with fixed known paths, per-file tail reads, and a generous global collection guard.
• Treats Panther/setup logs as administrator troubleshooting evidence only; they never decide compliance or override signed public policy.
• Shows Source Diagnostics as Notice, Warning, and Error categories on the static dashboard; these are troubleshooting signals, not fleet verdict authority.
• Shows GitHub Issue ticket links only from workflow-generated static metadata; browser JavaScript never creates or syncs issues.
• Treats existing devices as targeting 25H2 while 26H1 remains excluded for existing-device targeting.
• Emits human output, JSON, JSON-pretty, file output, and stable exit codes for RMM/fleet checks.
• Publishes a static GitHub Pages dashboard, Pages Wiki, and /api/v1 policy, signature, and manifest aliases.

Quick Start

Install the released package:

python -m pip install win11_release_guard
win11_release_guard --pretty
win11_release_guard --json-pretty --no-wua
win11_release_guard --json-pretty --include-raw-local-diagnostics

Use the source checkout for development or release-candidate validation:

python -m pip install -e ".[test]"
python -m win11_release_guard --self-test
python -m win11_release_guard --check-policy-source
python -m win11_release_guard --check-public-pages

Production compliance jobs normally use:

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

Deep dive: Quick Start, CLI and RMM Usage, Configuration.

Public Feed And Dashboard

Artifact	URL
Pages dashboard	https://avnsx.github.io/win11_release_guard/
Pages Wiki	https://avnsx.github.io/win11_release_guard/wiki/
Pages changelog	https://avnsx.github.io/win11_release_guard/wiki/changelog/
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

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. GitHub Pages is static; feed freshness is recomputed from generated timestamps in the browser and CLI. Source Diagnostics tiles filter Notices, Warnings, and Errors; View all resets the feed. Optional #Ticket links are hover/focus-only static links to repository issues when workflow-generated metadata exists.

Deep dive: GitHub Pages Dashboard, Anti-Static Freshness, dashboard docs.

Common User Paths

You are	Start here
New user	Quick Start
Admin / RMM user	CLI and RMM Usage
Maintainer	Build, Test and Release
Release manager	Tagged release lane
Package maintainer	PyPI Trusted Publishing lane
Future agent	Agent Chokepoints

Core Concepts

Concept	Short version	Detail
Trust source	Public JSON plus detached Ed25519 signature decides policy usability.	Policy Feed and Trust Model
Local detection	Build and signed policy evidence are the release truth.	Local Windows Detection
WUA role	Optional read-only explanation for offers/history.	Troubleshooting
Release targeting	25H2 is the existing-device target; 26H1 is excluded for existing devices.	Architecture Insight
Versions	Package/program version is not schema_version or api_version.	v0.3.1 notes
Source diagnostics	Notice/warning/error troubleshooting evidence stays visible; generator error events can block policy publishing, but diagnostics do not override runtime compliance verdicts.	Source Diagnostics

Maintainer Commands

python -m compileall -q win11_release_guard tools tests
python tools/check_project_identity.py
python tools/check_version_consistency.py
python tools/check_github_action_versions.py
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -q
python tools/scan_for_secret_material.py README.md CHANGELOG.md AGENTS.md docs wiki win11_release_guard tests tools pyproject.toml .github
python -m win11_release_guard --check-policy-source
python -m win11_release_guard --check-public-pages
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

Deployment-affecting changes require the live Pages gate before handover. Use the full gate in AGENTS.md and Build, Test and Release when changing workflows, the policy generator, signing, Pages, manifest/API aliases, source URLs, or public-check CLI behavior.

Safety And Trust Model

• Runtime clients fetch public JSON plus .sig. Runtime clients do not authenticate to GitHub and do not need GitHub tokens, private repository access, or a paid signing certificate.
• The private policy signing key lives only in the GitHub Actions secret WIN11_RELEASE_GUARD_POLICY_SIGNING_KEY_B64; public verification keys are committed.
• The production generator uses public Microsoft Release Health and Atom sources only; it does not use token-authenticated Microsoft APIs.
• Source Diagnostics issue sync runs only in GitHub Actions with the built-in github.token / GITHUB_TOKEN and minimal issues: write; no PAT or extra repository secret is required.
• PyPI publishing uses Trusted Publishing / GitHub OIDC in .github/workflows/pypi-publish.yml; no PyPI API token is required.
• GitHub scheduled workflows are best-effort automation, not guaranteed cron. Badge status is a useful signal, not an operational proof.
• 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.

Deep dive: policy signing, security automation, Tagged release lane.

Documentation Map

Need	Link
Pages Wiki home	https://avnsx.github.io/win11_release_guard/wiki/
Pages changelog	https://avnsx.github.io/win11_release_guard/wiki/changelog/
GitHub internal Wiki (Markdown mirror)	https://github.com/Avnsx/win11_release_guard/wiki
Full architecture	Architecture
Maintainer guide	docs/maintainer-guide.md
Release notes	CHANGELOG.md and docs/releases/v0.3.1.md
Safe source archives	Safe Exports and Clean Archives
FAQ	FAQ

The generated Pages Wiki is the primary public, indexed documentation surface. The GitHub internal Wiki remains a Markdown-compatible mirror for GitHub-native browsing. The repository wiki/ folder is source for both. .github/workflows/publish-policy.yml renders it into GitHub Pages. .github/workflows/sync-wiki.yml can mirror the same wiki/*.md source Markdown to the GitHub internal Wiki with the built-in Actions token, or produce a dry-run artifact for manual sync fallback.

CHANGELOG.md remains the manually maintained changelog source of truth. Newer entries are added at the top; older version sections remain visible in the generated Pages changelog.

Contribution, Support, License

• Issues: https://github.com/Avnsx/win11_release_guard/issues
• Releases: https://github.com/Avnsx/win11_release_guard/releases
• Changelog: CHANGELOG.md
• License: GPL-3.0-only, see LICENSE.txt

Do not commit GitHub tokens, private signing keys, generated site/, generated dist/, .tmp/, dependency-freshness.json, package metadata folders, pycache, raw worktree archives, or private key scratch files.

This project is independent open-source software and is not affiliated with Microsoft.