---
phase: 03-claude-md-hub-and-spoke-network-audit-create-missing-spokes-update-root-hub
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - python/opendeviationbar/validation/CLAUDE.md
  - python/opendeviationbar/processors/CLAUDE.md
  - scripts/heartbeat/CLAUDE.md
  - scripts/heartbeat/checks/CLAUDE.md
autonomous: true
requirements: [SPOKE-VALIDATION, SPOKE-PROCESSORS, SPOKE-HEARTBEAT]

must_haves:
  truths:
    - "validation/CLAUDE.md exists as intermediate parent between python/opendeviationbar/CLAUDE.md and validation/day_mode/CLAUDE.md"
    - "processors/CLAUDE.md exists with Parent link and file table for api.py and core.py"
    - "heartbeat/CLAUDE.md exists with Parent link to scripts/CLAUDE.md and file table"
    - "heartbeat/checks/CLAUDE.md exists with Parent link to heartbeat/CLAUDE.md and table listing all 13 check modules"
    - "validation/day_mode/CLAUDE.md Parent updated to point to validation/CLAUDE.md (not grandparent)"
  artifacts:
    - path: "python/opendeviationbar/validation/CLAUDE.md"
      provides: "Validation framework spoke"
      contains: "**Parent**"
    - path: "python/opendeviationbar/processors/CLAUDE.md"
      provides: "Trade processors spoke"
      contains: "**Parent**"
    - path: "scripts/heartbeat/CLAUDE.md"
      provides: "Health heartbeat spoke"
      contains: "**Parent**"
    - path: "scripts/heartbeat/checks/CLAUDE.md"
      provides: "Heartbeat check modules spoke"
      contains: "**Parent**"
  key_links:
    - from: "python/opendeviationbar/validation/day_mode/CLAUDE.md"
      to: "python/opendeviationbar/validation/CLAUDE.md"
      via: "Updated Parent header"
      pattern: "\\*\\*Parent\\*\\*.*validation/CLAUDE\\.md"
    - from: "scripts/heartbeat/checks/CLAUDE.md"
      to: "scripts/heartbeat/CLAUDE.md"
      via: "Parent header link"
      pattern: "\\*\\*Parent\\*\\*.*heartbeat/CLAUDE\\.md"
---

<objective>
Create CLAUDE.md spoke files for 4 more directories: validation/ (intermediate parent), processors/, heartbeat/, and heartbeat/checks/. Also update validation/day_mode/CLAUDE.md to point to the new intermediate parent.

Purpose: validation/ is critical because it creates a proper intermediate parent for the existing day_mode/ spoke. heartbeat/ and heartbeat/checks/ are 2-level deep with 13+ check modules that need documentation. processors/ handles all trade processing.
Output: 4 new CLAUDE.md files + 1 updated CLAUDE.md (day_mode parent fix).
</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
@scripts/CLAUDE.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create validation/CLAUDE.md, processors/CLAUDE.md, and fix day_mode parent</name>
  <files>python/opendeviationbar/validation/CLAUDE.md, python/opendeviationbar/processors/CLAUDE.md, python/opendeviationbar/validation/day_mode/CLAUDE.md</files>
  <read_first>
    python/opendeviationbar/validation/__init__.py
    python/opendeviationbar/validation/tier1.py
    python/opendeviationbar/validation/tier2.py
    python/opendeviationbar/validation/continuity.py
    python/opendeviationbar/validation/gap_classification.py
    python/opendeviationbar/validation/cache_staleness.py
    python/opendeviationbar/validation/post_storage.py
    python/opendeviationbar/validation/schemas.py
    python/opendeviationbar/validation/day_mode/CLAUDE.md
    python/opendeviationbar/processors/__init__.py
    python/opendeviationbar/processors/api.py
    python/opendeviationbar/processors/core.py
  </read_first>
  <action>
    **python/opendeviationbar/validation/CLAUDE.md:**
    - `**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Validation framework for bar integrity, Stathera continuity, gap classification, and day-mode enforcement
    - `## Files` table with all files: __init__.py, tier1.py, tier2.py, continuity.py, gap_classification.py, cache_staleness.py, post_storage.py, schemas.py
    - `## Validation Tiers` section: tier1.py (fast structural checks) vs tier2.py (deep statistical checks) -- read files to determine exact distinction
    - `## Stathera Continuity` section: continuity.py implements the trade-ID alignment invariant
    - `## Gap Classification` section: gap_classification.py taxonomy of gap types
    - `## Children` section: link to validation/day_mode/CLAUDE.md
    - `## Related` section linking to parent, hub

    **python/opendeviationbar/processors/CLAUDE.md:**
    - `**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Trade processing pipeline bridging raw trades to open deviation bars
    - `## Files` table: __init__.py, api.py, core.py
    - `## Processing Pipeline` section: how api.py provides the high-level API and core.py implements the processing logic using Rust PyOpenDeviationBarProcessor
    - `## Related` section linking to parent, hub, /crates/CLAUDE.md (Rust processor)

    **Update python/opendeviationbar/validation/day_mode/CLAUDE.md:**
    - Change `**Parent**:` from `/python/opendeviationbar/CLAUDE.md` to `/python/opendeviationbar/validation/CLAUDE.md`
    - Keep `**Hub**: [/CLAUDE.md](/CLAUDE.md)` intact
    - Do NOT change any other content in the file

  </action>
  <verify>
    <automated>grep -l 'Parent' python/opendeviationbar/validation/CLAUDE.md python/opendeviationbar/processors/CLAUDE.md 2>/dev/null | wc -l | grep -q 2 && grep 'validation/CLAUDE.md' python/opendeviationbar/validation/day_mode/CLAUDE.md | grep -q Parent && echo "PASS" || echo "FAIL"</automated>
  </verify>
  <acceptance_criteria>
    - validation/CLAUDE.md contains `**Parent**: [/python/opendeviationbar/CLAUDE.md]`
    - validation/CLAUDE.md has Files table with rows for all 8 files
    - validation/CLAUDE.md has a `## Children` or link to validation/day_mode/CLAUDE.md
    - processors/CLAUDE.md contains `**Parent**: [/python/opendeviationbar/CLAUDE.md]`
    - processors/CLAUDE.md has Files table with rows for api.py and core.py
    - day_mode/CLAUDE.md Parent line now references `/python/opendeviationbar/validation/CLAUDE.md` (not grandparent)
  </acceptance_criteria>
  <done>validation/CLAUDE.md and processors/CLAUDE.md exist with correct parents; day_mode/CLAUDE.md parent chain updated to go through validation/CLAUDE.md intermediate.</done>
