fix(jira): pin coding/new-task-v1 workflow_ref in webhook processor (#547)

A label-triggered Jira task submitted no workflow_ref, so createTaskCore
resolved it down the ladder to the platform default default/agent-v1 —
an artifact-delivery workflow whose prompt forbids branching and PRs.
The agent completed 'successfully' without committing, and the Jira
issue got '✅ finished. No pull request was opened.'

Pin workflow_ref: 'coding/new-task-v1' at the submission site: a
Jira-triggered task always targets a mapped repo, so the coding
workflow's requiresRepo/requiredInputs contract is always satisfiable.

Assert the pinned ref in the processor happy-path test and document the
workflow in JIRA_SETUP_GUIDE.md (+ Starlight mirror).

Fixes #546

Co-authored-by: Claude <noreply@anthropic.com>

Author: ayushtr-aws

cdk/src/handlers/jira-webhook-processor.ts

@@ -367,6 +367,10 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     {
       repo,
       task_description: taskDescription,
+      // Explicit coding workflow: a label-triggered Jira task always targets a
+      // mapped repo, so it must not fall through the resolution ladder to the
+      // repo-less default/agent-v1 (which never commits or opens a PR). #546
+      workflow_ref: 'coding/new-task-v1',
       ...(attachments.length > 0 && { attachments }),
     },
     {

cdk/test/handlers/jira-webhook-processor.test.ts

@@ -297,6 +297,9 @@ describe('jira-webhook-processor handler', () => {
     expect(reqBody.repo).toBe('org/repo');
     expect(reqBody.task_description).toContain('ENG-42: Fix the login bug');
     expect(reqBody.task_description).toContain('Users cannot log in.');
+    // Must pin the coding workflow — an absent workflow_ref falls through the
+    // resolution ladder to default/agent-v1, which never opens a PR (#546).
+    expect(reqBody.workflow_ref).toBe('coding/new-task-v1');
     expect(ctx.userId).toBe('cognito-user-1');
     expect(ctx.channelSource).toBe('jira');
     expect(ctx.channelMetadata).toMatchObject({

docs/guides/JIRA_SETUP_GUIDE.md

@@ -13,7 +13,7 @@ Set up the ABCA Jira Cloud integration so that adding a label to a Jira issue tr
 
 ## How it works
 
-A Jira-site admin creates an Atlassian OAuth 2.0 (3LO) app and authorizes it on the site. The OAuth token bundle is stored in a per-tenant Secrets Manager secret (`bgagent-jira-oauth-<cloudId>`). When a user adds the trigger label to a Jira issue, Jira fires a webhook to ABCA; the receiver verifies the `X-Hub-Signature` HMAC, dedupes, and async-invokes the processor, which resolves the tenant, looks up the project→repo mapping, and creates a task. The agent clones the repo, opens a PR, and comments on the Jira issue via the Jira REST v3 API (using the same stored OAuth token).
+A Jira-site admin creates an Atlassian OAuth 2.0 (3LO) app and authorizes it on the site. The OAuth token bundle is stored in a per-tenant Secrets Manager secret (`bgagent-jira-oauth-<cloudId>`). When a user adds the trigger label to a Jira issue, Jira fires a webhook to ABCA; the receiver verifies the `X-Hub-Signature` HMAC, dedupes, and async-invokes the processor, which resolves the tenant, looks up the project→repo mapping, and creates a task. Jira-triggered tasks always run the `coding/new-task-v1` workflow (the processor pins `workflow_ref` explicitly, since a label-triggered task always targets a mapped repo). The agent clones the repo, opens a PR, and comments on the Jira issue via the Jira REST v3 API (using the same stored OAuth token).
 
 **Tenant key.** Everything is indexed on `cloudId` — the Atlassian tenant UUID, *not* the site domain or name. Webhook payloads and the OAuth flow both surface `cloudId`; it is the join key across the project-mapping, user-mapping, and workspace-registry tables.
 

docs/src/content/docs/using/Jira-setup-guide.md

@@ -17,7 +17,7 @@ Set up the ABCA Jira Cloud integration so that adding a label to a Jira issue tr
 
 ## How it works
 
-A Jira-site admin creates an Atlassian OAuth 2.0 (3LO) app and authorizes it on the site. The OAuth token bundle is stored in a per-tenant Secrets Manager secret (`bgagent-jira-oauth-<cloudId>`). When a user adds the trigger label to a Jira issue, Jira fires a webhook to ABCA; the receiver verifies the `X-Hub-Signature` HMAC, dedupes, and async-invokes the processor, which resolves the tenant, looks up the project→repo mapping, and creates a task. The agent clones the repo, opens a PR, and comments on the Jira issue via the Jira REST v3 API (using the same stored OAuth token).
+A Jira-site admin creates an Atlassian OAuth 2.0 (3LO) app and authorizes it on the site. The OAuth token bundle is stored in a per-tenant Secrets Manager secret (`bgagent-jira-oauth-<cloudId>`). When a user adds the trigger label to a Jira issue, Jira fires a webhook to ABCA; the receiver verifies the `X-Hub-Signature` HMAC, dedupes, and async-invokes the processor, which resolves the tenant, looks up the project→repo mapping, and creates a task. Jira-triggered tasks always run the `coding/new-task-v1` workflow (the processor pins `workflow_ref` explicitly, since a label-triggered task always targets a mapped repo). The agent clones the repo, opens a PR, and comments on the Jira issue via the Jira REST v3 API (using the same stored OAuth token).
 
 **Tenant key.** Everything is indexed on `cloudId` — the Atlassian tenant UUID, *not* the site domain or name. Webhook payloads and the OAuth flow both surface `cloudId`; it is the join key across the project-mapping, user-mapping, and workspace-registry tables.