@goodandready/dsh-moa 0.2.69 → 0.2.71

package/lib/client.js

@@ -2055,6 +2055,101 @@ window.__ModuleLoader__.load({
                   "(" + (t("aggregator.workbench_companion_note") || "safe shadow Git checkpoints before file promotion") + ")"
                 )
               ),
+              /* AST-Level Composite Merge (#248) */
+              React.createElement(
+                "div",
+                { style: { display: "flex", flexDirection: "column", gap: 6, padding: "8px 12px", background: "var(--dsw-alias-bg-layer-2)", borderRadius: 8, border: "1px solid var(--dsw-alias-border-l2)", marginTop: 8 } },
+                React.createElement(
+                  "label",
+                  { style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer", fontSize: 13, fontWeight: 500 } },
+                  React.createElement("input", {
+                    type: "checkbox",
+                    checked: Boolean(currentPreset.ast_composite_merge_enabled),
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, ast_composite_merge_enabled: e.target.checked })),
+                    style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))", cursor: "pointer" }
+                  }),
+                  t("aggregator.ast_merge_title") || "\u{1F333} AST-Level Composite Merge (Semantic Tree Synthesis)"
+                ),
+                React.createElement(
+                  "div",
+                  { style: { fontSize: 12, color: "var(--dsw-alias-label-secondary)", marginLeft: 22 } },
+                  t("aggregator.ast_merge_desc") || "Merge imports, type signatures, JSDoc, and function bodies at the AST declaration level without duplicate import collisions."
+                ),
+                React.createElement(
+                  "div",
+                  { style: { fontSize: 11, color: "var(--dsw-alias-label-tertiary)", marginLeft: 22, marginTop: 2, display: "flex", alignItems: "center", gap: 6 } },
+                  "\u{1F517} Companion Plugin:",
+                  React.createElement(
+                    "a",
+                    { href: "https://github.com/GooDAnDReaDY/dsh-context-lens", target: "_blank", rel: "noopener noreferrer", style: { color: "var(--dsw-alias-state-brand-primary)", textDecoration: "underline" } },
+                    "@goodandready/dsh-context-lens"
+                  )
+                )
+              ),
+              /* Speculative MoA (#247) & Adversarial TDD Loop (#246) */
+              React.createElement(
+                "div",
+                { style: { display: "flex", flexDirection: "column", gap: 6, padding: "8px 12px", background: "var(--dsw-alias-bg-layer-2)", borderRadius: 8, border: "1px solid var(--dsw-alias-border-l2)", marginTop: 8 } },
+                React.createElement(
+                  "label",
+                  { style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer", fontSize: 13, fontWeight: 500 } },
+                  React.createElement("input", {
+                    type: "checkbox",
+                    checked: Boolean(currentPreset.speculative_moa_enabled),
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, speculative_moa_enabled: e.target.checked })),
+                    style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))", cursor: "pointer" }
+                  }),
+                  t("aggregator.speculative_moa_title") || "\u26A1 Speculative MoA (Fast Draft + Multi-Auditor Diffs)"
+                ),
+                React.createElement(
+                  "label",
+                  { style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer", fontSize: 13, fontWeight: 500, marginTop: 4 } },
+                  React.createElement("input", {
+                    type: "checkbox",
+                    checked: Boolean(currentPreset.adversarial_tdd_enabled),
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, adversarial_tdd_enabled: e.target.checked })),
+                    style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))", cursor: "pointer" }
+                  }),
+                  t("aggregator.adversarial_tdd_title") || "\u{1F6E1}\uFE0F Adversarial TDD Loop (Auto-Generated Red-Team Unit Tests)"
+                )
+              ),
+              /* Multimodal Visual MoA Consensus (#250) */
+              React.createElement(
+                "div",
+                { style: { display: "flex", flexDirection: "column", gap: 6, padding: "8px 12px", background: "var(--dsw-alias-bg-layer-2)", borderRadius: 8, border: "1px solid var(--dsw-alias-border-l2)", marginTop: 8 } },
+                React.createElement(
+                  "label",
+                  { style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer", fontSize: 13, fontWeight: 500 } },
+                  React.createElement("input", {
+                    type: "checkbox",
+                    checked: Boolean(currentPreset.visual_moa_enabled),
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, visual_moa_enabled: e.target.checked })),
+                    style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))", cursor: "pointer" }
+                  }),
+                  t("aggregator.visual_moa_title") || "\u{1F441}\uFE0F Multimodal Visual MoA Consensus"
+                ),
+                React.createElement(
+                  "div",
+                  { style: { fontSize: 12, color: "var(--dsw-alias-label-secondary)", marginLeft: 22 } },
+                  t("aggregator.visual_moa_desc") || "Render UI candidates in Live Canvas and evaluate visual layout fidelity via Vision Bridge VLM."
+                ),
+                React.createElement(
+                  "div",
+                  { style: { fontSize: 11, color: "var(--dsw-alias-label-tertiary)", marginLeft: 22, marginTop: 2, display: "flex", alignItems: "center", gap: 6, flexWrap: "wrap" } },
+                  "\u{1F517} Companion Plugins:",
+                  React.createElement(
+                    "a",
+                    { href: "https://github.com/GooDAnDReaDY/dsh-vision-bridge", target: "_blank", rel: "noopener noreferrer", style: { color: "var(--dsw-alias-state-brand-primary)", textDecoration: "underline" } },
+                    "@goodandready/dsh-vision-bridge"
+                  ),
+                  "/",
+                  React.createElement(
+                    "a",
+                    { href: "https://github.com/GooDAnDReaDY/dsh-live-canvas", target: "_blank", rel: "noopener noreferrer", style: { color: "var(--dsw-alias-state-brand-primary)", textDecoration: "underline" } },
+                    "@goodandready/dsh-live-canvas"
+                  )
+                )
+              ),
               /* Quota-Aware Provider Balancing (#253) */
               React.createElement(
                 "div",
@@ -2580,6 +2675,7 @@ window.__ModuleLoader__.load({
                     React.createElement("th", { style: { padding: "6px 8px" } }, t("leaderboard.runs")),
                     React.createElement("th", { style: { padding: "6px 8px" } }, t("leaderboard.wins")),
                     React.createElement("th", { style: { padding: "6px 8px" } }, t("leaderboard.winrate")),
+                    React.createElement("th", { style: { padding: "6px 8px" } }, "Elo"),
                     React.createElement("th", { style: { padding: "6px 10px" } }, t("leaderboard.cost"))
                   )
                 ),
@@ -2594,6 +2690,7 @@ window.__ModuleLoader__.load({
                       React.createElement("td", { style: { padding: "6px 8px", color: "var(--dsw-alias-label-secondary)" } }, String(m.runs)),
                       React.createElement("td", { style: { padding: "6px 8px", color: "var(--dsw-alias-state-success-primary)" } }, String(m.wins)),
                       React.createElement("td", { style: { padding: "6px 8px", fontWeight: 600 } }, (m.winRate ?? 0) + "%"),
+                      React.createElement("td", { style: { padding: "6px 8px", fontWeight: 600, color: "var(--dsw-alias-state-brand-primary)" } }, String(m.elo ?? 1500)),
                       React.createElement("td", { style: { padding: "6px 10px", color: "var(--dsw-alias-label-secondary)" } }, m.avgCostUsd > 0 ? "$" + m.avgCostUsd.toFixed(4) : "Free")
                     )
                   )

package/lib/history.js

@@ -1,3 +1,4 @@
+import { classifyEloCategory, computeEloFromRuns, INITIAL_ELO } from './moa-elo.js'
 import { logger } from './logger.js'
 /**
  * MoA Run History & Analytics Module
@@ -355,6 +356,7 @@ export function getMoaLeaderboard(filePath = getDefaultHistoryFile(), options =
     _historyCache.totalCount = totalRuns
 
     const modelStats = new Map()
+    const parsedRuns = []
     let filteredRuns = 0
     for (const line of lines) {
       try {
@@ -362,6 +364,7 @@ export function getMoaLeaderboard(filePath = getDefaultHistoryFile(), options =
         if (!item) continue
         if (presetFilter && presetFilter !== 'all' && item.preset !== presetFilter) continue
         filteredRuns++
+        parsedRuns.push(item)
 
         const rawWinner = item.winnerModel ? String(item.winnerModel).trim() : null
         const cleanWinner = rawWinner ? rawWinner.replace(/\s*\[fallback for .*\]$/i, '').trim() : null
@@ -415,13 +418,25 @@ export function getMoaLeaderboard(filePath = getDefaultHistoryFile(), options =
       }
     }
 
+    const { globalRatings, categoryRatings } = computeEloFromRuns(parsedRuns)
     const models = Array.from(modelStats.values())
-      .map((st) => ({
-        ...st,
-        winRate: st.runs > 0 ? Number(((st.wins / st.runs) * 100).toFixed(1)) : 0,
-        avgTokens: st.runs > 0 ? Math.round(st.totalTokens / st.runs) : 0,
-        avgCostUsd: st.runs > 0 ? Number((st.totalCostUsd / st.runs).toFixed(4)) : 0,
-      }))
+      .map((st) => {
+        const elo = Math.round(globalRatings.get(st.modelKey) ?? INITIAL_ELO)
+        const categoryElo = {}
+        for (const [cat, cMap] of categoryRatings.entries()) {
+          if (cMap.has(st.modelKey)) {
+            categoryElo[cat] = Math.round(cMap.get(st.modelKey))
+          }
+        }
+        return {
+          ...st,
+          elo,
+          categoryElo,
+          winRate: st.runs > 0 ? Number(((st.wins / st.runs) * 100).toFixed(1)) : 0,
+          avgTokens: st.runs > 0 ? Math.round(st.totalTokens / st.runs) : 0,
+          avgCostUsd: st.runs > 0 ? Number((st.totalCostUsd / st.runs).toFixed(4)) : 0,
+        }
+      })
       .sort((a, b) => b.wins - a.wins || b.winRate - a.winRate)
 
     const result = {

package/lib/moa-adversarial-tdd.js

@@ -0,0 +1,219 @@
+/**
+ * Adversarial TDD Loop with Auto-Generated Unit Test Gate (#246)
+ * Generates an autonomous unit test suite (covering edge cases, nullability, and security bounds)
+ * from the user prompt via a Red-Team / Test Engineer model, injects the generated test files
+ * into each candidate's isolated workspace, executes them via moa-test-gate.js, and formats
+ * an objective pass/fail verification report for the Judge panel.
+ */
+
+import fs from 'node:fs/promises'
+import fsSync from 'node:fs'
+import path from 'node:path'
+import { logger } from './logger.js'
+import { slotLabel } from './moa-prompts.js'
+import { extractFileBlocks } from './workspace/fs.js'
+import { isSafeRelativePath, assertPathContained } from './workspace/security.js'
+import { resolveCandidateDir, runCandidateTestGate } from './moa-test-gate.js'
+
+export const RED_TEAM_TDD_SYSTEM_PROMPT = `You are an Adversarial Red-Team Test Engineer for a Mixture-of-Agents coding pipeline.
+Given the user's coding prompt and any existing file signatures, generate a self-contained Node.js unit test file using \`node:test\` and \`node:assert/strict\`.
+Rules:
+1. Output the test file inside a markdown fence with \`path=__moa_adversarial.test.mjs\`.
+2. Include edge-case assertions (empty inputs, null/undefined handling, boundary values, and security/injection guards).
+3. Ensure the test file is syntactically valid ES module code that exits with 0 when all assertions pass and non-zero on failure.`
+
+/**
+ * Generates an adversarial unit test suite from the user prompt.
+ *
+ * @param {object} params
+ * @returns {Promise<{ testFiles: Array<{ relativePath: string, content: string }>, testCommand: string, generatorModel: string }>}
+ */
+export async function generateAdversarialTestSuite({
+  userPrompt = '',
+  referenceOutputs = [],
+  redTeamSlot = null,
+  callLlm,
+  signal = null,
+}) {
+  if (typeof callLlm !== 'function') {
+    return { testFiles: [], testCommand: '', generatorModel: 'none' }
+  }
+
+  // Pick a dedicated Red-Team / Test Engineer slot
+  const chosenSlot = (redTeamSlot?.provider && redTeamSlot?.model)
+    ? redTeamSlot
+    : (referenceOutputs.find((r) => r?.slot?.role_persona === 'tester')?.slot || referenceOutputs[0]?.slot || { provider: 'default', model: 'default' })
+
+  const sampleFiles = []
+  for (const ref of referenceOutputs) {
+    if (!ref?.ok || !Array.isArray(ref.files)) continue
+    for (const f of ref.files) {
+      const rel = f.relativePath || f.path
+      if (rel && !sampleFiles.includes(rel)) sampleFiles.push(rel)
+    }
+  }
+
+  const userMsg = [
+    `### User Task Specification:\n${userPrompt}`,
+    sampleFiles.length > 0 ? `\n### Target Candidate Files to Test:\n${sampleFiles.map((f) => `- \`${f}\``).join('\n')}` : '',
+    `\nGenerate the adversarial unit test file with \`\`\`js path=__moa_adversarial.test.mjs.`,
+  ].filter(Boolean).join('\n')
+
+  try {
+    const res = await callLlm({
+      provider: chosenSlot.provider,
+      model: chosenSlot.model,
+      messages: [
+        { role: 'system', content: RED_TEAM_TDD_SYSTEM_PROMPT },
+        { role: 'user', content: userMsg },
+      ],
+      temperature: 0.2,
+      maxTokens: 2048,
+      signal,
+    })
+
+    const rawText = typeof res === 'string' ? res : (res?.content || res?.text || '')
+    let files = extractFileBlocks(rawText).filter((f) =>
+      /\.(test|spec)\.(mjs|js|cjs|ts)$/i.test(f.relativePath || '') || (f.relativePath || '').includes('adversarial')
+    )
+
+    if (files.length === 0) {
+      const codeMatch = /```(?:js|javascript|mjs)\r?\n([\s\S]*?)```/i.exec(rawText)
+      if (codeMatch && codeMatch[1].trim()) {
+        files = [{ relativePath: '__moa_adversarial.test.mjs', content: codeMatch[1].trim() + '\n' }]
+      }
+    }
+
+    if (files.length === 0) {
+      return { testFiles: [], testCommand: '', generatorModel: slotLabel(chosenSlot) }
+    }
+
+    const primaryTestFile = files[0].relativePath
+    return {
+      testFiles: files,
+      testCommand: `node --test ${primaryTestFile}`,
+      generatorModel: slotLabel(chosenSlot),
+    }
+  } catch (err) {
+    logger.warn('[dsh-moa:adversarial-tdd] Failed to generate adversarial unit tests:', err?.message || err)
+    return { testFiles: [], testCommand: '', generatorModel: slotLabel(chosenSlot) }
+  }
+}
+
+/**
+ * Runs the Adversarial TDD Loop across all candidate workspaces and attaches results.
+ *
+ * @param {object} params
+ * @returns {Promise<{
+ *   executed: boolean,
+ *   generatorModel: string,
+ *   testCommand: string,
+ *   testFiles: string[],
+ *   results: Array<{ candidateIndex: number, label: string, passed: boolean, exitCode: number, summary: string }>,
+ *   directive: string
+ * }>}
+ */
+export async function runAdversarialTddLoop({
+  cwd,
+  runId,
+  userPrompt = '',
+  referenceOutputs = [],
+  preset = {},
+  callLlm,
+  execFn = null,
+  onProgress = null,
+  signal = null,
+}) {
+  const candidatesWithFiles = (referenceOutputs || []).filter((r) => r.ok && Array.isArray(r.files) && r.files.length > 0)
+  if (candidatesWithFiles.length === 0) {
+    return { executed: false, generatorModel: 'none', testCommand: '', testFiles: [], results: [], directive: '' }
+  }
+
+  if (typeof onProgress === 'function') {
+    onProgress('🛡️ *Adversarial TDD Loop: Generating Red-Team unit test suite from prompt...*\n')
+  }
+
+  const suite = await generateAdversarialTestSuite({
+    userPrompt,
+    referenceOutputs: candidatesWithFiles,
+    redTeamSlot: preset?.aggregator,
+    callLlm,
+    signal,
+  })
+
+  if (suite.testFiles.length === 0 || !suite.testCommand) {
+    return { executed: false, generatorModel: suite.generatorModel, testCommand: '', testFiles: [], results: [], directive: '' }
+  }
+
+  if (typeof onProgress === 'function') {
+    onProgress(`🧪 *Adversarial TDD Loop: Executing \`${suite.testCommand}\` against ${candidatesWithFiles.length} candidate workspace(s)...*\n`)
+  }
+
+  const timeoutMs = (typeof preset?.test_gate_timeout_sec === 'number' && preset.test_gate_timeout_sec > 0
+    ? preset.test_gate_timeout_sec
+    : 15) * 1000
+
+  const results = []
+  for (let i = 0; i < referenceOutputs.length; i++) {
+    const ref = referenceOutputs[i]
+    if (!ref.ok || !Array.isArray(ref.files) || ref.files.length === 0) continue
+    const candIdx = ref.index ?? (i + 1)
+    const candDir = resolveCandidateDir(cwd, candIdx, { runId })
+    if (!candDir || !fsSync.existsSync(candDir)) continue
+
+    // Materialize generated adversarial test files inside the candidate sandbox
+    for (const tf of suite.testFiles) {
+      if (!isSafeRelativePath(tf.relativePath)) continue
+      const dest = assertPathContained(candDir, tf.relativePath)
+      await fs.mkdir(path.dirname(dest), { recursive: true })
+      await fs.writeFile(dest, tf.content, 'utf8')
+    }
+
+    const gateRes = await runCandidateTestGate({
+      cwd,
+      candidateIndex: candIdx,
+      testCommand: suite.testCommand,
+      timeoutMs,
+      execFn,
+      runId,
+    })
+
+    // Remove temporary adversarial test files from candidate workspace so they don't get promoted unintentionally
+    for (const tf of suite.testFiles) {
+      if (!isSafeRelativePath(tf.relativePath)) continue
+      try {
+        const dest = assertPathContained(candDir, tf.relativePath)
+        await fs.rm(dest, { force: true })
+      } catch {}
+    }
+
+    if (gateRes) {
+      ref.testResult = gateRes
+      results.push({
+        candidateIndex: candIdx,
+        label: ref.label || `Candidate ${candIdx}`,
+        passed: Boolean(gateRes.passed),
+        exitCode: gateRes.exitCode ?? (gateRes.passed ? 0 : 1),
+        summary: gateRes.summary || (gateRes.passed ? 'PASSED' : 'FAILED'),
+      })
+    }
+  }
+
+  const reportLines = [
+    `### 🛡️ Adversarial TDD Verification Report (Generated by Red-Team \`${suite.generatorModel}\`):`,
+    `Command executed in isolated sandbox: \`${suite.testCommand}\``,
+    ...results.map(
+      (r) => `- **Candidate #${r.candidateIndex} (${r.label})**: **${r.passed ? 'PASSED ✅' : `FAILED ❌ (exit ${r.exitCode})`}** — ${r.summary}`
+    ),
+    'Strongly favor candidates that pass the adversarial Red-Team unit test suite.',
+  ]
+
+  return {
+    executed: results.length > 0,
+    generatorModel: suite.generatorModel,
+    testCommand: suite.testCommand,
+    testFiles: suite.testFiles.map((f) => f.relativePath),
+    results,
+    directive: results.length > 0 ? reportLines.join('\n') : '',
+  }
+}

