Add a periodic non-blocking CI dry-run of the spec bump (surface new upstream domains early)

[esraagamal6]

Motivation

A spec-pin bump is not always mechanical: it can silently pull in a whole new upstream domain that the generator doesn't yet model. We hit this bumping camunda-oca to latest main — upstream added the agent-instance domain, which surfaced a generator bug plus a new entity type with no matching ontology shape (see #386). Today that only becomes visible when someone manually attempts the bump.

Goal: turn "surprise at bump time" into an early, recurring heads-up — without ever blocking PR CI.

Proposal

A scheduled GitHub Actions workflow in this repo (api-test-generator) that dry-runs the bump against upstream main:

1. On a cron (e.g. weekly) and via manual workflow_dispatch.
2. For each config, fetch the spec at the upstream default branch instead of the pinned SHA:
   • camunda-oca → camunda/camunda (public; SPEC_REF=<main-sha> npm run fetch-spec:ref).
   • camunda-hub → camunda/camunda-hub (private; bundle via --spec-dir/--repo-url — needs read access, see Open questions).
3. Run npm run testsuite:generate + npm run generate:request-validation + the regression invariants against the fetched-latest spec.
4. On drift/failure, open (or update) a single tracking issue with the diff/summary. Non-blocking: runs only on schedule/dispatch, never on pull_request, so it can't fail anyone's PR.

This is exactly the manual bump we just did (#386), automated as a signal-only check.

Why here and not upstream

The check is "does the latest upstream spec still flow through our generator" — a property of the consumer (our pipeline, ontology ABox, invariants), which camunda/camunda knows nothing about. Putting it in upstream CI would be backwards coupling; their spec authors shouldn't be gated or pinged by our downstream tooling. The generator owns its own compatibility signal.

Open questions

• Hub auth: camunda/camunda-hub is private and not fetched in CI today. The dry-run for hub needs a token/GitHub App with read access (or scope the job to OCA only initially). fetch-spec also doesn't yet wire each config's spec.source (repo-url + entry-file) — see the manual --spec-dir workaround used for Bump camunda-oca spec to latest: model the agent-instance domain (new ABox entity shape + planner chains) #386.
• Reporting: open/refresh one rolling tracking issue vs. a new issue per drift.
• Cadence: weekly vs. on upstream release tags.

Acceptance

• Scheduled + dispatchable workflow that fetches latest-main spec per config and runs generate + invariants.
• Never triggers on pull_request (no PR-blocking).
• Emits an actionable signal (issue/summary) on drift, no-op when clean.
• At minimum covers camunda-oca; document the hub-auth prerequisite (or include hub if a token is available).