avorelo 0.1.0 → 0.2.0

package/scripts/lib/prelaunch-evidence-store.js

@@ -1,816 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-
-const { ensureCcoDirs, nowIso } = require("./fsx");
-const { redactPayload, redactString } = require("./product-learning-events");
-
-const FEEDBACK_EVIDENCE_DIR_REL = ".claude/cco/evidence/feedback";
-const FEEDBACK_EVIDENCE_JSONL_REL = `${FEEDBACK_EVIDENCE_DIR_REL}/feedback.jsonl`;
-const FEEDBACK_IMPORT_RECEIPT_REL = `${FEEDBACK_EVIDENCE_DIR_REL}/latest-import.json`;
-const FEEDBACK_INTAKE_PACK_DIR_REL = `${FEEDBACK_EVIDENCE_DIR_REL}/intake-pack`;
-const FEEDBACK_INTAKE_PACK_RECEIPT_REL = `${FEEDBACK_INTAKE_PACK_DIR_REL}/latest-pack.json`;
-const FEEDBACK_INTAKE_PACK_README_REL = `${FEEDBACK_INTAKE_PACK_DIR_REL}/README.md`;
-const FEEDBACK_INTAKE_PACK_TEMPLATE_REL = `${FEEDBACK_INTAKE_PACK_DIR_REL}/design-partner-feedback-template.md`;
-const FEEDBACK_INTAKE_PACK_CHECKLIST_REL = `${FEEDBACK_INTAKE_PACK_DIR_REL}/redaction-checklist.md`;
-
-const TOKEN_COST_EVIDENCE_DIR_REL = ".claude/cco/evidence/token-cost";
-const TOKEN_COST_EVIDENCE_JSONL_REL = `${TOKEN_COST_EVIDENCE_DIR_REL}/token-cost.jsonl`;
-const TOKEN_COST_CAPTURE_JSONL_REL = `${TOKEN_COST_EVIDENCE_DIR_REL}/capture.jsonl`;
-const TOKEN_COST_IMPORT_RECEIPT_REL = `${TOKEN_COST_EVIDENCE_DIR_REL}/latest-import.json`;
-const TOKEN_COST_CAPTURE_RECEIPT_REL = `${TOKEN_COST_EVIDENCE_DIR_REL}/latest-capture.json`;
-const TOKEN_COST_SUMMARY_REL = `${TOKEN_COST_EVIDENCE_DIR_REL}/summary.json`;
-
-const FEEDBACK_ITEM_CONTRACT = "avorelo.feedbackEvidenceItem.v1";
-const FEEDBACK_VALIDATION_CONTRACT = "avorelo.feedbackEvidenceValidation.v1";
-const FEEDBACK_INTAKE_PACK_CONTRACT = "avorelo.designPartnerFeedbackIntakePack.v1";
-const TOKEN_COST_ITEM_CONTRACT = "avorelo.tokenCostEvidenceItem.v1";
-const TOKEN_COST_VALIDATION_CONTRACT = "avorelo.tokenCostEvidenceValidation.v1";
-const TOKEN_COST_SUMMARY_CONTRACT = "avorelo.tokenCostEvidence.v1";
-
-const FEEDBACK_ALLOWED_KEYS = new Set([
-  "sourceType",
-  "date",
-  "persona",
-  "segment",
-  "theme",
-  "severity",
-  "quoteSummary",
-  "issueCategory",
-  "activationStage",
-  "trustConcern",
-  "pricingConcern",
-  "simulated",
-  "redacted",
-]);
-
-const TOKEN_COST_ALLOWED_KEYS = new Set([
-  "sourceType",
-  "capturedAt",
-  "runId",
-  "tool",
-  "taskType",
-  "modelProvider",
-  "modelName",
-  "provider",
-  "modelFamily",
-  "inputTokens",
-  "outputTokens",
-  "promptTokens",
-  "completionTokens",
-  "totalTokens",
-  "estimatedCostUsd",
-  "measuredCostUsd",
-  "costMicros",
-  "currency",
-  "evidenceMode",
-  "confidence",
-  "notesCategory",
-  "cacheHit",
-  "estimatedOnly",
-  "heuristic",
-  "redacted",
-]);
-
-const FEEDBACK_FORBIDDEN_KEYS = [
-  "prompt",
-  "promptText",
-  "rawPrompt",
-  "quote",
-  "rawQuote",
-  "transcript",
-  "code",
-  "rawCode",
-  "commandOutput",
-  "stack",
-  "path",
-  "filePath",
-  "repoContent",
-  "secret",
-  "apiKey",
-  "token",
-];
-
-const TOKEN_COST_FORBIDDEN_KEYS = [
-  "prompt",
-  "promptText",
-  "rawPrompt",
-  "completion",
-  "completionText",
-  "code",
-  "rawCode",
-  "commandOutput",
-  "stack",
-  "path",
-  "filePath",
-  "repoContent",
-  "secret",
-  "apiKey",
-  "accessToken",
-  "authorization",
-];
-
-function sha256(value) {
-  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
-}
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function safeReadJsonl(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return [];
-    return fs
-      .readFileSync(absPath, "utf8")
-      .split("\n")
-      .map((line) => line.trim())
-      .filter(Boolean)
-      .map((line) => {
-        try {
-          return JSON.parse(line);
-        } catch {
-          return null;
-        }
-      })
-      .filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-function ensureDir(cwd, rel) {
-  ensureCcoDirs(cwd);
-  const abs = path.join(cwd, rel);
-  fs.mkdirSync(abs, { recursive: true });
-  return abs;
-}
-
-function appendJsonl(absPath, items) {
-  if (!items.length) {
-    if (!fs.existsSync(absPath)) fs.writeFileSync(absPath, "", "utf8");
-    return;
-  }
-  const lines = items.map((item) => JSON.stringify(item)).join("\n") + "\n";
-  fs.appendFileSync(absPath, lines, "utf8");
-}
-
-function readImportInput(absPath) {
-  const raw = fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, "").trim();
-  if (!raw) return [];
-  if (raw.startsWith("[")) {
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed : [parsed];
-  }
-  if (raw.startsWith("{")) {
-    return [JSON.parse(raw)];
-  }
-  return raw
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => JSON.parse(line));
-}
-
-function summarizeRejectedRows(rejected) {
-  const counts = {};
-  rejected.forEach((item) => {
-    item.reasons.forEach((reason) => {
-      counts[reason] = (counts[reason] || 0) + 1;
-    });
-  });
-  return Object.entries(counts).map(([reason, count]) => ({ reason, count }));
-}
-
-function redactPathValue(value) {
-  const redacted = redactPayload({ filePath: value });
-  return redacted.filePath || "[redacted-path]";
-}
-
-function sanitizeText(value, max = 240) {
-  return redactString(String(value || "").slice(0, max).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "")).trim();
-}
-
-function sanitizeBoolean(value) {
-  return value === true;
-}
-
-function sanitizeNumber(value) {
-  if (value === null || value === undefined || value === "") return null;
-  const num = Number(value);
-  return Number.isFinite(num) ? num : null;
-}
-
-function sanitizeEnum(value, allowed, fallback = null) {
-  const normalized = sanitizeText(value || "", 64).toLowerCase();
-  if (!normalized) return fallback;
-  return allowed.has(normalized) ? normalized : fallback;
-}
-
-function findForbiddenKeys(row, forbiddenKeys) {
-  return Object.keys(row || {}).filter((key) => {
-    if (!forbiddenKeys.includes(key)) return false;
-    const value = row[key];
-    return value !== null && value !== undefined && String(value).trim() !== "";
-  });
-}
-
-function findUnknownKeys(row, allowedKeys) {
-  return Object.keys(row || {}).filter((key) => !allowedKeys.has(key));
-}
-
-function baseImportReceipt(contract, sourceFile, accepted, rejected, outputRel, itemContract) {
-  return {
-    contract,
-    schemaVersion: 1,
-    createdAt: nowIso(),
-    sourceFile: redactPathValue(sourceFile),
-    sourceFileHash: sha256(sourceFile),
-    acceptedCount: accepted.length,
-    rejectedCount: rejected.length,
-    rejectedReasonSummary: summarizeRejectedRows(rejected),
-    outputPath: outputRel,
-    itemContract,
-    redacted: true,
-  };
-}
-
-function normalizeFeedbackRow(row, index) {
-  const rejected = [];
-  if (!row || typeof row !== "object" || Array.isArray(row)) {
-    return { ok: false, reasons: ["row_not_object"], index };
-  }
-
-  const forbidden = findForbiddenKeys(row, FEEDBACK_FORBIDDEN_KEYS);
-  if (forbidden.length) rejected.push("forbidden_feedback_field");
-
-  const unknown = findUnknownKeys(row, FEEDBACK_ALLOWED_KEYS);
-  if (unknown.length) rejected.push("unknown_feedback_field");
-
-  const sourceType = sanitizeText(row.sourceType || "manual_import", 48);
-  const severity = sanitizeText(row.severity || "medium", 16).toLowerCase();
-  const quoteSummary = sanitizeText(row.quoteSummary || "", 240);
-  const theme = sanitizeText(row.theme || row.issueCategory || "", 64);
-  const issueCategory = sanitizeText(row.issueCategory || row.theme || "other", 64);
-
-  if (!quoteSummary) rejected.push("quote_summary_required");
-  if (!theme) rejected.push("theme_required");
-  if (!["low", "medium", "high", "blocker"].includes(severity)) rejected.push("invalid_severity");
-
-  if (rejected.length) {
-    return { ok: false, reasons: rejected, index };
-  }
-
-  const simulated = sanitizeBoolean(row.simulated) || sourceType.toLowerCase().includes("sim");
-
-  return {
-    ok: true,
-    value: {
-      contract: FEEDBACK_ITEM_CONTRACT,
-      schemaVersion: 1,
-      importedAt: nowIso(),
-      sourceType,
-      date: sanitizeText(row.date || nowIso(), 40),
-      persona: sanitizeText(row.persona || "unknown", 48) || "unknown",
-      segment: sanitizeText(row.segment || "unknown", 64) || "unknown",
-      theme,
-      severity,
-      quoteSummary,
-      issueCategory,
-      activationStage: sanitizeText(row.activationStage || "unknown", 48) || "unknown",
-      trustConcern: sanitizeBoolean(row.trustConcern),
-      pricingConcern: sanitizeBoolean(row.pricingConcern),
-      simulated,
-      redacted: true,
-    },
-  };
-}
-
-function normalizeTokenCostRow(row, index) {
-  const rejected = [];
-  if (!row || typeof row !== "object" || Array.isArray(row)) {
-    return { ok: false, reasons: ["row_not_object"], index };
-  }
-
-  const forbidden = findForbiddenKeys(row, TOKEN_COST_FORBIDDEN_KEYS);
-  if (forbidden.length) rejected.push("forbidden_token_cost_field");
-
-  const unknown = findUnknownKeys(row, TOKEN_COST_ALLOWED_KEYS);
-  if (unknown.length) rejected.push("unknown_token_cost_field");
-
-  const sourceType = sanitizeText(row.sourceType || "manual_import", 48);
-  const capturedAt = sanitizeText(row.capturedAt || nowIso(), 40);
-  const inputTokens = sanitizeNumber(row.inputTokens != null ? row.inputTokens : row.promptTokens);
-  const outputTokens = sanitizeNumber(row.outputTokens != null ? row.outputTokens : row.completionTokens);
-  const totalTokens = sanitizeNumber(row.totalTokens != null ? row.totalTokens : ((inputTokens || 0) + (outputTokens || 0)));
-  const estimatedCostUsd = sanitizeNumber(row.estimatedCostUsd);
-  const measuredCostUsd = sanitizeNumber(row.measuredCostUsd);
-  const costMicros = sanitizeNumber(row.costMicros);
-  const currency = sanitizeText(row.currency || (estimatedCostUsd != null || measuredCostUsd != null || costMicros != null ? "USD" : ""), 8);
-  const tool = sanitizeText(row.tool || "unknown", 48) || "unknown";
-  const taskType = sanitizeText(row.taskType || "unknown", 48) || "unknown";
-  const provider = sanitizeText(row.provider || row.modelProvider || "unknown", 24) || "unknown";
-  const modelFamily = sanitizeText(row.modelFamily || row.modelName || "unknown", 48) || "unknown";
-  const notesCategory = sanitizeText(row.notesCategory || "general", 32) || "general";
-  const explicitMode = sanitizeEnum(row.evidenceMode, new Set(["measured", "estimated", "heuristic", "missing"]), null);
-  const explicitConfidence = sanitizeEnum(row.confidence, new Set(["measured", "estimated", "heuristic", "missing"]), null);
-  const estimatedOnly = sanitizeBoolean(row.estimatedOnly);
-  const heuristic = sanitizeBoolean(row.heuristic);
-  const hasMeasuredCost = measuredCostUsd !== null || costMicros !== null;
-  const hasEstimatedCost = estimatedCostUsd !== null;
-  const hasTokenTotals = totalTokens !== null;
-
-  if (totalTokens === null) rejected.push("token_fields_required");
-  if (!hasMeasuredCost && !hasEstimatedCost) rejected.push("cost_fields_missing");
-
-  let evidenceMode = explicitMode;
-  if (!evidenceMode) {
-    if (heuristic) evidenceMode = "heuristic";
-    else if (hasMeasuredCost && hasTokenTotals && !estimatedOnly) evidenceMode = "measured";
-    else if (hasEstimatedCost && hasTokenTotals) evidenceMode = "estimated";
-    else if (hasTokenTotals) evidenceMode = "heuristic";
-    else evidenceMode = "missing";
-  }
-
-  if (evidenceMode === "measured" && !hasMeasuredCost) rejected.push("measured_cost_required");
-  if (evidenceMode === "estimated" && !hasMeasuredCost && !hasEstimatedCost) rejected.push("estimated_cost_required");
-
-  const hardRejectReasons = rejected.filter((reason) => reason !== "cost_fields_missing");
-  if (hardRejectReasons.length) {
-    return { ok: false, reasons: rejected, index };
-  }
-
-  let confidence = explicitConfidence;
-  if (!confidence) {
-    if (evidenceMode === "measured") confidence = "measured";
-    else if (evidenceMode === "estimated") confidence = "estimated";
-    else if (evidenceMode === "heuristic") confidence = "heuristic";
-    else confidence = "missing";
-  }
-
-  return {
-    ok: true,
-    value: {
-      contract: TOKEN_COST_ITEM_CONTRACT,
-      schemaVersion: 1,
-      importedAt: nowIso(),
-      sourceType,
-      capturedAt,
-      runIdHash: row.runId ? sha256(row.runId) : null,
-      tool,
-      taskType,
-      provider,
-      modelFamily,
-      modelProvider: provider,
-      modelName: modelFamily,
-      inputTokens,
-      outputTokens,
-      promptTokens: inputTokens,
-      completionTokens: outputTokens,
-      totalTokens,
-      estimatedCostUsd,
-      measuredCostUsd,
-      costMicros,
-      currency: currency || null,
-      evidenceMode,
-      confidence,
-      notesCategory,
-      cacheHit: sanitizeBoolean(row.cacheHit),
-      estimatedOnly,
-      heuristic: heuristic || evidenceMode === "heuristic",
-      redacted: true,
-    },
-    warnings: rejected,
-  };
-}
-
-function importFeedbackEvidence(cwd, sourceFile) {
-  const sourceAbs = path.resolve(sourceFile);
-  const evaluated = evaluateFeedbackRows(sourceAbs);
-  const accepted = evaluated.accepted;
-  const rejected = evaluated.rejected;
-
-  ensureDir(cwd, FEEDBACK_EVIDENCE_DIR_REL);
-  appendJsonl(path.join(cwd, FEEDBACK_EVIDENCE_JSONL_REL), accepted);
-
-  const receipt = {
-    ...baseImportReceipt(
-      "avorelo.feedbackEvidenceImport.v1",
-      sourceAbs,
-      accepted,
-      rejected,
-      FEEDBACK_EVIDENCE_JSONL_REL,
-      FEEDBACK_ITEM_CONTRACT
-    ),
-    safeNextActions: accepted.length
-      ? ["Run: node bin/avorelo feedback insights --json"]
-      : ["Fix rejected rows, then rerun: node bin/avorelo feedback import --file <path> --json"],
-  };
-  fs.writeFileSync(path.join(cwd, FEEDBACK_IMPORT_RECEIPT_REL), JSON.stringify(receipt, null, 2), "utf8");
-  return receipt;
-}
-
-function evaluateFeedbackRows(sourceAbs) {
-  const rows = readImportInput(sourceAbs);
-  const accepted = [];
-  const rejected = [];
-  rows.forEach((row, index) => {
-    const normalized = normalizeFeedbackRow(row, index);
-    if (normalized.ok) accepted.push(normalized.value);
-    else rejected.push({ index, reasons: normalized.reasons });
-  });
-  return { rows, accepted, rejected };
-}
-
-function validateFeedbackEvidence(cwd, sourceFile) {
-  const sourceAbs = path.resolve(sourceFile);
-  const evaluated = evaluateFeedbackRows(sourceAbs);
-  return {
-    contract: FEEDBACK_VALIDATION_CONTRACT,
-    schemaVersion: 1,
-    createdAt: nowIso(),
-    sourceFile: redactPathValue(sourceAbs),
-    sourceFileHash: sha256(sourceAbs),
-    acceptedCount: evaluated.accepted.length,
-    rejectedCount: evaluated.rejected.length,
-    rejectedReasonSummary: summarizeRejectedRows(evaluated.rejected),
-    outputPath: FEEDBACK_EVIDENCE_JSONL_REL,
-    writesPerformed: false,
-    itemContract: FEEDBACK_ITEM_CONTRACT,
-    safeNextActions: evaluated.accepted.length > 0 && evaluated.rejected.length === 0
-      ? [
-          "Run: node bin/avorelo feedback import --file <redacted-json-or-jsonl> --json",
-          "Run: node bin/avorelo feedback insights --json",
-        ]
-      : [
-          "Run: node bin/avorelo feedback intake-pack --json",
-          "Fix rejected rows, then rerun: node bin/avorelo feedback validate --file <path> --json",
-        ],
-    redacted: true,
-  };
-}
-
-function buildFeedbackIntakePackReadme() {
-  return [
-    "# Design Partner Feedback Intake Pack",
-    "",
-    "Use this pack to collect redacted design-partner feedback without storing raw transcripts, raw prompts, raw code, secrets, or sensitive paths.",
-    "",
-    "## Safe flow",
-    "",
-    "1. Capture short redacted summaries only.",
-    "2. Use the template in `design-partner-feedback-template.md` to structure each row.",
-    "3. Validate your prepared file:",
-    "   `node bin/avorelo feedback validate --file [redacted-json-or-jsonl] --json`",
-    "4. Import only after validation is clean:",
-    "   `node bin/avorelo feedback import --file [redacted-json-or-jsonl] --json`",
-    "5. Rebuild readiness summaries:",
-    "   `node bin/avorelo feedback insights --json`",
-    "",
-    "## What counts",
-    "",
-    "- real dogfood or design-partner observations",
-    "- redacted issue summaries",
-    "- activation stage, trust concern, and pricing concern metadata",
-    "",
-    "## What does not count",
-    "",
-    "- invented feedback",
-    "- simulated rows for readiness scoring",
-    "- raw interview transcripts",
-    "- raw customer quotes with sensitive data",
-  ].join("\n");
-}
-
-function buildFeedbackIntakeTemplate() {
-  return [
-    "# Design Partner Feedback Template",
-    "",
-    "Create a JSON or JSONL file using rows like this:",
-    "",
-    "```json",
-    "{",
-    '  "sourceType": "design_partner",',
-    '  "date": "2026-05-18",',
-    '  "persona": "developer",',
-    '  "segment": "agency",',
-    '  "theme": "install_confusion",',
-    '  "severity": "high",',
-    '  "quoteSummary": "Needed a clearer first-run install path after the initial setup.",',
-    '  "issueCategory": "activation",',
-    '  "activationStage": "first_run",',
-    '  "trustConcern": true,',
-    '  "pricingConcern": false,',
-    '  "simulated": false',
-    "}",
-    "```",
-    "",
-    "Required fields:",
-    "",
-    "- `sourceType`",
-    "- `theme`",
-    "- `severity`",
-    "- `quoteSummary`",
-    "",
-    "Recommended fields:",
-    "",
-    "- `segment`",
-    "- `issueCategory`",
-    "- `activationStage`",
-    "- `trustConcern`",
-    "- `pricingConcern`",
-    "",
-    "Never include raw transcripts, file paths, code, prompts, secrets, or command output.",
-  ].join("\n");
-}
-
-function buildFeedbackIntakeChecklist() {
-  return [
-    "# Redaction Checklist",
-    "",
-    "Before importing any feedback file, confirm:",
-    "",
-    "- no raw partner names or emails",
-    "- no raw company-private text",
-    "- no raw prompts",
-    "- no raw code",
-    "- no secrets or API keys",
-    "- no command output",
-    "- no Windows, Unix, or repo-local file paths",
-    "- no stack traces",
-    "- only short redacted quote summaries",
-    "",
-    "If you cannot safely summarize a note, leave it out until it can be redacted.",
-  ].join("\n");
-}
-
-function generateFeedbackIntakePack(cwd) {
-  ensureDir(cwd, FEEDBACK_INTAKE_PACK_DIR_REL);
-  fs.writeFileSync(path.join(cwd, FEEDBACK_INTAKE_PACK_README_REL), buildFeedbackIntakePackReadme(), "utf8");
-  fs.writeFileSync(path.join(cwd, FEEDBACK_INTAKE_PACK_TEMPLATE_REL), buildFeedbackIntakeTemplate(), "utf8");
-  fs.writeFileSync(path.join(cwd, FEEDBACK_INTAKE_PACK_CHECKLIST_REL), buildFeedbackIntakeChecklist(), "utf8");
-
-  const receipt = {
-    contract: FEEDBACK_INTAKE_PACK_CONTRACT,
-    schemaVersion: 1,
-    createdAt: nowIso(),
-    status: "ready",
-    outputDir: FEEDBACK_INTAKE_PACK_DIR_REL,
-    files: [
-      { id: "readme", path: FEEDBACK_INTAKE_PACK_README_REL, purpose: "safe intake steps" },
-      { id: "template", path: FEEDBACK_INTAKE_PACK_TEMPLATE_REL, purpose: "structured field template" },
-      { id: "checklist", path: FEEDBACK_INTAKE_PACK_CHECKLIST_REL, purpose: "redaction checklist" },
-    ],
-    safeNextActions: [
-      "Run: node bin/avorelo feedback validate --file <redacted-json-or-jsonl> --json",
-      "Run: node bin/avorelo feedback import --file <redacted-json-or-jsonl> --json",
-      "Run: node bin/avorelo feedback insights --json",
-    ],
-    noRawFeedbackRequested: true,
-    noPublicLaunchClaim: true,
-    redacted: true,
-  };
-  fs.writeFileSync(path.join(cwd, FEEDBACK_INTAKE_PACK_RECEIPT_REL), JSON.stringify(receipt, null, 2), "utf8");
-  return receipt;
-}
-
-function importTokenCostEvidence(cwd, sourceFile) {
-  const sourceAbs = path.resolve(sourceFile);
-  const evaluated = evaluateTokenCostRows(sourceAbs);
-  const accepted = evaluated.accepted;
-  const rejected = evaluated.rejected;
-  const warnings = evaluated.warnings;
-
-  ensureDir(cwd, TOKEN_COST_EVIDENCE_DIR_REL);
-  appendJsonl(path.join(cwd, TOKEN_COST_EVIDENCE_JSONL_REL), accepted);
-  const summary = writeTokenCostEvidenceSummary(cwd, buildTokenCostEvidenceSummary(cwd));
-
-  const receipt = {
-    ...baseImportReceipt(
-      "avorelo.tokenCostEvidenceImport.v1",
-      sourceAbs,
-      accepted,
-      rejected,
-      TOKEN_COST_EVIDENCE_JSONL_REL,
-      TOKEN_COST_ITEM_CONTRACT
-    ),
-    warningCount: warnings.length,
-    warningReasonSummary: summarizeRejectedRows(warnings),
-    summary,
-    safeNextActions: accepted.length
-      ? ["Run: node bin/avorelo token-cost summary --json", "Run: node bin/avorelo token-cost --json"]
-      : ["Provide token totals and cost fields, then rerun: node bin/avorelo token-cost import --file <path> --json"],
-    redacted: true,
-  };
-  fs.writeFileSync(path.join(cwd, TOKEN_COST_IMPORT_RECEIPT_REL), JSON.stringify(receipt, null, 2), "utf8");
-  return receipt;
-}
-
-function evaluateTokenCostRows(sourceAbs) {
-  const rows = readImportInput(sourceAbs);
-  const accepted = [];
-  const rejected = [];
-  const warnings = [];
-  rows.forEach((row, index) => {
-    const normalized = normalizeTokenCostRow(row, index);
-    if (normalized.ok) {
-      accepted.push(normalized.value);
-      if (normalized.warnings && normalized.warnings.length) {
-        warnings.push({ index, reasons: normalized.warnings });
-      }
-    } else {
-      rejected.push({ index, reasons: normalized.reasons });
-    }
-  });
-  return { rows, accepted, rejected, warnings };
-}
-
-function validateTokenCostEvidence(cwd, sourceFile) {
-  const sourceAbs = path.resolve(sourceFile);
-  const evaluated = evaluateTokenCostRows(sourceAbs);
-  return {
-    contract: TOKEN_COST_VALIDATION_CONTRACT,
-    schemaVersion: 1,
-    createdAt: nowIso(),
-    sourceFile: redactPathValue(sourceAbs),
-    sourceFileHash: sha256(sourceAbs),
-    acceptedCount: evaluated.accepted.length,
-    rejectedCount: evaluated.rejected.length,
-    warningCount: evaluated.warnings.length,
-    rejectedReasonSummary: summarizeRejectedRows(evaluated.rejected),
-    warningReasonSummary: summarizeRejectedRows(evaluated.warnings),
-    outputPath: TOKEN_COST_EVIDENCE_JSONL_REL,
-    writesPerformed: false,
-    itemContract: TOKEN_COST_ITEM_CONTRACT,
-    safeNextActions: evaluated.accepted.length > 0 && evaluated.rejected.length === 0
-      ? [
-          "Run: node bin/avorelo token-cost import --file <redacted-json-or-jsonl> --json",
-          "Run: node bin/avorelo token-cost summary --json",
-        ]
-      : [
-          "Fix rejected rows, then rerun: node bin/avorelo token-cost validate --file <path> --json",
-          "Run: node bin/avorelo token-cost summary --json after importing clean rows",
-        ],
-    redacted: true,
-  };
-}
-
-function summarizeAvailableFields(rows, fields) {
-  return fields.filter((field) => rows.some((row) => row[field] !== null && row[field] !== undefined && row[field] !== ""));
-}
-
-function deriveStoredTokenCostEvidenceMode(row) {
-  if (!row || typeof row !== "object") return "missing";
-  if (row.evidenceMode) return row.evidenceMode;
-  const totalTokens = row.totalTokens;
-  const hasMeasuredCost = typeof row.measuredCostUsd === "number" || typeof row.costMicros === "number";
-  const hasEstimatedCost = typeof row.estimatedCostUsd === "number";
-  if (row.heuristic === true) return "heuristic";
-  if (typeof totalTokens === "number" && hasMeasuredCost && row.estimatedOnly !== true) return "measured";
-  if (typeof totalTokens === "number" && (hasEstimatedCost || hasMeasuredCost)) return "estimated";
-  if (typeof totalTokens === "number") return "heuristic";
-  return "missing";
-}
-
-function buildTokenCostEvidenceSummary(cwd) {
-  const importedRows = readImportedTokenCostEvidence(cwd);
-  const capturedRows = readCapturedTokenCostEvidence(cwd);
-  const rows = [...capturedRows, ...importedRows];
-  const measuredRows = rows.filter((row) =>
-    row &&
-    row.redacted === true &&
-    deriveStoredTokenCostEvidenceMode(row) === "measured" &&
-    typeof row.totalTokens === "number" &&
-    (typeof row.measuredCostUsd === "number" || typeof row.costMicros === "number")
-  );
-  const estimatedRows = rows.filter((row) =>
-    row &&
-    row.redacted === true &&
-    deriveStoredTokenCostEvidenceMode(row) === "estimated" &&
-    typeof row.totalTokens === "number" &&
-    (typeof row.estimatedCostUsd === "number" || typeof row.measuredCostUsd === "number" || typeof row.costMicros === "number")
-  );
-  const heuristicRows = rows.filter((row) =>
-    row &&
-    row.redacted === true &&
-    (deriveStoredTokenCostEvidenceMode(row) === "heuristic" || (typeof row.totalTokens === "number" && typeof row.measuredCostUsd !== "number" && typeof row.costMicros !== "number" && typeof row.estimatedCostUsd !== "number"))
-  );
-
-  let evidenceMode = "missing";
-  if (measuredRows.length > 0) evidenceMode = "measured";
-  else if (estimatedRows.length > 0) evidenceMode = "estimated";
-  else if (heuristicRows.length > 0) evidenceMode = "heuristic";
-
-  const tokenFieldsAvailable = summarizeAvailableFields(rows, ["inputTokens", "outputTokens", "promptTokens", "completionTokens", "totalTokens"]);
-  const costFieldsAvailable = summarizeAvailableFields(rows, ["estimatedCostUsd", "measuredCostUsd", "costMicros", "currency"]);
-  const sourceTypes = Array.from(new Set(rows.map((row) => row && row.sourceType).filter(Boolean)));
-  const tools = Array.from(new Set(rows.map((row) => row && row.tool).filter(Boolean)));
-
-  const missingEvidence = [];
-  if (rows.length === 0) missingEvidence.push("No local token/cost evidence rows have been captured or imported.");
-  if (measuredRows.length === 0) missingEvidence.push("No redacted measured token/cost usage samples are available.");
-  if (tokenFieldsAvailable.length === 0) missingEvidence.push("No token fields are available in token/cost evidence.");
-  if (costFieldsAvailable.length === 0) missingEvidence.push("No cost fields are available in token/cost evidence.");
-
-  const safeNextActions = [];
-  if (rows.length === 0) {
-    safeNextActions.push("Run: node bin/avorelo token-cost capture --json");
-    safeNextActions.push("Run: node bin/avorelo token-cost validate --file <redacted-json-or-jsonl> --json");
-    safeNextActions.push("Run: node bin/avorelo token-cost import --file <redacted-json-or-jsonl> --json");
-  } else if (measuredRows.length === 0) {
-    safeNextActions.push("Run: node bin/avorelo token-cost capture --json after a real local task with runtime attribution.");
-    safeNextActions.push("Import measured token/cost usage rows with token totals and measured cost fields.");
-    safeNextActions.push("Run: node bin/avorelo token-cost import --file <redacted-json-or-jsonl> --json");
-  }
-  safeNextActions.push("Run: node bin/avorelo token-cost summary --json");
-
-  return {
-    contract: TOKEN_COST_SUMMARY_CONTRACT,
-    schemaVersion: 1,
-    createdAt: nowIso(),
-    status: evidenceMode === "measured" ? "pass" : evidenceMode === "missing" ? "warn" : "warn",
-    evidenceAvailable: rows.length > 0,
-    evidenceMode,
-    realUsageSamplesCount: measuredRows.length,
-    capturedUsageSamplesCount: capturedRows.filter((row) => deriveStoredTokenCostEvidenceMode(row) === "measured").length,
-    importedUsageSamplesCount: importedRows.filter((row) => deriveStoredTokenCostEvidenceMode(row) === "measured").length,
-    source: {
-      sourceTypes,
-      tools,
-      importedEvidencePath: TOKEN_COST_EVIDENCE_JSONL_REL,
-      captureEvidencePath: TOKEN_COST_CAPTURE_JSONL_REL,
-      importReceiptPath: TOKEN_COST_IMPORT_RECEIPT_REL,
-      captureReceiptPath: TOKEN_COST_CAPTURE_RECEIPT_REL,
-    },
-    costFieldsAvailable,
-    tokenFieldsAvailable,
-    confidence: evidenceMode === "measured" ? "measured" : evidenceMode === "estimated" ? "estimated" : evidenceMode === "heuristic" ? "heuristic" : "missing",
-    missingEvidence,
-    safeNextActions,
-    noSavingsClaimUnlessMeasured: true,
-    redacted: true,
-  };
-}
-
-function writeTokenCostEvidenceSummary(cwd, summary) {
-  ensureDir(cwd, TOKEN_COST_EVIDENCE_DIR_REL);
-  fs.writeFileSync(path.join(cwd, TOKEN_COST_SUMMARY_REL), JSON.stringify(summary, null, 2), "utf8");
-  return summary;
-}
-
-function readTokenCostEvidenceSummary(cwd) {
-  return safeReadJson(path.join(cwd, TOKEN_COST_SUMMARY_REL));
-}
-
-function readImportedFeedbackEvidence(cwd) {
-  return safeReadJsonl(path.join(cwd, FEEDBACK_EVIDENCE_JSONL_REL));
-}
-
-function readImportedTokenCostEvidence(cwd) {
-  return safeReadJsonl(path.join(cwd, TOKEN_COST_EVIDENCE_JSONL_REL));
-}
-
-function readCapturedTokenCostEvidence(cwd) {
-  return safeReadJsonl(path.join(cwd, TOKEN_COST_CAPTURE_JSONL_REL));
-}
-
-module.exports = {
-  FEEDBACK_EVIDENCE_DIR_REL,
-  FEEDBACK_EVIDENCE_JSONL_REL,
-  FEEDBACK_IMPORT_RECEIPT_REL,
-  FEEDBACK_INTAKE_PACK_DIR_REL,
-  FEEDBACK_INTAKE_PACK_RECEIPT_REL,
-  FEEDBACK_INTAKE_PACK_README_REL,
-  FEEDBACK_INTAKE_PACK_TEMPLATE_REL,
-  FEEDBACK_INTAKE_PACK_CHECKLIST_REL,
-  TOKEN_COST_EVIDENCE_DIR_REL,
-  TOKEN_COST_EVIDENCE_JSONL_REL,
-  TOKEN_COST_CAPTURE_JSONL_REL,
-  TOKEN_COST_IMPORT_RECEIPT_REL,
-  TOKEN_COST_CAPTURE_RECEIPT_REL,
-  TOKEN_COST_SUMMARY_REL,
-  FEEDBACK_ITEM_CONTRACT,
-  FEEDBACK_VALIDATION_CONTRACT,
-  FEEDBACK_INTAKE_PACK_CONTRACT,
-  TOKEN_COST_ITEM_CONTRACT,
-  TOKEN_COST_VALIDATION_CONTRACT,
-  TOKEN_COST_SUMMARY_CONTRACT,
-  readImportedFeedbackEvidence,
-  readImportedTokenCostEvidence,
-  readCapturedTokenCostEvidence,
-  readTokenCostEvidenceSummary,
-  validateFeedbackEvidence,
-  generateFeedbackIntakePack,
-  importFeedbackEvidence,
-  importTokenCostEvidence,
-  validateTokenCostEvidence,
-  buildTokenCostEvidenceSummary,
-  writeTokenCostEvidenceSummary,
-};