@proletariat/cli 0.3.45 → 0.3.47

package/dist/lib/linear/types.js

@@ -0,0 +1,34 @@
+/**
+ * Linear Integration Types
+ *
+ * Type definitions for the Linear ↔ PMO integration layer.
+ */
+/**
+ * Status mapping between Linear state types and PMO state categories.
+ */
+export const LINEAR_STATE_TO_PMO_CATEGORY = {
+    triage: 'triage',
+    backlog: 'backlog',
+    unstarted: 'unstarted',
+    started: 'started',
+    completed: 'completed',
+    canceled: 'canceled',
+};
+/**
+ * Priority mapping between Linear (1-4) and PMO (P0-P3).
+ * Linear: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low
+ * PMO: P0=Critical, P1=High, P2=Medium, P3=Low
+ */
+export const LINEAR_PRIORITY_TO_PMO = {
+    0: 'P3', // No priority → Low
+    1: 'P0', // Urgent → Critical
+    2: 'P1', // High → High
+    3: 'P2', // Medium → Medium
+    4: 'P3', // Low → Low
+};
+export const PMO_PRIORITY_TO_LINEAR = {
+    P0: 1, // Critical → Urgent
+    P1: 2, // High → High
+    P2: 3, // Medium → Medium
+    P3: 4, // Low → Low
+};

package/dist/lib/mcp/helpers.d.ts

@@ -31,6 +31,14 @@ export declare function formatTicket(t: Ticket): {
     epicId: string | undefined;
     position: number | undefined;
 };
+export declare function formatTicketCompact(t: Ticket): {
+    id: string;
+    title: string;
+    priority: string | undefined;
+    category: string | undefined;
+    assignee: string | undefined;
+    statusName: string | undefined;
+};
 export declare function formatTicketFull(t: Ticket): {
     description: string | undefined;
     subtasks: import("../pmo/types.js").Subtask[];

package/dist/lib/mcp/helpers.js

@@ -32,6 +32,16 @@ export function formatTicket(t) {
         position: t.position,
     };
 }
