{
  "meta": {
    "agent": "planner",
    "task_id": "541",
    "title": "BJ-1: AtlassianOAuthAuthProvider abstract base",
    "created_at": "2026-04-23T00:00:00Z"
  },
  "inputs": [
    {
      "name": "issue",
      "type": "link",
      "ref": "https://github.com/AgentSDE/agent-core/issues/541",
      "notes": "BJ-1 — abstract OAuth provider"
    },
    {
      "name": "epic",
      "type": "link",
      "ref": "https://github.com/AgentSDE/agent-core/issues/539",
      "notes": "Atlassian integration EPIC"
    },
    {
      "name": "dependency",
      "type": "link",
      "ref": "https://github.com/AgentSDE/agent-core/issues/540",
      "notes": "BJ-0 — PlatformAuthProvider interface (merged on rc/atlassian-integration)"
    },
    {
      "name": "interface",
      "type": "file",
      "ref": "src/platform/platform-auth-provider.interface.ts",
      "notes": "interface to implement (on rc/atlassian-integration)"
    },
    {
      "name": "pattern-source",
      "type": "file",
      "ref": "src/github/github-app-auth.provider.ts",
      "notes": "concurrency guard pattern (refreshPromise)"
    }
  ],
  "outputs": [
    {
      "name": "abstract-provider",
      "type": "spec",
      "format": "md",
      "content": "Abstract class AtlassianOAuthAuthProvider implementing PlatformAuthProvider via OAuth 2.0 rotating refresh-token flow."
    }
  ],
  "files": [
    {
      "path": "src/atlassian/atlassian-oauth-auth.provider.ts",
      "action": "create",
      "reason": "abstract class + refresh flow"
    },
    {
      "path": "src/atlassian/atlassian-oauth-state.repo.ts",
      "action": "create",
      "reason": "state repo interface + injection token (stub until BJ-5)"
    },
    {
      "path": "src/atlassian/index.ts",
      "action": "create",
      "reason": "barrel export"
    },
    {
      "path": "src/atlassian/atlassian-oauth-auth.provider.spec.ts",
      "action": "create",
      "reason": "unit tests via concrete test subclass"
    },
    {
      "path": "src/platform/platform-auth-provider.interface.ts",
      "action": "inspect",
      "reason": "target interface"
    },
    {
      "path": "src/github/github-app-auth.provider.ts",
      "action": "inspect",
      "reason": "copy refreshPromise concurrency guard"
    }
  ],
  "steps": [
    {
      "id": "S1",
      "summary": "Create AtlassianOAuthStateRepo interface + injection token",
      "acceptance": [
        "src/atlassian/atlassian-oauth-state.repo.ts defines AtlassianOAuthStateRepo with loadRefreshToken/saveRefreshToken",
        "Exports ATLASSIAN_OAUTH_STATE_REPO injection token"
      ],
      "depends_on": []
    },
    {
      "id": "S2",
      "summary": "Implement abstract AtlassianOAuthAuthProvider class (constructor + getToken + refresh + abstract getBotUsername)",
      "acceptance": [
        "Implements PlatformAuthProvider (tsc passes under strict)",
        "Returns cached access token when > 5 min from expiry",
        "Preemptively refreshes within 5-min buffer via POST tokenEndpoint with grant_type=refresh_token",
        "Concurrent getToken() calls share a single refreshPromise (pattern from github-app-auth.provider.ts)",
        "Rotated refresh_token persisted via stateRepo.saveRefreshToken before returning access token",
        "Endpoint failure rethrows without mutating cachedToken/tokenExpiresAt",
        "HTTP client and state repo are injectable (fetchFn parameter defaults to global fetch)",
        "Docstring describes refresh-token rotation invariant",
        "getBotUsername is abstract"
      ],
      "depends_on": [
        "S1"
      ]
    },
    {
      "id": "S3",
      "summary": "Add src/atlassian/index.ts barrel export",
      "acceptance": [
        "Re-exports AtlassianOAuthAuthProvider, AtlassianOAuthStateRepo, ATLASSIAN_OAUTH_STATE_REPO"
      ],
      "depends_on": [
        "S1",
        "S2"
      ]
    },
    {
      "id": "S4",
      "summary": "Add unit tests via a concrete test subclass",
      "acceptance": [
        "Covers cached-token reuse, preemptive refresh within 5-min buffer, concurrent getToken coalescing, rotated-token persistence, endpoint-failure error propagation",
        "Uses injected fetchFn + mocked AtlassianOAuthStateRepo (no real network)",
        "npm run test -- atlassian-oauth-auth passes",
        "npm run lint zero warnings"
      ],
      "depends_on": [
        "S2"
      ]
    }
  ],
  "risks": [
    {
      "risk": "AtlassianOAuthStateRepo impl not landed until BJ-5",
      "mitigation": "Ship interface + token only; subclasses cannot instantiate until real repo provider is registered"
    },
    {
      "risk": "Atlassian rotates refresh_token on every refresh — losing rotation = permanent re-auth",
      "mitigation": "Persist rotated refresh_token before returning access token; tests assert order"
    }
  ],
  "assumptions": [
    "Target base branch is rc/atlassian-integration (contains BJ-0)",
    "Token endpoint uses standard OAuth 2.0 form-encoded refresh-token grant returning { access_token, expires_in, refresh_token }"
  ],
  "open_questions": []
}