From d6b376effb6e0010c0be92f172a854d71747773b Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sun, 16 Aug 2026 15:29:27 +0200 Subject: [PATCH] Add a resume prompt for the file-length refactor 192 of the original 198 violations remain and the work spans more sessions than one context window holds. This is the handoff: paste it into a fresh session. Deliberately points at `check_file_length.sh --all` as the live worklist rather than enumerating files, so it cannot go stale, and records the traps that cost time -- above all that the gate must be wired LAST, because ci-mirror runs `pre-commit --all-files` on pre-push and would otherwise block every push for the rest of the effort. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY --- refactor_claude_todo_resume.md | 143 +++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 refactor_claude_todo_resume.md diff --git a/refactor_claude_todo_resume.md b/refactor_claude_todo_resume.md new file mode 100644 index 00000000..4021052f --- /dev/null +++ b/refactor_claude_todo_resume.md @@ -0,0 +1,143 @@ +# Resume: enforce the 250-line file cap + +> **Paste this whole file to a fresh Claude session opened in `~/testsAndMisc`.** +> It is self-contained. Continues `refactor_claude_todo.md`, which is still the +> spec — read it too, but the decisions below override it where they differ. + +## Where things stand + +**192 files** over 250 lines (was 198). All work so far is committed and pushed +to `main`; `git status` is clean apart from pre-existing unrelated edits to +`README.md`, `billsplit/analysis_options.yaml`, `focus_owner/analysis_options.yaml` +— **leave those three alone, they are not yours.** + +Done already (do not redo): + +| Commit | What | +| --------- | -------------------------------------------------------------------- | +| `~/utils` | `plans/` + `sessions/` exempted from the cap (`specs/` still capped) | +| `17b20e5` | New `no-inline-python` pre-commit hook + the one violation fixed | +| `004b4b0` | `CLAUDE.md` 259 → 141 lines | +| `72a5e28` | `poker-stakes/` tracked in git (58 files) | +| `73b85f5` | `poker-stakes/` 4 violations → 0 | + +## The live worklist + +Do not work from a list in this file — it goes stale. Run: + +```bash +bash ~/utils/scripts/check_file_length.sh --all +``` + +Current distribution: `linux_configuration` 84, `python_pkg` 50, +`phone_focus_mode` 13, `kcd2_dice_solver` 12, `focus_owner` 11, `billsplit` 6, +`reverse_survivors`/`meta`/`docs` 4 each, `.github`/`bucket_catch` 2 each. +**48 of them are near-misses at 251–300 lines** — highest count-drop per unit +of effort, do these first. + +## Decisions already made (do not re-ask) + +1. **Full clearance** to `--all` exit 0. When context runs out, write a fresh + handoff like this one rather than stopping mid-way. +2. **CI checks only files in the push/PR range**, not `--all`. +3. `docs/superpowers/plans/**` + `sessions/**` are exempt — already done. +4. `poker-stakes/` is tracked — already done. +5. For prose: automate what can be automated, delete the automated lines, keep + only HOW, never WHY. +6. Shell verification is `bash -n` + `shellcheck` + `systemctl cat` path checks. + **Never execute enforcement scripts that mutate the phone or the live system.** +7. One commit per logical unit. + +## The constraint that will bite you + +**Wire the file-length gate LAST**, only once `--all` already exits 0. + +`meta/scripts/ci_mirror.sh:109` runs `pre-commit run --all-files` as a +**pre-push** hook, and `.github/workflows/pre-commit.yml:105` does the same in +CI. Registering the hook while violations remain makes **every `git push` fail** +until the last file is fixed. Do not scope around it with `exclude:`/`files:` — +that is the allowlist the spec forbids. + +Final commit, once and only once the tree is clean: + +```yaml +- id: file-length + name: file length <= 250 lines + entry: bash /home/kuhy/utils/scripts/check_file_length.sh + language: system +``` + +Plus `.github/workflows/file-length.yml` modelled on +`~/todo/.github/workflows/file-length.yml` (checks out `kuhyx/utils` into +`.utils`), scoped to changed files. Then prove it fails: stage a deliberately +251-line file, confirm `git commit` aborts, delete it. + +## Split recipes + +- **Shell** — extract into `lib/*.sh` sourced by a thin entry script, + `set -euo pipefail` in each. Follow `phone_focus_mode/lib/` and + `linux_configuration/scripts/lib/common.sh`. +- **Python** — extract cohesive helpers into sibling modules; keep the public + API stable by re-exporting. +- **TS/Dart** — extract components; re-export from the original path so no + importer changes. +- **Tests** — split by describe/test-group. Coverage must not drop. + +Never game the cap: no one-lining, no deleting tests, no moving code into an +exempt extension, no suppressions. + +## Traps that cost time in the last session + +- **Test fixtures and coverage.** When splitting a test file, shared helpers + must go where the coverage config already excludes them (in `poker-stakes` + that is `src/test/**`, matched **by path**). Putting them beside the source + makes the coverage tool count them as production code and the 100% gate + fails. Move the file; do **not** add a `coverage.exclude` entry. +- **`end-of-file-fixer` aborts commits.** Files built with `sed`/`cat` often + lack a trailing newline. The hook fixes it and then fails the commit + ("files were modified by this hook"). Just `git add` again and re-commit. +- **Formatters silently revert edits.** A PostToolUse formatter stripped an + added import twice. After editing, `grep` the file to confirm the change + survived before running anything. +- **Contracts.** Staging **≥4 code files** requires a _fresh_ + `docs/superpowers/contracts/*.json` in that same commit, on top of the + per-commit `docs/superpowers/evidence/*.json`. Required keys: `title`, + `objective`, `acceptance_criteria`, `out_of_scope`, `verifier`. Validate with + `python3 meta/scripts/validate_contract.py `. +- **`invariants.test.ts` in poker-stakes** flakes on its 5s timeout under + parallel coverage load. It passes standalone in ~2.6s. Not a regression — + do not "fix" it by weakening the test. +- **Long commands**: background anything over ~60s rather than blocking. + +## `phone_focus_mode` — highest blast radius, do it LAST + +Two silent failure modes: + +1. **`deploy.sh` has a hardcoded flat push list** (search for `adb_cmd push`, + around lines 374–383) with **no `lib/` subdirectory**. Every new split lib + must be added there in the same commit, or the phone sources a missing file + at runtime — gate green, tests green, device broken. +2. **`config.sh` (556 lines) is sourced by 11 scripts.** Keep `config.sh` as + the entry point that re-sources its own parts, so all 11 callers keep + working untouched. + +Static check after each split: grep `deploy.sh`'s push list and every +`source`/`.` line in `phone_focus_mode/*.sh` and confirm each new lib appears. + +## Suggested order + +1. The 48 near-misses (251–300) — mechanical, biggest count drop. +2. `python_pkg` (50) — `pytest-coverage` gates each changed package on commit. +3. `linux_configuration` (84) — largest; check systemd unit paths still resolve. +4. `kcd2_dice_solver`, `focus_owner`, `billsplit`, the rest. +5. `phone_focus_mode` (13) — with the guard above. +6. Gate wiring + CI workflow — last. + +## Done condition + +```bash +cd ~/testsAndMisc && bash ~/utils/scripts/check_file_length.sh --all # exit 0 +pre-commit run --all-files # passes +``` + +Plus: a staged 251-line file makes `git commit` fail.