Read a project's goals and audience from the file its config names, in place of README.md
CI / tests (pull_request) Successful in 2m17s
CI / tests (pull_request) Successful in 2m17s
This commit is contained in:
@@ -2,6 +2,7 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- A project reads its goals and audience from the file its config sets as `goals-and-audience`, in place of `README.md`: loop-claude's prompts and judge, `rank_todo.py`, `todo-item` and rule-hook all read that file. `larv-review reviewer-header` names it on a `Goals and audience:` line, and the reviewers read it from there. A client's project can keep the file, named `goals.md`, in its config's folder, and void code health there as a README can. A checkout no config names now gets no premises and no ranking.
|
||||
- Reviewers read the technical principles from the folder a project's config sets as `principles`, in place of `~/.claude/principles/`. `larv-review reviewer-header` names the folder on a `Technical principles:` line and fails where no config sets it, or the folder is missing or empty. Write a config for each project before its next review; a project that keeps today's principles sets `principles = "~/.claude/principles"`.
|
||||
- A project can now have a config, `~/.claude-projects/<key>/config.toml`, that names its checkout and the path of every file the loop keeps for it. `project-config` prints those paths, and fails naming each setting a config leaves out. README → Install → "Set up a project" shows how to write one. Only larv-review's `reviewer-header` reads it yet, so a project without one can't run a review; a later release will need one for every project.
|
||||
- larv-review takes an item as a floor item only where its tagline opens with `Reach the comprehension floor:`. A tagline that quotes the floor elsewhere, such as in a decision title, no longer makes its chunk due a scoring run. Reword each open floor item's tagline in every project's `todo.md` to open with the phrase.
|
||||
|
||||
@@ -4,16 +4,16 @@
|
||||
|
||||
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.
|
||||
|
||||
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. 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.
|
||||
- **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.
|
||||
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
|
||||
- **When the next release has no items left and work has landed towards it, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged and the release holds no item, the release is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix, or an item its release review filed, lands, into that release; never start a later release's items or plan a new one.
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
|
||||
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the goals file's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; open `todo.md` only for what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs.
|
||||
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in `todo.md`, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's `## Audience`, picks it.
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Remove a finished item's row and detail from `todo.md`, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the row and detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item.
|
||||
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
|
||||
@@ -22,7 +22,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
|
||||
## Shared goal
|
||||
|
||||
Every project pursues the achieve goal below, ranked above every achieve goal its README states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
|
||||
Every project pursues the achieve goal below, ranked above every achieve goal its goals file states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
|
||||
|
||||
**Achieve:** Code health: the code stays easy to read, change safely and debug, tomorrow and after seven years of development.
|
||||
- Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
|
||||
@@ -55,7 +55,7 @@ Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-re
|
||||
Claude Code loads a rule file when a session writes a file its `paths:` frontmatter matches, or reads one with the Read tool or `head -n`, never `sed`. After a write, it loads only once the write is done. Read a rule file before you create a file it covers.
|
||||
|
||||
- The decision log: `~/.claude/rules/decisions.md`.
|
||||
- README goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- Goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- `todo.md` items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`.
|
||||
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, live in `~/.claude/skills/larv-review/standards/`.
|
||||
@@ -121,16 +121,17 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
## Vocabulary
|
||||
|
||||
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from `README.md` or the judge's records.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from the premises or the judge's records.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`, which `~/.claude/bin/project-config goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder.
|
||||
- **gate** — the merge gate: the checks a PR passes before it merges.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal and in `loop-inbox`, for a decision that is theirs. They type a one-line answer in either, or `/talk` to open the worker's session with `claude --resume` where they typed it. A release ready to cut opens that session at once, on loop-claude's terminal. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **judge's records** — the files the judge reads beside the README's premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/` and `~/.claude/skills/larv-review/standards/`.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/` and `~/.claude/skills/larv-review/standards/`.
|
||||
- **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`.
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's `README.md`, with code health ("Shared goal") first among the goals unless the README voids it.
|
||||
- **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.
|
||||
- **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".
|
||||
|
||||
@@ -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 only `project-config` and `larv-review reviewer-header`, which reads `principles`, read the config: every other tool still reads each 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 `~/`. 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. Every other tool still reads each file at the place this example gives it. 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. Until the other tools read the config, write the client's config like 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 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.
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.claude-projects/acme && cd ~/.claude-projects/acme
|
||||
|
||||
@@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Write
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
You check every yardstick you are handed against the whole project, which you read once for all of them. A yardstick is either the project's goals, every goal under its `README.md` → `## Goals` with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless the README voids it, or one principles file, every principle in it.
|
||||
You check every yardstick you are handed against the whole project, which you read once for all of them. A yardstick is either the project's goals, every goal under `## Goals` in the file your prompt's `Goals and audience:` line names, with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, or one principles file, every principle in it.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and `todo.md` first, then all of the project's code, config, tests and CI.
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Before anything else, **read the technical principles** in the folder your promp
|
||||
|
||||
1. **Identify the change surface**: Read the recent changes and pinpoint what external behavior is affected. If the change is purely internal with no external impact, say so plainly and stop — don't manufacture concerns.
|
||||
|
||||
2. **Identify the personas**: Who uses this? Check the README and any docs for documented personas. If personas are missing or unclear for the affected surface, review against your best-guess personas (e.g., "end customer", "tenant admin", "integrator/developer", "internal support", "CLI power user"), labelled as assumptions, and raise the persona question as a ❓.
|
||||
2. **Identify the personas**: Who uses this? Check the `## Audience` in the file your prompt's `Goals and audience:` line names, the README and any docs for documented personas. If personas are missing or unclear for the affected surface, review against your best-guess personas (e.g., "end customer", "tenant admin", "integrator/developer", "internal support", "CLI power user"), labelled as assumptions, and raise the persona question as a ❓.
|
||||
|
||||
3. **Walk the happy path** for each persona. Is it obvious? Does the naming match mental models? Is the minimum required input actually minimum?
|
||||
|
||||
@@ -47,7 +47,7 @@ Before anything else, **read the technical principles** in the folder your promp
|
||||
|
||||
## Your Output Format
|
||||
|
||||
Report only a defect a persona hits, a requirement of the plan, the README's goals or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless the README voids it) that the change breaks, or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
Report only a defect a persona hits, a requirement of the plan, the project's goals, in the file your prompt's `Goals and audience:` line names, or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it) that the change breaks, or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict:
|
||||
|
||||
|
||||
@@ -130,7 +130,7 @@ Every PR gets at least this sweep.
|
||||
|
||||
## Output Format
|
||||
|
||||
Report only a defect, a requirement of the plan, the README's goals or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless the README voids it) that the change breaks, a breach of a technical principle, and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
Report only a defect, a requirement of the plan, the project's goals, in the file your prompt's `Goals and audience:` line names, or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it) that the change breaks, a breach of a technical principle, and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis, mutation — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then the findings, most severe first, each with:
|
||||
- **Location**: File and line/function
|
||||
|
||||
@@ -52,11 +52,11 @@ You work in distinct stages. Never skip stages. Never collapse them. Goals, audi
|
||||
### Stage 0: Establish goals, audience, scale & domain language (do this first)
|
||||
You cannot judge whether an implementation is the best one without a yardstick. The yardstick is five artifacts: **the audience** (who this is for — concrete roles, not "users"), **the problem statement** (what hurts without this), **the goals and their priority order** (including which failure classes are intolerable — the correctness targets the test machinery is priced against), **the scale & horizon** (expected load and data volume in orders of magnitude, team and consumer count, and the intended lifetime — throwaway experiment / MVP / production / long-lived platform — with a promotion event, the one that graduates it and forces re-review), and **the domain glossary** — the ubiquitous language: each core domain concept, one name, one line of meaning. Every name in the design must come from it.
|
||||
|
||||
- **Gather** them — read the README, CLAUDE.md, AGENTS.md, the technical principles (constraints every design must satisfy), the relevant ticket, and any design docs. What isn't written down is a question for the user.
|
||||
- **Gather** them — read the README, the goals and audience in the file your prompt's `Goals and audience:` line names, else in the README, CLAUDE.md, AGENTS.md, the technical principles (constraints every design must satisfy), the relevant ticket, and any design docs. What isn't written down is a question for the user.
|
||||
- **Test** them: Is the audience concrete? Does the problem statement name the pain, not the solution? Are the goals explicit, prioritized so you know which wins when two collide, and mutually consistent? Is the horizon stated — spike or platform? Nothing is fit for a purpose whose size and lifespan are unknown. Does the glossary give each concept exactly one name?
|
||||
- **Fix first if broken.** Unless the purpose and goals are stated and consistent, surfacing the gap IS this run's deliverable: you execute one-shot and cannot pause for answers, so return a short draft of the missing artifacts plus the questions the user must answer, and stop there — design or review continues in a later invocation, once the agreed result is recorded. A missing audience, problem statement, scale & horizon, or glossary is the same fix-first gap. Never design against guessed goals, a guessed audience, or invented vocabulary — surface the ambiguity instead.
|
||||
|
||||
Output: agreed audience, problem statement, ordered goals, scale & horizon, and domain glossary. Only once these are recorded in the README do you proceed to Stage 1. The requirement never scales down; the artifacts do — a weekend spike answers all five at spike depth: five lines in a README, not five documents. Refuse to proceed without answers; never demand more depth than the recorded horizon justifies.
|
||||
Output: agreed audience, problem statement, ordered goals, scale & horizon, and domain glossary. Only once these are recorded, the audience and goals where you read them and the rest in the README, do you proceed to Stage 1. The requirement never scales down; the artifacts do — a weekend spike answers all five at spike depth: five lines in a README, not five documents. Refuse to proceed without answers; never demand more depth than the recorded horizon justifies.
|
||||
|
||||
### Stage 1: Describe
|
||||
Produce an architectural description covering:
|
||||
|
||||
@@ -15,6 +15,7 @@ from test_env import isolated_env
|
||||
from release_plan.release_standing import LastCut
|
||||
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
|
||||
from chunk_preflight.facts import open_pulls, render
|
||||
from project_config.test_project_config import write_config
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
README = "# Project\n\n## Goals\n\n**Void:** code health, since the plan's scores weigh goal 1 alone.\n\n1. **Achieve:** Work.\n\n## Audience\n\nMe.\n"
|
||||
@@ -83,6 +84,7 @@ class Repo:
|
||||
self.env = {**isolated_env(), "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_NOSYSTEM": "1", "HOME": str(self.temp / "home"), "PATH": str(self.fake), "LOOP_CLAUDE_TRANSCRIPTS": str(self.temp / "archive")}
|
||||
self.git(self.temp, "init", "--quiet", "--bare", "--initial-branch=main", str(self.origin))
|
||||
self.git(self.temp, "clone", "--quiet", str(self.origin), str(self.root))
|
||||
write_config(self.temp / "home", self.root)
|
||||
self.write(self.root, "README.md", README)
|
||||
self.write(self.root, "src/app.py", "def run():\n\treturn 1\n\n")
|
||||
self.commit(self.root, "start")
|
||||
|
||||
@@ -11,6 +11,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from transcript_archive.outcomes import ANSWERED, FINISHED, INTERRUPTED, UNFINISHED
|
||||
from judge_replay.replay import Case, case_from, report, reproduced, sample, verdict_kind
|
||||
from project_config.test_project_config import configured
|
||||
from loop_effects.effects import Effects
|
||||
from failure import Failure
|
||||
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
|
||||
@@ -109,6 +110,7 @@ class Main(unittest.TestCase):
|
||||
for key, verdicts in (("proj", (FINISHED, INTERRUPTED)), ("other", (FINISHED,))):
|
||||
(self.home / "code" / key).mkdir(parents=True)
|
||||
(self.home / "code" / key / "README.md").write_text("# p\n\n## Goals\n\n1. Ship.\n\n## Audience\n\nMe.\n")
|
||||
configured(self, self.home / "code" / key, home=self.home)
|
||||
chunk = self.home / ".claude" / "loop-claude-transcripts" / key / "c1"
|
||||
chunk.mkdir(parents=True)
|
||||
for n, verdict in enumerate(verdicts):
|
||||
@@ -155,7 +157,7 @@ class Main(unittest.TestCase):
|
||||
with self.subTest(said=said):
|
||||
self.assertIn(said, self.prompts[0])
|
||||
# The premises head the prompt and the records follow them.
|
||||
self.assertRegex(self.prompts[0], r"(?s)From README\.md:.*1\. Ship\..*The records:.*Be kind\.")
|
||||
self.assertRegex(self.prompts[0], r"(?s)From the goals file:.*1\. Ship\..*The records:.*Be kind\.")
|
||||
# The replay shows the judge the whole transcript, with no step-up marked in it.
|
||||
self.assertNotIn("[step]", self.prompts[0])
|
||||
|
||||
|
||||
@@ -31,6 +31,7 @@ class Launch:
|
||||
folder: pathlib.Path
|
||||
diff: pathlib.Path
|
||||
principles: pathlib.Path
|
||||
goals: pathlib.Path
|
||||
bare: bool
|
||||
|
||||
def asked(self) -> pathlib.Path:
|
||||
@@ -48,6 +49,7 @@ class Launch:
|
||||
f"Report: write it to {report}.",
|
||||
f"Diff: {self.diff}",
|
||||
f"Technical principles: {self.principles}",
|
||||
f"Goals and audience: {self.goals}",
|
||||
*([f"Places: {self.folder / 'places.md'}"] if self.pass_ in TAKE_PLACES else []),
|
||||
*([principles] if self.bare and (principles := principles_line(self.worktree)) else []),
|
||||
])
|
||||
@@ -84,7 +86,7 @@ def reviewer_header(default: str, pass_: str, rerun: bool) -> Failure | None:
|
||||
# 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, starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), pathlib.Path.home()))
|
||||
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_), ""), pathlib.Path.home()))
|
||||
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)
|
||||
|
||||
@@ -852,7 +852,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.plan(readme="# P\n\n## Goals\n\n**Void:** code health, since it is a probe.\n\n1. **Achieve:** A.\n")
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: item 1 names code health, which README.md voids", ran.stderr)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: item 1 names code health, which the goals file voids", ran.stderr)
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
@@ -997,6 +997,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
f"Report: write it to {folder}/stability-round-1.md.\n"
|
||||
f"Diff: {folder}/branch-{short}.diff\n"
|
||||
f"Technical principles: {self.checkout.parent}/principles\n"
|
||||
f"Goals and audience: {self.checkout}/README.md\n"
|
||||
f"Places: {folder}/places.md\n"
|
||||
)), ran.stderr)
|
||||
self.assertEqual((folder / f"branch-{short}.diff").read_text(), self.git("diff", base, "HEAD"))
|
||||
@@ -1080,6 +1081,10 @@ class LarvReviewTool(unittest.TestCase):
|
||||
def test_reviewer_header_names_the_principles_folder_the_projects_config_sets(self):
|
||||
self.assertEqual(self.header_line("Technical principles:", "prose"), f"Technical principles: {self.checkout.parent}/principles")
|
||||
|
||||
def test_reviewer_header_names_the_goals_file_the_projects_config_sets(self):
|
||||
self.config.write_text(PROJECT_CONFIG.replace('"checkout:README.md"', '"folder:goals.md"'))
|
||||
self.assertEqual(self.header_line("Goals and audience:", "principles"), f"Goals and audience: {self.config.parent}/goals.md")
|
||||
|
||||
def test_reviewer_header_fails_with_the_configs_message_where_it_sets_no_principles_folder(self):
|
||||
self.config.write_text(PROJECT_CONFIG.replace('principles = "~/principles"\n', ""))
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
|
||||
@@ -21,10 +21,10 @@ JUDGE_PROMPT_CHARS = 400000
|
||||
INTERRUPT_RULES = (
|
||||
"""Decide whether the human must now be interrupted. ~/.claude/CLAUDE.md → "Working loop", "Ask, don't guess" says """
|
||||
"which choices are reserved for the human. interrupt=true when any of these appear:\n"
|
||||
"- the worker asks the human about a reserved choice, or makes one itself, and neither README.md nor the "
|
||||
"- the worker asks the human about a reserved choice, or makes one itself, and neither the premises nor the "
|
||||
"records settle it; a choice the worker names a rule as asking the human's approval for counts as reserved, "
|
||||
"since some such rules, such as larv-review's, lie outside the records\n"
|
||||
"- it asks the human anything else without recommending an answer, and neither README.md "
|
||||
"- it asks the human anything else without recommending an answer, and neither the premises "
|
||||
"nor the records settle the matter\n"
|
||||
"- it asks again a question a [loop] line already answered\n"
|
||||
"- it is blocked on something only the human can supply: a credential, a version bump, a choice "
|
||||
@@ -46,7 +46,7 @@ INTERRUPT_RULES = (
|
||||
"wording; never construct another from facts it stated, except to end it with what an earlier answer left open."
|
||||
)
|
||||
QUOTE_RULES = (
|
||||
"Where README.md or the records answer the worker's own question and no [loop] line has "
|
||||
"Where the premises or the records answer the worker's own question and no [loop] line has "
|
||||
"quoted that answer yet, set interrupt=false and quote the passage that answers it; the worker is "
|
||||
"then given that passage in place of the human's reply. An interrupt outranks a quoted answer, and either "
|
||||
"outranks finished."
|
||||
@@ -55,7 +55,7 @@ FINISHED_RULES = (
|
||||
"The chunk is the piece of work the worker is on, shipped as one pull request.\n\n"
|
||||
"finished=true when the chunk is complete: merged, or nothing remains that the worker could do on "
|
||||
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}.\n\n"
|
||||
"An answer counts as recorded where README.md or the records above already hold it, the human's rules "
|
||||
"An answer counts as recorded where the premises or the records above already hold it, the human's rules "
|
||||
"(~/.claude/CLAUDE.md, ~/.claude/rules/, ~/.claude/skills/larv-review/standards/) included. "
|
||||
f"It also counts where the transcript shows the worker writing it into {ANSWER_DESTINATIONS}, "
|
||||
"but not into one of the human's rules.\n\n"
|
||||
@@ -67,7 +67,7 @@ JUDGE_RULES = "\n\n".join((INTERRUPT_RULES, QUOTE_RULES, FINISHED_RULES))
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Reply:
|
||||
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of README.md or the records that answers the worker's question, quoted verbatim, without elisions. Empty otherwise."})
|
||||
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of the premises or the records that answers the worker's question, quoted verbatim, without elisions. Empty otherwise."})
|
||||
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: loop_claude/escalation_mark.py.
|
||||
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends asking loop-claude for a higher rung, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. " + escalation_mark.QUOTE_AFTER_STEP + " Never a later mention of the trigger, and never the request itself."})
|
||||
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one transcript passage the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the worker's question; else what shows the chunk finished or the work remaining."})
|
||||
@@ -104,7 +104,7 @@ class Grounds(typing.NamedTuple):
|
||||
shown: str
|
||||
# The worker's own lines after the escalation mark, as escalation_mark.after_mark renders them, including those the tail in shown cuts off.
|
||||
after_mark: str
|
||||
# README.md's premises and the records.
|
||||
# The premises and the records.
|
||||
quotable: str
|
||||
# Each answer the human typed, whole, latest last (transcript.human_answers).
|
||||
typed: tuple[str, ...] = ()
|
||||
@@ -243,7 +243,7 @@ def re_ask_checked(verdict: Verdict, shown: str) -> Verdict:
|
||||
|
||||
|
||||
def answer_checked(verdict: Verdict, quotable: str) -> Verdict:
|
||||
"""The verdict; where it is a quoted answer that README.md and the records don't hold, an Interrupt on the same question instead."""
|
||||
"""The verdict; where it is a quoted answer that the premises and the records don't hold, an Interrupt on the same question instead."""
|
||||
if isinstance(verdict, QuotedAnswer) and not verbatim(verdict.answer, quotable):
|
||||
return Interrupt(verdict.evidence, verdict.question, escalation=verdict.escalation)
|
||||
return verdict
|
||||
@@ -252,7 +252,7 @@ def answer_checked(verdict: Verdict, quotable: str) -> Verdict:
|
||||
def judge_prompt(brief: Brief) -> tuple[str, Grounds]:
|
||||
"""The prompt, and what the judge's quotes are checked against."""
|
||||
head = (
|
||||
f"From README.md:\n{brief.premises}\n\n"
|
||||
f"From the goals file:\n{brief.premises}\n\n"
|
||||
f"The records: the project's working rules and decisions, then the human's rules for every project:\n{brief.records or 'none'}\n\n"
|
||||
f"The task the worker was given:\n{brief.task}\n\n"
|
||||
"What the worker did and said, what the human typed on [human] lines and what loop-claude told it on [loop] lines, latest last:\n"
|
||||
|
||||
@@ -9,10 +9,10 @@ from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
|
||||
from records.markdown_text import listed, quoted
|
||||
from claude_code.transcript import Typed
|
||||
|
||||
# Where the judge may quote an answer from, named as the human and the worker see them; of README.md the judge sees only the premises.
|
||||
QUOTE_SOURCES = listed(("README.md's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or")
|
||||
# Where the judge may quote an answer from, named as the human and the worker see them; of the goals file the judge sees only the premises.
|
||||
QUOTE_SOURCES = listed(("the goals file's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or")
|
||||
# Where the worker may write an answer the human typed, so it counts as recorded.
|
||||
ANSWER_DESTINATIONS = "README.md's Goals or Audience, " + ", ".join(RECORD_FILES) + ", todo.md or a comment"
|
||||
ANSWER_DESTINATIONS = "the goals file's Goals or Audience, " + ", ".join(RECORD_FILES) + ", todo.md or a comment"
|
||||
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {ANSWER_DESTINATIONS} at the one place it governs"
|
||||
# How review_launches names the reviews: "each reviewer" covers every pass with an agent.
|
||||
EACH_REVIEWER = "each reviewer"
|
||||
@@ -26,14 +26,14 @@ READING_RULE = "Read in small pieces: never read more than 80 lines of a file at
|
||||
NAME_THE_ITEMS = f"Name every todo.md item this chunk takes on one line, as in `{CHUNK_ITEMS} 297 (L 3, E + I 5), 298 (L 3, E + I 7)`, and write the whole line again whenever the set changes."
|
||||
|
||||
|
||||
AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it'
|
||||
AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless the goals file voids it'
|
||||
|
||||
|
||||
def fresh(task: str, premises: str, route: Route, project: Rung | None, facts: str) -> str:
|
||||
"""A chunk's first prompt; facts is preflight_facts' or preflight_failed's text."""
|
||||
routed = f"{routed_by(route, project)} {recount(route)}" if route.item else " ".join(rung_sentences(route, project))
|
||||
opening = f"{routed}\n\n" if routed else ""
|
||||
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one. {READING_RULE} {NAME_THE_ITEMS}\n\n{opening}{facts}\n\nThe chunk's todo.md items, or else the task above, set its scope. The goals below, {AFTER_CODE_HEALTH}, choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n{premises}"
|
||||
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one. {READING_RULE} {NAME_THE_ITEMS}\n\n{opening}{facts}\n\nThe chunk's todo.md items, or else the task above, set its scope. The goals below, {AFTER_CODE_HEALTH}, choose between ways to deliver that scope, and never widen it.\n\nFrom the goals file:\n{premises}"
|
||||
|
||||
|
||||
def routed_by(route: Route, project: Rung | None) -> str:
|
||||
|
||||
@@ -185,7 +185,7 @@ def annotation_of(cycle: Cycle, transcript_path: str, entries: list[Entry], judg
|
||||
|
||||
|
||||
def ruling_outcome(cycle: Cycle, ruling: Interrupt | QuotedAnswer, quoted_answers: int, annotation: outcomes.Annotation) -> str:
|
||||
"""The archive's outcome for a ruling: interrupted where it goes to the human, with the question put to them, and else answered from README.md or the records."""
|
||||
"""The archive's outcome for a ruling: interrupted where it goes to the human, with the question put to them, and else answered from the premises or the records."""
|
||||
if isinstance(ruling, QuotedAnswer) and not to_the_human(ruling, quoted_answers):
|
||||
return outcomes.answered(question=ruling.question, sources=prompts.QUOTE_SOURCES, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(judge_of(cycle)), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation)
|
||||
return outcomes.interrupted(question_for(ruling), ruling.evidence, str(judge_of(cycle)), ruling.escalation, cycle.route.worker_line(), ruling.judged.cost, annotation)
|
||||
|
||||
@@ -3,7 +3,7 @@ import dataclasses
|
||||
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
|
||||
from model_routing.route import Route
|
||||
|
||||
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from README.md or the records.
|
||||
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from the premises or the records.
|
||||
QUOTED_ANSWERS_PER_CYCLE = 3
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ class TypedAnswer:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Working:
|
||||
"""The worker runs, resumed with an answer quoted from README.md or the records, or typed by the human, when there is one."""
|
||||
"""The worker runs, resumed with an answer quoted from the premises or the records, or typed by the human, when there is one."""
|
||||
answered: QuotedAnswer | TypedAnswer | None = None
|
||||
quoted_answers: int = 0
|
||||
# Whether the ruling that brought the answer stepped the worker up a rung, so the worker is told of it.
|
||||
@@ -25,7 +25,7 @@ class Working:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Judging:
|
||||
"""The judge rules; quoted_answers counts the questions README.md or the records answered this cycle, and an interrupt does not reset it."""
|
||||
"""The judge rules; quoted_answers counts the questions the premises or the records answered this cycle, and an interrupt does not reset it."""
|
||||
transcript_path: str
|
||||
quoted_answers: int = 0
|
||||
|
||||
|
||||
@@ -2,26 +2,27 @@ HELP = """Run a task as headless claude cycles; a judge interrupts only when a d
|
||||
|
||||
usage: loop-claude <task>
|
||||
|
||||
Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
|
||||
premises; the task runs at the checkout root. Each cycle a worker runs the task. A chunk's first
|
||||
worker prompt also quotes the premises. They, with code health (~/.claude/CLAUDE.md → "Shared goal")
|
||||
ranked first unless README.md voids it, choose between ways to deliver the chunk's todo.md items, or
|
||||
else the task, and never widen them. A judge then reads the transcript's end, the premises, and the
|
||||
records: the project's AGENTS.md and docs/decisions.md, and the human's ~/.claude/CLAUDE.md,
|
||||
~/.claude/rules/*.md and ~/.claude/skills/larv-review/standards/*.md, where they exist. It rules
|
||||
whether the chunk, the work of one PR, is finished. A chunk stays unfinished until each answer the
|
||||
human typed in it that a later chunk could need is recorded: the premises or the records hold it, or
|
||||
the transcript shows the worker writing it into the premises, AGENTS.md, docs/decisions.md, todo.md
|
||||
or a code comment. A choice the worker made that the premises or the records settle is not asked
|
||||
about. When the worker asks a question they answer, the judge quotes the answer, loop-claude prints
|
||||
it, and the worker resumes with it. A quote they do not hold word for word is dropped, and the
|
||||
question goes to the human. So does a question asked again after its answer. A question the
|
||||
human answered earlier in the chunk goes back to the worker with that answer, unless the question
|
||||
quotes the words of the answer that leave it open. The fourth question
|
||||
they answer in one cycle goes to the human too, with the quote. An unfinished chunk resumes its
|
||||
session next cycle, and the worker is shown the passage the judge quoted as the work remaining. The
|
||||
next chunk starts a fresh session. Cycles continue until an exit below or Ctrl-C. Words:
|
||||
~/.claude/CLAUDE.md → "Vocabulary".
|
||||
Run it anywhere inside a project checkout whose goals file has ## Goals and ## Audience, the
|
||||
premises: the file its config, ~/.claude-projects/<key>/config.toml, sets as goals-and-audience,
|
||||
which `project-config goals-and-audience` prints. The task runs at the checkout root. Each cycle a
|
||||
worker runs the task. A chunk's first worker prompt also quotes the premises. They, with code health
|
||||
(~/.claude/CLAUDE.md → "Shared goal") ranked first unless the goals file voids it, choose between
|
||||
ways to deliver the chunk's todo.md items, or else the task, and never widen them. A judge then
|
||||
reads the transcript's end, the premises, and the records: the project's AGENTS.md and
|
||||
docs/decisions.md, and the human's ~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
|
||||
~/.claude/skills/larv-review/standards/*.md, where they exist. It rules whether the chunk, the work
|
||||
of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a
|
||||
later chunk could need is recorded: the premises or the records hold it, or the transcript shows the
|
||||
worker writing it into the premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A
|
||||
choice the worker made that the premises or the records settle is not asked about. When the worker
|
||||
asks a question they answer, the judge quotes the answer, loop-claude prints it, and the worker
|
||||
resumes with it. A quote they do not hold word for word is dropped, and the question goes to the
|
||||
human. So does a question asked again after its answer. A question the human answered earlier in the
|
||||
chunk goes back to the worker with that answer, unless the question quotes the words of the answer
|
||||
that leave it open. The fourth question they answer in one cycle goes to the human too, with the
|
||||
quote. An unfinished chunk resumes its session next cycle, and the worker is shown the passage the
|
||||
judge quoted as the work remaining. The next chunk starts a fresh session. Cycles continue until an
|
||||
exit below or Ctrl-C. Words: ~/.claude/CLAUDE.md → "Vocabulary".
|
||||
|
||||
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
|
||||
loop-claude prints the question on its terminal and lists it in loop-inbox, which shows the
|
||||
@@ -97,9 +98,9 @@ loop-claude --help succeeds: the loop reloads into the edited script.
|
||||
Exit 1, saying why, when:
|
||||
- no task is given
|
||||
- git cannot start or finds no checkout
|
||||
- README.md, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or
|
||||
- the goals file, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or
|
||||
~/.claude/skills/larv-review/standards/*.md where they exist, cannot be read or is not UTF-8
|
||||
- README.md holds no premises
|
||||
- no config names the checkout, or the goals file holds no premises
|
||||
- the models file cannot be read or written
|
||||
- claude leaves no transcript
|
||||
- a transcript cannot be read or archived
|
||||
|
||||
@@ -1,20 +1,24 @@
|
||||
from failure import Failure
|
||||
from project_config.main import goals_file
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
from records.markdown_text import sections
|
||||
|
||||
|
||||
def read_premises(root: str) -> str | Failure:
|
||||
"""README.md's ## Goals and ## Audience in root; a Failure where README.md cannot be read or lacks either, or holds one twice or empty."""
|
||||
text = read_utf8(root, "README.md", "no premises")
|
||||
"""## Goals and ## Audience in the file root's project config names for them; a Failure where no config names it, it cannot be read, or it lacks either, or holds one twice or empty."""
|
||||
path = goals_file(root)
|
||||
if isinstance(path, Failure):
|
||||
return Failure(f"{path.reason} - no premises.")
|
||||
text = read_utf8(str(path.parent), path.name, "no premises")
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
found = sections(text)
|
||||
for name in ("Goals", "Audience"):
|
||||
bodies = found.get(name, [])
|
||||
if not bodies:
|
||||
return Failure(f"README.md has no ## {name} heading - no premises.")
|
||||
return Failure(f"{path.name} has no ## {name} heading - no premises.")
|
||||
if len(bodies) > 1:
|
||||
return Failure(f"README.md has ## {name} more than once - no premises.")
|
||||
return Failure(f"{path.name} has ## {name} more than once - no premises.")
|
||||
if not bodies[0]:
|
||||
return Failure(f"README.md has no text under ## {name} - no premises.")
|
||||
return Failure(f"{path.name} has no text under ## {name} - no premises.")
|
||||
return f"## Goals\n{found['Goals'][0]}\n\n## Audience\n{found['Audience'][0]}"
|
||||
|
||||
@@ -3,7 +3,7 @@ import pathlib
|
||||
from failure import Failure
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
|
||||
# The records the judge reads beside the README's premises: these project files, then the human's rules below.
|
||||
# The records the judge reads beside the premises: these project files, then the human's rules below.
|
||||
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
|
||||
# The human's rules for every project, under ~/.claude: CLAUDE.md, then each .md file in these folders, which a repo check keeps present.
|
||||
HUMAN_RULES_FILE = "CLAUDE.md"
|
||||
|
||||
@@ -21,6 +21,7 @@ from test_env import isolated_env
|
||||
from loop_state.waiting.answers import send, Typed
|
||||
from loop_state import session_lock
|
||||
from loop_state.waiting.listing import waiting
|
||||
from project_config.test_project_config import write_config
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
TASK = "Do the next chunk."
|
||||
@@ -191,6 +192,7 @@ class Checkout:
|
||||
self.root = self.home / "code" / "proj"
|
||||
self.root.mkdir(parents=True)
|
||||
(self.root / "README.md").write_text(PREMISES)
|
||||
write_config(self.home, self.root)
|
||||
self.script = BIN / "loop-claude"
|
||||
self.env = isolated_env()
|
||||
fake = self.temp / "fake-bin"
|
||||
@@ -360,11 +362,25 @@ class Premises(unittest.TestCase):
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertEqual(run.stderr.strip(), f"README.md in {checkout.root}: Is a directory - no premises.")
|
||||
(checkout.home / ".claude-projects" / "proj" / "config.toml").unlink()
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertEqual(run.stderr.strip(), f"no config names the checkout {checkout.root}: write ~/.claude-projects/<key>/config.toml, as `project-config --help` shows - no premises.")
|
||||
(checkout.temp / "fake-bin" / "git").unlink()
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertTrue(run.stderr.startswith("git rev-parse --show-toplevel could not start: "), run.stderr)
|
||||
|
||||
def test_reads_the_premises_from_the_file_the_config_names(self):
|
||||
checkout = Checkout(self)
|
||||
checkout.commit_plan(TODO)
|
||||
(checkout.root / "README.md").write_text("# Project\n")
|
||||
folder = write_config(checkout.home, checkout.root, goals="folder:goals.md")
|
||||
(folder / "goals.md").write_text("## Goals\n1. Kept apart.\n\n## Audience\nThe client.\n")
|
||||
run = checkout.run([worker()])
|
||||
self.assertTrue(run.calls, run.stderr)
|
||||
self.assertIn("## Goals\n1. Kept apart.\n\n## Audience\nThe client.", argument(run.calls[0], "-p"))
|
||||
|
||||
def test_makes_no_worktree_for_a_readme_without_premises(self):
|
||||
checkout = Checkout(self)
|
||||
checkout.commit_plan(TODO)
|
||||
@@ -379,6 +395,7 @@ class Premises(unittest.TestCase):
|
||||
with self.subTest(root=root):
|
||||
root.mkdir(exist_ok=True)
|
||||
(root / "README.md").write_text(PREMISES)
|
||||
write_config(checkout.home, root)
|
||||
checkout.git("init", "--quiet", str(root))
|
||||
run = checkout.run([worker()], cwd=root)
|
||||
self.assertEqual(argument(run.calls[0], "--name"), f"A {str(root).lstrip('/')} loop-claude")
|
||||
@@ -407,7 +424,7 @@ class Cycles(unittest.TestCase):
|
||||
self.assertIsNone(argument(workers[1], "--name"))
|
||||
self.assertEqual(argument(workers[2], "--session-id"), session)
|
||||
self.assertTrue(argument(workers[0], "-p").startswith(f"{TASK}\n\nContinue any open draft PR"))
|
||||
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below, " 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it' ", choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n## Goals\n1. Work.\n\n## Audience\nMe."))
|
||||
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below, " 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless the goals file voids it' ", choose between ways to deliver that scope, and never widen it.\n\nFrom the goals file:\n## Goals\n1. Work.\n\n## Audience\nMe."))
|
||||
self.assertIn("main or master", argument(workers[0], "-p"))
|
||||
self.assertNotIn(TASK, argument(workers[1], "-p"))
|
||||
self.assertIn("Even then, it is finished only once every answer the human typed in it", argument(workers[1], "-p"))
|
||||
|
||||
@@ -274,7 +274,7 @@ class Transitions(unittest.TestCase):
|
||||
class QuestionFor(unittest.TestCase):
|
||||
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
|
||||
self.assertEqual(run.question_for(Interrupt("e", "Which one?")), "Which one?")
|
||||
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
|
||||
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
|
||||
|
||||
|
||||
class Cycles(unittest.TestCase):
|
||||
@@ -520,7 +520,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
|
||||
self.assertEqual(len(judge_prompts), 2)
|
||||
self.assertNotIn("the second", judge_prompts[0])
|
||||
self.assertIn("[human] the second", judge_prompts[1])
|
||||
self.assertIn("From README.md:\n## Goals", judge_prompts[0])
|
||||
self.assertIn("From the goals file:\n## Goals", judge_prompts[0])
|
||||
self.assertIn("The task the worker was given:\nDo it.", judge_prompts[0])
|
||||
|
||||
def test_a_question_the_records_answer_resumes_the_worker_with_the_answer_three_times_a_cycle(self):
|
||||
@@ -529,12 +529,12 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said, contextlib.redirect_stdout(io.StringIO()) as printed:
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A.")), Stop(2, "the human is needed to answer the question above, but nothing was typed"))
|
||||
resumed = fake.made("stream_claude")[1]
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answers it:\n\nUse *A*.\n\nContinue the task.")
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answers it:\n\nUse *A*.\n\nContinue the task.")
|
||||
self.assertEqual(len(fake.made("stream_claude")), 4)
|
||||
self.assertEqual(printed.getvalue().count("=== README.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answered: Which one? ===\nUse *A*."), 3)
|
||||
self.assertIn("Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
|
||||
quoted = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\n> Use *A*.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
self.assertEqual(printed.getvalue().count("=== the goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answered: Which one? ===\nUse *A*."), 3)
|
||||
self.assertIn("Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
|
||||
quoted = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\n> Use *A*.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
|
||||
def test_a_quoted_answer_that_cites_an_escalation_trigger_steps_the_worker_up_before_it_resumes_and_archives_the_step(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("quoted", answer="Use A.", escalation="working"), judged("finished")])
|
||||
@@ -2026,10 +2026,10 @@ class HelpLimits(unittest.TestCase):
|
||||
|
||||
class ExitContract(unittest.TestCase):
|
||||
def test_every_exit_1_stop_has_its_clause_in_help(self):
|
||||
read, git, premises_ = "a transcript cannot be read or archived", "git cannot start or finds no checkout", "README.md holds no premises"
|
||||
read, git, premises_ = "a transcript cannot be read or archived", "git cannot start or finds no checkout", "no config names the checkout, or the goals file holds no premises"
|
||||
models_ = "the models file cannot be read or written"
|
||||
names = (*records.RECORD_FILES, records.HUMAN_RULE_NAMES[0], *(f"{folder}*.md" for folder in records.HUMAN_RULE_NAMES[1:]))
|
||||
unreadable = f"README.md, or {', '.join(names[:-1])} or {names[-1]} where they exist, cannot be read or is not UTF-8"
|
||||
unreadable = f"the goals file, or {', '.join(names[:-1])} or {names[-1]} where they exist, cannot be read or is not UTF-8"
|
||||
# Every Stop whose code is not a literal 0, 2 or 130, in source order: path, function, code, start of reason, its --help clause.
|
||||
clauses = [
|
||||
("cycle/interrupt.py", "claude_open", "1", "f'could not start claude for the interrupt:", "claude cannot start for an interrupt"),
|
||||
|
||||
@@ -44,7 +44,7 @@ class Interrupt:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class QuotedAnswer:
|
||||
"""The worker asked a question that README.md or the records answer. The answer field quotes the passage."""
|
||||
"""The worker asked a question that the premises or the records answer. The answer field quotes the passage."""
|
||||
evidence: str
|
||||
question: str
|
||||
answer: str
|
||||
|
||||
@@ -47,11 +47,18 @@ def main(argv: list[str]) -> int:
|
||||
return 0
|
||||
|
||||
|
||||
def located() -> ProjectConfig | Failure:
|
||||
found = git("rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir")
|
||||
def located(directory: str | None = None) -> ProjectConfig | Failure:
|
||||
"""The config of the checkout that holds directory, else the current directory."""
|
||||
found = git("rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir", cwd=directory)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
if len(lines := found.splitlines()) != 2:
|
||||
return Failure(f"git rev-parse printed {found!r}, not a checkout's top folder and git directory on two lines")
|
||||
# The common dir is the main checkout's .git, whichever worktree runs this.
|
||||
return load(pathlib.Path(lines[0]), pathlib.Path(lines[1]).parent, pathlib.Path.home())
|
||||
|
||||
|
||||
def goals_file(directory: str) -> pathlib.Path | Failure:
|
||||
"""The file holding the premises, `## Goals` and `## Audience`, of the project whose checkout holds directory."""
|
||||
config = located(directory)
|
||||
return config if isinstance(config, Failure) else config.paths["goals-and-audience"]
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
import os
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
@@ -25,6 +27,27 @@ principles = "~/.claude/principles"
|
||||
"""
|
||||
|
||||
|
||||
def write_config(home: pathlib.Path, checkout: pathlib.Path, goals: str = "checkout:README.md") -> pathlib.Path:
|
||||
"""A config under home that names checkout, every setting inside it but goals-and-audience; for the tests of each tool that reads the config."""
|
||||
folder = home / ".claude-projects" / checkout.name
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
(folder / "config.toml").write_text(CLIENT.replace('"~/code/acme-billing"', f'"{checkout}"').replace('"folder:', '"checkout:').replace('"checkout:goals.md"', f'"{goals}"'), encoding="utf-8")
|
||||
return folder
|
||||
|
||||
|
||||
def configured(test: unittest.TestCase, checkout: pathlib.Path, goals: str = "checkout:README.md", home: pathlib.Path | None = None) -> pathlib.Path:
|
||||
"""Makes checkout a git checkout that a config names, under home, else a HOME of its own, for the rest of the test; the config's folder."""
|
||||
subprocess.run(["git", "init", "--quiet", str(checkout)], check=True, env=isolated_env())
|
||||
if home is None:
|
||||
made = tempfile.TemporaryDirectory()
|
||||
test.addCleanup(made.cleanup)
|
||||
home = pathlib.Path(made.name)
|
||||
patched = unittest.mock.patch.dict(os.environ, {"HOME": str(home)})
|
||||
patched.start()
|
||||
test.addCleanup(patched.stop)
|
||||
return write_config(home, checkout, goals)
|
||||
|
||||
|
||||
class ConfigCase(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
made = tempfile.TemporaryDirectory()
|
||||
|
||||
+17
-16
@@ -1,14 +1,15 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Score todo.md's items by the formula it states, weighing code health first and then README.md's achieve goals by their position, and hold them to its bar.
|
||||
"""Score todo.md's items by the formula it states, weighing code health first and then the goals file's achieve goals by their position, and hold them to its bar.
|
||||
|
||||
usage: rank_todo.py [--check] [todo.md]
|
||||
|
||||
Reads todo.md (default: ./todo.md), the README.md beside it, and docs/decisions.md and
|
||||
docs/comprehension-history.md where they exist. Rewrites each item's Score from the formula and
|
||||
sorts the items by release; within a release, question rows come first, then security rows, then
|
||||
the rest, each group by score from highest, then by ID. Then it moves each blocker, an item
|
||||
another's Blocked by cell names, that ranks below an item it blocks to just above the first such
|
||||
item. Orders the details to match. Writes each item's R, and adds the Blocked by and R columns to a
|
||||
Reads todo.md (default: ./todo.md); the goals file, which its project's config sets as
|
||||
goals-and-audience; and docs/decisions.md and docs/comprehension-history.md where they exist.
|
||||
Rewrites each item's Score from the formula and sorts the items by release; within a release,
|
||||
question rows come first, then security rows, then the rest, each group by score from highest,
|
||||
then by ID. Then it moves each blocker, an item another's Blocked by cell names, that ranks below
|
||||
an item it blocks to just above the first such item.
|
||||
Orders the details to match. Writes each item's R, and adds the Blocked by and R columns to a
|
||||
table without them. --check doesn't write anything and fails when the file is not ranked as it would be.
|
||||
|
||||
A valid todo.md; ## Details and each item's detail are optional:
|
||||
@@ -37,15 +38,15 @@ A valid todo.md; ## Details and each item's detail are optional:
|
||||
|
||||
- The formula holds numbers, + - * / ** and parentheses over L, E, I, R, S and V.
|
||||
- V sums, over the goals in an item's Moves cell, each goal's weight times how far the item moves it.
|
||||
README.md marks each goal **Maintain:** or **Achieve:**. Code health, the achieve goal every
|
||||
project shares, ranks first; a Moves cell names it as in `code health by 6`. README.md's achieve
|
||||
The goals file marks each goal **Maintain:** or **Achieve:**. Code health, the achieve goal
|
||||
every project shares, ranks first; a Moves cell names it as in `code health by 6`. Its achieve
|
||||
goals follow in reading order, a sub-goal such as 1.1 included. Each weighs 0.97 times the one
|
||||
before, and the weights sum to 1. With 5 achieve goals the first weighs 0.212 and the last 0.188.
|
||||
With 15 they weigh 0.082 and 0.053. The overall is the mean of the overall means of every scoring
|
||||
run on docs/comprehension-history.md's newest scored commit. While it is under 7.0, or the history
|
||||
holds no scoring run, code health weighs 4 times its weight by position, and the other goals keep
|
||||
theirs. A line `**Void:** code health, since <reason>.` in README.md's ## Goals drops code health,
|
||||
and an item may not name it. A project must void it where its docs/decisions.md has a
|
||||
theirs. A line `**Void:** code health, since <reason>.` in the goals file's ## Goals drops code
|
||||
health, and an item may not name it. A project must void it where its docs/decisions.md has a
|
||||
`## review opt-out:` title naming the comprehension check. An item that adds a test,
|
||||
a gate leg or a probe that fails where a maintain goal breaks may name that goal, by how much
|
||||
more confident the project becomes that the goal holds, 1 to 10. Each point is worth 0.5. An
|
||||
@@ -73,17 +74,17 @@ A valid todo.md; ## Details and each item's detail are optional:
|
||||
- The table holds the columns above. One missing L, E or I fails, and so does one with a column this
|
||||
version does not know, since writing it would drop that column.
|
||||
- A table in the old shape, with C, A, G and Goals columns in place of L, E, I and Moves, still
|
||||
ranks, by a formula over R, S, A, G and W and a | Goal | W | table that weighs every README goal, W
|
||||
ranks, by a formula over R, S, A, G and W and a | Goal | W | table that weighs every goal, W
|
||||
being the heaviest cited goal's weight; ranking it says to reshape it.
|
||||
- ## Renamed is optional: one line `- 0.2.1 renamed to 0.3.0` per renamed release. chunk-preflight,
|
||||
loop-claude and larv-review skip the line's first release, and ignore the second, which is for the
|
||||
reader. No item may sit under a marked release, and a line goes once a tag at or past its first
|
||||
release is cut. A release whose items all moved elsewhere without a line reads as finished.
|
||||
|
||||
Exit 1, saying why, on bad arguments, a file that cannot be read or written, a todo.md, README.md or
|
||||
docs/decisions.md that breaks the rules above, a scoring run on docs/comprehension-history.md's
|
||||
newest scored commit with no Mean row ending in its overall, an item that is not exempt scoring
|
||||
under the bar, or --check finding the file unranked.
|
||||
Exit 1, saying why, on bad arguments, a checkout no config names, a file that cannot be read or
|
||||
written, a todo.md, goals file or docs/decisions.md that breaks the rules above, a scoring run on
|
||||
docs/comprehension-history.md's newest scored commit with no Mean row ending in its overall, an
|
||||
item that is not exempt scoring under the bar, or --check finding the file unranked.
|
||||
"""
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
@@ -3,6 +3,7 @@ import pathlib
|
||||
import sys
|
||||
|
||||
from failure import Failure
|
||||
from project_config.main import goals_file
|
||||
from review_rules.comprehension_history import HISTORY
|
||||
from release_plan.ranking import rank, Ranked
|
||||
from records.file_writes import replace_file
|
||||
@@ -41,9 +42,12 @@ def check_failures(todo: pathlib.Path) -> list[str]:
|
||||
|
||||
|
||||
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
|
||||
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md. The last two are empty when missing; a missing todo.md or README.md is a Failure."""
|
||||
"""todo.md, the goals file its project's config names, and its docs/decisions.md and docs/comprehension-history.md. The last two are empty when missing; a missing todo.md, config or goals file is a Failure."""
|
||||
goals = goals_file(str(todo.parent))
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
texts = []
|
||||
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
|
||||
for path, missing in ((todo, "every project keeps a todo.md, and rank_todo.py --help shows one"), (goals, "rank_todo.py weighs goals from the file the project's config names as goals-and-audience"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
|
||||
try:
|
||||
texts.append(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
|
||||
+22
-22
@@ -1,4 +1,4 @@
|
||||
"""Rank todo.md's items by the formula it states, weighing code health first and then README.md's achieve goals by their position, and hold them to its bar; rank_todo.py --help states the rules.
|
||||
"""Rank todo.md's items by the formula it states, weighing code health first and then the goals file's achieve goals by their position, and hold them to its bar; rank_todo.py --help states the rules.
|
||||
"""
|
||||
import ast
|
||||
import dataclasses
|
||||
@@ -21,16 +21,16 @@ GOAL_STEP = 0.97
|
||||
UNDER_FLOOR = 4
|
||||
# What a point of an item's move on a maintain goal is worth. A defect that restores the goal weighs it at least this much per point. docs/decisions.md records the choice and its data.
|
||||
MAINTAIN_WEIGHT = 0.5
|
||||
# Any **Void:** line of README.md's ## Goals; ranked_goals accepts only `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
|
||||
# Any **Void:** line of the goals file's ## Goals; ranked_goals accepts only `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
|
||||
VOID = re.compile(r"^\*\*Void:\*\* (.*)$", re.M)
|
||||
# A docs/decisions.md title opting the project out of the comprehension check, as larv-review's SKILL.md → "Opt-out" spells it.
|
||||
OPTED_OUT = re.compile(r"^## review opt-out:.*\bcomprehension check\b", re.M)
|
||||
WEIGHTS_HEADER = "| Goal | W |"
|
||||
# The Exempt reasons that rank ahead of the rest of their release, in this order: a question first, since its answer may change other items, then a security finding.
|
||||
FIRST: dict[Exempt, int] = {"question": 0, "security": 1}
|
||||
# How README.md marks a goal; None where it marks it neither way.
|
||||
# How the goals file marks a goal; None where it marks it neither way.
|
||||
Mark = typing.Literal["Maintain", "Achieve"] | None
|
||||
RESHAPE = f"todo.md's items table is in the old shape, scoring A and G against goal weights todo.md states. Until todo.md has the shape rank_todo.py --help shows, reshaping it is the project's only work, as ~/.claude/CLAUDE.md → 'Working loop' says: mark README.md's goals **Maintain:** or **Achieve:**, name each item's {MOVES}, score its L, E and I in place of C, and set the bar below the score of every item to keep"
|
||||
RESHAPE = f"todo.md's items table is in the old shape, scoring A and G against goal weights todo.md states. Until todo.md has the shape rank_todo.py --help shows, reshaping it is the project's only work, as ~/.claude/CLAUDE.md → 'Working loop' says: mark the goals file's goals **Maintain:** or **Achieve:**, name each item's {MOVES}, score its L, E and I in place of C, and set the bar below the score of every item to keep"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -39,9 +39,9 @@ class Scoring:
|
||||
formula: ast.Expression
|
||||
bar: float
|
||||
next_id: int
|
||||
# Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. In OLD_SHAPE an item may name only the goals weights holds.
|
||||
# Every goal in rank order, each with its mark: code health first, unless the goals file voids it, then the goals file's goals in reading order. In OLD_SHAPE an item may name only the goals weights holds.
|
||||
goals: dict[str, Mark]
|
||||
# The weight of each goal an item may name: in OLD_SHAPE each of README.md's goals, at the weight todo.md states; else each achieve goal, as goal_weights weighs it. A maintain goal is weighed per item, by weight_of.
|
||||
# The weight of each goal an item may name: in OLD_SHAPE each of the goals file's goals, at the weight todo.md states; else each achieve goal, as goal_weights weighs it. A maintain goal is weighed per item, by weight_of.
|
||||
weights: dict[str, float]
|
||||
|
||||
|
||||
@@ -99,7 +99,7 @@ def notes(items: list[Item], scoring: Scoring) -> list[str]:
|
||||
if scoring.shape is OLD_SHAPE:
|
||||
return [RESHAPE] + dropped
|
||||
# Printed so the under-bar lines it causes do not read as items of low value.
|
||||
unweighed = [] if any(scoring.weights.values()) else ["README.md voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"]
|
||||
unweighed = [] if any(scoring.weights.values()) else ["the goals file voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"]
|
||||
return unweighed + dropped
|
||||
|
||||
|
||||
@@ -141,24 +141,24 @@ def read_scoring(text: str, lines: list[str], readme: str, decisions: str, histo
|
||||
|
||||
|
||||
def ranked_goals(readme: str, decisions: str) -> list[tuple[str, Mark]] | Failure:
|
||||
"""Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. A **Void:** line other than `**Void:** code health, since <reason>.` fails, and so does a docs/decisions.md that opts out of the comprehension check where README.md keeps code health, since the goal then has no signal."""
|
||||
"""Every goal in rank order, each with its mark: code health first, unless the goals file voids it, then the goals file's goals in reading order. A **Void:** line other than `**Void:** code health, since <reason>.` fails, and so does a docs/decisions.md that opts out of the comprehension check where the goals file keeps code health, since the goal then has no signal."""
|
||||
goals = readme_goals(readme)
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
voids = VOID.findall("".join(sections(readme).get("Goals", [])))
|
||||
if other := [void for void in voids if not void.startswith(f"{CODE_HEALTH}, since ")]:
|
||||
if other[0].lower().startswith(CODE_HEALTH):
|
||||
return Failure(f"README.md's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
return Failure(f"README.md's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
return Failure(f"the goals file's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
return Failure(f"the goals file's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
if voids:
|
||||
return goals
|
||||
if OPTED_OUT.search(decisions):
|
||||
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
|
||||
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in the goals file's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
|
||||
return [(CODE_HEALTH, "Achieve"), *goals]
|
||||
|
||||
|
||||
def weigh(lines: list[str], history: str, goals: list[tuple[str, Mark]], shape: Shape) -> dict[str, float] | Failure:
|
||||
"""Each goal's weight. In OLD_SHAPE, README.md's goals weigh what todo.md states, and code health has no weight, so no item may name it. Otherwise goal_weights gives each its weight, at the overall latest_overall reads where the goals hold code health."""
|
||||
"""Each goal's weight. In OLD_SHAPE, the goals file's goals weigh what todo.md states, and code health has no weight, so no item may name it. Otherwise goal_weights gives each its weight, at the overall latest_overall reads where the goals hold code health."""
|
||||
if shape is OLD_SHAPE:
|
||||
return parse_weights(lines, [number for number, _ in goals if number != CODE_HEALTH])
|
||||
if WEIGHTS_HEADER in lines:
|
||||
@@ -249,10 +249,10 @@ def check_citations(items: list[Item], decisions: str) -> Failure | None:
|
||||
|
||||
|
||||
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
|
||||
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
|
||||
"""The goals file's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
|
||||
found = sections(readme).get("Goals", [])
|
||||
if len(found) != 1:
|
||||
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
|
||||
return Failure(f"the goals file has ## Goals {len(found)} times; it needs it once")
|
||||
goals: list[tuple[str, Mark]] = []
|
||||
path: list[tuple[int, str]] = []
|
||||
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
|
||||
@@ -262,16 +262,16 @@ def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
|
||||
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
|
||||
numbers = [number for number, _ in goals]
|
||||
if not goals:
|
||||
return Failure("README.md's ## Goals has no numbered goal")
|
||||
return Failure("the goals file's ## Goals has no numbered goal")
|
||||
if len(set(numbers)) < len(numbers):
|
||||
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
|
||||
return Failure(f"the goals file's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
|
||||
return goals
|
||||
|
||||
|
||||
def goal_weights(goals: list[tuple[str, Mark]], overall: decimal.Decimal | None) -> dict[str, float] | Failure:
|
||||
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Every weight is 0 where goals holds no achieve goal, as where README.md voids code health and marks no goal **Achieve:**; an item then scores V 0 unless it names a maintain goal, and only an exempt one passes the bar. A maintain goal has no weight here: weight_of weighs it per item."""
|
||||
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Every weight is 0 where goals holds no achieve goal, as where the goals file voids code health and marks no goal **Achieve:**; an item then scores V 0 unless it names a maintain goal, and only an exempt one passes the bar. A maintain goal has no weight here: weight_of weighs it per item."""
|
||||
if unmarked := [number for number, mark in goals if mark is None]:
|
||||
return Failure(f"README.md's goal {unmarked[0]} is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score")
|
||||
return Failure(f"the goals file's goal {unmarked[0]} is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score")
|
||||
achieve = [number for number, mark in goals if mark == "Achieve"]
|
||||
total = sum(GOAL_STEP**rank for rank in range(len(achieve)))
|
||||
weights = {number: GOAL_STEP**rank / total for rank, number in enumerate(achieve)}
|
||||
@@ -346,7 +346,7 @@ def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Fail
|
||||
weights[found[0]] = weight
|
||||
if list(weights) != goals:
|
||||
default = "\n".join(f"| {goal} | {(len(goals) - index) / len(goals):.2f} |" for index, goal in enumerate(goals))
|
||||
return Failure(f"the goal weights list {', '.join(weights) or 'no goal'}, but README.md's goals are {', '.join(goals)}; by position they weigh:\n{WEIGHTS_HEADER}\n|---|---|\n{default}")
|
||||
return Failure(f"the goal weights list {', '.join(weights) or 'no goal'}, but the goals file's goals are {', '.join(goals)}; by position they weigh:\n{WEIGHTS_HEADER}\n|---|---|\n{default}")
|
||||
return weights
|
||||
|
||||
|
||||
@@ -364,15 +364,15 @@ def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
|
||||
|
||||
|
||||
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
|
||||
"""Why the item may not name one of the goals it names, such as one README.md voids or does not number; None when it may name each. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
|
||||
"""Why the item may not name one of the goals it names, such as one the goals file voids or does not number; None when it may name each. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
|
||||
if scoring.shape is OLD_SHAPE:
|
||||
unknown = [goal for goal, _ in item.moves if goal not in scoring.weights]
|
||||
return Failure(f"item {item.id} cites goal {', '.join(unknown)}, which the goal weights do not list") if unknown else None
|
||||
for goal, _ in item.moves:
|
||||
if goal == CODE_HEALTH and goal not in scoring.goals:
|
||||
return Failure(f"item {item.id} names {CODE_HEALTH}, which README.md voids; drop it from the item's {MOVES}, or the void from README.md")
|
||||
return Failure(f"item {item.id} names {CODE_HEALTH}, which the goals file voids; drop it from the item's {MOVES}, or the void from the goals file")
|
||||
if goal not in scoring.goals:
|
||||
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
|
||||
return Failure(f"item {item.id} cites goal {goal}, which the goals file's ## Goals does not number")
|
||||
return None
|
||||
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ 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 release_plan import plan_file, ranking
|
||||
from repo_checks import ROOT
|
||||
@@ -157,14 +158,14 @@ class Rank(unittest.TestCase):
|
||||
self.assertEqual(ranking.readme_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("README.md's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
|
||||
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("the goals file's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
|
||||
self.assertEqual(ranking.readme_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
|
||||
|
||||
def test_refuses_a_goal_it_cannot_weigh(self):
|
||||
cases = {
|
||||
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 3 by 6"), README): "item 3 cites goal 3, which README.md's ## Goals does not number",
|
||||
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 3 by 6"), README): "item 3 cites goal 3, which the goals file's ## Goals does not number",
|
||||
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 2.1 by 6"), README): "item 3 cites goal 2.1 twice; name each goal once",
|
||||
(TODO, README.replace("**Maintain:** Correct", "Correct")): "README.md's goal 2 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score",
|
||||
(TODO, README.replace("**Maintain:** Correct", "Correct")): "the goals file's goal 2 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score",
|
||||
}
|
||||
for (todo, readme), reason in cases.items():
|
||||
with self.subTest(reason=reason):
|
||||
@@ -197,7 +198,7 @@ class Rank(unittest.TestCase):
|
||||
def test_scores_every_item_zero_where_readme_marks_no_goal_achieve(self):
|
||||
ranked = self.ranked(TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| |").replace("| 1 by 9 |", "| |"), README.replace("**Achieve:**", "**Maintain:**"))
|
||||
self.assertEqual([line.split(" scores ")[0] for line in ranked.under_bar], ["item 2", "item 3", "item 1"])
|
||||
self.assertEqual(ranked.notes, ["README.md voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"])
|
||||
self.assertEqual(ranked.notes, ["the goals file voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"])
|
||||
|
||||
def test_accepts_a_move_of_ten_and_a_variable_base(self):
|
||||
ranked = self.ranked(TODO.replace("| 1 by 9 |", "| 1 by 10 |").replace("100 * V / 2**S", "V * S ** 2"))
|
||||
@@ -298,7 +299,7 @@ class CodeHealth(unittest.TestCase):
|
||||
|
||||
def test_drops_code_health_where_readme_voids_it(self):
|
||||
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
|
||||
self.assertEqual(self.scores("", voided), Failure("item 1 names code health, which README.md voids; drop it from the item's Moves, or the void from README.md"))
|
||||
self.assertEqual(self.scores("", voided), Failure("item 1 names code health, which the goals file voids; drop it from the item's Moves, or the void from the goals file"))
|
||||
ranked = ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", "")
|
||||
self.assertIn("| **Read easier.** | 1 | 1 | 1 | 1 | 1 | 1 by 2 | 100.0 |", ranked.text)
|
||||
|
||||
@@ -311,7 +312,7 @@ class CodeHealth(unittest.TestCase):
|
||||
|
||||
def test_refuses_a_plan_whose_project_opts_out_of_the_comprehension_check_yet_keeps_code_health(self):
|
||||
opted_out = "## review opt-out: the architect and the comprehension check\n\nCosts rounds.\n"
|
||||
self.assertEqual(ranking.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
|
||||
self.assertEqual(ranking.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in the goals file's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
|
||||
self.assertIsInstance(ranking.rank(self.todo, self.readme, opted_out.replace(" and the comprehension check", ""), ""), ranking.Ranked)
|
||||
voided = "## Goals\n\n**Void:** code health, since nobody reads the probes.\n\n1. **Achieve:** A.\n"
|
||||
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, opted_out, ""), ranking.Ranked)
|
||||
@@ -321,23 +322,24 @@ class CodeHealth(unittest.TestCase):
|
||||
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", SCORED.format(overall="high")), ranking.Ranked)
|
||||
|
||||
def test_refuses_a_void_of_anything_but_code_health(self):
|
||||
self.assertEqual(self.scores("", "## Goals\n\n**Void:** speed, since nobody waits.\n\n1. **Achieve:** A.\n"), Failure("README.md's ## Goals voids `speed, since nobody waits.`; only code health may be voided, as `**Void:** code health, since <reason>.`"))
|
||||
self.assertEqual(self.scores("", "## Goals\n\n**Void:** speed, since nobody waits.\n\n1. **Achieve:** A.\n"), Failure("the goals file's ## Goals voids `speed, since nobody waits.`; only code health may be voided, as `**Void:** code health, since <reason>.`"))
|
||||
|
||||
def test_shows_the_spelling_of_a_void_of_code_health_that_misses_it(self):
|
||||
for void in ("code health.", "Code health, since it is a one-off script.", "code health since it is a one-off script."):
|
||||
with self.subTest(void=void):
|
||||
self.assertEqual(self.scores("", f"## Goals\n\n**Void:** {void}\n\n1. **Achieve:** A.\n"), Failure(f"README.md's ## Goals voids code health as `{void}`; spell the void exactly `**Void:** code health, since <reason>.`"))
|
||||
self.assertEqual(self.scores("", f"## Goals\n\n**Void:** {void}\n\n1. **Achieve:** A.\n"), Failure(f"the goals file's ## Goals voids code health as `{void}`; spell the void exactly `**Void:** code health, since <reason>.`"))
|
||||
|
||||
def test_parses_code_health_in_a_moves_cell(self):
|
||||
self.assertEqual(todo_table.parse_moves("1", "code health by 4, 1.1 by 2"), (("code health", 4), ("1.1", 2)))
|
||||
self.assertIsInstance(todo_table.parse_moves("1", "code health by 11"), Failure)
|
||||
self.assertIsInstance(todo_table.parse_moves("1", "health by 4"), Failure)
|
||||
|
||||
def test_reads_the_history_beside_todo_md(self):
|
||||
def test_reads_the_history_beside_todo_md_and_the_goals_the_config_names(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
todo.write_text(self.todo)
|
||||
pathlib.Path(temp, "README.md").write_text(self.readme)
|
||||
folder = configured(self, pathlib.Path(temp), goals="folder:goals.md")
|
||||
(folder / "goals.md").write_text(self.readme)
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
pathlib.Path(temp, "docs", "comprehension-history.md").write_text(SCORED.format(overall="7.00"))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
|
||||
@@ -20,7 +20,7 @@ EXEMPTIONS: tuple[Exempt, ...] = typing.get_args(Exempt)
|
||||
BLOCKED_BY = "Blocked by"
|
||||
# The column naming each achieve goal an item moves and how far, such as `1.1 by 8, 1.2 by 5`.
|
||||
MOVES = "Moves"
|
||||
# The achieve goal every project shares, which ~/.claude/CLAUDE.md → "Shared goal" states, and a Moves cell names by these words, since it has no number in any README.
|
||||
# The achieve goal every project shares, which ~/.claude/CLAUDE.md → "Shared goal" states, and a Moves cell names by these words, since it has no number in any goals file.
|
||||
CODE_HEALTH = "code health"
|
||||
# How the items table's header opens, which tells it from any other table in todo.md.
|
||||
HEADER_START = "| ID | Release |"
|
||||
@@ -60,7 +60,7 @@ class Shape:
|
||||
|
||||
|
||||
def parse_moves(id_: str, cell: str) -> Moves | Failure:
|
||||
"""A Moves cell: empty, or each goal the item moves, named once, and how far. ranking.py's cited_goals_failure holds the rules that need README.md."""
|
||||
"""A Moves cell: empty, or each goal the item moves, named once, and how far. ranking.py's cited_goals_failure holds the rules that need the goals file."""
|
||||
matches = [re.fullmatch(rf"([0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
|
||||
moves = tuple((match.group(1), int(match.group(2))) for match in matches if match)
|
||||
if len(moves) < len(matches) or any(not 1 <= by <= TOP_SCORE for _, by in moves):
|
||||
@@ -260,7 +260,7 @@ def cells(row: str, count: int) -> list[str] | Failure:
|
||||
|
||||
|
||||
def parse_row(row: str, table: Table) -> Item | Failure:
|
||||
"""An item row of table, every cell checked but whether README.md numbers and weighs the goals it names."""
|
||||
"""An item row of table, every cell checked but whether the goals file numbers and weighs the goals it names."""
|
||||
found = cells(row, len(table.columns))
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
|
||||
@@ -18,6 +18,7 @@ from rule_hook.rules import blocks, Breach, check, command_breaches, file_breach
|
||||
from rule_hook.main import breaches_of
|
||||
from rule_hook.call import Call, parsed_call
|
||||
from git_cli.git_command import commit_message, CommitCall, commits
|
||||
from project_config.test_project_config import configured
|
||||
from release_plan.test_ranking import DECISIONS, README, TODO
|
||||
from rule_hook.git import guarded_git
|
||||
from test_env import isolated_env
|
||||
@@ -807,6 +808,7 @@ class Hook(unittest.TestCase):
|
||||
self.assertEqual(self.round_commit("Answer stability round 1: 0 🔴, 1 🟡 (0 misread); c").returncode, 0, "another chunk's rounds, fast-forwarded into the default branch, are not this chunk's")
|
||||
|
||||
def test_a_commit_while_an_unranked_todo_has_changes_is_blocked(self):
|
||||
configured(self, pathlib.Path(self.repo))
|
||||
pathlib.Path(self.repo, "docs").mkdir()
|
||||
for name, content in [("README.md", README), ("docs/decisions.md", DECISIONS), ("todo.md", TODO)]:
|
||||
pathlib.Path(self.repo, name).write_text(content)
|
||||
@@ -820,6 +822,7 @@ class Hook(unittest.TestCase):
|
||||
self.assertIn("todo.md: not ranked", ran.stderr)
|
||||
|
||||
def test_a_staged_todo_change_is_checked_and_no_clean_filter_runs(self):
|
||||
configured(self, pathlib.Path(self.repo))
|
||||
pathlib.Path(self.repo, "docs").mkdir()
|
||||
for name, content in [("README.md", README), ("docs/decisions.md", DECISIONS), ("todo.md", TODO), (".gitattributes", "todo.md filter=planted\n")]:
|
||||
pathlib.Path(self.repo, name).write_text(content)
|
||||
|
||||
@@ -7,6 +7,7 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from project_config.test_project_config import configured
|
||||
from release_plan.test_ranking import DECISIONS, OLD_SHAPE, README, TODO
|
||||
import rank_todo
|
||||
from release_plan import ranking
|
||||
@@ -21,6 +22,7 @@ class Main(unittest.TestCase):
|
||||
def test_ranks_the_file_in_place_and_check_writes_nothing(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
configured(self, pathlib.Path(temp))
|
||||
todo.write_text(TODO)
|
||||
pathlib.Path(temp, "README.md").write_text(README)
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
@@ -32,12 +34,13 @@ class Main(unittest.TestCase):
|
||||
pathlib.Path(temp, "README.md").write_bytes(b"\xff")
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not UTF-8\n"))
|
||||
pathlib.Path(temp, "README.md").unlink()
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not found; rank_todo.py weighs goals from the README.md beside todo.md\n"))
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not found; rank_todo.py weighs goals from the file the project's config names as goals-and-audience\n"))
|
||||
|
||||
def test_writes_the_ranked_file_yet_fails_on_an_item_under_the_bar(self):
|
||||
under = "item 2 scores 3.1, under the bar 4; delete it, or mark it with a reason the bar does not apply"
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
configured(self, pathlib.Path(temp))
|
||||
todo.write_text(TODO.replace("`Bar = 2`", "`Bar = 4`"))
|
||||
pathlib.Path(temp, "README.md").write_text(README)
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
@@ -48,6 +51,7 @@ class Main(unittest.TestCase):
|
||||
def test_says_to_reshape_an_old_shape_table_but_passes_the_check(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
configured(self, pathlib.Path(temp))
|
||||
todo.write_text(OLD_SHAPE)
|
||||
pathlib.Path(temp, "README.md").write_text(README)
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
|
||||
@@ -6,7 +6,7 @@ usage: todo-item add --release <version> --l <L> --e <E> --i <I> --s <S> [--move
|
||||
todo-item show <ID>
|
||||
|
||||
All three work on the todo.md in the current folder. add and finish also use the CHANGELOG.md beside it,
|
||||
and read the README.md and docs/decisions.md beside todo.md.
|
||||
and read the goals file its project's config names and the docs/decisions.md beside todo.md.
|
||||
The cells take the format rank_todo.py --help states; the letter flags take upper case too, as --L.
|
||||
|
||||
add takes Next ID as the item's ID and raises Next ID by one. It writes the row, with the tagline
|
||||
|
||||
@@ -7,6 +7,7 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
|
||||
|
||||
from project_config.test_project_config import configured
|
||||
from release_plan.test_ranking import DECISIONS, README, TODO
|
||||
from todo_item import edits, main
|
||||
from failure import Failure
|
||||
@@ -30,6 +31,7 @@ class TodoItem(unittest.TestCase):
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.folder = pathlib.Path(temp.name)
|
||||
configured(self, self.folder)
|
||||
self.todo = self.folder / "todo.md"
|
||||
self.changelog = self.folder / "CHANGELOG.md"
|
||||
(self.folder / "README.md").write_text(README)
|
||||
|
||||
@@ -1839,3 +1839,20 @@ Read most (opens and searches):
|
||||
Read most (opens and searches):
|
||||
|
||||
- `todo.md` 3
|
||||
|
||||
## Reading cost, chunk 1637197c2ac6, finished 2026-11-12T22:50:49Z
|
||||
|
||||
90214 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `bin/larv_review/test_larv_review.py` 8
|
||||
- `agents/systems-architect.md` 5
|
||||
- `CLAUDE.md` 4
|
||||
- `README.md` 3
|
||||
- `todo.md` 3
|
||||
- `agents/principles-auditor.md` 2
|
||||
- `bin/larv_review/main.py` 2
|
||||
- `bin/project_config/settings.py` 2
|
||||
- `rules/decisions.md` 2
|
||||
- `rules/todo-items.md` 2
|
||||
|
||||
@@ -1,12 +1,15 @@
|
||||
---
|
||||
paths:
|
||||
- "**/README.md"
|
||||
- "**/.claude-projects/*/goals.md"
|
||||
---
|
||||
|
||||
# Goals and Audience
|
||||
|
||||
- **Goals** state the project's aim and intent, not promises: one numbered line each, like slogans, in priority order; a sub-goal is indented under its goal — "1. Blazing fast performance. 2. Correctness is more important than many features." A goal names no step of the work, such as a check to run first, and rarely an implementation. How a goal is met goes in a method section further down the README and names the goal it serves. BANNED as a goal: `Kill weak candidates early, with the cheap checks first.` GOOD: the goal `Keep research on a budget, so it scales in both time and cost.`, with the cheap checks moved to the method section, naming that goal.
|
||||
They live in the project's goals file (`~/.claude/CLAUDE.md` → "Vocabulary"): `README.md`, or a client project's `goals.md` in its config's folder.
|
||||
|
||||
- **Goals** state the project's aim and intent, not promises: one numbered line each, like slogans, in priority order; a sub-goal is indented under its goal — "1. Blazing fast performance. 2. Correctness is more important than many features." A goal names no step of the work, such as a check to run first, and rarely an implementation. How a goal is met goes in a method section further down the goals file and names the goal it serves. BANNED as a goal: `Kill weak candidates early, with the cheap checks first.` GOOD: the goal `Keep research on a budget, so it scales in both time and cost.`, with the cheap checks moved to the method section, naming that goal.
|
||||
- **Mark each goal `**Maintain:**` or `**Achieve:**`.** A maintain goal is a state to hold: a change that breaks it is redesigned or dropped, whatever its value to other goals. An achieve goal is a direction to pursue, weighed against the other achieve goals. Under each achieve goal, three indented bullets: `Signal:` what moving towards it looks like, `Counter-signal:` what shows it is bought at a wrong price, and `Why:` one line on how the two connect. A goal with sub-goals states its own signal. A maintain goal has no bullets. BANNED: an unmarked goal; an achieve goal with no signal; `**Achieve:** Delivery speed.` with the signal `faster`. GOOD: `**Achieve:** Delivery speed.` with `Signal: hours from a chunk's start to its merge fall.`, `Counter-signal: 🔴 findings per chunk rise.` and `Why: speed bought by skipping review shows up as defects.`
|
||||
- **Leave code health out of the README.** `~/.claude/CLAUDE.md` → "Shared goal" states it for every project, ranked first, and says when and how a README voids it. File an item to drop a README goal that restates it: the goals after it renumber, and every Moves cell and decision citing them must follow.
|
||||
- **Leave code health out of the goals file.** `~/.claude/CLAUDE.md` → "Shared goal" states it for every project, ranked first, and says when and how a goals file voids it. File an item to drop a goal that restates it: the goals after it renumber, and every Moves cell and decision citing them must follow.
|
||||
- **Audience** names who depends on the project and what they may rely on.
|
||||
- **Every project's audience includes the contributor**: the person who reads the code to change it. The README doesn't list them, and drops them only with the `**Void:** code health` line (`~/.claude/CLAUDE.md` → "Shared goal").
|
||||
- **Every project's audience includes the contributor**: the person who reads the code to change it. The goals file doesn't list them, and drops them only with the `**Void:** code health` line (`~/.claude/CLAUDE.md` → "Shared goal").
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ paths:
|
||||
| 5 | — | — | irreversible: data lost for good, or a one-way door |
|
||||
|
||||
- **I's reach counts every project and session that runs the change.** A change to a hook or a tool that every session runs is I level 3, every consumer affected, even where one person uses it.
|
||||
- **Name in Moves each goal in `README.md` → `## Goals` the item moves, and how far,** from 1 to 10, judged by its value to the audience in `## Audience`: `1.1 by 8, 1.2 by 5`. Where the item moves code health, the goal in `CLAUDE.md` → "Shared goal", name it as in `code health by 6`, unless the README voids it. Name the most specific goal it moves, and a parent goal only for a move none of its sub-goals covers, never beside its own sub-goal. Name a maintain goal only where the item adds a test, a gate leg or a probe that fails where the goal breaks, or is a `defect` that restores it. For the test, gate leg or probe, the move is how much more confident the project becomes that the goal holds, judged against the confidence it already has: 9 or 10 where nothing yet shows the goal holds, about 5 where the item guards something new in an area mostly covered, 1 where it adds another way to check what is already checked. After one such item lands, judge the next against the new confidence. For a defect, the move is how much of the goal is broken. A change that only claims the goal doesn't move it. `rank_todo.py --help` says how it weighs each goal.
|
||||
- **Name in Moves each goal in the goals file's `## Goals` the item moves, and how far,** from 1 to 10, judged by its value to the audience in `## Audience`: `1.1 by 8, 1.2 by 5`. Where the item moves code health, the goal in `CLAUDE.md` → "Shared goal", name it as in `code health by 6`, unless the README voids it. Name the most specific goal it moves, and a parent goal only for a move none of its sub-goals covers, never beside its own sub-goal. Name a maintain goal only where the item adds a test, a gate leg or a probe that fails where the goal breaks, or is a `defect` that restores it. For the test, gate leg or probe, the move is how much more confident the project becomes that the goal holds, judged against the confidence it already has: 9 or 10 where nothing yet shows the goal holds, about 5 where the item guards something new in an area mostly covered, 1 where it adds another way to check what is already checked. After one such item lands, judge the next against the new confidence. For a defect, the move is how much of the goal is broken. A change that only claims the goal doesn't move it. `rank_todo.py --help` says how it weighs each goal.
|
||||
- **A table with C, A, G and Goals in place of L, E, I and Moves is in the old shape.** Reshaping it is the project's only work until done, as `CLAUDE.md` → "Working loop" says, and `rank_todo.py` says how. Until then, A is the item's value to the audience and G its value to the goals it cites.
|
||||
- **Score L, E and I against the project's anchors, and check every score against finished chunks.** Guess the scores, then run `~/.claude/bin/score-outcomes <L> <E> <I> <S>` in the project. It lists the finished items guessed nearest and the project's anchors, the shipped items its `docs/score-anchors.md` names for each level, each with what its chunk measured; then the median outcome at each guessed R and S, and how well L, E and I each order the chunks by review rounds and 🔴 findings, L by the share of chunks with a 🔴 instead where most hold none. Compare the item with each anchor in turn: is it more or less likely to hold a defect, to let one escape, or to do damage? Give it the level whose anchors it matches; where a level has no anchor, judge by the level's words in the table above. Set S to the value guessed for the finished items whose outcome matches what you expect of this one. Keep your guess when no listed item resembles the one you are scoring.
|
||||
- **Anchor each level of L, E and I with two or three items the project shipped,** in `docs/score-anchors.md`: a table whose Level column names a level, such as `L 1`, and whose Items column lists the anchors' IDs, such as `12, 14`. Choose an L anchor whose chunk, as `score-outcomes` measured it, fits the level's words: its lines changed and the components it touched. Choose an E anchor by the level's words and the later fixes `score-outcomes` counts for its chunk, the defects that escaped it. Choose an I anchor by the level's words and what followed its release, since no tool measures I yet. Leave out a level no shipped item shows. Replace a level's anchors when the items scored at it turn out about ten times more likely, or ten times less likely, than its words say: to hold a defect, to let one escape, or to do damage.
|
||||
|
||||
@@ -134,14 +134,14 @@ The release review is a release's last chunk, run once the release holds no item
|
||||
|
||||
### Architecture
|
||||
|
||||
Launch systems-architect: review the whole project as the release leaves it; the decision log carries previously accepted decisions to honor, the README the goals and Stage 0 artifacts. Give it the places per "Comprehension check" → "Places". Each of its other findings names a concrete later change the PR makes harder, such as "a second forge needs edits in four modules"; drop one that names none.
|
||||
Launch systems-architect: review the whole project as the release leaves it; the decision log carries previously accepted decisions to honor, the goals file the goals and audience, the README the Stage 0 artifacts. Give it the places per "Comprehension check" → "Places". Each of its other findings names a concrete later change the PR makes harder, such as "a second forge needs edits in four modules"; drop one that names none.
|
||||
|
||||
- **Stage 0 questions returned**: relay them to the user, record the answers in the README, re-run once.
|
||||
- **Stage 0 questions returned**: relay them to the user, record the goals and audience in the goals file and the rest in the README, re-run once.
|
||||
- **BLOCK** standing after any relaunch ("Rung up"): confirm with the user first when the restructure materially reshapes their PR; until confirmed, no later pass runs.
|
||||
|
||||
### Principles
|
||||
|
||||
Launch one principles-auditor on the trigger in §3, so the project is read once per round. Hand it the README's goals and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless the README voids it, and each file in the config's principles folder (`~/.claude/bin/project-config principles` prints it) whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → hand it the file.
|
||||
Launch one principles-auditor on the trigger in §3, so the project is read once per round. Hand it the goals file's goals, from the header's `Goals and audience:` line, and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, and each file in the config's principles folder (`~/.claude/bin/project-config principles` prints it) whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → hand it the file.
|
||||
|
||||
### Comprehension check
|
||||
|
||||
@@ -199,7 +199,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
|
||||
## 5. Goal alignment, then merge
|
||||
|
||||
1. Read the finished PR against the README goals and code health, unless the README voids it: does anything in it work against one? It breaks a maintain goal → do not merge; redesign the change or drop its item. It works against an achieve goal → do not merge; ask the human, stating the conflict.
|
||||
1. Read the finished PR against the goals file's goals and code health, unless that file voids it: does anything in it work against one? It breaks a maintain goal → do not merge; redesign the change or drop its item. It works against an achieve goal → do not merge; ask the human, stating the conflict.
|
||||
2. Run the comprehension check (§3) where it runs; it runs once. When `origin/<default branch>` moves after that, return to §4, and keep the ruling and scoring run already recorded.
|
||||
3. Remove the chunk's items from `todo.md` per `~/.claude/CLAUDE.md` → "Working loop" in the branch, commit and push that; the commit re-enters no pass.
|
||||
4. Aligned and every pass done → **merge** with `~/.claude/bin/chunk-pr merge`, run in the background, since its wait can outlast the Bash tool's timeout. It waits for the pull request's checks to pass, then takes the first merge method the repository allows on its forge. A repo whose `AGENTS.md` names another method merges that way with the forge's CLI instead, once the pull request's checks pass and `~/.claude/bin/larv-review scoring-run-owed` exits 0. A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
|
||||
|
||||
@@ -12,7 +12,6 @@
|
||||
|
||||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 346 | 0.10.0 | | | **Read a project's goals and audience from the file its config names, in place of `README.md`'s `## Goals` and `## Audience`.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 6 | 2.0 |
|
||||
| 344 | 0.10.0 | | | **Read and write the plan, `AGENTS.md`, the records and the changelog at the paths a project's config names, in every tool, prompt, rule and skill.** | 4 | 2 | 3 | 7 | 6 | 1.6 by 7 | 0.9 |
|
||||
| 345 | 0.10.0 | 344 | | **Commit each change a chunk makes to a plan or record outside the checkout into the project's `~/.claude-projects/<key>/` repo, titled like the chunk's own commits.** | 3 | 2 | 3 | 6 | 4 | 1.6 by 4 | 1.1 |
|
||||
| 348 | 0.11.0 | | | **Read each project's credentials from the env file its config names, fail naming each missing key, and keep every value out of prompts, transcripts, logs and the archive.** | 2 | 2 | 4 | 6 | 3 | 1.6 by 2, 4 by 5 | 6.9 |
|
||||
@@ -23,7 +22,7 @@
|
||||
| 350 | 0.11.0 | 344 | | **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.** | 4 | 2 | 3 | 7 | 7 | 1.6 by 4, code health by 2 | 1.1 |
|
||||
| 349 | 0.11.0 | | | **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.** | 2 | 1 | 2 | 3 | 2 | 1.6 by 3 | 1.1 |
|
||||
| 351 | 0.11.0 | 348, 349, 350 | | **Read a project's plan from the child issues of a Jira Cloud epic its config names, ranked in Jira's backlog order.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 6 | 1.2 |
|
||||
| 353 | 0.11.0 | 346, 351 | | **Let a project's config take its goals and audience from a Jira epic's description, under the same two headings.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 4 | 1.3 |
|
||||
| 353 | 0.11.0 | 351 | | **Let a project's config take its goals and audience from a Jira epic's description, under the same two headings.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 4 | 1.3 |
|
||||
| 358 | 0.11.0 | | | **Let a project's config allow its runtime and tests on the host, and set the comprehension floor that marks code health very important.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 4 | 1.3 |
|
||||
| 362 | 0.11.0 | 348 | | **Send loop-claude's notices through the notifier a project's config names, with Mattermost as the first backend.** | 2 | 1 | 2 | 3 | 3 | 1.6 by 3 | 1.0 |
|
||||
| 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 |
|
||||
@@ -89,10 +88,6 @@
|
||||
|
||||
## Details
|
||||
|
||||
### 346. Read a project's goals and audience from the file its config names, in place of `README.md`'s `## Goals` and `## Audience`.
|
||||
|
||||
lilleman's call, 2026-11-12: for a client project, goals and audience live in a file of their own in `~/.claude-projects/<key>/`, with the same `## Goals` and `## Audience` headings and the same rules (`rules/goals-and-audience.md`), which must then load for that file too. A project reads only its own premises, never a parent project's. Every reader uses the configured file: loop-claude's prompts and judge, `rank_todo.py`'s goal weights and Moves check, larv-review's principles pass, the comprehension panel, and the places in `CLAUDE.md` that say `README.md`. A legacy project whose comprehension score would pull its plan towards refactoring can void code health in that file with the `**Void:**` line, as a README can today.
|
||||
|
||||
### 344. Read and write the plan, `AGENTS.md`, the records and the changelog at the paths a project's config names, in every tool, prompt, rule and skill.
|
||||
|
||||
Today about 40 modules, and `CLAUDE.md`, `rules/` and the skills, name `todo.md`, `AGENTS.md`, `docs/decisions.md`, `docs/score-anchors.md`, `docs/comprehension-history.md`, `docs/reading-cost.md` and `CHANGELOG.md` as files at the checkout's root. Among them are `rank_todo.py`, `todo-item`, `chunk-preflight`, loop-claude's routing, chunk items, judge records and prompts, larv-review, loop-inbox, `release_plan`, `subagent-rung` and `reviewer_context.principles_line`. After this item each of them uses the configured path. Agents get the path in the prompts and in the output of `todo-item` and `chunk-preflight`. Keep each file's name, so `rules/todo-items.md` and `rules/decisions.md` still load by their `paths:` patterns wherever the file lives.
|
||||
|
||||
Reference in New Issue
Block a user