nexus-agents 2.113.0 → 2.114.0

package/dist/chunk-ATI7W2FT.js

@@ -0,0 +1,2474 @@
+import {
+  resolveToken
+} from "./chunk-YJSXYHSK.js";
+import {
+  REGISTRY_PATH,
+  getProjectRoot,
+  loadPapersRegistry,
+  loadTechniquesRegistry,
+  savePapersRegistry
+} from "./chunk-E2ER3LQF.js";
+import {
+  getToolMemory
+} from "./chunk-7BZKZUVR.js";
+import {
+  resolveInsideRoot
+} from "./chunk-NUBSJGQZ.js";
+import {
+  capitalizeWords
+} from "./chunk-6T3EPABN.js";
+import {
+  API_TIMEOUTS,
+  CLI_NAMES,
+  CLI_SUBPROCESS_TIMEOUTS,
+  StrategyDistiller,
+  createLogger,
+  getErrorMessage,
+  getOutcomeStore,
+  getTimeProvider,
+  registerPersistentDistillerFactory
+} from "./chunk-ZXF2XA4R.js";
+import {
+  ensureLearningDir,
+  getRulesFile
+} from "./chunk-CH7QIDHQ.js";
+
+// src/learning/strategy-distiller-persistence.ts
+import { writeFileSync, readFileSync, renameSync, unlinkSync, existsSync } from "fs";
+import { dirname } from "path";
+import { z } from "zod";
+var DistilledRuleSchema = z.object({
+  id: z.string(),
+  patternType: z.enum(["failure-rate", "success-rate", "latency-spike"]),
+  cli: z.enum(CLI_NAMES),
+  category: z.string(),
+  action: z.enum(["penalize", "boost", "avoid"]),
+  confidence: z.number(),
+  observationCount: z.number(),
+  metric: z.number(),
+  status: z.enum(["draft", "active", "promoted", "expired"]),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  tainted: z.boolean()
+});
+var RulesSnapshotSchema = z.object({
+  version: z.literal(1),
+  savedAt: z.string(),
+  rules: z.array(DistilledRuleSchema)
+});
+var PersistentStrategyDistiller = class extends StrategyDistiller {
+  filePath;
+  persistLogger;
+  constructor(outcomeStore, persistConfig, logger, distillerConfig) {
+    super(outcomeStore, logger, distillerConfig);
+    this.filePath = persistConfig?.filePath ?? getRulesFile();
+    this.persistLogger = logger ?? createLogger({ component: "PersistentStrategyDistiller" });
+    const dataDir = persistConfig?.dataDir;
+    ensureLearningDir(dataDir);
+    this.hydrate();
+  }
+  /** Override distill to persist rules after each run. */
+  distill() {
+    super.distill();
+    this.saveSnapshot();
+  }
+  // ==========================================================================
+  // Private
+  // ==========================================================================
+  hydrate() {
+    if (!existsSync(this.filePath)) {
+      this.persistLogger.debug("No rules file found, starting fresh", {
+        path: this.filePath
+      });
+      return;
+    }
+    try {
+      const content = readFileSync(this.filePath, "utf-8");
+      const parsed = JSON.parse(content);
+      const result = RulesSnapshotSchema.safeParse(parsed);
+      if (!result.success) {
+        this.persistLogger.warn("Rules file failed validation, starting fresh", {
+          path: this.filePath,
+          error: result.error.message
+        });
+        return;
+      }
+      this.loadRules(result.data.rules);
+      this.persistLogger.info("Hydrated distilled rules from disk", {
+        ruleCount: result.data.rules.length,
+        savedAt: result.data.savedAt,
+        path: this.filePath
+      });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      this.persistLogger.warn("Failed to hydrate rules from disk", {
+        error: msg,
+        path: this.filePath
+      });
+    }
+  }
+  saveSnapshot() {
+    const rules = this.getRules();
+    const snapshot = {
+      version: 1,
+      savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      rules
+    };
+    const tmpPath = `${this.filePath}.tmp.${String(process.pid)}`;
+    try {
+      ensureLearningDir(dirname(this.filePath));
+      writeFileSync(tmpPath, JSON.stringify(snapshot, null, 2), "utf-8");
+      renameSync(tmpPath, this.filePath);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      this.persistLogger.warn("Failed to persist rules to disk", {
+        error: msg,
+        path: this.filePath
+      });
+      try {
+        if (existsSync(tmpPath)) unlinkSync(tmpPath);
+      } catch (cleanupErr) {
+        const msg2 = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+        this.persistLogger.debug("Failed to clean up temp file during persist", {
+          path: tmpPath,
+          error: msg2
+        });
+      }
+    }
+  }
+};
+registerPersistentDistillerFactory(
+  (outcomeStore, logger) => new PersistentStrategyDistiller(outcomeStore, void 0, logger)
+);
+function loadPersistedRules(filePath = getRulesFile()) {
+  if (!existsSync(filePath)) return [];
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    const result = RulesSnapshotSchema.safeParse(parsed);
+    if (!result.success) return [];
+    return result.data.rules;
+  } catch {
+    return [];
+  }
+}
+
+// src/cli/research-helpers-status.ts
+function toStatusSummary(id, entry) {
+  return {
+    id,
+    name: entry.name,
+    status: entry.status,
+    priority: entry.priority,
+    topic: entry.topic,
+    implementationIssue: entry.implementation_issue
+  };
+}
+function filterByStatus(techniques, status) {
+  return Object.entries(techniques).filter(([, entry]) => status === "all" || entry.status === status).map(([id, entry]) => toStatusSummary(id, entry)).sort((a, b) => {
+    const priorityOrder = { P1: 0, P2: 1, P3: 2, P4: 3 };
+    const aPriority = a.priority !== null ? priorityOrder[a.priority] ?? 4 : 4;
+    const bPriority = b.priority !== null ? priorityOrder[b.priority] ?? 4 : 4;
+    if (aPriority !== bPriority) return aPriority - bPriority;
+    return a.name.localeCompare(b.name);
+  });
+}
+function countByStatus(techniques) {
+  let implemented = 0;
+  let planned = 0;
+  let notStarted = 0;
+  let rejected = 0;
+  for (const entry of Object.values(techniques)) {
+    switch (entry.status) {
+      case "implemented":
+        implemented++;
+        break;
+      case "planned":
+      case "in-progress":
+        planned++;
+        break;
+      case "not-started":
+        notStarted++;
+        break;
+      case "rejected":
+        rejected++;
+        break;
+    }
+  }
+  return {
+    implemented,
+    planned,
+    notStarted,
+    rejected,
+    total: implemented + planned + notStarted + rejected
+  };
+}
+async function getResearchStatus(options) {
+  const result = await loadTechniquesRegistry();
+  if (!result.ok) {
+    return {
+      success: false,
+      techniques: [],
+      counts: { implemented: 0, planned: 0, notStarted: 0, rejected: 0, total: 0 }
+    };
+  }
+  const registry = result.value;
+  if (options.techniqueId !== void 0 && options.techniqueId !== "") {
+    const entry = registry.techniques[options.techniqueId];
+    if (entry === void 0) {
+      return {
+        success: false,
+        techniques: [],
+        counts: countByStatus(registry.techniques)
+      };
+    }
+    return {
+      success: true,
+      techniques: [toStatusSummary(options.techniqueId, entry)],
+      counts: countByStatus(registry.techniques)
+    };
+  }
+  const statusFilter = options.status === "all" ? "all" : options.status;
+  const techniques = filterByStatus(registry.techniques, statusFilter);
+  return {
+    success: true,
+    techniques,
+    counts: countByStatus(registry.techniques)
+  };
+}
+function formatStatusResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+  if (format === "compact") {
+    const lines2 = result.techniques.map(
+      (t) => `${t.status.padEnd(12)} ${(t.priority ?? "-").padEnd(3)} ${t.id}`
+    );
+    return lines2.join("\n");
+  }
+  const lines = [];
+  lines.push("Research Registry Status");
+  lines.push("=".repeat(60));
+  lines.push("");
+  const { counts } = result;
+  lines.push(
+    `Implemented: ${String(counts.implemented)} | Planned: ${String(counts.planned)} | Not Started: ${String(counts.notStarted)} | Rejected: ${String(counts.rejected)}`
+  );
+  lines.push(`Total: ${String(counts.total)}`);
+  lines.push("");
+  if (result.techniques.length === 0) {
+    lines.push("No techniques found matching criteria.");
+    return lines.join("\n");
+  }
+  lines.push("Status       | Pri | Topic          | ID");
+  lines.push("-".repeat(60));
+  for (const tech of result.techniques) {
+    const status = tech.status.padEnd(12);
+    const priority = (tech.priority ?? "-").padEnd(3);
+    const topic = tech.topic.slice(0, 14).padEnd(14);
+    lines.push(`${status} | ${priority} | ${topic} | ${tech.id}`);
+  }
+  return lines.join("\n");
+}
+
+// src/cli/research-helpers-overlap.ts
+function calculateTagOverlap(tags1, tags2) {
+  const set1 = new Set(tags1);
+  const set2 = new Set(tags2);
+  const intersection = [...set1].filter((tag) => set2.has(tag));
+  const union = /* @__PURE__ */ new Set([...set1, ...set2]);
+  return union.size === 0 ? 0 : intersection.length / union.size;
+}
+function findSharedTags(tags1, tags2) {
+  const set2 = new Set(tags2);
+  return tags1.filter((tag) => set2.has(tag));
+}
+function determineRelationship(source, target, overlapScore) {
+  if (source.topic === target.topic && overlapScore > 0.5) {
+    return "overlapping";
+  }
+  if (source.topic === target.topic) {
+    return "complementary";
+  }
+  if (overlapScore > 0.3) {
+    return "enhances";
+  }
+  return "complementary";
+}
+async function findOverlaps(options) {
+  const result = await loadTechniquesRegistry();
+  if (!result.ok) {
+    return {
+      success: false,
+      sourceId: options.techniqueId,
+      matches: [],
+      suggestedAlignments: []
+    };
+  }
+  const registry = result.value;
+  const sourceEntry = registry.techniques[options.techniqueId];
+  if (!sourceEntry) {
+    return {
+      success: false,
+      sourceId: options.techniqueId,
+      matches: [],
+      suggestedAlignments: []
+    };
+  }
+  const matches = [];
+  for (const [id, entry] of Object.entries(registry.techniques)) {
+    if (id === options.techniqueId) continue;
+    const overlapScore = calculateTagOverlap(sourceEntry.tags, entry.tags);
+    const sharedTopic = sourceEntry.topic === entry.topic;
+    if (overlapScore >= options.threshold || sharedTopic) {
+      matches.push({
+        techniqueId: id,
+        name: entry.name,
+        overlapScore,
+        sharedTags: findSharedTags(sourceEntry.tags, entry.tags),
+        sharedTopic,
+        relationship: determineRelationship(sourceEntry, entry, overlapScore)
+      });
+    }
+  }
+  matches.sort((a, b) => b.overlapScore - a.overlapScore);
+  const suggestedAlignments = matches.filter((m) => m.relationship === "overlapping" || m.relationship === "enhances").slice(0, 3).map((m) => `${options.techniqueId} -> ${m.techniqueId}: ${m.relationship}`);
+  return {
+    success: true,
+    sourceId: options.techniqueId,
+    matches,
+    suggestedAlignments
+  };
+}
+function formatOverlapResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  lines.push(`Overlap Analysis: ${result.sourceId}`);
+  lines.push("=".repeat(60));
+  lines.push("");
+  if (!result.success) {
+    lines.push(`Technique '${result.sourceId}' not found in registry.`);
+    return lines.join("\n");
+  }
+  if (result.matches.length === 0) {
+    lines.push("No overlapping techniques found.");
+    return lines.join("\n");
+  }
+  lines.push(`Found ${String(result.matches.length)} related technique(s):`);
+  lines.push("");
+  for (const match of result.matches) {
+    const score = (match.overlapScore * 100).toFixed(0);
+    lines.push(`  ${match.techniqueId}`);
+    lines.push(`    Name: ${match.name}`);
+    lines.push(`    Overlap: ${score}% | Relationship: ${match.relationship}`);
+    if (match.sharedTags.length > 0) {
+      lines.push(`    Shared tags: ${match.sharedTags.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (result.suggestedAlignments.length > 0) {
+    lines.push("Suggested alignments.yaml entries:");
+    for (const alignment of result.suggestedAlignments) {
+      lines.push(`  - ${alignment}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/research/research-quality.ts
+var TIER_3_VENUES = /* @__PURE__ */ new Set([
+  "neurips",
+  "nips",
+  "icml",
+  "iclr",
+  "aaai",
+  "acl",
+  "emnlp",
+  "cvpr",
+  "iccv",
+  "eccv",
+  "sigir",
+  "kdd",
+  "www",
+  "icse",
+  "fse"
+]);
+var TIER_2_VENUES = /* @__PURE__ */ new Set([
+  "naacl",
+  "coling",
+  "eacl",
+  "ijcai",
+  "ecai",
+  "aistats",
+  "uai",
+  "colt",
+  "interspeech",
+  "ase",
+  "issta"
+]);
+function classifyVenue(venue) {
+  if (venue === null || venue === void 0 || venue.length === 0) return 0;
+  const normalized = venue.toLowerCase().replace(/[^a-z]/g, "");
+  if (TIER_3_VENUES.has(normalized)) return 3;
+  if (TIER_2_VENUES.has(normalized)) return 2;
+  if (!normalized.includes("arxiv")) return 1;
+  return 0;
+}
+function recencyBoost(publicationDate) {
+  if (publicationDate === void 0) return 0;
+  const now = /* @__PURE__ */ new Date();
+  const pubDate = new Date(publicationDate);
+  const monthsAgo = (now.getTime() - pubDate.getTime()) / (30 * 24 * 60 * 60 * 1e3);
+  if (monthsAgo < 6) return 2;
+  if (monthsAgo < 12) return 1;
+  return 0;
+}
+function citationScore(count) {
+  if (count === void 0 || count === 0) return 0;
+  if (count < 10) return 1;
+  if (count < 100) return 2;
+  return 3;
+}
+var PREPRINT_CAP_CITATION_BYPASS = 100;
+var PREPRINT_QUALITY_CAP = 6;
+function isPreprintOnly(paper) {
+  const venueTier = paper.venue_tier ?? classifyVenue(paper.venue);
+  const hasNoVenue = paper.venue === null || paper.venue === void 0 || paper.venue.length === 0;
+  return (paper.source === "arxiv" || paper.source === "preprint") && hasNoVenue && venueTier === 0;
+}
+function computeQualityScore(paper) {
+  const citations = citationScore(paper.citation_count);
+  const venue = paper.venue_tier ?? classifyVenue(paper.venue);
+  const code = paper.has_code === true ? 2 : 0;
+  const recency = recencyBoost(paper.publication_date);
+  let score = Math.min(10, citations + venue + code + recency);
+  const citationCount = paper.citation_count ?? 0;
+  if (isPreprintOnly(paper) && citationCount < PREPRINT_CAP_CITATION_BYPASS) {
+    score = Math.min(score, PREPRINT_QUALITY_CAP);
+  }
+  return score;
+}
+function computeEvidenceTier(paper) {
+  const score = paper.quality_score ?? computeQualityScore(paper);
+  const tags = new Set(paper.rigor_tags);
+  if (tags.has("peer-reviewed") && tags.has("has-code") && tags.has("has-baselines")) {
+    return "high";
+  }
+  if (score >= 7) return "high";
+  if (tags.has("has-code") || score >= 4) return "medium";
+  return "low";
+}
+
+// src/cli/research-helpers-registry.ts
+function getCurrentDate() {
+  const now = new Date(getTimeProvider().now());
+  return now.toLocaleDateString("en-CA", { timeZone: "America/New_York" });
+}
+function extractPublicationDate(arxivId) {
+  const match = /^(\d{2})(\d{2})\./.exec(arxivId);
+  const yearStr = match?.[1];
+  const monthStr = match?.[2];
+  if (yearStr === void 0 || monthStr === void 0) {
+    return "";
+  }
+  const year = parseInt(yearStr, 10);
+  const month = monthStr;
+  const fullYear = year < 50 ? 2e3 + year : 1900 + year;
+  return `${String(fullYear)}-${month}`;
+}
+function detectTopicFromMetadata(metadata) {
+  const text = `${metadata.title} ${metadata.summary}`.toLowerCase();
+  const topicKeywords = {
+    consensus: ["consensus", "voting", "agreement", "byzantine", "debate"],
+    routing: ["routing", "route", "cascade", "model selection", "cost-quality"],
+    memory: ["memory", "context", "kv-cache", "long-term", "retrieval"],
+    "code-generation": ["code", "self-improve", "refine", "debug", "skill"],
+    orchestration: ["orchestration", "multi-agent", "coordination", "workflow"],
+    security: ["safety", "security", "adversarial", "harmful", "jailbreak"]
+  };
+  for (const [topic, keywords] of Object.entries(topicKeywords)) {
+    for (const keyword of keywords) {
+      if (text.includes(keyword)) {
+        return topic;
+      }
+    }
+  }
+  return void 0;
+}
+function generateTagsFromMetadata(metadata) {
+  const tags = [];
+  const title = metadata.title.toLowerCase();
+  const tagPatterns = {
+    survey: ["survey", "review", "overview"],
+    benchmark: ["benchmark", "evaluation", "dataset"],
+    "multi-agent": ["multi-agent", "multiagent", "multiple agents"],
+    llm: ["llm", "large language model", "language model"],
+    "reinforcement-learning": ["reinforcement learning", "rl", "reward"]
+  };
+  for (const [tag, patterns] of Object.entries(tagPatterns)) {
+    for (const pattern of patterns) {
+      if (title.includes(pattern)) {
+        tags.push(tag);
+        break;
+      }
+    }
+  }
+  return tags;
+}
+function createRegistryError(code, message, paperId, cause) {
+  const error = { code, message };
+  if (paperId !== void 0) {
+    return { ...error, paperId, cause };
+  }
+  if (cause !== void 0) {
+    return { ...error, cause };
+  }
+  return error;
+}
+function paperEntryToResearchPaper(entry) {
+  return {
+    title: entry.title,
+    authors: [...entry.authors],
+    source: entry.source,
+    arxiv_id: entry.arxiv_id,
+    url: entry.url,
+    publication_date: entry.publication_date,
+    venue: entry.venue,
+    topics: [...entry.topics],
+    tags: [...entry.tags],
+    reviewed_date: entry.reviewed_date,
+    reviewed_in: entry.reviewed_in,
+    summary: entry.summary,
+    key_findings: [...entry.key_findings],
+    relevance: entry.relevance,
+    techniques_extracted: [...entry.techniques_extracted],
+    related_issues: [...entry.related_issues],
+    implementation_status: entry.implementation_status,
+    rigor_tags: entry.rigor_tags ? [...entry.rigor_tags] : [],
+    ...entry.venue_tier !== void 0 ? { venue_tier: entry.venue_tier } : {},
+    ...entry.quality_score !== void 0 ? { quality_score: entry.quality_score } : {},
+    ...entry.evidence_tier !== void 0 ? { evidence_tier: entry.evidence_tier } : {},
+    ...entry.citation_count !== void 0 ? { citation_count: entry.citation_count } : {},
+    ...entry.has_code !== void 0 ? { has_code: entry.has_code } : {},
+    ...entry.code_url !== void 0 ? { code_url: entry.code_url } : {},
+    ...entry.quality_notes !== void 0 ? { quality_notes: entry.quality_notes } : {},
+    ...entry.last_quality_check !== void 0 ? { last_quality_check: entry.last_quality_check } : {}
+  };
+}
+function generateRegistryEntry(metadata, topic) {
+  if (metadata.id === "" || metadata.title === "") {
+    return {
+      ok: false,
+      error: createRegistryError(
+        "INVALID_METADATA",
+        "arXiv metadata is missing required fields (id or title)",
+        void 0,
+        void 0
+      )
+    };
+  }
+  const detectedTopic = topic ?? detectTopicFromMetadata(metadata);
+  const topics = detectedTopic !== void 0 ? [detectedTopic] : [];
+  const tags = generateTagsFromMetadata(metadata);
+  const publicationDate = extractPublicationDate(metadata.id);
+  const entry = {
+    title: metadata.title,
+    authors: metadata.authors,
+    source: "arxiv",
+    arxiv_id: metadata.id,
+    url: `https://arxiv.org/abs/${metadata.id}`,
+    publication_date: publicationDate,
+    venue: null,
+    topics,
+    tags,
+    reviewed_date: getCurrentDate(),
+    reviewed_in: "",
+    summary: "",
+    key_findings: [],
+    relevance: "medium",
+    techniques_extracted: [],
+    related_issues: [],
+    implementation_status: "not-started"
+  };
+  const paperForScoring = paperEntryToResearchPaper(entry);
+  const qualityScore = computeQualityScore(paperForScoring);
+  const evidenceTier = computeEvidenceTier({ ...paperForScoring, quality_score: qualityScore });
+  const scoredEntry = {
+    ...entry,
+    venue_tier: 0,
+    quality_score: qualityScore,
+    evidence_tier: evidenceTier
+  };
+  return { ok: true, value: scoredEntry };
+}
+function paperExistsInRegistry(arxivId, registry) {
+  const paperId = `arxiv-${arxivId}`;
+  return paperId in registry.papers;
+}
+function createAddResult(paperId, entry, message, dryRun) {
+  return { ok: true, value: { success: true, paperId, entry, message, dryRun } };
+}
+async function persistPaperEntry(registry, paperId, entry, rootDir) {
+  const updated = {
+    schema_version: registry.schema_version,
+    papers: { ...registry.papers, [paperId]: entry }
+  };
+  const saveResult = await savePapersRegistry(updated, rootDir);
+  if (!saveResult.ok) {
+    return {
+      ok: false,
+      error: createRegistryError(
+        "SAVE_ERROR",
+        `Failed to save papers registry: ${saveResult.error.message}`,
+        paperId,
+        saveResult.error
+      )
+    };
+  }
+  return { ok: true, value: void 0 };
+}
+async function addPaperToRegistry(options) {
+  const { metadata, topic, dryRun = false, rootDir } = options;
+  const paperId = `arxiv-${metadata.id}`;
+  const entryResult = generateRegistryEntry(metadata, topic);
+  if (!entryResult.ok) return entryResult;
+  const entry = entryResult.value;
+  const loadResult = await loadPapersRegistry(rootDir);
+  if (!loadResult.ok) {
+    return {
+      ok: false,
+      error: createRegistryError(
+        "LOAD_ERROR",
+        `Failed to load papers registry: ${loadResult.error.message}`,
+        paperId,
+        loadResult.error
+      )
+    };
+  }
+  if (paperExistsInRegistry(metadata.id, loadResult.value)) {
+    return {
+      ok: false,
+      error: createRegistryError(
+        "DUPLICATE",
+        `Paper ${paperId} already exists in registry`,
+        paperId
+      )
+    };
+  }
+  if (dryRun) {
+    return createAddResult(paperId, entry, `[DRY RUN] Would add paper: ${metadata.title}`, true);
+  }
+  const persistResult = await persistPaperEntry(loadResult.value, paperId, entry, rootDir);
+  if (!persistResult.ok) return { ok: false, error: persistResult.error };
+  return createAddResult(paperId, entry, `Added paper: ${metadata.title}`, false);
+}
+
+// src/cli/research-helpers-arxiv.ts
+var ARXIV_API_TIMEOUT_MS = API_TIMEOUTS.arxivMs;
+function extractEntryXml(xml) {
+  const entryMatch = xml.match(/<entry>([\s\S]*?)<\/entry>/);
+  return entryMatch?.[1] ?? null;
+}
+var XML_ENTITIES = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&apos;": "'"
+};
+function decodeXmlEntities(s) {
+  return s.replace(/&(?:amp|lt|gt|quot|apos);/g, (m) => XML_ENTITIES[m] ?? m);
+}
+function parseArxivXml(arxivId, xml) {
+  const entryXml = extractEntryXml(xml);
+  if (entryXml === null) return null;
+  const titleMatch = entryXml.match(/<title>([^<]+)<\/title>/);
+  const summaryMatch = entryXml.match(/<summary>([^<]+)<\/summary>/s);
+  const publishedMatch = entryXml.match(/<published>([^<]+)<\/published>/);
+  const titleContent = titleMatch?.[1];
+  if (titleContent === void 0 || titleContent === "") return null;
+  return {
+    id: arxivId,
+    title: decodeXmlEntities(titleContent.trim().replace(/\s+/g, " ")),
+    authors: [],
+    // Would need more complex parsing
+    summary: decodeXmlEntities(summaryMatch?.[1]?.trim().replace(/\s+/g, " ") ?? ""),
+    published: publishedMatch?.[1] ?? "",
+    updated: "",
+    categories: [],
+    pdfUrl: `https://arxiv.org/pdf/${arxivId}.pdf`
+  };
+}
+function createArxivError(code, arxivId, message, cause) {
+  return { code, message, arxivId, cause };
+}
+function getErrorCodeFromException(err) {
+  if (err instanceof Error && err.name === "TimeoutError") {
+    return "TIMEOUT";
+  }
+  return "NETWORK";
+}
+async function fetchArxivMetadataResult(arxivId) {
+  const url = `https://export.arxiv.org/api/query?id_list=${arxivId}`;
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(ARXIV_API_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      return {
+        ok: false,
+        error: createArxivError(
+          "HTTP_ERROR",
+          arxivId,
+          `arXiv API returned ${String(response.status)} ${response.statusText}`
+        )
+      };
+    }
+    const xml = await response.text();
+    const metadata = parseArxivXml(arxivId, xml);
+    if (metadata === null) {
+      return {
+        ok: false,
+        error: createArxivError("PARSE_ERROR", arxivId, "Failed to parse arXiv XML response")
+      };
+    }
+    return { ok: true, value: metadata };
+  } catch (err) {
+    const code = getErrorCodeFromException(err);
+    const message = code === "TIMEOUT" ? `arXiv API request timed out after ${String(ARXIV_API_TIMEOUT_MS / 1e3)} seconds` : "Network error while fetching from arXiv API";
+    return { ok: false, error: createArxivError(code, arxivId, message, err) };
+  }
+}
+async function paperExists(arxivId) {
+  const result = await loadPapersRegistry();
+  if (!result.ok) {
+    return false;
+  }
+  const paperId = `arxiv-${arxivId}`;
+  return paperId in result.value.papers;
+}
+async function addResearchPaper(options) {
+  const paperId = `arxiv-${options.arxivId}`;
+  const metadataResult = await fetchArxivMetadataResult(options.arxivId);
+  if (!metadataResult.ok) {
+    return {
+      success: false,
+      paperId,
+      title: "",
+      message: `Could not fetch metadata for arXiv ID ${options.arxivId}: ${metadataResult.error.message}`,
+      dryRun: options.dryRun
+    };
+  }
+  const metadata = metadataResult.value;
+  const addOptions = {
+    metadata,
+    dryRun: options.dryRun
+  };
+  if (options.topic !== void 0) {
+    addOptions.topic = options.topic;
+  }
+  const addResult = await addPaperToRegistry(addOptions);
+  if (!addResult.ok) {
+    return {
+      success: false,
+      paperId,
+      title: metadata.title,
+      message: addResult.error.message,
+      dryRun: options.dryRun
+    };
+  }
+  return {
+    success: addResult.value.success,
+    paperId: addResult.value.paperId,
+    title: metadata.title,
+    message: addResult.value.message,
+    dryRun: addResult.value.dryRun
+  };
+}
+
+// src/cli/research-helpers-sources.ts
+import { z as z2 } from "zod";
+var SOURCE_API_TIMEOUT_MS = 3e4;
+var GitHubRepoSchema = z2.object({
+  full_name: z2.string().optional(),
+  html_url: z2.string().optional(),
+  description: z2.string().nullable().optional(),
+  stargazers_count: z2.number().optional()
+});
+var GitHubSearchResponseSchema = z2.object({
+  items: z2.array(GitHubRepoSchema).optional()
+});
+function createError(code, source, message, cause) {
+  return { code, message, source, cause };
+}
+function getToday() {
+  return (/* @__PURE__ */ new Date()).toISOString().split("T")[0] ?? "";
+}
+function buildHttpErrorResult(status, source) {
+  const isRateLimit = status === 429;
+  const envHint = source === "github" ? "GITHUB_TOKEN" : `${source.toUpperCase()}_API_KEY`;
+  const message = isRateLimit ? `${source} rate-limited (HTTP 429) \u2014 set ${envHint} or retry later` : `API returned ${String(status)}`;
+  return createError(isRateLimit ? "RATE_LIMIT" : "HTTP_ERROR", source, message);
+}
+async function fetchSource(options) {
+  const { url, source, headers, timeoutMs = SOURCE_API_TIMEOUT_MS } = options;
+  try {
+    const fetchInit = { signal: AbortSignal.timeout(timeoutMs) };
+    if (headers !== void 0) fetchInit.headers = headers;
+    const response = await fetch(url, fetchInit);
+    if (!response.ok) {
+      return { ok: false, error: buildHttpErrorResult(response.status, source) };
+    }
+    return { ok: true, value: response };
+  } catch (error) {
+    const isTimeout = error instanceof Error && error.name === "TimeoutError";
+    return {
+      ok: false,
+      error: createError(
+        isTimeout ? "TIMEOUT" : "NETWORK",
+        source,
+        isTimeout ? `${source} API timed out` : `Network error querying ${source}`,
+        error
+      )
+    };
+  }
+}
+function parseGitHubRepos(data) {
+  return (data.items ?? []).map((repo) => ({
+    source: "github",
+    title: repo.full_name ?? "",
+    url: repo.html_url ?? "",
+    description: repo.description ?? "",
+    relevance: (repo.stargazers_count ?? 0) > 1e3 ? "high" : (repo.stargazers_count ?? 0) > 100 ? "medium" : "low",
+    discoveredAt: getToday()
+  }));
+}
+async function discoverGitHubRepos(topic, maxResults = 10) {
+  const query = encodeURIComponent(topic);
+  const url = `https://api.github.com/search/repositories?q=${query}&sort=stars&order=desc&per_page=${String(maxResults)}`;
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "nexus-agents"
+  };
+  const tokenResult = await resolveToken({ platform: "github" });
+  if (tokenResult.ok) {
+    headers["Authorization"] = `Bearer ${tokenResult.value.value}`;
+  }
+  const fetchResult = await fetchSource({ url, source: "github", headers });
+  if (!fetchResult.ok) return fetchResult;
+  let raw;
+  try {
+    raw = await fetchResult.value.json();
+  } catch {
+    return {
+      ok: false,
+      error: createError("PARSE_ERROR", "github", "Response is not valid JSON")
+    };
+  }
+  const parsed = GitHubSearchResponseSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: createError("PARSE_ERROR", "github", "GitHub API response schema mismatch")
+    };
+  }
+  return { ok: true, value: parseGitHubRepos(parsed.data) };
+}
+function buildArxivUrl(opts) {
+  const words = opts.topic.split(/\s+/).filter((w) => w.length > 0);
+  const topicQuery = words.length <= 1 ? `(ti:${opts.topic} OR abs:${opts.topic})` : `(${words.map((w) => `(ti:${w} OR abs:${w})`).join(" AND ")})`;
+  let fullQuery = opts.authorFilter !== "" ? `${topicQuery} AND ${opts.authorFilter}` : topicQuery;
+  if (opts.sinceDate !== void 0 && /^\d{4}-\d{2}-\d{2}$/.test(opts.sinceDate)) {
+    const dateNum = opts.sinceDate.replace(/-/g, "");
+    const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0]?.replace(/-/g, "") ?? "";
+    fullQuery = `${fullQuery} AND submittedDate:[${dateNum} TO ${today}]`;
+  }
+  const encoded = encodeURIComponent(fullQuery);
+  return `https://export.arxiv.org/api/query?search_query=${encoded}&start=0&max_results=${String(opts.maxResults)}&sortBy=submittedDate&sortOrder=descending`;
+}
+async function discoverFromArxiv(topic, authorFilter, source, maxResults, sinceDate) {
+  const url = buildArxivUrl({ topic, authorFilter, maxResults, sinceDate });
+  const fetchResult = await fetchSource({ url, source });
+  if (!fetchResult.ok) return fetchResult;
+  const xml = await fetchResult.value.text();
+  const items = parseArxivEntries(xml, source, topic);
+  return { ok: true, value: items };
+}
+async function discoverArxiv(topic, maxResults = 10, sinceDate) {
+  return discoverFromArxiv(topic, "", "arxiv", maxResults, sinceDate);
+}
+async function discoverGoogleAI(topic, maxResults = 10, sinceDate) {
+  return discoverFromArxiv(topic, "", "google_ai", maxResults, sinceDate);
+}
+async function discoverMetaFAIR(topic, maxResults = 10, sinceDate) {
+  return discoverFromArxiv(topic, "", "meta_fair", maxResults, sinceDate);
+}
+async function discoverMicrosoftResearch(topic, maxResults = 10, sinceDate) {
+  return discoverFromArxiv(topic, "", "microsoft", maxResults, sinceDate);
+}
+async function discoverDeepMind(topic, maxResults = 10, sinceDate) {
+  return discoverFromArxiv(topic, "", "deepmind", maxResults, sinceDate);
+}
+function extractTag(entry, tag) {
+  const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`<${escaped}>(.*?)</${escaped}>`, "s");
+  return regex.exec(entry)?.[1]?.trim().replace(/\s+/g, " ") ?? "";
+}
+function truncate(text, maxLen = 200) {
+  return text.length > maxLen ? text.slice(0, maxLen - 3) + "..." : text;
+}
+function scoreRelevance(title, topic) {
+  const titleLower = title.toLowerCase();
+  const topicWords = topic.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  if (topicWords.length === 0) return "medium";
+  const matched = topicWords.filter((w) => titleLower.includes(w)).length;
+  const ratio = matched / topicWords.length;
+  if (ratio >= 0.6) return "high";
+  if (ratio >= 0.3) return "medium";
+  return "low";
+}
+function parseArxivEntries(xml, source, topic = "") {
+  const items = [];
+  const entryRegex = /<entry>([\s\S]*?)<\/entry>/g;
+  let match;
+  while ((match = entryRegex.exec(xml)) !== null) {
+    const entry = match[1];
+    if (entry === void 0) continue;
+    const title = extractTag(entry, "title");
+    if (title === "") continue;
+    const id = extractTag(entry, "id");
+    const arxivId = id.match(/(\d{4}\.\d{4,5})/)?.[1] ?? "";
+    items.push({
+      source,
+      title,
+      url: arxivId !== "" ? `https://arxiv.org/abs/${arxivId}` : id,
+      description: truncate(extractTag(entry, "summary")),
+      relevance: topic !== "" ? scoreRelevance(title, topic) : "medium",
+      discoveredAt: getToday()
+    });
+  }
+  return items;
+}
+
+// src/cli/research-helpers-sources-io.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var SOURCES_FILE = "sources.yaml";
+function validatePath(constructedPath, allowedRoot) {
+  const resolved = resolveInsideRoot(constructedPath, allowedRoot);
+  if (resolved === null) {
+    const root = path.resolve(allowedRoot);
+    return {
+      ok: false,
+      error: {
+        code: "PATH_TRAVERSAL",
+        message: `Path ${path.resolve(constructedPath)} is outside ${root}`
+      }
+    };
+  }
+  return { ok: true, value: resolved };
+}
+async function loadSourcesRegistry(rootDir) {
+  const root = rootDir ?? getProjectRoot();
+  const filePath = path.join(root, REGISTRY_PATH, SOURCES_FILE);
+  const pathResult = validatePath(filePath, root);
+  if (!pathResult.ok) return pathResult;
+  try {
+    const content = await fs.readFile(pathResult.value, "utf-8");
+    const parsed = parseYaml(content);
+    return { ok: true, value: parsed };
+  } catch (error) {
+    const code = error instanceof Error && "code" in error ? error.code : void 0;
+    if (code === "ENOENT") {
+      return {
+        ok: true,
+        value: { schema_version: "1.0", sources: {} }
+      };
+    }
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        message: `Failed to load sources: ${getErrorMessage(error)}`
+      }
+    };
+  }
+}
+async function saveSourcesRegistry(registry, rootDir) {
+  const root = rootDir ?? getProjectRoot();
+  const filePath = path.join(root, REGISTRY_PATH, SOURCES_FILE);
+  const pathResult = validatePath(filePath, root);
+  if (!pathResult.ok) return pathResult;
+  try {
+    const yaml2 = stringifyYaml(registry, { indent: 2 });
+    await fs.writeFile(pathResult.value, yaml2, "utf-8");
+    return { ok: true, value: void 0 };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "WRITE_ERROR",
+        message: `Failed to save sources: ${getErrorMessage(error)}`
+      }
+    };
+  }
+}
+async function sourceExistsInRegistry(url, rootDir) {
+  const result = await loadSourcesRegistry(rootDir);
+  if (!result.ok) return false;
+  return Object.values(result.value.sources).some((s) => s.url === url);
+}
+async function addSourceToRegistry(id, entry, rootDir) {
+  const loadResult = await loadSourcesRegistry(rootDir);
+  if (!loadResult.ok) return loadResult;
+  const registry = loadResult.value;
+  const updatedSources = { ...registry.sources, [id]: entry };
+  const updatedRegistry = {
+    ...registry,
+    sources: updatedSources
+  };
+  return saveSourcesRegistry(updatedRegistry, rootDir);
+}
+
+// src/cli/research-helpers-sources-academic.ts
+import { z as z3 } from "zod";
+function getToday2() {
+  return (/* @__PURE__ */ new Date()).toISOString().split("T")[0] ?? "";
+}
+function truncate2(text, maxLen = 200) {
+  return text.length > maxLen ? text.slice(0, maxLen - 3) + "..." : text;
+}
+var SemanticScholarPaperSchema = z3.object({
+  paperId: z3.string().optional(),
+  title: z3.string().optional(),
+  url: z3.string().optional(),
+  abstract: z3.string().nullable().optional(),
+  citationCount: z3.number().optional(),
+  year: z3.number().optional(),
+  isOpenAccess: z3.boolean().optional(),
+  externalIds: z3.object({
+    ArXiv: z3.string().optional(),
+    DOI: z3.string().optional()
+  }).optional()
+});
+var SemanticScholarResponseSchema = z3.object({
+  data: z3.array(SemanticScholarPaperSchema).optional()
+});
+var PapersWithCodePaperSchema = z3.object({
+  id: z3.string().optional(),
+  title: z3.string().optional(),
+  url_abs: z3.string().optional(),
+  url_pdf: z3.string().optional(),
+  abstract: z3.string().nullable().optional(),
+  proceeding: z3.string().nullable().optional(),
+  repository_count: z3.number().optional()
+});
+var PapersWithCodeResponseSchema = z3.object({
+  results: z3.array(PapersWithCodePaperSchema).optional()
+});
+function citationRelevance(count) {
+  if (count > 100) return "high";
+  if (count > 20) return "medium";
+  return "low";
+}
+function mapSemanticScholarPaper(paper) {
+  const arxivId = paper.externalIds?.ArXiv;
+  const paperUrl = arxivId !== void 0 ? `https://arxiv.org/abs/${arxivId}` : paper.url ?? `https://api.semanticscholar.org/paper/${paper.paperId ?? ""}`;
+  return {
+    source: "semantic_scholar",
+    title: paper.title ?? "",
+    url: paperUrl,
+    description: truncate2(paper.abstract ?? ""),
+    relevance: citationRelevance(paper.citationCount ?? 0),
+    discoveredAt: getToday2()
+  };
+}
+async function discoverSemanticScholar(topic, maxResults = 10) {
+  const query = encodeURIComponent(topic);
+  const fields = "title,url,abstract,citationCount,year,isOpenAccess,externalIds";
+  const url = `https://api.semanticscholar.org/graph/v1/paper/search?query=${query}&limit=${String(maxResults)}&fields=${fields}`;
+  const headers = {
+    "User-Agent": "nexus-agents",
+    Accept: "application/json"
+  };
+  const apiKey = process.env["SEMANTIC_SCHOLAR_API_KEY"];
+  if (apiKey !== void 0 && apiKey !== "") {
+    headers["x-api-key"] = apiKey;
+  }
+  const fetchResult = await fetchSource({
+    url,
+    source: "semantic_scholar",
+    headers
+  });
+  if (!fetchResult.ok) return fetchResult;
+  let raw;
+  try {
+    raw = await fetchResult.value.json();
+  } catch {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        source: "semantic_scholar",
+        message: "Response is not valid JSON"
+      }
+    };
+  }
+  const parsed = SemanticScholarResponseSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        source: "semantic_scholar",
+        message: "Response schema mismatch"
+      }
+    };
+  }
+  const items = (parsed.data.data ?? []).filter((p) => p.title !== void 0 && p.title !== "").map(mapSemanticScholarPaper);
+  return { ok: true, value: items };
+}
+function mapPwcPaper(paper) {
+  const hasCode = (paper.repository_count ?? 0) > 0;
+  return {
+    source: "papers_with_code",
+    title: paper.title ?? "",
+    url: paper.url_abs ?? "",
+    description: truncate2(paper.abstract ?? ""),
+    relevance: hasCode ? "high" : "medium",
+    discoveredAt: getToday2()
+  };
+}
+function pwcParseError(message) {
+  return { ok: false, error: { code: "PARSE_ERROR", source: "papers_with_code", message } };
+}
+function isNonJsonResponse(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  return contentType !== "" && !contentType.includes("application/json");
+}
+async function discoverPapersWithCode(topic, maxResults = 10) {
+  const query = encodeURIComponent(topic);
+  const url = `https://paperswithcode.com/api/v1/papers/?q=${query}&items_per_page=${String(maxResults)}`;
+  const fetchResult = await fetchSource({
+    url,
+    source: "papers_with_code",
+    headers: { "User-Agent": "nexus-agents", Accept: "application/json" }
+  });
+  if (!fetchResult.ok) return fetchResult;
+  if (isNonJsonResponse(fetchResult.value)) return { ok: true, value: [] };
+  let raw;
+  try {
+    raw = await fetchResult.value.json();
+  } catch {
+    return pwcParseError("Response is not valid JSON (possible HTML error page)");
+  }
+  const parsed = PapersWithCodeResponseSchema.safeParse(raw);
+  if (!parsed.success) return pwcParseError("Response schema mismatch");
+  const items = (parsed.data.results ?? []).filter((p) => p.title !== void 0 && p.title !== "").map(mapPwcPaper);
+  return { ok: true, value: items };
+}
+var OpenAlexWorkSchema = z3.object({
+  id: z3.string().optional(),
+  title: z3.string().optional(),
+  doi: z3.string().nullable().optional(),
+  publication_date: z3.string().nullable().optional(),
+  cited_by_count: z3.number().optional(),
+  is_oa: z3.boolean().optional(),
+  abstract_inverted_index: z3.record(z3.string(), z3.array(z3.number())).nullable().optional(),
+  primary_location: z3.object({
+    landing_page_url: z3.string().nullable().optional()
+  }).nullable().optional(),
+  ids: z3.object({
+    openalex: z3.string().optional(),
+    doi: z3.string().optional()
+  }).optional()
+});
+var OpenAlexResponseSchema = z3.object({
+  results: z3.array(OpenAlexWorkSchema).optional()
+});
+function reconstructAbstract(invertedIndex) {
+  if (!invertedIndex) return "";
+  const words = [];
+  for (const [word, positions] of Object.entries(invertedIndex)) {
+    for (const pos of positions) {
+      words.push([word, pos]);
+    }
+  }
+  words.sort((a, b) => a[1] - b[1]);
+  return words.map(([w]) => w).join(" ");
+}
+function mapOpenAlexWork(work) {
+  const url = work.primary_location?.landing_page_url ?? work.ids?.doi ?? work.id ?? "";
+  return {
+    source: "openalex",
+    title: work.title ?? "",
+    url,
+    description: truncate2(reconstructAbstract(work.abstract_inverted_index)),
+    relevance: citationRelevance(work.cited_by_count ?? 0),
+    discoveredAt: getToday2()
+  };
+}
+function openAlexParseError(message) {
+  return { ok: false, error: { code: "PARSE_ERROR", source: "openalex", message } };
+}
+async function discoverOpenAlex(topic, maxResults = 10, apiKey) {
+  const query = encodeURIComponent(topic);
+  const mailto = "nexus-agents@example.com";
+  const url = `https://api.openalex.org/works?search=${query}&per_page=${String(maxResults)}&mailto=${mailto}`;
+  const headers = {
+    "User-Agent": "nexus-agents",
+    Accept: "application/json"
+  };
+  if (apiKey !== void 0 && apiKey !== "") {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  }
+  const fetchResult = await fetchSource({
+    url,
+    source: "openalex",
+    headers
+  });
+  if (!fetchResult.ok) return fetchResult;
+  let raw;
+  try {
+    raw = await fetchResult.value.json();
+  } catch {
+    return openAlexParseError("Response is not valid JSON");
+  }
+  const parsed = OpenAlexResponseSchema.safeParse(raw);
+  if (!parsed.success) return openAlexParseError("Response schema mismatch");
+  const items = (parsed.data.results ?? []).filter((w) => w.title !== void 0 && w.title !== "").map(mapOpenAlexWork);
+  return { ok: true, value: items };
+}
+
+// src/cli/research-helpers-scoring.ts
+var WEIGHTS = {
+  relevance: 0.35,
+  impact: 0.25,
+  recency: 0.2,
+  reproducibility: 0.2
+};
+function scoreRelevance2(title, topic) {
+  const titleLower = title.toLowerCase();
+  const topicWords = topic.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  if (topicWords.length === 0) return 0.5;
+  const matched = topicWords.filter((w) => titleLower.includes(w)).length;
+  return matched / topicWords.length;
+}
+function relevanceLabelToScore(relevance) {
+  switch (relevance) {
+    case "high":
+      return 0.9;
+    case "medium":
+      return 0.5;
+    case "low":
+      return 0.2;
+    default:
+      return 0.5;
+  }
+}
+function scoreRecency(discoveredAt) {
+  const discoveredDate = new Date(discoveredAt);
+  if (isNaN(discoveredDate.getTime())) return 0.5;
+  const now = /* @__PURE__ */ new Date();
+  const daysSince = (now.getTime() - discoveredDate.getTime()) / (1e3 * 60 * 60 * 24);
+  return Math.max(0, 1 - daysSince / 730);
+}
+function scoreReproducibility(source) {
+  switch (source) {
+    case "github":
+      return 1;
+    case "papers_with_code":
+      return 0.8;
+    default:
+      return 0.3;
+  }
+}
+function scoreDiscoveredItem(item, topic) {
+  const relevance = topic !== "" ? scoreRelevance2(item.title, topic) : relevanceLabelToScore(item.relevance);
+  const impact = relevanceLabelToScore(item.relevance);
+  const recency = scoreRecency(item.discoveredAt);
+  const reproducibility = scoreReproducibility(item.source);
+  const composite = WEIGHTS.relevance * relevance + WEIGHTS.impact * impact + WEIGHTS.recency * recency + WEIGHTS.reproducibility * reproducibility;
+  return {
+    relevance: Math.round(relevance * 100) / 100,
+    impact: Math.round(impact * 100) / 100,
+    recency: Math.round(recency * 100) / 100,
+    reproducibility: Math.round(reproducibility * 100) / 100,
+    composite: Math.round(composite * 100) / 100
+  };
+}
+function rankDiscoveredItems(items, topic) {
+  return items.map((item) => ({ item, score: scoreDiscoveredItem(item, topic) })).sort((a, b) => b.score.composite - a.score.composite);
+}
+
+// src/cli/research-helpers-index-ops.ts
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+
+// src/indexer/research-index/research-index-base-types.ts
+import { z as z4 } from "zod";
+var ResearchTopicSchema = z4.string().min(1);
+var TechniqueStatusSchema = z4.enum([
+  "implemented",
+  "planned",
+  "in-progress",
+  "not-started",
+  "rejected"
+]);
+var PaperStatusSchema = z4.enum([
+  "implemented",
+  "planned",
+  "partial",
+  "in-progress",
+  "not-started",
+  "rejected",
+  "deferred"
+]);
+var TechniquePrioritySchema = z4.enum(["P1", "P2", "P3", "P4"]).nullable();
+var TechniqueComplexitySchema = z4.enum(["low", "medium", "high"]);
+var SourceTypeSchema = z4.enum([
+  "product_docs",
+  "specification",
+  "research_blog",
+  "code_analysis",
+  "open_source_repo"
+]);
+var DecisionHistoryEntrySchema = z4.object({
+  date: z4.string(),
+  decision: z4.string(),
+  rationale: z4.string()
+});
+var PaperMetricsSchema = z4.record(z4.string(), z4.string());
+var ResearchPaperSchema = z4.object({
+  /** Paper title */
+  title: z4.string(),
+  /** Paper authors */
+  authors: z4.array(z4.string()).optional().default([]),
+  /** Source type (arxiv, conference, journal, preprint) */
+  source: z4.string().optional(),
+  /** arXiv ID (e.g., '2501.06322') */
+  arxiv_id: z4.string().optional(),
+  /** URL to the paper */
+  url: z4.string().optional(),
+  /** Publication date (YYYY-MM format) */
+  publication_date: z4.string().optional(),
+  /** Publication venue */
+  venue: z4.string().nullable().optional(),
+  /** Research topics */
+  topics: z4.array(ResearchTopicSchema).optional().default([]),
+  /** Tags for searching */
+  tags: z4.array(z4.string()).optional().default([]),
+  /** Date when the paper was reviewed */
+  reviewed_date: z4.string().optional(),
+  /** File where the paper is reviewed */
+  reviewed_in: z4.string().optional(),
+  /** Summary of the paper */
+  summary: z4.string().optional(),
+  /** Key findings from the paper */
+  key_findings: z4.array(z4.string()).optional().default([]),
+  /** Relevance to the project */
+  relevance: z4.enum(["high", "medium", "low"]).optional(),
+  /** Techniques extracted from this paper */
+  techniques_extracted: z4.array(z4.string()).optional().default([]),
+  /** Related GitHub issues */
+  related_issues: z4.array(z4.number()).optional().default([]),
+  /** Implementation status */
+  implementation_status: PaperStatusSchema.optional().default("not-started"),
+  // ── Quality Assessment (Issue #1571) ──────────────────────────
+  /** Citation count from Semantic Scholar */
+  citation_count: z4.number().nonnegative().optional(),
+  /** Venue quality tier: 3=top, 2=good, 1=workshop, 0=preprint */
+  venue_tier: z4.number().min(0).max(3).optional(),
+  /** Whether the paper links to a code repository */
+  has_code: z4.boolean().optional(),
+  /** Code repository URL */
+  code_url: z4.string().optional(),
+  /** Rigor assessment tags */
+  rigor_tags: z4.array(
+    z4.enum(["has-code", "has-dataset", "has-baselines", "peer-reviewed", "single-model-eval"])
+  ).optional().default([]),
+  /** Composite quality score (0-10) */
+  quality_score: z4.number().min(0).max(10).optional(),
+  /** Evidence confidence tier */
+  evidence_tier: z4.enum(["high", "medium", "low"]).optional(),
+  /** Quality notes for low-scoring papers */
+  quality_notes: z4.string().optional(),
+  /** When quality was last assessed (ISO date) */
+  last_quality_check: z4.string().optional()
+});
+var ResearchTechniqueSchema = z4.object({
+  /** Technique name */
+  name: z4.string(),
+  /** Description of the technique */
+  description: z4.string(),
+  /** Source papers (arXiv IDs) */
+  source_papers: z4.array(z4.string()).optional().default([]),
+  /** Primary topic */
+  topic: ResearchTopicSchema,
+  /** Tags for searching */
+  tags: z4.array(z4.string()).optional().default([]),
+  /** Metrics associated with this technique */
+  metrics: z4.record(z4.string(), z4.string()).optional().default({}),
+  /** Implementation status */
+  status: TechniqueStatusSchema,
+  /** Priority level */
+  priority: TechniquePrioritySchema.optional().default(null),
+  /** Complexity level */
+  complexity: TechniqueComplexitySchema.optional(),
+  /** Files where this technique is implemented */
+  integration_files: z4.array(z4.string()).optional().default([]),
+  /** GitHub issue number for implementation */
+  implementation_issue: z4.number().nullable().optional().default(null),
+  /** Related PR numbers */
+  related_prs: z4.array(z4.number()).optional().default([]),
+  /** Implementation notes */
+  notes: z4.string().optional(),
+  /** Dependent techniques */
+  dependencies: z4.array(z4.string()).optional().default([]),
+  /** Decision history */
+  decision_history: z4.array(DecisionHistoryEntrySchema).optional().default([]),
+  // ── Evaluation Plan (Issue #1576 Wave 6) ──────────────────────
+  /** Structured evaluation plan for keeping or removing the technique */
+  evaluation_plan: z4.object({
+    success_criteria: z4.string().optional(),
+    evaluation_method: z4.string().optional(),
+    evaluation_deadline: z4.string().optional(),
+    removal_criteria: z4.string().optional()
+  }).optional(),
+  /** Evaluation status: pending (not yet evaluated), passed, failed, deferred */
+  evaluation_status: z4.enum(["pending", "passed", "failed", "deferred"]).optional()
+});
+var ResearchSourceSchema = z4.object({
+  /** Source name */
+  name: z4.string(),
+  /** Source type */
+  type: SourceTypeSchema,
+  /** URL */
+  url: z4.string(),
+  /** Vendor/organization */
+  vendor: z4.string().optional(),
+  /** Topics covered */
+  topics: z4.array(ResearchTopicSchema).optional().default([]),
+  /** Tags for searching */
+  tags: z4.array(z4.string()).optional().default([]),
+  /** Date when reviewed */
+  reviewed_date: z4.string().optional(),
+  /** File where reviewed */
+  reviewed_in: z4.string().nullable().optional(),
+  /** Key information extracted */
+  key_info: z4.array(z4.string()).optional().default([]),
+  /** Best practices documented */
+  best_practices: z4.array(z4.string()).optional().default([]),
+  /** Version checked */
+  version_checked: z4.string().optional(),
+  // ── Repo/Tool Quality Signals (for open_source_repo type) ──────
+  /** Quality signals for repositories and tools */
+  quality_signals: z4.object({
+    stars_at_review: z4.number().nonnegative().optional(),
+    language: z4.string().optional(),
+    has_tests: z4.boolean().optional(),
+    has_docs: z4.boolean().optional(),
+    has_paper: z4.boolean().optional(),
+    arxiv_id: z4.string().optional()
+  }).optional(),
+  /** Techniques extracted from this source */
+  techniques_extracted: z4.array(z4.string()).optional().default([]),
+  /** Adoption verdict: adopted, partially_adopted, rejected, monitoring, planned */
+  verdict: z4.enum(["adopted", "partially_adopted", "rejected", "monitoring", "planned"]).optional(),
+  /** Notes explaining the verdict */
+  verdict_notes: z4.string().optional(),
+  /** Composite quality score (0-10) */
+  quality_score: z4.number().min(0).max(10).optional(),
+  /** Evidence confidence tier */
+  evidence_tier: z4.enum(["high", "medium", "low"]).optional()
+});
+var PapersRegistrySchema = z4.object({
+  schema_version: z4.string(),
+  papers: z4.record(z4.string(), ResearchPaperSchema)
+});
+var TechniquesRegistrySchema = z4.object({
+  schema_version: z4.string(),
+  techniques: z4.record(z4.string(), ResearchTechniqueSchema)
+});
+var SourcesRegistrySchema = z4.object({
+  schema_version: z4.string(),
+  sources: z4.record(z4.string(), ResearchSourceSchema)
+});
+
+// src/indexer/research-index/research-index-stats-types.ts
+var DEFAULT_RESEARCH_INDEX_PARSER_OPTIONS = {
+  registryPath: "docs/research/registry",
+  strictValidation: true
+};
+var DEFAULT_RESEARCH_INDEX_GENERATOR_OPTIONS = {
+  includeP1Table: true,
+  includeP2Table: true,
+  includeRecentPapers: true,
+  recentPapersLimit: 5,
+  includePapersByTopic: true,
+  includeGitHubIssues: true
+};
+var ResearchIndexParseError = class extends Error {
+  constructor(message, file, details) {
+    super(message);
+    this.file = file;
+    this.details = details;
+    this.name = "ResearchIndexParseError";
+  }
+};
+var ResearchIndexGeneratorError = class extends Error {
+  constructor(message, details) {
+    super(message);
+    this.details = details;
+    this.name = "ResearchIndexGeneratorError";
+  }
+};
+
+// src/indexer/research-index/research-index-parser.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import * as yaml from "yaml";
+
+// src/research/source-quality.ts
+function starScore(stars) {
+  if (stars === void 0 || stars === 0) return 0;
+  if (stars < 100) return 1;
+  if (stars < 1e3) return 2;
+  return 3;
+}
+function reviewRecencyScore(reviewedDate) {
+  if (reviewedDate === void 0) return 0;
+  const now = /* @__PURE__ */ new Date();
+  const reviewed = new Date(reviewedDate);
+  const monthsAgo = (now.getTime() - reviewed.getTime()) / (30 * 24 * 60 * 60 * 1e3);
+  if (monthsAgo < 6) return 2;
+  if (monthsAgo < 12) return 1;
+  return 0;
+}
+function computeSourceQualityScore(source) {
+  const signals = source.quality_signals;
+  if (signals === void 0) {
+    return source.type === "open_source_repo" ? 0 : 3;
+  }
+  const stars = starScore(signals.stars_at_review);
+  const tests = signals.has_tests === true ? 1 : 0;
+  const docs = signals.has_docs === true ? 1 : 0;
+  const recency = reviewRecencyScore(source.reviewed_date);
+  const paper = signals.has_paper === true ? 1 : 0;
+  const raw = stars + tests + docs + recency + paper;
+  return Math.min(10, Math.round(raw * 10 / 8));
+}
+function computeSourceEvidenceTier(source) {
+  const score = source.quality_score ?? computeSourceQualityScore(source);
+  const signals = source.quality_signals;
+  const hasTests = signals?.has_tests === true;
+  const hasPaper = signals?.has_paper === true;
+  if (score >= 7 && (hasTests || hasPaper)) return "high";
+  if (score >= 4 || hasTests) return "medium";
+  return "low";
+}
+
+// src/indexer/research-index/research-index-parser.ts
+function buildValidationError(filePath, validationErr) {
+  const zodErr = validationErr;
+  const issues = zodErr.issues ?? [];
+  const issuesPreview = issues.slice(0, 5).map((i) => `${i.path.slice(0, 4).join(".")}: ${i.message}`).join("; ");
+  const more = issues.length > 5 ? ` (+${String(issues.length - 5)} more)` : "";
+  return new ResearchIndexParseError(
+    issuesPreview.length > 0 ? `Validation failed for ${filePath} \u2014 ${issuesPreview}${more}` : `Validation failed for ${filePath}`,
+    filePath,
+    validationErr
+  );
+}
+function readYamlFile(filePath, schema, defaultIfMissing) {
+  try {
+    if (!fs2.existsSync(filePath)) {
+      if (defaultIfMissing !== void 0) {
+        return { ok: true, value: defaultIfMissing };
+      }
+      return {
+        ok: false,
+        error: new ResearchIndexParseError(
+          `File not found: ${filePath}. Run 'nexus-agents research add ...' to create it.`,
+          filePath
+        )
+      };
+    }
+    const content = fs2.readFileSync(filePath, "utf-8");
+    const parsed = yaml.parse(content);
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+      return { ok: false, error: buildValidationError(filePath, result.error) };
+    }
+    return { ok: true, value: result.data };
+  } catch (error) {
+    return {
+      ok: false,
+      error: new ResearchIndexParseError(
+        `Failed to parse ${filePath}: ${getErrorMessage(error)}`,
+        filePath,
+        error
+      )
+    };
+  }
+}
+function parsePapersRegistry(registryPath) {
+  const filePath = path2.join(registryPath, "papers.yaml");
+  const result = readYamlFile(filePath, PapersRegistrySchema, {
+    schema_version: "1.0",
+    papers: {}
+  });
+  if (!result.ok) {
+    return result;
+  }
+  const papers = Object.entries(result.value.papers).map(([id, paper]) => ({
+    id,
+    ...paper
+  }));
+  return { ok: true, value: papers };
+}
+function parseTechniquesRegistry(registryPath) {
+  const filePath = path2.join(registryPath, "techniques.yaml");
+  const result = readYamlFile(filePath, TechniquesRegistrySchema, {
+    schema_version: "1.0",
+    techniques: {}
+  });
+  if (!result.ok) {
+    return result;
+  }
+  const techniques = Object.entries(result.value.techniques).map(
+    ([id, technique]) => ({
+      id,
+      ...technique
+    })
+  );
+  return { ok: true, value: techniques };
+}
+function parseSourcesRegistry(registryPath) {
+  const filePath = path2.join(registryPath, "sources.yaml");
+  const result = readYamlFile(filePath, SourcesRegistrySchema, {
+    schema_version: "1.0",
+    sources: {}
+  });
+  if (!result.ok) {
+    return result;
+  }
+  const sources = Object.entries(result.value.sources).map(
+    ([id, source]) => {
+      const score = source.quality_score ?? computeSourceQualityScore(source);
+      const tier = source.evidence_tier ?? computeSourceEvidenceTier({ ...source, quality_score: score });
+      return { id, ...source, quality_score: score, evidence_tier: tier };
+    }
+  );
+  return { ok: true, value: sources };
+}
+function countTechniquesByStatus(techniques) {
+  const counts = {
+    implemented: 0,
+    planned: 0,
+    "in-progress": 0,
+    "not-started": 0,
+    rejected: 0
+  };
+  for (const technique of techniques) {
+    counts[technique.status]++;
+  }
+  return {
+    implemented: counts["implemented"],
+    planned: counts["planned"],
+    inProgress: counts["in-progress"],
+    notStarted: counts["not-started"],
+    rejected: counts["rejected"]
+  };
+}
+function countTechniquesByPriority(techniques) {
+  const counts = {
+    P1: 0,
+    P2: 0,
+    P3: 0,
+    P4: 0,
+    none: 0
+  };
+  for (const technique of techniques) {
+    const priority = technique.priority;
+    if (priority === null) {
+      counts.none++;
+    } else {
+      counts[priority]++;
+    }
+  }
+  return counts;
+}
+function deriveAllTopics(papers, techniques) {
+  const topicSet = /* @__PURE__ */ new Set();
+  for (const p of papers) {
+    for (const t of p.topics) topicSet.add(t);
+  }
+  for (const t of techniques) {
+    topicSet.add(t.topic);
+  }
+  return [...topicSet].sort();
+}
+function computeTopicStats(papers, techniques) {
+  const allTopics = deriveAllTopics(papers, techniques);
+  return allTopics.map((topic) => {
+    const paperCount = papers.filter((p) => p.topics.includes(topic)).length;
+    const techniqueCount = techniques.filter((t) => t.topic === topic).length;
+    return {
+      topic,
+      paperCount,
+      techniqueCount
+    };
+  });
+}
+function computeStats(papers, techniques, sources) {
+  return {
+    totalPapers: papers.length,
+    totalTechniques: techniques.length,
+    totalSources: sources.length,
+    totalTopics: deriveAllTopics(papers, techniques).length,
+    techniquesByStatus: countTechniquesByStatus(techniques),
+    techniquesByPriority: countTechniquesByPriority(techniques),
+    topicStats: computeTopicStats(papers, techniques),
+    qualityDistribution: computeQualityDistribution(papers)
+  };
+}
+function computeQualityDistribution(papers) {
+  let high = 0;
+  let medium = 0;
+  let low = 0;
+  let unscored = 0;
+  let totalScore = 0;
+  let scored = 0;
+  for (const p of papers) {
+    const tier = p.evidence_tier;
+    if (tier === "high") high++;
+    else if (tier === "medium") medium++;
+    else if (tier === "low") low++;
+    else unscored++;
+    const score = p.quality_score;
+    if (score !== void 0) {
+      totalScore += score;
+      scored++;
+    }
+  }
+  return {
+    high,
+    medium,
+    low,
+    unscored,
+    averageScore: scored > 0 ? Math.round(totalScore / scored * 10) / 10 : 0
+  };
+}
+function parseRegistry(options = {}) {
+  const opts = { ...DEFAULT_RESEARCH_INDEX_PARSER_OPTIONS, ...options };
+  const papersResult = parsePapersRegistry(opts.registryPath);
+  if (!papersResult.ok) {
+    return papersResult;
+  }
+  const techniquesResult = parseTechniquesRegistry(opts.registryPath);
+  if (!techniquesResult.ok) {
+    return techniquesResult;
+  }
+  const sourcesResult = parseSourcesRegistry(opts.registryPath);
+  if (!sourcesResult.ok) {
+    return sourcesResult;
+  }
+  const stats = computeStats(papersResult.value, techniquesResult.value, sourcesResult.value);
+  const now = new Date(getTimeProvider().now());
+  const etFormatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: "America/New_York",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const parts = etFormatter.formatToParts(now);
+  const getPartValue = (type) => parts.find((p) => p.type === type)?.value ?? "";
+  const generatedAt = `${getPartValue("year")}-${getPartValue("month")}-${getPartValue("day")} (ET)`;
+  return {
+    ok: true,
+    value: {
+      schemaVersion: "1.0",
+      generatedAt,
+      papers: papersResult.value,
+      techniques: techniquesResult.value,
+      sources: sourcesResult.value,
+      stats
+    }
+  };
+}
+function getTechniquesByPriority(index, priority) {
+  return index.techniques.filter((t) => t.priority === priority);
+}
+function getPapersByTopic(index, topic) {
+  return index.papers.filter((p) => p.topics.includes(topic));
+}
+function getRecentlyReviewedPapers(index, limit = 5) {
+  return [...index.papers].filter(
+    (p) => typeof p.reviewed_date === "string"
+  ).sort((a, b) => b.reviewed_date.localeCompare(a.reviewed_date)).slice(0, limit);
+}
+function getTechniquesWithIssues(index) {
+  return index.techniques.filter((t) => t.implementation_issue !== null);
+}
+
+// src/indexer/research-index/research-index-generator-helpers.ts
+function generateHeader(index) {
+  const { stats } = index;
+  return `# Nexus-Agents Research Index
+
+**Generated:** ${index.generatedAt}
+**Total Papers:** ${String(stats.totalPapers)} | **Techniques:** ${String(stats.totalTechniques)} | **Topics:** ${String(stats.totalTopics)}
+
+---`;
+}
+function generateQuickStats(index) {
+  const { techniquesByStatus } = index.stats;
+  return `## Quick Stats
+
+| Status      | Papers | Techniques |
+| ----------- | ------ | ---------- |
+| Implemented | -      | ${String(techniquesByStatus.implemented)}         |
+| In Progress | -      | ${String(techniquesByStatus.inProgress)}          |
+| Planned     | -      | ${String(techniquesByStatus.planned)}          |
+| Not Started | -      | ${String(techniquesByStatus.notStarted)}          |
+| Rejected    | -      | ${String(techniquesByStatus.rejected)}          |
+
+> **Note:** Paper-level status tracking deprecated. Technique status is source of truth.`;
+}
+function generateTopicsTable(index) {
+  const { topicStats } = index.stats;
+  const topicDescriptions = {
+    consensus: "Multi-agent decision protocols",
+    routing: "Cost-efficient model routing",
+    memory: "Context and long-term memory",
+    "code-generation": "Self-improvement and skill learning",
+    "cli-tools": "External CLI integration",
+    orchestration: "Multi-agent coordination",
+    security: "Agent safety and security evaluation",
+    "multi-agent-worker-dispatch": "Worker dispatch and wave execution"
+  };
+  const rows = topicStats.map((stat) => {
+    const description = topicDescriptions[stat.topic];
+    const topicLink = `[${capitalizeWords(stat.topic.replaceAll("-", " "))}](topics/${stat.topic}/README.md)`;
+    return `| ${topicLink} | ${String(stat.paperCount)} | ${String(stat.techniqueCount)} | ${description ?? ""} |`;
+  });
+  return `---
+
+## Topics
+
+| Topic | Papers | Techniques | Description |
+| ----- | ------ | ---------- | ----------- |
+${rows.join("\n")}`;
+}
+function generateTechniqueRow(technique) {
+  const name = `[${technique.name}](registry/techniques.yaml#${technique.id})`;
+  const topic = technique.topic;
+  const metricsEntries = Object.entries(technique.metrics);
+  const metrics = metricsEntries.length > 0 ? metricsEntries.map(([key, value]) => `${key}: ${value}`).join(", ") : "-";
+  const issue = technique.implementation_issue !== null ? `#${String(technique.implementation_issue)}` : "-";
+  return `| ${name} | ${topic} | ${metrics} | ${issue} |`;
+}
+function generateP1Table(index) {
+  const p1Techniques = getTechniquesByPriority(index, "P1");
+  if (p1Techniques.length === 0) {
+    return "";
+  }
+  const rows = p1Techniques.map(generateTechniqueRow);
+  return `---
+
+## Priority 1 (P1) Techniques
+
+These techniques are high-impact and align well with the current architecture.
+
+| Technique | Topic | Key Metrics | Issue |
+| --------- | ----- | ----------- | ----- |
+${rows.join("\n")}`;
+}
+function generateP2Table(index) {
+  const p2Techniques = getTechniquesByPriority(index, "P2");
+  if (p2Techniques.length === 0) {
+    return "";
+  }
+  const rows = p2Techniques.map(generateTechniqueRow);
+  return `---
+
+## Priority 2 (P2) Techniques
+
+Medium-impact or requiring moderate changes.
+
+| Technique | Topic | Key Metrics | Issue |
+| --------- | ----- | ----------- | ----- |
+${rows.join("\n")}`;
+}
+function generateRecentPapers(index, limit) {
+  const recentPapers = getRecentlyReviewedPapers(index, limit);
+  if (recentPapers.length === 0) {
+    return "";
+  }
+  const rows = recentPapers.map((paper) => {
+    const paperUrl = paper.url ?? "";
+    const title = paperUrl !== "" ? `[${paper.title.replace(/\|/g, "-")}](${paperUrl})` : paper.title.replace(/\|/g, "-");
+    const topic = paper.topics[0] ?? "-";
+    const priority = "-";
+    const dateStr = paper.reviewed_date ?? "-";
+    return `| ${dateStr} | ${title} | ${topic} | ${priority} |`;
+  });
+  return `---
+
+## Recently Reviewed Papers
+
+| Date | Paper | Topic | Priority |
+| ---- | ----- | ----- | -------- |
+${rows.join("\n")}`;
+}
+function generatePapersByTopic(index) {
+  const topics = [
+    "consensus",
+    "routing",
+    "memory",
+    "code-generation",
+    "orchestration"
+  ];
+  const sections = topics.map((topic) => {
+    const papers = getPapersByTopic(index, topic);
+    if (papers.length === 0) {
+      return "";
+    }
+    const paperList = papers.map((paper) => {
+      const paperUrl = paper.url ?? "";
+      const title = paperUrl !== "" ? `[${paper.title}](${paperUrl})` : paper.title;
+      const summaryText = paper.summary?.trim().split("\n")[0] ?? "";
+      const summaryPart = summaryText !== "" ? ` - ${summaryText}` : "";
+      return `- ${title}${summaryPart}`;
+    }).join("\n");
+    return `### ${capitalizeWords(topic.replaceAll("-", " "))} (${String(papers.length)} papers)
+
+${paperList}`;
+  });
+  const nonEmptySections = sections.filter((s) => s.length > 0);
+  if (nonEmptySections.length === 0) {
+    return "";
+  }
+  return `---
+
+## Papers by Topic
+
+${nonEmptySections.join("\n\n")}`;
+}
+function generateGitHubIssues(index) {
+  const techniquesWithIssues = getTechniquesWithIssues(index);
+  if (techniquesWithIssues.length === 0) {
+    return "";
+  }
+  const rows = techniquesWithIssues.map((technique) => {
+    const papers = technique.source_papers.length > 0 ? technique.source_papers.join(", ") : "-";
+    const issueStr = String(technique.implementation_issue ?? 0);
+    return `| #${issueStr} | ${technique.name} | ${papers} |`;
+  });
+  return `---
+
+## GitHub Issues
+
+| Issue | Feature | Related Papers |
+| ----- | ------- | -------------- |
+${rows.join("\n")}`;
+}
+function generateSearchTags(index) {
+  const allTags = /* @__PURE__ */ new Set();
+  for (const technique of index.techniques) {
+    for (const tag of technique.tags) {
+      allTags.add(tag);
+    }
+  }
+  const tagList = Array.from(allTags).sort().slice(0, 20).map((tag) => `\`#${tag}\``).join(" ");
+  return `---
+
+## Search Tags
+
+${tagList}`;
+}
+function generateRegistryFiles(index) {
+  const paperCount = String(index.stats.totalPapers);
+  const techniqueCount = String(index.stats.totalTechniques);
+  return `---
+
+## Registry Files
+
+- [papers.yaml](registry/papers.yaml) - All ${paperCount} papers with metadata
+- [techniques.yaml](registry/techniques.yaml) - All ${techniqueCount} techniques with status
+- [sources.yaml](registry/sources.yaml) - Product docs and other sources`;
+}
+function generateContributingSection() {
+  const dateStr = getTimeProvider().nowDateString();
+  return `---
+
+## How to Contribute
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new research.
+
+---
+
+_Generated from YAML registries. Last updated: ${dateStr} (ET)_`;
+}
+function addSection(sections, section) {
+  if (section !== "") {
+    sections.push(section);
+  }
+}
+function buildOptionalSections(index, opts) {
+  const sections = [];
+  if (opts.includeP1Table) {
+    addSection(sections, generateP1Table(index));
+  }
+  if (opts.includeP2Table) {
+    addSection(sections, generateP2Table(index));
+  }
+  if (opts.includeRecentPapers) {
+    addSection(sections, generateRecentPapers(index, opts.recentPapersLimit));
+  }
+  if (opts.includePapersByTopic) {
+    addSection(sections, generatePapersByTopic(index));
+  }
+  if (opts.includeGitHubIssues) {
+    addSection(sections, generateGitHubIssues(index));
+  }
+  return sections;
+}
+
+// src/indexer/research-index/research-index-generator.ts
+function generateIndexMarkdown(index, options = {}) {
+  try {
+    const opts = { ...DEFAULT_RESEARCH_INDEX_GENERATOR_OPTIONS, ...options };
+    const sections = [
+      generateHeader(index),
+      generateQuickStats(index),
+      generateTopicsTable(index),
+      ...buildOptionalSections(index, opts),
+      generateSearchTags(index),
+      generateRegistryFiles(index),
+      generateContributingSection()
+    ];
+    const markdown = sections.join("\n\n");
+    return { ok: true, value: markdown };
+  } catch (error) {
+    return {
+      ok: false,
+      error: new ResearchIndexGeneratorError(
+        `Failed to generate markdown: ${getErrorMessage(error)}`,
+        error
+      )
+    };
+  }
+}
+function generateStatsJson(index) {
+  return JSON.stringify(
+    {
+      schemaVersion: index.schemaVersion,
+      generatedAt: index.generatedAt,
+      stats: index.stats
+    },
+    null,
+    2
+  );
+}
+function generateSummaryReport(index) {
+  const { stats } = index;
+  const { techniquesByStatus } = stats;
+  const implementedPercent = stats.totalTechniques > 0 ? Math.round(techniquesByStatus.implemented / stats.totalTechniques * 100) : 0;
+  const topicLines = stats.topicStats.map(
+    (t) => `- ${t.topic}: ${String(t.techniqueCount)} techniques, ${String(t.paperCount)} papers`
+  ).join("\n");
+  return `# Research Index Summary
+
+**Generated:** ${index.generatedAt}
+
+## Overview
+- **Total Papers:** ${String(stats.totalPapers)}
+- **Total Techniques:** ${String(stats.totalTechniques)}
+- **Implementation Rate:** ${String(implementedPercent)}%
+
+## Technique Status
+- Implemented: ${String(techniquesByStatus.implemented)}
+- Planned: ${String(techniquesByStatus.planned)}
+- Not Started: ${String(techniquesByStatus.notStarted)}
+- Rejected: ${String(techniquesByStatus.rejected)}
+
+## Evidence Quality Distribution
+${stats.qualityDistribution !== void 0 ? `- High evidence: ${String(stats.qualityDistribution.high)} papers
+- Medium evidence: ${String(stats.qualityDistribution.medium)} papers
+- Low evidence: ${String(stats.qualityDistribution.low)} papers
+- Unscored: ${String(stats.qualityDistribution.unscored)} papers
+- Average quality score: ${String(stats.qualityDistribution.averageScore)}/10` : "- Quality scoring not yet applied"}
+
+## Topics Coverage
+${topicLines}
+`;
+}
+
+// src/cli/research-helpers-index-ops.ts
+function getRegistryPath() {
+  return path3.resolve(process.cwd(), "docs/research/registry");
+}
+function getIndexPath() {
+  return path3.resolve(process.cwd(), "docs/research/RESEARCH_INDEX.md");
+}
+async function handleStatsCommand(options) {
+  const registryPath = getRegistryPath();
+  const result = parseRegistry({ registryPath });
+  if (!result.ok) {
+    return `Error: Failed to parse registry: ${result.error.message}`;
+  }
+  const index = result.value;
+  const formatVal = options["format"];
+  const format = typeof formatVal === "string" ? formatVal : void 0;
+  await Promise.resolve();
+  if (format === "json") {
+    return generateStatsJson(index);
+  }
+  return generateSummaryReport(index);
+}
+async function handleRefreshCommand(options) {
+  const outputVal = options["output"];
+  const outputPath = (typeof outputVal === "string" ? outputVal : void 0) ?? getIndexPath();
+  const registryPath = getRegistryPath();
+  const result = parseRegistry({ registryPath });
+  if (!result.ok) {
+    return `Error: Failed to parse registry: ${result.error.message}`;
+  }
+  const index = result.value;
+  const mdResult = generateIndexMarkdown(index);
+  if (!mdResult.ok) {
+    return `Error: Failed to generate markdown: ${mdResult.error.message}`;
+  }
+  await fs3.mkdir(path3.dirname(outputPath), { recursive: true });
+  await fs3.writeFile(outputPath, mdResult.value, "utf-8");
+  const stats = index.stats;
+  return [
+    `Research index regenerated successfully`,
+    `  Output: ${outputPath}`,
+    `  Papers: ${String(stats.totalPapers)}`,
+    `  Techniques: ${String(stats.totalTechniques)}`,
+    `  Implemented: ${String(stats.techniquesByStatus.implemented)}`
+  ].join("\n");
+}
+async function handleCheckCommand() {
+  const indexPath = getIndexPath();
+  try {
+    await fs3.access(indexPath);
+  } catch {
+    return `Error: Research index not found: ${indexPath}. Run 'nexus-agents research refresh' first.`;
+  }
+  const registryPath = getRegistryPath();
+  const result = parseRegistry({ registryPath });
+  if (!result.ok) {
+    return `Error: Failed to parse registry: ${result.error.message}`;
+  }
+  const mdResult = generateIndexMarkdown(result.value);
+  if (!mdResult.ok) {
+    return `Error: Failed to generate markdown: ${mdResult.error.message}`;
+  }
+  const existingContent = await fs3.readFile(indexPath, "utf-8");
+  const freshContent = mdResult.value;
+  const normalize = (s) => s.replace(/\s+/g, " ").trim();
+  const isFresh = normalize(existingContent) === normalize(freshContent);
+  if (isFresh) {
+    return `Research index is up to date (${String(result.value.stats.totalTechniques)} techniques)`;
+  }
+  return `Research index is out of date. Run "nexus-agents research refresh" to update.`;
+}
+
+// src/cli/research-helpers-issues.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function formatResearchIssueBody(findings, voteResult) {
+  const lines = [];
+  lines.push("## Research Findings");
+  lines.push("");
+  for (const finding of findings) {
+    lines.push(`### ${finding.title}`);
+    lines.push("");
+    lines.push(`- **Source:** ${finding.source}`);
+    lines.push(`- **URL:** ${finding.url}`);
+    lines.push(`- **Relevance:** ${finding.relevance}`);
+    if (finding.priority !== void 0) {
+      lines.push(`- **Priority:** ${finding.priority}`);
+    }
+    lines.push("");
+    lines.push(finding.description);
+    lines.push("");
+  }
+  if (voteResult !== void 0) {
+    lines.push("## Consensus Vote Result");
+    lines.push("");
+    lines.push(`- **Decision:** ${voteResult.decision}`);
+    lines.push(`- **Approval:** ${String(voteResult.approvalPercentage)}%`);
+    lines.push(`- **Strategy:** ${voteResult.strategy}`);
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("*Created by nexus-agents research workflow*");
+  return lines.join("\n");
+}
+function buildIssueArgs(options) {
+  const args = ["issue", "create", "--title", options.title, "--body", options.body];
+  if (options.labels.length > 0) args.push("--label", options.labels.join(","));
+  if (options.assignee !== void 0) args.push("--assignee", options.assignee);
+  return args;
+}
+function mapGhError(message) {
+  if (message.includes("not found") || message.includes("ENOENT")) {
+    return { code: "GH_NOT_FOUND", message: "GitHub CLI (gh) not found" };
+  }
+  if (message.includes("auth") || message.includes("401")) {
+    return { code: "GH_AUTH_FAILED", message: "GitHub CLI not authenticated" };
+  }
+  return { code: "GH_ERROR", message: `Failed to create issue: ${message}` };
+}
+async function createResearchIssue(options) {
+  try {
+    const { stdout } = await execFileAsync("gh", buildIssueArgs(options), {
+      timeout: CLI_SUBPROCESS_TIMEOUTS.ghCommandMs
+    });
+    const url = stdout.trim();
+    return { ok: true, value: { success: true, url, message: `Issue created: ${url}` } };
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return { ok: false, error: mapGhError(message) };
+  }
+}
+
+// src/context/context-retriever.ts
+var DEFAULT_LIMIT = 5;
+async function getContextForTask(options) {
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const logger = options.logger ?? createLogger({ component: "ContextRetriever" });
+  const [
+    beliefs,
+    similarMemories,
+    recentLearnings,
+    experiencePatterns,
+    outcomes,
+    researchInsights
+  ] = await Promise.all([
+    fetchBeliefs(options.task, limit, logger),
+    fetchSimilarMemories(options.task, limit, logger),
+    fetchRecentLearnings(options.task, limit, logger),
+    fetchExperiencePatterns(options.task, limit, logger),
+    fetchOutcomes(options.category, logger),
+    fetchResearchInsights(options.task, limit, logger)
+  ]);
+  const priorStrategies = fetchPriorStrategies(options.category, limit, logger);
+  return {
+    beliefs,
+    similarMemories,
+    recentLearnings,
+    experiencePatterns,
+    outcomes,
+    priorStrategies,
+    researchInsights
+  };
+}
+var MIN_RELEVANCE_TOKEN = 4;
+function selectRelevantResearch(techniques, task, limit) {
+  const taskTokens = tokenize(task);
+  if (taskTokens.size === 0) return [];
+  const matches = [];
+  for (const t of techniques) {
+    const fieldTokens = tokenize(`${t.name} ${t.topic}`);
+    let hit = false;
+    for (const tok of fieldTokens) {
+      if (taskTokens.has(tok)) {
+        hit = true;
+        break;
+      }
+    }
+    if (hit) {
+      matches.push(t);
+      if (matches.length >= limit) break;
+    }
+  }
+  return matches;
+}
+function tokenize(text) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length >= MIN_RELEVANCE_TOKEN) tokens.add(raw);
+  }
+  return tokens;
+}
+async function fetchResearchInsights(task, limit, logger) {
+  try {
+    const result = await getResearchStatus({ status: "all", format: "json" });
+    if (!result.success) return [];
+    return selectRelevantResearch(result.techniques, task, limit);
+  } catch (error) {
+    logger.debug("ContextRetriever: research insights fetch failed", {
+      error: formatError(error)
+    });
+    return [];
+  }
+}
+function fetchPriorStrategies(category, limit, logger) {
+  try {
+    const all = loadPersistedRules();
+    return all.filter((r) => r.status === "active" && !r.tainted).filter((r) => r.category === category || r.category === "*").slice(0, limit);
+  } catch (error) {
+    logger.debug("ContextRetriever: prior-strategies fetch failed", {
+      error: formatError(error)
+    });
+    return [];
+  }
+}
+async function fetchBeliefs(task, limit, logger) {
+  try {
+    const tm = getToolMemory(logger);
+    const beliefs = tm.getBeliefMemory();
+    const result = await beliefs.recallBySubject(task, limit);
+    return result.ok ? result.value : [];
+  } catch (error) {
+    logger.debug("ContextRetriever: belief fetch failed", { error: formatError(error) });
+    return [];
+  }
+}
+async function fetchSimilarMemories(task, limit, logger) {
+  try {
+    const tm = getToolMemory(logger);
+    const agentic = tm.getAgenticMemoryBackend();
+    if (agentic === null) return [];
+    const result = await agentic.searchAgentic(task, limit);
+    return result.ok ? result.value : [];
+  } catch (error) {
+    logger.debug("ContextRetriever: agentic search failed", { error: formatError(error) });
+    return [];
+  }
+}
+async function fetchRecentLearnings(task, limit, logger) {
+  try {
+    const tm = getToolMemory(logger);
+    const adaptive = tm.getAdaptiveMemoryBackend();
+    if (adaptive === null) return [];
+    const result = await adaptive.retrieveByPriority({ query: task, limit });
+    return result.ok ? result.value : [];
+  } catch (error) {
+    logger.debug("ContextRetriever: adaptive fetch failed", { error: formatError(error) });
+    return [];
+  }
+}
+function fetchExperiencePatterns(task, limit, logger) {
+  try {
+    const tm = getToolMemory(logger);
+    const mobimem = tm.getMobiMem();
+    if (mobimem === null) return Promise.resolve([]);
+    return Promise.resolve(mobimem.experience.findPatterns(task, limit));
+  } catch (error) {
+    logger.debug("ContextRetriever: mobimem fetch failed", { error: formatError(error) });
+    return Promise.resolve([]);
+  }
+}
+function fetchOutcomes(category, logger) {
+  try {
+    const store = getOutcomeStore();
+    return Promise.resolve(store.summarize({ category }));
+  } catch (error) {
+    logger.debug("ContextRetriever: outcomes fetch failed", { error: formatError(error) });
+    return Promise.resolve(null);
+  }
+}
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function inferTaskCategory(task) {
+  const t = task.toLowerCase();
+  if (/security|vulnerab|cve|threat|owasp|injection|xss/.test(t)) return "security_review";
+  if (/architect|design doc|rfc|adr|system design/.test(t)) return "architecture";
+  if (/test|spec|coverage|vitest|jest|pytest/.test(t)) return "testing";
+  if (/review|audit|critique|feedback/.test(t)) return "code_review";
+  if (/docs|documentation|readme|tutorial|guide/.test(t)) return "documentation";
+  if (/plan|roadmap|epic|sprint|breakdown/.test(t)) return "planning";
+  if (/research|investigate|explore|survey|analyze/.test(t)) return "research";
+  if (/deploy| ci |\bcd\b|pipeline|kubernetes|docker|infra|terraform/.test(t)) return "devops";
+  if (/implement|build|create|add|refactor|fix|bug|feature/.test(t)) return "code_generation";
+  return "exploration";
+}
+function summarizeContextForPrompt(ctx) {
+  const sections = [];
+  if (ctx.beliefs.length > 0) {
+    const lines = ctx.beliefs.slice(0, 5).map((b) => `- ${b.subject} ${b.predicate} ${b.object} (confidence: ${b.confidence})`);
+    sections.push(`### Beliefs
+${lines.join("\n")}`);
+  }
+  if (ctx.similarMemories.length > 0) {
+    const lines = ctx.similarMemories.slice(0, 3).map((m) => `- ${m.attributes.contextDescription}`);
+    sections.push(`### Similar prior work
+${lines.join("\n")}`);
+  }
+  if (ctx.experiencePatterns.length > 0) {
+    const lines = ctx.experiencePatterns.slice(0, 3).map(
+      (p) => `- ${p.taskType}: ${(p.successRate * 100).toFixed(0)}% success over ${String(p.attemptCount)} attempts`
+    );
+    sections.push(`### Observed patterns
+${lines.join("\n")}`);
+  }
+  if (ctx.outcomes !== null && ctx.outcomes.totalTasks > 0) {
+    sections.push(
+      `### Outcomes for this category
+- ${String(ctx.outcomes.totalTasks)} prior tasks, ${(ctx.outcomes.successRate * 100).toFixed(0)}% success`
+    );
+  }
+  if (ctx.researchInsights.length > 0) {
+    const lines = ctx.researchInsights.slice(0, 5).map((r) => `- ${r.name} (${r.status}) \u2014 ${r.topic}`);
+    sections.push(`### Prior research on this topic
+${lines.join("\n")}`);
+  }
+  return sections.length === 0 ? "" : `## Prior Context (Nexus Memory)
+${sections.join("\n\n")}`;
+}
+
+export {
+  RulesSnapshotSchema,
+  PersistentStrategyDistiller,
+  getResearchStatus,
+  formatStatusResult,
+  findOverlaps,
+  formatOverlapResult,
+  paperExists,
+  addResearchPaper,
+  fetchSource,
+  discoverGitHubRepos,
+  discoverArxiv,
+  discoverGoogleAI,
+  discoverMetaFAIR,
+  discoverMicrosoftResearch,
+  discoverDeepMind,
+  loadSourcesRegistry,
+  saveSourcesRegistry,
+  sourceExistsInRegistry,
+  addSourceToRegistry,
+  discoverSemanticScholar,
+  discoverPapersWithCode,
+  discoverOpenAlex,
+  rankDiscoveredItems,
+  PaperStatusSchema,
+  computeSourceQualityScore,
+  parseRegistry,
+  generateStatsJson,
+  handleStatsCommand,
+  handleRefreshCommand,
+  handleCheckCommand,
+  formatResearchIssueBody,
+  createResearchIssue,
+  getContextForTask,
+  selectRelevantResearch,
+  inferTaskCategory,
+  summarizeContextForPrompt
+};
+//# sourceMappingURL=chunk-ATI7W2FT.js.map