issue-tracker: board-sync — reconcile the local board with GitHub issues (Layer 1) - #2
Merged
Conversation
…, not just both-moved conflicts
…aces conflicts, per-run tmp dir
SSFSKIM
marked this pull request as ready for review
July 5, 2026 13:18
Owner
Author
|
Review gates passed before merge:
Both hermetic suites green (28+ board-sync assertions + existing toolkit, no regression); shellcheck baseline-clean. Human partner (repo owner) authorized the merge after the review pass. |
SSFSKIM
added a commit
that referenced
this pull request
Jul 10, 2026
Two-tier trust (review #1, human design call): developer feedback — the server-resolved role snapshot in TRIAGE_TRUSTED_ROLES (default admin), or a stripped .env #TRIAGE_DEV_CODE body prefix — is read as instruction (R1/R4 waived: dev ideas can be born ready-for-agent, labeled source:dev-feedback); user feedback keeps the conservative gate, residual risk explicitly accepted in the Decision Log. The dev code is stripped before the body reaches the prompt or ticket so it never leaks into a public issue. The rest of the review, all fixed: - #2 R2 requires a REAL file citation (path-shaped after :line strip; unknown:12 no longer counts) - #3 R3 scans risk SYMBOLS (assertStudentAccess, supabaseAdmin, RLS, generate-plan layout fns, past_exam_problems, SUPABASE_SERVICE_ROLE_KEY) in addition to paths - #4 claim issues a lease token; writeback is lease-conditional (late writeback after reclaim throws instead of clobbering); reclaim window validated at config load; second idempotency check right before registerTicket - #5 findExisting fails closed on gh search errors - #6 ticket body temp files: mkdtemp dir, mode 0600, removed in finally - #7 TRIAGE_ENABLED checked before config parsing - #8 spec drift fixed (feedback-dispatch.ts references, two-kill-switches) p86 DDL note gains triage_lease UUID. New src/trust.ts. 91 tests green, tsc clean.
SSFSKIM
added a commit
that referenced
this pull request
Jul 31, 2026
… (simplicity audit #2) Drop the Iron Law block, letter-vs-spirit clause, and 5-step gate pseudo-code; keep the evidence table's non-obvious rows. Replace two rigid definitions with the principles they approximated: freshness = no relevant change since the evidence was produced (not message boundaries), scope = verification proportional to the claim (not always the full command).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Who is submitting this PR? (required)
What problem are you trying to solve?
The
issue-trackerboard and a repo's GitHub issues drift apart, silently, with nothing to detect or repair it. Concretely, in a live session (the ida-solution consumer repo, 2026-07-04→05): the local board (doperpowers/issue-tracker/map.json) sat frozen at its 2026-07-03 state while the orchestrator had materialized 21 GitHub issues and re-cut priorities — the board update was a separate manual step that lagged, and a human had to notice the divergence. The drift is bidirectional and recurring: a daemon lands a ticket and the board goesdonebut the GitHub issue stays open; or a human closes an issue on GitHub and the board still shows it active. The only ticket↔issue link today is a(GH#NN)string parsed from the title — no structured field, so nothing can reliably reconcile the two. Theissue-tracker-substratedesign explicitly deferred "GitHub/GitLab sync or export"; this is that deferred work.What does this PR change?
Adds board-sync Layer 1 (state + close-reason): a deterministic toolkit (
board-meta.sh,board-link.sh,board-gh-plan.sh,board-gh-apply.sh) plus aboard-syncsubagent and/board-synccommand that reconcile the local board with GitHub issues — applying unambiguous state changes both ways against a.sync-state.jsonwatermark and writing everything it can't safely auto-apply toSYNC-REPORT.mdinstead of guessing. Two additive, backward-compatible node fields (gh,labels) carry the structured link; every board write still goes through the existing invariant-enforcing scripts.Is this change appropriate for the core library?
Argued yes — it extends existing core
issue-trackerinfrastructure (the board every doperpowers user's orchestrator already owns), is general-purpose (any repo that tracks work as GitHub issues), and the only third-party surface is GitHub viagh, which theissue-trackerskill already references ("If the repo tracks work on GitHub, file the GH issue…"). It is not a new domain skill or a new third-party integration. That said, this is the maintainer's call — flagging it explicitly rather than assuming.What alternatives did you consider?
From the design Decision Log (
docs/doperpowers/specs/2026-07-05-board-sync-design.md):map.json(bypasses the script-enforced invariants; unsafe/unauditable on cron) and over a pure script with no agent (can't judge ambiguous close-reason mapping / conflicts).ghnode field + one-time title backfill over parsing(GH#NN)every run (fragile) or a separate mapping file (dual-maintenance).Does this PR contain multiple unrelated changes?
No. One coherent feature (board↔GitHub state sync, Layer 1), delivered as a sequenced set of commits that build on each other (schema field → writers → diff → apply → agent → docs). Layers 2 (labels) and 3 (edges) are deliberately out of scope, tracked as their own future plans.
Existing PRs
uv.sync, requirements docs, codex-plugin sync, package-version sync, fork-from-upstream sync. None reconcile the issue board with GitHub.)Environment tested
Tests are hermetic (no network): a throwaway git repo, GitHub JSON fed via
--gh-jsonfixtures,--dry-run/--no-githubon the apply path. Both suites pass on macOS (Darwin 24.4.0):tests/issue-tracker/test-board-gh-sync.sh(28 board-sync assertions) andtests/issue-tracker/test-board-scripts.sh(no regression).shellcheck -xon the four new scripts shows only the repo-baseline SC1091 (sourced_lib.shnot followed).New harness support (required if this PR adds a new harness)
N/A — this PR adds no harness support. It adds board-sync scripts + a subagent/command to the existing
issue-trackerskill.Evaluation
This is toolkit/infrastructure (bash + inline python3 + a subagent prompt), not behavior-shaping skill prose, so the "N eval sessions / react-todo acceptance" framing doesn't apply directly. The relevant evaluation is the subagent-driven-development review process, which measurably earned correctness the plan had glossed — the per-task and final reviews caught and fixed four material bugs, all on the automated path where no human watches, each reproduced before fixing:
map.json, so a filtered plan stamped held-back tickets as synced → made plan-driven (plan emits anagreelist; apply refreshes only{applied} ∪ {agree}).board-gh-plan.shbare, which under a non-TTY subagent shell reads empty stdin and sees zero issues → the agent now fetchesghexplicitly via--gh-json, and the script was hardened so a bare call defaults togh.not_plannedGH→board branch lacked a reachability gate, emitting anautodone → wontfixthat the state machine rejects and that crashed the unattended apply mid-loop → gated to a reported conflict.board-link.sh --backfillskipped itslog.jsonlaudit entry → fixed.Rigor
doperpowers:writing-skills… — N/A (no behavior-shaping skill-prose change; this is toolkit + a subagent def).gh/board-transition.sh/JSON), and the read-only guarantee of the plan step. A final whole-branch review found and reproduced a Critical illegal-transition bug before merge.Human review