feat(linear): pre-hydrate recent human comments into task description (ADR-016)

The agent has no Linear MCP to read the issue thread at runtime, so fetch
recent HUMAN comments at admission time and fold them into the task
description under a '## Recent comments' heading — mirroring the Jira
processor (aws-samples#577).

- linear-feedback.fetchRecentComments: direct GraphQL (reuses existing
  token/graphqlData infra), filters app/integration comments (botActor
  present or no user) + bot-prefixed bodies (isBotAuthoredComment),
  oldest-first, capped, fail-open (any failure → []).
- processor: screenCommentsOrDrop screens the folded block through the
  Bedrock Guardrail (fail-open — third-party text that trips policy is
  dropped, never the reporter's task); buildTaskDescription folds within
  MAX_TASK_DESCRIPTION_LENGTH with truncation, mirroring Jira.

Aligns the Linear test suite to the Jira pattern (guardrail/S3 configured
by default, unconfigured case re-imports), which also adds the first
processor-level coverage of the P4.1 authenticated-attachment path.

Author: isadeks

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

@@ -18,7 +18,7 @@
  */
 
 import * as crypto from 'crypto';
-import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import { BedrockRuntimeClient, ApplyGuardrailCommand } from '@aws-sdk/client-bedrock-runtime';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { S3Client } from '@aws-sdk/client-s3';
 import { DynamoDBDocumentClient, GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
@@ -30,6 +30,7 @@ import { renderMaturingReply } from './shared/iteration-reply';
 import { cleanupPreScreenedAttachments, downloadScreenAndStoreLinearAttachments, LinearAttachmentError } from './shared/linear-attachments';
 import {
   deleteComment,
+  fetchRecentComments,
   reactToComment,
   replyToComment,
   reportIssueFailure,
@@ -41,6 +42,7 @@ import {
   EMOJI_STARTED,
   EMOJI_SUCCESS,
   EMOJI_NEEDS_INPUT,
+  type RenderedComment,
 } from './shared/linear-feedback';
 import {
   probeLinearIssueContext,
@@ -113,6 +115,7 @@ import { readConcurrencyBudget, releaseReadyChildren } from './shared/orchestrat
 import { upsertEpicPanel } from './shared/orchestration-rollup';
 import { claimCommentAck, clearRollupClaim, deriveOrchestrationId, loadOrchestration, setStatusCommentId, type OrchestrationReleaseContext } from './shared/orchestration-store';
 import type { Attachment, PassedAttachmentRecord } from './shared/types';
+import { MAX_TASK_DESCRIPTION_LENGTH } from './shared/validation';
 import { CODING_WORKFLOW_ID } from './shared/workflows';
 
 const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
@@ -900,7 +903,22 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     }
   }
 
-  const taskDescription = buildTaskDescription(issue, contextHint);
+  // ADR-016 pre-hydration: fetch recent HUMAN comments and fold them into the
+  // task description — the agent has no Linear MCP to read the thread at
+  // runtime. Advisory + fail-open end to end: a fetch failure yields no
+  // comments, and third-party comment text that trips the guardrail is dropped
+  // (never the task; the reporter-authored description is screened separately by
+  // createTaskCore). Mirrors the Jira processor (#619/#577).
+  let recentComments: RenderedComment[] = [];
+  if (WORKSPACE_REGISTRY_TABLE && resolvedAccessToken) {
+    const fetched = await fetchRecentComments(
+      { linearWorkspaceId: workspaceId, registryTableName: WORKSPACE_REGISTRY_TABLE },
+      issue.id,
+    );
+    recentComments = await screenCommentsOrDrop(fetched, issue.id, workspaceId);
+  }
+
+  const taskDescription = buildTaskDescription(issue, contextHint, recentComments);
 
   // Extract embedded image URLs from the issue description markdown. Non-Linear
   // (public CDN) images become URL attachments fetched+screened during context
@@ -3021,7 +3039,11 @@ function buildRevisionTaskDescription(issueText: string, pending: PendingPlan, f
   ].join('\n');
 }
 
-function buildTaskDescription(issue: LinearIssueEvent['data'], contextHint: string = ''): string {
+function buildTaskDescription(
+  issue: LinearIssueEvent['data'],
+  contextHint: string = '',
+  comments: readonly RenderedComment[] = [],
+): string {
   const parts: string[] = [];
   if (issue.identifier && issue.title) {
     parts.push(`${issue.identifier}: ${issue.title}`);
@@ -3036,7 +3058,99 @@ function buildTaskDescription(issue: LinearIssueEvent['data'], contextHint: stri
     parts.push('');
     parts.push(issue.description.trim());
   }
-  return parts.join('\n') || 'Linear issue';
+  const core = parts.join('\n') || 'Linear issue';
+
+  // Fold recent human comments under a clear heading so the agent can tell them
+  // from the description (ADR-016 pre-hydration). Comments are ADVISORY and must
+  // stay fail-open: they must never grow the description past
+  // MAX_TASK_DESCRIPTION_LENGTH and turn createTaskCore's length check into a
+  // hard rejection. Only append what fits the remaining budget, truncating the
+  // section if needed. Mirrors the Jira processor.
+  if (comments.length === 0) return core;
+  const commentSection = renderCommentSection(comments);
+  const separator = '\n';
+  const budget = MAX_TASK_DESCRIPTION_LENGTH - core.length - separator.length;
+  if (budget <= 0) return core; // description already fills the budget — drop comments
+  const fitted = commentSection.length <= budget
+    ? commentSection
+    : truncateCommentSection(commentSection, budget);
+  return fitted ? core + separator + fitted : core;
+}
+
+/** Notice appended when the comment section is truncated to fit the budget. */
+const COMMENT_TRUNCATION_NOTICE = '\n\n_(recent comments truncated)_';
+
+function renderCommentSection(comments: readonly RenderedComment[]): string {
+  const lines: string[] = ['', '## Recent comments'];
+  for (const c of comments) {
+    lines.push('');
+    const attribution = c.createdAt ? `**${c.author}** (${c.createdAt}):` : `**${c.author}**:`;
+    lines.push(attribution);
+    lines.push(c.markdown);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Trim a rendered comment section to at most ``budget`` characters, leaving room
+ * for a truncation notice. Returns '' if even the heading + notice can't fit, so
+ * the caller cleanly drops the section. Mirrors the Jira processor.
+ */
+function truncateCommentSection(section: string, budget: number): string {
+  const room = budget - COMMENT_TRUNCATION_NOTICE.length;
+  if (room <= 0) return '';
+  return section.slice(0, room) + COMMENT_TRUNCATION_NOTICE;
+}
+
+/**
+ * Screen the rendered comment block through the Bedrock Guardrail on its own, so
+ * third-party comment content that trips the policy is DROPPED (fail-open)
+ * rather than gating the reporter's task. Returns the comments unchanged when
+ * they pass, and ``[]`` when the guardrail intervenes or is unavailable — the
+ * task still proceeds with the reporter-authored title/description (which
+ * createTaskCore screens separately). Keeps the comment-enrichment contract
+ * fail-open end to end. Mirrors the Jira processor (#577 review, item 4).
+ */
+async function screenCommentsOrDrop(
+  comments: RenderedComment[],
+  issueId: string,
+  workspaceId: string,
+): Promise<RenderedComment[]> {
+  if (comments.length === 0) return comments;
+  if (!attachmentsBedrockClient || !GUARDRAIL_ID || !GUARDRAIL_VERSION) {
+    // No guardrail configured — drop unscreened third-party text rather than
+    // route it, unscreened, into the agent context.
+    logger.warn('Dropping Linear comments: guardrail not configured to screen them', {
+      issue_id: issueId,
+      linear_workspace_id: workspaceId,
+    });
+    return [];
+  }
+  const text = renderCommentSection(comments);
+  try {
+    const result = await attachmentsBedrockClient.send(new ApplyGuardrailCommand({
+      guardrailIdentifier: GUARDRAIL_ID,
+      guardrailVersion: GUARDRAIL_VERSION,
+      source: 'INPUT',
+      content: [{ text: { text } }],
+    }));
+    if (result.action === 'GUARDRAIL_INTERVENED') {
+      logger.warn('Dropping Linear comments: blocked by content policy (task still proceeds)', {
+        issue_id: issueId,
+        linear_workspace_id: workspaceId,
+      });
+      return [];
+    }
+    return comments;
+  } catch (err) {
+    // Fail-open on a screening outage too — comments are advisory.
+    logger.warn('Dropping Linear comments: screening unavailable (task still proceeds)', {
+      issue_id: issueId,
+      linear_workspace_id: workspaceId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return [];
+  }
 }
 
 /**

cdk/src/handlers/shared/linear-feedback.ts

@@ -20,6 +20,7 @@
 import { preservePreviewSuffix } from './iteration-reply';
 import { resolveLinearOauthToken } from './linear-oauth-resolver';
 import { logger } from './logger';
+import { isBotAuthoredComment } from './orchestration-comment-trigger';
 
 /**
  * Lambda-side helper for posting comments and reactions onto Linear issues
@@ -104,6 +105,36 @@ query IssueComments($issueId: String!) {
 }
 `.trim();
 
+/**
+ * Fetch comments with the author metadata needed to tell a human turn from a
+ * bot/integration one (ADR-016 pre-hydration — the agent has no Linear MCP to
+ * read the thread at runtime). ``user`` is the human author (null when a comment
+ * was posted by an OAuth app / integration); ``botActor`` is present precisely
+ * for those app/integration comments — so @bgagent's own progress and ack
+ * comments carry a ``botActor`` and no ``user``. ``createdAt`` orders the thread.
+ *
+ * We fetch the first 100 (matching {@link ISSUE_COMMENTS_QUERY}) and sort +
+ * slice to the most recent human comments CLIENT-SIDE, so the result is
+ * independent of Linear's connection sort direction. 100 covers every realistic
+ * issue thread; the rare over-100 issue simply may miss the oldest turns, which
+ * is acceptable for advisory context.
+ */
+const RECENT_COMMENTS_QUERY = `
+query RecentComments($issueId: String!) {
+  issue(id: $issueId) {
+    comments(first: 100) {
+      nodes {
+        id
+        body
+        createdAt
+        user { displayName name }
+        botActor { id }
+      }
+    }
+  }
+}
+`.trim();
+
 /**
  * Post a THREADED REPLY beneath an existing comment (#247 UX.3 ack trail).
  * ``parentId`` is the comment being replied to; the reply notifies and reads
@@ -457,6 +488,82 @@ export async function sweepDecompositionNotes(
   return deleted;
 }
 
+/** A rendered issue comment folded into the task context (mirrors the Jira
+ *  ``RenderedComment`` shape so the two processors read alike). */
+export interface RenderedComment {
+  readonly author: string;
+  readonly createdAt: string;
+  readonly markdown: string;
+}
+
+/** Default cap on recent human comments folded into the task context. */
+const DEFAULT_MAX_RECENT_COMMENTS = 20;
+
+interface RawLinearComment {
+  readonly id?: string;
+  readonly body?: string;
+  readonly createdAt?: string;
+  readonly user?: { readonly displayName?: string; readonly name?: string } | null;
+  readonly botActor?: { readonly id?: string } | null;
+}
+
+/**
+ * Fetch the most recent HUMAN-authored comments on an issue, rendered to
+ * markdown oldest-first, for pre-hydrating the task context (ADR-016 — the agent
+ * has no Linear MCP to read the thread at runtime). Best-effort / fail-open: any
+ * failure (token, GraphQL error, malformed body) logs a WARN and returns ``[]``
+ * so the task still proceeds — comments are advisory context, not a gate.
+ *
+ * "Human" excludes app/integration comments two ways (belt and suspenders):
+ *   1. ``botActor`` present, or ``user`` absent → posted by an OAuth app /
+ *      integration (this is how @bgagent's own comments are marked);
+ *   2. the body starts with one of the bot's own rendered-comment markers
+ *      ({@link isBotAuthoredComment}) — catches anything mis-attributed to a user.
+ */
+export async function fetchRecentComments(
+  ctx: LinearFeedbackContext,
+  issueId: string,
+  maxComments: number = DEFAULT_MAX_RECENT_COMMENTS,
+): Promise<RenderedComment[]> {
+  const token = await resolveToken(ctx);
+  if (!token) return [];
+  const data = await graphqlData(token, RECENT_COMMENTS_QUERY, { issueId });
+  const issue = data?.issue as { comments?: { nodes?: RawLinearComment[] } } | undefined;
+  const nodes = issue?.comments?.nodes ?? [];
+
+  const human: RenderedComment[] = [];
+  for (const node of nodes) {
+    // Skip app/integration comments (bgagent + other bots): they carry a
+    // botActor and no human user.
+    if (node.botActor || !node.user) continue;
+    const body = (node.body ?? '').trim();
+    if (!body) continue;
+    // Belt and suspenders: drop anything that reads as one of our own rendered
+    // comments even if it slipped through as a "user" comment.
+    if (isBotAuthoredComment(body)) continue;
+    human.push({
+      author: node.user.displayName?.trim() || node.user.name?.trim() || 'Unknown',
+      createdAt: typeof node.createdAt === 'string' ? node.createdAt : '',
+      markdown: body,
+    });
+  }
+
+  // Order oldest-first so the thread reads naturally, then keep the most recent
+  // ``maxComments`` (sort is client-side — independent of Linear's connection
+  // sort direction). Comments without a timestamp sort last (treated as newest).
+  human.sort((a, b) => (a.createdAt || '￿').localeCompare(b.createdAt || '￿'));
+  const recent = human.length > maxComments ? human.slice(human.length - maxComments) : human;
+
+  if (recent.length > 0) {
+    logger.info('Fetched recent human Linear comments for task context', {
+      linear_workspace_id: ctx.linearWorkspaceId,
+      issue_id: issueId,
+      count: recent.length,
+    });
+  }
+  return recent;
+}
+
 /**
  * Add an emoji reaction onto a Linear issue. Defaults to ❌ — the failure marker
  * the agent uses on the success/failure side. Same result contract as