feat(atlassian): add the Atlassian connector — Jira verify + Confluence publish [roadmap:atlassian]

[tcballard]

Summary

Implements rac/roadmaps/atlassian-connector.md (epic #4; sub-issues #5–#9).

Adds:

• rac-connect atlassian verify — read-only Jira related_tickets existence/state checks over rac export --graph, exit 3 on findings (the CI gate)
• rac-connect atlassian publish — idempotent managed Confluence pages over rac export --documents, keyed by a content property, never the title
• The TicketVerifier/PagePublisher seams, VerifySummary, the [atlassian] extra (an internal httpx client, no Atlassian SDK), the additive GraphEdge.external/provider contract fields, 30 offline tests, the docs page with the release-gating smoke checklist, ADR-010/ADR-011, and the design + roadmap artifacts

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/atlassian-connector.md (this repo, delivery track)
• rac/roadmaps/atlassian/atlassian.md (rac-core, suite intent — companion PR docs(roadmap): add the atlassian suite roadmap [roadmap:atlassian] core#249)

Relevant ADRs:

• rac/decisions/adr-010-atlassian-verify-publish-seams.md (new)
• rac/decisions/adr-011-confluence-page-identity-and-idempotency.md (new)
• rac/decisions/adr-002-connector-interface.md, adr-003-graph-connector-seam-neo4j.md (the sibling-seam precedent)
• rac-core ADR-087 (delegates ticket state checks here), ADR-090 (suite placement), ADR-065 (untrusted corpus content, propose-only write-back), ADR-086 (air-gap)

Scope

Included

• Verify: edge selection strictly by contract markers (external + provider == "jira"); key extraction from bare references and /browse/ URLs; dedupe with multi-artifact attribution; 100-key bulkfetch batches with fields=["status"]; exists/missing/forbidden classification incl. statusCategory; credential-free --dry-run
• Publish: page identity via the lore.artifact_id content property + lore-managed label; sha256 body-hash skip (second publish over an unchanged corpus performs zero writes); version-checked updates, 409 surfaced as a skip and never forced; deterministic escape-first Markdown-to-storage rendering (hostile HTML/macros stay inert, CDATA break-out blocked, only http/https/mailto links become anchors)
• Client: Basic auth from ATLASSIAN_BASE_URL/ATLASSIAN_EMAIL/ATLASSIAN_API_TOKEN; capped jittered backoff honouring Retry-After on 429/5xx; 401/403 fail fast without retry
• CI now installs .[dev,atlassian] so the mock-transport wire tests run (they importorskip httpx, so a bare .[dev] install still passes)

Excluded

• Inbound Confluence ingest (rac-core ADR-017/065-gated; future roadmap item)
• Jira comment-mode; Data Center profile (Bearer PAT, v2 endpoints); OAuth 3LO
• Jira remote-link backlinks from publish (client support is wired and tested; the CLI flag is deferred)
• Table rendering (degrades to escaped text); --json verify output (exit code is the day-one machine contract)
• Release tag — gated on the docs page's live smoke test (atlassian: live smoke test + first release tag #10)

Product / Architecture Decisions

• Two sibling seams, not overloads (ADR-010): verify is read-shaped and returns a report, never records — the shape keeps the recall/re-rank surface ADR-002 rejects structurally impossible. This extends the seam family exactly the way ADR-003 did for graphs; ADR-002 is not reopened.
• No Atlassian SDK: ~6 endpoints; an internal httpx client is a smaller supply chain than a wrapper library and the wire behaviour (backoff, conflict handling) is the part worth testing. Jira Cloud's classic /search endpoint no longer exists — the client uses bulkfetch; search, if ever needed, is POST /search/jql.
• Page identity is a content property, never the title (ADR-011): title-keying orphans pages on rename; id write-back into the corpus would violate the propose-only trust boundary (rac-core ADR-065). The mapping lives in Confluence itself — no local state.
• Change detection hashes our rendered output, not the read-back body — Confluence normalizes stored XHTML, so read-and-compare flaps.
• Verify exits 3 on findings, distinct from 1 (malformed input) and 2 (missing credentials), so CI can gate on reference state without conflating it with operator error.
• Nested CLI verbs (rac-connect atlassian verify|publish): the suite grows verbs (comment-mode, ingest) and a flat atlassian-verify would fork the backend namespace.

User-Facing Contract

CLI

rac export rac/ --graph     | rac-connect atlassian verify [--dry-run] [-i FILE] [-v]
rac export rac/ --documents | rac-connect atlassian publish [--dry-run] [--strict] [--space KEY] [-i FILE] [-v]

Human Output

Per-reference lines (exists PROJ-1: Done (done) <- RAC-…, missing PROJ-404: … <- RAC-…) — findings always print, even without --verbose; summary line to stderr (atlassian verify: 2 checked, 1 exist, 1 missing, 0 forbidden, 2 skipped). Publish action lines: created page … / updated page … / skip …: unchanged / version conflict … not overwritten.

JSON Output

None added. The graph input contract now surfaces edges[].external and edges[].provider in the reader (additive, tolerant defaults; emitted by rac-core since v0.25.0).

Exit Codes

• 0: verify — all checked references exist; publish — done
• 1: malformed --graph payload / malformed JSONL line under --strict
• 2: credentials missing (each absent ATLASSIAN_* variable named); publish also: no space configured
• 3: verify only — one or more references missing or forbidden

Verification

Ran

• python -m pytest -q — 192 passed (was 162; +30: graph marker parsing, verify behaviour, publish behaviour, render goldens, client wire contract, CLI verbs)
• python -m ruff check src/ tests/ scripts/, ruff format --check, python -m mypy src/ — clean
• python scripts/sync_readme.py --check — in sync (8 connectors; new "Workspace & ticketing" group, no script change needed — the grouping is data-driven)
• rac validate rac/, rac relationships rac/ --validate — exit 0; rac review rac/ — 100/100, nothing needs attention
• End-to-end against this repo's own corpus: rac export rac/ --graph | rac-connect atlassian verify --dry-run — 7 github-provider tickets correctly skipped, exit 0; rac export rac/ --documents | rac-connect atlassian publish --dry-run — 15 pages planned, exit 0

Covered

• Verify: github-provider and verified_by (provider-null) edges skipped by construction; resolved in-corpus edges ignored; key dedupe with multi-artifact attribution; the 101-keys-to-2-batches boundary; permission-hinted per-key errors and whole-batch auth failures classified forbidden; unparseable targets skipped not checked; empty graph exits 0; dry-run makes zero client calls
• Publish: create path sets property + label; unchanged-hash second run performs zero writes; changed body updates version+1; 409 conflict recorded and the stream continues (and the stored hash does not advance past the human's edit)
• Render: byte-exact golden; determinism = stable hash; script tags, injected ac:structured-macro text, and CDATA ]]> break-outs stay inert; javascript: links stay text
• Client: Basic-auth header and bulkfetch body shape; Retry-After honoured with a capped 4-retry budget then surfaced; 401/403 fail fast with no retry; 409 raises VersionConflictError; every missing env var named
• CLI: 0/1/2/3 exit contract, contract-major mismatch warning, --strict, --input, missing-space error

Review Path

1. rac/decisions/adr-010…, adr-011…, rac/designs/atlassian-connector-shape.md — the contract
2. src/rac_connectors/graph.py, base.py — the additive contract/seam layer
3. src/rac_connectors/atlassian/client.py — auth, backoff, the six endpoints
4. jira.py, render.py, confluence.py, connector.py — the two verbs
5. cli.py — nested verb wiring and exit codes
6. Tests (fakes for behaviour, MockTransport for the wire, goldens for render), then docs/connectors/atlassian.md + README region + CHANGELOG

Notes For Reviewer

• render.py is the security-sensitive file: corpus content is untrusted input (rac-core ADR-065), and the escape-first discipline plus the CDATA and link-scheme guards are what keep a hostile artifact from smuggling markup into Confluence. The golden tests pin it.
• The verify auth-failure path deliberately reports whole-batch 401/403 as forbidden findings (exit 3) rather than exit 2 — exit 2 is reserved for missing configuration; a rejected credential is instance state worth surfacing per reference.
• Known limitation: a managed page manually stripped of its property/label becomes invisible and a fresh publish creates a sibling (recorded with mitigation in ADR-011; orphan adoption is a named follow-up).
• The live path is unproven until the smoke test (atlassian: live smoke test + first release tag #10) runs — the docs page carries the checklist and gates the first tag.

Implementation Process

Implemented with AI assistance under the roadmap contract; final scope, review, and acceptance decisions rest with the maintainer.