candidate-staging-sync

name	candidate-staging-sync
description	Backfill or refresh staged candidate facts and timeline artifacts from live app rows plus district packets. Use when: expanding candidate-facts/timelines coverage to match public/data, resyncing after district-candidate edits, or restoring provenance on staged candidate files.

Candidate Staging Sync

When to Use

• After editing research/constituency-live-fields/*.json
• When research/candidate-facts/ or research/candidate-timelines/ drift from live thin rows
• When staged files need packet provenance or full live-row coverage

Canonical Agents

• facts-agent
• timeline-agent
• ingestion-validator-agent

What It Does

• Syncs one staged facts file and one staged timeline file for every structured seat candidate
• Syncs one structured research/constituency-live-fields/<district>.json file per district
• Seeds missing staged files from the live row plus district coverage packet sources
• Preserves hand-curated staged files, but adds packet provenance to them
• Allows extra research-only candidate files to exist beyond the live app layer

Procedure

1. Confirm the district publish packets exist for any touched district
2. Update the staged research source first; if public rows drift, treat them as generated outputs
3. Trigger facts/timeline subagents for touched candidates only
4. Trigger ingestion-validator subagent and write results to research/swarm/control/validation-state.json
5. Spot-check one synced facts file and one timeline file in the affected district

Provenance Model

• Live-app-linked staged files carry both provenance.research.liveAppLinked: true and provenance.app
• Research-only staged files carry provenance.research.liveAppLinked: false
• All staged files must keep district packet refs for coverage, review, and verification

Guardrails

• Do not hand-edit public/data/ as the normal starting point for staging sync work
• Do not let automated stage updates overwrite curated manual refs/events without explicit review decision
• When correcting a seat, also rewrite Current best-known live field prose so removed names do not linger; the parser will otherwise resurrect stale candidates from packet text
• Do not treat an empty staged timeline as publishable app timeline content
• Do not use sync as a substitute for constituency-level verification when the live row itself is wrong
• If constituency numbering in packets differs from app numbering, fix the packet or add a resolver rule before trusting the output

Handoff

• If sync changes the repo workflow or provenance shape, update docs/INGESTION_OPERATING_MODEL.md, research/README.md, AGENTS.md, README.md, and handoff docs in the same session