+export function formatTicketCompact(t) {
+    return {
+        id: t.id,
+        title: t.title,
+        priority: t.priority,
+        category: t.category,
+        assignee: t.assignee,
+        statusName: t.statusName,
+    };
+}
 export function formatTicketFull(t) {
     return {
         ...formatTicket(t),

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

@@ -2,9 +2,18 @@
  * MCP Board Tools
  */
 import { z } from 'zod';
-import { formatTicket, errorResponse, strictTool } from '../helpers.js';
+import { formatTicketCompact, errorResponse, strictTool } from '../helpers.js';
+/** Status categories considered "done" and excluded by default */
+const DONE_CATEGORIES = new Set(['completed', 'canceled']);
 export function registerBoardTools(server, ctx) {
-    strictTool(server, 'board_view', 'Show the kanban board', { project: z.string().optional().describe('Project ID') }, async (params) => {
+    strictTool(server, 'board_view', 'Show the kanban board. Returns compact ticket format by default (id, title, priority, category, assignee, statusName). Use ticket_show for full details. Excludes Done/Canceled columns by default.', {
+        project: z.string().optional().describe('Project ID'),
+        summary: z.boolean().optional().describe('Summary mode: return only column names and ticket counts, no ticket details'),
+        column: z.string().optional().describe('Filter to a specific column by name (case-insensitive partial match)'),
+        include_done: z.boolean().optional().describe('Include completed/canceled columns (excluded by default)'),
+        limit: z.number().int().nonnegative().optional().describe('Max tickets to return per column'),
+        offset: z.number().int().nonnegative().optional().describe('Number of tickets to skip per column (for pagination)'),
+    }, async (params) => {
         try {
             let projectId = params.project;
             if (!projectId) {
@@ -14,6 +23,40 @@ export function registerBoardTools(server, ctx) {
                 projectId = projects[0].id;
             }
             const board = await ctx.storage.getBoard(projectId);
+            // Filter out done columns unless explicitly requested
+            let columns = board.columns;
+            if (!params.include_done) {
+                columns = columns.filter((col) => !DONE_CATEGORIES.has(col.status || ''));
+            }
+            // Filter to specific column by name (case-insensitive partial match)
+            if (params.column) {
+                const columnFilter = params.column.toLowerCase();
+                columns = columns.filter((col) => col.name.toLowerCase().includes(columnFilter));
+            }
+            // Summary mode: just column names and ticket counts
+            if (params.summary) {
+                const totalTickets = columns.reduce((sum, col) => sum + col.tickets.length, 0);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                board: {
+                                    id: board.id,
+                                    name: board.name,
+                                    totalTickets,
+                                    columns: columns.map((col) => ({
+                                        name: col.name,
+                                        position: col.position,
+                                        ticketCount: col.tickets.length,
+                                    })),
+                                    updatedAt: board.updatedAt.toISOString(),
+                                },
+                            }, null, 2),
+                        }],
+                };
+            }
+            // Compact format (default): return compact ticket objects with pagination
             return {
                 content: [{
                         type: 'text',
@@ -22,15 +65,24 @@ export function registerBoardTools(server, ctx) {
                             board: {
                                 id: board.id,
                                 name: board.name,
-                                columns: board.columns.map((col) => ({
-                                    name: col.name,
-                                    position: col.position,
-                                    ticketCount: col.tickets.length,
-                                    tickets: col.tickets.map((t) => ({
-                                        ...formatTicket(t),
-                                        labels: t.labels,
-                                    })),
-                                })),
+                                columns: columns.map((col) => {
+                                    const total = col.tickets.length;
+                                    let tickets = col.tickets;
+                                    const offset = params.offset || 0;
+                                    if (offset > 0) {
+                                        tickets = tickets.slice(offset);
+                                    }
+                                    if (params.limit !== undefined) {
+                                        tickets = tickets.slice(0, params.limit);
+                                    }
+                                    return {
+                                        name: col.name,
+                                        position: col.position,
+                                        ticketCount: total,
+                                        ...(offset > 0 || params.limit !== undefined ? { showing: tickets.length, offset } : {}),
+                                        tickets: tickets.map((t) => formatTicketCompact(t)),
+                                    };
+                                }),
                                 updatedAt: board.updatedAt.toISOString(),
                             },
                         }, null, 2),

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

@@ -219,6 +219,42 @@ export function registerWorkTools(server, ctx) {
             return errorResponse(error);
         }
     });
+    strictTool(server, 'work_review', 'Run automated review-fix pipeline on a ticket: spawns review agent, checks results, auto-spawns fix agent if issues found, re-reviews until clean or max cycles reached. Requires ticket to have a PR.', {
+        ticket_id: z.string().describe('Ticket ID to review'),
+        max_cycles: z.number().optional().describe('Maximum review-fix cycles (default: 3)'),
+        skip_permissions: z.boolean().optional().describe('Skip permission prompts (default: false)'),
+        environment: z.enum(['devcontainer', 'host']).optional().describe('Execution environment (default: devcontainer)'),
+    }, async (params) => {
+        try {
+            const args = [params.ticket_id, '--auto'];
+            if (params.max_cycles) {
+                args.push('--max-cycles', String(params.max_cycles));
+            }
+            if (params.skip_permissions) {
+                args.push('--skip-permissions');
+            }
+            if (params.environment === 'host') {
+                args.push('--run-on-host');
+            }
+            const cmd = `prlt work review ${args.join(' ')}`;
+            const output = ctx.runCommand(cmd);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            ticketId: params.ticket_id,
+                            command: cmd,
+                            output,
+                            message: `Review pipeline started for ${params.ticket_id}`,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            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.'),

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

@@ -38,6 +38,7 @@ export declare const PMO_TABLES: {
     readonly label_groups: "pmo_label_groups";
     readonly labels: "pmo_labels";
     readonly ticket_labels: "pmo_ticket_labels";
+    readonly linear_issue_map: "pmo_linear_issue_map";
     readonly columns: "pmo_columns";
     readonly board_tickets: "pmo_board_tickets";
     readonly statuses: "pmo_statuses";
@@ -79,6 +80,7 @@ export declare const PMO_TABLE_SCHEMAS: {
     readonly ticket_labels: "\n    CREATE TABLE IF NOT EXISTS pmo_ticket_labels (\n      ticket_id TEXT NOT NULL REFERENCES pmo_tickets(id) ON DELETE CASCADE,\n      label_id TEXT NOT NULL REFERENCES pmo_labels(id) ON DELETE CASCADE,\n      PRIMARY KEY (ticket_id, label_id)\n    )";
     readonly roadmaps: "\n    CREATE TABLE IF NOT EXISTS pmo_roadmaps (\n      id TEXT PRIMARY KEY,\n      name TEXT NOT NULL UNIQUE,\n      description TEXT,\n      is_default INTEGER NOT NULL DEFAULT 0,\n      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n    )";
     readonly roadmap_projects: "\n    CREATE TABLE IF NOT EXISTS pmo_roadmap_projects (\n      roadmap_id TEXT NOT NULL REFERENCES pmo_roadmaps(id) ON DELETE CASCADE,\n      project_id TEXT NOT NULL REFERENCES pmo_projects(id) ON DELETE CASCADE,\n      position INTEGER NOT NULL DEFAULT 0,\n      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      PRIMARY KEY (roadmap_id, project_id)\n    )";
+    readonly linear_issue_map: "\n    CREATE TABLE IF NOT EXISTS pmo_linear_issue_map (\n      pmo_ticket_id TEXT NOT NULL REFERENCES pmo_tickets(id) ON DELETE CASCADE,\n      linear_issue_id TEXT NOT NULL,\n      linear_identifier TEXT NOT NULL,\n      linear_team_key TEXT NOT NULL,\n      linear_url TEXT NOT NULL,\n      sync_direction TEXT NOT NULL DEFAULT 'inbound',\n      last_synced_at TIMESTAMP,\n      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n      PRIMARY KEY (pmo_ticket_id),\n      UNIQUE (linear_issue_id)\n    )";
 };
 export declare const PMO_INDEXES: string;
 /**

package/dist/lib/pmo/schema.js

@@ -45,6 +45,8 @@ export const PMO_TABLES = {
     label_groups: 'pmo_label_groups',
     labels: 'pmo_labels',
     ticket_labels: 'pmo_ticket_labels',
+    // Linear integration tables
+    linear_issue_map: 'pmo_linear_issue_map', // Linear issue ↔ PMO ticket mapping
     // Legacy tables (deprecated, kept for migration)
     columns: 'pmo_columns', // DEPRECATED: use workflow_statuses
     board_tickets: 'pmo_board_tickets', // DEPRECATED: tickets now use status_id directly
@@ -482,6 +484,20 @@ export const PMO_TABLE_SCHEMAS = {
       created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       PRIMARY KEY (roadmap_id, project_id)
     )`,
+    // Linear integration: issue ↔ PMO ticket mapping
+    linear_issue_map: `
+    CREATE TABLE IF NOT EXISTS ${PMO_TABLES.linear_issue_map} (
+      pmo_ticket_id TEXT NOT NULL REFERENCES ${PMO_TABLES.tickets}(id) ON DELETE CASCADE,
+      linear_issue_id TEXT NOT NULL,
+      linear_identifier TEXT NOT NULL,
+      linear_team_key TEXT NOT NULL,
+      linear_url TEXT NOT NULL,
+      sync_direction TEXT NOT NULL DEFAULT 'inbound',
+      last_synced_at TIMESTAMP,
+      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+      PRIMARY KEY (pmo_ticket_id),
+      UNIQUE (linear_issue_id)
+    )`,
 };
 // =============================================================================
 // Indexes
@@ -544,6 +560,9 @@ export const PMO_INDEXES = `
   CREATE INDEX IF NOT EXISTS idx_pmo_labels_builtin ON ${PMO_TABLES.labels}(is_builtin);
   CREATE INDEX IF NOT EXISTS idx_pmo_ticket_labels_ticket ON ${PMO_TABLES.ticket_labels}(ticket_id);
   CREATE INDEX IF NOT EXISTS idx_pmo_ticket_labels_label ON ${PMO_TABLES.ticket_labels}(label_id);
+  CREATE INDEX IF NOT EXISTS idx_pmo_linear_issue_map_linear_id ON ${PMO_TABLES.linear_issue_map}(linear_issue_id);
+  CREATE INDEX IF NOT EXISTS idx_pmo_linear_issue_map_identifier ON ${PMO_TABLES.linear_issue_map}(linear_identifier);
+  CREATE INDEX IF NOT EXISTS idx_pmo_linear_issue_map_team ON ${PMO_TABLES.linear_issue_map}(linear_team_key);
 `;
 // =============================================================================
 // Combined Schema
@@ -587,6 +606,7 @@ export const PMO_SCHEMA_SQL = [
     PMO_TABLE_SCHEMAS.ticket_labels, // Ticket-label junction table
     PMO_TABLE_SCHEMAS.roadmaps, // Named roadmap definitions
     PMO_TABLE_SCHEMAS.roadmap_projects, // Roadmap-to-project associations
+    PMO_TABLE_SCHEMAS.linear_issue_map, // Linear issue ↔ PMO ticket mapping
     // Legacy tables (kept for migration, will be dropped after data migrated)
     PMO_TABLE_SCHEMAS.columns, // DEPRECATED
     PMO_TABLE_SCHEMAS.board_tickets, // DEPRECATED

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

@@ -184,7 +184,7 @@ export function runMigrations(db) {
         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 {
+            const migrate = db.transaction(() => {
                 // Create new table with correct schema
                 db.exec(`
           CREATE TABLE pmo_ticket_dependencies_new (
@@ -205,10 +205,8 @@ export function runMigrations(db) {
                 // 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
-            }
+            });
+            migrate();
         }
     }
     // Migration: Convert legacy priority values (URGENT/HIGH/MEDIUM/LOW) to P0-P3
@@ -490,6 +488,46 @@ Example (WRONG - do not do this):
 ./apps/cli/bin/run.js ticket edit TKT-123 ...
 \`\`\`
 `.trim();
+/**
+ * prlt CLI command reference sections for action prompts.
+ * Each action gets a tailored set of commands relevant to its workflow.
+ */
+const PRLT_COMMANDS_COMMON = `
+## prlt CLI Reference
+
+Use these commands to interact with the ticket system. Always use the global \`prlt\` command.
+
+| Command | Description |
+|---------|-------------|
+| \`prlt ticket show <id>\` | View full ticket details (description, AC, subtasks, labels) |
+| \`prlt ticket edit <id> [flags]\` | Update ticket fields (see flags below) |
+| \`prlt ticket list\` | List tickets on the board |
+| \`prlt whoami\` | Show current agent/user identity |
+
+### Common \`ticket edit\` flags
+| Flag | Description |
+|------|-------------|
+| \`--title "..."\` | Update title |
+| \`--description "..."\` | Update description |
+| \`--priority P0\\|P1\\|P2\\|P3\` | Set priority |
+| \`--category <type>\` | Set category (feature, bug, refactor, etc.) |
+| \`--add-ac "..."\` | Add acceptance criterion |
+| \`--clear-ac\` | Clear all acceptance criteria |
+| \`--add-subtask "..."\` | Add a subtask |
+| \`--clear-subtasks\` | Clear all subtasks |
+| \`--add-label "..."\` | Add a label |
+| \`--remove-label "..."\` | Remove a label |
+| \`--assignee <name>\` | Set assignee |
+| \`--owner <name>\` | Set owner |`;
+const PRLT_COMMANDS_CODE = `
+| \`prlt commit "message"\` | Create a commit with ticket ID from branch name |
+| \`prlt work ready <id> --pr\` | Mark ticket ready for review and create a PR |`;
+const PRLT_COMMANDS_REVIEW = `
+| \`prlt ticket move <id>\` | Move ticket to a different column |
+| \`prlt ticket complete <id>\` | Mark ticket as complete (move to Done) |`;
+const PRLT_COMMANDS_RESOLVE = `
+| \`prlt ticket resolve <id>\` | Interactive resolution of ambiguity questions |
+| \`prlt work resolve <id>\` | Agent-assisted resolution of ambiguity questions |`;
 /**
  * Seed built-in work actions.
  */
@@ -532,6 +570,15 @@ If NO ambiguities are found, add the \`ready\` label instead.
 
 **AI Agent Tip:** When running \`prlt\` commands without all required arguments, use \`--json\` to receive interactive prompts as structured JSON.
 
+### Additional prlt Commands
+| Command | Description |
+|---------|-------------|
+| \`prlt ticket show <id>\` | View full ticket details |
+| \`prlt ticket list\` | List tickets on the board |
+| \`prlt whoami\` | Show current agent/user identity |
+| \`prlt ticket resolve <id>\` | Interactive resolution of ambiguity questions |
+| \`prlt work resolve <id>\` | Agent-assisted resolution of ambiguity questions |
+
 ## Ticket Schema Reference
 
 | Field | Type | Valid Values | CLI Flag |
@@ -628,7 +675,10 @@ For each question:
 ## Important
 - This is an INTERACTIVE session - always ask the human before writing answers
 - If the ticket has acceptance criteria or subtasks that need updating based on answers, update those too
-- After resolving, move the ticket to the Ready column if all questions are answered`,
+- After resolving, move the ticket to the Ready column if all questions are answered
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_RESOLVE}`,
             endPrompt: `After resolving all questions:
 1. Update the ticket description with answers below each question
 2. Remove the \`needs-clarification\` label and add \`ready\` label
@@ -671,7 +721,10 @@ prlt commit "implement user validation"
 git push
 \`\`\`
 
-When complete, the ticket should be ready for code review.`,
+When complete, the ticket should be ready for code review.
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_CODE}`,
             endPrompt: `When complete:
 1. **Commit your work** in each repository directory you modified:
    \`\`\`bash
@@ -717,7 +770,10 @@ Continue working on this ticket from where you left off.
 
 \`\`\`bash
 git add -A && prlt commit "your change" && git push
-\`\`\``,
+\`\`\`
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_CODE}`,
             endPrompt: `When complete:
 1. **Commit your work** in each repository directory you modified:
    \`\`\`bash
@@ -761,9 +817,15 @@ After reviewing, determine your verdict:
 - **REQUEST_CHANGES**: There are issues that must be fixed before merging
 - **COMMENT**: General feedback, no blocking issues but some suggestions
 
-Do NOT modify any code. This is a read-only review.`,
+Do NOT modify any code. Do NOT attempt to fix any issues. This is a read-only review — report your findings only.
+If you identify issues that need fixing, describe them in your review. A separate action (Review & Fix) will handle fixes.
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_REVIEW}`,
             endPrompt: `When you have finished reviewing, post your review on the PR using \`gh pr review\`.
 
+**CRITICAL: Do NOT modify any code. Do NOT attempt to fix any issues you find. Your ONLY job is to report findings.**
+
 Choose the appropriate command based on your verdict:
 
 **If approving:**
@@ -810,7 +872,14 @@ COMMENT - Some suggestions but no blocking issues."
 
 Format the body with: what looks good, concerns (if any), suggested improvements (if any), and your verdict.
 
-No commits are needed for code review.`,
+No commits are needed for code review.
+
+**After posting your review**, if you found issues that need fixing, log them on the ticket so another action can address them:
+\`\`\`bash
+prlt ticket edit <TICKET_ID> --add-subtask "Fix: <description of issue>"
+\`\`\`
+
+**STOP:** After posting your review and logging any findings, your task is complete. Do not take any further actions, do not attempt to fix any issues, do not type additional instructions, and do not continue the conversation. Simply output your summary and use \`/exit\` to end the session.`,
             suggestedForCategories: ['started', 'completed'],
             modifiesCode: false,
             position: 4,
@@ -838,7 +907,11 @@ Review this ticket's implementation thoroughly and fix any issues found:
 
 \`\`\`bash
 git add -A && prlt commit "fix: address code review findings" && git push
-\`\`\``,
+\`\`\`
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_CODE}
+${PRLT_COMMANDS_REVIEW}`,
             endPrompt: `When you have finished reviewing and fixing:
 
 1. **If issues were found and fixed**, post a review summary and push your fixes:
@@ -908,7 +981,10 @@ Address the feedback on this ticket's pull request:
 
 \`\`\`bash
 git add -A && prlt commit "fix: address PR review feedback" && git push
-\`\`\``,
+\`\`\`
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_CODE}`,
             endPrompt: `After addressing all feedback:
 
 1. **Commit your changes**:
@@ -1117,7 +1193,10 @@ Write comprehensive tests for this ticket's implementation:
 
 \`\`\`bash
 git add -A && prlt commit "add tests for X" && git push
-\`\`\``,
+\`\`\`
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_CODE}`,
             endPrompt: `When complete:
 1. **Commit your tests**:
    \`\`\`bash

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

@@ -58,6 +58,21 @@ export class DependencyStorage {
         }
         const result = this.ctx.db.prepare(query).run(...params);
         if (result.changes === 0) {
+            // For relates_to, try the reverse direction since the relationship is symmetric
+            const reverseType = dependencyType ?? 'relates_to';
+            if (reverseType === 'relates_to') {
+                let reverseQuery = `DELETE FROM ${T.ticket_dependencies} WHERE ticket_id = ? AND depends_on_ticket_id = ?`;
+                const reverseParams = [dependsOnTicketId, ticketId];
+                if (dependencyType) {
+                    reverseQuery += ' AND dependency_type = ?';
+                    reverseParams.push(dependencyType);
+                }
+                const reverseResult = this.ctx.db.prepare(reverseQuery).run(...reverseParams);
+                if (reverseResult.changes === 0) {
+                    throw new PMOError('NOT_FOUND', 'Dependency not found');
+                }
+                return;
+            }
             throw new PMOError('NOT_FOUND', 'Dependency not found');
         }
     }

package/dist/lib/prompt-json.d.ts

@@ -88,6 +88,10 @@ export interface OutputMetadata {
     timestamp?: string;
     /** Resolved PR mode after flag precedence ('create-pr' | 'no-pr') */
     resolvedPRMode?: string;
+    /** Source of the resolved PR mode (e.g., 'flag --create-pr', 'workspace config', 'interactive prompt') */
+    prModeSource?: string;
+    /** Warning message when PR creation is disabled for code-modifying actions */
+    prWarning?: string;
 }
 /**
  * JSON output when a prompt would be shown