85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
|
# Genesis of Repo Manager
|
||
|
|
|
||
|
|
**Recorded:** 2026-08-09
|
||
|
|
**Origin project:** `prj-state-hub-retirement`
|
||
|
|
|
||
|
|
## Background
|
||
|
|
|
||
|
|
State Hub began as a useful live coordination and read-model service around
|
||
|
|
repository-backed workplans. Over time it accumulated repository registration,
|
||
|
|
workplans and tasks, decisions, messaging, progress, capability workflows,
|
||
|
|
service catalogs, SBOM data, telemetry, suggestions, execution controls,
|
||
|
|
operational projections, and dashboard aggregation.
|
||
|
|
|
||
|
|
This proved the value of file-backed work records and shared agent orientation,
|
||
|
|
but it also mixed repository integration, cross-domain information flow, and
|
||
|
|
several domain-specific projections in one service.
|
||
|
|
|
||
|
|
A broader Inter-Hub framework was then attempted in Haskell/IHP. Its concepts—
|
||
|
|
domain hubs, manifests, widgets, events, and an operator surface—were useful,
|
||
|
|
but its implementation and build path were too specialized. A Python/FastAPI
|
||
|
|
replacement named `core-hub` was subsequently deployed, while a reusable
|
||
|
|
library named `hub-core` was extracted from State Hub. The resulting three-way
|
||
|
|
division worked technically but left confusing names and no complete extension
|
||
|
|
or information-architecture model.
|
||
|
|
|
||
|
|
In August 2026 the direction was reset:
|
||
|
|
|
||
|
|
1. consolidate and retire `core-hub` into the surviving `hub-core` framework;
|
||
|
|
2. make hub-core the cross-domain control and interaction plane;
|
||
|
|
3. establish domain hubs around explicit Orthogonal Architecture concerns;
|
||
|
|
4. retire State Hub rather than rename its remainder as another hub; and
|
||
|
|
5. extract repository integration into a dedicated functional component.
|
||
|
|
|
||
|
|
## Why observation and control stay together
|
||
|
|
|
||
|
|
An early formulation separated `repo-state` from `repo-control`. This was
|
||
|
|
rejected. Both concern the same boundary: connecting a repository that must
|
||
|
|
remain perfectly viable on its own to HelixForge.
|
||
|
|
|
||
|
|
Repo Manager therefore owns both:
|
||
|
|
|
||
|
|
- the evidence-backed representation of repository state; and
|
||
|
|
- governed actions that intentionally change repository-owned records.
|
||
|
|
|
||
|
|
These remain internally separable modules, but not independent ecosystem
|
||
|
|
authorities.
|
||
|
|
|
||
|
|
## Agent representation
|
||
|
|
|
||
|
|
Repo Manager is more than a Git inventory. Each repository obtains a
|
||
|
|
representation inside HelixForge and may be assigned coach, lead, and director
|
||
|
|
agents. These roles help orient work, maintain quality and alignment, coordinate
|
||
|
|
dependencies, and escalate decisions. Their actions remain constrained by
|
||
|
|
repository policy, hub-core identity and authorization, and normal review
|
||
|
|
mechanisms.
|
||
|
|
|
||
|
|
## Relationship to the information architecture
|
||
|
|
|
||
|
|
Repository facts are only one part of HelixForge information flow. Users,
|
||
|
|
agents, services, domains, work, conversations, knowledge, telemetry, and costs
|
||
|
|
also need stable identity and communication. Cross-entity messaging and
|
||
|
|
interaction therefore belong to hub-core and its supporting components, not to
|
||
|
|
Repo Manager.
|
||
|
|
|
||
|
|
Repo Manager publishes repository facts and accepts repository commands through
|
||
|
|
those shared contracts. It should not connect directly to every domain hub or
|
||
|
|
functional service.
|
||
|
|
|
||
|
|
## Migration source
|
||
|
|
|
||
|
|
Useful State Hub implementation should be extracted rather than rewritten
|
||
|
|
blindly. Candidate source capabilities include:
|
||
|
|
|
||
|
|
- managed repository and host-path registration;
|
||
|
|
- repository file discovery;
|
||
|
|
- workplan and task parsing;
|
||
|
|
- consistency and reconciliation tooling;
|
||
|
|
- repository dependency and goal projections;
|
||
|
|
- controlled file-backed status transitions; and
|
||
|
|
- idempotency and local outbox patterns.
|
||
|
|
|
||
|
|
Cross-domain messages, general progress telemetry, capability federation,
|
||
|
|
scheduling, and domain projections are intentionally excluded from the new
|
||
|
|
component.
|