# Phase 2: Kintsugi Yesterday Priority Queue - Context

**Gathered:** 2026-03-23
**Status:** Ready for planning
**Mode:** From session discussion (milestone v1.5 planning)

<domain>
## Phase Boundary

Kintsugi reads the yesterday-repair signal file written by Phase 1's sidecar integrity check, injects flagged symbols at the HEAD of the repair queue, and clears the signal after processing.

Requirements: STARTUP-03

</domain>

<decisions>
## Implementation Decisions

### Signal File Consumption

**Decision:** At the start of each `kintsugi_pass()`, check for `/var/tmp/opendeviationbar-yesterday-repair.json`. If present:

1. Parse the JSON to get flagged symbols + reasons
2. Create Shard objects for each flagged symbol × all thresholds
3. Insert at HEAD of repair queue (before normal shard discovery)
4. After ALL flagged shards are repaired, delete the signal file

**Decision:** Signal file is consumed atomically — all-or-nothing. If kintsugi crashes mid-repair, the signal file persists and is retried next pass.

**Decision:** Use `read_yesterday_signal()` and `clear_yesterday_signal()` from `opendeviationbar.sidecar.yesterday_signal` (created in Phase 1).

### Queue Priority

**Decision:** Flagged yesterday shards go before normal shard discovery results. The existing `_shard_sort_key()` recency-first ordering still applies within the normal queue.

**Decision:** Flagged shards use the same `_repair_under_lock()` path (Parquet → Vision → REST priority, unchanged).

### Claude's Discretion

- Whether to log signal file consumption at INFO or WARNING level
- Whether to add signal file age check (ignore if > 24h old)
- Exact integration point in kintsugi_pass() or kintsugi_daemon()

</decisions>

<code_context>

## Existing Code Insights

- `kintsugi/orchestrator.py` has `kintsugi_pass()` — the main orchestration loop
- `kintsugi/discovery.py` has `discover_shards()`, `_select_repair_candidates()`, `Shard` class
- `sidecar/yesterday_signal.py` (Phase 1) has `write_yesterday_signal()`, `read_yesterday_signal()`
- Signal file format: `{"symbols": {"SYM": "reason"}, "timestamp": "ISO", "sidecar_pid": N}`
- Kintsugi's today-guard in `_repair()` prevents touching today — yesterday is safe

</code_context>

<specifics>
## Specific Ideas

- The signal file read should happen BEFORE `discover_shards()` so flagged symbols don't get double-counted
- Consider adding a `source: "yesterday_signal"` field to the Shard for telemetry differentiation

</specifics>

<deferred>
## Deferred Ideas

None.

</deferred>
