[PR #3302] [MERGED] ci: validate initial PR readiness declarations #5712

New issue

Closed

opened 2026-10-31 01:08:51 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:08:51 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3302
Author: @morluto
Created: 10/14/2026
Status: ✅ Merged
Merged: 10/14/2026
Merged by: @morluto

Base: main ← Head: codex/pr-readiness-gate

📝 Commits (1)

4c127aa ci: validate initial PR readiness declarations

📊 Changes

9 files changed (+702 additions, -14 deletions)

View changed files

📝 .github/pull_request_template.md (+4 -3)
➕ .github/workflows/pr-readiness.yml (+51 -0)
📝 AGENTS.md (+6 -6)
📝 CONTRIBUTING.md (+18 -5)
📝 scripts/ci/plan.mjs (+1 -0)
➕ scripts/ci/pr-readiness.d.mts (+63 -0)
➕ scripts/ci/pr-readiness.mjs (+173 -0)
📝 tests/boundary/filesystem/ciChangeScope.test.ts (+4 -0)
➕ tests/boundary/filesystem/prReadiness.test.ts (+382 -0)

📄 Description

Summary

Non-draft PRs can request maintainer review with the human readiness declarations still unchecked. Add a PR readiness status that checks the named owner and three declarations.

Readiness is declared once when opening the PR for review. Later pushes keep that declaration valid. Drafts remain allowed with the readiness status pending.

Problem and expected behavior

See #3294 for a non-draft PR with all three declarations unchecked. Documentation alone does not produce a failing check. Missing or unchecked declarations should fail the readiness status, while a completed initial declaration should continue to pass after further commits.

Change and scope

Add a metadata-only workflow and checker, cover the status boundary and workflow step with tests, and update the template and contributor/agent guidance to remove repeated human sign-off and checkbox-reset requirements.

The check reads the canonical declarations from the trusted repository template. It ignores examples in HTML comments, fenced code blocks, and quotes. It does not assess code quality, verify a person's reading, edit PR bodies, or close PRs.

Maintainer-requested CI change within the existing contribution scope; no target-analysis capability or advance provider scope decision is involved.

Contract and boundary impact

Semantic owner and earliest changed stage: trusted PR template owns declaration wording; the new checker owns parsing and GitHub status publication.
Contribution scope fit and linked maintainer decision: repository CI only; provider/capability scope approval is not applicable.
CLI and MCP/tool-catalog contract: unchanged.
Provider, bridge, target-format, or platform compatibility: unchanged.
Evidence, artifact, provenance, or reconstruction contract: no runtime change.
Target selection, authority, upstream behavior, and cleanup details: pull_request_target reads live PR metadata and checks out only the repository's default branch. Write authority is limited to commit statuses; credentials are not persisted by checkout.
Generated metadata, package, or installation impact: no shipped runtime or dependency changes.

Expected effects:

Contact network services — GitHub metadata reads and status publication.

Evidence and regression coverage

32 readiness tests passed, including missing/unchecked declarations, hidden examples, drafts, later pushes retaining readiness, unavailable API state, duplicate heads, and PR changes during a check.
The production workflow script executed in a Node subprocess with a recording GitHub API substitute. The test asserts trusted checkout and status-only write authority.
213 CI classification tests passed, including selection of code checks when this workflow changes.
Live GitHub execution remains unverified until the trusted workflow is merged. Tests do not establish hosted behavior.

Validation performed

CI classification suite — 213 tests passed.
npm run test:focused -- tests/boundary/filesystem/prReadiness.test.ts — final 32 tests passed.
npm run check:fast — passed.
npm run docs:check — passed, including 5 README consistency tests.
npm run verify:test-discovery — all 1,264 test files discovered exactly once.
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 -shellcheck= -pyflakes= .github/workflows/pr-readiness.yml — passed.
Changed-file formatting and Git diff checks — passed.
Real analysis-provider verification: not applicable.

Gate overhead

The previous workflow has no readiness task. The new ready-PR task makes five GitHub REST calls when commit associations fit one page; drafts and incomplete declarations use four. It installs no dependencies and invokes no model.

Completed local tasks with an in-process GitHub substitute:

Run	Elapsed	CPU	Peak single-process family memory	Model tokens
Cold task	0.821 ms	1.281 ms	45,808 KiB	0
Warm task	0.224 ms	0.239 ms	46,416 KiB	0

The module was loaded before the cold task; the warm task reused the process. Node startup, real GitHub latency, and hosted runner elapsed/CPU/memory costs are unmeasured. These measurements do not predict hosted job duration.

Compatibility, safety, and release

Existing PRs can copy the updated Author readiness section; checked declaration wording must match the trusted template.
GitHub shares commit statuses, so separate open PRs must use distinct head commits.
Activation after merge: dispatch the workflow for existing open PRs, then add PR readiness from GitHub Actions to the existing required status checks. Branch protection has not been changed by this PR.
Deploy the workflow to a target branch before requiring the status there.
Existing administrator overrides and maintainer review remain separate from this declaration check.

Author readiness

Human owner: @morluto

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

Material scope and authority questions are resolved.
Required checks pass.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/3302 **Author:** [@morluto](https://github.com/morluto) **Created:** 10/14/2026 **Status:** ✅ Merged **Merged:** 10/14/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/pr-readiness-gate` --- ### 📝 Commits (1) - [`4c127aa`](https://github.com/morluto/rea/commit/4c127aa77de86e1a5a1f8c2263e57aee12a4a523) ci: validate initial PR readiness declarations ### 📊 Changes **9 files changed** (+702 additions, -14 deletions) <details> <summary>View changed files</summary> 📝 `.github/pull_request_template.md` (+4 -3) ➕ `.github/workflows/pr-readiness.yml` (+51 -0) 📝 `AGENTS.md` (+6 -6) 📝 `CONTRIBUTING.md` (+18 -5) 📝 `scripts/ci/plan.mjs` (+1 -0) ➕ `scripts/ci/pr-readiness.d.mts` (+63 -0) ➕ `scripts/ci/pr-readiness.mjs` (+173 -0) 📝 `tests/boundary/filesystem/ciChangeScope.test.ts` (+4 -0) ➕ `tests/boundary/filesystem/prReadiness.test.ts` (+382 -0) </details> ### 📄 Description ## Summary Non-draft PRs can request maintainer review with the human readiness declarations still unchecked. Add a `PR readiness` status that checks the named owner and three declarations. Readiness is declared once when opening the PR for review. Later pushes keep that declaration valid. Drafts remain allowed with the readiness status pending. ## Problem and expected behavior See #3294 for a non-draft PR with all three declarations unchecked. Documentation alone does not produce a failing check. Missing or unchecked declarations should fail the readiness status, while a completed initial declaration should continue to pass after further commits. ## Change and scope Add a metadata-only workflow and checker, cover the status boundary and workflow step with tests, and update the template and contributor/agent guidance to remove repeated human sign-off and checkbox-reset requirements. The check reads the canonical declarations from the trusted repository template. It ignores examples in HTML comments, fenced code blocks, and quotes. It does not assess code quality, verify a person's reading, edit PR bodies, or close PRs. Maintainer-requested CI change within the existing contribution scope; no target-analysis capability or advance provider scope decision is involved. ## Contract and boundary impact - Semantic owner and earliest changed stage: trusted PR template owns declaration wording; the new checker owns parsing and GitHub status publication. - Contribution scope fit and linked maintainer decision: repository CI only; provider/capability scope approval is not applicable. - CLI and MCP/tool-catalog contract: unchanged. - Provider, bridge, target-format, or platform compatibility: unchanged. - Evidence, artifact, provenance, or reconstruction contract: no runtime change. - Target selection, authority, upstream behavior, and cleanup details: `pull_request_target` reads live PR metadata and checks out only the repository's default branch. Write authority is limited to commit statuses; credentials are not persisted by checkout. - Generated metadata, package, or installation impact: no shipped runtime or dependency changes. Expected effects: - [x] Contact network services — GitHub metadata reads and status publication. ## Evidence and regression coverage - 32 readiness tests passed, including missing/unchecked declarations, hidden examples, drafts, later pushes retaining readiness, unavailable API state, duplicate heads, and PR changes during a check. - The production workflow script executed in a Node subprocess with a recording GitHub API substitute. The test asserts trusted checkout and status-only write authority. - 213 CI classification tests passed, including selection of code checks when this workflow changes. - Live GitHub execution remains unverified until the trusted workflow is merged. Tests do not establish hosted behavior. ## Validation performed - CI classification suite — 213 tests passed. - `npm run test:focused -- tests/boundary/filesystem/prReadiness.test.ts` — final 32 tests passed. - `npm run check:fast` — passed. - `npm run docs:check` — passed, including 5 README consistency tests. - `npm run verify:test-discovery` — all 1,264 test files discovered exactly once. - `go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 -shellcheck= -pyflakes= .github/workflows/pr-readiness.yml` — passed. - Changed-file formatting and Git diff checks — passed. - Real analysis-provider verification: not applicable. <details> <summary>Gate overhead</summary> The previous workflow has no readiness task. The new ready-PR task makes five GitHub REST calls when commit associations fit one page; drafts and incomplete declarations use four. It installs no dependencies and invokes no model. Completed local tasks with an in-process GitHub substitute: | Run | Elapsed | CPU | Peak single-process family memory | Model tokens | | --- | ---: | ---: | ---: | ---: | | Cold task | 0.821 ms | 1.281 ms | 45,808 KiB | 0 | | Warm task | 0.224 ms | 0.239 ms | 46,416 KiB | 0 | The module was loaded before the cold task; the warm task reused the process. Node startup, real GitHub latency, and hosted runner elapsed/CPU/memory costs are unmeasured. These measurements do not predict hosted job duration. </details> ## Compatibility, safety, and release - Existing PRs can copy the updated Author readiness section; checked declaration wording must match the trusted template. - GitHub shares commit statuses, so separate open PRs must use distinct head commits. - **Activation after merge:** dispatch the workflow for existing open PRs, then add `PR readiness` from GitHub Actions to the existing required status checks. Branch protection has not been changed by this PR. - Deploy the workflow to a target branch before requiring the status there. - Existing administrator overrides and maintainer review remain separate from this declaration check. ## Author readiness Human owner: @morluto - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] Material scope and authority questions are resolved. - [ ] Required checks pass. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:08:51 +00:00