tegwick
8b5634ff2a
Implement observe/reconcile/update-task-status CLI path: workplan parse, JSON projection index, git-backed task status writeback with correlation events, and E2E pytest plus evidence artifacts. Finish foundation workplan.
131 lines
4.4 KiB
Markdown
131 lines
4.4 KiB
Markdown
---
|
||
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: "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: done
|
||
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.
|
||
|
||
**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: "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.
|
||
|
||
**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: "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.
|
||
|
||
**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.
|