@lumenflow/cli 2.2.2 → 2.3.2

package/dist/__tests__/state-doctor.test.js

@@ -0,0 +1,274 @@
+/**
+ * State Doctor CLI Tests (WU-1230)
+ *
+ * Tests for state:doctor --fix functionality:
+ * - Micro-worktree isolation for all tracked file changes
+ * - Removal of stale WU references from backlog.md and status.md
+ * - Changes pushed via merge, not direct file modification
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+/**
+ * Mocked modules
+ */
+vi.mock('@lumenflow/core/dist/micro-worktree.js', () => ({
+    withMicroWorktree: vi.fn(),
+}));
+vi.mock('@lumenflow/core/dist/git-adapter.js', () => ({
+    getGitForCwd: vi.fn(() => ({
+        fetch: vi.fn(),
+        merge: vi.fn(),
+        push: vi.fn(),
+    })),
+    createGitForPath: vi.fn(() => ({
+        add: vi.fn(),
+        commit: vi.fn(),
+        push: vi.fn(),
+    })),
+}));
+/**
+ * Import after mocks are set up
+ */
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+/**
+ * Constants for test paths
+ */
+const LUMENFLOW_DIR = '.lumenflow';
+const STATE_DIR = 'state';
+const STAMPS_DIR = 'stamps';
+const MEMORY_DIR = 'memory';
+const DOCS_TASKS_DIR = 'docs/04-operations/tasks';
+const BACKLOG_PATH = `${DOCS_TASKS_DIR}/backlog.md`;
+const STATUS_PATH = `${DOCS_TASKS_DIR}/status.md`;
+/**
+ * Test directory path
+ */
+let testDir;
+describe('state-doctor CLI (WU-1230)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Create temp directory for each test
+        testDir = mkdtempSync(join(tmpdir(), 'state-doctor-test-'));
+    });
+    afterEach(() => {
+        // Cleanup temp directory
+        try {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    });
+    describe('micro-worktree isolation', () => {
+        it('should use micro-worktree when --fix modifies tracked files', async () => {
+            // Setup: Create test state with broken events
+            setupTestState(testDir, {
+                wus: [],
+                events: [{ wuId: 'WU-999', type: 'claimed', timestamp: new Date().toISOString() }],
+            });
+            // Mock withMicroWorktree to track that it was called
+            const mockWithMicroWorktree = vi.mocked(withMicroWorktree);
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                // Execute the callback to simulate micro-worktree operations
+                const result = await options.execute({
+                    worktreePath: testDir,
+                    gitWorktree: {
+                        add: vi.fn(),
+                        addWithDeletions: vi.fn(),
+                        commit: vi.fn(),
+                        push: vi.fn(),
+                    },
+                });
+                return { ...result, ref: 'main' };
+            });
+            // Import and run the fix function
+            const { createStateDoctorFixDeps } = await import('../state-doctor-fix.js');
+            const deps = createStateDoctorFixDeps(testDir);
+            // When: Attempt to remove a broken event
+            await deps.removeEvent('WU-999');
+            // Then: micro-worktree should have been used
+            expect(mockWithMicroWorktree).toHaveBeenCalled();
+            expect(mockWithMicroWorktree).toHaveBeenCalledWith(expect.objectContaining({
+                operation: 'state-doctor',
+                pushOnly: true,
+            }));
+        });
+        it('should not directly modify files on main when --fix is used', async () => {
+            // Setup: Create test state with events file
+            const eventsPath = join(testDir, LUMENFLOW_DIR, STATE_DIR, 'wu-events.jsonl');
+            setupTestState(testDir, {
+                wus: [],
+                events: [{ wuId: 'WU-999', type: 'claimed', timestamp: new Date().toISOString() }],
+            });
+            const originalContent = readFileSync(eventsPath, 'utf-8');
+            // Mock withMicroWorktree to NOT actually modify files (simulating push-only mode)
+            const mockWithMicroWorktree = vi.mocked(withMicroWorktree);
+            mockWithMicroWorktree.mockResolvedValue({
+                commitMessage: 'fix: remove broken events',
+                files: ['.lumenflow/state/wu-events.jsonl'],
+                ref: 'main',
+            });
+            // Import and run the fix function
+            const { createStateDoctorFixDeps } = await import('../state-doctor-fix.js');
+            const deps = createStateDoctorFixDeps(testDir);
+            // When: Remove broken event
+            await deps.removeEvent('WU-999');
+            // Then: Original file on main should be unchanged
+            // (changes only happen in micro-worktree and pushed)
+            const currentContent = readFileSync(eventsPath, 'utf-8');
+            expect(currentContent).toBe(originalContent);
+        });
+    });
+    describe('backlog.md and status.md cleanup', () => {
+        it('should remove stale WU references from backlog.md when removing broken events', async () => {
+            // Setup: Create backlog.md with reference to WU that will be removed
+            setupTestState(testDir, {
+                wus: [],
+                events: [{ wuId: 'WU-999', type: 'claimed', timestamp: new Date().toISOString() }],
+                backlog: `# Backlog
+
+## In Progress
+
+- WU-999: Some old WU that no longer exists
+
+## Ready
+
+- WU-100: Valid WU
+`,
+            });
+            // Track the files that would be modified in micro-worktree
+            let capturedFiles = [];
+            const mockWithMicroWorktree = vi.mocked(withMicroWorktree);
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                const result = await options.execute({
+                    worktreePath: testDir,
+                    gitWorktree: {
+                        add: vi.fn(),
+                        addWithDeletions: vi.fn(),
+                        commit: vi.fn(),
+                        push: vi.fn(),
+                    },
+                });
+                capturedFiles = result.files;
+                return { ...result, ref: 'main' };
+            });
+            // Import and run the fix function
+            const { createStateDoctorFixDeps } = await import('../state-doctor-fix.js');
+            const deps = createStateDoctorFixDeps(testDir);
+            // When: Remove broken event for WU-999
+            await deps.removeEvent('WU-999');
+            // Then: backlog.md should be in the list of modified files
+            expect(capturedFiles).toContain(BACKLOG_PATH);
+        });
+        it('should remove stale WU references from status.md when removing broken events', async () => {
+            // Setup: Create status.md with reference to WU that will be removed
+            setupTestState(testDir, {
+                wus: [],
+                events: [{ wuId: 'WU-999', type: 'claimed', timestamp: new Date().toISOString() }],
+                status: `# Status
+
+## In Progress
+
+| Lane | WU | Title |
+|------|-----|-------|
+| Framework: CLI | WU-999 | Old WU |
+`,
+            });
+            // Track the files that would be modified
+            let capturedFiles = [];
+            const mockWithMicroWorktree = vi.mocked(withMicroWorktree);
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                const result = await options.execute({
+                    worktreePath: testDir,
+                    gitWorktree: {
+                        add: vi.fn(),
+                        addWithDeletions: vi.fn(),
+                        commit: vi.fn(),
+                        push: vi.fn(),
+                    },
+                });
+                capturedFiles = result.files;
+                return { ...result, ref: 'main' };
+            });
+            // Import and run the fix function
+            const { createStateDoctorFixDeps } = await import('../state-doctor-fix.js');
+            const deps = createStateDoctorFixDeps(testDir);
+            // When: Remove broken event for WU-999
+            await deps.removeEvent('WU-999');
+            // Then: status.md should be in the list of modified files
+            expect(capturedFiles).toContain(STATUS_PATH);
+        });
+    });
+    describe('commit and push behavior', () => {
+        it('should use pushOnly mode to avoid modifying local main', async () => {
+            setupTestState(testDir, {
+                wus: [],
+                events: [{ wuId: 'WU-999', type: 'claimed', timestamp: new Date().toISOString() }],
+            });
+            const mockWithMicroWorktree = vi.mocked(withMicroWorktree);
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                // Verify pushOnly is set
+                expect(options.pushOnly).toBe(true);
+                const result = await options.execute({
+                    worktreePath: testDir,
+                    gitWorktree: {
+                        add: vi.fn(),
+                        addWithDeletions: vi.fn(),
+                        commit: vi.fn(),
+                        push: vi.fn(),
+                    },
+                });
+                return { ...result, ref: 'main' };
+            });
+            const { createStateDoctorFixDeps } = await import('../state-doctor-fix.js');
+            const deps = createStateDoctorFixDeps(testDir);
+            await deps.removeEvent('WU-999');
+            // The assertion is inside the mock - if we get here without error, pushOnly was true
+            expect(mockWithMicroWorktree).toHaveBeenCalled();
+        });
+    });
+});
+function setupTestState(baseDir, state) {
+    // Create directories
+    const dirs = [
+        join(baseDir, LUMENFLOW_DIR, STATE_DIR),
+        join(baseDir, LUMENFLOW_DIR, STAMPS_DIR),
+        join(baseDir, LUMENFLOW_DIR, MEMORY_DIR),
+        join(baseDir, DOCS_TASKS_DIR, 'wu'),
+    ];
+    for (const dir of dirs) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Create events file
+    if (state.events && state.events.length > 0) {
+        const eventsPath = join(baseDir, LUMENFLOW_DIR, STATE_DIR, 'wu-events.jsonl');
+        const content = state.events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+        writeFileSync(eventsPath, content, 'utf-8');
+    }
+    // Create signals file
+    if (state.signals && state.signals.length > 0) {
+        const signalsPath = join(baseDir, LUMENFLOW_DIR, MEMORY_DIR, 'signals.jsonl');
+        const content = state.signals.map((s) => JSON.stringify(s)).join('\n') + '\n';
+        writeFileSync(signalsPath, content, 'utf-8');
+    }
+    // Create WU YAML files
+    if (state.wus) {
+        for (const wu of state.wus) {
+            const wuPath = join(baseDir, DOCS_TASKS_DIR, 'wu', `${wu.id}.yaml`);
+            const content = `id: ${wu.id}\nstatus: ${wu.status}\ntitle: ${wu.title || wu.id}\n`;
+            writeFileSync(wuPath, content, 'utf-8');
+        }
+    }
+    // Create backlog.md
+    if (state.backlog) {
+        const backlogPath = join(baseDir, BACKLOG_PATH);
+        writeFileSync(backlogPath, state.backlog, 'utf-8');
+    }
+    // Create status.md
+    if (state.status) {
+        const statusPath = join(baseDir, STATUS_PATH);
+        writeFileSync(statusPath, state.status, 'utf-8');
+    }
+}

