avorelo 0.1.0 → 0.3.0

package/scripts/lib/operating-value.js

@@ -1,1648 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-
-const {
-  buildValueProofs,
-  confidenceLabel,
-} = require("./value-proof-calibration");
-
-const {
-  getLocalPricingSource,
-  getLocalPricingEntry,
-} = require("./local-pricing");
-
-const {
-  buildTokenEvidence,
-  writeTokenEvidence,
-} = require("./token-evidence");
-
-const {
-  buildCostEvidenceV1,
-} = require("./cost-evidence");
-
-// ── Constants ─────────────────────────────────────────────────────────────────
-
-const OPERATING_VALUE_CONTRACT = "avorelo.operatingValue.v1";
-const OPERATING_VALUE_SCHEMA_VERSION = 1;
-const OPERATING_VALUE_DIR_REL = ".claude/cco/orchestration/operating-value";
-const OPERATING_VALUE_LATEST_REL = `${OPERATING_VALUE_DIR_REL}/latest-value.json`;
-const OPERATING_VALUE_SUMMARY_REL = `${OPERATING_VALUE_DIR_REL}/latest-summary.md`;
-const OPERATING_VALUE_HISTORY_DIR_REL = `${OPERATING_VALUE_DIR_REL}/history`;
-const OPERATING_VALUE_EVENTS_REL = ".claude/cco/events/operating-value.jsonl";
-const OPERATING_VALUE_DASHBOARD_PREVIEW_REL = `${OPERATING_VALUE_DIR_REL}/dashboard-preview.md`;
-
-// Receipt source paths
-const WORK_CONTROL_REL = ".claude/cco/orchestration/work-control/latest-receipt.json";
-const SESSION_CONTEXT_REL = ".claude/cco/orchestration/session-context/latest-context.json";
-const BRAIN_PACK_REL = ".claude/cco/context/brain-pack/latest.json";
-const WORKSPACE_REGISTRY_REL = ".claude/cco/orchestration/workspace-registry/latest-registry.json";
-const INSTALL_INTAKE_REL = ".claude/cco/security/install-intake/latest-receipt.json";
-const SAFE_PATH_REL = ".claude/cco/security/safe-path/latest-receipt.json";
-const PROOF_REL = ".claude/cco/orchestration/current-proof.json";
-
-// Staleness thresholds (ms)
-const STALE_SHORT_MS = 2 * 60 * 60 * 1000;  // 2 hours
-const STALE_LONG_MS = 24 * 60 * 60 * 1000;  // 24 hours
-
-// Token estimation constants
-const AVG_CHARS_PER_TOKEN = 4;
-const AVG_ASSET_SUMMARY_CHARS = 150;
-const RAW_TOKEN_CAP = 50000;
-const MINUTES_PER_MANUAL_STEP_LOW = 1;
-const MINUTES_PER_MANUAL_STEP_HIGH = 3;
-const MINUTES_CAP = 30;
-
-// ── File helpers ──────────────────────────────────────────────────────────────
-
-function ensureDir(p) {
-  fs.mkdirSync(p, { recursive: true });
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function safeReadJson(filePath) {
-  try {
-    if (!fs.existsSync(filePath)) return null;
-    const raw = fs.readFileSync(filePath, "utf8").replace(/^/, "");
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-function fileAgeMs(filePath) {
-  try {
-    const stat = fs.statSync(filePath);
-    return Date.now() - stat.mtimeMs;
-  } catch {
-    return Infinity;
-  }
-}
-
-function fileCharLen(filePath) {
-  try {
-    return fs.statSync(filePath).size;
-  } catch {
-    return 0;
-  }
-}
-
-function shortId() {
-  return crypto.randomBytes(4).toString("hex");
-}
-
-// ── Receipt readers ───────────────────────────────────────────────────────────
-
-function readReceipts(cwd) {
-  const read = (rel) => {
-    const abs = path.join(cwd, rel);
-    const data = safeReadJson(abs);
-    const ageMs = fileAgeMs(abs);
-    const charLen = fileCharLen(abs);
-    return { data, ageMs, present: data !== null, charLen, path: rel };
-  };
-  return {
-    workControl: read(WORK_CONTROL_REL),
-    sessionContext: read(SESSION_CONTEXT_REL),
-    brainPack: read(BRAIN_PACK_REL),
-    workspaceRegistry: read(WORKSPACE_REGISTRY_REL),
-    installIntake: read(INSTALL_INTAKE_REL),
-    safePath: read(SAFE_PATH_REL),
-    proof: read(PROOF_REL),
-  };
-}
-
-// ── Staleness checks ──────────────────────────────────────────────────────────
-
-function isStale(ageMs, thresholdMs) {
-  return ageMs > thresholdMs;
-}
-
-function ageLabel(ageMs) {
-  if (ageMs === Infinity) return "missing";
-  const hours = Math.round(ageMs / 1000 / 60 / 60);
-  if (hours < 1) return "< 1h ago";
-  if (hours < 24) return `${hours}h ago`;
-  return `${Math.round(hours / 24)}d ago`;
-}
-
-// ── Token estimation ──────────────────────────────────────────────────────────
-
-function estimateCharsToTokens(chars) {
-  return Math.round(chars / AVG_CHARS_PER_TOKEN);
-}
-
-function estimateRawContextTokens(receipts) {
-  let totalChars = 0;
-  const sources = [];
-
-  // Registry: totalAssets × avg chars
-  const reg = receipts.workspaceRegistry.data;
-  if (reg && reg.summary && reg.summary.totalAssets) {
-    const regChars = reg.summary.totalAssets * AVG_ASSET_SUMMARY_CHARS;
-    totalChars += regChars;
-    sources.push(`registry (${reg.summary.totalAssets} assets × ~${AVG_ASSET_SUMMARY_CHARS} chars)`);
-  }
-
-  // Work-control receipt file size
-  if (receipts.workControl.present && receipts.workControl.charLen > 0) {
-    totalChars += receipts.workControl.charLen;
-    sources.push(`work-control receipt (~${receipts.workControl.charLen} chars)`);
-  }
-
-  // Brain-pack file size
-  if (receipts.brainPack.present && receipts.brainPack.charLen > 0) {
-    totalChars += receipts.brainPack.charLen;
-    sources.push(`brain-pack (~${receipts.brainPack.charLen} chars)`);
-  }
-
-  // Session context source sections if available
-  const sc = receipts.sessionContext.data;
-  if (sc && sc.tokenDiscipline && sc.tokenDiscipline.estimatedTokens) {
-    // This is already the compact form — we're building raw estimate, so DON'T add compact here
-  }
-
-  if (totalChars === 0) return { tokens: null, sources: [], confidence: "unavailable" };
-
-  const rawTokens = Math.min(estimateCharsToTokens(totalChars), RAW_TOKEN_CAP);
-  return { tokens: rawTokens, sources, confidence: "estimated" };
-}
-
-function estimateCompactHandoffTokens(receipts) {
-  const sc = receipts.sessionContext.data;
-  if (sc && sc.tokenDiscipline && sc.tokenDiscipline.estimatedTokens) {
-    return { tokens: sc.tokenDiscipline.estimatedTokens, basis: "session-context.estimatedTokens", confidence: "measured" };
-  }
-  // Fallback: markdown handoff file size
-  const abs = path.join(
-    path.dirname(
-      path.join(process.cwd(), receipts.sessionContext.path || SESSION_CONTEXT_REL)
-    ),
-    "latest-context.md"
-  );
-  const mdPath = abs.replace(/latest-context\.json$/, "latest-context.md");
-  const mdCharLen = fileCharLen(mdPath);
-  if (mdCharLen > 0) {
-    return { tokens: estimateCharsToTokens(mdCharLen), basis: "session-context.md file size", confidence: "estimated" };
-  }
-  return { tokens: null, basis: "unavailable", confidence: "unavailable" };
-}
-
-// ── Manual steps count ────────────────────────────────────────────────────────
-
-function countManualStepsAvoided(receipts, capabilityRec) {
-  let count = 0;
-  const details = [];
-
-  if (capabilityRec && capabilityRec.recommendedPack) {
-    count++;
-    details.push("capability auto-recommended");
-  }
-
-  const wc = receipts.workControl.data;
-  if (wc && wc.workControl && wc.workControl.nextSafestAction) {
-    count++;
-    details.push("next command generated");
-  }
-
-  const sc = receipts.sessionContext.data;
-  if (sc && sc.sessionStart && (sc.sessionStart.relevantFiles || []).length > 0) {
-    count++;
-    details.push("relevant files selected");
-  }
-
-  if (receipts.workspaceRegistry.present) {
-    count++;
-    details.push("registry already available");
-  }
-
-  if (receipts.workControl.present) {
-    count++;
-    details.push("work-control available");
-  }
-
-  if (receipts.sessionContext.present) {
-    count++;
-    details.push("session-context available");
-  }
-
-  if (receipts.brainPack.present) {
-    count++;
-    details.push("brain-pack available");
-  }
-
-  if (receipts.proof.present) {
-    count++;
-    details.push("proof available");
-  }
-
-  return { count, details };
-}
-
-// ── Value Card builders ───────────────────────────────────────────────────────
-
-function buildTimeSavedCard(receipts, capabilityRec) {
-  const steps = countManualStepsAvoided(receipts, capabilityRec);
-  const sc = receipts.sessionContext.data;
-  const reg = receipts.workspaceRegistry.data;
-
-  const rediscoveryAvoided = sc && sc.tokenDiscipline && sc.tokenDiscipline.avoidedBroadRediscovery === true;
-  const relevantFiles = sc && sc.sessionStart ? (sc.sessionStart.relevantFiles || []).length : 0;
-  const totalAssets = reg && reg.summary ? reg.summary.totalAssets : null;
-
-  const lowEstimate = steps.count * MINUTES_PER_MANUAL_STEP_LOW;
-  const highEstimate = Math.min(steps.count * MINUTES_PER_MANUAL_STEP_HIGH, MINUTES_CAP);
-
-  const hasValue = steps.count > 0;
-  const timeSavedMinuteRange = hasValue ? `${lowEstimate}–${highEstimate}` : "0";
-
-  return {
-    id: "timeSaved",
-    label: "Time Saved",
-    status: hasValue ? "available" : "partial",
-    headline: hasValue
-      ? `Estimated ${timeSavedMinuteRange} minutes saved`
-      : "Limited time savings measured",
-    plainEnglishValue: hasValue
-      ? `Avorelo prepared ${steps.count} manual steps automatically (${steps.details.join(", ")}).${rediscoveryAvoided ? " Broad repo rediscovery avoided." : ""}`
-      : "Some Avorelo surfaces were not available to measure time savings.",
-    primaryMetric: `${steps.count} manual steps avoided`,
-    secondaryMetric: relevantFiles && totalAssets
-      ? `${relevantFiles} relevant files pre-selected from ${totalAssets} total assets`
-      : rediscoveryAvoided ? "Broad repo scan avoided" : null,
-    evidence: ["work-control", "session-context", "workspace-registry", "capability-recommender"].filter(
-      (s) => (s === "work-control" && receipts.workControl.present) ||
-             (s === "session-context" && receipts.sessionContext.present) ||
-             (s === "workspace-registry" && receipts.workspaceRegistry.present) ||
-             (s === "capability-recommender" && capabilityRec && capabilityRec.recommendedPack)
-    ),
-    confidence: steps.count >= 5 ? "medium" : "low",
-    estimateBasis: "heuristic: manual steps avoided × 1–3 minutes",
-    nextAction: sc && sc.sessionStart && sc.sessionStart.nextSafestAction
-      ? sc.sessionStart.nextSafestAction
-      : "Run `avorelo session-context --handoff --target claude` to prepare compact handoff.",
-    userFacingSentence: hasValue
-      ? `Avorelo saved an estimated ${timeSavedMinuteRange} minutes by handling ${steps.count} steps automatically.`
-      : "Run the core Avorelo surfaces to measure time savings.",
-  };
-}
-
-function buildCostOrTokensSavedCard(receipts, costEvidence) {
-  const rawEst = estimateRawContextTokens(receipts);
-  const compactEst = estimateCompactHandoffTokens(receipts);
-  const hasCostEstimate = costEvidence && costEvidence.costAvoidedEstimate !== null && costEvidence.dashboardAllowed;
-
-  const rawTokens = rawEst.tokens;
-  const compactTokens = compactEst.tokens;
-
-  let tokenReduction = null;
-  let compressionRatio = null;
-  let hasValue = false;
-
-  if (rawTokens !== null && compactTokens !== null && rawTokens > 0) {
-    tokenReduction = Math.max(0, rawTokens - compactTokens);
-    compressionRatio = Math.round((compactTokens / rawTokens) * 100) / 100;
-    hasValue = tokenReduction > 0;
-  }
-
-  const reg = receipts.workspaceRegistry.data;
-  const totalAssets = reg && reg.summary ? reg.summary.totalAssets : null;
-  const sc = receipts.sessionContext.data;
-  const relevantFiles = sc && sc.sessionStart ? (sc.sessionStart.relevantFiles || []).length : 0;
-
-  return {
-    id: "costOrTokensSaved",
-    label: "Context / Tokens Saved",
-    status: hasValue ? "available" : compactTokens !== null ? "partial" : "unavailable",
-    headline: hasValue
-      ? `~${tokenReduction.toLocaleString()} tokens not loaded into context`
-      : compactTokens !== null
-        ? `Compact handoff: ~${compactTokens.toLocaleString()} tokens`
-        : "Token savings not yet measurable",
-    plainEnglishValue: hasValue
-      ? `Avorelo prepared a ~${compactTokens.toLocaleString()}-token compact handoff instead of loading ~${rawTokens.toLocaleString()} candidate context tokens.`
-      : compactTokens !== null
-        ? `Compact handoff prepared (~${compactTokens.toLocaleString()} tokens). Run workspace-registry to enable before/after comparison.`
-        : "Run `avorelo session-context` and `avorelo workspace-registry` to enable context reduction measurement.",
-    primaryMetric: rawTokens && compactTokens
-      ? `~${rawTokens.toLocaleString()} raw candidate tokens → ~${compactTokens.toLocaleString()} compact tokens`
-      : compactTokens
-        ? `Compact handoff: ~${compactTokens.toLocaleString()} tokens`
-        : "unavailable",
-    secondaryMetric: relevantFiles && totalAssets
-      ? `${relevantFiles} of ${totalAssets} assets in compact context`
-      : null,
-    evidence: [
-      rawEst.tokens !== null ? "workspace-registry" : null,
-      compactEst.tokens !== null ? "session-context" : null,
-    ].filter(Boolean),
-    confidence: compactEst.confidence === "measured" && rawEst.confidence === "estimated" ? "medium" : "low",
-    estimateBasis: [
-      rawEst.sources.length ? `raw estimate from: ${rawEst.sources.join("; ")}` : null,
-      `compact from: ${compactEst.basis}`,
-    ].filter(Boolean).join(". "),
-    costAvoidedEstimate: hasCostEstimate ? costEvidence.costAvoidedEstimate : null,
-    costNote: hasCostEstimate
-      ? `Estimated cost impact: ~$${costEvidence.costAvoidedEstimate.toFixed(4)} (${costEvidence.confidence} confidence, local pricing)`
-      : "Cost estimate requires a local token pricing source. Token reduction shown instead.",
-    nextAction: receipts.sessionContext.present
-      ? "Review compact handoff at session-context --handoff --target claude"
-      : "Run `avorelo session-context --handoff --target claude` to generate compact handoff.",
-    userFacingSentence: hasValue
-      ? `Avorelo reduced estimated context from ~${rawTokens.toLocaleString()} to ~${compactTokens.toLocaleString()} tokens (~${tokenReduction.toLocaleString()} tokens avoided).`
-      : "Run core surfaces to measure context/token reduction.",
-  };
-}
-
-function buildSecurityRiskAvoidedCard(receipts) {
-  const intake = receipts.installIntake.data;
-  const safePath = receipts.safePath.data;
-  const reg = receipts.workspaceRegistry.data;
-
-  const highRiskItems = intake && intake.summary ? intake.summary.highRiskItems || 0 : 0;
-  const criticalRiskItems = intake && intake.summary ? intake.summary.criticalRiskItems || 0 : 0;
-  const totalRiskyItems = highRiskItems + criticalRiskItems;
-  const unknownItems = intake && intake.summary ? intake.summary.unknownItems || 0 : 0;
-
-  const highRiskAssets = reg && reg.summary ? reg.summary.highRiskAssets || 0 : 0;
-
-  const safePathDecision = safePath && safePath.safePathDecision ? safePath.safePathDecision : null;
-  const risksBlocked = safePathDecision === "block" ? 1 : 0;
-  const risksRouted = (safePathDecision === "approval_required" || safePathDecision === "recommend_reduced_scope" || safePathDecision === "warn_with_boundary") ? 1 : 0;
-  const risksAvoided = risksBlocked + risksRouted;
-
-  const hasValue = totalRiskyItems > 0 || highRiskAssets > 0 || risksAvoided > 0;
-  const intakePresent = receipts.installIntake.present;
-  const safePathPresent = receipts.safePath.present;
-
-  return {
-    id: "securityRiskAvoided",
-    label: "Security Risk Avoided",
-    status: intakePresent ? "available" : "partial",
-    headline: totalRiskyItems > 0
-      ? `${totalRiskyItems} risky item${totalRiskyItems !== 1 ? "s" : ""} surfaced before execution`
-      : intakePresent
-        ? "No high-risk items detected"
-        : "Security scan not yet run",
-    plainEnglishValue: intakePresent
-      ? `Avorelo scanned ${(intake.summary.totalItems || 0).toLocaleString()} intake items. ${totalRiskyItems} high/critical-risk item${totalRiskyItems !== 1 ? "s" : ""} flagged before execution.${risksBlocked ? ` ${risksBlocked} blocked.` : ""}${risksRouted ? ` ${risksRouted} routed via Safe Path.` : ""}${unknownItems > 0 ? ` ${unknownItems} unknown items need review.` : ""}`
-      : "Run `avorelo intake` to scan for risky packages, scripts, and MCP surfaces.",
-    primaryMetric: intakePresent
-      ? `${totalRiskyItems} high/critical-risk items` + (risksAvoided > 0 ? `, ${risksAvoided} routed/blocked` : "")
-      : "unavailable",
-    secondaryMetric: highRiskAssets > 0
-      ? `${highRiskAssets} high-risk workspace assets flagged`
-      : safePathDecision && safePathDecision !== "allow_as_is"
-        ? `Safe Path decision: ${safePathDecision.replace(/_/g, " ")}`
-        : null,
-    evidence: [
-      intakePresent ? "install-intake" : null,
-      safePathPresent ? "safe-path" : null,
-      reg ? "workspace-registry" : null,
-    ].filter(Boolean),
-    confidence: intakePresent ? "high" : "unavailable",
-    risksBlocked,
-    risksRouted,
-    nextAction: totalRiskyItems > 0
-      ? "Review risky items: run `avorelo intake --json` then use Safe Path for deploy/network scripts."
-      : intakePresent
-        ? "Intake scan clean. No action needed."
-        : "Run `avorelo intake` to scan local intake surfaces.",
-    userFacingSentence: intakePresent
-      ? totalRiskyItems > 0
-        ? `Avorelo surfaced ${totalRiskyItems} risky item${totalRiskyItems !== 1 ? "s" : ""} before execution.${risksBlocked ? ` ${risksBlocked} blocked.` : ""}`
-        : "Avorelo scanned all intake surfaces — no high-risk items detected."
-      : "Run `avorelo intake` to enable security risk measurement.",
-  };
-}
-
-function buildClarityCard(receipts) {
-  const wc = receipts.workControl.data;
-  const sc = receipts.sessionContext.data;
-
-  const nextActionPresent = Boolean(
-    (wc && wc.workControl && wc.workControl.nextSafestAction) ||
-    (sc && sc.sessionStart && sc.sessionStart.nextSafestAction)
-  );
-  const doNotRepeatCount = wc && wc.workControl && Array.isArray(wc.workControl.doNotRepeat)
-    ? wc.workControl.doNotRepeat.length : 0;
-  const relevantCommandsCount = sc && sc.sessionStart && Array.isArray(sc.sessionStart.relevantCommands)
-    ? sc.sessionStart.relevantCommands.length : 0;
-  const targetHandoffPrepared = Boolean(sc && sc.sessionStart && sc.sessionStart.compactPrompt);
-  const proofAvailable = receipts.proof.present;
-
-  const clarityScore = [nextActionPresent, doNotRepeatCount > 0, relevantCommandsCount > 0, targetHandoffPrepared, proofAvailable]
-    .filter(Boolean).length;
-
-  return {
-    id: "clarity",
-    label: "Clarity",
-    status: clarityScore >= 3 ? "available" : clarityScore >= 1 ? "partial" : "unavailable",
-    headline: nextActionPresent ? "Next action prepared" : "Clarity surface incomplete",
-    plainEnglishValue: nextActionPresent
-      ? `The next model session gets clear guidance: ${doNotRepeatCount > 0 ? `${doNotRepeatCount} do-not-repeat items, ` : ""}${relevantCommandsCount > 0 ? `${relevantCommandsCount} relevant commands, ` : ""}${targetHandoffPrepared ? "compact handoff, " : ""}${proofAvailable ? "proof evidence." : "no proof yet."}`
-      : "Run work-control and session-context to build the clarity surface.",
-    primaryMetric: nextActionPresent ? "Next action: available" : "Next action: missing",
-    secondaryMetric: `do-not-repeat: ${doNotRepeatCount}, commands: ${relevantCommandsCount}`,
-    evidence: [
-      wc ? "work-control" : null,
-      sc ? "session-context" : null,
-      proofAvailable ? "proof" : null,
-    ].filter(Boolean),
-    confidence: clarityScore >= 3 ? "medium" : "low",
-    nextActionPresent,
-    doNotRepeatCount,
-    relevantCommandsCount,
-    targetHandoffPrepared,
-    proofAvailable,
-    nextAction: !nextActionPresent
-      ? "Run `avorelo work-control --json` to generate next safest action guidance."
-      : null,
-    userFacingSentence: nextActionPresent
-      ? `Avorelo prepared clear next-step guidance with ${doNotRepeatCount} anti-patterns and ${relevantCommandsCount} relevant commands.`
-      : "Run core surfaces to build clarity for the next model session.",
-  };
-}
-
-function buildSeamlessnessCard(receipts, capabilityRec) {
-  const capabilityAutoRecommended = Boolean(capabilityRec && capabilityRec.recommendedPack);
-  const userDidNotChooseCapability = capabilityAutoRecommended;
-  const sc = receipts.sessionContext.data;
-  const jsonDumpAvoided = sc && sc.tokenDiscipline ? sc.tokenDiscipline.avoidedJsonDump === true : false;
-
-  const autoHandledCount = [
-    receipts.workControl.present,
-    receipts.sessionContext.present,
-    receipts.workspaceRegistry.present,
-    receipts.brainPack.present,
-    capabilityAutoRecommended,
-    jsonDumpAvoided,
-  ].filter(Boolean).length;
-
-  const userActionFindings = [
-    !receipts.installIntake.present,
-    !receipts.proof.present,
-  ].filter(Boolean).length;
-
-  const seamlessnessScore = Math.round((autoHandledCount / 6) * 100);
-
-  return {
-    id: "seamlessness",
-    label: "Seamlessness",
-    status: seamlessnessScore >= 60 ? "available" : "partial",
-    headline: capabilityAutoRecommended ? "Capability selected automatically" : "Some manual steps needed",
-    plainEnglishValue: capabilityAutoRecommended
-      ? `Avorelo automatically selected the right capability pack without requiring the user to choose. ${autoHandledCount} surfaces prepared automatically.`
-      : "The capability recommender did not run. Run `avorelo capabilities` to get an auto-routed recommendation.",
-    primaryMetric: `${autoHandledCount}/6 surfaces auto-handled`,
-    secondaryMetric: userActionFindings > 0 ? `${userActionFindings} surface${userActionFindings !== 1 ? "s" : ""} need user action` : null,
-    evidence: [
-      capabilityAutoRecommended ? "capability-recommender" : null,
-      sc ? "session-context" : null,
-    ].filter(Boolean),
-    confidence: autoHandledCount >= 4 ? "medium" : "low",
-    userDidNotChooseCapability,
-    autoHandledFindings: autoHandledCount,
-    userActionRequiredFindings: userActionFindings,
-    seamlessnessScore,
-    nextAction: !capabilityAutoRecommended
-      ? "Run `avorelo capabilities` to auto-recommend the right pack."
-      : null,
-    userFacingSentence: capabilityAutoRecommended
-      ? `Avorelo handled ${autoHandledCount} surfaces automatically — no manual capability selection needed.`
-      : "Run `avorelo capabilities` to enable seamless capability routing.",
-  };
-}
-
-// ── Readiness score ───────────────────────────────────────────────────────────
-
-function buildOperatingLoopReadiness(receipts, capabilityRec) {
-  const sc = receipts.sessionContext.data;
-  const wc = receipts.workControl.data;
-  const reg = receipts.workspaceRegistry.data;
-  const intake = receipts.installIntake.data;
-  const safePath = receipts.safePath.data;
-
-  const checks = {
-    workControlAvailable: receipts.workControl.present && !isStale(receipts.workControl.ageMs, STALE_SHORT_MS),
-    sessionContextFresh: receipts.sessionContext.present && !isStale(receipts.sessionContext.ageMs, STALE_SHORT_MS),
-    registryFresh: receipts.workspaceRegistry.present && !isStale(receipts.workspaceRegistry.ageMs, STALE_SHORT_MS),
-    brainPackAvailable: receipts.brainPack.present && !isStale(receipts.brainPack.ageMs, STALE_LONG_MS),
-    capabilityRecommendationAvailable: Boolean(capabilityRec && capabilityRec.recommendedPack),
-    nextActionAvailable: Boolean(
-      (wc && wc.workControl && wc.workControl.nextSafestAction) ||
-      (sc && sc.sessionStart && sc.sessionStart.nextSafestAction)
-    ),
-    proofAvailable: receipts.proof.present,
-    activeRisksRouted: (() => {
-      // A block/approval/reduced_scope is a SUCCESSFUL routing outcome
-      const highRiskItems = intake && intake.summary ? intake.summary.highRiskItems || 0 : 0;
-      const criticalRiskItems = intake && intake.summary ? intake.summary.criticalRiskItems || 0 : 0;
-      const safePathDecision = safePath && safePath.safePathDecision ? safePath.safePathDecision : null;
-      const intakeNextAction = intake && intake.nextAction ? intake.nextAction : null;
-      if (highRiskItems === 0 && criticalRiskItems === 0) return true;
-      // Risks exist — check if they are routed
-      return Boolean(
-        safePathDecision && safePathDecision !== "allow_as_is" ||
-        intakeNextAction ||
-        (receipts.safePath.present && receipts.safePath.data)
-      );
-    })(),
-    relevantFilesAvailable: Boolean(sc && sc.sessionStart && (sc.sessionStart.relevantFiles || []).length > 0),
-    targetHandoffPrepared: Boolean(sc && sc.sessionStart && sc.sessionStart.compactPrompt),
-  };
-
-  const score = Object.values(checks).filter(Boolean).length * 10;
-  const band = score >= 85 ? "excellent" : score >= 65 ? "good" : score >= 40 ? "fair" : "needs_attention";
-
-  const missingPieces = Object.entries(checks)
-    .filter(([, v]) => !v)
-    .map(([k]) => k);
-
-  const nextAction = missingPieces.length === 0
-    ? "All operating loop surfaces are ready."
-    : `Missing: ${missingPieces.slice(0, 3).join(", ")}. Run the corresponding Avorelo surface to improve readiness.`;
-
-  const bandLabel = { excellent: "Excellent", good: "Good", fair: "Fair", needs_attention: "Needs Attention" }[band];
-
-  return {
-    score,
-    band,
-    bandLabel,
-    summary: `Operating loop readiness: ${bandLabel} (${score}/100)`,
-    checks,
-    missingPieces,
-    nextAction,
-  };
-}
-
-// ── Opportunity detectors ─────────────────────────────────────────────────────
-
-function buildOpportunityFindings(receipts, capabilityRec, readiness) {
-  const findings = [];
-  const sc = receipts.sessionContext.data;
-  const wc = receipts.workControl.data;
-  const intake = receipts.installIntake.data;
-
-  function addFinding(id, severity, confidence, valueType, plainEnglish, evidence, recommendedAction, handledAuto, needsUser) {
-    findings.push({ id, severity, confidence, valueType, plainEnglish, evidence, recommendedAction, handledAutomatically: handledAuto, needsUserAction: needsUser });
-  }
-
-  if (!receipts.sessionContext.present) {
-    addFinding("missing_session_context", "warning", "high", "time",
-      "Session context not found. The next model session will need to rediscover the repo.",
-      [], "Run `avorelo session-context --handoff --target claude`.", false, true);
-  } else if (isStale(receipts.sessionContext.ageMs, STALE_SHORT_MS)) {
-    addFinding("stale_session_context", "info", "high", "time",
-      `Session context is stale (${ageLabel(receipts.sessionContext.ageMs)}). May not reflect current repo state.`,
-      ["session-context"], "Run `avorelo session-context --handoff --target claude` to refresh.", false, true);
-  }
-
-  if (!receipts.workControl.present) {
-    addFinding("missing_work_control", "warning", "high", "clarity",
-      "Work-control receipt not found. No finalState or nextSafestAction guidance available.",
-      [], "Run `avorelo work-control --json`.", false, true);
-  } else if (isStale(receipts.workControl.ageMs, STALE_SHORT_MS)) {
-    addFinding("stale_work_control", "info", "medium", "clarity",
-      `Work-control receipt is stale (${ageLabel(receipts.workControl.ageMs)}).`,
-      ["work-control"], "Run `avorelo work-control --json` to refresh.", false, true);
-  }
-
-  if (!receipts.workspaceRegistry.present) {
-    addFinding("missing_workspace_registry", "warning", "high", "time",
-      "Workspace registry not found. Asset inventory not available for session context.",
-      [], "Run `avorelo workspace-registry`.", false, true);
-  } else if (isStale(receipts.workspaceRegistry.ageMs, STALE_SHORT_MS)) {
-    addFinding("stale_workspace_registry", "info", "medium", "time",
-      `Workspace registry is stale (${ageLabel(receipts.workspaceRegistry.ageMs)}).`,
-      ["workspace-registry"], "Run `avorelo workspace-registry` to refresh.", false, true);
-  }
-
-  if (receipts.brainPack.present && isStale(receipts.brainPack.ageMs, STALE_LONG_MS)) {
-    addFinding("stale_brain_pack", "info", "low", "time",
-      `Brain Pack is stale (${ageLabel(receipts.brainPack.ageMs)}).`,
-      ["brain-pack"], "Run `avorelo brain-pack` to refresh project context.", false, true);
-  }
-
-  // Rediscovery loop risk: registry present but session context missing
-  if (receipts.workspaceRegistry.present && !receipts.sessionContext.present) {
-    addFinding("rediscovery_loop_risk", "warning", "high", "time",
-      "Workspace registry is available but session context is missing. The next model will rediscover files already indexed.",
-      ["workspace-registry"], "Run `avorelo session-context --handoff --target claude` to use the indexed registry.", false, true);
-  }
-
-  // Huge JSON dump risk
-  const hasHighRawCandidate = (() => {
-    const rawEst = estimateRawContextTokens(receipts);
-    return rawEst.tokens !== null && rawEst.tokens > 8000;
-  })();
-  const scMissingWithHighRaw = !receipts.sessionContext.present && hasHighRawCandidate;
-  const scPresentButNoAvoid = sc && sc.tokenDiscipline && sc.tokenDiscipline.avoidedJsonDump === false;
-  if (scMissingWithHighRaw || scPresentButNoAvoid) {
-    addFinding("huge_json_dump_risk", "warning", "medium", "cost_tokens",
-      scMissingWithHighRaw
-        ? `No compact handoff prepared. Raw candidate context estimated at ~${estimateRawContextTokens(receipts).tokens?.toLocaleString()} tokens.`
-        : "Session context did not avoid a JSON dump.",
-      scPresentButNoAvoid ? ["session-context"] : [], "Run `avorelo session-context --handoff --target claude` to produce a compact handoff.", false, true);
-  }
-
-  // Overwide context
-  const compactTokens = sc && sc.tokenDiscipline ? sc.tokenDiscipline.estimatedTokens : null;
-  if (compactTokens && compactTokens > 8000 && sc.tokenDiscipline.truncationApplied !== true) {
-    addFinding("overwide_context_risk", "info", "medium", "cost_tokens",
-      `Compact handoff is ${compactTokens.toLocaleString()} tokens. Consider narrowing scope.`,
-      ["session-context"], "Run `avorelo session-context --max-chars 4000` to reduce context.", false, true);
-  }
-
-  if (!capabilityRec || !capabilityRec.recommendedPack) {
-    addFinding("missing_capability_recommendation", "info", "medium", "seamlessness",
-      "No capability recommendation found. Capability routing may not be optimal.",
-      [], "Run `avorelo capabilities --json` to get a recommendation.", false, true);
-  } else if (capabilityRec.wrongCapabilityRisk) {
-    addFinding("wrong_capability_risk", "warning", "medium", "seamlessness",
-      "Capability recommender flagged potential wrong-capability risk.",
-      ["capability-recommender"], "Review recommended pack and consider alternatives.", false, true);
-  }
-
-  // Unsafe action needs safe path
-  const highRisk = intake && intake.summary ? (intake.summary.highRiskItems || 0) : 0;
-  const critRisk = intake && intake.summary ? (intake.summary.criticalRiskItems || 0) : 0;
-  if ((highRisk > 0 || critRisk > 0) && !receipts.safePath.present) {
-    addFinding("unsafe_action_needs_safe_path", "warning", "high", "security",
-      `${highRisk + critRisk} high/critical-risk intake item(s) found but no Safe Path receipt generated.`,
-      ["install-intake"], "Run `avorelo guard --action command_run --action deploy_operation` before executing risky scripts.", false, true);
-  }
-
-  if (critRisk > 0) {
-    addFinding("high_risk_intake_needs_review", "error", "high", "security",
-      `${critRisk} critical-risk intake item(s) need review before proceeding.`,
-      ["install-intake"], "Review: run `avorelo intake --json` and inspect criticalRiskItems.", false, true);
-  }
-
-  if (!receipts.proof.present) {
-    addFinding("missing_proof", "info", "medium", "clarity",
-      "No proof receipt found. Verification status unknown.",
-      [], "Run `avorelo proof` after a session to capture what was checked.", true, false);
-  }
-
-  if (!readiness.checks.nextActionAvailable) {
-    addFinding("missing_next_action", "warning", "high", "clarity",
-      "No nextSafestAction available in work-control or session context.",
-      [], "Run `avorelo work-control --json` to generate next-action guidance.", false, true);
-  }
-
-  if (!readiness.checks.targetHandoffPrepared) {
-    addFinding("target_handoff_not_prepared", "info", "medium", "seamlessness",
-      "No compact handoff prepared for a target (Claude/Codex/local model).",
-      [], "Run `avorelo session-context --handoff --target claude`.", false, true);
-  }
-
-  return findings;
-}
-
-// ── In-session value moments ──────────────────────────────────────────────────
-
-function buildSessionValueMoments(receipts, capabilityRec, findings, readiness) {
-  const moments = [];
-  const sc = receipts.sessionContext.data;
-  const wc = receipts.workControl.data;
-  const intake = receipts.installIntake.data;
-
-  // session_start
-  const sessionContextFresh = receipts.sessionContext.present && !isStale(receipts.sessionContext.ageMs, STALE_SHORT_MS);
-  const relevantFiles = sc && sc.sessionStart ? (sc.sessionStart.relevantFiles || []).length : 0;
-  const compactTokens = sc && sc.tokenDiscipline ? sc.tokenDiscipline.estimatedTokens : null;
-  // Suppress moment if session context value is weak (no relevant files, no compact tokens)
-  const sessionStartValueStrong = sessionContextFresh && (relevantFiles > 0 || compactTokens !== null);
-  if (sessionStartValueStrong) {
-    moments.push({
-      moment: "session_start",
-      severity: "success",
-      oneLine: `Ready to continue. Avorelo selected ${relevantFiles} relevant files and prepared a compact Claude handoff${compactTokens ? ` (~${compactTokens.toLocaleString()} tokens)` : ""}.`,
-      whyItMatters: "The next model session gets targeted context instead of broad rediscovery.",
-      evidence: ["session-context", "workspace-registry"],
-      nextAction: sc && sc.sessionStart && sc.sessionStart.nextSafestAction ? sc.sessionStart.nextSafestAction : null,
-      suppressIfLowValue: false,
-    });
-  } else if (!sessionContextFresh) {
-    moments.push({
-      moment: "session_start",
-      severity: "info",
-      oneLine: "Session context not ready. Run `avorelo session-context --handoff --target claude` before the next session.",
-      whyItMatters: "Without compact session context, the next model will rediscover files and context manually.",
-      evidence: [],
-      nextAction: "avorelo session-context --handoff --target claude",
-      suppressIfLowValue: false,
-    });
-  }
-
-  // routing_decision
-  const capPack = capabilityRec && capabilityRec.recommendedPack;
-  if (capPack) {
-    moments.push({
-      moment: "routing_decision",
-      severity: "info",
-      oneLine: `Recommended path: ${capPack.name}. Why: ${capabilityRec.reason || "capability matched workspace signals"}.`,
-      whyItMatters: "Using the right capability reduces wasted context and manual routing decisions.",
-      evidence: ["capability-recommender"],
-      nextAction: capabilityRec.nextAction || null,
-      suppressIfLowValue: readiness.score >= 80,
-    });
-  }
-
-  // risk_detected
-  const highRisk = intake && intake.summary ? (intake.summary.highRiskItems || 0) : 0;
-  const critRisk = intake && intake.summary ? (intake.summary.criticalRiskItems || 0) : 0;
-  if (highRisk > 0 || critRisk > 0) {
-    moments.push({
-      moment: "risk_detected",
-      severity: critRisk > 0 ? "warning" : "info",
-      oneLine: `Risk surfaced: ${highRisk + critRisk} risky item${(highRisk + critRisk) !== 1 ? "s" : ""} detected (${critRisk} critical). Use Safe Path before executing deploy/network scripts.`,
-      whyItMatters: "Executing risky scripts without review can cause irreversible damage.",
-      evidence: ["install-intake"],
-      nextAction: "avorelo guard --action command_run --action deploy_operation",
-      suppressIfLowValue: false,
-    });
-  }
-
-  // proof_complete
-  if (receipts.proof.present) {
-    const proof = receipts.proof.data;
-    const finalStatus = proof && proof.finalStatus ? proof.finalStatus : "unknown";
-    const checkedStages = proof && proof.verification ? proof.verification : null;
-    moments.push({
-      moment: "proof_complete",
-      severity: finalStatus === "success" ? "success" : "info",
-      oneLine: `Proof: ${finalStatus}. Verification: ${checkedStages ? "recorded" : "not recorded"}.`,
-      whyItMatters: "Proof shows what was checked so the next session knows where to continue.",
-      evidence: ["proof"],
-      nextAction: null,
-      suppressIfLowValue: finalStatus === "success",
-    });
-  }
-
-  // session_end
-  const hasAnySavings = receipts.sessionContext.present || receipts.workControl.present;
-  if (hasAnySavings) {
-    const savers = [
-      receipts.sessionContext.present ? "context reduced" : null,
-      receipts.workControl.present && wc && wc.workControl && wc.workControl.nextSafestAction ? "next action preserved" : null,
-      (highRisk > 0 || critRisk > 0) ? "risk surfaced" : null,
-      capPack ? "capability auto-selected" : null,
-    ].filter(Boolean);
-    moments.push({
-      moment: "session_end",
-      severity: "success",
-      oneLine: savers.length > 0
-        ? `Saved this session: ${savers.join(", ")}.`
-        : "Avorelo surfaces are ready for the next session.",
-      whyItMatters: "These savings compound — each prepared session reduces rediscovery in the next.",
-      evidence: [],
-      nextAction: null,
-      suppressIfLowValue: savers.length === 0,
-    });
-  }
-
-  return moments;
-}
-
-// ── Coach output ──────────────────────────────────────────────────────────────
-
-function buildCoachOutput(findings, readiness, receipts) {
-  // Find the most impactful finding
-  const priority = ["error", "warning", "info"];
-  const valueTypePriority = ["security", "time", "cost_tokens", "clarity", "seamlessness"];
-
-  const prioritized = [...findings].sort((a, b) => {
-    const ai = priority.indexOf(a.severity);
-    const bi = priority.indexOf(b.severity);
-    if (ai !== bi) return ai - bi;
-    return valueTypePriority.indexOf(a.valueType) - valueTypePriority.indexOf(b.valueType);
-  });
-
-  const top = prioritized[0];
-
-  if (!top) {
-    return {
-      finding: "All operating loop surfaces are ready.",
-      whyItMatters: "Avorelo has prepared context, capability routing, and safety surfaces.",
-      expectedValue: "The next session starts with no rediscovery needed.",
-      recommendedAction: "Run `avorelo session-context --handoff --target claude` when starting a new session.",
-      confidence: readiness.score >= 80 ? "high" : "medium",
-      askUserOnlyIfBlocked: null,
-    };
-  }
-
-  const valueTypeLabels = {
-    time: "time saved",
-    cost_tokens: "context/token reduction",
-    security: "security risk avoided",
-    clarity: "clarity improved",
-    seamlessness: "seamlessness improved",
-  };
-
-  return {
-    finding: top.plainEnglish,
-    whyItMatters: `This ${top.severity === "error" ? "critical issue" : "opportunity"} affects ${valueTypeLabels[top.valueType] || top.valueType}.`,
-    expectedValue: top.valueType === "time" ? "Avoid repo rediscovery in the next session."
-      : top.valueType === "security" ? "Prevent risky actions from running without review."
-        : top.valueType === "cost_tokens" ? "Reduce candidate context loaded in the next session."
-          : "Improve operating loop quality.",
-    recommendedAction: top.recommendedAction,
-    confidence: top.confidence,
-    askUserOnlyIfBlocked: top.needsUserAction ? null : null,
-  };
-}
-
-// ── Impact validation ─────────────────────────────────────────────────────────
-
-function buildImpactValidation(receipts, readiness) {
-  const rawEst = estimateRawContextTokens(receipts);
-  const compactEst = estimateCompactHandoffTokens(receipts);
-  const sc = receipts.sessionContext.data;
-  const reg = receipts.workspaceRegistry.data;
-  const wc = receipts.workControl.data;
-
-  const rawTokens = rawEst.tokens;
-  const compactTokens = compactEst.tokens;
-
-  const before = {
-    rawContextEstimateTokens: rawTokens,
-    rawContextEstimateBasis: rawEst.sources.join("; ") || "unavailable",
-    workControlReceiptChars: receipts.workControl.charLen,
-    registryAssets: reg && reg.summary ? reg.summary.totalAssets : null,
-    broadScanWouldHaveOccurred: !receipts.sessionContext.present,
-  };
-
-  const after = {
-    compactHandoffTokens: compactTokens,
-    compactHandoffBasis: compactEst.basis,
-    relevantFilesSelected: sc && sc.sessionStart ? (sc.sessionStart.relevantFiles || []).length : 0,
-    broadScanAvoided: receipts.sessionContext.present,
-    jsonDumpAvoided: Boolean(sc && sc.tokenDiscipline && sc.tokenDiscipline.avoidedJsonDump),
-    nextActionPresent: readiness.checks.nextActionAvailable,
-    proofPresent: receipts.proof.present,
-  };
-
-  let verdict = "insufficient_data";
-  let confidence = "low";
-
-  if (rawTokens === null || compactTokens === null) {
-    verdict = "insufficient_data";
-    confidence = "low";
-  } else if (compactTokens > rawTokens) {
-    verdict = "regressed";
-    confidence = "low";
-  } else {
-    const reduction = (rawTokens - compactTokens) / rawTokens;
-    const hasQualitySignals = after.nextActionPresent && (after.proofPresent || after.relevantFilesSelected > 0);
-    if (reduction >= 0.5 && hasQualitySignals) {
-      verdict = "improved";
-      confidence = "medium";
-    } else if (reduction > 0 || hasQualitySignals) {
-      verdict = "unclear";
-      confidence = "low";
-    } else {
-      verdict = "insufficient_data";
-    }
-  }
-
-  const tokenReduction = rawTokens && compactTokens ? Math.max(0, rawTokens - compactTokens) : null;
-  const evidenceSources = [
-    rawEst.sources.length ? `raw estimate sources: ${rawEst.sources.join(", ")}` : null,
-    `compact from: ${compactEst.basis}`,
-  ].filter(Boolean);
-
-  return {
-    verdict,
-    before,
-    after,
-    tokenReduction,
-    tokenReductionPercent: rawTokens && tokenReduction ? Math.round((tokenReduction / rawTokens) * 100) : null,
-    evidence: evidenceSources,
-    confidence,
-    caveat: "Context estimates are based on candidate source sizes, not measured model context window usage. Confidence is intentionally conservative.",
-  };
-}
-
-// ── Dashboard-ready surface ───────────────────────────────────────────────────
-
-function buildDashboardReady(cards, readiness, capabilityRec, receipts, localDashboardPath, calibration) {
-  const timeSaved = cards.timeSaved;
-  const costTokens = cards.costOrTokensSaved;
-  const security = cards.securityRiskAvoided;
-
-  // Hero sentence: pick strongest available signal
-  let hero = "Avorelo operating surfaces are ready.";
-  if (timeSaved.status === "available" && timeSaved.headline.includes("minutes")) {
-    hero = timeSaved.userFacingSentence;
-  } else if (costTokens.status === "available" && costTokens.userFacingSentence.includes("tokens")) {
-    hero = costTokens.userFacingSentence;
-  } else if (security.status === "available") {
-    hero = security.userFacingSentence;
-  }
-
-  const nextAction = readiness.nextAction;
-
-  const wc = receipts.workControl.data;
-  const evidenceLine = [
-    receipts.workControl.present ? `work-control: ${wc && wc.workControl ? wc.workControl.finalState || "ok" : "ok"}` : null,
-    receipts.sessionContext.present ? "session-context: ready" : null,
-    receipts.workspaceRegistry.present ? `registry: ${receipts.workspaceRegistry.data && receipts.workspaceRegistry.data.summary ? receipts.workspaceRegistry.data.summary.totalAssets + " assets" : "ready"}` : null,
-    receipts.installIntake.present ? `intake: scanned` : null,
-  ].filter(Boolean).join(" · ");
-
-  const shouldShowInSession = readiness.band === "needs_attention" || readiness.band === "fair";
-  const shouldShowDashboard = true;
-
-  // Derive proof data for primary card enrichment from calibration
-  const proofs = calibration ? calibration.proofs : [];
-  const getProof = (id) => proofs.find((p) => p.valueId === id) || null;
-  const timeSavedProof = getProof("timeSaved");
-  const tokenProof = getProof("tokenReduction");
-  const securityProof = getProof("risksSurfaced") || proofs.find((p) => p.dimension === "security" && p.value !== null) || null;
-
-  const calibVerdict = calibration ? calibration.calibrationReport.overallVerdict : null;
-  const safeCopyCandidates = calibration ? (calibration.calibrationReport.recommendedCopySafe || []) : [];
-  const blockedCopyCandidates = calibration ? (calibration.calibrationReport.blockedCopy || []) : [];
-
-  return {
-    hero,
-    primaryCards: [
-      {
-        id: timeSaved.id, label: timeSaved.label, headline: timeSaved.headline,
-        status: timeSaved.status, userFacingSentence: timeSaved.userFacingSentence,
-        confidence: timeSaved.confidence, estimateBasis: timeSaved.estimateBasis,
-        valueClass: timeSavedProof ? timeSavedProof.valueClass : "heuristic",
-        caveat: timeSavedProof && timeSavedProof.caveats.length ? timeSavedProof.caveats[0] : null,
-        evidence: timeSavedProof ? timeSavedProof.evidence : (timeSaved.evidence || []),
-        userFacingAllowed: timeSavedProof ? timeSavedProof.userFacingAllowed : (timeSaved.status !== "unavailable"),
-        dashboardAllowed: timeSavedProof ? timeSavedProof.dashboardAllowed : (timeSaved.status !== "unavailable"),
-      },
-      {
-        id: costTokens.id, label: costTokens.label, headline: costTokens.headline,
-        status: costTokens.status, userFacingSentence: costTokens.userFacingSentence,
-        confidence: costTokens.confidence, estimateBasis: costTokens.estimateBasis,
-        valueClass: tokenProof ? tokenProof.valueClass : "unavailable",
-        caveat: tokenProof && tokenProof.caveats.length ? tokenProof.caveats[0] : "Cost unavailable — no local pricing source",
-        evidence: tokenProof ? tokenProof.evidence : (costTokens.evidence || []),
-        userFacingAllowed: tokenProof ? tokenProof.userFacingAllowed : (costTokens.status !== "unavailable"),
-        dashboardAllowed: tokenProof ? tokenProof.dashboardAllowed : (costTokens.status !== "unavailable"),
-      },
-      {
-        id: security.id, label: security.label, headline: security.headline,
-        status: security.status, userFacingSentence: security.userFacingSentence,
-        confidence: security.confidence,
-        valueClass: securityProof ? securityProof.valueClass : (security.confidence === "high" ? "measured" : "unavailable"),
-        caveat: securityProof && securityProof.caveats.length ? securityProof.caveats[0] : null,
-        evidence: securityProof ? securityProof.evidence : (security.evidence || []),
-        userFacingAllowed: securityProof ? securityProof.userFacingAllowed : (security.status !== "unavailable"),
-        dashboardAllowed: securityProof ? securityProof.dashboardAllowed : (security.status !== "unavailable"),
-      },
-    ],
-    secondaryCards: [
-      { id: cards.clarity.id, label: cards.clarity.label, headline: cards.clarity.headline, status: cards.clarity.status },
-      { id: cards.seamlessness.id, label: cards.seamlessness.label, headline: cards.seamlessness.headline, status: cards.seamlessness.status },
-    ],
-    evidenceLine: evidenceLine || "No evidence available yet.",
-    readinessScore: readiness.score,
-    readinessBand: readiness.band,
-    nextAction,
-    calibrationVerdict: calibVerdict,
-    caveatLine: "Time estimate is heuristic. Token estimate is based on candidate context size, not measured model context window usage.",
-    localDashboardPath: localDashboardPath || null,
-    displayPolicy: {
-      onlyUserFacingAllowedByDefault: true,
-      caveatsRequired: true,
-      pricingClaimsBlocked: true,
-      websiteClaimsBlockedUntilMeasuredHighConfidence: true,
-    },
-    safeCopyCandidates,
-    blockedCopyCandidates,
-    shouldShowInSession,
-    shouldShowDashboard,
-  };
-}
-
-// ── Willingness-to-pay signals ────────────────────────────────────────────────
-
-function buildWillingnessToPaySignals(cards, readiness, receipts) {
-  const signals = [];
-
-  const timeSaved = cards.timeSaved;
-  if (timeSaved.status === "available" && timeSaved.primaryMetric.includes("steps")) {
-    signals.push({
-      signal: "time_savings_measurable",
-      value: timeSaved.headline,
-      evidence: "work-control + session-context + registry surfaces",
-      userFacingHook: timeSaved.userFacingSentence,
-    });
-  }
-
-  const reg = receipts.workspaceRegistry.data;
-  if (reg && reg.valueMeasurement && reg.valueMeasurement.willingnessToPaySignal) {
-    signals.push({
-      signal: "workspace_registry_wtp",
-      value: reg.valueMeasurement.willingnessToPaySignal,
-      evidence: "workspace-registry.valueMeasurement",
-    });
-  }
-
-  if (readiness.score >= 70) {
-    signals.push({
-      signal: "high_readiness_score",
-      value: `${readiness.score}/100 (${readiness.band})`,
-      evidence: "operating loop readiness score",
-      userFacingHook: "Your AI coding environment is well-prepared. Avorelo handles the setup automatically.",
-    });
-  }
-
-  return signals;
-}
-
-// ── Display policy helpers ────────────────────────────────────────────────────
-
-function filterUserFacingValueCards(proofs) {
-  return (proofs || []).filter((p) => p.userFacingAllowed === true);
-}
-
-function buildSafeCopyCandidates(calibrationReport) {
-  return calibrationReport ? (calibrationReport.recommendedCopySafe || []) : [];
-}
-
-function buildBlockedCopyCandidates(calibrationReport) {
-  return calibrationReport ? (calibrationReport.blockedCopy || []) : [];
-}
-
-function formatCaveatLine(proof) {
-  if (!proof || !proof.caveats || !proof.caveats.length) return null;
-  return proof.caveats[0];
-}
-
-function formatEvidenceLine(proofs) {
-  const sources = new Set();
-  (proofs || []).forEach((p) => {
-    (p.evidence || []).forEach((e) => sources.add(e));
-  });
-  return sources.size ? Array.from(sources).join(" · ") : null;
-}
-
-// ── Local dashboard preview ───────────────────────────────────────────────────
-
-function buildLocalDashboardPreview(cwd, value) {
-  const dashboardReady = value.dashboardReady;
-  const readiness = value.operatingLoopReadiness;
-
-  if (!dashboardReady) return null;
-
-  // Filter primary cards to user-facing-allowed only
-  const visiblePrimaryCards = (dashboardReady.primaryCards || []).filter(
-    (c) => c.userFacingAllowed !== false
-  );
-
-  const calibVerdict = dashboardReady.calibrationVerdict;
-  const caveatLine = dashboardReady.caveatLine;
-
-  const lines = [
-    `# Avorelo Value Summary`,
-    `_Generated: ${value.createdAt || new Date().toISOString()}_`,
-    ``,
-    `## Hero`,
-    `**${dashboardReady.hero}**`,
-    ``,
-    `Readiness: **${readiness.bandLabel}** (${readiness.score}/100)`,
-    ``,
-    `## Primary Value`,
-    ``,
-    `| Dimension | Status | Headline | Confidence |`,
-    `|-----------|--------|----------|------------|`,
-    ...visiblePrimaryCards.map((c) => {
-      const conf = c.valueClass ? `${c.valueClass}${c.confidence ? `, ${c.confidence}` : ""}` : (c.confidence || "");
-      return `| ${c.label} | ${c.status} | ${c.headline} | ${conf} |`;
-    }),
-    ``,
-    visiblePrimaryCards.some((c) => c.caveat) ? `## Caveats` : null,
-    ...visiblePrimaryCards
-      .filter((c) => c.caveat)
-      .map((c) => `- **${c.label}:** ${c.caveat}`),
-    visiblePrimaryCards.some((c) => c.caveat) ? `` : null,
-    `## Next Action`,
-    `${dashboardReady.nextAction}`,
-    ``,
-    `## Evidence`,
-    `${dashboardReady.evidenceLine}`,
-    ``,
-    calibVerdict ? `## Calibration` : null,
-    calibVerdict ? `Verdict: **${calibVerdict.replace(/_/g, " ")}**` : null,
-    caveatLine ? `_${caveatLine}_` : null,
-    calibVerdict ? `` : null,
-    `_Run \`avorelo operating-value --json\` for the full calibrated data contract._`,
-  ].filter((l) => l !== null);
-
-  const content = lines.join("\n") + "\n";
-  const abs = path.join(cwd, OPERATING_VALUE_DASHBOARD_PREVIEW_REL);
-  try {
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, content, "utf8");
-    return OPERATING_VALUE_DASHBOARD_PREVIEW_REL;
-  } catch {
-    return null;
-  }
-}
-
-// ── Main builder ──────────────────────────────────────────────────────────────
-
-function buildOperatingValue(cwd, options = {}) {
-  const valueId = `ov-${Date.now()}-${shortId()}`;
-  const createdAt = nowIso();
-
-  const receipts = readReceipts(cwd);
-
-  // Read capability recommendation (non-blocking)
-  let capabilityRec = null;
-  try {
-    const { buildCapabilityLayerSurface } = require("./capability-recommender");
-    capabilityRec = buildCapabilityLayerSurface(cwd, {}, null);
-  } catch {}
-
-  // ── Measurement evidence (non-blocking) ──────────────────────────────────────
-  let pricingSource = null;
-  let pricingEntry = null;
-  let tokenEvidence = null;
-  let costEvidenceV1 = null;
-  try {
-    pricingSource = getLocalPricingSource(cwd);
-    if (pricingSource.available) {
-      // Default to claude-sonnet-4-6 if no specific model info available
-      pricingEntry = getLocalPricingEntry(cwd, "anthropic", "claude-sonnet-4-6");
-    }
-    tokenEvidence = buildTokenEvidence(cwd);
-    writeTokenEvidence(cwd, tokenEvidence);
-    costEvidenceV1 = buildCostEvidenceV1({ pricingSource, pricingEntry, tokenEvidence });
-  } catch {}
-
-  const cards = {
-    timeSaved: buildTimeSavedCard(receipts, capabilityRec),
-    costOrTokensSaved: buildCostOrTokensSavedCard(receipts, costEvidenceV1),
-    securityRiskAvoided: buildSecurityRiskAvoidedCard(receipts),
-    clarity: buildClarityCard(receipts),
-    seamlessness: buildSeamlessnessCard(receipts, capabilityRec),
-  };
-
-  const readiness = buildOperatingLoopReadiness(receipts, capabilityRec);
-  const findings = buildOpportunityFindings(receipts, capabilityRec, readiness);
-  const moments = buildSessionValueMoments(receipts, capabilityRec, findings, readiness);
-  const coach = buildCoachOutput(findings, readiness, receipts);
-  const impactValidation = buildImpactValidation(receipts, readiness);
-  const willingnessToPaySignals = buildWillingnessToPaySignals(cards, readiness, receipts);
-
-  const rawEst = estimateRawContextTokens(receipts);
-  const compactEst = estimateCompactHandoffTokens(receipts);
-  const steps = countManualStepsAvoided(receipts, capabilityRec);
-  const sc = receipts.sessionContext.data;
-  const reg = receipts.workspaceRegistry.data;
-  const intake = receipts.installIntake.data;
-  const safePath = receipts.safePath.data;
-
-  // ── Value proof calibration (computed before dashboardReady so display policy fields are populated) ─
-  const highRiskItemsForProof = intake && intake.summary ? intake.summary.highRiskItems || 0 : 0;
-  const critRiskItemsForProof = intake && intake.summary ? intake.summary.criticalRiskItems || 0 : 0;
-  const safePathDecisionForProof = safePath && safePath.safePathDecision ? safePath.safePathDecision : null;
-  const risksBlockedForProof = safePathDecisionForProof === "block" ? 1 : 0;
-  const risksRoutedForProof = (safePathDecisionForProof === "approval_required" || safePathDecisionForProof === "recommend_reduced_scope" || safePathDecisionForProof === "warn_with_boundary") ? 1 : 0;
-  const tokenReductionForProof = rawEst.tokens && compactEst.tokens ? Math.max(0, rawEst.tokens - compactEst.tokens) : null;
-  const capAppliedForProof = steps.count * MINUTES_PER_MANUAL_STEP_HIGH > MINUTES_CAP;
-
-  const calibration = buildValueProofs({
-    manualStepsAvoided: steps.count,
-    minMinutes: steps.count * MINUTES_PER_MANUAL_STEP_LOW,
-    maxMinutes: Math.min(steps.count * MINUTES_PER_MANUAL_STEP_HIGH, MINUTES_CAP),
-    timeSavedEvidence: cards.timeSaved.evidence,
-    capApplied: capAppliedForProof,
-    rawCandidateTokens: rawEst.tokens,
-    rawConfidence: rawEst.confidence,
-    rawSources: rawEst.sources,
-    compactHandoffTokens: compactEst.tokens,
-    compactConfidence: compactEst.confidence,
-    tokenReduction: tokenReductionForProof,
-    hasLocalPricingSource: !!(pricingSource && pricingSource.available),
-    costEvidence: costEvidenceV1,
-    risksSurfaced: highRiskItemsForProof + critRiskItemsForProof,
-    risksRouted: risksRoutedForProof,
-    risksBlocked: risksBlockedForProof,
-    approvalsRequired: 0,
-    reducedScopeRecommendations: 0,
-    reviewRequiredItems: 0,
-    highRiskAssetsInRegistry: reg && reg.summary ? reg.summary.highRiskAssets || 0 : 0,
-    intakePresent: receipts.installIntake.present,
-    safePathPresent: receipts.safePath.present,
-    nextActionPresent: readiness.checks.nextActionAvailable,
-    doNotRepeatCount: cards.clarity.doNotRepeatCount,
-    relevantCommandsCount: cards.clarity.relevantCommandsCount,
-    targetHandoffPrepared: readiness.checks.targetHandoffPrepared,
-    proofAvailable: receipts.proof.present,
-  });
-
-  const dashboardReady = buildDashboardReady(cards, readiness, capabilityRec, receipts, null, calibration);
-
-  // Build local dashboard preview now that dashboardReady has calibration data
-  const finalPreviewPath = options.skipPreview ? null : buildLocalDashboardPreview(cwd, {
-    createdAt,
-    operatingLoopReadiness: readiness,
-    valueCards: cards,
-    dashboardReady,
-  });
-  dashboardReady.localDashboardPath = finalPreviewPath;
-
-  const optimizationEffectiveness = {
-    rawContextWouldHaveLoadedTokens: rawEst.tokens,
-    rawContextSources: rawEst.sources,
-    compactHandoffTokens: compactEst.tokens,
-    compactHandoffBasis: compactEst.basis,
-    tokenReductionEstimate: rawEst.tokens && compactEst.tokens ? Math.max(0, rawEst.tokens - compactEst.tokens) : null,
-    contextCompressionRatio: rawEst.tokens && compactEst.tokens && rawEst.tokens > 0 ? Math.round((compactEst.tokens / rawEst.tokens) * 100) / 100 : null,
-    relevantFilesSelected: sc && sc.sessionStart ? (sc.sessionStart.relevantFiles || []).length : 0,
-    totalWorkspaceAssets: reg && reg.summary ? reg.summary.totalAssets : null,
-    broadScanAvoided: Boolean(sc && sc.tokenDiscipline && sc.tokenDiscipline.avoidedBroadRediscovery),
-    hugeJsonDumpAvoided: Boolean(sc && sc.tokenDiscipline && sc.tokenDiscipline.avoidedJsonDump),
-    manualStepsAvoided: steps.count,
-    manualStepsDetail: steps.details,
-    timeSavedEstimateMinutesLow: steps.count * MINUTES_PER_MANUAL_STEP_LOW,
-    timeSavedEstimateMinutesHigh: Math.min(steps.count * MINUTES_PER_MANUAL_STEP_HIGH, MINUTES_CAP),
-    costAvoidedEstimate: null,
-    costNote: "Cost avoided requires a local token pricing source. Not available.",
-    estimateBasis: "heuristic (manual steps × 1–3 min, token estimates from source char lengths)",
-    confidence: steps.count >= 5 ? "medium" : "low",
-  };
-
-  const routingQuality = {
-    recommendedCapabilityPack: capabilityRec ? capabilityRec.recommendedPack : null,
-    additionalPacks: capabilityRec ? capabilityRec.additionalPacks : [],
-    capabilityAutoRecommended: Boolean(capabilityRec && capabilityRec.recommendedPack),
-    wrongCapabilityRisk: Boolean(capabilityRec && capabilityRec.wrongCapabilityRisk),
-    nextActionQuality: readiness.checks.nextActionAvailable ? "available" : "missing",
-    confidence: capabilityRec ? "medium" : "unavailable",
-  };
-
-  const highRiskItems = intake && intake.summary ? intake.summary.highRiskItems || 0 : 0;
-  const critRiskItems = intake && intake.summary ? intake.summary.criticalRiskItems || 0 : 0;
-  const safePathDecision = safePath && safePath.safePathDecision ? safePath.safePathDecision : null;
-
-  const securityRoutingEffectiveness = {
-    highRiskAssets: reg && reg.summary ? reg.summary.highRiskAssets || 0 : null,
-    riskyAssetsRouted: Boolean(safePathDecision && safePathDecision !== "allow_as_is"),
-    risksBlocked: safePathDecision === "block" ? 1 : 0,
-    risksRouted: (safePathDecision === "approval_required" || safePathDecision === "recommend_reduced_scope" || safePathDecision === "warn_with_boundary") ? 1 : 0,
-    unknownToolOrMcpDetected: intake && intake.summary ? intake.summary.unknownItems > 0 : null,
-    safePathRecommended: Boolean(safePathDecision && safePathDecision !== "allow_as_is"),
-    riskAvoidedSummary: intake && intake.summary
-      ? `${highRiskItems + critRiskItems} high/critical-risk items scanned, ${safePathDecision ? safePathDecision.replace(/_/g, " ") : "no safe-path receipt"}`
-      : "Install intake not yet run.",
-    confidence: receipts.installIntake.present ? "high" : "unavailable",
-  };
-
-  const clarityEff = {
-    nextActionPresent: readiness.checks.nextActionAvailable,
-    doNotRepeatCount: cards.clarity.doNotRepeatCount,
-    relevantCommandsCount: cards.clarity.relevantCommandsCount,
-    targetHandoffPrepared: readiness.checks.targetHandoffPrepared,
-    proofAvailable: receipts.proof.present,
-  };
-
-  const seamlessnessEff = {
-    userDidNotChooseCapability: cards.seamlessness.userDidNotChooseCapability,
-    oneCommandToContinue: Boolean(sc && sc.sessionStart && sc.sessionStart.nextSafestAction),
-    autoHandledFindings: cards.seamlessness.autoHandledFindings,
-    userActionRequiredFindings: cards.seamlessness.userActionRequiredFindings,
-    seamlessnessScore: cards.seamlessness.seamlessnessScore,
-  };
-
-  const primaryValue = {
-    timeSaved: { headline: cards.timeSaved.headline, status: cards.timeSaved.status, userFacingSentence: cards.timeSaved.userFacingSentence },
-    costOrTokensSaved: { headline: cards.costOrTokensSaved.headline, status: cards.costOrTokensSaved.status, userFacingSentence: cards.costOrTokensSaved.userFacingSentence },
-    securityRiskAvoided: { headline: cards.securityRiskAvoided.headline, status: cards.securityRiskAvoided.status, userFacingSentence: cards.securityRiskAvoided.userFacingSentence },
-  };
-
-  // Source receipt summary (no raw content — paths only)
-  const sourceReceipts = {
-    workControl: { present: receipts.workControl.present, path: WORK_CONTROL_REL, ageMs: receipts.workControl.present ? receipts.workControl.ageMs : null },
-    sessionContext: { present: receipts.sessionContext.present, path: SESSION_CONTEXT_REL, ageMs: receipts.sessionContext.present ? receipts.sessionContext.ageMs : null },
-    brainPack: { present: receipts.brainPack.present, path: BRAIN_PACK_REL, ageMs: receipts.brainPack.present ? receipts.brainPack.ageMs : null },
-    workspaceRegistry: { present: receipts.workspaceRegistry.present, path: WORKSPACE_REGISTRY_REL, ageMs: receipts.workspaceRegistry.present ? receipts.workspaceRegistry.ageMs : null },
-    capabilityRecommendation: { present: Boolean(capabilityRec), path: null },
-    installIntake: { present: receipts.installIntake.present, path: INSTALL_INTAKE_REL, ageMs: receipts.installIntake.present ? receipts.installIntake.ageMs : null },
-    safePath: { present: receipts.safePath.present, path: SAFE_PATH_REL, ageMs: receipts.safePath.present ? receipts.safePath.ageMs : null },
-    proof: { present: receipts.proof.present, path: PROOF_REL, ageMs: receipts.proof.present ? receipts.proof.ageMs : null },
-  };
-
-  return {
-    schemaVersion: OPERATING_VALUE_SCHEMA_VERSION,
-    contract: OPERATING_VALUE_CONTRACT,
-    valueId,
-    createdAt,
-    cwd,
-    sourceReceipts,
-    primaryValue,
-    valueCards: cards,
-    operatingLoopReadiness: readiness,
-    optimizationEffectiveness,
-    routingQuality,
-    securityRoutingEffectiveness,
-    clarityEffectiveness: clarityEff,
-    seamlessness: seamlessnessEff,
-    opportunityFindings: findings,
-    sessionValueMoments: moments,
-    coach,
-    impactValidation,
-    dashboardReady,
-    willingnessToPaySignals,
-    valueProofs: calibration.proofs,
-    calibrationReport: calibration.calibrationReport,
-    productLearning: {
-      eventsWritten: [],
-      suggestedEvents: [
-        "operating_value_generated",
-        "value_proof_calibrated",
-        calibration.calibrationReport.overclaimRisks.length > 0 ? "value_claim_overclaim_risk_detected" : null,
-      ].filter(Boolean),
-    },
-    redacted: true,
-  };
-}
-
-// ── Write / read functions ────────────────────────────────────────────────────
-
-function writeOperatingValue(cwd, value) {
-  const dir = path.join(cwd, OPERATING_VALUE_DIR_REL);
-  const histDir = path.join(cwd, OPERATING_VALUE_HISTORY_DIR_REL);
-  fs.mkdirSync(dir, { recursive: true });
-  fs.mkdirSync(histDir, { recursive: true });
-
-  const latestAbs = path.join(cwd, OPERATING_VALUE_LATEST_REL);
-  fs.writeFileSync(latestAbs, JSON.stringify(value, null, 2), "utf8");
-
-  const histAbs = path.join(histDir, `${value.valueId}.json`);
-  fs.writeFileSync(histAbs, JSON.stringify(value, null, 2), "utf8");
-
-  // Write summary markdown
-  const summaryAbs = path.join(cwd, OPERATING_VALUE_SUMMARY_REL);
-  fs.writeFileSync(summaryAbs, buildOperatingValueSummaryMarkdown(value), "utf8");
-
-  // Append event
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    appendProductLearningEvent(cwd, {
-      eventName: "operating_value_generated",
-      category: "operating_value",
-      payload: {
-        readinessScore: value.operatingLoopReadiness.score,
-        readinessBand: value.operatingLoopReadiness.band,
-        manualStepsAvoided: value.optimizationEffectiveness.manualStepsAvoided,
-        tokenReductionEstimate: value.optimizationEffectiveness.tokenReductionEstimate,
-        impactValidationVerdict: value.impactValidation.verdict,
-        confidence: value.optimizationEffectiveness.confidence,
-        opportunityCount: value.opportunityFindings.length,
-      },
-    });
-    if (value.calibrationReport) {
-      appendProductLearningEvent(cwd, {
-        eventName: "value_proof_calibrated",
-        category: "operating_value",
-        payload: {
-          overallVerdict: value.calibrationReport.overallVerdict,
-          measuredCount: value.calibrationReport.measuredCount,
-          estimatedCount: value.calibrationReport.estimatedCount,
-          heuristicCount: value.calibrationReport.heuristicCount,
-          unavailableCount: value.calibrationReport.unavailableCount,
-          overclaimRiskCount: value.calibrationReport.overclaimRisks.length,
-        },
-      });
-    }
-  } catch {}
-
-  return {
-    valuePath: OPERATING_VALUE_LATEST_REL,
-    summaryPath: OPERATING_VALUE_SUMMARY_REL,
-    historyPath: path.posix.join(OPERATING_VALUE_HISTORY_DIR_REL.replace(/\\/g, "/"), `${value.valueId}.json`),
-  };
-}
-
-function readLatestOperatingValue(cwd) {
-  const abs = path.join(cwd, OPERATING_VALUE_LATEST_REL);
-  return safeReadJson(abs);
-}
-
-// ── Surface for dashboard integration ────────────────────────────────────────
-
-function buildOperatingValueSurface(cwd) {
-  try {
-    const latest = readLatestOperatingValue(cwd);
-    if (!latest) {
-      return { status: "missing", hero: null, latestValuePath: null };
-    }
-    const dr = latest.dashboardReady;
-    return {
-      status: "available",
-      latestValuePath: OPERATING_VALUE_LATEST_REL,
-      hero: dr ? dr.hero : null,
-      timeSaved: latest.valueCards ? latest.valueCards.timeSaved : null,
-      costOrTokensSaved: latest.valueCards ? latest.valueCards.costOrTokensSaved : null,
-      securityRiskAvoided: latest.valueCards ? latest.valueCards.securityRiskAvoided : null,
-      clarity: latest.valueCards ? latest.valueCards.clarity : null,
-      seamlessness: latest.valueCards ? latest.valueCards.seamlessness : null,
-      readinessScore: latest.operatingLoopReadiness ? latest.operatingLoopReadiness.score : null,
-      readinessBand: latest.operatingLoopReadiness ? latest.operatingLoopReadiness.band : null,
-      nextAction: dr ? dr.nextAction : null,
-      localDashboardPath: dr ? dr.localDashboardPath : null,
-      shouldShowInSession: dr ? dr.shouldShowInSession : false,
-      shouldShowDashboard: dr ? dr.shouldShowDashboard : false,
-      calibrationVerdict: dr ? dr.calibrationVerdict : null,
-      calibrationReport: latest.calibrationReport || null,
-      createdAt: latest.createdAt,
-    };
-  } catch {
-    return { status: "error", hero: null, latestValuePath: null };
-  }
-}
-
-// ── Text formatters ───────────────────────────────────────────────────────────
-
-function buildOperatingValueSummaryMarkdown(value) {
-  const dr = value.dashboardReady;
-  const readiness = value.operatingLoopReadiness;
-  const coach = value.coach;
-  const validation = value.impactValidation;
-  const findings = value.opportunityFindings || [];
-  const actionFindings = findings.filter((f) => f.needsUserAction);
-
-  const lines = [
-    `# Avorelo Operating Value Summary`,
-    `_${value.createdAt}_`,
-    ``,
-    `## Hero`,
-    `**${dr ? dr.hero : "Operating surfaces ready."}**`,
-    ``,
-    `## Readiness: ${readiness.bandLabel} (${readiness.score}/100)`,
-    readiness.nextAction,
-    ``,
-    `## Primary Value`,
-    `- **Time Saved:** ${value.valueCards.timeSaved.headline} — ${value.valueCards.timeSaved.userFacingSentence}`,
-    `- **Context/Tokens:** ${value.valueCards.costOrTokensSaved.headline} — ${value.valueCards.costOrTokensSaved.userFacingSentence}`,
-    `- **Security:** ${value.valueCards.securityRiskAvoided.headline} — ${value.valueCards.securityRiskAvoided.userFacingSentence}`,
-    ``,
-    `## Coach`,
-    `**Finding:** ${coach.finding}`,
-    `**Expected value:** ${coach.expectedValue}`,
-    `**Recommended action:** ${coach.recommendedAction}`,
-    ``,
-    `## Impact Validation`,
-    `Verdict: **${validation.verdict}** (confidence: ${validation.confidence})`,
-    validation.tokenReduction ? `Token reduction: ~${validation.tokenReduction.toLocaleString()} tokens (${validation.tokenReductionPercent || "?"}%)` : "Token data insufficient for comparison.",
-    `_${validation.caveat}_`,
-    ``,
-    actionFindings.length > 0 ? [
-      `## Action Needed (${actionFindings.length})`,
-      ...actionFindings.slice(0, 3).map((f) => `- [${f.severity.toUpperCase()}] ${f.plainEnglish} → ${f.recommendedAction}`),
-    ].join("\n") : `## All Clear`,
-    actionFindings.length === 0 ? "No user action needed. All findings handled automatically." : "",
-    ``,
-    (() => {
-      const cr = value.calibrationReport;
-      if (!cr) return null;
-      const lines = [
-        `## Calibration`,
-        `Verdict: **${cr.overallVerdict}** (measured: ${cr.measuredCount}, estimated: ${cr.estimatedCount}, heuristic: ${cr.heuristicCount}, unavailable: ${cr.unavailableCount})`,
-        cr.strongestClaims.length ? `Strongest: ${cr.strongestClaims.slice(0, 2).join("; ")}` : null,
-        cr.weakestClaims.length ? `Weakest: ${cr.weakestClaims.slice(0, 2).join("; ")}` : null,
-        cr.overclaimRisks.length ? `Overclaim risks: ${cr.overclaimRisks.map((r) => r.valueId).join(", ")}` : null,
-        ``,
-        `## Safe Copy Candidates`,
-        cr.recommendedCopySafe && cr.recommendedCopySafe.length
-          ? cr.recommendedCopySafe.map((s) => `- ${s}`).join("\n")
-          : "- None ready yet — run more Avorelo surfaces to generate measured or estimated claims.",
-        ``,
-        `## Blocked Copy`,
-        cr.blockedCopy && cr.blockedCopy.length
-          ? cr.blockedCopy.map((s) => `- BLOCKED: ${s}`).join("\n")
-          : "- No specific blocked copy identified.",
-      ].filter((l) => l !== null);
-      return lines.join("\n");
-    })(),
-    ``,
-    `_Run \`avorelo operating-value --json\` for the full data contract._`,
-  ].filter((l) => l !== undefined && l !== null);
-
-  return lines.join("\n") + "\n";
-}
-
-function formatOperatingValueText(value, options = {}) {
-  if (options.momentsOnly) {
-    const moments = value.sessionValueMoments || [];
-    if (!moments.length) return "No in-session value moments generated.\n";
-    return moments
-      .filter((m) => !m.suppressIfLowValue || options.showAll)
-      .map((m) => `[${m.moment.toUpperCase()}] ${m.oneLine}${m.nextAction ? `\n  → ${m.nextAction}` : ""}`)
-      .join("\n") + "\n";
-  }
-
-  if (options.validateOnly) {
-    const v = value.impactValidation;
-    const cr = value.calibrationReport;
-    const lines = [
-      `Impact Validation: ${v.verdict.toUpperCase()} (confidence: ${v.confidence})`,
-      v.tokenReduction ? `Token reduction: ~${v.tokenReduction.toLocaleString()} tokens (${v.tokenReductionPercent || "?"}%)` : "Token comparison unavailable.",
-      `Before: ~${v.before.rawContextEstimateTokens || "?"} raw candidate tokens`,
-      `After:  ~${v.after.compactHandoffTokens || "?"} compact tokens`,
-      v.after.broadScanAvoided ? "Broad scan: avoided" : "Broad scan: not detected as avoided",
-      v.after.nextActionPresent ? "Next action: present" : "Next action: missing",
-      `Caveat: ${v.caveat}`,
-      cr ? "" : null,
-      cr ? `Calibration Verdict: ${cr.overallVerdict}` : null,
-      cr && cr.strongestClaims.length ? `Strongest: ${cr.strongestClaims.slice(0, 2).join("; ")}` : null,
-      cr && cr.weakestClaims.length ? `Weakest: ${cr.weakestClaims.slice(0, 2).join("; ")}` : null,
-      cr && cr.overclaimRisks.length ? `Overclaim risks: ${cr.overclaimRisks.map((r) => r.valueId).join(", ")}` : null,
-    ].filter((l) => l !== null);
-    return lines.join("\n") + "\n";
-  }
-
-  const dr = value.dashboardReady;
-  const readiness = value.operatingLoopReadiness;
-  const coach = value.coach;
-
-  const timeSavedLabel = confidenceLabel(value.valueCards.timeSaved.estimateBasis && value.valueCards.timeSaved.estimateBasis.startsWith("heuristic") ? "heuristic" : "estimated", value.valueCards.timeSaved.confidence);
-  const tokensLabel = confidenceLabel(value.valueCards.costOrTokensSaved.confidence === "low" ? "estimated" : "estimated", value.valueCards.costOrTokensSaved.confidence);
-  const securityLabel = value.valueCards.securityRiskAvoided.confidence === "high" ? "measured" : null;
-  const calibVerdict = value.calibrationReport ? value.calibrationReport.overallVerdict : null;
-  const costCard = value.valueCards.costOrTokensSaved;
-  const costNote = costCard.costAvoidedEstimate !== null
-    ? ` · ${costCard.costNote}`
-    : null;
-
-  // Build token method label for Tokens/Cost line
-  let tokenMethodLabel = null;
-  try {
-    const { readTokenEvidence } = require("./token-evidence");
-    const te = readTokenEvidence(value.cwd || process.cwd());
-    if (te && te.tokenizer) {
-      const m = te.tokenizer.method;
-      if (m === "provider_usage") {
-        tokenMethodLabel = "measured from local provider usage";
-      } else if (m === "local_tokenizer") {
-        tokenMethodLabel = "estimated with local tokenizer";
-      } else if (m && m.includes("chars_div_4")) {
-        tokenMethodLabel = "estimated from chars/4";
-      }
-    }
-  } catch { /* non-blocking */ }
-
-  const tokensLine = tokenMethodLabel
-    ? `  Tokens/Cost:   ${costCard.headline} (${tokenMethodLabel})${costNote || ""}`
-    : `  Tokens/Cost:   ${costCard.headline}${tokensLabel ? ` (${tokensLabel})` : ""}${costNote || ""}`;
-
-  return [
-    `Avorelo Operating Value`,
-    ``,
-    `  ${dr ? dr.hero : "Surfaces ready."}`,
-    ``,
-    `  Readiness:   ${readiness.bandLabel} (${readiness.score}/100)`,
-    ``,
-    `  Time Saved:    ${value.valueCards.timeSaved.headline}${timeSavedLabel ? ` (${timeSavedLabel})` : ""}`,
-    tokensLine,
-    `  Security:      ${value.valueCards.securityRiskAvoided.headline}${securityLabel ? ` (${securityLabel})` : ""}`,
-    calibVerdict && calibVerdict !== "safe_to_show" ? `  Calibration:   ${calibVerdict.replace(/_/g, " ")}` : null,
-    ``,
-    coach.finding ? `  Action: ${coach.recommendedAction}` : null,
-    ``,
-    `  Evidence:    ${dr ? dr.evidenceLine : "—"}`,
-    dr && dr.localDashboardPath ? `  Dashboard: ${dr.localDashboardPath}` : null,
-    `  Full data: avorelo operating-value --json`,
-    ``,
-  ].filter((l) => l !== null).join("\n");
-}
-
-// ── Exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  OPERATING_VALUE_CONTRACT,
-  OPERATING_VALUE_SCHEMA_VERSION,
-  OPERATING_VALUE_LATEST_REL,
-  OPERATING_VALUE_SUMMARY_REL,
-  OPERATING_VALUE_DIR_REL,
-  OPERATING_VALUE_DASHBOARD_PREVIEW_REL,
-  buildOperatingValue,
-  writeOperatingValue,
-  readLatestOperatingValue,
-  buildOperatingValueSurface,
-  buildOperatingValueSummaryMarkdown,
-  formatOperatingValueText,
-  filterUserFacingValueCards,
-  buildSafeCopyCandidates,
-  buildBlockedCopyCandidates,
-  formatCaveatLine,
-  formatEvidenceLine,
-};