kandev/docs/plans/github-api-resilience/task-02-consolidate-documentation-api-reads.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
02-consolidate-documentation-api-reads	Consolidate documentation API reads	done	2	01-rate-aware-api-recovery	plan.md	REQ-CI-PR-DOCS-002 REQ-CI-PR-DOCS-003 REQ-CI-PR-DOCS-004	AC-CI-PR-DOCS-002.2 AC-CI-PR-DOCS-003.1 AC-CI-PR-DOCS-003.2 AC-CI-PR-DOCS-004.1 AC-CI-PR-DOCS-004.2 AC-CI-PR-DOCS-004.3 AC-CI-PR-DOCS-004.4	../../specs/ci/system-design/pull-request-documentation-coverage.md

Task 02: Consolidate documentation API reads

Summary

Reuse exact-head and base data, remove a duplicate pull request read, and avoid full evaluations for events that cannot change documentation coverage.

In scope

• .github/scripts/pr-docs.cjs
• .github/scripts/pr-docs.test.cjs
• .github/workflows/pr-docs.yml
• .github/scripts/pr-docs-workflow-contract_test.py
• This work order's implementation results

Out of scope

Coverage-policy exemptions, artifact frontmatter, merge-group membership, rulesets, tokens, and other GitHub workflows.

Acceptance

• Reuse the pending-status pull request snapshot. Perform one later consistency read for a stable pull request. Read each (revision, path) once.
• Resolve a verified existing requirement from changed head/base documents with zero code-search calls. Keep bounded fallback and duplicate detection for new, moved, missing, or ambiguous IDs.
• Route opened, reopened, synchronize, base-branch retargets, exact no-docs-allow label transitions, dispatch, and merge-group checks. Skip title, description, readiness, and unrelated label events before checkout or API use.

Verification

Run from the repository root:

node --test .github/scripts/pr-docs.test.cjs
python3 .github/scripts/pr-docs-workflow-contract_test.py
python3 .github/scripts/lint-action-pinning_test.py
python3 .github/scripts/lint-action-pinning.py
zizmor .github/workflows/pr-docs.yml
git diff --check

Files likely touched

• .github/scripts/pr-docs.cjs
• .github/scripts/pr-docs.test.cjs
• .github/workflows/pr-docs.yml
• .github/scripts/pr-docs-workflow-contract_test.py
• docs/plans/github-api-resilience/task-02-consolidate-documentation-api-reads.md

Dependencies

Task 01.

Risks

Start a fresh cache after metadata instability and for every merge-group member. Scan all changed requirement documents in a referenced directory before relying on trusted-base uniqueness.

Parallelism

sequential

Inputs

• Requirements
• System design
• Plan
• .github/AGENTS.md

Results

Implemented the exact-revision read strategy in .github/scripts/pr-docs.cjs and the relevant event gates in .github/workflows/pr-docs.yml.

• The initial pull request snapshot used for the pending status is passed into evaluation, leaving one later consistency read for a stable run.
• Content reads use a (revision, path) cache. Changed requirement documents are loaded at the exact head before search, and their corresponding base paths are loaded once for identity comparison.
• Existing or renamed requirement definitions with the same requirement heading/ID in their trusted base path skip code search, including body or acceptance-text changes. New, moved without a trusted base identity, missing, and ambiguous identities keep the bounded search and directory fallback.
• The workflow admits only opened, reopened, synchronize, base-branch retargets, exact override-label transitions, manual dispatch, and merge-group checks. Title and description edits, readiness changes, and unrelated label events are rejected at the job gate.

Verification:

• node --test .github/scripts/pr-docs.test.cjs (75 passed)
• python3 .github/scripts/pr-docs-workflow-contract_test.py (7 passed)
• python3 .github/scripts/lint-action-pinning_test.py (9 passed)
• python3 .github/scripts/lint-action-pinning.py (24 workflows passed)
• zizmor .github/workflows/pr-docs.yml (no findings)
• git diff --check (passed)