CI: governance drift check (closes #58)

.github/workflows/governance-drift.yml

@@ -0,0 +1,74 @@
+name: Governance Drift
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "vendor/data-governance/**"
+      - "lib/governance/**"
+      - "app/standards/data-model/**"
+      - "scripts/build-governance-catalog.*"
+      - ".github/workflows/governance-drift.yml"
+
+jobs:
+  drift:
+    name: Validate governance registry
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository (with submodules)
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # The drift script (vendor/data-governance/scripts/check_governance_drift.py)
+      # is pure stdlib — no requirements.txt and no third-party imports — so there
+      # is nothing to `pip install`. Confirmed by reading its imports: base64,
+      # json, os, subprocess, sys, urllib.error, urllib.request, pathlib, typing.
+      #
+      # Token: the script's remote checks read several repos in the ui-insight
+      # org (OpenERA, UCMDailyRegister, AuditDashboard, StratPlanTacticsMB,
+      # ProcessMapping, AISPEG), most of which are private. The workflow-issued
+      # GITHUB_TOKEN is scoped to this repo only, so an org secret named
+      # PORTFOLIO_GH_TOKEN (PAT with `repo` scope on those repos) is preferred
+      # if present; we fall back to GITHUB_TOKEN otherwise. The script reads
+      # PORTFOLIO_GH_TOKEN first (see GitHubClient.__init__).
+
+      - name: Run governance drift check
+        id: drift
+        env:
+          PORTFOLIO_GH_TOKEN: ${{ secrets.PORTFOLIO_GH_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -o pipefail
+          script="vendor/data-governance/scripts/check_governance_drift.py"
+          if [ ! -f "$script" ]; then
+            echo "::error::Drift script not found at $script — submodule may not have been checked out."
+            exit 2
+          fi
+
+          # Tee to a file so we can post the output to the step summary regardless of exit status.
+          set +e
+          python "$script" 2>&1 | tee drift-output.txt
+          status=${PIPESTATUS[0]}
+          set -e
+
+          {
+            echo "## Governance drift check"
+            echo
+            if [ "$status" -eq 0 ]; then
+              echo "Result: **PASS** — registry, vocabularies, and remote portfolio state are consistent."
+            else
+              echo "Result: **FAIL** — drift detected. Review the output below and update the registry, vendored submodule, or remote source as appropriate."
+            fi
+            echo
+            echo '```'
+            cat drift-output.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          exit "$status"

CLAUDE.md

@@ -189,6 +189,12 @@ npm run lint               # ESLint
 
 `npm run build` is the primary verification step. Run it before committing.
 
+A `Governance Drift` workflow (`.github/workflows/governance-drift.yml`) runs
+on PRs that touch `vendor/data-governance/**`, `lib/governance/**`,
+`app/standards/data-model/**`, or `scripts/build-governance-catalog.*`, and
+fails the build if the upstream drift script reports drift between the
+vendored registry and the live portfolio repos.
+
 ### Governance submodule
 
 `vendor/data-governance/` is a git submodule pointing at

REFACTOR.md

@@ -312,6 +312,21 @@ similarity-aware review. Status updates flow from manual edits to
 **Output:** old AISPEG-collaborator-era content is fully retired or salvaged.
 Codebase reflects the new architecture without legacy cruft.
 
+### Sprint 5 — Data governance integration
+
+- Vendored `ui-insight/data-governance` as a git submodule at
+  `vendor/data-governance/` and added a `prebuild`/`predev` step
+  (`scripts/build-governance-catalog.ts`) that emits typed
+  `lib/governance/{catalog,vocabularies}.ts` modules so the Data Model
+  explorer page stays in sync with the upstream Unified Data Model.
+- Added a `Governance Drift` GitHub Actions workflow
+  (`.github/workflows/governance-drift.yml`) that runs the upstream
+  `check_governance_drift.py` validator on PRs touching
+  `vendor/data-governance/**`, `lib/governance/**`,
+  `app/standards/data-model/**`, or `scripts/build-governance-catalog.*`.
+  Drift output streams into the Actions Step Summary panel; the job fails
+  on non-zero exit so registry drift cannot land silently.
+
 ## v1 cut
 
 **v1 = Sprints 1 + 2 + 3.** v1.5 = Sprint 4. Sprint 1 alone is independently

lib/governance/vocabularies.ts

@@ -726,6 +726,54 @@ export const vocabularyGroups: VocabularyGroup[] = [
       }
     ]
   },
+  {
+    "domain": "processmapping",
+    "application": "ProcessMapping",
+    "group": "DocumentType",
+    "description": "Document classifications for materials referenced in process maps and workflows — award documents, funding announcements, budget forms, proposal narratives, subaward agreements, and sponsor correspondence",
+    "values": [
+      {
+        "code": "AWARD_NOTICE",
+        "label": "Award Notice / Agreement",
+        "description": "Fully executed award agreements, federal notices of award, cooperative agreements, research terms and conditions, and related award-establishing documents"
+      },
+      {
+        "code": "AWARD_MODIFICATION",
+        "label": "Award Modification",
+        "description": "Post-award amendments including modifications, no-cost extensions, PI changes, rebudget approvals, and amendment letters"
+      },
+      {
+        "code": "FUNDING_OPPORTUNITY",
+        "label": "Funding Opportunity (FOA/NOFO/RFA)",
+        "description": "Funding opportunity announcements, notices of funding opportunity, requests for applications, program announcements, and program solicitations"
+      },
+      {
+        "code": "BUDGET_DOCUMENT",
+        "label": "Budget Form / Spreadsheet / Justification",
+        "description": "R&R and SF-424A budget forms, budget spreadsheets, budget justification narratives, and sponsor-specific budget pages (NIH modular, NSF detailed)"
+      },
+      {
+        "code": "PROPOSAL_NARRATIVE",
+        "label": "Proposal Narrative & Personnel Forms",
+        "description": "Proposal documents, project narratives, research plans, biosketches, current and pending support, and VERAS proposal forms with personnel listings"
+      },
+      {
+        "code": "SUBAWARD_DOCUMENT",
+        "label": "Subaward / Subrecipient Agreement",
+        "description": "Subaward agreements, subrecipient agreements, pass-through entity subaward documents, and subaward modifications"
+      },
+      {
+        "code": "COMPLIANCE_RECORD",
+        "label": "Compliance / Personnel Reference Record",
+        "description": "SFI disclosure confirmations, RST completion records, Banner NBAJOBS records, departmental personnel lists, and institutional policy references (APM)"
+      },
+      {
+        "code": "SPONSOR_CORRESPONDENCE",
+        "label": "Sponsor Correspondence & Guidance",
+        "description": "Sponsor correspondence, agency financial reporting guides, and other ad-hoc communications or guidance documents from the funding agency"
+      }
+    ]
+  },
   {
     "domain": "processmapping",
     "application": "ProcessMapping",