---
phase: 05-documentation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - scripts/CLAUDE.md
  - python/opendeviationbar/kintsugi/CLAUDE.md
  - scripts/heartbeat/CLAUDE.md
  - python/opendeviationbar/CLAUDE.md
  - CLAUDE.md
autonomous: true
requirements: [DOC-01]

must_haves:
  truths:
    - "scripts/CLAUDE.md documents seeder day-boundary backfill mechanism"
    - "kintsugi/CLAUDE.md documents Parquet trust verification gate"
    - "heartbeat/CLAUDE.md documents dynamic symbol coverage from registry"
    - "python/opendeviationbar/CLAUDE.md lists crossover.py in file mapping"
    - "Root CLAUDE.md references day-boundary completeness in monitoring table"
  artifacts:
    - path: "scripts/CLAUDE.md"
      provides: "Seeder day-boundary backfill documentation"
      contains: "_backfill_yesterday_boundary"
    - path: "python/opendeviationbar/kintsugi/CLAUDE.md"
      provides: "Parquet trust gate documentation"
      contains: "crossover_tid"
    - path: "scripts/heartbeat/CLAUDE.md"
      provides: "Dynamic symbol coverage documentation"
      contains: "get_heartbeat_symbols"
    - path: "python/opendeviationbar/CLAUDE.md"
      provides: "crossover.py in file mapping"
      contains: "crossover.py"
    - path: "CLAUDE.md"
      provides: "Day-boundary completeness in monitoring layers"
      contains: "day-boundary"
  key_links:
    - from: "CLAUDE.md"
      to: "scripts/CLAUDE.md"
      via: "CLAUDE.md network hub-and-spoke"
      pattern: "scripts/CLAUDE.md"
    - from: "CLAUDE.md"
      to: "python/opendeviationbar/CLAUDE.md"
      via: "CLAUDE.md network hub-and-spoke"
      pattern: "python/opendeviationbar/CLAUDE.md"
---

<objective>
Document the v5.0 day-boundary completeness guarantee across the CLAUDE.md network.

Purpose: The CLAUDE.md network is the single source of truth for project knowledge. Phases 1-4 added a shared crossover TID utility, seeder day-boundary backfill, kintsugi Parquet trust gate, and dynamic heartbeat symbol coverage. These must be documented so future sessions understand the mechanisms.

Output: 5 updated CLAUDE.md files reflecting v5.0 changes.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md