package/lib/moa-ast-merge.js

@@ -0,0 +1,230 @@
+/**
+ * AST-Level Composite Merge Integration via dsh-context-lens (#248)
+ * Semantically merges candidate files at the AST/declaration level (deduplicating imports,
+ * combining type signatures, JSDoc comments, and function bodies) using dsh-context-lens
+ * when available via ctx.reflect / service(ctx, 'contextLens'), with a clean fallback
+ * to structured declaration merge and standard string composite directives.
+ */
+
+import vm from 'node:vm'
+import { service } from './services.js'
+import { logger } from './logger.js'
+import { buildCompositeBlockDirectives } from './moa-multi-judge.js'
+import { extractFileBlocks } from './workspace/fs.js'
+
+/**
+ * Checks whether dsh-context-lens service is available on the Cordis context.
+ */
+export function resolveContextLensService(ctx, explicitLens = null) {
+  if (explicitLens) return explicitLens
+  const fromSvc = service(ctx, 'contextLens')
+  if (fromSvc) return fromSvc
+  try {
+    if (ctx?.reflect && typeof ctx.reflect.get === 'function') {
+      const refl = ctx.reflect.get('contextLens') || ctx.reflect.get('dsh-context-lens')
+      if (refl) return refl
+    }
+  } catch {}
+  return null
+}
+
+/**
+ * Parses top-level imports, declarations, and JSDoc from JS/TS source code.
+ */
+export function parseModuleDeclarations(source = '') {
+  const lines = String(source || '').split(/\r?\n/)
+  const imports = []
+  const bodyLines = []
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (/^import\s+/.test(trimmed) && (trimmed.endsWith(';') || trimmed.includes(' from '))) {
+      imports.push(trimmed.replace(/;$/, ''))
+    } else {
+      bodyLines.push(line)
+    }
+  }
+
+  const bodyText = bodyLines.join('\n')
+  const declarations = new Map()
+  const declRegex = /((?:\/\*\*[\s\S]*?\*\/\s*)?)(export\s+(?:async\s+)?(?:function|class|const|let|type|interface)\s+([A-Za-z0-9_$]+)[\s\S]*?)(?=(?:\n(?:\/\*\*[\s\S]*?\*\/\s*)?export\s+(?:async\s+)?(?:function|class|const|let|type|interface)\s+)|$)/g
+  let match
+  while ((match = declRegex.exec(bodyText)) !== null) {
+    const jsdoc = (match[1] || '').trim()
+    const code = (match[2] || '').trim()
+    const name = match[3]
+    if (name) {
+      declarations.set(name, { name, jsdoc, code })
+    }
+  }
+
+  return { imports, declarations, rawBody: bodyText.trim() }
+}
+
+/**
+ * Validates JavaScript syntax using node:vm compileFunction (ignoring TypeScript-only syntax).
+ */
+export function isValidJsAstSyntax(code = '', filename = 'module.js') {
+  if (/\.tsx?$/i.test(filename)) return true
+  const stripped = String(code)
+    .replace(/^\s*import\s+[\s\S]*?from\s+['"][^'"]+['"];?\s*$/gm, '')
+    .replace(/^\s*import\s+['"][^'"]+['"];?\s*$/gm, '')
+    .replace(/^\s*export\s+default\s+/gm, 'const __default_export__ = ')
+    .replace(/^\s*export\s+(async\s+function|function|class|const|let|var)\b/gm, '$1')
+    .replace(/^\s*export\s*\{[^}]*\};?\s*$/gm, '')
+  try {
+    new vm.Script(stripped, { filename })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Merges multiple candidate versions of the same file at declaration/AST level:
+ * - Deduplicates all import statements without collisions
+ * - Combines the richest JSDoc documentation, type signature, and implementation per symbol
+ */
+export async function mergeCandidateAstFiles(candidates = [], options = {}) {
+  const lens = resolveContextLensService(options.ctx, options.contextLens)
+  const byPath = new Map()
+
+  for (const cand of candidates) {
+    if (!cand || cand.ok === false) continue
+    const files = Array.isArray(cand.files) && cand.files.length > 0
+      ? cand.files
+      : extractFileBlocks(cand.text || '')
+    for (const f of files) {
+      const rel = f.relativePath || f.path
+      if (!rel || !f.content) continue
+      if (!byPath.has(rel)) byPath.set(rel, [])
+      byPath.get(rel).push({
+        candidateIndex: cand.index,
+        label: cand.label,
+        content: f.content,
+      })
+    }
+  }
+
+  const mergedFiles = []
+  for (const [relativePath, versions] of byPath.entries()) {
+    if (versions.length === 1) {
+      mergedFiles.push({
+        relativePath,
+        content: versions[0].content,
+        contributors: [versions[0].label || `Candidate ${versions[0].candidateIndex}`],
+        usedContextLens: Boolean(lens),
+      })
+      continue
+    }
+
+    // If dsh-context-lens provides a native mergeAst or analyzeAst method, use it first
+    if (lens && typeof lens.mergeAst === 'function') {
+      try {
+        const mergedCode = await lens.mergeAst({
+          filePath: relativePath,
+          versions: versions.map((v) => v.content),
+        })
+        if (mergedCode && typeof mergedCode === 'string' && isValidJsAstSyntax(mergedCode, relativePath)) {
+          mergedFiles.push({
+            relativePath,
+            content: mergedCode,
+            contributors: versions.map((v) => v.label || `Candidate ${v.candidateIndex}`),
+            usedContextLens: true,
+          })
+          continue
+        }
+      } catch (err) {
+        logger.warn(`[dsh-moa:ast-merge] contextLens.mergeAst failed for ${relativePath}, using declaration AST merger:`, err?.message || err)
+      }
+    }
+
+    // Declaration-level AST synthesis: deduplicate imports & merge JSDoc + bodies
+    const uniqueImports = new Set()
+    const mergedDecls = new Map()
+
+    for (const ver of versions) {
+      const parsed = parseModuleDeclarations(ver.content)
+      for (const imp of parsed.imports) uniqueImports.add(imp)
+
+      for (const [symName, decl] of parsed.declarations.entries()) {
+        if (!mergedDecls.has(symName)) {
+          mergedDecls.set(symName, { ...decl })
+        } else {
+          const existing = mergedDecls.get(symName)
+          // Keep the richest JSDoc comment from any candidate
+          if (decl.jsdoc && decl.jsdoc.length > (existing.jsdoc || '').length) {
+            existing.jsdoc = decl.jsdoc
+          }
+          // Prefer more comprehensive implementation if existing is a short stub
+          if (decl.code.length > existing.code.length && existing.code.length < 120) {
+            existing.code = decl.code
+          }
+        }
+      }
+    }
+
+    let assembled = ''
+    if (uniqueImports.size > 0) {
+      assembled += Array.from(uniqueImports).map((i) => `${i};`).join('\n') + '\n\n'
+    }
+    if (mergedDecls.size > 0) {
+      assembled += Array.from(mergedDecls.values())
+        .map((d) => (d.jsdoc ? `${d.jsdoc}\n${d.code}` : d.code))
+        .join('\n\n') + '\n'
+    } else {
+      assembled = versions[0].content
+    }
+
+    if (!isValidJsAstSyntax(assembled, relativePath)) {
+      assembled = versions[0].content
+    }
+
+    mergedFiles.push({
+      relativePath,
+      content: assembled,
+      contributors: versions.map((v) => v.label || `Candidate ${v.candidateIndex}`),
+      usedContextLens: Boolean(lens),
+    })
+  }
+
+  return mergedFiles
+}
+
+/**
+ * Builds the AST-level composite merge directive for the Judge/Curator.
+ * Gracefully falls back to standard buildCompositeBlockDirectives when dsh-context-lens is absent
+ * and no multi-version AST declarations are detected.
+ */
+export async function buildAstCompositeMergeDirective(candidates = [], options = {}) {
+  const lens = resolveContextLensService(options.ctx, options.contextLens)
+  const mergedFiles = await mergeCandidateAstFiles(candidates, options)
+  const baseDirective = buildCompositeBlockDirectives(candidates, options)
+
+  if (!lens && mergedFiles.length === 0) {
+    return {
+      degraded: true,
+      usedContextLens: false,
+      mergedFiles: [],
+      directive: baseDirective,
+    }
+  }
+
+  const astBlocks = mergedFiles
+    .map((mf) => `#### AST Pre-Merged Preview: \`${mf.relativePath}\` (Contributors: ${mf.contributors.join(', ')})\n\`\`\`js path=${mf.relativePath}\n${mf.content.trim()}\n\`\`\``)
+    .join('\n\n')
+
+  const directive = [
+    baseDirective.trim(),
+    `\n### 🌳 AST-Level Semantic Composite Merge (${lens ? 'via `dsh-context-lens`' : 'Fallback Declaration Merger'}):`,
+    'Imports have been deduplicated and declarations (JSDoc, type signatures, and function bodies) have been aligned across candidates:',
+    astBlocks,
+  ].join('\n\n')
+
+  return {
+    degraded: !lens,
+    usedContextLens: Boolean(lens),
+    mergedFiles,
+    directive,
+  }
+}