avorelo 0.1.0

package/scripts/lib/release-candidate-bundle.js

@@ -0,0 +1,166 @@
+"use strict";
+
+// ── Release Candidate Bundle ──────────────────────────────────────────────────
+// Contract: avorelo.releaseCandidateBundle.v1
+// Assembles a local release candidate bundle from summaries and refs only.
+// No raw prompts, raw feedback, raw source code, secrets, or raw configs.
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.releaseCandidateBundle.v1";
+const SCHEMA_VERSION = 1;
+const BUNDLE_DIR_REL = ".claude/cco/orchestration/full-readiness";
+const ARTIFACT_REL = BUNDLE_DIR_REL + "/latest-release-candidate-bundle.json";
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch { return null; }
+}
+
+function pick(obj, fields) {
+  if (!obj) return null;
+  var out = {};
+  fields.forEach(function(f) { if (obj[f] !== undefined) out[f] = obj[f]; });
+  return out;
+}
+
+function collectReleaseCandidateArtifacts(cwd, options) {
+  options = options || {};
+  function read(rel) { return safeReadJson(path.join(cwd, rel)); }
+  return {
+    gate: read(".claude/cco/orchestration/full-readiness/latest-gate.json"),
+    evidenceClosure: read(".claude/cco/orchestration/full-readiness/latest-evidence-closure.json"),
+    knownLimitations: read(".claude/cco/orchestration/full-readiness/latest-known-limitations.json"),
+    externalUserSim: read(".claude/cco/orchestration/full-readiness/latest-external-user-simulation.json"),
+    prelaunchIntel: read(".claude/cco/orchestration/prelaunch-intelligence/latest-intelligence.json"),
+    feedbackIntel: read(".claude/cco/orchestration/prelaunch-intelligence/latest-feedback-intelligence.json"),
+    installJourney: read(".claude/cco/orchestration/prelaunch-intelligence/latest-install-journey.json"),
+    tokenCost: read(".claude/cco/orchestration/prelaunch-intelligence/latest-token-cost-intelligence.json"),
+    tokenCostCapture: read(".claude/cco/evidence/token-cost/latest-capture.json"),
+    tokenCostEvidence: read(".claude/cco/evidence/token-cost/summary.json"),
+    proofOutcomeEvidence: read(".claude/cco/orchestration/seamless-outcome/latest-proof-outcome-evidence.json"),
+    mcpPolicy: read(".claude/cco/orchestration/mcp-tool-governance/latest-policy.json"),
+    launchHardening: read(".claude/cco/orchestration/launch-hardening/latest-gate.json"),
+    supportBundle: read(".claude/cco/support/latest-support-bundle.json"),
+    companyLoop: read(".claude/cco/orchestration/company-loop/latest-report.json"),
+  };
+}
+
+function buildReleaseCandidateBundle(cwd, options) {
+  options = options || {};
+  var a = collectReleaseCandidateArtifacts(cwd, options);
+
+  var gateSummary = pick(a.gate, ["contract", "status", "releaseCandidateStatus", "score", "decision", "recommendedNextPr", "safeNextAction", "noPublicLaunchClaim", "noReleaseReadyClaimUnlessPassed", "redacted"]);
+  if (gateSummary && a.gate) { gateSummary.blockerCount = (a.gate.blockers || []).length; gateSummary.warningCount = (a.gate.warnings || []).length; gateSummary.passCount = (a.gate.passes || []).length; }
+
+  var evidenceClosureSummary = pick(a.evidenceClosure, ["contract", "status", "evidencePresentCount", "evidenceMissingCount", "totalChecked", "nextAction", "redacted"]);
+  var knownLimitationsSummary = pick(a.knownLimitations, ["contract", "totalLimitations", "blockerLimitationsCount", "warnLimitationsCount", "infoLimitationsCount", "overallImpact", "redacted"]);
+  var externalUserSimSummary = pick(a.externalUserSim, ["contract", "status", "totalScenarios", "passed", "warned", "blocked", "redacted"]);
+
+  var prelaunchIntelSummary = pick(a.prelaunchIntel, ["contract", "status", "score", "noPublicLaunchClaim", "noReleaseReadyClaim", "redacted"]);
+  if (prelaunchIntelSummary && a.prelaunchIntel) {
+    prelaunchIntelSummary.recommendation = a.prelaunchIntel.recommendedNextPr && a.prelaunchIntel.recommendedNextPr.recommendation || null;
+    prelaunchIntelSummary.missingEvidenceCount = (a.prelaunchIntel.missingEvidence || []).length;
+  }
+
+  var feedbackIntelSummary = pick(a.feedbackIntel, ["contract", "status", "readinessStatus", "score", "redacted"]);
+  if (feedbackIntelSummary && a.feedbackIntel) {
+    feedbackIntelSummary.qualifiedFeedbackItemsCount = a.feedbackIntel.qualifiedFeedbackItemsCount || 0;
+    feedbackIntelSummary.topFriction = a.feedbackIntel.topFriction || null;
+  }
+
+  var installJourneySummary = pick(a.installJourney, ["contract", "status", "stepsComplete", "totalSteps", "redacted"]);
+  var tokenCostSummary = pick(a.tokenCost, ["contract", "status", "readinessStatus", "evidenceLevel", "evidenceMode", "noExactSavingsClaim", "redacted"]);
+  if (tokenCostSummary && a.tokenCost) {
+    tokenCostSummary.realUsageSamplesCount = a.tokenCost.realUsageSamplesCount || 0;
+    tokenCostSummary.capturedUsageSamplesCount = a.tokenCost.capturedUsageSamplesCount || a.tokenCostCapture && a.tokenCostCapture.realUsageSamplesCount || 0;
+    tokenCostSummary.confidence = a.tokenCost.confidence || "missing";
+  }
+  if (tokenCostSummary && a.tokenCostEvidence) {
+    tokenCostSummary.evidenceMode = a.tokenCostEvidence.evidenceMode || tokenCostSummary.evidenceMode || "missing";
+    tokenCostSummary.noSavingsClaimUnlessMeasured = a.tokenCostEvidence.noSavingsClaimUnlessMeasured === true;
+  }
+  var proofOutcomeSummary = pick(a.proofOutcomeEvidence, ["contract", "status", "latestProofAvailable", "realTaskProofCount", "proofQuality", "simulatedProofDetected", "redacted"]);
+  var mcpSummary = pick(a.mcpPolicy, ["contract", "status", "note", "redacted"]);
+  var hardeningSummary = pick(a.launchHardening, ["contract", "status", "redacted"]);
+  if (hardeningSummary && a.launchHardening) { hardeningSummary.pass = a.launchHardening.summary && a.launchHardening.summary.pass || 0; hardeningSummary.warn = a.launchHardening.summary && a.launchHardening.summary.warn || 0; hardeningSummary.fail = a.launchHardening.summary && a.launchHardening.summary.fail || 0; }
+
+  var supportSummary = pick(a.supportBundle, ["contract", "redacted", "artifactPath"]);
+  if (supportSummary && a.supportBundle) supportSummary.intelligenceSummaryStatus = a.supportBundle.intelligenceSummary && a.supportBundle.intelligenceSummary.status || null;
+
+  var failureRecoverySummary = a.supportBundle && a.supportBundle.failureRecoveryReadinessSummary || null;
+  var hookSafetyBoundarySummary = a.supportBundle && a.supportBundle.hookSafetyBoundarySummary || null;
+  var installAiReadinessSummary = a.supportBundle && a.supportBundle.installAiReadinessSummary || null;
+
+  var companyLoopSummary = pick(a.companyLoop, ["contract", "redacted"]);
+  if (companyLoopSummary && a.companyLoop) { companyLoopSummary.recommendedNextPr = (a.companyLoop.nextPrRecommendation && a.companyLoop.nextPrRecommendation.recommendedNextPr) || a.companyLoop.recommendedNextPr || null; companyLoopSummary.confidence = a.companyLoop.nextPrRecommendation && a.companyLoop.nextPrRecommendation.confidence || null; }
+
+  var bundleStatus = a.gate && a.gate.releaseCandidateStatus || "insufficient_data";
+  var overallStatus = a.gate && a.gate.status || "insufficient_data";
+
+  // Activation distribution readiness summary (PR #149)
+  var activationDistributionSummary = null;
+  try {
+    var adrMod = require("./activation-distribution-readiness");
+    var adrSurface = adrMod.buildActivationDistributionSurface(cwd, {});
+    if (adrSurface.status !== "not_available") {
+      activationDistributionSummary = { status: adrSurface.status, score: adrSurface.score, blockerCount: adrSurface.blockerCount, warningCount: adrSurface.warningCount, noPublicLaunchClaim: true, redacted: true };
+    }
+  } catch (e) {}
+
+  // Design partner feedback summary (PR #160)
+  var designPartnerFeedbackSummary = null;
+  try {
+    var dpMod = require("./design-partner-feedback");
+    var dpSummary = dpMod.buildDesignPartnerFeedbackSummary(cwd, {});
+    designPartnerFeedbackSummary = { status: dpSummary.status, qualifiedSessionCount: dpSummary.qualifiedSessionCount, blockerCount: dpSummary.blockerCount, partnerAliasCount: dpSummary.partnerAliasCount, noPublicLaunchClaim: true, noExternalFeedbackClaim: true, redacted: true };
+  } catch (e) {}
+
+  // Public distribution truth summary (PR #161)
+  var publicDistributionSummary = null;
+  try {
+    var pdGate = safeReadJson(path.join(cwd, ".claude/cco/orchestration/public-distribution/latest-gate.json"));
+    if (pdGate) {
+      publicDistributionSummary = { status: pdGate.status, score: pdGate.score, publicInstallStatus: pdGate.publicInstallStatus, localPackageStatus: pdGate.localPackageStatus, packageContentStatus: pdGate.packageContentStatus, claimSafetyStatus: pdGate.claimSafetyStatus, provenanceStatus: pdGate.provenanceStatus, blockerCount: (pdGate.blockers || []).length, warningCount: (pdGate.warnings || []).length, recommendedNextPr: pdGate.recommendedNextPr, noPublicLaunchClaim: true, redacted: true };
+    }
+  } catch (e) {}
+
+  // Adapter technical readiness summary (PR #162)
+  var adapterTechnicalReadinessSummary = null;
+  try {
+    var adapterGate = safeReadJson(path.join(cwd, ".claude/cco/orchestration/adapter-readiness/latest-technical-gate.json"));
+    if (adapterGate) {
+      adapterTechnicalReadinessSummary = { status: adapterGate.status, score: adapterGate.score, verdict: adapterGate.verdict, blockerCount: adapterGate.blockerCount || 0, warningCount: adapterGate.warningCount || 0, browserRequired: false, noBrowserLaunch: true, noPublicLaunchClaim: true, redacted: true };
+    }
+  } catch (e) {}
+
+  var bundle = { contract: CONTRACT, schemaVersion: SCHEMA_VERSION, createdAt: nowIso(), status: overallStatus, releaseCandidateStatus: bundleStatus, fullReadinessGate: gateSummary, evidenceClosure: evidenceClosureSummary, knownLimitations: knownLimitationsSummary, externalUserSimulation: externalUserSimSummary, prelaunchIntelligence: prelaunchIntelSummary, feedbackIntelligence: feedbackIntelSummary, installJourney: installJourneySummary, tokenCostIntelligence: tokenCostSummary, proofOutcomeEvidence: proofOutcomeSummary, failureRecoveryReadiness: failureRecoverySummary, hookSafetyBoundaryReadiness: hookSafetyBoundarySummary, installAiReadiness: installAiReadinessSummary, mcpGovernance: mcpSummary, launchHardening: hardeningSummary, supportBundle: supportSummary, companyLoop: companyLoopSummary, activationDistribution: activationDistributionSummary, designPartnerFeedback: designPartnerFeedbackSummary, publicDistribution: publicDistributionSummary, adapterTechnicalReadiness: adapterTechnicalReadinessSummary, noPublicLaunchClaim: true, noReleaseReadyClaimUnlessPassed: true, rawContentExcluded: true, redacted: true };
+  try { appendProductLearningEvent(cwd, { eventName: "release_candidate_bundle_built", category: "full_readiness", status: overallStatus, releaseCandidateStatus: bundleStatus }); } catch (e) {}
+  return bundle;
+}
+
+function writeReleaseCandidateBundle(cwd, bundle) {
+  var dir = path.join(cwd, BUNDLE_DIR_REL);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(bundle, null, 2));
+  return bundle;
+}
+
+function formatReleaseCandidateBundleText(bundle, options) {
+  options = options || {};
+  var lines = [];
+  lines.push("Release candidate bundle: " + bundle.releaseCandidateStatus);
+  lines.push("Gate status: " + bundle.status);
+  if (bundle.fullReadinessGate) { lines.push("Score: " + bundle.fullReadinessGate.score); lines.push("Blockers: " + bundle.fullReadinessGate.blockerCount + ", Warnings: " + bundle.fullReadinessGate.warningCount); }
+  if (bundle.knownLimitations) lines.push("Known limitations: " + bundle.knownLimitations.totalLimitations);
+  if (bundle.fullReadinessGate && bundle.fullReadinessGate.recommendedNextPr) lines.push("Next PR: " + bundle.fullReadinessGate.recommendedNextPr);
+  lines.push(""); lines.push("Bundle contains summaries and refs only. No raw content."); lines.push("No public launch claim.");
+  return lines.join("\n");
+}
+
+module.exports = { CONTRACT, SCHEMA_VERSION, ARTIFACT_REL, buildReleaseCandidateBundle, collectReleaseCandidateArtifacts, writeReleaseCandidateBundle, formatReleaseCandidateBundleText };

