Jira integration

Module: packages/core/src/jira/ Tools: apps/mcp/src/tools/jira/ Migration: 0012_jira_integration.sql

Two strict modes

Mirror (drobek → Jira, one-way). State changes push a transition +

comment to the linked Jira issue. Drobek never reads Jira state back — Jira is a reporting surface, not a second write path.

Pull-as-template. import_jira_epic({ epicKey }) snapshots a Jira

epic tree into a proposed drobek plan. Future Jira edits do NOT propagate (same pattern as task-22 template instantiation).

The single write path invariant is preserved: drobek owns state, Jira gets told.

Schema additions

tasks.external_jira_issue text — Jira issue key (PROJ-1234).
plans.external_jira_epic text — Jira epic key.
jira_state_mappings — per-installation table mapping drobek_state →

jira_transition_id (Atlassian custom workflows are configurable, so this is customer-edited in Settings, not hard-coded).

jira_sync_events — audit row per mirror call (transition / comment /

create / delete_warn) with success + error columns.

MCP tools

Tool	Scope	Purpose
`import_jira_epic`	`plans:write`	snapshot Jira epic → proposed plan
`link_jira_issue`	`tasks:write`	attach existing issue to a task
`unlink_jira_issue`	`tasks:write`	detach

import_jira_epic wires Jira is blocked by links as drobek dependencies. External blockers (issues outside the imported set) are dropped from the DAG and surfaced via the audit row as orphan refs — they can be re-imported or linked manually later.

Mirror helpers (pure)

mapDrobekStateToJira(state, mappings) — returns the configured jira_transition_id or null. Caller skips the mirror call on null (silent — "not configured" is normal, not an error).

formatMirrorComment({ taskId, fromState, toState, actor, at }) — terse single-line body that the runtime worker posts to the Jira issue.

What's NOT here (and never will be)

Bidirectional sync. Jira can't change drobek state. By design.
Sprint/board/story-point primitives. Drobek doesn't model agile cadence.
mTLS client cert auth for Server/DC. Customer must use PAT through a

reverse proxy; PEM CA cert for server verification is sufficient.

Comment sync by default. Task-29a typed comments stay in drobek; they

would clutter Jira. Customers can opt in per-org via Settings (task 36).

Runtime adapter

The actual Atlassian REST client (Cloud OAuth 3LO or Server/DC PAT, with custom-CA https.Agent for self-hosted) is constructed by the verification worker (task 32 neighbourhood). The MCP tool uses a deterministic stub client when no real client has been injected, so the surface is testable in a fresh dev environment.