Queue plans for the whole shown set, beside the queue-add (#1685)

Author: brillout

FEATURES-SPEC.md

@@ -99,6 +99,7 @@ happens while nobody is at the keyboard.
 - A plan page when a plan exists; a button to start an agent writing one when it doesn't
 - Queue a ticket into the AI queue
 - Queue every ticket the filters show into the AI queue, in one click from the page heading
+- Queue a plan for every unplanned ticket the filters show, from the same heading
 - Tickets carry a GitHub issue link, so merging closes the issue
 
 ## Handoff and what lands in git

packages/framework/dashboard/components/TicketsPage.SPEC.md

@@ -12,6 +12,7 @@ The user wants to see the whole backlog — not one project's slice of it — de
 - **Click-to-filter** - clicking a row's topic adds that topic to the filter, clicking its claim marker narrows to claimed tickets; both add to what is already filtered rather than replacing it.
 - **Plan it or work it from the row** - a ticket can be handed to a planning agent or to an unattended work agent without leaving the page.
 - **Queue the whole shown set** - a button beside the page's heading adds every unclaimed shown ticket to the AI queue (a ticket already queued stays as it is), counting on its label what one click adds; no agent starts — the queue's own consumers do that.
+- **Queue plans for the whole shown set** - a sibling button queues one plan ask per shown ticket still to plan — the plan-tickets ask, placed by the ticket's priority — skipping tickets already planned, already queued, or claimed.
 - **Filtered-away tickets are accounted for** - the page says how many tickets the filters hide and offers to clear them; a project the user deselected disappears silently instead.
 
 ## Business logic
@@ -92,6 +93,22 @@ Once a click has queued the shown set, the button reads "Queued" and rests; any
 
 Queueing rather than starting agents keeps the one click cheap and durable: entries are what the framework already picks up on its own, survive anything that interrupts the work, and spend nothing until an agent actually starts. Skipping already-queued tickets matters because a duplicate entry would outlive its agent's check-off as an open entry naming a closed ticket, costing the sweep an agent.
 
+### Queue plans for the whole shown set
+
+#### User story
+
+The user has filtered the backlog to a slice they intend to work soon and wants plans written for all of it first — to read before committing agents — without asking ticket by ticket.
+
+#### Business logic
+
+Beside the queue-the-shown-set button sits its plan sibling: one click queues, for every shown ticket that has no plan yet and no claim on it, the ask for that ticket's plan — the same wording the plan-tickets preset queues — placed in the AI queue by the ticket's own priority, walked in the shown order. A drain agent reaching such an entry writes the plan. No agent starts from the click.
+
+The click leaves alone what queueing again would waste: a ticket whose plan ask is already an open entry (recognized by its exact wording), and a ticket already queued for implementation — its work would land before a trailing plan could matter. The button's label counts only what it will ask for, saying "unplanned" the moment its count differs from the shown tally; hovering explains the mechanics, the worked order, and what is left alone. Once a click has queued the shown set's plans the button reads "Plans queued" and rests until the shown set changes. With nothing left to plan the button is not offered — the queue-the-tickets button stands on its own.
+
+#### Rationale
+
+Plans are for a human to read before spending agents, so asking for them in bulk is the natural prelude to queueing the same slice for implementation. The asks ride the same queue as everything else so the framework's own consumers pick them up with no new machinery — and the entry deliberately is not a ticket link, since a leading ticket link is what every reader takes as "queued for implementation".
+
 ### Filtered-away tickets are accounted for
 
 #### User story

packages/framework/dashboard/components/TicketsPage.test.SPEC.md

@@ -8,6 +8,8 @@ Grouping: the flat mode renders one cross-project list ordered across projects,
 
 The page-wide queue-add button: every shown ticket is queued the way the ticket detail page queues one (title as the entry, ticket linked, priority picking the section) and no agent is started; after the click the button reads "Queued" and stays disabled until the shown set changes, when it arms again counting the new set; a ticket an open queue entry already links to is not queued twice, and a checked-off entry does not count as queued; claimed tickets are skipped, with the button's label counting only the unclaimed tickets it will add; and the button is absent when nothing is shown or every shown ticket is claimed.
 
+Its plan sibling: every shown ticket still to plan gets one plan ask queued, the ticket named with its priority, with no implementation entry and no agent started; after the click the button reads "Plans queued" and rests; planned and claimed tickets are skipped with the label counting only what is left to plan; a plan ask already queued (recognized by its exact wording) and a ticket already queued for implementation are not asked again; and with every shown ticket planned the plan button is absent while the queue-add still offers.
+
 ## Before modifying/creating SPEC.md files
 
 You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/framework/dashboard/components/TicketsPage.test.tsx

@@ -8,7 +8,7 @@ const onAllTickets = vi.hoisted(() => vi.fn())
 const onTicketsMeta = vi.hoisted(() => vi.fn())
 const onQueue = vi.hoisted(() => vi.fn())
 vi.mock('../rpc/reads.js', () => ({ onAllTickets, onTicketsMeta, onQueue }))
-vi.mock('../rpc/control.js', () => ({ sendQueueTicket: vi.fn(), sendStart: vi.fn() }))
+vi.mock('../rpc/control.js', () => ({ sendQueueTicket: vi.fn(), sendQueueTicketPlan: vi.fn(), sendStart: vi.fn() }))
 
 const { TicketsPage } = await import('./TicketsPage.js')
 
@@ -29,6 +29,15 @@ beforeEach(() => {
   window.history.replaceState(null, '', '/tickets')
 })
 
+/** Fresh control mocks for the tests that click the header's queue-adds. */
+const controls = async () => {
+  const { sendStart, sendQueueTicket, sendQueueTicketPlan } = await import('../rpc/control.js')
+  vi.mocked(sendStart).mockClear().mockResolvedValue({ ok: true, agentId: 'a1' })
+  vi.mocked(sendQueueTicket).mockClear().mockResolvedValue({ ok: true, file: 'TODO_AGENTS.md' })
+  vi.mocked(sendQueueTicketPlan).mockClear().mockResolvedValue({ ok: true, file: 'TODO_AGENTS.md' })
+  return { sendStart, sendQueueTicket, sendQueueTicketPlan }
+}
+
 afterEach(cleanup)
 
 // The Tickets view (#1144): every registered project's backlog, one section each — reading
@@ -260,13 +269,6 @@ describe('TicketsPage grouping (#1144)', () => {
 // every unclaimed shown ticket joins the AI queue (unless an open entry already links to it),
 // and no agent starts: the queue's own consumers do that.
 describe('TicketsPage add the shown set to the AI queue', () => {
-  const controls = async () => {
-    const { sendStart, sendQueueTicket } = await import('../rpc/control.js')
-    vi.mocked(sendStart).mockClear().mockResolvedValue({ ok: true, agentId: 'a1' })
-    vi.mocked(sendQueueTicket).mockClear().mockResolvedValue({ ok: true, file: 'TODO_AGENTS.md' })
-    return { sendStart, sendQueueTicket }
-  }
-
   test('every shown ticket joins the queue, and the button rests as Queued until the set changes', async () => {
     onAllTickets.mockResolvedValue([
       {
@@ -341,22 +343,115 @@ describe('TicketsPage add the shown set to the AI queue', () => {
     expect(sendQueueTicket).toHaveBeenCalledWith('p1', 'First', { file: 'a.md' })
   })
 
-  test('nothing shown, no button: an empty shown set is not an offer', async () => {
+  test('nothing shown, no buttons: an empty shown set is not an offer', async () => {
     onAllTickets.mockResolvedValue([
       { projectId: 'p1', projectName: 'Alpha', tickets: [ticket({ file: 'a.md', title: 'First' })] },
     ])
     window.history.replaceState(null, '', '/tickets?q=zzz-no-match')
     render(<TicketsPage onOpenTicket={() => {}} />)
     await screen.findByText(/1 ticket hidden by the current filters/i)
     expect(screen.queryByRole('button', { name: /to the ai queue/i })).toBeNull()
+    expect(screen.queryByRole('button', { name: /queue plans/i })).toBeNull()
   })
 
-  test('every shown ticket claimed, no button: the whole set is already being worked', async () => {
+  test('every shown ticket claimed, no buttons: the whole set is already being worked', async () => {
     onAllTickets.mockResolvedValue([
       { projectId: 'p1', projectName: 'Alpha', tickets: [ticket({ file: 'a.md', title: 'First', locked: true })] },
     ])
     render(<TicketsPage onOpenTicket={() => {}} />)
     await screen.findByText('First')
     expect(screen.queryByRole('button', { name: /to the ai queue/i })).toBeNull()
+    expect(screen.queryByRole('button', { name: /queue a plan/i })).toBeNull()
+  })
+})
+
+// The plan sibling of the queue-add: one `Create tickets/<stem>.plan.md` entry per shown ticket
+// still to plan — the Plan tickets preset's own ask, placed by the ticket's priority — and no
+// agent starts here either.
+describe('TicketsPage queue plans for the shown set', () => {
+  test('every shown ticket still to plan gets its plan queued, and the button rests as Plans queued', async () => {
+    onAllTickets.mockResolvedValue([
+      {
+        projectId: 'p1',
+        projectName: 'Alpha',
+        tickets: [ticket({ file: 'a.md', title: 'First', priority: '7' }), ticket({ file: 'b.md', title: 'Second' })],
+      },
+    ])
+    const { sendStart, sendQueueTicket, sendQueueTicketPlan } = await controls()
+    render(<TicketsPage onOpenTicket={() => {}} />)
+    fireEvent.click(await screen.findByRole('button', { name: 'Queue plans for all 2 tickets shown below' }))
+    // One plan ask per ticket, the ticket named with its priority so the entry lands in its
+    // section — and neither an implementation entry nor an agent comes out of this button.
+    await waitFor(() => expect(sendQueueTicketPlan).toHaveBeenCalledTimes(2))
+    expect(sendQueueTicketPlan).toHaveBeenCalledWith('p1', { file: 'a.md', priority: '7' })
+    expect(sendQueueTicketPlan).toHaveBeenCalledWith('p1', { file: 'b.md' })
+    expect(sendQueueTicket).not.toHaveBeenCalled()
+    expect(sendStart).not.toHaveBeenCalled()
+    const rested = await screen.findByRole('button', { name: 'Plans queued' })
+    expect((rested as HTMLButtonElement).disabled).toBe(true)
+  })
+
+  test('planned and claimed tickets are skipped, and the label counts only what is left to plan', async () => {
+    onAllTickets.mockResolvedValue([
+      {
+        projectId: 'p1',
+        projectName: 'Alpha',
+        tickets: [
+          ticket({ file: 'a.md', title: 'First' }),
+          ticket({ file: 'b.md', title: 'Second', planned: true }),
+          ticket({ file: 'c.md', title: 'Third', locked: true, lockedBy: 'agent-1' }),
+        ],
+      },
+    ])
+    const { sendQueueTicketPlan } = await controls()
+    render(<TicketsPage onOpenTicket={() => {}} />)
+    fireEvent.click(await screen.findByRole('button', { name: 'Queue a plan for the one unplanned ticket shown below' }))
+    await screen.findByRole('button', { name: 'Plans queued' })
+    expect(sendQueueTicketPlan).toHaveBeenCalledTimes(1)
+    expect(sendQueueTicketPlan).toHaveBeenCalledWith('p1', { file: 'a.md' })
+  })
+
+  test('a plan already asked for — or a ticket queued for implementation — is not asked again', async () => {
+    onAllTickets.mockResolvedValue([
+      {
+        projectId: 'p1',
+        projectName: 'Alpha',
+        tickets: [
+          ticket({ file: 'a.md', title: 'First' }),
+          ticket({ file: 'b.md', title: 'Second' }),
+          ticket({ file: 'c.md', title: 'Third' }),
+        ],
+      },
+    ])
+    // a.md's plan ask is already an open entry (recognized by its exact text); b.md is queued
+    // for implementation, whose work would land before a trailing plan could matter.
+    onQueue.mockResolvedValue([
+      {
+        projectId: 'p1',
+        projectName: 'Alpha',
+        open: 2,
+        total: 2,
+        items: [
+          { text: 'Create tickets/a.plan.md', done: false },
+          { text: '[Second](tickets/b.md)', done: false },
+        ],
+      },
+    ])
+    const { sendQueueTicketPlan } = await controls()
+    render(<TicketsPage onOpenTicket={() => {}} />)
+    fireEvent.click(await screen.findByRole('button', { name: 'Queue plans for all 3 tickets shown below' }))
+    await screen.findByRole('button', { name: 'Plans queued' })
+    expect(sendQueueTicketPlan).toHaveBeenCalledTimes(1)
+    expect(sendQueueTicketPlan).toHaveBeenCalledWith('p1', { file: 'c.md' })
+  })
+
+  test('every shown ticket planned already, no plan button — the queue-add still offers', async () => {
+    onAllTickets.mockResolvedValue([
+      { projectId: 'p1', projectName: 'Alpha', tickets: [ticket({ file: 'a.md', title: 'First', planned: true })] },
+    ])
+    render(<TicketsPage onOpenTicket={() => {}} />)
+    await screen.findByText('First')
+    expect(screen.queryByRole('button', { name: /queue a plan|queue plans/i })).toBeNull()
+    expect(screen.getByRole('button', { name: 'Add the ticket shown below to the AI queue' })).toBeTruthy()
   })
 })