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

  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)

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`
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):

MCP update_task_status → SH PATCH /tasks → DB
  → later fix-consistency writeback → git commit → push-seal

Target Stage B:

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:

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.