Read and write each record through the store its config names, and open one for agents with project-record
CI / tests (pull_request) Successful in 2m14s

This commit is contained in:
2026-11-13 23:54:04 +01:00
parent 854eb63407
commit 084bc74b1c
40 changed files with 624 additions and 161 deletions
+5
View File
@@ -72,12 +72,17 @@
!bin/mutate_changes/
!bin/mutate_changes/*.py
!bin/project-config
!bin/project-record
!bin/project_config/
!bin/project_config/*.py
!bin/project_record/
!bin/project_record/*.py
!bin/rank_todo.py
!bin/reading-cost
!bin/reading_cost/
!bin/reading_cost/*.py
!bin/record_store/
!bin/record_store/*.py
!bin/release_plan/
!bin/release_plan/*.py
!bin/repo_checks/
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- Every tool reads and writes a project's five records (`decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`) through one store per record, so that a later release can keep a record outside files. A markdown file is the only kind of store so far, and no config changes. Agents open a record with the new `project-record open <record>`, which prints the file to read and edit, and run `project-record save <record>` after each edit.
- `loop-inbox` is gone. loop-claude now asks its questions only on its own terminal. A line typed there answers a question, and `/talk` opens the worker's session. The Mattermost DM still tells you a loop waits. To upgrade, quit any `loop-inbox` still open and remove your `~/.local/bin/loop-inbox` link. Once every loop started before the upgrade has reloaded or ended, remove the folder `~/.local/state/loop-claude/`, which nothing reads any more.
- rule-hook refuses a Read or a Grep of `~/.claude/.env` or of the `env-file` any project's config names, and a Bash command that names either or searches a folder holding either with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so that a worker doesn't put a credential in its transcript in passing. A command that hides the path, such as behind a glob or a variable, still goes through.
- To keep Mattermost DMs, move the keys from `~/.claude/.env` into a file outside the checkout and the config's folder, such as `~/.claude-projects/<key>.env`, and name it in the project's config as `env-file`; `mattermost-dm` and loop-claude's DMs no longer read `~/.claude/.env`, and a project with no `env-file` gets none. A failure names each missing key and holds no token.
+2 -1
View File
@@ -2,7 +2,7 @@
## Working loop
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. A project may keep a record outside files, so read and edit a record in the file `~/.claude/bin/project-record open <record>` prints, and run `project-record save <record>` after each edit. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
- **Until the goals file has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. In a README both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
@@ -134,6 +134,7 @@ Claude Code reads this section by its heading when it compacts a conversation. K
- **plan** — the project's `todo.md`, at the path its config names as `plan`.
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's goals file, with code health ("Shared goal") first among the goals unless the goals file voids it.
- **project's rung** — the cheapest rung on loop-claude's routing ladder of the project's model, which is the model loop-claude's prompt names as the project's, or else your own.
- **record** — one of five things a project keeps beside its plan, each where its config names it: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`.
- **release** — a semver version the human cuts.
- **release review** — a release's last chunk: the architecture and principles passes over the whole project, before the release is ready to cut; `larv-review` §3 → "Release review".
- **reviewer** — a reporter of findings: an agent under `~/.claude/agents/`, `/security-review` or a forge's auto-reviewer.
+3 -1
View File
@@ -79,7 +79,7 @@ To get loop-claude's questions and stops as Mattermost DMs from a bot, write the
Each project the loop runs in has a folder, `~/.claude-projects/<key>/`, where `<key>` is the project's name, and a config in it, `config.toml`. The folder is a git repo of its own, so the config has a history and a client's files never enter this repo. The loop commits each change it makes to a file there, such as the plan, in that repo, titled as its commits in the checkout. A project is a whole git checkout, never a subfolder of one.
The config names the project's main checkout and the path of every file the loop keeps for it. No setting has a default: `project-config` fails and names each setting a config leaves out. A path is `checkout:<path>` inside the checkout, `folder:<path>` inside the config's folder, or one that starts with `/` or `~/`. Every tool reads and writes each file at the path its setting gives, and `chunk-preflight` and `todo-item` print those paths for the agents. Keep each file's name, such as `todo.md`: the rules for a file load by its name. A project of your own keeps every file but the principles in its checkout:
The config names the project's main checkout and the path of every file the loop keeps for it. No setting has a default: `project-config` fails and names each setting a config leaves out. A path is `checkout:<path>` inside the checkout, `folder:<path>` inside the config's folder, or one that starts with `/` or `~/`. Every tool reads and writes each file at the path its setting gives, and `chunk-preflight` and `todo-item` print those paths for the agents. Five of the settings each name a record: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`. A tool reads and writes a record only through the store its setting names, and an agent through `project-record`, so that a record can later be kept outside files; a path names a markdown file, the only kind of store so far. Keep each file's name, such as `todo.md`: the rules for a file load by its name. A project of your own keeps every file but the principles in its checkout:
```toml
checkout = "~/code/log"
@@ -145,6 +145,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
- `mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]` mutation-tests the lines a branch changes and prints each mutant its tests don't kill; `mutate-changes --help` says which tool it runs for each language.
- `project-config [<setting>]` prints the paths a project's config sets, or the one asked for, and fails naming each setting the config leaves out; Install → "Set up a project" shows a config.
- `project-record open <record>` prints the path of a file holding one of a project's records, for an agent to read and edit, and `project-record save <record>` stores the edit; for a record kept as a file, that file is the record.
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`, by default the one its config names; `rank_todo.py --help` states the format.
- `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.
- `review-replay <pass> <model>` replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, qualifies: it finds no less of the 🔴 and 🟡 findings than two replays on the project's rung find, within a margin, and misses no 🔴 that both found. `review-replay --help` states the replay. With `--omit-claude-md` it tests instead whether the pass's reviewer may start without `CLAUDE.md`: it replays each round three times as archived and once without the instruction files, and prints whether the reviewer passes: whether the last replay missed no more findings than the most an unchanged replay missed, with each count and each finding it missed. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.
@@ -173,6 +174,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `mattermost_dm/` sends the human a Mattermost DM, for `mattermost-dm` and for loop-claude through `loop_effects`.
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read, and the list prices, which `routing_figures` and `transcript_archive` read.
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `record_store/` reads and writes a project's records, each through the store the project's config names (`stores.py`). `contract.py` holds the tests every kind of store must pass, and `fakes.py` a store in memory that the tests of other tools use.
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`). `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises, and `citations.py` holds `todo.md` and `docs/decisions.md` to each other. `plan_file.py` reads, ranks, checks and writes a `todo.md`, for `larv_review`, `rank_todo.py`, `rule_hook` and `todo_item`.
- `repo_checks/` tests the repo itself.
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
+3 -1
View File
@@ -5,6 +5,7 @@ from branch_chunks.cut import BranchChunk, cut_branch, LOG, NOT_WORK, plan_revis
from failure import Failure
from git_cli.git_repo import git, Git, text_at
from project_config.main import located
from record_store.stores import store
# Where branch_chunks reads the plan and the records, by the setting that names each in a project's config.
@@ -16,7 +17,8 @@ def unsupported(checkout: str | None, home: pathlib.Path, run: Git = git) -> str
config = located(checkout, home, run)
if isinstance(config, Failure):
return None
elsewhere = [str(config.paths[setting]) for setting, path in READ_AT.items() if config.tracked(setting) != path]
held = [(str(config.paths["plan"]), config.tracked("plan")), *((record.label, record.tracked) for record in (store(config, name) for name in READ_AT if name != "plan"))]
elsewhere = [label for (label, tracked), path in zip(held, READ_AT.values()) if tracked != path]
if not elsewhere:
return None
return f"the project's config puts {', '.join(elsewhere)} elsewhere than {', '.join(READ_AT.values())} in the checkout, the only paths whose commits are read so far"
+2 -1
View File
@@ -71,6 +71,7 @@ from chunk_preflight.choices import forge_of, plan_name, planned, pulls_command,
from chunk_preflight.facts import JOINING_DETAILS, render
from project_config.main import located
from release_plan.named_code import named_paths
from record_store.stores import store
BIN = pathlib.Path(__file__).resolve().parents[1]
# Each tool run in the item's worktree, {item} standing for the item's ID.
@@ -125,7 +126,7 @@ def preflight(root: pathlib.Path, timeout: float, make: bool) -> list[str] | Fai
if isinstance(config, Failure):
return config
outside = None if config.tracked("plan") else config.paths["plan"]
held = default_plan(str(root), ref, config.place("plan"), config.place("changelog"))
held = default_plan(str(root), ref, config.place("plan"), store(config, "changelog"))
plan = planned(held.todo, held.cut, ref, outside)
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make)
# A `checkout:` path lands in the worktree the chunk works in.
+3 -1
View File
@@ -12,6 +12,7 @@ from release_plan.release_standing import chunk_item, Cut, default_plan, Next, R
from git_cli.git_repo import default_ref, git
from deploy_release.deploy import deploy
from failure import Failure
from record_store.stores import FileStore
from deploy_release import forge
from chunk_preflight.choices import forge_of
from release_plan.todo_table import items
@@ -108,7 +109,8 @@ def same_origin(clone: str, checkout: str) -> Failure | None:
def ready_release(clone: str, ref: str) -> Release | Failure:
"""The next release, as chunk-preflight works it out, where it is ready to cut: it holds no item in todo.md, its release review has landed and changes are unreleased."""
plan = default_plan(clone, ref, "todo.md", "CHANGELOG.md")
# This setup's own changelog, at its fixed path in the clone: --cut releases claude-config, which no project's config names here.
plan = default_plan(clone, ref, "todo.md", FileStore(pathlib.Path(clone, "CHANGELOG.md"), "CHANGELOG.md"))
found = items(plan.todo) if isinstance(plan.todo, str) else plan.todo
if isinstance(found, Failure):
return Failure(f"todo.md on {ref} cannot be read: {found.reason}")
+5 -3
View File
@@ -4,18 +4,20 @@ from failure import Failure
from git_cli.git_repo import file_at, full_history, git
from review_rules.comprehension_history import HistoryChange
from project_config.main import located
from record_store.stores import store
def history_changes(default: str, home: pathlib.Path) -> list[HistoryChange] | Failure:
"""Each merged change on the default branch that touched the history, newest first. A Failure where the project's config puts the history outside the checkout, where no commit holds it."""
"""Each merged change on the default branch that touched the history, newest first. A Failure where no commit holds the history, as for one the project's config puts outside the checkout."""
if partial := full_history():
return partial
config = located(None, home)
if isinstance(config, Failure):
return config
history = config.tracked("comprehension-history")
record = store(config, "comprehension-history")
history = record.tracked
if history is None:
return Failure(f"larv-review doesn't support a comprehension history outside the checkout: no commit holds {config.paths['comprehension-history']}, so it cannot tell which commit was last measured")
return Failure(f"larv-review doesn't support a comprehension history outside the checkout: no commit holds {record.label}, so it cannot tell which commit was last measured")
# history names the file from the checkout's top, and git reads a path from the directory it runs in.
root = str(config.top)
commits = git("log", "--first-parent", "--format=%H", default, "--", history, cwd=root)
+12 -18
View File
@@ -11,8 +11,8 @@ from larv_review.seats import FIRST_SEATS, scores, seats_file, SeatsFile
from larv_review.scoring import floor_step, means, under_floor
from project_config.main import located
from release_plan import plan_file
from record_store.stores import RecordStore, store
from larv_review.scoring_setup import removed_setup
from text_files.file_writes import replace_file
Say = typing.Callable[[str], None]
@@ -109,7 +109,7 @@ def read_seats(path: pathlib.Path, paired: bool, home: pathlib.Path, now: float)
return decided(text, now, paired, commit_exists, history)
def decided(text: str, now: float, paired: bool, commit_known: typing.Callable[[str], bool], history: tuple[pathlib.Path, str]) -> tuple[Heading, SeatsFile] | Failure:
def decided(text: str, now: float, paired: bool, commit_known: typing.Callable[[str], bool], history: tuple[RecordStore, str]) -> tuple[Heading, SeatsFile] | Failure:
"""The heading the seats file's entry goes under, stamped with now, and the file parsed from text. Fails when text names a commit that commit_known denies, or when the history already holds an entry on what the seats read."""
given = seats_file(text)
if isinstance(given, Failure):
@@ -120,7 +120,7 @@ def decided(text: str, now: float, paired: bool, commit_known: typing.Callable[[
if unknown := [commit for commit in (named.commit, named.against) if commit and not commit_known(commit)]:
return Failure(f"the seats file names {', '.join(unknown)}, which is no commit in this checkout")
if recorded(history[1], given.read):
return Failure(f"{history[0]} already holds an entry on {given.read}; record each ruling or run once")
return Failure(f"{history[0].label} already holds an entry on {given.read}; record each ruling or run once")
return named, given
@@ -139,16 +139,14 @@ def read_agreement(home: pathlib.Path) -> str | Failure:
return history if isinstance(history, Failure) else agreement_report(history[1])
def history_file(home: pathlib.Path) -> tuple[pathlib.Path, str] | Failure:
"""The project's comprehension history, where its config puts it, and its text, empty when the file is missing."""
def history_file(home: pathlib.Path) -> tuple[RecordStore, str] | Failure:
"""The store the project's config names for its comprehension history, and the history's text, empty where there is none yet."""
config = located(None, home)
if isinstance(config, Failure):
return config
history = config.paths["comprehension-history"]
try:
return history, history.read_text(encoding="utf-8") if history.exists() else ""
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"could not read {history}: {failure}")
history = store(config, "comprehension-history")
text = history.read()
return text if isinstance(text, Failure) else (history, text)
def append(read: str, entry: str, home: pathlib.Path) -> str | Failure:
@@ -158,11 +156,7 @@ def append(read: str, entry: str, home: pathlib.Path) -> str | Failure:
return read_history
history, text = read_history
if recorded(text, read):
return Failure(f"{history} already holds an entry on {read}; record each ruling or run once")
try:
history.parent.mkdir(parents=True, exist_ok=True)
except OSError as failure:
return Failure(f"could not create {history.parent}: {failure}")
if unwritten := replace_file(history, appended(text, entry).encode()):
return Failure(f"could not write {history}: {unwritten.reason}")
return f"Appended to {history}."
return Failure(f"{history.label} already holds an entry on {read}; record each ruling or run once")
if unwritten := history.write(appended(text, entry)):
return unwritten
return f"Appended to {history.label}."
+6 -4
View File
@@ -7,6 +7,7 @@ from failure import Failure
from git_cli.git_repo import file_at, git
from release_plan.todo_table import items, NoItemsTable
from project_config.main import located
from record_store.stores import store
def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[str], None]) -> Failure | None:
@@ -20,11 +21,12 @@ def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[st
checkout = str(config.top)
if not has_plan(config.paths["plan"]):
return None
# No commit holds a file outside the checkout. So the plan as the chunk found it cannot be read, nor the runs the branch recorded counted; the merge goes on, as `docs/decisions.md` → "project config: a tool that reads a file's commits …" says.
plan, history = config.tracked("plan"), config.tracked("comprehension-history")
# No commit holds a file outside the checkout, nor a record kept outside git. So the plan as the chunk found it cannot be read, nor the runs the branch recorded counted; the merge goes on, as `docs/decisions.md` → "project config: a tool that reads a file's commits …" says.
record = store(config, "comprehension-history")
plan, history = config.tracked("plan"), record.tracked
if plan is None or history is None:
name, setting = ("plan", "plan") if plan is None else ("comprehension history", "comprehension-history")
warn(f"larv-review doesn't support a {name} outside the checkout, so it cannot tell whether the chunk owes a scoring run: {config.paths[setting]}")
name, where = ("plan", str(config.paths["plan"])) if plan is None else ("comprehension history", record.label)
warn(f"larv-review doesn't support a {name} outside the checkout, so it cannot tell whether the chunk owes a scoring run: {where}")
return None
base = git("merge-base", default, "HEAD", cwd=checkout)
if isinstance(base, Failure):
+5 -4
View File
@@ -1,12 +1,13 @@
import pathlib
from release_plan.release_standing import Cut, default_plan, held_at, LastCut, next_release, Unknown
from release_plan.release_standing import Cut, default_plan, LastCut, next_release, Unknown
from failure import Failure
from larv_review.scoring import is_floor_item
from release_plan.todo_table import Item, items, NoItemsTable, renames
from project_config.main import located
from release_plan.goals_file import OPTED_OUT
from release_plan.release import Release, version
from record_store import stores
from larv_review.unmeasured import unmeasured_cut
@@ -69,12 +70,12 @@ def plan_reasons(ref: str, ids: list[int] | None, home: pathlib.Path) -> list[st
if isinstance(config, Failure):
return config
checkout = str(config.top)
decisions = held_at(ref, config.place("decisions"), checkout)
decisions = stores.held_at(ref, stores.store(config, "decisions"), checkout)
if isinstance(decisions, Failure):
return decisions
if OPTED_OUT.search(decisions):
return []
held = default_plan(checkout, ref, config.place("plan"), config.place("changelog"))
held = default_plan(checkout, ref, config.place("plan"), stores.store(config, "changelog"))
before = held.todo
if isinstance(before, Failure):
return before
@@ -94,7 +95,7 @@ def plan_reasons(ref: str, ids: list[int] | None, home: pathlib.Path) -> list[st
landed_release = landed_towards(planned, held.cut)
if isinstance(landed_release, Failure):
return landed_release
unmeasured = unmeasured_cut(ref, config.place("comprehension-history"), checkout)
unmeasured = unmeasured_cut(ref, stores.store(config, "comprehension-history"), checkout)
if isinstance(unmeasured, Failure):
return unmeasured
if ids is None:
+6 -2
View File
@@ -7,6 +7,7 @@ from review_rules.round_titles import cap, round_counts
from failure import Failure
from chunk_preflight.choices import forge_of
from larv_review.history_commands import history_file, places_report
from record_store.stores import local_file, store
from project_config.main import located
from review_rules.review_folder import made_review_folder
from deploy_release.forge import open_pull, runner
@@ -33,7 +34,7 @@ class Launch:
principles: pathlib.Path
goals: pathlib.Path
bare: bool
# The project's `AGENTS.md` and its decision log, where its config puts them.
# The project's `AGENTS.md`, where its config puts it, and a local file of its decision log.
rules: pathlib.Path
decisions: pathlib.Path
@@ -89,7 +90,10 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
# A typo in the config would otherwise hand every reviewer an empty folder, and the review would run with no principles.
if not principles.is_dir() or not any(principles.iterdir()):
return Failure(f"{principles} is not a folder with a file in it; {config.folder / 'config.toml'} sets it as `principles`")
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, config.paths["goals-and-audience"], starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], config.paths["decisions"])
decisions = local_file(store(config, "decisions"), folder / "decisions.md")
if isinstance(decisions, Failure):
return decisions
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, config.paths["goals-and-audience"], starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions)
if rerun and not launch.asked().exists():
return Failure(f"no report asked for a rerun of {pass_}'s round {round_}: {launch.asked()} is missing; relaunch before you commit the round's answers")
written = write_inputs(launch, base, home)
+3 -2
View File
@@ -11,6 +11,7 @@ from git_cli.git_repo import git
from project_config.main import located
from review_rules.review_folder import made_review_folder, review_folder
from project_config.settings import ProjectConfig
from record_store.stores import store
CLAUDE_MD = "CLAUDE.md"
PANEL = pathlib.Path(__file__).resolve().parents[2] / "skills" / "comprehension-panel"
@@ -79,8 +80,8 @@ def project_values(text: str, source: str) -> dict[str, str] | Failure:
def forbidden(config: ProjectConfig) -> tuple[list[str], str]:
"""The files no seat may open, as git names them, and the words that tell a seat so. A file the project's config puts outside the checkout is in neither: the scoring worktree doesn't hold it."""
held = [(path, what) for setting, what in FORBIDDEN if (path := config.tracked(setting))]
"""The files no seat may open, as git names them, and the words that tell a seat so. The plan or a record that no commit holds is in neither: the scoring worktree doesn't hold it."""
held = [(path, what) for setting, what in FORBIDDEN if (path := config.tracked(setting) if setting == "plan" else store(config, setting).tracked)]
files = [path for path, _ in held]
return files, f"{listed(files, 'or')} ({listed([what for _, what in held], 'and')})" if held else "any record of a past panel"
+4 -3
View File
@@ -24,6 +24,7 @@ from test_env import isolated_env
from release_plan.todo_table import Item, items, NoItemsTable
from release_plan.release_standing import LastCut
from larv_review.ruling_base import measured_commit
from record_store.fakes import MemoryStore
from larv_review.seats import score_line, scores, seats_file, SeatsFile
from larv_review.owed import shortfall
@@ -322,7 +323,7 @@ class Agreement(unittest.TestCase):
class Decided(unittest.TestCase):
AT = 1_700_000_000.0
HISTORY = (pathlib.Path("history.md"), "")
HISTORY = (MemoryStore(label="history.md"), "")
def test_heads_the_entry_with_the_time_it_is_given(self):
decided_on = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, self.HISTORY)
@@ -336,7 +337,7 @@ class Decided(unittest.TestCase):
def test_fails_where_the_history_already_holds_an_entry_on_the_file(self):
held = scored("2023-11-14T22:13:20Z", "PR #2", "abcdef1", "7", "7")
failed = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, (pathlib.Path("history.md"), appended("", held)))
failed = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, (MemoryStore(label="history.md"), appended("", held)))
self.assertEqual(failed, Failure("history.md already holds an entry on PR #2 at abcdef1; record each ruling or run once"))
def test_fails_on_a_seats_file_that_does_not_parse_without_asking_about_a_commit(self):
@@ -857,7 +858,7 @@ class LarvReviewTool(unittest.TestCase):
self.addCleanup(docs.chmod, 0o700)
for ran in (self.run_tool("record-ruling", votes_file), self.record_sevens()):
self.assertEqual((ran.returncode, ran.stdout), (1, ""), ran.stderr)
self.assertIn("could not write", ran.stderr)
self.assertIn("cannot write", ran.stderr)
def record_sevens(self):
"""Run record-scoring for item 1 on a scores file in which every seat scores 7 throughout."""
+3 -4
View File
@@ -3,12 +3,11 @@ import datetime
from review_rules.comprehension_history import entries
from failure import Failure
from git_cli.git_repo import git
from release_plan.release_standing import held_at
from project_config.settings import Place
from record_store.stores import held_at, RecordStore
def unmeasured_cut(default: str, history: Place, checkout: str) -> str | None | Failure:
"""Whether the default branch's newest release was cut unmeasured, as `v0.7.0, cut with no scoring run since v0.6.0`. It was where no scoring run in the default branch's history, the file at history, is newer than the second-newest v* tag. None where the branch holds fewer than two such tags, or a run since the earlier one.
def unmeasured_cut(default: str, history: RecordStore, checkout: str) -> str | None | Failure:
"""Whether the default branch's newest release was cut unmeasured, as `v0.7.0, cut with no scoring run since v0.6.0`. It was where no scoring run in the default branch's comprehension history is newer than the second-newest v* tag. None where the branch holds fewer than two such tags, or a run since the earlier one.
The reason ends once a run follows the earlier tag, so it asks only after a release was cut with none; it lets the chunk that finds the gap record the run.
+2 -1
View File
@@ -15,6 +15,7 @@ from loop_claude.cycle import prompts
from model_routing.route import Route, route_from
from model_routing.ladder import Rung
from claude_code.session import session_open, transcript_file
from record_store.stores import store
# Seconds routing waits for origin to name its default branch, asked only where the checkout records none; past them, the chunk runs on the project's rung.
ORIGIN_TIMEOUT = 60
@@ -79,7 +80,7 @@ def fetched_plan(loop: Loop) -> DefaultPlan | Failure:
if config.tracked("plan") is None:
say(UNSEEN_RELEASES, loop.effects)
ref = default_ref(loop.root, ORIGIN_TIMEOUT, run=loop.effects.git)
return ref if isinstance(ref, Failure) else default_plan(loop.root, ref, config.place("plan"), config.place("changelog"), loop.effects.git)
return ref if isinstance(ref, Failure) else default_plan(loop.root, ref, config.place("plan"), store(config, "changelog"), loop.effects.git)
def plan_item(plan: DefaultPlan | Failure, effects: Effects) -> Item | None:
+19 -11
View File
@@ -3,6 +3,7 @@ import pathlib
from failure import Failure
from project_config.main import located
from loop_claude.project.text_file import read_utf8
from record_store.stores import store
# The records the judge reads beside the premises: these project files, then the human's rules below.
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
@@ -14,22 +15,29 @@ HUMAN_RULE_DIRS = ("rules", "skills/larv-review/standards")
HUMAN_RULE_NAMES = (f"~/.claude/{HUMAN_RULES_FILE}", *(f"~/.claude/{folder}/" for folder in HUMAN_RULE_DIRS))
def read_records(root: str, home: pathlib.Path, claude_dir: pathlib.Path) -> str | Failure:
"""The project's record files, then the human's rules for every project, CLAUDE.md first, each headed by its name; a file that does not exist is left out.
CONSEQUENCE = "the judge cannot read the records"
The record files are read where the config under home of root's project puts them, and headed by their names in RECORD_FILES wherever that is."""
def read_records(root: str, home: pathlib.Path, claude_dir: pathlib.Path) -> str | Failure:
"""The project's records, then the human's rules for every project, CLAUDE.md first, each headed by its name; one that does not exist, or is empty, is left out.
`AGENTS.md` is read where the config under home of root's project puts it, and the decision log from the store that config names. Each is headed by its name in RECORD_FILES wherever it is kept."""
config = located(root, home)
if isinstance(config, Failure):
return Failure(f"{config.reason} - the judge cannot read the records.")
return Failure(f"{config.reason} - {CONSEQUENCE}.")
rules = [claude_dir / HUMAN_RULES_FILE] + [rule for folder in HUMAN_RULE_DIRS for rule in sorted((claude_dir / folder).glob("*.md"))]
sources = [(str(config.paths[setting].parent), config.paths[setting].name, name) for setting, name in zip(RECORD_SETTINGS, RECORD_FILES)]
sources += [(str(rule.parent), rule.name, f"~/.claude/{rule.relative_to(claude_dir)}") for rule in rules]
decisions = store(config, RECORD_SETTINGS[1]).read()
texts = [(RECORD_FILES[0], file_text(config.paths[RECORD_SETTINGS[0]])), (RECORD_FILES[1], Failure(f"{decisions.reason} - {CONSEQUENCE}.") if isinstance(decisions, Failure) else decisions)]
texts += [(f"~/.claude/{rule.relative_to(claude_dir)}", file_text(rule)) for rule in rules]
records = []
for folder, name, heading in sources:
if not pathlib.Path(folder, name).exists():
continue
text = read_utf8(folder, name, "the judge cannot read the records")
for heading, text in texts:
if isinstance(text, Failure):
return text
records.append(f"From {heading}:\n{text.strip()}")
if text:
records.append(f"From {heading}:\n{text.strip()}")
return "\n\n".join(records)
def file_text(path: pathlib.Path) -> str | Failure:
"""path's text, empty where no such file exists."""
return read_utf8(str(path.parent), path.name, CONSEQUENCE) if path.exists() else ""
+1 -1
View File
@@ -1468,7 +1468,7 @@ class Records(unittest.TestCase):
claude_md.mkdir(parents=True)
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"CLAUDE.md in {claude_md.parent}: Is a directory - the judge cannot read the records."))
pathlib.Path(root, "docs", "decisions.md").mkdir(parents=True)
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"decisions.md in {root}/docs: Is a directory - the judge cannot read the records."))
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"cannot read {root}/docs/decisions.md: [Errno 21] Is a directory: '{root}/docs/decisions.md' - the judge cannot read the records."))
pathlib.Path(root, "AGENTS.md").write_bytes(b"# Rules\n\xff\n")
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"AGENTS.md in {root} is not UTF-8 on line 2 - the judge cannot read the records."))
+11 -10
View File
@@ -38,6 +38,7 @@ import sys
from metric_bench.bench import bench, co_changed, medians, METRICS, RunScores, Score, tracked_places
from review_rules.comprehension_history import entries, Entry
from failure import Failure
from record_store.stores import FileStore, RecordStore, store
from git_cli.git_repo import git
from metric_bench.python_units import measured, python_units, Unit
from project_config.main import project
@@ -64,25 +65,25 @@ def main(argv: list[str]) -> int:
return 0
def read_history(given: pathlib.Path | None) -> tuple[str, pathlib.Path, str] | Failure:
"""The checkout that holds the history, the history's path and its text."""
def read_history(given: pathlib.Path | None) -> tuple[str, str, str] | Failure:
"""The checkout that holds the history, what a message calls the history and its text. The history is the file given, else the one in the store the project's config names."""
if given and not given.parent.is_dir():
return Failure(f"could not read {given}: no folder {given.parent}")
found = git("rev-parse", "--show-toplevel", cwd=str(given.parent) if given else None)
if isinstance(found, Failure):
return found
if given:
history = given
history: RecordStore = FileStore(given, None)
elif isinstance(config := project(), Failure):
return config
else:
history = config.paths["comprehension-history"]
if not given and not history.exists():
return Failure(f"no comprehension history at {history}; larv-review writes one at a project's first paired ruling or scoring run")
try:
return found.strip(), history, history.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"could not read {history}: {failure}")
history = store(config, "comprehension-history")
text = history.read()
if isinstance(text, Failure):
return text
if not text:
return Failure(f"no comprehension history at {history.label}; larv-review writes one at a project's first paired ruling or scoring run")
return found.strip(), history.label, text
def scored_runs(found: list[Entry]) -> list[Entry]:
+1 -1
View File
@@ -232,7 +232,7 @@ class BlackBox(unittest.TestCase):
def test_exits_1_naming_a_history_it_cannot_read_and_unknown_arguments(self):
top = self.project("")
self.assertIn("could not read", self.run_tool(top, str(pathlib.Path(top, "missing.md"))).stderr)
self.assertIn(f"no comprehension history at {top}/missing.md", self.run_tool(top, str(pathlib.Path(top, "missing.md"))).stderr)
pathlib.Path(top, "docs", "comprehension-history.md").unlink()
self.assertIn("no comprehension history at", self.run_tool(top).stderr)
self.assertIn("could not read", self.run_tool(top, str(pathlib.Path(top, "gone", "x.md"))).stderr)
+9
View File
@@ -0,0 +1,9 @@
#!/usr/bin/env python3
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from project_record import main
sys.exit(main.main(sys.argv[1:]))
View File
+58
View File
@@ -0,0 +1,58 @@
"""Open one of a project's records as a file to read and edit, and save the edit.
usage: project-record open <record>
project-record save <record>
Run inside a checkout, or a worktree of one. <record> is one of decisions, score-anchors,
comprehension-history, reading-cost and changelog, each kept where the project's config names it.
open prints the path of a file holding the record's text, and nothing else. Read and edit that
file. Where the record is kept as a file, the path is that file. Where it is kept elsewhere, the
path is a copy under ~/.local/state/project-record/<key>/, written afresh with the record as it
stands, so open it again before each edit. A record that doesn't exist yet has no file at the path:
create it there.
save stores the file's text in the record, and prints one line saying so. Where the record is kept
as a file there is nothing left to store, and it says that. Run it after every edit, so the same
steps work wherever a project keeps the record.
Exit 2 on bad arguments, and 1, saying why, on any other failure.
"""
import pathlib
import sys
from failure import Failure
from record_store.stores import FileStore, local_file, RECORDS, RecordStore, store, stored
from project_config.main import located
# Three readers, seated as the human and as the agents that follow the rules, picked the spelling from five candidates: git's verbs, such as checkout and commit, or pull and push, read as acting on the repo.
COMMANDS = ("open", "save")
# Where the copy of a record kept outside files goes, under the user's home, in a folder per project.
COPIES = ".local/state/project-record"
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) != 2 or argv[0] not in COMMANDS or argv[1] not in RECORDS:
print(f"usage: project-record {'|'.join(COMMANDS)} <record>, where <record> is one of {', '.join(RECORDS)}", file=sys.stderr)
return 2
home = pathlib.Path.home()
config = located(None, home)
done = config if isinstance(config, Failure) else act(argv[0], store(config, argv[1]), home / COPIES / config.key / f"{argv[1]}.md")
if isinstance(done, Failure):
print(f"project-record: {done.reason}", file=sys.stderr)
return 1
print(done)
return 0
def act(command: str, record: RecordStore, copy: pathlib.Path) -> str | Failure:
"""What command, one of COMMANDS, prints for record, whose copy goes at copy where it needs one."""
if command == "open":
opened = local_file(record, copy)
return opened if isinstance(opened, Failure) else str(opened)
if unstored := stored(record, copy):
return unstored
return f"{record.path} is the record itself, so nothing is left to store." if isinstance(record, FileStore) else f"Stored {copy} in {record.label}."
+71
View File
@@ -0,0 +1,71 @@
import os
import pathlib
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.test_project_config import configured
from failure import Failure
from project_record import main
from record_store.fakes import MemoryStore
TOOL = pathlib.Path(__file__).resolve().parents[1] / "project-record"
class Act(unittest.TestCase):
def setUp(self) -> None:
self.copy = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()), "acme", "decisions.md")
def test_open_prints_only_the_path_of_a_copy_holding_the_record(self):
self.assertEqual(main.act("open", MemoryStore("# Decisions\n"), self.copy), str(self.copy))
self.assertEqual(self.copy.read_text(), "# Decisions\n")
def test_save_stores_the_edited_copy_and_says_where(self):
record = MemoryStore("# Decisions\n", label="the wiki page Decisions")
main.act("open", record, self.copy)
self.copy.write_text("# Decisions\n\n- New\n")
self.assertEqual(main.act("save", record, self.copy), f"Stored {self.copy} in the wiki page Decisions.")
self.assertEqual(record.text, "# Decisions\n\n- New\n")
def test_a_record_that_fails_is_a_failure(self):
self.assertEqual(main.act("open", MemoryStore(fails="the wiki is down"), self.copy), Failure("the wiki is down"))
class BlackBox(unittest.TestCase):
def setUp(self) -> None:
self.top = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())).resolve()
configured(self, self.top)
def run_tool(self, *args: str) -> subprocess.CompletedProcess[str]:
return subprocess.run([sys.executable, str(TOOL), *args], capture_output=True, cwd=self.top, env=dict(os.environ), text=True)
def test_a_file_record_opens_as_its_own_file_and_save_has_nothing_to_store(self):
opened = self.run_tool("open", "decisions")
self.assertEqual((opened.returncode, opened.stdout, opened.stderr), (0, f"{self.top}/docs/decisions.md\n", ""))
saved = self.run_tool("save", "decisions")
self.assertEqual((saved.returncode, saved.stdout, saved.stderr), (0, f"{self.top}/docs/decisions.md is the record itself, so nothing is left to store.\n", ""))
self.assertFalse((pathlib.Path(os.environ["HOME"]) / ".local").exists(), "a file record gets no copy")
def test_exits_2_with_the_usage_on_an_unknown_command_or_record(self):
for args in ([], ["open"], ["open", "plan"], ["close", "decisions"], ["open", "decisions", "changelog"]):
ran = self.run_tool(*args)
self.assertEqual((ran.returncode, ran.stdout), (2, ""), args)
self.assertIn("usage: project-record open|save <record>, where <record> is one of decisions, score-anchors, comprehension-history, reading-cost, changelog", ran.stderr)
def test_exits_1_saying_why_where_no_config_names_the_checkout(self):
(pathlib.Path(os.environ["HOME"]) / ".claude-projects" / self.top.name / "config.toml").unlink()
ran = self.run_tool("open", "decisions")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn("no config names the checkout", ran.stderr)
def test_help_prints_the_usage(self):
ran = self.run_tool("--help")
self.assertEqual(ran.returncode, 0)
self.assertIn("usage: project-record open <record>", ran.stdout)
if __name__ == "__main__":
unittest.main()
+8 -20
View File
@@ -31,11 +31,11 @@ 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 record_store.stores import FileStore, RecordStore, store
from transcript_archive.read import finished_chunks, read_threads
from git_cli.git_repo import git
from project_config.main import project
from transcript_archive.location import project_archive
from text_files.file_writes import replace_file
from text_files.utc_stamp import utc
@dataclasses.dataclass(frozen=True)
@@ -61,19 +61,21 @@ def main(argv: list[str]) -> int:
config = project()
if not given and isinstance(config, Failure):
return failed(config)
record = pathlib.Path(given[0]) if given or isinstance(config, Failure) else config.paths["reading-cost"]
record: RecordStore = FileStore(pathlib.Path(given[0]), None) if given or isinstance(config, Failure) else store(config, "reading-cost")
updated = update(record, archive, checkout, str(home), utc(time.time()) if reset else None)
if isinstance(updated, Failure):
return failed(updated)
print(f"Appended {updated.appended} reading-cost figure{'' if updated.appended == 1 else 's'} from {archive}{' and a reset' if reset else ''} to {record}.")
print(f"Appended {updated.appended} reading-cost figure{'' if updated.appended == 1 else 's'} from {archive}{' and a reset' if reset else ''} to {record.label}.")
print(trend(updated.readings))
return 0
def update(record: pathlib.Path, archive: pathlib.Path, checkout: Checkout, home: str, reset_at: str | None) -> Updated | Failure:
text = read_record(record)
def update(record: RecordStore, archive: pathlib.Path, checkout: Checkout, home: str, reset_at: str | None) -> Updated | Failure:
text = record.read()
if isinstance(text, Failure):
return text
# A record not yet kept opens with its title.
text = text or "# Reading cost\n"
figures = new_figures(text, archive, checkout, home)
if isinstance(figures, Failure):
return figures
@@ -82,7 +84,7 @@ def update(record: pathlib.Path, archive: pathlib.Path, checkout: Checkout, home
readings = readings_of(text)
if isinstance(readings, Failure):
return readings
if marks and (unwritten := write_record(record, text)):
if marks and (unwritten := record.write(text)):
return unwritten
return Updated(len(figures), readings)
@@ -101,15 +103,6 @@ def new_figures(record: str, archive: pathlib.Path, checkout: Checkout, home: st
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
@@ -129,8 +122,3 @@ def located() -> Checkout | Failure:
return Checkout(top, str(pathlib.Path(common).parent), frozenset(filter(None, listed.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}")
View File
+42
View File
@@ -0,0 +1,42 @@
"""What every record backend must hold, as tests. A backend's test case inherits RecordStoreContract and unittest.TestCase, and builds its store in new_store."""
import typing
from record_store.stores import held_at, RecordStore
class RecordStoreContract:
"""Runs against the store new_store returns: one that holds no record yet."""
assertEqual: typing.Callable[..., None]
assertIsNone: typing.Callable[..., None]
assertTrue: typing.Callable[..., None]
def new_store(self) -> RecordStore:
raise NotImplementedError
def test_a_record_never_written_reads_empty(self) -> None:
self.assertEqual(self.new_store().read(), "")
def test_reads_back_what_it_wrote_to_the_character(self) -> None:
store = self.new_store()
text = "# Decisions\n\n- Å, 🔴 and a | pipe\n\n\n"
self.assertIsNone(store.write(text))
self.assertEqual(store.read(), text)
def test_a_write_replaces_the_whole_record(self) -> None:
store = self.new_store()
store.write("first\nsecond\n")
self.assertIsNone(store.write("third\n"))
self.assertEqual(store.read(), "third\n")
def test_names_itself_for_a_message(self) -> None:
self.assertTrue(self.new_store().label.strip())
def test_reads_as_it_stands_at_any_revision_where_no_commit_holds_it(self) -> None:
store = self.new_store()
store.write("as it stands\n")
if store.tracked is None:
self.assertEqual(held_at("no-such-revision", store, "/nowhere", run=refuse), "as it stands\n")
def refuse(*args: str, **options: object) -> str:
raise AssertionError(f"git {' '.join(args)} ran for a record no commit holds")
+22
View File
@@ -0,0 +1,22 @@
"""Record stores for tests, held to record_store.contract like every backend."""
import dataclasses
from failure import Failure
@dataclasses.dataclass
class MemoryStore:
"""A record held in memory, as a backend outside git holds one. Set fails to make every read and write fail with that reason."""
text: str = ""
label: str = "the record in memory"
tracked: str | None = None
fails: str | None = None
def read(self) -> str | Failure:
return Failure(self.fails) if self.fails else self.text
def write(self, text: str) -> Failure | None:
if self.fails:
return Failure(self.fails)
self.text = text
return None
+94
View File
@@ -0,0 +1,94 @@
"""The one way a tool reads or writes a project's records: through the store its config names for each.
Each record has its own setting in the config, so a project may keep one record in its wiki and another as a file. The setting's value names the backend. A path names a markdown file, the only backend so far."""
import dataclasses
import pathlib
import typing
from failure import Failure
from git_cli.git_repo import file_at, git, Git
from project_config.settings import ProjectConfig
from text_files.file_writes import replace_file
# The settings in a project's config that each name a record.
RECORDS = ("decisions", "score-anchors", "comprehension-history", "reading-cost", "changelog")
class RecordStore(typing.Protocol):
"""One record, as text. record_store.contract holds every backend to the same behaviour."""
@property
def label(self) -> str:
"""What a message calls the record, such as its path."""
@property
def tracked(self) -> str | None:
"""The record's path from the checkout's top, as git names a file in a commit; None where no commit holds a version of it, as for a file outside the checkout or a wiki page."""
def read(self) -> str | Failure:
"""The record's text as it stands, empty where it doesn't exist yet."""
def write(self, text: str) -> Failure | None:
"""Replaces the record's whole text, creating the record where it doesn't exist yet."""
@dataclasses.dataclass(frozen=True)
class FileStore:
"""A record kept as a markdown file at path."""
path: pathlib.Path
tracked: str | None
@property
def label(self) -> str:
return str(self.path)
def read(self) -> str | Failure:
try:
# Decoded from bytes, so the text keeps the line ends the file holds.
return self.path.read_bytes().decode("utf-8")
except FileNotFoundError:
return ""
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"cannot read {self.path}: {failure}")
def write(self, text: str) -> Failure | None:
try:
self.path.parent.mkdir(parents=True, exist_ok=True)
except OSError as failure:
return Failure(f"cannot write {self.path}: {failure}")
unwritten = replace_file(self.path, text.encode("utf-8"))
return Failure(f"cannot write {self.path}: {unwritten.reason}") if unwritten else None
def store(config: ProjectConfig, record: str) -> RecordStore:
"""The store config names for record, one of RECORDS."""
if record not in RECORDS:
raise ValueError(f"{record} is not a record; the records are {', '.join(RECORDS)}")
return FileStore(config.paths[record], config.tracked(record))
def held_at(revision: str, record: RecordStore, cwd: str, run: Git = git) -> str | Failure:
"""record's text at revision, read in the checkout at cwd, where its commits hold the record; else as it stands. Empty where there is no such record."""
return record.read() if record.tracked is None else file_at(revision, record.tracked, cwd, run)
def local_file(record: RecordStore, copy: pathlib.Path) -> pathlib.Path | Failure:
"""A file holding record's text, for an agent, which reads and edits files: the record's own file where a file is its backend, else copy, written with the text as it stands. Neither exists where the record doesn't yet. `stored` puts an edited copy back."""
if isinstance(record, FileStore):
return record.path
text = record.read()
if isinstance(text, Failure):
return text
if text and (unwritten := FileStore(copy, None).write(text)):
return unwritten
return copy
def stored(record: RecordStore, copy: pathlib.Path) -> Failure | None:
"""Stores in record the text of copy, the file `local_file` gave for it. Where that is the record's own file, the edit is already the record."""
if isinstance(record, FileStore):
return None
text = FileStore(copy, None).read()
if isinstance(text, Failure):
return text
return record.write(text) if text else Failure(f"{copy} is missing or empty, so nothing is stored in {record.label}; `record open` writes the file to edit")
+150
View File
@@ -0,0 +1,150 @@
import pathlib
import re
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from record_store.fakes import MemoryStore
from project_config.settings import ProjectConfig
from record_store.contract import RecordStoreContract
from record_store import stores
class MemoryStoreContract(RecordStoreContract, unittest.TestCase):
def new_store(self) -> stores.RecordStore:
return MemoryStore()
class FileStoreContract(RecordStoreContract, unittest.TestCase):
def setUp(self) -> None:
self.folder = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
def new_store(self) -> stores.RecordStore:
return stores.FileStore(self.folder / "docs" / "decisions.md", None)
class FileStoreInACheckoutContract(FileStoreContract):
def new_store(self) -> stores.RecordStore:
return stores.FileStore(self.folder / "docs" / "decisions.md", "docs/decisions.md")
class FileStore(unittest.TestCase):
def setUp(self) -> None:
self.folder = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
def test_names_its_path(self):
self.assertEqual(stores.FileStore(self.folder / "CHANGELOG.md", "CHANGELOG.md").label, str(self.folder / "CHANGELOG.md"))
def test_a_file_that_is_not_utf8_is_a_failure_naming_it(self):
path = self.folder / "decisions.md"
path.write_bytes(b"\xff\xfe")
read = stores.FileStore(path, None).read()
self.assertIsInstance(read, Failure)
self.assertIn(f"cannot read {path}: ", read.reason)
def test_a_write_that_fails_is_a_failure_naming_it(self):
(self.folder / "docs").write_text("a file where the folder goes")
path = self.folder / "docs" / "decisions.md"
written = stores.FileStore(path, None).write("text\n")
self.assertIsInstance(written, Failure)
self.assertIn(f"cannot write {path}: ", written.reason)
def test_a_write_keeps_the_text_as_given_not_the_platforms_line_ends(self):
path = self.folder / "decisions.md"
stores.FileStore(path, None).write("one\r\ntwo\n")
self.assertEqual(path.read_bytes(), b"one\r\ntwo\n")
self.assertEqual(stores.FileStore(path, None).read(), "one\r\ntwo\n")
class HeldAt(unittest.TestCase):
def setUp(self) -> None:
self.top = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
self.git("init", "-q", "-b", "main")
(self.top / "CHANGELOG.md").write_text("committed\n")
self.git("add", "-A")
self.git("-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-qm", "first")
(self.top / "CHANGELOG.md").write_text("as it stands\n")
def git(self, *args: str) -> None:
subprocess.run(["git", *args], cwd=self.top, check=True, capture_output=True)
def test_a_record_in_the_checkout_reads_as_the_revision_holds_it(self):
store = stores.FileStore(self.top / "CHANGELOG.md", "CHANGELOG.md")
self.assertEqual(stores.held_at("main", store, str(self.top)), "committed\n")
def test_a_record_the_revision_lacks_reads_empty(self):
store = stores.FileStore(self.top / "docs" / "decisions.md", "docs/decisions.md")
self.assertEqual(stores.held_at("main", store, str(self.top)), "")
def test_a_record_outside_the_checkout_reads_as_it_stands(self):
store = stores.FileStore(self.top / "CHANGELOG.md", None)
self.assertEqual(stores.held_at("main", store, str(self.top)), "as it stands\n")
class LocalFile(unittest.TestCase):
def setUp(self) -> None:
self.folder = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
def test_a_file_record_is_its_own_local_file_and_no_copy_is_made(self):
record = stores.FileStore(self.folder / "decisions.md", None)
record.write("kept\n")
self.assertEqual(stores.local_file(record, self.folder / "copies" / "decisions.md"), self.folder / "decisions.md")
self.assertIsNone(stores.stored(record, self.folder / "copies" / "decisions.md"))
self.assertEqual((record.read(), (self.folder / "copies").exists()), ("kept\n", False))
def test_a_record_outside_files_is_copied_and_an_edited_copy_is_stored_back(self):
record, copy = MemoryStore("# Decisions\n"), self.folder / "copies" / "decisions.md"
self.assertEqual(stores.local_file(record, copy), copy)
self.assertEqual(copy.read_text(), "# Decisions\n")
copy.write_text("# Decisions\n\n- One more\n")
self.assertIsNone(stores.stored(record, copy))
self.assertEqual(record.text, "# Decisions\n\n- One more\n")
def test_a_record_that_does_not_exist_yet_gets_no_copy(self):
copy = self.folder / "decisions.md"
self.assertEqual((stores.local_file(MemoryStore(), copy), copy.exists()), (copy, False))
def test_storing_a_missing_copy_fails_and_leaves_the_record(self):
record = MemoryStore("kept\n")
self.assertIn("is missing or empty", stores.stored(record, self.folder / "decisions.md").reason)
self.assertEqual(record.text, "kept\n")
def test_a_record_that_cannot_be_read_or_written_fails_with_its_reason(self):
record, copy = MemoryStore(fails="the wiki is down"), self.folder / "decisions.md"
self.assertEqual(stores.local_file(record, copy), Failure("the wiki is down"))
copy.write_text("edited\n")
self.assertEqual(stores.stored(record, copy), Failure("the wiki is down"))
class Store(unittest.TestCase):
def config(self, top: pathlib.Path, folder: pathlib.Path) -> ProjectConfig:
paths = {record: top / f"{record}.md" for record in stores.RECORDS} | {"changelog": folder / "CHANGELOG.md", "plan": top / "todo.md"}
return ProjectConfig("acme", folder, top, paths)
def test_a_record_in_the_checkout_is_tracked_by_its_path_from_the_top(self):
store = stores.store(self.config(pathlib.Path("/code/acme"), pathlib.Path("/home/me/.claude-projects/acme")), "decisions")
self.assertEqual((store.label, store.tracked), ("/code/acme/decisions.md", "decisions.md"))
def test_a_record_in_the_configs_folder_is_not_tracked(self):
store = stores.store(self.config(pathlib.Path("/code/acme"), pathlib.Path("/home/me/.claude-projects/acme")), "changelog")
self.assertEqual((store.label, store.tracked), ("/home/me/.claude-projects/acme/CHANGELOG.md", None))
def test_the_plan_is_not_a_record(self):
with self.assertRaises(ValueError):
stores.store(self.config(pathlib.Path("/code/acme"), pathlib.Path("/home/me/.claude-projects/acme")), "plan")
class OneWayIn(unittest.TestCase):
def test_no_tool_reads_a_records_place_from_the_config_itself(self):
bin_folder = pathlib.Path(__file__).resolve().parents[1]
reach = re.compile(r"""(?:paths\[|\.place\(|\.tracked\()["'](?:%s)["']""" % "|".join(stores.RECORDS))
found = [f"{path.relative_to(bin_folder)}:{number}" for path in sorted(bin_folder.rglob("*.py")) if "test_" not in path.name and path.parent.name != "record_store" for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1) if reach.search(line)]
self.assertEqual(found, [], "read and write a record through record_store.stores.store")
if __name__ == "__main__":
unittest.main()
+6 -5
View File
@@ -5,6 +5,7 @@ from failure import Failure
from project_config.settings import ProjectConfig
from release_plan.ranking import rank, Ranked
from text_files.file_writes import replace_file
from record_store.stores import store
def rank_file(todo: pathlib.Path, config: ProjectConfig) -> Ranked | Failure:
@@ -38,11 +39,11 @@ def check_failures(todo: pathlib.Path, config: ProjectConfig) -> list[str]:
def read_all(todo: pathlib.Path, config: ProjectConfig) -> tuple[str, str, str, str] | Failure:
"""todo, the plan, then the goals file, the decision log and the comprehension history that config names. The last two are empty when missing; a missing plan or goals file is a Failure."""
"""todo, the plan, then the goals file, the decision log and the comprehension history, each from the store config names. The last two are empty when missing; a missing plan or goals file is a Failure."""
plan = read(todo, "every project keeps a todo.md, and rank_todo.py --help shows one")
if isinstance(plan, Failure):
return plan
goals_text, decisions, history = read(config.paths["goals-and-audience"], "rank_todo.py weighs goals from the file the project's config names as goals-and-audience"), read(config.paths["decisions"], None), read(config.paths["comprehension-history"], None)
goals_text, decisions, history = read(config.paths["goals-and-audience"], "rank_todo.py weighs goals from the file the project's config names as goals-and-audience"), store(config, "decisions").read(), store(config, "comprehension-history").read()
if isinstance(goals_text, Failure):
return goals_text
if isinstance(decisions, Failure):
@@ -52,12 +53,12 @@ def read_all(todo: pathlib.Path, config: ProjectConfig) -> tuple[str, str, str,
return plan, goals_text, decisions, history
def read(path: pathlib.Path, missing: str | None) -> str | Failure:
"""path's text; where it is missing, a Failure saying missing, or "" where missing is None."""
def read(path: pathlib.Path, missing: str) -> str | Failure:
"""path's text; where it is missing, a Failure saying missing."""
try:
return path.read_text(encoding="utf-8")
except FileNotFoundError:
return Failure(f"{path}: not found; {missing}") if missing else ""
return Failure(f"{path}: not found; {missing}")
except OSError as failure:
return Failure(f"{path}: {failure.strerror}")
except UnicodeDecodeError:
+8 -7
View File
@@ -8,6 +8,7 @@ from failure import Failure
from release_plan.todo_table import Item, items, next_item, renames
from project_config.settings import Place
from text_files.markdown_text import sections
from record_store import stores
# The version a branch with no v* tag and no dated CHANGELOG.md heading counts as cut: below every release, 0.0.0 included, so that every release todo.md names comes after it.
BEFORE_FIRST_RELEASE = (-1, 0, 0)
@@ -94,10 +95,10 @@ class DefaultPlan:
cut: LastCut
def default_plan(root: str, ref: str, plan: Place, changelog: Place, run: Git = git) -> DefaultPlan:
"""What ref, the default branch as last fetched, holds for the pick, read in the checkout at root through run. plan and changelog are where the project's config puts todo.md and CHANGELOG.md."""
def default_plan(root: str, ref: str, plan: Place, changelog: stores.RecordStore, run: Git = git) -> DefaultPlan:
"""What ref, the default branch as last fetched, holds for the pick, read in the checkout at root through run. plan is where the project's config puts todo.md, and changelog the store it names for the changelog."""
tag = newest_tag(root, merged_into=ref, run=run)
changes = held_at(ref, changelog, root, run)
changes = stores.held_at(ref, changelog, root, run)
after = dated_cut(tag, changes)
since = tag if after is None else heading_commit(after, ref, changelog, root, run)
commits = since if isinstance(since, Failure) else commits_since(since, ref, root, run)
@@ -117,12 +118,12 @@ def held_at(revision: str, place: Place, cwd: str, run: Git = git) -> str | Fail
return Failure(f"cannot read {place}: {failure}")
def heading_commit(release: Release, ref: str, changelog: Place, cwd: str, run: Git = git) -> str | None | Failure:
"""The oldest commit on ref that added release's dated heading to CHANGELOG.md, which a branch with no tag counts the unreleased commits from; None where git finds none, as for a changelog outside the checkout."""
if isinstance(changelog, pathlib.Path):
def heading_commit(release: Release, ref: str, changelog: stores.RecordStore, cwd: str, run: Git = git) -> str | None | Failure:
"""The oldest commit on ref that added release's dated heading to the changelog, which a branch with no tag counts the unreleased commits from; None where git finds none, as for a changelog no commit holds."""
if changelog.tracked is None:
return None
# -G matches the heading line itself, so a changelog entry that quotes the heading doesn't count.
added = run("log", "--reverse", "--format=%H", "-G", dated_heading_pattern(release), ref, "--", changelog, cwd=cwd)
added = run("log", "--reverse", "--format=%H", "-G", dated_heading_pattern(release), ref, "--", changelog.tracked, cwd=cwd)
return added if isinstance(added, Failure) else next(iter(added.split()), None)
+19 -13
View File
@@ -7,6 +7,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from record_store.stores import FileStore
from test_env import isolated_env
from release_plan import release_standing
from release_plan import todo_table
@@ -17,6 +18,11 @@ HEADER = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I |
ROW = "| {id} | {release} | | | **Do {id}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
def changelog_of(repo: str) -> FileStore:
"""The changelog at its usual path in the checkout at repo."""
return FileStore(pathlib.Path(repo, "CHANGELOG.md"), "CHANGELOG.md")
def naming(named: set[tuple[int, int, int]] | Failure) -> list[str] | Failure:
"""LastCut.todos_since holding one todo.md text that files an item under each release in named."""
if isinstance(named, Failure):
@@ -157,7 +163,7 @@ class ChunkItem(unittest.TestCase):
self.assertIs(release_standing.release_reviewed("v0.1.0", "main", repo), True)
self.assertIs(release_standing.release_reviewed(None, "main", repo), True)
self.assertIsInstance(release_standing.release_reviewed("v9.9.9", "main", repo), Failure)
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut.reviewed, True)
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut.reviewed, True)
def test_counts_no_release_review_of_a_release_cut_under_a_dated_heading_on_a_branch_with_no_tag(self):
repo = tempfile.mkdtemp()
@@ -168,13 +174,13 @@ class ChunkItem(unittest.TestCase):
pathlib.Path(repo, "CHANGELOG.md").write_text("# Changelog\n\n## 0.0.1 - 2026-10-03\n")
run("add", "CHANGELOG.md")
run("commit", "-q", "-m", "Cut 0.0.1")
self.assertIs(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut.reviewed, False, "that review reviewed 0.0.1, which is cut")
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut.commits, 0, "no commit follows the one that cut 0.0.1")
self.assertEqual(release_standing.chunk_item([], release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut), release_standing.Unplanned(None))
self.assertIs(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut.reviewed, False, "that review reviewed 0.0.1, which is cut")
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut.commits, 0, "no commit follows the one that cut 0.0.1")
self.assertEqual(release_standing.chunk_item([], release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut), release_standing.Unplanned(None))
run("commit", "-q", "--allow-empty", "-m", "Ship item 2")
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut.commits, 1)
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut.commits, 1)
run("commit", "-q", "--allow-empty", "-m", "Release review of 0.1.0")
self.assertIs(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut.reviewed, True)
self.assertIs(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut.reviewed, True)
def test_counts_from_the_commit_on_the_named_branch_that_first_added_the_dated_heading_to_changelog_md(self):
repo = tempfile.mkdtemp()
@@ -193,7 +199,7 @@ class ChunkItem(unittest.TestCase):
run("commit", "-q", "--allow-empty", "-m", "Ship item 2")
run("checkout", "-q", "-b", "side")
run("commit", "-q", "--allow-empty", "-m", "Side work")
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut.commits, 2, "the commits after Cut 0.0.1 on main")
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut.commits, 2, "the commits after Cut 0.0.1 on main")
def test_takes_the_tag_over_a_dated_heading_and_counts_every_commit_without_either(self):
repo = tempfile.mkdtemp()
@@ -203,12 +209,12 @@ class ChunkItem(unittest.TestCase):
pathlib.Path(repo, "todo.md").write_text(HEADER + ROW.format(id=1, release="0.2.0"))
run("add", "todo.md")
run("commit", "-q", "-m", "Plan")
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md").cut, release_standing.LastCut(None, "", 1, [HEADER + ROW.format(id=1, release="0.2.0")], False))
self.assertEqual(release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo)).cut, release_standing.LastCut(None, "", 1, [HEADER + ROW.format(id=1, release="0.2.0")], False))
run("tag", "v0.1.0")
pathlib.Path(repo, "CHANGELOG.md").write_text("# Changelog\n\n## 0.2.0 - 2026-10-03\n")
run("add", "CHANGELOG.md")
run("commit", "-q", "-m", "Date 0.2.0")
held = release_standing.default_plan(repo, "main", "todo.md", "CHANGELOG.md")
held = release_standing.default_plan(repo, "main", "todo.md", changelog_of(repo))
self.assertEqual(held.todo, HEADER + ROW.format(id=1, release="0.2.0"))
self.assertEqual(held.cut, release_standing.LastCut("v0.1.0", "# Changelog\n\n## 0.2.0 - 2026-10-03\n", 1, [HEADER + ROW.format(id=1, release="0.2.0")], False))
self.assertEqual(release_standing.chunk_item(plan_under((0, 2, 0)), held.cut), release_standing.Next((0, 2, 0), one((0, 2, 0))))
@@ -221,16 +227,16 @@ class ChunkItem(unittest.TestCase):
pathlib.Path(repo, "todo.md").write_text(HEADER + ROW.format(id=1, release="0.9.0"))
run("add", "todo.md")
run("commit", "-q", "-m", "A todo.md the project's owners keep")
held = release_standing.default_plan(repo, "main", folder / "todo.md", folder / "CHANGELOG.md")
held = release_standing.default_plan(repo, "main", folder / "todo.md", FileStore(folder / "CHANGELOG.md", None))
self.assertEqual((held.todo, held.cut), ("", release_standing.LastCut(None, "", 1, [""], False)), "neither file exists yet")
plan = HEADER + ROW.format(id=2, release="0.2.0")
(folder / "todo.md").write_text(plan)
(folder / "CHANGELOG.md").write_text("# Changelog\n\n## 0.1.0 - 2026-10-03\n")
held = release_standing.default_plan(repo, "main", folder / "todo.md", folder / "CHANGELOG.md")
held = release_standing.default_plan(repo, "main", folder / "todo.md", FileStore(folder / "CHANGELOG.md", None))
self.assertEqual(held.todo, plan)
self.assertEqual(held.cut, release_standing.LastCut(None, "# Changelog\n\n## 0.1.0 - 2026-10-03\n", 1, [plan], False))
(folder / "todo.md").write_bytes(b"\xff")
unreadable = release_standing.default_plan(repo, "main", folder / "todo.md", "CHANGELOG.md")
unreadable = release_standing.default_plan(repo, "main", folder / "todo.md", changelog_of(repo))
assert isinstance(unreadable.todo, Failure) and isinstance(unreadable.cut.todos_since, Failure), unreadable
self.assertTrue(unreadable.todo.reason.startswith(f"cannot read {folder}/todo.md: "), unreadable.todo.reason)
self.assertEqual(unreadable.cut.todos_since, unreadable.todo)
@@ -247,7 +253,7 @@ class ChunkItem(unittest.TestCase):
run("commit", "-q", "-m", "Cut 0.1.0")
# Only this git knows where the checkout is, so a read that goes round it fails.
there = lambda *args, cwd: release_standing.git(*args, cwd=repo)
held = release_standing.default_plan("/nowhere", "main", "todo.md", "CHANGELOG.md", there)
held = release_standing.default_plan("/nowhere", "main", "todo.md", changelog_of("/nowhere"), there)
self.assertEqual(held, release_standing.DefaultPlan(plan, release_standing.LastCut(None, "# Changelog\n\n## 0.1.0 - 2026-10-03\n", 0, [plan], False)))
def test_counts_the_changes_unreleased_since_the_last_cut_by_unreleased_entries_and_else_by_commits(self):
+12 -11
View File
@@ -13,9 +13,9 @@ from git_cli.git_repo import default_ref
from loop_effects.effects import Effects
from failure import Failure
from rung_replay.search import first_reply
from record_store.stores import local_file, store
from project_config.main import located
from review_rules.reviewer_context import principles_line, reviewer_context
from project_config.settings import ProjectConfig
from review_rules.review_folder import REPORTS, review_folder
from model_routing.ladder import Rung
from claude_code.entries import structured_output
@@ -111,7 +111,7 @@ def reviewed_in(found: Round, code: Code, rung: Rung, copies: Copies, home: path
return Failure(f"the prompt names {', '.join(lost)}, which the review folder did not hold from the chunk's start until the round's")
if isinstance(cloned := clone_reviewed(found, code, copies.clone, effects), Failure):
return cloned
launched = launch(found.reviewer, rung, prompt, found.root, copies.clone, home, bare)
launched = launch(found.reviewer, rung, prompt, found.root, copies, home, bare)
if isinstance(launched, Failure):
return launched
reply = claude_reply(effects.claude, launched[0], copies.clone, launched[1], "claude")
@@ -120,8 +120,8 @@ def reviewed_in(found: Round, code: Code, rung: Rung, copies: Copies, home: path
return reply["result"] if isinstance(reply.get("result"), str) else Failure("the reviewer replied with no report")
def launch(reviewer: str, rung: Rung, prompt: str, checkout: str, clone: str, home: pathlib.Path, bare: bool) -> tuple[list[str], str] | Failure:
"""claude's arguments and prompt for reviewer on rung, in clone, a copy of the project whose checkout is checkout. Where bare, it starts without CLAUDE.md, and the prompt holds what the SubagentStart hook and the header's last line hand such a reviewer."""
def launch(reviewer: str, rung: Rung, prompt: str, checkout: str, copies: Copies, home: pathlib.Path, bare: bool) -> tuple[list[str], str] | Failure:
"""claude's arguments and prompt for reviewer on rung, in copies.clone, a copy of the project whose checkout is checkout. Where bare, it starts without CLAUDE.md, and the prompt holds what the SubagentStart hook and the header's last line hand such a reviewer."""
args = ["--agent", reviewer, *rung.flags()]
if not bare:
return args, prompt
@@ -131,16 +131,17 @@ def launch(reviewer: str, rung: Rung, prompt: str, checkout: str, clone: str, ho
config = located(checkout, home)
if isinstance(config, Failure):
return config
rules, decisions = (cloned(config, setting, clone) for setting in ("working-rules", "decisions"))
record = store(config, "decisions")
# No commit holds a decision log outside the checkout, so the reviewer reads it as it stands today.
decisions = local_file(record, pathlib.Path(copies.reports, "decisions.md")) if record.tracked is None else pathlib.Path(copies.clone, record.tracked)
if isinstance(decisions, Failure):
return decisions
tracked = config.tracked("working-rules")
# Likewise for an `AGENTS.md` outside the checkout.
rules = config.paths["working-rules"] if tracked is None else pathlib.Path(copies.clone, tracked)
return [*args, *NO_CLAUDE_MD], "\n".join([f"{context}\n\n{prompt}", *([principles] if (principles := principles_line(rules, decisions)) else [])])
def cloned(config: ProjectConfig, setting: str, clone: str) -> pathlib.Path:
"""Where the reviewer in clone reads the file the config names as setting: the clone's copy of a file in the checkout, else the file as it stands today, which has no copy at the reviewed commit."""
tracked = config.tracked(setting)
return config.paths[setting] if tracked is None else pathlib.Path(clone, tracked)
def copy_reports(found: Round, folder: pathlib.Path, reports: str) -> None:
"""Copies into reports each report written to folder after found's chunk began and before its round did."""
# The round's own report, any later one, and one from an earlier attempt at the item in the same worktree would each hand the reviewer the findings it is to find.
+6 -5
View File
@@ -122,17 +122,18 @@ class Launch(unittest.TestCase):
(self.home / ".claude").mkdir()
(self.home / ".claude" / "CLAUDE.md").write_text("## Shared goal\n\nHealth.\n\n## Prose\n\nShort.\n\n## Vocabulary\n\nWords.\n")
self.clone = self.home / "clone"
self.reports = self.home / "reports"
self.clone.mkdir()
self.checkout = self.home / "proj"
self.checkout.mkdir()
self.config = configured(self, self.checkout, home=self.home) / "config.toml"
def test_runs_the_reviewer_as_archived_with_claude_md(self):
self.assertEqual(replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), str(self.clone), self.home, False), (["--agent", "prose-reviewer", *REFERENCE.flags()], "Review it."))
self.assertEqual(replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), replay.Copies(str(self.clone), str(self.reports)), self.home, False), (["--agent", "prose-reviewer", *REFERENCE.flags()], "Review it."))
def test_drops_claude_md_and_hands_the_reviewer_what_the_hook_and_the_header_would(self):
(self.clone / "AGENTS.md").write_text("")
args, prompt = replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), str(self.clone), self.home, True)
args, prompt = replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), replay.Copies(str(self.clone), str(self.reports)), self.home, True)
self.assertEqual(args, ["--agent", "prose-reviewer", *REFERENCE.flags(), "--settings", json.dumps({"env": {"CLAUDE_CODE_DISABLE_CLAUDE_MDS": "1"}})])
self.assertEqual(prompt, f"{reviewer_context(self.home)}\n\nReview it.\nPrinciples: read {self.clone}/AGENTS.md first, for the project principles and the decision titles.")
@@ -140,16 +141,16 @@ class Launch(unittest.TestCase):
self.config.write_text(self.config.read_text().replace('"checkout:AGENTS.md"', '"folder:AGENTS.md"'))
(self.clone / "AGENTS.md").write_text("")
(self.config.parent / "AGENTS.md").write_text("")
prompt = replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), str(self.clone), self.home, True)[1]
prompt = replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), replay.Copies(str(self.clone), str(self.reports)), self.home, True)[1]
self.assertTrue(prompt.endswith(f"Principles: read {self.config.parent}/AGENTS.md first, for the project principles and the decision titles."), prompt)
def test_fails_without_a_config_for_the_checkout(self):
self.config.unlink()
self.assertIn("no config names the checkout", replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), str(self.clone), self.home, True).reason)
self.assertIn("no config names the checkout", replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), replay.Copies(str(self.clone), str(self.reports)), self.home, True).reason)
def test_fails_without_the_sections_to_hand_over(self):
(self.home / ".claude" / "CLAUDE.md").write_text("")
self.assertIsInstance(replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), str(self.clone), self.home, True), Failure)
self.assertIsInstance(replay.launch("prose-reviewer", REFERENCE, "Review it.", str(self.checkout), replay.Copies(str(self.clone), str(self.reports)), self.home, True), Failure)
class Match(unittest.TestCase):
+4 -8
View File
@@ -104,6 +104,7 @@ from release_plan.named_code import named_files
from project_config.main import project
from transcript_archive.location import project_archive
from score_outcomes.reversals import reversal_lines
from record_store.stores import store
# The scores score-outcomes takes, in order.
GIVEN = ("L", "E", "I", "S")
@@ -167,17 +168,12 @@ def failed(failure: Failure) -> int:
def read_anchors() -> Anchors | Failure:
"""The project's anchors as they stand where its config puts them, so a branch that edits them shows its edit; none where it has no such file."""
"""The project's anchors as they stand in the store its config names, so a branch that edits them shows its edit; none where it keeps none."""
config = project()
if isinstance(config, Failure):
return config
anchors = config.paths["score-anchors"]
try:
return parse_anchors(anchors.read_text(encoding="utf-8"))
except FileNotFoundError:
return []
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"cannot read {anchors}: {failure}")
text = store(config, "score-anchors").read()
return text if isinstance(text, Failure) else parse_anchors(text)
def read_reversals() -> list[str] | Failure:
+1 -1
View File
@@ -55,7 +55,7 @@ class Main(unittest.TestCase):
self.assertEqual(self.run_main("--check"), (0, ""))
self.assertEqual(pathlib.Path(temp, "todo.md").read_text(), "the project owners' own notes\n")
(folder / "decisions.md").write_bytes(b"\xff")
self.assertEqual(self.run_main(), (1, f"{folder}/decisions.md: not UTF-8\n"))
self.assertEqual(self.run_main(), (1, f"cannot read {folder}/decisions.md: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte\n"))
def test_refuses_a_file_that_is_not_the_plan_the_config_names_and_a_checkout_no_config_names(self):
with tempfile.TemporaryDirectory() as temp:
+11 -12
View File
@@ -39,6 +39,7 @@ from failure import Failure
from project_config.main import located
from release_plan import plan_file, ranking
from project_config.settings import ProjectConfig
from record_store.stores import store
# Each score flag, as --l or --L, and the column it fills.
LETTERS = ("L", "E", "I", "S")
@@ -118,14 +119,14 @@ def add(args: argparse.Namespace, config: ProjectConfig, stdin: typing.TextIO) -
def finish(args: argparse.Namespace, config: ProjectConfig) -> str | Failure:
todo, changelog = config.paths["plan"], config.paths["changelog"]
todo, changelog = config.paths["plan"], store(config, "changelog")
texts = finish_texts(args, config)
if isinstance(texts, Failure):
return Failure(f"not finished: {texts.reason}")
ranked, news = texts
if unwritten := plan_file.write(todo, ranked.text):
return Failure(f"not finished: {unwritten.reason}")
if news is not None and (unwritten := plan_file.write(changelog, news)):
if news is not None and (unwritten := changelog.write(news)):
return Failure(f"{unwritten.reason}; todo.md no longer holds item {args.id}, so add its bullet by hand")
for line in plan_file.report_lines(todo, ranked):
print(line, file=sys.stderr)
@@ -134,9 +135,12 @@ def finish(args: argparse.Namespace, config: ProjectConfig) -> str | Failure:
def finish_texts(args: argparse.Namespace, config: ProjectConfig) -> tuple[ranking.Ranked, str | None] | Failure:
"""What finish writes: the plan ranked without item args.id, and the changelog's new text, None where finish leaves it as is."""
todo, changelog = config.paths["plan"], config.paths["changelog"]
if changelog.exists() and args.changelog is None and not args.no_changelog:
return Failure(f"{changelog} exists; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything")
todo, changelog = config.paths["plan"], store(config, "changelog")
news = changelog.read()
if isinstance(news, Failure):
return news
if news and args.changelog is None and not args.no_changelog:
return Failure(f"{changelog.label} exists; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything")
texts = plan_file.read_all(todo, config)
if isinstance(texts, Failure):
return texts
@@ -148,11 +152,6 @@ def finish_texts(args: argparse.Namespace, config: ProjectConfig) -> tuple[ranki
return ranked
if args.changelog is None:
return ranked, None
try:
news = with_bullet(changelog.read_text(encoding="utf-8") if changelog.exists() else "", args.changelog)
except OSError as failure:
return Failure(f"{changelog}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{changelog}: not UTF-8")
return news if isinstance(news, Failure) else (ranked, news)
added = with_bullet(news, args.changelog)
return added if isinstance(added, Failure) else (ranked, added)
+2 -1
View File
@@ -2,11 +2,12 @@
paths:
- "**/AGENTS.md"
- "**/docs/decisions.md"
- "**/project-record/*/decisions.md"
---
# Decisions: one home, each linked to a goal or a technical principle
**The decision log has one home: `docs/decisions.md`**. A title states the whole decision in one line: what holds at the commit it ships in, in words a reader finds in the code or the plan. `AGENTS.md` lists the project principles and the title of each decision no project principle covers, so a session works by the decisions without loading their background. The entry holds the background: its date, who made it, the reasoning, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies.
**The decision log has one home: `docs/decisions.md`**, or wherever the project's config keeps the record `decisions`. Read and edit it in the file `~/.claude/bin/project-record open decisions` prints, and run `project-record save decisions` after each edit. A title states the whole decision in one line: what holds at the commit it ships in, in words a reader finds in the code or the plan. `AGENTS.md` lists the project principles and the title of each decision no project principle covers, so a session works by the decisions without loading their background. The entry holds the background: its date, who made it, the reasoning, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies.
**Every decision links to a goal or a technical principle.** An entry names the goal it serves or the technical principle it applies, from the config's principles folder; one that can do neither is a missing goal, and an entry already in the repo with neither behind it is a finding. Propose the goal, never a reason of your own — `~/.claude/CLAUDE.md` → "Working loop", "Ask, don't guess" says how. An entry working against a goal or a technical principle stands only while it names the `todo.md` item that ends it.
+4 -9
View File
@@ -12,8 +12,7 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 354 | 0.11.0 | | | **Read and write the decisions, score anchors, comprehension history, reading cost and changelog each through the backend its project's config names, with markdown files as one backend.** | 4 | 2 | 3 | 7 | 7 | 1.6 by 4, code health by 1 | 0.7 |
| 364 | 0.11.0 | 354 | | **Read a client repo's own `CLAUDE.md` and `AGENTS.md`, propose to its team each change that aligns them with this setup, and record each conflict left as a decision in the project's records.** | 2 | 2 | 2 | 4 | 2 | 1.6 by 4, 1.2 by 2 | 2.2 |
| 364 | 0.11.0 | | | **Read a client repo's own `CLAUDE.md` and `AGENTS.md`, propose to its team each change that aligns them with this setup, and record each conflict left as a decision in the project's records.** | 2 | 2 | 2 | 4 | 2 | 1.6 by 4, 1.2 by 2 | 2.2 |
| 376 | 0.11.0 | | owner | **Make `principles/technical-principles.md` ask for files in folders before comment banners, and for an entry point a newcomer finds at once.** | 1 | 2 | 2 | 3 | 2 | 1.1 by 4 | 1.6 |
| 360 | 0.11.0 | | | **Make `chunk-pr merge` wait for the human approvals a project's config requires, as part of the gate, before it merges.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 5 | 1.6 |
| 357 | 0.11.0 | | | **Write prose in the language a project's config names, and title its commits, pull requests and branches by the templates it names.** | 3 | 2 | 3 | 6 | 4 | 1.6 by 5 | 1.4 |
@@ -26,7 +25,7 @@
| 363 | 0.11.0 | 362 | | **Add a Slack backend to the notifier, sending each notice as a DM from a bot.** | 2 | 1 | 2 | 3 | 3 | 1.6 by 4 | 1.3 |
| 373 | 0.11.0 | | | **Pick the next release's chunks that may run at once by the files and the parts of files each is predicted to touch, and record the prediction beside what each merged chunk touched.** | 3 | 2 | 2 | 5 | 5 | 1.5 by 4, 1.4 by 2 | 1.3 |
| 352 | 0.11.0 | 351 | | **Write a project's plan to its Jira epic: file items as child issues, edit those the loop filed, score unscored issues with a comment, and move a finished item to the status its config names.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 6 | 1.2 |
| 355 | 0.11.0 | 349, 354 | | **Store a record on the Confluence Cloud page its config names, as markdown converted through the adf-codec shim, and interrupt the human when a teammate saved the page since the loop read it.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 6 | 1.2 |
| 355 | 0.11.0 | 349 | | **Store a record on the Confluence Cloud page its config names, as markdown converted through the adf-codec shim, and interrupt the human when a teammate saved the page since the loop read it.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 6 | 1.2 |
| 356 | 0.11.0 | | | **Hand reviewers the review standards from the folder a project's config names, in place of `~/.claude/skills/larv-review/standards/`.** | 2 | 2 | 3 | 5 | 2 | 1.6 by 3 | 1.1 |
| 372 | 0.11.0 | | | **Key loop-claude's session, archive, routing state and config-folder commits per chunk, so two chunks of one project run side by side without touching each other's state.** | 3 | 2 | 3 | 6 | 6 | 1.5 by 3 | 0.4 |
| 374 | 0.11.0 | 360, 372 | | **Merge open chunks one at a time: rebase, finish the item in todo.md and CHANGELOG.md, rerun the gate and the paired ruling, and keep a chunk waiting for approval in the queue without blocking the next.** | 4 | 2 | 3 | 7 | 6 | 1.5 by 4, 1.6 by 3 | 1.0 |
@@ -90,10 +89,6 @@
## Details
### 354. Read and write the decisions, score anchors, comprehension history, reading cost and changelog each through the backend its project's config names, with markdown files as one backend.
lilleman's call, 2026-11-12: each record has its own backend setting, so a client project can keep, say, decisions and changelog in Confluence and anchors and comprehension history as files. Which goes where is asked per client at setup. Every tool and agent that reads or writes a record goes through the interface: the judge's records, `rank_todo.py`'s decision check, `todo-item finish --changelog`, larv-review's scoring and places, `score-outcomes`, `rules/decisions.md`. The plan store's contract suite has a twin for records, on fakes. Re-scored 2026-11-13 at L 4 and S 7: about 15 modules in 10 packages and 11 agent-facing files read a record, several at a git ref, and the record interface is the first backend interface, since item 350's plan store is not built yet. R is above 5, so this item ships alone.
### 364. Read a client repo's own `CLAUDE.md` and `AGENTS.md`, propose to its team each change that aligns them with this setup, and record each conflict left as a decision in the project's records.
lilleman's call, 2026-11-12: the loop may change every file in a client repo, but in agreement with the team, so a change to their instruction files goes to them as a proposal in a pull request. Where a conflict stays, the loop records which rule it follows and why as a decision in the project's decision record, so it is never asked twice. This is a working rule in `CLAUDE.md`.
@@ -129,7 +124,7 @@ lilleman's call, 2026-11-12: a client may want docs and Jira text in another lan
### 350. Route every read and write of the plan, by tools and by agents, through one plan-store interface and `todo-item`, with the markdown file as one backend.
After item 344 every reader finds `todo.md` by its configured path, but each still parses the markdown itself, and agents still Read and grep the file. After this item agents list, show, add, edit, move and finish items only through `todo-item`, which gains list, edit and move commands. `rules/todo-items.md` loads today only when a session touches a `todo.md`, so it must load another way for a plan with no file. The interface carries what ranking needs: ID, release, blocked by, exempt, tagline, L, E, I, S, moves, detail, and an order the backend supplies (score order for markdown, Jira rank for Jira). One contract suite runs against every backend, on fakes only, per lilleman's call of 2026-11-12. R is above 5, so this item ships alone.
After item 344 every reader finds `todo.md` by its configured path, but each still parses the markdown itself, and agents still Read and grep the file. After this item agents list, show, add, edit, move and finish items only through `todo-item`, which gains list, edit and move commands. `rules/todo-items.md` loads today only when a session touches a `todo.md`, so it must load another way for a plan with no file. The interface carries what ranking needs: ID, release, blocked by, exempt, tagline, L, E, I, S, moves, detail, and an order the backend supplies (score order for markdown, Jira rank for Jira). One contract suite runs against every backend, on fakes only, per lilleman's call of 2026-11-12; `bin/record_store/contract.py` is its twin for records. R is above 5, so this item ships alone.
### 349. Convert markdown to ADF and back with `@larvit/adf-codec`'s portable calls, through a pinned Node shim run in a container with a memory limit.
@@ -169,7 +164,7 @@ lilleman's calls, 2026-11-12. Without asking, the loop may create child issues i
### 355. Store a record on the Confluence Cloud page its config names, as markdown converted through the adf-codec shim, and interrupt the human when a teammate saved the page since the loop read it.
lilleman's calls, 2026-11-12: one page per record, whose ID the config names. The loop reads the page's ADF as portable markdown and writes markdown back through adf-codec. It writes with the version number it read; where Confluence reports a newer version, the loop asks the human, and never overwrites a teammate's edit on its own. Auth: email plus API token from the project's env file.
lilleman's calls, 2026-11-12: one page per record, whose ID the config names. The loop reads the page's ADF as portable markdown and writes markdown back through adf-codec. It writes with the version number it read; where Confluence reports a newer version, the loop asks the human, and never overwrites a teammate's edit on its own. Auth: email plus API token from the project's env file. The page is one more `RecordStore` in `bin/record_store/stores.py`, held to `contract.py`, which `store` picks by the setting's value; `project-config` and `chunk-preflight` print each record's setting as a path today. `write` takes only the text, so the store itself keeps the version it read.
### 356. Hand reviewers the review standards from the folder a project's config names, in place of `~/.claude/skills/larv-review/standards/`.