Healthcare Data Platform — Decision Log

The why+when timeline. An append-only record of the significant decisions and lessons that shaped how this project was built — the connective tissue between the formal strategy stack (../architecture/) and the per-version retros (../implementation/briefings/). Specs say what the platform is; this log says how we came to build it this way, and what we learned — including the calls that were later corrected. What earns an entry: an architecture decision, a process/workflow change, an experiment that shaped direction, a lesson worth not re-learning, a corrected call. NOT every feature (the briefings + implementation/completed/ cover those). One short entry: date · the call · the why · what it superseded (if anything). Cadence: maintained at each version seam (extracted from the briefing's retro — part of the close ritual, ../implementation/README.md). Back-filled from the re-foundation era at creation (2026-07-02) — so the narrative survives without the transcripts. _Newest first._

2026-07-05 — 0.10 CLOSED (1/1 + fix, 8 pts): the keystone re-scoped the arc — the reading-first pivot + the initiative endpoint defined

Outcome. 0.10.1 roadmap-as-files delivered the clickability keystone: every candidate a file (candidates/), the roadmap a sorted link index, every card clickable-to-preview, STATUS restructured (exec summary + links). Dan's same-evening playtest then did two things: caught B02 (garbled candidate preview — 0.10.1 stored candidates as pre-converted HTML where feature specs store raw markdown; the shared downstream conversion ran TWICE and escaped the tags; one-line fix, escaped-tag count 1→0) and generated the structural signal that re-scoped the next version. The pivot (the real story): the full-width bottom panel is inherited water — a v1-era holdover from before the reading pane existed. With everything clickable-to-pane, the views became navigation, and navigation wants a COLUMN, not width → 0.11 = the reading-first layout (master-detail: left activity column of polymorphic cards — one look, three verbs: file/section/nav — + near-full-height reading pane; brief: implementation/discovery/reading_first_layout.md). Option B at the seam: 0.10.2 (specced, ready) was ABSORBED into 0.11 rather than built — its render sites target the layout being replaced; the review-cost ceiling says never spend review twice on the same surfaces. Resolution logic transfers verbatim. A single-feature version is fine when the theme completes — size to the seam, not the slate. The initiative arc, defined (Dan): initiative 0 = platform standing + demo-ready — now explicitly including UI/workflow DONE (0.11) + PUBLISHED (danbrickey.dev landing + HDP subdomain). Initiative 1 = back to the DATA (more domains, personas, a realism pass — the mock data's artificial consistency is visible on screen; the demo's subject is the workflow, so the data must resonate without distracting). 1.0 = the dual pivot: the workflow switch (Desktop + board) and the data return, coinciding. Bug policy refined: severity is contextual to EXPOSURE — publishing graduates demo-visible minors into the pre-publish stability lane (B03 rides 0.11). Lessons banked: UI features get a human click-test lap in the DoD (B02 lived in the exact spot file:// automation can't reach); the board's git view proved trustworthy in the hygiene sweep (6 folders→2, 11 branches→2 — the "extra" folders were orphaned checkouts, and leftover verification servers were the folder locks). Velocity: 0.9=~15 → 0.10=8, closed early on purpose.

2026-07-05 — 0.9 CLOSED (3/3, ~15 pts): the FIRST three-part-scheme version — "the board replaces VS Code" begins

Outcome. 0.9 is the first version under the initiative.version.feature scheme (features 0.9.1/0.9.2/0.9.3), and the first slice of the 0.x arc "the board replaces VS Code." 0.9.1 board contract catch-up — made build_board.py natively parse the three-part scheme (fixing a LIVE bug — the board was blind to release/0.9 the moment it was cut) + read build reports from feature docs; the first feature to dogfood the build-report-in-doc contract, self-hosting (the board parsed 0.9.1's own report out of its doc). 0.9.2 git-status view — a 7th board view showing branches/worktrees/pending-changes, the #1 VS-Code reflex, extending the existing _git machinery; overview-altitude only (D2 — no diffs, which is the descent it avoids). 0.9.3 review queue — the keystone: the assistant flags a doc → review_queue.md → a board Review Queue panel → click → read in the detail pane (reusing 8-1's embedded-doc renderer, extended to arbitrary docs); D3 read-only board honored (the file is assistant-edited, never board-written). Verified against reality, all three — the discipline held even though reports now live in docs (I read them from the doc + checked the claims): 0.9.1's release/0.9 resolution + D1 legacy-compat (full v1-v8 arc) + the 22→doc-report count; 0.9.2's 11-branches/4-worktrees matching git exactly + 0-diff-content; 0.9.3's queue rendering + read-only + the arbitrary-doc load. The build-report-in-doc change proved out — I re-attached to each build from the repo, no paste. The parallel-merge lesson (the real story of the close): 0.9.2 + 0.9.3 ran as a 2-agent parallel run and hit the FIRST genuine interleaved-code conflict (both restructured the same render functions). "Keep both" is a HYPOTHESIS, not a rule — the naive auto-resolve broke (two -> str: closers; two _js_tmpl assignments would've silently dropped a feature). Resolved by understanding WHY the JS templates differed (0.9.2's git-view is static/no-JS; 0.9.3 added the review handlers → keep both badges + 0.9.3's _js_tmpl), then VERIFYING the merged board runs with both views live. Generated files (board.html) get REGENERATED from the merged generator, never merge-marker-resolved. Banked as the parallel-doctrine refinement. Velocity: v8=19 → 0.9=~15 (three clean M's). A peak-dogfood version: about the board, built + reviewed THROUGH the board.

2026-07-04 — v8 CLOSED (4/4, ~19 pts): "the demo, made real" + the workflow spine gets two upgrades

Outcome. v8 delivered four features and closed with two workflow-contract migrations (below). 8-1 Review Cockpit (L) — the feature board became a two-pane master-detail cockpit: click a card → its Markdown spec (incl. ASCII wireframes as terminal blocks) renders in a sticky detail pane, board stays put; 3 funnel-derived lanes (Ready — / Committed vN / Delivered vN ✅ current-only, all from the roadmap Ver column); pop-out talk-track window; icon-only expand overlay; the v7 scroll-jump-on-refresh FIXED. Built to a LOCKED Claude Design handoff — the design-tool→spec→ build pipeline's first real use, and it landed clean on the first build (the wireframe/design gate paying off). Recreated in build_board.py (prototype runtime NOT ported). The key capability: read any spec/wireframe/diagram without the file system (spec markdown embedded at gen-time — file:// can't fetch). 8-2 benefit-content buildout (L) — cost-sharing (copays/deductibles/OOP/coinsurance) by segment on the EXISTING h_benefit_package sat (no new hub/link), seeded + RNG-isolated, + a norms business-rule; the Tier-2 depth anchor. 8-3 clinical persona (S) — the exam-room reskin, the wireframe-gate's first use (built to an ASCII wireframe, no post-hoc redesign). 8-4 board-in- Evidence (S) — the interactive cockpit now iframes onto the public Vercel URL (current-per-deploy via a generator copy step). Verified against reality, all four (the standing discipline): 8-1's spec-embed + ASCII-render + scroll-fix + deterministic regen; 8-2's D1-no-new-hub + RNG-isolation (only benefit_package.csv changed) + by-segment plausibility + 868 PASS; 8-3's reskin-only + 757 reconciled + theme-reuse + wireframe- adherence; 8-4's D2 current-per-deploy (hash-identical + a round-trip marker proof) + DB-less serving. The artifact-as-muse loop fired AGAIN — dogfooding the 8-1 cockpit surfaced the feature-board-v3 vision ("the board replaces VS Code" — git-status view, review queue, pane extensions), captured as a discovery doc + a candidate first named initiative. TWO WORKFLOW-CONTRACT MIGRATIONS at this close (both apply going forward):

