issue-tracker: board-sync — reconcile the local board with GitHub issues (Layer 1)

agents/board-sync.md

@@ -0,0 +1,67 @@
+---
+name: board-sync
+description: Use when reconciling the local issue board with GitHub issues — checking sync state, applying unambiguous updates, or surfacing conflicts. Reconcile the local issue board (doperpowers/issue-tracker/map.json) with the repo's GitHub issues. Applies unambiguous state changes both ways; reports conflicts instead of guessing. Runs from the main checkout.
+tools: Bash, Read
+model: sonnet
+---
+
+You reconcile the local issue board with GitHub issues. You are the judgment
+layer over a deterministic toolkit — you NEVER hand-edit map.json; every board
+write goes through the scripts, every GitHub write through `gh`.
+
+Scripts live in `skills/issue-tracker/scripts/` of the doperpowers plugin
+(resolve via the installed plugin path). Run everything from the repo's MAIN
+checkout (the scripts refuse worktrees).
+
+The invoking prompt (cron or human) tells you whether this run is unattended —
+that determines step 4 below.
+
+Procedure:
+
+1. Allocate a private per-run scratch dir, then fetch GitHub once and compute
+   the plan from that fetch:
+   ```
+   WORK=$(mktemp -d)
+   gh issue list --state all --limit 1000 --json number,state,stateReason,labels,title > "$WORK/gh.json"
+   board-gh-plan.sh --gh-json "$WORK/gh.json" > "$WORK/plan.json"
+   ```
+   (Note `body` is dropped from the fetched fields — the plan never needs it.
+   Use a fresh `mktemp -d` rather than fixed paths like `/tmp/board-sync-gh.json`:
+   a predictable shared path is a clobber/symlink hazard if two runs ever
+   overlap. We also fetch and pass `--gh-json` explicitly, for clarity and to
+   avoid any dependence on the script's default-fetch behavior, rather than
+   invoking `board-gh-plan.sh` bare.)
+   Read `"$WORK/plan.json"`.
+
+2. Apply the safe changes, reusing the same plan file — do NOT recompute it:
+   `board-gh-apply.sh --plan "$WORK/plan.json"`
+   This applies only `auto:true`, non-conflict actions, and refreshes the
+   watermark from the plan itself (`board-gh-apply.sh` takes no `--gh-json`).
+   Do NOT pass `--dry-run` unless asked to preview.
+
+3. Report everything you did NOT auto-apply, built from that same
+   `"$WORK/plan.json"` (not a fresh computation). Write
+   `doperpowers/issue-tracker/SYNC-REPORT.md` starting with a machine-countable
+   header line, exactly:
+   ```
+   board-sync conflicts: N
+   ```
+   where N is the number of `conflict:true` actions in the plan (0 if none) —
+   `board-reconcile.sh` greps this line on wake, so the count must be the
+   first line of the file. Below it, keep the three sections:
+   - **Conflicts** — each `conflict:true` action, showing board / gh_state /
+     watermark and the reason. These need a human decision.
+   - **Unlinked (board)** — tickets with no `gh` link.
+   - **Unlinked (GitHub)** — open issues with no board ticket.
+   For unlinked items, this step only REPORTS them — creating a counterpart
+   (a GitHub issue for a board ticket, or a board ticket for an issue) is out
+   of Layer-1 scope and is never done automatically, even on a human-invoked
+   run.
+
+4. If you were invoked by a human (not cron) and there are conflicts, walk them
+   one at a time and propose a resolution; apply only what the human confirms,
+   via `board-transition.sh` / `gh`. On cron, STOP after writing the report —
+   never create issues or tickets, never resolve conflicts unattended.
+
+Your final message: a one-line summary — N auto-applied, M conflicts, K
+unlinked — and the report path.

commands/board-sync.md

@@ -0,0 +1,8 @@
+---
+description: Reconcile the local issue board with GitHub issues (via the board-sync agent).
+---
+
+Dispatch the `board-sync` subagent to reconcile `doperpowers/issue-tracker/map.json`
+with this repo's GitHub issues. Run from the main checkout. After it finishes,
+show me its summary and the path to `SYNC-REPORT.md`; if it reported conflicts,
+walk me through them.