feat(tracker): pluggable issue tracker with Jira and Linear providers

.devflow/features/tracker-references/KNOWLEDGE.md

@@ -5,7 +5,7 @@ description: "Use when modifying src/assets/agents/git.mds, adding or changing a
 category: architecture
 directories: [src/assets/agents/git.mds, src/assets/mds/tracker, src/assets/mds/git, src/core/mds-variants.ts, src/core/reference-sweep.ts, src/targets/claude-code/installer.ts, src/assets/commands/_partials/_tracker.mds, src/assets/skills/git, src/assets/skills/review-methodology, tests/tracker, tests/fixtures/tracker/baseline, tests/installer, tests/guards/capability-hoist.test.ts, tests/guards/provider-scope.test.ts, tests/guards/guard-census.test.ts]
 created: 2026-09-14
-updated: 2026-09-16
+updated: 2026-09-17
 ---
 
 # Tracker References
@@ -14,7 +14,7 @@ updated: 2026-09-16
 
 Tracker Phase 2 (issue #324, tracking #321) splits `src/assets/agents/git.mds` — the always-loaded, per-spawn-billed Git agent prompt (PF-026) — into a **provider-independent contract** that stays in `git.mds` and **per-provider mechanics** that compile into generated skill references, loaded only by the operations that need them. The split is GitHub-only; Jira/Linear land in Phase 3 with the resolution substrate already reserved. This is the internal-refactor half of the tracker initiative: **zero user-visible behaviour change** — every GitHub-rendered artifact (`Tracked = #{n}`, `Depends on: #{n}`, issue filenames) is byte-identical to before the split.
 
-**Status — NOT landed.** Phase 2 is open as **PR #339**. `origin/main` is `33b730e` and contains none of this work. The branch is merely *aligned with* `main` by merge commit `10ea0d5`, which pulled that `33b730e` in — `33b730e` is PR **#338**, a different PR that did land. Read "landed" strictly (PF-010: merged to `main`); until #339 merges, do not treat Phase 2 as shipped or skip the merge.
+**Status — landed.** Phase 2 is on `main` as squash commit `ecfc141` (PR #339, issue #324). Every measurement and baseline in this file is stated against that tree. The provider dimension built on top of it — selection, the background Tracker agent, hook Section 3, `--emit` and the reader-side preamble — is owned by `.devflow/features/tracker-feature/KNOWLEDGE.md`, which also carries the Jira (3b) and Linear (3c) slots.
 
 The system has five moving parts that must be understood together: (1) the contract left in `git.mds` plus a ≤40-line provider-resolution preamble that is the *single* place a provider token is resolved; (2) the MDS build machinery (`VARIANT_MODULES`, `expandVariants`, `splitVariantSections`) that fans reference modules out into per-op files; (3) the byte-budget guard that makes the split's payoff a tested property, not an assumption; (4) the containment oracle that proves no text was silently paraphrased or dropped during the move; (5) the installer's converge-not-merge overlay that gets the generated files into a user's `~/.claude/skills/devflow:git/references/` tree atomically. `feature-knowledge-system` owns the general MDS build pipeline (generator hosts, `output-dir:`); this KB owns the tracker-specific consumer of that pipeline.
 
@@ -102,7 +102,7 @@ Zero-unaccounted-lines over `git.md ∪ generated GitHub references`, checked ag
 
 `CONTAINMENT_EXEMPTIONS` names every deliberately **rewritten** (not relocated) line range, each entry requiring a rationale of **≥ 40 characters**, asserted non-empty. Both policing arms matter: a range present with no matching content is a real gap; a range that *stops* being needed (content became a pure move after all) must also go red — "an exclusion that stops matching is red" fired for real during this phase (two stale `github-api.md` exclusions had to be deleted). The exemption count is **63** — 48 from Phase 2 proper (29 from the original split, 11 rows tagged `#340.` for issue #340's scrub-then-post rewrite of the `github-api.md`/`patterns.md` D11 inline-body recipes, 8 rows tagged `#341.` for issue #341's rewrite of `_github.mds`'s tech-debt-archive chain and its own remaining `github-api.md` recipes), plus 15 rows tagged `#339-resolve.` added by the /resolve fix wave (B20/B23/B32) for the unquoted-expansion fixes the wave carried across verbatim, the batch-projection change, and one D4 stop-and-report spelling in `github-api.md` (see Gotchas) — all individually justified — e.g. the D4 remote-unavailable/secondary-rate-limit sentences, the `< 50` backpressure rung, the D11 "to GitHub" scope sentence, the D11 close-comment scope clause (#341), the `&& gh …` post-command placeholder, [DR-17]'s commit-B batch-first rewrite, `ensure-traceable-issue`'s D3 pointer (repointed after its target section moved), and headings demoted from `##` to `###` on the move into a generated reference (see PF-063 in Gotchas). This count is unaffected by the 2026-09-15 fence-aware extractor fix — that fix changed how a section is EXTRACTED, not what content moved, so no exemption range changed.
 
-Structural parity: `opsWithLoadInstruction > 0 && files.length > 0` — never a one-element set-parity scaffold (the exact PF-018/GAP-42 trap). Per-define non-emptiness enforces `MIN_REFERENCE_CHARS = 80` as a **floor** (registered in `numeric-floors.json`'s `floors` array, not `ceilings` — raising it only makes the guard stricter; lowering it re-admits the shape it exists to catch: a reference that kept its heading and lost its body). AC-2.7 reachability walks the full **13-file** manifest (10 GitHub ops + 3 cross-cutting), asserted in both directions, plus the negative check that no `references/tracker/_mcp.md` exists and no `'_mcp.md'` literal is named from any `github/{op}.md` after a GitHub-only build. The DR-19 shared-literal registry (started here, MCP arm deferred to Phase 3) asserts every normative sentence of `publication-gate.md`/`learn-conventions.md`/`decision-markers.md` appears in exactly one of those three files, **and** that no sentence in the registry is restated in any `github/{op}.md`.
+Structural parity: `opsWithLoadInstruction > 0 && files.length > 0` — never a one-element set-parity scaffold (the exact PF-018/GAP-42 trap). Per-define non-emptiness enforces `MIN_REFERENCE_CHARS = 80` as a **floor** (registered in `numeric-floors.json`'s `floors` array, not `ceilings` — raising it only makes the guard stricter; lowering it re-admits the shape it exists to catch: a reference that kept its heading and lost its body). AC-2.7 reachability walks the full manifest, asserted in both directions — **34 files** from Phase 3c (three providers × 10 ops + 3 cross-cutting + the tool-call contract), with the template instantiated per REGISTERED provider rather than for `github` alone, and the contract reachable by a third rule (a shipped consumer names it). The negative half did not relax: no `'_mcp.md'` literal may be named from any `github/{op}.md`, and the gate still SHUTS for an injected registry with no tool-call provider. The DR-19 shared-literal registry (started here) asserts every normative sentence of `publication-gate.md`/`learn-conventions.md`/`decision-markers.md` appears in exactly one of those three files, **and** that no sentence in the registry is restated in any provider's `{op}.md`. Its MCP arm landed in Phase 3c as a **SEPARATE** `MCP_SHARED_LITERAL_REGISTRY` rather than as rows added here: this registry's ownership arm asserts its owners are exactly `GIT_CROSS_CUTTING_DOCS`, and the tool-call contract is a different module kind behind a different gate, so folding it in would have meant relaxing that arm to admit a fourth owner instead of classifying the case (ADR-025).
 
 ### 7. The installer overlay (`src/targets/claude-code/installer.ts`, `src/core/reference-sweep.ts`, `formatOverlaySummary` in `init.ts`)
 
@@ -140,7 +140,9 @@ What Phase 2 deliberately reserves without implementing:
 - `_mcp.md` is **not generated** in Phase 2 (AC-2.7 asserts its absence) — no MCP-backed provider module exists yet, so it would have no reachable consumer (ADR-003).
 - The DEGRADED reason `tracker mechanics unavailable` is reachable **by design** from the overlay's failure paths (an overlay unit that fails to refresh, or a declared reference absent from the build) even though its *runtime* consumption arm lands in Phase 3 (P3a-S14).
 - The shared-literal registry's MCP arm ([DR-19]) is deferred until `_mcp.md` exists.
-- **The `## Operations` contract table's provider-specific wording is Phase 3's to decide, not an oversight.** `git.mds`'s always-loaded table still reads "Fetch GitHub issue" / "Fetch multiple GitHub issues" while D4, D11, the Principles and the Boundaries were all neutralised to "the tracker". That asymmetry is deliberate in Phase 2 on two grounds: the table is contract prose, outside the mechanics-move charter, and every character of it lands against `git.mds`'s thin headroom. Phase 3 — which is when a second provider makes the wording actually wrong rather than merely narrow — owns the neutralisation decision for the table, and for `src/assets/skills/git/SKILL.md:188`'s `X-RateLimit-Remaining` threshold, the other GitHub literal deliberately left in an always-loaded file (there because the regression pass verified it is a load-bearing D4 mitigation). Do **not** rename either in Phase 2.
+- **The `## Operations` contract table's provider-specific wording was Phase 3's to decide, and Phase 3 decided it (#325).** Phase 2 left the always-loaded table reading "Fetch GitHub issue" / "Fetch multiple GitHub issues" while D4, D11, the Principles and the Boundaries were all neutralised to "the tracker". The asymmetry was deliberate on two grounds — the table is contract prose, outside the mechanics-move charter, and every character of it lands against `git.mds`'s thin headroom — and it was reserved for the point at which a second provider would make the wording actually wrong rather than merely narrow. **The three tracker cells are now "tracker issue(s)", together with the two op-body descriptions that duplicate them**, because a table contradicting the operation two hundred lines below it is a worse end state than either wording alone. `create-release` and `fetch-review-threads` still name GitHub: PR and release hosting stay there under every provider, so those are not tracker facts. **`src/assets/skills/git/SKILL.md`'s `X-RateLimit-Remaining` threshold was KEPT**, deliberately — it is a load-bearing GitHub D4 mitigation in a file the GitHub path preloads, `SKILL.md` has 19 ch of headroom, and the skill carries GitHub doctrine rather than provider-neutral contract. Recorded so its survival reads as a decision rather than an oversight.
+
+- **The `backlink-shipped-issues` digits-only entry gate was the same class of defect, and it was live.** Step 0 required every `SHIPPED_ISSUES` entry to be "digits only" — a GitHub shape in a provider-blind, always-loaded position, so the operation was unreachable under jira and linear. #325 made the step defer to the resolved provider's anchored reference grammar and **moved the github grammar `^#?[1-9][0-9]{0,8}$` into `_github.mds`'s `backlink_shipped_issues` define**, with the same drop rule and the canonical per-ref DEGRADED reason. The grammar was placed ABOVE the range `STATUS_LINE_REFERENCE_FILES` samples in that file (`between('1. Fetch existing comments authored by the viewer:', 'Apply the Comment-sink scrub (D11) …')`), which is why the frozen fixture stayed byte-identical: an addition outside a sampled slice is invisible to the extractor. **When adding to a reference the frozen fixture samples, check where its anchors are first.**
 - **A prunable flat cross-cutting root** — `sweepOrphanedReferences` is scoped strictly to `references/tracker/**`, so an orphaned flat document at the references root is never pruned. Widening it needs an allowlist of the hand-authored files that live there (`github-api.md`, `violations.md`, …), which does not exist; `D-OVERLAY-FLAT-UNIT` deliberately treats the flat set as one non-prunable unit until it does. Phase-3 candidate, recorded so the narrower scope reads as a decision rather than an omission.
 - Devflow-wide prompt diet, tracked in issue #342 (see Overview) — this feature's byte-budget ceilings are a per-agent instance of that broader effort, not the effort itself.
 
@@ -207,6 +209,7 @@ What Phase 2 deliberately reserves without implementing:
 - PF-058: containment is four separate obligations — the per-op Principle-8 marker-neutralisation pointer restored to `setup-task`/`fetch-issue` is this pitfall's direct fix; the record explains why the global principle alone once proved insufficient for exactly these two ops
 - PF-060: prose-only instructions are not guards — every prohibition in this feature (no `tracker-{provider}.md` filename, no `~/.claude` literal, no `<!-- devflow:` restatement) is backed by a mechanical negative guard, not just a written rule
 - PF-063: byte-identical relocation is not semantics-preserving across a grammar boundary — the direct cause of the `###`-heading-depth rule for generated references; resolved by the fence-aware section-boundary rule (mechanics owned by `test-harness`), applied here to the two remaining `###`-demotion exemptions
+- `.devflow/features/tracker-feature/KNOWLEDGE.md` — the provider dimension layered on this split: how a provider is selected (`manifest.features.tracker`, `devflow tracker`, `--tracker`), how `~/.devflow/tracker.md` conventions are inferred, the generation gate that turns `_mcp.md` on, and the reader-side resolution order and mismatch guard
 - `.devflow/features/feature-knowledge-system/KNOWLEDGE.md` — the general MDS build pipeline (generator hosts, `output-dir:`, `skill-refs` variant) this feature's build side extends
 - `.devflow/features/test-harness/KNOWLEDGE.md` — `extractOpSectionFromCorpus`, `collectUnfencedH2`, `gitAgentSinkCorpus`, goldens lifecycle, `walkFiles`, the general guard conventions this feature's tests follow, and the Guard 10 follow-up / fence-aware boundary mechanics referenced throughout this file's Gotchas
 - `.devflow/features/dynamic-workflow-engine/KNOWLEDGE.md` — `_tracker.mds`'s adoption sites among the command-layer partials, `DIST_FILES` vs `ALL_HOSTS`