@principles/pd-cli 1.73.0

package/tests/commands/candidate-internalize.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleCandidateInternalize } from '../../src/commands/candidate.js';
+
+const { mockStateManager, MockRuntimeStateManager } = vi.hoisted(() => {
+  const mockStateManager = {
+    initialize: vi.fn().mockResolvedValue(undefined),
+    getCandidate: vi.fn(),
+    getTask: vi.fn().mockResolvedValue(null),
+    createTask: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+    connection: {
+      getDb: vi.fn(),
+    },
+  };
+
+  function MockRuntimeStateManager(this: any) {
+    return mockStateManager;
+  }
+  MockRuntimeStateManager.prototype = {};
+
+  return { mockStateManager, MockRuntimeStateManager };
+});
+
+vi.mock('@principles/core/runtime-v2', async (importOriginal) => {
+  const original = await importOriginal() as Record<string, unknown>;
+  return {
+    ...original,
+    RuntimeStateManager: MockRuntimeStateManager,
+    decideInternalizationRoute: vi.fn(),
+  };
+});
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/tmp/test-workspace'),
+}));
+
+import { decideInternalizationRoute } from '@principles/core/runtime-v2';
+
+const mockCandidate = (overrides: Partial<{
+  candidateId: string;
+  sourceRecommendationJson: string;
+  description: string;
+}> = {}) => ({
+  candidateId: overrides.candidateId ?? 'cand-001',
+  artifactId: 'art-001',
+  taskId: 'task-001',
+  sourceRunId: 'run-001',
+  title: 'Test Candidate',
+  description: overrides.description ?? 'Test description',
+  confidence: 0.85,
+  status: 'active',
+  createdAt: new Date().toISOString(),
+  sourceRecommendationJson: overrides.sourceRecommendationJson ?? JSON.stringify({
+    kind: 'principle',
+    description: 'Test principle',
+    abstractedPrinciple: 'Always handle errors',
+  }),
+});
+
+describe('handleCandidateInternalize (PRI-89)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockStateManager.getCandidate.mockResolvedValue(null);
+    mockStateManager.getTask.mockResolvedValue(null);
+    mockStateManager.createTask.mockResolvedValue({
+      taskId: 'dreamer-cand-001-prompt',
+      taskKind: 'dreamer',
+      status: 'pending',
+    });
+  });
+
+  it('valid actionable candidate creates root dreamer PI task', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate());
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'principle-ledger',
+      missingFields: [],
+      reason: 'Principle recommendation ready for ledger write path.',
+      nextAction: 'Proceed with principle-ledger intake.',
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleCandidateInternalize({
+      candidateId: 'cand-001',
+      workspace: '/tmp/test',
+      json: true,
+    });
+
+    expect(mockStateManager.createTask).toHaveBeenCalledOnce();
+    const createArg = (mockStateManager.createTask as ReturnType<typeof vi.fn>).mock.calls[0] as unknown[];
+    expect((createArg[0] as Record<string, unknown>).taskKind).toBe('dreamer');
+    expect((createArg[0] as Record<string, unknown>).status).toBe('pending');
+
+    const output = JSON.parse(consoleSpy.mock.calls[0]![0] as string);
+    expect(output.status).toBe('created');
+    expect(output.candidateId).toBe('cand-001');
+    expect(output.route).toBe('principle-ledger');
+    expect(output.channel).toBe('prompt');
+    expect(output.taskId).toBeDefined();
+
+    consoleSpy.mockRestore();
+  });
+
+  it('repeated seed returns existing task, no duplicate', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate());
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'principle-ledger',
+      missingFields: [],
+      reason: 'Ready',
+      nextAction: 'Proceed',
+    });
+    mockStateManager.getTask.mockResolvedValue({
+      taskId: 'dreamer-cand-001-prompt',
+      taskKind: 'dreamer',
+      status: 'pending',
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleCandidateInternalize({
+      candidateId: 'cand-001',
+      workspace: '/tmp/test',
+      json: true,
+    });
+
+    expect(mockStateManager.createTask).not.toHaveBeenCalled();
+    const output = JSON.parse(consoleSpy.mock.calls[0]![0] as string);
+    expect(output.status).toBe('existing');
+
+    consoleSpy.mockRestore();
+  });
+
+  it('--dry-run does not write database', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate());
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'principle-ledger',
+      missingFields: [],
+      reason: 'Ready',
+      nextAction: 'Proceed',
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleCandidateInternalize({
+      candidateId: 'cand-001',
+      workspace: '/tmp/test',
+      json: true,
+      dryRun: true,
+    });
+
+    expect(mockStateManager.createTask).not.toHaveBeenCalled();
+    const output = JSON.parse(consoleSpy.mock.calls[0]![0] as string);
+    expect(output.status).toBe('dry_run');
+
+    consoleSpy.mockRestore();
+  });
+
+  it('defer/non-actionable route returns no_task_created', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({ kind: 'defer', description: 'Skip' }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: false,
+      route: 'deferred',
+      missingFields: [],
+      reason: 'Recommendation explicitly deferred',
+      nextAction: 'No action needed',
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleCandidateInternalize({
+      candidateId: 'cand-001',
+      workspace: '/tmp/test',
+      json: true,
+    });
+
+    expect(mockStateManager.createTask).not.toHaveBeenCalled();
+    const output = JSON.parse(consoleSpy.mock.calls[0]![0] as string);
+    expect(output.status).toBe('no_task_created');
+
+    consoleSpy.mockRestore();
+  });
+
+  it('candidate not found returns structured error', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(null);
+
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await expect(
+      handleCandidateInternalize({
+        candidateId: 'nonexistent',
+        workspace: '/tmp/test',
+        json: true,
+      })
+    ).rejects.toThrow();
+
+    expect(mockStateManager.createTask).not.toHaveBeenCalled();
+
+    consoleSpy.mockRestore();
+  });
+
+  it('recommendation kind maps to correct channel', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({ kind: 'rule', description: 'Test rule', triggerPattern: 'test', action: 'do-thing' }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'rule-candidate',
+      missingFields: [],
+      reason: 'Rule ready',
+      nextAction: 'Proceed',
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleCandidateInternalize({
+      candidateId: 'cand-001',
+      workspace: '/tmp/test',
+      json: true,
+    });
+
+    const output = JSON.parse(consoleSpy.mock.calls[0]![0] as string);
+    expect(output.channel).toBe('code_tool_hook');
+
+    consoleSpy.mockRestore();
+  });
+
+  it('column fallback: sourceRecommendationJson empty but columns complete still creates task', async () => {
+    mockStateManager.getCandidate.mockResolvedValue({
+      candidateId: 'cand-fb-001',
+      artifactId: 'art-fb-001',
+      taskId: 'task-fb-001',
+      sourceRunId: 'run-fb-001',
+      title: 'Fallback Candidate',
+      description: 'Fallback desc',
+      confidence: 0.7,
+      status: 'active',
+      createdAt: new Date().toISOString(),
+      sourceRecommendationJson: undefined,
+    });
+
+    const mockPrepare = vi.fn().mockReturnValue({
+      get: vi.fn().mockReturnValue({
+        recommendation_kind: 'principle',
+        trigger_pattern: null,
+        action: null,
+        abstracted_principle: 'Always validate inputs',
+      }),
+    });
+    mockStateManager.connection.getDb.mockReturnValue({ prepare: mockPrepare });
+
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'principle-ledger',
+      missingFields: [],
+      reason: 'Principle ready (column fallback)',
+      nextAction: 'Proceed',
+    });
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleCandidateInternalize({
+      candidateId: 'cand-fb-001',
+      workspace: '/tmp/test',
+      json: true,
+    });
+
+    expect(mockStateManager.createTask).toHaveBeenCalledOnce();
+    const output = JSON.parse(consoleSpy.mock.calls[0]![0] as string);
+    expect(output.status).toBe('created');
+    expect(output.candidateId).toBe('cand-fb-001');
+
+    consoleSpy.mockRestore();
+  });
+});

