diff --git a/.gitignore b/.gitignore index 1bfa6950..bcf6e1e2 100644 --- a/.gitignore +++ b/.gitignore @@ -25,8 +25,9 @@ !bin/loop_claude/**/*.py !bin/markdown_sections.py !bin/rank_todo.py -!bin/reading_cost.py -!bin/shell_reads.py +!bin/reading-cost +!bin/reading_cost/ +!bin/reading_cost/*.py !bin/statusline.py !bin/test_*.py !docs/ diff --git a/AGENTS.md b/AGENTS.md index f4a59110..40f17a90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ Decisions live in `docs/decisions.md`: - settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped - the repo may name bender, bender-infra and ai-sandbox - todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py` -- reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/comprehension-history.md` in the next chunk's PR +- reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/reading-cost.md` in the next chunk's PR - reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item ## Working rules diff --git a/CHANGELOG.md b/CHANGELOG.md index 613aedca..00a4b450 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## Unreleased -- larv-review runs the new `bin/reading_cost.py`, which measures each chunk `loop-claude` finished from its archive: the new input tokens the worker and its subagents took in before the worker's first commit, and the files git tracks that they read most. It appends each figure the project's `docs/comprehension-history.md` lacks. Once 10 chunks are measured, and the last 5 chunks' median is above the 5 before them, larv-review files one plan item naming the files read most, or refreshes it. The chunk that ships it runs `reading_cost.py --reset`, so the trend counts only chunks that finished after it. +- larv-review runs the new `bin/reading-cost`, which measures each chunk `loop-claude` finished from its archive: the new input tokens the worker and its subagents took in before the worker's first commit, and the files git tracks that they read most. It appends each figure the project's `docs/reading-cost.md` lacks. Once 10 chunks are measured, and the last 5 chunks' median is above the 5 before them, larv-review files one plan item naming the files read most, or refreshes it. The chunk that ships it runs `reading-cost --reset`, so the trend counts only chunks that finished after it. - larv-review appends every scoring run to the project's `docs/comprehension-history.md`: the commit the seats read, each seat's five scores and the seats' mean, and the places each seat named. The ratchet compares a run with the history's last run on the default branch. The `comprehension floor:` entry in `docs/decisions.md` keeps only the decisions to ship under the floor; a project's next scoring run moves the last scores the entry still holds into the history. The seats do not read the history. - The README's goals put quality with the fewest interrupts first, as goal 1; sharing the setup, backups and leaking nothing follow as goals 2–4. - larv-review reruns the comprehension scoring run before merge when any commit since the last run changes more than `docs/decisions.md`, `docs/comprehension-history.md`, `todo.md` or `CHANGELOG.md`, so the recorded scores are the merged commit's. A score under the floor, or below the default branch's recorded scores, blocks the merge and is never filed in `todo.md`. A fix lifts either; your decision to ship under the floor lifts only a score under the floor. A rerun counts toward the three-round cap only when it reports a blocking score that no decision of yours covers. diff --git a/README.md b/README.md index ad898b4e..f55d6009 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Rename `## Unreleased` in `CHANGELOG.md` to the version, commit, tag that commit - `loop-claude ` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract. - `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`; `rank_todo.py --help` states the format. -- `reading_cost.py [--reset] [history]` appends a figure for each chunk `loop-claude` finished to a project's comprehension history, and says whether the figures rise; `reading_cost.py --help` states the measure. +- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure. - `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it. Test on the host, with `uv` on `PATH` to fetch mypy and the Python version Install names (`docs/decisions.md` → `bin/`): `python3 -m unittest discover -s bin -p 'test_*.py'` diff --git a/bin/reading-cost b/bin/reading-cost new file mode 100755 index 00000000..9f370fb6 --- /dev/null +++ b/bin/reading-cost @@ -0,0 +1,9 @@ +#!/usr/bin/env python3 +import pathlib +import sys + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) + +from reading_cost import main + +sys.exit(main.main(sys.argv[1:])) diff --git a/bin/reading_cost.py b/bin/reading_cost.py deleted file mode 100644 index 5e3d2267..00000000 --- a/bin/reading_cost.py +++ /dev/null @@ -1,281 +0,0 @@ -#!/usr/bin/env python3 -"""Measure each chunk loop-claude finished, append the figures to a project's history, and say whether they rise. - -usage: reading_cost.py [--reset] [history] - -Run it inside a project checkout or one of its worktrees. history defaults to -docs/comprehension-history.md there, created when missing. It reads loop-claude's archive of the -project, $LOOP_CLAUDE_TRANSCRIPTS/ (default ~/.claude/loop-claude-transcripts), being the -checkout's path relative to ~/code, or to / outside it. For each finished chunk the history does not -yet hold, it measures what the worker and its subagents read before the worker's first commit: their -new input tokens (uncached and cache-written; cache reads excluded), and how often they opened or -searched each file git tracks in the checkout. A chunk whose worker never committed is not measured. -Each figure is appended under a "## Reading cost, chunk , finished " heading, in the -order the chunks finished. - ---reset also appends a "## Reading cost reset, " heading: the trend then counts only -figures of chunks that finished after it. - -It then compares the median tokens of the history's last 5 figures with the 5 before them, in -the order their chunks finished, and prints "Rising:" or "Not rising:" with both medians. Rising, it -lists the files the last 5 chunks read most. With fewer than 10 figures, it says so. - -Exit 1, saying why, on unknown arguments, or when git cannot start or finds no checkout, the -archive or the history cannot be read or written, or a figure in the history cannot be read back. -""" -import collections -import dataclasses -import os -import pathlib -import re -import statistics -import subprocess -import sys -import time - -sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) - -from loop_claude.claude_code.entries import assistant_parts, parse_entry, tool_call -from failure import Failure -from loop_claude.transcript_archive import finished_chunks, FinishedChunk, utc -from loop_claude.paths import paths_from -from loop_claude.project.checkout import project_key -from shell_reads import Reads, resolved, shell_reads -from file_writes import replace_file -from markdown_sections import sections - -COMMIT = re.compile(r"(^|[\s;&|(])git\s+(-C\s+\S+\s+)?commit\b") -HEADING = "Reading cost, chunk " -PLACE = re.compile(r"^- `(.+)` (\d+)$") -PLACES_KEPT = 10 -RESET = "Reading cost reset, " -TOKENS = re.compile(r"^(\d+) new input tokens before the first commit\.$") -WINDOW = 5 - - -@dataclasses.dataclass(frozen=True) -class Reading: - """What the worker and its subagents took in before the worker's first commit.""" - tokens: int - places: collections.Counter[str] - - -@dataclasses.dataclass(frozen=True) -class Checkout: - root: str - top: str - tracked: frozenset[str] - - -def main(argv: list[str]) -> int: - reset = argv[:1] == ["--reset"] - given = argv[1:] if reset else argv - if given in (["-h"], ["--help"]): - print(__doc__.strip()) - return 0 - if len(given) > 1 or given[:1] and given[0].startswith("-"): - print(f"unknown arguments {' '.join(given)}; usage: reading_cost.py [--reset] [history]", file=sys.stderr) - return 1 - checkout = located() - if isinstance(checkout, Failure): - return failed(checkout) - home = pathlib.Path.home() - paths = paths_from(home, os.environ) - archive = paths.transcript_archive / project_key(checkout.root, paths.code) - history = pathlib.Path(given[0]) if given else pathlib.Path(checkout.top, "docs", "comprehension-history.md") - updated = update(history, archive, checkout, str(home), utc(time.time()) if reset else None) - if isinstance(updated, Failure): - return failed(updated) - appended, readings = updated - print(f"Appended {appended} reading-cost figure{'' if appended == 1 else 's'} from {archive}{' and a reset' if reset else ''} to {history}.") - print(trend(readings)) - return 0 - - -def update(history: pathlib.Path, archive: pathlib.Path, checkout: Checkout, home: str, reset_at: str | None) -> tuple[int, list[Reading]] | Failure: - """How many figures it appended, and the readings the trend counts.""" - text = read_history(history) - if isinstance(text, Failure): - return text - figures = new_figures(text, archive, checkout, home) - if isinstance(figures, Failure): - return figures - marks = [*figures, f"## {RESET}{reset_at}\n"] if reset_at else figures - text = merged(text, marks) if marks else text - readings = readings_of(text) - if isinstance(readings, Failure): - return readings - if marks and (unwritten := write_history(history, text)): - return unwritten - return len(figures), readings - - -def new_figures(history: str, archive: pathlib.Path, checkout: Checkout, home: str) -> list[str] | Failure: - chunks = finished_chunks(archive) - if isinstance(chunks, Failure): - return chunks - figures = [] - for chunk in unheld(chunks, history): - threads = read_threads(chunk) - if isinstance(threads, Failure): - return threads - if reading := measure(threads, checkout, home): - figures.append(figure(chunk, reading)) - return figures - - -def write_history(history: pathlib.Path, text: str) -> Failure | None: - try: - history.parent.mkdir(parents=True, exist_ok=True) - except OSError as failure: - return Failure(f"could not write {history}: {failure.strerror}") - unwritten = replace_file(history, text.encode()) - return Failure(f"could not write {history}: {unwritten.reason}") if unwritten else None - - -def failed(failure: Failure) -> int: - print(failure.reason, file=sys.stderr) - return 1 - - -def located() -> Checkout | Failure: - try: - found = subprocess.run(["git", "rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], capture_output=True, text=True) - if found.returncode != 0: - return Failure(found.stderr.strip()) - top, common = found.stdout.splitlines() - listed = subprocess.run(["git", "ls-files", "-z"], capture_output=True, cwd=top, text=True) - except (OSError, ValueError) as failure: - return Failure(f"could not find the checkout: {failure}") - if listed.returncode != 0: - return Failure(listed.stderr.strip()) - # The common dir is the checkout's .git, whichever worktree runs this. - return Checkout(str(pathlib.Path(common).parent), top, frozenset(filter(None, listed.stdout.split("\0")))) - - -def read_history(history: pathlib.Path) -> str | Failure: - try: - return history.read_text(encoding="utf-8") if history.exists() else "# Comprehension history\n" - except (OSError, UnicodeDecodeError) as failure: - return Failure(f"could not read {history}: {failure}") - - -def read_threads(chunk: FinishedChunk) -> list[bytes] | Failure: - """The worker's transcript, then each subagent's.""" - try: - return [path.read_bytes() for path in (chunk.transcript, *chunk.subagents)] - except OSError as failure: - return Failure(f"could not read {failure.filename}: {failure.strerror}") - - -def unheld(chunks: list[FinishedChunk], history: str) -> list[FinishedChunk]: - held = {heading.removeprefix(HEADING).split(",")[0] for heading in sections(history) if heading.startswith(HEADING)} - return [chunk for chunk in chunks if chunk_id(chunk) not in held] - - -def chunk_id(chunk: FinishedChunk) -> str: - return chunk.folder[:12] - - -def measure(threads: list[bytes], checkout: Checkout, home: str) -> Reading | None: - worker, *subagents = [entries_of(thread) for thread in threads] - commit = commit_time(worker) - if commit is None: - return None - before = [[entry for entry in thread if entry.get("type") == "assistant" and str(entry.get("timestamp", "")) < commit] for thread in (worker, *subagents)] - reads = [reads_of(part, str(entry.get("cwd") or "/"), home) for thread in before for entry in thread for part in assistant_parts(entry)] - roots = [checkout.root, *(added for found in reads for added in found.added)] - places = collections.Counter(place for found in reads for path in found.read if (place := relative(path, roots)) in checkout.tracked) - return Reading(sum(map(tokens_in, before)), places) - - -def entries_of(raw: bytes) -> list[dict]: - return [entry for line in raw.splitlines() if (entry := parse_entry(line))] - - -def commit_time(worker: list[dict]) -> str | None: - for entry in worker: - for part in assistant_parts(entry): - name, arguments = call_of(part) - if name == "Bash" and COMMIT.search(str(arguments.get("command", ""))): - return str(entry.get("timestamp", "")) - return None - - -def tokens_in(entries: list[dict]) -> int: - # Claude Code writes one entry per content block of a message, each with the message's usage. - usages = {str(message.get("id") or entry.get("uuid")): message.get("usage") for entry in entries if isinstance(message := entry.get("message"), dict)} - return sum(count(usage, "input_tokens") + count(usage, "cache_creation_input_tokens") for usage in usages.values() if isinstance(usage, dict)) - - -# A count Claude Code left out or wrote as another type adds nothing, so one odd entry leaves the rest of the figure standing. -def count(usage: dict, field: str) -> int: - value = usage.get(field) - return value if isinstance(value, int) else 0 - - -def call_of(part: object) -> tuple[object, dict]: - call = tool_call(part) - return (call[0], call[1]) if call and isinstance(call[1], dict) else (None, {}) - - -def reads_of(part: object, cwd: str, home: str) -> Reads: - name, arguments = call_of(part) - path = arguments.get("file_path") if name == "Read" else arguments.get("path") if name == "Grep" else None - if path: - return Reads([resolved(cwd, str(path), home)], []) - return shell_reads(str(arguments.get("command", "")), cwd, home) if name == "Bash" else Reads([], []) - - -# Relative to the deepest root holding it, so the checkout and each worktree name a file alike. -def relative(path: str, roots: list[str]) -> str | None: - holding = [root for root in roots if path.startswith(root.rstrip("/") + "/")] - return path[len(max(holding, key=len).rstrip("/")) + 1:] if holding else None - - -def figure(chunk: FinishedChunk, reading: Reading) -> str: - places = "".join(f"- `{path}` {times}\n" for path, times in ranked(reading.places)) - return f"## {HEADING}{chunk_id(chunk)}, finished {chunk.finished}\n\n{reading.tokens} new input tokens before the first commit.\n" + (f"\nRead most (opens and searches):\n\n{places}" if places else "") - - -# The figures after the last reset, in the order their chunks finished: each machine appends its own archive's chunks. -def readings_of(history: str) -> list[Reading] | Failure: - dated = [] - resets = [""] - for heading, bodies in sections(history).items(): - if heading.startswith(RESET): - resets.append(heading.removeprefix(RESET)) - elif heading.startswith(HEADING): - lines = bodies[0].splitlines() if bodies else [] - tokens = [int(match.group(1)) for line in lines if (match := TOKENS.match(line))] - if len(tokens) != 1: - return Failure(f"the figure under \"## {heading}\" holds no single tokens line; restore it from git history") - dated.append((heading.rsplit(", finished ", 1)[-1], Reading(tokens[0], collections.Counter({match.group(1): int(match.group(2)) for line in lines if (match := PLACE.match(line))})))) - return [reading for finished, reading in sorted(dated, key=lambda item: item[0]) if finished > max(resets)] - - -def ranked(places: collections.Counter[str]) -> list[tuple[str, int]]: - return sorted(places.items(), key=lambda item: (-item[1], item[0]))[:PLACES_KEPT] - - -def merged(history: str, figures: list[str]) -> str: - return history.rstrip("\n") + "\n\n" + "\n".join(figures) - - -def trend(readings: list[Reading]) -> str: - if len(readings) < 2 * WINDOW: - return f"{len(readings)} chunks measured since the last reset; the trend needs {2 * WINDOW}." - last, earlier = middle(readings[-WINDOW:]), middle(readings[-2 * WINDOW:-WINDOW]) - medians = f"the last {WINDOW} chunks' median is {last} new input tokens before their first commit, the {WINDOW} before them {earlier}." - if last <= earlier: - return f"Not rising: {medians}" - read_most = "".join(f"\n- `{path}` {times}" for path, times in ranked(sum((reading.places for reading in readings[-WINDOW:]), collections.Counter()))) - return f"Rising: {medians}\n\nRead most over the last {WINDOW} (opens and searches):\n{read_most}" - - -def middle(readings: list[Reading]) -> int: - return round(statistics.median(reading.tokens for reading in readings)) - - -if __name__ == "__main__": - sys.exit(main(sys.argv[1:])) diff --git a/bin/reading_cost/__init__.py b/bin/reading_cost/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/bin/reading_cost/archive.py b/bin/reading_cost/archive.py new file mode 100644 index 00000000..f2f01328 --- /dev/null +++ b/bin/reading_cost/archive.py @@ -0,0 +1,20 @@ +import pathlib +import typing + +from failure import Failure +from loop_claude.transcript_archive import finished_chunks, FinishedChunk, utc +from loop_claude.paths import paths_from +from loop_claude.project.checkout import project_key + + +def project_archive(checkout_root: str, home: pathlib.Path, env: typing.Mapping[str, str]) -> pathlib.Path: + paths = paths_from(home, env) + return paths.transcript_archive / project_key(checkout_root, paths.code) + + +def read_threads(chunk: FinishedChunk) -> list[bytes] | Failure: + """The worker's transcript, then each subagent's.""" + try: + return [path.read_bytes() for path in (chunk.transcript, *chunk.subagents)] + except OSError as failure: + return Failure(f"could not read {failure.filename}: {failure.strerror}") diff --git a/bin/reading_cost/figures.py b/bin/reading_cost/figures.py new file mode 100644 index 00000000..03a7b69f --- /dev/null +++ b/bin/reading_cost/figures.py @@ -0,0 +1,68 @@ +import collections +import re +import statistics + +from failure import Failure +from reading_cost.archive import FinishedChunk +from reading_cost.measure import Reading +from markdown_sections import sections + +HEADING = "Reading cost, chunk " +PLACE = re.compile(r"^- `(.+)` (\d+)$") +PLACES_KEPT = 10 +RESET = "Reading cost reset, " +TOKENS = re.compile(r"^(\d+) new input tokens before the first commit\.$") +WINDOW = 5 + + +def unheld(chunks: list[FinishedChunk], record: str) -> list[FinishedChunk]: + held = {heading.removeprefix(HEADING).split(",")[0] for heading in sections(record) if heading.startswith(HEADING)} + return [chunk for chunk in chunks if chunk_id(chunk) not in held] + + +def chunk_id(chunk: FinishedChunk) -> str: + return chunk.folder[:12] + + +def figure(chunk: FinishedChunk, reading: Reading) -> str: + places = "".join(f"- `{path}` {times}\n" for path, times in ranked(reading.places)) + return f"## {HEADING}{chunk_id(chunk)}, finished {chunk.finished}\n\n{reading.tokens} new input tokens before the first commit.\n" + (f"\nRead most (opens and searches):\n\n{places}" if places else "") + + +# The figures after the last reset, in the order their chunks finished: each machine appends its own archive's chunks. +def readings_of(record: str) -> list[Reading] | Failure: + dated = [] + resets = [""] + for heading, bodies in sections(record).items(): + if heading.startswith(RESET): + resets.append(heading.removeprefix(RESET)) + elif heading.startswith(HEADING): + lines = bodies[0].splitlines() if bodies else [] + tokens = [int(match.group(1)) for line in lines if (match := TOKENS.match(line))] + if len(tokens) != 1: + return Failure(f"the figure under \"## {heading}\" holds no single tokens line; restore it from git history") + dated.append((heading.rsplit(", finished ", 1)[-1], Reading(tokens[0], collections.Counter({match.group(1): int(match.group(2)) for line in lines if (match := PLACE.match(line))})))) + return [reading for finished, reading in sorted(dated, key=lambda item: item[0]) if finished > max(resets)] + + +def ranked(places: collections.Counter[str]) -> list[tuple[str, int]]: + return sorted(places.items(), key=lambda item: (-item[1], item[0]))[:PLACES_KEPT] + + +def merged(record: str, figures: list[str]) -> str: + return record.rstrip("\n") + "\n\n" + "\n".join(figures) + + +def trend(readings: list[Reading]) -> str: + if len(readings) < 2 * WINDOW: + return f"{len(readings)} chunks measured since the last reset; the trend needs {2 * WINDOW}." + last, earlier = median_tokens(readings[-WINDOW:]), median_tokens(readings[-2 * WINDOW:-WINDOW]) + medians = f"the last {WINDOW} chunks' median is {last} new input tokens before their first commit, the {WINDOW} before them {earlier}." + if last <= earlier: + return f"Not rising: {medians}" + read_most = "".join(f"\n- `{path}` {times}" for path, times in ranked(sum((reading.places for reading in readings[-WINDOW:]), collections.Counter()))) + return f"Rising: {medians}\n\nRead most over the last {WINDOW} (opens and searches):\n{read_most}" + + +def median_tokens(readings: list[Reading]) -> int: + return round(statistics.median(reading.tokens for reading in readings)) diff --git a/bin/reading_cost/main.py b/bin/reading_cost/main.py new file mode 100644 index 00000000..7530fe34 --- /dev/null +++ b/bin/reading_cost/main.py @@ -0,0 +1,126 @@ +"""Measure each chunk loop-claude finished, append the figures to a project's record, and say whether they rise. + +usage: reading-cost [--reset] [record] + +Run it inside a project checkout or one of its worktrees. record defaults to docs/reading-cost.md +there, created when missing. It reads loop-claude's archive of the project, +$LOOP_CLAUDE_TRANSCRIPTS/ (default ~/.claude/loop-claude-transcripts), being the +checkout's path relative to ~/code, or to / outside it. For each finished chunk the record does not +yet hold, it measures what the worker and its subagents read before the worker's first commit: their +new input tokens (uncached and cache-written; cache reads excluded), and how often they opened or +searched each file git tracks in the checkout. A chunk whose worker never committed is not measured. +Each figure is appended under a "## Reading cost, chunk , finished " heading, in the +order the chunks finished. + +--reset also appends a "## Reading cost reset, " heading: the trend then counts only +figures of chunks that finished after it. + +It then compares the median tokens of the record's last 5 figures with the 5 before them, in the +order their chunks finished, and prints "Rising:" or "Not rising:" with both medians. Rising, it +lists the files the last 5 chunks read most. With fewer than 10 figures, it says so. + +Exit 1, saying why, on unknown arguments, or when git cannot start or finds no checkout, the +archive or the record cannot be read or written, or a figure in the record cannot be read back. +""" +import os +import pathlib +import subprocess +import sys +import time + +from reading_cost.measure import Checkout, measure, Reading +from failure import Failure +from reading_cost.figures import figure, merged, readings_of, RESET, trend, unheld +from reading_cost.archive import finished_chunks, project_archive, read_threads, utc +from file_writes import replace_file + +def main(argv: list[str]) -> int: + reset = argv[:1] == ["--reset"] + given = argv[1:] if reset else argv + if given in (["-h"], ["--help"]): + print(__doc__.strip()) + return 0 + if len(given) > 1 or given[:1] and given[0].startswith("-"): + print(f"unknown arguments {' '.join(given)}; usage: reading-cost [--reset] [record]", file=sys.stderr) + return 1 + checkout = located() + if isinstance(checkout, Failure): + return failed(checkout) + home = pathlib.Path.home() + archive = project_archive(checkout.root, home, os.environ) + record = pathlib.Path(given[0]) if given else pathlib.Path(checkout.top, "docs", "reading-cost.md") + updated = update(record, archive, checkout, str(home), utc(time.time()) if reset else None) + if isinstance(updated, Failure): + return failed(updated) + appended, readings = updated + print(f"Appended {appended} reading-cost figure{'' if appended == 1 else 's'} from {archive}{' and a reset' if reset else ''} to {record}.") + print(trend(readings)) + return 0 + + +def update(record: pathlib.Path, archive: pathlib.Path, checkout: Checkout, home: str, reset_at: str | None) -> tuple[int, list[Reading]] | Failure: + """How many figures it appended, and the readings the trend counts.""" + text = read_record(record) + if isinstance(text, Failure): + return text + figures = new_figures(text, archive, checkout, home) + if isinstance(figures, Failure): + return figures + marks = [*figures, f"## {RESET}{reset_at}\n"] if reset_at else figures + text = merged(text, marks) if marks else text + readings = readings_of(text) + if isinstance(readings, Failure): + return readings + if marks and (unwritten := write_record(record, text)): + return unwritten + return len(figures), readings + + +def new_figures(record: str, archive: pathlib.Path, checkout: Checkout, home: str) -> list[str] | Failure: + chunks = finished_chunks(archive) + if isinstance(chunks, Failure): + return chunks + figures = [] + for chunk in unheld(chunks, record): + threads = read_threads(chunk) + if isinstance(threads, Failure): + return threads + if reading := measure(threads, checkout, home): + figures.append(figure(chunk, reading)) + return figures + + +def write_record(record: pathlib.Path, text: str) -> Failure | None: + try: + record.parent.mkdir(parents=True, exist_ok=True) + except OSError as failure: + return Failure(f"could not write {record}: {failure.strerror}") + unwritten = replace_file(record, text.encode()) + return Failure(f"could not write {record}: {unwritten.reason}") if unwritten else None + + +def failed(failure: Failure) -> int: + print(failure.reason, file=sys.stderr) + return 1 + + +def located() -> Checkout | Failure: + try: + found = subprocess.run(["git", "rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], capture_output=True, text=True) + if found.returncode != 0: + return Failure(found.stderr.strip()) + top, common = found.stdout.splitlines() + listed = subprocess.run(["git", "ls-files", "-z"], capture_output=True, cwd=top, text=True) + except (OSError, ValueError) as failure: + return Failure(f"could not find the checkout: {failure}") + if listed.returncode != 0: + return Failure(listed.stderr.strip()) + # The common dir is the checkout's .git, whichever worktree runs this. + return Checkout(str(pathlib.Path(common).parent), top, frozenset(filter(None, listed.stdout.split("\0")))) + + +def read_record(record: pathlib.Path) -> str | Failure: + try: + return record.read_text(encoding="utf-8") if record.exists() else "# Reading cost\n" + except (OSError, UnicodeDecodeError) as failure: + return Failure(f"could not read {record}: {failure}") diff --git a/bin/reading_cost/measure.py b/bin/reading_cost/measure.py new file mode 100644 index 00000000..226ee692 --- /dev/null +++ b/bin/reading_cost/measure.py @@ -0,0 +1,80 @@ +import collections +import dataclasses +import re + +from loop_claude.claude_code.entries import assistant_parts, parse_entry, tool_call +from reading_cost.shell_reads import Reads, resolved, shell_reads + +COMMIT = re.compile(r"(^|[\s;&|(])git\s+(-C\s+\S+\s+)?commit\b") + + + +@dataclasses.dataclass(frozen=True) +class Reading: + """What the worker and its subagents took in before the worker's first commit.""" + tokens: int + places: collections.Counter[str] + + + +@dataclasses.dataclass(frozen=True) +class Checkout: + root: str + top: str + tracked: frozenset[str] + + +def measure(threads: list[bytes], checkout: Checkout, home: str) -> Reading | None: + worker, *subagents = [entries_of(thread) for thread in threads] + commit = commit_time(worker) + if commit is None: + return None + before = [[entry for entry in thread if entry.get("type") == "assistant" and str(entry.get("timestamp", "")) < commit] for thread in (worker, *subagents)] + reads = [reads_of(part, str(entry.get("cwd") or "/"), home) for thread in before for entry in thread for part in assistant_parts(entry)] + roots = [checkout.root, *(added for found in reads for added in found.added)] + places = collections.Counter(place for found in reads for path in found.read if (place := relative(path, roots)) in checkout.tracked) + return Reading(sum(map(tokens_in, before)), places) + + +def entries_of(raw: bytes) -> list[dict]: + return [entry for line in raw.splitlines() if (entry := parse_entry(line))] + + +def commit_time(worker: list[dict]) -> str | None: + for entry in worker: + for part in assistant_parts(entry): + name, arguments = call_of(part) + if name == "Bash" and COMMIT.search(str(arguments.get("command", ""))): + return str(entry.get("timestamp", "")) + return None + + +def tokens_in(entries: list[dict]) -> int: + # Claude Code writes one entry per content block of a message, each with the message's usage. + usages = {str(message.get("id") or entry.get("uuid")): message.get("usage") for entry in entries if isinstance(message := entry.get("message"), dict)} + return sum(count(usage, "input_tokens") + count(usage, "cache_creation_input_tokens") for usage in usages.values() if isinstance(usage, dict)) + + +# A count Claude Code left out or wrote as another type adds nothing, so one odd entry leaves the rest of the figure standing. +def count(usage: dict, field: str) -> int: + value = usage.get(field) + return value if isinstance(value, int) else 0 + + +def call_of(part: object) -> tuple[object, dict]: + call = tool_call(part) + return (call[0], call[1]) if call and isinstance(call[1], dict) else (None, {}) + + +def reads_of(part: object, cwd: str, home: str) -> Reads: + name, arguments = call_of(part) + path = arguments.get("file_path") if name == "Read" else arguments.get("path") if name == "Grep" else None + if path: + return Reads([resolved(cwd, str(path), home)], []) + return shell_reads(str(arguments.get("command", "")), cwd, home) if name == "Bash" else Reads([], []) + + +# Relative to the deepest root holding it, so the checkout and each worktree name a file alike. +def relative(path: str, roots: list[str]) -> str | None: + holding = [root for root in roots if path.startswith(root.rstrip("/") + "/")] + return path[len(max(holding, key=len).rstrip("/")) + 1:] if holding else None diff --git a/bin/shell_reads.py b/bin/reading_cost/shell_reads.py similarity index 100% rename from bin/shell_reads.py rename to bin/reading_cost/shell_reads.py diff --git a/bin/test_reading_cost.py b/bin/test_reading_cost.py index 52e86d34..0e7db0e5 100644 --- a/bin/test_reading_cost.py +++ b/bin/test_reading_cost.py @@ -13,14 +13,14 @@ import unittest sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) from loop_claude.transcript_archive import archive, FINISHED, FINISHED_AT, finished_chunks, FinishedChunk, UNFINISHED, utc -from reading_cost import Checkout, Reading +from reading_cost.measure import Checkout, Reading from failure import Failure +from reading_cost import figures, measure from test_loop_claude_black_box import host_env from loop_claude.paths import paths_from -import reading_cost -from shell_reads import Reads, shell_reads +from reading_cost.shell_reads import Reads, shell_reads -TOOL = pathlib.Path(__file__).resolve().parent / "reading_cost.py" +TOOL = pathlib.Path(__file__).resolve().parent / "reading-cost" def said(timestamp, message_id, command=None, tokens=0, cwd="/c/p", **call): @@ -60,36 +60,36 @@ class Measure(unittest.TestCase): ] subagent = [said("2", "s1", tokens=1, name="Grep", input={"path": "/c/w/src/a.py"}), said("7", "s2", tokens=100, name="Read", input={"file_path": "/c/p/late.py"})] checkout = Checkout("/c/p", "/c/w", frozenset({"README.md", "late.py", "src/a.py", "src/b.py", "x.py"})) - self.assertEqual(reading_cost.measure([jsonl(worker), jsonl(subagent)], checkout, "/h"), Reading(33, collections.Counter({"src/a.py": 2, "README.md": 1, "src/b.py": 1}))) + self.assertEqual(measure.measure([jsonl(worker), jsonl(subagent)], checkout, "/h"), Reading(33, collections.Counter({"src/a.py": 2, "README.md": 1, "src/b.py": 1}))) def test_measures_nothing_for_a_worker_that_never_committed(self): - self.assertIsNone(reading_cost.measure([jsonl([said("1", "m1", command="git log --grep commit")])], Checkout("/c/p", "/c/p", frozenset()), "/h")) + self.assertIsNone(measure.measure([jsonl([said("1", "m1", command="git log --grep commit")])], Checkout("/c/p", "/c/p", frozenset()), "/h")) def test_skips_a_usage_that_is_not_a_count(self): - self.assertEqual(reading_cost.tokens_in([{"message": {"id": "m", "usage": {"input_tokens": "7", "cache_creation_input_tokens": 2}}}]), 2) + self.assertEqual(measure.tokens_in([{"message": {"id": "m", "usage": {"input_tokens": "7", "cache_creation_input_tokens": 2}}}]), 2) class Figures(unittest.TestCase): def test_rises_only_above_the_five_before_and_needs_ten(self): flat = [Reading(100, collections.Counter({"a.py": 1}))] * 10 - self.assertEqual(reading_cost.trend(flat[:9]), "9 chunks measured since the last reset; the trend needs 10.") - self.assertTrue(reading_cost.trend(flat).startswith("Not rising: the last 5 chunks' median is 100 new input tokens")) - self.assertTrue(reading_cost.trend(flat[:9] + [Reading(3000000, collections.Counter())]).startswith("Not rising:")) - self.assertEqual(reading_cost.trend(flat[:5] + [Reading(101, collections.Counter({"b.py": 2}))] * 5), "Rising: the last 5 chunks' median is 101 new input tokens before their first commit, the 5 before them 100.\n\nRead most over the last 5 (opens and searches):\n\n- `b.py` 10") + self.assertEqual(figures.trend(flat[:9]), "9 chunks measured since the last reset; the trend needs 10.") + self.assertTrue(figures.trend(flat).startswith("Not rising: the last 5 chunks' median is 100 new input tokens")) + self.assertTrue(figures.trend(flat[:9] + [Reading(3000000, collections.Counter())]).startswith("Not rising:")) + self.assertEqual(figures.trend(flat[:5] + [Reading(101, collections.Counter({"b.py": 2}))] * 5), "Rising: the last 5 chunks' median is 101 new input tokens before their first commit, the 5 before them 100.\n\nRead most over the last 5 (opens and searches):\n\n- `b.py` 10") def test_a_figure_reads_back_as_the_reading_it_was_written_from_and_a_damaged_one_fails(self): reading = Reading(7, collections.Counter({"b.py": 1, "a.py": 3})) - written = reading_cost.figure(FinishedChunk("abcdef0123456789", "t", pathlib.Path(), []), reading) + written = figures.figure(FinishedChunk("abcdef0123456789", "t", pathlib.Path(), []), reading) self.assertEqual(written, "## Reading cost, chunk abcdef012345, finished t\n\n7 new input tokens before the first commit.\n\nRead most (opens and searches):\n\n- `a.py` 3\n- `b.py` 1\n") - self.assertEqual(reading_cost.readings_of(written), [reading]) - self.assertEqual(reading_cost.readings_of(written.replace("7 new", "seven new")), Failure('the figure under "## Reading cost, chunk abcdef012345, finished t" holds no single tokens line; restore it from git history')) + self.assertEqual(figures.readings_of(written), [reading]) + self.assertEqual(figures.readings_of(written.replace("7 new", "seven new")), Failure('the figure under "## Reading cost, chunk abcdef012345, finished t" holds no single tokens line; restore it from git history')) def test_counts_only_figures_finished_after_the_last_reset_in_the_order_they_finished(self): def written(chunk, finished, tokens): - return reading_cost.figure(FinishedChunk(chunk, finished, pathlib.Path(), []), Reading(tokens, collections.Counter())) + return figures.figure(FinishedChunk(chunk, finished, pathlib.Path(), []), Reading(tokens, collections.Counter())) history = "\n".join([written("a", "2026-10-01T00:00:00Z", 1), written("c", "2026-10-03T00:00:00Z", 3), "## Reading cost reset, 2026-10-02T00:00:00Z\n", written("b", "2026-10-04T00:00:00Z", 2)]) - self.assertEqual(reading_cost.readings_of(history), [Reading(3, collections.Counter()), Reading(2, collections.Counter())]) + self.assertEqual(figures.readings_of(history), [Reading(3, collections.Counter()), Reading(2, collections.Counter())]) def test_the_archive_stamps_what_it_reads_back(self): self.assertRegex(f"{utc(1790000000)} {FINISHED}", FINISHED_AT) @@ -134,10 +134,10 @@ class ReadingCostTool(unittest.TestCase): self.git("worktree", "add", "-q", str(worktree)) ran = self.run_tool(worktree) self.assertEqual(ran.returncode, 0, ran.stderr) - history = worktree / "docs" / "comprehension-history.md" + history = worktree / "docs" / "reading-cost.md" self.assertEqual(ran.stdout, f"Appended 2 reading-cost figures from {self.home / '.claude' / 'loop-claude-transcripts' / 'proj'} to {history}.\n2 chunks measured since the last reset; the trend needs 10.\n") figure = "## Reading cost, chunk {}, finished {}\n\n33 new input tokens before the first commit.\n\nRead most (opens and searches):\n\n- `a.py` 1\n" - self.assertEqual(history.read_text(), "# Comprehension history\n\n" + "\n".join(figure.format(chunk.folder[:12], chunk.finished) for chunk in chunks)) + self.assertEqual(history.read_text(), "# Reading cost\n\n" + "\n".join(figure.format(chunk.folder[:12], chunk.finished) for chunk in chunks)) self.assertTrue(self.run_tool(worktree).stdout.startswith(f"Appended 0 reading-cost figures from")) self.assertEqual(history.read_text().count("## Reading cost"), 2) reset = self.run_tool(worktree, "--reset") diff --git a/bin/test_types.py b/bin/test_types.py index 18a7bbb4..f626d4cb 100644 --- a/bin/test_types.py +++ b/bin/test_types.py @@ -11,5 +11,5 @@ class Types(unittest.TestCase): self.assertIsNotNone(floor, "README.md's Install names `Python 3.N or newer`") if shutil.which("uv") is None: self.fail("uv on PATH fetches mypy; see README.md's Test line") - ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "-m", "rank_todo", "-m", "reading_cost", "-m", "shell_reads", "-m", "statusline", "-p", "loop_claude"], capture_output=True, cwd=ROOT / "bin", text=True) + ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "-m", "rank_todo", "-p", "reading_cost", "-m", "statusline", "-p", "loop_claude"], capture_output=True, cwd=ROOT / "bin", text=True) self.assertEqual(ran.returncode, 0, ran.stdout + ran.stderr) diff --git a/docs/decisions.md b/docs/decisions.md index 934c1ece..6291d557 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -110,9 +110,9 @@ lilleman decided to ship each of these under the floor on the day listed. Each l 2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; the names of the host, its infrastructure project and the sandbox VM are none of those. Valid while the repo names them without their addresses or credentials. -## reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/comprehension-history.md` in the next chunk's PR +## reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/reading-cost.md` in the next chunk's PR -2026-10-08, lilleman. Serves goal 1.1: comprehension measured from real work, at no model cost (goal 1.4). loop-claude archives from the main checkout, outside any PR, so a tracked file it wrote there would dirty that checkout. So `bin/reading_cost.py` measures each finished chunk the history lacks from the archive, in the next chunk's worktree. A PR that never merges then loses no figure, and loop-claude needs no change. Serves goal 4 by naming only files git tracks, and token counts. Rejected: loop-claude opening a PR of its own, one more PR per chunk and a tie to the forge; the worker measuring its own transcript before merging, which misses the chunk's tail. The figure counts new input tokens, uncached and cache-written, because workers read mostly through Bash and subagents, where parsed paths alone miss what they read. Valid while loop-claude archives every finished chunk with its subagents' transcripts. +2026-10-08, lilleman. Serves goal 1.1: comprehension measured from real work, at no model cost (goal 1.4). loop-claude archives from the main checkout, outside any PR, so a tracked file it wrote there would dirty that checkout. So `bin/reading-cost` measures each finished chunk `docs/reading-cost.md` lacks from the archive, in the next chunk's worktree. The figures keep a file of their own, so `docs/comprehension-history.md` keeps one writer, the scoring run. A PR that never merges then loses no figure, and loop-claude needs no change. Serves goal 4 by naming only files git tracks, and token counts. Rejected: loop-claude opening a PR of its own, one more PR per chunk and a tie to the forge; the worker measuring its own transcript before merging, which misses the chunk's tail. The figure counts new input tokens, uncached and cache-written, because workers read mostly through Bash and subagents, where parsed paths alone miss what they read. Valid while loop-claude archives every finished chunk with its subagents' transcripts. ## reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item diff --git a/skills/larv-review/SKILL.md b/skills/larv-review/SKILL.md index e0805cc2..8ff82132 100644 --- a/skills/larv-review/SKILL.md +++ b/skills/larv-review/SKILL.md @@ -24,7 +24,7 @@ Words: `~/.claude/CLAUDE.md` → "Vocabulary". What a reviewer reports: ~/.claud Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the default branch. Commit, push with upstream set, and open a **draft** PR so CI cycles while the review runs. No remote → review locally and say so in the summary. -**Reading cost.** Run `~/.claude/bin/reading_cost.py` in the chunk's worktree and commit what it appends to `docs/comprehension-history.md`; the commit re-enters no pass. On `Rising:`, file a plan item titled `**Lower the reading cost of the files chunks read most before their first commit.**`, scored per `~/.claude/CLAUDE.md` → "Todo items" with the tool's medians and files as its detail; where the plan already holds it, refresh its detail instead. The item names the next release, or the one after when this chunk ships the next release's last item. On exit 1, repair what its message names and run it again; when the message names no repair, file it as a `question` item, or refresh the question item an earlier run filed, and go on. Leave the plan as it is on any other output. The chunk that ships that item runs the tool with `--reset` instead, so the next rise is measured on chunks that finished after it. +**Reading cost.** Run `~/.claude/bin/reading-cost` in the chunk's worktree and commit what it appends to `docs/reading-cost.md`; the commit re-enters no pass. Resolve a merge conflict in that file by putting the default branch's figures first and dropping a figure for a chunk the default branch already holds. On `Rising:`, file a plan item titled `**Lower the reading cost of the files chunks read most before their first commit.**`, scored per `~/.claude/CLAUDE.md` → "Todo items" with the tool's medians and files as its detail; where the plan already holds it, refresh its detail instead. The item names the next release, or the one after when this chunk ships the next release's last item. On exit 1, repair what its message names and run it again; when the message names no repair, file it as a `question` item, or refresh the question item an earlier run filed, and go on. Leave the plan as it is on any other output. The chunk that ships that item runs the tool with `--reset` instead, so the next rise is measured on chunks that finished after it. ## 3. Passes @@ -89,7 +89,7 @@ Then the comprehension floor, which the scoring run measures. Four simulated rea Two files of the project keep the floor's records: -- **History.** `docs/comprehension-history.md` keeps every scoring run and reading-cost figure, appended and never edited, except as the merge-conflict rule below says. A run is a `## , at ` heading naming when the seats finished and the commit they read; a table of each seat's five scores, with a last row holding the four seats' mean of each; and under each seat, labelled `, hardest first:` or, for the architect, `, would restructure first:`, its places, each as `path:line` and the unit's name. A `## Reading cost` heading opens a reading-cost figure or reset (§2). Appending a run re-enters no pass. Resolve a merge conflict in the file by putting the default branch's runs and figures first, and dropping a figure for a chunk the default branch already holds. +- **History.** `docs/comprehension-history.md` keeps every scoring run, appended and never edited. A run is a `## , at ` heading naming when the seats finished and the commit they read; a table of each seat's five scores, with a last row holding the four seats' mean of each; and under each seat, labelled `, hardest first:` or, for the architect, `, would restructure first:`, its places, each as `path:line` and the unit's name. Appending a run re-enters no pass. Resolve a merge conflict in the file by putting the default branch's runs first. - **Entry.** `docs/decisions.md` keeps one entry whose title opens `comprehension floor:`. It holds each decision to ship under the floor, with its scores. A `comprehension floor:` entry written before the history may still hold the last scoring run's five scores. While the default branch's history holds no run, the ratchet compares with those scores. The next scoring run moves them, and only them, into the history as its first run: a heading of the date or time the entry gives and whatever it names the run by, its commit included where named, and a table with the mean alone. The rest of the entry stays. @@ -105,7 +105,7 @@ Fix the places the seats name under the lowest dimension and under each dimensio Put each run's five scores in the summary, and append the run to the history on this branch. List in the entry each decision to ship under the floor, and file its places in `todo.md` per `~/.claude/CLAUDE.md` → "Todo items". A project without the entry gets it at its first scoring run, titled `comprehension floor: every dimension and the overall at 7.0 or above` and applying KISS (`~/.claude/principles/technical-principles.md`). -**Fresh.** Where the chunk ran a scoring run, the architecture pass is done only once its last scoring run measured the commit to merge. That run may predate commits that change only `docs/decisions.md`, `docs/comprehension-history.md`, `todo.md` or `CHANGELOG.md`. Any other commit after it, a prose fix included, because the seats read the docs, calls for a rescore: the scoring run again, once every other pass is done, the auto-reviewer included. A rescore reporting a 🔴 that no decision to ship answers is an architecture round. Any other rescore is not a round: append only its run to the history, in a commit titled `Rescore: …`. A `Rescore:` commit re-enters no pass: push it and wait for the forge's checks (§4 step 3), not for an auto-review. +**Fresh.** Where the chunk ran a scoring run, the architecture pass is done only once its last scoring run measured the commit to merge. That run may predate commits that change only `docs/decisions.md`, `docs/comprehension-history.md`, `docs/reading-cost.md`, `todo.md` or `CHANGELOG.md`. Any other commit after it, a prose fix included, because the seats read the docs, calls for a rescore: the scoring run again, once every other pass is done, the auto-reviewer included. A rescore reporting a 🔴 that no decision to ship answers is an architecture round. Any other rescore is not a round: append only its run to the history, in a commit titled `Rescore: …`. A `Rescore:` commit re-enters no pass: push it and wait for the forge's checks (§4 step 3), not for an auto-review. **Suspended.** A decision in the project's `docs/decisions.md`, held before the chunk began, may name plan items to ship without a scoring run. A named item counts as `todo.md` worded it before the chunk began. The decision must name the later plan item whose chunk ends the suspension with a scoring run. A chunk may ship named items only with each other. Such a chunk skips the scoring run, so neither the floor nor the ratchet can block it, and its summary cites the decision. A chunk shipping its release's last item runs the scoring run, even when every item it ships is named. diff --git a/todo.md b/todo.md index 03996a80..162efd2e 100644 --- a/todo.md +++ b/todo.md @@ -121,7 +121,7 @@ Raised by the architect on PR #225 and by the inherited architect of PR #224's s The key names the project's session, archive folder and models entry. `project_key` drops the leading `/`, so `~/code/a` and `/a` share all three, and one loop can resume or delete the other's session. -`bin/reading_cost.py` keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; `loop-claude` keys it by `--show-toplevel`, so a loop started inside a worktree archives where `reading_cost.py` never looks. Derive both keys one way. +`bin/reading-cost` keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; `loop-claude` keys it by `--show-toplevel`, so a loop started inside a worktree archives where `reading-cost` never looks. Derive both keys one way. ### 67. Point stability-reviewer at the technical principles in place of its own restatement of them. @@ -169,7 +169,7 @@ Claude Code owns that file and writes it. `trust` reads it, changes it and write ### 4. Name each chunk's archive folder by the chunk's start time, so `/` lists chunks in the order they ran. -Today the folder is the SHA-256 of the transcript's first timestamped line, which tells the human nothing; that line carries the start time. Drop the fallback to the first line, which every chunk of a project shares, and give the tests' fake transcripts ISO timestamps. `bin/reading_cost.py` takes a chunk's id from the folder's first 12 characters and skips a chunk whose id the history holds, so give it a way to match a figure written under the old name. +Today the folder is the SHA-256 of the transcript's first timestamped line, which tells the human nothing; that line carries the start time. Drop the fallback to the first line, which every chunk of a project shares, and give the tests' fake transcripts ISO timestamps. `bin/reading-cost` takes a chunk's id from the folder's first 12 characters and skips a chunk whose id `docs/reading-cost.md` holds, so give it a way to match a figure written under the old name. ### 52. Record why this checkout lives in Claude Code's own directory, or move it out and link it in.