@flyingrobots/graft 0.6.0 → 0.7.0

package/src/mcp/tools/refactor-difficulty.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { toJsonObject } from "../../operations/result-dto.js";
+import { refactorDifficultyFromGraph } from "../../warp/refactor-difficulty.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const refactorDifficultyTool: ToolDefinition = {
+  name: "graft_difficulty",
+  description:
+    "Refactor difficulty score for a symbol. Combines WARP aggregate " +
+    "churn curvature with WARP reference-edge friction so agents can " +
+    "choose refactor vs workaround.",
+  schema: {
+    symbol: z.string(),
+    path: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const symbol = args["symbol"];
+      const rawPath = args["path"];
+      const rawLimit = args["limit"];
+
+      if (typeof symbol !== "string" || symbol.trim().length === 0) {
+        throw new Error("graft_difficulty: symbol must be a non-empty string");
+      }
+
+      const warp = await ctx.getWarp();
+      const result = await refactorDifficultyFromGraph(warp, {
+        symbol,
+        ...(typeof rawPath === "string" ? { path: rawPath } : {}),
+        ...(typeof rawLimit === "number" ? { limit: rawLimit } : {}),
+      });
+
+      ctx.recordFootprint({
+        symbols: [symbol.trim()],
+        paths: result.entries.map((entry) => entry.filePath),
+      });
+
+      return ctx.respond("graft_difficulty", toJsonObject(result));
+    };
+  },
+};

package/src/mcp/tools/safe-read.ts

@@ -58,7 +58,7 @@ export const safeReadTool: ToolDefinition = {
             });
           }
 
-          cacheResult.obs.touch();
+          cacheResult.obs.touch(ctx.cache.now());
           ctx.metrics.recordCacheHit(cf.actual.bytes);
           ctx.recordFootprint({
             symbols: cacheResult.obs.outline.map((e) => e.name),
@@ -108,7 +108,7 @@ export const safeReadTool: ToolDefinition = {
             jumpTable: cf.jumpTable,
             actual: cf.actual,
             readCount: newReadCount,
-            lastReadAt: updatedObs?.lastReadAt ?? new Date().toISOString(),
+            lastReadAt: updatedObs?.lastReadAt ?? ctx.cache.now(),
           });
         }
       }

package/src/mcp/tools/structural-blame.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { structuralBlameFromGraph } from "../../warp/warp-structural-blame.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+
+export const structuralBlameTool: ToolDefinition = {
+  name: "graft_blame",
+  description:
+    "Symbol-level blame: who last changed a symbol's signature, when " +
+    "it was created, and its full change history. Returns creation " +
+    "commit, last signature change, change count, reference count, " +
+    "and chronological history.",
+  schema: {
+    symbol: z.string(),
+    path: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const symbol = args["symbol"];
+      const rawPath = args["path"];
+
+      if (typeof symbol !== "string" || symbol.trim().length === 0) {
+        throw new Error("graft_blame: symbol must be a non-empty string");
+      }
+
+      const symbolName = symbol.trim();
+      const filePath = typeof rawPath === "string" ? rawPath : undefined;
+      const warp = await ctx.getWarp();
+
+      const blame = await structuralBlameFromGraph(
+        warp,
+        symbolName,
+        filePath ?? "",
+      );
+
+      ctx.recordFootprint({ symbols: [symbolName] });
+
+      return ctx.respond("graft_blame", toJsonObject({
+        symbol: blame.symbol,
+        filePath: blame.filePath,
+        changeCount: blame.changeCount,
+        createdInCommit: blame.createdInCommit ?? null,
+        lastSignatureChange: blame.lastSignatureChange ?? null,
+        referenceCount: blame.referenceCount,
+        history: blame.history.map((v) => ({
+          sha: v.sha,
+          tick: v.tick,
+          changeKind: v.changeKind,
+          present: v.present,
+          signature: v.signature ?? null,
+        })),
+      }));
+    };
+  },
+};

package/src/mcp/tools/structural-churn.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { toJsonObject } from "../../operations/result-dto.js";
+import { structuralChurnFromGraph } from "../../warp/warp-structural-churn.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const structuralChurnTool: ToolDefinition = {
+  name: "graft_churn",
+  description:
+    "Structural churn report — which symbols change most frequently? " +
+    "Identifies maintenance hotspots by walking indexed commits and " +
+    "counting per-symbol change frequency.",
+  schema: {
+    path: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const warp = await ctx.getWarp();
+      const options: { path?: string; limit?: number } = {};
+      const pathArg = args["path"];
+      const limitArg = args["limit"];
+      if (typeof pathArg === "string") options.path = pathArg;
+      if (typeof limitArg === "number") options.limit = limitArg;
+      const result = await structuralChurnFromGraph(warp, options);
+      return ctx.respond("graft_churn", toJsonObject(result));
+    };
+  },
+};

package/src/mcp/tools/structural-log.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { structuralLogFromGraph } from "../../warp/warp-structural-log.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const structuralLogTool: ToolDefinition = {
+  name: "graft_log",
+  description:
+    "Structural git log — shows symbol-level changes (added, removed, " +
+    "changed) per commit. Like `git log` but for code structure, not lines.",
+  schema: {
+    path: z.string().optional(),
+    limit: z.number().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const filePath = args["path"] as string | undefined;
+      const limit = args["limit"] as number | undefined;
+      const warp = await ctx.getWarp();
+
+      const options: { path?: string; limit?: number } = {};
+      if (filePath !== undefined) options.path = filePath;
+      if (limit !== undefined) options.limit = limit;
+      const entries = await structuralLogFromGraph(warp, options);
+
+      ctx.recordFootprint({
+        symbols: entries.flatMap((e) => [
+          ...e.symbols.added.map((s) => s.name),
+          ...e.symbols.removed.map((s) => s.name),
+          ...e.symbols.changed.map((s) => s.name),
+        ]),
+      });
+
+      return ctx.respond("graft_log", toJsonObject({
+        entries,
+        count: entries.length,
+        layer: "commit_worldline",
+      }));
+    };
+  },
+};

package/src/mcp/tools/structural-review.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { structuralReview, type ReferenceCountResult } from "../../operations/structural-review.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { ToolContext, ToolDefinition, ToolHandler } from "../context.js";
+import { countSymbolReferencesFromGraph } from "../../warp/warp-reference-count.js";
+import { nodePathOps } from "../../adapters/node-paths.js";
+import { countNamedImportReferencesAtRef } from "../../operations/import-reference-impact.js";
+
+async function countReviewReferences(
+  ctx: ToolContext,
+  symbolName: string,
+  filePath: string,
+  headRef: string,
+): Promise<ReferenceCountResult> {
+  const warpCtx = await ctx.getWarp();
+  const graphResult = await countSymbolReferencesFromGraph(warpCtx, symbolName, filePath);
+  if (graphResult.referenceCount > 0) {
+    return graphResult;
+  }
+
+  try {
+    const fallbackResult = await countNamedImportReferencesAtRef({
+      cwd: ctx.projectRoot,
+      git: ctx.git,
+      pathOps: nodePathOps,
+      symbolName,
+      filePath,
+      ref: headRef,
+    });
+    return fallbackResult.referenceCount > 0 ? fallbackResult : graphResult;
+  } catch {
+    return graphResult;
+  }
+}
+
+export const structuralReviewTool: ToolDefinition = {
+  name: "graft_review",
+  description:
+    "Zero-noise structural PR review. Categorizes changed files as " +
+    "structural, formatting, test, docs, or config. Detects breaking " +
+    "changes (removed exports, changed signatures) with impact counts.",
+  schema: { base: z.string().optional(), head: z.string().optional() },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const head = args["head"] as string | undefined;
+      const result = await structuralReview({
+        cwd: ctx.projectRoot,
+        fs: ctx.fs,
+        git: ctx.git,
+        resolveWorkingTreePath: (filePath) => ctx.resolvePath(filePath),
+        base: args["base"] as string | undefined,
+        head,
+        countReferences: async (symbolName, filePath) => {
+          return countReviewReferences(ctx, symbolName, filePath, head ?? "HEAD");
+        },
+      });
+      ctx.recordFootprint({
+        paths: result.files.map((f) => f.path),
+      });
+      return ctx.respond("graft_review", toJsonObject(result));
+    };
+  },
+};

package/src/mcp/warp-pool.ts

@@ -1,22 +1,22 @@
-import type { WarpHandle } from "../ports/warp.js";
+import type WarpApp from "@git-stunts/git-warp";
 import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
 
 export interface WarpPool {
-  getOrOpen(repoId: string, worktreeRoot: string, writerId?: string): Promise<WarpHandle>;
+  getOrOpen(repoId: string, worktreeRoot: string, writerId?: string): Promise<WarpApp>;
   size(): number;
 }
 
 export class InMemoryWarpPool implements WarpPool {
-  private readonly opened = new Map<string, Map<string, Promise<WarpHandle>>>();
+  private readonly opened = new Map<string, Map<string, Promise<WarpApp>>>();
 
-  constructor(private readonly openWarp: (worktreeRoot: string, writerId: string) => Promise<WarpHandle>) {}
+  constructor(private readonly openWarp: (worktreeRoot: string, writerId: string) => Promise<WarpApp>) {}
 
-  getOrOpen(repoId: string, worktreeRoot: string, writerId: string = DEFAULT_WARP_WRITER_ID): Promise<WarpHandle> {
+  getOrOpen(repoId: string, worktreeRoot: string, writerId: string = DEFAULT_WARP_WRITER_ID): Promise<WarpApp> {
     const repoHandles = this.opened.get(repoId);
     const cached = repoHandles?.get(writerId);
     if (cached !== undefined) return cached;
 
-    const nextRepoHandles = repoHandles ?? new Map<string, Promise<WarpHandle>>();
+    const nextRepoHandles = repoHandles ?? new Map<string, Promise<WarpApp>>();
     const opened = this.openWarp(worktreeRoot, writerId).catch((error: unknown) => {
       const current = this.opened.get(repoId);
       current?.delete(writerId);

package/src/mcp/workspace-router-model.ts

@@ -4,7 +4,7 @@ import type { RepoStateTracker } from "./repo-state.js";
 import type { RuntimeCausalContext } from "./runtime-causal-context.js";
 import type { PersistedLocalHistorySummary } from "./persisted-local-history.js";
 import type { GovernorTracker } from "../session/tracker.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
 
 export type WorkspaceMode = "repo_local" | "daemon";
 export type WorkspaceBindState = "bound" | "unbound";
@@ -89,7 +89,7 @@ export interface WorkspaceExecutionContext {
   readonly metrics: Metrics;
   readonly graftDir: string;
   readonly repoState: RepoStateTracker;
-  readonly getWarp: () => Promise<WarpHandle>;
+  readonly getWarp: () => Promise<WarpContext>;
 }
 
 export interface ResolvedWorkspace {

package/src/mcp/workspace-router-runtime.ts

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import { createRepoPathResolver } from "../adapters/repo-paths.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { GitClient } from "../ports/git.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
 import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
 import { GovernorTracker } from "../session/tracker.js";
 import { ObservationCache } from "./cache.js";
@@ -48,7 +48,7 @@ export interface BoundWorkspace {
   readonly warpWriterId: string;
   readonly transportSessionId: string;
   readonly slice: WorkspaceSlice;
-  readonly getWarp: () => Promise<WarpHandle>;
+  readonly getWarp: () => Promise<WarpContext>;
 }
 
 export function createWorkspaceSlice(input: {
@@ -94,11 +94,14 @@ export async function createBoundWorkspace(input: {
     transportSessionId: input.transportSessionId,
     warpWriterId: input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
     slice: input.slice,
-    getWarp: () => input.warpPool.getOrOpen(
-      input.resolved.repoId,
-      input.resolved.worktreeRoot,
-      input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
-    ),
+    getWarp: async () => ({
+      app: await input.warpPool.getOrOpen(
+        input.resolved.repoId,
+        input.resolved.worktreeRoot,
+        input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
+      ),
+      strandId: null,
+    }),
   };
 }
 
@@ -193,7 +196,7 @@ export async function resolveCheckoutBoundaryHookEvent(input: {
 
 export async function buildPersistedLocalHistoryGraphContext(
   worktreeRoot: string,
-  getWarp: () => Promise<WarpHandle>,
+  getWarp: () => Promise<WarpContext>,
 ): Promise<PersistedLocalHistoryGraphContext | null> {
   try {
     return {

package/src/mcp/workspace-router.ts

@@ -37,7 +37,7 @@ import {
 import { resolveWorkspaceRequest, stableWorkspaceId } from "./workspace-router-resolution.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { GitClient } from "../ports/git.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
 import type { JsonObject } from "../contracts/json-object.js";
 import type { WarpPool } from "./warp-pool.js";
 import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
@@ -87,6 +87,7 @@ interface WorkspaceRouterOptions {
   readonly authorizationPolicy?: WorkspaceAuthorizationPolicy | undefined;
   readonly sharedAttachPolicy?: WorkspaceSharedAttachPolicy | undefined;
   readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly persistedLocalHistoryGraph?: boolean;
 }
 
 export class WorkspaceRouter {
@@ -197,7 +198,7 @@ export class WorkspaceRouter {
     return this.requireBinding().resolvePath;
   }
 
-  getWarp(): Promise<WarpHandle> {
+  getWarp(): Promise<WarpContext> {
     return this.requireBinding().getWarp();
   }
 
@@ -670,12 +671,18 @@ export class WorkspaceRouter {
   private async buildPersistedLocalHistoryGraphContext(
     binding: BoundWorkspace,
   ): Promise<PersistedLocalHistoryGraphContext | null> {
+    if (this.options.persistedLocalHistoryGraph === false) {
+      return null;
+    }
     return buildPersistedLocalHistoryGraphContext(binding.worktreeRoot, binding.getWarp);
   }
 
   private async buildPersistedLocalHistoryGraphContextFromExecution(
     execution: WorkspaceExecutionContext,
   ): Promise<PersistedLocalHistoryGraphContext | null> {
+    if (this.options.persistedLocalHistoryGraph === false) {
+      return null;
+    }
     return buildPersistedLocalHistoryGraphContext(execution.worktreeRoot, execution.getWarp);
   }
 }

package/src/operations/adaptive-projection.ts

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// Adaptive Projection Selection — structural auto-selection
+// ---------------------------------------------------------------------------
+
+/** Structural metrics for projection selection. */
+export interface ProjectionCandidate {
+  readonly fileLines: number;
+  readonly fileBytes: number;
+  readonly symbolCount: number;
+  readonly outlineCompressionRatio: number;
+  readonly targetSymbol?: string;
+}
+
+/** Selected projection with reasoning. */
+export interface ProjectionSelection {
+  readonly projection: "outline" | "content" | "range";
+  readonly reason: string;
+}
+
+const SMALL_FILE_THRESHOLD = 50;
+const HORIZON_RATIO = 0.7;
+
+/**
+ * Select the optimal projection based on structural metrics.
+ *
+ * - Dense large files → outline (saves the most context)
+ * - Small or irreducibly complex files → content (outline doesn't help)
+ * - Targeted symbol investigation → range (surgical read)
+ */
+export function selectProjection(candidate: ProjectionCandidate): ProjectionSelection {
+  // If a specific symbol is targeted, use range
+  if (candidate.targetSymbol !== undefined) {
+    return {
+      projection: "range",
+      reason: `Targeted read for symbol "${candidate.targetSymbol}" — range is most efficient.`,
+    };
+  }
+
+  // Small files or high compression ratio → content
+  if (candidate.fileLines <= SMALL_FILE_THRESHOLD || candidate.outlineCompressionRatio >= HORIZON_RATIO) {
+    return {
+      projection: "content",
+      reason: candidate.fileLines <= SMALL_FILE_THRESHOLD
+        ? `Small file (${String(candidate.fileLines)} lines) — content fits easily.`
+        : `Outline is ${String(Math.round(candidate.outlineCompressionRatio * 100))}% of content — outline provides negligible savings.`,
+    };
+  }
+
+  // Default: outline for larger files with good compression
+  return {
+    projection: "outline",
+    reason: `${String(candidate.fileLines)} lines, ${String(candidate.symbolCount)} symbols, ${String(Math.round(candidate.outlineCompressionRatio * 100))}% compression — outline is efficient.`,
+  };
+}

package/src/operations/agent-handoff.ts

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// Agent Handoff Protocol — structured session transfer
+// ---------------------------------------------------------------------------
+
+import type { ObservationCache } from "./observation-cache.js";
+
+/** The structured handoff payload. */
+export interface HandoffPayload {
+  readonly sessionId: string;
+  readonly filesRead: readonly string[];
+  readonly symbolsInspected: readonly string[];
+  readonly observations: number;
+  readonly budgetConsumed: string;
+}
+
+/** Options for building a handoff. */
+export interface HandoffOptions {
+  readonly cache: ObservationCache;
+  readonly sessionId: string;
+  readonly budgetTotal?: number;
+  readonly budgetConsumed?: number;
+}
+
+/**
+ * Build a structured handoff payload from the current session state.
+ *
+ * Projects the observation cache into a portable JSON payload that
+ * a receiving agent can use to understand what the departing agent
+ * knew and where it left off.
+ */
+export function buildHandoff(options: HandoffOptions): HandoffPayload {
+  const { cache, sessionId } = options;
+
+  const filesRead: string[] = [];
+  const symbolsInspected: string[] = [];
+  let observationCount = 0;
+
+  for (const [filePath, observation] of cache.allEntries()) {
+    filesRead.push(filePath);
+    for (const entry of observation.outline) {
+      symbolsInspected.push(entry.name);
+    }
+    observationCount++;
+  }
+
+  let budgetStr = "unknown";
+  if (options.budgetTotal !== undefined && options.budgetConsumed !== undefined && options.budgetTotal > 0) {
+    const pct = Math.round((options.budgetConsumed / options.budgetTotal) * 100);
+    budgetStr = `${String(pct)}%`;
+  }
+
+  return {
+    sessionId,
+    filesRead,
+    symbolsInspected,
+    observations: observationCount,
+    budgetConsumed: budgetStr,
+  };
+}

package/src/operations/capture-range.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Capture Range — opaque handles for run_capture output
+// ---------------------------------------------------------------------------
+
+
+
+interface CaptureEntry {
+  readonly sessionId: string;
+  readonly content: string;
+  readonly lines: readonly string[];
+}
+
+/** Result of a range retrieval. */
+export type CaptureRangeResult =
+  | { readonly ok: true; readonly lines: readonly string[]; readonly totalLines: number }
+  | { readonly ok: false; readonly error: string };
+
+/**
+ * Registry of opaque capture handles.
+ *
+ * Maps UUIDs to capture content. Handles are session-scoped — a
+ * handle from one session is rejected in another.
+ */
+export class CaptureHandleRegistry {
+  private nextId = 0;
+  private readonly entries = new Map<string, CaptureEntry>();
+
+  /**
+   * Register capture content and return an opaque handle.
+   */
+  register(sessionId: string, content: string): string {
+    const handle = `capture-${String(++this.nextId)}`;
+    const lines = content.split("\n").filter(
+      (line, index, arr) => index < arr.length - 1 || line.length > 0,
+    );
+    this.entries.set(handle, { sessionId, content, lines });
+    return handle;
+  }
+
+  /**
+   * Retrieve a line range from a capture handle.
+   *
+   * @param handle - The opaque handle from register()
+   * @param sessionId - The requesting session (must match the registering session)
+   * @param start - 1-based start line (inclusive)
+   * @param end - 1-based end line (inclusive)
+   */
+  getRange(handle: string, sessionId: string, start: number, end: number): CaptureRangeResult {
+    const entry = this.entries.get(handle);
+    if (entry === undefined) {
+      return { ok: false, error: "Capture handle not found" };
+    }
+    if (entry.sessionId !== sessionId) {
+      return { ok: false, error: "Capture handle belongs to a different session" };
+    }
+
+    const totalLines = entry.lines.length;
+    const clampedStart = Math.max(1, start);
+    const clampedEnd = Math.min(totalLines, end);
+    const lines = entry.lines.slice(clampedStart - 1, clampedEnd);
+
+    return { ok: true, lines, totalLines };
+  }
+}

package/src/operations/conversation-primer.ts

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// Conversation Primer — auto-orient agent at session start via graft_map
+// ---------------------------------------------------------------------------
+
+import type { GitClient } from "../ports/git.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { PathOps } from "../ports/paths.js";
+
+/** Result of building a conversation primer. */
+export interface ConversationPrimerResult {
+  readonly scope: string;
+  readonly files: readonly string[];
+  readonly truncated: boolean;
+  readonly totalFiles: number;
+}
+
+/** Options for building a primer. */
+export interface ConversationPrimerOptions {
+  readonly cwd: string;
+  readonly git: GitClient;
+  readonly fs: FileSystem;
+  readonly pathOps: PathOps;
+  readonly scope?: string;
+  readonly maxFiles?: number;
+}
+
+/** Common source directory names, in priority order. */
+const COMMON_SCOPES = ["src", "lib", "app", "packages"];
+
+async function isDirectory(fileSystem: FileSystem, dirPath: string): Promise<boolean> {
+  try {
+    await fileSystem.readdir(dirPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a conversation primer for the given project.
+ *
+ * Auto-detects the best scope (src/, lib/, etc.) or uses an explicit
+ * scope. Returns a list of tracked files, truncated if beyond maxFiles.
+ */
+export async function buildConversationPrimer(
+  options: ConversationPrimerOptions,
+): Promise<ConversationPrimerResult> {
+  const { cwd, git, fs: fileSystem, pathOps, maxFiles = 50 } = options;
+
+  // Detect scope
+  let scope = options.scope ?? ".";
+  if (options.scope === undefined) {
+    for (const candidate of COMMON_SCOPES) {
+      const candidatePath = pathOps.join(cwd, candidate);
+      if (await isDirectory(fileSystem, candidatePath)) {
+        scope = candidate;
+        break;
+      }
+    }
+  }
+
+  // List tracked files via git ls-files (allowed by plumbing)
+  const lsResult = await git.run({
+    cwd,
+    args: ["ls-files", "--", scope],
+  });
+
+  const allFiles = lsResult.stdout
+    .split("\n")
+    .map((f) => f.trim())
+    .filter((f) => f.length > 0);
+
+  const truncated = allFiles.length > maxFiles;
+  const files = truncated ? allFiles.slice(0, maxFiles) : allFiles;
+
+  return {
+    scope,
+    files,
+    truncated,
+    totalFiles: allFiles.length,
+  };
+}