@maycombhq/atticus 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/chunk-QAXW2N3B.js

@@ -0,0 +1,1216 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  onboardingView
+} from "./chunk-7JITZFJC.js";
+import {
+  onboardingQueue,
+  queueWhy,
+  reasonOf
+} from "./chunk-LQJPN536.js";
+import {
+  repoIdKey
+} from "./chunk-4U276ICE.js";
+import {
+  houseUntaughtOf,
+  houseUntaughtWords
+} from "./chunk-EHA7RMZ3.js";
+import {
+  catalogSources
+} from "./chunk-OWNCM4ZN.js";
+import {
+  rulesLackingAll
+} from "./chunk-WXFLMQSR.js";
+import {
+  loadReadPlan,
+  partOfWords,
+  readCostOf,
+  readCostWords,
+  readPlanProgress,
+  readPlanRelOf,
+  tokensWords
+} from "./chunk-TYQBFTBR.js";
+import {
+  checkoutOf,
+  conventionsAt
+} from "./chunk-2F4CYZKJ.js";
+import {
+  isMetarepo,
+  notMetarepo
+} from "./chunk-3G4YI4ZU.js";
+import {
+  readTaskRun
+} from "./chunk-6MUGR4LS.js";
+import {
+  readChangeTasks
+} from "./chunk-UGUP3ZM6.js";
+import {
+  readNeeds,
+  seedCollisions
+} from "./chunk-R7NYHMUU.js";
+import {
+  ASSISTANT_FORMATS,
+  probedAssistant,
+  readProbes,
+  whatRunsWhere
+} from "./chunk-BEVTIBRH.js";
+import {
+  readChangeFiles
+} from "./chunk-S4PMJU6H.js";
+import {
+  assess,
+  changeStore,
+  isManualPrUrl,
+  liveHandoff,
+  loadChangeContext,
+  loadChangePolicy,
+  releasePrReasons,
+  stageCompletion
+} from "./chunk-IDKCWSM5.js";
+import {
+  fileStepStore
+} from "./chunk-7IGKHZ4Z.js";
+import {
+  readCatalog
+} from "./chunk-J2JAKCIW.js";
+import {
+  readKnowledge,
+  snapshotDates,
+  workingDays
+} from "./chunk-745DAZ4L.js";
+import {
+  baseClonePath
+} from "./chunk-PKBHS4AA.js";
+import {
+  stepClassOfNextStep
+} from "./chunk-P32RUW3B.js";
+import {
+  ScanVerifyProposal,
+  catalogDirOf,
+  changesDirOf,
+  changesRelOf,
+  factsDirOf,
+  factsFileOf,
+  factsRelOf,
+  fastPathOf,
+  headFromFiles,
+  isAdopted,
+  listQuestions,
+  loadOrgPack,
+  orderQuestions,
+  orgPackDirOf,
+  proposalsDirOf,
+  questionWeights,
+  readRepoSpec,
+  readSpecFindings,
+  stepModelsOf
+} from "./chunk-Q2TECDIT.js";
+import {
+  require_dist
+} from "./chunk-BQGDB6ZL.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/next-commands.js
+var import_yaml = __toESM(require_dist(), 1);
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+var METAREPO = "metarepo";
+var DRAFTING = ["feature", "architecture", "stories"];
+var draftingAt = (s) => DRAFTING.indexOf(s);
+var STALE_DAYS = 14;
+var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+async function verifyState(root, repo) {
+  const text = await readFile(join(proposalsDirOf(root), "scan", `${repo}.yaml`), "utf8").catch(() => void 0);
+  if (text === void 0)
+    return "none";
+  const p = ScanVerifyProposal.safeParse((0, import_yaml.parse)(text));
+  if (!p.success)
+    return "none";
+  const s = p.data.settings;
+  const entries = s.exclude.length + s.prefixes.length + s.clients.length;
+  if (entries > 0 && (!p.data.accepted || p.data.accepted.at < p.data.at))
+    return "accept";
+  return "done";
+}
+async function staleOf(root, repo) {
+  const text = await readFile(join(factsDirOf(root), `${repo}.verify.yaml`), "utf8").catch(() => void 0);
+  let facts;
+  try {
+    const c = (0, import_yaml.parse)(text ?? "")?.commit;
+    if (typeof c === "string" && /^[0-9a-f]{7,64}$/.test(c))
+      facts = c;
+  } catch {
+    return void 0;
+  }
+  if (!facts)
+    return void 0;
+  let dir;
+  try {
+    dir = isAdopted(root) ? root : baseClonePath(root, repo);
+  } catch {
+    return void 0;
+  }
+  const head = await headFromFiles(dir);
+  if (!head || head.startsWith(facts) || facts.startsWith(head))
+    return void 0;
+  return { facts, head };
+}
+async function readNextState(root) {
+  const view = await onboardingView(root);
+  const problems = [...view.problems];
+  const repos = [];
+  const factIds = (await readdir(factsDirOf(root)).catch(() => [])).map((n) => factsFileOf(n)).flatMap((f) => f?.facts ? [f.repo] : []);
+  const fromFacts = catalogSources((await readCatalog(join(catalogDirOf(root), "generated"), { cacheRoot: root })).records);
+  for (const r of view.repos) {
+    const hasFacts = existsSync(join(factsDirOf(root), `${r.id}.jsonl`));
+    const near = hasFacts ? [] : factIds.filter((x) => x !== r.id && repoIdKey(x) === repoIdKey(r.id)).sort().map((x) => ({ id: x, file: `${factsRelOf(root)}/${x}.jsonl` }));
+    const spec = await readRepoSpec(root, r.id, { cacheRoot: root });
+    problems.push(...spec.problems);
+    const findings = await readSpecFindings(root, r.id);
+    const plan = await readPlanProgress(root, r.id);
+    const planFile = await loadReadPlan(root, r.id);
+    const mapped = !!spec.header?.template.startsWith("facts@") || (fromFacts.get(r.id)?.facts ?? 0) > 0;
+    const stale = mapped && hasFacts ? await staleOf(root, r.id) : void 0;
+    const rules = hasFacts && r.cloned && !await staleOf(root, r.id) ? await rulesLackingAll(root, r.id, planFile?.rules) : [];
+    repos.push({
+      id: r.id,
+      cloned: r.cloned,
+      settings: r.scanSettings.present,
+      scanned: r.lastScan !== null,
+      verify: await verifyState(root, r.id),
+      flows: spec.flows.length,
+      checked: !!findings && findings.draftedAt === spec.header?.drafted?.at,
+      findings: findings?.findings.filter((f) => !f.question).length ?? 0,
+      described: !r.description ? "none" : r.description.trust === "suggested" ? "draft" : "said",
+      ...mapped ? { facts: true } : {},
+      ...stale ? { stale } : {},
+      ...rules.length ? { rules } : {},
+      ...planFile ? { cost: readCostOf(planFile) } : {},
+      ...hasFacts ? { read: true } : {},
+      ...near.length ? { nearFacts: near } : {},
+      ...plan ? {
+        readPlan: {
+          total: plan.total,
+          done: plan.done,
+          ...plan.next ? { next: { part: plan.next.part, paths: plan.next.paths } } : {},
+          file: readPlanRelOf(root, r.id)
+        }
+      } : {}
+    });
+  }
+  const waiting = repos.filter((r) => r.cloned && !r.facts && !r.scanned);
+  if (waiting.length) {
+    const q = await onboardingQueue(root, waiting.map((r) => ({
+      repo: r.id,
+      ...r.read || (r.readPlan?.done ?? 0) > 0 ? { started: true } : {}
+    })));
+    problems.push(...q.problems);
+    q.queue.forEach((x, order) => {
+      const r = repos.find((y) => y.id === x.repo);
+      r.queue = { order, reason: reasonOf(x), why: queueWhy(x) };
+    });
+    const first = waiting.filter((r) => !r.read).sort((a, b) => (a.queue?.order ?? Infinity) - (b.queue?.order ?? Infinity))[0];
+    const dir = first ? await checkoutOf(root, first.id) : void 0;
+    if (first && dir && (await conventionsAt(root)).housePrefixes.length) {
+      const found = await houseUntaughtOf(root, first.id, { dir }).catch(() => []);
+      if (found.length)
+        first.houseUntaught = found;
+    }
+  }
+  const open = await listQuestions(root, { state: "open" });
+  problems.push(...open.problems);
+  const changeIds = new Set(await changeStore(root).list().then((cs) => cs.map((c) => c.id), () => []));
+  const changeQuestions = {};
+  const openIds = new Set(open.questions.map((q) => q.id));
+  for (const q of open.questions)
+    if (changeIds.has(q.repo))
+      (changeQuestions[q.repo] ??= []).push(q.id);
+  const knowledge = await readKnowledge(root, { cacheRoot: root });
+  const sources = [];
+  for (const w of view.sources.wikis) {
+    const newest = (await snapshotDates(root, w.id))[0];
+    sources.push({
+      id: w.id,
+      snapshot: !!newest,
+      scanned: !!newest && !!knowledge.report?.snapshots.some((s) => s.source === w.id && s.date === newest),
+      ...newest ? { age: Math.floor((Date.now() - Date.parse(`${newest}T00:00:00Z`)) / 864e5) } : {}
+    });
+  }
+  const orgPack = await loadOrgPack(orgPackDirOf(root)).catch((e) => e);
+  let orgpack;
+  try {
+    if (orgPack instanceof Error)
+      throw orgPack;
+    const op = orgPack;
+    const names = new Set(op.profiles.flatMap((p) => (p.profile?.systems ?? []).flatMap((x) => [x.name, ...x.aliases])).map((n) => n.toLowerCase()));
+    const missing = knowledge.items.filter((i) => (i.kind === "Product" && i.productKind === "product" || i.kind === "Party" && i.partyKind === "vendor" && !!i.quote) && ![i.name, ...i.aliases].some((n) => names.has(n.toLowerCase()))).length;
+    let draft;
+    for (const f of await readdir(join(proposalsDirOf(root), "orgpack")).catch(() => []))
+      if (f.endsWith(".yaml")) {
+        const d = (0, import_yaml.parse)(await readFile(join(proposalsDirOf(root), "orgpack", f), "utf8"));
+        if (d?.platform && d.proposals?.length)
+          draft = { platform: d.platform, proposals: d.proposals.length };
+      }
+    if (missing || draft)
+      orgpack = { missing, ...draft ? { draft } : {} };
+  } catch (e) {
+    problems.push({ file: "org-pack", message: e.message.split("\n")[0] });
+  }
+  const changes = [];
+  let unverifiedNeeds = 0;
+  let active;
+  const types = orgPack instanceof Error ? [] : orgPack.changeTypes.types;
+  const { policy } = await loadChangePolicy(orgPackDirOf(root));
+  const clashes = await seedCollisions(root).catch(() => []);
+  let ctxP;
+  const changeContext = () => ctxP ??= loadChangeContext(root);
+  try {
+    for (const c of await changeStore(root).list()) {
+      const clash = clashes.filter((x) => x.change === c.id).map(({ seed, repo, capability, flow }) => ({ seed, repo, capability, flow }));
+      const files = await readChangeFiles(join(changesDirOf(root), c.id)).catch(() => void 0);
+      const stagesDone = (await stageCompletion({ root, policy }, c)).filter((s) => s.state === "done").map((s) => s.stage);
+      const needs = await readNeeds(root, c.id);
+      const open2 = needs?.needs.filter((n) => n.status === "open") ?? [];
+      unverifiedNeeds += open2.filter((n) => {
+        const r = knowledge.reviews[n.item];
+        return r?.state !== "verified" && r?.state !== "corrected";
+      }).length;
+      const longest = open2.map((n) => ({
+        n,
+        // The lead time as the knowledge scan read it (ADR 0117); a need with none sorts last.
+        days: n.leadTimeDays ? workingDays(n.leadTimeDays) : 0
+      })).sort((a, b) => b.days - a.days)[0];
+      const own = stageOf(c.state);
+      const loop = draftingAt(own) >= 0 ? await loopState(root, c.id, own) : void 0;
+      const live = c.state === "returned" ? void 0 : liveHandoff(c);
+      const busy = await stageInProgress(root, c.id);
+      const asked = await stageQuestions(root, c.id, openIds);
+      const questions = [.../* @__PURE__ */ new Set([...changeQuestions[c.id] ?? [], ...asked])];
+      const missing = c.state === "define" || c.state === "returned" ? await draftMissing(changeContext, c).catch(() => ({ draft: false, brief: false })) : { draft: false, brief: false };
+      const blocking = stageOf(c.state) === "tasks" ? await blockingOf(changeContext, c).catch(() => 0) : 0;
+      const gate = draftingAt(own) >= 0 && !live && (stagesDone.includes(own) || c.state === "returned") ? await gateFindingsOf(changeContext, c).catch(() => []) : [];
+      if (busy && stageOf(c.state) !== "done" && (!active || busy > active.at))
+        active = { id: c.id, at: busy };
+      changes.push({
+        id: c.id,
+        state: c.state,
+        tasks: files ? await Promise.all(readChangeTasks(files).map(async (t) => {
+          const run = t.done ? void 0 : (await readTaskRun(root, c.id, t.id).catch(() => void 0))?.state;
+          return { id: t.id, repo: t.repo, done: t.done, ...run ? { run } : {} };
+        })) : [],
+        feature: existsSync(join(changesDirOf(root), c.id, "feature.yaml")),
+        ...missing.draft ? { undrafted: true } : {},
+        ...blocking ? { blocking } : {},
+        ...gate.length ? { gate } : {},
+        ...c.state === "released" ? await releasedOf(root, c.id) : {},
+        ...stageOf(c.state) === "release" ? await releasePrsOf(root, c.id) : {},
+        ...missing.brief ? { brief: `${changesRelOf(root)}/${c.id}/brief.md` } : {},
+        ...questions.length ? { questions } : {},
+        ...knowledge.items.length ? { knowledge: true } : {},
+        ...stagesDone.length ? { stagesDone } : {},
+        ...loop ? { loop } : {},
+        ...live ? {
+          handoff: {
+            phase: live.phase,
+            number: live.pr.number,
+            url: live.pr.url,
+            state: live.state,
+            ...isManualPrUrl(live.pr.url) ? await manualPrRecorded(root, c.id, live.branch, orgPack) : {}
+          }
+        } : {},
+        ...clash.length ? { seedCollisions: clash } : {},
+        ...await isFast(root, c, types) ? {
+          fast: true,
+          .../^state: done$/m.test(await readFile(join(changesDirOf(root), c.id, "stage", "small.yaml"), "utf8").catch(() => "")) ? { fastDone: true } : {}
+        } : {},
+        ...needs ? {
+          needs: {
+            open: open2.length,
+            ...longest?.days ? { longest: `${longest.n.title}, ${longest.n.leadTime}` } : {}
+          }
+        } : {}
+      });
+    }
+  } catch (e) {
+    problems.push({ file: "openspec/changes", message: e.message.split("\n")[0] });
+  }
+  return {
+    repos,
+    catalogRecords: view.catalog.records,
+    // ADR 0140 (Q3): in the order to ask them, what a change in flight rests on first.
+    openQuestions: orderQuestions(open.questions, await questionWeights(root, open.questions).catch(() => /* @__PURE__ */ new Map())).map((q) => q.id),
+    ...Object.keys(changeQuestions).length ? { changeQuestions } : {},
+    ...active ? { active: active.id } : {},
+    sources,
+    changes,
+    problems,
+    ...orgpack ? { orgpack } : {},
+    ...unverifiedNeeds ? { unverifiedNeeds } : {}
+  };
+}
+var UNDER_WAY = /* @__PURE__ */ new Set(["drafting", "waiting", "questions", "stopped"]);
+async function stageInProgress(root, change) {
+  const dir = join(changesDirOf(root), change, "stage");
+  let newest;
+  for (const f of (await readdir(dir).catch(() => [])).filter((x) => x.endsWith(".yaml"))) {
+    const loop = await readFile(join(dir, f), "utf8").then((t) => {
+      try {
+        return (0, import_yaml.parse)(t);
+      } catch {
+        return null;
+      }
+    }, () => null);
+    const at = typeof loop?.updatedAt === "string" ? loop.updatedAt : "";
+    if (typeof loop?.state === "string" && UNDER_WAY.has(loop.state) && (!newest || at > newest))
+      newest = at || "0";
+  }
+  return newest;
+}
+async function loopState(root, change, stage) {
+  const t = await readFile(join(changesDirOf(root), change, "stage", `${stage}.yaml`), "utf8").catch(() => void 0);
+  if (t === void 0)
+    return void 0;
+  try {
+    const s = (0, import_yaml.parse)(t)?.state;
+    return typeof s === "string" ? s : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function stageQuestions(root, change, open) {
+  const out = [];
+  for (const s of DRAFTING) {
+    const t = await readFile(join(changesDirOf(root), change, "stage", `${s}.yaml`), "utf8").catch(() => "");
+    let y;
+    try {
+      y = (0, import_yaml.parse)(t);
+    } catch {
+      continue;
+    }
+    if (Array.isArray(y?.questions)) {
+      for (const q of y.questions)
+        if (typeof q === "string" && open.has(q))
+          out.push(q);
+    }
+  }
+  return out;
+}
+async function isFast(root, c, types) {
+  const type = types.find((t) => t.id === c.type);
+  if (!type || type.size !== "small" && !type.smallWhenBriefSays)
+    return false;
+  const brief = await readFile(join(changesDirOf(root), c.id, "brief.md"), "utf8").catch(() => "");
+  return fastPathOf(type, brief).fast;
+}
+async function draftMissing(ctx, c) {
+  const a = await assess(await ctx(), c);
+  return {
+    draft: a.blockers.some((b) => b.code === "missing-artifact" && (b.artifact === "proposal" || b.artifact === "specs")),
+    brief: a.blockers.some((b) => (b.code === "missing-artifact" || b.code === "unfilled-artifact") && b.artifact === "brief")
+  };
+}
+async function blockingOf(ctx, c) {
+  const a = await assess(await ctx(), c);
+  return a.blockers.filter((b) => b.code === "blocking-finding" || b.code === "open-gap").length;
+}
+async function gateFindingsOf(ctx, c) {
+  const a = await assess(await ctx(), c);
+  return a.blockers.flatMap((b) => b.code === "blocking-finding" || b.code === "open-gap" ? [{ code: b.code, ...b.finding ? { finding: b.finding } : {}, message: b.message }] : []);
+}
+function gateBlockedStep(c, stage, gate) {
+  const first = c.gate?.[0];
+  if (!first)
+    return void 0;
+  const id = c.id;
+  const more = c.gate.length - 1;
+  const head = `${id}'s ${stage} stage is done, but the ${gate} gate is blocked, so its hand-off would be refused: ${first.message.replace(/\.?$/, ".")}`;
+  const tail = more ? `; ${more} more after it.` : ".";
+  const asked = /\(owner question (q-[0-9a-f]+)[,)]/.exec(first.message)?.[1];
+  if (asked)
+    return {
+      step: "answer",
+      command: `atticus questions answer ${asked}`,
+      where: METAREPO,
+      why: `${head} Its owner answers ${asked} (Questions, Owner questions), and the answer closes the gap${tail}`,
+      person: true,
+      change: id
+    };
+  const f = first.finding ?? "<id>";
+  if (first.code === "open-gap")
+    return {
+      step: "finding",
+      command: `atticus finding ${id} ${f} ask`,
+      where: METAREPO,
+      why: `${head} Ask its owner (atticus finding ${id} ${f} ask --asked-of <who>), or fill it in (atticus finding ${id} ${f} edit-and-apply)${tail}`,
+      person: true,
+      change: id
+    };
+  return {
+    step: "finding",
+    command: `atticus finding ${id} ${f} edit-and-apply`,
+    where: METAREPO,
+    why: `${head} Fix it (atticus finding ${id} ${f} edit-and-apply), or record why it doesn't apply (not-relevant --reason, or waive)${tail}`,
+    person: true,
+    change: id
+  };
+}
+async function releasedOf(root, id) {
+  try {
+    const { archiveGate } = await import("./chunk-5BD2KYLE.js");
+    const g = await archiveGate(root, id);
+    return {
+      released: { blockers: g.blockers.map((b) => ({ code: b.code, message: b.message })) }
+    };
+  } catch {
+    return { released: { blockers: [] } };
+  }
+}
+function releasedSteps(c) {
+  const id = c.id;
+  const blockers = c.released?.blockers ?? [];
+  const repoOf = (m) => /^([A-Za-z0-9][\w.-]*): /.exec(m)?.[1];
+  const reads = [];
+  for (const b of blockers) {
+    const repo = repoOf(b.message);
+    if (!repo)
+      continue;
+    if (b.code === "needs-reading")
+      reads.push({
+        step: "reread",
+        command: `atticus map ${repo}`,
+        slash: `/atticus-map ${repo}`,
+        where: METAREPO,
+        why: `${id} is released, and the archive gate needs what shipped read: ${b.message}`,
+        repo,
+        change: id
+      });
+    else if (b.code === "catalog-stale")
+      reads.push({
+        step: "verify",
+        command: `atticus verify ${repo} --write`,
+        where: METAREPO,
+        why: `${id} is released, and the archive gate needs the catalog written from what shipped: ${b.message}`,
+        repo,
+        change: id
+      });
+    else if (b.code === "not-synced")
+      reads.push({
+        step: "sync",
+        command: `atticus workspace sync --repos ${repo}`,
+        where: METAREPO,
+        why: `${id} is released, and the archive gate needs ${repo}'s clone at what merged: ${b.message}`,
+        repo,
+        change: id
+      });
+  }
+  const others = blockers.filter((b) => !repoOf(b.message) || !["needs-reading", "catalog-stale", "not-synced"].includes(b.code));
+  if (others.length)
+    return [
+      ...reads,
+      {
+        step: "archive-gate",
+        command: `atticus ci archive-gate ${id}`,
+        where: METAREPO,
+        why: `${id} is released, but the archive gate doesn't pass yet: ${others.map((b) => b.message).join(" ")}`,
+        change: id,
+        person: true
+      }
+    ];
+  return [
+    ...reads,
+    {
+      step: "archive",
+      command: `atticus change archive ${id}`,
+      where: METAREPO,
+      why: reads.length ? `Then a person archives ${id} (its spec deltas merge into openspec/specs/ and the estate is scanned again).` : `${id} is released and the archive gate passes: a person archives it (its spec deltas merge into openspec/specs/ and the estate is scanned again, so the catalog says what shipped).`,
+      change: id,
+      person: true
+    }
+  ];
+}
+async function releasePrsOf(root, id) {
+  const reasons = await releasePrReasons(root, id).catch(() => []);
+  if (reasons.some((r) => r.code === "release-pr-missing" || r.code === "release-pr-stale"))
+    return { releasePrs: "raise" };
+  if (reasons.some((r) => r.code === "release-pr-not-merged"))
+    return { releasePrs: "merge" };
+  return {};
+}
+function stageOf(state) {
+  switch (state) {
+    case "draft":
+    case "define":
+    case "returned":
+      return "feature";
+    case "design":
+      return "architecture";
+    case "plan":
+      return "stories";
+    case "build":
+    case "qa":
+      return "tasks";
+    case "released":
+    case "archived":
+      return "done";
+    default:
+      return "release";
+  }
+}
+function changeSteps(c) {
+  if (c.state === "released")
+    return releasedSteps(c);
+  const stage = stageSteps(c);
+  const id = c.id;
+  const done = stageOf(c.state) === "done";
+  const find = c.feature && c.knowledge && !c.needs && !done ? [
+    {
+      step: "needs",
+      command: `atticus change needs ${id}`,
+      slash: `/atticus-needs ${id}`,
+      where: METAREPO,
+      why: `${id} is placed on the estate: your assistant says what it needs from the organisation (requests and processes to raise, standards to follow, teams to involve), and Atticus checks each against the change's own words (ADR 0101).`,
+      change: id
+    }
+  ] : [];
+  const raise = c.needs?.open && !done ? [
+    {
+      step: "raise-needs",
+      command: `atticus needs --change ${id}`,
+      where: METAREPO,
+      why: `${plural(c.needs.open, "need")} of ${id} ${c.needs.open === 1 ? "is" : "are"} open${c.needs.longest ? ` (the longest: ${c.needs.longest})` : ""}. Raise each, then record it with atticus needs done ${id} <item>.`,
+      change: id,
+      person: true
+    }
+  ] : [];
+  const seeds = done ? [] : [...new Set((c.seedCollisions ?? []).map((x) => x.repo))].sort().map((repo) => {
+    const xs = c.seedCollisions.filter((x) => x.repo === repo);
+    return {
+      step: "accept-seed",
+      command: `atticus spec accept ${repo}`,
+      where: METAREPO,
+      why: `${id} adds ${xs.map((x) => x.flow).join(", ")} as new, and ${repo}'s starting spec (${xs[0].seed}), not accepted yet, adds ${xs.length === 1 ? "it" : "them"} too: archiving both would fail on a requirement added twice. A person reads and accepts the seed. Then run the change's stories stage again (atticus plan stories ${id}) so it modifies the seeded requirement (ADR 0156).`,
+      person: true,
+      change: id,
+      repo
+    };
+  });
+  const gate = done ? [] : handoffWait(c);
+  if (gate.length)
+    return [...gate, ...find, ...raise];
+  const asked = done ? [] : questionStep(c);
+  const ownDone = (c.stagesDone ?? []).includes(stageOf(c.state));
+  return ownDone ? [...seeds, ...stage, ...asked, ...find, ...raise] : [...asked, ...seeds, ...stage, ...find, ...raise];
+}
+async function manualPrRecorded(root, change, branch, orgPack) {
+  const steps = await fileStepStore(root).list({ change, system: "git-host" }).catch(() => []);
+  const open = steps.find((x) => x.action === "open-pull-request" && x.inputs.head === branch && x.state !== "open");
+  if (!open)
+    return {};
+  const named = orgPack instanceof Error ? void 0 : orgPack.runtime.adapters.gitHost?.settings.metarepo;
+  const repo = typeof open.inputs.repo === "string" ? open.inputs.repo : void 0;
+  return { recorded: typeof named === "string" || !repo ? {} : { repo } };
+}
+function handoffWait(c) {
+  const h = c.handoff;
+  if (!h)
+    return [];
+  const id = c.id;
+  if (h.state === "changes-requested")
+    return [
+      {
+        step: "handoff",
+        command: `atticus change handoff ${id} --approve`,
+        where: METAREPO,
+        why: `Changes were requested on PR #${h.number} (${id}'s ${h.phase} hand-off): update the work, then a person hands it off again.`,
+        change: id,
+        person: true,
+        ...isManualPrUrl(h.url) ? {} : { pr: h.url }
+      }
+    ];
+  if (isManualPrUrl(h.url) && h.recorded)
+    return [
+      {
+        step: "merge",
+        command: `atticus change sync ${id}${h.recorded.repo ? ` --repo ${h.recorded.repo}` : ""}`,
+        where: METAREPO,
+        why: `${id}'s ${h.phase} hand-off PR is recorded on its manual steps: syncing reads what was recorded and moves the change on; once its merge is recorded, that approves the ${h.phase} gate.`,
+        change: id,
+        person: true
+      }
+    ];
+  if (isManualPrUrl(h.url))
+    return [
+      {
+        step: "merge",
+        command: `atticus todo --change ${id}`,
+        where: METAREPO,
+        why: `${id}'s ${h.phase} hand-off PR isn't open yet: your Git host is manual, so opening it is a step waiting on you (atticus todo, or Home \u203A Manual steps in the app). Open it on the Git host as its step says, record its link, then sync; merging it approves the ${h.phase} gate.`,
+        change: id,
+        person: true,
+        pr: h.url
+      }
+    ];
+  return [
+    {
+      step: "merge",
+      command: `atticus change sync ${id}`,
+      where: METAREPO,
+      why: `${id}'s ${h.phase} hand-off PR #${h.number} is raised (${h.url}): a person approves and merges it on the Git host, then syncing moves the change on (ADR 0073).`,
+      change: id,
+      person: true,
+      pr: h.url
+    }
+  ];
+}
+function questionStep(c) {
+  const ids = c.questions ?? [];
+  if (!ids.length)
+    return [];
+  const stage = stageOf(c.state);
+  const again = draftingAt(stage) >= 0 ? `Answer ${plural(ids.length, "question")} on Questions (or atticus questions answer <id>), then run the ${c.fast ? "fast path's one step" : `${stage} stage`} again.` : `Its stage goes on once ${ids.length === 1 ? "it is" : "they are"} answered.`;
+  return [
+    {
+      step: "answer",
+      command: "atticus questions list --state open",
+      slash: "/atticus-answer",
+      where: METAREPO,
+      why: `${plural(ids.length, "question")} of ${c.id} ${ids.length === 1 ? "is" : "are"} waiting for a person: ${ids.join(", ")}. ${again}`,
+      person: true,
+      change: c.id
+    }
+  ];
+}
+function againWhy(c, stage) {
+  return c.loop === "questions" && !c.questions?.length ? `The questions the ${stage} stage of ${c.id} asked are answered: run the stage again so it reads the answers (ADR 0087).` : void 0;
+}
+function stageSteps(c) {
+  const id = c.id;
+  const stage = stageOf(c.state);
+  if (c.brief && stage === "feature" && !c.stagesDone?.includes("feature"))
+    return [
+      {
+        step: "brief",
+        command: c.brief,
+        where: METAREPO,
+        why: `Write the brief of ${id} (${c.brief}): it still holds only the template. The feature stage places the change on the estate from it.`,
+        change: id,
+        person: true
+      }
+    ];
+  if (c.fast && (stage === "feature" || stage === "architecture" || stage === "stories"))
+    return c.fastDone ? [
+      {
+        step: "small-handoff",
+        command: `atticus change handoff ${id} --approve`,
+        where: METAREPO,
+        why: `${id}'s one step is done and nothing blocks it: a person opens its pull request, and merging it approves the plan (ADR 0113).`,
+        change: id,
+        person: true
+      }
+    ] : [
+      {
+        step: "small",
+        command: `atticus change small ${id}`,
+        slash: `/atticus-small ${id}`,
+        where: METAREPO,
+        why: `${id} is a small change: your assistant places it, writes its target flows and words its stories in one step, and Atticus runs every stage's checks and the critic at its gate (ADR 0113). Then a person approves its one pull request.`,
+        change: id
+      }
+    ];
+  if ((stage === "feature" || stage === "architecture" || stage === "stories") && c.stagesDone?.includes(stage)) {
+    const later = c.stagesDone.slice(c.stagesDone.indexOf(stage) + 1);
+    const gate = c.state === "returned" ? "define" : c.state;
+    if (stage === "feature" && c.undrafted)
+      return [
+        {
+          step: "draft",
+          command: `atticus change draft ${id}`,
+          slash: `/atticus-draft ${id}`,
+          where: METAREPO,
+          why: `${id} is placed on the estate, but its proposal or specs aren't written yet: your assistant drafts them, and Atticus checks the draft. Then a person raises the define hand-off.`,
+          change: id
+        }
+      ];
+    const blocked = gateBlockedStep(c, stage, gate);
+    if (blocked)
+      return [blocked];
+    return [
+      {
+        step: "handoff",
+        command: `atticus change handoff ${id} --approve`,
+        where: METAREPO,
+        why: `${id}'s ${stage} stage is done${later.length ? ` (and ${later.join(" and ")} ran ahead)` : ""}, but the change is still in ${c.state}: a person raises its ${gate} hand-off PR, and merging it approves the ${gate} gate and moves it on (ADR 0073).`,
+        change: id,
+        person: true
+      }
+    ];
+  }
+  switch (stage) {
+    case "feature":
+      return [
+        {
+          step: "feature",
+          command: `atticus change feature ${id}`,
+          slash: `/atticus-feature ${id}`,
+          where: METAREPO,
+          why: againWhy(c, "feature") ?? `${id} is at the feature stage: your assistant places it on the estate's flows and features, and Atticus checks and criticises every draft until nothing blocks (ADR 0087).`,
+          change: id
+        }
+      ];
+    case "architecture":
+      return [
+        // Fifth UX walk: the architecture stage reads the placed feature; without one it refuses.
+        ...c.feature === false ? [
+          {
+            step: "feature",
+            command: `atticus change feature ${id}`,
+            slash: `/atticus-feature ${id}`,
+            where: METAREPO,
+            why: `${id} isn't placed on the estate yet: your assistant places it on the flows and features first, then writes its target flows.`,
+            change: id
+          }
+        ] : [],
+        {
+          step: "architecture",
+          command: `atticus change architecture ${id}`,
+          slash: `/atticus-architecture ${id}`,
+          where: METAREPO,
+          why: againWhy(c, "architecture") ?? `${id} is at the architecture stage: your assistant writes its target flows, and Atticus checks and criticises every draft until nothing blocks (ADR 0087).`,
+          change: id
+        }
+      ];
+    case "stories":
+      return [
+        {
+          step: "stories",
+          command: `atticus plan stories ${id}`,
+          slash: `/atticus-stories ${id}`,
+          where: METAREPO,
+          why: againWhy(c, "stories") ?? `${id} has an approved design: write its stories and tasks.`,
+          change: id
+        }
+      ];
+    case "tasks": {
+      const underWay = (x) => x.run === "built" || x.run === "unverified" || x.run === "pr-open" || x.run === "waiting";
+      const open = c.tasks.filter((x) => !x.done);
+      const t = open.find((x) => !underWay(x));
+      const drafted = open.filter(underWay).map((x) => x.id);
+      const draftedNote = drafted.length ? ` ${drafted.length === 1 ? "Task" : "Tasks"} ${drafted.join(", ")} ${drafted.length === 1 ? "is" : "are"} under way: raise or merge ${drafted.length === 1 ? "its" : "their"} PR on the Task board.` : "";
+      if (!t && drafted.length)
+        return [
+          {
+            step: "tasks",
+            command: `atticus change status ${id}`,
+            where: METAREPO,
+            why: `Every task of ${id} not ticked is under way.${draftedNote}`,
+            change: id
+          }
+        ];
+      const handoffStep = {
+        step: "handoff",
+        command: `atticus change handoff ${id} --approve`,
+        where: METAREPO,
+        why: `Every task of ${id} is ticked: a person raises its ${c.state} hand-off PR, and merging it approves the ${c.state} gate and moves it on (ADR 0073).`,
+        change: id,
+        person: true
+      };
+      if (!t && c.blocking)
+        return [
+          {
+            step: "findings",
+            command: `atticus change status ${id}`,
+            where: METAREPO,
+            why: `Every task of ${id} is ticked, but ${plural(c.blocking, "blocking finding")} hold${c.blocking === 1 ? "s" : ""} its ${c.state} hand-off: a person resolves each (Apply fix, Not relevant or Waive, on the change's page), then raises the hand-off PR.`,
+            change: id,
+            person: true
+          },
+          handoffStep
+        ];
+      if (!t)
+        return [handoffStep];
+      return [
+        {
+          step: "task",
+          command: `atticus task run ${id} ${t.id}`,
+          slash: `/atticus-task ${id} ${t.id}`,
+          where: METAREPO,
+          why: `Task ${t.id} of ${id} in ${t.repo} is the first one not done. /atticus-task gives your assistant its context (atticus task context ${id} ${t.id}): the story, the criteria, the step with today's code and the files to change (ADR 0113).${draftedNote}`,
+          repo: t.repo,
+          change: id
+        }
+      ];
+    }
+    case "release":
+      if (c.releasePrs === "raise")
+        return [
+          {
+            step: "release-prs",
+            command: `atticus change release-prs ${id} --approve`,
+            where: METAREPO,
+            why: `${id}'s code reaches each repo's default branch through its release PRs: raise them (Release \u203A Raise the release PRs), then a person merges each on the Git host.`,
+            person: true,
+            change: id
+          }
+        ];
+      if (c.releasePrs === "merge")
+        return [
+          {
+            step: "release-prs-merge",
+            command: `atticus change sync ${id}`,
+            where: METAREPO,
+            why: `${id}'s release PRs wait on a person on the Git host: merge each, then Sync records it (Release).`,
+            person: true,
+            change: id
+          }
+        ];
+      return [
+        {
+          step: "release",
+          command: `atticus change status ${id}`,
+          slash: `/atticus-release ${id}`,
+          where: METAREPO,
+          why: `${id} is on its way to release: check what still blocks it.`,
+          change: id
+        }
+      ];
+    default:
+      return [];
+  }
+}
+function changeAnswer(c, filed) {
+  const id = c.id;
+  const ids = filed.filter((q) => !c.questions?.includes(q));
+  if (!ids.length)
+    return [];
+  return [
+    {
+      step: "answer",
+      command: "atticus questions list --state open",
+      slash: "/atticus-answer",
+      where: METAREPO,
+      why: `${plural(ids.length, "question")} of ${id} ${ids.length === 1 ? "is" : "are"} waiting for a person: ${ids.join(", ")}. Its stage goes on once ${ids.length === 1 ? "it is" : "they are"} answered.`,
+      person: true,
+      change: id
+    }
+  ];
+}
+function nearFactsWords(r) {
+  return (r.nearFacts ?? []).map((n) => ` No facts are filed under ${r.id}, but ${n.id} has some (${n.file}) and its id is near this one: if they are one repo, keep one id with atticus repo rename ${r.id} ${n.id} (or rename the facts to ${r.id}).`).join("");
+}
+function costWords(r) {
+  const e = r.cost?.estimated;
+  if (!e)
+    return "";
+  return ` Estimated about ${tokensWords(e.tokens)} tokens in ${e.sessions} session${e.sessions === 1 ? "" : "s"} (atticus map ${r.id} --estimate; an estimate, not a meter).`;
+}
+function nextSteps(s) {
+  const out = [];
+  const byChange = s.changeQuestions ?? {};
+  const inHand = s.active ? s.changes.find((c) => c.id === s.active) : void 0;
+  if (inHand && stageOf(inHand.state) !== "done")
+    out.push(...changeAnswer(inHand, byChange[inHand.id] ?? []), ...changeSteps(inHand));
+  const ofChanges = /* @__PURE__ */ new Set([
+    ...Object.values(byChange).flat(),
+    ...s.changes.filter((c) => stageOf(c.state) !== "done").flatMap((c) => c.questions ?? [])
+  ]);
+  const repoQuestions = s.openQuestions.filter((id) => !ofChanges.has(id));
+  if (s.repos.length === 0 && !inHand) {
+    out.push({
+      step: "discover",
+      command: "atticus repos discover <folder>",
+      why: "No repo is listed yet. Propose the manifest from a folder of clones or your Git host's organisation (--org)."
+    });
+    return out;
+  }
+  const notCloned = s.repos.filter((r) => !r.cloned);
+  if (notCloned.length)
+    out.push({
+      step: "sync",
+      command: "atticus workspace sync",
+      why: `${plural(notCloned.length, "repo")} ${notCloned.length === 1 ? "isn't" : "aren't"} cloned yet: ${notCloned.map((r) => r.id).join(", ")}.`
+    });
+  const unread = s.repos.filter((r) => r.cloned && !r.facts && !r.scanned).sort((a, b) => (a.queue?.order ?? Infinity) - (b.queue?.order ?? Infinity));
+  for (const r of unread)
+    out.push(r.read ? {
+      step: "write",
+      command: `atticus verify ${r.id} --write`,
+      why: `${r.id} is read: atticus verify ${r.id} --write checks its facts against the code, then puts them in the catalog and renders its map.`,
+      repo: r.id
+    } : {
+      step: "map",
+      command: `atticus map ${r.id}`,
+      slash: `/atticus-map ${r.id}`,
+      where: METAREPO,
+      // A-ledger: a repo read in parts says which part comes next, so nobody keeps the list.
+      why: (r.readPlan?.next ? `${r.id} is read in ${r.readPlan.total} parts (${r.readPlan.file}): ${partOfWords({ part: r.readPlan.next.part, total: r.readPlan.total })} is next, ${r.readPlan.done === 0 ? "none" : r.readPlan.done} ${r.readPlan.done === 1 ? "is" : "are"} read (${r.readPlan.next.paths.join(", ")}). Your assistant reads the part and writes its facts, each citing its line.` : `${r.id} isn't read yet: your assistant reads it and writes its facts, each citing its line, and atticus verify ${r.id} checks them.`) + // Only a reason that moved it up the queue is worth a sentence here; --queue says all.
+      (r.queue && (r.queue.reason === "called" || r.queue.reason === "gateway" || r.queue.reason === "places") ? ` ${r.queue.why}` : "") + costWords(r) + houseUntaughtWords(r.id, r.houseUntaught ?? []) + nearFactsWords(r),
+      repo: r.id
+    });
+  for (const r of s.repos.filter((x) => x.cloned && x.facts && x.stale))
+    out.push({
+      step: "reread",
+      command: `atticus map ${r.id}`,
+      slash: `/atticus-map ${r.id}`,
+      where: METAREPO,
+      why: `${r.id}'s clone moved past its facts' commit (facts ${r.stale.facts.slice(0, 12)}, clone ${r.stale.head.slice(0, 12)}): atticus estate fresh says how many facts to read again; your assistant reads only the files that changed.`,
+      repo: r.id
+    });
+  for (const r of s.repos.filter((x) => x.cloned && x.read && x.rules?.length))
+    out.push({
+      step: "rules",
+      command: `atticus map ${r.id} --rules`,
+      slash: `/atticus-map ${r.id} --rules`,
+      where: METAREPO,
+      why: `${r.id} was read before reading rules added since (${r.rules.join(", ")}): your assistant reads only the files they apply to, for what they ask, and atticus verify ${r.id} records the rules. atticus map --all --stale tops up every such repo.`,
+      repo: r.id
+    });
+  const cloned = s.repos.filter((r) => r.cloned && !r.facts && r.scanned);
+  for (const r of cloned.filter((x) => !x.settings))
+    out.push({
+      step: "survey",
+      command: `atticus scan survey ${r.id}`,
+      slash: `/atticus-survey ${r.id}`,
+      where: METAREPO,
+      why: `${r.id} has no scan settings yet: your assistant reads it and drafts them, and Atticus checks each entry against the code.`,
+      repo: r.id
+    });
+  if (cloned.length && s.catalogRecords === 0)
+    out.push({
+      step: "scan",
+      command: "atticus scan",
+      why: "The catalog is empty: scan the repos into it."
+    });
+  const scanned = cloned;
+  for (const r of scanned)
+    if (r.verify === "none")
+      out.push({
+        step: "verify",
+        command: `atticus scan verify ${r.id}`,
+        slash: `/atticus-verify ${r.id}`,
+        where: METAREPO,
+        why: `The last scan of ${r.id} hasn't been verified: your assistant compares the code with what the scan recorded.`,
+        repo: r.id
+      });
+    else if (r.verify === "accept")
+      out.push({
+        step: "accept",
+        command: `atticus scan verify ${r.id} --accept`,
+        why: `The verify of ${r.id} proposes scan settings entries. A person reads the proposal and accepts it.`,
+        person: true,
+        repo: r.id
+      });
+  const undescribed = s.repos.filter((r) => r.described === "none");
+  if (undescribed.length)
+    out.push({
+      step: "describe",
+      command: `atticus repo describe ${undescribed[0].id} --description "what it is"`,
+      why: `${plural(undescribed.length, "repo")} ${undescribed.length === 1 ? "doesn't say" : "don't say"} what ${undescribed.length === 1 ? "it is" : "they are"}: ${undescribed.map((r) => r.id).join(", ")}. One line each is carried into every reading prompt, the join's questions and the views, so an opaque id can be read and placed.`,
+      person: true,
+      ...undescribed.length === 1 ? { repo: undescribed[0].id } : {}
+    });
+  const drafted = s.repos.filter((r) => r.described === "draft");
+  if (drafted.length)
+    out.push({
+      step: "describe-accept",
+      command: `atticus repo describe ${drafted[0].id} --accept`,
+      why: `Your assistant drafted what ${drafted.length === 1 ? "this repo is" : "these repos are"} and nobody has confirmed ${drafted.length === 1 ? "it" : "them"}: ${drafted.map((r) => r.id).join(", ")}. Until a person does, each is shown as unconfirmed everywhere it is used.`,
+      person: true,
+      ...drafted.length === 1 ? { repo: drafted[0].id } : {}
+    });
+  if (repoQuestions.length)
+    out.push({
+      step: "answer",
+      command: "atticus questions list --state open",
+      slash: "/atticus-answer",
+      where: METAREPO,
+      why: `${plural(repoQuestions.length, "question")} ${repoQuestions.length === 1 ? "is" : "are"} waiting for a person: ${repoQuestions.join(", ")}. The steps that asked go on once they are answered.`,
+      person: true
+    });
+  for (const r of scanned) {
+    const slash = { slash: `/atticus-spec ${r.id}`, where: METAREPO, repo: r.id };
+    if (r.flows === 0)
+      out.push({
+        step: "spec",
+        command: `atticus spec draft ${r.id}`,
+        ...slash,
+        why: `${r.id} has no spec yet: your assistant writes its flows, one per trigger, each step cited.`
+      });
+    else if (!r.checked)
+      out.push({
+        step: "spec-check",
+        command: `atticus spec check ${r.id}`,
+        ...slash,
+        why: `The spec of ${r.id} hasn't been checked since its last draft.`
+      });
+    else if (r.findings > 0)
+      out.push({
+        step: "spec",
+        command: `atticus spec draft ${r.id}`,
+        ...slash,
+        why: `The last spec check of ${r.id} found ${plural(r.findings, "problem")}: draft the flagged flows again, then check.`
+      });
+  }
+  for (const k of s.sources)
+    if (!k.snapshot)
+      out.push({
+        step: "sync-source",
+        command: `atticus sources sync --source ${k.id}`,
+        slash: `/atticus-knowledge ${k.id}`,
+        where: METAREPO,
+        why: `The knowledge source ${k.id} has no snapshot yet: copy its pages, then read them into knowledge items.`,
+        source: k.id
+      });
+    else if (!k.scanned)
+      out.push({
+        step: "knowledge",
+        command: `atticus knowledge scan --source ${k.id}`,
+        slash: `/atticus-knowledge ${k.id}`,
+        where: METAREPO,
+        why: `The newest snapshot of ${k.id} hasn't been read into knowledge items yet.`,
+        source: k.id
+      });
+    else if ((k.age ?? 0) > STALE_DAYS)
+      out.push({
+        step: "sync-source",
+        command: `atticus sources sync --source ${k.id}`,
+        slash: `/atticus-knowledge ${k.id}`,
+        where: METAREPO,
+        why: `The newest snapshot of ${k.id} is ${k.age} days old: sync it again, and a rescan reads only the pages that changed (ADR 0101).`,
+        source: k.id
+      });
+  if (s.orgpack?.draft)
+    out.push({
+      step: "accept-orgpack",
+      command: `atticus orgpack accept ${s.orgpack.draft.platform}`,
+      why: `A draft of the ${s.orgpack.draft.platform} profile has ${plural(s.orgpack.draft.proposals, "system")} from the wikis waiting: read it (proposals/orgpack/${s.orgpack.draft.platform}.md) and accept what is right, with --only or --verified-only.`,
+      person: true
+    });
+  else if (s.orgpack?.missing)
+    out.push({
+      step: "orgpack-draft",
+      command: "atticus orgpack draft",
+      why: `The wikis name ${plural(s.orgpack.missing, "product or vendor", "products and vendors")} that no profile has yet: draft them into the org pack, with their aliases and owners.`
+    });
+  if (s.unverifiedNeeds)
+    out.push({
+      step: "verify-knowledge",
+      command: "atticus knowledge list --unverified",
+      why: `${plural(s.unverifiedNeeds, "open need")} of changes ${s.unverifiedNeeds === 1 ? "comes" : "come"} from knowledge items no person has verified: check each against its page (atticus knowledge verify, correct or reject).`,
+      person: true
+    });
+  const inFlight = s.changes.filter((c) => stageOf(c.state) !== "done" || c.state === "released");
+  for (const c of inFlight)
+    if (c !== inHand)
+      out.push(...changeAnswer(c, byChange[c.id] ?? []), ...changeSteps(c));
+  if (!inFlight.length)
+    out.push({
+      step: "new-change",
+      command: 'atticus change new "<title>" --type <type>',
+      why: out.length ? "Then start a change: no change is in flight." : "Everything is onboarded, checked and answered, and no change is in flight. Start one."
+    });
+  return out;
+}
+async function nextCommand(root, o, io) {
+  if (!isMetarepo(root)) {
+    io.err(notMetarepo(root));
+    return 2;
+  }
+  const state = await readNextState(root);
+  if (o.queue)
+    return queueOut(state, o, io);
+  const steps = nextSteps(state);
+  const runtime = await loadOrgPack(orgPackDirOf(root)).then((op) => op.runtime).catch(() => void 0);
+  const probes = (await readProbes(root)).results;
+  const probed = runtime ? probedAssistant(runtime, probes) : [...probes].sort((a, b) => b.measured.localeCompare(a.measured))[0]?.assistant;
+  const assistant = probed ?? runtime?.assistants.default ?? "copilot";
+  if (o.json) {
+    const runs = runtime ? whatRunsWhere(runtime, { probes }) : void 0;
+    const modelMode = !!runtime && runtime.ai !== "off" && runtime.modes.allowed.includes("model") && !!runtime.adapters.model && runtime.adapters.model.type !== "mock";
+    const classed = steps.map((x) => {
+      const c = x.person ? void 0 : stepClassOfNextStep(x.step);
+      return c ? { ...x, stepClass: c } : x;
+    });
+    const orgModels = stepModelsOf(runtime);
+    io.out(JSON.stringify({
+      next: classed[0],
+      steps: classed,
+      problems: state.problems,
+      ...runs ? { runs } : {},
+      modelMode,
+      assistant,
+      ...Object.keys(orgModels).length ? { orgModels } : {}
+    }, null, 2));
+    return 0;
+  }
+  for (const p of state.problems)
+    io.err(`Couldn't read ${p.file}: ${p.message}`);
+  const typeIn = ASSISTANT_FORMATS[assistant].typeIn;
+  const slashLine = (x) => x.slash ? `In ${typeIn}${x.where && x.where !== METAREPO ? ` in ${x.where}` : ""}: ${x.slash}` : void 0;
+  if (!o.all) {
+    const n = steps[0];
+    io.out(`Next: ${n.command}`);
+    const sl = slashLine(n);
+    if (sl)
+      io.out(sl);
+    io.out(`Why: ${n.why}`);
+    if (steps.length > 1)
+      io.out(`${plural(steps.length - 1, "more step")} after this one: atticus next --all`);
+    return 0;
+  }
+  steps.forEach((x, i) => {
+    io.out(`${i + 1}. ${x.command}`);
+    const sl = slashLine(x);
+    if (sl)
+      io.out(`   ${sl}`);
+    io.out(`   ${x.why}`);
+  });
+  return 0;
+}
+function queueOut(s, o, io) {
+  const waiting = s.repos.filter((r) => r.queue).sort((a, b) => a.queue.order - b.queue.order);
+  const read = s.repos.filter((r) => r.facts);
+  if (o.json) {
+    io.out(JSON.stringify({
+      queue: waiting.map((r) => ({
+        repo: r.id,
+        order: r.queue.order + 1,
+        reason: r.queue.reason,
+        why: r.queue.why,
+        command: `atticus map ${r.id}`,
+        slash: `/atticus-map ${r.id}`,
+        ...r.cost ? { cost: r.cost } : {}
+      })),
+      read: read.map((r) => ({
+        repo: r.id,
+        ...r.cost ? { cost: r.cost } : {},
+        ...r.stale ? { stale: r.stale } : {}
+      })),
+      problems: s.problems
+    }, null, 2));
+    return 0;
+  }
+  for (const p of s.problems)
+    io.err(`Couldn't read ${p.file}: ${p.message}`);
+  io.out(waiting.length ? `${plural(waiting.length, "repo")} to read, in the order that lands links early (callees and gateways first):` : "No repo is waiting to be read.");
+  waiting.forEach((r, i) => io.out(`  ${i + 1}. ${r.id}: ${r.queue.why} ${r.cost?.estimated ? `Cost: ${readCostWords(r.cost)}.` : `Cost: not estimated yet (atticus map ${r.id} --estimate).`}`));
+  if (read.length) {
+    io.out(`${plural(read.length, "repo")} read:`);
+    for (const r of read)
+      io.out(`  ${r.id}: ${r.cost ? readCostWords(r.cost) || "no cost on file" : "no cost on file (read before Atticus recorded one)"}${r.stale ? `; its clone moved past its facts' commit: atticus estate fresh` : ""}`);
+  }
+  io.out("Tokens estimated are counted from the source; reported ones are your assistant's word (atticus map <repo> --spent); Atticus meters neither.");
+  return 0;
+}
+
+export {
+  readNextState,
+  changeSteps,
+  nextSteps,
+  nextCommand
+};