klok-cli 1.1.0__tar.gz → 1.2.0__tar.gz

{klok_cli-1.1.0/klok_cli.egg-info → klok_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klok-cli
-Version: 1.1.0
+Version: 1.2.0
 Summary: A batteries-included command-line time tracker with a plaintext backend.
 Author: Rajat Singh
 License: MIT
@@ -131,6 +131,35 @@ klok checkin --mood 4 --energy 3 --stress 2
 klok mindful :month          # sessions, time, averages, streaks
 ```
 
+## What drains you, what lifts you
+
+The thing no other tracker does: klok joins *how you felt* to *what you were
+doing*. Rate a day's blocks in about twenty seconds, then let klok tell you which
+work costs you energy and which gives it back — from your own private, local data,
+no cloud and no screen surveillance.
+
+```sh
+klok review                  # walk today's blocks, rate each 1–5 (a digit, then Enter)
+klok stop --felt 4           # or rate a block the moment you stop it
+klok digest :week            # what drained vs lifted you, in plain language
+klok digest :month -o energy.txt   # write a shareable copy
+```
+
+`klok review` asks one quick energy rating per tracked block (blank skips, `b`
+goes back, `q` quits), so the data stays cheap to keep. `klok digest` then reports
+the projects and tags whose energy sits clearly above or below your average, and
+only once there's enough rated data to trust it — the footer always says how many
+blocks it's working from.
+
+```text
++reviews drains you
+  averages 1.3 points below your overall energy over 7 blocks
+deep work lifts you
+  averages 0.9 points above your overall energy over 11 blocks
+
+Based on 34 rated blocks across 12 days. Rate more with `klok review` for sharper results.
+```
+
 ## A web dashboard
 
 ```sh

{klok_cli-1.1.0 → klok_cli-1.2.0}/README.md

@@ -105,6 +105,35 @@ klok checkin --mood 4 --energy 3 --stress 2
 klok mindful :month          # sessions, time, averages, streaks
 ```
 
+## What drains you, what lifts you
+
+The thing no other tracker does: klok joins *how you felt* to *what you were
+doing*. Rate a day's blocks in about twenty seconds, then let klok tell you which
+work costs you energy and which gives it back — from your own private, local data,
+no cloud and no screen surveillance.
+
+```sh
+klok review                  # walk today's blocks, rate each 1–5 (a digit, then Enter)
+klok stop --felt 4           # or rate a block the moment you stop it
+klok digest :week            # what drained vs lifted you, in plain language
+klok digest :month -o energy.txt   # write a shareable copy
+```
+
+`klok review` asks one quick energy rating per tracked block (blank skips, `b`
+goes back, `q` quits), so the data stays cheap to keep. `klok digest` then reports
+the projects and tags whose energy sits clearly above or below your average, and
+only once there's enough rated data to trust it — the footer always says how many
+blocks it's working from.
+
+```text
++reviews drains you
+  averages 1.3 points below your overall energy over 7 blocks
+deep work lifts you
+  averages 0.9 points above your overall energy over 11 blocks
+
+Based on 34 rated blocks across 12 days. Rate more with `klok review` for sharper results.
+```
+
 ## A web dashboard
 
 ```sh

{klok_cli-1.1.0 → klok_cli-1.2.0}/klok/__init__.py

@@ -1,3 +1,3 @@
 """klok - a command-line time tracker with a plaintext backend."""
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"

{klok_cli-1.1.0 → klok_cli-1.2.0}/klok/cli.py

@@ -20,6 +20,8 @@ from klok.mindful import (BREATHING_TAG, MEDITATION_TAG, PATTERNS, Checkin,
                           parse_pattern, pattern_phases, rounds_for, sit_plan,
                           sparkline, streak)
 from klok.model import Frame, normalise_tags
+from klok.insights import drain_findings
+from klok.pairing import frame_at, is_practice
 from klok.report import (Renderer, by_day, by_project, by_sheet, by_tag,
                          render_day_chart, render_gaps, render_log,
                          render_punchcard, render_report, render_summary,
@@ -38,11 +40,25 @@ TIME_OPTIONS = {"-a", "--at", "--from", "--to", "--start", "--stop", "--now",
                 "--for", "--interval-bell", "--warmup"}
 
 
+def _default_ask(prompt: str):
+    """The real input seam: one line from the user, or ``None`` at EOF.
+
+    ``review`` reads through this rather than calling ``input`` directly, the
+    same spirit as the ``sleep=``/``clock=`` seams in ``focus``/``mindful``,
+    so the in-process test suite can feed scripted answers with no real TTY.
+    """
+    try:
+        return input(prompt)
+    except EOFError:
+        return None
+
+
 class Context:
     """Everything a command needs: config, store, clock and renderer."""
 
-    def __init__(self, args):
+    def __init__(self, args, ask=None):
         self.config = Config(args.home)
+        self.ask = ask or _default_ask
         self.store = Store(self.config)
         self.now = parse_datetime(args.now) if args.now else now_local()
         color_mode = "never" if args.no_color else (args.color or self.config.get("general.color", "auto"))
@@ -198,6 +214,7 @@ def cmd_start(ctx: Context) -> int:
 
 def cmd_stop(ctx: Context) -> int:
     args = ctx.args
+    felt = check_score("felt", getattr(args, "felt", None))  # validate before stopping
     at = resolve_time(ctx, args.at)
     sheet = None if args.all else ctx.sheet_filter()
     stopped = stop_running(ctx, at, note=args.note or "", sheet=sheet)
@@ -205,10 +222,17 @@ def cmd_stop(ctx: Context) -> int:
         ctx.echo("Nothing is running.")
         return 1
     ctx.store.save("stop")
+    if felt is not None:
+        store = CheckinStore(ctx.config)
+        for frame in stopped:
+            store.replace(store.energy_at(frame.start, frame.end_or(ctx.now)),
+                          Checkin(at=frame.start, energy=felt))
     for frame in stopped:
         ctx.echo("Stopped %s after %s [%s]" % (describe(ctx, frame),
                                                format_duration(frame.duration(ctx.now)),
                                                ctx.term.paint(frame.id, "grey")))
+    if felt is not None:
+        ctx.echo("Noted energy %d for %s." % (felt, "it" if len(stopped) == 1 else "them"))
     return 0
 
 
@@ -1173,9 +1197,14 @@ def cmd_checkin(ctx: Context) -> int:
                  % (removed.id, removed.at.strftime("%Y-%m-%d %H:%M")))
         return 0
 
+    words = list(args.words)
     mood = check_score("mood", args.mood)
     energy = check_score("energy", args.energy)
     stress = check_score("stress", args.stress)
+    # `klok checkin 4` shorthand: a bare leading integer is an energy rating,
+    # as long as --energy was not also given.  Everything else stays the note.
+    if energy is None and words and re.fullmatch(r"\d+", words[0]):
+        energy = check_score("energy", words.pop(0))
     if mood is None and energy is None and stress is None and sys.stdin.isatty():
         mood = check_score("mood", _ask("Mood 1-5 (1 low, 5 good)"))
         energy = check_score("energy", _ask("Energy 1-5"))
@@ -1184,7 +1213,7 @@ def cmd_checkin(ctx: Context) -> int:
         raise MindfulError("give at least one of --mood, --energy or --stress")
 
     checkin = Checkin(at=resolve_time(ctx, args.at), mood=mood, energy=energy, stress=stress,
-                      note=" ".join(args.words).strip(), tags=normalise_tags(args.tag or []))
+                      note=" ".join(words).strip(), tags=normalise_tags(args.tag or []))
     store.add(checkin)
     store.save()
     parts = ["%s %d" % (name, value) for name, value in
@@ -1325,6 +1354,134 @@ def cmd_mindful(ctx: Context) -> int:
     return 0
 
 
+def cmd_review(ctx: Context) -> int:
+    """Walk the range's tracked blocks and rate each one's energy, 1-5.
+
+    One block at a time: a digit then Enter records it, a blank line skips,
+    ``b`` steps back to re-rate the previous block, ``q`` (or EOF) stops.  By
+    default it walks the active sheet only and the blocks that have no energy
+    rating yet; ``--all-sheets`` widens the scope and ``--redo`` re-walks the
+    already-rated ones too.  Practice sessions and a still-running frame are
+    left out.  Each rating is one energy ``Checkin`` stamped at the block's
+    start instant, so the timestamp join associates it with that block.
+    """
+    start, end = ctx.range_of(":day")
+    sheet = ctx.sheet_filter()
+    practice = ctx.config.get("mindful.sheet", "wellbeing")
+    frames = ctx.store.select(start, end, sheet=sheet, now=ctx.now)
+    blocks = sorted((frame for frame in frames
+                     if not frame.running and not is_practice(frame, practice)
+                     and frame.start < frame.end_or(ctx.now)),
+                    key=lambda frame: frame.start)
+    store = CheckinStore(ctx.config)
+    redo = ctx.args.redo
+    pending = [frame for frame in blocks
+               if redo or store.energy_at(frame.start, frame.end_or(ctx.now)) is None]
+    if not pending:
+        if blocks:
+            ctx.echo("Every block here is already rated. Use `klok review --redo` to re-rate.")
+        else:
+            ctx.echo("No blocks to review in this range.")
+        return 0
+
+    rated = 0
+    index = 0
+    while index < len(pending):
+        frame = pending[index]
+        current = store.energy_at(frame.start, frame.end_or(ctx.now))
+        marker = ctx.term.paint("  [energy %d]" % current.energy, "grey") if current else ""
+        ctx.echo("%s  %s  (%s-%s)%s" % (
+            frame.label(), format_duration(frame.duration(ctx.now)),
+            ctx.renderer.fmt_time(frame.start), ctx.renderer.fmt_time(frame.stop), marker))
+        answer = ctx.ask("  Energy 1-5 (Enter skips, b back, q quit): ")
+        if answer is None:
+            break
+        answer = answer.strip().lower()
+        if answer == "":
+            index += 1
+            continue
+        if answer == "q":
+            break
+        if answer == "b":
+            index = max(0, index - 1)
+            continue
+        try:
+            value = check_score("energy", answer)
+        except MindfulError as exc:
+            ctx.echo("  %s" % exc)
+            continue
+        store.replace(current, Checkin(at=frame.start, energy=value))
+        rated += 1
+        index += 1
+
+    ctx.echo("Rated %d block%s." % (rated, "" if rated == 1 else "s"))
+    return 0
+
+
+def cmd_digest(ctx: Context) -> int:
+    """What your energy ratings add up to: which work drains or lifts you.
+
+    Reads the frames and energy check-ins in the range, joins each rating to
+    the block it falls in, and reports the projects and tags whose energy sits
+    clearly above or below your overall average.  It only reports a pattern
+    once there is enough data to trust it, so an honest footer always says how
+    many rated blocks it is working from.  ``-o`` writes the same text to a
+    file to share.
+    """
+    start, end = ctx.range_of(":week")
+    sheet = ctx.sheet_filter()
+    now = min(ctx.now, end - timedelta(seconds=1))
+    frames = ctx.store.select(start, end, sheet=sheet, now=now)
+    checkins = CheckinStore(ctx.config).select(start, end)
+
+    findings = drain_findings(frames, checkins, now)
+
+    # Rated blocks and the days they span, joined the same way insights does.
+    rated = {}
+    for checkin in checkins:
+        if checkin.energy is None:
+            continue
+        frame = frame_at(frames, checkin.at, now)
+        if frame is not None:
+            rated[id(frame)] = frame  # by identity, matching insights._rated_blocks
+    block_count = len(rated)
+    day_count = len({frame.start.date() for frame in rated.values()})
+
+    header = "Energy digest  %s to %s" % (
+        start.date().isoformat(), (end - timedelta(seconds=1)).date().isoformat())
+    body = []  # (kind, text): kind "head" is a finding headline, "plain" is as-is
+    if findings:
+        for finding in findings:
+            body.append(("head", finding.headline))
+            body.append(("plain", "  %s" % finding.detail))
+    elif block_count:
+        body.append(("plain", "No clear pattern yet. Keep rating blocks with `klok review`;"))
+        body.append(("plain", "a project or tag needs several rated blocks before it shows up here."))
+    else:
+        body.append(("plain", "Nothing rated yet. Rate a day's blocks with `klok review` and come back."))
+    footer = "Based on %d rated block%s across %d day%s." % (
+        block_count, "" if block_count == 1 else "s",
+        day_count, "" if day_count == 1 else "s")
+    if block_count:
+        footer += " Rate more with `klok review` for sharper results."
+
+    def render(colored: bool) -> str:
+        paint = ctx.term.paint if colored else (lambda text, *styles: text)
+        out = [paint(header, "bold"), ""]
+        for kind, text in body:
+            out.append(paint(text, "bold") if kind == "head" else text)
+        out += ["", paint(footer, "grey")]
+        return "\n".join(out)
+
+    if ctx.args.output:
+        with open(ctx.args.output, "w", encoding="utf-8") as handle:
+            handle.write(render(False) + "\n")
+        ctx.echo("Wrote the digest to %s" % ctx.args.output)
+    else:
+        print(render(True))
+    return 0
+
+
 # ------------------------------------------------------------------- checks
 def cmd_check(ctx: Context) -> int:
     problems = []
@@ -1361,7 +1518,7 @@ _klok_completions() {
   local commands="start stop cancel status restart switch track add stretch edit annotate tag untag
 rename move lengthen shorten fill join split delete undo log summary report chart gaps stats projects
 tags sheet sheets archive export import config where timer pomodoro breathe meditate checkin mood
-mindful check completion version"
+mindful review digest check completion version"
   COMPREPLY=($(compgen -W "$commands" -- "${COMP_WORDS[COMP_CWORD]}"))
 }
 complete -F _klok_completions klok
@@ -1373,7 +1530,7 @@ _klok() {
   commands=(start stop cancel status restart switch track add stretch edit annotate tag untag rename
 move lengthen shorten fill join split delete undo log summary report chart gaps stats projects tags
 sheet sheets archive export import config where timer pomodoro breathe meditate checkin mood
-mindful check completion version)
+mindful review digest check completion version)
   _describe 'klok command' commands
 }
 compdef _klok klok
