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
|
|
@ -35,3 +35,9 @@ rmgr update-task-status --path . --task-id <ID> --status progress
|
|||
```
|
||||
|
||||
Vertical-slice proof: [docs/evidence/t05-vertical-slice.md](docs/evidence/t05-vertical-slice.md).
|
||||
|
||||
Direction:
|
||||
|
||||
- [State Hub repo tooling research](history/2026-08-09-state-hub-repo-tooling-research.md)
|
||||
- [Architecture blueprint (retirement path)](specs/ArchitectureBlueprint.md)
|
||||
- Next: [RMGR-WP-0002](workplans/RMGR-WP-0002-retirement-dual-run-strangler.md) dual-run strangler
|
||||
|
|
|
|||
280
history/2026-08-09-state-hub-repo-tooling-research.md
Normal file
280
history/2026-08-09-state-hub-repo-tooling-research.md
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
# Research: How State Hub interacts with repositories
|
||||
|
||||
**Recorded:** 2026-08-09
|
||||
**Audience:** Repo Manager + State Hub retirement
|
||||
**Sources:** `state-hub` checkout (API, scripts, MCP, Makefile, docs), activity-core consumers, prior RM extraction inventory
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive summary
|
||||
|
||||
State Hub is the **live index and agent coordination surface** for fleet
|
||||
repositories. It does **not** own Git truth. It:
|
||||
|
||||
1. **Registers** repos (slug, domain, classification, host paths, remotes).
|
||||
2. **Resolves** a checkout on the current machine via `host_paths` / `local_path`.
|
||||
3. **Parses** file-backed work records (workplans, tasks, and related kinds).
|
||||
4. **Reconciles** files ↔ Postgres with ADR-001 (“file wins”) via
|
||||
`consistency_check` / `statehub fix-consistency`.
|
||||
5. **Mutates files** for selected status writebacks (API reconciliation path +
|
||||
fix-consistency writeback), then **git commit + push-seal**.
|
||||
6. **Serves** agents (MCP/REST) and automation (activity-core sweep, SBOM, DoI).
|
||||
|
||||
Repo Manager’s job is to take over (1)–(5) as the repository boundary while
|
||||
hub-core keeps messaging, progress, and cross-domain projections.
|
||||
|
||||
---
|
||||
|
||||
## 2. Interaction model (as-built)
|
||||
|
||||
```text
|
||||
Agents (Claude/Codex) activity-core Operators
|
||||
│ │ │
|
||||
│ MCP / REST │ GET /repos/ │ make / CLI
|
||||
│ update_task_status │ POST sweep │ register-path
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────┐
|
||||
│ State Hub API │
|
||||
│ /repos /workplans /tasks │
|
||||
│ /reconciliation /consistency │
|
||||
│ /progress /messages … │
|
||||
└───────────────┬─────────────────┘
|
||||
│ Postgres (index)
|
||||
┌───────────────┴─────────────────┐
|
||||
│ resolve_repo_path(host_paths) │
|
||||
│ parse workplans/*.md │
|
||||
│ writeback + git commit/push │
|
||||
└───────────────┬─────────────────┘
|
||||
▼
|
||||
Git checkouts on hosts
|
||||
(workstation, railiance01, …)
|
||||
```
|
||||
|
||||
**Authority:** repository files + Git history.
|
||||
**Hub DB:** rebuildable cache/index.
|
||||
**Operator config:** `host_paths` (not in Git).
|
||||
|
||||
---
|
||||
|
||||
## 3. Registration and classification tooling
|
||||
|
||||
| Tool | Entry | What it does |
|
||||
| --- | --- | --- |
|
||||
| REST `POST/GET/PATCH /repos/` | API | CRUD `managed_repos` |
|
||||
| `POST /repos/{slug}/paths` | API / `make register-path` | Set `host_paths[hostname]=path` |
|
||||
| `POST /repos/onboard` | API | Onboarding helper |
|
||||
| `scripts/register_from_classification.py` | `make register-from-classification` | Upsert from `.repo-classification.yaml` |
|
||||
| `statehub register` / `register-project` | CLI / make | Scaffold INTENT/AGENTS, register, optional seed WP |
|
||||
| `list_domain_repos` / `list_repos_by_classification` | MCP | Discovery |
|
||||
| `register_repo` / `register_repo_from_classification` / `update_repo_path` | MCP | Agent registration |
|
||||
|
||||
**Classification spine:** committed `.repo-classification.yaml` (category,
|
||||
domain, tags, business fields). Canon allowed vocab in the-custodian.
|
||||
Domain FK on `managed_repos` derived from primary domain.
|
||||
|
||||
**Multi-host:** each machine registers its checkout path. Consistency uses
|
||||
`host_paths[current_hostname]` then falls back to `local_path`.
|
||||
|
||||
**Pitfall observed:** `statehub register` seeds a bootstrap workplan with a
|
||||
generic `REPO-WP-0001` style id; if a real WP already uses that prefix, **id
|
||||
collision** occurs (seen on repo-manager). Prefer classification register +
|
||||
hand-authored workplans for mature repos.
|
||||
|
||||
---
|
||||
|
||||
## 4. Work-record loop (files ↔ index)
|
||||
|
||||
### 4.1 File conventions
|
||||
|
||||
- `workplans/<PREFIX>-WP-NNNN-*.md` with YAML frontmatter + ````task` blocks.
|
||||
- Hub UUIDs written back as `state_hub_workstream_id` / `state_hub_task_id`.
|
||||
- Generated `WORK-RECORDS.md` and `.custodian-brief.md` (fix-consistency).
|
||||
- Other kinds: intakes/decisions/register entries (C-31/C-32 registration).
|
||||
|
||||
### 4.2 Read path (agents)
|
||||
|
||||
| Action | Typical path |
|
||||
| --- | --- |
|
||||
| Orient | `get_domain_summary` / `GET /state/summary` |
|
||||
| List work | `list_workplans` / `GET /workplans/?…` |
|
||||
| List tasks | `list_tasks` / `GET /tasks/?workplan_id=` |
|
||||
| Brief offline | `.custodian-brief.md` in each repo |
|
||||
|
||||
### 4.3 Write path (status)
|
||||
|
||||
| Action | Path | File effect |
|
||||
| --- | --- | --- |
|
||||
| MCP `update_task_status` | REST PATCH task | May go DB-first then consistency writeback |
|
||||
| API reconciliation | `api/routers/reconciliation.py` | Classifies write-through vs deferred; may patch file via `workplan_files` |
|
||||
| `statehub fix-consistency --fix` | `scripts/consistency_check.py` | File↔DB drift repair; optional git writeback commit |
|
||||
| Push seal | `scripts/repo_sync.py` | After fix commits: pull-ff gates + push so local≡remote |
|
||||
|
||||
**Git rules (critical):**
|
||||
|
||||
- **C-16** behind remote → skip writes (pull first).
|
||||
- **C-17** ahead + push failed → skip further writes.
|
||||
- **Push-seal:** fix runs that create commits must push before return.
|
||||
|
||||
---
|
||||
|
||||
## 5. Consistency engine (primary repo tooling)
|
||||
|
||||
**Script:** `scripts/consistency_check.py` (large monolith).
|
||||
**CLI wrappers:** `statehub fix-consistency`, `make check-consistency` /
|
||||
`make fix-consistency`, MCP `check_repo_consistency`.
|
||||
|
||||
| Mode | Meaning |
|
||||
| --- | --- |
|
||||
| `--repo SLUG` | Single registered repo |
|
||||
| `--here [PATH]` | Infer slug from cwd/remote |
|
||||
| `--all` | All registered repos |
|
||||
| `--remote --all` | Pull then fix (fleet sweep) |
|
||||
| `--fix` | Apply file-wins repairs + writebacks |
|
||||
| `--no-writeback` | Check/report only |
|
||||
|
||||
**Scheduled automation:** activity-core (or operator) →
|
||||
`POST /consistency/sweep/remote-all` → remote-all sweep with wall-clock budget.
|
||||
|
||||
**C-rule families (repo-relevant):**
|
||||
|
||||
| Group | Examples | Role |
|
||||
| --- | --- | --- |
|
||||
| Parse/structure | C-01, C-02 | workplans/ present and parseable |
|
||||
| Binding/drift | C-03–C-06, C-09–C-12, C-15, C-19, C-22 | UUID + status/title drift; file wins |
|
||||
| Orphans | C-07, C-08, C-14 | DB without file / ghost workstreams |
|
||||
| Git sync | C-16, C-17 | Protect against clobber / open-loop |
|
||||
| Classification | C-24 | `.repo-classification.yaml` |
|
||||
| Id hygiene | C-26, C-27 | prefix + collision |
|
||||
| Work-record kinds | C-31–C-33 | registry + WORK-RECORDS index |
|
||||
| **Inbox (not repo)** | C-25, C-28, C-29 | messages — hub-core territory |
|
||||
| Quality soft | C-34 | DoR-Ok soft warnings |
|
||||
|
||||
Parsers also live in `api/services/workplan_files.py` for in-process API
|
||||
writeback (overlap with consistency_check — dual implementation risk).
|
||||
|
||||
---
|
||||
|
||||
## 6. REST surfaces touching repos (selected)
|
||||
|
||||
| Prefix / route | Purpose |
|
||||
| --- | --- |
|
||||
| `/repos/` | Registry list/create |
|
||||
| `/repos/{slug}` PATCH/archive | Metadata / lifecycle |
|
||||
| `/repos/{slug}/paths` | Host path registration |
|
||||
| `/repos/{slug}/sync` | Sync trigger |
|
||||
| `/repos/{slug}/doi`, `/doi/summary` | Definition of Integrated scoring |
|
||||
| `/repos/todo-md-staleness` | Automation input (activity-core) |
|
||||
| `/repos/scope-health` | SCOPE.md health |
|
||||
| `/repos/{slug}/dispatch` | Agent dispatch orientation |
|
||||
| `/workplans/`, `/tasks/` | Work index CRUD |
|
||||
| `/reconciliation` | State-change + optional file write-through |
|
||||
| `/consistency/sweep/remote-all` | Fleet reconcile job |
|
||||
|
||||
Related but **not pure repo boundary:** progress, messages, suggestions, fabric,
|
||||
token events, service catalog, TPSC, capabilities (mixed hub + repo).
|
||||
|
||||
---
|
||||
|
||||
## 7. MCP tooling (repo-facing subset)
|
||||
|
||||
| Tool | Role |
|
||||
| --- | --- |
|
||||
| `register_repo` / `register_repo_from_classification` | Registration |
|
||||
| `update_repo_path` | Host path |
|
||||
| `list_domain_repos` / `list_repos_by_classification` | Discovery |
|
||||
| `check_repo_consistency` | Wraps consistency engine |
|
||||
| `validate_repo_adr` | ADR-001 checklist script |
|
||||
| `ingest_sbom_tool` | SBOM ingest for a repo |
|
||||
| `get_repo_goals` / `update_repo_goal` / `get_repo_dispatch` | Goals / dispatch |
|
||||
| `list_workplans` / `create_workplan` / `update_workplan*` | Work index |
|
||||
| `list_tasks` / `update_task_status` / bulk status | Task index + mutate |
|
||||
| `get_domain_summary` / `get_state_summary` | Orientation (includes repo health) |
|
||||
|
||||
Sanctioned writes vs bootstrap-only are documented in `mcp_server/TOOLS.md`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Adjacent tooling (repo-attached inventories)
|
||||
|
||||
| Tool | Makefile / script | Notes |
|
||||
| --- | --- | --- |
|
||||
| SBOM ingest | `make ingest-sbom`, `ingest_sbom.py` | Lockfiles + tools yaml |
|
||||
| TPSC ingest | `ingest_tpsc.py` | Service declarations |
|
||||
| Capabilities ingest | `ingest_capabilities.py` | Registry |
|
||||
| DoI check | `check_doi.py` | Integration maturity |
|
||||
| ADR validate | `validate_repo_adr.py` | File layout |
|
||||
| Gitea inventory | `gitea_inventory.py` | Forge listing |
|
||||
| Normalize attached WPs | `normalize_attached_repo_workplans.py` | Fleet hygiene |
|
||||
| Edge outbox | `api/edge/outbox.py` | Offline queue when hub unreachable |
|
||||
|
||||
These are **repo-scoped jobs** but not the core ADR-001 consistency loop.
|
||||
|
||||
---
|
||||
|
||||
## 9. Downstream consumers
|
||||
|
||||
| Consumer | Interaction |
|
||||
| --- | --- |
|
||||
| **All agent AGENTS.md templates** | Session start brief; end with fix-consistency |
|
||||
| **activity-core** | `GET /repos/`, todo-md-staleness, SBOM bulk, remote sweep, context resolvers |
|
||||
| **ops-bridge** | Tunnels to API/MCP (`:8000` / `:18000`) |
|
||||
| **Dashboard** | Observable pages over REST |
|
||||
| **wise-validator / agentic-resources** | Progress and legacy field callers (historical) |
|
||||
|
||||
---
|
||||
|
||||
## 10. Strengths of the established tooling
|
||||
|
||||
1. **File-first doctrine is operational**, not only documented (C-rules + writeback).
|
||||
2. **Multi-host path registry** enables workstation + cluster workers on one slug.
|
||||
3. **Push-seal** closed the open-loop commit pile-up class of bugs.
|
||||
4. **Classification spine** unifies discovery without hard-coding domain folders.
|
||||
5. **MCP + REST + CLI** give agents and humans the same coordination surface.
|
||||
6. **Fleet sweep** exists for unattended reconcile (activity-core / remote-all).
|
||||
|
||||
---
|
||||
|
||||
## 11. Failure modes and technical debt (retirement-relevant)
|
||||
|
||||
| Issue | Impact |
|
||||
| --- | --- |
|
||||
| Monolithic `consistency_check.py` | Hard to own outside state-hub; extract unit is large |
|
||||
| Dual parsers (API vs script) | Drift risk between writeback paths |
|
||||
| Bootstrap WP id collisions | `statehub register` unsafe on repos with real WP-0001 |
|
||||
| Topic spine residual | `topic_id` still on models; classification is future spine |
|
||||
| Inbox C-rules in consistency | Couples messaging to “repo fix” |
|
||||
| Index mixed with hub concerns | Progress/messages/catalogs in same service as repo authority |
|
||||
| Ghost workstreams from MCP create_* | Bootstrap-only tools still create DB-first risk if misused |
|
||||
| Scheduled sweep fragility | Cluster notes: sweeps paused/gaps after cutovers |
|
||||
|
||||
---
|
||||
|
||||
## 12. Mapping to Repo Manager (current)
|
||||
|
||||
| State Hub capability | RM status (2026-08-09) |
|
||||
| --- | --- |
|
||||
| Observe + parse workplans | **Partial** — `rmgr observe/reconcile` (JSON index) |
|
||||
| Task status writeback + git | **Partial** — `rmgr update-task-status` |
|
||||
| Full C-rules / push-seal | **Not yet** — still SH |
|
||||
| Registry + host_paths as system of record | **Still SH** |
|
||||
| MCP / FastAPI / Postgres index | **Still SH** |
|
||||
| Dual-run adapter for retirement | **Missing** — blocks clean strangler |
|
||||
|
||||
See also: `docs/state-hub-extraction-inventory_v0.1.md`,
|
||||
`docs/observation-command-contracts_v0.1.md`.
|
||||
|
||||
---
|
||||
|
||||
## 13. Conclusion for retirement sequencing
|
||||
|
||||
The **retirement-critical path** is not a better CLI UX or a prettier model.
|
||||
It is:
|
||||
|
||||
1. Make Repo Manager the **authoritative executor** of reconcile + file writeback
|
||||
for at least one production command path agents already use.
|
||||
2. Keep State Hub as a **strangler facade** (MCP/REST) until meters show zero
|
||||
direct need for SH to touch checkouts.
|
||||
3. Only then move registry/host_paths and drop SH repo mutation.
|
||||
|
||||
That sequence is elaborated in `specs/ArchitectureBlueprint.md` and the next
|
||||
workplan **RMGR-WP-0002**.
|
||||
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.
|
||||
133
workplans/RMGR-WP-0002-retirement-dual-run-strangler.md
Normal file
133
workplans/RMGR-WP-0002-retirement-dual-run-strangler.md
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
---
|
||||
id: RMGR-WP-0002
|
||||
type: workplan
|
||||
title: "Retirement dual-run: SH adapter for writeback and reconcile"
|
||||
domain: infotech
|
||||
repo: repo-manager
|
||||
status: proposed
|
||||
owner: codex
|
||||
topic_slug: repo-manager
|
||||
created: "2026-08-09"
|
||||
updated: "2026-08-09"
|
||||
parent_project: prj-state-hub-retirement
|
||||
parent_workplan: SHR-WP-0001
|
||||
stream: S1
|
||||
related:
|
||||
- RMGR-WP-0001
|
||||
- STATE-WP-0079
|
||||
- ACTIVITY-WP-0029
|
||||
- specs/ArchitectureBlueprint.md
|
||||
- history/2026-08-09-state-hub-repo-tooling-research.md
|
||||
---
|
||||
|
||||
# Retirement dual-run: SH adapter for writeback and reconcile
|
||||
|
||||
## Goal
|
||||
|
||||
Close in on **State Hub retirement of repository checkout mutation** by making
|
||||
Repo Manager the executor for the highest-value write path and for reconcile,
|
||||
behind a **State Hub dual-run facade**—not by refactoring RM for cleanliness.
|
||||
|
||||
Success is measured by: agent task-status updates and fix-consistency can run
|
||||
with **Git evidence produced by Repo Manager**, while State Hub remains the
|
||||
MCP/REST entrypoint until meters allow cutover (Blueprint Stage B → toward D).
|
||||
|
||||
**Out of scope for this workplan:** dashboard UX, SBOM product work, full MCP
|
||||
rewrite, topic-spine cleanup, generic framework polish, expanding command catalog
|
||||
beyond what dual-run requires.
|
||||
|
||||
## Blueprint alignment
|
||||
|
||||
See `specs/ArchitectureBlueprint.md` §4–§9. This WP is Stage B.
|
||||
|
||||
## Define dual-run feature flags and success meters
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0002-T01
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Specify flags (e.g. `RM_WRITEBACK=1`, `RM_RECONCILE=1`) and a minimal meter:
|
||||
count of checkout mutations by source `state-hub` vs `repo-manager`. Document
|
||||
rollback (flag off → SH native path). No new product metrics frameworks.
|
||||
|
||||
## Productionize task-status command for dual-run
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0002-T02
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Harden `repo.work.update_task_status` from the T05 slice for dual-run use:
|
||||
idempotency key, expected_head_sha optional, push-seal compatible behavior
|
||||
(or explicit handoff to existing SH push-seal once), failure codes matching
|
||||
CMD-0001. Keep CLI; add thin HTTP only if SH adapter requires it.
|
||||
|
||||
## State Hub facade: route update_task_status to RM when flagged
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0002-T03
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
In **state-hub** (child change under this coordination): when flag on, MCP/REST
|
||||
task status updates call RM command for file+git evidence, then refresh SH index
|
||||
as needed. When flag off, preserve current behavior. Compatibility test: same
|
||||
file result as native SH writeback on golden fixtures.
|
||||
|
||||
Coordinate IDs with STATE-WP-0079; do not expand SH scope beyond the adapter.
|
||||
|
||||
## Dual-run reconcile: SH fix-consistency delegates to RM when flagged
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0002-T04
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Port or wrap the **minimum** C-rules needed so `statehub fix-consistency --fix`
|
||||
(or a feature-flagged path) can execute reconcile via RM for a pilot repo set.
|
||||
Inbox C-rules stay on SH/hub-core. Goal: SH process stops implementing new
|
||||
reconcile logic; it proxies.
|
||||
|
||||
## Pilot cutover on one non-critical repo
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0002-T05
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Enable flags for **one** agreed pilot repo (e.g. repo-manager itself or a
|
||||
low-risk tooling repo). Run agent task status + fix-consistency for ≥1 session.
|
||||
Capture evidence: before/after git SHAs, meter counts, no data loss. Document
|
||||
operator rollback.
|
||||
|
||||
## Hand evidence to STATE-WP-0079 / project gates
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0002-T06
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Write cutover evidence under `docs/evidence/` and link from STATE-WP-0079 /
|
||||
G-RMGR notes so the retirement program can expand the flag fleet-wide. No extra
|
||||
architecture rewrite—just retirement evidence.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- [ ] Feature flags + mutation meter defined and usable
|
||||
- [ ] Task-status dual-run path works with RM git_sha evidence
|
||||
- [ ] fix-consistency can delegate reconcile for pilot set
|
||||
- [ ] One pilot repo runs dual-run without regression
|
||||
- [ ] Evidence package enables STATE-WP-0079 expansion
|
||||
- [ ] No scope creep into non-retirement refactors
|
||||
|
||||
## Residuals (only if needed at finish)
|
||||
|
||||
Anything not required for Stage B becomes a later WP or residual intake with
|
||||
`origin: residual` — not silent backlog in SCOPE.md.
|
||||
Loading…
Add table
Add a link
Reference in a new issue