ci(codeql): add pre-merge schema-validation pin for .github/codeql/config.yml

[cagataycali]

Problem

.github/codeql/config.yml ships a query-filters: [{exclude: {id: py/unsafe-cyclic-import}}] block whose schema correctness is currently validated only out-of-band: the next CodeQL run on main either auto-closes the targeted alerts (#85, #86, #87, #253, #254, #255) or it doesn't. A typo at the schema level -- excludes: for exclude:, id: becoming a list, or the rule id misspelled -- silently no-ops the suppression with no signal at PR time.

The regression contract added in #216 (tests/simulation/test_no_cyclic_imports.py + the existing test_no_import_cycle.py) pins runtime safety, not CodeQL behaviour. A schema-level typo in config.yml would not trip either pin -- it only manifests as alerts re-appearing in the Security tab on the next scheduled scan.

This is the same shape as the dependabot.yml wrong-path bug (#235): a config file that looks right, parses as YAML, but is silently ignored by the consumer. PR #216 R5 review surfaced this concern explicitly.

Proposed fix

Add a small unit test (tests/test_codeql_config_schema.py or similar) that:

1. Loads .github/codeql/config.yml via yaml.safe_load.
2. Asserts the query-filters block matches the expected shape:

   import yaml
   from pathlib import Path
   
   def test_codeql_config_query_filter_shape():
       config = yaml.safe_load(Path('.github/codeql/config.yml').read_text())
       filters = config.get('query-filters', [])
       assert len(filters) >= 1, 'config.yml: query-filters block missing'
       exclude = filters[0].get('exclude')
       assert exclude is not None, "config.yml: first query-filter must be an 'exclude' (not 'excludes' or another key)"
       assert exclude.get('id') == 'py/unsafe-cyclic-import', (
           f"config.yml: exclude.id must be 'py/unsafe-cyclic-import', got {exclude.get('id')!r}"
       )

3. (Optional) Validates the rest of the config's top-level keys against a known allowlist (name, disable-default-queries, queries, paths-ignore, paths, query-filters) so an accidental typo at the top level (querie-filters:) also fails loud.

The test should fail with a diagnostic that points at the config file and names the actual key found, so the failure mode is debuggable without reading the test source.

Acceptance criteria

• Test exists and pins the expected shape (exclude.id == 'py/unsafe-cyclic-import').
• Test fails loudly with diagnostic naming the actual key on each schema mutation:
  • excludes instead of exclude
  • id value misspelled (e.g. py/cyclic-unsafe-import)
  • id becomes a list instead of a string
  • query-filters becomes queries-filter (top-level typo)
• Test runs in the same suite as tests/simulation/test_no_cyclic_imports.py (or wherever the CodeQL pin tests live).
• AGENTS.md compliance: ASCII clean, no emojis in code/diagnostic strings.
• Referenced from .github/codeql/README.md so future readers know the schema is pin-tested.

Why this issue (not bundled into #216)

• security(codeql): suppress py/unsafe-cyclic-import on simulation triple (closes #215) #216 reached its round-budget cap at R5 per AGENTS.md tenet 8. New scope cannot land in security(codeql): suppress py/unsafe-cyclic-import on simulation triple (closes #215) #216 without breaking the round-budget discipline that PR has been holding to.
• The R5 reviewer surfaced this concern specifically as a follow-up: "a unit test that loads this YAML and asserts the exact shape ... catches typos and accidental refactors at PR time, not weeks later" (PR security(codeql): suppress py/unsafe-cyclic-import on simulation triple (closes #215) #216 R5 thread on config.yml:53).
• Single-file scope (one new test file, no production code change) makes this an ideal follow-up PR -- minimal risk, clear acceptance criteria, regression-pin-only.

Context

• Surfaced during PR security(codeql): suppress py/unsafe-cyclic-import on simulation triple (closes #215) #216 R5 review. The R5 review deferred this explicitly to a follow-up since security(codeql): suppress py/unsafe-cyclic-import on simulation triple (closes #215) #216 is config-only and round-capped.
• Companion to ci(codeql): enforce that py/unsafe-cyclic-import suppression stays narrow #229 (CI enforcement that suppression stays narrow): ci(codeql): enforce that py/unsafe-cyclic-import suppression stays narrow #229 catches expansion of the suppression's effective scope; this issue catches typos that silently drop the suppression.
• Companion to ci(dependabot): config file at .github/workflows/dependabot.yml is silently ignored (canonical path is .github/dependabot.yml) #235 (dependabot.yml at wrong path): same failure shape -- config that parses but is silently ignored. A pin test on the schema is the same defensive posture.
• AGENTS.md > Review Learnings (feat: MuJoCo simulation backend - AgentTool with 50+ actions #85) > Pin regression tests for reviewed fixes applies: the suppression's schema correctness is a contract, and contracts deserve pin tests.

---

Filed by autonomous agent. Strands Agents.