{
  "meta": {
    "agent": "planner",
    "task_id": "547",
    "title": "BJ-7: JiraAdapter + webhook route",
    "created_at": "2026-04-23T17:11:32Z"
  },
  "inputs": [
    {
      "name": "issue",
      "type": "link",
      "ref": "https://github.com/AgentSDE/agent-core/issues/547",
      "notes": "Wave 2 of Atlassian integration epic #539; depends on #540"
    },
    {
      "name": "platform-adapter-interface",
      "type": "file",
      "ref": "src/webhook/adapters/platform-adapter.interface.ts",
      "notes": "PlatformAdapter contract to implement"
    },
    {
      "name": "github-adapter-reference",
      "type": "file",
      "ref": "src/webhook/adapters/github.adapter.ts",
      "notes": "Reference implementation; HMAC block at lines 30-45 to be extracted"
    },
    {
      "name": "dispatch-event-dto",
      "type": "file",
      "ref": "src/webhook/dto/dispatch-event.dto.ts",
      "notes": "DispatchEventType union to extend with issue_updated + link_created"
    }
  ],
  "outputs": [
    {
      "name": "JiraAdapter",
      "type": "spec",
      "format": "md",
      "content": "New adapter with platform='jira', HMAC-SHA256 via shared helper, 5-event normalize switch"
    },
    {
      "name": "webhook-route",
      "type": "spec",
      "format": "md",
      "content": "POST /webhooks/jira mirrors handleGitHub: verify signature, persist delivery, resolve tenant, dispatch"
    }
  ],
  "files": [
    {
      "path": "src/webhook/crypto.ts",
      "action": "create",
      "reason": "Shared HMAC-SHA256 verification helper"
    },
    {
      "path": "src/webhook/adapters/github.adapter.ts",
      "action": "modify",
      "reason": "Delegate verifySignature to shared helper"
    },
    {
      "path": "src/webhook/adapters/github.adapter.spec.ts",
      "action": "modify",
      "reason": "Preserve existing coverage after refactor"
    },
    {
      "path": "src/webhook/adapters/jira.adapter.ts",
      "action": "create",
      "reason": "Implements PlatformAdapter for Jira"
    },
    {
      "path": "src/webhook/adapters/jira.adapter.spec.ts",
      "action": "create",
      "reason": "Unit tests for signature + 5 event types + unknown-event ignore"
    },
    {
      "path": "src/webhook/webhook.controller.ts",
      "action": "modify",
      "reason": "Add POST /webhooks/jira handler"
    },
    {
      "path": "src/webhook/webhook.controller.spec.ts",
      "action": "modify",
      "reason": "Coverage for jira route"
    },
    {
      "path": "src/webhook/webhook.module.ts",
      "action": "modify",
      "reason": "Register JiraAdapter in onModuleInit"
    },
    {
      "path": "src/webhook/dto/dispatch-event.dto.ts",
      "action": "modify",
      "reason": "Add issue_updated, link_created event types; add 'jira' to platform union"
    },
    {
      "path": "src/config/config.schema.ts",
      "action": "modify",
      "reason": "Add optional JIRA_WEBHOOK_SECRET"
    },
    {
      "path": ".env.example",
      "action": "modify",
      "reason": "Document JIRA_WEBHOOK_SECRET"
    },
    {
      "path": "CLAUDE.md",
      "action": "modify",
      "reason": "Env-var table update for JIRA_WEBHOOK_SECRET"
    }
  ],
  "steps": [
    {
      "id": "S1",
      "summary": "Extract verifyHmacSha256 to src/webhook/crypto.ts and refactor GitHubAdapter to use it",
      "acceptance": [
        "crypto.ts exports verifyHmacSha256(rawBody, header, secret, prefix) that throws UnauthorizedException on missing/invalid signature",
        "GitHubAdapter.verifySignature delegates to the helper with prefix 'sha256='",
        "Existing github.adapter.spec.ts suites pass unchanged"
      ],
      "depends_on": []
    },
    {
      "id": "S2",
      "summary": "Extend DispatchEventType + platform union; add JIRA_WEBHOOK_SECRET to config schema, .env.example, CLAUDE.md",
      "acceptance": [
        "DispatchEventType includes 'issue_updated' and 'link_created'",
        "'jira' is a member of the platform union in dispatch-event.dto.ts",
        "JIRA_WEBHOOK_SECRET is optional in config.schema.ts and documented in .env.example + CLAUDE.md env table",
        "npm run build passes"
      ],
      "depends_on": []
    },
    {
      "id": "S3",
      "summary": "Implement JiraAdapter with HMAC verify (header x-hub-signature) and 5-event normalize",
      "acceptance": [
        "JiraAdapter implements PlatformAdapter with platform='jira'",
        "verifySignature uses the shared helper and JIRA_WEBHOOK_SECRET",
        "normalize maps jira:issue_created → intake, jira:issue_updated → issue_updated (inspects changelog for label transitions), jira:issue_deleted → task_cancelled, comment_created|comment_updated → issue_comment, jira:issuelink_created → link_created",
        "Unknown webhookEvent returns { event: null, reason } — does not throw",
        "jira.adapter.spec.ts covers all 5 events + bad/missing signature + unknown event"
      ],
      "depends_on": [
        "S1",
        "S2"
      ]
    },
    {
      "id": "S4",
      "summary": "Add POST /webhooks/jira route + JiraAdapter registration + controller tests",
      "acceptance": [
        "POST /webhooks/jira returns 401 on bad/missing x-hub-signature",
        "Valid payload returns 200 and dispatches via DispatchService",
        "WebhookDeliveryEntity persisted with source='jira'",
        "JiraAdapter registered alongside GitHubAdapter in WebhookModule.onModuleInit()",
        "webhook.controller.spec.ts covers the jira route scenarios",
        "npm run test and npm run lint pass with zero warnings"
      ],
      "depends_on": [
        "S3"
      ]
    }
  ],
  "risks": [
    {
      "risk": "#540 (BJ-0) not merged; platform-union edits may collide on rebase",
      "mitigation": "Include the 'jira' union addition here; drop on rebase if #540 lands first"
    },
    {
      "risk": "TenantResolverService may not support 'jira' source yet",
      "mitigation": "Use configured org as fallback tenant; open follow-up if resolver needs Jira branch"
    },
    {
      "risk": "E2E webhook suite may not exercise the new route",
      "mitigation": "Unit + controller spec coverage is sufficient for this PR; E2E handled by later BJ- stories"
    }
  ],
  "assumptions": [
    "Jira sends signature in header 'x-hub-signature' using prefix 'sha256=' (WebSub standard)",
    "Raw body is available via req.rawBody, same as GitHub handler",
    "jira:issue_updated without a changelog field should still emit an issue_updated dispatch (graceful)",
    "Unknown webhookEvent should return 200 with ignored status (no throw)"
  ],
  "open_questions": [
    "Does TenantResolverService.resolveFromWebhook already accept 'jira' as platform?",
    "Is 'link_created' DispatchEventType consumed by any downstream phase in this PR, or is downstream routing a later BJ- story?"
  ]
}