Skip to content

simiancraft/simiancraft-skills / skills/burn-down-github-issues

burn-down-github-issues

Unverified

Run an unattended burndown of a GitHub issue backlog as cards on a per-operator GitHub Projects board whose lanes are an explicit state machine: appraise and size the inbox, carve what is over the ceiling, fix the ready ones in parallel git worktrees, prove each fix on a draft pull request, have an isolated second-engine reviewer judge it, land one branch at a time with freshness checks, and dead-letter per phase whatever a machine cannot finish. Use when the task is "work the backlog unattended", "triage and fix recent issues", "run the issue loop", "burn down issues", or "where is issue N on the board". Requires a per-repository burn-down-github-issues.config.ts at the target repo's root (the loop refuses to start without it), the prove-work-on-github skill, the codex and claude CLIs for the default seats, and a gh token with the project scope for the board. Skip for one-off fixes to a known issue you are already working interactively, and for backlogs whose issues are mostly product decisions rather than code.

FileKindSize
SKILL.mdskill md17.0 KB
board.tsscript6.5 KB
callbacks/README.mdmarkdown1.1 KB
callbacks/on-size-over-ceilingother843 B
card.tsscript4.3 KB
chart-machine.tsscript3.9 KB
claim-race.tsscript6.1 KB
export-machine.tsscript1.8 KB
lanes.tsscript5.2 KB
lib/admission.test.tsscript7.6 KB
lib/admission.tsscript5.5 KB
lib/board-writer.test.tsscript3.6 KB
lib/board-writer.tsscript11.8 KB
lib/carving-revisit.test.tsscript7.5 KB
lib/carving.tsscript26.9 KB
lib/floor/config.test.tsscript456 B
lib/floor/config.tsscript8.1 KB
lib/floor/floor.test.tsscript9.9 KB
lib/floor/floor.tsscript28.7 KB
lib/floor/incident.tsscript11.2 KB
lib/floor/ledger.tsscript5.6 KB
lib/floor/probe.tsscript3.6 KB
lib/lanes.tsscript4.4 KB
lib/machine.test.tsscript11.2 KB
lib/machine.tsscript52.4 KB
lib/place-callbacks.test.tsscript2.5 KB
lib/place-callbacks.tsscript3.0 KB
lib/preflight.test.tsscript4.5 KB
lib/preflight.tsscript1.2 KB
lib/pressure.test.tsscript56.9 KB
lib/refs.test.tsscript1010 B
lib/refs.tsscript1.9 KB
lib/run-scope.test.tsscript5.4 KB
lib/run-scope.tsscript1.2 KB
lib/scenarios.test.tsscript17.1 KB
lib/simulate.test.tsscript7.3 KB
lib/simulate.tsscript7.0 KB
lib/world-sweep.test.tsscript21.4 KB
loop.source.test.tsscript4.8 KB
loop.tsscript66.2 KB
prompts/diagnose.mdmarkdown2.1 KB
prompts/walk.mdmarkdown3.6 KB
references/adopting.mdmarkdown26.3 KB
references/architecture.mdmarkdown20.7 KB
references/floor.mdmarkdown14.6 KB
references/operating.mdmarkdown19.6 KB
references/state-machine.mdmarkdown31.1 KB
status.tsscript4.9 KB
watch.tsscript6.4 KB

lib/machine.ts

View on GitHub
/**
 * The burndown as a hierarchical state machine, in the shape XState gives a statechart: compound
 * states for the phases, leaf states for the lanes, events the agents and the tracker raise,
 * guards on the counters and the facts, and named actions (an agent seat to run, a tracker
 * write to make, a card to move). The data is the specification; `machine.test.ts` checks it
 * against the lane table, and `references/state-machine.md` is its prose.
 *
 * Root is parallel: `ticket` walks the lanes, `line` is the operator's switch, and the three
 * seams the loop holds at (appraise, dispatch, merge) are guards on `line` rather than states of
 * the ticket, which is why a pause never moves a card.
 *
 * Targets are absolute dotted paths under the root. `ticket.reconcile` is the transient state the
 * reconcile precedence lives in: every hold removal, claim release, hand move, and run start
 * enters it, and its guarded `always` transitions put the card where the facts say. There is
 * deliberately no history node: re-entering a state runs its entry actions, and most of those
 * start an agent, so a card that left for a wait comes back through reconcile, not to where it was.
 */

export type Transition = {
  target: string;
  /** Name of a guard, as XState names them; the reference explains each. Absent means unconditional. */
  guard?: string;
  /** Names of actions run on the transition, in order. */
  actions?: string[];
};

/** What a leaf state shows as: a stable key code uses, and the name and description the board shows. */
export type LaneSpec = { key: string; name: string; description: string };

export type StateNode = {
  /** The lane this leaf state shows as on the board. Absent on compound, transient, and final states. */
  lane?: LaneSpec;
  type?: 'compound' | 'parallel' | 'history' | 'final' | 'transient';
  /** Actions run on entering the state; an agent seat to run is one of them. */
  entry?: string[];
  exit?: string[];
  initial?: string;
  states?: Record<string, StateNode>;
  /** Event name to one or more guarded transitions, tried in order. */
  on?: Record<string, Transition | Transition[]>;
  /** Eventless transitions, tried in order on entry; XState's `always`. The reconcile state is made of these. */
  always?: Transition[];
};

/**
 * A person's redrive (`fix.ts --redrive`, or the loop finding a lifted hold over a pull request):
 * the hold comes off, the redrive is counted, and the existing pull request is continued rather
 * than a second one opened. No seat begins on a stale lane, so a lane behind the base catches up
 * first; the objection that stopped the work stands as the brief, which is a standing rejection.
 */
const REDRIVE: Transition[] = [
  { target: 'ticket.landing.catchingUp', guard: 'prExists and behindBase', actions: ['countRedrive', 'unlabelHold', 'reclaim', 'prToDraft'] },
  { target: 'ticket.work.sentBack', guard: 'prExists', actions: ['countRedrive', 'unlabelHold', 'reclaim'] },
  { target: 'ticket.reconcile', actions: ['countRedrive', 'unlabelHold'] },
];

/**
 * A pull request of the loop's own whose driver is gone, with no hold on it: a run that died on
 * another machine, a lane that was removed. Nobody objected to the work, so it is not a revision.
 * It catches up, then goes to the closest lane that can carry it on: Proving, where its author
 * makes the proof current and hands it to review.
 */
