Tracker Phase 3 — init-selected provider, background Tracker agent, Jira + Linear

[dean0x]

Initial Request

Phases 0–2 leave a provider-shaped hole with exactly one provider in it.

Phase 0 repaired the command→agent issue seam and froze two goldens. Phase 1 compiled the Git agent from an MDS generator host, provably byte-identical. Phase 2 split the Git agent into a provider-neutral contract (git.md, the ops, their **Input:**/**Output:** blocks, the D4/D11 invariants, the ≤40-line preamble) and GitHub mechanics generated per op into dist/skills/git/references/tracker/github/{op}.md. The shape is correct and the only occupant is GitHub.

Phase 3 fills the hole:

1. A deterministic provider selection — manifest.features.tracker = { provider }, an enum over github|jira|linear defaulting to github, chosen at devflow init on both wizard paths, settable non-interactively with --tracker <id> and afterwards with devflow tracker --set <id>, inspectable with devflow tracker --status.
2. A background Tracker agent (17th agent, model: sonnet, read-only, no tools: key) that infers the project's tracker conventions once — from the connected MCP server plus a bounded git-history scan — and writes the global, write-once ~/.devflow/tracker.md (D11-scrubbed, chmod 600, # UNRESOLVED: sentinels for anything it could not determine, and a ## Dedup Strategy section recording the probe evidence).
3. A SessionStart hook section (Section 3 of session-start-context) that emits a silent background-setup directive — for jira/linear only, only when ~/.devflow/tracker.md is absent, only on source: startup|clear, bounded by a claim file and an attempt cap.
4. An MCP contract module (_mcp.mds → references/tracker/_mcp.md) with a mechanical D11 gate — redact-secrets.cjs --emit — because a shell && short-circuit cannot exist inside an MCP tool call, and an instruction is not a gate.
5. Two provider mechanics modules: Jira (3b) and Linear (3c).

Selection and conventions are separate. That separation is what makes the silent-github path, the hook gate and the zero-change GitHub guarantee all trivial: selection is a manifest enum read by a hook and a preamble; conventions are an inferred global file that only ever exists for a non-GitHub user.

Honest user-visible-change statement

• GitHub users — the default, and every existing install: nothing changes. No prompt, no new file, no altered byte. Regression-tested against the frozen tests/fixtures/golden/github-status-lines.txt captured at Phase 0 and never regenerated since (AC-3.1). No Jira or Linear literal reaches dist/agents/git.md, dist/commands/*.md or references/tracker/github/** (AC-3.12). Under provider github the hook's Section 3 performs zero subprocess invocations (DR-10).

• Jira/Linear users get, deliberately and visibly:

  • one new init wizard question (Advanced always; Recommended only when the mode prompt was shown interactively);
  • a --tracker <id> flag and a devflow tracker --status/--set <id> command;
  • a silent background agent that writes ~/.devflow/tracker.md at a session start — never narrated, never a question;
  • a - **Tracker**: {provider} line in ### Traceability;
  • and the one accepted UX regression — a confirm prompt on devflow uninstall where a user with no other user content previously got a silent artifacts-only sweep.

• Linear ships at rank 4 — visible first-line marker, no author filter, post-with-warning — and says so in a ## Known Unknowns section with a filed probe issue.

The uninstall consequence, stated in full

~/.devflow/tracker.md is classified as user content (OD-15), sitting in uninstall.ts:227-265 between preference-profile.md (:246-250) and learning.json (:252-256). resolveDevflowDirCleanup (:170-202) needs no change: adding a userContent entry automatically flips a user-scope interactive uninstall from 'artifacts-only' to 'prompt' (:198-201).

The rationale is the agent-models.json reclassification, verbatim: "Stale per-agent model overrides silently re-apply…" (uninstall.ts:215-217). "Silently" is the load-bearing word. Phase 3's provider-mismatch guard (P3a-S14) removes silence: a stale tracker.md whose frontmatter provider: disagrees with the resolved provider produces TRACEABILITY: DEGRADED (tracker configuration mismatch) and no tracker call.

Reversal condition, recorded: the user-content classification is conditional on the mismatch guard shipping. If P3a-S14's guard is ever dropped, tracker.md is reclassified to an install artifact in the same change — otherwise a silently-authoritative stale file survives uninstall.

.tracker.processing, .tracker.attempts and .tracker.enabled are install artifacts (installArtifactPaths, uninstall.ts:283-306) and are removed by an artifacts-only sweep, which keeps tracker.md. The two lists must stay disjoint (@d8, uninstall.ts:276-278).

Execution: SEQUENTIAL_CODE_AGENTS · context-risk: HIGH · Design artifact: .devflow/docs/design/tracker-phase-3.2026-09-05_1155.md (authoritative; local, gitignored — a 60k-truncated copy is posted as a collapsed comment).

Product Requirements

Depends on

Phase 2 (#324) merged to main. Tracking issue: #321.

Acceptance criteria

• AC-3.1 — UAC-1 holds — no prompt, no new file, no altered byte on the GitHub path — regression-tested against the frozen github-status-lines.txt
• AC-3.2 (rewritten) — in a Jira project with provider jira and no tracker.md, a session start emits the directive once, the background Tracker agent writes the file, and the next tracker op resolves from it — with zero user-visible narration and zero questions — the full end-to-end "next tracker op resolves from it" is (process-only — PR checklist)
• AC-3.3 — provider jira with no Jira MCP ⇒ a named DEGRADED at each tracker op, branch and PR still created, Tracked (pending) with the reason, never a GitHub issue as fallback
• AC-3.4 — SHIPPED_ISSUES="PROJ-1 PROJ-2" under jira never yields COMPLETE
• AC-3.5 — --emit prints no body on every non-zero path; nonce present and per-invocation; every posting mechanic spells the body {SCRUBBED_BODY} and names D11-OK; the bypass guard is red on create_comment(body: $DEVFLOW_BODY_RAW) — AMENDMENT [DR-01]: …and every posting mechanic also names SECRET-EXPOSED. The success framing is D11-OK <nonce> <sha256> <bytes> <n> [type:count,…], carrying the first-pass scrub result. _mcp.md mandates: echo SCRUB: N […] from the D11-OK line before posting; when N > 0 also emit SECRET-EXPOSED (rotate {type} credential — the source file still holds it). tests/guards/mcp-sink-bypass.test.ts asserts every posting mechanic names D11-OK AND SECRET-EXPOSED; the known-bad sample is a Jira posting mechanic that omits the rotation line. Both literals are added to the DEGRADED/status-line literal registry test. — AMENDMENT [DR-06]: …and every posting mechanic names the <bytes> verification: before posting, confirm the received body's byte length equals the <bytes> field of the D11-OK line; on mismatch DO NOT POST and emit TRACEABILITY: DEGRADED (redaction unavailable). Known-bad = a mechanic that names D11-OK but not <bytes>.
• AC-3.6 (repurposed — carve-out is void) — the init wizard step is reachable under interactive-Recommended and Advanced, unreachable under --recommended/non-TTY, and --tracker suppresses the prompt on both paths
• AC-3.7 — the hostile-tracker.md table passes for every field; the normalisation literal appears exactly once; no mechanics file re-reads provider:
• AC-3.8 — file-set parity across three providers both directions; every define non-empty; every matrix cell filled — vacuous until 3c; assert providers.length === 3
• AC-3.9 (rewritten) — MCP tools absent or denied ⇒ the agent writes nothing, removes the claim file, and the next startup re-arms; MCP present but ambiguous ⇒ the file is written with # UNRESOLVED: sentinels — AMENDMENT [DR-02]: on a write-less exit the agent increments {devflowDir}/.tracker.attempts before deleting the claim file; on a successful write it deletes the counter.
• AC-3.10 — the retired-wording grep is clean repo-wide
• AC-3.11 — /implement PROJ-123 → branch {type}/PROJ-123-{slug} with the type from ## Issue Types, - **Issue**: PROJ-123, - **Tracker**: jira, and the rendered PR link line — live journey is (process-only — PR checklist)
• AC-3.12 — no Jira/Linear literal in dist/agents/git.md, dist/commands/*.md or references/tracker/github/**
• AC-3.13 — 32767 pinned and 60000/X-RateLimit-Remaining absent in the Jira/Linear modules; Retry-After present in Jira; RATELIMITED present in Linear — AMENDMENT [DR-08]: …plus "no per-item fetch verb (getJiraIssue, get_issue, or any single-key fetch capability) appears in any provider's fetch-issues-batch reference", RED against a seeded per-item fixture.
• AC-3.14 — per-provider find_marker names the identity capability and the first-line predicate; a marker at line 5 of a third-party comment does not suppress; markers are namespaced per comment kind
• AC-3.15 — the tracker.md write is scrub-gated fail-closed; no userinfo URL, no email/accountId literal; denied field names dropped with ### Substitutions; file mode 0600
• AC-3.16 (amended — carve-out rows void) — the three-way ADR-007 sweep plus the per-section absent⇒default table, enumerated by name over the 10 tracker ops and the named command sites
• AC-3.17 (rewritten) — two concurrent Tracker agents ⇒ exactly one file; the loser exits silently without overwriting or reporting
• AC-3.18 — no command source and no dist/commands/*.md (incl. release.md) reads ~/.devflow/tracker.md; no curl/wget/Authorization:/token-env read in git.md ∪ references
• AC-3.19 — each of 3a/3b/3c independently satisfies prefix-shippability with a green suite (process-only — PR checklist); its clause-(iii) arm is resolved by decision D-D below — do not read AC-3.19 as blocking 3a
• AC-3.20 (new) — provider change (re-init, --reset, or reinstall) never leaves a silently-authoritative stale file: init renames it and the preamble emits DEGRADED (tracker configuration mismatch)
• AC-3.21 (new) — manifest.features.tracker absent or malformed parses to {provider:'github'} and never makes parseManifest return null
• AC-3.22 (new) — hook output is independent of the developer's real $HOME
• Prefix-shippability — After phase N: (i) npm run build && npm test && npm run test:integration && npm pack --dry-run are green; (ii) a fresh install from the tarball drives /plan → /implement → /code-review → /resolve → /release on a GitHub project with no new prompt and no new file in git status; (iii) every artifact in the tree has at least one reachable consumer in this phase's end-state — no file, define, list element, frontmatter key or conditional arm exists solely for a later phase (ADR-003); (iv) the frozen github-status-lines.txt fixture is byte-identical to its Phase-0 capture.
• Clause (iii) per phase — The prefix-shippability invariant says "After phase N". Phase 3 is one phase. Its clause (iii) obligation is therefore evaluated at the 3c boundary, not at each of 3a/3b/3c.

Subtasks

#	Domain	Owned files (with anchors)	Steps	Depends on	Gate	Handoff contents
3a-1	TS core + CLI + uninstall	new src/core/tracker.ts · new src/cli/commands/tracker-prompts.ts · new src/cli/commands/tracker.ts · src/cli/commands/init.ts (:222-238, :259-265, :291-292, :375-392, :438-453, :665-688, :744, :753, :924-958, :947-951, :1996) · src/cli/commands/init-seed.ts (:35-49, :52-61, :87-115, :335, :355-369) · src/core/manifest.ts (:38-72, :135-142, :229) · src/cli/commands/uninstall.ts (:227-265, :283-306) · new tests/core/tracker.test.ts · new tests/tracker-prompts.test.ts · new tests/tracker-cli.test.ts · tests/manifest.test.ts · tests/init-seed.test.ts · tests/uninstall-logic.test.ts:913-935	P3a-S1, S2, S3, S4, S5, S6, S15, S17	Phase 2 merged to main	G3.1	the manifest key path literal features.tracker.provider as a shared constant · confirmation that features.tracker is absent-tolerant and never in the hard-null set at manifest.ts:151-165 · the chosen model tier (sonnet) so tracker.md's frontmatter and the hook allowlist agree · the .tracker.enabled sentinel path and its write/remove rule [DR-10] · the rearmTrackerInference helper name and the two call sites [DR-22] · the explicit pairing note that P3a-S15's rename and P3a-S17's user-content classification are void unless 3a-4's P3a-S14 mismatch guard ships in the same 3a group (the OD-15 reversal condition)
3a-2	prompt assets + agent-enumerating tests	new src/assets/agents/tracker.md (incl. the tracker.md schema template) · src/core/plugins.ts:63 · tests/agent-frontmatter.test.ts:35, :36-53 (16→17) · tests/agent-name-guards.test.ts (:511-524, :618-673) · tests/build.test.ts — [D21] re-verify the tests/build.test.ts repoint ranges (plan-1 :46-55/:84-91/:106-135 vs plan-2 :45-55/:84-92/:100-140, neither verified) before asserting no literal edits are needed · tests/skill-references.test.ts · new tests/tracker-agent.test.ts · new tests/tracker/hostile-values.test.ts	P3a-S9, S16, S10	3a-1	G3.2	tracker.md's frontmatter name: byte-exactly (Tracker) · the claim-file path {devflowDir}/.tracker.processing and the attempt-counter path · the statement that _roster.mds gains no row and plugins.ts uses a structural, not exempted, Guard-5 pass · the schema section names verbatim, so 3a-4's ## Tracker input contract block matches
3a-3	hooks + tests	src/assets/scripts/hooks/session-start-context (:8-13, insert at :166) · tests/shell-hooks.test.ts (new describe beside :1670) · tests/config-disable-guards.test.ts:190-221 · the TS↔shell key-path parity constant + its test	P3a-S7, S8	3a-2 (the agent file must exist first)	G3.3	the allowlisted provider case literal and the byte-identical silence clause · the resolved ${DEVFLOW_DIR:-$HOME/.devflow} idiom · the named TRACKER_PROCESSING_STALE_SECS constant · the counter-increment rule at directive emission [DR-02]
3a-4	prompt assets + scripts + tests	new src/assets/mds/tracker/_mcp.mds · src/assets/scripts/redact-secrets.cjs (--emit, :85-88 narrowing, exit 5, amended :380-410 block) · tests/redact-secrets.test.ts (new describes) · src/assets/agents/git.mds:29 preamble additions · src/core/feature-config.ts (the tracker key) · new tests/guards/mcp-sink-bypass.test.ts · new tests/tracker/schema-scope.test.ts · new tests/tracker/byte-budget.test.ts (P3a-S18, BUDGET_GIT_MD_P3) · tests/fixtures/golden/git-agent.md (P3a-S18 — the standalone golden-regeneration commit) · docs/reference/platform-assumptions.md · P3a-S19 docs: CLAUDE.md · docs/reference/cli-reference.md · README.md · new .devflow/features/tracker-feature/KNOWLEDGE.md · CHANGELOG.md	P3a-S11, S12, S13, S14, S18, S19	3a-3	G3.4	the _mcp.md generation-gating disposition · the D11-OK <nonce> <sha256> <bytes> <n> [type:count,…] framing literal verbatim [DR-01] · the <bytes> verification clause [DR-06] · the capability-probe table · the re-derived BUDGET_GIT_MD_P3 and the ≤70-line preamble ceiling [DR-13]
3b	prompt assets + tests	new src/assets/mds/tracker/_jira.mds · its manifest rows in scripts/build-mds.ts · new tests/tracker/jira-module.test.ts	P3b-S1, S2, S3	3a-4	G3.5	the file-set / define-set parity shape now that N = 2 providers · the marker-namespacing scheme (devflow:shipped / devflow:wave / devflow:traceability) · the DEGRADED literals actually emitted, checked against §14's canonical table · the per-op aggregate call budget literal [DR-09]
3c	prompt assets + tests	new src/assets/mds/tracker/_linear.mds · manifest rows · new tests/tracker/linear-module.test.ts · new tests/provider-literals.test.ts · ## Known Unknowns + the filed probe issue	P3c-S1 … S7	3b	G3.6	— (terminal)

Gates

Gate	Must be green before	Assertions
G3.1	3a-2 starts	tests/tracker-prompts.test.ts green incl. the 8-row gate matrix and the hostile-value table · manifest round-trip: a manifest with no features.tracker parses; features.tracker: "jira" (a string) self-heals to {provider:'github'}; parseManifest never returns null (AC-3.21) · uninstall disjointness test 9f extended to before.length === 6 · --reset ⇒ github · rearmTrackerInference unit cases + one call-site assertion each in init-seed.test.ts and tracker-cli.test.ts [DR-22] · the .tracker.enabled sentinel is written when the resolved provider ≠ github and removed when it is [DR-10]
G3.2	3a-3 starts	loadShippedDefaults() ⊇ getAllAgentNames() = 17 and ['tracker'] === 'sonnet' · agent-frontmatter retitled 16→17 · agent-name-guards capitalizeFirst and the >= 50 floor green · tracker.md has no tools: key and no Agent(/subagent_type literal · _roster.mds unchanged
G3.3	3a-4 starts	Full shell-hooks Section-3 suite green incl. hostile providers ⇒ no directive; source: resume/compact ⇒ no directive; fresh/stale claim; attempt cap at N=5; counter incremented on directive emission [DR-02]; provider github ⇒ zero subprocess invocations [DR-10]; _HAS_JQ=false parity; envelope key-set (:1010-1018 and :297 — [drift: two planners cite :701/:710, which are the UserPromptSubmit preamble assertions]) · config-disable-guards.test.ts passes under a seeded temp $HOME with provider=jira (AC-3.22)
G3.4	3b starts	--emit prints no body on every non-zero path with a per-invocation nonce (AC-3.5) · the framing carries <n> [type:count,…] and the SOURCE module src/assets/mds/tracker/_mcp.mds names both SCRUB: and SECRET-EXPOSED [DR-01] · the same SOURCE module names the <bytes> verification [DR-06] — [E2] both clauses are asserted against the source .mds, never the generated dist/skills/git/references/tracker/_mcp.md, which does not exist at the 3a boundary because generation is keyed on a jira/linear module existing (P3a-S12 / hazard H7 / conflict C5) · the MCP bypass guard proven red on create_comment(body: $DEVFLOW_BODY_RAW) · the AC-2.7 _mcp.md guard re-scoped (H7) · hostile-tracker.md table green for every field, normalisation literal appears exactly once (AC-3.7) · the two-sided schema-heading test green with >= 11 sections [DR-21] · the DEGRADED registry test green in both directions [DR-04] · BUDGET_GIT_MD_P3 and the ≤70-line preamble ceiling green [DR-13] · P3a-S14's mismatch guard confirmed shipped (the precondition for 3a-1's user-content classification and the rename transition)
G3.5	3c starts	File-set + define-set parity across two providers both directions, every define non-empty (AC-3.8 partial) · 32767 pinned; 60000 / X-RateLimit-Remaining absent from _jira.mds; Retry-After present (AC-3.13) · the fetch_batch single-query bullet present and no per-item fetch verb in the batch reference [DR-08] · the aggregate call budget pinned as a tested literal [DR-09] · frozen status lines unchanged
G3.6	PR opens	Full prefix-shippability · parity across three providers · AC-3.12 · AC-3.18 · AC-3.19 (process checklist) · the _mcp.md shared-literal registry negative arm green and non-vacuous [DR-19] · the Phase-3 tests/fixtures/golden/git-agent.md regeneration commit is present and standalone (its own commit, reviewed as a text diff, no behaviour change in it) and tests/fixtures/golden/github-status-lines.txt is byte-identical to its Phase-0 capture [DR-03]

/implement spawn notes

• Spawn one Code agent per subtask, in the order 3a-1 → 3a-2 → 3a-3 → 3a-4 → 3b → 3c. Each agent's prompt carries this artifact's §7 step block for its subtask, its row of the table above, its gate, and the handoff it receives.
• Commits are pathspec-scoped (git commit -- <owned paths>) so per-commit provenance survives the squash-merge.
• Three commits, not six. 3a-1 … 3a-4 produce the single 3a commit group; the phase's commit boundaries are 3a, 3b, 3c.
• Spawn-input contract (implement.mds:136-172) — stated per agent so nothing is left to inference:
  • 3a-1 · 3a-2 · 3a-3 · 3a-4 · 3b — CREATE_PR: false, PUSH: false, HANDOFF_REQUIRED: true.
  • 3c — CREATE_PR: true, PUSH: true. implement.mds:409: "The last sequential Code agent (with CREATE_PR: true) handles PR creation" — for SEQUENTIAL_CODE_AGENTS there is no separate Git-agent PR-creation step, so a terminal agent carrying CREATE_PR: false ends the phase with commits on a branch and no PR, and the Closes #325 traceability chain never fires.
• [I10] Handoff, stated explicitly on every spawn: HANDOFF_REQUIRED: true on every subtask but the last; every Code agent reads and writes HANDOFF_FILE = .devflow/docs/handoff-{branch_slug}.md (implement.mds:151), writing its §6-row "Handoff contents" after its own gate passes. PUSH is a Code-agent input (code.md:34, :83) that implement.mds's spawn template does not carry — state it in each spawn prompt.
• The 3a-4 → 3b run seam is pre-authorised (§5.4; conflict C18 / decision D-G(a)). Taking it changes which agent is terminal: the first run's terminal agent (3a-4) keeps CREATE_PR: false, the second run's terminal agent (3c) carries CREATE_PR: true. Re-invoke /implement on the same issue and the same branch.
• Standing instruction for every Code prompt: "a golden mismatch means the source is wrong, never the fixture."

Execution strategy

SEQUENTIAL_CODE_AGENTS — 6 subtasks: 3a-1 → 3a-2 → 3a-3 → 3a-4 → 3b → 3c. Phase context risk: HIGH.

One issue, three ordered commits 3a → 3b → 3c on one branch (decision D-C). 3a alone spans five domains — TypeScript core, CLI, hooks, prompt assets, shell scripts — and is the phase's bulk, so it is executed as four sequential Code agents producing one commit group. init.ts (2,007 lines) is flagged critically unstable by the skim heatmap and 3a is its largest single consumer, which is why 3a-1's init/manifest work is its own reviewable commit inside the phase.

Why PARALLEL_CODE_AGENTS is rejected

Three independent facts, any one sufficient (PF-020's closure rule: disjointness must hold over each agent's READ/EXECUTE closure, not merely its WRITE set):

1. npm run build is rm -rf dist && … (package.json:20). Every Code agent's verification step deletes and rebuilds the one shared dist/. A sibling agent mid-suite observes a missing dist tree — and every dist-scanning guard in this feature deliberately fails loud on a missing directory. Parallel agents therefore manufacture nondeterministic red suites that look exactly like real regressions.
2. /implement has no worktree isolation — grep for worktree in implement.mds returns zero hits. All Code agents share one worktree, one git index, one dist/, one node_modules, one vitest run.
3. The test corpus spans every partition. The seam test, the D11 sink-class guard, the containment test and the frozen fixture all read git.md ∪ dist/commands/*.md ∪ dist/skills/git/references/** — the union of every proposed subtask's outputs.

The closest legitimate candidate, recorded so it is not re-litigated: 3a-1 (TS selection substrate) ∥ 3a-2 (prompt asset + plugins.ts). Write sets are genuinely disjoint including test files. It is still rejected on the shared-dist/ and no-worktree-isolation grounds. If parallelism is ever wanted here it requires per-agent git worktrees with per-worktree dist/, which /implement does not support — a tooling change, not a plan change.

PR title

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

Implementation Plan

Design artifact (authoritative): .devflow/docs/design/tracker-phase-3.2026-09-05_1155.md — local and gitignored. A copy truncated at the 60k comment cap is posted as a collapsed comment: #325 (comment). Run with /implement .devflow/docs/design/tracker-phase-3.2026-09-05_1155.md. Tracking issue: #321.

[dean0x]

Design artifact: tracker-phase-3.2026-09-05_1155.md (excerpt truncated at the 60k comment cap — the local file is authoritative)

---

type: design-artifact
version: 1
status: APPROVED
issue: 325
title: "Tracker Phase 3 — init-selected provider, background Tracker agent, Jira + Linear"
slug: tracker-phase-3
created: 2026-09-05T11:55:00Z
execution-strategy: SEQUENTIAL_CODE_AGENTS
context-risk: HIGH

Tracking issue: #321 · Depends on: Phase 2 (#324) merged to main · Next phase: none (final)

This artifact is fully self-contained. .devflow/docs/ is gitignored, so a pointer to any planning document resolves to "not committed; ask the author" (PF-037). Every normative rule, table, glossary entry and literal a Code agent needs is inlined below, never linked. Do not go looking for synthesis-planning.md, synthesis-impl.md or design-review.md — everything binding is here.

---

1. Problem Statement

Phases 0–2 leave a provider-shaped hole with exactly one provider in it.

Phase 0 repaired the command→agent issue seam and froze two goldens. Phase 1 compiled the Git agent from an MDS generator host, provably byte-identical. Phase 2 split the Git agent into a provider-neutral contract (git.md, the ops, their **Input:**/**Output:** blocks, the D4/D11 invariants, the ≤40-line preamble) and GitHub mechanics generated per op into dist/skills/git/references/tracker/github/{op}.md. The shape is correct and the only occupant is GitHub.

