@nebulacomponents/citable 1.17.0 → 1.18.0

package/src/analysis/eeat.js

@@ -0,0 +1,300 @@
+import { parse as parseHtml } from 'node-html-parser';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+
+/**
+ * Evaluates on-page content against Google's E-E-A-T rubric on a 0.0 - 5.0 scale.
+ *
+ * Premise 2 compliance:
+ * - fact_status: 'modeled_rubric_evaluation'
+ * - E-E-A-T is an evaluative framework from the Search Quality Rater Guidelines,
+ *   NOT a direct algorithmic ranking factor or search engine API metric.
+ */
+export function evaluateEeat(page, ctx = {}) {
+  const html = page.html || '';
+  const root = parseHtml(html);
+  const text = (page.text || root.textContent || '').replace(/\s+/g, ' ').trim();
+  const lowerText = text.toLowerCase();
+  const reg = registryPageFor(ctx, page);
+
+  // -------------------------------------------------------------
+  // 1. EXPERIENCE (0.0 - 5.0)
+  // -------------------------------------------------------------
+  const expSignals = [];
+  const expMissing = [];
+  let expScore = 1.0;
+
+  // First-person practitioner indicators
+  const FIRST_PERSON_RX = /\b(?:we tested|in our testing|we evaluated|our evaluation|we measured|our analysis|we observed|our findings|in our experience|our team found|hands-on|case study|we verified|we deployed)\b/i;
+  if (FIRST_PERSON_RX.test(text)) {
+    expScore += 1.2;
+    expSignals.push('First-person practitioner observations and testing language detected');
+  } else {
+    expMissing.push('Add first-hand testing observations, case studies, or practitioner findings');
+  }
+
+  // Original media / demonstrations / code artifacts
+  const codeBlocks = root.querySelectorAll('pre, code, table');
+  if (codeBlocks.length >= 2) {
+    expScore += 1.0;
+    expSignals.push(`Structured demonstration artifacts present (${codeBlocks.length} code/table blocks)`);
+  } else {
+    expMissing.push('Include original demonstration tables, code snippets, or walkthroughs');
+  }
+
+  // Original images with descriptive captions/alt text
+  const images = page.images || root.querySelectorAll('img');
+  const validImages = images.filter((img) => {
+    const alt = typeof img === 'object' && img.getAttribute ? img.getAttribute('alt') : img.alt;
+    return Boolean(alt && alt.length > 5);
+  });
+  if (validImages.length >= 1) {
+    expScore += 0.8;
+    expSignals.push(`Descriptive contextual images present (${validImages.length} with detailed alt text)`);
+  }
+
+  // Quantitative measurement / benchmark data
+  const METRIC_DATA_RX = /(?:\b\d+(?:\.\d+)?%|\b\d+\s*ms\b|\b\d+\s*s\b|\$\d+(?:,\d{3})*|\bbenchmark\b|\bresults showed\b)/i;
+  if (METRIC_DATA_RX.test(text)) {
+    expScore += 1.0;
+    expSignals.push('Quantitative experimental or benchmark metrics presented');
+  } else {
+    expMissing.push('Include verifiable quantitative benchmark data or empirical results');
+  }
+
+  expScore = Math.min(5.0, Math.max(0.0, Math.round(expScore * 10) / 10));
+
+  // -------------------------------------------------------------
+  // 2. EXPERTISE (0.0 - 5.0)
+  // -------------------------------------------------------------
+  const expertSignals = [];
+  const expertMissing = [];
+  let expertScore = 1.0;
+
+  // Author attribution in page or schema
+  let authorName = null;
+  let authorSameAs = null;
+  for (const j of (page.jsonLd || [])) {
+    for (const b of (j.blocks || [])) {
+      if (b.author) {
+        const authorObj = Array.isArray(b.author) ? b.author[0] : b.author;
+        authorName = authorObj?.name || (typeof authorObj === 'string' ? authorObj : null);
+        authorSameAs = authorObj?.sameAs || null;
+      }
+    }
+  }
+
+  // Visible byline check
+  const BYLINE_RX = /\b(?:written by|authored by|author:|by)\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)/i;
+  const bylineMatch = text.match(BYLINE_RX);
+  if (!authorName && bylineMatch) {
+    authorName = bylineMatch[1];
+  }
+
+  if (authorName) {
+    expertScore += 1.5;
+    expertSignals.push(`Attributed author identified: "${authorName}"`);
+  } else {
+    expertMissing.push('Add explicit author byline with credentials or Person schema');
+  }
+
+  // Author credentials / biography / authoritative profiles
+  const BIO_RX = /\b(?:ph\.?d|m\.?d|engineer|architect|researcher|director|specialist|consultant|analyst|professor|founder|lead)\b/i;
+  if (authorSameAs || BIO_RX.test(text)) {
+    expertScore += 1.2;
+    expertSignals.push('Author credentials, professional title, or external disambiguation profiles verified');
+  } else {
+    expertMissing.push('Link author to authoritative profile (sameAs: LinkedIn, ORCID, GitHub) and list credentials');
+  }
+
+  // Content depth & semantic heading hierarchy
+  const wordCount = page.rawVisibleWordCount || page.wordCount || text.split(/\s+/).filter(Boolean).length;
+  const headings = page.headings || [];
+  if (wordCount >= 600 && headings.length >= 3) {
+    expertScore += 1.3;
+    expertSignals.push(`Substantive technical depth (${wordCount} words, ${headings.length} headings)`);
+  } else if (wordCount < 300) {
+    expertMissing.push('Expand content depth to address topic comprehensively (currently thin <300 words)');
+  }
+
+  expertScore = Math.min(5.0, Math.max(0.0, Math.round(expertScore * 10) / 10));
+
+  // -------------------------------------------------------------
+  // 3. AUTHORITATIVENESS (0.0 - 5.0)
+  // -------------------------------------------------------------
+  const authSignals = [];
+  const authMissing = [];
+  let authScore = 1.0;
+
+  // External primary source citations (.edu, .gov, standards, docs)
+  const links = page.links || root.querySelectorAll('a').map((a) => ({
+    href: a.getAttribute('href') || '',
+    text: a.text.trim(),
+  }));
+
+  const externalLinks = links.filter((l) => /^https?:\/\//i.test(l.href));
+  const authoritativeDomains = externalLinks.filter((l) => {
+    const u = l.href.toLowerCase();
+    return u.includes('.edu') || u.includes('.gov') || u.includes('.org') ||
+           u.includes('w3.org') || u.includes('rfc-editor.org') || u.includes('github.com') ||
+           u.includes('arxiv.org') || u.includes('developer.mozilla.org') || u.includes('web.dev');
+  });
+
+  if (authoritativeDomains.length >= 2) {
+    authScore += 1.5;
+    authSignals.push(`Primary authority citations present (${authoritativeDomains.length} citations to academic/standard/industry domains)`);
+  } else if (externalLinks.length >= 1) {
+    authScore += 0.8;
+    authSignals.push(`External citations present (${externalLinks.length} external links)`);
+    authMissing.push('Cite recognized primary sources (standards organizations, academic research, official documentation)');
+  } else {
+    authMissing.push('Add outbound citations to primary sources and industry standards');
+  }
+
+  // Registry claim grounding
+  const claims = ctx.registries?.claims?.entries || [];
+  const pageClaims = claims.filter((c) => c.canonical_url === page.url || c.claim_id);
+  const verifiedClaims = pageClaims.filter((c) => c.status === 'verified');
+  if (verifiedClaims.length >= 1) {
+    authScore += 1.5;
+    authSignals.push(`Page claims backed by verified evidence records (${verifiedClaims.length} verified claims)`);
+  } else {
+    authMissing.push('Ground material claims in evidence registry with primary citations');
+  }
+
+  // Publisher / Organization entity graph
+  let hasOrgSchema = false;
+  for (const j of (page.jsonLd || [])) {
+    for (const b of (j.blocks || [])) {
+      const type = [].concat(b['@type'] || []).join(',');
+      const pubType = [].concat(b.publisher?.["@type"] || []).join(",");
+      if (/Organization|Corporation/i.test(type) || /Organization|Corporation/i.test(pubType)) hasOrgSchema = true;
+    }
+  }
+  if (hasOrgSchema) {
+    authScore += 1.0;
+    authSignals.push('Publisher Organization schema graph present');
+  } else {
+    authMissing.push('Add Organization schema with publisher credentials and sameAs properties');
+  }
+
+  authScore = Math.min(5.0, Math.max(0.0, Math.round(authScore * 10) / 10));
+
+  // -------------------------------------------------------------
+  // 4. TRUSTWORTHINESS (0.0 - 5.0) — The foundational pillar
+  // -------------------------------------------------------------
+  const trustSignals = [];
+  const trustMissing = [];
+  let trustScore = 1.0;
+
+  // Editorial freshness / visible timestamps
+  const DATE_RX = /\b(?:published|updated|last modified|reviewed|date):\s*([a-zA-Z]+\s+\d{1,2},\s*\d{4}|\d{4}-\d{2}-\d{2})\b/i;
+  const hasVisibleDate = DATE_RX.test(text);
+  let hasSchemaDate = false;
+  for (const j of (page.jsonLd || [])) {
+    for (const b of (j.blocks || [])) {
+      if (b.datePublished || b.dateModified) hasSchemaDate = true;
+    }
+  }
+  if (hasVisibleDate || hasSchemaDate) {
+    trustScore += 1.0;
+    trustSignals.push('Transparent publication and modification dates disclosed');
+  } else {
+    trustMissing.push('Disclose explicit publication and last-updated dates');
+  }
+
+  // Contact / About / Support transparency
+  const hasContact = links.some((l) => /contact|about|support|team|company/i.test(l.href) || /contact|about|support/i.test(l.text));
+  if (hasContact) {
+    trustScore += 1.0;
+    trustSignals.push('Direct contact, about, or support channels accessible');
+  } else {
+    trustMissing.push('Provide clear navigation links to About Us, Contact, and Support pages');
+  }
+
+  // Legal transparency: Privacy policy & Terms
+  const hasPrivacy = links.some((l) => /privacy/i.test(l.href) || /privacy/i.test(l.text));
+  const hasTerms = links.some((l) => /terms/i.test(l.href) || /terms/i.test(l.text));
+  if (hasPrivacy && hasTerms) {
+    trustScore += 1.0;
+    trustSignals.push('Privacy policy and terms of service disclosed');
+  } else {
+    trustMissing.push('Provide clear links to Privacy Policy and Terms of Service');
+  }
+
+  // Security & protocol
+  if (page.url && page.url.startsWith('https://')) {
+    trustScore += 1.0;
+    trustSignals.push('Secure HTTPS transport confirmed');
+  } else if (!page.url.startsWith('http://')) {
+    trustScore += 0.5; // relative / local test
+  }
+
+  // Commercial / sponsorship transparency
+  const sponsoredLinks = links.filter((l) => (l.rel || '').includes('sponsored') || (l.rel || '').includes('nofollow'));
+  if (sponsoredLinks.length > 0) {
+    trustScore += 0.5;
+    trustSignals.push('Commercial and affiliate links properly attributed with rel="sponsored"');
+  }
+
+  trustScore = Math.min(5.0, Math.max(0.0, Math.round(trustScore * 10) / 10));
+
+  // -------------------------------------------------------------
+  // COMPOSITE E-E-A-T SCORE (0.0 - 5.0)
+  // In Google Quality Rater Guidelines, Trust is the foundational base:
+  // untrusted content cannot achieve a high overall rating.
+  // -------------------------------------------------------------
+  let composite = (trustScore * 0.40) + (expertScore * 0.25) + (expScore * 0.20) + (authScore * 0.15);
+  if (trustScore < 2.0) {
+    composite = Math.min(composite, trustScore); // Trust cap
+  }
+  composite = Math.round(composite * 10) / 10;
+
+  // Grade rating
+  let rating = 'medium';
+  if (composite >= 4.0) rating = 'very_high';
+  else if (composite >= 3.0) rating = 'high';
+  else if (composite >= 2.0) rating = 'medium';
+  else rating = 'low';
+
+  return {
+    url: page.url,
+    fact_status: 'modeled_rubric_evaluation',
+    methodology: 'Google Search Quality Rater Guidelines (E-E-A-T Evaluative Rubric)',
+    disclaimer: 'E-E-A-T is an evaluative heuristic rubric modeled on Quality Rater Guidelines, not an algorithmic ranking score. Google does not calculate a single E-E-A-T metric.',
+    composite_score: composite,
+    overall_rating: rating,
+    dimensions: {
+      experience: {
+        score: expScore,
+        scale: '0.0 - 5.0',
+        signals: expSignals,
+        gaps: expMissing,
+      },
+      expertise: {
+        score: expertScore,
+        scale: '0.0 - 5.0',
+        author: authorName,
+        signals: expertSignals,
+        gaps: expertMissing,
+      },
+      authoritativeness: {
+        score: authScore,
+        scale: '0.0 - 5.0',
+        signals: authSignals,
+        gaps: authMissing,
+      },
+      trustworthiness: {
+        score: trustScore,
+        scale: '0.0 - 5.0',
+        signals: trustSignals,
+        gaps: trustMissing,
+      },
+    },
+    actionable_improvements: [
+      ...expMissing.map((g) => ({ dimension: 'experience', recommendation: g })),
+      ...expertMissing.map((g) => ({ dimension: 'expertise', recommendation: g })),
+      ...authMissing.map((g) => ({ dimension: 'authoritativeness', recommendation: g })),
+      ...trustMissing.map((g) => ({ dimension: 'trustworthiness', recommendation: g })),
+    ],
+  };
+}

