Tracker Sync

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) 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 

Writes work/trackers/github/.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/.yaml for the real field IDs + exact option names and runs the gh GraphQL mutation). NEVER write the board from this script.

1. Re-pull and re-diff to confirm the row is now in_sync. Verify-before-claim.

Boards without a workflow/projects/.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/.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/.yaml — board registry (fields, statemap, syncpolicy)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bks-lab
• Source: bks-lab/open-bridge
• License: MIT
• Homepage: https://bks-lab.github.io/open-bridge/

Install and usage instructions live in the source repository linked above.