boost-skill-cli 1.2.35__tar.gz → 1.2.36__tar.gz

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36}/Makefile

@@ -88,6 +88,7 @@ lint:
 	$(PY) scripts/build_registries.py --check
 	$(PY) scripts/build_roadmap.py --check
 	$(PY) scripts/build_command_reference.py --check
+	$(PY) scripts/build_vex.py --check
 	$(PY) scripts/lock_toolchain.py --check
 	$(PY) scripts/a11y_check.py
 	$(PY) scripts/page_budget.py
@@ -237,6 +238,7 @@ generate:
 	$(PY) scripts/build_registries.py
 	$(PY) scripts/build_roadmap.py
 	$(PY) scripts/build_command_reference.py
+	$(PY) scripts/build_vex.py
 
 # regenerate docs/demo.gif (brew install vhs)
 demo:

{boost_skill_cli-1.2.35/boost_skill_cli.egg-info → boost_skill_cli-1.2.36}/PKG-INFO

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

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.35'
-__version_tuple__ = version_tuple = (1, 2, 35)
+__version__ = version = '1.2.36'
+__version_tuple__ = version_tuple = (1, 2, 36)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36/boost_skill_cli.egg-info}/PKG-INFO

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

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36}/boost_skill_cli.egg-info/SOURCES.txt

@@ -464,6 +464,7 @@ docs/roadmap/items/update-diff-before-apply.md
 docs/roadmap/items/update-refreshed-rules-without-a-gate.md
 docs/roadmap/items/update-refreshes-rules-and-workflows.md
 docs/roadmap/items/update-reinstall-widens-agent-scope.md
+docs/roadmap/items/vex-openvex-feed.md
 docs/roadmap/items/visual-regression-pass-on-the-guide.md
 docs/roadmap/items/widen-the-ruff-rule-surface-b-sim-c4-perf-ruf.md
 docs/roadmap/items/windows-in-the-ci-matrix.md
@@ -476,6 +477,12 @@ docs/roadmap/items/zip-strict-audit.md
 docs/roadmap/items/zizmor-ignores-drift-and-make-lint-never-ran-it.md
 docs/roadmap/items/zizmor-pin-is-a-yanked-release.md
 docs/superpowers/specs/2026-08-16-catalogue-content-identity-design.md
+docs/vex/meta.md
+docs/vex/openvex.json
+docs/vex/statements/gitleaks-secretscan-test-fixtures.md
+docs/vex/statements/quality-trust-fingerprint-not-sensitive.md
+docs/vex/statements/zizmor-adhoc-packages-lint-runners.md
+docs/vex/statements/zizmor-dangerous-triggers-workflow-run.md
 evals/README.md
 evals/__init__.py
 evals/baseline.json
@@ -508,6 +515,7 @@ scripts/build_demo_index.py
 scripts/build_registries.py
 scripts/build_roadmap.py
 scripts/build_scale_corpus.py
+scripts/build_vex.py
 scripts/check_anchors.py
 scripts/check_branch_current.py
 scripts/check_dco.py
@@ -770,6 +778,7 @@ tests/unit/test_typosquat.py
 tests/unit/test_updatediff.py
 tests/unit/test_util.py
 tests/unit/test_version.py
+tests/unit/test_vex.py
 tests/unit/test_visual_harness_flags.py
 tests/unit/test_workflow_concurrency.py
 tests/unit/test_workflow_concurrency_groups.py

boost_skill_cli-1.2.36/docs/roadmap/items/vex-openvex-feed.md

