Pluggable issue tracker (GitHub + Jira + Linear) — tracking

[dean0x]

Summary

Devflow embeds GitHub Issues as its ticket system across commands, agents and skills. This work makes the tracker pluggable — GitHub, Jira and Linear — without losing any of today's compliance-gated traceability behaviour.

The provider is chosen once at devflow init (default github) and stored in manifest.features.tracker.provider. Per-project conventions are inferred once, silently, in the background by a new Tracker agent into ~/.devflow/tracker.md; no question is ever asked of the user. Provider mechanics move out of the 938-line Git agent into generated per-op skill references that are loaded one file per spawn, so the learned instructions never sit permanently in session context.

GitHub users see no change at all — no prompt, no new file, no altered byte — and that guarantee is enforced by a frozen github-status-lines.txt fixture captured in Phase 0 and compared at every phase boundary.

Four phases, executed strictly in order, each branched from main after the previous phase's squash-merge.

Phases

• Phase 0 — harness first + live-defect fixes (Tracker Phase 0 — harness first + live-defect fixes #322)
• Phase 1 — MDS plumbing, provably byte-identical (Tracker Phase 1 — MDS plumbing, provably byte-identical #323)
• Phase 2 — contract/mechanics split, GitHub only (Tracker Phase 2 — contract/mechanics split (GitHub only) #324)
• Phase 3 — init-selected provider + Tracker agent + Jira + Linear (Tracker Phase 3 — init-selected provider, background Tracker agent, Jira + Linear #325)

PR checklist (applies to every phase PR)

• Test-inventory table present with a red proof per guard — guard name · file:line it lands in · the known-bad sample it must fail on · the commit in which it was proven red. A guard with no recorded red proof is not a deliverable.
• CHANGELOG enumerates the user-visible changes with before/after.
• Prefix-shippability command sequence run and pasted — npm run build && npm test && npm run test:integration && npm pack --dry-run, git status --porcelain empty, and the frozen-fixture cmp clean.
• Release-blocker items named in the release-readiness section (Phase 2: the shadow-overlay AC is a release blocker, not merely an AC).

These four are process ACs. There is no mechanical test behind them and none should be faked — a test that asserts a document's shape rather than the system's behaviour is a vacuous guard.

Execution notes

• Branch from main after each squash-merge. No phase PR is ever opened against another phase's branch; no stacking. If a branch is nonetheless cut early, retarget to main and rebase (--force-with-lease), then re-run full CI against the new base.
• Run /implement once per phase, against that phase's design artifact. Every phase is SEQUENTIAL_CODE_AGENTS; parallel Code agents are rejected feature-wide (shared dist/ under rm -rf, no worktree isolation, overlapping read closures).
• Pre-authorised splits: Phase 0's A3a/A3b, Phase 2's per-op T2 commits, and Phase 3's 3a-4 → 3b /implement re-invocation (same branch, CREATE_PR: false on the first run's terminal agent). Never split inside 3a. A P0a/P0b PR split requires explicit approval — it changes the issue count.
• The two goldens have different lifecycles. git-agent.md is regenerated deliberately in Phase 2 and once in Phase 3, each in its own commit reviewed as a text diff. github-status-lines.txt is never regenerated through Phase 3.
• The design artifacts live under .devflow/docs/design/, which is gitignored — every normative rule is inlined into each phase issue and artifact, never linked. Artifacts exceeding the 60k comment cap are posted as a truncated stub; each artifact is self-contained regardless.

Out of scope

• git.md's second size cut (git.md: second size cut — move the 8 PR/review op bodies to references (SG-7) #326, SG-7) — moving the 8 PR/review op bodies to references. Filed separately because the post-review-summary / post-resolution-summary mechanics are D10 and D11 sinks and may move only in a PR that moves their guards, never as a size optimisation. Depends on Phase 2 being merged.
• The Linear capability probe issue — filed during Phase 3c alongside the ## Known Unknowns section, so the unknown has a named owner. Linear ships at rank 4 (visible first-line marker, no author filter, post-with-warning).

Decisions fixed for this issue set (D-I)

1. Each phase issue body is the D3 template carrying that phase's problem statement, execution strategy, subtask table and AC list; the full design artifact is posted as a collapsed comment.
2. Label feature on all four phase issues — the conventional-commit kind (fix/refactor/feat) is carried by the PR title, not the label. Phase issue titles use the artifact title: frontmatter values ("Tracker Phase N — …"); PR titles use the conventional-commit strings.
3. All four phase issues and this tracking issue are created up front, in order P0 → P1 → P2 → P3 → tracking.
4. Depends on: #N appears as prose in each phase issue body — not as the ticket-template dependency grammar, which belongs to the wave scheduler.
5. This tracking issue is created by the Git agent as a plain issue with a custom body, not through the D3 template.
6. Artifacts over the 60k comment cap are posted as a truncated stub per the existing operation behaviour.