timeline-swarm-orchestrator

name	timeline-swarm-orchestrator
description	Manage timeline swarm control files. Use when: assigning candidates, tracking shard state, orchestrating stage agents, and publishing approved candidates through rolling-state control.

Timeline Swarm Orchestrator

When to Use

• Assigning queued candidates to stage-agent runs
• Spawning or recycling long-lived end-to-end candidate workers
• Syncing all 5 shard files after every state change
• Handling rejected or blocked candidates through escalation policy

Canonical Outputs

• research/swarm/shards/*.json (O01–O05)
• research/swarm/tasks/*.json
• research/swarm/batches/state.json
• research/swarm/control/state.json
• research/swarm/control/publication-state.json
• research/swarm/control/validation-state.json
• research/swarm/escalations/state.json

District-to-Orchestrator Map

• O01: Ernakulam plus reserve capacity (slots P01-P08, P41-P52, and P101-P110)
• O02: Malappuram, Palakkad (slots P09-P16, P53-P64, and P111-P120)
• O03: Thiruvananthapuram, Kollam, Pathanamthitta (slots P17-P24, P65-P76, and P121-P130)
• O04: Thrissur, Alappuzha, Kottayam, Idukki (slots P25-P32, P77-P88, and P131-P140)
• O05: Kannur, Kozhikode, Wayanad, Kasaragod (slots P33-P40, P89-P100, and P141-P150)

Procedure

1. Read research/swarm/guardrails.json, own shard, research/swarm/control/state.json, and research/swarm/control/publication-state.json before acting
2. Run a preflight check before claiming or publishing:
   • publish lease is idle and activePublicationSet is empty, or both surfaces point to the same candidate set
   • stale publish_contention messages are cleared when the gate is already idle
   • target cluster prep notes exist when the run depends on tracked checklist coverage
   • declaration-refresh lanes should seed published candidates from research/statewide/declaration-gap-priority.json before ad hoc picking
   • if a declaration-first seed overfills one shard, move only idle slot ids through loanedInPairIds / loanedOutPairIds; keep candidate claims in the owning shard file instead of spilling them into a non-owning shard
   • newly touched candidates will get intake + evidence before downstream writes
3. Spawn or recycle long-lived workers for each available shard slot; the worker should claim one candidate, run research through publication, then pick the next queued candidate
4. Before mutating a candidate task, review, facts, or timeline file, claim that candidate in shard activeAssignments
5. Do not let two workers mutate the same candidate concurrently
6. Before mutating public/data/, acquire research/swarm/control/publication-state.json.publishLease and mirror the same candidate set in research/swarm/batches/state.json.activePublicationSet
7. Publish only candidates whose review decision is approve
8. Trigger ingestion-validator-agent and surface blockers, but do not treat validator state as an automatic reopen gate unless standards-keeper adds a hold
9. Mark successfully projected candidates as published, then release candidate claims and the publish gate
10. Rebuild shard aggregates from task files and sync rolling control files; treat research/swarm/control/state.json.capacity as the configured worker-pool ceiling

Guardrails

• Do not publish with any rejected candidates
• Task file is authoritative; rebuild shard counts from task files if contention corrupted shard totals
• Do not mix candidate content with orchestration metadata
• Do not create run-numbered wave artifacts; use rolling control files only
• Do not hold the publish gate across unrelated work; release it after the public write and validation handoff
• Do not let newly touched candidates skip intake/evidence creation

Handoff

• After publish: update rolling control state, touch handoff.md only if the rolling snapshot materially changed, then commit