@proletariat/cli 0.3.47 → 0.3.49

package/dist/lib/external-issues/linear.js

@@ -0,0 +1,261 @@
+import { ExternalIssueAdapterError, toNormalizedEnvelope, } from './types.js';
+const DEFAULT_LINEAR_API_URL = 'https://api.linear.app/graphql';
+const LINEAR_ISSUES_QUERY = `
+  query IssuesForSpawn($teamKey: String!, $first: Int!) {
+    issues(
+      first: $first
+      filter: {
+        team: { key: { eq: $teamKey } }
+        state: { type: { nin: ["completed", "canceled"] } }
+      }
+      orderBy: updatedAt
+    ) {
+      nodes {
+        id
+        identifier
+        title
+        description
+        url
+        priority
+        labels {
+          nodes {
+            name
+          }
+        }
+        state {
+          name
+          type
+        }
+      }
+    }
+  }
+`;
+const LINEAR_ISSUE_BY_IDENTIFIER_QUERY = `
+  query IssueForSpawn($id: String!) {
+    issue(id: $id) {
+      id
+      identifier
+      title
+      description
+      url
+      priority
+      labels {
+        nodes {
+          name
+        }
+      }
+      state {
+        name
+        type
+      }
+    }
+  }
+`;
+function priorityFromLinear(value) {
+    switch (value) {
+        case 1:
+            return 'P0';
+        case 2:
+            return 'P1';
+        case 3:
+            return 'P2';
+        case 4:
+            return 'P3';
+        default:
+            return null;
+    }
+}
+function ensureLinearConfig(config) {
+    const apiKey = config.apiKey || process.env.LINEAR_API_KEY || process.env.PRLT_LINEAR_API_KEY;
+    const team = config.team || process.env.PRLT_LINEAR_TEAM || process.env.LINEAR_TEAM_KEY;
+    const apiUrl = config.apiUrl || process.env.PRLT_LINEAR_API_URL || DEFAULT_LINEAR_API_URL;
+    if (!apiKey) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Linear API key. Set LINEAR_API_KEY or PRLT_LINEAR_API_KEY.');
+    }
+    if (!team) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Linear team key. Pass --team or set PRLT_LINEAR_TEAM.');
+    }
+    return { apiKey, team, apiUrl };
+}
+function ensureLinearIssueShape(issue) {
+    if (!issue.id || !issue.identifier || !issue.title || !issue.url) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Linear issue payload is missing required fields (id, identifier, title, url).', issue);
+    }
+}
+/**
+ * Normalize a raw Linear API issue node into a canonical IssueEnvelope.
+ */
+export function normalizeLinearIssue(rawIssue) {
+    if (!rawIssue || typeof rawIssue !== 'object') {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Linear issue payload is invalid.', rawIssue);
+    }
+    const issue = rawIssue;
+    ensureLinearIssueShape(issue);
+    const labels = (issue.labels?.nodes || [])
+        .map(label => label.name?.trim())
+        .filter((name) => Boolean(name));
+    const [projectKey] = issue.identifier.split('-');
+    return {
+        source: 'linear',
+        external_id: issue.id,
+        external_key: issue.identifier,
+        title: issue.title,
+        description: issue.description || '',
+        labels,
+        priority: priorityFromLinear(issue.priority),
+        status: issue.state?.name || 'Unknown',
+        url: issue.url,
+        project_key: projectKey || 'UNKNOWN',
+        assignee: null,
+        item_type: 'issue',
+        raw: rawIssue,
+    };
+}
+/**
+ * Normalize a raw Linear issue into a PMO-ready NormalizedIssueEnvelope.
+ */
+export function normalizeLinearIssueToEnvelope(rawIssue) {
+    const envelope = normalizeLinearIssue(rawIssue);
+    return toNormalizedEnvelope(envelope, 'feature');
+}
+/**
+ * Build a PMO ticket description from a NormalizedIssueEnvelope.
+ */
+export function buildLinearTicketDescription(envelope) {
+    const body = envelope.description.trim();
+    const metadataLines = [
+        `- Source: ${envelope.source.name}`,
+        `- External key: ${envelope.source.externalKey}`,
+        `- External id: ${envelope.source.externalId}`,
+        `- URL: ${envelope.source.url}`,
+        `- Status: ${envelope.status}`,
+        `- Priority: ${envelope.priority || 'Unset'}`,
+        `- Labels: ${envelope.labels.length > 0 ? envelope.labels.join(', ') : 'None'}`,
+    ];
+    const parts = [
+        body,
+        '## External Issue Context',
+        metadataLines.join('\n'),
+    ].filter(Boolean);
+    return parts.join('\n\n');
+}
+/**
+ * Build ticket metadata from a NormalizedIssueEnvelope for traceability.
+ */
+export function buildLinearMetadata(envelope) {
+    return {
+        external_source: envelope.source.name,
+        external_key: envelope.source.externalKey,
+        external_id: envelope.source.externalId,
+        external_url: envelope.source.url,
+        external_raw: JSON.stringify(envelope.source.raw),
+    };
+}
+/**
+ * Build a spawn context message from a NormalizedIssueEnvelope.
+ */
+export function buildLinearSpawnContextMessage(envelope, additionalMessage) {
+    const lines = [
+        `External issue source: ${envelope.source.name}`,
+        `External issue key: ${envelope.source.externalKey}`,
+        `External issue id: ${envelope.source.externalId}`,
+        `External issue URL: ${envelope.source.url}`,
+    ];
+    if (additionalMessage?.trim()) {
+        lines.push('', additionalMessage.trim());
+    }
+    return lines.join('\n');
+}
+/**
+ * Build a CLI command string for selecting a specific Linear issue.
+ */
+export function buildLinearIssueChoiceCommand(issueIdentifier, projectId) {
+    let command = `prlt work linear --issue ${issueIdentifier} --json`;
+    if (projectId) {
+        command += ` -P ${projectId}`;
+    }
+    return command;
+}
+/**
+ * Fetch a single Linear issue by identifier (for example, ENG-123) and normalize it.
+ */
+export async function getLinearIssueByIdentifier(configInput, identifier, options) {
+    const config = ensureLinearConfig(configInput);
+    const fetchImpl = options?.fetchImpl || fetch;
+    const response = await fetchImpl(config.apiUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: config.apiKey,
+        },
+        body: JSON.stringify({
+            query: LINEAR_ISSUE_BY_IDENTIFIER_QUERY,
+            variables: {
+                id: identifier,
+            },
+        }),
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new ExternalIssueAdapterError('AUTH_FAILED', 'Linear authentication failed. Verify your LINEAR_API_KEY token.');
+    }
+    if (!response.ok) {
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', `Linear request failed with status ${response.status}.`);
+    }
+    const payload = await response.json();
+    if (payload.errors && payload.errors.length > 0) {
+        const message = payload.errors[0]?.message || 'Unknown Linear API error.';
+        if (/auth|token|forbidden|unauthorized/i.test(message)) {
+            throw new ExternalIssueAdapterError('AUTH_FAILED', `Linear authentication failed: ${message}`);
+        }
+        // "not found" should be treated as null, not hard failure.
+        if (/not found/i.test(message)) {
+            return null;
+        }
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', `Linear API error: ${message}`);
+    }
+    const node = payload.data?.issue;
+    if (!node)
+        return null;
+    return normalizeLinearIssueToEnvelope(node);
+}
+/**
+ * Fetch and normalize Linear issues into NormalizedIssueEnvelopes.
+ */
+export async function listLinearIssues(configInput, options) {
+    const config = ensureLinearConfig(configInput);
+    const fetchImpl = options?.fetchImpl || fetch;
+    const limit = Math.max(1, Math.min(options?.limit ?? 20, 100));
+    const response = await fetchImpl(config.apiUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: config.apiKey,
+        },
+        body: JSON.stringify({
+            query: LINEAR_ISSUES_QUERY,
+            variables: {
+                teamKey: config.team,
+                first: limit,
+            },
+        }),
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new ExternalIssueAdapterError('AUTH_FAILED', 'Linear authentication failed. Verify your LINEAR_API_KEY token.');
+    }
+    if (!response.ok) {
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', `Linear request failed with status ${response.status}.`);
+    }
+    const payload = await response.json();
+    if (payload.errors && payload.errors.length > 0) {
+        const message = payload.errors[0]?.message || 'Unknown Linear API error.';
+        if (/auth|token|forbidden|unauthorized/i.test(message)) {
+            throw new ExternalIssueAdapterError('AUTH_FAILED', `Linear authentication failed: ${message}`);
+        }
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', `Linear API error: ${message}`);
+    }
+    const nodes = payload.data?.issues?.nodes;
+    if (!Array.isArray(nodes)) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Linear response payload was missing issues.nodes.', payload);
+    }
+    return nodes.map(normalizeLinearIssueToEnvelope);
+}

