feat: complete BitBucket VCS provider integration gaps

[acreeger]

Fixes #861

feat: complete BitBucket VCS provider integration gaps

Context

PR #609 adds BitBucket VCS provider support. After merging the generic merge mode refactoring (epic #842), a gap analysis identified several places where BitBucket isn't fully wired in.

Important correction: An earlier analysis incorrectly claimed that some MCP PR operations (get_pr, create_comment(type:pr)) already routed through BitBucket. This was wrong — all MCP PR operations have always been GitHub-only. No BitBucket routing has ever existed in the MCP server.

Current State

The MCP server (src/mcp/issue-management-server.ts) has these PR-related tools, all hardcoded to GitHub:

Tool	Current Code	Line
get_pr	new GitHubIssueManagementProvider()	262
get_review_comments	new GitHubIssueManagementProvider()	332
create_comment(type:pr)	providerType = 'github'	441
update_comment(type:pr)	providerType = 'github'	493

All have comments saying "PRs only exist on GitHub" which is no longer true with BitBucket support.

Additionally, VersionControlProvider.createPR() returns Promise<string> (URL only), which means finish.ts can never pass a PR number to SessionSummaryService for BitBucket PRs.

Changes Required

1. Fix createPR() return type

Files: src/lib/VersionControlProvider.ts, src/lib/providers/bitbucket/BitBucketVCSProvider.ts, src/commands/finish.ts

• createPR() returns Promise<string> (line 46) but PRCreationResult interface already exists (lines 9-13) with { url, number, wasExisting }
• Change createPR() return type to Promise<PRCreationResult>
• Update BitBucketVCSProvider.createPR() to return { url: pr.links.html.href, number: pr.id, wasExisting: false }
• Update finish.ts to extract prNumber from the result
• This unblocks SessionSummaryService which already has VCS routing code but never gets a prNumber for BitBucket

2. Add BitBucket PR comment API methods to BitBucketApiClient

File: src/lib/providers/bitbucket/BitBucketApiClient.ts

Currently only has addPRComment() for general comments. Need:

a) updatePRComment(workspace, repoSlug, prId, commentId, content)

• PUT /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id}
• Body: { "content": { "raw": "text" } }
• Confirmed supported by BitBucket Cloud REST API (verified from official swagger.json)

b) listPRComments(workspace, repoSlug, prId)

• GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments
• Returns comments including inline metadata (from, to, path fields)
• Needs pagination (follow existing getAllWorkspaceMembers pattern)

c) addInlinePRComment(workspace, repoSlug, prId, content, filePath, line)

• POST to same endpoint as addPRComment but with inline: { to: line, path: filePath } in body

3. Add VCS provider methods to BitBucketVCSProvider

File: src/lib/providers/bitbucket/BitBucketVCSProvider.ts

Add methods that delegate to BitBucketApiClient:

• updatePRComment(prNumber, commentId, body, cwd?)
• getReviewComments(prNumber, cwd?) — calls listPRComments, filters for comments with inline property
• createReviewComment(prNumber, path, line, body, cwd?) — calls addInlinePRComment

4. Update VersionControlProvider interface

File: src/lib/VersionControlProvider.ts

Add to the interface:

• updatePRComment(prNumber: number, commentId: string, body: string, cwd?: string): Promise<{ id: string; url: string }>
• getReviewComments(prNumber: number, cwd?: string): Promise<ReviewComment[]>
• createReviewComment(prNumber: number, path: string, line: number, body: string, cwd?: string): Promise<{ id: string; url: string }>

Define ReviewComment type to match what the MCP tool's output schema expects.

5. Route MCP PR operations through VCS provider

File: src/mcp/issue-management-server.ts

The MCP server needs to load the VCS provider at startup (like it does for issue provider) and route PR operations through it.

a) At startup: initialize a VCS provider from settings using VCSProviderFactory
b) get_pr (line 257-263): Use VCS provider's fetchPR() when BitBucket configured, fall back to GitHub
c) create_comment(type:pr) (line 438-443): Use VCS provider's createPRComment() when BitBucket configured
d) update_comment(type:pr) (line 490-495): Use VCS provider's updatePRComment() when BitBucket configured
e) get_review_comments (line 327-334): Use VCS provider's getReviewComments() when BitBucket configured
f) Remove all "PRs only exist on GitHub" comments

6. Documentation

File: docs/iloom-commands.md

• Add VCS provider configuration section explaining versionControl.provider and versionControl.bitbucket settings
• Document supported provider combinations (e.g., Jira issues + BitBucket VCS, GitHub issues + BitBucket VCS)
• Note that Draft PR mode is GitHub-only

Out of Scope

