Build scripts/check-no-stale-plan-id-comments.sh grep gate #74

New Issue

2026-05-12T19:21:51Z

KofTwentyTwo commented

2026-05-12 19:21:51 +00:00

(Migrated from github.com)

Goal

Implement the grep gate recommended in .planning/code-commenting-guide.md that flags comment blocks consisting only of a Plan/B-/D- reference with no descriptive prose.

Behavior

Warn-level initially: prints findings, exits 0. Do not break existing builds.
Detection: match comment lines (//, ///, block-comment continuation) where the only non-whitespace content is a Plan ID pattern (Plan \d+-\d+[a-z]?, B-\d+[a-z]?, D-\d+[a-z]?, audit-\d{4}-\d{2}-\d{2}) and trailing punctuation, with no surrounding WHY-prose in the comment block.
Scope: scan App/**/*.swift and packages/**/*.swift. Skip generated files, vendored sources, .build/, and test fixtures.
Output: path:line: <stale plan-id-only comment> lines, suitable for editor jump.
Exit code flip: once the codebase is brought up to standard (epic #64 closes), bump to fail-level (exit 1 on any finding) in a follow-up.

Acceptance criteria

Script lives at scripts/check-no-stale-plan-id-comments.sh.
Runs in <5 s on the full corpus.
Documented in CLAUDE.md boundary-gates list (sibling CLAUDE.md issue).
Includes a fixture-based self-test (or at minimum a manual smoke test command in the header comment).

Parent epic

#64

Source

.planning/code-commenting-guide.md → Tooling recommendations

## Goal Implement the grep gate recommended in `.planning/code-commenting-guide.md` that flags comment blocks consisting only of a Plan/B-/D- reference with no descriptive prose. ## Behavior - **Warn-level initially:** prints findings, exits 0. Do not break existing builds. - **Detection:** match comment lines (`//`, `///`, block-comment continuation) where the only non-whitespace content is a Plan ID pattern (`Plan \d+-\d+[a-z]?`, `B-\d+[a-z]?`, `D-\d+[a-z]?`, `audit-\d{4}-\d{2}-\d{2}`) and trailing punctuation, with no surrounding WHY-prose in the comment block. - **Scope:** scan `App/**/*.swift` and `packages/**/*.swift`. Skip generated files, vendored sources, `.build/`, and test fixtures. - **Output:** `path:line: <stale plan-id-only comment>` lines, suitable for editor jump. - **Exit code flip:** once the codebase is brought up to standard (epic #64 closes), bump to fail-level (exit 1 on any finding) in a follow-up. ## Acceptance criteria - Script lives at `scripts/check-no-stale-plan-id-comments.sh`. - Runs in <5 s on the full corpus. - Documented in `CLAUDE.md` boundary-gates list (sibling CLAUDE.md issue). - Includes a fixture-based self-test (or at minimum a manual smoke test command in the header comment). ## Parent epic #64 ## Source .planning/code-commenting-guide.md → Tooling recommendations

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#74