@@ -0,0 +1,39 @@
+---
+id: vex-openvex-feed
+board: code
+section: health
+status: shipped
+category: Security · Posture
+complexity: S
+impact: Low
+wow: 2
+note: OSPS-VM-04.02 — 4 statements, zero fabricated CVEs
+order: 45
+owner: loop/vex
+pr:
+title: A machine-readable VEX feed, sourced from findings that already existed
+---
+<code>OSPS-VM-04.02</code> — a Level 3 Baseline criterion <a
+href="roadmap.html#osps-baseline-levels">the audit</a> hadn't reached — asks for a VEX
+document accounting for vulnerabilities that don't affect the project, with the
+non-exploitability reasoning attached. boost already had that reasoning; it just wasn't in a
+form a consumer could ingest. CodeQL dismissals carry a <code>#
+codeql[rule-id]</code> comment, <code>.gitleaks.toml</code> allowlists boost's own synthetic
+secret-scanner fixtures, and <code>.github/zizmor.yml</code> documents six ignores by reason.
+<a href="https://openvex.dev/">OpenVEX</a> 0.2.0 turns those into
+a published document at <code>docs/vex/openvex.json</code>,
+generated by <code>scripts/build_vex.py</code> from one statement file per finding under
+<code>docs/vex/statements/</code> — the same one-file-per-item convention the roadmap boards
+themselves use, wired into <code>make generate</code> and a <code>--check</code> freshness
+gate in CI.
+<b>Four statements, and every one traces to a real, already-merged suppression</b> — not an
+invented CVE. boost has never had one, so nothing here is named <code>CVE-</code> or
+<code>GHSA-</code>; each statement's vulnerability name is the scanner's own rule id instead
+(<code>codeql:py/clear-text-logging-sensitive-data</code>, <code>gitleaks:...</code>,
+<code>zizmor:dangerous-triggers</code>, <code>zizmor:adhoc-packages</code>).
+<b>This satisfies one criterion, not the level.</b> <code>OSPS-QA-07.01</code> — a non-author
+human approval before merge — is the wall Level 3 hits regardless, and this change does not
+move it; <code>docs/openssf-badge.md</code> tracks the passing-badge criteria only and has no
+Baseline rows to flip, so the record lives here and in
+<code>docs/security-design.md</code>
+instead.

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36}/docs/roadmap.html

@@ -133,7 +133,7 @@
       <div class="stat"><b>17</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>7</b><span>Planned</span></div>
-      <div class="stat"><b>279</b><span>Loop finds</span></div>
+      <div class="stat"><b>280</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -5287,6 +5287,42 @@ composed into a blind spot, which is the shape most of these have.</p>
           <span class="m">Gemini warned once per skill per session and no boost surface could see it</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="vex-openvex-feed">
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Security · Posture</span></div>
+        <h3>A machine-readable VEX feed, sourced from findings that already existed</h3>
+        <details class="cardbody"><summary>Write-up</summary>
+        <p><code>OSPS-VM-04.02</code> — a Level 3 Baseline criterion <a
+href="roadmap.html#osps-baseline-levels">the audit</a> hadn't reached — asks for a VEX
+document accounting for vulnerabilities that don't affect the project, with the
+non-exploitability reasoning attached. boost already had that reasoning; it just wasn't in a
+form a consumer could ingest. CodeQL dismissals carry a <code>#
+codeql[rule-id]</code> comment, <code>.gitleaks.toml</code> allowlists boost's own synthetic
+secret-scanner fixtures, and <code>.github/zizmor.yml</code> documents six ignores by reason.
+<a href="https://openvex.dev/">OpenVEX</a> 0.2.0 turns those into
+a published document at <code>docs/vex/openvex.json</code>,
+generated by <code>scripts/build_vex.py</code> from one statement file per finding under
+<code>docs/vex/statements/</code> — the same one-file-per-item convention the roadmap boards
+themselves use, wired into <code>make generate</code> and a <code>--check</code> freshness
+gate in CI.
+<b>Four statements, and every one traces to a real, already-merged suppression</b> — not an
+invented CVE. boost has never had one, so nothing here is named <code>CVE-</code> or
+<code>GHSA-</code>; each statement's vulnerability name is the scanner's own rule id instead
+(<code>codeql:py/clear-text-logging-sensitive-data</code>, <code>gitleaks:...</code>,
+<code>zizmor:dangerous-triggers</code>, <code>zizmor:adhoc-packages</code>).
+<b>This satisfies one criterion, not the level.</b> <code>OSPS-QA-07.01</code> — a non-author
+human approval before merge — is the wall Level 3 hits regardless, and this change does not
+move it; <code>docs/openssf-badge.md</code> tracks the passing-badge criteria only and has no
+Baseline rows to flip, so the record lives here and in
+<code>docs/security-design.md</code>
+instead.</p></details>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m">Impact <b>Low</b></span>
+          <span class="m">Wow <b class="wow">★★</b></span>
+          <span class="m">OSPS-VM-04.02 — 4 statements, zero fabricated CVEs</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36}/docs/security-design.md

