Skip to content

JWB-945: Tracker port v2 — registry and vendor-neutral adapter contract - #95

Merged
JarenKempton merged 1 commit into
mainfrom
task/JWB-945
Nov 13, 2026
Merged

JarenKempton merged 1 commit into
mainfrom
task/JWB-945

Conversation

@JarenKempton

@JarenKempton JarenKempton commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Interlock lane interlock-lane:49bb04be-ac4f-4a2a-9c33-123d5aebe3a4

Jira JWB-945. Tracker port v2: core reaches trackers only through a registry and a vendor-neutral port.

What changed

  • src/app/tracker/registry.ts is the only file that imports a tracker adapter. Pickup, release, supervisor, the lane tracker, login/logout and doctor all go through it.
  • Port (src/domain/tracker/port.ts): methods are camelCase. listWork, complete and linkArtifact are optional. removeMirror is now part of the port, along with the journaled-write hooks.
  • Sign-in has an auth kind: none, external_cli or token.
  • Each adapter has a mirror tier: structured (claim and run are read back through claimMarker) or assignee_only. ADR 0002 is amended so the Git ref is the only exact authority for assignee-only trackers.
  • There is one ticket type in domain/tracker/ticket.ts, and kind is optional (default task). Removed: the capability registry (CAPABILITIES, requireCapabilities, Run.capabilities, ClaimLock.describe), Jira Rank discovery and Ticket.order.
  • Adapter kit: the fake tracker moved to src/conformance/fake-tracker.ts. The conformance suite now adjusts its checks to the mirror tier and gained a remove_mirror scenario. docs/domain-model.md has a new "Write an adapter" section.

Surface changes to know about

  • doctor --json reports tracker sign-in as trackers: { jira: {...} }. Before, it was a top-level jira key. The text output is unchanged.
  • New journal and recovery evidence is written under pendingTrackerWrite. Rows written under the old pendingJiraWrite key are still read; there is a test for it.
  • Jira read is now a single issue GET. It no longer searches the parent map to compute order. listWork still sends ORDER BY Rank ASC, and the supervisor launches in that order.
  • The config keys (jira_site, tracker.jira.site) are unchanged.

Acceptance evidence (head c6fc069)

AC Evidence
Registry is the only place that names an adapter; core imports no vendor code grep -rln "adapters/trackers/jira|JiraTrackerAdapter|jiraSignIn" src → only src/adapters/trackers/jira/{sign-in,tracker}.ts and src/app/tracker/registry.ts. Lint enforces it: with a probe file src/app/lane/probe-vendor.ts importing ../../adapters/trackers/jira/sign-in.ts, vp check fails with eslint(no-restricted-imports) … help: Only src/app/tracker/registry.ts names a tracker adapter.
camelCase; optional listWork/complete/linkArtifact; auth kind src/domain/tracker/port.ts. grep -rn "link_artifact|list_work|\.transition(" src → none
Mirror tier + ADR 0002 StructuredTracker / AssigneeOnlyTracker are in the port, Jira declares structured, and the ADR amendment is in docs/adr/0002-…
Optional kind, one ticket type, capability registry and Rank/order removed grep -rn "CAPABILITIES|requireCapabilities|rankField|\.order\b" src → none
Adapter kit and docs; Jira unchanged test/conformance/runner.test.ts: the fake passes in both tiers (18 cases); Jira passes the same suite in test/adapters/trackers/jira/tracker.test.ts

Commands run at this head:

vp check           → pass: Found no warnings, lint errors, or type errors in 174 files
vp run typecheck   → exit 0
vp run test        → 688 pass, 0 fail

Real path, read-only against live Jira (responsibid). Scratch copy of the ledger with XDG_STATE_HOME; baseline is a detached worktree at 858f3e1 (main):

bun src/main.ts doctor --project JWB
  main and branch print the same five ✓ lines:
  ✓ Jira signed in at https://responsibid.atlassian.net as jaren.kempton (credential store)
  ✓ Jira permissions in JWB: browse, transition, assign, edit issue properties
  ...
bun src/main.ts pickup JWB-964 --dry-run --json
  both exit 0, state "planned", ticket jira:responsibid:JWB:ticket:JWB-964, branch task/JWB-964;
  the plan JSON differs only in the self-command path in the lane procedure lines.

Not verified live: Jira mirror writes (apply, restore, complete, linkArtifact). Mutating real tracker state was not authorized, so the injected-transport FakeJira tests and the conformance suite cover these paths.

🤖 Generated with Claude Code

…ontract

- src/app/tracker/registry.ts is the only file that imports a tracker
  adapter; lint (no-restricted-imports) rejects any other import from
  src/adapters/trackers/.
- Port methods are camelCase; listWork, complete and linkArtifact are
  optional; removeMirror, pendingWrite and verifyPendingWrite are on the port.
- Sign-in declares an auth kind: none, external_cli or token.
- Adapters declare a mirror tier, structured or assignee_only; ADR 0002 is
  amended so the Git ref is the only exact authority for assignee-only.
- One ticket type with optional kind (default task); the capability
  registry, Run.capabilities, ClaimLock.describe and Jira Rank/order are gone.
- The fake tracker moves into src/conformance as the adapter kit and passes
  the tier-aware conformance suite in both tiers; domain-model.md gains a
  "Write an adapter" section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@JarenKempton JarenKempton changed the title task/JWB-945 JWB-945: Tracker port v2 — registry and vendor-neutral adapter contract Nov 13, 2026
@JarenKempton
JarenKempton merged commit e78e2bb into main Nov 13, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant