@llm-dev-ops/agentics-cli 2.7.31 → 2.7.33

package/dist/pipeline/phase2/phases/adr-generator.js

@@ -70,48 +70,176 @@ function findDossierRefs(dossier, keywords) {
 // ============================================================================
 // ADR Markdown Renderer
 // ============================================================================
+/**
+ * Render a Phase2ADRRecord as a markdown document.
+ *
+ * ADR-PIPELINE-101 — when the LLM-generated record carries the rich-content
+ * fields (architectureDiagram, components, performanceTargets, references,
+ * appendices, implementationStatus), the renderer interleaves them into a
+ * structure that mirrors `docs/good_ADR_example.md`. When those fields are
+ * absent (deterministic fallback path), it produces the legacy thin format
+ * for backwards compatibility.
+ */
 function renderADRMarkdown(adr) {
     const lines = [];
     lines.push(`# ${adr.id}: ${adr.title}`);
     lines.push('');
     lines.push(`**Status:** ${adr.status}`);
     lines.push(`**Date:** ${adr.date}`);
+    if (adr.authors && adr.authors.length > 0) {
+        lines.push(`**Authors:** ${adr.authors.join(', ')}`);
+    }
+    if (adr.deciders && adr.deciders.length > 0) {
+        lines.push(`**Deciders:** ${adr.deciders.join(', ')}`);
+    }
+    if (adr.supersedes) {
+        lines.push('');
+        lines.push(`**Note:** This ADR supersedes ${adr.supersedes}.`);
+    }
+    lines.push('');
+    lines.push('---');
     lines.push('');
+    // ── Context ─────────────────────────────────────────────────────────
     lines.push('## Context');
+    lines.push('');
     lines.push(adr.context);
     lines.push('');
+    // ── Decision ────────────────────────────────────────────────────────
     lines.push('## Decision');
+    lines.push('');
     lines.push(adr.decision);
     lines.push('');
+    // ── Architecture diagram (if provided) ──────────────────────────────
+    if (adr.architectureDiagram && adr.architectureDiagram.trim()) {
+        lines.push('### Architecture');
+        lines.push('');
+        lines.push('```');
+        lines.push(adr.architectureDiagram.trim());
+        lines.push('```');
+        lines.push('');
+    }
+    // ── Key Components ──────────────────────────────────────────────────
+    if (adr.components && adr.components.length > 0) {
+        lines.push('## Key Components');
+        lines.push('');
+        let idx = 0;
+        for (const comp of adr.components) {
+            idx++;
+            lines.push(`### ${idx}. ${comp.name}`);
+            lines.push('');
+            lines.push(comp.description);
+            lines.push('');
+            if (comp.codeExample && comp.codeExample.code.trim()) {
+                lines.push('```' + (comp.codeExample.language || ''));
+                lines.push(comp.codeExample.code.trim());
+                lines.push('```');
+                lines.push('');
+            }
+            if (comp.configTable && comp.configTable.rows.length > 0) {
+                lines.push(renderTable(comp.configTable.headers, comp.configTable.rows));
+                lines.push('');
+            }
+            if (comp.performanceCharacteristics && comp.performanceCharacteristics.length > 0) {
+                lines.push('**Performance characteristics:**');
+                lines.push('');
+                for (const p of comp.performanceCharacteristics)
+                    lines.push(`- ${p}`);
+                lines.push('');
+            }
+            if (comp.securityNotes && comp.securityNotes.length > 0) {
+                lines.push('**Security guarantees:**');
+                lines.push('');
+                for (const s of comp.securityNotes)
+                    lines.push(`- ${s}`);
+                lines.push('');
+            }
+        }
+    }
+    // ── Performance Targets (top-level table) ───────────────────────────
+    if (adr.performanceTargets && adr.performanceTargets.rows.length > 0) {
+        lines.push('## Performance Targets');
+        lines.push('');
+        lines.push(renderTable(adr.performanceTargets.headers, adr.performanceTargets.rows));
+        lines.push('');
+    }
+    // ── Alternatives ────────────────────────────────────────────────────
     if (adr.alternatives.length > 0) {
         lines.push('## Alternatives Considered');
+        lines.push('');
         for (const alt of adr.alternatives) {
             const status = alt.rejected ? '(rejected)' : '(selected)';
             lines.push(`- **${alt.option}** ${status}: ${alt.rationale}`);
         }
         lines.push('');
     }
+    // ── Consequences ────────────────────────────────────────────────────
     if (adr.consequences.length > 0) {
         lines.push('## Consequences');
+        lines.push('');
         for (const c of adr.consequences) {
             const icon = c.type === 'positive' ? '+' : c.type === 'negative' ? '-' : '~';
             lines.push(`- [${icon}] ${c.description}`);
         }
         lines.push('');
     }
-    if (adr.researchDossierItemRefs.length > 0) {
+    // ── Implementation Status ───────────────────────────────────────────
+    if (adr.implementationStatus && adr.implementationStatus.rows.length > 0) {
+        lines.push('## Implementation Status');
+        lines.push('');
+        lines.push(renderTable(adr.implementationStatus.headers, adr.implementationStatus.rows));
+        lines.push('');
+    }
+    // ── References (numbered) ───────────────────────────────────────────
+    if (adr.references && adr.references.length > 0) {
         lines.push('## References');
-        lines.push(`Dossier items: ${adr.researchDossierItemRefs.join(', ')}`);
         lines.push('');
+        let r = 0;
+        for (const ref of adr.references) {
+            r++;
+            lines.push(`${r}. ${ref}`);
+        }
+        lines.push('');
+    }
+    // ── Dossier item refs (kept as a separate section so they don't bury
+    // the formal references) ───────────────────────────────────────────
+    if (adr.researchDossierItemRefs.length > 0) {
+        lines.push('## Research Dossier Source Items');
+        lines.push('');
+        lines.push(adr.researchDossierItemRefs.map(r => `\`${r}\``).join(', '));
+        lines.push('');
+    }
+    // ── Appendices ──────────────────────────────────────────────────────
+    if (adr.appendices && adr.appendices.length > 0) {
+        let letterCode = 'A'.charCodeAt(0);
+        for (const apx of adr.appendices) {
+            lines.push(`## Appendix ${String.fromCharCode(letterCode)}: ${apx.title}`);
+            lines.push('');
+            lines.push(apx.body);
+            lines.push('');
+            letterCode++;
+        }
     }
     // ADR-PIPELINE-018: Include simulation lineage when present
     if (adr.simulationId) {
         lines.push('## Lineage');
-        lines.push(`Originating simulation: ${adr.simulationId}`);
+        lines.push('');
+        lines.push(`Originating simulation: \`${adr.simulationId}\``);
         lines.push('');
     }
     return lines.join('\n');
 }
+/** Render a markdown table — header row + separator + data rows. */
+function renderTable(headers, rows) {
+    const lines = [];
+    lines.push(`| ${headers.join(' | ')} |`);
+    lines.push(`|${headers.map(() => '---').join('|')}|`);
+    for (const row of rows) {
+        // Pad/truncate to header length so the table stays valid.
+        const padded = headers.map((_, i) => row[i] ?? '');
+        lines.push(`| ${padded.join(' | ')} |`);
+    }
+    return lines.join('\n');
+}
 // ============================================================================
 // ADR Builder — derived from SPARC + dossier
 // ============================================================================
@@ -1178,6 +1306,7 @@ function tryGenerateLLMADRs(sparc, dossier, query, phase2Dir = '') {
         const startMs = Date.now();
         // Use --print for one-shot generation (no MCP, no interactive session)
         const model = process.env['AGENTICS_CLAUDE_MODEL'] || 'claude-sonnet-4-20250514';
+        process.stderr.write(`[adr-generator] Invoking ${claudeBin} (${model}) for rich ADR generation — up to 6 minutes\n`);
         const rawOutput = execFileSync(claudeBin, [
             '--print',
             '--output-format', 'text',
@@ -1185,8 +1314,11 @@ function tryGenerateLLMADRs(sparc, dossier, query, phase2Dir = '') {
             prompt,
         ], {
             encoding: 'utf-8',
-            timeout: 120_000, // 2 minutes — ADR generation is complex
-            maxBuffer: 10 * 1024 * 1024,
+            // ADR-PIPELINE-101 — rich ADRs (architecture diagrams + per-component
+            // code examples + appendices) need substantially more output than the
+            // pre-101 thin format. Bump to 6 minutes.
+            timeout: 360_000,
+            maxBuffer: 32 * 1024 * 1024,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: { ...process.env, MCP_SERVER_MODE: undefined }, // Clear MCP flag for subprocess
         });
@@ -1238,54 +1370,80 @@ function buildADRPrompt(sparc, dossier, query, phase2Dir = '') {
     const erpPromptContext = techStack.erp
         ? `\nERP API DETAILS (use these EXACT paths):\n${formatERPContextForPrompt(techStack.erp)}\n`
         : '';
-    return (`You are a senior solution architect writing Architecture Decision Records. Read the FULL project requirements below and write ADRs that guide a developer on HOW to build this specific system.\n\n` +
+    return (`You are a senior staff architect writing detailed Architecture Decision Records (ADRs) for a real engineering team.\n\n` +
+        `Each ADR you produce MUST be a long-form, implementation-grade document that includes ASCII architecture diagrams, named components with code examples, configuration tables, performance targets, security guarantees, references, and appendices — NOT a 5-bullet skeleton. A developer must be able to take ONE of your ADRs and build the slice it describes without asking follow-up questions. Reference shape: 400-800 lines of markdown per ADR when rendered.\n\n` +
         `## Project Requirements\n\n${query}\n\n` +
         `## Services Identified\n${serviceList}\n` +
-        `\nRESEARCH FINDINGS:\n${dossierContext}\n` +
-        (agentContext ? agentContext + '\n' : '') +
-        `\nDETECTED TECHNOLOGIES: ${techMentions.join(', ') || 'not specified'}\n` +
+        `\n## Research Findings\n${dossierContext}\n` +
+        (agentContext ? '\n' + agentContext + '\n' : '') +
+        `\n## Detected Technologies\n${techMentions.join(', ') || 'not specified'}\n` +
         erpPromptContext +
-        `\nWrite 8-12 ADRs as a JSON array. Each ADR must be an IMPLEMENTATION DECISION that tells a developer what to build and how.\n` +
-        `\nIMPORTANT: ADRs must cover TWO categories:\n` +
-        `\nA) DOMAIN-SPECIFIC DECISIONS (at least 5) — these guide implementation of the actual business logic:\n` +
-        `   - How to model the core domain concepts (e.g., "Model emissions as facility-level time series with BU rollup")\n` +
-        `   - How to implement the key algorithms/calculations (scoring, ranking, normalization, weighting)\n` +
-        `   - How to structure the decision/simulation/optimization logic\n` +
-        `   - How domain entities relate and what business rules constrain them\n` +
-        `   - How to handle the specific workflows the user described\n` +
-        `   - CRITICAL: Each non-obvious algorithmic choice gets its OWN ADR:\n` +
-        `     * Scoring/ranking algorithms (normalization method, weight handling, rounding)\n` +
-        `     * Routing/filtering strategies (viability thresholds, mode selection, split ratios)\n` +
-        `     * Factor sourcing (emissions factors, cost multipliers, regional variations)\n` +
-        `     * Threshold models (SLA tolerances, priority levels, constraint buffers)\n` +
-        `     * Estimation fallbacks (distance estimation for unknown routes, default handling)\n` +
-        `     * Immutability/audit patterns (comparison persistence, content hashing, lineage)\n` +
-        `\nB) INFRASTRUCTURE DECISIONS (3-5) — technology choices that support the domain:\n` +
-        `   - Data persistence: which database(s) and why\n` +
-        `   - ERP integration approach for ${techMentions[0] || 'the ERP system'}\n` +
-        `   - Deployment and cloud platform specifics\n` +
-        `   - Security and compliance requirements\n` +
-        `\nEach ADR title should describe a SPECIFIC decision, not a category. Example:\n` +
-        `  GOOD: "Use Monte Carlo simulation for carbon price forecasting with configurable volatility"\n` +
-        `  BAD: "Performance Architecture"\n` +
-        `  GOOD: "Model emissions baseline as facility-level time series with business unit rollup"\n` +
-        `  BAD: "Data persistence strategy"\n` +
-        `\nReturn ONLY a JSON array (no markdown fences, no explanation before or after):\n` +
+        `\n## Output Contract\n\n` +
+        `Return ONLY a JSON array of 8-12 ADRs (no markdown fences, no preamble). Each ADR object MUST have this shape:\n` +
+        '```json\n' +
         `[\n` +
         `  {\n` +
-        `    "title": "Specific decision title that tells a developer what to build",\n` +
-        `    "context": "Why this decision matters — reference the specific business problem from the requirements",\n` +
-        `    "decision": "The specific approach — include enough detail that a developer can implement it",\n` +
-        `    "alternatives": [{"option": "Name", "rationale": "Why considered", "rejected": true/false}],\n` +
-        `    "consequences": [{"description": "Impact on the system", "type": "positive|negative|neutral"}]\n` +
+        `    "title": "Specific decision title — what the developer is building (e.g. 'Model water usage as facility-level 15-min time series with cooling-zone partitioning and weather correlation')",\n` +
+        `    "authors": ["Solution Architecture", "Sustainability Operations"],\n` +
+        `    "deciders": ["Architecture Review Board"],\n` +
+        `    "context": "3-6 paragraphs. Sub-section the problem space (the challenge, current state, target state). Cite specific requirements from the brief. NEVER one paragraph.",\n` +
+        `    "decision": "3-6 paragraphs. State the chosen approach concretely with named modules, schemas, thresholds. Cite ERP API paths if applicable. NEVER one sentence.",\n` +
+        `    "architectureDiagram": "ASCII box diagram showing how data/control flows through this slice. 8-15 lines. Use +-+, |, ->, etc.",\n` +
+        `    "components": [\n` +
+        `      {\n` +
+        `        "name": "Concrete module/class name (e.g. 'WaterUsageIngestor', 'CoolingScenarioEvaluator')",\n` +
+        `        "description": "1-2 paragraphs explaining what this component does and why it exists.",\n` +
+        `        "codeExample": { "language": "typescript", "code": "// 5-25 lines of REAL working code — interface, function signature, schema, query, etc. Not pseudo-code." },\n` +
+        `        "configTable": { "headers": ["Parameter", "Default", "Description"], "rows": [["window_size_min", "15", "Aggregation window for time-series rollup"], ["..."], ["..."]] },\n` +
+        `        "performanceCharacteristics": ["Bullet list of measurable perf claims (e.g. 'p99 ingest latency < 200ms at 50K events/sec')"],\n` +
+        `        "securityNotes": ["Bullet list of threat-model notes (e.g. 'Approval signatures use Ed25519, stored in HSM-backed key vault')"]\n` +
+        `      }\n` +
+        `    ],\n` +
+        `    "performanceTargets": { "headers": ["Metric", "Target", "Measurement"], "rows": [["Ingestion throughput", ">= 50K events/sec", "Per region, sustained 1h"], ["Query p95", "< 500ms", "Facility-level rollup, last 7 days"]] },\n` +
+        `    "alternatives": [\n` +
+        `      { "option": "Concrete alternative name (not 'Approach A')", "rationale": "Why it was considered and why rejected/selected. 1-3 sentences.", "rejected": true }\n` +
+        `    ],\n` +
+        `    "consequences": [\n` +
+        `      { "description": "Concrete consequence — what becomes easier/harder/possible/impossible. Reference specific downstream impact.", "type": "positive" }\n` +
+        `    ],\n` +
+        `    "implementationStatus": { "headers": ["Component", "Status", "Notes"], "rows": [["WaterUsageIngestor", "Planned", "Spec complete, awaiting Phase 5"], ["CoolingScenarioEvaluator", "Planned", "Depends on factor library"]] },\n` +
+        `    "references": [\n` +
+        `      "ASHRAE TC 9.9 — Thermal Guidelines for Data Processing Environments (2021)",\n` +
+        `      "ServiceNow Sustainability Management — Water Use API: https://developer.servicenow.com/...",\n` +
+        `      "Belady, C. — Carbon-Aware Computing in Hyperscale Data Centers (2022)"\n` +
+        `    ],\n` +
+        `    "appendices": [\n` +
+        `      { "title": "ServiceNow Field Mapping", "body": "Markdown table or prose mapping ADR concepts to ServiceNow CMDB tables (cmdb_ci_facility, sn_sustain_*) with example record shapes." },\n` +
+        `      { "title": "Sample Query", "body": "A realistic query/snippet showing how this ADR's slice is exercised end-to-end. Fenced code block." }\n` +
+        `    ]\n` +
         `  }\n` +
         `]\n` +
-        `\nCRITICAL RULES:\n` +
-        `- NO generic titles like "Security Architecture", "Performance Architecture", "Service Boundary"\n` +
-        `- Every ADR must contain enough implementation detail that a developer can build from it\n` +
-        `- The "decision" field should be 2-4 sentences describing the specific approach, not one vague sentence\n` +
-        `- Reference actual domain concepts from the requirements (not generic "entities" or "services")\n` +
-        `- If the user specified technologies (${techMentions.join(', ')}), reference them in relevant ADRs`);
+        '```\n' +
+        `\n## Coverage Requirements\n\n` +
+        `A) DOMAIN-SPECIFIC DECISIONS (at least 5):\n` +
+        `   - How to model the core domain (data shape, partitioning, time semantics)\n` +
+        `   - How to implement key algorithms (scoring, anomaly detection, scenario comparison, recommendation ranking)\n` +
+        `   - How decision/simulation/optimization logic is structured\n` +
+        `   - How domain entities relate and what business rules constrain them\n` +
+        `   - How specific user-described workflows are wired end-to-end\n` +
+        `   Each non-obvious algorithmic choice gets its OWN ADR: scoring/normalization, threshold models, factor sourcing, estimation fallbacks, immutability/audit patterns.\n\n` +
+        `B) INFRASTRUCTURE DECISIONS (3-5):\n` +
+        `   - Data persistence (which database, why, schema sketch)\n` +
+        `   - ERP integration for ${techMentions[0] || 'the named ERP'} (concrete API paths, idempotency, retry, rate limits)\n` +
+        `   - Deployment + cloud platform specifics\n` +
+        `   - Security, compliance, audit trail (RBAC, separation of duties, hash chain)\n\n` +
+        `## Critical Rules\n\n` +
+        `- NO generic titles like "Security Architecture", "Performance Architecture", "Service Boundary".\n` +
+        `- Every ADR's "decision" field is 3-6 paragraphs, NEVER one sentence.\n` +
+        `- "context" is 3-6 paragraphs explaining the problem space + current state + target state.\n` +
+        `- "components" has 2-5 entries per ADR, each with a real code example.\n` +
+        `- "appendices" has at least 1 entry (e.g. ERP field mapping, sample queries, threshold tables).\n` +
+        `- Reference actual domain concepts from the brief — never generic "entities" or "services".\n` +
+        `- If the user named technologies (${techMentions.join(', ')}), every relevant ADR cites them BY NAME with concrete API paths.\n` +
+        `- ASCII diagrams MUST show real component names from this project, not abstract boxes labelled "Service A".\n` +
+        `- Code examples MUST compile (or be syntactically valid pseudo-code with real types).\n` +
+        `- References MUST include at least one industry standard / RFC / vendor doc URL where applicable.\n\n` +
+        `Return ONLY the JSON array. No prose before or after. No markdown fences around the array.`);
 }
 /**
  * Parse raw LLM JSON response into Phase2ADRRecord[].
@@ -1326,6 +1484,7 @@ function parseRawADRs(rawText, dossier) {
         const cons = Array.isArray(raw.consequences)
             ? raw.consequences.map(c => makeCons(String(c.description || ''), (c.type || 'neutral')))
             : [makeCons('Decision applied', 'neutral')];
+        // ADR-PIPELINE-101: thread the rich-content fields if the LLM produced them.
         return {
             id: `ADR-P2-${pad3(idx + 1)}`,
             title: String(raw.title || `Decision ${idx + 1}`),
@@ -1339,9 +1498,90 @@ function parseRawADRs(rawText, dossier) {
             researchDossierItemRefs: findDossierRefs(dossier, [
                 String(raw.title || '').toLowerCase(),
             ]),
+            ...parseRichADRFields(raw),
         };
     });
 }
+/**
+ * Extract the optional ADR-PIPELINE-101 rich-content fields (architectureDiagram,
+ * components, performanceTargets, references, appendices, implementationStatus,
+ * authors, deciders) from an LLM JSON object. Returns a partial object — caller
+ * spreads it onto the base record so missing fields stay undefined.
+ */
+function parseRichADRFields(raw) {
+    const out = {};
+    if (Array.isArray(raw.authors)) {
+        out.authors = raw.authors.map(String).filter(Boolean);
+    }
+    if (Array.isArray(raw.deciders)) {
+        out.deciders = raw.deciders.map(String).filter(Boolean);
+    }
+    if (typeof raw.architectureDiagram === 'string' && raw.architectureDiagram.trim()) {
+        out.architectureDiagram = raw.architectureDiagram;
+    }
+    if (Array.isArray(raw.references)) {
+        out.references = raw.references.map(String).filter(Boolean);
+    }
+    const pt = parseTable(raw.performanceTargets);
+    if (pt)
+        out.performanceTargets = pt;
+    const is = parseTable(raw.implementationStatus);
+    if (is)
+        out.implementationStatus = is;
+    if (Array.isArray(raw.appendices)) {
+        out.appendices = raw.appendices
+            .filter((a) => a !== null && typeof a === 'object')
+            .map(a => ({
+            title: String(a['title'] ?? ''),
+            body: String(a['body'] ?? ''),
+        }))
+            .filter(a => a.title && a.body);
+    }
+    if (Array.isArray(raw.components)) {
+        out.components = raw.components
+            .filter((c) => c !== null && typeof c === 'object')
+            .map(c => {
+            const compOut = {
+                name: String(c['name'] ?? ''),
+                description: String(c['description'] ?? ''),
+            };
+            const ce = c['codeExample'];
+            if (ce && typeof ce === 'object') {
+                const lang = String(ce['language'] ?? '');
+                const code = String(ce['code'] ?? '');
+                if (code.trim())
+                    compOut.codeExample = { language: lang, code };
+            }
+            const ct = parseTable(c['configTable']);
+            if (ct)
+                compOut.configTable = ct;
+            if (Array.isArray(c['performanceCharacteristics'])) {
+                compOut.performanceCharacteristics = c['performanceCharacteristics'].map(String).filter(Boolean);
+            }
+            if (Array.isArray(c['securityNotes'])) {
+                compOut.securityNotes = c['securityNotes'].map(String).filter(Boolean);
+            }
+            return compOut;
+        })
+            .filter(c => c.name && c.description);
+    }
+    return out;
+}
+/** Parse a {headers, rows} table-shaped value into a strict shape, or undefined. */
+function parseTable(v) {
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const t = v;
+    if (!Array.isArray(t['headers']) || !Array.isArray(t['rows']))
+        return undefined;
+    const headers = t['headers'].map(String);
+    const rows = t['rows']
+        .filter(Array.isArray)
+        .map(row => row.map(String));
+    if (headers.length === 0 || rows.length === 0)
+        return undefined;
+    return { headers, rows };
+}
 /**
  * Generate ADRs via direct Anthropic API call.
  * Used when Claude Code runner is unavailable (MCP mode).
@@ -1369,14 +1609,16 @@ function tryGenerateADRsViaAPI(sparc, dossier, query) {
             '-H', 'anthropic-version: 2023-06-01',
             '-d', JSON.stringify({
                 model: process.env['AGENTICS_ADR_MODEL'] || 'claude-sonnet-4-20250514',
-                max_tokens: 8192,
+                // ADR-PIPELINE-101 — rich ADRs with diagrams + components + appendices
+                // need substantially more output tokens than the pre-101 thin format.
+                max_tokens: 32768,
                 messages: [{ role: 'user', content: prompt }],
             }),
         ];
         const rawResponse = execFileSync('curl', curlArgs, {
             encoding: 'utf-8',
-            timeout: 120_000,
-            maxBuffer: 10 * 1024 * 1024,
+            timeout: 360_000,
+            maxBuffer: 32 * 1024 * 1024,
         });
         const response = JSON.parse(rawResponse);
         if (response.error) {