Summary

Org rulesets must require the exact GitHub check names workflows report. For
reusable-required-check (and any job-level uses: reusable), that is
{caller_job_id} / {job-name} — not the inner job-name alone. checks-py-lintro
was still on legacy unprefixed names (🧪 Test Suite & Coverage), which left PR
gates stuck as Expected while Actions showed green prefixed checks
(test-suite-coverage / 🧪 Test Suite & Coverage).

We fixed checks-py-lintro live on the org. This issue tracks making that contract
durable in lgtm-ci without committing per-repo ruleset JSON snapshots.

Problem

• docs/workflow-contract.md still framed inline runs-on gates as the legacy path;
  the preferred path is update org rulesets to prefixed paths and keep
  reusable-required-check.
• No repo tooling documents which ruleset applies to which consumer repo or how to
  safely update required contexts.
• A prior spike added org/rulesets/*.json — we do not want committed JSON
  per ruleset/repo (drift, duplication, bypasses GitHub as source of truth).

Proposed Solution

1. Documentation (source of truth for names, not full ruleset payloads)

Extend docs/workflow-contract.md and docs/reusable-workflows.md:

• Rulesets require {caller_job_id} / {job-name} for uses: gates; inline jobs use
  name: only (e.g. 🔐 Security Audit).

• Add a markdown registry (not JSON) of org rulesets, e.g.
  docs/org-rulesets.md:

  Ruleset	GitHub id	Repos	Required contexts (examples)
  checks-py-lintro	16132640	py-lintro	test-suite-coverage / 🧪 Test Suite & Coverage, …

  Link each row to the standard caller job ids consumers must use.

2. Shell tooling (operational, no committed payloads)

Under scripts/ci/org/:

• export-ruleset.sh — fetch live ruleset via gh api, print or write to
  stdout / temp file (optional -o for local edits; never checked in).
• sync-ruleset.sh — apply changes from a local file path argument or stdin
  (operator workflow: export → edit → sync). Do not ship default JSON in the repo.
• list-rulesets.sh (optional) — table of ruleset id + name + repos for discovery.

Scripts document required env (LGTM_ORG=lgtm-hq) and org-admin gh auth.

3. Explicit non-goals

• No org/rulesets/*.json (or similar) committed for any project.
• No change to reusable-required-check.yml behavior.
• No mass ruleset migration in this issue — only contract + tooling; follow-up issues
  per repo/ruleset as needed (checks-turbo-themes, etc.).

Implementation Notes

• Reference consumer pattern already used on checks-rustume (prefixed paths).
• checks-py-lintro live contexts after fix:
  • test-suite-coverage / 🧪 Test Suite & Coverage
  • lintro-code-quality / 🛠️ Lintro Code Quality
  • 🔐 Security Audit
• BATS smoke tests: dry-run / jq validation on fixture snippets, not live org API.

Benefits

• Consumers know which check name rulesets expect before merging workflow changes.
• Org updates are repeatable without JSON drift in git.
• Avoids repeat of py-lintro #971 “green Actions, pending ruleset” confusion.

References

• py-lintro PR #971 — lgtm-ci v0.32 adoption
• reusable-required-check.yml (feat(workflows): add reusable-required-check for org ruleset gates (#168 §4) #264 / workflow-contract Org ruleset section)
• Parent: feat(workflows): standardize reusable workflows as drop-in CI for all lgtm-hq repos #168 (standardize reusables across lgtm-hq repos)