pi-python-helper 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ does not guarantee a stable public tool schema.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-21
+
+### Changed
+
+- Adopt `pi-helper-core` (`^0.1.1`) for the shared response envelope, bounded command runner, TDD checkpoint, validation-bundle gate, completion evidence, artifact staleness, and test selection. `src/core/result.ts` and `src/core/runner.ts` are now thin shims, and `src/validation/` and `src/build/` supply only Python signals, labels, and rules.
+- **Breaking:** tool metadata no longer carries `pythonVersion`; the interpreter version now lives in the ecosystem-neutral `metadata.toolchain` (`{ kind: 'python', version }`).
+- Validation and completion messages now use the shared core wording (`uv lock --check`/`uv sync` labels); the drift check reports a mismatch against "the lockfile" generically.
+
+### Added
+
+- `test/core-dependency.test.ts` pins the `pi-helper-core` dependency and the shared behaviours the Python tools delegate to.
+
+## [0.3.0] - 2026-09-21
+
+### Added
+
+- `py_test_config` audits the pytest configuration pytest will actually use against the plugins the project declares and the tests on disk. It reports the cases that make a run look green while tests never execute (`ASYNC_TESTS_WITHOUT_PLUGIN`, `ASYNC_TESTS_REQUIRE_MARKER`), the options pytest rejects before collection (`ASYNCIO_MODE_WITHOUT_PLUGIN`, `COVERAGE_OPTION_WITHOUT_PLUGIN`), and a `testpaths` entry that does not exist (`TESTPATH_MISSING`). Only syntax separates an unmarked coroutine test from a marked one, so the decision is made on the AST rather than by matching text.
+- The scanner reports `[tool.pytest.ini_options]` as `manifest.pytestOptions` and, per scanned file, `asyncTests` and `asyncioMarkedTests` (protocol version 3).
+- Every tool response carries `attention`: `true` whenever the caller must act (`ok: false`, or a warning or error). It is derived centrally in `result()`, so `ok: false` always implies `attention: true` and no diagnostic is silently dropped. `ok` is now documented as the tool's **verdict** — "the project state is acceptable / the command succeeded / the gate may proceed" — rather than "the tool ran", so a check that finds a problem still returns `ok: false` without having failed. An `info` diagnostic is informational and does not raise `attention`.
+
+### Changed
+
+- **Breaking:** scanner protocol `SCANNER_VERSION` is now 3. A scanner reporting version 2 is rejected with `SCANNER_VERSION_MISMATCH`.
+
+### Fixed
+
+- `py_test_select` no longer returns `ok: false` with no diagnostic at all when the change set contains no Python file (or git reports no changes). An empty selection is an answer rather than a failure, so it now returns `ok: true` and explains itself with the `NO_CHANGED_PATHS` warning.
+- `py_failure_diagnose` no longer fabricates `uv add <import name>` for a `ModuleNotFoundError` whose providing distribution is unknown, matching the rule `py_dependency_plan` already follows. The alias table resolves a single provider (`yaml` → `uv add pyyaml`), while an import with several candidates (`cv2`) or none asks the caller to verify the distribution instead of installing the wrong package.
+- `py_failure_diagnose` no longer repeats the same suggestion twice when a missing module is neither project code nor declared. `refineWithDeclarations` appended its generic "verify the distribution" advice on top of what the classifier had already reported, so a single undeclared import produced two suggestions with two duplicates.
+
 ## [0.2.0] - 2026-09-22
 
 ### Fixed

package/docs/tools.md

@@ -12,6 +12,7 @@
 
 모든 도구는 동일한 `PyToolResult` 규격을 반환합니다. 반환 형태는 구조만 기록하며 값·경로·버전·소요시간은 스냅샷에서 제외합니다.
 
+- `attention`: boolean
 - `commands` (optional): array of
   - `args`: array<string>
   - `cwd`: string
@@ -29,12 +30,13 @@
   - `cwd`: string
   - `durationMs`: number
   - `projectRoot` (optional): string
-  - `pythonVersion` (optional): string
   - `toolVersion`: string
+  - `toolchain` (optional): object
+    - `kind`: string
+    - `source`: string
+    - `version`: string
   - `truncated`: boolean
 - `ok`: boolean
-- `projectRoot` (optional): string
-- `pythonVersion` (optional): string
 - `suggestions`: array of
   - `command` (optional): string
   - `confidence`: string