package/src/analysis/funnelAnalysis.js

@@ -0,0 +1,171 @@
+import { safePath } from '../detectors/framework.js';
+
+/**
+ * Perform End-to-End Funnel and Conversion-Path Analysis across site pages.
+ */
+export function analyzeConversionFunnel(sitePages = [], declaredFunnel = null) {
+  let steps = [];
+
+  if (declaredFunnel?.steps?.length) {
+    steps = declaredFunnel.steps;
+  } else {
+    // Auto-discover standard conversion path from site pages
+    const roleOrder = ['landing', 'product', 'pricing', 'checkout', 'confirmation'];
+    const discovered = [];
+
+    for (const role of roleOrder) {
+      const p = sitePages.find((page) => {
+        const u = (page.url || '').toLowerCase();
+        if (role === 'landing' && (u.endsWith('/') || u.includes('home') || u.includes('landing'))) return true;
+        if (role === 'product' && (u.includes('product') || u.includes('feature') || u.includes('solution'))) return true;
+        if (role === 'pricing' && (u.includes('pricing') || u.includes('plan'))) return true;
+        if (role === 'checkout' && (u.includes('checkout') || u.includes('signup') || u.includes('demo') || u.includes('contact'))) return true;
+        if (role === 'confirmation' && (u.includes('thank-you') || u.includes('success') || u.includes('confirmed'))) return true;
+        return false;
+      });
+      if (p) {
+        discovered.push({
+          step_id: `STEP-${role.toUpperCase()}`,
+          name: `${role[0].toUpperCase()}${role.slice(1)} Page`,
+          url_pattern: p.url,
+          role,
+        });
+      }
+    }
+    steps = discovered.length >= 2 ? discovered : [];
+  }
+
+  if (steps.length === 0) {
+    return {
+      funnel_id: declaredFunnel?.funnel_id || 'AUTO-DISCOVERED',
+      funnel_name: declaredFunnel?.name || 'Conversion Funnel',
+      status: 'insufficient_steps',
+      message: 'Could not establish conversion funnel: declare steps in .citable/funnels.yaml or provide multi-step pages.',
+      steps: [],
+      funnel_health_score: 0,
+      leaks: [],
+    };
+  }
+
+  const stepEvaluations = [];
+  const leaks = [];
+  let continuityScore = 100;
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const page = sitePages.find((p) => (p.url || '').includes(step.url_pattern) || safePath(p.url) === safePath(step.url_pattern));
+
+    if (!page) {
+      continuityScore -= 25;
+      leaks.push({
+        step_id: step.step_id,
+        severity: 'critical',
+        type: 'missing_page',
+        description: `Funnel step page matching "${step.url_pattern}" was not found in audited site output`,
+      });
+      stepEvaluations.push({
+        step: i + 1,
+        step_id: step.step_id,
+        name: step.name,
+        url: step.url_pattern,
+        role: step.role,
+        status_code: null,
+        continuity_intact: false,
+        drop_off_risk: 'critical',
+      });
+      continue;
+    }
+
+    const ctas = page.ctas || [];
+    const forms = page.forms || [];
+    let nextStepLinked = true;
+    let nextStepTarget = null;
+    let paramPreserved = true;
+
+    if (i < steps.length - 1) {
+      const nextStep = steps[i + 1];
+      const linkToNext = ctas.find((c) => c.target && c.target.includes(nextStep.url_pattern));
+      if (!linkToNext) {
+        nextStepLinked = false;
+        continuityScore -= 20;
+        leaks.push({
+          step_id: step.step_id,
+          severity: 'high',
+          type: 'missing_next_step_cta',
+          description: `Step ${i + 1} (${step.name}) has no interactive CTA linking directly to step ${i + 2} (${nextStep.name})`,
+        });
+      } else {
+        nextStepTarget = linkToNext.target;
+        // Check attribution parameter preservation
+        if (linkToNext.target.includes('?') && !linkToNext.target.includes('utm_')) {
+          paramPreserved = false;
+          continuityScore -= 10;
+          leaks.push({
+            step_id: step.step_id,
+            severity: 'medium',
+            type: 'attribution_parameter_loss',
+            description: `CTA link to "${nextStepTarget}" strips campaign attribution query parameters`,
+          });
+        }
+      }
+    }
+
+    // Post-conversion confirmation page indexing check
+    if (step.role === 'confirmation' || i === steps.length - 1) {
+      const robots = Array.from(page.robotsDirectives || []);
+      const hasNoindex = robots.some((r) => r.includes('noindex'));
+      if (!hasNoindex && (step.role === 'confirmation' || page.url.includes('thank-you') || page.url.includes('success'))) {
+        continuityScore -= 10;
+        leaks.push({
+          step_id: step.step_id,
+          severity: 'medium',
+          type: 'unprotected_conversion_page',
+          description: 'Post-conversion thank-you page lacks a noindex directive, risking conversion goal contamination in analytics',
+        });
+      }
+    }
+
+    // Distraction leaks on checkout / high-intent steps
+    if (['checkout', 'pricing', 'signup'].includes(step.role) && (page.navLinksCount || 0) > 12) {
+      continuityScore -= 15;
+      leaks.push({
+        step_id: step.step_id,
+        severity: 'medium',
+        type: 'enclosed_checkout_leak',
+        description: `Conversion step "${step.name}" contains ${page.navLinksCount} header/footer links, leaking visitors out of the funnel`,
+      });
+    }
+
+    // Drop-off risk assessment
+    let dropOffRisk = 'low';
+    if (!nextStepLinked || page.status >= 400) dropOffRisk = 'critical';
+    else if (forms.some((f) => f.fieldCount > 6)) dropOffRisk = 'high';
+    else if ((page.navLinksCount || 0) > 12) dropOffRisk = 'moderate';
+
+    stepEvaluations.push({
+      step: i + 1,
+      step_id: step.step_id,
+      name: step.name,
+      url: page.url,
+      role: step.role,
+      status_code: page.status,
+      continuity_intact: nextStepLinked && page.status === 200,
+      next_step_target: nextStepTarget,
+      drop_off_risk: dropOffRisk,
+      form_count: forms.length,
+      cta_count: ctas.length,
+    });
+  }
+
+  const finalScore = Math.min(100, Math.max(0, continuityScore));
+
+  return {
+    funnel_id: declaredFunnel?.funnel_id || 'DISCOVERED-FUNNEL',
+    funnel_name: declaredFunnel?.name || 'Primary Conversion Path',
+    funnel_health_score: finalScore,
+    status: finalScore >= 80 ? 'healthy' : finalScore >= 50 ? 'needs_optimization' : 'critical_leaks',
+    steps: stepEvaluations,
+    total_steps: steps.length,
+    leaks,
+  };
+}

