diff --git a/architecture/README.md b/architecture/README.md index 5e4b602..fac1cc7 100644 --- a/architecture/README.md +++ b/architecture/README.md @@ -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-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 | +| [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). diff --git a/architecture/retirement-gates_v0.1.md b/architecture/retirement-gates_v0.1.md new file mode 100644 index 0000000..eccb37e --- /dev/null +++ b/architecture/retirement-gates_v0.1.md @@ -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). diff --git a/evidence/baseline-2026-08-09.yaml b/evidence/baseline-2026-08-09.yaml new file mode 100644 index 0000000..d099e4e --- /dev/null +++ b/evidence/baseline-2026-08-09.yaml @@ -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. diff --git a/history/2026-08-09-foundation-complete.md b/history/2026-08-09-foundation-complete.md new file mode 100644 index 0000000..239f7b3 --- /dev/null +++ b/history/2026-08-09-foundation-complete.md @@ -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. diff --git a/workplans/SHR-WP-0001-foundation.md b/workplans/SHR-WP-0001-foundation.md index 4302ce6..76debc0 100644 --- a/workplans/SHR-WP-0001-foundation.md +++ b/workplans/SHR-WP-0001-foundation.md @@ -126,7 +126,7 @@ CORE-WP-0010, STATE-WP-0079, ACTIVITY-WP-0029, OPS-WP-0003, FIN-WP-0003 ```task id: SHR-WP-0001-T06 -status: todo +status: done priority: medium 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 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 - [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] Hub/extension architecture (T04) draft-reviewable - [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.