@llm-dev-ops/agentics-cli 1.4.58 → 1.4.68

package/dist/pipeline/phase2/phases/sparc-specification.js

@@ -19,6 +19,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { createSpan, endSpan, emitSpan } from '../telemetry.js';
 import { normalizeContextName } from './ddd-generator.js';
+import { createClaudeCodeRunner } from '../../../runtime/claude-code-runner.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -26,11 +27,322 @@ const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
 const SPARC_SUBDIR = 'sparc';
 // ============================================================================
+// Intelligence / ML Detection
+// ============================================================================
+/**
+ * Detect whether the user's query requires intelligence/ML/analytics contexts.
+ * Returns keywords found and suggested intelligence context names.
+ */
+export function detectIntelligenceRequirements(query) {
+    const lowerQuery = query.toLowerCase();
+    const keywords = [];
+    const patterns = [
+        [/\b(?:ai|artificial[\s-]?intelligence|machine[\s-]?learning|ml)\b/i, 'AI/ML'],
+        [/\b(?:predict|prediction|predictive)\b/i, 'prediction'],
+        [/\b(?:anomal|outlier|deviation[\s-]?detect)\b/i, 'anomaly-detection'],
+        [/\b(?:pattern[\s-]?recogni|pattern[\s-]?detect|pattern[\s-]?analys)\b/i, 'pattern-recognition'],
+        [/\b(?:forecast|forecasting|time[\s-]?series)\b/i, 'forecasting'],
+        [/\b(?:classif|categoriz|cluster)\b/i, 'classification'],
+        [/\b(?:neural[\s-]?net|deep[\s-]?learn|transformer|llm|nlp)\b/i, 'deep-learning'],
+        [/\b(?:recommend|suggestion[\s-]?engine|collaborative[\s-]?filter)\b/i, 'recommendation'],
+        [/\b(?:sentiment[\s-]?analy|text[\s-]?mining|natural[\s-]?language)\b/i, 'nlp'],
+        [/\b(?:computer[\s-]?vision|image[\s-]?recogni|object[\s-]?detect)\b/i, 'vision'],
+        [/\b(?:drift|model[\s-]?degradat|concept[\s-]?drift)\b/i, 'drift-detection'],
+        [/\b(?:feature[\s-]?engineer|feature[\s-]?extract|feature[\s-]?store)\b/i, 'feature-engineering'],
+        [/\b(?:train|training[\s-]?data|training[\s-]?pipeline|model[\s-]?train)\b/i, 'model-training'],
+        [/\b(?:data[\s-]?pipeline|etl|data[\s-]?ingest|data[\s-]?lake)\b/i, 'data-pipeline'],
+        [/\b(?:analytics|analytic|statistical[\s-]?analys|data[\s-]?analys)\b/i, 'analytics'],
+        [/\b(?:historical[\s-]?data|historical[\s-]?pattern|trend[\s-]?analys)\b/i, 'historical-analysis'],
+    ];
+    for (const [pat, keyword] of patterns) {
+        if (pat.test(lowerQuery))
+            keywords.push(keyword);
+    }
+    if (keywords.length === 0)
+        return { hasIntelligence: false, keywords: [], suggestedContexts: [] };
+    // Build suggested contexts based on detected keywords
+    const suggestedContexts = [];
+    if (keywords.some(k => ['anomaly-detection', 'drift-detection', 'pattern-recognition'].includes(k))) {
+        suggestedContexts.push({
+            name: 'anomaly-detection-engine',
+            type: 'anomaly-detection',
+            commands: ['DetectAnomalies', 'TrainDetectionModel', 'UpdateBaseline', 'GetAnomalyReport', 'ConfigureThresholds'],
+            description: 'Anomaly detection and pattern recognition engine using statistical and ML models',
+        });
+    }
+    if (keywords.some(k => ['prediction', 'forecasting', 'time-series'].includes(k))) {
+        suggestedContexts.push({
+            name: 'forecasting-engine',
+            type: 'forecasting',
+            commands: ['RunForecast', 'TrainForecastModel', 'EvaluateModelAccuracy', 'GetForecastResults', 'UpdateHistoricalData'],
+            description: 'Time-series forecasting and predictive analytics engine',
+        });
+    }
+    if (keywords.some(k => ['AI/ML', 'deep-learning', 'classification', 'model-training'].includes(k))) {
+        suggestedContexts.push({
+            name: 'ml-inference-engine',
+            type: 'ml-inference',
+            commands: ['RunInference', 'TrainModel', 'DeployModel', 'EvaluateModel', 'GetModelMetrics', 'RetireModel'],
+            description: 'Machine learning model lifecycle management and inference engine',
+        });
+    }
+    if (keywords.some(k => ['analytics', 'historical-analysis'].includes(k))) {
+        suggestedContexts.push({
+            name: 'analytics-engine',
+            type: 'analytics',
+            commands: ['RunAnalysis', 'GenerateReport', 'ComputeMetrics', 'QueryHistoricalData', 'BuildDashboard'],
+            description: 'Analytics and business intelligence engine for historical data analysis',
+        });
+    }
+    if (keywords.some(k => ['data-pipeline', 'feature-engineering'].includes(k))) {
+        suggestedContexts.push({
+            name: 'data-pipeline',
+            type: 'data-pipeline',
+            commands: ['IngestData', 'TransformData', 'ExtractFeatures', 'ValidateData', 'SchedulePipeline'],
+            description: 'Data ingestion, transformation, and feature engineering pipeline',
+        });
+    }
+    if (keywords.some(k => ['recommendation', 'nlp', 'vision'].includes(k))) {
+        suggestedContexts.push({
+            name: 'ml-inference-engine',
+            type: 'ml-inference',
+            commands: ['RunInference', 'TrainModel', 'DeployModel', 'EvaluateModel', 'GetModelMetrics', 'RetireModel'],
+            description: 'Machine learning model lifecycle management and inference engine',
+        });
+    }
+    // If we detected intelligence keywords but no specific context matched, add a generic one
+    if (suggestedContexts.length === 0) {
+        suggestedContexts.push({
+            name: 'intelligence-engine',
+            type: 'analytics',
+            commands: ['AnalyzeData', 'DetectPatterns', 'GenerateInsights', 'RunModel', 'GetResults'],
+            description: 'Intelligence and analytics engine for data-driven insights',
+        });
+    }
+    // Deduplicate by name
+    const seen = new Set();
+    const deduped = suggestedContexts.filter(c => {
+        if (seen.has(c.name))
+            return false;
+        seen.add(c.name);
+        return true;
+    });
+    return { hasIntelligence: true, keywords, suggestedContexts: deduped };
+}
+// ============================================================================
 // Helpers
 // ============================================================================