const RESUME: Transition[] = [
  { target: 'ticket.landing.catchingUp', guard: 'behindBase', actions: ['reclaim', 'markResuming'] },
  { target: 'ticket.work.proving', actions: ['reclaim', 'prToDraft', 'runProver'] },
];

/** Transitions every ticket state inherits, tried before its own only for the events named here. */
const TICKET_WIDE: Record<string, Transition | Transition[]> = {
  ISSUE_CLOSED: [
    { target: 'ticket.terminal.merged', guard: 'aMergedPrReferencesIt' },
    { target: 'ticket.terminal.closedWithoutCode' },
  ],
  PR_MERGED: { target: 'ticket.terminal.merged', actions: ['closeIssueWithPointer'] },
  HOLD_ADDED_BY_PERSON: [
    { target: 'ticket.human.needsDecision', guard: 'holdIsNeedsDecision' },
    { target: 'ticket.human.needsHuman', guard: 'holdIsNeedsHuman' },
    { target: 'ticket.human.parked', guard: 'holdIsParked' },
  ],
  SKIPPED: { target: 'ticket.offBoard', actions: ['archiveCard'] },
  FOREIGN_CLAIM: { target: 'ticket.waits.claimedElsewhere' },
  RUN_STARTED: { target: 'ticket.reconcile' },
  HAND_MOVED: { target: 'ticket.reconcile', actions: ['logHandMove'] },
};

