pi-python-helper 0.1.1 → 0.2.0

package/extensions/tools/validation.ts

@@ -2,6 +2,12 @@ import { Type } from 'typebox';
 import { failure, result, warn } from '../../src/core/result.ts';
 import { runCommand } from '../../src/core/runner.ts';
 import { pytestCommand, uvLockCheck, uvSyncFrozen } from '../../src/build/commands.ts';
+import { describeRemovals, parseSyncOutput } from '../../src/build/sync.ts';
+import {
+  qualityCommands,
+  selectQualityRunners,
+  type QualityRunner,
+} from '../../src/build/quality.ts';
 import { diagnoseFailure } from '../../src/build/failure.ts';
 import { parsePytestOutput } from '../../src/build/pytest.ts';
 import { detectStaleArtifacts } from '../../src/build/staleness.ts';
@@ -10,18 +16,29 @@ import {
   requiredDeclarationsFrom,
 } from '../../src/project/conformance.ts';
 import { readInstalledDistributions } from '../../src/project/installed.ts';
+import { buildDeclaredIndex } from '../../src/dependencies/plan.ts';
+import { checkRequiredTools } from '../../src/environment/tools.ts';
 import { summarizeValidation, type ValidationStep } from '../../src/validation/bundle.ts';
 import { buildCompletionEvidence } from '../../src/validation/evidence.ts';
 import { checkTdd } from '../../src/validation/tdd.ts';
 import { join } from 'node:path';
 import { isFile } from '../../src/project/root.ts';
 import { runScanProject } from '../../src/project/scanner.ts';
