Skip to content

feat(review): add PR description check and execution plans - #4

Merged
PerfectPan merged 2 commits into
mainfrom
feat/pr-checks-and-execution-plans
Sep 30, 2026
Merged

PerfectPan merged 2 commits into
mainfrom
feat/pr-checks-and-execution-plans

Conversation

@PerfectPan

@PerfectPan PerfectPan commented Sep 30, 2026 •

Copy link
Copy Markdown
Owner

Title format: type(scope): summary, in English.

Summary

  • Plans now carry a detailed execution plan (preconditions, completion contract, ordered tasks with Files / Change / Tests / Exit condition, validation ledger, rollback per batch) on top of the existing design sections.
  • New scripts/check-pr-body.sh plus a PR description job in review.yml enforce PR/MR description structure.
  • scripts/check-pr-title.sh rejects CJK characters; docs require conventional titles for bot PRs too (chore(release): version packages, chore(deps): ...).
  • Backported two generic fixes to scripts/check-repository.sh from a downstream fork.
  • Referenced PerfectPan/lint-config for JS/TS lint, format, and tsconfig rules.

Motivation

  • The workflow is Spec (required behavior) + Plan (technical decisions and detailed execution plan). The Plan template only covered design, and docs/plans/README.md said a plan is "not a task checklist", so implementers still had to derive the execution order themselves.
  • PR descriptions drifted from the template (empty Summary/Validation, tool attribution lines) with nothing enforcing them, and titles were occasionally written in Chinese or left as bot defaults.
  • The private-path regex flagged URL segments such as https://example.com/Users/..., and grep -q at the end of a pipeline can fail spuriously under pipefail when 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 a blocked status 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.sh is the single list of required ## headings. check-repository.sh sources it (the staged copy via eval in --staged mode, because Bash 3.2 cannot source <(...)), and check-pr-body.sh sources it too.
  • check-pr-body.sh reads 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 matches generated (with|by) .*(claude|codex|copilot|cursor|gpt|ai) case-insensitively (ai as a whole word) or the robot-emoji form.
  • review.yml job PR description passes the body through env: PR_BODY and printf '%s\n' "$PR_BODY" into stdin; no ${{ }} is interpolated into shell. It runs on the existing edited trigger, so description edits re-run it. It is skipped when github.event.pull_request.user.type == 'Bot' (dependabot, release PRs, create-pull-request with GITHUB_TOKEN); the title job still runs for bots. A job skipped by if: reports as skipped, which satisfies a required status check. CONTRIBUTING and AGENTS document the exemption. configure-github-repository.sh adds it to the required contexts.
  • check-pr-title.sh uses perl -CI -0777 with \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 -q became grep ... >/dev/null. New scripts added to required_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).
  • Staged and worktree modes with ## Evidence renamed 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: ## Summary and ## 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-word ai only).
  • Body with ### Evidence instead 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 under LC_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 lists repository checks, conventional PR title, PR description.
  • ruby -ryaml -e 'YAML.load_file(".github/workflows/review.yml")': parses; the Review run on this PR (human author) ran all three jobs green after the bot-skip commit.
  • This PR body: ./scripts/check-pr-body.sh pr-body.md: check-pr-body: ok.
  • PR title: ./scripts/check-pr-title.sh "feat(review): add PR description check and execution plans": check-pr-title: ok.

Skipped gates and reasons:

  • Format, lint, test, build, package: the template has no stack. shellcheck is not installed locally.

Evidence

  • Requirement and paired Spec/Plan: repository maintenance request; PR checklist only, no separate Plan.
  • Logs, screenshots, package output, or deployed artifact: command output summarized in Validation; the Review workflow run on this PR exercises the new PR description job.
  • Reviewer notes that changed the final scope: none yet.

Safety Checklist

  • No credentials, tokens, private hostnames, personal filesystem paths, or generated logs are included.
  • Local config, generated output, build artifacts, and temporary workspaces are not staged.
  • User-facing behavior, docs, changelog, migrations, or rollback notes are updated when relevant.
  • Completed Spec/Plan constraints are migrated to tests or current-state docs before retirement; unfinished scope remains active.
  • The branch is current enough for review, and the remote head matches the intended commit.

Follow-up Risks

  • Branch protection on existing repositories must be re-applied with configure-github-repository.sh --apply to require PR description; until then the job is advisory.
  • check-pr-title.sh now needs perl (present on GitHub-hosted runners and macOS).
  • Downstream forks that customized template lines will see those lines treated as placeholders only when they match the local templates, so the check adapts per repository.
  • PerfectPan/lint-config is being created in parallel; the reference is by name only.

PerfectPan and others added 2 commits October 1, 2026 01:14
- 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>
@PerfectPan
PerfectPan merged commit 5de4438 into main Sep 30, 2026
6 checks passed
@PerfectPan
PerfectPan deleted the feat/pr-checks-and-execution-plans branch September 30, 2026 17:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant