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

package/dist/{chunk-RUVFXE2L.js → chunk-4WXRPQDE.js}

@@ -4,61 +4,108 @@ var require = __atticusCreateRequire(import.meta.url);
 var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
 var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
 import {
+  onboardingQueue,
+  queueWhy,
+  reasonOf
+} from "./chunk-HE3HRDNZ.js";
+import {
+  onboardingView
+} from "./chunk-PNQLCRSS.js";
+import {
+  houseUntaughtOf,
+  houseUntaughtWords
+} from "./chunk-3J5I7ZOU.js";
+import {
+  repoIdKey
+} from "./chunk-OMPENNWY.js";
+import {
+  catalogSources
+} from "./chunk-4FOAYLI4.js";
+import {
+  readTaskRun
+} from "./chunk-Y6K3CJBU.js";
+import {
+  rulesLackingAll
+} from "./chunk-GIFMBCTW.js";
+import {
+  loadReadPlan,
   partOfWords,
+  readCostOf,
+  readCostWords,
   readPlanProgress,
-  readPlanRelOf
-} from "./chunk-FQXYPF7E.js";
+  readPlanRelOf,
+  tokensWords
+} from "./chunk-MD7KUEJ3.js";
 import {
-  onboardingView
-} from "./chunk-EBEW3XXQ.js";
+  checkoutOf,
+  conventionsAt
+} from "./chunk-Q46QDDMF.js";
+import {
+  readChangeTasks
+} from "./chunk-YWAKDNMH.js";
 import {
   isMetarepo,
   notMetarepo
 } from "./chunk-3G4YI4ZU.js";
-import {
-  readChangeTasks
-} from "./chunk-OT2O76OS.js";
 import {
   ASSISTANT_FORMATS,
   probedAssistant,
   readProbes,
   whatRunsWhere
-} from "./chunk-IPKHE5D6.js";
+} from "./chunk-3AQ2R5NL.js";
 import {
-  metarepoOpenSpec,
-  openspecProgress,
-  readNeeds
-} from "./chunk-CKSITVS4.js";
+  readNeeds,
+  seedCollisions
+} from "./chunk-BEPCKDCP.js";
 import {
   readChangeFiles
-} from "./chunk-3HI6Z55Y.js";
+} from "./chunk-K332XW7K.js";
 import {
+  assess,
   changeStore,
+  isManualPrUrl,
+  liveHandoff,
+  loadChangeContext,
   loadChangePolicy,
+  releasePrReasons,
   stageCompletion
-} from "./chunk-XY3P7JW7.js";
+} from "./chunk-HSZMPH5T.js";
+import {
+  readCatalog
+} from "./chunk-4SLBCEPD.js";
 import {
   readKnowledge,
   snapshotDates,
   workingDays
-} from "./chunk-L24C55VN.js";
+} from "./chunk-64AADMTW.js";
+import {
+  baseClonePath
+} from "./chunk-XOL3GFW2.js";
 import {
   stepClassOfNextStep
-} from "./chunk-CNUKCS2T.js";
+} from "./chunk-QHJJMZLX.js";
 import {
   ScanVerifyProposal,
+  catalogDirOf,
   changesDirOf,
+  changesRelOf,
   factsDirOf,
+  factsFileOf,
+  factsRelOf,
   fastPathOf,
+  headFromFiles,
+  isAdopted,
   listQuestions,
   loadOrgPack,
+  orderQuestions,
   orgPackDirOf,
   proposalsDirOf,
+  questionWeights,
   readRepoSpec,
   readSpecFindings,
   require_dist,
   stepModelsOf
-} from "./chunk-S2A7YC3Q.js";
+} from "./chunk-PAINMSID.js";
 import {
   __toESM
 } from "./chunk-TV45EUGM.js";
@@ -71,10 +118,6 @@ import { join } from "node:path";
 var METAREPO = "metarepo";
 var DRAFTING = ["feature", "architecture", "stories"];
 var draftingAt = (s) => DRAFTING.indexOf(s);
