@cat-factory/app 0.275.0 → 0.276.0

package/app/utils/laneGeometry.ts

@@ -0,0 +1,104 @@
+/**
+ * The swimlane layout's fixed pixel geometry, and the two functions that derive a frame's size
+ * from it.
+ *
+ * One module rather than numbers spread across the components, because three consumers have to
+ * agree exactly: `useBlockQueries.contentSize` computes the frame's minimum size, `FrameSwimlanes`
+ * renders into that space, and `framePlacement` reserves a spot for a frame that does not exist
+ * yet. When they disagree the lanes are clipped by their own frame or a new service is dropped on
+ * top of its neighbour, both of which look like rendering bugs rather than a stale constant. That
+ * is why the two derivations below are FUNCTIONS here rather than arithmetic at each call site:
+ * a constant restating the result is exactly the thing that went stale.
+ *
+ * These are DELIBERATELY fixed rather than derived from content. A lane scrolls; it does not
+ * grow. The frame of a service with 300 open tasks is the same size as one with three, which is
+ * what keeps a board of many services readable — the old free-layout frames grew with their task
+ * count until the busiest service dwarfed everything around it. A reader who wants more room
+ * drags the frame's border, and the stored size raises the floor these numbers set.
+ */
+export const LANE_GEOMETRY = {
+  /** Card width, matching the task card's own fixed width. */
+  cardWidth: 210,
+  /** One lane column: a card plus its gutters. */
+  laneWidth: 226,
+  /** Gap between lane columns. */
+  laneGap: 8,
+  /** The three live lanes plus the gaps and the canvas's own padding. */
+  canvasWidth: 226 * 3 + 8 * 2 + 16,
+  /** A lane's scrolling body, at the frame's floor size. */
+  laneBodyHeight: 420,
+  /** A lane's header (label, count, the withheld-count line on the Done lane). */
+  laneHeaderHeight: 34,
+  /** The collapsed Done strip's header row. */
+  doneStripHeight: 32,
+  /** An initiative card in the band above the lanes. */
+  initiativeWidth: 240,
+  initiativeHeight: 176,
+  /**
+   * A service with no children at all renders one "add the first task" panel and no lanes, so it
+   * reserves the panel's footprint rather than the lanes'. Sizing an empty service as though the
+   * lanes were there would leave every new frame two and a half times taller than the thing
+   * inside it, and would push its neighbours that much further away for nothing.
+   */
+  emptyFrameWidth: 360,
+  emptyFrameHeight: 220,
+} as const
+
+/** What the frame lays out itself, which is everything its height cannot derive from a lane. */
+export interface FrameContent {
+  /**
+   * Whether the frame renders lanes at all: it has tasks, modules or initiatives under it. The
+   * same predicate `BlockNode` gates `FrameSwimlanes` on, because a size that disagrees with
+   * what rendered is the clipping bug this module exists to prevent.
+   */
+  readonly hasChildren: boolean
+  /** Initiative cards, which sit in a wrapping band above the lanes. */
+  readonly initiatives: number
+}
+
+/** How many initiative cards fit across a canvas `width` px wide. */
+function initiativeRows(count: number, width: number): number {
+  const perRow = Math.max(1, Math.floor(width / LANE_GEOMETRY.initiativeWidth))
+  return Math.ceil(count / perRow)
+}
+
+/**
+ * The smallest size that fits a frame's swimlanes and its initiative band: the floor a resizable
+ * frame can never be dragged below, and the footprint a placement decision reserves for one that
+ * does not exist yet.
+ */
+export function frameContentSize(content: FrameContent): { w: number; h: number } {
+  if (!content.hasChildren) {
+    return { w: LANE_GEOMETRY.emptyFrameWidth, h: LANE_GEOMETRY.emptyFrameHeight }
+  }
+  const w = LANE_GEOMETRY.canvasWidth
+  return {
+    w,
+    h:
+      initiativeRows(content.initiatives, w) * LANE_GEOMETRY.initiativeHeight +
+      LANE_GEOMETRY.laneBodyHeight +
+      LANE_GEOMETRY.laneHeaderHeight +
+      LANE_GEOMETRY.doneStripHeight,
+  }
+}
+
+/**
+ * How tall a lane's scrolling body is inside a frame of `size`.
+ *
+ * The inverse of {@link frameContentSize}: the room left once the initiative band, the lane
+ * headers and the collapsed Done strip have taken theirs. A frame at its floor size gets exactly
+ * `laneBodyHeight` back, and a frame the reader has dragged taller gives the whole difference to
+ * the lanes — which is the point of dragging it. Without this the lanes kept their constant
+ * height and the extra space was dead canvas below them, so the gesture appeared to do nothing.
+ *
+ * Never returns less than `laneBodyHeight`: a frame can be dragged no smaller than its floor, and
+ * a caller measuring one mid-layout should not be able to collapse a lane to nothing.
+ */
+export function laneBodyHeightIn(size: { w: number; h: number }, initiatives: number): number {
+  const room =
+    size.h -
+    initiativeRows(initiatives, size.w) * LANE_GEOMETRY.initiativeHeight -
+    LANE_GEOMETRY.laneHeaderHeight -
+    LANE_GEOMETRY.doneStripHeight
+  return Math.max(LANE_GEOMETRY.laneBodyHeight, room)
+}

