feat(pm): replace PR comment links with native attachments/remote links

src/jira/client.ts

@@ -253,4 +253,21 @@ export const jiraClient = {
 			},
 		});
 	},
+
+	async addRemoteLink(issueKey: string, url: string, title: string): Promise<void> {
+		logger.debug('Adding JIRA remote link', { issueKey, url, title });
+		await getClient().issueRemoteLinks.createOrUpdateRemoteIssueLink({
+			issueIdOrKey: issueKey,
+			globalId: url,
+			relationship: 'Pull Request',
+			object: {
+				url,
+				title,
+				icon: {
+					url16x16: 'https://github.com/favicon.ico',
+					title: 'GitHub',
+				},
+			},
+		});
+	},
 };

src/pm/jira/adapter.ts

@@ -331,6 +331,10 @@ export class JiraPMProvider implements PMProvider {
 		await this.addComment(_workItemId, `Attachment: [${name}](${url})`);
 	}
 
+	async linkPR(workItemId: string, prUrl: string, prTitle: string): Promise<void> {
+		await jiraClient.addRemoteLink(workItemId, prUrl, prTitle);
+	}
+
 	async addAttachmentFile(
 		workItemId: string,
 		buffer: Buffer,

src/pm/lifecycle.ts

@@ -29,6 +29,15 @@ export interface ProjectPMConfig {
 	};
 }
 