</task>

<task type="auto">
  <name>Task 2: Create heartbeat/CLAUDE.md and heartbeat/checks/CLAUDE.md spokes</name>
  <files>scripts/heartbeat/CLAUDE.md, scripts/heartbeat/checks/CLAUDE.md</files>
  <read_first>
    scripts/heartbeat/__init__.py
    scripts/heartbeat/__main__.py
    scripts/heartbeat/config.py
    scripts/heartbeat/formatter.py
    scripts/heartbeat/alert_dedup.py
    scripts/heartbeat/state.py
    scripts/heartbeat/telegram.py
    scripts/heartbeat/checks/__init__.py
    scripts/heartbeat/checks/stathera.py
    scripts/heartbeat/checks/freshness.py
    scripts/heartbeat/checks/clickhouse.py
    scripts/heartbeat/checks/services.py
    scripts/heartbeat/checks/sidecar.py
    scripts/heartbeat/checks/kintsugi.py
    scripts/heartbeat/checks/resources.py
    scripts/heartbeat/checks/junction.py
    scripts/heartbeat/checks/ratelimit.py
    scripts/heartbeat/checks/seeder.py
    scripts/heartbeat/checks/version.py
    scripts/heartbeat/checks/vision_oracle.py
    scripts/heartbeat/checks/yesterday.py
  </read_first>
  <action>
    **scripts/heartbeat/CLAUDE.md:**
    - `**Parent**: [/scripts/CLAUDE.md](/scripts/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Health heartbeat system running every 5 minutes via systemd timer, monitoring sidecar, kintsugi, ClickHouse, and Stathera integrity
    - `## Files` table: __init__.py, __main__.py, config.py, formatter.py, alert_dedup.py, state.py, telegram.py -- with actual purposes from reading each file
    - `## Entry Point` section: __main__.py runs all checks, aggregates results, sends Telegram message
    - `## Alert Deduplication` section: how alert_dedup.py prevents notification spam
    - `## Children` section: link to checks/CLAUDE.md
    - `## Related` section linking to parent, hub, /scripts/systemd/CLAUDE.md (timer config), /deploy/CLAUDE.md (monit)

    **scripts/heartbeat/checks/CLAUDE.md:**
    - `**Parent**: [/scripts/heartbeat/CLAUDE.md](/scripts/heartbeat/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)`
    - 1-2 sentence description: Individual health check modules each returning a result dict consumed by the heartbeat formatter
    - `## Checks` table listing ALL 13 check modules: __init__.py, stathera.py, freshness.py, clickhouse.py, services.py, sidecar.py, kintsugi.py, resources.py, junction.py, ratelimit.py, seeder.py, version.py, vision_oracle.py, yesterday.py -- with actual purpose from reading each file
    - `## Check Interface` section: document the common check signature/return format (read __init__.py and any check to determine)
    - `## Key Checks` section highlighting stathera.py as the primary gap detection check
    - `## Related` section linking to parent, hub

  </action>
  <verify>
    <automated>grep -l 'Parent' scripts/heartbeat/CLAUDE.md scripts/heartbeat/checks/CLAUDE.md 2>/dev/null | wc -l | grep -q 2 && echo "PASS" || echo "FAIL"</automated>
  </verify>
  <acceptance_criteria>
    - heartbeat/CLAUDE.md contains `**Parent**: [/scripts/CLAUDE.md]`
    - heartbeat/CLAUDE.md has Files table with rows for all 7 files
    - heartbeat/CLAUDE.md has link to checks/CLAUDE.md child
    - checks/CLAUDE.md contains `**Parent**: [/scripts/heartbeat/CLAUDE.md]`
    - checks/CLAUDE.md has Checks table with rows for all 13 check modules
    - checks/CLAUDE.md documents the common check interface/return format
  </acceptance_criteria>
  <done>heartbeat/CLAUDE.md and heartbeat/checks/CLAUDE.md exist with correct 2-level parent chain, complete file tables for all modules, and domain-specific sections.</done>
</task>

</tasks>

<verification>
All 4 new CLAUDE.md files exist and validation/day_mode parent chain is fixed:
1. `grep -l 'Parent' python/opendeviationbar/validation/CLAUDE.md python/opendeviationbar/processors/CLAUDE.md scripts/heartbeat/CLAUDE.md scripts/heartbeat/checks/CLAUDE.md` returns all 4 paths
2. `grep 'validation/CLAUDE.md' python/opendeviationbar/validation/day_mode/CLAUDE.md` confirms parent chain fix
3. Each file has domain-specific content, not boilerplate
</verification>

<success_criteria>
4 new CLAUDE.md spokes created (validation, processors, heartbeat, heartbeat/checks), day_mode parent chain fixed to point through validation/ intermediate, all with correct Parent links and source-derived content.
</success_criteria>

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