repo-manager/workplans/RMGR-WP-0001-foundation.md

---
id: RMGR-WP-0001
type: workplan
title: "Repo Manager architecture and foundation"
domain: infotech
repo: repo-manager
status: finished
owner: codex
topic_slug: repo-manager
created: "2026-08-09"
updated: "2026-08-09"
state_hub_workstream_id: "5409d164-36da-54c8-8d79-6577a23268ce"
parent_project: prj-state-hub-retirement
parent_workplan: SHR-WP-0001
stream: S1
related:
  - SHR-ARCH-IA-0001
  - SHR-INV-0001
  - HUB-WP-0004
  - STATE-WP-0079
---

# Repo Manager architecture and foundation

## Goal

Turn the repository genesis and scope into an implementable contract and first
vertical slice, coordinated by the State Hub retirement project
(`prj-state-hub-retirement` / SHR-WP-0001 stream **S1**). See project map:
`architecture/child-workplan-map_v0.1.md`.

## Define the repository representation

```task
id: RMGR-WP-0001-T01
status: done
priority: high
state_hub_task_id: "64adbb6b-7f15-52c0-bd2c-f946e1b7b904"
```

Specify stable repository identity, locations, revisions, classifications,
declared records, relationships, health, lifecycle, and coach/lead/director
agent assignments. Identify which fields are authoritative in the repository
and which are replaceable projections.

**Result (2026-08-09):** `docs/repository-representation_v0.1.md` + YAML
catalog (RMGR-ARCH-REP-0001). Authority vs projection per field family; declared
records; signals; agent roles; State Hub `managed_repos` column map for T03.

## Define observation and command contracts

```task
id: RMGR-WP-0001-T02
status: done
priority: high
state_hub_task_id: "641dc63f-a0a2-5dcc-b325-b8d9172fc53c"
```

Define normalized repository facts, governed commands, authorization context,
idempotency, correlation, evidence, failure behavior, and hub-core integration
without exposing persistence models.

**Result (2026-08-09):** `docs/observation-command-contracts_v0.1.md` + YAML
(`helixforge.repo-manager` 0.1 / RMGR-ARCH-CMD-0001). Observation ops, command
catalog, scopes, evidence, failures, events, hub-core port.repo/work mapping.
Runtime OpenAPI deferred to T04/T05.

## Inventory extraction candidates

```task
id: RMGR-WP-0001-T03
status: done
priority: high
state_hub_task_id: "11e32753-5c32-5e92-98c2-5d9bbc28b059"
```

Map relevant State Hub repository registration, host-path, workplan parsing,
consistency, reconciliation, dependency, file-mutation, and outbox behavior to
keep/adapt/replace/retire dispositions with compatibility tests.

**Result (2026-08-09):** `docs/state-hub-extraction-inventory_v0.1.md` + YAML
(RMGR-INV-EXTRACT-0001). Module candidates E-REG/PATH/PARSE/C/WR/DEP/JOB/OUT;
inbox C-rules retired from RM; phases P0–P5; compat suites T-PARSE…T-DUAL-RUN.

## Select the implementation foundation

```task
id: RMGR-WP-0001-T04
status: done
priority: medium
state_hub_task_id: "cfd36624-6f47-5fe0-90de-6bf1fa9d4006"
```

Choose the runtime, persistence, package, migration, test, and deployment shape
consistent with the ordinary HelixForge platform. Record the decision before
substantial implementation.

**Result (2026-08-09):** ADR-001 `docs/adr-001-implementation-foundation.md` —
Python 3.12, FastAPI/uvicorn, Postgres+SQLAlchemy async+Alembic (own DB),
src/repo_manager, uv/hatchling, pytest-asyncio, Docker later; CLI `rmgr`
skeleton. Package scaffold + version test landed (no business logic yet).

## Prove one repository end to end

```task
id: RMGR-WP-0001-T05
status: done
priority: high
state_hub_task_id: "1144b02a-5d3f-544e-9c02-d14f1df10140"
```

Register and represent one independently valid repository, index its declared
work, emit a normalized change through hub-core contracts, apply one authorized
file-backed transition, and prove the resulting Git evidence and rebuilt
projection.

**Result (2026-08-09):** Vertical slice implemented — `rmgr observe|reconcile|
update-task-status`. Parser, JSON projection (`.repo-manager/index.json`),
git-backed writeback with required `evidence.git_sha`, contract-shaped events.
Proof: `pytest tests/test_e2e_vertical_slice.py` + `docs/evidence/t05-*`.
Limits: local JSON index (not Postgres yet); hub-core HTTP emit deferred;
authz not enforced on CLI.

## Acceptance

- [x] The authority and data model are explicit.
- [x] Observation and command contracts are versioned and testable.
  - (semantics + catalog done; automated suite with runtime in T04/T05)
- [x] State Hub extraction candidates have dispositions.
- [x] The implementation foundation has a recorded decision.
- [x] One repository completes the end-to-end vertical slice.