File item 429: lessons from a client setup for the principles, reviewers and larv-review #614

Merged
lilleman merged 4 commits from plan-team-principles into main 2026-11-18 17:58:25 +01:00
+29 -1
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 429`
`Next ID = 439`
## Items
@@ -28,6 +28,7 @@
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 421 | 0.12.0 | | | **Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 4 | 1.3 |
| 316 | 0.12.0 | | | **Launch comprehension seats as an agent type of their own under `agents/`, without `CLAUDE.md` and the skill and agent listings a general-purpose subagent carries.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
| 429 | 0.12.0 | | | **Bring nine lessons from a client setup into the principles, the reviewers, larv-review and the project config, and rank a deterministic tool first where an outside reviewer's finding changes the setup.** | 4 | 2 | 3 | 7 | 7 | 1.1 by 5, 1.6 by 5 | 0.9 |
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 422 | 0.12.0 | 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
@@ -285,6 +286,33 @@ Touches:
- `bin/rule_hook/test_rule_hook.py`: `ReviewerRung`
- `bin/larv_review/test_scoring_setup.py`
### 429. Bring nine lessons from a client setup into the principles, the reviewers, larv-review and the project config, and rank a deterministic tool first where an outside reviewer's finding changes the setup.
Lessons from running this setup in a client's repo, shipped as one chunk. Each part names the gap it closes; none names the client, its code or its reviewers' text.
1. **Open the pull request after our own review, where CI runs on pushed branches.** Today larv-review §2 opens a draft first. A forge's auto-reviewer reviews drafts and human reviewers see them, so in a client's chunk about six outside findings landed that our passes would have caught. Nothing in larv-review needs a pull request before the gate: `reviewer-header` prints `PR: none open at the pushed head`, and round counts read commit titles. Push early so CI runs; run `chunk-pr open` once every §3 pass is done and §2's tests, static analysis and mutation tests pass; mark it ready at once. Where CI runs only on pull requests, keep the draft-first order. Decide which from the repo's CI config, and say in the summary which order the chunk took.
2. **Rules for tests on a shared environment**, in the "Tests and tooling" bullet under "Compose, do not entangle", one BANNED/GOOD pair each: assert only on records the test created and can name, never on a count or the first row; never change state the test doesn't own; pass in any order and beside a second copy of itself running at the same time; a helper registers its teardown before it creates anything, keyed by a value it made itself, and the teardown deletes only what it can name; a helper that saves checks what was saved, never the status code alone.
3. **"Make invalid states unrepresentable" gets an example about function inputs.** Its only example is a database time type, so in a client's chunk nobody connected it to a test helper that validated its caller's input, over four review rounds. BANNED: a helper that takes a token and a message, and checks that the message holds the token. GOOD: the helper makes the token and builds the message. Add: "When a review finds a second edge case in a check, change the signature so the input can't occur."
4. **stability-reviewer checks a change that stores a value differently**, in "Data Integrity & Persistence": where a change escapes, converts or grows a stored value, the longest value it can now write must fit the column, and every search, filter or comparison on the column must still find what users type. In a client's chunk, escaping text into a TEXT column lowered its overflow limit fivefold, and a LIKE search stopped matching apostrophes; stability missed both.
5. **A `conventions` setting in the project config**: an optional list of paths, in the other settings' path syntax, such as `checkout:CONVENTIONS.md`. `reviewer-header` prints them, every reviewer reads them beside the principles and standards, and the team's rule wins where they conflict. A missing file fails as an empty principles folder does. Today a team's conventions reach reviewers only by hand.
6. **larv-review §2 files an item to add a mutation tool** when `mutate-changes` prints its line naming changed files no tool covers, or refreshes the item an earlier chunk filed: the language's mutation tool, pinned to a version that supports the project's language version. In a client's PHP repo without one, three findings were surviving mutants a tool would have reported before review.
7. **The principle "Never mock a service your own team runs."** Test the seam to it against its real build, in a harness that runs the real stack; mock only a third party that can't be run locally in a reasonable way. The rule binds the test that covers the seam: a unit test of the caller's own logic may still use a fake, as "Use real collaborators or fakes" allows.
8. **The principle "Don't loosen a type when refactoring"**, under "Validate data and build DTOs as early as possible.", with one BANNED/GOOD pair: a function that returned a concrete type keeps returning it when its implementation changes, never `object`, `array`, `mixed` or `any`; introduce a DTO or value object instead.
9. **Reflect on every outside reviewer's finding, deterministic tools first.** `CLAUDE.md` → "Working loop" → "Change the setup for each reasonable fix an outside reviewer asked for on a PR" already asks why our review missed it, but ranks reviewer agents and larv-review with the hooks and tools, and covers only fixes. Make it cover every finding an outside reviewer raises, and rank the places: 1. a deterministic tool that would have caught it, such as a rule-hook rule, a gate check, a linter setting or `mutate-changes`; 2. the technical principles or review standards; 3. anything else: the reviewers' agents, `larv-review`'s text, or the project's own settings, principles folder or `AGENTS.md`.
Touches:
- `CLAUDE.md`: `## Working loop` (small)
- `skills/larv-review/SKILL.md`: `## 2. Ship the branch`, `## 4. Gate`, `### Principles` (small)
- `bin/chunk_pr/main.py`: `opened` (small)
- `bin/chunk_pr/test_chunk_pr.py`
- `principles/technical-principles.md`: `Compose, do not entangle`, `Make invalid states unrepresentable.`, `Validate data and build DTOs as early as possible.`, `Most, if not all, code should have automated tests, and each test earns its keep.`
- `agents/stability-reviewer.md`: `### 7. Data Integrity & Persistence` (small), `### 11. Tests` (small)
- `bin/project_config/settings.py`: `SETTINGS`
- `bin/project_config/test_project_config.py`
- `bin/larv_review/reviewer_header.py`
- `bin/larv_review/test_larv_review.py`
- `README.md`: `## Install` (small)
### 310. Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.
281 worker resumes after the 1-hour cache expired rewrote a whole context, $379 of the $9,154 measured from 2026-09-30 to 2026-11-11 (4.1%). A compaction while the cache is warm reads the context at a twentieth of the input price and leaves about 20k tokens to rewrite later.