feat(precommit): pluggable step framework + doctest/typecheck/doc-consistency steps

[misnaej]

Closes #6, #5, #48, #46. Folds in the tokenize bug fix (ex-#56). Addresses #4 (v1 scope). Follow-up: #57 (dogfood pyrefly on forge).

One cohesive PR for the pre-commit step subsystem — per CLAUDE.md's new PR-granularity rule (also added here), related work ships together rather than fragmenting into parallel PRs.

Summary

Turns the hardcoded step tuple into a registry with a uniform on/off layer, ships three opt-in pluggable steps, and folds in a real bug those steps surfaced. MINOR → v1.24.0.

Changes

• feat: uniform [tool.forge.precommit] config to enable/disable steps #6 framework — StepDef registry (SSoT for name/fn/default-on); [tool.forge.precommit] enable/disable + forge-precommit --only/--skip. Override sits over each step's self-skip; disable beats enable; unknown names → clean error, no traceback. run_all dispatches through the module namespace (keeps steps monkeypatchable).
• feat: doctest pre-commit step + CI integration #5 doctest — opt-in pytest --doctest-modules; non-blocking default; 'no items ran' → skip.
• feat: add a configurable (pluggable) type-checking step to forge-precommit #48 typecheck — opt-in, runs pyrefly (single checker, per maintainer — no mypy/ty/pyright menu); non-blocking default; missing binary fails loudly.
• feat: verify-forge-doc-consistency — check doc claims against repo state #4 doc_consistency (v1) — opt-in step + verify-forge-doc-consistency CLI: CLI name-lists + agent counts vs disk. Non-blocking.
• forge-config: enforce CONFIG_KEYS registry against actual config readers #46 — new [tool.forge.*] keys in CONFIG_KEYS + two drift tests coupling the registry to its readers.
• Security — config-supplied paths validated (reject option-like / repo-escaping) before subprocess argv.
• Bug fix (ex-fix(audit): catch tokenize.TokenError, not the nonexistent TokenizeError #56) — tokenize.TokenError not the nonexistent TokenizeError in 3 audit modules (broken except clauses → AttributeError); surfaced by pyrefly while dogfooding the typecheck step. + regression test.
• Tooling — dev/setup.sh installs the [dev] umbrella (test+audit+typecheck), not just [test]; typecheck extra declares pyrefly.
• Docs — configuration.md, CHANGELOG v1.24.0 (authored on dev per release-process §5), CLAUDE.md PR-granularity guideline, REPO_STRUCTURE, regenerated api-digest/cli-reference. Bump → 1.24.0.

Testing

~38 new tests (framework precedence, all three steps + edge cases, the CLI, #46 drift, tokenize regression). Full suite green. Dogfood: verify-forge-doc-consistency passes on forge.

Breaking Changes

None — every new step is opt-in and off by default; existing behavior unchanged.

[misnaej]

Squash-merge message (copy verbatim):

feat(precommit): pluggable step framework + opt-in steps

- StepDef registry with --only/--skip/enable/disable overrides (closes #6)
- Three opt-in steps: doctest, pyrefly typecheck, doc-consistency CLI (closes #5, #48, #4)
- Config-path validation; CONFIG_KEYS drift tests (closes #46)
- Fix tokenize.TokenError in audit modules; regression test (closes #56)

[misnaej]

PR Verification Results

verified-at: d46bd3a (PR #55, branch feat/precommit-step-framework)

Pre-run reports were generated at commit 4ae47b4. All LOW/MEDIUM findings were addressed in d46bd3a (current HEAD). Reports used directly per the pre-run fast-path.

Design Check

PASS (minor issues resolved). Clean additive: StepDef registry, _resolve_steps, --only/--skip, three opt-in steps, verify-forge-doc-consistency CLI. MEDIUM finding (run_all dispatches via module namespace for test monkeypatching) kept by deliberate choice — refactoring to monkeypatch the registry would churn production + tests for a style preference; accepted with improved explanatory comment. LOWs resolved: dead "no items ran" branch removed; _bad_scan_paths annotation fixed to list[object]; --skip now subtracts from --only set.

Security Review

PASS. All subprocess calls list-form with shell=False; config paths validated via Path.resolve().relative_to(repo_root). LOWs resolved: _bad_scan_paths now rejects empty/whitespace paths; pyrefly pinned >=1,<2. Tokenize fix is a correctness fix with no security impact.

Documentation Check

PASS. _bad_scan_paths annotation corrected to list[object]; step_doc_consistency docstring trimmed to reflect v1 scope (CLI names + agent counts only, not skill/hook/plugin.json). No remaining errors.

Issue Management

PR description carries bare Closes #6, #5, #48, #46 on the first line — auto-close wired correctly. #56 already closed prior to this PR landing. #4 addressed in v1 scope (name-lists + counts) via Addresses #4 — intentionally not auto-closed; v2+ work tracked in open issue. Follow-up #57 (dogfood pyrefly on forge, strict config + triage remaining type findings) filed and open — no action needed here.

Code Quality (from code_health/ logs)

• Ruff: PASS — 87 files unchanged, all checks passed
• Docstring verification: PASS — 0 errors, 0 warnings, 5 info (verbose fixture docstrings, non-blocking)
• Docstring coverage: PASS — 100.0% (1199/1199 symbols)
• Test naming: PASS — 27 files, 0 issues
• Repo structure: PASS — 133 paths in sync
• Manifest JSON: PASS
• CLI wiring: PASS
• Commit types parity: PASS
• Plugin version: PASS — plugin.json 1.24.0 > latest tag 1.23.2
• pip_audit: SKIP (pip-audit not on PATH)
• CI: SUCCESS (GitHub Actions ci check at d46bd3a)

Recommendation: Ready for merge. Squash-merge message posted above.

[misnaej]

Follow-up (dcb7ad9): trimmed doc_consistency scope further per review. Dropped the agent-count check entirely — it needed a hardcoded 0–20 number-word table and depended on exact prose phrasing ("twelve foundation agents"), a maintenance burden for low signal. verify-forge-doc-consistency now does only the robust, zero-maintenance check: every [project.scripts] CLI is documented in docs/cli-reference.md. Squash-merge message above is unaffected.