@agjs/tsforge 0.1.0

package/src/loop/tools/execute-tool.ts

@@ -0,0 +1,80 @@
+import type { IToolCall } from "../../inference";
+import { TOOL_NAME, READ_ONLY_TOOL_NAMES, type ToolName } from "../../agent";
+import { readFile, runShell, doEdit, doCreate } from "./file-ops";
+import { doHashlineEdit } from "./edit-hashline";
+import { doSearch, doLsp } from "./lsp-ops";
+import { doScaffoldUi } from "./scaffold-ui";
+import { doScaffoldRoutes } from "./scaffold-routes";
+import { doScaffoldWeb } from "./scaffold-web";
+import { doAddDependency } from "./add-dependency";
+import { reject, type IToolContext } from "./tool-context";
+
+export type { IToolContext } from "./tool-context";
+
+type ToolHandler = (
+  args: Record<string, unknown>,
+  ctx: IToolContext
+) => Promise<string> | string;
+
+/** Name → handler. The LSP entries close over their tool name so `doLsp` keeps
+ *  one body. Keyed by ToolName, so a new tool must register here (exhaustive). */
+const HANDLERS: Record<ToolName, ToolHandler> = {
+  [TOOL_NAME.read]: readFile,
+  [TOOL_NAME.run]: runShell,
+  [TOOL_NAME.edit]: doEdit,
+  [TOOL_NAME.editLines]: doHashlineEdit,
+  [TOOL_NAME.create]: doCreate,
+  [TOOL_NAME.search]: doSearch,
+  [TOOL_NAME.symbolSearch]: (a, c) => doLsp(TOOL_NAME.symbolSearch, a, c),
+  [TOOL_NAME.findReferences]: (a, c) => doLsp(TOOL_NAME.findReferences, a, c),
+  [TOOL_NAME.typeAt]: (a, c) => doLsp(TOOL_NAME.typeAt, a, c),
+  [TOOL_NAME.diagnostics]: (a, c) => doLsp(TOOL_NAME.diagnostics, a, c),
+  [TOOL_NAME.renameSymbol]: (a, c) => doLsp(TOOL_NAME.renameSymbol, a, c),
+  [TOOL_NAME.organizeImports]: (a, c) => doLsp(TOOL_NAME.organizeImports, a, c),
+  [TOOL_NAME.scaffoldUi]: doScaffoldUi,
+  [TOOL_NAME.scaffoldRoutes]: doScaffoldRoutes,
+  [TOOL_NAME.scaffoldWeb]: doScaffoldWeb,
+  [TOOL_NAME.addDependency]: doAddDependency,
+  // yield_status is intercepted by the Session BEFORE tool dispatch (it ends the
+  // turn); this handler only fires if one slips through with other calls.
+  [TOOL_NAME.yieldStatus]: () =>
+    "(turn continues — finish the work, then yield alone)",
+};
+
+function isToolName(name: string): name is ToolName {
+  return Object.hasOwn(HANDLERS, name);
+}
+
+/**
+ * Perform one tool call and return the text result fed back to the model as a
+ * tool message. Dispatch only — the handlers live in file-ops (read/run/edit/
+ * create) and lsp-ops (search + the semantic tools); scope enforcement and arg
+ * parsing live with each handler (tool-context holds the shared helpers).
+ */
+export async function executeTool(
+  call: IToolCall,
+  ctx: IToolContext
+): Promise<string> {
+  if (!isToolName(call.name)) {
+    return `unknown tool: ${call.name}`;
+  }
+
+  // PLAN MODE hard guard: the advertised tool list already omits mutating tools,
+  // but a salvaged/forced call can name anything — reject it here so plan mode
+  // is a guarantee, not a convention. (`run` passes; its handler enforces a
+  // read-only command allowlist.)
+  if (
+    ctx.readOnly === true &&
+    !READ_ONLY_TOOL_NAMES.has(call.name) &&
+    call.name !== TOOL_NAME.run
+  ) {
+    return reject(
+      ctx,
+      call.name,
+      `plan mode: \`${call.name}\` is disabled — explore with read-only tools and ` +
+        "present your plan as text; the user must approve it before files can change."
+    );
+  }
+
+  return HANDLERS[call.name](call.arguments, ctx);
+}

package/src/loop/tools/file-ops.ts

