From 5656905d41f8d683bde87e71fa4d943057e0094d Mon Sep 17 00:00:00 2001 From: abrichr Date: Mon, 27 Jul 2026 22:35:57 -0400 Subject: [PATCH] docs: stop telling readers that status.json fixes itself MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `validate_platform_manifest.py` compares this manifest against https://openadapt.ai/status.json and reports skew as a warning. Both the docstring and the warning text explained that choice by saying status.json "regenerates on its own cadence in openadapt-web". It does not regenerate. It is a hand-edited file. Nothing derives it from PyPI or from this manifest, and no component release writes back to openadapt-web. On 2026-07-28 it advertised openadapt-flow 1.24.0 and openadapt 1.10.0 while PyPI had 1.25.1 and 1.10.1, and this validator had been quietly warning about exactly that. The severity is unchanged and deliberately so: status.json lives in another repository, and a release here must not be blocked by an edit nobody in this repo can make. What changes is that the message no longer tells the reader the problem is transient. A warning that explains itself away is a warning nobody acts on, and that is how the skew survived. Both texts now say what is actually true, name openadapt-web's own daily guard (scripts/check_published_version_claims.mjs) as after-the-fact detection rather than prevention, and name the two files a person has to edit. No behaviour change. `python scripts/validate_platform_manifest.py --strict-status` passes with 0 warnings against the current live status.json. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM --- docs/platform-manifest.md | 14 ++++++++++++-- scripts/validate_platform_manifest.py | 20 ++++++++++++++++---- 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/platform-manifest.md b/docs/platform-manifest.md index 3b1125171..1a3f07247 100644 --- a/docs/platform-manifest.md +++ b/docs/platform-manifest.md @@ -116,8 +116,18 @@ Validated today: An unreachable PyPI warns rather than fails — it is not evidence of drift — unless `--require-network` is passed. - Status skew: disagreement with `status.json` versions is a warning by - default (status.json regenerates on its own cadence in `openadapt-web`); - `--strict-status` escalates it to a failure. + default, because that file lives in another repository and a release here + must not be blocked by an edit nobody in this repo can make; + `--strict-status` escalates it to a failure. The warning is **not** + self-healing: `status.json` is hand-maintained in `openadapt-web` and + nothing generates it from PyPI or from this manifest. On 2026-07-28 it + advertised flow 1.24.0 and launcher 1.10.0 against PyPI's 1.25.1 and 1.10.1. + `openadapt-web` runs a daily guard + (`scripts/check_published_version_claims.mjs`) that fails on exactly this, + but that detects after the fact and still needs a person to open the + corrective pull request. Skew reported here means someone must edit + `public/status.json` and `data/published-version-claims.json` in + `openadapt-web`. Not validated yet (planned): diff --git a/scripts/validate_platform_manifest.py b/scripts/validate_platform_manifest.py index 3f58cf305..4b4c19011 100644 --- a/scripts/validate_platform_manifest.py +++ b/scripts/validate_platform_manifest.py @@ -29,8 +29,18 @@ class of check (for example in an airgapped environment). * Status-document agreement (network): version skew against https://openadapt.ai/status.json is reported as a WARNING by default, - because status.json is regenerated on its own cadence in openadapt-web. - Pass --strict-status to escalate the skew to a failure. + because status.json lives in another repository and this manifest is not its + source of truth. It stays a warning so a release here cannot be blocked by an + edit nobody in this repo can make. Pass --strict-status to escalate the skew + to a failure. + + Do NOT read that warning as self-healing. status.json is HAND-MAINTAINED in + openadapt-web; nothing generates it from PyPI or from this manifest. On + 2026-07-28 it advertised flow 1.24.0 and launcher 1.10.0 while PyPI had + 1.25.1 and 1.10.1. openadapt-web runs its own daily guard + (scripts/check_published_version_claims.mjs) that fails on exactly this, but + that is after-the-fact detection and still needs a person to open the + corrective PR. Skew reported here means someone must go and edit that file. What it does NOT validate yet (planned, see docs/platform-manifest.md): @@ -395,8 +405,10 @@ def check_against_status(manifest: dict, report: Report, strict: bool) -> None: emit( f"{role} skew vs {STATUS_URL}: manifest has " f"{component.get('version')!r}, status.json has " - f"{status_version!r} (status.json regenerates on its own " - "cadence in openadapt-web)" + f"{status_version!r} (status.json is hand-maintained in " + "openadapt-web and will not correct itself -- edit " + "public/status.json and data/published-version-claims.json " + "there)" ) lifecycle = (status.get("product_lifecycle") or "").lower() if lifecycle and lifecycle != manifest.get("release_channel"):