Skip to content

docs: define carve-changesets suite handoffs #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shaug merged 1 commit into from
Jul 22, 2026
Merged

docs: define carve-changesets suite handoffs #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ summary: Chronological history of repository and skill changes.

## 2026-07-21 — Consolidated carve-changesets CLI and live contract

- docs: define carve-changesets suite handoffs
- feat: add stateless changeset merge and propagation
(`925affa807c203824127a0fe5e0fb084f14f378d`)
- refactor: make strict apply use one proof
(`c8ca89566562d7d154bfe1a1711140323e3ba9f8`)
- fix: bind GitHub operations to the selected remote
Expand Down
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ Current reusable agent skills:
- `skills/implement-epic` — traverse live GitHub or Linear epic graphs and
delegate each selected child to `implement-ticket`, then refresh graph state
and verify separately authorized epic closeout
- `skills/carve-changesets` — recompose a review-ready source branch into a
stateless chain, review each changeset through `review-code-change`, and
delegate each published PR lifecycle to `babysit-pr`
- `skills/review-code-change` — orchestrate the repository-owned review lenses
into one evidence-bound, deduplicated verdict
- `skills/prepare-changesets` — decompose a large, review-ready branch into a
Expand All @@ -41,6 +44,11 @@ implement-epic
├── review-code-change # initial candidate review
└── babysit-pr # published PR lifecycle
└── review-code-change # after a head-changing fix

carve-changesets
├── review-code-change # direct per-changeset review
└── babysit-pr # each published PR lifecycle
└── review-code-change # after a head-changing fix
```

Compatible runtimes may provide named subagents or equivalent isolated
Expand Down
11 changes: 10 additions & 1 deletion skills/carve-changesets/references/SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,11 +303,17 @@ Publish authority does not permit merging, force-pushing any branch, changing
the source or base branch, or speaking in review threads unless separately
authorized.

After publication, it permits delegating each exact changeset PR to `babysit-pr`
with the `ready_to_merge` completion policy. Existing changeset candidate
mutation and push authority may be passed through, but merge authority must be
withheld and reply or thread-resolution authority remains separate.

#### Merge-and-propagate

Includes publish authority and additionally permits:

- delegating each PR lifecycle to `babysit-pr` under an explicit merge policy;
- delegating each PR lifecycle to `babysit-pr` with `merge_when_ready` and
passing through explicit merge authority without expansion;
- merging a changeset PR only after every applicable gate passes;
- updating downstream PR bases after an upstream merge; and
- force-pushing with `--force-with-lease` only to downstream changeset branches
Expand All @@ -322,6 +328,9 @@ The base branch must never be force-pushed under any authority.

### Suite seams

The candidate packet, authority mapping, ownership transfer, and terminal-result
protocol are defined in [suite-handoffs.md](suite-handoffs.md).

`carve-changesets` uniquely owns:

- decomposition analysis and changeset boundary selection;
Expand Down
123 changes: 123 additions & 0 deletions skills/carve-changesets/references/suite-handoffs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# Per-changeset review and PR lifecycle handoffs

This reference defines how `carve-changesets` composes with the repository-owned
`review-code-change` and `babysit-pr` skills. The normative changeset state,
authority, and safety rules remain in [SPEC.md](SPEC.md). The delegated skills'
live contracts remain authoritative for their internal behavior.

## Ownership boundaries

`carve-changesets` owns changeset boundaries, materialization, chain ordering,
metadata, whole-chain equivalence, and downstream propagation. It constructs
review and PR-lifecycle handoffs, applies accepted review fixes, and verifies
returned identities before promoting chain state.

`review-code-change` is read-only. It reviews one exact changeset candidate and
returns an evidence-bound verdict; it does not edit a changeset, choose a new
boundary, mutate the plan, or push a branch. `carve-changesets` owns any
accepted fix and must rebuild invalidated validation and review evidence
afterward.

Once ownership of a published PR is delegated, `babysit-pr` exclusively owns
that PR's current-head CI, failed-check diagnosis and eligible retries,
published feedback, ticket-scoped candidate fixes, post-fix repository review,
base drift, mergeability, and optional merge. `carve-changesets` must not run a
competing watcher, retry checks, disposition review threads, or mutate the
delegated candidate.

The reverse boundary is equally strict: `babysit-pr` does not rebase, renumber,
or retarget the remaining stacked changesets and does not perform downstream
propagation. After a verified merge result returns, those chain mechanics belong
to `carve-changesets` again.

## Per-changeset review packet

Construct a fresh `review-code-change` packet for changeset *i* from raw,
current evidence. Never add the implementation transcript, expected findings,
prior conclusions, or fixture answers.

| Packet section | Changeset evidence |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repository` | Exact repository identity and the stacked base branch: the chain's base branch for changeset 1, otherwise changeset *i - 1*'s branch. |
| `candidate` | Exact changeset head SHA, exact stacked-base SHA as `comparison_base_sha`, and the complete unified diff from that stacked base to the changeset head. |
| `change_contract` | Goal derived from the changeset slug and description, with `pr_notes` preserving scaffolding, flags, and intentional incompleteness. Acceptance criteria state the observable outcome at this position; non-goals name work reserved for later changesets; preserved behaviors include the applicable invariants from `SPEC.md`. |
| `sources` | Applicable repository instructions, `SPEC.md`, named architecture or design documents, and representative nearby patterns for the files changed by this changeset. |
| `validation` | At least one focused and one full entry with exact commands and results. Focused evidence covers the chain prefix through changeset *i*; full evidence records the approved repository or whole-chain validation applicable at this boundary. Required unavailable checks are recorded as unavailable, never silently omitted. |
| `worktree` | Tracked, staged, unstaged, untracked, and ignored state when needed to prove candidate integrity. |