package/dist/lib/external-issues/types.d.ts

@@ -142,3 +142,70 @@ export declare class ExternalIssueError extends Error {
     validationErrors?: IssueValidationError[] | undefined;
     constructor(code: ExternalIssueErrorCode, message: string, source?: IssueSource | undefined, validationErrors?: IssueValidationError[] | undefined);
 }
+/**
+ * Error codes for adapter-level operations (config, auth, payload, request).
+ */
+export type ExternalIssueAdapterErrorCode = 'MISSING_CONFIG' | 'AUTH_FAILED' | 'BAD_PAYLOAD' | 'REQUEST_FAILED';
+/**
+ * Typed error for external issue adapter operations.
+ *
+ * Covers config, auth, payload, and request failures that occur
+ * when interacting with a specific external issue source.
+ */
+export declare class ExternalIssueAdapterError extends Error {
+    readonly code: ExternalIssueAdapterErrorCode;
+    readonly causeDetail?: unknown | undefined;
+    constructor(code: ExternalIssueAdapterErrorCode, message: string, causeDetail?: unknown | undefined);
+}
+/**
+ * Source metadata nested object for traceability.
+ */
+export interface IssueSourceMetadata {
+    /** Which external system the issue came from */
+    name: IssueSource;
+    /** Unique identifier in the external system (e.g., Linear UUID) */
+    externalId: string;
+    /** Human-readable key in the external system (e.g., "ENG-123") */
+    externalKey: string;
+    /** URL to view the issue in the external system */
+    url: string;
+    /** Original raw payload from the external system */
+    raw: Record<string, unknown>;
+}
+/**
+ * PMO-ready normalized issue envelope.
+ *
+ * Wraps a canonical IssueEnvelope with PMO-oriented fields (e.g., category)
+ * and a nested source metadata object for ergonomic access in commands.
+ *
+ * Produced by normalizing an IssueEnvelope into the shape expected by
+ * PMO ticket creation and the spawn context pipeline.
+ */
+export interface NormalizedIssueEnvelope {
+    /** Nested source metadata for traceability */
+    source: IssueSourceMetadata;
+    /** Issue title / summary */
+    title: string;
+    /** Issue description (markdown or plain text) */
+    description: string;
+    /** Labels / tags applied to the issue */
+    labels: string[];
+    /** Priority level (normalized to P0-P3 scale, or null) */
+    priority: string | null;
+    /** Current status name in the external system */
+    status: string;
+    /** Project key in the external system */
+    projectKey: string;
+    /** Assignee display name or identifier */
+    assignee: string | null;
+    /** PMO ticket category derived from source metadata (e.g., "feature") */
+    category: string | null;
+    /** Source-native work item kind when available */
+    itemType?: string | null;
+}
+/**
+ * Convert a canonical IssueEnvelope to a NormalizedIssueEnvelope.
+ *
+ * Deterministic: same input always produces same output.
+ */
+export declare function toNormalizedEnvelope(envelope: IssueEnvelope, category?: string | null): NormalizedIssueEnvelope;

