From 1a7f4a11d502b32e5f351f4a4cde088e3ddd7e2d Mon Sep 17 00:00:00 2001 From: Will-thom <116388885+Will-thom@users.noreply.github.com> Date: Tue, 9 Jun 2026 22:44:18 -0300 Subject: [PATCH] docs: add provider context planning map --- .github/backlog/ISSUES.md | 2 +- ROADMAP.md | 2 ++ docs/integrations.md | 2 ++ docs/project-visual-map.md | 1 + docs/provider-context-plan.md | 68 +++++++++++++++++++++++++++++++++++ 5 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 docs/provider-context-plan.md diff --git a/.github/backlog/ISSUES.md b/.github/backlog/ISSUES.md index bbec37d..e349aa5 100644 --- a/.github/backlog/ISSUES.md +++ b/.github/backlog/ISSUES.md @@ -535,7 +535,7 @@ Implementation work in this stage should remain gated by the Stage 2.1 readiness Provider-context planning root: -- #82 - `[Stage 3] Provider context planning map` +- #82 - `[Stage 3] Provider context planning map`. Completed by [`docs/provider-context-plan.md`](../../docs/provider-context-plan.md). Suggested planning merge order: diff --git a/ROADMAP.md b/ROADMAP.md index 28e4254..cc3ee85 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -136,6 +136,8 @@ Goal: connect local Maven evidence to pull request context while keeping the cor Release gate: [v0.3.0 release acceptance checklist](docs/release-acceptance-v0.3.0.md). +Planning map: [Provider context plan](docs/provider-context-plan.md). + Planned work: - GitHub adapter for changed files and check runs. diff --git a/docs/integrations.md b/docs/integrations.md index 211c9c3..6d653ea 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -25,6 +25,8 @@ This means GitHub is the only platform with official project automation and exam Native PR and CI context adapters are planned for Stage 3. +The planning lane is documented in the [Provider Context Plan](provider-context-plan.md). + Planned order: 1. GitHub adapter for changed files and check runs. diff --git a/docs/project-visual-map.md b/docs/project-visual-map.md index 7c022f8..966e912 100644 --- a/docs/project-visual-map.md +++ b/docs/project-visual-map.md @@ -187,6 +187,7 @@ This document is a navigation aid. The source of truth remains: - [MVP hardening plan](mvp-hardening-plan.md) - [v0.1.0 release snapshot](release-snapshot-v0.1.0.md) - [v0.3.0 release acceptance checklist](release-acceptance-v0.3.0.md) +- [Provider context plan](provider-context-plan.md) - [MVP acceptance checklist](mvp-acceptance.md) - [Implementation status](implementation-status.md) - [Label guide](labels.md) diff --git a/docs/provider-context-plan.md b/docs/provider-context-plan.md new file mode 100644 index 0000000..420678f --- /dev/null +++ b/docs/provider-context-plan.md @@ -0,0 +1,68 @@ +# 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](project-visual-map.md), [v0.3.0 release acceptance checklist](release-acceptance-v0.3.0.md), [integration scope](integrations.md), and [roadmap](../ROADMAP.md). + +## Readiness Gates + +Stage 3 provider-context work starts after these gates are available: + +- [#79 Stage 3 readiness gate](https://github.com/pr-cli/pr-maven-cli/issues/79) +- [#100 v0.3.0 release acceptance checklist](https://github.com/pr-cli/pr-maven-cli/issues/100) +- [#101 visual dependency map](https://github.com/pr-cli/pr-maven-cli/issues/101) +- [#102 post-gate label review](https://github.com/pr-cli/pr-maven-cli/issues/102) + +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](https://github.com/pr-cli/pr-maven-cli/issues/84) and [#85 provider fixture and mock contract](https://github.com/pr-cli/pr-maven-cli/issues/85) +2. [#83 provider error and offline fallback taxonomy](https://github.com/pr-cli/pr-maven-cli/issues/83) and [#86 GitHub token and permission matrix](https://github.com/pr-cli/pr-maven-cli/issues/86) +3. [#87 changed-files fixture contract](https://github.com/pr-cli/pr-maven-cli/issues/87) and [#89 check-runs fixture contract](https://github.com/pr-cli/pr-maven-cli/issues/89) +4. [#90 PR context JSON extension contract](https://github.com/pr-cli/pr-maven-cli/issues/90), [#88 Markdown PR summary content contract](https://github.com/pr-cli/pr-maven-cli/issues/88), and [#91 why, explain, and ci command UX boundaries](https://github.com/pr-cli/pr-maven-cli/issues/91) +5. [#93 CI artifact directory fixture layout](https://github.com/pr-cli/pr-maven-cli/issues/93), [#92 GitLab parity boundary](https://github.com/pr-cli/pr-maven-cli/issues/92), and [#94 agent evidence bundle schema](https://github.com/pr-cli/pr-maven-cli/issues/94) + +## 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](https://github.com/pr-cli/pr-maven-cli/issues/21) +- [#22 GitHub adapter interface](https://github.com/pr-cli/pr-maven-cli/issues/22) +- [#23 GitHub check runs adapter](https://github.com/pr-cli/pr-maven-cli/issues/23) +- [#24 baseline comparison model](https://github.com/pr-cli/pr-maven-cli/issues/24) +- [#25 PR-to-module relevance scoring](https://github.com/pr-cli/pr-maven-cli/issues/25) +- [#26 confidence model v2](https://github.com/pr-cli/pr-maven-cli/issues/26) +- [#27 prmaven explain command](https://github.com/pr-cli/pr-maven-cli/issues/27) +- [#28 prmaven ci command](https://github.com/pr-cli/pr-maven-cli/issues/28) +- [#29 Markdown PR summary output](https://github.com/pr-cli/pr-maven-cli/issues/29) +- [#34 agent evidence bundle output](https://github.com/pr-cli/pr-maven-cli/issues/34) +- [#36 CI artifact directory option](https://github.com/pr-cli/pr-maven-cli/issues/36) + +## 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.