repo-manager/specs/ArchitectureBlueprint.md

# 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.