Phase 3 fills the hole:

1. A deterministic provider selection — manifest.features.tracker = { provider }, an enum over github|jira|linear defaulting to github, chosen at devflow init on both wizard paths, settable non-interactively with --tracker <id> and afterwards with devflow tracker --set <id>, inspectable with devflow tracker --status.
2. A background Tracker agent (17th agent, model: sonnet, read-only, no tools: key) that infers the project's tracker conventions once — from the connected MCP server plus a bounded git-history scan — and writes the global, write-once ~/.devflow/tracker.md (D11-scrubbed, chmod 600, # UNRESOLVED: sentinels for anything it could not determine, and a ## Dedup Strategy section recording the probe evidence).
3. A SessionStart hook section (Section 3 of session-start-context) that emits a silent background-setup directive — for jira/linear only, only when ~/.devflow/tracker.md is absent, only on source: startup|clear, bounded by a claim file and an attempt cap.
4. An MCP contract module (_mcp.mds → references/tracker/_mcp.md) with a mechanical D11 gate — redact-secrets.cjs --emit — because a shell && short-circuit cannot exist inside an MCP tool call, and an instruction is not a gate.
5. Two provider mechanics modules: Jira (3b) and Linear (3c).

Selection and conventions are separate. That separation is what makes the silent-github path, the hook gate and the zero-change GitHub guarantee all trivial: selection is a manifest enum read by a hook and a preamble; conventions are an inferred global file that only ever exists for a non-GitHub user.

