timeline-enrichment-worker

name	timeline-enrichment-worker
description	Optional helper for one candidate's timeline pass in the active worker-pool model.

Timeline Enrichment Worker

When to Use

• An assigned candidate needs one conservative timeline pass and the end-to-end worker is split into helpers
• You are only handling the timeline lane for one candidate at a time
• The active workflow is queued -> assigned -> published | blocked; this helper does not reintroduce the retired stage machine

Canonical Outputs

• research/candidate-timelines/<candidateId>.json (updated staged timeline)
• research/swarm/tasks/<candidateId>.json (keep the candidate in assigned unless blocked)
• research/swarm/escalations/state.json when blocked

Procedure

1. Read research/swarm/guardrails.json and the candidate task before acting
2. Confirm the candidate is claimed in the owning shard's activeAssignments
3. Read candidate evidence, candidate facts, existing timeline, and district packet context
4. Add or adjust source-backed candidate-specific events with conservative eventStatus and exact dates, aiming for the shipped 20-event floor without turning the route into biography prose
5. When a declaration source is available, keep the public route to one or two plain-language affidavit summary cards per comparable cycle and push any extra approved detail into the full sourced log instead of the default route
6. Preserve event IDs and suppress instead of deleting when downgrading visibility
7. Keep the task aligned with the active worker-pool flow; do not re-create the retired facts_updated -> timeline_updated -> approved chain
8. If evidence is conflicting or policy-blocked, mark the candidate blocked and update the rolling entry in research/swarm/escalations/state.json

Guardrails

• Keep the timeline candidate-specific and voter-useful
• Keep statewide-admin schedule items out of the main feed when enough candidate-focused material exists; use them only as last-resort fallback when the route would otherwise stay below 20 visible events
• Use the strongest reviewed evidence available for eventStatus, and keep wording explicit when stronger status claims rely on lower-tier sources
• Do not turn one affidavit page into many same-date cards in the default curated route
• Do not edit reviews, public data, or other candidates' files
• Do not create run-numbered escalation files
• One candidate, one claim, one timeline pass
• Keep manual additions conservative and source-backed

Handoff

• Return the candidate to the orchestrator or end-to-end worker for publication or block handling