Repository navigation
Description
Is your enhancement related to a problem? Please describe
The Global DoD checklist gate requires every box ticked, so it compels contributors to attest to things that are not yet true — and cannot be true at the moment a PR is opened.
scripts/validation/template-helpers.cjs:
function hasCompletedChecklist(sectionText) {
const cleaned = stripHtmlComments(sectionText);
const hasUnchecked = /(?:^|\n)\s*-\s*\[\s\]\s*/.test(cleaned);
const hasChecked = /(?:^|\n)\s*-\s*\[[xX]\]\s*/.test(cleaned);
return hasChecked && !hasUnchecked; // ← zero unchecked boxes required
}Consumed by validate-pr-template.yml, which fails the PR with:
##[error] PR #… is missing required template content: Global DoD checklist
pr_feature.md's checklist contains rows that are structurally impossible to satisfy when the PR is opened:
| Row | Why it cannot be true yet |
|---|---|
CI green; linked issues closed; release notes prepared |
CI has not run when the body is first validated. Linked issues close on merge. |
Code/design reviews approved |
The PR exists in order to request review. |
And there is no way to express N/A. A documentation-only PR has no accessibility surface; a prompt-only PR has no WPCS applicability. The only way to pass is to tick them anyway.
Why this matters
Three consequences, in increasing order of seriousness:
- The gate is unsatisfiable honestly. Every contributor must either tick
CI greenbefore CI runs, or accept a permanently red check. - It trains inaccurate attestation. The checklist is a Definition of Done — a record of what was actually verified. A gate that rewards ticking regardless converts it into a formality.
- A fully-ticked checklist therefore carries no information. Once everyone ticks everything to pass, a reviewer cannot distinguish a PR where security was genuinely reviewed from one where the box was cleared to go green. The control defeats itself.
Live example — #1392. Three boxes are deliberately unticked: CI green (red from a pre-existing schema-path bug, #1395), Code/design reviews approved (no reviewer assigned yet), and the accessibility checklist (N/A — the diff has no UI). Each is annotated with the reason in the PR body. validate-pr-template fails, and in the current design it is right to fail: the DoD is not met. But the only route to green is to write something inaccurate.
Describe the solution you'd like
Either fix, or both:
Option A — support an explicit N/A marker (recommended)
Teach hasCompletedChecklist() to treat a third state as resolved:
const NA = /(?:^|\n)\s*-\s*\[~\]\s*/; // or [n/a]
const hasUnresolved = /(?:^|\n)\s*-\s*\[\s\]\s*/.test(cleaned);
return hasChecked && !hasUnresolved; // [~] counts as resolvedConvention: - [~] Accessibility checklist — N/A, no UI surface, with a required reason after the em dash. This keeps the gate strict — a bare - [ ] still fails — while letting a contributor state "considered, does not apply", which is a genuinely different claim from both "done" and "not done".
Option B — exempt rows already enforced elsewhere
CI green and Code/design reviews approved are enforced independently and more reliably by checks.yml and branch protection. Requiring a self-attestation of a machine-checked fact adds no assurance. Drop them from the validated set (or move them to a "Merge readiness" block the validator ignores) and let the automation that actually gates merge do the work.
Either way
Add unit tests to the existing 45-case suite for template-helpers.cjs covering: N/A markers accepted, bare unchecked still rejected, mixed states, and N/A without a reason (rejected if the reason is mandated).
Designs / Mockups
N/A — validation logic only.
Accessibility Considerations
N/A to the change itself. Worth noting that the current design harms accessibility outcomes indirectly: when the a11y row must be ticked on PRs with no UI surface, the tick stops meaning "accessibility was reviewed", so genuine a11y attestation loses its signal.
Acceptance Criteria
-
hasCompletedChecklist()distinguishes done, not done, and not applicable — or the impossible-at-open rows are removed from the validated set - A bare
- [ ]still fails, so the gate is not merely weakened - If an N/A marker is adopted, it is documented in
pr_feature.mdand the sibling PR templates, and a reason is required - Unit tests added to the
template-helpers.cjssuite for each state -
docs/PR_CREATION_PROCESS.mdandCLAUDE.mdupdated to describe the convention - feat(playwright-testing-agent): performance routing, a11y/SEO/console gates, and scope-exclusion discipline #1392 can pass the gate without any inaccurate tick
- All acceptance criteria met
- Documentation/changelog updated
- Tests added/updated
- PR uses correct branch prefix (
feat/orfix/) - Labels/types match org standards
Testing Requirements
- Unit tests for
hasCompletedChecklist()across done / not-done / N/A / mixed / N/A-without-reason. - Verify against the real body of feat(playwright-testing-agent): performance routing, a11y/SEO/console gates, and scope-exclusion discipline #1392 — it should pass once N/A is expressible and the CI/review rows are handled, and still fail if a substantive row is left bare.
- Confirm no regression in
template-enforcement.yml, which shares the helper module.
Describe alternatives you've considered
- Tick everything and move on. Rejected: it makes the checklist decorative and is the behaviour this issue exists to stop. It also produces a written record that misstates what was verified.
- Drop the checklist requirement entirely. Rejected: the checklist has real value as a prompt; the problem is only that it cannot express N/A and includes rows that are premature at open.
- Re-validate on every push so the boxes can be ticked later. Doesn't help — the contributor still has to tick
CI greenmanually, and nothing re-checks whether it became true. - Split into "at open" and "before merge" checklists. A cleaner long-term shape, but a larger template change across every PR template; Option A gets most of the benefit for far less churn.
Additional Context
scripts/validation/template-helpers.cjs—hasCompletedChecklist().github/workflows/validate-pr-template.yml— the consumer.github/workflows/template-enforcement.yml— shares the module; must not regress.github/PULL_REQUEST_TEMPLATE/pr_feature.md— the checklist in question- feat(playwright-testing-agent): performance routing, a11y/SEO/console gates, and scope-exclusion discipline #1392 — live example, with three boxes deliberately unticked and annotated
Note the helper is otherwise correct and well-tested — the regex matches the heading exactly as intended, and stripHtmlComments handles template comments properly. This is a design gap in what the checklist is asked to express, not a coding defect.
Definition of Ready (DoR)
- Problem/opportunity defined — with the failing check and a live example
- Acceptance criteria written
- Designs attached (if relevant) — N/A, validation logic only
- Dependencies mapped —
template-helpers.cjs, both consuming workflows, the PR templates - Estimate added — small if Option A alone; larger if the templates are restructured
Definition of Done (DoD)
- All AC met and demonstrated
- Documentation and changelog updated
- Tests added/updated
- Correct labels/types applied
- PR uses correct branch prefix
🤖 Generated with Claude Code
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity
linear-code commentedon Jul 29, 2026
LS-1951
github-actions commentedon Jul 29, 2026
⏱️ Aging and SLA annotation
Maintained by project-meta-sync workflow.
github-actions commentedon Sep 8, 2026
This issue has labels that are not in the canonical taxonomy:
migrate:priority:normalmigrate:type:improvemigrate:area:automationValid Canonical Labels
Please use labels with a prefix from the canonical taxonomy:
type:bug,type:feature,type:task,type:documentation, etc.status:needs-triage,status:in-progress,status:done, etc.priority:critical,priority:high,priority:normal,priority:lowarea:ci,area:docs,area:labels,area:security, etc.meta:needs-changelog,meta:duplicate,meta:blocked, etc.For the complete list, see .github/labels.yml.