-import { messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
+import { hasDirectory, messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
 
 function stepFrom(run: { code: number | null; timedOut: boolean }): ValidationStep {
   return { executed: true, ok: run.code === 0 && !run.timedOut, exitCode: run.code };
 }
 
+function skippedStep(name: string, reason: string): ValidationStep {
+  return { name, executed: false, ok: false, exitCode: null, skippedReason: reason };
+}
+
+/** A lock/quality step that the caller disabled rather than one that failed. */
+function disabledStep(name: string, reason: string): ValidationStep {
+  return { name, executed: false, ok: true, exitCode: null, skippedReason: reason };
+}
+
 export function registerValidationTools(pi: Pi): void {
   pi.registerTool({
     name: 'py_sync',
@@ -31,11 +48,19 @@ export function registerValidationTools(pi: Pi): void {
     promptSnippet: 'Preview or run the uv environment sync',
     promptGuidelines: [
       'Use py_sync with execute=false to preview the uv command, and execute=true only when the environment must be created or refreshed.',
+      'Use py_sync after changing pyproject.toml or uv.lock; a sync that removed packages is reported because later steps cannot run without them.',
     ],
     parameters: Type.Object({
       mode: Type.Optional(
         Type.Union([Type.Literal('check'), Type.Literal('sync')], {
-          description: 'check runs uv lock --check; sync runs uv sync --frozen --all-groups.',
+          description:
+            'check runs uv lock --check; sync runs uv sync --frozen --all-groups --all-extras.',
+        }),
+      ),
+      extras: Type.Optional(
+        Type.Union([Type.Literal('all'), Type.Literal('none')], {
+          description:
+            'Whether sync requests every [project.optional-dependencies] extra. Defaults to all: without it uv removes extras such as the dev tooling.',
         }),
       ),
       execute: Type.Optional(Type.Boolean()),
@@ -47,7 +72,8 @@ export function registerValidationTools(pi: Pi): void {
       try {
         const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
         const mode = params.mode ?? 'check';
-        const command = mode === 'check' ? uvLockCheck(ctx.cwd) : uvSyncFrozen(ctx.cwd);
+        const extras = params.extras ?? 'all';
+        const command = mode === 'check' ? uvLockCheck(ctx.cwd) : uvSyncFrozen(ctx.cwd, { extras });
         const lockPresent = await isFile(join(root, 'uv.lock'));
 
         if (!params.execute) {
@@ -55,7 +81,7 @@ export function registerValidationTools(pi: Pi): void {
             result(ctx.cwd, started, {
               ok: true,
               summary: `${mode} command preview generated; nothing was executed.`,
-              data: { executed: false, mode, command, lockPresent },
+              data: { executed: false, mode, extras, command, lockPresent },
               evidence: [{ kind: 'command_preview', ...command }],
               warnings: lockPresent
                 ? []
@@ -90,51 +116,148 @@ export function registerValidationTools(pi: Pi): void {
         });
         const output = `${run.stdout}\n${run.stderr}`;
         const diagnosis = run.code === 0 ? undefined : diagnoseFailure(output);
+        if (mode === 'check') {
+          return text(
+            result(ctx.cwd, started, {
+              ok: run.code === 0,
+              summary: run.timedOut
+                ? 'uv exceeded the time limit and was terminated.'
+                : run.code === 0
+                  ? 'uv.lock matches pyproject.toml.'
+                  : `uv check failed: ${diagnosis?.summary ?? 'see the captured output.'}`,
+              data: {
+                executed: true,
+                mode,
+                exitCode: run.code,
+                truncated: run.truncated,
+                timedOut: run.timedOut,
+                stdoutTail: run.stdout.slice(-4000),
+                stderrTail: run.stderr.slice(-4000),
+                diagnosis,
+              },
+              evidence: [{ kind: 'uv_command', mode, exitCode: run.code, executed: true }],
+              warnings: run.truncated
+                ? [
+                    {
+                      code: 'OUTPUT_TRUNCATED',
+                      message: 'Command output was truncated; only the tail is reported.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : [],
+              errors:
+                run.code === 0
+                  ? []
+                  : [
+                      {
+                        code: 'LOCKFILE_OUT_OF_DATE',
+                        message:
+                          diagnosis?.summary ??
+                          run.stderr.trim().slice(0, 500) ??
+                          'uv exited with a non-zero status.',
+                        severity: 'error' as const,
+                      },
+                    ],
+              suggestions: diagnosis?.suggestions ?? [],
+              commands: [command],
+              truncated: run.truncated,
+              projectRoot: root,
+            }),
+          );
+        }
+
+        // A sync that removed distributions is the explanation for every later
+        // "command not found", so it is reported even on exit code 0.
+        const inventory = parseSyncOutput(run.stdout, run.stderr);
+        const removals = describeRemovals(inventory);
+        const venvPath = join(root, '.venv');
+        const venvDir = (await hasDirectory(venvPath)) ? venvPath : undefined;
+        const toolchain = await checkRequiredTools(venvDir, ['pytest']);
+        const pytestMissing = toolchain.checked && toolchain.missing.includes('pytest');
 
         return text(
           result(ctx.cwd, started, {
-            ok: run.code === 0,
+            ok: run.code === 0 && !pytestMissing,
             summary: run.timedOut
               ? 'uv exceeded the time limit and was terminated.'
-              : run.code === 0
-                ? mode === 'check'
-                  ? 'uv.lock matches pyproject.toml.'
-                  : 'The environment was synchronised from the lockfile.'
-                : `uv ${mode} failed: ${diagnosis?.summary ?? 'see the captured output.'}`,
+              : run.code !== 0
+                ? `uv sync failed: ${diagnosis?.summary ?? 'see the captured output.'}`
+                : pytestMissing
+                  ? 'The environment was synchronised, but pytest is not installed in .venv afterwards.'
+                  : removals
+                    ? `The environment was synchronised from the lockfile. ${removals}`
+                    : 'The environment was synchronised from the lockfile.',
             data: {
               executed: true,
               mode,
+              extras,
               exitCode: run.code,
               truncated: run.truncated,
               timedOut: run.timedOut,
+              inventory,
+              removed: inventory.uninstalled,
+              toolchain,
               stdoutTail: run.stdout.slice(-4000),
               stderrTail: run.stderr.slice(-4000),
               diagnosis,
             },
-            evidence: [{ kind: 'uv_command', mode, exitCode: run.code, executed: true }],
-            warnings: run.truncated
-              ? [
-                  {
-                    code: 'OUTPUT_TRUNCATED',
-                    message: 'Command output was truncated; only the tail is reported.',
-                    severity: 'warning' as const,
-                  },
-                ]
-              : [],
+            evidence: [
+              {
+                kind: 'uv_command',
+                mode,
+                extras,
+                exitCode: run.code,
+                uninstalled: inventory.uninstalled,
+                toolchainMissing: toolchain.missing,
+                executed: true,
+              },
+            ],
+            warnings: [
+              ...(run.truncated
+                ? [
+                    {
+                      code: 'OUTPUT_TRUNCATED',
+                      message: 'Command output was truncated; only the tail is reported.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
+              ...(removals
+                ? [
+                    warn(
+                      'SYNC_REMOVED_PACKAGES',
+                      `${removals} Request the extras that provide them (for example uv sync --extra dev) or install everything with uv sync --all-extras.`,
+                      join(root, 'uv.lock'),
+                    ),
+                  ]
+                : []),
+            ],
             errors:
-              run.code === 0
+              run.code === 0 && !pytestMissing
                 ? []
                 : [
                     {
-                      code: mode === 'check' ? 'LOCKFILE_OUT_OF_DATE' : 'SYNC_FAILED',
-                      message:
-                        diagnosis?.summary ??
-                        run.stderr.trim().slice(0, 500) ??
-                        'uv exited with a non-zero status.',
+                      code: pytestMissing ? 'TOOLCHAIN_BROKEN' : 'SYNC_FAILED',
+                      message: pytestMissing
+                        ? 'pytest is not installed in the project environment after uv sync, so the test step cannot run.'
+                        : (diagnosis?.summary ??
+                          run.stderr.trim().slice(0, 500) ??
+                          'uv exited with a non-zero status.'),
                       severity: 'error' as const,
                     },
                   ],
-            suggestions: diagnosis?.suggestions ?? [],
+            suggestions: pytestMissing
+              ? [
+                  {
+                    message:
+                      extras === 'all'
+                        ? 'pytest is declared in an extra that uv still removed. Check that the extra name is spelled correctly in [project.optional-dependencies].'
+                        : 'Re-run the sync with extras=all, or add the extra that provides pytest.',
+                    confidence: 'high' as const,
+                    command: 'uv sync --frozen --all-groups --all-extras',
+                  },
+                ]
+              : (diagnosis?.suggestions ?? []),
             commands: [command],
             truncated: run.truncated,
             projectRoot: root,
@@ -158,6 +281,12 @@ export function registerValidationTools(pi: Pi): void {
     ],
     parameters: Type.Object({
       targets: Type.Optional(Type.Array(Type.String())),
+      quality: Type.Optional(
+        Type.Boolean({
+          description:
+            'Run the lint/type tools the project declares (ruff, pyright, and mypy when [tool.mypy] exists). Defaults to true.',
+        }),
+      ),
       execute: Type.Optional(Type.Boolean()),
       timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 3600 })),
       path: Type.Optional(Type.String()),
@@ -171,14 +300,44 @@ export function registerValidationTools(pi: Pi): void {
         const sync = uvSyncFrozen(ctx.cwd);
         const test = pytestCommand(ctx.cwd, { targets: params.targets });
         const timeoutMs = (params.timeoutSeconds ?? 1800) * 1000;
-        const commands = [lock, sync, test];
+        const runQuality = params.quality ?? true;
+
+        // The declared quality tools are read from the manifest so the bundle can
+        // match what CI runs without a separate configuration file.
+        const manifestScan = await runScanProject(ctx.cwd, { root, mode: 'manifest' }, signal);
+        const runners: QualityRunner[] = runQuality
+          ? selectQualityRunners({
+              declared: buildDeclaredIndex(
+                manifestScan.payload?.manifest ?? {
+                  dependencies: [],
+                  optionalDependencies: {},
+                  dependencyGroups: {},
+                },
+              ).keys(),
+              toolConfiguration: manifestScan.payload?.manifest?.toolConfiguration,
+            })
+          : [];
+        const quality = qualityCommands(ctx.cwd, runners);
+        const commands = [lock, sync, test, ...quality];
 
         if (!params.execute) {
           return text(
             result(ctx.cwd, started, {
               ok: true,
-              summary: `Validation sequence preview generated (${lockPresent ? 'uv lock --check, uv sync, pytest' : 'uv sync, pytest'}); nothing was executed.`,
-              data: { executed: false, lockPresent, steps: commands },
+              summary: `Validation sequence preview generated (${[
+                lockPresent ? 'uv lock --check' : undefined,
+                'uv sync',
+                'pytest',
+                ...runners.map((runner) => runner.name),
+              ]
+                .filter(Boolean)
+                .join(', ')}); nothing was executed.`,
+              data: {
+                executed: false,
+                lockPresent,
+                quality: runners.map((runner) => runner.name),
+                steps: commands,
+              },
               evidence: [
                 {
                   kind: 'validation_preview',
@@ -197,7 +356,8 @@ export function registerValidationTools(pi: Pi): void {
               errors: [],
               suggestions: [
                 {
-                  message: 'Set execute=true to run the sequence. This creates or refreshes .venv.',
+                  message:
+                    'Set execute=true to run the sequence. This creates or refreshes .venv, including every declared extra.',
                   confidence: 'high' as const,
                 },
               ],
@@ -221,17 +381,35 @@ export function registerValidationTools(pi: Pi): void {
           timeoutMs,
           maxBytes: 256 * 1024,
         });
-        const testRun =
-          syncRun.code === 0
-            ? await runCommand(test.executable, test.args, {
-                cwd: ctx.cwd,
-                signal,
-                timeoutMs,
-                maxBytes: 512 * 1024,
-              })
-            : undefined;
+        const syncInventory = parseSyncOutput(syncRun.stdout, syncRun.stderr);
+        const removals = describeRemovals(syncInventory);
+
+        // A sync can succeed while removing the interpreter-side tools the next
+        // step needs, so availability is re-checked instead of trusting exit 0.
+        const venvPath = join(root, '.venv');
+        const venvDir = (await hasDirectory(venvPath)) ? venvPath : undefined;
+        const toolchain = await checkRequiredTools(venvDir, [
+          'pytest',
+          ...runners.map((runner) => runner.name),
+        ]);
+        const pytestMissing = toolchain.checked && toolchain.missing.includes('pytest');
+        const syncOk = syncRun.code === 0 && !pytestMissing;
+        const skippedReason = pytestMissing
+          ? 'pytest is not installed in the project environment after uv sync, so the test step was skipped and no test result exists.'
+          : undefined;
+
+        const testRun = syncOk
+          ? await runCommand(test.executable, test.args, {
+              cwd: ctx.cwd,
+              signal,
+              timeoutMs,
+              maxBytes: 512 * 1024,
+            })
+          : undefined;
 
         const report = testRun ? parsePytestOutput(testRun.stdout, testRun.stderr) : undefined;
+        const testPassed = Boolean(report && testRun?.code === 0 && !report.incomplete);
+
         const scan = await runScanProject(ctx.cwd, { root, mode: 'manifest' }, signal);
         const installed = await readInstalledDistributions(join(root, '.venv'));
         const conformance = compareInstalledConformance({
@@ -244,19 +422,63 @@ export function registerValidationTools(pi: Pi): void {
 
         const lockStep: ValidationStep = lockRun
           ? stepFrom(lockRun)
-          : { executed: false, ok: false, exitCode: null };
-        const syncStep = stepFrom(syncRun);
+          : disabledStep(
+              'uv lock --check',
+              'uv.lock was not found, so the lock check was skipped.',
+            );
+        const syncStep: ValidationStep = syncOk
+          ? stepFrom(syncRun)
+          : {
+              ...stepFrom(syncRun),
+              ok: false,
+              skippedReason,
+            };
         const testStep: ValidationStep = testRun
           ? {
               ...stepFrom(testRun),
               failures: report ? report.counts.failed + report.counts.errors : undefined,
             }
-          : { executed: false, ok: false, exitCode: null };
+          : skippedStep(
+              'pytest',
+              syncRun.code !== 0
+                ? 'The sync step did not complete, so pytest was not run.'
+                : (skippedReason ?? 'pytest was not run.'),
+            );
+
+        // Quality commands only run once the tests pass: a failing test is the
+        // first actionable signal, and running both wastes the caller's budget.
+        const qualitySteps: ValidationStep[] = [];
+        for (const [index, runner] of runners.entries()) {
+          if (!testPassed) {
+            qualitySteps.push(
+              skippedStep(runner.name, 'Tests did not pass, so the quality check was skipped.'),
+            );
+            continue;
+          }
+          if (toolchain.checked && toolchain.missing.includes(runner.name)) {
+            qualitySteps.push(
+              skippedStep(
+                runner.name,
+                `${runner.name} is not installed in the project environment, so the quality check was skipped.`,
+              ),
+            );
+            continue;
+          }
+          const preview = quality[index];
+          const run = await runCommand(preview.executable, preview.args, {
+            cwd: ctx.cwd,
+            signal,
+            timeoutMs,
+            maxBytes: 256 * 1024,
+          });
+          qualitySteps.push({ name: runner.name, ...stepFrom(run) });
+        }
 
         const summary = summarizeValidation({
           lock: lockStep,
           sync: syncStep,
           test: testStep,
+          quality: qualitySteps,
           conformance: conformance.verdict,
           stale: staleness.stale,
         });
@@ -274,12 +496,17 @@ export function registerValidationTools(pi: Pi): void {
               executed: true,
               checks: summary.checks,
               lock: { ...lockStep, present: lockPresent },
-              sync: syncStep,
+              sync: {
+                ...syncStep,
+                uninstalled: syncInventory.uninstalled,
+                toolchainMissing: toolchain.missing,
+              },
               test: {
                 ...testStep,
                 counts: report?.counts,
                 failures: report?.failures.slice(0, 20),
               },
+              quality: qualitySteps,
               conformance,
               staleArtifacts: staleness,
               firstFailure: diagnosis,
@@ -290,14 +517,32 @@ export function registerValidationTools(pi: Pi): void {
                 checks: summary.checks,
                 lockExitCode: lockStep.exitCode ?? null,
                 syncExitCode: syncStep.exitCode ?? null,
+                syncUninstalled: syncInventory.uninstalled,
                 testExitCode: testStep.exitCode ?? null,
                 testCounts: report?.counts ?? null,
+                quality: qualitySteps.map((step) => ({ name: step.name, ok: step.ok })),
                 conformanceVerdict: conformance.verdict,
                 stale: staleness.stale,
               },
             ],
             warnings: [
+              ...(removals
+                ? [
+                    warn(
+                      'SYNC_REMOVED_PACKAGES',
+                      `${removals} The bundle requests every extra, so a removal here means the tool is not declared as one.`,
+                      join(root, 'uv.lock'),
+                    ),
+                  ]
+                : []),
               ...conformance.warnings,
+              ...qualitySteps
+                .filter((step) => step.executed && !step.ok)
+                .map((step) => ({
+                  code: 'QUALITY_CHECK_FAILED',
+                  message: `${step.name ?? 'quality check'} exited with code ${step.exitCode ?? 'unknown'}.`,
+                  severity: 'warning' as const,
+                })),
               ...staleness.artifacts.map((artifact) => ({
                 code: artifact.code,
                 message: artifact.message,
@@ -331,6 +576,16 @@ export function registerValidationTools(pi: Pi): void {
                       'Fix the failing step before reporting completion; a partial run is not evidence.',
                     confidence: 'high' as const,
                   },
+                  ...(pytestMissing
+                    ? [
+                        {
+                          message:
+                            'pytest is declared in an extra but is not installed after uv sync. Remove the extras=none override, or add the extra that provides pytest to [project.optional-dependencies].',
+                          confidence: 'high' as const,
+                          command: 'uv sync --frozen --all-groups --all-extras',
+                        },
+                      ]
+                    : []),
                   ...(diagnosis?.suggestions ?? []),
                 ],
             commands,
@@ -374,7 +629,7 @@ export function registerValidationTools(pi: Pi): void {
           .filter(Boolean);
         source = 'git diff';
       }
-      const checkpoint = checkTdd(changedPaths, params.testChangedPaths ?? changedPaths);
+      const checkpoint = checkTdd(changedPaths, params.testChangedPaths ?? []);
       return text(
         result(ctx.cwd, started, {
           ok: checkpoint.ok,
@@ -382,7 +637,16 @@ export function registerValidationTools(pi: Pi): void {
             ? `TDD checkpoint passed across ${changedPaths.length} changed path(s) from ${source}.`
             : 'TDD checkpoint found production changes without a related test change.',
           data: { ...checkpoint, changedPaths, source },
-          evidence: checkpoint.reasons.map((message) => ({ kind: 'tdd_blocker', message })),
+          evidence: [
+            ...checkpoint.reasons.map((message) => ({ kind: 'tdd_blocker', message })),
+            ...checkpoint.associations.map((entry) => ({
+              kind: 'tdd_association',
+              source: entry.source,
+              test: entry.test,
+              sharedTokens: entry.sharedTokens,
+              strength: entry.strength,
+            })),
+          ],
           warnings: checkpoint.reasons.map((message) => ({
             code: 'TDD_CHECKPOINT',
             message,

package/helpers/scan_project.py

@@ -35,7 +35,9 @@ from pathlib import Path
 
 # Bumped whenever the request or the result document changes shape, so the
 # caller can refuse to interpret a document it does not understand.
-SCANNER_VERSION = 1
+# 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
 
 KNOWN_SECTIONS = ("environment", "manifest", "imports")
 EXIT_OK = 0
@@ -510,9 +512,12 @@ def _is_type_checking_test(test) -> bool:
 
 
 class ImportCollector(ast.NodeVisitor):
+    """Collect top-level import names and the full dotted modules they reference."""
+
     def __init__(self) -> None:
         self.all: set[str] = set()
         self.type_checking: set[str] = set()
+        self.modules: set[str] = set()
         self._guard_depth = 0
 
     def _record(self, name: str) -> None:
@@ -536,12 +541,20 @@ class ImportCollector(ast.NodeVisitor):
     def visit_Import(self, node: ast.Import) -> None:
         for alias in node.names:
             self._record(alias.name.split(".")[0])
+            self.modules.add(alias.name)
 
     def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
         if node.level:  # relative import -> always local
+            for alias in node.names:
+                self.modules.add(alias.name)
             return
         if node.module:
             self._record(node.module.split(".")[0])
+            self.modules.add(node.module)
+            # `from pkg.db import database` names a submodule, not the package,
+            # so both spellings are recorded and either can match a change.
+            for alias in node.names:
+                self.modules.add(f"{node.module}.{alias.name}")
 
 
 def scan_imports(root: Path, max_files: int) -> dict:
@@ -589,6 +602,7 @@ def scan_imports(root: Path, max_files: int) -> dict:
                 {
                     "path": relative,
                     "imports": sorted(names),
+                    "importModules": sorted(collector.modules),
                     "typeCheckingImports": sorted(collector.type_checking),
                 }
             )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-python-helper",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Python (uv) development tools for the pi coding agent",
   "type": "module",
   "keywords": [

package/skills/python-development/SKILL.md

@@ -10,24 +10,24 @@ license: Apache-2.0
 
 ## 조사 및 작업 순서 (Investigation order)
 
-1. 인터프리터나 가상환경 상태가 불확실할 때는 `py_environment`를 실행하세요. 잘못된 Python으로 테스트를 실행하는 것이 가장 흔한 실패 원인입니다.
+1. 인터프리터나 가상환경 상태가 불확실할 때는 `py_environment`를 실행하세요. 잘못된 Python으로 테스트를 실행하는 것이 가장 흔한 실패 원인입니다. `interpreterOrigin: 'venv'`이면 분석이 프로젝트 환경을 봤다는 뜻이고, `'path'`이면 호스트 PATH의 Python을 봤다는 뜻입니다. `available`은 "지금 실행 가능", `installable`은 "uv sync로 설치 가능"(선언되었지만 실행 파일 없음)입니다.
 2. `pyproject.toml`이나 `uv.lock`을 편집하기 전에 `py_project_inspect`로 레이아웃(src/flat), 의존성 그룹, lockfile 드리프트, **환경 정합성**(선언 ↔ lock ↔ 실제 설치본)을 확인하세요. 정합성은 `consistent` / `drifted` / `unverifiable` 중 하나이며, `unverifiable`을 일치로 해석하지 마세요.
 3. 의존성을 추가/이동하기 전에 `py_dependency_plan`을 사용하세요. `ast`로 실제 import를 스캔하여 다음을 구분합니다:
    - 선언되지 않은 import (런타임 오류로 이어짐)
    - `[project] dependencies`가 아니라 dev 그룹/extra에만 선언된 런타임 import
    - `uv.lock`에 없거나 스펙을 만족하지 않는 버전
 4. import 이름과 배포 이름은 다를 수 있습니다(`PIL`/`pillow`, `yaml`/`PyYAML`). `py_dependency_plan`의 제안을 `uv add`로 적용하세요.
-5. 소스 코드를 수정한 후에는 `py_test_select`로 변경 파일과 연관된 테스트를 선별하세요. 매칭이 실패하면 전체 스위트가 범위가 되며, 선택 이유가 함께 반환됩니다.
-6. 테스트 실행은 `py_test`를 사용하세요. `execute=false`로 먼저 미리보기하고, 실제 실행 시에만 `execute=true`를 전달합니다.
-7. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다.
-8. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요.
+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`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
 
 ## 안전 규칙 (Safety)
 
-- `py_sync`와 `py_validation_bundle`은 `execute: true`가 명시적으로 전달되기 전까지 명령을 실행하지 않고 미리보기만 반환합니다. `execute=true`는 `.venv`를 생성/갱신하므로 사용자 확인 없이 반복 실행하지 마세요.
+- `py_sync`와 `py_validation_bundle`은 `execute: true`가 명시적으로 전달되기 전까지 명령을 실행하지 않고 미리보기만 반환합니다. `execute=true`는 `.venv`를 생성/갱신하므로 사용자 확인 없이 반복 실행하지 마세요. `extras: 'none'`은 프로젝트가 요청할 때만 사용하세요: extra로 선언된 dev 도구를 삭제할 수 있습니다.
 - Python에는 ROS의 `cmd_vel`처럼 위험을 결정론적으로 알려주는 이름이 없습니다. 다음은 되돌릴 수 없는 작업으로 취급하세요: `uv publish`/`twine upload`(공개 불가 회수), `git push --force`, `git reset --hard`/`git clean -fd`, `alembic downgrade`, `DROP`/`DELETE`(WHERE 없는), `rm -rf`, `conda env remove`.
 - 가상환경을 파괴하는 명령(`rm -rf .venv`, `uv venv --clear`)이나 전역 Python에 패키지를 설치하는 명령(`pip install` without a venv)을 임의로 실행하지 마세요.
 - 도구는 파일을 쓰지 않습니다. `pyproject.toml`/`uv.lock` 수정은 항상 명시적인 편집 도구로 수행하세요.
@@ -36,6 +36,11 @@ license: Apache-2.0
 
 - `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]` 추가 여부만 검토하세요.
+- `MARKER_SPLIT_LOCK_ENTRIES`는 정상입니다. uv가 같은 배포판을 마커별로 여러 버전으로 기록한 것이며, 설치 버전이 그중 하나와 일치하면 드리프트가 아닙니다.
+- `TOOL_NOT_INSTALLED`는 lock에는 있지만 `.venv`에 실행 파일이 없다는 뜻입니다. `uv sync` 직후에 발생했다면 sync가 extra를 삭제한 것이므로 `uv sync --frozen --all-groups --all-extras`로 복구하세요.
+- `SYNC_REMOVED_PACKAGES`는 sync가 `.venv`에서 패키지를 제거했음을 뜻하며, 같은 실행에서 이어지는 "command not found"의 원인입니다.
+- `UNMAPPED_IMPORTS`는 분석한 인터프리터가 import를 배포판에 연결하지 못했다는 뜻입니다. 이 상태에서는 `UNDECLARED_IMPORT`가 "선언 누락"이 아니라 "배포 이름 미확인"일 수 있으므로, 제안된 `uv add` 명령이 없으면 배포 이름을 직접 확인하세요.
 - `INSTALLED_VERSION_MISMATCH`는 `uv add`/`uv lock` 후 `uv sync`를 잊은 상태입니다. `uv lock --check`는 이걸 잡지 못하니(락은 최신) 테스트를 신뢰하기 전에 `uv sync --frozen`을 실행하세요.
 - `INSTALLED_PACKAGE_UNTRACKED`는 `.venv`에만 있고 lock에 없는 패키지입니다. 에이전트가 `uv pip install`로 임의 설치했을 가능성을 의심하세요.
 - `CONDITIONAL_PACKAGES_ABSENT`는 정상입니다. `sys_platform == 'win32'`나 `python_version < '3.11'` 같은 마커 때문에 해당 플랫폼에 설치되지 않은 항목이며, 드리프트로 취급하지 마세요.