pyfltr 2.2.2__tar.gz → 3.0.0__tar.gz

{pyfltr-2.2.2 → pyfltr-3.0.0}/.claude/agents/tool-compat-checker.md

@@ -1,6 +1,6 @@
 ---
 name: tool-compat-checker
-description: pyfltr が呼び出す外部ツール（ruff/mypy/pytest/pylint/pyright/ty/black/isort/autoflake/pyupgrade/pflake8/markdownlint/textlint）のコマンドライン引数・出力フォーマットが最新版と乖離していないか検査する。PRレビュー前や make update 後に呼び出す。必ず「チェック対象ツール名」または「ALL」を引数として与えること。
+description: pyfltr が呼び出す外部ツール（ruff/mypy/pytest/pylint/pyright/ty/markdownlint/textlint/shellcheck/shfmt/typos/actionlint/eslint/biome/oxlint/prettier/tsc/vitest/cargo-fmt/cargo-clippy/cargo-check/cargo-test/cargo-deny/dotnet-format/dotnet-build/dotnet-test/uv-sort/ec/pre-commit）のコマンドライン引数・出力フォーマットが最新版と乖離していないか検査する。PRレビュー前や make update 後に呼び出す。必ず「チェック対象ツール名」または「ALL」を引数として与えること。
 tools: Read, Grep, Glob, WebFetch, Bash
 ---
 

{pyfltr-2.2.2 → pyfltr-3.0.0}/.claude/skills/pyfltr-add-tool/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pyfltr-add-tool
-description: pyfltr に新しい formatter / linter / tester を追加する際の定型手順チェックリスト。config.py / command.py / error_parser.py / docs/index.md / tests を一貫して更新する。
-disable-model-invocation: true
+description: pyfltr に新しい formatter / linter / tester を追加する際の定型手順チェックリスト。config.py / command.py / error_parser.py / docs/guide/index.md / tests を一貫して更新する。
 ---
 
 # pyfltr 新ツール追加チェックリスト
