Add refactor_claude_todo.md: 250-line file-length cap

A ready-to-use prompt describing the goal (every file at most 250 lines,
code and prose alike), this repo's actual violations ranked by Fowler ROI
(lines x commits/yr), how to split each kind, and the requirement to wire in
the shared pre-commit gate so files stay small permanently.

Generated from a measured survey of every repo; the gate itself lives in
~/utils (file_length/ + scripts/check_file_length.sh).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C7yZz45ezmzCB89Cv5gAtZ

refactor_claude_todo.md

@@ -0,0 +1,96 @@
+# Refactor TODO — enforce the 250-line file cap
+
+> **This file is a ready-to-use prompt.** Paste it to Claude, or open this repo
+> and say "do refactor_claude_todo". It is self-contained: everything needed to
+> execute is below. Generated 2026-08-14 from a measured survey of every repo.
+
+## Goal
+
+Every file in this repo must be **at most 250 lines** — source, tests, and
+prose (`.md`/`.txt`/`.rst`/`.tex`) alike — and must **stay** that way forever,
+enforced by a gate that fails the commit, not by a note anyone can ignore.
+
+Why: a file that cannot be read in one piece forces re-reads and partial edits,
+which is the single largest avoidable cost in an LLM-assisted workflow. Aim by
+churn, not size alone — refactoring pays where code is read and changed often
+(Fowler, _refactoring economic benefit_).
+
+## Scope in this repo
+
+- **200 files** currently exceed 250 lines (of 807 eligible files).
+- **88,451 lines** sit in violation; longest file is **2053 lines**.
+
+Exempt (do NOT split these):
+
+- generated files — `*.g.dart`, `*.freezed.dart`, `*.gr.dart`, `**/l10n/generated/**`,
+  anything with a `GENERATED` header
+- markup — `.html`, `.css`, `.scss`
+- data files — `.json`, `.yaml`, `.csv`, wordlists and other data-ish `.txt`
+  (mean line length under 25 chars)
+
+## Violations, highest ROI first
+
+ROI = lines x commits in the last year. Work top-down; a long file nobody edits
+has near-zero payoff and should not be first.
+
+| lines | commits/yr | kind  | file                                                                                           |
+| ----: | ---------: | :---- | :--------------------------------------------------------------------------------------------- |
+|   556 |         41 | code  | `phone_focus_mode/config.sh`                                                                   |
+|  1734 |          9 | code  | `linux_configuration/scripts/periodic_background/digital_wellbeing/setup_midnight_shutdown.sh` |
+|   833 |         15 | code  | `phone_focus_mode/deploy.sh`                                                                   |
+|  1337 |          8 | code  | `linux_configuration/scripts/periodic_background/check_and_enable_services.sh`                 |
+|  1091 |          9 | code  | `phone_focus_mode/focus_ctl.sh`                                                                |
+|   543 |         12 | code  | `phone_focus_mode/focus_daemon.sh`                                                             |
+|   929 |          6 | code  | `linux_configuration/scripts/periodic_background/digital_wellbeing/pacman/pacman_wrapper.sh`   |
+|   564 |          9 | code  | `focus_owner/android/app/src/main/kotlin/com/kuhy/focus_owner/EnforcementRunner.kt`            |
+|   918 |          5 | code  | `linux_configuration/scripts/periodic_background/digital_wellbeing/setup_night_lockdown.sh`    |
+|   912 |          5 | code  | `linux_configuration/scripts/periodic_background/hosts/install.sh`                             |
+|   258 |         16 | prose | `CLAUDE.md`                                                                                    |
+|   698 |          5 | code  | `reverse_survivors/src/core/sim.test.ts`                                                       |
+|   620 |          5 | code  | `linux_configuration/scripts/lib/common.sh`                                                    |
+|   415 |          7 | code  | `focus_owner/android/app/src/main/kotlin/com/kuhy/focus_owner/DevicePolicyBridge.kt`           |
+|   912 |          3 | code  | `linux_configuration/scripts/single_use/features/setup_searxng.sh`                             |
+
+_(185 further files over 250 lines not listed — re-run the survey for the full set.)_
+
+## How to split
+
+- **Python** — extract cohesive helpers into sibling modules; keep the public
+  API and imports stable.
+- **Shell** — split into `lib/*.sh` sourced by a thin entry script. Keep
+  `set -euo pipefail` in each.
+- **Dart / TypeScript** — extract widgets/components into their own files.
+- **Tests** — split by test-group into sibling files
+  (`foo.test.ts` -> `foo.parsing.test.ts`, `foo.render.test.ts`). Coverage must
+  not drop.
+- **Docs** — split into topic files under `docs/` with an index. For an
+  oversized `CLAUDE.md`, move detail into referenced docs so the
+  always-loaded part shrinks.
+
+**Do not** game the cap: no one-lining, no deleting tests, no moving code into
+an exempt extension, no `# noqa`-style suppressions.
+
+## Make it permanent (required — this is the point)
+
+A refactor without a gate silently regrows. Before this task is done:
+
+1. Wire the shared gate `~/utils/scripts/check_file_length.sh` into this repo's
+   `.pre-commit-config.yaml` as a local hook. If the repo has no pre-commit
+   config, add a minimal one.
+2. The hook checks **files in the commit** (not the whole tree), so unrelated
+   commits never break, and it **fails** — exit 1, not a warning.
+3. No baseline file and no allowlist. Those are suppressions.
+4. If this repo has CI (`.github/workflows`), add the same check there so it
+   also fails on push.
+
+## Done condition
+
+- `bash ~/utils/scripts/check_file_length.sh --all` from this repo root exits 0.
+- The repo's own test suite and coverage bar are still green.
+- `pre-commit run --files <changed files>` passes.
+- A deliberately over-250-line test file, staged, makes `git commit` **fail**.
+- For a deployed daemon/app: the entry point still actually runs.
+
+## Verify
+
+Many scripts here run from systemd timers and the working tree. After splitting a script, run it directly and confirm the timer unit still resolves its path.