T-1JAO-python-runtime-doc-warns-script-lib-name-collision
Status: closed/superseded · Impact: low · Complexity: small
Auto-generated from a /sdlc:task-work post-mortem. Review and
promote to open/ready before picking up.
When a script package under plugin/scripts/<name>/ shares its name
with a library package under plugin/lib/<name>/, sys.path
resolution shadows one with the other and the failure mode is
confusing. python-runtime.md is the canonical convention doc for
plugin-side Python layout and it currently says nothing about this
trap. Citing the live incident from
T-QC31-add-sdlc-lease-cli-commands (the CLI handler subdir
had to be renamed from plugin/scripts/lease/ to
plugin/scripts/lease_cli/ mid-implementation), a one-paragraph
convention note would prevent the next planner from proposing a
colliding name.
| Location | Role today |
|---|---|
plugin/conventions/python-runtime.md | Documents the plugin/lib/ layout, the pytest.ini pythonpath bootstrap, and the uv-inline-script invocation pattern. Does NOT mention name-collision risk between plugin/scripts/<x>/ and plugin/lib/<x>/. |
plugin/scripts/lease_cli/ | The CLI handler package — renamed during the lease-CLI implementation to avoid colliding with plugin/lib/lease/. The rationale lives in the package docstring only. |
Proposed
Section titled “Proposed”plugin/conventions/python-runtime.md gains a short subsection
(“Avoid name collisions with library packages”) that:
- States the rule: a script package under
plugin/scripts/<name>/MUST NOT share a name with any package underplugin/lib/. - Explains the failure mode in one sentence (
sys.pathresolution shadows one with the other; symptom isImportErroror silently wrong import). - Names the resolution: suffix the script package (e.g.
lease_cli/for a CLI wrapping theleaselibrary). - Optionally points task-define / task spec authors at this
convention with a one-line “before proposing a new package name,
grep
plugin/lib/for a collision”.
Approach
Section titled “Approach”- Read the current
python-runtime.mdto find the right insertion point — probably right after theplugin/lib/layout section. - Add the “Avoid name collisions with library packages” subsection per the Proposed shape.
- Add a one-line cross-reference from the lease-CLI package docstring back to this convention so future readers find the rule from the symptom.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/conventions/python-runtime.md | modify | Add the “Avoid name collisions with library packages” subsection with rule, failure mode, and resolution pattern. |
plugin/scripts/lease_cli/__init__.py | modify | Add a one-line pointer in the module docstring to the new convention section (best-guess path; may not exist yet — see Dependencies). |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1:
plugin/conventions/python-runtime.mdcontains a subsection that names the rule, the failure mode, and the_cli(or equivalent) suffix as the conventional resolution. - AC-2: The subsection includes at least one worked example
demonstrating the collision rule and its
_cli-suffixed resolution. - AC-3: A grep for
plugin/scripts/<name>directories that duplicate aplugin/lib/<name>name returns zero matches — asserted by a short check script underplugin/scripts/, or noted as a future addition if no enforcement is in scope.
Out of scope
Section titled “Out of scope”- Adding an automated linter that fails CI on collisions. The convention note is enough for slice 1; a linter is a future enhancement.
- Renaming any other existing script packages. Today only
lease_cliwas at risk; future collisions are blocked by the convention, not by a sweep.
Dependencies
Section titled “Dependencies”- T-QC31-add-sdlc-lease-cli-commands — the lease CLI must land first so the worked-example reference is real.
Discovery context
Section titled “Discovery context”Spawned by /sdlc:task-work post-mortem of T-QC31-add-sdlc-lease-cli-commands on 2026-05-23.
Dedup search (spawn-from-post-mortem)
Section titled “Dedup search (spawn-from-post-mortem)”Bullet: Name collision: lease (library package) vs lease/ (CLI subdir). The task spec called for plugin/scripts/lease/ for handler modules, but plugin/lib/lease/ is already on sys.path and would shadow it. Renamed the CLI subpackage to plugin/scripts/lease_cli/ and documented the rationale. Suggests: task specs that propose new module names should grep for collisions during planning, OR python-runtime.md should add a ‘avoid naming a script package the same as a library package’ note. Keywords searched: python-runtime, subpackage, documented, collisions, collision, lease_cli, rationale, suggests Excluded: 2026-05-23-add-sdlc-lease-cli-commands Top candidates (score / status / headline):
- 25 / in-progress / 2026-05-23-add-lease-protocol-library-and-schemas — Add lease-protocol library and payload schemas
- 13 / planning/draft / 2026-05-23-python-runtime-doc-uv-test-recipe — python-runtime.md documents the canonical uv-flavored library test command
- 11 / closed/done / 2026-05-23-establish-plugin-lib-convention — Establish
plugin/lib/convention for Python libraries - 8 / in-progress / 2026-05-22-move-plugin-runtime-state-to-sdlc-dir — Migrate sdlc plugin runtime state from .claude/ to .sdlc/
- 5 / closed/done / 2026-05-19-document-commit-message-pattern — Document robust commit-message
pattern (mktemp + git commit -F) for SDLC skills
Decision: LINKED-EXISTING 2026-05-23-add-lease-protocol-library-and-schemas Rationale: Overridden to
SPAWNED. The top match (the lease-library task) is about adding the library itself, not about
plugin/scripts naming conventions. The 2nd candidate (
python-runtime-doc-uv-test-recipe) is also a python-runtime.md edit but its concern is the uv-flavored test recipe, not naming-collision guidance — distinct enough to scaffold as a sibling task that both edit the same doc.