Answer product-owner round 1: 1 🔴, 5 🟡 (1 misread); an absent item is named, an approved pull request answers its comments first, and todo-item keeps its own checks
This commit is contained in:
@@ -107,7 +107,7 @@ A project's config may set four more things, each optional, as `project-config -
|
||||
|
||||
A legacy project with no container setup sets `tooling-on-host = true`, so the loop runs its language runtime, package manager, tests and task runner directly on the host. One whose code the comprehension panel scores low may lower `readability-floor` from 7.0: under it, the ranking weighs code health 4 times as much, and a scoring run asks for a floor item.
|
||||
|
||||
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
|
||||
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer, on an approved pull request too; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
|
||||
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
|
||||
|
||||
@@ -162,7 +162,7 @@ It renames `## Unreleased` in `CHANGELOG.md` to the version and merges that thro
|
||||
|
||||
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`.
|
||||
|
||||
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks; once it is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
|
||||
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks; once the pull request is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
|
||||
- `chunk-preflight` finds the mechanical facts a chunk starts from, and with `--worktree` makes its worktree; `loop-claude` runs it with `--worktree` before it routes each chunk, and `chunk-preflight --help` lists the facts.
|
||||
- `command-patterns [<version>] [--calls <file>]` prints a table of the shell command patterns a release's archived chunks ran, such as `tea pr create`, for an audit of the release, and with `--calls <file>` saves each call as a JSON line; `command-patterns --help` states the columns and the line's keys.
|
||||
- `deploy-release [--cut] [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says; with `--cut`, run in the development clone, it first cuts the next release, as Release says.
|
||||
|
||||
+8
-7
@@ -81,14 +81,15 @@ Valid while the archive's file names, the Vocabulary and the panel keep these wo
|
||||
|
||||
## chunk-pr: the chunks of a project merge one at a time on a machine, each finishing its plan items in its turn, and a pull request that waits for an approval leaves the queue while it waits
|
||||
|
||||
2026-11-15, lilleman's call of 2026-11-13 in item 374, which split item 361. Serves goals 1.5 and 1.4: with several chunks open, every chunk removed its item from `todo.md` and added a bullet to `CHANGELOG.md` in its branch, so each merge left the others a conflict, a gate rerun and often a review round. `chunk-pr merge --finish <ID>` now makes those edits in the chunk's turn, on top of every chunk merged before. The worker's choices, for what the call left open:
|
||||
2026-11-15, lilleman's call of 2026-11-13 in item 374, which split item 361. Serves goals 1.5 and 1.4: with several chunks open, every chunk removed its item from `todo.md` and added a bullet to `CHANGELOG.md` in its branch, so each merge left the others a conflict, a gate rerun and often a review round. `chunk-pr merge --finish <ID>` now makes those edits in the chunk's turn, on top of every chunk merged before. The worker's choices follow. The first differs from the call, and the rest settle what it left open:
|
||||
|
||||
- **A merge of the default branch, where the call said rebase.** A rebase rewrites commits the pull request already shows. The forge then drops the approval and the review threads' places, and the round titles rule-hook counts on the branch get new commits. `chunk-pr sync` already merges, and the turn reuses it.
|
||||
- **The queue is a file in the git folder the checkout's worktrees share**, held with flock for the turn (`bin/chunk_pr/main.py` → `QUEUE`). Every chunk of the project on the machine finds it without a config or a key. Two machines don't share it: there the forge refuses the second merge, whose head lacks the first, and its next run merges the first in.
|
||||
- **A merge of the default branch, where the call said rebase.** A rebase rewrites commits the pull request already shows. The forge then drops the approval and the review threads' places. rule-hook counts a pass's rounds by the branch's commit titles, and a rebase gives each of those commits a new hash. `chunk-pr sync` already merges, and the turn reuses it.
|
||||
- **The queue is a file in the git folder the checkout's worktrees share**, held with flock for the turn (`bin/chunk_pr/main.py` → `QUEUE`). Every chunk of the project on the machine finds it without a config or a key. Two machines don't share it: there the second chunk merges without the first one's changes in its head, unless the branch protection requires an up-to-date branch. A turn lasts as long as its checks, which chunk-pr waits 30 minutes for on Gitea. So a merge waits 30 minutes for its turn, then fails naming the pull request that holds the queue, whose number the holder writes into the file.
|
||||
- **The turn holds the queue through the checks**, so what merges is what the checks ran on. A project without forge checks waits the minute `chunk-pr --help` names.
|
||||
- **The wait for an approval is outside the turn.** The first turn pushes the finished branch, so the approver reads what merges. Once approved, the pull request takes a new turn. Where the default branch moved meanwhile, that turn merges it in, and a branch protection that dismisses approvals on a push asks the approver again.
|
||||
- **A reviewer's comment ends the wait, in place of the loop watching for one.** `chunk-pr merge` runs in the worker's own session, so its failure is what resumes the worker, which answers and runs it again. A comment that waits is a review thread nobody resolved whose last comment someone other than the pull request's author wrote: the worker answers as that author, so an answered thread waits for the reviewer again. A comment outside a thread doesn't end the wait, since bots write those too.
|
||||
- **A paired ruling runs again after a turn merged the default branch in**, on the last measured commit as before: `review: the comprehension check records …` says why the base stays. `chunk-pr merge` stops once to ask for it, and its next run merges whether or not a ruling was added, since no ruling blocks a merge (project principle 2).
|
||||
- **The wait for an approval is outside the turn.** The first turn pushes the finished branch, so the approver reads what merges. Once approved, the pull request takes a new turn. Where the default branch moved meanwhile, that turn merges it in, and a branch protection that dismisses approvals on a push asks the approver again. A finish that fails is pushed with whatever the turn merged in, so the pull request's head stays the commit checked out. `larv-review scoring-run-owed` runs after the finish is committed, since it counts as shipped the items the committed plan no longer holds.
|
||||
- **A reviewer's comment ends the wait, in place of the loop watching for one.** `chunk-pr merge` runs in the worker's own session, so its failure is what resumes the worker, which answers and runs it again. A comment that waits is a review thread nobody resolved whose last comment someone other than the pull request's author wrote: the worker answers as that author, so an answered thread waits for the reviewer again. A comment outside a thread doesn't end the wait, since bots write those too. An approved pull request with such a thread stays unmerged too: a client's reviewer who approves and asks for one more thing gets an answer first.
|
||||
- **A paired ruling runs again once the default branch has moved past it**, on the last measured commit as before: `review: the comprehension check records …` says why the base stays. `chunk-pr merge` stops while the default branch holds commits the branch's last commit of a ruling doesn't, whoever merged them in: the turn, `chunk-pr sync` or the worker after a conflict. What the ruling says never stops the merge (project principle 2). A scoring run reads no base, so it stays.
|
||||
- **An item the plan doesn't hold is named on merge's last line, not refused.** chunk-pr cannot tell an item an earlier run finished from a mistyped ID, so the reader does. Such a run still commits the plan and the changelog, since the earlier run may have stopped between `todo-item finish` and its commit. chunk-pr checks that an ID is a number before its turn, and leaves every other rule of `todo-item finish` to that tool.
|
||||
|
||||
Valid while a chunk's worker runs `chunk-pr merge` itself, and one machine runs a project's loops.
|
||||
|
||||
@@ -402,7 +403,7 @@ The base is the last measured commit: the default branch's newest merged change
|
||||
|
||||
2026-11-11, lilleman. Serves goal 1.1. Item 296 made `chunk-pr merge` refuse while a scoring run the plan calls is unrecorded on the branch, so a missing run can block a merge. No score or ruling does, and the titles say so: "no score blocks a merge".
|
||||
|
||||
2026-11-15, the worker's choice in item 374, which lilleman's call of 2026-11-13 left open. The call asked that a ruling never charge one chunk with another's change, by reading against the new base after a rebase. Only the release review runs a paired ruling, and it measures the whole release, so its base stays the last measured commit. What another chunk's merge changes is the head: a ruling recorded before the merge came in read a head that never merges. So `chunk-pr merge` stops where its turn merged the default branch into a branch that has recorded a comprehension check, and the worker runs the ruling again at the new head.
|
||||
2026-11-15, the worker's choice in item 374, which differs from lilleman's call of 2026-11-13. The call asked that a ruling never charge one chunk with another's change, by reading against the new base after a rebase. Only the release review runs a paired ruling, and it measures the whole release, so its base stays the last measured commit. What another chunk's merge changes is the head: a ruling recorded before the merge came in read a head that never merges. So `chunk-pr merge` stops where the default branch has moved since the branch last recorded a paired ruling, and the worker runs the ruling again at the new head.
|
||||
|
||||
## review: the premises chunk's whole review is the human's approval
|
||||
|
||||
|
||||
@@ -145,7 +145,7 @@ Launch one principles-auditor on the trigger in §3, so the project is read once
|
||||
|
||||
### Comprehension check
|
||||
|
||||
The comprehension check records how hard the project is for its contributor to read (`~/.claude/rules/goals-and-audience.md`), and no score blocks a merge; only a run the plan calls and the branch lacks does, per "Scoring run". Simulated readers, the seats, launched per `~/.claude/skills/comprehension-panel/SKILL.md`, each read the whole project, not the diff. It reports no findings and is no pass: it runs once, in §5, after every pass is done, the auto-reviewer included, so it reads the branch as review left it. It runs a paired ruling in the release review, even where an opt-out skips its architect, and a scoring run where one is due. It skips only as "Opt-out" or "Suspended" below says.
|
||||
The comprehension check records how hard the project is for its contributor to read (`~/.claude/rules/goals-and-audience.md`), and no score blocks a merge; only a run the plan calls and the branch lacks does, per "Scoring run". Simulated readers, the seats, launched per `~/.claude/skills/comprehension-panel/SKILL.md`, each read the whole project, not the diff. It reports no findings and is no pass: it runs in §5, after every pass is done, the auto-reviewer included, so it reads the branch as review left it. It runs a paired ruling in the release review, even where an opt-out skips its architect, and a scoring run where one is due. It skips only as "Opt-out" or "Suspended" below says.
|
||||
|
||||
**Paired ruling.** Each seat votes whether the project reads better, the same or worse at this branch's head than at the base.
|
||||
|
||||
@@ -200,11 +200,12 @@ 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 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 scoring run already recorded. A paired ruling read the head before the other chunk's merge came in, so run it again at the new head and record it.
|
||||
2. Run the comprehension check (§3) where it runs. When `origin/<default branch>` moves after that, return to §4, and keep the scoring run already recorded. Where the chunk recorded a paired ruling, run it again at the new head and record it: it read the head before the other chunk's merge came in.
|
||||
3. Run `~/.claude/bin/touch-predictions record <ID>...` in the worktree, naming the chunk's items: it records what they were predicted to touch beside what the branch touched, where the project's config names that record. A later pass through this step, after a return to §4, skips it. Commit and push it; the commit re-enters no pass. Leave the chunk's items in the plan, and write no changelog bullet in the branch: step 4 does both, so that `todo.md` and `CHANGELOG.md` never conflict between chunks. Revise any decision that cites an item now, since `todo-item finish` refuses while one does.
|
||||
4. Aligned and every pass done → **merge** with `~/.claude/bin/chunk-pr merge`, run in the background with its `timeout` set to 7200000 ms, since its wait can outlast the Bash tool's default. Give it one `--finish <ID>` per item the chunk ships, each with the arguments `~/.claude/CLAUDE.md` → "Working loop" asks of `todo-item finish`, as in `chunk-pr merge --finish 12 --changelog '<bullet>' --finish 13 --no-changelog`. The project's chunks merge one at a time. In its turn, `chunk-pr merge` merges `origin/<default branch>` into the branch, finishes those items, pushes, and waits for the pull request's checks to pass; then it takes the first merge method the repository allows on its forge. Where it stops, do what it asks and run it again with the same arguments:
|
||||
4. Aligned and every pass done → **merge** with `~/.claude/bin/chunk-pr merge`, run in the background with its `timeout` set to 7200000 ms, since its wait can outlast the Bash tool's default. Give it one `--finish <ID>` per item the chunk ships, each with the arguments `todo-item finish` takes (`todo-item --help`), as in `chunk-pr merge --finish 12 --changelog '<bullet>' --finish 13 --no-changelog`. The project's chunks merge one at a time. In its turn, `chunk-pr merge` merges `origin/<default branch>` into the branch, finishes those items, pushes, and waits for the pull request's checks to pass; then it takes the first merge method the repository allows on its forge. Where it stops, do what it asks and run it again with the same arguments:
|
||||
- **A merge conflict.** Resolve it, commit and push. Rerun only the passes whose triggers the resolution's own lines meet (§3), each in a round of its own.
|
||||
- **A paired ruling to run again**, as step 2 says.
|
||||
- **A paired ruling to run again.** `chunk-pr merge` has merged the default branch in and pushed. Run the ruling at that head, record it, commit and push. Don't return to §4 for it: the next turn waits for the checks at the new head.
|
||||
- **An owed scoring run, or a queue another pull request holds.** Record the run, or wait, as the message says.
|
||||
- **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. The wait doesn't hold the queue, so other chunks merge meanwhile.
|
||||
|
||||
A repo whose `AGENTS.md` names another method merges that way with the forge's CLI instead, after it finishes the chunk's items with `todo-item finish` in the branch, and once the pull request's checks pass, `~/.claude/bin/larv-review scoring-run-owed` exits 0 and, where `~/.claude/bin/project-config wait-for-approval` prints `true`, GitHub reports the pull request approved. A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
|
||||
|
||||
Reference in New Issue
Block a user