Seed Repo Manager foundation

history/2026-08-09-genesis.md

@@ -0,0 +1,84 @@
+# 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.