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

package/dist/pipeline/auto-chain.js

@@ -221,6 +221,102 @@ function mergeRufloCacheIntoPhase(runDir, phaseNum) {
  * Phase 1 artifacts must already exist at ~/.agentics/runs/<traceId>/.
  * Each subsequent phase reads the prior phase's output from the same run directory.
  */
+/**
+ * ADR-PIPELINE-028: Nuclear ADR guarantee. Call before returning from executeAutoChain.
+ * Checks if ADRs exist anywhere in the run directory. If not, generates them from
+ * the scenario query using the template builder (no LLM required).
+ */
+async function ensureAdrsExist(runDir, traceId, scenarioQuery) {
+    if (!scenarioQuery)
+        return;
+    const adrLocations = [
+        path.join(runDir, 'phase4', 'adrs', 'adr-index.json'),
+        path.join(runDir, 'phase2', 'adrs', 'adr-index.json'),
+    ];
+    const hasAdrs = adrLocations.some(p => {
+        try {
+            if (!fs.existsSync(p))
+                return false;
+            const content = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            return Array.isArray(content) && content.length > 0;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (hasAdrs)
+        return;
+    console.error('');
+    console.error('  [ADR-028] No ADRs found — generating guaranteed set');
+    try {
+        const { buildPhase2ADRs } = await import('./phase2/phases/adr-generator.js');
+        const { buildPhase2DDD } = await import('./phase2/phases/ddd-generator.js');
+        // Load SPARC/dossier from any available location, or use empty defaults
+        let sparc = { architecture: { services: [] }, specification: { requirements: [], constraints: [] } };
+        let dossier = { items: [], crossReferences: [], summary: { totalItems: 0, bySource: {}, byCategory: {}, keyRisks: [], criticalConstraints: [] }, id: 'fallback', traceId, generatedFrom: 'adr-028-guarantee' };
+        for (const sub of ['phase3/sparc/sparc-combined.json', 'phase2/sparc/sparc-combined.json', 'phase2/sparc-specification.json']) {
+            const p = path.join(runDir, sub);
+            if (fs.existsSync(p)) {
+                try {
+                    sparc = JSON.parse(fs.readFileSync(p, 'utf-8'));
+                    break;
+                }
+                catch { /* skip */ }
+            }
+        }
+        for (const sub of ['phase2/research-dossier.json', 'research-dossier.json']) {
+            const p = path.join(runDir, sub);
+            if (fs.existsSync(p)) {
+                try {
+                    dossier = JSON.parse(fs.readFileSync(p, 'utf-8'));
+                    break;
+                }
+                catch { /* skip */ }
+            }
+        }
+        const adrs = buildPhase2ADRs(sparc, dossier, scenarioQuery);
+        if (adrs.length === 0)
+            return;
+        // Write to BOTH phase4 and phase2 so downstream consumers find them regardless of which path they check
+        for (const targetDir of [path.join(runDir, 'phase4'), path.join(runDir, 'phase2')]) {
+            const adrDir = path.join(targetDir, 'adrs');
+            fs.mkdirSync(adrDir, { recursive: true });
+            fs.writeFileSync(path.join(adrDir, 'adr-index.json'), JSON.stringify(adrs, null, 2) + '\n', 'utf-8');
+            for (const adr of adrs) {
+                const slug = (adr.title || 'untitled').toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 60);
+                const md = [
+                    `# ${adr.id}: ${adr.title}`,
+                    `\n**Status:** ${adr.status}`,
+                    `**Date:** ${adr.date}`,
+                    `\n## Context\n${adr.context}`,
+                    `\n## Decision\n${adr.decision}`,
+                    adr.alternatives?.length > 0 ? `\n## Alternatives Considered\n${adr.alternatives.map((a) => `- **${a.option}** ${a.rejected ? '(rejected)' : '(selected)'}: ${a.rationale}`).join('\n')}` : '',
+                    adr.consequences?.length > 0 ? `\n## Consequences\n${adr.consequences.map((c) => `- [${c.type === 'positive' ? '+' : c.type === 'negative' ? '-' : '~'}] ${c.description}`).join('\n')}` : '',
+                ].filter(Boolean).join('\n');
+                fs.writeFileSync(path.join(adrDir, `${adr.id}-${slug}.md`), md + '\n', 'utf-8');
+            }
+        }
+        console.error(`  [ADR-028] Generated ${adrs.length} ADRs (phase4/adrs/ + phase2/adrs/)`);
+        // Also generate DDD model
+        try {
+            const dddModel = buildPhase2DDD(sparc, adrs, dossier, scenarioQuery);
+            if (dddModel?.contexts?.length > 0) {
+                for (const targetDir of [path.join(runDir, 'phase4'), path.join(runDir, 'phase2')]) {
+                    const dddDir = path.join(targetDir, 'ddd');
+                    fs.mkdirSync(dddDir, { recursive: true });
+                    fs.writeFileSync(path.join(dddDir, 'domain-model.json'), JSON.stringify(dddModel, null, 2) + '\n', 'utf-8');
+                }
+                console.error(`  [ADR-028] Generated DDD model (${dddModel.contexts.length} bounded contexts)`);
+            }
+        }
+        catch {
+            // DDD is best-effort
+        }
+    }
+    catch (err) {
+        console.error(`  [ADR-028] ADR guarantee failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export async function executeAutoChain(traceId, options = {}) {
     const pipelineStart = Date.now();
     const homeDir = process.env['HOME'] ?? '/tmp';
@@ -234,13 +330,15 @@ export async function executeAutoChain(traceId, options = {}) {
     let scenarioBranch;
     let originalBranch;
     let scenarioQuery = '';
-    // Read scenario query from Phase 1 manifest (needed for branch naming)
+    // Read scenario query and simulation ID from Phase 1 manifest
+    let simulationId = '';
     try {
         const manifestPath = path.join(runDir, 'manifest.json');
         if (fs.existsSync(manifestPath)) {
             const raw = fs.readFileSync(manifestPath, 'utf-8');
             const manifest = JSON.parse(raw);
             scenarioQuery = manifest.query ?? '';
+            simulationId = manifest.simulation_id ?? manifest.execution_id ?? '';
         }
     }
     catch {
@@ -343,6 +441,7 @@ export async function executeAutoChain(traceId, options = {}) {
                 recordPhaseFailure(PHASE_AGENTS[2], traceId, errMsg);
                 phases.push({ phase: 2, label: 'Deep Research', status: 'failed', timing: Date.now() - phaseStart, artifacts: [], outputDir: phaseDir, error: errMsg });
                 copyPlanningArtifacts(runDir, projectRoot);
+                await ensureAdrsExist(runDir, traceId, scenarioQuery);
                 return buildResult(traceId, runDir, phases, pipelineStart, mode);
             }
         }
@@ -439,6 +538,7 @@ export async function executeAutoChain(traceId, options = {}) {
                     console.error('  [ABORT] No Phase 2 SPARC artifacts to recover from — pipeline cannot continue');
                     phases.push({ phase: 3, label: 'SPARC + London TDD', status: 'failed', timing: Date.now() - phaseStart, artifacts: [], outputDir: phaseDir, error: errMsg });
                     copyPlanningArtifacts(runDir, projectRoot);
+                    await ensureAdrsExist(runDir, traceId, scenarioQuery);
                     return buildResult(traceId, runDir, phases, pipelineStart, mode);
                 }
             }
@@ -869,23 +969,34 @@ The prompts must be production-grade — they will be given directly to a coding
                                 derivedPhases.push({ title: heading, slug, content: section, folder, adrIds: matchedAdrIds });
                             }
                         }
-                        // If SPARC didn't produce enough sections, fall back to ADR-derived phases
-                        if (derivedPhases.length < 3) {
-                            // Group ADRs into logical clusters
+                        // ADR-PIPELINE-031: Enrich with ADR-derived phases when SPARC sections alone are insufficient.
+                        // Each ADR that isn't already covered by a SPARC-derived phase becomes its own build step.
+                        if (derivedPhases.length < 8 && adrs.length > 0) {
+                            const existingSlugs = new Set(derivedPhases.map(p => p.slug));
+                            const existingTitleWords = new Set(derivedPhases.flatMap(p => p.title.toLowerCase().split(/\W+/).filter(w => w.length > 3)));
                             for (const adr of adrs) {
                                 const slug = adr.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50);
+                                // Skip if a phase with similar slug or overlapping title already exists
+                                if (existingSlugs.has(slug))
+                                    continue;
+                                const adrKeywords = adr.title.toLowerCase().split(/\W+/).filter(w => w.length > 3);
+                                const overlap = adrKeywords.filter(w => existingTitleWords.has(w)).length;
+                                if (overlap >= 2)
+                                    continue; // sufficiently covered by an existing phase
                                 const adrLower = `${adr.title} ${adr.context} ${adr.decision}`.toLowerCase();
                                 let folder = 'backend';
                                 if (/frontend|ui|dashboard/.test(adrLower))
                                     folder = 'frontend';
-                                else if (/erp|netsuite|sap|dynamics/.test(adrLower))
+                                else if (/erp|netsuite|sap|dynamics|coupa|workday|maximo|oracle/.test(adrLower))
                                     folder = 'erp';
-                                else if (/integration|connector/.test(adrLower))
+                                else if (/integration|connector|webhook/.test(adrLower))
                                     folder = 'integrations';
                                 else if (/deploy|infra|docker/.test(adrLower))
                                     folder = 'src';
                                 else if (/test|quality/.test(adrLower))
                                     folder = 'tests';
+                                else if (/audit|governance|approval/.test(adrLower))
+                                    folder = 'backend';
                                 derivedPhases.push({
                                     title: adr.title,
                                     slug,
@@ -893,6 +1004,9 @@ The prompts must be production-grade — they will be given directly to a coding
                                     folder,
                                     adrIds: [adr.id],
                                 });
+                                existingSlugs.add(slug);
+                                for (const w of adrKeywords)
+                                    existingTitleWords.add(w);
                             }
                         }
                         // Always add foundation (first) and testing/deployment (last) if not present
@@ -934,6 +1048,186 @@ The prompts must be production-grade — they will be given directly to a coding
                                 adrIds: [],
                             });
                         }
+                        // ADR-PIPELINE-031: Guarantee ≥10 prompts by adding standard cross-cutting phases
+                        // when domain-specific + ADR-derived phases don't reach the minimum.
+                        const crossCutting = [
+                            { title: 'Observability & Structured Logging', slug: 'observability', folder: 'backend',
+                                content: `ADR-PIPELINE-034: Implement complete observability infrastructure.
+
+## 1. Structured Logger (src/logger.ts)
+
+Create a logger factory that outputs JSON to stderr:
+
+\`\`\`typescript
+export interface Logger {
+  info(event: string, data?: Record<string, unknown>): void;
+  warn(event: string, data?: Record<string, unknown>): void;
+  error(event: string, error: Error, data?: Record<string, unknown>): void;
+}
+
+export function createLogger(service: string): Logger {
+  // Each log entry: { timestamp, level, service, event, correlationId?, ...data }
+  // Output to stderr as single-line JSON
+}
+
+// Correlation ID context — thread through entire request lifecycle
+export function withCorrelationId<T>(correlationId: string, fn: () => T): T;
+export function getCorrelationId(): string | undefined;
+\`\`\`
+
+## 2. Correlation ID Threading
+
+Every analysis run generates a correlationId (UUID). This ID flows through:
+- analysis.started → analysis.excess_detected → analysis.completed
+- decision.created → erp.sync.attempted → erp.sync.succeeded/failed
+
+Pass correlationId as a parameter through service functions or use AsyncLocalStorage.
+
+## 3. Instrumentation Points (minimum)
+
+| Event | When | Data |
+|-------|------|------|
+| analysis.started | Analysis begins | { correlationId, supplierCount, recordCount } |
+| analysis.completed | Analysis finishes | { correlationId, durationMs, flagCount, opportunityCount } |
+| decision.created | Decision recorded | { correlationId, decisionId, opportunityId, status } |
+| erp.sync.attempted | ERP write starts | { correlationId, transactionId, supplierId, action } |
+| erp.sync.succeeded | ERP write succeeds | { correlationId, transactionId, responseTime } |
+| erp.sync.failed | ERP write fails | { correlationId, transactionId, error, retryCount } |
+
+## 4. ERP Error Handling
+
+The ERP connector must handle:
+- Network timeout: configurable (default 30s), log erp.sync.failed with timeout error
+- Rate limiting (429): exponential backoff (1s, 2s, 4s, max 3 retries), log each retry
+- Schema validation: log and quarantine invalid records, don't crash the pipeline
+- Idempotency: generate idempotency key per transaction to prevent duplicate writes on retry
+
+## 5. Health Check
+
+If the project includes an API layer, add GET /health returning:
+\`\`\`json
+{ "status": "ok", "service": "packaging-waste-optimizer", "version": "0.1.0", "uptime": 12345, "lastAnalysisRun": "2026-04-09T..." }
+\`\`\`
+
+## 6. Tests
+
+- Test that logger outputs valid JSON to stderr
+- Test that correlationId flows through analysis → decision → ERP sync
+- Test that ERP error handling retries on 429 and logs failures` },
+                            { title: 'Configuration & Environment Management', slug: 'configuration', folder: 'src',
+                                content: `ADR-PIPELINE-034: Configuration module for environment-based settings.
+
+Create src/config.ts with a typed configuration object:
+
+\`\`\`typescript
+export interface AppConfig {
+  env: 'development' | 'staging' | 'production';
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+  erp: {
+    baseUrl: string;
+    apiVersion: string;
+    clientId: string;
+    timeoutMs: number;     // default 30000
+    maxRetries: number;    // default 3
+  };
+  analysis: {
+    // Domain-specific thresholds — externalized, not hardcoded
+    [key: string]: number | string | boolean;
+  };
+}
+\`\`\`
+
+Requirements:
+- Read all values from environment variables (never hardcode secrets)
+- Validate at startup — fail fast with clear error messages for missing required vars
+- Provide sensible defaults for optional values (timeoutMs, maxRetries, logLevel)
+- Export a singleton config object used by all services
+- Include tests that verify validation catches missing required vars` },
+                            { title: 'API Layer & Request Handling', slug: 'api-layer', folder: 'backend',
+                                content: 'Build REST API endpoints exposing core domain operations. Input validation at API boundary (Zod or equivalent). Authentication and authorization middleware. Structured error responses with correlation IDs. Rate limiting.' },
+                            { title: 'Persistence & Data Access Layer', slug: 'persistence', folder: 'backend',
+                                content: 'Implement repository interfaces per aggregate (ports pattern). Database adapter implementations. Audit trail persistence (append-only, tamper-evident). Transaction management for multi-aggregate operations.' },
+                            { title: 'Demo Script & CLI Entry Point', slug: 'demo', folder: 'src',
+                                content: `ADR-PIPELINE-037: User-facing entry points for the prototype.
+
+## 1. Demo Script (src/demo.ts) — REQUIRED
+
+Create a runnable demo (\`npx tsx src/demo.ts\`) that:
+1. Loads all seed data
+2. Runs the complete analysis pipeline end-to-end
+3. Prints formatted results to stdout using tables (not raw JSON):
+   - Summary table: key metrics, top findings
+   - Per-entity breakdown (e.g., per-supplier, per-zone, per-employee)
+   - Scenario comparison table with tradeoff columns
+4. Demonstrates the decision/approval workflow:
+   - Create a draft decision for the top opportunity
+   - Approve it with a test approver
+5. Shows the ERP sync payload:
+   - Print the structured payload that would be sent to the ERP
+   - Mark as "dry run" — do not actually sync
+
+The demo must run without any external dependencies (no database, no API keys, no network).
+
+## 2. CLI Interface (src/cli.ts) — OPTIONAL
+
+If time permits, create a minimal CLI:
+\`\`\`
+npx tsx src/cli.ts --analyze          # Run analysis, print results
+npx tsx src/cli.ts --scenarios        # Show scenario comparison
+npx tsx src/cli.ts --decide <id>      # Create decision for opportunity
+npx tsx src/cli.ts --sync <id>        # Dry-run ERP sync for decision
+npx tsx src/cli.ts --help             # Usage examples
+\`\`\`
+
+## 3. Architecture Divergence ADR — REQUIRED
+
+Create \`docs/ADR-001-monolithic-prototype.md\` in the generated project:
+
+\`\`\`markdown
+# ADR-001: Monolithic Library for Prototype Phase
+
+## Status
+Accepted
+
+## Context
+The SPARC architecture specification describes multiple microservices with event-driven
+communication. For the prototype evaluation period (3-7 days), deploying and operating
+microservices adds unnecessary complexity without delivering proportional value.
+
+## Decision
+Build as a single TypeScript library with clean module boundaries:
+- analysis/ — Pure computation, no side effects
+- decisions/ — State management with audit trail
+- erp/ — External system integration (adapter pattern)
+- data/ — Seed data and data access
+
+Each module exports a barrel (index.ts) and communicates via typed interfaces,
+not shared mutable state. This structure enables decomposition into independent
+services when the pilot validates the approach.
+
+## Consequences
+- Prototype can be built, tested, and demonstrated in days, not weeks
+- Module boundaries enforce separation of concerns without deployment overhead
+- Migration to microservices requires extracting modules into packages — not rewriting
+\`\`\`
+
+## Tests
+- Test that demo.ts runs without errors (import and execute main function)
+- Test that it produces non-empty stdout output` },
+                        ];
+                        const existingSlugSet = new Set(derivedPhases.map(p => p.slug));
+                        for (const cc of crossCutting) {
+                            if (derivedPhases.length >= 12)
+                                break;
+                            if (existingSlugSet.has(cc.slug))
+                                continue;
+                            // Don't add if a phase already covers this topic
+                            if (derivedPhases.some(p => p.title.toLowerCase().includes(cc.slug.split('-')[0])))
+                                continue;
+                            derivedPhases.push({ ...cc, adrIds: [] });
+                            existingSlugSet.add(cc.slug);
+                        }
+                        console.error(`  [PROMPTS] ${derivedPhases.length} phases derived (SPARC + ADRs + cross-cutting, minimum 10 per ADR-PIPELINE-031)`);
                         // ── Helper: extract DDD context names and summaries relevant to a phase ──
                         function getDddSummaryForPhase(phaseTitle, phaseContent) {
                             if (!dddContent)
@@ -1024,6 +1318,14 @@ The prompts must be production-grade — they will be given directly to a coding
                                 `**Target folder:** \`${phase.folder}/\``,
                                 '',
                             ];
+                            // ADR-PIPELINE-033: Simulation lineage in every prompt
+                            if (simulationId || traceId) {
+                                lines.push('## Simulation Lineage', '');
+                                if (simulationId)
+                                    lines.push(`Originating simulation: \`${simulationId}\``);
+                                lines.push(`Trace ID: \`${traceId}\``);
+                                lines.push('');
+                            }
                             // ── Narrative description — the core of each prompt ──
                             lines.push('## Overview', '', narrative, '');
                             // Previously completed phases (brief list)
@@ -1075,8 +1377,8 @@ The prompts must be production-grade — they will be given directly to a coding
                             if (dddSummary) {
                                 lines.push('## Domain Model Reference', '', dddSummary, '');
                             }
-                            // Implementation instructions
-                            lines.push('## Implementation Requirements', '', '- All code must be CUSTOM to this project — implement the specific business logic described above', '- Follow the technology decisions from the ADRs referenced in the overview', '- Write production-quality code with proper error handling', '- Include unit tests (London School TDD — mock at module boundaries)', '- Export public interfaces so later build phases can import them', `- Place all files in the \`${phase.folder}/\` directory`, '');
+                            // Implementation instructions — ADR-PIPELINE-033: include traceability requirements
+                            lines.push('## Implementation Requirements', '', '- All code must be CUSTOM to this project — implement the specific business logic described above', '- Follow the technology decisions from the ADRs referenced in the overview', '- Write production-quality code with proper error handling', '- Include unit tests (London School TDD — mock at module boundaries)', '- Export public interfaces so later build phases can import them', `- Place all files in the \`${phase.folder}/\` directory`, '', '## Traceability Requirements (ADR-PIPELINE-033)', '', '- All domain types that represent decisions, recommendations, or ERP actions must include optional `simulationId?: string` and `traceId?: string` fields', '- Audit trail entries must include these IDs when available', '- ERP transaction payloads must carry `simulationId` and `traceId` for end-to-end lineage', `${simulationId ? `- Use simulation ID \`${simulationId}\` as the default value when creating records in this build step` : '- Simulation ID will be injected at runtime from the pipeline context'}`, '');
                             fs.writeFileSync(path.join(promptsDir, filename), lines.join('\n'), { mode: 0o600, encoding: 'utf-8' });
                             completedPhases.push(`${order}. ${phase.title}`);
                         }
@@ -1087,7 +1389,17 @@ The prompts must be production-grade — they will be given directly to a coding
                             folder: phase.folder,
                             adrs: phase.adrIds,
                         }));
-                        fs.writeFileSync(path.join(promptsDir, 'execution-plan.json'), JSON.stringify({ totalSteps, prompts: planItems }, null, 2), { mode: 0o600, encoding: 'utf-8' });
+                        // ADR-PIPELINE-033: Include simulation lineage in execution plan
+                        const plan = {
+                            totalSteps,
+                            prompts: planItems,
+                            lineage: {
+                                simulationId: simulationId || undefined,
+                                traceId: traceId || undefined,
+                                pipelineVersion: '1.7.3',
+                            },
+                        };
+                        fs.writeFileSync(path.join(promptsDir, 'execution-plan.json'), JSON.stringify(plan, null, 2), { mode: 0o600, encoding: 'utf-8' });
                         console.error(`  [PROMPTS] Wrote ${totalSteps} implementation prompts derived from SPARC architecture + ADRs`);
                     }
                     copyPlanningArtifacts(runDir, projectRoot);
@@ -1217,6 +1529,7 @@ The prompts must be production-grade — they will be given directly to a coding
                 // Check if phase5-manifest.json exists on disk — if so, allow Phase 6 to attempt degraded mode
                 const phase5ManifestPath = path.join(phaseDir, 'phase5-manifest.json');
                 if (!fs.existsSync(phase5ManifestPath)) {
+                    await ensureAdrsExist(runDir, traceId, scenarioQuery);
                     return buildResult(traceId, runDir, phases, pipelineStart, mode);
                 }
                 console.error('  [INFO] Phase 5 manifest written — Phase 6 will attempt degraded mode.');
@@ -1273,6 +1586,7 @@ The prompts must be production-grade — they will be given directly to a coding
                 console.error(`  [FAIL] Phase 6 failed: ${errMsg}`);
                 recordPhaseFailure(PHASE_AGENTS[6], traceId, errMsg);
                 phases.push({ phase: 6, label: 'ERP Surface Push', status: 'failed', timing: Date.now() - phaseStart, artifacts: [], outputDir: phaseDir, error: errMsg });
+                await ensureAdrsExist(runDir, traceId, scenarioQuery);
                 return buildResult(traceId, runDir, phases, pipelineStart, mode);
             }
         }
@@ -1305,6 +1619,8 @@ The prompts must be production-grade — they will be given directly to a coding
             console.error(`  [WARN] Materialization failed: ${errMsg}`);
         }
     }
+    // ADR-028: Final ADR guarantee before returning
+    await ensureAdrsExist(runDir, traceId, scenarioQuery);
     // ── Shutdown swarm and persist metrics ──
     const totalTiming = Date.now() - pipelineStart;
     const pipelineSuccess = phases.every(p => p.status === 'completed' || p.status === 'skipped');