+/**
+ * Extract a human-readable PR title from a GitHub PR URL.
+ * E.g. "https://github.com/owner/repo/pull/123" → "Pull Request #123"
+ */
+export function extractPRTitle(prUrl: string): string {
+	const match = prUrl.match(/\/pull\/(\d+)/);
+	return match ? `Pull Request #${match[1]}` : 'Pull Request';
+}
+
 /**
  * Resolve PM-specific config (labels, statuses) from project configuration.
  * Delegates to the registered integration's resolveLifecycleConfig().
@@ -64,11 +73,22 @@ export class PMLifecycleManager {
 		if (agentType === 'implementation') {
 			await this.safeMove(workItemId, this.pmConfig.statuses.inReview);
 			if (prUrl) {
-				if (progressCommentId) {
-					// Replace the progress comment with the "PR created" message
-					await this.safeUpdateOrAddComment(workItemId, progressCommentId, `PR created: ${prUrl}`);
-				} else {
-					await this.safeAddComment(workItemId, `PR created: ${prUrl}`);
+				const prTitle = extractPRTitle(prUrl);
+				let linked = false;
+				try {
+					await this.provider.linkPR(workItemId, prUrl, prTitle);
+					linked = true;
+				} catch {
+					// linkPR failed — fall through to comment fallback
+				}
+				if (!linked) {
+					const message = `PR created: ${prUrl}`;
+					if (progressCommentId) {
+						// Replace the progress comment with the "PR created" message
+						await this.safeUpdateOrAddComment(workItemId, progressCommentId, message);
+					} else {
+						await this.safeAddComment(workItemId, message);
+					}
 				}
 			}
 		}

src/pm/trello/adapter.ts

@@ -196,6 +196,10 @@ export class TrelloPMProvider implements PMProvider {
 		await trelloClient.addAttachment(workItemId, url, name);
 	}
 
+	async linkPR(workItemId: string, prUrl: string, prTitle: string): Promise<void> {
+		await trelloClient.addAttachment(workItemId, prUrl, prTitle);
+	}
+
 	async addAttachmentFile(
 		workItemId: string,
 		buffer: Buffer,

src/pm/types.ts

@@ -101,6 +101,9 @@ export interface PMProvider {
 	getCustomFieldNumber(workItemId: string, fieldId: string): Promise<number>;
 	updateCustomFieldNumber(workItemId: string, fieldId: string, value: number): Promise<void>;
 
+	// PR linking
+	linkPR(workItemId: string, prUrl: string, prTitle: string): Promise<void>;
+
 	// Utility
 	getWorkItemUrl(id: string): string;
 	getAuthenticatedUser(): Promise<{ id: string; name: string; username: string }>;

tests/helpers/mockPMProvider.ts

@@ -33,6 +33,7 @@ export function createMockPMProvider() {
 		deleteChecklistItem: vi.fn(),
 		addAttachment: vi.fn(),
 		addAttachmentFile: vi.fn(),
+		linkPR: vi.fn().mockResolvedValue(undefined),
 		getCustomFieldNumber: vi.fn(),
 		updateCustomFieldNumber: vi.fn(),
 		getWorkItemUrl: vi.fn(),

tests/unit/jira/client.test.ts

@@ -15,6 +15,7 @@ const {
 	mockIssueComments,
 	mockIssueSearch,
 	mockIssueAttachments,
+	mockIssueRemoteLinks,
 	mockMyself,
 	mockProjects,
 } = vi.hoisted(() => ({
@@ -37,6 +38,9 @@ const {
 	mockIssueAttachments: {
 		addAttachment: vi.fn(),
 	},
+	mockIssueRemoteLinks: {
+		createOrUpdateRemoteIssueLink: vi.fn(),
+	},
 	mockMyself: {
 		getCurrentUser: vi.fn(),
 	},
@@ -51,6 +55,7 @@ vi.mock('jira.js', () => ({
 		issueComments: mockIssueComments,
 		issueSearch: mockIssueSearch,
 		issueAttachments: mockIssueAttachments,
+		issueRemoteLinks: mockIssueRemoteLinks,
 		myself: mockMyself,
 		projects: mockProjects,
 	})),
@@ -84,6 +89,7 @@ describe('jiraClient', () => {
 		mockIssueComments.updateComment.mockReset();
 		mockIssueSearch.searchForIssuesUsingJql.mockReset();
 		mockIssueAttachments.addAttachment.mockReset();
+		mockIssueRemoteLinks.createOrUpdateRemoteIssueLink.mockReset();
 		mockMyself.getCurrentUser.mockReset();
 		mockProjects.getProject.mockReset();
 		_resetCloudIdCache();
@@ -567,6 +573,71 @@ describe('jiraClient', () => {
 		});
 	});
 
+	describe('addRemoteLink', () => {
+		it('calls createOrUpdateRemoteIssueLink with correct params', async () => {
+			mockIssueRemoteLinks.createOrUpdateRemoteIssueLink.mockResolvedValue({ id: 'link-1' });
+
+			await withJiraCredentials(creds, () =>
+				jiraClient.addRemoteLink(
+					'TEST-1',
+					'https://github.com/owner/repo/pull/42',
+					'Pull Request #42',
+				),
+			);
+
+			expect(mockIssueRemoteLinks.createOrUpdateRemoteIssueLink).toHaveBeenCalledWith(
+				expect.objectContaining({
+					issueIdOrKey: 'TEST-1',
+					globalId: 'https://github.com/owner/repo/pull/42',
+					relationship: 'Pull Request',
+					object: expect.objectContaining({
+						url: 'https://github.com/owner/repo/pull/42',
+						title: 'Pull Request #42',
+					}),
+				}),
+			);
+		});
+
+		it('uses PR URL as globalId for idempotency', async () => {
+			mockIssueRemoteLinks.createOrUpdateRemoteIssueLink.mockResolvedValue({ id: 'link-2' });
+			const prUrl = 'https://github.com/owner/repo/pull/99';
+
+			await withJiraCredentials(creds, () =>
+				jiraClient.addRemoteLink('PROJ-5', prUrl, 'Pull Request #99'),
+			);
+
+			expect(mockIssueRemoteLinks.createOrUpdateRemoteIssueLink).toHaveBeenCalledWith(
+				expect.objectContaining({
+					globalId: prUrl,
+				}),
+			);
+		});
+
+		it('sets GitHub favicon icon on the remote link object', async () => {
+			mockIssueRemoteLinks.createOrUpdateRemoteIssueLink.mockResolvedValue({});
+
+			await withJiraCredentials(creds, () =>
+				jiraClient.addRemoteLink('TEST-1', 'https://github.com/owner/repo/pull/1', 'PR #1'),
+			);
+
+			expect(mockIssueRemoteLinks.createOrUpdateRemoteIssueLink).toHaveBeenCalledWith(
+				expect.objectContaining({
+					object: expect.objectContaining({
+						icon: expect.objectContaining({
+							url16x16: 'https://github.com/favicon.ico',
+						}),
+					}),
+				}),
+			);
+		});
+
+		it('throws when called outside withJiraCredentials scope', async () => {
+			await expect(
+				jiraClient.addRemoteLink('TEST-1', 'https://github.com/pr/1', 'PR #1'),
+			).rejects.toThrow('No JIRA credentials in scope');
+		});
+	});
+
 	describe('getIssueComments', () => {
 		it('returns comments array', async () => {
 			const comments = [{ id: 'c1', body: 'First comment' }];

tests/unit/pm/jira/adapter.test.ts

@@ -17,6 +17,7 @@ const { mockJiraClient, mockAdfToPlainText, mockMarkdownToAdf } = vi.hoisted(()
 		getIssueLabels: vi.fn(),
 		updateLabels: vi.fn(),
 		addAttachmentFile: vi.fn(),
+		addRemoteLink: vi.fn(),
 		getCustomFieldValue: vi.fn(),
 		updateCustomField: vi.fn(),
 		getMyself: vi.fn(),
@@ -685,6 +686,20 @@ describe('JiraPMProvider', () => {
 		});
 	});
 
+	describe('linkPR', () => {
+		it('delegates to jiraClient.addRemoteLink with workItemId, prUrl, and prTitle', async () => {
+			mockJiraClient.addRemoteLink.mockResolvedValue(undefined);
+
+			await provider.linkPR('PROJ-1', 'https://github.com/owner/repo/pull/42', 'Pull Request #42');
+
+			expect(mockJiraClient.addRemoteLink).toHaveBeenCalledWith(
+				'PROJ-1',
+				'https://github.com/owner/repo/pull/42',
+				'Pull Request #42',
+			);
+		});
+	});
+
 	describe('getCustomFieldNumber', () => {
 		it('returns numeric custom field value', async () => {
 			mockJiraClient.getCustomFieldValue.mockResolvedValue(99);