[AAASM-5048] ✨ (ci): Add modules.json ref-drift CI gate

[Chisanan232]

Stacked on / depends on #132 (AAASM-5047). This gate only passes because #132 corrected the stale core ref from master to main. Merge #132 first. GitHub shows this diff against main; the branch is cut from #132's branch, so the modules.json fix will disappear from this diff once #132 merges.

What

Adds a dedicated CI workflow .github/workflows/modules-ref-check.yml that, for every entry in modules.json, resolves the referenced repo's live default branch via git ls-remote --symref <url> HEAD and fails the build if the pinned ref doesn't match.

Triggers: pull_request and push to main scoped to modules.json (and the workflow file itself), plus workflow_dispatch. Uses the repo's existing pinned actions/checkout SHA; git and python3 are preinstalled on the runner, so no other actions are needed.

Why

Nothing validated modules.json ref values against reality. This exact failure class — a referenced repo renames its default branch (e.g. master→main), the stale pin then makes git clone -b <ref> fail in aggregate.yml, breaking the Aggregate job on every docs PR and scheduled run — broke the file three times in one week (node-sdk, go-sdk, and core / AAASM-5047). This gate catches the drift at PR time instead of in the aggregation job.

How verified

• ruby -ryaml -e "YAML.load_file(...)" → parses
• actionlint → clean
• Dry-ran the check logic locally against the (5047-fixed) modules.json: all 5 modules (core, python-sdk, node-sdk, go-sdk, arena) resolve to live default main, exit 0. Against the pre-fix file (core=master, live default=main) it would exit 1 — confirming it genuinely catches the drift.

Jira

https://lightning-dust-mite.atlassian.net/browse/AAASM-5048

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

🔎 Claude Code review — evidence for maintainer

CI state: Green. SonarCloud (pass), Aggregate all module docs (pass), hub component metadata (pass), and the new "Verify modules.json refs match live default branches" gate (pass, 8s) — i.e. the gate this PR adds ran against real remotes in CI and passed.

Scope vs ticket (AAASM-5048): Exactly as scoped. Adds one file, .github/workflows/modules-ref-check.yml (+98 lines). Triggers on pull_request/push to main scoped to modules.json (+ the workflow file) and workflow_dispatch. For each entry it resolves the repo's live default branch via git ls-remote --symref and fails on drift. Reuses the repo's existing pinned actions/checkout SHA; git/python3 are runner built-ins so no new actions are introduced.

Stacking: Depends on #132 (AAASM-5047). This branch is cut from #132's branch so the gate sees the corrected core ref and passes its own CI — merge #132 first. Local dry-run confirmed the gate exits 1 against the pre-fix modules.json (core=master vs live main) and 0 against the fixed one, so it genuinely catches the drift class.

Side-effects: None beyond intended. No product/docs content changed; the workflow is path-filtered to modules.json so it won't run on unrelated PRs. No untrusted GitHub-event input is used in any run: step (inputs come only from the tracked modules.json).

Two-party review: evidence only. Not an approval; not self-merged.

[Chisanan232]

✅ Claude Code review — READY (maintainer evidence)

1. CI: 4p/0f, SonarCloud PASS; the new gate itself ran green (8s).
2. Sonar/CodeCov: no issues.
3. Scope (AAASM-5048): new .github/workflows/modules-ref-check.yml validates each modules.json ref against the live default branch via git ls-remote --symref, fails on drift. Dry-run confirmed: exit 0 on fixed file, exit 1 on pre-fix file — genuinely catches the class. Complete.
4. Side-effects: none — additive workflow, path-filtered, pinned checkout SHA, no untrusted event input in run:.
5. FE: none.

Verdict: scope-complete, MERGEABLE. Stacked on #132 — merge #132 first. Evidence only — not an approval, not self-merged.