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:

consolidate and retire core-hub into the surviving hub-core framework;
make hub-core the cross-domain control and interaction plane;
establish domain hubs around explicit Orthogonal Architecture concerns;
retire State Hub rather than rename its remainder as another hub; and
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.

3.6 KiB Raw Blame History