Tighten rules and add Vercel-style validate/extract pipeline

[nathan-gage]

Summary

• Fixes 9 rules surfaced in review (notably api-deprecated-aliases had typing.deprecated instead of warnings.deprecated, and error-assert-invariants blended two distinct ideas)
• Adds 7 new rules covering common Python footguns (mutable defaults, bare except, context managers, boolean flag params, sentinels, no-side-effects imports, timezone-aware datetimes)
• Adds Vercel-parity pipeline: src/validate.py, src/extract_tests.py, generated test-cases.json
• Declares Python 3.11+ floor; tags Pydantic-specific rules; updates _template.md to require primary-source references for version-/library-dependent rules

71 rules, 0 validation failures, 71 test cases extracted.

Rule fixes

• api-deprecated-aliases — use warnings.deprecated() (3.13+) for funcs/classes; compatibility kwarg + warnings.warn for parameter renames
• Split error-assert-invariants → error-assert-debug-only (notes -O strips asserts) + error-assert-never-exhaustiveness
• perf-isinstance-tuple-syntax — demoted to "only on profiled hot paths"
• error-trust-validated-state — narrowed with a 4-item trust-domain checklist
• simplify-cached-property — adds thread-safety, __dict__/slots, and idempotency caveats
• data-encapsulate-mutable-state — reframed as "narrowest clear scope"
• perf-generator-over-list — reframed as a streaming/memory rule
• api-instance-vs-module-fn — reframed as "simplest namespace that matches ownership and polymorphism"
• error-specific-exceptions — distinguishes broad except Exception: from bare except:

New rules

error-no-bare-except, data-mutable-defaults, error-context-managers, api-no-boolean-flag-params, data-sentinel-when-none-is-valid, imports-no-side-effects, data-aware-datetimes

Pipeline / repo

• src/validate.py — lints frontmatter, structure, references; required references trigger on concrete signals (Python 3.X+, PEP NNN, warnings.deprecated, cached_property, assert_never, zoneinfo, KW_ONLY, ExceptionGroup, CancelledError, asyncio, pydantic, TypeAdapter, BaseModel, model_validator, model_dump, mypy, pyright, ruff)
• src/extract_tests.py — generates test-cases.json for LLM evals
• metadata.json + SKILL.md declare Python 3.11+ floor
• README documents src/, the build/validate/extract pipeline, and the reference policy

Test plan

• python src/validate.py — 71 rules, 0 failures
• python src/build.py — 8 sections, 71 rules, 186,855 bytes
• python src/extract_tests.py — 71 cases extracted, 0 skipped
• Spot-check several of the rewritten rules (api-deprecated-aliases, both new error-assert-* rules, error-trust-validated-state, simplify-cached-property, perf-isinstance-tuple-syntax)
• Spot-check the new rules (especially data-mutable-defaults, error-context-managers, data-aware-datetimes)

🤖 Generated with Claude Code