avorelo 0.1.0

package/scripts/lib/batch-jobs.js

@@ -0,0 +1,71 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+
+const BATCH_DIR = ".claude/cco/batch/jobs";
+
+function batchPath(cwd, jobId) {
+  return path.join(cwd, BATCH_DIR, `${jobId}.json`);
+}
+
+function createBatchJob(cwd, input) {
+  const ts = Date.now();
+  const jobId = String(input?.jobId || `batch-${ts}`);
+  const job = {
+    version: 1,
+    jobId,
+    provider: input?.provider || "claude",
+    mode: input?.mode || "headless",
+    taskType: input?.taskType || "general",
+    inputRef: input?.inputRef || null,
+    status: "queued",
+    costEstimate: Number(input?.costEstimate || 0),
+    resultRef: null,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+
+  const abs = batchPath(cwd, jobId);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, JSON.stringify(job, null, 2), "utf8");
+  return job;
+}
+
+function updateBatchJob(cwd, jobId, patch) {
+  const abs = batchPath(cwd, jobId);
+  if (!fs.existsSync(abs)) return null;
+  const current = JSON.parse(fs.readFileSync(abs, "utf8"));
+  const next = {
+    ...current,
+    ...(patch || {}),
+    updatedAt: nowIso(),
+  };
+  fs.writeFileSync(abs, JSON.stringify(next, null, 2), "utf8");
+  return next;
+}
+
+function listBatchJobs(cwd) {
+  const dir = path.join(cwd, BATCH_DIR);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => Date.parse(b.updatedAt || 0) - Date.parse(a.updatedAt || 0));
+}
+
+module.exports = {
+  BATCH_DIR,
+  createBatchJob,
+  updateBatchJob,
+  listBatchJobs,
+};

package/scripts/lib/brain-pack.js