@@ -466,6 +468,27 @@ Preview or run pytest through uv run --frozen and summarise failures by test, fi
   - `risk`: string
 - `executed`: boolean
 
+### `py_test_config`
+
+Audit pytest configuration against the declared plugins and the tests on disk, and report options that make tests pass without running. Read-only.
+
+- 시스템 프롬프트 한 줄: `Validate pytest configuration and detect tests that never run`
+- 라벨: Python Test Config
+- 프로젝트 상태 변경: 없음 (읽기 전용)
+
+**파라미터**
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `path` | `string` | 아니오 | Project directory to audit; defaults to the project root. |
+
+**프롬프트 가이드라인**
+
+- Use py_test_config when a test run reports fewer tests than expected, when async tests may be silently skipped, or before trusting a green run.
+- Use py_test_config after changing pyproject.toml, pytest.ini, or the test layout to confirm the configuration still matches the project.
+
+**반환 `data` 형태**: 캡처되지 않음
+
 ### `py_test_select`
 
 Select focused pytest targets from changed files using pytest naming conventions, without running tests. Read-only.

package/extensions/index.ts

@@ -3,12 +3,14 @@ import { detectPythonEnvironment } from '../src/environment/discovery.ts';
 import { registerDependencyTools } from './tools/dependencies.ts';
 import { registerEnvironmentTools } from './tools/environment.ts';
 import { registerTestingTools } from './tools/testing.ts';