package/app/utils/laneSort.spec.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from 'vitest'
+import type { Block, ExecutionInstance, PipelineStep } from '~/types/domain'
+import {
+  groupLaneTasks,
+  LANE_SORT_KEYS,
+  runActivityAt,
+  runWaitingSince,
+  sortLaneTasks,
+  type LaneTaskEntry,
+} from '~/utils/laneSort'
+
+// Two invariants carry the ordering, and both are about NOT inventing facts. An unknown
+// timestamp must never rank as an extreme (a run that reported no activity is not stale and
+// not fresh), and every comparator must be total, because these re-run on every live board
+// push and an unresolved tie lets cards trade places for no visible reason.
+
+function entry(overrides: Partial<LaneTaskEntry> = {}): LaneTaskEntry {
+  return {
+    task: { id: 'blk', title: 'Task', status: 'ready', level: 'task' } as Block,
+    reason: 'unstarted',
+    order: 0,
+    activityAt: null,
+    waitingSince: null,
+    moduleName: null,
+    initiativeName: null,
+    epicName: null,
+    ...overrides,
+  }
+}
+
+function task(overrides: Partial<Block> = {}): Block {
+  return { id: 'blk', title: 'Task', status: 'ready', level: 'task', ...overrides } as Block
+}
+
+function step(overrides: Partial<PipelineStep> = {}): PipelineStep {
+  return { agentKind: 'coder', state: 'done', progress: 1, ...overrides } as PipelineStep
+}
+
+function run(steps: PipelineStep[], overrides: Partial<ExecutionInstance> = {}): ExecutionInstance {
+  return { id: 'exe', blockId: 'blk', status: 'running', steps, ...overrides } as ExecutionInstance
+}
+
+describe('runActivityAt', () => {
+  it('prefers the harness heartbeat, the truthful signal where it exists', () => {
+    expect(runActivityAt(run([step({ startedAt: 100, lastActivityAt: 500 })]))).toBe(500)
+  })
+
+  it('falls back to a start stamp, then the run creation, then unknown', () => {
+    // `lastActivityAt` is only stamped on CONTAINER steps by a heartbeat-capable image, so
+    // it is legitimately absent for inline steps and older harnesses.
+    expect(runActivityAt(run([step({ startedAt: 100 })]))).toBe(100)
+    expect(runActivityAt(run([step()], { createdAt: 42 }))).toBe(42)
+    expect(runActivityAt(run([step()]))).toBeNull()
+    expect(runActivityAt(null)).toBeNull()
+  })
+
+  it('takes the LATEST signal across steps, not the first', () => {
+    expect(runActivityAt(run([step({ lastActivityAt: 100 }), step({ lastActivityAt: 900 })]))).toBe(
+      900,
+    )
+  })
+})
+
+describe('runWaitingSince', () => {
+  it("reads the engine's own park clock", () => {
+    expect(runWaitingSince(run([step({ pausedAt: 700 })]))).toBe(700)
+  })
+
+  it('takes the EARLIEST park, so the wait is measured from when it started', () => {
+    expect(runWaitingSince(run([step({ pausedAt: 700 }), step({ pausedAt: 300 })]))).toBe(300)
+  })
+
+  it('never substitutes how long the run has been ALIVE for how long it has WAITED', () => {
+    // A run three days old that parked a minute ago has waited a minute. Falling back to
+    // the run's start would sort a busy run to the top of the review queue.
+    expect(runWaitingSince(run([step()], { createdAt: 1 }))).toBeNull()
+  })
+
+  it('accepts the notification-derived wait as an independent second source', () => {
+    // Not every park surface stamps `pausedAt`; `collectReviewDebt` derives the same fact
+    // from the earliest open review-wait card.
+    expect(runWaitingSince(run([step()]), 250)).toBe(250)
+    // …but the engine's own clock wins when both are present.
+    expect(runWaitingSince(run([step({ pausedAt: 700 })]), 250)).toBe(700)
+  })
+})
+
+describe('sortLaneTasks — unknown values', () => {
+  it('ranks an unknown timestamp LAST in both directions', () => {
+    const known = entry({ order: 1, activityAt: 500 })
+    const unknown = entry({ order: 0, activityAt: null })
+
+    // Oldest-first would put `null` first if it were read as 0, and newest-first would put
+    // it first if it were read as Infinity. Neither is a fact anybody recorded.
+    expect(sortLaneTasks([unknown, known], 'oldest_activity', 'in_progress')).toEqual([
+      known,
+      unknown,
+    ])
+    expect(sortLaneTasks([unknown, known], 'newest_activity', 'in_progress')).toEqual([
+      known,
+      unknown,
+    ])
+  })
+
+  it('does not read a missing severity as `low`', () => {
+    const critical = entry({ order: 1, task: task({ taskTypeFields: { severity: 'critical' } }) })
+    const none = entry({ order: 0, task: task() })
+    expect(sortLaneTasks([none, critical], 'severity_desc', 'needs_you')).toEqual([critical, none])
+  })
+
+  it('does not read a missing estimate as zero impact', () => {
+    // `estimate` is absent until a `task-estimator` step has run, which is most tasks.
+    const rated = entry({
+      order: 1,
+      task: task({
+        estimate: { complexity: 0.2, risk: 0.2, impact: 0.9, rationale: '', createdAt: 1 },
+      }),
+    })
+    const unrated = entry({ order: 0, task: task() })
+    expect(sortLaneTasks([unrated, rated], 'impact_desc', 'not_started')).toEqual([rated, unrated])
+  })
+})
+
+describe('sortLaneTasks — determinism', () => {
+  it('resolves every tie on board order, for every sort key', () => {
+    // Live pushes re-run these constantly; an unresolved tie reads as the lane shuffling
+    // itself. Asserted over the whole key list so a new key cannot skip the tiebreak.
+    const a = entry({ order: 0, task: task({ id: 'a', title: 'Same' }) })
+    const b = entry({ order: 1, task: task({ id: 'b', title: 'Same' }) })
+    for (const key of LANE_SORT_KEYS) {
+      const ordered = sortLaneTasks([b, a], key, 'not_started')
+      expect(
+        ordered.map((e) => e.task.id),
+        `key ${key}`,
+      ).toEqual(['a', 'b'])
+    }
+  })
+
+  it('does not mutate its input', () => {
+    const entries = [entry({ order: 1 }), entry({ order: 0 })]
+    const snapshot = [...entries]
+    sortLaneTasks(entries, 'smart', 'not_started')
+    expect(entries).toEqual(snapshot)
+  })
+})
+
+describe('sortLaneTasks — the per-lane smart order', () => {
+  it('sinks a dependency-blocked task below one that can start now', () => {
+    const blocked = entry({ order: 0, reason: 'dependencies' })
+    const ready = entry({ order: 1, reason: 'unstarted' })
+    expect(sortLaneTasks([blocked, ready], 'smart', 'not_started')).toEqual([ready, blocked])
+  })
+
+  it('leads the in-progress lane with the QUIETEST run', () => {
+    // A healthy run needs nothing; the reason to scan this column is to find the one that
+    // stopped making noise.
+    const quiet = entry({ order: 1, reason: 'running', activityAt: 100 })
+    const busy = entry({ order: 0, reason: 'running', activityAt: 900 })
+    expect(sortLaneTasks([busy, quiet], 'smart', 'in_progress')).toEqual([quiet, busy])
+  })
+
+  it('leads the needs-you lane with what is BROKEN, then the longest wait', () => {
+    // A failure raises no review-wait card and stamps no park clock, so a pure wait-time
+    // order files it behind gates that are merely patient.
+    const failed = entry({ order: 2, reason: 'failed', waitingSince: null })
+    const oldGate = entry({ order: 1, reason: 'approval', waitingSince: 100 })
+    const newGate = entry({ order: 0, reason: 'approval', waitingSince: 900 })
+    expect(sortLaneTasks([newGate, oldGate, failed], 'smart', 'needs_you')).toEqual([
+      failed,
+      oldGate,
+      newGate,
+    ])
+  })
+
+  it('leads the done lane with the most recent completion', () => {
+    const older = entry({ order: 0, task: task({ completedAt: 100 }) })
+    const newer = entry({ order: 1, task: task({ completedAt: 900 }) })
+    expect(sortLaneTasks([older, newer], 'smart', 'done')).toEqual([newer, older])
+  })
+})
+
+describe('groupLaneTasks', () => {
+  it('keeps everything in one unlabelled group when grouping is off', () => {
+    const entries = [entry({ order: 0 }), entry({ order: 1 })]
+    expect(groupLaneTasks(entries, 'none')).toEqual([{ id: null, label: null, entries }])
+  })
+
+  it('orders groups by where their first member appears, preserving the sort', () => {
+    // A group appearing out of sort order would silently override the sort key the reader
+    // just chose.
+    const groups = groupLaneTasks(
+      [
+        entry({ order: 0, moduleName: 'invoicing' }),
+        entry({ order: 1, moduleName: 'billing' }),
+        entry({ order: 2, moduleName: 'invoicing' }),
+      ],
+      'module',
+    )
+    expect(groups.map((g) => g.label)).toEqual(['invoicing', 'billing'])
+    expect(groups[0]!.entries.map((e) => e.order)).toEqual([0, 2])
+  })
+
+  it('forces the catch-all group last however early its first member sorts', () => {
+    // "Everything else" reading above a named group inverts the hierarchy the grouping states.
+    const groups = groupLaneTasks(
+      [entry({ order: 0, moduleName: null }), entry({ order: 1, moduleName: 'billing' })],
+      'module',
+    )
+    expect(groups.map((g) => g.label)).toEqual(['billing', null])
+  })
+
+  it('carries a module BLOCK id onto its header so the header can be a drop target', () => {
+    const groups = groupLaneTasks(
+      [entry({ moduleName: 'billing' }), entry({ order: 1, moduleName: 'unbuilt' })],
+      'module',
+      new Map([['billing', 'mod_1']]),
+    )
+    expect(groups.find((g) => g.label === 'billing')?.id).toBe('mod_1')
+    // A module the engine has not materialised yet is still grouped and labelled; it just
+    // is not something a card can be dropped onto.
+    expect(groups.find((g) => g.label === 'unbuilt')?.id).toBeNull()
+  })
+
+  it('groups by blocking reason, so one lane can be split by what it needs', () => {
+    const groups = groupLaneTasks(
+      [entry({ order: 0, reason: 'failed' }), entry({ order: 1, reason: 'approval' })],
+      'blocking_reason',
+    )
+    expect(groups.map((g) => g.label)).toEqual(['failed', 'approval'])
+  })
+
+  it('omits an empty catch-all group rather than rendering an empty header', () => {
+    const groups = groupLaneTasks([entry({ moduleName: 'billing' })], 'module')
+    expect(groups).toHaveLength(1)
+  })
+})

