repo-manager/INTENT.md

domain	repo	updated
infotech	repo-manager	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.