package/dist/__tests__/wu-done.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ensureCleanWorktree } from '../wu-done-check.js';
+import * as gitAdapter from '@lumenflow/core/git-adapter';
+import * as errorHandler from '@lumenflow/core/error-handler';
+// Mock dependencies
+vi.mock('@lumenflow/core/git-adapter');
+vi.mock('@lumenflow/core/error-handler');
+describe('wu-done', () => {
+    describe('ensureCleanWorktree', () => {
+        let mockGit;
+        beforeEach(() => {
+            vi.resetAllMocks();
+            mockGit = {
+                getStatus: vi.fn(),
+            };
+            vi.mocked(gitAdapter.createGitForPath).mockReturnValue(mockGit);
+        });
+        it('should pass if worktree is clean', async () => {
+            mockGit.getStatus.mockResolvedValue(''); // Clean status
+            await ensureCleanWorktree('/path/to/worktree');
+            expect(mockGit.getStatus).toHaveBeenCalled();
+            expect(errorHandler.die).not.toHaveBeenCalled();
+        });
+        it('should die if worktree has uncommitted changes', async () => {
+            mockGit.getStatus.mockResolvedValue('M  file.ts\n?? new-file.ts'); // Dirty status
+            await ensureCleanWorktree('/path/to/worktree');
+            expect(mockGit.getStatus).toHaveBeenCalled();
+            expect(errorHandler.die).toHaveBeenCalledWith(expect.stringContaining('Worktree has uncommitted changes'));
+        });
+        it('should use the correct worktree path', async () => {
+            mockGit.getStatus.mockResolvedValue('');
+            await ensureCleanWorktree('/custom/worktree/path');
+            expect(gitAdapter.createGitForPath).toHaveBeenCalledWith('/custom/worktree/path');
+        });
+    });
+});

