repo-manager/INTENT.md

---
domain: infotech
repo: repo-manager
repo_flavor: tooling
updated: "2026-08-09"
parent_project: prj-state-hub-retirement
---

# INTENT

> Why `repo-manager` exists, 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

```text
 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.md`
- `prj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.md`
- `prj-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:

1. identify and locate it;
2. explain purpose, ownership, relationships, and current state;
3. validate and index 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 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`).