Answer prose round 1: 1 🔴, 7 🟡 (0 misread); state principle 6 as the code runs it, call them project principles, ask on every principle change
CI / tests (pull_request) Successful in 2m7s

This commit is contained in:
2026-11-11 16:07:06 +01:00
parent 84d23fa95c
commit 6d6876fbcf
4 changed files with 13 additions and 13 deletions
+9 -9
View File
@@ -1,18 +1,18 @@
# Working here
## Principles
## Project principles
Each principle states one rule that the decisions in `docs/decisions.md` apply; the entries there hold the specifics and the evidence.
Each project principle states one rule that the decisions in `docs/decisions.md` apply; the entries there hold the specifics and the evidence. The numbers name the principles, and don't rank them.
1. **Cut cost only where a measurement of archived chunks shows quality holds.** Chunk bundling, the round cap, which fixes rerun a pass, the review a Markdown-only branch gets, the passes kept for the release review, review opt-outs, the security pass, compaction and the routing ladder all apply it.
2. **A measurement files or ranks work, and never blocks a merge.** The comprehension floor and check, and a reading-cost rise, apply it. A merge waits on a scoring run the plan calls only until the run is recorded, whatever it scores.
3. **Each file has one writer.** `~/.claude/loop-claude-models.json` is loop-claude's, `~/.claude.json` is Claude Code's, `~/.claude` moves only through `deploy-release`, and each pass has a reviewer of its own. The exception is `~/.claude/settings.json`, which Claude Code writes from any session: git's clean filter `bin/settings_filter.py` keeps each machine's model and Claude Code's key order out of every commit, and a working rule below carries the rest into this repo.
1. **Cut cost only where a measurement of archived chunks shows quality holds.** Chunk bundling, the round cap, which fixes rerun a pass, a reviewer of its own for each pass, the review a branch changing only Markdown no agent follows gets, the passes kept for the release review, review opt-outs, the security pass, compaction and the routing ladder all apply it.
2. **A measurement files or ranks work, and never blocks a merge.** The comprehension floor and check, and a reading-cost rise, apply it. A merge waits on a scoring run the plan calls for only until the run is recorded, whatever it scores.
3. **Each file has one writer.** `~/.claude/loop-claude-models.json` is loop-claude's, `~/.claude.json` is Claude Code's, and `~/.claude` moves only through `deploy-release`. The exception is `~/.claude/settings.json`, which Claude Code writes from any session. Git's clean filter `bin/settings_filter.py` keeps each machine's model and Claude Code's key order out of every commit, and the working rule on `~/.claude/settings.json` below carries its other changes into this repo.
4. **A rule a program can check is enforced by a program, and reviewers rule on the rest.** rule-hook and its overrides, `docker-run-memory`, the refused writes of reviewers under `agents/`, and CI with `main`'s branch protection apply it.
5. **A chunk can't vouch for itself.** Only a precedent the repo held before the chunk began, a review pass or the human approves what a chunk writes: an unanswered ask leaves the PR unmerged, the human approves the premises chunk and runs `deploy-release --cut`, and the judge holds a chunk open while an answer the human typed is recorded nowhere.
6. **An unattended run never waits on a prompt, and a lasting failure stops it.** Every claude loop-claude starts runs in auto mode with permissions bypassed inside its sandbox and `CLAUDE_CODE_SANDBOXED` set; a failed archive stops the loop, and a `claude` that cannot start, as during an update, is retried.
7. **One word names one thing, and one rule has one home.** The `bin/` vocabulary, `CLAUDE.md` holding only the rules no path can scope, and the `rules/` files loaded by their `paths:` apply it.
5. **A chunk can't vouch for itself.** What a chunk writes is approved by a review pass, by the human, or by a precedent the repo held before the chunk began. So an unanswered ask leaves the PR unmerged, the human approves the premises chunk and runs `deploy-release --cut`, and the judge holds a chunk open while an answer the human typed isn't recorded anywhere.
6. **An unattended run never waits on a prompt, and a lasting failure stops it.** Every claude loop-claude starts bypasses permissions inside its sandbox, each claude it or loop-inbox opens on a terminal has `CLAUDE_CODE_SANDBOXED` set, and interactive sessions run in auto mode with the dangerous-mode prompt skipped. A failed archive stops the loop, while a `claude` that cannot start, as during an update, is retried.
7. **One word names one thing, and one rule has one home.** In `bin/`, an outcome is an entry of a `.outcomes.md` file in loop-claude's archive, a record is a document tools or people keep entries in, and a place is what a comprehension seat names. `CLAUDE.md` holds only the rules no path can scope, and each `rules/` file loads by its `paths:`.
## Decisions no principle covers
## Decisions no project principle covers
- bin/: the tools run on the host's Python, with no container, and so do their tests outside CI
- bin/: the tools support only the latest stable Python, and the tests, written in plain unittest, run on it in four pytest-xdist workers
+1 -1
View File
@@ -10,7 +10,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **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 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. `AGENTS.md` lists the project's principles and the title of each decision no principle covers. Read an entry in `docs/decisions.md` only where the principle or title leaves open what the chunk or the review needs.
- **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. `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.
+2 -2
View File
@@ -6,8 +6,8 @@ paths:
# Decisions: one home, each linked to a goal or a technical principle
**The decision log has one home: `docs/decisions.md`**. A title states the whole decision in one line: what holds at the commit it ships in, in words a reader finds in the code or the plan. `AGENTS.md` lists the project's principles and the title of each decision no principle covers, so a session works by the decisions without loading their background. The entry holds the background: its date, who made it, the reasoning, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies.
**The decision log has one home: `docs/decisions.md`**. A title states the whole decision in one line: what holds at the commit it ships in, in words a reader finds in the code or the plan. `AGENTS.md` lists the project principles and the title of each decision no project principle covers, so a session works by the decisions without loading their background. The entry holds the background: its date, who made it, the reasoning, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies.
**Every decision links to a goal or a technical principle.** An entry names the goal it serves or the technical principle under `~/.claude/principles/` it applies; one that can do neither is a missing goal, and an entry already in the repo with neither behind it is a finding. Propose the goal, never a reason of your own — `~/.claude/CLAUDE.md` → "Working loop", "Ask, don't guess" says how. An entry working against a goal or a technical principle stands only while it names the `todo.md` item that ends it.
**Check each new decision against the project's principles.** A principle, listed in the project's `AGENTS.md` under `## Principles`, states one rule that several decisions apply. Each time a decision is recorded, ask three things: does a principle already cover it, does it break one, does it apply the same rule as decisions already listed? A decision a principle covers adds no title to `AGENTS.md`. A rule it shares with listed decisions is a new principle, which covers them too: once the human approves it, their titles leave `AGENTS.md`, so a project distils its principles as its decisions land. A break, a new principle, or a change to one is the human's: ask, unless the evidence is overwhelming, and leave the principles as they are until the human answers. A break questions both sides: either the principle or the decision is wrong.
**Check each new decision against the project's principles.** A project principle, listed in the project's `AGENTS.md` under `## Project principles`, states one rule that several decisions apply. Each time a decision is recorded, ask three things. Does a project principle already cover it? Then it adds no title to `AGENTS.md`, and needs no ask. Does it break one? Then either the principle or the decision is wrong. Does it apply the same rule as decisions already listed? Then that rule is a new project principle, which covers those decisions too. A break, a new project principle or a change to one is the human's: ask, with your recommendation, and leave the project principles as they are until the human answers. Once the human approves a new one, the titles it covers leave `AGENTS.md`.
+1 -1
View File
@@ -6,7 +6,7 @@ The reader is a competent reader of THIS codebase. A comment or a paragraph earn
## Where a choice goes
**A choice that shapes what the code does, made in one place, is a comment there, with its reason. Made in more than one place, it is a decision, and the decision log owns it.** A decision's rejected alternative, or what it deliberately does not cover, stays out of every call site. A choice found anywhere else — an `AGENTS.md` body, a comment away from the code it governs, or a README section that is neither a goal nor how one is met — moves: to a comment at its one place, or, once made in more than one place, to `docs/decisions.md`, leaving its title in `AGENTS.md`'s list unless a principle there covers it.
**A choice that shapes what the code does, made in one place, is a comment there, with its reason. Made in more than one place, it is a decision, and the decision log owns it.** A decision's rejected alternative, or what it deliberately does not cover, stays out of every call site. A choice found anywhere else — an `AGENTS.md` body, a comment away from the code it governs, or a README section that is neither a goal nor how one is met — moves: to a comment at its one place, or, once made in more than one place, to `docs/decisions.md`, leaving its title among `AGENTS.md`'s decision titles unless a project principle there covers it.
## Comments