package/dist/__tests__/wu-edit.test.js

@@ -0,0 +1,119 @@
+/**
+ * WU-1225: Tests for wu-edit append-by-default behavior
+ *
+ * Validates that array fields (code_paths, risks, acceptance, etc.)
+ * now append by default instead of replacing, making behavior consistent
+ * across all array options.
+ */
+import { describe, it, expect } from 'vitest';
+import { applyEdits, mergeStringField } from '../wu-edit.js';
+describe('wu-edit applyEdits', () => {
+    describe('WU-1225: code_paths append-by-default', () => {
+        const baseWU = {
+            id: 'WU-1225',
+            status: 'ready',
+            code_paths: ['existing/path.ts'],
+        };
+        it('appends code_paths by default (no flags)', () => {
+            const opts = { codePaths: ['new/path.ts'] };
+            const result = applyEdits(baseWU, opts);
+            expect(result.code_paths).toEqual(['existing/path.ts', 'new/path.ts']);
+        });
+        it('appends code_paths when --append is set (backwards compat)', () => {
+            const opts = { codePaths: ['new/path.ts'], append: true };
+            const result = applyEdits(baseWU, opts);
+            expect(result.code_paths).toEqual(['existing/path.ts', 'new/path.ts']);
+        });
+        it('replaces code_paths when --replace-code-paths is set', () => {
+            const opts = { codePaths: ['new/path.ts'], replaceCodePaths: true };
+            const result = applyEdits(baseWU, opts);
+            expect(result.code_paths).toEqual(['new/path.ts']);
+        });
+    });
+    describe('WU-1225: risks append-by-default', () => {
+        const baseWU = {
+            id: 'WU-1225',
+            status: 'ready',
+            risks: ['existing risk'],
+        };
+        it('appends risks by default', () => {
+            const opts = { risks: ['new risk'] };
+            const result = applyEdits(baseWU, opts);
+            expect(result.risks).toEqual(['existing risk', 'new risk']);
+        });
+        it('replaces risks when --replace-risks is set', () => {
+            const opts = { risks: ['new risk'], replaceRisks: true };
+            const result = applyEdits(baseWU, opts);
+            expect(result.risks).toEqual(['new risk']);
+        });
+    });
+    describe('WU-1225: blocked_by append-by-default', () => {
+        const baseWU = {
+            id: 'WU-1225',
+            status: 'ready',
+            blocked_by: ['WU-100'],
+        };
+        it('appends blocked_by by default', () => {
+            const opts = { blockedBy: 'WU-200' };
+            const result = applyEdits(baseWU, opts);
+            expect(result.blocked_by).toEqual(['WU-100', 'WU-200']);
+        });
+        it('replaces blocked_by when --replace-blocked-by is set', () => {
+            const opts = { blockedBy: 'WU-200', replaceBlockedBy: true };
+            const result = applyEdits(baseWU, opts);
+            expect(result.blocked_by).toEqual(['WU-200']);
+        });
+    });
+    describe('WU-1225: dependencies append-by-default', () => {
+        const baseWU = {
+            id: 'WU-1225',
+            status: 'ready',
+            dependencies: ['WU-50'],
+        };
+        it('appends dependencies by default', () => {
+            const opts = { addDep: 'WU-60' };
+            const result = applyEdits(baseWU, opts);
+            expect(result.dependencies).toEqual(['WU-50', 'WU-60']);
+        });
+        it('replaces dependencies when --replace-dependencies is set', () => {
+            const opts = { addDep: 'WU-60', replaceDependencies: true };
+            const result = applyEdits(baseWU, opts);
+            expect(result.dependencies).toEqual(['WU-60']);
+        });
+    });
+    describe('WU-1144: acceptance already appends by default', () => {
+        const baseWU = {
+            id: 'WU-1225',
+            status: 'ready',
+            acceptance: ['existing criterion'],
+        };
+        it('appends acceptance by default', () => {
+            const opts = { acceptance: ['new criterion'] };
+            const result = applyEdits(baseWU, opts);
+            expect(result.acceptance).toEqual(['existing criterion', 'new criterion']);
+        });
+        it('replaces acceptance when --replace-acceptance is set', () => {
+            const opts = { acceptance: ['new criterion'], replaceAcceptance: true };
+            const result = applyEdits(baseWU, opts);
+            expect(result.acceptance).toEqual(['new criterion']);
+        });
+    });
+});
+describe('wu-edit mergeStringField', () => {
+    it('appends by default', () => {
+        const result = mergeStringField('existing', 'new', false);
+        expect(result).toBe('existing\n\nnew');
+    });
+    it('replaces when shouldReplace is true', () => {
+        const result = mergeStringField('existing', 'new', true);
+        expect(result).toBe('new');
+    });
+    it('returns new value if existing is empty', () => {
+        const result = mergeStringField('', 'new', false);
+        expect(result).toBe('new');
+    });
+    it('returns new value if existing is undefined', () => {
+        const result = mergeStringField(undefined, 'new', false);
+        expect(result).toBe('new');
+    });
+});

