feat(03-01): create WorktreeManager port interface

- Worktree type for representing git worktrees
- WorktreeDiff type for change preview
- MergeResult type for merge operation results
- WorktreeManager interface (PORT) with CRUD, diff, and merge methods
- Full JSDoc documentation explaining port-adapter relationship

Covers requirements: GIT-01, GIT-02, GIT-03, GIT-04

src/git/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Git Module - Public API
+ *
+ * Exports the WorktreeManager port interface and types.
+ * All modules should import from this index file.
+ *
+ * Pattern follows EventBus module:
+ * - Port interface (WorktreeManager) is what consumers depend on
+ * - Adapter implementations will be added in future plans
+ */
+
+// Port interface (what consumers depend on)
+export type { WorktreeManager } from './types.js';
+
+// Domain types
+export type { Worktree, WorktreeDiff, MergeResult } from './types.js';

src/git/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Git Module Types
+ *
+ * Port interface for git worktree operations.
+ * WorktreeManager is the PORT. Implementations (GitWorktreeManager, MockWorktreeManager) are ADAPTERS.
+ *
+ * This follows the same hexagonal architecture pattern as EventBus:
+ * - Interface defines the contract (port)
+ * - Implementations can be swapped without changing consumers
+ * - Enables testing with in-memory/mock implementations
+ */
+
+// =============================================================================
+// Worktree Domain Types
+// =============================================================================
+
+/**
+ * Represents a git worktree - an isolated working directory
+ * that shares the same git repository but has its own branch.
+ */
+export interface Worktree {
+  /** Unique identifier for this worktree */
+  id: string;
+  /** Branch name checked out in this worktree */
+  branch: string;
+  /** Absolute path to the worktree directory */
+  path: string;
+  /** True if this is the main worktree (the original checkout) */
+  isMainWorktree: boolean;
+}
+
+/**
+ * Represents the diff/changes in a worktree compared to its base.
+ * Used for previewing what will be merged.
+ */
+export interface WorktreeDiff {
+  /** List of files with changes */
+  files: Array<{
+    /** Relative path to the file */
+    path: string;
+    /** Type of change */
+    status: 'added' | 'modified' | 'deleted';
+  }>;
+  /** Human-readable summary of changes (e.g., "3 files changed, 45 insertions") */
+  summary: string;
+}
+
+/**
+ * Result of a merge operation.
+ * Success means clean merge; failure means conflicts that need resolution.
+ */
+export interface MergeResult {
+  /** True if merge completed without conflicts */
+  success: boolean;
+  /** List of conflicting files (only present if success is false) */
+  conflicts?: string[];
+  /** Human-readable message describing the result */
+  message: string;
+}
+
+// =============================================================================
+// WorktreeManager Port Interface
+// =============================================================================
+
+/**
+ * WorktreeManager Port Interface
+ *
+ * Manages git worktrees for isolated agent workspaces.
+ * Each agent gets its own worktree to avoid file conflicts.
+ *
+ * This is the PORT - implementations (adapters) include:
+ * - GitWorktreeManager: Real git operations via CLI
+ * - MockWorktreeManager: In-memory for testing
+ *
+ * Covers requirements:
+ * - GIT-01: Create worktree for agent
+ * - GIT-02: List/get worktrees
+ * - GIT-03: Preview diff before merge
+ * - GIT-04: Merge worktree back and cleanup
+ */
+export interface WorktreeManager {
+  /**
+   * Create a new worktree for isolated agent work.
+   *
+   * Creates a new branch and worktree directory.
+   * The worktree will be ready for the agent to start working.
+   *
+   * @param id - Unique identifier for the worktree (usually agent/task ID)
+   * @param branch - Branch name to create
+   * @param baseBranch - Branch to base the new branch on (defaults to current branch)
+   * @returns The created worktree
+   * @throws If worktree creation fails (e.g., branch already exists)
+   */
+  create(id: string, branch: string, baseBranch?: string): Promise<Worktree>;
+
+  /**
+   * Remove a worktree and optionally its branch.
+   *
+   * Cleans up the worktree directory and removes it from git's tracking.
+   * Should be called after merge or when abandoning work.
+   *
+   * @param id - Worktree identifier
+   * @throws If worktree doesn't exist or removal fails
+   */
+  remove(id: string): Promise<void>;
+
+  /**
+   * List all worktrees in the repository.
+   *
+   * Returns all worktrees including the main one.
+   * Useful for discovering active agent workspaces.
+   *
+   * @returns Array of all worktrees
+   */
+  list(): Promise<Worktree[]>;
+
+  /**
+   * Get a specific worktree by ID.
+   *
+   * @param id - Worktree identifier
+   * @returns The worktree if found, null otherwise
+   */
+  get(id: string): Promise<Worktree | null>;
+
+  /**
+   * Get the diff/changes in a worktree.
+   *
+   * Shows what files have changed compared to the base branch.
+   * Used for previewing before merge.
+   *
+   * @param id - Worktree identifier
+   * @returns Diff information
+   * @throws If worktree doesn't exist
+   */
+  diff(id: string): Promise<WorktreeDiff>;
+
+  /**
+   * Merge worktree changes into target branch.
+   *
+   * Attempts to merge the worktree's branch into the target branch.
+   * Returns conflict information if merge cannot be completed cleanly.
+   *
+   * @param id - Worktree identifier
+   * @param targetBranch - Branch to merge into (usually 'main' or 'integration')
+   * @returns Merge result with success status and any conflicts
+   * @throws If worktree doesn't exist
+   */
+  merge(id: string, targetBranch: string): Promise<MergeResult>;
+}