tegwick
1b3eb39436
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49
175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
---
|
|
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
|
|
state_hub_workstream_id: "c5abf6a3-0ea9-43b8-8757-179829dd8a9c"
|
|
---
|
|
|
|
# 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
|
|
state_hub_task_id: "b1e2fe24-8a38-4672-a7a7-4a45f90355fb"
|
|
```
|
|
|
|
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.
|
|
State Hub decision `7168ee97-71bd-43e8-9d8b-0d5532743d08` records the same
|
|
single-authority boundary.
|
|
|
|
## Freeze the hub-side projection contract
|
|
|
|
```task
|
|
id: HUB-WP-0006-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "47d7d168-217f-45c6-b4d7-ab9cf4dd5329"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed 2026-08-22. Packaged `helixforge.repository-navigation` 1.0.0
|
|
defines the strict Repo Manager page envelope, stable registrar UUID identity,
|
|
atomic snapshot/rebuild and cursor rules, per-repository provenance, failure
|
|
diagnostics, all six derived facet kinds, read-only query routes, and expiring
|
|
State Hub topic aliases with residual ownership. Both representative fixtures
|
|
validate, the wheel contains the versioned artifacts, and the full suite passes
|
|
72 tests.
|
|
|
|
## Implement Repo Manager ingestion and rebuild
|
|
|
|
```task
|
|
id: HUB-WP-0006-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "2884eb0f-046f-4122-a422-8a06c7c32298"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed 2026-08-22. `RepositoryNavigationService` consumes an injected
|
|
`port.repo` client, validates the exact v1.0.0 envelope plus cross-page
|
|
semantics, and applies deterministic full or incremental generations with
|
|
idempotent duplicate handling. Migration `0003_repository_navigation`
|
|
persists active state, normalized repository rows, and all derived facets in
|
|
one atomic transaction. Invalid versions and transfers preserve the last
|
|
generation as stale; readiness distinguishes current, stale, unavailable, and
|
|
disabled dependencies. PostgreSQL migration SQL renders through head and the
|
|
77-test suite covers durable reopen, startup injection, outage, rejection,
|
|
full rebuild, upsert, and deletion.
|
|
|
|
## Expose projection query and MCP navigation
|
|
|
|
```task
|
|
id: HUB-WP-0006-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "a1d85610-c3ea-4718-b394-ba4abcecf177"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed 2026-08-22. The read-only projection port now supports cross-facet
|
|
HTTP queries plus direct facet resolution for primary/secondary domain,
|
|
category, capability tag, business stake, and business mechanic. Filters OR
|
|
within a family and AND across families; snapshot/filter-bound cursors reject
|
|
reuse after rebuild with 409. Responses validate against the frozen output
|
|
schema and carry source revision, observed provenance, rebuild time, status,
|
|
and content hash. MCP tools `query_repository_navigation` and
|
|
`get_repository_navigation_facet` expose the same navigation fields. Runtime
|
|
OpenAPI inspection confirms that every navigation operation is GET-only.
|
|
|
|
## Prove conformance and failure behavior
|
|
|
|
```task
|
|
id: HUB-WP-0006-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "a3c0efba-9913-4617-b167-8853b34de36e"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed 2026-08-22. A packaged incremental fixture and 15 focused ingestion
|
|
checks now cover single- and multi-page full rebuild, incremental upsert plus
|
|
delete, duplicate delivery, snapshot-ID reuse with changed content,
|
|
unsupported versions, upstream outage, inconsistent-page atomicity, durable
|
|
reopen, stable ordering, filter- and generation-bound cursors, response
|
|
provenance, GET-only HTTP navigation, and projection tables without foreign
|
|
database keys. The wheel rebuild succeeds and the complete suite passes 88
|
|
tests.
|
|
|
|
## Hand A5/A4 navigation to State Hub retirement
|
|
|
|
```task
|
|
id: HUB-WP-0006-T06
|
|
status: wait
|
|
priority: high
|
|
state_hub_task_id: "5c6f3006-b1c7-422b-ad38-8727ae4dc7c2"
|
|
```
|
|
|
|
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.
|
|
|
|
Readiness checkpoint 2026-08-22: T02-T05 are complete, but T06 remains `wait`.
|
|
`RMGR-WP-0008-T06` delivered validation and the authority contract, not a
|
|
transport that emits the frozen paged envelope with registrar
|
|
`repository_id` values. A Repo Manager-owned `port.repo` publisher/adapter is
|
|
therefore still required before comparison can start. Hub-core commits
|
|
`a701dc8` through `93a9151` also require migration/image deployment, and
|
|
`STATE-WP-0079-T04` remains `progress`. Do not move `RM_SLICE_TOPICSPINE` from
|
|
off until those three gates close; rollback remains the flag set to off plus
|
|
the prior State Hub read route.
|
|
|
|
## Acceptance
|
|
|
|
- [x] Repo Manager v1.0 authority and projection contract accepted
|
|
- [x] Hub-side projection and compatibility alias contract versioned
|
|
- [x] Rebuildable durable ingestion passes provenance and failure checks
|
|
- [x] HTTP/MCP navigation reads only the derived projection
|
|
- [ ] A5/A4 consumer comparison and rollback evidence recorded
|