tegwick
e3fbdbc148
Strengthen Intent and Scope for State Hub registration and HelixForge boundaries; mark foundation workplan active. Classification synced via register-from-classification (do not re-run statehub register bootstrap — it collides with RMGR-WP-0001).
6.1 KiB
| domain | repo | repo_flavor | updated | parent_project |
|---|---|---|---|---|
| infotech | repo-manager | tooling | 2026-08-09 | prj-state-hub-retirement |
INTENT
Why
repo-managerexists, where its authority begins and ends, and how it relates to hub-core, State Hub retirement, and ordinary repositories.
One-line intent
Repo Manager is the HelixForge repository integration boundary: it represents repositories, indexes repository-owned records, reconciles drift, and applies governed repository changes without making repos dependent on HelixForge internals.
Why it exists
HelixForge must work with many repositories. Each repository must stay coherent, inspectable, buildable, and governable on its own. At the same time, HelixForge needs a trustworthy representation of the repository, its declared work, relationships, condition, and the agents that help it evolve.
Repo Manager is that boundary. It combines observation and governed control because they share one authority, policy, identity, and audit surface: a component that only observes cannot safely reconcile; a component that mutates without an evidence-backed model is unsafe.
It is established as part of State Hub retirement
(prj-state-hub-retirement): repository registration, host paths, workplan
file indexing, consistency reconciliation, and file-backed status writeback
move here from State Hub. Cross-domain messaging, projections, and hub
composition move to hub-core, not here.
Governing principle
The repository remains authoritative for repository-owned records.
Repo Manager discovers, validates, indexes, relates, and—when explicitly authorized—changes those records. Database rows are projections and operational indexes, not replacements for Git or repository files. Indexes must be rebuildable from authoritative inputs.
What it is
| Area | Responsibility |
|---|---|
| Repository registry | Identity, classification, lifecycle, remotes, checkouts, host paths |
| Record indexing | Workplans, tasks, decisions, and other file-backed work records |
| Consistency | Detect and reconcile file ↔ projection drift |
| Governed mutation | Explicit commands with policy checks, evidence, and Git outcomes |
| Agent roles | Coach / lead / director assignment for a repository (not hub-wide inbox) |
| Hub-core port | Emit normalized repository and work-record facts; accept addressing via contracts |
What it is not
| Concern | Owner |
|---|---|
| Cross-domain messages, conversations, routing | hub-core |
| Domain hub composition / extension registry | hub-core |
| Progress/orientation projections across domains | hub-core |
| Schedules, ops-run execution, event-triggered jobs | activity-core |
| Non-repo issues | issue-core |
| AuthN / user directory | identity authorities |
| AuthZ decisions | flex-auth (or successor) |
| Secrets | OpenBao / credential custody |
| Git hosting | Forgejo (or other forge) |
Temporary project coordination (prj-*) |
project repos + their GOAL.md |
| Legacy mixed coordination service | state-hub (until retirement gates) |
Repo Manager is a functional component, not a domain hub (Orthogonal Architecture / SHR hub-extension taxonomy).
Repository representation
Every managed repository may be represented with:
- stable identity, ownership, purpose, classification, and lifecycle;
- local checkouts, remotes, revisions, branches, and sync state;
- declared workplans, tasks, decisions, capabilities, services, and policies;
- relationships to other repositories and external authorities;
- health, maturity, drift, risk, and attention signals (derived);
- coach / lead / director agent assignments;
- accepted commands and outcome evidence.
Agent roles represent the repository inside HelixForge. They do not supersede human ownership, code review, repository policy, or authorization controls.
Ecosystem position
repositories (Git + files)
▲
│ observe / governed command
▼
repo-manager ──port.repo / port.work──► hub-core
│ │
│ ├── domain hubs
│ └── agents / MCP
└── extracts from state-hub (retirement)
- hub-core addresses repositories through versioned contracts, not SQL.
- Domain hubs consume repository projections via hub-core.
- State Hub remains operational until cutover; new permanent repo-authority features should land here (or as dual-run adapters), not as State Hub growth.
Architecture references (project-owned until promoted):
prj-state-hub-retirement/architecture/information-model_v0.1.mdprj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.mdprj-state-hub-retirement/architecture/child-workplan-map_v0.1.md(stream S1)
What success looks like
A repository joins HelixForge by declaring ordinary versioned files and registration metadata. Repo Manager can then:
- identify and locate it;
- explain purpose, ownership, relationships, and current state;
- validate and index repository-owned records;
- assign and expose its agent representation;
- emit changes through stable hub-core contracts;
- accept an authorized command and apply it with auditable Git evidence;
- recover or rebuild projections from repository sources.
No repository should require direct connections to every HelixForge service to participate.
Design values
- Repository autonomy — usable outside HelixForge.
- Files and Git as evidence — intent and work remain inspectable.
- Observation and action together — one boundary for read and write.
- Governed mutation — explicit, scoped, reviewable, idempotent where possible.
- Contract isolation — no foreign consumers on persistence models.
- Graceful degradation — hub outage must not corrupt the repository.
- Replaceable projections — rebuild from authority.
Genesis
Recorded in history/2026-08-09-genesis.md. Implementation workplan:
RMGR-WP-0001 (parent project SHR-WP-0001).