+/**
+ * Load agentics fleet report from phase2Dir and format for LLM context.
+ * Returns a string summary of agent findings, or empty string if unavailable.
+ */
+function loadAgenticsFleetContext(phase2Dir) {
+    try {
+        const reportPath = path.join(phase2Dir, 'agentics-agents-report.json');
+        if (!fs.existsSync(reportPath))
+            return '';
+        const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+        if (!report.results || report.results.length === 0)
+            return '';
+        const successResults = report.results.filter(r => r.status === 200);
+        if (successResults.length === 0)
+            return '';
+        const agentSummaries = successResults.slice(0, 15).map(r => {
+            const resp = r.response;
+            const data = resp?.['data'];
+            // Extract meaningful content from agent response
+            let finding = '';
+            if (data) {
+                // Common agent response shapes
+                const plan = data['plan'];
+                const analysis = data['analysis'];
+                const hypothesis = data['hypothesis'];
+                const metrics = data['metrics'];
+                const recommendations = data['recommendations'];
+                if (plan?.['steps']) {
+                    const steps = plan['steps'].slice(0, 3);
+                    finding = steps.map(s => s['title'] || s['description'] || '').join('; ');
+                }
+                else if (analysis?.['summary'] || analysis?.['findings']) {
+                    finding = String(analysis['summary'] || analysis['findings'] || '').slice(0, 200);
+                }
+                else if (hypothesis?.['statement']) {
+                    finding = `Hypothesis: ${hypothesis['statement']}`;
+                }
+                else if (metrics?.['kpis']) {
+                    const kpis = metrics['kpis'].slice(0, 3);
+                    finding = kpis.map(k => `${k['name']}: ${k['value']} ${k['unit'] || ''}`).join('; ');
+                }
+                else if (recommendations) {
+                    finding = recommendations.slice(0, 3)
+                        .map(r2 => String(r2['recommendation'] || r2['title'] || r2)).join('; ');
+                }
+                else {
+                    // Generic extraction: take first few string values
+                    const vals = Object.values(data).filter(v => typeof v === 'string').slice(0, 2);
+                    finding = vals.map(v => String(v).slice(0, 100)).join('; ');
+                }
+            }
+            return `- [${r.domain}/${r.agent}] ${r.role}: ${finding || 'analysis completed'}`;
+        }).join('\n');
+        return `\nAGENTICS FLEET ANALYSIS (${successResults.length} agents from 27 domains):\n${agentSummaries}\n`;
+    }
+    catch {
+        return '';
+    }
+}
 function pad3(n) {
     return String(n).padStart(3, '0');
 }
