This is page 13 of 18. Use http://codebase.md/minipuft/claude-prompts-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .actrc
├── .gitattributes
├── .github
│ └── workflows
│ ├── ci.yml
│ ├── mcp-compliance.yml
│ └── pr-validation.yml
├── .gitignore
├── agent.md
├── assets
│ └── logo.png
├── CLAUDE.md
├── config
│ └── framework-state.json
├── docs
│ ├── architecture.md
│ ├── chain-modification-examples.md
│ ├── contributing.md
│ ├── enhanced-gate-system.md
│ ├── execution-architecture-guide.md
│ ├── installation-guide.md
│ ├── mcp-tool-usage-guide.md
│ ├── mcp-tools-reference.md
│ ├── prompt-format-guide.md
│ ├── prompt-management.md
│ ├── prompt-vs-template-guide.md
│ ├── README.md
│ ├── template-development-guide.md
│ ├── TODO.md
│ ├── troubleshooting.md
│ └── version-history.md
├── LICENSE
├── local-test.sh
├── plans
│ ├── nunjucks-dynamic-chain-orchestration.md
│ ├── outputschema-realtime-progress-and-validation.md
│ ├── parallel-conditional-execution-analysis.md
│ ├── sqlite-storage-migration.md
│ └── symbolic-command-language-implementation.md
├── README.md
├── scripts
│ ├── setup-windows-testing.sh
│ ├── test_server.js
│ ├── test-all-platforms.sh
│ └── windows-tests
│ ├── test-windows-paths.js
│ ├── test-windows-startup.sh
│ └── windows-env.sh
└── server
├── config
│ ├── framework-state.json
│ └── tool-descriptions.json
├── config.json
├── jest.config.cjs
├── LICENSE
├── package-lock.json
├── package.json
├── prompts
│ ├── analysis
│ │ ├── advanced_analysis_engine.md
│ │ ├── content_analysis.md
│ │ ├── deep_analysis.md
│ │ ├── deep_research.md
│ │ ├── markdown_notebook.md
│ │ ├── note_integration.md
│ │ ├── note_refinement.md
│ │ ├── notes.md
│ │ ├── progressive_research.md
│ │ ├── prompts.json
│ │ ├── query_refinement.md
│ │ └── review.md
│ ├── architecture
│ │ ├── prompts.json
│ │ └── strategic-system-alignment.md
│ ├── content_processing
│ │ ├── format_enhancement.md
│ │ ├── noteIntegration.md
│ │ ├── obsidian_metadata_optimizer.md
│ │ ├── prompts.json
│ │ ├── vault_related_notes_finder.md
│ │ └── video_notes_enhanced.md
│ ├── debugging
│ │ ├── analyze_logs.md
│ │ └── prompts.json
│ ├── development
│ │ ├── analyze_code_structure.md
│ │ ├── analyze_file_structure.md
│ │ ├── code_review_optimization_chain.md
│ │ ├── component_flow_analysis.md
│ │ ├── create_modularization_plan.md
│ │ ├── detect_code_issues.md
│ │ ├── detect_project_commands.md
│ │ ├── expert_code_implementation.md
│ │ ├── generate_comprehensive_claude_md.md
│ │ ├── prompts.json
│ │ ├── strategicImplement.md
│ │ ├── suggest_code_improvements.md
│ │ └── transform_code_to_modules.md
│ ├── documentation
│ │ ├── create_docs_chain.md
│ │ ├── docs-content-creation.md
│ │ ├── docs-content-planning.md
│ │ ├── docs-final-assembly.md
│ │ ├── docs-project-analysis.md
│ │ ├── docs-review-refinement.md
│ │ └── prompts.json
│ ├── education
│ │ ├── prompts.json
│ │ └── vault_integrated_notes.md
│ ├── general
│ │ ├── diagnose.md
│ │ └── prompts.json
│ ├── promptsConfig.json
│ └── testing
│ ├── final_verification_test.md
│ └── prompts.json
├── README.md
├── scripts
│ └── validate-dependencies.js
├── src
│ ├── api
│ │ └── index.ts
│ ├── chain-session
│ │ └── manager.ts
│ ├── config
│ │ └── index.ts
│ ├── Dockerfile
│ ├── execution
│ │ ├── context
│ │ │ ├── context-resolver.ts
│ │ │ ├── framework-injector.ts
│ │ │ └── index.ts
│ │ ├── index.ts
│ │ ├── parsers
│ │ │ ├── argument-parser.ts
│ │ │ ├── index.ts
│ │ │ └── unified-command-parser.ts
│ │ └── types.ts
│ ├── frameworks
│ │ ├── framework-manager.ts
│ │ ├── framework-state-manager.ts
│ │ ├── index.ts
│ │ ├── integration
│ │ │ ├── framework-semantic-integration.ts
│ │ │ └── index.ts
│ │ ├── methodology
│ │ │ ├── guides
│ │ │ │ ├── 5w1h-guide.ts
│ │ │ │ ├── cageerf-guide.ts
│ │ │ │ ├── react-guide.ts
│ │ │ │ └── scamper-guide.ts
│ │ │ ├── index.ts
│ │ │ ├── interfaces.ts
│ │ │ └── registry.ts
│ │ ├── prompt-guidance
│ │ │ ├── index.ts
│ │ │ ├── methodology-tracker.ts
│ │ │ ├── service.ts
│ │ │ ├── system-prompt-injector.ts
│ │ │ └── template-enhancer.ts
│ │ └── types
│ │ ├── index.ts
│ │ ├── integration-types.ts
│ │ ├── methodology-types.ts
│ │ └── prompt-guidance-types.ts
│ ├── gates
│ │ ├── constants.ts
│ │ ├── core
│ │ │ ├── gate-definitions.ts
│ │ │ ├── gate-loader.ts
│ │ │ ├── gate-validator.ts
│ │ │ ├── index.ts
│ │ │ └── temporary-gate-registry.ts
│ │ ├── definitions
│ │ │ ├── code-quality.json
│ │ │ ├── content-structure.json
│ │ │ ├── educational-clarity.json
│ │ │ ├── framework-compliance.json
│ │ │ ├── research-quality.json
│ │ │ ├── security-awareness.json
│ │ │ └── technical-accuracy.json
│ │ ├── gate-state-manager.ts
│ │ ├── guidance
│ │ │ ├── FrameworkGuidanceFilter.ts
│ │ │ └── GateGuidanceRenderer.ts
│ │ ├── index.ts
│ │ ├── intelligence
│ │ │ ├── GatePerformanceAnalyzer.ts
│ │ │ └── GateSelectionEngine.ts
│ │ ├── templates
│ │ │ ├── code_quality_validation.md
│ │ │ ├── educational_clarity_validation.md
│ │ │ ├── framework_compliance_validation.md
│ │ │ ├── research_self_validation.md
│ │ │ ├── security_validation.md
│ │ │ ├── structure_validation.md
│ │ │ └── technical_accuracy_validation.md
│ │ └── types.ts
│ ├── index.ts
│ ├── logging
│ │ └── index.ts
│ ├── mcp-tools
│ │ ├── config-utils.ts
│ │ ├── constants.ts
│ │ ├── index.ts
│ │ ├── prompt-engine
│ │ │ ├── core
│ │ │ │ ├── engine.ts
│ │ │ │ ├── executor.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── processors
│ │ │ │ ├── response-formatter.ts
│ │ │ │ └── template-processor.ts
│ │ │ └── utils
│ │ │ ├── category-extractor.ts
│ │ │ ├── classification.ts
│ │ │ ├── context-builder.ts
│ │ │ └── validation.ts
│ │ ├── prompt-manager
│ │ │ ├── analysis
│ │ │ │ ├── comparison-engine.ts
│ │ │ │ ├── gate-analyzer.ts
│ │ │ │ └── prompt-analyzer.ts
│ │ │ ├── core
│ │ │ │ ├── index.ts
│ │ │ │ ├── manager.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── operations
│ │ │ │ └── file-operations.ts
│ │ │ ├── search
│ │ │ │ ├── filter-parser.ts
│ │ │ │ └── prompt-matcher.ts
│ │ │ └── utils
│ │ │ ├── category-manager.ts
│ │ │ └── validation.ts
│ │ ├── shared
│ │ │ └── structured-response-builder.ts
│ │ ├── system-control.ts
│ │ ├── tool-description-manager.ts
│ │ └── types
│ │ └── shared-types.ts
│ ├── metrics
│ │ ├── analytics-service.ts
│ │ ├── index.ts
│ │ └── types.ts
│ ├── performance
│ │ ├── index.ts
│ │ └── monitor.ts
│ ├── prompts
│ │ ├── category-manager.ts
│ │ ├── converter.ts
│ │ ├── file-observer.ts
│ │ ├── hot-reload-manager.ts
│ │ ├── index.ts
│ │ ├── loader.ts
│ │ ├── promptUtils.ts
│ │ ├── registry.ts
│ │ └── types.ts
│ ├── runtime
│ │ ├── application.ts
│ │ └── startup.ts
│ ├── semantic
│ │ ├── configurable-semantic-analyzer.ts
│ │ └── integrations
│ │ ├── index.ts
│ │ └── llm-clients.ts
│ ├── server
│ │ ├── index.ts
│ │ └── transport
│ │ └── index.ts
│ ├── smithery.yaml
│ ├── text-references
│ │ ├── conversation.ts
│ │ └── index.ts
│ ├── types
│ │ └── index.ts
│ ├── types.ts
│ └── utils
│ ├── chainUtils.ts
│ ├── errorHandling.ts
│ ├── global-resource-tracker.ts
│ ├── index.ts
│ └── jsonUtils.ts
├── tests
│ ├── ci-startup-validation.js
│ ├── enhanced-validation
│ │ ├── contract-validation
│ │ │ ├── contract-test-suite.js
│ │ │ ├── interface-contracts.js
│ │ │ └── interface-contracts.ts
│ │ ├── environment-validation
│ │ │ ├── environment-parity-checker.js
│ │ │ └── environment-test-suite.js
│ │ ├── lifecycle-validation
│ │ │ ├── lifecycle-test-suite.js
│ │ │ └── process-lifecycle-validator.js
│ │ └── validation-orchestrator.js
│ ├── helpers
│ │ └── test-helpers.js
│ ├── integration
│ │ ├── mcp-tools.test.ts
│ │ ├── server-startup.test.ts
│ │ └── unified-parsing-integration.test.ts
│ ├── performance
│ │ ├── parsing-system-benchmark.test.ts
│ │ └── server-performance.test.ts
│ ├── scripts
│ │ ├── consolidated-tools.js
│ │ ├── establish-performance-baselines.js
│ │ ├── functional-mcp-validation.js
│ │ ├── integration-mcp-tools.js
│ │ ├── integration-routing-system.js
│ │ ├── integration-server-startup.js
│ │ ├── integration-unified-parsing.js
│ │ ├── methodology-guides.js
│ │ ├── performance-memory.js
│ │ ├── runtime-integration.js
│ │ ├── unit-conversation-manager.js
│ │ ├── unit-semantic-analyzer.js
│ │ └── unit-unified-parsing.js
│ ├── setup.ts
│ ├── test-enhanced-parsing.js
│ └── unit
│ ├── conversation-manager.test.ts
│ ├── semantic-analyzer-three-tier.test.ts
│ └── unified-parsing-system.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/docs/enhanced-gate-system.md:
--------------------------------------------------------------------------------
```markdown
1 | # Enhanced Gate System - Current Implementation Guide
2 |
3 | ## Overview
4 |
5 | The Enhanced Gate System provides comprehensive content validation and quality assessment for AI prompt execution. The system implements **7 gate definitions** with **3 configurable check types**, offering flexible validation capabilities while integrating seamlessly with the consolidated MCP architecture.
6 |
7 | **Key Features:**
8 | - **7 Gate Definitions** (code-quality, content-structure, educational-clarity, framework-compliance, research-quality, security-awareness, technical-accuracy)
9 | - **3 Validation Check Types** (content_check, pattern_check, llm_self_check) configurable via JSON definitions
10 | - **5-Level Gate Precedence System** (Temporary → Template → Category → Framework → Fallback)
11 | - **Framework Integration** with CAGEERF, ReACT, 5W1H, and SCAMPER methodologies
12 | - **Performance Tracking** with usage statistics and evaluation metrics
13 | - **Consolidated Tool Integration** through the 3-tool MCP architecture
14 |
15 | ## Gate Integration by Execution Type
16 |
17 | The gate system integrates with all execution types through the consolidated `prompt_engine` tool:
18 |
19 | | Execution Type | Gate Integration Status | How to Enable | Performance Impact |
20 | |----------------|------------------------|-----------------|-------------------|
21 | | **Prompts** | ✅ **Optional** | `gate_validation: true` | Minimal overhead |
22 | | **Templates** | ✅ **Optional** | `gate_validation: true` | Moderate overhead |
23 | | **Chains** | ✅ **Default** | Automatic (can disable) | Step-level validation |
24 |
25 | ### Prompt Execution with Gates
26 |
27 | ```bash
28 | # Basic prompt with optional gate validation
29 | prompt_engine >>content_analysis input="my data" gate_validation=true
30 | ```
31 |
32 | ### Template Execution with Gates
33 |
34 | ```bash
35 | # Template with framework enhancement and gate validation
36 | prompt_engine >>analysis_template data="content" execution_mode="template" gate_validation=true
37 | ```
38 |
39 | ### Chain Execution with Gates
40 |
41 | ```bash
42 | # Chain execution with automatic gate validation
43 | prompt_engine >>research_chain topic="AI trends" llm_driven_execution=true
44 | # Gates are enabled by default for chains, can disable with gate_validation=false
45 | ```
46 |
47 | ## Architecture
48 |
49 | ### Core Components
50 |
51 | #### 1. Gate Loader (`gate-loader.ts`)
52 | - **Purpose**: Loads gate definitions from JSON files with hot-reload support
53 | - **Features**:
54 | - Dynamic gate loading and caching
55 | - File-based gate definitions (7 gates in `/gates/definitions/`)
56 | - Hot-reload capability for gate updates
57 | - Context-aware gate activation
58 |
59 | #### 2. Gate Validator (`gate-validator.ts`)
60 | - **Purpose**: Validates content against gate definitions with 3 check types
61 | - **Features**:
62 | - **content_check**: Length validation, required/forbidden patterns
63 | - **pattern_check**: Regex matching, keyword count validation
64 | - **llm_self_check**: Heuristic-based quality assessment
65 | - Intelligent retry hints for failed validations
66 | - Performance statistics tracking
67 |
68 | #### 3. Gate Selection Engine (`GateSelectionEngine.ts`)
69 | - **Purpose**: Intelligent gate selection based on context and semantic analysis
70 | - **Features**:
71 | - Framework-based gate selection (ReACT, CAGEERF, 5W1H, SCAMPER)
72 | - Category-based gate mapping (analysis, education, development, research)
73 | - Semantic analysis integration for enhanced selection
74 | - Confidence scoring and execution time estimation
75 |
76 | #### 4. Category Extractor (`category-extractor.ts`)
77 | - **Purpose**: 5-level gate precedence system for intelligent selection
78 | - **Features**:
79 | - **Temporary gates** (highest priority) - execution-specific gates
80 | - **Template gates** - prompt-defined include/exclude patterns
81 | - **Category gates** - automatic selection based on prompt category
82 | - **Framework gates** - methodology-specific validation
83 | - **Fallback gates** (lowest priority) - default content-structure gates
84 |
85 | #### 5. Consolidated Tool Integration
86 | - **prompt_engine**: Gate validation through `gate_validation` parameter and gate configuration
87 | - **system_control**: Gate performance monitoring and statistics
88 | - **prompt_manager**: Gate configuration management in prompt definitions
89 |
90 | ## Implemented Gate Definitions
91 |
92 | The system includes **7 gate definitions** located in `/server/src/gates/definitions/`:
93 |
94 | ### 1. **code-quality**
95 | - **Type**: validation
96 | - **Purpose**: Validates code quality and best practices
97 | - **Activation**: Development and code-focused prompts
98 | - **Pass Criteria**: Configurable via JSON (content checks, pattern matching, LLM assessment)
99 |
100 | ### 2. **content-structure**
101 | - **Type**: validation
102 | - **Purpose**: Validates document structure and organization
103 | - **Activation**: All prompt categories (fallback gate)
104 | - **Pass Criteria**: Content structure, required sections, formatting
105 |
106 | ### 3. **educational-clarity**
107 | - **Type**: validation
108 | - **Purpose**: Ensures educational content is clear and well-structured
109 | - **Activation**: Education category, ReACT framework
110 | - **Pass Criteria**: Clarity metrics, pedagogical structure, examples
111 |
112 | ### 4. **framework-compliance**
113 | - **Type**: validation
114 | - **Purpose**: Validates compliance with active methodology framework
115 | - **Activation**: All frameworks (CAGEERF, ReACT, 5W1H, SCAMPER)
116 | - **Pass Criteria**: Framework-specific validation rules
117 |
118 | ### 5. **research-quality**
119 | - **Type**: validation
120 | - **Purpose**: Ensures research content meets quality standards
121 | - **Activation**: Analysis and research categories, CAGEERF framework
122 | - **Pass Criteria**: Research rigor, evidence quality, citation completeness
123 |
124 | ### 6. **security-awareness**
125 | - **Type**: validation
126 | - **Purpose**: Validates security considerations and best practices
127 | - **Activation**: Development category, security-sensitive prompts
128 | - **Pass Criteria**: Security pattern detection, vulnerability checks
129 |
130 | ### 7. **technical-accuracy**
131 | - **Type**: validation
132 | - **Purpose**: Validates technical accuracy and precision
133 | - **Activation**: Analysis, research, and technical prompts
134 | - **Pass Criteria**: Technical precision, accuracy metrics, validation patterns
135 |
136 | ## Validation Check Types
137 |
138 | Each gate definition can use **3 configurable check types**:
139 |
140 | ### 1. **content_check**
141 | - Length validation (min/max bounds)
142 | - Required patterns (must be present)
143 | - Forbidden patterns (must not be present)
144 | - Basic content quality assessment
145 |
146 | ### 2. **pattern_check**
147 | - Regex pattern matching
148 | - Keyword count validation
149 | - Pattern compliance verification
150 | - Structural pattern detection
151 |
152 | ### 3. **llm_self_check**
153 | - Heuristic-based quality assessment
154 | - Word count and structure analysis
155 | - Configurable pass thresholds
156 | - Quality scoring with improvement hints
157 |
158 | ## Usage Examples
159 |
160 | ### Basic Gate Validation
161 |
162 | ```bash
163 | # Enable gates for any prompt execution
164 | prompt_engine >>my_prompt input="test data" gate_validation=true
165 |
166 | # Check gate evaluation in system status
167 | system_control status
168 | ```
169 |
170 | ### Framework-Enhanced Validation
171 |
172 | ```bash
173 | # Use gates with specific framework
174 | system_control switch_framework framework="CAGEERF"
175 | prompt_engine >>analysis_prompt data="content" execution_mode="template" gate_validation=true
176 | ```
177 |
178 | ### Chain Execution with Step Validation
179 |
180 | ```bash
181 | # Chains automatically use gate validation
182 | prompt_engine >>content_creation_chain topic="AI ethics" llm_driven_execution=true
183 |
184 | # Monitor chain execution and gate performance
185 | system_control analytics include_history=true
186 | ```
187 |
188 | ### Advanced Configuration
189 |
190 | ```typescript
191 | // Gate evaluation context
192 | const context: GateEvaluationContext = {
193 | content: 'Content to validate...',
194 | metadata: {
195 | contentType: 'analysis',
196 | targetAudience: 'technical',
197 | },
198 | runtime: 'production'
199 | };
200 |
201 | // Execute with specific gate configuration
202 | const result = await gateRegistry.evaluateGate('content-quality-gate', context);
203 | ```
204 |
205 | ## Integration with Consolidated Architecture
206 |
207 | ### MCP Tool Integration
208 |
209 | The gate system integrates with the **3 consolidated MCP tools**:
210 |
211 | #### **prompt_engine Integration**
212 | - **Gate Parameter**: `gate_validation: boolean`
213 | - **Default Behavior**: Automatic for chains, optional for prompts/templates
214 | - **Failure Handling**: Intelligent retry with improvement suggestions
215 |
216 | #### **system_control Integration**
217 | - **Analytics**: Gate usage statistics and performance metrics
218 | - **Health Monitoring**: Gate evaluation success rates and timing
219 | - **Diagnostics**: Gate failure analysis and troubleshooting
220 |
221 | #### **prompt_manager Integration**
222 | - **Type Analysis**: Recommends gate usage based on prompt complexity
223 | - **Quality Assessment**: Gate compliance analysis for prompt optimization
224 |
225 | ### Framework System Integration
226 |
227 | Gates integrate with the **4 methodology frameworks**:
228 |
229 | - **CAGEERF**: Comprehensive structured validation with completeness gates
230 | - **ReACT**: Logic and reasoning validation with pattern matching gates
231 | - **5W1H**: Systematic analysis validation with required fields gates
232 | - **SCAMPER**: Creative content validation with tone and readability gates
233 |
234 | ## Configuration
235 |
236 | ### Gate Definition Structure
237 |
238 | ```typescript
239 | interface ExtendedGateDefinition {
240 | id: string; // Unique gate identifier
241 | name: string; // Human-readable name
242 | type: 'validation' | 'approval' | 'condition' | 'quality';
243 | requirements: ExtendedGateRequirement[];
244 | failureAction: 'stop' | 'retry' | 'skip' | 'rollback';
245 | runtimeTargets?: string[]; // Target runtimes
246 | configVersion?: string; // Configuration version
247 | }
248 | ```
249 |
250 | ### Gate Requirement Configuration
251 |
252 | ```typescript
253 | interface ExtendedGateRequirement {
254 | type: ExtendedGateType; // One of 19+ implemented types
255 | criteria: {
256 | // Content length criteria
257 | min?: number;
258 | max?: number;
259 |
260 | // Readability criteria
261 | readabilityTarget?: 'beginner' | 'intermediate' | 'advanced';
262 | fleschKincaidMin?: number;
263 | fleschKincaidMax?: number;
264 |
265 | // Format validation
266 | format?: string;
267 | allowedFormats?: string[];
268 |
269 | // Custom criteria
270 | customCriteria?: Record<string, any>;
271 | };
272 | weight?: number; // Requirement weight
273 | required?: boolean; // Is requirement mandatory
274 | runtimeOverrides?: Record<string, any>;
275 | }
276 | ```
277 |
278 | ## Performance Characteristics
279 |
280 | ### Evaluation Performance
281 | - **Content Analysis**: ~50-100ms per gate
282 | - **Structure Validation**: ~30-80ms per gate
283 | - **Pattern Matching**: ~20-50ms per gate
284 | - **Custom Logic**: ~40-120ms per gate
285 |
286 | ### System Integration Performance
287 | - **Prompt Execution**: +10-50ms overhead when gates enabled
288 | - **Template Execution**: +50-200ms with framework + gate validation
289 | - **Chain Execution**: Per-step validation with minimal impact
290 |
291 | ### Performance Monitoring
292 |
293 | The system tracks comprehensive metrics:
294 | - **Gate Success Rate**: Percentage of successful validations
295 | - **Evaluation Time**: Average time per gate type
296 | - **Usage Statistics**: Most/least used gates and strategies
297 | - **Error Rates**: Common failure patterns and resolution
298 |
299 | Access performance data:
300 | ```bash
301 | # View gate performance analytics
302 | system_control analytics
303 |
304 | # Check system health including gate evaluation
305 | system_control health
306 |
307 | # Get detailed diagnostics
308 | system_control diagnostics
309 | ```
310 |
311 | ## Error Handling
312 |
313 | ### Graceful Degradation
314 | - **Strategy Fallback**: Automatic fallback to basic validation if advanced evaluators fail
315 | - **Partial Evaluation**: Continue execution on non-critical gate failures
316 | - **Error Recovery**: Retry mechanisms with exponential backoff
317 |
318 | ### Error Types & Recovery
319 | - **Validation Errors**: Invalid gate configurations - provides configuration guidance
320 | - **Evaluation Errors**: Runtime evaluation failures - offers fallback options
321 | - **Timeout Errors**: Gate evaluation timeouts - suggests simpler validation
322 | - **Resource Errors**: Insufficient resources - provides optimization suggestions
323 |
324 | ### Intelligent Hints & Recovery
325 |
326 | The system provides actionable guidance for failed gates:
327 |
328 | ```typescript
329 | interface ImprovementSuggestion {
330 | type: 'content' | 'structure' | 'format' | 'style';
331 | priority: 'low' | 'medium' | 'high' | 'critical';
332 | message: string;
333 | example?: string;
334 | autoFixable?: boolean;
335 | }
336 | ```
337 |
338 | ## Testing & Validation
339 |
340 | ### Testing Gate Integration
341 |
342 | ```bash
343 | # Test basic gate validation
344 | prompt_engine >>test_prompt content="short" gate_validation=true
345 |
346 | # Test with different gate types through system
347 | system_control status # Check gate system health
348 |
349 | # Test framework integration
350 | system_control switch_framework framework="ReACT"
351 | prompt_engine >>analysis_prompt input="data" gate_validation=true
352 | ```
353 |
354 | ### Validation Examples
355 |
356 | ```typescript
357 | // Test individual gate evaluator
358 | const gateService = createGateEvaluator(logger);
359 | const result = await gateService.evaluateGate(content, gateDefinition);
360 |
361 | // Test strategy pattern
362 | const supportedTypes = gateService.getSupportedGateTypes();
363 | console.log(`Supported gates: ${supportedTypes.length}`); // Should show 19+
364 | ```
365 |
366 | ## Troubleshooting
367 |
368 | ### Common Issues
369 |
370 | 1. **Gate Evaluation Timeouts**
371 | - **Cause**: Complex content or resource constraints
372 | - **Solution**: Increase timeout or simplify validation criteria
373 | - **Check**: `system_control diagnostics`
374 |
375 | 2. **Strategy Evaluator Failures**
376 | - **Cause**: Missing evaluator implementation or configuration error
377 | - **Solution**: Verify gate type exists in supported list
378 | - **Check**: `gateService.getSupportedGateTypes()`
379 |
380 | 3. **Integration with Consolidated Tools**
381 | - **Cause**: Incorrect parameter usage or tool configuration
382 | - **Solution**: Use `gate_validation: true/false` parameter correctly
383 | - **Check**: Review prompt_engine parameter documentation
384 |
385 | 4. **Framework Compliance Issues**
386 | - **Cause**: Framework switching affects gate behavior
387 | - **Solution**: Verify active framework with `system_control status`
388 | - **Check**: Framework-specific gate configurations
389 |
390 | ### Debug Tools
391 |
392 | ```bash
393 | # Check gate system health
394 | system_control health
395 |
396 | # View comprehensive system diagnostics
397 | system_control diagnostics
398 |
399 | # Monitor gate performance
400 | system_control analytics include_history=true
401 |
402 | # Reset gate performance metrics if needed
403 | system_control reset_metrics confirm=true
404 | ```
405 |
406 | ## Best Practices
407 |
408 | ### Gate Design
409 | - **Single Responsibility**: Each gate validates one specific aspect
410 | - **Clear Criteria**: Well-defined validation thresholds and targets
411 | - **Meaningful Feedback**: Actionable guidance for failed validations
412 | - **Performance Aware**: Efficient evaluation algorithms and timeouts
413 |
414 | ### Integration Patterns
415 | - **Optional by Default**: Enable gates when quality assurance is needed
416 | - **Chain Validation**: Use automatic gate validation for multi-step processes
417 | - **Framework Alignment**: Choose gates that complement active methodology
418 | - **Progressive Enhancement**: Start with basic gates, add advanced validation as needed
419 |
420 | ### Configuration Management
421 | - **Version Control**: Track gate configuration versions
422 | - **Environment Specific**: Different configs for development/production
423 | - **Performance Testing**: Regular validation of gate evaluation performance
424 | - **Documentation**: Clear documentation for all custom gates and criteria
425 |
426 | ## Monitoring and Observability
427 |
428 | ### Key Metrics
429 | - **Gate Success Rate**: Overall validation success percentage
430 | - **Evaluation Time**: Performance metrics per gate type and strategy
431 | - **Usage Statistics**: Most/least used gates and patterns
432 | - **Error Rates**: Common failure categories and resolution patterns
433 |
434 | ### System Integration Monitoring
435 |
436 | ```bash
437 | # Monitor gate integration with execution types
438 | system_control analytics
439 |
440 | # Track framework + gate combinations
441 | system_control switch_history
442 |
443 | # View system health including gate performance
444 | system_control health
445 | ```
446 |
447 | ## Phase 3: Temporary Gates System (✅ Production Ready)
448 |
449 | ### Overview
450 |
451 | **Status**: ✅ **Complete** (Released 2025-09-29)
452 | **Version**: v1.3.0
453 |
454 | The Temporary Gates System provides dynamic, execution-scoped quality gates that can be created on-demand and automatically cleaned up after use. This system enables flexible quality control for specific executions without permanent configuration changes.
455 |
456 | ### Key Features
457 |
458 | **✅ Implemented Features:**
459 | 1. **5-Level Gate Precedence System**
460 | - Level 1: **Temporary Gates** (Highest Priority) - Runtime-created gates
461 | - Level 2: **Template Gates** - Prompt configuration gates
462 | - Level 3: **Category Gates** - Automatic category-based selection
463 | - Level 4: **Framework Gates** - Methodology-specific gates
464 | - Level 5: **Fallback Gates** (Lowest Priority) - System defaults
465 |
466 | 2. **Multiple Scope Support**
467 | - **Execution-scoped**: Single prompt execution (auto-cleanup)
468 | - **Chain-scoped**: Multi-step workflows with inheritance
469 | - **Step-scoped**: Individual chain steps
470 |
471 | 3. **Automatic Lifecycle Management**
472 | - Time-based expiration (default: 1 hour)
473 | - Scope-based cleanup (chain completion, execution end)
474 | - Memory-efficient registry with automatic pruning
475 |
476 | 4. **MCP Tool Integration**
477 | - 5 dedicated gate management actions in `prompt_manager`
478 | - Hot-reload support for dynamic gate updates
479 | - Full gate configuration persistence
480 |
481 | ### MCP Actions for Gate Management
482 |
483 | The `prompt_manager` tool provides 5 actions for comprehensive gate management:
484 |
485 | #### 1. **create_with_gates** - Create Prompts with Suggested Gates
486 | ```bash
487 | prompt_manager action="create_with_gates" \
488 | id="my_prompt" \
489 | name="My Prompt" \
490 | description="Prompt description" \
491 | category="development" \
492 | user_message_template="Template with {{variable}}" \
493 | arguments='[{"name": "variable", "type": "string"}]' \
494 | suggested_gates='[{"type": "validation", "name": "input_validation", "description": "..."}]'
495 | ```
496 |
497 | **Features:**
498 | - Create prompts with initial gate suggestions
499 | - Analyze prompt intent and recommend appropriate gates
500 | - Automatic gate configuration generation
501 |
502 | #### 2. **update_gates** - Modify Gate Configuration
503 | ```bash
504 | prompt_manager action="update_gates" \
505 | id="my_prompt" \
506 | gate_configuration='{"include": ["code-quality"], "exclude": ["security"], "framework_gates": true}'
507 | ```
508 |
509 | **Features:**
510 | - Update include/exclude gate lists
511 | - Toggle framework gates on/off
512 | - Immediate hot-reload updates
513 |
514 | #### 3. **add_temporary_gates** - Add Runtime Gates
515 | ```bash
516 | prompt_manager action="add_temporary_gates" \
517 | id="my_prompt" \
518 | temporary_gates='[{
519 | "name": "custom_validation",
520 | "type": "validation",
521 | "scope": "execution",
522 | "description": "Custom validation for this execution",
523 | "guidance": "Ensure specific criteria are met",
524 | "pass_criteria": ["Criterion 1", "Criterion 2"]
525 | }]' \
526 | gate_scope="execution" \
527 | inherit_chain_gates=true
528 | ```
529 |
530 | **Features:**
531 | - Add temporary gates to any prompt
532 | - Support execution, chain, and step scopes
533 | - Automatic cleanup after expiration
534 |
535 | #### 4. **analyze_gates** - Gate Analysis and Recommendations
536 | ```bash
537 | prompt_manager action="analyze_gates" \
538 | id="my_prompt"
539 | ```
540 |
541 | **Features:**
542 | - Analyze prompt complexity and recommend gates
543 | - Suggest temporary gates for specific use cases
544 | - Provide gate configuration templates
545 |
546 | #### 5. **suggest_temporary_gates** - Contextual Gate Suggestions
547 | ```bash
548 | prompt_manager action="suggest_temporary_gates" \
549 | id="my_prompt" \
550 | execution_context='{"complexity": "high", "domain": "security"}'
551 | ```
552 |
553 | **Features:**
554 | - Context-aware gate suggestions
555 | - Automatic temporary gate generation
556 | - Integration with semantic analysis
557 |
558 | ### Chain-Level Gate Inheritance (Phase 3B)
559 |
560 | **Feature**: Chain-scoped temporary gates automatically inherit to all child steps.
561 |
562 | **Implementation:**
563 | - Unique chain execution IDs track gate scope
564 | - `chainGateIds` array propagates gates to steps
565 | - Hierarchical cleanup removes chain + step gates
566 |
567 | **Example:**
568 | ```bash
569 | # Create chain with temporary gates
570 | prompt_manager action="add_temporary_gates" \
571 | id="analysis_chain" \
572 | temporary_gates='[{
573 | "name": "chain_quality_gate",
574 | "type": "quality",
575 | "scope": "chain",
576 | "description": "Quality standards for entire chain",
577 | "guidance": "Maintain quality across all steps",
578 | "pass_criteria": ["All steps complete", "Results coherent"]
579 | }]' \
580 | gate_scope="chain"
581 |
582 | # Execute chain - all steps automatically inherit chain gates
583 | prompt_engine >>analysis_chain input="data"
584 | ```
585 |
586 | **Benefits:**
587 | - Consistent quality standards across multi-step workflows
588 | - Reduced configuration (set once, apply to all steps)
589 | - Automatic cleanup after chain completion
590 |
591 | ### Temporary Gate Lifecycle
592 |
593 | ```
594 | ┌─────────────────────────────────────────────────┐
595 | │ 1. CREATION │
596 | │ - Via add_temporary_gates MCP action │
597 | │ - Or automatically by semantic analysis │
598 | │ - Assigned unique ID and creation timestamp │
599 | └─────────────────────────────────────────────────┘
600 | │
601 | ▼
602 | ┌─────────────────────────────────────────────────┐
603 | │ 2. ACTIVATION │
604 | │ - Loaded during prompt execution │
605 | │ - Highest precedence in 5-level system │
606 | │ - Merged with other gate levels │
607 | └─────────────────────────────────────────────────┘
608 | │
609 | ▼
610 | ┌─────────────────────────────────────────────────┐
611 | │ 3. EXECUTION │
612 | │ - Validation against pass_criteria │
613 | │ - Guidance injected into system prompt │
614 | │ - Results tracked in gate registry │
615 | └─────────────────────────────────────────────────┘
616 | │
617 | ▼
618 | ┌─────────────────────────────────────────────────┐
619 | │ 4. CLEANUP │
620 | │ - Time-based: Expires after 1 hour (default) │
621 | │ - Scope-based: Chain completion cleanup │
622 | │ - Manual: cleanupChainExecution() method │
623 | └─────────────────────────────────────────────────┘
624 | ```
625 |
626 | ### Use Cases
627 |
628 | **1. One-Time Validation Requirements**
629 | ```bash
630 | # Add temporary gate for specific execution
631 | prompt_manager action="add_temporary_gates" \
632 | id="code_review" \
633 | temporary_gates='[{
634 | "name": "security_audit",
635 | "type": "validation",
636 | "scope": "execution",
637 | "description": "Extra security validation for sensitive code",
638 | "pass_criteria": ["No hardcoded credentials", "All inputs validated"]
639 | }]'
640 | ```
641 |
642 | **2. Chain Workflow Quality Standards**
643 | ```bash
644 | # Set chain-wide quality gates
645 | prompt_manager action="add_temporary_gates" \
646 | id="data_pipeline" \
647 | temporary_gates='[{
648 | "name": "data_quality",
649 | "type": "quality",
650 | "scope": "chain",
651 | "description": "Data quality standards for entire pipeline",
652 | "pass_criteria": ["No null values", "Schema validated"]
653 | }]' \
654 | gate_scope="chain"
655 | ```
656 |
657 | **3. Context-Specific Guidance**
658 | ```bash
659 | # Add guidance gate for novice users
660 | prompt_manager action="add_temporary_gates" \
661 | id="tutorial_prompt" \
662 | temporary_gates='[{
663 | "name": "beginner_guidance",
664 | "type": "guidance",
665 | "scope": "execution",
666 | "description": "Extra explanation for learning",
667 | "guidance": "Provide step-by-step explanations with examples"
668 | }]'
669 | ```
670 |
671 | ### Architecture Components
672 |
673 | #### 1. Temporary Gate Registry (`temporary-gate-registry.ts`)
674 | **Features:**
675 | - In-memory storage with TTL management
676 | - Scope-based retrieval (execution, chain, step)
677 | - Automatic cleanup on expiration
678 | - Chain hierarchy cleanup methods
679 |
680 | **Key Methods:**
681 | - `createTemporaryGate(definition, scopeId)` - Create new temporary gate
682 | - `getTemporaryGatesForScope(scope, scopeId)` - Retrieve gates for scope
683 | - `cleanupChainExecution(chainExecutionId)` - Clean up chain + step gates
684 | - `cleanupExpiredGates()` - Remove expired gates (runs periodically)
685 |
686 | #### 2. Gate Configuration Types (`execution/types.ts`)
687 | **EnhancedGateConfiguration Interface:**
688 | ```typescript
689 | interface EnhancedGateConfiguration {
690 | include?: string[];
691 | exclude?: string[];
692 | framework_gates?: boolean;
693 | temporary_gates?: TemporaryGateDefinition[];
694 | gate_scope?: 'execution' | 'session' | 'chain' | 'step';
695 | inherit_chain_gates?: boolean;
696 | }
697 | ```
698 |
699 | #### 3. Chain Gate Inheritance (`executor.ts`)
700 | **Features:**
701 | - Automatic chain execution ID generation
702 | - Chain-scoped gate creation before step execution
703 | - Gate IDs propagated to metadata for step inheritance
704 | - Documentation in chain instructions
705 |
706 | ### Performance Characteristics
707 |
708 | **Memory Usage:**
709 | - Temporary gates: ~1KB per gate
710 | - Registry overhead: ~10KB base
711 | - Automatic cleanup prevents memory leaks
712 | - Recommended limit: <1000 concurrent temporary gates
713 |
714 | **Execution Impact:**
715 | - Gate creation: <1ms
716 | - Gate retrieval: <1ms (in-memory lookup)
717 | - Precedence resolution: <5ms (5 levels)
718 | - Cleanup: <10ms (batch operations)
719 |
720 | **Total Overhead:**
721 | - Single execution: ~10ms
722 | - Chain execution: ~20ms (includes inheritance)
723 | - Negligible impact on overall execution time
724 |
725 | ### Testing and Validation
726 |
727 | **Phase 3A: Bug Fixes & Validation** ✅
728 | - Fixed `add_temporary_gates` parameter validation
729 | - Created comprehensive test prompts
730 | - Verified MCP schema completeness
731 | - TypeScript compilation validated
732 |
733 | **Phase 3B: Chain-Level Gate Inheritance** ✅
734 | - Implemented chain-scoped gate creation
735 | - Added hierarchical cleanup methods
736 | - Extended ChainExecutionContext with gate tracking
737 | - Validated gate persistence and loading
738 |
739 | **Phase 3C: Session-Scoped Gates** ❌ SKIPPED
740 | - Determined not applicable for stateless MCP architecture
741 | - Existing scopes (execution, chain, step) provide sufficient coverage
742 | - No session lifecycle in MCP protocol
743 |
744 | **Phase 3D: Comprehensive Testing** ✅
745 | - All 5 MCP gate actions validated
746 | - 5-level precedence system tested
747 | - Performance benchmarks confirmed
748 | - Documentation complete
749 |
750 | ### Migration Notes
751 |
752 | **From Phase 2 to Phase 3:**
753 | - Existing gate configurations remain compatible
754 | - No breaking changes to gate definitions
755 | - New temporary gates are additive feature
756 | - Hot-reload maintains server uptime
757 |
758 | **Backward Compatibility:**
759 | - All existing prompts work without modification
760 | - Temporary gates are optional enhancement
761 | - Framework gates continue to function
762 | - No configuration migrations required
763 |
764 | ## Future Enhancements
765 |
766 | ### Planned Improvements
767 |
768 | #### **MCP Tool Integration** (Roadmap)
769 | - **Dedicated Gate Management Tools**: Standalone tools for gate configuration
770 | - **Visual Gate Designer**: GUI tools for complex gate creation
771 | - **Testing Framework**: Comprehensive gate testing and validation tools
772 | - **Custom Evaluator API**: Plugin system for user-defined validation logic
773 |
774 | #### **Advanced Validation** (Research Phase)
775 | - **Machine Learning Gates**: AI-powered validation with learning capabilities
776 | - **Real-time Adaptation**: Dynamic gate configuration based on content patterns
777 | - **Cross-Framework Validation**: Methodology mixing and hybrid approaches
778 | - **Integration APIs**: Third-party system integration for specialized validation
779 |
780 | #### **Performance Optimization** (Next Release)
781 | - **Caching System**: Gate configuration and result caching
782 | - **Parallel Processing**: Multiple requirements evaluated simultaneously
783 | - **Circuit Breakers**: Automatic fallback for consistently failing gates
784 | - **Resource Management**: Intelligent resource allocation for gate evaluation
785 |
786 | ### Migration Path
787 |
788 | **Current State**: 19 implemented evaluators with strategy-based architecture
789 | **Next Phase**: Enhanced MCP integration and advanced validation features
790 | **Long-term**: AI-powered validation and cross-system integration
791 |
792 | ## Conclusion
793 |
794 | The Enhanced Gate System provides a sophisticated, production-ready validation framework that integrates seamlessly with the consolidated MCP architecture. With **19 specialized evaluators** organized into **4 strategic categories**, it offers comprehensive quality assurance while maintaining performance and usability.
795 |
796 | **Key Strengths**:
797 | - **Comprehensive Coverage**: 19+ gate types covering all major validation needs
798 | - **Strategic Architecture**: Organized, maintainable code with clear separation of concerns
799 | - **Consolidated Integration**: Works seamlessly with the 3-tool MCP architecture
800 | - **Framework Awareness**: Adapts to active methodology frameworks
801 | - **Performance Focused**: Efficient evaluation with comprehensive monitoring
802 |
803 | The system is designed for production use with extensive error handling, performance monitoring, and intelligent recovery mechanisms. It provides the quality assurance infrastructure needed for professional AI prompt execution while maintaining the simplicity and efficiency of the consolidated tool architecture.
804 |
805 | For implementation details and advanced configuration options, see the source code in `/server/src/gates/` and the consolidated tool integration in `/server/src/mcp-tools/`.
```
--------------------------------------------------------------------------------
/plans/parallel-conditional-execution-analysis.md:
--------------------------------------------------------------------------------
```markdown
1 | # Parallel & Conditional Execution - Current System Analysis
2 |
3 | **Status**: Analysis Complete
4 | **Created**: 2025-10-19
5 | **Priority**: High
6 | **Complexity**: Medium-High (Parallel), High (Conditional)
7 |
8 | ## Executive Summary
9 |
10 | **Parallel Execution**: ✅ **Architecturally Designed** but ❌ **NOT Implemented**
11 | **Conditional Execution**: ⚠️ **Template-Level Only** (Nunjucks conditionals, not execution branching)
12 | **Parser Support**: ❌ **Neither operator currently detectable**
13 |
14 | **Key Finding**: The system is **instruction-based** (generates instructions for LLM to execute steps) rather than **execution-based** (server executes steps directly). This architectural choice impacts how parallel and conditional operators can be implemented.
15 |
16 | ## Detailed Findings
17 |
18 | ### 1. Parallel Execution Status
19 |
20 | #### ✅ Type Definitions Exist (Infrastructure Ready)
21 |
22 | **Location**: `server/src/execution/types.ts:39`
23 | ```typescript
24 | export interface ChainStep {
25 | parallelGroup?: string; // Group ID for parallel execution (steps with same group run concurrently)
26 | dependencies?: string[]; // Step IDs that must complete before this step
27 | timeout?: number; // Step-specific timeout in milliseconds
28 | retries?: number; // Number of retries for this step
29 | stepType?: 'prompt' | 'tool' | 'gate' | 'condition';
30 | }
31 | ```
32 |
33 | **Location**: `server/src/execution/types.ts:237`
34 | ```typescript
35 | export interface EnhancedChainExecutionOptions {
36 | enableParallelExecution?: boolean; // Enable parallel execution of steps in same parallel group
37 | maxConcurrency?: number; // Maximum concurrent steps
38 | parallelTimeout?: number; // Timeout for parallel groups
39 | }
40 | ```
41 |
42 | **Location**: `server/src/types/index.ts:150`
43 | ```typescript
44 | export interface EnhancedChainExecutionContext {
45 | executionPlan?: {
46 | executionOrder: string[]; // Topologically sorted step execution order
47 | parallelGroups: Map<string, string[]>; // Parallel execution groups
48 | };
49 | activeParallelGroups: Map<string, string[]>; // Currently executing parallel groups
50 | retryCount: Record<string, number>; // Retry attempts per step
51 | }
52 | ```
53 |
54 | #### ❌ Execution Logic NOT Implemented
55 |
56 | **Current Chain Execution**: `server/src/mcp-tools/prompt-engine/core/executor.ts:437`
57 | ```typescript
58 | // generateChainInstructions() - Returns instructions for LLM to execute
59 | instructions += `- Execute steps sequentially, do not skip steps\n`;
60 | instructions += `- Validate outputs before proceeding to next step\n`;
61 | ```
62 |
63 | **Reality**:
64 | - Chain executor generates **Markdown instructions** for LLM to execute steps
65 | - No server-side step execution engine
66 | - LLM is responsible for calling MCP tools for each step
67 | - No `Promise.all()` or concurrent execution logic
68 |
69 | **Missing Components**:
70 | 1. **Parallel Step Executor**: No code to execute multiple steps concurrently
71 | 2. **Dependency Resolver**: No topological sorting implementation
72 | 3. **Result Aggregator**: No logic to merge parallel step results
73 | 4. **Scheduler**: No parallel group scheduling
74 | 5. **Synchronization**: No coordination between parallel steps
75 |
76 | **Detection Only**: `server/src/semantic/configurable-semantic-analyzer.ts:595`
77 | ```typescript
78 | if ((step as any).parallelGroup) {
79 | hasParallelSteps = true;
80 | // Only used for semantic analysis/classification, not execution
81 | }
82 | ```
83 |
84 | ### 2. Conditional Execution Status
85 |
86 | #### ⚠️ Template-Level Conditionals Only (Nunjucks)
87 |
88 | **What EXISTS**: Nunjucks template conditionals in user message templates
89 |
90 | **Example**: `server/prompts/analysis/advanced_analysis_engine.md`
91 | ```nunjucks
92 | {% if depth == 'expert' %}
93 | ## Expert-Level Analysis Required
94 | Apply rigorous academic standards...
95 | {% elif depth == 'comprehensive' %}
96 | ## Comprehensive Analysis
97 | Thorough examination with detailed coverage...
98 | {% else %}
99 | ## Standard Analysis
100 | Balanced approach with key insights...
101 | {% endif %}
102 | ```
103 |
104 | **Classification Detection**: `server/src/mcp-tools/prompt-engine/utils/classification.ts:222`
105 | ```typescript
106 | const conditionals = (convertedPrompt.userMessageTemplate.match(/\{%\s*(if|for|while)\s/g) || []).length;
107 | complexity += conditionals * 0.1;
108 | ```
109 |
110 | **Behavior**: Conditionals evaluated at **template rendering time** based on input arguments, NOT based on execution results.
111 |
112 | #### ❌ What DOESN'T EXIST: Execution-Level Conditional Branching
113 |
114 | **Missing Capabilities**:
115 | 1. **Dynamic Step Selection**: No ability to choose next step based on previous result
116 | 2. **LLM-Evaluated Conditions**: No condition evaluation against execution output
117 | 3. **Branching Logic**: No "if step1 succeeds then step2a else step2b" workflow
118 | 4. **Result-Based Routing**: No decision points in execution flow
119 | 5. **Conditional Operator**: No `?` operator parsing or execution
120 |
121 | **Closest Analogy - Gate Conditionals**: `server/src/mcp-tools/prompt-engine/core/engine.ts:1589-1617`
122 | ```typescript
123 | // Only conditional logic in execution system: gate result rendering
124 | this.logger.info(`🔍 [DEBUG] Gate conditional logic:`, {
125 | hasGateResults: !!gateResults
126 | });
127 |
128 | if (gateResults) {
129 | this.logger.info(`🔀 [DEBUG] Taking IF branch (gateResults exists)`);
130 | // Render gate results
131 | return this.renderGateResults(gateResults, template);
132 | } else {
133 | this.logger.info(`🔀 [DEBUG] Taking ELSE branch (no gateResults)`);
134 | // Render gate guidance
135 | return this.renderGateGuidance(applicableGates, template);
136 | }
137 | ```
138 |
139 | **Note**: This is **gate rendering logic** for UI display, not execution branching.
140 |
141 | ### 3. Parser Support Status
142 |
143 | #### ❌ NO Symbolic Operator Detection
144 |
145 | **Current Parser**: `server/src/execution/parsers/unified-command-parser.ts`
146 |
147 | **Supported Formats**:
148 | ```typescript
149 | private initializeStrategies(): ParsingStrategy[] {
150 | return [
151 | this.createSimpleCommandStrategy(), // >>prompt_name arguments
152 | this.createJsonCommandStrategy() // {"command": ">>prompt", "args": {...}}
153 | ];
154 | }
155 | ```
156 |
157 | **Operator Detection Patterns - NOT IMPLEMENTED**:
158 | - ❌ Chain operator: `-->`
159 | - ❌ Parallel operator: `+`
160 | - ❌ Conditional operator: `?`
161 | - ❌ Gate operator: `=`
162 | - ❌ Framework operator: `@`
163 |
164 | **Current Regex Patterns**: `server/src/execution/parsers/unified-command-parser.ts:132-138`
165 | ```typescript
166 | canHandle: (command: string) => {
167 | // More flexible pattern - handles spaces in prompt names via underscore conversion
168 | return /^(>>|\/)[a-zA-Z0-9_\-\s]+(\s|$)/.test(command.trim());
169 | }
170 | ```
171 |
172 | **No symbolic operators** in detection patterns.
173 |
174 | ### 4. Test Evidence
175 |
176 | #### Concurrent Command Processing Test
177 |
178 | **Location**: `tests/integration/unified-parsing-integration.test.ts:414-428`
179 | ```typescript
180 | test('should handle concurrent command processing', async () => {
181 | const concurrentCommands = [
182 | '>>simple_test concurrent test 1',
183 | '>>multi_arg_test concurrent test 2',
184 | '>>simple_test concurrent test 3'
185 | ];
186 |
187 | const promises = concurrentCommands.map(command =>
188 | parsingSystem.commandParser.parseCommand(command, promptsData)
189 | );
190 |
191 | const results = await Promise.all(promises);
192 |
193 | expect(results).toHaveLength(3);
194 | expect(stats.commandParser.totalParses).toBe(concurrentCommands.length);
195 | });
196 | ```
197 |
198 | **What This Tests**:
199 | - Parser **thread-safety** (handling multiple parse requests concurrently)
200 | - Multiple **independent commands** processed in parallel
201 |
202 | **What This Does NOT Test**:
203 | - Parallel execution of **steps within a single chain**
204 | - Concurrent **prompt execution**
205 | - Parallel **step result aggregation**
206 |
207 | ## Architectural Implications
208 |
209 | ### Current Architecture: Instruction-Based Execution
210 |
211 | ```
212 | ┌─────────────────────────────────────────────────────────────┐
213 | │ User Command: >>chain_prompt args │
214 | └────────────────┬────────────────────────────────────────────┘
215 | │
216 | ▼
217 | ┌─────────────────────────────────────────────────────────────┐
218 | │ Parser: Detect chain, parse steps │
219 | └────────────────┬────────────────────────────────────────────┘
220 | │
221 | ▼
222 | ┌─────────────────────────────────────────────────────────────┐
223 | │ ChainExecutor: Generate Markdown instructions │
224 | │ - Step 1: Call >>prompt1 │
225 | │ - Step 2: Call >>prompt2 with step1_result │
226 | │ - Step 3: Call >>prompt3 with step2_result │
227 | └────────────────┬────────────────────────────────────────────┘
228 | │
229 | ▼
230 | ┌─────────────────────────────────────────────────────────────┐
231 | │ Return instructions to LLM (Claude Code) │
232 | └────────────────┬────────────────────────────────────────────┘
233 | │
234 | ▼
235 | ┌─────────────────────────────────────────────────────────────┐
236 | │ LLM executes steps manually: │
237 | │ - Calls prompt_engine tool for each step │
238 | │ - Manages context/results between steps │
239 | │ - Handles errors and retries │
240 | └─────────────────────────────────────────────────────────────┘
241 | ```
242 |
243 | **Key Characteristics**:
244 | - ✅ Flexible (LLM can adapt execution)
245 | - ✅ Error-resilient (LLM handles issues)
246 | - ❌ No true parallel execution (LLM is sequential)
247 | - ❌ Slower (multiple MCP tool calls)
248 | - ❌ No deterministic branching (LLM makes decisions)
249 |
250 | ### Alternative Architecture: Server-Side Execution Engine
251 |
252 | ```
253 | ┌─────────────────────────────────────────────────────────────┐
254 | │ User Command: >>step1 + step2 + step3 --> synthesis │
255 | └────────────────┬────────────────────────────────────────────┘
256 | │
257 | ▼
258 | ┌─────────────────────────────────────────────────────────────┐
259 | │ Parser: Detect operators (+, -->) │
260 | │ - Parallel group: [step1, step2, step3] │
261 | │ - Sequential: synthesis │
262 | └────────────────┬────────────────────────────────────────────┘
263 | │
264 | ▼
265 | ┌─────────────────────────────────────────────────────────────┐
266 | │ ExecutionEngine: Build execution plan │
267 | │ - Parallel group 1: Execute step1, step2, step3 concurrently │
268 | │ - Wait for all to complete │
269 | │ - Sequential: Execute synthesis with aggregated results │
270 | └────────────────┬────────────────────────────────────────────┘
271 | │
272 | ▼
273 | ┌─────────────────────────────────────────────────────────────┐
274 | │ StepExecutor: Execute each step │
275 | │ Promise.all([ │
276 | │ executePrompt('step1'), │
277 | │ executePrompt('step2'), │
278 | │ executePrompt('step3') │
279 | │ ]) │
280 | └────────────────┬────────────────────────────────────────────┘
281 | │
282 | ▼
283 | ┌─────────────────────────────────────────────────────────────┐
284 | │ ResultAggregator: Merge parallel results │
285 | │ aggregatedResult = { │
286 | │ step1_result: "...", │
287 | │ step2_result: "...", │
288 | │ step3_result: "..." │
289 | │ } │
290 | └────────────────┬────────────────────────────────────────────┘
291 | │
292 | ▼
293 | ┌─────────────────────────────────────────────────────────────┐
294 | │ Continue execution with synthesis step │
295 | │ executePrompt('synthesis', aggregatedResult) │
296 | └────────────────┬────────────────────────────────────────────┘
297 | │
298 | ▼
299 | ┌─────────────────────────────────────────────────────────────┐
300 | │ Return final result to user │
301 | └─────────────────────────────────────────────────────────────┘
302 | ```
303 |
304 | **Key Characteristics**:
305 | - ✅ True parallel execution (real concurrency)
306 | - ✅ Faster (single MCP interaction)
307 | - ✅ Deterministic (predictable execution flow)
308 | - ❌ Less flexible (fixed execution plan)
309 | - ❌ Complex error handling needed
310 | - ❌ Major architectural change
311 |
312 | ## Gap Analysis
313 |
314 | ### Components Needed for Parallel Execution
315 |
316 | #### 1. Parser Enhancement (**Estimated: 2-3 days**)
317 |
318 | **File**: `server/src/execution/parsers/symbolic-command-parser.ts` (new)
319 |
320 | ```typescript
321 | export class SymbolicCommandParser {
322 | private readonly PARALLEL_PATTERN = /\s*\+\s*/g;
323 |
324 | detectParallelOperator(command: string): {
325 | hasParallel: boolean;
326 | prompts: string[];
327 | } {
328 | if (!this.PARALLEL_PATTERN.test(command)) {
329 | return { hasParallel: false, prompts: [] };
330 | }
331 |
332 | const prompts = command.split('+').map(p => p.trim());
333 | return {
334 | hasParallel: true,
335 | prompts
336 | };
337 | }
338 | }
339 | ```
340 |
341 | #### 2. Execution Engine (**Estimated: 1-2 weeks**)
342 |
343 | **File**: `server/src/execution/engines/parallel-executor.ts` (new)
344 |
345 | ```typescript
346 | export class ParallelExecutor {
347 | /**
348 | * Execute multiple steps concurrently
349 | */
350 | async executeParallelGroup(
351 | steps: ChainStep[],
352 | context: ExecutionContext
353 | ): Promise<ParallelExecutionResult> {
354 | this.logger.info(`Executing ${steps.length} steps in parallel`);
355 |
356 | const promises = steps.map(step =>
357 | this.executeStep(step, context)
358 | );
359 |
360 | const results = await Promise.all(promises);
361 |
362 | return this.aggregateResults(results);
363 | }
364 |
365 | private async executeStep(
366 | step: ChainStep,
367 | context: ExecutionContext
368 | ): Promise<StepResult> {
369 | // Execute individual step
370 | // This requires actual prompt execution, not instruction generation
371 | }
372 |
373 | private aggregateResults(
374 | results: StepResult[]
375 | ): ParallelExecutionResult {
376 | // Merge results from parallel executions
377 | return {
378 | combinedOutput: results.map(r => r.output).join('\n\n'),
379 | stepResults: results,
380 | metadata: {
381 | executionTime: Math.max(...results.map(r => r.executionTime)),
382 | stepCount: results.length
383 | }
384 | };
385 | }
386 | }
387 | ```
388 |
389 | #### 3. Dependency Resolver (**Estimated: 3-5 days**)
390 |
391 | **File**: `server/src/execution/engines/dependency-resolver.ts` (new)
392 |
393 | ```typescript
394 | export class DependencyResolver {
395 | /**
396 | * Topological sort of steps based on dependencies
397 | */
398 | resolveExecutionOrder(steps: ChainStep[]): ExecutionPlan {
399 | const graph = this.buildDependencyGraph(steps);
400 | const executionOrder = this.topologicalSort(graph);
401 | const parallelGroups = this.identifyParallelGroups(steps, executionOrder);
402 |
403 | return {
404 | executionOrder,
405 | parallelGroups,
406 | estimatedTime: this.estimateExecutionTime(parallelGroups)
407 | };
408 | }
409 |
410 | private identifyParallelGroups(
411 | steps: ChainStep[],
412 | executionOrder: string[]
413 | ): Map<string, string[]> {
414 | const groups = new Map<string, string[]>();
415 |
416 | // Group steps with same parallelGroup ID
417 | for (const step of steps) {
418 | if (step.parallelGroup) {
419 | const existing = groups.get(step.parallelGroup) || [];
420 | existing.push(step.promptId);
421 | groups.set(step.parallelGroup, existing);
422 | }
423 | }
424 |
425 | return groups;
426 | }
427 |
428 | private topologicalSort(graph: DependencyGraph): string[] {
429 | // Kahn's algorithm or DFS-based topological sort
430 | // Returns execution order respecting dependencies
431 | }
432 | }
433 | ```
434 |
435 | #### 4. State Management (**Estimated: 3-5 days**)
436 |
437 | **File**: `server/src/execution/engines/execution-state-manager.ts` (new)
438 |
439 | ```typescript
440 | export class ExecutionStateManager {
441 | private activeExecutions = new Map<string, ExecutionState>();
442 |
443 | trackParallelGroup(
444 | groupId: string,
445 | stepIds: string[]
446 | ): void {
447 | const state = this.getOrCreateState(groupId);
448 | state.activeSteps = stepIds;
449 | state.startTime = Date.now();
450 | }
451 |
452 | recordStepCompletion(
453 | groupId: string,
454 | stepId: string,
455 | result: StepResult
456 | ): void {
457 | const state = this.getState(groupId);
458 | state.completedSteps.add(stepId);
459 | state.stepResults[stepId] = result;
460 |
461 | // Check if group is complete
462 | if (state.completedSteps.size === state.activeSteps.length) {
463 | this.finalizeGroup(groupId);
464 | }
465 | }
466 |
467 | handleStepFailure(
468 | groupId: string,
469 | stepId: string,
470 | error: Error
471 | ): void {
472 | const state = this.getState(groupId);
473 | state.failedSteps.add(stepId);
474 |
475 | // Decide: fail fast or continue with partial results?
476 | }
477 | }
478 | ```
479 |
480 | ### Components Needed for Conditional Execution
481 |
482 | #### 1. Parser Enhancement (**Estimated: 2-3 days**)
483 |
484 | **File**: `server/src/execution/parsers/symbolic-command-parser.ts` (enhancement)
485 |
486 | ```typescript
487 | export class SymbolicCommandParser {
488 | private readonly CONDITIONAL_PATTERN = /\?\s*["'](.+?)["']\s*:\s*(\w+)(?:\s*:\s*(\w+))?/;
489 |
490 | detectConditionalOperator(command: string): {
491 | hasConditional: boolean;
492 | condition: string;
493 | trueBranch: string;
494 | falseBranch?: string;
495 | } {
496 | const match = command.match(this.CONDITIONAL_PATTERN);
497 |
498 | if (!match) {
499 | return { hasConditional: false, condition: '', trueBranch: '' };
500 | }
501 |
502 | return {
503 | hasConditional: true,
504 | condition: match[1],
505 | trueBranch: match[2],
506 | falseBranch: match[3]
507 | };
508 | }
509 | }
510 | ```
511 |
512 | #### 2. Condition Evaluator (**Estimated: 1 week**)
513 |
514 | **File**: `server/src/execution/engines/condition-evaluator.ts` (new)
515 |
516 | ```typescript
517 | export class ConditionEvaluator {
518 | /**
519 | * Evaluate condition against execution result
520 | */
521 | async evaluateCondition(
522 | condition: string,
523 | executionResult: any
524 | ): Promise<boolean> {
525 | const conditionType = this.detectConditionType(condition);
526 |
527 | switch (conditionType) {
528 | case 'presence':
529 | return this.evaluatePresenceCondition(condition, executionResult);
530 | case 'comparison':
531 | return this.evaluateComparisonCondition(condition, executionResult);
532 | case 'pattern':
533 | return this.evaluatePatternCondition(condition, executionResult);
534 | case 'llm':
535 | return this.evaluateLLMCondition(condition, executionResult);
536 | }
537 | }
538 |
539 | private evaluatePresenceCondition(
540 | condition: string,
541 | result: any
542 | ): boolean {
543 | // Check if result contains specific text/pattern
544 | return result.toLowerCase().includes(condition.toLowerCase());
545 | }
546 |
547 | private async evaluateLLMCondition(
548 | condition: string,
549 | result: any
550 | ): Promise<boolean> {
551 | // Use LLM to evaluate complex conditions
552 | const prompt = `Evaluate if this condition is true: "${condition}"
553 |
554 | Given the following execution result:
555 | ${result}
556 |
557 | Return ONLY "true" or "false".`;
558 |
559 | const evaluation = await this.callLLM(prompt);
560 | return evaluation.toLowerCase().includes('true');
561 | }
562 | }
563 | ```
564 |
565 | #### 3. Dynamic Step Selector (**Estimated: 3-5 days**)
566 |
567 | **File**: `server/src/execution/engines/step-selector.ts` (new)
568 |
569 | ```typescript
570 | export class StepSelector {
571 | /**
572 | * Select next step based on condition evaluation
573 | */
574 | async selectNextStep(
575 | conditionalOp: ConditionalOperator,
576 | previousResult: any
577 | ): Promise<string> {
578 | const conditionMet = await this.conditionEvaluator.evaluateCondition(
579 | conditionalOp.condition,
580 | previousResult
581 | );
582 |
583 | if (conditionMet) {
584 | this.logger.info(`Condition "${conditionalOp.condition}" is TRUE, executing: ${conditionalOp.trueBranch}`);
585 | return conditionalOp.trueBranch;
586 | } else {
587 | if (conditionalOp.falseBranch) {
588 | this.logger.info(`Condition "${conditionalOp.condition}" is FALSE, executing: ${conditionalOp.falseBranch}`);
589 | return conditionalOp.falseBranch;
590 | } else {
591 | this.logger.info(`Condition "${conditionalOp.condition}" is FALSE, no false branch, stopping`);
592 | return null;
593 | }
594 | }
595 | }
596 |
597 | /**
598 | * Build dynamic execution path based on conditions
599 | */
600 | async buildConditionalPath(
601 | initialStep: ChainStep,
602 | conditionals: ConditionalOperator[]
603 | ): Promise<ChainStep[]> {
604 | const path: ChainStep[] = [initialStep];
605 | let currentResult = null;
606 |
607 | for (const conditional of conditionals) {
608 | const nextStepId = await this.selectNextStep(conditional, currentResult);
609 | if (!nextStepId) break;
610 |
611 | const nextStep = this.findStep(nextStepId);
612 | path.push(nextStep);
613 |
614 | // Would need to execute step to get result for next condition
615 | currentResult = await this.executeStep(nextStep);
616 | }
617 |
618 | return path;
619 | }
620 | }
621 | ```
622 |
623 | #### 4. Branch Execution Engine (**Estimated: 1 week**)
624 |
625 | **File**: `server/src/execution/engines/branch-executor.ts` (new)
626 |
627 | ```typescript
628 | export class BranchExecutor {
629 | /**
630 | * Execute conditional branches
631 | */
632 | async executeConditionalBranch(
633 | mainStep: ChainStep,
634 | conditionalOp: ConditionalOperator,
635 | context: ExecutionContext
636 | ): Promise<BranchExecutionResult> {
637 | // Execute main step
638 | const mainResult = await this.executeStep(mainStep, context);
639 |
640 | // Evaluate condition
641 | const conditionMet = await this.conditionEvaluator.evaluateCondition(
642 | conditionalOp.condition,
643 | mainResult
644 | );
645 |
646 | // Execute appropriate branch
647 | const branchStepId = conditionMet
648 | ? conditionalOp.trueBranch
649 | : conditionalOp.falseBranch;
650 |
651 | if (!branchStepId) {
652 | return {
653 | mainResult,
654 | branchResult: null,
655 | conditionMet,
656 | executionPath: [mainStep.promptId]
657 | };
658 | }
659 |
660 | const branchStep = this.findStep(branchStepId);
661 | const branchResult = await this.executeStep(branchStep, {
662 | ...context,
663 | previousResult: mainResult
664 | });
665 |
666 | return {
667 | mainResult,
668 | branchResult,
669 | conditionMet,
670 | executionPath: [mainStep.promptId, branchStep.promptId]
671 | };
672 | }
673 | }
674 | ```
675 |
676 | ## Implementation Strategies
677 |
678 | ### Strategy 1: Hybrid Approach (Recommended)
679 |
680 | **Concept**: Extend instruction-based system with server-side execution for operators
681 |
682 | **Parallel Operator Implementation**:
683 | ```
684 | 1. Parser detects `+` operator
685 | 2. Generate instructions that include:
686 | - "Execute steps 1, 2, 3 in parallel using separate MCP tool calls"
687 | - "Wait for all to complete before proceeding"
688 | - Provide result aggregation template
689 | 3. LLM executes steps concurrently (multiple tool calls)
690 | 4. LLM aggregates results following template
691 | ```
692 |
693 | **Pros**:
694 | - ✅ Minimal architectural change
695 | - ✅ Leverages existing instruction system
696 | - ✅ LLM handles error cases flexibly
697 | - ✅ Quick to implement (parser + instruction templates)
698 |
699 | **Cons**:
700 | - ❌ Not true server-side parallelism
701 | - ❌ Depends on LLM's ability to parallelize
702 | - ❌ Variable execution patterns
703 |
704 | ### Strategy 2: Server-Side Execution Engine (Future)
705 |
706 | **Concept**: Build full execution engine with actual step execution
707 |
708 | **Implementation**:
709 | ```
710 | 1. Parser detects operators and builds execution plan
711 | 2. ExecutionEngine executes steps directly:
712 | - ParallelExecutor for `+` groups
713 | - ConditionalExecutor for `?` branches
714 | - SequentialExecutor for `-->` chains
715 | 3. Return final aggregated result to LLM
716 | ```
717 |
718 | **Pros**:
719 | - ✅ True parallel execution
720 | - ✅ Deterministic execution flow
721 | - ✅ Performance optimization
722 | - ✅ Consistent behavior
723 |
724 | **Cons**:
725 | - ❌ Major architectural change
726 | - ❌ Complex error handling
727 | - ❌ Longer development time (2-3 months)
728 | - ❌ Loss of LLM flexibility
729 |
730 | ### Strategy 3: Progressive Enhancement (Pragmatic)
731 |
732 | **Concept**: Start with Strategy 1, evolve toward Strategy 2
733 |
734 | **Phase 1** (Weeks 1-2): Instruction-based operators
735 | - Implement `-->`, `=`, `@` with instruction generation
736 | - Add `+` with parallel execution instructions for LLM
737 |
738 | **Phase 2** (Weeks 3-4): Partial server-side execution
739 | - Implement simple parallel executor for `+` operator
740 | - Keep complex chains as instructions
741 | - Measure performance improvements
742 |
743 | **Phase 3** (Months 2-3): Full execution engine
744 | - Build complete server-side execution system
745 | - Migrate all operators to execution engine
746 | - Maintain backward compatibility with instruction mode
747 |
748 | **Pros**:
749 | - ✅ Immediate value from Phase 1
750 | - ✅ Incremental investment
751 | - ✅ Learn from usage patterns
752 | - ✅ Minimize risk
753 |
754 | **Cons**:
755 | - ⚠️ Longer overall timeline
756 | - ⚠️ Temporary code duplication
757 | - ⚠️ Multiple refactorings
758 |
759 | ## Recommendations
760 |
761 | ### Immediate Actions (This Week)
762 |
763 | 1. **Update Implementation Plan**: Revise `symbolic-command-language-implementation.md` with architecture insights
764 | 2. **Choose Strategy**: Recommend **Strategy 3 (Progressive Enhancement)**
765 | 3. **Prioritize Operators**:
766 | - **Phase 1A**: `-->` (chain), `=` (gate), `@` (framework) - Instruction-based
767 | - **Phase 1B**: `+` (parallel) - Instruction-based with LLM-driven concurrency
768 | - **Phase 2**: `+` (parallel) - Server-side execution engine
769 | - **Phase 3**: `?` (conditional) - Server-side execution engine
770 |
771 | ### Architecture Decision
772 |
773 | **Proposal**: Dual-mode execution system
774 |
775 | ```typescript
776 | export interface ExecutionMode {
777 | mode: 'instruction' | 'server';
778 | features: {
779 | parallel: boolean;
780 | conditional: boolean;
781 | gateValidation: boolean;
782 | };
783 | }
784 |
785 | // Start with instruction mode
786 | const defaultMode: ExecutionMode = {
787 | mode: 'instruction',
788 | features: {
789 | parallel: false, // LLM-driven via instructions
790 | conditional: false,
791 | gateValidation: true
792 | }
793 | };
794 |
795 | // Evolve to server mode
796 | const futureMode: ExecutionMode = {
797 | mode: 'server',
798 | features: {
799 | parallel: true, // True Promise.all() execution
800 | conditional: true, // Server-side branching
801 | gateValidation: true
802 | }
803 | };
804 | ```
805 |
806 | ### Revised Implementation Timeline
807 |
808 | **Phase 1A: Foundation (Weeks 1-2)** - Instruction-Based Operators
809 | - Chain operator (`-->`) with instruction generation
810 | - Gate operator (`=`) with temporary gate creation
811 | - Framework operator (`@`) with framework switching
812 | - **Deliverable**: Basic symbolic operators working
813 |
814 | **Phase 1B: Parallel Instructions (Week 3)** - Hybrid Approach
815 | - Parallel operator (`+`) detection
816 | - Generate parallel execution instructions for LLM
817 | - Result aggregation templates
818 | - **Deliverable**: LLM-driven parallel execution
819 |
820 | **Phase 2: Server-Side Parallel (Weeks 4-6)** - Execution Engine v1
821 | - Build ParallelExecutor with Promise.all()
822 | - Dependency resolution system
823 | - Result aggregation engine
824 | - **Deliverable**: True server-side parallelism
825 |
826 | **Phase 3: Conditional Execution (Weeks 7-10)** - Execution Engine v2
827 | - Condition evaluator (rule-based + LLM)
828 | - Dynamic step selector
829 | - Branch execution engine
830 | - **Deliverable**: Full conditional workflow support
831 |
832 | ## Technical Debt & Risks
833 |
834 | ### Risk 1: Instruction vs Execution Paradigm Conflict
835 |
836 | **Risk**: Mixing instruction-based and execution-based approaches creates complexity
837 |
838 | **Mitigation**:
839 | - Clear separation of concerns (mode detection)
840 | - Feature flags for execution mode
841 | - Comprehensive testing for both modes
842 | - Migration guide for users
843 |
844 | ### Risk 2: LLM Reliability for Parallel Execution (Phase 1B)
845 |
846 | **Risk**: LLM may not reliably execute parallel steps concurrently
847 |
848 | **Mitigation**:
849 | - Clear instructions emphasizing parallelism
850 | - Examples of concurrent tool calls
851 | - Fallback to sequential if needed
852 | - Monitor success rates
853 |
854 | ### Risk 3: Performance Overhead of Server-Side Execution
855 |
856 | **Risk**: Server-side execution may be slower due to MCP protocol overhead
857 |
858 | **Mitigation**:
859 | - Performance benchmarking
860 | - Optimize MCP tool calls
861 | - Batch operations where possible
862 | - User choice between modes
863 |
864 | ### Risk 4: Complex Error Handling in Execution Engine
865 |
866 | **Risk**: Server-side execution requires sophisticated error handling
867 |
868 | **Mitigation**:
869 | - Comprehensive error types
870 | - Retry logic with backoff
871 | - Partial result preservation
872 | - Clear error messages
873 |
874 | ## Success Metrics
875 |
876 | ### Phase 1A Metrics
877 | - ✅ Parser detects `-->`, `=`, `@` operators (100% accuracy)
878 | - ✅ Instructions generated correctly (manual validation)
879 | - ✅ LLM executes chains successfully (>90% success rate)
880 |
881 | ### Phase 1B Metrics
882 | - ✅ Parallel operator detected (100% accuracy)
883 | - ⚠️ LLM executes steps concurrently (>70% success rate)
884 | - ⚠️ Results aggregated correctly (>80% accuracy)
885 |
886 | ### Phase 2 Metrics
887 | - ✅ True parallel execution (Promise.all() used)
888 | - ✅ Performance improvement (>30% faster than sequential)
889 | - ✅ Dependency resolution works (100% correct ordering)
890 |
891 | ### Phase 3 Metrics
892 | - ✅ Conditional branching works (100% correct paths)
893 | - ✅ LLM condition evaluation accurate (>85% agreement with rules)
894 | - ✅ Complex workflows supported (3+ branches)
895 |
896 | ## Next Steps
897 |
898 | ### Immediate (This Week)
899 | 1. ✅ Create this analysis document
900 | 2. ⏳ Update symbolic-command-language-implementation.md
901 | 3. ⏳ Create architecture decision record (ADR)
902 | 4. ⏳ Prototype parallel operator parser
903 |
904 | ### Short Term (Weeks 1-2)
905 | 1. Implement Phase 1A operators (instruction-based)
906 | 2. Test with real-world use cases
907 | 3. Gather user feedback
908 | 4. Refine instruction templates
909 |
910 | ### Medium Term (Weeks 3-6)
911 | 1. Build parallel executor (server-side)
912 | 2. Performance benchmarking
913 | 3. Migration guide for execution modes
914 | 4. User education materials
915 |
916 | ### Long Term (Months 2-3)
917 | 1. Full execution engine with conditionals
918 | 2. Advanced features (nested conditionals, complex dependencies)
919 | 3. Optimization and scaling
920 | 4. Production deployment
921 |
922 | ---
923 |
924 | **End of Analysis Document**
925 |
926 | This analysis will inform the implementation strategy for parallel and conditional execution operators in the symbolic command language system.
927 |
```
--------------------------------------------------------------------------------
/server/src/execution/parsers/argument-parser.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Argument Processing Pipeline
3 | *
4 | * Advanced argument processing system that handles validation, sanitization,
5 | * type coercion, and enrichment based on prompt definitions and execution context.
6 | *
7 | * Features:
8 | * - Type-aware argument coercion based on prompt definitions
9 | * - Smart default resolution (replaces hardcoded {{previous_message}})
10 | * - Multi-source context aggregation
11 | * - Argument validation cascading
12 | * - Context-aware placeholder resolution
13 | */
14 |
15 | import { Logger } from "../../logging/index.js";
16 | import type { PromptData, PromptArgument } from "../../prompts/types.js";
17 | import { safeJsonParse, validateJsonArguments } from "../../utils/index.js";
18 | import type { ValidationResult, ValidationError, ValidationWarning } from "../types.js";
19 |
20 | /**
21 | * Processing result with detailed metadata
22 | */
23 | export interface ArgumentParsingResult {
24 | processedArgs: Record<string, string | number | boolean | null>;
25 | resolvedPlaceholders: Record<string, string | number | boolean | null>;
26 | validationResults: ValidationResult[];
27 | metadata: {
28 | parsingStrategy: string;
29 | appliedDefaults: string[];
30 | typeCoercions: Array<{ arg: string; from: string; to: string }>;
31 | contextSources: Record<string, string>;
32 | warnings: string[];
33 | };
34 | }
35 |
36 |
37 | /**
38 | * Execution context for argument processing
39 | */
40 | export interface ExecutionContext {
41 | conversationHistory?: Array<{role: string; content: string; timestamp?: string}>;
42 | environmentVars?: Record<string, string>;
43 | promptDefaults?: Record<string, string | number | boolean | null>;
44 | userSession?: Record<string, string | number | boolean | null>;
45 | systemContext?: Record<string, string | number | boolean | null>;
46 | }
47 |
48 | /**
49 | * Processing strategy interface
50 | */
51 | interface ProcessingStrategy {
52 | name: string;
53 | canHandle: (rawArgs: string, promptData: PromptData) => boolean;
54 | process: (rawArgs: string, promptData: PromptData, context: ExecutionContext) => ArgumentParsingResult;
55 | }
56 |
57 | /**
58 | * Argument Processor Class
59 | */
60 | export class ArgumentParser {
61 | private logger: Logger;
62 | private strategies: ProcessingStrategy[];
63 |
64 | // Processing statistics
65 | private stats = {
66 | totalProcessed: 0,
67 | successfulProcessing: 0,
68 | validationFailures: 0,
69 | typeCoercions: 0,
70 | defaultsApplied: 0,
71 | contextResolutions: 0
72 | };
73 |
74 | constructor(logger: Logger) {
75 | this.logger = logger;
76 | this.strategies = this.initializeStrategies();
77 | this.logger.debug(`ArgumentParser initialized with ${this.strategies.length} processing strategies`);
78 | }
79 |
80 | /**
81 | * Process arguments through validation, sanitization, and enrichment pipeline
82 | */
83 | async parseArguments(
84 | rawArgs: string,
85 | promptData: PromptData,
86 | context: ExecutionContext = {}
87 | ): Promise<ArgumentParsingResult> {
88 | this.stats.totalProcessed++;
89 |
90 | this.logger.debug(`Processing arguments for prompt "${promptData.id}": "${rawArgs.substring(0, 100)}..."`);
91 |
92 | // Select appropriate processing strategy
93 | const strategy = this.selectStrategy(rawArgs, promptData);
94 |
95 | try {
96 | const result = strategy.process(rawArgs, promptData, context);
97 |
98 | // Apply validation and enrichment
99 | const enrichedResult = await this.enrichResult(result, promptData, context);
100 |
101 | this.stats.successfulProcessing++;
102 | this.updateProcessingStats(enrichedResult);
103 |
104 | this.logger.debug(`Arguments processed successfully using strategy: ${strategy.name}`);
105 | return enrichedResult;
106 |
107 | } catch (error) {
108 | this.stats.validationFailures++;
109 | this.logger.error(`Argument processing failed for prompt ${promptData.id}:`, error);
110 | throw error;
111 | }
112 | }
113 |
114 | /**
115 | * Initialize processing strategies
116 | */
117 | private initializeStrategies(): ProcessingStrategy[] {
118 | return [
119 | this.createJsonStrategy(),
120 | this.createKeyValueStrategy(),
121 | this.createSimpleTextStrategy(),
122 | this.createFallbackStrategy()
123 | ];
124 | }
125 |
126 | /**
127 | * Select best processing strategy for the given arguments
128 | */
129 | private selectStrategy(rawArgs: string, promptData: PromptData): ProcessingStrategy {
130 | for (const strategy of this.strategies) {
131 | if (strategy.canHandle(rawArgs, promptData)) {
132 | return strategy;
133 | }
134 | }
135 |
136 | // Should never reach here due to fallback strategy, but safety first
137 | return this.strategies[this.strategies.length - 1];
138 | }
139 |
140 | /**
141 | * JSON argument processing strategy
142 | */
143 | private createJsonStrategy(): ProcessingStrategy {
144 | return {
145 | name: 'json',
146 | canHandle: (rawArgs: string) => {
147 | const trimmed = rawArgs.trim();
148 | return (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
149 | (trimmed.startsWith('[') && trimmed.endsWith(']'));
150 | },
151 | process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
152 | const parseResult = safeJsonParse(rawArgs);
153 | if (!parseResult.success || !parseResult.data) {
154 | throw new Error(`Invalid JSON arguments: ${parseResult.error || 'Unknown parsing error'}`);
155 | }
156 |
157 | const jsonArgs = parseResult.data;
158 | const validation = validateJsonArguments(jsonArgs, promptData);
159 |
160 | const processedArgs = validation.sanitizedArgs || {};
161 | // Ensure processedArgs only contains allowed types for UnifiedExecutionContext
162 | const compatibleArgs: Record<string, string | number | boolean | null> = {};
163 | for (const [key, value] of Object.entries(processedArgs)) {
164 | if (Array.isArray(value)) {
165 | // Convert arrays to JSON strings for compatibility
166 | compatibleArgs[key] = JSON.stringify(value);
167 | } else {
168 | compatibleArgs[key] = value as string | number | boolean | null;
169 | }
170 | }
171 |
172 | const validationResults = this.createValidationResults(compatibleArgs, promptData, validation);
173 |
174 | return {
175 | processedArgs: compatibleArgs,
176 | resolvedPlaceholders: {},
177 | validationResults,
178 | metadata: {
179 | parsingStrategy: 'json',
180 | appliedDefaults: [],
181 | typeCoercions: [],
182 | contextSources: {},
183 | warnings: validation.errors || []
184 | }
185 | };
186 | }
187 | };
188 | }
189 |
190 | /**
191 | * Key-value pair processing strategy (arg1=value1 arg2=value2)
192 | */
193 | private createKeyValueStrategy(): ProcessingStrategy {
194 | return {
195 | name: 'keyvalue',
196 | canHandle: (rawArgs: string) => {
197 | return /\w+\s*=\s*/.test(rawArgs);
198 | },
199 | process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
200 | const processedArgs: Record<string, string | number | boolean | null> = {};
201 | const typeCoercions: Array<{ arg: string; from: string; to: string }> = [];
202 |
203 | // Parse key=value pairs with proper quote handling
204 | const pairs = rawArgs.match(/(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s]+(?:\s+(?!\w+\s*=)[^\s]*)*?))/g) || [];
205 |
206 | for (const pair of pairs) {
207 | const match = pair.match(/(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|(.*))/);
208 | if (match) {
209 | const [, key, doubleQuoted, singleQuoted, unquoted] = match;
210 | // Use the appropriate captured group - quoted strings take precedence
211 | const value = doubleQuoted !== undefined ? doubleQuoted :
212 | singleQuoted !== undefined ? singleQuoted :
213 | unquoted || '';
214 | const trimmedValue = value.trim();
215 |
216 | // Find argument definition for type coercion
217 | const argDef = promptData.arguments.find(arg => arg.name === key);
218 | if (argDef) {
219 | const coercedValue = this.coerceArgumentType(trimmedValue, argDef);
220 | if (coercedValue.wasCoerced) {
221 | typeCoercions.push({
222 | arg: key,
223 | from: typeof trimmedValue,
224 | to: typeof coercedValue.value
225 | });
226 | }
227 | processedArgs[key] = coercedValue.value;
228 | } else {
229 | processedArgs[key] = trimmedValue;
230 | }
231 | }
232 | }
233 |
234 | const validationResults = this.createValidationResults(processedArgs, promptData);
235 |
236 | return {
237 | processedArgs,
238 | resolvedPlaceholders: {},
239 | validationResults,
240 | metadata: {
241 | parsingStrategy: 'keyvalue',
242 | appliedDefaults: [],
243 | typeCoercions,
244 | contextSources: {},
245 | warnings: []
246 | }
247 | };
248 | }
249 | };
250 | }
251 |
252 | /**
253 | * Simple text processing strategy
254 | */
255 | private createSimpleTextStrategy(): ProcessingStrategy {
256 | return {
257 | name: 'simple',
258 | canHandle: (rawArgs: string, promptData: PromptData) => {
259 | return rawArgs.trim().length > 0 && promptData.arguments.length > 0;
260 | },
261 | process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
262 | const processedArgs: Record<string, string | number | boolean | null> = {};
263 | const appliedDefaults: string[] = [];
264 | const contextSources: Record<string, string> = {};
265 |
266 | if (promptData.arguments.length === 1) {
267 | // Single argument - assign all text to it
268 | const arg = promptData.arguments[0];
269 | processedArgs[arg.name] = rawArgs.trim();
270 | contextSources[arg.name] = 'user_provided';
271 | } else {
272 | // Multiple arguments - use intelligent defaults
273 | this.applyIntelligentDefaults(
274 | rawArgs,
275 | promptData,
276 | processedArgs,
277 | appliedDefaults,
278 | contextSources,
279 | context
280 | );
281 | }
282 |
283 | const validationResults = this.createValidationResults(processedArgs, promptData);
284 |
285 | return {
286 | processedArgs,
287 | resolvedPlaceholders: {},
288 | validationResults,
289 | metadata: {
290 | parsingStrategy: 'simple',
291 | appliedDefaults,
292 | typeCoercions: [],
293 | contextSources,
294 | warnings: []
295 | }
296 | };
297 | }
298 | };
299 | }
300 |
301 | /**
302 | * Fallback processing strategy
303 | */
304 | private createFallbackStrategy(): ProcessingStrategy {
305 | return {
306 | name: 'fallback',
307 | canHandle: () => true, // Always handles as last resort
308 | process: (rawArgs: string, promptData: PromptData, context: ExecutionContext): ArgumentParsingResult => {
309 | const processedArgs: Record<string, string | number | boolean | null> = {};
310 | const appliedDefaults: string[] = [];
311 | const contextSources: Record<string, string> = {};
312 | const warnings: string[] = [];
313 |
314 | // Apply defaults for all arguments
315 | for (const arg of promptData.arguments) {
316 | if (rawArgs.trim()) {
317 | // Use provided text for first argument, defaults for rest
318 | if (Object.keys(processedArgs).length === 0) {
319 | processedArgs[arg.name] = rawArgs.trim();
320 | contextSources[arg.name] = 'user_provided';
321 | } else {
322 | const defaultValue = this.resolveContextualDefault(arg, context);
323 | processedArgs[arg.name] = defaultValue.value;
324 | contextSources[arg.name] = defaultValue.source;
325 | appliedDefaults.push(arg.name);
326 | }
327 | } else {
328 | const defaultValue = this.resolveContextualDefault(arg, context);
329 | processedArgs[arg.name] = defaultValue.value;
330 | contextSources[arg.name] = defaultValue.source;
331 | appliedDefaults.push(arg.name);
332 | }
333 | }
334 |
335 | warnings.push('Used fallback argument processing - consider using structured format');
336 |
337 | const validationResults = this.createValidationResults(processedArgs, promptData);
338 |
339 | return {
340 | processedArgs,
341 | resolvedPlaceholders: {},
342 | validationResults,
343 | metadata: {
344 | parsingStrategy: 'fallback',
345 | appliedDefaults,
346 | typeCoercions: [],
347 | contextSources,
348 | warnings
349 | }
350 | };
351 | }
352 | };
353 | }
354 |
355 | /**
356 | * Apply intelligent defaults for arguments
357 | * ENHANCED: Smarter content mapping and auto-fill for 100% success rate
358 | */
359 | private applyIntelligentDefaults(
360 | userContent: string,
361 | promptData: PromptData,
362 | processedArgs: Record<string, string | number | boolean | null>,
363 | appliedDefaults: string[],
364 | contextSources: Record<string, string>,
365 | context: ExecutionContext
366 | ): void {
367 | // Enhanced priority order for content assignment with better semantic matching
368 | const contentPriority = [
369 | 'content', 'text', 'input', 'data', 'message', 'query', 'prompt',
370 | 'description', 'topic', 'subject', 'analysis', 'code', 'file'
371 | ];
372 |
373 | // Find the most appropriate argument for user content using multiple strategies
374 | let targetArg = null;
375 |
376 | // Strategy 1: Exact semantic match
377 | for (const priority of contentPriority) {
378 | targetArg = promptData.arguments.find(arg =>
379 | arg.name.toLowerCase().includes(priority)
380 | );
381 | if (targetArg) {
382 | this.logger.debug(`Semantic match found: ${targetArg.name} (matched: ${priority})`);
383 | break;
384 | }
385 | }
386 |
387 | // Strategy 2: Description-based matching
388 | if (!targetArg && userContent) {
389 | targetArg = promptData.arguments.find(arg =>
390 | arg.description && (
391 | arg.description.toLowerCase().includes('content') ||
392 | arg.description.toLowerCase().includes('text') ||
393 | arg.description.toLowerCase().includes('input') ||
394 | arg.description.toLowerCase().includes('analyze')
395 | )
396 | );
397 | if (targetArg) {
398 | this.logger.debug(`Description match found: ${targetArg.name}`);
399 | }
400 | }
401 |
402 | // Strategy 3: First required argument
403 | if (!targetArg) {
404 | targetArg = promptData.arguments.find(arg => arg.required);
405 | if (targetArg) {
406 | this.logger.debug(`First required argument selected: ${targetArg.name}`);
407 | }
408 | }
409 |
410 | // Strategy 4: First argument (fallback)
411 | if (!targetArg && promptData.arguments.length > 0) {
412 | targetArg = promptData.arguments[0];
413 | this.logger.debug(`First argument fallback: ${targetArg.name}`);
414 | }
415 |
416 | // Assign user content to target argument with intelligent processing
417 | if (targetArg && userContent) {
418 | processedArgs[targetArg.name] = this.processContentForArgument(userContent, targetArg);
419 | contextSources[targetArg.name] = 'user_provided_smart_mapped';
420 | this.logger.debug(`Mapped user content to ${targetArg.name}: "${userContent.substring(0, 50)}..."`);
421 | }
422 |
423 | // Fill remaining arguments with enhanced contextual defaults
424 | for (const arg of promptData.arguments) {
425 | if (!processedArgs[arg.name]) {
426 | const defaultValue = this.resolveEnhancedContextualDefault(arg, context, userContent, promptData);
427 | processedArgs[arg.name] = defaultValue.value;
428 | contextSources[arg.name] = defaultValue.source;
429 | appliedDefaults.push(arg.name);
430 | }
431 | }
432 |
433 | // Log the mapping for debugging
434 | this.logger.debug(`Intelligent defaults applied:`, {
435 | promptId: promptData.id,
436 | userContentLength: userContent.length,
437 | targetArgument: targetArg?.name,
438 | totalArguments: promptData.arguments.length,
439 | appliedDefaults
440 | });
441 | }
442 |
443 | /**
444 | * Process content specifically for an argument type
445 | */
446 | private processContentForArgument(content: string, arg: PromptArgument): string {
447 | // Basic content processing - can be enhanced further
448 | const trimmed = content.trim();
449 |
450 | // If argument name suggests it wants a specific format, attempt to extract it
451 | if (arg.name.toLowerCase().includes('json') && !trimmed.startsWith('{')) {
452 | // For JSON arguments, wrap simple content appropriately
453 | return `{"content": "${trimmed.replace(/"/g, '\\"')}"}`;
454 | }
455 |
456 | if (arg.name.toLowerCase().includes('url') && !trimmed.match(/^https?:\/\//)) {
457 | // Basic URL validation/enhancement could go here
458 | this.logger.debug(`Argument ${arg.name} expects URL but got: ${trimmed.substring(0, 50)}`);
459 | }
460 |
461 | return trimmed;
462 | }
463 |
464 | /**
465 | * Enhanced contextual default resolver with more intelligence
466 | */
467 | private resolveEnhancedContextualDefault(
468 | arg: PromptArgument,
469 | context: ExecutionContext,
470 | userContent: string,
471 | promptData: PromptData
472 | ): { value: any; source: string } {
473 | // Enhanced strategies with content-aware defaults
474 | const strategies = [
475 | () => this.getFromPromptDefaults(arg, context.promptDefaults),
476 | () => this.getFromEnvironment(arg, context.environmentVars),
477 | () => this.getFromConversationHistory(arg, context.conversationHistory),
478 | () => this.getFromSystemContext(arg, context.systemContext),
479 | () => this.generateContentAwareDefault(arg, userContent, promptData),
480 | () => this.generateSmartDefault(arg)
481 | ];
482 |
483 | for (const strategy of strategies) {
484 | const result = strategy();
485 | if (result.value !== null && result.value !== undefined && result.value !== '') {
486 | return result;
487 | }
488 | }
489 |
490 | // Enhanced fallback with more semantic defaults
491 | return this.generateSemanticFallback(arg);
492 | }
493 |
494 | /**
495 | * Generate content-aware defaults based on user input and prompt context
496 | */
497 | private generateContentAwareDefault(
498 | arg: PromptArgument,
499 | userContent: string,
500 | promptData: PromptData
501 | ): { value: any; source: string } {
502 | const argName = arg.name.toLowerCase();
503 | const userLower = userContent.toLowerCase();
504 |
505 | // Generate defaults based on argument semantics and user content
506 | if (argName.includes('level') || argName.includes('depth')) {
507 | if (userLower.includes('simple') || userLower.includes('basic')) {
508 | return { value: 'beginner', source: 'content_inference' };
509 | } else if (userLower.includes('complex') || userLower.includes('advanced')) {
510 | return { value: 'expert', source: 'content_inference' };
511 | }
512 | return { value: 'intermediate', source: 'content_inference' };
513 | }
514 |
515 | if (argName.includes('format') || argName.includes('type')) {
516 | if (userLower.includes('json') || userContent.includes('{')) {
517 | return { value: 'json', source: 'content_inference' };
518 | } else if (userLower.includes('list') || userLower.includes('bullet')) {
519 | return { value: 'list', source: 'content_inference' };
520 | }
521 | return { value: 'text', source: 'content_inference' };
522 | }
523 |
524 | if (argName.includes('style') || argName.includes('tone')) {
525 | if (userLower.includes('formal') || userLower.includes('professional')) {
526 | return { value: 'formal', source: 'content_inference' };
527 | } else if (userLower.includes('casual') || userLower.includes('friendly')) {
528 | return { value: 'casual', source: 'content_inference' };
529 | }
530 | return { value: 'neutral', source: 'content_inference' };
531 | }
532 |
533 | if (argName.includes('length') || argName.includes('size')) {
534 | const wordCount = userContent.split(/\s+/).length;
535 | if (wordCount > 100) {
536 | return { value: 'detailed', source: 'content_inference' };
537 | } else if (wordCount < 20) {
538 | return { value: 'brief', source: 'content_inference' };
539 | }
540 | return { value: 'moderate', source: 'content_inference' };
541 | }
542 |
543 | return { value: null, source: 'no_content_match' };
544 | }
545 |
546 | /**
547 | * Generate semantic fallback defaults
548 | */
549 | private generateSemanticFallback(arg: PromptArgument): { value: any; source: string } {
550 | const argName = arg.name.toLowerCase();
551 |
552 | // Common semantic defaults
553 | const semanticDefaults: Record<string, string> = {
554 | 'level': 'intermediate',
555 | 'depth': 'moderate',
556 | 'format': 'text',
557 | 'style': 'neutral',
558 | 'tone': 'professional',
559 | 'length': 'moderate',
560 | 'type': 'analysis',
561 | 'mode': 'standard',
562 | 'approach': 'systematic',
563 | 'focus': 'comprehensive'
564 | };
565 |
566 | for (const [keyword, defaultValue] of Object.entries(semanticDefaults)) {
567 | if (argName.includes(keyword)) {
568 | return { value: defaultValue, source: 'semantic_fallback' };
569 | }
570 | }
571 |
572 | // Description-based fallback
573 | if (arg.description) {
574 | const desc = arg.description.toLowerCase();
575 | if (desc.includes('required') || desc.includes('must')) {
576 | return { value: '[Please specify]', source: 'required_placeholder' };
577 | }
578 | }
579 |
580 | // Final fallback
581 | return { value: '', source: 'empty_fallback' };
582 | }
583 |
584 | /**
585 | * Resolve contextual default for an argument (legacy method)
586 | */
587 | private resolveContextualDefault(
588 | arg: PromptArgument,
589 | context: ExecutionContext
590 | ): { value: any; source: string } {
591 | // Priority order for context resolution
592 | const strategies = [
593 | () => this.getFromPromptDefaults(arg, context.promptDefaults),
594 | () => this.getFromEnvironment(arg, context.environmentVars),
595 | () => this.getFromConversationHistory(arg, context.conversationHistory),
596 | () => this.getFromSystemContext(arg, context.systemContext),
597 | () => this.generateSmartDefault(arg)
598 | ];
599 |
600 | for (const strategy of strategies) {
601 | const result = strategy();
602 | if (result.value !== null && result.value !== undefined) {
603 | return result;
604 | }
605 | }
606 |
607 | // Final fallback
608 | return { value: '', source: 'empty_fallback' };
609 | }
610 |
611 | /**
612 | * Get default from prompt-specific defaults
613 | */
614 | private getFromPromptDefaults(
615 | arg: PromptArgument,
616 | promptDefaults?: Record<string, string | number | boolean | null>
617 | ): { value: any; source: string } {
618 | if (promptDefaults && promptDefaults[arg.name] !== undefined) {
619 | return { value: promptDefaults[arg.name], source: 'prompt_defaults' };
620 | }
621 | return { value: null, source: 'none' };
622 | }
623 |
624 | /**
625 | * Get default from environment variables
626 | */
627 | private getFromEnvironment(
628 | arg: PromptArgument,
629 | environmentVars?: Record<string, string>
630 | ): { value: any; source: string } {
631 | if (environmentVars) {
632 | const envKey = `PROMPT_${arg.name.toUpperCase()}`;
633 | if (environmentVars[envKey]) {
634 | return { value: environmentVars[envKey], source: 'environment' };
635 | }
636 | }
637 | return { value: null, source: 'none' };
638 | }
639 |
640 | /**
641 | * Get default from conversation history
642 | */
643 | private getFromConversationHistory(
644 | arg: PromptArgument,
645 | conversationHistory?: any[]
646 | ): { value: any; source: string } {
647 | if (conversationHistory && conversationHistory.length > 0) {
648 | const lastMessage = conversationHistory[conversationHistory.length - 1];
649 | if (lastMessage && lastMessage.content) {
650 | // For content-like arguments, use last message
651 | const contentArgs = ['content', 'text', 'input', 'message', 'query'];
652 | if (contentArgs.some(keyword => arg.name.toLowerCase().includes(keyword))) {
653 | return { value: lastMessage.content, source: 'conversation_history' };
654 | }
655 | }
656 | }
657 | return { value: null, source: 'none' };
658 | }
659 |
660 | /**
661 | * Get default from system context
662 | */
663 | private getFromSystemContext(
664 | arg: PromptArgument,
665 | systemContext?: Record<string, string | number | boolean | null>
666 | ): { value: any; source: string } {
667 | if (systemContext && systemContext[arg.name] !== undefined) {
668 | return { value: systemContext[arg.name], source: 'system_context' };
669 | }
670 | return { value: null, source: 'none' };
671 | }
672 |
673 | /**
674 | * Generate smart default based on argument characteristics
675 | */
676 | private generateSmartDefault(arg: PromptArgument): { value: any; source: string } {
677 | // Generate contextual placeholders based on argument name and description
678 | const name = arg.name.toLowerCase();
679 | const description = (arg.description || '').toLowerCase();
680 |
681 | if (name.includes('content') || name.includes('text') || name.includes('input')) {
682 | return { value: '[Content will be provided]', source: 'smart_placeholder' };
683 | }
684 |
685 | if (name.includes('file') || name.includes('path')) {
686 | return { value: '[File path will be specified]', source: 'smart_placeholder' };
687 | }
688 |
689 | if (name.includes('count') || name.includes('number')) {
690 | return { value: '1', source: 'smart_default' };
691 | }
692 |
693 | if (name.includes('format') || name.includes('style')) {
694 | return { value: 'default', source: 'smart_default' };
695 | }
696 |
697 | // Generic placeholder
698 | return {
699 | value: `[${arg.name} to be provided]`,
700 | source: 'generic_placeholder'
701 | };
702 | }
703 |
704 | /**
705 | * Type coercion for arguments based on prompt definitions
706 | */
707 | private coerceArgumentType(
708 | value: string,
709 | argDef: PromptArgument
710 | ): { value: any; wasCoerced: boolean } {
711 | const originalType = typeof value;
712 |
713 | // If argument has type hints in description, use them
714 | const description = (argDef.description || '').toLowerCase();
715 |
716 | if (description.includes('number') || description.includes('integer')) {
717 | const numValue = Number(value);
718 | if (!isNaN(numValue)) {
719 | return { value: numValue, wasCoerced: originalType !== 'number' };
720 | }
721 | }
722 |
723 | if (description.includes('boolean') || value.toLowerCase() === 'true' || value.toLowerCase() === 'false') {
724 | return {
725 | value: value.toLowerCase() === 'true',
726 | wasCoerced: originalType !== 'boolean'
727 | };
728 | }
729 |
730 | if (description.includes('array') || description.includes('list') ||
731 | argDef.name.toLowerCase().includes('list') ||
732 | description.includes('A list of') || description.includes('list of')) {
733 | try {
734 | const parsed = JSON.parse(value);
735 | if (Array.isArray(parsed)) {
736 | return { value: parsed, wasCoerced: true };
737 | }
738 | } catch {
739 | // If not valid JSON, split by comma and clean up
740 | const arrayValue = value.split(',').map(item => item.trim()).filter(item => item.length > 0);
741 | return { value: arrayValue, wasCoerced: true };
742 | }
743 | }
744 |
745 | // Handle JSON objects
746 | if (description.includes('json') || description.includes('object') ||
747 | description.includes('objects') || value.startsWith('{') || value.startsWith('[')) {
748 | try {
749 | const parsed = JSON.parse(value);
750 | return { value: parsed, wasCoerced: true };
751 | } catch {
752 | // Invalid JSON, keep as string
753 | return { value, wasCoerced: false };
754 | }
755 | }
756 |
757 | // No coercion needed or possible
758 | return { value, wasCoerced: false };
759 | }
760 |
761 | /**
762 | * Create validation results for processed arguments
763 | */
764 | private createValidationResults(
765 | processedArgs: Record<string, string | number | boolean | null>,
766 | promptData: PromptData,
767 | existingValidation?: any
768 | ): ValidationResult[] {
769 | const results: ValidationResult[] = [];
770 |
771 | for (const arg of promptData.arguments) {
772 | const value = processedArgs[arg.name];
773 | const result: ValidationResult = {
774 | argumentName: arg.name,
775 | valid: true,
776 | originalValue: value,
777 | processedValue: value,
778 | appliedRules: [],
779 | warnings: [],
780 | errors: []
781 | };
782 |
783 | // Check if argument is required but missing
784 | if (arg.required && (value === undefined || value === null || value === '')) {
785 | result.valid = false;
786 | result.errors = result.errors || [];
787 | result.errors.push({
788 | field: arg.name,
789 | message: `Required argument '${arg.name}' is missing`,
790 | code: 'REQUIRED_ARGUMENT_MISSING',
791 | suggestion: `Please provide a value for argument '${arg.name}'`,
792 | example: `"${arg.name}": "example_value"`
793 | });
794 | }
795 |
796 | // Add existing validation errors if any
797 | if (existingValidation && existingValidation.errors) {
798 | result.warnings = result.warnings || [];
799 | result.warnings.push(...existingValidation.errors);
800 | }
801 |
802 | results.push(result);
803 | }
804 |
805 | return results;
806 | }
807 |
808 | /**
809 | * Enrich processing result with additional validation and context
810 | */
811 | private async enrichResult(
812 | result: ArgumentParsingResult,
813 | promptData: PromptData,
814 | context: ExecutionContext
815 | ): Promise<ArgumentParsingResult> {
816 | // Add any additional enrichment logic here
817 | // For now, just return the result as-is
818 | return result;
819 | }
820 |
821 | /**
822 | * Update processing statistics
823 | */
824 | private updateProcessingStats(result: ArgumentParsingResult): void {
825 | this.stats.defaultsApplied += result.metadata.appliedDefaults.length;
826 | this.stats.typeCoercions += result.metadata.typeCoercions.length;
827 | this.stats.contextResolutions += Object.keys(result.metadata.contextSources).length;
828 | }
829 |
830 | /**
831 | * Get processing statistics
832 | */
833 | getStats(): typeof this.stats {
834 | return { ...this.stats };
835 | }
836 |
837 | /**
838 | * Reset statistics
839 | */
840 | resetStats(): void {
841 | this.stats = {
842 | totalProcessed: 0,
843 | successfulProcessing: 0,
844 | validationFailures: 0,
845 | typeCoercions: 0,
846 | defaultsApplied: 0,
847 | contextResolutions: 0
848 | };
849 | }
850 | }
851 |
852 | /**
853 | * Factory function to create argument processor
854 | */
855 | export function createArgumentParser(logger: Logger): ArgumentParser {
856 | return new ArgumentParser(logger);
857 | }
```
--------------------------------------------------------------------------------
/server/src/frameworks/integration/framework-semantic-integration.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Framework-Semantic Integration - Phase 2 Implementation
3 | * Intelligent framework switching and consensus mechanisms
4 | *
5 | * Key Integration Points:
6 | * - Semantic Analysis provides WHAT the prompt needs (complexity, structure, requirements)
7 | * - Framework Manager provides HOW to approach it (methodology, system prompts)
8 | * - Integration layer coordinates between systems WITHOUT interference
9 | */
10 |
11 | import { Logger } from "../../logging/index.js";
12 | import { ConvertedPrompt } from "../../types/index.js";
13 | import { FrameworkManager } from "../framework-manager.js";
14 | import {
15 | FrameworkDefinition,
16 | FrameworkExecutionContext,
17 | FrameworkSelectionCriteria,
18 | FrameworkSwitchingConfig,
19 | FrameworkUsageInsights,
20 | FrameworkSwitchRecommendation,
21 | IntegratedAnalysisResult
22 | } from "../types/index.js";
23 | import {
24 | ContentAnalyzer,
25 | ContentAnalysisResult
26 | } from "../../semantic/configurable-semantic-analyzer.js";
27 | import { FrameworkStateManager } from "../framework-state-manager.js";
28 | import { PromptGuidanceService } from "../prompt-guidance/service.js";
29 |
30 | /**
31 | * Integrated analysis result (imported from types/integration-types.js)
32 | */
33 |
34 | /**
35 | * Framework switching configuration (imported from types)
36 | */
37 |
38 | /**
39 | * Framework-Semantic Integration Engine
40 | * Coordinates framework selection based on structural analysis and user preference
41 | */
42 | export class FrameworkSemanticIntegration {
43 | private frameworkManager: FrameworkManager;
44 | private frameworkStateManager: FrameworkStateManager;
45 | private semanticAnalyzer: ContentAnalyzer;
46 | private logger: Logger;
47 | private config: FrameworkSwitchingConfig;
48 | // Phase 4: Prompt guidance coordination
49 | private promptGuidanceService?: PromptGuidanceService;
50 |
51 | // Framework switching state management
52 | private lastFrameworkSwitch = new Map<string, number>();
53 | private frameworkUsageHistory = new Map<string, FrameworkUsageMetrics>();
54 |
55 | constructor(
56 | frameworkManager: FrameworkManager,
57 | frameworkStateManager: FrameworkStateManager,
58 | semanticAnalyzer: ContentAnalyzer,
59 | logger: Logger,
60 | config: Partial<FrameworkSwitchingConfig> = {}
61 | ) {
62 | this.frameworkManager = frameworkManager;
63 | this.frameworkStateManager = frameworkStateManager;
64 | this.semanticAnalyzer = semanticAnalyzer;
65 | this.logger = logger;
66 |
67 | this.config = {
68 | enableAutomaticSwitching: config.enableAutomaticSwitching ?? true,
69 | switchingThreshold: config.switchingThreshold ?? 0.8,
70 | preventThrashing: config.preventThrashing ?? true,
71 | switchingCooldownMs: config.switchingCooldownMs ?? 30000, // 30 second cooldown
72 | blacklistedFrameworks: config.blacklistedFrameworks ?? [],
73 | preferredFrameworks: config.preferredFrameworks ?? []
74 | };
75 | }
76 |
77 | /**
78 | * Main integration method - combines semantic analysis with framework selection
79 | * Phase 4: Enhanced with prompt guidance coordination
80 | */
81 | async analyzeWithFrameworkIntegration(
82 | prompt: ConvertedPrompt,
83 | userFrameworkPreference?: string,
84 | includePromptGuidance?: boolean
85 | ): Promise<IntegratedAnalysisResult> {
86 | const startTime = performance.now();
87 |
88 | // NEW: Check if framework system is enabled before proceeding
89 | if (!this.frameworkStateManager.isFrameworkSystemEnabled()) {
90 | this.logger.debug(`Framework system disabled - returning semantic analysis only for prompt: ${prompt.id}`);
91 | return this.createNonFrameworkIntegratedResult(prompt, startTime);
92 | }
93 |
94 | try {
95 | // Step 1: Perform semantic analysis (WHAT does the prompt need?)
96 | this.logger.debug(`Starting semantic analysis for prompt: ${prompt.id}`);
97 | const semanticAnalysis = await this.semanticAnalyzer.analyzePrompt(prompt);
98 |
99 | // Step 2: Check analysis capabilities and adapt accordingly
100 | const analysisCapabilities = semanticAnalysis.capabilities;
101 | this.logger.debug(`Analysis capabilities: semantic=${analysisCapabilities.hasSemanticUnderstanding}, framework=${analysisCapabilities.canRecommendFramework}`);
102 |
103 | // Step 3: Enhance framework criteria with user preference and analysis mode
104 | const executionType = semanticAnalysis.executionType;
105 | const enhancedCriteria = this.enhanceFrameworkCriteria(
106 | {
107 | executionType: executionType as "template" | "chain",
108 | complexity: semanticAnalysis.complexity
109 | },
110 | userFrameworkPreference,
111 | semanticAnalysis
112 | );
113 |
114 | // Step 4: Framework selection adapted to analysis capabilities
115 | this.logger.debug(`Selecting framework based on semantic criteria (mode: ${semanticAnalysis.analysisMetadata.mode})`);
116 | const frameworkContext = this.selectOptimalFramework(
117 | prompt,
118 | enhancedCriteria,
119 | semanticAnalysis
120 | );
121 |
122 | // Step 5: Validate framework-semantic alignment
123 | const alignment = this.validateFrameworkAlignment(semanticAnalysis, frameworkContext);
124 |
125 | // Step 6: Generate alternative frameworks (adapted for analysis mode)
126 | const alternatives = this.generateAlternativeFrameworks(enhancedCriteria, frameworkContext, semanticAnalysis);
127 |
128 | // Step 6: Build integrated result with optional prompt guidance
129 | const result: IntegratedAnalysisResult = {
130 | semanticAnalysis,
131 | frameworkContext,
132 | integration: {
133 | frameworkSelectionReason: frameworkContext.metadata.selectionReason,
134 | semanticFrameworkAlignment: alignment.overallAlignment,
135 | alternativeFrameworks: alternatives,
136 | consensusMetrics: alignment.detailedMetrics
137 | },
138 | recommendations: this.generateIntegratedRecommendations(
139 | semanticAnalysis,
140 | frameworkContext,
141 | alignment
142 | )
143 | };
144 |
145 | // Phase 4: Apply prompt guidance if requested and available
146 | if (includePromptGuidance && this.promptGuidanceService?.isInitialized()) {
147 | try {
148 | const guidanceResult = await this.promptGuidanceService.applyGuidance(prompt, {
149 | includeSystemPromptInjection: true,
150 | includeTemplateEnhancement: true,
151 | frameworkOverride: frameworkContext.selectedFramework.methodology,
152 | semanticAnalysis: semanticAnalysis
153 | });
154 |
155 | // Enhance the result with prompt guidance information
156 | result.promptGuidance = {
157 | guidanceApplied: guidanceResult.guidanceApplied,
158 | enhancedPrompt: guidanceResult.enhancedPrompt,
159 | systemPromptInjection: guidanceResult.systemPromptInjection,
160 | templateEnhancement: guidanceResult.templateEnhancement,
161 | processingTimeMs: guidanceResult.processingTimeMs,
162 | confidenceScore: guidanceResult.metadata.confidenceScore
163 | };
164 |
165 | this.logger.debug(`Prompt guidance applied with confidence: ${guidanceResult.metadata.confidenceScore}`);
166 |
167 | } catch (error) {
168 | this.logger.warn("Failed to apply prompt guidance:", error);
169 | }
170 | }
171 |
172 | // Update performance tracking
173 | this.updateFrameworkUsage(
174 | frameworkContext.selectedFramework.id,
175 | performance.now() - startTime,
176 | alignment.overallAlignment
177 | );
178 |
179 | this.logger.info(
180 | `Framework integration completed: ${frameworkContext.selectedFramework.name} ` +
181 | `(alignment: ${(alignment.overallAlignment * 100).toFixed(1)}%)`
182 | );
183 |
184 | return result;
185 |
186 | } catch (error) {
187 | this.logger.error("Framework-semantic integration failed:", error);
188 | return this.createFallbackIntegratedResult(prompt, startTime);
189 | }
190 | }
191 |
192 | /**
193 | * Get framework performance insights for optimization
194 | */
195 | getFrameworkUsageInsights(): FrameworkUsageInsights {
196 | const frameworks = this.frameworkManager.listFrameworks(true);
197 | const insights: FrameworkUsageInsights = {
198 | totalAnalyses: 0,
199 | frameworkUsage: {},
200 | recommendations: []
201 | };
202 |
203 | frameworks.forEach(framework => {
204 | const metrics = this.frameworkUsageHistory.get(framework.id);
205 | if (metrics) {
206 | insights.frameworkUsage[framework.id] = {
207 | framework: framework,
208 | ...metrics
209 | };
210 | insights.totalAnalyses += metrics.usageCount;
211 | }
212 | });
213 |
214 | // Generate optimization recommendations
215 | insights.recommendations = this.generateUsageRecommendations(insights);
216 |
217 | return insights;
218 | }
219 |
220 | /**
221 | * Intelligent framework switching based on performance and alignment
222 | */
223 | async evaluateFrameworkSwitch(
224 | prompt: ConvertedPrompt,
225 | currentResult: IntegratedAnalysisResult
226 | ): Promise<FrameworkSwitchRecommendation | null> {
227 | if (!this.config.enableAutomaticSwitching) {
228 | return null;
229 | }
230 |
231 | // Check if framework context is available (framework system enabled)
232 | if (!currentResult.frameworkContext) {
233 | return null; // Cannot switch if framework system is disabled
234 | }
235 |
236 | const currentFramework = currentResult.frameworkContext.selectedFramework;
237 | const alignment = currentResult.integration.semanticFrameworkAlignment;
238 |
239 | // Check if switching is warranted
240 | if (alignment >= this.config.switchingThreshold) {
241 | return null; // Current framework is performing well
242 | }
243 |
244 | // Check cooldown period to prevent thrashing
245 | if (this.config.preventThrashing) {
246 | const lastSwitch = this.lastFrameworkSwitch.get(prompt.id);
247 | if (lastSwitch && Date.now() - lastSwitch < this.config.switchingCooldownMs) {
248 | return null; // Still in cooldown period
249 | }
250 | }
251 |
252 | // Evaluate alternatives
253 | const alternatives = currentResult.integration.alternativeFrameworks;
254 | const bestAlternative = alternatives.find(alt =>
255 | !this.config.blacklistedFrameworks.includes(alt.id) &&
256 | alt.id !== currentFramework.id
257 | );
258 |
259 | if (!bestAlternative) {
260 | return null; // No viable alternatives
261 | }
262 |
263 | return {
264 | currentFramework: currentFramework,
265 | recommendedFramework: bestAlternative,
266 | reason: `Low alignment (${(alignment * 100).toFixed(1)}%) suggests ${bestAlternative.name} would be more suitable`,
267 | expectedImprovement: this.estimateImprovementPotential(
268 | currentFramework,
269 | bestAlternative,
270 | currentResult.semanticAnalysis
271 | )
272 | };
273 | }
274 |
275 | // Private implementation methods
276 |
277 | /**
278 | * Enhance framework criteria with user preferences, context, and analysis capabilities
279 | */
280 | private enhanceFrameworkCriteria(
281 | baseCriteria: FrameworkSelectionCriteria,
282 | userPreference?: string,
283 | semanticAnalysis?: ContentAnalysisResult
284 | ): FrameworkSelectionCriteria {
285 | const enhanced = { ...baseCriteria };
286 |
287 | // Apply user preference if provided
288 | if (userPreference) {
289 | enhanced.userPreference = userPreference as any;
290 | }
291 |
292 | // Handle analysis mode specific logic
293 | if (semanticAnalysis) {
294 | // In structural mode, user choice is more important
295 | if (semanticAnalysis.analysisMetadata.mode === 'structural') {
296 | if (!userPreference && semanticAnalysis.frameworkRecommendation.requiresUserChoice) {
297 | // Log that user choice is needed
298 | this.logger.info("Structural analysis mode - framework selection requires user choice or default");
299 | }
300 | }
301 |
302 | // In semantic mode, use intelligent recommendations
303 | if (semanticAnalysis.analysisMetadata.mode === 'semantic' &&
304 | semanticAnalysis.frameworkRecommendation.shouldUseFramework) {
305 | // We can trust the semantic recommendation more
306 | this.logger.debug("Semantic analysis provides framework recommendation");
307 | }
308 | }
309 |
310 | // Apply global preferences
311 | if (this.config.preferredFrameworks.length > 0 && !enhanced.userPreference) {
312 | // Don't override user preference, but suggest from preferred list
313 | }
314 |
315 | return enhanced;
316 | }
317 |
318 | /**
319 | * Select framework using rule-based selection logic and user preference
320 | */
321 | private selectOptimalFramework(
322 | prompt: ConvertedPrompt,
323 | criteria: FrameworkSelectionCriteria,
324 | semanticAnalysis: ContentAnalysisResult
325 | ): FrameworkExecutionContext {
326 | // Use framework manager's selection logic
327 | const frameworkContext = this.frameworkManager.generateExecutionContext(prompt, criteria);
328 |
329 | // Log selection reasoning
330 | this.logger.debug(
331 | `Framework selection: ${frameworkContext.selectedFramework.name} ` +
332 | `(reason: ${frameworkContext.metadata.selectionReason})`
333 | );
334 |
335 | return frameworkContext;
336 | }
337 |
338 | /**
339 | * Validate alignment between semantic analysis and selected framework
340 | */
341 | private validateFrameworkAlignment(
342 | semanticAnalysis: ContentAnalysisResult,
343 | frameworkContext: FrameworkExecutionContext
344 | ): FrameworkAlignmentResult {
345 | const framework = frameworkContext.selectedFramework;
346 |
347 | // Calculate alignment scores
348 | const confidenceAlignment = this.calculateConfidenceAlignment(
349 | semanticAnalysis.confidence,
350 | frameworkContext.metadata.confidence
351 | );
352 |
353 | const complexityMatch = this.calculateComplexityMatch(
354 | semanticAnalysis.complexity,
355 | framework
356 | );
357 |
358 | const executionTypeCompatibility = this.calculateExecutionTypeCompatibility(
359 | semanticAnalysis.executionType,
360 | framework
361 | );
362 |
363 | const overallAlignment = (confidenceAlignment + complexityMatch + executionTypeCompatibility) / 3;
364 |
365 | return {
366 | overallAlignment,
367 | detailedMetrics: {
368 | confidenceAlignment,
369 | complexityMatch,
370 | executionTypeCompatibility
371 | }
372 | };
373 | }
374 |
375 | /**
376 | * Generate alternative framework options for consensus
377 | */
378 | private generateAlternativeFrameworks(
379 | criteria: FrameworkSelectionCriteria,
380 | currentContext: FrameworkExecutionContext,
381 | semanticAnalysis?: ContentAnalysisResult
382 | ): FrameworkDefinition[] {
383 | const allFrameworks = this.frameworkManager.listFrameworks(true);
384 | const currentFramework = currentContext.selectedFramework;
385 |
386 | // Return frameworks that are NOT the current one, sorted by suitability
387 | return allFrameworks
388 | .filter(f => f.id !== currentFramework.id)
389 | .filter(f => !this.config.blacklistedFrameworks.includes(f.id))
390 | .slice(0, 3); // Limit to top 3 alternatives
391 | }
392 |
393 | /**
394 | * Generate integrated recommendations combining semantic and framework insights
395 | */
396 | private generateIntegratedRecommendations(
397 | semanticAnalysis: ContentAnalysisResult,
398 | frameworkContext: FrameworkExecutionContext,
399 | alignment: FrameworkAlignmentResult
400 | ) {
401 | return {
402 | executionApproach: this.generateExecutionApproach(semanticAnalysis, frameworkContext),
403 | expectedPerformance: {
404 | processingTime: this.estimateProcessingTime(semanticAnalysis),
405 | memoryUsage: this.estimateMemoryUsage(semanticAnalysis),
406 | cacheable: semanticAnalysis.complexity !== "high"
407 | },
408 | qualityAssurance: [
409 | ...semanticAnalysis.suggestedGates,
410 | ...this.getFrameworkSpecificGates(frameworkContext.selectedFramework)
411 | ],
412 | optimizations: this.generateOptimizationSuggestions(semanticAnalysis, frameworkContext, alignment)
413 | };
414 | }
415 |
416 | // Helper methods for alignment calculations
417 |
418 | private calculateConfidenceAlignment(semanticConfidence: number, frameworkConfidence: number): number {
419 | // How well do the confidence scores align?
420 | const difference = Math.abs(semanticConfidence - frameworkConfidence);
421 | return Math.max(0, 1 - difference);
422 | }
423 |
424 | private calculateComplexityMatch(
425 | semanticComplexity: string,
426 | framework: FrameworkDefinition
427 | ): number {
428 | // Check if framework is suitable for the complexity level
429 | const complexityScore: Record<string, number> = {
430 | 'low': 1,
431 | 'medium': 2,
432 | 'high': 3
433 | };
434 |
435 | const semantic = complexityScore[semanticComplexity] || 2;
436 |
437 | // Framework suitability based on methodology
438 | let frameworkSuitability = 2; // Default medium
439 | switch (framework.methodology) {
440 | case 'CAGEERF':
441 | frameworkSuitability = 3; // Best for high complexity
442 | break;
443 | case 'ReACT':
444 | frameworkSuitability = 2.5; // Good for medium-high
445 | break;
446 | case '5W1H':
447 | frameworkSuitability = 2; // Good for medium
448 | break;
449 | case 'SCAMPER':
450 | frameworkSuitability = 1.5; // Best for low-medium
451 | break;
452 | }
453 |
454 | const difference = Math.abs(semantic - frameworkSuitability);
455 | return Math.max(0, 1 - difference / 3);
456 | }
457 |
458 | private calculateExecutionTypeCompatibility(
459 | executionType: string,
460 | framework: FrameworkDefinition
461 | ): number {
462 | // Check if execution type is compatible with framework
463 | if (framework.applicableTypes.length === 0) return 1.0; // Framework supports all types
464 |
465 | return framework.applicableTypes.includes(executionType) ? 1.0 : 0.6;
466 | }
467 |
468 | // Additional helper methods
469 |
470 | private generateExecutionApproach(
471 | semanticAnalysis: ContentAnalysisResult,
472 | frameworkContext: FrameworkExecutionContext
473 | ): string {
474 | const baseApproach = `Execute as ${semanticAnalysis.executionType} using ${frameworkContext.selectedFramework.name} methodology`;
475 |
476 | // Add mode-specific context
477 | if (semanticAnalysis.analysisMetadata.mode === 'structural') {
478 | return `${baseApproach} (structural analysis mode)`;
479 | } else if (semanticAnalysis.analysisMetadata.mode === 'semantic') {
480 | return `${baseApproach} (intelligent semantic analysis)`;
481 | } else {
482 | return `${baseApproach} (fallback analysis mode)`;
483 | }
484 | }
485 |
486 | private getFrameworkSpecificGates(framework: FrameworkDefinition): string[] {
487 | const gates: string[] = [];
488 |
489 | // Use actual gate IDs from definitions directory
490 | switch (framework.methodology) {
491 | case 'CAGEERF':
492 | gates.push('framework-compliance', 'technical-accuracy', 'content-structure');
493 | break;
494 | case 'ReACT':
495 | gates.push('framework-compliance', 'educational-clarity');
496 | break;
497 | case '5W1H':
498 | gates.push('framework-compliance', 'research-quality');
499 | break;
500 | case 'SCAMPER':
501 | gates.push('framework-compliance', 'content-structure');
502 | break;
503 | }
504 |
505 | return gates;
506 | }
507 |
508 | private generateOptimizationSuggestions(
509 | semanticAnalysis: ContentAnalysisResult,
510 | frameworkContext: FrameworkExecutionContext,
511 | alignment: FrameworkAlignmentResult
512 | ): string[] {
513 | const suggestions: string[] = [];
514 |
515 | if (alignment.overallAlignment < 0.7) {
516 | suggestions.push("Consider framework switching for better alignment");
517 | }
518 |
519 | if (semanticAnalysis.complexity === "low") {
520 | suggestions.push("Enable parallel processing for performance improvement");
521 | }
522 |
523 | if (semanticAnalysis.confidence > 0.8) {
524 | suggestions.push("Enable caching to improve repeat performance");
525 | }
526 |
527 | // Mode-specific suggestions
528 | if (semanticAnalysis.analysisMetadata.mode === 'structural') {
529 | suggestions.push("Consider enabling semantic analysis for intelligent framework recommendations");
530 | if (semanticAnalysis.limitations.length > 0) {
531 | suggestions.push("Enable LLM integration or Claude hooks for better analysis capabilities");
532 | }
533 | }
534 |
535 | // Warning-based suggestions
536 | if (semanticAnalysis.warnings.length > 0) {
537 | suggestions.push("Review analysis warnings for potential configuration improvements");
538 | }
539 |
540 | return suggestions;
541 | }
542 |
543 | /**
544 | * Estimate processing time based on semantic analysis
545 | */
546 | private estimateProcessingTime(semanticAnalysis: ContentAnalysisResult): number {
547 | let baseTime = 100; // Base processing time in ms
548 |
549 | // Adjust based on complexity
550 | switch (semanticAnalysis.complexity) {
551 | case "high":
552 | baseTime *= 3;
553 | break;
554 | case "medium":
555 | baseTime *= 2;
556 | break;
557 | default:
558 | break;
559 | }
560 |
561 | // Adjust based on execution type
562 | switch (semanticAnalysis.executionType) {
563 | case "chain":
564 | // Advanced chains with workflow-like features get higher multiplier
565 | if (semanticAnalysis.executionCharacteristics.advancedChainFeatures?.requiresAdvancedExecution) {
566 | baseTime *= 2.5;
567 | } else {
568 | baseTime *= 2;
569 | }
570 | break;
571 | default:
572 | break;
573 | }
574 |
575 | return baseTime;
576 | }
577 |
578 | /**
579 | * Estimate memory usage based on semantic analysis
580 | */
581 | private estimateMemoryUsage(semanticAnalysis: ContentAnalysisResult): string {
582 | if (semanticAnalysis.complexity === "high") {
583 | return "high";
584 | } else if (semanticAnalysis.complexity === "medium") {
585 | return "medium";
586 | } else {
587 | return "low";
588 | }
589 | }
590 |
591 | private updateFrameworkUsage(
592 | frameworkId: string,
593 | processingTime: number,
594 | alignmentScore: number
595 | ): void {
596 | let metrics = this.frameworkUsageHistory.get(frameworkId);
597 |
598 | if (!metrics) {
599 | metrics = {
600 | usageCount: 0,
601 | averageProcessingTime: 0,
602 | averageAlignmentScore: 0,
603 | lastUsed: new Date()
604 | };
605 | }
606 |
607 | metrics.usageCount++;
608 | metrics.averageProcessingTime = (metrics.averageProcessingTime + processingTime) / 2;
609 | metrics.averageAlignmentScore = (metrics.averageAlignmentScore + alignmentScore) / 2;
610 | metrics.lastUsed = new Date();
611 |
612 | this.frameworkUsageHistory.set(frameworkId, metrics);
613 | }
614 |
615 | private generateUsageRecommendations(insights: FrameworkUsageInsights): string[] {
616 | const recommendations: string[] = [];
617 |
618 | const frameworkUsage = Object.values(insights.frameworkUsage);
619 | if (frameworkUsage.length === 0) return recommendations;
620 |
621 | // Find best and worst performing frameworks
622 | const mostUsedFramework = frameworkUsage.reduce((best, current) =>
623 | current.usageCount > best.usageCount ? current : best
624 | );
625 |
626 | const leastUsedFramework = frameworkUsage.reduce((worst, current) =>
627 | current.usageCount < worst.usageCount ? current : worst
628 | );
629 |
630 | if (mostUsedFramework.usageCount > 10) {
631 | recommendations.push(`Most used framework: ${mostUsedFramework.framework.name} (${mostUsedFramework.usageCount} uses)`);
632 | }
633 |
634 | if (leastUsedFramework.usageCount === 0) {
635 | recommendations.push(`Unused framework: ${leastUsedFramework.framework.name} - consider if it's needed`);
636 | }
637 |
638 | return recommendations;
639 | }
640 |
641 | private estimateImprovementPotential(
642 | currentFramework: FrameworkDefinition,
643 | alternativeFramework: FrameworkDefinition,
644 | semanticAnalysis: ContentAnalysisResult
645 | ): number {
646 | // Estimate potential improvement based on framework characteristics
647 | let improvement = 0.1; // Base improvement assumption
648 |
649 | // Framework-specific improvements
650 | if (semanticAnalysis.complexity === 'high' && alternativeFramework.methodology === 'CAGEERF') {
651 | improvement += 0.2;
652 | }
653 |
654 | if (semanticAnalysis.executionType === 'chain' && alternativeFramework.methodology === 'ReACT') {
655 | improvement += 0.15;
656 | }
657 |
658 | return Math.min(improvement, 0.4); // Cap at 40% improvement
659 | }
660 |
661 | private async createNonFrameworkIntegratedResult(prompt: ConvertedPrompt, startTime: number): Promise<IntegratedAnalysisResult> {
662 | // When framework system is disabled, provide semantic analysis without framework integration
663 | const semanticAnalysis = await this.semanticAnalyzer.analyzePrompt(prompt);
664 |
665 | return {
666 | semanticAnalysis,
667 | frameworkContext: null as any, // No framework context when disabled
668 | integration: {
669 | frameworkSelectionReason: "Framework system disabled",
670 | semanticFrameworkAlignment: 0,
671 | alternativeFrameworks: [],
672 | consensusMetrics: {
673 | confidenceAlignment: 0,
674 | complexityMatch: 0,
675 | executionTypeCompatibility: 0
676 | }
677 | },
678 | recommendations: {
679 | executionApproach: `Execute as ${semanticAnalysis.executionType} without framework methodology`,
680 | expectedPerformance: {
681 | processingTime: this.estimateProcessingTime(semanticAnalysis),
682 | memoryUsage: this.estimateMemoryUsage(semanticAnalysis),
683 | cacheable: semanticAnalysis.complexity !== "high"
684 | },
685 | qualityAssurance: semanticAnalysis.suggestedGates,
686 | optimizations: ["Framework system disabled - using standard execution"]
687 | }
688 | };
689 | }
690 |
691 | /**
692 | * Phase 4: Set prompt guidance service for intelligent coordination
693 | */
694 | setPromptGuidanceService(promptGuidanceService: PromptGuidanceService): void {
695 | this.promptGuidanceService = promptGuidanceService;
696 | this.logger.info("PromptGuidanceService integrated with FrameworkSemanticIntegration");
697 | }
698 |
699 | /**
700 | * Phase 4: Check if prompt guidance is available and ready
701 | */
702 | hasPromptGuidance(): boolean {
703 | return this.promptGuidanceService?.isInitialized() ?? false;
704 | }
705 |
706 | /**
707 | * Phase 4: Apply semantic-guided prompt enhancement
708 | */
709 | async applySemanticGuidedEnhancement(
710 | prompt: ConvertedPrompt,
711 | semanticAnalysis: ContentAnalysisResult,
712 | frameworkContext: FrameworkExecutionContext
713 | ): Promise<any> {
714 | if (!this.promptGuidanceService?.isInitialized()) {
715 | this.logger.debug("Prompt guidance service not available for semantic-guided enhancement");
716 | return null;
717 | }
718 |
719 | try {
720 | const guidanceResult = await this.promptGuidanceService.applyGuidance(prompt, {
721 | includeSystemPromptInjection: true,
722 | includeTemplateEnhancement: true,
723 | frameworkOverride: frameworkContext.selectedFramework.methodology,
724 | semanticAnalysis: semanticAnalysis
725 | });
726 |
727 | return {
728 | enhancedPrompt: guidanceResult.enhancedPrompt,
729 | systemPromptInjection: guidanceResult.systemPromptInjection,
730 | templateEnhancement: guidanceResult.templateEnhancement,
731 | guidanceMetadata: {
732 | semanticAware: guidanceResult.metadata.semanticAware,
733 | semanticComplexity: guidanceResult.metadata.semanticComplexity,
734 | confidenceScore: guidanceResult.metadata.confidenceScore,
735 | enhancementsApplied: guidanceResult.metadata.enhancementsApplied
736 | }
737 | };
738 | } catch (error) {
739 | this.logger.error("Failed to apply semantic-guided enhancement:", error);
740 | return null;
741 | }
742 | }
743 |
744 | private createFallbackIntegratedResult(prompt: ConvertedPrompt, startTime: number): IntegratedAnalysisResult {
745 | const fallbackFramework = this.frameworkManager.listFrameworks(true)[0];
746 |
747 | return {
748 | semanticAnalysis: {
749 | executionType: "template",
750 | requiresExecution: false,
751 | requiresFramework: false,
752 | confidence: 0.3,
753 | reasoning: ["Fallback analysis"],
754 |
755 | capabilities: {
756 | canDetectStructure: false,
757 | canAnalyzeComplexity: false,
758 | canRecommendFramework: false,
759 | hasSemanticUnderstanding: false
760 | },
761 |
762 | limitations: ["Fallback analysis with minimal capabilities"],
763 | warnings: ["Analysis failed - using basic fallback"],
764 |
765 | executionCharacteristics: {
766 | hasConditionals: false,
767 | hasLoops: false,
768 | hasChainSteps: false,
769 | argumentCount: 0,
770 | templateComplexity: 0,
771 | hasSystemMessage: false,
772 | hasUserTemplate: false,
773 | hasStructuredReasoning: false,
774 | hasMethodologyKeywords: false,
775 | hasComplexAnalysis: false
776 | },
777 | complexity: "low",
778 | suggestedGates: ["basic_validation"],
779 | frameworkRecommendation: {
780 | shouldUseFramework: false,
781 | reasoning: ["Fallback analysis - framework not recommended"],
782 | confidence: 0.9
783 | },
784 | analysisMetadata: {
785 | version: "2.0.0",
786 | mode: "structural",
787 | analysisTime: performance.now() - startTime,
788 | analyzer: "content",
789 | cacheHit: false
790 | }
791 | },
792 | frameworkContext: this.frameworkManager.generateExecutionContext(prompt, {
793 | executionType: "template",
794 | complexity: "low"
795 | }),
796 | integration: {
797 | frameworkSelectionReason: "Fallback selection",
798 | semanticFrameworkAlignment: 0.3,
799 | alternativeFrameworks: [],
800 | consensusMetrics: {
801 | confidenceAlignment: 0.3,
802 | complexityMatch: 0.3,
803 | executionTypeCompatibility: 0.3
804 | }
805 | },
806 | recommendations: {
807 | executionApproach: "Basic template execution",
808 | expectedPerformance: {
809 | processingTime: 100,
810 | memoryUsage: "low",
811 | cacheable: true
812 | },
813 | qualityAssurance: ["basic_validation"],
814 | optimizations: []
815 | }
816 | };
817 | }
818 | }
819 |
820 | // Supporting interfaces
821 |
822 | interface FrameworkUsageMetrics {
823 | usageCount: number;
824 | averageProcessingTime: number;
825 | averageAlignmentScore: number;
826 | lastUsed: Date;
827 | }
828 |
829 | interface FrameworkAlignmentResult {
830 | overallAlignment: number;
831 | detailedMetrics: {
832 | confidenceAlignment: number;
833 | complexityMatch: number;
834 | executionTypeCompatibility: number;
835 | };
836 | }
837 |
838 | // Interfaces imported from types/index.js
839 |
840 | /**
841 | * Create and configure framework-semantic integration with configurable analyzer
842 | */
843 | export async function createFrameworkSemanticIntegration(
844 | frameworkManager: FrameworkManager,
845 | frameworkStateManager: FrameworkStateManager,
846 | logger: Logger,
847 | semanticAnalyzer: ContentAnalyzer,
848 | config?: Partial<FrameworkSwitchingConfig>
849 | ): Promise<FrameworkSemanticIntegration> {
850 | return new FrameworkSemanticIntegration(frameworkManager, frameworkStateManager, semanticAnalyzer, logger, config);
851 | }
```
--------------------------------------------------------------------------------
/server/src/frameworks/prompt-guidance/template-enhancer.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Template Enhancer - Phase 3 Implementation
3 | *
4 | * Enhances user templates with methodology guidance and framework-specific improvements.
5 | * Extracted from methodology guide enhancement logic for centralized template processing.
6 | */
7 |
8 | import { Logger } from "../../logging/index.js";
9 | import { ConvertedPrompt } from "../../types/index.js";
10 | import {
11 | IMethodologyGuide,
12 | FrameworkDefinition,
13 | TemplateEnhancementResult,
14 | ProcessingGuidance,
15 | TemplateEnhancementConfig
16 | } from "../types/index.js";
17 | import { ContentAnalysisResult } from "../../semantic/configurable-semantic-analyzer.js";
18 | import { LightweightGateSystem } from "../../gates/core/index.js";
19 |
20 | /**
21 | * Template enhancement configuration
22 | */
23 | export interface TemplateEnhancerConfig {
24 | enableArgumentSuggestions: boolean;
25 | enableStructureOptimization: boolean;
26 | enableValidationIntegration: boolean;
27 | enableQualityGates: boolean;
28 | maxSuggestions: number;
29 | enhancementLevel: 'minimal' | 'moderate' | 'comprehensive';
30 | // Phase 4: Semantic awareness settings
31 | enableSemanticAwareness: boolean;
32 | semanticComplexityAdaptation: boolean;
33 | semanticInsightIntegration: boolean;
34 | semanticEnhancementStrategy: 'conservative' | 'moderate' | 'aggressive';
35 | }
36 |
37 | /**
38 | * Template enhancement context
39 | */
40 | export interface TemplateEnhancementContext {
41 | promptName: string;
42 | promptCategory: string;
43 | promptType: string;
44 | existingArguments: string[];
45 | targetAudience?: string;
46 | complexityLevel?: 'low' | 'medium' | 'high';
47 | }
48 |
49 | /**
50 | * Template Enhancer
51 | *
52 | * Applies methodology-specific enhancements to user templates,
53 | * providing intelligent suggestions and structural improvements.
54 | */
55 | export class TemplateEnhancer {
56 | private logger: Logger;
57 | private config: TemplateEnhancerConfig;
58 | private gateSystem?: LightweightGateSystem;
59 |
60 | constructor(logger: Logger, config?: Partial<TemplateEnhancerConfig>, gateSystem?: LightweightGateSystem) {
61 | this.logger = logger;
62 | this.gateSystem = gateSystem;
63 | this.config = {
64 | enableArgumentSuggestions: true,
65 | enableStructureOptimization: true,
66 | enableValidationIntegration: true,
67 | enableQualityGates: true,
68 | maxSuggestions: 10,
69 | enhancementLevel: 'moderate',
70 | // Phase 4: Semantic awareness defaults
71 | enableSemanticAwareness: true,
72 | semanticComplexityAdaptation: true,
73 | semanticInsightIntegration: true,
74 | semanticEnhancementStrategy: 'moderate',
75 | ...config
76 | };
77 | }
78 |
79 | /**
80 | * Enhance template with methodology guidance
81 | * Extracted from methodology guide.guideTemplateProcessing()
82 | * Phase 4: Enhanced with semantic analysis awareness
83 | */
84 | async enhanceTemplate(
85 | template: string,
86 | prompt: ConvertedPrompt,
87 | methodologyGuide: IMethodologyGuide,
88 | framework: FrameworkDefinition,
89 | context?: TemplateEnhancementContext,
90 | semanticAnalysis?: ContentAnalysisResult
91 | ): Promise<TemplateEnhancementResult> {
92 | const startTime = Date.now();
93 | this.logger.debug(`Enhancing template with ${framework.methodology} methodology for ${prompt.name}`);
94 |
95 | try {
96 | // Get methodology-specific template processing guidance
97 | const processingGuidance = methodologyGuide.guideTemplateProcessing(
98 | template,
99 | prompt.executionMode || 'template'
100 | );
101 |
102 | // Build enhancement context with semantic analysis
103 | const enhancementContext = this.buildEnhancementContext(prompt, context, semanticAnalysis);
104 |
105 | // Apply enhancements based on configuration and semantic insights
106 | const enhancedTemplate = await this.applyEnhancements(
107 | template,
108 | processingGuidance,
109 | methodologyGuide,
110 | enhancementContext,
111 | semanticAnalysis
112 | );
113 |
114 | // Generate improvement suggestions with semantic insights
115 | const suggestions = this.generateSuggestions(
116 | template,
117 | enhancedTemplate,
118 | processingGuidance,
119 | methodologyGuide,
120 | enhancementContext,
121 | semanticAnalysis
122 | );
123 |
124 | // Validate enhanced template with semantic awareness
125 | const validation = this.validateEnhancedTemplate(
126 | enhancedTemplate,
127 | processingGuidance,
128 | methodologyGuide,
129 | semanticAnalysis
130 | );
131 |
132 | const result: TemplateEnhancementResult = {
133 | originalTemplate: template,
134 | enhancedTemplate,
135 | suggestions,
136 | processingGuidance,
137 | sourceFramework: framework,
138 | metadata: {
139 | enhancementTime: new Date(),
140 | enhancementLevel: this.config.enhancementLevel,
141 | suggestionsCount: suggestions.length,
142 | validationPassed: validation.passed,
143 | processingTimeMs: Date.now() - startTime,
144 | methodologyApplied: framework.methodology,
145 | // Phase 4: Semantic analysis metadata
146 | semanticAware: semanticAnalysis !== undefined,
147 | semanticComplexity: semanticAnalysis?.complexity,
148 | semanticConfidence: semanticAnalysis?.confidence,
149 | semanticEnhancementsApplied: this.getSemanticEnhancementsApplied(semanticAnalysis)
150 | },
151 | validation
152 | };
153 |
154 | this.logger.debug(`Template enhancement completed for ${framework.methodology} in ${result.metadata.processingTimeMs}ms`);
155 | return result;
156 |
157 | } catch (error) {
158 | this.logger.error(`Failed to enhance template with ${framework.methodology}:`, error);
159 |
160 | // Return fallback result with original template
161 | return {
162 | originalTemplate: template,
163 | enhancedTemplate: template,
164 | suggestions: [],
165 | processingGuidance: {
166 | processingSteps: [],
167 | templateEnhancements: {
168 | systemPromptAdditions: [],
169 | userPromptModifications: [],
170 | contextualHints: []
171 | },
172 | executionFlow: {
173 | preProcessingSteps: [],
174 | postProcessingSteps: [],
175 | validationSteps: []
176 | }
177 | },
178 | sourceFramework: framework,
179 | metadata: {
180 | enhancementTime: new Date(),
181 | enhancementLevel: this.config.enhancementLevel,
182 | suggestionsCount: 0,
183 | validationPassed: false,
184 | processingTimeMs: Date.now() - startTime,
185 | methodologyApplied: framework.methodology,
186 | error: error instanceof Error ? error.message : 'Unknown error'
187 | },
188 | validation: {
189 | passed: false,
190 | score: 0,
191 | issues: [error instanceof Error ? error.message : 'Enhancement failed'],
192 | recommendations: ['Review template structure and methodology compatibility']
193 | }
194 | };
195 | }
196 | }
197 |
198 | /**
199 | * Apply methodology-specific enhancements to template
200 | * Phase 4: Enhanced with semantic analysis awareness
201 | */
202 | private async applyEnhancements(
203 | template: string,
204 | guidance: ProcessingGuidance,
205 | methodologyGuide: IMethodologyGuide,
206 | context: TemplateEnhancementContext,
207 | semanticAnalysis?: ContentAnalysisResult
208 | ): Promise<string> {
209 | let enhancedTemplate = template;
210 |
211 | // Phase 4: Apply semantic-aware enhancements first
212 | if (this.config.enableSemanticAwareness && semanticAnalysis) {
213 | enhancedTemplate = this.applySemanticAwareEnhancements(
214 | enhancedTemplate,
215 | semanticAnalysis,
216 | methodologyGuide,
217 | context
218 | );
219 | }
220 |
221 | // Apply structural improvements based on enhancement level
222 | if (this.config.enableStructureOptimization) {
223 | enhancedTemplate = this.applyStructuralEnhancements(
224 | enhancedTemplate,
225 | guidance.templateEnhancements.contextualHints,
226 | context,
227 | semanticAnalysis
228 | );
229 | }
230 |
231 | // FIXED: Remove duplicate methodology structure addition
232 | // The framework system prompt already provides methodology guidance
233 | // Template enhancer should focus on structure optimization, not methodology duplication
234 |
235 | // Integrate quality gates if enabled (with semantic complexity awareness)
236 | if (this.config.enableQualityGates && this.shouldApplyQualityGates(semanticAnalysis)) {
237 | enhancedTemplate = await this.integrateQualityGates(
238 | enhancedTemplate,
239 | guidance.executionFlow.validationSteps,
240 | context,
241 | semanticAnalysis
242 | );
243 | }
244 |
245 | return enhancedTemplate;
246 | }
247 |
248 | /**
249 | * Apply structural enhancements to template
250 | * Phase 4: Enhanced with semantic analysis awareness
251 | */
252 | private applyStructuralEnhancements(
253 | template: string,
254 | suggestions: string[],
255 | context: TemplateEnhancementContext,
256 | semanticAnalysis?: ContentAnalysisResult
257 | ): string {
258 | let enhanced = template;
259 |
260 | // Phase 4: Use semantic analysis to guide structural improvements
261 | if (semanticAnalysis && this.config.enableSemanticAwareness) {
262 | // Add structure based on semantic complexity
263 | if (!this.hasStructuredSections(template) && this.shouldAddStructure(semanticAnalysis)) {
264 | enhanced = this.addSemanticAwareStructure(enhanced, context, semanticAnalysis);
265 | }
266 |
267 | // Apply suggestions based on semantic characteristics
268 | const semanticFilteredSuggestions = this.filterSuggestionsBySemanticAnalysis(
269 | suggestions,
270 | semanticAnalysis
271 | );
272 | for (const suggestion of semanticFilteredSuggestions.slice(0, this.config.maxSuggestions)) {
273 | enhanced = this.applySuggestion(enhanced, suggestion, context);
274 | }
275 | } else {
276 | // Fallback to original logic
277 | if (!this.hasStructuredSections(template)) {
278 | enhanced = this.addBasicStructure(enhanced, context);
279 | }
280 |
281 | for (const suggestion of suggestions.slice(0, this.config.maxSuggestions)) {
282 | enhanced = this.applySuggestion(enhanced, suggestion, context);
283 | }
284 | }
285 |
286 | return enhanced;
287 | }
288 |
289 | /**
290 | * Add methodology-specific structure to template
291 | * Phase 4: Enhanced with semantic analysis awareness
292 | */
293 | private addMethodologyStructure(
294 | template: string,
295 | methodologyGuide: IMethodologyGuide,
296 | context: TemplateEnhancementContext,
297 | semanticAnalysis?: ContentAnalysisResult
298 | ): string {
299 | const methodology = methodologyGuide.methodology;
300 | let enhanced = template;
301 |
302 | // Phase 4: Determine methodology structure complexity based on semantic analysis
303 | const structureLevel = this.determineMethodologyStructureLevel(semanticAnalysis);
304 |
305 | // Add methodology-specific sections based on type and semantic complexity
306 | switch (methodology) {
307 | case "CAGEERF":
308 | enhanced = this.addCAGEERFStructure(enhanced, context, structureLevel);
309 | break;
310 | case "ReACT":
311 | enhanced = this.addReACTStructure(enhanced, context, structureLevel);
312 | break;
313 | case "5W1H":
314 | enhanced = this.add5W1HStructure(enhanced, context, structureLevel);
315 | break;
316 | case "SCAMPER":
317 | enhanced = this.addSCAMPERStructure(enhanced, context, structureLevel);
318 | break;
319 | }
320 |
321 | return enhanced;
322 | }
323 |
324 | /**
325 | * Add CAGEERF methodology structure
326 | * Phase 4: Enhanced with semantic structure levels
327 | */
328 | private addCAGEERFStructure(
329 | template: string,
330 | context: TemplateEnhancementContext,
331 | structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'
332 | ): string {
333 | if (template.includes('## Context') || template.includes('## Analysis')) {
334 | return template; // Already has CAGEERF structure
335 | }
336 |
337 | // Phase 4: Adapt CAGEERF structure based on semantic complexity
338 | let cageerfSections = '';
339 |
340 | switch (structureLevel) {
341 | case 'minimal':
342 | cageerfSections = `
343 | ## Context & Analysis
344 | Provide context and analyze the situation.
345 |
346 | ## Goals & Execution
347 | Define objectives and outline the approach.
348 |
349 | ## Evaluation
350 | Assess the effectiveness of the solution.
351 | `;
352 | break;
353 |
354 | case 'comprehensive':
355 | cageerfSections = `
356 | ## Context
357 | Please provide the situational context and background information.
358 | *Consider stakeholders, constraints, and environmental factors.*
359 |
360 | ## Analysis
361 | Conduct systematic analysis of the situation or problem.
362 | *Use analytical frameworks and identify root causes.*
363 |
364 | ## Goals
365 | Define specific, measurable objectives and desired outcomes.
366 | *Ensure goals are SMART (Specific, Measurable, Achievable, Relevant, Time-bound).*
367 |
368 | ## Execution
369 | Outline the implementation approach and action steps.
370 | *Include timelines, resources, and risk mitigation strategies.*
371 |
372 | ## Evaluation
373 | Assess the effectiveness and quality of the solution.
374 | *Define metrics and evaluation criteria.*
375 |
376 | ## Refinement
377 | Identify improvement opportunities and optimization strategies.
378 | *Consider feedback loops and continuous improvement.*
379 |
380 | ## Framework
381 | Document the methodology and approach used.
382 | *Reflect on the CAGEERF process and lessons learned.*
383 | `;
384 | break;
385 |
386 | case 'moderate':
387 | default:
388 | cageerfSections = `
389 | ## Context
390 | Please provide the situational context and background information.
391 |
392 | ## Analysis
393 | Conduct systematic analysis of the situation or problem.
394 |
395 | ## Goals
396 | Define specific, measurable objectives and desired outcomes.
397 |
398 | ## Execution
399 | Outline the implementation approach and action steps.
400 |
401 | ## Evaluation
402 | Assess the effectiveness and quality of the solution.
403 |
404 | ## Refinement
405 | Identify improvement opportunities and optimization strategies.
406 |
407 | ## Framework
408 | Document the methodology and approach used.
409 | `;
410 | break;
411 | }
412 |
413 | return template + cageerfSections;
414 | }
415 |
416 | /**
417 | * Add ReACT methodology structure
418 | */
419 | private addReACTStructure(template: string, context: TemplateEnhancementContext, structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'): string {
420 | if (template.includes('## Reasoning') || template.includes('## Action')) {
421 | return template; // Already has ReACT structure
422 | }
423 |
424 | const reactSections = `
425 | ## Reasoning
426 | Think through the problem systematically and logically.
427 |
428 | ## Action
429 | Take specific, targeted actions based on the reasoning.
430 |
431 | ## Observation
432 | Observe the results and gather feedback from actions taken.
433 | `;
434 |
435 | return template + reactSections;
436 | }
437 |
438 | /**
439 | * Add 5W1H methodology structure
440 | */
441 | private add5W1HStructure(template: string, context: TemplateEnhancementContext, structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'): string {
442 | if (template.includes('## Who') || template.includes('## What')) {
443 | return template; // Already has 5W1H structure
444 | }
445 |
446 | const fiveW1HSections = `
447 | ## Who
448 | Identify the stakeholders, people involved, and target audience.
449 |
450 | ## What
451 | Define what needs to be accomplished or addressed.
452 |
453 | ## When
454 | Establish timelines, deadlines, and scheduling considerations.
455 |
456 | ## Where
457 | Specify locations, environments, or contexts where this applies.
458 |
459 | ## Why
460 | Understand the underlying reasons, motivations, and objectives.
461 |
462 | ## How
463 | Outline the methods, processes, and approaches to be used.
464 | `;
465 |
466 | return template + fiveW1HSections;
467 | }
468 |
469 | /**
470 | * Add SCAMPER methodology structure
471 | */
472 | private addSCAMPERStructure(template: string, context: TemplateEnhancementContext, structureLevel: 'minimal' | 'moderate' | 'comprehensive' = 'moderate'): string {
473 | if (template.includes('## Substitute') || template.includes('## Combine')) {
474 | return template; // Already has SCAMPER structure
475 | }
476 |
477 | const scamperSections = `
478 | ## Substitute
479 | What can be substituted or replaced to improve the solution?
480 |
481 | ## Combine
482 | What ideas, processes, or elements can be combined?
483 |
484 | ## Adapt
485 | What can be adapted from other contexts or solutions?
486 |
487 | ## Modify
488 | What can be modified, magnified, or emphasized?
489 |
490 | ## Put to Other Uses
491 | How can this be used differently or for other purposes?
492 |
493 | ## Eliminate
494 | What can be removed, simplified, or minimized?
495 |
496 | ## Reverse
497 | What can be reversed, rearranged, or approached differently?
498 | `;
499 |
500 | return template + scamperSections;
501 | }
502 |
503 | /**
504 | * Generate improvement suggestions based on methodology
505 | */
506 | private generateSuggestions(
507 | originalTemplate: string,
508 | enhancedTemplate: string,
509 | guidance: ProcessingGuidance,
510 | methodologyGuide: IMethodologyGuide,
511 | context: TemplateEnhancementContext,
512 | semanticAnalysis?: ContentAnalysisResult
513 | ): string[] {
514 | const suggestions: string[] = [];
515 |
516 | // Add argument suggestions if enabled
517 | if (this.config.enableArgumentSuggestions) {
518 | suggestions.push(...guidance.templateEnhancements.userPromptModifications);
519 | }
520 |
521 | // Add methodology-specific suggestions
522 | suggestions.push(...this.generateMethodologySpecificSuggestions(
523 | originalTemplate,
524 | methodologyGuide,
525 | context
526 | ));
527 |
528 | // Add structural suggestions
529 | suggestions.push(...guidance.templateEnhancements.contextualHints);
530 |
531 | // Limit suggestions based on configuration
532 | return suggestions.slice(0, this.config.maxSuggestions);
533 | }
534 |
535 | /**
536 | * Generate methodology-specific suggestions
537 | */
538 | private generateMethodologySpecificSuggestions(
539 | template: string,
540 | methodologyGuide: IMethodologyGuide,
541 | context: TemplateEnhancementContext
542 | ): string[] {
543 | const suggestions: string[] = [];
544 | const methodology = methodologyGuide.methodology;
545 |
546 | // Common suggestions for all methodologies
547 | if (!template.includes('{{')) {
548 | suggestions.push("Consider adding template variables using {{variable}} syntax for dynamic content");
549 | }
550 |
551 | if (context.complexityLevel === 'high' && !template.includes('## ')) {
552 | suggestions.push("For complex prompts, consider adding structured sections with markdown headers");
553 | }
554 |
555 | // Methodology-specific suggestions
556 | switch (methodology) {
557 | case "CAGEERF":
558 | if (!template.toLowerCase().includes('context')) {
559 | suggestions.push("Consider adding a Context section to establish situational background");
560 | }
561 | if (!template.toLowerCase().includes('goal')) {
562 | suggestions.push("Define specific Goals to guide the analysis and execution");
563 | }
564 | break;
565 |
566 | case "ReACT":
567 | if (!template.toLowerCase().includes('reason')) {
568 | suggestions.push("Include reasoning steps to make thought processes explicit");
569 | }
570 | if (!template.toLowerCase().includes('action')) {
571 | suggestions.push("Specify concrete actions to take based on reasoning");
572 | }
573 | break;
574 |
575 | case "5W1H":
576 | const missing5W1H = ['who', 'what', 'when', 'where', 'why', 'how'].filter(
577 | w => !template.toLowerCase().includes(w)
578 | );
579 | if (missing5W1H.length > 0) {
580 | suggestions.push(`Consider addressing: ${missing5W1H.join(', ')} for comprehensive analysis`);
581 | }
582 | break;
583 |
584 | case "SCAMPER":
585 | if (!template.toLowerCase().includes('creative')) {
586 | suggestions.push("Emphasize creative thinking and alternative approaches");
587 | }
588 | break;
589 | }
590 |
591 | return suggestions;
592 | }
593 |
594 | /**
595 | * Integrate quality gates into template (Phase 2 enhancement)
596 | */
597 | private async integrateQualityGates(
598 | template: string,
599 | qualityGates: string[],
600 | context: TemplateEnhancementContext,
601 | semanticAnalysis?: ContentAnalysisResult
602 | ): Promise<string> {
603 | if (qualityGates.length === 0) {
604 | return template;
605 | }
606 |
607 | // Load actual gate guidance if gate system is available
608 | let gateGuidance: string[] = [];
609 | if (this.gateSystem) {
610 | try {
611 | gateGuidance = await this.gateSystem.getGuidanceText(
612 | qualityGates,
613 | {
614 | promptCategory: context.promptCategory,
615 | framework: "CAGEERF", // Default framework for gate context
616 | explicitRequest: true
617 | }
618 | );
619 | } catch (error) {
620 | this.logger.warn("Failed to load gate guidance:", error);
621 | // Fallback to gate IDs if guidance loading fails
622 | gateGuidance = qualityGates.map(gateId => `Gate: ${gateId}`);
623 | }
624 | } else {
625 | // Fallback: use gate IDs when no gate system available
626 | gateGuidance = qualityGates.map(gateId => `Quality criterion: ${gateId}`);
627 | }
628 |
629 | const qualitySection = `
630 | ## Quality Validation
631 | Please ensure the following quality criteria are met:
632 |
633 | ${gateGuidance.map(guidance => `- ${guidance}`).join('\n')}
634 | `;
635 |
636 | return template + qualitySection;
637 | }
638 |
639 | /**
640 | * Validate enhanced template
641 | */
642 | private validateEnhancedTemplate(
643 | template: string,
644 | guidance: ProcessingGuidance,
645 | methodologyGuide: IMethodologyGuide,
646 | semanticAnalysis?: ContentAnalysisResult
647 | ): {
648 | passed: boolean;
649 | score: number;
650 | issues: string[];
651 | recommendations: string[];
652 | } {
653 | const issues: string[] = [];
654 | const recommendations: string[] = [];
655 | let score = 100;
656 |
657 | // Check template length
658 | if (template.length < 50) {
659 | issues.push("Template is too short for effective guidance");
660 | score -= 20;
661 | }
662 |
663 | if (template.length > 5000) {
664 | issues.push("Template is very long and may be difficult to use");
665 | score -= 10;
666 | recommendations.push("Consider breaking into smaller, focused sections");
667 | }
668 |
669 | // Check for template variables
670 | const variableCount = (template.match(/\{\{[^}]+\}\}/g) || []).length;
671 | if (variableCount === 0 && this.config.enableArgumentSuggestions) {
672 | issues.push("No template variables found - template may not be dynamic enough");
673 | score -= 15;
674 | recommendations.push("Add {{variable}} placeholders for user input");
675 | }
676 |
677 | // Check for structure
678 | if (!this.hasStructuredSections(template)) {
679 | issues.push("Template lacks clear structure");
680 | score -= 15;
681 | recommendations.push("Add section headers to organize content");
682 | }
683 |
684 | // Check methodology integration
685 | const methodology = methodologyGuide.methodology.toLowerCase();
686 | if (!template.toLowerCase().includes(methodology)) {
687 | issues.push(`Methodology ${methodologyGuide.methodology} not clearly integrated`);
688 | score -= 10;
689 | }
690 |
691 | // Ensure minimum score
692 | score = Math.max(score, 0);
693 |
694 | return {
695 | passed: issues.length === 0,
696 | score,
697 | issues,
698 | recommendations
699 | };
700 | }
701 |
702 | /**
703 | * Build enhancement context from prompt and user context
704 | * Phase 4: Enhanced with semantic analysis integration
705 | */
706 | private buildEnhancementContext(
707 | prompt: ConvertedPrompt,
708 | userContext?: TemplateEnhancementContext,
709 | semanticAnalysis?: ContentAnalysisResult
710 | ): TemplateEnhancementContext {
711 | return {
712 | promptName: prompt.name || 'Unnamed Prompt',
713 | promptCategory: prompt.category || 'general',
714 | promptType: prompt.executionMode || 'template',
715 | existingArguments: prompt.arguments?.map(arg => arg.name) || [],
716 | complexityLevel: this.assessComplexityWithSemantics(prompt, semanticAnalysis),
717 | ...userContext
718 | };
719 | }
720 |
721 | /**
722 | * Assess prompt complexity
723 | */
724 | private assessComplexity(prompt: ConvertedPrompt): 'low' | 'medium' | 'high' {
725 | const argCount = prompt.arguments?.length || 0;
726 | const contentLength = prompt.userMessageTemplate?.length || 0;
727 |
728 | if (argCount >= 5 || contentLength > 1000) return 'high';
729 | if (argCount >= 3 || contentLength > 500) return 'medium';
730 | return 'low';
731 | }
732 |
733 | /**
734 | * Check if template has structured sections
735 | */
736 | private hasStructuredSections(template: string): boolean {
737 | return /^##\s+/.test(template) || template.includes('\n## ');
738 | }
739 |
740 | /**
741 | * Add basic structure to unstructured template
742 | */
743 | private addBasicStructure(template: string, context: TemplateEnhancementContext): string {
744 | return `## ${context.promptName}
745 |
746 | ${template}
747 |
748 | ## Output Requirements
749 | Please provide a comprehensive response that addresses all aspects of this prompt.
750 | `;
751 | }
752 |
753 | /**
754 | * Apply a specific suggestion to template
755 | */
756 | private applySuggestion(template: string, suggestion: string, context: TemplateEnhancementContext): string {
757 | // This is a simplified implementation - in practice, this would contain
758 | // more sophisticated suggestion application logic
759 | return template;
760 | }
761 |
762 | /**
763 | * Update enhancer configuration
764 | */
765 | updateConfig(config: Partial<TemplateEnhancerConfig>): void {
766 | this.config = { ...this.config, ...config };
767 | this.logger.debug('TemplateEnhancer configuration updated', config);
768 | }
769 |
770 | /**
771 | * Get current enhancer configuration
772 | */
773 | getConfig(): TemplateEnhancerConfig {
774 | return { ...this.config };
775 | }
776 |
777 | // Phase 4: Semantic-aware enhancement methods
778 |
779 | /**
780 | * Apply semantic-aware enhancements based on analysis results
781 | */
782 | private applySemanticAwareEnhancements(
783 | template: string,
784 | semanticAnalysis: ContentAnalysisResult,
785 | methodologyGuide: IMethodologyGuide,
786 | context: TemplateEnhancementContext
787 | ): string {
788 | let enhanced = template;
789 |
790 | // Apply complexity-based enhancements
791 | switch (semanticAnalysis.complexity) {
792 | case 'high':
793 | enhanced = this.applyHighComplexityEnhancements(enhanced, semanticAnalysis, context);
794 | break;
795 | case 'medium':
796 | enhanced = this.applyMediumComplexityEnhancements(enhanced, semanticAnalysis, context);
797 | break;
798 | case 'low':
799 | enhanced = this.applyLowComplexityEnhancements(enhanced, semanticAnalysis, context);
800 | break;
801 | }
802 |
803 | // Apply execution characteristic-based enhancements
804 | if (semanticAnalysis.executionCharacteristics.hasStructuredReasoning) {
805 | enhanced = this.addReasoningStructure(enhanced);
806 | }
807 |
808 | if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) {
809 | enhanced = this.addAnalysisStructure(enhanced, methodologyGuide);
810 | }
811 |
812 | return enhanced;
813 | }
814 |
815 | /**
816 | * Determine methodology structure level based on semantic analysis
817 | */
818 | private determineMethodologyStructureLevel(
819 | semanticAnalysis?: ContentAnalysisResult
820 | ): 'minimal' | 'moderate' | 'comprehensive' {
821 | if (!semanticAnalysis || !this.config.enableSemanticAwareness) {
822 | return this.config.enhancementLevel;
823 | }
824 |
825 | // Base decision on semantic complexity and confidence
826 | const complexityScore = this.calculateSemanticComplexityScore(semanticAnalysis);
827 |
828 | if (complexityScore >= 0.8) {
829 | return 'comprehensive';
830 | } else if (complexityScore >= 0.5) {
831 | return 'moderate';
832 | } else {
833 | return 'minimal';
834 | }
835 | }
836 |
837 | /**
838 | * Calculate semantic complexity score for structure decisions
839 | */
840 | private calculateSemanticComplexityScore(semanticAnalysis: ContentAnalysisResult): number {
841 | let score = 0;
842 |
843 | // Base complexity mapping
844 | switch (semanticAnalysis.complexity) {
845 | case 'high': score += 0.6; break;
846 | case 'medium': score += 0.4; break;
847 | case 'low': score += 0.2; break;
848 | }
849 |
850 | // Execution characteristics influence
851 | const chars = semanticAnalysis.executionCharacteristics;
852 | if (chars.hasStructuredReasoning) score += 0.1;
853 | if (chars.hasComplexAnalysis) score += 0.1;
854 | if (chars.hasChainSteps) score += 0.1;
855 | if (chars.argumentCount > 3) score += 0.1;
856 |
857 | // Confidence influence
858 | score += (semanticAnalysis.confidence * 0.2);
859 |
860 | return Math.min(score, 1.0);
861 | }
862 |
863 | /**
864 | * Assess complexity with semantic analysis integration
865 | */
866 | private assessComplexityWithSemantics(
867 | prompt: ConvertedPrompt,
868 | semanticAnalysis?: ContentAnalysisResult
869 | ): 'low' | 'medium' | 'high' {
870 | if (semanticAnalysis && this.config.semanticComplexityAdaptation) {
871 | return semanticAnalysis.complexity;
872 | }
873 |
874 | // Fallback to original assessment
875 | return this.assessComplexity(prompt);
876 | }
877 |
878 | /**
879 | * Determine if structure should be added based on semantic analysis
880 | */
881 | private shouldAddStructure(semanticAnalysis: ContentAnalysisResult): boolean {
882 | // Always add structure for high complexity
883 | if (semanticAnalysis.complexity === 'high') return true;
884 |
885 | // Add structure if has structured reasoning characteristics
886 | if (semanticAnalysis.executionCharacteristics.hasStructuredReasoning) return true;
887 |
888 | // Add structure if has complex analysis patterns
889 | if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) return true;
890 |
891 | // Add structure for medium complexity with high confidence
892 | if (semanticAnalysis.complexity === 'medium' && semanticAnalysis.confidence > 0.8) return true;
893 |
894 | return false;
895 | }
896 |
897 | /**
898 | * Add semantic-aware structure to template
899 | */
900 | private addSemanticAwareStructure(
901 | template: string,
902 | context: TemplateEnhancementContext,
903 | semanticAnalysis: ContentAnalysisResult
904 | ): string {
905 | const structureType = this.determineOptimalStructureType(semanticAnalysis);
906 |
907 | switch (structureType) {
908 | case 'analytical':
909 | return this.addAnalyticalStructure(template, context);
910 | case 'procedural':
911 | return this.addProceduralStructure(template, context);
912 | case 'creative':
913 | return this.addCreativeStructure(template, context);
914 | default:
915 | return this.addBasicStructure(template, context);
916 | }
917 | }
918 |
919 | /**
920 | * Filter suggestions based on semantic analysis
921 | */
922 | private filterSuggestionsBySemanticAnalysis(
923 | suggestions: string[],
924 | semanticAnalysis: ContentAnalysisResult
925 | ): string[] {
926 | // Prioritize suggestions based on semantic characteristics
927 | const prioritizedSuggestions = suggestions.map(suggestion => ({
928 | suggestion,
929 | priority: this.calculateSuggestionPriority(suggestion, semanticAnalysis)
930 | }));
931 |
932 | return prioritizedSuggestions
933 | .sort((a, b) => b.priority - a.priority)
934 | .map(item => item.suggestion);
935 | }
936 |
937 | /**
938 | * Calculate suggestion priority based on semantic analysis
939 | */
940 | private calculateSuggestionPriority(
941 | suggestion: string,
942 | semanticAnalysis: ContentAnalysisResult
943 | ): number {
944 | let priority = 1;
945 |
946 | // Higher priority for structure suggestions if template has structural reasoning
947 | if (suggestion.includes('structure') && semanticAnalysis.executionCharacteristics.hasStructuredReasoning) {
948 | priority += 2;
949 | }
950 |
951 | // Higher priority for analysis suggestions if template has complex analysis
952 | if (suggestion.includes('analysis') && semanticAnalysis.executionCharacteristics.hasComplexAnalysis) {
953 | priority += 2;
954 | }
955 |
956 | // Higher priority for variable suggestions based on argument count
957 | if (suggestion.includes('variable') && semanticAnalysis.executionCharacteristics.argumentCount > 2) {
958 | priority += 1;
959 | }
960 |
961 | return priority;
962 | }
963 |
964 | /**
965 | * Determine if quality gates should be applied based on semantic analysis
966 | */
967 | private shouldApplyQualityGates(semanticAnalysis?: ContentAnalysisResult): boolean {
968 | if (!semanticAnalysis || !this.config.enableSemanticAwareness) {
969 | return this.config.enableQualityGates && this.config.enhancementLevel === 'comprehensive';
970 | }
971 |
972 | // Apply quality gates for high complexity or high confidence scenarios
973 | return (
974 | semanticAnalysis.complexity === 'high' ||
975 | (semanticAnalysis.complexity === 'medium' && semanticAnalysis.confidence > 0.8) ||
976 | semanticAnalysis.executionCharacteristics.hasComplexAnalysis
977 | );
978 | }
979 |
980 | /**
981 | * Get semantic enhancements applied for metadata
982 | */
983 | private getSemanticEnhancementsApplied(semanticAnalysis?: ContentAnalysisResult): string[] {
984 | if (!semanticAnalysis || !this.config.enableSemanticAwareness) {
985 | return [];
986 | }
987 |
988 | const enhancements = [];
989 |
990 | if (this.config.semanticComplexityAdaptation) {
991 | enhancements.push(`complexity-${semanticAnalysis.complexity}`);
992 | }
993 |
994 | if (semanticAnalysis.executionCharacteristics.hasStructuredReasoning) {
995 | enhancements.push('structured-reasoning');
996 | }
997 |
998 | if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) {
999 | enhancements.push('complex-analysis');
1000 | }
1001 |
1002 | if (semanticAnalysis.confidence > 0.8) {
1003 | enhancements.push('high-confidence');
1004 | }
1005 |
1006 | return enhancements;
1007 | }
1008 |
1009 | // Helper methods for complexity-based enhancements
1010 |
1011 | private applyHighComplexityEnhancements(
1012 | template: string,
1013 | semanticAnalysis: ContentAnalysisResult,
1014 | context: TemplateEnhancementContext
1015 | ): string {
1016 | // Add comprehensive structure and validation for high complexity
1017 | return template;
1018 | }
1019 |
1020 | private applyMediumComplexityEnhancements(
1021 | template: string,
1022 | semanticAnalysis: ContentAnalysisResult,
1023 | context: TemplateEnhancementContext
1024 | ): string {
1025 | // Add moderate structure and guidance for medium complexity
1026 | return template;
1027 | }
1028 |
1029 | private applyLowComplexityEnhancements(
1030 | template: string,
1031 | semanticAnalysis: ContentAnalysisResult,
1032 | context: TemplateEnhancementContext
1033 | ): string {
1034 | // Apply minimal enhancements for low complexity
1035 | return template;
1036 | }
1037 |
1038 | private addReasoningStructure(template: string): string {
1039 | if (!template.includes('## Reasoning') && !template.includes('## Analysis')) {
1040 | return template + '\n\n## Reasoning\nPlease think through this step-by-step:\n\n1. \n2. \n3. ';
1041 | }
1042 | return template;
1043 | }
1044 |
1045 | private addAnalysisStructure(template: string, methodologyGuide: IMethodologyGuide): string {
1046 | if (!template.includes('## Analysis')) {
1047 | return template + `\n\n## Analysis\nApply ${methodologyGuide.methodology} systematic analysis:\n\n- \n- \n- `;
1048 | }
1049 | return template;
1050 | }
1051 |
1052 | private determineOptimalStructureType(semanticAnalysis: ContentAnalysisResult): string {
1053 | if (semanticAnalysis.executionCharacteristics.hasComplexAnalysis) return 'analytical';
1054 | if (semanticAnalysis.executionCharacteristics.hasChainSteps) return 'procedural';
1055 | if (semanticAnalysis.executionCharacteristics.hasMethodologyKeywords) return 'creative';
1056 | return 'basic';
1057 | }
1058 |
1059 | private addAnalyticalStructure(template: string, context: TemplateEnhancementContext): string {
1060 | return `## ${context.promptName} - Analytical Framework
1061 |
1062 | ${template}
1063 |
1064 | ## Analysis Steps
1065 | 1. Define the problem or question
1066 | 2. Gather relevant information
1067 | 3. Apply analytical methods
1068 | 4. Draw conclusions
1069 | 5. Validate results
1070 |
1071 | ## Expected Output
1072 | Provide a structured analysis with clear reasoning and evidence.
1073 | `;
1074 | }
1075 |
1076 | private addProceduralStructure(template: string, context: TemplateEnhancementContext): string {
1077 | return `## ${context.promptName} - Procedural Framework
1078 |
1079 | ${template}
1080 |
1081 | ## Process Steps
1082 | 1. Preparation
1083 | 2. Execution
1084 | 3. Validation
1085 | 4. Documentation
1086 |
1087 | ## Expected Output
1088 | Provide step-by-step results with clear progression.
1089 | `;
1090 | }
1091 |
1092 | private addCreativeStructure(template: string, context: TemplateEnhancementContext): string {
1093 | return `## ${context.promptName} - Creative Framework
1094 |
1095 | ${template}
1096 |
1097 | ## Creative Process
1098 | 1. Explore possibilities
1099 | 2. Generate alternatives
1100 | 3. Evaluate options
1101 | 4. Refine solutions
1102 |
1103 | ## Expected Output
1104 | Provide innovative solutions with creative reasoning.
1105 | `;
1106 | }
1107 | }
1108 |
1109 | /**
1110 | * Create and configure a TemplateEnhancer instance
1111 | */
1112 | export function createTemplateEnhancer(
1113 | logger: Logger,
1114 | config?: Partial<TemplateEnhancerConfig>,
1115 | gateSystem?: LightweightGateSystem
1116 | ): TemplateEnhancer {
1117 | return new TemplateEnhancer(logger, config, gateSystem);
1118 | }
```