gsd-pi 2.20.0 → 2.22.0

package/src/resources/extensions/gsd/collision-diagnostics.ts

@@ -0,0 +1,332 @@
+/**
+ * Collision Diagnostics Module
+ *
+ * Bridges NamespacedRegistry collision data and NamespacedResolver ambiguous
+ * resolution into a classified diagnostic taxonomy. Provides two functions:
+ * - analyzeCollisions: Scans registry and resolver state to produce classified diagnostics
+ * - doctorReport: Formats diagnostics into human-readable output with severity and remediation
+ *
+ * This module implements R010 (collision reporting) and R011 (doctor advice) for the
+ * namespaced component system.
+ */
+
+import type { NamespacedRegistry, RegistryDiagnostic } from './namespaced-registry.js';
+import type { NamespacedResolver, ResolutionResult } from './namespaced-resolver.js';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Classification of collision type.
+ * - canonical-conflict: Two plugins registered the same canonical name (hard error)
+ * - shorthand-overlap: Same bare name exists in multiple namespaces (ambiguity)
+ * - alias-conflict: Alias shadows a canonical name or bare component name
+ */
+export type CollisionClass = 'canonical-conflict' | 'shorthand-overlap' | 'alias-conflict';
+
+/**
+ * Severity level for diagnostics.
+ * - error: Hard collision that prevents correct resolution
+ * - warning: Ambiguity that may cause surprising behavior
+ */
+export type DiagnosticSeverity = 'error' | 'warning';
+
+/**
+ * A classified diagnostic with full context for remediation.
+ */
+export interface ClassifiedDiagnostic {
+	/** The collision classification */
+	class: CollisionClass;
+
+	/** Severity level */
+	severity: DiagnosticSeverity;
+
+	/** All canonical names involved in the collision */
+	involvedCanonicalNames: string[];
+
+	/** File paths to the conflicting components */
+	filePaths: string[];
+
+	/** Human-readable remediation advice */
+	remediation: string;
+
+	/** Optional: the bare name causing ambiguity (shorthand-overlap only) */
+	ambiguousBareName?: string;
+
+	/** Optional: the alias string (alias-conflict only) */
+	alias?: string;
+
+	/** Optional: the canonical name the alias points to (alias-conflict only) */
+	aliasTarget?: string;
+
+	/** Optional: type of alias conflict */
+	aliasConflictType?: 'shadows-canonical' | 'shadows-bare-name';
+}
+
+/**
+ * Doctor report with summary statistics and formatted entries.
+ */
+export interface DoctorReport {
+	/** Summary counts by class */
+	summary: {
+		/** Total diagnostics */
+		total: number;
+		/** Canonical conflicts (errors) */
+		canonicalConflicts: number;
+		/** Shorthand overlaps (warnings) */
+		shorthandOverlaps: number;
+		/** Alias conflicts (warnings) */
+		aliasConflicts: number;
+	};
+
+	/** Formatted report entries */
+	entries: string[];
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Analyze a registry and resolver to produce classified diagnostics.
+ *
+ * This function:
+ * 1. Reads registry.getDiagnostics() for canonical conflicts (→ error severity)
+ * 2. Groups registry.getAll() by bare component.name
+ * 3. For groups with 2+ entries, calls resolver.resolve(bareName) to confirm ambiguity
+ * 4. Produces warning diagnostics for ambiguous shorthand resolution
+ *
+ * @param registry - The namespaced registry to analyze
+ * @param resolver - The resolver to test ambiguity
+ * @returns Array of classified diagnostics
+ */
+export function analyzeCollisions(
+	registry: NamespacedRegistry,
+	resolver: NamespacedResolver
+): ClassifiedDiagnostic[] {
+	const diagnostics: ClassifiedDiagnostic[] = [];
+
+	// Step 1: Process canonical conflicts from registry diagnostics
+	const registryDiagnostics = registry.getDiagnostics();
+	for (const diag of registryDiagnostics) {
+		if (diag.type === 'collision') {
+			diagnostics.push({
+				class: 'canonical-conflict',
+				severity: 'error',
+				involvedCanonicalNames: [diag.collision.canonicalName],
+				filePaths: [diag.collision.winnerPath, diag.collision.loserPath],
+				remediation: `Canonical name "${diag.collision.canonicalName}" registered multiple times. ` +
+					`The first registration (${diag.collision.winnerSource ?? 'unknown source'}) ` +
+					`took precedence over subsequent registration (${diag.collision.loserSource ?? 'unknown source'}). ` +
+					`Rename one of the conflicting components to resolve.`,
+			});
+		}
+	}
+
+	// Step 2: Find shorthand overlaps by grouping components by bare name
+	const components = registry.getAll();
+	const byBareName = new Map<string, typeof components>();
+
+	for (const component of components) {
+		const bareName = component.name;
+		if (!byBareName.has(bareName)) {
+			byBareName.set(bareName, []);
+		}
+		byBareName.get(bareName)!.push(component);
+	}
+
+	// Step 3: For groups with 2+ entries, check if resolver confirms ambiguity
+	for (const [bareName, candidates] of byBareName) {
+		if (candidates.length >= 2) {
+			// Use resolver to confirm ambiguity
+			const result = resolver.resolve(bareName);
+
+			if (result.resolution === 'ambiguous') {
+				// This is a shorthand overlap
+				const canonicalNames = candidates.map(c => c.canonicalName);
+				const filePaths = candidates.map(c => c.filePath);
+
+				diagnostics.push({
+					class: 'shorthand-overlap',
+					severity: 'warning',
+					involvedCanonicalNames: canonicalNames,
+					filePaths,
+					remediation: formatShorthandRemediation(bareName, canonicalNames),
+					ambiguousBareName: bareName,
+				});
+			}
+			// If resolution is 'shorthand' or 'local-first', the overlap is resolved
+			// unambiguously by the resolver, so we don't warn
+		}
+	}
+
+	// Step 4: Check for alias conflicts
+	const aliases = registry.getAliases();
+	const canonicalNamesSet = new Set(components.map(c => c.canonicalName));
+
+	for (const [alias, targetCanonical] of aliases) {
+		// Check if alias shadows a canonical name
+		// (This can happen if a component was registered AFTER the alias was created)
+		if (canonicalNamesSet.has(alias)) {
+			const shadowedComponent = components.find(c => c.canonicalName === alias);
+			const aliasedComponent = components.find(c => c.canonicalName === targetCanonical);
+
+			diagnostics.push({
+				class: 'alias-conflict',
+				severity: 'warning',
+				involvedCanonicalNames: [alias, targetCanonical],
+				filePaths: [
+					shadowedComponent?.filePath ?? '<unknown>',
+					aliasedComponent?.filePath ?? '<unknown>',
+				],
+				remediation: formatAliasShadowsCanonicalRemediation(alias, targetCanonical),
+				alias,
+				aliasTarget: targetCanonical,
+				aliasConflictType: 'shadows-canonical',
+			});
+			continue; // Skip further checks for this alias
+		}
+
+		// Check if alias shadows a bare name (matches component.name in any namespace)
+		const matchingBareNames = components.filter(c => c.name === alias);
+		if (matchingBareNames.length > 0) {
+			const filePaths = matchingBareNames.map(c => c.filePath);
+			const aliasedComponent = components.find(c => c.canonicalName === targetCanonical);
+			if (aliasedComponent) filePaths.push(aliasedComponent.filePath);
+
+			diagnostics.push({
+				class: 'alias-conflict',
+				severity: 'warning',
+				involvedCanonicalNames: [targetCanonical, ...matchingBareNames.map(c => c.canonicalName)],
+				filePaths,
+				remediation: formatAliasShadowsBareNameRemediation(alias, targetCanonical, matchingBareNames.map(c => c.canonicalName)),
+				alias,
+				aliasTarget: targetCanonical,
+				aliasConflictType: 'shadows-bare-name',
+			});
+		}
+	}
+
+	return diagnostics;
+}
+
+/**
+ * Format remediation advice for shorthand overlap.
+ *
+ * @param bareName - The ambiguous bare name
+ * @param canonicalNames - All canonical names that match
+ * @returns Human-readable remediation message
+ */
+function formatShorthandRemediation(bareName: string, canonicalNames: string[]): string {
+	const suggestions = canonicalNames
+		.map(cn => `\`${cn}\``)
+		.join(', ');
+
+	return `Bare name "${bareName}" is ambiguous across ${canonicalNames.length} namespaces. ` +
+		`Use a canonical name (${suggestions}) to avoid ambiguity.`;
+}
+
+/**
+ * Format remediation advice for alias shadowing a canonical name.
+ *
+ * @param alias - The alias that shadows a canonical name
+ * @param targetCanonical - The canonical name the alias points to
+ * @returns Human-readable remediation message
+ */
+function formatAliasShadowsCanonicalRemediation(alias: string, targetCanonical: string): string {
+	return `Alias "${alias}" shadows an existing canonical name. ` +
+		`The alias points to "${targetCanonical}", but resolving "${alias}" will now match the component, not the alias. ` +
+		`Consider rename or remove the alias to avoid confusion.`;
+}
+
+/**
+ * Format remediation advice for alias shadowing a bare name.
+ *
+ * @param alias - The alias that shadows bare names
+ * @param targetCanonical - The canonical name the alias points to
+ * @param shadowedCanonicals - The canonical names whose bare names are shadowed
+ * @returns Human-readable remediation message
+ */
+function formatAliasShadowsBareNameRemediation(
+	alias: string,
+	targetCanonical: string,
+	shadowedCanonicals: string[]
+): string {
+	const shadowed = shadowedCanonicals.map(cn => `\`${cn}\``).join(', ');
+	return `Alias "${alias}" shadows ${shadowedCanonicals.length} component(s) with the same bare name (${shadowed}). ` +
+		`Resolving "${alias}" will use the alias (pointing to "${targetCanonical}"), not shorthand resolution. ` +
+		`Use canonical names to be explicit, or rename the alias if this is unintended.`;
+}
+
+/**
+ * Format diagnostics into a human-readable doctor report.
+ *
+ * Each diagnostic is formatted with:
+ * - Severity icon (❌ error / ⚠️ warning)
+ * - Description of the issue
+ * - Involved file paths
+ * - Remediation advice
+ *
+ * @param diagnostics - Array of classified diagnostics
+ * @returns Doctor report with summary and formatted entries
+ */
+export function doctorReport(diagnostics: ClassifiedDiagnostic[]): DoctorReport {
+	const summary = {
+		total: diagnostics.length,
+		canonicalConflicts: diagnostics.filter(d => d.class === 'canonical-conflict').length,
+		shorthandOverlaps: diagnostics.filter(d => d.class === 'shorthand-overlap').length,
+		aliasConflicts: diagnostics.filter(d => d.class === 'alias-conflict').length,
+	};
+
+	const entries = diagnostics.map(diagnostic => formatDiagnosticEntry(diagnostic));
+
+	return { summary, entries };
+}
+
+/**
+ * Format a single diagnostic entry for display.
+ *
+ * @param diagnostic - The diagnostic to format
+ * @returns Formatted string entry
+ */
+function formatDiagnosticEntry(diagnostic: ClassifiedDiagnostic): string {
+	const icon = diagnostic.severity === 'error' ? '❌' : '⚠️';
+	const lines: string[] = [];
+
+	// Header with severity and class
+	lines.push(`${icon} ${diagnostic.class.toUpperCase()}`);
+
+	// Description
+	if (diagnostic.class === 'canonical-conflict') {
+		lines.push(`   Canonical name conflict: ${diagnostic.involvedCanonicalNames[0]}`);
+	} else if (diagnostic.class === 'alias-conflict') {
+		if (diagnostic.aliasConflictType === 'shadows-canonical') {
+			lines.push(`   Alias "${diagnostic.alias}" shadows canonical name (points to ${diagnostic.aliasTarget})`);
+		} else {
+			lines.push(`   Alias "${diagnostic.alias}" shadows bare name (points to ${diagnostic.aliasTarget})`);
+		}
+	} else {
+		lines.push(`   Shorthand overlap: "${diagnostic.ambiguousBareName}" matches ${diagnostic.involvedCanonicalNames.length} components`);
+	}
+
+	// File paths
+	lines.push('   Files:');
+	for (const path of diagnostic.filePaths) {
+		lines.push(`     - ${path}`);
+	}
+
+	// Remediation
+	lines.push(`   Remediation: ${diagnostic.remediation}`);
+
+	return lines.join('\n');
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+	analyzeCollisions,
+	doctorReport,
+};

package/src/resources/extensions/gsd/commands.ts

@@ -26,7 +26,8 @@ import {
   loadEffectiveGSDPreferences,
   resolveAllSkillReferences,
 } from "./preferences.js";
-import { loadFile, saveFile, appendOverride, appendKnowledge } from "./files.js";
+import { loadFile, saveFile, appendOverride, appendKnowledge, splitFrontmatter, parseFrontmatterMap } from "./files.js";
+import { runClaudeImportFlow } from "./claude-import.js";
 import {
   formatDoctorIssuesForPrompt,
   formatDoctorReport,
@@ -68,13 +69,13 @@ function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|migrate|remote|steer|knowledge",
+    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         "help", "next", "auto", "stop", "pause", "status", "visualize", "queue", "quick", "discuss",
         "capture", "triage",
         "history", "undo", "skip", "export", "cleanup", "mode", "prefs",
-        "config", "hooks", "run-hook", "skill-health", "doctor", "migrate", "remote", "steer", "inspect", "knowledge",
+        "config", "hooks", "run-hook", "skill-health", "doctor", "forensics", "migrate", "remote", "steer", "inspect", "knowledge",
       ];
       const parts = prefix.trim().split(/\s+/);
 
@@ -100,7 +101,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (parts[0] === "prefs" && parts.length <= 2) {
         const subPrefix = parts[1] ?? "";
-        return ["global", "project", "status", "wizard", "setup"]
+        return ["global", "project", "status", "wizard", "setup", "import-claude"]
           .filter((cmd) => cmd.startsWith(subPrefix))
           .map((cmd) => ({ value: `prefs ${cmd}`, label: cmd }));
       }
@@ -204,6 +205,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "forensics" || trimmed.startsWith("forensics ")) {
+        const { handleForensics } = await import("./forensics.js");
+        await handleForensics(trimmed.replace(/^forensics\s*/, "").trim(), ctx, pi);
+        return;
+      }
+
       if (trimmed === "next" || trimmed.startsWith("next ")) {
         if (trimmed.includes("--dry-run")) {
           await handleDryRun(ctx, projectRoot());
@@ -274,6 +281,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "cleanup") {
+        await handleCleanupBranches(ctx, projectRoot());
+        await handleCleanupSnapshots(ctx, projectRoot());
+        return;
+      }
+
       if (trimmed === "cleanup branches") {
         await handleCleanupBranches(ctx, projectRoot());
         return;
@@ -507,6 +520,15 @@ async function handlePrefs(args: string, ctx: ExtensionCommandContext): Promise<
     return;
   }
 
+  if (trimmed === "import-claude" || trimmed === "import-claude global") {
+    await handleImportClaude(ctx, "global");
+    return;
+  }
+
+  if (trimmed === "import-claude project") {
+    await handleImportClaude(ctx, "project");
+    return;
+  }
   if (trimmed === "status") {
     const globalPrefs = loadGlobalGSDPreferences();
     const projectPrefs = loadProjectGSDPreferences();
@@ -537,7 +559,38 @@ async function handlePrefs(args: string, ctx: ExtensionCommandContext): Promise<
     return;
   }
 
-  ctx.ui.notify("Usage: /gsd prefs [global|project|status|wizard|setup]", "info");
+  ctx.ui.notify("Usage: /gsd prefs [global|project|status|wizard|setup|import-claude [global|project]]", "info");
+}
+
+async function handleImportClaude(ctx: ExtensionCommandContext, scope: "global" | "project"): Promise<void> {
+  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  if (!existsSync(path)) {
+    await ensurePreferencesFile(path, ctx, scope);
+  }
+
+  const readPrefs = (): Record<string, unknown> => {
+    if (!existsSync(path)) return { version: 1 };
+    const content = readFileSync(path, "utf-8");
+    const [frontmatterLines] = splitFrontmatter(content);
+    return frontmatterLines ? parseFrontmatterMap(frontmatterLines) : { version: 1 };
+  };
+
+  const writePrefs = async (prefs: Record<string, unknown>): Promise<void> => {
+    prefs.version = prefs.version || 1;
+    const frontmatter = serializePreferencesToFrontmatter(prefs);
+    let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+    if (existsSync(path)) {
+      const existingContent = readFileSync(path, "utf-8");
+      const closingIdx = existingContent.indexOf("\n---", existingContent.indexOf("---"));
+      if (closingIdx !== -1) {
+        const afterFrontmatter = existingContent.slice(closingIdx + 4);
+        if (afterFrontmatter.trim()) body = afterFrontmatter;
+      }
+    }
+    await saveFile(path, `---\n${frontmatter}---${body}`);
+  };
+
+  await runClaudeImportFlow(ctx, scope, readPrefs, writePrefs);
 }
 
 async function handlePrefsMode(ctx: ExtensionCommandContext, scope: "global" | "project"): Promise<void> {
@@ -991,7 +1044,7 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
   const currentIsolation = git.isolation ? String(git.isolation) : "";
   const isolationChoice = await ctx.ui.select(
     `Git isolation strategy${currentIsolation ? ` (current: ${currentIsolation})` : " (default: worktree)"}:`,
-    ["worktree", "branch", "(keep current)"],
+    ["worktree", "branch", "none", "(keep current)"],
   );
   if (isolationChoice && isolationChoice !== "(keep current)") {
     git.isolation = isolationChoice;
@@ -1095,7 +1148,7 @@ async function configureNotifications(ctx: ExtensionCommandContext, prefs: Recor
 
   for (const field of notifFields) {
     const current = notif[field.key];
-    const currentStr = current !== undefined ? String(current) : "";
+    const currentStr = current !== undefined && typeof current === "boolean" ? String(current) : "";
     const choice = await ctx.ui.select(
       `${field.label}${currentStr ? ` (current: ${currentStr})` : ` (default: ${field.defaultVal})`}:`,
       ["true", "false", "(keep current)"],

package/src/resources/extensions/gsd/diff-context.ts

@@ -0,0 +1,220 @@
+/**
+ * Diff-aware context module — prioritizes recently-changed files when building
+ * context for the AI agent. Uses git diff/status to discover changes, then
+ * provides ranking utilities for context-window budget allocation.
+ *
+ * Standalone module: only imports node:child_process and node:path.
+ */
+
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ChangedFileInfo {
+  path: string;
+  changeType: "modified" | "added" | "deleted" | "staged";
+  linesChanged?: number;
+}
+
+export interface RecentFilesOptions {
+  /** Maximum number of files to return (default 20) */
+  maxFiles?: number;
+  /** Only consider commits within this many days (default 7) */
+  sinceDays?: number;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+const EXEC_OPTS = {
+  encoding: "utf-8" as const,
+  timeout: 5000,
+  stdio: ["pipe", "pipe", "pipe"] as ["pipe", "pipe", "pipe"],
+};
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, { ...EXEC_OPTS, cwd }).trim();
+}
+
+function splitLines(output: string): string[] {
+  return output
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns recently-changed file paths, deduplicated and sorted by recency
+ * (most recent first). Combines committed diffs, staged changes, and
+ * unstaged/untracked files from `git status`.
+ */
+export async function getRecentlyChangedFiles(
+  cwd: string,
+  options?: RecentFilesOptions,
+): Promise<string[]> {
+  const maxFiles = options?.maxFiles ?? 20;
+  const sinceDays = options?.sinceDays ?? 7;
+  const dir = resolve(cwd);
+
+  try {
+    // 1. Committed changes in the last N commits (or since sinceDays)
+    let committedFiles: string[] = [];
+    try {
+      const days = Math.max(1, Math.floor(Number(sinceDays)));
+      if (!Number.isFinite(days)) throw new Error("invalid sinceDays");
+      const raw = git(["log", "--diff-filter=ACMR", "--name-only", "--pretty=format:", `--since=${days} days ago`], dir);
+      committedFiles = splitLines(raw);
+    } catch {
+      // Fallback: use HEAD~10
+      try {
+        const raw = git(["diff", "--name-only", "HEAD~10"], dir);
+        committedFiles = splitLines(raw);
+      } catch {
+        // Shallow clone or <10 commits — ignore
+      }
+    }
+
+    // 2. Staged changes
+    let stagedFiles: string[] = [];
+    try {
+      const raw = git(["diff", "--cached", "--name-only"], dir);
+      stagedFiles = splitLines(raw);
+    } catch {
+      // ignore
+    }
+
+    // 3. Unstaged / untracked via porcelain status
+    let statusFiles: string[] = [];
+    try {
+      const raw = git(["status", "--porcelain"], dir);
+      statusFiles = splitLines(raw).map((line) => line.slice(3)); // strip XY + space
+    } catch {
+      // ignore
+    }
+
+    // Deduplicate, preserving insertion order (most-recent-first: status → staged → committed)
+    const seen = new Set<string>();
+    const result: string[] = [];
+    for (const file of [...statusFiles, ...stagedFiles, ...committedFiles]) {
+      if (!seen.has(file)) {
+        seen.add(file);
+        result.push(file);
+      }
+    }
+
+    return result.slice(0, maxFiles);
+  } catch {
+    // Non-git directory or git unavailable — graceful fallback
+    return [];
+  }
+}
+
+/**
+ * Returns richer change metadata: change type and approximate line counts.
+ */
+export async function getChangedFilesWithContext(
+  cwd: string,
+): Promise<ChangedFileInfo[]> {
+  const dir = resolve(cwd);
+
+  try {
+    const result: ChangedFileInfo[] = [];
+    const seen = new Set<string>();
+
+    const add = (info: ChangedFileInfo) => {
+      if (!seen.has(info.path)) {
+        seen.add(info.path);
+        result.push(info);
+      }
+    };
+
+    // 1. Staged files with numstat
+    try {
+      const numstat = git(["diff", "--cached", "--numstat"], dir);
+      for (const line of splitLines(numstat)) {
+        const [added, deleted, filePath] = line.split("\t");
+        if (!filePath) continue;
+        const lines =
+          added === "-" || deleted === "-"
+            ? undefined
+            : Number(added) + Number(deleted);
+        add({ path: filePath, changeType: "staged", linesChanged: lines });
+      }
+    } catch {
+      // ignore
+    }
+
+    // 2. Unstaged modifications with numstat
+    try {
+      const numstat = git(["diff", "--numstat"], dir);
+      for (const line of splitLines(numstat)) {
+        const [added, deleted, filePath] = line.split("\t");
+        if (!filePath) continue;
+        const lines =
+          added === "-" || deleted === "-"
+            ? undefined
+            : Number(added) + Number(deleted);
+        add({ path: filePath, changeType: "modified", linesChanged: lines });
+      }
+    } catch {
+      // ignore
+    }
+
+    // 3. Untracked / deleted from porcelain status
+    try {
+      const raw = git(["status", "--porcelain"], dir);
+      for (const line of splitLines(raw)) {
+        const code = line.slice(0, 2);
+        const filePath = line.slice(3);
+        if (seen.has(filePath)) continue;
+
+        if (code.includes("?")) {
+          add({ path: filePath, changeType: "added" });
+        } else if (code.includes("D")) {
+          add({ path: filePath, changeType: "deleted" });
+        } else if (code.includes("A")) {
+          add({ path: filePath, changeType: "added" });
+        } else {
+          add({ path: filePath, changeType: "modified" });
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Ranks a file list so that recently-changed files appear first.
+ * Files present in `changedFiles` are placed at the front (in their
+ * original changedFiles order), followed by unchanged files in their
+ * original order.
+ */
+export function rankFilesByRelevance(
+  files: string[],
+  changedFiles: string[],
+): string[] {
+  const changedSet = new Set(changedFiles);
+  const changed: string[] = [];
+  const rest: string[] = [];
+
+  for (const f of files) {
+    if (changedSet.has(f)) {
+      changed.push(f);
+    } else {
+      rest.push(f);
+    }
+  }
+
+  // Maintain changedFiles priority order within the changed group
+  const changedOrder = new Map(changedFiles.map((f, i) => [f, i]));
+  changed.sort((a, b) => (changedOrder.get(a) ?? 0) - (changedOrder.get(b) ?? 0));
+
+  return [...changed, ...rest];
+}