• Init wizard VCS provider step (document in docs instead)
• Draft PR operations for BitBucket (BitBucket doesn't support drafts)

Must-Haves

• createPR() returns PRCreationResult ({ url, number, wasExisting })
• BitBucketApiClient has updatePRComment(), addInlinePRComment(), listPRComments() methods
• BitBucketVCSProvider has updatePRComment(), getReviewComments(), createReviewComment() methods
• VersionControlProvider interface updated with new methods
• MCP server loads VCS provider at startup and routes all PR operations through it
• All "PRs only exist on GitHub" comments removed
• All new methods have tests
• pnpm build succeeds
• pnpm test passes
• VCS provider configuration documented in docs/iloom-commands.md

---

This PR was created automatically by iloom.

[acreeger]

Analysis Phase

• Fetch and understand issue requirements
• Research VersionControlProvider interface and PRCreationResult type
• Research BitBucketApiClient - existing methods and patterns
• Research BitBucketVCSProvider - existing methods and patterns
• Research GitHubVCSProvider / GitHubIssueManagementProvider - for parity comparison
• Research MCP server PR operation routing
• Research finish.ts PR creation flow
• Research SessionSummaryService VCS routing
• Cross-cutting change analysis across all layers
• Document findings

---

Executive Summary

This issue requires wiring BitBucket VCS operations into 4 distinct subsystems: (1) changing createPR() to return structured data instead of a bare URL, (2) adding 3 new API methods to BitBucketApiClient and 3 corresponding methods to BitBucketVCSProvider, (3) updating the VersionControlProvider interface, and (4) routing the MCP server's 4 PR-related tools through the VCS provider instead of hardcoding GitHub. The issue description is thorough and accurate; analysis confirms all stated line numbers and change requirements. However, analysis uncovered two additional gaps not mentioned in the issue.

Questions and Key Decisions

Question	Answer
Should the MCP server route PR operations through VersionControlProvider directly, or through IssueManagementProvider with new methods?	Through VersionControlProvider. The MCP server already loads settings at startup; VCSProviderFactory.create(settings) can produce a provider. The IssueManagementProvider interface is for issue trackers (GitHub/Linear/Jira), not VCS operations. Mixing concerns would be architecturally wrong.
createPRComment on VersionControlProvider returns Promise<void> but MCP create_comment(type:pr) needs {id, url}. How to handle?	The return type must change to Promise<{id: string; url: string}>. This is a cross-cutting change affecting the interface, BitBucketVCSProvider, and any GitHub adapter. The addPRComment on BitBucketApiClient currently returns void and must return the API response body (which includes id and links.html.href).
BitBucketApiClient.request() only supports GET and POST. How to add PUT?	Extend the method union from 'GET' | 'POST' to 'GET' | 'POST' | 'PUT' (line 119). Add a private put<T>() helper matching the existing get<T>() and post<T>() pattern.

HIGH/CRITICAL Risks

• Session summary never posts to newly created BitBucket PRs: finish.ts line 1181 calls vcsProvider.createPR() which returns string (URL only). The prNumber is never extracted, so generateSessionSummaryIfConfigured is never called after creating a new PR (it IS called for existing PRs at line 1173). Changing the return type to PRCreationResult fixes this.
• Session summary hardcodes GitHub for PR comments: SessionSummaryService.postSummaryToIssue() at line 408 sets providerType = 'github' when prNumber is provided. Even after fixing createPR(), session summaries would attempt to post to GitHub instead of BitBucket. This must be updated to route through the VCS provider.

Impact Summary

• 1 interface to modify (VersionControlProvider) - return type change + 3 new methods
• 1 API client to extend (BitBucketApiClient) - PUT support + 3 new methods
• 1 VCS provider to extend (BitBucketVCSProvider) - return type change + 3 new methods
• 1 MCP server to refactor (issue-management-server.ts) - VCS provider initialization + 4 tool routing changes
• 1 command file to update (finish.ts) - extract prNumber from PRCreationResult + pass to summary
• 1 service to fix (SessionSummaryService) - VCS-aware PR comment routing
• 1 docs file to update (docs/iloom-commands.md)
• All existing test files for above components need updates
• Key decision: createPRComment return type change from Promise<void> to Promise<{id: string; url: string}> is a breaking interface change

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

BitBucket VCS support was added in PR #609 but left gaps: PR operations in the MCP server are hardcoded to GitHub, createPR() returns a bare URL preventing downstream systems from using the PR number, and several comment operations (update, inline review) are missing from the BitBucket provider.

Architectural Context

The system has two parallel provider abstractions:

• IssueManagementProvider (src/mcp/types.ts:336): Issue tracker abstraction (GitHub/Linear/Jira). Handles issues, comments, dependencies. Used by the MCP server.
• VersionControlProvider (src/lib/VersionControlProvider.ts:32): VCS abstraction (GitHub/BitBucket). Handles PRs, branches. Used by finish.ts, LoomManager.

PR operations currently split across both systems. The MCP server uses GitHubIssueManagementProvider directly for PR tools (get_pr, get_review_comments, create/update_comment for PRs). The finish.ts command uses VersionControlProvider via VCSProviderFactory.

Edge Cases Identified

• VCSProviderFactory.create() returns null for GitHub (line 38-40) - MCP routing must handle this fallback to GitHubIssueManagementProvider
• BitBucket API token could be missing from settings - BitBucketVCSProvider.fromSettings() already validates this (line 42-47)
• BitBucket PR comments don't have the same URL structure as GitHub (#issuecomment-N) - comment ID extraction logic differs

Codebase Research Findings

Change 1: createPR() return type

VersionControlProvider interface - src/lib/VersionControlProvider.ts:40-46

• Current: createPR(...): Promise<string>
• PRCreationResult already defined at lines 9-13: { url: string, number: number, wasExisting: boolean }
• Change to Promise<PRCreationResult>

BitBucketVCSProvider.createPR() - src/lib/providers/bitbucket/BitBucketVCSProvider.ts:111-164

• Line 163: return pr.links.html.href - change to return { url: pr.links.html.href, number: pr.id, wasExisting: false }
• The pr variable (line 143) is BitBucketPullRequest which has both .id and .links.html.href
• Response validation at line 154 already checks pr?.id and pr?.links?.html?.href

finish.ts VCS PR workflow - src/commands/finish.ts:1181-1196

• Line 1181: const prUrl = await vcsProvider.createPR(...) - change to destructure PRCreationResult
• Line 1189-1190: use result.url for logging and finishResult.prUrl
• After line 1195: add generateSessionSummaryIfConfigured(parsed, worktree, options, result.number)

finish.ts GitHub/legacy PR workflow - src/commands/finish.ts:1218+

• The legacy PRManager.createOrOpenPR() path at line 1261 returns { url, number } already - no change needed

Change 2: BitBucketApiClient new methods

File: src/lib/providers/bitbucket/BitBucketApiClient.ts

a) Extend request() to support PUT

