feat(ci): registry→trunk catalog sync automation + drift alarm

[andrewjong]

Closes the registration footgun that bit mighty (2026-08-29): module registration is two merges — the registry PR (airstack-modules-index) and the trunk fixture/catalog sync — and because the docs deploy regenerates the published catalog from the live registry, a missed half silently dropped the module from the site while git looked correct. Per discussion, we're keeping the registry separate (versioned-docs freshness, gate-free registration PRs, bot-stamped compat matrix) and closing the gap mechanically:

1. Drift alarm (deploy_docs_from_develop.yaml)

New step before catalog regeneration: gen_docs_catalog.py --check against a fresh registry clone with an empty fetched-modules dir (the committed-page variant, so the comparison is apples-to-apples with the fixture-generated pages). On mismatch it emits a warning annotation + job summary and files one docs-catalog-drift issue (idempotent — no duplicates while one is open). It never fails the deploy: the regenerated catalog published downstream is correct either way; git is what lags. Develop deploy only — main/release committed pages intentionally lag develop. Registry unreachable ⇒ step skips (existing failure-isolation posture).

2. Trunk-sync automation (sync-modules-index.yml + scripts/registry_sync.py)

Daily + workflow_dispatch (run it right after merging a registry PR). Mirrors the registry's modules/*.yaml + stacks/*.yaml into tests/meta/fixtures/modules_index/ (deletions included), regenerates the committed docs/modules/ pages, and — only when something changed — bumps the .env VERSION pre-release counter (increment-gate requirement; publish will retag, not rebuild) and inserts a release-notes bullet. Non-empty diff ⇒ commits to bot/sync-modules-index (force-refreshed from develop each run, so a stale VERSION bump self-heals) and opens the PR if one isn't already open.

No cross-repo secrets: the registry is cloned read-only; the PR is opened in-repo with the workflow token. Known limitation: PRs opened by the workflow token don't trigger CI — close/reopen the bot PR to run checks. (Adding a PAT/GitHub-App secret later would lift this and also enable instant registry→trunk triggering instead of daily polling.)

Validation

• registry_sync.py run locally against the live registry: in-sync (no-op), and against a copy with an injected fake entry: fixture + pages regenerated, VERSION 0.20.0-alpha.20 → .21, release-notes bullet inserted under (Unreleased).
• Drift-check command run locally against the live registry: passes (currently in sync).
• Both workflows parse as YAML; tests/meta/test_docs_catalog_contract.py (15 tests, includes the deploy-workflow contract) passes.

Docs

AGENTS.md (registry bullet + CI table row) and the create-module / extract-module skills now describe the automated flow: merge registry PR → dispatch sync-modules-index → merge the bot PR; drift can no longer stay silent.

VERSION 0.20.0-alpha.20 → 0.20.0-alpha.21 + release-notes entry.

🤖 Generated with Claude Code

[github-actions]

Test Metrics — edc4ef221ff456b3d4429f572199afd5ed7fdb1a

This was a unit/build-only run. Simulation regression comparison does not apply.

system.test_build_packages

Pass rates

Test	Pass	Fail	Skip	Rate
test_colcon_build_gcs	1	0	0	100%
test_colcon_build_ms_airsim	1	0	0	100%
test_colcon_build_robot	1	0	0	100%
test_colcon_test_robot	1	0	0	100%

Metrics

Test	Metric	Value
test_colcon_build_robot	duration_s	108.9s
test_colcon_test_robot	duration_s	53.19s
test_colcon_build_gcs	duration_s	149.8s
test_colcon_build_ms_airsim	duration_s	15.18s