+// ============================================================================
+// Complete SPARC Generation (single LLM call)
+//
+// SPARC is a high-level architecture document with 5 sections:
+//   Specification, Pseudocode, Architecture, Refinement, Completion
+// Each section should be deep, domain-specific, and cohesive — not
+// disconnected template fragments. See docs/SPARC-reference.md for examples.
+// ============================================================================
+/**
+ * Generate the ENTIRE SPARC document in one LLM call.
+ * This produces a cohesive architecture document like the PowerInfer example
+ * in docs/SPARC-reference.md — deep domain-specific content, not templates.
+ */
+function tryGenerateCompleteSPARC(query, projectContext, dossier, artifacts, phase2Dir) {
+    try {
+        const runner = createClaudeCodeRunner();
+        // Build rich context from dossier + agents
+        const dossierItems = dossier.items.slice(0, 40)
+            .map(i => `- [${i.category}] ${i.title}: ${i.content.slice(0, 200)}`)
+            .join('\n');
+        const agentContext = loadAgenticsFleetContext(phase2Dir);
+        // Extract domain services for the prompt
+        const domainServices = extractDomainServices(query, artifacts, dossier);
+        const servicesList = domainServices.map(svc => `- ${svc.name}: ${svc.responsibility} (capabilities: ${svc.capabilities.join(', ')}; systems: ${svc.relatedSystems.join(', ') || 'none'})`).join('\n');
+        // Detect tech stack
+        const allText = (query + ' ' + projectContext).toLowerCase();
+        const techStack = [];
+        const techPatterns = [
+            [/\bsap\b/i, 'SAP'], [/\bsnowflake\b/i, 'Snowflake'], [/\bsalesforce\b/i, 'Salesforce'],
+            [/\baws\b/i, 'AWS'], [/\bazure\b/i, 'Azure'], [/\bgcp\b|google cloud/i, 'GCP'],
+            [/\bkafka\b/i, 'Kafka'], [/\bpostgres/i, 'PostgreSQL'], [/\bmongodb\b/i, 'MongoDB'],
+            [/\bredis\b/i, 'Redis'], [/\bkubernetes\b|\bk8s\b/i, 'Kubernetes'],
+            [/\boracle\b/i, 'Oracle'], [/\bnetsuite\b/i, 'NetSuite'], [/\bworkday\b/i, 'Workday'],
+        ];
+        for (const [pat, name] of techPatterns) {
+            if (pat.test(allText))
+                techStack.push(name);
+        }
+        // Detect intelligence/ML requirements
+        const intelligenceReqs = detectIntelligenceRequirements(query);
+        let intelligenceGuidance = '';
+        if (intelligenceReqs.hasIntelligence) {
+            intelligenceGuidance = '\n=== INTELLIGENCE/ML REQUIREMENTS ===\n' +
+                `Detected keywords: ${intelligenceReqs.keywords.join(', ')}\n` +
+                'The following intelligence contexts MUST be included in the architecture:\n' +
+                intelligenceReqs.suggestedContexts.map(c => `- ${c.name} (${c.type}): ${c.description}\n  Commands: ${c.commands.join(', ')}\n  NOTE: This is NOT a CRUD context. It must contain ML/analytics logic, not Create/Update/Delete operations.`).join('\n') +
+                '\n\nCRITICAL: Intelligence contexts must have commands like TrainModel, RunInference, DetectAnomalies — NOT generic Create*, Update*, Delete*.\n';
+        }
+        const prompt = `You are a senior enterprise architect creating a complete SPARC architecture document.\n` +
+            `\nSPARC is a high-level architecture methodology with 5 sections: Specification, Pseudocode, Architecture, Refinement, Completion.\n` +
+            `Each section must be DEEPLY domain-specific — not generic templates.\n` +
+            `\n=== PROJECT ===\n${query}\n` +
+            `\n=== TECHNOLOGY STACK ===\n${techStack.join(', ') || 'To be determined based on domain requirements'}\n` +
+            `\n=== PROJECT CONTEXT ===\n${projectContext.slice(0, 3000)}\n` +
+            `\n=== RESEARCH FINDINGS (${dossier.items.length} items from 110 agents) ===\n${dossierItems}\n` +
+            (agentContext ? `\n${agentContext}` : '') +
+            (intelligenceGuidance ? `\n${intelligenceGuidance}` : '') +
+            `\n=== DOMAIN SERVICES ===\n${servicesList}\n` +
+            `\nWrite the COMPLETE SPARC document with these 5 sections. Use the section headers EXACTLY as shown:\n` +
+            `\n# Specification\n` +
+            `Deep domain analysis: goals and motivation, supported features/model classes, specific performance/latency/memory targets with numbers, ` +
+            `compatibility and integration requirements with actual system APIs (e.g. real SAP API names, real Snowflake SQL interfaces). ` +
+            `Include functional requirements with acceptance criteria, non-functional requirements with specific numbers, ` +
+            `stakeholder roles specific to this domain (not generic "Employees"), and system integration details.\n` +
+            `\n# Pseudocode\n` +
+            `High-level pseudocode showing the ACTUAL algorithms, data structures, and control flow. ` +
+            `Include typed struct/class definitions with real field names and types. ` +
+            `Show function signatures with typed parameters. Show the REAL business logic — calculations, validations, decision trees, state machines. ` +
+            `NOT generic "validate_input → process → persist" templates. ` +
+            `Use \`\`\`pseudocode blocks for code.\n` +
+            `\n# Architecture\n` +
+            `System architecture: component design, data flow diagrams, module interactions, technology stack decisions with rationale. ` +
+            `Include crate/package organization, backend implementations, data models and schemas, ` +
+            `key architectural patterns (why microservices vs monolith, why event sourcing vs CRUD, etc.), ` +
+            `scalability strategy, security architecture, and integration architecture with actual external system APIs.\n` +
+            `\n# Refinement\n` +
+            `Optimization and hardening: quantization/performance support, format compatibility details, ` +
+            `fallback strategies, SIMD/parallel optimizations, memory layout, cache locality, ` +
+            `quality vs performance trade-offs with specific tuning parameters, security hardening, ` +
+            `edge case handling specific to this domain.\n` +
+            `\n# Completion\n` +
+            `Integration plan: how components connect end-to-end, testing plan (unit/integration/e2e with domain-specific test cases), ` +
+            `benchmark targets with specific numbers, deployment strategy, monitoring and observability, ` +
+            `model/system-specific adjustments, post-deployment validation.\n` +
+            `\nCRITICAL RULES:\n` +
+            `1. Every section must be DEEPLY domain-specific to "${query.slice(0, 100)}"\n` +
+            `2. Include REAL API names, REAL data structures, REAL algorithms — not placeholders\n` +
+            `3. Pseudocode must have typed structs and real function logic, not "validate→execute→persist"\n` +
+            `4. Architecture must describe actual component interactions, not "User → API → DB"\n` +
+            `5. Use the research findings and agent analysis above as your primary source of domain knowledge\n` +
+            `6. Each section should be 500-2000 words of substantive content\n` +
+            `7. This is a HIGH-LEVEL ARCHITECTURE document — not a process description`;
+        const result = runner.invoke(prompt, {
+            runId: `sparc-complete-${Date.now()}`,
+            timeoutMs: 300_000, // 5 minutes for comprehensive document
+        });
+        const data = result.data;
+        const content = typeof data.content === 'string' ? data.content : '';
+        // Validate: must have all 5 sections and substantial content
+        if (content.length < 3000) {
+            process.stderr.write(`[sparc] Complete SPARC too short (${content.length} chars), falling back\n`);
+            return null;
+        }
+        const hasSections = ['# Specification', '# Pseudocode', '# Architecture', '# Refinement', '# Completion']
+            .every(h => content.includes(h));
+        if (!hasSections) {
+            process.stderr.write('[sparc] Complete SPARC missing sections, falling back\n');
+            return null;
+        }
+        process.stderr.write(`[sparc] LLM-generated complete SPARC: ${content.length} chars in ${result.durationMs}ms\n`);
+        return content;
+    }
+    catch (err) {
+        process.stderr.write(`[sparc] Complete SPARC generation failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/**
+ * Split a complete SPARC document into its 5 sections.
+ * Looks for "# Specification", "# Pseudocode", "# Architecture", "# Refinement", "# Completion"
+ * as top-level headers.
+ */
+function splitSPARCSections(fullDoc) {
+    const sectionPattern = /^# (Specification|Pseudocode|Architecture|Refinement|Completion)\b/gm;
+    const positions = [];
+    let match;
+    while ((match = sectionPattern.exec(fullDoc)) !== null) {
+        const sectionName = match[1];
+        if (sectionName) {
+            positions.push({ name: sectionName.toLowerCase(), start: match.index });
+        }
+    }
+    const extract = (name) => {
+        const idx = positions.findIndex(p => p.name === name);
+        if (idx === -1)
+            return `# ${name.charAt(0).toUpperCase() + name.slice(1)}\n\n(Section not generated)`;
+        const pos = positions[idx];
+        const nextPos = idx + 1 < positions.length ? positions[idx + 1] : undefined;
+        const end = nextPos ? nextPos.start : fullDoc.length;
+        return fullDoc.slice(pos.start, end).trim();
+    };
+    return {
+        specification: extract('specification'),
+        pseudocode: extract('pseudocode'),
+        architecture: extract('architecture'),
+        refinement: extract('refinement'),
+        completion: extract('completion'),
+    };
+}
 /** Gather all textual content from Phase 1 artifacts into a single context blob. */
 function gatherProjectContext(artifacts) {
     const parts = [];
@@ -106,7 +418,64 @@ function summarizeDossier(dossier) {
 // Each function writes a SPARC phase document driven entirely by the user's
 // query and collected artifacts. No hardcoded patterns.
 // ============================================================================
-function writeSpecificationMarkdown(query, projectContext, _dossierSummary, dossier) {
+function writeSpecificationMarkdown(query, projectContext, _dossierSummary, dossier, phase2Dir = '') {
+    // ADR-027: Try LLM-generated specification first
+    const llmSpec = tryGenerateLLMSpecification(query, projectContext, dossier, phase2Dir);
+    if (llmSpec)
+        return llmSpec;
+    // Fallback: deterministic bullet-point format
+    return writeTemplateSpecification(query, projectContext, dossier);
+}
+/**
+ * ADR-027: Generate a real specification using Claude.
+ * Derives functional requirements, acceptance criteria, stakeholder analysis,
+ * and non-functional requirements from the domain — not just bullet-pointing the dossier.
+ */
+function tryGenerateLLMSpecification(query, projectContext, dossier, phase2Dir = '') {
+    try {
+        const runner = createClaudeCodeRunner();
+        const dossierItems = dossier.items.slice(0, 30)
+            .map(i => `- [${i.category}] ${i.title}: ${i.content.slice(0, 150)}`)
+            .join('\n');
+        // ADR-027: Include agentics fleet analysis from 110 agents
+        const agentContext = phase2Dir ? loadAgenticsFleetContext(phase2Dir) : '';
+        const prompt = `You are a senior business analyst writing a functional specification.\n` +
+            `\nPROJECT: ${query}\n` +
+            `\nPROJECT CONTEXT:\n${projectContext.slice(0, 2000)}\n` +
+            `\nRESEARCH FINDINGS:\n${dossierItems}\n` +
+            (agentContext ? agentContext + '\n' : '') +
+            `\nWrite a complete "Specification" markdown document with these sections:\n` +
+            `\n# Specification\n` +
+            `## Objective - What this system does and why\n` +
+            `## Stakeholders & Actors - Real roles (e.g., Trader, Risk Manager, Compliance Officer, IT Admin) with their needs — NOT generic "Employees"\n` +
+            `## Functional Requirements - Numbered, testable requirements with acceptance criteria. Each requirement must be specific enough to write a test for.\n` +
+            `## Non-Functional Requirements - Performance targets (specific numbers), security requirements, compliance requirements, scalability targets\n` +
+            `## System Integrations - Specific systems to integrate with, actual API surfaces, data flows, authentication methods\n` +
+            `## Domain Model Overview - Key entities with their attributes and relationships (typed fields, not generic)\n` +
+            `## Risk Factors - Domain-specific risks with severity and mitigation strategies\n` +
+            `## Success Criteria - Measurable outcomes that determine project success\n` +
+            `## Assumptions & Constraints\n` +
+            `## Reflection - Summary of specification coverage\n` +
+            `\nCRITICAL: Derive REAL requirements from the domain. Do NOT just reformat the research findings as bullet points. Each requirement must be specific, testable, and include acceptance criteria.`;
+        const result = runner.invoke(prompt, {
+            runId: `sparc-spec-${Date.now()}`,
+            timeoutMs: 180_000,
+        });
+        const data = result.data;
+        const content = typeof data.content === 'string' ? data.content : '';
+        if (content.length > 500) {
+            process.stderr.write(`[sparc-specification] LLM-generated specification: ${content.length} chars in ${result.durationMs}ms\n`);
+            return content;
+        }
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`[sparc-specification] LLM spec failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/** Fallback: deterministic specification from dossier items. */
+function writeTemplateSpecification(query, projectContext, dossier) {
     const requirements = dossier.items.filter(i => i.category === 'requirement' || i.category === 'recommendation');
     const constraints = dossier.items.filter(i => i.category === 'constraint');
     const risks = dossier.items.filter(i => i.category === 'risk');
@@ -176,15 +545,99 @@ function writeSpecificationMarkdown(query, projectContext, _dossierSummary, doss
     lines.push('');
     return lines.join('\n');
 }
-function writePseudocodeMarkdown(query, _context, dossier, artifacts) {
+function writePseudocodeMarkdown(query, _context, dossier, artifacts, phase2Dir = '') {
+    // Derive modules from DOMAIN services (not roadmap phases)
+    const domainServices = extractDomainServices(query, artifacts, dossier);
+    // ADR-027 Change 1: Try LLM-generated domain-specific pseudocode first
+    const llmResult = tryGenerateLLMPseudocode(query, domainServices, dossier, phase2Dir);
+    if (llmResult)
+        return llmResult;
+    // Fallback: deterministic template (original behavior pre-ADR-027)
+    return writeTemplatePseudocode(query, domainServices);
+}
+/**
+ * ADR-027 Change 1: Generate domain-specific pseudocode using Claude Code LLM.
+ *
+ * Instead of the generic validate→execute→persist template, Claude generates
+ * pseudocode with domain-specific typed data structures, real algorithms,
+ * business rules, and integration points.
+ *
+ * @returns Pseudocode markdown string, or null if LLM is unavailable/fails.
+ */
+function tryGenerateLLMPseudocode(query, services, dossier, phase2Dir = '') {
+    try {
+        const runner = createClaudeCodeRunner();
+        // Build dossier context (limit to avoid prompt overflow)
+        const relevantItems = dossier.items
+            .filter(i => ['requirement', 'recommendation', 'decision-rationale', 'constraint'].includes(i.category))
+            .slice(0, 25);
+        const dossierContext = relevantItems
+            .map(i => `- [${i.category}] ${i.title}: ${i.content.slice(0, 200)}`)
+            .join('\n');
+        // ADR-027: Include agentics fleet analysis from 110 agents
+        const agentContext = phase2Dir ? loadAgenticsFleetContext(phase2Dir) : '';
+        const servicesList = services.map(svc => `### ${svc.name}\n- Responsibility: ${svc.responsibility}\n- Capabilities: ${svc.capabilities.join(', ')}\n- Related systems: ${svc.relatedSystems.join(', ') || 'none'}`).join('\n\n');
+        const prompt = `You are a senior domain engineer writing detailed pseudocode for an enterprise system.\n` +
+            `\nDOMAIN: ${query}\n` +
+            `\nRESEARCH FINDINGS:\n${dossierContext}\n` +
+            (agentContext ? agentContext + '\n' : '') +
+            `\nSERVICES TO IMPLEMENT:\n${servicesList}\n` +
+            `\nWrite a complete pseudocode document in markdown. For EACH service above, write:\n` +
+            `1. Domain-specific data structures with typed fields (string, number, boolean, Date, enums)\n` +
+            `2. Functions with typed parameters implementing REAL domain algorithms\n` +
+            `3. Domain-specific error handling and validation\n` +
+            `4. Business rules, calculations, and decision logic specific to this domain\n` +
+            `\nCRITICAL: Do NOT write generic templates like "validate_preconditions(input) -> aggregate.execute(input) -> persist(aggregate)". Every function must contain domain-specific logic with real typed parameters.\n` +
+            `\nFormat: Start with "# Pseudocode" then "## Objective" describing the domain, then a "## [Service Name] Service" section per service with \`\`\`pseudocode blocks containing typed structs and functions. End with "## Reflection" summarizing coverage.\n` +
+            `\nExample of GOOD pseudocode for a maintenance domain (write for YOUR domain, not this):\n` +
+            `\`\`\`pseudocode\n` +
+            `struct MaintenanceOrder:\n` +
+            `    order_id: string\n` +
+            `    aircraft_registration: string\n` +
+            `    task_type: enum(scheduled|unscheduled|deferred)\n` +
+            `    priority: enum(AOG|urgent|routine)\n` +
+            `    estimated_labor_hours: number\n` +
+            `    parts_required: PartRequirement[]\n` +
+            `\n` +
+            `function create_maintenance_order(reg: string, task: TaskType, findings: InspectionFinding[]):\n` +
+            `    aircraft = lookup_aircraft(reg)\n` +
+            `    if aircraft.status == "retired": return AircraftRetiredError(reg)\n` +
+            `    priority = assess_priority(findings, aircraft.next_flight_time)\n` +
+            `    parts = calculate_required_parts(findings, aircraft.type_certificate)\n` +
+            `    labor = estimate_labor_hours(findings, aircraft.maintenance_history)\n` +
+            `    order = MaintenanceOrder(generate_id(), reg, task, priority, labor, parts)\n` +
+            `    if priority == AOG: notify_ops_control(aircraft, order)\n` +
+            `    persist(order)\n` +
+            `    emit_event("maintenance.order.created", order)\n` +
+            `    return order\n` +
+            `\`\`\``;
+        const result = runner.invoke(prompt, {
+            runId: `sparc-pseudo-${Date.now()}`,
+            timeoutMs: 180_000, // 3 minutes for comprehensive pseudocode
+        });
+        // Extract content from unwrapped Claude Code envelope
+        const data = result.data;
+        const content = typeof data.content === 'string' ? data.content : '';
+        if (content.length > 300) {
+            process.stderr.write(`[sparc-specification] LLM-generated pseudocode: ${content.length} chars in ${result.durationMs}ms\n`);
+            return content;
+        }
+        process.stderr.write('[sparc-specification] LLM returned insufficient pseudocode, using template fallback\n');
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`[sparc-specification] LLM pseudocode generation failed, using template fallback: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/** Fallback: deterministic pseudocode template (pre-ADR-027 behavior). */
+function writeTemplatePseudocode(query, domainServices) {
     const lines = [];
     lines.push('# Pseudocode');
     lines.push('');
     lines.push('## Objective');
     lines.push(`Create a pseudocode outline for each domain service: **${query}**`);
     lines.push('');
-    // Derive modules from DOMAIN services (not roadmap phases)
-    const domainServices = extractDomainServices(query, artifacts, dossier);
     for (const svc of domainServices) {
         const title = svc.name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
         lines.push(`## ${title} Service`);
@@ -637,6 +1090,24 @@ function extractDomainServices(query, artifacts, dossier) {
             }
         }
     }
+    // 9. ADR-029 Fix 4: Add intelligence/ML services when query requires them
+    const intelligenceReqs = detectIntelligenceRequirements(query);
+    if (intelligenceReqs.hasIntelligence) {
+        for (const ctx of intelligenceReqs.suggestedContexts) {
+            // Only add if not already covered by an existing service
+            const alreadyExists = Array.from(services.values()).some(s => s.name.toLowerCase().includes(ctx.name.split('-')[0]) ||
+                ctx.name.includes(s.name.toLowerCase()));
+            if (!alreadyExists) {
+                services.set(ctx.name, {
+                    name: ctx.name,
+                    responsibility: ctx.description,
+                    capabilities: ctx.commands,
+                    relatedSystems: [],
+                    dossierItemRefs: [],
+                });
+            }
+        }
+    }
     return Array.from(services.values()).slice(0, 12);
 }
 // ============================================================================
@@ -832,12 +1303,31 @@ export async function generateSPARCSpecification(context) {
         // Gather project context from all artifacts
         const projectContext = gatherProjectContext(context.phase1Artifacts);
         const dossierSummary = summarizeDossier(dossier);
-        // Build 5 SPARC markdown documents
-        const specMd = writeSpecificationMarkdown(query, projectContext, dossierSummary, dossier);
-        const pseudoMd = writePseudocodeMarkdown(query, projectContext, dossier, context.phase1Artifacts);
-        const archMd = writeArchitectureMarkdown(query, projectContext, dossier, context.phase1Artifacts);
-        const refineMd = writeRefinementMarkdown(query, projectContext, dossier);
-        const completionMd = writeCompletionMarkdown(query, projectContext, dossier, context.phase1Artifacts);
+        // ADR-027: Try single comprehensive LLM SPARC generation first
+        // SPARC is ONE cohesive architecture document, not 5 disconnected fragments
+        const llmSparc = tryGenerateCompleteSPARC(query, projectContext, dossier, context.phase1Artifacts, context.phase2Dir);
+        let specMd;
+        let pseudoMd;
+        let archMd;
+        let refineMd;
+        let completionMd;
+        if (llmSparc) {
+            // LLM generated the full SPARC — split into sections
+            const sections = splitSPARCSections(llmSparc);
+            specMd = sections.specification;
+            pseudoMd = sections.pseudocode;
+            archMd = sections.architecture;
+            refineMd = sections.refinement;
+            completionMd = sections.completion;
+        }
+        else {
+            // Fallback: individual LLM calls per section, then template fallback
+            specMd = writeSpecificationMarkdown(query, projectContext, dossierSummary, dossier, context.phase2Dir);
+            pseudoMd = writePseudocodeMarkdown(query, projectContext, dossier, context.phase1Artifacts, context.phase2Dir);
+            archMd = writeArchitectureMarkdown(query, projectContext, dossier, context.phase1Artifacts);
+            refineMd = writeRefinementMarkdown(query, projectContext, dossier);
+            completionMd = writeCompletionMarkdown(query, projectContext, dossier, context.phase1Artifacts);
+        }
         // Build JSON compat shim
         const sparc = buildCompatJSON(dossier, context.phase1Artifacts);
         // Write files