From e75c0baf57d00a294e9cb4cd2114698c4a0b86a7 Mon Sep 17 00:00:00 2001
From: Dylan Trotter <dylan@bitcomplete.io>
Date: Mon, 26 Oct 2026 18:54:49 +0000
Subject: [PATCH 1/2] stewards: bb stewards needs lists the needsYou set
 (BB-69)

---
 plugins/stewards/server.test.ts           | 54 +++++++++++++++++++++++
 plugins/stewards/server.ts                | 32 +++++++-------
 plugins/stewards/skills/stewards/SKILL.md |  2 +-
 3 files changed, 71 insertions(+), 17 deletions(-)

diff --git a/plugins/stewards/server.test.ts b/plugins/stewards/server.test.ts
index 56209fe8..478ff859 100644
--- a/plugins/stewards/server.test.ts
+++ b/plugins/stewards/server.test.ts
@@ -4077,6 +4077,60 @@ describe("needs you items", () => {
   });
 });
 
+// BB-69: the CLI lists the same "waiting on you" set the Stewards page and the
+// sidebar do, in the same order: open questions, with-user escalations, needs.
+describe("bb stewards needs lists the needsYou set (BB-69)", () => {
+  type BoardView = { questions: Array<{ id: string }>; withUser: Array<{ id: string }>; needs: Array<{ id: string }> };
+
+  async function adopted() {
+    const t = await setup();
+    t.entities.set("uuid-12", issue());
+    await t.ring("linear", "uuid-12");
+    const binding = () => t.hooks.store.find("ENG-12", "p1")!;
+    const board = async () => ((await t.harness.callRpc("stewardsBoard", { projectId: "p1" })) as { board: BoardView }).board;
+    const cli = async () => (await t.harness.behavior.runCli(["needs", "--project", "p1"])).stdout;
+    return { ...t, binding, board, cli };
+  }
+
+  it("prints an open question before a need, with its choices and the done command", async () => {
+    const t = await adopted();
+    const b = t.binding();
+    const question = t.hooks.store.ask({ projectId: "p1", bindingId: b.id, escalationId: null, question: "Merge or close?", context: null, choices: ["Merge", "Close"] });
+    const need = t.hooks.store.fileNeed({ bindingId: b.id, kind: "configure", url: "", what: "Enable the flag", how: null });
+    const out = await t.cli();
+    expect(out).toContain(question.id);
+    expect(out).toContain(need.id);
+    // The question comes first.
+    expect(out.indexOf(question.id)).toBeLessThan(out.indexOf(need.id));
+    expect(out).toMatch(new RegExp(`${question.id} — question, ENG-12: Merge or close\\? \\[choices: Merge, Close\\] — bb stewards done ${question.id} --choice "<label>"`, "u"));
+    expect(out).toContain(`${need.id} — configure, ENG-12: Enable the flag — bb stewards done ${need.id}`);
+  });
+
+  it("prints an uncovered with-user escalation between the question and the need", async () => {
+    const t = await adopted();
+    const b = t.binding();
+    const question = t.hooks.store.ask({ projectId: "p1", bindingId: b.id, escalationId: null, question: "Which option?", context: null });
+    const escalation = t.hooks.store.escalate({ bindingId: b.id, kind: "approval", question: "Approve the spec?", meanwhile: "Wait.", route: "me", recommendation: null, projectId: "p1" });
+    const need = t.hooks.store.fileNeed({ bindingId: b.id, kind: "configure", url: "", what: "Enable the flag", how: null });
+    const out = await t.cli();
+    expect(out.indexOf(question.id)).toBeLessThan(out.indexOf(escalation.id));
+    expect(out.indexOf(escalation.id)).toBeLessThan(out.indexOf(need.id));
+    expect(out).toContain(`${escalation.id} — approval escalation, ENG-12: Approve the spec? — bb stewards done ${escalation.id}`);
+  });
+
+  it("equals the set and order the board's needsYou returns", async () => {
+    const t = await adopted();
+    const b = t.binding();
+    t.hooks.store.ask({ projectId: "p1", bindingId: b.id, escalationId: null, question: "Which option?", context: null });
+    t.hooks.store.escalate({ bindingId: b.id, kind: "approval", question: "Approve the spec?", meanwhile: "Wait.", route: "me", recommendation: null, projectId: "p1" });
+    t.hooks.store.fileNeed({ bindingId: b.id, kind: "configure", url: "", what: "Enable the flag", how: null });
+    const view = await t.board();
+    const expected = [...view.questions, ...view.withUser, ...view.needs].map((x) => x.id);
+    const printed = (await t.cli()).split("\n").map((line) => line.split(" — ")[0]);
+    expect(printed).toEqual(expected);
+  });
+});
+
 // BB-20: a decide item or forwarded decision question can carry fixed
 // choices, so the page shows a button each instead of asking for a word.
 describe("fixed choices on decide items and questions", () => {
diff --git a/plugins/stewards/server.ts b/plugins/stewards/server.ts
index df913ed5..398a863d 100644
--- a/plugins/stewards/server.ts
+++ b/plugins/stewards/server.ts
@@ -6544,24 +6544,24 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P
           }),
 
           needs: cliCommand({
-            summary: "Things waiting on the user: links and the action each supports",
-            description: "The same items as the Stewards page's \"Waiting on you\" section. `done <id>` closes one from a thread.",
-            options: { all: { type: "boolean", description: "Include closed items" }, project: PROJECT_OPTION, json: JSON_OPTION },
+            summary: "Things waiting on the user: open questions, escalations with the user, then needs",
+            description: "The same items as the Stewards page's \"Waiting on you\" section and the sidebar, in the same order: open questions, route-`me` escalations no question or need covers, then needs. Each line ends with the `bb stewards done` command that answers it.",
+            options: { project: PROJECT_OPTION, json: JSON_OPTION },
             async run(input, ctx) {
               const projectId = projectOf(input.options.project, ctx);
-              const rows = input.options.all ? store.allNeedsForProject(projectId) : store.openNeedsForProject(projectId);
-              if (input.options.json) return { exitCode: 0, stdout: JSON.stringify(rows) };
-              if (rows.length === 0) return { exitCode: 0, stdout: "Nothing is waiting on the user." };
-              return {
-                exitCode: 0,
-                stdout: rows
-                  .map((n) => {
-                    const b = store.binding(n.bindingId);
-                    const view = b === null ? null : needView(n, b);
-                    return `${n.id} — ${n.kind}, ${b?.entityKey ?? n.bindingId}: ${n.what}${choicesNote(needChoices(n))}${n.url === "" ? "" : ` (${n.url})`}${view !== null && !view.actionable ? ` [not actionable: ${view.why}]` : ""}`;
-                  })
-                  .join("\n"),
-              };
+              // One builder for the three surfaces, so the CLI, the page and the
+              // sidebar cannot drift (BB-69).
+              const { questions, withUser, needs } = needsYou(projectId);
+              if (input.options.json) return { exitCode: 0, stdout: JSON.stringify({ questions, withUser, needs }) };
+              if (questions.length + withUser.length + needs.length === 0) return { exitCode: 0, stdout: "Nothing is waiting on the user." };
+              const oneLine = (text: string) => text.replace(/\s+/gu, " ").trim();
+              const done = (id: string, choices: readonly string[]) => `bb stewards done ${id}${choices.length === 0 ? "" : ` --choice "<label>"`}`;
+              const lines = [
+                ...questions.map((q) => `${q.id} — question, ${q.key ?? "project"}: ${oneLine(q.question)}${choicesNote(q.choices)} — ${done(q.id, q.choices)}`),
+                ...withUser.map((x) => `${x.id} — ${x.kind} escalation, ${x.key}: ${oneLine(x.question)} — ${done(x.id, [])}`),
+                ...needs.map((n) => `${n.id} — ${n.kind}, ${n.key}: ${oneLine(n.what)}${choicesNote(n.choices)}${n.url === null ? "" : ` (${n.url})`}${n.actionable ? "" : ` [not actionable: ${n.why ?? "unknown"}]`} — ${done(n.id, n.choices)}`),
+              ];
+              return { exitCode: 0, stdout: lines.join("\n") };
             },
           }),
 