• Line 118-119: private async request<T>(method: 'GET' | 'POST', ...) - add 'PUT'
• Add private async put<T>(endpoint: string, body: unknown): Promise<T> matching post<T>() at line 191-193

b) updatePRComment()

• PUT /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id}
• Body: { content: { raw: text } }
• Returns: BitBucket comment object with id and links.html.href

c) listPRComments()

• GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments
• Needs pagination following getAllWorkspaceMembers() pattern at line 340-357
• Returns: paginated { values: Comment[], next?: string }

d) addInlinePRComment()

• POST to same endpoint as addPRComment with additional inline: { to: line, path: filePath } in body

e) addPRComment() return type change

• Line 286-300: Currently returns Promise<void> - needs to return the response body with id and links
• Interface for return: { id: number, links: { html: { href: string } } } (matching BitBucket API response)

Change 3: BitBucketVCSProvider new methods

File: src/lib/providers/bitbucket/BitBucketVCSProvider.ts

New methods to add:

• updatePRComment(prNumber, commentId, body, cwd?) - delegates to client.updatePRComment()
• getReviewComments(prNumber, cwd?) - calls client.listPRComments(), filters for inline property
• createReviewComment(prNumber, path, line, body, cwd?) - calls client.addInlinePRComment()

Existing pattern to follow: createPRComment() at line 189-195 shows the pattern of calling getWorkspaceAndRepo(cwd) then delegating to client.

Change 4: VersionControlProvider interface updates

File: src/lib/VersionControlProvider.ts

New methods to add to interface:

• updatePRComment(prNumber: number, commentId: string, body: string, cwd?: string): Promise<{ id: string; url: string }>
• getReviewComments(prNumber: number, cwd?: string): Promise<ReviewComment[]>
• createReviewComment(prNumber: number, path: string, line: number, body: string, cwd?: string): Promise<{ id: string; url: string }>

Also change createPRComment return type from Promise<void> to Promise<{ id: string; url: string }>.

Define ReviewComment type to match ReviewCommentResult from src/mcp/types.ts:53-64.

Change 5: MCP server routing

File: src/mcp/issue-management-server.ts

Startup initialization (in main() at line 1035):

• After settings load (line 1058), initialize VCS provider: const vcsProvider = VCSProviderFactory.create(settings!)
• Store as module-level variable like settings

Tool routing changes:

a) get_pr (line 257-282): When vcsProvider !== null, call vcsProvider.fetchPR(prNumber) and map result to PRResult shape

b) get_review_comments (line 327-353): When vcsProvider !== null, call vcsProvider.getReviewComments(prNumber) and map to ReviewCommentResult[]

c) create_comment(type:pr) (line 438-464): When vcsProvider !== null, call vcsProvider.createPRComment(prNumber, body) instead of routing to GitHub IssueManagementProvider

d) update_comment(type:pr) (line 487-516): When vcsProvider !== null, call vcsProvider.updatePRComment(prNumber, commentId, body)

e) Remove all "PRs only exist on GitHub" comments

Architecture note: Tool handler closures in McpServer can capture the module-level vcsProvider variable, same pattern as the existing settings capture.

Change 6: SessionSummaryService fix (not in issue)

File: src/lib/SessionSummaryService.ts:398-426

Line 408-409 hardcodes providerType = 'github' when prNumber is provided. This needs to be VCS-aware:

• Load VCS provider from settings
• When VCS provider is BitBucket and prNumber is provided, use the VCS provider's createPRComment instead of the IssueManagementProvider

Change 7: finish.ts session summary gap (not in issue)

File: src/commands/finish.ts:1174-1196

After vcsProvider.createPR() (line 1181), the session summary is never generated for newly created PRs. With PRCreationResult, the prNumber becomes available and generateSessionSummaryIfConfigured should be called.

Architectural Flow Analysis

Data Flow: createPR() return value

Entry Point: src/lib/VersionControlProvider.ts:40-46 - createPR() returns Promise<string>

Flow Path:

1. src/lib/providers/bitbucket/BitBucketVCSProvider.ts:111-164 - createPR() calls client.createPullRequest(), extracts pr.links.html.href, returns URL string
2. src/commands/finish.ts:1181 - executeVCSPRWorkflow() receives URL string as prUrl
3. src/commands/finish.ts:1190 - Stores URL in finishResult.prUrl
4. Dead end: No prNumber extracted, so generateSessionSummaryIfConfigured never called for new PRs

After fix:

1. VersionControlProvider.createPR() returns Promise<PRCreationResult> ({url, number, wasExisting})
2. BitBucketVCSProvider.createPR() returns { url: pr.links.html.href, number: pr.id, wasExisting: false }
3. finish.ts extracts both url and number from result
4. Calls generateSessionSummaryIfConfigured(parsed, worktree, options, result.number)