@@ -45,7 +44,22 @@ BUILTIN_COMMANDS: dict[str, CommandInfo] = {
 "<new-tool>-fast": True,             # fast 実行対象か
 ```
 
-### 1-3. プリセット（`load_config` 内）
+### 1-3. 言語カテゴリ定数（`config.py` 上部）
+
+新ツールが特定言語専用の場合、対応する定数タプルに追加する。
+
+```python
+PYTHON_COMMANDS: tuple[str, ...] = (
+    ...
+    "<new-tool>",
+)
+```
+
+カテゴリ: `PYTHON_COMMANDS`・`JAVASCRIPT_COMMANDS`・`RUST_COMMANDS`・`DOTNET_COMMANDS`。
+カテゴリに属するツールは `python`/`javascript`/`rust`/`dotnet` キーが `False` のときゲートで無効化される。
+全言語共通のツール（`typos`・`ec`・`actionlint` 等）はいずれのカテゴリにも属さない。
+
+### 1-4. プリセット（`load_config` 内）
 
 `preset = "latest"` 等で既定挙動を変えたい場合、`config.values["<new-tool>"]` を明示的にon/offする。
 
@@ -87,9 +101,9 @@ uv add --optional <extra> <new-tool-package>
 
 ## 6. ドキュメント
 
-- `docs/index.md` の「対応ツール」一覧に追記する
+- `docs/guide/index.md` の「対応ツール」一覧に追記する
 
-対応ツール一覧は`docs/index.md`に一元化されている。`README.md`には書かない。
+対応ツール一覧は`docs/guide/index.md`に一元化されている。`README.md`には書かない。
 
 ## 7. 検証
 
@@ -103,7 +117,7 @@ uv run pyfltr run-for-agent
 
 雛形にすべき既存ツールは `pyfltr/command.py` と `pyfltr/error_parser.py` を参照:
 
-- formatterの例: `ruff-format` / `black`
+- formatterの例: `ruff-format` / `prettier`
 - linterの例: `ruff-check` / `mypy`
 - testerの例: `pytest`（ほぼ唯一なので新規testerは要相談）
 

{pyfltr-2.2.2 → pyfltr-3.0.0}/.github/workflows/ci.yaml

@@ -72,7 +72,7 @@ jobs:
         run: uv sync --all-extras --all-groups
 
       - name: Test with pyfltr
-        run: uv run pyfltr ci
+        run: uv run pyfltr ci --output-format=github-annotations
 
       - name: Prune uv cache for CI
         run: uv cache prune --ci
@@ -119,7 +119,7 @@ jobs:
         run: uv sync --all-extras --all-groups
 
       - name: Test with pyfltr
-        run: uv run pyfltr ci
+        run: uv run pyfltr ci --output-format=github-annotations
 
       - name: Prune uv cache for CI
         run: uv cache prune --ci

{pyfltr-2.2.2 → pyfltr-3.0.0}/.gitignore

@@ -211,3 +211,9 @@ __marimo__/
 # Claude Code (個人設定とランタイム生成ファイル)
 .claude/settings.local.json
 .claude/.format-dirty
+
+# spec-driven 一時ファイル (作業中メモ・サブエージェント出力)
+# `respect-gitignore=true` 既定動作により pyfltr の textlint からも自動除外される
+*.working.md
+*.review-*.md
+*.research-*.md

pyfltr-3.0.0/.textlintignore

@@ -0,0 +1,2 @@
+# spec-drivenワークフローの一時ドキュメント（実装完了時に削除される）
+**/*.working.md

pyfltr-3.0.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md: pyfltr
+
+## 開発手順
+
+- `make update`: 依存更新 + pre-commit autoupdate + pinactアクション更新 + 全テスト実行
+  - `make update-actions`: GitHub Actionsのハッシュピン更新のみ（mise経由でpinact実行）
+- テストコードは`pyfltr/xxx_.py`に対して`tests/xxx_test.py`として配置する
+- 実行パイプラインの構造: `run_pipeline`（main.py）がTUI/非TUI分岐の最上位関数。パイプライン共通の前処理（ファイル展開など）はこの関数内でTUI起動前に実行する
+- コミット前の検証方法: `uv run pyfltr run-for-agent`
+  - ドキュメントなどのみの変更の場合は省略可（pre-commitで実行されるため）
+  - テストコードの単体実行なども極力 `uv run pyfltr run-for-agent <path>` を使う（pytestを直接呼び出さない）
+    - 詳細な情報などが必要な場合に限り `uv run pytest -vv <path>` などを使用
+  - JSONL出力は`header`（実行環境・`run_id`・`schema_hints`）→ `diagnostic`+`tool`（ツール完了ごと）→ `warning`→ `summary`（末尾）の順に出力される。末尾の`summary`で`failed`と`diagnostics`を確認し、必要に応じて`diagnostic`行のファイル・行番号・メッセージを参照する。`header.run_id`（ULID）は実行アーカイブの参照キー
+  - `header.schema_hints`はJSONL各フィールドの意味をLLM向け英語ガイドとして毎runに付与する
+  - `summary.guidance`（英語配列）は`failed > 0`のときのみ付与され、`tool.retry_command` / `--only-failed` / `show-run` の案内を示す
+  - `diagnostic`の任意フィールド: `rule`・`rule_url`（対応ツールのみ）・`severity`（3値に正規化）・`fix`（値域の詳細は後述）
+  - `fix`は`"safe"` / `"unsafe"` / `"suggested"` / `"none"`の4値。ツールが自動修正情報を返さない場合はフィールドごと省略
+  - `tool`の任意フィールド: `retry_command`（当該ツールで失敗したファイルのみに絞った再実行コマンド）・`truncated`（smart truncation発生時。`archive`パスで全文参照）
+  - `retry_command`の追加仕様: 失敗時（`has_error=true`）のみ出力。成功時・`cached=true`時は出力されない。失敗ファイルを特定できない場合はターゲット位置引数が空
+  - `tool`のキャッシュ関連フィールド: `cached`（ファイルhashキャッシュから復元されたとき `true`）・`cached_from`（`cached=true` 時のソース `run_id`）
+  - 詳細仕様は`docs/guide/usage.md`の「jsonlスキーマ」節および`llms.txt`を参照。`--output-format=sarif` / `github-annotations` でCI向け形式にも切り替え可能
+  - `--fail-fast`: 1ツールでもエラーが出た時点で残りを打ち切る（起動済みはterminate、未開始はskipped扱い）
+  - `--no-cache`: ファイルhashキャッシュを無効化する。現状はtextlintのみ対象
+  - `--only-failed`: 直前runから失敗ツール・失敗ファイルを抽出し、ツール別にその組み合わせのみ再実行する。直前run無し/失敗ツール無し/targets交差空ならメッセージを出してrc=0で成功終了する
+  - `--from-run <RUN_ID>`: `--only-failed`の参照対象runを明示指定する（前方一致・`latest`対応）。併用前提で単独指定は拒否。不在`<RUN_ID>`時は警告を出してrc=0で早期終了する
+  - `header.run_id`はユーザーキャッシュに保存された該当runの参照キー。`pyfltr list-runs`で一覧、`pyfltr show-run <run_id>`で詳細（`<run_id>`は前方一致・`latest`エイリアス可）を参照する。`--tool <name>`でdiagnostics全件、`--tool <name> --output`で`output.log`全文が得られる
+  - MCPクライアント（Claude Desktopなど）からは`pyfltr mcp`でMCPサーバーを起動する。提供ツールは`list_runs` / `show_run` / `show_run_diagnostics` / `show_run_output` / `run_for_agent`の5種類で、アーカイブ参照と実行を行える
+
+## 注意点
+
+- `uv run mkdocs build --strict`でリンク・nav整合性を検証（ただし日本語アンカーリンク`#見出し日本語`はMkDocs TOCで解決できずINFO通知のみで`--strict`でも検知されないため手動確認要）
+- 内部リンクは英数アンカーを優先する。MkDocs（Material）のslugifyは英数のみを採用してアンカー生成するが、markdownlint MD051は見出し原文を見るため、`{#id}`記法で明示併設する（例:「### jsonl形式の使い方 {#jsonl}」）
+- `docs/guide/index.md`の対応ツール一覧と`mkdocs.yml`内llmstxt `markdown_description`の「対応ツール」節は人手同期（SSOT化しない運用）
+- `mkdocs.yml`内llmstxt `markdown_description`にはLLMが利用する際に有用な情報のみ記載する（`run-for-agent`サブコマンド、主要オプションなど）。LLMにとって不要な情報はdocs側をSSOTとし、多重管理を避ける
+- ドキュメント構成変更時は`docs/development/development.md`の「READMEとdocsの役割分担」節を先に参照

{pyfltr-2.2.2 → pyfltr-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfltr
-Version: 2.2.2
+Version: 3.0.0
 Summary: Python Formatters, Linters, and Testers Runner.
 Project-URL: Homepage, https://github.com/ak110/pyfltr
 Author-email: "aki." <mark@aur.ll.to>
@@ -16,28 +16,25 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: <4.0,>=3.11
-Requires-Dist: autoflake>=2.0
-Requires-Dist: black>=22.0
-Requires-Dist: dill>=0.3
-Requires-Dist: flake8-bugbear>=23.0
-Requires-Dist: flake8-tidy-imports>=4.11.0
-Requires-Dist: isort>=5.0
-Requires-Dist: mypy>=1.0
+Requires-Dist: mcp>=1.0
 Requires-Dist: natsort>=8.4.0
-Requires-Dist: pre-commit>=4.5.1
-Requires-Dist: pylint-pydantic>=0.4.1
-Requires-Dist: pylint>=3.0
-Requires-Dist: pyproject-flake8>=7.0
-Requires-Dist: pyright[nodejs]>=1.1.403
-Requires-Dist: pytest-asyncio>=1.0.0
-Requires-Dist: pytest>=7.0
-Requires-Dist: pyupgrade>=3.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: psutil>=6.0
+Requires-Dist: python-ulid>=3.0
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: ruff>=0.12.1
 Requires-Dist: textual>=8.0.0
-Requires-Dist: ty>=0.0.26
-Requires-Dist: uv-sort>=0.5
-Provides-Extra: pyright
+Provides-Extra: python
+Requires-Dist: dill>=0.3; extra == 'python'
+Requires-Dist: mypy>=1.0; extra == 'python'
+Requires-Dist: pre-commit>=4.5.1; extra == 'python'
+Requires-Dist: pylint-pydantic>=0.4.1; extra == 'python'
+Requires-Dist: pylint>=3.0; extra == 'python'
+Requires-Dist: pyright[nodejs]>=1.1.403; extra == 'python'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'python'
+Requires-Dist: pytest>=7.0; extra == 'python'
+Requires-Dist: ruff>=0.12.1; extra == 'python'
+Requires-Dist: ty>=0.0.26; extra == 'python'
+Requires-Dist: uv-sort>=0.5; extra == 'python'
 Description-Content-Type: text/markdown
 
 # pyfltr: Python Formatters, Linters, and Testers Runner
@@ -45,7 +42,8 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/ak110/pyfltr/actions/workflows/ci.yaml/badge.svg)](https://github.com/ak110/pyfltr/actions/workflows/ci.yaml)
 [![PyPI version](https://badge.fury.io/py/pyfltr.svg)](https://badge.fury.io/py/pyfltr)
 
-各種formatter / linter / testerをまとめて並列実行するツール。
+Python / Rust / .NET / TypeScript・JavaScript / ドキュメントなど多言語プロジェクトのformatter・linter・testerを単一コマンドで並列実行するCLIツール。
+（要Python 3.11以上）
 
 ## 特徴
 
@@ -55,13 +53,34 @@ Description-Content-Type: text/markdown
 - 除外指定（exclude）の書式差をツール間で吸収
 - 自動修正系ツール（ruff format・prettierなど）を修正と失敗扱いの両立で実行
 - LLMエージェント向けJSON Lines出力（`pyfltr run-for-agent`・`PYFLTR_OUTPUT_FORMAT`環境変数・`--output-format=jsonl`）に対応
+- MCPサーバーを本体同梱（`pyfltr mcp`）。Claude Desktopなどのエージェントから直接lint実行・アーカイブ参照が行える
+- シェル補完スクリプト生成（`pyfltr generate-shell-completion`）に対応
 
 ## インストール
 
 ```shell
 pip install pyfltr
+# uv を使う場合
+uv add --dev pyfltr
 ```
 
+uvxでの実行も可能。
+
+```shell
+uvx pyfltr --help
+```
+
+Python系ツール（ruff / mypy / pylint / pyright / ty / pytest / uv-sort）を利用する場合は、extrasで追加依存を導入する。
+
+```shell
+pip install 'pyfltr[python]'
+```
+
+Python / JavaScript / Rust / .NETの各言語カテゴリに属するツールはすべて既定で無効（opt-in）である。
+`preset = "latest"` + 言語カテゴリキー（`python` / `javascript` / `rust` / `dotnet`）の`true`指定だけで、当該言語の推奨ツール一式が有効化される。
+プリセット非収録のツール（`ty`など）を追加したい場合のみ個別に`{command} = true`を指定する。
+詳細は[設定項目](docs/guide/configuration.md)を参照。
+
 ## ドキュメント
 
 - <https://ak110.github.io/pyfltr/> — 概要・対応ツール一覧・設定リファレンス

pyfltr-3.0.0/README.md

@@ -0,0 +1,49 @@
+# pyfltr: Python Formatters, Linters, and Testers Runner
+
+[![CI](https://github.com/ak110/pyfltr/actions/workflows/ci.yaml/badge.svg)](https://github.com/ak110/pyfltr/actions/workflows/ci.yaml)
+[![PyPI version](https://badge.fury.io/py/pyfltr.svg)](https://badge.fury.io/py/pyfltr)
+
+Python / Rust / .NET / TypeScript・JavaScript / ドキュメントなど多言語プロジェクトのformatter・linter・testerを単一コマンドで並列実行するCLIツール。
+（要Python 3.11以上）
+
+## 特徴
+
+- 多言語対応のformatter・linter・testerをまとめて呼び出す単一コマンド
+- 複数ツールの並列実行による総実行時間の短縮
+- 設定の集約: `pyproject.toml`に寄せた統一設定
+- 除外指定（exclude）の書式差をツール間で吸収
+- 自動修正系ツール（ruff format・prettierなど）を修正と失敗扱いの両立で実行
+- LLMエージェント向けJSON Lines出力（`pyfltr run-for-agent`・`PYFLTR_OUTPUT_FORMAT`環境変数・`--output-format=jsonl`）に対応
+- MCPサーバーを本体同梱（`pyfltr mcp`）。Claude Desktopなどのエージェントから直接lint実行・アーカイブ参照が行える
+- シェル補完スクリプト生成（`pyfltr generate-shell-completion`）に対応
+
+## インストール
+
+```shell
+pip install pyfltr
+# uv を使う場合
+uv add --dev pyfltr
+```
+
+uvxでの実行も可能。
+
+```shell
+uvx pyfltr --help
+```
+
+Python系ツール（ruff / mypy / pylint / pyright / ty / pytest / uv-sort）を利用する場合は、extrasで追加依存を導入する。
+
+```shell
+pip install 'pyfltr[python]'
+```
+
+Python / JavaScript / Rust / .NETの各言語カテゴリに属するツールはすべて既定で無効（opt-in）である。
+`preset = "latest"` + 言語カテゴリキー（`python` / `javascript` / `rust` / `dotnet`）の`true`指定だけで、当該言語の推奨ツール一式が有効化される。
+プリセット非収録のツール（`ty`など）を追加したい場合のみ個別に`{command} = true`を指定する。
+詳細は[設定項目](docs/guide/configuration.md)を参照。
+
+## ドキュメント
+
+- <https://ak110.github.io/pyfltr/> — 概要・対応ツール一覧・設定リファレンス
+- <https://ak110.github.io/pyfltr/llms.txt> — LLM向け構造化インデックス
+- [docs/development/development.md](docs/development/development.md) — 開発者向け情報

pyfltr-3.0.0/docs/development/architecture.md

@@ -0,0 +1,135 @@
+# アーキテクチャ概要
+
+pyfltrの実装構造とモジュール責務分離の設計判断をまとめる。
+本ページは保守・拡張に携わる開発者向け。
+利用者向けの機能解説は[CLIコマンド](../guide/usage.md)・[設定項目](../guide/configuration.md)を参照。
+
+## 実行パイプライン
+
+`pyfltr.main.run_pipeline()`がCLI/MCPの双方から呼び出される最上位エントリ。
+TUI/非TUIの分岐はこの関数の内側で行い、パイプライン共通の前処理（ファイル展開・`--only-failed`絞り込み・アーカイブ初期化など）はTUI起動より前に集約する。
+
+実行ステージは次の3段で構成する。
+
+1. fixステージ — `{command}-fix-args`が定義された有効なlinterを順次`--fix`付きで実行する（`ci`サブコマンドは無効）
+2. formatterステージ — `ruff-format`・`prettier`等のformatterを直列または並列で実行する
+3. linter/testerステージ — 残りのlinter/testerを並列実行する
+
+各ステージの結果は`CommandResult`に集約され、ステージ完了ごとに`archive_hook`へ渡される。
+ステージ間の中断（`--fail-fast`時の打ち切りなど）は`stage_runner`の共通ヘルパーで吸収する。
+
+## モジュール構成
+
+`run_pipeline()`から呼び出される主要モジュールと責務を示す。
+
+### CLIエントリ
+
+| モジュール | 責務 |
+| --- | --- |
+| `main.py` | argparse構築・サブコマンドディスパッチ・`run_pipeline()`本体・retry_command生成委譲 |
+| `cli.py` | 非TUI実行器。3ステージのループとログ出力を担う |
+| `ui.py` | TUI実行器。Textualベース。`call_from_thread`を介して非同期にステージを駆動する |
+| `stage_runner.py` | `cli.py`/`ui.py`共通の小さなヘルパー（`make_skipped_result()`・`cancel_pending_futures()`） |
+| `executor.py` | プロセスプール管理 |
+
+### コマンド実行
+
+| モジュール | 責務 |
+| --- | --- |
+| `command.py` | `execute_command()`（subprocess起動・ファイル渡し・結果収集）と`CommandResult`データクラス |
+| `error_parser.py` | ツール出力の解析と`ErrorLocation`生成 |
+| `rule_urls.py` | ツール別の公式ドキュメントURL組み立てテンプレート |
+| `precommit.py` | `.pre-commit-config.yaml`の解釈（自動SKIP対応） |
+
+### 設定とパス処理
+
+| モジュール | 責務 |
+| --- | --- |
+| `config.py` | `pyproject.toml`読み込み・`CommandInfo`定義・プリセット・言語カテゴリ（python / javascript / rust / dotnet）ゲート処理 |
+| `paths.py` | `normalize_separators()`によるパス区切りの統一 |
+| `warnings_.py` | JSONL `warning`レコード生成 |
+
+### 出力フォーマット
+
+| モジュール | 責務 |
+| --- | --- |
+| `llm_output.py` | JSONL出力（`header`/`diagnostic`/`tool`/`warning`/`summary`の各レコード生成）・smart truncation |
+| `sarif_output.py` | SARIF 2.1.0形式のJSON生成 |
+| `github_annotations.py` | GitHub Annotation形式（`::error file=...`等）の生成 |
+| `shell_completion.py` | bash/PowerShell補完スクリプト生成 |
+
+### 実行アーカイブと再実行支援
+
+| モジュール | 責務 |
+| --- | --- |
+| `archive.py` | `ArchiveStore`（書き込み・読み取り・クリーンアップ）・`policy_from_config()` |
+| `cache.py` | `CacheStore`（ファイルhashベースのスキップキャッシュ）・`is_cacheable()`・`resolve_config_files()` |
+| `runs.py` | `list-runs`/`show-run`サブコマンド本体・`resolve_run_id()`（前方一致・`latest`エイリアス） |
+| `retry.py` | `retry_command`生成ヘルパー群（`detect_launcher_prefix()`・`build_retry_args_template()`等） |
+| `only_failed.py` | `--only-failed`フィルター本体・`ToolTargets` dataclass |
+
+### MCPサーバー
+
+| モジュール | 責務 |
+| --- | --- |
+| `mcp_.py` | FastMCPサーバー本体・5ツール（`list_runs`/`show_run`/`show_run_diagnostics`/`show_run_output`/`run_for_agent`）・stdio隔離 |
+
+## サブコマンドとargparse
+
+argparse subparsers（`required=True`）でサブコマンドを必須化し、引数なし実行時のフォールバック挙動は持たない。
+共通オプションは`parents=[common]`で各サブパーサーへ継承する。
+サブコマンド別の既定値（`exit_zero_even_if_formatted`・`commands`・`output_format`・`include_fix_stage`）は`_apply_subcommand_defaults()`で手動注入する。
+`set_defaults()`経由の注入を避けたのは、共通親パーサーを継承しているサブパーサーに対して他サブパーサーのdefaultが書き換わる既知挙動を回避するため。
+
+サブコマンド一覧と用途は[CLIコマンド](../guide/usage.md)を参照。
+
+## 主要な設計判断
+
+### 言語カテゴリはゲートとして働く
+
+`python` / `javascript` / `rust` / `dotnet`の各言語カテゴリに属するツールは既定で無効（カテゴリキーが既定`false`）。
+対象外プロジェクトで意図しないツール実行が起こることを避けるため、対応する言語カテゴリキー（例: `python = true`）でゲートを開けるか、`{command} = true`の個別明示が必要。
+
+プリセットは各時点の推奨ツール構成を示すスナップショットで言語別ツールも含むが、カテゴリキーが`false`のままだとプリセット由来の該当ツール`true`をゲート処理で`false`へ押し戻す。
+個別`{command} = true`はゲートを越えて最優先される。
+Python系の追加依存は`pyfltr[python]`オプショナルグループに分離する。
+JavaScript / Rust / .NET系は各言語のツールチェイン（Node.js・cargo・dotnet CLI）が前提のため、pyfltr本体はこれらの依存を抱えない。
+
+代替案として「完全別パッケージ（`pyfltr-python`）に分離」も検討したが、リポジトリ・リリース・バージョン整合の複雑度が増し、ユーザー体験もextras方式より劣るため不採用とした。
+
+### 必須依存は最小化
+
+本体必須依存は次の役割に限定する。
+
+- 骨組み: `textual`（TUI）・`natsort`（自然順ソート）・`pyyaml`（pre-commit設定）
+- run_id生成: `python-ulid`
+- MCP同梱: `mcp`・`platformdirs`
+- プロセス判定: `psutil`（`git commit`経由起動を親系列で検出してMM状態ガイダンスを出す用途）
+
+`mcp`を本体必須に含めるのはサーバー同梱体験（`pyfltr mcp`が即座に使える）を保つため。
+
+### subprocess実行はPopen一本化
+
+`command._run_subprocess()`は`subprocess.Popen`ベースに統一する。
+`--fail-fast`の中断処理（外部スレッドからの`terminate()`呼び出し）が成立する基盤として必要。
+`_active_processes`は`threading.Lock`で排他し、追加・削除と中断の衝突を防ぐ。
+
+`_resolve_bin_commandline()`の`mise --version`、`_filter_by_gitignore()`の`git check-ignore`、`main.py`の`cls`/`clear`はパイプライン外のため対象外。
+
+### `cli.py`/`ui.py`の共通化はヘルパーに絞る
+
+`cli.py`は`call_from_thread`を持たない直接呼び出し、`ui.py`はRich UIへの`call_from_thread`埋め込みという構造差がある。
+完全共通化はlock取得タイミング差で実装が複雑になるため、`make_skipped_result()`・`cancel_pending_futures()`の2関数を`stage_runner.py`へ抽出するに留める。
+残余重複は`# pylint: disable=duplicate-code`を理由コメント付きで維持する。
+
+### `main.py`分割の方針
+
+retry系ヘルパー・`--only-failed`フィルター・パス正規化を専用モジュールへ分離し、`main.py`の肥大化を抑える。
+`run_pipeline()`本体は中核として残し、分割対象から外す。
+
+| 移動先 | 内容 |
+| --- | --- |
+| `retry.py` | `detect_launcher_prefix()`・`build_retry_args_template()`等のretry系5関数と`_VALUE_OPTIONS` |
+| `only_failed.py` | `apply_filter()`（5サブ関数に責務分割）・`ToolTargets` dataclass |
+| `paths.py` | `normalize_separators()` |
+| `stage_runner.py` | `cli.py`/`ui.py`共通の2ヘルパー |

pyfltr-3.0.0/docs/development/archive-and-cache.md

@@ -0,0 +1,174 @@
+# 実行アーカイブとファイルhashキャッシュ
+
+pyfltrが提供する2つのユーザーキャッシュ基盤の設計判断と内部仕様。
+利用者向けの設定キーや有効/無効化方法は[設定項目](../guide/configuration.md)を参照。
+
+## 共通の前提
+
+両機能は同じユーザーキャッシュディレクトリ配下に保存先を持つ。
+保存ルートは`platformdirs.user_cache_dir("pyfltr")`で解決し、環境変数`PYFLTR_CACHE_DIR`で上書きできる（テスト・運用上の強制上書き用）。
+
+| OS | 既定の保存ルート |
+| --- | --- |
+| Linux | `~/.cache/pyfltr/` |
+| macOS | `~/Library/Caches/pyfltr/` |
+| Windows | `%LOCALAPPDATA%\pyfltr\Cache` |
+
+プロジェクトローカルにキャッシュを作らない方針を採る。
+`.gitignore`運用の負担を増やさず、複数プロジェクト横断での参照を可能にするため。
+
+## 実行アーカイブ
+
+### 目的
+
+エージェント連携時にJSONL出力のsmart truncationで削られた情報やツール生出力を事後参照可能にする。
+`list-runs`/`show-run`サブコマンドおよびMCPの読み取り系ツール群は本アーカイブを単一の真実源とする。
+
+### ディレクトリ構造
+
+```text
+<cache_root>/runs/<run_id>/meta.json
+<cache_root>/runs/<run_id>/tools/<tool>/output.log
+<cache_root>/runs/<run_id>/tools/<tool>/diagnostics.jsonl
+<cache_root>/runs/<run_id>/tools/<tool>/tool.json
+```
+
+`meta.json`は実行単位のメタ情報。
+
+- `run_id`（ULID）・`version`・`python`・`executable`・`platform`・`cwd`
+- `argv`（起動時引数列）・`commands`（実行対象ツール列）・`files`（対象ファイル数）
+- `started_at` / `finished_at`（ISO 8601 UTC）・`exit_code`（finalize後）
+
+`tool.json`はツール単位のメタ情報（`tool`/`type`/`status`/`returncode`/`files`/`elapsed`/`diagnostics`/`has_error`/`commandline`）。
+`output.log`はツールの標準出力・標準エラーの結合した生文字列。
+`diagnostics.jsonl`は`ErrorLocation`を1件1行でJSONLシリアライズしたもの。
+
+### run_id
+
+ULID（26文字、Crockford Base32、タイムスタンプ由来で辞書順ソート可能）を採用する。
+`python-ulid`パッケージで生成し、JSONLの`header`レコードに`run_id`フィールドとして含める。
+
+UUID v4ではなくULIDを採用した理由は次の3点。
+
+- タイムスタンプ由来で辞書順ソート＝時系列順ソートとなる。`list_runs`の実装・デバッグが簡潔になる
+- 人が見たときに新旧の判別がしやすい
+- 十分な衝突耐性（48bit timestamp + 80bit random）
+
+### 自動クリーンアップ
+
+世代数・合計サイズ・保存期間の3軸で制御する。
+いずれかの閾値を超過した時点で古い順（run_id昇順）に削除する。
+
+| 設定キー | 既定値 | 0以下を指定した場合 |
+| --- | --- | --- |
+| `archive-max-runs` | 100 | 世代軸の自動削除を無効化 |
+| `archive-max-size-mb` | 1024 | サイズ軸の自動削除を無効化 |
+| `archive-max-age-days` | 30 | 期間軸の自動削除を無効化 |
+
+クリーンアップは各実行冒頭で`ArchiveStore.cleanup()`を同期実行する。
+将来的な非同期化の余地は残すが、v3初版では単純な同期実行で開始する。
+
+### 書き込み経路
+
+TUI経路・非TUI経路・JSONL stdout有無のいずれでもアーカイブ書き込みを発生させる。
+漏れを防ぐため、`execute_command`戻り値受信直後の独立フックとして提供する。
+
+実装の流れ。
+
+1. `run_pipeline`が`ArchiveStore`を生成し、`start_run`でrun_idを採番する
+2. `run_pipeline`が`_archive_hook`クロージャを組み立て、`cli.run_commands_with_cli`と`ui.run_commands_with_ui`の`archive_hook`引数へ注入する
+3. 各実行器はツール完了時（fixステージも含む）に`archive_hook(result)`を呼ぶ
+4. `run_pipeline`終端で`finalize_run`を呼び、`exit_code`/`finished_at`を書き込む
+
+JSONL stdoutストリーミングの`on_result`とは独立した経路にすることで、どちらか一方を切り替えても他方が失われない。
+
+### オプトアウト
+
+既定で有効。次のいずれかで無効化できる。
+
+- `--no-archive` CLIオプション
+- `archive = false` 設定
+
+無効化時は`ArchiveStore`を生成せず、`archive_hook`も`None`のまま。
+JSONLの`header`レコードから`run_id`フィールドも省略される。
+
+オプトイン化（既定無効）は却下した。
+エージェント連携時のUXを損なうため、既定有効＋自動削除で肥大化を抑える設計とした。
+
+### diagnosticシリアライズの方針
+
+アーカイブ用の`_error_to_dict`はLLM向け出力（`llm_output.py`）と独立した最小構造とする。
+`ErrorLocation`の全フィールドを保存することで、`rule_url`等のフィールドが追加された際の追従コストを抑える。
+
+## ファイルhashキャッシュ
+
+### キャッシュの目的
+
+同じ入力に対するツール再実行をスキップし、エージェント連携時の待ち時間と無駄な再計算を削減する。
+
+### 対象ツール
+
+ファイル間依存を持たず、設定ファイルもCWDでのみ解決するlinterに限定する。
+具体的には`textlint`のみ。
+
+対象判定は`CommandInfo.cacheable: bool`で明示する。
+新ツール追加時の判断ミスを防ぐため既定値は`False`とし、対象ツールのみ`True`を指定する。
+
+以下はいずれも対象外とする。
+
+- 書き込み型formatter（`ruff-format`/`prettier`/`shfmt`/`uv-sort`）— ヒット時にファイル書き換えがスキップされ、ファイル状態と結果が不整合になる
+- tester（`pytest`/`vitest`）— 対象ファイル以外のソース・設定・環境への依存があり、依存解析またはプロジェクト全体hashが必要で実装コストに見合わない
+- 依存型linter（`mypy`/`ruff-check`/`pylint`等）— import先や型情報のキャッシュが必要で、対象ファイル単独のhashでは整合性を保てない
+- 外部参照linter（`shellcheck`/`actionlint`）— `source`文やreusable workflowなど外部参照を含みうるため安全側で除外
+- 階層型設定を参照するlinter（`ec`/`markdownlint`/`typos`）— 階層型の設定解決は静的列挙では網羅できない
+
+### キャッシュキー
+
+誤ヒットを防ぐため、次の情報をすべてsha256で連結する。
+
+- ツール名
+- 実効コマンドライン全体（`--{command}-args`反映後のリスト）
+- ステージ区別（`fix_stage`フラグの真偽）
+- 構造化出力の設定値（`--human-readable`反映後、ツールが構造化出力を持つ場合）
+- 対象ファイル群のsha256（ファイル内容＋相対パス）
+- ツール固有設定ファイル群のsha256（存在しない場合は空文字扱い）
+- pyfltrのMAJORバージョン（メジャー更新で出力フォーマット変更時に旧キャッシュを無効化）
+
+ツール本体のバージョンはキャッシュキーに含めない。
+`pnpx`/`mise @latest`経由で実体が変わりうるが、短期破棄前提（既定12時間）で実害を許容する方針。
+
+### textlintのconfig_files
+
+公式に自動読み込みされる設定ファイル候補を完全列挙する。
+
+- `.textlintrc` / `.textlintrc.json` / `.textlintrc.yml` / `.textlintrc.yaml`
+- `.textlintrc.js` / `.textlintrc.cjs`
+- `package.json`（`textlint`フィールド）
+- `.textlintignore`
+
+### 外部ファイル参照引数の安全策
+
+`--{command}-args`に`--config`/`--ignore-path`を含む場合、当該実行ではキャッシュを無効化する（書き込みも読み出しもスキップ）。
+指定されたパスを動的に解釈する複雑さを避けるための安全側の実装。
+
+### 保存先とクリーンアップ
+
+`<cache_root>/cache/<tool>/<hash>.json`として保存する。
+クリーンアップは期間軸のみ（既定`cache-max-age-hours=12`）。
+サイズ・世代数の軸は採用しない（短期破棄前提でストレージ暴発リスクが小さいため）。
+
+### ヒット時の挙動
+
+- ツール実行をスキップして`CommandResult`を完全復元し、`cached=True`/`cached_from=<ソースrun_id>`を設定する
+- アーカイブ書き込みは行わない（同じ結果を重複記録しない方針。ソースrunを`cached_from`で参照誘導する）
+- JSONLの`tool`レコードに`cached`/`cached_from`を出力する
+- `retry_command`は出力しない（再実行不要）
+
+### キャッシュのオプトアウト
+
+既定で有効。次のいずれかで無効化できる。
+
+- `--no-cache` CLIオプション
+- `cache = false` 設定
+
+実行アーカイブと方針を揃え、エージェント連携時のUXを毀損しないようにする。

pyfltr-3.0.0/docs/development/index.md

@@ -0,0 +1,16 @@
+# 開発者向けガイド
+
+pyfltr本体の保守・貢献に必要な情報をまとめている。
+対象読者は本リポジトリへパッチを送る開発者や、ローカルでpyfltr自身の動作確認を行う利用者。
+
+## 開発手順
+
+- [開発手順](development.md) — 開発環境構築・サプライチェーン対策・ドキュメント運用・リリース手順
+
+## 内部設計
+
+- [アーキテクチャ概要](architecture.md) — 実行パイプライン・モジュール構成・主要設計判断
+- [実行アーカイブとファイルhashキャッシュ](archive-and-cache.md) — `<cache_root>/runs/`と`<cache_root>/cache/`の保存先・自動クリーンアップ・対象判定
+- [JSONL出力の設計](jsonl-output.md) — severity正規化・rule_url・retry_command・smart truncation・SARIF/GitHub Annotation
+- [詳細参照サブコマンドと再実行支援](subcommands.md) — `list-runs`/`show-run`の実装配置・`--only-failed`/`--from-run`の絞り込み戦略
+- [MCPサーバー](mcp-server.md) — `pyfltr mcp`サブコマンドとMCPツール5種・FastMCP採用・stdio隔離