Enhancement: work item discovery tool — scan GitHub and Azure DevOps for issues and upsert as work-item entities

[JoshuaRowePhantom]

Summary

There is currently no tool that discovers work items (GitHub issues, Azure DevOps work items) and upserts them as work-item entities in the workspace store. This tool is the data-supply side of the pull-requests/work-items views.

---

Design

GitHub Work Item Discovery

Tool type: "github-work-item-discovery"
File: Tools/GitHub/GitHubWorkItemDiscoveryTool.cs

Behaviour:

1. For each github-repository entity in the store, call GET /repos/{owner}/{repo}/issues?state=all&per_page=100 (pagination via Link header)
2. For each issue returned:
   • Skip if pull_request key is present (those are PRs, not issues)
   • Map fields: number, title, state → status (open/closed), labels[].name → labels[], linked commit SHAs from timeline events → related-commits[], html_url → urls.default
   • Upsert a github-work-item entity using WorkspaceToolEntityUtilities.UpsertEntityByPrimaryNameAsync
   • Naming: ["github", <owner>, <repo>, "work-items", <number>]
   • If a related github-pull-request entity exists in the store (via the timeline cross-referenced events), also create a related relationship between the work item and that PR entity
3. Write a tool-execution-result entity summarising: repositories scanned, issues found, entities created/updated.

Auth: Uses GitHubTokenResolver (shared with GitHubPullRequestDiscoveryTool).

---

Azure DevOps Work Item Discovery

Tool type: "azure-devops-work-item-discovery"
File: Tools/AzureDevOps/AzureDevOpsWorkItemDiscoveryTool.cs

Behaviour:

1. For each azure-devops-project entity in the store, run a WIQL query: SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project ORDER BY [System.ChangedDate] DESC
2. Batch-fetch work item details via POST /_apis/wit/workitemsbatch
3. Map fields:
   • System.Title → title
   • System.State → status (Active/In Progress → in-progress; New/To Do → open; Done/Resolved/Closed → closed)
   • System.Tags → labels[] (split on ;)
   • relations[].url where rel = ArtifactLink/Git.Commit → related-commits[] (extract SHA from artifact URI)
   • _links.html.href → urls.default
4. Upsert as azure-devops-work-item entities.
5. Update the existing AzureDevOpsWorkItemDiscoveryTool rather than creating a separate one (same tool, extended field mapping).

---

Tool Relationship Schema

Both tools need a tool-relationship entity that configures:

• Which repositories/projects to scan
• Poll frequency (suggested default: every 15 minutes)
• Max items per repository (default: 200)

---

Tests

GitHubWorkItemDiscoveryTool_MapsIssueFieldsToWorkItemEntity

• Mock GitHub API returning one issue with labels, state=open
• Assert entity has correct status, labels, urls.default, naming convention

GitHubWorkItemDiscoveryTool_SkipsIssuesThatArePullRequests

• Mock API returning issue with pull_request key present
• Assert no github-work-item entity upserted

GitHubWorkItemDiscoveryTool_WritesRelatedRelationship_WhenLinkedPrEntityExists

• Mock cross-referenced timeline event pointing to a PR entity already in store
• Assert related relationship entity created between issue and PR

AzureDevOpsWorkItemDiscoveryTool_MapsTagsToLabels

• ADO work item with System.Tags = "bug;performance"
• Assert labels = ["bug", "performance"]

AzureDevOpsWorkItemDiscoveryTool_MapsGitCommitLinksToRelatedCommits

• ADO work item with artifact link vstfs:///Git/Commit/<project-id>/<repo-id>/<sha>
• Assert related-commits = ["<sha>"]

[JoshuaRowePhantom]

Design

Branch: feat/work-item-discovery-214 | Worktree: worktrees/3

Approach

Two new tools following the existing IWorkspaceTool pattern:

GitHubWorkItemDiscoveryTool (Tools/GitHub/GitHubWorkItemDiscoveryTool.cs)

• Tool type: github-work-item-discovery
• Reads participants with entity-types containing git-repository and urls.default matching https://github.com/
• Calls gh issue list via ProcessRunner.RunAndLogAsync (cmd.exe /c gh on Windows)
• Skips items where pull_request key is present
• Upserts git-work-item entities (types: entity, work-item, git-work-item, external)
• Naming: ["github", owner, repo, "work-items", number]
• Fields: title, status (OPEN->open, CLOSED->closed), labels[], urls.default
• Creates related relationship entities when cross-referenced PR entities exist in store

AzureDevOpsWorkItemDiscoveryTool (Tools/AzureDevOps/AzureDevOpsWorkItemDiscoveryTool.cs)

• Tool type: azure-devops-work-item-discovery
• Reads participants with entity-types containing azure-devops-project; extracts org/project from urls.default
• WIQL POST -> batch work items POST via injected HTTP poster (injectable for tests)
• Maps System.State -> status, System.Tags -> labels (split on ;), artifact links -> related-commits (SHA from vstfs URI)
• Upserts azure-devops-work-item entities (types: entity, work-item, azure-devops-work-item, external)
• Naming: ["azure-devops", org, project, "work-items", id]
• Auth: PAT from AZURE_DEVOPS_TOKEN env var or personal-access-token property on tool entity

