utils/dopamine-ux/TODO-04-screen-locker.md

Surface the workout streak that screen-locker already tracks

## findings (3, ranked by value over effort)

1. **`snapshot.streak` is populated and no renderer reads it** — the cheapest
   win in the whole project. Zero new state, zero conftest change, zero deps.
2. **Week-transition reward strings are discarded into `_logger.info`** —
   fully-formed celebratory sentences that never reach a user.
3. **The success moment exists only on the lock screen**, for 1.5s. The status
   window — the surface visited *voluntarily* — shows only enforcement.

## what

screen-locker computes a real workout streak and celebratory reward text, then
throws almost all of it away. Verified 2026-08-16:

- `StatusSnapshot` (`screen_locker/_status_types.py` ~:88-101) carries populated
  `streak`, `bonus_hours_this_week` and `early_bird_extended` fields, filled by
  `_status_data.py` ~:210-214. **Grep confirms no renderer reads them.**
- `_extra_benefits.py` `process_week_transition()` (~:82, reward strings built at
  ~:130-139) produces fully-formed celebratory sentences — and
  `_startup_checks.py` ~:57-58 sends them to `_logger.info` and nowhere else.
- The one success moment that exists is on the **lock screen**:
  `_unlock_view.py` `unlock_screen()` (~:25) paints "Great job! 💪" and
  `🔥 {streak}-week streak`, for `_UNLOCK_DELAY_MS = 1500` before routing away.

So the surface the user visits **voluntarily** — the status window, opened from
the tray icon — shows enforcement and budget depletion, and no evidence of
success at all. This is the cheapest high-value change in the whole project:
the data already exists, is already true, and needs no new state.

## where

Repo: `~/src/screen-locker`.

Primary:
- `screen_locker/_status_sections.py` — the section renderers used by the status
  window (`_section_*` functions). **177 lines; has headroom.** Add
  `_section_streak` here.
- `screen_locker/status_view.py` — `StatusWindow`, `render()`. Call the new
  section from here. ⚠️ **246 lines — only 4 left under the 250 cap.** Expect to
  extract something, or add the call in a way that costs ~1 line.
- `screen_locker/_status_types.py` — `StatusSnapshot` (~:88-101), the fields you
  are rendering. Read-only for this task.
- `screen_locker/_extra_benefits.py` (179 lines) — `process_week_transition()`
  and its reward strings; `current_streak()` ~:154,
  `weekly_shutdown_bonus_hours()` ~:159, `has_extended_early_bird()` ~:171.
- `screen_locker/_startup_checks.py` ~:57-58 — where the reward strings are
  currently discarded into a log call.
- `screen_locker/_unlock_view.py` (72 lines, lots of headroom) — the existing
  success moment, if you extend it.

## must

- **Render the already-populated fields.** Add `_section_streak` to
  `_status_sections.py` showing the weekly streak, this week's bonus hours, and
  the extended-early-bird state, and call it from `status_view.py`'s `render()`.
  Zero new state, zero conftest change, zero new dependency.
- **Stop discarding the reward strings.** `process_week_transition()` returns
  human-readable celebratory sentences that currently only reach the log. Surface
  them where the user will actually see them — the status window is the obvious
  home; a milestone is worth more than a silent counter increment.
- Match the existing positive-status styling rather than inventing one:
  `_status_sections.py` ~:73-78 already renders `"{n} above the weekly minimum!"`
  in success green, and uses `✓` marks at ~:36 and ~:57.
- Keep the streak **true**. It counts real ISO weeks with ≥5 counted workouts
  (`_weekly_check.py`: `WEEKLY_WORKOUT_MINIMUM = 5`, `COUNTED_WORKOUT_TYPES =
  {phone_verified, runnerup_verified, manual_workout}`). Do not round, pad, or
  "encourage" the number.

- must not: **make any reward reduce enforcement.** This is recorded twice in the
  repo as a deliberate decision:
  > `_startup_checks.py` ~:88-93 — "there is no banked 'skip a workout' credit —
  > that mechanic works against the goal of maximizing weekly workouts, so it was
  > removed in favor of a shutdown-time-only reward"
  > `_extra_benefits.py` ~:5-8 — "This never reduces enforcement … it only grants
  > extra comfort time on top of a floor you still have to earn each day."

  Every reward here is **display or comfort-time only**. Do not reintroduce a
  banked skip, a streak freeze, a grace day, or any mechanic that lowers the
  floor. A dopamine loop that lets you skip the workout defeats the app.
- must not: add **sound** to any enforcement or lock path. screen-locker is a
  self-restriction tool; a chime on lock is punishment audio, and a chime on
  unlock trains the wrong association. This repo stays silent. (Sound is
  opt-out-on elsewhere in the fleet; here it is simply absent.)
