Rewrites the driver doc as a self-contained fresh-session prompt: supersedes the one-file-per-session pacing decision (user asked for batching), adds an explicit "do not ask should I continue" preamble, orders the remaining 8 shell files into a safe tier and a deployment-trap tier, and points at the pacman_hook_stall_* family as the worked reference split with harness + entry-harness pattern. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
13 KiB
Next session: Phase-driven campaign — CI green → 250-cap zero → gates → shell coverage
Paste this whole file into a fresh Claude session opened in
~/testsAndMisc. It is self-contained. Do not go looking for the previous session's context.
This file drives a multi-session campaign with four phases, run strictly in order. Do not skip ahead to a later phase while an earlier one is incomplete — re-check the phase's exit condition at the start of every session, even if this doc claims it's done, since state can drift between sessions.
The user's request that created this campaign (verbatim intent): make it true FOR SURE that all files are under the 250-line cap, then add a 100% shell test-coverage gate, then add a pre-commit rule that blocks commits when any file is over 250 lines AND checks that GitHub Actions is green on this repo.
How to run this session (read before anything else)
Do not ask "should I continue?" between files. The queue below is already
approved. Work it to completion, or until you hit a genuine design fork or an
irreversible action. Ending a turn to narrate progress mid-queue is a bug —
summarise once, at the end. This was violated twice in the previous session
despite being written in ~/.claude/memories/workflow-rules.md; it is
repeated here because the standing rule alone did not hold.
Standing decisions — do NOT re-litigate:
- 100% line coverage on what you extract/write tests for — same bar every prior split has used.
- Split blind where there is no device. Do not deploy to the phone, do not ask to. Prove splits with tests, hashes and real runs instead.
- CI must be fixed before any new gate is added. (Phase 0 is done; this just means don't add a gate on top of a red baseline if CI regresses.)
- The shell coverage gate is a NEW, separate requirement covering every
.shfile repo-wide. That is Phase 3 — do not conflate it with Phase 1.
The old "one file split per session" pacing decision is superseded: the user explicitly asked for multiple files per session ("this is a very slow way of doing it"). Batch through the queue.
Phase 0: CI green — DONE 2026-08-18, re-verify only
gh run list --limit 5 should show Pre-commit checks, Shell tests and
Python tests green on main. Fixed by adding librsvg2-bin to both
workflows (4326ea4) and making python-tests.yml self-triggering +
workflow_dispatch (4a35be7).
Two traps worth keeping:
python-tests.ymlis path-filtered. A commit touching only workflow files or only non-Python paths will NOT trigger it — that is expected, not a failure. Check the workflow's own last run rather than assuming.gh run rerunreplays the historical commit's workflow YAML, notmain's current one. It cannot verify a workflow-file fix. Push a real commit under a watched path instead.
Phase 1: Drive the 250-line cap to zero — IN PROGRESS, 8 files left
Re-run bash meta/scripts/check_file_length.sh --all first; the list drifts.
1734 linux_configuration/scripts/periodic_background/digital_wellbeing/setup_midnight_shutdown.sh
1225 linux_configuration/scripts/periodic_background/check_and_enable_services.sh
1017 linux_configuration/scripts/single_use/utils/generate_study_materials.sh
929 linux_configuration/scripts/periodic_background/digital_wellbeing/pacman/pacman_wrapper.sh
918 linux_configuration/scripts/periodic_background/digital_wellbeing/setup_night_lockdown.sh
913 linux_configuration/scripts/periodic_background/hosts/install.sh
705 linux_configuration/scripts/periodic_background/digital_wellbeing/block_compulsive_opening.sh
485 linux_configuration/scripts/periodic_background/digital_wellbeing/install_leechblock.sh
Everything remaining is a shell script. All three focus_owner files are
done (47e05d1, 6efb4ba, 7d7b3c7) — that repo is confirmed live and
enforcing, not a dead-code candidate.
The queue, in this order
Safe tier — do these first, no deployment trap:
check_and_enable_services.sh(1225) — alib/already exists beside it atlinux_configuration/scripts/periodic_background/lib/(currently holds onlyperiodic_browser.sh), but nolib/tests/yet — you will create it. Referenced byinstall_makepkg_wrapper.shandpacman/lib/integrity.sh.generate_study_materials.sh(1017) — referenced byrepo_to_study.shandlib/repo_study_steps.sh; alib/withrepo_study_steps.shalready exists beside it.hosts/install.sh(913) — widest reference surface of the three: 13 referencing files, includinginstall_core_system.sh,setup_periodic_system.sh,fresh-install/main.shandphone_focus_mode/deploy_phases.sh. Handle with more care than its line count suggests;grep -rlbefore and after.
All three were confirmed live/referenced — none is an archive candidate, so don't spend a round asking "do you still use this?" for these three.
Deployment-trap tier — 4 files, handle last and very carefully:
setup_midnight_shutdown.sh, pacman_wrapper.sh, install_leechblock.sh,
block_compulsive_opening.sh. These are copied to /usr/local/… and
pacman_wrapper.sh prefers the deployed copy on every pacman invocation
— a naive split breaks pacman -S on this machine. Re-verify the mechanism
before assuming (grep -n "prefer\|deployed" pacman_wrapper.sh near line
831). You cannot run sudo pacman -S from the Bash tool (deadlocks on
db.lck); hand the user a ! sudo pacman -S <pkg> line plus the expected
output if live verification is ever needed.
setup_midnight_shutdown.sh additionally needs a non-standard plan. Its
39 top-level-looking functions are NOT all real: several (log,
now_epoch/current_epoch, cmd_add/cmd_list/cmd_remove,
require_root) are duplicated because the outer script generates inner
standalone scripts via heredocs (create_shutdown_check_script,
create_override_manager_script, install_monitor_service) that get written
to /usr/local/bin/. extract_shell_functions.py and
verify_shell_split.sh both assume real top-level functions and will
mishandle a heredoc body. The plan that will work: extract only the genuine
outer orchestration functions, treat each create_*_script heredoc as one
atomic unit that moves whole (never split its interior), and verify by
hashing the emitted /usr/local/bin/* content before and after
(sha256sum on a rendered-heredoc temp file), not just by running
verify_shell_split.sh on the outer file.
Reference split to copy
linux_configuration/scripts/single_use/fixes/lib/ + lib/tests/ is the
worked example — look at the pacman_hook_stall_* family:
lib/tests/pacman_hook_stall_harness.sh— sourced, not executed;_t_pass/_t_fail/_t_eq,mktemp -d+trap cleanup EXIT, PATH-shim fakes for external tools.lib/tests/pacman_hook_stall_entry_harness.sh— separate fixture setup for the entry-script test, split out early so neither file passes 250 lines.- One
test_<lib>.shper lib, asserting against real function calls. test_diagnose_pacman_hook_stall_*.sh— runs the actual entry script as a subprocess against the same fakes.
Tooling
meta/scripts/check_file_length.sh --all— the gate. Run before every commit. Applies to test files too.meta/scripts/extract_shell_functions.py— moves functions brace-by-brace. Never slice by line range. Verify placement withgrep -con the anchor.meta/scripts/verify_shell_split.sh <pre-split-rev> <old> <new>...— proves every function moved verbatim. For a partial split, list the old path among the new paths too.meta/scripts/shell_coverage.sh <test> <subject> [min]— kcov wrapper, 100% minimum. Hand it the test script directly;bash script.shinstruments the bash binary and silently reports 0/0.
Sharp edges that have bitten before
local a="$1" b="${a}"fails underset -u— separatelocalstatements.- A function that calls
exit(notreturn) kills the whole test script if called directly in anifcondition. Use a subshell:if (fn args); then. - A backgrounded process needs
disownbeforekill/waitbehaves. - SIGINT to a backgrounded job was unreliable here; SIGTERM was not.
- If a script computes a real resource allocation from live system state, make the constants env-overridable and pin them tiny in every test.
- A file must not assign a global it never reads (SC2034). The hook runs
shellcheckwith no-x, but.shellcheckrc'sexternal-sources=true+source-path=SCRIPTDIRmeans asource=annotation on the sourcing file still resolves. - New sourced libs need a shebang AND the executable bit, staged with
git add --chmod=+x— a plaingit addafterwards resets it.
Exit condition for Phase 1: check_file_length.sh --all exits 0.
Phase 2: Wire the file-length gate into pre-commit
Do NOT start until Phase 1 exits 0 — wiring it early breaks every commit repo-wide, including unrelated ones.
-
Add a
localhook to.pre-commit-config.yamlrunningbash meta/scripts/check_file_length.sh --all, following the existinglanguage: system+pass_filenames: falseshape (seeai-evidence-contract/no-polling-antipatterns). Repo-wide, not per-file: a file that grows past 250 lines without being staged this commit should still be caught. -
GitHub-Actions-green check — GENUINE DESIGN FORK, ask the user first. A pre-commit hook cannot block on "is CI green" for a commit that does not exist yet. Two real options:
- (a) check the latest run on
mainis green before allowing a new commit — catches "building on a known-broken baseline", not "did MY change break it"; - (b) a pre-push hook running the CI workflows' local equivalent
before allowing the push — closer to the real guarantee, and
ci-mirroralready does this for the Python/pre-commit side. Extending it to also runShell tests' local equivalent is likely the more honest answer.
This is the one place in Phases 1–2 where stopping to ask is correct.
- (a) check the latest run on
-
Verify by making a throwaway file exceed 250 lines, confirming the commit is blocked with a clear message, then removing it.
Phase 3: Repo-wide 100% shell coverage gate — largest phase, many sessions
Do NOT start until Phases 1 AND 2 are done.
487 .sh files exist repo-wide vs ~15 lib/tests/ dirs following the
established pattern — on the order of 450+ untested scripts, roughly an order
of magnitude more work than Phase 1. Re-count before starting.
Ask the user to confirm scope before starting Phase 3 at all, and ask whether the gate should be repo-wide from day one or ratchet (only new or modified files must be covered, with a shrinking allowlist of pre-existing untested files). A hard repo-wide gate would block unrelated commits to any of 450+ files until every one has tests. Recommend the ratchet, but it is the user's call.
Rules that will bite you
- No suppressions, ever. No
# noqa, no per-file-ignore without asking every time, no new shellcheck disable. - Every commit touching code needs evidence in
docs/superpowers/evidence/<slug>-<date>.json. Staging ≥4 code files also needs a freshdocs/superpowers/contracts/*.json. Put the measured number in it, not a rounded one. - An archive does not need new tests. The 100%-coverage rule binds code that is split or newly written, not code that is deleted.
- A test file broken by your commit is a same-session bug, not a TODO.
Run
gh run listafter every push — CI-only suites (likelinux_configuration/tests/*.shrun directly byshell-tests.yml) are not caught by pre-commit's file-scoped hooks. pre-commit run --files <changed>aftergit add.prettierandci-mirrorrun on pre-push.npx prettier --writeany.md/.jsonyou touch, evidence and contract files included.- Work directly on
main.git stashand branch creation are blocked; usegit worktree add --detachfor a clean baseline (but NEVERgit filter-repoinside a worktree — it shares the object store and will corrupt the main repo; always a throwawaygit clonefor that). - Watch
jscpd(fails above 2%). Measure in a clean HEAD worktree. - Cap pytest memory:
systemd-run --user --scope -p MemorySwapMax=0 -p MemoryMax=2G. - Known tooling bug, fix opportunistically:
~/.claude/scripts/dart_format_changed.sh <repo>reports "No changed Dart files" even when files changed, if invoked with a repo path from outside that repo — itcds into$repothen runsgit status --porcelain, whose paths are relative to the git worktree root, so its[[ -f $path ]]check fails for every file. Workaround used:dart format <files>directly. Real fix:cdto the git toplevel, or strip the prefix.