-var canMoveOn = (state) => {
-  const at = draftingAt(stageOf(state));
-  return at >= 0 && at < DRAFTING.length - 1;
-};
 var STALE_DAYS = 14;
 var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 async function verifyState(root, repo) {
@@ -90,15 +133,46 @@ async function verifyState(root, repo) {
     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,
@@ -109,8 +183,12 @@ async function readNextState(root) {
       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",
-      ...spec.header?.template.startsWith("facts@") ? { facts: true } : {},
-      ...existsSync(join(factsDirOf(root), `${r.id}.jsonl`)) ? { read: true } : {},
+      ...mapped ? { facts: true } : {},
+      ...stale ? { stale } : {},
+      ...rules.length ? { rules } : {},
+      ...planFile ? { cost: readCostOf(planFile) } : {},
+      ...hasFacts ? { read: true } : {},
+      ...near.length ? { nearFacts: near } : {},
       ...plan ? {
         readPlan: {
           total: plan.total,
@@ -121,10 +199,30 @@ async function readNextState(root) {
       } : {}
     });
   }
+  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);
@@ -164,9 +262,12 @@ async function readNextState(root) {
   let active;
   const types = orgPack instanceof Error ? [] : orgPack.changeTypes.types;
   const { policy } = await loadChangePolicy(orgPackDirOf(root));
-  const os = metarepoOpenSpec(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);
@@ -180,17 +281,41 @@ async function readNextState(root) {
         // 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 progress = os && canMoveOn(c.state) ? await openspecProgress(os, c.id).catch(() => void 0) : void 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;
       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 ? readChangeTasks(files).map((t) => ({ id: t.id, repo: t.repo, done: t.done })) : [],
+        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 } : {},
+        ...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 } : {},
-        ...progress?.next ? { openspecStage: progress.next } : {},
+        ...loop ? { loop } : {},
+        ...live ? {
+          handoff: {
+            phase: live.phase,
+            number: live.pr.number,
+            url: live.pr.url,
+            state: live.state
+          }
+        } : {},
+        ...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 } : {}
@@ -209,7 +334,8 @@ async function readNextState(root) {
   return {
     repos,
     catalogRecords: view.catalog.records,
-    openQuestions: open.questions.map((q) => q.id),
+    // 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,
@@ -237,6 +363,35 @@ async function stageInProgress(root, change) {
   }
   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)
@@ -244,6 +399,25 @@ async function isFast(root, c, types) {
   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 releasePrsOf(root, id) {
+  const reasons = await releasePrReasons(root, id).catch(() => []);
+  if (reasons.some((r) => r.code === "release-pr-missing"))
+    return { releasePrs: "raise" };
+  if (reasons.some((r) => r.code === "release-pr-not-merged"))
+    return { releasePrs: "merge" };
+  return {};
+}
 function stageOf(state) {
   switch (state) {
     case "draft":
@@ -268,7 +442,7 @@ function changeSteps(c) {
   const stage = stageSteps(c);
   const id = c.id;
   const done = stageOf(c.state) === "done";
-  const find = c.feature && !c.needs && !done ? [
+  const find = c.feature && c.knowledge && !c.needs && !done ? [
     {
       step: "needs",
       command: `atticus change needs ${id}`,
@@ -288,13 +462,101 @@ function changeSteps(c) {
       person: true
     }
   ] : [];
-  return [...find, ...stage, ...raise];
+  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];
+}
+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))
+    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 byState = stageOf(c.state);
-  const at = draftingAt;
-  const stage = c.openspecStage && at(byState) >= 0 && at(c.openspecStage) > at(byState) ? c.openspecStage : byState;
+  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 ? [
       {
@@ -318,6 +580,17 @@ function stageSteps(c) {
   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
+        }
+      ];
     return [
       {
         step: "handoff",
@@ -337,18 +610,29 @@ function stageSteps(c) {
           command: `atticus change feature ${id}`,
           slash: `/atticus-feature ${id}`,
           where: METAREPO,
-          why: `${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).`,
+          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: `${id} is at the architecture stage: your assistant writes its target flows, and Atticus checks and criticises every draft until nothing blocks (ADR 0087).`,
+          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
         }
       ];
@@ -359,35 +643,83 @@ function stageSteps(c) {
           command: `atticus plan stories ${id}`,
           slash: `/atticus-stories ${id}`,
           where: METAREPO,
-          why: `${id} has an approved design: write its stories and tasks.`,
+          why: againWhy(c, "stories") ?? `${id} has an approved design: write its stories and tasks.`,
           change: id
         }
       ];
     case "tasks": {
-      const t = c.tasks.find((x) => !x.done);
-      if (!t)
+      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} is ticked; the status says what is left before release.`,
+            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).`,
+          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",
@@ -402,7 +734,9 @@ function stageSteps(c) {
       return [];
   }
 }
-function changeAnswer(id, ids) {
+function changeAnswer(c, filed) {
+  const id = c.id;
+  const ids = filed.filter((q) => !c.questions?.includes(q));
   if (!ids.length)
     return [];
   return [
@@ -417,13 +751,25 @@ function changeAnswer(id, ids) {
     }
   ];
 }
+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.id, byChange[inHand.id] ?? []), ...changeSteps(inHand));
-  const ofChanges = new Set(Object.values(byChange).flat());
+    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({
@@ -440,7 +786,7 @@ function nextSteps(s) {
       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);
+  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",
@@ -453,7 +799,26 @@ function nextSteps(s) {
       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.`,
+      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);
@@ -593,7 +958,7 @@ function nextSteps(s) {
   const inFlight = s.changes.filter((c) => stageOf(c.state) !== "done");
   for (const c of inFlight)
     if (c !== inHand)
-      out.push(...changeAnswer(c.id, byChange[c.id] ?? []), ...changeSteps(c));
+      out.push(...changeAnswer(c, byChange[c.id] ?? []), ...changeSteps(c));
   if (!inFlight.length)
     out.push({
       step: "new-change",
@@ -608,6 +973,8 @@ async function nextCommand(root, o, io) {
     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;
@@ -656,9 +1023,43 @@ async function nextCommand(root, o, io) {
   });
   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 {
-  canMoveOn,
   readNextState,
   changeSteps,
   nextSteps,