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: active
owner: codex
topic_slug: repo-manager
created: "2026-08-09"
updated: "2026-08-09"
state_hub_workstream_id: "e32a9d49-a38f-4117-8e37-1c66afe1dad1"
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: "43468b5c-f49f-43c3-bf30-922fadc1f8c0"
```

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: "2453316f-33f4-41d0-bcb5-c7552db88d68"
```

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: todo
priority: high
state_hub_task_id: "deee10be-25e1-4ee7-b47e-93dc816916c9"
```

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.

## Select the implementation foundation

```task
id: RMGR-WP-0001-T04
status: todo
priority: medium
state_hub_task_id: "0a041f4e-09fc-4f69-8a48-ac396186bc8f"
```

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

## Prove one repository end to end

```task
id: RMGR-WP-0001-T05
status: todo
priority: high
state_hub_task_id: "5036a248-1c47-423f-be8d-4fd232896c31"
```

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.

## 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)
- [ ] State Hub extraction candidates have dispositions.
- [ ] The implementation foundation has a recorded decision.
- [ ] One repository completes the end-to-end vertical slice.