ADR-005 — Tasks live in the Plan Engine graph; GitHub issues stay synced (elimination deferred)

:::note Contenido en inglés Esta página del wiki se sincroniza desde la base de conocimiento en inglés y todavía no está traducida. :::

reference · tech-lead · updated 2026-06-21 · source

• Status: Accepted (2026-06-20; built by effort #560)
• Date: 2026-06-17
• Owner: Tech Lead
• Related issue: #423
• Depends on: ADR-004 (the graph is where tasks live)
• Amends: the task-management hard rule in CLAUDE.md ("GitHub issues + Projects v2 = source of truth")

Context

• Three task stores colliding: GitHub issues + Projects v2 (kit-task-*), packages/engine/src/tickets.ts (JSON), and the Plan Engine graph (ADR-004). Triple-write.
• Projects v2 is flat — it fakes the tree+DAG the graph models natively.
• GitHub Actions is billing-blocked → issue-close-on-merge and native task automation are already broken.
• Cross-surface parity (terminal · Claude Code desktop/web · Cowork) needs a networked SoT, not local files or the Projects API.
• Inventory to migrate (snapshot 2026-06-17): ~57 open issues, ~166 closed, 2 open PRs.

Decision

• The Plan Engine graph is the source of truth for tasks/plans (reuses plan_node/plan_dependency/plan_version/plan_link from ADR-004, plus the sync_event table this ADR adds to make the GitHub↔graph mirror idempotent and loop-free — the 5-table model).
• Ingest: open issues → live plan_nodes; closed issues → a one-time snapshot/archive. History is migrated, not lost.
• GitHub issues are kept SYNCHRONIZED with the graph (mirror), not eliminated. Final elimination is a deferred decision (see Open question).
• Sync bridge: PR merge / Vercel deploy → graph (plan_link/status); graph task changes mirror back to GitHub while sync is on. Precedent: the Mission Control webhook.
• GitHub stays the home for code + PRs + Vercel previews + branch protection, plus (for now) a synced mirror of task state.
• kit-task-* write to the graph (node id) and keep GitHub in sync.

Open question (deferred — do NOT decide yet)

How to coordinate the graph with git/GitHub history and render a correct visualization — the issue↔node mapping, how closed history is represented, and the roadmap/timeline view spanning both. Resolve this before any elimination.

Consequences

Positive — single SoT for live work; native tree/DAG/versioning; cross-surface parity; history preserved; reversible (nothing deleted — sync keeps GitHub usable as a fallback).

Negative / trade-offs — a bidirectional sync is real work and a drift source if buggy; the issue#N→node-id re-key touches a lot; Cowork needs hosted engine+MCP + machine auth.

Sequencing (HARD) — GitHub issues + Projects stay the operative SoT until the graph is the daily driver and ingest is verified. No elimination until then and an explicit future decision. Decide now: build the graph + sync; defer elimination.

Follow-ups (built under effort #560) — ingest job (open→nodes, closed→snapshot); bidirectional sync bridge (sync_event); re-key branch-naming + worktree↔task + /kit-gc; aligned kit-engine-boundary.md (rules #3/#4) + CLAUDE.md task rule; tickets.ts retired (#570).

Alternatives considered

Option	Why not (now)
Full drop — eliminate GitHub issues outright	Premature; history coordination + visualization unresolved. Deferred, not rejected.
Keep GitHub issues + Projects as the SoT	Projects flat; Actions broken; triple-write persists.
Hard-delete issues	Irreversible; loses ~223 issues of history.

References

• ADR-004 · .claude/rules/kit-engine-boundary.md · .claude/rules/branch-naming.md
• knowledge/product-development-flow.md · Prior decision: #221 in decisions/log.md