provider-context-plan.md

Provider Context Plan

This document organizes Stage 3 provider-context work before implementation-heavy adapters begin.

Provider context means optional pull request, changed-file, check-run, CI artifact, and summary metadata that can enrich local Maven findings. It must remain additive: the local analyzer continues to work from local Maven report artifacts without network access or provider tokens.

Use this plan with the project visual map, v0.3.0 release acceptance checklist, integration scope, and roadmap.

Readiness Gates

Stage 3 provider-context work starts after these gates are available:

• #79 Stage 3 readiness gate
• #100 v0.3.0 release acceptance checklist
• #101 visual dependency map
• #102 post-gate label review

Implementation-heavy issues remain blocked until their related design contracts, fixtures, and mocks land.

Design Contract Order

The first ready Stage 3 lane is design and validation, not live provider implementation.

Recommended order:

1. #84 Provider adapter package boundaries and #85 provider fixture and mock contract
2. #83 provider error and offline fallback taxonomy and #86 GitHub token and permission matrix
3. #87 changed-files fixture contract and #89 check-runs fixture contract
4. #90 PR context JSON extension contract, #88 Markdown PR summary content contract, and #91 why, explain, and ci command UX boundaries
5. #93 CI artifact directory fixture layout, #92 GitLab parity boundary, and #94 agent evidence bundle schema

Implementation Issues That Stay Blocked

The following issues should not start until the relevant design contract is merged or explicitly waived by a maintainer:

• #21 GitHub changed files adapter
• #22 GitHub adapter interface
• #23 GitHub check runs adapter
• #24 baseline comparison model
• #25 PR-to-module relevance scoring
• #26 confidence model v2
• #27 prmaven explain command
• #28 prmaven ci command
• #29 Markdown PR summary output
• #34 agent evidence bundle output
• #36 CI artifact directory option

Contributor Slicing Rules

Each provider-context contribution should:

• change one contract, fixture shape, or documented boundary at a time;
• preserve local report-only behavior;
• avoid live API calls in default tests;
• prefer sanitized fixtures and fake clients over real provider data;
• document permission and offline behavior before adding token-aware code;
• keep JSON additions additive and compatible with existing consumers.

Label Expectations

Every provider-context issue should keep:

• one stage:* label;
• at least one area:* label;
• exactly one current status:* label;
• at least one contributor-fit label such as help wanted, need help, good first contribution, oss first friendly, or agent-friendly.

Ready design issues signal that contributors may start drafting contracts. Blocked implementation issues signal that the repo is still waiting for the prerequisite contract, fixture, or mock design.

Detailed package-boundary guidance lives in Provider Adapter Package Boundaries. Fixture and fake-client guidance lives in Provider Fixtures And Mocks. Provider failure behavior lives in Provider Errors And Offline Fallbacks. GitHub read-token expectations live in GitHub Provider Permissions. Changed-file fixture expectations live in Changed-Files Fixture Contract. Check-run fixture expectations live in Check-Runs Fixture Contract. PR context JSON extension expectations live in PR Context JSON Extension Contract. Markdown PR summary expectations live in Markdown PR Summary Contract. Command UX boundaries live in Command UX Boundaries.