Schema choices

• git-work-item and azure-devops-work-item entity types already defined (Enhancement: define platform-agnostic base entity schemas for organization, repository, work-item, and pull-request #211)

Files changing

• New: Phantom.Workspaces/Tools/GitHub/GitHubWorkItemDiscoveryTool.cs
• New: Phantom.Workspaces/Tools/AzureDevOps/AzureDevOpsWorkItemDiscoveryTool.cs
• New: Phantom.Workspaces.Tools.Tests/GitHubWorkItemDiscoveryToolTests.cs
• New: Phantom.Workspaces.Tools.Tests/AzureDevOpsWorkItemDiscoveryToolTests.cs
• New: Phantom.Workspaces.Data.Core/JsonEntities/defaults/tools/github-work-item-discovery-tool.json
• New: Phantom.Workspaces.Data.Core/JsonEntities/defaults/tools/azure-devops-work-item-discovery-tool.json
• Edit: Phantom.Workspaces/ViewModels/MainWindowViewModel.cs -- register both tools

[JoshuaRowePhantom]

Tests

GitHubWorkItemDiscoveryToolTests.cs (Phantom.Workspaces.Tools.Tests)

1. GitHubWorkItemDiscoveryTool_MapsIssueFieldsToWorkItemEntity

   • One git-repository participant with GitHub URL
   • Mock runner returns one open issue with labels
   • Assert git-work-item entity created with correct status=open, labels, urls.default, naming convention

2. GitHubWorkItemDiscoveryTool_SkipsIssuesThatArePullRequests

   • Mock runner returns JSON with pull_request key present
   • Assert no git-work-item entity upserted

3. GitHubWorkItemDiscoveryTool_WritesRelatedRelationship_WhenLinkedPrEntityExists

   • Pre-seed a git-pull-request entity in store named ["github", "owner", "repo", "pull-requests", "42"]
   • Mock issue list runner returns issue Bump actions/checkout from 4 to 7 #1; mock timeline runner returns cross-reference event to PR Steering text appears before streaming output it was injected after #42
   • Assert related relationship entity created linking work item to PR

4. GitHubWorkItemDiscoveryTool_ClosedIssue_MapsToClosedStatus

   • Mock runner returns closed issue
   • Assert status = closed

5. GitHubWorkItemDiscoveryTool_UpsertIsIdempotent_DoesNotDuplicateEntity

   • Run tool twice with same mock data
   • Assert only one entity with that name

AzureDevOpsWorkItemDiscoveryToolTests.cs (Phantom.Workspaces.Tools.Tests)

6. AzureDevOpsWorkItemDiscoveryTool_MapsTagsToLabels

   • ADO work item with System.Tags = "bug;performance"
   • Assert labels = ["bug", "performance"]

7. AzureDevOpsWorkItemDiscoveryTool_MapsGitCommitLinksToRelatedCommits

   • ADO work item with artifact link vstfs:///Git/Commit///
   • Assert related-commits = [""]

[JoshuaRowePhantom]

Verification passed

Checked: Commit b6daf22 (Fix #214) on the features branch. Files inspected:

• Phantom.Workspaces/Tools/GitHub/GitHubWorkItemDiscoveryTool.cs
• Phantom.Workspaces/Tools/AzureDevOps/AzureDevOpsWorkItemDiscoveryTool.cs
• Phantom.Workspaces.Tools.Tests/GitHubWorkItemDiscoveryToolTests.cs
• Phantom.Workspaces.Tools.Tests/AzureDevOpsWorkItemDiscoveryToolTests.cs
• Phantom.Workspaces.Data.Core/JsonEntities/defaults/tools/github-work-item-discovery-tool.json
• Phantom.Workspaces.Data.Core/JsonEntities/defaults/tools/azure-devops-work-item-discovery-tool.json
• Phantom.Workspaces/ViewModels/MainWindowViewModel.cs (tool registration at lines 569-570)

Result: Implementation found, all verification criteria satisfied, tests present.

• GitHubWorkItemDiscoveryTool: tool type github-work-item-discovery, skips PRs, maps number/title/state/labels/url to git-work-item entities named ["github", owner, repo, "work-items", number], creates related relationship when cross-referenced PR entity exists, uses gh issue list via ProcessRunner.
• AzureDevOpsWorkItemDiscoveryTool: tool type azure-devops-work-item-discovery, WIQL + batch-fetch, maps System.State->status, System.Tags->labels, ArtifactLink vstfs URIs->related-commits, upserts azure-devops-work-item entities named ["azure-devops", org, project, "work-items", id], auth via PAT env var or tool property.
• 5 GitHub and 3 Azure DevOps tests cover all described cases. No skipped, disabled, or timing-dependent tests. No unresolved TODOs.