Three-part version scheme initiative.version.feature (e.g. 0.9.1). A single dotted number

replaces the old mixed vN + N-x (the dash is gone). 1st = initiative (theme/arc: 0 = through v8, 1 = "the board replaces VS Code"); 2nd = version within it (.9, .10); 3rd = feature within the version (.1, .2). History stays v1–v8 (no git-tag rewrite); the next version is 0.9, its features 0.9.1/0.9.2. The board's native I.V.F parser is deferred to its own 0.9 feature (a single split(".") — simpler than the mixed scheme it replaces); docs/tag narrate 0.9 now.

Build report moves INTO the feature doc (drop the separate JSON). The agent writes a

## Build Report 3rd section (labeled fields the board parses + a prose delta); solves the copy-paste-back friction, survives cross-session review, travels through distillation. build_board.py parses the doc section instead of build_reports/*.json. Parallel doctrine at scale: 8-2 + 8-3 ran as a 2-agent parallel run; the cache merge-conflict is now a known pattern (regenerate the cache from the merged tree). 8-1's Claude Design handoff established the high-fidelity-UI pipeline: design in Claude Design → export the handoff zip → lock it in the repo → build to it. Velocity: v1=34 → … → v7=15 → v8=~19 (grew with 8-1's re-scope + 8-4).

2026-07-04 — v7 CLOSED (3/3, ~15 pts): "the demo, shipped" + the artifact-as-muse loop firing twice

