@llm-dev-ops/agentics-cli 1.7.2 → 1.8.0

package/dist/synthesis/simulation-renderers.js

@@ -73,6 +73,24 @@ export function computeFleetMetrics(results) {
 // ============================================================================
 // Extract signal payload from nested agent response
 // ============================================================================
+/**
+ * ADR-PIPELINE-033: Extract simulation and trace IDs for decision lineage.
+ * These IDs create an auditable chain from recommendation back to the analysis.
+ */
+function extractSimulationLineage(simulationResult) {
+    const payload = extractSignalPayload(simulationResult);
+    const data = payload.data ?? {};
+    const simId = safeString(data, 'simulation_id')
+        || safeString(data, 'execution_id')
+        || safeString(data, 'id')
+        || safeString(data, 'sim_id')
+        || '';
+    const traceId = safeString(data, 'trace_id')
+        || safeString(data, 'correlation_id')
+        || safeString(data, 'run_id')
+        || '';
+    return { simulationId: simId, traceId };
+}
 function extractSignalPayload(response) {
     // Agent responses often have: { signal: { payload: { type, data } } }
     const signalPayload = safeGet(response, 'signal', 'payload');
@@ -232,14 +250,18 @@ export function synthesizeFinancials(simData, platformResults, query) {
  * All clearly labeled as estimates.
  */
 function estimateFinancialsFromQuery(query) {
-    // Extract employee count — simple string search, no regex
-    let employees = 10000;
     const lower = query.toLowerCase();
+    const fmt = (n) => n >= 1_000_000 ? `$${(n / 1_000_000).toFixed(1)}M` : `$${(n / 1000).toFixed(0)}K`;
+    // ── ADR-PIPELINE-029 §2: Try domain-specific bottom-up model first ──
+    const domainModel = tryDomainSpecificFinancials(query, lower);
+    if (domainModel)
+        return domainModel;
+    // ── Fallback: per-employee heuristic with visible methodology ──
+    let employees = 10000;
     const empIdx = lower.indexOf('employees');
     const staffIdx = lower.indexOf('staff');
     const targetIdx = empIdx !== -1 ? empIdx : staffIdx;
     if (targetIdx > 5) {
-        // Walk backward from "employees" to find the number
         const before = query.substring(Math.max(0, targetIdx - 30), targetIdx).trim();
         const words = before.split(/\s+/);
         for (let i = words.length - 1; i >= 0; i--) {
@@ -251,14 +273,16 @@ function estimateFinancialsFromQuery(query) {
             }
         }
     }
-    // Industry affects per-employee costs and savings multiplier
-    const isPharma = lower.includes('pharma') || lower.includes('drug') || lower.includes('gxp') || lower.includes('clinical');
+    // Industry detection
+    const isPharma = lower.includes('pharma') || lower.includes('drug') || lower.includes('gxp');
     const isFinancial = lower.includes('financial') || lower.includes('banking') || lower.includes('insurance');
     const isRetail = lower.includes('retail') || lower.includes('grocery') || lower.includes('store');
-    const isUtility = lower.includes('water') || lower.includes('utility') || lower.includes('energy') || lower.includes('grid') || lower.includes('distribution');
+    const isUtility = lower.includes('water') || lower.includes('utility') || lower.includes('energy') || lower.includes('grid');
+    const isHealthcare = lower.includes('healthcare') || lower.includes('hospital') || lower.includes('patient');
     const isSustainability = lower.includes('sustainability') || lower.includes('emissions') || lower.includes('carbon') || lower.includes('esg');
-    const isHealthcare = lower.includes('healthcare') || lower.includes('hospital') || lower.includes('clinical') || lower.includes('patient');
     const isProfessionalServices = lower.includes('professional services') || lower.includes('consulting') || lower.includes('advisory');
+    const isManufacturing = lower.includes('manufacturing') || lower.includes('factory') || lower.includes('production line');
+    const isConsumerGoods = lower.includes('consumer goods') || lower.includes('cpg') || lower.includes('fmcg') || lower.includes('packaging');
     let industryLabel = 'enterprise';
     let costPerEmployee = 25;
     let savingsMultiplier = 50;
@@ -280,25 +304,38 @@ function estimateFinancialsFromQuery(query) {
     else if (isUtility) {
         costPerEmployee = 20;
         savingsMultiplier = 55;
-        industryLabel = 'utility';
+        industryLabel = 'utility infrastructure';
     }
     else if (isHealthcare) {
         costPerEmployee = 30;
         savingsMultiplier = 65;
         industryLabel = 'healthcare';
     }
-    else if (isSustainability || isProfessionalServices) {
+    else if (isManufacturing) {
+        costPerEmployee = 22;
+        savingsMultiplier = 55;
+        industryLabel = 'manufacturing';
+    }
+    else if (isConsumerGoods) {
+        costPerEmployee = 20;
+        savingsMultiplier = 45;
+        industryLabel = 'consumer goods';
+    }
+    else if (isSustainability) {
         costPerEmployee = 25;
         savingsMultiplier = 50;
-        industryLabel = isSustainability ? 'sustainability' : 'professional services';
+        industryLabel = 'sustainability';
+    }
+    else if (isProfessionalServices) {
+        costPerEmployee = 25;
+        savingsMultiplier = 50;
+        industryLabel = 'professional services';
     }
     const pilotCost = Math.round(employees * costPerEmployee / 1000) * 1000;
     const annualSavings = Math.round(employees * savingsMultiplier / 1000) * 1000;
     const paybackMonths = Math.max(6, Math.min(24, Math.round(pilotCost / (annualSavings / 12))));
-    const npv5yr = Math.round(annualSavings * 3.5); // ~10% discount rate, 5 years
+    const npv5yr = Math.round(annualSavings * 3.5);
     const roiPct = Math.round((annualSavings / pilotCost) * 100);
-    const fmt = (n) => n >= 1_000_000 ? `$${(n / 1_000_000).toFixed(1)}M` : `$${(n / 1000).toFixed(0)}K`;
-    // Build methodology string so the numbers are defensible
     const methodology = `${employees.toLocaleString()} employees × $${costPerEmployee}/employee ${industryLabel} benchmark`;
     const savingsMethod = `${employees.toLocaleString()} employees × $${savingsMultiplier}/employee annual efficiency gain`;
     return {
@@ -312,6 +349,156 @@ function estimateFinancialsFromQuery(query) {
         isEstimated: true,
     };
 }
+/**
+ * ADR-PIPELINE-029 §2: Domain-specific bottom-up financial models.
+ * These use query signals to build unit-economics-based estimates
+ * rather than generic per-employee heuristics.
+ *
+ * Returns null if no domain-specific model applies — caller falls back
+ * to per-employee heuristic.
+ */
+function tryDomainSpecificFinancials(query, lower) {
+    const fmt = (n) => n >= 1_000_000 ? `$${(n / 1_000_000).toFixed(1)}M` : `$${(n / 1000).toFixed(0)}K`;
+    const employees = extractEmployeeCount(query, lower);
+    // ── Packaging / Supplier Waste ──
+    if (/packag|supplier.*waste|excess.*material|supplier.*sustainab/i.test(lower)) {
+        // Bottom-up: suppliers × avg excess rate × cost per shipment × annual volume
+        const supplierMatch = lower.match(/(\d+)[,.]?\d*\s*(?:suppliers?|vendors?)/);
+        const supplierCount = supplierMatch ? parseInt(supplierMatch[1], 10) : estimateSupplierCount(employees);
+        const avgExcessRate = 0.18; // 18% industry average excess packaging
+        const avgCostPerShipment = 4.50; // avg packaging cost per shipment, USD
+        const annualShipmentsPerSupplier = 2400; // ~200/month
+        const totalShipments = supplierCount * annualShipmentsPerSupplier;
+        const addressableWaste = totalShipments * avgExcessRate * avgCostPerShipment;
+        const achievableReduction = 0.35; // 35% of addressable waste through optimization
+        const annualSavings = Math.round(addressableWaste * achievableReduction / 1000) * 1000;
+        const implCost = Math.round(Math.max(200000, annualSavings * 0.6) / 1000) * 1000;
+        const roiPct = Math.round((annualSavings / implCost) * 100);
+        const paybackMonths = Math.max(6, Math.min(18, Math.round(implCost / (annualSavings / 12))));
+        const methodology = `${supplierCount} suppliers × ${(annualShipmentsPerSupplier).toLocaleString()} shipments/yr × ` +
+            `${(avgExcessRate * 100).toFixed(0)}% excess rate × $${avgCostPerShipment.toFixed(2)}/shipment × ` +
+            `${(achievableReduction * 100).toFixed(0)}% achievable reduction`;
+        return {
+            budget: `${fmt(implCost)} - ${fmt(implCost * 1.4)} (implementation + ${supplierCount}-supplier rollout)`,
+            roi: `${roiPct}% projected (${fmt(annualSavings)} annual savings ÷ ${fmt(implCost)} investment; ${methodology})`,
+            npv: `${fmt(Math.round(annualSavings * 3.5))} 5-year NPV (10% discount rate, ${fmt(addressableWaste)} total addressable waste)`,
+            payback: `${paybackMonths}-${paybackMonths + 4} months (break-even at ${Math.round(achievableReduction * avgExcessRate * 100)}% packaging reduction)`,
+            revenue: `${fmt(annualSavings)} annual waste reduction savings (${methodology})`,
+            costSavings: `${fmt(addressableWaste)} total addressable packaging waste annually`,
+            hasData: true,
+            isEstimated: true,
+        };
+    }
+    // ── Water Loss / Utility Network ──
+    if (/water\s*loss|non.?revenue\s*water|leak|pipe.*aging|distribution\s*network/i.test(lower)) {
+        // Bottom-up: system volume × loss rate × water cost × achievable reduction
+        const popMatch = lower.match(/(\d+)[,.]?\d*\s*(?:customer|connection|household|meter)/);
+        const customers = popMatch ? parseInt(popMatch[1], 10) : Math.round(employees * 4.5); // ~4.5 customers per employee
+        const avgDailyVolumeM3 = customers * 0.4; // 400 liters/customer/day
+        const lossRate = 0.22; // 22% industry average NRW
+        const waterCostPerM3 = 1.85;
+        const dailyLossM3 = avgDailyVolumeM3 * lossRate;
+        const annualLossCost = dailyLossM3 * 365 * waterCostPerM3;
+        const achievableReduction = 0.30; // 30% of losses through targeted intervention
+        const annualSavings = Math.round(achievableReduction * annualLossCost / 1000) * 1000;
+        const implCost = Math.round(Math.max(300000, annualSavings * 0.5) / 1000) * 1000;
+        const roiPct = Math.round((annualSavings / implCost) * 100);
+        const paybackMonths = Math.max(6, Math.min(18, Math.round(implCost / (annualSavings / 12))));
+        const methodology = `${customers.toLocaleString()} connections × ${(lossRate * 100).toFixed(0)}% NRW rate × ` +
+            `$${waterCostPerM3}/m³ × ${(achievableReduction * 100).toFixed(0)}% achievable reduction`;
+        return {
+            budget: `${fmt(implCost)} - ${fmt(implCost * 1.4)} (AI platform + sensor integration for ${customers.toLocaleString()} connections)`,
+            roi: `${roiPct}% projected (${fmt(annualSavings)} annual water savings ÷ ${fmt(implCost)} investment; ${methodology})`,
+            npv: `${fmt(Math.round(annualSavings * 3.5))} 5-year NPV (10% discount rate, ${fmt(annualLossCost)} annual water loss cost)`,
+            payback: `${paybackMonths}-${paybackMonths + 4} months (break-even at ${Math.round(achievableReduction * lossRate * 100)}% loss reduction)`,
+            revenue: `${fmt(annualSavings)} annual water loss reduction (${methodology})`,
+            costSavings: `${fmt(annualLossCost)} total addressable water loss cost annually`,
+            hasData: true,
+            isEstimated: true,
+        };
+    }
+    // ── Travel / Emissions / Sustainability ──
+    if (/travel.*emission|carbon.*footprint|sustainab.*travel|business\s*travel.*reduc|commut.*emission/i.test(lower)) {
+        // Bottom-up: travelers × avg trips × emissions per trip × carbon cost × achievable reduction
+        const travelerPct = 0.35; // 35% of employees are business travelers
+        const travelers = Math.round(employees * travelerPct);
+        const avgTripsPerYear = 6;
+        const avgEmissionsPerTripKg = 850; // kg CO2e (mix of domestic + international)
+        const carbonPricePerTonne = 75; // $/tonne CO2e (social cost of carbon)
+        const avgTripCost = 2200; // $ per trip
+        const totalEmissionsKg = travelers * avgTripsPerYear * avgEmissionsPerTripKg;
+        const totalTravelCost = travelers * avgTripsPerYear * avgTripCost;
+        const achievableReduction = 0.25; // 25% through virtual-first + rail substitution
+        const emissionsSavingsKg = totalEmissionsKg * achievableReduction;
+        const travelCostSavings = totalTravelCost * achievableReduction * 0.6; // 60% cost recovery (some virtual, some rail)
+        const carbonValueSavings = (emissionsSavingsKg / 1000) * carbonPricePerTonne;
+        const annualSavings = Math.round((travelCostSavings + carbonValueSavings) / 1000) * 1000;
+        const implCost = Math.round(Math.max(200000, annualSavings * 0.4) / 1000) * 1000;
+        const roiPct = Math.round((annualSavings / implCost) * 100);
+        const paybackMonths = Math.max(4, Math.min(14, Math.round(implCost / (annualSavings / 12))));
+        const methodology = `${travelers.toLocaleString()} travelers × ${avgTripsPerYear} trips/yr × ` +
+            `${avgEmissionsPerTripKg} kg CO2e/trip × ${(achievableReduction * 100).toFixed(0)}% reduction`;
+        return {
+            budget: `${fmt(implCost)} - ${fmt(implCost * 1.3)} (platform + integration with travel/expense systems)`,
+            roi: `${roiPct}% projected (${fmt(annualSavings)} combined savings ÷ ${fmt(implCost)} investment; ${methodology})`,
+            npv: `${fmt(Math.round(annualSavings * 3.5))} 5-year NPV (10% discount rate, ${fmt(travelCostSavings)} travel + ${fmt(carbonValueSavings)} carbon value)`,
+            payback: `${paybackMonths}-${paybackMonths + 4} months (${Math.round(emissionsSavingsKg / 1000)} tonnes CO2e/yr reduction)`,
+            revenue: `${fmt(annualSavings)} annual combined savings (${fmt(travelCostSavings)} travel cost + ${fmt(carbonValueSavings)} carbon value at $${carbonPricePerTonne}/tonne)`,
+            costSavings: `${Math.round(emissionsSavingsKg / 1000).toLocaleString()} tonnes CO2e annual reduction (${methodology})`,
+            hasData: true,
+            isEstimated: true,
+        };
+    }
+    // ── Procurement / Supplier Management ──
+    if (/procurement.*optim|supplier.*manag|spend.*analy|purchas.*order|sourcing/i.test(lower)) {
+        const spendPct = 0.40; // 40% of revenue typically goes to procurement
+        const estimatedRevenue = employees * 150000; // rough revenue/employee
+        const totalSpend = estimatedRevenue * spendPct;
+        const addressableSpend = totalSpend * 0.30; // 30% of spend is addressable
+        const savingsRate = 0.05; // 5% savings on addressable spend
+        const annualSavings = Math.round(addressableSpend * savingsRate / 1000) * 1000;
+        const implCost = Math.round(Math.max(300000, annualSavings * 0.5) / 1000) * 1000;
+        const roiPct = Math.round((annualSavings / implCost) * 100);
+        const paybackMonths = Math.max(6, Math.min(18, Math.round(implCost / (annualSavings / 12))));
+        const methodology = `${fmt(totalSpend)} est. procurement spend × 30% addressable × 5% optimization rate`;
+        return {
+            budget: `${fmt(implCost)} - ${fmt(implCost * 1.4)} (AI analytics + ERP integration)`,
+            roi: `${roiPct}% projected (${fmt(annualSavings)} savings ÷ ${fmt(implCost)} investment; ${methodology})`,
+            npv: `${fmt(Math.round(annualSavings * 3.5))} 5-year NPV (10% discount rate, ${fmt(addressableSpend)} addressable spend)`,
+            payback: `${paybackMonths}-${paybackMonths + 4} months (break-even at ${(savingsRate * 100).toFixed(1)}% of addressable spend)`,
+            revenue: `${fmt(annualSavings)} annual procurement savings (${methodology})`,
+            costSavings: `${fmt(addressableSpend)} addressable procurement spend annually`,
+            hasData: true,
+            isEstimated: true,
+        };
+    }
+    return null; // No domain-specific model — caller uses per-employee fallback
+}
+/** Extract employee count from query text. Returns default 10000 if not found. */
+function extractEmployeeCount(query, lower) {
+    let employees = 10000;
+    const empIdx = lower.indexOf('employees');
+    const staffIdx = lower.indexOf('staff');
+    const targetIdx = empIdx !== -1 ? empIdx : staffIdx;
+    if (targetIdx > 5) {
+        const before = query.substring(Math.max(0, targetIdx - 30), targetIdx).trim();
+        const words = before.split(/\s+/);
+        for (let i = words.length - 1; i >= 0; i--) {
+            const cleaned = (words[i] ?? '').replace(/,/g, '').replace(/approximately/i, '').trim();
+            const num = parseInt(cleaned, 10);
+            if (num > 100 && num < 10_000_000) {
+                employees = num;
+                break;
+            }
+        }
+    }
+    return employees;
+}
+/** Estimate supplier count from employee count for procurement scenarios. */
+function estimateSupplierCount(employees) {
+    // Rough: 1 active supplier per 50-100 employees for large enterprises
+    return Math.max(20, Math.round(employees / 75));
+}
 // extractFinancials is now synthesizeFinancials — kept as export for external callers
 export { synthesizeFinancials as extractFinancials };
 /**
@@ -366,7 +553,10 @@ function generateDomainRisks(query, extracted) {
     // System-specific data quality risks (not generic)
     const isWorkday = /workday/i.test(q);
     const isSAP = /sap|s\/4hana/i.test(q);
-    const isMaximo = /maximo|ibm/i.test(q);
+    const isMaximo = /maximo|ibm\s+maximo/i.test(q);
+    const isCoupa = /coupa/i.test(q);
+    const isOracle = /oracle\s+(fusion|erp|cloud)/i.test(q);
+    const isNetSuite = /netsuite/i.test(q);
     if (isWorkday) {
         risks.push({
             risk: `Workday custom report and RaaS API data may have field-level gaps — expense categories, cost centers, and worker location data are often inconsistent across regions`,
@@ -403,6 +593,37 @@ function generateDomainRisks(query, extracted) {
             mitigation: 'Confirm Maximo version and OSLC API version during technical spike; build version-aware adapter with feature detection',
         });
     }
+    else if (isCoupa) {
+        risks.push({
+            risk: `Coupa API pagination limits (50 records/page default) and supplier data completeness — custom fields, contract metadata, and sustainability scores may not be populated for all suppliers`,
+            category: 'Data', likelihood: 'High', impact: 'Medium', score: 6,
+            mitigation: 'Audit Coupa object availability during discovery; implement cursor-based pagination with retry; validate supplier field population rates before analysis',
+        });
+        risks.push({
+            risk: `Coupa approval workflow integration — custom approval chains for AI-recommended supplier actions must align with existing procurement approval hierarchies`,
+            category: 'Technical', likelihood: 'Medium', impact: 'High', score: 6,
+            mitigation: 'Map existing Coupa approval workflows during discovery; implement as Coupa custom form or external approval with writeback, not parallel workflow',
+        });
+    }
+    else if (isOracle) {
+        risks.push({
+            risk: `Oracle ERP Cloud REST API versioning — endpoint schemas change between quarterly updates, and custom flex fields require explicit BI publisher configuration`,
+            category: 'Data', likelihood: 'High', impact: 'Medium', score: 6,
+            mitigation: 'Pin to specific Oracle API version; implement schema validation on each response; plan flex field configuration with Oracle admin team',
+        });
+        risks.push({
+            risk: `Oracle ERP Cloud integration security — OAuth2 with JWT assertion flow and fine-grained role requirements for each API endpoint`,
+            category: 'Technical', likelihood: 'Medium', impact: 'High', score: 6,
+            mitigation: 'Technical spike with Oracle admin to configure integration user with minimum required roles; document JWT certificate rotation procedure',
+        });
+    }
+    else if (isNetSuite) {
+        risks.push({
+            risk: `NetSuite SuiteTalk/REST API token-based auth and record-level concurrency — optimistic locking may cause write conflicts during batch sync`,
+            category: 'Technical', likelihood: 'Medium', impact: 'High', score: 6,
+            mitigation: 'Implement retry with exponential backoff for concurrency errors; use RESTlet for custom record operations where SuiteTalk is restrictive',
+        });
+    }
     else {
         risks.push({
             risk: `Data quality and completeness in ${primarySystem} may not meet analytical requirements`,
@@ -451,8 +672,13 @@ function generateDomainRisks(query, extracted) {
             });
         }
     }
-    // Water/utility-specific risks
-    if (/(?:water|pipe|leak|pressure|distribution|meter|flow)/i.test(q)) {
+    // Water/utility-specific risks — require strong water/utility signal to avoid template leakage
+    // "flow" alone can match workflow, "distribution" alone can match supply chain
+    const isWaterDomain = /water\s*(loss|distribution|utility|network|treatment|pipe)/i.test(q)
+        || (/\bpipe\b/i.test(q) && /\b(leak|pressure|aging|infrastructure)\b/i.test(q))
+        || /\bnon.?revenue\s*water\b/i.test(q)
+        || /\bDMA\b/.test(query); // District Metered Area — only appears in water utility context
+    if (isWaterDomain) {
         risks.push({
             risk: 'Sensor data gaps — pressure and flow telemetry may have coverage holes in older distribution zones with limited SCADA instrumentation',
             category: 'Data', likelihood: 'High', impact: 'Medium', score: 6,
@@ -472,6 +698,27 @@ function generateDomainRisks(query, extracted) {
             mitigation: 'Sensitivity analysis on key assumptions; quarterly re-validation of financial model',
         });
     }
+    // Packaging / supplier waste risks
+    if (/(?:packag|supplier.*waste|excess.*material|over.?pack)/i.test(q)) {
+        risks.push({
+            risk: 'Supplier resistance to packaging changes — established suppliers may push back on packaging standard modifications that require retooling or new materials',
+            category: 'Organizational', likelihood: 'Medium', impact: 'High', score: 6,
+            mitigation: 'Phased approach starting with willing suppliers; demonstrate cost savings to incentivize adoption; contractual compliance timelines',
+        });
+        risks.push({
+            risk: 'Product damage from packaging reduction — reducing protective packaging below threshold increases transit damage risk for fragile items',
+            category: 'Operational', likelihood: 'Low', impact: 'High', score: 3,
+            mitigation: 'Category-specific fragility benchmarks; pilot with low-fragility categories first; damage rate monitoring during rollout',
+        });
+    }
+    // Procurement / supplier management risks
+    if (/(?:procurement|supplier.*manag|sourcing|spend.*analy|purchas)/i.test(q)) {
+        risks.push({
+            risk: 'Supplier data quality — supplier master data may have inconsistent categorization, duplicate records, or stale contact information across regions',
+            category: 'Data', likelihood: 'High', impact: 'Medium', score: 6,
+            mitigation: 'Supplier data cleansing sprint during discovery; define minimum data quality thresholds before analysis; flag low-confidence results',
+        });
+    }
     // Always include vendor dependency
     risks.push({
         risk: 'Technology vendor dependency — platform availability, pricing changes, or API deprecation',
@@ -487,6 +734,7 @@ export function renderExecutiveSummary(query, simulationResult, platformResults)
     const now = new Date().toISOString();
     const simPayload = extractSignalPayload(simulationResult);
     const simData = simPayload.data ?? {};
+    const lineage = extractSimulationLineage(simulationResult);
     const successProb = extractSuccessProbability(simData);
     const timeline = safeString(simData, 'timeline_estimate') || safeString(simData, 'timeline') || '12-18 weeks';
     const problemStatement = distillProblemStatement(query);
@@ -604,9 +852,12 @@ export function renderExecutiveSummary(query, simulationResult, platformResults)
         lines.push(step);
     }
     lines.push('');
-    // Provenance
+    // Provenance — ADR-PIPELINE-033: include simulation lineage for decision traceability
     const sources = platformResults.filter(r => r.status >= 200 && r.status < 300).map(r => `${r.domain}/${r.agent}`);
     lines.push('---', '');
+    if (lineage.simulationId) {
+        lines.push(`*Simulation: ${lineage.simulationId}${lineage.traceId ? ` | Trace: ${lineage.traceId}` : ''}*`);
+    }
     lines.push(`*Sources: ${sources.slice(0, 8).join(', ')}${sources.length > 8 ? ` + ${sources.length - 8} more` : ''}*`);
     lines.push(`*Generated: ${now}*`);
     return lines.join('\n');
@@ -616,6 +867,7 @@ export function renderExecutiveSummary(query, simulationResult, platformResults)
 // ============================================================================
 export function renderDecisionMemo(query, simulationResult, platformResults) {
     const now = new Date().toISOString();
+    const lineage = extractSimulationLineage(simulationResult);
     const simPayload = extractSignalPayload(simulationResult);
     const simData = simPayload.data ?? {};
     const successProb = extractSuccessProbability(simData);
@@ -676,7 +928,7 @@ export function renderDecisionMemo(query, simulationResult, platformResults) {
         const fmt = (n) => n >= 1_000_000 ? `$${(n / 1_000_000).toFixed(1)}M` : `$${(n / 1000).toFixed(0)}K`;
         pilotBudget = `${fmt(pilotVal)} - ${fmt(pilotVal * 1.5)}`;
     }
-    lines.push(`| **A. Scoped Pilot** | Validate with subset of data and ${extracted.domain_entities.slice(0, 2).join(', ') || 'core entities'} | ${pilotBudget} | 8-12 weeks | Low | **Recommended** |`, `| **B. Full Deployment** | Enterprise-wide rollout across all ${extracted.systems.length > 0 ? extracted.systems.join(', ') : 'systems'} | ${fullBudget} | ${safeString(simData, 'timeline_estimate') || '16-24 weeks'} | Medium | After pilot validation |`, `| **C. Do Nothing** | Continue with manual processes | $0 | N/A | High | Not recommended — costs compound |`, '');
+    lines.push(`| **A. Scoped Pilot** | Validate with subset of data and ${extracted.domain_entities.slice(0, 2).join(', ') || 'core entities'} | ${pilotBudget} | 8-12 weeks | Low | **Recommended** |`, `| **B. Full Deployment** | Enterprise-wide rollout across all ${extracted.systems.length > 0 ? extracted.systems.join(', ') : 'systems'} | ${fullBudget} | ${safeString(simData, 'timeline_estimate') || '16-24 weeks'} | Medium | After pilot validation |`, `| **C. Do Nothing** | Continue with manual processes | $0 upfront | N/A | High | Not recommended — ${fin.costSavings ? fin.costSavings + ' annual waste continues' : fin.revenue ? fin.revenue + ' in annual savings foregone' : 'costs compound without intervention'} |`, '');
     // Financial Impact
     lines.push('## Financial Impact', '');
     if (fin.hasData) {
@@ -769,9 +1021,12 @@ export function renderDecisionMemo(query, simulationResult, platformResults) {
         lines.push(`| ${row.name} | ${row.role} | ${row.impact} | ${row.action} |`);
     }
     lines.push('');
-    // Provenance
+    // Provenance — ADR-PIPELINE-033: include simulation lineage
     const sources = platformResults.filter(r => r.status >= 200 && r.status < 300).map(r => `${r.domain}/${r.agent}`);
     lines.push('---', '');
+    if (lineage.simulationId) {
+        lines.push(`*Simulation: ${lineage.simulationId}${lineage.traceId ? ` | Trace: ${lineage.traceId}` : ''}*`);
+    }
     lines.push(`*Sources: ${sources.slice(0, 6).join(', ')}${sources.length > 6 ? ` + ${sources.length - 6} more` : ''}*`);
     lines.push(`*Generated: ${now}*`);
     return lines.join('\n');
@@ -860,16 +1115,28 @@ const STAKEHOLDER_PATTERNS = [
     [/\bunion\s*(representative|rep|delegate|leadership)\b/i, 'Union Representatives'],
     // Finance & Procurement
     [/\bfinance\s*(team|department|controller|director|manager)\b/i, 'Finance / CFO'],
-    [/\bprocurement\s*(team|manager|officer)\b/i, 'Procurement'],
+    [/\bprocurement\s*(team|manager|officer|director|lead|head)\b/i, 'Procurement Leadership'],
+    [/\bsupplier\s*(relationship|management)\s*(manager|team|lead)?\b/i, 'Supplier Relationship Management'],
+    [/\bcategory\s*(manager|management|lead)\b/i, 'Category Management'],
+    [/\bpackaging\s*(engineer|team|specialist|manager)\b/i, 'Packaging Engineering'],
+    [/\bsourcing\s*(team|manager|specialist|director)\b/i, 'Strategic Sourcing'],
+    // Sustainability / ESG
+    [/\bsustainability\s*(team|officer|director|manager|lead|vp)\b/i, 'Sustainability Leadership'],
+    [/\besg\s*(team|reporting|officer|analyst|director)\b/i, 'ESG Reporting'],
+    [/\btravel\s*(policy|manager|team|coordinator)\b/i, 'Travel Policy Management'],
+    [/\bcarbon\s*(manager|team|officer|analyst)\b/i, 'Carbon Management'],
+    [/\benvironment(?:al)?\s*(team|officer|manager|director|health|safety)\b/i, 'Environmental Health & Safety'],
     // Governance & Compliance
     [/\bcompliance\s*(team|officer|department|manager)\b/i, 'Compliance & Regulatory Affairs'],
     [/\bregulat(?:ory|or)\s*(affairs|team|compliance|body|bodies|commission)?\b/i, 'Regulatory Affairs'],
     [/\bsecurity\s*(team|officer|department)\b/i, 'Security Team'],
     [/\bauditor[s]?\b/i, 'Auditors'],
+    [/\bquality\s*(assurance|team|manager|engineer|control)\b/i, 'Quality Assurance'],
     // General
     [/\bmanager[s]?\b/i, 'Team Managers'],
     [/\bemployee[s]?\b/i, 'Workforce'],
     [/\bvendor[s]?\b/i, 'External Vendors'],
+    [/\bsupplier[s]?\b/i, 'Suppliers'],
     [/\bcustomer[s]?\b/i, 'Customers / Ratepayers'],
     [/\bstakeholder[s]?\b/i, 'Stakeholders'],
 ];
@@ -1121,37 +1388,69 @@ function extractScenarioFromQuery(query) {
  * capitalizes the first word, and truncates to a readable length.
  */
 function distillProblemStatement(query) {
-    // Remove common preambles and context-setting openings
-    let cleaned = query
-        // Strip "I lead/manage/run..." biographical introductions
-        .replace(/^I\s+(?:lead|manage|run|oversee|am responsible for|work in|head)\s+[^.]+\.\s*/i, '')
-        // Strip "We are a..." / "Our company is..." organizational descriptions
-        .replace(/^(?:We are|Our (?:company|organization|firm|team) is)\s+[^.]+\.\s*/i, '')
-        // Strip "One of the challenges..." problem setup
-        .replace(/^One of the (?:challenges|issues|problems)\s+(?:we face|I face)\s+is\s+/i, '')
-        // Strip standard intent preambles
-        .replace(/^(?:I want to|I'd like to|I need to|We need to|We want to|Please|Can you|Could you)\s+/i, '')
-        .replace(/^(?:build|create|design|develop|implement|generate|make)\s+(?:a\s+|an\s+)?/i, '')
-        .replace(/^(?:working\s+)?prototype\s+(?:for|of|that)\s+/i, '')
-        .replace(/^(?:proof of concept|poc)\s+(?:for|of|that)\s+/i, '')
-        .trim();
-    // If the remaining text still starts with a lowercase conjunction or context word,
-    // try to find the first real problem/goal sentence
+    // ADR-PIPELINE-030 §1: Extract a consulting-grade problem statement.
+    // Strategy: try targeted extraction first, then fall back to stripping.
+    // ── Strategy 1: Extract the core objective directly ──
+    // "We believe AI could help us better understand and reduce unnecessary packaging"
+    // "Ideally, the system would review travel and expense patterns"
+    // These sentences ARE the problem statement — use them directly when found.
+    const objectivePatterns = [
+        /(?:we believe|we think)\s+(?:AI|the system|a system|an AI|this)\s+(?:could|can|would|should|might)\s+(?:help\s+(?:us|the\s+\w+)\s+)?(.{30,250}?)(?:\.\s|$)/i,
+        /(?:ideally),?\s+the\s+system\s+would:?\s*\n?\s*-?\s*(.{20,200}?)(?:\n-|\.\s|$)/i,
+        /(?:the goal|the objective|our goal|our objective)\s+is\s+(?:to\s+)?(.{20,200}?)(?:\.\s|$)/i,
+        /(?:what we want|what we need)\s+(?:is|to)\s+(.{20,200}?)(?:\.\s|$)/i,
+    ];
+    for (const pat of objectivePatterns) {
+        const m = query.match(pat);
+        if (m?.[1]) {
+            let objective = m[1].trim().replace(/[.!?,;:]+$/, '');
+            // Clean leading articles/conjunctions
+            objective = objective.replace(/^(?:to\s+)?(?:better\s+)?/i, '');
+            if (objective.length > 20) {
+                return capitalize(objective).slice(0, 150);
+            }
+        }
+    }
+    // ── Strategy 2: Extract from "One of the challenges..." ──
+    const challengeMatch = query.match(/one of the (?:challenges|issues|problems)\s+(?:we face|I face|they face)\s+is\s+(.{20,250}?)(?:\.\s|$)/i);
+    if (challengeMatch?.[1]) {
+        return capitalize(challengeMatch[1].trim().replace(/[.!?,;:]+$/, '')).slice(0, 150);
+    }
+    // ── Strategy 3: Strip biographical context iteratively ──
+    let cleaned = query;
+    // Keep stripping context sentences until we hit something that isn't biographical
+    const bioPatterns = [
+        /^I\s+(?:lead|manage|run|oversee|am responsible for|work in|head)\s+[^.]+\.\s*/i,
+        /^(?:We are|Our (?:company|organization|firm|team) is)\s+[^.]+\.\s*/i,
+        /^(?:Our|The)\s+(?:finance|HR|procurement|operations|IT|supply chain)[^.]+\.\s*/i,
+        /^(?:We have|We operate|We work with|We serve)\s+[^.]+\.\s*/i,
+        /^(?:This includes|These include|This covers)\s+[^.]+\.\s*/i,
+    ];
+    for (let i = 0; i < 5; i++) { // max 5 biographical sentences
+        let stripped = false;
+        for (const pat of bioPatterns) {
+            if (pat.test(cleaned)) {
+                cleaned = cleaned.replace(pat, '');
+                stripped = true;
+                break;
+            }
+        }
+        if (!stripped)
+            break;
+    }
+    // Strip context-setting sentences
     if (/^(right now|currently|at present|today|however|but|while|although)/i.test(cleaned)) {
-        // Skip the context sentence and find the next one
         const nextSentence = cleaned.replace(/^[^.]+\.\s*/, '');
         if (nextSentence.length > 30)
             cleaned = nextSentence;
     }
-    // Try to extract the core objective from "We believe..." / "Ideally..." / "The system would..."
-    const idealMatch = query.match(/(?:we believe|ideally|the system (?:would|should)|the goal is|the objective is)\s+(.{30,200}?)(?:\.|$)/i);
-    if (idealMatch && idealMatch[1] && cleaned.length > 200) {
-        cleaned = idealMatch[1].trim();
-    }
-    // Capitalize first letter
-    if (cleaned.length > 0) {
-        cleaned = cleaned[0].toUpperCase() + cleaned.slice(1);
-    }
+    // Strip intent preambles
+    cleaned = cleaned
+        .replace(/^(?:I want to|I'd like to|I need to|We need to|We want to|Please|Can you|Could you)\s+/i, '')
+        .replace(/^(?:build|create|design|develop|implement|generate|make)\s+(?:a\s+|an\s+)?/i, '')
+        .replace(/^(?:working\s+)?prototype\s+(?:for|of|that)\s+/i, '')
+        .replace(/^(?:proof of concept|poc)\s+(?:for|of|that)\s+/i, '')
+        .trim();
     // Truncate at sentence boundary if too long
     if (cleaned.length > 150) {
         const boundary = cleaned.lastIndexOf('.', 150);
@@ -1159,13 +1458,17 @@ function distillProblemStatement(query) {
             cleaned = cleaned.slice(0, boundary + 1);
         }
         else {
-            // Truncate at last word boundary
             const truncated = cleaned.slice(0, 150);
             const lastSpace = truncated.lastIndexOf(' ');
             cleaned = (lastSpace > 100 ? truncated.slice(0, lastSpace) : truncated).trim();
         }
     }
-    return cleaned || query.slice(0, 150);
+    return capitalize(cleaned) || query.slice(0, 150);
+}
+function capitalize(text) {
+    if (text.length === 0)
+        return text;
+    return text[0].toUpperCase() + text.slice(1);
 }
 /**
  * Synthesize agent response data into readable prose bullet points.
@@ -1496,6 +1799,7 @@ export function renderFinancialAnalysis(query, simulationResult, platformResults
     const simPayload = extractSignalPayload(simulationResult);
     const simData = simPayload.data ?? {};
     const fin = synthesizeFinancials(simData, platformResults, query);
+    const lineage = extractSimulationLineage(simulationResult);
     const successProb = extractSuccessProbability(simData);
     const extracted = extractScenarioFromQuery(query);
     const roiData = extractAgentData(platformResults, 'costops', 'roi');
@@ -1629,6 +1933,9 @@ export function renderFinancialAnalysis(query, simulationResult, platformResults
     lines.push(`| Optimistic | Faster adoption, lower integration costs | ${optCostStr} | ${fin.roi ? fin.roi.replace(/\d+/, m => String(Math.round(parseInt(m) * 1.3))) : 'Above base'} | 25% |`);
     lines.push(`| Pessimistic | Slower adoption, scope growth | ${pessCostStr} | ${fin.roi ? fin.roi.replace(/\d+/, m => String(Math.round(parseInt(m) * 0.6))) : 'Below base'} | 25% |`);
     lines.push('', '*Scenario analysis assumes ±20% cost variance and ±30% timeline variance from base case.*', '');
+    if (lineage.simulationId) {
+        lines.push(`*Simulation: ${lineage.simulationId}${lineage.traceId ? ` | Trace: ${lineage.traceId}` : ''}*`);
+    }
     lines.push(`*Sources: ${sources.length > 0 ? sources.join(', ') : 'simulation data + industry benchmarks'}*`);
     lines.push(`*Generated: ${now}*`);
     return lines.join('\n');