Skip to content

tweaks/several-shelf-items-one-review (TW-taq0ps) - #31

Merged
thegrubbsian merged 9 commits into
mainfrom
tiller/tweaks/several-shelf-items-one-review
Nov 19, 2026
Merged

thegrubbsian merged 9 commits into
mainfrom
tiller/tweaks/several-shelf-items-one-review

Conversation

@thegrubbsian

Copy link
Copy Markdown
Member

Adds a batch noun for shelf work, so "fix these n bugs under one PR" has a lawful path: several bugs, chores, or tweaks on one branch, one pull request, crossed to done together by one tiller sync (TW-taq0ps).

Change

tiller add batch <key> --title <text> <member>...     # 2+ members; born ready, no approval of its own
tiller batch <batch> --add <member> --remove <member>
tiller claim|release|reassign batch <batch>
tiller start|check|submit|resume|cancel batch <batch>
tiller show|status batch <batch>     tiller ls batches
tiller sync [--accept-fast-forward <batch>]
  • The record lives at .tiller/batches/<key>/batch.yml with a BT- id and no contract file. Its branch is tiller/batches/<key>. Membership is stored on each member as batch: BT-....
  • The batch alone carries the lifecycle. A member keeps its stored status, reads the derived phase batched, and crosses with done_basis: batched.
  • start batch refuses until every member is approved and ready. A member of a live batch refuses claim, start, check, submit, and resume, and names the batch.
  • Membership is editable while the batch is ready, in_progress, or check. An edit at check stales recorded gates. Cancelling the batch releases its members; a batch that loses its last member is cancelled.
  • The queue, the readout, tiller next, show, status, ls, search, and query treat a batch as one unit of work.
  • The execute guidance has a Batched shelf work section with choreography. It says an agent asked for a shared review of shelf work must use a batch, every commit carries the id of the member it serves, and each bug needs its own regression test.

Review findings fixed before this PR

An independent review found that a batch could cross done with no members, because the guidance never committed the member state files that hold the batch pointer. Three layers now close it: the choreography names that commit, check batch and submit batch refuse batch_state_uncommitted, and sync leaves a merged batch with no members in_review and reports it. Batch events no longer land on a member's History as its own, the unrecorded-merge warning gives correct advice for a batch, and tiller next no longer offers a batch that cannot start.

Judgment calls beyond the settled decisions

  • submit batch --recover-merged refuses. The message says to cancel the batch and recover each member.
  • Cancelling a member while its batch is in review refuses, as membership edits do. Returning a member to proposed is refused once the batch has started.
  • No merge_batch queue kind was added. An in-review batch appears as an in-review bug does: in tiller next and through its attest rows.
  • rename, order, and transfer have no batch arm.
  • The sync guard detects a batch with zero members. A batch where only some pointers reached the integration branch still crosses with the members it sees.

Open ruling

batches becomes a reserved epic key. A released project with a non-draft epic keyed batches would be refused by the schema 16 migration. This was found by reading, not by a run.

Schema, generation, console

  • Folded into schema 16, which is merged and unreleased. No new migration. Orientation generation 63 to 64.
  • ui/ is untouched; the console is tweaks/console-shows-shelf-batches (TW-5u3b5y). The serve endpoints now answer for a batch (/api/node/batch/<id>, /api/ls?noun=batch, board streams, evidence), so batch links no longer 404, but the console has no batch page design, labels a search section "Batchs", and still shows a batched member as Ready with no batch named. The console was read, not run.
  • TestVocabularyCoversEveryTransition skips the batch noun until TW-5u3b5y adds its event types to ui/src/lib/vocabulary.json.

Merge with a merge commit, not a squash, so tiller sync can record the tweak done.