- must not: add a write tool to the MCP server. `_mcp.py` ~:14-26 states it is
  read-only by design. Adding `streak` to the existing `get_status` output is
  fine; a new action tool violates a stated invariant.
- must not: add `# noqa` (banned repo-wide) or a silent `except`
  (`scripts/check_silent_failures.py` — every handler re-raises or logs at
  warning or above).
- must not: create a new on-disk state file unless genuinely unavoidable. If you
  do, you **must** add it to `_ISOLATED_STATE` in
  `screen_locker/tests/conftest.py` (~:134), listing *every* module that binds
  the path at import time — a missed binding lets tests write to kuhy's real
  state. Read the comment at ~:131-133 and the fixture docstring at ~:170-175.

- optional: a daily streak alongside the weekly one. Note this **would** be new
  state (the existing streak is consecutive-*weeks*), so it triggers the conftest
  requirement above. diet-guard's consecutive-*day* streak
  (`~/src/diet-guard/diet_guard/_daystatus.py` ~:144) is the precedent to mirror.

## done

1. Opening the status window (tray icon → click, or `screen-locker-status`) shows
   the current streak, bonus hours and early-bird state — with the real values
   from `extra_benefits_state.json`, not placeholders.
2. A week-transition milestone reaches the UI instead of only `_logger.info`.
3. `cd ~/src/screen-locker && python -m pytest` passes.
4. `pre-commit run --files <changed files>` is clean — including the 250-line cap
   (`scripts/check_file_length.py`) and the silent-failure check.
5. `git diff` touches no enforcement logic: no change to lock decisions, weekly
   minimums, or shutdown floors.

## verify

Desktop — this is a desktop Python app.

```
cd ~/src/screen-locker
python -m screen_locker --status          # CLI: confirm the values it prints
screen-locker-status                      # the Tk window: confirm they render
```

Paste both outputs. The CLI already prints `streak`/`bonus_hours` (`_status.py`
~:138-141), so it is your ground truth: the window must show the **same numbers**.
If they disagree, the renderer is wrong, not the data.

Current real state for comparison: `screen_locker/extra_benefits_state.json` and
`screen_locker/workout_log.json` (12 days of entries, 2026-07-12 → 2026-08-15).

## read first

- `screen_locker/_status_sections.py` — every existing `_section_*`. Match their
  signature and style; note the success-green precedent at ~:73-78.
- `screen_locker/_status_types.py` ~:88-101 — the three fields you are rendering.
- `screen_locker/_extra_benefits.py` — especially the module docstring ~:5-8
  (the enforcement invariant) and the reward strings ~:130-139.
- `screen_locker/_unlock_view.py` — the existing celebration, for tone.
- `screen_locker/status_view.py` — check its line count **before** editing.
- `~/src/screen-locker/CLAUDE.md` — repo rules (no silent failures, ruff `select=ALL`).

## context you would otherwise rediscover

- **`workout_log.json` is the single source of truth**, written only through
  `_log_mixin.py` `write_signed_entry()` (~:82), HMAC-signed via
  `gatelock.log_integrity`, deduped on `workout_id`. The Flutter app converges on
  it via `_manual_push.py`. There is no second history — a streak computed from
  it is authoritative.
- All persistence is **JSON files, no sqlite**; paths declared in
  `screen_locker/_constants.py`. The streak store is
  `screen_locker/extra_benefits_state.json` (`consecutive_5plus_weeks`,
  `last_processed_iso_week`, `weekly_shutdown_bonus_hours`,
  `extended_early_bird_iso_weeks`).
- Thresholds live in `_extra_benefits.py`: `_MILESTONE_INTERVAL = 4` (4-week
  milestone), `_BONUS_THRESHOLD = 5` (workouts per week).
- **There is no config system** — no argparse, no env vars, no config file. Every
  tunable is a module-level constant. An opt-out toggle has no existing home;
  for a self-restriction tool, requiring a code edit to disable is arguably
  correct, so prefer a constant in `_constants.py` over new state.
- `~/gatelock` is **not** a repo — it is `~/src/utils/gatelock/gatelock/`, consumed as
  a pinned git dep, and it holds no workout state.
- Manual workouts were **not** removed: `_manual_workout.py` implements a
  rate-limited, evidence-gated subsystem (budget 2 per 7 days, 10 per 30).
- Three UI surfaces exist: the Tk status window (`status_view.py`), a GTK tray
  icon at `~/.config/i3/scripts/screen_locker_tray.py` (outside the repo, shells
  out to the CLI, refreshes every 60s), and the lock screen itself. No i3blocks
  integration exists despite `format_summary_line` being described as one.

REMOVE ME AFTER FINISH