@@ -0,0 +1,323 @@
+import { join } from "node:path";
+import { applyEdits } from "../../files/edit";
+import { applyCreate } from "../../files/create";
+import { EDIT_FAIL_REASON } from "../../files";
+import { writable, normalizeWorkspacePath } from "../../lib/scope";
+import { LOOP_LIMITS } from "../loop.constants";
+import { toEdits, toCreate, toRun, toRead, runCommand } from "../../agent";
+import { ruleHelpFromOutput } from "../feedback/rule-docs";
+import { condenseToolOutput } from "./condense";
+import { parseOrRepair, reject, type IToolContext } from "./tool-context";
+import { formatHashHeader, HL_LINE_SEP } from "../../files/hashline-format";
+import { SessionSnapshotStore } from "../../files/hashline";
+import { flags } from "../../config";
+
+/**
+ * Read a file for the model. TRUSTED-MODE (by design): `read` and `run` are NOT
+ * sandboxed to the workspace — a `../config` read or any shell command the
+ * process can run is permitted, like a local human-run coding agent (Claude Code,
+ * etc.). Only WRITES (`edit`/`create`) are scope-enforced, since those are what
+ * mutate the user's project. tsforge runs locally on the user's own machine
+ * against their own code; the threat model is mistakes, not a hostile operator.
+ * (Sandboxing reads would be a separate, explicit execution profile.)
+ */
+export async function readFile(
+  args: Record<string, unknown>,
+  ctx: IToolContext & { snapshotStore?: SessionSnapshotStore }
+): Promise<string> {
+  const { value: r, feedback } = parseOrRepair(args, toRead, ctx, "read");
+
+  if (r === null) {
+    if (feedback !== undefined && feedback.length > 0) {
+      return feedback;
+    }
+
+    return "read: malformed args (need `file`)";
+  }
+
+  r.file = normalizeWorkspacePath(ctx.cwd, r.file);
+
+  ctx.report({ kind: "tool", task: ctx.task, message: `read ${r.file}` });
+
+  const handle = Bun.file(join(ctx.cwd, r.file));
+
+  if (!(await handle.exists())) {
+    return `read: ${r.file} does not exist`;
+  }
+
+  const content = await handle.text();
+
+  // Annotate with hashline header if enabled
+  if (flags.hashlineEditTool()) {
+    ctx.snapshotStore ??= new SessionSnapshotStore();
+
+    const hash = ctx.snapshotStore.record(r.file, content);
+    const header = formatHashHeader(r.file, hash);
+    const lines = content.split("\n");
+    const annotated = lines
+      .map((line, i) => `${i + 1}${HL_LINE_SEP}${line}`)
+      .join("\n");
+
+    return `${header}\n${annotated}`;
+  }
+
+  return content;
+}
+
+/** Commands a plan-mode `run` may execute — pure inspection, never mutation. */
+const READ_ONLY_COMMANDS = new Set([
+  "ls",
+  "cat",
+  "head",
+  "tail",
+  "wc",
+  "rg",
+  "grep",
+  "find",
+  "tree",
+  "stat",
+  "file",
+  "which",
+  "du",
+  "tsc",
+  "git",
+]);
+
+/** Git subcommands that only inspect the repo. */
+const READ_ONLY_GIT = new Set(["status", "log", "diff", "show", "branch"]);
+
+/** Shell metacharacters that could turn a read into a write (`> out`, `&& rm`,
+ *  `| tee`, command substitution). Their PRESENCE disqualifies — conservative. */
+const SHELL_WRITE_RE = /[>;&|`]|\$\(/;
+
+/**
+ * Deterministically read-only: exactly one allowlisted command, no redirects/
+ * pipes/chaining. Used by plan mode so the model can explore (`ls`, `rg`,
+ * `git log`, `tsc --noEmit`) without any path to mutating the workspace.
+ */
+export function isReadOnlyCommand(command: string): boolean {
+  if (SHELL_WRITE_RE.test(command)) {
+    return false;
+  }
+
+  const [head, sub] = command.trim().split(/\s+/);
+
+  if (head === undefined || !READ_ONLY_COMMANDS.has(head)) {
+    return false;
+  }
+
+  if (head === "git") {
+    return sub !== undefined && READ_ONLY_GIT.has(sub);
+  }
+
+  return true;
+}
+
+export async function runShell(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  const { value: r, feedback } = parseOrRepair(args, toRun, ctx, "run");
+
+  if (r === null) {
+    if (feedback !== undefined && feedback.length > 0) {
+      return feedback;
+    }
+
+    return "run: malformed args (need `command`)";
+  }
+
+  if (ctx.readOnly === true && !isReadOnlyCommand(r.command)) {
+    return reject(
+      ctx,
+      "run",
+      "plan mode: only read-only commands are allowed (ls, cat, rg, grep, find, " +
+        `git status/log/diff/show/branch, tsc — no pipes/redirects). Blocked: ${r.command}`
+    );
+  }
+
+  const res = await runCommand(
+    ctx.cwd,
+    r.command,
+    ctx.signal === undefined ? {} : { signal: ctx.signal }
+  );
+  const raw = `${res.stdout}${res.stderr}`;
+  // Condition the output for the model through the single condensing pipeline
+  // (progress-strip → shape/per-tool condensers → signal-preserving truncation).
+  // Anything unrecognized — and any real FAILURE's errors — passes through.
+  const { text: output, via } = condenseToolOutput(
+    { command: r.command, output: raw, exitCode: res.exitCode },
+    LOOP_LIMITS.maxToolOutputChars
+  );
+
+  // Make the saving observable (and let us SPOT over-condensing in the log).
+  if (via !== null && output.length < raw.length) {
+    ctx.report({
+      kind: "tool",
+      task: ctx.task,
+      message: `condensed ${String(raw.length)}→${String(output.length)} chars via ${via}`,
+    });
+  }
+
+  // If the command surfaced lint/type errors, attach the failing rules' own
+  // bad→good docs to what the model reads — so it fixes from examples, not blind.
+  const help = res.exitCode === 0 ? "" : ruleHelpFromOutput(output);
+  const guidance =
+    help.length > 0 ? `\n\nFix guidance for the failing rules:\n${help}` : "";
+
+  // Log the guidance too (in the event output) so we can SEE the injection fire,
+  // not just feed it silently to the model.
+  ctx.report({
+    kind: "run",
+    task: ctx.task,
+    message: `$ ${r.command}`,
+    command: r.command,
+    exitCode: res.exitCode,
+    output: `${output}${guidance}`,
+  });
+
+  return `exit ${res.exitCode}\n${output}${guidance}`;
+}
+
+export async function doEdit(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  const { value: edit, feedback } = parseOrRepair(args, toEdits, ctx, "edit");
+
+  if (edit === null) {
+    if (feedback !== undefined && feedback.length > 0) {
+      return feedback;
+    }
+
+    return "edit: malformed args (need `file` plus either `oldString`/`newString` or an `edits` array of {oldString,newString})";
+  }
+
+  edit.file = normalizeWorkspacePath(ctx.cwd, edit.file);
+
+  if (!writable(edit.file, ctx.files)) {
+    return reject(
+      ctx,
+      "edit",
+      `edit ${edit.file} REJECTED: out of scope. You may only edit/create: ${ctx.files.join(", ")} (or throwaway files under scratch/).`
+    );
+  }
+
+  // The size cap is PER replacement — each piece must be surgical (no lazy
+  // whole-function rewrite) — but a batch may carry many pieces, so the model
+  // can fix the same issue at several spread-out sites in ONE turn.
+  for (let i = 0; i < edit.edits.length; i += 1) {
+    const span = (edit.edits[i]?.oldString ?? "").split("\n").length;
+
+    if (span > LOOP_LIMITS.maxEditLines) {
+      return reject(
+        ctx,
+        "edit",
+        `edit ${edit.file} REJECTED: replacement #${i + 1} is too large (${span} lines). Change ONLY the broken lines — make small, targeted replacements (the gate names the exact lines). To fix several spots, pass each as its own entry in \`edits\`; don't rewrite a whole function.`
+      );
+    }
+  }
+
+  const result = await applyEdits(ctx.cwd, edit.file, edit.edits);
+
+  if (result.ok) {
+    for (const r of edit.edits) {
+      ctx.report({
+        kind: "edit",
+        task: ctx.task,
+        file: edit.file,
+        message: `edit ${edit.file}`,
+        oldString: r.oldString,
+        newString: r.newString,
+      });
+    }
+
+    return `edited ${edit.file} (${result.count} change${result.count === 1 ? "" : "s"})`;
+  }
+
+  const where =
+    edit.edits.length > 1 ? ` (replacement #${result.index + 1})` : "";
+
+  return reject(
+    ctx,
+    `edit:${result.reason}`,
+    `edit ${edit.file} REJECTED${where}: ${editFailHelp(edit.file, result)}`
+  );
+}
+
+/**
+ * Turn an edit-failure reason into ACTIONABLE feedback. The bare reason strings
+ * ("not-found", "missing-file") were fatally ambiguous: a slow local model read
+ * an edit's "not-found" (= the oldString wasn't in the file) as "the FILE wasn't
+ * found", switched to `create`, hit "already exists", and thrashed edit↔create to
+ * the turn cap. Each message now says exactly what failed AND what to do next —
+ * crucially, whether the file exists (don't `create`) or not (do `create`).
+ */
+function editFailHelp(
+  file: string,
+  result: { reason: string; matches?: number }
+): string {
+  if (result.reason === EDIT_FAIL_REASON.ambiguous) {
+    return `oldString matched ${result.matches ?? 0} places — include more surrounding lines to make it unique`;
+  }
+
+  if (result.reason === EDIT_FAIL_REASON.missingFile) {
+    return `the file ${file} does not exist yet — use \`create\` to make it (NOT edit)`;
+  }
+
+  if (result.reason === EDIT_FAIL_REASON.notFound) {
+    return `the file ${file} EXISTS, but your oldString text was not found in it. Do NOT use \`create\` (it already exists). \`read\` the file to see its exact current contents, then edit with text copied verbatim from it.`;
+  }
+
+  return result.reason;
+}
+
+export async function doCreate(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  const { value: create, feedback } = parseOrRepair(
+    args,
+    toCreate,
+    ctx,
+    "create"
+  );
+
+  if (create === null) {
+    if (feedback !== undefined && feedback.length > 0) {
+      return feedback;
+    }
+
+    return "create: malformed args (need file, content)";
+  }
+
+  create.file = normalizeWorkspacePath(ctx.cwd, create.file);
+
+  if (!writable(create.file, ctx.files)) {
+    return reject(
+      ctx,
+      "create",
+      `create ${create.file} REJECTED: out of scope. You may only edit/create: ${ctx.files.join(", ")} (or throwaway files under scratch/).`
+    );
+  }
+
+  const result = await applyCreate(ctx.cwd, create);
+
+  if (result.ok) {
+    ctx.report({
+      kind: "create",
+      task: ctx.task,
+      file: create.file,
+      message: `create ${create.file}`,
+      content: create.content,
+    });
+
+    return `created ${create.file}`;
+  }
+
+  return reject(
+    ctx,
+    "create:exists",
+    `create ${create.file} REJECTED: already exists — use \`edit\``
+  );
+}