@@ -1382,7 +1539,7 @@ compdef _klok klok
 for cmd in start stop cancel status restart switch track add stretch edit annotate tag untag rename \\
     move lengthen shorten fill join split delete undo log summary report chart gaps stats projects \\
     tags sheet sheets archive export import config where timer pomodoro breathe meditate \\
-    checkin mood mindful check completion version
+    checkin mood mindful review digest check completion version
     complete -c klok -n __fish_use_subcommand -a $cmd
 end
 """,
@@ -1564,6 +1721,7 @@ def build_parser() -> argparse.ArgumentParser:
     stop.add_argument("-a", "--at", metavar="TIME", help="stop at this time (e.g. 17:30, -5m)")
     stop.add_argument("-n", "--note", metavar="TEXT", help="append an annotation while stopping")
     stop.add_argument("--all", action="store_true", help="stop running entries on every sheet")
+    stop.add_argument("--felt", metavar="1-5", help="also record how the stretch felt, as an energy check-in")
 
     add("cancel", "Discard the running entry without recording it.",
         aliases=["abort"], parents=[sheet_opts], func=cmd_cancel)
@@ -1826,6 +1984,16 @@ def build_parser() -> argparse.ArgumentParser:
                       parents=[range_opts, sheet_opts], func=cmd_mindful)
     mindful_cmd.add_argument("--no-chart", action="store_true", help="skip the per-day chart")
 
+    review_cmd = add("review", "Rate each of a day's tracked blocks for energy, one at a time.",
+                     parents=[range_opts, sheet_opts], func=cmd_review)
+    review_cmd.add_argument("--redo", action="store_true",
+                            help="re-walk blocks that are already rated and replace their rating")
+
+    digest_cmd = add("digest", "What your energy ratings add up to: what drains or lifts you.",
+                     parents=[range_opts, sheet_opts], func=cmd_digest)
+    digest_cmd.add_argument("-o", "--output", metavar="FILE",
+                            help="write the digest to a file instead of stdout")
+
     current_group[0] = "Other"
     add("check", "Look for overlaps and other suspicious entries.", aliases=["sanity", "doctor"],
         func=cmd_check)
@@ -1840,7 +2008,7 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv=None) -> int:
+def main(argv=None, ask=None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
     if not argv:
         argv = ["status"]
@@ -1850,7 +2018,7 @@ def main(argv=None) -> int:
         parser.print_help()
         return 1
     try:
-        ctx = Context(args)
+        ctx = Context(args, ask=ask)
         return args.func(ctx) or 0
     except (StoreError, TimeParseError, ValueError, KeyError) as exc:
         return die(str(exc))

{klok_cli-1.1.0 → klok_cli-1.2.0}/klok/dashboard.py

@@ -12,12 +12,12 @@ from pathlib import Path
 from typing import List, Optional
 
 from klok import __version__
-from klok.mindful import BREATHING_TAG, MEDITATION_TAG, Checkin
+from klok.mindful import Checkin
 from klok.model import Frame
+from klok.pairing import frame_at, is_practice
 
 TEMPLATE = "dashboard.html"
 DATA_MARKER = "/*KLOK_DATA*/null"
-PRACTICE_TAGS = {BREATHING_TAG, MEDITATION_TAG}
 NO_PROJECT = "(no project)"
 
 
@@ -29,22 +29,6 @@ def _iso(moment: datetime) -> str:
     return moment.isoformat(timespec="seconds")
 
 
-def is_practice(frame: Frame, practice_sheet: str = "") -> bool:
-    """Breathing and sitting sessions, however they were recorded."""
-    return bool(PRACTICE_TAGS.intersection(frame.tags)) or (
-        bool(practice_sheet) and frame.sheet == practice_sheet)
-
-
-def frame_at(frames: List[Frame], moment: datetime, now: datetime) -> Optional[Frame]:
-    """The frame that was running at ``moment``; the latest-started one wins."""
-    found = None
-    for frame in frames:
-        if frame.start <= moment < frame.end_or(now):
-            if found is None or frame.start >= found.start:
-                found = frame
-    return found
-
-
 def _mean(values) -> Optional[float]:
     present = [value for value in values if value is not None]
     return round(sum(present) / len(present), 2) if present else None

klok_cli-1.2.0/klok/insights.py

@@ -0,0 +1,107 @@
+"""Energy insights: which projects and tags drain or lift you.
+
+A single deterministic analyzer over the frame/check-in join.  For every
+energy-bearing check-in (``energy is not None``) we find the frame it fell
+inside (``pairing.frame_at``); a *rated block* is a frame holding at least one
+such check-in, and its energy is the mean of those check-ins.  Each project
+and each tag is then scored by how far the mean energy of its rated blocks
+sits from your overall mean -- a drain (below) or a lift (above).
+
+Honesty over count (see docs/designs/energy-aware-klok.md): a project or tag
+is reported only when it has at least ``MIN_BLOCKS`` rated blocks *and* an
+effect of at least ``MIN_EFFECT`` energy points, so sparse data stays silent.
+This is the first-slice analyzer; the per-hour, per-weekday and fade analyzers
+are deferred behind the go/no-go gate.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from statistics import mean
+from typing import Dict, List, Tuple
+
+from klok import pairing
+from klok.mindful import Checkin
+from klok.model import Frame
+
+MIN_BLOCKS = 5
+MIN_EFFECT = 0.5
+NO_PROJECT = "(no project)"
+
+
+@dataclass
+class Finding:
+    """One drain-or-lift result, ready to print in the digest."""
+
+    headline: str
+    detail: str
+    effect_size: float
+    n: int
+
+
+def _rated_blocks(frames: List[Frame], checkins: List[Checkin],
+                  now: datetime) -> List[Tuple[Frame, float]]:
+    """Join once.  Every frame carrying at least one energy-bearing check-in,
+    paired with the mean energy of those check-ins.  Mood/stress-only
+    check-ins (``energy is None``) and check-ins that match no frame are
+    ignored, so neither creates or inflates a block.
+    """
+    energies: Dict[int, List[int]] = {}   # id(frame) -> raw energies
+    frame_of: Dict[int, Frame] = {}       # id(frame) -> the frame itself
+    for checkin in checkins:
+        if checkin.energy is None:
+            continue
+        frame = pairing.frame_at(frames, checkin.at, now)
+        if frame is None:
+            continue
+        energies.setdefault(id(frame), []).append(checkin.energy)
+        frame_of[id(frame)] = frame
+    return [(frame_of[key], float(mean(values)))
+            for key, values in energies.items()]
+
+
+def _findings_for(groups: Dict[str, List[float]], overall: float,
+                  prefix: str = "") -> List[Finding]:
+    """Turn one grouping (by project or by tag) into surviving findings."""
+    findings = []
+    for name, block_energies in groups.items():
+        n = len(block_energies)
+        if n < MIN_BLOCKS:
+            continue
+        effect = round(float(mean(block_energies)) - overall, 2)
+        if abs(effect) < MIN_EFFECT:
+            continue
+        drains = effect < 0
+        findings.append(Finding(
+            headline="%s%s %s" % (prefix, name,
+                                  "drains you" if drains else "lifts you"),
+            detail="averages %.1f points %s your overall energy over %d blocks"
+                   % (abs(effect), "below" if drains else "above", n),
+            effect_size=effect,
+            n=n,
+        ))
+    return findings
+
+
+def drain_findings(frames: List[Frame], checkins: List[Checkin],
+                   now: datetime) -> List[Finding]:
+    """Projects and tags that drain or lift you, most draining first.
+
+    Returns ``[]`` when there is nothing honest to say: no rated blocks, or
+    none that clear the ``MIN_BLOCKS``/``MIN_EFFECT`` suppression rule.
+    """
+    rated = _rated_blocks(frames, checkins, now)
+    if not rated:
+        return []
+    overall = float(mean(energy for _, energy in rated))
+
+    by_project: Dict[str, List[float]] = {}
+    by_tag: Dict[str, List[float]] = {}
+    for frame, energy in rated:
+        by_project.setdefault(frame.project or NO_PROJECT, []).append(energy)
+        for tag in frame.tags:
+            by_tag.setdefault(tag, []).append(energy)
+
+    findings = _findings_for(by_project, overall)
+    findings += _findings_for(by_tag, overall, prefix="+")
+    findings.sort(key=lambda finding: (finding.effect_size, finding.headline))
+    return findings

