jobtrackingapp/.gsd/milestones/M001/slices/S01/tasks/T01-PLAN.md

estimated_steps, estimated_files, skills_used

estimated_steps	estimated_files	skills_used
4	3	best-practices test

T01: Add a job-aware Gmail matching contract and backend ranking tests

Slice: S01 — Smarter Gmail import and matching Milestone: M001

Description

Build the backend contract that makes Gmail import job-aware. The executor should keep the existing OAuth flow, but add a new job-scoped candidate discovery path that uses the actual JobApplication, Company, recruiter, and existing correspondence data to rank likely Gmail messages/threads for one job. This task closes the main risk in R002 and anchors the import loop on the imported job from R001 instead of a generic inbox search.

Steps

1. Inspect the current Gmail controller/service contract and define a job-scoped candidate response shape in JobTrackerApi/Controllers/GmailController.cs that includes ranked thread/message suggestions, match reasons, confidence or score inputs, and already-imported state.
2. Implement the backend matching flow in JobTrackerApi/Controllers/GmailController.cs and JobTrackerApi/Services/GmailOAuthService.cs: load the owned job with company context, derive multiple Gmail queries from recruiter/company/title/correspondence signals, fetch/dedupe results, group by thread, and rank them server-side.
3. Preserve the existing generic Gmail endpoints, but make the new job-aware endpoint the primary contract for this slice so the UI can consume it without recreating ranking heuristics in the browser.
4. Expand JobTrackerApi.Tests/GmailControllerTests.cs to cover owned-job lookup, empty/duplicate behavior, and ranked candidate output with explicit reasons instead of only the current missing-message-ids case.

Must-Haves

• The new backend contract is scoped to one owned JobApplication and never bypasses the EF ownership filters already enforced in Data/JobTrackerContext.cs.
• Ranked candidates include enough detail for the UI to explain why a message or thread was suggested and whether it was already imported.
• Tests assert the new contract and failure/duplicate cases, not just the happy path.

Verification

• dotnet test JobTrackerApi.Tests/JobTrackerApi.Tests.csproj --filter GmailControllerTests
• Confirm the updated tests cover job-scoped matching, duplicate flags, and invalid or missing job inputs.

Observability Impact

• Signals added/changed: per-candidate match reasons/score inputs and explicit already-imported flags in the job-scoped Gmail response.
• How a future agent inspects this: hit the job-aware Gmail endpoint in JobTrackerApi/Controllers/GmailController.cs or read the focused assertions in JobTrackerApi.Tests/GmailControllerTests.cs.
• Failure state exposed: the response or tests should make it obvious whether failure came from job lookup, Gmail candidate retrieval, or ranking/dedupe.

Inputs

• JobTrackerApi/Controllers/GmailController.cs — existing Gmail API surface and import behavior.
• JobTrackerApi/Services/GmailOAuthService.cs — existing Gmail list/detail retrieval and current N+1 summary hydration.
• JobTrackerApi.Tests/GmailControllerTests.cs — current minimal Gmail controller test coverage.

Expected Output

• JobTrackerApi/Controllers/GmailController.cs — adds the job-scoped Gmail matching endpoint and ranking contract.
• JobTrackerApi/Services/GmailOAuthService.cs — supports the new candidate discovery flow.
• JobTrackerApi.Tests/GmailControllerTests.cs — proves the new backend matching behavior and duplicate/failure paths.