coulomb/prj-state-hub-retirement
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(SHR-WP-0001): complete T06 gates and finish foundation workplan

Browse source 
Add baseline evidence (2026-08-09) and executable retirement gates mapped to
GOAL.md. Mark all foundation tasks done and workplan finished; next work is
child implementation streams.
This commit is contained in:
tegwick 2026-08-09 21:46:54 +02:00
parent 5d938baf31
commit a00d8c1e19
5 changed files with 335 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

3
architecture/README.md
View file

@ -10,5 +10,6 @@ in child repos; durable promotion targets are noted in each document.
| [hub-extension-architecture_v0.1.md](hub-extension-architecture_v0.1.md) | SHR-WP-0001-T04 | draft-reviewable | | [hub-extension-architecture_v0.1.md](hub-extension-architecture_v0.1.md) | SHR-WP-0001-T04 | draft-reviewable |
| [hub-extension-contract_v0.1.yaml](hub-extension-contract_v0.1.yaml) | SHR-WP-0001-T04 | companion | | [hub-extension-contract_v0.1.yaml](hub-extension-contract_v0.1.yaml) | SHR-WP-0001-T04 | companion |
| [child-workplan-map_v0.1.md](child-workplan-map_v0.1.md) | SHR-WP-0001-T05 | active | | [child-workplan-map_v0.1.md](child-workplan-map_v0.1.md) | SHR-WP-0001-T05 | active |
| [retirement-gates_v0.1.md](retirement-gates_v0.1.md) | SHR-WP-0001-T06 | active |
Related: [`../inventory/`](../inventory/) disposition inventory, [`../GOAL.md`](../GOAL.md). Related: [`../inventory/`](../inventory/), [`../evidence/`](../evidence/), [`../GOAL.md`](../GOAL.md).

196
architecture/retirement-gates_v0.1.md Normal file
View file

