docs: research SH repo tooling, architecture blueprint, RMGR-WP-0002
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.
This commit is contained in:
parent
77bd79c153
commit
754d02f40e
4 changed files with 613 additions and 0 deletions
194
specs/ArchitectureBlueprint.md
Normal file
194
specs/ArchitectureBlueprint.md
Normal file
|
|
@ -0,0 +1,194 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue