@boyingliu01/xp-gate 0.6.0 → 0.6.2

package/lib/__tests__/audit-log.test.ts

@@ -0,0 +1,107 @@
+/**
+ * @test audit-log
+ * @intent Verify UI gate bypass audit logging and threshold reporting
+ * @covers AUDIT-LOG-001
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  appendAuditEntry,
+  readAllEntries,
+  countBypassesInWindow,
+  exceedsBypassThreshold,
+  formatRetroReport,
+  type AuditEntry,
+} from '../audit-log';
+
+const TEST_DIR = join(process.cwd(), '.audit-log-test');
+
+function baseEntry(overrides: Partial<Omit<AuditEntry, 'gate_count'>> = {}): Omit<AuditEntry, 'gate_count'> {
+  return {
+    timestamp: new Date().toISOString(),
+    branch: 'main',
+    commit: 'abc123',
+    user: 'tester',
+    reason: 'manual approval for test',
+    bypass_type: 'ui-gates',
+    ...overrides,
+  };
+}
+
+describe('audit-log', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe('appendAuditEntry and readAllEntries', () => {
+    it('should append an entry and compute gate_count', () => {
+      const first = appendAuditEntry(baseEntry(), TEST_DIR);
+      const second = appendAuditEntry(baseEntry({ commit: 'def456' }), TEST_DIR);
+
+      expect(first.gate_count).toBe(0);
+      expect(second.gate_count).toBe(1);
+
+      const entries = readAllEntries(join(TEST_DIR, '.audit-log.jsonl'));
+      expect(entries).toHaveLength(2);
+      expect(entries[1].commit).toBe('def456');
+    });
+
+    it('should return empty array when log file is missing or empty', () => {
+      expect(readAllEntries(join(TEST_DIR, 'missing.jsonl'))).toEqual([]);
+      const emptyLog = join(TEST_DIR, '.audit-log.jsonl');
+      writeFileSync(emptyLog, '', 'utf8');
+      expect(readAllEntries(emptyLog)).toEqual([]);
+    });
+  });
+
+  describe('rolling window calculations', () => {
+    it('should count only matching bypass type in rolling window', () => {
+      const now = new Date();
+      const old = new Date(now.getTime() - 40 * 24 * 60 * 60 * 1000).toISOString();
+      const entries: AuditEntry[] = [
+        { ...baseEntry({ timestamp: now.toISOString(), bypass_type: 'ui-gates' }), gate_count: 0 },
+        { ...baseEntry({ timestamp: now.toISOString(), bypass_type: 'other' }), gate_count: 0 },
+        { ...baseEntry({ timestamp: old, bypass_type: 'ui-gates' }), gate_count: 0 },
+      ];
+
+      expect(countBypassesInWindow(entries, 'ui-gates')).toBe(1);
+    });
+
+    it('should report threshold exceedance', () => {
+      const entries: AuditEntry[] = Array.from({ length: 4 }, (_, i) => ({
+        ...baseEntry({ commit: `commit-${i}` }),
+        gate_count: i,
+      }));
+      expect(exceedsBypassThreshold(entries, 'ui-gates')).toEqual({ exceeded: true, count: 4 });
+    });
+  });
+
+  describe('formatRetroReport', () => {
+    it('should include recent bypasses and threshold warning', () => {
+      const entries: AuditEntry[] = Array.from({ length: 4 }, (_, i) => ({
+        ...baseEntry({ reason: `reason-${i}`, branch: `branch-${i}` }),
+        gate_count: i,
+      }));
+      const report = formatRetroReport(entries, 'ui-gates');
+      expect(report).toContain('Last 30 days: 4 bypasses');
+      expect(report).toContain('EXCEEDS threshold');
+      expect(report).toContain('reason-3');
+    });
+
+    it('should omit recent section when no matching bypasses exist', () => {
+      const report = formatRetroReport([], 'ui-gates');
+      expect(report).toContain('Last 30 days: 0 bypasses');
+      expect(report).not.toContain('Recent bypasses');
+    });
+  });
+});

package/lib/__tests__/detect-deps.test.js

@@ -1,6 +1,8 @@
 /**
  * @test detect-deps
- * @intent Verify checkDeps() correctly detects missing/present/outdated dependencies
+ * @intent Verify checkDeps() correctly detects missing/present/outdated dependencies across platforms,
+ *         detectPlatform() identifies the correct AI agent platform,
+ *         and autoInstallDeps() handles install scenarios
  */
 const fs = require('fs');
 const path = require('path');
