boost-skill-cli 1.0.296__tar.gz → 1.0.297__tar.gz

{boost_skill_cli-1.0.296/boost_skill_cli.egg-info → boost_skill_cli-1.0.297}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.296
+Version: 1.0.297
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.297}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.296'
-__version_tuple__ = version_tuple = (1, 0, 296)
+__version__ = version = '1.0.297'
+__version_tuple__ = version_tuple = (1, 0, 297)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.297/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.296
+Version: 1.0.297
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.297}/boost_skill_cli.egg-info/SOURCES.txt

@@ -297,6 +297,7 @@ docs/roadmap/items/sbom-declares-the-wrong-version.md
 docs/roadmap/items/sbom-on-every-release-cyclonedx-syft.md
 docs/roadmap/items/sbom-release-event-never-fires.md
 docs/roadmap/items/scan-and-sync-rules-and-workflows.md
+docs/roadmap/items/scheduled-toolchain-lock-regeneration.md
 docs/roadmap/items/scorecard-findings-triage.md
 docs/roadmap/items/second-type-checker-pyright.md
 docs/roadmap/items/secret-and-pii-scanning-of-installed-skills.md
@@ -352,6 +353,7 @@ requirements/lint-tools.in
 requirements/lint-tools.txt
 requirements/mutation-tools.in
 requirements/mutation-tools.txt
+requirements/platform-pins.lock
 requirements/release-tools.in
 requirements/release-tools.txt
 requirements/test-tools.in
@@ -506,6 +508,7 @@ tests/unit/test_perf_gate.py
 tests/unit/test_pkg_confusions.py
 tests/unit/test_pkg_injection.py
 tests/unit/test_pkg_secrets.py
+tests/unit/test_platform_pins.py
 tests/unit/test_policy.py
 tests/unit/test_post_deploy_smoke.py
 tests/unit/test_projectlock.py

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.297}/docs/roadmap/items/dependabot-regeneration-drops-platform-pins.md

@@ -2,15 +2,15 @@
 id: dependabot-regeneration-drops-platform-pins
 board: code
 section: internals
-status: planned
+status: shipped
 category: Build · Bug
 complexity: M
 impact: High
 wow: 3
 note: every pip bump PR is unmergeable — 2 of 2 observed, both red on the install step
 order: 36
