coach: review events, CLI and signed ledger

Add the review and skeleton session-log events, the review_cli write path
(review-list, review-finish, skeleton-open) and the coach's own signed
review ledger. A review event marks the day solved and starts the +3/+10
re-test clock. The flagged report is read through the guard CLI; a guard
failure is could-not-check, never nothing-to-review.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4
This commit is contained in:
Krzysztof Rudnicki 2026-11-21 21:56:30 +01:00
parent e2fb7535dd
commit 299e3b6fc2
14 changed files with 1188 additions and 6 deletions

View File

@ -0,0 +1,108 @@
"""The guard's flagged-solve report, read through the guard's own CLI.
A flagged solve took long although its theory was taught; `/leetcode review`
(DOCS-review.md) starts from that evidence. The coach may import only the four
guard modules `guard_bridge` allow-lists, so the report comes from running
``python3 -m leetcode_guard --flagged --json`` and parsing what it prints.
"Could not check" is not "nothing flagged": a guard that is missing, hangs,
exits non-zero or prints something else raises `CouldNotCheckError`. Only a
report whose ``flagged`` list is empty means there is nothing to review.
"""
from __future__ import annotations
import json
import logging
import subprocess
import sys
from typing import Any, Final
_LOG: Final = logging.getLogger(__name__)
GUARD_COMMAND: Final[tuple[str, ...]] = (
sys.executable,
*("-m", "leetcode_guard", "--flagged", "--json"),
)
"""The same interpreter the coach runs on: the guard is installed beside it."""
GUARD_TIMEOUT_SECONDS: Final = 30.0
_SECONDS_PER_MINUTE: Final = 60
Row = dict[str, Any]
class CouldNotCheckError(RuntimeError):
"""The guard gave no usable report; never the same as an empty one."""
def _fail(reason: str) -> CouldNotCheckError:
_LOG.warning("guard flagged report unusable: %s", reason)
return CouldNotCheckError(reason)
def flagged_rows() -> list[Row]:
"""The flagged solves, newest first, exactly as the guard reports them.
Raises:
CouldNotCheckError: when the guard CLI gave no usable report.
"""
try:
proc = subprocess.run(
GUARD_COMMAND,
capture_output=True,
text=True,
stdin=subprocess.DEVNULL,
timeout=GUARD_TIMEOUT_SECONDS,
check=False,
)
except (OSError, subprocess.TimeoutExpired) as exc:
reason = f"the guard CLI did not run ({exc})"
raise _fail(reason) from exc
if proc.returncode != 0:
last = (proc.stderr.strip().splitlines() or ["no message"])[-1]
msg = f"the guard CLI failed (exit {proc.returncode}: {last})"
raise _fail(msg)
try:
report = json.loads(proc.stdout)
except ValueError as exc:
reason = f"the guard CLI printed something that is not JSON ({exc})"
raise _fail(reason) from exc
rows = report.get("flagged") if isinstance(report, dict) else None
if not isinstance(rows, list):
msg = "the guard report has no flagged list"
raise _fail(msg)
if not all(isinstance(r, dict) and isinstance(r.get("slug"), str) for r in rows):
msg = "the guard report has a flagged row without a slug"
raise _fail(msg)
return rows
def flagged_slugs() -> set[str]:
"""The slugs that can be reviewed right now (raises like `flagged_rows`)."""
return {row["slug"] for row in flagged_rows()}
def _minutes(seconds: object) -> str:
if not isinstance(seconds, int):
return "n/a"
return f"{round(seconds / _SECONDS_PER_MINUTE)}m"
def _pairs(value: object, *, timed: bool) -> str:
if not isinstance(value, dict) or not value:
return "none"
shown = (f"{name} {_minutes(n) if timed else n}" for name, n in value.items())
return ", ".join(shown)
def evidence_line(row: Row) -> str:
"""One flagged solve as the evidence a review starts from."""
return (
f"{row['slug']} accepted {row.get('accepted_at', 'n/a')}"
f" active {_minutes(row.get('active_seconds'))}"
f" span {_minutes(row.get('span_seconds'))}"
f" failed {_pairs(row.get('failed'), timed=False)}"
f" first submit {_minutes(row.get('first_submission_active_seconds'))}"
f" tabs {_pairs(row.get('tab_seconds'), timed=True)}"
f" theory {row.get('theory', 'n/a')}"
)

View File

@ -8,6 +8,9 @@ record, so progress survives anything that survives the logs.
first day by which it has both a ``code`` and a ``postmortem`` event. A
later re-test session logs its own code and post-mortem; that never moves
the solve day, so it cannot reset the schedule.
* A ``review`` event (REVIEW.md: a flagged solve, reviewed with a named cause)
also marks its day solved and the problem started: an uncoached solve has
neither ``code`` nor ``postmortem``, and its re-test clock starts here.
* Re-tests fall due ``RETEST_OFFSETS`` days after the solve day (+3, +10).
Each ``retest`` event completes one stage.
@ -136,10 +139,11 @@ def _history(entries: list[tuple[dt.date, Event]]) -> History:
solved: dt.date | None = None
for day, event in entries:
seen.add(event["event"])
if solved is None and {"code", "postmortem"} <= seen:
if solved is None and ({"code", "postmortem"} <= seen or "review" in seen):
solved = day
retests = sum(event["event"] == "retest" for _day, event in entries)
return History(started="code" in seen, solved=solved, retests=retests)
started = "code" in seen or "review" in seen
return History(started=started, solved=solved, retests=retests)
def history(slug: str, directory: Path | None = None) -> History:

View File