{klok_cli-1.1.0 → klok_cli-1.2.0}/klok/mindful.py

@@ -369,6 +369,43 @@ class CheckinStore:
         return [item for item in self.items
                 if (start is None or item.at >= start) and (end is None or item.at < end)]
 
+    def energy_at(self, start: datetime, end: datetime) -> Optional[Checkin]:
+        """The energy-bearing check-in inside ``[start, end)``, latest wins.
+
+        "Energy-bearing" means ``energy is not None``; a mood- or stress-only
+        check-in in the same interval is ignored, so it never masks a block
+        that has not actually been rated for energy.
+        """
+        found = [item for item in self.items
+                 if item.energy is not None and start <= item.at < end]
+        return found[-1] if found else None
+
+    def replace(self, old: Optional[Checkin], new: Checkin) -> Checkin:
+        """Re-rate in place: drop ``old`` (if any) then add ``new``, one save.
+
+        ``CheckinStore`` has no update, so re-rating a block is remove-then-add;
+        doing both before a single atomic save keeps the file consistent and
+        never leaves a duplicate energy check-in behind.
+
+        Re-rating changes the *energy* of a block, not the rest of a check-in.
+        When ``old`` carried a mood, stress, note or tags the user logged, those
+        are kept on ``new`` unless ``new`` sets its own, so a quick energy
+        re-rate never silently discards earlier entries.
+        """
+        if old is not None:
+            if new.mood is None:
+                new.mood = old.mood
+            if new.stress is None:
+                new.stress = old.stress
+            if not new.note:
+                new.note = old.note
+            if not new.tags:
+                new.tags = list(old.tags)
+            self._items = [item for item in self.items if item.id != old.id]
+        self.add(new)
+        self.save()
+        return new
+
 
 # ----------------------------------------------------------------- reporting
 def sparkline(values) -> str:

