commit_msg.txt

fix(debug): improve source discovery validation and fallback diagnostics

- DiscoverLocalSymbols returns *DiscoveryResult (Found/SearchDir/Warnings);
  validates empty projectRoot and path-is-file; unreadable files go to Warnings
- Resolver.Resolve validates --contract-source override path before use;
  adds WithNonInteractive() returning ErrSourceNotFound instead of blocking stdin in CI
- AutoDiscoverLocalSymbols validates projectRoot and expectedHash upfront
- debug.go: validateSourceDiscoveryFlags() covers --contract-source and
  --source-alias JSON validity for --wasm/--demo early-return paths
- debug_dry_run.go: source discovery pre-flight [OK]/[FAIL] entries with Fix: hints
- Added ErrSourceDiscoveryFailed sentinel and WrapSourceDiscoveryFailed with Hint
- Fixed pre-existing workspace.go: SourceMapData -> SourceMaps, removed unused import
- Fixed pre-existing duplicate contains() in external_repos_test.go
- 47 new tests across 4 new test files covering all validation paths
- Updated docs/source-mapping.md and docs/debug-command.md