Say in the README, CLAUDE.md and the decision log that every tool reads a project's files where its config puts them
CI / tests (pull_request) Successful in 2m21s
CI / tests (pull_request) Successful in 2m21s
This commit is contained in:
@@ -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. 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. 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.
|
||||
@@ -130,7 +130,7 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
- **paired ruling** — the seats vote whether the project reads better, the same or worse at the branch's head than at the base, the commit `larv-review ruling-base` prints; `larv-review --help` says how the votes make the ruling.
|
||||
- **pass** — one kind of review a chunk may take, run in rounds by its reviewers until clean; `larv-review` §3 lists them.
|
||||
- **place** — the smallest addressable unit, such as a function or a section heading, that a seat names with its `path:line` when it judges how hard the project is to read there.
|
||||
- **plan** — `todo.md`.
|
||||
- **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.
|
||||
- **release** — a semver version the human cuts.
|
||||
|
||||
@@ -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. 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 `~/`. Today the tools read only two settings from the config. `principles` reaches the reviewers through `larv-review reviewer-header`. `goals-and-audience` is read by loop-claude, `rank_todo.py`, `todo-item` and rule-hook, and reaches the reviewers the same way. The tools still read every other file at the place this example gives it. 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. 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"
|
||||
@@ -94,7 +94,7 @@ goals-and-audience = "checkout:README.md"
|
||||
principles = "~/.claude/principles"
|
||||
```
|
||||
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold will live in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows. A client's goals and audience may live in the config's folder, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. Until the other tools read the config, keep every other setting as in the example above.
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` of ours, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits, so three things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is due, or find a paired ruling's base. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.claude-projects/acme && cd ~/.claude-projects/acme
|
||||
@@ -144,7 +144,7 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
|
||||
- `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.
|
||||
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`; `rank_todo.py --help` states the format.
|
||||
- `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.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
|
||||
@@ -126,6 +126,19 @@ class Repo:
|
||||
|
||||
|
||||
class ChunkPreflightTool(unittest.TestCase):
|
||||
def test_reads_a_plan_outside_the_checkout_as_it_stands_and_names_where_the_config_puts_each_file(self):
|
||||
repo = Repo(self)
|
||||
folder = repo.temp / "home" / ".claude-projects" / "proj"
|
||||
config = folder / "config.toml"
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"folder:todo.md"'))
|
||||
(folder / "todo.md").write_text(SHIPPED)
|
||||
done = repo.preflight("--worktree")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
worktree = repo.temp / "proj-item-7"
|
||||
self.assertIn("item 7, L 1, E + I 2", done.stdout, "origin's todo.md still holds item 3, which the plan in the config's folder does not")
|
||||
self.assertIn(f"- The project's config puts its files at: plan {folder}/todo.md; working-rules {worktree}/AGENTS.md; decisions {worktree}/docs/decisions.md; ", done.stdout)
|
||||
self.assertIn("`rank_todo.py --check` exited 0", done.stdout)
|
||||
|
||||
def test_reads_the_fetched_default_branchs_plan_and_makes_the_items_worktree_off_it_leaving_the_checkout_as_it_was(self):
|
||||
repo = Repo(self)
|
||||
repo.push_from_elsewhere("todo.md", SHIPPED)
|
||||
|
||||
@@ -21,6 +21,7 @@ Each project principle states one rule that the decisions below apply; their ent
|
||||
- loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
|
||||
- machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
|
||||
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
|
||||
- project config: a tool that reads a file's commits says it does not support that file outside the checkout, and the work goes on
|
||||
- review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
|
||||
- review: a reviewer or comprehension seat that rules the work below standard may ask to rerun once, one rung up, in the same round; the ruling that stands is an escalation trigger for the worker unless the fix changes only prose, and never for the judge
|
||||
- review: a reviewer under `agents/` marks a 🔴 or 🟡 `[misread]` where the implementer misread code that had already shipped, each round title counts the marked findings, and `score-outcomes` lists them per chunk
|
||||
@@ -278,6 +279,17 @@ Valid while the later fixes per finished chunk, which `score-outcomes` and the r
|
||||
|
||||
2026-10-04, lilleman. Serves goal 1.4. In a restructure, each step's scoring run measures code the next step deletes. It costs a run and, below the floor, blocks the step, yet doesn't say anything about what the restructure buys. The scoring run after the last step measures that. 2026-10-08: the paired ruling replaced the scoring run in most chunks, and the suspension covers it too; the ruling after the last step compares with the commit measured before the first step. 2026-10-13, lilleman: the comprehension check doesn't block anything now, so a suspension saves only the runs. Valid while such a decision names its items and the plan item that ends it.
|
||||
|
||||
## project config: a tool that reads a file's commits says it does not support that file outside the checkout, and the work goes on
|
||||
|
||||
2026-11-13, larv-review. Serves goal 1.6: a client's plan and records live in the config's folder, and the loop still runs there. A file the config puts outside the checkout has no commit in the project's history, so a tool that needs the file's commits cannot do its job for it. Each such tool says so and never blocks the loop or a merge:
|
||||
|
||||
- `score-outcomes` and loop-claude's routing figures read what each chunk shipped from the commits of `todo.md`, and leave `docs/comprehension-history.md` and `docs/reading-cost.md` out of a chunk's work. They count a project only where the three are at those paths in the checkout (`bin/branch_chunks/read.py`, `unsupported`). `score-outcomes` exits 1 with the reason; the routing figures list the project under "Default branches unread".
|
||||
- `larv-review` cannot count the scoring runs a branch recorded, or find a paired ruling's base, in a comprehension history outside the checkout: it says so, and the merge goes on.
|
||||
- rule-hook cannot tell whether a plan outside the checkout changed, so it checks that plan's ranking on every call.
|
||||
- A file outside the checkout is read as it stands, never as the default branch held it: release standing, chunk-preflight and loop-claude's routing read such a plan or changelog from disk.
|
||||
|
||||
Messages keep each file's usual name, such as `todo.md`, as its label, since the config keeps the names. Revisit at 0.13.0, which plans the support.
|
||||
|
||||
## review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
|
||||
|
||||
2026-10-30, lilleman through todo item 258. Serves goal 1.1. fejkdata.dev's release review of 0.1.0 filed the architect's findings as items 28 to 36, in releases after 0.1.0, so the release the human was about to cut still held the drift the review had found. A release review's branch opens with an empty commit, so under `larv-review` §3 → "Findings" → "Outside the chunk" every finding lay outside its change and was filed. The review's whole point is to leave the release without the drift the release's small changes made, so the whole project is its chunk and the passes fix within their five rounds. Three kinds of finding are still filed, each under the release being reviewed, or under the earliest release `rules/todo-items.md` allows where that release's semver bump forbids it, such as a feature in a patch release: one whose fix needs a human answer, marked `question`; one whose fix adds a feature; and one whose fix the five rounds cannot finish. The release isn't ready to cut while one is open, so `CLAUDE.md` → "Working loop" calls a release finished only once its review has merged and it holds no item. Valid while a release review's rounds can fix what they find.
|
||||
|
||||
@@ -4,7 +4,7 @@ A scoring-run seat's prompt is the opening, the seat's background, the shared br
|
||||
|
||||
- `{checkout}` and `{branch}`: the worktree the seats read, and its branch.
|
||||
- `{main}`: the project's main checkout.
|
||||
- `{forbidden}`: `todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' records and past chunks' reading cost)`.
|
||||
- `{forbidden}`: the plan, the decision log, past panels' records and past chunks' reading cost, each where the project's config puts it in the checkout. Where it puts all four at their usual paths: `todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' records and past chunks' reading cost)`. A file the config puts outside the checkout is left out, since the seats' worktree doesn't hold it.
|
||||
- `{git}`: `git -C {checkout} ls-files`, and for a paired seat also `git -C {base checkout} ls-files`, each in backticks.
|
||||
- `{files}`: every tracked file in `git -C {checkout} ls-files`, except test files and those `{forbidden}` names. Give one recursive glob per top-level source directory, say which test files it leaves out, and list each file no glob matches. Example: `bin/**/*.py` except `test_*.py`, plus launchers such as `bin/loop-claude`.
|
||||
- `{preloaded}`: the files the harness pre-loads into a seat, found per `SKILL.md` → "What makes the result trustworthy".
|
||||
|
||||
Reference in New Issue
Block a user