ドキュメント進化追跡ツール は何をしますか？
バージョンをまたいでドキュメントがどのように進化したかを追跡する、自己完結型のスキルです。バージョンファミリー（v1.md, v2.md, ... またはタイムスタンプ付きファイルのディレクトリ）を指定すると、連続するバージョン間の段落レベルの差分を計算し、コンセプトの系譜（導入 / 保持 / 変更 / 削除）を追跡します。
必須ワークフロー
依存関係のブートストラップ（初回実行時）
初回実行前に、このスキルのランタイム依存関係を確認します。
- コア: 純粋な標準ライブラリ — インストール不要。
- オプション:
PyYAML（設定ファイルが.yamlの場合のみ必要。JSON設定は標準ライブラリのみで動作します）。
PyYAML が不足しており、設定がYAML形式の場合は、ユーザーにその旨を伝え、pip install pyyaml を実行してよいか確認してください。ユーザーの明示的な同意なしにグローバル環境にインストールしないでください。
- 設定ファイル（
config/examples/family.jsonを参照。YAML設定もPyYAMLがインストールされていればサポートされます）を読み込みます。 versions_dirに少なくとも2つのバージョンファイルが存在することを確認します。python -m src.cli run --config <path> [--concepts "A,B"]を実行します。- トランジション数を報告し、
./evolution/evolution_<tracking_id>.{md,json}をユーザーに示します。
使用すべき状況
- 一連のドキュメントバージョン（タイムスタンプ付きまたは連番）を経時的に比較する必要がある場合。
- ユーザーが「変更点を追跡」「バージョン履歴」「草稿間の差分」「コンセプトの系譜」を求めている場合。
- 名前付きコンセプト（用語、見出し、定義）を草稿間で追跡し、いつ導入・変更・削除されたかを確認する必要がある場合。
- 草稿の進化を単一の最終差分ではなく、タイムラインとして報告する必要がある場合。
使用例
# 設定を検証し、見つかったバージョンファイルを確認する
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json
# トラッカーを実行する。追跡するコンセプトをオプションで指定可能
python -m src.cli run --config config/examples/family.json --concepts "entropy,partition function"
レポートは ./evolution/evolution_<tracking_id>.{md,json} に出力されます。Markdownタイムラインは人間が読むためのもの、JSONはプログラムで利用するためのものです。
エラー処理
- 設定が無効（
validateで0以外の終了コード）— 報告されたフィールドを修正し再検証してください。命名規則とversions_dirが通常の問題箇所です。 - 2バージョン未満しか見つからない — 実行が中断されます。
version_namingルールを実際のファイル名と照合して確認し、再試行してください。 - コンセプトが完全に出現しない — すべてのバージョンで不在として報告されます。これは有効な結果であり、エラーではありません。
- 予期しない終了コード — メッセージをそのまま報告してください。手動でファイルをdiffしようとしないでください。
差分の粒度
| 粒度 | 分割ルール |
|---|---|
line | 空でない行 |
paragraph (デフォルト) | 空行で区切られたブロック |
sentence | 句読点で区切られた文 |
制限事項
- diffは構造的（
difflibによるブロックのアライメント）であり、意味的ではありません。コンセプトは、その正確なフレーズ（大文字小文字を区別しない）がバージョンのテキスト内に出現した場合にのみ「存在する」と見なされます。 sequential/timestamp以外のカスタム命名規則はサポートされていません。