---
phase: 03-claude-md-hub-and-spoke-network-audit-create-missing-spokes-update-root-hub
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/CLAUDE.md
  - python/opendeviationbar/sidecar/CLAUDE.md
  - python/opendeviationbar/kintsugi/CLAUDE.md
  - python/opendeviationbar/checkpoint/CLAUDE.md
autonomous: true
requirements: [SPOKE-SRC, SPOKE-SIDECAR, SPOKE-KINTSUGI, SPOKE-CHECKPOINT]

must_haves:
  truths:
    - "src/CLAUDE.md exists with Parent link to /CLAUDE.md and file-to-module table for all 11 .rs files"
    - "sidecar/CLAUDE.md exists with Parent link to python/opendeviationbar/CLAUDE.md and file table for all 12 files"
    - "kintsugi/CLAUDE.md exists with Parent link to python/opendeviationbar/CLAUDE.md and file table for all 9 files"
    - "checkpoint/CLAUDE.md exists with Parent link to python/opendeviationbar/CLAUDE.md and file table for 4 files"
  artifacts:
    - path: "src/CLAUDE.md"
      provides: "PyO3 bindings spoke"
      contains: "**Parent**"
    - path: "python/opendeviationbar/sidecar/CLAUDE.md"
      provides: "Streaming sidecar spoke"
      contains: "**Parent**"
    - path: "python/opendeviationbar/kintsugi/CLAUDE.md"
      provides: "Gap reconciliation spoke"
      contains: "**Parent**"
    - path: "python/opendeviationbar/checkpoint/CLAUDE.md"
      provides: "Resumable population spoke"
      contains: "**Parent**"
  key_links:
    - from: "src/CLAUDE.md"
      to: "/CLAUDE.md"
      via: "Parent header link"
      pattern: "\\*\\*Parent\\*\\*.*CLAUDE\\.md"
    - from: "python/opendeviationbar/sidecar/CLAUDE.md"
      to: "/python/opendeviationbar/CLAUDE.md"
      via: "Parent header link"
      pattern: "\\*\\*Parent\\*\\*.*CLAUDE\\.md"
---

<objective>
Create CLAUDE.md spoke files for the 4 highest-complexity missing directories: src/ (PyO3 bindings), sidecar/ (streaming sidecar package), kintsugi/ (gap reconciliation package), and checkpoint/ (resumable population package).

Purpose: These are the 4 largest missing spokes (2,200-4,900 LOC each), all recently modularized or core infrastructure. AI agents working in these directories currently get no directory-level context.
Output: 4 new CLAUDE.md files following the established spoke pattern.
</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/03-claude-md-hub-and-spoke-network-audit-create-missing-spokes-update-root-hub/03-RESEARCH.md

