tegwick
5979dd895a
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a06d83-1cbc-71f2-b0dc-e0f48cedae43
206 lines
9.8 KiB
Markdown
206 lines
9.8 KiB
Markdown
---
|
||
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-09-04"
|
||
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-GEN — Generation transition completeness
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| **Statement** | No generation is considered superseded until its capabilities have explicit dispositions, consumers and repository scope are reconciled, downstream lanes and credentials are swept, and its successor runs on infrastructure with an accepted lifetime. |
|
||
| **Evidence** | `inventory/inter-hub-disposition.yaml`; `inventory/repository-scope-reality-20260904.md`; routed owner intakes listed there; successor deployment evidence in `CORE-WP-0011`. A transition sweep must independently inspect workload pulls, DNS resolution, access/tunnel catalogs, credential routes, scheduled jobs, CI runners, and source configuration. |
|
||
| **Owner** | `SHR-WP-0002-T06`; residual implementation belongs to each routed repository owner. |
|
||
| **Status** | **in_progress** — generation-2 dispositions and successor placement are evidenced; routed lane/registry residuals remain open. |
|
||
|
||
### 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-GEN | SHR-WP-0002 + routed repository owners |
|
||
| 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).
|