Answer prose round 1: 0 🔴, 9 🟡 (0 misread); name the five as project records, cut what CLAUDE.md already says, and reword the comments the round named
CI / tests (pull_request) Successful in 2m27s

This commit was merged in pull request #530.
This commit is contained in:
2026-11-14 00:25:18 +01:00
parent 4fc00a0b89
commit 9508838439
11 changed files with 15 additions and 15 deletions
+1 -1
View File
@@ -2,7 +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.
- The new `project-record open <record>` prints the file in which an agent reads and edits one of a project's five records (`decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`), and `project-record save <record>` stores the edit. Every tool now reads and writes a record the same one way, so that a later release can keep a record outside files. No config needs a change.
- `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 -2
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. 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.
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. Read and edit a project 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,7 +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`.
- **project record** — one of five documents 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 -3
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. 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:
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 name the project's records: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`. 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"
@@ -159,7 +159,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `todo-item add …` files an item in a project's `todo.md`, taking `Next ID` as the item's ID, and `todo-item finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`; both rank the file. `todo-item show <ID>` prints an item's row and detail. `todo-item --help` states the flags.
- `wait-for <file> [<pattern>] [--timeout <seconds>]` waits until a file a background job writes holds a line matching the pattern, and prints it.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `mattermost_dm/`, `model_routing/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `mattermost_dm/`, `model_routing/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool.
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
@@ -174,7 +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.
- `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 backend 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.
+1 -1
View File
@@ -109,7 +109,7 @@ 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."""
# This setup's own changelog, at its fixed path in the clone: --cut releases claude-config, which no project's config names here.
# No project's config names the clone, so its changelog is read at the fixed path, on ref like the plan.
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):
+1 -1
View File
@@ -19,7 +19,7 @@ CONSEQUENCE = "the judge cannot read the records"
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.
"""The project's `AGENTS.md` and decision log, 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)
+1 -1
View File
@@ -66,7 +66,7 @@ def main(argv: list[str]) -> int:
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."""
"""The checkout that holds the history, the history's label for a message, and the history's 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)
+2 -2
View File
@@ -25,7 +25,7 @@ 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.
# Not git's verbs, such as checkout and commit: those 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"
@@ -49,7 +49,7 @@ def main(argv: list[str]) -> int:
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."""
"""What command, one of COMMANDS, prints for record. copy is where a record kept outside files gets its file."""
if command == "open":
opened = local_file(record, copy)
return opened if isinstance(opened, Failure) else str(opened)
+1 -1
View File
@@ -74,7 +74,7 @@ def update(record: RecordStore, archive: pathlib.Path, checkout: Checkout, home:
text = record.read()
if isinstance(text, Failure):
return text
# A record not yet kept opens with its title.
# An empty record starts with its title.
text = text or "# Reading cost\n"
figures = new_figures(text, archive, checkout, home)
if isinstance(figures, Failure):
+1 -1
View File
@@ -39,7 +39,7 @@ 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, each from the store 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 config names, and the decision log and the comprehension history, each from the store config names for it. 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
+1 -1
View File
@@ -7,7 +7,7 @@ paths:
# Decisions: one home, each linked to a goal or a technical principle
**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.
**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.
**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.
+1 -1
View File
@@ -164,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. 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.
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`. `store` picks it by the setting's value. `project-config` and `chunk-preflight` print each record's setting as a path, so make both print a page's setting as it is written. `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/`.