@cat-factory/app 0.20.0 → 0.21.0

package/app/components/board/BoardCanvas.vue

@@ -4,7 +4,9 @@ import { Background } from '@vue-flow/background'
 import { Controls } from '@vue-flow/controls'
 import { MiniMap } from '@vue-flow/minimap'
 import BlockNode from './nodes/BlockNode.vue'
+import EpicNode from './nodes/EpicNode.vue'
 import TaskDependencyEdges from './TaskDependencyEdges.vue'
+import DependencyConnectOverlay from './DependencyConnectOverlay.vue'
 import { STATUS_META } from '~/utils/catalog'
 import { readDndPayload, blockIdFromEvent } from '~/utils/dnd'
 import { BOARD_FLOW_ID } from '~/composables/useBoardFlow'
@@ -41,15 +43,24 @@ function frameExpanded(id: string) {
   return ui.isFrameExpanded(id) && ui.lod !== 'far'
 }
 
-const nodes = computed(() =>
-  board.frames.map((b) => ({
+const nodes = computed(() => [
+  ...board.frames.map((b) => ({
     id: b.id,
     type: 'block',
     position: b.position,
     draggable: !frameExpanded(b.id),
     data: {},
   })),
-)
+  // Epics are top-level grouping nodes (non-structural), drawn alongside frames and
+  // linked to their member tasks by the dependency-edge overlay.
+  ...board.epics.map((b) => ({
+    id: b.id,
+    type: 'epic',
+    position: b.position,
+    draggable: true,
+    data: {},
+  })),
+])
 
 onNodeDragStop(({ node }) => {
   board.moveBlock(node.id, { x: node.position.x, y: node.position.y })
@@ -149,6 +160,10 @@ async function onDrop(event: DragEvent) {
       <template #node-block="props">
         <BlockNode :id="props.id" />
       </template>
+
+      <template #node-epic="props">
+        <EpicNode :id="props.id" />
+      </template>
     </VueFlow>
 
     <!-- An empty board reads as broken; invite the user to add a service. The
@@ -183,5 +198,8 @@ async function onDrop(event: DragEvent) {
 
     <!-- task dependency arrows, overlaid in screen space -->
     <TaskDependencyEdges />
+
+    <!-- live preview line while drag-to-connecting a dependency -->
+    <DependencyConnectOverlay />
   </div>
 </template>

package/app/components/board/DependencyConnectOverlay.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { useDependencyConnect } from '~/composables/useDependencyConnect'
+
+// Draws the live preview line while a dependency drag-to-connect is in progress. Mounted
+// once on the board; reads the shared connect state. Fixed, full-viewport, click-through.
+const { connecting } = useDependencyConnect()
+</script>
+
+<template>
+  <svg
+    v-if="connecting"
+    class="pointer-events-none fixed inset-0 z-50 h-full w-full overflow-visible"
+  >
+    <line
+      :x1="connecting.x1"
+      :y1="connecting.y1"
+      :x2="connecting.x2"
+      :y2="connecting.y2"
+      stroke="#f59e0b"
+      :stroke-width="2"
+      stroke-dasharray="5 4"
+      stroke-opacity="0.9"
+    />
+  </svg>
+</template>

package/app/components/board/TaskDependencyEdges.vue

@@ -15,6 +15,9 @@ const svg = ref<SVGSVGElement | null>(null)
 
 type Seg = { id: string; x1: number; y1: number; x2: number; y2: number; done: boolean }
 const segments = ref<Seg[]>([])
+// Epic→member membership links (distinct style from dependency edges).
+type MemberSeg = { id: string; x1: number; y1: number; x2: number; y2: number }
+const memberSegments = ref<MemberSeg[]>([])
 
 // task → its dependencies, both ends being tasks
 const taskDeps = computed(() => {
@@ -29,6 +32,17 @@ const taskDeps = computed(() => {
   return out
 })
 
+// epic → each of its member tasks (membership, drawn as a soft violet link).
+const epicLinks = computed(() => {
+  const out: { id: string; source: string; target: string }[] = []
+  for (const e of board.epics) {
+    for (const m of board.epicMembers(e.id)) {
+      out.push({ id: `${e.id}__${m.id}`, source: e.id, target: m.id })
+    }
+  }
+  return out
+})
+
 /** Resolve a task's anchor: walk up task → module → service to the first card
  * that's actually rendered (a container may be collapsed). */
 function anchorEl(taskId: string): HTMLElement | null {
@@ -81,6 +95,23 @@ function recompute() {
     })
   }
   segments.value = next
+
+  const members: MemberSeg[] = []
+  for (const link of epicLinks.value) {
+    const a = anchorEl(link.source)
+    const b = anchorEl(link.target)
+    if (!a || !b || a === b) continue
+    const ra = a.getBoundingClientRect()
+    const rb = b.getBoundingClientRect()
+    const ax = ra.left + ra.width / 2 - origin.left
+    const ay = ra.top + ra.height / 2 - origin.top
+    const bx = rb.left + rb.width / 2 - origin.left
+    const by = rb.top + rb.height / 2 - origin.top
+    const start = border(ax, ay, ra.width / 2, ra.height / 2, bx, by)
+    const end = border(bx, by, rb.width / 2, rb.height / 2, ax, ay)
+    members.push({ id: link.id, x1: start.x, y1: start.y, x2: end.x, y2: end.y })
+  }
+  memberSegments.value = members
 }
 
 const { pause, resume } = useRafFn(recompute, { immediate: false })
@@ -115,6 +146,20 @@ onBeforeUnmount(pause)
       </marker>
     </defs>
 
+    <!-- epic → member membership links (soft violet, no arrowhead) -->
+    <line
+      v-for="s in memberSegments"
+      :key="s.id"
+      :x1="s.x1"
+      :y1="s.y1"
+      :x2="s.x2"
+      :y2="s.y2"
+      stroke="#8b5cf6"
+      :stroke-width="1.5"
+      stroke-dasharray="2 5"
+      :stroke-opacity="0.5"
+    />
+
     <line
       v-for="s in segments"
       :key="s.id"

package/app/components/board/nodes/EpicNode.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { Block } from '~/types/domain'
+
+// Vue Flow passes the node's `id` as a prop. An epic is a NON-structural grouping node:
+// it has no children of its own (tasks join it via their `epicId`), so it renders as a
+// compact card showing the epic title + a roll-up of its member tasks. The dependency-edge
+// overlay draws the links from this card to each member (anchored by `data-block-id`).
+const props = defineProps<{ id: string }>()
+
+const board = useBoardStore()
+const ui = useUiStore()
+
+const block = computed<Block | undefined>(() => board.getBlock(props.id))
+const members = computed(() => board.epicMembers(props.id))
+const total = computed(() => members.value.length)
+const done = computed(() => members.value.filter((m) => m.status === 'done').length)
+const active = computed(() =>
+  members.value.filter((m) => m.status === 'in_progress' || m.status === 'pr_ready').length,
+)
+const selected = computed(() => ui.selectedBlockId === props.id)
+</script>
+
+<template>
+  <div
+    v-if="block"
+    :data-block-id="block.id"
+    class="w-56 cursor-pointer rounded-lg border bg-slate-900/90 px-3 py-2 shadow-lg backdrop-blur transition-colors"
+    :class="
+      selected ? 'border-violet-400 ring-1 ring-violet-400/50' : 'border-violet-500/40'
+    "
+    @click="ui.select(block.id)"
+  >
+    <div class="flex items-center gap-1.5">
+      <UIcon name="i-lucide-layers" class="h-3.5 w-3.5 shrink-0 text-violet-400" />
+      <span class="text-[10px] font-semibold uppercase tracking-wide text-violet-300">Epic</span>
+      <span class="ml-auto text-[10px] text-slate-400">{{ done }}/{{ total }}</span>
+    </div>
+    <div class="mt-1 truncate text-sm font-medium text-slate-100" :title="block.title">
+      {{ block.title }}
+    </div>
+    <div class="mt-1.5 h-1 w-full overflow-hidden rounded-full bg-slate-700/60">
+      <div
+        class="h-full rounded-full bg-violet-500"
+        :style="{ width: total ? `${Math.round((done / total) * 100)}%` : '0%' }"
+      />
+    </div>
+    <div v-if="active" class="mt-1 text-[10px] text-slate-400">{{ active }} active</div>
+    <div v-else-if="total === 0" class="mt-1 text-[10px] text-slate-500">No tasks yet</div>
+  </div>
+</template>

package/app/components/board/nodes/TaskCard.vue

@@ -18,6 +18,10 @@ const task = computed<Block | undefined>(() => board.getBlock(props.taskId))
 const statusMeta = computed(() => (task.value ? STATUS_META[task.value.status] : null))
 const selected = computed(() => ui.selectedBlockId === props.taskId)
 
+// Drag-to-connect: dragging from this card's handle onto another task makes THAT task
+// depend on this one (this is the prerequisite). The composable tracks the gesture.
+const { start: startConnect } = useDependencyConnect()
+
 // ---- dependencies (gate execution order; may point across frames) ----------
 const deps = computed(() =>
   (task.value?.dependsOn ?? []).map((id) => board.getBlock(id)).filter((b): b is Block => !!b),
@@ -196,6 +200,16 @@ function selectTask() {
         :title="schedule.enabled ? 'Recurring pipeline' : 'Recurring pipeline (paused)'"
       />
       <span class="truncate text-[11px] font-semibold text-slate-100">{{ task.title }}</span>
+      <!-- drag-to-connect handle: drag onto another task to make it depend on this one -->
+      <button
+        type="button"
+        class="nodrag ml-1 shrink-0 cursor-crosshair rounded-full p-0.5 text-slate-500 hover:bg-slate-800 hover:text-amber-400"
+        title="Drag onto another task to make it depend on this one"
+        @pointerdown.stop="startConnect(task.id, $event)"
+        @click.stop
+      >
+        <UIcon name="i-lucide-spline" class="h-3 w-3" />
+      </button>
       <span
         class="ml-auto shrink-0 text-[9px] uppercase tracking-wide"
         :class="

package/app/components/panels/InspectorPanel.vue

@@ -12,6 +12,7 @@ import TaskDependencies from '~/components/panels/inspector/TaskDependencies.vue
 import TaskStructure from '~/components/panels/inspector/TaskStructure.vue'
 import TaskRunSettings from '~/components/panels/inspector/TaskRunSettings.vue'
 import TaskExecution from '~/components/panels/inspector/TaskExecution.vue'
+import EpicChildren from '~/components/panels/inspector/EpicChildren.vue'
 import RecurringScheduleSettings from '~/components/panels/inspector/RecurringScheduleSettings.vue'
 import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentStopButton from '~/components/board/AgentStopButton.vue'
@@ -51,6 +52,7 @@ const level = computed(() => block.value?.level ?? 'frame')
 const isFrame = computed(() => level.value === 'frame')
 const isContainer = computed(() => level.value === 'frame' || level.value === 'module')
 const isTask = computed(() => level.value === 'task')
+const isEpic = computed(() => level.value === 'epic')
 
 const instance = computed(() => execution.getInstance(block.value?.executionId))
 const typeMeta = computed(() => (block.value ? blockTypeMeta(block.value.type) : null))
@@ -442,6 +444,9 @@ const showOriginalDescription = ref(false)
         <TaskExecution :block="block" />
       </template>
 
+      <!-- epic: the full tree of member tasks, grouped by service → module -->
+      <EpicChildren v-else-if="isEpic" :block="block" />
+
       <!-- actions -->
       <div class="flex items-center gap-2">
         <UDropdownMenu v-if="isTask" :items="runMenu">

package/app/components/panels/inspector/EpicChildren.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { Block } from '~/types/domain'
+import { STATUS_META } from '~/utils/catalog'
+
+// The epic inspector body: the full tree of member tasks (which may live under different
+// services/modules), grouped service → module → task. Each task row selects it. Membership
+// is the task's `epicId`; the epic is non-structural, so this reads across the whole board.
+const props = defineProps<{ block: Block }>()
+
+const board = useBoardStore()
+const ui = useUiStore()
+
+const members = computed(() => board.epicMembers(props.block.id))
+const done = computed(() => members.value.filter((m) => m.status === 'done').length)
+
+/** Member tasks grouped by their owning service, then by module (or "direct"). */
+const groups = computed(() => {
+  const byService = new Map<
+    string,
+    { service: Block | undefined; modules: Map<string, { module: Block | undefined; tasks: Block[] }> }
+  >()
+  for (const task of members.value) {
+    const service = board.serviceOf(task)
+    const serviceKey = service?.id ?? '—'
+    if (!byService.has(serviceKey)) byService.set(serviceKey, { service, modules: new Map() })
+    const group = byService.get(serviceKey)!
+    // The task's structural container: a module when its parent is a module, else "direct".
+    const parent = task.parentId ? board.getBlock(task.parentId) : undefined
+    const moduleKey = parent && parent.level === 'module' ? parent.id : '—'
+    if (!group.modules.has(moduleKey)) {
+      group.modules.set(moduleKey, { module: parent?.level === 'module' ? parent : undefined, tasks: [] })
+    }
+    group.modules.get(moduleKey)!.tasks.push(task)
+  }
+  return [...byService.values()]
+})
+</script>
+
+<template>
+  <div>
+    <div class="mb-1 flex items-center justify-between">
+      <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+        Epic tasks
+      </span>
+      <span class="text-[11px] text-slate-500">{{ done }}/{{ members.length }} done</span>
+    </div>
+
+    <div v-if="members.length === 0" class="text-[11px] text-slate-500">
+      No tasks belong to this epic yet. Import an epic's children, or set a task's epic.
+    </div>
+
+    <div v-else class="space-y-2">
+      <div v-for="(group, gi) in groups" :key="gi" class="rounded-md border border-slate-700/60 p-2">
+        <div class="mb-1 flex items-center gap-1 text-[11px] font-medium text-slate-300">
+          <UIcon name="i-lucide-box" class="h-3 w-3 text-slate-500" />
+          {{ group.service?.title ?? 'Unassigned' }}
+        </div>
+        <div v-for="(mod, mi) in [...group.modules.values()]" :key="mi" class="pl-1">
+          <div v-if="mod.module" class="text-[10px] uppercase tracking-wide text-slate-500">
+            {{ mod.module.title }}
+          </div>
+          <button
+            v-for="task in mod.tasks"
+            :key="task.id"
+            type="button"
+            class="flex w-full items-center gap-1.5 rounded px-1 py-0.5 text-left text-xs text-slate-200 hover:bg-slate-800"
+            @click="ui.select(task.id)"
+          >
+            <span
+              class="h-2 w-2 shrink-0 rounded-full"
+              :style="{ backgroundColor: STATUS_META[task.status].color }"
+            />
+            <span class="truncate">{{ task.title }}</span>
+            <span class="ml-auto shrink-0 text-[10px] text-slate-500">
+              {{ STATUS_META[task.status].label }}
+            </span>
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -45,6 +45,13 @@ function setResponsible(userId: string) {
   board.updateBlock(props.block.id, { responsibleProductUserId: userId })
 }
 
+// ---- auto-start dependents -------------------------------------------------
+// Preceding-task toggle: when this task merges, the engine auto-starts the tasks that
+// depend on it (skipping any on an individual-usage model, which can't unlock unattended).
+function setAutoStartDependents(value: boolean) {
+  board.updateBlock(props.block.id, { autoStartDependents: value })
+}
+
 // ---- merge policy preset ---------------------------------------------------
 // Which merge threshold preset governs this task's auto-merge decision + CI-fixer
 // budget. None selected → the workspace default preset. (The old confidence-based
@@ -365,5 +372,23 @@ const resolveOnMergeLabel = computed(() =>
         Unassigned — set a product owner to notify them when requirement review flags this task.
       </div>
     </div>
+
+    <!-- auto-start dependents: when this task merges, start the tasks that depend on it -->
+    <div>
+      <div class="flex items-center justify-between gap-2">
+        <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+          Auto-start dependents
+        </span>
+        <USwitch
+          size="sm"
+          :model-value="block.autoStartDependents ?? false"
+          @update:model-value="setAutoStartDependents"
+        />
+      </div>
+      <div class="mt-1 text-[11px] text-slate-500">
+        When this task merges, automatically start the tasks that depend on it (once their
+        other dependencies are also done).
+      </div>
+    </div>
   </div>
 </template>

package/app/components/tasks/TaskImportModal.vue

@@ -162,6 +162,35 @@ async function doImport() {
     importing.value = false
   }
 }
+
+// Spawn the referenced issue as an EPIC: an epic node + a task per child issue (into the
+// chosen container), with dependency edges seeded from the issues' blocked-by/depends-on
+// links. Needs a container for the child tasks.
+async function doSpawnEpic() {
+  const value = ref_.value.trim()
+  if (!value || !source.value || !containerId.value) return
+  importing.value = true
+  try {
+    const { epic, tasks: spawned } = await tasks.spawnEpic(source.value, value, containerId.value)
+    ref_.value = ''
+    ui.closeTaskImport()
+    ui.select(epic.id)
+    toast.add({
+      title: `Spawned epic "${epic.title}"`,
+      description: `${spawned.length} child task(s) created`,
+      icon: 'i-lucide-layers',
+    })
+  } catch (e) {
+    toast.add({
+      title: 'Could not spawn epic',
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    importing.value = false
+  }
+}
 </script>
 
 <template>
@@ -209,8 +238,38 @@ async function doImport() {
           >
             Import
           </UButton>
+          <UButton
+            color="primary"
+            variant="soft"
+            icon="i-lucide-layers"
+            :loading="importing"
+            :disabled="!ref_.trim() || !containerId"
+            :title="
+              containerId
+                ? 'Spawn this epic + its children as a linked task group'
+                : 'Pick a container for the child tasks first'
+            "
+            @click="doSpawnEpic"
+          >
+            As epic
+          </UButton>
         </div>
 
+        <!-- Container for epic children when spawning from a pasted ref (the shared
+             "Create tasks in" selector below covers the search-results case). -->
+        <UFormField
+          v-if="containerItems.length && !freshHits.length && !sourceTasks.length"
+          label="Epic children container"
+          class="w-72"
+        >
+          <USelect
+            v-model="containerId"
+            :items="containerItems"
+            placeholder="Pick a frame or module"
+            class="w-full"
+          />
+        </UFormField>
+
         <!-- Browse: search the tracker by title so an issue can be turned into a
              task without knowing its key. -->
         <UFormField v-if="searchable" label="Search issues">

package/app/composables/api/board.ts

@@ -51,6 +51,16 @@ export function boardApi({ http, ws }: ApiContext) {
       body: { name: string; position?: Position },
     ) => http<Block>(`${ws(workspaceId)}/blocks/${blockId}/modules`, { method: 'POST', body }),
 
+    // Create an epic grouping node (optionally placed under a service/module).
+    addEpic: (
+      workspaceId: string,
+      body: { title: string; description?: string; position: Position; parentId?: string },
+    ) => http<Block>(`${ws(workspaceId)}/epics`, { method: 'POST', body }),
+
+    // Assign a task to an epic, or detach it (epicId: null).
+    assignToEpic: (workspaceId: string, blockId: string, body: { epicId: string | null }) =>
+      http<Block>(`${ws(workspaceId)}/blocks/${blockId}/epic`, { method: 'POST', body }),
+
     updateBlock: (workspaceId: string, blockId: string, body: Partial<Block>) =>
       http<Block>(`${ws(workspaceId)}/blocks/${blockId}`, { method: 'PATCH', body }),
 

package/app/composables/api/tasks.ts

@@ -82,6 +82,18 @@ export function tasksApi({ http, ws }: ApiContext) {
         body,
       }),
 
+    // Spawn an epic + its children as an epic node + child tasks, with dependency edges
+    // seeded from the issues' blocked-by/depends-on links.
+    spawnEpic: (
+      workspaceId: string,
+      source: TaskSourceKind,
+      body: { ref: string; containerId: string; position?: { x: number; y: number } },
+    ) =>
+      http<{ epic: Block; tasks: Block[] }>(
+        `${ws(workspaceId)}/task-sources/${source}/epics/spawn`,
+        { method: 'POST', body },
+      ),
+
     // ---- issue-tracker selection (workspace-level) ------------------------
     getTrackerSettings: (workspaceId: string) =>
       http<TrackerSettings>(`${ws(workspaceId)}/tracker-settings`),

package/app/composables/useBlockQueries.ts

@@ -56,6 +56,19 @@ export function useBlockQueries(blocks: Ref<Block[]>) {
   /** All tasks across every service (used for the dependency picker). */
   const allTasks = computed(() => blocks.value.filter((b) => b.level === 'task'))
 
+  /** Epic grouping nodes (non-structural; group tasks via their `epicId`). */
+  const epics = computed(() => blocks.value.filter((b) => b.level === 'epic'))
+
+  /** The tasks that belong to an epic (anywhere on the board) via their `epicId`. */
+  function epicMembers(epicId: string): Block[] {
+    return blocks.value.filter((b) => b.epicId === epicId)
+  }
+
+  /** The epic a task belongs to, if any. */
+  function epicOf(task: Block): Block | undefined {
+    return task.epicId ? getBlock(task.epicId) : undefined
+  }
+
   /** A task's dependencies that are not yet merged (i.e. block it from running). */
   function unmetDeps(taskId: string) {
     const t = getBlock(taskId)
@@ -139,6 +152,9 @@ export function useBlockQueries(blocks: Ref<Block[]>) {
     getBlock,
     frames,
     allTasks,
+    epics,
+    epicMembers,
+    epicOf,
     childrenOf,
     tasksOf,
     modulesOf,

package/app/composables/useDependencyConnect.ts

@@ -0,0 +1,61 @@
+import { ref } from 'vue'
+
+/**
+ * Drag-to-connect for board dependencies. A small connector handle on a task card calls
+ * {@link start} on pointerdown; we then track the pointer (a live preview line drawn by
+ * `DependencyConnectOverlay`) and, on release over another task card, create the edge
+ * "dropped-on dependsOn dragged-from" — i.e. you drag from the prerequisite onto the task
+ * that should wait for it. Module-level state so the handle and the overlay share one drag.
+ *
+ * Coordinates are client (screen) space, so the overlay is a fixed full-viewport SVG and
+ * the gesture follows pan/zoom for free (the cards move under the cursor, the line tracks
+ * the cursor). Target resolution uses `elementFromPoint` → nearest `[data-block-id]`.
+ */
+export interface ConnectState {
+  sourceId: string
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+}
+
+const connecting = ref<ConnectState | null>(null)
+
+export function useDependencyConnect() {
+  const board = useBoardStore()
+
+  function onMove(ev: PointerEvent) {
+    if (!connecting.value) return
+    connecting.value.x2 = ev.clientX
+    connecting.value.y2 = ev.clientY
+  }
+
+  async function onUp(ev: PointerEvent) {
+    const state = connecting.value
+    window.removeEventListener('pointermove', onMove)
+    window.removeEventListener('pointerup', onUp)
+    connecting.value = null
+    if (!state) return
+    // Resolve the task under the cursor on release.
+    const el = document.elementFromPoint(ev.clientX, ev.clientY)
+    const card = el?.closest('[data-block-id]') as HTMLElement | null
+    const targetId = card?.getAttribute('data-block-id') ?? null
+    if (!targetId || targetId === state.sourceId) return
+    const target = board.getBlock(targetId)
+    const source = board.getBlock(state.sourceId)
+    if (!target || target.level !== 'task' || !source || source.level !== 'task') return
+    // Dropped-on task depends on the dragged-from (prerequisite) task.
+    await board.toggleDependency(targetId, state.sourceId)
+  }
+
+  /** Begin a connect drag from `sourceId`'s handle. */
+  function start(sourceId: string, ev: PointerEvent) {
+    ev.preventDefault()
+    ev.stopPropagation()
+    connecting.value = { sourceId, x1: ev.clientX, y1: ev.clientY, x2: ev.clientX, y2: ev.clientY }
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', onUp)
+  }
+
+  return { connecting, start }
+}

package/app/stores/board.ts

@@ -15,8 +15,8 @@ import { useBlockQueries } from '~/composables/useBlockQueries'
 interface RemovalSnapshot {
   /** The removed block + all its descendants, in their original order. */
   removed: Block[]
-  /** Survivors whose `dependsOn` lost an edge to a removed block (originals to restore). */
-  edges: { id: string; dependsOn: string[] }[]
+  /** Survivors whose `dependsOn`/`epicId` lost an edge to a removed block (originals to restore). */
+  edges: { id: string; dependsOn: string[]; epicId: string | null }[]
 }
 
 export const useBoardStore = defineStore('board', () => {
@@ -97,6 +97,44 @@ export const useBoardStore = defineStore('board', () => {
     return block
   }
 
+  /**
+   * Add an epic grouping node. Epics are non-structural: they group tasks via the tasks'
+   * `epicId`, so this just drops a new `epic`-level block on the board.
+   */
+  async function addEpic(
+    title: string,
+    position: { x: number; y: number },
+    options?: { description?: string; parentId?: string },
+  ): Promise<Block> {
+    const block = await api.addEpic(useWorkspaceStore().requireId(), {
+      title,
+      position,
+      ...(options?.description ? { description: options.description } : {}),
+      ...(options?.parentId ? { parentId: options.parentId } : {}),
+    })
+    upsert(block)
+    return block
+  }
+
+  /** Assign a task to an epic, or detach it (epicId: null). */
+  async function assignToEpic(taskId: string, epicId: string | null) {
+    const t = getBlock(taskId)
+    if (!t) return
+    const prev = t.epicId ?? null
+    t.epicId = epicId // optimistic
+    try {
+      upsert(await api.assignToEpic(useWorkspaceStore().requireId(), taskId, { epicId }))
+    } catch (e) {
+      t.epicId = prev
+      toast.add({
+        title: 'Could not change epic',
+        description: e instanceof Error ? e.message : String(e),
+        icon: 'i-lucide-triangle-alert',
+        color: 'error',
+      })
+    }
+  }
+
   /** Add a module (sub-frame) inside a service. */
   async function addModule(
     serviceId: string,
@@ -171,15 +209,22 @@ export const useBoardStore = defineStore('board', () => {
       }
     }
     const removed = blocks.value.filter((b) => doomed.has(b.id))
-    // Survivors that pointed at a doomed block lose that edge — snapshot the originals.
+    // Survivors that pointed at a doomed block (dependency edge or epic membership) lose
+    // that link — snapshot the originals so a failed delete restores them faithfully.
     const edges = blocks.value
-      .filter((b) => !doomed.has(b.id) && b.dependsOn.some((d) => doomed.has(d)))
-      .map((b) => ({ id: b.id, dependsOn: [...b.dependsOn] }))
+      .filter(
+        (b) =>
+          !doomed.has(b.id) &&
+          (b.dependsOn.some((d) => doomed.has(d)) || (b.epicId != null && doomed.has(b.epicId))),
+      )
+      .map((b) => ({ id: b.id, dependsOn: [...b.dependsOn], epicId: b.epicId ?? null }))
     blocks.value = blocks.value.filter((b) => !doomed.has(b.id))
     for (const b of blocks.value) {
       if (b.dependsOn.some((d) => doomed.has(d))) {
         b.dependsOn = b.dependsOn.filter((d) => !doomed.has(d))
       }
+      // A member of a deleted epic loses its membership (the task itself survives).
+      if (b.epicId != null && doomed.has(b.epicId)) b.epicId = null
     }
     return { removed, edges }
   }
@@ -189,7 +234,10 @@ export const useBoardStore = defineStore('board', () => {
     for (const b of snap.removed) if (!getBlock(b.id)) blocks.value.push(b)
     for (const e of snap.edges) {
       const b = getBlock(e.id)
-      if (b) b.dependsOn = e.dependsOn
+      if (b) {
+        b.dependsOn = e.dependsOn
+        b.epicId = e.epicId
+      }
     }
   }
 
@@ -252,10 +300,23 @@ export const useBoardStore = defineStore('board', () => {
     upsert(await api.updateBlock(useWorkspaceStore().requireId(), id, patch))
   }
 
-  /** Toggle a dependency edge target -> source (target dependsOn source). */
+  /**
+   * Toggle a dependency edge target -> source (target dependsOn source). The backend
+   * rejects an edge that would close a cycle (422) — surface that as a toast rather than
+   * letting it throw unhandled out of a board gesture.
+   */
   async function toggleDependency(targetId: string, sourceId: string) {
     if (targetId === sourceId || !getBlock(targetId)) return
-    upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
+    try {
+      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
+    } catch (e) {
+      toast.add({
+        title: 'Could not link tasks',
+        description: e instanceof Error ? e.message : String(e),
+        icon: 'i-lucide-triangle-alert',
+        color: 'error',
+      })
+    }
   }
 
   /** Remove a dependency edge target -> source if it exists. */
@@ -275,6 +336,8 @@ export const useBoardStore = defineStore('board', () => {
     addServiceFromRepo,
     addTask,
     addModule,
+    addEpic,
+    assignToEpic,
     reparentBlock,
     detach,
     reattach,

package/app/stores/tasks.ts

@@ -9,6 +9,7 @@ import type {
   TaskSourceState,
 } from '~/types/domain'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { useBoardStore } from '~/stores/board'
 
 /**
  * Task-source integration state: the trackers the backend offers (and their
@@ -210,6 +211,29 @@ export const useTasksStore = defineStore('tasks', () => {
     return result
   }
 
+  /**
+   * Spawn an epic and its children onto the board: an epic node + a task per child issue
+   * (joined to the epic), with dependency edges seeded from the issues' links. Upserts the
+   * created blocks so the board reflects them immediately (the stream also re-broadcasts).
+   */
+  async function spawnEpic(
+    source: TaskSourceKind,
+    ref: string,
+    containerId: string,
+    position?: { x: number; y: number },
+  ) {
+    const board = useBoardStore()
+    const result = await api.spawnEpic(workspace.requireId(), source, {
+      ref,
+      containerId,
+      ...(position ? { position } : {}),
+    })
+    board.upsert(result.epic)
+    for (const t of result.tasks) board.upsert(t)
+    await loadTasks().catch(() => {})
+    return result
+  }
+
   return {
     available,
     probeError,
@@ -237,5 +261,6 @@ export const useTasksStore = defineStore('tasks', () => {
     search,
     linkToBlock,
     createTaskFromIssue,
+    spawnEpic,
   }
 })

package/app/types/domain.ts

@@ -59,8 +59,11 @@ export type BlockType =
  *  - `module`  a sub-frame inside a service; created when a task assigned to a
  *              not-yet-existing module is implemented (tasks can also be dragged in)
  *  - `task`    a draggable unit of work living inside a service or a module
+ *  - `epic`    a NON-structural grouping node: it groups tasks (which keep their own
+ *              service/module parent) via their `epicId`, and is drawn linked to them.
+ *              Never a container — nothing is reparented into an epic.
  */
-export type BlockLevel = 'frame' | 'module' | 'task'
+export type BlockLevel = 'frame' | 'module' | 'task' | 'epic'
 
 /**
  * The kind of work a task represents, chosen at creation. Drives the card's badge/icon
@@ -109,6 +112,16 @@ export interface Block {
   level: BlockLevel
   /** parent container: service or module for a task, service for a module. */
   parentId: string | null
+  /**
+   * task-only: membership link to an `epic`-level block, independent of `parentId`.
+   * Set when the task belongs to an epic (drawn linked to it); absent/null otherwise.
+   */
+  epicId?: string | null
+  /**
+   * task-only: when this task merges, automatically start the tasks that depend on it
+   * (and whose other dependencies are also done). Off/absent ⇒ dependents wait.
+   */
+  autoStartDependents?: boolean
   /** task-only: 0..1 confidence produced when the pipeline finishes. */
   confidence?: number
   /** task-only: the task-estimator's triage (complexity/risk/impact); absent until it runs. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",