ADR-003 (plan only): repository scope boundary — govern the Gap Map, not the OSO org - #404
Merged
Merged
Conversation
…not the OSO org A deeper review found the root cause of Phase 5's sprawl: inventory membership is triggered by "exists on OSO OR read by any repo notebook," which pulls whole peripheral pipelines (entities, events, metrics, analytical scores, catalog reference inputs) into Gap Map governance and generates endless namespace-move, schedule, compatibility and retirement work. The ownership test is wrong: a live OSO notebook reading a table does not make it map governance. This is a PLAN-ONLY PR. It sets the boundary and sequences the execution; it moves, removes, or reclassifies no asset. - docs/architecture/adr-003-repository-scope-boundary.md: the boundary rule (4 membership categories), a `role` field taxonomy (governed-output / repo-computation / compatibility), a warehouse/dependencies.yaml spec for external OSO inputs (contract, not owned), a root-scoped-DAG design (notebooks stop creating core DAG nodes; three separate views), proposed anti-reintroduction gates, and a full classification: the 24 long_tail assets to externalize and the 4 questionable gap_map assets resolved individually. Honestly flags that this partly unwinds the recent foundation_model_repos work (#397/#400) and retires the stack_map transition. - CLAUDE.md: charter amended with the scope boundary + the Phase-5 freeze. - migration-status.md: Phase 5 marked FROZEN (scope reset) pending the boundary. - data-architecture.md §11.3: superseded-in-basis pointer to ADR-003. - phase5 plan + runbook: FROZEN banners; execute nothing until the boundary lands. No inventory change, so no counts move. Gates: build.validate 0 errors, count-claim clean, docs-integrity + inventory suites pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5bY5TtNtdqoxaeJBdNmXv
…variants Address the four blocking findings, the execution clarification, and the nits on #404. 1. Freeze durability: ADR status is now "Accepted — implementation pending"; the freeze holds until the mechanism (role field, dependencies.yaml contracts, root-scoped DAG, anti-reintroduction gates) is MERGED, not when the ADR is accepted. CLAUDE.md, migration-status, and both old runbooks reworded accordingly. 2. AGENTS.md: the repo map no longer says "one entry per platform table" or that warehouse/models mirrors the org. It now states assets.yaml holds governed outputs + repo computation + compatibility shims only, external OSO inputs live in dependencies.yaml, warehouse/models is not an org-wide mirror, and OSO existence / standalone-notebook use never confers membership. 3. Taxonomy split: the repo tracks governed assets (categories 1,2,4) in assets.yaml and dependency contracts (category 3) in dependencies.yaml, disjoint; a dependency is never a governed asset. governed-output redefined as a published Gap Map artifact whose schema + publication lifecycle are owned here (so the evaluation.* release-path outputs qualify even though they derive partly from observations). "gap_map/release only" is now "every governed asset is population: gap_map; only governed outputs require release_path". 4. Gate invariants rewritten to also protect dependencies.yaml: every external table a repo computation reads appears in dependencies.yaml exactly once; every dependency has a named required_by; no dependency referenced only by a notebook/external product; assets.yaml and dependencies.yaml are disjoint; platform inputs are contracts (compatibility-shim the exception); required_by is recorded and mechanically re-derived and gated. Execution clarification: step 5 removals require a verified ownership handoff (destination repo/path, owner, merged transfer PR, working deploy, proof OSO consumers still work); foundation_model_repos is unwound by ownership transfer, never by reversing the platform deployment, so entities.models is never orphaned. Nits: dependencies schema allows content_contract_sha256 + verified_at when an oso.* input has no model revision; the role is compatibility-shim (distinct from status: compatibility); the old runbooks now read "SUPERSEDED — NOT EXECUTABLE", not merely frozen. Still plan-only; no inventory change. Gates: build.validate 0 errors, count-claim clean, docs-integrity + inventory suites pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5bY5TtNtdqoxaeJBdNmXv
…mark superseded docs HISTORICAL - CLAUDE.md scope: governed outputs/repo computations/compatibility shims -> assets.yaml; direct OSO inputs -> dependencies.yaml, never assets.yaml (was still listing OSO deps as assets.yaml members). - phase5 plan + runbook: internal status lines -> HISTORICAL - NOT EXECUTABLE; the '3 executable moves' phrasing neutralized to past-tense/superseded. - ADR execution-sequence heading: 'frozen until this boundary lands' -> 'frozen until the mechanism lands'. - data-architecture.md 11.3 pointer: ADR-003 'proposed' -> 'Accepted - implementation pending'. Plan-only; no inventory change. Gates: build.validate 0, count-claim clean, docs-integrity + inventory suites pass, git diff --check clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5bY5TtNtdqoxaeJBdNmXv
Per review: a 'responsible owner' field is signal-free when it is always the same account. Replace the 5-item ownership-handoff checklist with one load-bearing rule for step 5 externalizations: never leave a consumed table with no producer and no data (don't delete the live OSO table; keep every reader resolving). The foundation_model_repos -> entities.models no-orphan case is preserved. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5bY5TtNtdqoxaeJBdNmXv
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
2 participants
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.
What
A plan-only scope reset. It sets the repository boundary and sequences the execution into later PRs; it moves, removes, and reclassifies no asset and changes no behavior.
Root cause it addresses: inventory membership is triggered by "exists on OSO OR is read by any repo notebook," which pulls whole peripheral pipelines (
entities,events,metrics, analyticalscores, catalog reference inputs) into Gap Map governance and generates the endless namespace-move / schedule / compatibility / retirement work. The ownership test is wrong — a live OSO notebook reading a table doesn't make it map governance.The boundary (ADR-003)
An asset is governed only if it is: (1) a curated declaration / published table on the release path, (2) repo-owned computation implementing/auditing map semantics, (3) a direct OSO dependency of (1)/(2) — recorded as a contract, not owned, or (4) a temporary compatibility shim with an exit. Everything else lives on OSO and is discoverable in OSO's UI.
Mechanisms specified (built in later PRs, not here):
rolefield on governed assets (governed-output/repo-computation/compatibility);warehouse/dependencies.yaml— external-input contracts (purpose, grain, freshness, verified_revision,owner: oso), carrying no migration/retirement/mirror obligations;population: long_tailas a governed population).Classification (grounded in the current inventory, dated 2026-08-29)
long_tailassets → externalize (discovery pipeline, activity pipeline, analytical scores, catalog reference inputs). Ownership transfers to the platform repo; no OSO deletion. Includesregistry.foundation_model_repos+catalog.foundation_model_repos— this partly unwinds Phase 5 close-out: foundation_model_repos → registry, #395 back-port, orphan receipt #397/Phase 5 reconciliation: activate registry.foundation_model_repos, repoint entities.models #400, flagged honestly.gap_mapassets resolved individually (stack_map,stack_contributors,signal_artificialanalysis.model_evaluations,signal_lmarena.text_leaderboard) — none is in the canonical map pipeline; each externalizes or must gain a named map use. This also retires thestack_map → registrytransition.Freeze
All Phase-5 platform migration is held until this boundary is accepted and the mechanism PRs (steps 2–4) land.
CLAUDE.md,migration-status.md, and both phase5 operations docs carry the freeze;data-architecture.md§11.3 gets a superseded-in-basis pointer.Gates
No inventory change → no counts move.
build.validate→0 error(s);count_claim_violations()→[];test_docs_integrity+test_assets_inventorypass.Checklist
uv run python -m build.validateprints0 error(s)build/notebook_data.jsonornotebooks/ai-stack-map.py🤖 Generated with Claude Code
Generated by Claude Code