avorelo 0.1.0 → 0.3.0

package/scripts/lib/feedback-intelligence.js

@@ -1,537 +0,0 @@
-"use strict";
-
-// ── Feedback Intelligence ─────────────────────────────────────────────────────
-//
-// Contract: avorelo.feedbackIntelligence.v1
-//
-// Clusters local feedback entries into actionable friction types.
-// Deterministic, keyword/reason-code based — no LLM calls, no network.
-// No raw user text exposed if it may contain sensitive data.
-
-const fs = require("fs");
-const path = require("path");
-const { nowIso } = require("./fsx");
-const { appendProductLearningEvent } = require("./product-learning-events");
-const { readImportedFeedbackEvidence } = require("./prelaunch-evidence-store");
-
-const CONTRACT = "avorelo.feedbackIntelligence.v1";
-const SCHEMA_VERSION = 1;
-const INTELLIGENCE_DIR_REL = ".claude/cco/orchestration/prelaunch-intelligence";
-const ARTIFACT_REL = `${INTELLIGENCE_DIR_REL}/latest-feedback-intelligence.json`;
-
-const FRICTION_TYPES = Object.freeze([
-  "install_confusion",
-  "ai_prompt_unclear",
-  "hook_approval_unclear",
-  "mcp_governance_warn",
-  "token_context_unknown",
-  "proof_missing",
-  "support_bundle_missing",
-  "command_noise",
-  "recovery_needed",
-  "first_value_unclear",
-  "verification_missing",
-  "missing_evidence",
-  "exact_savings_unavailable",
-  "browser_proof_missing",
-  "plugin_distribution_unclear",
-  "unknown",
-]);
-
-const FRICTION_KEYWORDS = {
-  install_confusion: ["install", "setup", "first_run", "first run", "install-ai", "onboard"],
-  ai_prompt_unclear: ["ai_prompt", "ai prompt", "prompt unclear", "ai install", "prompt_unclear"],
-  hook_approval_unclear: ["hook", "hook_apply", "approval", "lifecycle"],
-  mcp_governance_warn: ["mcp", "tool governance", "mcp_governance", "mcp_warn", "mcp warn"],
-  token_context_unknown: ["token", "context", "cost", "token_context", "token context"],
-  proof_missing: ["proof", "evidence", "proof_missing", "receipt missing"],
-  support_bundle_missing: ["support_bundle", "support bundle", "bundle missing"],
-  command_noise: ["noise", "noisy", "verbose", "output_too_noisy", "too many"],
-  recovery_needed: ["recovery", "repair", "rollback", "failure", "broken"],
-  first_value_unclear: ["first_value", "first value", "value_unclear", "value unclear"],
-  verification_missing: ["verification", "verify", "gate", "reality_gate"],
-  missing_evidence: ["missing_evidence", "missing evidence", "no receipt", "ledger_incomplete"],
-  exact_savings_unavailable: ["savings", "exact savings", "cost savings", "dollar"],
-  browser_proof_missing: ["browser_proof", "browser proof", "visual proof", "screenshot"],
-  plugin_distribution_unclear: ["plugin", "marketplace", "distribution", "adapter"],
-};
-
-// Legacy friction type mapping from alpha-feedback VALID_FRICTION_TYPES
-const LEGACY_FRICTION_MAP = {
-  first_run_unclear: "install_confusion",
-  hook_apply_friction: "hook_approval_unclear",
-  output_too_noisy: "command_noise",
-  output_too_sparse: "verification_missing",
-  command_not_found: "install_confusion",
-  proof_missing: "proof_missing",
-  value_unclear: "first_value_unclear",
-  safe_run_unclear: "first_value_unclear",
-  ledger_incomplete: "missing_evidence",
-  doctor_confusing: "install_confusion",
-  support_bundle_missing: "support_bundle_missing",
-  feedback_path_missing: "missing_evidence",
-  other: "unknown",
-};
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function classifyFriction(entryOrSignal, options = {}) {
-  const signal = entryOrSignal || {};
-  const frictionType = signal.frictionType || signal.type || "";
-  const summary = (signal.summary || signal.finding || "").toLowerCase();
-
-  // Direct friction type match
-  if (FRICTION_TYPES.includes(frictionType)) {
-    return frictionType;
-  }
-
-  // Legacy mapping
-  if (LEGACY_FRICTION_MAP[frictionType]) {
-    return LEGACY_FRICTION_MAP[frictionType];
-  }
-
-  // Keyword match on summary
-  for (const [type, keywords] of Object.entries(FRICTION_KEYWORDS)) {
-    for (const kw of keywords) {
-      if (summary.includes(kw.toLowerCase())) {
-        return type;
-      }
-    }
-  }
-
-  return "unknown";
-}
-
-function collectFeedbackEntries(cwd, options = {}) {
-  const { listFeedback } = require("./alpha-feedback");
-  let manualEntries = [];
-  try {
-    const result = listFeedback(cwd, { limit: 200 });
-    manualEntries = result.items || [];
-  } catch {}
-
-  const importedEntries = readImportedFeedbackEvidence(cwd).map((entry) => ({
-    contract: entry.contract,
-    schemaVersion: entry.schemaVersion,
-    id: `import-${entry.importedAt || "unknown"}`,
-    source: entry.sourceType || "manual_import",
-    persona: entry.persona || "unknown",
-    frictionType: entry.theme || entry.issueCategory || "unknown",
-    severity: entry.severity || "medium",
-    summary: entry.quoteSummary || "",
-    desiredBehavior: "",
-    evidencePath: "[redacted-path]",
-    createdAt: entry.date || entry.importedAt || nowIso(),
-    redacted: true,
-    imported: true,
-    simulated: entry.simulated === true,
-    segment: entry.segment || "unknown",
-    theme: entry.theme || "unknown",
-    issueCategory: entry.issueCategory || "unknown",
-    activationStage: entry.activationStage || "unknown",
-    trustConcern: entry.trustConcern === true,
-    pricingConcern: entry.pricingConcern === true,
-  }));
-
-  let designPartnerEntries = [];
-  try {
-    const { readAllDesignPartnerSessions } = require("./design-partner-feedback");
-    const sessions = readAllDesignPartnerSessions(cwd);
-    designPartnerEntries = sessions.map((s) => ({
-      contract: s.contract,
-      schemaVersion: s.schemaVersion,
-      id: s.sessionId,
-      source: "design_partner",
-      persona: "unknown",
-      frictionType: s.frictionType || "unknown",
-      severity: s.severity || "medium",
-      summary: s.summary || "",
-      desiredBehavior: s.desiredBehavior || "",
-      createdAt: s.createdAt,
-      redacted: true,
-      imported: false,
-      simulated: s.simulated === true,
-      segment: "design_partner",
-      theme: s.theme || "unknown",
-      issueCategory: s.issueCategory || "unknown",
-      activationStage: s.activationStage || "unknown",
-      trustConcern: false,
-      pricingConcern: false,
-    }));
-  } catch {}
-
-  return manualEntries.concat(importedEntries).concat(designPartnerEntries);
-}
-
-function buildFrictionClusters(cwd, options = {}) {
-  const entries = collectFeedbackEntries(cwd, options);
-
-  if (entries.length === 0) {
-    return {
-      status: "insufficient_data",
-      clusters: [],
-      totalEntries: 0,
-      message: "No feedback entries found. Add dogfood feedback to build friction clusters.",
-    };
-  }
-
-  const clusterMap = {};
-
-  for (const entry of entries) {
-    const type = classifyFriction(entry, options);
-    if (!clusterMap[type]) {
-      clusterMap[type] = {
-        frictionType: type,
-        count: 0,
-        severity: "low",
-        evidenceRefs: [],
-        evidenceRefCount: 0,
-        representativeSummaries: [],
-        recommendedAction: null,
-        mappedNextPr: null,
-        redacted: true,
-      };
-    }
-    const cluster = clusterMap[type];
-    cluster.count += 1;
-
-    // Track max severity
-    const sevOrder = { low: 0, medium: 1, high: 2, blocker: 3 };
-    if ((sevOrder[entry.severity] || 0) > (sevOrder[cluster.severity] || 0)) {
-      cluster.severity = entry.severity;
-    }
-
-    // Add evidence ref (path, not raw content)
-    if (entry.evidencePath) {
-      cluster.evidenceRefCount += 1;
-      if (cluster.evidenceRefs.length < 3) {
-        cluster.evidenceRefs.push("[redacted-path]");
-      }
-    }
-
-    // Bounded representative summaries (max 3, max 120 chars each, redacted)
-    if (cluster.representativeSummaries.length < 3 && entry.summary) {
-      const truncated = String(entry.summary).slice(0, 120).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "");
-      cluster.representativeSummaries.push(truncated);
-    }
-  }
-
-  // Assign recommended actions and PR mappings
-  for (const cluster of Object.values(clusterMap)) {
-    cluster.recommendedAction = getRecommendedAction(cluster.frictionType);
-    cluster.mappedNextPr = getMappedNextPr(cluster.frictionType);
-  }
-
-  const clusters = Object.values(clusterMap).sort((a, b) => b.count - a.count);
-
-  return {
-    status: "ready",
-    clusters,
-    totalEntries: entries.length,
-    message: null,
-  };
-}
-
-function getRecommendedAction(frictionType) {
-  const actions = {
-    install_confusion: "Improve install-ai prompt clarity and first-run docs.",
-    ai_prompt_unclear: "Review AI install prompt text for ambiguity.",
-    hook_approval_unclear: "Add approval boundary clarification to hook apply docs.",
-    mcp_governance_warn: "Run avorelo mcp doctor and review policy warnings.",
-    token_context_unknown: "Run avorelo token-efficiency --json and add caveat clarity.",
-    proof_missing: "Run avorelo proof after task completion.",
-    support_bundle_missing: "Run avorelo support-bundle --json.",
-    command_noise: "Audit default CLI output for verbosity.",
-    recovery_needed: "Run avorelo doctor --json and review failure-recovery plan.",
-    first_value_unclear: "Run avorelo first-value-check and improve first-value docs.",
-    verification_missing: "Run avorelo outcome --gate --json.",
-    missing_evidence: "Run full Avorelo sequence to populate ledger receipts.",
-    exact_savings_unavailable: "Token cost evidence is estimated. No exact savings claim will be made.",
-    browser_proof_missing: "Browser Proof deferred until visual friction is dominant.",
-    plugin_distribution_unclear: "Plugin/adapter readiness deferred until distribution friction is dominant.",
-    unknown: "Review feedback entry manually and re-classify.",
-  };
-  return actions[frictionType] || "Review and address this friction type.";
-}
-
-function getMappedNextPr(frictionType) {
-  const map = {
-    install_confusion: "Install / activation repair",
-    ai_prompt_unclear: "Install / activation repair",
-    hook_approval_unclear: "Install / activation repair",
-    mcp_governance_warn: "MCP governance repair",
-    token_context_unknown: "Token / cost evidence repair",
-    proof_missing: "Full Readiness / Release Candidate Gate",
-    support_bundle_missing: "Support bundle repair",
-    command_noise: "Full Readiness / Release Candidate Gate",
-    recovery_needed: "Full Readiness / Release Candidate Gate",
-    first_value_unclear: "Install / activation repair",
-    verification_missing: "Full Readiness / Release Candidate Gate",
-    missing_evidence: "Full Readiness / Release Candidate Gate",
-    exact_savings_unavailable: "Token / cost evidence repair",
-    browser_proof_missing: "Browser Proof / Visual QA Bridge",
-    plugin_distribution_unclear: "Plugin / Adapter Technical Readiness",
-    unknown: null,
-  };
-  return map[frictionType] || null;
-}
-
-function scoreFeedbackCoverage(entries, clusters) {
-  const qualifiedEntries = entries.filter((entry) => entry.simulated !== true && entry.summary && entry.summary.trim().length > 0);
-  const realEntries = qualifiedEntries.length;
-  const sourceCount = new Set(qualifiedEntries.map((entry) => entry.source || entry.sourceType || "unknown")).size;
-  const themeCount = new Set(qualifiedEntries.map((entry) => classifyFriction(entry))).size;
-  const severityCoverage = new Set(qualifiedEntries.map((entry) => entry.severity || "medium")).size;
-  const simulatedEntries = entries.filter((entry) => entry.simulated === true).length;
-
-  let score = 0;
-  score += Math.min(realEntries, 6) * 10;
-  score += Math.min(sourceCount, 3) * 8;
-  score += Math.min(themeCount, 4) * 5;
-  score += Math.min(severityCoverage, 3) * 3;
-  if (clusters.some((cluster) => cluster.severity === "blocker")) score -= 10;
-  score = Math.max(0, Math.min(100, score));
-
-  let readinessStatus = "warn";
-  if (realEntries === 0) readinessStatus = simulatedEntries > 0 ? "info" : "warn";
-  else if (realEntries >= 3 && sourceCount >= 1) readinessStatus = "pass";
-
-  let evidenceQuality = "missing";
-  if (realEntries >= 5 && sourceCount >= 2 && themeCount >= 2) evidenceQuality = "strong";
-  else if (realEntries >= 3) evidenceQuality = "moderate";
-  else if (realEntries >= 1) evidenceQuality = "weak";
-
-  return {
-    score,
-    readinessStatus,
-    evidenceQuality,
-    qualifiedEntries,
-    simulatedEntries,
-    sourceCount,
-    themeCount,
-  };
-}
-
-function buildFeedbackIntelligence(cwd, options = {}) {
-  const entries = collectFeedbackEntries(cwd, options);
-  const clusterResult = buildFrictionClusters(cwd, options);
-  const { status, clusters, totalEntries, message } = clusterResult;
-
-  const topFriction = clusters[0] || null;
-  const hasBlockers = clusters.some((c) => c.severity === "blocker");
-  const coverage = scoreFeedbackCoverage(entries, clusters);
-  const topThemes = clusters.slice(0, 5).map((cluster) => ({
-    theme: cluster.frictionType,
-    count: cluster.count,
-    severity: cluster.severity,
-  }));
-  const objections = entries
-    .filter((entry) => entry.pricingConcern === true)
-    .slice(0, 5)
-    .map((entry) => ({
-      theme: classifyFriction(entry),
-      severity: entry.severity || "medium",
-    }));
-  const activationIssues = entries
-    .filter((entry) => (entry.activationStage || "").toLowerCase() !== "unknown")
-    .slice(0, 10)
-    .map((entry) => ({
-      activationStage: entry.activationStage,
-      theme: classifyFriction(entry),
-      severity: entry.severity || "medium",
-    }));
-  const trustConcerns = entries
-    .filter((entry) => entry.trustConcern === true)
-    .slice(0, 10)
-    .map((entry) => ({
-      theme: classifyFriction(entry),
-      severity: entry.severity || "medium",
-    }));
-  const pricingConcerns = entries
-    .filter((entry) => entry.pricingConcern === true)
-    .slice(0, 10)
-    .map((entry) => ({
-      theme: classifyFriction(entry),
-      severity: entry.severity || "medium",
-    }));
-  const sources = entries.reduce((acc, entry) => {
-    const source = entry.source || entry.sourceType || "unknown";
-    acc[source] = (acc[source] || 0) + 1;
-    return acc;
-  }, {});
-  const hasStructuredEvidence = entries.some((entry) => (
-    entry.imported === true
-    || entry.source === "manual_import"
-    || entry.source === "design_partner"
-    || entry.sourceType === "design_partner"
-    || (entry.activationStage && entry.activationStage !== "unknown")
-    || entry.trustConcern === true
-    || entry.pricingConcern === true
-    || (entry.segment && entry.segment !== "unknown")
-  ));
-  const missingEvidence = [];
-  if (coverage.qualifiedEntries.length === 0) {
-    missingEvidence.push("No redacted real feedback evidence imported or captured locally.");
-  }
-  if (!hasStructuredEvidence) {
-    missingEvidence.push("No structured design-partner feedback evidence is present.");
-  }
-  if (!entries.some((entry) => entry.activationStage && entry.activationStage !== "unknown")) {
-    missingEvidence.push("No activation-stage-tagged feedback evidence present.");
-  }
-  const safeNextActions = coverage.qualifiedEntries.length === 0
-    ? [
-        "Run: node bin/avorelo feedback intake-pack --json",
-        "Run: node bin/avorelo feedback add --source dogfood --summary \"...\"",
-        "Run: node bin/avorelo feedback import --file <redacted-json-or-jsonl> --json",
-        "Run: node bin/avorelo feedback session --partner <alias> --summary \"...\" --consent not_recorded",
-      ]
-    : [
-        "Run: node bin/avorelo feedback insights --json",
-        "Run: node bin/avorelo feedback summary --json",
-        "Import additional structured feedback if external evidence exists.",
-      ];
-
-  return {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    createdAt: nowIso(),
-    status: coverage.qualifiedEntries.length === 0 ? "insufficient_data" : status,
-    readinessStatus: coverage.readinessStatus,
-    score: coverage.score,
-    feedbackItemsCount: totalEntries,
-    qualifiedFeedbackItemsCount: coverage.qualifiedEntries.length,
-    simulatedFeedbackItemsCount: coverage.simulatedEntries,
-    sources,
-    coverage: {
-      sourceCount: coverage.sourceCount,
-      themeCount: coverage.themeCount,
-      activationStagesTagged: activationIssues.length,
-      trustConcernCount: trustConcerns.length,
-      pricingConcernCount: pricingConcerns.length,
-    },
-    topThemes,
-    objections,
-    activationIssues,
-    trustConcerns,
-    pricingConcerns,
-    evidenceQuality: coverage.evidenceQuality,
-    missingEvidence,
-    safeNextActions,
-    totalFeedbackEntries: totalEntries,
-    clustersFound: clusters.length,
-    topFriction: topFriction ? topFriction.frictionType : null,
-    topFrictionCount: topFriction ? topFriction.count : 0,
-    clusters,
-    hasBlockerSeverity: hasBlockers,
-    message,
-    simulatedDataExcluded: true,
-    sourceArtifacts: {
-      manualFeedbackDir: ".claude/cco/feedback",
-      importedFeedbackEvidence: ".claude/cco/evidence/feedback/feedback.jsonl",
-      intakePackDir: ".claude/cco/evidence/feedback/intake-pack",
-    },
-    noRawFeedbackExposed: true,
-    redacted: true,
-  };
-}
-
-function writeFeedbackIntelligence(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 buildFeedbackIntelligenceSurface(cwd, options = {}) {
-  const absPath = path.join(cwd, ARTIFACT_REL);
-  const existing = safeReadJson(absPath);
-  if (existing) {
-    return {
-      status: existing.status,
-      readinessStatus: existing.readinessStatus,
-      topFriction: existing.topFriction,
-      clustersFound: existing.clustersFound,
-      totalEntries: existing.totalFeedbackEntries,
-      qualifiedFeedbackItemsCount: existing.qualifiedFeedbackItemsCount || 0,
-      artifactPath: ARTIFACT_REL,
-    };
-  }
-  const intel = buildFeedbackIntelligence(cwd, options);
-  writeFeedbackIntelligence(cwd, intel);
-  return {
-    status: intel.status,
-    readinessStatus: intel.readinessStatus,
-    topFriction: intel.topFriction,
-    clustersFound: intel.clustersFound,
-    totalEntries: intel.totalFeedbackEntries,
-    qualifiedFeedbackItemsCount: intel.qualifiedFeedbackItemsCount || 0,
-    artifactPath: ARTIFACT_REL,
-  };
-}
-
-function formatFeedbackIntelligenceText(intelligence, options = {}) {
-  const debug = options.debug === true;
-  const lines = [];
-
-  lines.push(`Feedback intelligence: ${intelligence.status}`);
-  lines.push(`  Readiness: ${intelligence.readinessStatus}`);
-  lines.push(`  Score: ${intelligence.score}`);
-  lines.push(`  Entries: ${intelligence.totalFeedbackEntries}`);
-  lines.push(`  Qualified: ${intelligence.qualifiedFeedbackItemsCount}`);
-  lines.push(`  Clusters: ${intelligence.clustersFound}`);
-
-  if (intelligence.topFriction) {
-    lines.push(`  Top friction: ${intelligence.topFriction} (${intelligence.topFrictionCount})`);
-  } else {
-    lines.push(`  Top friction: none`);
-  }
-
-  if (intelligence.message) {
-    lines.push(`  Note: ${intelligence.message}`);
-  }
-
-  if (debug && intelligence.clusters && intelligence.clusters.length > 0) {
-    lines.push("");
-    lines.push("Friction clusters:");
-    for (const cluster of intelligence.clusters) {
-      lines.push(`  - ${cluster.frictionType} (${cluster.severity}, x${cluster.count})`);
-      lines.push(`    Action: ${cluster.recommendedAction}`);
-      if (cluster.mappedNextPr) {
-        lines.push(`    Next PR: ${cluster.mappedNextPr}`);
-      }
-    }
-  }
-
-  if (debug && intelligence.safeNextActions && intelligence.safeNextActions.length > 0) {
-    lines.push("");
-    lines.push("Next:");
-    intelligence.safeNextActions.slice(0, 3).forEach((action) => lines.push(`  - ${action}`));
-  }
-
-  return lines.join("\n");
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  ARTIFACT_REL,
-  FRICTION_TYPES,
-  FRICTION_KEYWORDS,
-  LEGACY_FRICTION_MAP,
-  classifyFriction,
-  collectFeedbackEntries,
-  buildFrictionClusters,
-  buildFeedbackIntelligence,
-  writeFeedbackIntelligence,
-  buildFeedbackIntelligenceSurface,
-  formatFeedbackIntelligenceText,
-};