diff --git a/plugins/stewards/skills/stewards/SKILL.md b/plugins/stewards/skills/stewards/SKILL.md
index 0f1e831c..65fcec21 100644
--- a/plugins/stewards/skills/stewards/SKILL.md
+++ b/plugins/stewards/skills/stewards/SKILL.md
@@ -378,7 +378,7 @@ project.
 | `bb stewards spawn-flags [<binding>] [--project <id>]` | The full runnable `bb thread spawn …` command for a steward's workers, from the playbook's `models.worker` and the project environment |
 | `bb stewards list [--all] [--json]` | Bindings and their status records |
 | `bb stewards show <ENG-12 \| owner/repo#3 \| k8s-namespace/name>` | One binding in full: gate, guidance, escalations, needs, workers, fingerprints |
-| `bb stewards needs [--all] [--json]` | What waits on the user, with links and the action each supports |
+| `bb stewards needs [--json]` | What waits on the user, in the sidebar's order: open questions, escalations with the user, then needs; each line ends with the `bb stewards done` command that answers it |
 | `bb stewards done <need_… \| qst_…> [--choice <label>] [--note <text>]` | Close a waiting item from a thread; `--choice` records the label the user gave in chat (it must be one of the item's choices) and saves it as guidance; an `approve-spec` item records the approval on the gate and resolves its escalation; wakes the steward with it |
 | `bb stewards detach <key>` | One stop turn; stays detached until the label is removed and re-added |
 | `bb stewards secret import --from <dotenv> --setting <name>` | A requester thread's own command: read a dotenv on its machine into a declared secret setting and delete the file |

From baca3a1fd14e7f9e54712b799f24ec593dcff077 Mon Sep 17 00:00:00 2001
From: Dylan Trotter <dylan@bitcomplete.io>
Date: Mon, 26 Oct 2026 19:04:15 +0000
Subject: [PATCH 2/2] stewards: keep bb stewards needs --all and the old --json
 needs array (BB-69)

---
 plugins/stewards/DESIGN.md                |  7 +++---
 plugins/stewards/server.test.ts           | 30 +++++++++++++++++++++++
 plugins/stewards/server.ts                | 24 +++++++++++++++---
 plugins/stewards/skills/stewards/SKILL.md |  2 +-
 4 files changed, 56 insertions(+), 7 deletions(-)

diff --git a/plugins/stewards/DESIGN.md b/plugins/stewards/DESIGN.md
index 4591cb55..d7592ea9 100644
--- a/plugins/stewards/DESIGN.md
+++ b/plugins/stewards/DESIGN.md
@@ -1491,9 +1491,10 @@ page does not already make.
 
 **One source of truth.** `server.ts`'s `needsYou(projectId, { actionableOnly
 })` builds the board's `questions`, `withUser` and `needs` lists in one place;
-the board calls it unfiltered and the sidebar calls it with `actionableOnly`,
-so the two surfaces cannot drift and a non-actionable need is on the page but
-not in the sidebar's count or items. `stewardsSidebar` carries, per project,
+the board calls it unfiltered, the sidebar calls it with `actionableOnly`, and
+`bb stewards needs` prints it, so the surfaces cannot drift and a non-actionable
+need is on the page but not in the sidebar's count or items. `stewardsSidebar`
+carries, per project,
 `needs: { count, items }` with the same row shapes, each tagged
 `question`/`withUser`/`need` so the app knows how to render the row and which
 one-click action it carries.
diff --git a/plugins/stewards/server.test.ts b/plugins/stewards/server.test.ts
index 478ff859..fd06a3e8 100644
--- a/plugins/stewards/server.test.ts
+++ b/plugins/stewards/server.test.ts
@@ -4129,6 +4129,36 @@ describe("bb stewards needs lists the needsYou set (BB-69)", () => {
     const printed = (await t.cli()).split("\n").map((line) => line.split(" — ")[0]);
     expect(printed).toEqual(expected);
   });
+
+  it("extends the old needs array with questions and with-user escalations in --json", async () => {
+    const t = await adopted();
+    const b = t.binding();
+    const question = t.hooks.store.ask({ projectId: "p1", bindingId: b.id, escalationId: null, question: "Which option?", context: null });
+    const escalation = t.hooks.store.escalate({ bindingId: b.id, kind: "approval", question: "Approve the spec?", meanwhile: "Wait.", route: "me", recommendation: null, projectId: "p1" });
+    const need = t.hooks.store.fileNeed({ bindingId: b.id, kind: "configure", url: "", what: "Enable the flag", how: null });
+    const parsed = JSON.parse((await t.harness.behavior.runCli(["needs", "--project", "p1", "--json"])).stdout) as { questions: Array<{ id: string }>; withUser: Array<{ id: string }>; needs: Array<{ id: string }> };
+    expect(Object.keys(parsed).sort()).toEqual(["needs", "questions", "withUser"]);
+    expect(parsed.questions.map((q) => q.id)).toEqual([question.id]);
+    expect(parsed.withUser.map((x) => x.id)).toEqual([escalation.id]);
+    expect(parsed.needs.map((n) => n.id)).toEqual([need.id]);
+    // `--all` keeps the old array of every need.
+    const all = JSON.parse((await t.harness.behavior.runCli(["needs", "--all", "--project", "p1", "--json"])).stdout) as unknown;
+    expect(Array.isArray(all)).toBe(true);
+  });
+
+  it("the printed done command closes the question and the escalation it names", async () => {
+    const t = await adopted();
+    const b = t.binding();
+    const question = t.hooks.store.ask({ projectId: "p1", bindingId: b.id, escalationId: null, question: "Which option?", context: null });
+    const escalation = t.hooks.store.escalate({ bindingId: b.id, kind: "approval", question: "Approve the spec?", meanwhile: "Wait.", route: "me", recommendation: null, projectId: "p1" });
+    const out = await t.cli();
+    expect(out).toContain(`bb stewards done ${question.id}`);
+    expect(out).toContain(`bb stewards done ${escalation.id}`);
+    expect((await t.harness.behavior.runCli(["done", question.id, "--project", "p1"])).exitCode).toBe(0);
+    expect(t.hooks.store.question(question.id)!.status).toBe("answered");
+    expect((await t.harness.behavior.runCli(["done", escalation.id, "--project", "p1"])).exitCode).toBe(0);
+    expect(t.hooks.store.escalation(escalation.id)!.status).toBe("resolved");
+  });
 });
 
 // BB-20: a decide item or forwarded decision question can carry fixed
diff --git a/plugins/stewards/server.ts b/plugins/stewards/server.ts
index 398a863d..a92adc50 100644
--- a/plugins/stewards/server.ts
+++ b/plugins/stewards/server.ts
@@ -6545,14 +6545,32 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P
 
           needs: cliCommand({
             summary: "Things waiting on the user: open questions, escalations with the user, then needs",
-            description: "The same items as the Stewards page's \"Waiting on you\" section and the sidebar, in the same order: open questions, route-`me` escalations no question or need covers, then needs. Each line ends with the `bb stewards done` command that answers it.",
-            options: { project: PROJECT_OPTION, json: JSON_OPTION },
+            description: "The same items as the Stewards page's \"Waiting on you\" section and the sidebar, in the same order: open questions, route-`me` escalations no question or need covers, then needs. Each line ends with the `bb stewards done` command that answers it. `--all` keeps its old job: every need, open or closed, as a diagnostic.",
+            options: { all: { type: "boolean", description: "Include closed items" }, project: PROJECT_OPTION, json: JSON_OPTION },
             async run(input, ctx) {
               const projectId = projectOf(input.options.project, ctx);
+              // `--all` stays the closed-needs diagnostic it was on main.
+              if (input.options.all) {
+                const rows = store.allNeedsForProject(projectId);
+                if (input.options.json) return { exitCode: 0, stdout: JSON.stringify(rows) };
+                if (rows.length === 0) return { exitCode: 0, stdout: "Nothing is waiting on the user." };
+                return {
+                  exitCode: 0,
+                  stdout: rows
+                    .map((n) => {
+                      const b = store.binding(n.bindingId);
+                      const view = b === null ? null : needView(n, b);
+                      return `${n.id} — ${n.kind}, ${b?.entityKey ?? n.bindingId}: ${n.what}${choicesNote(needChoices(n))}${n.url === "" ? "" : ` (${n.url})`}${view !== null && !view.actionable ? ` [not actionable: ${view.why}]` : ""}`;
+                    })
+                    .join("\n"),
+                };
+              }
               // One builder for the three surfaces, so the CLI, the page and the
               // sidebar cannot drift (BB-69).
               const { questions, withUser, needs } = needsYou(projectId);
-              if (input.options.json) return { exitCode: 0, stdout: JSON.stringify({ questions, withUser, needs }) };
+              // The JSON extends the old needs array with the questions and
+              // with-user escalations alongside it.
+              if (input.options.json) return { exitCode: 0, stdout: JSON.stringify({ questions, withUser, needs: store.openNeedsForProject(projectId) }) };
               if (questions.length + withUser.length + needs.length === 0) return { exitCode: 0, stdout: "Nothing is waiting on the user." };
               const oneLine = (text: string) => text.replace(/\s+/gu, " ").trim();
               const done = (id: string, choices: readonly string[]) => `bb stewards done ${id}${choices.length === 0 ? "" : ` --choice "<label>"`}`;
diff --git a/plugins/stewards/skills/stewards/SKILL.md b/plugins/stewards/skills/stewards/SKILL.md
index 65fcec21..013d2c98 100644
--- a/plugins/stewards/skills/stewards/SKILL.md
+++ b/plugins/stewards/skills/stewards/SKILL.md
@@ -378,7 +378,7 @@ project.
 | `bb stewards spawn-flags [<binding>] [--project <id>]` | The full runnable `bb thread spawn …` command for a steward's workers, from the playbook's `models.worker` and the project environment |
 | `bb stewards list [--all] [--json]` | Bindings and their status records |
 | `bb stewards show <ENG-12 \| owner/repo#3 \| k8s-namespace/name>` | One binding in full: gate, guidance, escalations, needs, workers, fingerprints |
-| `bb stewards needs [--json]` | What waits on the user, in the sidebar's order: open questions, escalations with the user, then needs; each line ends with the `bb stewards done` command that answers it |
+| `bb stewards needs [--all] [--json]` | What waits on the user, in the sidebar's order: open questions, escalations with the user, then needs; each line ends with the `bb stewards done` command that answers it. `--all` is the closed-needs diagnostic |
 | `bb stewards done <need_… \| qst_…> [--choice <label>] [--note <text>]` | Close a waiting item from a thread; `--choice` records the label the user gave in chat (it must be one of the item's choices) and saves it as guidance; an `approve-spec` item records the approval on the gate and resolves its escalation; wakes the steward with it |
 | `bb stewards detach <key>` | One stop turn; stays detached until the label is removed and re-added |
 | `bb stewards secret import --from <dotenv> --setting <name>` | A requester thread's own command: read a dotenv on its machine into a declared secret setting and delete the file |