klok_cli-1.2.0/klok/pairing.py

@@ -0,0 +1,39 @@
+"""Pairing helpers: match a check-in to the frame that was running at a
+given moment, and classify practice (breathing/meditation) sessions.
+
+These were born in ``dashboard.py``; they live here so the dashboard, the
+``review`` ritual and the ``insights`` digest all share one join and agree
+on what "the block this check-in belongs to" means.  The join is
+timestamp-based and half-open (``start <= moment < end``), and ties between
+overlapping frames go to the latest-started one.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+from klok.mindful import BREATHING_TAG, MEDITATION_TAG
+from klok.model import Frame
+
+PRACTICE_TAGS = {BREATHING_TAG, MEDITATION_TAG}
+
+
+def is_practice(frame: Frame, practice_sheet: str = "") -> bool:
+    """Breathing and sitting sessions, however they were recorded."""
+    return bool(PRACTICE_TAGS.intersection(frame.tags)) or (
+        bool(practice_sheet) and frame.sheet == practice_sheet)
+
+
+def frame_at(frames: List[Frame], moment: datetime, now: datetime) -> Optional[Frame]:
+    """The frame that was running at ``moment``; the latest-started one wins.
+
+    Half-open: a frame covers ``start <= moment < end``.  ``now`` resolves the
+    end of a still-running frame.  When frames overlap, the one that started
+    most recently takes the moment, which is why callers that want an
+    unambiguous reverse lookup timestamp a check-in at the block's *start*.
+    """
+    found = None
+    for frame in frames:
+        if frame.start <= moment < frame.end_or(now):
+            if found is None or frame.start >= found.start:
+                found = frame
+    return found

{klok_cli-1.1.0 → klok_cli-1.2.0/klok_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klok-cli
-Version: 1.1.0
+Version: 1.2.0
 Summary: A batteries-included command-line time tracker with a plaintext backend.
 Author: Rajat Singh
 License: MIT
@@ -131,6 +131,35 @@ klok checkin --mood 4 --energy 3 --stress 2
 klok mindful :month          # sessions, time, averages, streaks
 ```
 
+## What drains you, what lifts you
+
+The thing no other tracker does: klok joins *how you felt* to *what you were
+doing*. Rate a day's blocks in about twenty seconds, then let klok tell you which
+work costs you energy and which gives it back — from your own private, local data,
+no cloud and no screen surveillance.
+
+```sh
+klok review                  # walk today's blocks, rate each 1–5 (a digit, then Enter)
+klok stop --felt 4           # or rate a block the moment you stop it
+klok digest :week            # what drained vs lifted you, in plain language
+klok digest :month -o energy.txt   # write a shareable copy
+```
+
+`klok review` asks one quick energy rating per tracked block (blank skips, `b`
+goes back, `q` quits), so the data stays cheap to keep. `klok digest` then reports
+the projects and tags whose energy sits clearly above or below your average, and
+only once there's enough rated data to trust it — the footer always says how many
+blocks it's working from.
+
+```text
++reviews drains you
+  averages 1.3 points below your overall energy over 7 blocks
+deep work lifts you
+  averages 0.9 points above your overall energy over 11 blocks
+
+Based on 34 rated blocks across 12 days. Rate more with `klok review` for sharper results.
+```
+
 ## A web dashboard
 
 ```sh

{klok_cli-1.1.0 → klok_cli-1.2.0}/klok_cli.egg-info/SOURCES.txt

@@ -9,8 +9,10 @@ klok/dashboard.html
 klok/dashboard.py
 klok/focus.py
 klok/formats.py
+klok/insights.py
 klok/mindful.py
 klok/model.py
+klok/pairing.py
 klok/report.py
 klok/storage.py
 klok/timeparse.py
@@ -21,6 +23,8 @@ klok_cli.egg-info/dependency_links.txt
 klok_cli.egg-info/entry_points.txt
 klok_cli.egg-info/top_level.txt
 tests/test_cli.py
+tests/test_insights.py
 tests/test_mindful.py
+tests/test_pairing.py
 tests/test_storage.py
 tests/test_timeparse.py

{klok_cli-1.1.0 → klok_cli-1.2.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 # by an unrelated, empty placeholder package. The installed command is
 # still plain `klok` - see [project.scripts] below.
 name = "klok-cli"
-version = "1.1.0"
+version = "1.2.0"
 description = "A batteries-included command-line time tracker with a plaintext backend."
 readme = "README.md"
 requires-python = ">=3.9"

{klok_cli-1.1.0 → klok_cli-1.2.0}/tests/test_cli.py

@@ -9,6 +9,23 @@ from pathlib import Path
 from klok.cli import main
 
 
+def scripted_input(answers):
+    """A stand-in for the ``Context`` input seam that replays a script.
+
+    Each prompt returns the next scripted answer; once they run out it returns
+    ``None`` the way a real read does at EOF, so a `review` walk ends cleanly.
+    """
+    pending = iter(answers)
+
+    def ask(prompt):
+        try:
+            return next(pending)
+        except StopIteration:
+            return None
+
+    return ask
+
+
 class CliTestCase(unittest.TestCase):
     """Drives the real entry point and reads what a user would see."""
 
@@ -20,11 +37,12 @@ class CliTestCase(unittest.TestCase):
     def tearDown(self):
         shutil.rmtree(self.home, ignore_errors=True)
 
-    def run_klok(self, *args, clock=None):
+    def run_klok(self, *args, clock=None, answers=None):
         argv = ["--home", str(self.home), "--no-color", "--now", clock or self.clock] + [str(a) for a in args]
+        ask = scripted_input(answers) if answers is not None else None
         out, err = io.StringIO(), io.StringIO()
         with redirect_stdout(out), redirect_stderr(err):
-            code = main(argv)
+            code = main(argv, ask=ask)
         return code, out.getvalue() + err.getvalue()
 
     def assertOk(self, *args, **kwargs):
@@ -542,6 +560,191 @@ class MindfulnessTests(CliTestCase):
         self.assertNotIn("klok breathe", self.assertOk("status"))
 
 
+class CheckinShorthandTests(CliTestCase):
+    """`klok checkin 4`, `klok stop --felt` and the flag forms coexisting."""
+
+    def energies(self):
+        """Every energy check-in, as (energy, HH:MM) pairs in time order."""
+        path = self.home / "checkins.jsonl"
+        if not path.exists():
+            return []
+        out = []
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            item = json.loads(line)
+            if item.get("energy") is not None:
+                out.append((item["energy"], item["at"][11:16]))
+        return sorted(out, key=lambda pair: pair[1])
+
+    def test_bare_integer_sets_energy(self):
+        output = self.assertOk("checkin", "4")
+        self.assertIn("energy 4", output)
+        self.assertEqual([e for e, _ in self.energies()], [4])
+
+    def test_flag_forms_still_work_alongside_the_positional(self):
+        # The positional shorthand must not have broken --mood/--energy/--stress.
+        self.assertOk("checkin", "--mood", "4")
+        self.assertOk("checkin", "--energy", "2", "--mood", "3")
+        self.assertEqual([e for e, _ in self.energies()], [2])
+
+    def test_bare_integer_keeps_the_rest_as_a_note(self):
+        self.assertOk("checkin", "4", "after", "lunch")
+        output = self.assertOk("mood", ":day")
+        self.assertIn("after lunch", output)
+
+    def test_leading_dash_value_is_not_swallowed_as_the_positional(self):
+        # `--energy 2 --mood 3` keeps parsing; words stays empty, no crash.
+        self.assertOk("checkin", "--energy", "2", "--mood", "3")
+        rows = json.loads(self.assertOk("mood", ":day", "--json"))
+        self.assertEqual(rows[0]["energy"], 2)
+        self.assertEqual(rows[0]["mood"], 3)
+
+    def test_non_integer_first_word_is_a_note_not_a_rating(self):
+        code, output = self.run_klok("checkin", "just", "a", "note")
+        self.assertEqual(code, 1)
+        self.assertIn("at least one", output)
+
+    def test_stop_felt_records_an_energy_checkin_at_the_block_start(self):
+        self.assertOk("start", "acme", "--at", "09:00")
+        output = self.assertOk("stop", "--at", "10:30", "--felt", "4")
+        self.assertIn("energy 4", output)
+        self.assertEqual(self.energies(), [(4, "09:00")])
+
+    def test_stop_felt_rejects_an_out_of_range_value_without_stopping(self):
+        self.assertOk("start", "acme", "--at", "09:00")
+        code, output = self.run_klok("stop", "--at", "10:30", "--felt", "9")
+        self.assertEqual(code, 1)
+        self.assertIn("between 1 and 5", output)
+        # The frame was not stopped and no check-in was written.
+        self.assertEqual(self.energies(), [])
+        payload = json.loads(self.assertOk("status", "--json"))
+        self.assertTrue(payload["running"])
+
+
+class ReviewTests(CliTestCase):
+    """The end-of-day `klok review` energy ritual."""
+
+    def energies(self):
+        path = self.home / "checkins.jsonl"
+        if not path.exists():
+            return []
+        out = []
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            item = json.loads(line)
+            out.append(item)
+        return sorted(out, key=lambda item: item["at"])
+
+    def two_blocks(self):
+        self.assertOk("track", "09:00", "to", "11:00", "acme", "+deep")
+        self.assertOk("track", "11:00", "to", "11:20", "email")
+
+    def test_happy_path_rates_each_block_at_its_start(self):
+        self.two_blocks()
+        output = self.assertOk("review", answers=["4", "2"])
+        self.assertIn("acme +deep", output)
+        self.assertIn("(09:00-11:00)", output)
+        self.assertIn("Rated 2 blocks", output)
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(4, "09:00"), (2, "11:00")])
+
+    def test_blank_line_skips_a_block(self):
+        self.two_blocks()
+        self.assertOk("review", answers=["", "3"])
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(3, "11:00")])
+
+    def test_q_quits_the_walk(self):
+        self.two_blocks()
+        output = self.assertOk("review", answers=["4", "q"])
+        self.assertIn("Rated 1 block.", output)
+        energies = [c["energy"] for c in self.energies()]
+        self.assertEqual(energies, [4])
+
+    def test_back_re_rates_without_duplicating(self):
+        self.two_blocks()
+        # Rate block 0 as 3, step back from block 1, re-rate block 0 as 5, skip block 1.
+        self.assertOk("review", answers=["3", "b", "5", ""])
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(5, "09:00")])
+
+    def test_redo_replaces_an_existing_rating(self):
+        self.two_blocks()
+        self.assertOk("review", answers=["4", "2"])
+        self.assertOk("review", "--redo", answers=["1", "5"])
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(1, "09:00"), (5, "11:00")])
+
+    def test_already_rated_blocks_are_skipped_without_redo(self):
+        self.two_blocks()
+        self.assertOk("review", answers=["4"])  # rate only block 0
+        # A second plain review only offers the still-unrated block.
+        output = self.assertOk("review", answers=["3"])
+        self.assertIn("email", output)
+        self.assertNotIn("acme +deep", output)
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(4, "09:00"), (3, "11:00")])
+
+    def test_mood_only_checkin_does_not_mask_an_unrated_block(self):
+        self.assertOk("track", "09:00", "to", "11:00", "acme")
+        # A mood-only check-in inside the block has energy None.
+        self.assertOk("checkin", "--mood", "4", "--at", "10:00")
+        output = self.assertOk("review", answers=["3"])
+        self.assertIn("acme", output)
+        self.assertIn("Rated 1 block", output)
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()
+                    if c["energy"] is not None]
+        self.assertEqual(energies, [(3, "09:00")])
+
+    def test_practice_and_running_frames_are_left_out(self):
+        self.assertOk("track", "09:00", "to", "10:00", "acme")
+        # A practice session (meditation tag) on the default work sheet.
+        self.assertOk("track", "10:00", "to", "10:20", "mindfulness", "+meditation")
+        # A still-running frame.
+        self.assertOk("start", "later", "--at", "12:00")
+        output = self.assertOk("review", answers=["4", "4", "4"])
+        self.assertIn("acme", output)
+        self.assertNotIn("mindfulness", output)
+        self.assertNotIn("later", output)
+        self.assertIn("Rated 1 block", output)
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(4, "09:00")])
+
+    def test_default_scope_is_the_active_sheet_only(self):
+        self.assertOk("track", "09:00", "to", "10:00", "acme")
+        self.assertOk("track", "10:00", "to", "11:00", "sideproj", "--sheet", "personal")
+        # Plain review walks the active sheet (default) only.
+        output = self.assertOk("review", answers=["4"])
+        self.assertIn("acme", output)
+        self.assertNotIn("sideproj", output)
+        self.assertEqual([c["energy"] for c in self.energies()], [4])
+
+    def test_all_sheets_widens_the_scope(self):
+        self.assertOk("track", "09:00", "to", "10:00", "acme")
+        self.assertOk("track", "10:00", "to", "11:00", "sideproj", "--sheet", "personal")
+        output = self.assertOk("review", "--all-sheets", answers=["4", "5"])
+        self.assertIn("acme", output)
+        self.assertIn("sideproj", output)
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(4, "09:00"), (5, "10:00")])
+
+    def test_invalid_answer_reprompts_the_same_block(self):
+        self.two_blocks()
+        # "9" is out of range: re-prompt the same block, then accept 4.
+        output = self.assertOk("review", answers=["9", "4", "2"])
+        self.assertIn("between 1 and 5", output)
+        energies = [(c["energy"], c["at"][11:16]) for c in self.energies()]
+        self.assertEqual(energies, [(4, "09:00"), (2, "11:00")])
+
+    def test_nothing_to_review_is_a_clean_no_op(self):
+        output = self.assertOk("review")
+        self.assertIn("No blocks to review", output)
+
+
 class DashboardTests(CliTestCase):
     def payload(self, *args):
         out = self.home / "dash.html"
@@ -659,5 +862,91 @@ class HelpAndErrorsTests(CliTestCase):
         self.assertNotIn("Nothing tracked yet", output)
 
 
+class DigestTests(CliTestCase):
+    """`klok digest`: project/tag drain-vs-lift from the energy ratings."""
+
+    def ten_rated_blocks(self):
+        # Five draining acme blocks, five lifting writing blocks, same day.
+        for hour in range(1, 6):
+            self.assertOk("track", "0%d:00" % hour, "to", "0%d:45" % hour, "acme", "+reviews")
+        for hour in range(1, 6):
+            self.assertOk("track", "1%d:00" % hour, "to", "1%d:45" % hour, "writing", "+deep")
+        # review walks in start order: the five acme blocks, then the five writing blocks.
+        self.assertOk("review", answers=["2"] * 5 + ["5"] * 5)
+
+    def test_digest_surfaces_drain_and_lift(self):
+        self.ten_rated_blocks()
+        output = self.assertOk("digest")
+        self.assertIn("acme drains you", output)
+        self.assertIn("writing lifts you", output)
+        self.assertIn("+reviews drains you", output)
+        self.assertIn("Based on 10 rated blocks across 1 day.", output)
+
+    def test_digest_with_no_ratings_says_so(self):
+        output = self.assertOk("digest")
+        self.assertIn("Nothing rated yet", output)
+        self.assertIn("Based on 0 rated blocks across 0 days.", output)
+
+    def test_too_few_blocks_report_no_pattern(self):
+        self.assertOk("track", "09:00", "to", "10:00", "acme")
+        self.assertOk("review", answers=["5"])
+        output = self.assertOk("digest")
+        self.assertIn("No clear pattern yet", output)
+        self.assertIn("Based on 1 rated block across 1 day.", output)
+
+    def test_digest_writes_a_plain_file(self):
+        self.ten_rated_blocks()
+        path = self.home / "digest.txt"
+        self.assertOk("digest", "-o", str(path))
+        text = path.read_text(encoding="utf-8")
+        self.assertIn("drains you", text)
+        self.assertIn("Based on 10 rated blocks", text)
+        self.assertNotIn("\x1b[", text)  # no terminal colour codes in the shared copy
+
+
+class CheckinReplaceRegressionTests(CliTestCase):
+    """Re-rating a block must not destroy the rest of a check-in, and
+    degenerate (zero-duration) blocks must not be rated or duplicated."""
+
+    def checkins(self):
+        path = self.home / "checkins.jsonl"
+        if not path.exists():
+            return []
+        out = []
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line:
+                out.append(json.loads(line))
+        return sorted(out, key=lambda item: item["at"])
+
+    def test_stop_felt_keeps_a_logged_note(self):
+        # The flagship repro: a rich check-in inside the block, then `stop --felt`.
+        self.assertOk("start", "acme", "--at", "09:00")
+        self.assertOk("checkin", "4", "rough", "meeting", "--at", "09:30")
+        self.assertOk("stop", "--at", "11:00", "--felt", "2")
+        items = self.checkins()
+        self.assertEqual(len(items), 1)                 # no duplicate
+        self.assertEqual(items[0]["energy"], 2)         # energy re-rated
+        self.assertEqual(items[0]["note"], "rough meeting")  # note preserved
+
+    def test_review_redo_keeps_a_logged_note(self):
+        self.assertOk("track", "09:00", "to", "11:00", "acme")
+        self.assertOk("checkin", "3", "standup", "notes", "--at", "09:30")
+        self.assertOk("review", "--redo", answers=["5"])
+        items = self.checkins()
+        self.assertEqual(len(items), 1)
+        self.assertEqual(items[0]["energy"], 5)
+        self.assertEqual(items[0]["note"], "standup notes")
+
+    def test_zero_duration_block_is_skipped(self):
+        # A block that starts and stops at the same instant has an empty window;
+        # review must leave it out rather than orphan or duplicate a rating.
+        self.assertOk("start", "acme", "--at", "10:00")
+        self.assertOk("stop", "--at", "10:00")
+        output = self.assertOk("review", answers=["4"])
+        self.assertIn("No blocks to review", output)
+        self.assertEqual(self.checkins(), [])
+
+
 if __name__ == "__main__":
     unittest.main()

klok_cli-1.2.0/tests/test_insights.py

@@ -0,0 +1,144 @@
+"""Tests for the project/tag drain analyzer (klok.insights).
+
+The analyzer joins energy-bearing check-ins to the frame each fell inside,
+means them per block, and reports a project or tag only when it clears the
+suppression rule (``n >= MIN_BLOCKS`` and ``|effect| >= MIN_EFFECT``).  These
+build frames and check-ins directly and lock the exact Finding values.
+"""
+
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from klok.insights import MIN_BLOCKS, MIN_EFFECT, Finding, drain_findings
+from klok.mindful import Checkin
+from klok.model import Frame
+
+TZ = timezone.utc
+BASE = datetime(2026, 9, 1, tzinfo=TZ)
+NOW = BASE + timedelta(days=2)
+
+
+def block(index, project="", tags=(), energies=(3,)):
+    """One 30-minute frame plus its check-ins, stamped at the block start."""
+    start = BASE + timedelta(hours=index)
+    frame = Frame(start=start, stop=start + timedelta(minutes=30),
+                  project=project, tags=list(tags))
+    checks = [Checkin(at=start, energy=energy) for energy in energies]
+    return frame, checks
+
+
+def scenario(*blocks):
+    frames, checkins = [], []
+    for frame, checks in blocks:
+        frames.append(frame)
+        checkins.extend(checks)
+    return frames, checkins
+
+
+class ConstantsTests(unittest.TestCase):
+    def test_thresholds_are_the_agreed_defaults(self):
+        self.assertEqual(MIN_BLOCKS, 5)
+        self.assertEqual(MIN_EFFECT, 0.5)
+
+
+class SuppressionTests(unittest.TestCase):
+    def test_no_checkins_means_no_findings(self):
+        frames = [Frame(start=BASE, stop=BASE + timedelta(hours=1), project="acme")]
+        self.assertEqual(drain_findings(frames, [], NOW), [])
+
+    def test_checkin_outside_every_frame_is_ignored(self):
+        frame = Frame(start=BASE, stop=BASE + timedelta(hours=1), project="acme")
+        stray = Checkin(at=BASE + timedelta(hours=5), energy=1)
+        self.assertEqual(drain_findings([frame], [stray], NOW), [])
+
+    def test_single_rated_block_is_suppressed(self):
+        # one rated block: n = 1, well under MIN_BLOCKS
+        frames, checkins = scenario(block(0, project="acme", energies=(1,)))
+        self.assertEqual(drain_findings(frames, checkins, NOW), [])
+
+    def test_all_equal_energy_is_suppressed(self):
+        # six rated blocks, every one energy 3: the effect is exactly 0
+        frames, checkins = scenario(*[block(i, project="acme", energies=(3,))
+                                      for i in range(6)])
+        self.assertEqual(drain_findings(frames, checkins, NOW), [])
+
+
+class ProjectFindingTests(unittest.TestCase):
+    def test_clear_drain_and_lift_surface_ranked(self):
+        blocks = []
+        # five draining acme blocks; each block averages (1 + 3) / 2 = 2.0
+        for i in range(5):
+            blocks.append(block(i, project="acme", energies=(1, 3)))
+        # five lifting writing blocks at energy 4
+        for i in range(5, 10):
+            blocks.append(block(i, project="writing", energies=(4,)))
+        frames, checkins = scenario(*blocks)
+
+        findings = drain_findings(frames, checkins, NOW)
+
+        # overall = (5 * 2.0 + 5 * 4.0) / 10 = 3.0; ranked most draining first
+        self.assertEqual(len(findings), 2)
+        drain, lift = findings
+        self.assertEqual(drain, Finding(
+            headline="acme drains you",
+            detail="averages 1.0 points below your overall energy over 5 blocks",
+            effect_size=-1.0, n=5))
+        self.assertEqual(lift, Finding(
+            headline="writing lifts you",
+            detail="averages 1.0 points above your overall energy over 5 blocks",
+            effect_size=1.0, n=5))
+
+
+class TagFindingTests(unittest.TestCase):
+    def test_tag_findings_surface_while_the_uniform_project_is_suppressed(self):
+        blocks = []
+        for i in range(5):
+            blocks.append(block(i, project="work", tags=("reviews",), energies=(2,)))
+        for i in range(5, 10):
+            blocks.append(block(i, project="work", tags=("deep",), energies=(4,)))
+        frames, checkins = scenario(*blocks)
+
+        findings = drain_findings(frames, checkins, NOW)
+
+        # project "work" covers all ten blocks: mean 3.0 == overall, effect 0
+        headlines = [finding.headline for finding in findings]
+        self.assertNotIn("work drains you", headlines)
+        self.assertNotIn("work lifts you", headlines)
+        self.assertEqual(len(findings), 2)
+        drain, lift = findings
+        self.assertEqual(drain, Finding(
+            headline="+reviews drains you",
+            detail="averages 1.0 points below your overall energy over 5 blocks",
+            effect_size=-1.0, n=5))
+        self.assertEqual(lift, Finding(
+            headline="+deep lifts you",
+            detail="averages 1.0 points above your overall energy over 5 blocks",
+            effect_size=1.0, n=5))
+
+
+class MoodOnlyTests(unittest.TestCase):
+    def test_mood_only_checkin_creates_no_block(self):
+        frame = Frame(start=BASE, stop=BASE + timedelta(hours=1), project="acme")
+        mood = Checkin(at=BASE + timedelta(minutes=10), mood=4)  # energy is None
+        self.assertEqual(drain_findings([frame], [mood], NOW), [])
+
+    def test_mood_only_checkin_does_not_inflate_a_rated_project(self):
+        blocks = [block(i, project="acme", energies=(2,)) for i in range(5)]
+        blocks += [block(i, project="writing", energies=(4,)) for i in range(5, 10)]
+        frames, checkins = scenario(*blocks)
+        # a sixth acme frame whose only check-in is mood-only (energy None)
+        extra_start = BASE + timedelta(hours=20)
+        frames.append(Frame(start=extra_start, stop=extra_start + timedelta(minutes=30),
+                            project="acme"))
+        checkins.append(Checkin(at=extra_start, mood=5))
+
+        findings = drain_findings(frames, checkins, NOW)
+
+        acme = next(finding for finding in findings
+                    if finding.headline == "acme drains you")
+        self.assertEqual(acme.n, 5)            # the mood-only block did not count
+        self.assertEqual(acme.effect_size, -1.0)
+
+
+if __name__ == "__main__":
+    unittest.main()

klok_cli-1.2.0/tests/test_pairing.py

@@ -0,0 +1,91 @@
+"""Tests for the shared pairing helpers (klok.pairing).
+
+frame_at and is_practice were extracted here from dashboard.py so the
+dashboard, the review ritual and the insights digest share one join. These
+lock the join's exact behavior (half-open, latest-started wins, practice
+classification) and a dashboard-payload invariant so the extraction can be
+proven behavior-preserving.
+"""
+
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from klok.dashboard import build_payload
+from klok.mindful import BREATHING_TAG, Checkin
+from klok.model import Frame
+from klok.pairing import frame_at, is_practice
+
+TZ = timezone.utc
+
+
+def at(hour, minute=0):
+    return datetime(2026, 9, 1, hour, minute, tzinfo=TZ)
+
+
+class FrameAtTests(unittest.TestCase):
+    def setUp(self):
+        self.now = at(23)
+        self.a = Frame(start=at(9), stop=at(11), project="acme")
+        self.b = Frame(start=at(11), stop=at(12), project="internal")
+
+    def test_moment_inside_a_frame_matches_it(self):
+        self.assertIs(frame_at([self.a, self.b], at(10), self.now), self.a)
+
+    def test_start_is_inclusive_end_is_exclusive(self):
+        # half-open: start belongs to the block, the stop instant does not.
+        self.assertIs(frame_at([self.a, self.b], at(9), self.now), self.a)
+        self.assertIs(frame_at([self.a, self.b], at(11), self.now), self.b)
+
+    def test_moment_outside_every_frame_is_none(self):
+        self.assertIsNone(frame_at([self.a, self.b], at(8), self.now))
+        self.assertIsNone(frame_at([self.a, self.b], at(12), self.now))
+
+    def test_overlap_goes_to_the_latest_started(self):
+        outer = Frame(start=at(9), stop=at(12), project="outer")
+        inner = Frame(start=at(10), stop=at(11), project="inner")
+        self.assertIs(frame_at([outer, inner], at(10, 30), self.now), inner)
+
+    def test_running_frame_uses_now_for_its_end(self):
+        running = Frame(start=at(9), stop=None, project="acme")
+        self.assertIs(frame_at([running], at(15), self.now), running)
+        self.assertIsNone(frame_at([running], at(23), at(23)))
+
+
+class IsPracticeTests(unittest.TestCase):
+    def test_practice_tag_marks_it(self):
+        self.assertTrue(is_practice(Frame(start=at(9), tags=[BREATHING_TAG])))
+
+    def test_practice_sheet_marks_it(self):
+        frame = Frame(start=at(9), sheet="wellbeing")
+        self.assertTrue(is_practice(frame, practice_sheet="wellbeing"))
+        self.assertFalse(is_practice(frame, practice_sheet="default"))
+
+    def test_plain_work_is_not_practice(self):
+        self.assertFalse(is_practice(Frame(start=at(9), project="acme")))
+
+
+class DashboardPayloadRegressionTests(unittest.TestCase):
+    """Locks the dashboard's join output so moving frame_at cannot drift it."""
+
+    def test_energy_mean_joins_checkins_to_their_frame(self):
+        now = at(23)
+        frames = [
+            Frame(start=at(9), stop=at(11), project="acme"),
+            Frame(start=at(11), stop=at(12), project="internal"),
+        ]
+        checkins = [
+            Checkin(at=at(10), energy=4),      # inside acme
+            Checkin(at=at(10, 30), energy=2),  # inside acme
+            Checkin(at=at(11, 30), energy=5),  # inside internal
+        ]
+        payload = build_payload(frames, checkins, now)
+        energy = {p["name"]: p["energy"] for p in payload["projects"]}
+        self.assertEqual(energy["acme"], 3.0)       # (4 + 2) / 2
+        self.assertEqual(energy["internal"], 5.0)
+        # each check-in carries the project it joined to
+        self.assertEqual([c["project"] for c in payload["checkins"]],
+                         ["acme", "acme", "internal"])
+
+
+if __name__ == "__main__":
+    unittest.main()