Close the scoping vocabulary gap; scope ADR 0005's status to what was decided - #318
Merged
Merged
Conversation
Closes the follow-up ADR 0001's 2026-07-24 amendment named and never did: the vendored iids-portfolio ProjectStatus vocabulary did not list `scoping`, while lib/portfolio.ts has used it since July and one project currently claims it. Nothing would have caught this. The governance drift workflow does not run on lib/portfolio.ts changes, so the typed union and the vendored registry can diverge in silence — which is the failure mode the catalog exists to prevent. Upstream ui-insight/data-governance#17 adds `scoping` at Display_Order 2 between idea and approved, corrects the Exploring rollup to include it, and sharpens `idea` (which read "no owner OR no sponsor" and would now overlap scoping — the verifier means neither). This bumps the submodule pointer and regenerates the typed catalog from it. Regenerated, not hand-edited, per Agent Rule 13. npm run build, npm run lint, and npm run verify:portfolio all pass (29 projects, 0 errors, 2 pre-existing stale-commit-date warnings). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The header read `Proposed` / `Deciders: Pending` three days after Phase 1 shipped, so the index was telling readers that a decision embodied in live tables, live code, and a public surface had not been made yet. The fix is not a flat flip to Accepted. This ADR does two different things: it designs a registry this repo owns and can build alone, and it proposes a division of institutional labour that binds other offices — TDX as the workflow system of record, a shared prioritization model, OIT's ownership of the approved-tools list. The first was decided and built. The second is still a proposal, and nothing in this repo can accept it on the working group's behalf. Marking the whole ADR Accepted would assert a ratification that hasn't happened, in the audit trail itself. So the status is split, with a dated amendment recording the split (append-only, per this directory's own lifecycle rules) and an inventory of what exists: Phase 1's five tables plus lib/utr.ts, lib/requests.ts, Migration 019's survey candidates, and /portfolio/pipeline are Accepted; the TDX boundary, prioritization model, and approved-tools ownership stay Proposed; Phases 2-4 are unbuilt, and the amendment names the specific tables and modules that don't exist so the gap is checkable rather than implied. Deciders now names Barrie Robison for the part that was decided, rather than "Pending". The format section of docs/adr/README.md gains a line permitting a scoped status for this case, since ADR 0005 is now the precedent — with the constraint that a header must never imply a ratification that hasn't happened. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Vendored strategic-plan submodule is behind upstreamThe vendored submodule pointer at The submodule is pinned at upstream This is an advisory comment from |
Governance catalog changes1 vocabulary value(s) added, 0 removed across 1 domain(s). Vocabulary values on existing groups (+1 / -0)Added
Posted by |
ProfessorPolymorphic
added a commit
that referenced
this pull request
Jul 27, 2026
The `scoping` drift closed in #318 should never have been findable only by hand. ADR 0001's amendment named the upstream registration as a follow-up, the follow-up was missed, a project shipped claiming the status, and every check stayed green for three days. My first instinct was to add lib/portfolio.ts to the Governance Drift workflow's path filter. That would not have worked: the drift script validates the vendored registry's internal consistency and its remote repo canaries, and has no knowledge of this repo's TypeScript unions. Running it on a portfolio change would have been a no-op that looked like a fix. The check belongs in verify:portfolio, which already runs on every PR and can see both sides. verifyGovernanceVocabularyParity() asserts that the ProjectStatus and PublicStage unions in lib/portfolio.ts and the registered iids-portfolio vocabulary contain exactly the same codes. It reads the unions from the exhaustive OPERATIONAL_LABEL and PUBLIC_STAGE_LABEL records, so tsc guarantees there is no third list to keep in sync, and a missing vocabulary group is itself an error rather than a silently-skipped check. Both directions fail. A code in the union but not the vocabulary means the registry misdescribes what statuses exist; a code in the vocabulary but not the union means one was retired without deregistering it, and the Data Model explorer shows stakeholders a state the site can no longer produce. Each message names the fix, including the two-repo order. Verified by reproducing the original drift — removing `scoping` from the generated vocabulary fails with the intended error — and the reverse, by adding a code the union lacks. Baseline still passes: 29 projects, 0 errors, 2 pre-existing stale-commit-date warnings. ADR 0001 gains an amendment closing both vocabulary follow-ups and recording the consequence for future ones: adding an operational status is now a two-repo change in a fixed order, and an amendment that defers something should say what will fail if it is forgotten. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The two remaining governance items from the documentation audit.
1.
scopingreaches the vendored vocabularyADR 0001's 2026-07-24 amendment named this follow-up itself — "add
scopingto the vendorediids-portfolioProjectStatus vocabulary upstream" — and it was never done.lib/portfolio.tshas usedscopingsince July and one project currently claims it, against a registry that didn't list the code.Nothing would have caught it. The governance drift workflow doesn't run on
lib/portfolio.tschanges, so the typed union and the vendored registry can diverge in silence — which is the exact failure the catalog exists to prevent.Upstream: ui-insight/data-governance#17, merged. It adds
scopingat Display_Order 2 betweenideaandapproved, corrects theExploringrollup toidea, scoping, approved, and sharpensidea— its rule read "no committed operationalOwner OR no committed iidsSponsor", which withscopingin place would let a project with exactly one of the two satisfy both codes. The verifier treats neither asideaand either asscoping; the vocabulary now says the same. Rules were transcribed fromlib/portfolio-verification.tsrather than paraphrased.This PR bumps the submodule pointer and regenerates
lib/governance/vocabularies.tsvianpm run build:governance— regenerated, not hand-edited, per Agent Rule 13.2. ADR 0005's status
The header read
Proposed/Deciders: Pendingthree days after Phase 1 shipped, so the index was telling readers a decision embodied in live tables, live code, and a public surface hadn't been made.A flat flip to Accepted would have been wrong. This ADR does two things:
tech_requests+ 4 tables (Migration 018),lib/utr.ts,lib/requests.ts, Migration 019's survey candidates,/portfolio/pipelineproject_interest_pool,governance_flags,project_gates, orprioritization_*tables; nolib/approved-tools.ts,/standards/approved-tools,/internal/prioritization, orscripts/sync-tdx.tsMarking the whole thing Accepted would assert that a group which hasn't met on it signed off. The site's standard is that every claim names a human and holds up; an ADR header overclaiming ratification fails that standard in the audit trail itself.
Recorded as a dated amendment rather than a silent header rewrite, per this directory's append-only rule.
docs/adr/README.md's format section gains a line permitting a scoped status, since 0005 is now the precedent — constrained so a header can never imply a ratification that hasn't happened.One thing to confirm
Decidersnow reads "Barrie Robison (IIDS), for the registry design and Phase 1 as built." That's inferred from the 2026-07-24 amendment ("the portfolio owner's call") and from Phase 1 having shipped. Correct it if the attribution is wrong.Verification
npm run build,npm run lint, andnpm run verify:portfolioall pass — 29 projects, 0 errors, 2 pre-existing stale-commit-date warnings.scopingand the correctedExploringrollup confirmed present in the regenerated catalog.🤖 Generated with Claude Code