refactor: Address PR review feedback on shared packages

- Standardize vitest to v4.0.16 across all packages
- Clean up type imports in events.ts (remove verbose inline casting)
- Expand skipDirs to support Python, Rust, Go, PHP, Gradle projects
- Document circular dependency prevention in @automaker/types
- Add comprehensive error handling documentation to @automaker/git-utils

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

libs/git-utils/README.md

@@ -186,13 +186,73 @@ index 0000000..0000000
 
 ### Directory Filtering
 When scanning non-git directories, automatically excludes:
-- `node_modules`
-- `.git`
-- `.automaker`
-- `dist`, `build`
-- `.next`, `.nuxt`
-- `__pycache__`, `.cache`
-- `coverage`
+- `node_modules`, `.git`, `.automaker`
+- Build outputs: `dist`, `build`, `out`, `tmp`, `.tmp`
+- Framework caches: `.next`, `.nuxt`, `.cache`, `coverage`
+- Language-specific: `__pycache__` (Python), `target` (Rust), `vendor` (Go/PHP), `.gradle` (Gradle), `.venv`/`venv` (Python)
+
+## Error Handling
+
+Git operations can fail for various reasons. This package provides graceful error handling patterns:
+
+### Common Error Scenarios
+
+**1. Repository Not Found**
+```typescript
+const isRepo = await isGitRepo('/path/does/not/exist');
+// Returns: false (no exception thrown)
+```
+
+**2. Not a Git Repository**
+```typescript
+const result = await getGitRepositoryDiffs('/not/a/git/repo');
+// Fallback behavior: treats all files as "new"
+// Returns synthetic diffs for all files in directory
+```
+
+**3. Git Command Failures**
+```typescript
+// Permission errors, corrupted repos, or git not installed
+try {
+  const result = await getGitRepositoryDiffs('/project');
+} catch (error) {
+  // Handle errors from git commands
+  // Errors are logged via @automaker/utils logger
+  console.error('Git operation failed:', error);
+}
+```
+
+**4. File Read Errors**
+```typescript
+// When generating synthetic diffs for inaccessible files
+const diff = await generateSyntheticDiffForNewFile('/path', 'locked-file.txt');
+// Returns placeholder: "[Unable to read file content]"
+// Error is logged but doesn't throw
+```
+
+### Best Practices
+
+1. **Check repository status first**:
+   ```typescript
+   const isRepo = await isGitRepo(path);
+   if (!isRepo) {
+     // Handle non-git case appropriately
+   }
+   ```
+
+2. **Expect non-git directories**:
+   - `getGitRepositoryDiffs()` automatically handles both cases
+   - Always returns a valid result structure
+
+3. **Monitor logs**:
+   - Errors are logged with the `[GitUtils]` prefix
+   - Check logs for permission issues or git configuration problems
+
+4. **Handle edge cases**:
+   - Empty repositories (no commits yet)
+   - Detached HEAD states
+   - Corrupted git repositories
+   - Missing git binary
 
 ## Dependencies
 

libs/git-utils/src/diff.ts

@@ -141,7 +141,9 @@ export async function listAllFilesInDirectory(
   // Directories to skip
   const skipDirs = new Set([
     "node_modules", ".git", ".automaker", "dist", "build",
-    ".next", ".nuxt", "__pycache__", ".cache", "coverage"
+    ".next", ".nuxt", "__pycache__", ".cache", "coverage",
+    ".venv", "venv", "target", "vendor", ".gradle",
+    "out", "tmp", ".tmp"
   ]);
 
   try {

libs/platform/package.json

@@ -19,6 +19,6 @@
   "devDependencies": {
     "@types/node": "^22.10.5",
     "typescript": "^5.7.3",
-    "vitest": "^3.1.4"
+    "vitest": "^4.0.16"
   }
 }

libs/types/README.md

@@ -118,6 +118,8 @@ const options: ExecuteOptions = {
 
 None - this is a pure types package.
 
+**IMPORTANT**: This package must NEVER depend on other `@automaker/*` packages to prevent circular dependencies. All other packages depend on this one, making it the foundation of the dependency tree.
+
 ## Used By
 
 - `@automaker/utils`
@@ -127,3 +129,21 @@ None - this is a pure types package.
 - `@automaker/git-utils`
 - `@automaker/server`
 - `@automaker/ui`
+
+## Circular Dependency Prevention
+
+To maintain the package dependency hierarchy and prevent circular dependencies:
+
+1. **Never add dependencies** to other `@automaker/*` packages in `package.json`
+2. **Keep result types here** - For example, `DependencyResolutionResult` should stay in `@automaker/dependency-resolver`, not be moved here
+3. **Import only base types** - Other packages can import from here, but this package cannot import from them
+4. **Document the rule** - When adding new functionality, ensure it follows this constraint
+
+This constraint ensures a clean one-way dependency flow:
+```
+@automaker/types (foundation - no dependencies)
+    ↓
+@automaker/utils, @automaker/platform, etc.
+    ↓
+@automaker/server, @automaker/ui
+```