package/dist/__tests__/wu-prep.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as locationResolver from '@lumenflow/core/dist/context/location-resolver.js';
+import * as wuYaml from '@lumenflow/core/dist/wu-yaml.js';
+import { CONTEXT_VALIDATION, WU_STATUS } from '@lumenflow/core/dist/wu-constants.js';
+const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+// Mock dependencies
+vi.mock('@lumenflow/core/dist/context/location-resolver.js');
+vi.mock('@lumenflow/core/dist/error-handler.js');
+vi.mock('@lumenflow/core/dist/wu-yaml.js');
+vi.mock('../gates.js', () => ({
+    runGates: vi.fn().mockResolvedValue(true),
+}));
+describe('wu-prep (WU-1223)', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    describe('location validation', () => {
+        it('should error when run from main checkout', async () => {
+            // Mock location as main checkout
+            vi.mocked(locationResolver.resolveLocation).mockResolvedValue({
+                type: LOCATION_TYPES.MAIN,
+                cwd: '/repo',
+                gitRoot: '/repo',
+                mainCheckout: '/repo',
+                worktreeName: null,
+                worktreeWuId: null,
+            });
+            // Import after mocks are set up
+            const { resolveLocation } = await import('@lumenflow/core/dist/context/location-resolver.js');
+            const location = await resolveLocation();
+            // Verify the mock returns main
+            expect(location.type).toBe(LOCATION_TYPES.MAIN);
+        });
+        it('should proceed when run from worktree', async () => {
+            // Mock location as worktree
+            vi.mocked(locationResolver.resolveLocation).mockResolvedValue({
+                type: LOCATION_TYPES.WORKTREE,
+                cwd: '/repo/worktrees/framework-cli-wu-1223',
+                gitRoot: '/repo/worktrees/framework-cli-wu-1223',
+                mainCheckout: '/repo',
+                worktreeName: 'framework-cli-wu-1223',
+                worktreeWuId: 'WU-1223',
+            });
+            const { resolveLocation } = await import('@lumenflow/core/dist/context/location-resolver.js');
+            const location = await resolveLocation();
+            // Verify the mock returns worktree
+            expect(location.type).toBe(LOCATION_TYPES.WORKTREE);
+            expect(location.mainCheckout).toBe('/repo');
+        });
+    });
+    describe('WU status validation', () => {
+        it('should only allow in_progress WUs', async () => {
+            // Mock WU YAML with wrong status
+            const mockDoc = {
+                id: 'WU-1223',
+                status: WU_STATUS.DONE,
+                title: 'Test WU',
+            };
+            vi.mocked(wuYaml.readWU).mockReturnValue(mockDoc);
+            const { readWU } = await import('@lumenflow/core/dist/wu-yaml.js');
+            const doc = readWU('path/to/wu.yaml', 'WU-1223');
+            expect(doc.status).toBe(WU_STATUS.DONE);
+            expect(doc.status).not.toBe(WU_STATUS.IN_PROGRESS);
+        });
+    });
+    describe('success message', () => {
+        it('should include copy-paste instruction with main path', async () => {
+            // The success message should include:
+            // 1. Main checkout path
+            // 2. WU ID
+            // 3. Copy-paste command: cd <main> && pnpm wu:done --id <WU-ID>
+            const mainCheckout = '/repo';
+            const wuId = 'WU-1223';
+            // Build expected command that would be in the success message
+            const expectedCommand = `cd ${mainCheckout} && pnpm wu:done --id ${wuId}`;
+            expect(expectedCommand).toBe('cd /repo && pnpm wu:done --id WU-1223');
+        });
+    });
+});
+describe('wu:done worktree check (WU-1223)', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    it('should error when run from worktree with guidance to use wu:prep', async () => {
+        // Mock location as worktree
+        vi.mocked(locationResolver.resolveLocation).mockResolvedValue({
+            type: LOCATION_TYPES.WORKTREE,
+            cwd: '/repo/worktrees/framework-cli-wu-1223',
+            gitRoot: '/repo/worktrees/framework-cli-wu-1223',
+            mainCheckout: '/repo',
+            worktreeName: 'framework-cli-wu-1223',
+            worktreeWuId: 'WU-1223',
+        });
+        const { resolveLocation } = await import('@lumenflow/core/dist/context/location-resolver.js');
+        const location = await resolveLocation();
+        // The error message should guide user to wu:prep workflow
+        expect(location.type).toBe(LOCATION_TYPES.WORKTREE);
+        // Error message should contain:
+        const errorShouldContain = [
+            'wu:prep', // Mention the new command
+            'main checkout', // Explain where wu:done should run
+            '/repo', // Main checkout path
+        ];
+        // Build the expected error content
+        const expectedGuidance = `pnpm wu:prep --id WU-1223`;
+        expect(expectedGuidance).toContain('wu:prep');
+    });
+});

package/dist/agent-issues-query.js

@@ -243,9 +243,10 @@ async function main() {
     const issues = await readIssues(baseDir, sinceDate, opts.category, opts.severity);
     displaySummary(issues, opts.since);
 }
-// Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+if (import.meta.main) {
     main().catch((err) => {
         die(`Issues query failed: ${err.message}`);
     });

package/dist/agent-log-issue.js

@@ -6,11 +6,32 @@
  *
  * Usage:
  *   pnpm agent:log-issue --category workflow --severity minor --title "..." --description "..."
+ *   pnpm agent:log-issue --category tooling --severity major --title "..." --description "..." \
+ *     --tag worktree --tag gates --file src/main.ts --file src/utils.ts
+ *
+ * WU-1182: Uses Commander.js repeatable options pattern for --tag and --file.
+ * Use --tag multiple times instead of comma-separated --tags.
  */
 import { Command } from 'commander';
 import { logIncident, getCurrentSession } from '@lumenflow/agent';
 import { EXIT_CODES, INCIDENT_SEVERITY, LUMENFLOW_PATHS, } from '@lumenflow/core/dist/wu-constants.js';
 import chalk from 'chalk';
+/**
+ * WU-1182: Collector function for Commander.js repeatable options.
+ * Accumulates multiple flag values into an array.
+ *
+ * Usage: --tag a --tag b → ['a', 'b']
+ *
+ * This follows Commander.js best practices - use repeatable pattern for
+ * multi-value options instead of comma-separated splits.
+ *
+ * @param value - New value from CLI
+ * @param previous - Previously accumulated values
+ * @returns Updated array with new value appended
+ */
+function collectRepeatable(value, previous) {
+    return previous.concat([value]);
+}
 const program = new Command()
     .name('agent:log-issue')
     .description('Log a workflow issue or incident')