@CLAUDE.md
@python/opendeviationbar/CLAUDE.md
@crates/CLAUDE.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create src/CLAUDE.md and sidecar/CLAUDE.md spokes</name>
  <files>src/CLAUDE.md, python/opendeviationbar/sidecar/CLAUDE.md</files>
  <read_first>
    src/lib.rs
    src/core_bindings.rs
    src/arrow_bindings.rs
    src/binance_bindings.rs
    src/exness_bindings.rs
    src/streaming_bindings.rs
    src/stream_manager_bindings.rs
    src/gap_bindings.rs
    src/odb_engine_bindings.rs
    src/helpers.rs
    src/thread_pool_init.rs
    python/opendeviationbar/sidecar/__init__.py
    python/opendeviationbar/sidecar/midnight.py
    python/opendeviationbar/sidecar/http_server.py
    python/opendeviationbar/sidecar/checkpoint.py
    python/opendeviationbar/sidecar/clickhouse_write.py
    python/opendeviationbar/sidecar/config_helpers.py
    python/opendeviationbar/sidecar/dead_letter.py
    python/opendeviationbar/sidecar/notifications.py
    python/opendeviationbar/sidecar/recovery.py
    python/opendeviationbar/sidecar/yesterday_signal.py
    python/opendeviationbar/clickhouse/CLAUDE.md
    python/opendeviationbar/storage/CLAUDE.md
  </read_first>
  <action>
    Create two CLAUDE.md spoke files following the established pattern from the 03-RESEARCH.md spoke template.

    **src/CLAUDE.md:**
    - `**Parent**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: PyO3 bindings layer bridging Rust crates to Python module
    - `## Files` table with all 11 .rs files and their actual purposes (read each file to determine)
    - `## Module Registration` section documenting the pattern in lib.rs (how #[pymodule] works, submodule structure)
    - `## Binding Naming Convention` section (each `*_bindings.rs` maps to a domain)
    - `## Build` section with `maturin develop` command
    - `## Related` section linking to /CLAUDE.md (hub) and /crates/CLAUDE.md (Rust types being bound)
    - DO NOT duplicate content from root CLAUDE.md architecture section -- focus on binding-specific knowledge

    **python/opendeviationbar/sidecar/CLAUDE.md:**
    - `**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Streaming sidecar package orchestrating real-time bar generation
    - `## Files` table with all 12 files and their actual purposes (read each file to determine)
    - `## Startup Sequence` section referencing the invariant from root CLAUDE.md (#294, #295) but documenting which files implement which steps
    - `## Writer Ownership` section documenting sidecar's "owns today" role
    - `## Related` section linking to parent, hub, /scripts/systemd/CLAUDE.md (service config), /deploy/CLAUDE.md (monitoring)
    - DO NOT duplicate the full startup sequence from root CLAUDE.md -- reference it and add file-level mapping

  </action>
  <verify>
    <automated>grep -c '**Parent**' src/CLAUDE.md python/opendeviationbar/sidecar/CLAUDE.md 2>/dev/null | grep -v ':0$' | wc -l | grep -q 2 && echo "PASS: Both spokes have Parent header" || echo "FAIL"</automated>
  </verify>
  <acceptance_criteria>
    - src/CLAUDE.md contains `**Parent**: [/CLAUDE.md](/CLAUDE.md)`
    - src/CLAUDE.md has a Files table with rows for: lib.rs, core_bindings.rs, arrow_bindings.rs, binance_bindings.rs, exness_bindings.rs, streaming_bindings.rs, stream_manager_bindings.rs, gap_bindings.rs, odb_engine_bindings.rs, helpers.rs, thread_pool_init.rs
    - src/CLAUDE.md has `## Related` section with link to /crates/CLAUDE.md
    - sidecar/CLAUDE.md contains `**Parent**: [/python/opendeviationbar/CLAUDE.md]`
    - sidecar/CLAUDE.md has a Files table with rows for all 12 files in the sidecar/ directory
    - sidecar/CLAUDE.md has `## Related` section
    - Neither file contains generic boilerplate like "utility functions" or "helper module"
  </acceptance_criteria>
  <done>Both src/CLAUDE.md and sidecar/CLAUDE.md exist with correct Parent links, complete file tables derived from reading actual source, domain-specific sections, and Related links.</done>
</task>

<task type="auto">
  <name>Task 2: Create kintsugi/CLAUDE.md and checkpoint/CLAUDE.md spokes</name>
  <files>python/opendeviationbar/kintsugi/CLAUDE.md, python/opendeviationbar/checkpoint/CLAUDE.md</files>
  <read_first>
    python/opendeviationbar/kintsugi/__init__.py
    python/opendeviationbar/kintsugi/orchestrator.py
    python/opendeviationbar/kintsugi/discovery.py
    python/opendeviationbar/kintsugi/repair.py
    python/opendeviationbar/kintsugi/verify.py
    python/opendeviationbar/kintsugi/daemon.py
    python/opendeviationbar/kintsugi/dead_letter.py
    python/opendeviationbar/kintsugi/telemetry.py
    python/opendeviationbar/kintsugi/_helpers.py
    python/opendeviationbar/checkpoint/__init__.py
    python/opendeviationbar/checkpoint/engine.py
    python/opendeviationbar/checkpoint/models.py
    python/opendeviationbar/checkpoint/storage.py
  </read_first>
  <action>
    Create two CLAUDE.md spoke files following the established pattern.

    **python/opendeviationbar/kintsugi/CLAUDE.md:**
    - `**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Gap reconciliation package implementing Stathera-driven discovery, repair, and verification
    - `## Files` table with all 9 Python files and their actual purposes
    - `## Discovery-Repair-Verify Flow` section documenting the pipeline: discovery.py finds shards -> repair.py fixes them -> verify.py confirms Stathera integrity
    - `## Writer Ownership` section: kintsugi owns yesterday and older, today-guard is ABSOLUTE
    - `## Shard Sort Key` section: `(-gap_end_ms, symbol_rank)` -- newest first, BTCUSDT priority
    - `## Related` section linking to parent, hub, /scripts/CLAUDE.md (daemon config), /python/opendeviationbar/clickhouse/CLAUDE.md (write operations)
    - DO NOT duplicate the full kintsugi explanation from root CLAUDE.md -- focus on file-level architecture

    **python/opendeviationbar/checkpoint/CLAUDE.md:**
    - `**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Resumable population engine with checkpoint persistence
    - `## Files` table with all 4 files and their actual purposes
    - `## Checkpoint Flow` section: engine.py drives population, models.py defines checkpoint data structures, storage.py persists to ClickHouse
    - `## Memory Guards` section referencing MEM-013 bounded flush from root CLAUDE.md
    - `## Related` section linking to parent, hub, /python/opendeviationbar/clickhouse/CLAUDE.md (storage backend)

  </action>
  <verify>
    <automated>grep -c '**Parent**' python/opendeviationbar/kintsugi/CLAUDE.md python/opendeviationbar/checkpoint/CLAUDE.md 2>/dev/null | grep -v ':0$' | wc -l | grep -q 2 && echo "PASS" || echo "FAIL"</automated>
  </verify>
  <acceptance_criteria>
    - kintsugi/CLAUDE.md contains `**Parent**: [/python/opendeviationbar/CLAUDE.md]`
    - kintsugi/CLAUDE.md has a Files table with rows for all 9 files
    - kintsugi/CLAUDE.md has `## Related` section
    - checkpoint/CLAUDE.md contains `**Parent**: [/python/opendeviationbar/CLAUDE.md]`
    - checkpoint/CLAUDE.md has a Files table with rows for all 4 files (including __init__.pyi)
    - checkpoint/CLAUDE.md has `## Related` section
    - Both files reference actual function names and patterns from reading the source
  </acceptance_criteria>
  <done>Both kintsugi/CLAUDE.md and checkpoint/CLAUDE.md exist with correct Parent links, complete file tables, domain-specific flow documentation, and Related links.</done>
</task>

</tasks>

<verification>
All 4 CLAUDE.md files exist and pass:
1. `grep -l 'Parent' src/CLAUDE.md python/opendeviationbar/sidecar/CLAUDE.md python/opendeviationbar/kintsugi/CLAUDE.md python/opendeviationbar/checkpoint/CLAUDE.md` returns all 4 paths
2. Each file has a `## Files` table with correct file count
3. Each file has a `## Related` section
4. No file contains generic boilerplate
</verification>

<success_criteria>
4 new CLAUDE.md spokes created for the highest-complexity directories (src, sidecar, kintsugi, checkpoint), each with correct Parent links, source-derived file tables, and domain-specific sections.
</success_criteria>

<output>
After completion, create `.planning/phases/03-claude-md-hub-and-spoke-network-audit-create-missing-spokes-update-root-hub/03-01-SUMMARY.md`
</output>
