From 4db1feaa9bc9a0433c60bff56cf2733e39851236 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 03:17:24 +0000 Subject: [PATCH 1/2] ci: guard the code-comments rule with a grep in the build job CONTRIBUTING.md's "Code comments" section relies on review to hold. This fails the build job on the framing vocabulary instead. Only that vocabulary is matched. Bare `#NNN` is deliberately not matched: issue links are allowed where the thread carries detail the comment cannot, and the pattern would hit every hex colour. Prose docs are exempt by path. One letter of each alternative is bracketed so the workflow file, which holds the pattern, does not match itself. Verified: passes on the tree, catches a planted `Phase 7` and a planted `PLAN.md` reference, does not self-match, and ci.yml still parses. The step is purely additive. Split out of the comment PR so that one stays comment- and docs-only, which is the property its mechanical verification rests on. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QAy8brFG9x8fXet3AV9dJE --- .github/workflows/ci.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6ce62f926..88d337ea6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,6 +15,22 @@ jobs: with: node-version: 24 cache: npm + # CONTRIBUTING.md "Code comments": comments say what the code does, not + # which phase of the project produced it. Only the framing vocabulary is + # matched -- issue links are allowed where the thread carries detail the + # comment cannot, so bare `#NNN` is deliberately not matched here (it + # would also hit every hex colour). Prose docs are exempt by path. + # + # One letter of each alternative is bracketed so this file, which holds + # the pattern, is not itself a match -- the scan covers .github/workflows. + - name: No project framing in code comments + run: | + if grep -rnE '(Phas[e] [0-9]|PLA[N]\.md|parit[y] milestone|open questio[n] [0-9])' \ + app styles plugins scripts tests template.yml tailwind.config.js \ + playwright.config.ts .github/workflows; then + echo "::error::Project framing in a code comment -- see CONTRIBUTING.md 'Code comments'." + exit 1 + fi - run: npm ci - run: npm run compile - run: npm run test:unit From 07d53b2ab70c82a7f07b9a091c787cf5decbf40e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 04:26:04 +0000 Subject: [PATCH 2/2] ci: exempt README.md from the framing guard, and skip binaries The guard contradicted the rule it enforces. CONTRIBUTING.md exempts prose docs by name, "the test suite's own README.md" included, and the step's own comment repeats that -- but the scan recurses through `tests`, so tests/visual/README.md was scanned like any source file. Confirmed by appending a permitted history line to it: the step failed. It carries eight issue references today, so it is exactly the file the exemption is for. --exclude=README.md is scoped to READMEs, not all Markdown: the fixture `.md` files under tests/visual/fixture are still scanned, verified with a planted ``. -I skips the 29 binary PNG snapshots under tests/visual/__snapshots__. Nothing matches this pattern in them today, but grep reports "Binary file ... matches" and exits 0 on a stray byte hit, which would fail the step for no reason -- a pattern earlier in this work did match those PNGs. Verified: passes clean, exempts the README, still catches a planted `Phase 8` in styles/rtl.css and `Phase 9` in a fixture, does not self-match, and ci.yml still parses. Reported by the Copilot reviewer on #202. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QAy8brFG9x8fXet3AV9dJE --- .github/workflows/ci.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 88d337ea6..ba82d9b97 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,9 +23,15 @@ jobs: # # One letter of each alternative is bracketed so this file, which holds # the pattern, is not itself a match -- the scan covers .github/workflows. + # + # --exclude=README.md: prose docs keep their history, and tests/visual's + # README sits inside a scanned path (it carries eight issue references + # today). -I: skip the binary snapshots under tests/visual/__snapshots__, + # where grep would report "Binary file ... matches" and fail the step. - name: No project framing in code comments run: | - if grep -rnE '(Phas[e] [0-9]|PLA[N]\.md|parit[y] milestone|open questio[n] [0-9])' \ + if grep -rnIE --exclude=README.md \ + '(Phas[e] [0-9]|PLA[N]\.md|parit[y] milestone|open questio[n] [0-9])' \ app styles plugins scripts tests template.yml tailwind.config.js \ playwright.config.ts .github/workflows; then echo "::error::Project framing in a code comment -- see CONTRIBUTING.md 'Code comments'."