Affected Interfaces (ALL must be updated):

• VersionControlProvider.createPR() at src/lib/VersionControlProvider.ts:40-46 - Return type Promise<string> -> Promise<PRCreationResult>
• BitBucketVCSProvider.createPR() at src/lib/providers/bitbucket/BitBucketVCSProvider.ts:111 - Return value
• finish.ts:executeVCSPRWorkflow() at src/commands/finish.ts:1181 - Destructure result

Data Flow: MCP PR comment routing

Entry Point: src/mcp/issue-management-server.ts:435 - create_comment tool handler
Flow Path:

1. Line 441: providerType = type === 'pr' ? 'github' : ... - hardcoded to GitHub
2. Line 442: IssueManagementProviderFactory.create(providerType, settings) - creates GitHub provider
3. Line 443: provider.createComment(...) - uses GitHub gh CLI

After fix:

1. Module-level vcsProvider initialized from settings at startup
2. When type === 'pr' and vcsProvider !== null: route to vcsProvider.createPRComment()
3. When type === 'pr' and vcsProvider === null: fall back to existing GitHub path

Data Flow: Session summary PR comment

Entry Point: src/lib/SessionSummaryService.ts:126 - generateAndPostSummary()
Flow Path:

1. Line 199: calls postSummaryToIssue(input.issueNumber, summary, settings, worktreePath, input.prNumber)
2. Line 408: providerType = prNumber !== undefined ? 'github' : ... - hardcoded to GitHub
3. Line 411: IssueManagementProviderFactory.create(providerType, settings) - GitHub provider
4. Line 421: provider.createComment({...type: 'pr'}) - posts via GitHub

After fix: When prNumber is provided, check if VCS provider is configured; if BitBucket, use VCS provider's createPRComment() instead.

Affected Files

Core changes (from issue):

• src/lib/VersionControlProvider.ts - createPR() return type + 3 new interface methods + createPRComment return type + ReviewComment type definition
• src/lib/providers/bitbucket/BitBucketApiClient.ts:118-119 - Extend request() method union to include PUT; add put<T>() helper; add updatePRComment(), listPRComments(), addInlinePRComment() methods; change addPRComment() to return response
• src/lib/providers/bitbucket/BitBucketVCSProvider.ts:111-164 - Update createPR() return; add updatePRComment(), getReviewComments(), createReviewComment() methods; update createPRComment() return
• src/mcp/issue-management-server.ts:186-190,257-282,327-353,438-464,487-516,1035-1058 - Import VCSProviderFactory; initialize VCS provider at startup; route 4 PR tools through VCS provider with GitHub fallback
• src/commands/finish.ts:1181-1196 - Destructure PRCreationResult; call generateSessionSummaryIfConfigured for new PRs
• docs/iloom-commands.md - VCS provider configuration documentation

Additional changes (discovered in analysis):

• src/lib/SessionSummaryService.ts:398-426 - VCS-aware PR comment routing instead of hardcoded GitHub
• src/mcp/types.ts:32-33,42-43,267 - Remove/update "PRs only exist on GitHub" comments in type docs

Test files:

• src/lib/providers/bitbucket/BitBucketApiClient.test.ts - Tests for 3 new API methods + PUT support
• src/lib/providers/bitbucket/BitBucketVCSProvider.test.ts - Tests for 3 new methods + createPR return type
• src/lib/VCSProviderFactory.test.ts - May need updates if factory interface changes
• src/commands/finish.test.ts - Update mocks for createPR return type
• src/lib/SessionSummaryService.test.ts - Test VCS-aware routing

Integration Points

• BitBucketApiClient is only consumed by BitBucketVCSProvider - safe to change
• VersionControlProvider interface is consumed by: finish.ts, VCSProviderFactory, and will be consumed by MCP server
• SessionSummaryService is consumed by finish.ts and summary.ts command
• MCP create_comment/update_comment tools are consumed by external Claude agents - output schema {id, url} must be maintained

Medium Severity Risks

• No GitHubVCSProvider exists: GitHub VCS uses PRManager (gh CLI wrapper). The new VersionControlProvider methods (updatePRComment, getReviewComments, createReviewComment) need GitHub implementations if the interface is non-optional. Consider making them optional methods (with ?) to avoid requiring GitHub implementation now.
• BitBucket pagination edge case: listPRComments pagination must handle the next field correctly. The pattern exists in getAllWorkspaceMembers() (line 340-357) but PR comments could have higher volume.
• MCP output schema mismatch: get_pr output schema (line 214-255) is GitHub-specific (headRefName, baseRefName, files with additions/deletions). BitBucket's fetchPR() returns a PullRequest type which has different field names (branch/baseBranch). The mapping must produce the same output shape.

[acreeger]

Implementation Plan for Issue #861

Summary

This issue requires completing BitBucket VCS provider integration across 4 subsystems: (1) changing createPR() return type from bare URL string to structured PRCreationResult, (2) adding 3 new API methods to BitBucketApiClient and 3 corresponding methods to BitBucketVCSProvider, (3) updating the VersionControlProvider interface with new optional methods and a return type change on createPRComment, and (4) routing the MCP server's 4 PR-related tools through the VCS provider instead of hardcoding GitHub. Additionally, SessionSummaryService must be updated for VCS-aware PR comment routing.

