Repository navigation
feat(review): add PR description check and execution plans - #4
Merged
Merged
Conversation
- Extend the Plan template with an execution section: preconditions, completion contract, ordered tasks with files/change/tests/exit condition, validation ledger, and rollback per batch. Plans stay blocked while a material decision is unresolved. - Align CONTRIBUTING, AGENTS, specs and plans READMEs on Spec = required behavior, Plan = technical decisions + execution plan. - Add scripts/check-pr-body.sh and a "PR description" review job; share the required section list with check-repository.sh via scripts/lib/review-sections.sh and require the new job in branch protection. - Reject CJK characters in PR titles and document conventional titles for release and dependency bot PRs. - Match private paths only at a path boundary and avoid grep -q SIGPIPE failures under pipefail in check-repository.sh. - Point JavaScript/TypeScript projects at PerfectPan/lint-config. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Dependency and release bots write their own PR bodies without the template sections. Skip the PR description job when the PR author is a Bot account; the conventional title check still runs for them. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Title format:
type(scope): summary, in English.Summary
Files / Change / Tests / Exit condition, validation ledger, rollback per batch) on top of the existing design sections.scripts/check-pr-body.shplus aPR descriptionjob inreview.ymlenforce PR/MR description structure.scripts/check-pr-title.shrejects CJK characters; docs require conventional titles for bot PRs too (chore(release): version packages,chore(deps): ...).scripts/check-repository.shfrom a downstream fork.PerfectPan/lint-configfor JS/TS lint, format, and tsconfig rules.Motivation
docs/plans/README.mdsaid a plan is "not a task checklist", so implementers still had to derive the execution order themselves.https://example.com/Users/..., andgrep -qat the end of a pipeline can fail spuriously underpipefailwhen the writer gets SIGPIPE.Implementation Notes
docs/plans/0000-template.md: replaced "Delivery plan and effort" with "6. Execution plan" (6.1-6.6); the work split/schedule table is kept as optional 6.6. Added ablockedstatus and the rule to stay blocked while a decision that changes scope, interfaces, data, or rollout is unresolved. "Delete sections that do not apply" is unchanged.CONTRIBUTING.md,AGENTS.md,specs/README.md,docs/plans/README.md,docs/README.md,README.md: consistent wording, Spec = required behavior, Plan = technical decisions + detailed execution plan; still no RFC directory.scripts/lib/review-sections.shis the single list of required##headings.check-repository.shsources it (the staged copy viaevalin--stagedmode, because Bash 3.2 cannotsource <(...)), andcheck-pr-body.shsources it too.check-pr-body.shreads a file argument or stdin, strips CR, and fails when a required section is missing, when Summary or Validation holds only blank lines, bare-/checkbox bullets, HTML comments, or lines copied unchanged from the PR/MR templates, or when a line matchesgenerated (with|by) .*(claude|codex|copilot|cursor|gpt|ai)case-insensitively (aias a whole word) or the robot-emoji form.review.ymljobPR descriptionpasses the body throughenv: PR_BODYandprintf '%s\n' "$PR_BODY"into stdin; no${{ }}is interpolated into shell. It runs on the existingeditedtrigger, so description edits re-run it. It is skipped whengithub.event.pull_request.user.type == 'Bot'(dependabot, release PRs,create-pull-requestwithGITHUB_TOKEN); the title job still runs for bots. A job skipped byif:reports as skipped, which satisfies a required status check. CONTRIBUTING and AGENTS document the exemption.configure-github-repository.shadds it to the required contexts.check-pr-title.shusesperl -CI -0777with\p{Han}, kana, Hangul, CJK punctuation, and fullwidth ranges so the check does not depend on the runner locale. The allowed type list is unchanged.check-repository.sh: private paths must follow start-of-line, whitespace, quote, backtick,(,<,>, or=;git show ... | grep -qbecamegrep ... >/dev/null. New scripts added torequired_files. Project-specific parts of the fork were not copied.Validation
for f in scripts/*.sh scripts/lib/*.sh .githooks/pre-commit; do bash -n "$f"; done: all ok../scripts/check-repository.sh:check-repository: ok../scripts/check-repository.sh --staged(also run by the pre-commit hook on commit):check-repository: ok (staged).## Evidencerenamed in the PR template: both exit 1 with.github/pull_request_template.md is missing required section: Evidence; restored afterwards../scripts/check-pr-body.sh .github/pull_request_template.md: exit 1,section has no content beyond template placeholders: ## Summaryand## Validation. Same for the GitLab template../scripts/check-pr-body.sh filled.md(PR template with a Summary bullet and one checked Validation line):check-pr-body: ok. The CRLF variant piped through stdin also passes../scripts/check-pr-body.sh attributed.md(filled body plus the robot-emoji attribution footer that Claude Code appends by default): exit 1,remove agent attribution lines:with the offending line number. The equivalent Codex attribution line also fails; a line reading that a changelog was produced by a maintainer script passes (whole-wordaionly).### Evidenceinstead of## Evidence: exit 1,missing required section: ## Evidence. Empty stdin:missing PR body. Missing file:file not found../scripts/check-pr-title.sh "docs: update project template":check-pr-title: ok../scripts/check-pr-title.sh "docs: <CJK summary>"(Chinese, Japanese, and Korean samples, also underLC_ALL=C): exit 1,title must be English; CJK characters are not allowed../scripts/check-pr-title.sh "chore(release): version packages":check-pr-title: ok../scripts/configure-github-repository.sh --repo a/b --branch main: dry-run payload listsrepository checks,conventional PR title,PR description.ruby -ryaml -e 'YAML.load_file(".github/workflows/review.yml")': parses; theReviewrun on this PR (human author) ran all three jobs green after the bot-skip commit../scripts/check-pr-body.sh pr-body.md:check-pr-body: ok../scripts/check-pr-title.sh "feat(review): add PR description check and execution plans":check-pr-title: ok.Skipped gates and reasons:
shellcheckis not installed locally.Evidence
Reviewworkflow run on this PR exercises the newPR descriptionjob.Safety Checklist
Follow-up Risks
configure-github-repository.sh --applyto requirePR description; until then the job is advisory.check-pr-title.shnow needsperl(present on GitHub-hosted runners and macOS).PerfectPan/lint-configis being created in parallel; the reference is by name only.