diff --git a/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md b/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md index fa6f12e..f7c12a1 100644 --- a/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md +++ b/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md @@ -7,6 +7,7 @@ - Included batch: **BAT-057** (`REQ-119`, `REQ-120`, `REQ-121`, `REQ-122`) - Source discovery: `dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md` - Project control card: `★M5 core release: operator broker truth hotfix (BAT-057 / REL-011)` — Project #7, `P0`, `Release-Pending` +- M5 coordination: [M5 coordinated release train readiness](../runbooks/m5-coordinated-release-train-readiness.md) ## Release intent diff --git a/docs/runbooks/m5-coordinated-release-train-readiness.md b/docs/runbooks/m5-coordinated-release-train-readiness.md new file mode 100644 index 0000000..2a61e91 --- /dev/null +++ b/docs/runbooks/m5-coordinated-release-train-readiness.md @@ -0,0 +1,68 @@ +# M5 coordinated release train — deployment readiness and execution control + +- Status: **draft coordination control-plane** +- Date: 2026-07-16 +- Coordinator: TREX lead +- Scope: `trex-core` REL-011, `portfolio-hub` REL-004, `trex-web` REL-002 +- Authority: This document coordinates release order and shared stop criteria. It **does not replace** each service's release document, runbook, release approval, or operator-owned deployment procedure. + +## 1. Decision statement + +The three releases have implementation and non-production verification evidence sufficient to **request** their individual release executions. They are **not yet authorized as deployed**. No operator may infer a production approval, service restart, database migration, proxy change, credential change, or live reconciliation from this readiness record. + +A release may start only when its own approval and every listed gate is satisfied. A failure in one release stops that release and blocks any dependent later release; it does not by itself authorize a rollback or change in another service. + +## 2. Release inventory and evidence + +| Order | Service / release | Pinned application source | Evidence supporting an execution request | Non-negotiable outstanding gate | +| --- | --- | --- | --- | --- | +| 1 | `trex-core` REL-011 / BAT-057 | `6d90f8951dbf354eb41301492d0bcaf0af24d882` (runtime PR #42 merge `94e148940adb008db0bbd215052a1e984f7c566b`) | `807 passed, 47 skipped`; diff hygiene PASS; no DB migration, dependency manifest, service-unit, or AMQP wire change | release approval; actual host baseline/rollback SHA; restart and read-only smoke evidence | +| 2 | `portfolio-hub` REL-004 / BAT-024, BAT-025 | `914b3dc6e6b9e2cbd7068fb30435c83f0581eab5` or reviewed descendant | `597 passed, 11 warnings`; isolated PostgreSQL migration `3 passed`; committed PR #21 independent QC PASS | Justin Ko release-window approval; restorable backup; DB lock/current/schema/row-count checks; migration and platform rollout evidence | +| 3 | `trex-web` REL-002 / BAT-010 | `1ec2cf4345310cab0d3468e36b31e0613668b482` or approved descendant | `npm run lint`, `npm run build`, `npm test`: `283 passed, 0 failed`; independent QC PASS | resolve and record actual reverse-proxy upstream / selected port (`3000` vs historical `8004`); `/trex`-prefix and dependency-health smoke | + +Supporting service documents: + +- core: `docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md`, `docs/runbooks/rel-011-m5-operator-broker-truth-hotfix-deployment.md` +- portfolio-hub: `docs/releases/rel-004_20260715_manual-ledger-api-and-metadata-migration.md`, `docs/runbooks/rel-004-m5-manual-ledger-deployment-runbook.md` +- trex-web: `docs/releases/rel-002_20260715_m5-portfolio-ui-theme.md`, `docs/runbooks/rel-002-m5-portfolio-ui-theme-deployment.md` + +## 3. Shared prerequisites before any execution + +1. Record an explicit release-window approval for the specific REL; an approved document push is not deployment approval. +2. Record operator, window, target host/environment, source/artifact pin, and the currently working rollback source/artifact **before** changing a process or database. +3. Confirm the release's source is exactly pinned or a separately reviewed descendant. Never deploy an unpinned branch head. +4. Keep credentials, `.env` values, tokens, backup contents, bearer headers, and customer/portfolio data out of chat, terminal capture, and release documents. +5. Run only the service-owned runbook commands or the real operator-owned platform procedure. Local test Compose files, guessed systemd commands, and ad-hoc production command substitutions are prohibited. +6. Capture secret-free command exit status, timestamps, PID/rollout state, health/status result, and rollback decision in the corresponding REL evidence table. + +## 4. Coordinated execution order + +### Step 1 — trex-core REL-011 (independent, urgent broker-truth hotfix) + +Execute only after REL-011 approval. Capture the current deployed SHA, update to the pin, use the existing supervisor to restart the core daemon, then perform only the runbook's read-only checks (`sync --all --dry-run` and `verify`) against the approved instance. `sync --live --yes`, slot/order mutation, automatic remediation, and changing `credential_fetch_enabled` are outside this release. + +**Proceed to Step 2 only when:** the daemon remains healthy, logs show no startup/fatal error, the read-only checks have their expected no-write classification, and no rollback trigger occurs. + +### Step 2 — portfolio-hub REL-004 (highest-risk: production DB migration) + +Execute only after independent REL-004 approval and the backup/DB gates pass. Perform the approved backup and capture Alembic `heads/current`, active workload/locks, schema state, and row counts. Upgrade exactly to `20260715_0028`, prove the four metadata columns/default/not-null/row-count invariants, then use the existing operator-owned rolling deployment procedure. Start with read-only health and existing-read checks; a manual-ledger mutation smoke needs separate explicit approval for a designated non-sensitive test portfolio. + +**Proceed to Step 3 only when:** migration postchecks pass, portfolio-hub health reports `db_enabled: true`, existing read paths work, authorization checks are correct, and the agreed observation period is clean. + +### Step 3 — trex-web REL-002 (presentation release after dependencies are healthy) + +Before stopping the process, reconcile the actual reverse-proxy upstream with the active deploy script and explicitly record the chosen app port. Stop if `/trex` is stripped or if the proxy target differs from the selected port. After portfolio-hub is healthy, build and start through `scripts/deploy-trex-web.sh`, then smoke the reverse-proxy route—not only localhost—for sign-in, portfolio list, safe existing portfolio detail, selected state/table readability, refresh/session, and logs. + +## 5. Stop and rollback boundaries + +| Release | Stop immediately when | Permitted recovery | +| --- | --- | --- | +| core REL-011 | missing approval/pin, daemon startup failure, error/no-write barrier failure, unexpected broker mutation risk | use captured pre-release source with the normal supervisor restart; retain all evidence; no live sync as a diagnostic shortcut | +| portfolio REL-004 | missing backup, unknown/branched Alembic state, lock/workload not accepted, migration/schema/null/row-count mismatch, health or authorization anomaly | before success: do not deploy new code; after migration success: roll back only to compatible code and retain additive schema `20260715_0028`; no downgrade, column drop, or restore without separate incident approval | +| web REL-002 | unresolved 3000/8004 proxy decision, `/trex` stripped, build/start failure, sign-in/portfolio regression, material readability regression | stop new process, restore captured known-good revision with the approved script, and recheck `/trex`, sign-in, portfolio list; no DB rollback applies | + +## 6. Release completion rule + +A service becomes `released` only after its own runbook evidence is complete and the lead records `confirm-release`. Do not mark the M5 train released because a source commit was pushed, a build passed, or another service succeeded. + +The coordinated train closes only when all intended service releases have individual evidence and decisions, or when deferred/excluded services are explicitly recorded with rationale and follow-up ownership.