@proletariat/cli 0.3.36 → 0.3.41

package/dist/lib/mcp/tools/tmux.js

@@ -0,0 +1,182 @@
+/**
+ * MCP Tmux Tools
+ *
+ * Provides tmux interaction tools for AI agents to drive interactive CLI sessions.
+ * Used by the explore-cli action to perform exploratory QA testing.
+ *
+ * Tools:
+ * - tmux_send_keys: Send keystrokes to a tmux session
+ * - tmux_capture_pane: Capture current terminal screen from a tmux session
+ * - tmux_start_session: Start a new tmux session with an optional command
+ * - tmux_list_sessions: List active tmux sessions
+ * - tmux_kill_session: Kill a tmux session
+ */
+import { z } from 'zod';
+import { execFileSync } from 'node:child_process';
+import { errorResponse, strictTool, successResponse } from '../helpers.js';
+const TMUX_ENV = { ...process.env, TERM: process.env.TERM || 'xterm-256color' };
+/**
+ * Execute a tmux command with args passed as an array (no shell interpretation).
+ */
+function runTmux(args, timeoutMs = 10_000) {
+    return execFileSync('tmux', args, {
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        env: TMUX_ENV,
+    }).trim();
+}
+/** Validate session name — alphanumeric, hyphens, underscores, dots only. */
+function validateSessionName(name) {
+    if (!/^[a-zA-Z0-9_.-]+$/.test(name)) {
+        throw new Error(`Invalid session name: "${name}". Only alphanumeric, hyphens, underscores, and dots allowed.`);
+    }
+}
+/**
+ * Check if a tmux session exists.
+ */
+function sessionExists(sessionName) {
+    try {
+        runTmux(['has-session', '-t', sessionName]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function registerTmuxTools(server, _ctx) {
+    // ── tmux_send_keys ───────────────────────────────────────────────────
+    strictTool(server, 'tmux_send_keys', 'Send keystrokes to a tmux session. Supports text input and special keys like Enter, Escape, Up, Down, Left, Right, C-c (Ctrl+C), Tab, BSpace, etc. Use this to interact with interactive CLI menus and prompts.', {
+        session: z.string().describe('Tmux session name to send keys to'),
+        keys: z.string().describe('Keys to send. Text is sent literally; special keys: Enter, Escape, Up, Down, Left, Right, C-c, C-d, Tab, BSpace, Space, Home, End, PPage, NPage'),
+        literal: z.boolean().optional().describe('If true, send keys as literal text (disables special key lookup). Default false.'),
+        delay_ms: z.number().optional().describe('Milliseconds to wait after sending keys before returning (default 100). Useful to let the UI render.'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (!sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session not found: ${params.session}`));
+            }
+            const args = ['send-keys', '-t', params.session];
+            if (params.literal)
+                args.push('-l');
+            args.push(params.keys);
+            runTmux(args);
+            // Wait for UI to render
+            const delay = Math.min(params.delay_ms ?? 100, 30_000);
+            if (delay > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            return successResponse({ sent: params.keys, session: params.session });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_capture_pane ────────────────────────────────────────────────
+    strictTool(server, 'tmux_capture_pane', 'Capture the current visible content of a tmux pane. Returns the terminal screen text, useful for reading CLI output, menu states, error messages, and interactive prompt displays.', {
+        session: z.string().describe('Tmux session name to capture from'),
+        start_line: z.number().optional().describe('Start line for capture (negative = scrollback). Default: beginning of visible pane.'),
+        end_line: z.number().optional().describe('End line for capture. Default: end of visible pane.'),
+        escape_sequences: z.boolean().optional().describe('If true, include ANSI escape sequences in output. Default false (plain text).'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (!sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session not found: ${params.session}`));
+            }
+            const args = ['capture-pane', '-t', params.session, '-p'];
+            if (params.escape_sequences)
+                args.push('-e');
+            if (params.start_line !== undefined)
+                args.push('-S', String(params.start_line));
+            if (params.end_line !== undefined)
+                args.push('-E', String(params.end_line));
+            const content = runTmux(args);
+            return successResponse({
+                session: params.session,
+                content,
+                lines: content.split('\n').length,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_start_session ───────────────────────────────────────────────
+    strictTool(server, 'tmux_start_session', 'Start a new tmux session, optionally running a command inside it. Use this to launch a CLI session for exploratory testing.', {
+        session: z.string().describe('Name for the new tmux session'),
+        command: z.string().optional().describe('Command to run in the session (e.g., "prlt" to launch the CLI)'),
+        width: z.number().optional().describe('Terminal width in columns (default 120)'),
+        height: z.number().optional().describe('Terminal height in rows (default 40)'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session already exists: ${params.session}`));
+            }
+            const width = params.width ?? 120;
+            const height = params.height ?? 40;
+            const args = ['new-session', '-d', '-s', params.session, '-x', String(width), '-y', String(height)];
+            if (params.command)
+                args.push(params.command);
+            runTmux(args);
+            // Give the session a moment to initialize
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            return successResponse({
+                session: params.session,
+                width,
+                height,
+                command: params.command || '(default shell)',
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_list_sessions ───────────────────────────────────────────────
+    strictTool(server, 'tmux_list_sessions', 'List all active tmux sessions with their status and dimensions.', {}, async () => {
+        try {
+            let output;
+            try {
+                output = runTmux(['list-sessions', '-F', '#{session_name}|#{session_width}|#{session_height}|#{session_windows}|#{session_created}']);
+            }
+            catch {
+                // No sessions running
+                return successResponse({ sessions: [] });
+            }
+            const sessions = output.split('\n').filter(Boolean).map((line) => {
+                const [name, width, height, windows, created] = line.split('|');
+                return {
+                    name,
+                    width: parseInt(width, 10),
+                    height: parseInt(height, 10),
+                    windows: parseInt(windows, 10),
+                    created: new Date(parseInt(created, 10) * 1000).toISOString(),
+                };
+            });
+            return successResponse({ sessions });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_kill_session ────────────────────────────────────────────────
+    strictTool(server, 'tmux_kill_session', 'Kill (terminate) a tmux session and all processes running in it.', {
+        session: z.string().describe('Name of the tmux session to kill'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (!sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session not found: ${params.session}`));
+            }
+            runTmux(['kill-session', '-t', params.session]);
+            return successResponse({
+                killed: params.session,
+                message: `Session "${params.session}" terminated`,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+}

package/dist/lib/mcp/tools/work.js

@@ -219,4 +219,56 @@ export function registerWorkTools(server, ctx) {
             return errorResponse(error);
         }
     });
+    strictTool(server, 'work_spawn', 'Spawn work on a ticket using the full CLI pipeline (agent selection, Docker build, container creation, branch setup, tmux session). Shells out to "prlt work spawn" — works whenever prlt is installed, no workspace context needed in-process.', {
+        ticket_id: z.string().describe('Ticket ID to spawn work for'),
+        action: z.string().optional().describe('Action to perform (e.g., implement, groom, review, custom). Defaults to implement.'),
+        display_mode: z.enum(['terminal', 'background']).optional().describe('Display mode (default: background)'),
+        skip_permissions: z.boolean().optional().describe('Skip permission prompts — danger mode (default: false)'),
+        create_pr: z.boolean().optional().describe('Create PR when work is ready (default: false)'),
+        agent: z.string().optional().describe('Agent name to use (default: ephemeral agent created on-demand)'),
+        environment: z.enum(['devcontainer', 'host']).optional().describe('Execution environment (default: devcontainer if available)'),
+    }, async (params) => {
+        try {
+            // Build the prlt work spawn command
+            const args = [params.ticket_id];
+            // Add flags
+            if (params.action) {
+                args.push('--action', params.action);
+            }
+            if (params.display_mode) {
+                args.push('--display', params.display_mode);
+            }
+            else {
+                args.push('--display', 'background');
+            }
+            if (params.skip_permissions) {
+                args.push('--skip-permissions');
+            }
+            if (params.create_pr) {
+                args.push('--create-pr');
+            }
+            if (params.environment === 'host') {
+                args.push('--run-on-host');
+            }
+            // Always skip confirmation in MCP context
+            args.push('--yes');
+            const cmd = `prlt work spawn ${args.join(' ')}`;
+            const output = ctx.runCommand(cmd);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            ticketId: params.ticket_id,
+                            command: cmd,
+                            output,
+                            message: `Spawned work for ${params.ticket_id} via CLI pipeline`,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
 }

package/dist/lib/pmo/schema.d.ts

@@ -66,7 +66,7 @@ export declare const PMO_TABLE_SCHEMAS: {
     readonly project_specs: "\n    CREATE TABLE IF NOT EXISTS pmo_project_specs (\n      project_id TEXT NOT NULL REFERENCES pmo_projects(id) ON DELETE CASCADE,\n      spec_id TEXT NOT NULL REFERENCES pmo_specs(id) ON DELETE CASCADE,\n      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      PRIMARY KEY (project_id, spec_id)\n    )";
     readonly cache_metadata: "\n    CREATE TABLE IF NOT EXISTS pmo_cache_metadata (\n      key TEXT PRIMARY KEY,\n      value TEXT NOT NULL\n    )";
     readonly settings: "\n    CREATE TABLE IF NOT EXISTS pmo_settings (\n      key TEXT PRIMARY KEY,\n      value TEXT NOT NULL\n    )";
-    readonly agent_work: "\n    CREATE TABLE IF NOT EXISTS agent_work (\n      id TEXT PRIMARY KEY,\n      ticket_id TEXT NOT NULL,\n      agent_name TEXT NOT NULL,\n      executor TEXT NOT NULL,\n      environment TEXT NOT NULL DEFAULT 'host',\n      display_mode TEXT NOT NULL DEFAULT 'terminal',\n      sandboxed INTEGER NOT NULL DEFAULT 0,\n      status TEXT NOT NULL DEFAULT 'starting',\n      branch TEXT,\n      pid TEXT,\n      container_id TEXT,\n      session_id TEXT,\n      host TEXT,\n      log_path TEXT,\n      started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      completed_at TIMESTAMP,\n      exit_code INTEGER,\n      FOREIGN KEY (ticket_id) REFERENCES pmo_tickets(id) ON DELETE CASCADE\n    )";
+    readonly agent_work: "\n    CREATE TABLE IF NOT EXISTS agent_work (\n      id TEXT PRIMARY KEY,\n      ticket_id TEXT NOT NULL,\n      agent_name TEXT NOT NULL,\n      executor TEXT NOT NULL,\n      environment TEXT NOT NULL DEFAULT 'host',\n      display_mode TEXT NOT NULL DEFAULT 'terminal',\n      sandboxed INTEGER NOT NULL DEFAULT 0,\n      status TEXT NOT NULL DEFAULT 'starting',\n      branch TEXT,\n      pid TEXT,\n      container_id TEXT,\n      session_id TEXT,\n      host TEXT,\n      log_path TEXT,\n      started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      completed_at TIMESTAMP,\n      exit_code INTEGER,\n      error_message TEXT,\n      FOREIGN KEY (ticket_id) REFERENCES pmo_tickets(id) ON DELETE CASCADE\n    )";
     readonly containers: "\n    CREATE TABLE IF NOT EXISTS containers (\n      id TEXT PRIMARY KEY,\n      agent_name TEXT NOT NULL,\n      docker_id TEXT NOT NULL,\n      docker_name TEXT,\n      image TEXT,\n      status TEXT NOT NULL DEFAULT 'unknown',\n      current_execution_id TEXT,\n      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      last_seen_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      FOREIGN KEY (agent_name) REFERENCES agents(name) ON DELETE CASCADE,\n      FOREIGN KEY (current_execution_id) REFERENCES agent_work(id) ON DELETE SET NULL\n    )";
     readonly id_sequences: "\n    CREATE TABLE IF NOT EXISTS id_sequences (\n      table_name TEXT PRIMARY KEY,\n      next_id INTEGER NOT NULL DEFAULT 1\n    )";
     readonly statuses: "\n    CREATE TABLE IF NOT EXISTS pmo_statuses (\n      id TEXT PRIMARY KEY,\n      project_id TEXT NOT NULL,\n      name TEXT NOT NULL,\n      category TEXT NOT NULL,\n      position INTEGER NOT NULL DEFAULT 0,\n      color TEXT,\n      description TEXT,\n      is_default INTEGER NOT NULL DEFAULT 0,\n      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      FOREIGN KEY (project_id) REFERENCES pmo_projects(id) ON DELETE CASCADE,\n      UNIQUE(project_id, name)\n    )";

package/dist/lib/pmo/schema.js

@@ -337,6 +337,7 @@ export const PMO_TABLE_SCHEMAS = {
       started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       completed_at TIMESTAMP,
       exit_code INTEGER,
+      error_message TEXT,
       FOREIGN KEY (ticket_id) REFERENCES ${PMO_TABLES.tickets}(id) ON DELETE CASCADE
     )`,
     // Docker containers (per-agent, reused across executions)

package/dist/lib/pmo/storage/base.js

@@ -178,6 +178,39 @@ export function runMigrations(db) {
             }
         }
     }
+    // Migration: Migrate old ticket_dependencies schema (blocked_by_ticket_id) to new format
+    if (tableExists(T.ticket_dependencies)) {
+        const depsColumns = db.pragma(`table_info(${T.ticket_dependencies})`);
+        const depsColumnNames = new Set(depsColumns.map(c => c.name));
+        if (depsColumnNames.has('blocked_by_ticket_id') && !depsColumnNames.has('depends_on_ticket_id')) {
+            // Old schema detected - migrate to new format
+            try {
+                // Create new table with correct schema
+                db.exec(`
+          CREATE TABLE pmo_ticket_dependencies_new (
+            ticket_id TEXT NOT NULL REFERENCES ${T.tickets}(id) ON DELETE RESTRICT,
+            depends_on_ticket_id TEXT NOT NULL REFERENCES ${T.tickets}(id) ON DELETE RESTRICT,
+            dependency_type TEXT NOT NULL DEFAULT 'blocks' CHECK (dependency_type IN ('blocks', 'relates_to', 'duplicates')),
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (ticket_id, depends_on_ticket_id, dependency_type),
+            CHECK (ticket_id != depends_on_ticket_id)
+          )
+        `);
+                // Copy existing blocking relationships (old schema: ticket_id is blocked by blocked_by_ticket_id)
+                db.exec(`
+          INSERT OR IGNORE INTO pmo_ticket_dependencies_new (ticket_id, depends_on_ticket_id, dependency_type, created_at)
+          SELECT ticket_id, blocked_by_ticket_id, 'blocks', created_at
+          FROM ${T.ticket_dependencies}
+        `);
+                // Replace old table with new one
+                db.exec(`DROP TABLE ${T.ticket_dependencies}`);
+                db.exec(`ALTER TABLE pmo_ticket_dependencies_new RENAME TO ${T.ticket_dependencies}`);
+            }
+            catch {
+                // Migration may have already been applied partially
+            }
+        }
+    }
     // Migration: Convert legacy priority values (URGENT/HIGH/MEDIUM/LOW) to P0-P3
     if (tableExists(T.tickets)) {
         try {
@@ -252,6 +285,19 @@ export function runMigrations(db) {
             // Column may already exist
         }
     }
+    // Migration: Add error_message column to agent_work table (TKT-1082)
+    if (tableExists(T.agent_work)) {
+        const agentWorkColumns = db.pragma(`table_info(${T.agent_work})`);
+        const agentWorkColumnNames = new Set(agentWorkColumns.map(c => c.name));
+        if (!agentWorkColumnNames.has('error_message')) {
+            try {
+                db.exec(`ALTER TABLE ${T.agent_work} ADD COLUMN error_message TEXT`);
+            }
+            catch {
+                // Column may already exist
+            }
+        }
+    }
     // Migration: Reassign orphaned tickets (TKT-940)
     // Tickets with project_id that doesn't match any existing project are "orphaned".
     // This can happen when a 'default' project never existed or was deleted.
@@ -887,6 +933,167 @@ The PR will be updated automatically with your pushed changes.`,
             modifiesCode: true,
             position: 6,
         },
+        {
+            id: 'explore-cli',
+            name: 'Explore CLI',
+            description: 'AI QA agent that autonomously explores the interactive CLI to discover bugs',
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Explore CLI (Autonomous QA)
+
+You are an AI QA tester for the prlt CLI. You have access to a tmux session where the CLI is running.
+Your job is to **systematically explore every menu, try every option, and find bugs**.
+
+## Your Tools
+
+- **tmux_send_keys** — send keystrokes to the tmux session (typing, arrows, Enter, Escape, Ctrl+C, etc.)
+- **tmux_capture_pane** — read the current terminal screen to see what's displayed
+- **tmux_start_session** — start a new tmux session to run the CLI in
+- **tmux_list_sessions** — list active tmux sessions
+- **ticket_create** — file a bug ticket when you find something broken
+
+## Getting Started
+
+1. Start a tmux session for testing:
+   \`\`\`
+   tmux_start_session({ session: "qa-test", command: "prlt" })
+   \`\`\`
+2. Wait a moment, then capture the screen to see the main menu:
+   \`\`\`
+   tmux_capture_pane({ session: "qa-test" })
+   \`\`\`
+3. Begin systematic exploration.
+
+## Exploration Strategies
+
+Work through these systematically. After each action, always capture the screen to see the result.
+
+### 1. Navigate Every Top-Level Menu Item
+- Use arrow keys (Up/Down) to highlight each option
+- Press Enter to select each one
+- Capture the screen to see what happens
+- Press Escape or Ctrl+C to go back
+
+### 2. Test Every Submenu Option
+- For each menu item, explore all sub-options
+- Try selecting each choice in every list/menu
+
+### 3. Test Input Handling
+- **Valid inputs**: Normal expected values
+- **Empty inputs**: Just press Enter without typing anything
+- **Invalid inputs**: Random strings, numbers where text is expected, etc.
+- **Long strings**: Very long ticket titles, descriptions (100+ characters)
+- **Special characters**: Quotes, backslashes, Unicode (emojis, CJK characters)
+- **SQL injection-like**: \`'; DROP TABLE --\` style strings
+- **Boundary values**: 0, -1, 999999, etc. for numeric inputs
+
+### 4. Test Cancellation Flows
+- Press Ctrl+C mid-flow (should exit gracefully, no crash)
+- Press Escape in menus (should go back)
+- Press q or Q in menus (common quit shortcut)
+- Rapidly press Escape multiple times
+
+### 5. Test Navigation Edge Cases
+- Rapid arrow key presses (Up Up Up Down Down Down)
+- Arrow keys at the top/bottom of lists (should not crash)
+- Tab key in various contexts
+- Home/End keys
+
+### 6. Test Error Recovery
+- Navigate to ticket operations without any tickets
+- Try to create items with duplicate names
+- Try operations on non-existent IDs
+
+## What to Look For
+
+- **Crashes**: Unhandled exceptions, stack traces visible on screen
+- **Rendering glitches**: Items cut off, wrong alignment, overlapping text, garbled output
+- **Wrong data**: Incorrect values displayed, stale data, missing information
+- **Missing options**: Menu items that should exist but don't
+- **Broken navigation**: Arrow keys don't work, can't go back, infinite loops
+- **Unhelpful errors**: Generic "Error" with no details, or raw error objects
+- **Hangs**: Screen freezes, no response to input (wait 10 seconds before declaring a hang)
+- **Screen overflow**: Content pushed off screen, no scrolling available
+- **Partial renders**: Screen shows half-drawn UI elements
+- **State corruption**: Operations succeed but data is wrong afterward
+
+## Cross-Validation
+
+Compare what you see on screen with what the MCP tools return:
+- After creating a ticket via the interactive menu, use \`ticket_list\` to verify it was created correctly
+- After moving a ticket, verify the status changed via \`ticket_show\`
+- Check that counts displayed in menus match actual data
+
+## When You Find a Bug
+
+1. **Document exact reproduction steps** — which keys you pressed, in what order
+2. **Capture the screen** showing the bug
+3. **File a ticket** using the ticket_create MCP tool:
+   - Title: Clear description of the bug
+   - Category: "bug"
+   - Priority: P1 for crashes/data loss, P2 for rendering/UX issues, P3 for minor issues
+   - Description: Include exact reproduction steps, screen capture, and expected vs actual behavior
+
+## Session Management
+
+- If the CLI crashes, restart it: kill the session and start a new one
+- If you get stuck, use Ctrl+C to escape, or kill and restart the session
+- Periodically capture the screen even when not expecting changes (catch intermittent issues)
+
+## Test Prioritization
+
+Start with the most commonly used flows, then move to edge cases:
+1. Main menu navigation
+2. Ticket operations (create, list, view, edit, move)
+3. Project operations
+4. Board view
+5. Work/session operations
+6. Epic and spec operations
+7. Settings and configuration
+8. Edge cases and stress testing`,
+            endPrompt: `## Wrap-Up
+
+When you've completed your exploration:
+
+1. **Summarize your findings**: List all bugs found with their ticket IDs
+2. **Note areas not tested**: If you couldn't reach certain features, list them
+3. **Rate overall CLI quality**: Brief assessment of stability, UX, and completeness
+
+Output a structured summary:
+\`\`\`
+## Exploratory QA Summary
+
+### Bugs Filed
+- TKT-XXX: [brief description]
+- TKT-YYY: [brief description]
+
+### Areas Tested
+- [ ] Main menu navigation
+- [ ] Ticket CRUD
+- [ ] Project operations
+- [ ] Board view
+- [ ] Work sessions
+- [ ] Epics & specs
+- [ ] Error handling
+- [ ] Input validation
+
+### Areas Not Tested
+- [list any areas you couldn't reach]
+
+### Overall Assessment
+[Brief quality assessment]
+\`\`\`
+
+Clean up your tmux session:
+\`\`\`
+tmux_kill_session({ session: "qa-test" })
+\`\`\``,
+            suggestedForCategories: [],
+            modifiesCode: false,
+            position: 8,
+        },
         {
             id: 'test',
             name: 'Write Tests',

package/dist/lib/pmo/storage/dependencies.d.ts

@@ -16,6 +16,7 @@ export declare class DependencyStorage {
     deleteTicketDependency(ticketId: string, dependsOnTicketId: string, dependencyType?: TicketDependencyType): Promise<void>;
     /**
      * List dependencies for a ticket.
+     * For relates_to dependencies, also returns reverse relationships (symmetric).
      */
     listTicketDependencies(ticketId: string): Promise<TicketDependency[]>;
     /**

package/dist/lib/pmo/storage/dependencies.js

@@ -63,14 +63,22 @@ export class DependencyStorage {
     }
     /**
      * List dependencies for a ticket.
+     * For relates_to dependencies, also returns reverse relationships (symmetric).
      */
     async listTicketDependencies(ticketId) {
         const rows = this.ctx.db.prepare(`
       SELECT ticket_id, depends_on_ticket_id, dependency_type, created_at
       FROM ${T.ticket_dependencies}
       WHERE ticket_id = ?
+
+      UNION
+
+      SELECT depends_on_ticket_id AS ticket_id, ticket_id AS depends_on_ticket_id, dependency_type, created_at
+      FROM ${T.ticket_dependencies}
+      WHERE depends_on_ticket_id = ? AND dependency_type = 'relates_to'
+
       ORDER BY created_at DESC
-    `).all(ticketId);
+    `).all(ticketId, ticketId);
         return rows.map((row) => ({
             ticketId: row.ticket_id,
             dependsOnTicketId: row.depends_on_ticket_id,
@@ -92,7 +100,7 @@ export class DependencyStorage {
       LEFT JOIN ${T.workflow_statuses} ws ON t.status_id = ws.id
       WHERE d.ticket_id = ? AND d.dependency_type = 'blocks'
     `).all(ticketId);
-        return Promise.all(rows.map((row) => rowToTicket(this.ctx.db, row)));
+        return Promise.all(rows.map((row) => rowToTicket(this.ctx.drizzle, row)));
     }
     /**
      * Get tickets that depend on this ticket (blocking).
@@ -108,7 +116,7 @@ export class DependencyStorage {
       LEFT JOIN ${T.workflow_statuses} ws ON t.status_id = ws.id
       WHERE d.depends_on_ticket_id = ? AND d.dependency_type = 'blocks'
     `).all(ticketId);
-        return Promise.all(rows.map((row) => rowToTicket(this.ctx.db, row)));
+        return Promise.all(rows.map((row) => rowToTicket(this.ctx.drizzle, row)));
     }
     /**
      * Check if a ticket is blocked by incomplete dependencies.

package/dist/lib/pmo/storage/epics.js

@@ -186,7 +186,7 @@ export class EpicStorage {
       WHERE t.project_id = ? AND t.epic_id = ?
       ORDER BY ws.position, t.position ASC, t.created_at ASC
     `).all(projectId, epicId);
-        return Promise.all(rows.map((row) => rowToTicket(this.ctx.db, row)));
+        return Promise.all(rows.map((row) => rowToTicket(this.ctx.drizzle, row)));
     }
     /**
      * Link a ticket to an epic.

package/dist/lib/pmo/storage/helpers.d.ts

@@ -1,7 +1,7 @@
 /**
  * Helper functions for converting database rows to domain types.
  */
-import Database from 'better-sqlite3';
+import type { DrizzleDB } from '../../database/drizzle.js';
 import { AcceptanceCriterion, Spec, StateCategory, Ticket } from '../types.js';
 import { SpecRow, TicketRow, WorkflowStatusRow } from './types.js';
 /**
@@ -16,13 +16,13 @@ import { SpecRow, TicketRow, WorkflowStatusRow } from './types.js';
 export declare function wrapSqliteError(entityType: string, operation: 'create' | 'update' | 'delete', err: unknown): never;
 /**
  * Convert a database row to a Ticket object.
- * Fetches related data (subtasks, metadata, status info).
+ * Fetches related data (subtasks, metadata, status info) using Drizzle ORM.
  */
-export declare function rowToTicket(db: Database.Database, row: TicketRow): Promise<Ticket>;
+export declare function rowToTicket(drizzle: DrizzleDB, row: TicketRow): Promise<Ticket>;
 /**
  * Get acceptance criteria for a ticket (sync version).
  */
-export declare function getAcceptanceCriteriaSync(db: Database.Database, ticketId: string): AcceptanceCriterion[];
+export declare function getAcceptanceCriteriaSync(drizzle: DrizzleDB, ticketId: string): AcceptanceCriterion[];
 /**
  * Convert a database row to a Spec object.
  */