ai-prompt-guide-mcp 1.0.0

package/dist/shared/workflow-prompt-utilities.js

@@ -0,0 +1,163 @@
+/**
+ * Workflow Prompt Utilities
+ *
+ * Utilities for extracting, resolving, and enriching tasks with workflow prompts.
+ * Supports two workflow types:
+ * - Main-Workflow: Project-level methodology for entire task series
+ * - Workflow: Task-specific process guidance
+ */
+import { getWorkflowPrompt } from '../prompts/workflow-prompts.js';
+import { getTaskHeadings } from './task-utilities.js';
+import { getGlobalLogger } from '../utils/logger.js';
+const logger = getGlobalLogger();
+/**
+ * Extract workflow prompt name from task content
+ * Parses "Workflow:" field from task metadata
+ * Returns empty string if field exists but has no value
+ *
+ * @param content - Task content to parse
+ * @returns Workflow name, empty string if field exists with no value, or null if not found
+ */
+export function extractWorkflowName(content) {
+    // Check if field exists with or without value using flexible regex
+    // Matches formats: **Workflow:**, Workflow:, - Workflow:, * Workflow:, - **Workflow:**, * **Workflow:**
+    // Note: In markdown, **Workflow:** means bold "Workflow:" (** before and after)
+    // Use [ \t]* instead of \s* to avoid matching newlines
+    const fieldRegex = /^(?:-\s+|\*\s+)?(?:\*\*Workflow:\*\*|Workflow:)[ \t]*(.*)$/m;
+    const match = content.match(fieldRegex);
+    if (match != null) {
+        // Field exists - return trimmed value (may be empty string)
+        const value = match[1]?.trim() ?? '';
+        return value;
+    }
+    // Field does not exist at all
+    return null;
+}
+/**
+ * Extract main workflow prompt name from task content
+ * Parses "Main-Workflow:" field from task metadata
+ * Returns empty string if field exists but has no value
+ *
+ * @param content - Task content to parse
+ * @returns Main workflow name, empty string if field exists with no value, or null if not found
+ */
+export function extractMainWorkflowName(content) {
+    // Check if field exists with or without value using flexible regex
+    // Matches formats: **Main-Workflow:**, Main-Workflow:, - Main-Workflow:, * Main-Workflow:, - **Main-Workflow:**, * **Main-Workflow:**
+    // Note: In markdown, **Main-Workflow:** means bold "Main-Workflow:" (** before and after)
+    // Use [ \t]* instead of \s* to avoid matching newlines
+    const fieldRegex = /^(?:-\s+|\*\s+)?(?:\*\*Main-Workflow:\*\*|Main-Workflow:)[ \t]*(.*)$/m;
+    const match = content.match(fieldRegex);
+    if (match != null) {
+        // Field exists - return trimmed value (may be empty string)
+        return match[1]?.trim() ?? '';
+    }
+    // Field does not exist at all
+    return null;
+}
+/**
+ * Resolve and load workflow prompt by name
+ * Wraps getWorkflowPrompt with error handling
+ *
+ * @param workflowName - Name of workflow to resolve
+ * @returns WorkflowPrompt object or null if not found or error occurs
+ */
+export function resolveWorkflowPrompt(workflowName) {
+    // Return null for empty/invalid names
+    if (workflowName == null || workflowName === '') {
+        return null;
+    }
+    try {
+        // Add workflow_ prefix when looking up prompts (prompts are stored with prefix)
+        const prompt = getWorkflowPrompt(`workflow_${workflowName}`);
+        return prompt ?? null;
+    }
+    catch {
+        // Return null on any error (prompts not loaded, etc.)
+        return null;
+    }
+}
+/**
+ * Enrich task with task-specific workflow (if specified)
+ * Does NOT mutate original taskData
+ *
+ * @param taskData - Base task data to enrich
+ * @param taskContent - Raw task content to extract workflow from
+ * @returns Enriched task data with workflow field (if found)
+ */
+export function enrichTaskWithWorkflow(taskData, taskContent) {
+    const workflowName = extractWorkflowName(taskContent);
+    // Return new object (not same reference) if no workflow field or empty value
+    if (workflowName == null || workflowName === '') {
+        return { ...taskData };
+    }
+    const workflow = resolveWorkflowPrompt(workflowName);
+    // Log warning for invalid workflow names
+    if (workflow == null) {
+        logger.warn('Workflow prompt not found', {
+            workflowName,
+            taskSlug: taskData.slug
+        });
+        return { ...taskData };
+    }
+    // Return new object with workflow added (do not mutate original)
+    return {
+        ...taskData,
+        workflow
+    };
+}
+/**
+ * Enrich task with main workflow from first task in series
+ * Locates the Tasks section, finds the first task, extracts Main-Workflow field,
+ * and resolves the workflow prompt.
+ * Does NOT mutate original taskData
+ *
+ * @param manager - Document manager for loading task content
+ * @param document - Document containing the task
+ * @param taskData - Base task data to enrich
+ * @returns Promise resolving to enriched task data with mainWorkflow field (if found)
+ */
+export async function enrichTaskWithMainWorkflow(manager, document, taskData) {
+    try {
+        // Find tasks section (slug 'tasks' or title.toLowerCase() === 'tasks')
+        const tasksSection = document.headings.find(h => h.slug === 'tasks' || h.title.toLowerCase() === 'tasks');
+        if (tasksSection == null) {
+            return { ...taskData };
+        }
+        // Get first task using getTaskHeadings
+        const taskHeadings = await getTaskHeadings(document, tasksSection);
+        const firstTask = taskHeadings[0];
+        if (firstTask == null) {
+            return { ...taskData };
+        }
+        // Load first task content
+        const firstTaskContent = await manager.getSectionContent(document.metadata.path, firstTask.slug);
+        if (firstTaskContent == null) {
+            return { ...taskData };
+        }
+        // Extract main workflow name
+        const mainWorkflowName = extractMainWorkflowName(firstTaskContent);
+        if (mainWorkflowName == null || mainWorkflowName === '') {
+            return { ...taskData };
+        }
+        // Resolve main workflow
+        const mainWorkflow = resolveWorkflowPrompt(mainWorkflowName);
+        if (mainWorkflow == null) {
+            logger.warn('Main workflow prompt not found', {
+                mainWorkflowName,
+                firstTaskSlug: firstTask.slug
+            });
+            return { ...taskData };
+        }
+        // Return new object with mainWorkflow added (do not mutate original)
+        return {
+            ...taskData,
+            mainWorkflow
+        };
+    }
+    catch {
+        // Return new object (not same reference) on any failure
+        return { ...taskData };
+    }
+}
+//# sourceMappingURL=workflow-prompt-utilities.js.map

