# repo-manager

Repository integration boundary for the HelixForge agentic software development
and operations environment.

Repositories remain independently valid and usable. Repo Manager gives each
repository a stable representation inside HelixForge, observes its declared
state, performs governed repository changes, and hosts its coach/lead/director
agent representation.

| | |
| --- | --- |
| **Flavor** | tooling (not a domain hub) |
| **Domain** | infotech |
| **Parent project** | [prj-state-hub-retirement](../prj-state-hub-retirement) |
| **Foundation WP** | [RMGR-WP-0001](workplans/RMGR-WP-0001-foundation.md) |

Start with [INTENT.md](INTENT.md), [SCOPE.md](SCOPE.md), and the
[genesis record](history/2026-08-09-genesis.md).

Architecture:

- [Repository representation v0.1](docs/repository-representation_v0.1.md)
- [Observation and command contracts v0.1](docs/observation-command-contracts_v0.1.md)
- [State Hub extraction inventory v0.1](docs/state-hub-extraction-inventory_v0.1.md)
- [ADR-001 Implementation foundation](docs/adr-001-implementation-foundation.md)
- [Railiance app deployment guide](docs/RailianceAppDeploymentGuide.md) (`RMGR-WP-0006`)
- [Repository standards v0.1](docs/repository-standards_v0.1.md) (`RMGR-WP-0004`)
- [Repository registers v0.1](docs/repository-registers_v0.1.md) (`RMGR-WP-0008`)

```bash
make install   # or: uv pip install -e ".[dev]"
make test
rmgr --version
rmgr observe --path .
rmgr reconcile --path .
rmgr update-task-status --path . --task-id <ID> --status progress
rmgr workplan create --path . --workplan-id EX-WP-0001 --title "Example" --goal "Deliver X."
rmgr workplan update --path . --workplan-id EX-WP-0001 --status active
rmgr workplan delete --path . --workplan-id EX-WP-0001 --confirm  # archives; never erases
rmgr task add --path . --workplan-id EX-WP-0001 --title "Implement" --description "Deliver it."
rmgr task update --path . --task-id EX-WP-0001-T01 --status progress
rmgr adhoc add --path . --title "Small fix" --description "Complete the bounded fix."
rmgr sync --path . --push  # primary/railiance01 derives the exact pushed commit
rmgr register put --path . --kind technical-debt --entry-id TD-001 \
  --title "Debt item" --data-json '{"severity":"high"}'
rmgr register list --path . --kind technical-debt
rmgr rapp wrap --path ../rapp-some-app --app some-app \
  --ownership-repo some-app --from-app ../some-app
rmgr rapp validate --path ../rapp-user-engine --family-root ..
rmgr rapp place --path ../rapp-some-app --reef reef-railiance
rmgr conform --path .
rmgr prefix-uniqueness --root ..
rmgr scaffold --path ../prj-example --flavor project --wp-prefix EX-WP --no-commit
rmgr scaffold --path . --refresh-hub-access --no-commit  # State Hub access table from config/state-hub-access.yaml
```

`rmgr sync` is the normal work-record closeout path. It uses the canonical kind
registry, fills only missing deterministic UUIDv5 identifiers, refuses dirty or
behind workplan sources, verifies that the API is `primary/railiance01`, and
requests one central forge-derived reconciliation. A local/cache State Hub is
never populated. `registrar-reconcile` remains only for sealed legacy UUID
migration and repair.

Vertical-slice proof: [docs/evidence/t05-vertical-slice.md](docs/evidence/t05-vertical-slice.md).

Direction:

- [State Hub repo tooling research](history/2026-08-09-state-hub-repo-tooling-research.md)
- [Architecture blueprint (retirement path)](specs/ArchitectureBlueprint.md)
- Dual-run: [docs/dual-run.md](docs/dual-run.md) · [RMGR-WP-0002](workplans/RMGR-WP-0002-retirement-dual-run-strangler.md)