The packet must satisfy the bundled review-suite contract and schema. In
particular, the diff is complete and candidate-bound, acceptance criteria are
non-empty, and every required validation command has an exact result or an
explicit unavailable reason.

Review is required before claiming `chain_ready` or `prs_open`, and the result
must be clean for every exact changeset candidate represented by that terminal
state. It is also required before a published candidate is handed to
`babysit-pr` when no current clean result exists. Any changeset head change
invalidates its packet, validation, and verdict; rebuild all three before
continuing.

For base-only drift, retain review evidence only when the review-suite contract
allows it: the effective diff and resulting tree are unchanged, no conflict or
relevant overlap exists, repository policy permits retention, and the proof is
recorded. Otherwise rebuild the affected packet and review.

Review may run earlier after a changeset has been materialized, but an early
result does not establish a later terminal state unless its candidate identity
still matches. `plan_ready`, dry-run planning, and status-only operations have
no materialized candidate to review and do not require or invent a packet.

## PR lifecycle handoff

Delegate only an open PR whose exact head and predecessor base match the
rehydrated chain. Immediately before handoff, capture and verify:

- repository, PR number and URL, head repository, branch, head SHA, base branch,
and base SHA;
- changeset index, slug, source identity, required metadata, complete diff,
resulting tree, and commit history;
- tracked, staged, unstaged, untracked, and ignored worktree state;
- focused and full validation evidence and the current clean per-changeset
review result;
- required CI, human, connector, comment, formal-review, reaction, and thread
gates, including documented absence;
- completion policy, retry and review-cycle budgets, and the separately granted
mutation, push, retry, reply, resolution, and merge authorities; and
- exclusive mutation ownership plus the changeset scope and non-goals that
constrain any PR fix.

Candidate identity and authority must match the live `babysit-pr` contract.
Reject stale, conflicting, forked, superseded, or ambiguously owned PR state
instead of delegating it.

| Active `carve-changesets` authority | `babysit-pr` policy | Passed authority |
| ----------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Decompose-only | No handoff | Remote publication is forbidden. |
| Publish | `ready_to_merge` | Existing changeset candidate mutation and push authority may be passed through. Merge is withheld; reply and thread-resolution authority remain separate. |
| Merge-and-propagate | `merge_when_ready` | Explicit merge authority is passed through without expansion. Reply and thread-resolution authority remain separate. |

Ordinary pending CI or review time is not a reason for `carve-changesets` to
reclaim ownership. A head-changing fix made during the delegation requires
`babysit-pr` to rerun affected and full validation, obtain a fresh
repository-owned review, push the new candidate, and rebuild invalidated remote
gates before it can return a terminal result.

## Terminal-result mapping

Reread live GitHub and git state before accepting a returned terminal result.
The repository, PR, branch, head, base, completion policy, authority, and gate
evidence must match the handoff. A stale or conflicting result maps to
`blocked`; do not translate it into progress.

| `babysit-pr` result | `carve-changesets` handling |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready_to_merge` | Accept only for the exact open, mergeable candidate after every applicable non-merge gate passes. With publish authority, this contributes to `prs_open`; merge remains withheld. |
| `merged` | Independently verify the exact PR merged and its result is represented on the live base. Rehydrate the chain, propagate the downstream branches and PR bases under merge-and-propagate authority, then hand the next exact PR to `babysit-pr`. Claim `all_merged` only after the final PR, propagation, equivalence, validation, and cleanup requirements in `SPEC.md` all pass. |
| `closed` | Return `blocked` with `PR closed without merge` unless a canonical replacement is independently verified; preserve partial artifacts. |
| `blocked` | Return `blocked` with the concrete reason, exact candidate reached, preserved artifacts, and one action required to resume. |

When propagation changes a downstream head or effective candidate, prior review,
validation, CI, and feedback evidence is invalid. Rebuild the per-changeset
packet before the next lifecycle handoff. When only the stacked base identity
changes, apply the review-suite base-drift rules rather than assuming evidence
survives.
Loading