package/tests/commands/candidate-route.test.ts

@@ -0,0 +1,328 @@
+/**
+ * PRI-46: pd candidate route — Internalization route inspection tests
+ *
+ * Tests that handleCandidateRoute correctly loads a candidate,
+ * reconstructs the recommendation, calls decideInternalizationRoute,
+ * and outputs the decision as JSON or text.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { handleCandidateRoute } from '../../src/commands/candidate.js';
+
+// ── Mock setup ──────────────────────────────────────────────────────────────
+
+const { mockStateManager, MockRuntimeStateManager } = vi.hoisted(() => {
+  const mockStateManager = {
+    initialize: vi.fn().mockResolvedValue(undefined),
+    getCandidate: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+    connection: {
+      getDb: vi.fn(),
+    },
+  };
+
+  function MockRuntimeStateManager(this: any) {
+    return mockStateManager;
+  }
+  MockRuntimeStateManager.prototype = {};
+
+  return { mockStateManager, MockRuntimeStateManager };
+});
+
+vi.mock('@principles/core/runtime-v2', () => ({
+  RuntimeStateManager: MockRuntimeStateManager,
+  decideInternalizationRoute: vi.fn(),
+}));
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/tmp/test-workspace'),
+}));
+
+import { decideInternalizationRoute } from '@principles/core/runtime-v2';
+
+// ── Test fixtures ───────────────────────────────────────────────────────────
+
+const mockCandidate = (overrides: Partial<{
+  candidateId: string;
+  sourceRecommendationJson: string;
+  description: string;
+}> = {}) => ({
+  candidateId: overrides.candidateId ?? 'cand-001',
+  artifactId: 'art-001',
+  taskId: 'task-001',
+  sourceRunId: 'run-001',
+  title: 'Test candidate',
+  description: overrides.description ?? 'Test recommendation',
+  confidence: 0.85,
+  sourceRecommendationJson: overrides.sourceRecommendationJson ?? JSON.stringify({
+    kind: 'rule',
+    description: 'Block force push',
+    triggerPattern: 'git\\s+push\\s+--force',
+    action: 'block and require approval',
+  }),
+  status: 'pending' as const,
+  createdAt: '2026-05-04T00:00:00.000Z',
+});
+
+let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+let exitSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+});
+
+afterEach(() => {
+  consoleLogSpy.mockRestore();
+  consoleErrorSpy.mockRestore();
+  exitSpy.mockRestore();
+  vi.clearAllMocks();
+});
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('handleCandidateRoute', () => {
+  // ── 1. Ready rule candidate ─────────────────────────────────────────────
+
+  it('ready rule candidate outputs JSON with ready=true and route=rule-candidate', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate());
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'rule-candidate',
+      missingFields: [],
+      reason: 'Rule recommendation ready for candidate pipeline.',
+      nextAction: 'Proceed with rule-candidate compilation.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-001', workspace: '/tmp/ws', json: true });
+
+    expect(exitSpy).not.toHaveBeenCalledWith(1);
+
+    const jsonOutput = consoleLogSpy.mock.calls.find(call => {
+      try { JSON.parse(call[0] as string); return true; } catch { return false; }
+    });
+    expect(jsonOutput).toBeDefined();
+    const parsed = JSON.parse((jsonOutput as [string])[0]);
+    expect(parsed.candidateId).toBe('cand-001');
+    expect(parsed.recommendationKind).toBe('rule');
+    expect(parsed.route).toBe('rule-candidate');
+    expect(parsed.ready).toBe(true);
+    expect(parsed.missingFields).toEqual([]);
+  });
+
+  // ── 2. Incomplete rule candidate ────────────────────────────────────────
+
+  it('incomplete rule candidate (missing triggerPattern) outputs ready=false with missingFields', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({
+        kind: 'rule',
+        description: 'Incomplete rule',
+        action: 'block',
+      }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: false,
+      route: 'rule-candidate',
+      missingFields: ['triggerPattern'],
+      reason: 'Rule recommendation incomplete: missing triggerPattern.',
+      nextAction: 'Re-run diagnostician with PHASE 4 taxonomy to generate missing rule fields.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-002', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.ready).toBe(false);
+    expect(parsed.missingFields).toContain('triggerPattern');
+    expect(parsed.route).toBe('rule-candidate');
+  });
+
+  // ── 3. Principle candidate ──────────────────────────────────────────────
+
+  it('principle candidate with abstractedPrinciple routes to principle-ledger', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({
+        kind: 'principle',
+        description: 'Avoid mixing concerns',
+        abstractedPrinciple: 'Separate concerns into distinct modules',
+      }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'principle-ledger',
+      missingFields: [],
+      reason: 'Principle recommendation ready for ledger write path.',
+      nextAction: 'Proceed with principle-ledger intake.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-003', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.route).toBe('principle-ledger');
+    expect(parsed.ready).toBe(true);
+    expect(parsed.recommendationKind).toBe('principle');
+  });
+
+  // ── 4. Implementation candidate ──────────────────────────────────────────
+
+  it('implementation candidate routes to implementation-candidate', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({
+        kind: 'implementation',
+        description: 'Auto-add error boundary to React components',
+      }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'implementation-candidate',
+      missingFields: [],
+      reason: 'Implementation recommendation ready for candidate pipeline.',
+      nextAction: 'Proceed with implementation-candidate intake and compilation.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-003b', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.route).toBe('implementation-candidate');
+    expect(parsed.ready).toBe(true);
+    expect(parsed.recommendationKind).toBe('implementation');
+  });
+
+  // ── 5. Prompt candidate ─────────────────────────────────────────────────
+
+  it('prompt candidate routes to prompt-injection-candidate', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({
+        kind: 'prompt',
+        description: 'Add safety reminder to system prompt',
+      }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'prompt-injection-candidate',
+      missingFields: [],
+      reason: 'Prompt recommendation ready for injection candidate pipeline.',
+      nextAction: 'Proceed with prompt-injection-candidate intake.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-004', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.route).toBe('prompt-injection-candidate');
+    expect(parsed.ready).toBe(true);
+  });
+
+  // ── 6. Defer candidate ──────────────────────────────────────────────────
+
+  it('defer candidate routes to deferred with ready=false', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({
+        kind: 'defer',
+        description: 'Not actionable yet',
+      }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: false,
+      route: 'deferred',
+      missingFields: [],
+      reason: 'Recommendation explicitly deferred — no internalization action required.',
+      nextAction: 'No action needed. Re-evaluate if context changes.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-005', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.route).toBe('deferred');
+    expect(parsed.ready).toBe(false);
+    expect(parsed.reason).toContain('deferred');
+  });
+
+  // ── 7. Unknown kind routes to deferred ──────────────────────────────────
+
+  it('unknown recommendation kind routes to deferred', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: JSON.stringify({
+        kind: 'unknown_nonsense',
+        description: 'Bad kind',
+      }),
+    }));
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: false,
+      route: 'deferred',
+      missingFields: [],
+      reason: 'Unrecognized recommendation kind "unknown_nonsense" — deferred to safe default.',
+      nextAction: 'Review diagnostician output for unsupported recommendation kind.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-005b', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.route).toBe('deferred');
+    expect(parsed.ready).toBe(false);
+    expect(parsed.recommendationKind).toBe('unknown_nonsense');
+  });
+
+  // ── 8. Candidate not found ──────────────────────────────────────────────
+
+  it('candidate not found exits 1 with error message', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(null);
+
+    await handleCandidateRoute({ candidateId: 'nonexistent', workspace: '/tmp/ws', json: true });
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('nonexistent'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  // ── 8. Malformed source_recommendation_json uses column fallback ────────
+
+  it('malformed source_recommendation_json falls back to DB columns', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate({
+      sourceRecommendationJson: 'not-valid-json{{{',
+    }));
+    mockStateManager.connection.getDb.mockReturnValue({
+      prepare: () => ({
+        get: () => ({
+          recommendation_kind: 'implementation',
+          trigger_pattern: null,
+          action: null,
+          abstracted_principle: null,
+        }),
+      }),
+    });
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'implementation-candidate',
+      missingFields: [],
+      reason: 'Implementation recommendation ready for candidate pipeline.',
+      nextAction: 'Proceed with implementation-candidate intake and compilation.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-006', workspace: '/tmp/ws', json: true });
+
+    const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(parsed.route).toBe('implementation-candidate');
+    expect(parsed.ready).toBe(true);
+    expect(parsed._meta?.source).toBe('column_fallback');
+  });
+
+  // ── 9. Text output includes route/ready/missingFields ───────────────────
+
+  it('text output includes route, ready, and missingFields', async () => {
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate());
+    (decideInternalizationRoute as ReturnType<typeof vi.fn>).mockReturnValue({
+      ready: true,
+      route: 'rule-candidate',
+      missingFields: [],
+      reason: 'Rule recommendation ready for candidate pipeline.',
+      nextAction: 'Proceed with rule-candidate compilation.',
+    });
+
+    await handleCandidateRoute({ candidateId: 'cand-001', workspace: '/tmp/ws', json: false });
+
+    const allOutput = consoleLogSpy.mock.calls.map(call => call[0]).join('\n');
+    expect(allOutput).toContain('cand-001');
+    expect(allOutput).toContain('rule-candidate');
+    expect(allOutput).toContain('Ready:          true');
+    expect(allOutput).toContain('(none)');
+  });
+});

package/tests/commands/candidate-show.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { mockCandidateShow, mockResolveWorkspaceDir } = vi.hoisted(() => ({
+  mockCandidateShow: vi.fn(),
+  mockResolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
+}));
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: mockResolveWorkspaceDir,
+}));
+
+vi.mock('../../src/commands/candidate.js', () => ({
+  handleCandidateShow: mockCandidateShow,
+  handleCandidateIntake: vi.fn(),
+  handleCandidateRoute: vi.fn(),
+  handleCandidateInternalize: vi.fn(),
+  handleCandidateAudit: vi.fn(),
+  handleCandidateInternalizationBackfill: vi.fn(),
+}));
+
+import { Command } from 'commander';
+
+function createTestProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+
+  const candidateCmd = program.command('candidate');
+
+  candidateCmd
+    .command('show [candidateId]')
+    .description('Show detail for a single principle candidate')
+    .requiredOption('-w, --workspace <path>', 'Workspace directory')
+    .option('--candidate-id <id>', 'Candidate ID (alternative to positional arg)')
+    .option('--json', 'Output raw JSON')
+    .action(async (candidateId, opts) => {
+      const resolvedId = opts.candidateId ?? candidateId;
+      if (!resolvedId) {
+        throw new Error('candidate ID is required (positional or --candidate-id)');
+      }
+      if (candidateId && opts.candidateId && candidateId !== opts.candidateId) {
+        throw new Error(`conflicting candidate IDs: positional="${candidateId}", --candidate-id="${opts.candidateId}"`);
+      }
+      await mockCandidateShow({ candidateId: resolvedId, ...opts });
+    });
+
+  return program;
+}
+
+describe('candidate show CLI', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCandidateShow.mockResolvedValue(undefined);
+  });
+
+  it('positional candidateId works', async () => {
+    const program = createTestProgram();
+    await program.parseAsync(['node', 'pd', 'candidate', 'show', 'c_123', '-w', '/ws']);
+
+    expect(mockCandidateShow).toHaveBeenCalledWith(
+      expect.objectContaining({ candidateId: 'c_123' }),
+    );
+  });
+
+  it('--candidate-id works', async () => {
+    const program = createTestProgram();
+    await program.parseAsync(['node', 'pd', 'candidate', 'show', '-w', '/ws', '--candidate-id', 'c_456']);
+
+    expect(mockCandidateShow).toHaveBeenCalledWith(
+      expect.objectContaining({ candidateId: 'c_456' }),
+    );
+  });
+
+  it('both positional and --candidate-id with same value works', async () => {
+    const program = createTestProgram();
+    await program.parseAsync(['node', 'pd', 'candidate', 'show', 'c_789', '-w', '/ws', '--candidate-id', 'c_789']);
+
+    expect(mockCandidateShow).toHaveBeenCalledWith(
+      expect.objectContaining({ candidateId: 'c_789' }),
+    );
+  });
+
+  it('conflicting positional and --candidate-id throws error', async () => {
+    const program = createTestProgram();
+    await expect(
+      program.parseAsync(['node', 'pd', 'candidate', 'show', 'c_a', '-w', '/ws', '--candidate-id', 'c_b']),
+    ).rejects.toThrow('conflicting candidate IDs');
+  });
+
+  it('neither positional nor --candidate-id throws error', async () => {
+    const program = createTestProgram();
+    await expect(
+      program.parseAsync(['node', 'pd', 'candidate', 'show', '-w', '/ws']),
+    ).rejects.toThrow('candidate ID is required');
+  });
+});