+import { registerTestConfigTools } from './tools/test-config.ts';
 import { registerValidationTools } from './tools/validation.ts';
 
 export default function (pi: ExtensionAPI): void {
   registerEnvironmentTools(pi);
   registerDependencyTools(pi);
   registerTestingTools(pi);
+  registerTestConfigTools(pi);
   registerValidationTools(pi);
 
   pi.registerCommand('py-status', {

package/extensions/shared.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { open } from 'node:fs/promises';
-import { basename, dirname, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { findProjectRoot, isDirectory, isFile } from '../src/project/root.ts';
 
 export type Pi = ExtensionAPI;
@@ -70,3 +70,15 @@ export async function readTextIfExists(
 export function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+/** INI files that can carry pytest configuration, in the order they are read. */
+export const PYTEST_INI_FILES = ['pytest.ini', 'tox.ini', 'setup.cfg'] as const;
+
+export async function readPytestIniFiles(
+  root: string,
+): Promise<Record<string, string | undefined>> {
+  const entries = await Promise.all(
+    PYTEST_INI_FILES.map(async (name) => [name, await readTextIfExists(join(root, name))] as const),
+  );
+  return Object.fromEntries(entries);
+}

package/extensions/tools/dependencies.ts

@@ -72,7 +72,7 @@ export function registerDependencyTools(pi: Pi): void {
             errors: [],
             suggestions: plan.suggestions,
             projectRoot: root,
-            pythonVersion: scan.payload.pythonVersion,
+            toolchain: { kind: 'python', version: scan.payload.pythonVersion, source: 'project' },
           }),
         );
       } catch (error) {

package/extensions/tools/environment.ts

@@ -10,22 +10,12 @@ import { runScanProject } from '../../src/project/scanner.ts';
 import {
   hasDirectory,
   messageOf,
-  readTextIfExists,
+  readPytestIniFiles,
   resolveProjectRoot,
   text,
   type Pi,
 } from '../shared.ts';
 
-/** INI files that can carry pytest configuration, in the order they are read. */
-const PYTEST_INI_FILES = ['pytest.ini', 'tox.ini', 'setup.cfg'];
-
-async function readPytestIniFiles(root: string): Promise<Record<string, string | undefined>> {
-  const entries = await Promise.all(
-    PYTEST_INI_FILES.map(async (name) => [name, await readTextIfExists(join(root, name))] as const),
-  );
-  return Object.fromEntries(entries);
-}
-
 export function registerEnvironmentTools(pi: Pi): void {
   pi.registerTool({
     name: 'py_environment',
@@ -77,7 +67,11 @@ export function registerEnvironmentTools(pi: Pi): void {
               confidence: 'medium' as const,
             })),
             projectRoot: environment.projectRoot,
-            pythonVersion: python?.version,
+            toolchain: {
+              kind: 'python',
+              version: python?.version,
+              source: environment.projectRoot ? 'project' : 'path',
+            },
           }),
         );
       } catch (error) {
@@ -185,7 +179,7 @@ export function registerEnvironmentTools(pi: Pi): void {
             errors: [],
             suggestions: inspection.suggestions,
             projectRoot: inspection.root,
-            pythonVersion: scan.payload.pythonVersion,
+            toolchain: { kind: 'python', version: scan.payload.pythonVersion, source: 'project' },
           }),
         );
       } catch (error) {

package/extensions/tools/test-config.ts

@@ -0,0 +1,148 @@
+import { Type } from 'typebox';
+import { join } from 'node:path';
+import { failure, result, type Diagnostic } from '../../src/core/result.ts';
+import {
+  auditPytestConfiguration,
+  resolvePytestOptions,
+  type AsyncTestFile,
+} from '../../src/build/pytest-audit.ts';
+import { buildDeclaredIndex, normalizeName } from '../../src/dependencies/plan.ts';
+import { isRunnableTestFile } from '../../src/project/paths.ts';
+import { isDirectory } from '../../src/project/root.ts';
+import { runScanProject } from '../../src/project/scanner.ts';
+import { messageOf, readPytestIniFiles, resolveProjectRoot, text, type Pi } from '../shared.ts';
+
+export function registerTestConfigTools(pi: Pi): void {
+  pi.registerTool({
+    name: 'py_test_config',
+    label: 'Python Test Config',
+    description:
+      'Audit pytest configuration against the declared plugins and the tests on disk, and report options that make tests pass without running. Read-only.',
+    promptSnippet: 'Validate pytest configuration and detect tests that never run',
+    promptGuidelines: [
+      'Use py_test_config when a test run reports fewer tests than expected, when async tests may be silently skipped, or before trusting a green run.',
+      'Use py_test_config after changing pyproject.toml, pytest.ini, or the test layout to confirm the configuration still matches the project.',
+    ],
+    parameters: Type.Object({
+      path: Type.Optional(
+        Type.String({ description: 'Project directory to audit; defaults to the project root.' }),
+      ),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
+        const scan = await runScanProject(ctx.cwd, { root, mode: 'all', maxFiles: 2000 }, signal);
+        if (!scan.ok || !scan.payload) {
+          return text(
+            failure(
+              ctx.cwd,
+              started,
+              scan.message ?? 'The project scanner failed.',
+              scan.code ?? 'SCANNER_FAILED',
+            ),
+          );
+        }
+
+        const manifest = scan.payload.manifest;
+        const declared = new Set(
+          buildDeclaredIndex(
+            manifest ?? {
+              dependencies: [],
+              optionalDependencies: {},
+              dependencyGroups: {},
+            },
+          ).keys(),
+        );
+
+        const resolution = resolvePytestOptions({
+          pyprojectOptions: manifest?.pytestOptions ?? null,
+          iniFiles: await readPytestIniFiles(root),
+        });
+
+        // Only files pytest would actually collect can hide a test, so a script
+        // that happens to define `async def test_*` is not reported.
+        const testFiles = (scan.payload.imports?.files ?? []).filter((file) =>
+          isRunnableTestFile(file.path),
+        );
+        const unmarkedAsyncTests: AsyncTestFile[] = testFiles
+          .map((file) => ({
+            path: file.path,
+            tests: (file.asyncTests ?? []).filter(
+              (name) => !(file.asyncioMarkedTests ?? []).includes(name),
+            ),
+          }))
+          .filter((entry) => entry.tests.length > 0);
+
+        const missingTestPaths: string[] = [];
+        for (const entry of resolution.options.testpaths) {
+          if (!(await isDirectory(join(root, entry)))) missingTestPaths.push(entry);
+        }
+
+        const findings = auditPytestConfiguration({
+          sources: resolution.sources,
+          options: resolution.options,
+          declared,
+          unmarkedAsyncTests,
+          missingTestPaths,
+          hasTestFiles: testFiles.length > 0,
+        });
+
+        const toDiagnostic = (finding: (typeof findings)[number]): Diagnostic => ({
+          code: finding.code,
+          message: finding.suggestion
+            ? `${finding.message} ${finding.suggestion}`
+            : finding.message,
+          severity: finding.severity,
+        });
+        const errors = findings.filter((finding) => finding.severity === 'error');
+        const warnings = findings.filter((finding) => finding.severity !== 'error');
+
+        return text(
+          result(ctx.cwd, started, {
+            ok: errors.length === 0,
+            summary:
+              findings.length === 0
+                ? `pytest configuration is consistent (${resolution.sources[0] ?? 'no configuration file'}, ${testFiles.length} test file(s)).`
+                : `${errors.length} error(s) and ${warnings.length} warning(s) in the pytest configuration.`,
+            data: {
+              sources: resolution.sources,
+              options: resolution.options,
+              findings,
+              unmarkedAsyncTests,
+              missingTestPaths,
+              testFileCount: testFiles.length,
+              declared: {
+                pytestAsyncio: declared.has(normalizeName('pytest-asyncio')),
+                pytestCov: declared.has(normalizeName('pytest-cov')),
+              },
+            },
+            evidence: [
+              {
+                kind: 'pytest_config_audit',
+                sources: resolution.sources,
+                findings: findings.map((finding) => finding.code),
+                unmarkedAsyncTests: unmarkedAsyncTests.reduce(
+                  (total, entry) => total + entry.tests.length,
+                  0,
+                ),
+              },
+            ],
+            warnings: warnings.map(toDiagnostic),
+            errors: errors.map(toDiagnostic),
+            suggestions: findings
+              .filter((finding) => finding.suggestion)
+              .map((finding) => ({
+                message: finding.suggestion as string,
+                confidence: 'high' as const,
+              })),
+            projectRoot: root,
+            toolchain: { kind: 'python', version: scan.payload.pythonVersion, source: 'project' },
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+}

package/extensions/tools/testing.ts

@@ -98,6 +98,10 @@ export function registerTestingTools(pi: Pi): void {
           ? undefined
           : await collectTestImports(root, ctx.cwd, signal);
         const selection = selectTests(changed, testFiles, { testImports });
+        // `changed` still holds non-Python paths, so "nothing to select" has to be
+        // decided on what the selector actually matched.
+        const hasPythonChange =
+          selection.changedSourceFiles.length > 0 || selection.changedTestFiles.length > 0;
         // Only files pytest collects tests from become targets; naming
         // `tests/utils.py` as a target overstates the run.
         const targets = selection.selected
@@ -111,7 +115,7 @@ export function registerTestingTools(pi: Pi): void {
 
         return text(
           result(ctx.cwd, started, {
-            ok: selection.selected.length > 0 || testFiles.length === 0,
+            ok: selection.selected.length > 0 || testFiles.length === 0 || !hasPythonChange,
             summary:
               `${selection.selected.length} test file(s) selected from ${testFiles.length} known test file(s) ` +
               `for ${selection.changedSourceFiles.length} changed source file(s) (${changedSource}).` +
@@ -137,6 +141,16 @@ export function registerTestingTools(pi: Pi): void {
               },
             ],
             warnings: [
+              ...(!hasPythonChange
+                ? [
+                    {
+                      code: 'NO_CHANGED_PATHS',
+                      message:
+                        'No changed Python file was found, so nothing could be selected. Pass changedPaths explicitly when the change is not visible to git.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
               ...(testFiles.length === 0
                 ? [
                     {

package/extensions/tools/validation.ts

@@ -590,7 +590,11 @@ export function registerValidationTools(pi: Pi): void {
                 ],
             commands,
             projectRoot: root,
-            pythonVersion: scan.payload?.pythonVersion,
+            toolchain: {
+              kind: 'python',
+              version: scan.payload?.pythonVersion,
+              source: 'project',
+            },
           }),
         );
       } catch (error) {

package/helpers/scan_project.py

@@ -37,7 +37,10 @@ from pathlib import Path
 # caller can refuse to interpret a document it does not understand.
 # 2: each scanned file reports `importModules`, the full dotted module names it
 #    references, so test selection can map a test file to the module it imports.
-SCANNER_VERSION = 2
+# 3: the manifest reports `[tool.pytest.ini_options]` as `pytestOptions`, and each
+#    scanned file reports `asyncTests`/`asyncioMarkedTests`, so a configuration
+#    audit can tell an async test that runs from one that is silently skipped.
+SCANNER_VERSION = 3
 
 KNOWN_SECTIONS = ("environment", "manifest", "imports")
 EXIT_OK = 0
@@ -234,6 +237,62 @@ def detect_layout(root: Path) -> tuple[str, list[str]]:
     return layout, sorted(set(modules))
 
 
+def json_safe(value):
+    """Recursively coerce a TOML value into something `json.dumps` accepts.
+
+    `tomllib` can produce datetimes, which are valid TOML but not JSON; a single
+    one would turn the whole document into a scanner crash.
+    """
+    if isinstance(value, dict):
+        return {str(key): json_safe(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [json_safe(item) for item in value]
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return str(value)
+
+
+ASYNC_MARKERS = {"asyncio", "anyio", "trio"}
+
+
+def _dotted_name(node: ast.AST) -> str:
+    """Rebuild `a.b.c` from an attribute chain, or "" when it is not one."""
+    parts = []
+    current = node
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if not isinstance(current, ast.Name):
+        return ""
+    parts.append(current.id)
+    return ".".join(reversed(parts))
+
+
+def async_test_functions(tree: ast.AST) -> tuple:
+    """Async test functions and the subset that carries an async marker.
+
+    pytest-asyncio's default `strict` mode runs a coroutine test only when it is
+    marked, so an unmarked `async def test_*` is collected and then silently
+    skipped. Only the syntax distinguishes the two, so this must be an AST walk
+    rather than a text search.
+    """
+    async_tests: list = []
+    marked: list = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.AsyncFunctionDef):
+            continue
+        if not node.name.startswith("test"):
+            continue
+        async_tests.append(node.name)
+        for decorator in node.decorator_list:
+            target = decorator.func if isinstance(decorator, ast.Call) else decorator
+            dotted = _dotted_name(target)
+            if dotted.rsplit(".", 1)[-1] in ASYNC_MARKERS and ".mark." in f".{dotted}":
+                marked.append(node.name)
+                break
+    return sorted(async_tests), sorted(marked)
+
+
 def scan_manifests(root: Path) -> dict:
     result: dict = {
         "pyprojectPath": None,
@@ -249,6 +308,7 @@ def scan_manifests(root: Path) -> dict:
         "buildRequires": [],
         "entryPoints": [],
         "toolConfiguration": {},
+        "pytestOptions": None,
         "layout": None,
         "modules": [],
         "legacySetupPy": False,
@@ -310,6 +370,9 @@ def scan_manifests(root: Path) -> dict:
                 key: key in tool
                 for key in ("ruff", "mypy", "pytest", "coverage", "pyright", "ty", "hatch")
             }
+            pytest_table = tool.get("pytest") if isinstance(tool.get("pytest"), dict) else {}
+            ini_options = pytest_table.get("ini_options")
+            result["pytestOptions"] = json_safe(ini_options) if isinstance(ini_options, dict) else None
             uv_table = tool.get("uv") if isinstance(tool.get("uv"), dict) else {}
             workspace = uv_table.get("workspace") if isinstance(uv_table.get("workspace"), dict) else {}
             members = workspace.get("members")
@@ -598,12 +661,15 @@ def scan_imports(root: Path, max_files: int) -> dict:
             collector.visit(tree)
             names = collector.all
             names.discard("")
+            async_tests, asyncio_marked = async_test_functions(tree)
             files.append(
                 {
                     "path": relative,
                     "imports": sorted(names),
                     "importModules": sorted(collector.modules),
                     "typeCheckingImports": sorted(collector.type_checking),
+                    "asyncTests": async_tests,
+                    "asyncioMarkedTests": asyncio_marked,
                 }
             )
             for name in names:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-python-helper",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Python (uv) development tools for the pi coding agent",
   "type": "module",
   "keywords": [
@@ -69,5 +69,8 @@
     "prettier": "^3.9.8",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "pi-helper-core": "^0.1.1"
   }
 }

package/skills/python-development/SKILL.md

@@ -19,11 +19,12 @@ license: Apache-2.0
 4. import 이름과 배포 이름은 다를 수 있습니다(`PIL`/`pillow`, `yaml`/`PyYAML`). `py_dependency_plan`의 제안을 `uv add`로 적용하세요.
 5. 소스 코드를 수정한 후에는 `py_test_select`로 변경 파일과 연관된 테스트를 선별하세요. 테스트가 변경 모듈을 **실제로 import**하면 가장 강한 근거이며, 이름 규약은 그 다음입니다. `narrowed: false`나 `NO_NARROWING`은 "30개 중 30개 선택"처럼 결과가 좁혀지지 않았다는 뜻이고, `SELECTION_WITHOUT_IMPORT_EVIDENCE`는 근거가 파일 이름뿐이라는 뜻이므로 변경이 넓다면 전체 스위트나 `lastFailed=true`를 사용하세요.
 6. 테스트 실행은 `py_test`를 사용하세요. `execute=false`로 먼저 미리보기하고, 실제 실행 시에만 `execute=true`를 전달합니다. 커버리지 플래그나 `-m` 마커 선택처럼 도구가 모델링하지 않는 프로젝트 표준 옵션은 `extraArgs`로 넘기세요.
-7. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다. 실행 파일을 찾지 못해 명령이 시작되지 못한 경우(`Failed to spawn`, `command not found`)는 `tool_not_installed`로 분류됩니다.
-8. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요. sync는 `[project.optional-dependencies]`의 extra를 함께 요청하므로 dev 도구가 extra로 선언된 프로젝트에서도 삭제되지 않습니다. `SYNC_REMOVED_PACKAGES`가 보이면 그것이 이후 "command not found"의 원인입니다.
-9. 재현이 어려운 실패는 `py_test`의 `lastFailed=true`(`--lf`)로 직전 실패만 다시 실행하세요.
-10. 작업 완료를 보고하기 전에 `py_validation_bundle`(lock 검사 → sync → pytest → 환경 정합성 → 오래된 아티팩트 검사)을 실행하고, `py_completion_evidence`로 근거가 충분한지 확인하세요. 정합성이 `drifted`나 `unverifiable`이면 테스트가 통과했어도 게이트는 실패합니다.
-11. `py_tdd_checkpoint`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
+7. 테스트가 예상보다 적게 실행되거나 초록색 결과를 믿기 어려울 때는 `py_test_config`로 pytest 설정을 검증하세요. `ASYNC_TESTS_WITHOUT_PLUGIN`/`ASYNC_TESTS_REQUIRE_MARKER`는 async 테스트가 **수집만 되고 실행되지 않는** 상태(플러그인 미선언 또는 `asyncio_mode` 미설정 + 마커 없음)를 뜻하며, `COVERAGE_OPTION_WITHOUT_PLUGIN`과 `ASYNCIO_MODE_WITHOUT_PLUGIN`은 실행 전에 pytest가 오류로 중단되는 설정입니다. `TESTPATH_MISSING`은 `testpaths`가 존재하지 않는 디렉터리를 가리킨다는 경고입니다.
+8. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다. 실행 파일을 찾지 못해 명령이 시작되지 못한 경우(`Failed to spawn`, `command not found`)는 `tool_not_installed`로 분류됩니다.
+9. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요. sync는 `[project.optional-dependencies]`의 extra를 함께 요청하므로 dev 도구가 extra로 선언된 프로젝트에서도 삭제되지 않습니다. `SYNC_REMOVED_PACKAGES`가 보이면 그것이 이후 "command not found"의 원인입니다.
+10. 재현이 어려운 실패는 `py_test`의 `lastFailed=true`(`--lf`)로 직전 실패만 다시 실행하세요.
+11. 작업 완료를 보고하기 전에 `py_validation_bundle`(lock 검사 → sync → pytest → 환경 정합성 → 오래된 아티팩트 검사)을 실행하고, `py_completion_evidence`로 근거가 충분한지 확인하세요. 정합성이 `drifted`나 `unverifiable`이면 테스트가 통과했어도 게이트는 실패합니다. 각 응답에서 조치 필요 여부는 `attention`으로 판단하세요.
+12. `py_tdd_checkpoint`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
 
 ## 안전 규칙 (Safety)
 
@@ -34,6 +35,8 @@ license: Apache-2.0
 
 ## 해석 규칙 (Interpretation rules)
 
+- `ok`는 도구의 **판정**이며 "도구가 실행됐다"는 뜻이 아닙니다. 검사 도구는 문제를 찾으면 도구 자체가 실패하지 않았어도 `ok: false`를 반환합니다. 조치가 필요한지는 `attention`을 읽으세요: `ok: false`이거나 경고·오류가 하나라도 있으면 `true`입니다.
+- `ok: false`에는 항상 그것을 설명하는 진단(`warnings` 또는 `errors`)이 함께 옵니다. 설명 없는 `ok: false`를 보면 도구 결함이므로 그대로 보고하세요. 게이트 도구는 판정을 `data.ok`(`checkpoint.ok`, `evidence.ok`, `summary.ok`)에도 노출합니다.
 - `PROJECT_INSTALLED_NOT_EDITABLE`는 프로젝트가 환경에 live link가 아니라 복사본으로 설치되어, 소스 변경이 테스트에 반영되지 않음을 의미합니다. `uv sync`로 해결하세요.
 - `PROJECT_NOT_INSTALLED`는 lock이 editable 설치를 기대하는데 `.venv`에 프로젝트가 없다는 뜻입니다. `uv sync`를 실행하고, 그래도 실패하면 빌드 백엔드가 패키지를 찾지 못한 것입니다(`[project] name`과 모듈 디렉터리 이름이 일치하는지 확인).
 - `PROJECT_VIRTUAL_SOURCE`는 정상입니다. `[build-system]`이 없으면 uv는 프로젝트를 `virtual` 소스로 기록하고 `.venv`에 설치하지 않습니다. 누락(`PROJECT_NOT_INSTALLED`)으로 취급하지 말고 `[build-system]` 추가 여부만 검토하세요.

package/src/build/failure.ts

@@ -1,4 +1,5 @@
 import type { Suggestion } from '../core/result.ts';
+import { importAliasCandidates } from '../dependencies/aliases.ts';
 
 export type FailureKind =
   | 'tool_not_installed'
@@ -222,6 +223,24 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
 
   if (kind === 'module_not_found' && missing) {
     const module = missing[1].split('.')[0];
+    // The traceback names an import, not a distribution. `uv add <import name>`
+    // installs a different package or nothing at all when the two disagree, so a
+    // command is emitted only when the alias table yields exactly one provider.
+    const providers = importAliasCandidates(module);
+    const resolveSuggestion: Suggestion =
+      providers.length === 1
+        ? {
+            message: `Declare the distribution providing "${module}" with uv add ${providers[0]} if it is third-party. Import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
+            confidence: 'medium',
+            command: `uv add ${providers[0]}`,
+          }
+        : {
+            message:
+              providers.length > 1
+                ? `"${module}" is provided by more than one distribution (${providers.join(', ')}). Verify which one the project needs before adding it.`
+                : `The distribution providing "${module}" is unknown. Verify the distribution name before adding it; import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
+            confidence: 'medium',
+          };
     return {
       kind: 'module_not_found',
       summary: `Import failed because the module "${module}" could not be found.`,
@@ -231,11 +250,7 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
       firstUserFrame: userFrame,
       evidence: [{ message: missing[0].trim(), file: userFrame?.path, line: userFrame?.line }],
       suggestions: [
-        {
-          message: `Declare the distribution that provides "${module}" with uv add ${module} if it is third-party. Import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
-          confidence: 'medium',
-          command: `uv add ${module}`,
-        },
+        resolveSuggestion,
         {
           message:
             'If the module is project code, run uv sync so the project package is installed in editable mode.',
@@ -404,7 +419,6 @@ export function refineWithDeclarations(
   const module = diagnosis.missingModule;
   if (!module) return diagnosis;
   const normalized = module.replace(/[-_.]+/g, '-').toLowerCase();
-  const suggestions: Suggestion[] = [];
 
   if (input.localModules.has(module)) {
     return {
@@ -447,14 +461,9 @@ export function refineWithDeclarations(
     };
   }
 
-  suggestions.push({
-    message: `Declare the distribution providing "${module}" with uv add ${module}, or verify the import name.`,
-    confidence: 'medium',
-    command: `uv add ${module}`,
-  });
-  suggestions.push({
-    message: 'Import names can differ from distribution names (PIL/pillow, yaml/PyYAML).',
-    confidence: 'medium',
-  });
-  return { ...diagnosis, suggestions: [...diagnosis.suggestions, ...suggestions] };
+  // The module is neither project code nor declared, so this refinement adds no
+  // new information: `diagnoseFailure` already reported the unknown provider.
+  // Appending here duplicated those suggestions, so the diagnosis is returned
+  // unchanged.
+  return diagnosis;
 }