tegwick
754d02f40e
Document how State Hub registers, resolves, reconciles, and mutates repos; blueprint Stage B dual-run toward retirement; open workplan for SH adapter writeback/reconcile without non-retirement refactors.
194 lines
7.2 KiB
Markdown
194 lines
7.2 KiB
Markdown
# Architecture Blueprint — Repo Manager toward State Hub retirement
|
||
|
||
**Status:** draft-for-execution
|
||
**Date:** 2026-08-09
|
||
**Owner:** repo-manager
|
||
**Parent program:** `prj-state-hub-retirement`
|
||
**Inputs:**
|
||
`history/2026-08-09-state-hub-repo-tooling-research.md`,
|
||
RMGR-WP-0001 docs (REP/CMD/EXTRACT/ADR-001),
|
||
project IA + hub-extension architecture
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
Define the **target shape** of repository integration so State Hub can stop
|
||
owning checkouts, and so we do **not** spend the next cycle on opportunistic
|
||
refactors. Improvements are only in scope when they shorten the retirement path.
|
||
|
||
---
|
||
|
||
## 2. North star
|
||
|
||
```text
|
||
Agents / automation
|
||
│
|
||
│ hub-core ports (MCP gateway, REST)
|
||
▼
|
||
┌─────────────┐ port.repo / port.work ┌────────────────┐
|
||
│ hub-core │ ─────────────────────────────► │ repo-manager │
|
||
│ projections │ │ (this service)│
|
||
└─────────────┘ └────────┬───────┘
|
||
│
|
||
observe / reconcile /
|
||
governed writeback
|
||
│
|
||
▼
|
||
Git repositories
|
||
(file authority)
|
||
```
|
||
|
||
**Invariants (non-negotiable):**
|
||
|
||
1. Files + Git remain authoritative for repo-owned work.
|
||
2. Repo Manager owns **registry, path resolution, parse, reconcile, writeback**.
|
||
3. Hub-core owns **messages, progress, cross-domain orientation**.
|
||
4. activity-core owns **schedules**; it must not embed repo parsers.
|
||
5. No new permanent repo-mutation logic lands in State Hub.
|
||
|
||
---
|
||
|
||
## 3. Current state (after RMGR-WP-0001)
|
||
|
||
| Layer | Today | Gap to retirement |
|
||
| --- | --- | --- |
|
||
| Docs / contracts | Representation, commands, extraction inventory, ADR-001 | OK |
|
||
| CLI vertical slice | observe / reconcile / update-task-status + git evidence | Not production path |
|
||
| Projection store | Local JSON `.repo-manager/index.json` | Not fleet Postgres index |
|
||
| HTTP API | None | Agents still hit State Hub |
|
||
| C-rules / push-seal | State Hub only | Fleet still depends on SH |
|
||
| Dual-run facade | None | Cannot cut MCP without break |
|
||
| Strangler metrics | Legacy meters exist for workstream routes | Need “checkout mutator” meter |
|
||
|
||
---
|
||
|
||
## 4. Target architecture (improved infrastructure)
|
||
|
||
### 4.1 Components
|
||
|
||
| Component | Responsibility | Deploy |
|
||
| --- | --- | --- |
|
||
| **repo-manager API** | `helixforge.repo-manager` 0.1 HTTP | k8s service + Postgres |
|
||
| **rmgr CLI** | Operator/agent local: reconcile, register path, commands | installed via uv/pip |
|
||
| **consistency package** | Ported C-rules (minus inbox) + push-seal | library inside RM |
|
||
| **SH compatibility adapter** | Temporary: SH MCP/REST → RM commands | process in SH or sidecar |
|
||
| **activity-core caller** | Sweep invokes RM reconcile HTTP | schedule only |
|
||
|
||
### 4.2 Data planes
|
||
|
||
| Data | Authority | Store |
|
||
| --- | --- | --- |
|
||
| Workplans/tasks/decisions | Git files | index in **RM Postgres** |
|
||
| Classification | `.repo-classification.yaml` | cache on managed_repos |
|
||
| host_paths | operator | **RM Postgres** (migrate from SH) |
|
||
| Command idempotency | RM | RM Postgres |
|
||
| Progress/messages | hub-core | hub-core DB |
|
||
| Orientation summaries | derived | hub-core projection (reads RM + messages) |
|
||
|
||
### 4.3 Strangler stages (retirement, not polish)
|
||
|
||
```text
|
||
Stage A SH still mutates checkouts; RM slice is shadow (observe-only in prod)
|
||
Stage B SH MCP update_task_status + fix-consistency call RM for writeback
|
||
when feature flag on (dual-run); SH index still updated
|
||
Stage C RM registry is SoR for host_paths; SH reads RM or shared read model
|
||
Stage D Agents point MCP at hub-core/RM; SH receives zero checkout mutations
|
||
Stage E SH repo routes 410/retired; SH process only until full hub retirement
|
||
```
|
||
|
||
**Exit criterion for “repo extraction done” (G-RMGR subset):**
|
||
During a stabilization window, **no State Hub process performs git write or
|
||
workplan file patch** on fleet checkouts (metered).
|
||
|
||
### 4.4 What we deliberately improve (only if it enables A→E)
|
||
|
||
| Improvement | Why retirement needs it |
|
||
| --- | --- |
|
||
| Single parser module in RM | Dual SH parsers would diverge during dual-run |
|
||
| Feature-flagged SH adapter | Zero-downtime cut of agent write path |
|
||
| Meter: `checkout_mutation_source=sh|rm` | Prove Stage D |
|
||
| Neutral UUID field names (accept `state_hub_*` still) | Avoid rewrite of entire fleet frontmatter mid-cut |
|
||
|
||
### 4.5 What we defer (not next)
|
||
|
||
- Full FastMCP surface parity with SH
|
||
- SBOM/TPSC/DoI productization inside RM
|
||
- Dashboard rewrite
|
||
- Topic spine cleanup beyond “don’t depend on it”
|
||
- Perfect policy-port integration (dev allowlist OK until hub-core ready)
|
||
- Premature monorepo packaging
|
||
|
||
---
|
||
|
||
## 5. Agent write-path target (detail)
|
||
|
||
**Today (simplified):**
|
||
|
||
```text
|
||
MCP update_task_status → SH PATCH /tasks → DB
|
||
→ later fix-consistency writeback → git commit → push-seal
|
||
```
|
||
|
||
**Target Stage B:**
|
||
|
||
```text
|
||
MCP update_task_status → SH facade (flag)
|
||
→ RM command repo.work.update_task_status
|
||
→ file patch + git_sha evidence
|
||
→ SH/RM index refresh
|
||
→ optional hub-core progress event (correlation_id)
|
||
```
|
||
|
||
**Target Stage D:**
|
||
|
||
```text
|
||
MCP (hub-core or RM) → RM command only
|
||
→ hub-core progress
|
||
→ no SH checkout I/O
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Fleet reconcile target
|
||
|
||
**Today:** `POST /consistency/sweep/remote-all` → SH runs consistency_check on each host path.
|
||
|
||
**Target:** activity-core schedule → `POST {repo-manager}/v1/reconcile/fleet` or per-repo `repo.reconcile` with same C-rule semantics (inbox rules excluded; messaging stays hub-core).
|
||
|
||
SH may keep a **deprecated proxy** until Stage D.
|
||
|
||
---
|
||
|
||
## 7. Risks if we “improve” instead of strangling
|
||
|
||
| Distraction | Retirement cost |
|
||
| --- | --- |
|
||
| Rebuild full SH MCP in RM first | Months before any traffic moves |
|
||
| Perfect domain model without dual-run | SH remains mutator forever |
|
||
| Shared SH database “temporarily” | Cutover never clean; authority muddied |
|
||
| Big-bang registry migration | Path resolution breaks multi-host workers |
|
||
|
||
---
|
||
|
||
## 8. Success metrics
|
||
|
||
| Metric | Stage B | Stage D |
|
||
| --- | --- | --- |
|
||
| % task status writes with RM git_sha evidence | > 0 experimental host | 100% agent path |
|
||
| SH checkout file patches / day | declining | 0 |
|
||
| Fleet remote-all failures | ≤ baseline | ≤ baseline |
|
||
| Agent session breakage | none material | none material |
|
||
|
||
---
|
||
|
||
## 9. Immediate execution focus
|
||
|
||
The **next workplan** implements **Stage B for one command path** and
|
||
**shadow reconcile**, not infrastructure cosmetics:
|
||
|
||
→ **RMGR-WP-0002** — Retirement dual-run: SH adapter for task status writeback + reconcile proxy.
|
||
|
||
That is the shortest path to State Hub **no longer being required to touch Git**
|
||
for the highest-frequency agent mutation, which unlocks STATE-WP-0079 slices
|
||
and G-RMGR evidence.
|