package/src/analysis/iceMatrix.js

@@ -0,0 +1,205 @@
+/**
+ * Impact / Effort / Confidence (ICE) scoring matrix for Citable findings and initiatives.
+ *
+ * All factors are explicitly scored on a transparent 1-10 scale.
+ * Formula: ICE Score = (Impact × Confidence) / Effort
+ * Quadrants:
+ * - Quick Wins: High Impact (>=6), Low Effort (<=4), High Confidence (>=6)
+ * - Strategic Bets: High Impact (>=6), High Effort (>=5)
+ * - Low-Hanging Fruit: Low Impact (<6), Low Effort (<=4)
+ * - Deprioritize: Low Impact (<6), High Effort (>=5) or Low Confidence (<5)
+ */
+
+const SEVERITY_IMPACT_MAP = {
+  critical: 10,
+  high: 8,
+  medium: 5,
+  low: 2,
+  informational: 1,
+  experimental: 2,
+};
+
+const DETECTOR_EFFORT_MAP = {
+  TECH: 4,
+  CRAWL: 3,
+  CWV: 5,
+  ARCH: 6,
+  PAGE: 3,
+  ANS: 4,
+  GEO: 5,
+  RECO: 6,
+  SCHEMA: 3,
+  LINK: 4,
+  ENTITY: 4,
+  CLAIM: 5,
+  EVD: 6,
+  SEC: 4,
+  MOBILE: 3,
+  CRO: 4,
+};
+
+const CONFIDENCE_MAP = {
+  deterministic: 10,
+  verified: 9,
+  validated: 8,
+  proxy: 6,
+  modeled: 6,
+  anecdote: 4,
+  assumption: 3,
+};
+
+/**
+ * Score an audit finding for the ICE matrix
+ */
+export function scoreFinding(finding) {
+  const severity = finding.classification?.severity || 'medium';
+  const impact = SEVERITY_IMPACT_MAP[severity] ?? 5;
+
+  const ns = (finding.detector_id || '').split('-')[0];
+  let effort = DETECTOR_EFFORT_MAP[ns] ?? 4;
+  if (finding.remediation?.review_required) effort += 2;
+  effort = Math.min(10, Math.max(1, effort));
+
+  let confidence = 8;
+  if (finding.classification?.deterministic) {
+    confidence = 10;
+  } else if (finding.fact_status === 'observed_telemetry') {
+    confidence = 9;
+  } else if (finding.fact_status === 'modeled_rubric_evaluation') {
+    confidence = 6;
+  }
+
+  const iceScore = Math.round(((impact * confidence) / effort) * 10) / 10;
+
+  let quadrant = 'low_hanging_fruit';
+  if (impact >= 6 && effort <= 4 && confidence >= 6) {
+    quadrant = 'quick_wins';
+  } else if (impact >= 6 && effort >= 5) {
+    quadrant = 'strategic_bets';
+  } else if (impact < 6 && effort <= 4) {
+    quadrant = 'low_hanging_fruit';
+  } else {
+    quadrant = 'deprioritize';
+  }
+
+  return {
+    id: finding.detector_id || finding.finding_id,
+    finding_id: finding.finding_id,
+    detector_id: finding.detector_id,
+    title: finding.observation?.summary || finding.name || finding.detector_id,
+    subject: finding.subject?.identifier || finding.subject?.url || 'global',
+    severity,
+    impact,
+    effort,
+    confidence,
+    ice_score: iceScore,
+    quadrant,
+  };
+}
+
+/**
+ * Score an initiative from initiatives.yaml for the ICE matrix
+ */
+export function scoreInitiative(initiative) {
+  const SCALE = { none: 0, low: 2, medium: 5, high: 8, critical: 10, validated: 9, transformative: 10, trivial: 1, very_high: 9, negligible: 1 };
+
+  const demand = SCALE[initiative.customer_demand] ?? 5;
+  const rev = SCALE[initiative.revenue_potential] ?? 5;
+  const diff = SCALE[initiative.strategic_differentiation] ?? 5;
+  const impact = Math.min(10, Math.max(1, Math.round((demand + rev + diff) / 3)));
+
+  const engCost = SCALE[initiative.engineering_cost] ?? 5;
+  const opCost = SCALE[initiative.operating_cost || 'none'] ?? 0;
+  const effort = Math.min(10, Math.max(1, Math.round(engCost + opCost * 0.3)));
+
+  const confidence = CONFIDENCE_MAP[initiative.evidence_strength] ?? 5;
+  const iceScore = Math.round(((impact * confidence) / effort) * 10) / 10;
+
+  let quadrant = 'low_hanging_fruit';
+  if (impact >= 6 && effort <= 4 && confidence >= 6) {
+    quadrant = 'quick_wins';
+  } else if (impact >= 6 && effort >= 5) {
+    quadrant = 'strategic_bets';
+  } else if (impact < 6 && effort <= 4) {
+    quadrant = 'low_hanging_fruit';
+  } else {
+    quadrant = 'deprioritize';
+  }
+
+  return {
+    id: initiative.initiative_id,
+    title: initiative.title,
+    owner: initiative.owner || 'unassigned',
+    status: initiative.status,
+    impact,
+    effort,
+    confidence,
+    ice_score: iceScore,
+    quadrant,
+  };
+}
+
+/**
+ * Build the full ICE Scoring Matrix from a list of findings or initiatives
+ */
+export function buildIceMatrix(items = [], { type = 'findings' } = {}) {
+  const scored = items.map((item) => (type === 'initiatives' ? scoreInitiative(item) : scoreFinding(item)));
+  scored.sort((a, b) => b.ice_score - a.ice_score || b.impact - a.impact);
+
+  const quadrants = {
+    quick_wins: scored.filter((i) => i.quadrant === 'quick_wins'),
+    strategic_bets: scored.filter((i) => i.quadrant === 'strategic_bets'),
+    low_hanging_fruit: scored.filter((i) => i.quadrant === 'low_hanging_fruit'),
+    deprioritize: scored.filter((i) => i.quadrant === 'deprioritize'),
+  };
+
+  return {
+    fact_status: 'transparent_prioritization_matrix',
+    scoring_method: 'ICE: (Impact [1-10] × Confidence [1-10]) / Effort [1-10]',
+    total_items: scored.length,
+    summary: {
+      quick_wins_count: quadrants.quick_wins.length,
+      strategic_bets_count: quadrants.strategic_bets.length,
+      low_hanging_fruit_count: quadrants.low_hanging_fruit.length,
+      deprioritize_count: quadrants.deprioritize.length,
+    },
+    quadrants,
+    ranked_items: scored,
+  };
+}
+
+/**
+ * Format ICE Matrix as human-readable terminal table / markdown
+ */
+export function formatIceMatrixOutput(matrix) {
+  const lines = [
+    `Impact / Effort / Confidence (ICE) Prioritization Matrix`,
+    `=======================================================`,
+    `Methodology: ${matrix.scoring_method}`,
+    `Total Items Scored: ${matrix.total_items}`,
+    ``,
+    `QUADRANT SUMMARY:`,
+    `  Quadrant I   [Quick Wins]:          ${matrix.summary.quick_wins_count} item(s) (High Impact, Low Effort, High Confidence)`,
+    `  Quadrant II  [Strategic Bets]:      ${matrix.summary.strategic_bets_count} item(s) (High Impact, High Effort)`,
+    `  Quadrant III [Low-Hanging Fruit]:   ${matrix.summary.low_hanging_fruit_count} item(s) (Low Impact, Low Effort)`,
+    `  Quadrant IV  [Deprioritize]:        ${matrix.summary.deprioritize_count} item(s) (Low Impact or Low Confidence)`,
+    ``,
+    `RANKED ACTION MATRIX:`,
+    `  ${'Rank'.padEnd(6)} | ${'ID'.padEnd(16)} | ${'Impact'.padEnd(8)} | ${'Effort'.padEnd(8)} | ${'Conf'.padEnd(6)} | ${'ICE Score'.padEnd(10)} | Quadrant`,
+    `  ${'-'.repeat(80)}`,
+  ];
+
+  matrix.ranked_items.forEach((item, idx) => {
+    const rank = `#${idx + 1}`.padEnd(6);
+    const id = (item.id || '').slice(0, 16).padEnd(16);
+    const impact = `${item.impact}/10`.padEnd(8);
+    const effort = `${item.effort}/10`.padEnd(8);
+    const conf = `${item.confidence}/10`.padEnd(6);
+    const score = `${item.ice_score}`.padEnd(10);
+    const q = item.quadrant.toUpperCase();
+    lines.push(`  ${rank} | ${id} | ${impact} | ${effort} | ${conf} | ${score} | ${q}`);
+    lines.push(`         ${item.title.slice(0, 70)}`);
+  });
+
+  return lines.join('\n');
+}