Questions and Key Decisions

Question	Answer	Rationale
Should new VCS interface methods be required or optional?	Optional (?) on VersionControlProvider	GitHub VCS still uses legacy PRManager/GitHubIssueManagementProvider, so requiring these methods would force creating a GitHubVCSProvider class -- out of scope
How should MCP server route PR ops when VCS provider is null?	Fall back to existing GitHubIssueManagementProvider	VCSProviderFactory.create() returns null for GitHub (line 38-40). The fallback preserves existing behavior.
Should createPRComment return type change from void to {id, url}?	Yes	MCP create_comment(type:pr) needs {id, url} response. BitBucketApiClient.addPRComment() must return API response body instead of void.
How to add PUT support to BitBucketApiClient?	Extend request() method union from 'GET' | 'POST' to 'GET' | 'POST' | 'PUT', add put<T>() helper	Follows existing get<T>()/post<T>() pattern at lines 184-193
How to handle get_pr output shape for BitBucket?	Map BitBucketVCSProvider.fetchPR() PullRequest type to PRResult in the MCP tool handler	PullRequest has branch/baseBranch, PRResult expects headRefName/baseRefName -- simple field mapping

High-Level Execution Phases

1. Interface and Type Changes: Update VersionControlProvider interface -- createPR() return type, createPRComment() return type, add 3 new optional methods, define ReviewComment type
2. API Client Extensions: Add PUT support to BitBucketApiClient, add 3 new API methods (updatePRComment, listPRComments, addInlinePRComment), change addPRComment return type
3. VCS Provider Implementation: Update BitBucketVCSProvider.createPR() return value, add 3 new methods, update createPRComment() return
4. Consumer Updates: Update finish.ts to destructure PRCreationResult and call session summary for new PRs; update SessionSummaryService for VCS-aware routing
5. MCP Server Routing: Initialize VCS provider at startup, route 4 PR tools through it with GitHub fallback
6. Tests: Unit tests for all new/changed methods
7. Documentation: VCS provider configuration section in docs/iloom-commands.md

Quick Stats

• 0 files for deletion
• 9 files to modify (7 source + 2 test files)
• 0 new files to create (all changes go in existing files)
• Dependencies: None
• Estimated complexity: Medium

Potential Risks (HIGH/CRITICAL only)

• MCP get_pr output shape mismatch: BitBucket PullRequest type uses branch/baseBranch while PRResult uses headRefName/baseRefName. The mapping must produce identical output shape. Mitigation: explicit field mapping in MCP tool handler.
• createPRComment return type change is breaking: All implementations of VersionControlProvider must update. Only BitBucketVCSProvider implements it today (GitHub uses legacy path), so impact is contained.

---

Complete Implementation Guide (click to expand for step-by-step details)

Automated Test Cases to Create

Test File: src/lib/providers/bitbucket/BitBucketApiClient.test.ts (MODIFY)

Purpose: Test new API methods (PUT support, updatePRComment, listPRComments, addInlinePRComment) and addPRComment return type change

Click to expand test structure (30 lines)

describe('put method support', () => {
  it('should send PUT requests to BitBucket API', async () => {
    // Mock https.request, verify method is 'PUT'
  })
})

describe('updatePRComment', () => {
  it('should PUT to correct endpoint with content body', async () => {
    // Verify PUT /repositories/{ws}/{repo}/pullrequests/{id}/comments/{commentId}
    // Body: { content: { raw: "text" } }
    // Returns { id, links.html.href }
  })
})

describe('listPRComments', () => {
  it('should GET PR comments with pagination', async () => {
    // Mock paginated response with next URL
    // Verify all pages are fetched
  })
  it('should return all comments including inline and general', async () => {
    // Verify comments with and without inline property
  })
})

describe('addInlinePRComment', () => {
  it('should POST with inline metadata', async () => {
    // Verify body includes inline: { to: line, path: filePath }
    // Returns { id, links.html.href }
  })
})

describe('addPRComment (return type)', () => {
  it('should return comment id and url from response', async () => {
    // Verify it returns { id, links: { html: { href } } } instead of void
  })
})

Test File: src/lib/providers/bitbucket/BitBucketVCSProvider.test.ts (MODIFY)

Purpose: Test new VCS provider methods and createPR return type change

Click to expand test structure (35 lines)

describe('createPR return type', () => {
  it('should return PRCreationResult with url, number, and wasExisting', async () => {
    // Mock client.createPullRequest to return { id: 123, links.html.href: '...' }
    // Verify result is { url, number: 123, wasExisting: false }
  })
})

describe('createPRComment return type', () => {
  it('should return { id, url } from API response', async () => {
    // Mock client.addPRComment to return { id: 456, links: { html: { href: '...' } } }
    // Verify result is { id: '456', url: '...' }
  })
})

describe('updatePRComment', () => {
  it('should delegate to client.updatePRComment and return { id, url }', async () => {
    // Mock client.updatePRComment
    // Verify workspace/repo resolution and delegation
  })
})

describe('getReviewComments', () => {
  it('should call listPRComments and filter for inline comments', async () => {
    // Mock client.listPRComments with mixed inline/general comments
    // Verify only inline comments returned, mapped to ReviewComment
  })
})

describe('createReviewComment', () => {
  it('should delegate to client.addInlinePRComment', async () => {
    // Mock client.addInlinePRComment
    // Verify parameters passed correctly
  })
})