export const MACHINE: StateNode = {
  type: 'parallel',
  states: {
    line: {
      initial: 'active',
      states: {
        active: { on: { PAUSE: { target: 'line.paused', actions: ['banner'] } } },
        paused: { on: { GO: { target: 'line.active', actions: ['clearBanner'] } } },
      },
    },

    ticket: {
      initial: 'appraisal',
      on: TICKET_WIDE,
      states: {
        offBoard: { type: 'final' },

        /** The reconcile precedence, top to bottom; GitHub facts beat the lane, the lane beats labels. */
        reconcile: {
          type: 'transient',
          entry: ['readIssue', 'readPullRequests', 'readClaims', 'readRecords', 'readLabels', 'readCard'],
          always: [
              { target: 'ticket.terminal.merged', guard: 'issueClosedByMerge' },
              { target: 'ticket.terminal.closedWithoutCode', guard: 'issueClosed' },
              { target: 'ticket.terminal.merged', guard: 'prMergedIssueOpen', actions: ['closeIssueWithPointer'] },
              { target: 'ticket.human.needsDecision', guard: 'labelNeedsDecision' },
              { target: 'ticket.human.needsHuman', guard: 'labelNeedsHuman' },
              { target: 'ticket.human.parked', guard: 'labelParked' },
              // A panel whose run died holds with the reviews it posted; one still running elsewhere is that run's.
              { target: 'ticket.human.needsDecision', guard: 'labelDeliberating and panelStale', actions: ['commentPanelReceipt', 'unlabelDeliberating', 'labelHold'] },
              { target: 'ticket.waits.claimedElsewhere', guard: 'labelDeliberating' },
              { target: 'ticket.deadLetters.appraisal', guard: 'labelDlqAppraise' },
              { target: 'ticket.deadLetters.carve', guard: 'labelDlqCarve' },
              { target: 'ticket.deadLetters.work', guard: 'labelDlqWork' },
              { target: 'ticket.deadLetters.review', guard: 'labelDlqReview' },
              { target: 'ticket.deadLetters.landing', guard: 'labelDlqLand' },
              { target: 'ticket.waits.pausedByEpic', guard: 'pausedByAncestor' },
              { target: 'ticket.waits.claimedElsewhere', guard: 'foreignClaimLive' },
              { target: 'ticket.carving.spawningChildren', guard: 'ownClaimLive and applyingRecord' },
              { target: 'ticket.carving.revisiting', guard: 'ownClaimLive and trunkFingerprintMoved' },
              { target: 'ticket.carving.carving', guard: 'ownClaimLive and oversizedNoRecord' },
              { target: 'ticket.landing.approved', guard: 'ownClaimLive and readyPr and verdictMerge' },
              { target: 'ticket.review.readyForReview', guard: 'ownClaimLive and readyPr' },
              { target: 'ticket.work.drafted', guard: 'ownClaimLive and draftPr' },
              { target: 'ticket.work.coding', guard: 'ownClaimLive' },
              { target: 'ticket.deadLetters.work', guard: 'deadClaim and draftPr', actions: ['clearClaim'] },
              { target: 'ticket.review.readyForReview', guard: 'deadClaim and readyPr and trustedVerdict', actions: ['reclaim'] },
              // A pull request with nobody driving it (a lifted park, a lifted dead letter, a run
              // that died elsewhere): the card belongs with the work, not back in Ready.
              { target: 'ticket.review.readyForReview', guard: 'readyPr', actions: ['clearClaim'] },
              { target: 'ticket.work.drafted', guard: 'draftPr', actions: ['clearClaim'] },
              { target: 'ticket.carving.spawningChildren', guard: 'applyingRecord', actions: ['clearClaim'] },
              { target: 'ticket.carving.childrenInFlight', guard: 'liveRecord or openChild', actions: ['clearClaim'] },
              { target: 'ticket.carving.rollingUp', guard: 'releasedLabel', actions: ['clearClaim'] },
              { target: 'ticket.waits.blockedBySibling', guard: 'blockerOpen', actions: ['clearClaim'] },
              { target: 'ticket.carving.toCarve', guard: 'sizedOverCeiling', actions: ['clearClaim'] },
              { target: 'ticket.ready.ready', guard: 'sizedWithinCeiling', actions: ['clearClaim'] },
              { target: 'ticket.appraisal.inbox', actions: ['clearClaim'] },
          ],
        },

        appraisal: {
          initial: 'inbox',
          // Every phase answers a machine failure in every one of its lanes, into its own queue:
          // a throw between two agent turns is a failure too, and no lane may drop it.
          on: { AGENT_FAILED: { target: 'ticket.deadLetters.appraisal', actions: ['labelDlq', 'commentReason'] } },
          states: {
            inbox: {
              lane: { key: 'A1', name: 'Inbox', description: 'On the board, unsized, not yet looked at' },
              entry: ['moveCard'],
              on: {
                APPRAISER_DISPATCHED: { target: 'ticket.appraisal.appraising', guard: 'lineActive' },
                // fix.ts on one named issue: a person's own dispatch, which skips the sizing pass.
                // The worker's first step is still the appraisal, and its verdict can still be a close.
                PERSON_DISPATCHED: { target: 'ticket.work.coding', guard: 'noOpenPr', actions: ['claim', 'createWorktree'] },
              },
            },
            appraising: {
              lane: { key: 'A2', name: 'Appraising', description: 'An appraiser turn is running' },
              entry: ['moveCard', 'runAppraiser'],
              on: {
                APPRAISED: [
                  // An adopter may turn the second opinion off; the close is then the appraiser's alone.
                  { target: 'ticket.terminal.closedWithoutCode', guard: 'verdictIsClose and closesUnconfirmed', actions: ['commentReceipt', 'closeIssue'] },
                  { target: 'ticket.appraisal.confirmingClose', guard: 'verdictIsClose' },
                  { target: 'ticket.panel.reviewing', guard: 'verdictNeedsDecision and panelAvailable and panelsUnderCap', actions: ['commentQuestion'] },
                  { target: 'ticket.human.needsDecision', guard: 'verdictNeedsDecision', actions: ['labelHold', 'commentQuestion'] },
                  { target: 'ticket.human.needsHuman', guard: 'verdictNeedsHuman', actions: ['labelHold', 'commentReason'] },
                  { target: 'ticket.carving.toCarve', guard: 'sizedOverCeiling', actions: ['labelSize', 'fireSizeCallback'] },
                  { target: 'ticket.ready.ready', guard: 'sizedWithinCeiling', actions: ['labelSize'] },
                  // Half a verdict (valid, with no size) or one the driver cannot read is a failed turn.
                  // A released trunk's remainder goes back to Rolling up, which asks again on the next sweep.
                  { target: 'ticket.carving.rollingUp', guard: 'appraisalsUnderCap and releasedLabel', actions: ['countAppraisal'] },
                  { target: 'ticket.appraisal.inbox', guard: 'appraisalsUnderCap', actions: ['countAppraisal'] },
                  { target: 'ticket.deadLetters.appraisal', actions: ['labelDlq', 'commentReason'] },
                ],
                AGENT_FAILED: [
                  // A released trunk's remainder goes back to Rolling up, which asks again on the next sweep.
                  { target: 'ticket.carving.rollingUp', guard: 'appraisalsUnderCap and releasedLabel', actions: ['countAppraisal'] },
                  { target: 'ticket.appraisal.inbox', guard: 'appraisalsUnderCap', actions: ['countAppraisal'] },
                  { target: 'ticket.deadLetters.appraisal', actions: ['labelDlq', 'commentReason'] },
                ],
              },
            },
            confirmingClose: {
              lane: { key: 'A3', name: 'Confirming close', description: 'A second engine re-checks the close receipt against the base' },
              entry: ['moveCard', 'runConfirmer'],
              on: {
                CONFIRMED: { target: 'ticket.terminal.closedWithoutCode', actions: ['commentBothReceipts', 'closeIssue'] },
                DISPUTED: { target: 'ticket.human.needsHuman', actions: ['labelHold', 'commentBothOpinions'] },
                // The close is the appraiser's or a worker's. A confirmer that fails is a failed
                // turn of whichever asked: a worker's attempt, or one more appraisal.
                AGENT_FAILED: [
                  { target: 'ticket.ready.ready', guard: 'closeByWorker and attemptsUnderCap and noOpenPr', actions: ['countAttempt', 'releaseClaim', 'removeWorktree'] },
                  { target: 'ticket.deadLetters.work', guard: 'closeByWorker', actions: ['countAttempt', 'labelDlq', 'commentReason', 'releaseClaim'] },
                  // A released trunk's remainder goes back to Rolling up, which asks again on the next sweep.
                  { target: 'ticket.carving.rollingUp', guard: 'appraisalsUnderCap and releasedLabel', actions: ['countAppraisal'] },
                  { target: 'ticket.appraisal.inbox', guard: 'appraisalsUnderCap', actions: ['countAppraisal'] },
                  { target: 'ticket.deadLetters.appraisal', actions: ['labelDlq', 'commentReason'] },
                ],
              },
            },
          },
        },

        ready: {
          initial: 'ready',
          states: {
            ready: {
              lane: { key: 'B1', name: 'Ready', description: 'Sized within the ceiling, unclaimed, unblocked, no open PR' },
              entry: ['moveCard'],
              on: {
                DISPATCHED: { target: 'ticket.work.coding', guard: 'lineActive and noOpenPr', actions: ['claim', 'createWorktree'] },
                BLOCKER_OPENED: { target: 'ticket.waits.blockedBySibling' },
                PAUSED_BY_TRUNK: { target: 'ticket.waits.pausedByEpic', actions: ['labelPaused'] },
              },
            },
          },
        },

        carving: {
          initial: 'toCarve',
          on: { AGENT_FAILED: { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] } },
          states: {
            toCarve: {
              lane: { key: 'C1', name: 'To carve', description: 'Sized over the ceiling; waiting for the knife' },
              entry: ['moveCard'],
              on: { KNIFE_DISPATCHED: { target: 'ticket.carving.carving', guard: 'lineActive', actions: ['claimCarving'] } },
            },
            carving: {
              lane: { key: 'C2', name: 'Carving', description: 'The knife is inventorying criteria and cutting along a seam' },
              entry: ['moveCard', 'runCarver'],
              on: {
                CUT_PROPOSED: { target: 'ticket.carving.confirmingCut' },
                KNIFE_VERDICT: [
                  { target: 'ticket.panel.reviewing', guard: 'verdictTooUncertain and panelAvailable and panelsUnderCap', actions: ['commentQuestion', 'liveRecord'] },
                  { target: 'ticket.human.needsDecision', guard: 'verdictTooUncertain', actions: ['labelHold', 'commentQuestion', 'liveRecord'] },
                  { target: 'ticket.human.needsHuman', guard: 'verdictIndivisible or verdictSmallEnough or verdictNothingLeft', actions: ['labelHold', 'commentBothOpinions', 'liveRecord'] },
                  // A verdict the driver cannot read is a failed turn, not an opinion about the issue.
                  // A released trunk's oversized remainder is still rolling up until its next carving lands.
                  { target: 'ticket.carving.rollingUp', guard: 'carvesUnderCap and releasedLabel', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.carving.toCarve', guard: 'carvesUnderCap', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                ],
                AGENT_FAILED: [
                  // A released trunk's oversized remainder is still rolling up until its next carving lands.
                  { target: 'ticket.carving.rollingUp', guard: 'carvesUnderCap and releasedLabel', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.carving.toCarve', guard: 'carvesUnderCap', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                ],
              },
            },
            confirmingCut: {
              lane: { key: 'C3', name: 'Confirming cut', description: 'A second engine checks cover, severability, ownership, sizes, seam' },
              entry: ['moveCard', 'runCarveConfirmer'],
              on: {
                CUT_CONFIRMED: { target: 'ticket.carving.spawningChildren' },
                // The carver's opinion about the issue is confirmed here too, and then it is a person's.
                OPINION_CONFIRMED: [
                  { target: 'ticket.panel.reviewing', guard: 'verdictTooUncertain and panelAvailable and panelsUnderCap', actions: ['commentQuestion', 'liveRecord', 'releaseClaim'] },
                  { target: 'ticket.human.needsDecision', guard: 'verdictTooUncertain', actions: ['labelHold', 'commentQuestion', 'liveRecord', 'releaseClaim'] },
                  { target: 'ticket.human.needsHuman', actions: ['labelHold', 'commentBothOpinions', 'liveRecord', 'releaseClaim'] },
                ],
                CUT_DISPUTED: [
                  { target: 'ticket.carving.carving', guard: 'carveRoundsUnderCap', actions: ['countCarveRound'] },
                  { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentBothOpinions', 'releaseClaim'] },
                ],
                // The confirmer's failed turn is counted like the carver's: tried again under the cap.
                AGENT_FAILED: [
                  // A released trunk's oversized remainder is still rolling up until its next carving lands.
                  { target: 'ticket.carving.rollingUp', guard: 'carvesUnderCap and releasedLabel', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.carving.toCarve', guard: 'carvesUnderCap', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                ],
              },
            },
            spawningChildren: {
              lane: { key: 'C4', name: 'Spawning children', description: 'The cut is applied: children created in delivery order with edges' },
              entry: ['moveCard', 'postApplyingRecord', 'createChildren', 'addEdges', 'adoptReferences', 'postLiveRecord', 'labelTrunk'],
              on: {
                SPAWN_COMPLETE: { target: 'ticket.carving.childrenInFlight', actions: ['releaseClaim', 'admitChildren'] },
                AGENT_FAILED: { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
              },
            },
            childrenInFlight: {
              lane: { key: 'C5', name: 'Epic: children in flight', description: 'The parent is held while its leaves move through their own lanes' },
              entry: ['moveCard'],
              on: {
                FINGERPRINT_CHANGED: { target: 'ticket.carving.revisiting', guard: 'lineActive', actions: ['claimCarving'] },
                ALL_CHILDREN_CLOSED: { target: 'ticket.carving.revisiting', guard: 'lineActive', actions: ['claimCarving'] },
              },
            },
            revisiting: {
              lane: { key: 'C6', name: 'Revisiting', description: 'The knife asks whether the carving is still good' },
              entry: ['moveCard', 'runCarver', 'runCarveConfirmer'],
              on: {
                REVISITED: [
                  { target: 'ticket.carving.childrenInFlight', guard: 'verdictStillGood', actions: ['postLiveRecord', 'countRevisit', 'releaseClaim'] },
                  { target: 'ticket.carving.spawningChildren', guard: 'verdictAmend', actions: ['countGeneration'] },
                  { target: 'ticket.carving.rollingUp', guard: 'verdictExhausted' },
                  { target: 'ticket.panel.reviewing', guard: 'verdictQuestion and panelAvailable and panelsUnderCap', actions: ['commentQuestion', 'pauseTouchedLeaves', 'releaseClaim'] },
                  { target: 'ticket.human.needsDecision', guard: 'verdictQuestion', actions: ['labelHold', 'commentQuestion', 'pauseTouchedLeaves', 'releaseClaim'] },
                  // The carver's own opinion that what is left cannot be cut: a person weighs it.
                  { target: 'ticket.human.needsHuman', guard: 'verdictIndivisible', actions: ['labelHold', 'commentBothOpinions', 'pauseTouchedLeaves', 'releaseClaim'] },
                  { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                ],
                CAP_REACHED: { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                AGENT_FAILED: [
                  { target: 'ticket.carving.childrenInFlight', guard: 'carvesUnderCap', actions: ['countCarve', 'releaseClaim'] },
                  { target: 'ticket.deadLetters.carve', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                ],
              },
            },
            rollingUp: {
              lane: { key: 'C7', name: 'Rolling up', description: 'Children done or cut exhausted; the remainder is being accounted for' },
              entry: ['moveCard', 'commentRollUp', 'postReleasedRecord', 'unlabelTrunk', 'labelReleased'],
              on: {
                ROLLED_UP: [
                  { target: 'ticket.terminal.closedWithoutCode', guard: 'nothingRemains', actions: ['closeIssue'] },
                  // A release that was interrupted after its remainder was sized, or carved again, is
                  // finished from what the tracker already says.
                  { target: 'ticket.carving.childrenInFlight', guard: 'liveRecord', actions: ['unlabelReleased'] },
                  { target: 'ticket.carving.toCarve', guard: 'sizedOverCeiling' },
                  { target: 'ticket.ready.ready', guard: 'sizedWithinCeiling', actions: ['unlabelReleased'] },
                  { target: 'ticket.appraisal.appraising', actions: ['unlabelSize'] },
                ],
              },
            },
          },
        },

        work: {
          initial: 'coding',
          // Each Work lane is its own seat, and the driver moves the card from what the seat leaves
          // on the remote: Coding ends at a pushed commit the driver announces as coded, Proving at
          // a ready pull request whose head is the proven commit. No seat moves its own card, so a
          // lane is always derivable from facts, and a kill costs the lane it happened in, not the
          // work before it. The hand-offs below are the escapes either seat may take; a lane's own
          // list is tried first.
          on: {
            WORKER_VERDICT: [
              { target: 'ticket.appraisal.confirmingClose', guard: 'verdictIsClose' },
              { target: 'ticket.panel.reviewing', guard: 'verdictNeedsDecision and panelAvailable and panelsUnderCap', actions: ['commentQuestion', 'parkPr', 'releaseClaim'] },
              { target: 'ticket.human.needsDecision', guard: 'verdictNeedsDecision', actions: ['labelHold', 'commentQuestion', 'parkPr', 'releaseClaim'] },
              { target: 'ticket.human.needsHuman', guard: 'verdictNeedsHuman', actions: ['labelHold', 'commentReason', 'parkPr', 'releaseClaim'] },
              { target: 'ticket.carving.toCarve', guard: 'verdictOutOfBandOverCeiling', actions: ['labelSize', 'parkPr', 'releaseClaim'] },
              // A verdict the driver cannot read is a failed turn, settled like one.
              { target: 'ticket.ready.ready', guard: 'attemptsUnderCap and noOpenPr', actions: ['countAttempt', 'releaseClaim', 'removeWorktree'] },
              { target: 'ticket.deadLetters.work', actions: ['countAttempt', 'labelDlq', 'commentReason', 'releaseClaim'] },
            ],
            // With a pull request open there is no Ready to return to: that work waits in the queue.
            AGENT_FAILED: [
              { target: 'ticket.ready.ready', guard: 'attemptsUnderCap and noOpenPr', actions: ['countAttempt', 'releaseClaim', 'removeWorktree'] },
              { target: 'ticket.deadLetters.work', actions: ['countAttempt', 'labelDlq', 'commentReason', 'releaseClaim'] },
            ],
          },
          states: {
            sentBack: {
              lane: { key: 'D4', name: 'Sent back', description: 'Rejected over the code; a code revision is pending or in progress' },
              entry: ['moveCard', 'prToDraft', 'runCoderRevision'],
              on: {
                // A revision is code like a first attempt, and is proved again by a fresh seat.
                CODED: { target: 'ticket.work.proving', actions: ['announceCoded', 'runProver'] },
                WORKER_VERDICT: [
                  { target: 'ticket.appraisal.confirmingClose', guard: 'verdictIsClose' },
                  { target: 'ticket.panel.reviewing', guard: 'verdictNeedsDecision and panelAvailable and panelsUnderCap', actions: ['commentQuestion', 'parkPr', 'releaseClaim'] },
                  { target: 'ticket.human.needsDecision', guard: 'verdictNeedsDecision', actions: ['labelHold', 'commentQuestion', 'parkPr', 'releaseClaim'] },
                  { target: 'ticket.human.needsHuman', guard: 'verdictNeedsHuman', actions: ['labelHold', 'commentReason', 'parkPr', 'releaseClaim'] },
                  { target: 'ticket.carving.toCarve', guard: 'verdictOutOfBandOverCeiling', actions: ['labelSize', 'parkPr', 'releaseClaim'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.work', actions: ['countAttempt', 'labelDlq', 'commentReason', 'releaseClaim'] },
              },
            },
            coding: {
              lane: { key: 'D1', name: 'Coding', description: 'Claim held; the coder makes the smallest change, gates it, and pushes' },
              entry: ['moveCard', 'runCoder'],
              on: {
                // The coder's push is the fact; the driver announces it on the issue, then a fresh seat proves it.
                CODED: { target: 'ticket.work.proving', actions: ['announceCoded', 'runProver'] },
                WORKER_VERDICT: [
                  { target: 'ticket.appraisal.confirmingClose', guard: 'verdictIsClose' },
                  { target: 'ticket.panel.reviewing', guard: 'verdictNeedsDecision and panelAvailable and panelsUnderCap', actions: ['commentQuestion', 'releaseClaim'] },
                  { target: 'ticket.human.needsDecision', guard: 'verdictNeedsDecision', actions: ['labelHold', 'commentQuestion', 'releaseClaim'] },
                  { target: 'ticket.human.needsHuman', guard: 'verdictNeedsHuman', actions: ['labelHold', 'commentReason', 'releaseClaim'] },
                  { target: 'ticket.carving.toCarve', guard: 'verdictOutOfBandOverCeiling', actions: ['labelSize', 'releaseClaim'] },
                ],
              },
            },
            proving: {
              lane: { key: 'D2', name: 'Proving', description: 'Coded and pushed; the prover acquires proof and opens the pull request' },
              entry: ['moveCard'],
              on: {
                // A ready pull request whose head is the proven commit: the prover's whole contract.
                PROVED: { target: 'ticket.review.readyForReview', actions: ['prReady'] },
                // Proof that cannot be produced is a fault in the code, not the proof: back a step,
                // with what could not be shown as the coder's brief. It spends an attempt.
                PROOF_REFUSED: [
                  { target: 'ticket.work.coding', guard: 'attemptsUnderCap', actions: ['countAttempt', 'announceUnproved'] },
                  { target: 'ticket.deadLetters.work', actions: ['countAttempt', 'labelDlq', 'commentReason', 'releaseClaim'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.work', actions: ['countAttempt', 'labelDlq', 'commentReason', 'releaseClaim'] },
              },
            },
            drafted: {
              lane: { key: 'D3', name: 'Drafted', description: 'A draft PR with proof exists; not yet declared complete' },
              entry: ['moveCard'],
              on: {
                PR_READY: { target: 'ticket.review.readyForReview' },
                RESUMED: RESUME,
                REDRIVEN: REDRIVE,
                RUN_DIED: { target: 'ticket.deadLetters.work', actions: ['labelDlq', 'commentReason'] },
              },
            },
          },
        },

        review: {
          initial: 'readyForReview',
          on: { AGENT_FAILED: { target: 'ticket.deadLetters.review', actions: ['labelDlq', 'commentReason', 'releaseClaim'] } },
          states: {
            readyForReview: {
              lane: { key: 'E1', name: 'Ready for review', description: 'PR ready; CI running; no reviewer has started' },
              entry: ['moveCard'],
              on: {
                // No review begins on a stale lane.
                REVIEWER_DISPATCHED: [
                  { target: 'ticket.landing.catchingUp', guard: 'behindBase' },
                  { target: 'ticket.review.evidenceUnderReview' },
                ],
                RESUMED: RESUME,
                // A person lifted a hold by hand; the run start finds the card here, the objection on the thread.
                REDRIVEN: REDRIVE,
                // The reviewer's seat finds the pull request in draft: it was never declared complete.
                PR_TO_DRAFT: { target: 'ticket.work.drafted' },
                // Or finds the lane dirty: work the author never committed, which no review can read.
                UNDECLARED_WORK: { target: 'ticket.deadLetters.work', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
              },
            },
            evidenceUnderReview: {
              lane: { key: 'E2', name: 'Evidence under review', description: 'The reviewer reads the receipts, re-runs the checks, judges adequacy' },
              entry: ['moveCard', 'runReviewer'],
              on: {
                REVIEWED: [
                  { target: 'ticket.landing.approved', guard: 'decisionMerge', actions: ['pinReviewedHead'] },
                  // A rejection goes to the lane it is about: asking for more evidence is the
                  // prover's, objecting to the code is the coder's. Neither begins on a stale lane:
                  // the rejection stands through the catch-up, which hands the card on afterwards.
                  { target: 'ticket.landing.catchingUp', guard: 'reviewRoundsUnderCap and behindBase', actions: ['spendRound', 'prToDraft'] },
                  { target: 'ticket.work.proving', guard: 'decisionGatherMore and reviewRoundsUnderCap', actions: ['spendRound', 'prToDraft', 'runProver'] },
                  { target: 'ticket.work.sentBack', guard: 'reviewRoundsUnderCap', actions: ['spendRound'] },
                  { target: 'ticket.deadLetters.review', actions: ['spendRound', 'labelDlq', 'commentObjection', 'clearRounds', 'releaseClaim'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.review', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                PR_TO_DRAFT: { target: 'ticket.work.drafted' },
              },
            },
          },
        },

        landing: {
          initial: 'approved',
          on: { AGENT_FAILED: { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] } },
          states: {
            approved: {
              lane: { key: 'F1', name: 'Approved', description: 'Merge verdict pinned to a head; waiting for the front of the queue' },
              entry: ['moveCard', 'enqueue', 'checkBoundary'],
              on: {
                // The boundary is a fact about the change, so it is asked once, before anything waits.
                BOUNDARY_REFUSED: { target: 'ticket.human.parked', actions: ['labelParked', 'parkPr', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                // A lane that moved past the reviewed commit was never judged.
                HEAD_MOVED: { target: 'ticket.review.readyForReview', actions: ['leaveQueue'] },
                // Nothing lands that lacks the current base: behind at all is enough to catch up.
                FRONT_OF_QUEUE: [
                  { target: 'ticket.landing.catchingUp', guard: 'behindBase' },
                  { target: 'ticket.landing.checksPending' },
                ],
              },
            },
            catchingUp: {
              lane: { key: 'F2', name: 'Catching up', description: 'The base moved; merging it in before a revision, a review, or the merge, never rebasing' },
              entry: ['moveCard', 'leaveQueue', 'mergeBaseIntoBranch'],
              on: {
                // The closure decides what the catch-up costs, never whether it happens. Movement
                // outside the work leaves a standing approval or an unreviewed proof intact;
                // movement inside it sends an approval back to review and a proof back to its author.
                CAUGHT_UP: [
                  // A resumed pull request has no verdict and no driver's memory of its proof:
                  // whatever the base changed, its author makes the proof current next.
                  { target: 'ticket.work.proving', guard: 'resuming', actions: ['pushBranch', 'prToDraft', 'runProver'] },
                  { target: 'ticket.landing.checksPending', guard: 'standingVerdictMerge and movementOutsideClosure and netChangeIntact', actions: ['pushBranch', 'pinLandingHead'] },
                  { target: 'ticket.review.readyForReview', guard: 'standingVerdictMerge and refreshesUnderCap', actions: ['countRefresh', 'pushBranch'] },
                  { target: 'ticket.work.proving', guard: 'standingVerdictGatherMore and reviewRoundsUnderCap', actions: ['pushBranch', 'runProver'] },
                  { target: 'ticket.work.sentBack', guard: 'standingVerdictRejection and reviewRoundsUnderCap', actions: ['pushBranch'] },
                  // The rejection that spent the last round: there is no revision left to catch up for.
                  { target: 'ticket.deadLetters.review', guard: 'standingVerdictRejection or standingVerdictGatherMore', actions: ['labelDlq', 'commentObjection', 'clearRounds', 'releaseClaim'] },
                  { target: 'ticket.review.readyForReview', guard: 'noVerdictYet and movementOutsideClosure and netChangeIntact', actions: ['pushBranch'] },
                  // Stale proof is demoted to the closest lane that can correct it: Proving, not a revision.
                  { target: 'ticket.work.proving', guard: 'noVerdictYet and refreshesUnderCap', actions: ['countRefresh', 'pushBranch', 'prToDraft', 'runProver'] },
                  { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
                ],
                CONFLICT: { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentReason', 'releaseClaim'] },
              },
            },
            checksPending: {
              lane: { key: 'F3', name: 'Checks pending', description: 'Fresh at the front; waiting on the PR checks' },
              entry: ['moveCard', 'waitOnChecks'],
              on: {
                CHECKS: [
                  // Checks take time. A card that fell behind while they ran goes back to catch up
                  // from here; it never enters a later lane lacking the base.
                  { target: 'ticket.landing.catchingUp', guard: 'checksGreen and behindBase and refreshesUnderCap', actions: ['countRefresh'] },
                  { target: 'ticket.deadLetters.landing', guard: 'checksGreen and behindBase', actions: ['labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                  { target: 'ticket.landing.smoke', guard: 'checksGreen and smokeConfigured' },
                  { target: 'ticket.landing.merging', guard: 'checksGreen' },
                  { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                ],
              },
            },
            smoke: {
              lane: { key: 'F4', name: 'Smoke', description: 'The smoke command runs against the exact head that would land' },
              entry: ['moveCard', 'runSmoke'],
              on: {
                SMOKE: [
                  { target: 'ticket.landing.catchingUp', guard: 'smokePassed and behindBase and refreshesUnderCap', actions: ['countRefresh'] },
                  { target: 'ticket.deadLetters.landing', guard: 'smokePassed and behindBase', actions: ['labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                  { target: 'ticket.landing.merging', guard: 'smokePassed' },
                  { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentTail', 'leaveQueue', 'releaseClaim'] },
                ],
              },
            },
            merging: {
              lane: { key: 'F5', name: 'Merging', description: 'The line says go; merging the pinned head and confirming' },
              entry: ['moveCard', 'askMayMerge', 'liveGate', 'lookUpstreamOnceMore', 'mergeWithPinnedHead', 'confirmMerged'],
              on: {
                MERGED: { target: 'ticket.terminal.merged', actions: ['closeIssueWithPointer', 'putOnFloor', 'followBase', 'leaveQueue', 'releaseClaim', 'removeWorktree'] },
                ISSUE_CHANGED_UNDER_REVIEW: { target: 'ticket.human.parked', actions: ['labelParked', 'parkPr', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                // The line can hold a card here while it is paused; anything that landed meanwhile is caught up first.
                BASE_MOVED_WHILE_WAITING: [
                  { target: 'ticket.landing.catchingUp', guard: 'refreshesUnderCap', actions: ['countRefresh'] },
                  { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                ],
                MERGE_UNREPORTED: { target: 'ticket.deadLetters.landing', actions: ['cancelQueuedMerge', 'labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] },
                LINE_GAVE_UP: { target: 'ticket.deadLetters.landing', actions: ['labelDlq', 'commentReason', 'leaveQueue', 'releaseClaim'] },
              },
            },
          },
        },

        waits: {
          initial: 'blockedBySibling',
          states: {
            blockedBySibling: {
              lane: { key: 'W1', name: 'Blocked by sibling', description: 'A blocked-by edge points at an issue not closed as completed' },
              entry: ['moveCard'],
              on: {
                BLOCKER_CLOSED: [
                  // Not straight to Ready: the freed card may be unsized, oversized, or blocked by another
                  // sibling, so reconcile places it by its facts (realized by the work phase's refill).
                  { target: 'ticket.reconcile', guard: 'blockerCompleted' },
                  { target: 'ticket.reconcile', guard: 'hasOpenParent', actions: ['revisitParent'] },
                  { target: 'ticket.human.needsHuman', actions: ['labelHold', 'commentReason'] },
                ],
              },
            },
            pausedByEpic: {
              lane: { key: 'W2', name: 'Paused by epic', description: 'The trunk has an open question; the pause marker names it' },
              entry: ['moveCard'],
              on: { PAUSE_LIFTED: { target: 'ticket.reconcile', actions: ['unlabelPaused'] } },
            },
            claimedElsewhere: {
              lane: { key: 'W3', name: 'Claimed elsewhere', description: 'Another run holds a live claim on this issue' },
              entry: ['moveCard'],
              on: {
                // Not a history node: re-entering a state runs its entry actions, and most of those
                // start an agent. The facts decide where the card resumes.
                CLAIM_RELEASED: { target: 'ticket.reconcile' },
                CLAIM_EXPIRED: { target: 'ticket.reconcile' },
              },
            },
          },
        },

        deadLetters: {
          initial: 'work',
          // A queue is a resting place. A triage agent that fails is one more machine failure, so
          // the card stays in its queue with the failure recorded and triage stopped; it does not
          // become a person's hold. Only a triage that reaches a decision sends a card to a person.
          // The failure's target is the queue itself, which does not re-enter it, so triage is not
          // started again by its own failure.
          states: {
            appraisal: {
              lane: { key: 'Q1', name: 'Appraisal DLQ', description: 'Appraiser or confirmer failed past the cap' },
              entry: ['moveCard', 'runTriage'],
              on: {
                TRIAGED: [
                  { target: 'ticket.appraisal.appraising', guard: 'decisionRetry and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'applyStrategy'] },
                  { target: 'ticket.human.needsHuman', actions: ['unlabelDlq', 'labelHold', 'commentHistory'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.appraisal', actions: ['countTriage', 'commentReason', 'stopTriage'] },
              },
            },
            carve: {
              lane: { key: 'Q2', name: 'Carve DLQ', description: 'Carve failed, disputed past the cap, or hit a depth, generation, or revisit cap' },
              entry: ['moveCard', 'runTriage'],
              on: {
                // A person lifted the label: a carved trunk is revisited in a new epoch, anything else is carved again.
                REDRIVEN: [
                  { target: 'ticket.carving.revisiting', guard: 'liveRecord or openChild', actions: ['countRedrive', 'unlabelHold', 'claimCarving'] },
                  { target: 'ticket.carving.toCarve', actions: ['countRedrive', 'unlabelHold'] },
                ],
                TRIAGED: [
                  { target: 'ticket.carving.spawningChildren', guard: 'decisionRetry and redrivesUnderCap and applyingRecord', actions: ['countRedrive', 'unlabelDlq'] },
                  { target: 'ticket.carving.carving', guard: 'decisionRetry and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'applyStrategy'] },
                  { target: 'ticket.human.needsHuman', actions: ['unlabelDlq', 'labelHold', 'commentBothOpinions'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.carve', actions: ['countTriage', 'commentReason', 'stopTriage'] },
              },
            },
            work: {
              lane: { key: 'Q3', name: 'Work DLQ', description: 'Worker failed past the cap, or the run died with undeclared work' },
              entry: ['moveCard', 'runTriage'],
              on: {
                REDRIVEN: REDRIVE,
                TRIAGED: [
                  { target: 'ticket.carving.toCarve', guard: 'decisionOversize', actions: ['unlabelDlq', 'labelSize'] },
                  // Work that has a pull request is carried on, never started over: caught up first when behind.
                  { target: 'ticket.landing.catchingUp', guard: 'decisionRetry and redrivesUnderCap and prExists and behindBase', actions: ['countRedrive', 'unlabelDlq', 'reclaim', 'markResuming'] },
                  { target: 'ticket.work.proving', guard: 'decisionRetry and redrivesUnderCap and readyPr', actions: ['countRedrive', 'unlabelDlq', 'reclaim', 'prToDraft', 'runProver'] },
                  { target: 'ticket.work.drafted', guard: 'decisionRetry and redrivesUnderCap and draftPr', actions: ['countRedrive', 'unlabelDlq', 'reclaim'] },
                  { target: 'ticket.work.coding', guard: 'decisionRetry and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'applyStrategy', 'clearAttempts'] },
                  { target: 'ticket.human.parked', guard: 'prExists', actions: ['unlabelDlq', 'labelParked', 'parkPr', 'commentHistory'] },
                  { target: 'ticket.human.needsHuman', actions: ['unlabelDlq', 'labelHold', 'commentHistory'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.work', actions: ['countTriage', 'commentReason', 'stopTriage'] },
              },
            },
            review: {
              lane: { key: 'Q4', name: 'Review DLQ', description: 'Review rounds exhausted, or no trusted verdict' },
              entry: ['moveCard', 'runTriage'],
              on: {
                REDRIVEN: REDRIVE,
                TRIAGED: [
                  { target: 'ticket.review.readyForReview', guard: 'decisionRerunReviewer and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'reclaim'] },
                  // A retry is a revision, and no revision begins on a stale lane: the rejection stands
                  // through the catch-up, which hands the card to Sent back.
                  { target: 'ticket.landing.catchingUp', guard: 'decisionRetry and redrivesUnderCap and behindBase', actions: ['countRedrive', 'unlabelDlq', 'applyStrategy', 'reclaim', 'prToDraft'] },
                  { target: 'ticket.work.sentBack', guard: 'decisionRetry and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'applyStrategy', 'reclaim'] },
                  { target: 'ticket.panel.reviewing', guard: 'decisionDesignObjection and panelAvailable and panelsUnderCap', actions: ['unlabelDlq', 'commentQuestion', 'parkPr'] },
                  { target: 'ticket.human.needsDecision', guard: 'decisionDesignObjection', actions: ['unlabelDlq', 'labelHold', 'commentQuestion', 'parkPr'] },
                  { target: 'ticket.human.parked', actions: ['unlabelDlq', 'labelParked', 'parkPr', 'commentHistory'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.review', actions: ['countTriage', 'commentReason', 'stopTriage'] },
              },
            },
            landing: {
              lane: { key: 'Q5', name: 'Landing DLQ', description: 'Conflicts, red checks, smoke failure, refresh cap, or unreported merge' },
              entry: ['moveCard', 'runTriage'],
              on: {
                REDRIVEN: REDRIVE,
                TRIAGED: [
                  { target: 'ticket.landing.catchingUp', guard: 'decisionResolveConflict and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'reclaim'] },
                  { target: 'ticket.landing.approved', guard: 'decisionRetry and redrivesUnderCap', actions: ['countRedrive', 'unlabelDlq', 'reclaim'] },
                  { target: 'ticket.human.parked', actions: ['unlabelDlq', 'labelParked', 'parkPr', 'commentHistory'] },
                ],
                AGENT_FAILED: { target: 'ticket.deadLetters.landing', actions: ['countTriage', 'commentReason', 'stopTriage'] },
              },
            },
          },
        },

        /**
         * The adversarial check before a person is brought in. Before an agent-raised question parks
         * a card, three frontier models on different engines (the raising seat's and two others)
         * each try to answer it from the code, the conventions, and the thread, and each one's review
         * lands on the issue. Only a question all three decide alike, on facts that verify, is settled
         * here; anything still open goes to a person with that research already on the thread.
         */
        panel: {
          initial: 'reviewing',
          states: {
            reviewing: {
              lane: { key: 'P1', name: 'Panel review', description: 'Three frontier models test whether a person must decide; read-only' },
              entry: ['moveCard', 'labelDeliberating', 'countPanel', 'runPanel'],
              on: {
                // Every question decided: the receipt is the ruling, and the card goes back the way a
                // person's answer sends it, without the new epoch only a person's hold removal starts.
                PANEL_PROCEED: [
                  { target: 'ticket.carving.revisiting', guard: 'isTrunk', actions: ['commentPanelReceipt', 'unlabelDeliberating', 'claimCarving'] },
                  { target: 'ticket.appraisal.inbox', actions: ['commentPanelReceipt', 'unlabelDeliberating', 'unlabelSize'] },
                ],
                // Anything still open, including a seat that failed or ran out of time: a panel short
                // a seat cannot decide, so the hold the raising seat asked for stands. A seat failing
                // is not the machine failing, which is why the panel answers no AGENT_FAILED.
                PANEL_HOLD: { target: 'ticket.human.needsDecision', actions: ['commentPanelReceipt', 'unlabelDeliberating', 'labelHold'] },
              },
            },
          },
        },

        human: {
          initial: 'needsHuman',
          states: {
            needsDecision: {
              lane: { key: 'H1', name: 'Needs decision', description: 'A product or domain ruling nobody has made; the question is on the thread' },
              entry: ['moveCard'],
              on: {
                HOLD_REMOVED: [
                  { target: 'ticket.carving.revisiting', guard: 'isTrunk', actions: ['newEpoch', 'claimCarving'] },
                  { target: 'ticket.appraisal.inbox', actions: ['unlabelSize'] },
                ],
              },
            },
            needsHuman: {
              lane: { key: 'H2', name: 'Needs human', description: 'Access, authority, an engine tie, or a DLQ past its redrive cap' },
              entry: ['moveCard'],
              on: { HOLD_REMOVED: { target: 'ticket.reconcile', actions: ['clearCappedCounter'] } },
            },
            parked: {
              lane: { key: 'H3', name: 'Parked', description: 'A PR exists and a person owns the landing' },
              entry: ['moveCard'],
              on: {
                HOLD_REMOVED: { target: 'ticket.reconcile', actions: ['unparkPr', 'keepPrForReuse'] },
                REDRIVEN: REDRIVE,
                LANDED_BY_HAND: { target: 'ticket.terminal.merged' },
              },
            },
          },
        },

        terminal: {
          initial: 'closedWithoutCode',
          states: {
            merged: {
              lane: { key: 'T1', name: 'Merged', description: 'The PR landed and the issue is closed with a pointer' },
              entry: ['moveCard', 'rollUpToParent'],
              on: {
                WALKED: [
                  { target: 'ticket.terminal.verifiedOnFloor', guard: 'walkPassed' },
                  { target: 'ticket.terminal.merged', actions: ['noteIncident'] },
                ],
                REOPENED: { target: 'ticket.reconcile', actions: ['newEpisode'] },
              },
            },
            closedWithoutCode: {
              lane: { key: 'T2', name: 'Closed without code', description: 'Closed with a re-checkable receipt, or by a person' },
              entry: ['moveCard', 'rollUpToParent'],
              on: { REOPENED: { target: 'ticket.reconcile', actions: ['newEpisode'] } },
            },
            verifiedOnFloor: {
              lane: { key: 'T3', name: 'Verified on the floor', description: 'Merged and found present on the deployed base' },
              entry: ['moveCard'],
              on: { REOPENED: { target: 'ticket.reconcile', actions: ['newEpisode'] } },
            },
          },
        },
      },
    },
  },
};

/** The phase a ticket state path belongs to, from its second segment. */
export const PHASE_OF_STATE: Record<string, Phase> = {
  appraisal: 'appraisal',
  ready: 'ready',
  carving: 'carving',
  work: 'work',
  review: 'review',
  landing: 'landing',
  waits: 'waits',
  deadLetters: 'dead-letters',
  panel: 'panel',
  human: 'human',
  terminal: 'terminal',
};

export type Phase =
  | 'appraisal'
  | 'ready'
  | 'carving'
  | 'work'
  | 'review'
  | 'landing'
  | 'waits'
  | 'dead-letters'
  | 'panel'
  | 'human'
  | 'terminal';

/** Every state path under the root, depth first, with its node. */
export function walk(node: StateNode = MACHINE, path = ''): Array<[string, StateNode]> {
  const out: Array<[string, StateNode]> = [];
  for (const [name, child] of Object.entries(node.states ?? {})) {
    const here = path ? `${path}.${name}` : name;
    out.push([here, child]);
    out.push(...walk(child, here));
  }
  return out;
}

/** Every transition in the machine with the path of the state it leaves and the event that fires it. */
export function transitions(): Array<{ from: string; event: string; transition: Transition }> {
  const out: Array<{ from: string; event: string; transition: Transition }> = [];
  for (const [from, node] of walk()) {
    for (const [event, list] of Object.entries(node.on ?? {})) {
      for (const transition of Array.isArray(list) ? list : [list]) out.push({ from, event, transition });
    }
    for (const transition of node.always ?? []) out.push({ from, event: 'always', transition });
  }
  return out;
}
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: 471kUpdated Claude CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall