Describe the Bug
On Windows, backlog automation can fail in two related ways:
- The CLI can crash during startup or help rendering when the active console is not UTF-8 and Rich emits Unicode symbols.
- Programmatic reuse of
specfact backlog add from another Python environment is brittle because the external SpecFact module path and the installed specfact_cli runtime are interpreter-specific and not self-contained.
In practice this prevents reliable automation around backlog creation unless the caller manually forces UTF-8 output, injects external module paths, and uses the same interpreter that hosts the installed SpecFact stack.
To Reproduce
Steps to reproduce the behavior:
# Example 1: CLI help or startup on a Windows CP1252 console
specfact backlog add --help
# Example 2: programmatic backlog creation from a separate virtual environment
python -c "from sample_backlog_helper import run_create; run_create()"
Example:
python -m sample_package.email_to_backlog \
--title "Sample backlog intake" \
--project-id sample-org/SampleProject \
--iteration "SampleProject\\2026\\Sprint 01" \
--category "Collaboration" \
--subcategory "Stakeholder collobaration"
Expected Behavior
specfact backlog add --help should render successfully on Windows without requiring manual UTF-8 environment variables.- Programmatic callers should be able to invoke backlog creation from a separate Python environment without manually mounting
.specfact/modules/... paths.
- If external modules are required, the CLI should detect and report a clear compatibility error instead of failing with low-level import or compiled-extension errors.
Actual Behavior
What actually happened:
- The CLI crashed with a
UnicodeEncodeError while writing Rich output to a Windows console using a non-UTF-8 code page.
- Programmatic invocation failed with module-resolution and runtime-compatibility errors such as:
ModuleNotFoundError: No module named 'specfact_backlog'ModuleNotFoundError: No module named 'specfact_cli'ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'
This occurred because the automation environment used one Python interpreter while the installed SpecFact stack and its compiled dependencies were located in a different interpreter environment.
Environment
- OS: Windows 11 (sample)
- Python Version: 3.13.x for the installed SpecFact CLI, 3.12.x for the calling virtual environment (sample)
- SpecFact CLI Version: 0.42.x (sample)
- Installation Method: pip into a user-level Python installation, with external modules under
.specfact/modules (sample)
Command Output
Include the full command output (sanitized sample):
Traceback (most recent call last):
...
UnicodeEncodeError: 'charmap' codec can't encode characters in position 0-1: character maps to <undefined>
During programmatic invocation:
Traceback (most recent call last):
...
ModuleNotFoundError: No module named 'specfact_backlog'
During fallback path injection:
Traceback (most recent call last):
...
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'
Codebase Context (for brownfield issues)
If this bug occurs when analyzing legacy code:
- Project Type: plain Python automation package wrapping SpecFact CLI
- Codebase Size: ~20 Python files (sample)
- Python Version in Target Codebase: 3.12 (sample)
Additional Context
- Related symptoms surfaced while automating
specfact backlog add from a repo-local helper.
- Workarounds found:
- Set
PYTHONIOENCODING=utf-8 and PYTHONUTF8=1 before invoking SpecFact on Windows.
- Manually add the external SpecFact module path under
.specfact/modules/specfact-backlog/src to sys.path.
- Use the same Python interpreter that hosts the installed
specfact_cli package and compiled dependencies.
- Impact on workflow:
- Breaks straightforward Windows automation for backlog creation.
- Forces helper scripts to contain environment-specific bootstrap logic.
- Makes virtual-environment-based integration fragile and hard to support predictably.
Describe the Bug
On Windows, backlog automation can fail in two related ways:
specfact backlog addfrom another Python environment is brittle because the external SpecFact module path and the installedspecfact_cliruntime are interpreter-specific and not self-contained.In practice this prevents reliable automation around backlog creation unless the caller manually forces UTF-8 output, injects external module paths, and uses the same interpreter that hosts the installed SpecFact stack.
To Reproduce
Steps to reproduce the behavior:
Example:
Expected Behavior
specfact backlog add --helpshould render successfully on Windows without requiring manual UTF-8 environment variables..specfact/modules/...paths.Actual Behavior
What actually happened:
UnicodeEncodeErrorwhile writing Rich output to a Windows console using a non-UTF-8 code page.ModuleNotFoundError: No module named 'specfact_backlog'ModuleNotFoundError: No module named 'specfact_cli'ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'This occurred because the automation environment used one Python interpreter while the installed SpecFact stack and its compiled dependencies were located in a different interpreter environment.
Environment
.specfact/modules(sample)Command Output
Include the full command output (sanitized sample):
Codebase Context (for brownfield issues)
If this bug occurs when analyzing legacy code:
Additional Context
specfact backlog addfrom a repo-local helper.PYTHONIOENCODING=utf-8andPYTHONUTF8=1before invoking SpecFact on Windows..specfact/modules/specfact-backlog/srctosys.path.specfact_clipackage and compiled dependencies.