From adfe9bae36f83a56c2ba328233813949c4fa2ea2 Mon Sep 17 00:00:00 2001 From: Taleef Date: Mon, 8 Jun 2026 10:40:49 -0400 Subject: [PATCH 1/2] docs(decisions): add ADR-003 for TWH single-instance consolidation Captures the 2026-05-21 decision (Doug) to collapse the three-instance dev model (workwell/ecqm/twh) down to a single all-encompassing TWH deployment. Quotes JOURNAL rationale; notes that ecqm seeding path and *_ECQM secrets are retained as restore-later capability. Co-Authored-By: Claude Sonnet 4.6 --- docs/DECISIONS.md | 17 +++++++++++++++++ docs/JOURNAL.md | 15 +++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 3568487..6388f35 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -12,6 +12,23 @@ - Clear seam for post-MVP split: package boundaries remain explicit so services can be carved out later if load or ownership requires it. - Keeps risk focus on measure correctness, run determinism, and case idempotency rather than distributed-systems overhead. +## ADR-003: Single all-encompassing TWH instance (consolidation from three-instance model) + +- **Date:** 2026-05-21 +- **Status:** Accepted +- **Stakeholder:** Doug (confirmed direction 2026-05-21) +- **Context:** During the sprint build-out (May 2–17), three separate deployment instances were created to isolate concerns during development: `workwell` (base skeleton), `ecqm` (CMS eCQM catalog seeding), and `twh` (Total Worker Health — OSHA safety measures). Each had its own workflow, frontend image, and partially-seeded database. Doug's May 21 review surfaced that these were not separate products — they were a development stepping stone. From the JOURNAL 2026-05-21 entry: + > "Doug clarified the product direction: TWH (Total Worker Health) is all-encompassing. OSHA occupational safety compliance and clinical quality (eCQMs, HEDIS wellness) are not separate products — they are two sides of the same coin and belong in one platform. The three-instance deployment model (workwell, ecqm, twh) was a development stepping stone, not the product architecture. One TWH instance covers everything." + > + > "NIOSH's TWH framework is the conceptual foundation: worker health is shaped by both workplace hazards (OSHA safety programs) and general health promotion (chronic disease, preventive care). WorkWell is the platform that manages both in one system with a shared measure catalog, shared case workflow, shared audit trail, and shared CQL evaluation engine." +- **Decision:** Consolidate to a single TWH deployment. Delete the `deploy-os-mieweb.yml` (workwell instance) and `deploy-ecqm-mieweb.yml` (eCQM instance) workflows. The sole active workflow is `deploy-twh-mieweb.yml`, which builds the backend (`ghcr.io/taleef7/workwell-api`) and TWH-branded frontend (`ghcr.io/taleef7/workwell-twh-frontend`) and sets `WORKWELL_INSTANCE=twh` to seed all three measure categories on startup: OSHA safety (4 active CQL + 3 catalog-only), HEDIS wellness (4 active CQL), and CMS eCQM catalog (49 Draft entries). The old `workwell` and `workwell-api` MIE containers were deleted from the manager UI. Fly.io `workwell-measure-studio-api` was destroyed (stale secondary stack from the Fly era). The production URLs are `https://twh.os.mieweb.org` (frontend) and `https://twh-api.os.mieweb.org` (backend). +- **Consequences:** + - `ecqm.os.mieweb.org` and `workwell.os.mieweb.org` are intentionally offline. The workwell hostname currently returns a 404; a 301 redirect to `twh.os.mieweb.org` is the documented follow-up (see infra/redirect/). + - The eCQM seeding path (`ensureCmsEcqmCatalogSeed()`), the `workwell-ecqm-frontend` image build config, and the `*_ECQM` GitHub secrets are retained as a restore-later capability in case a separate eCQM-only instance is needed in future. + - Every push to `main` deploys the single TWH environment, giving a clear signal that `main` is always production. + - The platform can expand its catalog (more OSHA measures, more HEDIS measures, more CMS eCQMs) without any infrastructure change — it is all one seeded database with one shared catalog, case workflow, and audit trail. + - Cost: reduced — one container pair instead of three. + ## ADR-002: evidence_json shape and define-level traceability - **Date:** 2026-05-01 diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md index bfb8dbd..259a23e 100644 --- a/docs/JOURNAL.md +++ b/docs/JOURNAL.md @@ -1,5 +1,20 @@ # Journal +## 2026-06-09 — Polish pass: ADR-003, workwell.os redirect, CQL code-filter tightening, trend view, code explorer + +### What changed + +Post-external-review polish pass based on Doug's harmonization brief. Six independent PRs opened from feature branches; tasks executed in order below. + +- **ADR-003 (docs/adr-003-twh-consolidation):** Captured the 2026-05-21 TWH consolidation decision in DECISIONS.md as a numbered ADR. Quoted the JOURNAL rationale; documented that the ecqm seeding path and `*_ECQM` secrets are retained as restore-later capability. +- *(Further entries added per PR as tasks complete.)* + +### Verification + +- No code changes in this entry; docs-only PR. + +--- + ## 2026-06-08 — Documentation sync: truth-up across the living docs ### What changed From 979a9283dc5aa68a8764772fb4d4a3c1d4cb5039 Mon Sep 17 00:00:00 2001 From: Taleef Date: Mon, 8 Jun 2026 13:04:37 -0400 Subject: [PATCH 2/2] fix(docs): redate journal entry to 2026-06-08 and scope to this PR only Entry was future-dated 2026-06-09 and claimed six PRs existed that had not yet shipped. Corrected to the real commit date and trimmed content to describe only the ADR-003 addition in this PR. Co-Authored-By: Claude Sonnet 4.6 --- docs/JOURNAL.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md index 259a23e..e50425b 100644 --- a/docs/JOURNAL.md +++ b/docs/JOURNAL.md @@ -1,17 +1,14 @@ # Journal -## 2026-06-09 — Polish pass: ADR-003, workwell.os redirect, CQL code-filter tightening, trend view, code explorer +## 2026-06-08 — docs(decisions): ADR-003 TWH single-instance consolidation ### What changed -Post-external-review polish pass based on Doug's harmonization brief. Six independent PRs opened from feature branches; tasks executed in order below. - -- **ADR-003 (docs/adr-003-twh-consolidation):** Captured the 2026-05-21 TWH consolidation decision in DECISIONS.md as a numbered ADR. Quoted the JOURNAL rationale; documented that the ecqm seeding path and `*_ECQM` secrets are retained as restore-later capability. -- *(Further entries added per PR as tasks complete.)* +- **ADR-003:** Captured the 2026-05-21 TWH single-instance consolidation decision in `docs/DECISIONS.md` as a numbered ADR. Quoted the JOURNAL rationale verbatim; documented that the eCQM seeding path and `*_ECQM` secrets are retained as restore-later capability; noted the `workwell.os` redirect as a follow-up (see `infra/redirect/`). ### Verification -- No code changes in this entry; docs-only PR. +- Docs-only PR; no backend or frontend changes. ---