[adoption] explicit source_layout provides no import-path wiring guidance for subproject packages

[chrisdpurcell]

Outcome

source_layout = "explicit" documents how declared roots reach Ruff/basedpyright/coverage scopes, but not how Python at the root can import a package that lives in a subproject directory. The managed pytest/coverage gate fails with ModuleNotFoundError until the consumer independently wires a uv workspace plus a dev dependency.

Evidence

• Fresh adoption, project-standards 5.26.0 (v5.26.0), Linux, Python 3.14.7, uv 0.11.6.
• python-tooling 1.16 with build_backend = "none", source_layout = "explicit", additional_source_roots = ["subproj/src"], pytest.test_paths = ["subproj/tests"].
• After apply, uv run coverage run -m pytest fails:

subproj/tests/conftest.py:9: in <module>
    from subproj.content.loader import Content
E   ModuleNotFoundError: No module named 'subproj'

The declared roots reach the checker include, Ruff src, and coverage.run.source as documented — but nothing puts the package on the root environment's import path.

Expected behavior

The adopt guide (or troubleshooting table) should state the import prerequisite and the supported wiring, e.g. a uv workspace with the subproject as a member plus a dev dependency on it:

[tool.uv.workspace]
members = ["subproj"]

[tool.uv.sources]
subproj = { workspace = true }

with additional_dev_dependencies = ["subproj"] (and a note that additional_dev_dependencies is the intended channel for this).

Consumer consequence

Multiple failed gate cycles; the fix is discoverable only from uv workspace knowledge, not from the standards documentation.

Blocks progress: no (workaround found).

[chrisdpurcell]

Investigation: confirmed as a documentation gap, with a simpler supported fix than the one proposed

The gap is precisely locatable — an existing troubleshooting row covers this exact setup and omits the prerequisite

adopt.md already has a row for the reporter's configuration verbatim:

Python lives only under selected subprojects and there is no repository-wide Python root — Set
source_layout = "explicit" and declare every root in additional_source_roots plus
pytest.test_paths. No src or . root is rendered, so unrelated nested projects and undeclared
scripts stay outside the checker, Ruff, coverage, and pytest scopes.

That row instructs the adopter to do exactly what they did, and says nothing about importability. So this
is not a missing document — it is a specific existing row that is incomplete.

Why static analysis resolves but runtime import does not

_import_roots (providers/python_tooling.py:157) is named for imports but its docstring scopes it to
one consumer: "Return the checker's import-resolution roots." It feeds basedpyright extraPaths.
Nothing in the payload writes runtime sys.path — a grep for pythonpath, PYTHONPATH, or conftest
across the 1.17 provider returns only a comment, and there is no uv workspace guidance anywhere in the
payload (the sole workspace hit is ${workspaceFolder} in rendered VS Code settings, unrelated).

The reporter's diagnosis is therefore exactly right, and the behavior is a deliberate boundary rather
than a bug: the package configures tools, and runtime importability is a packaging concern. The
defect is that nothing says so at the point of use.

A supported fix exists today that needs neither a workspace nor a dev dependency

The KEY OWNERSHIP INVARIANT (issues #99 / #117, python_tooling.py:270-282) states that this package
owns exactly the leaf keys it names and that every undeclared key is consumer-owned by construction.
It names this case explicitly: "pythonpath in [tool.pytest.ini_options]".

_pytest_key (:479-486) confirms the owned set is exactly four keys — minversion, testpaths,
addopts, markers. So a consumer may write:

[tool.pytest.ini_options]
pythonpath = ["subproj/src"]

directly into the managed table, and reconcile will not touch it. This is not theoretical:
tests/package_contract/test_python_tooling_reconstruction.py:1693
(test_python_tooling_v4_migration_preserves_consumer_checker_and_pytest_keys) writes
pythonpath = ["."] and asserts at :1720 that it survives. Scope limit on that evidence: the test
exercises the V4→V5 migration path, so it proves preservation through migration; the general claim rests
on the per-leaf-key contribution identity (key:/tool/pytest/ini_options/<leaf>, :1029-1031) rather
than on that test alone.

The two fixes are not equivalent, and the difference is worth documenting

• pytest.ini_options.pythonpath fixes pytest only, with no new dependency and no workspace.
• The uv workspace plus additional_dev_dependencies the reporter proposed fixes every uv run
  invocation, which matters because the whole managed gate is uv run ....

A troubleshooting row should probably offer both and say which is which, rather than picking one.

Secondary finding

additional_dev_dependencies appears in adopt.md exactly once, at :40, as a bare
additional_dev_dependencies = [] inside the config block, with no prose anywhere describing what it is
for. The reporter's suggestion that it be named as "the intended channel for this" is well founded — it
is currently undiscoverable from the documentation.

Version status

All references above are 1.17 (shipping in v5.27.0); the behavior is unchanged from 1.16. A fix lands in
1.18 — 1.17's payload bytes freeze at the v5.27.0 tag.

Evidence gathered read-only against the working tree; nothing here touched the in-flight release.

[chrisdpurcell]

Fields set under the operator's 2026-09-01 instruction: Type=Bug, Workflow=Ready, Priority=P2 Planned, Size=S, Change risk=R1 Low, Execution mode=Unattended agent.

The fix lands in python-tooling 1.18 for release v5.28.0.

Acceptance criteria (authored 2026-09-01 by the session orchestrator from the owner's investigation comment):

1. The existing adopt.md troubleshooting row for source_layout = "explicit" gains an explicit statement that runtime importability is not handled by the declared roots, plus the pytest.ini_options.pythonpath fix.
2. The row also documents the alternative (uv workspace member + additional_dev_dependencies) and states which of the two fixes covers pytest only vs. every uv run invocation.
3. additional_dev_dependencies gets at least one sentence of explanatory prose in adopt.md (currently a bare = [] example with none).

[chrisdpurcell]

Resolved by python-tooling 1.18, cut in PR #225 (merged to testing as d08a79d, ships in v5.28.0). The acceptance criteria recorded on this issue are covered by the 1.18 adopt.md rows and the contract tests in tests/package_contract/test_python_tooling_1_18.py; the per-leaf-key preservation claim was additionally confirmed end-to-end in a live consumer repro this session (keys survive reconcile --apply, validate, and an option change that rewrites the same table). 1.17 stays byte-immutable.