From 6288ba3d7dc11561752121c4366ba23a0f95664f Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 22 Aug 2026 00:12:03 +0200 Subject: [PATCH] docs: accept repository classification boundary Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49 --- INTENT.md | 10 +- README.md | 7 ++ SCOPE.md | 20 +-- WORK-RECORDS.md | 7 ++ ...2-repository-classification-projections.md | 51 ++++++++ ...06-repository-classification-navigation.md | 118 ++++++++++++++++++ 6 files changed, 201 insertions(+), 12 deletions(-) create mode 100644 docs/adr/ADR-0002-repository-classification-projections.md create mode 100644 workplans/HUB-WP-0006-repository-classification-navigation.md diff --git a/INTENT.md b/INTENT.md index e74504f..55227de 100644 --- a/INTENT.md +++ b/INTENT.md @@ -2,8 +2,8 @@ **Project:** `hub-core` **Domain:** `infotech` -**Status:** Active — surviving hub framework and runtime (`HUB-WP-0004`) -**Updated:** 2026-08-21 +**Status:** Active — production hub framework and runtime +**Updated:** 2026-08-22 --- @@ -24,7 +24,7 @@ three-repo hub stack: | --- | --- | | `hub-core` | Shared Python package plus target framework/runtime — this repo | | `state-hub` | Legacy coordination host; capabilities move or retire incrementally | -| `core-hub` | Current `/api/v2` runtime; routes are absorbed, then the repo is archived | +| `core-hub` | Previous `/api/v2` runtime; retained temporarily as rollback before archive | Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md` @@ -109,6 +109,7 @@ models where extended, and workflow callbacks. | Concern | Owner | |---|---| | Repository-owned workplans, tasks, decisions, and consistency | `repo-manager` over Git authority | +| Repository classification validation and repository projection | `repo-manager` over `.repo-classification.yaml` authority | | Domain-specific business data and APIs | Domain hubs and specialized services | | Custodian canon, constitution, domain charters | `the-custodian` | | Event-triggered maintenance task creation | `activity-core` | @@ -127,7 +128,7 @@ acceptance flows) stay in the host hub. | Consumer | Relationship | |---|---| | `state-hub` | Compatibility source during incremental capability cutover | -| `core-hub` | `/api/v2` route/runtime source to absorb before archival | +| `core-hub` | Rollback source during stabilization; archive after CORE-WP-0010 closes | | `ops-hub`, `fin-hub`, future hubs | Domain/aspect extensions using versioned hub-core ports and manifests | Extraction boundary and migration status: @@ -145,6 +146,7 @@ Extraction boundary and migration status: - the surviving runtime exposes versioned `helixforge.hub-extension` ports and projections - schema changes to shared primitives are versioned through hub-core migrations, not ad hoc forks - repository work authority and domain-specific business models never migrate into hub-core +- cross-domain navigation is rebuilt from versioned owner projections with provenance --- diff --git a/README.md b/README.md index 248306f..3bc597b 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,13 @@ surface runs the immutable `055cf49` image while Core Hub remains deployed with an empty writer set through the seven-day stabilization window ending no earlier than 2026-08-28T20:49:50+02:00. +Repository classification remains authoritative in each repository and is +validated/projected by Repo Manager. Hub-core consumes that versioned +projection for cross-domain navigation under +`docs/adr/ADR-0002-repository-classification-projections.md`; it does not own a +mutable topic or classification write surface. Implementation and A5 handoff +are tracked in `HUB-WP-0006`. + ## First Slice - SQLAlchemy base metadata and timestamp helpers. diff --git a/SCOPE.md b/SCOPE.md index e7b41ea..073c48e 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,6 +1,6 @@ # SCOPE — hub-core -**Updated:** 2026-08-21 +**Updated:** 2026-08-22 --- @@ -38,6 +38,9 @@ the Python package remains independently importable. catalogs, port APIs, fixtures, and compatibility matrices - **Surviving runtime surfaces** — registry, messaging, progress and interaction events, projections, telemetry, `/api/v2` compatibility, and MCP +- **Cross-domain navigation projections** — rebuildable aggregation of Repo + Manager's validated repository classifications without classification write + authority - **Documentation** — `README.md`, `INTENT.md`, `SCOPE.md`, pointer to extraction boundary in `the-custodian` @@ -82,12 +85,13 @@ python3 -m venv .venv && .venv/bin/pip install -e . --- -## What is not possible yet +## What remains - **Published PyPI package** — consumed via editable path or private index only -- **Production durable port store** — T04 ships only the fail-closed ephemeral conformance backend - **Complete State Hub decoupling** — dev-hub routes and models still live in `state-hub` -- **ops-hub / fin-hub adoption** — planned; not verified in this repo +- **Repository classification navigation** — accepted contract; ingestion, + query/MCP, and A5 cutover remain in `HUB-WP-0006` +- **fin-hub adoption** — planned; not verified in this repo - **Capability registry entries** — scaffold only (`capabilities: []`); no registered reusable behaviors yet --- @@ -104,7 +108,7 @@ python3 -m venv .venv && .venv/bin/pip install -e . | Primary consumer | `state-hub` (editable dependency, router/schema import in progress) | | Extraction workplan | `CUST-WP-0025` (custodian domain) | | Target architecture | `SHR-ARCH-IA-0001` + `SHR-ARCH-HUB-0001` | -| Runtime workplan | `HUB-WP-0004` | +| Runtime workplans | `HUB-WP-0004` and `HUB-WP-0005` finished; `HUB-WP-0006` active | --- @@ -140,11 +144,11 @@ hub-core/ | Repo | Boundary | |---|---| | `state-hub` | Temporary compatibility source; no new permanent authorities | -| `core-hub` | `/api/v2` runtime and route source to absorb, then archive | -| `repo-manager` | Owns repository representation, work index, consistency, and governed Git mutations | +| `core-hub` | Previous `/api/v2` runtime retained as rollback through stabilization, then archive | +| `repo-manager` | Owns repository representation, classification validation/projection, work index, consistency, and governed Git mutations | | `the-custodian` | Owns ecosystem architecture (`hub-ecosystem-architecture.md`) and extraction boundary | | `reuse-surface` | Federation hub for capability indexes; not a runtime dependency of hub-core | -| `ops-hub` | Consumer of core-hub `/api/v2`; operations tables stay local | +| `ops-hub` | Verified consumer of hub-core `/api/v2`; operations tables stay local | --- diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index f672137..2f09c83 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -13,6 +13,7 @@ | workplan | HUB-WP-0003 | finished | — | workplans/HUB-WP-0003-ecosystem-consolidation-library-lane.md | | workplan | HUB-WP-0004 | finished | — | workplans/HUB-WP-0004-runtime-and-extension-contract.md | | workplan | HUB-WP-0005 | finished | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md | +| workplan | HUB-WP-0006 | active | — | workplans/HUB-WP-0006-repository-classification-navigation.md | | task | HUB-WP-0001-T01 | done | — | workplans/HUB-WP-0001-statehub-bootstrap.md | | task | HUB-WP-0001-T02 | done | — | workplans/HUB-WP-0001-statehub-bootstrap.md | | task | HUB-WP-0001-T03 | done | — | workplans/HUB-WP-0001-statehub-bootstrap.md | @@ -37,3 +38,9 @@ | task | HUB-WP-0005-T04 | done | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md | | task | HUB-WP-0005-T05 | done | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md | | task | HUB-WP-0005-T06 | done | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md | +| task | HUB-WP-0006-T01 | done | — | workplans/HUB-WP-0006-repository-classification-navigation.md | +| task | HUB-WP-0006-T02 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md | +| task | HUB-WP-0006-T03 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md | +| task | HUB-WP-0006-T04 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md | +| task | HUB-WP-0006-T05 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md | +| task | HUB-WP-0006-T06 | wait | — | workplans/HUB-WP-0006-repository-classification-navigation.md | diff --git a/docs/adr/ADR-0002-repository-classification-projections.md b/docs/adr/ADR-0002-repository-classification-projections.md new file mode 100644 index 0000000..c110516 --- /dev/null +++ b/docs/adr/ADR-0002-repository-classification-projections.md @@ -0,0 +1,51 @@ +# ADR-0002: Consume repository classification as a projection + +**Status:** Accepted +**Date:** 2026-08-22 +**Workplan:** `HUB-WP-0006-T01` +**Upstream contract:** `RMGR-CONTRACT-CLASSIFICATION-0001` version 1.0 + +## Context + +State Hub's legacy topic spine mixes mutable topic rows with repository +classification and navigation. State Hub retirement slice A5 replaces that +model. Repo Manager now validates each repository-authoritative +`.repo-classification.yaml` and publishes the validated classification in its +repository projection. + +Hub-core owns cross-domain projection and navigation, but it must not turn the +projection into a second classification authority or recreate a mutable topic +table. + +## Decision + +1. Repo Manager's classification contract version 1.0 is accepted without a + schema gap. Repo Manager owns validation and publication; the repository + file remains authoritative. +2. Hub-core consumes only validated Repo Manager projections through a + versioned `port.repo` boundary. It does not read, validate, infer, coerce, or + write `.repo-classification.yaml` directly. +3. Hub-core may aggregate repositories by primary domain, secondary domain, + category, capability tag, business stake, and business mechanic for + navigation and hub composition. Every derived view carries Repo Manager + source identity, repository revision, contract version, and rebuild time. +4. A legacy State Hub topic identifier may be retained as a compatibility + alias during A5 cutover. It is not a new authority and must have an expiry + or residual owner. +5. Invalid or unsupported projection versions fail closed and remain visible + as diagnostics. Hub-core does not silently reinterpret them. +6. State Hub owns the A5 consumer-route switch and rollback flag under + `STATE-WP-0079`. Hub-core owns the receiving projection/query and navigation + surface; Repo Manager owns the input contract. + +## Consequences + +- Topic navigation becomes rebuildable from repository authority rather than + copied from the State Hub `topics` table. +- Repository classification changes continue through governed Repo Manager + mutation and repository review, never a hub-core write endpoint. +- Hub-core needs an explicit Repo Manager client, projection schema, query/MCP + surface, provenance checks, and unavailable/version-mismatch behavior before + A5 can switch. +- Contract evolution is negotiated by version; a canon vocabulary change is + not inferred from observed data. diff --git a/workplans/HUB-WP-0006-repository-classification-navigation.md b/workplans/HUB-WP-0006-repository-classification-navigation.md new file mode 100644 index 0000000..3ec83d5 --- /dev/null +++ b/workplans/HUB-WP-0006-repository-classification-navigation.md @@ -0,0 +1,118 @@ +--- +id: HUB-WP-0006 +type: workplan +title: "Repository classification aggregation and navigation" +domain: infotech +repo: hub-core +status: active +owner: codex +topic_slug: custodian +created: "2026-08-22" +updated: "2026-08-22" +parent_project: prj-state-hub-retirement +parent_workplan: STATE-WP-0079 +related: + - HUB-WP-0004 + - HUB-WP-0005 + - RMGR-WP-0008 + - RMGR-CONTRACT-CLASSIFICATION-0001 +--- + +# Repository classification aggregation and navigation + +## Goal + +Consume Repo Manager's validated repository-classification projections and +provide rebuildable cross-domain aggregation/navigation without creating a +second classification authority. Supply the hub-core receiving surface needed +for State Hub retirement slices A5 and the repository-facing part of A4/B5. + +## Accept the classification projection boundary + +```task +id: HUB-WP-0006-T01 +status: done +priority: high +``` + +Review `RMGR-CONTRACT-CLASSIFICATION-0001` version 1.0 and record the hub-core +authority, validation, versioning, provenance, failure, and A5 routing +boundary. + +Completed 2026-08-22. `docs/adr/ADR-0002-repository-classification-projections.md` +accepts the contract without a schema gap. Repository files remain authority; +Repo Manager validates and publishes; hub-core derives navigation only; and +STATE-WP-0079 retains the consumer-route switch and rollback flag. + +## Freeze the hub-side projection contract + +```task +id: HUB-WP-0006-T02 +status: todo +priority: high +``` + +Define the input envelope, supported contract versions, stable repository +identity, cursor/snapshot semantics, provenance, diagnostics, and the derived +domain/category/tag/stake/mechanic views. Define legacy topic aliases as +temporary compatibility metadata, not mutable topic authority. + +## Implement Repo Manager ingestion and rebuild + +```task +id: HUB-WP-0006-T03 +status: todo +priority: high +``` + +Add an injected `port.repo` client, deterministic full rebuild plus incremental +upsert/delete behavior, durable PostgreSQL projection tables, content hashes, +and dependency-aware readiness. Reject invalid or unsupported projection +versions without coercion. + +## Expose projection query and MCP navigation + +```task +id: HUB-WP-0006-T04 +status: todo +priority: high +``` + +Expose cross-repository query routes and MCP tools for domain, secondary +domain, category, capability tag, business stake, and business mechanic. +Responses carry source revision and rebuild provenance. No endpoint writes +classification authority. + +## Prove conformance and failure behavior + +```task +id: HUB-WP-0006-T05 +status: todo +priority: medium +``` + +Add contract fixtures and checks for full rebuild, incremental changes, +deletion, duplicate delivery, unsupported versions, Repo Manager outage, +stable ordering/cursors, provenance, and absence of classification writes or +foreign database access. + +## Hand A5/A4 navigation to State Hub retirement + +```task +id: HUB-WP-0006-T06 +status: wait +priority: high +``` + +With `STATE-WP-0079`, compare legacy topic/navigation consumers with the new +projection, retain explicit aliases where required, run owned consumer smokes, +switch A5 through `RM_SLICE_TOPICSPINE`, and record rollback plus residual +expiry. Wait on T02-T05 and the State Hub cutover window. + +## Acceptance + +- [x] Repo Manager v1.0 authority and projection contract accepted +- [ ] Hub-side projection and compatibility alias contract versioned +- [ ] Rebuildable durable ingestion passes provenance and failure checks +- [ ] HTTP/MCP navigation reads only the derived projection +- [ ] A5/A4 consumer comparison and rollback evidence recorded