package/scripts/lib/remediation.js

@@ -0,0 +1,81 @@
+"use strict";
+
+const { safeWriteJson, safeWriteText, nowIso } = require("./fsx");
+
+function toRiskClass(report) {
+  if ((report?.riskScore ?? 0) >= 80) return "high";
+  if ((report?.riskScore ?? 0) >= 45) return "medium";
+  return "low";
+}
+
+function buildPatchCandidates(report, filePath) {
+  const reasons = report?.topReasons || [];
+  if (!reasons.length) return [];
+
+  return reasons.map((reasonCode, idx) => {
+    const confidence = Math.max(0.3, 1 - idx * 0.2);
+    return {
+      patchId: `patch_${idx + 1}`,
+      reasonCode,
+      files: [filePath],
+      confidence,
+      rationale: `Suggested remediation for ${reasonCode}`,
+      recommendedOwnerAction: "Review finding, apply patch manually, and re-run /cco-audit.",
+    };
+  });
+}
+
+function validatePatchMetadata(patch) {
+  return Boolean(
+    patch &&
+      typeof patch.reasonCode === "string" &&
+      Array.isArray(patch.files) &&
+      patch.files.length > 0 &&
+      Number.isFinite(Number(patch.confidence))
+  );
+}
+
+function createRemediationJob(cwd, { sessionId, filePath, report }) {
+  const now = Date.now();
+  const jobId = `job_${now}`;
+  const riskClass = toRiskClass(report);
+  const patches = buildPatchCandidates(report, filePath).filter(validatePatchMetadata);
+
+  const patchPaths = patches.map((patch, idx) => {
+    const rel = `.claude/cco/patches/${jobId}-${idx + 1}.patch`;
+    const content = [
+      `# Patch suggestion ${idx + 1}`,
+      `# reasonCode: ${patch.reasonCode}`,
+      `# confidence: ${patch.confidence}`,
+      `# files: ${patch.files.join(",")}`,
+      `# recommendedOwnerAction: ${patch.recommendedOwnerAction}`,
+      "# TODO: apply manual remediation based on security guidance",
+      "",
+    ].join("\n");
+    safeWriteText(cwd, rel, content);
+    return rel;
+  });
+
+  const job = {
+    jobId,
+    sessionId,
+    findingIds: (report?.highlights || []).map((h) => h.id),
+    patches: patches.map((p, idx) => ({ ...p, path: patchPaths[idx] })),
+    approvalState: "suggested",
+    remediationState: "patch-suggested",
+    riskClass,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+
+  const jobPath = `.claude/cco/patches/jobs/${jobId}.json`;
+  safeWriteJson(cwd, jobPath, job);
+
+  return { job, jobPath };
+}
+
+module.exports = {
+  createRemediationJob,
+  validatePatchMetadata,
+  toRiskClass,
+};

package/scripts/lib/repo-map.js

@@ -0,0 +1,391 @@
+"use strict";
+
+// ── Repo Map / Symbol Map ─────────────────────────────────────────────────────
+//
+// Builds a concise, deterministic repo map from file metadata and safe parsing.
+// No network, no LLM, no full code dumps.
+//
+// Contract: avorelo.repoMap.v1
+//
+// Non-goals: full AST parsing, external parser dependencies, code dumping,
+//            secret/env exposure, minified/binary files.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.repoMap.v1";
+const SCHEMA_VERSION = 1;
+
+const REPO_MAP_DIR_REL = ".claude/cco/orchestration/repo-map";
+const LATEST_MAP_REL = `${REPO_MAP_DIR_REL}/latest-map.json`;
+
+// ── Exclusion patterns ────────────────────────────────────────────────────────
+
+const EXCLUDED_DIRS = new Set([
+  "node_modules", ".git", ".svn", "dist", "build", "out", ".next", ".nuxt",
+  "__pycache__", ".venv", "venv", "env", ".tox", "coverage", ".cache",
+  ".turbo", ".yarn", "vendor", "target", "bin", "obj", ".expo",
+]);
+
+const EXCLUDED_EXTENSIONS = new Set([
+  ".map", ".min.js", ".min.css", ".bundle.js",
+  ".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico", ".webp", ".avif",
+  ".woff", ".woff2", ".ttf", ".eot", ".otf",
+  ".pdf", ".zip", ".tar", ".gz", ".br", ".bz2",
+  ".exe", ".dll", ".so", ".dylib", ".bin",
+  ".lock",
+]);
+
+const SENSITIVE_FILES = new Set([
+  ".env", ".env.local", ".env.production", ".env.staging", ".env.development",
+  ".env.test", "secrets.json", "credentials.json", ".npmrc", ".netrc",
+]);
+
+const MAX_FILES = 2000;
+const MAX_FILE_BYTES_FOR_SYMBOLS = 100 * 1024; // 100 KB
+const MAX_SYMBOL_LINES = 5000;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function isExcludedDir(name) {
+  return EXCLUDED_DIRS.has(name) || name.startsWith(".");
+}
+
+function isExcludedFile(name) {
+  const lower = name.toLowerCase();
+  if (SENSITIVE_FILES.has(name) || SENSITIVE_FILES.has(lower)) return "sensitive";
+  const ext = path.extname(lower);
+  if (EXCLUDED_EXTENSIONS.has(ext)) return "excluded";
+  // Detect generated/minified by suffix pattern
+  if (lower.endsWith(".min.js") || lower.endsWith(".min.css") || lower.endsWith(".bundle.js") || lower.endsWith(".chunk.js")) return "excluded";
+  // Lock files
+  if (lower.endsWith(".lock") || lower === "package-lock.json" || lower === "pnpm-lock.yaml" || lower === "yarn.lock") return "excluded";
+  return false;
+}
+
+function isBinary(buffer) {
+  // Simple heuristic: check first 512 bytes for null bytes
+  const check = Math.min(buffer.length, 512);
+  for (let i = 0; i < check; i++) {
+    if (buffer[i] === 0) return true;
+  }
+  return false;
+}
+
+function detectWorkspaceType(cwd) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    if (pkg.workspaces) return "npm_workspaces";
+    if (fs.existsSync(path.join(cwd, "pnpm-workspace.yaml"))) return "pnpm_workspaces";
+    if (fs.existsSync(path.join(cwd, "lerna.json"))) return "lerna";
+    return "single_package";
+  } catch {}
+  try {
+    if (fs.existsSync(path.join(cwd, "Cargo.toml"))) return "rust_cargo";
+    if (fs.existsSync(path.join(cwd, "go.mod"))) return "go_module";
+    if (fs.existsSync(path.join(cwd, "pyproject.toml")) || fs.existsSync(path.join(cwd, "setup.py"))) return "python";
+  } catch {}
+  return "unknown";
+}
+
+function detectPackageScopes(cwd) {
+  const scopes = [];
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    if (pkg.workspaces) {
+      const ws = Array.isArray(pkg.workspaces) ? pkg.workspaces : (pkg.workspaces.packages || []);
+      for (const pattern of ws.slice(0, 10)) {
+        const p = pattern.replace(/\*$/, "").replace(/\/$/, "");
+        if (fs.existsSync(path.join(cwd, p))) scopes.push(p);
+      }
+    }
+  } catch {}
+  return scopes;
+}
+
+// ── Symbol extraction (safe heuristic, no AST) ───────────────────────────────
+
+function extractSymbols(content, ext) {
+  const symbols = [];
+  const lines = content.split("\n");
+  if (lines.length > MAX_SYMBOL_LINES) return symbols;
+
+  const patterns = [];
+  if ([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"].includes(ext)) {
+    patterns.push(
+      /^(?:export\s+)?(?:async\s+)?function\s+(\w+)/,
+      /^(?:export\s+)?class\s+(\w+)/,
+      /^(?:export\s+)?const\s+(\w+)\s*=/,
+      /^module\.exports\s*=\s*\{([^}]{0,200})\}/,
+      /^exports\.(\w+)\s*=/,
+    );
+  } else if ([".py"].includes(ext)) {
+    patterns.push(/^def\s+(\w+)/, /^class\s+(\w+)/);
+  } else if ([".go"].includes(ext)) {
+    patterns.push(/^func\s+(\w+)/, /^type\s+(\w+)/);
+  }
+
+  for (const line of lines.slice(0, 200)) {
+    for (const re of patterns) {
+      const m = line.match(re);
+      if (m && m[1]) {
+        const sym = m[1].slice(0, 60);
+        if (sym && !symbols.includes(sym)) symbols.push(sym);
+        if (symbols.length >= 20) return symbols;
+      }
+    }
+  }
+  return symbols;
+}
+
+// ── File walker ───────────────────────────────────────────────────────────────
+
+function walkFiles(cwd, dir, files, counts, depth = 0) {
+  if (depth > 8) return;
+  if (files.length >= MAX_FILES) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (files.length >= MAX_FILES) break;
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      if (isExcludedDir(entry.name)) continue;
+      walkFiles(cwd, path.join(dir, entry.name), files, counts, depth + 1);
+    } else if (entry.isFile()) {
+      const abs = path.join(dir, entry.name);
+      const rel = path.relative(cwd, abs).replace(/\\/g, "/");
+      const exclusionReason = isExcludedFile(entry.name);
+
+      let stat;
+      try { stat = fs.statSync(abs); } catch { continue; }
+
+      if (exclusionReason === "sensitive") {
+        counts.sensitiveExcluded++;
+        continue;
+      }
+
+      const ext = path.extname(entry.name).toLowerCase();
+
+      // Check for binary
+      try {
+        const buf = Buffer.allocUnsafe(512);
+        const fd = fs.openSync(abs, "r");
+        const read = fs.readSync(fd, buf, 0, 512, 0);
+        fs.closeSync(fd);
+        if (isBinary(buf.slice(0, read))) {
+          counts.binaryExcluded++;
+          continue;
+        }
+      } catch { continue; }
+
+      if (exclusionReason === "excluded") {
+        counts.generatedExcluded++;
+        continue;
+      }
+
+      // Check for minified (line > 1000 chars)
+      let isMinified = false;
+      if (stat.size < 10 * 1024) {
+        try {
+          const content = fs.readFileSync(abs, "utf8");
+          const firstLine = content.split("\n")[0] || "";
+          if (firstLine.length > 1000) isMinified = true;
+        } catch {}
+      } else if (stat.size > 500 * 1024) {
+        isMinified = true; // large files treated as generated
+      }
+      if (isMinified) {
+        counts.minifiedExcluded++;
+        continue;
+      }
+
+      const fileEntry = {
+        path: rel,
+        ext,
+        bytes: stat.size,
+        estimatedTokens: Math.ceil(stat.size / 4),
+      };
+
+      // Extract symbols for source files under size limit
+      if (stat.size < MAX_FILE_BYTES_FOR_SYMBOLS && [".js", ".mjs", ".ts", ".tsx", ".jsx", ".py", ".go"].includes(ext)) {
+        try {
+          const content = fs.readFileSync(abs, "utf8");
+          const syms = extractSymbols(content, ext);
+          if (syms.length > 0) fileEntry.symbols = syms;
+        } catch {}
+      }
+
+      files.push(fileEntry);
+    }
+  }
+}
+
+// ── Token count tree ──────────────────────────────────────────────────────────
+
+function buildTokenCountTree(files) {
+  const byDir = {};
+  for (const f of files) {
+    const dir = path.dirname(f.path) || ".";
+    byDir[dir] = (byDir[dir] || 0) + f.estimatedTokens;
+  }
+  return byDir;
+}
+
+// ── Main build ────────────────────────────────────────────────────────────────
+
+function buildRepoMap(cwd, options = {}) {
+  const files = [];
+  const counts = { generatedExcluded: 0, binaryExcluded: 0, minifiedExcluded: 0, sensitiveExcluded: 0 };
+
+  let status = "ready";
+  let caveats = [];
+
+  try {
+    walkFiles(cwd, cwd, files, counts);
+  } catch (e) {
+    status = "partial";
+    caveats.push(`File walk error: ${e.message}`);
+  }
+
+  if (files.length >= MAX_FILES) {
+    status = "partial";
+    caveats.push(`File count capped at ${MAX_FILES}. Map may be incomplete for large repos.`);
+  }
+
+  const tokenCountTree = buildTokenCountTree(files);
+  const totalEstimatedTokens = files.reduce((s, f) => s + f.estimatedTokens, 0);
+  const workspaceType = detectWorkspaceType(cwd);
+  const packageScopes = detectPackageScopes(cwd);
+
+  caveats.push("Token estimates are approximate (chars/4 heuristic). Actual tokenization may differ.");
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    root: cwd,
+    workspaceType,
+    packageScopes,
+    fileCount: files.length,
+    totalEstimatedTokens,
+    files,
+    symbols: files.filter((f) => f.symbols && f.symbols.length > 0).map((f) => ({ path: f.path, symbols: f.symbols })),
+    generatedExcluded: counts.generatedExcluded,
+    binaryExcluded: counts.binaryExcluded,
+    minifiedExcluded: counts.minifiedExcluded,
+    sensitiveExcluded: counts.sensitiveExcluded,
+    tokenCountTree,
+    caveats,
+    redacted: true,
+  };
+}
+
+function buildSymbolMap(cwd, options = {}) {
+  const map = buildRepoMap(cwd, options);
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: map.createdAt,
+    status: map.status,
+    symbolCount: map.symbols.length,
+    symbols: map.symbols,
+    caveats: map.caveats,
+    redacted: true,
+  };
+}
+
+function selectLikelyRelevantFiles(cwd, taskText, repoMap, options = {}) {
+  if (!taskText || !repoMap || !repoMap.files) return [];
+  const words = taskText.toLowerCase().split(/\W+/).filter((w) => w.length > 3);
+  const scored = [];
+  for (const f of repoMap.files) {
+    let score = 0;
+    const fp = f.path.toLowerCase();
+    for (const w of words) {
+      if (fp.includes(w)) score += 2;
+    }
+    if (f.symbols) {
+      for (const sym of f.symbols) {
+        for (const w of words) {
+          if (sym.toLowerCase().includes(w)) score += 3;
+        }
+      }
+    }
+    if (score > 0) scored.push({ ...f, relevanceScore: score });
+  }
+  return scored.sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, 20);
+}
+
+function writeRepoMap(cwd, map) {
+  const dir = path.join(cwd, REPO_MAP_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const abs = path.join(cwd, LATEST_MAP_REL);
+  // Write without full file content — just metadata
+  const compact = {
+    ...map,
+    files: map.files.map((f) => ({ path: f.path, ext: f.ext, bytes: f.bytes, estimatedTokens: f.estimatedTokens, symbols: f.symbols })),
+  };
+  fs.writeFileSync(abs, JSON.stringify(compact, null, 2), "utf8");
+  try {
+    appendProductLearningEvent(cwd, "repo_map_generated", {
+      fileCount: map.fileCount,
+      totalEstimatedTokens: map.totalEstimatedTokens,
+      workspaceType: map.workspaceType,
+      status: map.status,
+    });
+  } catch {}
+  return abs;
+}
+
+function buildRepoMapSurface(cwd, options = {}) {
+  const abs = path.join(cwd, LATEST_MAP_REL);
+  if (!fs.existsSync(abs)) {
+    return { status: "not_available", artifactPath: LATEST_MAP_REL };
+  }
+  try {
+    const map = JSON.parse(fs.readFileSync(abs, "utf8"));
+    return {
+      status: map.status || "unknown",
+      fileCount: map.fileCount,
+      totalEstimatedTokens: map.totalEstimatedTokens,
+      workspaceType: map.workspaceType,
+      artifactPath: LATEST_MAP_REL,
+    };
+  } catch {
+    return { status: "error", artifactPath: LATEST_MAP_REL };
+  }
+}
+
+function formatRepoMapText(map, options = {}) {
+  const lines = [`Repo Map (${map.status})`];
+  lines.push(`  Files: ${map.fileCount} | Tokens (est.): ~${map.totalEstimatedTokens}`);
+  lines.push(`  Workspace: ${map.workspaceType}`);
+  if (map.packageScopes && map.packageScopes.length) {
+    lines.push(`  Packages: ${map.packageScopes.join(", ")}`);
+  }
+  lines.push(`  Excluded: ${map.generatedExcluded} generated, ${map.binaryExcluded} binary, ${map.minifiedExcluded} minified, ${map.sensitiveExcluded} sensitive`);
+  if (map.caveats && map.caveats.length) {
+    lines.push(`  Caveat: ${map.caveats[0]}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  REPO_MAP_DIR_REL,
+  LATEST_MAP_REL,
+  buildRepoMap,
+  buildSymbolMap,
+  selectLikelyRelevantFiles,
+  writeRepoMap,
+  buildRepoMapSurface,
+  formatRepoMapText,
+};