@ -0,0 +1,196 @@
---
id: SHR-ARCH-GATES-0001
type: architecture
title: "Migration and retirement acceptance gates v0.1"
status: active
version: "0.1"
created: "2026-08-09"
updated: "2026-08-09"
workplan_task: SHR-WP-0001-T06
baseline: evidence/baseline-2026-08-09.yaml
related:
- GOAL.md
- architecture/child-workplan-map_v0.1.md
- inventory/state-hub-disposition.yaml
- architecture/information-model_v0.1.md
- architecture/hub-extension-architecture_v0.1.md
---
# Migration and retirement acceptance gates v0.1
## Purpose
Turn `GOAL.md` success and project-retirement clauses into **executable or
evidence-backed gates**. Each gate has: id, statement, measurable evidence,
owner stream(s), and status.
Baseline snapshot: [`evidence/baseline-2026-08-09.yaml`](../evidence/baseline-2026-08-09.yaml)
(`SHR-EVID-BASELINE-0001`).
**Status vocabulary:** `open` | `in_progress` | `met` | `waived` (with rationale).
---
## A. Project success gates (from GOAL.md)
### G-IA — Canonical information model
| | |
| --- | --- |
| **Statement** | Entities, relations, and kinds (events, signals, messages, conversations, requests, work, decisions, knowledge, telemetry) are defined with authority and correlation rules. |
| **Evidence** | `architecture/information-model_v0.1.md` + `.yaml` (SHR-ARCH-IA-0001); human review optional for canon promotion. |
| **Owner** | SHR-WP-0001-T03 |
| **Status** | **met** (draft-reviewable; promotion residual) |
### G-EXT — Hub / domain-extension contract
| | |
| --- | --- |
| **Statement** | Versioned hub-core + domain-extension contract implements OA-relevant concepts and has a conformance suite. |
| **Evidence** | Architecture + contract outline **met** at Tier 0 (`hub-extension-architecture_v0.1.md`, `helixforge.hub-extension` YAML). **Conformance suite (Tier 1–3)** still required. |
| **Owner** | SHR-WP-0001-T04; suite → **HUB-WP-0004** |
| **Status** | **in_progress** (docs met; automated suite open) |
### G-HUB-RUNTIME — Hub-core production runtime
| | |
| --- | --- |
| **Statement** | Hub-core contains production runtime, contracts, SDK, extension registry, and compatibility surface required by active consumers. |
| **Evidence** | Deployed hub-core image serving registry/messaging/events/projections; consumer smokes green; contract artefacts published. |
| **Owner** | **HUB-WP-0004** |
| **Status** | **open** |
### G-CORE-ABSORB — core-hub traffic absorbed
| | |
| --- | --- |
| **Statement** | Production traffic formerly served by core-hub runs from consolidated hub-core; core-hub repository archived. |
| **Evidence** | Dual-run report; cutover progress event; ops-hub + activity-core smokes on new host; forge archive flag; completion record with revisions. |
| **Owner** | **CORE-WP-0010** (depends HUB-WP-0004) |
| **Status** | **open** |
### G-RMGR — Repo Manager end-to-end
| | |
| --- | --- |
| **Statement** | Repo Manager represents repositories end to end: file-backed work records, consistency, agent roles, change events, governed mutations. |
| **Evidence** | RMGR-WP-0001 acceptance: contracts versioned; one repo vertical slice with Git evidence + rebuilt projection; extraction dispositions for State Hub repo/work surfaces. |
| **Owner** | **RMGR-WP-0001** |
| **Status** | **open** |
### G-DISP — Full disposition inventory
| | |
| --- | --- |
| **Statement** | Every State Hub route, model, dataset, job, MCP tool, dashboard view, and known consumer has keep/move/replace/retire disposition. |
| **Evidence** | `inventory/state-hub-disposition.yaml` (425 items, v0.1.1). Re-validate on material surface change before freeze. |
| **Owner** | SHR-WP-0001-T02; maintenance → **STATE-WP-0079** |
| **Status** | **met** (initial complete; refresh before freeze) |
### G-HANDOFF — Capabilities on new owners
| | |
| --- | --- |
| **Statement** | All retained capabilities operate through new owners with compatibility, data-count, provenance, authorization, and failure-mode tests. |
| **Evidence** | Per-slice: (1) owner API/port green tests; (2) row-count or content-hash compare vs pre-slice dump; (3) provenance fields present; (4) auth deny/allow cases; (5) failure-mode notes. Inventory `move`/`replace` items checked off. |
| **Owner** | **STATE-WP-0079** + RMGR / HUB / OPS / FIN / ACTIVITY streams |
| **Status** | **open** |
### G-FREEZE — Stabilization window
| | |
| --- | --- |
| **Statement** | State Hub receives no normal reads or writes during an agreed stabilization window. |
| **Evidence** | Window dates recorded in progress event; access logs / meter show only health/admin; agents and automation pointed at successors; exception log empty or residual-owned. |
| **Owner** | **STATE-WP-0079-T06** + operator |
| **Status** | **open** |
| **Suggested window** | ≥ 7 consecutive days after last normal consumer cutover (operator may extend). |
### G-BACKUP — Backup / restore / rollback / history
| | |
| --- | --- |
| **Statement** | Backup, restore, rollback, and historical-query evidence accepted. |
| **Evidence** | (1) Final `pg_dump` (or CNPG backup) of State Hub DB with checksum; (2) restore drill into isolated DB with count compare vs baseline/final; (3) documented rollback procedure exercised once in dual-run; (4) historical work queryable from Git files + archived dump for projections. |
| **Owner** | **STATE-WP-0079** + ops; baseline recovery paths in `evidence/baseline-2026-08-09.yaml` |
| **Status** | **open** |
| **Note** | Cluster scheduled backups not yet configured — manual dump is current path (`state-hub/docs/cluster-operating-model.md`). |
### G-STOP — State Hub stopped and archived
| | |
| --- | --- |
| **Statement** | State Hub stopped; repository and final data archived read-only. |
| **Evidence** | Deployment scaled to zero / removed; forge repo archived; final dump stored with location recorded; INTENT marks retired; no scheduled jobs targeting SH API. |
| **Owner** | **STATE-WP-0079** + ops |
| **Status** | **open** |
---
## B. Project repository retirement gates (from GOAL.md)
| Gate | Statement | Evidence | Status |
| --- | --- | --- | --- |
| **P1** | Every success gate above has accepted evidence | Checklist in final report | **open** (A-section) |
| **P2** | Residuals have live owners outside this repo | Intake/WP ids with `origin: residual` | **open** |
| **P3** | Decisions/architecture promoted to durable homes | Paths in hub-core / custodian canon / child INTENT | **open** (partial: project-repo flavor already in custodian) |
| **P4** | Child workplans finished, cancelled, or handed off | Map statuses all terminal | **open** |
| **P5** | Final project report (revisions, migrations, archives, obligations, rollback expiry) | `history/YYYY-MM-DD-completion.md` | **open** |
| **P6** | This repo completed + read-only after consistency/link check | `project_status: archived` in GOAL.md; forge archive | **open** |
---
## C. Cross-cutting evidence rules
1. **Re-baseline before each major cutover** — copy `evidence/baseline-*.yaml` pattern with new date; never overwrite without rename.
2. **Counts** — for data moves, capture pre/post totals for affected tables; ±0 unexplained rows fails the slice.
3. **Callers** — known callers in baseline must be re-pointed or explicitly retired before G-FREEZE.
4. **Secrets** — never in evidence files; dump storage location may be referenced, not contents.
5. **Correlation** — cutover progress events include `correlation_id` linking slice id, dump checksum, and PR links.
6. **Waiver** — only with human progress note citing residual work-record id.
---
## D. Baseline summary (2026-08-09)
| Metric | Value |
| --- | ---: |
| Topics | 14 |
| Workplans | 887 |
| Tasks | 5222 |
| Decisions | 89 |
| Domains | 14 |
| Managed repos | 105 |
| OpenAPI paths (live) | 135 |
| Inventory items | 425 |
| Disposition move / replace / keep / retire | 269 / 66 / 48 / 42 |
Availability: private tunnel only (`127.0.0.1:8000`). Recovery: manual CNPG dump + WSL2 fallback path.
---
## E. Gate ownership matrix
| Gate | Primary child WP |
| --- | --- |
| G-IA, G-DISP (initial) | SHR-WP-0001 (done) |
| G-EXT suite, G-HUB-RUNTIME | HUB-WP-0004 |
| G-CORE-ABSORB | CORE-WP-0010 |
| G-RMGR | RMGR-WP-0001 |
| G-HANDOFF, G-FREEZE, G-BACKUP, G-STOP | STATE-WP-0079 (+ owners) |
| Domain hub conformance | OPS-WP-0003, FIN-WP-0003 |
| Automation retarget | ACTIVITY-WP-0029 |
| P1–P6 project archive | this repo after children terminal |
---
## F. Acceptance for T06
- [x] Baseline counts, callers, availability, recovery paths recorded
- [x] GOAL.md success clauses mapped to measurable gates
- [x] Project retirement clauses mapped (P1–P6)
- [x] Owners linked to child workplan map
- [ ] Gates **met** (implementation — out of scope for foundation WP)
Foundation workplan SHR-WP-0001 delivers the **gate definitions and baseline**;
closing the gates is the implementation program (S1–S7 + evidence).

