avorelo 0.1.0

package/scripts/lib/prelaunch-intelligence.js

@@ -0,0 +1,869 @@
+"use strict";
+
+// ── Pre-Launch Intelligence Layer ─────────────────────────────────────────────
+//
+// Contract: avorelo.prelaunchIntelligence.v1
+//
+// Aggregates signals from install, activation, feedback, token/cost, MCP,
+// hardening, support and turns them into actionable pre-launch insight.
+//
+// Local-only. Redacted. No public launch claim. No exact savings without source.
+// Not a release candidate gate — this prepares us for that gate.
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.prelaunchIntelligence.v1";
+const SCHEMA_VERSION = 1;
+const INTELLIGENCE_DIR_REL = ".claude/cco/orchestration/prelaunch-intelligence";
+const ARTIFACT_REL = `${INTELLIGENCE_DIR_REL}/latest-intelligence.json`;
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+// ── Signal collection ─────────────────────────────────────────────────────────
+
+function collectPrelaunchSignals(cwd, options = {}) {
+  const readArtifact = (rel) => safeReadJson(path.join(cwd, rel));
+
+  // Install / activation signals
+  const installPrompt = readArtifact(".claude/cco/orchestration/ai-install/latest-prompt.json");
+  const prelaunchReadiness = readArtifact(".claude/cco/orchestration/prelaunch-readiness/latest-activation-readiness.json");
+  const activation = readArtifact(".claude/cco/orchestration/activation/latest-activation.json");
+  const alphaReadiness = readArtifact(".claude/cco/orchestration/alpha-readiness/latest-gate.json");
+
+  // Token/cost signals
+  const tokenEfficiency = readArtifact(".claude/cco/orchestration/token-efficiency/latest-evidence.json");
+  const tokenQualityGate = readArtifact(".claude/cco/orchestration/token-efficiency/latest-quality-gate.json");
+  const cacheReadiness = readArtifact(".claude/cco/orchestration/cache-readiness/latest-readiness.json");
+
+  // MCP signals
+  const mcpInventory = readArtifact(".claude/cco/orchestration/mcp-tool-governance/latest-inventory.json");
+  const mcpRisk = readArtifact(".claude/cco/orchestration/mcp-tool-governance/latest-risk.json");
+  const mcpPolicy = readArtifact(".claude/cco/orchestration/mcp-tool-governance/latest-policy.json");
+
+  // Hardening signals
+  const launchHardening = readArtifact(".claude/cco/orchestration/launch-hardening/latest-gate.json");
+  const failureRecovery = readArtifact(".claude/cco/orchestration/failure-recovery/latest-recovery.json");
+  const artifactHealth = readArtifact(".claude/cco/orchestration/artifact-health/latest-health.json");
+  const hookDoctor = readArtifact(".claude/cco/orchestration/hook-apply/latest-doctor.json");
+
+  // Support / proof signals
+  const supportBundle = readArtifact(".claude/cco/support/latest-support-bundle.json");
+  const valueSummary = readArtifact(".claude/cco/orchestration/seamless-outcome/latest-value-summary.json");
+  const realityGate = readArtifact(".claude/cco/orchestration/seamless-outcome/latest-reality-gate.json");
+  const proofOutcomeEvidence = readArtifact(".claude/cco/orchestration/seamless-outcome/latest-proof-outcome-evidence.json");
+  const companyLoop = readArtifact(".claude/cco/orchestration/company-loop/latest-report.json");
+  const externalUserSimulation = readArtifact(".claude/cco/orchestration/full-readiness/latest-external-user-simulation.json");
+
+  // Intelligence sub-surfaces
+  const feedbackIntelligence = readArtifact(".claude/cco/orchestration/prelaunch-intelligence/latest-feedback-intelligence.json");
+  const tokenCostIntelligence = readArtifact(".claude/cco/orchestration/prelaunch-intelligence/latest-token-cost-intelligence.json");
+  const installJourney = readArtifact(".claude/cco/orchestration/prelaunch-intelligence/latest-install-journey.json");
+
+  return {
+    installPrompt,
+    prelaunchReadiness,
+    activation,
+    alphaReadiness,
+    tokenEfficiency,
+    tokenQualityGate,
+    cacheReadiness,
+    mcpInventory,
+    mcpRisk,
+    mcpPolicy,
+    launchHardening,
+    failureRecovery,
+    artifactHealth,
+    hookDoctor,
+    supportBundle,
+    valueSummary,
+    realityGate,
+    proofOutcomeEvidence,
+    companyLoop,
+    externalUserSimulation,
+    feedbackIntelligence,
+    tokenCostIntelligence,
+    installJourney,
+  };
+}
+
+// ── Score computation ─────────────────────────────────────────────────────────
+
+function scorePrelaunchSignals(signals, options = {}) {
+  let score = 0;
+  let maxScore = 0;
+  const blockers = [];
+  const warnings = [];
+  const evidenceMap = {};
+
+  function addCheck(id, weight, status, description, recoveryAction) {
+    maxScore += weight;
+    if (status === "pass") {
+      score += weight;
+      evidenceMap[id] = "pass";
+    } else if (status === "warn") {
+      score += weight * 0.5;
+      evidenceMap[id] = "warn";
+      warnings.push({ id, description, recoveryAction });
+    } else {
+      evidenceMap[id] = "fail";
+      blockers.push({ id, description, recoveryAction });
+    }
+  }
+
+  // Install prompt (weight 15)
+  if (signals.installPrompt?.status === "ready") {
+    addCheck("install_prompt", 15, "pass", "AI install prompt ready", null);
+  } else if (signals.installPrompt) {
+    addCheck("install_prompt", 15, "warn", "AI install prompt present but not ready",
+      "Run: node bin/avorelo install-ai --json");
+  } else {
+    addCheck("install_prompt", 15, "fail", "AI install prompt missing",
+      "Run: node bin/avorelo install-ai --json");
+  }
+
+  // Prelaunch readiness (weight 20)
+  const plStatus = signals.prelaunchReadiness?.status;
+  if (plStatus === "pass") {
+    addCheck("prelaunch_readiness", 20, "pass", "Pre-launch readiness passes", null);
+  } else if (plStatus === "warn") {
+    addCheck("prelaunch_readiness", 20, "warn", "Pre-launch readiness has warnings",
+      "Run: node bin/avorelo prelaunch-readiness --json");
+  } else {
+    addCheck("prelaunch_readiness", 20, "warn", "Pre-launch readiness not yet run",
+      "Run: node bin/avorelo prelaunch-readiness --json");
+  }
+
+  // Token/cost evidence (weight 10)
+  const tokenLevel = signals.tokenEfficiency?.evidenceLevel;
+  if (tokenLevel === "exact" || tokenLevel === "estimated") {
+    addCheck("token_cost_evidence", 10, "pass", "Token/cost evidence available", null);
+  } else {
+    addCheck("token_cost_evidence", 10, "warn", "Token/cost evidence not available",
+      "Run: node bin/avorelo token-efficiency --json");
+  }
+
+  // Token quality gate (weight 5)
+  const tqStatus = signals.tokenQualityGate?.status;
+  if (tqStatus === "pass") {
+    addCheck("token_quality_gate", 5, "pass", "Token quality gate passes", null);
+  } else if (tqStatus === "warn") {
+    addCheck("token_quality_gate", 5, "warn", "Token quality gate warns",
+      "Review: node bin/avorelo token-efficiency --json");
+  } else {
+    addCheck("token_quality_gate", 5, "warn", "Token quality gate not run",
+      "Run: node bin/avorelo token-efficiency --json");
+  }
+
+  // MCP governance (weight 10)
+  const mcpStatus = signals.mcpInventory?.status;
+  if (mcpStatus === "pass" || mcpStatus === "ready") {
+    addCheck("mcp_governance", 10, "pass", "MCP governance ready", null);
+  } else if (mcpStatus === "warn") {
+    addCheck("mcp_governance", 10, "warn", "MCP governance has warnings",
+      "Run: node bin/avorelo mcp doctor --json");
+  } else {
+    addCheck("mcp_governance", 10, "warn", "MCP governance not run",
+      "Run: node bin/avorelo mcp doctor --json");
+  }
+
+  // Launch hardening (weight 15)
+  const lhStatus = signals.launchHardening?.status;
+  if (lhStatus === "pass") {
+    addCheck("launch_hardening", 15, "pass", "Launch hardening passes", null);
+  } else if (lhStatus === "warn") {
+    addCheck("launch_hardening", 15, "warn", `Launch hardening warns (score: ${signals.launchHardening?.score})`,
+      "Run: node bin/avorelo launch-hardening --json");
+  } else {
+    addCheck("launch_hardening", 15, "warn", "Launch hardening not run",
+      "Run: node bin/avorelo launch-hardening --json");
+  }
+
+  // Support bundle (weight 5)
+  const sbStatus = signals.supportBundle?.status;
+  if (sbStatus === "ready") {
+    addCheck("support_bundle", 5, "pass", "Support bundle available", null);
+  } else {
+    addCheck("support_bundle", 5, "warn", "Support bundle not generated",
+      "Run: node bin/avorelo support-bundle --json");
+  }
+
+  // Proof/outcome (weight 10)
+  if (signals.valueSummary) {
+    addCheck("proof_outcome", 10, "pass", "Value summary/proof available", null);
+  } else {
+    addCheck("proof_outcome", 10, "warn", "No proof or value summary generated",
+      "Run: node bin/avorelo proof after completing a task.");
+  }
+
+  // Reality gate (weight 10)
+  const rgStatus = signals.realityGate?.status;
+  if (rgStatus === "pass") {
+    addCheck("reality_gate", 10, "pass", "Reality gate passes", null);
+  } else if (rgStatus === "warn") {
+    addCheck("reality_gate", 10, "warn", `Reality gate warns (score: ${signals.realityGate?.score})`,
+      "Run: node bin/avorelo outcome --gate --json");
+  } else {
+    addCheck("reality_gate", 10, "warn", "Reality gate not run",
+      "Run: node bin/avorelo outcome --gate --json");
+  }
+
+  const normalizedScore = maxScore > 0 ? Math.round((score / maxScore) * 100) : 0;
+
+  return {
+    score: normalizedScore,
+    rawScore: score,
+    maxScore,
+    blockers,
+    warnings,
+    evidenceMap,
+  };
+}
+
+// ── Install journey summary ───────────────────────────────────────────────────
+
+function buildInstallJourneySummary(signals) {
+  const journey = signals.installJourney;
+  if (!journey) {
+    return {
+      status: "not_available",
+      stepsComplete: null,
+      stepsTotal: null,
+      manualStepsAvoided: 0,
+      nextAction: "Run: node bin/avorelo install-journey --json",
+    };
+  }
+  return {
+    status: journey.status,
+    stepsComplete: journey.stepsComplete,
+    stepsTotal: journey.stepsTotal,
+    manualStepsAvoided: journey.manualStepsAvoided?.length || 0,
+    nextAction: journey.nextAction,
+  };
+}
+
+// ── Friction summary ──────────────────────────────────────────────────────────
+
+function buildFrictionSummary(signals) {
+  const fi = signals.feedbackIntelligence;
+  if (!fi || fi.status === "insufficient_data") {
+    return {
+      status: "insufficient_data",
+      totalEntries: 0,
+      topFriction: null,
+      clustersFound: 0,
+      message: "No feedback entries. Add dogfood feedback to build friction insights.",
+    };
+  }
+  return {
+    status: fi.status,
+    totalEntries: fi.totalFeedbackEntries || 0,
+    topFriction: fi.topFriction,
+    clustersFound: fi.clustersFound || 0,
+    topClusters: (fi.clusters || []).slice(0, 3).map((c) => ({
+      frictionType: c.frictionType,
+      count: c.count,
+      severity: c.severity,
+      recommendedAction: c.recommendedAction,
+    })),
+  };
+}
+
+// ── Token/cost summary ────────────────────────────────────────────────────────
+
+function buildTokenCostSummary(signals) {
+  const tci = signals.tokenCostIntelligence;
+  const te = signals.tokenEfficiency;
+
+  if (!tci && !te) {
+    return {
+      evidenceLevel: "not_available",
+      status: "not_available",
+      noExactSavingsClaim: true,
+      message: "Run avorelo token-efficiency --json to generate token evidence.",
+    };
+  }
+
+  if (tci) {
+    return {
+      evidenceLevel: tci.evidenceLevel,
+      status: tci.status,
+      readinessStatus: tci.readinessStatus || (tci.status === "ready" ? "pass" : tci.status === "partial" ? "warn" : "info"),
+      realUsageSamplesCount: tci.realUsageSamplesCount || 0,
+      confidence: tci.confidence || "missing",
+      evidenceMode: tci.evidenceMode || "missing",
+      contextAvoidedEstimate: tci.contextAvoidedEstimate,
+      cacheReadinessStatus: tci.cacheReadinessSummary?.status,
+      noExactSavingsClaim: true,
+      noSavingsClaimUnlessMeasured: tci.noSavingsClaimUnlessMeasured === true,
+      caveats: tci.caveats?.slice(0, 2) || [],
+      missingEvidence: tci.missingEvidence || [],
+    };
+  }
+
+  return {
+    evidenceLevel: te.evidenceLevel || "not_available",
+    status: te.evidenceLevel ? "partial" : "not_available",
+    noExactSavingsClaim: true,
+    caveats: ["Token estimates are approximate."],
+  };
+}
+
+// ── Risk summary ──────────────────────────────────────────────────────────────
+
+function buildRiskSummary(signals) {
+  const risks = [];
+
+  // Launch hardening
+  const lh = signals.launchHardening;
+  if (lh && lh.status !== "pass") {
+    risks.push({
+      area: "launch_hardening",
+      severity: lh.status === "fail" ? "high" : "medium",
+      description: `Launch hardening ${lh.status} (score: ${lh.score || "?"})`,
+      recoveryAction: "Run: node bin/avorelo launch-hardening --json",
+    });
+  }
+
+  // MCP governance
+  const mcpRisk = signals.mcpRisk;
+  if (mcpRisk?.highRiskCount > 0 || mcpRisk?.unknownCount > 0) {
+    risks.push({
+      area: "mcp_governance",
+      severity: "medium",
+      description: `MCP: ${mcpRisk.highRiskCount || 0} high-risk, ${mcpRisk.unknownCount || 0} unknown tools`,
+      recoveryAction: "Run: node bin/avorelo mcp doctor --json",
+    });
+  }
+
+  // Reality gate
+  const rg = signals.realityGate;
+  if (rg && rg.status !== "pass") {
+    risks.push({
+      area: "reality_gate",
+      severity: rg.status === "fail" ? "high" : "medium",
+      description: `Reality gate ${rg.status} (score: ${rg.score || "?"})`,
+      recoveryAction: "Run: node bin/avorelo outcome --gate --json",
+    });
+  }
+
+  // Failure recovery
+  if (!signals.failureRecovery) {
+    risks.push({
+      area: "failure_recovery",
+      severity: "low",
+      description: "Failure recovery plan not generated",
+      recoveryAction: "Run: node bin/avorelo launch-hardening --json",
+    });
+  }
+
+  return {
+    riskCount: risks.length,
+    highRiskCount: risks.filter((r) => r.severity === "high").length,
+    risks,
+  };
+}
+
+// ── Support summary ───────────────────────────────────────────────────────────
+
+function buildSupportSummary(signals) {
+  const sb = signals.supportBundle;
+  if (!sb) {
+    return {
+      status: "not_available",
+      artifactsAvailable: 0,
+      feedbackItems: 0,
+      promptReadinessSummary: null,
+      redacted: true,
+    };
+  }
+  return {
+    status: sb.status,
+    artifactsAvailable: sb.summary?.artifactsAvailable || 0,
+    artifactsMissing: sb.summary?.artifactsMissing || 0,
+    feedbackItems: sb.summary?.feedbackItems || 0,
+    productLearningEvents: sb.summary?.productLearningEvents || 0,
+    // Include prompt readiness summary safely (no raw promptText)
+    promptReadinessSummary: signals.prelaunchReadiness
+      ? {
+          status: signals.prelaunchReadiness.status,
+          score: signals.prelaunchReadiness.score,
+          noPublicLaunchClaim: signals.prelaunchReadiness.noPublicLaunchClaim,
+        }
+      : null,
+    redacted: true,
+  };
+}
+
+// ── Evidence strength ─────────────────────────────────────────────────────────
+
+function buildEvidenceStrength(signals, scoreData) {
+  const strongEvidence = Object.values(scoreData.evidenceMap).filter((v) => v === "pass").length;
+  const totalChecked = Object.keys(scoreData.evidenceMap).length;
+  const evidenceCoverage = totalChecked > 0 ? Math.round((strongEvidence / totalChecked) * 100) : 0;
+
+  const signalCoverageMap = {
+    install: signals.installPrompt ? "available" : "missing",
+    prelaunch_readiness: signals.prelaunchReadiness ? "available" : "missing",
+    token_efficiency: signals.tokenEfficiency ? "available" : "missing",
+    mcp_governance: signals.mcpInventory ? "available" : "missing",
+    launch_hardening: signals.launchHardening ? "available" : "missing",
+    support_bundle: signals.supportBundle ? "available" : "missing",
+    proof_outcome: signals.valueSummary ? "available" : "missing",
+    reality_gate: signals.realityGate ? "available" : "missing",
+    feedback: signals.feedbackIntelligence?.status === "ready" ? "available" : "partial",
+    company_loop: signals.companyLoop ? "available" : "missing",
+  };
+
+  const availableCount = Object.values(signalCoverageMap).filter((v) => v === "available").length;
+  const partialCount = Object.values(signalCoverageMap).filter((v) => v === "partial").length;
+  const totalSignals = Object.keys(signalCoverageMap).length;
+
+  let strengthLabel;
+  if (availableCount >= totalSignals * 0.8) strengthLabel = "strong";
+  else if (availableCount + partialCount >= totalSignals * 0.5) strengthLabel = "moderate";
+  else strengthLabel = "weak";
+
+  return {
+    label: strengthLabel,
+    evidenceCoverage,
+    signalCoverageMap,
+    availableSignals: availableCount,
+    totalSignals,
+  };
+}
+
+function buildComponentScores(signals, scoreData) {
+  const feedbackScore = signals.feedbackIntelligence?.score || 0;
+  const activationEvidenceScore = Math.round(
+    [
+      signals.installJourney?.status === "ready" ? 100 : 60,
+      signals.prelaunchReadiness?.status === "pass" ? 100 : signals.prelaunchReadiness ? 70 : 30,
+      signals.valueSummary ? 100 : 20,
+    ].reduce((sum, value) => sum + value, 0) / 3
+  );
+  const costEvidenceScore = signals.tokenCostIntelligence?.status === "ready"
+    ? 100
+    : signals.tokenCostIntelligence?.status === "partial"
+      ? 60
+      : 25;
+  const readinessEvidenceScore = Math.round(
+    [
+      signals.launchHardening?.status === "pass" ? 100 : signals.launchHardening ? 70 : 30,
+      signals.mcpPolicy?.status === "pass" ? 100 : signals.mcpPolicy ? 70 : 30,
+      signals.supportBundle?.status === "ready" ? 100 : signals.supportBundle ? 60 : 30,
+      signals.realityGate?.status === "pass" ? 100 : signals.realityGate ? 70 : 30,
+    ].reduce((sum, value) => sum + value, 0) / 4
+  );
+  const simulationCoverageScore = signals.externalUserSimulation
+    ? Math.round(((signals.externalUserSimulation.passed || 0) / Math.max(1, signals.externalUserSimulation.totalScenarios || 1)) * 100)
+    : 0;
+
+  return {
+    feedbackScore,
+    activationEvidenceScore,
+    costEvidenceScore,
+    readinessEvidenceScore,
+    simulationCoverageScore,
+  };
+}
+
+function buildMissingEvidence(signals, scoreData, frictionSummary, tokenCostSummary) {
+  const missingEvidence = [];
+  if ((signals.feedbackIntelligence?.qualifiedFeedbackItemsCount || 0) === 0) {
+    missingEvidence.push("No qualified redacted feedback evidence is available yet.");
+  }
+  if ((signals.tokenCostIntelligence?.realUsageSamplesCount || 0) === 0) {
+    missingEvidence.push("No real token/cost usage samples are available yet.");
+  }
+  if (!signals.proofOutcomeEvidence || signals.proofOutcomeEvidence.latestProofAvailable !== true) {
+    missingEvidence.push("No proof/value summary artifact is available from a real task.");
+  }
+  if (!signals.failureRecovery) {
+    missingEvidence.push("No failure-recovery plan artifact is available.");
+  }
+  if (!signals.hookDoctor && !signals.launchHardening) {
+    missingEvidence.push("No current hook/failure boundary verification artifact is available.");
+  }
+  if (frictionSummary.status === "insufficient_data") {
+    missingEvidence.push("Feedback coverage is insufficient for friction clustering.");
+  }
+  if (tokenCostSummary.evidenceMode === "missing" || tokenCostSummary.evidenceLevel === "not_available") {
+    missingEvidence.push("Token/cost evidence remains heuristic-only or missing.");
+  }
+  return missingEvidence;
+}
+
+function buildSafeNextActions(signals, scoreData, missingEvidence) {
+  const next = [];
+  const push = (value) => {
+    if (value && !next.includes(value)) next.push(value);
+  };
+  if ((signals.feedbackIntelligence?.qualifiedFeedbackItemsCount || 0) === 0) {
+    push("Run: node bin/avorelo feedback intake-pack --json");
+    push("Run: node bin/avorelo feedback import --file <redacted-json-or-jsonl> --json");
+    push("Run: node bin/avorelo feedback add --source dogfood --summary \"...\"");
+  }
+  if ((signals.tokenCostIntelligence?.realUsageSamplesCount || 0) === 0) {
+    push("Run: node bin/avorelo token-cost capture --json");
+    push("Run: node bin/avorelo token-cost import --file <redacted-json-or-jsonl> --json");
+    push("Run: node bin/avorelo token-efficiency --json");
+  }
+  if (!signals.proofOutcomeEvidence || signals.proofOutcomeEvidence.latestProofAvailable !== true) {
+    push("Run: node bin/avorelo proof after completing a real task");
+  }
+  if (!signals.failureRecovery) {
+    push("Run: node bin/avorelo launch-hardening --json");
+  }
+  if (missingEvidence.length === 0) {
+    push("Run: node bin/avorelo full-readiness --json");
+  }
+  return next;
+}
+
+// ── Recommended next PR ───────────────────────────────────────────────────────
+
+function buildRecommendedNextPr(signals, scoreData, frictionSummary, riskSummary) {
+  const blockers = scoreData.blockers;
+  const warnings = scoreData.warnings;
+  const topFriction = frictionSummary.topFriction;
+  const highRisks = riskSummary.highRiskCount;
+
+  if ((signals.feedbackIntelligence?.qualifiedFeedbackItemsCount || 0) === 0) {
+    return {
+      recommendation: "Operational: Import real design-partner feedback",
+      rationale: "Readiness still lacks qualified real feedback evidence. The intake primitive exists; the next honest move is collecting and importing redacted real feedback.",
+      confidence: "high",
+      notRecommendedYet: ["GrowthBook / variants — deferred until feedback and measurement evidence are stronger."],
+    };
+  }
+
+  if ((signals.tokenCostIntelligence?.realUsageSamplesCount || 0) === 0) {
+    return {
+      recommendation: "Operational: Capture/import real token-cost evidence",
+      rationale: "Token/cost evidence is still heuristic-only. Measured local samples are needed before stronger efficiency claims.",
+      confidence: "high",
+      notRecommendedYet: ["Website / pricing — deferred until measured token/cost evidence exists."],
+    };
+  }
+
+  // If insufficient data, recommend dogfood first
+  if (frictionSummary.status === "insufficient_data" && scoreData.score < 50) {
+    return {
+      recommendation: "Dogfood / Data Collection",
+      rationale: "Insufficient signal data. Run full Avorelo sequence and add dogfood feedback.",
+      confidence: "low",
+      notRecommendedYet: ["Website / pricing — deferred until Full Readiness Gate"],
+    };
+  }
+
+  // If core signals are strong enough, recommend Full Readiness Gate
+  if (scoreData.score >= 85 && highRisks === 0 && blockers.length === 0) {
+    return {
+      recommendation: "Full Readiness / Release Candidate Gate",
+      rationale: `Pre-launch intelligence score ${scoreData.score}/100. Core signals strong. Low risk.`,
+      confidence: "medium",
+      notRecommendedYet: ["Website / pricing — deferred until Full Readiness Gate passes"],
+    };
+  }
+
+  // Friction-based recommendations
+  if (topFriction === "browser_proof_missing") {
+    return {
+      recommendation: "Browser Proof / Visual QA Bridge",
+      rationale: "Visual proof friction is the dominant cluster.",
+      confidence: "medium",
+      notRecommendedYet: ["Website / pricing — deferred until Full Readiness Gate"],
+    };
+  }
+
+  if (topFriction === "plugin_distribution_unclear") {
+    return {
+      recommendation: "Plugin / Adapter Technical Readiness",
+      rationale: "Plugin distribution friction is the dominant cluster.",
+      confidence: "medium",
+      notRecommendedYet: ["Website / pricing — deferred until Full Readiness Gate"],
+    };
+  }
+
+  if (topFriction === "install_confusion" || topFriction === "ai_prompt_unclear" || topFriction === "hook_approval_unclear") {
+    return {
+      recommendation: "Install / activation repair",
+      rationale: `Install confusion (${topFriction}) is the dominant friction cluster.`,
+      confidence: "high",
+      notRecommendedYet: ["Website / pricing — deferred until repair complete"],
+    };
+  }
+
+  if (topFriction === "token_context_unknown" || topFriction === "exact_savings_unavailable") {
+    return {
+      recommendation: "Token / cost evidence repair",
+      rationale: "Token/cost evidence gaps are the dominant friction cluster.",
+      confidence: "medium",
+      notRecommendedYet: ["Website / pricing — deferred until Full Readiness Gate"],
+    };
+  }
+
+  if (topFriction === "mcp_governance_warn") {
+    return {
+      recommendation: "MCP governance repair",
+      rationale: "MCP governance warnings are the dominant friction cluster.",
+      confidence: "medium",
+      notRecommendedYet: ["Website / pricing — deferred until Full Readiness Gate"],
+    };
+  }
+
+  // Risk-based fallback
+  if (highRisks > 0) {
+    return {
+      recommendation: "Full Readiness / Release Candidate Gate (after risk repair)",
+      rationale: `${highRisks} high-risk signals detected. Repair before proceeding.`,
+      confidence: "low",
+      notRecommendedYet: ["Website / pricing — deferred until all risks resolved"],
+    };
+  }
+
+  // Default: head toward Full Readiness Gate
+  return {
+    recommendation: "Full Readiness / Release Candidate Gate",
+    rationale: `Pre-launch intelligence score ${scoreData.score}/100. No dominant blocker cluster.`,
+    confidence: "low",
+    notRecommendedYet: [
+      "Website / pricing — deferred until Full Readiness Gate",
+      "Browser Proof — only if visual proof friction dominates",
+      "Plugin readiness — only if distribution friction dominates",
+    ],
+  };
+}
+
+// ── Main build function ───────────────────────────────────────────────────────
+
+function buildPrelaunchIntelligence(cwd, options = {}) {
+  // Ensure sub-intelligences are built
+  const { buildFeedbackIntelligence, writeFeedbackIntelligence } = require("./feedback-intelligence");
+  const { buildTokenCostRollup, writeTokenCostIntelligence } = require("./token-cost-intelligence");
+  const { buildInstallJourneyIntelligence, writeInstallJourneyIntelligence } = require("./install-journey-intelligence");
+  const { buildProofOutcomeEvidence, writeProofOutcomeEvidence } = require("./proof-outcome-evidence");
+
+  const fbIntel = buildFeedbackIntelligence(cwd, options);
+  writeFeedbackIntelligence(cwd, fbIntel);
+
+  const tcIntel = buildTokenCostRollup(cwd, options);
+  writeTokenCostIntelligence(cwd, tcIntel);
+
+  const ijIntel = buildInstallJourneyIntelligence(cwd, options);
+  writeInstallJourneyIntelligence(cwd, ijIntel);
+  const proofIntel = buildProofOutcomeEvidence(cwd, options);
+  writeProofOutcomeEvidence(cwd, proofIntel);
+
+  // Re-collect signals including the freshly written sub-intelligences
+  const signals = collectPrelaunchSignals(cwd, options);
+  const scoreData = scorePrelaunchSignals(signals, options);
+
+  const installJourney = buildInstallJourneySummary(signals);
+  const frictionSummary = buildFrictionSummary(signals);
+  const tokenCostSummary = buildTokenCostSummary(signals);
+  const riskSummary = buildRiskSummary(signals);
+  const supportSummary = buildSupportSummary(signals);
+  const evidenceStrength = buildEvidenceStrength(signals, scoreData);
+  const componentScores = buildComponentScores(signals, scoreData);
+  const missingEvidence = buildMissingEvidence(signals, scoreData, frictionSummary, tokenCostSummary);
+  const safeNextActions = buildSafeNextActions(signals, scoreData, missingEvidence);
+  const recommendedNextPr = buildRecommendedNextPr(signals, scoreData, frictionSummary, riskSummary);
+
+  // Overall status
+  let status;
+  if (scoreData.score >= 85 && scoreData.blockers.length === 0) {
+    status = "ready";
+  } else if (scoreData.score >= 60) {
+    status = "warn";
+  } else if (evidenceStrength.availableSignals < evidenceStrength.totalSignals * 0.3) {
+    status = "insufficient_data";
+  } else {
+    status = "warn";
+  }
+
+  // Signal coverage summary
+  const signalCoverage = {
+    installSignals: signals.installPrompt !== null,
+    activationSignals: signals.prelaunchReadiness !== null,
+    tokenSignals: signals.tokenEfficiency !== null,
+    mcpSignals: signals.mcpInventory !== null,
+    hardeningSignals: signals.launchHardening !== null,
+    supportSignals: signals.supportBundle !== null,
+    proofSignals: signals.valueSummary !== null,
+    feedbackSignals: (fbIntel.totalFeedbackEntries || 0) > 0,
+    companyLoopSignals: signals.companyLoop !== null,
+  };
+
+  // Next action
+  let nextAction;
+  if (scoreData.blockers.length > 0) {
+    nextAction = scoreData.blockers[0].recoveryAction;
+  } else if (scoreData.warnings.length > 0) {
+    nextAction = scoreData.warnings[0].recoveryAction;
+  } else {
+    nextAction = recommendedNextPr.recommendation;
+  }
+
+  const intelligence = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    score: scoreData.score,
+    signalCoverage,
+    componentScores,
+    installJourney,
+    frictionSummary,
+    tokenCostSummary,
+    riskSummary,
+    supportSummary,
+    evidenceStrength,
+    missingEvidence,
+    safeNextActions,
+    recommendedNextPr,
+    blockers: scoreData.blockers,
+    warnings: scoreData.warnings,
+    nextAction,
+    noPublicLaunchClaim: true,
+    noReleaseReadyClaim: true,
+    noReleaseReadyClaimUnlessPassed: true,
+    redacted: true,
+  };
+
+  return intelligence;
+}
+
+function writePrelaunchIntelligence(cwd, intelligence) {
+  const dirAbs = path.join(cwd, INTELLIGENCE_DIR_REL);
+  fs.mkdirSync(dirAbs, { recursive: true });
+  const absPath = path.join(cwd, ARTIFACT_REL);
+  fs.writeFileSync(absPath, JSON.stringify(intelligence, null, 2), "utf8");
+  return absPath;
+}
+
+function buildPrelaunchIntelligenceSurface(cwd, options = {}) {
+  const absPath = path.join(cwd, ARTIFACT_REL);
+  const existing = safeReadJson(absPath);
+  if (existing && !options.refresh) {
+    return {
+      status: existing.status,
+      score: existing.score,
+      recommendedNextPr: existing.recommendedNextPr?.recommendation,
+      topFriction: existing.frictionSummary?.topFriction,
+      tokenEvidenceLevel: existing.tokenCostSummary?.evidenceLevel,
+      artifactPath: ARTIFACT_REL,
+    };
+  }
+  const intel = buildPrelaunchIntelligence(cwd, options);
+  writePrelaunchIntelligence(cwd, intel);
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "prelaunch_intelligence_run",
+      category: "prelaunch_intelligence",
+      status: intel.status,
+      score: intel.score,
+      recommendedNextPr: intel.recommendedNextPr?.recommendation,
+      topFriction: intel.frictionSummary?.topFriction,
+    });
+  } catch {}
+
+  return {
+    status: intel.status,
+    score: intel.score,
+    recommendedNextPr: intel.recommendedNextPr?.recommendation,
+    topFriction: intel.frictionSummary?.topFriction,
+    tokenEvidenceLevel: intel.tokenCostSummary?.evidenceLevel,
+    artifactPath: ARTIFACT_REL,
+  };
+}
+
+function formatPrelaunchIntelligenceText(intelligence, options = {}) {
+  const debug = options.debug === true;
+  const lines = [];
+
+  lines.push(`Pre-launch intelligence: ${intelligence.status}`);
+  lines.push("");
+  lines.push("Signals:");
+  lines.push(`  Install journey: ${intelligence.installJourney?.status || "not_available"}`);
+  lines.push(`  Feedback coverage: ${intelligence.frictionSummary?.status || "not_available"}`);
+  lines.push(`  Token/cost evidence: ${intelligence.tokenCostSummary?.evidenceLevel || "not_available"}`);
+  lines.push(`  Top friction: ${intelligence.frictionSummary?.topFriction || "none"}`);
+  lines.push("");
+  lines.push(`Next:`);
+  lines.push(`  ${intelligence.nextAction || intelligence.recommendedNextPr?.recommendation}`);
+  lines.push("");
+  lines.push("No launch-ready claim.");
+
+  if (debug) {
+    lines.push("");
+    lines.push(`Score: ${intelligence.score}/100`);
+    lines.push(`Evidence strength: ${intelligence.evidenceStrength?.label}`);
+    if (intelligence.componentScores) {
+      lines.push(`Feedback: ${intelligence.componentScores.feedbackScore}/100`);
+      lines.push(`Activation evidence: ${intelligence.componentScores.activationEvidenceScore}/100`);
+      lines.push(`Cost evidence: ${intelligence.componentScores.costEvidenceScore}/100`);
+      lines.push(`Readiness evidence: ${intelligence.componentScores.readinessEvidenceScore}/100`);
+      lines.push(`Simulation coverage: ${intelligence.componentScores.simulationCoverageScore}/100`);
+    }
+    if (intelligence.blockers?.length > 0) {
+      lines.push("");
+      lines.push(`Blockers (${intelligence.blockers.length}):`);
+      for (const b of intelligence.blockers) {
+        lines.push(`  - ${b.id}: ${b.description}`);
+        if (b.recoveryAction) lines.push(`    Recovery: ${b.recoveryAction}`);
+      }
+    }
+    if (intelligence.warnings?.length > 0) {
+      lines.push("");
+      lines.push(`Warnings (${intelligence.warnings.length}):`);
+      for (const w of intelligence.warnings.slice(0, 5)) {
+        lines.push(`  - ${w.id}: ${w.description}`);
+      }
+    }
+    if (intelligence.riskSummary?.risks?.length > 0) {
+      lines.push("");
+      lines.push("Risks:");
+      for (const r of intelligence.riskSummary.risks) {
+        lines.push(`  [${r.severity}] ${r.area}: ${r.description}`);
+      }
+    }
+    if (intelligence.missingEvidence?.length > 0) {
+      lines.push("");
+      lines.push("Missing evidence:");
+      for (const item of intelligence.missingEvidence.slice(0, 5)) {
+        lines.push(`  - ${item}`);
+      }
+    }
+    lines.push("");
+    lines.push(`Recommended next PR: ${intelligence.recommendedNextPr?.recommendation}`);
+    lines.push(`Rationale: ${intelligence.recommendedNextPr?.rationale}`);
+    lines.push(`Confidence: ${intelligence.recommendedNextPr?.confidence}`);
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  ARTIFACT_REL,
+  INTELLIGENCE_DIR_REL,
+  collectPrelaunchSignals,
+  scorePrelaunchSignals,
+  buildPrelaunchIntelligence,
+  writePrelaunchIntelligence,
+  buildPrelaunchIntelligenceSurface,
+  formatPrelaunchIntelligenceText,
+};