package/src/loop/tools/index.ts

@@ -0,0 +1,2 @@
+export { executeTool } from "./execute-tool";
+export type { IToolContext } from "./tool-context";

package/src/loop/tools/lsp-ops.ts

@@ -0,0 +1,222 @@
+import { relative } from "node:path";
+import { fileArg, TOOL_NAME, type ToolName } from "../../agent";
+import { runArgvCommand } from "../../lib/fs";
+import { writable } from "../../lib/scope";
+import { LOOP_LIMITS } from "../loop.constants";
+import { str, reject, type IToolContext } from "./tool-context";
+
+/** ripgrep search over the working dir — the model's primary navigation at
+ *  scale (structural/text, fast). Falls back gracefully if `rg` is absent. */
+export async function doSearch(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  const fromPattern = str(args, "pattern");
+  const pattern = fromPattern.length > 0 ? fromPattern : str(args, "query");
+
+  if (pattern.length === 0) {
+    return "search: malformed args (need `pattern`)";
+  }
+
+  const glob = str(args, "glob");
+  // Spawn rg with an explicit argv (NO shell) — the pattern/glob come from the
+  // model, so a `sh -c` string would let `$()`/backticks inside them execute.
+  const argv = [
+    "rg",
+    "--line-number",
+    "--no-heading",
+    "--color",
+    "never",
+    "-e",
+    pattern,
+    ...(glob.length > 0 ? ["-g", glob] : []),
+  ];
+  const res = await runArgvCommand(
+    ctx.cwd,
+    argv,
+    ctx.signal === undefined ? {} : { signal: ctx.signal }
+  );
+  // rg exits 1 when there are simply no matches (not an error); 2 = real error,
+  // 127 = rg absent. Surface stderr only on a real failure, not on "no matches".
+  const body = res.exitCode > 1 ? `${res.stdout}${res.stderr}` : res.stdout;
+  const out = body.slice(0, LOOP_LIMITS.maxToolOutputChars);
+
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `search ${pattern}${glob.length > 0 ? ` (${glob})` : ""}`,
+  });
+
+  return out.trim().length > 0 ? out : `no matches for ${pattern}`;
+}
+
+/** Dispatch the semantic (LanguageService-backed) tools. The model addresses
+ *  symbols by NAME + file; read-only tools are unrestricted, the two that WRITE
+ *  (rename_symbol, organize_imports) are scope-enforced. */
+export function doLsp(
+  name: ToolName,
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): string {
+  const svc = ctx.tsService;
+
+  if (svc === undefined || svc === null) {
+    return `${name}: unavailable (this project has no TypeScript LanguageService)`;
+  }
+
+  const file = fileArg(args) ?? "";
+  const rel = (abs: string): string => relative(ctx.cwd, abs);
+
+  if (name === TOOL_NAME.symbolSearch) {
+    const q = str(args, "query");
+    const query = q.length > 0 ? q : str(args, "symbol");
+
+    if (query.length === 0) {
+      return "symbol_search: need `query`";
+    }
+
+    const hits = svc.symbols(query);
+
+    ctx.report({
+      kind: "tool",
+      task: ctx.task,
+      message: `symbol_search ${query} → ${hits.length}`,
+    });
+
+    return hits.length === 0
+      ? `no symbols matching '${query}'`
+      : hits
+          .map((h) => `${h.kind} ${h.name} — ${rel(h.file)}:${h.line}`)
+          .join("\n");
+  }
+
+  if (name === TOOL_NAME.diagnostics) {
+    if (file.length === 0) {
+      return "diagnostics: need `file`";
+    }
+
+    const diags = svc.diagnostics(file);
+
+    ctx.report({
+      kind: "tool",
+      task: ctx.task,
+      message: `diagnostics ${file} → ${diags.length}`,
+    });
+
+    return diags.length === 0
+      ? `no semantic diagnostics in ${file}`
+      : diags
+          .map((d) => `TS${d.code}: ${d.message.split("\n")[0] ?? d.message}`)
+          .join("\n");
+  }
+
+  // organize_imports operates on a whole FILE (no symbol/position) — handle it
+  // here, before doSymbolLsp's `need {file, symbol}` guard would wrongly reject a
+  // valid `{file}`-only call (its schema requires only `file`). See P1 review.
+  if (name === TOOL_NAME.organizeImports) {
+    if (file.length === 0) {
+      return "organize_imports: need `file`";
+    }
+
+    if (!writable(file, ctx.files)) {
+      return reject(
+        ctx,
+        "organize_imports",
+        `organize_imports ${file} REJECTED: out of scope.`
+      );
+    }
+
+    const n = svc.organizeImports(file);
+
+    ctx.report({
+      kind: "tool",
+      task: ctx.task,
+      message: `organize_imports ${file} (${n})`,
+    });
+
+    return `organize_imports: ${n} change(s) in ${file}`;
+  }
+
+  // The remaining tools address a symbol by name within a file.
+  return doSymbolLsp(name, svc, file, args, ctx, rel);
+}
+
+type LspService = NonNullable<IToolContext["tsService"]>;
+
+/** The LSP tools that resolve a symbol position first (type_at, find_references,
+ *  rename_symbol). Split out of doLsp to keep each function's branching small. */
+function doSymbolLsp(
+  name: ToolName,
+  svc: LspService,
+  file: string,
+  args: Record<string, unknown>,
+  ctx: IToolContext,
+  rel: (abs: string) => string
+): string {
+  const symbol = str(args, "symbol");
+
+  if (file.length === 0 || symbol.length === 0) {
+    return `${name}: need {file, symbol}`;
+  }
+
+  const pos = svc.positionOfSymbol(file, symbol);
+
+  if (pos === undefined) {
+    return `${name}: '${symbol}' not found in ${file}`;
+  }
+
+  if (name === TOOL_NAME.typeAt) {
+    const type = svc.typeAt(file, pos);
+
+    ctx.report({ kind: "tool", task: ctx.task, message: `type_at ${symbol}` });
+
+    return type.length > 0
+      ? `${symbol}: ${type}`
+      : `no type info for ${symbol}`;
+  }
+
+  if (name === TOOL_NAME.findReferences) {
+    const refs = svc.references(file, pos);
+
+    ctx.report({
+      kind: "tool",
+      task: ctx.task,
+      message: `find_references ${symbol} → ${refs.length}`,
+    });
+
+    return refs.length === 0
+      ? `no references to '${symbol}'`
+      : refs.map((r) => `${rel(r.file)}:${r.line}`).join("\n");
+  }
+
+  // rename_symbol — scope-enforced: a semantic rename can touch many files; it
+  // must NOT edit read-only/out-of-scope ones.
+  const newName = str(args, "newName");
+
+  if (newName.length === 0) {
+    return "rename_symbol: need `newName`";
+  }
+
+  const targets = svc.renameTargets(file, pos).map(rel);
+  const outOfScope = targets.filter((t) => !writable(t, ctx.files));
+
+  if (outOfScope.length > 0) {
+    return reject(
+      ctx,
+      "rename_symbol",
+      `rename '${symbol}' REJECTED: would edit out-of-scope/read-only file(s): ${outOfScope.join(", ")}. Rename only symbols whose every reference is in your editable files.`
+    );
+  }
+
+  const changed = svc.rename(file, pos, newName);
+
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `rename_symbol ${symbol}→${newName} (${changed ?? 0})`,
+  });
+
+  return changed === null
+    ? `rename_symbol: '${symbol}' can't be renamed here`
+    : `renamed '${symbol}' → '${newName}' across ${changed} location(s)`;
+}