package/dist/shared/workflow-prompt-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-prompt-utilities.js","sourceRoot":"","sources":["../../src/shared/workflow-prompt-utilities.ts"],"names":[],"mappings":"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"}

package/dist/slug.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Slug generation utilities using github-slugger
+ */
+/**
+ * Converts a title to a URL-safe slug using github-slugger
+ * Uses static transform (no internal counters) for deterministic results
+ */
+export declare function titleToSlug(title: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../src/slug.ts"],"names":[],"mappings":"AAAA;;GAEG;AAqBH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA6BjD"}

package/dist/slug.js

@@ -0,0 +1,40 @@
+/**
+ * Slug generation utilities using github-slugger
+ */
+import GithubSlugger from 'github-slugger';
+import { ERROR_CODES } from './constants/defaults.js';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+/**
+ * Creates a custom error with code, context, and version information
+ */
+function createError(message, code, context) {
+    const error = new Error(message);
+    return Object.assign(error, {
+        code,
+        context: { ...context, version: packageJson.version }
+    });
+}
+/**
+ * Converts a title to a URL-safe slug using github-slugger
+ * Uses static transform (no internal counters) for deterministic results
+ */
+export function titleToSlug(title) {
+    if (typeof title !== 'string') {
+        throw createError('Title must be a string', ERROR_CODES.INVALID_TITLE, { title, type: typeof title });
+    }
+    const trimmed = title.trim();
+    if (trimmed.length === 0) {
+        throw createError('Title cannot be empty', ERROR_CODES.INVALID_TITLE, { title });
+    }
+    try {
+        // Use static slug method for deterministic behavior
+        const slugger = new GithubSlugger();
+        return slugger.slug(trimmed);
+    }
+    catch (error) {
+        throw createError('Failed to generate slug from title', ERROR_CODES.INVALID_TITLE, { title, error: error instanceof Error ? error.message : String(error) });
+    }
+}
+//# sourceMappingURL=slug.js.map

package/dist/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../src/slug.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,aAAa,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE;;GAEG;AACH,SAAS,WAAW,CAAC,OAAe,EAAE,IAAY,EAAE,OAAiC;IACnF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,CAAkB,CAAC;IAClD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE;QAC1B,IAAI;QACJ,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE;KACtD,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,WAAW,CACf,wBAAwB,EACxB,WAAW,CAAC,aAAa,EACzB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,KAAK,EAAE,CAC9B,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,WAAW,CACf,uBAAuB,EACvB,WAAW,CAAC,aAAa,EACzB,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,oDAAoD;QACpD,MAAM,OAAO,GAAG,IAAI,aAAa,EAAE,CAAC;QACpC,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,WAAW,CACf,oCAAoC,EACpC,WAAW,CAAC,aAAa,EACzB,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACzE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/template-loader.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Template loader for onboarding and instructional messages
+ * Safely loads markdown templates from the templates directory
+ */
+export {};
+//# sourceMappingURL=template-loader.d.ts.map

package/dist/template-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-loader.d.ts","sourceRoot":"","sources":["../src/template-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/template-loader.js

@@ -0,0 +1,8 @@
+/**
+ * Template loader for onboarding and instructional messages
+ * Safely loads markdown templates from the templates directory
+ */
+export {};
+// This file is preserved for potential future template functionality
+// All exports have been removed as they are currently unused
+//# sourceMappingURL=template-loader.js.map

package/dist/template-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-loader.js","sourceRoot":"","sources":["../src/template-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;;AAEH,qEAAqE;AACrE,6DAA6D"}

package/dist/tools/__tests__/create-document-self-reference.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=create-document-self-reference.test.d.ts.map

package/dist/tools/__tests__/create-document-self-reference.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-document-self-reference.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/create-document-self-reference.test.ts"],"names":[],"mappings":""}

package/dist/tools/__tests__/create-document-self-reference.test.js

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { executeCreateDocumentPipeline } from '../create/pipeline.js';
+import { getGlobalSessionStore } from '../../session/session-store.js';
+import { createDocumentManager } from '../../shared/utilities.js';
+describe('create_document self-reference bug', () => {
+    let sessionState;
+    let sessionId;
+    let manager;
+    let tempDir;
+    beforeEach(async () => {
+        // Set MCP_WORKSPACE_PATH for config loading
+        process.env["MCP_WORKSPACE_PATH"] = process.env["MCP_WORKSPACE_PATH"] ?? "/tmp/test-workspace";
+        // Create temporary directory for test documents
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'create-doc-self-ref-test-'));
+        // Configure MCP_WORKSPACE_PATH for config loading
+        process.env["MCP_WORKSPACE_PATH"] = tempDir;
+        // Create a unique session for each test
+        sessionId = `test-session-${Date.now()}-${Math.random()}`;
+        sessionState = {
+            sessionId,
+            createDocumentStage: 0
+        };
+        // Create DocumentManager with temp directory for dependency injection
+        manager = createDocumentManager(tempDir);
+        // Clear session state
+        const sessionStore = getGlobalSessionStore();
+        sessionStore.reset(sessionId);
+    });
+    afterEach(async () => {
+        // Clean up temporary directory
+        try {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore if directory doesn't exist
+        }
+    });
+    it('should NOT include newly created document in its own suggestions', async () => {
+        // Create a document
+        const args = {
+            namespace: 'api/specs',
+            title: 'Test Self Reference API',
+            overview: 'Test document that should not suggest itself'
+        };
+        const result = await executeCreateDocumentPipeline(args, sessionState, manager);
+        // Verify creation succeeded
+        expect(result).toHaveProperty('stage', 'creation');
+        expect(result).toHaveProperty('success', true);
+        // Extract created document path
+        const creationResult = result;
+        const createdPath = creationResult.created;
+        // Check if suggestions exist
+        if (creationResult.suggestions?.related_documents != null) {
+            const relatedDocs = creationResult.suggestions.related_documents;
+            // The bug: document suggests itself with relevance 1.0
+            // After fix: document should NOT appear in its own suggestions
+            const selfReference = relatedDocs.find(doc => doc.path === createdPath);
+            expect(selfReference).toBeUndefined(); // SHOULD NOT FIND ITSELF
+        }
+        // If no suggestions, test passes (no self-reference possible)
+    });
+    it('should exclude current document even with high keyword overlap', async () => {
+        // Create first document
+        const args1 = {
+            namespace: 'api/specs',
+            title: 'Authentication API',
+            overview: 'Complete authentication API documentation with OAuth2 and JWT support'
+        };
+        const firstResult = await executeCreateDocumentPipeline(args1, sessionState, manager);
+        expect(firstResult).toHaveProperty('stage', 'creation');
+        // Create second document with very similar keywords
+        const args2 = {
+            namespace: 'api/specs',
+            title: 'Authentication Helper API',
+            overview: 'Authentication helper utilities for OAuth2 and JWT authentication support'
+        };
+        const result = await executeCreateDocumentPipeline(args2, sessionState, manager);
+        // Verify creation succeeded
+        expect(result).toHaveProperty('stage', 'creation');
+        expect(result).toHaveProperty('success', true);
+        const creationResult = result;
+        const createdPath = creationResult.created;
+        // Check suggestions - the key test is that it doesn't suggest itself
+        if (creationResult.suggestions?.related_documents != null) {
+            const relatedDocs = creationResult.suggestions.related_documents;
+            // Should NOT suggest itself (the second document) - THIS IS THE CRITICAL TEST
+            const selfReference = relatedDocs.find(doc => doc.path === createdPath);
+            expect(selfReference).toBeUndefined(); // SHOULD NOT find itself
+            // If it found related docs, verify first doc might be there (but don't require it)
+            // This is optional since suggestion algorithm might not always return all matches
+            if (relatedDocs.length > 0) {
+                // At least verify none of them are the current document
+                relatedDocs.forEach(doc => {
+                    expect(doc.path).not.toBe(createdPath);
+                });
+            }
+        }
+    });
+    it('should handle single document without self-reference', async () => {
+        // Create single document - should get no suggestions or empty suggestions, but never self-reference
+        const args = {
+            namespace: 'api/specs',
+            title: 'Isolated Document',
+            overview: 'Document with unique keywords that should not match anything'
+        };
+        const result = await executeCreateDocumentPipeline(args, sessionState, manager);
+        // Check result - it should either succeed or fail, but never suggest itself
+        if ('stage' in result && result.stage === 'creation') {
+            const creationResult = result;
+            // Should have either no suggestions or empty array, but NEVER self-reference
+            if (creationResult.suggestions?.related_documents != null) {
+                const relatedDocs = creationResult.suggestions.related_documents;
+                const createdPath = creationResult.created;
+                const selfReference = relatedDocs.find(doc => doc.path === createdPath);
+                expect(selfReference).toBeUndefined();
+            }
+        }
+        // If creation fails, that's fine for this test - we're just ensuring no self-reference when it succeeds
+    });
+});
+//# sourceMappingURL=create-document-self-reference.test.js.map

