fix(conformance): write compliance/CACHE_VERSION marker to detect stale storyboard cache

[bokelley]

Closes #1648

Summary

compliance/cache/ is gitignored (populated at sync/publish time), so schema-sync.yml's diff guard was blind to compliance-only spec bumps — new storyboard YAMLs, fixed idempotency_key strings — any spec release that didn't also change TypeScript schemas would leave stale storyboards in the published npm artifact. This caused the silent mismatch the issue describes: --version reports AdCP 3.0.8 while compliance/cache/ still contains 3.0.6 storyboards, producing false-positive and false-negative results in buyer-side storyboard validation.

Root cause is two-part:

1. The diff guard in schema-sync.yml watched only src/lib/types/, src/lib/agents/, and package.json — invisible to compliance-only spec changes.
2. No validation caught the version mismatch before publishing.

The fix avoids removing compliance/cache/ from .gitignore (which would add large YAML bulk to git history). Instead, sync-schemas.ts writes a tiny tracked marker file compliance/CACHE_VERSION (one level above the gitignored compliance/cache/) that CI can diff against.

Changes:

• scripts/sync-schemas.ts: writes compliance/CACHE_VERSION after every tarball sync, using adcp_version from the tarball's index.json. The per-file fallback path (tarball endpoint 404) also writes the marker using the ADCP_VERSION pin — compliance storyboards aren't actually synced on that path, but the marker prevents a hard CI failure.
• .github/workflows/schema-sync.yml: diff guard now includes compliance/CACHE_VERSION via git status --short (detects both new/untracked and modified marker files). Version capture moved before the diff check so PR titles are correct for compliance-only bumps too.
• .github/workflows/ci.yml: post-sync validation step asserts compliance/CACHE_VERSION matches ADCP_VERSION, catching version drift before any PR can merge.

Known limitation: The per-file fallback path writes the marker with the ADCP_VERSION pin rather than the tarball's embedded adcp_version, since no tarball is available. This reflects intent (the pin) rather than actual cached content — the pre-existing console.warn documents that compliance storyboards are not synced on this path. The asymmetry is safe for semver pins but would produce a mismatch if ADCP_VERSION were ever set to "latest" (pre-existing concern, not introduced here).

What tested

• npm run format:check: ✅ passes
• Pre-existing typecheck errors (Cannot find type definition file for 'node', deprecated moduleResolution) verified to exist on main before this branch — not introduced here
• git diff HEAD~2 HEAD: reviewed manually; all imports already present in sync-schemas.ts; path.dirname(COMPLIANCE_CACHE_DIR) resolves to compliance/ (confirmed by reviewers); compliance/ guaranteed by replaceTree's mkdirSync before the marker write

Nits from pre-PR review (not fixed)

• ci.yml lines 39/45: cat FILE | tr -d is useless-use-of-cat; tr -d '[:space:]' < FILE is idiomatic — no correctness impact
• schema-sync.yml line 58: 2>/dev/null suppresses stderr on git status; if git exits non-zero for any reason the compliance bump is silently missed — ci.yml's hard check is the safety net, so no release-safety gap, but the failure mode is invisible
• sync-schemas.ts tarball path (~line 388): a // compliance/ guaranteed by replaceTree above comment would clarify why mkdirSync is absent there but present in the per-file fallback path

Pre-PR review

• code-reviewer (round 1): approved after fixing dead || cat ADCP_VERSION fallback in schema-sync.yml (pipe through tr exits 0 on empty input, silently producing empty string). Fixed in second commit.
• ad-tech-protocol-expert: approved after adding per-file fallback marker write in sync() — the blocker was that syncSchemasPerFile path never wrote the marker, which would have caused ci.yml to hard-fail with "not found". Fixed in second commit.
• code-reviewer (round 2): approved — no blockers; three nits surfaced above.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout 1651 →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_01JACGQ4QjAH319KJNKjCwQy

[bokelley]

Closing — source issue #1648 was a misdiagnose (npx cache pointed at a stale install at a different path), so the hazard this guards against hasn't materialized. The existing ci:schema-check already catches compliance-only spec drift via metadata-comment changes in generated files (validated on today's 3.0.10 bump in #1655 — the entity-hydration / manifest / core.generated headers all flipped and would have failed CI if the sync had been skipped). A tracked marker file would be defense-in-depth on top of that, but it's surface area for the same outcome.

[bokelley]

Acknowledged — makes sense. The ci:schema-check coverage you validated on the 3.0.10 bump in #1655 addresses the underlying concern, so this branch isn't needed.

---

Generated by Claude Code

[bokelley]

Understood — closing the loop here. #1655's ci:schema-check coverage makes this branch redundant; no further action needed.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01CR6y6uzgoLTEt4L7RF1cit

---

Generated by Claude Code