-owner:
-pr:
+owner: loop/dependabot-lock-guard
+pr: 342
 title: Dependabot cannot regenerate the hash-pinned locks
 ---
 <b>Every Dependabot PR that touches <code>requirements/*.txt</code> is unmergeable</b>, and the
@@ -49,6 +49,19 @@ Dependabot bump can be <i>reproduced</i> rather than merged — take the version
 re-resolve that one package universally, and every other pin (markers included) stays as committed.
 Both open bumps were landed that way: <code>hypothesis</code> 6.161.6 to 6.163.0 and
 <code>twine</code> 6.2.0 to 7.0.0, four changed lines across five locks, with
-<code>colorama</code> and <code>pywin32-ctypes</code> intact. What remains is the config half —
-stopping Dependabot raising these at all — which is deliberately still open because its effect is
-only observable on the next scheduled run.
+<code>colorama</code> and <code>pywin32-ctypes</code> intact.
+<b>Shipped:</b> both remaining halves. The <code>/requirements</code> entry now carries
+<code>open-pull-requests-limit: 0</code>, which switches off <i>version</i> updates — the ones that
+regenerate the lock — while <b>security</b> updates ignore the limit and keep firing, so the entry
+still earns its place. The <code>/</code> entry is untouched; narrowing that one is
+[[dependabot-root-pip-entry-duplicates-requirements]].
+And the guard the card asked for exists: <code>requirements/platform-pins.lock</code> records every
+marker-gated pin <b>by name and marker but not version</b>, so a routine bump leaves it untouched
+and only a change in the <i>shape</i> of a resolution moves a line.
+<code>lock_toolchain.py --audit</code> diffs the locks against it and <b>runs first inside
+<code>--check</code></b>, before uv is invoked at all — it reads only committed files, so it also
+runs in the unit suite and on a runner that could not resolve. A lost pin now fails naming the
+package, the group and the marker it lost, and prints the <code>-P</code> command that reproduces
+the bump properly. A <i>lost</i> pin and a <i>new</i> pin are reported differently on purpose: the
+same textual drift, but one is a broken install on a platform CI never resolves on and the other is
+routine — collapsing them into one "stale" message is how this stayed invisible the first time.

boost_skill_cli-1.0.297/docs/roadmap/items/scheduled-toolchain-lock-regeneration.md

@@ -0,0 +1,45 @@
+---
+id: scheduled-toolchain-lock-regeneration
+board: code
+section: internals
+status: planned
+category: Build · Gap
+complexity: M
+impact: Med
+wow: 2
+note: the toolchain lock now has no proactive update path — by choice, but nothing replaces it yet
+order: 36
+owner:
+pr:
+title: The toolchain lock has no proactive update path any more
+---
+<code>#342</code> set <code>open-pull-requests-limit: 0</code> on the <code>/requirements</code>
+Dependabot entry, because Dependabot cannot regenerate a hash-pinned universal lock without dropping
+the pins whose environment markers exclude them on the resolving platform (see
+[[dependabot-regeneration-drops-platform-pins]]). That was the right call — every pip bump it raised
+was unmergeable — but it reverses the reason the entry was added in the first place: <b>a pin with no
+update path is only half the job</b>, and the dev/CI toolchain now has none.
+
+The trade is bounded rather than silent, which is why this is <code>Med</code> and not
+<code>High</code>. Dependabot <b>security</b> updates ignore the limit and still fire;
+<code>pip-audit.yml</code> runs weekly against the resolved closure and <b>blocks</b> on a live CVE
+(Dependabot only ever opened a PR); and <code>osv-scanner.yml</code> covers what a PR introduces. So
+the exposure is not "a vulnerable pin sits there unnoticed" — it is
+<b>stale-but-not-vulnerable tooling</b>, drifting further from upstream every week until something
+forces a bump.
+
+The replacement the card already named: regenerate on a schedule with
+<code>scripts/lock_toolchain.py --upgrade</code> and open the PR from that, so the resolution stays
+universal and every conditional pin survives. Four points worth getting right rather than guessing.
+<b>First</b>, it needs <code>uv</code> and the network — the required gate's <code>--check</code>
+already assumes both on CI, but no scheduled job currently sets them up. <b>Second</b>,
+<code>--upgrade</code> re-resolves all five groups, so a weekly cadence would land large multi-group
+diffs; per-group jobs, or a lower cadence, keep a bump reviewable, and the reason <code>-P</code>
+exists at all is that a bare <code>--upgrade</code> buries one package in unrelated churn.
+<b>Third</b>, a new workflow is not free in this repo: it must be zizmor-clean with every
+<code>uses:</code> pinned to a <i>peeled</i> commit SHA, carry narrow <code>permissions</code>, and
+— if it is ever made a required context — grow a <code>merge_group:</code> trigger, which
+<code>check_required_checks.py</code> enforces. <b>Fourth</b>, nothing needs to guard the output:
+<code>lock_toolchain.py --audit</code> and <code>requirements/platform-pins.lock</code> already fail
+closed on a lost marker-gated pin, so a regeneration job that got it wrong would be caught the same
+way a Dependabot PR now is.

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.297}/docs/roadmap.html

@@ -111,7 +111,7 @@
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>4</b><span>Planned</span></div>
-      <div class="stat"><b>178</b><span>Loop finds</span></div>
+      <div class="stat"><b>179</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -1219,7 +1219,7 @@ lock file silently clobbers it and still reports "created," even though it overw
       </article>
 
       <article class="cap rcard" id="dependabot-regeneration-drops-platform-pins">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Build · Bug</span></div>
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Build · Bug</span></div>
         <h3>Dependabot cannot regenerate the hash-pinned locks</h3>
         <p><b>Every Dependabot PR that touches <code>requirements/*.txt</code> is unmergeable</b>, and the
 failure is not in the bumped package. Dependabot re-resolves the lock on Linux and writes that
@@ -1257,9 +1257,22 @@ Dependabot bump can be <i>reproduced</i> rather than merged — take the version
 re-resolve that one package universally, and every other pin (markers included) stays as committed.
 Both open bumps were landed that way: <code>hypothesis</code> 6.161.6 to 6.163.0 and
 <code>twine</code> 6.2.0 to 7.0.0, four changed lines across five locks, with
-<code>colorama</code> and <code>pywin32-ctypes</code> intact. What remains is the config half —
-stopping Dependabot raising these at all — which is deliberately still open because its effect is
-only observable on the next scheduled run.</p>
+<code>colorama</code> and <code>pywin32-ctypes</code> intact.
+<b>Shipped:</b> both remaining halves. The <code>/requirements</code> entry now carries
+<code>open-pull-requests-limit: 0</code>, which switches off <i>version</i> updates — the ones that
+regenerate the lock — while <b>security</b> updates ignore the limit and keep firing, so the entry
+still earns its place. The <code>/</code> entry is untouched; narrowing that one is
+[[dependabot-root-pip-entry-duplicates-requirements]].
+And the guard the card asked for exists: <code>requirements/platform-pins.lock</code> records every
+marker-gated pin <b>by name and marker but not version</b>, so a routine bump leaves it untouched
+and only a change in the <i>shape</i> of a resolution moves a line.
+<code>lock_toolchain.py --audit</code> diffs the locks against it and <b>runs first inside
+<code>--check</code></b>, before uv is invoked at all — it reads only committed files, so it also
+runs in the unit suite and on a runner that could not resolve. A lost pin now fails naming the
+package, the group and the marker it lost, and prints the <code>-P</code> command that reproduces
+the bump properly. A <i>lost</i> pin and a <i>new</i> pin are reported differently on purpose: the
+same textual drift, but one is a broken install on a platform CI never resolves on and the other is
+routine — collapsing them into one "stale" message is how this stayed invisible the first time.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m hi">Impact <b>High</b></span>
@@ -1284,6 +1297,47 @@ validator that rejects values below 1; reuse it here.</p>
         </div>
       </article>
 
+      <article class="cap rcard" id="scheduled-toolchain-lock-regeneration">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Build · Gap</span></div>
+        <h3>The toolchain lock has no proactive update path any more</h3>
+        <p><code>#342</code> set <code>open-pull-requests-limit: 0</code> on the <code>/requirements</code>
+Dependabot entry, because Dependabot cannot regenerate a hash-pinned universal lock without dropping
+the pins whose environment markers exclude them on the resolving platform (see
+[[dependabot-regeneration-drops-platform-pins]]). That was the right call — every pip bump it raised
+was unmergeable — but it reverses the reason the entry was added in the first place: <b>a pin with no
+update path is only half the job</b>, and the dev/CI toolchain now has none.
+
+The trade is bounded rather than silent, which is why this is <code>Med</code> and not
+<code>High</code>. Dependabot <b>security</b> updates ignore the limit and still fire;
+<code>pip-audit.yml</code> runs weekly against the resolved closure and <b>blocks</b> on a live CVE
+(Dependabot only ever opened a PR); and <code>osv-scanner.yml</code> covers what a PR introduces. So
+the exposure is not "a vulnerable pin sits there unnoticed" — it is
+<b>stale-but-not-vulnerable tooling</b>, drifting further from upstream every week until something
+forces a bump.
+
+The replacement the card already named: regenerate on a schedule with
+<code>scripts/lock_toolchain.py --upgrade</code> and open the PR from that, so the resolution stays
+universal and every conditional pin survives. Four points worth getting right rather than guessing.
+<b>First</b>, it needs <code>uv</code> and the network — the required gate's <code>--check</code>
+already assumes both on CI, but no scheduled job currently sets them up. <b>Second</b>,
+<code>--upgrade</code> re-resolves all five groups, so a weekly cadence would land large multi-group
+diffs; per-group jobs, or a lower cadence, keep a bump reviewable, and the reason <code>-P</code>
+exists at all is that a bare <code>--upgrade</code> buries one package in unrelated churn.
+<b>Third</b>, a new workflow is not free in this repo: it must be zizmor-clean with every
+<code>uses:</code> pinned to a <i>peeled</i> commit SHA, carry narrow <code>permissions</code>, and
+— if it is ever made a required context — grow a <code>merge_group:</code> trigger, which
+<code>check_required_checks.py</code> enforces. <b>Fourth</b>, nothing needs to guard the output:
+<code>lock_toolchain.py --audit</code> and <code>requirements/platform-pins.lock</code> already fail
+closed on a lost marker-gated pin, so a regeneration job that got it wrong would be caught the same
+way a Dependabot PR now is.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>M</b></span>
+          <span class="m">Impact <b>Med</b></span>
+          <span class="m">Wow <b class="wow">★★</b></span>
+          <span class="m">the toolchain lock now has no proactive update path — by choice, but nothing replaces it yet</span>
+        </div>
+      </article>
+
       <article class="cap rcard" id="crash-listing-branch-untested">
         <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Testing · Bug</span></div>
         <h3><code>boost log --crashes</code> listing branch has no non-empty test</h3>

boost_skill_cli-1.0.297/requirements/platform-pins.lock

@@ -0,0 +1,58 @@
+# GENERATED by scripts/lock_toolchain.py — DO NOT EDIT.
+#
+# NOT a requirements file — there are no versions and no hashes here,
+# and nothing installs it. It records which pins in requirements/*.txt
+# carry an environment marker, so that LOSING one is a red gate.
+#
+# Why: a lock re-resolved on a single platform (which is what
+# Dependabot commits) silently drops every pin whose marker excludes it
+# there. The locks install with --require-hashes on Windows and macOS
+# too, so a dropped pin is an install failure on the platform that
+# needed it — reported against the install step, never naming the
+# package. `lock_toolchain.py --audit` diffs the locks against this
+# file and names it.
+#
+# Versions are deliberately absent: a routine bump must not churn this
+# file, or regenerating it becomes reflexive and it stops being a
+# tripwire. Only a change in the SHAPE of the resolution moves a line.
+
+[lint-tools]
+librt ; platform_python_implementation != 'PyPy'
+
+[test-tools]
+attrs ; python_full_version < '3.10'
+colorama ; sys_platform == 'win32'
+coverage ; python_full_version < '3.10'
+coverage ; python_full_version >= '3.10'
+exceptiongroup ; python_full_version < '3.11'
+hypothesis ; python_full_version < '3.10'
+hypothesis ; python_full_version >= '3.10'
+iniconfig ; python_full_version < '3.10'
+iniconfig ; python_full_version >= '3.10'
+pytest ; python_full_version < '3.10'
+pytest ; python_full_version >= '3.10'
+tomli ; python_full_version <= '3.11'
+typing-extensions ; python_full_version < '3.11'
+
+[mutation-tools]
+colorama ; sys_platform == 'win32'
+pyyaml ; python_full_version != '3.13.*'
+pyyaml-ft ; python_full_version == '3.13.*'
+tomli ; python_full_version <= '3.11'
+
+[coverage-tools]
+colorama ; sys_platform == 'win32'
+
+[release-tools]
+cffi ; platform_machine != 'ppc64le' and platform_machine != 's390x' and platform_python_implementation != 'PyPy' and sys_platform == 'linux'
+colorama ; os_name == 'nt' or sys_platform == 'win32'
+cryptography ; platform_machine != 'ppc64le' and platform_machine != 's390x' and sys_platform == 'linux'
+jaraco-classes ; platform_machine != 'ppc64le' and platform_machine != 's390x'
+jaraco-context ; platform_machine != 'ppc64le' and platform_machine != 's390x'
+jaraco-functools ; platform_machine != 'ppc64le' and platform_machine != 's390x'
+jeepney ; platform_machine != 'ppc64le' and platform_machine != 's390x' and sys_platform == 'linux'
+keyring ; platform_machine != 'ppc64le' and platform_machine != 's390x'
+more-itertools ; platform_machine != 'ppc64le' and platform_machine != 's390x'
+pycparser ; implementation_name != 'PyPy' and platform_machine != 'ppc64le' and platform_machine != 's390x' and platform_python_implementation != 'PyPy' and sys_platform == 'linux'
+pywin32-ctypes ; platform_machine != 'ppc64le' and platform_machine != 's390x' and sys_platform == 'win32'
+secretstorage ; platform_machine != 'ppc64le' and platform_machine != 's390x' and sys_platform == 'linux'

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.297}/scripts/lock_toolchain.py

@@ -3,6 +3,7 @@
 
     python3 scripts/lock_toolchain.py            # regenerate requirements/*.txt
     python3 scripts/lock_toolchain.py --check     # fail (exit 1) on drift
+    python3 scripts/lock_toolchain.py --audit     # fail on a LOST platform pin
     python3 scripts/lock_toolchain.py --upgrade   # re-resolve to newest allowed
     python3 scripts/lock_toolchain.py -P twine    # re-resolve ONE package
 
@@ -31,6 +32,15 @@ The ``--check`` form runs in CI's lint job and in ``make lint``, exactly like
 ``build_registries.py --check`` / ``build_roadmap.py --check``: the generated
 file is committed, and a stale one is a red gate rather than a surprise later.
 
+``--audit`` is the guard for the failure above, and it runs *first* inside
+``--check``. ``requirements/platform-pins.lock`` records every marker-gated pin
+by **name and marker but not version**, so a routine bump leaves it untouched
+and only a change in the *shape* of the resolution moves it. Losing a pin then
+fails here, naming the package and the marker, instead of surfacing three jobs
+later as an install-step error that never mentions it. Unlike ``--check`` the
+audit reads only committed files — no uv, no network — so it also runs in the
+unit suite (``tests/unit/test_platform_pins.py``) and on any runner.
+
 Why hash-pinned requirements rather than ``uv.lock``:
 
 * ``[project].dependencies`` is empty and must stay that way — boost's runtime
@@ -63,6 +73,12 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 REQS = ROOT / "requirements"
 
+# The committed memory of which pins are conditional. Deliberately NOT a .txt:
+# tests/unit/test_toolchain_lock.py requires every requirements/*.txt to have a
+# matching .in declaration, and the suffix also keeps pip and OSV-Scanner from
+# mistaking a hashless manifest for something installable.
+PLATFORM_PINS = REQS / "platform-pins.lock"
+
 # (stem, python-version) for each group. Every group resolves --universal.
 #
 # Universal is not optional for a *committed* lock. Without it uv resolves for
@@ -117,6 +133,134 @@ def _uv() -> str:
     return str(local) if local.exists() else (shutil.which("uv") or "uv")
 
 
+def _manifest_header() -> str:
+    """The stable banner for requirements/platform-pins.lock."""
+    return (
+        "# GENERATED by scripts/lock_toolchain.py — DO NOT EDIT.\n"
+        "#\n"
+        "# NOT a requirements file — there are no versions and no hashes here,\n"
+        "# and nothing installs it. It records which pins in requirements/*.txt\n"
+        "# carry an environment marker, so that LOSING one is a red gate.\n"
+        "#\n"
+        "# Why: a lock re-resolved on a single platform (which is what\n"
+        "# Dependabot commits) silently drops every pin whose marker excludes it\n"
+        "# there. The locks install with --require-hashes on Windows and macOS\n"
+        "# too, so a dropped pin is an install failure on the platform that\n"
+        "# needed it — reported against the install step, never naming the\n"
+        "# package. `lock_toolchain.py --audit` diffs the locks against this\n"
+        "# file and names it.\n"
+        "#\n"
+        "# Versions are deliberately absent: a routine bump must not churn this\n"
+        "# file, or regenerating it becomes reflexive and it stops being a\n"
+        "# tripwire. Only a change in the SHAPE of the resolution moves a line.\n"
+    )
+
+
+def marker_pins(text: str) -> tuple[tuple[str, str], ...]:
+    """The (name, marker) of every marker-gated pin in one compiled lock.
+
+    Sorted and de-duplicated so the result depends on the resolution, not on the
+    order uv happened to emit — that keeps ``render``/``parse`` exactly
+    reciprocal and stops a cosmetic reshuffle reading as drift.
+
+    Unmarked pins are ignored on purpose: they install everywhere, so losing one
+    is ordinary drift that ``--check`` already catches. This guard is only about
+    the conditional pins, which are invisible to a single-platform resolve.
+    """
+    pins = set()
+    for raw in text.splitlines():
+        # Every uv pin line ends in ` \` before its indented --hash block.
+        line = raw.strip().rstrip("\\").strip()
+        if not line or line.startswith("#") or line.startswith("-"):
+            continue                      # comment, --hash, -r, --index-url
+        head, sep, marker = line.partition(";")
+        if not sep or "==" not in head:
+            continue                      # unmarked, or not a pin at all
+        name = head.split("==")[0].strip()   # keeps any `[extra]`
+        if name:
+            # Collapse whitespace so cosmetic spacing is not a change.
+            pins.add((name, " ".join(marker.split())))
+    return tuple(sorted(pins))
+
+
+def render_platform_pins(locks: "dict[str, str]") -> str:
+    """The manifest text recording the marker-gated pins of `locks`.
+
+    A group with no conditional pins still gets its section header, so the
+    manifest states "none here" rather than staying silent about it.
+    """
+    out = [_manifest_header()]
+    for stem, _python_version in GROUPS:
+        if stem not in locks:
+            continue
+        out.append("\n[%s]\n" % stem)
+        for name, marker in marker_pins(locks[stem]):
+            out.append("%s ; %s\n" % (name, marker))
+    return "".join(out)
+
+
+def parse_platform_pins(text: str) -> "dict[str, tuple[tuple[str, str], ...]]":
+    """`{group: ((name, marker), ...)}` as recorded by a manifest."""
+    out: "dict[str, list[tuple[str, str]]]" = {}
+    stem = None
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("[") and line.endswith("]"):
+            stem = line[1:-1]
+            out.setdefault(stem, [])
+            continue
+        if stem is None:
+            continue
+        name, _sep, marker = line.partition(";")
+        out[stem].append((name.strip(), " ".join(marker.split())))
+    return {k: tuple(v) for k, v in out.items()}
+
+
+def read_locks() -> "dict[str, str]":
+    """The committed text of every group's generated lock."""
+    return {stem: (REQS / ("%s.txt" % stem)).read_text(encoding="utf-8")
+            for stem, _python_version in GROUPS}
+
+
+def audit_platform_pins(locks: "dict[str, str]",
+                        manifest_text: str) -> "list[str]":
+    """Problems found comparing `locks` against the recorded manifest.
+
+    A LOST pin and a NEW pin are reported differently on purpose. They are the
+    same textual drift but opposite in meaning: one is a broken install on a
+    platform CI never resolves on, the other is a routine addition that only
+    needs the manifest regenerating. Collapsing them into one "stale" message is
+    how the original failure stayed invisible.
+    """
+    recorded = parse_platform_pins(manifest_text)
+    problems = []
+    for stem, _python_version in GROUPS:
+        if stem not in locks:
+            continue
+        want = set(recorded.get(stem, ()))
+        have = set(marker_pins(locks[stem]))
+        for name, marker in sorted(want - have):
+            problems.append(
+                "%s: LOST %s ; %s\n"
+                "    The lock no longer carries this marker-gated pin, so a\n"
+                "    --require-hashes install fails on the platform the marker\n"
+                "    selects. This is what a lock re-resolved on one platform\n"
+                "    looks like — do not merge it. Reproduce the bump instead:\n"
+                "        python3 scripts/lock_toolchain.py -P %s"
+                % (stem, name, marker, name))
+        for name, marker in sorted(have - want):
+            problems.append(
+                "%s: NEW %s ; %s\n"
+                "    A marker-gated pin that requirements/platform-pins.lock\n"
+                "    does not record. If this addition is intended, run\n"
+                "        python3 scripts/lock_toolchain.py\n"
+                "    and commit the regenerated manifest."
+                % (stem, name, marker))
+    return problems
+
+
 def compile_group(stem: str, python_version: str, upgrade: bool,
                   packages: Sequence[str] = ()) -> str:
     """Resolve one group and return the file contents we want on disk.
@@ -167,6 +311,9 @@ def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__)
     ap.add_argument("--check", action="store_true",
                     help="exit 1 if any generated file is stale")
+    ap.add_argument("--audit", action="store_true",
+                    help="exit 1 if a lock has lost a marker-gated pin "
+                         "(no uv, no network — runs first inside --check)")
     ap.add_argument("--upgrade", action="store_true",
                     help="re-resolve to the newest versions the .in files allow")
     ap.add_argument("-P", "--upgrade-package", action="append", default=[],
@@ -183,6 +330,30 @@ def main() -> int:
         # --upgrade already re-resolves everything, so naming a package on top
         # of it reads as a narrowing that is not happening.
         raise SystemExit("lock_toolchain: --upgrade and -P are exclusive")
+    if args.audit and (args.upgrade or args.upgrade_package):
+        # The audit reads what is committed; re-resolving in the same breath
+        # would audit a file the caller is in the middle of replacing.
+        raise SystemExit(
+            "lock_toolchain: --audit cannot be combined with --upgrade/-P")
+
+    # Before anything that needs uv or the network. A lost platform pin is the
+    # failure that costs three Windows jobs and never names the package, so it
+    # is reported here even on a runner that could not resolve at all.
+    if args.audit or args.check:
+        problems = audit_platform_pins(
+            read_locks(),
+            PLATFORM_PINS.read_text(encoding="utf-8")
+            if PLATFORM_PINS.exists() else "")
+        if problems:
+            print("platform-pin audit FAILED:\n")
+            for problem in problems:
+                print("  %s\n" % problem)
+            return 1
+        print("platform pins intact.")
+        if args.audit and not args.check:
+            return 0
+        # `--check --audit` asked for both, so fall through to the drift check
+        # rather than letting the cheaper flag silently swallow the other.
 
     stale = []
     for stem, python_version in GROUPS:
@@ -197,6 +368,14 @@ def main() -> int:
         target.write_text(want, encoding="utf-8")
         print("wrote %s" % target.relative_to(ROOT))
 
+    if not args.check:
+        # Recorded from what was just written, so the manifest and the locks
+        # can only ever disagree when something regenerated the locks WITHOUT
+        # going through this script — which is precisely the case to catch.
+        PLATFORM_PINS.write_text(render_platform_pins(read_locks()),
+                                 encoding="utf-8")
+        print("wrote %s" % PLATFORM_PINS.relative_to(ROOT))
+
     if args.check:
         if stale:
             print("toolchain lock is STALE for: %s" % ", ".join(stale))