Merge remote-tracking branch 'origin/main' into item-441

This commit is contained in:
2026-11-19 01:37:46 +01:00
4 changed files with 43 additions and 9 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- Describe do-epic in the README: its entry under Tools, and its machine settings and `repo-rule.md` under Set up a project.
- do-epic finishes an epic: once none of its issues is open, a finishing chunk files a release review of each repo the epic changed, as an issue labelled `do-epic-release-review`, and asks you to confirm each goal. `do-epic <EPIC-KEY> --close-epic` then posts the summary piped in as a comment on the epic and closes it in Jira, by the transition `jira-finish-transition` names, to the status `jira-finish-status` names.
- do-epic parks a chunk whose pull request waits on its checks, an approval or a new review: the chunk frees its place for the next one, its tmux window says what it awaits, and its worker goes on when the gate opens or a reviewer comments, even after a reboot. `do-epic <EPIC-KEY> --status` prints what each open issue does.
- A chunk that `do-epic` runs files a finding about an epic goal as an issue of the epic, with `do-epic <EPIC-KEY> --file`, and records a decision in the epic's description, with `--record-decision`; its judge reads the epic's Scoring and Decisions before the repo's records.
+8
View File
@@ -150,6 +150,13 @@ cd ~/code/acme-billing && ~/.claude/bin/project-config
The last line prints each setting's path once the config is complete.
`do-epic` keeps its settings per machine, not per project, in `~/.claude-projects/do-epic/`, two files for every epic:
- `config.toml` sets `jira-url`, the site, such as `https://acme.atlassian.net`; `env-file`, the file holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, a path that starts with `/` or `~/`, outside the clone folder and every folder of `~/.claude-projects`; and `repoless-model`, the model that works an item with no repo. It may also set `clone-folder`, where a missing repo is cloned, `~/code` if left out; `language`, the language of Jira text, English if left out; and `jira-finish-transition` with `jira-finish-status`, which name the workflow transition that closes a finished epic and the status it leads to, such as `"Mark as done"` and `"Done"`. Set both or neither: without them do-epic closes no epic.
- `repo-rule.md` is prose that says how to tell an item's repo, such as "a label that equals a repo's name names that repo". It may not be blank. do-epic doesn't read it yet: until it picks each item's repo from the rule, an issue runs once a label `repo:<name>` records its repo, `do-epic-claude` marks work of Claude's that changes no repo, and `do-epic-human` a task of yours.
Each repo an epic changes has a project config of its own, as in the rest of this section. `do-epic` fails and names each setting or file that is missing or invalid.
A project runs on the routing ladder this setup ships, `bin/model_routing/routing-ladder.json`: the rungs, least competent first, each a model at an effort, that loop-claude routes workers, subagents and reviews to. To run one project on other rungs, as when an outage or a client's account leaves it fewer models, copy that file to `~/.claude-projects/<key>/routing-ladder.json` and cut or change its rungs. Keep one model for each family, such as opus: Claude Code launches a subagent by its family's name. The project's file replaces the shipped ladder whole. loop-claude reads it as each cycle starts, and `subagent-rung` and rule-hook each time they run. The loop never commits it, so commit it in the folder's repo yourself only where it should last. Set the project's models to ones its ladder holds, for example with `LOOP_CLAUDE_WORKER_MODEL` and `LOOP_CLAUDE_JUDGE_MODEL`. A model off the ladder is not routed: every worker runs on that model, at the effort Claude Code's `settings.json` gives. Each cycle of a project on a ladder of its own says so on stderr, naming the file, and says where the worker's model is off it. `loop-claude --help` shows the file's shape.
## Update
@@ -183,6 +190,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `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.
- `compress-archives` gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them; Install's crontab line runs it daily.
- `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.
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. An open issue runs once a label names its repo, in Jira's backlog order, as many at once as a line such as `**Max parallel chunks:** 2` in the epic's description allows, 1 without it, and as each repo's `parallel-chunks` allows. A chunk whose pull request waits on a gate parks. do-epic closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
- `judge-replay <model> [--offline]` replays loop-claude's judge on archived verdicts of the projects run on the model. It prints what each rung a review climbs to misses, and the lowest rung below those that returns every verdict, as each candidate above it does. With `--offline` it doesn't call a judge: it counts what a "?" rule, a decision table and a classifier trained on the archive decide of each verdict's kind from the worker's final message, and how many interrupts each misses. `judge-replay --help` states both replays.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
- `loop-claude <task>` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract.
+31
View File
@@ -2927,3 +2927,34 @@ Read most (opens and searches):
- `bin/do_epic/epic_record.py` 1
- `bin/loop_claude/project/premises.py` 1
- `bin/loop_claude/project/records.py` 1
## Reading cost, chunk d77b99fcaa22, finished 2026-11-18T23:16:50Z
112582 new input tokens before the first commit.
Read most (opens and searches):
- `bin/do_epic/main.py` 7
- `bin/forge/pulls.py` 4
- `bin/chunk_pr/approval.py` 3
- `bin/chunk_pr/main.py` 3
- `bin/do_epic/scheduler.py` 3
- `rules/todo-items.md` 3
- `README.md` 2
- `bin/agent_cycle/tmux.py` 1
- `bin/do_epic/chunk_prompt.py` 1
- `docs/decisions.md` 1
## Reading cost, chunk 12edf0c9126c, finished 2026-11-19T00:27:34Z
96788 new input tokens before the first commit.
Read most (opens and searches):
- `bin/do_epic/main.py` 4
- `rules/todo-items.md` 3
- `bin/do_epic/backend/protocol.py` 1
- `bin/do_epic/chunk_prompt.py` 1
- `bin/do_epic/scheduler.py` 1
- `bin/plan_store/jira_epic.py` 1
- `bin/release_plan/release_standing.py` 1
+3 -9
View File
@@ -14,7 +14,6 @@
|---|---|---|---|---|---|---|---|---|---|---|---|
| 441 | 0.12.0 | | | **Move an epic's issue to done in Jira when its chunk finishes, so no finished chunk starts again and what it blocks starts.** | 2 | 2 | 2 | 4 | 3 | 1 by 6 | 2.3 |
| 416 | 0.12.0 | | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 418 | 0.12.0 | | | **Describe do-epic in `README.md`'s tools and setup, with its machine settings and `repo-rule.md`.** | 1 | 2 | 1 | 2 | 2 | 1 by 5 | 2.1 |
| 420 | 0.12.0 | | | **End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.** | 2 | 2 | 2 | 4 | 3 | 1.5 by 6 | 2.0 |
| 412 | 0.12.0 | | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
@@ -94,14 +93,6 @@ Touches:
- `bin/do_epic/main.py`
### 418. Describe do-epic in `README.md`'s tools and setup, with its machine settings and `repo-rule.md`.
Each chunk keeps the README true for what it changes; this item writes the overview a new reader needs (`docs/decisions.md` → `do-epic: drives one Jira epic …`).
Touches:
- `README.md`: `## Tools`, `### Set up a project` (small)
### 420. End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.
On 2026-11-18 the worker of the item 402 chunk merged its pull request at about 11:47, printed its summary and then waited 95 minutes: it had started `until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done` in the background, and `pgrep -f` matched the loop's own command line, so the condition never held. Its `claude -p` stayed alive ("Waiting for background work to finish"), `loop-claude` waited for it to exit, and the window's slot started no new chunk until the human found it and killed the shell.
@@ -159,11 +150,14 @@ Touches:
Today `do-epic <EPIC-KEY>` starts only an issue whose label already records its repo, and prints that every other one waits (`bin/do_epic/scheduler.py` → `chunks`). `split.split`, `repo_pick.picked` and `ranking` exist and nothing calls them. Each is a headless claude call on a rung: route it on `repoless-model`'s rung of the shipped ladder. An `Unclear` pick is an interrupt on the terminal of the `do-epic <EPIC-KEY>` the human runs. A chunk that finishes starts the next chunks without planning again, so no window waits on a question.
The README says today that do-epic doesn't pick or rank by itself (`README.md` → `## Tools`, `### Set up a project`); this item makes both true, so it rewords those two passages.
Touches:
- `bin/do_epic/main.py`: `windows_opened`, `chunks_started`
- `bin/do_epic/planning.py`
- `bin/do_epic/test_main.py`
- `README.md`: `## Tools`, `### Set up a project` (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.