CI: governance drift check (closes #58)

[ProfessorPolymorphic]

Summary

Adds a Governance Drift GitHub Actions workflow that runs the upstream
vendor/data-governance/scripts/check_governance_drift.py validator on PRs
that touch the governance surface, plus the corresponding CLAUDE.md /
REFACTOR.md updates.

• Path filter: vendor/data-governance/**, lib/governance/**, app/standards/data-model/**, scripts/build-governance-catalog.*, and the workflow file itself
• actions/checkout@v4 with submodules: recursive
• actions/setup-python@v5 at Python 3.11
• No pip install — the upstream drift script is pure stdlib (base64, json, os, subprocess, sys, urllib.error, urllib.request, pathlib, typing); confirmed by reading the script and confirmed by the absence of requirements.txt / pyproject.toml in vendor/data-governance/
• Both PORTFOLIO_GH_TOKEN (preferred — read first by the script) and GITHUB_TOKEN (fallback) are exported to the step; this is required because the script reads files from sibling private repos (see "Findings" below)
• Output streamed to $GITHUB_STEP_SUMMARY as a fenced code block with a PASS/FAIL header

Acceptance criteria

• Workflow at .github/workflows/governance-drift.yml
• Submodules checked out with submodules: recursive
• Python set up; drift script's deps installed (none — stdlib only)
• Workflow fails when drift script reports drift (verified — see Findings)
• Drift output in the Actions Step Summary panel
• Path filter limits trigger
• CLAUDE.md and REFACTOR.md updated

Findings — two real issues that block a green run today

The CI on this PR is currently red, and per the brief's stop condition I
am not papering over either issue. Both serve as the red CI evidence:

• Run on commit a6e847a: https://github.com/ui-insight/AISPEG/actions/runs/25235605858
• Run on commit e9f1cd8: https://github.com/ui-insight/AISPEG/actions/runs/25235691593

I could not produce a green run from this branch alone. Reasons:

1. Cross-repo token scope (workflow side)

The script's run_remote_checks reads files from five sibling repos in the
ui-insight org (OpenERA, UCMDailyRegister, AuditDashboard,
StratPlanTacticsMB, ProcessMapping), four of which are private. The
auto-issued workflow GITHUB_TOKEN is scoped only to ui-insight/AISPEG and
returns 404 on repos/ui-insight/OpenERA/contents/docker-compose.yml. The
script's file_text method does not catch RemoteMissing, so it crashes
mid-run with an uncaught exception:

RemoteMissing: GitHub resource not found for repos/ui-insight/OpenERA/contents/docker-compose.yml

The script already documents the right env var for this: GitHubClient.__init__
reads PORTFOLIO_GH_TOKEN first. Once an org-level secret named
PORTFOLIO_GH_TOKEN (a PAT with repo scope on the five sibling repos) is
provisioned and visible to this workflow, the script will use the HTTP path
with that token and run to completion. The workflow already exposes
PORTFOLIO_GH_TOKEN to the step, so no further AISPEG-side change is needed
once the secret exists.

2. Pre-existing upstream registry drift (data-governance side)

Even after the token issue is fixed, the script will fail one check:

FAIL ProcessMapping remote controlled-value counts match local governance registry

Verified locally with the host's gh auth: the live ui-insight/ProcessMapping
repo's data/allowed_values.json currently has 10 vocabulary groups / 78
values; the vendored data-governance registry expects 9 / 70. The
submodule pointer is already at ecb9eaccbf23d0a8817366cc85f55a01a32e62a5,
the tip of ui-insight/data-governance@main, so this is genuine pre-existing
drift in the upstream registry — not introduced by this PR.

Recommended unblock: open a follow-up PR against ui-insight/data-governance
to align catalog/processmapping.json, vocabularies/processmapping/allowed_values.json,
and the relevant docs/README rows with the live ProcessMapping vocabulary
counts. Then bump the AISPEG submodule pointer.

What I did not do

• I did not add a try/except around the script invocation or || true
  to mask the failure.
• I did not edit the upstream script.
• I did not modify the vendored registry data.

The workflow itself is functioning exactly as designed: it fails the build
on detected drift, surfaces the reason in the step summary, and the path
filter keeps it quiet on PRs that don't touch the governance surface.
Provisioning the secret + bumping upstream registry are out-of-scope
operator actions; once both are done, this PR's CI will go green on a
re-run.

Test plan

• Verify the workflow run triggered on this PR appears in the Actions tab and links from the PR's Checks panel
• Open the failed run and confirm the step summary panel shows the PASS/FAIL block with the script's output (or its traceback) inline
• After PORTFOLIO_GH_TOKEN is provisioned and the upstream registry drift is fixed, re-run the workflow and confirm it goes green
• Open a separate PR that touches only an unrelated path (e.g. app/portfolio/**) and confirm this workflow does not run

🤖 Generated with Claude Code

[ProfessorPolymorphic]

Token unblock confirmed

PORTFOLIO_GH_TOKEN is now provisioned as an org secret. Re-ran the workflow on this PR; the result tells a much cleaner story:

• ✅ 36 PASS lines including:
  • PASS remote repository exists: ui-insight/OpenERA
  • PASS remote repository exists: ui-insight/UCMDailyRegister
  • PASS remote repository exists: ui-insight/AuditDashboard
  • PASS remote repository exists: ui-insight/StratPlanTacticsMB
  • PASS remote repository exists: ui-insight/ProcessMapping
  • PASS OpenERA remote compose exposes current frontend/backend ports
  • PASS UCM remote compose documents shared DB and HOST_PORT default
  • PASS Audit Dashboard remote compose matches documented ports and backend health endpoint
  • PASS ProcessMapping remote asset counts match local governance registry
  • PASS StratPlan remote canonical counts match local governance registry
• ❌ One legitimate FAIL: ProcessMapping remote controlled-value counts match local governance registry — the vocabulary drift documented in ui-insight/data-governance#10.

This is the workflow doing exactly what it was built to do. The remaining red ride is now an upstream-registry-alignment problem, not a CI problem.

Run #25235691593, attempt 2

What's left to make this PR mergeable

1. ✅ Provision PORTFOLIO_GH_TOKEN org secret — done
2. ⏭ Resolve ui-insight/data-governance#10 (ProcessMapping vocab counts) — upstream
3. ⏭ Bump the vendor/data-governance submodule pointer in this repo to pick up the upstream fix

Once 2 + 3 land, the next push will produce the green run we need for the PR description's "one green / one red" evidence.

[ProfessorPolymorphic]

All-green achieved

The submodule bump landed (vendor/data-governance → 5e811f7) and the workflow flipped:

• ✅ Lint & Accessibility — 29s
• ✅ TypeScript — 24s
• ✅ Production Build — 34s
• ✅ Validate governance registry — 9s (first green run on this PR)

The PR now has both a red run (attempt 1 — token-scope issue, since fixed by org-secret provisioning) and a green run (latest) captured in the run history — satisfying the "one green / one red" evidence acceptance criterion from #58.

Trajectory

1. Workflow created → red (uncaught exception, token missing).
2. PORTFOLIO_GH_TOKEN org secret provisioned → red (script-level, on legitimate ProcessMapping registry drift).
3. ui-insight/data-governance#11 merged (synced ProcessMapping → registry, adding the DocumentType group).
4. Submodule bump on this branch (commit 34e75d0) + rebased onto current main.
5. → All green.

Merging.