Known Issues & Tech Debt¶

Acknowledged gaps and limitations in this template project. Maintained so they don't need to be rediscovered each session. Remove entries as they're resolved; add new ones as they're found.

Active Issues¶

Area	Issue	Details	Severity
CI	Container scan is advisory-only	`container-scan.yml` results don't block PRs. Intentional (high false-positive rate), but means container vulnerabilities can ship unnoticed.	Low
CI	Docs deploy is path-filtered	`docs-deploy.yml` only runs on `docs/`, `src/`, `mkdocs.yml` changes pushed to main. Build validation is covered by `docs-build.yml` (runs every PR, in CI gate).	Info
CI	Workflow guards use `YOURNAME`	Workflow `if:` guards reference `YOURNAME/YOURREPO` — intentional per ADR 011 (disabled by default for forks). Enable via repo vars.	Info
CI	CI gate check-name drift risk	If a workflow job's `name:` field is renamed without updating `REQUIRED_CHECKS` in `ci-gate.yml`, the gate silently stops finding it and times out.	Medium
Docs	`docs/workflows.md` can drift	Manually maintained workflow inventory. Adding/removing workflows without updating this file makes it misleading.	Medium
Template	Placeholder source code	Everything under `src/simple_python_boilerplate/` is example code. Template users must replace it entirely.	Info
Hatch	Stale env after dependency removal	After removing a dependency from `pyproject.toml`, the old package silently remains. Hatch inherits pip's limitation: `install` adds packages but never removes them. No auto-uninstall mechanism exists in Hatch. Workaround: `task env:reset` or `hatch env remove default`.	Medium
VS Code	Ruff-lsp deprecation warning	The legacy `ruff-lsp` server has been replaced by the native Ruff extension. If `ruff.lint.run` exists in VS Code User Settings, a deprecation warning appears. Remove it from User Settings (Ctrl+Shift+P → "Open User Settings (JSON)"). See Troubleshooting.	Low
Tooling	Global pip footgun	Running bare `pip install <pkg>` outside a Hatch env is easy to do and silently pollutes the global Python. No guardrail beyond convention.	Medium
Scripts	Shebang requires manual chmod	After adding a shebang (`#!/usr/bin/env python3`) to a script, you must `git add --chmod=+x` it separately. The pre-commit hook catches it, but only at commit time.	Low
Scripts	UI helper duplication in git_doctor	Box-drawing char init, `_section()`, `_kv()`, and `_merge_row()` are duplicated across 8 functions in `git_doctor.py`. ~200 lines of boilerplate. Extract into a shared `_UIContext` dataclass.	Low
Release	Coverage badge token is placeholder	`README.md` coverage badge uses `token=YOUR_TOKEN`. Replace with actual Codecov token or remove the badge.	Low
Security	pygments CVE-2026-4539 (no fix)	`pygments<=2.19.2` has a ReDoS vulnerability in `AdLLexer`. No fixed version released yet. Temporarily ignored in `nightly-security.yml` pip-audit job. Remove the `ignore-vulns` entry once pygments releases a fix.	Medium
CI	Bot PRs don't trigger CI gate	PRs created by `github-actions[bot]` (e.g., pre-commit autoupdate, Dependabot) use `GITHUB_TOKEN`, which by design does not trigger `pull_request` events for other workflows. The CI gate stays pending. Workaround: close and reopen the PR, push an empty commit, or use a PAT/GitHub App token in the creating workflow.	Medium

Resolved¶

Move resolved issues here with a brief note on how/when they were fixed, then delete them after a release cycle.

Area	Issue	Resolution	Date
Release	Pre-1.0 version bump config	Set `bump-minor-pre-major: false` in `release-please-config.json`. Breaking changes now bump major per SemVer. Removed stale `_comment_todo` / `_comment_versioning` fields.	2026-03
Release	Classifier still says Beta	Changed to `Development Status :: 5 - Production/Stable` in `pyproject.toml`. Also set `major_version_zero = false` in `[tool.commitizen]`.	2026-03
Scripts	Doctor scripts overlap	Shared check logic extracted into `_doctor_common.py` (imported by `doctor.py`, `env_doctor.py`, `git_doctor.py`). Color helpers centralised in `_colors.py`. Remaining per-script logic is intentionally specialised — each doctor script has a distinct scope (env, git, repo).	2026-03
Scripts	`_SKIP_SCRIPTS` is hardcoded	By design: convention-based exclusion (`_` prefix) handles all internal modules. The explicit set only contains `__init__.py`. Making this configurable via `pyproject.toml` adds complexity for no practical benefit since the `_` prefix convention covers all current and foreseeable cases.	2026-03
Security	PGP key import path unclear	`SECURITY.md` now documents both relative (`gpg --import pgp-key.asc` from repo root) and absolute path options, with a note explaining when each is appropriate.	2026-03
Docs	`docs/reference/commands.md` scope	Generator now covers Taskfile tasks, script `--help` output, Hatch envs, and CLI entry points (`[project.scripts]`). Custom Makefile targets aren't included — this project doesn't use Make. Non-issue for this project.	2026-03
Pre-commit	`check-json` fails on `.vscode/settings.json`	`.vscode/settings.json` uses JSONC (comments). Added to the `check-json` exclude pattern in `.pre-commit-config.yaml`.	2026-03
Security	PGP key fingerprint is a TODO	Fingerprint and keyserver URL added to SECURITY.md	2026-03
VS Code	`python` interpreter path not found	Removed `python.defaultInterpreterPath` from `.code-workspace` settings entirely. Neither `"python"`, `${workspaceFolder}/...`, nor relative paths resolve reliably in `.code-workspace` files. The Python extension's auto-discovery finds `.venv` and the picker (Ctrl+Shift+P → Select Interpreter) stores the choice per-workspace.	2026-03

How to Use This File¶

Found something? Add a row to the Active table with area, description, and severity (Info / Low / Medium / High).
Fixed something? Move it to Resolved with a date and brief note.
Copilot context: This file is referenced from .github/copilot-instructions.md so Copilot knows about current gaps without the instructions file growing unbounded.