simiancraft/simiancraft-skills / skills/carve-github-issue
carve-github-issue
VerifiedBreak one GitHub issue that is too large to work into sub-issues, unattended, and keep the carving honest as the children close. A carver names the pieces along the highest natural seam (domain, tier, route, area, file, unit, material), matches each against the backlog so nothing is authored twice, and a second engine confirms the cut covers the parent before anything is created. The parent becomes a trunk that is finished by closing its children; every child close re-checks the trunk, and a trunk with nothing left goes back to the appraiser. Use when the task is "this issue is too big, split it", "carve #N into sub-issues", "is this carving still good", or when burn-down-github-issues sizes an issue over its ceiling. Requires a per-repository config (its own, or the burndown's), the codex and claude CLIs for the default seats, and GitHub sub-issues on the repository. Skip for fixing anything; this skill writes only to the tracker.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| carve.ts | script | 10.6 KB |
| lib/callbacks.ts | script | 1.4 KB |
| lib/carve.test.ts | script | 19.0 KB |
| lib/carve.ts | script | 25.6 KB |
| lib/claims.test.ts | script | 12.9 KB |
| lib/claims.ts | script | 13.8 KB |
| lib/fake-tracker.ts | script | 9.4 KB |
| lib/knife.test.ts | script | 52.3 KB |
| lib/knife.ts | script | 52.9 KB |
| lib/record.ts | script | 12.7 KB |
| lib/tree.ts | script | 23.3 KB |
| lib/validate.test.ts | script | 12.8 KB |
| prompts/carve.md | markdown | 8.1 KB |
| prompts/confirm-carve.md | markdown | 4.1 KB |
| prompts/revisit.md | markdown | 4.9 KB |
| references/adopting.md | markdown | 6.3 KB |
| references/callbacks.md | markdown | 1.7 KB |
| references/lifecycle.md | markdown | 29.7 KB |
| references/seams.md | markdown | 9.1 KB |
| references/the-record.md | markdown | 6.6 KB |
references/lifecycle.md
View on GitHub# The lifecycle
The durable contract of the knife, the burndown, the fix pipeline, and the appraiser on one tracker: every state an issue can be in, every transition, every announced intent and its repair, the invariants each has a test or a gate for, and the windows that remain on a tracker without compare-and-swap. This is the reference the code is checked against; the record grammar is in `the-record.md` and the methodology in `seams.md`.
A trunk is worked by closing its children; a leaf is worked by the fix pipeline; the knife owns every transition between. The board a person will eventually see is these states as columns, derivable from the tracker alone.
Only so many things can happen to a ticket. This section names all of them; the rest of the collection is the machinery that makes each transition hold. Every state is derived from the issue itself (its labels, its sub-issue tree, its latest record); nothing in a run directory decides a state, and every multi-write transition is announced on the tracker with its full payload before it starts so any machine can finish it. That property is deliberate: these states are the columns of the board this work will eventually be shown on, and a state a person cannot read off the issue is a defect.
One rule governs every cost trade-off below: churn spent re-reading an existing issue is cheaper than the churn a wrong carving multiplies into. Where the collection can spend an agent turn or a tracker read to be sure, it does.
### States
Derived in this precedence; every issue is in exactly one. "Unreleased record" means `applying` or `live`. A deleted issue is not in any state; its former children and blockers see it as `DELETED`.
| Precedence | State | Derived from | Who owns it |
|---|---|---|---|
| 1 | **Closed** | `state: CLOSED`; `stateReason` `COMPLETED` or `NOT_PLANNED` | terminal |
| 2 | **Held** | any of `needs-human`, `needs-decision`, `loop/skip`, `loop/parked`, any `loop/dlq: <phase>` on the issue itself; or `loop/paused` on the issue or on any ancestor | a person, or the parent that paused it. A hold on a trunk stops the trunk, not its leaves; only `loop/paused` reaches down. `loop/paused` is owned by trunks alone: each trunk's pause is a bot-authored pause marker on the child naming the trunk, the label stays while any trunk's marker is unreleased, and a person who wants a leaf held uses `loop/skip` or a `needs-*` label, never `loop/paused`; the label with no marker is torn and the sweep removes it with a comment |
| 3 | **Claimed** | `loop/carving` or `loop/working` with an unexpired, unreleased claim | the run that claimed it |
| 4 | **Trunk** | an unreleased record, or any open child, or `loop/released` (a release whose appraisal has not run yet) | the knife; workers take its leaves; the burndown runs the release appraisal under its own claim |
| 5 | **Blocked** | a `blocked-by` on the tracker or in any ancestor's record whose target is not closed `COMPLETED` | its blocker; a leaf whose blocker is closed `NOT_PLANNED`, deleted, or part of a cycle goes Held (`needs-human`) by the sweep when it has no open parent, and triggers its parent's revisit when it has one |
| 6 | **Oversized** | sized over the ceiling | the knife (carve) |
| 7 | **Leaf** | sized at or under the ceiling | the fix pipeline |
| 8 | **Unsized** | no `size:` label | the appraiser |
`loop/carved` is the trunk's label for people and for the worker's selection; a trunk that lost it is still a trunk by this table and is re-labelled at its next revisit. `loop/carve-gen: N` is the second way the sweep finds an unreleased trunk; both come off at release, and `loop/released` takes their place until the appraisal has run.
### Transitions
| From | Event | To | Notes |
|---|---|---|---|
| Unsized | appraiser: `valid` at or under the ceiling | Leaf | the size must be on the scale |
| Unsized | appraiser: `valid` over the ceiling | Oversized | fires the size callback, which runs the knife with the ceiling the loop is using |
| Unsized | appraiser: close confirmed / hand-off | Closed / Held | the close is the close intent (`closeIssue` posts the comment with its marker, then closes); its finisher re-reads the issue first and abandons it for a trunk (other than one carrying `loop/released`, which the appraiser is being asked to finish) or an issue claimed by a run other than the one the appraiser runs under; the hand-off is an intent finished by the label |
| Unsized | appraiser: crash, malformed answer, confirmer failure | Unsized | `loop/appraisals: N`; on reaching `maxAppraiseAttempts` (3) goes to the appraisal dead-letter queue (`loop/dlq: appraisal`) with the log tail |
| Oversized | knife: `carve` confirmed | Trunk | generation 1: claim, `applying` record, children, edges, callback, `live` record, labels, unclaim |
| Oversized | knife: `small-enough`, `indivisible`, `nothing-left`, all confirmed | Held (`needs-human`) | the carver's opinion about the issue, which a person weighs; both opinions on the thread; a `live` record with the verdict |
| Oversized | knife: disputed past the round cap | Dead letter (`loop/dlq: carve`) | two engines that never agreed is the machine giving up, not an opinion; both opinions on the thread; a `live` record; removing the label is a redrive |
| Oversized | knife: `too-uncertain` confirmed | Held (`needs-decision`) | the question on the thread; a `live` record with the verdict |
| Oversized | knife: `failed` (crash, invalid answer, upstream refusal) | Oversized | `loop/carves: N`; on reaching `maxCarveAttempts` (3) goes to the carve dead-letter queue (`loop/dlq: carve`) with the log tail; `busy` never counts |
| Oversized | depth cap | Dead letter (`loop/dlq: carve`) | the record says `indivisible` with the depth stated |
| Oversized | another run's claim, or a worker's claim, is live | Oversized (`busy`) | retried by the sweep once the claim is gone |
| Leaf | worker starts | Claimed (`loop/working`) | after the live gate and before the lane is created; released at the terminal outcome, whatever it is; renewed every five minutes for the life of the run |
| Claimed (working) | `merged`; `already-fixed`, `obsolete`, `answered` confirmed by the second engine | Closed (`COMPLETED`) | the pipeline re-reads topology before merge and before every close; the close hook posts a roll-up and revisits the parent when there is one |
| Claimed (working) | a close the second engine disputed; `needs-*`; parked; dlq; topology changed under it | Held | the trunk waits; the pull request, if any, is parked with the reason; a merge that landed before the close was refused parks the issue with the merge named |
| Claimed (working) | `out-of-band` with points on the scale and over the ceiling | Oversized | recursion; the depth guard bounds it; any other `out-of-band` is `failed` |
| Claimed (working) | worker or confirmer `failed` on the first attempt | Leaf | `loop/attempts: N`; on reaching `maxWorkerAttempts` (3) goes to the work dead-letter queue (`loop/dlq: work`) with the log tail |
| Claimed (working) | worker or confirmer `failed` on a revision | Dead letter (`loop/dlq: work`) | at once, since the pull request exists and there is no Ready to go back to; counts `loop/attempts: N` |
| Claimed (working) | the run dies | Leaf | the next run's stranded pass takes a fresh claim and resumes the lane, sends the issue to `loop/dlq: work` with the reason when the lane is dirty or its pull request has no usable verdict, or any machine's sweep clears the expired claim |
| Leaf | a person closes it | Closed | `COMPLETED` completes its criteria; `NOT_PLANNED` orphans them; a dependent sibling stays Blocked |
| Trunk | anything in the fingerprint changes (a child's state, body, title, labels, comments, edges, or record; a blocker's state; the trunk's body, title, labels, or the text of any comment by a person) | Trunk | revisit: `still-good` (new record), or `amend` confirmed (new generation), each with its pause set |
| Trunk | revisit: hand-off confirmed | Held | the trunk's hold; the leaves the question touches, and their dependents along recorded edges, transitively, get `loop/paused`; the rest keep working. A hand-off forced by a cap on a seam dispute pauses every open leaf, since the whole carving is in question |
| Held (trunk) | a person answers and removes the hold | Trunk | the sweep sees the hold gone (a redrive) and hands the trunk to the knife, which forces a revisit whatever the rest of the fingerprint says; that revisit's record, and only it, opens the next epoch with `revisits: 0`, lifts every pause this trunk recorded, and amends as the answer requires, including a rollback piece for work that landed on the old premise; a released trunk re-enters the release appraisal instead |
| Trunk | revisit: `exhausted` confirmed | Trunk (`loop/released`) | the release intent: a `released` record; size label off; `loop/carved` and `loop/carve-gen` off; counters off; `on-carve-pass`; `loop/released` on, which completes it; the standalone command stops here and reports `left-alone` on any later visit while the label stands |
| Trunk (`loop/released`) | the burndown's release appraisal (the hook in the same run, or the sweep's first pass at any age) | Leaf, Trunk (carve mode), Closed, or Held | a repair under a fresh `loop/carving` claim, re-run from the tracker's state until `loop/released` is gone: with no size label, `appraiseIssue` with `release: true` sizes the remainder with the closed children in view and fires no size callback; a `valid` size writes the size label; then, with a size label at or under the ceiling, `loop/released` off; with one over the ceiling, `carveIssue` in-process as the next generation with the closed children adopted as completed pieces (its `applying` record supersedes the `released` one as the newest announcement) and, after its `live` record, `loop/released` off; a close goes through the close intent and leaves `loop/released` on the closed issue, which is harmless; `retry`, a crash, or a malformed answer counts `loop/appraisals: N` and leaves `loop/released` on, and at `maxAppraiseAttempts` the trunk goes Held (`needs-human`) with the label still on, so the hold's removal re-enters here |
| Trunk | revisit disputed past the round cap; `amend` on reaching `maxGenerations` (5) in this epoch; `still-good` on reaching `maxRevisitsPerGeneration` (10) in this epoch | Dead letter (`loop/dlq: carve`) | the label and children stay; a person resolves; removing the dead-letter label is a redrive as above |
| Oversized | knife hand-off on an issue that has no generation yet | Held | `loop/handed-off` marks it for the sweep, so a hold removed after the issue aged out of the window is still seen; the label comes off when the hold does |
| Trunk | knife `failed` | Trunk | `loop/carves: N` as above; the sweep retries while the tracker still differs from the record |
| Trunk | a person closes it with children open | Closed | the sweep releases every pause marker the trunk placed, on every open issue it paused; children continue as leaves, and a child of a closed parent that becomes invalidly blocked is treated as a root (handed to a person) |
| Leaf (formerly released) | a person reopens a child | Trunk (carve mode) | closed children never route; open ones do; the reopened child is adopted, not re-authored |
| Held | a person removes the hold label | whatever the table derives | a counter at its cap is cleared by the sweep first; `needs-decision` answered re-enters with the answer in the thread |
| Closed | a person reopens | whatever the table derives | a reopened child changes the tree and triggers a revisit; a reopened child of a released trunk makes the trunk a Trunk again, in carve mode |
A close followed by a reopen before any run sees either leaves the fingerprint as it was; that is not an event, and nothing is lost by treating it as none.
### Terminal cases
Closed, and every Held state. Nothing else is terminal, and every non-terminal state has a retry path with a counter: `loop/appraisals: N` for the appraiser, `loop/carves: N` per generation for the knife, `loop/attempts: N` and `loop/reviews: N` for the fix pipeline, `maxGenerations` and `maxRevisitsPerGeneration` per trunk per epoch, `maxDepth` per tree. Recursion is bounded twice: an authored child is at most the ceiling, so strictly smaller than its oversized parent on the scale, and the depth cap ends any tree the scale did not; an adopted or referenced piece keeps its own size and is carved on its own depth.
### Intents and repairs
Every intent is announced first, with everything a finisher needs. A knife intent is finished by whoever finds it, beginning with a claim, so two machines that find one announcement do not both finish it; a finisher that finds the announcement younger than two minutes waits thirty seconds and re-reads before creating anything, so read lag does not turn a finished write into a second one. An appraiser intent (a hand-off, a close) is finished by the run that announced it, in process, and by nothing else: the sweep neither finishes nor abandons one, and a later appraisal of the issue re-derives its own verdict, reusing a matching announcement younger than thirty minutes on the same open issue rather than posting a second and otherwise ignoring it. A crash between an appraiser's announcement and its label or close therefore costs one duplicated comment, never a hold or a close a person did not ask for. Only the newest announcement on an issue is ever finished; an older one is superseded by it. A finisher re-checks each pending write's target before making it: a write whose precondition a person has since undone (a counteraction) is marked `abandoned` in the journal (the knife's local file, per issue and generation, of the writes this machine has seen done or abandoned) and skipped, the rest of the intent is finished, and a revisit follows so the person's change is judged rather than overwritten.
| Intent (the announcement, with its payload) | Finished by, in order | Completion predicate |
|---|---|---|
| `applying` record: the accepted cut, the ledger, the supersessions, the pause set | children, adoptions, references, edges (obsolete edges removed), supersessions (each a close intent with `reason: superseded by #n`), pauses, callback, `loop/carve-gen: N`, `loop/carved`, `loop/handed-off` off, counters cleared, `live` record | a `live` record of the same generation exists |
| `released` record, linking every closed child | size label off, `loop/carved` and `loop/carve-gen` off, counters off, callback, `loop/released` on | `loop/released` is present; or the release appraisal has consumed it: a size label is present, a newer record exists, or the issue is closed. A later reopen never revives a consumed release |
| `<!-- carve-handoff verdict=V gen=G -->` with the reason, the affected criteria, the pause set, both opinions when disputed, and the log tail when a counter tripped | `loop/handed-off` when the issue has no generation, hold label, pauses, callback, `live` record with the verdict | a `live` record with that verdict exists after the comment |
| `<!-- appraise-handoff verdict=V -->` with the reason and the log tail when a counter tripped | the hold label | the hold label is present |
| `<!-- loop-close verdict=V by=R -->`, the comment `closeIssue` posts, with the explanation and both opinions when a confirmer ran (R: `appraiser`, `worker`, `knife`, `reconcile`) | the close, `COMPLETED` or `NOT_PLANNED` as the verdict says | the issue is closed with the reason the verdict names (`NOT_PLANNED` for `obsolete` and `superseded`, else `COMPLETED`); a finisher that re-reads a trunk without `loop/released`, or a foreign claim, abandons it with a comment and leaves the issue selectable |
Repairs, each re-run from the tracker's state by the sweep or on entry to an issue, none announced:
| Repair | Rule |
|---|---|
| claim | the claim comment, then the label; the work; the unclaim comment; then the label off when no other unreleased claim comment exists and the journal has no pending step. A run that leaves a step pending (a thrown write, a kill) posts its unclaim and leaves the label on, so the sweep's first pass finds the issue; the sweep finishes what it finds and only then removes a label with no live claim, an expired claim, or an unclaim with the label still on, each with a comment. A claim past `expires` is not live: the live gate and the knife ignore it before any sweep has run |
| pauses | markers and `loop/paused` match the newest `live` record's pause commands: a marker naming this trunk on each commanded child, the label on; markers released and the label off where no unreleased marker remains; a `loop/paused` with no marker removed with a comment |
| the appraiser's `valid` size | the size label, then the size callback; a crash between the two loses that callback invocation and nothing else, since the sweep's second pass routes an oversized label without one (a named boundary: the knife reads the label, so the label cannot follow the callback) |
| the release appraisal | as the transition table's `loop/released` row: each step keyed on what the previous step wrote (no size label: appraise; size label at or under the ceiling: `loop/released` off; size label over it and no record newer than the `released` one: carve; a newer record: `loop/released` off), until `loop/released` is gone |
| the held snapshot | a Held trunk whose newest record's `seen.holds` does not list its hold gets a record of the same state (`live` stays `live`, `released` stays `released`), the same ledger and `revisits`, a fresh fingerprint, and `note: hold-observed`, with no agent turn |
Callbacks run before the write that completes their intent, so a crash between the two replays the callback on repair; that is the only way a callback runs twice, and the payload's idempotency key (`issue`, `generation`, `epoch`, `revisits`, `verdict`) lets an adopter drop the replay. A callback is invoked when its process has been spawned and reaped; its exit code is logged and a non-zero exit is not retried, since the collection has no way to tell a failed side effect from a completed one. `references/callbacks.md` says both.
### Invariants
Each has a test in the knife's suite or a gate in its adoption record. Every "refuses" is a check at the last read before a write; the windows that remain after that read are listed under Boundaries.
- A confirmed cut is applied only to the trunk it was confirmed against: the fingerprint is re-read after the agreeing confirmer and immediately before the `applying` record, and any difference restarts from the carver.
- A referenced or adopted issue closed `NOT_PLANNED` (which is also how the knife closes a superseded child) or deleted does not complete a criterion; the ledger marks it `orphaned`, `still-good` is invalid while any criterion is orphaned, and the revisit must re-own it.
- A criterion the thread has retracted is `withdrawn`, citing the comment; it counts as done for exhaustion; if the comment disappears or its text changes the criterion is `open` again, and the sweep sees it because comment bodies are in the fingerprint.
- Mode is chosen from the latest record, never from the tree, so a released trunk is never revisited into a second `exhausted`.
- Closed children never route an issue to the knife; only open children, an unreleased record, `loop/released`, or an oversized label do. Release removes both trunk labels, so a released trunk sized small is an ordinary leaf.
- Merge reconciliation refuses a trunk, a held, paused, or blocked issue, or a claimed one, on its snapshot and again on the re-read immediately before closing, and requires a closing keyword at the start of a line or after a period, not preceded by "not" or "n't", before an issue number.
- A worker refuses to start on, merge, or close a trunk, a held issue, a paused issue (itself or an ancestor), an oversized issue, or a leaf whose blocker (on the tracker or in any ancestor's record) is not `COMPLETED`: the live gate reads before claiming, and every close and merge path reads again.
- The knife refuses to carve under a live worker claim, a worker refuses to start under a live knife claim, and the appraiser refuses to close a claimed issue or a trunk when it re-reads before closing. Claims arbitrate only among runs that authenticate as one GitHub account, which `references/adopting.md` requires of every machine on one tracker; a run whose `botLogin` cannot be read refuses to start.
- Every close of a leaf, wherever it comes from, is followed by a revisit of its parent: immediately when the loop made the close, on the next run's sweep otherwise, because the fingerprint carries child states.
- Two roll-ups for one close are impossible: the roll-up is keyed by child, event, and the close time, and the hook skips one the thread already carries.
- The knife's own writes never trigger a revisit: the fingerprint excludes bot-authored marker comments and `loop/*` labels, and a hand-off writes its hold label before its record.
- `busy` never spends an attempt.
- Every marker is trusted only when its comment's author, or for the child-body marker the issue's author, is `ctx.botLogin`; a marker in a person's comment or body is ordinary text. A finisher adopts an existing issue as a pending piece only when all of these hold: the marker matches the generation and piece, the issue's author is the bot, its parent is the trunk, its title is the piece's title, and its body equals `renderChildBody` for the piece after whitespace normalization; on any other match it stops with `needs-human` naming the issue, since something claims to be the knife's work and is not.
- A held trunk is snapshotted by the repair above, so the hold's removal is a fingerprint difference the next sweep sees; the snapshot never changes the record's state, so a released trunk stays in release appraisal.
- `loop/paused` on an issue with no unreleased pause marker is torn: the sweep's first pass lists the label and removes it with a comment. A person's hold on a leaf is `loop/skip` or a `needs-*` label, which nothing in the collection removes.
### Boundaries
These windows exist on any tracker without compare-and-swap, and this document names them instead of claiming to close them.
- A hold, blocker, pause, or child added between a worker's last read and its merge or close; a blocker reopened in that window.
- A trunk changed between the knife's final fingerprint read and the `applying` record landing.
- A reference gaining a parent between its final read and its attachment.
- The appraiser's re-read finding an unclaimed leaf and the knife claiming it before the close lands.
- Two claim comments briefly coexisting before the loser reads the winner; the design guarantees one recognized winner among runs that share the bot account and whose clocks agree to within a minute, not that two artifacts never coexist.
- Read-after-write lag on the tracker immediately after a comment or label write. The finisher's thirty-second wait narrows the window for a duplicated child; it does not remove it.
- Two trunks authoring one missing piece in the same instant. A later revisit of either may see the twin through normalization and supersede one; the lower issue number survives so both revisits agree; it is not guaranteed that either revisit sees it before the twin is worked.
- A person changing tracker state during any multi-write intent; the finisher honours what it can see and abandons the write it can no longer justify.
- The appraiser takes no claim of its own outside a release appraisal, so two machines appraising one unsized issue in the same minute spend duplicate turns; the close intent and the re-read before every close keep the outcome single.
- A person who edits an authored child's body to equal what the knife would have written is acting; the adoption check reads the current body, not its history.
- A person who deletes records, markers, or `loop/*` labels is acting. The knife trusts the larger of the label and the record for generations and counters, treats a missing record as a difference, and repairs torn labels; it does not defend against deliberate removal of every trace.
## Guards
- **Depth.** The root is depth 0; an issue at depth d is carvable iff d < `maxDepth` (default 3). At the cap the issue is `indivisible` with the depth stated. GitHub's limit is eight.
- **Fan-out.** `maxChildren` (default 8) open or new pieces per cut (a closed child a revisit adopts is history and does not count), and the trunk's `subIssuesSummary.total` plus authored pieces plus references to be attached at or under 100.
- **Floor.** No authored child under the scale's smallest rung, none over the ceiling, none without its own acceptance and proof; an adopted or referenced piece keeps whatever size it has and is carved on its own depth if it is over the ceiling. A file, unit, or material cut is admissible only when the physical boundary also owns one change or one reviewable outcome.
- **Counters.** Every cap in the collection trips on reaching N. `loop/carves: N`, `loop/appraisals: N`, and `loop/attempts: N` in the pattern of `loop/reviews: N`, incremented on a `failed` outcome only and written before the hand-off comment when the increment reaches the cap, cleared as a journal step of a confirmed verdict, and by the dead letter of their phase; `repairDurableState` takes the caps and repairs all four. `loop/carve-gen: N` is the generation high-water mark while the trunk is unreleased; the knife trusts the larger of the label and the newest record of any state. `maxGenerations` (5) and `maxRevisitsPerGeneration` (10) count within the current epoch, which the record carries; a person removing a hold from a trunk at either cap starts a new epoch, which the redrive revisit's own record opens; the sweep writes no record of its own for it. For a label counter at its cap whose hand-off comment carries its label, the sweep clears the counter when the hold is gone; the removal is the reset. The revisit cap is a known unknown: how often a healthy trunk is revisited is unmeasured, the record makes it measurable, and `references/operating.md` says to raise it or rethink the trigger if trunks reach it routinely.
- **Claims.** The knife posts a claim comment with `expires` thirty minutes out, then adds `loop/carving`, then re-reads; if an earlier unreleased, unexpired claim of either kind by another run exists (earlier by `databaseId`), it posts its own unclaim, removes nothing else, and returns `busy`. The worker does the same with `loop/working` after the live gate and before its lane is created. Both holders renew `expires` by editing the marker every five minutes on a timer for the life of the run, whatever the run is doing. A stranded resume takes a fresh claim; it never renews a dead run's. The sweep clears an expired claim, a label with no claim, or an unclaim with the label still on, each with a comment. The local `carve-<n>.lock` stays as the cheap first check on one machine.
- **Time.** The knife bounds itself: every agent turn has the runtime's 45-minute cap and rounds are capped, so a carve terminates by construction. The size callback that invokes it runs with no outer timer by default (`sizeCallbackTimeoutMinutes: 0`, validated as a non-negative integer); the burndown's shutdown kills its process group.
- **The worker's live gate and landing checks.** Immediately before claiming, `fixIssue` reads the issue and its ancestors and returns `left-alone` when the issue is Closed, Held (itself, or `loop/paused` on an ancestor), a Trunk, Oversized, or Blocked (on the tracker or in an ancestor's record), and `busy` when a foreign claim is live; then it claims, then it creates the lane. Immediately before merge, and immediately before every close in `land` and in `settleTerminalVerdict`, the pipeline re-reads the same and, on any refusal, parks the pull request with the reason and releases the claim; a refusal found after a merge landed parks the issue with the merge named.
## Revisit triggers
- **Inside the loop.** `closeIssue` awaits `ctx.onClosed(event)` after the close, so every close path (the fix pipeline, stranded resume, reconciliation, the appraiser) fires it; a throw is logged and never changes an outcome. The burndown's hook: if the closed issue has a parent, post the roll-up on the trunk (its marker keyed by child, event, and `closedAt`), skipping one the thread already carries; then `carveIssue` on the trunk, at most once per trunk per run (an in-process set; later closes in the same run are seen by the next sweep); after a confirmed `exhausted`, the release appraisal as the transition table says. A closed parent is logged and left alone.
- **Outside the loop.** The sweep runs after stranded-pull-request resume, under the loop lock, and in a dry run only logs. Three passes over `gh issue list --limit 5000 --state open --json <the tree fields>`. First, every issue labelled `loop/carved`, `loop/carve-gen: *`, `loop/released`, `loop/handed-off`, `loop/carving`, `loop/working`, or `loop/paused`: finish the newest unfinished knife intent (a `loop/released` trunk that is not Held gets its release appraisal); reconcile pause markers and labels to the newest record, removing a torn `loop/paused`; clear expired or torn claims, after finishing; snapshot a Held trunk whose record does not list its hold; where a hold has been removed since the newest record (its `seen.holds` lists one the tracker lacks), hand the trunk to the knife as a redrive (a forced revisit whose record opens the next epoch; a released trunk re-enters the release appraisal instead) and take `loop/handed-off` off; otherwise `needsRevisit(record, tree)` decides, and `no-record` hands the trunk to the knife. Second, every issue not in the first pass, not Held, not Claimed, and either sized over the ceiling and inside the age window, or with an open child at any age, is handed to the knife. Third, every leaf whose blocker is closed `NOT_PLANNED`, deleted, or in a cycle: with an open parent, its parent is revisited; otherwise it goes to a person with `needs-human`; and every open issue labelled `loop/paused` releases each pause marker whose trunk is no longer open, dropping the label once no unreleased marker remains.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |