testsAndMisc/NEXT_SESSION_PROMPT.md
Krzysztof kuhy Rudnicki 6691cb2644 NEXT_SESSION_PROMPT.md: rewrite for a fresh session, 8 files left
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
2026-08-21 13:29:17 +02:00

13 KiB
Raw Blame History

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:

  1. 100% line coverage on what you extract/write tests for — same bar every prior split has used.
  2. 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.
  3. 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.)
  4. The shell coverage gate is a NEW, separate requirement covering every .sh file 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.yml is 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 rerun replays the historical commit's workflow YAML, not main'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:

  1. check_and_enable_services.sh (1225) — a lib/ already exists beside it at linux_configuration/scripts/periodic_background/lib/ (currently holds only periodic_browser.sh), but no lib/tests/ yet — you will create it. Referenced by install_makepkg_wrapper.sh and pacman/lib/integrity.sh.
  2. generate_study_materials.sh (1017) — referenced by repo_to_study.sh and lib/repo_study_steps.sh; a lib/ with repo_study_steps.sh already exists beside it.
  3. hosts/install.sh (913) — widest reference surface of the three: 13 referencing files, including install_core_system.sh, setup_periodic_system.sh, fresh-install/main.sh and phone_focus_mode/deploy_phases.sh. Handle with more care than its line count suggests; grep -rl before 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>.sh per 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 with grep -c on 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.sh instruments the bash binary and silently reports 0/0.

Sharp edges that have bitten before

  • local a="$1" b="${a}" fails under set -u — separate local statements.
  • A function that calls exit (not return) kills the whole test script if called directly in an if condition. Use a subshell: if (fn args); then.
  • A backgrounded process needs disown before kill/wait behaves.
  • 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 shellcheck with no -x, but .shellcheckrc's external-sources=true + source-path=SCRIPTDIR means a source= annotation on the sourcing file still resolves.
  • New sourced libs need a shebang AND the executable bit, staged with git add --chmod=+x — a plain git add afterwards 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.

  1. Add a local hook to .pre-commit-config.yaml running bash meta/scripts/check_file_length.sh --all, following the existing language: system + pass_filenames: false shape (see ai-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.

  2. 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 main is 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-mirror already does this for the Python/pre-commit side. Extending it to also run Shell tests' local equivalent is likely the more honest answer.

    This is the one place in Phases 1–2 where stopping to ask is correct.

  3. 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 fresh docs/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 list after every push — CI-only suites (like linux_configuration/tests/*.sh run directly by shell-tests.yml) are not caught by pre-commit's file-scoped hooks.
  • pre-commit run --files <changed> after git add. prettier and ci-mirror run on pre-push. npx prettier --write any .md/.json you touch, evidence and contract files included.
  • Work directly on main. git stash and branch creation are blocked; use git worktree add --detach for a clean baseline (but NEVER git filter-repo inside a worktree — it shares the object store and will corrupt the main repo; always a throwaway git clone for 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 — it cds into $repo then runs git 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: cd to the git toplevel, or strip the prefix.