@@ -173,6 +173,43 @@ Every one of these gates blocks a merge to `main`.
 | `import-linter` | the layering that keeps `core/` free of CLI concerns |
 | SLSA provenance + PyPI Trusted Publishing | a released artifact traces to the commit and workflow that built it |
 
+## VEX: accounting for findings that don't affect boost
+
+Every tool in the table above finds things it does not fix — a CodeQL query
+firing on a pattern that isn't actually sensitive here, a gitleaks match on a
+string that was never a real credential, a zizmor rule on a trigger that
+carries its own mitigation. Each dismissal already has a written reason living
+next to the code it describes: a `# codeql[rule-id]` suppression comment, a
+`.gitleaks.toml` allowlist entry, an ignore in `.github/zizmor.yml`. None of
+that was a document a consumer could ingest, which is exactly what OSPS
+Baseline's `OSPS-VM-04.02` asks for: *"While active, any vulnerabilities in
+the software components not affecting the project MUST be accounted for in a
+VEX document, augmenting the vulnerability report with non-exploitability
+details."*
+
+[`docs/vex/openvex.json`](vex/openvex.json) is that document — an
+[OpenVEX](https://openvex.dev/) 0.2.0 feed, published at
+<https://jonnyeclectic.github.io/boost/vex/openvex.json>. It is generated by
+`scripts/build_vex.py` from one Markdown file per statement under
+[`docs/vex/statements/`](vex/statements/) — the same one-file-per-item
+convention `docs/roadmap/items/*.md` uses, so two people adding two different
+findings edit two different files rather than one shared JSON blob.
+`make generate` regenerates it; `make lint` and CI both run
+`build_vex.py --check` and fail if the committed document has drifted from
+its source files.
+
+Every statement in it today is sourced from a real, already-dismissed finding
+in this repository, not an invented one — the print-side CodeQL
+`py/clear-text-logging-sensitive-data` finding on `trust add`'s fingerprint
+line, the gitleaks allowlist entry for `tests/unit/test_secretscan.py`'s
+synthetic fixtures, and the two categories of `zizmor` ignores in
+`.github/zizmor.yml`. **boost has never had a CVE**, so the document names no
+CVE or GHSA identifier — each statement's `vulnerability.name` is the
+scanner's own rule id (`codeql:...`, `gitleaks:...`, `zizmor:...`) instead. An
+empty-but-honest VEX document would have been the right call had none of these
+findings existed to describe; naming a vulnerability that was never reported
+would not have been.
+
 ## Security review record
 
 OpenSSF Best Practices `security_review` asks for a review performed within the

{boost_skill_cli-1.2.35 → boost_skill_cli-1.2.36}/docs/verifying-releases.md

@@ -77,6 +77,15 @@ PGP key for boost, they did not come from this project.
 | Git tag | Points at the commit the release was built from | `git verify-tag` is *not* applicable — tags are unsigned; the provenance attestation is the authority |
 | Release notes | Assembled from the merged pull requests in that release | [Releases page](https://github.com/jonnyeclectic/boost/releases) |
 
+## VEX: findings that do not affect boost
+
+The SBOM says what is in a release; a separate, continuously-updated
+[OpenVEX](https://openvex.dev/) document says which known findings against
+those components don't actually affect boost, with the reasoning attached.
+It is not published per release — it is always current at
+[`docs/vex/openvex.json`](vex/openvex.json). See
+[security-design.md](security-design.md#vex-accounting-for-findings-that-dont-affect-boost).
+
 ## Can you rebuild it yourself? Yes — the measurement
 
 A reproducible build lets a third party rebuild the artifact from source and

boost_skill_cli-1.2.36/docs/vex/meta.md

@@ -0,0 +1,12 @@
+---
+id: openvex
+author: "the boost project (https://github.com/jonnyeclectic/boost)"
+version: 1
+timestamp: "2026-08-28T00:00:00Z"
+---
+Document-level identity for `docs/vex/openvex.json`, hand-edited the way a
+changelog is: bump `version` and set `timestamp` to the date of the change
+whenever a statement under `statements/` is added, changed, or removed.
+Neither field is computed — `scripts/build_vex.py` deliberately never reads
+the wall clock, so `--check` can compare byte-for-byte. This body is prose
+for humans editing the file; it is not part of the generated document.

boost_skill_cli-1.2.36/docs/vex/openvex.json

@@ -0,0 +1,61 @@
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "@id": "https://jonnyeclectic.github.io/boost/vex/openvex.json",
+  "author": "the boost project (https://github.com/jonnyeclectic/boost)",
+  "timestamp": "2026-08-28T00:00:00Z",
+  "version": 1,
+  "statements": [
+    {
+      "vulnerability": {
+        "name": "gitleaks:leaked-secret-detection"
+      },
+      "products": [
+        {
+          "@id": "pkg:pypi/boost-skill-cli"
+        }
+      ],
+      "status": "not_affected",
+      "justification": "vulnerable_code_not_present",
+      "impact_statement": "`tests/unit/test_secretscan.py` exists to prove `boost_cli/core/secretscan.py`\nflags private keys and API tokens, so it ships synthetic examples of both by\ndesign — strings shaped exactly like the credentials gitleaks' own ruleset\nlooks for. gitleaks correctly matches the shape; none of the matched strings\nis a real, working credential, was ever live, or grants access to anything.\n`.gitleaks.toml` allowlists only this one file, by exact path, and the\nallowlist's own comment states why: nothing else in the repository is\nexcluded from the scan."
+    },
+    {
+      "vulnerability": {
+        "name": "codeql:py/clear-text-logging-sensitive-data"
+      },
+      "products": [
+        {
+          "@id": "pkg:pypi/boost-skill-cli"
+        }
+      ],
+      "status": "not_affected",
+      "justification": "vulnerable_code_not_present",
+      "impact_statement": "CodeQL's `py/clear-text-logging-sensitive-data` query flags\n`boost trust add`'s success line, which prints the trusted key's name and\nminisign fingerprint, because the argument is user-supplied and `fingerprint`\nreads like a credential name. It is not one: the value is a minisign\n**public** key fingerprint, which is meant to be published, and printing it is\nthe entire point of the command — it is how a user checks by eye that the key\nthey just trusted matches the one the publisher advertises. The class of data\nthe query exists to catch (a secret, token, or password) is not present in\nwhat is logged, so the pattern the rule looks for does not apply here. An\nearlier automated fix that replaced this line with a constant string removed\nthe only verification `trust add` offers; the line was restored, the\nsuppression carries this reasoning inline\n(`# codeql[py/clear-text-logging-sensitive-data]`), and\n`tests/functional/test_tap_signing.py` pins the output so it cannot be quietly\ndropped a second time."
+    },
+    {
+      "vulnerability": {
+        "name": "zizmor:adhoc-packages"
+      },
+      "products": [
+        {
+          "@id": "pkg:pypi/boost-skill-cli"
+        }
+      ],
+      "status": "not_affected",
+      "justification": "inline_mitigations_already_exist",
+      "impact_statement": "zizmor's `adhoc-packages` rule flags installing packages without a lockfile,\nbecause an unpinned install can resolve to a tampered or unexpectedly newer\npackage. Two workflows do this on purpose: `theme-lint.yml` installs\nmajor-pinned linters with `--no-save` into an empty checkout — boost ships no\n`package.json`, so a lockfile would exist solely for this one step — and\n`visual.yml` installs a pinned `puppeteer-core` from\n`tests/visual/package.json`, also `--no-save`. Both run on an ephemeral\nrunner, hold only `contents: read`, and their output gates nothing but\nthemselves — a compromised lint or screenshot tool in either job cannot reach\na secret or influence a later, privileged job."
+    },
+    {
+      "vulnerability": {
+        "name": "zizmor:dangerous-triggers"
+      },
+      "products": [
+        {
+          "@id": "pkg:pypi/boost-skill-cli"
+        }
+      ],
+      "status": "not_affected",
+      "justification": "inline_mitigations_already_exist",
+      "impact_statement": "zizmor's `dangerous-triggers` rule flags `workflow_run`, because the classic\nfailure mode is a privileged run executing pull-request-controlled code. Four\nworkflows use it — `ci-failure-issue.yml`, `publish.yml`, `post-deploy.yml`,\n`sbom.yml` — and each carries the mitigation that makes the pattern safe in\nits specific case, recorded inline in `.github/zizmor.yml`: none of them\nchecks out the triggering run's head SHA (each explicitly checks out `main`,\na release tag, or nothing at all), so no code a fork's pull request could\ninfluence ever runs in the privileged context. `publish.yml`, the one job that\nholds write credentials (PyPI Trusted Publisher OIDC), is additionally scoped\nto `push` events from this repository only — a fork PR opened from a branch\nnamed `main` cannot satisfy that filter. `sbom.yml` is gated on\n`head_repository == this repository` for the same reason. The remaining two\nhold only `contents: read` and no secrets."
+    }
+  ]
+}

boost_skill_cli-1.2.36/docs/vex/statements/gitleaks-secretscan-test-fixtures.md

@@ -0,0 +1,15 @@
+---
+id: gitleaks-secretscan-test-fixtures
+vulnerability: "gitleaks:leaked-secret-detection"
+status: not_affected
+justification: vulnerable_code_not_present
+source: .gitleaks.toml, tests/unit/test_secretscan.py
+---
+`tests/unit/test_secretscan.py` exists to prove `boost_cli/core/secretscan.py`
+flags private keys and API tokens, so it ships synthetic examples of both by
+design — strings shaped exactly like the credentials gitleaks' own ruleset
+looks for. gitleaks correctly matches the shape; none of the matched strings
+is a real, working credential, was ever live, or grants access to anything.
+`.gitleaks.toml` allowlists only this one file, by exact path, and the
+allowlist's own comment states why: nothing else in the repository is
+excluded from the scan.

boost_skill_cli-1.2.36/docs/vex/statements/quality-trust-fingerprint-not-sensitive.md

@@ -0,0 +1,22 @@
+---
+id: quality-trust-fingerprint-not-sensitive
+vulnerability: "codeql:py/clear-text-logging-sensitive-data"
+status: not_affected
+justification: vulnerable_code_not_present
+source: boost_cli/commands/quality.py:1248
+---
+CodeQL's `py/clear-text-logging-sensitive-data` query flags
+`boost trust add`'s success line, which prints the trusted key's name and
+minisign fingerprint, because the argument is user-supplied and `fingerprint`
+reads like a credential name. It is not one: the value is a minisign
+**public** key fingerprint, which is meant to be published, and printing it is
+the entire point of the command — it is how a user checks by eye that the key
+they just trusted matches the one the publisher advertises. The class of data
+the query exists to catch (a secret, token, or password) is not present in
+what is logged, so the pattern the rule looks for does not apply here. An
+earlier automated fix that replaced this line with a constant string removed
+the only verification `trust add` offers; the line was restored, the
+suppression carries this reasoning inline
+(`# codeql[py/clear-text-logging-sensitive-data]`), and
+`tests/functional/test_tap_signing.py` pins the output so it cannot be quietly
+dropped a second time.

boost_skill_cli-1.2.36/docs/vex/statements/zizmor-adhoc-packages-lint-runners.md

@@ -0,0 +1,17 @@
+---
+id: zizmor-adhoc-packages-lint-runners
+vulnerability: "zizmor:adhoc-packages"
+status: not_affected
+justification: inline_mitigations_already_exist
+source: .github/zizmor.yml (theme-lint.yml:48, visual.yml:38)
+---
+zizmor's `adhoc-packages` rule flags installing packages without a lockfile,
+because an unpinned install can resolve to a tampered or unexpectedly newer
+package. Two workflows do this on purpose: `theme-lint.yml` installs
+major-pinned linters with `--no-save` into an empty checkout — boost ships no
+`package.json`, so a lockfile would exist solely for this one step — and
+`visual.yml` installs a pinned `puppeteer-core` from
+`tests/visual/package.json`, also `--no-save`. Both run on an ephemeral
+runner, hold only `contents: read`, and their output gates nothing but
+themselves — a compromised lint or screenshot tool in either job cannot reach
+a secret or influence a later, privileged job.

boost_skill_cli-1.2.36/docs/vex/statements/zizmor-dangerous-triggers-workflow-run.md

@@ -0,0 +1,20 @@
+---
+id: zizmor-dangerous-triggers-workflow-run
+vulnerability: "zizmor:dangerous-triggers"
+status: not_affected
+justification: inline_mitigations_already_exist
+source: .github/zizmor.yml (ci-failure-issue.yml:28, publish.yml:19, post-deploy.yml:21, sbom.yml:29)
+---
+zizmor's `dangerous-triggers` rule flags `workflow_run`, because the classic
+failure mode is a privileged run executing pull-request-controlled code. Four
+workflows use it — `ci-failure-issue.yml`, `publish.yml`, `post-deploy.yml`,
+`sbom.yml` — and each carries the mitigation that makes the pattern safe in
+its specific case, recorded inline in `.github/zizmor.yml`: none of them
+checks out the triggering run's head SHA (each explicitly checks out `main`,
+a release tag, or nothing at all), so no code a fork's pull request could
+influence ever runs in the privileged context. `publish.yml`, the one job that
+holds write credentials (PyPI Trusted Publisher OIDC), is additionally scoped
+to `push` events from this repository only — a fork PR opened from a branch
+named `main` cannot satisfy that filter. `sbom.yml` is gated on
+`head_repository == this repository` for the same reason. The remaining two
+hold only `contents: read` and no secrets.

boost_skill_cli-1.2.36/scripts/build_vex.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+# Copyright the boost contributors.
+# SPDX-License-Identifier: GPL-3.0-only
+"""Render ``docs/vex/openvex.json`` — boost's OpenVEX 0.2.0 feed — from a
+human-edited source of truth.
+
+OSPS Baseline ``OSPS-VM-04.02`` asks for exactly this: "While active, any
+vulnerabilities in the software components not affecting the project MUST be
+accounted for in a VEX document, augmenting the vulnerability report with
+non-exploitability details." boost's scanners (CodeQL, gitleaks, zizmor) each
+already carry that reasoning inline — a ``# codeql[rule-id]`` suppression
+comment, a gitleaks allowlist entry, a ``.github/zizmor.yml`` ignore — but none
+of that is a document a consumer can *ingest*. This script is the bridge.
+
+Source of truth is ``docs/vex/statements/*.md``, one Markdown-with-frontmatter
+file per VEX statement — the same convention ``scripts/build_roadmap.py`` uses
+for ``docs/roadmap/items/*.md``, for the same reason: two loops adding two
+different findings touch two different files and merge cleanly. Document-level
+identity (author, version, timestamp) lives in the single shared
+``docs/vex/meta.md``, edited by hand when a statement is added, changed, or
+removed — bump ``version`` and ``timestamp`` together, the same way a package
+changelog does. Nothing here reads the wall clock: the output is a pure
+function of the committed files, so ``--check`` (and the test suite's
+freshness test) can compare it byte-for-byte.
+
+Statement frontmatter:
+
+    ---
+    id: quality-trust-fingerprint-not-sensitive   # must equal the filename
+    vulnerability: "codeql:py/clear-text-logging-sensitive-data"
+    status: not_affected                          # not_affected|affected|fixed|under_investigation
+    justification: vulnerable_code_not_present     # required when status is not_affected
+    products:                                      # optional; defaults to [DEFAULT_PRODUCT]
+      - pkg:pypi/boost-skill-cli
+    ---
+    Free-text impact statement — why this finding does not affect boost. This
+    becomes the OpenVEX statement's `impact_statement` field.
+
+Run:    python3 scripts/build_vex.py            # regenerate docs/vex/openvex.json
+Verify: python3 scripts/build_vex.py --check    # fail if it has drifted
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+# Reuse the repo's stdlib-only frontmatter parser (no new dependency), the same
+# way scripts/build_roadmap.py does. Importable without an editable install.
+sys.path.insert(0, str(ROOT))
+from boost_cli.core import frontmatter  # noqa: E402
+
+VEX_DIR = ROOT / "docs" / "vex"
+STATEMENTS_DIR = VEX_DIR / "statements"
+META_FILE = VEX_DIR / "meta.md"
+OUTPUT_FILE = VEX_DIR / "openvex.json"
+
+CONTEXT = "https://openvex.dev/ns/v0.2.0"
+# Same canonical Pages URL as Makefile's BOOST_SITE and
+# scripts/post_deploy_smoke.py's DEFAULT_BASE — keep the three in sync.
+SITE_BASE = "https://jonnyeclectic.github.io/boost/"
+DOC_ID = SITE_BASE + "vex/openvex.json"
+DEFAULT_PRODUCT = "pkg:pypi/boost-skill-cli"
+
+VALID_STATUS = ("not_affected", "affected", "fixed", "under_investigation")
+# The five OpenVEX justifications for a `not_affected` statement.
+VALID_JUSTIFICATION = (
+    "component_not_present",
+    "vulnerable_code_not_present",
+    "vulnerable_code_not_in_execute_path",
+    "vulnerable_code_cannot_be_controlled_by_adversary",
+    "inline_mitigations_already_exist",
+)
+
+
+class VexError(Exception):
+    """A statement or the document metadata is malformed."""
+
+
+def load_meta() -> dict:
+    meta, _ = frontmatter.parse(META_FILE.read_text(encoding="utf-8"))
+    for field in ("author", "version", "timestamp"):
+        if not meta.get(field):
+            raise VexError("%s: missing %r" % (META_FILE.name, field))
+    return meta
+
+
+def load_statements() -> list[dict]:
+    """Load and validate every statement, sorted by id for a stable order."""
+    statements = []
+    for path in sorted(STATEMENTS_DIR.glob("*.md")):
+        meta, body = frontmatter.parse(path.read_text(encoding="utf-8"))
+        meta["_file"] = path.name
+        meta["_body"] = body.strip()
+        if not meta.get("id"):
+            raise VexError("%s: missing 'id'" % path.name)
+        if meta["id"] != path.stem:
+            raise VexError(
+                "%s: id %r does not match filename" % (path.name, meta["id"]))
+        if not meta.get("vulnerability"):
+            raise VexError("%s: missing 'vulnerability'" % path.name)
+        status = meta.get("status")
+        if status not in VALID_STATUS:
+            raise VexError("%s: bad status %r" % (path.name, status))
+        justification = meta.get("justification")
+        if status == "not_affected" and justification not in VALID_JUSTIFICATION:
+            raise VexError(
+                "%s: status 'not_affected' requires a valid 'justification' "
+                "(one of %s)" % (path.name, ", ".join(VALID_JUSTIFICATION)))
+        if not meta["_body"]:
+            raise VexError(
+                "%s: empty impact statement — the body is what makes this "
+                "finding reviewable, not just machine-readable" % path.name)
+        statements.append(meta)
+    statements.sort(key=lambda m: str(m["id"]))
+    return statements
+
+
+def render_statement(meta: dict) -> dict:
+    products = meta.get("products") or [DEFAULT_PRODUCT]
+    stmt = {
+        "vulnerability": {"name": meta["vulnerability"]},
+        "products": [{"@id": p} for p in products],
+        "status": meta["status"],
+    }
+    if meta.get("justification"):
+        stmt["justification"] = meta["justification"]
+    stmt["impact_statement"] = meta["_body"]
+    return stmt
+
+
+def build() -> str:
+    meta = load_meta()
+    statements = [render_statement(s) for s in load_statements()]
+    doc = {
+        "@context": CONTEXT,
+        "@id": DOC_ID,
+        "author": meta["author"],
+        "timestamp": meta["timestamp"],
+        "version": int(meta["version"]),
+        "statements": statements,
+    }
+    return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Regenerate docs/vex/openvex.json from docs/vex/statements/*.md.")
+    parser.add_argument(
+        "--check", action="store_true",
+        help="verify the committed document matches a fresh render; exit 1 on drift.")
+    args = parser.parse_args(argv)
+
+    fresh = build()
+    if args.check:
+        committed = OUTPUT_FILE.read_text(encoding="utf-8") if OUTPUT_FILE.exists() else None
+        if committed != fresh:
+            print("ERROR: docs/vex/openvex.json is stale — regenerate with\n"
+                  "    python3 scripts/build_vex.py\n"
+                  "and commit the result (see CONTRIBUTING.md).", file=sys.stderr)
+            print("::error::VEX document is stale — run "
+                  "`python3 scripts/build_vex.py` and commit", file=sys.stderr)
+            return 1
+        print("docs/vex/openvex.json is up to date.")
+        return 0
+
+    OUTPUT_FILE.write_text(fresh, encoding="utf-8")
+    print("wrote %s" % OUTPUT_FILE)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())