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

package/dist/pipeline/auto-chain.js

@@ -234,13 +234,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 {
@@ -869,23 +871,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 +906,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 +950,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 +1220,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 +1279,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 +1291,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);