José Almeida
5.6 KiB
created, status, requirements, system_design, legacy_specs
| created | status | requirements | system_design | legacy_specs | ||||
|---|---|---|---|---|---|---|---|---|
| 2026-09-10 | done |
|
|
Implementation plan: PR documentation coverage
Overview
Build a deterministic coverage validator, integrate PR status reporting, then add merge-queue evaluation and contributor guidance. The CI system owns this package because it controls repository checks and label exceptions.
Scope
In scope: narrow exemptions, 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.
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.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
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.
Risks
- Conservative defaults require labels for some small fixes, refactors, and dependency manifest changes.
- 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.