@cgh567/agent 2.4.2 → 2.4.4

package/daemon/lib/goal-research-pipeline.js

@@ -0,0 +1,644 @@
+'use strict';
+/**
+ * daemon/lib/goal-research-pipeline.js — GoalResearchPipeline
+ *
+ * Runs 10 parallel research sources for a CompanyGoal before the Three Cs
+ * interpretation loop fires. Writes a GoalResearchBrief node to Memgraph
+ * and links it to the CompanyGoal via HAS_RESEARCH edge.
+ *
+ * Called by:
+ *   - wizard-engine.js (Step 2 submit — fires async after company created)
+ *   - hbo-bridge.js tickGoalDecompose() — if brief missing/stale, research first
+ *
+ * Design principles:
+ *   - Idempotent: skips if fresh brief (< 24h) already exists for this goal
+ *   - Fail-open: any source failure returns null for that source — pipeline continues
+ *   - 15s total timeout via Promise.race on the full parallel batch
+ *   - No new infrastructure: SearXNG via hbo-research-bridge, Memgraph via mgQuery
+ *   - Pure CJS — no TypeScript, matches daemon/lib/ convention
+ */
+
+const path   = require('path');
+const crypto = require('crypto');
+
+const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const RESEARCH_TIMEOUT_MS = 15000;   // 15s total
+
+// ── Lazy-loaded deps ─────────────────────────────────────────────────────────
+
+function _getResearchBridge(mg, companyId) {
+  try {
+    const { HBOResearchBridge } = require('./hbo-research-bridge');
+    // Pass positional (mgQuery, companyId) — bridge uses companyId for log labels only
+    return new HBOResearchBridge(mg, companyId || 'pipeline');
+  } catch (_) {
+    return null;
+  }
+}
+
+let _isBusinessSignal = null;
+function _getIsBusinessSignal() {
+  if (_isBusinessSignal !== null) return _isBusinessSignal;
+  try {
+    _isBusinessSignal = require('./mental-model-service').isBusinessSignal;
+  } catch (_) {
+    _isBusinessSignal = () => true; // default to business framing if import fails
+  }
+  return _isBusinessSignal;
+}
+
+// ── Logging ───────────────────────────────────────────────────────────────────
+
+function _log(level, msg, extra) {
+  const entry = JSON.stringify({ ts: new Date().toISOString(), level, module: 'goal-research-pipeline', msg, ...extra });
+  process.stdout.write(entry + '\n');
+}
+
+// ── Source runners ────────────────────────────────────────────────────────────
+
+/**
+ * SearXNG web sources (sources 2–5).
+ * Returns { marketContext, competitorContext, strategyContext, newsContext }.
+ */
+async function _runWebSources(goalTitle, companyName, bridge) {
+  if (!bridge || typeof bridge.search !== 'function') {
+    return { marketContext: null, competitorContext: null, strategyContext: null, newsContext: null };
+  }
+
+  const industry = companyName ? `${companyName} industry` : '';
+  const [market, competitors, strategy, news] = await Promise.allSettled([
+    bridge.search(`${goalTitle} ${industry} benchmark market data 2024 2025`),
+    bridge.search(`${goalTitle} competitors strategies how to achieve`),
+    bridge.search(`${goalTitle} OKR framework best practices strategy 2024`),
+    companyName ? bridge.search(`${companyName} news growth 2024 2025`) : Promise.resolve(null),
+  ]);
+
+  const _fmt = (r) => {
+    if (r.status !== 'fulfilled' || !r.value?.results?.length) return null;
+    return r.value.results.slice(0, 3)
+      .map(x => `- ${(x.title || '').slice(0, 100)}: ${(x.content || '').slice(0, 200)}`)
+      .join('\n');
+  };
+
+  return {
+    marketContext:     _fmt(market),
+    competitorContext: _fmt(competitors),
+    strategyContext:   _fmt(strategy),
+    newsContext:       _fmt(news),
+  };
+}
+
+/**
+ * Company website crawl (source 1).
+ * Returns companyWebsite string or null.
+ */
+async function _runWebsiteCrawl(domain, bridge) {
+  if (!domain || !bridge || typeof bridge.crawl !== 'function') return null;
+  try {
+    const url = domain.startsWith('http') ? domain : `https://${domain}`;
+    const result = await bridge.crawl(url, { timeout: 8000, maxChars: 2000 });
+    if (!result || !result.text) return null;
+    return result.text.slice(0, 2000);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Memgraph CRM context (source 6).
+ * Reads Lead/Opportunity/Account nodes for the company.
+ */
+async function _runCrmContext(companyId, mg) {
+  try {
+    const result = await mg(
+      `MATCH (n)
+       WHERE (n:Lead OR n:Opportunity OR n:Account) AND n.companyId = $cid
+       RETURN labels(n)[0] AS type, n.name AS name, n.value AS value,
+              n.status AS status, n.stage AS stage
+       ORDER BY n.createdAt DESC LIMIT 20`,
+      { cid: companyId }
+    );
+    const rows = result?.rows ?? [];
+    if (!rows.length) return null;
+    const lines = rows.map(r => {
+      const [type, name, value, status, stage] = Array.isArray(r) ? r : [r.type, r.name, r.value, r.status, r.stage];
+      const parts = [type, name].filter(Boolean);
+      if (value)  parts.push(`$${value}`);
+      if (stage || status) parts.push(stage || status);
+      return `- ${parts.join(' | ')}`;
+    });
+    return `CRM pipeline (${rows.length} records):\n${lines.join('\n')}`;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Prior task results (source 7).
+ * Reads recent TaskResult nodes that mention the goal domain.
+ */
+async function _runPriorTaskResults(companyId, goalTitle, mg) {
+  try {
+    const keywords = goalTitle.split(/\s+/).filter(w => w.length > 3).slice(0, 3);
+    if (!keywords.length) return null;
+    // Build a simple WHERE clause checking result text for any keyword
+    const result = await mg(
+      `MATCH (tr:TaskResult {companyId: $cid})
+       WHERE tr.summary IS NOT NULL
+       RETURN tr.summary AS summary, tr.createdAt AS createdAt
+       ORDER BY tr.createdAt DESC LIMIT 10`,
+      { cid: companyId }
+    );
+    const rows = result?.rows ?? [];
+    if (!rows.length) return null;
+    // Filter client-side for keyword relevance
+    const kw = keywords.map(k => k.toLowerCase());
+    const relevant = rows.filter(r => {
+      const text = (Array.isArray(r) ? r[0] : r.summary || '').toLowerCase();
+      return kw.some(k => text.includes(k));
+    }).slice(0, 5);
+    if (!relevant.length) return null;
+    return relevant.map(r => `- ${(Array.isArray(r) ? r[0] : r.summary || '').slice(0, 200)}`).join('\n');
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Company beliefs context (source 8).
+ * Reads confirmed CompanyBelief nodes.
+ */
+async function _runBeliefsContext(companyId, mg) {
+  try {
+    const result = await mg(
+      `MATCH (cb:CompanyBelief {companyId: $cid, status: 'confirmed'})
+       RETURN cb.question AS question, cb.answer AS answer
+       ORDER BY cb.confirmedAt DESC LIMIT 10`,
+      { cid: companyId }
+    );
+    const rows = result?.rows ?? [];
+    if (!rows.length) return null;
+    return rows.map(r => {
+      const [q, a] = Array.isArray(r) ? r : [r.question, r.answer];
+      return `- Q: ${(q || '').slice(0, 150)}\n  A: ${(a || '').slice(0, 200)}`;
+    }).join('\n');
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Department plans context (source 9).
+ * Reads SystemAim.strategicDirectives and active GoalPillar nodes.
+ */
+async function _runDepartmentPlansContext(companyId, mg) {
+  try {
+    const [aimResult, pillarResult] = await Promise.allSettled([
+      mg(
+        `MATCH (sa:SystemAim {companyId: $cid})
+         RETURN sa.mission AS mission, sa.strategicDirectives AS directives LIMIT 1`,
+        { cid: companyId }
+      ),
+      mg(
+        `MATCH (gp:GoalPillar {companyId: $cid})
+         WHERE gp.status IN ['active', 'in_progress']
+         RETURN gp.name AS name, gp.description AS desc
+         ORDER BY gp.createdAt DESC LIMIT 8`,
+        { cid: companyId }
+      ),
+    ]);
+
+    const parts = [];
+    if (aimResult.status === 'fulfilled') {
+      const row = aimResult.value?.rows?.[0];
+      if (row) {
+        const [mission, directives] = Array.isArray(row) ? row : [row.mission, row.directives];
+        if (mission) parts.push(`Mission: ${String(mission).slice(0, 300)}`);
+        if (directives) {
+          const dirs = Array.isArray(directives) ? directives : [directives];
+          parts.push(`Strategic directives:\n${dirs.slice(0, 5).map(d => `- ${String(d).slice(0, 150)}`).join('\n')}`);
+        }
+      }
+    }
+    if (pillarResult.status === 'fulfilled') {
+      const rows = pillarResult.value?.rows ?? [];
+      if (rows.length) {
+        parts.push(`Active pillars:\n${rows.map(r => {
+          const [name, desc] = Array.isArray(r) ? r : [r.name, r.desc];
+          return `- ${name || ''}: ${(desc || '').slice(0, 100)}`;
+        }).join('\n')}`);
+      }
+    }
+    return parts.length ? parts.join('\n\n') : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Industry-specific tournament candidate strategies.
+ * Keys are industry slugs matching SystemAim.industry values.
+ */
+const INDUSTRY_CANDIDATES = {
+  'professional-services/tax': [
+    { label: 'Client acquisition via referral network and trust-building' },
+    { label: 'Regulatory compliance automation — ZIMRA/IRS/HMRC filing efficiency' },
+    { label: 'Self-service digital portal reducing manual client touchpoints' },
+    { label: 'SMB market penetration via affordable tiered pricing' },
+    { label: 'WhatsApp and mobile-native service delivery for emerging markets' },
+  ],
+  'professional-services/legal': [
+    { label: 'Contract automation and document template library' },
+    { label: 'Compliance monitoring for regulatory changes affecting clients' },
+    { label: 'Referral network expansion via professional associations' },
+    { label: 'Subscription retainer model for recurring legal advisory' },
+    { label: 'Digital client portal for document exchange and status tracking' },
+  ],
+  'healthcare': [
+    { label: 'Patient acquisition via community outreach and referral programs' },
+    { label: 'Telehealth expansion to reduce access barriers' },
+    { label: 'Preventive care program to improve patient outcomes and retention' },
+    { label: 'Insurance and billing process automation to reduce administrative burden' },
+    { label: 'Specialist partnership network for referral and care coordination' },
+  ],
+  'research-platform': [
+    { label: 'Participant pool expansion via WhatsApp and community networks' },
+    { label: 'Researcher onboarding automation to reduce time-to-first-study' },
+    { label: 'Platform marketplace connecting researchers with participant segments' },
+    { label: 'Longitudinal study capability to increase researcher stickiness' },
+    { label: 'Academic institution partnerships for credibility and volume' },
+  ],
+  'saas/b2b': [
+    { label: 'Product-led growth — feature-driven acquisition and retention' },
+    { label: 'Revenue expansion — upsell + cross-sell to existing accounts' },
+    { label: 'New market penetration — target new ICP segment' },
+    { label: 'Operational efficiency — reduce costs and improve margins' },
+    { label: 'Top-down goal cascade — CEO decomposes to department OKRs' },
+  ],
+  'ecommerce': [
+    { label: 'Conversion rate optimization via UX and checkout improvements' },
+    { label: 'Customer lifetime value expansion via loyalty and subscription' },
+    { label: 'Marketplace expansion to new channels and geographies' },
+    { label: 'Supply chain efficiency to improve margins and delivery speed' },
+    { label: 'Influencer and community-led acquisition strategy' },
+  ],
+};
+
+/**
+ * Idea tournament (source 10).
+ * Generates 5 strategic approaches and runs a tournament.
+ * Returns { winner, rankings, hint }.
+ */
+async function _runTournament(goalTitle, companyId, bridge, mg) {
+  if (!bridge || typeof bridge.runTournament !== 'function') {
+    return { tournamentWinner: null, tournamentRankings: null, tournamentHint: null };
+  }
+
+  // Read industry from SystemAim for domain-aware candidates
+  let industry = null;
+  if (mg) {
+    try {
+      const aimRes = await mg(
+        `MATCH (sa:SystemAim {companyId: $cid}) RETURN sa.industry AS industry LIMIT 1`,
+        { cid: companyId }
+      );
+      industry = aimRes?.rows?.[0]?.[0] ?? aimRes?.rows?.[0]?.industry ?? null;
+    } catch (_) {}
+  }
+
+  // Generate candidate approaches based on the goal
+  const isBusinessSignal = _getIsBusinessSignal();
+  const isBusiness = isBusinessSignal(goalTitle);
+
+  // Determine candidates from industry if available, fall back to generic
+  let candidates;
+  if (industry && INDUSTRY_CANDIDATES[industry]) {
+    candidates = INDUSTRY_CANDIDATES[industry];
+  } else if (industry) {
+    // Check prefix match (e.g. 'professional-services/consulting' matches 'professional-services/tax' patterns)
+    const prefix = Object.keys(INDUSTRY_CANDIDATES).find(k => industry.startsWith(k.split('/')[0]));
+    candidates = prefix ? INDUSTRY_CANDIDATES[prefix] : null;
+  }
+  if (!candidates) {
+    // Generic fallback — existing behaviour
+    candidates = isBusiness
+      ? [
+          { label: 'Top-down goal cascade — CEO decomposes to department OKRs' },
+          { label: 'Revenue expansion — upsell + cross-sell to existing accounts' },
+          { label: 'New market penetration — target new ICP segment' },
+          { label: 'Operational efficiency — reduce costs and improve margins' },
+          { label: 'Product-led growth — feature-driven acquisition and retention' },
+        ]
+      : [
+          { label: 'Iterative improvement — incremental changes with fast feedback' },
+          { label: 'Systematic approach — structured planning and execution' },
+          { label: 'Parallel workstreams — split across multiple teams' },
+          { label: 'Risk-first approach — address blockers before building' },
+          { label: 'MVP-first approach — ship minimal version, learn, iterate' },
+        ];
+  }
+
+  try {
+    const result = await bridge.runTournament({
+      goal: goalTitle,
+      criteria: ['feasibility', 'impact', 'speed', 'alignment'],
+      candidates,
+      timeoutSeconds: 12, // must be less than RESEARCH_TIMEOUT_MS (15s) so result can be processed
+      goalId: companyId,
+    });
+
+    if (!result || !result.winner) {
+      return { tournamentWinner: null, tournamentRankings: null, tournamentHint: null };
+    }
+
+    return {
+      tournamentWinner:   result.winner,
+      tournamentRankings: JSON.stringify(result.rankings?.slice(0, 5) || []),
+      tournamentHint:     result.confidence ? `${Math.round(result.confidence * 100)}% confidence` : null,
+    };
+  } catch (_) {
+    return { tournamentWinner: null, tournamentRankings: null, tournamentHint: null };
+  }
+}
+
+// ── Verification rubric generator ─────────────────────────────────────────────
+
+/**
+ * generateRubric — Build a verification rubric from assembled research results.
+ * Produces a structured checklist agents can use to verify goal completion.
+ *
+ * @param {{ marketContext, competitorContext, crmContext, tournamentWinner, beliefsContext }} results
+ * @returns {{ checks: string[], dataSources: string[], completionCriteria: string }}
+ */
+function generateRubric(results) {
+  const checks = [];
+  const dataSources = [];
+
+  if (results.marketContext) {
+    checks.push('Market data reviewed and benchmark targets set');
+    dataSources.push('market_research');
+  }
+  if (results.competitorContext) {
+    checks.push('Competitor analysis completed and differentiation identified');
+    dataSources.push('competitor_analysis');
+  }
+  if (results.crmContext) {
+    checks.push('CRM pipeline reviewed — accounts and opportunities aligned to goal');
+    dataSources.push('crm');
+  }
+  if (results.tournamentWinner) {
+    checks.push(`Strategy selected via tournament: ${String(results.tournamentWinner).slice(0, 80)}`);
+    dataSources.push('strategy_tournament');
+  }
+  if (results.beliefsContext) {
+    checks.push('Company beliefs and constraints reviewed');
+    dataSources.push('company_beliefs');
+  }
+  if (results.priorWorkContext) {
+    checks.push('Prior task results reviewed for continuity');
+    dataSources.push('prior_work');
+  }
+
+  // Always include baseline checks
+  checks.push('Goal decomposition completed by CEO agent');
+  checks.push('Department OKRs aligned to company goal');
+  checks.push('Progress tracked in Memgraph via Task completion');
+
+  return {
+    checks,
+    dataSources,
+    completionCriteria: `All ${checks.length} checklist items satisfied with evidence in Memgraph`,
+  };
+}
+
+
+
+class GoalResearchPipeline {
+  /**
+   * @param {Function} mgQuery  - async (cypher, params) => { keys, rows }
+   */
+  constructor(mgQuery) {
+    this.mg = mgQuery;
+  }
+
+  /**
+   * research — Run all 10 sources in parallel and write GoalResearchBrief to Memgraph.
+   *
+   * @param {string} goalId      - CompanyGoal node ID
+   * @param {string} goalTitle   - The goal text (used for queries)
+   * @param {string} companyId   - Company ID
+   * @param {{ domain?: string, companyName?: string, force?: boolean }} [options]
+   * @returns {Promise<string|null>} - The GoalResearchBrief node ID, or null on failure
+   */
+  async research(goalId, goalTitle, companyId, options = {}) {
+    const { domain, companyName, force = false } = options;
+
+    if (!goalId || !goalTitle || !companyId) {
+      _log('warn', 'research: missing required params', { goalId, companyId });
+      return null;
+    }
+
+    // ── Idempotency check: skip if fresh brief already exists ──────────────
+    if (!force) {
+      try {
+        const existing = await this.mg(
+          `MATCH (cg:CompanyGoal {id: $gid})-[:HAS_RESEARCH]->(grb:GoalResearchBrief)
+           WHERE grb.createdAt >= localdatetime() - duration({hours: 24})
+           RETURN grb.id AS id LIMIT 1`,
+          { gid: goalId }
+        );
+        if (existing?.rows?.length) {
+          const existingId = existing.rows[0][0] ?? existing.rows[0].id;
+          _log('info', `research: fresh brief already exists — skipping`, { goalId, briefId: existingId });
+          return existingId;
+        }
+      } catch (_) { /* non-fatal — proceed with research */ }
+    }
+
+    const briefId = `grb:${goalId}:${Date.now()}`;
+    const bridge  = _getResearchBridge(this.mg, companyId);
+
+    _log('info', `research: starting 10-source parallel research`, { goalId, goalTitle: goalTitle.slice(0, 80) });
+
+    // ── Run all sources in parallel with 15s total timeout ─────────────────
+    let results;
+    try {
+      results = await Promise.race([
+        Promise.allSettled([
+          /* 1 */ _runWebsiteCrawl(domain, bridge),
+          /* 2-5 */ _runWebSources(goalTitle, companyName, bridge),
+          /* 6 */ _runCrmContext(companyId, this.mg),
+          /* 7 */ _runPriorTaskResults(companyId, goalTitle, this.mg),
+          /* 8 */ _runBeliefsContext(companyId, this.mg),
+          /* 9 */ _runDepartmentPlansContext(companyId, this.mg),
+          /* 10 */ _runTournament(goalTitle, companyId, bridge, this.mg),
+        ]),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('research_timeout_15s')), RESEARCH_TIMEOUT_MS)
+        ),
+      ]);
+    } catch (err) {
+      _log('warn', `research: timeout or error — writing partial brief`, { goalId, err: err.message });
+      // On timeout, we still write whatever was collected (all settled values up to timeout)
+      // Promise.allSettled with a race: any pending promises resolve to their settled state
+      // We write a minimal brief so the pipeline isn't blocked.
+      results = [
+        { status: 'rejected', reason: new Error('timeout') },
+        { status: 'fulfilled', value: { marketContext: null, competitorContext: null, strategyContext: null, newsContext: null } },
+        { status: 'rejected', reason: new Error('timeout') },
+        { status: 'rejected', reason: new Error('timeout') },
+        { status: 'rejected', reason: new Error('timeout') },
+        { status: 'rejected', reason: new Error('timeout') },
+        { status: 'fulfilled', value: { tournamentWinner: null, tournamentRankings: null, tournamentHint: null } },
+      ];
+    }
+
+    // ── Unpack results ─────────────────────────────────────────────────────
+    const [websiteR, webR, crmR, priorR, beliefsR, deptR, tournamentR] = results;
+
+    const companyWebsite   = websiteR.status === 'fulfilled'   ? websiteR.value          : null;
+    const webCtx           = webR.status === 'fulfilled'       ? webR.value              : {};
+    const crmContext       = crmR.status === 'fulfilled'       ? crmR.value              : null;
+    const priorWorkContext = priorR.status === 'fulfilled'     ? priorR.value            : null;
+    const beliefsContext   = beliefsR.status === 'fulfilled'   ? beliefsR.value          : null;
+    const deptContext      = deptR.status === 'fulfilled'      ? deptR.value             : null;
+    const tournamentCtx    = tournamentR.status === 'fulfilled' ? tournamentR.value      : {};
+
+    const { marketContext = null, competitorContext = null, strategyContext = null, newsContext = null } = webCtx || {};
+    const { tournamentWinner = null, tournamentRankings = null, tournamentHint = null } = tournamentCtx || {};
+
+    // ── Compute confidence score ───────────────────────────────────────────
+    const sourcesUsed = [
+      companyWebsite, marketContext, competitorContext, strategyContext, newsContext,
+      crmContext, priorWorkContext, beliefsContext, deptContext, tournamentWinner,
+    ].filter(Boolean).length;
+    const confidenceScore = Math.round((sourcesUsed / 10) * 100);
+
+    // ── Generate verification rubric ───────────────────────────────────────
+    const verificationRubric = generateRubric({
+      marketContext, competitorContext, crmContext: crmContext,
+      tournamentWinner, beliefsContext, priorWorkContext,
+    });
+
+    // ── Write GoalResearchBrief node ───────────────────────────────────────
+    try {
+      await this.mg(
+        `MERGE (grb:GoalResearchBrief {id: $id})
+         ON CREATE SET
+           grb.goalId                = $goalId,
+           grb.companyId             = $companyId,
+           grb.companyWebsite        = $companyWebsite,
+           grb.marketContext         = $marketContext,
+           grb.competitorContext     = $competitorContext,
+           grb.benchmarks            = $strategyContext,
+           grb.newsContext           = $newsContext,
+           grb.crmContext            = $crmContext,
+           grb.priorWorkContext      = $priorWorkContext,
+           grb.beliefsContext        = $beliefsContext,
+           grb.departmentPlansContext= $deptContext,
+           grb.tournamentWinner      = $tournamentWinner,
+           grb.tournamentRankings    = $tournamentRankings,
+           grb.tournamentHint        = $tournamentHint,
+           grb.confidenceScore       = $confidenceScore,
+           grb.sourcesUsed           = $sourcesUsed,
+           grb.verificationRubric    = $verificationRubric,
+           grb.dataCompleteness      = $dataCompleteness,
+           grb.confirmedByUser       = false,
+           grb.corrections           = [],
+           grb.createdAt             = localdatetime(),
+           grb.expiresAt             = localdatetime() + duration({hours: 24})
+         ON MATCH SET
+           grb.updatedAt             = localdatetime()`,
+        {
+          id: briefId, goalId, companyId,
+          companyWebsite:    companyWebsite    ? companyWebsite.slice(0, 3000)    : null,
+          marketContext:     marketContext     ? marketContext.slice(0, 2000)     : null,
+          competitorContext: competitorContext ? competitorContext.slice(0, 2000) : null,
+          strategyContext:   strategyContext   ? strategyContext.slice(0, 2000)   : null,
+          newsContext:       newsContext       ? newsContext.slice(0, 1000)       : null,
+          crmContext:        crmContext        ? crmContext.slice(0, 2000)        : null,
+          priorWorkContext:  priorWorkContext  ? priorWorkContext.slice(0, 2000)  : null,
+          beliefsContext:    beliefsContext    ? beliefsContext.slice(0, 2000)    : null,
+          deptContext:       deptContext       ? deptContext.slice(0, 2000)       : null,
+          tournamentWinner:  tournamentWinner  ? String(tournamentWinner).slice(0, 500)  : null,
+          tournamentRankings: tournamentRankings ? String(tournamentRankings).slice(0, 2000) : null,
+          tournamentHint:    tournamentHint    ? String(tournamentHint).slice(0, 200)    : null,
+          confidenceScore, sourcesUsed,
+          verificationRubric: JSON.stringify(verificationRubric),
+          dataCompleteness: sourcesUsed / 10,
+        }
+      );
+
+      // Link brief to goal
+      await this.mg(
+        `MATCH (cg:CompanyGoal {id: $goalId}), (grb:GoalResearchBrief {id: $briefId})
+         MERGE (cg)-[:HAS_RESEARCH]->(grb)`,
+        { goalId, briefId }
+      );
+
+      _log('info', `research: brief written`, {
+        goalId, briefId, sourcesUsed, confidenceScore,
+        tournamentWinner: tournamentWinner ? String(tournamentWinner).slice(0, 60) : null,
+      });
+
+      return briefId;
+    } catch (err) {
+      _log('warn', `research: failed to write brief to Memgraph`, { goalId, err: err.message });
+      return null;
+    }
+  }
+
+  /**
+   * getLatestBrief — Retrieve the most recent GoalResearchBrief for a goal.
+   * Returns the brief object or null.
+   */
+  async getLatestBrief(goalId) {
+    try {
+      const result = await this.mg(
+        `MATCH (cg:CompanyGoal {id: $gid})-[:HAS_RESEARCH]->(grb:GoalResearchBrief)
+         RETURN grb
+         ORDER BY grb.createdAt DESC LIMIT 1`,
+        { gid: goalId }
+      );
+      const row = result?.rows?.[0];
+      if (!row) return null;
+      // Memgraph returns node properties as an object in rows[0][0]
+      const node = Array.isArray(row) ? row[0] : row;
+      return node?.properties ?? node ?? null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * applyCorrection — Append a user correction to the brief.
+   * Called by the Three Cs loop when user responds with a correction.
+   */
+  async applyCorrection(briefId, correction) {
+    if (!briefId || !correction) return;
+    try {
+      await this.mg(
+        `MATCH (grb:GoalResearchBrief {id: $id})
+         SET grb.corrections = coalesce(grb.corrections, []) + [$correction],
+             grb.updatedAt   = localdatetime()`,
+        { id: briefId, correction: String(correction).slice(0, 500) }
+      );
+    } catch (_) { /* non-fatal */ }
+  }
+
+  /**
+   * confirm — Mark brief as confirmed by user (Three Cs loop complete).
+   */
+  async confirm(briefId) {
+    if (!briefId) return;
+    try {
+      await this.mg(
+        `MATCH (grb:GoalResearchBrief {id: $id})
+         SET grb.confirmedByUser = true, grb.confirmedAt = localdatetime()`,
+        { id: briefId }
+      );
+    } catch (_) { /* non-fatal */ }
+  }
+}
+
+module.exports = { GoalResearchPipeline };