[theCodeDrift]

Shows how to prove a rule's scope excludes a path with folder fixtures, and says so in the never-read error.

• fixtureLayoutBlock() in prompts/recipes.ts: put the excluded offending file in a pass/ case beside a clean file the scope admits. The case then counts as read, and passes when the rule stays quiet on both. Includes the issue's src/**/*.ts + src/generated/** example.
• agent/create-sg-rule.md step 6 says the same, with a new error-table row.
• Five recipes embed the shared block, so their topics bump: create-sg-rule v15, create-vale-rule v22, create-runtime-rule v9, improve-rule.anonymous v7, validate-rule v11.
• rules/fixtures.ts describeCaseFailure: the scope-excluded never-read error for a pass case now ends with the remedy. Fail-case message unchanged; Vale shares the path.

Tests in sg-fixtures.test.ts: pass-case hint, no hint on fail cases, the mixed pass case verifies, each excluded file alone is rejected. typecheck, lint, pnpm test (3166 passed) pass. No OpenSpec change: behaviour is unchanged.

Note: #682 (F-671) also bumps create-sg-rule to v15; whichever merges second needs v16.

Commits are unsigned: the signing key couldn't be unlocked remotely, and the owner chose to ship unsigned.

Closes #677

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 1m 4s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contained no reviewThreads, no reviews, and only the trigger comment itself under comments — this is the first review of this PR, so the whole diff was assessed fresh.

• Read prior review data
• Fetch PR diff and metadata
• Read changed files in full context
• Review for correctness, security, performance, tests, clarity
• Post inline comments for concrete issues
• Post final summary

Assessment

This is a focused docs/error-message change with no behavioral surface beyond wording, matching the changeset and "No OpenSpec change" claim.

Verified correctness of the core logic change (packages/cli/src/rules/fixtures.ts:311-325): the new pass-case suggestion appended to the "never read" error is accurate to the implementation. I traced scanCase/runSgFixtures in packages/cli/src/rules/sg-fixtures.ts:106-200: "read" (reached.length > 0 || findings.length > 0) is decided once per whole case directory, not per file. So the documented fix — adding one clean file the scope admits alongside the excluded file, in the same pass/ case — does make the case count as read, exactly as the new message, the recipes.ts block, and create-sg-rule.md step 6 all claim. The fail-case branch is untouched (message returned as-is), consistent with the PR description ("Fail-case message unchanged").

Consistency check: all five recipes (create-sg-rule, create-vale-rule, create-runtime-rule, improve-rule.anonymous, validate-rule) resolve %(FIXTURE_LAYOUT)s to the single fixtureLayoutBlock() in recipes.ts (confirmed via the one FIXTURE_LAYOUT: mapping in recipes.ts:1013), so the new bullet lands identically in all of them — matching the described version bumps.

Tests: the four new/changed cases in sg-fixtures.test.ts cover the stated behavior directly: pass-case hint present, fail-case hint absent, the mixed pass/ case actually verifying (2 passed, 0 findings), and each excluded file alone still failing as never-read. These exercise the real verifyRule path rather than just describeCaseFailure in isolation, which is the right level given the fix is about the interaction between per-case "read" detection and the message.

Minor, non-blocking observations (not raised as inline comments since none affect correctness):

• create-sg-rule.md's new error-table row ("a pass case showing an exclusion was never read") is the only one of the five recipes where this guidance is spelled out twice — once in the shared %(FIXTURE_LAYOUT)s block (step 6) and again in the table (step 7). That's consistent with the existing table already restating "the rule's scope excluded a case" from the same block, so it's following the file's existing convention rather than introducing a new one.
• The PR body's own note that fix(validate): state sg-regex-needs-kind in the ast-grep rule schema #682 also bumps create-sg-rule to v15 is a merge-order concern between two PRs, not something this PR can fix by itself.

I found nothing new to flag beyond the above; the change does what it describes and the test coverage matches the actual per-case semantics.

[theCodeDrift]

Re: @github-actions — "Claude finished @theCodeDrift's task in 1m 4s"…
#687 (comment)

Read and acknowledged; no code change. The duplicated error-table row in create-sg-rule.md follows that file's existing convention of restating the shared fixture-layout guidance in step 7, and the v15 topic-version overlap with #682 is a merge-order question handled when the two land.

— AI Coding Agent