101
evidence/baseline-2026-08-09.yaml Normal file
View file

@ -0,0 +1,101 @@
# SHR-EVID-BASELINE-0001 — State Hub migration baseline (orientation + gate inputs)
# Captured during SHR-WP-0001-T06. Re-capture before each major cutover slice.
id: SHR-EVID-BASELINE-0001
captured_at: "2026-08-09T19:45:00Z"
source: "GET http://127.0.0.1:8000/state/summary + selective REST"
state_hub_git_rev: "462f4a4"
cluster_access: "ops-bridge state-hub-primary → 127.0.0.1:8000"
health:
status: ok
db: connected
coordination_totals:
topics:
total: 14
active: 14
workplans:
total: 887
proposed: 14
ready: 6
active: 8
blocked: 2
backlog: 7
finished: 806
archived: 44
tasks:
total: 5222
wait: 8
todo: 146
progress: 8
done: 4815
cancel: 245
decisions:
total: 89
open: 0
resolved: 87
escalated: 0
superseded: 2
registry_counts:
domains: 14
managed_repos: 105
api_surface:
openapi_path_count: 135
# inventory route extract (static) may differ slightly from live OpenAPI
inventory_route_items: 187
inventory_mcp_tools: 88
inventory_datasets: 42
inventory_dashboard_pages: 39
inventory_migrations: 43
inventory_total_items: 425
disposition_snapshot:
move: 269
replace: 66
keep: 48
retire: 42
known_callers:
- id: agents-mcp
path: "MCP SSE :8001 / remote :18001"
- id: dashboard-observable
path: "state-hub/dashboard"
- id: activity-core
path: "sweeps, sinks, context resolvers"
- id: fix-consistency-cli
path: "statehub fix-consistency"
- id: custodian-register
path: "statehub register / custodian_cli"
- id: remote-workers
path: "tunnel :18000/:18001"
- id: ops-bridge
path: "private access only"
notes: "Detail inventory: inventory/jobs-callers-ops.yaml and state-hub/docs/evidence/workstream-caller-inventory-20260709.md"
availability_expectations:
operator_primary: "http://127.0.0.1:8000 via ops-bridge"
remote_agents: "http://127.0.0.1:18000 API, :18001 MCP"
public_exposure: none
local_fallback: "WSL2 make api + docker postgres (rollback only)"
recovery_paths:
backup_current:
- "Manual CNPG pg_dump (scheduled backups not yet configured — see cluster-operating-model.md)"
- "WSL2 docker postgres dump path for rollback drills"
restore:
- "Restore into isolated DB; compare counts; then cut traffic"
rollback:
- "bridge down state-hub-primary && local make api (documented fallback)"
- "Retain prior image tag / dump until rollback expiry (set per cutover)"
historical_query:
- "Git workplan files remain authority for work records"
- "Final DB dump + archived state-hub repo for non-file projections"
full_table_rowcounts:
status: deferred_to_cutover_slices
note: >
Per-table SELECT counts should be captured in STATE-WP-0079 / owner WPs
immediately before each data handoff. This baseline locks coordination
totals and surface inventory for T06 gate definitions.

