claude-dev-env 1.19.1 → 1.19.3

package/docs/CODE_RULES.md

@@ -44,7 +44,7 @@ These rules are automatically enforced by `code-rules-enforcer.py`. Violations b
 | No NEW comments | `#` / `//` in new code only (existing comments NEVER removed; shebangs, type:, noqa, eslint, docstrings exempt) |
 | Imports at top | No `import` inside function bodies |
 | Logging format args | No `log_*(f"...")` - use `log_*("...", arg)` |
-| File line count | Max 400 lines per file |
+| File line count | Advisory only — see [File length guidance](#65-file-length-guidance) |
 | Magic values | No literals in function bodies (0, 1, -1 exempt). Includes string templates — if you strip the interpolations from an f-string and the remaining literal text is structural (paths, URLs, patterns), those fragments are magic values that belong in config |
 | Constants location | No `UPPER_SNAKE =` outside `config/` |
 
@@ -121,6 +121,28 @@ def function_name(
 
 ---
 
+## 6.5 FILE LENGTH GUIDANCE
+
+File length is a **smell signal, not a hard threshold**. Long files often hide multiple responsibilities, but legitimately long files exist (migrations, generated code, registries, fixtures). The hook surfaces advisories instead of blocking.
+
+**Two advisory thresholds (non-blocking, stderr only):**
+
+| Threshold | Source basis | Hook behavior |
+|-----------|--------------|---------------|
+| `>= 400` lines | Robert C. Martin, *Clean Code* (2008), Ch. 5 "Formatting" — small files preferred; Martin Fowler, *Refactoring* — "Large Class" code smell | Soft advisory: "consider splitting" |
+| `>= 1000` lines | pylint default `max-module-lines=1000`; SonarQube rule S104 default `1000` | Strong nudge: "exceeds widely-used static-analysis defaults" |
+
+**What we deliberately reject:**
+
+- **Hard numeric blocks** — Google's Python Style Guide imposes no file-length cap (only a ~40-line function review hint at https://google.github.io/styleguide/pyguide.html). A blocking rule produces false positives on legitimate cases.
+- **A single magic number** — Different sources land at 200 (*Clean Code* preference), 750 (some SonarQube language profiles), or 1000 (pylint, Sonar Java). No source justifies a single universal cap.
+
+**When to actually split:**
+
+The size signal matters *because* of what it usually indicates: multiple responsibilities (Single Responsibility Principle — Robert C. Martin, *Agile Software Development*, 2002), poor cohesion (Steve McConnell, *Code Complete 2e*, 2004, Ch. 5–6), or the "Large Class" / "Long Function" smells (Fowler). Use the readability rubric (`~/.claude/skills/readability-review/SKILL.md`) when an advisory fires — split based on cohesion, not line count.
+
+---
+
 ## 7. RIGHT-SIZED ENGINEERING
 
 **Simple > Clever. Functions > Classes. Concrete > Abstract.**
@@ -175,7 +197,7 @@ Hook will enforce:
 [⚡] No magic values
 [⚡] Imports at top
 [⚡] Logging format args
-[⚡] File under 400 lines
+[ ] File length reasonable (advisory at 400, strong nudge at 1000 — see §6.5)
 [⚡] Constants in config/
 
 Manual check:

package/hooks/blocking/code-rules-enforcer.py

@@ -2,15 +2,17 @@
 """
 CODE_RULES.md enforcer - blocks code that violates mandatory rules.
 
-Checks (all blocking):
+Checks (blocking):
 1. No comments (# or // in code, excluding shebangs/type: ignore)
 2. Imports at top (no imports inside functions)
 3. Logging f-strings (log_* calls must use format args)
-4. File line count (>400 blocks)
-5. Windows API None (win32gui calls with None parameter)
-6. Magic values (literals in function bodies)
-7. E2E test naming (no online/offline in test names)
-8. Constants outside config (UPPER_SNAKE = in non-config files)
+4. Windows API None (win32gui calls with None parameter)
+5. Magic values (literals in function bodies)
+6. E2E test naming (no online/offline in test names)
+7. Constants outside config (UPPER_SNAKE = in non-config files)
+
+Advisory only (non-blocking):
+- File line count: stderr warning at 400 lines (soft) and 1000 lines (hard)
 """
 import json
 import re
@@ -27,6 +29,9 @@ HOOK_INFRASTRUCTURE_PATTERNS = {"/.claude/hooks/", "\\.claude\\hooks\\", "\\.cla
 WORKFLOW_REGISTRY_PATTERNS = {"/workflow/", "\\workflow\\", "_tab.py", "/states.py", "\\states.py", "/modules.py", "\\modules.py"}
 MIGRATION_PATH_PATTERNS = {"/migrations/", "\\migrations\\"}
 
+ADVISORY_LINE_THRESHOLD_SOFT = 400
+ADVISORY_LINE_THRESHOLD_HARD = 1000
+
 
 def get_file_extension(file_path: str) -> str:
     """Extract lowercase file extension."""
@@ -308,12 +313,27 @@ def check_logging_fstrings(content: str) -> list[str]:
     return issues
 
 
-def check_file_line_count(content: str) -> list[str]:
-    """Check file line count."""
-    line_count = content.count("\n") + 1
-    if line_count > 400:
-        return [f"File has {line_count} lines (max 400) - split into smaller modules"]
-    return []
+def advise_file_line_count(content: str, file_path: str) -> None:
+    """Emit non-blocking stderr advisories when a file crosses size smell thresholds.
+
+    Thresholds are smell signals, not hard caps. See CODE_RULES.md "File length guidance"
+    for rationale. Soft threshold aligns with Clean Code Ch. 5 / Fowler "Large Class".
+    Hard threshold matches pylint default max-module-lines and SonarQube S104 default.
+    """
+    line_count = len(content.splitlines())
+    if line_count >= ADVISORY_LINE_THRESHOLD_HARD:
+        print(
+            f"[CODE_RULES advisory] {file_path}: {line_count} lines - "
+            f"exceeds pylint/SonarQube default ({ADVISORY_LINE_THRESHOLD_HARD}); "
+            f"strongly consider splitting by responsibility (SRP / cohesion)",
+            file=sys.stderr,
+        )
+    elif line_count >= ADVISORY_LINE_THRESHOLD_SOFT:
+        print(
+            f"[CODE_RULES advisory] {file_path}: {line_count} lines - "
+            f"consider splitting (Clean Code Ch. 5; Fowler 'Large Class' smell)",
+            file=sys.stderr,
+        )
 
 
 def check_windows_api_none(content: str) -> list[str]:
@@ -485,7 +505,7 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_e2e_test_naming(content, file_path))
 
     if extension in ALL_CODE_EXTENSIONS:
-        all_issues.extend(check_file_line_count(content))
+        advise_file_line_count(content, file_path)
 
     return all_issues
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.19.1",
+    "version": "1.19.3",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/skill-builder/SKILL.md

@@ -62,8 +62,8 @@ The feedback loop: observe Claude B's behavior, bring insights back, refine the
 
 When building a **new** skill as a **full package** (architecture inventory, progressive disclosure files, `evals/`, **human checkpoint after each file**), treat the following as **mandatory** before implementation:
 
-- **Read:** `prompt-generator/templates/skill-from-ground-up.md` inside the claude-dev-env `skills/` directory (repository path: `packages/claude-dev-env/skills/prompt-generator/templates/skill-from-ground-up.md`).
-- **Do:** Run `/prompt-generator` with that file’s token table filled so the downstream session follows architecture-first sequencing, per-file review gates, and eval rows tied only to user-pasted or explicitly approved evidence.
+- **Read:** the installed `@jl-cmd/prompt-generator` template `prompt-generator/templates/skill-from-ground-up.md` (upstream repository path: `skills/prompt-generator/templates/skill-from-ground-up.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
+- **Do:** Run `/prompt-generator` using that installed template with the file’s token table filled so the downstream session follows architecture-first sequencing, per-file review gates, and eval rows tied only to user-pasted or explicitly approved evidence.
 
 Use this **together with** gap-analysis and eval-scenario templates in this package; the ground-up template supplies the **orchestration contract** for the multi-file layout Anthropic recommends.
 
@@ -71,7 +71,7 @@ Use this **together with** gap-analysis and eval-scenario templates in this pack
 
 When **improving** an existing skill as a **multi-file** or **checkpointed** package (baseline directory plus planned deltas, observation-grounded evals), treat the following as **mandatory** before Phase 2–6 file work in `improve-skill.md` or package-aware steps in `polish-skill.md`:
 
-- **Read:** `prompt-generator/templates/skill-refinement-package.md` (repository path: `packages/claude-dev-env/skills/prompt-generator/templates/skill-refinement-package.md`).
+- **Read:** `prompt-generator/templates/skill-refinement-package.md` (repository path: `skills/prompt-generator/templates/skill-refinement-package.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
 - **Do:** Run `/prompt-generator` with that file’s token table filled (`[[BASELINE_SKILL_ROOT]]`, `[[WORKSPACE_ROOT]]`, observation gap path, evidence rule) so rollout stays architecture-first, delta-focused, and tied to real observation or approved excerpts.
 
 Net-new packages without a baseline skill directory use `skill-from-ground-up.md` instead.

package/skills/skill-builder/workflows/improve-skill.md

@@ -55,7 +55,7 @@ From here, follow the same phases as `${CLAUDE_SKILL_DIR}/workflows/new-skill.md
 
 Whenever Phases 2–6 will touch **multiple files**, **progressive disclosure layout**, or use **checkpointed file-by-file rollout**, treat this as **required** before expanding or rewriting the tree:
 
-1. Read `prompt-generator/templates/skill-refinement-package.md` from the claude-dev-env `skills/` tree (repository path: `packages/claude-dev-env/skills/prompt-generator/templates/skill-refinement-package.md`).
+1. Read `skill-refinement-package.md` from the installed prompt-generator skill, typically at `~/.claude/skills/prompt-generator/templates/skill-refinement-package.md` (source dependency: [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
 2. Run `/prompt-generator` with that template’s token table filled: set `[[BASELINE_SKILL_ROOT]]` to the existing skill directory, `[[WORKSPACE_ROOT]]` to your iteration workspace (in-place or snapshot per user preference), and `[[DESIGN_INPUT_GLOB]]` to this workflow’s observation-based `gap-analysis.md` when it exists.
 
 Use `skill-from-ground-up.md` **only** for **greenfield** packages where no baseline skill directory exists yet; use `skill-refinement-package.md` for every refinement anchored to an existing skill.

package/skills/skill-builder/workflows/new-skill.md

@@ -11,7 +11,7 @@ Full evaluation-driven lifecycle for building a new skill from scratch.
 
 When the outcome includes **ARCHITECTURE.md**, **REFERENCE / EXAMPLES / WORKFLOWS**, and **`evals/*.json`** under a workspace (Anthropic-style progressive disclosure plus checkpointed rollout):
 
-1. Read `prompt-generator/templates/skill-from-ground-up.md` from the claude-dev-env `skills/` tree (repository path: `packages/claude-dev-env/skills/prompt-generator/templates/skill-from-ground-up.md`).
+1. Read `prompt-generator/templates/skill-from-ground-up.md` from the installed `~/.claude/skills/` tree (provided by [@jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
 2. Run `/prompt-generator` using that template (substitute tokens per its table) **before** Phase 3 expands the repo; align the XML scope block with this workflow’s workspace and evidence rules.
 3. Keep Phase 1–2 artifacts honest: eval prompts and expectations stay grounded in **real** user scenarios; the template reinforces eval rows that reference pasted or explicitly approved evidence only.
 

package/skills/skill-builder/workflows/polish-skill.md

@@ -12,7 +12,7 @@ Final optimization pass for a skill that is functionally complete.
 
 When the polish pass will touch **more than frontmatter alone** (for example `REFERENCE.md`, `EXAMPLES.md`, `WORKFLOWS.md`, link structure, or eval JSON), or the user wants **checkpointed** multi-file updates alongside description work:
 
-1. Read `prompt-generator/templates/skill-refinement-package.md` (repository path: `packages/claude-dev-env/skills/prompt-generator/templates/skill-refinement-package.md`).
+1. Read `prompt-generator/templates/skill-refinement-package.md` (repository path: `skills/prompt-generator/templates/skill-refinement-package.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
 2. Run `/prompt-generator` with tokens filled so `ARCHITECTURE.md` records baseline inventory, planned deltas for polish, and evidence rules for any new trigger or behavior evals.
 
 Purely **single-field** `description` edits with no structural package changes can skip this block.

package/skills/skill-writer/SKILL.md

@@ -36,7 +36,7 @@ When invoked with arguments (e.g. `/skill-writer improve this: [paste]`), treat
 
 When the user is creating a **new** skill as a **package** (workspace with `ARCHITECTURE.md`, `REFERENCE.md`, `EXAMPLES.md`, `WORKFLOWS.md`, `evals/*.json`, per-file human review), **before** drafting `SKILL.md`:
 
-1. Read `packages/claude-dev-env/skills/prompt-generator/templates/skill-from-ground-up.md` (installed layout: sibling folder `prompt-generator/templates/skill-from-ground-up.md` under the same `skills/` parent).
+1. Read `prompt-generator/templates/skill-from-ground-up.md` (installed layout: sibling folder under the same `skills/` parent; repository path: `skills/prompt-generator/templates/skill-from-ground-up.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
 2. Ensure `/prompt-generator` has run with that template filled so architecture-first steps, checkpoint gates, and eval evidence rules are already agreed.
 
 If the task is **only** editing an existing `SKILL.md` or a small single-file tweak, this subsection does not apply.
@@ -45,7 +45,7 @@ If the task is **only** editing an existing `SKILL.md` or a small single-file tw
 
 When the user is **refining** an existing skill as a **package** (baseline skill directory, `ARCHITECTURE.md` with planned deltas, checkpointed updates to REFERENCE / EXAMPLES / WORKFLOWS / `evals/`), **before** rewriting multiple files:
 
-1. Read `packages/claude-dev-env/skills/prompt-generator/templates/skill-refinement-package.md` (installed layout: `prompt-generator/templates/skill-refinement-package.md` under the same `skills/` parent).
+1. Read `prompt-generator/templates/skill-refinement-package.md` (installed layout: under the same `skills/` parent; repository path: `skills/prompt-generator/templates/skill-refinement-package.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
 2. Ensure `/prompt-generator` has run with that template filled so baseline root, workspace root, observation inputs, and evidence rules are fixed before edits proceed.
 
 If the change set is a **small single-file** tweak, this subsection does not apply.