[AAASM-4719] ♻️ (examples): Own every SDK-version surface + orphan-literal audit

[Chisanan232]

What changed

Makes scripts/generate_example_metadata.py the complete single source of truth for SDK-version literals and adds a coverage invariant so a new stale surface fails CI. Four capabilities, stdlib-only and idempotent:

1. Bullet-form Prerequisites ownership (closes AAASM-4717). The generator owned only the table form of the ## Prerequisites SDK row; go/README.md states it as a Markdown bullet, which had drifted to v0.0.1-rc.3 while the table rows advanced to rc.5. A list-marker-anchored bullet matcher (wired into process_prereq_rows alongside the table matcher) now aligns it — go/README.md:33 is rewritten to v0.0.1-rc.5. It cannot collide with the table row (leading |) or the generated sdk-install block, and a trailing note is preserved.
2. Dockerfile pin ownership. The agent-assembly==<ver> pip pin in scenarios/*/Dockerfile / scenarios/*/*/Dockerfile (the live-core-enforcement python-agent image) is now owned via a bounded, non-recursive walker and a lookbehind-anchored rewriter. No content diff today (already rc5) — this closes the ownership gap that forced a hand-bump in AAASM-4702.
3. --check orphan-version-literal audit. A new --check mode (default stays: rewrite) scans a bounded set of human-authored surfaces — manifest pins (pyproject.toml/package.json/go.mod/Dockerfile under python/ node/ go/ scenarios/) and SDK-version prose in READMEs + docs/*.md — and exits non-zero naming each file:line that drifts from the SoT. It never scans lockfiles or vendored trees, matches the main-SDK identifiers precisely (no false-match on @agent-assembly/runtime-* or the github.com/ai-agent-assembly/... org path), and honors an inline sdk-version-exempt marker for legitimate historical/provenance text.
4. CI wiring. .github/workflows/example-metadata-check.yml gains scenarios/**/go.mod and scenarios/**/Dockerfile trigger paths, plus steps that run --check and the new unit tests. permissions: contents: read unchanged; other lanes untouched.

Related ticket

Closes AAASM-4719
Closes AAASM-4717

• https://lightning-dust-mite.atlassian.net/browse/AAASM-4719
• https://lightning-dust-mite.atlassian.net/browse/AAASM-4717

How to verify

Run from the repo root (all stdlib, no installs):

python scripts/generate_example_metadata.py     # rewrites go/README.md:33 rc.3 -> rc.5
python scripts/generate_example_metadata.py      # re-run: "No changes"
git diff --exit-code                             # clean (idempotent)
python scripts/generate_example_metadata.py --check   # exit 0 on a clean tree
python -m unittest scripts.test_generate_example_metadata   # 13 tests, OK

Negative check: edit any pin to a wrong version and --check exits non-zero naming its file:line; revert restores exit 0.

New tests (scripts/test_generate_example_metadata.py, 13 cases) cover the bullet rewrite (trailing-note preservation + no-collision with the table/generated block), the Dockerfile rewrite (identifier precision + two-level walk bound), and the audit (in-sync pass, stale manifest/Dockerfile/prose detection, exemption marker, subpackage/org-path non-false-match).

Checklist

• PR title follows [AAASM-XXXX] <GitEmoji> (<scope>): <summary>
• No secrets, API keys, or .env files committed
• Example sub-projects include their own README.md with prerequisites and run instructions
• SDK/runtime version dependencies are documented or pinned

🤖 Generated with Claude Code

https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6

[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]

Review (AAASM-4719, closes AAASM-4717) — READY.

• CI: all required checks green (14) and the SonarCloud quality gate passed; the follow-up commit re-triggers the lanes.
• Scope: covers every acceptance criterion — bullet-form Prerequisites ownership (reconciles the go top-level README bullet), scenario Dockerfile SDK-pin ownership, the orphan-version-literal audit mode (precise main-SDK identifiers, runtime sub-packages and the go org path excluded, lockfiles never scanned, inline exempt marker for provenance), widened drift-check workflow paths plus the audit and tests wired in, and 13 stdlib unittest cases.
• Side effects: additive and safe. The default generate behavior is unchanged; the audit is a new opt-in mode. The bullet matcher is list-marker anchored so it cannot touch the table row or the generated block; the generator remains stdlib-only and idempotent (clean re-run, no drift). No existing function or business logic is altered.
• Front end: none touched — this is repo tooling, so Playwright validation is not applicable.
• Review feedback: one bot nit (an unused module constant) was valid; fixed in cdbf0fe with no functionality change (idempotency, audit, and all 13 tests still pass) and replied on the thread.

Base master; awaiting Pioneer review — not merged.

— Reviewed by Claude Code