@@ -16,6 +18,7 @@ describe('detect-deps', () => {
     process.env.HOME = tmpHome;
     vi.resetModules();
     delete require.cache[require.resolve('../detect-deps')];
+    delete require.cache[require.resolve('../shared-paths')];
   });
 
   afterEach(() => {
@@ -24,8 +27,10 @@ describe('detect-deps', () => {
     vi.restoreAllMocks();
   });
 
-  function makeSkillDir(skillName, contents = {}) {
-    const dir = path.join(tmpHome, '.config', 'opencode', 'skills', skillName);
+  function makeSkillDir(skillName, contents = {}, baseDir) {
+    const dir = baseDir
+      ? path.join(baseDir, skillName)
+      : path.join(tmpHome, '.config', 'opencode', 'skills', skillName);
     fs.mkdirSync(dir, { recursive: true });
     if (contents.packageJson) {
       fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(contents.packageJson));
@@ -48,6 +53,8 @@ describe('detect-deps', () => {
     return dir;
   }
 
+  // ── checkDeps: backward-compatible tests (default platform = opencode) ──
+
   it('returns ok:false missing:superpowers when no deps exist', async () => {
     const { checkDeps } = require('../detect-deps');
     const result = await checkDeps();
@@ -127,7 +134,6 @@ describe('detect-deps', () => {
   });
 
   it('returns ok:true (no version check) when package.json has no version and no SKILL.md', async () => {
-    // getSkillVersion returns null → skips version check → ok
     makeSkillDir('superpowers', { packageJson: {} });
     makeSkillDir('gstack', { packageJson: {} });
     const { checkDeps } = require('../detect-deps');
@@ -147,13 +153,8 @@ describe('detect-deps', () => {
   });
 
   it('returns null version when neither package.json nor SKILL.md exist (skips version check)', async () => {
-    // Create empty dirs (no metadata files)
-    fs.mkdirSync(path.join(tmpHome, '.config', 'opencode', 'skills', 'superpowers'), {
-      recursive: true,
-    });
-    fs.mkdirSync(path.join(tmpHome, '.config', 'opencode', 'skills', 'gstack'), {
-      recursive: true,
-    });
+    fs.mkdirSync(path.join(tmpHome, '.config', 'opencode', 'skills', 'superpowers'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, '.config', 'opencode', 'skills', 'gstack'), { recursive: true });
     const { checkDeps } = require('../detect-deps');
     const result = await checkDeps();
     expect(result.ok).toBe(true);
@@ -164,17 +165,14 @@ describe('detect-deps', () => {
     makeSkillDir('gstack', { packageJson: { version: '1.0.0' } });
     const { checkDeps } = require('../detect-deps');
     const result = await checkDeps();
-    // superpowers version=null → skips version check → ok
     expect(result.ok).toBe(true);
   });
 
-  it('compareVersions handles partial versions (e.g. 1.0 treated as 1.0.0)', async () => {
-    // version "1.0" in SKILL.md regex requires X.Y.Z so won't match; use package.json
+  it('compareVersions handles partial versions (e.g. 1 treated as 1.0.0)', async () => {
     makeSkillDir('superpowers', { packageJson: { version: '1' } });
     makeSkillDir('gstack', { packageJson: { version: '1.0.0' } });
     const { checkDeps } = require('../detect-deps');
     const result = await checkDeps();
-    // '1' parsed as [1] vs [1,0,0] → equal at index 0; index 1: 0 vs 0; index 2: 0 vs 0 → equal → passes
     expect(result.ok).toBe(true);
   });
 
@@ -196,14 +194,187 @@ describe('detect-deps', () => {
   });
 
   it('prefers SKILLS_DIR over OPENCODE_DIR when both exist', async () => {
-    // Put low version in SKILLS_DIR, high in OPENCODE_DIR
     makeSkillDir('superpowers', { packageJson: { version: '0.0.1' } });
     makeOpencodeDir('superpowers', { packageJson: { version: '2.0.0' } });
     makeSkillDir('gstack', { packageJson: { version: '1.0.0' } });
     const { checkDeps } = require('../detect-deps');
     const result = await checkDeps();
-    // Should use SKILLS_DIR (first in possiblePaths) → 0.0.1 fails
     expect(result.ok).toBe(false);
     expect(result.versionMismatch.found).toBe('0.0.1');
   });
+
+  // ── Platform-specific tests (Issue #128) ──
+
+  describe('checkDeps with platform parameter', () => {
+    it('qoder: checks ~/.qoder/skills/ for dependencies', async () => {
+      const qoderSkills = path.join(tmpHome, '.qoder', 'skills');
+      makeSkillDir('superpowers', { packageJson: { version: '2.0.0' } }, path.join(qoderSkills, 'superpowers'));
+      makeSkillDir('gstack', { packageJson: { version: '1.0.0' } }, path.join(qoderSkills, 'gstack'));
+      const { checkDeps } = require('../detect-deps');
+      const result = await checkDeps('qoder');
+      expect(result.ok).toBe(true);
+    });
+
+    it('qoder: returns missing when qoder skills dir is empty', async () => {
+      fs.mkdirSync(path.join(tmpHome, '.qoder', 'skills'), { recursive: true });
+      const { checkDeps } = require('../detect-deps');
+      const result = await checkDeps('qoder');
+      expect(result.ok).toBe(false);
+      expect(result.missing).toBe('superpowers');
+    });
+
+    it('claude-code: checks ~/.claude/skills/ for dependencies', async () => {
+      const claudeSkills = path.join(tmpHome, '.claude', 'skills');
+      makeSkillDir('superpowers', { packageJson: { version: '2.0.0' } }, path.join(claudeSkills, 'superpowers'));
+      makeSkillDir('gstack', { packageJson: { version: '1.0.0' } }, path.join(claudeSkills, 'gstack'));
+      const { checkDeps } = require('../detect-deps');
+      const result = await checkDeps('claude-code');
+      expect(result.ok).toBe(true);
+    });
+
+    it('claude-code: returns missing when claude skills dir is empty', async () => {
+      fs.mkdirSync(path.join(tmpHome, '.claude', 'skills'), { recursive: true });
+      const { checkDeps } = require('../detect-deps');
+      const result = await checkDeps('claude-code');
+      expect(result.ok).toBe(false);
+      expect(result.missing).toBe('superpowers');
+    });
+
+    it('unknown platform falls back to opencode profile', async () => {
+      makeSkillDir('superpowers', { packageJson: { version: '2.0.0' } });
+      makeSkillDir('gstack', { packageJson: { version: '1.0.0' } });
+      const { checkDeps } = require('../detect-deps');
+      const result = await checkDeps('unknown-platform');
+      expect(result.ok).toBe(true);
+    });
+
+    it('qoder platform does NOT find deps in opencode dir', async () => {
+      // Put deps in opencode dir but NOT in qoder dir
+      makeSkillDir('superpowers', { packageJson: { version: '2.0.0' } });
+      makeSkillDir('gstack', { packageJson: { version: '1.0.0' } });
+      const { checkDeps } = require('../detect-deps');
+      const result = await checkDeps('qoder');
+      expect(result.ok).toBe(false);
+      expect(result.missing).toBe('superpowers');
+    });
+  });
+
+  // ── detectPlatform tests ──
+
+  describe('detectPlatform', () => {
+    it('returns "qoder" when ~/.qoder/skills/ exists', () => {
+      fs.mkdirSync(path.join(tmpHome, '.qoder', 'skills'), { recursive: true });
+      const { detectPlatform } = require('../detect-deps');
+      expect(detectPlatform()).toBe('qoder');
+    });
+
+    it('returns "claude-code" when ~/.claude/skills/ exists', () => {
+      fs.mkdirSync(path.join(tmpHome, '.claude', 'skills'), { recursive: true });
+      const { detectPlatform } = require('../detect-deps');
+      expect(detectPlatform()).toBe('claude-code');
+    });
+
+    it('returns "opencode" as default when no platform dirs exist', () => {
+      const { detectPlatform } = require('../detect-deps');
+      expect(detectPlatform()).toBe('opencode');
+    });
+
+    it('prefers qoder over claude-code when both exist', () => {
+      fs.mkdirSync(path.join(tmpHome, '.qoder', 'skills'), { recursive: true });
+      fs.mkdirSync(path.join(tmpHome, '.claude', 'skills'), { recursive: true });
+      const { detectPlatform } = require('../detect-deps');
+      expect(detectPlatform()).toBe('qoder');
+    });
+  });
+
+  // ── getSkillsDirs tests ──
+
+  describe('getSkillsDirs', () => {
+    it('returns opencode paths for opencode platform', () => {
+      const { getSkillsDirs } = require('../detect-deps');
+      const dirs = getSkillsDirs('opencode');
+      expect(dirs[0]).toContain('.config');
+      expect(dirs[0]).toContain('opencode');
+    });
+
+    it('returns qoder paths for qoder platform', () => {
+      const { getSkillsDirs } = require('../detect-deps');
+      const dirs = getSkillsDirs('qoder');
+      expect(dirs[0]).toContain('.qoder');
+    });
+
+    it('returns claude-code paths for claude-code platform', () => {
+      const { getSkillsDirs } = require('../detect-deps');
+      const dirs = getSkillsDirs('claude-code');
+      expect(dirs[0]).toContain('.claude');
+    });
+  });
+
+  // ── PLATFORM_PROFILES tests ──
+
+  describe('PLATFORM_PROFILES', () => {
+    it('all platforms have requiredDeps defined', () => {
+      const { PLATFORM_PROFILES } = require('../detect-deps');
+      expect(PLATFORM_PROFILES.opencode.requiredDeps.length).toBe(2);
+      expect(PLATFORM_PROFILES.qoder.requiredDeps.length).toBe(2);
+      expect(PLATFORM_PROFILES['claude-code'].requiredDeps.length).toBe(2);
+    });
+
+    it('all platforms have skillsDirs defined', () => {
+      const { PLATFORM_PROFILES } = require('../detect-deps');
+      expect(PLATFORM_PROFILES.opencode.skillsDirs.length).toBeGreaterThan(0);
+      expect(PLATFORM_PROFILES.qoder.skillsDirs.length).toBeGreaterThan(0);
+      expect(PLATFORM_PROFILES['claude-code'].skillsDirs.length).toBeGreaterThan(0);
+    });
+  });
+
+  // ── autoInstallDeps tests ──
+
+  describe('autoInstallDeps', () => {
+    it('returns ok:true with empty installed when deps already exist', async () => {
+      makeSkillDir('superpowers', { packageJson: { version: '2.0.0' } });
+      makeSkillDir('gstack', { packageJson: { version: '1.0.0' } });
+      const { autoInstallDeps } = require('../detect-deps');
+      const result = await autoInstallDeps();
+      expect(result.ok).toBe(true);
+      expect(result.installed).toEqual([]);
+    });
+
+    it('creates skills directory if it does not exist', async () => {
+      const { autoInstallDeps } = require('../detect-deps');
+      // Mock execSync to avoid actual git clone
+      const { execSync } = require('child_process');
+      vi.spyOn(require('child_process'), 'execSync').mockImplementation((cmd) => {
+        // Simulate successful clone by creating the target dir
+        const match = cmd.match(/"([^"]+)"$/);
+        if (match) {
+          fs.mkdirSync(match[1], { recursive: true });
+          fs.writeFileSync(path.join(match[1], 'package.json'), JSON.stringify({ version: '2.0.0' }));
+        }
+        return '';
+      });
+
+      const result = await autoInstallDeps();
+      // Should have attempted to install
+      expect(result.ok).toBe(true);
+      expect(result.installed).toContain('superpowers');
+      expect(result.installed).toContain('gstack');
+
+      vi.restoreAllMocks();
+    });
+
+    it('returns errors when git clone fails', async () => {
+      const { autoInstallDeps } = require('../detect-deps');
+      vi.spyOn(require('child_process'), 'execSync').mockImplementation(() => {
+        throw new Error('git not found');
+      });
+
+      const result = await autoInstallDeps();
+      expect(result.ok).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors[0].message).toContain('git not found');
+
+      vi.restoreAllMocks();
+    });
+  });
 });

package/lib/__tests__/doctor.test.js

@@ -27,6 +27,7 @@ describe('doctor', () => {
     delete require.cache[require.resolve('../uninstall')];
     delete require.cache[require.resolve('../init')];
     delete require.cache[require.resolve('../detect-deps.js')];
+    delete require.cache[require.resolve('../shared-paths')];
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});

package/lib/__tests__/gate-audit.test.ts

@@ -11,6 +11,8 @@ import {
   readTailEntries,
   computeStats,
   rotateIfNeeded,
+  parseCliOptions,
+  getCommitHash,
   type GateAuditEntry,
 } from '../gate-audit';
 
@@ -114,6 +116,28 @@ describe('gate-audit', () => {
       const tail = readTailEntries(undefined, repoRoot);
       expect(tail.length).toBe(20);
     });
+
+    it('should skip malformed JSON lines', () => {
+      const repoRoot = join(TEST_DIR, 'malformed-tail');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(
+        join(logDir, 'audit.jsonl'),
+        `not-json\n${JSON.stringify(makeEntry({ repo_path: repoRoot, gate_id: 'gate-valid' }))}\n`,
+        'utf8',
+      );
+      const tail = readTailEntries(10, repoRoot);
+      expect(tail.length).toBe(1);
+      expect(tail[0].gate_id).toBe('gate-valid');
+    });
+
+    it('should return empty array for empty log file', () => {
+      const repoRoot = join(TEST_DIR, 'empty-log');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(join(logDir, 'audit.jsonl'), '', 'utf8');
+      expect(readTailEntries(10, repoRoot)).toEqual([]);
+    });
   });
 
   describe('computeStats', () => {
@@ -153,6 +177,41 @@ describe('gate-audit', () => {
       const stats = computeStats(repoRoot);
       expect(stats[0].avg_issues).toBe(2.67);
     });
+
+    it('should return empty array for empty stats log', () => {
+      const repoRoot = join(TEST_DIR, 'empty-stats-log');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(join(logDir, 'audit.jsonl'), '', 'utf8');
+      expect(computeStats(repoRoot)).toEqual([]);
+    });
+
+    it('should skip malformed lines during stats aggregation', () => {
+      const repoRoot = join(TEST_DIR, 'malformed-stats');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(
+        join(logDir, 'audit.jsonl'),
+        `${JSON.stringify(makeEntry({ repo_path: repoRoot, gate_id: 'gate-1' }))}\n{bad json}\n`,
+        'utf8',
+      );
+      const stats = computeStats(repoRoot);
+      expect(stats).toHaveLength(1);
+      expect(stats[0].gate_id).toBe('gate-1');
+    });
+  });
+
+  describe('CLI helpers', () => {
+    it('should parse CLI options and skip dangling flags', () => {
+      expect(parseCliOptions(['--gate-id', 'gate-1', '--passed', 'true', '--dangling'])).toEqual({
+        'gate-id': 'gate-1',
+        passed: 'true',
+      });
+    });
+
+    it('should return a commit hash string or unknown', () => {
+      expect(typeof getCommitHash()).toBe('string');
+    });
   });
 
   describe('rotateIfNeeded', () => {

package/lib/__tests__/init.test.js

@@ -24,6 +24,7 @@ describe('init', () => {
     vi.resetModules();
     delete require.cache[require.resolve('../init')];
     delete require.cache[require.resolve('../detect-deps.js')];
+    delete require.cache[require.resolve('../shared-paths')];
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
@@ -102,6 +103,13 @@ describe('init', () => {
   });
 
   it('init([]) with missing superpowers warns Missing dependencies', async () => {
+    // Mock execSync to make auto-install fail immediately
+    vi.spyOn(childProcess, 'execSync').mockImplementation((cmd) => {
+      if (typeof cmd === 'string' && cmd.includes('git clone')) {
+        throw new Error('git clone not available in test');
+      }
+      return '';
+    });
     const { init } = require('../init');
     const result = await init([]);
     expect(result).toBe(0);
@@ -110,6 +118,13 @@ describe('init', () => {
   });
 
   it('init([]) with versionMismatch warns version detail', async () => {
+    // Mock execSync to make auto-install fail immediately
+    vi.spyOn(childProcess, 'execSync').mockImplementation((cmd) => {
+      if (typeof cmd === 'string' && cmd.includes('git clone')) {
+        throw new Error('git clone not available in test');
+      }
+      return '';
+    });
     // superpowers too old, gstack good
     const sp = path.join(skillsDir(), 'superpowers');
     fs.mkdirSync(sp, { recursive: true });

package/lib/__tests__/install-skill.test.js

@@ -69,6 +69,7 @@ describe('install-skill', () => {
     vi.resetModules();
     delete require.cache[require.resolve('../install-skill')];
     delete require.cache[require.resolve('../detect-deps')];
+    delete require.cache[require.resolve('../shared-paths')];
     delete require.cache[require.resolve('../download-skill')];
     delete require.cache[require.resolve('../rollback')];
     vi.spyOn(console, 'log').mockImplementation(() => {});

package/lib/__tests__/ui-detector.test.ts

@@ -114,7 +114,63 @@ describe('ui-detector', () => {
     it('should handle git command failure gracefully', async () => {
       mockExecSync.mockImplementation(() => {
         throw new Error('git not available');
-      });
+  describe('collectUiMatches and detectUiSprint', () => {
+    it('should detect UI files in components directory', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/components/Button.tsx', 'src/utils/helper.ts']);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toEqual(['src/components/Button.tsx']);
+      expect(result.matchedRules.length).toBeGreaterThan(0);
+    });
+
+    it('should exclude test files from matching', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/components/Button.test.tsx']);
+      expect(result.isUiSprint).toBe(false);
+      expect(result.matchedFiles).toEqual([]);
+    });
+
+    it('should exclude coverage directory files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['coverage/components/Coverage.tsx']);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should handle empty file list', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([]);
+      expect(result.isUiSprint).toBe(false);
+      expect(result.matchedFiles).toEqual([]);
+    });
+
+    it('should collect multiple UI files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Header.tsx',
+        'src/utils/api.ts',
+        'views/styles/app.css',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toHaveLength(2);
+    });
+
+    it('should aggregate unique rules across files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Button.tsx',
+        'src/components/Card.tsx',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles.length).toBeGreaterThan(0);
+    });
+
+    it('should respect .ui-gate-ignore patterns', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const withoutIgnore = collectUiMatches(['legacy/components/Old.tsx']);
+      expect(withoutIgnore.isUiSprint).toBe(true);
+    });
+  });
+});
       const { detectUiSprint } = await import('../ui-detector');
       const result = detectUiSprint();
       expect(result.isUiSprint).toBe(false);
@@ -197,4 +253,59 @@ describe('ui-detector', () => {
       expect(rules).toContain('style-.css');
     });
   });
+
+  describe('collectUiMatches', () => {
+    it('should detect UI files in components directory', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/components/Button.tsx', 'src/utils/helper.ts']);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toEqual(['src/components/Button.tsx']);
+      expect(result.matchedRules.length).toBeGreaterThan(0);
+    });
+
+    it('should exclude __tests__ directory files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/__tests__/Button.test.tsx']);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should exclude src/__snapshots__ directory files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/__snapshots__/Button.test.tsx.snap']);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should handle empty file list', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([]);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should collect multiple UI files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Header.tsx',
+        'src/utils/api.ts',
+        'views/styles/app.css',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toHaveLength(2);
+    });
+
+    it('should collect unique rules across files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Button.tsx',
+        'src/components/Card.tsx',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles.length).toBeGreaterThan(0);
+    });
+
+    it('should respect .ui-gate-ignore patterns', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const withoutIgnore = collectUiMatches(['legacy/components/Old.tsx']);
+      expect(withoutIgnore.isUiSprint).toBe(true);
+    });
+  });
 });