fix(workflows): repo-bound task without workflow_ref → coding/new-task-v1, not default/agent-v1 (#594)

* fix(workflows): repo-bound task w/o workflow_ref → coding/new-task-v1, not default/agent-v1

#296 (workflow-driven tasks) replaced the task_type→workflow mapping with a
resolution ladder, but left the repo-aware rung ('Phase 4') unwired. Every
task with no explicit workflow_ref — all Slack tasks and all #247
orchestration children (neither sets one) — fell through to the platform
default default/agent-v1: the freeform, repo-less agent prompt with NO
git/PR discipline. The agent then improvised (gh api / gh pr create against
an empty local clone), so ensure_pr found no commits and recorded
pr_url=null, screenshot→Linear routing lost its branch signal, and #247 A4
stacking broke (children couldn't fetch the unpushed predecessor branch).

Re-wire the missing rung minimally: resolveWorkflowRef takes hasRepo; an
absent ref with a repo present resolves to coding/new-task-v1 (the
disciplined coding workflow — edit locally, commit, push, platform opens
the PR via ensure_pr), matching pre-#296 behaviour. Repo-less tasks still
default to default/agent-v1. An explicit workflow_ref always wins. The
single create-task-core call site passes Boolean(body.repo), so both Slack
and orchestration (which create via createTaskCore with repo set) inherit
the fix. Upstream regression — worth an upstream issue too.

Updated workflows + create-task-core tests; the old test asserting
default/agent-v1 for a repo task encoded the regression.

(cherry picked from commit 99b5a17)
(cherry picked from commit 9d8b25d)

* refactor: pin coding workflow at channel call sites, not the resolver default

Rework per review (#594): follow the merged #547 precedent instead of changing
the shared resolver default. A repo-bound channel task must run the disciplined
coding workflow (clone → commit → push → platform opens the PR), not the
repo-less default/agent-v1 that records pr_url=null — but that "repo task ⇒
coding workflow" decision now lives explicitly at each channel's createTaskCore
call site rather than as an implicit resolver-level inference.

Addresses the review point-by-point:

- B3(a): revert resolveWorkflowRef to its single-arg form (no hasRepo); pin
  workflow_ref: CODING_WORKFLOW_ID in the Linear and Slack processors, mirroring
  the Jira processor (#546/#547). One visible decision per channel, uniform
  across all three. (No #247-child path exists on main.)
- B2: moot — no resolver behaviour change, so WORKFLOWS.md / API_CONTRACT.md /
  USER_GUIDE.md all stay accurate. No doc edits, no mirror regen needed.
- N1: moot — the hasRepo param is gone, so the "forgot hasRepo" footgun can't exist.
- N2: promote the 'coding/new-task-v1' literal to CODING_WORKFLOW_ID next to
  DEFAULT_WORKFLOW_ID, with a module-load invariant asserting both ids exist in
  DESCRIPTORS (a descriptor rename now fails at import, not as a runtime
  TypeError). Jira's literal switched to the constant too — uniform.
- N3: moot — the stale "last rung" JSDoc was in the reverted resolver block.
- §6 test gap: create-task-core caller tests now assert the real behaviour
  (omitted ref → default/agent-v1, with AND without a repo — the symmetric
  repo-less case that was missing). Channel processor tests (Linear/Slack/Jira)
  assert each pins workflow_ref: 'coding/new-task-v1'.

Full cdk build green (compile + jest + eslint + synth).

Author: isadeks

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

@@ -25,6 +25,7 @@ import { reportIssueFailure } from './shared/jira-feedback';
 import { resolveJiraOauthToken } from './shared/jira-oauth-resolver';
 import { logger } from './shared/logger';
 import type { Attachment } from './shared/types';
+import { CODING_WORKFLOW_ID } from './shared/workflows';
 
 const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
 
@@ -370,7 +371,7 @@ export async function handler(event: ProcessorEvent): Promise<void> {
       // 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',
+      workflow_ref: CODING_WORKFLOW_ID,
       ...(attachments.length > 0 && { attachments }),
     },
     {

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

@@ -25,6 +25,7 @@ import { reportIssueFailure } from './shared/linear-feedback';
 import { resolveLinearOauthToken } from './shared/linear-oauth-resolver';
 import { logger } from './shared/logger';
 import type { Attachment } from './shared/types';
+import { CODING_WORKFLOW_ID } from './shared/workflows';
 
 const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
 
@@ -300,6 +301,11 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     {
       repo,
       task_description: taskDescription,
+      // Explicit coding workflow: a label-triggered Linear 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). Mirrors
+      // the Jira processor (#546/#547). See CODING_WORKFLOW_ID.
+      workflow_ref: CODING_WORKFLOW_ID,
       ...(attachments.length > 0 && { attachments }),
     },
     {

cdk/src/handlers/shared/workflows.ts

@@ -148,6 +148,32 @@ const DESCRIPTORS: Record<string, WorkflowDescriptor> = {
 /** The platform default workflow — the last rung of the resolution ladder. */
 export const DEFAULT_WORKFLOW_ID = 'default/agent-v1';
 
+/**
+ * The disciplined coding workflow (clone → edit → commit → push → platform
+ * opens the PR via ``ensure_pr``). A repo-bound task with no explicit
+ * ``workflow_ref`` must run THIS, not the repo-less {@link DEFAULT_WORKFLOW_ID}
+ * (which improvises against an empty local clone and records ``pr_url=null``).
+ *
+ * The channel processors (Linear/Jira/Slack) and the #247 orchestration release
+ * path pin this explicitly at their ``createTaskCore`` call sites — see
+ * ``jira-webhook-processor.ts`` (#546/#547, the first instance) — rather than
+ * relying on a resolver-level default, so the "repo task ⇒ coding workflow"
+ * decision lives at one visible place per channel and stays uniform across them.
+ */
+export const CODING_WORKFLOW_ID = 'coding/new-task-v1';
+
+// Fail at MODULE LOAD (deploy/import time), not at request time, if either
+// well-known id ever drifts out of DESCRIPTORS — e.g. a descriptor rename.
+// Without this a rename surfaces as an obscure runtime
+// ``TypeError: Cannot read properties of undefined (reading 'id')`` inside the
+// Lambda on the first affected task; TypeScript's ``Record<string, …>`` index
+// type will not catch it (N2).
+for (const requiredId of [DEFAULT_WORKFLOW_ID, CODING_WORKFLOW_ID]) {
+  if (!DESCRIPTORS[requiredId]) {
+    throw new Error(`Workflow descriptor "${requiredId}" is missing from DESCRIPTORS`);
+  }
+}
+
 /** Pattern for a valid workflow ref: ``<domain>/<name>-vN[@<constraint>]``. */
 const WORKFLOW_REF_PATTERN = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*-v\d+(@[^\s]+)?$/;
 
@@ -186,7 +212,16 @@ export type WorkflowResolutionError = 'unknown_id' | 'unsatisfiable_version';
  * resolution ladder (WORKFLOWS.md §"Replacing task types"):
  *   1. explicit ``workflow_ref`` (id + optional ``@constraint``);
  *   2. (Blueprint default — Phase 4, not yet wired);
- *   3. the platform default ``default/agent-v1``.
+ *   3. the repo-less platform default ``default/agent-v1``.
+ *
+ * NOTE: an absent ref falls back to the repo-less default here regardless of
+ * whether the request carries a repo. A repo-bound channel task (Linear/Jira/
+ * Slack/#247) must NOT rely on this fallback — it pins an explicit
+ * ``workflow_ref: CODING_WORKFLOW_ID`` at its call site so a repo task runs the
+ * disciplined coding workflow (commit + push + PR), not the repo-less agent
+ * that records ``pr_url=null``. That decision lives at the call site, one per
+ * channel, mirroring ``jira-webhook-processor.ts`` (#546/#547) — see
+ * {@link CODING_WORKFLOW_ID}.
  *
  * Returns ``null`` when an explicit ref cannot be resolved — either the id is
  * unknown OR an ``@constraint`` pins a version the platform does not ship. The

cdk/src/handlers/slack-command-processor.ts

@@ -25,6 +25,7 @@ import { logger } from './shared/logger';
 import { slackFetch } from './shared/slack-api';
 import { getSlackSecret, SLACK_SECRET_PREFIX } from './shared/slack-verify';
 import type { Attachment } from './shared/types';
+import { CODING_WORKFLOW_ID } from './shared/workflows';
 import type { SlackCommandPayload } from './slack-commands';
 
 /**
@@ -243,6 +244,11 @@ async function handleSubmit(event: MentionEvent, args: string[], reply: ReplyFn)
       repo,
       issue_number: issueNumber,
       task_description: description,
+      // Explicit coding workflow: a Slack-submitted task targets a repo, so it
+      // must not fall through the resolution ladder to the repo-less
+      // default/agent-v1 (which never commits or opens a PR). Mirrors the Jira
+      // processor (#546/#547). See CODING_WORKFLOW_ID.
+      workflow_ref: CODING_WORKFLOW_ID,
       ...(attachments.length > 0 && { attachments }),
     },
     {

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

@@ -176,6 +176,10 @@ describe('linear-webhook-processor handler', () => {
     expect(reqBody.repo).toBe('org/repo');
     expect(reqBody.task_description).toContain('ABC-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. Mirrors
+    // the Jira processor (#546/#547).
+    expect(reqBody.workflow_ref).toBe('coding/new-task-v1');
     expect(ctx.userId).toBe('cognito-user-1');
     expect(ctx.channelSource).toBe('linear');
     expect(ctx.channelMetadata).toMatchObject({

cdk/test/handlers/shared/create-task-core.test.ts

@@ -589,15 +589,34 @@ describe('createTaskCore', () => {
     expect(result.statusCode).toBe(201);
   });
 
-  test('resolves the default workflow when workflow_ref is omitted', async () => {
+  test('resolves the platform default when workflow_ref is omitted (repo present)', async () => {
+    // createTaskCore does NOT infer the coding workflow from the mere presence
+    // of a repo — that "repo task ⇒ coding workflow" decision is pinned by each
+    // CHANNEL processor at its call site (Linear/Jira/Slack pass
+    // workflow_ref: CODING_WORKFLOW_ID; see those processors' tests). A raw
+    // createTaskCore call with no ref falls through the resolution ladder to the
+    // repo-less platform default, whether or not a repo is attached.
     const result = await createTaskCore(
       { repo: 'org/repo', task_description: 'Fix the bug' },
       makeContext(),
       'req-default',
     );
     expect(result.statusCode).toBe(201);
     const body = JSON.parse(result.body);
-    // No workflow_ref ⇒ the resolution ladder falls to the platform default.
+    expect(body.data.resolved_workflow).toEqual({ id: 'default/agent-v1', version: '1.0.0' });
+  });
+
+  test('resolves the platform default when workflow_ref is omitted AND no repo (symmetric)', async () => {
+    // §6 symmetric coverage: the repo-less path through the real caller. Guards
+    // against a future fallback-branch inversion that a repo-pinned test would
+    // miss (the repo-less default must stay default/agent-v1).
+    const result = await createTaskCore(
+      { task_description: 'Do some research' },
+      makeContext(),
+      'req-default-norepo',
+    );
+    expect(result.statusCode).toBe(201);
+    const body = JSON.parse(result.body);
     expect(body.data.resolved_workflow).toEqual({ id: 'default/agent-v1', version: '1.0.0' });
   });
 

cdk/test/handlers/shared/workflows.test.ts

@@ -21,6 +21,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import {
+  CODING_WORKFLOW_ID,
   DEFAULT_WORKFLOW_ID,
   WORKFLOW_MODEL_ALLOWLIST,
   disallowedWorkflowModel,
@@ -72,12 +73,21 @@ describe('resolveWorkflowRef', () => {
     expect(resolveWorkflowRefError(undefined)).toBeNull();
   });
 
-  test('falls back to the platform default when ref is absent', () => {
+  test('falls back to the repo-less platform default when ref is absent', () => {
     expect(resolveWorkflowRef(undefined)).toEqual({ id: DEFAULT_WORKFLOW_ID, version: '1.0.0' });
     expect(resolveWorkflowRef(null)).toEqual({ id: DEFAULT_WORKFLOW_ID, version: '1.0.0' });
     expect(resolveWorkflowRef('')).toEqual({ id: DEFAULT_WORKFLOW_ID, version: '1.0.0' });
   });
 
+  test('CODING_WORKFLOW_ID resolves to the disciplined coding workflow', () => {
+    // The channel processors pin this at the call site for a repo-bound task
+    // (the "repo task ⇒ coding workflow" decision lives per-channel, not in the
+    // resolver default). Assert the constant points at a real, repo-bound,
+    // non-read-only workflow so a descriptor rename can't silently mispoint it.
+    const resolved = resolveWorkflowRef(CODING_WORKFLOW_ID);
+    expect(resolved).toEqual({ id: 'coding/new-task-v1', version: '1.0.0' });
+  });
+
   test('returns null for an unknown but well-formed ref', () => {
     expect(resolveWorkflowRef('coding/does-not-exist-v1')).toBeNull();
   });

cdk/test/handlers/slack-command-processor.test.ts

@@ -170,6 +170,10 @@ describe('slack-command-processor handler', () => {
     expect(reqBody.repo).toBe('org/repo');
     expect(reqBody.issue_number).toBe(42);
     expect(reqBody.task_description).toBe('add validation');
+    // Must pin the coding workflow — an absent workflow_ref falls through the
+    // resolution ladder to default/agent-v1, which never opens a PR. Mirrors
+    // the Jira processor (#546/#547).
+    expect(reqBody.workflow_ref).toBe('coding/new-task-v1');
     expect(ctx.channelSource).toBe('slack');
     expect(ctx.userId).toBe('cognito-1');
     // mention_thread_ts flows to channel_metadata