popeye-cli 2.2.0 → 2.7.0

package/tests/pipeline/skills/coverage-gate.test.ts

@@ -0,0 +1,370 @@
+/**
+ * Skill Coverage Gate tests — assertSkillCoverage with conditional roles.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  assertSkillCoverage,
+  ROLE_REQUIRED_USAGE,
+  PHASE_ORDER,
+} from '../../../src/pipeline/skills/coverage-gate.js';
+import type { SkillUsageEvent } from '../../../src/pipeline/skills/usage-registry.js';
+import type { PipelineState, PipelineRole, PipelinePhase } from '../../../src/pipeline/types.js';
+import { createDefaultPipelineState } from '../../../src/pipeline/types.js';
+
+/** Helper to create a usage event */
+function makeEvent(
+  role: PipelineRole,
+  phase: string = 'ROLE_PLANNING',
+): SkillUsageEvent {
+  return {
+    role,
+    phase: phase as SkillUsageEvent['phase'],
+    used_as: 'system_prompt',
+    skill_source: 'defaults',
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/** Helper to create pipeline state with overrides */
+function makePipeline(overrides: Partial<PipelineState> = {}): PipelineState {
+  return {
+    ...createDefaultPipelineState(),
+    ...overrides,
+  };
+}
+
+describe('assertSkillCoverage', () => {
+  describe('expected use — all active roles have usage', () => {
+    it('should pass when all active roles have recorded usage', () => {
+      const activeRoles: PipelineRole[] = [
+        'DISPATCHER', 'ARCHITECT', 'DB_EXPERT', 'BACKEND_PROGRAMMER',
+      ];
+      const events: SkillUsageEvent[] = [
+        makeEvent('ARCHITECT', 'ARCHITECTURE'),
+        makeEvent('DB_EXPERT', 'ROLE_PLANNING'),
+        makeEvent('BACKEND_PROGRAMMER', 'ROLE_PLANNING'),
+      ];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, events, pipeline);
+
+      expect(result.pass).toBe(true);
+      expect(result.missing).toHaveLength(0);
+      expect(result.covered).toContain('DISPATCHER');
+      expect(result.covered).toContain('ARCHITECT');
+    });
+  });
+
+  describe('fail case — active role missing usage', () => {
+    it('should fail when active UI_UX_SPECIALIST has no usage events', () => {
+      const activeRoles: PipelineRole[] = [
+        'DISPATCHER', 'ARCHITECT', 'UI_UX_SPECIALIST',
+      ];
+      const events: SkillUsageEvent[] = [
+        makeEvent('ARCHITECT', 'ARCHITECTURE'),
+        // UI_UX_SPECIALIST has no events
+      ];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, events, pipeline);
+
+      expect(result.pass).toBe(false);
+      expect(result.missing).toHaveLength(1);
+      expect(result.missing[0].role).toBe('UI_UX_SPECIALIST');
+      expect(result.missing[0].reason).toContain('No skill usage recorded');
+    });
+  });
+
+  describe('DISPATCHER — meta-only role always passes', () => {
+    it('should mark DISPATCHER as covered without any events', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER'],
+        [],
+        makePipeline({ activeRoles: ['DISPATCHER'] }),
+      );
+
+      expect(result.pass).toBe(true);
+      expect(result.covered).toContain('DISPATCHER');
+    });
+  });
+
+  describe('DEBUGGER — conditional on recovery', () => {
+    it('should pass when recoveryCount=0 (not required)', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'DEBUGGER'],
+        [],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'DEBUGGER'],
+          recoveryCount: 0,
+        }),
+      );
+
+      expect(result.pass).toBe(true);
+      expect(result.covered).toContain('DEBUGGER');
+    });
+
+    it('should fail when recoveryCount>0 and no usage events', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'DEBUGGER'],
+        [],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'DEBUGGER'],
+          recoveryCount: 1,
+        }),
+      );
+
+      expect(result.pass).toBe(false);
+      expect(result.missing).toHaveLength(1);
+      expect(result.missing[0].role).toBe('DEBUGGER');
+    });
+
+    it('should pass when recoveryCount>0 and usage recorded', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'DEBUGGER'],
+        [makeEvent('DEBUGGER', 'RECOVERY_LOOP')],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'DEBUGGER'],
+          recoveryCount: 2,
+        }),
+      );
+
+      expect(result.pass).toBe(true);
+      expect(result.covered).toContain('DEBUGGER');
+    });
+  });
+
+  describe('ARBITRATOR — conditional on arbitration', () => {
+    it('should pass when no arbitration artifacts exist', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'ARBITRATOR'],
+        [],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'ARBITRATOR'],
+          artifacts: [],
+        }),
+      );
+
+      expect(result.pass).toBe(true);
+      expect(result.covered).toContain('ARBITRATOR');
+    });
+
+    it('should fail when arbitration artifacts exist but no usage', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'ARBITRATOR'],
+        [],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'ARBITRATOR'],
+          artifacts: [{
+            id: 'arb-1',
+            type: 'arbitration',
+            phase: 'CONSENSUS_MASTER_PLAN',
+            version: 1,
+            path: 'docs/arbitration.json',
+            sha256: 'abc',
+            timestamp: new Date().toISOString(),
+            immutable: true,
+            content_type: 'json',
+            group_id: 'g1',
+          }],
+        }),
+      );
+
+      expect(result.pass).toBe(false);
+      expect(result.missing[0].role).toBe('ARBITRATOR');
+    });
+  });
+
+  describe('JOURNALIST — conditional on journal triggers', () => {
+    it('should pass when no journal-triggering phases completed', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'JOURNALIST'],
+        [],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'JOURNALIST'],
+          gateResults: {},
+        }),
+      );
+
+      expect(result.pass).toBe(true);
+    });
+
+    it('should fail when journal phase completed but no usage', () => {
+      const result = assertSkillCoverage(
+        ['DISPATCHER', 'JOURNALIST'],
+        [],
+        makePipeline({
+          activeRoles: ['DISPATCHER', 'JOURNALIST'],
+          gateResults: {
+            CONSENSUS_MASTER_PLAN: {
+              phase: 'CONSENSUS_MASTER_PLAN',
+              pass: true,
+              blockers: [],
+              missingArtifacts: [],
+              failedChecks: [],
+              timestamp: new Date().toISOString(),
+            },
+          },
+        }),
+      );
+
+      expect(result.pass).toBe(false);
+      expect(result.missing[0].role).toBe('JOURNALIST');
+    });
+  });
+
+  describe('ROLE_REQUIRED_USAGE configuration', () => {
+    it('should have entries for all 16 pipeline roles', () => {
+      const expectedRoles: PipelineRole[] = [
+        'DISPATCHER', 'ARCHITECT', 'DB_EXPERT', 'BACKEND_PROGRAMMER',
+        'FRONTEND_PROGRAMMER', 'WEBSITE_PROGRAMMER', 'UI_UX_SPECIALIST',
+        'MARKETING_EXPERT', 'SOCIAL_EXPERT', 'QA_TESTER', 'REVIEWER',
+        'ARBITRATOR', 'DEBUGGER', 'AUDITOR', 'JOURNALIST', 'RELEASE_MANAGER',
+      ];
+
+      for (const role of expectedRoles) {
+        expect(ROLE_REQUIRED_USAGE[role]).toBeDefined();
+      }
+    });
+  });
+
+  // ─── v2.4.5: Phase-aware deferral ────────────────────────
+
+  describe('phase-aware deferral (v2.4.5)', () => {
+    it('should defer AUDITOR at CONSENSUS_ROLE_PLANS', () => {
+      // AUDITOR requires AUDIT phase, which comes after CONSENSUS_ROLE_PLANS
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'AUDITOR'];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, [], pipeline, 'CONSENSUS_ROLE_PLANS');
+
+      expect(result.pass).toBe(true);
+      expect(result.deferred).toContain('AUDITOR');
+      expect(result.missing).toHaveLength(0);
+    });
+
+    it('should check AUDITOR at PRODUCTION_GATE (AUDIT <= PRODUCTION_GATE)', () => {
+      // AUDIT comes before PRODUCTION_GATE in PHASE_ORDER, so AUDITOR is checked
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'AUDITOR'];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, [], pipeline, 'PRODUCTION_GATE');
+
+      expect(result.pass).toBe(false);
+      expect(result.missing).toHaveLength(1);
+      expect(result.missing[0].role).toBe('AUDITOR');
+      expect(result.deferred).not.toContain('AUDITOR');
+    });
+
+    it('should pass AUDITOR at PRODUCTION_GATE with events', () => {
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'AUDITOR'];
+      const events = [makeEvent('AUDITOR', 'AUDIT')];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, events, pipeline, 'PRODUCTION_GATE');
+
+      expect(result.pass).toBe(true);
+      expect(result.covered).toContain('AUDITOR');
+      expect(result.deferred).toHaveLength(0);
+    });
+
+    it('should defer RELEASE_MANAGER at PRODUCTION_GATE (DONE > PRODUCTION_GATE)', () => {
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'RELEASE_MANAGER'];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, [], pipeline, 'PRODUCTION_GATE');
+
+      expect(result.pass).toBe(true);
+      expect(result.deferred).toContain('RELEASE_MANAGER');
+    });
+
+    it('should check QA_TESTER at CONSENSUS_ROLE_PLANS (ROLE_PLANNING <= CONSENSUS_ROLE_PLANS)', () => {
+      // QA_TESTER has phases [ROLE_PLANNING, QA_VALIDATION].
+      // ROLE_PLANNING comes before CONSENSUS_ROLE_PLANS, so QA_TESTER is checked.
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'QA_TESTER'];
+      const events = [makeEvent('QA_TESTER', 'ROLE_PLANNING')];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(activeRoles, events, pipeline, 'CONSENSUS_ROLE_PLANS');
+
+      expect(result.pass).toBe(true);
+      expect(result.covered).toContain('QA_TESTER');
+      expect(result.deferred).not.toContain('QA_TESTER');
+    });
+
+    it('should pass full production scenario at CONSENSUS_ROLE_PLANS', () => {
+      // Simulate real pipeline: all SUPPORT_ROLES + website impl roles active.
+      // Provide events only for roles through ROLE_PLANNING phase.
+      const activeRoles: PipelineRole[] = [
+        'DISPATCHER', 'ARCHITECT', 'QA_TESTER', 'REVIEWER', 'ARBITRATOR',
+        'DEBUGGER', 'AUDITOR', 'JOURNALIST', 'RELEASE_MANAGER',
+        'DB_EXPERT', 'BACKEND_PROGRAMMER', 'WEBSITE_PROGRAMMER',
+      ];
+      const events: SkillUsageEvent[] = [
+        makeEvent('ARCHITECT', 'ARCHITECTURE'),
+        makeEvent('DB_EXPERT', 'ROLE_PLANNING'),
+        makeEvent('BACKEND_PROGRAMMER', 'ROLE_PLANNING'),
+        makeEvent('WEBSITE_PROGRAMMER', 'ROLE_PLANNING'),
+        makeEvent('QA_TESTER', 'ROLE_PLANNING'),
+      ];
+      const pipeline = makePipeline({
+        activeRoles,
+        recoveryCount: 0,
+        artifacts: [],
+        gateResults: {},
+      });
+
+      const result = assertSkillCoverage(activeRoles, events, pipeline, 'CONSENSUS_ROLE_PLANS');
+
+      expect(result.pass).toBe(true);
+      // AUDITOR and RELEASE_MANAGER should be deferred
+      expect(result.deferred).toContain('AUDITOR');
+      expect(result.deferred).toContain('RELEASE_MANAGER');
+      // REVIEWER should also be deferred (REVIEW phase > CONSENSUS_ROLE_PLANS)
+      expect(result.deferred).toContain('REVIEWER');
+      // Conditional roles with no trigger are covered (not deferred)
+      expect(result.covered).toContain('ARBITRATOR');
+      expect(result.covered).toContain('DEBUGGER');
+      expect(result.covered).toContain('JOURNALIST');
+    });
+
+    it('should fall back to strict mode with unknown currentPhase', () => {
+      // An unknown phase not in PHASE_ORDER gets indexOf = -1, same as strict mode
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'AUDITOR'];
+      const pipeline = makePipeline({ activeRoles });
+
+      const result = assertSkillCoverage(
+        activeRoles, [], pipeline, 'SOME_NEW_PHASE' as PipelinePhase,
+      );
+
+      // Strict mode: AUDITOR is checked (not deferred) and fails
+      expect(result.pass).toBe(false);
+      expect(result.missing).toHaveLength(1);
+      expect(result.missing[0].role).toBe('AUDITOR');
+      expect(result.deferred).toHaveLength(0);
+    });
+
+    it('should use strict mode when currentPhase is omitted (backward compat)', () => {
+      const activeRoles: PipelineRole[] = ['DISPATCHER', 'AUDITOR'];
+      const pipeline = makePipeline({ activeRoles });
+
+      // No currentPhase param — same as original behavior
+      const result = assertSkillCoverage(activeRoles, [], pipeline);
+
+      expect(result.pass).toBe(false);
+      expect(result.missing).toHaveLength(1);
+      expect(result.missing[0].role).toBe('AUDITOR');
+      expect(result.deferred).toHaveLength(0);
+    });
+
+    it('PHASE_ORDER should include all key phases', () => {
+      const keyPhases: PipelinePhase[] = [
+        'INTAKE', 'CONSENSUS_ROLE_PLANS', 'PRODUCTION_GATE', 'DONE', 'STUCK',
+        'AUDIT', 'REVIEW', 'ARCHITECTURE', 'ROLE_PLANNING',
+      ];
+      for (const phase of keyPhases) {
+        expect(PHASE_ORDER).toContain(phase);
+      }
+    });
+  });
+});

