Skip to content

CLAUDE.md advertises a craftsmanship-checker size gate (300 lines/file, 40 lines/method) that does not exist #297

Description

@cdeust

Finding (measured, not assumed)

CLAUDE.md "Code Style" states:

300 lines max per file; 40 lines max per method. Enforced by the
craftsmanship-checker pre-commit hook.

That hook does not exist. Verified 2026-07-30:

  • No file matching *craftsmanship* anywhere in the tracked tree.
  • No non-sample hook in .git/hooks/ (only .sample templates).
  • No .pre-commit-config.yaml.
  • No CI job in .github/workflows/ci.yml checking file or method length
    (the lint job runs ruff format/ruff check, doc-claims, badges,
    uv.lock/pip-constraints sync, and actionlint — none measure length).
  • scripts/install_hooks.py exists but is unrelated: it migrates legacy
    Claude Code session hooks out of ~/.claude/settings.json, not a git
    pre-commit hook.

The caps have been documented and unenforced. PR #284 shipped a 54-line
method (run_stdio_drained, over both the general §4.2 50-line cap and
this repo's own stricter 40-line convention) through 19 passing checks
before a manual review caught it (see docs/provenance/ / PR #284 history)
— nothing automated would have.

Acceptance criteria

  • A real, blocking CI gate (wired into the lint job) measures file length
    and per-function/method length (signature-to-close, AST lineno..
    end_lineno) against the 300/40 caps, with sanctioned exemptions only
    (auto-generated file marker; pure match-statement dispatch functions).
  • Negative-control tests prove the gate rejects a deliberately over-cap
    file and function.
  • The gate is run against the full current tree and reports every existing
    breach; a large pre-existing backlog is handled via a committed, dated
    ratchet baseline that can shrink but never grow (tracked separately, see
    follow-up issue for the backlog itself).
  • An optional local pre-commit hook is also provided.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions