avorelo 0.1.0 → 0.2.0

package/scripts/lib/company-loop.js

@@ -1,1149 +0,0 @@
-"use strict";
-
-const fs = require("node:fs");
-const path = require("node:path");
-
-const CONTRACT = "avorelo.companyLoop.v1";
-const SCHEMA_VERSION = 1;
-
-const LOOP_DIR_REL = ".claude/cco/orchestration/company-loop";
-const LATEST_REPORT_REL = `${LOOP_DIR_REL}/latest-report.json`;
-
-const PERSONAS = Object.freeze([
-  "product_manager",
-  "qa_verification",
-  "ux_design",
-  "security",
-  "devex",
-  "cost_cogs",
-  "support_cs",
-  "marketing_growth",
-]);
-
-const PERSONA_LABELS = Object.freeze({
-  product_manager: "Product Manager",
-  qa_verification: "QA / Verification",
-  ux_design: "UX / Design Reviewer",
-  security: "Security Reviewer",
-  devex: "DevEx",
-  cost_cogs: "Cost / COGS",
-  support_cs: "Support / Customer Success",
-  marketing_growth: "Marketing / Growth",
-});
-
-const FRICTION_CLUSTER_TYPES = Object.freeze([
-  "missing_evidence",
-  "noisy_output",
-  "manual_fallback_required",
-  "generic_next_action",
-  "verification_missing",
-  "proof_missing",
-  "unavailable_worker",
-  "context_too_large",
-  "unknown_asset_repeated",
-  "high_risk_blocked_without_continuation",
-  "value_claim_not_evidence_backed",
-  "activation_friction",
-  "support_explainability_gap",
-]);
-
-const ROADMAP_CANDIDATES = Object.freeze([
-  "hook_baseline_pack",
-  "mcp_least_privilege_cleanup",
-  "browser_proof_evidence",
-  "plugin_adapter_technical_readiness",
-  "activation_alpha_readiness",
-  "repair_work_orchestration_accuracy",
-  "repair_value_evidence_ledger",
-  "repair_ux_noise_compactness",
-]);
-
-function safeReadJson(filePath) {
-  try {
-    if (!fs.existsSync(filePath)) return null;
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function makePersonaFinding(persona, status, finding, options = {}) {
-  return {
-    persona,
-    status,
-    finding,
-    evidence: options.evidence || null,
-    recommendedFix: options.recommendedFix || null,
-    severity: options.severity || (status === "fail" ? "high" : status === "warn" ? "medium" : "low"),
-    reasonCodes: options.reasonCodes || [],
-    redacted: true,
-  };
-}
-
-// --- Product Manager ---
-function reviewProductManager(ledger) {
-  const rollup = ledger.rollup || {};
-  const nextAction = rollup.nextAction;
-  const completedItems = (rollup.completed || []).filter((c) => c !== "not_available");
-  const orchEntry = (ledger.entries || []).find((e) => e.type === "orchestration");
-
-  if (completedItems.length === 0 && !orchEntry) {
-    return makePersonaFinding(
-      "product_manager",
-      "warn",
-      "No completed work or orchestration plan found. Ledger may be empty or first run.",
-      {
-        evidence: "ledger.rollup.completed = not_available",
-        recommendedFix: "Run a full Avorelo task to populate ledger entries.",
-        reasonCodes: ["NO_COMPLETED_WORK"],
-      }
-    );
-  }
-
-  if (!nextAction || nextAction.includes("Run node bin/avorelo outcome")) {
-    return makePersonaFinding(
-      "product_manager",
-      "warn",
-      "Next action is generic. Recommend a more specific next action from ledger evidence.",
-      {
-        evidence: nextAction,
-        recommendedFix: "Improve nextAction resolution from Reality Gate gaps or persona findings.",
-        reasonCodes: ["GENERIC_NEXT_ACTION"],
-      }
-    );
-  }
-
-  return makePersonaFinding(
-    "product_manager",
-    "pass",
-    `Next action clear. ${completedItems.length} completed item(s) in ledger.`,
-    { evidence: nextAction }
-  );
-}
-
-// --- QA / Verification ---
-function reviewQaVerification(ledger) {
-  const gateEntry = (ledger.entries || []).find((e) => e.type === "reality_gate");
-  const outcomeEntry = (ledger.entries || []).find((e) => e.type === "outcome");
-  const verified = ledger.rollup?.verified || [];
-
-  if (!gateEntry && !outcomeEntry) {
-    return makePersonaFinding(
-      "qa_verification",
-      "warn",
-      "No Reality Gate or outcome receipt found. Verification evidence missing.",
-      {
-        evidence: null,
-        recommendedFix: "Run node bin/avorelo outcome --gate to generate Reality Gate.",
-        reasonCodes: ["VERIFICATION_MISSING", "PROOF_MISSING"],
-      }
-    );
-  }
-
-  const gateStatus = gateEntry?.status;
-  if (gateStatus === "fail") {
-    return makePersonaFinding(
-      "qa_verification",
-      "fail",
-      `Reality Gate failed. ${gateEntry.summary}`,
-      {
-        evidence: gateEntry.evidencePath,
-        recommendedFix: "Fix Reality Gate failures before merging.",
-        severity: "high",
-        reasonCodes: gateEntry.reasonCodes || [],
-      }
-    );
-  }
-
-  if (gateStatus === "warn") {
-    return makePersonaFinding(
-      "qa_verification",
-      "warn",
-      `Reality Gate has warnings. ${gateEntry.summary}`,
-      {
-        evidence: gateEntry.evidencePath,
-        recommendedFix: "Review Reality Gate warnings and address where possible.",
-        reasonCodes: gateEntry.reasonCodes || [],
-      }
-    );
-  }
-
-  return makePersonaFinding(
-    "qa_verification",
-    "pass",
-    `Verification evidence present. ${verified.length > 0 ? verified.join(", ") : "Reality Gate available."}`,
-    { evidence: gateEntry?.evidencePath || outcomeEntry?.evidencePath }
-  );
-}
-
-// --- UX / Design ---
-function reviewUxDesign(ledger) {
-  const friction = ledger.rollup?.friction || [];
-  const noisyFriction = friction.filter(
-    (f) =>
-      f.includes("noisy") ||
-      f.includes("verbose") ||
-      f.includes("dump") ||
-      f.includes("scattered")
-  );
-
-  if (noisyFriction.length > 0) {
-    return makePersonaFinding(
-      "ux_design",
-      "warn",
-      `Noisy output signals detected: ${noisyFriction.join(", ")}.`,
-      {
-        evidence: noisyFriction.join(", "),
-        recommendedFix: "Audit default CLI output for verbosity and move details behind --debug.",
-        reasonCodes: ["NOISY_DEFAULT_OUTPUT"],
-      }
-    );
-  }
-
-  const orchEntry = (ledger.entries || []).find((e) => e.type === "orchestration");
-  if (orchEntry?.status === "pass") {
-    return makePersonaFinding(
-      "ux_design",
-      "pass",
-      "Ledger compact by default. Debug detail available via --debug flag.",
-      { evidence: "ledger.formatWorkLedgerText" }
-    );
-  }
-
-  return makePersonaFinding(
-    "ux_design",
-    "skip",
-    "No specific UX signal in current ledger. Compact default assumed.",
-    {}
-  );
-}
-
-// --- Security ---
-function reviewSecurity(ledger) {
-  const guardEntry = (ledger.entries || []).find((e) => e.type === "guard");
-  const hygieneEntry = (ledger.entries || []).find((e) => e.type === "workspace_hygiene");
-
-  const riskSignals = ledger.entries
-    ? ledger.entries.flatMap((e) => e.riskSignals || [])
-    : [];
-
-  if (!guardEntry && !hygieneEntry) {
-    return makePersonaFinding(
-      "security",
-      "warn",
-      "No guard or workspace hygiene receipt found. Security posture unverified.",
-      {
-        recommendedFix: "Run node bin/avorelo workspace-hygiene and node bin/avorelo guard.",
-        reasonCodes: ["GUARD_RECEIPT_MISSING", "HYGIENE_RECEIPT_MISSING"],
-      }
-    );
-  }
-
-  const highRisk = riskSignals.filter(
-    (r) =>
-      r.includes("critical") ||
-      r.includes("unknown_subjects") ||
-      r.includes("high_risk")
-  );
-
-  if (highRisk.length > 0) {
-    return makePersonaFinding(
-      "security",
-      "warn",
-      `High-risk signals present: ${highRisk.join(", ")}.`,
-      {
-        evidence: riskSignals.join(", "),
-        recommendedFix: "Review high-risk assets and unknown subjects before proceeding.",
-        reasonCodes: highRisk,
-      }
-    );
-  }
-
-  return makePersonaFinding(
-    "security",
-    "pass",
-    `Guard and hygiene evidence present. Risk signals: ${riskSignals.join(", ") || "none"}.`,
-    { evidence: guardEntry?.evidencePath || hygieneEntry?.evidencePath }
-  );
-}
-
-// --- DevEx ---
-function reviewDevEx(ledger) {
-  const orchEntry = (ledger.entries || []).find((e) => e.type === "orchestration");
-  const friction = ledger.rollup?.friction || [];
-  const handoffFriction = friction.filter(
-    (f) => f.includes("handoff") || f.includes("continuation") || f.includes("manual_fallback")
-  );
-
-  if (handoffFriction.length > 0) {
-    return makePersonaFinding(
-      "devex",
-      "warn",
-      `Handoff/continuation friction: ${handoffFriction.join(", ")}.`,
-      {
-        evidence: handoffFriction.join(", "),
-        recommendedFix: "Improve stage handoff and continuation paths.",
-        reasonCodes: ["HANDOFF_FRICTION"],
-      }
-    );
-  }
-
-  if (orchEntry?.status === "pass") {
-    const orchData = orchEntry.summary;
-    return makePersonaFinding(
-      "devex",
-      "pass",
-      `Orchestration available and usable. ${orchData}`,
-      { evidence: orchEntry.evidencePath }
-    );
-  }
-
-  return makePersonaFinding(
-    "devex",
-    "skip",
-    "DevEx signals not determinable from current ledger.",
-    {}
-  );
-}
-
-// --- Cost / COGS ---
-function reviewCostCogs(ledger) {
-  const saved = ledger.rollup?.saved || [];
-  const orchEntry = (ledger.entries || []).find((e) => e.type === "orchestration");
-  const frictions = ledger.rollup?.friction || [];
-  const contextLarge = frictions.filter(
-    (f) => f.includes("context_too_large") || f.includes("broad_scan")
-  );
-
-  if (contextLarge.length > 0) {
-    return makePersonaFinding(
-      "cost_cogs",
-      "warn",
-      `Context/cost friction detected: ${contextLarge.join(", ")}.`,
-      {
-        evidence: contextLarge.join(", "),
-        recommendedFix: "Reduce context budget or improve hygiene-guided exclusions.",
-        reasonCodes: ["CONTEXT_TOO_LARGE"],
-      }
-    );
-  }
-
-  const localSignals = saved.filter((s) => s.includes("local") || s.includes("cheap"));
-
-  if (localSignals.length > 0) {
-    return makePersonaFinding(
-      "cost_cogs",
-      "pass",
-      `Local/cheap stages used: ${localSignals.join(", ")}.`,
-      {
-        evidence: localSignals.join(", "),
-      }
-    );
-  }
-
-  return makePersonaFinding(
-    "cost_cogs",
-    "skip",
-    "Cost/COGS signals not determinable. No local-stage evidence in ledger.",
-    {
-      recommendedFix: "Run orchestrate to generate stage worker evidence.",
-    }
-  );
-}
-
-// --- Support / CS ---
-function reviewSupportCs(ledger) {
-  const outcomeEntry = (ledger.entries || []).find((e) => e.type === "outcome");
-  const rollup = ledger.rollup || {};
-
-  if (!outcomeEntry) {
-    return makePersonaFinding(
-      "support_cs",
-      "warn",
-      "No outcome receipt found. Customer-explainable summary unavailable.",
-      {
-        recommendedFix: "Run node bin/avorelo outcome to generate value summary.",
-        reasonCodes: ["SUPPORT_EXPLAINABILITY_GAP"],
-      }
-    );
-  }
-
-  const hasEvidence = ledger.evidence?.receiptPaths?.length > 0;
-  return makePersonaFinding(
-    "support_cs",
-    "pass",
-    `Outcome summary available. Evidence paths: ${hasEvidence ? ledger.evidence.receiptPaths.length : 0}.`,
-    { evidence: outcomeEntry.evidencePath }
-  );
-}
-
-// --- Marketing / Growth ---
-function reviewMarketingGrowth(ledger) {
-  const frictions = ledger.rollup?.friction || [];
-  const valueClaims = frictions.filter((f) => f.includes("not_evidence_backed"));
-
-  if (valueClaims.length > 0) {
-    return makePersonaFinding(
-      "marketing_growth",
-      "warn",
-      `Value claims not fully evidence-backed: ${valueClaims.join(", ")}.`,
-      {
-        evidence: valueClaims.join(", "),
-        recommendedFix: "Ensure all value signals reference receipt evidence paths.",
-        reasonCodes: ["VALUE_CLAIM_NOT_EVIDENCE_BACKED"],
-      }
-    );
-  }
-
-  return makePersonaFinding(
-    "marketing_growth",
-    "pass",
-    "No positioning drift detected. Value claims reference receipt evidence.",
-    {}
-  );
-}
-
-function runInternalPersonaReview(ledger) {
-  return [
-    reviewProductManager(ledger),
-    reviewQaVerification(ledger),
-    reviewUxDesign(ledger),
-    reviewSecurity(ledger),
-    reviewDevEx(ledger),
-    reviewCostCogs(ledger),
-    reviewSupportCs(ledger),
-    reviewMarketingGrowth(ledger),
-  ];
-}
-
-function clusterFriction(ledger, personaFindings) {
-  const clusters = [];
-
-  function countFriction(signalMatches, clusterType, severity, examples, recommendedFix) {
-    if (signalMatches.length === 0) return;
-    clusters.push({
-      clusterId: `cluster-${clusterType.replace(/_/g, "-")}`,
-      type: clusterType,
-      severity,
-      count: signalMatches.length,
-      examples: signalMatches.slice(0, 3),
-      evidencePaths: ledger.evidence?.receiptPaths?.slice(0, 3) || [],
-      recommendedFix,
-      candidateRoadmapItem: mapFrictionToRoadmap(clusterType),
-      redacted: true,
-    });
-  }
-
-  const frictionSignals = [
-    ...(ledger.rollup?.friction || []),
-    ...personaFindings
-      .filter((pf) => pf.status === "warn" || pf.status === "fail")
-      .flatMap((pf) => pf.reasonCodes || []),
-  ];
-
-  const allEntries = ledger.entries || [];
-
-  // Missing evidence
-  const missingEv = frictionSignals.filter(
-    (f) =>
-      f.includes("missing") ||
-      f.includes("not_available") ||
-      f.includes("MISSING") ||
-      f.includes("NO_")
-  );
-  countFriction(missingEv, "missing_evidence", "medium", missingEv,
-    "Generate missing receipts with full Avorelo run.");
-
-  // Noisy output
-  const noisy = frictionSignals.filter((f) => f.includes("noisy") || f.includes("verbose"));
-  countFriction(noisy, "noisy_output", "low", noisy,
-    "Move debug detail behind --debug flag.");
-
-  // Manual fallback
-  const manual = frictionSignals.filter(
-    (f) => f.includes("manual_fallback") || f.includes("INSPECT_MAP_FIRST")
-  );
-  countFriction(manual, "manual_fallback_required", "medium", manual,
-    "Run workspace-hygiene before orchestrate to enable automatic context selection.");
-
-  // Generic next action
-  const generic = personaFindings.filter(
-    (pf) => (pf.reasonCodes || []).includes("GENERIC_NEXT_ACTION")
-  );
-  if (generic.length > 0) {
-    countFriction(
-      generic.map((g) => g.persona),
-      "generic_next_action",
-      "medium",
-      generic.map((g) => g.finding),
-      "Resolve Reality Gate gaps to produce specific next action."
-    );
-  }
-
-  // Verification missing
-  const verMissing = frictionSignals.filter(
-    (f) => f.includes("VERIFICATION_MISSING") || f.includes("reality_gate_failures")
-  );
-  countFriction(verMissing, "verification_missing", "high", verMissing,
-    "Run node bin/avorelo outcome --gate to produce verification evidence.");
-
-  // Proof missing
-  const proofMissing = frictionSignals.filter((f) => f.includes("PROOF_MISSING"));
-  countFriction(proofMissing, "proof_missing", "medium", proofMissing,
-    "Run node bin/avorelo proof after task completion.");
-
-  // Unknown asset repeated
-  const unknownAsset = frictionSignals.filter(
-    (f) => f.includes("unknown_asset") || f.includes("UNKNOWN_ASSET")
-  );
-  countFriction(unknownAsset, "unknown_asset_repeated", "medium", unknownAsset,
-    "Review and classify unknown workspace assets.");
-
-  // Value not evidence-backed
-  const valueClaims = frictionSignals.filter(
-    (f) => f.includes("not_evidence_backed") || f.includes("VALUE_CLAIM")
-  );
-  countFriction(valueClaims, "value_claim_not_evidence_backed", "medium", valueClaims,
-    "Link value signals to receipt evidence paths.");
-
-  // Context too large
-  const contextLarge = frictionSignals.filter(
-    (f) => f.includes("context_too_large") || f.includes("CONTEXT_TOO_LARGE")
-  );
-  countFriction(contextLarge, "context_too_large", "medium", contextLarge,
-    "Reduce context budget or improve hygiene-guided exclusions.");
-
-  // Support explainability gap
-  const suppGap = frictionSignals.filter(
-    (f) => f.includes("SUPPORT_EXPLAINABILITY_GAP") || f.includes("explainability")
-  );
-  countFriction(suppGap, "support_explainability_gap", "low", suppGap,
-    "Generate outcome summary before completing task.");
-
-  return clusters;
-}
-
-function mapFrictionToRoadmap(clusterType) {
-  const map = {
-    missing_evidence: "repair_value_evidence_ledger",
-    noisy_output: "repair_ux_noise_compactness",
-    manual_fallback_required: "hook_baseline_pack",
-    generic_next_action: "repair_value_evidence_ledger",
-    verification_missing: "repair_work_orchestration_accuracy",
-    proof_missing: "browser_proof_evidence",
-    unknown_asset_repeated: "mcp_least_privilege_cleanup",
-    context_too_large: "repair_work_orchestration_accuracy",
-    value_claim_not_evidence_backed: "repair_value_evidence_ledger",
-    support_explainability_gap: "activation_alpha_readiness",
-    activation_friction: "activation_alpha_readiness",
-    high_risk_blocked_without_continuation: "repair_work_orchestration_accuracy",
-  };
-  return map[clusterType] || null;
-}
-
-function buildCostCogsQualityRollup(ledger, personaFindings) {
-  const saved = ledger.rollup?.saved || [];
-  const verified = ledger.rollup?.verified || [];
-  const friction = ledger.rollup?.friction || [];
-
-  const localStages = saved.filter((s) => s.includes("local")).length;
-  const tokenSavings = saved
-    .filter((s) => s.includes("token"))
-    .map((s) => {
-      const m = s.match(/(\d+)/);
-      return m ? parseInt(m[1], 10) : 0;
-    });
-  const totalTokenSavingsEstimate = tokenSavings.reduce((a, b) => a + b, 0);
-
-  const costPersona = personaFindings.find((p) => p.persona === "cost_cogs");
-  const qaPersona = personaFindings.find((p) => p.persona === "qa_verification");
-
-  return {
-    estimatedLocalStagesUsed: localStages,
-    estimatedContextTokensSaved: totalTokenSavingsEstimate,
-    estimateMethod: totalTokenSavingsEstimate > 0 ? "receipt_based_estimate" : "not_available",
-    qualityChecksVerified: verified.length,
-    frictionPointsDetected: friction.length,
-    costPersonaStatus: costPersona?.status || "skip",
-    qualityPersonaStatus: qaPersona?.status || "skip",
-    caveats: [
-      "Token savings are estimates from receipt data, not exact billing amounts.",
-      "No exact/guaranteed savings are claimed.",
-    ],
-    redacted: true,
-  };
-}
-
-function recommendNextPr(ledger, personaFindings, frictionClusters) {
-  const friction = ledger.rollup?.friction || [];
-  const frictionTypes = frictionClusters.map((c) => c.type);
-  const realityGateEntry = (ledger.entries || []).find((e) => e.type === "reality_gate");
-  const gateStatus = realityGateEntry?.status;
-  const evidencePaths = ledger.evidence?.receiptPaths || [];
-
-  let recommended = null;
-  let whyNow = null;
-  let confidence = "low";
-
-  // Hook Apply — lifecycle hooks not yet applied (PR #141)
-  const hooksNotApplied = friction.some((f) => f === "hooks_not_yet_applied" || f === "hooks_not_yet_installed");
-  const hooksApplied = evidencePaths.some((p) => p.includes("hook-apply/latest-apply.json"));
-  if (hooksNotApplied && !hooksApplied) {
-    recommended = "Explicit Hook Apply + Lifecycle Live";
-    whyNow = "Lifecycle hooks are previewed but not yet applied. Apply to make Avorelo seamless.";
-    confidence = "high";
-  }
-
-  // Hook Baseline Pack — lifecycle/hook evidence missing or manual fallback
-  else if (
-    frictionTypes.includes("manual_fallback_required") ||
-    friction.some((f) => f.includes("INSPECT_MAP_FIRST") || f.includes("NO_HYGIENE_REPORT"))
-  ) {
-    recommended = "Hook Baseline Pack + Claude/OpenHands-compatible adapters";
-    whyNow = "Manual fallback and missing lifecycle evidence are the top friction clusters.";
-    confidence = "medium";
-  }
-
-  // MCP Least-Privilege Cleanup
-  else if (frictionTypes.includes("unknown_asset_repeated")) {
-    recommended = "MCP Least-Privilege Cleanup";
-    whyNow = "Unknown/broad workspace assets repeatedly appear in hygiene and context receipts.";
-    confidence = "medium";
-  }
-
-  // Browser Proof / Evidence
-  else if (frictionTypes.includes("proof_missing")) {
-    recommended = "Browser Proof / Evidence";
-    whyNow = "Proof gaps detected across ledger entries.";
-    confidence = "low";
-  }
-
-  // Post-activation: if alpha activation is present and gate passes, recommend next layer
-  else if (
-    evidencePaths.some((p) => p.includes("alpha-readiness/latest-gate.json")) &&
-    evidencePaths.some((p) => p.includes("orchestration/activation/latest-activation.json"))
-  ) {
-    recommended = "MCP Least-Privilege Cleanup or Launch Hardening";
-    whyNow = "Alpha activation and readiness gate are in place. Next: harden for launch or clean MCP surfaces.";
-    confidence = "medium";
-  }
-
-  // Activation / Alpha Readiness
-  else if (
-    frictionTypes.includes("activation_friction") ||
-    frictionTypes.includes("support_explainability_gap")
-  ) {
-    recommended = "Activation / Alpha Readiness / Customer Feedback Loop";
-    whyNow = "Activation friction and support explainability gaps dominate.";
-    confidence = "medium";
-  }
-
-  // Repair: Value evidence / ledger accuracy
-  else if (
-    frictionTypes.includes("missing_evidence") ||
-    frictionTypes.includes("value_claim_not_evidence_backed")
-  ) {
-    recommended = "Repair: Value evidence / ledger accuracy";
-    whyNow = "Missing or unevidenced value claims in ledger rollup.";
-    confidence = "medium";
-  }
-
-  // Repair: Work-Aware Orchestration accuracy
-  else if (
-    frictionTypes.includes("verification_missing") ||
-    frictionTypes.includes("context_too_large")
-  ) {
-    recommended = "Repair: Work-Aware Orchestration accuracy";
-    whyNow = "Verification gaps or context overload in orchestration stage.";
-    confidence = "low";
-  }
-
-  // Default — Repair UX/noise/compactness
-  else if (frictionTypes.includes("noisy_output")) {
-    recommended = "Repair: UX/noise/compactness";
-    whyNow = "Noisy output friction detected in default surfaces.";
-    confidence = "low";
-  }
-
-  // Fallback
-  else {
-    recommended = "Repair: Value evidence / ledger accuracy";
-    whyNow = "No dominant friction cluster — ledger may need more receipt population.";
-    confidence = "low";
-  }
-
-  const notRecommendedYet = [
-    "Public positioning / pricing / website changes — deferred until Alpha Readiness passes.",
-    "Cloud telemetry / external analytics — intentionally deferred.",
-    "Browser Proof — deferred unless proof_missing is dominant cluster.",
-    "Full execution runtime — deferred.",
-  ];
-
-  return {
-    recommendedNextPr: recommended,
-    whyNow,
-    evidencePaths: evidencePaths.slice(0, 5),
-    expectedValue: "Reduce top friction cluster and improve ledger completeness.",
-    risk: "low",
-    confidence,
-    notRecommendedYet,
-    redacted: true,
-  };
-}
-
-function recommendNextPrWithIntelligence(ledger, personaFindings, frictionClusters, intelligenceSignals) {
-  // Start with base recommendation
-  const base = recommendNextPr(ledger, personaFindings, frictionClusters);
-
-  if (!intelligenceSignals) return base;
-
-  const topFriction = intelligenceSignals.topFriction;
-  const prelaunchScore = intelligenceSignals.prelaunchScore || 0;
-  const tokenLevel = intelligenceSignals.tokenEvidenceLevel;
-  const journeyStatus = intelligenceSignals.journeyStatus;
-
-  // Override with intelligence-backed recommendation
-  if (topFriction === "browser_proof_missing") {
-    return {
-      ...base,
-      recommendedNextPr: "Browser Proof / Visual QA Bridge",
-      whyNow: "Visual proof friction dominates feedback intelligence clusters.",
-      confidence: "medium",
-    };
-  }
-
-  if (topFriction === "plugin_distribution_unclear") {
-    return {
-      ...base,
-      recommendedNextPr: "Plugin / Adapter Technical Readiness",
-      whyNow: "Plugin distribution friction dominates feedback intelligence clusters.",
-      confidence: "medium",
-    };
-  }
-
-  if (topFriction === "install_confusion" || topFriction === "ai_prompt_unclear" || topFriction === "hook_approval_unclear") {
-    return {
-      ...base,
-      recommendedNextPr: "Install / activation repair",
-      whyNow: `Install confusion (${topFriction}) is the dominant cluster from feedback intelligence.`,
-      confidence: "high",
-    };
-  }
-
-  if (topFriction === "token_context_unknown" || tokenLevel === "not_available") {
-    return {
-      ...base,
-      recommendedNextPr: "Token / cost evidence repair",
-      whyNow: "Token/cost evidence missing or unclear per intelligence layer.",
-      confidence: "medium",
-    };
-  }
-
-  // If intelligence score is strong and journey is ready, recommend Full Readiness Gate
-  if (prelaunchScore >= 85 && journeyStatus === "ready") {
-    return {
-      ...base,
-      recommendedNextPr: "Full Readiness / Release Candidate Gate",
-      whyNow: `Pre-launch intelligence score ${prelaunchScore}/100. Install journey ready. No dominant blocker.`,
-      confidence: "medium",
-    };
-  }
-
-  // If no intelligence override, use base recommendation
-  return base;
-}
-
-
-function recommendNextPrWithFullReadiness(ledger, personaFindings, frictionClusters, intelligenceSignals, fullReadinessSignals) {
-  const base = recommendNextPrWithIntelligence(ledger, personaFindings, frictionClusters, intelligenceSignals);
-  if (!fullReadinessSignals) return base;
-
-  const gateStatus = fullReadinessSignals.gateStatus;
-  const rcStatus = fullReadinessSignals.releaseCandidateStatus;
-  const blockerCount = fullReadinessSignals.blockerCount || 0;
-  const safetyBlocker = fullReadinessSignals.safetyBlocker;
-  const installDistributionDominates = fullReadinessSignals.installDistributionDominates;
-  const browserProofDominates = fullReadinessSignals.browserProofDominates;
-  const pluginAdapterDominates = fullReadinessSignals.pluginAdapterDominates;
-  const feedbackInsufficient = fullReadinessSignals.feedbackInsufficient;
-  const tokenEvidenceMissing = fullReadinessSignals.tokenEvidenceMissing;
-  const proofOutcomeMissing = fullReadinessSignals.proofOutcomeMissing;
-
-  if (safetyBlocker) {
-    return { ...base, recommendedNextPr: "Repair: Safety / Support / MCP blocker", whyNow: "Full readiness gate has a safety/MCP hard blocker. Repair before launch.", confidence: "high", notRecommendedYet: [...(base.notRecommendedYet || []), "Website / pricing � deferred until gate passes with no safety blockers."] };
-  }
-  if (feedbackInsufficient) {
-    return { ...base, recommendedNextPr: "Operational: Import real design-partner feedback", whyNow: "Full readiness still lacks qualified redacted feedback evidence.", confidence: "high" };
-  }
-  if (tokenEvidenceMissing) {
-    return { ...base, recommendedNextPr: "Operational: Capture/import real token-cost evidence", whyNow: "Token/cost evidence is still heuristic-only or missing measured usage samples.", confidence: "high" };
-  }
-  if (proofOutcomeMissing) {
-    return { ...base, recommendedNextPr: "Operational: Run proof after a real bounded task", whyNow: "A real proof/value summary artifact is still missing from readiness evidence.", confidence: "medium" };
-  }
-  if (rcStatus === "candidate_ready" && blockerCount === 0) {
-    // If adapter readiness is already verified, move to alpha launch candidate prep
-    if (fullReadinessSignals && fullReadinessSignals.adapterReadinessVerified) {
-      return { ...base, recommendedNextPr: "Alpha Launch Candidate Prep", whyNow: "Full readiness gate and adapter technical readiness both passed. Ready for alpha launch candidate.", confidence: "high" };
-    }
-    return { ...base, recommendedNextPr: "Plugin/Adapter Technical Readiness", whyNow: "Full readiness gate passed. Distribution truth verified. Plugin/adapter readiness is next.", confidence: "high" };
-  }
-  if (rcStatus === "candidate_warn" && blockerCount === 0 && installDistributionDominates) {
-    return { ...base, recommendedNextPr: "Repair: Distribution blockers before next PR", whyNow: "Gate warned with distribution blockers. Repair install claims or package content.", confidence: "high" };
-  }
-  if (browserProofDominates) {
-    return { ...base, recommendedNextPr: "Browser Proof / Visual QA Bridge", whyNow: "Browser proof limitation is dominant in full readiness gate.", confidence: "medium" };
-  }
-  if (pluginAdapterDominates) {
-    return { ...base, recommendedNextPr: "Plugin / Adapter Technical Readiness", whyNow: "Plugin/adapter limitation is dominant.", confidence: "medium" };
-  }
-  if (gateStatus === "blocked" && fullReadinessSignals.gateRecommendedNextPr) {
-    return { ...base, recommendedNextPr: fullReadinessSignals.gateRecommendedNextPr, whyNow: "Full readiness gate blocked. Repair required.", confidence: "high" };
-  }
-  const notRecommendedYet = [...(base.notRecommendedYet || [])];
-  if (rcStatus !== "candidate_ready" && !(rcStatus === "candidate_warn" && blockerCount === 0)) {
-    if (!notRecommendedYet.includes("Website / pricing � deferred until full readiness gate passes.")) {
-      notRecommendedYet.push("Website / pricing � deferred until full readiness gate passes.");
-    }
-  }
-  return { ...base, notRecommendedYet };
-}
-
-function buildCompanyLoop(cwd, options = {}) {
-  const { buildWorkLedger, writeWorkLedger } = require("./work-ledger");
-  const ledger = buildWorkLedger(cwd, options);
-
-  // Read alpha feedback into ledger friction signals (local only)
-  try {
-    const { readFeedbackSummary } = require("./alpha-feedback");
-    const feedbackSummary = readFeedbackSummary(cwd);
-    if (feedbackSummary && feedbackSummary.topFrictionType) {
-      const rollupFriction = ledger.rollup?.friction;
-      if (Array.isArray(rollupFriction)) {
-        rollupFriction.push(`alpha_feedback:${feedbackSummary.topFrictionType}`);
-      }
-    }
-  } catch {}
-
-  // Consume pre-launch intelligence signals (PR #147)
-  let intelligenceSignals = null;
-  try {
-    const { collectPrelaunchSignals, scorePrelaunchSignals } = require("./prelaunch-intelligence");
-    const { buildFeedbackIntelligenceSurface } = require("./feedback-intelligence");
-    const { buildTokenCostIntelligenceSurface } = require("./token-cost-intelligence");
-    const { buildInstallJourneySurface } = require("./install-journey-intelligence");
-
-    const signals = collectPrelaunchSignals(cwd, options);
-    const scoreData = scorePrelaunchSignals(signals, options);
-    const feedbackSurface = buildFeedbackIntelligenceSurface(cwd, options);
-    const tokenSurface = buildTokenCostIntelligenceSurface(cwd, options);
-    const journeySurface = buildInstallJourneySurface(cwd, options);
-
-    intelligenceSignals = {
-      prelaunchScore: scoreData.score,
-      prelaunchStatus: scoreData.score >= 85 ? "strong" : scoreData.score >= 60 ? "moderate" : "weak",
-      topFriction: feedbackSurface.topFriction,
-      feedbackClusters: feedbackSurface.clustersFound,
-      qualifiedFeedbackItemsCount: feedbackSurface.qualifiedFeedbackItemsCount || 0,
-      tokenEvidenceLevel: tokenSurface.evidenceLevel,
-      tokenRealUsageSamplesCount: tokenSurface.realUsageSamplesCount || 0,
-      journeyStatus: journeySurface.status,
-      manualStepsAvoided: journeySurface.manualStepsAvoided,
-      aiInstallReady: signals.installPrompt?.status === "ready",
-      prelaunchReadinessScore: signals.prelaunchReadiness?.score,
-    };
-
-    // Inject intelligence-based friction into ledger
-    const rollupFriction = ledger.rollup?.friction;
-    if (Array.isArray(rollupFriction)) {
-      if (feedbackSurface.topFriction) {
-        rollupFriction.push(`intelligence_friction:${feedbackSurface.topFriction}`);
-      }
-      if (tokenSurface.evidenceLevel === "not_available") {
-        rollupFriction.push("intelligence_friction:token_context_unknown");
-      }
-      if (journeySurface.status !== "ready") {
-        rollupFriction.push("intelligence_friction:install_journey_incomplete");
-      }
-    }
-  } catch {}
-
-  const personaFindings = runInternalPersonaReview(ledger);
-  const frictionClusters = clusterFriction(ledger, personaFindings);
-  const cogsRollup = buildCostCogsQualityRollup(ledger, personaFindings);
-  // Consume full readiness gate signals (PR #148)
-  let fullReadinessSignals = null;
-  try {
-    const { buildFullReadinessSurface } = require("./full-readiness-gate");
-    const { buildKnownLimitationsSurface } = require("./known-limitations");
-    const { buildProofOutcomeEvidenceSurface } = require("./proof-outcome-evidence");
-    const gateSurface = buildFullReadinessSurface(cwd, options);
-    const limitationsSurface = buildKnownLimitationsSurface(cwd, options);
-    const proofOutcomeSurface = buildProofOutcomeEvidenceSurface(cwd, options);
-    if (gateSurface.status !== "not_available") {
-      const limitationsList = limitationsSurface?.limitations || [];
-      fullReadinessSignals = {
-        gateStatus: gateSurface.status,
-        releaseCandidateStatus: gateSurface.releaseCandidateStatus,
-        blockerCount: gateSurface.blockerCount,
-        gateRecommendedNextPr: gateSurface.recommendedNextPr,
-        safetyBlocker: (gateSurface.blockerCount || 0) > 0 &&
-          ["mcp_tool_governance","hook_safety_boundaries","support_bundle_redaction","no_false_claims"].some(
-            (id) => (gateSurface.blockers || []).find((b) => b.id === id)
-          ),
-        adapterReadinessVerified: false, // will be updated when adapterReadinessSignals is consumed
-        installDistributionDominates:
-          (limitationsList).some((l) => l.id === "install_distribution" && l.severity !== "info") &&
-          (intelligenceSignals?.qualifiedFeedbackItemsCount || 0) > 0 &&
-          (intelligenceSignals?.tokenRealUsageSamplesCount || 0) > 0,
-        browserProofDominates:
-          intelligenceSignals?.topFriction === "browser_proof_missing" ||
-          (limitationsList).some((l) => l.id === "browser_proof_missing" && l.severity === "blocker"),
-        pluginAdapterDominates:
-          (limitationsList).some((l) => l.id === "plugin_adapter_pending" && l.severity === "blocker"),
-        feedbackInsufficient:
-          (intelligenceSignals?.qualifiedFeedbackItemsCount || 0) === 0,
-        tokenEvidenceMissing:
-          (intelligenceSignals?.tokenRealUsageSamplesCount || 0) === 0,
-        proofOutcomeMissing:
-          proofOutcomeSurface.latestProofAvailable !== true || (proofOutcomeSurface.realTaskProofCount || 0) === 0,
-      };
-    }
-  } catch {}
-
-  // Consume activation distribution readiness signals (PR #149)
-  let activationDistributionSignals = null;
-  try {
-    const { buildActivationDistributionSurface } = require("./activation-distribution-readiness");
-    const adrSurface = buildActivationDistributionSurface(cwd, options);
-    if (adrSurface.status !== "not_available") {
-      activationDistributionSignals = {
-        status: adrSurface.status,
-        score: adrSurface.score,
-        blockerCount: adrSurface.blockerCount || 0,
-        warningCount: adrSurface.warningCount || 0,
-        isReady: adrSurface.status === "ready",
-        safeNextAction: (adrSurface.safeNextActions || [])[0] || null,
-      };
-      if (fullReadinessSignals && activationDistributionSignals.blockerCount > 0) {
-        fullReadinessSignals.installDistributionDominates = true;
-      }
-    }
-  } catch {}
-
-  // Consume public distribution gate signals (PR #161)
-  let publicDistributionSignals = null;
-  try {
-    const pdGatePath = path.join(cwd, ".claude/cco/orchestration/public-distribution/latest-gate.json");
-    if (fs.existsSync(pdGatePath)) {
-      const pdGate = JSON.parse(fs.readFileSync(pdGatePath, "utf8"));
-      if (pdGate && pdGate.status) {
-        publicDistributionSignals = {
-          status: pdGate.status,
-          score: pdGate.score,
-          blockerCount: (pdGate.blockers || []).length,
-          warningCount: (pdGate.warnings || []).length,
-          publicInstallStatus: pdGate.publicInstallStatus,
-          claimSafetyStatus: pdGate.claimSafetyStatus,
-          recommendedNextPr: pdGate.recommendedNextPr,
-          isBlocked: pdGate.status === "blocked",
-          isLocalOnly: pdGate.status === "local_only",
-        };
-        // If distribution is blocked (false claims, forbidden files), elevate to full readiness
-        if (fullReadinessSignals && pdGate.status === "blocked") {
-          fullReadinessSignals.installDistributionDominates = true;
-        }
-      }
-    }
-  } catch {}
-
-  // Consume adapter technical readiness signals (PR #162)
-  let adapterReadinessSignals = null;
-  try {
-    const adapterGatePath = path.join(cwd, ".claude/cco/orchestration/adapter-readiness/latest-technical-gate.json");
-    if (fs.existsSync(adapterGatePath)) {
-      const adapterGate = JSON.parse(fs.readFileSync(adapterGatePath, "utf8"));
-      if (adapterGate && adapterGate.status) {
-        adapterReadinessSignals = {
-          status: adapterGate.status,
-          score: adapterGate.score,
-          verdict: adapterGate.verdict,
-          blockerCount: adapterGate.blockerCount || 0,
-          warningCount: adapterGate.warningCount || 0,
-          browserRequired: false,
-          noBrowserLaunch: true,
-          isReady: adapterGate.verdict === "adapter_ready",
-          isBlocked: adapterGate.status === "blocked",
-          safeNextAction: adapterGate.safeNextAction || null,
-        };
-        // If adapter readiness is blocked, elevate to full readiness
-        if (fullReadinessSignals && adapterGate.status === "blocked") {
-          fullReadinessSignals.pluginAdapterDominates = true;
-        }
-        // If adapter readiness is ready, clear plugin/adapter friction and mark verified
-        if (fullReadinessSignals && adapterGate.verdict === "adapter_ready") {
-          fullReadinessSignals.pluginAdapterDominates = false;
-          fullReadinessSignals.adapterReadinessVerified = true;
-        }
-      }
-    }
-  } catch {}
-
-  const nextPrRecommendation = recommendNextPrWithFullReadiness(
-    ledger, personaFindings, frictionClusters, intelligenceSignals, fullReadinessSignals
-  );
-
-  const warnCount = personaFindings.filter((p) => p.status === "warn").length;
-  const failCount = personaFindings.filter((p) => p.status === "fail").length;
-  const topFriction = frictionClusters[0]?.type || null;
-
-  const reportStatus =
-    failCount > 0 ? "fail" : warnCount > 2 ? "warn" : "pass";
-
-  const report = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    createdAt: new Date().toISOString(),
-    status: reportStatus,
-    ledger,
-    personaFindings,
-    frictionClusters,
-    cogsRollup,
-    nextPrRecommendation,
-    intelligenceSignals,
-    fullReadinessSignals,
-    activationDistributionSignals,
-    publicDistributionSignals,
-    adapterReadinessSignals,
-    surface: {
-      status: reportStatus,
-      latestReportPath: LATEST_REPORT_REL,
-      personaWarnCount: warnCount,
-      topFriction,
-      recommendedNextPr: nextPrRecommendation.recommendedNextPr,
-      confidence: nextPrRecommendation.confidence,
-    },
-    redacted: true,
-  };
-
-  return report;
-}
-
-function writeCompanyLoopReport(cwd, report) {
-  const dir = path.join(cwd, LOOP_DIR_REL);
-  fs.mkdirSync(dir, { recursive: true });
-  const filePath = path.join(cwd, LATEST_REPORT_REL);
-  fs.writeFileSync(filePath, JSON.stringify(report, null, 2), "utf8");
-  return filePath;
-}
-
-function buildCompanyLoopSurface(cwd) {
-  const reportPath = path.join(cwd, LATEST_REPORT_REL);
-  if (!fs.existsSync(reportPath)) {
-    return {
-      status: "not_available",
-      latestReportPath: LATEST_REPORT_REL,
-      personaWarnCount: 0,
-      topFriction: null,
-      recommendedNextPr: null,
-      confidence: "low",
-    };
-  }
-  const data = safeReadJson(reportPath);
-  if (!data) return { status: "warn", latestReportPath: LATEST_REPORT_REL };
-  return data.surface || {
-    status: data.status,
-    latestReportPath: LATEST_REPORT_REL,
-    personaWarnCount: (data.personaFindings || []).filter((p) => p.status === "warn").length,
-    topFriction: (data.frictionClusters || [])[0]?.type || null,
-    recommendedNextPr: data.nextPrRecommendation?.recommendedNextPr || null,
-    confidence: data.nextPrRecommendation?.confidence || "low",
-  };
-}
-
-function formatCompanyLoopText(report, options = {}) {
-  const debug = options.debug === true;
-  const lines = [];
-
-  lines.push(`Avorelo Company Loop: ${report.status}`);
-  lines.push(`Created: ${report.createdAt}`);
-  lines.push("");
-
-  const { nextPrRecommendation, frictionClusters, cogsRollup } = report;
-
-  if (nextPrRecommendation) {
-    lines.push(`Recommended Next PR:`);
-    lines.push(`  ${nextPrRecommendation.recommendedNextPr}`);
-    lines.push(`  Why: ${nextPrRecommendation.whyNow}`);
-    lines.push(`  Confidence: ${nextPrRecommendation.confidence}`);
-    lines.push("");
-  }
-
-  if (frictionClusters?.length > 0) {
-    lines.push("Top Friction Clusters:");
-    for (const cluster of frictionClusters.slice(0, 5)) {
-      lines.push(
-        `  - ${cluster.type} (${cluster.severity}, count: ${cluster.count}): ${cluster.recommendedFix}`
-      );
-    }
-    lines.push("");
-  } else {
-    lines.push("Friction Clusters: none detected");
-    lines.push("");
-  }
-
-  if (cogsRollup) {
-    lines.push("COGS / Quality Rollup:");
-    lines.push(`  Local stages used (estimate): ${cogsRollup.estimatedLocalStagesUsed}`);
-    lines.push(`  Context tokens saved (estimate): ${cogsRollup.estimatedContextTokensSaved}`);
-    lines.push(`  Estimate method: ${cogsRollup.estimateMethod}`);
-    lines.push(`  Quality checks verified: ${cogsRollup.qualityChecksVerified}`);
-    lines.push("");
-  }
-
-  if (debug) {
-    lines.push("--- Debug: Persona Findings ---");
-    for (const pf of report.personaFindings || []) {
-      const label = PERSONA_LABELS[pf.persona] || pf.persona;
-      lines.push(`[${pf.status.toUpperCase()}] ${label}:`);
-      lines.push(`  ${pf.finding}`);
-      if (pf.evidence) lines.push(`  Evidence: ${pf.evidence}`);
-      if (pf.recommendedFix) lines.push(`  Fix: ${pf.recommendedFix}`);
-      if (pf.reasonCodes?.length > 0) lines.push(`  Codes: ${pf.reasonCodes.join(", ")}`);
-    }
-    lines.push("");
-
-    lines.push("--- Debug: Not Recommended Yet ---");
-    for (const item of nextPrRecommendation?.notRecommendedYet || []) {
-      lines.push(`  - ${item}`);
-    }
-    lines.push("");
-
-    lines.push("--- Debug: COGS Caveats ---");
-    for (const caveat of cogsRollup?.caveats || []) {
-      lines.push(`  ${caveat}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  PERSONAS,
-  PERSONA_LABELS,
-  FRICTION_CLUSTER_TYPES,
-  ROADMAP_CANDIDATES,
-  LATEST_REPORT_REL,
-  runInternalPersonaReview,
-  clusterFriction,
-  buildCostCogsQualityRollup,
-  recommendNextPr,
-  recommendNextPrWithIntelligence,
-  recommendNextPrWithFullReadiness,
-  buildCompanyLoop,
-  writeCompanyLoopReport,
-  buildCompanyLoopSurface,
-  formatCompanyLoopText,
-};