package/tests/pipeline/skills/usage-registry.test.ts

@@ -0,0 +1,114 @@
+/**
+ * SkillUsageRegistry tests — recording, querying, and array reference sharing.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SkillUsageRegistry } from '../../../src/pipeline/skills/usage-registry.js';
+import type { SkillUsageEvent } from '../../../src/pipeline/skills/usage-registry.js';
+
+describe('SkillUsageRegistry', () => {
+  let events: SkillUsageEvent[];
+  let registry: SkillUsageRegistry;
+
+  beforeEach(() => {
+    events = [];
+    registry = new SkillUsageRegistry(events);
+  });
+
+  describe('record', () => {
+    it('should record a usage event with all fields', () => {
+      registry.record('ARCHITECT', 'ARCHITECTURE', 'system_prompt', 'defaults', '1.0');
+
+      const recorded = registry.getEvents();
+      expect(recorded).toHaveLength(1);
+      expect(recorded[0].role).toBe('ARCHITECT');
+      expect(recorded[0].phase).toBe('ARCHITECTURE');
+      expect(recorded[0].used_as).toBe('system_prompt');
+      expect(recorded[0].skill_source).toBe('defaults');
+      expect(recorded[0].skill_version).toBe('1.0');
+      expect(recorded[0].timestamp).toBeTruthy();
+    });
+
+    it('should record event without optional version', () => {
+      registry.record('REVIEWER', 'REVIEW', 'review_prompt', 'project_override');
+
+      const recorded = registry.getEvents();
+      expect(recorded).toHaveLength(1);
+      expect(recorded[0].skill_version).toBeUndefined();
+    });
+
+    it('should push into the shared array reference', () => {
+      registry.record('AUDITOR', 'AUDIT', 'system_prompt', 'defaults');
+
+      // The underlying events array should be mutated directly
+      expect(events).toHaveLength(1);
+      expect(events[0].role).toBe('AUDITOR');
+    });
+  });
+
+  describe('getEvents', () => {
+    it('should return a copy of events', () => {
+      registry.record('ARCHITECT', 'ARCHITECTURE', 'system_prompt', 'defaults');
+      const copy = registry.getEvents();
+
+      // Mutating the copy should not affect the original
+      copy.push({
+        role: 'DEBUGGER',
+        phase: 'RECOVERY_LOOP',
+        used_as: 'system_prompt',
+        skill_source: 'defaults',
+        timestamp: new Date().toISOString(),
+      });
+
+      expect(registry.getEvents()).toHaveLength(1);
+    });
+  });
+
+  describe('getEventsForRole', () => {
+    it('should filter events by role', () => {
+      registry.record('ARCHITECT', 'ARCHITECTURE', 'system_prompt', 'defaults');
+      registry.record('REVIEWER', 'REVIEW', 'review_prompt', 'defaults');
+      registry.record('ARCHITECT', 'CONSENSUS_ARCHITECTURE', 'other', 'defaults');
+
+      const architectEvents = registry.getEventsForRole('ARCHITECT');
+      expect(architectEvents).toHaveLength(2);
+      expect(architectEvents.every((e) => e.role === 'ARCHITECT')).toBe(true);
+    });
+
+    it('should return empty array for role with no events', () => {
+      registry.record('ARCHITECT', 'ARCHITECTURE', 'system_prompt', 'defaults');
+
+      const debuggerEvents = registry.getEventsForRole('DEBUGGER');
+      expect(debuggerEvents).toHaveLength(0);
+    });
+  });
+
+  describe('hasUsage', () => {
+    it('should return true for role with recorded events', () => {
+      registry.record('AUDITOR', 'AUDIT', 'system_prompt', 'defaults');
+
+      expect(registry.hasUsage('AUDITOR')).toBe(true);
+    });
+
+    it('should return false for role with no events', () => {
+      expect(registry.hasUsage('DEBUGGER')).toBe(false);
+    });
+  });
+
+  describe('state serialization', () => {
+    it('should round-trip through JSON correctly', () => {
+      registry.record('ARCHITECT', 'ARCHITECTURE', 'system_prompt', 'defaults', '1.0');
+      registry.record('REVIEWER', 'REVIEW', 'review_prompt', 'project_override', '2.0');
+
+      // Simulate state serialization
+      const serialized = JSON.stringify(events);
+      const deserialized = JSON.parse(serialized) as SkillUsageEvent[];
+
+      // Create new registry from deserialized data
+      const newRegistry = new SkillUsageRegistry(deserialized);
+      expect(newRegistry.getEvents()).toHaveLength(2);
+      expect(newRegistry.hasUsage('ARCHITECT')).toBe(true);
+      expect(newRegistry.hasUsage('REVIEWER')).toBe(true);
+    });
+  });
+});

package/tests/pipeline/strategy-context.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Strategy context loader tests — loadStrategyForRole, STRATEGY_ROLES.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { STRATEGY_ROLES, loadStrategyForRole } from '../../src/pipeline/strategy-context.js';
+
+const TEST_DIR = join(process.cwd(), 'tmp-strategy-context-test');
+
+function makeValidStrategy() {
+  return {
+    icp: { primaryPersona: 'developers', painPoints: ['slow builds'], goals: ['fast CI'], objections: ['cost'] },
+    positioning: { category: 'DevTools', differentiators: ['speed'], valueProposition: 'Build faster', proofPoints: ['10x'] },
+    messaging: { headline: 'Build Faster', subheadline: 'CI that works', elevatorPitch: 'Fast CI', longDescription: 'A fast CI platform' },
+    seoStrategy: { primaryKeywords: ['CI'], secondaryKeywords: ['build'], longTailKeywords: ['fast CI'], titleTemplates: {}, metaDescriptions: {} },
+    siteArchitecture: {
+      pages: [{ path: '/', title: 'Home', purpose: 'Landing', pageType: 'landing', sections: ['hero'], seoKeywords: ['CI'], conversionGoal: 'signup' }],
+      navigation: [{ label: 'Home', href: '/' }],
+      footerSections: [{ title: 'Links', links: [{ label: 'Home', href: '/' }] }],
+    },
+    conversionStrategy: {
+      primaryCta: { text: 'Get Started', href: '/signup' },
+      secondaryCta: { text: 'Learn More', href: '/docs' },
+      trustSignals: ['SOC2'],
+      socialProof: ['1000+ teams'],
+      leadCapture: 'webhook',
+    },
+    competitiveContext: { category: 'CI/CD', competitors: ['CircleCI'], differentiators: ['speed'] },
+  };
+}
+
+beforeEach(() => {
+  mkdirSync(join(TEST_DIR, '.popeye'), { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});
+
+describe('STRATEGY_ROLES', () => {
+  it('includes exactly WEBSITE_PROGRAMMER, MARKETING_EXPERT, SOCIAL_EXPERT', () => {
+    expect(STRATEGY_ROLES).toContain('WEBSITE_PROGRAMMER');
+    expect(STRATEGY_ROLES).toContain('MARKETING_EXPERT');
+    expect(STRATEGY_ROLES).toContain('SOCIAL_EXPERT');
+    expect(STRATEGY_ROLES).toHaveLength(3);
+  });
+});
+
+describe('loadStrategyForRole', () => {
+  it('returns undefined when no strategy file exists', () => {
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns formatted string when valid .popeye/website-strategy.json exists', () => {
+    const strategy = makeValidStrategy();
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.json'),
+      JSON.stringify(strategy),
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBeDefined();
+    expect(result).toContain('Target Customer');
+    expect(result).toContain('developers');
+    expect(result).toContain('Build Faster');
+    expect(result).toContain('SEO Keywords');
+    expect(result).toContain('Conversion Strategy');
+  });
+
+  it('handles nested strategy field in JSON', () => {
+    const strategy = makeValidStrategy();
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.json'),
+      JSON.stringify({ strategy, metadata: { inputHash: 'abc', generatedAt: '2025-01-01', version: 1 } }),
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBeDefined();
+    expect(result).toContain('developers');
+  });
+
+  it('returns undefined for malformed JSON', () => {
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.json'),
+      '{ invalid json!!!',
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined for JSON that fails schema validation', () => {
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.json'),
+      JSON.stringify({ icp: { primaryPersona: '' } }),
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBeUndefined();
+  });
+
+  it('falls back to .popeye/website-strategy.md when JSON absent', () => {
+    const mdContent = '# Strategy\n\nTarget: developers\nKeywords: CI, build';
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.md'),
+      mdContent,
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBe(mdContent);
+  });
+
+  it('prefers JSON over MD when both exist', () => {
+    const strategy = makeValidStrategy();
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.json'),
+      JSON.stringify(strategy),
+    );
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.md'),
+      '# Fallback MD',
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    // JSON is checked first, should get formatted strategy not raw MD
+    expect(result).toContain('Target Customer');
+    expect(result).not.toContain('Fallback MD');
+  });
+
+  it('falls back to MD when JSON is malformed', () => {
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.json'),
+      '{ bad json }',
+    );
+    writeFileSync(
+      join(TEST_DIR, '.popeye', 'website-strategy.md'),
+      '# Good MD Strategy',
+    );
+
+    const result = loadStrategyForRole(TEST_DIR);
+    expect(result).toBe('# Good MD Strategy');
+  });
+});