Metadata-Version: 2.4
Name: win11_release_guard
Version: 0.3.1
Summary: Windows 11 broad-fleet release compliance guard.
Author: Mikail ("Avnsx") C.
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/Avnsx/win11_release_guard
Project-URL: Repository, https://github.com/Avnsx/win11_release_guard
Project-URL: Documentation, https://github.com/Avnsx/win11_release_guard/wiki
Project-URL: Changelog, https://github.com/Avnsx/win11_release_guard/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Avnsx/win11_release_guard/issues
Project-URL: Public Feed, https://avnsx.github.io/win11_release_guard/windows-release-policy.json
Project-URL: Pages Dashboard, https://avnsx.github.io/win11_release_guard/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: cryptography>=41
Provides-Extra: test
Requires-Dist: packaging>=24; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# Windows 11 Release Guard

![Windows 11 Release Guard dashboard preview](assets/images/windows-11-release-guard-hero-dashboard.png)

<p>
  <a href="https://pypi.org/project/win11-release-guard/" aria-label="Download win11_release_guard from PyPI">
    <img src="assets/images/download_from_pypi.png" alt="Download from PyPI" width="96" height="96">
  </a>
</p>

[![PyPI](https://img.shields.io/pypi/v/win11_release_guard?logo=pypi&label=PyPI)](https://pypi.org/project/win11_release_guard/)
[![Python](https://img.shields.io/pypi/pyversions/win11_release_guard?logo=python&label=Python)](https://pypi.org/project/win11_release_guard/)
[![License](https://img.shields.io/pypi/l/win11_release_guard?label=license)](https://github.com/Avnsx/win11_release_guard/blob/main/LICENSE.txt)
[![PyPI downloads](https://img.shields.io/pypi/dm/win11_release_guard?label=PyPI%20downloads)](https://pypi.org/project/win11_release_guard/)
[![GitHub Release](https://img.shields.io/github/v/release/Avnsx/win11_release_guard?label=release)](https://github.com/Avnsx/win11_release_guard/releases)

[![CI](https://github.com/Avnsx/win11_release_guard/actions/workflows/ci.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/ci.yml)
[![Publish policy](https://github.com/Avnsx/win11_release_guard/actions/workflows/publish-policy.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/publish-policy.yml)
[![Publish Python package](https://github.com/Avnsx/win11_release_guard/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/pypi-publish.yml)
[![CodeQL](https://github.com/Avnsx/win11_release_guard/actions/workflows/codeql.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/codeql.yml)
[![Pylint](https://github.com/Avnsx/win11_release_guard/actions/workflows/pylint.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/pylint.yml)
[![Dependency audit](https://github.com/Avnsx/win11_release_guard/actions/workflows/dependency-audit.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/dependency-audit.yml)
[![Dependency freshness](https://github.com/Avnsx/win11_release_guard/actions/workflows/dependency-freshness.yml/badge.svg)](https://github.com/Avnsx/win11_release_guard/actions/workflows/dependency-freshness.yml)

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:

```powershell
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:

```powershell
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:

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

Deep dive: [Quick Start](https://avnsx.github.io/win11_release_guard/wiki/Quick-Start/), [CLI and RMM Usage](https://avnsx.github.io/win11_release_guard/wiki/CLI-and-RMM-Usage/), [Configuration](https://avnsx.github.io/win11_release_guard/wiki/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](https://avnsx.github.io/win11_release_guard/wiki/GitHub-Pages-Dashboard/), [Anti-Static Freshness](https://avnsx.github.io/win11_release_guard/wiki/Anti-Static-Freshness/), [dashboard docs](docs/dashboard-and-pages.md).

## Common User Paths

| You are | Start here |
| --- | --- |
| New user | [Quick Start](https://avnsx.github.io/win11_release_guard/wiki/Quick-Start/) |
| Admin / RMM user | [CLI and RMM Usage](https://avnsx.github.io/win11_release_guard/wiki/CLI-and-RMM-Usage/) |
| Maintainer | [Build, Test and Release](https://avnsx.github.io/win11_release_guard/wiki/Build-Test-and-Release/) |
| Release manager | [Tagged release lane](docs/tagged-release-lane.md) |
| Package maintainer | [PyPI Trusted Publishing lane](docs/tagged-release-lane.md#pypi-trusted-publishing-lane) |
| Future agent | [Agent Chokepoints](https://avnsx.github.io/win11_release_guard/wiki/Agent-Chokepoints/) |

## Core Concepts

| Concept | Short version | Detail |
| --- | --- | --- |
| Trust source | Public JSON plus detached Ed25519 signature decides policy usability. | [Policy Feed and Trust Model](https://avnsx.github.io/win11_release_guard/wiki/Policy-Feed-and-Trust-Model/) |
| Local detection | Build and signed policy evidence are the release truth. | [Local Windows Detection](https://avnsx.github.io/win11_release_guard/wiki/Local-Windows-Detection/) |
| WUA role | Optional read-only explanation for offers/history. | [Troubleshooting](https://avnsx.github.io/win11_release_guard/wiki/Troubleshooting/) |
| Release targeting | 25H2 is the existing-device target; 26H1 is excluded for existing devices. | [Architecture Insight](docs/architecture-insight.md) |
| Versions | Package/program version is not `schema_version` or `api_version`. | [v0.3.1 notes](docs/releases/v0.3.1.md) |
| 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](https://avnsx.github.io/win11_release_guard/wiki/Source-Diagnostics/) |

## Maintainer Commands

```powershell
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](AGENTS.md#deployment-affecting-live-verification-gate) and [Build, Test and Release](https://avnsx.github.io/win11_release_guard/wiki/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](docs/policy-signing.md), [security automation](docs/security-automation.md), [Tagged release lane](docs/tagged-release-lane.md).

## 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](https://avnsx.github.io/win11_release_guard/wiki/Architecture/) |
| Maintainer guide | [docs/maintainer-guide.md](docs/maintainer-guide.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) and [docs/releases/v0.3.1.md](docs/releases/v0.3.1.md) |
| Safe source archives | [Safe Exports and Clean Archives](https://avnsx.github.io/win11_release_guard/wiki/Safe-Exports-and-Clean-Archives/) |
| FAQ | [FAQ](https://avnsx.github.io/win11_release_guard/wiki/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](CHANGELOG.md)
- License: GPL-3.0-only, see [LICENSE.txt](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.
