Answer product-owner round 1: 0 🔴, 3 🟡 (1 misread); say which plans finish at once, keep a repo with its own merge method from merging, and file item 457

This commit is contained in:
Lilleman
2026-11-19 18:07:54 +01:00
parent 24bd382d48
commit 22654a5e05
5 changed files with 72 additions and 49 deletions
+1 -1
View File
@@ -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 levels the branch, finishes the chunk's plan items on it, waits for the checks and marks the pull request ready, but leaves the merge to a person. The finished items land with that merge. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. 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. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. 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:<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.
+4 -3
View File
@@ -49,8 +49,9 @@ merge merges the pull request in its turn: the chunks of one project on this
fails at once instead of waiting: do-epic parks the chunk until the approval comes.
Where the project's config sets `merge = "human"` (`project-config --help`), it does
steps 1 to 4, marks the pull request ready in place of step 5, and prints that the pull
request awaits a person's merge, exit 0. The plan items step 2 finished are commits on
the branch, so they land with that merge. It reads no approval then, whatever
request awaits a person's merge, exit 0. A plan or changelog in the checkout that step 2
finished is a commit on the branch, so it lands with that merge; one in Jira, or in
the config's folder, is finished at once. It reads no approval then, whatever
`wait-for-approval` says. Once a person merged it, run clean.
It stops, without merging, and says what to do before running it again:
- on a merge conflict in step 1, naming the conflicted files, with the merge in progress;
@@ -362,7 +363,7 @@ class Merging:
base: str
required: set[str]
waits: bool
by_human: bool = False
by_human: bool
@dataclasses.dataclass(frozen=True)
+3 -3
View File
@@ -18,7 +18,7 @@ DRIVER = DO_EPIC
def shipping(config: ProjectConfig) -> str:
"""How a chunk in the repo that config names ships its change. An epic's issue isn't an item of the repo's plan, so `chunk-pr merge --finish`, which adds a finished item's changelog bullet, doesn't apply: the worker writes the bullet itself, where the repo publishes something others consume. Where the repo's config leaves the merge to a person, the worker is told that its run ends with the pull request ready (docs/decisions.md → `do-epic: drives one Jira epic …`, "Releases")."""
"""How a chunk in the repo that config names ships its change. An epic's issue isn't an item of the repo's plan, so `chunk-pr merge --finish`, which adds a finished item's changelog bullet, doesn't apply: the worker writes the bullet itself, where the repo publishes something others consume. (docs/decisions.md → `do-epic: drives one Jira epic …`, "Releases"). Where the repo's config leaves the merge to a person, the worker ends its run on `chunk-pr merge`'s word, since do-epic parks the chunk until that merge ("Long gates")."""
opening = "The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."
if config.merge == "human":
opening += " The repo's team merges its pull requests itself, so `chunk-pr merge` leaves the pull request ready for a person to merge: end your run when it says so."
@@ -54,8 +54,8 @@ NAMES = prompts.RecordNames(
)
WORKER = prompts.worker_prompts(DRIVER, fresh, "", NAMES)
# What a worker does with a reviewer's feedback, as the decision asks (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
FEEDBACK = 'Where a reviewer left feedback, fix what is reasonable and push the fix, answer each other comment in its thread, and change the setup so our review would have caught the finding (~/.claude/CLAUDE.md → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first"). Then merge the pull request as before. Where the pull request is merged, run `chunk-pr clean` in its worktree and finish the chunk.'
# What a worker that was parked does: with a reviewer's feedback, and with a pull request a person merged, as the decision asks (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
FEEDBACK = 'Where a reviewer left feedback, fix what is reasonable and push the fix, answer each other comment in its thread, and change the setup so our review would have caught the finding (~/.claude/CLAUDE.md → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first"). Then merge the pull request as before. Where the pull request is merged already, run `chunk-pr clean` in its worktree instead, and finish the chunk; where it was closed without a merge, say so and end your run.'
def unparked(news: str) -> WorkerPrompts:
+3 -2
View File
@@ -216,9 +216,10 @@ Launch prose-reviewer with what the diff touched and every section this review c
- **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. Fixed or declined, it ends with the same setup change (§4 step 6). The wait doesn't hold the queue, so other chunks merge meanwhile.
- **A person's merge**, where the project's config sets `merge = "human"` (`chunk-pr --help`). `chunk-pr merge` exits 0, saying the pull request awaits a person's merge. Leave it ready and unmerged, say so in the summary, and skip step 5: whoever continues the chunk after the merge runs it.
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.
Where the project's config sets `merge = "human"` (`chunk-pr --help`), `chunk-pr merge` exits 0 instead, saying the pull request awaits a person's merge. Don't run it again: leave the pull request ready and unmerged, say so in the summary, and skip step 5, which whoever continues the chunk after the merge runs.
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. Where `~/.claude/bin/project-config merge` prints `human`, it doesn't merge at all: it finishes the items in the branch, marks the pull request ready and leaves it unmerged. A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
5. Merged → run `~/.claude/bin/chunk-pr clean` in the chunk's worktree, and put a failure it prints in the summary.
6. Stop. The next chunk gets a fresh session.
+61 -40
View File
@@ -6,18 +6,19 @@
`Bar = 0.1`
`Next ID = 457`
`Next ID = 458`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 451 | 0.13.0 | | | **Add a project setting `merge = "human"`, under which a chunk leaves its pull request ready for a person to merge, and a do-epic chunk parks until the pull request is merged.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 7 | 1.4 |
| 456 | 0.13.0 | 451 | | **Keep loop-claude from starting a chunk for an item whose pull request is ready and awaits a person's merge under `merge = "human"`.** | 2 | 2 | 2 | 4 | 4 | 1.6 by 5, 1.4 by 3 | 2.2 |
| 448 | 0.13.0 | | | **Read a team's own repo labels as do-epic's picks, through a label table in its config, and treat an item that has sub-tasks as split, so planning never files sub-tasks beside the team's own.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 8 | 2.2 |
| 452 | 0.13.0 | | | **Make do-epic's view of the Jira workflow settings: the statuses at which an issue unblocks the issues it blocks, and the moves the team's own automation makes, so do-epic makes none of those.** | 3 | 2 | 2 | 5 | 5 | 1.6 by 7, 1.5 by 3 | 2.1 |
| 449 | 0.13.0 | 448 | | **Record do-epic's repo picks and sub-task summaries in the team's own spelling, such as `core-4` and `core-4: Bygg …`, as its config sets them.** | 2 | 2 | 2 | 4 | 3 | 1.6 by 6 | 2.0 |
| 451 | 0.13.0 | | | **Add a project setting `merge = "human"`, under which a chunk leaves its pull request ready for a person to merge, and a do-epic chunk parks until the pull request is merged.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 7 | 1.4 |
| 457 | 0.13.0 | 451 | | **Resume a chunk whose pull request awaits a person's merge once it no longer merges cleanly into the default branch, so the worker brings it level again.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 4, 1.5 by 3 | 1.9 |
| 453 | 0.13.0 | | | **Make the issue types that do-epic and `todo-item add` file in Jira settings, since a Jira project such as TW has no Task type.** | 2 | 2 | 1 | 3 | 2 | 1.6 by 5 | 1.8 |
| 456 | 0.13.0 | 451 | | **Keep loop-claude from starting a chunk for an item whose pull request is ready and awaits a person's merge under `merge = "human"`.** | 3 | 2 | 2 | 5 | 5 | 1.6 by 5, 1.4 by 3 | 1.7 |
| 450 | 0.13.0 | | | **Add `do-epic <EPIC-KEY> --dry-run`, which prints every Jira write planning would make and each chunk that would start, and makes none of them.** | 2 | 2 | 2 | 4 | 3 | 1.6 by 5 | 1.6 |
| 455 | 0.13.0 | | | **Let a chunk file a follow-up issue that its own issue blocks, with `do-epic --file --blocked-by` and `--parent`, so a change a repo ships as two pull requests gets an issue for each.** | 2 | 2 | 1 | 3 | 2 | 1.6 by 4 | 1.4 |
| 454 | 0.13.0 | | | **Start a do-epic chunk's issue as the team's board expects, by settings: assigned to the account do-epic works as, moved by a start transition and added to a board's active sprint.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 4 | 1.1 |
@@ -78,43 +79,6 @@
## Details
### 451. Add a project setting `merge = "human"`, under which a chunk leaves its pull request ready for a person to merge, and a do-epic chunk parks until the pull request is merged.
Every chunk merges its own pull request with `chunk-pr merge`. Some teams forbid that: Timewave's conventions say never to merge a pull request without the human's explicit go-ahead for that pull request. The loop can't run in such a team's repos without breaking the rule, and `wait-for-approval` doesn't cover it, since a reviewer's approval is not the go-ahead to merge.
- A project setting `merge` takes `chunk`, the default and today's behaviour, or `human`.
- Under `human`, `chunk-pr merge` levels the branch and marks the pull request ready, then leaves the merge to a person and exits saying the pull request awaits a person's merge.
- A do-epic chunk then parks on a new gate, `your merge`, shown in its window's name and in `--status` like any gate. It takes no slot, finishes once the forge reports the pull request merged, and still resumes when a reviewer comments.
- A loop-claude chunk ends with the pull request ready. The chunk settles how the item's `--finish` runs after a person merges it.
- `parked_through` in `bin/do_epic/main.py` is the place the comprehension seats found hardest to follow; leave it easier to read than it was.
Touches:
- `bin/project_config/settings.py`: `SCALARS` (small)
- `bin/chunk_pr/main.py`: `merged`, `merge_turn`
- `bin/chunk_pr/approval.py`: `awaited` (small)
- `bin/do_epic/gates.py`: `gate`, `Gate`
- `bin/do_epic/main.py`: `parked_through`
- `bin/do_epic/chunk_prompt.py`: `shipping`
- `bin/do_epic/test_gates.py`
- `bin/do_epic/test_main.py`
- `README.md`: `### Set up a project` (small), `## Tools` (small)
### 456. Keep loop-claude from starting a chunk for an item whose pull request is ready and awaits a person's merge under `merge = "human"`.
Under `merge = "human"`, `chunk-pr merge` leaves a chunk's pull request ready, with its item finished only on the branch. Until a person merges it, the default branch's plan still holds the item, so `chunk-preflight` names it as the next item again. loop-claude then starts a cycle that can only run `chunk-pr merge` once more and end, and it does so every cycle until the merge.
- `chunk-preflight` passes over an item whose branch has an open pull request that isn't a draft, where the project's config sets `merge = "human"`, and says so in its facts.
- Where every remaining item of the release waits like that, loop-claude stops and says which pull requests await a merge.
- Once the pull request is merged, the next chunk's preflight runs `chunk-pr clean` for the worktree it left, or tells the worker to.
Touches:
- `bin/chunk_preflight/main.py`
- `bin/chunk_preflight/facts.py`: `item_lines`, `pulls_text`
- `bin/chunk_preflight/test_chunk_preflight.py`
- `README.md`: `### Set up a project` (small)
### 448. Read a team's own repo labels as do-epic's picks, through a label table in its config, and treat an item that has sub-tasks as split, so planning never files sub-tasks beside the team's own.
do-epic reads an item's repo only from a `repo:<name>` label. A team that labels each issue with its repo's name, or with a short name such as `twu-4` for `tenant-web-ui-4`, gets no issue counted as placed. Planning then predicts every open item's repos again and can file sub-tasks beside the ones the team filed, and the team's own sub-tasks never run. On TW-13503, nine items with 40 sub-tasks between them would have been split again, two of them under issues with open pull requests. docs/decisions.md → `do-epic: drives one Jira epic …` already says that on the first machine, an item's label that equals a repo's name names that repo.
@@ -182,6 +146,44 @@ Touches:
- `bin/do_epic/test_split.py`
- `README.md`: `### Set up a project` (small)
### 451. Add a project setting `merge = "human"`, under which a chunk leaves its pull request ready for a person to merge, and a do-epic chunk parks until the pull request is merged.
Every chunk merges its own pull request with `chunk-pr merge`. Some teams forbid that: Timewave's conventions say never to merge a pull request without the human's explicit go-ahead for that pull request. The loop can't run in such a team's repos without breaking the rule, and `wait-for-approval` doesn't cover it, since a reviewer's approval is not the go-ahead to merge.
- A project setting `merge` takes `chunk`, the default and today's behaviour, or `human`.
- Under `human`, `chunk-pr merge` levels the branch and marks the pull request ready, then leaves the merge to a person and exits saying the pull request awaits a person's merge.
- A do-epic chunk then parks on a new gate, `your merge`, shown in its window's name and in `--status` like any gate. It takes no slot, finishes once the forge reports the pull request merged, and still resumes when a reviewer comments.
- A loop-claude chunk ends with the pull request ready. The chunk settles how the item's `--finish` runs after a person merges it.
- `parked_through` in `bin/do_epic/main.py` is the place the comprehension seats found hardest to follow; leave it easier to read than it was.
Touches:
- `bin/project_config/settings.py`: `SCALARS` (small)
- `bin/chunk_pr/main.py`: `merged`, `merge_turn`
- `bin/chunk_pr/approval.py`: `awaited` (small)
- `bin/do_epic/gates.py`: `gate`, `Gate`
- `bin/do_epic/main.py`: `parked_through`
- `bin/do_epic/chunk_prompt.py`: `shipping`
- `bin/do_epic/test_gates.py`
- `bin/do_epic/test_main.py`
- `README.md`: `### Set up a project` (small), `## Tools` (small)
### 457. Resume a chunk whose pull request awaits a person's merge once it no longer merges cleanly into the default branch, so the worker brings it level again.
Under `merge = "human"` a pull request stays ready for hours or days while the default branch moves. A conflict, such as each branch holding its own changelog bullet or plan edit, or a branch protection that requires an up-to-date branch, then blocks the person who would merge it. Yet `gate` in `bin/do_epic/gates.py` reads only the draft state, the checks, the review decision and the waiting threads, so the window and `--status` keep saying `awaits your merge`, and nothing resumes the chunk unless a reviewer comments.
- Where `by_human`, `gate` reads the forge's mergeability before it returns the `your merge` gate: GitHub's `mergeable` and `mergeStateStatus`, Gitea's `mergeable`. No reader exists yet under `bin/forge/`; add one beside `open_pull` in `bin/forge/pulls.py`.
- A pull request that conflicts with the default branch, or is behind it where the branch protection requires an up-to-date branch, gives an `Open` whose news tells the worker to run `chunk-pr merge` again, which levels, pushes, waits for the checks and marks ready. Settle whether that rerun passes `--finish` again, since the items are already finished on the branch.
- GitHub reports `mergeable` as `UNKNOWN` while it computes it: that keeps the `your merge` gate until the next read, rather than resuming the chunk.
- State the new resume in `docs/decisions.md` → "Long gates".
Touches:
- `bin/do_epic/gates.py`: `gate` (small)
- `bin/forge/pulls.py`
- `bin/forge/test_forge.py`
- `bin/do_epic/test_gates.py`
### 453. Make the issue types that do-epic and `todo-item add` file in Jira settings, since a Jira project such as TW has no Task type.
do-epic and `todo-item add` file every new issue as a Task, the name `plan_store/jira_epic.py` sets as `ISSUE_TYPE`. A Jira project without a Task type, such as TW, whose types are Feature, Bug, Chore and Investigation, refuses each one. So `do-epic --file` fails there, and so does the epic's finishing, which files a release review for each repo.
@@ -200,6 +202,25 @@ Touches:
- `bin/do_epic/backend/test_jira.py`
- `README.md`: `### Set up a project` (small)
### 456. Keep loop-claude from starting a chunk for an item whose pull request is ready and awaits a person's merge under `merge = "human"`.
Under `merge = "human"`, `chunk-pr merge` leaves a chunk's pull request ready, with its item finished only on the branch. Until a person merges it, the default branch's plan still holds the item, so `chunk-preflight` names it as the next item again. loop-claude then starts a cycle that can only run `chunk-pr merge` once more and end, and it does so every cycle until the merge.
- `chunk-preflight` passes over an item whose branch has an open pull request that isn't a draft, where the project's config sets `merge = "human"`, and says so in its facts.
- Where every remaining item of the release waits like that, loop-claude stops and says which pull requests await a merge.
- Once the pull request is merged, the next chunk's preflight runs `chunk-pr clean` for the worktree it left, or tells the worker to.
- Under `merge = "human"`, `chunk-pr merge --finish` finishes a plan kept in Jira, or a plan or changelog kept in the config's folder, at once, before the person merges; where the pull request is closed unmerged, the item stays finished. Settle whether loop-claude finishes such an item only after the merge.
- Under loop-claude nobody answers a reviewer's comment on a pull request that awaits a person's merge, since the chunk's run has ended. Settle who does, or say in README that the person asks for it.
Touches:
- `bin/chunk_preflight/main.py`
- `bin/chunk_preflight/facts.py`: `item_lines`, `pulls_text`
- `bin/chunk_preflight/test_chunk_preflight.py`
- `bin/chunk_pr/main.py`: `levelled_and_finished`, `finished` (small)
- `bin/chunk_pr/test_chunk_pr.py`
- `README.md`: `### Set up a project` (small)
### 450. Add `do-epic <EPIC-KEY> --dry-run`, which prints every Jira write planning would make and each chunk that would start, and makes none of them.
`do-epic <EPIC-KEY>` writes to Jira before it starts any chunk: labels, sub-tasks, comments on a team's issues and a new backlog order. A person has no way to see those writes before they happen, so the first run on a team's epic is a gamble, and the writes can't be taken back in one step. On TW-13503 the first run would have filed duplicate sub-tasks and posted comments to the team.