Test File: src/lib/SessionSummaryService.test.ts (MODIFY)

Purpose: Test VCS-aware PR comment routing

it('should use VCS provider for PR comments when BitBucket is configured', async () => {
  // Mock settings with versionControl.provider = 'bitbucket'
  // Verify VCSProviderFactory.create is called
  // Verify provider.createPRComment is called instead of IssueManagementProviderFactory
})

Files to Modify

1. src/lib/VersionControlProvider.ts (lines 4, 46, 61, 69)

Change: Add ReviewComment type, change createPR return type, change createPRComment return type, add 3 new optional methods

• Line 4: Add no new imports needed (ReviewComment defined locally)
• After line 21 (after ExistingPR): Add ReviewComment interface matching ReviewCommentResult shape from src/mcp/types.ts:53-64
• Line 46: Change createPR(...) return type from Promise<string> to Promise<PRCreationResult>
• Line 53: Change createDraftPR?(...) return type from Promise<string> to Promise<PRCreationResult>
• Line 61: Change createPRComment(...) return type from Promise<void> to Promise<{ id: string; url: string }>
• After line 61: Add 3 new optional methods:

updatePRComment?(prNumber: number, commentId: string, body: string, cwd?: string): Promise<{ id: string; url: string }>
getReviewComments?(prNumber: number, cwd?: string): Promise<ReviewComment[]>
createReviewComment?(prNumber: number, path: string, line: number, body: string, cwd?: string): Promise<{ id: string; url: string }>

2. src/lib/providers/bitbucket/BitBucketApiClient.ts (lines 118-119, 191-193, 286-300)

Change: Add PUT support, add 3 new methods, change addPRComment return type

• Line 119: Extend method union to 'GET' | 'POST' | 'PUT'
• After line 193: Add private async put<T>(endpoint: string, body: unknown): Promise<T> helper
• Add BitBucketComment interface near existing interfaces (after line 89):

export interface BitBucketComment {
  id: number
  content: { raw: string }
  inline?: { from: number | null; to: number | null; path: string }
  links: { html: { href: string } }
  user?: { display_name: string; uuid: string }
  created_on?: string
  updated_on?: string
}

• Lines 286-300: Change addPRComment return type from Promise<void> to Promise<BitBucketComment>, return the POST response instead of discarding it
• After line 300: Add updatePRComment() method -- PUT to /repositories/{ws}/{repo}/pullrequests/{prId}/comments/{commentId} with { content: { raw } }
• After updatePRComment: Add listPRComments() method -- paginated GET following getAllWorkspaceMembers pattern at lines 340-357
• After listPRComments: Add addInlinePRComment() method -- POST with inline: { to: line, path: filePath } in body

3. src/lib/providers/bitbucket/BitBucketVCSProvider.ts (lines 4, 117, 163, 189-195)

Change: Update createPR return, update createPRComment return, add 3 new methods

• Line 4: Import PRCreationResult and ReviewComment from ../../VersionControlProvider.js
• Line 117: Change return type from Promise<string> to Promise<PRCreationResult>
• Line 163: Change return pr.links.html.href to return { url: pr.links.html.href, number: pr.id, wasExisting: false }
• Lines 189-195: Change createPRComment return type from Promise<void> to Promise<{ id: string; url: string }>, return mapped response from client.addPRComment
• After line 195: Add updatePRComment(), getReviewComments(), createReviewComment() methods
• Each follows existing pattern: getWorkspaceAndRepo(cwd) then delegate to client
• getReviewComments calls client.listPRComments(), filters for comments with inline property, maps to ReviewComment[]

4. src/lib/providers/bitbucket/index.ts (line 2)

Change: Export new BitBucketComment type from BitBucketApiClient

5. src/commands/finish.ts (lines 1181-1196)

Change: Destructure PRCreationResult from createPR, call session summary for new PRs

• Line 1181: Change const prUrl = await vcsProvider.createPR(...) to const prResult = await vcsProvider.createPR(...)
• Line 1189: Change prUrl to prResult.url
• Line 1190: Change finishResult.prUrl = prUrl to finishResult.prUrl = prResult.url
• After line 1195 (after the operations.push): Add await this.generateSessionSummaryIfConfigured(parsed, worktree, options, prResult.number)

6. src/lib/SessionSummaryService.ts (lines 398-426)

Change: VCS-aware PR comment routing

• Add import: VCSProviderFactory from ./VCSProviderFactory.js
• Lines 406-411: When prNumber is provided, check if VCS provider is configured via VCSProviderFactory.create(settings). If non-null, use vcsProvider.createPRComment(). Fall back to existing GitHub path when null.

Click to expand pseudocode for SessionSummaryService change (15 lines)

// In postSummaryToIssue, replace lines 406-425:
const finalSummary = await this.applyAttributionWithSettings(summary, settings, worktreePath)
const targetNumber = prNumber ?? issueNumber
const targetType = prNumber !== undefined ? 'pr' : 'issue'

if (prNumber !== undefined) {
  // Try VCS provider first for PR comments
  const vcsProvider = VCSProviderFactory.create(settings)
  if (vcsProvider) {
    await vcsProvider.createPRComment(prNumber, finalSummary)
    return
  }
  // Fall through to issue management provider (GitHub)
}

const providerType = prNumber !== undefined
  ? 'github'
  : (settings.issueManagement?.provider ?? 'github') as IssueProvider
