tracker-sync

name	tracker-sync
description	Persistent snapshot + bidirectional reconcile between The Bridge tasks and GitHub Project boards. Pulls each board into work/trackers/<provider>/<slug>.json (the local mirror / dump), diffs it against work/tasks|streams/*/STATUS.md sync.github bindings into a delta table (in_sync · remote_ahead · local_ahead · state_mismatch · orphan_local · orphan_remote), and pushes local→remote changes through github-projects-manager — gated, never auto. GitHub is the system of record, The Bridge is the cockpit (remote-authoritative). Trigger: "/tracker-sync", "tracker sync", "sync my tasks", "reconcile tasks", "board reconcile", "snapshot github", "which task is in which state", "github project dump", "sync tasks down", "sync tasks up", "task drift", "sync status".
metadata	{"scope":"core","tools":["Bash","Read","Glob","Grep"]}

Tracker-Sync

Keeps The Bridge's task state and the GitHub Project boards aligned, with a persistent local snapshot as the pivot. Three deterministic engine subcommands (scripts/tracker-sync.py — a shared repo-root utility shipped with the Bridge repo itself, not a file inside this skill's own directory) plus one gated write path.

Provider scope: GitHub Projects V2 only for now — other trackers (e.g. ADO) are readable via trackers/*.md playbooks but are not covered by snapshot/diff/push.

Model — remote-authoritative. The team works in GitHub, so the board owns shared status. The Bridge mirrors it, surfaces drift, and stages your pushes. Pull is autonomous (read-only); every cross-write is a proposal:

• never auto-write STATUS.md (a human decides what a remote change means)
• never auto-push to GitHub (gated, batch-confirmed, via github-projects-manager)

When to use

• "sync my tasks", "which task is in which state"
• "pull the boards", "snapshot the projects", "give me a board dump"
• before/after working a board, to see what drifted
• /briefing calls the pull side automatically (see references/workflow.md)

Subcommands (verbs)

Verb	What	Gate
pull	refresh snapshots from all enabled GitHub boards	autonomous (read-only)
status / diff	render the delta table (the control surface)	read-only
push	apply local_ahead rows to GitHub	gated, via github-projects-manager
sync	pull → diff → offer push	gated at the push step only

How to run

pull (down — autonomous)

python3 scripts/tracker-sync.py pull            # all boards from ecosystem.yaml
python3 scripts/tracker-sync.py pull --project <slug>

Writes work/trackers/github/<slug>.json + work/trackers/_index.yaml with a pulled_at stamp. Best-effort: if gh is missing/unauthed it warns and skips — never blocks. The git history of work/trackers/ IS the dated dump history.

diff (the cockpit — read-only)

python3 scripts/tracker-sync.py diff            # table
python3 scripts/tracker-sync.py diff --format json
python3 scripts/tracker-sync.py diff --exit-code   # exit 2 if actionable drift

Each row is one linked issue, classified (see references/diff-model.md). Present the table, then offer the obvious next action per class:

Class	Means	Offer
in_sync	local == board	nothing
remote_ahead	board moved past local (e.g. a teammate moved it to Done)	propose STATUS.md update (gated; never auto)
local_ahead	local moved past board	push (gated)
state_mismatch	blocked/odd divergence	surface, ask
orphan_local	STATUS links an issue not in any snapshot	re-pull / fix repo / unlink
board_stale	issue closed/merged but its card never moved to Done	propose board-hygiene push (card → Done), gated
orphan_remote	your open board item linked to no task	propose link or new task

pull fetches each repo's closed issues/PRs and stamps item.closed; in diff the issue lifecycle wins over the board Status field (a closed issue on a New card is still done). --no-issue-state skips this for a faster pull.

push (up — GATED, via github-projects-manager)

1. python3 scripts/tracker-sync.py plan --format json → list of Status-field ops.
2. Show the batch. For EACH operation get explicit [y/n] (or one batch [y]).
3. For each approved op, hand off to github-projects-manager (it reads workflow/projects/<slug>.yaml for the real field IDs + exact option names and runs the gh GraphQL mutation). NEVER write the board from this script.
4. Re-pull and re-diff to confirm the row is now in_sync. Verify-before-claim.

Boards without a workflow/projects/<slug>.yaml registry can be pulled and diffed, but push degrades: plan emits to_option: null (no field-ID mapping). Surface that honestly and offer to scaffold the registry from workflow/projects/_template.yaml rather than pushing blind.

Config

Uses the same integrations.github block as /briefing Stream B (enabled, projects: ecosystem, assignee_me). Optional per-board sync_policy: in workflow/projects/<slug>.yaml (authority, auto_pull) — see references/diff-model.md. No config = remote-authoritative default.

Hard rules

• Remote-authoritative: GitHub wins on Status; pull proposes, never overwrites STATUS.
• No auto-push. All board writes go through github-projects-manager, gated.
• Snapshots are USER data (work/trackers/) — never promoted upstream.
• The engine is the only deterministic surface; judgement (what a drift means) stays with the skill + the human.

Related

• scripts/tracker-sync.py — the engine · tests: scripts/tests/test-tracker-sync.sh
• references/diff-model.md — full classification + phase-bucket rules
• references/workflow.md — pull/diff/push playbook + /briefing integration
• skills/github-projects-manager/ — the gated write executor (push handoff)
• protocols/standing-orders/task-sync.md — the per-task sync.github resolver
• trackers/README.md — normalized item schema (== the snapshot format)
• workflow/projects/<slug>.yaml — board registry (fields, state_map, sync_policy)