Bug: 'specfact code' fails despite successful module installation

[danieldekay]

Bug: specfact code command fails despite successful module installation

Description

The specfact code command group fails with "Module 'nold-ai/specfact-codebase' is not installed" error, even immediately after successful installation of the module.

Steps to Reproduce

1. Install the specfact-codebase module:

specfact module install nold-ai/specfact-codebase --scope user --reinstall

Output:

SpecFact CLI - v0.46.18
⏱️  Started: 2026-05-06 15:24:41
Installed nold-ai/specfact-codebase -> /home/kaesmad/.specfact/modules/specfact-codebase
Verified: official (nold-ai)

✓ Finished: 2026-05-06 15:24:42 | Duration: 0.91s

2. Attempt to use the code command:

specfact code import --help

Expected Behavior

The specfact code import --help command should display help for the import subcommand.

Actual Behavior

⏱️  Started: 2026-05-06 15:24:55
Module 'nold-ai/specfact-codebase' is not installed.
The code command group is provided by that module. Install with specfact module 
install nold-ai/specfact-codebase, or run specfact init --profile <profile> to 
install bundles.

✓ Finished: 2026-05-06 15:24:55 | Duration: 0.19s

Environment

• SpecFact CLI: v0.46.18
• Module Version: nold-ai/specfact-codebase v0.41.9
• Installation Method: uv tool (uvx specfact-cli)
• Python: 3.12.11
• OS: Linux (Ubuntu-based)
• Shell: zsh

Investigation

Module Files Present

$ ls -la ~/.specfact/modules/specfact-codebase/
total 28
drwxr-xr-x 4 kaesmad kaesmad 4096 May  6 11:32 .
drwxr-xr-x 5 kaesmad kaesmad 4096 May  6 11:32 ..
-rw-r--r-- 1 kaesmad kaesmad   71 May  6 11:32 .specfact-install-verified-checksum
-rw-r--r-- 1 kaesmad kaesmad   25 May  6 11:32 .specfact-registry-id
-rw-r--r-- 1 kaesmad kaesmad  658 Apr 15 14:08 module-package.yaml
drwxr-xr-x 3 kaesmad kaesmad 4096 May  6 11:32 resources
drwxr-xr-x 3 kaesmad kaesmad 4096 May  6 11:32 src

Module Registered

$ cat ~/.specfact/registry/modules.json | jq '.modules[] | select(.id == "nold-ai/specfact-codebase")'
{
  "id": "nold-ai/specfact-codebase",
  "version": "0.41.9",
  "enabled": true
}

Module Listed as Installed

$ specfact module list
┌──────────────────────────────┬─────────┬─────────┬────────────┬───────────┐
│ Module                       │ Version │ State   │ Trust      │ Publisher │
├──────────────────────────────┼─────────┼─────────┼────────────┼───────────┤
│ nold-ai/specfact-codebase    │ 0.41.9  │ enabled │ [official] │ nold-ai   │
└──────────────────────────────┴─────────┴─────────┴────────────┴───────────┘

Python Import Fails

The SpecFact CLI's Python environment cannot import the module:

$ /home/kaesmad/.local/share/uv/tools/specfact-cli/bin/python3 -c "import specfact_codebase"
ModuleNotFoundError: No module named 'specfact_codebase'

Comparison with Working Module

The plan command (from specfact-project module) works correctly:

$ specfact plan --help
✓ Works correctly

Both modules have identical installation markers:

$ ls ~/.specfact/modules/specfact-project/.specfact*
.specfact-install-verified-checksum
.specfact-registry-id

$ ls ~/.specfact/modules/specfact-codebase/.specfact*
.specfact-install-verified-checksum
.specfact-registry-id

Root Cause Analysis

The module files are downloaded and registered, but the module's Python package is not in the Python path of the SpecFact CLI's execution environment. The CLI appears to check module registration metadata but fails to properly add the module's src/ directory to sys.path before attempting to import the command groups.

Workaround

None found. The code command group is completely unusable.

Impact

• Critical: All brownfield import functionality is unavailable
• Users cannot use: specfact code import, specfact code analyze, specfact code drift, specfact code validate, specfact code repro
• The documentation and prompt files reference these commands, creating user confusion

Additional Context

• Attempted specfact init --install-deps: No effect
• Attempted specfact init ide: No effect
• Attempted module uninstall/reinstall: No effect
• Attempted uv tool upgrade specfact-cli: No effect
• Other module commands (plan, module, init) work correctly

Related Files

• Module package definition: ~/.specfact/modules/specfact-codebase/module-package.yaml
• Registry state: ~/.specfact/registry/modules.json
• Command registry: ~/.specfact/registry/commands.json