@ -0,0 +1,203 @@
"""The commands `/leetcode review` and the skeleton sheets run (DOCS-review.md).
python3 -m leetcode_coach.review_cli review-list
python3 -m leetcode_coach.review_cli review-finish <slug> --cause <cause>
[--module <unit>] (--module with missing-idea, and only with it)
python3 -m leetcode_coach.review_cli skeleton-open <slug> <unit>
A Claude Code session has no REPL and so no exported session log
(`session_log.append_current` writes nothing there): these commands are its
explicit write path. ``review-finish`` is the only writer of a ``review``
event and of the review ledger, and it refuses a slug the guard does not flag
right now. It signs the ledger row first and logs the event second: a failure
at either step leaves the slug flagged, so the same command can run again. An
abandoned review calls nothing and so writes nothing.
``skeleton-open`` prints the sheet file byte for byte on stdout and nothing
else there (the stop gate passes a sheet only when the reply quotes it
verbatim); its one confirmation line goes to stderr.
The printed lines are the interface (T201 exemption in pyproject.toml); the
tests assert on stdout.
"""
from __future__ import annotations
import argparse
import logging
from pathlib import Path
import re
import sys
from typing import Final
from leetcode_coach import fetch_problem, flagged, progress, review_ledger, session_log
_LOG: Final = logging.getLogger(__name__)
SKELETON_DIR: Final = Path(__file__).with_name("skeletons")
SHEET_NAME: Final = "DOCS-{unit}.md"
CAUSES: Final = (
"statement",
"missing-idea",
"idea-to-code",
"debugging",
"interruption",
)
MODULE_CAUSE: Final = "missing-idea"
CARD_CAUSES: Final = frozenset({"missing-idea", "idea-to-code"})
NOTHING: Final = "nothing to review"
EXIT_OK: Final = 0
EXIT_REFUSED: Final = 1
EXIT_UNCHECKED: Final = 2
EXIT_NOT_WRITTEN: Final = 3
_UNIT: Final = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
def _refuse(why: str) -> int:
print(f"refused: {why}")
return EXIT_REFUSED
def _unchecked(exc: flagged.CouldNotCheckError, tail: str = "") -> int:
print(f"could not check: {exc}{tail}")
return EXIT_UNCHECKED
def review_list() -> int:
"""Print every flagged solve with its evidence, or `NOTHING`."""
try:
rows = flagged.flagged_rows()
except flagged.CouldNotCheckError as exc:
_LOG.warning("review-list could not read the flagged report: %s", exc)
return _unchecked(exc)
for row in rows:
print(flagged.evidence_line(row))
if not rows:
print(NOTHING)
return EXIT_OK
def _module_problem(cause: str, module: str | None) -> str | None:
if (cause == MODULE_CAUSE) != (module is not None):
return (
f"--module names the unit for --cause {MODULE_CAUSE} and goes with "
"no other cause; nothing written"
)
if module is not None and not _UNIT.fullmatch(module):
return f"{module!r} is not a unit id; nothing written"
return None
def review_finish(problem: str, cause: str, module: str | None) -> int:
"""Close one review: the signed ledger row, then the ``review`` event."""
if (problem_text := _module_problem(cause, module)) is not None:
return _refuse(problem_text)
try:
slug = fetch_problem.slug_from(problem)
reviewable = flagged.flagged_slugs()
except ValueError as exc:
_LOG.warning("review-finish got a bad problem name: %s", exc)
return _refuse(f"{exc}; nothing written")
except flagged.CouldNotCheckError as exc:
_LOG.warning("review-finish could not read the flagged report: %s", exc)
return _unchecked(exc, "; nothing written")
if slug not in reviewable:
return _refuse(f"{slug} is not flagged, {NOTHING}; nothing written")
return _record(slug, cause, module)
def _record(slug: str, cause: str, module: str | None) -> int:
"""Write the row, then the event, and say which of the two happened."""
try:
fresh = review_ledger.record(slug, cause)
except review_ledger.LedgerError as exc:
_LOG.warning("review of %s not recorded: %s", slug, exc)
print(
f"nothing written: no signed ledger row ({exc}), so no review event "
"either; fix that and run the same command again"
)
return EXIT_NOT_WRITTEN
fields = {"cause": cause} if module is None else {"cause": cause, "module": module}
try:
session_log.append(session_log.log_path(slug), "review", **fields)
except OSError as exc:
_LOG.warning("review event for %s not logged: %s", slug, exc)
print(
f"ledger row written, review event NOT logged ({exc}); "
"run the same command again"
)
return EXIT_NOT_WRITTEN
named = f", module {module}" if module is not None else ""
print(f"review logged: {slug}, cause {cause}{named}")
print("ledger row: " + ("written" if fresh else "already there, not written twice"))
if cause in CARD_CAUSES:
print("card: build ONE property -> operation card now (DOCS-review.md step 6)")
else:
print("card: none for this cause")
return EXIT_OK
def skeleton_open(problem: str, unit: str) -> int:
"""Log a ``skeleton`` event and print the unit's sheet, after a code attempt.
A ``code`` event in any of the slug's session logs counts; so does a slug
the guard flags right now (a review: the accepted submission is the code).
"""
try:
slug = fetch_problem.slug_from(problem)
except ValueError as exc:
_LOG.warning("skeleton-open got a bad problem name: %s", exc)
return _refuse(f"{exc}; nothing logged")
if not _UNIT.fullmatch(unit):
return _refuse(f"{unit!r} is not a unit id; nothing logged")
sheet = SKELETON_DIR / SHEET_NAME.format(unit=unit)
if not sheet.is_file():
return _refuse(
f"no skeleton sheet for unit {unit!r} at {sheet}; nothing logged"
)
if progress.count_events(slug, "code") == 0:
try:
in_review = slug in flagged.flagged_slugs()
except flagged.CouldNotCheckError as exc:
_LOG.warning("skeleton-open could not read the flagged report: %s", exc)
return _unchecked(exc, "; no code attempt in the log, nothing logged")
if not in_review:
return _refuse(
f"{slug} has no code attempt yet (no code event, not flagged): "
"a skeleton opens only after the first code; nothing logged"
)
text = sheet.read_bytes()
session_log.append(session_log.log_path(slug), "skeleton", unit=unit)
sys.stdout.flush()
sys.stdout.buffer.write(text)
sys.stdout.buffer.flush()
print(f"skeleton logged: {slug}, unit {unit}", file=sys.stderr)
return EXIT_OK
def _parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="review_cli")
sub = parser.add_subparsers(dest="command", required=True)
sub.add_parser("review-list", help="flagged solves with their evidence")
finish = sub.add_parser("review-finish", help="close a review with its one cause")
finish.add_argument("slug")
finish.add_argument("--cause", choices=CAUSES, required=True)
finish.add_argument("--module", help=f"unit id; only with {MODULE_CAUSE}")
opener = sub.add_parser("skeleton-open", help="log and print a unit's sheet")
opener.add_argument("slug")
opener.add_argument("unit")
return parser
def main(argv: list[str]) -> int:
"""Dispatch one of the three commands; 0 only when it did its job."""
args = _parser().parse_args(argv)
if args.command == "review-list":
return review_list()
if args.command == "review-finish":
return review_finish(args.slug, args.cause, args.module)
return skeleton_open(args.slug, args.unit)
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))

