Bug Report: Environment Manager Not Detected in Monorepo Structure

[danieldekay]

Environment

• SpecFact Version: 0.46.18
• OS: Linux (Ubuntu/Debian)
• Python: 3.12.11
• Project Structure: Monorepo (multiple pyproject.toml in subdirectories)

Issue Description

specfact init ide reports "No Compatible Environment Manager Detected" despite uv being installed and available in PATH, and multiple pyproject.toml files existing in the repository.

Steps to Reproduce

1. Have a monorepo project structure:

   repo-root/
   ├── backend/
   │   ├── pyproject.toml  ✓ (exists, uses uv)
   │   └── .venv/
   ├── worker/
   │   ├── pyproject.toml  ✓ (exists, uses uv)
   │   └── .venv/
   └── (no root pyproject.toml)
   

2. Ensure uv is installed: which uv → /home/kaesmad/.local/bin/uv
3. Run: specfact init ide
4. See error: "⚠ No Compatible Environment Manager Detected"

Expected Behavior

SpecFact should:

• Detect uv in PATH (or other supported tools)
• OR detect pyproject.toml files in subdirectories (monorepo pattern)
• OR allow manual specification of environment manager

Actual Behavior

╭───────────────────────────────────────────────────────╮
│ ⚠ No Compatible Environment Manager Detected          │
╰───────────────────────────────────────────────────────╯
Supported tools: hatch, poetry, uv, pip

Despite:

• ✅ uv is installed and in PATH
• ✅ uv --version works: uv 0.9.28
• ✅ Multiple pyproject.toml files exist in project subdirectories
• ✅ Project actively uses uv (verified via uv run pytest commands)

Diagnostic Information

Environment Manager Check

$ which uv
/home/kaesmad/.local/bin/uv

$ uv --version
uv 0.9.28

$ echo $PATH | grep -o '\.local/bin'
.local/bin  # Present in PATH

Project Structure

$ ls -la backend/pyproject.toml worker/pyproject.toml
-rw-r--r-- 1 kaesmad kaesmad 6364 May  5 11:07 backend/pyproject.toml
-rw-r--r-- 1 kaesmad kaesmad  806 Mar 25 09:06 worker/pyproject.toml

$ ls backend/.venv worker/.venv
backend/.venv:  # Virtual environment exists
worker/.venv:   # Virtual environment exists

Terminal History Shows Active uv Usage

$ history | grep "uv run" | tail -3
uv run pytest -v tests/
uv run ruff check .
uv run pytest

Root Cause Hypothesis

SpecFact's environment manager detection logic:

1. Only checks for pyproject.toml in the current directory (repo root)
2. Does NOT check for tools in PATH as a fallback
3. Does NOT support monorepo patterns where pyproject.toml is in subdirectories

Impact

• Cannot complete IDE setup for monorepo projects
• Blocks prompt installation workflow
• Makes SpecFact unusable for multi-package repositories (common pattern)

Suggested Fix

Environment manager detection should:

1. Check PATH first: If uv, poetry, hatch, or pip exist in PATH → detect as available
2. Scan subdirectories: Look for */pyproject.toml patterns (1-2 levels deep)
3. Allow manual override: --env-manager uv flag to skip detection
4. Graceful degradation: If no env manager, warn but don't block IDE setup

Workaround

None available. User cannot proceed with IDE setup in monorepo projects.

Additional Context

• Monorepo structure is common for microservices, backends with multiple workers, etc.
• Projects like this often have separate virtual environments per package
• The repo actively uses uv (proven by terminal history and .venv directories)

Related Issues

This may be related to the broader module detection issue, suggesting SpecFact's discovery mechanisms need improvement for non-standard project layouts.

[djm81]

Source tracking synced: remediation is tracked by user story #557 under feature #353. #557 blocks this bug report until OpenSpec change runtime-01-discovery-reliability is implemented, validated, and merged. Repo decision: stays in nold-ai/specfact-cli, not specfact-cli-modules, because the root cause is CLI environment manager detection.

[djm81]

Implementation tracking update: remediation is tracked through User Story #557, which blocks this bug report. The story now includes a CI-capable runtime discovery smoke script covering rootless monorepo env-manager detection, init ide auto detection, and explicit --env-manager uv. This bug remains a source bug report, not a child of the feature/epic.