1.1 Honest user-visible-change statement

• GitHub users — the default, and every existing install: nothing changes. No prompt, no new file, no altered byte. Regression-tested against the frozen tests/fixtures/golden/github-status-lines.txt captured at Phase 0 and never regenerated since (AC-3.1). No Jira or Linear literal reaches dist/agents/git.md, dist/commands/*.md or references/tracker/github/** (AC-3.12). Under provider github the hook's Section 3 performs zero subprocess invocations (DR-10).

• Jira/Linear users get, deliberately and visibly:

  • one new init wizard question (Advanced always; Recommended only when the mode prompt was shown interactively);
  • a --tracker <id> flag and a devflow tracker --status/--set <id> command;
  • a silent background agent that writes ~/.devflow/tracker.md at a session start — never narrated, never a question;
  • a - **Tracker**: {provider} line in ### Traceability;
  • and the one accepted UX regression — a confirm prompt on devflow uninstall where a user with no other user content previously got a silent artifacts-only sweep.

• Linear ships at rank 4 — visible first-line marker, no author filter, post-with-warning — and says so in a ## Known Unknowns section with a filed probe issue.

1.2 The uninstall consequence, stated in full

~/.devflow/tracker.md is classified as user content (OD-15), sitting in uninstall.ts:227-265 between preference-profile.md (:246-250) and learning.json (:252-256). resolveDevflowDirCleanup (:170-202) needs no change: adding a userContent entry automatically flips a user-scope interactive uninstall from 'artifacts-only' to 'prompt' (:198-201).

The rationale is the agent-models.json reclassification, verbatim: "Stale per-agent model overrides silently re-apply…" (uninstall.ts:215-217). "Silently" is the load-bearing word. Phase 3's provider-mismatch guard (P3a-S14) removes silence: a stale tracker.md whose frontmatter provider: disagrees with the resolved provider produces TRACEABILITY: DEGRADED (tracker configuration mismatch) and no tracker call.

Reversal condition, recorded: the user-content classification is conditional on the mismatch guard shipping. If P3a-S14's guard is ever dropped, tracker.md is reclassified to an install artifact in the same change — otherwise a silently-authoritative stale file survives uninstall.

.tracker.processing, .tracker.attempts and .tracker.enabled are install artifacts (installArtifactPaths, uninstall.ts:283-306) and are removed by an artifacts-only sweep, which keeps tracker.md. The two lists must stay disjoint (@d8, uninstall.ts:276-278).

---

2. Acceptance Criteria

All 22 criteria below are verbatim from the phase specification, with amendments marked inline and tagged with the design-review finding that produced them. No AC is dropped, renumbered or paraphrased.

AC	Text	Pinning test	Status
AC-3.1	UAC-1 holds — no prompt, no new file, no altered byte on the GitHub path — regression-tested against the frozen github-status-lines.txt	frozen fixture; GitHub-path hook cases emit nothing	covered
AC-3.2 (rewritten)	in a Jira project with provider jira and no tracker.md, a session start emits the directive once, the background Tracker agent writes the file, and the next tracker op resolves from it — with zero user-visible narration and zero questions	hook Section 3 suite + agent write test + preamble read test	covered as three unit slices; the full end-to-end "next tracker op resolves from it" is (process-only — PR checklist)
AC-3.3	provider jira with no Jira MCP ⇒ a named DEGRADED at each tracker op, branch and PR still created, Tracked (pending) with the reason, never a GitHub issue as fallback	no-MCP fixture ⇒ named DEGRADED per op	covered
AC-3.4	SHIPPED_ISSUES="PROJ-1 PROJ-2" under jira never yields COMPLETE	jira module test	covered
AC-3.5	--emit prints no body on every non-zero path; nonce present and per-invocation; every posting mechanic spells the body {SCRUBBED_BODY} and names D11-OK; the bypass guard is red on create_comment(body: $DEVFLOW_BODY_RAW)	--emit describes ×6 + MCP bypass guard	covered
	AMENDMENT [DR-01]: …and every posting mechanic also names SECRET-EXPOSED. The success framing is D11-OK <nonce> <sha256> <bytes> <n> [type:count,…], carrying the first-pass scrub result. _mcp.md mandates: echo SCRUB: N […] from the D11-OK line before posting; when N > 0 also emit SECRET-EXPOSED (rotate {type} credential — the source file still holds it). tests/guards/mcp-sink-bypass.test.ts asserts every posting mechanic names D11-OK AND SECRET-EXPOSED; the known-bad sample is a Jira posting mechanic that omits the rotation line. Both literals are added to the DEGRADED/status-line literal registry test.	bypass guard forward arm ×2 literals; registry test
	AMENDMENT [DR-06]: …and every posting mechanic names the <bytes> verification: before posting, confirm the received body's byte length equals the <bytes> field of the D11-OK line; on mismatch DO NOT POST and emit TRACEABILITY: DEGRADED (redaction unavailable). Known-bad = a mechanic that names D11-OK but not <bytes>.	bypass guard third forward arm
AC-3.6 (repurposed — carve-out is void)	the init wizard step is reachable under interactive-Recommended and Advanced, unreachable under --recommended/non-TTY, and --tracker suppresses the prompt on both paths	tracker-prompts.test.ts gate matrix (8 rows) + both-path reachability + flag-suppresses-prompt	covered
AC-3.7	the hostile-tracker.md table passes for every field; the normalisation literal appears exactly once; no mechanics file re-reads provider:	hostile table (field × payload)	covered
AC-3.8	file-set parity across three providers both directions; every define non-empty; every matrix cell filled	cross-provider parity (3c) + per-define non-emptiness + matrix completeness	covered — vacuous until 3c; assert providers.length === 3
AC-3.9 (rewritten)	MCP tools absent or denied ⇒ the agent writes nothing, removes the claim file, and the next startup re-arms; MCP present but ambiguous ⇒ the file is written with # UNRESOLVED: sentinels	agent tests	covered
	AMENDMENT [DR-02]: on a write-less exit the agent increments {devflowDir}/.tracker.attempts before deleting the claim file; on a successful write it deletes the counter.	EC-67 rows: "directive emitted ⇒ counter +1", "agent writes ⇒ counter absent"
AC-3.10	the retired-wording grep is clean repo-wide	final allowlist narrowing (empty)	covered
AC-3.11	/implement PROJ-123 → branch {type}/PROJ-123-{slug} with the type from ## Issue Types, - **Issue**: PROJ-123, - **Tracker**: jira, and the rendered PR link line	prompt-text assertions	covered as prompt-text; live journey is (process-only — PR checklist)
AC-3.12	no Jira/Linear literal in dist/agents/git.md, dist/commands/*.md or references/tracker/github/**	negative grep	covered
AC-3.13	32767 pinned and 60000/X-RateLimit-Remaining absent in the Jira/Linear modules; Retry-After present in Jira; RATELIMITED present in Linear	tests/provider-literals.test.ts	covered
	AMENDMENT [DR-08]: …plus "no per-item fetch verb (getJiraIssue, get_issue, or any single-key fetch capability) appears in any provider's fetch-issues-batch reference", RED against a seeded per-item fixture.	tests/provider-literals.test.ts
AC-3.14	per-provider find_marker names the identity capability and the first-line predicate; a marker at line 5 of a third-party comment does not suppress; markers are namespaced per comment kind	jira/linear module tests	covered
AC-3.15	the tracker.md write is scrub-gated fail-closed; no userinfo URL, no email/accountId literal; denied field names dropped with ### Substitutions; file mode 0600	agent tests	covered
AC-3.16 (amended — carve-out rows void)	the three-way ADR-007 sweep plus the per-section absent⇒default table, enumerated by name over the 10 tracker ops and the named command sites	tests/tracker/schema-scope.test.ts	covered
AC-3.17 (rewritten)	two concurrent Tracker agents ⇒ exactly one file; the loser exits silently without overwriting or reporting	concurrency test	covered
AC-3.18	no command source and no dist/commands/*.md (incl. release.md) reads ~/.devflow/tracker.md; no curl/wget/Authorization:/token-env read in git.md ∪ references	negative greps	covered
AC-3.19	each of 3a/3b/3c independently satisfies prefix-shippability with a green suite	prefix-shippability run at each of 3a/3b/3c	(process-only — PR checklist); its clause-(iii) arm is resolved by decision D-D below — do not read AC-3.19 as blocking 3a
AC-3.20 (new)	provider change (re-init, --reset, or reinstall) never leaves a silently-authoritative stale file: init renames it and the preamble emits DEGRADED (tracker configuration mismatch)	transition test asserting both arms	covered
AC-3.21 (new)	manifest.features.tracker absent or malformed parses to {provider:'github'} and never makes parseManifest return null	manifest round-trip	covered
AC-3.22 (new)	hook output is independent of the developer's real $HOME	two temp HOMEs + config-disable-guards.test.ts env fix	covered

Additional flagged rows carried into this phase:

• Linear's borrowed 32767 — no phase measures it ⇒ ## Known Unknowns plus a filed probe issue with a named owner as a named 3c deliverable (P3c-S3).
• devflow tracker CLI — needs tests/tracker-cli.test.ts, mirroring compliance-cli.test.ts:24-127; syncManifestFeature (manifest.ts:271-282) is already generic and needs no change.

2.1 Standing AC — prefix-shippability (verbatim; applies at every phase boundary)

After phase N: (i) npm run build && npm test && npm run test:integration && npm pack --dry-run are green; (ii) a fresh install from the tarball drives /plan → /implement → /code-review → /resolve → /release on a GitHub project with no new prompt and no new file in git status; (iii) every artifact in the tree has at least one reachable consumer in this phase's end-state — no file, define, list element, frontmatter key or conditional arm exists solely for a later phase (ADR-003); (iv) the frozen github-status-lines.txt fixture is byte-identical to its Phase-0 capture.

Command sequence run at every boundary:

npm run build && npm test && npm run test:integration && npm pack --dry-run
git status --porcelain                     # must be empty
cmp -s <(extract-status-lines) tests/fixtures/golden/github-status-lines.txt   # clause (iv)

Clause (ii) additionally requires, once per phase before merge, a manual install of the packed tarball into a scratch $HOME and the five-command walk-through.

2.1.1 Clause (iii) is read per phase, not per commit — decision D-D

The prefix-shippability invariant says "After phase N". Phase 3 is one phase. Its clause (iii) obligation is therefore evaluated at the 3c boundary, not at each of 3a/3b/3c.

This matters concretely: _mcp.mds, redact-secrets.cjs --emit and tests/guards/mcp-sink-bypass.test.ts all land in 3a-4, and their first runtime consumer (a Jira per-op mechanics file that spells {SCRUBBED_BODY}) lands in 3b. Under a per-commit reading, 3a would ship three artifacts with no reachable consumer and fail its own gate. Under the phase-boundary reading — the one the invariant's own wording supports — 3a is fine and 3c closes the clause.

Consequences, stated so no reviewer reads AC-3.19 as blocking:

• _mcp.mds, --emit and the bypass guard stay in 3a. Do not defer them to 3b.
• Phase 2's AC-2.7 guard is re-scoped in 3a-4 (P3a-S12) from "no _mcp.md exists after a GitHub-only build" to "_mcp.md is generated only when a jira/linear module exists, and is never named from any github op file." Without this re-scope, gate G3.4 cannot be green (hazard H7).
• AC-3.19 is a process AC — encode it as a PR-template checklist item in the tracking issue. Do not fake a mechanical test for it.

---

3. Scope

3.1 Included

Selection substrate (3a-1)

• src/core/tracker.ts — TRACKER_PROVIDERS registry, TrackerProvider union, TrackerFeatureState, parseTrackerId (strict), normalizeTrackerFeature (tolerant), and the attempt-counter lifecycle pair trackerAttemptsPath / rearmTrackerInference [DR-22].
• src/cli/commands/tracker-prompts.ts — the four-part wizard-step contract.
• src/cli/commands/tracker.ts — devflow tracker --status/--set <id> (OD-13).
• init.ts wiring on both wizard paths, --tracker <id>, boundary parse, summary/outcome lines, --reset.
• init-seed.ts seed + defaults + reset gating; manifest.ts type + normalize + self-heal.
• uninstall.ts classification and disjointness; the .tracker.enabled sentinel writer [DR-10].
• The init-time provider-change rename transition (tracker.md → tracker.md.{old}.bak).

Tracker agent (3a-2)

• src/assets/agents/tracker.md — the agent, including the tracker.md writer-side schema template.
• src/core/plugins.ts:63 registration; every agent-enumerating test updated 16 → 17.

Hook (3a-3)

• session-start-context Section 3, inserted at :166, plus the two real-$HOME hook-test fixes.

MCP substrate + preamble (3a-4)

• src/assets/mds/tracker/_mcp.mds → references/tracker/_mcp.md.
• redact-secrets.cjs --emit with the decomposition, double scrub, framing and exit code 5.
• Git-agent preamble: provider resolution order, ref-grammar corroboration, project-key rule, mismatch guard, # UNRESOLVED: hard sentinel, - **Tracker**: status line, ## Tracker input contract block.
• src/core/feature-config.ts — the per-repo tracker key (OD-9).
• The Phase-3 byte-budget row and the ≤70-line preamble ceiling [DR-13].

Providers

• 3b — _jira.mds mechanics module + 10 generated per-op references + the Jira matrix column.
• 3c — _linear.mds mechanics module + 10 generated per-op references + the Linear matrix column + ## Known Unknowns + the filed probe issue + cross-provider parity and provider-literal pins.

Docs — CLAUDE.md, docs/reference/cli-reference.md, README.md:56, docs/reference/platform-assumptions.md (completed), a new .devflow/features/tracker-feature/KNOWLEDGE.md, CHANGELOG.md.

3.2 Deferred (named, with the reason and the cost of deferral)

Deferred	Why	Cost while deferred
Per-project tracker.md override (a repo-local conventions file)	The global file plus the per-repo tracker provider key covers the requester's journey; a per-project conventions file re-introduces a project-vs-global precedence rule, a second write-once lock, a second uninstall classification and a gitignore carve-out — all of which this phase deliberately deleted	A developer working across two Jira sites on one machine gets one global site value; the repo-derived sections (## Project key, ## Issue Types, ## Transitions, ## Wave Filter) are re-derived at call time from repo history, so the practical blast radius is limited to ## Project — site
Team-shared tracker config	The per-repo tracker key lives in .devflow/config.json, which .gitignore:44 (.devflow/* with re-includes only for features/ and conventions.md) keeps local-only. Sharing it needs a carve-out, a review of what else in config.json would become shared, and a team-vs-personal precedence rule	The per-repo override is per-developer, not team-shared. Every teammate on a Jira repo must set it themselves (or rely on ref-grammar corroboration, which is designed to get this right without configuration). State this in cli-reference.md

3.3 Excluded (deleted by design — record the deletion, ADR-003)

• No devflow:tracker-setup skill (skill count stays 41).
• No command-side question step; no tracker_learn_step(); no AskUserQuestion anywhere in the tracker path.
• No learn-tracker op — so git-agent.test.ts REQUIRED_OPS and registry-integrity.test.ts:397-405 INTERNAL_OPS need no new entry.
• No ## Tracker Discovery / ## Tracker Learned / ## Tracker Learning Required headings — all three are retired; no op emits them.
• No per-project .devflow/tracker.md and no consumer of one.
• No gitignore carve-out v4 in either writer, and no 3a-first merge choreography.
• No ADR-002 scoped-commit step (the Tracker agent runs no git command at all in its write path).
• No MCP-server detection from the hook — i.e. nothing reads ~/.claude.json.
• No --no-tracker flag — --tracker github is the off switch (decision D-E). A --no-tracker whose only meaning is "⇒ github" is a second spelling of an existing value.
• No _roster.mds row for Tracker.
• The DEGRADED literal interactive setup required — run /plan in an interactive session — retired, because no question step exists.
• The learned: frontmatter key in tracker.md — dropped, because no planner supplied a consumer and an unread field is residue under ADR-003 clause (iii).
• The rule ">50% unresolved ⇒ don't write" — dropped as arbitrary and colliding with retry semantics. The correct split is transient vs permanent: MCP absent/denied ⇒ write nothing (transient, retry); MCP present but evidence thin ⇒ write with sentinels (permanent, a human must decide).

---

4. Gap Analysis Results

Every gap this phase closes, one line each, with the step that closes it.

ID	One-line	Landing step
GAP-02	_mcp.md is 100% MCP content with zero reachable consumer in Phase 2 and would be billed to every GitHub user	P3a-S12 (authored in 3a, generation keyed on an MCP-backed provider)
GAP-04	D11's fail-closed gate is a shell && short-circuit that cannot exist for an MCP sink; the recipe silently downgrades a mechanical gate to an instruction	P3a-S11 (--emit) + P3a-S12 ({SCRUBBED_BODY} recipe)
GAP-07	Registry completeness, not scanned > 0 — agent-frontmatter.test.ts:35 is the only hand-maintained agent enumeration	P3a-S10
GAP-10	provider: reaches ~30 filename-composition sinks; PF-023 requires exactly one resolution root, and repair-not-reject would launder a hostile value	P3a-S1 (static map, reject-never-repair)
GAP-12	Three vocabularies (10 ops, 21 defines, 15 capabilities) with no mapping; AC-3.8's file-set parity has no subject	P3b-S3 + P3c-S4 (the matrix, all three columns)
GAP-13	~13 new DEGRADED literals with three synonyms for one condition, no consolidated registry, and a 60k→{cap} change that reads as contradicting AC-2.1	P3a-S14 (registry test) + P3b-S2/P3c-S5 (60000 present on GitHub, absent elsewhere)
GAP-16	tracker.md is a laundering path: ~11 values reach ~8 sink classes with shape rules specified for two, no secret gate, no query-injection rule, no size or read-tool bound	P3a-S16 (schema + validators) + P3a-S9 (D11 gate on the write)
GAP-17	The schema has no section → reader → neutral-default → validation table; four sections have no default, one offers an option no agent can execute, one contradicts manage-debt	P3a-S16 (writer) + P3a-S14 (reader) + tests/tracker/schema-scope.test.ts
GAP-18	The digits-only pre-flight is the shell-injection guard for interpolated refs; per-provider relaxation is a security change; numeric extraction from a TEAM-123 branch can write a correct-looking wrong Closes #123	P3c-S1 (anchored grammar + UUID alternative)
GAP-19	Nothing forbids an HTTP/curl fallback when a tracker MCP tool is absent or denied — the highest-value bypass of both D11 and the no-credential-read rule	P3a-S12 (the no-HTTP-fallback literal) + AC-3.18 negative greps
GAP-20	Marker ownership is violated by a caller-restated literal; author-filter-absent ⇒ do-not-post recreates the suppression hole; paginated marker reads make the dedup predicate unsound	P3b-S1 (namespaced first-line markers) + P3c-S2 (post-with-warning)
GAP-26	fetch_batch must be a single query, never a per-item loop	P3b-S2 / P3c-S2 change bullet + P3c-S5 negative [DR-08]
GAP-29	Acceptance-criteria coverage: the requester's own journey and several deliverables had no AC	AC-3.2, AC-3.11, AC-3.19 (marked process-only)
GAP-30	The collapsed <details> artifact comment and the 60k pointer sentence have no Jira/Linear analogue, and truncation can drop the evidence lines	P3b-S2 (render_collapsed_block ⇒ pointer sentence only; preservation order)
GAP-37	Marker dedup predicates and devflow policy bounds would be triplicated across provider modules where only size_cap and the rate-limit signal are genuine provider facts	P3b-S2 / P3c-S2 (cross-cutting data stays in the contract layer)
GAP-38	No guard stops a command from reading tracker.md the way release.md:85 reads conventions.md	AC-3.18 negative grep over command sources and dist/commands/*.md
GAP-40	Linear's unpublished facts are borrowed with no probe owner; the "measured" cap is measured by no phase	P3c-S3 (## Known Unknowns + filed probe issue with a named owner)
GAP-42	A single-provider file-set-parity scaffold is a vacuous scan	P3c-S4 (providers.length === 3, both directions)
GAP-48	Provider resolution and capability resolution are two independent checks with no observable distinction	P3a-S14 (optional per-run capability attestation line)
GAP-54	redact-secrets.cjs:85-88 skips a candidate containing a placeholder, so api_key = "<x> AKIA…" disarms rule 8	P3a-S11 change 8 (anchored placeholder match)
GAP-34	Carve-out v4	VOID — deleted in its entirety; no gitignore work in this phase

---

5. Execution Strategy

SEQUENTIAL_CODE_AGENTS — 6 subtasks: 3a-1 → 3a-2 → 3a-3 → 3a-4 → 3b → 3c. Phase context risk: HIGH.

One issue, three ordered commits 3a → 3b → 3c on one branch (decision D-C). 3a alone spans five domains — TypeScript core, CLI, hooks, prompt assets, shell scripts — and is the phase's bulk, so it is executed as four sequential Code agents producing one commit group. init.ts (2,007 lines) is flagged critically unstable by the skim heatmap and 3a is its largest single consumer, which is why 3a-1's init/manifest work is its own reviewable commit inside the phase.

5.1 Why PARALLEL_CODE_AGENTS is rejected

Three independent facts, any one sufficient (PF-020's closure rule: disjointness must hold over each agent's READ/EXECUTE closure, not merely its WRITE set):

1. npm run build is rm -rf dist && … (package.json:20). Every Code agent's verification step deletes and rebuilds the one shared dist/. A sibling agent mid-suite observes a missing dist tree — and every dist-scanning guard in this feature deliberately fails loud on a missing directory. Parallel agents therefore manufacture nondeterministic red suites that look exactly like real regressions.
2. /implement has no worktree isolation — grep for worktree in implement.mds returns zero hits. All Code agents share one worktree, one git index, one dist/, one node_modules, one vitest run.
3. The test corpus spans every partition. The seam test, the D11 sink-class guard, the containment test and the frozen fixture all read git.md ∪ dist/commands/*.md ∪ dist/skills/git/references/** — the union of every proposed subtask's outputs.

The closest legitimate candidate, recorded so it is not re-litigated: 3a-1 (TS selection substrate) ∥ 3a-2 (prompt asset + plugins.ts). Write sets are genuinely disjoint including test files. It is still rejected on the shared-dist/ and no-worktree-isolation grounds. If parallelism is ever wanted here it requires per-agent git worktrees with per-worktree dist/, which /implement does not support — a tooling change, not a plan change.

5.2 ★ The agent-before-hook ordering — conflict C4 (load-bearing; ALREADY APPLIED below)

tests/agent-name-guards.test.ts:618-673 scans dist/commands/*.md and every hook script for subagent_type[=:]\s*\\?"…" (:641 — note the shell-escaped form used inside hook heredocs) and requires a byte-equal match to a real agent's frontmatter name:, with a >= 50 match floor (:665-668).

A hook that names Tracker before src/assets/agents/tracker.md exists turns that guard red at the subtask boundary.

Therefore: the Tracker agent lands in 3a-2 and the hook lands in 3a-3 — this is conflict C4 (agent-before-hook), resolved here. This ordering is already applied throughout §7 — the step numbers are not sequential in commit order, and that is deliberate. Gate G3.2 blocks 3a-3 until the 17-agent guards are green (hazard H8).

5.3 Context risk per subtask

Subtask	Risk	Driver
3a-1	HIGH	init.ts is 2,007 lines and flagged critically unstable; 10 edit sites across two wizard paths + seed + reset + re-init + uninstall. Compliance is a byte-for-byte template — the mitigating factor
3a-2	MEDIUM	One new ~250-line prompt asset + 5 hand-maintained test enumerations
3a-3	HIGH	tests/shell-hooks.test.ts is 2,677 lines; the new describe needs ~15 cases including backend parity with _HAS_JQ=false
3a-4	HIGH	Amends a normative single-stdout-boundary block in redact-secrets.cjs and adds preamble prose to git.mds — two files with maximal blast radius
3b / 3c	MEDIUM	Self-contained modules; risk is in the DEGRADED-literal vocabulary drifting from the canonical table in §14

5.4 Run splitting — the one pre-authorised seam (conflict C18)

Six sequential Code agents in one /implement run is at the upper end. If the run must be split, the only safe seam is 3a-4 → 3b (conflict C18 / decision D-G(a); D-C keeps Phase 3 one issue): re-invoke /implement against the same issue and the same branch, with CREATE_PR: false on the first run's terminal agent (3a-4) and CREATE_PR: true on the second run's terminal agent (3c). This is pre-authorised — no further approval is needed to take it.

Never split inside 3a. 3a's four subtasks are one commit group; splitting them across /implement runs risks landing the hook before the agent (H8) or the preamble before the schema template (drift the two-sided heading test exists to catch).

5.5 Standing execution rules

R1 — TDD, RED-first, with a known-bad sample. The authoring order for every step is: write the guard → observe RED → apply the change → GREEN. A guard with no known-bad sample is not accepted. Three RED mechanics in decreasing preference: (a) run the guard against the pre-fix tree and record the failure text in the PR body; (b) an inline known-bad sample asserted inside the same it (copy the shape at git-agent.test.ts:419-424); (c) a seeded bad fixture in a temp tree (build-mds.test.ts:495-531 spawnSync shape, installer-new.test.ts mkdtemp lifecycle). Never revert a landed fix to demonstrate red.

R2 — No threshold is ever lowered. postingOps.length >= 8 · matchCount >= 50 · 60000 · ≤50 · head -50 / head -20 / --limit 30 / --max-count=200 · the 3,072-byte charter cap · >= 2 marker-occurrence floors · toHaveLength(11) / toBe(13) / toBe(14). When text moves, the corpus widens; the number does not move.

R3 — Fail-loud on missing dist. Every dist-scanning guard throws with a build hint, never returns/skips. Use requireDistFiles() / requireDistFile() (tests/helpers.ts:14-37). "A guard that silently skips on a missing build artifact is not a guard."

R4 — Temp HOME in every hook test. Any hook test that can reach Section 3 must pass env: { ...process.env, HOME: tmpHome }. Seed the temp HOME — never an empty fixture (PF-018). Fixtures write paths using the same string passed as cwd; assert both raw and realpath forms (macOS /private).

R5 — Never scanned > 0 over the agent corpus. Use resolveAllAgents() and the mandatory assertion expect([...resolveAllAgents().keys()]).toEqual(expect.arrayContaining(getAllAgentNames())) — 16 today, 17 after 3a-2. Rationale to restate: 15 of 16 agents survive scanned > 0 while coverage of git silently disappears.

R6 — Every commit is green on its own. npm run build && npm test && npm run test:integration && npm pack --dry-run at every commit boundary.

Test-file naming scheme (repo-wide for this feature): tests/seams/ · tests/goldens/ · tests/guards/ · tests/tracker/ · tests/installer/ · tests/dynamic/ · tests/core/.

---

6. Subtask Breakdown

#	Domain	Owned files (with anchors)	Steps	Depends on	Gate	Handoff contents
3a-1	TS core + CLI + uninstall	new src/core/tracker.ts · new src/cli/commands/tracker-prompts.ts · new src/cli/commands/tracker.ts · src/cli/commands/init.ts (:222-238, :259-265, :291-292, :375-392, :438-453, :665-688, :744, :753, :924-958, :947-951, :1996) · src/cli/commands/init-seed.ts (:35-49, :52-61, :87-115, :335, :355-369) · src/core/manifest.ts (:38-72, :135-142, :229) · src/cli/commands/uninstall.ts (:227-265, :283-306) · new tests/core/tracker.test.ts · new tests/tracker-prompts.test.ts · new tests/tracker-cli.test.ts · tests/manifest.test.ts · tests/init-seed.test.ts · tests/uninstall-logic.test.ts:913-935	P3a-S1, S2, S3, S4, S5, S6, S15, S17	Phase 2 merged to main	G3.1	the manifest key path literal features.tracker.provider as a shared constant · confirmation that features.tracker is absent-tolerant and never in the hard-null set at manifest.ts:151-165 · the chosen model tier (sonnet) so tracker.md's frontmatter and the hook allowlist agree · the .tracker.enabled sentinel path and its write/remove rule [DR-10] · the rearmTrackerInference helper name and the two call sites [DR-22] · the explicit pairing note that P3a-S15's rename and P3a-S17's user-content classification are void unless 3a-4's P3a-S14 mismatch guard ships in the same 3a group (the OD-15 reversal condition)
3a-2	prompt assets + agent-enumerating tests	new src/assets/agents/tracker.md (incl. the tracker.md schema template) · src/core/plugins.ts:63 · tests/agent-frontmatter.test.ts:35, :36-53 (16→17) · tests/agent-name-guards.test.ts (:511-524, :618-673) · tests/build.test.ts — [D21] re-verify the tests/build.test.ts repoint ranges (plan-1 :46-55/:84-91/:106-135 vs plan-2 :45-55/:84-92/:100-140, neither verified) before asserting no literal edits are needed · tests/skill-references.test.ts · new tests/tracker-agent.test.ts · new tests/tracker/hostile-values.test.ts	P3a-S9, S16, S10	3a-1	G3.2	tracker.md's frontmatter name: byte-exactly (Tracker) · the claim-file path {devflowDir}/.tracker.processing and the attempt-counter path · the statement that _roster.mds gains no row and plugins.ts uses a structural, not exempted, Guard-5 pass · the schema section names verbatim, so 3a-4's ## Tracker input contract block matches
3a-3	hooks + tests	src/assets/scripts/hooks/session-start-context (:8-13, insert at :166) · tests/shell-hooks.test.ts (new describe beside :1670) · tests/config-disable-guards.test.ts:190-221 · the TS↔shell key-path parity constant + its test	P3a-S7, S8	3a-2 (the agent file must exist first)	G3.3	the allowlisted provider case literal and the byte-identical silence clause · the resolved ${DEVFLOW_DIR:-$HOME/.devflow} idiom · the named TRACKER_PROCESSING_STALE_SECS constant · the counter-increment rule at directive emission [DR-02]
3a-4	prompt assets + scripts + tests	new src/assets/mds/tracker/_mcp.mds · src/assets/scripts/redact-secrets.cjs (--emit, :85-88 narrowing, exit 5, amended :380-410 block) · tests/redact-secrets.test.ts (new describes) · src/assets/agents/git.mds:29 preamble additions · src/core/feature-config.ts (the tracker key) · new tests/guards/mcp-sink-bypass.test.ts · new tests/tracker/schema-scope.test.ts · new tests/tracker/byte-budget.test.ts (P3a-S18, BUDGET_GIT_MD_P3) · tests/fixtures/golden/git-agent.md (P3a-S18 — the standalone golden-regeneration commit) · docs/reference/platform-assumptions.md · P3a-S19 docs: CLAUDE.md · docs/reference/cli-reference.md · README.md · new .devflow/features/tracker-feature/KNOWLEDGE.md · CHANGELOG.md	P3a-S11, S12, S13, S14, S18, S19	3a-3	G3.4	the _mcp.md generation-gating disposition · the D11-OK <nonce> <sha256> <bytes> <n> [type:count,…] framing literal verbatim [DR-01] · the <bytes> verification clause [DR-06] · the capability-probe table · the re-derived BUDGET_GIT_MD_P3 and the ≤70-line preamble ceiling [DR-13]
3b	prompt assets + tests	new src/assets/mds/tracker/_jira.mds · its manifest rows in scripts/build-mds.ts · new tests/tracker/jira-module.test.ts	P3b-S1, S2, S3	3a-4	G3.5	the file-set / define-set parity shape now that N = 2 providers · the marker-namespacing scheme (devflow:shipped / devflow:wave / devflow:traceability) · the DEGRADED literals actually emitted, checked against §14's canonical table · the per-op aggregate call budget literal [DR-09]
3c	prompt assets + tests	new src/assets/mds/tracker/_linear.mds · manifest rows · new tests/tracker/linear-module.test.ts · new tests/provider-literals.test.ts · ## Known Unknowns + the filed probe issue	P3c-S1 … S7	3b	G3.6	— (terminal)

6.1 Gates

Gate	Must be green before	Assertions
G3.1	3a-2 starts	tests/tracker-prompts.test.ts green incl. the 8-row gate matrix and the hostile-value table · manifest round-trip: a manifest with no features.tracker parses; features.tracker: "jira" (a string) self-heals to {provider:'github'}; parseManifest never returns null (AC-3.21) · uninstall disjointness test 9f extended to before.length === 6 · --reset ⇒ github · rearmTrackerInference unit cases + one call-site assertion each in init-seed.test.ts and tracker-cli.test.ts [DR-22] · the .tracker.enabled sentinel is written when the resolved provider ≠ github and removed when it is [DR-10]
G3.2	3a-3 starts	loadShippedDefaults() ⊇ getAllAgentNames() = 17 and ['tracker'] === 'sonnet' · agent-frontmatter retitled 16→17 · agent-name-guards capitalizeFirst and the >= 50 floor green · tracker.md has no tools: key and no Agent(/subagent_type literal · _roster.mds unchanged
G3.3	3a-4 starts	Full shell-hooks Section-3 suite green incl. hostile providers ⇒ no directive; source: resume/compact ⇒ no directive; fresh/stale claim; attempt cap at N=5; counter incremented on directive emission [DR-02]; provider github ⇒ zero subprocess invocations [DR-10]; _HAS_JQ=false parity; envelope key-set (:1010-1018 and :297 — [drift: two planners cite :701/:710, which are the UserPromptSubmit preamble assertions]) · config-disable-guards.test.ts passes under a seeded temp $HOME with provider=jira (AC-3.22)
G3.4	3b starts	--emit prints no body on every non-zero path with a per-invocation nonce (AC-3.5) · the framing carries <n> [type:count,…] and the SOURCE module src/assets/mds/tracker/_mcp.mds names both SCRUB: and SECRET-EXPOSED [DR-01] · the same SOURCE module names the <bytes> verification [DR-06] — [E2] both clauses are asserted against the source .mds, never the generated dist/skills/git/references/tracker/_mcp.md, which does not exist at the 3a boundary because generation is keyed on a jira/linear module existing (P3a-S12 / hazard H7 / conflict C5) · the MCP bypass guard proven red on create_comment(body: $DEVFLOW_BODY_RAW) · the AC-2.7 _mcp.md guard re-scoped (H7) · hostile-tracker.md table green for every field, normalisation literal appears exactly once (AC-3.7) · the two-sided schema-heading test green with >= 11 sections [DR-21] · the DEGRADED registry test green in both directions [DR-04] · BUDGET_GIT_MD_P3 and the ≤70-line preamble ceiling green [DR-13] · P3a-S14's mismatch guard confirmed shipped (the precondition for 3a-1's user-content classification and the rename transition)
G3.5	3c starts	File-set + define-set parity across two providers both directions, every define non-empty (AC-3.8 partial) · 32767 pinned; 60000 / X-RateLimit-Remaining absent from _jira.mds; Retry-After present (AC-3.13) · the fetch_batch single-query bullet present and no per-item fetch verb in the batch reference [DR-08] · the aggregate call budget pinned as a tested literal [DR-09] · frozen status lines unchanged
G3.6	PR opens	Full prefix-shippability · parity across three providers · AC-3.12 · AC-3.18 · AC-3.19 (process checklist) · the _mcp.md shared-literal registry negative arm green and non-vacuous [DR-19] · the Phase-3 tests/fixtures/golden/git-agent.md regeneration commit is present and standalone (its own commit, reviewed as a text diff, no behaviour change in it) and tests/fixtures/golden/github-status-lines.txt is byte-identical to its Phase-0 capture [DR-03]

6.2 /implement spawn notes

• Spawn one Code agent per subtask, in the order 3a-1 → 3a-2 → 3a-3 → 3a-4 → 3b → 3c. Each agent's prompt carries this artifact's §7 step block for its subtask, its row of the table above, its gate, and the handoff it receives.
• Commits are pathspec-scoped (git commit -- <owned paths>) so per-commit provenance survives the squash-merge.
• Three commits, not six. 3a-1 … 3a-4 produce the single 3a commit group; the phase's commit boundaries are 3a, 3b, 3c.
• Spawn-input contract (implement.mds:136-172) — stated per agent so nothing is left to inference:
  • 3a-1 · 3a-2 · 3a-3 · 3a-4 · 3b — CREATE_PR: false, PUSH: false, HANDOFF_REQUIRED: true.
  • 3c — CREATE_PR: true, PUSH: true. implement.mds:409: "The last sequential Code agent (with CREATE_PR: true) handles PR creation" — for SEQUENTIAL_CODE_AGENTS there is no separate Git-agent PR-creation step, so a terminal agent carrying CREATE_PR: false ends the phase with commits on a branch and no PR, and the Closes #325 traceability chain never fires.
• [I10] Handoff, stated explicitly on every spawn: HANDOFF_REQUIRED: true on every subtask but the last; every Code agent reads and writes HANDOFF_FILE = .devflow/docs/handoff-{branch_slug}.md (implement.mds:151), writing its §6-row "Handoff contents" after its own gate passes. PUSH is a Code-agent input (code.md:34, :83) that implement.mds's spawn template does not carry — state it in each spawn prompt.
• The 3a-4 → 3b run seam is pre-authorised (§5.4; conflict C18 / decision D-G(a)). Taking it changes which agent is terminal: the first run's terminal agent (3a-4) keeps CREATE_PR: false, the second run's terminal agent (3c) carries CREATE_PR: true. Re-invoke /implement on the same issue and the same branch.
• Standing instruction for every Code prompt: "a golden mismatch means the source is wrong, never the fixture."

6.3 Assumptions applied (all confirmed at Gate 2; every step is written against the recommendation)

ID	Decision	Where it shapes a step
OD-9	Per-repo tracker key in .devflow/config.json + ref-grammar corroboration. The corrected rule: the signal is the repo's issue grammar, NEVER "GitHub remote + gh auth ⇒ github" — devflow deliberately keeps PR hosting on GitHub while the tracker is Jira, so that condition is TRUE for essentially every Jira user including the requester, and would disable the feature for exactly the user it targets	P3a-S13, P3a-S14
OD-10	Tracker agent model: sonnet	P3a-S9 frontmatter, P3a-S7 hook model allowlist case, P3a-S10 loadShippedDefaults()['tracker'] === 'sonnet'
OD-11	The agent probes and records ## Dedup Strategy with probe evidence; the recorded value is a hint that may only narrow the probe order — the live probe is the sole authority for the DEGRADED reason	P3a-S9 (probe ladder + section); P3b-S2 / P3c-S2 read it as a hint only
OD-12	Linear ships at rank 4 (post-with-warning): there is no viewer/"me" tool on a stock official Linear MCP (six independent catalogs agree) and create_attachment is a base64 upload, not the URL-link form, so Linear's documented URL idempotency is unreachable. Ranks 1 and 3 both require a non-stock server. Ships with ## Known Unknowns and a filed probe issue as a named 3c deliverable	P3c-S2, P3c-S3, P3c-S5
OD-13	Minimal devflow tracker --status/--set <id> in 3a	P3a-S6
OD-14	Attempt cap N = 5	P3a-S7 (hook cap + increment), P3a-S9 (agent increment/reset), P3a-S3/P3a-S6 (re-arm), P3a-S17 (install artifact)
OD-15	~/.devflow/tracker.md is user content on uninstall, conditional on the mismatch guard shipping; reversal condition recorded	P3a-S17, conditional on P3a-S14
D-B	Process-only ACs: AC-3.19, and the live-MCP walk-throughs of AC-3.2 and AC-3.11. Encode as a PR-template checklist in the tracking issue. Do not fake a mechanical test.	§2
D-C	One issue, three commits 3a → 3b → 3c; the 3a-4 → 3b /implement re-invocation is pre-authorised; never split inside 3a	§5.4, §6.2
D-D	Prefix-shippability clause (iii) is read per phase; _mcp.mds, --emit and the bypass guard stay in 3a; AC-2.7's guard is re-scoped in 3a-4	§2.1.1, P3a-S12
D-E	Omit --no-tracker — --tracker github is the off switch	§3.3, P3a-S3
D-F	N = 5 is re-armed by devflow init and by devflow tracker --set/--status; both paths documented in cli-reference.md	P3a-S1 (the helper), P3a-S3, P3a-S6, P3a-S19
D-G	Pre-authorised splits: in-PR splits (Phase 2's per-op commits) and the 3a-4 → 3b /implement run split (same branch, CREATE_PR: false on the first run's terminal agent) are pre-authorised; a PR-level split changes the issue count and requires explicit approval; never split inside 3a	§5.4, §6.2

---

7. Implementation Plan

Steps are listed in commit order, which is not numeric order — the agent-before-hook correction (§5.2) puts P3a-S9/S16/S10 before P3a-S7/S8. Design-review resolutions are folded into the step that owns them and tagged [DR-nn].

── COMMIT 3a — selection substrate + agent + hook + MCP substrate ──

3a-1 · Selection substrate

P3a-S1 — src/core/tracker.ts: registry + strict parser + tolerant normalizer + counter lifecycle

• Goal: One typed module owning the provider domain, mirroring compliance but rejecting rather than repairing.
• Files: new src/core/tracker.ts.
• Change:
  • TRACKER_PROVIDERS registry {id,label,hint} mirroring compliance.ts:44-51, carrying its doc verbatim: "Labels are stamped verbatim into installed artifacts — no user input is ever written."
  • type TrackerProvider = 'github'|'jira'|'linear'; interface TrackerFeatureState { provider: TrackerProvider } mirroring compliance.ts:19-24. Drop the enabled field compliance carries — provider:'github' is the off position, and {enabled:false, provider:'jira'} would be incoherent. Record that rationale in the file.
  • parseTrackerId — strict boundary parser, mirroring compliance.ts:131-152 parseFrameworkList: returns {ok:true;value} | {ok:false;error}; the error names every valid ID and the offending value; all-invalid never yields a silent empty.
  • normalizeTrackerFeature — tolerant sink normalizer, mirroring compliance.ts:113-124 + :161-183: drop-not-error, ADR-014 self-heal. Divergence to record: normalizeId (compliance.ts:84) repairs (space→dash, alias); repair is forbidden for provider — copy the shape, not normalizeId.
  • The validated token selects a hardcoded path prefix from a static map (compliance.ts:74 LABEL_BY_ID; compliance-compose.ts:117-125's "Never ?? id: falling back to the raw ID is exactly the echo this exists to prevent"). The input string is never concatenated into a path.
  • [DR-22] The attempt-counter lifecycle lives here and only here. Add, beside the registry:
    • trackerAttemptsPath(devflowDir): string — pure path derivation.
    • rearmTrackerInference(devflowDir): Result<void, TrackerError> — removes the counter; idempotent when absent; never throws (PF-014). init.ts and src/cli/commands/tracker.ts each call it exactly once. A bare "also delete this file" appended to an eleven-row edit list in a 2,007-line file is the same policy expressed twice with no owner — this is the owner.
  • [DR-10] The presence sentinel is derived here too: trackerEnabledSentinelPath(devflowDir) → {devflowDir}/.tracker.enabled, a zero-byte sentinel written whenever the resolved provider ≠ github and removed when it is. Writers are init.ts (P3a-S3) and devflow tracker --set (P3a-S6); the sole reader is the hook (P3a-S7 step 2).
• Ids: AC-3.7, EC-59, EC-63, GAP-10, S5.
• RED-first: tests/core/tracker.test.ts written first. Hostile table: JIRA, jira (trailing space), jira-cloud, ../../etc/passwd, github/../../rules/devflow, empty, 200 chars, `id`, . Assert reject, never repair — jira-cloud must error, not normalise to jira. Plus three rearmTrackerInference cases: idempotent when absent · removes when present · never throws [DR-22].

P3a-S2 — src/cli/commands/tracker-prompts.ts (four-part wizard-step contract)

• Files: new src/cli/commands/tracker-prompts.ts; new tests/tracker-prompts.test.ts mirroring tests/compliance-prompts.test.ts structurally, byte-for-byte as a template: header :1-13; makePrompts fake-IO builder :33-57 (queue-consuming, failing loudly when over-consumed); describe('shouldRunComplianceStep') :59 with rows 1–8 at :60-131; describe('runComplianceStep') :136; mutation-safety its :252/:274; 'Current setting:' note its :292/:307.
• Change — four exports:
  • shouldRunTrackerStep — the compliance-prompts.ts:77-99 gate, signature {mode, modePromptShown, isTTY, hasCliOverride}.
  • TrackerPromptIO extends WizardPromptIO — the :103-116 extension pattern. WizardPromptIO.select is boolean-typed, so declare a sibling, not a widened generic; prompt-io.ts:61-70 clackSelect<T> is already generic, so a 3-value select needs no helper change.
  • buildClackTrackerPrompts (:117-137) and formatTrackerSummary (:56-68).
  • runTrackerStep (:178-…) returning {kind:'resolved';state;messages} | {kind:'cancelled'} — never process.exit, never throws (PF-014). init.ts owns p.cancel(...); process.exit(0) at the caller (init.ts:940-943). Defensive copies throughout.
  • Header restates ADR-013, ADR-019, PF-029, PF-014 exactly as compliance-prompts.ts:1-15 does.
• Rationale to record (copy compliance, not attribution): attribution (attribution-prompts.ts:51-57) is Advanced-only because it silently rewrites git metadata; a wrong tracker provider is immediately visible and trivially reversible, while a user who never sees the question silently gets github — invisible to exactly the Jira/Linear user who needs the prompt. Compliance's signature is also the only one already carrying hasCliOverride, which --tracker needs. Gate on modePromptShown, never on the mode name (PF-029). Use p.select, never p.confirm — Enter-through must be an informed keep.
• Ids: AC-3.6 (repurposed), EC-56, EC-57, EC-58, EC-60.
• Verify: gate-table test over the same four-input matrix as compliance; zero prompts under --recommended and !isTTY; note text containing the seeded value (Current setting: …); outcome-line assertion.

P3a-S3 — init.ts wiring (flag, option type, boundary parse, both wizard paths, summary/outcome, --reset)

file:line	Change
init.ts:291-292	.option('--tracker <id>', 'Issue tracker provider: github, jira, or linear') immediately after the two compliance options. --no-tracker is omitted (decision D-E) — --tracker github is the off switch
init.ts:259-265	InitOptions += tracker?: string
init.ts:222-238	resolveTrackerInitState(option, seedProvider) beside resolveComplianceInitState
init.ts:438-453	Boundary parse block mirroring the compliance block verbatim in shape: let cliTrackerOverride: TrackerFeatureState | undefined, p.log.error(result.error) + process.exit(1) on !ok, before any prompt
init.ts:665-688	Recommended-path call site, after the compliance step's closing brace (:688)
init.ts:924-958	Advanced / re-init call site, inserted between compliance and attribution, incl. the else if (cliTrackerOverride !== undefined) honour-without-prompting arm (:952-956 shape). Re-init is Advanced-only by construction (:668-670), so a Recommended-only implementation would be dead on every re-init
init.ts:744 / :753	Recommended summary block gains Tracker: {…} — Recommended emits no per-step outcome lines, so the summary is its only surface
init.ts:947-951	Advanced outcome-line loop — mandatory, since Advanced has no end-of-wizard recap
init.ts:375-392 and :1996	The early manifest read (preserve tracker alongside compliance) and the single writeManifest call site
init.ts (new, post-resolution)	[DR-22] Call rearmTrackerInference(devflowDir) once — the documented re-arm path (OD-14 / D-F). Do not inline an fs.rm
init.ts (new, post-resolution)	[DR-10] Write {devflowDir}/.tracker.enabled (zero bytes) when the resolved provider ≠ github; remove it when the resolved provider is github. This is the hook's cheap gate

• Ids: AC-3.6, EC-56..EC-62, GAP-29.
• Verify: both-path test behind one shared predicate (the predicate is the single authority); precedence cliOverride ?? wizardResult ?? seed; flag ⇒ zero prompts; --reset ⇒ github and the stale-file transition fires; one call-site assertion that rearmTrackerInference is invoked [DR-22]; sentinel written/removed per resolved provider [DR-10].

P3a-S4 — init-seed.ts seed, defaults, --reset

• Files [verified]: init-seed.ts:35-49 (FeatureSeed += tracker: TrackerFeatureState), :52-61 (FEATURE_DEFAULTS += tracker: { provider: 'github' }), :87-115 (resolveSeedFeatures — use const tracker = { ...rawTracker }; the defensive spread is mandatory — :97-101 documents verbatim why ?? alone returns the module-level default by reference and "downstream mutation would corrupt it process-wide"), :335 (resolveResetGatedInputs — --reset ⇒ github), :355-369 (applyCliToggles += tracker: toggles.tracker ?? base.tracker).
• Ids: EC-62, A.1 "Seed on re-init".
• RED-first: a test that mutates the returned seed and asserts FEATURE_DEFAULTS.tracker is unchanged.

P3a-S5 — manifest.ts type, normalize, self-heal

• Files [verified]: manifest.ts:38-72 (add tracker: TrackerFeatureState after compliance at :71, doc-comment mirroring :66-71), :229 (tracker: normalizeTrackerFeature(features.tracker) immediately after the compliance line), :135-142 (add the row to the self-heal JSDoc). :258-263 writeManifest and :271-282 syncManifestFeature<K extends keyof ManifestData['features']> need zero changes — both are already generic.
• Change: NEVER add tracker to the hard-null validation set at :151-165. A pre-tracker manifest would become "no prior install" for every existing user. Put that sentence in the code as a comment.
• [DR-26] Recorded consequence: a malformed manifest value self-heals to github silently — that is the correct ADR-014 behaviour and it emits no DEGRADED. The canonical table in §14 carries this as its own row ("manifest value malformed ⇒ (none — self-healed to github, ADR-014)"), and the unknown tracker provider reason is narrowed to the per-repo config value. The two must not be conflated.
• Ids: AC-3.21 (new), EC-63.
• RED-first: round-trip — a manifest without features.tracker parses to {provider:'github'}; features.tracker: "jira" (a string, not an object) parses to the default, not null; parseManifest never returns null for either.

P3a-S6 — devflow tracker --status / --set <id> CLI

• Files: new src/cli/commands/tracker.ts; registration beside devflow agents / devflow proxy; new tests/tracker-cli.test.ts mirroring compliance-cli.test.ts:24-127 resolveComplianceCliAction.
• [DR-25] One line to record, in the file header: "src/core/tracker.ts (domain) + src/cli/commands/tracker.ts (CLI) mirrors the compliance.ts pair exactly; ADR-013's pure-core / I/O-target split is the reason both names exist." A reviewer meeting five tracker* files in one commit otherwise has no signal that the duplication is deliberate. Record it again in the 3a docs sweep's tracker KB section.
• Change: ~30 lines. --status prints the manifest provider and ~/.devflow/tracker.md's presence/provenance. --set <id> parses via parseTrackerId, calls syncManifestFeature('tracker', …) (already generic — zero manifest changes), invokes the provider-change rename transition (P3a-S15), calls rearmTrackerInference once [DR-22], and writes/removes the .tracker.enabled sentinel [DR-10].
• Ids: OD-13, EC-61.
• Verify: --set jira-cloud exits non-zero naming valid IDs; --set jira with a stale tracker.md renames it and reports the rename; one call-site assertion for rearmTrackerInference.

P3a-S15 — Init-time provider-change rename (the writer's repair)

• Files: `sr

…truncated — full report in the local design artifact .devflow/docs/design/tracker-phase-3.2026-09-05_1155.md (not committed; ask the author)

[dean0x]

Implementation Plan

Design artifact posted as collapsed comment above