package/src/loop/tools/scaffold-routes.ts

@@ -0,0 +1,68 @@
+import { join } from "node:path";
+import { writable, normalizeWorkspacePath } from "../../lib/scope";
+import { materializeRoutes, asRoutePaths } from "../../web-routes";
+import { type IToolContext } from "./tool-context";
+
+/**
+ * `scaffold_routes` — materialize ALL of an app's routes as file-based stubs from
+ * a model-declared path list, so the route union is complete up front and no
+ * `<Link to>` can forward-reference a missing route (the error class that ate ~1/3
+ * of multi-route builds). The model owns WHAT (which pages — app-specific); this
+ * owns HOW (correct createFileRoute + $param filename mapping). Like scaffold_ui:
+ * overwrites stubs idempotently and reports ONE summary event (not per-file
+ * `create`s) so the write-guard doesn't re-check the generated shells.
+ */
+export async function doScaffoldRoutes(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  const paths = asRoutePaths(args.routes);
+
+  if (paths.length === 0) {
+    return 'scaffold_routes REJECTED: `routes` must be a non-empty array of path strings (e.g. ["/", "/accounts", "/accounts/$accountId"]).';
+  }
+
+  const files = materializeRoutes(paths);
+  const written: string[] = [];
+  const kept: string[] = [];
+
+  for (const [rel, content] of Object.entries(files)) {
+    const path = normalizeWorkspacePath(ctx.cwd, rel);
+
+    if (!writable(path, ctx.files)) {
+      continue;
+    }
+
+    // NEVER overwrite an existing route file — it may already be FILLED with the
+    // real page. scaffold_routes is idempotent + additive: it only stubs routes
+    // that don't exist yet. (Re-calling it to add new pages used to clobber every
+    // already-built page back to a stub → an endless re-fill loop.)
+    if (await Bun.file(join(ctx.cwd, path)).exists()) {
+      kept.push(path);
+      continue;
+    }
+
+    await Bun.write(join(ctx.cwd, path), content);
+    written.push(path);
+  }
+
+  const keptNote =
+    kept.length > 0
+      ? ` (kept ${String(kept.length)} existing route(s) untouched)`
+      : "";
+
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `scaffold_routes: created ${String(written.length)} new route stub(s)${keptNote}`,
+  });
+
+  return (
+    `scaffold_routes: created ${String(written.length)} NEW route stub(s)${keptNote}. ` +
+    `It is ADDITIVE and safe to call again — it NEVER overwrites a route you've already ` +
+    `built, only adds missing ones. New stubs are PLACEHOLDERS (data-tsforge-stub): replace ` +
+    `EACH with the real page (its list/detail/form using your types + useCollection(service) ` +
+    `+ @/components/ui). The gate FAILS while any stub remains. To FILL a route, EDIT its file ` +
+    `directly — do NOT call scaffold_routes again to "reset" it.`
+  );
+}