[Followup] Quarterly audit: cross-cache-identity flag-doc vs code drift

[jakebromberg]

Summary

Quarterly audit task per §4.2 of the cross-cache-identity plan. Diffs the canonical Backend feature-flag inventory in WXYC/Backend-Service/CLAUDE.md ("Cross-cache-identity feature flags (canonical inventory)") against actual code references in each consumer repo and fails if any flag has been renamed, removed, or added without coordinated CLAUDE.md updates.

Why this is post-MVP

The per-PR grep-asserts (Backend scripts/check-cross-cache-identity-flags.sh, LML/SI scripts/check_cross_cache_identity_flags.sh) catch CLAUDE.md drift at PR time. They do NOT catch (a) drift between Backend's canonical and a consumer's local doc, (b) drift between docs and code references — the per-repo asserts are scoped to that repo only.

A periodic cross-repo audit is the right tier-3 check. It is not PR-blocking and does not need to be on the cross-cache-identity project board (this is cross-cache-identity-followup work, not core scope).

Scope

A scheduled GitHub Action (cron weekly or quarterly; recommend monthly during the dual-run window, then quarterly post-cutover) that:

1. Checks out Backend, LML, semantic-index.
2. Parses Backend's CLAUDE.md "Cross-cache-identity feature flags (canonical inventory)" table — extract (flag_name, owning_repo, default) tuples.
3. For each (flag_name, owning_repo):
   • Confirms flag_name appears in the owning repo's local doc.
   • Confirms flag_name appears at least once in the owning repo's source tree (Python os.getenv("FLAG") / Node process.env.FLAG).
   • Confirms the doc-listed default matches the in-code default.
4. Posts a Markdown report as a comment on this issue (or an open follow-up) when drift is found. Otherwise no-op.

Deliverables

• Workflow file at WXYC/catalog-audits/.github/workflows/cross-cache-identity-flag-audit.yml (matches the existing pattern of cross-cache-identity-timeouts.yml).
• A short audit script in WXYC/catalog-audits/scripts/cross_cache_identity_flag_audit/ (Python, since catalog-audits is Python).
• Documentation note in catalog-audits/CLAUDE.md ("Cross-cache-identity decision timeouts" subsection) cross-referencing this audit.

Out of scope

• The audit does NOT modify any docs or code. Read-only, report-only.
• Not a deploy gate. The per-PR grep-asserts already block PR merge on local-doc drift.

Plan reference

WXYC/wiki/plans/library-hook-canonicalization-plan.md §4.2 (audit clause: "A quarterly post-launch task ... diffs the canonical Backend list against actual code references in each consumer repo").

Related

• Parent (BS#667 cluster):
  • [E2 step 0d] Cross-repo env-var documentation (canonical source: Backend CLAUDE.md) #667 (E2 step 0d issue)
  • [E2 step 0d 1/3] Backend canonical feature-flag inventory + grep-assert (BS#667) #740 (canonical inventory PR)
  • [E2 step 0d 2/3] LML feature-flag documentation + grep-assert (cross-cache-identity) library-metadata-lookup#253 (LML PR)
  • [E2 step 0d 3/3] semantic-index feature-flag documentation + grep-assert (cross-cache-identity) semantic-index#285 (semantic-index PR)
• Epic parent: [Epic] E2 — Canonical identity record (library_identity) + LML write contract #663 (E2)

[jakebromberg]

Superseded by the architecture pivot in #800.

This issue would have built a catalog-audits workflow watching the §4.2 flag inventory in #667 (also closed today as superseded). With the pivot retiring the dual-write flag set, the drift-audit target no longer exists.

If a similar audit becomes useful for the new bulk-resolve flag set, it'll be re-filed against that surface.

See #800 for the decision record.