package/app/utils/laneSort.ts

@@ -0,0 +1,306 @@
+import type { Block, ExecutionInstance, PipelineStep } from '~/types/domain'
+import type { LaneReason, TaskLane } from '~/utils/swimlanes'
+
+// ---------------------------------------------------------------------------
+// Ordering and grouping WITHIN a swimlane.
+//
+// Two rules shape every comparator here.
+//
+// An UNKNOWN value sorts last, in both directions. A task whose run reported no
+// activity timestamp is not "very stale" and not "just active" — it is unknown,
+// and ranking it as either end of the scale is the platform inventing a fact it
+// does not have. `nullsLast` is the one place that is enforced.
+//
+// Every comparator ends on the board's own insertion order. Live board events
+// re-run these on every push, so a comparator that leaves ties unresolved lets
+// equal-ranked cards swap places whenever anything upstream changes, which reads
+// as the lane shuffling itself for no reason.
+// ---------------------------------------------------------------------------
+
+/**
+ * How a lane's cards are ordered.
+ *
+ * `smart` is the default and is per-lane (see {@link SMART_ORDER_BY_LANE}): the order that
+ * is actionable differs by column, and one global key is wrong for at least two of them.
+ * The explicit keys exist to override that when a reader is doing something specific
+ * (triaging bugs by severity, sweeping a backlog alphabetically).
+ */
+export const LANE_SORT_KEYS = [
+  'smart',
+  'title',
+  'oldest_activity',
+  'newest_activity',
+  'longest_wait',
+  'severity_desc',
+  'impact_desc',
+  'task_type',
+] as const
+export type LaneSortKey = (typeof LANE_SORT_KEYS)[number]
+
+/**
+ * How a lane's cards are divided into labelled groups.
+ *
+ * `module` is the one that replaces a structural affordance: module sub-frames no longer
+ * render as boxes on the canvas, so grouping by module is how a service's modules are seen
+ * on the board, and a module group header is a drop target for reparenting into it.
+ */
+export const LANE_GROUP_KEYS = [
+  'none',
+  'module',
+  'task_type',
+  'initiative',
+  'epic',
+  'blocking_reason',
+] as const
+export type LaneGroupKey = (typeof LANE_GROUP_KEYS)[number]
+
+/**
+ * Narrow an untrusted value to a sort/group key.
+ *
+ * Both are derived from the key lists themselves rather than hand-listed, so retiring a key
+ * cannot leave a predicate still admitting it. They exist because the reader's choice is
+ * PERSISTED in their browser: a blob written by an older build can name a key this one has
+ * dropped, and handing that to the comparator lookup would resolve `undefined` and throw
+ * while sorting — taking the whole board down over a stale preference.
+ */
+export function isLaneSortKey(value: unknown): value is LaneSortKey {
+  return (LANE_SORT_KEYS as readonly unknown[]).includes(value)
+}
+
+export function isLaneGroupKey(value: unknown): value is LaneGroupKey {
+  return (LANE_GROUP_KEYS as readonly unknown[]).includes(value)
+}
+
+/** Bug severity, ranked so `critical` sorts first. Absent severity is unknown, not `low`. */
+const SEVERITY_RANK: Record<string, number> = { critical: 3, high: 2, medium: 1, low: 0 }
+
+/**
+ * One task, plus everything the comparators and groupers need, resolved once by the caller.
+ *
+ * Assembled in the component layer (which can reach the stores) and consumed only by the
+ * pure functions below, so ordering stays unit-testable without a Pinia instance.
+ */
+export interface LaneTaskEntry {
+  readonly task: Block
+  /** Why this task is in its lane, from `classifyTask`. */
+  readonly reason: LaneReason
+  /** The task's index in its frame's block list: the stable final tiebreak. */
+  readonly order: number
+  /** Epoch ms of the run's last observed sign of life, or null when not derivable. */
+  readonly activityAt: number | null
+  /** Epoch ms the task started waiting on a human, or null when not derivable. */
+  readonly waitingSince: number | null
+  /** The module this task belongs to, by name. Null when it belongs to none. */
+  readonly moduleName: string | null
+  /** The initiative this task belongs to, by title. Null when it belongs to none. */
+  readonly initiativeName: string | null
+  /** The epic this task belongs to, by title. Null when it belongs to none. */
+  readonly epicName: string | null
+}
+
+/**
+ * The run's last observed sign of life.
+ *
+ * `lastActivityAt` is the truthful answer but is only ever stamped on CONTAINER steps by a
+ * harness new enough to send heartbeats, so it is absent for inline steps, unpolled steps
+ * and older images. `startedAt` is the next best evidence the step is moving, and the run's
+ * `createdAt` is the floor. Returns null rather than 0 when none of the three is present:
+ * see the module header on why unknown may not be spelled as a number.
+ */
+export function runActivityAt(
+  run: Pick<ExecutionInstance, 'steps' | 'createdAt'> | null,
+): number | null {
+  if (!run) return null
+  let latest: number | null = null
+  for (const step of run.steps) {
+    for (const stamp of [step.lastActivityAt, step.startedAt]) {
+      if (stamp != null && (latest == null || stamp > latest)) latest = stamp
+    }
+  }
+  return latest ?? run.createdAt ?? null
+}
+
+/**
+ * When the run started waiting on a human.
+ *
+ * `step.pausedAt` is the engine's own park clock — set once when a step parks on an
+ * approval, a raised decision or an iteration-cap gate, and cleared when it resumes — so it
+ * is exact where it exists. It is absent until a step has parked at least once, and not
+ * every park surface stamps it, which is why this returns null rather than falling back to
+ * the run's start: a run that has been ALIVE for three days has not been WAITING for three
+ * days, and conflating the two would sort a busy run to the top of the queue.
+ *
+ * The caller may supply `notificationWaitingSince` — the earliest open review-wait
+ * notification for the block, which `collectReviewDebt` already derives in contracts — as
+ * an independent second source for the parks that stamp no `pausedAt`.
+ */
+export function runWaitingSince(
+  run: Pick<ExecutionInstance, 'steps'> | null,
+  notificationWaitingSince?: number | null,
+): number | null {
+  const parked = run?.steps.reduce<number | null>((earliest, step: PipelineStep) => {
+    const at = step.pausedAt
+    if (at == null) return earliest
+    return earliest == null || at < earliest ? at : earliest
+  }, null)
+  return parked ?? notificationWaitingSince ?? null
+}
+
+/** Compare two possibly-unknown numbers, always ranking unknown last. */
+function nullsLast(a: number | null, b: number | null, cmp: (x: number, y: number) => number) {
+  if (a == null && b == null) return 0
+  if (a == null) return 1
+  if (b == null) return -1
+  return cmp(a, b)
+}
+
+const ascending = (x: number, y: number) => x - y
+const descending = (x: number, y: number) => y - x
+
+function severityRank(task: Block): number | null {
+  const severity = task.taskTypeFields?.severity
+  return severity == null ? null : (SEVERITY_RANK[severity] ?? null)
+}
+
+/**
+ * How urgently a `needs_you` task's reason reads, lowest first.
+ *
+ * `failed` and `budget_paused` lead because they are BROKEN rather than queued: no wait
+ * clock is running on them (a failure raises no review-wait card and stamps no `pausedAt`),
+ * so a pure wait-time order would file them last, behind gates that are merely patient.
+ * `unclassified` sits with them because a task the board cannot describe is the one most
+ * likely to be silently stuck.
+ */
+const NEEDS_YOU_TIER: Partial<Record<LaneReason, number>> = {
+  failed: 0,
+  budget_paused: 0,
+  unclassified: 0,
+}
+
+type Comparator = (a: LaneTaskEntry, b: LaneTaskEntry) => number
+
+const EXPLICIT_COMPARATORS: Record<Exclude<LaneSortKey, 'smart'>, Comparator> = {
+  title: (a, b) => a.task.title.localeCompare(b.task.title),
+  oldest_activity: (a, b) => nullsLast(a.activityAt, b.activityAt, ascending),
+  newest_activity: (a, b) => nullsLast(a.activityAt, b.activityAt, descending),
+  longest_wait: (a, b) => nullsLast(a.waitingSince, b.waitingSince, ascending),
+  severity_desc: (a, b) => nullsLast(severityRank(a.task), severityRank(b.task), descending),
+  impact_desc: (a, b) =>
+    nullsLast(a.task.estimate?.impact ?? null, b.task.estimate?.impact ?? null, descending),
+  task_type: (a, b) =>
+    (a.task.taskType ?? '').localeCompare(b.task.taskType ?? '') ||
+    a.task.title.localeCompare(b.task.title),
+}
+
+/**
+ * The `smart` order per lane, and why each column wants its own.
+ *
+ * - **not_started** — what can be started RIGHT NOW, so a task blocked on an unmerged
+ *   dependency sinks below one that is ready. Within each half, board order: the author's
+ *   own sequence is the best available statement of intent for work nothing has touched.
+ * - **in_progress** — quietest first. A healthy run needs nothing from anyone; the reason
+ *   to look at this column at all is to find the run that has stopped making noise.
+ * - **needs_you** — broken things first (see {@link NEEDS_YOU_TIER}), then longest wait, so
+ *   the queue is fair and the escalation the workspace already applies to a waiting
+ *   notification is reflected in the order.
+ * - **done** — newest completion first; recency is the only useful order for an archive
+ *   (and `selectDoneLaneTasks` has already sorted on it).
+ */
+export const SMART_ORDER_BY_LANE: Record<TaskLane, Comparator> = {
+  not_started: (a, b) => Number(a.reason === 'dependencies') - Number(b.reason === 'dependencies'),
+  in_progress: (a, b) => nullsLast(a.activityAt, b.activityAt, ascending),
+  needs_you: (a, b) =>
+    (NEEDS_YOU_TIER[a.reason] ?? 1) - (NEEDS_YOU_TIER[b.reason] ?? 1) ||
+    nullsLast(a.waitingSince, b.waitingSince, ascending),
+  done: (a, b) => nullsLast(a.task.completedAt ?? null, b.task.completedAt ?? null, descending),
+}
+
+/**
+ * Order a lane's entries. Non-mutating.
+ *
+ * Every key ends on `order`, so the result is fully determined and a live board event
+ * cannot make equal-ranked cards trade places.
+ */
+export function sortLaneTasks(
+  entries: readonly LaneTaskEntry[],
+  key: LaneSortKey,
+  lane: TaskLane,
+): LaneTaskEntry[] {
+  const primary = key === 'smart' ? SMART_ORDER_BY_LANE[lane] : EXPLICIT_COMPARATORS[key]
+  return [...entries].sort((a, b) => primary(a, b) || a.order - b.order)
+}
+
+/** One labelled run of cards inside a lane. */
+export interface LaneGroup {
+  /**
+   * Stable identity for the `v-for` key and, when grouping by `module`, the module BLOCK's
+   * id — which is what makes the header a drop target. Null for the catch-all group.
+   */
+  readonly id: string | null
+  /** Null ⇒ the catch-all group ("no module", "not in an initiative", …). */
+  readonly label: string | null
+  readonly entries: LaneTaskEntry[]
+}
+
+/**
+ * The value a task is grouped under, or null for the catch-all group.
+ *
+ * `module` reads the module NAME rather than the parent block id because a task declares
+ * its module (`moduleName`) long before the module block exists: the engine materialises
+ * that block lazily, on merge (`PostMergeBoardController.applyModuleAssignment`). Keying on
+ * the parent alone would leave every unmerged task in "no module" while the board shows the
+ * module it is destined for, so grouping would appear to ignore what the author wrote.
+ */
+function groupLabelOf(entry: LaneTaskEntry, key: Exclude<LaneGroupKey, 'none'>): string | null {
+  switch (key) {
+    case 'module':
+      return entry.moduleName
+    case 'task_type':
+      return entry.task.taskType ?? null
+    case 'initiative':
+      return entry.initiativeName
+    case 'epic':
+      return entry.epicName
+    case 'blocking_reason':
+      return entry.reason
+  }
+}
+
+/**
+ * Divide a lane's (already ordered) entries into groups, preserving that order both within
+ * each group and between groups: a group appears where its first member does, so the sort
+ * key still governs what a reader meets first. The catch-all group is forced last, because
+ * "everything else" reading before a named group inverts the hierarchy the grouping states.
+ *
+ * `moduleBlockIdByName` maps a module name to the block id that materialises it, so a
+ * module group header can act as a reparent drop zone. A module that has no block yet is
+ * still grouped and labelled; it simply is not a drop target.
+ */
+export function groupLaneTasks(
+  ordered: readonly LaneTaskEntry[],
+  key: LaneGroupKey,
+  moduleBlockIdByName?: ReadonlyMap<string, string>,
+): LaneGroup[] {
+  if (key === 'none') return [{ id: null, label: null, entries: [...ordered] }]
+
+  const byLabel = new Map<string, LaneTaskEntry[]>()
+  const catchAll: LaneTaskEntry[] = []
+  for (const entry of ordered) {
+    const label = groupLabelOf(entry, key)
+    if (label == null) {
+      catchAll.push(entry)
+      continue
+    }
+    const bucket = byLabel.get(label)
+    if (bucket) bucket.push(entry)
+    else byLabel.set(label, [entry])
+  }
+
+  const groups: LaneGroup[] = [...byLabel].map(([label, entries]) => ({
+    id: key === 'module' ? (moduleBlockIdByName?.get(label) ?? null) : label,
+    label,
+    entries,
+  }))
+  if (catchAll.length > 0) groups.push({ id: null, label: null, entries: catchAll })
+  return groups
+}