Merge remote-tracking branch 'origin/main' into item-303
CI / tests (pull_request) Successful in 2m53s

This commit is contained in:
2026-11-17 01:30:19 +01:00
24 changed files with 273 additions and 213 deletions
+2
View File
@@ -51,6 +51,8 @@
!bin/deploy_release/
!bin/deploy_release/*.py
!bin/failure.py
!bin/forge/
!bin/forge/*.py
!bin/git_cli/
!bin/git_cli/*.py
!bin/judge-replay
+4
View File
@@ -1,5 +1,9 @@
# Changelog
## Unreleased
- A plan kept as a Jira epic takes no changelog bullet: `todo-item finish` there needs neither `--changelog` nor `--no-changelog`, and refuses `--changelog`, since the issues' history is the changelog.
## 0.11.0
- `adf_codec.convert` can now convert ADF to markdown and back without losing a block's `localId` or the empty paragraphs Jira uses for spacing, so a Jira or Confluence document read and saved back unedited comes back identical: `markdown_to_adf_lossless`, `adf_to_markdown_lossless` and `adfs_to_markdown_lossless`. No tool calls them yet.
+1 -1
View File
@@ -18,7 +18,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **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 from the plan, 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 item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
- **Remove a finished item from the plan, 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 item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: `finish` there refuses `--changelog`. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
- **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.
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
+4 -4
View File
@@ -190,18 +190,18 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `settings_filter.py` is git's clean filter for `settings.json`: it drops `"model"` and sorts the keys. `.gitattributes` sets the filter `settings` on `settings.json`, and Install's `git config` line makes this script that filter.
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
- `subagent-rung [--plan] <model> <L>` prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model on the project's routing ladder, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
- `todo-item` reads and changes a project's plan, whatever holds it: `list` prints the items in the plan's order and `show <ID>` one item's row and detail; `add …` files an item under the next free ID, `edit <ID> …` sets an item's cells or detail, and `move <ID> --release <version>` sets an item's release; `finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`. Each change ranks a markdown plan. `todo-item --help` states the flags.
- `todo-item` reads and changes a project's plan, whatever holds it: `list` prints the items in the plan's order and `show <ID>` one item's row and detail; `add …` files an item under the next free ID, `edit <ID> …` sets an item's cells or detail, and `move <ID> --release <version>` sets an item's release; `finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`, except for a plan kept in Jira. Each change ranks a markdown plan. `todo-item --help` states the flags.
- `touch-predictions record <ID>...` appends what a chunk's items were predicted to touch, under `Touches:` in their details, beside the files and parts its branch touched, to the record the config names as `touch-predictions`; `touch-predictions --help` shows the spelling and how a part is named. `chunk-preflight` reads the same predictions to name the items that may start chunks at once.
- `wait-for <file> [<pattern>] [--timeout <seconds>]` waits until a file a background job writes holds a line matching the pattern, and prints it.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `atlassian/`, `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, which `repo_checks/test_package_cycles.py` checks.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `atlassian/`, `branch_chunks/`, `claude_code/`, `command_lines/`, `forge/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, which `repo_checks/test_package_cycles.py` checks.
- `adf_codec/` converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back, in a throwaway container running a pinned `@larvit/adf-codec`. It builds the container's image inside a heavy slot.
- `atlassian/` holds what the Jira and Confluence backends share (`client.py`): one Atlassian account's credentials, the request both backends send, and each service's error messages.
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `chunk_pr` imports `deploy_release`'s forge calls, and `forge_of` as `deploy_release` does.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_plan`'s `release_standing`.
- `deploy_release` imports `release_plan`'s `release_standing`.
- `forge/` tells a GitHub origin from a Gitea one and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
- `loop_claude` runs `chunk-preflight` as a process of its own.
+1 -2
View File
@@ -5,8 +5,7 @@ import time
import typing
from failure import Failure
from chunk_preflight.gathered import Forge
from deploy_release.forge import Run
from forge.commands import Forge, Run
# A human answers in hours, so merge polls once a minute and gives up after 90 minutes. That leaves half an hour for the queue and the checks inside the 2 hours a background command may run; a run that needs more is killed before the give-up message prints, and its next run goes on from what it pushed.
POLL_SECONDS = 60
+5 -5
View File
@@ -29,8 +29,9 @@ merge merges the pull request in its turn: the chunks of one project on this
turns, one at a time. Run it in the background. In its turn it:
1. fetches origin and merges its default branch into the branch, as sync does;
2. finishes each plan item a --finish names with `todo-item finish`, passing on
--changelog or --no-changelog, and commits what that changed in the plan and the
changelog, so both change only at merge time, on top of every chunk merged before;
--changelog or --no-changelog (a Jira plan takes no --changelog, as todo-item says),
and commits what that changed in the plan and the changelog, so both change only
at merge time, on top of every chunk merged before;
3. pushes, also where step 2 failed after step 1 brought changes in;
4. waits for the pull request's checks, and those origin's default branch requires, to
pass on the head; where no check reports within a minute, it takes the pull request
@@ -85,10 +86,9 @@ import time
import typing
from chunk_pr.approval import approval, approved, awaited, unanswered
from deploy_release.forge import checks_passed, gitea, merged_pull, open_pull, required_checks, Run, runner
from forge.pulls import checks_passed, merged_pull, open_pull, required_checks
from failure import Failure
from chunk_preflight.gathered import Forge
from chunk_preflight.choices import forge_of
from forge.commands import Forge, forge_of, gitea, Run, runner
from project_config.main import located
from project_config.settings import ProjectConfig
from plan_store.plans import says_no_item
+1 -1
View File
@@ -15,7 +15,7 @@ from chunk_pr.main import cleaned, merged, QUEUE, step, turn, USAGE
from failure import Failure
from test_env import isolated_env
from project_config.settings import ProjectConfig
from deploy_release.forge import Run
from forge.commands import Run
from chunk_pr.approval import THREADS
TOOL = pathlib.Path(__file__).resolve().parents[1] / "chunk-pr"
+1 -5
View File
@@ -1,7 +1,7 @@
"""The pure choices the preflight's steps act on."""
import pathlib
from chunk_preflight.gathered import Forge
from forge.commands import Forge
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": ("tea", "pulls", "list")}
@@ -26,10 +26,6 @@ def worktree_add(branch: str, path: pathlib.Path, default: str, local: bool, pus
return ["worktree", "add", "--quiet", "--no-track", "-b", branch, str(path), default], f"added on the new branch {branch}, made off {default}."
def forge_of(origin_url: str) -> Forge:
return "gh" if "github.com" in origin_url else "tea"
def pulls_command(forge: Forge, branch: str) -> list[str]:
"""The command that lists open pull requests: gh only branch's, by number and URL; tea every one, by index, head and URL, for facts.open_pulls to pick branch's."""
if forge == "gh":
+2 -1
View File
@@ -4,7 +4,8 @@ from touch_predictions.beside import chunks_beside
from release_plan.next_chunk import cut_name, NextChunk, NoItem
from release_plan.release_standing import dated_cut, LastCut, unreleased_entries, UNSEEN_RELEASES
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, Ran
from forge.commands import Forge
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, Ran
from text_files.markdown_text import listed, quoted
from chunk_preflight.choices import PULLS_LIST
from plan.release import version
+1 -4
View File
@@ -1,15 +1,12 @@
"""What the preflight gathers, which facts.render states."""
import dataclasses
import pathlib
import typing
from failure import Failure
from forge.commands import Forge
from release_plan.release_standing import LastCut
from release_plan.next_chunk import NextChunk, NoItem
# The CLI that lists a forge's pull requests: gh for a github.com origin, tea for any other.
Forge = typing.Literal["gh", "tea"]
@dataclasses.dataclass(frozen=True)
class Ran:
+3 -2
View File
@@ -78,13 +78,14 @@ import typing
from git_cli.git_repo import commit_exists, default_branch, file_at, git, top
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, Ran, Worktree
from chunk_preflight.choices import forge_of, pulls_command, worktree_add, worktree_on
from forge.commands import Forge, forge_of
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, Ran, Worktree
from chunk_preflight.facts import JOINING_DETAILS, render
from project_config.main import located
from plan.named_paths import named_paths
from release_plan.next_chunk import NextChunk, NoItem, plan_name, planned
from release_plan.release_standing import project_plan
from chunk_preflight.choices import pulls_command, worktree_add, worktree_on
BIN = pathlib.Path(__file__).resolve().parents[1]
# Each tool run in the item's worktree, {item} standing for the item's ID.
+1 -5
View File
@@ -13,7 +13,6 @@ from project_config.templates import BRANCH
from release_plan.next_chunk import CarriedOver, NoItem
from chunk_preflight import choices
from failure import Failure
from chunk_preflight.choices import forge_of, worktree_add
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, Ran, Worktree
from test_env import isolated_env
from release_plan.release_standing import LastCut, UNSEEN_RELEASES
@@ -21,6 +20,7 @@ from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
from release_plan import next_chunk
from chunk_preflight.facts import open_pulls, render
from plan_store.todo_md import plan_of
from chunk_preflight.choices import worktree_add
from project_config.test_project_config import write_config
BIN = pathlib.Path(__file__).resolve().parents[1]
@@ -653,10 +653,6 @@ class Gathering(unittest.TestCase):
self.assertEqual(worktree_add("item-3", path, "origin/main", False, True)[0], ["worktree", "add", "--quiet", "--track", "-b", "item-3", "/c/proj-item-3", "origin/item-3"])
self.assertEqual(worktree_add("item-3", path, "origin/main", False, False)[0], ["worktree", "add", "--quiet", "--no-track", "-b", "item-3", "/c/proj-item-3", "origin/main"])
def test_lists_pull_requests_with_gh_on_a_github_origin_and_with_tea_elsewhere(self):
self.assertEqual(forge_of("git@github.com:o/r.git"), "gh")
self.assertEqual(forge_of("https://gitea.larvit.se/o/r.git"), "tea")
def test_reads_the_timeout_setting_as_seconds_above_0_and_else_takes_the_default(self):
self.assertEqual(seconds(None), TIMEOUT)
self.assertEqual(seconds("2.5"), 2.5)
+10 -9
View File
@@ -14,9 +14,10 @@ from deploy_release.deploy import deploy
from failure import Failure
from plan_store.todo_md import FilePlan
from record_store.stores import FileStore
from deploy_release import forge
from chunk_preflight.choices import forge_of
from forge.commands import forge_of, runner
from plan.release import newest_tag, Release, UNRELEASED_HEADING, version
from forge import pulls
from deploy_release import release_pull
from project_config import templates
@@ -153,7 +154,7 @@ def land(clone: str, ref: str, named: str, title: str) -> Failure | None:
url = git("config", "--get", "remote.origin.url", cwd=clone)
if isinstance(url, Failure):
return url
on, run, branch, base = forge_of(url), forge.runner(clone), f"release-{named}", ref.removeprefix("origin/")
on, run, branch, base = forge_of(url), runner(clone), f"release-{named}", ref.removeprefix("origin/")
head = branch_head(branch, clone)
if isinstance(head, Failure):
return head
@@ -168,23 +169,23 @@ def land(clone: str, ref: str, named: str, title: str) -> Failure | None:
head = branch_head(branch, clone) or Failure(f"pushed {branch}, but origin holds no such branch")
if isinstance(head, Failure):
return head
number = forge.open_pull(on, branch, head, run)
number = pulls.open_pull(on, branch, head, run)
if number is None:
if isinstance(created := forge.create_pull(on, branch, base, title, run), Failure):
if isinstance(created := release_pull.create_pull(on, branch, base, title, run), Failure):
return created
number = forge.open_pull(on, branch, head, run) or Failure(f"opened a pull request for {branch}, but the forge lists none from origin at {head[:12]}")
number = pulls.open_pull(on, branch, head, run) or Failure(f"opened a pull request for {branch}, but the forge lists none from origin at {head[:12]}")
if isinstance(number, str):
said(f"opened pull request {number}")
if isinstance(number, Failure):
return number
required = forge.required_checks(on, base, run)
required = pulls.required_checks(on, base, run)
if isinstance(required, Failure):
return required
said(f"waiting for the checks of pull request {number}" + (f"; {base} requires {', '.join(sorted(required))}" if required else ""))
if isinstance(passed := forge.checks_passed(on, number, head, required, run), Failure):
if isinstance(passed := pulls.checks_passed(on, number, head, required, run), Failure):
return passed
said(f"the checks of pull request {number} passed")
if isinstance(merged := forge.merge(on, number, head, run), Failure):
if isinstance(merged := release_pull.merge(on, number, head, run), Failure):
return merged
said(f"merged pull request {number}")
return None
+23
View File
@@ -0,0 +1,23 @@
"""Opening and merging a cut's pull request, with gh where origin is on GitHub and with tea elsewhere.
merge is pinned to head, the commit origin's release branch points at: the forge merges the pull request only while its head is still that commit, so a push to the branch after its checks passed is never merged.
"""
from failure import Failure
from forge.commands import Forge, gitea, Run
def create_pull(forge: Forge, branch: str, base: str, title: str, run: Run) -> Failure | None:
body = ["--body" if forge == "gh" else "--description", "Rename ## Unreleased in CHANGELOG.md to the version."]
command = ["gh", "pr"] if forge == "gh" else ["tea", "pulls"]
created = run([*command, "create", "--head", branch, "--base", base, "--title", title, *body])
return created if isinstance(created, Failure) else None
def merge(forge: Forge, number: str, head: str, run: Run) -> Failure | None:
"""Merge pull request number, fast-forward only on Gitea and by rebase on GitHub. The forge refuses where the pull request's head is no longer head."""
if forge == "gh":
# GitHub has no fast-forward-only merge. A rebase merge of a branch already on top of main is the nearest, though it may give the commit a new hash, so the cut finds it on main by its title.
merged = run(["gh", "pr", "merge", number, "--rebase", "--match-head-commit", head])
else:
merged = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{number}/merge", "Do=fast-forward-only", f"head_commit_id={head}")
return merged if isinstance(merged, Failure) else None
+4 -55
View File
@@ -1,16 +1,13 @@
import itertools
import json
import os
import pathlib
import subprocess
import sys
import tempfile
import typing
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from deploy_release.forge import checks_passed, POLL_SECONDS, required_checks, WAIT_SECONDS
from failure import Failure
from test_env import isolated_env
@@ -229,6 +226,10 @@ save()
""".replace("PYTHON", sys.executable)
# The protection of main that requires CI's check.
REQUIRED = '{"name": "main", "enable_status_check": true, "status_check_contexts": ["CI / tests (pull_request)"]}'
class Cut(unittest.TestCase):
"""A development clone whose next release, 0.2.0, holds no item, has its release review landed and one change unreleased; and a ~/.claude on v0.1.0."""
@@ -486,58 +487,6 @@ class Cut(unittest.TestCase):
self.assertEqual(self.origin_git("log", "-1", "--format=%s", "main").strip(), "Release review of 0.2.0")
def tea(statuses: typing.Iterable[str], branch: str = '{"name": "main"}') -> typing.Callable[[list[str]], str]:
"""A tea answering each read of the head's status with the next of statuses, and of branch main with branch."""
answers = iter(statuses)
return lambda command: branch if command[-1] == "repos/{owner}/{repo}/branches/main" else next(answers)
REQUIRED = '{"name": "main", "enable_status_check": true, "status_check_contexts": ["CI / tests (pull_request)"]}'
class RequiredChecks(unittest.TestCase):
def test_reads_on_tea_the_checks_the_protection_of_the_base_requires(self):
self.assertEqual(required_checks("tea", "main", tea([], REQUIRED)), {"CI / tests (pull_request)"})
def test_reads_none_on_tea_where_the_protection_turns_status_checks_off(self):
self.assertEqual(required_checks("tea", "main", tea([], '{"name": "main", "enable_status_check": false, "status_check_contexts": ["CI / tests (pull_request)"]}')), set())
def test_fails_on_tea_where_the_branch_reads_in_another_shape(self):
self.assertIsInstance(required_checks("tea", "main", tea([], "[]")), Failure)
def test_reads_none_on_github_whose_watch_covers_them(self):
self.assertEqual(required_checks("gh", "main", self.fail), set())
class ChecksPassed(unittest.TestCase):
def test_waits_on_tea_while_a_check_is_pending(self):
slept = []
self.assertIsNone(checks_passed("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 1}', '{"state": "success", "total_count": 1}']), slept.append))
self.assertEqual(slept, [POLL_SECONDS])
def test_takes_a_commit_with_no_status_on_tea_as_passed_where_the_base_requires_none(self):
self.assertIsNone(checks_passed("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 0}']), self.fail))
def test_waits_on_tea_for_a_check_the_base_requires_until_it_reports_and_passes(self):
slept = []
statuses = ['{"state": "pending", "total_count": 0, "statuses": []}', '{"state": "success", "total_count": 1, "statuses": [{"context": "lint", "status": "success"}]}', '{"state": "success", "total_count": 2, "statuses": [{"context": "lint", "status": "success"}, {"context": "CI / tests (pull_request)", "status": "success"}]}']
self.assertIsNone(checks_passed("tea", "1", "abc", {"CI / tests (pull_request)"}, tea(statuses), slept.append))
self.assertEqual(slept, [POLL_SECONDS, POLL_SECONDS])
def test_takes_on_tea_a_required_glob_as_met_by_a_check_it_matches(self):
passed = '{"state": "success", "total_count": 1, "statuses": [{"context": "CI / tests (pull_request)", "status": "success"}]}'
self.assertIsNone(checks_passed("tea", "1", "abc", {"CI / *"}, tea([passed]), self.fail))
def test_gives_up_on_tea_after_the_wait_naming_a_required_check_that_never_reported(self):
slept = []
waited = checks_passed("tea", "1", "abc", {"CI / tests (pull_request)"}, tea(itertools.repeat('{"state": "pending", "total_count": 0, "statuses": []}')), slept.append)
self.assertIsInstance(waited, Failure)
self.assertIn("CI / tests (pull_request)", waited.reason)
self.assertEqual(sum(slept), WAIT_SECONDS)
def test_fails_on_tea_where_a_check_failed(self):
self.assertIsInstance(checks_passed("tea", "1", "abc", set(), tea(['{"state": "failure", "total_count": 1}']), self.fail), Failure)
if __name__ == "__main__":
unittest.main()
View File
+42
View File
@@ -0,0 +1,42 @@
"""Which forge a checkout's origin is on, and running that forge's CLI in the checkout."""
import json
import subprocess
import typing
from failure import Failure
# The CLI of the forge that origin is on, as forge_of picks it.
Forge = typing.Literal["gh", "tea"]
# Runs a command in the checkout: what it printed, or a Failure with its reason.
Run = typing.Callable[[list[str]], str | Failure]
def forge_of(origin_url: str) -> Forge:
return "gh" if "github.com" in origin_url else "tea"
def runner(cwd: str) -> Run:
def run(command: list[str]) -> str | Failure:
try:
done = subprocess.run(command, capture_output=True, cwd=cwd, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL)
except OSError as failure:
return Failure(f"{command[0]} could not start: {failure}")
if done.returncode:
return Failure(f"{' '.join(command[:3])}: {(done.stderr or done.stdout).strip()}")
return done.stdout
return run
def gitea(run: Run, endpoint: str, *fields: str) -> typing.Any | Failure:
"""What Gitea's API answered at endpoint, parsed; with fields, `key=value` strings, a POST of them. tea api exits 0 on an HTTP error too, so an answer with Gitea's `message` key is a Failure."""
answered = run(["tea", "api", *(["--method", "POST"] if fields else []), *[word for field in fields for word in ("--field", field)], endpoint])
if isinstance(answered, Failure) or not answered.strip():
return answered
try:
parsed = json.loads(answered)
except ValueError:
return Failure(f"tea api {endpoint} printed no JSON: {answered.strip()[:200]}")
if isinstance(parsed, dict) and "message" in parsed:
return Failure(f"tea api {endpoint}: {parsed['message']}")
return parsed
@@ -1,50 +1,16 @@
"""The pull request steps of a cut. They run gh where origin is on GitHub and tea elsewhere, as chunk_preflight tells the two apart.
Each step is pinned to head, the commit origin's release branch points at: the cut takes only a pull request from origin itself whose head is that commit, and the forge merges it only while its head is still that commit. So a fork's pull request from a branch of the same name, or a push to the branch after its checks passed, is never merged.
"""
"""Finding a pull request from origin's own branch, and waiting for the checks on its head commit."""
import fnmatch
import json
import subprocess
import time
import typing
from failure import Failure
from chunk_preflight.choices import Forge
from forge.commands import Forge, gitea, Run
# How long the cut waits between two reads of the head commit's status on Gitea.
# How long checks_passed waits between two reads: of the head commit's status on Gitea, or of gh's watch while it reports no checks.
POLL_SECONDS = 10
# How long the cut waits for the checks before it gives up; CI took about 3 minutes in 2026-11.
# How long checks_passed waits on Gitea for the checks before it gives up; CI took about 3 minutes in 2026-11. gh's watch waits as long as the checks run.
WAIT_SECONDS = 30 * 60
# Runs a command in the clone: what it printed, or a Failure with its reason.
Run = typing.Callable[[list[str]], str | Failure]
def runner(cwd: str) -> Run:
def run(command: list[str]) -> str | Failure:
try:
done = subprocess.run(command, capture_output=True, cwd=cwd, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL)
except OSError as failure:
return Failure(f"{command[0]} could not start: {failure}")
if done.returncode:
return Failure(f"{' '.join(command[:3])}: {(done.stderr or done.stdout).strip()}")
return done.stdout
return run
def gitea(run: Run, endpoint: str, *fields: str) -> typing.Any | Failure:
"""What Gitea's API answered at endpoint, parsed; with fields, `key=value` strings, a POST of them. tea api exits 0 on an HTTP error too, so an answer with Gitea's `message` key is a Failure."""
answered = run(["tea", "api", *(["--method", "POST"] if fields else []), *[word for field in fields for word in ("--field", field)], endpoint])
if isinstance(answered, Failure) or not answered.strip():
return answered
try:
parsed = json.loads(answered)
except ValueError:
return Failure(f"tea api {endpoint} printed no JSON: {answered.strip()[:200]}")
if isinstance(parsed, dict) and "message" in parsed:
return Failure(f"tea api {endpoint}: {parsed['message']}")
return parsed
def open_pull(forge: Forge, branch: str, head: str, run: Run) -> str | None | Failure:
"""The number of the open pull request from origin's own branch whose head is head; None where there is none."""
@@ -75,13 +41,6 @@ def pull_at(forge: Forge, branch: str, head: str, state: typing.Literal["open",
return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}")
def create_pull(forge: Forge, branch: str, base: str, title: str, run: Run) -> Failure | None:
body = ["--body" if forge == "gh" else "--description", "Rename ## Unreleased in CHANGELOG.md to the version."]
command = ["gh", "pr"] if forge == "gh" else ["tea", "pulls"]
created = run([*command, "create", "--head", branch, "--base", base, "--title", title, *body])
return created if isinstance(created, Failure) else None
def required_checks(forge: Forge, base: str, run: Run) -> set[str] | Failure:
"""The checks, or glob patterns of checks, that the forge's protection of the branch base requires before a merge. None on GitHub, where gh's watch covers them.
@@ -132,13 +91,3 @@ def checks_passed(forge: Forge, number: str, head: str, required: set[str], run:
sleep(POLL_SECONDS)
waited_on = f"{', '.join(missing)}, which the protection requires, never passed" if missing else "a check is still pending"
return Failure(f"gave up on pull request {number} after {WAIT_SECONDS // 60} minutes: {waited_on}")
def merge(forge: Forge, number: str, head: str, run: Run) -> Failure | None:
"""Merge pull request number, fast-forward only on Gitea and by rebase on GitHub. The forge refuses where the pull request's head is no longer head."""
if forge == "gh":
# GitHub has no fast-forward-only merge. A rebase merge of a branch already on top of main is the nearest, though it may give the commit a new hash, so the cut finds it on main by its title.
merged = run(["gh", "pr", "merge", number, "--rebase", "--match-head-commit", head])
else:
merged = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{number}/merge", "Do=fast-forward-only", f"head_commit_id={head}")
return merged if isinstance(merged, Failure) else None
+99
View File
@@ -0,0 +1,99 @@
import itertools
import pathlib
import sys
import typing
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from forge.pulls import checks_passed, open_pull, POLL_SECONDS, required_checks, WAIT_SECONDS
from forge.commands import forge_of, gitea
class ForgeOf(unittest.TestCase):
def test_takes_a_github_origin_as_gh_and_any_other_as_tea(self):
self.assertEqual(forge_of("git@github.com:o/r.git"), "gh")
self.assertEqual(forge_of("https://gitea.larvit.se/o/r.git"), "tea")
# An answer no call can read, longer than the 200 characters of it that a failure quotes.
LONG = "[" + ", ".join(["1"] * 100) + "]"
class Gitea(unittest.TestCase):
def test_fails_with_giteas_message_where_it_answers_an_error(self):
self.assertEqual(gitea(lambda command: '{"message": "not found"}', "repos/o/r").reason, "tea api repos/o/r: not found")
def test_fails_quoting_the_first_200_characters_where_tea_prints_no_json(self):
self.assertEqual(gitea(lambda command: "x" * 300, "repos/o/r").reason, f"tea api repos/o/r printed no JSON: {'x' * 200}")
class OpenPull(unittest.TestCase):
def test_fails_quoting_the_first_200_characters_where_tea_lists_pull_requests_in_another_shape(self):
self.assertEqual(open_pull("tea", "item-3", "abc", lambda command: LONG).reason, f"tea api listed pull requests in a shape that can't be read: {LONG[:200]}")
def tea(statuses: typing.Iterable[str], branch: str = '{"name": "main"}') -> typing.Callable[[list[str]], str]:
"""A tea answering each read of the head's status with the next of statuses, and of branch main with branch."""
answers = iter(statuses)
return lambda command: branch if command[-1] == "repos/{owner}/{repo}/branches/main" else next(answers)
REQUIRED = '{"name": "main", "enable_status_check": true, "status_check_contexts": ["CI / tests (pull_request)"]}'
class RequiredChecks(unittest.TestCase):
def test_reads_on_tea_the_checks_the_protection_of_the_base_requires(self):
self.assertEqual(required_checks("tea", "main", tea([], REQUIRED)), {"CI / tests (pull_request)"})
def test_reads_none_on_tea_where_the_protection_turns_status_checks_off(self):
self.assertEqual(required_checks("tea", "main", tea([], '{"name": "main", "enable_status_check": false, "status_check_contexts": ["CI / tests (pull_request)"]}')), set())
def test_fails_on_tea_quoting_the_first_200_characters_where_the_branch_reads_in_another_shape(self):
self.assertEqual(required_checks("tea", "main", tea([], LONG)).reason, f"tea api answered branch main in a shape that can't be read: {LONG[:200]}")
def test_reads_none_on_github_whose_watch_covers_them(self):
self.assertEqual(required_checks("gh", "main", self.fail), set())
class ChecksPassed(unittest.TestCase):
def test_waits_on_tea_while_a_check_is_pending(self):
slept = []
self.assertIsNone(checks_passed("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 1}', '{"state": "success", "total_count": 1}']), slept.append))
self.assertEqual(slept, [POLL_SECONDS])
def test_takes_a_commit_with_no_status_on_tea_as_passed_where_the_base_requires_none(self):
self.assertIsNone(checks_passed("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 0}']), self.fail))
def test_waits_on_tea_for_a_check_the_base_requires_until_it_reports_and_passes(self):
slept = []
statuses = ['{"state": "pending", "total_count": 0, "statuses": []}', '{"state": "success", "total_count": 1, "statuses": [{"context": "lint", "status": "success"}]}', '{"state": "success", "total_count": 2, "statuses": [{"context": "lint", "status": "success"}, {"context": "CI / tests (pull_request)", "status": "success"}]}']
self.assertIsNone(checks_passed("tea", "1", "abc", {"CI / tests (pull_request)"}, tea(statuses), slept.append))
self.assertEqual(slept, [POLL_SECONDS, POLL_SECONDS])
def test_takes_on_tea_a_required_glob_as_met_by_a_check_it_matches(self):
passed = '{"state": "success", "total_count": 1, "statuses": [{"context": "CI / tests (pull_request)", "status": "success"}]}'
self.assertIsNone(checks_passed("tea", "1", "abc", {"CI / *"}, tea([passed]), self.fail))
def test_gives_up_on_tea_after_the_wait_naming_each_required_check_that_never_reported(self):
slept, read = [], []
pending = tea(itertools.repeat('{"state": "pending", "total_count": 0, "statuses": []}'))
waited = checks_passed("tea", "1", "abc", {"lint", "CI / tests (pull_request)"}, lambda command: read.append(command) or pending(command), slept.append)
self.assertEqual(waited.reason, "gave up on pull request 1 after 30 minutes: CI / tests (pull_request), lint, which the protection requires, never passed")
self.assertEqual(sum(slept), WAIT_SECONDS)
self.assertEqual(len(read), WAIT_SECONDS // POLL_SECONDS + 1)
def test_gives_up_on_tea_after_the_wait_saying_a_check_is_still_pending(self):
waited = checks_passed("tea", "1", "abc", set(), tea(itertools.repeat('{"state": "pending", "total_count": 1, "statuses": []}')), lambda seconds: None)
self.assertEqual(waited.reason, "gave up on pull request 1 after 30 minutes: a check is still pending")
def test_fails_on_tea_where_a_check_failed(self):
self.assertEqual(checks_passed("tea", "1", "abc", set(), tea(['{"state": "failure", "total_count": 1}']), self.fail).reason, "a check on pull request 1 ended in failure")
def test_fails_on_tea_quoting_the_first_200_characters_where_the_status_reads_in_another_shape(self):
self.assertEqual(checks_passed("tea", "1", "abc", set(), tea([LONG]), self.fail).reason, f"tea api printed no commit status for abc: {LONG[:200]}")
if __name__ == "__main__":
unittest.main()
+2 -2
View File
@@ -5,12 +5,12 @@ import pathlib
from git_cli.git_repo import branch_titles, git, top
from review_rules.round_titles import cap, round_counts
from failure import Failure
from chunk_preflight.choices import forge_of
from forge.commands import forge_of, runner
from record_store.stores import goals_store, local_file, store
from larv_review.history_commands import history_file, places_report
from project_config.main import located, title_templates
from review_rules.review_folder import made_review_folder
from deploy_release.forge import open_pull, runner
from forge.pulls import open_pull
from larv_review.plan_listing import plan_listing
from plan_store.stores import store as plan_store
from review_rules.reviewer_context import principles_line, starts_bare
+11 -3
View File
@@ -63,7 +63,9 @@ mistake. It prints `Finished item <ID> in <plan>.` It doesn't write anything whi
finish <ID> --no-changelog also drops an item no chunk built.
In a Jira epic, finish doesn't remove anything: it moves the item's issue by the transition, and to
the status, that the config's `jira-finish-transition` and `jira-finish-status` name, as
`project-config --help` shows. The --changelog rules hold there too, and docs/decisions.md isn't checked.
`project-config --help` shows. The issues' history is the changelog, so finish there needs
neither --changelog nor --no-changelog, and never reads the changelog. It refuses --changelog and
accepts --no-changelog. docs/decisions.md isn't checked.
It fails, moving no issue, where the config sets neither, where the issue has no such transition
from its present status, or where the transition leads to another status or to one Jira doesn't
count as done. An issue that no chunk built is dropped in Jira, not with finish, which would mark it done.
@@ -116,7 +118,8 @@ def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.T
case "move":
done = reported(plan.edit(args.id, {"Release": args.release}, None), "not moved", lambda written: f"Moved item {written.id} to release {args.release} in {plan.label}.")
case _:
done = finish(args, plan, store(config, "changelog"))
# A Jira plan keeps no changelog: the issues' history in Jira says what shipped.
done = finish(args, plan, None if config.epic else store(config, "changelog"))
if isinstance(done, Failure):
print(done.reason, file=sys.stderr)
return 1
@@ -217,7 +220,12 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure:
return reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore) -> str | Failure:
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore | None) -> str | Failure:
"""Finish item args.id in plan. changelog is where its bullet goes, or None where the plan keeps no changelog."""
if changelog is None:
if args.changelog is not None:
return Failure("not finished: the plan is a Jira epic, so the issues' history is the changelog; drop --changelog")
return reported(plan.finish(args.id), "not finished", lambda written: f"Finished item {written.id} in {plan.label}.")
held = changelog.held()
if isinstance(held, Failure):
return Failure(f"not finished: {held.reason}")
+40 -1
View File
@@ -4,10 +4,11 @@ import pathlib
import sys
import tempfile
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from project_config.test_project_config import configured
from project_config.test_project_config import configured, JIRA_PLAN, JIRA_SCORING
from plan.test_ranking import DECISIONS, README, TODO
from project_config.settings import DEFAULT_FLOOR
from todo_item import edits, main
@@ -266,6 +267,44 @@ class Finish(TodoItem):
self.assertEqual(self.todo.read_text(), before)
class FinishInJira(TodoItem):
"""A plan kept as a Jira epic keeps no changelog: the issues' history in Jira says what shipped."""
def setUp(self):
super().setUp()
self.config.write_text(self.config.read_text().replace('"checkout:todo.md"', f'"{JIRA_PLAN}"') + 'env-file = "~/acme.env"\n' + JIRA_SCORING)
self.plan = MemoryPlan({3: {"Release": "0.1.0", "Item": "**Count the runs.**", "L": "1", "E": "2", "I": "3", "S": "1"}})
patched = unittest.mock.patch.object(main, "plan_store", return_value=self.plan)
patched.start()
self.addCleanup(patched.stop)
def test_finishes_without_either_flag_and_doesnt_touch_the_changelog(self):
self.changelog.write_text(CHANGELOG)
self.assertEqual(self.run_main("finish", "3"), (0, "Finished item 3 in the plan in memory.\n", ""))
self.assertEqual((self.plan.rows, self.changelog.read_text()), ({}, CHANGELOG))
def test_finishes_with_no_changelog_so_chunk_pr_merge_keeps_working(self):
self.changelog.write_text(CHANGELOG)
self.assertEqual(self.run_main("finish", "3", "--no-changelog"), (0, "Finished item 3 in the plan in memory.\n", ""))
self.assertEqual(self.changelog.read_text(), CHANGELOG)
def test_refuses_a_bullet_and_says_the_issues_history_is_the_changelog(self):
self.changelog.write_text(CHANGELOG)
code, out, err = self.run_main("finish", "3", "--changelog", "Runs are fast.")
self.assertEqual((code, out), (1, ""))
self.assertTrue(err.startswith("not finished: "), err)
self.assertIn("the issues' history is the changelog", err)
self.assertEqual((list(self.plan.rows), self.changelog.read_text()), ([3], CHANGELOG))
def test_a_failing_finish_says_not_finished(self):
self.plan.fails = "Jira refused"
self.assertEqual(self.run_main("finish", "3"), (1, "", "not finished: Jira refused\n"))
def test_doesnt_read_the_changelog(self):
self.changelog.write_bytes(b"# Changelog\n\n\xff\n")
self.assertEqual(self.run_main("finish", "3")[::2], (0, ""))
class Show(TodoItem):
def test_prints_the_header_the_row_and_the_detail(self):
row = "| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 |"
+1 -1
View File
@@ -202,7 +202,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
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. 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 `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:
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`. Where the plan is a Jira epic, give 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.** `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.
+11 -57
View File
@@ -15,12 +15,10 @@
| 303 | 0.12.0 | | defect | **Archive each judge run's prompt and json reply beside the verdict it gave, so judge cost, replays and backups cover the judge as they cover the worker.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3, 3 by 2 | 4.2 |
| 306 | 0.12.0 | | | **Set a strategy that keeps loop-claude's archive and larv-review's review folders backed up and small over the years, compressing older entries without losing any.** | 3 | 2 | 4 | 7 | 5 | 3 by 5 | 3.9 |
| 304 | 0.12.0 | 303 | defect | **Archive each review-replay and judge-replay run's transcript beside its result, so a replay that decided a rung can be checked and re-priced later.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 2, 3 by 2 | 3.8 |
| 287 | 0.12.0 | | | **Move the forge helpers `Forge`, `forge_of`, `runner`, `open_pull`, `merged_pull`, `pull_at`, `gitea`, `checks_passed` and `required_checks` into one module that `chunk_preflight`, `chunk_pr`, `deploy_release` and `larv_review` all import from, so no tool imports another tool's internals for them.** | 3 | 1 | 3 | 5 | 5 | code health by 3 | 2.9 |
| 387 | 0.12.0 | | | **Bind a project's rung to its ladder in one value, so the routing functions and `Cycle` take one argument for both.** | 3 | 1 | 3 | 5 | 5 | code health by 3 | 2.9 |
| 338 | 0.12.0 | | owner | **Script each step that 0.9.0's chunks repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 3, 1.5 by 3 | 2.3 |
| 288 | 0.12.0 | | | **Point the two reading-cost decisions at code health and goal 1.4's counter-signal, in place of the goal 1.1 they cite.** | 1 | 2 | 1 | 2 | 1 | code health by 1, 1.4 by 1 | 2.2 |
| 391 | 0.12.0 | | | **Read and write a Jira epic issue's description and a Confluence record page through the lossless pair, so saving an unedited document leaves it unchanged.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 6, 1.1 by 3 | 1.9 |
| 394 | 0.12.0 | | | **Write no changelog bullet for a plan kept in Jira: `todo-item finish` there needs neither --changelog nor --no-changelog and refuses --changelog, since the issues' history is the changelog.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 4 | 1.3 |
| 319 | 0.12.0 | | | **Start a fresh session with a brief of the chunk when a rung step changes the worker's model, in place of resuming the old session.** | 3 | 2 | 3 | 6 | 4 | 1.1 by 2, 1.4 by 2 | 1.2 |
| 309 | 0.12.0 | | | **Run a scoring run's second pass on one head with two seats in place of four, once `larv-review agreement` shows the seats agree with each other more than a run agrees with its rerun.** | 2 | 2 | 2 | 4 | 2 | 1.4 by 3 | 1.2 |
| 299 | 0.12.0 | | | **Replay the archived judge verdicts through code rules and a classifier trained locally on the archive, and file an item for each verdict kind one of them decides with no missed interrupt.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
@@ -89,7 +87,7 @@ Touches:
- `bin/loop_claude/cycle/judge.py`: `run_judge`, `judge_once`
- `bin/loop_claude/cycle/run.py`: `(module)` (small)
- `bin/transcript_archive/write.py`: `archive`, `copy_for`
- `bin/transcript_archive/location.py` (small)
- `bin/transcript_archive/location.py`
- `bin/transcript_archive/test_transcript_archive.py`
- `bin/judge_replay/main.py`: `archived_cases`, `rule`
- `bin/judge_replay/replay.py`: `case_from`
@@ -111,8 +109,8 @@ Touches:
- `bin/transcript_archive/write.py`: `copy_for`, `mirror`
- `bin/transcript_archive/test_transcript_archive.py`
- `bin/routing_figures/archive.py`
- `bin/reading_cost/main.py` (small)
- `bin/score_outcomes/reversals.py` (small)
- `bin/reading_cost/main.py`
- `bin/score_outcomes/reversals.py`
- `bin/review_replay/rounds.py`
- `bin/judge_replay/main.py`: `archived_cases` (small)
- `skills/larv-review/SKILL.md`: `## 6. Wrap up` (small)
@@ -134,29 +132,6 @@ Touches:
- `bin/judge_replay/test_judge_replay.py`
- `bin/loop_claude/cycle/judge.py`: `judge_args`, `run_judge` (small)
### 287. Move the forge helpers `Forge`, `forge_of`, `runner`, `open_pull`, `merged_pull`, `pull_at`, `gitea`, `checks_passed` and `required_checks` into one module that `chunk_preflight`, `chunk_pr`, `deploy_release` and `larv_review` all import from, so no tool imports another tool's internals for them.
Today the helpers live in two tools. `Forge` is defined in `bin/chunk_preflight/gathered.py` and imported by `bin/chunk_preflight/choices.py`, `bin/chunk_preflight/facts.py`, `bin/chunk_preflight/main.py` and `bin/chunk_pr/main.py`, and again through `choices` by `bin/deploy_release/forge.py`. `forge_of` lives in `choices.py`, which `bin/chunk_pr/main.py`, `bin/deploy_release/cut.py` and `bin/larv_review/reviewer_header.py` import. `open_pull`, `runner` and `gitea` live in `bin/deploy_release/forge.py`, which `bin/chunk_pr/main.py` and `bin/larv_review/reviewer_header.py` import. So `deploy_release` imports `chunk_preflight`, and `chunk_pr` and `larv_review` import both.
Both comprehension seats of PR #453's paired ruling (2026-11-09) named this web as a place that cost them time, and neither saw a reason for it: a second forge would need edits in `chunk_preflight`, `deploy_release`, `chunk_pr` and `larv_review`.
Put the seven helpers in a folder named by what it holds, such as `bin/forge/`, and import them from there. Keep each helper's behaviour and its tests. `chunk_preflight/choices.py` keeps `pulls_command`, which is preflight's own. Check `docs/decisions.md` for a mention of where a helper lives, and update it.
Touches:
- `bin/deploy_release/forge.py`
- `bin/chunk_preflight/gathered.py`: `Forge`
- `bin/chunk_preflight/choices.py`: `forge_of`, `(module)` (small)
- `bin/chunk_preflight/facts.py`: `(module)` (small)
- `bin/chunk_preflight/main.py`: `(module)` (small)
- `bin/chunk_pr/main.py`: `(module)` (small)
- `bin/chunk_pr/approval.py`: `(module)` (small)
- `bin/deploy_release/cut.py`: `(module)` (small)
- `bin/larv_review/reviewer_header.py`: `(module)` (small)
- `bin/chunk_pr/test_chunk_pr.py` (small)
- `bin/chunk_preflight/test_chunk_preflight.py` (small)
- `bin/deploy_release/test_deploy_release.py` (small)
### 387. Bind a project's rung to its ladder in one value, so the routing functions and `Cycle` take one argument for both.
Filed by PR #553, which made the routing ladder a file a project may replace. Its stability round 1 found two places the comprehension seats name as hard, touched and no easier to read: `bin/loop_claude/routing.py` `unfinished_route` took `ladder` as a fourth parameter, and `Cycle` in `bin/loop_claude/cycle/run.py` gained the field `ladder`. The patch threaded the ladder as an argument, since a wider change did not fit a patch cut during an outage.
@@ -168,14 +143,14 @@ Touches:
- `bin/model_routing/ladder.py`: `Ladder`
- `bin/loop_claude/routing.py`
- `bin/loop_claude/cycle/run.py`: `Cycle`
- `bin/loop_claude/loop/main.py` (small)
- `bin/loop_claude/cycle/prompts.py` (small)
- `bin/loop_claude/loop/chunk_start.py` (small)
- `bin/loop_claude/loop/close.py` (small)
- `bin/loop_claude/escalation_mark.py` (small)
- `bin/model_routing/review_choice.py` (small)
- `bin/rule_hook/reviewer_rung.py` (small)
- `bin/judge_replay/main.py` (small)
- `bin/loop_claude/loop/main.py`
- `bin/loop_claude/cycle/prompts.py`
- `bin/loop_claude/loop/chunk_start.py`
- `bin/loop_claude/loop/close.py`
- `bin/loop_claude/escalation_mark.py`
- `bin/model_routing/review_choice.py`
- `bin/rule_hook/reviewer_rung.py`
- `bin/judge_replay/main.py`
- `bin/loop_claude/test_loop_claude.py`
### 338. Script each step that 0.9.0's chunks repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.
@@ -196,27 +171,6 @@ Both `docs/decisions.md` entries under `reading cost: a rise is …` and `readin
Open before building: the lossless markdown is less readable than the portable one (upstream larvit/adf-codec#185), and agents and the judge read the plan's details from it. Decide how a detail stays readable, for example by reading lossless and showing a person a portable view. Test that an unedited issue and page save back identical. The item ships alone because its R is above 5.
### 394. Write no changelog bullet for a plan kept in Jira: `todo-item finish` there needs neither --changelog nor --no-changelog and refuses --changelog, since the issues' history is the changelog.
The human ruled on 2026-11-16 that a project whose plan is a Jira epic keeps no changelog of its own: the issues' history in Jira already says what shipped. Today `todo-item finish` asks for `--changelog <bullet>` or `--no-changelog` whenever the configured changelog holds text, for a Jira plan too, and writes the bullet to `CHANGELOG.md` or the Confluence page.
Done when, for a plan kept in Jira:
- `todo-item finish <ID>` moves the issue without asking for either flag, and doesn't read or write the changelog;
- `todo-item finish <ID> --changelog <bullet>` refuses, writing nothing, and says the issues' history is the changelog;
- `--no-changelog` is still accepted, so `chunk-pr merge --finish <ID> --no-changelog` keeps working;
- `CLAUDE.md` → "Working loop" and larv-review §5 say a Jira plan takes no changelog bullet.
A plan kept as todo.md behaves as today. A client's own `CHANGELOG.md` stays the team's: the loop just stops adding to it.
Touches:
- `bin/todo_item/main.py`: `finish`, `(module)` (small)
- `bin/todo_item/test_todo_item.py`
- `bin/chunk_pr/main.py`: `(module)` (small)
- `CLAUDE.md`: `## Working loop` (small)
- `skills/larv-review/SKILL.md`: `## 5. Goal alignment, then merge` (small)
### 319. Start a fresh session with a brief of the chunk when a rung step changes the worker's model, in place of resuming the old session.
On SWE-bench Verified with Haiku 4.5 and Opus 4.7, handing the strong model the weak model's transcript solved 69.2% at $1.61 a task; starting the strong model fresh solved 79.2% at $0.90 (arXiv 2608.24358, The Handoff Tax). A model switch also rereads the whole context uncached (Claude Code prompt caching docs). A worker that steps from Sonnet 5.5 to Opus 5.5 by `--resume` is the raw handoff; an effort-only step within one model keeps the cache and isn't. The escalated subagent, which starts fresh with the trigger's evidence, already follows the pattern that won.