package/dist/tools/__tests__/create-document-self-reference.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-document-self-reference.test.js","sourceRoot":"","sources":["../../../src/tools/__tests__/create-document-self-reference.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAClD,IAAI,YAA0B,CAAC;IAC/B,IAAI,SAAiB,CAAC;IACtB,IAAI,OAAwB,CAAC;IAC7B,IAAI,OAAe,CAAC;IAEpB,UAAU,CAAC,KAAK,IAAI,EAAE;QACpB,4CAA4C;QAC5C,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,qBAAqB,CAAC;QAE/F,gDAAgD;QAChD,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,2BAA2B,CAAC,CAAC,CAAC;QAEhF,kDAAkD;QAClD,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC;QAE5C,wCAAwC;QACxC,SAAS,GAAG,gBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1D,YAAY,GAAG;YACb,SAAS;YACT,mBAAmB,EAAE,CAAC;SACvB,CAAC;QAEF,sEAAsE;QACtE,OAAO,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAEzC,sBAAsB;QACtB,MAAM,YAAY,GAAG,qBAAqB,EAAE,CAAC;QAC7C,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACnB,+BAA+B;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;QAChF,oBAAoB;QACpB,MAAM,IAAI,GAAG;YACX,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,yBAAyB;YAChC,QAAQ,EAAE,8CAA8C;SACzD,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QAEhF,4BAA4B;QAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE/C,gCAAgC;QAChC,MAAM,cAAc,GAAG,MAOtB,CAAC;QAEF,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC;QAE3C,6BAA6B;QAC7B,IAAI,cAAc,CAAC,WAAW,EAAE,iBAAiB,IAAI,IAAI,EAAE,CAAC;YAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,CAAC,iBAAiB,CAAC;YAEjE,uDAAuD;YACvD,+DAA+D;YAC/D,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;YAExE,MAAM,CAAC,aAAa,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,yBAAyB;QAClE,CAAC;QACD,8DAA8D;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC9E,wBAAwB;QACxB,MAAM,KAAK,GAAG;YACZ,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,oBAAoB;YAC3B,QAAQ,EAAE,uEAAuE;SAClF,CAAC;QAEF,MAAM,WAAW,GAAG,MAAM,6BAA6B,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QACtF,MAAM,CAAC,WAAW,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAExD,oDAAoD;QACpD,MAAM,KAAK,GAAG;YACZ,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,2BAA2B;YAClC,QAAQ,EAAE,2EAA2E;SACtF,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QAEjF,4BAA4B;QAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE/C,MAAM,cAAc,GAAG,MAOtB,CAAC;QAEF,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC;QAE3C,qEAAqE;QACrE,IAAI,cAAc,CAAC,WAAW,EAAE,iBAAiB,IAAI,IAAI,EAAE,CAAC;YAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,CAAC,iBAAiB,CAAC;YAEjE,8EAA8E;YAC9E,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;YACxE,MAAM,CAAC,aAAa,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,yBAAyB;YAEhE,mFAAmF;YACnF,kFAAkF;YAClF,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,wDAAwD;gBACxD,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;oBACxB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACzC,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;QACpE,oGAAoG;QACpG,MAAM,IAAI,GAAG;YACX,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,mBAAmB;YAC1B,QAAQ,EAAE,8DAA8D;SACzE,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QAEhF,4EAA4E;QAC5E,IAAI,OAAO,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACrD,MAAM,cAAc,GAAG,MAOtB,CAAC;YAEF,6EAA6E;YAC7E,IAAI,cAAc,CAAC,WAAW,EAAE,iBAAiB,IAAI,IAAI,EAAE,CAAC;gBAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,CAAC,iBAAiB,CAAC;gBACjE,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC;gBAE3C,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;gBACxE,MAAM,CAAC,aAAa,CAAC,CAAC,aAAa,EAAE,CAAC;YACxC,CAAC;QACH,CAAC;QACD,wGAAwG;IAC1G,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/tools/__tests__/create-document-workflow-regression.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Comprehensive regression tests for create-document workflow Stage 2.5
+ *
+ * Tests the complete enhanced document discovery system including:
+ * - Multi-factor relevance scoring
+ * - Enhanced keyword extraction with frontmatter support
+ * - Structured broken reference detection
+ * - Factor-based explanation generation
+ * - Fingerprint-based performance optimization
+ * - Integration between all enhanced components
+ *
+ * This test suite ensures that the Stage 1-4 enhancements work correctly
+ * in the complete create-document workflow, providing regression protection.
+ */
+export {};
+//# sourceMappingURL=create-document-workflow-regression.test.d.ts.map

package/dist/tools/__tests__/create-document-workflow-regression.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-document-workflow-regression.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/create-document-workflow-regression.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}