avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/feedback-intelligence.js

@@ -0,0 +1,537 @@
+"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 open after task completion to check receipts.",
+    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,
+};