specweave 1.0.486 → 1.0.488

package/dist/src/core/skill-gen/drift-detector.d.ts

@@ -1,24 +1,24 @@
 /**
  * Drift Detector — compares project-local skills against current living docs.
  *
- * Runs during living docs sync. Warns when skills reference modules or APIs
- * that no longer appear in the analysis output.
+ * Runs during living docs sync. Returns structured DriftResult[] when skills
+ * reference modules or APIs that no longer appear in the analysis output.
  *
  * Error-isolated: never throws, never blocks sync.
  *
  * @module core/skill-gen/drift-detector
  */
+import type { DriftResult } from './types.js';
 export declare class DriftDetector {
     private projectRoot;
     constructor(projectRoot: string);
     /**
      * Check project-local skills for stale references.
-     * Never throws.
+     * Returns structured DriftResult[] — never throws.
      */
-    check(): Promise<void>;
+    check(): Promise<DriftResult[]>;
     private getSkillFiles;
     private loadDocsContent;
-    private collectMarkdownFiles;
     private extractModuleReferences;
 }
 //# sourceMappingURL=drift-detector.d.ts.map

package/dist/src/core/skill-gen/drift-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drift-detector.d.ts","sourceRoot":"","sources":["../../../../src/core/skill-gen/drift-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,qBAAa,aAAa;IACxB,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM;IAI/B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAuCd,aAAa;YASb,eAAe;YAoBf,oBAAoB;IAkBlC,OAAO,CAAC,uBAAuB;CAchC"}
+{"version":3,"file":"drift-detector.d.ts","sourceRoot":"","sources":["../../../../src/core/skill-gen/drift-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAsB9C,qBAAa,aAAa;IACxB,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM;IAI/B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YA0CvB,aAAa;YASb,eAAe;IAoB7B,OAAO,CAAC,uBAAuB;CAiBhC"}

package/dist/src/core/skill-gen/drift-detector.js

@@ -1,8 +1,8 @@
 /**
  * Drift Detector — compares project-local skills against current living docs.
  *
- * Runs during living docs sync. Warns when skills reference modules or APIs
- * that no longer appear in the analysis output.
+ * Runs during living docs sync. Returns structured DriftResult[] when skills
+ * reference modules or APIs that no longer appear in the analysis output.
  *
  * Error-isolated: never throws, never blocks sync.
  *
@@ -10,18 +10,31 @@
  */
 import { readFile, readdir, stat } from 'fs/promises';
 import { join } from 'path';
+import { collectMarkdownFiles } from './utils.js';
 /**
  * Extracts capitalized multi-word identifiers that look like module/class names.
  * Matches PascalCase identifiers (e.g., AuthModule, OldModule, CoreService).
  */
 const MODULE_NAME_PATTERN = /\b([A-Z][a-z]+(?:[A-Z][a-z]+)+)\b/g;
+/**
+ * Common PascalCase words that are not project-specific module references.
+ * These are excluded from drift detection to reduce false positives.
+ */
+const PASCAL_CASE_EXCLUSIONS = new Set([
+    'TypeScript', 'JavaScript', 'SpecWeave', 'ReactComponent', 'NextJs',
+    'NodeModule', 'ErrorBoundary', 'PascalCase', 'CamelCase', 'GraphQL',
+    'TypeORM', 'PostgreSQL', 'MongoDB', 'CloudFlare', 'GitHub', 'GitLab',
+    'BitBucket', 'WebSocket', 'OAuth', 'OpenAPI', 'AsyncIterator', 'EventEmitter',
+    'ReadStream', 'WriteStream', 'AbortController', 'RegExp', 'ArrayBuffer',
+    'SharedWorker', 'ServiceWorker', 'IndexedDB', 'LocalStorage', 'SessionStorage',
+]);
 export class DriftDetector {
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
     /**
      * Check project-local skills for stale references.
-     * Never throws.
+     * Returns structured DriftResult[] — never throws.
      */
     async check() {
         try {
@@ -30,30 +43,32 @@ export class DriftDetector {
             try {
                 const st = await stat(skillsDir);
                 if (!st.isDirectory())
-                    return;
+                    return [];
             }
             catch {
-                return; // No skills directory
+                return []; // No skills directory
             }
             const skillFiles = await this.getSkillFiles(skillsDir);
             if (skillFiles.length === 0)
-                return;
+                return [];
             const docsContent = await this.loadDocsContent();
             if (!docsContent)
-                return;
+                return [];
             const docsLower = docsContent.toLowerCase();
+            const results = [];
             for (const skillFile of skillFiles) {
                 const content = await readFile(join(skillsDir, skillFile), 'utf-8');
                 const moduleRefs = this.extractModuleReferences(content);
                 const staleRefs = moduleRefs.filter((ref) => !docsLower.includes(ref.toLowerCase()));
-                if (staleRefs.length > 0) {
-                    console.warn(`[DriftDetector] Possible stale references in ${skillFile}: ${staleRefs.join(', ')}. These modules no longer appear in living docs.`);
+                const validRefs = moduleRefs.filter((ref) => docsLower.includes(ref.toLowerCase()));
+                if (staleRefs.length > 0 || validRefs.length > 0) {
+                    results.push({ skillFile, staleRefs, validRefs });
                 }
             }
+            return results;
         }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            console.warn(`[DriftDetector] Warning: ${msg}`);
+        catch {
+            return [];
         }
     }
     async getSkillFiles(dir) {
@@ -68,7 +83,7 @@ export class DriftDetector {
     async loadDocsContent() {
         const docsDir = join(this.projectRoot, '.specweave', 'docs', 'internal');
         try {
-            const files = await this.collectMarkdownFiles(docsDir);
+            const files = await collectMarkdownFiles(docsDir);
             if (files.length === 0)
                 return null;
             const contents = [];
@@ -86,34 +101,16 @@ export class DriftDetector {
             return null;
         }
     }
-    async collectMarkdownFiles(dir) {
-        const results = [];
-        try {
-            const entries = await readdir(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                const fullPath = join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    results.push(...(await this.collectMarkdownFiles(fullPath)));
-                }
-                else if (entry.name.endsWith('.md')) {
-                    results.push(fullPath);
-                }
-            }
-        }
-        catch {
-            // Skip
-        }
-        return results;
-    }
     extractModuleReferences(content) {
         const matches = new Set();
         let match;
         // Reset regex state
         MODULE_NAME_PATTERN.lastIndex = 0;
         while ((match = MODULE_NAME_PATTERN.exec(content)) !== null) {
-            // Skip common false positives
             const name = match[1];
-            if (!['README', 'SKILL', 'CHANGELOG', 'LICENSE', 'TODO'].includes(name.toUpperCase())) {
+            // Skip common false positives and excluded PascalCase words
+            if (!['README', 'SKILL', 'CHANGELOG', 'LICENSE', 'TODO'].includes(name.toUpperCase()) &&
+                !PASCAL_CASE_EXCLUSIONS.has(name)) {
                 matches.add(name);
             }
         }

package/dist/src/core/skill-gen/drift-detector.js.map

@@ -1 +1 @@
-{"version":3,"file":"drift-detector.js","sourceRoot":"","sources":["../../../../src/core/skill-gen/drift-detector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"drift-detector.js","sourceRoot":"","sources":["../../../../src/core/skill-gen/drift-detector.ts"],"names":[],"mappings":"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"}

package/dist/src/core/skill-gen/signal-collector.d.ts

@@ -1,9 +1,9 @@
 /**
- * Signal Collector — detects recurring patterns from living docs output.
+ * Signal Collector — detects recurring patterns from living docs using LLM analysis.
  *
  * Runs on every increment closure (wired into LifecycleHookDispatcher.onIncrementDone).
- * Reads markdown files from .specweave/docs/internal/, extracts pattern candidates,
- * and persists them to .specweave/state/skill-signals.json.
+ * Reads markdown files from .specweave/docs/internal/, sends them to the LLM for
+ * pattern extraction, and persists results to .specweave/state/skill-signals.json.
  *
  * Error-isolated: never throws, never blocks increment closure.
  *
@@ -24,21 +24,19 @@ export declare class SignalCollector {
      */
     collect(incrementId: string): Promise<void>;
     /**
-     * Load signal store from disk, recovering from corruption.
+     * Seed mode: scan all living docs and populate the signal store
+     * without associating patterns with any increment.
      */
-    private loadStore;
+    collectSeed(): Promise<void>;
     /**
-     * Save signal store to disk.
+     * Detect patterns via LLM analysis of markdown files.
+     * Handles batching when total tokens exceed TOKEN_BUDGET.
      */
-    private saveStore;
+    private detectPatternsLLM;
     /**
-     * Detect patterns from living docs markdown files.
+     * Build the user prompt with <documents> block.
      */
-    private detectPatterns;
-    /**
-     * Recursively collect markdown files from a directory.
-     */
-    private collectMarkdownFiles;
+    private buildPrompt;
     /**
      * Create or update a signal entry.
      */

package/dist/src/core/skill-gen/signal-collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal-collector.d.ts","sourceRoot":"","sources":["../../../../src/core/skill-gen/signal-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwDH,UAAU,gBAAgB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAS;gBAEnB,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAM3D;;;OAGG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjD;;OAEG;YACW,SAAS;IAmBvB;;OAEG;YACW,SAAS;IAOvB;;OAEG;YACW,cAAc;IA8B5B;;OAEG;YACW,oBAAoB;IAkBlC;;OAEG;IACH,OAAO,CAAC,YAAY;IA4CpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc;CAGvB"}
+{"version":3,"file":"signal-collector.d.ts","sourceRoot":"","sources":["../../../../src/core/skill-gen/signal-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH,UAAU,gBAAgB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAwBD,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAS;gBAEnB,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAM3D;;;OAGG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BjD;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAmDlC;;;OAGG;YACW,iBAAiB;IAgF/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,OAAO,CAAC,YAAY;IA8DpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc;CAGvB"}

package/dist/src/core/skill-gen/signal-collector.js

@@ -1,64 +1,39 @@
 /**
- * Signal Collector — detects recurring patterns from living docs output.
+ * Signal Collector — detects recurring patterns from living docs using LLM analysis.
  *
  * Runs on every increment closure (wired into LifecycleHookDispatcher.onIncrementDone).
- * Reads markdown files from .specweave/docs/internal/, extracts pattern candidates,
- * and persists them to .specweave/state/skill-signals.json.
+ * Reads markdown files from .specweave/docs/internal/, sends them to the LLM for
+ * pattern extraction, and persists results to .specweave/state/skill-signals.json.
  *
  * Error-isolated: never throws, never blocks increment closure.
  *
  * @module core/skill-gen/signal-collector
  */
-import { readFile, writeFile, readdir, mkdir, copyFile } from 'fs/promises';
+import { readFile } from 'fs/promises';
 import { join, relative } from 'path';
-import { EMPTY_SIGNAL_STORE, SKILL_GEN_DEFAULTS } from './types.js';
-/**
- * Pattern detection categories with keyword indicators.
- * A category is detected when 3+ keywords appear in a single file.
- */
-const PATTERN_CATEGORIES = {
-    'error-handling': {
-        keywords: ['error-handling', 'error handling', 'try/catch', 'error boundar', 'catch block', 'error middleware'],
-        description: 'Consistent error handling patterns',
-    },
-    'naming-conventions': {
-        keywords: ['naming convention', 'file naming', 'variable naming', 'kebab-case', 'camelCase', 'PascalCase'],
-        description: 'Consistent naming convention patterns',
-    },
-    'architecture-patterns': {
-        keywords: ['architecture pattern', 'module organization', 'dependency injection', 'clean architecture', 'layered', 'hexagonal'],
-        description: 'Architectural organization patterns',
-    },
-    'testing-patterns': {
-        keywords: ['test pattern', 'mock pattern', 'test organization', 'test fixture', 'test factory', 'test helper'],
-        description: 'Testing convention patterns',
-    },
-    'api-patterns': {
-        keywords: ['api pattern', 'api boundary', 'endpoint pattern', 'route pattern', 'validation', 'zod', 'schema validation'],
-        description: 'API design and validation patterns',
-    },
-    'auth-patterns': {
-        keywords: ['auth pattern', 'authentication', 'authorization', 'jwt', 'session', 'oauth', 'auth middleware'],
-        description: 'Authentication and authorization patterns',
-    },
-    'data-model': {
-        keywords: ['data model', 'database', 'schema', 'migration', 'orm', 'prisma', 'typeorm', 'sequelize'],
-        description: 'Data model and database patterns',
-    },
-    'state-management': {
-        keywords: ['state management', 'redux', 'zustand', 'context', 'store', 'global state'],
-        description: 'State management patterns',
-    },
-    'integration-patterns': {
-        keywords: ['integration', 'external api', 'third-party', 'webhook', 'event-driven', 'message queue'],
-        description: 'External integration patterns',
-    },
-    'build-deploy': {
-        keywords: ['build pattern', 'deploy', 'ci/cd', 'pipeline', 'docker', 'containeriz'],
-        description: 'Build and deployment patterns',
+import { SKILL_GEN_DEFAULTS } from './types.js';
+import { collectMarkdownFiles, loadSignalStore, saveSignalStore, sanitizeString, estimateTokenCount, capEvidence, TOKEN_BUDGET, } from './utils.js';
+import { loadLLMConfig, createProvider, hasLLMConfig } from '../llm/provider-factory.js';
+const LLM_PATTERN_SCHEMA = {
+    type: 'object',
+    properties: {
+        patterns: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    category: { type: 'string', description: 'Kebab-case category slug' },
+                    name: { type: 'string', description: 'Short pattern name' },
+                    description: { type: 'string', description: 'What and why' },
+                    evidence: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['category', 'name', 'description', 'evidence'],
+            },
+        },
     },
+    required: ['patterns'],
 };
-const MIN_KEYWORD_HITS = 3;
+const SYSTEM_PROMPT = `You are a software architecture analyst. Given project documentation, identify recurring implementation patterns. Return structured JSON only.`;
 export class SignalCollector {
     constructor(projectRoot, options) {
         this.projectRoot = projectRoot;
@@ -71,137 +46,216 @@ export class SignalCollector {
      */
     async collect(incrementId) {
         try {
-            const store = await this.loadStore();
+            if (!hasLLMConfig(this.projectRoot)) {
+                console.warn('[skill-gen] No LLM config found — skipping pattern detection');
+                return;
+            }
             const docsDir = join(this.projectRoot, '.specweave', 'docs', 'internal');
-            const patterns = await this.detectPatterns(docsDir);
+            const files = await collectMarkdownFiles(docsDir);
+            if (files.length === 0)
+                return;
+            const config = loadLLMConfig(this.projectRoot);
+            if (!config)
+                return;
+            const provider = await createProvider(config);
+            const patterns = await this.detectPatternsLLM(files, provider);
+            const store = await loadSignalStore(this.getSignalsPath());
             for (const detected of patterns) {
-                this.upsertSignal(store, detected, incrementId);
+                this.upsertSignal(store, detected, incrementId, files);
             }
             this.pruneIfNeeded(store);
-            await this.saveStore(store);
+            await saveSignalStore(this.getSignalsPath(), store);
         }
         catch (error) {
-            // Error-isolated: log and continue
             const msg = error instanceof Error ? error.message : String(error);
             console.warn(`[SignalCollector] Warning: ${msg}`);
         }
     }
     /**
-     * Load signal store from disk, recovering from corruption.
+     * Seed mode: scan all living docs and populate the signal store
+     * without associating patterns with any increment.
      */
-    async loadStore() {
-        const signalsPath = this.getSignalsPath();
+    async collectSeed() {
         try {
-            const content = await readFile(signalsPath, 'utf-8');
-            return JSON.parse(content);
-        }
-        catch (error) {
-            if (error?.code === 'ENOENT') {
-                return { ...EMPTY_SIGNAL_STORE, signals: [] };
+            if (!hasLLMConfig(this.projectRoot)) {
+                console.warn('[skill-gen] No LLM config found — skipping seed');
+                return;
             }
-            // Corrupted file — backup and start fresh
-            try {
-                await copyFile(signalsPath, signalsPath + '.bak');
-            }
-            catch {
-                // backup failed, continue anyway
+            const docsDir = join(this.projectRoot, '.specweave', 'docs', 'internal');
+            const files = await collectMarkdownFiles(docsDir);
+            if (files.length === 0)
+                return;
+            const config = loadLLMConfig(this.projectRoot);
+            if (!config)
+                return;
+            const provider = await createProvider(config);
+            const patterns = await this.detectPatternsLLM(files, provider);
+            const store = await loadSignalStore(this.getSignalsPath());
+            const now = new Date().toISOString();
+            for (const pattern of patterns) {
+                const existingKey = store.signals.find(s => s.category === pattern.category && s.pattern === sanitizeString(pattern.name));
+                if (existingKey)
+                    continue; // Skip duplicates
+                const newSignal = {
+                    id: `sig-${sanitizeString(pattern.category)}-${sanitizeString(pattern.name)}`,
+                    pattern: sanitizeString(pattern.name),
+                    category: sanitizeString(pattern.category),
+                    description: sanitizeString(pattern.description),
+                    incrementIds: [],
+                    firstSeen: now,
+                    lastSeen: now,
+                    confidence: 0,
+                    evidence: capEvidence(pattern.evidence.map(e => sanitizeString(e))),
+                    uniqueSourceFiles: files.map(f => relative(this.projectRoot, f)),
+                    suggested: false,
+                    declined: false,
+                    generated: false,
+                };
+                store.signals.push(newSignal);
             }
-            return { ...EMPTY_SIGNAL_STORE, signals: [] };
+            await saveSignalStore(this.getSignalsPath(), store);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.warn(`[SignalCollector] Warning: ${msg}`);
         }
     }
     /**
-     * Save signal store to disk.
-     */
-    async saveStore(store) {
-        const signalsPath = this.getSignalsPath();
-        const dir = join(this.projectRoot, '.specweave', 'state');
-        await mkdir(dir, { recursive: true });
-        await writeFile(signalsPath, JSON.stringify(store, null, 2));
-    }
-    /**
-     * Detect patterns from living docs markdown files.
+     * Detect patterns via LLM analysis of markdown files.
+     * Handles batching when total tokens exceed TOKEN_BUDGET.
      */
-    async detectPatterns(docsDir) {
-        const files = await this.collectMarkdownFiles(docsDir);
-        const detectedMap = new Map();
+    async detectPatternsLLM(files, provider) {
+        // Read files and estimate tokens
+        const docs = [];
         for (const filePath of files) {
             try {
-                const content = (await readFile(filePath, 'utf-8')).toLowerCase();
+                const content = await readFile(filePath, 'utf-8');
                 const relPath = relative(this.projectRoot, filePath);
-                for (const [category, { keywords }] of Object.entries(PATTERN_CATEGORIES)) {
-                    const hits = keywords.filter((kw) => content.includes(kw.toLowerCase()));
-                    if (hits.length >= MIN_KEYWORD_HITS) {
-                        const existing = detectedMap.get(category) || [];
-                        if (!existing.includes(relPath)) {
-                            existing.push(relPath);
-                        }
-                        detectedMap.set(category, existing);
-                    }
-                }
+                docs.push({ path: relPath, content, tokens: estimateTokenCount(content) });
             }
             catch {
                 // Skip unreadable files
             }
         }
-        return Array.from(detectedMap.entries()).map(([category, evidence]) => ({
-            category,
-            evidence,
-        }));
-    }
-    /**
-     * Recursively collect markdown files from a directory.
-     */
-    async collectMarkdownFiles(dir) {
-        const results = [];
-        try {
-            const entries = await readdir(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                const fullPath = join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    results.push(...(await this.collectMarkdownFiles(fullPath)));
-                }
-                else if (entry.name.endsWith('.md')) {
-                    results.push(fullPath);
-                }
+        if (docs.length === 0)
+            return [];
+        const totalTokens = docs.reduce((sum, d) => sum + d.tokens, 0);
+        if (totalTokens <= TOKEN_BUDGET) {
+            // Single call
+            const prompt = this.buildPrompt(docs);
+            const result = await provider.analyzeStructured(prompt, {
+                schema: LLM_PATTERN_SCHEMA,
+                temperature: 0.1,
+                maxTokens: 4096,
+                timeout: 30000,
+                systemPrompt: SYSTEM_PROMPT,
+            });
+            return result.data.patterns;
+        }
+        // Batched chunking
+        const chunks = [];
+        let currentChunk = [];
+        let currentTokens = 0;
+        for (const doc of docs) {
+            if (currentTokens + doc.tokens > TOKEN_BUDGET && currentChunk.length > 0) {
+                chunks.push(currentChunk);
+                currentChunk = [];
+                currentTokens = 0;
             }
+            currentChunk.push(doc);
+            currentTokens += doc.tokens;
         }
-        catch {
-            // Directory doesn't exist or is unreadable
+        if (currentChunk.length > 0) {
+            chunks.push(currentChunk);
         }
-        return results;
+        // Call LLM per chunk and merge
+        const allPatterns = [];
+        for (const chunk of chunks) {
+            try {
+                const prompt = this.buildPrompt(chunk);
+                const result = await provider.analyzeStructured(prompt, {
+                    schema: LLM_PATTERN_SCHEMA,
+                    temperature: 0.1,
+                    maxTokens: 4096,
+                    timeout: 30000,
+                    systemPrompt: SYSTEM_PROMPT,
+                });
+                allPatterns.push(...result.data.patterns);
+            }
+            catch {
+                // Skip failed chunks, continue with others
+            }
+        }
+        // Deduplicate by category + name
+        const seen = new Map();
+        for (const p of allPatterns) {
+            const key = `${p.category}::${p.name}`;
+            if (!seen.has(key)) {
+                seen.set(key, p);
+            }
+        }
+        return Array.from(seen.values());
+    }
+    /**
+     * Build the user prompt with <documents> block.
+     */
+    buildPrompt(docs) {
+        const docBlocks = docs
+            .map(d => `--- file: ${d.path} ---\n${d.content}`)
+            .join('\n');
+        return `Analyze these project documents and identify recurring patterns.
+For each pattern provide: category (kebab-case slug), name (short identifier),
+description (1-2 sentences explaining what the pattern is and why it matters),
+and evidence (list of relevant quotes or references from the docs, max 5 per pattern).
+
+<documents>
+${docBlocks}
+</documents>`;
     }
     /**
      * Create or update a signal entry.
      */
-    upsertSignal(store, detected, incrementId) {
-        const existing = store.signals.find((s) => s.category === detected.category);
+    upsertSignal(store, detected, incrementId, sourceFiles) {
+        const sanitizedName = sanitizeString(detected.name);
+        const sanitizedCategory = sanitizeString(detected.category);
+        const existing = store.signals.find(s => s.category === sanitizedCategory && s.pattern === sanitizedName);
         const now = new Date().toISOString();
+        const relSourceFiles = sourceFiles.map(f => relative(this.projectRoot, f));
         if (existing) {
             if (!existing.incrementIds.includes(incrementId)) {
                 existing.incrementIds.push(incrementId);
             }
             existing.lastSeen = now;
-            // Merge evidence (deduplicated)
+            // Update uniqueSourceFiles with Set semantics
+            const fileSet = new Set(existing.uniqueSourceFiles ?? []);
+            for (const f of relSourceFiles) {
+                fileSet.add(f);
+            }
+            existing.uniqueSourceFiles = Array.from(fileSet);
+            // Merge evidence (deduplicated) then cap
             for (const ev of detected.evidence) {
-                if (!existing.evidence.includes(ev)) {
-                    existing.evidence.push(ev);
+                const sanitizedEv = sanitizeString(ev);
+                if (!existing.evidence.includes(sanitizedEv)) {
+                    existing.evidence.push(sanitizedEv);
                 }
             }
-            // Recalculate confidence based on increment count
-            existing.confidence = Math.min(1.0, existing.incrementIds.length / this.minSignalCount);
+            existing.evidence = capEvidence(existing.evidence);
+            // Confidence = uniqueSourceFiles.length / minSignalCount capped at 1.0
+            existing.confidence = Math.min(1.0, existing.uniqueSourceFiles.length / this.minSignalCount);
         }
         else {
-            const meta = PATTERN_CATEGORIES[detected.category];
+            const uniqueFiles = Array.from(new Set(relSourceFiles));
             const newSignal = {
-                id: `sig-${detected.category}`,
-                pattern: `${detected.category}-pattern`,
-                category: detected.category,
-                description: meta?.description ?? `Detected ${detected.category} pattern`,
+                id: `sig-${sanitizedCategory}-${sanitizedName}`,
+                pattern: sanitizedName,
+                category: sanitizedCategory,
+                description: sanitizeString(detected.description),
                 incrementIds: [incrementId],
                 firstSeen: now,
                 lastSeen: now,
-                confidence: 1 / this.minSignalCount,
-                evidence: detected.evidence,
+                confidence: Math.min(1.0, uniqueFiles.length / this.minSignalCount),
+                evidence: capEvidence(detected.evidence.map(e => sanitizeString(e))),
+                uniqueSourceFiles: uniqueFiles,
                 suggested: false,
                 declined: false,
                 generated: false,