public-candidate-sync

name	public-candidate-sync
description	Refresh public district candidate rows from structured live-field research plus staged facts/timelines. Use when: surfacing all candidates per constituency in the app, resyncing public/data after research candidate changes, or restoring legacy candidate route aliases.

Public Candidate Sync

When to Use

• After research/constituency-live-fields/ or staged candidate facts/timelines change
• When public/data/district-candidates/*.json drift from the structured research layer
• When the app should surface the full known field per constituency, not just one promoted row

Canonical Agents

• publication-agent
• ingestion-validator-agent

What It Does

• Writes every district override JSON from research/constituency-live-fields/*.json
• Writes one public candidate-detail JSON per live candidate at public/data/candidate-details/*.json
• Carries forward candidate IDs and legacy aliases for route compatibility
• Pulls trust metadata from staged candidate facts
• Pulls filingStatus into public district rows for seat-stage UI use
• Pulls merged chronology arrays from staged candidate timelines
• Writes timelineMeta coverage fields into public candidate-detail payloads
• Keeps visible public copy concise: title <= 80, description <= 160, one sentence by default
• Leaves voter-facing event filtering to the client; public detail files can still contain statewide-admin schedule items that the candidate route hides

Procedure

1. Ensure staged facts/timelines are current for touched candidates
2. Trigger publication-agent to update touched district rows and candidate-detail files
3. Trigger ingestion-validator-agent and surface any drift before calling the sync done
4. Spot-check one district page, one constituency page, one thin candidate page, and one deeper-history candidate page for ordering, preview behavior, and chronology depth

Guardrails

• Do not hand-edit public/data/district-candidates/*.json after the sync unless you also update the research layer
• Do not drop aliases for previously published candidate IDs unless you intentionally want to break old routes
• Keep timeline: [] for candidates whose staged timeline file has no events
• Treat research/swarm/control/validation-state.json as the rolling defect register for both district rows and candidate-detail files; it becomes a true gate only when standards-keeper adds a hold
• Keep browse previews from promoting scaffold-only copy as if it were the latest meaningful candidate development
• If the research layer still has a prose-only unresolved seat, fix the research parse first instead of inventing public candidates
• For Tamil Nadu coverage work, do not add synthetic DMK / AIADMK rows just because the party-coverage audit shows an alliance-covered literal gap; only publish a new row when seat-local evidence shows that literal party is actually contesting the seat
• For Tamil Nadu source-confirmed official absences, update research/statewide/tamil-nadu-party-lane-absences.json and the diagnostic instead of publishing a synthetic row

Handoff

• Update AGENTS.md, README.md, handoff.md, docs/HANDOFF_2026-03-22.md, and any affected data skills when the public-sync contract changes