Outcome. v7 built HDP's demo capability by being a worked example of the demo it enables. 7-1 Board Demo Rail — folded the demo INTO the board (a right-edge talk rail + present mode + 2 structural diagrams + 6 LIVE panels reading real board data), so the demo is a view of the board = a view of the specs, non-staleness all the way down. The rail is exhibit A: a feature the workflow shipped, so it proves the method by being a product of it. 7-2 persona member-call (CSR) screen — a zero-new-model reskin of person_360 + person_events into a "rep on the phone" view; the demo's visible-payoff headliner, look extracted to a reusable persona stylesheet. 7-3 coverage span realism — surfaced by playing 7-2. Verified against reality (three times, not the reports): 7-1's D1 (closed board unchanged) by a same-git-state generator-only diff (0 deletions, 700 pure additions — isolation, not a naive line-diff); 7-2's D2 (reskin-only) by an empty dbt/ diff + 757 reconciliation; 7-3's tail-collapse by re-running the exact before-query + confirming RNG isolation (provider/network CSVs byte-identical). The headline lesson — the dogfood-playtest is a primary roadmap source. Playing 7-2's screen surfaced a real data defect (member-months avg 302 / max 612 / 81% over 17 yrs — structurally valid, behaviorally absurd), which became 7-3 (segment-typed spans + a recent-coverage window → avg 302→63mo, max 612→221 Medicare, >300mo 259→0; commercial median 42mo, Medicare 120mo). Using the rail surfaced its own v8 evolution (the two-surface split — private talk-track window + public board overlays + a scroll-jump-on-refresh bug). The loop fired twice in one version. The firewall held: findings feed the NEXT version, never a retroactive edit. Process changes banked (the v7→v8 hinge): (1) the dogfood-playtest is a scheduled roadmap input; (2) synthetic naming gets a proximity check — "Gem State" was too close to Gemstone Holdings (BCI's holding co), renamed Anchor Health Cooperative; (3) the demo reserve is restructured by funnel stage (≥2 ready-to-ground + ≥2 ready-to-hand-off) so a demo walks the whole pipeline, and grounded ≠ agent-ready (cut a persona hand-off spec before the first demo); (4) verifying a "pure addition" claim needs same-state isolation (the D1 technique). Also logged: benefit-content buildout deferred to v8 (avoid stacking two generator change-drivers with 7-3); a stale CLAUDE.md parquet-cache line to soften. The parallel run held again: 7-1 + 7-2 built concurrently, clean merge — the BCI-demo workflow shape, now routine.

2026-07-03 — 6-2 DELIVERED: the person_events timeline (the 2-4 anti-pattern, resolved right)

Outcome (reviewed against reality). 6-2 built person_events (platinum): one row per (resolved person, dated event), a union of encounters (via patient_key) + claims (via member_key), each resolved to the person through cs_patient_member_same_as — the resolution join lives in the MART, and the Evidence page/source only filter by person_key (D2 honored). This closes the 2-4 D3 finding the right way: the member_id→member_key→claim join the app refused now lives in the platform where business logic belongs. The old <Note> saying "the timeline can't be built" was removed — the loop is visibly closed. Verified independently: read the mart + source + page (join in the mart, page is filter-only); my own build 778/778; person_events = 68,594 = 34,297 enc + 34,297 clm, 757 distinct persons = person_360's 757 (no orphans); committed cache = 68,594 rows (correct, not stale — extracted from git and counted); build-without-DB verified myself (renamed the DuckDB, npm run build, page rendered from cache). Good judgment: the agent rejected an unpaginated table for the 3,212-event person (scatter + recent-30 instead, pagination noted as a follow-on). The parallel run landed: 6-1 + 6-2 built concurrently in separate worktrees, merged clean (different file sets), no lock fight — HDP's first true parallel-build-agents run, and the exact workflow shape for the BCI demo. Cache note: the committed cache came from 6-2's pre-6-1 branch, but 6-1's member sats are raw-vault-only (not surfaced in any Evidence page — the COB dashboard stat is a deferred [demo] idea), so the cache is complete for what the dashboard renders. v6 (2/2) ready to close.

2026-07-03 — 6-1 DELIVERED: member sat trio + the independent-RNG generator pattern

Outcome (reviewed against reality — additivity verified by full regen). 6-1 added three member dimensions as sats on h_member: disability + exchange (plain Type-2 sat()) + COB (ma_s_member_cob, a ma_sat() sub-keyed by cob_seq — a member holds several other-coverage records at once). D1 executed exactly. The load-bearing check was D3 (additivity): each new family carried its own generator increment (emitter → CSV → bronze → hashed stage → sat), and a generator increment that perturbs the shared RNG would silently change unrelated existing data (the 4-1 _pick_service_date cascade lesson). Verified independently, not on the report: I hashed all 32 data CSVs, regenerated from scratch, re-hashed → every existing CSV byte-identical, only the 3 new CSVs appear; git status data/ clean; 823/823 green on my own build; sats reconcile to source (80/147/162). The reusable pattern (worth naming): give each new generator family its OWN seeded random.Random instance (seed + 1_000_003, + 2_000_003, + 3_000_003) so its draws can't shift the shared sequence feeding existing tables. This is the definitive fix to the RNG-cascade problem that's shadowed the generator since 4-1 — an additive increment is now a solved pattern, not a per-feature risk. (D5 polish: correlated COB carrier↔insurance-type to avoid implausible pairings — judgment without touching determinism.) Delivered in parallel with 6-2 (person_360 deepening) — the first true parallel-build-agents run (separate worktrees = separate DuckDBs, no lock fight; different file sets = no merge conflict). Also a demo rehearsal: two isolated agents building while the review session grooms — the exact workflow shape for the BCI pitch.

2026-07-03 — 5-2 DELIVERED: S9 CLOSED (provider match rule single-sourced + drift guard)

Outcome (reviewed against reality — the guard was tested, not trusted). The provider same-as match rule lived in two independent copies (cs_provider_same_as.sql SQL twin + resolvers.py Python, which stamps what the dashboard reads); 4-1 caught them drifted. Fix: a canonical scripts/synth/match_rules.py (the tuple PROVIDER_MATCH_FIELDS, the derived matched_on literal, the is_unique_match PSA-5 guard) that resolvers.py now imports instead of restating; the SQL stays a hand-written twin (can't import Python) pinned by a drift guard (check_match_rule_drift.py) that runs at the top of every generator run — so the generator refuses to produce data from a drifted rule. Verified independently: (1) regenerated from the refactored code myself → 3 claims CSVs byte-identical to baseline, git status data/ clean (D2 held — a pure refactor); (2) broke the SQL's matched_on literal myself (4-tuple→3-tuple) → the standalone guard exited 1 with a clear message AND the generator raised MatchRuleDriftError and refused to run; restored, re-verified clean; (3) dbt build 770/770; resolved counts unchanged (3,885 providers / 22,106 stamped). The principle: a drift guard that isn't tested against real drift is theater — so I broke it on purpose. Scope note (honest): the guard compares the SQL's matched_on literal against the canonical rule (the documented contract), not the SQL's actual join columns — so it catches a drifted rule name, not a hypothetical join-logic change that leaves the label stale. Reasonable for an S; noted, not expanded. Process win: the agent hit a secret-scanning hook flagging the report's MD5 hex as high-entropy and — rather than --no-verify — reworked the proof to git-diff/status-clean evidence (stronger anyway: it compares against the committed baseline, not a typed hash). No hook bypass. S9 closed; v5 (2/2) ready to close.

2026-07-03 — 5-1 DELIVERED: S8 altitude inversion FIXED (in-network determination → gold)

Outcome (reviewed against reality — a textbook clean relocation). The in-network determination lived in claim_network_status (platinum) but fct_member_month (gold) read it — the S8 medallion inversion (gold←platinum). Fix: a new gold cs_claim_network_status computed sat holds the determination (moved verbatim — 104 lines, diff-confirmed identical to the old platinum body); fct_member_month reads the gold cs_; claim_network_status platinum is now a 6-line passthrough view. Verified independently, NOT on the report: (1) line-diffed the moved SQL — verbatim; (2) ran my OWN before/after byte-identical test — git-reverted the 3 files, rebuilt both states, snapshotted all 3 consumers (claim_network_status, fct_member_month, person_360) ordered by PK, diffed each pair → 0 lines, all three (34,297 / 171,038 / 757 rows unchanged, in/out/unknown split identical); (3) medallion grep — zero gold/silver/bronze models ref any platinum model (the contract is restored); the new gold cs_ reads only silver+gold; the platinum passthrough's only downstream is person_360. dbt build 770/770 green (+9 tests for the cs_). The lesson reinforced: the byte-identical git-stash-diff (the 4-2 discipline) is what makes a "pure relocation" trustworthy — "tests still pass" would not have proven the determination didn't shift. Also: the 5-1 worktree was seeded by a FRESH dbt build --full-refresh from release/v5, not by copying the stale main-tree DB — the v4 hinge (the 4-3 stale-seed lesson) applied on its first outing, and the seed carried correct data (34,297, not the stale 36,416). S8 is closed; S9 (5-2) is next.

2026-07-03 — 4-3 DELIVERED: dashboard publishable; a STALE-SEED bug caught at review

Outcome (reviewed against reality — the catch is the lesson). 4-3 built the committed-parquet-cache path so evidence build runs on Vercel with no DuckDB (gazetteer's proven pattern; the .gitignore exception force-tracks only .evidence/template/static/data/). The agent's work was procedurally correct AND its build-without-DB test passed — but the cache carried the wrong data. Row-count review caught it: the committed member_month was 246,576 vs release/v4's true 171,038 (also claim_network 36,416 vs 34,297, person_360 728 vs 757). Root cause = MY seeding error, not the agent's: I seeded the worktree by copying the main-tree DuckDB**, which is STALE (last built before 4-1's claims regen — it still shows the pre-disambiguator counts). The agent faithfully snapshotted the DB it was given; its "cache == sources output" spot-check passed because both came from the same stale DB. Fix at review: ran a clean dbt build --full-refresh in the worktree (from release/v4's committed CSVs → correct DB), npm run sources, re-verified build-without-DB green, re-committed. All three docs (publishing.md, the spec's delivered note, the build report) had cited the stale counts — corrected. The lesson (process, carry forward): the main-tree DuckDB is a build ARTIFACT and goes stale; never seed a worktree cache-gen from it — a dbt-reading worktree must dbt build --full-refresh from its own branch's data first, THEN generate the cache. A stale DB is invisible to a build that only reads it; only a row-count reconciliation against a fresh build catches it. Reinforces the standing rule: review reconciles counts against reality, never trusts the report's own spot-check (which shares the build's inputs). (Deploy itself: D3 — Dan's ~15-min Vercel click-through, handed off in docs/publishing.md, not done in-session.)

2026-07-03 — 4-2 DELIVERED: the platform builds GREEN on live Snowflake (migration-test run #2)

Outcome (reviewed against reality — the most BCI-transferable proof on the board). The whole 120-model estate built 761/761 green on a live Snowflake trial (COTWTFF-OJ66083, the reused gazetteer trial), with the SAME dbt models that build green on DuckDB — zero Snowflake-only forks (D2 held). This is experiment[1] of the migration-test thesis (gazetteer v10 was #0): an AI-leveraged architect ports a governed DV2.0 platform to a new warehouse with byte-identical models. Verification (not the report on faith): (1) my independent DuckDB build --full-refresh = 761/761 green with all 25 Phase-B model changes in place — proving no regression/fork; (2) the report carries both-target run_results (snowflake 21:40Z, duckdb re-green 21:41Z, 641 tests each) + a gold-layer row-count parity table; (3) I cross-checked that parity against my own DuckDB — dim_patient 1171, fct_encounter 53346, dim_member 1294, fct_member_month 171038, fct_claim 34297 all match, closing the chain my-DuckDB == report-DuckDB == report-Snowflake. 6 cross-dialect fixes, all duckdb__-branch-untouched (the structural guarantee DuckDB output can't move): generate_series/STRFTIME/FILTER (Phase A) + identifier-quoting parity (project quoting: identifier false + per-table override for the group/organization reserved words), a dv_now() dispatched macro (Snowflake has no NOW()), "START" quoted in 6 bronze models, both date-spine macros' Snowflake variants rewritten around GENERATOR's constant-rowcount requirement (Phase B). Sharpest finding: dbt-fusion (which this repo's own config had designated for Snowflake) requires a literal account even to compile — empirically confirming the profile fix to the local dbt-snowflake + key-pair path (D7) was the correct route; the Workspace assumption never worked as documented. Auth reuse win: no new trial — same account, key-pair (.p8) valid on the USER, new healthcare database namespace beside gazetteer's. Held for review (outward-facing): the stale origin/feature/snowflake-dual-target remote is confirmed merged (PR #28) and safe to delete, but that's a git push --delete (shared state) — flagged for Dan, not done by the agent or silently. Deferred: the T0/T1/T2 parity match-contract stays a separate v5 candidate (D1 — green build ≠ full parity, though the row-count spot-check already looks perfect).

2026-07-03 — 4-1 DELIVERED: S9 drift closed, network story now leads

Outcome (reviewed against reality). 4-1 shipped the disambiguator in two passes: pass 1 added city to the vault cs_provider_same_as (correct but a DAG leaf — moved no data), pass 2 applied the SAME 4-tuple (name+specialty+state+city, same PSA-5 never-guess guard) to resolvers.py and regenerated. The two rule copies are now consistent (S9 closed as a fix; the single-source-of-truth refactor stays routed to a future version). Verified by an independent full-refresh rebuild + DuckDB decomposition — NOT the report on faith: determined claims (in+out) 24.9% → 54.6%, now the dominant network determination; unknown 45.4%, of which the true unidentifiable-provider residue is 25.2% (8,629 — the bucket the feature attacks, down from 54.8%) and uninsured/lapsed is 20.3% (6,958 — a member-eligibility category the resolver can't and shouldn't touch). Determinism byte-identical on re-regen (MD5s match, git status clean); both 2-3 fixtures intact (17,099 two-source collision; l_claim_encounter 34,297 1:1); 761/761 green on my own build. Review-value note: the agent's headline number (25.2%) was right but ambiguously labeled — only the independent rebuild-and-decompose confirmed WHICH bucket moved and that the 45.4% total unknown reconciles exactly. Reviewing the decomposition, not just the delivered figure, is what made the delivery trustworthy. Known-and-flagged, not fixed: claims.py _pick_service_date() short-circuits an rng.random() draw when a provider doesn't resolve, so a flipped resolution shifts the shared RNG sequence — claim_line/claim_diagnosis diffs are therefore wider than "just the newly-resolved claims." Deterministic (proven), no business-logic impact; a generator-design artifact any resolver-count-changing edit triggers. Left as-is.

2026-07-03 — the launch-location bug is SOLVED (the ☑worktree checkbox)

Resolution (after 4 recurrences). Every v2/v3 build agent launched in a harness phantom worktree (.claude/worktrees/<random> on claude/<random>) instead of the named pre-made worktree — a standing open item since v2. Root cause found via a screenshot of the desktop launch UI: the worktree checkbox in the task-launch panel auto-creates the app's OWN throwaway worktree off main, ignoring the pre-created healthcare-data-platform-<feature> folder. The fix: uncheck the worktree box and point the folder picker (Open folder…) at the specific feature worktree; the branch dropdown then doesn't matter (the folder already has the right phaseN-x branch checked out). Confirmed working on the 4-1 launch — the agent's report had NO wrong-worktree note for the first time. The recovery instructions stay (belt + suspenders), but the launch is now correct at the source. Standing item closed.

2026-07-03 — S9: provider-match logic is DUPLICATED across dbt + the generator (drift)

Finding (surfaced by 4-1, verified at review). The provider same-as match rule lives in two independent places: dbt/models/.../cs_provider_same_as.sql (the vault model) AND scripts/synth/resolvers.py build_provider_resolver() (the generator, which stamps payer_provider_id into data/claims/ at generation time). The dashboard reads the generator's resolution; the dbt model is a DAG leaf with zero consumers (dbt ls proves it). So 4-1's dbt-only change moved nothing — the two copies had drifted (4-tuple vs 3-tuple). Immediate call (Dan): extend 4-1 to fix BOTH copies + regenerate, so the rule is consistent and the dashboard actually moves. Deeper debt routed: a "single-source-of-truth for provider resolution" candidate (should the generator READ the dbt same-as, or a shared rule module, instead of re-deriving?) — the duplication is the real risk, like S8's altitude inversion. Pattern (again): the fast v1/v2 builds accreted a logic duplication that only a feature touching it surfaces. Lesson for spec-writing: when a feature targets a "resolution" or "determination," first check WHERE that value is actually computed — a vault model can be a leaf while the real logic lives in the generator.

2026-07-03 — v3 CLOSED (3/3, ~18 pts): the lighter version shipped CLEANER than v2

Outcome: v3 delivered all three committed features (gold rewire, payer distillation, generator realism) at ~18 pts — the deliberate lighter counterweight to v2's 26-pt point-ceiling run, with one review-heavy feature (3-1) + two light ones, sequenced solo-then-parallel. The finding: a lighter version can be CLEANER than a max-size one. The bottleneck-first sequencing (3-1 solo, then 3-2/3-3 parallel) kept the conductor's attention un-split during the one hard review. Confirms the v2 hinge — version size is a review-cost dial, not a point target — and adds the corollary: shape (one heavy + a light pair) matters as much as size.

2026-07-03 — model tiering refined: review REASONING, not just outcomes

Lesson (a corrected heuristic). v2 made Sonnet 5 + Ultracode the build default (spec gates quality > tier), reserving top tier for design-heavy work. v3 complicates that: 3-1 (TOP tier, the review-heavy feature) reached a correct decision (don't wire pit_patient) via factually wrong reasoning (claimed pit_patient is single-load; it's a 2.78M-row multi-snapshot spine) — a close review caught it. Meanwhile 3-3 (Sonnet 5 + Ultracode) did something harder — overturned its own spec's premise with verified evidence and escalated cleanly. Refined rule: keep Sonnet 5 + Ultracode default including for design-heavy work; the lever is review depth scaled to consequence, not model tier scaled to difficulty. And review reasoning, not just outcomes — a right call for a wrong reason is a latent trap for the next reader.

2026-07-03 — the escalation-reframe: a wall became the feature (3-3)

Call (Dan's [mine]). 3-3's realism pass hit a floor: ~55% of claims are "unknown" not from the date bug the spec assumed but from provider non-resolution — the vault's same-as (cs_provider_same_as / PSA-5) correctly refusing to guess on genuinely-ambiguous duplicate providers. Acceptance criterion 1 was unreachable by tuning. Decision: merge the real improvement (85%→75%) + REFRAME the wall as the feature — the dashboard splits "unknown" into uninsured vs unidentifiable-provider, telling the MDM-discipline story (a data platform that won't fabricate a match it can't defend — genuinely BCI-transferable). Why it matters: the STOP-and-escalate protocol turned a "failed acceptance criterion" into a better product narrative than the original spec imagined. A dod_met: false that the review resolved into a complete, richer delivery. The lesson: an honest escalation is an opportunity, not a defeat — the wall often teaches the real story.

2026-07-03 — S1+S2 resolved; S8 + provider-disambiguator surfaced (architectural debt)

Outcome. v3's 3-1 closed the 2-1 audit's top finding (S1: clinical facts bypass the vault — now repointed) plus S2 (added s_encounter). But the audit-heavy v3 work surfaced TWO new architectural findings from the fast v1/v2 builds: S8 (the 3-2 distillation found the in-network determination at the wrong altitude — platinum reach-down + a gold←platinum inversion) and the provider-MDM ambiguity (the 3-3 escalation). Pattern: the fast v1/v2 payer builds accreted layering debts that only a systematic audit surfaces. Ratified: budget a little architectural-hygiene capacity per version; distillation is a structural audit that finds things, not busywork.

2026-07-02 — v2 CLOSED (4/4, 26 pts): the point-ceiling experiment succeeded

Outcome: v2 shipped all four committed features in one session — clinical audit, claims lifecycle rule + validation pass, Evidence payer dashboard, synthetic generator — at 26 pts (~2× gazetteer's post-foundation cadence), the deliberate point-ceiling experiment. Zero rolled, all reviewed against reality, all merged. The finding: version size can push well above the ~12–13 pt cadence WHEN reviews stay bounded, and reviews stay bounded when specs are tight. The autonomy-ceiling thesis holds at the version altitude: the ceiling is review bandwidth, not point count or agent stamina. Ratified into the workflow: version size is now a review-cost dial (how many features carry design novelty), not a fixed point target. Two clean post-foundation velocity readings now exist (v2 = 26 shipped clean → the ceiling is at least 26).

2026-07-02 — model tiering: Sonnet 5 + Ultracode = build default (spec gates quality, not tier)

Call: the build-agent tier drops to Sonnet 5 + Ultracode as the default; reserve the top tier (Opus/Fable) for loosely-specced or novel-design features. Why: Sonnet 5 + Ultracode delivered v2's hardest feature (2-3, the 13-module generator) at full parity on independent reverification — byte-identical determinism, correct collision resolution, the 1:1 bridge intact, an honest diagnosis of a subtle incremental-vs-full-refresh failure, and an unprompted improvement (the inverse collision test). The load-bearing insight: spec quality gates build quality more than model tier. A tight, well-grounded spec let a cheaper model succeed on the hardest build. Review rigor scales up for a cheaper tier — cheap anyway when the spec is tight. Caveat (open): tested on a heavily-grounded feature; the real stress is a loosely-specced/novel one — revisit the tier call there.

2026-07-02 — the launch-location deviation is a HARNESS problem (recovery ≠ fix)

Lesson (recurring, unresolved). Both v2 dbt-writing agents (2-2, 2-3) launched in the main tree instead of their assigned worktree. Both recovered correctly (absolute-path writes, main tree verified pristine), and a mid-v2 doctrine fix taught recovery + STOP-and-report. But the fix does not prevent the wrong-tree start — the agent's cwd at launch is a harness behavior, not something the build protocol controls. Carried into v3 as a standing open item: the real fix is either a harness guarantee that an agent launches in its assigned cwd, or a hard first-line gate. A recovery instruction is a mitigation; it worked twice, but "worked because the agent was careful" is not a control.

2026-07-02 — grounding-before-committing corrected 3 of 3 top v3 candidates

Call: ground the top uncommitted roadmap candidates (parallel read-only agents) before committing them to a version. Why: every one of the three v3 candidates grounded (Snowflake port / S1 gold rewire / member-sat trio) had a one-line WSJF that masked a dependency or a factual error — the Snowflake branch was already merged (~60% pre-built, not "mine or retire"); S1 is coupled to S2; the member trio needs a net-new generator increment. Each correction changed the size/risk/sequencing. The WSJF ranking only stays useful if it tracks reality, and reality drifts under the board between seams — grounding is how the drift gets caught before it costs a mid-build STOP.

2026-07-02 — specs/ is clinical-only; the payer distillation is tracked debt

Call: record explicitly that specs/ (the rebuild-from truth) covers the CLINICAL estate only — the 2-1 audit was clinical-scoped, so the payer/membership/claims spine (7 of 15 hubs + their links/sats/dims/facts/marts) is not yet distilled into the by-layer docs. The payer semantics are complete in business-rules/; only the structural specs/ docs lag. Scoped as a dedicated v3 candidate ("Distill the payer layer into specs/"), the payer analog of the clinical audit. Why write it down: "moving the file ≠ distilling it" is the exact trap the version-close ritual warns about; naming the gap as a tracked feature is what keeps it from silently rotting as "done."

2026-07-02 — v2 2-1 delivered: the clinical audit (first review through the new gate)

Delivered: the R2 clinical audit — 52 clinical models audited against OP1–OP8; 9 specs/<layer>/ docs + 4 business-rules/clinical/ docs distilled; 45 consolidated schema entries split to 1:1 ymls (tests:→data_tests:); +10 additive key tests; 13 org-sim docs/specs/ files retired; green baseline reverified (PASS=730/ERROR=0, 613 tests). The headline finding (S1): the #30 concept-hub rework built the silver structures but never finished the gold half — fct_encounter/condition/medication still read the DV staging views, so the reworked hubs/links + pit_patient are DAG leaves. The audit surfaced and routed it (roadmap, WSJF 3.2) rather than redesigning mid-audit — the audit-observes-not-redesigns discipline held. Review independently reverified the build (not just the agent's report). The autonomy reading: L feature, zero STOPs, delivered whole — the spec's [mine] calls covered every fork; the delta was thin (one estimate correction, ~45→52 models).

2026-07-02 — lesson (already gazetteer-warned): status-flip-on-merge must be structural

Lesson (a corrected-call carry-forward). At the 2-1 merge, the status flip (building→delivered) slipped: a sed -i ran after git mv had already staged the file, so the commit carried the unmodified (still-building) version, and the board showed v2 0/4 after a successful merge. This is the EXACT bug gazetteer's v9 lesson named ("flip status when you merge") and its v11 lesson escalated ("a recorded lesson that isn't STRUCTURAL doesn't take"). Caught here by reading the board's own state immediately post-merge — the board being the check that surfaced it. Carried forward: the flip must be a single edit-then-stage-then-commit, verified by a board regen showing the expected delivered count, as the last step of every merge — not a separate sed pass. Candidate for a real guard (a merge helper, or a board drift-check that asserts every completed/ spec is status: delivered).

2026-07-02 — the purpose hierarchy written down: LEARNING.md is the true apex

Call: HDP gets a LEARNING.md (the gazetteer two-altitude pattern): PRIMARY = Dan learns and works on AI workflows; SECONDARY = a work-mirroring health data platform whose method transfers to BCI; alongside = structural experimentation (business keys, hub/link design); POTENTIAL = an MS capstone candidate (~1.5 yrs out, no commitment). No separate MISSION.md — the product mission already lives in architecture/0_winning_statement.md (rung 0); stating it twice would violate single-source-per-fact. When product and learning point different ways, learning wins. Why: without the apex written down, every workflow-instrument or experiment feature reads as scope creep against the demo mission — the same tie-breaker problem gazetteer solved 2026-06-10.

2026-07-02 — v2 sized as a deliberate point-ceiling experiment (26 pts)

Call: commit all four specs to v2 (26 pts, ~2× gazetteer's post-foundation cadence) as a ratified experiment: push the point limit of a version and measure whether features still ship quickly and regularly — the version-level sibling of the autonomy-ceiling experiment (that one sized the feature an agent carries; this sizes the version a conductor carries). Seam measurements: elapsed days, review-queue backup, rolled features. Escape hatch stands: re-slice mid-cycle without ceremony; rolling a feature is a measurement, not a failure. Why: regular shipping is the cadence goal; the binding constraint is review cost, and the only way to find the version ceiling is to push it deliberately with the surround (board, cockpit, build reports) now standing.

2026-07-02 — v1 seam: the full gazetteer workflow surround, ported in one pass

Call: at the v1 close, port the complete matured board (6 tabs, version roll-ups, Next-up, live-refresh, STATUS generation) plus the whole surround — roadmap.md (WSJF gate), bugs.md (the lighter defect lane), briefings/, this log, /score-idea — rather than growing them piecemeal. Why: v1 proved the build method transfers but ran with the surround absent (work was good but invisible; re-entry meant re-reading specs). The surround is what makes the method resumable and reviewable — and the board traveling project-to-project intact is the point of the portable-workflow direction. Also ratified: the two-level branch model (release/vN + phaseN-x/<feature>) starts at v2 — v1's one-branch-carries-all was the retro's #1 bite. Supersedes the trimmed 334-line bootstrap board.

2026-07-02 — v1 numbering backfilled; the re-foundation IS version 1

Call: the five delivered payer features get phase: 1-1…1-5; the re-foundation cycle closes as v1.0 (the repo's first tag); the next cycle is v2. Why: the board's version roll-up and velocity accounting need a version spine, and the re-foundation was in substance a complete version (structure + five features + capstone). v1's 34 pts is flagged a cold-start, not a cadence baseline.

2026-06-28 — the payer expansion's four locked design calls (D-A…D-D)

Call: provider identity resolves via cs_provider_same_as on name+specialty+state (D-A, no NPI in Synthea); separate provider and organization hubs, not a FACETS-style polymorphic PRPR (D-B); claims are seeded FROM Synthea encounters and bridged via l_claim_encounter (D-C); the network machinery collapses to a single h_network — no subgroup/class/capitation/covering-sets/zip-rules (D-D, "simpler than FACETS"). Why: each borrows data_domains' proven structure while cutting complexity no use case demanded; D-D is the standing scope discipline the roadmap's [facets-depth] rows defer to. Recorded in implementation/discovery/payer_source_expansion.md.

2026-06-27/28 — sequencing inversion: the payer expansion leapfrogged the clinical audit

Lesson (a corrected-call carry-forward). The refoundation plan named the clinical audit (R2) "the FIRST real work," but the build momentum ran the R3 payer expansion first — five features in two days — and the audit debt carried forward (now v2's 2-1). It worked out, but the inversion was never written down at the time; the v1→v2 retro reconstructed it after the fact. When you consciously invert a plan, log the inversion the moment you make it.

2026-06-28 — the claims business key is source-qualified (the OP4 exception, exercised)

Call: claim identity = claim ID qualified by source system — the deliberate exception to source-neutral business keys, because transactional IDs (claims, premium bills) are collision-prone across source systems. Why: this is the OP4 operating principle inherited from the data_domains standard; HDP exists to exercise exactly this kind of work-shaped rule on synthetic data. The two-source synthetic fiction (legacy/gemstone-style) that makes the collision REAL is committed for v2's generator (D3 in feature_synthetic_data_generator.md).

2026-06-27 — the re-foundation structure: four first-class folders, org-sim relocated not discarded

Call: repo root gets four first-class documentation citizens — architecture/ (the why: the Roger Martin strategy stack), business-rules/ (the platform-agnostic what-the-business-means), specs/ (the rebuild-from truth, mirroring dbt/models/), implementation/ (the doing: funnel + build records; renamed from planning/ because it captures the build, not just the plan). The old org-sim (epic/feature/story, role-agents, gates) survives as a documented altitude mapping in architecture/README.md, not as build ceremony. Why: the org-sim's ceremony was coordination technology for many hands; solo, keep the altitudes and the one human-gated review, drop the tickets. The single feature spec (Summation + [mine]/[agent] Decisions + Detail) replaces the epic/feature/story trio.

2026-06-27 — business rules are a first-class layer, separate from architecture

Call: business semantics ("a claim can't be paid before it's adjudicated") live in business-rules/, platform-agnostically — NOT in architecture/ (methodology) and NOT only-in-the-SQL. Why: a business rule outlives the tech stack that executes it; stating it separately is what makes the platform regenerable/migratable (move-and-improve re-derives the implementation from the stated rule). The implementation is validated against the prose — a contract first exercised deliberately in v2's rules pass.

2026-07-06 — the platform gets a home: danbrickey.dev landing + hdp subdomain live (0.11.2)

Call: the apex danbrickey.dev now serves a radically-basic personal landing page (its own Vercel project, root = landing/, bound via a Cloudflare CNAME-flatten at the root), and HDP is served at hdp.danbrickey.dev (the custom subdomain added to the existing HDP Vercel project, mirroring gazetteer's setup on the same domain). The landing links to the live projects — HDP (hdp.danbrickey.dev) and gazetteer (gazetteer.danbrickey.dev). Two deliberate content calls: the GitHub source link was removed (repo stays private for now) and the page stays a plain launchpad, not a portfolio site (that's the meta-repo vision, later). Why: this is the "PUBLISHED" half of initiative 0's exit criteria (init 0 = platform standing + demo-ready + published) and the first brick of the idea→publish portfolio pipeline. The agent/Dan split held as designed — the agent built + locally verified the page, Dan did the registrar/Vercel binding (a hard boundary: no agent login). Ops footnote: the landing/ folder was brought to main early to unblock Vercel's production-branch folder-picker, and its copy on release/0.11 was synced to match so the 0.11-close merge stays conflict-free. (0.11.2 delivered; 0.11.3 = the remaining board views is next.)

2026-07-06 — 0.11 closed: the reading-first layout + publish-last ritual + a visitor-presentation initiative

Call: 0.11 shipped the reading-first board (0.11.1 shell + 0.11.3 the remaining views) and the danbrickey.dev landing (0.11.2) — completing init-0's UI + published half. Three structural decisions came with it: (1) the reading-first master-detail layout replaced the full-width bottom panel (the panel was "inherited water" from the v1 board — re-chosen against once the pane existed); the column-format migration self-corrected the view set (Decisions + Review Queue → the Inbox; Cockpit → Activity). (2) The close ritual was reordered to publish-LAST — scope the next version BEFORE deploying, so the public board ships a forward-looking snapshot (this version done + the next staged) instead of a stale backward-only one; first exercised here in a scope-first flow. (3) A visitor-presentation initiative was recognized (0.12 board-pages + 0.13 front-door), triggered by Dan reviewing the board as its first playtest — the board is now functional enough that its static pages can deload. Why: the board maturing means it takes over the "where is everything" reference role, so STATUS/roadmap shrink and the exhaustive material moves to the board (interactive) or appendices; and a portfolio board is only as good as its forward story, so the roadmap became a first-class release artifact (the publish-last principle). Standing app-era earmarks logged in ideas.md (Planning view, two-way board, feature permalinks / decouple-location-from-state) as the board approaches its static-HTML ceiling — the board-app graduation is the next-initiative arc.

2026-07-07 — 0.12 closed: the board carries the reference role; the wrong-tree launch solved at orchestration

Call: 0.12 ("Swept workshop") shipped 3/3 — the History view (delivered features browsable, Version Arc as pane-default), the STATUS deload (blurb + launchpad + listing + appendices; the inflight/done GENERATED blocks retired), and the roadmap prose deload (orientation prose; ranked table moved to the bottom; the Delivered ledger deleted, not archived). Three structural decisions came with it: (1) the board is now the single reference surface — "what shipped" lives in completed/ rendered through the History view; STATUS and the roadmap are narratives + launchpads, so there is one less hand-maintained ledger to drift. (2) The wrong-tree build launch is solved at the orchestration layer: the orchestrator enters the feature worktree BEFORE spawning the build agent, so the agent inherits the correct cwd and its location self-check passes first-try (the 0.12.1 first launch proved the guardrail STOPs correctly; the 0.12.2 launch proved the fix). (3) Cross-feature integration risks get named in the handoff — 0.12.2's restructure of STATUS.md could have broken 0.12.1's Version-arc extraction; one sentence in the handoff turned a review surprise into a verified DoD line. Seam sweep: seven v4–v6 delivered docs finally moved backlog/ → completed/ (pre-existing drift the board's stem-resolution had masked). Why: the visitor-presentation initiative's inner half is done — the board's own pages read for a cold visitor without losing the working feel; 0.13 (front door: Anchor Health branding + landing revamp) completes the outer half.

2026-07-08 — 0.13 closed: the front door + the artifact-graduation pattern; 0.14 returns to data-platform depth

Call: 0.13 ("Front door") shipped 2/2 — Anchor Health branding wired into the Evidence dashboard (0.13.1) + the danbrickey.dev landing revamp (0.13.2) — completing the visitor-presentation initiative (0.12 board pages + 0.13 front door). Four decisions came with it: (1) the artifact-graduation pattern — the landing outgrew the monorepo and graduated to its own PUBLIC repo (github.com/danbrickey/danbrickey.dev): it's Dan's portfolio front door, a peer to the project repos, and a public page shouldn't live in the private HDP repo. The build record + design package stay in HDP as provenance; the idea→publish portfolio pipeline now exists end to end. (2) The branch-naming convention is fully-dotted phase<I.V.F>/<feature> — the hybrid phase0.13-1/ used this session matched neither of the board parser's patterns (dotted or legacy-integer), so features never lit up as BUILDING; caught by dogfooding the board, fixed + documented in CLAUDE.md. (3) A version's size is not its feature count — 0.13 was 2 features but carried a heavy domain/DNS/email infrastructure slab (canonical danbrickey.dev + redirects + dan@brickey.dev email routing on Cloudflare + the Cloudflare MCP install + the Vercel repoint). (4) 0.14 deliberately returns to data-platform depth (premium billing — real DV2.0/Kimball) after five versions of board/tooling/presentation: the winning statement is a governed DV2.0 platform, and the recent arc built the shop window, not the goods. Why: the presentation layer is now complete (front door + board pages read for a cold visitor); the highest-leverage next work is the BCI-transferable data engineering the platform exists to demonstrate. The board-app graduation (static-HTML ceiling) remains the looming tooling arc, consciously deferred.

2026-07-08 — 0.14 closed: the money lifecycle + the verify step as the version's hero

Call: 0.14 ("Premium billing" — the return to data-platform depth) shipped 3/3 — generator realism v3 (0.14.1: the aligned, current substrate), premium billing (0.14.2: the money-in DV2.0 estate + fct_premium_month), and the loss-ratio reconciliation page (0.14.3: blended MLR 0.8525, verifiable live). It's the first version since ~v6–v8 to grow the DATA CORE — the platform now models the money lifecycle (premium in → claims out → a loss ratio that looks like one). Several decisions came with it: (1) The verify step is a first-class actor, and it earned it — premium billing was built structurally flawless (937 tests green, every reconciliation passing) yet reported a wrong MLR TWICE (a verification-method bug: 0.85 that was really 1.01; then a coherence artifact: blended 0.85 propped up by $207K of claims for never-covered members). Tests + reconciliation did NOT catch it; independent re-derivation from the data did, both times. This is the demo thesis — "the AI built it, and here's the check that caught the AI's own wrong number." (2) DR08 — uninsured = self-pay — a never-covered member's claim has plan-paid $0 (they self-pay); the claim + charge/allowed stay. A business-truth data ruling (Dan) that made the MLR coherent (blended = per-segment). (3) The data-realism lane (DR01–08) is the permanent iterative substrate, and the MLR doubles as a standing realism check (a wrong ratio is a data problem). (4) Risk adjustment grounded → 0.15's headliner (SNOMED → a hand-curated chronic-only risk mapping → a member risk score, surfaced three ways). Why: the platform's mission is a governed claims+clinical DV2.0 estate demonstrated by one AI-leveraged architect; 0.14 is the proof that the engineering — not just the presentation — holds up under independent verification. The specs/ distillation of the 0.14 models is the carried-forward close task (interim record: completed/ + business-rules/premium/).

2026-07-09 — the feature board is handed off to its own repo (Vantage); HDP's board is frozen

Call: The feature board is officially graduating out of HDP into its own repository — the new app-version is named Vantage. HDP's board (scripts/build_board.py + docs/board.html, the 4,358-line monolith at its static-HTML ceiling) is now FROZEN: maintenance / bug-fix only, no feature development. All board feature effort moves to Vantage (a parallel repo, kicked off 2026-07-09 with a handoff package). Accordingly the board-improvement candidates are removed from HDP's roadmap — light mode (feature_theme_light_mode.md) and CSS tokenization (feature_theme_tokens.md) removed today; the roadmap-table-refactor was removed 2026-07-09 (Dan confirmed the freeze covers it too). Their candidate files are preserved as Vantage's seed reference (per the handoff). The feature_board_graduation roadmap row is retained as a HANDED-OFF marker (like the landing-page graduation at 0.13). Why: the monolith "doesn't always update / show the latest state" and has outgrown a build-step-generated static page; it already lives in two repos (HDP + gazetteer) and should serve the whole portfolio. Running it as its own repo decouples board development from HDP's cadence — board effort no longer competes on HDP's roadmap. This is the 2nd graduation after the landing page (0.13), extending the idea→publish portfolio pipeline. Vantage carries its own governance (not HDP's, and not the parent EDP data-domains constitution). See [[board_meta_repository_vision]] + the handoff package.