Path Confusion Prevention Guide

The Problem

Date: October 10, 2025 Incident: Multiple PRs all failed due to targeting wrong codebase

What Happened

Agents were instructed to work on "feedback-service" but targeted the wrong working directory:

• ❌ Wrong: ~/apps/zeron/feedback-service/ (deleted TypeScript monorepo code)
• ✅ Correct: ~/apps/zeron-feedback-service/ (production JavaScript Express app)

This resulted in:

• Massive PRs with 100+ files of deleted monorepo code
• 3 separate attempts all failing the same way
• Hours of lost development time
• Need to extract clean conductor work via cherry-picking

Root Cause

1. Monorepo Migration: The feedback-service was originally in the monorepo, then moved to a separate repo
2. Config Lag: Project configs still pointed to old monorepo path
3. No Codebase Verification: Agents didn't verify they were in the correct codebase before working
4. Agent Context Blindness: Agents had no warning about similar directory names

Prevention Measures

1. Path Validation (Already Implemented)

Location: conductor/src/project-registry.ts:44-85

The registry already validates paths on startup:

// Track path validation issues
if (!existsSync(config.project.working_directory)) {
  pathIssues.push({
    projectId: config.project.id,
    path: config.project.working_directory
  });
}

// Log path validation summary
if (pathIssues.length > 0) {
  this.logger.warn('⚠️  Path validation issues detected', {
    count: pathIssues.length,
    issues: pathIssues
  });
  this.logger.warn('Projects with invalid paths will show ❌ in dashboard');
}

2. Dashboard Indicators (Already Implemented)

Location: conductor/static/app.js:166-169

The dashboard shows ✅/❌ for path validation:

<span class="text-xs break-all ${project.pathExists ? 'text-gray-300' : 'text-red-400'}">
  ${project.pathExists ? '✅' : '❌'} ${this.escapeHtml(project.workingDir)}
  ${!project.pathExists ? ' <span class="text-red-500 font-semibold">(NOT FOUND)</span>' : ''}
</span>

3. Enhanced Agent Context (Recommended)

Location: conductor/src/agent-manager.ts

Add explicit path verification warnings to builder agent context:

// CRITICAL PATH VERIFICATION
// You are working in: ${workingDirectory}
//
// ⚠️  BEFORE making ANY changes:
// 1. Verify you are in the CORRECT codebase
// 2. Check package.json or other identifying files
// 3. Look for expected dependencies/structure
//
// STOP if you see unexpected code (e.g., deleted monorepo code)
// ASK the user if directory seems wrong

4. Real-Time Config Validation (Recommended)

Location: conductor/static/config.js

Add live path validation when configuring projects:

async function validateWorkingDirectory(path) {
  const response = await fetch('/api/validate-path', {
    method: 'POST',
    body: JSON.stringify({ path })
  });

  const result = await response.json();

  if (!result.exists) {
    showWarning('⚠️  Directory does not exist: ' + path);
  } else if (result.isEmpty) {
    showWarning('⚠️  Directory is empty - is this correct?');
  } else {
    showSuccess('✅ Directory validated: ' + path);
    showInfo('Contains: ' + result.files.slice(0, 5).join(', '));
  }
}

5. Codebase Fingerprinting (Recommended)

Location: conductor/src/project-registry.ts

Add method to detect codebase type and warn about mismatches:

private async detectCodebaseType(workingDir: string): Promise<{
  type: 'unknown' | 'node-ts' | 'node-js' | 'python' | 'empty';
  confidence: number;
  indicators: string[];
}> {
  const indicators: string[] = [];

  if (existsSync(join(workingDir, 'package.json'))) {
    const pkg = JSON.parse(readFileSync(join(workingDir, 'package.json'), 'utf-8'));

    if (pkg.devDependencies?.typescript) {
      indicators.push('TypeScript project');
      return { type: 'node-ts', confidence: 0.9, indicators };
    }

    indicators.push('JavaScript project');
    return { type: 'node-js', confidence: 0.8, indicators };
  }

  if (existsSync(join(workingDir, 'requirements.txt'))) {
    indicators.push('Python project');
    return { type: 'python', confidence: 0.9, indicators };
  }

  const files = readdirSync(workingDir);
  if (files.length === 0) {
    return { type: 'empty', confidence: 1.0, indicators: ['Empty directory'] };
  }

  return { type: 'unknown', confidence: 0.0, indicators: ['Unknown project type'] };
}

6. Pre-Spawn Safety Checks (Critical)

Before spawning any agent, conductor should:

1. ✅ Verify working directory exists (existsSync)
2. ✅ Verify directory is not empty
3. ✅ Verify expected codebase type matches config
4. ✅ Log fingerprint for audit trail
5. ❌ Abort spawn if checks fail

7. Dashboard Path Issues Section (Recommended)

Location: conductor/static/index.html and app.js

Add prominent warning section for path issues:

<!-- Path Validation Issues (show if any) -->
<div id="path-issues-container" class="hidden">
  <div class="bg-red-900/20 border border-red-500 rounded-lg p-5">
    <h2 class="text-xl font-bold text-red-400 mb-3">⚠️  Path Validation Issues</h2>
    <p class="text-red-300 mb-3">
      The following projects have invalid working directories and cannot be processed:
    </p>
    <ul id="path-issues-list" class="list-disc list-inside text-red-300 space-y-1">
      <!-- Populated by app.js -->
    </ul>
    <p class="text-red-400 mt-3 font-semibold">
      Fix these paths in configuration before running conductor!
    </p>
  </div>
</div>

Lessons Learned

1. Trust But Verify

Even if a path is in config, validate it exists and contains expected code.

2. Fail Fast, Fail Loud

Don't let agents start working in wrong directories. Abort early.

3. Agent Context Matters

Agents need explicit warnings about path confusion risks.

4. Dashboard Visibility

Make path issues IMPOSSIBLE to miss in the UI.

5. Audit Trails

Log codebase fingerprints for every spawn event.

Migration Checklist

When moving code between repos:

• [ ] Update all project configs with new paths
• [ ] Verify paths in dashboard show ✅
• [ ] Update CLAUDE.md with correct paths
• [ ] Test agent spawn in new location
• [ ] Document the migration in project docs
• [ ] Add redirect/warning in old location

Future Enhancements

1. Auto-discovery: Scan filesystem for known projects and suggest configs
2. Path aliases: Support multiple valid paths for same project (dev/prod)
3. Git verification: Verify working directory is correct git repo
4. Codebase diff: Compare expected vs actual codebase structure
5. Smart suggestions: "Did you mean zeron-feedback-service instead of feedback-service?"

Related Files

• conductor/src/project-registry.ts - Path validation logic
• conductor/static/app.js - Dashboard path indicators
• conductor/src/agent-manager.ts - Agent spawn context
• conductor/config/*.yaml - Project configurations

References

• Incident: Multiple contaminated PRs (October 10, 2025)
• Resolution: Clean PR with extracted conductor work
• Config Fix: feedback-service.yaml updated with correct path