@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/ready-4f8edezt.js

@@ -0,0 +1,2016 @@
+// @bun
+import {
+  READINESS_REFUSAL_EXIT,
+  REMOTE,
+  SPEC_BLOCKED_LABEL,
+  SPEC_NEEDS_WORK_LABEL,
+  SPEC_READY_LABEL,
+  answeredYes,
+  blockedLineSentence,
+  boardRepoLabel,
+  createGhIssueBoard,
+  createGhRunner,
+  createGhSpecIssueReader,
+  createRefreshingGhIssueBoard,
+  epicProblemMessage,
+  ghBoardTrust,
+  goHome,
+  hasDiverged,
+  hasSpecReadyLabel,
+  hopDecisionSentence,
+  hopFilePath,
+  hopMoveSentence,
+  isLive,
+  issueSource,
+  loadConfig,
+  moduleOfLabels,
+  notReadySentence,
+  oneHopAllows,
+  openNextSources,
+  parseBaseStanding,
+  parseClaimMessage,
+  parseWorkingTree,
+  planLabel,
+  positionAt,
+  positionFilePath,
+  readBoardRepository,
+  readEpicProblems,
+  readHopRecord,
+  readPositionFile,
+  requireCompleteSpec,
+  requireTrustedBoardAuthor,
+  resolvePrProvider,
+  samePlace,
+  scanClaimBranches,
+  selectBoardRelations,
+  staleAgainst,
+  trackedChanges,
+  typeOfLabels,
+  writeHopRecord,
+  writePositionFile
+} from "./index-gqz4jn6j.js";
+import {
+  countTasks,
+  isFile,
+  parsePlan,
+  planFileName,
+  plural,
+  stubOfPlanFile
+} from "./index-39kbcw68.js";
+import {
+  CommandExit,
+  commandSpelling,
+  createGitRunner,
+  createLinePrompter,
+  gitSaid,
+  lazyPrompter
+} from "./index-cy98y87p.js";
+import"./index-2a7nb3an.js";
+import"./index-j4k2vdz3.js";
+import {
+  ConfigError
+} from "./index-gvek4r8m.js";
+import {
+  DEFAULT_BRANCH_TEMPLATE,
+  branchFromTemplate,
+  messageOf
+} from "./index-ykggr043.js";
+import"./index-z1w83f81.js";
+
+// src/cli/core/parseArgs.ts
+var REFUSAL = "parseArgs";
+function refuseArgumentAliases(args) {
+  for (const arg of args) {
+    if ((arg.aliases ?? []).length > 0) {
+      throw new TypeError(`${REFUSAL}: argument "${arg.name}" declares aliases, and a positional argument has no spelling for one to stand for`);
+    }
+  }
+}
+function spellingsOf(flags) {
+  const owners = new Map;
+  const claim = (spelling, name) => {
+    const owner = owners.get(spelling);
+    if (owner !== undefined && owner !== name) {
+      throw new TypeError(`${REFUSAL}: the spelling "${spelling}" names both flag "${owner}" and flag "${name}"`);
+    }
+    owners.set(spelling, name);
+  };
+  for (const flag of flags)
+    claim(flag.name, flag.name);
+  for (const flag of flags) {
+    for (const alias of flag.aliases ?? [])
+      claim(alias, flag.name);
+  }
+  return owners;
+}
+function readLine(argv, record) {
+  const positional = [];
+  for (let i = 0;i < argv.length; i++) {
+    const word = argv[i];
+    if (word === undefined)
+      continue;
+    if (word === "--") {
+      for (const rest of argv.slice(i + 1)) {
+        if (rest !== undefined)
+          positional.push(rest);
+      }
+      break;
+    }
+    const isLong = word.startsWith("--");
+    if (!isLong && !(word.startsWith("-") && word.length > 1)) {
+      positional.push(word);
+      continue;
+    }
+    const body = word.slice(isLong ? 2 : 1);
+    const eqIndex = body.indexOf("=");
+    const next = argv[i + 1];
+    if (eqIndex !== -1) {
+      record(body.slice(0, eqIndex), body.slice(eqIndex + 1));
+    } else if (isLong && body.startsWith("no-") && body.length > 3) {
+      record(body.slice(3), false);
+    } else if (next !== undefined && !next.startsWith("-")) {
+      record(body, next);
+      i++;
+    } else {
+      record(body, true);
+    }
+  }
+  return positional;
+}
+function parseArgs(argv, spec = {}) {
+  const { args = [], flags: flagSpecs = [] } = spec;
+  refuseArgumentAliases(args);
+  const spellings = spellingsOf(flagSpecs);
+  const flags = {};
+  const positional = readLine(argv, (spelling, value) => {
+    flags[spellings.get(spelling) ?? spelling] = value;
+  });
+  for (const flag of flagSpecs) {
+    if (flag.default === undefined || Object.hasOwn(flags, flag.name))
+      continue;
+    flags[flag.name] = typeof flag.default === "number" ? String(flag.default) : flag.default;
+  }
+  for (const arg of args.slice(positional.length)) {
+    if (arg.default === undefined)
+      break;
+    positional.push(String(arg.default));
+  }
+  return { positional, flags };
+}
+
+// src/next/relations-mode.ts
+async function modeConfig(root, home) {
+  try {
+    return (await loadConfig({ root, home }, {}, () => {
+      return;
+    })).config;
+  } catch (error) {
+    if (error instanceof ConfigError)
+      return null;
+    throw error;
+  }
+}
+async function openNextRelations(context, seams) {
+  const { project } = context;
+  if (project === null)
+    return;
+  const config = await modeConfig(project.root, project.home);
+  if (config?.boardRelationships !== "native")
+    return;
+  const provider = resolvePrProvider({ configured: config.prProvider, dir: project.root, readRemote: seams.readRemote });
+  if (provider.provider !== "gh")
+    return;
+  const gh = (seams.openGh ?? ((root) => createGhRunner({ cwd: root })))(project.root);
+  const repository = await readBoardRepository(gh);
+  return selectBoardRelations(config, { gh, repository });
+}
+
+// src/plan/list.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+function listing(dir, stub) {
+  const plan = join(dir, planFileName(stub, false));
+  const trackerPath = join(dir, planFileName(stub, true));
+  const tracker = isFile(trackerPath) ? trackerPath : null;
+  const planModel = parsePlan(readFileSync(plan, "utf8"));
+  const counted = tracker === null ? planModel : parsePlan(readFileSync(tracker, "utf8"));
+  return { stub, plan, tracker, tasks: countTasks(counted.tasks), issues: planModel.issues.length };
+}
+function listPlans(plans) {
+  const dir = plans.path;
+  if (!existsSync(dir))
+    return { dir, plans: [] };
+  const stubs = readdirSync(dir).filter((name) => isFile(join(dir, name))).map((name) => stubOfPlanFile(name)).filter((stub) => stub !== null).sort((a, b) => a.localeCompare(b));
+  return { dir, plans: stubs.map((stub) => listing(dir, stub)) };
+}
+
+// src/next/readings.ts
+var DETACHED = "HEAD";
+var PORCELAIN_PATH_AT = 3;
+function once(read) {
+  let held = null;
+  return () => {
+    held = held ?? { value: read() };
+    return held.value;
+  };
+}
+function readBranch(sources, note) {
+  const result = sources.git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (!result.ok) {
+    note(`the branch at the project root could not be read, so no branch names a plan or a pull request: ${gitSaid(result)}`);
+    return "";
+  }
+  const branch = result.stdout.trim();
+  if (branch !== DETACHED)
+    return branch;
+  note("the project root is on a detached HEAD, so no branch names a plan or a pull request");
+  return "";
+}
+function readStanding(sources, remote, note) {
+  const { base } = sources;
+  const tracking = `${remote}/${base}`;
+  const fetched = sources.git(["fetch", remote, base]);
+  if (!fetched.ok) {
+    note(`\`${tracking}\` could not be fetched, so how \`${base}\` stands is read off what this clone holds: ${gitSaid(fetched)}`);
+  }
+  const counted = sources.git(["rev-list", "--left-right", "--count", `${base}...${tracking}`]);
+  if (!counted.ok) {
+    note(`how \`${base}\` stands against \`${tracking}\` could not be read: ${gitSaid(counted)}`);
+    return null;
+  }
+  const standing = parseBaseStanding(counted.stdout);
+  if (standing === null) {
+    note(`git answered ${JSON.stringify(counted.stdout)} for how \`${base}\` stands against \`${tracking}\`, which is no pair of counts`);
+  }
+  return standing;
+}
+function changedPaths(entries) {
+  return Object.freeze(entries.map((entry) => entry.slice(PORCELAIN_PATH_AT).trim()));
+}
+function readTracked(sources, note) {
+  const result = sources.git(["status", "--porcelain"]);
+  if (!result.ok) {
+    note(`the working tree could not be read, so whether it holds changes to tracked files is unknown: ${gitSaid(result)}`);
+    return Object.freeze([]);
+  }
+  return changedPaths(trackedChanges(parseWorkingTree(result.stdout)));
+}
+function readCheckout(sources, note) {
+  const result = sources.git(["rev-parse", "--show-toplevel"]);
+  const checkout = result.ok ? result.stdout.trim() : "";
+  if (checkout !== "")
+    return checkout;
+  const why = result.ok ? "git printed no top level" : gitSaid(result);
+  note(`the checkout the working tree was read in could not be named: ${why}`);
+  return null;
+}
+function holdsTree(live, checkout) {
+  return live.some((record) => record.worktree === undefined) || live.some((record) => record.worktree === checkout());
+}
+function readRefs(sources, remote, note, scanner = scanClaimBranches) {
+  const scan = scanner(sources.git, remote, sources.branchTemplate);
+  scan.problems.forEach((problem) => note(problem));
+  return scan.refs;
+}
+function readPlans(sources, note) {
+  try {
+    const listing2 = listPlans(sources.plans);
+    return listing2.plans;
+  } catch (error) {
+    note(`the plans under ${sources.plans.label}/ could not be read: ${messageOf(error)}`);
+    return [];
+  }
+}
+async function readOpenPull(sources, branch, note) {
+  if (branch === "")
+    return null;
+  const summary = await sources.pulls.findOpen(branch);
+  if (summary === null)
+    return null;
+  const detail = await sources.pulls.get(summary.number);
+  if (detail === null) {
+    note(`the provider answered no pull request #${summary.number}, having just named it as the open one on \`${branch}\``);
+  }
+  const checks = await sources.pulls.checks(summary.number);
+  return { summary, mergeable: detail?.mergeable ?? "unknown", verdict: checks.verdict };
+}
+function readBranchPlan(branch, plans, template = DEFAULT_BRANCH_TEMPLATE) {
+  return plans.find((plan) => branchFromTemplate(template, plan.stub) === branch) ?? null;
+}
+function hasRun(records, stub) {
+  const file = planFileName(stub, false);
+  return records.some((record) => record.planStub === stub || record.plan === file || record.plan.endsWith(`/${file}`));
+}
+function hasBranch(refs, stub, template = DEFAULT_BRANCH_TEMPLATE) {
+  const branch = branchFromTemplate(template, stub);
+  return refs.some((ref) => ref === branch || ref.endsWith(`/${branch}`));
+}
+function readBranchTips(sources, remote, stub, note) {
+  const branch = planBranchOf(sources, stub);
+  const tips = [];
+  for (const ref of [`refs/heads/${branch}`, `refs/remotes/${remote}/${branch}`]) {
+    const resolved = sources.git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    const said = gitSaid(resolved);
+    if (resolved.ok && resolved.stdout.trim() !== "") {
+      tips.push(ref);
+    } else if (said !== "") {
+      note(`\`${ref}\` could not be read, so its plan reads as started: ${said}`);
+      return null;
+    }
+  }
+  return tips;
+}
+function planBranchOf(sources, stub) {
+  return branchFromTemplate(sources.branchTemplate ?? DEFAULT_BRANCH_TEMPLATE, stub);
+}
+function readBranchMessages(sources, ref, note) {
+  const result = sources.git(["log", "-z", "--format=%B", `${sources.base}..${ref}`]);
+  if (!result.ok) {
+    note(`the commits of \`${ref}\` past \`${sources.base}\` could not be read, so its plan reads as started: ${gitSaid(result)}`);
+    return null;
+  }
+  return result.stdout.split("\x00").map((message) => message.trim()).filter((message) => message !== "");
+}
+function claimsOnly(messages) {
+  return messages.length > 0 && messages.every((message) => parseClaimMessage(message).kind === "ownership");
+}
+function hasStartedBranch(sources, remote, refs, stub, note) {
+  if (!hasBranch(refs, stub, sources.branchTemplate))
+    return false;
+  const tips = readBranchTips(sources, remote, stub, note);
+  if (tips === null)
+    return true;
+  if (tips.length === 0) {
+    note(`\`${planBranchOf(sources, stub)}\` is on ${remote} but not fetched here, so its commits were not read and its plan reads as started`);
+    return true;
+  }
+  return tips.some((ref) => {
+    const messages = readBranchMessages(sources, ref, note);
+    return messages === null || !claimsOnly(messages);
+  });
+}
+function openWorld(sources) {
+  let problems = [];
+  const note = (problem) => {
+    problems = [...problems, problem];
+  };
+  const remote = sources.remote ?? REMOTE;
+  const runs = once(() => sources.runs());
+  const branch = once(() => readBranch(sources, note));
+  const plans = once(() => readPlans(sources, note));
+  const refs = once(() => readRefs(sources, remote, note));
+  const roadmap = once(async () => {
+    const reading = await sources.board.next();
+    reading.problems.forEach((problem) => note(problem));
+    return reading;
+  });
+  const checkout = once(() => readCheckout(sources, note));
+  return {
+    sources,
+    remote,
+    branch,
+    liveRun: once(() => runs().find((record) => isLive(record)) ?? null),
+    liveRunHoldsTree: once(() => holdsTree(runs().filter((record) => isLive(record)), checkout)),
+    standing: once(() => readStanding(sources, remote, note)),
+    tracked: once(() => readTracked(sources, note)),
+    checkout,
+    branchPlan: once(() => readBranchPlan(branch(), plans(), sources.branchTemplate)),
+    unstartedPlan: once(() => plans().find((plan) => !hasRun(runs(), plan.stub) && !hasStartedBranch(sources, remote, refs(), plan.stub, note)) ?? null),
+    openPull: once(() => readOpenPull(sources, branch(), note)),
+    roadmap,
+    picked: once(async () => {
+      if (branch() !== sources.base)
+        return null;
+      const { line } = await roadmap();
+      if (line === null)
+        return null;
+      return {
+        line,
+        ready: await sources.board.isReady(line.issue),
+        blocked: await sources.board.blocking(line.issue)
+      };
+    }),
+    problems: () => problems
+  };
+}
+function onBase(world) {
+  return world.branch() === world.sources.base;
+}
+function branchLabel(world) {
+  const branch = world.branch();
+  return branch === "" ? "this checkout" : `\`${branch}\``;
+}
+
+// src/next/hop-rows.ts
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function ref(issue) {
+  return `#${String(issue)}`;
+}
+function placeText(place) {
+  return place.epic === null ? `board ${ref(place.board)}` : `epic ${ref(place.epic)} on board ${ref(place.board)}`;
+}
+function dryHopSentence(dry, next) {
+  return `hop from epic ${ref(dry.number)}: it ran dry, next \`now\` epic ${ref(next.number)} on board ${ref(next.board)}`;
+}
+async function hopView(world) {
+  if (!onBase(world))
+    return null;
+  const reading = await world.roadmap();
+  return reading.hop === undefined ? null : { reading, hop: reading.hop };
+}
+function awayRecord(hop) {
+  return hop.record?.state === "away" ? hop.record : null;
+}
+function homeOf(view) {
+  return view.hop.position?.home ?? { board: view.reading.roadmap, epic: null };
+}
+function homeAnswer(id, reading, step, issue) {
+  return {
+    id,
+    action: "home",
+    reading,
+    proposal: `go back home to ${placeText(step.home)}`,
+    ...issue === null ? {} : { issue },
+    ...step.pullRequest === null ? {} : { pullRequest: step.pullRequest },
+    hop: Object.freeze(step)
+  };
+}
+async function readGate(roadmap, pullRequest) {
+  try {
+    return await roadmap.ownerApproval(pullRequest);
+  } catch (error) {
+    return {
+      state: "unknown",
+      reason: `could not read the owner gate of ${ref(pullRequest)}: ${oneLine(messageOf(error))}`,
+      owners: []
+    };
+  }
+}
+async function waitingIssue(world, pullRequest) {
+  let hop;
+  try {
+    hop = (await world.roadmap()).hop;
+  } catch {
+    return null;
+  }
+  const record = hop?.record ?? null;
+  if (record?.target === null || record === null)
+    return null;
+  const named = record.pullRequest === pullRequest || hop?.target?.pullRequest === pullRequest;
+  return named ? record.target : null;
+}
+async function readPrOwnerReview(world) {
+  const { roadmap } = world.sources;
+  if (roadmap === undefined)
+    return null;
+  const open = await world.openPull();
+  if (open === null || open.mergeable !== "mergeable")
+    return null;
+  if (open.verdict !== "green" && open.verdict !== "none")
+    return null;
+  const pullRequest = open.summary.number;
+  const gate = await readGate(roadmap, pullRequest);
+  if (gate.state === "not-gated" || gate.state === "approved")
+    return null;
+  const issue = await waitingIssue(world, pullRequest);
+  return {
+    id: "pr-owner-review",
+    action: "none",
+    reading: `waiting on ${ref(issue ?? pullRequest)} (owner review)`,
+    proposal: `leave ${ref(pullRequest)} to its owner's review, which rafa does not merge past: ${oneLine(gate.reason)}`,
+    pullRequest,
+    ...issue === null ? {} : { issue }
+  };
+}
+function dryEnded(view, record) {
+  const { dryEpic, line } = view.reading;
+  if (line !== null || dryEpic === undefined)
+    return null;
+  const step = { action: "home", home: record.home, closing: "halted", pullRequest: null };
+  const reading = `epic ${ref(dryEpic.number)}, where the dry hop went, has no line left, and a second hop would leave home behind`;
+  return homeAnswer("away-ended", reading, step, null);
+}
+async function notReadyEnded(world, record, target) {
+  const picked = await world.picked();
+  if (picked === null || picked.line.issue !== target || picked.ready || picked.blocked !== null)
+    return null;
+  const step = { action: "home", home: record.home, closing: "halted", pullRequest: null };
+  const reading = `${ref(target)}, the hop's target in epic ${ref(record.targetEpic)}, carries no \`${SPEC_READY_LABEL}\`, so its spec is refused as not ready`;
+  return homeAnswer("away-ended", reading, step, target);
+}
+async function readAwayEnded(world) {
+  const view = await hopView(world);
+  const record = view === null ? null : awayRecord(view.hop);
+  if (view === null || record === null)
+    return null;
+  if (record.kind === "dry")
+    return dryEnded(view, record);
+  const target = view.hop.target;
+  if (target === null)
+    return null;
+  const where = `${ref(target.issue)}, the hop's target in epic ${ref(record.targetEpic)}`;
+  if (target.closed) {
+    const step = { action: "home", home: record.home, closing: "merged", pullRequest: null };
+    return homeAnswer("away-ended", `${where}, is closed`, step, target.issue);
+  }
+  if (target.pullRequest !== null) {
+    const step = { action: "home", home: record.home, closing: "waiting", pullRequest: target.pullRequest };
+    return homeAnswer("away-ended", `${where}, has pull request ${ref(target.pullRequest)} open`, step, target.issue);
+  }
+  return notReadyEnded(world, record, target.issue);
+}
+function decisionOf(view, kind) {
+  const decision = view?.hop.decision ?? null;
+  return decision?.kind === kind ? decision : null;
+}
+async function readHopHalt(world) {
+  const view = await hopView(world);
+  const halt = decisionOf(view, "halt");
+  if (view === null || halt === null)
+    return null;
+  const home = view.hop.record?.home ?? view.hop.position?.home ?? halt.from;
+  const step = { action: "home", home, closing: "halted", pullRequest: null };
+  return homeAnswer("hop-halt", hopDecisionSentence(halt), step, halt.chain.blocked);
+}
+async function readHopBlocked(world) {
+  const view = await hopView(world);
+  const move = decisionOf(view, "hop");
+  if (view === null || move === null || awayRecord(view.hop) !== null)
+    return null;
+  const opening = {
+    kind: "blocker",
+    home: homeOf(view),
+    from: move.from,
+    blocked: move.blocked,
+    target: move.blocker,
+    targetEpic: move.epic,
+    targetBoard: move.board
+  };
+  return {
+    id: "hop-blocked",
+    action: "hop",
+    reading: hopDecisionSentence(move),
+    proposal: `hop to ${placeText(move.to)} and work ${ref(move.blocker)}, keeping home`,
+    issue: move.blocker,
+    hop: Object.freeze({ action: "hop", opening: Object.freeze(opening) })
+  };
+}
+function dryPlaces(view, dry) {
+  const from = { board: view.reading.roadmap, epic: dry.number };
+  const { position } = view.hop;
+  return {
+    from,
+    home: position === null || samePlace(position.current, position.home) ? from : position.home
+  };
+}
+async function readHopDry(world) {
+  const view = await hopView(world);
+  if (view === null || awayRecord(view.hop) !== null)
+    return null;
+  const { dryEpic, line } = view.reading;
+  const next = view.hop.nextEpic;
+  if (line !== null || dryEpic === undefined || next === null)
+    return null;
+  const { from, home } = dryPlaces(view, dryEpic);
+  const to = { board: next.board, epic: next.number };
+  if (!oneHopAllows(from, to, home))
+    return null;
+  const opening = {
+    kind: "dry",
+    home: homeOf(view),
+    from,
+    blocked: null,
+    target: null,
+    targetEpic: next.number,
+    targetBoard: next.board
+  };
+  return {
+    id: "hop-dry",
+    action: "hop",
+    reading: dryHopSentence(dryEpic, next),
+    proposal: `hop to ${placeText(to)}, keeping home`,
+    hop: Object.freeze({ action: "hop", opening: Object.freeze(opening) })
+  };
+}
+
+// src/next/preconditions.ts
+var MAX_NAMED_FILES = 5;
+function nameFiles(paths) {
+  const shown = paths.slice(0, MAX_NAMED_FILES).map((path) => `\`${path}\``);
+  const hidden = paths.length - shown.length;
+  return hidden > 0 ? `${shown.join(", ")} and ${hidden} more` : shown.join(", ");
+}
+function oneLine2(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function treeLabel(checkout) {
+  return checkout === null ? "the working tree" : `the working tree at \`${checkout}\``;
+}
+function readTreeModified(world) {
+  const paths = world.tracked();
+  if (paths.length === 0)
+    return null;
+  const tree = treeLabel(world.checkout());
+  return {
+    id: "tree-modified",
+    action: "none",
+    reading: `${tree} has changes to ${plural(paths.length, "tracked file")}: ${nameFiles(paths)}`,
+    proposal: "commit or set aside your changes; rafa will not touch them"
+  };
+}
+async function readPullsUnusable(world) {
+  try {
+    await world.openPull();
+    return null;
+  } catch (error) {
+    return {
+      id: "pulls-unusable",
+      action: "none",
+      reading: `the \`${world.sources.pulls.kind}\` pull request provider could not be asked: ${oneLine2(messageOf(error))}`,
+      proposal: "run `rafa doctor` to see what the provider needs, then read the state again"
+    };
+  }
+}
+
+// src/next/state.ts
+var PREFIX = "rafa next";
+var NEXT_PRECONDITIONS = Object.freeze([
+  "tree-modified",
+  "pulls-unusable"
+]);
+function prLabel(open) {
+  return `#${open.summary.number}`;
+}
+function readLoopRunning(world) {
+  const record = world.liveRun();
+  if (record === null)
+    return null;
+  return {
+    id: "loop-running",
+    action: "none",
+    reading: `a loop for \`${planLabel(record)}\` is ${record.state} on \`${record.branch}\`, session ${record.sessionId}`,
+    proposal: "nothing to start while it runs; `rafa loop status` says where it is",
+    planStub: record.planStub
+  };
+}
+function readBaseBehind(world) {
+  if (!onBase(world))
+    return null;
+  const standing = world.standing();
+  if (standing === null || standing.behind === 0)
+    return null;
+  const { base } = world.sources;
+  const tracking = `${world.remote}/${base}`;
+  const ahead = hasDiverged(standing) ? ` and ${plural(standing.ahead, "commit")} ahead of it` : "";
+  return {
+    id: "base-behind",
+    action: "sync",
+    reading: `\`${base}\` is ${plural(standing.behind, "commit")} behind \`${tracking}\`${ahead}`,
+    proposal: `fast-forward \`${base}\` to \`${tracking}\``
+  };
+}
+function readTrackerBlocked(world) {
+  const plan = world.branchPlan();
+  if (plan === null || plan.tasks.blocked === 0)
+    return null;
+  const held = `${plural(plan.tasks.blocked, "blocked task")} and ${plural(plan.tasks.open, "open one")}`;
+  return {
+    id: "tracker-blocked",
+    action: "resume",
+    reading: `\`${plan.stub}\` has ${held} on ${branchLabel(world)}`,
+    proposal: `resume the loop on \`${plan.stub}\`, which retries a blocked task first`,
+    planStub: plan.stub,
+    planPath: plan.plan
+  };
+}
+function readTrackerOpen(world) {
+  const plan = world.branchPlan();
+  if (plan === null || plan.tasks.open === 0)
+    return null;
+  return {
+    id: "tracker-open",
+    action: "resume",
+    reading: `\`${plan.stub}\` has ${plural(plan.tasks.open, "open task")} left on ${branchLabel(world)}`,
+    proposal: `resume the loop on \`${plan.stub}\``,
+    planStub: plan.stub,
+    planPath: plan.plan
+  };
+}
+async function readPrPending(world) {
+  const open = await world.openPull();
+  if (open === null)
+    return null;
+  if (open.verdict !== "pending" && open.mergeable !== "unknown")
+    return null;
+  const settling = open.verdict === "pending" ? "its checks are still running" : `GitHub has not settled whether it merges into \`${open.summary.baseRefName}\``;
+  return {
+    id: "pr-pending",
+    action: "wait",
+    reading: `${prLabel(open)} is open on \`${open.summary.headRefName}\` and ${settling}`,
+    proposal: `wait for the checks on ${prLabel(open)}`,
+    pullRequest: open.summary.number
+  };
+}
+function redClause(open) {
+  if (open.mergeable === "conflicting")
+    return `conflicts with \`${open.summary.baseRefName}\``;
+  return open.verdict === "red" ? "its checks are red" : null;
+}
+async function readPrRed(world) {
+  const open = await world.openPull();
+  if (open === null)
+    return null;
+  const why = redClause(open);
+  if (why === null)
+    return null;
+  return {
+    id: "pr-red",
+    action: "triage",
+    reading: `${prLabel(open)} is open on \`${open.summary.headRefName}\` and ${why}`,
+    proposal: `triage ${prLabel(open)}`,
+    pullRequest: open.summary.number
+  };
+}
+async function readPrNoChecks(world) {
+  const open = await world.openPull();
+  if (open === null || open.verdict !== "none" || open.mergeable !== "mergeable")
+    return null;
+  const base = `\`${open.summary.baseRefName}\``;
+  return {
+    id: "pr-no-checks",
+    action: "merge-unchecked",
+    reading: `${prLabel(open)} is open on \`${open.summary.headRefName}\`, reports no check at all and merges into ${base}`,
+    proposal: `merge ${prLabel(open)} into ${base} with no checks`,
+    pullRequest: open.summary.number
+  };
+}
+async function readPrGreen(world) {
+  const open = await world.openPull();
+  if (open === null || open.verdict !== "green" || open.mergeable !== "mergeable")
+    return null;
+  const base = `\`${open.summary.baseRefName}\``;
+  return {
+    id: "pr-green",
+    action: "merge",
+    reading: `${prLabel(open)} is open on \`${open.summary.headRefName}\`, green and merges into ${base}`,
+    proposal: `merge ${prLabel(open)} into ${base}`,
+    pullRequest: open.summary.number
+  };
+}
+function readPlanUnstarted(world) {
+  if (!onBase(world))
+    return null;
+  const plan = world.unstartedPlan();
+  if (plan === null)
+    return null;
+  return {
+    id: "plan-unstarted",
+    action: "start",
+    reading: `\`${plan.stub}\` is planned, with no run and no branch`,
+    proposal: `start the loop on \`${plan.stub}\`, creating its branch`,
+    planStub: plan.stub,
+    planPath: plan.plan
+  };
+}
+async function readIssueReady(world) {
+  const picked = await world.picked();
+  if (picked === null || !picked.ready || picked.blocked !== null)
+    return null;
+  const { issue } = picked.line;
+  return {
+    id: "issue-ready",
+    action: "plan",
+    reading: `#${issue} is next on the roadmap and carries \`${SPEC_READY_LABEL}\``,
+    proposal: `create the plan for #${issue}`,
+    issue
+  };
+}
+async function readIssueBlocked(world) {
+  if (world.sources.board.mode === "native")
+    return null;
+  const picked = await world.picked();
+  if (picked === null || picked.blocked === null)
+    return null;
+  const { issue } = picked.line;
+  return {
+    id: "issue-blocked",
+    action: "unblock",
+    reading: blockedLineSentence(picked.blocked),
+    proposal: `re-read the blockers of #${issue} and take \`${SPEC_BLOCKED_LABEL}\` off once they have all closed`,
+    issue
+  };
+}
+async function readIssueNotReady(world) {
+  const picked = await world.picked();
+  if (picked === null || picked.blocked !== null)
+    return null;
+  const { issue } = picked.line;
+  return {
+    id: "issue-not-ready",
+    action: "ready",
+    reading: notReadySentence(issue),
+    proposal: `check the spec of #${issue} and mark it ready`,
+    issue
+  };
+}
+function readNothingHere(world) {
+  const where = branchLabel(world);
+  const plan = world.branchPlan();
+  return {
+    id: "nothing-left",
+    action: "none",
+    reading: plan === null ? `${where} is no plan branch, and it has no open pull request` : `\`${plan.stub}\` has no task left on ${where}, and it has no open pull request`,
+    proposal: `nothing to run from ${where}; the cycle goes on from \`${world.sources.base}\``,
+    planStub: plan?.stub ?? null
+  };
+}
+async function readNothingLeft(world) {
+  if (!onBase(world))
+    return readNothingHere(world);
+  const roadmap = await world.roadmap();
+  const passed = plural(roadmap.passed, "line");
+  return {
+    id: "nothing-left",
+    action: "none",
+    reading: `the roadmap, issue #${roadmap.roadmap}, has no line left that is not done or taken (${passed} passed)`,
+    proposal: "open the next spec issue and add it to the roadmap"
+  };
+}
+var ROWS = Object.freeze([
+  { id: "loop-running", read: readLoopRunning },
+  { id: "base-behind", read: readBaseBehind },
+  { id: "tracker-blocked", read: readTrackerBlocked },
+  { id: "tracker-open", read: readTrackerOpen },
+  { id: "pr-pending", read: readPrPending, pulls: true },
+  { id: "pr-red", read: readPrRed, pulls: true },
+  { id: "pr-no-checks", read: readPrNoChecks, pulls: true },
+  { id: "pr-green", read: readPrGreen, pulls: true },
+  { id: "plan-unstarted", read: readPlanUnstarted },
+  { id: "issue-ready", read: readIssueReady },
+  { id: "issue-blocked", read: readIssueBlocked },
+  { id: "issue-not-ready", read: readIssueNotReady },
+  { id: "nothing-left", read: readNothingLeft }
+]);
+var NEXT_STATES = Object.freeze(ROWS.map((row) => row.id));
+var HOP_ROWS_AHEAD_OF = Object.freeze({
+  "pr-no-checks": [{ id: "pr-owner-review", read: readPrOwnerReview, pulls: true }],
+  "plan-unstarted": [{ id: "away-ended", read: readAwayEnded }],
+  "issue-blocked": [{ id: "hop-halt", read: readHopHalt }, { id: "hop-blocked", read: readHopBlocked }],
+  "nothing-left": [{ id: "hop-dry", read: readHopDry }]
+});
+var ROADMAP_ROWS = Object.freeze(ROWS.flatMap((row) => [...HOP_ROWS_AHEAD_OF[row.id] ?? [], row]));
+var NEXT_ROADMAP_STATES = Object.freeze(ROADMAP_ROWS.map((row) => row.id));
+var LOOP_ROW = new Set(["loop-running"]);
+var NO_ROW = new Set;
+function aheadOfTree(world) {
+  return world.liveRunHoldsTree() ? LOOP_ROW : NO_ROW;
+}
+async function firstAnswer(world, rows) {
+  for (const row of rows) {
+    if (row.pulls === true) {
+      const unusable = await readPullsUnusable(world);
+      if (unusable !== null)
+        return unusable;
+    }
+    const found = await row.read(world);
+    if (found !== null)
+      return found;
+  }
+  return null;
+}
+function answer(row, problems) {
+  return Object.freeze({
+    id: row.id,
+    action: row.action,
+    reading: row.reading,
+    proposal: row.proposal,
+    pullRequest: row.pullRequest ?? null,
+    issue: row.issue ?? null,
+    planStub: row.planStub ?? null,
+    planPath: row.planPath ?? null,
+    problems: Object.freeze([...problems]),
+    ...row.hop === undefined ? {} : { hop: row.hop }
+  });
+}
+async function readNextState(sources) {
+  const world = openWorld(sources);
+  const rows = sources.roadmap === undefined ? ROWS : ROADMAP_ROWS;
+  const ahead = aheadOfTree(world);
+  const found = await firstAnswer(world, rows.filter((row) => ahead.has(row.id))) ?? readTreeModified(world) ?? await firstAnswer(world, rows.filter((row) => !ahead.has(row.id)));
+  if (found !== null)
+    return answer(found, world.problems());
+  throw new Error(`${PREFIX}: no row of the table answered, and the last row answers for every reading`);
+}
+
+// src/next/hint.ts
+var HINT_FLAG = "hint";
+var HINT_TIMEOUT_MS = 2000;
+var HINT_MARK = "\uD83D\uDC49";
+var HINT_LEAD = "Next:";
+function commandWords(invocation) {
+  return [invocation.command, ...invocation.argv].join(" ");
+}
+function capitalised(text) {
+  return `${text.slice(0, 1).toUpperCase()}${text.slice(1)}`;
+}
+function nextQuestion(state) {
+  return `${capitalised(state.proposal)}? [y/N] `;
+}
+function hintLine(state, invocation) {
+  return `${HINT_MARK} ${HINT_LEAD} ${state.proposal} \u2014 rafa ${commandWords(invocation)}`;
+}
+function wantsHint(flags) {
+  const value = flags[HINT_FLAG];
+  return value !== false && value !== "false";
+}
+var DEFAULT_HINT_SEAMS = Object.freeze({});
+function afterDelay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+  });
+}
+function silenced() {
+  return Object.freeze({
+    info: () => {
+      return;
+    },
+    warn: () => {
+      return;
+    },
+    error: () => {
+      return;
+    },
+    debug: () => {
+      return;
+    },
+    emit: () => {
+      return;
+    },
+    result: () => {
+      return;
+    }
+  });
+}
+async function readOnce(context, seams) {
+  const relations = await openNextRelations(context, seams);
+  const sources = await openNextSources({ ...context, output: silenced() }, seams, relations === undefined ? {} : { relations });
+  return readNextState(sources);
+}
+async function readWithin(read, expire) {
+  const reading = Promise.resolve().then(read).then((state) => ({ state }), () => null);
+  const raced = await Promise.race([reading, expire(HINT_TIMEOUT_MS).then(() => null)]);
+  return raced === null ? null : raced.state;
+}
+async function nextStepHint(context, seams = DEFAULT_HINT_SEAMS) {
+  if (!wantsHint(context.flags))
+    return null;
+  try {
+    const read = seams.readState ?? (() => readOnce(context, seams));
+    const state = await readWithin(read, seams.expire ?? afterDelay);
+    if (state === null)
+      return null;
+    const invocation = actionInvocation(state);
+    if (invocation === null)
+      return null;
+    const isTerminal = seams.isTerminal ?? (() => process.stdin.isTTY === true);
+    if (isTerminal()) {
+      return Object.freeze({ kind: "question", state, invocation, line: nextQuestion(state) });
+    }
+    const line = hintLine(state, invocation);
+    context.output.info(line);
+    return Object.freeze({ kind: "command", state, invocation, line });
+  } catch {
+    return null;
+  }
+}
+
+// src/next/hop-action.ts
+import { rmSync } from "fs";
+var NO_REHOME = "--no-rehome";
+function hopLogLine(opening) {
+  const { from, blocked, target, targetEpic, targetBoard } = opening;
+  if (opening.kind === "dry" || blocked === null || target === null) {
+    return dryHopSentence({ number: from.epic ?? from.board }, { number: targetEpic, board: targetBoard });
+  }
+  return hopMoveSentence({ from, blocked, blocker: target, epic: targetEpic });
+}
+function homeLogLine(home) {
+  return `back home: ${placeText(home)}`;
+}
+function openedRecord(opening, now) {
+  return {
+    ...opening,
+    state: "away",
+    pullRequest: null,
+    startedAt: now.toISOString()
+  };
+}
+function writeRecord(root, record) {
+  try {
+    writeHopRecord(root, record);
+  } catch (error) {
+    throw new CommandExit(1, `\u274C Could not write ${hopFilePath(root)}: ${messageOf(error)}`);
+  }
+}
+function restoreRecord(root, before) {
+  if (before.set)
+    writeHopRecord(root, before.record);
+  else
+    rmSync(hopFilePath(root), { force: true });
+}
+async function runHop(world, step) {
+  const { opening } = step;
+  const before = readHopRecord(world.root);
+  const record = openedRecord(opening, world.now());
+  writeRecord(world.root, record);
+  try {
+    await world.switchTo([String(opening.targetEpic), NO_REHOME]);
+  } catch (error) {
+    restoreRecord(world.root, before);
+    throw error;
+  }
+  world.info(hopLogLine(opening));
+  return record;
+}
+function writePosition(root, position) {
+  try {
+    writePositionFile(root, position);
+  } catch (error) {
+    throw new CommandExit(1, `\u274C Could not write ${positionFilePath(root)}: ${messageOf(error)}`);
+  }
+}
+function movedHome(world, step) {
+  const reading = readPositionFile(world.root);
+  if (reading.set) {
+    if (samePlace(reading.position.current, reading.position.home))
+      return { now: reading.position, written: false };
+    return { now: goHome(reading.position), written: true };
+  }
+  if (reading.reason === "absent")
+    return { now: null, written: false };
+  world.warn(`${reading.detail}, so it is written afresh at home`);
+  return { now: positionAt(step.home), written: true };
+}
+function awayToClose(world, position) {
+  const reading = readHopRecord(world.root);
+  if (!reading.set) {
+    if (reading.reason !== "absent")
+      world.warn(`${reading.detail}, so no hop record is closed`);
+    return null;
+  }
+  const { record } = reading;
+  if (record.state !== "away" || position === null)
+    return null;
+  return staleAgainst(record, position) ? null : record;
+}
+function runHome(world, step) {
+  const moved = movedHome(world, step);
+  if (moved.written && moved.now !== null)
+    writePosition(world.root, moved.now);
+  const away = awayToClose(world, moved.now);
+  const closed = away === null ? null : { ...away, state: step.closing, pullRequest: step.pullRequest ?? away.pullRequest };
+  if (closed !== null)
+    writeRecord(world.root, closed);
+  const line = homeLogLine(moved.now?.home ?? step.home);
+  world.info(line);
+  return Object.freeze({
+    position: moved.written ? moved.now : null,
+    record: closed,
+    line
+  });
+}
+
+// src/next/actions.ts
+var PREFIX2 = "rafa next";
+var NEXT_IN_PROCESS_ACTIONS = Object.freeze(["sync", "hop", "home"]);
+var SWITCH_COMMAND = Object.freeze({ subject: "switch", action: "switch" });
+var ROADMAP_WORD = "--roadmap";
+var ROADMAP_PASSED_ACTIONS = new Set(["plan", "start", "resume"]);
+var CLAIM_AHEAD_WORD = "--claim-ahead";
+function passedWords(action, options) {
+  if (options.roadmap !== true || !ROADMAP_PASSED_ACTIONS.has(action))
+    return [];
+  return options.claimAhead === true && action === "plan" ? [ROADMAP_WORD, CLAIM_AHEAD_WORD] : [ROADMAP_WORD];
+}
+function needed(state, value, what) {
+  if (value === null) {
+    throw new Error(`${PREFIX2}: state "${state.id}" proposes "${state.action}" and names no ${what}`);
+  }
+  return String(value);
+}
+function pullRequestOf(state) {
+  return needed(state, state.pullRequest, "pull request");
+}
+function issueOf(state) {
+  return needed(state, state.issue, "issue");
+}
+function planFlagOf(state) {
+  return `--plan=${needed(state, state.planPath, "plan file")}`;
+}
+var ACTION_COMMANDS = Object.freeze({
+  resume: { subject: "loop", action: "start", argv: (state) => [planFlagOf(state)] },
+  wait: { subject: "pr", action: "wait", argv: (state) => [pullRequestOf(state)] },
+  triage: { subject: "pr", action: "triage", argv: (state) => [pullRequestOf(state)] },
+  merge: { subject: "pr", action: "merge", argv: (state) => [pullRequestOf(state), "--yes"] },
+  "merge-unchecked": { subject: "pr", action: "merge", argv: (state) => [pullRequestOf(state), "--skip-checks"] },
+  settle: { subject: "release", action: "settle", argv: () => [] },
+  start: { subject: "loop", action: "start", argv: (state) => [planFlagOf(state), "--create-branch"] },
+  plan: { subject: "plan", action: "create", argv: () => ["--next"] },
+  unblock: { subject: "issue", action: "unblock", argv: (state) => [issueOf(state)] },
+  ready: { subject: "issue", action: "ready", argv: (state) => [issueOf(state)] }
+});
+var NEXT_COMMAND_ACTIONS = Object.freeze(Object.keys(ACTION_COMMANDS));
+var LABELS_ONLY_ACTIONS = new Set(["unblock"]);
+var OFFERED_COMMAND_ACTIONS = Object.freeze({
+  labels: NEXT_COMMAND_ACTIONS,
+  native: Object.freeze(NEXT_COMMAND_ACTIONS.filter((action) => !LABELS_ONLY_ACTIONS.has(action)))
+});
+function offeredCommandActions(mode) {
+  return OFFERED_COMMAND_ACTIONS[mode];
+}
+function notOffered(state, mode) {
+  return new Error(`${PREFIX2}: state "${state.id}" proposes "${state.action}", which is offered in labels mode only` + ` and board.relationships is ${mode}: the tracker clears a blocker when it closes`);
+}
+function runsCommand(action) {
+  return NEXT_COMMAND_ACTIONS.includes(action);
+}
+function actionInvocation(state, options = {}) {
+  if (!runsCommand(state.action))
+    return null;
+  const mode = options.mode ?? "labels";
+  if (!offeredCommandActions(mode).includes(state.action))
+    throw notOffered(state, mode);
+  const spec = ACTION_COMMANDS[state.action];
+  return Object.freeze({
+    action: state.action,
+    command: commandSpelling(spec),
+    argv: Object.freeze([...spec.argv(state), ...passedWords(state.action, options)])
+  });
+}
+function actionContext(caller, command, argv) {
+  const { positional, flags } = parseArgs(argv, command);
+  return Object.freeze({
+    ...caller,
+    args: Object.freeze(positional),
+    flags: Object.freeze({ ...flags, [HINT_FLAG]: false }),
+    argv: Object.freeze([...argv])
+  });
+}
+async function runRegistered(caller, name, argv, step) {
+  const command = caller.registry.find(name.subject, name.action);
+  if (command === undefined) {
+    throw new CommandExit(1, `\u274C ${PREFIX2}: the "${step}" step runs "rafa ${commandSpelling(name)}", which is registered by nothing`);
+  }
+  await command.run(actionContext(caller, command, argv));
+}
+function hopWorld(caller, state) {
+  if (caller.project === null) {
+    throw new Error(`${PREFIX2}: the action "${state.action}" of state "${state.id}" runs inside a project, and was handed none`);
+  }
+  return {
+    root: caller.project.root,
+    switchTo: (argv) => runRegistered(caller, SWITCH_COMMAND, argv, state.action),
+    info: (line) => {
+      caller.output.info(line);
+    },
+    warn: (line) => {
+      caller.output.warn(line);
+    },
+    now: () => new Date
+  };
+}
+function noStep(state) {
+  return new Error(`${PREFIX2}: state "${state.id}" proposes "${state.action}" and carries no ${state.action} step`);
+}
+async function runHopStep(caller, state) {
+  const step = state.hop;
+  if (step?.action !== state.action)
+    throw noStep(state);
+  if (step.action === "hop") {
+    await runHop(hopWorld(caller, state), step);
+    return;
+  }
+  runHome(hopWorld(caller, state), step);
+}
+async function runAction(caller, state, options = {}) {
+  if (state.action === "hop" || state.action === "home") {
+    await runHopStep(caller, state);
+    return;
+  }
+  const invocation = actionInvocation(state, options);
+  if (invocation === null) {
+    throw new Error(`${PREFIX2}: the action "${state.action}" of state "${state.id}" runs no registered command`);
+  }
+  await runRegistered(caller, ACTION_COMMANDS[invocation.action], invocation.argv, invocation.action);
+}
+
+// src/next/ending.ts
+var HINT_FLAG_SPEC = Object.freeze({
+  name: HINT_FLAG,
+  description: "Ends by naming the one step that follows, asking it where there is a terminal to answer on;" + " `--no-hint` reads nothing and prints nothing.",
+  type: "boolean",
+  default: true
+});
+function actionOutput(output) {
+  return Object.freeze({ ...output, result: () => {
+    return;
+  } });
+}
+var DEFAULT_ENDING_SEAMS = Object.freeze({});
+async function endWithNextStep(context, seams = DEFAULT_ENDING_SEAMS) {
+  const hint = await nextStepHint(context, seams);
+  if (hint === null)
+    return null;
+  if (hint.kind !== "question")
+    return Object.freeze({ hint, asked: false, ran: false });
+  const open = seams.openPrompter ?? (() => createLinePrompter(process.stdin, process.stderr));
+  const prompter = open();
+  let taken;
+  try {
+    taken = answeredYes(await prompter.ask(hint.line));
+  } finally {
+    prompter.close();
+  }
+  if (!taken)
+    return Object.freeze({ hint, asked: true, ran: false });
+  await runAction({ ...context, output: actionOutput(context.output) }, hint.state);
+  return Object.freeze({ hint, asked: true, ran: true });
+}
+
+// src/commands/issue/declarations.ts
+var ISSUE_SUBJECT = Object.freeze({
+  name: "issue",
+  summary: "the tracker: list, show, create, edit, comment on and move issues; mark one ready, unblock it and check its references"
+});
+var ISSUE_STATE_WORDS = Object.freeze([
+  "backlog",
+  "todo",
+  "in-progress",
+  "in-review",
+  "done",
+  "released",
+  "cancelled"
+]);
+var ISSUE_TYPE_WORDS = Object.freeze([
+  "code",
+  "bug",
+  "spike",
+  "adr",
+  "chore",
+  "package-api",
+  "epic",
+  "spec"
+]);
+var ISSUE_PRIORITY_WORDS = Object.freeze([
+  "urgent",
+  "high",
+  "medium",
+  "low"
+]);
+var ISSUE_TRIAGE_MODULE = "unassigned";
+var ISSUE_READY_LABEL = "spec:ready";
+var ISSUE_NEEDS_WORK_LABEL = "spec:needs-work";
+var ISSUE_BLOCKED_LABEL = "spec:blocked";
+var ISSUE_HINT_FLAG_SPEC = Object.freeze({
+  name: "hint",
+  description: "Ends by naming the one step that follows, asking it where there is a terminal to answer on;" + " `--no-hint` reads nothing and prints nothing.",
+  type: "boolean",
+  default: true
+});
+var DEFAULT_ISSUE_TYPE = "code";
+var PRIORITY_FLAG = "priority";
+var STAMP_FLAG = "stamp";
+var READY_YES_FLAG = "yes";
+var READY_DRY_RUN_FLAG = "dry-run";
+var UNBLOCK_ALL_FLAG = "all";
+var UNBLOCK_YES_FLAG = "yes";
+var ISSUE_LIST_FLAGS = Object.freeze([
+  {
+    name: "roadmap",
+    description: "List the unticked lines of the Roadmap issue instead, in its order, with the spec, blocked by," + " has and refs columns, and the epics it names grouped by horizon. Reads the GitHub board whatever" + " tracker the chain lands on.",
+    type: "boolean"
+  },
+  {
+    name: "all",
+    description: "With --roadmap, keep the ticked lines too, each in its place, and show the epics of every" + " horizon, not only now. Refused without --roadmap.",
+    type: "boolean"
+  },
+  {
+    name: "full",
+    description: "With --roadmap, print each epic's issues under its row, on two rows each: number, state and" + " title, then labels and blockers. Refused without --roadmap.",
+    type: "boolean"
+  },
+  {
+    name: "check",
+    description: "With --roadmap, exit 1 when any type:epic issue on the board is open with its work done, or" + " closed with it not done, or when the board could not be read, naming each. Refused without --roadmap.",
+    type: "boolean"
+  },
+  {
+    name: "labels",
+    description: "With --roadmap, print each issue's labels on a row of their own under it, and under each --full" + " member; they are no column. Refused without --roadmap.",
+    type: "boolean"
+  },
+  {
+    name: "texts",
+    description: "With --roadmap, spell the spec and blocked by columns in words instead of symbols, with no legend." + " Refused without --roadmap.",
+    type: "boolean",
+    aliases: ["t"]
+  },
+  {
+    name: "refresh",
+    description: "With --roadmap, read the whole board again instead of only what changed since the listing kept" + " under .rafa/cache/. Refused without --roadmap.",
+    type: "boolean"
+  },
+  {
+    name: "state",
+    description: `Only issues in this state: one of ${ISSUE_STATE_WORDS.join(", ")}. Refused on the github tracker` + " and beside --roadmap.",
+    type: "string"
+  },
+  {
+    name: "type",
+    description: `Only issues of this type: one of ${ISSUE_TYPE_WORDS.join(", ")}.`,
+    type: "string"
+  },
+  {
+    name: "module",
+    description: "Only issues of this module.",
+    type: "string"
+  },
+  {
+    name: "search",
+    description: "Only issues whose title or body holds this text.",
+    type: "string"
+  },
+  {
+    name: "limit",
+    description: "At most this many issues, a positive whole number. The limit of the tracker when left out," + " and none under --roadmap.",
+    type: "number"
+  }
+]);
+var ISSUE_LIST_DECLARATION = Object.freeze({
+  name: "issue list",
+  subject: ISSUE_SUBJECT.name,
+  action: "list",
+  summary: "list the issues on the tracker, or the Roadmap's lines in its order, narrowed by type, module or text",
+  description: "Lists the issues on the tracker `tracker.default` names in `.rafa/config.yaml`, or on the first" + " `tracker.fallback` kind whose preflight passes when it fails, each kind passed over warned about." + " Prints the tracker, then one row per issue: its id, state, type and title; under `--type=bug`, a header" + " and the columns id, state, module, action and summary, read back from each title. Each flag narrows the" + " list, and a flag left out narrows by nothing. The github tracker holds an issue open or closed, so" + " it refuses `--state`, and lists 30 issues unless `--limit` says otherwise. With `--roadmap` it lists" + " the unticked lines of the Roadmap issue (`roadmap.issue`, else the lowest-numbered open type:roadmap" + " board, else the open issue titled Roadmap) in its" + " order instead, read off the GitHub board, as a table adding four columns: spec, whether the issue" + " can be planned (every section of the spec template filled, and the spec:ready label on it), as a" + " symbol; blocked by, the blockers grouped by whether they are still open;" + " has, a plan, a branch or a pull request already made for it; and refs, how many references of the" + " issue's saved copy under `specs.dir` read suspect or dangling, `-` with no copy. A legend names each" + " symbol, `--texts` (`-t`) spells them in words, and `--labels` prints the labels on a row under each" + " issue. A Roadmap naming epics prints them alone, grouped by horizon under a `Roadmap #<n> \xB7 <horizon>`" + " heading with the columns #, state, done/total, blocked, date and title, the now horizon only unless" + " `--all`, with one line counting the lines naming no epic; `--full` prints each epic's issues under" + " its row, and the lines naming no epic as the table. The board listing is kept under .rafa/cache/ and" + " read for what changed since; `--refresh` reads the whole board again. `--check` exits 1 when any" + " type:epic issue's stored state" + " disagrees with its computed one. `--type`, `--module`, `--search` and `--limit` then narrow the spec rows, keeping their" + " order, and an unreachable board is warned about with the rows still printed. With `--output=json`" + " the tracker, the query and every issue, or under `--roadmap` the roadmap, the rows, the epics and the" + " warnings, are the data of the terminal result event.",
+  args: [],
+  flags: [...ISSUE_LIST_FLAGS],
+  examples: [
+    {
+      cmd: "rafa issue list",
+      note: "Lists the issues on the tracker the chain lands on, one row each."
+    },
+    {
+      cmd: "rafa issue list --type=bug --search=timeout",
+      note: "Lists the bugs whose title or body holds the word timeout, in the columns id, state, module, action and summary."
+    },
+    {
+      cmd: "rafa issue list --limit=5 --output=json",
+      note: "Writes a start event, then a result event whose data holds the tracker, the query and five issues at most."
+    },
+    {
+      cmd: "rafa issue list --roadmap",
+      note: "Prints the Roadmap's unticked lines in its order, with the spec, blocked by, has and refs of each."
+    },
+    {
+      cmd: "rafa issue list --roadmap --full",
+      note: "Prints the Roadmap's now epics with each epic's issues underneath, then its spec lines."
+    },
+    {
+      cmd: "rafa issue list --roadmap --check",
+      note: "Prints the Roadmap, then exits 1 when an epic is open with its work done or closed with it not done."
+    },
+    {
+      cmd: "rafa issue list --roadmap --all --type=bug",
+      note: "Prints the bugs on the Roadmap, ticked lines included, in the Roadmap's order, beside its epics of every horizon."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_SHOW_DECLARATION = Object.freeze({
+  name: "issue show",
+  subject: ISSUE_SUBJECT.name,
+  action: "show",
+  summary: "show one issue on the tracker: its fields, then its body",
+  description: "Reads one issue on the tracker `tracker.default` names in `.rafa/config.yaml`, or on the first" + " `tracker.fallback` kind whose preflight passes when it fails, each kind passed over warned about." + " The id is the issue number on that tracker, so on a tracker fallen back to it names a different" + " issue. Prints the tracker, the id, the URL when there is one, the title, state, type, module and" + " priority, then the body. With `--output=json` the tracker and the issue are the data of the" + " terminal result event.",
+  args: [
+    {
+      name: "id",
+      description: "The issue id on the tracker: a GitHub issue number, or the number of a file under `.rafa/issues/`.",
+      type: "string",
+      required: true
+    }
+  ],
+  flags: [],
+  examples: [
+    {
+      cmd: "rafa issue show 12",
+      note: "Prints issue 12 on the tracker the chain lands on, its fields and then its body."
+    },
+    {
+      cmd: "rafa issue show 12 --output=json",
+      note: "Writes a start event, then a result event whose data holds the tracker and the issue."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_CREATE_DECLARATION = Object.freeze({
+  name: "issue create",
+  subject: ISSUE_SUBJECT.name,
+  action: "create",
+  summary: "create an issue on the tracker from a title and a body, a bug from its fields",
+  description: "Files one issue on the tracker `tracker.default` names in `.rafa/config.yaml`, or on the first" + " `tracker.fallback` kind whose preflight passes when it fails, each kind passed over warned about." + " `--title` is required for every type but `bug`. The issue is of type `code` and module `unassigned` unless" + " `--type` and `--module` say otherwise, and with no `--priority` the tracker marks it needs-triage. A" + " `--type=bug` line is filed from its fields: `--module`, `--action`, `--summary`, `--cause` and" + " `--reproduce`, each also read from a section of the body, with rafa filling the versions and the place," + " rendering the title through `issues.titles.bug` and refusing a record missing a field, naming each. The body is" + " `--body`, or what the file `--body-file` names holds, standard input for `-`. A spec whose body" + " carries a `Blocked by: #24` line is filed blocked, and refused when the line names no issue, the" + " issue itself or an issue the board does not hold. With `board.project.number` set, a GitHub issue is" + " added to the project and its fields filled, any failure there a warning that keeps the exit code. Prints the" + " tracker and id of the issue filed, and its URL when there is one. With `--output=json` the tracker" + " and the ref are the data of the terminal result event. `--dry-run` prints the title and body the line" + " would file, resolves no tracker and files nothing.",
+  args: [],
+  flags: [
+    {
+      name: "title",
+      description: "The title of the issue. Required for every type but bug, whose title is rendered from its fields.",
+      type: "string"
+    },
+    {
+      name: "body",
+      description: "The body of the issue, as markdown. Empty when left out. Not with --body-file.",
+      type: "string"
+    },
+    {
+      name: "body-file",
+      description: "A file holding the body of the issue, read whole; `-` reads standard input. Not with --body.",
+      type: "string"
+    },
+    {
+      name: "type",
+      description: `What the issue is for: one of ${ISSUE_TYPE_WORDS.join(", ")}.`,
+      type: "string",
+      default: DEFAULT_ISSUE_TYPE
+    },
+    {
+      name: "module",
+      description: `The module the issue belongs to; ${ISSUE_TRIAGE_MODULE} when left out. A bug names one, or unknown.`,
+      type: "string"
+    },
+    {
+      name: "priority",
+      description: `How urgent the issue is: one of ${ISSUE_PRIORITY_WORDS.join(", ")}. Marked needs-triage when left out.`,
+      type: "string"
+    },
+    {
+      name: "summary",
+      description: "A bug: one line saying what is wrong, the last part of its title.",
+      type: "string"
+    },
+    {
+      name: "action",
+      description: "A bug: what was running, a command, a step or a test; or unknown.",
+      type: "string"
+    },
+    {
+      name: "cause",
+      description: "A bug: its cause code from `rafa bug codes`, or <family>:new-context when no leaf fits.",
+      type: "string"
+    },
+    {
+      name: "proposed",
+      description: "A bug: beside a new-context cause, the leaf you would have used, as <family>:<leaf>.",
+      type: "string"
+    },
+    {
+      name: "reproduce",
+      description: "A bug: the steps, or the condition that revealed it. Never unknown.",
+      type: "string"
+    },
+    {
+      name: "rerun",
+      description: "A bug: one command that shows it again.",
+      type: "string"
+    },
+    {
+      name: "env",
+      description: "A bug: the place it was seen, one of local, ci, prod, a place `issues.environments` adds, or" + " unknown. Left out, ci when the CI variable is set and local otherwise.",
+      type: "string"
+    },
+    {
+      name: "project",
+      description: "A bug: the project, where one tracker holds several.",
+      type: "string"
+    },
+    {
+      name: "path",
+      description: "A bug: the file the error points at, which names the package its Versions section holds. Left" + " out, the first file of the project the artifact names.",
+      type: "string"
+    },
+    {
+      name: "dry-run",
+      description: "Print the title and the body the line would file, resolve no tracker and file nothing.",
+      type: "boolean"
+    }
+  ],
+  examples: [
+    {
+      cmd: 'rafa issue create --type=bug --module=loop --action=start --summary="resume does not find the worktree branch"' + ' --reproduce="rafa loop start --continue after a stop" --cause=git:new-context --proposed=git:branch-not-found --dry-run',
+      note: "Prints the title `loop - start: resume does not find the worktree branch` and the body of the bug, and files nothing."
+    },
+    {
+      cmd: 'rafa issue create --title="Document issue move" --priority=low --output=json',
+      note: "Writes a start event, then a result event whose data holds the tracker and the ref of the issue."
+    },
+    {
+      cmd: 'rafa issue create --title="Faster plan show" --body-file=spec.md',
+      note: "Files an issue whose body is what spec.md holds; --body-file=- reads it from standard input."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_COMMENT_DECLARATION = Object.freeze({
+  name: "issue comment",
+  subject: ISSUE_SUBJECT.name,
+  action: "comment",
+  summary: "comment on one issue on the tracker",
+  description: "Posts `--body` as a comment on one issue on the tracker `tracker.default` names in" + " `.rafa/config.yaml`, or on the first `tracker.fallback` kind whose preflight passes when it fails," + " each kind passed over warned about. The id is the issue number on that tracker, so on a tracker" + " fallen back to it names a different issue. With `--output=json` the tracker and the ref commented" + " on are the data of the terminal result event.",
+  args: [
+    {
+      name: "id",
+      description: "The issue id on the tracker: a GitHub issue number, or the number of a file under `.rafa/issues/`.",
+      type: "string",
+      required: true
+    }
+  ],
+  flags: [
+    {
+      name: "body",
+      description: "The comment, as markdown. Required.",
+      type: "string",
+      required: true
+    }
+  ],
+  examples: [
+    {
+      cmd: 'rafa issue comment 12 --body="Seen again after the retry change."',
+      note: "Posts one comment on issue 12 on the tracker the chain lands on."
+    },
+    {
+      cmd: "rafa issue comment 12 --body=Reproduced --output=json",
+      note: "Writes a start event, then a result event whose data holds the tracker and the ref commented on."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_MOVE_DECLARATION = Object.freeze({
+  name: "issue move",
+  subject: ISSUE_SUBJECT.name,
+  action: "move",
+  summary: "move one issue on the tracker to a state",
+  description: "Moves one issue on the tracker `tracker.default` names in `.rafa/config.yaml`, or on the first" + " `tracker.fallback` kind whose preflight passes when it fails, each kind passed over warned about," + ` to one of the states ${ISSUE_STATE_WORDS.join(", ")}. The id is the issue number on that tracker, so on` + " a tracker fallen back to it names a different issue. The github tracker holds an issue open or" + " closed, so it warns for backlog, in-progress, in-review and released, which it cannot hold, and" + " still exits 0. With `--output=json` the tracker, the ref, the state and the warning are the data" + " of the terminal result event.",
+  args: [
+    {
+      name: "id",
+      description: "The issue id on the tracker: a GitHub issue number, or the number of a file under `.rafa/issues/`.",
+      type: "string",
+      required: true
+    },
+    {
+      name: "state",
+      description: `The state to move the issue to: one of ${ISSUE_STATE_WORDS.join(", ")}.`,
+      type: "string",
+      required: true
+    }
+  ],
+  flags: [],
+  examples: [
+    {
+      cmd: "rafa issue move 12 done",
+      note: "Moves issue 12 to done, which closes it on the github tracker."
+    },
+    {
+      cmd: "rafa issue move 12 in-progress --output=json",
+      note: "Writes a start event, then a result event whose data holds the tracker, the ref, the state and any warning."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_READY_DECLARATION = Object.freeze({
+  name: "issue ready",
+  subject: ISSUE_SUBJECT.name,
+  action: "ready",
+  summary: `mark an issue ${ISSUE_READY_LABEL} once its author and its body check out`,
+  description: "Reads the issue on the GitHub board, refuses one opened by an account without write access to" + " the repository, refuses a body that does not fill the spec template, refuses an issue carrying two" + " `epic:` labels (with board.relationships set to labels, the default), and then asks whether to mark it" + ` ${ISSUE_READY_LABEL}. On a yes it swaps the labels in one write, adding ${ISSUE_READY_LABEL} and` + ` removing ${ISSUE_NEEDS_WORK_LABEL}. \`--yes\` makes the swap with no question once every check passes,` + " with or without a terminal, and refuses everything the checks refuse without it; without a terminal and" + " without `--yes` it prints both readings and adds no label. A run that marks the issue, or finds" + " it marked already, ends by naming the one step that follows, which `--no-hint` turns off." + " `--dry-run` makes every check and prints both readings, asking nothing and writing nothing whatever" + " the terminal, exits 2 on a check that refuses, and is refused beside `--yes`. With" + " `--output=json` the report is the data of the terminal result event.",
+  args: [
+    {
+      name: "n",
+      description: "The issue number on the GitHub board.",
+      type: "string",
+      required: true
+    }
+  ],
+  flags: [
+    {
+      name: READY_YES_FLAG,
+      description: `Marks the issue ${ISSUE_READY_LABEL} without asking, once its author and its body check out;` + " a check that refuses still refuses. Needed where standard input is no terminal.",
+      type: "boolean"
+    },
+    {
+      name: READY_DRY_RUN_FLAG,
+      description: "Prints both readings and writes nothing, asking no question whatever the terminal;" + " a check that refuses still exits 2. Not with --yes.",
+      type: "boolean"
+    },
+    ISSUE_HINT_FLAG_SPEC
+  ],
+  examples: [
+    {
+      cmd: "rafa issue ready 57",
+      note: `Checks #57 and asks whether to mark it ${ISSUE_READY_LABEL}.`
+    },
+    {
+      cmd: "rafa issue ready 57 --yes",
+      note: `Checks #57 and marks it ${ISSUE_READY_LABEL} with no question, from a script or an agent.`
+    },
+    {
+      cmd: "rafa issue ready 57 --dry-run",
+      note: "Checks #57 and reads its status in one line, from a script, an agent or CI, marking nothing."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_UNBLOCK_DECLARATION = Object.freeze({
+  name: "issue unblock",
+  subject: ISSUE_SUBJECT.name,
+  action: "unblock",
+  summary: `take ${ISSUE_BLOCKED_LABEL} off an issue whose blockers have all closed`,
+  description: `Reads the "Blocked by: #24 #26" line of an issue labelled ${ISSUE_BLOCKED_LABEL} on the GitHub` + " board, asks the board for each blocker's state, and when every blocker is closed asks whether to" + ` remove ${ISSUE_BLOCKED_LABEL} and removes it on a yes. With a blocker still open it names it and` + ` changes nothing. An issue labelled ${ISSUE_BLOCKED_LABEL} whose "Blocked by:" line is missing, names` + " itself or names an id the board has no issue for is reported and never guessed at. Without a" + " terminal and without `--yes` it asks nothing and writes nothing. `--yes` answers the question yes" + " without putting it, terminal or not, and names the blockers it read closed; it never removes" + ` ${ISSUE_BLOCKED_LABEL} from an issue with a blocker open or a line it refuses to guess at.` + " With `--output=json` the outcome of each issue is the" + " data of the terminal result event. With board.relationships set to native it reads nothing and" + " writes nothing: GitHub clears a blocker by itself when the blocking issue closes.",
+  args: [
+    {
+      name: "n",
+      description: "The issue number on the GitHub board. Left out, `--all` reads every blocked issue.",
+      type: "string",
+      required: false
+    }
+  ],
+  flags: [
+    {
+      name: UNBLOCK_ALL_FLAG,
+      description: `Read every open issue labelled ${ISSUE_BLOCKED_LABEL}, asking about each one in turn.`,
+      type: "boolean"
+    },
+    {
+      name: UNBLOCK_YES_FLAG,
+      description: `Answer the question yes without putting it, so ${ISSUE_BLOCKED_LABEL} comes off every issue` + " whose blockers are all closed, with no terminal needed. An open blocker or an unreadable" + ' "Blocked by:" line still changes nothing.',
+      type: "boolean"
+    }
+  ],
+  examples: [
+    {
+      cmd: "rafa issue unblock 57",
+      note: `Asks whether to remove ${ISSUE_BLOCKED_LABEL} from #57 when every issue its "Blocked by:" line names is closed.`
+    },
+    {
+      cmd: "rafa issue unblock 57 --yes",
+      note: `Removes ${ISSUE_BLOCKED_LABEL} from #57 with no question when every blocker it names is closed.`
+    },
+    {
+      cmd: "rafa issue unblock --all",
+      note: "Walks every open blocked issue on the board, asking about each one whose blockers have all closed."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_CHECK_DECLARATION = Object.freeze({
+  name: "issue check",
+  subject: ISSUE_SUBJECT.name,
+  action: "check",
+  summary: "read the references a spec's saved copy names, each with its state",
+  description: "Reads the saved copy of issue <n> under `specs.dir` and prints every reference it names \u2014 an" + " issue, a file, a declared symbol, a command, a flag, a config key \u2014 with its state against the" + " stamp the copy keeps: ok, new, dangling, suspect, resolved or unknown. A reference the copy keeps no" + " stamp for is stamped on this read. Exits 0 whatever the states are, and plans nothing. A missing" + " saved copy is refused, naming the `rafa plan create --issue=<n>` that writes one. With" + " `--output=json` every reference, with its kind, line, state and fingerprint, is the data of the" + " terminal result event.",
+  args: [
+    {
+      name: "n",
+      description: "The issue number on the GitHub board whose saved copy is read.",
+      type: "string",
+      required: true
+    }
+  ],
+  flags: [
+    {
+      name: STAMP_FLAG,
+      description: "Re-stamp every reference with what its target holds now, so the next check reads each one ok.",
+      type: "boolean"
+    }
+  ],
+  examples: [
+    {
+      cmd: "rafa issue check 151",
+      note: "Prints each reference the saved copy of #151 names with its state, and a count per state."
+    },
+    {
+      cmd: "rafa issue check 151 --stamp",
+      note: "Prints the same reading, then re-stamps every reference as reviewed without planning."
+    },
+    {
+      cmd: "rafa issue check 151 --output=json",
+      note: "Writes a start event, then a result event whose data lists every reference with its kind, line, state and fingerprint."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+var ISSUE_EDIT_DECLARATION = Object.freeze({
+  name: "issue edit",
+  subject: ISSUE_SUBJECT.name,
+  action: "edit",
+  summary: "append a dated update to an issue body, or replace its body or title, after four gates",
+  description: "Edits one issue on the tracker the chain lands on, after four gates weighed in order, the first" + " refusal ending the run with nothing written and exit code 2: the account editing must have write" + " access or be in board.trustedAuthors; so must the issue's author; the text added must leak nothing," + " and a complete spec must stay complete; and the issue must be open, its labels and saved spec copies" + " allowing the edit. An append (`--append-file` or `--append`, with `--reason`) adds a block" + " `**Updated <YYYY-MM-DD>, <reason>:**` below the body, leaving the original part byte for byte; the" + " same block already closing the body answers `already`. `--replace-file` replaces the body and" + " `--title` the title. `--priority` sets the priority, removes every other and takes the issue out" + " of triage in one write, alone or beside `--title`, weighed by the gates as a title change; a priority" + " the issue already holds alone answers `already`. After the write the issue is read again: a body that no longer holds what was" + " written answers `conflict` with exit code 1, the bodies read before and after saved under" + " `.rafa/scratch/`. An append on an issue already planned answers `stale-copy` and names" + " `rafa plan create --issue=<n> --refresh`, which it never runs. `--dry-run` prints each gate's" + " reading and the added part and writes nothing. With `--output=json` the report and the tracker are" + " the data of the terminal result event.",
+  args: [
+    {
+      name: "n",
+      description: "The issue number on the tracker.",
+      type: "string",
+      required: true
+    }
+  ],
+  flags: [
+    {
+      name: "append-file",
+      description: "A file holding the text to append, read whole; `-` reads standard input." + " Needs --reason. Not with --append, --replace-file, --title or --priority.",
+      type: "string"
+    },
+    {
+      name: "append",
+      description: "The text to append. Needs --reason. Not with --append-file, --replace-file, --title or --priority.",
+      type: "string"
+    },
+    {
+      name: "reason",
+      description: "Why the update was made, written into its heading. Required with an append, refused otherwise.",
+      type: "string"
+    },
+    {
+      name: "replace-file",
+      description: "A file holding the new body, read whole; `-` reads standard input. Not with an append or --priority.",
+      type: "string"
+    },
+    {
+      name: "title",
+      description: "The new title, alone or beside --replace-file or --priority. Not with an append.",
+      type: "string"
+    },
+    {
+      name: PRIORITY_FLAG,
+      description: `The new priority, one of ${ISSUE_PRIORITY_WORDS.join(", ")}: it replaces the one the issue holds and takes` + " the issue out of triage. Alone or beside --title. Not with an append or --replace-file.",
+      type: "string"
+    },
+    {
+      name: "while-in-development",
+      description: "Allows an append on an issue a loop has claimed, answering stale-copy. Only with an append.",
+      type: "boolean"
+    },
+    {
+      name: "dry-run",
+      description: "Prints the added part and each gate's reading and writes nothing; a refusal still exits 2.",
+      type: "boolean"
+    }
+  ],
+  examples: [
+    {
+      cmd: 'rafa issue edit 57 --append-file=update.md --reason="scope narrowed"',
+      note: "Appends what update.md holds to #57 below a dated heading naming the reason."
+    },
+    {
+      cmd: 'rafa issue edit 57 --append="Also covers --dry-run." --reason=clarified --dry-run',
+      note: "Prints each gate's reading and the block it would append, and writes nothing."
+    },
+    {
+      cmd: 'rafa issue edit 57 --title="Faster plan show"',
+      note: "Changes the title of #57 and leaves its body alone."
+    },
+    {
+      cmd: "rafa issue edit 57 --priority=high --dry-run",
+      note: "Prints each gate's reading and the swap, such as `priority: needs-triage \u2192 high`, and writes nothing."
+    },
+    {
+      cmd: "rafa issue edit 57 --replace-file=spec.md --output=json",
+      note: "Replaces the body of #57; the report and the tracker are the data of the result event."
+    }
+  ],
+  outputs: ["text", "json"]
+});
+
+// src/commands/issue/issue-tracker.ts
+var DEFAULT_ISSUE_SEAMS = Object.freeze({});
+function lineRefusal(problem, usage) {
+  return new CommandExit(1, `\u274C ${problem}
+Usage: ${usage}`);
+}
+function issueProject(context) {
+  if (context.project === null)
+    throw new Error("rafa issue runs inside a project, and was handed none");
+  return context.project;
+}
+async function issueSubjectConfig(project, warn) {
+  try {
+    return (await loadConfig({ root: project.root, home: project.home }, {}, warn)).config;
+  } catch (error) {
+    if (!(error instanceof ConfigError))
+      throw error;
+    throw new CommandExit(1, ["\u274C The config cannot be used:", ...error.problems.map((problem) => `  ${problem}`)].join(`
+`));
+  }
+}
+
+// src/commands/issue/ready.ts
+var READY_USAGE = "rafa issue ready <n> [--yes | --dry-run]";
+var READY_WRITE_EXIT = 1;
+var ISSUE_NUMBER = /^[1-9]\d*$/u;
+function readyQuestion(issue) {
+  return `Mark #${String(issue)} ${SPEC_READY_LABEL}? [y/N] `;
+}
+function trustPassLine(issue, repo, reading) {
+  if (!reading.trusted) {
+    throw new TypeError(`issue ready: ${reading.login} is not trusted, and has no pass to name`);
+  }
+  const because = reading.source === "allow-list" ? "listed in board.trustedAuthors" : `who has write access to ${repo}`;
+  return `#${String(issue)} was opened by ${reading.login}, ${because}`;
+}
+function completeLine(issue) {
+  return `#${String(issue)} fills every heading the spec template asks for, with no placeholder left`;
+}
+function unaskedMessage(issue) {
+  const number = String(issue);
+  return `#${number} is ready to mark; there is no terminal to ask on, so ${SPEC_READY_LABEL} was not added.` + ` Run rafa issue ready ${number} where an answer can be typed`;
+}
+function requireOneEpic(found) {
+  const listed = {
+    number: found.number,
+    title: found.title,
+    body: found.body,
+    state: found.state,
+    stateReason: null,
+    labels: found.labels,
+    type: typeOfLabels(found.labels),
+    module: moduleOfLabels(found.labels)
+  };
+  const several = readEpicProblems([listed]).find((problem) => problem.kind === "several-epic-labels");
+  if (several === undefined)
+    return;
+  throw new CommandExit(READINESS_REFUSAL_EXIT, `issue #${String(found.number)} cannot be marked ${SPEC_READY_LABEL}: ${epicProblemMessage(several)}`);
+}
+function readyReport(issue, status, reading, lines) {
+  return Object.freeze({
+    issue,
+    status,
+    author: reading.login,
+    trustedBy: reading.source,
+    trust: lines.trust,
+    checked: lines.checked,
+    message: lines.message
+  });
+}
+async function runIssueReady(options) {
+  const { gh, issue, trust, ask } = options;
+  const board = options.board ?? createGhIssueBoard({ gh });
+  const readIssue = options.readIssue ?? createGhSpecIssueReader({ gh });
+  const found = await readIssue(issue);
+  const reading = await requireTrustedBoardAuthor({ kind: "issue", number: issue }, trust, found.author);
+  requireCompleteSpec(issueSource(issue), found.body);
+  if ((options.relationships ?? "labels") === "labels")
+    requireOneEpic(found);
+  const lines = { trust: trustPassLine(issue, trust.repo, reading), checked: completeLine(issue) };
+  if (hasSpecReadyLabel(found.labels)) {
+    return readyReport(issue, "already", reading, {
+      ...lines,
+      message: `#${String(issue)} is already marked ${SPEC_READY_LABEL}`
+    });
+  }
+  if (options.dryRun === true) {
+    return readyReport(issue, "checked", reading, {
+      ...lines,
+      message: `#${String(issue)} is ready to mark; --${READY_DRY_RUN_FLAG} wrote nothing.`
+    });
+  }
+  if (options.yes !== true) {
+    if (ask === null) {
+      return readyReport(issue, "unasked", reading, { ...lines, message: unaskedMessage(issue) });
+    }
+    if (!await ask(readyQuestion(issue))) {
+      return readyReport(issue, "declined", reading, {
+        ...lines,
+        message: `#${String(issue)} was left unmarked`
+      });
+    }
+  }
+  try {
+    await board.swapLabels(issue, SPEC_NEEDS_WORK_LABEL, SPEC_READY_LABEL);
+  } catch (error) {
+    throw new CommandExit(READY_WRITE_EXIT, `\u274C ${SPEC_READY_LABEL} could not be put on #${String(issue)}: ${messageOf(error)}`);
+  }
+  return readyReport(issue, "marked", reading, {
+    ...lines,
+    message: `Marked #${String(issue)} ${SPEC_READY_LABEL}, and took ${SPEC_NEEDS_WORK_LABEL} off it`
+  });
+}
+function readReadyIssue(context) {
+  const { args } = context;
+  if (args.length > 1) {
+    throw lineRefusal(`Expected one issue number, got ${String(args.length)}: ${args.join(" ")}`, READY_USAGE);
+  }
+  const word = args[0];
+  if (word === undefined) {
+    throw lineRefusal("Name the issue number to mark ready", READY_USAGE);
+  }
+  if (!ISSUE_NUMBER.test(word)) {
+    throw lineRefusal(`"${word}" is no issue number, which is a whole number from 1`, READY_USAGE);
+  }
+  return Number(word);
+}
+function readReadySwitch(context, name) {
+  const value = context.flags[name];
+  if (value === undefined)
+    return false;
+  if (typeof value === "boolean")
+    return value;
+  if (value === "true" || value === "false")
+    return value === "true";
+  throw lineRefusal(`--${name} takes no value, and read "${value}" as one`, READY_USAGE);
+}
+function readReadyYes(context) {
+  return readReadySwitch(context, READY_YES_FLAG);
+}
+function readReadyDryRun(context) {
+  return readReadySwitch(context, READY_DRY_RUN_FLAG);
+}
+var DEFAULT_READY_SEAMS = Object.freeze({});
+async function markIssueReady(context, seams) {
+  const issue = readReadyIssue(context);
+  const yes = readReadyYes(context);
+  const dryRun = readReadyDryRun(context);
+  if (yes && dryRun) {
+    throw lineRefusal(`--${READY_YES_FLAG} and --${READY_DRY_RUN_FLAG} cannot be used together: one asks for the write and the other for none`, READY_USAGE);
+  }
+  const project = issueProject(context);
+  const config = await issueSubjectConfig(project, (message) => {
+    context.output.warn(message);
+  });
+  const openGh = seams.openGh ?? ((dir) => createGhRunner({ cwd: dir }));
+  const openGit = seams.openGit ?? createGitRunner;
+  const isTerminal = seams.isTerminal ?? (() => process.stdin.isTTY === true);
+  const openPrompter = seams.openPrompter ?? (() => createLinePrompter(process.stdin, process.stderr));
+  const gh = openGh(project.root);
+  const trust = ghBoardTrust({
+    gh,
+    trustedAuthors: config.boardTrustedAuthors,
+    repo: boardRepoLabel(openGit(project.root))
+  });
+  const prompter = lazyPrompter(openPrompter);
+  try {
+    return await runIssueReady({
+      gh,
+      issue,
+      trust,
+      board: createRefreshingGhIssueBoard({ gh, config, warn: (line) => {
+        context.output.warn(line);
+      } }),
+      relationships: config.boardRelationships,
+      yes,
+      dryRun,
+      ask: isTerminal() ? prompter.ask : null
+    });
+  } finally {
+    prompter.close();
+  }
+}
+function writeReport(context, report) {
+  context.output.info(report.trust);
+  context.output.info(report.checked);
+  context.output.info(report.message);
+}
+function createIssueReadyCommand(seams = DEFAULT_READY_SEAMS) {
+  const command = {
+    ...ISSUE_READY_DECLARATION,
+    run: async (context) => {
+      const made = await markIssueReady(context, seams);
+      if (context.outputMode === "json")
+        context.output.result(made);
+      else
+        writeReport(context, made);
+      if ((made.status === "marked" || made.status === "already") && !readReadyDryRun(context)) {
+        await endWithNextStep(context, seams.ending);
+      }
+    }
+  };
+  return Object.freeze(command);
+}
+var command = createIssueReadyCommand();
+var ready_default = command;
+export {
+  trustPassLine,
+  runIssueReady,
+  requireOneEpic,
+  readyQuestion,
+  readReadyYes,
+  readReadyIssue,
+  readReadyDryRun,
+  markIssueReady,
+  ready_default as default,
+  createIssueReadyCommand,
+  completeLine,
+  READY_WRITE_EXIT,
+  READY_USAGE,
+  DEFAULT_READY_SEAMS
+};