@.planning/phases/01-crossover-tid-utility/01-01-SUMMARY.md
@.planning/phases/02-seeder-day-boundary-backfill/02-01-SUMMARY.md
@.planning/phases/03-kintsugi-parquet-trust/03-01-SUMMARY.md
@.planning/phases/04-heartbeat-coverage/04-01-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Update spoke CLAUDE.md files (scripts, kintsugi, heartbeat, python layer)</name>
  <read_first>
    - scripts/CLAUDE.md (full file -- find the Exness seeder section and Kintsugi section to place new seeder boundary docs nearby)
    - python/opendeviationbar/kintsugi/CLAUDE.md (full file -- find repair flow section to add Parquet trust gate)
    - scripts/heartbeat/CLAUDE.md (full file -- find the config section to add dynamic symbol docs)
    - python/opendeviationbar/CLAUDE.md (lines 40-80 -- File-to-Responsibility Mapping table to add crossover.py)
    - python/opendeviationbar/crossover.py (first 30 lines -- get the actual function signature and docstring)
    - scripts/tick_cache_seeder.py (grep for _backfill_yesterday_boundary to get signature and docstring)
    - python/opendeviationbar/kintsugi/repair.py (grep for crossover_tid to see how the gate works)
    - scripts/heartbeat/config.py (grep for get_heartbeat_symbols to get signature)
  </read_first>
  <files>
    scripts/CLAUDE.md
    python/opendeviationbar/kintsugi/CLAUDE.md
    scripts/heartbeat/CLAUDE.md
    python/opendeviationbar/CLAUDE.md
  </files>
  <action>
    **scripts/CLAUDE.md** -- Add a new section "## Seeder Day-Boundary Backfill (v5.0)" near the existing seeder documentation. Document:
    - The root cause: seeder's 5-min cycle stops ~5 min before midnight, leaving yesterday's Parquet file missing trades from the last cycle through the crossover TID boundary
    - The fix: `_backfill_yesterday_boundary()` in `tick_cache_seeder.py` runs at the top of each `_seed_symbol()` call for spot market symbols
    - How it works: checks yesterday's Parquet `max(agg_trade_id)` against `crossover_tid - 1` from the shared `get_crossover_tid()` utility, fetches missing trailing trades via Binance REST if incomplete
    - State marker dedup: `~/.cache/opendeviationbar/seeder-state/{symbol}_boundary_{date}.done` prevents redundant backfill within the same UTC day
    - Complete files also get a state marker to skip crossover TID REST lookup on subsequent 5-min invocations

    **python/opendeviationbar/kintsugi/CLAUDE.md** -- Add a "## Parquet Trust Gate (v5.0)" section after the Writer Ownership section. Document:
    - Before day-recompute, kintsugi verifies `max(agg_trade_id) >= crossover_tid - 1` on the Parquet file via the shared `get_crossover_tid()` utility
    - Incomplete Parquet files fall back to Vision/REST with WARNING log
    - Crossover lookup failure (None) proceeds with Parquet anyway with DEBUG log (graceful degradation -- don't block repair when API is down)
    - Last bar in both Parquet and Vision repair paths marked `is_orphan=True` (day boundary incomplete bar)
    - Gate runs AFTER ticks are loaded to avoid double-reading the Parquet file

    **scripts/heartbeat/CLAUDE.md** -- Add a "## Dynamic Symbol Coverage (v5.0)" section after the Alert Deduplication section. Document:
    - `get_heartbeat_symbols()` in `config.py` dynamically queries symbol registry for all enabled Binance spot symbols
    - Uses `lru_cache(maxsize=1)` -- heartbeat is a 5-min oneshot, no stale-cache risk
    - Exness forex symbols excluded (no agg_trade_id, cannot do Stathera checks)
    - Graceful fallback to (BTCUSDT, ETHUSDT) on any exception -- heartbeat must never crash
    - `HEARTBEAT_PRIORITY_SYMBOLS` kept for backward compat (freshness.py display ordering) but deprecated in favor of dynamic lookup
    - Yesterday completion check now runs for all 17+ streaming symbols, not just BTC/ETH

    **python/opendeviationbar/CLAUDE.md** -- Add `crossover.py` row to the File-to-Responsibility Mapping table:
    - `crossover.py` | Shared crossover TID lookup: `get_crossover_tid(symbol, date)` (v5.0, extracted from sidecar)

  </action>
  <verify>
    <automated>grep -c "_backfill_yesterday_boundary" scripts/CLAUDE.md && grep -c "crossover_tid" python/opendeviationbar/kintsugi/CLAUDE.md && grep -c "get_heartbeat_symbols" scripts/heartbeat/CLAUDE.md && grep -c "crossover.py" python/opendeviationbar/CLAUDE.md</automated>
  </verify>
  <done>
    - scripts/CLAUDE.md has a seeder day-boundary backfill section with _backfill_yesterday_boundary, state marker, and crossover TID details
    - kintsugi/CLAUDE.md has a Parquet trust gate section with completeness check, fallback behavior, and orphan marking
    - heartbeat/CLAUDE.md has a dynamic symbol coverage section with get_heartbeat_symbols, fallback, and lru_cache details
    - python/opendeviationbar/CLAUDE.md lists crossover.py in the file mapping table
  </done>
</task>

<task type="auto">
  <name>Task 2: Update root CLAUDE.md with v5.0 monitoring and terminology</name>
  <read_first>
    - CLAUDE.md (lines 240-280 -- monitoring table with L1-L8 layers)
    - CLAUDE.md (lines 320-340 -- Terminology table with Crossover TID entry)
  </read_first>
  <files>
    CLAUDE.md
  </files>
  <action>
    **Root CLAUDE.md** -- Two targeted updates:

    1. **Monitoring table (### Monitoring and Gap Prevention)**: Add a new row L9 after L8:
       - L9 | Seeder day-boundary backfill: Parquet `max(tid) == crossover_tid - 1` | `tick_cache_seeder.py`
       Update the intro text "8 protection layers (v1.4)" to "9 protection layers (v5.0)".

    2. **Terminology table**: Update the "Crossover TID" entry to mention it is now a shared utility:
       - Change from sidecar-specific ("Used by midnight preflight") to shared ("Queried via shared `get_crossover_tid()` utility (v5.0). Used by sidecar midnight preflight, seeder day-boundary backfill, kintsugi Parquet trust gate, and heartbeat yesterday completion check.")

    Do NOT rewrite unrelated sections. Make surgical edits only.

  </action>
  <verify>
    <automated>grep -c "L9" CLAUDE.md && grep -c "get_crossover_tid" CLAUDE.md && grep -c "9 protection layers" CLAUDE.md</automated>
  </verify>
  <done>
    - Root CLAUDE.md monitoring table has L9 row for seeder day-boundary backfill
    - Root CLAUDE.md intro text says "9 protection layers (v5.0)"
    - Root CLAUDE.md Crossover TID terminology updated to reference shared utility and all 4 consumers
  </done>
</task>

</tasks>

<verification>
All 5 CLAUDE.md files updated with v5.0 documentation:
1. `grep "_backfill_yesterday_boundary" scripts/CLAUDE.md` -- seeder boundary docs
2. `grep "Parquet Trust Gate" python/opendeviationbar/kintsugi/CLAUDE.md` -- kintsugi gate docs
3. `grep "get_heartbeat_symbols" scripts/heartbeat/CLAUDE.md` -- dynamic symbol docs
4. `grep "crossover.py" python/opendeviationbar/CLAUDE.md` -- module map entry
5. `grep "L9" CLAUDE.md` -- monitoring layer added
6. `grep "get_crossover_tid" CLAUDE.md` -- terminology updated
</verification>

<success_criteria>

- DOC-01 satisfied: root cause + fix documented in scripts/CLAUDE.md (seeder boundary), kintsugi/CLAUDE.md (Parquet trust), heartbeat/CLAUDE.md (dynamic symbols), and root CLAUDE.md (monitoring table + terminology)
- All new sections reference v5.0 for traceability
- No unrelated sections modified
  </success_criteria>

<output>
After completion, create `.planning/phases/05-documentation/05-01-SUMMARY.md`
</output>