@@ -0,0 +1,578 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson, safeWriteText } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const BRAIN_PACK_CONTRACT = "avorelo.brainPack.v1";
+const BRAIN_PACK_SCHEMA_VERSION = 1;
+const BRAIN_PACK_LATEST_JSON = ".claude/cco/context/brain-pack/latest.json";
+const BRAIN_PACK_LATEST_MD = ".claude/cco/context/brain-pack/latest.md";
+const BRAIN_PACK_EVENT_LOG = ".claude/cco/events/brain-pack.jsonl";
+
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|(?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*\S+)/i;
+
+function redactIfSecret(text) {
+  if (!text) return text;
+  const s = String(text);
+  return SECRET_PATTERN.test(s) ? "[REDACTED]" : s;
+}
+
+function createBrainPackId() {
+  return `bp-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+// ── Package.json reader ───────────────────────────────────────────────────────
+
+function readPackageJson(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// ── Work-Control reader (safe) ────────────────────────────────────────────────
+
+function readWorkControlForBrainPack(cwd) {
+  try {
+    const { readLatestWorkControlReceipt } = require("./work-control-receipts");
+    return readLatestWorkControlReceipt(cwd);
+  } catch {
+    return null;
+  }
+}
+
+// ── Session Context reader (safe) ─────────────────────────────────────────────
+
+function readSessionContextForBrainPack(cwd) {
+  try {
+    const { readLatestSessionContext } = require("./session-context-optimizer");
+    return readLatestSessionContext(cwd);
+  } catch {
+    return null;
+  }
+}
+
+// ── Dogfood doc scanner (safe, compact) ───────────────────────────────────────
+
+function readLatestDogfoodSignals(cwd) {
+  const signals = { gaps: [], nextCandidates: [] };
+  try {
+    const dogfoodDir = path.join(cwd, "docs", "dogfood");
+    if (!fs.existsSync(dogfoodDir)) return signals;
+    const files = fs.readdirSync(dogfoodDir).filter((f) => f.endsWith(".md"));
+    // Read only the most recent dogfood doc (compact, safe)
+    if (!files.length) return signals;
+    const latest = files.sort().pop();
+    const content = fs.readFileSync(path.join(dogfoodDir, latest), "utf8");
+    // Extract deferred sections compactly (just headings)
+    const lines = content.split("\n").filter((l) => l.startsWith("## Deferred") || l.startsWith("13. Deferred") || l.includes("deferred") || l.includes("gap"));
+    signals.gaps = lines.slice(0, 5).map((l) => l.replace(/^#+\s*/, "").trim()).filter(Boolean);
+    signals.nextCandidates = [];
+  } catch {
+    // safe fail
+  }
+  return signals;
+}
+
+// ── Project builder ───────────────────────────────────────────────────────────
+
+function buildProject(cwd, pkg) {
+  const name = pkg?.name || path.basename(cwd);
+  const productName = pkg?.productName || pkg?.name || name;
+
+  // Try to read CLAUDE.md for product direction hints
+  let productDirection = "Local AI coding optimization platform.";
+  let architecturePrinciples = [
+    "local-first, no mandatory cloud",
+    "deterministic, no LLM calls in core logic",
+    "compact receipts, not huge JSON",
+    "capability-router pattern: one router, no duplicates",
+    "evidence-backed decisions",
+  ];
+  let nonGoals = [
+    "AI Workspace Registry (deferred)",
+    "Browser Proof (deferred)",
+    "Workflow Intelligence Radar (deferred)",
+    "Full model gateway (deferred)",
+    "Pricing / website (deferred)",
+  ];
+
+  try {
+    const claudeMdPath = path.join(cwd, "CLAUDE.md");
+    if (fs.existsSync(claudeMdPath)) {
+      const content = fs.readFileSync(claudeMdPath, "utf8");
+      // Extract first non-empty line after # heading as direction hint
+      const lines = content.split("\n").filter((l) => l.trim() && !l.startsWith("#")).slice(0, 3);
+      if (lines.length) productDirection = lines[0].slice(0, 200);
+    }
+  } catch {}
+
+  // Detect current roadmap stage from work-control or package version
+  const wcReceipt = readWorkControlForBrainPack(cwd);
+  const currentRoadmapStage = wcReceipt?.task?.text
+    ? String(wcReceipt.task.text).slice(0, 100)
+    : "Context Intelligence Completion v1";
+
+  return {
+    name: redactIfSecret(name),
+    productName: redactIfSecret(productName),
+    repoPath: redactIfSecret(cwd),
+    currentRoadmapStage,
+    productDirection,
+    nonGoals,
+    architecturePrinciples,
+  };
+}
+
+// ── Repo conventions builder ──────────────────────────────────────────────────
+
+function buildRepoConventions(cwd, pkg) {
+  const scripts = pkg?.scripts || {};
+  const testCommands = ["node --test tests/*.test.js", "cmd /c npm test"];
+  const buildCommands = [];
+  const validationCommands = ["node scripts/validate-operating-layer.js"];
+
+  if (scripts.test) buildCommands.push(`npm test`);
+  if (scripts.build) buildCommands.push(`npm run build`);
+  if (scripts["test:brand"]) testCommands.push("npm run test:brand");
+
+  const packageManager = fs.existsSync(path.join(cwd, "yarn.lock")) ? "yarn"
+    : fs.existsSync(path.join(cwd, "pnpm-lock.yaml")) ? "pnpm"
+    : "npm";
+
+  return {
+    packageManager,
+    testCommands,
+    buildCommands,
+    validationCommands,
+    branchPrConventions: "kebab-case, feature branches, PR per bounded task",
+    runtimeArtifactRules: "do not commit .claude/cco/ runtime receipts; do not commit .avorelo/ artifacts",
+  };
+}
+
+// ── Context rules builder ─────────────────────────────────────────────────────
+
+function buildContextRules() {
+  return {
+    doNotRediscover: true,
+    avoidHugeJson: true,
+    preferNamedFiles: true,
+    useAvoreloFirst: true,
+    useWorkControl: true,
+    useSessionContext: true,
+    useCapabilityRecommender: true,
+    note: "Start from Work-Control receipt and Session Context, not broad repo scans.",
+  };
+}
+
+// ── User preferences builder ──────────────────────────────────────────────────
+
+function buildUserPreferences() {
+  return {
+    preferredWorkflow: "bounded-implementation-first",
+    promptStyle: "short, direct, no trailing summaries",
+    dogfoodExpectations: "structured feedback with frictionObserved, missingContext, capabilityThatShouldHaveHandledIt",
+    safetyExpectations: "no bypassing guards, no destructive ops without confirmation, preserve blocks",
+  };
+}
+
+// ── Recipe detection ──────────────────────────────────────────────────────────
+
+const RECIPE_SIGNALS = [
+  {
+    name: "pr_continuation_or_merge",
+    signals: ["pr", "merge", "ci", "branch", "validation", "pull request", "commit"],
+    recommendedCapabilityPack: "release_readiness",
+    firstCommand: "node bin/avorelo work-control --handoff",
+    doNotRepeat: ["Do not rewrite commit history without explicit approval.", "Do not push --force without user confirmation."],
+    deferredCapabilities: [],
+  },
+  {
+    name: "security_or_intake_review",
+    signals: ["mcp", "package", "install", "unknown tool", "dependency", "risk", "intake", "guard"],
+    recommendedCapabilityPack: "install_intake_risk",
+    firstCommand: "node bin/avorelo intake --json",
+    doNotRepeat: ["Do not execute unknown-source tools before intake review.", "Do not skip guard evaluation for MCP tool calls."],
+    deferredCapabilities: [],
+  },
+  {
+    name: "context_or_token_optimization",
+    signals: ["context", "token", "session", "handoff", "rediscovery", "continuation", "brain pack", "brain-pack"],
+    recommendedCapabilityPack: "workflow_efficiency",
+    firstCommand: "node bin/avorelo session-context --handoff",
+    doNotRepeat: ["Do not paste huge JSON into context.", "Do not broad-scan repo before reading named files."],
+    deferredCapabilities: [],
+  },
+  {
+    name: "skills_or_source_backed_workflow",
+    signals: ["skill", "recipe", "workflow", "reference", "source-backed", "source backed"],
+    recommendedCapabilityPack: "source_backed_skills",
+    firstCommand: "node bin/avorelo skills route --task \"<task>\"",
+    doNotRepeat: ["Do not use skill sources before intake review.", "Do not duplicate skill routing logic in session context."],
+    deferredCapabilities: [],
+  },
+  {
+    name: "frontend_or_browser_evidence",
+    signals: ["browser", "screenshot", "visual", "frontend", "playwright", "ui", "landing page"],
+    recommendedCapabilityPack: "frontend_readiness",
+    firstCommand: "node bin/avorelo visual-qa --dry-run",
+    doNotRepeat: ["Browser Proof remains deferred.", "Do not implement visual QA infrastructure in this session."],
+    deferredCapabilities: ["browser_proof_evidence", "full_visual_qa"],
+  },
+  {
+    name: "launch_pricing_site",
+    signals: ["pricing", "website", "landing page", "launch", "plugin", "marketplace"],
+    recommendedCapabilityPack: null,
+    firstCommand: null,
+    doNotRepeat: ["Pricing/website/plugin launch is deferred.", "Do not start public-web work in this session."],
+    deferredCapabilities: ["pricing_website_plugin_launch"],
+  },
+];
+
+function detectRecipe(task, options = {}) {
+  if (!task || typeof task !== "string") {
+    return {
+      detectedRecipe: null,
+      confidence: 0,
+      reason: "No task provided — recipe detection skipped.",
+      recommendedCapabilityPack: null,
+      firstCommand: null,
+      doNotRepeat: [],
+      deferredCapabilities: [],
+    };
+  }
+
+  const taskLower = task.toLowerCase();
+
+  // Score each recipe by signal matches
+  const scored = RECIPE_SIGNALS.map((recipe) => {
+    const matches = recipe.signals.filter((signal) => taskLower.includes(signal));
+    return { recipe, matches, score: matches.length };
+  }).filter((s) => s.score > 0).sort((a, b) => b.score - a.score);
+
+  if (!scored.length) {
+    return {
+      detectedRecipe: null,
+      confidence: 0,
+      reason: "No matching recipe signals found.",
+      recommendedCapabilityPack: null,
+      firstCommand: null,
+      doNotRepeat: [],
+      deferredCapabilities: [],
+    };
+  }
+
+  const best = scored[0];
+  const confidence = Math.min(1, best.score / 3);
+
+  // Note: recipe detection augments, does not replace, capability recommender
+  // The capability recommender is the authoritative router
+
+  return {
+    detectedRecipe: best.recipe.name,
+    confidence: parseFloat(confidence.toFixed(2)),
+    reason: `Matched signals: ${best.matches.join(", ")}`,
+    recommendedCapabilityPack: best.recipe.recommendedCapabilityPack,
+    firstCommand: best.recipe.firstCommand
+      ? best.recipe.firstCommand.replace("<task>", task.slice(0, 60))
+      : null,
+    doNotRepeat: best.recipe.doNotRepeat,
+    deferredCapabilities: best.recipe.deferredCapabilities,
+    note: "Recipe detection augments capability-recommender output. Use recommendCapabilities() as the authoritative router.",
+  };
+}
+
+// ── Signals reader ────────────────────────────────────────────────────────────
+
+function buildSignals(cwd, wcReceipt, sessionContext) {
+  const signals = {
+    lastWorkControlFinalState: wcReceipt?.workControl?.finalState || null,
+    latestSessionContextPath: ".claude/cco/orchestration/session-context/latest-context.json",
+    knownGaps: [],
+    nextRoadmapCandidates: [],
+  };
+
+  // Pull next safest action from work-control
+  if (wcReceipt?.workControl?.nextSafestAction) {
+    signals.nextSafestAction = String(wcReceipt.workControl.nextSafestAction).slice(0, 200);
+  }
+
+  // Pull known gaps from dogfood docs
+  const dogfoodSignals = readLatestDogfoodSignals(cwd);
+  signals.knownGaps = dogfoodSignals.gaps.slice(0, 5);
+
+  // Next roadmap candidates from brief's deferred list
+  signals.nextRoadmapCandidates = [
+    "AI Workspace Registry / Asset Inventory Foundation",
+    "Browser Proof / Evidence",
+    "Workflow Intelligence Radar",
+    "Full Brain Pack UI / management",
+    "Full recipe library",
+  ];
+
+  return signals;
+}
+
+// ── Main build function ───────────────────────────────────────────────────────
+
+function buildBrainPack(cwd, options = {}) {
+  const pkg = readPackageJson(cwd);
+  const wcReceipt = readWorkControlForBrainPack(cwd);
+  const sessionContext = readSessionContextForBrainPack(cwd);
+
+  const brainPackId = createBrainPackId();
+  const createdAt = nowIso();
+
+  const project = buildProject(cwd, pkg);
+  const userPreferences = buildUserPreferences();
+  const repoConventions = buildRepoConventions(cwd, pkg);
+  const contextRules = buildContextRules();
+  const signals = buildSignals(cwd, wcReceipt, sessionContext);
+
+  // Capability recommender integration (read-only, no new router)
+  let capabilityRecommendation = null;
+  try {
+    const { recommendCapabilities } = require("./capability-recommender");
+    const rec = recommendCapabilities({ cwd, signals: {}, plan: "free" });
+    capabilityRecommendation = {
+      recommendedPackId: rec.recommendedPack?.id || null,
+      recommendedPackName: rec.recommendedPack?.name || null,
+      reason: rec.reason || null,
+      nextAction: rec.nextAction || null,
+    };
+  } catch {
+    capabilityRecommendation = null;
+  }
+
+  // Recipe detection (based on last task)
+  const lastTask = wcReceipt?.task?.text || options.task || null;
+  const recipe = lastTask ? detectRecipe(lastTask, { cwd }) : null;
+
+  const brainPack = {
+    schemaVersion: BRAIN_PACK_SCHEMA_VERSION,
+    contract: BRAIN_PACK_CONTRACT,
+    brainPackId,
+    createdAt,
+    project,
+    userPreferences,
+    repoConventions,
+    contextRules,
+    recipes: recipe ? [recipe] : [],
+    signals,
+    capabilityRecommendation,
+    redacted: true,
+  };
+
+  return brainPack;
+}
+
+// ── Markdown builder ──────────────────────────────────────────────────────────
+
+function buildBrainPackMarkdown(brainPack) {
+  const p = brainPack.project || {};
+  const r = brainPack.repoConventions || {};
+  const s = brainPack.signals || {};
+  const cr = brainPack.contextRules || {};
+  const cap = brainPack.capabilityRecommendation;
+
+  const lines = [
+    `# Avorelo Brain Pack — ${p.name || "project"}`,
+    `> ${p.productName || ""}  |  Generated: ${brainPack.createdAt}`,
+    "",
+    "## Project",
+    `- **Product direction:** ${p.productDirection || ""}`,
+    `- **Current roadmap stage:** ${p.currentRoadmapStage || ""}`,
+    "",
+    "## Architecture Principles",
+    ...(p.architecturePrinciples || []).map((a) => `- ${a}`),
+    "",
+    "## Non-Goals (this session)",
+    ...(p.nonGoals || []).map((n) => `- ${n}`),
+    "",
+    "## Repo Conventions",
+    `- Package manager: ${r.packageManager || "npm"}`,
+    `- Tests: ${(r.testCommands || []).join(", ")}`,
+    `- Validation: ${(r.validationCommands || []).join(", ")}`,
+    `- Artifacts: ${r.runtimeArtifactRules || ""}`,
+    "",
+    "## Context Rules",
+    `- Do not rediscover repo: ${cr.doNotRediscover}`,
+    `- Avoid huge JSON: ${cr.avoidHugeJson}`,
+    `- Prefer named files: ${cr.preferNamedFiles}`,
+    `- ${cr.note || ""}`,
+    "",
+  ];
+
+  if (cap) {
+    lines.push("## Recommended Capability");
+    lines.push(`- Pack: ${cap.recommendedPackName || cap.recommendedPackId || "none"}`);
+    lines.push(`- Why: ${cap.reason || ""}`);
+    lines.push(`- Next: ${cap.nextAction || ""}`);
+    lines.push("");
+  }
+
+  if (brainPack.recipes?.length) {
+    const rec = brainPack.recipes[0];
+    lines.push("## Detected Recipe");
+    lines.push(`- Recipe: ${rec.detectedRecipe}`);
+    lines.push(`- Confidence: ${rec.confidence}`);
+    lines.push(`- First command: \`${rec.firstCommand || ""}\``);
+    lines.push("");
+  }
+
+  lines.push("## Signals");
+  lines.push(`- Last work-control state: ${s.lastWorkControlFinalState || "missing"}`);
+  if (s.nextSafestAction) lines.push(`- Next safest action: ${s.nextSafestAction}`);
+  lines.push("");
+
+  if (s.knownGaps?.length) {
+    lines.push("## Known Gaps");
+    s.knownGaps.forEach((g) => lines.push(`- ${g}`));
+    lines.push("");
+  }
+
+  lines.push("## Deferred Capabilities");
+  (s.nextRoadmapCandidates || []).forEach((c) => lines.push(`- ${c}`));
+  lines.push("");
+
+  lines.push("---");
+  lines.push("*Generated by `avorelo brain-pack`. Do not paste raw — use `avorelo brain-pack --json` for compact output.*");
+
+  return lines.join("\n");
+}
+
+// ── Write function ────────────────────────────────────────────────────────────
+
+function writeBrainPack(cwd, brainPack) {
+  ensureCcoDirs(cwd);
+
+  const brainPackDir = path.join(cwd, ".claude", "cco", "context", "brain-pack");
+  fs.mkdirSync(brainPackDir, { recursive: true });
+
+  safeWriteJson(cwd, BRAIN_PACK_LATEST_JSON, brainPack);
+
+  const md = buildBrainPackMarkdown(brainPack);
+  safeWriteText(cwd, BRAIN_PACK_LATEST_MD, md);
+
+  // Append event log (compact)
+  try {
+    const logAbs = path.join(cwd, BRAIN_PACK_EVENT_LOG);
+    fs.mkdirSync(path.dirname(logAbs), { recursive: true });
+    const logEntry = JSON.stringify({
+      brainPackId: brainPack.brainPackId,
+      createdAt: brainPack.createdAt,
+      projectName: brainPack.project?.name || null,
+      recipesCount: (brainPack.recipes || []).length,
+      capabilityRecommended: brainPack.capabilityRecommendation?.recommendedPackId || null,
+    });
+    fs.appendFileSync(logAbs, `${logEntry}\n`, "utf8");
+  } catch {}
+
+  // Product learning events
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "brain_pack_generated",
+      category: "brain_pack",
+      status: "completed",
+      payload: {
+        brainPackId: brainPack.brainPackId,
+        hasCapabilityRecommendation: Boolean(brainPack.capabilityRecommendation),
+        recipesCount: (brainPack.recipes || []).length,
+        signalsCount: Object.keys(brainPack.signals || {}).length,
+      },
+    });
+  } catch {}
+
+  return {
+    jsonPath: BRAIN_PACK_LATEST_JSON,
+    mdPath: BRAIN_PACK_LATEST_MD,
+  };
+}
+
+// ── Read latest ───────────────────────────────────────────────────────────────
+
+function readLatestBrainPack(cwd) {
+  return safeReadJson(cwd, BRAIN_PACK_LATEST_JSON, null);
+}
+
+// ── Surface builder (for dashboard/status) ────────────────────────────────────
+
+function buildBrainPackSurface(cwd) {
+  const latest = readLatestBrainPack(cwd);
+  if (!latest) {
+    return {
+      status: "missing",
+      latestBrainPackPath: null,
+      productDirectionAvailable: false,
+      repoConventionsAvailable: false,
+      recipesAvailable: false,
+      recommendedRecipe: null,
+      nextAction: "Run `node bin/avorelo brain-pack --init` to create the first brain pack.",
+    };
+  }
+
+  const recipe = (latest.recipes || [])[0] || null;
+
+  return {
+    status: "available",
+    latestBrainPackPath: BRAIN_PACK_LATEST_JSON,
+    latestMarkdownPath: BRAIN_PACK_LATEST_MD,
+    productDirectionAvailable: Boolean(latest.project?.productDirection),
+    repoConventionsAvailable: Boolean(latest.repoConventions?.packageManager),
+    recipesAvailable: (latest.recipes || []).length > 0,
+    recommendedRecipe: recipe?.detectedRecipe || null,
+    capabilityRecommended: latest.capabilityRecommendation?.recommendedPackId || null,
+    nextAction: latest.signals?.nextSafestAction
+      || "Run `node bin/avorelo brain-pack --json` to refresh.",
+    brainPackId: latest.brainPackId,
+  };
+}
+
+// ── Summary text ──────────────────────────────────────────────────────────────
+
+function formatBrainPackText(brainPackOrSurface, options = {}) {
+  if (!brainPackOrSurface) {
+    return "Brain Pack: MISSING · run `avorelo brain-pack --init` to create.\n";
+  }
+
+  if (brainPackOrSurface.contract === BRAIN_PACK_CONTRACT) {
+    const bp = brainPackOrSurface;
+    const lines = [
+      `Brain Pack: ${bp.brainPackId}`,
+      `Project: ${bp.project?.name || "unknown"}`,
+      `Stage: ${bp.project?.currentRoadmapStage || "unknown"}`,
+      `Capability: ${bp.capabilityRecommendation?.recommendedPackName || "none"}`,
+      `Recipe: ${(bp.recipes || [])[0]?.detectedRecipe || "none"}`,
+      `State: ${bp.signals?.lastWorkControlFinalState || "missing"}`,
+      `JSON: ${BRAIN_PACK_LATEST_JSON}`,
+    ];
+    return lines.join("\n") + "\n";
+  }
+
+  const surface = brainPackOrSurface;
+  const lines = [
+    `Brain Pack: ${surface.status?.toUpperCase() || "MISSING"}`,
+    surface.recommendedRecipe ? `Recipe: ${surface.recommendedRecipe}` : null,
+    surface.nextAction ? `Next: ${surface.nextAction}` : null,
+    surface.latestBrainPackPath ? `Path: ${surface.latestBrainPackPath}` : null,
+  ].filter(Boolean);
+  return lines.join("\n") + "\n";
+}
+
+module.exports = {
+  BRAIN_PACK_CONTRACT,
+  BRAIN_PACK_SCHEMA_VERSION,
+  BRAIN_PACK_LATEST_JSON,
+  BRAIN_PACK_LATEST_MD,
+  buildBrainPack,
+  writeBrainPack,
+  readLatestBrainPack,
+  buildBrainPackSurface,
+  buildBrainPackMarkdown,
+  formatBrainPackText,
+  detectRecipe,
+};