Summary
scripts/check_limitations_sync.py --check-states verifies that every issue cited in a limitation table (KNOWN_ISSUES.md, SKILL.md, spec chapters) is still open, via the GitHub API. Today that flag only runs when someone remembers to run it manually — the pre-commit/CI invocation checks table cross-file sync but not issue states.
The 2026-07-02 documentation sweep found three KNOWN_ISSUES.md Limitations rows citing closed issues (#237, #592, #645) — drift that accumulated silently across several releases because nothing runs the state check automatically.
Proposal
Add a scheduled GitHub Actions workflow (weekly cron is enough) that runs:
python scripts/check_limitations_sync.py --check-states
and fails loudly when a limitation row cites a closed issue. Failure output should name the file, line, and closed issue so the fix is mechanical. It should not gate PRs (the API call needs network + token and closed-issue drift is not the PR author's fault) — a scheduled job with a visible red X on the Actions tab is the right pressure.
Notes
GITHUB_TOKEN provided to Actions is sufficient for issue-state reads on a public repo.- Rate limits are a non-issue at weekly cadence (~40 cited issues per run).
Summary
scripts/check_limitations_sync.py --check-statesverifies that every issue cited in a limitation table (KNOWN_ISSUES.md, SKILL.md, spec chapters) is still open, via the GitHub API. Today that flag only runs when someone remembers to run it manually — the pre-commit/CI invocation checks table cross-file sync but not issue states.The 2026-07-02 documentation sweep found three KNOWN_ISSUES.md Limitations rows citing closed issues (#237, #592, #645) — drift that accumulated silently across several releases because nothing runs the state check automatically.
Proposal
Add a scheduled GitHub Actions workflow (weekly cron is enough) that runs:
and fails loudly when a limitation row cites a closed issue. Failure output should name the file, line, and closed issue so the fix is mechanical. It should not gate PRs (the API call needs network + token and closed-issue drift is not the PR author's fault) — a scheduled job with a visible red X on the Actions tab is the right pressure.
Notes
GITHUB_TOKENprovided to Actions is sufficient for issue-state reads on a public repo.