package/dist/lib/external-issues/types.js

@@ -24,3 +24,44 @@ export class ExternalIssueError extends Error {
         this.name = 'ExternalIssueError';
     }
 }
+/**
+ * Typed error for external issue adapter operations.
+ *
+ * Covers config, auth, payload, and request failures that occur
+ * when interacting with a specific external issue source.
+ */
+export class ExternalIssueAdapterError extends Error {
+    code;
+    causeDetail;
+    constructor(code, message, causeDetail) {
+        super(message);
+        this.code = code;
+        this.causeDetail = causeDetail;
+        this.name = 'ExternalIssueAdapterError';
+    }
+}
+/**
+ * Convert a canonical IssueEnvelope to a NormalizedIssueEnvelope.
+ *
+ * Deterministic: same input always produces same output.
+ */
+export function toNormalizedEnvelope(envelope, category) {
+    return {
+        source: {
+            name: envelope.source,
+            externalId: envelope.external_id,
+            externalKey: envelope.external_key,
+            url: envelope.url,
+            raw: envelope.raw,
+        },
+        title: envelope.title,
+        description: envelope.description,
+        labels: envelope.labels,
+        priority: envelope.priority,
+        status: envelope.status,
+        projectKey: envelope.project_key,
+        assignee: envelope.assignee,
+        category: category ?? null,
+        itemType: envelope.item_type ?? null,
+    };
+}

package/dist/lib/init/index.d.ts

@@ -35,6 +35,10 @@ export declare function validateHQLocation(location: string): {
     valid: boolean;
     reason?: string;
 };
+/**
+ * Check if an HQ name is already in use by another headquarters on this machine.
+ */
+export declare function isHQNameTaken(name: string): boolean;
 /**
  * Prompt user for HQ name
  */

package/dist/lib/init/index.js

@@ -8,7 +8,7 @@ import { createAgentWorktrees } from '../agents/index.js';
 import { addRepositoriesToHQ, isInGitRepo } from '../repos/index.js';
 import { createPMO, } from '../pmo/index.js';
 import { createWorkspaceDatabase, addRepositoriesToDatabase, addAgentsToDatabase, createTheme, addThemeNames, setActiveTheme } from '../database/index.js';
-import { ensureMachineConfigDir, registerHeadquarters, getOrganizations, createOrganization, } from '../machine-config.js';
+import { ensureMachineConfigDir, registerHeadquarters, getOrganizations, createOrganization, findHeadquartersByName, } from '../machine-config.js';
 import { hasGitHubRemote } from '../repos/git.js';
 import { isGHInstalled, isGHAuthenticated } from '../pr/index.js';
 /**
@@ -55,6 +55,13 @@ export function validateHQLocation(location) {
     }
     return { valid: true };
 }
+/**
+ * Check if an HQ name is already in use by another headquarters on this machine.
+ */
+export function isHQNameTaken(name) {
+    const existing = findHeadquartersByName(name);
+    return existing.length > 0;
+}
 /**
  * Prompt user for HQ name
  */
@@ -74,6 +81,9 @@ export async function promptForHQName() {
                 if (!/^[a-zA-Z0-9-_]+$/.test(input)) {
                     return 'Name can only contain letters, numbers, hyphens, and underscores';
                 }
+                if (isHQNameTaken(input.trim())) {
+                    return `HQ name "${input.trim()}" is already in use on this machine. Pick another name.`;
+                }
                 return true;
             },
         }]);

package/dist/lib/machine-config.d.ts