const provider = IssueManagementProviderFactory.create(providerType, settings)
await provider.createComment({ number: String(targetNumber), body: finalSummary, type: targetType })

7. src/mcp/issue-management-server.ts (lines 36, 186-192, 257-282, 327-353, 438-464, 487-516, 1056-1059)

Change: Initialize VCS provider at startup, route 4 PR tools through it

• After line 36 (let settings): Add let vcsProvider: VersionControlProvider | null = null
• Add imports: VCSProviderFactory, VersionControlProvider, ReviewComment
• Lines 186-192: Remove/update "PRs only exist on GitHub" comments and description text
• After line 1058 (settings = await settingsManager.loadSettings()): Initialize VCS provider with try/catch

Tool routing changes (each tool handler gets an early-return branch when vcsProvider is available):

a) get_pr handler (line 257-282): When vcsProvider, call vcsProvider.fetchPR(parseInt(number)), map to PRResult (headRefName = pr.branch, baseRefName = pr.baseBranch). Else fall through to existing path.

b) get_review_comments handler (line 327-353): When vcsProvider?.getReviewComments, call it. Map ReviewComment[] to output shape. Else fall through to existing path.

c) create_comment(type:pr) handler (line 438-464): When type === 'pr' and vcsProvider, call vcsProvider.createPRComment(parseInt(number), sanitizedBody), return mapped result. Else fall through to existing path.

d) update_comment(type:pr) handler (line 487-516): When type === 'pr' and vcsProvider?.updatePRComment, call it, return mapped result. Else fall through to existing path.

e) Remove all "PRs only exist on GitHub" comments in the file.

8. src/mcp/types.ts (lines 32-33, 42-43, 266)

Change: Remove "PRs only exist on GitHub" comments from doc comments on GetPRInput, GetReviewCommentsInput, and PRResult

9. docs/iloom-commands.md (after line 2066)

Change: Add VCS provider configuration section

Click to expand documentation content (45 lines)

**Version Control (VCS) Provider Settings:**

iloom supports multiple version control providers for PR operations. By default, GitHub is used via the `gh` CLI. For BitBucket Cloud, configure the following in `.iloom/settings.json`:

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `versionControl.provider` | `"github"` \| `"bitbucket"` | `"github"` | VCS provider for PR operations |
| `versionControl.bitbucket.username` | string | (required) | BitBucket username |
| `versionControl.bitbucket.apiToken` | string | (required) | BitBucket API token (store in `settings.local.json`) |
| `versionControl.bitbucket.workspace` | string | (auto-detected) | BitBucket workspace slug |
| `versionControl.bitbucket.repoSlug` | string | (auto-detected) | Repository slug |
| `versionControl.bitbucket.reviewers` | string[] | - | Usernames to add as PR reviewers |

**Example Configuration:**