@@ -19,9 +40,9 @@ const program = new Command()
     .requiredOption('--title <title>', 'Short description (5-100 chars)')
     .requiredOption('--description <desc>', 'Detailed context (10-2000 chars)')
     .option('--resolution <res>', 'How the issue was resolved')
-    .option('--tags <tags>', 'Comma-separated tags (e.g., worktree,gates)')
+    .option('--tag <tag>', 'Tag for categorization (repeatable)', collectRepeatable, [])
     .option('--step <step>', 'Current workflow step (e.g., wu:done, gates)')
-    .option('--files <files>', 'Comma-separated related files')
+    .option('--file <file>', 'Related file path (repeatable)', collectRepeatable, [])
     .action(async (opts) => {
     try {
         const session = await getCurrentSession();
@@ -36,10 +57,10 @@ const program = new Command()
             title: opts.title,
             description: opts.description,
             resolution: opts.resolution,
-            tags: opts.tags ? opts.tags.split(',').map((t) => t.trim()) : [],
+            tags: opts.tag,
             context: {
                 current_step: opts.step,
-                related_files: opts.files ? opts.files.split(',').map((f) => f.trim()) : [],
+                related_files: opts.file,
             },
         };
         await logIncident(incident);

package/dist/backlog-prune.js

@@ -6,7 +6,7 @@
  * - Auto-tagging stale WUs (in_progress/ready too long without activity)
  * - Archiving old completed WUs (done for > N days)
  *
- * WU-1106: INIT-003 Phase 3b - Migrate from PatientPath tools/backlog-prune.mjs
+ * WU-1106: INIT-003 Phase 3b - Migrate from PatientPath tools/backlog-prune.ts
  *
  * Usage:
  *   pnpm backlog:prune           # Dry-run mode (shows what would be done)
@@ -291,9 +291,10 @@ async function main() {
     }
     process.exit(EXIT_CODES.SUCCESS);
 }
-// Guard main() for testability
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/dist/cli-entry-point.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-console -- CLI entry point uses console for error output */
 /**
  * Shared CLI entry point wrapper
  *
@@ -12,6 +13,10 @@
  *
  * WU-1085: Initializes color support respecting NO_COLOR/FORCE_COLOR/--no-color
  *
+ * WU-1233: Adds EPIPE protection for pipe resilience. When CLI output is piped
+ * through head/tail, the pipe may close before all output is written. Without
+ * this protection, Node.js throws unhandled EPIPE errors crashing the process.
+ *
  * @example
  * ```typescript
  * // At the bottom of each CLI file:
@@ -23,15 +28,20 @@
  * ```
  */
 import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
-import { initColorSupport } from '@lumenflow/core';
+import { initColorSupport, StreamErrorHandler } from '@lumenflow/core';
 /**
  * Wraps an async main function with proper error handling.
  * WU-1085: Also initializes color support based on NO_COLOR/FORCE_COLOR/--no-color
+ * WU-1233: Attaches EPIPE handler for graceful pipe closure
  *
  * @param main - The async main function to execute
  * @returns Promise that resolves when main completes (or after error handling)
  */
 export async function runCLI(main) {
+    // WU-1233: Attach EPIPE handler before running command
+    // This must be done early to catch any EPIPE errors during execution
+    const streamErrorHandler = StreamErrorHandler.createWithDefaults();
+    streamErrorHandler.attach();
     // WU-1085: Initialize color support before running command
     initColorSupport();
     try {