@@ -40,6 +40,7 @@ export interface MachineConfig {
 }
 /**
  * Get the path to the machine-level config directory (~/.proletariat/).
+ * Uses process.env.HOME when set (for testability), falling back to os.homedir().
  */
 export declare function getMachineConfigDir(): string;
 /**

package/dist/lib/machine-config.js

@@ -5,9 +5,11 @@ import { isValidHQ } from './workspace.js';
 const CONFIG_VERSION = '1.0.0';
 /**
  * Get the path to the machine-level config directory (~/.proletariat/).
+ * Uses process.env.HOME when set (for testability), falling back to os.homedir().
  */
 export function getMachineConfigDir() {
-    return path.join(os.homedir(), '.proletariat');
+    const home = process.env.HOME || os.homedir();
+    return path.join(home, '.proletariat');
 }
 /**
  * Get the path to the machine-level config file (~/.proletariat/config.json).
@@ -32,9 +34,10 @@ export function ensureMachineConfigDir() {
  * - Removes trailing slashes
  */
 export function normalizePath(inputPath) {
-    // Expand ~ to home directory
+    // Expand ~ to home directory (respect process.env.HOME for testability)
+    const home = process.env.HOME || os.homedir();
     let resolved = inputPath.startsWith('~')
-        ? path.join(os.homedir(), inputPath.slice(1))
+        ? path.join(home, inputPath.slice(1))
         : inputPath;
     // Make absolute
     resolved = path.resolve(resolved);

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

@@ -67,7 +67,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      error_message TEXT,\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      permission_mode TEXT NOT NULL DEFAULT 'safe',\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

@@ -328,7 +328,7 @@ export const PMO_TABLE_SCHEMAS = {
       executor TEXT NOT NULL,
       environment TEXT NOT NULL DEFAULT 'host',
       display_mode TEXT NOT NULL DEFAULT 'terminal',
-      sandboxed INTEGER NOT NULL DEFAULT 0,
+      permission_mode TEXT NOT NULL DEFAULT 'safe',
       status TEXT NOT NULL DEFAULT 'starting',
       branch TEXT,
       pid TEXT,

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

@@ -165,10 +165,10 @@ export class ActionStorage {
             description: row.description || undefined,
             prompt: row.prompt,
             endPrompt: row.end_prompt || undefined,
-            suggestedForCategories: row.default_category
-                ? JSON.parse(row.default_category)
+            suggestedForCategories: row.suggested_for_categories
+                ? JSON.parse(row.suggested_for_categories)
                 : undefined,
-            defaultMoveToCategory: row.default_category,
+            defaultMoveToCategory: row.default_move_to_category,
             modifiesCode: row.modifies_code === 1,
             isBuiltin: row.is_builtin === 1,
             createdAt: new Date(row.created_at),

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

@@ -345,6 +345,37 @@ export function runMigrations(db) {
             // Non-critical migration - don't fail initialization
         }
     }
+    // Migration: Rename sandboxed column to permission_mode in agent_work table
+    if (tableExists(T.agent_work)) {
+        const awColumns = db.pragma(`table_info(${T.agent_work})`);
+        const awColumnNames = new Set(awColumns.map(c => c.name));
+        if (awColumnNames.has('sandboxed') && !awColumnNames.has('permission_mode')) {
+            try {
+                db.exec(`ALTER TABLE ${T.agent_work} ADD COLUMN permission_mode TEXT NOT NULL DEFAULT 'safe'`);
+                // Migrate existing data: sandboxed=1 → 'safe', sandboxed=0 → 'danger'
+                db.exec(`UPDATE ${T.agent_work} SET permission_mode = CASE WHEN sandboxed = 1 THEN 'safe' ELSE 'danger' END`);
+            }
+            catch {
+                // Column may already exist
+            }
+        }
+    }
+    // Migration: Rename execution.sandboxed setting to execution.permission_mode
+    if (tableExists('workspace_settings')) {
+        try {
+            const oldSetting = db.prepare(`SELECT value FROM workspace_settings WHERE key = 'execution.sandboxed'`).get();
+            if (oldSetting) {
+                const permMode = oldSetting.value === 'true' ? 'safe' : 'danger';
+                db.prepare(`
+          INSERT INTO workspace_settings (key, value) VALUES ('execution.permission_mode', ?)
+          ON CONFLICT(key) DO UPDATE SET value = excluded.value
+        `).run(permMode);
+            }
+        }
+        catch {
+            // Non-critical migration
+        }
+    }
 }
 /**
  * Seed built-in workflows from BUILTIN_TEMPLATES (single source of truth).
@@ -817,7 +848,16 @@ 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. Do NOT attempt to fix any issues. This is a read-only review — report your findings only.
+## STRICT RULES - READ CAREFULLY
+
+- **DO NOT** merge the PR (\`gh pr merge\` is FORBIDDEN)
+- **DO NOT** push any code (\`git push\` is FORBIDDEN)
+- **DO NOT** run tests or test suites
+- **DO NOT** modify, edit, or write any code files
+- **DO NOT** create commits
+- Your ONLY output should be a \`gh pr review\` comment
+- This is a **read-only** review — read the diff, analyze it, post your review, and stop
+
 If you identify issues that need fixing, describe them in your review. A separate action (Review & Fix) will handle fixes.
 
 ${PRLT_COMMANDS_COMMON}
@@ -872,7 +912,7 @@ 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.
+**REMINDER:** Do NOT merge the PR. Do NOT run tests. Do NOT modify code. Only post the review comment above.
 
 **After posting your review**, if you found issues that need fixing, log them on the ticket so another action can address them:
 \`\`\`bash
@@ -884,6 +924,76 @@ prlt ticket edit <TICKET_ID> --add-subtask "Fix: <description of issue>"
             modifiesCode: false,
             position: 4,
         },
+        {
+            id: 'review-comment',
+            name: 'Review Comment',
+            description: 'Post review comments on a PR without merging, testing, or modifying code',
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Review Comment
+
+Read the PR diff, analyze the changes, and post a GitHub review comment. That is your ONLY job.
+
+## STRICT RULES - READ CAREFULLY
+
+You are a **read-only** reviewer. You MUST follow these rules:
+
+- **DO NOT** run \`gh pr merge\` — merging is FORBIDDEN
+- **DO NOT** run \`git push\` — pushing is FORBIDDEN
+- **DO NOT** run tests or test suites of any kind
+- **DO NOT** modify, edit, or write any code files
+- **DO NOT** create commits or branches
+- **DO NOT** run any commands that change repository state
+- Your **ONLY** permitted write operation is \`gh pr review\` to post your comment
+
+## What To Do
+
+1. Read the PR diff to understand the changes
+2. Analyze the code for bugs, issues, style, and correctness
+3. Post your review using \`gh pr review\` with the appropriate verdict
+4. **STOP** — do nothing else after posting the review
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_REVIEW}`,
+            endPrompt: `Post your review on the PR using \`gh pr review\`. This is the ONLY action you should take.
+
+**If approving:**
+\`\`\`bash
+gh pr review --approve --body "## Review
+
+### Summary
+- ...
+
+APPROVED - Looks good to merge."
+\`\`\`
+
+**If requesting changes:**
+\`\`\`bash
+gh pr review --request-changes --body "## Review
+
+### Issues
+- ...
+
+REQUEST CHANGES - Please address the above."
+\`\`\`
+
+**If commenting:**
+\`\`\`bash
+gh pr review --comment --body "## Review
+
+### Feedback
+- ...
+
+COMMENT - Some suggestions, no blockers."
+\`\`\`
+
+**CRITICAL REMINDER:** After posting your review, STOP. Do NOT merge the PR. Do NOT run tests. Do NOT modify code. Do NOT push anything. Your job is done after the \`gh pr review\` command.`,
+            suggestedForCategories: ['completed'],
+            modifiesCode: false,
+            position: 5,
+        },
         {
             id: 'review-fix',
             name: 'Review & Fix',
@@ -943,7 +1053,7 @@ ${PRLT_COMMANDS_REVIEW}`,
    \`\`\``,
             suggestedForCategories: ['started', 'completed'],
             modifiesCode: true,
-            position: 5,
+            position: 6,
         },
         {
             id: 'revise',
@@ -1007,7 +1117,7 @@ The PR will be updated automatically with your pushed changes.`,
             suggestedForCategories: ['completed'],
             defaultMoveToCategory: 'started',
             modifiesCode: true,
-            position: 6,
+            position: 7,
         },
         {
             id: 'explore-cli',
@@ -1168,7 +1278,7 @@ tmux_kill_session({ session: "qa-test" })
 \`\`\``,
             suggestedForCategories: [],
             modifiesCode: false,
-            position: 8,
+            position: 9,
         },
         {
             id: 'test',
@@ -1213,7 +1323,7 @@ ${PRLT_COMMANDS_CODE}`,
 **IMPORTANT:** Use the global \`prlt\` command.`,
             suggestedForCategories: ['started', 'completed'],
             modifiesCode: true,
-            position: 7,
+            position: 8,
         },
     ];
     // Use INSERT OR REPLACE to always update builtin actions with latest prompts

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

@@ -139,7 +139,7 @@ export class EpicStorage {
             updates.push('file_path = ?');
             params.push(changes.filePath);
         }
-        if (changes.specId !== undefined) {
+        if ('specId' in changes) {
             updates.push('spec_id = ?');
             params.push(changes.specId || null);
         }