Verification

  • Tests at the store, mutate, views, serve, and CLI layers, including a "seven bugs, one PR" end-to-end test, the partial-sync re-sync path, and pinned guidance text.
  • tiller check tweak green: build, tests, lint.
  • The built binary was driven through the whole story on a scratch project: three bugs batched, started, checked, submitted, merged with a merge commit, and one sync recording four done crossings.

Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
A batch is one review of several bugs, chores, or tweaks. Its record lives at
.tiller/batches/<key>/batch.yml with a BT- id and no contract file, and it
carries the shelf execution body, so claim, start, check, submit, resume, and
the done crossing reuse the shelf code paths. Membership is stored once, on
the member, as a batch pointer.

A member keeps its stored status and reads the derived phase batched. It
refuses claim, reassign, start, check, submit, resume, resolve --by, remove,
and merged review recovery, naming the batch. start batch refuses until every
member is approved. Membership edits are allowed in ready, in_progress, and
check, stale the gates at check, and cancel a batch left with no members.
Cancelling a batch releases its members and cancels none.

Sync observes a batch on its own branch from in_review exactly as a shelf
node, then crosses every member with done_basis batched in the same run. The
unrecorded-merge warning reports the batch in place of its members.

The record is folded into schema 16; the 15 to 16 migration note says so.

Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
tiller add batch creates a batch and tiller batch --add/--remove changes its
members. claim, release, reassign, start, check, submit, resume, cancel,
attest --gate, show, status, ls, and sync --accept-fast-forward take batch as
a noun. Every batch rule that refuses is a blocked answer carrying the batch
and the command to run instead.

show and status on a member name its batch with the batch's status, branch,
and PR, and on a batch list every member with its stored status and the
highest member severity. The queue, the readout, and tiller next hold a batch
as one unit of work and never offer its members, except that a proposed
member still queues for its own approval.

An end-to-end test drives seven bugs through one batch, one branch, one
submission, one merge, and one sync.

Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
tiller guide execute gains a Batched shelf work section and choreography. It
says an agent asked for a shared review of shelf work must use a batch and
never a hand-named branch, that every commit on the batch branch carries the
id of the member it serves, and that each bug still needs its own regression
test. A batch is one unit of work with one worktree, and naming one scopes the
run to it.

The orientation defines batch and batched, puts add batch and batch in the
resolve delegation class, and moves to generation 64. The artifact schema
gains a Batches section, the CLI surface the command contract and refusal
reasons, and the command reference a Batches section. The distribution spec
notes that batches ride the schema 16 stamp.

Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
…t it

A batch's membership lives in each member's state file, and sync reads the
integration branch. A member pointer that was never committed on the batch
branch left sync crossing the batch with no members, closing it over bugs
that stayed ready. check batch now refuses batch_state_uncommitted while a
member's state file is uncommitted, submit batch also while the batch record
is, and sync leaves a merged batch with no members in review and reports it
with the repair.

Batch events target the batch alone and name members in their after map, and
each member gets its own batch.<noun> event when it joins or leaves, so a
member's history never shows the batch's verb or status. A batch cancelled
because its last member left records cancel.batch, and a member's cancel
names the batch it left.

A ready batch with an unapproved member is no longer offered as work or
counted as ready. A member's legal moves drop cancel once its batch is in
review or done. search finds a batch, query follows batched_in and batches,
the board streams list a batch in place of its members, and the serve node,
list, and evidence routes answer for the batch noun.

Also: the unrecorded-merge advice is correct for a batch, a fast-forward
assertion on a member names its batch, --add and --remove of one node is
refused, stale gates are reported only when something was staled, and a
blocked contributor removal names a batch's own remedy.

Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
The batch choreography now makes the first commit on the batch branch carry
the batch record, every member's state file, and their events, and says the
same for every later membership change. The orientation states the rule, and
the specs describe the commit guard, the sync guard and its warning, the
batch event shapes, the batched_in relationship, and the corrected crossing
order in the command reference.

Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
Signed-off-by: JC Grubbs <grubbs.jc@gmail.com>
@thegrubbsian
thegrubbsian merged commit 3a316dd into main Nov 19, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant