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/carving.ts

View on GitHub
/**
 * The burndown's side of carving: the close hook that rolls a leaf's close up to its trunk and
 * revisits it, the release appraisal that finishes an exhausted trunk under the loop's own claim,
 * and the sweep that runs at the start of every run so closes, edits, holds, and crashes made
 * outside the loop are seen. The knife itself is the sibling skill; this file only decides when
 * to call it and what to do with the answer.
 */

import { placeByFacts } from './board-writer.ts';
import { appraiseIssue, recordAppraisalThrow, type AppraiseKnobs, isHeld } from '../../appraise-github-issues/lib/appraise.ts';
import type { Seat } from '../../fix-github-issue/lib/engines.ts';
import type { CarveKnobs } from '../../carve-github-issue/lib/carve.ts';
import { claim, keepClaimed, leaseLost, trackerIo } from '../../carve-github-issue/lib/claims.ts';
import { carveIssue, unreleasedPauseMarkers } from '../../carve-github-issue/lib/knife.ts';
import { fingerprint, liveClaim, needsRevisit, parseMarker, pointsOf, readTree, type Tree } from '../../carve-github-issue/lib/tree.ts';
import type { CloseEvent, Context } from '../../fix-github-issue/lib/context.ts';
import { HOLD_LABELS } from '../../fix-github-issue/lib/labels.ts';
import type { Issue } from '../../fix-github-issue/lib/pipeline.ts';
import { isStopping, mutate, RunStopping } from '../../fix-github-issue/lib/shell.ts';

export type CarvingDeps = {
  ctx: Context;
  knobs: CarveKnobs;
  appraisal: {
    seats: { appraiser: Seat; confirmer: Seat };
    confirmCloses: boolean;
    skipLabels: string[];
    maxAppraiseAttempts: number;
    sizeCallbackTimeoutMinutes: number;
  };
  /** Effective `--only` membership, including discovered descendants; shared with the loop. */
  only: ReadonlySet<number> | null;
  ageDays: number;
  /** Places the trunk's card in a lane (a key from lib/lanes.ts) on every projection the driver keeps. */
  mark: (issue: number, title: string, lane: string, note?: string) => void;
  log: (message: string) => void;
};

const SWEEP_LABELS = ['loop/carved', 'loop/released', 'loop/handed-off', 'loop/carving', 'loop/working', 'loop/paused'];

/**
 * The lane a knife outcome leaves the trunk in. `atRest` is where the card sat before the knife
 * ran (To carve for a fresh cut, Epic for a revisit): a verdict that changed nothing, a failure
 * short of the cap, and a claim held elsewhere all leave it there.
 */
/**
 * The lane an outcome names outright. Null for every outcome that names none (a failed turn, a
 * trunk left alone, a busy one, a resumed announcement, a throw): there the tracker says where
 * the card rests, and a guess would show progress that did not happen.
 */
function laneOf(outcome: string): string | null {
  if (outcome === 'carve' || outcome === 'amend' || outcome === 'still-good') return 'C5';
  if (outcome === 'exhausted') return 'C7';
  if (outcome === 'too-uncertain') return 'H1';
  // The carver's opinions about the issue all take `needs-human`, so the card rests where the label does.
  if (outcome === 'indivisible' || outcome === 'nothing-left' || outcome === 'small-enough') return 'H2';
  if (outcome === 'dlq') return 'Q2';
  return null;
}

/** Where a trunk's card rests by the tracker's own facts, its carving record included. */
function restingLane(tree: Tree, ceiling: number, runId: string): { lane: string; why: string } {
  const now = Date.now();
  const foreign = tree.claims.find((c) => !c.released && Date.parse(c.expires) > now && c.runId !== runId);
  const placed = placeByFacts({
    state: tree.issue.state === 'OPEN' ? 'OPEN' : 'CLOSED',
    labels: tree.issue.labels.map((l) => l.name),
    pulls: [],
    points: pointsOf(tree.issue.labels) ?? undefined,
    ceiling,
    blocked: tree.blockers.some((b) => !(b.state === 'CLOSED' && b.stateReason === 'COMPLETED')),
    openChildren: tree.children.some((c) => c.state === 'OPEN'),
    claimedBy: foreign?.runId,
    pausedAbove: tree.ancestors.some((a) => a.labels.includes('loop/paused')),
  });
  // A close, a person's hold, a dead letter, and another run's claim all outrank an announced
  // generation: the card says who has the trunk before it says what is unfinished on it.
  if (/^[THQW]/.test(placed.lane) || tree.record?.state !== 'applying') return placed;
  return { lane: 'C4', why: `generation ${tree.record.generation} is still being applied` };
}

function issueOf(tree: Tree): Issue {
  return { number: tree.issue.number, title: tree.issue.title, createdAt: tree.issue.createdAt, labels: tree.issue.labels, parent: tree.issue.parent, subIssuesSummary: tree.issue.subIssuesSummary, blockedBy: tree.issue.blockedBy };
}

/** How many times one trunk is revisited in one run, however often its tree moves. */
export const MAX_REVISITS_PER_RUN = 8;

/**
 * A trunk is revisited when its tree moved since the facts this run's last visit of it judged, so a
 * child closing after the sweep (or after an earlier child's close) still rolls up in the same run.
 * One trunk is visited by one call at a time: a trigger that arrives during a visit (another lane's
 * close, or a close the visit itself makes, whose hook asks for the same trunk) is noted and served
 * by one more pass after it, never awaited from inside it. Each run caps visits at
 * MAX_REVISITS_PER_RUN while the trunk still has open children; the visit after its last child
 * closes, which rolls it up, is never refused.
 */
export class Carving {
  /** The facts each trunk's last successful visit this run judged, as its fingerprint. */
  private readonly lastSeen = new Map<number, string>();
  private readonly visits = new Map<number, number>();
  /** Trunks being visited now. */
  private readonly active = new Set<number>();
  /** Why a trunk was asked for again while it was being visited; served after the visit. */
  private readonly pending = new Map<number, string>();
  private readonly deps: CarvingDeps;
  constructor(deps: CarvingDeps) {
    // Every card this driver places goes through `mark`. A card is a projection of an issue the run
    // holds, so once its lease on an issue is lost that issue's card is another run's to place.
    const mark: CarvingDeps['mark'] = (number, title, lane, note) => {
      if (leaseLost(deps.ctx, number)) return;
      deps.mark(number, title, lane, note);
    };
    this.deps = { ...deps, mark };
  }

  /** `ctx.onClosed`: roll the close up to the parent, then revisit the parent once this run. */
  async onClosed(event: CloseEvent): Promise<void> {
    const { ctx, log } = this.deps;
    const io = trackerIo(ctx);
    const closed = io.view(event.issue);
    const parent = closed?.parent?.number ?? null;
    if (parent === null) return;
    const trunk = io.view(parent);
    if (!trunk || trunk.state !== 'OPEN') {
      log(`#${event.issue} closed under #${parent}, which is not open; nothing to roll up`);
      return;
    }
    const marker = `<!-- carve-rollup child=${event.issue} event=${event.kind} at=${event.closedAt} -->`;
    if (!trunk.comments.some((c) => c.author === ctx.botLogin && c.body.startsWith(marker))) {
      const how = event.kind === 'merged' ? `merged in #${event.pr}` : event.kind === 'answered' ? 'answered on its thread' : `closed: ${event.reason}`;
      mutate(ctx, `roll up #${event.issue} on #${parent}`, ['gh', 'issue', 'comment', String(parent), '--body', `${marker}\nLeaf #${event.issue} (${closed?.title ?? ''}) ${how} at ${event.closedAt}.`]);
    }
    await this.revisit(parent, `#${event.issue} closed`);
  }

  /**
   * One trunk's visit inside the sweep. A knife that throws has already counted the failed carve on
   * the trunk (a dead letter at the cap) and rested its card, so the sweep goes on to the next trunk
   * rather than ending the run on the first bad one; a stop is the operator's and still ends it.
   */
  private async guard(number: number, visit: () => Promise<void>): Promise<void> {
    try {
      await visit();
    } catch (error) {
      if (error instanceof RunStopping || isStopping()) throw error;
      this.deps.log(`  #${number}  sweep: ${(error as Error).message.split('\n')[0]}; on to the next trunk`);
    }
  }

  /**
   * Hands a trunk to the knife when its tree moved since this run last judged it, and finishes a
   * release when the knife exhausts it. A call for a trunk already being visited returns at once and
   * leaves a note, so a close made inside the visit cannot wait on the visit that made it.
   */
  async revisit(number: number, why: string): Promise<void> {
    if (this.active.has(number)) {
      this.pending.set(number, why);
      this.deps.log(`#${number} asked for again while it is being visited (${why}); one more pass follows the visit`);
      return;
    }
    this.active.add(number);
    // A visit that throws still serves a note left during it (one recovery pass), then reports the
    // error; a second failure, or a stop, ends at once.
    let failure: unknown = null;
    try {
      let reason = why;
      for (;;) {
        try {
          await this.revisitOnce(number, reason);
        } catch (error) {
          if (error instanceof RunStopping || isStopping() || failure !== null) throw error;
          failure = error;
        }
        const again = this.pending.get(number);
        if (again === undefined) break;
        this.pending.delete(number);
        reason = again;
      }
      if (failure !== null) throw failure;
    } finally {
      this.active.delete(number);
      this.pending.delete(number);
    }
  }

  private async revisitOnce(number: number, why: string): Promise<void> {
    const { ctx, knobs, mark, log } = this.deps;
    const io = trackerIo(ctx);
    const tree = readTree(ctx, number, io);
    const facts = JSON.stringify(fingerprint(tree, ctx.botLogin));
    if (this.lastSeen.get(number) === facts) {
      log(`#${number} unchanged since its last revisit this run (${why}); nothing to do`);
      return;
    }
    const count = (this.visits.get(number) ?? 0) + 1;
    const childrenOpen = tree.children.some((child) => child.state === 'OPEN');
    if (count > MAX_REVISITS_PER_RUN && childrenOpen) {
      log(`#${number} revisited ${MAX_REVISITS_PER_RUN} times this run (${why}); the next sweep sees the rest`);
      return;
    }
    this.visits.set(number, count);
    try {
      await this.visitTree(number, why, tree);
    } catch (error) {
      // A visit that failed judged nothing: the same facts may be tried again.
      this.lastSeen.delete(number);
      throw error;
    }
    // The facts this visit judged, not what the tracker shows after it: a change made meanwhile (a
    // child closing during the knife's turn) still differs from them, so its trigger is served.
    this.lastSeen.set(number, facts);
  }

  private async visitTree(number: number, why: string, tree: Tree): Promise<void> {
    const { ctx, knobs, mark } = this.deps;
    const io = trackerIo(ctx);
    const issue = issueOf(tree);
    // The card enters the lane of the work about to happen: an announced generation is finished
    // in Spawning children, a trunk that already has a record or children is visited in
    // Revisiting, and anything else is a first carving. The knife moves the card as it works.
    const visiting = tree.record?.state === 'live' || tree.children.some((c) => c.state === 'OPEN');
    mark(number, issue.title, tree.record?.state === 'applying' ? 'C4' : visiting ? 'C6' : 'C2', why);
    let outcome: Awaited<ReturnType<typeof carveIssue>>;
    try {
      outcome = await carveIssue(ctx, issue, knobs, io);
    } catch (error) {
      this.rest(number, issue.title, `the knife threw: ${(error as Error).message}`);
      throw error;
    }
    this.settle(number, issue.title, outcome);
    if (outcome.outcome === 'exhausted') await this.releaseAppraisal(number);
  }

  /** The card follows the outcome where it names a lane, and the tracker where it does not. */
  private settle(number: number, title: string, outcome: { outcome: string; reason: string }): void {
    // Without the lease the card is another run's to place, from the tracker's facts or otherwise.
    if (outcome.outcome === 'lease-lost') {
      this.deps.log(`#${number}  card left alone: ${outcome.reason}`);
      return;
    }
    const lane = laneOf(outcome.outcome);
    if (lane) this.deps.mark(number, title, lane, outcome.reason.slice(0, 80));
    else this.rest(number, title, outcome.reason);
  }

  /** Places the card from the tracker's facts; a tracker that cannot be read leaves it where it is. */
  private rest(number: number, title: string, note: string): void {
    const { ctx, knobs, mark, log } = this.deps;
    try {
      const placed = restingLane(readTree(ctx, number, trackerIo(ctx)), knobs.ceiling, ctx.runId);
      mark(number, title, placed.lane, `${note}; ${placed.why}`.slice(0, 80));
    } catch (error) {
      log(`#${number} could not be placed from the tracker: ${(error as Error).message.split('\n')[0]}`);
    }
  }

  /**
   * The release appraisal, re-run from the tracker's state until `loop/released` is gone: with no
   * size label, appraise the remainder (no size callback); a size at or under the ceiling takes
   * the label off; a size over it carves the next generation in process, then takes it off.
   */
  async releaseAppraisal(number: number): Promise<void> {
    const { ctx, knobs, appraisal, mark, log } = this.deps;
    if (ctx.dryRun) {
      log(`DRY RUN  would run the release appraisal on #${number}`);
      return;
    }
    const io = trackerIo(ctx);
    let handle = await claim(ctx, io, number, 'carving');
    if (handle === 'busy') {
      log(`#${number} release appraisal: another run holds it`);
      return;
    }
    let stop = keepClaimed(handle);
    try {
      for (let step = 0; step < 4; step++) {
        const tree = readTree(ctx, number, io);
        const labels = tree.issue.labels.map((l) => l.name);
        if (!labels.includes('loop/released') || tree.issue.state !== 'OPEN') return;
        if (labels.some((l) => HOLD_LABELS.includes(l) && l !== 'loop/paused')) return;
        const issue = issueOf(tree);
        const points = pointsOf(tree.issue.labels);
        if (points === null) {
          // Rolling up hands the remainder to an appraiser, and the card says so while it runs.
          mark(number, issue.title, 'A2', 'release appraisal of the remainder');
          let outcome: Awaited<ReturnType<typeof appraiseIssue>>;
          try {
            outcome = await appraiseIssue(ctx, issue, { ...appraisal, ageDays: null, release: true, ownClaim: ctx.runId, onVerdict: undefined });
          } catch (error) {
            // Settled like any appraisal that threw: counted, a dead letter at the cap, and the card
            // says which. Below the cap the trunk is still rolling up and the next sweep tries again.
            const counted = recordAppraisalThrow(ctx, issue, appraisal.maxAppraiseAttempts, error as Error, (m) => log(`#${number}  ${m}`));
            mark(number, issue.title, counted.deadLetter ? 'Q1' : 'C7', `release appraisal: ${counted.reason}`.slice(0, 80));
            throw error;
          }
          // An appraisal that stopped because the trunk changed under it (a hold, a claim, a close)
          // names no lane, and one that must be tried again leaves the trunk rolling up.
          if (outcome.changed) this.rest(number, issue.title, `release appraisal: ${outcome.reason}`);
          else {
            const lane = outcome.deadLetter ? 'Q1' : outcome.retry ? 'C7' : outcome.verdict === 'valid' ? ((outcome.points ?? 0) > knobs.ceiling ? 'C1' : 'B1') : outcome.verdict === 'needs-decision' ? 'H1' : outcome.verdict === 'needs-human' || outcome.close === 'disputed' ? 'H2' : outcome.close === 'confirmed' || outcome.close === 'skipped' ? 'T2' : 'C7';
            mark(number, issue.title, lane, `release appraisal: ${outcome.reason}`.slice(0, 80));
          }
          if (outcome.verdict !== 'valid') return;
          continue;
        }
        const newerRecord = tree.record && tree.record.state !== 'released';
        if (points > knobs.ceiling && !newerRecord) {
          // The knife claims for itself; this claim steps aside for it and is retaken after.
          stop();
          handle.release();
          // Released here, so the finally below has nothing of its own to release if the knife throws.
          handle = 'busy';
          // The remainder is oversized, so it is To carve before the knife takes it.
          mark(number, issue.title, 'C1', `released at ${points}, over the ceiling of ${knobs.ceiling}`);
          let outcome: Awaited<ReturnType<typeof carveIssue>>;
          try {
            outcome = await carveIssue(ctx, issue, knobs, io);
          } catch (error) {
            this.rest(number, issue.title, `the knife threw: ${(error as Error).message}`);
            throw error;
          }
          this.settle(number, issue.title, outcome);
          if (outcome.outcome !== 'carve' && outcome.outcome !== 'resumed') return;
          handle = await claim(ctx, io, number, 'carving');
          if (handle === 'busy') return;
          stop = keepClaimed(handle);
          continue;
        }
        if (leaseLost(ctx, number)) {
          log(`#${number} release appraisal: this run lost its lease; leaving loop/released for the next sweep`);
          return;
        }
        mutate(ctx, `unlabel #${number} loop/released`, ['gh', 'issue', 'edit', String(number), '--remove-label', 'loop/released']);
        mark(number, issue.title, points > knobs.ceiling ? 'C5' : 'B1', `released at ${points}`);
        return;
      }
    } finally {
      stop();
      if (handle !== 'busy') handle.release();
    }
  }