View File

@ -0,0 +1,139 @@
"""The coach's OWN signed ledger: one row per finished review.
``~/.local/share/leetcode-coach/review_ledger.json``, laid out like the
guard's ledger (``{"version": 1, "entries": [...]}``) so ``earned_time``'s
verified-row reader can read it. It is a separate file on purpose: nothing in
the coach may reach the guard's ledger (`relay/__init__.py`).
A row is signed the way every locker signs: HMAC-SHA256 over the canonical
JSON of the row without ``hmac``, keyed with ``/etc/workout-locker/hmac.key``.
`entry_signature` repeats ``earned_time.entry_signature``'s three lines, since
the coach does not depend on ``earned_time``;
``test_earned_time_verifies_the_row_and_signs_it_the_same`` holds the two
together.
Fail closed: without a readable key, or over a ledger file that does not
parse, `record` raises `LedgerError` and writes nothing. Each slug gets one row
ever. The write is a rename over the target, so a crash leaves the old file.
"""
from __future__ import annotations
from datetime import UTC, datetime
import hashlib
import hmac
import json
import logging
import os
from pathlib import Path
import tempfile
from typing import Any, Final
_LOG: Final = logging.getLogger(__name__)
LEDGER_PATH: Final = (
Path.home() / ".local" / "share" / "leetcode-coach" / "review_ledger.json"
)
KEY_FILE: Final = Path("/etc/workout-locker/hmac.key")
VERSION: Final = 1
"""The guard ledger's ``_ledger_io._VERSION``."""
SOURCE: Final = "leetcode-coach-review"
ID_PREFIX: Final = "review:"
class LedgerError(RuntimeError):
"""No signed row could be written; nothing on disk changed."""
def entry_signature(entry: dict[str, object], key: bytes) -> str:
"""The HMAC-SHA256 every locker signs a ledger row with (``hmac`` left out)."""
body = {k: v for k, v in entry.items() if k != "hmac"}
payload = json.dumps(body, sort_keys=True, separators=(",", ":"))
return hmac.new(key, payload.encode(), hashlib.sha256).hexdigest()
def _key() -> bytes:
try:
key = KEY_FILE.read_bytes().strip()
except OSError as exc:
_LOG.warning("cannot read the signing key at %s: %s", KEY_FILE, exc)
msg = f"cannot read the signing key at {KEY_FILE}: {exc}"
raise LedgerError(msg) from exc
if not key:
_LOG.warning("the signing key at %s is empty", KEY_FILE)
msg = f"the signing key at {KEY_FILE} is empty"
raise LedgerError(msg)
return key
def _entries() -> list[Any]:
"""The rows on disk; none while the file does not exist yet."""
if not LEDGER_PATH.exists():
return []
try:
data = json.loads(LEDGER_PATH.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
_LOG.warning("review ledger %s is unreadable: %s", LEDGER_PATH, exc)
msg = f"the review ledger at {LEDGER_PATH} is unreadable, not overwritten"
raise LedgerError(msg) from exc
entries = data.get("entries") if isinstance(data, dict) else None
if not isinstance(entries, list):
_LOG.warning("review ledger %s has no entries list", LEDGER_PATH)
msg = f"the review ledger at {LEDGER_PATH} has no entries, not overwritten"
raise LedgerError(msg)
return entries
def _write(entries: list[Any]) -> None:
text = json.dumps({"version": VERSION, "entries": entries}, indent=2) + "\n"
folder = LEDGER_PATH.parent
try:
folder.mkdir(parents=True, exist_ok=True)
fd, tmp = tempfile.mkstemp(dir=folder, prefix=".review-", suffix=".json")
with os.fdopen(fd, "w", encoding="utf-8") as fh:
fh.write(text)
Path(tmp).replace(LEDGER_PATH)
except OSError as exc:
_LOG.warning("review ledger %s not written: %s", LEDGER_PATH, exc)
msg = f"cannot write the review ledger at {LEDGER_PATH}: {exc}"
raise LedgerError(msg) from exc
def record(slug: str, cause: str, *, now: datetime | None = None) -> bool:
"""Sign and append the row for one finished review.
Args:
slug: The reviewed problem.
cause: The one named cause.
now: The finish time, timezone-aware (default: now, local time).
Returns:
True when the row was written, False when the slug already had one.
Raises:
LedgerError: no key, an unreadable ledger or a failed write; nothing
on disk changed.
"""
key = _key()
entries = _entries()
entry_id = ID_PREFIX + slug
if any(isinstance(e, dict) and e.get("entry_id") == entry_id for e in entries):
return False
moment = now or datetime.now(tz=UTC).astimezone()
row: dict[str, object] = {
"entry_id": entry_id,
"kind": "credit",
"day": moment.date().isoformat(),
"created_at": moment.isoformat(),
"amount": 1,
"device": "pc",
"detail": {
"title_slug": slug,
"cause": cause,
"source": SOURCE,
"finished_at": str(int(moment.timestamp())),
},
}
row["hmac"] = entry_signature(row, key)
_write([*entries, row])
return True

View File

@ -39,8 +39,11 @@ EVENTS = frozenset(
{
*("req", "req_check", "code", "rung", "reveal", "postmortem", "retest"),
*("session_start", "grade", "chat", "session_end"),
*("review", "skeleton"),
}
)
"""``review`` carries ``cause`` (and ``module`` for ``missing-idea``), ``skeleton``
carries ``unit``; both came with ``review_cli`` (REVIEW.md)."""
def sessions_dir() -> Path:

View File

@ -0,0 +1,63 @@
"""Shared by the review tests: a fake guard CLI, the test key, a flagged row.
The three ``REAL_*`` values are read at import time, before the autouse
fixture in ``conftest.py`` repoints the seams, so a test can still name the
production default without ever using it.
"""
from __future__ import annotations
import json
import sys
from typing import TYPE_CHECKING, Any
from leetcode_coach import flagged, review_ledger
if TYPE_CHECKING:
from pathlib import Path
import pytest
REVIEW_KEY = b"coach-test-key"
REAL_GUARD_COMMAND = flagged.GUARD_COMMAND
REAL_REVIEW_LEDGER = review_ledger.LEDGER_PATH
REAL_KEY_FILE = review_ledger.KEY_FILE
def flagged_row(slug: str = "two-sum") -> dict[str, Any]:
"""One row of the guard's ``--flagged --json`` report (measured 2026-11-21)."""
return {
"slug": slug,
"accepted_at": "2026-11-21T18:01:34+01:00",
"day": "2026-11-21",
"active_seconds": 1500,
"span_seconds": 2400,
"tab_seconds": {"description": 1200, "solutions": 300},
"failed": {"Wrong Answer": 2},
"first_submission_active_seconds": 720,
"theory": "done",
"flagged": True,
}
def fake_guard(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
*slugs: str,
stdout: str | None = None,
code: int = 0,
sleep: float = 0,
) -> None:
"""Point the guard seam at a script that prints a report (or ``stdout``)."""
report = {"flagged": [flagged_row(slug) for slug in slugs], "measured": []}
text = json.dumps(report) if stdout is None else stdout
script = tmp_path / "fake_guard.py"
script.write_text(
"import sys, time\n"
f"time.sleep({sleep!r})\n"
f"sys.stdout.write({text!r})\n"
"sys.stderr.write('guard said no\\n')\n"
f"sys.exit({code})\n",
encoding="utf-8",
)
monkeypatch.setattr(flagged, "GUARD_COMMAND", (sys.executable, str(script)))

View File

@ -6,6 +6,11 @@ the small fixture toolbox, so a reviewed edit of the real `toolbox.json` cannot
flip a leak test. `toolbox.load` (cards, clusters) still reads the real file.
Env vars are *set* (to empty or a dead path) rather than deleted, so teardown
also removes the `LEETCODE_COACH_LOG` the REPL exports for its hooks.
The review flow gets the same treatment: its ledger and signing key live in
tmp, the guard CLI seam is a dead path and the sheet dir is empty. After every
test the real review ledger must be exactly as it was: a test that got past
the `review_ledger.LEDGER_PATH` seam fails here, loudly.
"""
from __future__ import annotations
@ -14,17 +19,44 @@ from typing import TYPE_CHECKING
import pytest
from leetcode_coach import local_backend, progress, session_log, toolbox
from leetcode_coach import (
flagged,
local_backend,
progress,
review_cli,
review_ledger,
session_log,
toolbox,
)
from leetcode_coach.tests._review_support import REAL_REVIEW_LEDGER, REVIEW_KEY
from leetcode_coach.tests._shared import FIXTURE_TOOLBOX
if TYPE_CHECKING:
from collections.abc import Iterator
from pathlib import Path
DEAD_OLLAMA = "http://127.0.0.1:9" # the discard port: connection refused at once
def _stamp(path: Path) -> tuple[int, int] | None:
"""(mtime, size) of `path`, or None while it does not exist."""
if not path.exists():
return None
stat = path.stat()
return stat.st_mtime_ns, stat.st_size
@pytest.fixture(autouse=True)
def _hermetic_coach(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
def _hermetic_coach(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
real_ledger = _stamp(REAL_REVIEW_LEDGER)
key_file = tmp_path / "review-hmac.key"
key_file.write_bytes(REVIEW_KEY + b"\n")
monkeypatch.setattr(
review_ledger, "LEDGER_PATH", tmp_path / "coach" / "review_ledger.json"
)
monkeypatch.setattr(review_ledger, "KEY_FILE", key_file)
monkeypatch.setattr(flagged, "GUARD_COMMAND", (str(tmp_path / "no-such-guard"),))
monkeypatch.setattr(review_cli, "SKELETON_DIR", tmp_path / "skeletons")
monkeypatch.setenv(progress.SESSIONS_ENV, str(tmp_path / "sessions"))
monkeypatch.setenv(progress.CLUSTER_ENV, "")
monkeypatch.setenv(session_log.LOG_ENV, "")
@ -36,3 +68,7 @@ def _hermetic_coach(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
return real(FIXTURE_TOOLBOX if path is None else path)
monkeypatch.setattr(toolbox, "load_safe", fixture_toolbox)
yield
assert _stamp(REAL_REVIEW_LEDGER) == real_ledger, (
f"a test wrote the real review ledger at {REAL_REVIEW_LEDGER}"
)

View File

@ -0,0 +1,92 @@
"""The coach reads the guard's flagged report through the guard CLI only."""
from __future__ import annotations
import sys
from typing import TYPE_CHECKING
import pytest
from leetcode_coach import flagged
from leetcode_coach.tests._review_support import (
REAL_GUARD_COMMAND,
fake_guard,
flagged_row,
)
if TYPE_CHECKING:
from pathlib import Path
def test_the_real_command_is_the_guard_cli_on_this_interpreter() -> None:
assert (
sys.executable,
"-m",
"leetcode_guard",
"--flagged",
"--json",
) == REAL_GUARD_COMMAND
def test_rows_come_back_as_the_guard_printed_them(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum", "3sum")
assert flagged.flagged_rows() == [flagged_row("two-sum"), flagged_row("3sum")]
assert flagged.flagged_slugs() == {"two-sum", "3sum"}
def test_an_empty_report_is_an_answer(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
fake_guard(tmp_path, monkeypatch)
assert flagged.flagged_rows() == []
@pytest.mark.parametrize(
("stdout", "code", "why"),
[
('{"flagged": []}', 3, "exit 3: guard said no"),
("Traceback", 0, "not JSON"),
('{"measured": []}', 0, "no flagged list"),
('{"flagged": {}}', 0, "no flagged list"),
("[]", 0, "no flagged list"),
('{"flagged": [{"active_seconds": 5}]}', 0, "without a slug"),
('{"flagged": ["two-sum"]}', 0, "without a slug"),
],
)
def test_a_guard_that_cannot_answer_is_could_not_check(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, stdout: str, code: int, why: str
) -> None:
fake_guard(tmp_path, monkeypatch, stdout=stdout, code=code)
with pytest.raises(flagged.CouldNotCheckError, match=why):
flagged.flagged_rows()
def test_a_missing_guard_is_could_not_check() -> None:
with pytest.raises(flagged.CouldNotCheckError, match="did not run"):
flagged.flagged_rows()
def test_a_hung_guard_is_could_not_check(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
fake_guard(tmp_path, monkeypatch, sleep=5)
monkeypatch.setattr(flagged, "GUARD_TIMEOUT_SECONDS", 0.2)
with pytest.raises(flagged.CouldNotCheckError, match="did not run"):
flagged.flagged_rows()
def test_the_evidence_line_shows_what_the_guard_measured() -> None:
assert flagged.evidence_line(flagged_row("two-sum")) == (
"two-sum accepted 2026-11-21T18:01:34+01:00 active 25m span 40m"
" failed Wrong Answer 2 first submit 12m"
" tabs description 20m, solutions 5m theory done"
)
def test_the_evidence_line_survives_a_sparse_row() -> None:
assert flagged.evidence_line({"slug": "3sum", "span_seconds": None}) == (
"3sum accepted n/a active n/a span n/a"
" failed none first submit n/a tabs none theory n/a"
)

View File

@ -195,3 +195,23 @@ def test_append_event_writes_todays_file(
assert event["event"] == "retest"
assert dt.datetime.fromisoformat(event["ts"]).tzinfo is not None
assert progress.count_events("two-sum", "retest", tmp_path / "new") == 1
def test_a_review_marks_the_day_solved_and_starts_the_clock(tmp_path: Path) -> None:
review = {"event": "review", "cause": "debugging"}
log(tmp_path, DAY0, "two-sum", review)
past = progress.history("two-sum", tmp_path)
assert (past.started, past.solved, past.retests) == (True, DAY0, 0)
assert progress.due_retests(tmp_path, today=DAY0 + dt.timedelta(days=2)) == []
due = progress.due_retests(tmp_path, today=DAY0 + dt.timedelta(days=3))
assert [(r["slug"], r["stage"], r["due"]) for r in due] == [
("two-sum", 1, "2026-10-23")
]
def test_a_review_after_a_coached_solve_does_not_move_the_solve_day(
tmp_path: Path,
) -> None:
solve(tmp_path, DAY0, "3sum")
log(tmp_path, DAY0 + dt.timedelta(days=5), "3sum", {"event": "review"})
assert progress.history("3sum", tmp_path).solved == DAY0

View File

@ -0,0 +1,220 @@
"""`review-list` and `review-finish`: stdout is the interface, so assert on it."""
from __future__ import annotations
import json
from typing import TYPE_CHECKING, Any
import pytest
from leetcode_coach import flagged, progress, review_cli, review_ledger, session_log
from leetcode_coach.tests._review_support import fake_guard, flagged_row
if TYPE_CHECKING:
from pathlib import Path
def _events(slug: str) -> list[dict[str, Any]]:
return session_log.read(session_log.log_path(slug))
def _rows() -> list[dict[str, Any]]:
if not review_ledger.LEDGER_PATH.exists():
return []
entries: list[dict[str, Any]] = json.loads(
review_ledger.LEDGER_PATH.read_text(encoding="utf-8")
)["entries"]
return entries
def _nothing_written(slug: str = "two-sum") -> bool:
return not _events(slug) and not _rows()
def test_review_list_prints_every_flagged_solve_with_its_evidence(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum", "3sum")
assert review_cli.main(["review-list"]) == 0
assert capsys.readouterr().out.splitlines() == [
flagged.evidence_line(flagged_row("two-sum")),
flagged.evidence_line(flagged_row("3sum")),
]
def test_review_list_says_nothing_to_review_when_nothing_is_flagged(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch)
assert review_cli.main(["review-list"]) == 0
assert capsys.readouterr().out == "nothing to review\n"
def test_review_list_never_shows_a_guard_failure_as_nothing_to_review(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, code=1)
assert review_cli.main(["review-list"]) == review_cli.EXIT_UNCHECKED != 0
out = capsys.readouterr().out
assert out.startswith("could not check: ")
assert "nothing to review" not in out
def test_review_finish_logs_the_event_and_signs_a_row(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
url = "https://leetcode.com/problems/two-sum/description/"
args = ["review-finish", url, "--cause", "missing-idea", "--module", "hashing"]
assert review_cli.main(args) == 0
(event,) = _events("two-sum")
assert {k: v for k, v in event.items() if k != "ts"} == {
"event": "review",
"cause": "missing-idea",
"module": "hashing",
}
(row,) = _rows()
assert (row["entry_id"], row["detail"]["cause"]) == (
"review:two-sum",
"missing-idea",
)
assert progress.history("two-sum").solved == progress.local_today()
assert capsys.readouterr().out.splitlines() == [
"review logged: two-sum, cause missing-idea, module hashing",
"ledger row: written",
"card: build ONE property -> operation card now (DOCS-review.md step 6)",
]
@pytest.mark.parametrize("cause", ["statement", "debugging", "interruption"])
def test_a_cause_without_a_card_is_only_recorded(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
capsys: pytest.CaptureFixture[str],
cause: str,
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
assert review_cli.main(["review-finish", "two-sum", "--cause", cause]) == 0
(event,) = _events("two-sum")
assert event["cause"] == cause
assert "module" not in event
assert capsys.readouterr().out.splitlines() == [
f"review logged: two-sum, cause {cause}",
"ledger row: written",
"card: none for this cause",
]
def test_idea_to_code_makes_a_card_without_a_module(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
assert review_cli.main(["review-finish", "two-sum", "--cause", "idea-to-code"]) == 0
assert "card: build ONE" in capsys.readouterr().out
def test_review_finish_refuses_a_slug_that_is_not_flagged(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "3sum")
code = review_cli.main(["review-finish", "two-sum", "--cause", "debugging"])
assert code == review_cli.EXIT_REFUSED != 0
assert capsys.readouterr().out == (
"refused: two-sum is not flagged, nothing to review; nothing written\n"
)
assert _nothing_written()
def test_review_finish_cannot_check_is_not_a_refusal_and_writes_nothing(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, stdout="boom")
code = review_cli.main(["review-finish", "two-sum", "--cause", "debugging"])
assert code == review_cli.EXIT_UNCHECKED
out = capsys.readouterr().out
assert out.startswith("could not check: ")
assert out.endswith("; nothing written\n")
assert _nothing_written()
@pytest.mark.parametrize(
("extra", "why"),
[
(["--cause", "missing-idea"], "--module names the unit"),
(["--cause", "debugging", "--module", "hashing"], "--module names the unit"),
(["--cause", "missing-idea", "--module", "../x"], "not a unit id"),
],
)
def test_review_finish_checks_the_module_before_anything_else(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
capsys: pytest.CaptureFixture[str],
extra: list[str],
why: str,
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
code = review_cli.main(["review-finish", "two-sum", *extra])
assert code == review_cli.EXIT_REFUSED
out = capsys.readouterr().out
assert out.startswith("refused: ")
assert why in out
assert _nothing_written()
def test_review_finish_refuses_what_is_not_a_slug(
capsys: pytest.CaptureFixture[str],
) -> None:
code = review_cli.main(["review-finish", "Two Sum!", "--cause", "debugging"])
assert code == review_cli.EXIT_REFUSED
assert "not a LeetCode problem URL or slug" in capsys.readouterr().out
def test_an_unknown_cause_never_reaches_the_log(
capsys: pytest.CaptureFixture[str],
) -> None:
with pytest.raises(SystemExit) as stop:
review_cli.main(["review-finish", "two-sum", "--cause", "bad-luck"])
assert stop.value.code != 0
assert "invalid choice" in capsys.readouterr().err
assert _nothing_written()
def test_without_a_signing_key_nothing_is_written_and_it_says_so(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
review_ledger.KEY_FILE.unlink()
code = review_cli.main(["review-finish", "two-sum", "--cause", "debugging"])
assert code == review_cli.EXIT_NOT_WRITTEN != 0
out = capsys.readouterr().out
assert out.startswith("nothing written: no signed ledger row (")
assert "no review event either" in out
assert _nothing_written()
def test_a_slug_with_a_row_gets_its_event_but_no_second_row(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
review_ledger.record("two-sum", "statement")
assert review_cli.main(["review-finish", "two-sum", "--cause", "debugging"]) == 0
assert [e["event"] for e in _events("two-sum")] == ["review"]
assert [r["detail"]["cause"] for r in _rows()] == ["statement"]
assert "ledger row: already there, not written twice" in capsys.readouterr().out
def test_a_lost_event_is_reported_as_exactly_that(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
fake_guard(tmp_path, monkeypatch, "two-sum")
def full_disk(*_args: object, **_fields: object) -> None:
raise OSError(28, "No space left on device")
monkeypatch.setattr(session_log, "append", full_disk)
code = review_cli.main(["review-finish", "two-sum", "--cause", "debugging"])
assert code == review_cli.EXIT_NOT_WRITTEN
out = capsys.readouterr().out
assert out.startswith("ledger row written, review event NOT logged (")
assert "run the same command again" in out
assert len(_rows()) == 1

View File

@ -0,0 +1,158 @@
"""The coach's own signed review ledger: one row per finished review."""
from __future__ import annotations
import datetime as dt
import importlib
import json
from pathlib import Path
from typing import TYPE_CHECKING, Any
import pytest
from leetcode_coach import review_ledger
from leetcode_coach.tests._review_support import (
REAL_KEY_FILE,
REAL_REVIEW_LEDGER,
REVIEW_KEY,
)
if TYPE_CHECKING:
from types import ModuleType
NOW = dt.datetime(
2026, 11, 21, 22, 5, 7, 123456, tzinfo=dt.timezone(dt.timedelta(hours=1))
)
REPO_ROOT = Path(__file__).resolve().parents[3]
# A real guard row (jq -c '.entries[-3]' of the guard ledger, 2026-11-21).
GUARD_ROW: dict[str, object] = {
"entry_id": "ac:2200718614",
"kind": "credit",
"day": "2026-11-21",
"created_at": "2026-11-21T18:01:58.572372+01:00",
"amount": 1,
"device": "pc",
"detail": {
"title_slug": "matrix-diagonal-sum",
"lang": "typescript",
"source": "leetcode",
"submitted_at": "1795280494",
},
"hmac": "f47d870875b9adcbc1fa4982ac56caf85fb1e206b2073fedba471694b84393ac",
}
def _ledger() -> dict[str, Any]:
data: dict[str, Any] = json.loads(
review_ledger.LEDGER_PATH.read_text(encoding="utf-8")
)
return data
def _earned_time(monkeypatch: pytest.MonkeyPatch) -> ModuleType:
"""The monorepo's own earned_time: the reader that must accept our rows."""
monkeypatch.syspath_prepend(str(REPO_ROOT / "earned_time"))
return importlib.import_module("earned_time")
def test_the_seams_point_away_from_the_real_machine(tmp_path: Path) -> None:
assert tmp_path in review_ledger.LEDGER_PATH.parents
assert tmp_path in review_ledger.KEY_FILE.parents
home = Path.home() / ".local" / "share" / "leetcode-coach"
assert home / "review_ledger.json" == REAL_REVIEW_LEDGER
assert Path("/etc/workout-locker/hmac.key") == REAL_KEY_FILE
def test_a_finished_review_writes_one_signed_row_in_the_guard_layout() -> None:
assert review_ledger.record("two-sum", "idea-to-code", now=NOW) is True
data = _ledger()
assert list(data) == ["version", "entries"]
assert data["version"] == 1
(row,) = data["entries"]
signature = row.pop("hmac")
assert row == {
"entry_id": "review:two-sum",
"kind": "credit",
"day": "2026-11-21",
"created_at": "2026-11-21T22:05:07.123456+01:00",
"amount": 1,
"device": "pc",
"detail": {
"title_slug": "two-sum",
"cause": "idea-to-code",
"source": "leetcode-coach-review",
"finished_at": str(int(NOW.timestamp())),
},
}
assert signature == review_ledger.entry_signature(row, REVIEW_KEY)
assert [p.name for p in review_ledger.LEDGER_PATH.parent.iterdir()] == [
"review_ledger.json"
]
def test_earned_time_verifies_the_row_and_signs_it_the_same(
monkeypatch: pytest.MonkeyPatch,
) -> None:
earned_time = _earned_time(monkeypatch)
review_ledger.record("two-sum", "missing-idea", now=NOW)
(row,) = _ledger()["entries"]
assert earned_time.verified(row, REVIEW_KEY) is True
assert row["hmac"] == earned_time.entry_signature(row, REVIEW_KEY)
odd = {**GUARD_ROW, "detail": {"title_slug": "zażółć", "n": 1.5, "x": None}}
for sample in (GUARD_ROW, odd):
assert review_ledger.entry_signature(
sample, REVIEW_KEY
) == earned_time.entry_signature(sample, REVIEW_KEY)
forged = {**row, "amount": 2}
assert earned_time.verified(forged, REVIEW_KEY) is False
def test_the_default_clock_is_local_time_with_an_offset() -> None:
review_ledger.record("two-sum", "debugging")
(row,) = _ledger()["entries"]
created = dt.datetime.fromisoformat(row["created_at"])
assert created.utcoffset() is not None
assert row["day"] == created.date().isoformat()
assert row["detail"]["finished_at"] == str(int(created.timestamp()))
def test_a_slug_is_never_written_twice() -> None:
assert review_ledger.record("two-sum", "debugging", now=NOW) is True
before = review_ledger.LEDGER_PATH.read_bytes()
assert review_ledger.record("two-sum", "statement", now=NOW) is False
assert review_ledger.LEDGER_PATH.read_bytes() == before
assert review_ledger.record("3sum", "statement", now=NOW) is True
assert [e["entry_id"] for e in _ledger()["entries"]] == [
"review:two-sum",
"review:3sum",
]
@pytest.mark.parametrize("content", [None, b"", b" \n"])
def test_without_a_key_nothing_is_written(content: bytes | None) -> None:
if content is None:
review_ledger.KEY_FILE.unlink()
else:
review_ledger.KEY_FILE.write_bytes(content)
with pytest.raises(review_ledger.LedgerError, match="signing key"):
review_ledger.record("two-sum", "debugging", now=NOW)
assert not review_ledger.LEDGER_PATH.exists()
@pytest.mark.parametrize("text", ["not json", '{"entries": 5}', "[]", "\xff"])
def test_an_unreadable_ledger_is_never_overwritten(text: str) -> None:
review_ledger.LEDGER_PATH.parent.mkdir(parents=True)
review_ledger.LEDGER_PATH.write_bytes(text.encode("latin-1"))
with pytest.raises(review_ledger.LedgerError, match="not overwritten"):
review_ledger.record("two-sum", "debugging", now=NOW)
assert review_ledger.LEDGER_PATH.read_bytes() == text.encode("latin-1")
def test_a_failed_write_is_a_ledger_error(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
blocker = tmp_path / "a-file"
blocker.write_text("x", encoding="utf-8")
monkeypatch.setattr(review_ledger, "LEDGER_PATH", blocker / "review_ledger.json")
with pytest.raises(review_ledger.LedgerError, match="cannot write"):
review_ledger.record("two-sum", "debugging", now=NOW)

View File

@ -81,3 +81,17 @@ def test_read_tolerates_a_missing_file_and_torn_lines(
assert "not JSON" in caplog.text
assert session_log.has_code(path)
assert not session_log.has_code(tmp_path / "other.jsonl")
def test_review_and_skeleton_are_events_with_their_payload(tmp_path: Path) -> None:
path = tmp_path / "log.jsonl"
session_log.append(path, "review", cause="missing-idea", module="hashing")
session_log.append(path, "skeleton", unit="hashing")
review, skeleton = session_log.read(path)
assert (review["event"], review["cause"], review["module"]) == (
"review",
"missing-idea",
"hashing",
)
assert (skeleton["event"], skeleton["unit"]) == ("skeleton", "hashing")
assert datetime.fromisoformat(review["ts"]).tzinfo is not None

View File

@ -0,0 +1,117 @@
"""`skeleton-open`: only after a code attempt, logged, the sheet byte for byte.
The stop gate lets a sheet through only when the reply quotes this command's
stdout verbatim, so stdout is the sheet file and nothing else; the one
confirmation line goes to stderr.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
import pytest
from leetcode_coach import review_cli, session_log
from leetcode_coach.tests._review_support import fake_guard
if TYPE_CHECKING:
from pathlib import Path
# Bare fences, tabs, no final newline: nothing a "helpful" print would keep.
SHEET = "# hashing\n\n```\nfunction solve(xs: number[]) {\n\t// HOLE: remember?\n}\n```"
def _sheet(text: str = SHEET) -> None:
review_cli.SKELETON_DIR.mkdir(parents=True, exist_ok=True)
(review_cli.SKELETON_DIR / "DOCS-hashing.md").write_bytes(text.encode())
def _logged(slug: str = "two-sum") -> list[tuple[str, object]]:
events = session_log.read(session_log.log_path(slug))
return [(e["event"], e.get("unit")) for e in events]
def test_after_code_stdout_is_the_sheet_unchanged_and_the_opening_is_logged(
capfdbinary: pytest.CaptureFixture[bytes],
) -> None:
_sheet()
session_log.append(session_log.log_path("two-sum"), "code")
assert review_cli.main(["skeleton-open", "two-sum", "hashing"]) == 0
captured = capfdbinary.readouterr()
assert captured.out == SHEET.encode()
assert captured.err == b"skeleton logged: two-sum, unit hashing\n"
assert _logged() == [("code", None), ("skeleton", "hashing")]
def test_code_from_an_earlier_day_counts(capsys: pytest.CaptureFixture[str]) -> None:
_sheet(SHEET + "\n")
old = session_log.sessions_dir() / "2026-10-01-two-sum.jsonl"
session_log.append(old, "code")
assert review_cli.main(["skeleton-open", "two-sum", "hashing"]) == 0
assert capsys.readouterr().out == SHEET + "\n"
assert _logged() == [("skeleton", "hashing")]
def test_a_flagged_solve_is_a_code_attempt_for_a_review(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
_sheet()
fake_guard(tmp_path, monkeypatch, "two-sum")
assert review_cli.main(["skeleton-open", "two-sum", "hashing"]) == 0
assert capsys.readouterr().out == SHEET
assert _logged() == [("skeleton", "hashing")]
def test_before_any_code_the_sheet_stays_shut(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
_sheet()
fake_guard(tmp_path, monkeypatch, "3sum")
session_log.append(session_log.log_path("two-sum"), "req", text="req: a")
code = review_cli.main(["skeleton-open", "two-sum", "hashing"])
assert code == review_cli.EXIT_REFUSED
out = capsys.readouterr().out
assert out.startswith("refused: two-sum has no code attempt yet")
assert "HOLE" not in out
assert _logged() == [("req", None)]
def test_no_code_and_no_guard_is_could_not_check(
capsys: pytest.CaptureFixture[str],
) -> None:
_sheet()
code = review_cli.main(["skeleton-open", "two-sum", "hashing"])
assert code == review_cli.EXIT_UNCHECKED
out = capsys.readouterr().out
assert out.startswith("could not check: ")
assert "HOLE" not in out
assert _logged() == []
def test_a_missing_sheet_is_an_error_and_logs_nothing(
capsys: pytest.CaptureFixture[str],
) -> None:
session_log.append(session_log.log_path("two-sum"), "code")
code = review_cli.main(["skeleton-open", "two-sum", "hashing"])
assert code == review_cli.EXIT_REFUSED
assert capsys.readouterr().out.startswith(
"refused: no skeleton sheet for unit 'hashing' at "
)
assert _logged() == [("code", None)]
@pytest.mark.parametrize(
("slug", "unit", "why"),
[
("two-sum", "../SKILL", "not a unit id"),
("two-sum", "Hashing", "not a unit id"),
("Two Sum", "hashing", "not a LeetCode problem URL or slug"),
],
)
def test_bad_names_are_refused(
capsys: pytest.CaptureFixture[str], slug: str, unit: str, why: str
) -> None:
_sheet()
assert review_cli.main(["skeleton-open", slug, unit]) == review_cli.EXIT_REFUSED
assert why in capsys.readouterr().out
assert _logged() == []

View File

@ -21,8 +21,9 @@ dependencies = [
include = ["leetcode_coach*"]
[tool.setuptools.package-data]
# The skill body and the launcher are read/executed from the package dir.
leetcode_coach = ["SKILL.md", "leetcode", "*.json", "py.typed"]
# The skill body, the texts it points to (DOCS-review.md, DOCS-skeletons.md),
# the skeleton sheets and the launcher are read/executed from the package dir.
leetcode_coach = ["*.md", "skeletons/*.md", "leetcode", "*.json", "py.typed"]
[tool.ruff]
target-version = "py314"
@ -75,6 +76,10 @@ unfixable = []
"leetcode_coach/cluster_cli.py" = ["T201"]
"leetcode_coach/toolbox_cards.py" = ["T201"]
"leetcode_coach/report.py" = ["T201"]
# review-list / review-finish / skeleton-open: the lines Claude reads back in
# a review. Without this entry the fixer emptied `_refuse` and `_unchecked`
# (2026-11-21) and the run still exited 0.
"leetcode_coach/review_cli.py" = ["T201"]
# S310 (urlopen scheme audit): all three open a fixed literal URL --
# AnkiConnect on 127.0.0.1, LeetCode's https GraphQL endpoint, and Ollama on
# localhost, where http_json additionally refuses any URL off OLLAMA_URL. They