`.iloom/settings.json`:
```json
{
  "versionControl": {
    "provider": "bitbucket",
    "bitbucket": {
      "username": "your-username",
      "workspace": "your-workspace",
      "reviewers": ["reviewer1", "reviewer2"]
    }
  }
}

.iloom/settings.local.json (gitignored):

{
  "versionControl": {
    "bitbucket": {
      "apiToken": "your-api-token"
    }
  }
}

Supported Provider Combinations:

• GitHub Issues + GitHub VCS (default)
• GitHub Issues + BitBucket VCS
• Linear Issues + BitBucket VCS
• Jira Issues + BitBucket VCS

Note: Draft PR mode (mergeBehavior.mode: "draft-pr") is GitHub-only. BitBucket does not support draft pull requests.

</details>

## Detailed Execution Order

### Phase 1 (parallel): Interface, API Client, and Types

#### Step 1a: Update VersionControlProvider interface and types
**Files:** `src/lib/VersionControlProvider.ts`, `src/mcp/types.ts`
**Contract:** `ReviewComment = { id: string, body: string, path: string, line: number | null, side: string | null, author: { id: string, displayName: string } | null, createdAt: string, updatedAt: string | null, inReplyToId: string | null }`, `PRCreationResult` (already exists at line 9-13)

1. Add `ReviewComment` interface after `ExistingPR` -> Verify: interface compiles
2. Change `createPR()` return type at line 46 -> Verify: type is `Promise<PRCreationResult>`
3. Change `createDraftPR?()` return type at line 53 -> Verify: type matches
4. Change `createPRComment()` return type at line 61 -> Verify: `Promise<{ id: string; url: string }>`
5. Add 3 optional methods -> Verify: interface has 6+ methods in PR section
6. Update `src/mcp/types.ts` comments (lines 32, 42, 266) -> Verify: no "PRs only exist on GitHub" text

#### Step 1b: Extend BitBucketApiClient with PUT and new methods
**Files:** `src/lib/providers/bitbucket/BitBucketApiClient.ts`, `src/lib/providers/bitbucket/BitBucketApiClient.test.ts`, `src/lib/providers/bitbucket/index.ts`
**Contract:** `BitBucketComment` interface as defined above

1. Add `BitBucketComment` interface -> Verify: type exported
2. Extend `request()` method union at line 119 -> Verify: accepts `'PUT'`
3. Add `put<T>()` helper -> Verify: delegates to `request('PUT', ...)`
4. Change `addPRComment` return from void to `BitBucketComment` -> Verify: returns response body
5. Add `updatePRComment()` -> Verify: PUT to correct endpoint
6. Add `listPRComments()` with pagination -> Verify: follows `getAllWorkspaceMembers` pattern
7. Add `addInlinePRComment()` -> Verify: POST with inline metadata
8. Export `BitBucketComment` from `index.ts`
9. Add tests -> Verify: `pnpm test -- src/lib/providers/bitbucket/BitBucketApiClient.test.ts`

### Phase 2 (parallel): Provider Implementation and Consumer Updates

#### Step 2a: Update BitBucketVCSProvider
**Files:** `src/lib/providers/bitbucket/BitBucketVCSProvider.ts`, `src/lib/providers/bitbucket/BitBucketVCSProvider.test.ts`

1. Update imports for `PRCreationResult`, `ReviewComment`
2. Change `createPR()` return at lines 117/163 -> Verify: returns `PRCreationResult`
3. Change `createPRComment()` return at lines 189-195 -> Verify: returns `{ id, url }`
4. Add `updatePRComment()` -> Verify: delegates to client
5. Add `getReviewComments()` -> Verify: filters inline comments, maps to `ReviewComment[]`
6. Add `createReviewComment()` -> Verify: delegates to client
7. Update test mock client with new methods
8. Add tests -> Verify: `pnpm test -- src/lib/providers/bitbucket/BitBucketVCSProvider.test.ts`

#### Step 2b: Update finish.ts and SessionSummaryService
**Files:** `src/commands/finish.ts`, `src/lib/SessionSummaryService.ts`

1. Update `finish.ts:1181` to destructure `PRCreationResult` -> Verify: `prResult.url`, `prResult.number` used
2. Update lines 1189-1190 -> Verify: uses `prResult.url`
3. Add `generateSessionSummaryIfConfigured` call after line 1195 -> Verify: called with `prResult.number`
4. Add `VCSProviderFactory` import to `SessionSummaryService.ts`
5. Update `postSummaryToIssue()` for VCS-aware routing -> Verify: BitBucket uses VCS provider, GitHub falls back
6. Verify: `pnpm compile`

### Phase 3 (sequential): MCP Server Routing

#### Step 3: Route MCP PR operations through VCS provider
**Files:** `src/mcp/issue-management-server.ts`

1. Add imports for `VCSProviderFactory`, `VersionControlProvider`
2. Add module-level `vcsProvider` variable
3. Initialize in `main()` after settings load
4. Route `get_pr` handler -> Verify: BitBucket uses `fetchPR`, GitHub falls back
5. Route `get_review_comments` handler -> Verify: BitBucket uses `getReviewComments`, GitHub falls back
6. Route `create_comment(type:pr)` handler -> Verify: BitBucket uses `createPRComment`, GitHub falls back
7. Route `update_comment(type:pr)` handler -> Verify: BitBucket uses `updatePRComment`, GitHub falls back
8. Remove "PRs only exist on GitHub" comments
9. Verify: `pnpm compile`

### Phase 4 (sequential): Documentation and Final Verification

#### Step 4: Documentation and build verification
**Files:** `docs/iloom-commands.md`

1. Add VCS provider configuration section after Jira settings section
2. Run `pnpm build`
3. Run `pnpm test`

## Execution Plan

1. Run Steps 1a, 1b in parallel
   • Step 1a: VersionControlProvider interface + types.ts comment cleanup
   • Step 1b: BitBucketApiClient PUT support + 3 new methods + tests
     Contract: ReviewComment interface, PRCreationResult (existing), BitBucketComment interface
2. Run Steps 2a, 2b in parallel (both depend on Phase 1)
   • Step 2a: BitBucketVCSProvider new methods + tests
   • Step 2b: finish.ts PRCreationResult handling + SessionSummaryService VCS routing
3. Run Step 3 (sequential -- depends on Phase 2, modifies MCP server)
   • MCP server VCS provider initialization and PR tool routing
4. Run Step 4 (sequential -- final verification)
   • Documentation + pnpm build + pnpm test

## Dependencies and Configuration

None -- no new packages required.

</details>

[acreeger]

Implementation Complete

Summary

Completed BitBucket VCS provider integration across 8 files, adding PR comment CRUD operations, review comment support, proper PRCreationResult typing, MCP server routing, and SessionSummaryService VCS awareness. All changes include comprehensive test coverage.

Changes Made

• src/lib/VersionControlProvider.ts: Added ReviewComment interface, changed createPR() to return PRCreationResult, changed createPRComment() to return {id, url}, added 3 optional methods
• src/mcp/types.ts: Removed 3 "PRs only exist on GitHub" comments
• src/lib/providers/bitbucket/BitBucketApiClient.ts: Added PUT support, updatePRComment(), listPRComments(), addInlinePRComment(), BitBucketComment interface
• src/lib/providers/bitbucket/BitBucketVCSProvider.ts: Updated createPR() and createPRComment() return types, added updatePRComment(), getReviewComments(), createReviewComment()
• src/lib/providers/bitbucket/index.ts: Added BitBucketComment export
• src/commands/finish.ts: Uses PRCreationResult, generates session summary for new PRs
• src/lib/SessionSummaryService.ts: Routes PR comments through VCS provider when available
• src/mcp/issue-management-server.ts: Loads VCS provider at startup, routes all PR operations through it
• docs/iloom-commands.md: Added VCS provider configuration section

Validation Results

• ✅ Tests: 4631 passed / 4631 total (1 skipped)
• ✅ Typecheck: Passed
• ✅ Lint: Passed (0 warnings)
• ✅ Build: Passed (all 3 targets)