  /**
   * The sweep: three passes over the open backlog. First, every labelled trunk, claim, or pause:
   * finish, repair, redrive, or revisit. Second, every unlabelled, unheld, unclaimed issue that is
   * oversized inside the window or has an open child at any age. Third, every leaf whose blocker
   * is closed not planned, deleted, or cyclic, and every pause a closed trunk left behind.
   */
  async sweep(all: Issue[]): Promise<void> {
    const { ctx, knobs, only, ageDays, log } = this.deps;
    const io = trackerIo(ctx);
    const inScope = (issue: Issue) => only === null || only.has(issue.number);
    const cutoff = Date.now() - ageDays * 24 * 60 * 60 * 1000;
    const first = new Set<number>();

    for (const issue of all) {
      try {
        if (!inScope(issue)) continue;
        const labels = issue.labels.map((l) => l.name);
        if (!labels.some((l) => SWEEP_LABELS.includes(l) || l.startsWith('loop/carve-gen'))) continue;
        first.add(issue.number);
        const tree = readTree(ctx, issue.number, io);
        const now = new Date().toISOString();

        // Torn or expired claims: a label with no live claim behind it comes off, once nothing is pending.
        for (const kind of ['carving', 'working'] as const) {
          const label = kind === 'carving' ? 'loop/carving' : 'loop/working';
          if (!labels.includes(label)) continue;
          const live = tree.claims.some((c) => c.kind === kind && !c.released && Date.parse(c.expires) > Date.parse(now));
          const pending = tree.intents.some((i) => !i.finished && (i.kind === 'applying' || i.kind === 'released' || i.kind === 'carve-handoff'));
          if (live || pending) continue;
          if (ctx.dryRun) {
            log(`DRY RUN  would clear the stale ${label} on #${issue.number}`);
            continue;
          }
          mutate(ctx, `clear stale ${label} on #${issue.number}`, ['gh', 'issue', 'comment', String(issue.number), '--body', `The ${label} label had no live claim behind it (the run died, or was killed); cleared by the sweep.`]);
          mutate(ctx, `unlabel #${issue.number} ${label}`, ['gh', 'issue', 'edit', String(issue.number), '--remove-label', label]);
        }
        // A torn loop/paused: no unreleased marker from any trunk.
        if (labels.includes('loop/paused')) {
          const byTrunk = new Map<number, boolean>();
          for (const c of tree.issue.comments) {
            if (c.author !== ctx.botLogin) continue;
            const m = parseMarker(c.body);
            if (m?.name === 'carve-pause') byTrunk.set(Number(m.fields.by), true);
            if (m?.name === 'carve-unpause') byTrunk.set(Number(m.fields.by), false);
          }
          const anyLive = [...byTrunk.values()].some(Boolean);
          if (!anyLive) {
            if (ctx.dryRun) log(`DRY RUN  would remove the torn loop/paused on #${issue.number}`);
            else {
              mutate(ctx, `comment on #${issue.number}`, ['gh', 'issue', 'comment', String(issue.number), '--body', 'loop/paused with no trunk pausing it; removed by the sweep. A person who wants this held uses loop/skip or a needs-* label.']);
              mutate(ctx, `unlabel #${issue.number} loop/paused`, ['gh', 'issue', 'edit', String(issue.number), '--remove-label', 'loop/paused']);
            }
          }
        }
        const isTrunkish = labels.includes('loop/carved') || labels.includes('loop/released') || labels.includes('loop/handed-off') || labels.some((l) => l.startsWith('loop/carve-gen')) || tree.record !== null || tree.children.length > 0;
        if (!isTrunkish) continue;
        const held = labels.some((l) => HOLD_LABELS.includes(l) && l !== 'loop/paused');
        const pending = tree.intents.some((i) => !i.finished && (i.kind === 'applying' || i.kind === 'released' || i.kind === 'carve-handoff'));
        if (pending) {
          await this.guard(issue.number, () => this.revisit(issue.number, 'an unfinished announcement'));
          continue;
        }
        if (labels.includes('loop/released')) {
          if (!held) await this.guard(issue.number, () => this.releaseAppraisal(issue.number));
          continue;
        }
        const redrive = Boolean(tree.record && tree.record.seen.holds.some((h) => !labels.includes(h)));
        if (held) {
          // The knife snapshots a hold it has not recorded, then leaves the trunk to its person.
          if (tree.record && !tree.record.seen.holds.some((h) => labels.includes(h))) await this.guard(issue.number, () => this.revisit(issue.number, 'a hold to snapshot'));
          continue;
        }
        if (redrive) {
          await this.guard(issue.number, () => this.revisit(issue.number, 'a hold was removed'));
          continue;
        }
        const why = needsRevisit(tree.record, tree, ctx.botLogin);
        if (why) await this.guard(issue.number, () => this.revisit(issue.number, why === 'no-record' ? 'no record' : `${why} changed`));
      } catch (error) {
        // One unreadable thread costs that issue this sweep, never the run: a rate limit on one read
        // would otherwise end every run at startup until the API recovered.
        if (error instanceof RunStopping || isStopping()) throw error;
        log(`  #${issue.number}  sweep: ${(error as Error).message.split('\n')[0]}; skipped this sweep, the next one retries`);
      }
    }

    // Second pass: oversized in the window, or an open child at any age.
    for (const issue of all) {
      try {
        if (!inScope(issue) || first.has(issue.number)) continue;
        const labels = issue.labels.map((l) => l.name);
        if (labels.some((l) => HOLD_LABELS.includes(l))) continue;
        const points = pointsOf(issue.labels);
        const summary = issue.subIssuesSummary;
        const openChild = summary !== undefined && summary.total > summary.completed;
        const oversized = points !== null && points > knobs.ceiling && (only !== null || issue.parent || Date.parse(issue.createdAt) >= cutoff);
        if (!openChild && !oversized) continue;
        const tree = readTree(ctx, issue.number, io);
        if (liveClaim(tree, new Date().toISOString(), ctx.runId)) continue;
        await this.guard(issue.number, () => this.revisit(issue.number, openChild ? 'an open child with no record' : `sized ${points}, over the ceiling`));
      } catch (error) {
        if (error instanceof RunStopping || isStopping()) throw error;
        log(`  #${issue.number}  sweep: ${(error as Error).message.split('\n')[0]}; skipped this sweep, the next one retries`);
      }
    }

    // Third pass: invalid blockers, and pauses left by closed trunks.
    for (const issue of all) {
      try {
        if (!inScope(issue)) continue;
        const blockers = issue.blockedBy?.nodes ?? [];
        const invalid = blockers.find((b) => b.state === 'DELETED' || (b.state === 'CLOSED' && (b.stateReason === 'NOT_PLANNED' || b.stateReason === 'DUPLICATE')));
        if (invalid) {
          const parent = issue.parent?.number ?? null;
          const parentNode = parent === null ? null : io.view(parent);
          if (parent !== null && parentNode && parentNode.state === 'OPEN') {
            await this.guard(parent, () => this.revisit(parent, `#${issue.number} has an invalid blocker #${invalid.number}`));
          } else if (!issue.labels.some((l) => l.name === 'needs-human')) {
            if (ctx.dryRun) log(`DRY RUN  would hand #${issue.number} to a person for its invalid blocker #${invalid.number}`);
            else {
              mutate(ctx, `comment on #${issue.number}`, ['gh', 'issue', 'comment', String(issue.number), '--body', `<!-- appraise-handoff verdict=needs-human -->\nBlocked by #${invalid.number}, which is ${invalid.state === 'DELETED' ? 'deleted' : 'closed not planned'}, and no open parent owns the dependency. A person decides whether this still waits on anything.`]);
              mutate(ctx, `label #${issue.number} needs-human`, ['gh', 'issue', 'edit', String(issue.number), '--add-label', 'needs-human']);
            }
          }
        }
        // Pauses whose trunk has closed. Each paused issue is judged on its own thread, against every
        // trunk that paused it: a marker is released only when its own trunk is closed, and the label
        // comes off only when no unreleased marker remains. Nothing depends on a parent's cleanup
        // having finished, so a write that failed partway is finished by the next sweep.
        if (issue.labels.some((l) => l.name === 'loop/paused')) {
          const node = io.view(issue.number);
          const held = [...unreleasedPauseMarkers(node?.comments ?? [], ctx.botLogin)].filter(([, paused]) => paused).map(([trunk]) => trunk);
          const closed = held.filter((trunk) => io.view(trunk)?.state !== 'OPEN');
          for (const trunk of closed) {
            if (ctx.dryRun) log(`DRY RUN  would release the pause #${trunk} left on #${issue.number}`);
            else mutate(ctx, `unpause #${issue.number} for closed #${trunk}`, ['gh', 'issue', 'comment', String(issue.number), '--body', `<!-- carve-unpause by=${trunk} -->\n#${trunk} is closed; its pause is released.`]);
          }
          if (closed.length > 0 && closed.length === held.length) {
            if (ctx.dryRun) log(`DRY RUN  would unlabel #${issue.number} loop/paused`);
            else mutate(ctx, `unlabel #${issue.number} loop/paused`, ['gh', 'issue', 'edit', String(issue.number), '--remove-label', 'loop/paused']);
          }
        }
      } catch (error) {
        if (error instanceof RunStopping || isStopping()) throw error;
        log(`  #${issue.number}  sweep: ${(error as Error).message.split('\n')[0]}; skipped this sweep, the next one retries`);
      }
    }
  }
}

export { isHeld };
export type { AppraiseKnobs };
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 CodeCodexVerifiedInstall
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