@hizliemre/horse-code 0.1.0

package/dist/chunk-F2IALVBU.js

@@ -0,0 +1,212 @@
+import {
+  buildSkillTool,
+  editFileTool,
+  writeFileTool
+} from "./chunk-3XVZXTB6.js";
+import {
+  globTool,
+  grepTool,
+  readFileTool
+} from "./chunk-TOPZL5SU.js";
+import {
+  ToolRegistry,
+  runStructuredRole
+} from "./chunk-YILDXPSI.js";
+
+// src/engine/language.ts
+function respondIn(language) {
+  if (!language || /^english$/i.test(language)) return "";
+  return `
+
+Respond to the user in ${language}: everything you say to them, and every question you ask, is in ${language}. Code, identifiers, logs and commit messages keep whatever language the project uses.`;
+}
+
+// src/engine/writer-registry.ts
+import { z as z2 } from "zod";
+
+// src/engine/normalize-question.ts
+import { z } from "zod";
+var NormalizedQuestionSchema = z.object({
+  question: z.string().describe("The core question, concise, WITHOUT the embedded options table/list."),
+  options: z.array(z.string()).describe("Each selectable choice as a SHORT label; the recommended one first, suffixed ' (recommended)'. Empty when the question is genuinely open-ended."),
+  multiSelect: z.boolean().describe("true only if the user may pick more than one.")
+});
+var PROMPT = "You reformat an agent's question for a terminal UI that renders selectable options (arrow keys + Enter). Given the raw question text \u2014 which may embed choices as a markdown table, an A/B/C/D list, or a 'recommended' suggestion \u2014 extract exactly:\n- `question`: the core question, concise, WITHOUT the embedded options table/list.\n- `options`: each selectable choice as a SHORT label. If one choice is recommended, list it FIRST and append ' (recommended)'. Do NOT add an 'other' / free-text / 'answer in your own words' option \u2014 the UI already provides that.\n- `multiSelect`: true only if the user may pick several.\nIf the text is genuinely open-ended (no discrete choices), return options: []. Preserve the user's language. Return the result via submit.";
+function looksLikeChoices(text) {
+  return /\|[^\n]*\|[^\n]*\|/.test(text) || /(^|\n)\s*[A-Ea-e][).\-:]\s/.test(text) || /(^|\n)\s*[-*]\s+\S.*(\n\s*[-*]\s+\S.*){1,}/.test(text) || /\b(option|seçenek|choice|önerilen|recommended)\b/i.test(text);
+}
+async function normalizeQuestion(deps, raw) {
+  const { role: agentRole, model, fallbacks, onExhausted, onFallback } = deps.roleRegistry.fallbackOpts("refiner");
+  return runStructuredRole({
+    provider: deps.provider,
+    role: agentRole,
+    model,
+    fallbacks,
+    onExhausted,
+    onFallback,
+    // This shapes the question the USER reads; a rule like "always ask in Turkish" belongs here.
+    systemPrompt: PROMPT + deps.roleRegistry.ruleSuffix(),
+    tools: new ToolRegistry(),
+    messages: [{ role: "user", content: raw }],
+    permission: deps.permission,
+    approve: deps.approve,
+    cwd: ".",
+    signal: deps.signal
+  }, NormalizedQuestionSchema);
+}
+function extractChoicesFrom(text) {
+  const lines = text.split("\n");
+  const rows = lines.map((l) => l.trim()).filter((l) => l.startsWith("|") && l.endsWith("|") && !/^\|[\s|:-]+\|$/.test(l)).map((l) => l.slice(1, -1).split("|").map((c) => c.trim()));
+  const body = rows.filter((cells) => cells.length >= 2 && cells[0] && cells[1]).filter((cells, i) => !(i === 0 && /^(option|seçenek|choice|alternatif)$/i.test(cells[0])));
+  if (body.length >= 2) {
+    const question = lines.filter((l) => !/^\s*\|.*\|\s*$/.test(l)).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    return { choices: body.map((cells) => ({ label: cells[0], description: cells.slice(1).join(" \u2014 ") })), question };
+  }
+  const isLettered = (l) => /^\s*([A-Ea-e])[).\-:]\s+(\S.*)$/.exec(l.trim());
+  const lettered = lines.map(isLettered).filter((m) => !!m).map((m) => ({ label: `${m[1].toUpperCase()} \u2014 ${m[2]}` }));
+  if (lettered.length >= 2) {
+    const question = lines.filter((l) => !isLettered(l)).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    return { choices: lettered, question };
+  }
+  const MARKER = /\(([A-Ea-e])\)\s*/g;
+  const marks = [...text.matchAll(MARKER)];
+  const inOrder = marks.length >= 2 && marks.every((m, i) => m[1].toUpperCase() === String.fromCharCode(65 + i));
+  if (inOrder) {
+    const first = marks[0].index ?? 0;
+    const parts = marks.map((m, i) => {
+      const start = (m.index ?? 0) + m[0].length;
+      const end = i + 1 < marks.length ? marks[i + 1].index ?? text.length : text.length;
+      return { letter: m[1].toUpperCase(), body: text.slice(start, end).trim().replace(/\s+/g, " ") };
+    }).filter((p) => p.body);
+    if (parts.length >= 2) {
+      const question = text.slice(0, first).replace(/\s*(Se\u00e7enekler|Options|Choices)\s*:?\s*$/i, "").trim();
+      return {
+        choices: parts.map((p) => ({ label: `${p.letter} \u2014 ${clipLabel(p.body)}`, description: p.body })),
+        question: question || text
+      };
+    }
+  }
+  return { choices: [], question: text };
+}
+var clipLabel = (body) => {
+  const cut = body.replace(/^\[[^\]]*\]\s*/, "");
+  const stop = cut.search(/[—–.;:]\s/);
+  const head = stop > 12 ? cut.slice(0, stop) : cut;
+  return head.length > 72 ? `${head.slice(0, 71)}\u2026` : head;
+};
+
+// src/engine/writer-registry.ts
+var askUserParams = z2.object({
+  question: z2.string(),
+  // For a multiple-choice question, list the choices here → the UI shows a selectable checkbox/radio list
+  // (arrow keys + Enter) instead of a free-text box. Omit for an open-ended question.
+  //
+  // A choice may be a plain string, or an object carrying what the label alone cannot say: a one-line
+  // `description`, and a `preview` rendered in a panel beside the list while that option is focused. Use the
+  // rich form when the decision turns on the trade-offs rather than the name (e.g. "which approach?").
+  options: z2.array(z2.union([
+    z2.string(),
+    z2.object({ label: z2.string(), description: z2.string().optional(), preview: z2.string().optional() })
+  ])).optional().describe(
+    "The choices, when the question has discrete answers \u2014 the UI renders a selectable list instead of a free-text box. Omit for an open-ended question. A choice may be a plain string, or an object with a one-line `description` and a `preview` shown beside the list; use the rich form when the decision turns on trade-offs rather than on the name."
+  ),
+  multiSelect: z2.boolean().optional().describe(
+    "True when the user may pick more than one (checkboxes); omitted means pick exactly one (radio)."
+  ),
+  /**
+   * What the user has to DO before they can answer — one action per entry.
+   *
+   * Present ⇒ this is a hand-off, not a question: the run has stopped because only a person can carry the
+   * next step, and the UI says so rather than showing a bare "? Question".
+   */
+  steps: z2.array(z2.string()).optional().describe(
+    'What the user has to DO before they can answer \u2014 one action per entry. Supplying this makes it a HAND-OFF rather than a question: the run has stopped because only a person can carry the next step, and the UI says so instead of showing a bare "? Question". Use it whenever you are asking someone to go and perform something and report back; leave it out when you only want an answer.'
+  )
+});
+var POINTS_ELSEWHERE = /\b(above|below|earlier|previously|as listed|as described)\b|yukarı|aşağı|altında|önceki|birazdan|listelenen/i;
+var ITEM_REFERENCE = /(?:^|[^\w])(?:q|soru|question|madde|item)\s*\.?\s*(\d{1,2})\b/gi;
+var ITEM_STATED = /^[\s>*\-–—#]*(?:q|soru|question|madde|item)\s*\.?\s*\d{1,2}\s*[:).]/gim;
+function danglingItems(question) {
+  const referenced = new Set([...question.matchAll(ITEM_REFERENCE)].map((m) => Number(m[1])));
+  if (referenced.size < 2) return [];
+  const stated = question.match(ITEM_STATED)?.length ?? 0;
+  return stated >= referenced.size ? [] : [...referenced].sort((a, b) => a - b);
+}
+var ENUMERATOR = /(?:^|[^\w])\(?(\d{1,2})[).:]/g;
+function packedQuestions(question) {
+  if ((question.match(/\?/g)?.length ?? 0) < 2) return 0;
+  const numbered = new Set([...question.matchAll(ENUMERATOR)].map((m) => Number(m[1])));
+  return numbered.size;
+}
+var ONE_AT_A_TIME = "This tool asks ONE question and takes ONE answer. Ask the first one on its own, with its own `options`, and call this tool again for the next once you have the answer \u2014 the answer to one of these usually changes what the next one should be.";
+function buildAskUserTool(askUser, normalize) {
+  return {
+    name: "ask_user",
+    description: 'Ask the user ONE question and get their answer. Several decisions are several calls: ask the first, read the answer, then ask the next \u2014 the user has one answer field, so four questions in one box means four decisions they must hold in their head and answer in prose. For a multiple-choice question, pass `options` (the choices) \u2014 the UI shows a selectable list the user checks off; set `multiSelect: true` when they may pick several. Omit `options` for an open-ended (free-text) question. An option may be a plain string, or {label, description, preview} when the decision turns on trade-offs the label cannot carry \u2014 the preview is shown beside the list as the user moves the cursor. A `label` is a SHORT single line (a few words, no line breaks): it is a name for the choice, not the argument for it. Put the reasoning in `description` (one sentence) and the detail in `preview`. If you have findings to report, WRITE THEM as your message before calling this \u2014 a question that says "the evaluation is above" when you never wrote one leaves the user choosing between options whose basis they cannot see. The user may attach a free-text note to their choice, which arrives appended to the answer.\n\nWhen you need the user to DO something first \u2014 click through a screen, run a scenario, look at a network response \u2014 put each action in `steps`, one per entry, and ask in `question` for what they should report back. The user reads THIS BOX and the chat; a file you wrote is not on their screen, so "the steps above" points at nothing they can see. With `steps` the UI shows a hand-off \u2014 the numbered actions and then the question \u2014 instead of a bare question.',
+    permissionLevel: "safe",
+    parameters: askUserParams,
+    run: async (rawArgs, ctx) => {
+      const parsed = askUserParams.safeParse(rawArgs);
+      if (!parsed.success) {
+        return { content: `ask_user: invalid args: ${parsed.error.issues.map((i) => i.message).join("; ")}`, isError: true };
+      }
+      const { question, options, multiSelect, steps } = parsed.data;
+      const asker = ctx.role || ctx.model ? { asker: { ...ctx.role ? { role: ctx.role } : {}, ...ctx.model ? { model: ctx.model } : {} } } : {};
+      if (POINTS_ELSEWHERE.test(question) && !steps?.length && !ctx.said?.trim()) {
+        return {
+          content: "ask_user: this question refers to something the user cannot see. You wrote no message this turn, so there is nothing above it \u2014 and a file you wrote is not on their screen. Put what they must do in `steps` (one action per entry), or write it out in `question`, and ask again.",
+          isError: true
+        };
+      }
+      const dangling = danglingItems(question);
+      if (dangling.length && !steps?.length && !ctx.said?.trim()) {
+        return {
+          content: `ask_user: this asks the user to answer ${dangling.map((n) => `Q${n}`).join(", ")}, and none of them is on their screen \u2014 you did not write them this turn, and a file you wrote is not something they are looking at. ${ONE_AT_A_TIME}`,
+          isError: true
+        };
+      }
+      const packed = packedQuestions(question);
+      if (packed >= 2 && !steps?.length && !options?.length) {
+        return {
+          content: `ask_user: this is ${packed} questions in one box, and the user has one answer field for all of them. ${ONE_AT_A_TIME}`,
+          isError: true
+        };
+      }
+      if ((!options || options.length === 0) && !steps?.length && looksLikeChoices(question)) {
+        const found = extractChoicesFrom(question);
+        if (found.choices.length >= 2) {
+          return { content: await askUser(found.question, { options: found.choices, ...asker }), isError: false };
+        }
+        if (normalize) {
+          try {
+            const n = await normalize(question);
+            if (n.options.length > 0) {
+              return { content: await askUser(n.question, { options: n.options, multiSelect: n.multiSelect, ...asker }), isError: false };
+            }
+          } catch {
+          }
+        }
+      }
+      return { content: await askUser(question, { options, multiSelect, steps, ...asker }), isError: false };
+    }
+  };
+}
+function writerRegistry(skillRegistry, extra = []) {
+  const r = new ToolRegistry();
+  r.register(readFileTool);
+  r.register(writeFileTool);
+  r.register(editFileTool);
+  r.register(grepTool);
+  r.register(globTool);
+  r.register(buildSkillTool(skillRegistry));
+  for (const t of extra) r.register(t);
+  return r;
+}
+
+export {
+  respondIn,
+  normalizeQuestion,
+  extractChoicesFrom,
+  buildAskUserTool,
+  writerRegistry
+};

package/dist/chunk-FFYBY2NA.js

@@ -0,0 +1,392 @@
+import {
+  stateRoot
+} from "./chunk-SSDLHWSF.js";
+import {
+  writeAtomic
+} from "./chunk-B67BK5GQ.js";
+
+// src/engine/trace.ts
+import { readFile, writeFile, mkdir, rm } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { createHash } from "crypto";
+import { dirname, join } from "path";
+var TRACE_DIR = join(".horsecode", "traces");
+var traceRoot = TRACE_DIR;
+function setTraceRoot(rel) {
+  if (rel && rel.trim()) traceRoot = rel.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function traceRootRel() {
+  return traceRoot;
+}
+var MAX_DISCOVERY_DEPTH = 4;
+function discoverTraceRoot(cwd, trackedFiles) {
+  const candidates = trackedFiles.map((f) => f.replace(/\\/g, "/")).filter((f) => f.endsWith(`/${TRACE_INDEX}`) && f.split("/").length <= MAX_DISCOVERY_DEPTH).sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+  for (const rel of candidates) {
+    try {
+      const raw = readFileSync(join(cwd, rel), "utf8");
+      const doc = JSON.parse(raw);
+      if (doc?.version !== 1 || typeof doc.traces !== "object" || doc.traces === null) continue;
+      if (!Object.keys(doc.traces).length) continue;
+      return rel.slice(0, -`/${TRACE_INDEX}`.length);
+    } catch {
+    }
+  }
+  return void 0;
+}
+var TRACE_INDEX = "index.json";
+var TRACEABLE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|c|h|cc|cpp|hpp|cs|php|swift|kt|scala)$/;
+function everTraceable(file) {
+  return TRACEABLE_EXT.test(file);
+}
+var NOT_SOURCE = /(^|\/)(dist|build|out|node_modules|vendor|coverage|graphify-out|\.[^/]+)\//;
+var GENERATED = /(\.Designer\.cs|ModelSnapshot\.cs|\.(g|generated)\.(cs|ts|js)|\.d\.ts|_pb2(_grpc)?\.py|\.pb\.go)$/;
+function traceable(files, opts) {
+  return files.filter((f) => !NOT_SOURCE.test(f) && !GENERATED.test(f) && (opts?.code === false || TRACEABLE_EXT.test(f)));
+}
+function traceDir(cwd) {
+  return join(stateRoot(cwd), traceRoot);
+}
+function tracePath(cwd, file) {
+  return join(traceDir(cwd), `${file}.md`);
+}
+function hashContent(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+async function loadTraceIndex(cwd) {
+  try {
+    const raw = JSON.parse(await readFile(join(traceDir(cwd), TRACE_INDEX), "utf8"));
+    if (raw?.version === 1 && typeof raw.traces === "object" && raw.traces !== null) return raw;
+  } catch {
+  }
+  return { version: 1, traces: {} };
+}
+function mergeTraceIndexes(ours, theirs) {
+  const traces = { ...ours.traces };
+  for (const [file, rec] of Object.entries(theirs.traces)) {
+    const mine = traces[file];
+    if (!mine || (rec.writtenAt ?? 0) > (mine.writtenAt ?? 0)) traces[file] = rec;
+  }
+  return { version: 1, traces };
+}
+function parseTraceIndex(text) {
+  try {
+    const raw = JSON.parse(text);
+    if (raw?.version === 1 && typeof raw.traces === "object" && raw.traces !== null) return raw;
+  } catch {
+  }
+  return void 0;
+}
+function serializeTraceIndex(index) {
+  return `${JSON.stringify(index, null, 2)}
+`;
+}
+async function saveTraceIndex(cwd, index) {
+  await mkdir(traceDir(cwd), { recursive: true });
+  await writeAtomic(join(traceDir(cwd), TRACE_INDEX), `${JSON.stringify(index, null, 2)}
+`);
+}
+async function readTrace(cwd, file) {
+  try {
+    return await readFile(tracePath(cwd, file), "utf8");
+  } catch {
+    return void 0;
+  }
+}
+function indexSync(cwd) {
+  try {
+    const raw = JSON.parse(readFileSync(join(traceDir(cwd), TRACE_INDEX), "utf8"));
+    if (raw?.version === 1 && typeof raw.traces === "object" && raw.traces !== null) return raw;
+  } catch {
+  }
+  return { version: 1, traces: {} };
+}
+function traceIsStale(cwd, file, rec) {
+  if (!rec?.hash) return false;
+  try {
+    return hashContent(readFileSync(join(stateRoot(cwd), file), "utf8")) !== rec.hash;
+  } catch {
+    return false;
+  }
+}
+var STALE_BANNER = "> \u26A0\uFE0F **This file has changed since this note was written.** Treat everything below as the previous version: the purpose is probably still right, the specifics may not be. Read the file itself before relying on any detail here.\n\n";
+function readTraceSync(cwd, file) {
+  const rec = indexSync(cwd).traces[file];
+  const mark = (body) => traceIsStale(cwd, file, rec) ? STALE_BANNER + body : body;
+  if (rec?.doc) {
+    try {
+      return mark(readFileSync(join(stateRoot(cwd), rec.doc), "utf8"));
+    } catch {
+    }
+  }
+  if (!file || file.includes("..") || file.startsWith("/")) return void 0;
+  try {
+    return mark(readFileSync(tracePath(cwd, file), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+var MAX_TRACE_FILE_CHARS = 6e4;
+var CHARS_PER_TOKEN = 3.13;
+var TRACE_OUTPUT_TOKENS = 350;
+function traceState(cwd, file, content, index, hash = hashContent(content)) {
+  if (content.length > MAX_TRACE_FILE_CHARS) return "too-large";
+  if (!content.trim()) return "empty";
+  const rec = index.traces[file];
+  const backing = rec?.doc ? join(cwd, rec.doc) : tracePath(cwd, file);
+  if (!rec || !existsSync(backing)) return "missing";
+  return rec.hash === hash ? "current" : "stale";
+}
+async function traceCoverage(cwd, files, index) {
+  const out = { traceable: 0, current: 0, missing: 0, stale: 0 };
+  for (const file of files) {
+    let content;
+    try {
+      content = await readFile(join(cwd, file), "utf8");
+    } catch {
+      continue;
+    }
+    const state = traceState(cwd, file, content, index);
+    if (state === "too-large" || state === "empty") continue;
+    out.traceable++;
+    out[state]++;
+  }
+  return out;
+}
+async function planTraces(cwd, files, graph, index) {
+  const jobs = [];
+  const skipped = [];
+  let upToDate = 0;
+  const symbolsOf = /* @__PURE__ */ new Map();
+  const fileOfNode = /* @__PURE__ */ new Map();
+  if (graph) {
+    for (const n of graph.nodes) {
+      if (!n.source_file) continue;
+      fileOfNode.set(n.id, n.source_file);
+      const list = symbolsOf.get(n.source_file);
+      if (list) list.push(n.label);
+      else symbolsOf.set(n.source_file, [n.label]);
+    }
+  }
+  const usedByOf = /* @__PURE__ */ new Map();
+  const usesOf = /* @__PURE__ */ new Map();
+  if (graph) {
+    for (const e of graph.edges) {
+      const sf = fileOfNode.get(e.source);
+      const tf = fileOfNode.get(e.target);
+      if (!sf || !tf || sf === tf) continue;
+      let a = usedByOf.get(tf);
+      if (!a) {
+        a = /* @__PURE__ */ new Set();
+        usedByOf.set(tf, a);
+      }
+      a.add(sf);
+      let b = usesOf.get(sf);
+      if (!b) {
+        b = /* @__PURE__ */ new Set();
+        usesOf.set(sf, b);
+      }
+      b.add(tf);
+    }
+  }
+  const relatedOf = (file) => ({
+    usedBy: [...usedByOf.get(file) ?? []].slice(0, 12),
+    uses: [...usesOf.get(file) ?? []].slice(0, 12)
+  });
+  for (const file of files) {
+    let content;
+    try {
+      content = await readFile(join(cwd, file), "utf8");
+    } catch {
+      continue;
+    }
+    const hash = hashContent(content);
+    const state = traceState(cwd, file, content, index, hash);
+    if (state === "too-large") {
+      skipped.push({ file, why: `${Math.round(content.length / 1e3)} KB \u2014 too large to trace economically` });
+      continue;
+    }
+    if (state === "empty") continue;
+    if (state === "current") {
+      upToDate++;
+      continue;
+    }
+    const rel = relatedOf(file);
+    jobs.push({ file, hash, content, symbols: (symbolsOf.get(file) ?? []).slice(0, 40), ...rel });
+  }
+  const estimatedInputTokens = Math.round(jobs.reduce((n, j) => n + j.content.length / CHARS_PER_TOKEN, 0) + jobs.length * 200);
+  return { jobs, upToDate, estimatedInputTokens, estimatedOutputTokens: jobs.length * TRACE_OUTPUT_TOKENS, skipped };
+}
+function tracePrompt(job, brief) {
+  const rel = [
+    job.symbols.length ? `Defines: ${job.symbols.join(", ")}` : "",
+    job.usedBy.length ? `Used by: ${job.usedBy.join(", ")}` : "Used by: nothing else in this repo",
+    job.uses.length ? `Uses: ${job.uses.join(", ")}` : ""
+  ].filter(Boolean).join("\n");
+  const context = brief ? `What this project IS, from its own documentation \u2014 use this vocabulary and these rules; do not contradict them and do not repeat them back:
+${brief}
+
+---
+
+` : "";
+  return `${context}Write a short reference note about ONE source file, for an engineer who has never seen this codebase and is about to change it.
+
+Answer, in at most 150 words total, under these exact headings:
+**Purpose** \u2014 what this file is responsible for, in one or two sentences. Say what it is FOR in the product's terms, not what its syntax does. "Decides which model a role gets when its first choice is rate-limited" is useful; "exports a function that returns an array" is not.
+**Key decisions** \u2014 any non-obvious choice a reader would otherwise undo by accident. Omit the heading entirely if there are none; do not invent one.
+**Careful** \u2014 what breaks elsewhere if this changes, based on the relationships given below. Omit if nothing does.
+
+Rules:
+- State only what the code and the relationships below actually show. If the business purpose is not evident, say what the file does technically and do NOT speculate about why.
+- No preamble, no restating the filename, no summary of what you were asked.
+
+File: ${job.file}
+${rel}
+
+---
+${job.content}`;
+}
+async function saveTrace(cwd, job, body, model) {
+  const path = tracePath(cwd, job.file);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `# ${job.file}
+
+${body.trim()}
+`, "utf8");
+  return { hash: job.hash, file: job.file, writtenAt: Date.now(), ...model ? { model } : {} };
+}
+async function pruneTraces(cwd, liveFiles, index) {
+  const gone = Object.keys(index.traces).filter((f) => !liveFiles.has(f));
+  for (const f of gone) {
+    delete index.traces[f];
+    await rm(tracePath(cwd, f), { force: true });
+  }
+  return gone;
+}
+var GITIGNORE_MARKER = "# horse-code project knowledge";
+var SHARED_DERIVED = [
+  /**
+   * The community names, and NOT the graph they name.
+   *
+   * The graph used to be here too, and it is the one thing in this list that cannot survive a merge. It is a
+   * single line of JSON — 33.7 MB of it on a real project — and git merges by line, so two branches that
+   * both rebuilt it have nothing to reconcile. Measured on PR 677: of twelve files touched by the merge,
+   * every one auto-merged except `graphify-out/graph.json` and the labels beside it, and those two blocked
+   * the pull request outright. Rebuilding it costs CPU and nothing else, `graphify update` is incremental,
+   * and a session gets its copy through INHERITED_ASSETS without git being involved at all.
+   *
+   * The names are the opposite on every count. graphify's clustering finds the communities on its own, but
+   * naming them is step 5 of its runbook and the step an LLM performs: "look at its node labels and write a
+   * 2-5 word plain-language name". `graph.json` stores each node's community NUMBER and nothing else —
+   * measured on a real project, not one of its 6,283 names appears anywhere in the graph file. So a clone
+   * that has the graph still reads "community 47" where this file says "Wallet Member & Balance", and
+   * getting that back means paying an LLM for the naming pass again.
+   *
+   * It merges, too: `pruneAreaNames` writes one key per line in numeric order precisely so that a change to
+   * one name is a change to one line. Two branches adding different names merge cleanly; only two branches
+   * naming the SAME community differently conflict, in 136 KB rather than 33.7 MB.
+   */
+  { path: "graphify-out/.graphify_labels.json", why: "# Shared \u2014 the community names an LLM wrote; the graph stores only their numbers." }
+];
+function localOnly() {
+  return [...LOCAL_ONLY];
+}
+function sharedDerived() {
+  return SHARED_DERIVED.map((s) => s.path);
+}
+var LOCAL_ONLY = [
+  "graphify-out/manifest.json",
+  "graphify-out/graph.html",
+  "graphify-out/.graphify_root",
+  // The graph itself: rebuilt per checkout, inherited by copy, and unmergeable by construction — see above.
+  "graphify-out/graph.json",
+  // …and the commit it was built at, which describes that local copy and travels with it.
+  "graphify-out/.graph-commit.json"
+];
+var NESTED_CHECKOUTS = [".claude/worktrees/", ".horsecode/worktrees/"];
+function openDirectory(text, dir) {
+  return text.split("\n").map((l) => l.trim() === `${dir}/` ? l.replace(`${dir}/`, `${dir}/*`) : l).join("\n");
+}
+function planGitignore(current, root0 = ".") {
+  let text = current;
+  const rules = [];
+  const lines = () => text.split("\n").map((l) => l.trim());
+  const has = (rule) => lines().includes(rule);
+  const keep = (path, isDir, why) => {
+    const dir = path.split("/")[0];
+    const target = isDir ? `${path}/` : path;
+    const blocked = lines().some((l) => l === `${dir}/` || l === `${dir}/*` || l === dir || l === path);
+    if (!blocked || has(`!${target}`)) return;
+    text = openDirectory(text, dir);
+    rules.push(why, `!${target}`);
+  };
+  keep(
+    traceRootRel().replace(/\\/g, "/"),
+    true,
+    "# Shared \u2014 the traces describe the code, so every clone starts understanding the project instead of re-buying it."
+  );
+  for (const s of SHARED_DERIVED) keep(s.path, false, s.why);
+  const note = (comment) => {
+    if (!rules.includes(comment)) rules.push(comment);
+  };
+  const nested = NESTED_CHECKOUTS.filter((d) => existsSync(join(root0, d)) && !has(d) && !has(d.replace(/\/$/, "")));
+  if (nested.length) {
+    note("# Nested checkouts of this repository \u2014 committing one commits the repository into itself.");
+    rules.push(...nested);
+  }
+  const local = LOCAL_ONLY.filter((r) => !has(r) && !has("graphify-out/") && !has("graphify-out/*"));
+  if (local.length) {
+    note("# Machine-local or derived: an AST cache keyed by local mtimes, and a viewer regenerated on every build.");
+    rules.push(...local);
+  }
+  return { text, rules };
+}
+async function ensureGitignore(cwd) {
+  const path = join(cwd, ".gitignore");
+  let current = "";
+  try {
+    current = await readFile(path, "utf8");
+  } catch {
+  }
+  const plan = planGitignore(current, cwd);
+  if (!plan.rules.length && plan.text === current) return false;
+  const heading = plan.text.includes(GITIGNORE_MARKER) ? "" : `${GITIGNORE_MARKER}
+`;
+  const block = plan.rules.length ? `${heading}${plan.rules.join("\n")}
+` : "";
+  const body = `${plan.text.trimEnd()}${plan.text.trim() && block ? "\n\n" : ""}${block}`;
+  await writeFile(path, body, "utf8");
+  return true;
+}
+
+export {
+  TRACE_DIR,
+  setTraceRoot,
+  traceRootRel,
+  discoverTraceRoot,
+  TRACE_INDEX,
+  TRACEABLE_EXT,
+  everTraceable,
+  traceable,
+  traceDir,
+  tracePath,
+  hashContent,
+  loadTraceIndex,
+  mergeTraceIndexes,
+  parseTraceIndex,
+  serializeTraceIndex,
+  saveTraceIndex,
+  readTrace,
+  readTraceSync,
+  MAX_TRACE_FILE_CHARS,
+  TRACE_OUTPUT_TOKENS,
+  traceState,
+  traceCoverage,
+  planTraces,
+  tracePrompt,
+  saveTrace,
+  pruneTraces,
+  GITIGNORE_MARKER,
+  localOnly,
+  sharedDerived,
+  ensureGitignore
+};