feat(work-items): Jira adapter for the work-item-tracker seam

[kyle-sexton]

Motivation

First identified work-readiness gap for a day-job environment: GitHub is the git host, but Jira (multiple projects) is the ticketing system. The work-item-tracker seam currently has GitHub-shaped defaults; skills that read/reference work items need a Jira implementation behind the same seam.

Shape

• Interface/implementation split at the existing work-item-tracker seam; GitHub remains the shipped default.
• Jira adapter as an additional implementation, selected via setup/user config.
• Setup action should discover/ask for Jira binding (site, project keys, auth) rather than hardcoding.
• Commit/branch key linkage: environment uses SW2-12345: message commit convention — adapter should support Jira-key extraction/linkage where skills consume ticket references.

Constraint (hard)

Read/consume-only by default: no automated Jira ticket creation. Backlog intake is human-gated in the target environment. Any write capability must be opt-in and explicit.

Acceptance sketch

• Plugin installs user-globally on a work machine, setup binds Jira, work-item-consuming skills resolve SW2-* keys without plugin-source edits.

[kyle-sexton]

This was generated by AI during triage.

Triage T2 → draft plan below; routed needs-human priority: high wayfind: design. Adapter mechanism is execution-ready behind the existing seam, but 7 design decisions remain (decision #7 is load-bearing: the issue's own acceptance sketch is not satisfiable without a human scoping call), so not auto-status: ready.

---

Plan

A Jira adapter is a new adapters/jira/ sibling to adapters/github/ behind the existing seam. Core dispatcher, CONTRACT.md, lib/, and the ID grammar need no change — the adapter is pure add-on plus binding/config additions. GitHub stays the shipped default.

ID mapping (the linchpin — no shared-code change)

The native Jira key SW2-12345 maps to the seam's qualified ID grammar (lib/id.sh WIT_ID_REGEX) as:

jira:<site>/<PROJECTKEY>#<number>     e.g. jira:company.atlassian.net/SW2#12345  ⇄  SW2-12345

provider=jira, owner=<site host> (dots allowed, no slash — a Cloud host fits the owner group), repo=<project key>, number=<issue number>. The adapter reconstructs the native key PROJECTKEY-number from repo+number and parses it back the same way. id.sh is untouched.

Verb table (adapter surface = core public set minus list-frontier plus list-items)

Verb	R/W	Default capability	Note
get-item	read	true	GET issue; normalize to the item object.
list-items	read	true	JQL query scoped to binding-declared project(s); paginate to limits.list_items_max. Feeds core list-frontier.
capabilities	read	true	Cats capabilities.json (as GitHub adapter does).
create-item	write	false	Consume-only default → dispatcher exits 6.
claim	write	false	Assignee + lease write → 6. Blocks /work-items:work and track start on Jira until writes opt in.
renew-lease	write	false	6.
reclaim	write	false	6.
link-blocks	write	false	Would write a Jira issue-link → 6.
add-sub-item	write	false	Would write parent/epic link → 6.

Consume-only enforcement is contract-native, not a new mechanism. The dispatcher gates every verb on capabilities.json .verbs[$v] // false and exits 6 before invoking any script (verified: capabilities.sh merely cats the JSON; the gate reads the JSON directly). Shipping writes as false is exactly the pattern local-markdown uses for reclaim: false — no write script need even exist in the default ship. This satisfies the HARD CONSTRAINT with zero automated Jira ticket creation possible.

Read-path normalization (in the adapter, mirroring common.sh's WIT_ITEM_JQ)

• state: Jira statusCategory → Done maps to closed, everything else open (exact cut is a human decision).
• assignees: Jira single assignee → one-element assignees[].
• labels: Jira labels[] verbatim; canonical role labels ride as ordinary Jira labels — list-frontier --autonomous filters them core-side unchanged.
• blocked_by_count: count open inward is blocked by issue links (parallel to GitHub counting only open blockers).
• type: Jira issue type name → normalized type.
• parent_id: Jira parent/epic → qualified jira:site/PROJ#N or null.

Binding / config additions

Jira has no gh repo view equivalent to derive scope at runtime, so site + project keys are required binding config (invalid → exit 3, paralleling local-markdown's required storage_dir).

{
  "schema_version": "1.0",
  "provider": "jira",
  "config": {
    "lease_ttl_hours": 24,
    "jira": {
      "site": "company.atlassian.net",
      "project_keys": ["SW2", "ABC"],
      "auth_env": "JIRA_API_TOKEN",
      "auth_email": "ci@company.com"
    }
  }
}

• Secrets stay out of the binding — token referenced by env-var name only; the real secret lives in the env / secret-store per setup's existing rule. (Storage mechanism flagged, not designed.)
• list-items/list-frontier build JQL scope from project_keys; --repo <site>/<PROJ> narrows to one project.

Setup-skill discovery flow (extends skills/setup/SKILL.md "Provider binding")

Add jira as a selectable provider. Setup interviews for (never hardcodes): site host, project key(s), auth env-var name + email, and probes that the token resolves in-env at bind time (never stores it). Writes only non-secret config. Surfaces the consume-only default plainly. Setup authors no adapter (per its existing "does NOT" list).

SW2-* key extraction / linkage — split into two paths

1. Read/resolve path (satisfiable without skill edits). Skills already delegate ID construction to the adapter ("adapter: Resolve item ID" in track start). A Jira adapter operations README supplying SW2-12345 → jira:site/PROJ#12345 resolution lets skills resolve SW2-* references through the seam with no plugin-source edits.
2. Branch / PR / commit linkage (NOT satisfiable without plugin-source edits). skills/track/actions/start.md hardcodes a numeric branch regex ^[a-z]+/(routine-issue-)?([0-9]+)- and suggests <type>/<N>-<slug> — both drop the project key and fail to match feat/SW2-12345-slug. The Closes #N injection is owned by a separate plugin (/pull-request). Full linkage requires edits spanning two plugins' source — which the acceptance sketch forbids.

Conformance

Add conformance/bindings/jira.sh targeting a throwaway sandbox site (on-demand). The abstract suite already asserts capability-gated skips — write verbs assert exit 6 for free.

Acceptance criteria (behavioral)

• With a Jira binding, get-item jira:<site>/SW2#12345 returns a normalized item object (normalized state, assignees, labels, open-only blocked_by_count, type, parent_id, url), CR-free.
• list-frontier (and --autonomous) returns open, unassigned, unblocked items scoped to configured project keys, needs-human excluded under --autonomous.
• Every write verb exits 6 under the default binding — no code path creates, claims, or mutates a Jira ticket by default. Consequently /work-items:work and track start cannot operate on a Jira repo until writes are explicitly enabled — accepted gap.
• A binding missing jira.site or jira.project_keys exits 3.
• No secret literal in the binding; adapter reads the token from the named env var, exits 4 when absent/invalid.
• Binding Jira via setup requires no plugin-source edits for the read/resolve path; a SW2-12345 reference resolves and get-item returns it.
• Selecting github behaves exactly as today.
• Conformance runs green against the sandbox binding, writes asserted as exit-6 skips.

Human decisions required

1. Opt-in-write mechanism — (a) consumer-local adapter shadow (contract-native, full-adapter drift); (b) binding flag config.jira.allow_writes + runtime refusal (no drift, stretches exit-6 semantics); (c) seam change letting config override manifest bits (cleanest, broadest blast radius).
2. Auth model + secret storage — Basic (email + token) vs OAuth 2.0; which env var / secret-store (flagged only).
3. REST API surface — Cloud REST v3 vs v2, Cloud vs Data Center/Server.
4. status → open/closed cut — confirm statusCategory == Done → closed vs explicit allow-list.
5. Project-key ↔ repo mapping — confirm project_keys[] as scope source and default JQL when --repo omitted.
6. Blocker/sub-item link-type semantics — which Jira link type is authoritative (needed even for the read path).
7. Acceptance reconciliation (the hard one) — full SW2-* branch/PR linkage needs cross-plugin source edits the acceptance forbids. Human must scope this issue to the read/resolve path only (and file linkage separately) or relax the "no plugin-source edits" acceptance.

Confidence: NEEDS-HUMAN

Decisions 1–6 are parameter picks that unblock autonomous execution once chosen; decision 7 is different in kind — full SW2-* branch/PR linkage requires cross-plugin source edits the issue's own acceptance forbids, so the acceptance as written is not satisfiable without a human scoping call.

[kyle-sexton]

Maintainer decision on the T2 plan's sub-decisions (2026-07-19, batch-approved; relayed by planning session).

• docs(playbook): document the local plugin development loop #7 (load-bearing): scope this issue to the READ/RESOLVE path only. Branch/PR SW2-* linkage is filed as a sequenced follow-up after the adapter lands — not abandoned, and the "no plugin-source edits" acceptance stays intact for this issue.
• chore: initialize marketplace scaffold #1 (opt-in writes): defers — consume-only default; write verbs exit-6. Posture key per source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 when writes are later considered.
• fix: correct plugin-system inaccuracies and harden references #2 (auth): tentatively Basic email + API token — UNVERIFIED against the target Jira; confirm edition (Cloud vs Data Center) during the 2026-07-21 work-laptop pass before implementation hard-codes anything. That check also settles feat: markdown-formatter plugin (pilot migration) #3 (REST v3 vs v2).
• perf(markdown-formatter): unwired producer builds telemetry payload before the opt-in guard (~90ms/edit on Windows) #6 (blocker/sub-item link type): discover from the target Jira's actual conventions on the same laptop pass.
• ci: onboard to the CI platform (ci-workflows + standards) #4, feat(hook-telemetry): marketplace-wide telemetry contract + markdown-formatter producer #5: defaults confirmed (statusCategory == Done → closed; project_keys[] scope + default JQL).

Adapter work that doesn't depend on #2/#3/#6 facts may proceed now via normal flow.

[kyle-sexton]

This was generated by AI during triage. · Category: Feature · Priority: priority: high (week north-star: first-identified work-readiness gap for the day-job environment — GitHub host + Jira ticketing). Routed needs-human + wayfind: design.

Triage

Genuine open design (a new backend adapter behind the tracker seam, plus auth/binding and key-linkage design), so needs-human. Framing below to make the design pass concrete.

Dependencies (must precede or co-design)

• Agnosticism prerequisite: a Jira adapter is only reachable if the seam is actually provider-neutral at every consumer. Today planning:wayfind/plan bypass the seam and hardcode gh — planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 (routed status: ready) and planning: plan close-out and tracker-write phases emit gh-hardcoded tracker writes; close-out hardcodes docs/adr + docs/specs #418 must land first, or wayfind/plan remain GitHub-only regardless of a Jira adapter existing. Any skill that hardcodes gh is a hole this feature leaks through.
• Consume-only default: this issue's hard constraint ("read/consume-only by default; no automated Jira ticket creation; writes opt-in + explicit") is the SAME posture decision carried by source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440. The adapter's default should fall out of source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440's write_mode contract, not invent its own.

Design questions for the human

1. Adapter contract fit: the work-item-tracker seam CONTRACT defines coordination verbs (get-item, list-frontier, create-item, claim/lease, link-blocks, sub-items). Which map cleanly to Jira (issues, JQL search, transitions, links, sub-tasks) and which have no clean Jira equivalent (lease/claim semantics, blocked-by edges vs Jira link types)? The claim/lease protocol especially needs a Jira-native realization or an explicit "unsupported → degrade" story.
2. Auth + binding: site URL, multiple project keys, auth (API token / OAuth). Setup action discovers/asks rather than hardcoding. Secret storage follows the repo's secret-binding convention.
3. Key linkage: the SW2-12345: message commit convention → Jira-key extraction where skills consume ticket references. Define the extraction/linkage contract (which skills consume keys, how branch/commit keys resolve to items).
4. Consume-only realization: with writes disabled by default (source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440), confirm every read-path skill (the north-star set) resolves SW2-* keys through the adapter without any write.

Recommended human path

Settle #440 (write posture) → land #416/#418 (agnosticism) → then /planning:design the Jira adapter against the seam CONTRACT, with the claim/lease and link-type mapping as the sharpest design risks. GitHub stays the shipped default; Jira is an additional selectable implementation.