docs: fix stale plugin-authoring guide and dataset layout in spec

The "how to add a check" steps in docs/spec.md referenced a
`Y2k38CheckBase.h` with `y2k38::MatcherCallback<T>` / `y2k38::ActionBase<D>`
templates that do not exist on this branch — that abstraction was reverted
earlier in this PR (72e15ca). A contributor following the spec could not
build. Rewrite the steps to match the real pattern: a per-check namespace
defining a matcher, a `MatcherCallback`, and a free `addMatcher(MatchFinder*)`
registered from `Y2k38AllAction::CreateASTConsumer`.

Also correct the dataset tree, which listed a `whitelist/` directory that
does not exist and omitted the actual `downcast-bug/` directory. Keep the
whitelist convention as documented guidance for new checks.

Add `just setup-dev` to the CLAUDE.md build section for parity with README.

https://claude.ai/code/session_01DAu2VdTJ6vFYtMw8R1iV7C

Author: Ran350

CLAUDE.md

@@ -15,6 +15,9 @@ unmerged worktree. See `.claude/rules/git-workflow.md` for the full safe cleanup
 # First-time setup (downloads ~700 MB LLVM 11)
 just setup-llvm
 
+# First-time setup + build in one step (setup-llvm then build)
+just setup-dev
+
 # Build everything
 just build          # Clang plugin (cmake) + Rust reporter (cargo)
 just build-plugin   # Clang plugin only

docs/spec.md

@@ -105,12 +105,17 @@ narrow `time_t` to `int`.
 
 Built with CMake against LLVM/Clang 11. Produces `liby2k38-plugin.so`.
 
-Each check is an independent `ASTFrontendAction` subclass registered under a common plugin entry
-point (`y2k38-all`). New checks are added by:
-
-1. Creating `lib/<check-name>/` with `*Action.{h,cpp}` (use `y2k38::MatcherCallback<T>` and `y2k38::ActionBase<D>` from `Y2k38CheckBase.h`).
-2. Adding the action to `Y2k38AllAction`.
-3. Adding a one-line `CMakeLists.txt` that calls `add_y2k38_check(<name> <source>)`.
+Each check lives in its own namespace under `lib/<check-name>/` and is registered into a common
+plugin entry point (`y2k38-all`). New checks are added by:
+
+1. Creating `lib/<check-name>/<Name>Action.{h,cpp}` with a namespace that defines:
+   - an AST matcher (e.g. `matcher`),
+   - a `MatcherCallback : public MatchFinder::MatchCallback` that emits the diagnostic, and
+   - a free function `void addMatcher(MatchFinder *Finder)` that binds the matcher to the callback.
+2. Calling `<namespace>::addMatcher(Finder)` from `Y2k38AllAction::CreateASTConsumer`
+   (`lib/y2k38-all/Y2k38AllAction.h`).
+3. Adding a one-line `CMakeLists.txt` that calls `add_y2k38_check(<name> <source>)`
+   (see `lib/CMakeLists.txt`).
 
 ### Rust Reporter (`reporter/`)
 
@@ -130,11 +135,13 @@ Environment variables (override defaults at runtime):
 
 ```
 dataset/
-├── blacklist/   # C files that MUST trigger at least one warning
-└── whitelist/   # C files that MUST trigger zero warnings
+├── blacklist/     # C files that MUST trigger at least one warning
+└── downcast-bug/  # time_t downcast examples
 ```
 
-Used for regression testing.
+Used for regression testing. A `whitelist/` (C files that MUST trigger zero warnings) is the
+convention for new checks — see `.claude/rules/test-design.md` — and should be added alongside
+the corresponding blacklist file.
 
 ---