Carlos Florêncio
6.9 KiB
created, updated, status, requirements, system_design, legacy_specs
| created | updated | status | requirements | system_design | legacy_specs | ||||
|---|---|---|---|---|---|---|---|---|---|
| 2026-09-10 | 2026-09-16 | done |
|
|
Implementation plan: PR documentation coverage
Overview
Build a deterministic coverage validator, integrate PR status reporting, add merge-queue evaluation and contributor guidance, then refine narrow path exemptions from observed repository-maintenance cases. The CI system owns this package because it controls repository checks and label exceptions.
Scope
In scope: narrow exemptions including the canonical plugin registry source, linked artifact validation, the exact no-docs-allow override, current-revision statuses, queue compatibility, and actionable summaries.
Out of scope: AI classification, application UI, automatic label management, publishing a PR, and live ruleset mutations. Public user documentation remains governed by the existing contribution checklist.
Technical approach
Use the proposed .github/scripts/pr-docs.cjs module for pure policy functions and bounded GitHub reads.
Use .github/workflows/pr-docs.yml for base-controlled execution and the PR documentation coverage commit status.
Reuse the existing Node runtime from GitHub-hosted runners and the built-in test runner; no pnpm dependency installation is needed.
Register Node and workflow contract tests in .github/workflows/lint-action-pinning.yml.
Keep plugin-registry/plugins.yaml as an exact path exemption in the classifier; do not broaden the rule to the full registry tree.
Existing patterns: .github/workflows/pr-size-label.yml for metadata pagination,
.github/scripts/pr-size-label-workflow-contract_test.py for workflow checks, and
docs/ci-merge-queue.md for required-check rollout constraints.
Tests
All named test suites below are proposed files.
| Criteria | Evidence |
|---|---|
| AC-CI-PR-DOCS-001.2 through .6 | pr-docs.test.cjs: classification and artifact graph fixtures |
| AC-CI-PR-DOCS-001.7 | pr-docs.test.cjs: exact registry-source exemption and mixed-path trigger fixture |
| AC-CI-PR-DOCS-001.1; AC-CI-PR-DOCS-002.1 through .4 | Fake GitHub adapter exercises draft/fork events and label transitions |
| AC-CI-PR-DOCS-003.1 through .3 | API failures, pagination caps, stale head/label reads, path and content restrictions |
| AC-CI-PR-DOCS-003.4 through .5 | Per-member queue evaluation, active prefix reevaluation, mismatched queue boundaries, override removal, and rollout checklist |
Use a representative #3137 fixture: fix(worktree) with runtime recovery paths and no artifacts fails.
Do not fetch the live PR in unit tests.
End-to-end evidence
No application browser flow changes. The workflow contract and mocked API tests run locally. After deployment, record real GitHub run URLs for an uncovered PR, a covered PR, an exempt PR, a fork, override addition/removal without pushes, and a merge group. Verify one member's documents or override cannot satisfy another member. Live smoke tests and required-check activation are deployment steps, not completed local evidence.
Work orders
- Task 01: Validate documentation coverage
- Task 02: Report pull request coverage
- Task 03: Support merge queue coverage
- Task 04: Exempt the canonical plugin registry source
Execute sequentially. No subagents are authorized.
Verification results
Task 01's 2026-09-13 regression fix reuses requirement searches and directory
listings within each exact-head snapshot. Its deterministic quota regression
now uses three searches for six work orders. All 50 Node tests, five workflow
contract tests, documentation catalog/specification checks, and whitespace
checks pass. A GET-only evaluation of exact PR #3626 head 93abff34efe8c9ab2bec68acb8e6aba1eb2a23d4
returned covered with three searches and no failed requests. See Task 01 for
red/green evidence and limits. Consumption by trusted main and the new PR's
CI/review gates remain delivery work; no status override or merge is claimed.
Design validation on 2026-09-10:
python3 scripts/lint-spec-files.test.py: 36 tests passed.python3 scripts/lint-spec-files.py --all: passed.git diff --check -- docs/specs docs/decisions docs/plans/pr-documentation-coverage: passed.git status --short -- docs/plans/pr-documentation-coverage: confirmed the new package is present and untracked.
Implementation is complete. Live GitHub smoke-test evidence and required-check activation remain deployment steps and are not claimed by this change.
Implementation verification on 2026-09-10:
node --test .github/scripts/pr-docs.test.cjs: 35 tests passed.python3 .github/scripts/pr-docs-workflow-contract_test.py: 5 tests passed.python3 .github/scripts/lint-action-pinning_test.py: 9 tests passed.python3 .github/scripts/lint-action-pinning.py: 24 workflows passed.python3 scripts/lint-spec-files.py --all: passed.zizmor .github/workflows/pr-docs.yml: no findings.git diff --check: passed.
Repository-wide zizmor .github/workflows still reports existing findings in
unrelated workflows; the new workflow has no reported findings.
Amendment: canonical plugin registry source
The original three work orders remain complete. This amendment adds one exact
path exemption for the curated plugin-registry/plugins.yaml pointer source.
The implementation preserves normal coverage for every other registry path and
for any pull request that combines the exempt source with a non-exempt path.
Task 04 verification completed on 2026-09-16:
- 77 validator tests, 7 workflow contract tests, and 9 action-pinning tests passed.
- All 24 workflow files passed action-pinning lint.
zizmor .github/workflows/pr-docs.ymlreported no findings.- The specification catalog and linter passed;
git diff --checkpassed.
Risks
- Conservative defaults require labels for some small fixes, refactors, and dependency manifest changes.
- An overly broad registry match could allow schema, generator, or generated-catalog changes to bypass delivery context; exact-path tests constrain this risk.
- The target-branch event queue retains up to 100 pending runs; higher bursts can still cancel new runs.
- Structural validation cannot establish semantic relevance or planning chronology.
- Merge queue boundary resolution needs real payload validation before mandatory rollout.
- GitHub label/status publication is eventually consistent.
- Adding a required status is an administrator operation separate from merging workflow files.