diff --git a/README.md b/README.md index dec76e07..9734d1d0 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ A legacy project with no container setup sets `tooling-on-host = true`, so the l 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. -A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. loop-claude starts no chunk from an item such a pull request finishes. Once every item left in the release waits and one waits for a merge, the loop stops and names the pull requests to merge. The first chunk after a merge runs `chunk-pr clean` in the worktree the merged one left. Nobody works on a pull request that awaits your merge: to have a reviewer's comment answered, turn it back into a draft, and a chunk takes its item up again. Left out, the setting is `"chunk"`: the chunk merges. +A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once; where you close the pull request unmerged, file the item again. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. loop-claude doesn't start a chunk for an item that a ready pull request finishes. Once no item left in the release can start and one awaits a merge, loop-claude stops and names the pull requests to merge; run it again after you merge one. The first chunk after a merge runs `chunk-pr clean` in the worktree the merged pull request left, where nobody pushed to the pull request after the chunk did. Nobody works on a pull request that awaits your merge. To have a reviewer's comment answered, turn the pull request back into a draft: a chunk then takes its item up again. Left out, the setting is `"chunk"`: the chunk merges. 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:`, 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. diff --git a/bin/chunk_pr/main.py b/bin/chunk_pr/main.py index 7a6f736f..6b249149 100644 --- a/bin/chunk_pr/main.py +++ b/bin/chunk_pr/main.py @@ -476,7 +476,7 @@ def finished(run: Run, branch: str, finish: list[str], config: ProjectConfig) -> if isinstance(finishing, Failure): return finishing title = templates.title_of(config.commit_title, config.branch, branch, finish[0], f"Finish item {finish[0]} in the plan") - # Under `merge = "human"` a plan or changelog outside the checkout is finished here, before the person merges, since no run follows that merge; where they close the pull request unmerged, they file the item again. + # Under `merge = "human"` a plan or changelog outside the checkout is finished here, before the person merges, since no run follows that merge. # A plan in Jira, or a changelog on a Confluence page, is no file to commit. records = [record for record in (config.plan_file, config.paths.get("changelog")) if record is not None and record.is_file()] return committed(run, title, records) diff --git a/bin/chunk_preflight/facts.py b/bin/chunk_preflight/facts.py index d95fca2c..806b0029 100644 --- a/bin/chunk_preflight/facts.py +++ b/bin/chunk_preflight/facts.py @@ -29,11 +29,11 @@ def render(found: Gathered) -> list[str]: def merge_lines(found: Gathered) -> list[str]: - """What `merge = "human"` leaves for the worker to know: each worktree a merged pull request left, the items passed over since their pull request awaits a person's merge, and why those could not be read.""" + """What `merge = "human"` leaves for the worker to know: each worktree a merged pull request left, the items passed over since their pull request awaits a person's merge, or why those pull requests could not be read.""" left = [f"- The worktree {worktree.path}, on the branch {worktree.branch}, is left from pull request #{worktree.pull}, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step." for worktree in found.left] items = found.item.plan.items if isinstance(found.item, ItemFacts) else [] passed = [f"item {item.id}, by pull request {item.awaits_merge}" for item in items if item.awaits_merge] - over = [f"- Passed over, since each is finished on a branch whose pull request is ready and awaits a person's merge: {'; '.join(passed)}. No chunk takes one."] if passed else [] + over = [f"- Items passed over, each finished on a branch whose ready pull request awaits a person's merge: {'; '.join(passed)}. No chunk takes one."] if passed else [] unread = [f"- The pull requests that await a person's merge cannot be read, so no item is passed over for one: {found.merges_unread.reason}"] if found.merges_unread else [] return [*left, *over, *unread] diff --git a/bin/chunk_preflight/gathered.py b/bin/chunk_preflight/gathered.py index b6008c01..00f81899 100644 --- a/bin/chunk_preflight/gathered.py +++ b/bin/chunk_preflight/gathered.py @@ -46,9 +46,10 @@ class ItemFacts: @dataclasses.dataclass(frozen=True) class LeftWorktree: - """A worktree on a branch whose pull request, of this number, has merged.""" + """A worktree on a branch whose pull request has merged.""" path: pathlib.Path branch: str + # The merged pull request's number. pull: str @@ -70,7 +71,7 @@ class Gathered: plan_outside: bool # The language and the templates the project's config names, by their settings. texts: dict[str, str] - # Why the pull requests that await a person's merge could not be read; None where they were read, or the chunk merges its own. + # Why the pull requests that await a person's merge could not be read; None where they were read or not asked for. merges_unread: Failure | None = None - # Each other worktree whose pull request a person has merged, which `chunk-pr clean` is still to remove. + # The worktrees `chunk-pr clean` is still to remove. left: tuple[LeftWorktree, ...] = () diff --git a/bin/chunk_preflight/main.py b/bin/chunk_preflight/main.py index e38bf979..86e00ba6 100644 --- a/bin/chunk_preflight/main.py +++ b/bin/chunk_preflight/main.py @@ -16,15 +16,15 @@ and prints that the release reviews and the cuts are the human's to call. It pri newest version CHANGELOG.md heads `## X.Y.Z - YYYY-MM-DD`; an undated heading doesn't count. Then how many entries the default branch's CHANGELOG.md holds under ## Unreleased, or else how many commits followed the cut: the tag, or the commit that added that heading; -- under `merge = "human"` (`project-config --help`), each other worktree whose pull request has - merged, for the worker to run `chunk-pr clean` in, and each item passed over: one that an open - pull request, no draft, finished on its branch, where the checkout holds the plan. Such an item - waits until a person merges. Where every item left in the release waits and one awaits a merge, - it names those pull requests and says the working loop stops there; +- under `merge = "human"` (`project-config --help`), each worktree beside the checkout whose pull + request has merged, for the worker to run `chunk-pr clean` in, and each item passed over: one + finished on the branch of an open pull request that is not a draft, where the checkout holds + the plan. Where no item of the release can start and one awaits such a merge, it names those + pull requests and says the working loop stops there; - the next release and its first item that does not wait, the item loop-claude routes on, with its L and E + I; with --item , the plan item of that ID instead, which loop-claude names in a window - named for an item. An item waits while it is marked question, or while an item still in todo.md - blocks it. Where the last cut is a version x.y.z, the next release is the earliest after x.y.z + named for an item. An item waits while it is marked question, while an item still in todo.md + blocks it, or while it awaits such a merge. Where the last cut is a version x.y.z, the next release is the earliest after x.y.z that todo.md has named at that cut or since, less a release its ## Renamed section marks renamed. Where nothing is cut, it is the earliest release todo.md has ever named, less those renamed, so a release whose items are all done still reads as next. @@ -181,7 +181,7 @@ def item_worktree(root: pathlib.Path, branch: str, default: str) -> Worktree | F def left_worktrees(root: pathlib.Path, forge_run: Run) -> tuple[LeftWorktree, ...]: - """Each worktree beside the checkout whose branch's pull request has merged at the worktree's head: under `merge = "human"` a person merges after the chunk's run has ended, so its worker never ran `chunk-pr clean`. A worktree whose forge can't be asked counts as not left.""" + """Each worktree but root that is on a branch whose pull request merged with the worktree's head commit as its head: under `merge = "human"` a person merges after the chunk's run has ended, so its worker never ran `chunk-pr clean`. Where the forge can't be asked, no worktree counts as left.""" listing, url = git("worktree", "list", "--porcelain"), git("remote", "get-url", "origin") if isinstance(listing, Failure) or isinstance(url, Failure): return () diff --git a/bin/forge/pulls.py b/bin/forge/pulls.py index 7655748c..2c641471 100644 --- a/bin/forge/pulls.py +++ b/bin/forge/pulls.py @@ -56,7 +56,7 @@ class ReadyPull: def ready_pulls(forge: Forge, run: Run) -> list[ReadyPull] | Failure: - """Each open pull request from origin's own branches that is no draft, which Gitea tells by its title (GITEA_DRAFT). A row whose number or head is no number or commit ID is left out, since callers pass them to git.""" + """Each open pull request from origin's own branches that is no draft, which Gitea tells by its title (GITEA_DRAFT). A row is left out where its head is no commit ID, since the caller passes the head to git, or where its number is not all digits, since the caller prints it.""" if forge == "gh": # 100 is the most GitHub's API lists a page; gh lists 30 unless told. listed = run(["gh", "pr", "list", "--limit", "100", "--json", "number,url,headRefOid,isDraft,isCrossRepository", "--template", "{{range .}}{{.number}}\t{{.url}}\t{{.headRefOid}}\t{{.isDraft}}\t{{.isCrossRepository}}\n{{end}}"]) diff --git a/bin/plan/todo_table.py b/bin/plan/todo_table.py index 6bc7605b..38731980 100644 --- a/bin/plan/todo_table.py +++ b/bin/plan/todo_table.py @@ -107,7 +107,7 @@ class Item: blocked_by: tuple[int, ...] # Empty where the item has none, and where a reader took only the table. detail: str = "" - # The pull request, as `# `, whose merge by a person the item awaits, finished on that branch only; empty where it awaits none, and where the reader asked no forge. release_plan.awaiting_merge sets it. + # The pull request, as `# `, whose merge by a person the item awaits; empty where it awaits none, and where the reader asked no forge. release_plan.awaiting_merge sets it. awaits_merge: str = "" @property diff --git a/bin/release_plan/awaiting_merge.py b/bin/release_plan/awaiting_merge.py index 7f6c92ea..6e36e01a 100644 --- a/bin/release_plan/awaiting_merge.py +++ b/bin/release_plan/awaiting_merge.py @@ -3,14 +3,14 @@ import dataclasses from failure import Failure from forge.commands import Forge, Run -from forge.pulls import ready_pulls from git_cli.git_repo import Git, git -from plan_store import stores from plan_store.plans import Plan, PlanStore +from forge.pulls import ready_pulls +from plan_store import stores def awaiting(ref: str, plan: PlanStore, root: str, forge: Forge, forge_run: Run, run: Git = git) -> dict[int, str] | Failure: - """Each plan item, by ID, that awaits a person's merge, with its pull request as `# `: an item the plan held where the pull request's branch left ref, the default branch, and no longer holds at its head. A pull request whose head the checkout hasn't fetched, or whose plan can't be read, names none.""" + """Each plan item, by ID, that awaits a person's merge, with its pull request as `# `: an item that the plan held at the commit where the pull request's branch left ref, the default branch, and that the plan at the pull request's head no longer holds. A pull request whose head the checkout hasn't fetched, or whose plan can't be read, names none.""" pulls = ready_pulls(forge, forge_run) if isinstance(pulls, Failure): return pulls @@ -26,5 +26,5 @@ def awaiting(ref: str, plan: PlanStore, root: str, forge: Forge, forge_run: Run, def marked(plan: Plan, awaited: dict[int, str]) -> Plan: - """plan with each item awaited names marked as awaiting its pull request's merge, so it waits.""" + """plan, with each item whose ID awaited holds marked as awaiting that pull request's merge, so the item waits.""" return dataclasses.replace(plan, items=[dataclasses.replace(item, awaits_merge=awaited.get(item.id, "")) for item in plan.items]) diff --git a/skills/larv-review/standards/prose.md b/skills/larv-review/standards/prose.md index 87aec594..a362c13c 100644 --- a/skills/larv-review/standards/prose.md +++ b/skills/larv-review/standards/prose.md @@ -12,4 +12,4 @@ Everything written — chat, commit messages, comments, docs, code — is in **E - **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, doesn't carry anything — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone. - **Write negations as people say them.** After a verb, or after its preposition, write `doesn't anything` or `anyone`, never ` nothing` or `no one`; each breach is a 🟡. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`. - **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader choosing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`. -- **A sentence about several named things holds for each.** Where a sentence gives one property to several named tables, fields or flags, check the property in each one's source. Where it fails for one, split the sentence. BANNED, where only `users` has the column: `Each row of users and groups has a name`. GOOD: `Each row of users has a name. A row of groups has only an id`. +- **A sentence about several named things holds for each.** Where a sentence gives one property to several named fields, flags or tables, check the property in each one's source. Where it fails for one, split the sentence. BANNED, where only `users` has the column: `Each row of users and groups has a name`. GOOD: `Each row of users has a name. A row of groups has only an id`.