Kanban board: optionally back agent tickets with GitHub issues (read-only, cached)

[serge-ivo]

Problem

Each agent instance has a Kanban board of tickets, and that work usually also exists as GitHub issues on the agent's repo. Two parallel records of the same work with nothing reconciling them, so a card can sit stale while the real issue has moved on.

Proposal

Let a ticket optionally be backed by a GitHub issue. Explicitly NOT two-way sync, and NOT a live view calling the GitHub API on every board render. The ticket row stores the issue NUMBER as a stable key plus a small cached projection (title, state, labels) for display. GitHub stays the single source of truth for issue content; the board never claims to own the description.

Cache Invalidation

Prefer GitHub webhooks over polling: on issue events, update the cached row for the ticket referencing that number. Fall back to refresh-on-open if a webhook is missed. Avoid timer-based polling.

V1 Scope

Board is read-only with respect to GitHub. Moving a card does NOT mutate the issue upstream. Drag-to-change-issue-state is deliberately deferred to a later issue since it needs conflict handling this does not.

Settings

Per-agent setting for whether that agent's board is issue-backed at all, since not every agent has or wants a repo behind it. Boards stay fully usable with no issue backing.

Sequencing

This adds a field to the ticket model. The original draft of this issue sequenced that behind in-flight update_ticket work cited as "#137". Two corrections, both verified at filing time:

• That work is MCP connector: board tickets can be created but never edited proappstore-online/platform#137 (PAS), not an issue on this repo. A bare #137 here autolinks to Refactor: split agent-storage.ts (1262 LOC) per storage domain #137, "Refactor: split agent-storage.ts (1262 LOC) per storage domain" — closed, and unrelated to tickets.
• It is no longer in flight: MCP connector: board tickets can be created but never edited proappstore-online/platform#137 was closed as completed on 2026-08-16, landed by feat(mcp): a backlog ticket can be edited, not only filed (#137) proappstore-online/platform#140 ("feat(mcp): a backlog ticket can be edited, not only filed").

It also landed on PAS, not here, so it does not touch this repo's ticket model and there is no schema collision on this repo to sequence around. Anyone picking this up should confirm the current shape of the ticket model on this repo directly rather than treating the PAS change as a blocker.

Cross-reference

• MCP connector: board tickets can be created but never edited proappstore-online/platform#137 — the PAS update_ticket work referenced above (closed, completed)
• feat(mcp): a backlog ticket can be edited, not only filed (#137) proappstore-online/platform#140 — the PR that landed it

[proagentstore]

Clarification on labels, from discussion with the owner.

The cached projection should carry the issue's GitHub labels through to the card as labels — visibly, on the card itself — not merely store them in the row for internal use.

Importantly, these live in parallel with the card's own board position. A card has:

• its column / status on the Kanban board, which is board-owned state, and
• its GitHub labels, which are mirrored from the issue and are read-only in v1.

These are two independent axes and must not be conflated. Do not derive the column from labels, and do not flatten labels into board status. A card can sit in any column while displaying whatever labels the issue carries upstream, and moving the card must not attempt to change the labels.

This also means label changes made on GitHub should flow back through the same webhook path as title and state changes.

[serge-ivo]

Delivered the foundational read-only, cached, opt-in slice. Commit: 4720a885.

What shipped:

• Migration 0144 — adds github_issue_number INTEGER and github_issue_cache TEXT to board_items.
• PUT /:instanceId/board/items/:jobKey/github-issue — link or unlink a card to a GitHub issue. On link: fetches the issue from GitHub via the existing conditional-fetch/cache machinery, stores the number + a compact projection (title, state, labels, url). Unlink clears both columns. Linking never touches user_status.
• POST /:instanceId/board/github-issues/refresh — re-fetches the projection for every linked card on an instance's board, updating the cache. Uses agent_instances.config.boardGithubRepo as the per-instance opt-in repo (or an override in the request body). Skips unreachable issues without blocking the others; reports { refreshed, skipped }.
• BoardItemView.githubIssue — optional { number, title, state, labels, url } included in every GET /board response where a card has a populated cache. Both runtime-backed and standalone cards carry it. Board column and issue labels are independent axes — the code never derives column from labels, never touches labels on a move.
• 10 new tests driven against realSchemaD1 (migration 0144 in scope): link populates cache, link on unavailable GitHub stores number with empty cache, link never overwrites user_status, unlink clears columns, refresh updates all linked cards and reports counts, buildInstanceBoard includes the projection on standalone and normal cards.

Deferred (not part of this issue's V1 scope):

• Console UI rendering labels on the card (the projection is now in the API response; the console just needs to read githubIssue.labels on a BoardItemView card).
• Webhook-based cache invalidation (GitHub issue events → cache refresh). The refresh route is the manual path the issue says to fall back to.
• MCP tool for link/refresh (covered by the known-gaps ratchet; nothing was newly untracked).
• Write-back (drag-to-close issue) — explicitly deferred to a later issue per the spec.