---
name: ci-traceability-gate
description: "How spt-core CI's traceability job installs traceable-reqs (PAT secret + BigscreenVR release), and the v0.1.0-stale gotcha."
metadata: 
  node_type: memory
  type: reference
  originSessionId: 884ebd12-8e23-4eea-819b-bf8aeaa031f5
---

spt-core CI (`.github/workflows/ci.yml`) has two jobs: **test** (ubuntu+windows matrix: build/test/clippy) and **traceability** (downloads the `traceable-reqs` binary, runs `./traceable-reqs check --json`, hard gate).

**Install seam (the part that broke):** the traceability job does `gh release download --repo BigscreenVR/traceable-reqs --pattern '*linux-x86_64'` (no version pin → grabs the **latest** release). `BigscreenVR/traceable-reqs` is **PRIVATE + cross-org**, so the default repo-scoped `GITHUB_TOKEN` can't read it ("release not found"). Fixed 2026-06-02 by using `GH_TOKEN: ${{ secrets.TRACEABLE_REQS_TOKEN }}` — a PAT (in SaberMage's account) with read access to that repo, stored as the `TRACEABLE_REQS_TOKEN` repo secret on SaberMage/spt-core.

**The v0.1.0-stale gotcha:** the released `v0.1.0` binary (2026-05-04) predates the `[<stage>->...]` *illustration-escape* feature, so it flagged the angle-bracketed example tokens in `docs/TRACEABILITY.md` as `must`-severity `parse_error` findings → exit 1. It passed locally only because the dev's locally-built binary was newer (and Windows CRLF masking). Fixed by cutting **v0.1.1** from BigscreenVR/traceable-reqs `main` (HEAD had the fix; bumped `rust/Cargo.toml` 0.1.0→0.1.1, pushed tag → the repo's `release.yml` builds linux/windows/macos and publishes). CI auto-picked it up (latest-release download). **Lesson:** the project's tag-doc convention can outrun the pinned binary — keep the traceable-reqs release ahead of `TRACEABILITY.md`/`CLAUDE.md` convention changes.

I (this account, SaberMage) have **admin** on `BigscreenVR/traceable-reqs` — can cut releases. The Rust source is in its `rust/` subdir. See [[cross-machine-test-rig]] for the gravity-linux build host.