feat(agent): complete Linear project-milestone matching adapter

[jsdevninja]

Summary

• Complete the Linear backend for auto-project/milestone matching (feat(agent): Linear adapter for project/milestone matching #3186): list workspace projectMilestones for fuzzy fallback when Linear's GitHub integration has not already linked the PR, while still preferring attachmentsForURL native links.
• Add GitHubCompositeProjectTrackerAdapter + createProjectTrackerAdapter factory, probeLinearWorkspaceAccess diagnostics helper, and fail-open degradation for Linear list API outages (mirrors the GitHub path).
• Expand unit coverage: native-link partial matches, milestone fuzzy fallback, pagination/page-limit caps, composite attach delegation, and webhook-level linear-backend gating.

Closes #3186

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck (after npm ci)
• npm run test:coverage on focused linear/project-tracker suites — src/integrations/linear-adapter.ts at 100% lines/branches; project-tracker-adapter.ts patch arms covered including composite attach delegation
• npm run test:workers (not run locally)
• npm run build:mcp
• npm run test:mcp-pack (not run locally)
• npm run ui:openapi:check (no API schema changes)
• npm run ui:lint (no UI changes)
• npm run ui:typecheck (no UI changes)
• npm run ui:build (no UI changes)
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Full npm run test:ci not run end-to-end locally (wrangler missing for cf-typegen:check in this environment). CI validate is the authoritative gate.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

N/A — agent integration layer only; no visible UI.

Notes

• Builds on the initial Linear backend landed in feat(agent): add Linear backend for project/milestone matching #3290; this PR closes the remaining milestone-equivalent fuzzy path and hardens fail-open behavior so Linear outages degrade to a missed suggestion instead of a webhook error.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-10 10:54:09 UTC}

8 files · 1 AI reviewer · no blockers · readiness 100/100 · CI failing · blocked

🛑 Suggested Action - Fix Blockers

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/auth/rate-limit.ts (matched src/auth/**).

Review summary
This PR completes the Linear backend by implementing `listOpenMilestones` with the same cursor-pagination pattern used by `listOpenProjects`, adds a `GitHubCompositeProjectTrackerAdapter` + `createProjectTrackerAdapter` factory, and switches the linear fallback path in `resolveTrackerMatches` to fail-open independently on both the projects and milestones list calls, mirroring the existing GitHub pattern. The tests exercise real code paths (pagination cursors, empty-key short-circuit, HTTP/GraphQL error propagation, native-link preference over fuzzy fallback) rather than fabricating impossible states, and the composite adapter's delegation is directly verified. The main open question is that `probeLinearWorkspaceAccess` and `createProjectTrackerAdapter` are added and tested but no call site is visible in the diff (`resolveTrackerMatches` still hand-instantiates `new LinearAdapter()`/`new GitHubCompositeProjectTrackerAdapter()` rather than using the factory), so their production wiring can't be confirmed from what's shown.

Nits — 6 non-blocking

• `createProjectTrackerAdapter` (src/integrations/project-tracker-adapter.ts) is defined and tested but `resolveTrackerMatches` still constructs `new LinearAdapter()`/`new GitHubCompositeProjectTrackerAdapter()` directly in the visible diff — confirm the factory is actually wired into a real call site, or note it as forward-looking API for a follow-up.
• `probeLinearWorkspaceAccess` (src/integrations/linear-adapter.ts) is described as a 'maintainer diagnostics' helper but no caller is visible in this diff — confirm it's reachable from an actual admin/diagnostics surface rather than being exported-but-unused.
• `listOpenMilestones`'s GraphQL query (src/integrations/linear-adapter.ts) filters only `includeArchived: false`, unlike `listOpenProjects` which filters by `LINEAR_OPEN_PROJECT_STATUS_TYPES` — worth a one-line comment confirming Linear's `ProjectMilestone` type has no open/completed distinction to filter on, so the method name 'listOpenMilestones' doesn't overpromise.
• project-tracker-adapter.ts is now ~403 lines, just over the repo's own 400-line size-smell threshold — consider whether `GitHubCompositeProjectTrackerAdapter` belongs in a separate file.
• Magic issue-number references (`feat(agent): Linear adapter for project/milestone matching #3186`) are repeated across new doc comments in both files; a shared constant or single canonical reference would avoid drift if the issue number is ever wrong in one spot.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

CI checks failing

• codecov/patch — 97.36% of diff hit (target 99.00%)

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#3186
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 241 registered-repo PR(s), 152 merged, 40 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jsdevninja; Gittensor profile; 241 PR(s), 40 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: jsdevninja
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 241 PR(s), 40 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[JSONbored]

Please, also get this wired up:

The main open question is that `probeLinearWorkspaceAccess` and `createProjectTrackerAdapter` are added and tested but no call site is visible in the diff (`resolveTrackerMatches` still hand-instantiates `new LinearAdapter()`/`new GitHubCompositeProjectTrackerAdapter()` rather than using the factory), so their production wiring can't be confirmed from what's shown.

I'll leave the PR open so you can do this (out of scope of the original issue) but this feature is pointless if not wired up everywhere it should be.

[codecov]

Codecov Report

❌ Patch coverage is 97.36842% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.13%. Comparing base (eecc228) to head (0c26c08).

Files with missing lines	Patch %	Lines
src/api/routes.ts	87.50%	0 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (97.36%) is below the target coverage (99.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4642   +/-   ##
=======================================
  Coverage   94.13%   94.13%           
=======================================
  Files         434      434           
  Lines       38554    38583   +29     
  Branches    14053    14059    +6     
=======================================
+ Hits        36291    36319   +28     
  Misses       1604     1604           
- Partials      659      660    +1     

Files with missing lines	Coverage Δ
src/auth/rate-limit.ts	98.83% <ø> (ø)
src/integrations/linear-adapter.ts	100.00% <100.00%> (ø)
src/integrations/project-tracker-adapter.ts	100.00% <100.00%> (ø)
src/api/routes.ts	94.24% <87.50%> (-0.03%)	⬇️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (codecov/patch)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (codecov/patch)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.

[jsdevninja]

Rebased on latest main and pushed codecov fix: workspace-probe route test now seeds a registered repo so repo?.installationId is covered. Factory wiring (resolveProjectTrackerMatches -> createProjectTrackerAdapter) and probe route were already in the prior fix commit.