101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
---
|
|
domain: infotech
|
|
repo: repo-manager
|
|
updated: "2026-08-09"
|
|
---
|
|
|
|
# Intent
|
|
|
|
## Why Repo Manager exists
|
|
|
|
HelixForge needs to work with many repositories without making those
|
|
repositories dependent on HelixForge internals. A repository must remain
|
|
coherent, inspectable, buildable, and governable on its own. At the same time,
|
|
HelixForge needs a trustworthy representation of the repository, its declared
|
|
work, its relationships, its current condition, and the agents responsible for
|
|
helping it evolve.
|
|
|
|
Repo Manager is that integration boundary.
|
|
|
|
It combines repository observation and governed repository control because
|
|
they are inseparable parts of the same responsibility. A component that can
|
|
observe repository state but cannot safely reconcile it is incomplete; a
|
|
component that changes repositories without maintaining an evidence-backed
|
|
model of their state is unsafe.
|
|
|
|
## Governing principle
|
|
|
|
**The repository remains authoritative for repository-owned records.**
|
|
|
|
Repo Manager discovers, validates, indexes, relates, and—when explicitly
|
|
authorized—changes those records. Its database representations are projections
|
|
and operational indexes, not replacements for Git or repository files.
|
|
|
|
## Repository representation
|
|
|
|
Every managed repository receives a durable HelixForge representation that can
|
|
include:
|
|
|
|
- stable identity, ownership, purpose, classification, and lifecycle;
|
|
- local checkouts, remotes, revisions, branches, and synchronization state;
|
|
- declared workplans, tasks, decisions, capabilities, services, and policies;
|
|
- relationships to other repositories and external authorities;
|
|
- health, maturity, drift, risk, and attention signals;
|
|
- an assigned agent representation, including coach, lead, and director roles;
|
|
- commands the repository accepts and evidence of their outcomes.
|
|
|
|
The agent roles represent the repository in HelixForge. They do not supersede
|
|
human ownership, repository policy, code review, or authorization controls.
|
|
|
|
## Ecosystem position
|
|
|
|
Repo Manager is a functional component used by `hub-core`. It is not a domain
|
|
hub and does not own cross-domain communication.
|
|
|
|
- `hub-core` owns cross-domain identity, addressing, messaging, interaction,
|
|
projections, telemetry, policy integration, and domain-hub composition.
|
|
- Repo Manager owns the repository integration boundary and emits normalized
|
|
repository and work-record facts to hub-core.
|
|
- Domain hubs consume repository projections through hub-core rather than
|
|
importing Repo Manager internals.
|
|
- Specialized authorities such as `activity-core`, `issue-core`, identity
|
|
services, and credential systems continue to own their respective execution
|
|
and data boundaries.
|
|
|
|
## What success looks like
|
|
|
|
A repository can join HelixForge by declaring ordinary, versioned files and
|
|
registration metadata. Repo Manager can then:
|
|
|
|
1. identify and locate it;
|
|
2. explain its purpose, ownership, relationships, and current state;
|
|
3. validate and index its repository-owned records;
|
|
4. assign and expose its agent representation;
|
|
5. emit changes through stable hub-core contracts;
|
|
6. accept an authorized command and apply it with auditable Git evidence;
|
|
7. recover or rebuild its projections from repository sources.
|
|
|
|
No repository should require direct connections to every HelixForge service or
|
|
library to participate.
|
|
|
|
## Design values
|
|
|
|
- **Repository autonomy:** integration must not make a repository unusable
|
|
outside HelixForge.
|
|
- **Files and Git as evidence:** repository-owned intent and work remain
|
|
inspectable and recoverable.
|
|
- **Observation and action together:** reads and writes share one authority,
|
|
policy, identity, and audit boundary.
|
|
- **Governed mutation:** changes are explicit, scoped, reviewable, and
|
|
idempotent where possible.
|
|
- **Contract isolation:** other components integrate through stable contracts,
|
|
not Repo Manager database models.
|
|
- **Graceful degradation:** temporary hub or network failure must not corrupt a
|
|
repository or erase pending evidence.
|
|
- **Replaceable projections:** indexes can be rebuilt from authoritative inputs.
|
|
|
|
## Genesis
|
|
|
|
Repo Manager originates in the retirement design for the legacy `state-hub`.
|
|
The detailed rationale and architectural lineage are recorded in
|
|
`history/2026-08-09-genesis.md`.
|