27
history/2026-08-09-foundation-complete.md Normal file
View file

@ -0,0 +1,27 @@
# Milestone — foundation workplan complete
**Recorded:** 2026-08-09
**Workplan:** SHR-WP-0001 (finished)
## Delivered
| Task | Deliverable |
| --- | --- |
| T01 | `prj-` flavor canon (`project-repository-flavor_v0.1.md`) |
| T02 | SHR-INV-0001 disposition inventory (425 items) |
| T03 | Information model SHR-ARCH-IA-0001 |
| T04 | Hub-extension architecture SHR-ARCH-HUB-0001 |
| T05 | Child workplan map SHR-ARCH-MAP-0001 + child WPs |
| T06 | Baseline + retirement gates SHR-ARCH-GATES-0001 |
## Next
Implementation streams (not this foundation WP):
- RMGR-WP-0001, HUB-WP-0004 (parallel start)
- then CORE-WP-0010, STATE-WP-0079, ACTIVITY-WP-0029, OPS-WP-0003, FIN-WP-0003
- close GOAL.md gates with evidence
No residuals from foundation require new intakes: child WPs already exist;
register-CLI GOAL.md support sits on STATE-WP-0079-T03; conformance suite on
HUB-WP-0004-T05.

11
workplans/SHR-WP-0001-foundation.md
View file

@ -126,7 +126,7 @@ CORE-WP-0010, STATE-WP-0079, ACTIVITY-WP-0029, OPS-WP-0003, FIN-WP-0003
```task ```task
id: SHR-WP-0001-T06 id: SHR-WP-0001-T06
status: todo status: done
priority: medium priority: medium
state_hub_task_id: "d793f242-999c-47ad-86f2-6d972cc20b84" state_hub_task_id: "d793f242-999c-47ad-86f2-6d972cc20b84"
``` ```
@ -135,6 +135,13 @@ Record baseline row counts, callers, availability expectations, recovery paths,
and historical-evidence requirements. Turn the success and retirement clauses and historical-evidence requirements. Turn the success and retirement clauses
in `GOAL.md` into executable or evidence-backed gates. in `GOAL.md` into executable or evidence-backed gates.
**Result (2026-08-09):** Baseline `evidence/baseline-2026-08-09.yaml`
(SHR-EVID-BASELINE-0001): topics 14, workplans 887, tasks 5222, decisions 89,
domains 14, repos 105. Gates `architecture/retirement-gates_v0.1.md`
(SHR-ARCH-GATES-0001) map GOAL.md success + project retirement (P1–P6) to
owners/evidence. G-IA and G-DISP met at foundation level; remaining gates open
on child streams.
## Acceptance ## Acceptance
- [x] The `prj-` flavor has a durable canonical definition. - [x] The `prj-` flavor has a durable canonical definition.
@ -143,4 +150,4 @@ in `GOAL.md` into executable or evidence-backed gates.
- [x] Information architecture (T03) draft-reviewable - [x] Information architecture (T03) draft-reviewable
- [x] Hub/extension architecture (T04) draft-reviewable - [x] Hub/extension architecture (T04) draft-reviewable
- [x] Each implementation stream has one local owner and workplan. - [x] Each implementation stream has one local owner and workplan.
- [ ] Migration and retirement gates have measurable evidence requirements. - [x] Migration and retirement gates have measurable evidence requirements.