fix-llm-artifacts

LLM アーティファクトを修正する

以前の review-llm-artifacts の実行で検出された項目に、自動的な安全／リスク分類を適用して修正します。.beagle/llm-artifacts-verification.json が存在する場合は、false_positive とマークされた検出項目をスキップし、inconclusive はリスクのある修正として扱います（修正を促すか、ユーザーの指示に従ってスキップします）。

使用方法

必要に応じて次のフラグを指定し、fix-llm-artifacts スキルを呼び出します。

fix-llm-artifacts [--dry-run] [--all] [--category <name>]

フラグ：

• --dry-run - ファイルを変更せず、修正内容を表示します
• --all - コードベース全体を修正します（レビュー JSON がない場合は、先に review-llm-artifacts --all を実行します）
• --category <name> - 特定のカテゴリのみ修正します：tests|dead-code|abstraction|style

手順

必須ゲート

順序が重要です。各合格条件を満たすまで修正を適用しないでください（これらの手順は「内部検証」ではありません）。

1. 作業ツリー — git status --porcelain の結果が空であるか、メッセージ beagle-core: pre-fix-llm-artifacts backup で stash が作成され、git stash list に表示されている必要があります。ユーザーが stash／バックアップを拒否した場合は、中止するか、編集前にレポートへリスクを明示的に受け入れたことを記録してください。
2. ディスク上のレビュー成果物 — .beagle/llm-artifacts-review.json が存在するか、--all によって review-llm-artifacts が実行され、そのファイルが書き出されている必要があります。それ以外の場合は中止してください（記憶や推測に基づいて修正しないでください）。 2a. エコー＋ID ロック（誤った情報の捏造防止） — レビューを読み込んだ後（セクション 3）、解析済み JSON の検出項目テーブル（id | category | file:line | description）をエコーし、ID の正確な集合をロック済み ID 集合として記録します。この集合に含まれる検出項目のみを修正してください。ブランチ名、ディレクトリ、記憶から推測した検出項目は決して修正しないでください。適用またはスキップする修正はすべて、ロック済み ID 1 件に対して 1 件ずつ対応させます。review-verification-protocol スキル → 誤った情報の捏造防止（ゲート 0）を参照してください。 2b. 修正ごとの存在確認 — いずれかの検出項目を編集する前に、（i）その id がロック済み集合に含まれていること、（ii）記載された file が存在し、引用されたコードが実際に file:line にあることを確認してください（その場で読み込んでください）。ファイルまたはコードが存在しない場合は、編集しないでください — 検出項目が古いか、捏造されたものです。理由を付けてスキップし、次に進んでください。検出項目に合わせてファイルを作成または書き換えることは決してしないでください。
3. 古いレビュー — jq -r '.git_head' .beagle/llm-artifacts-review.json が git rev-parse HEAD と異なる場合は、レビューを再実行するかユーザーに確認してください。y → レビューを再実行してから続行します。n → 修正の作業を中止します（古い検出項目に対して修正を適用しないでください）。
4. 検証オーバーレイ — .beagle/llm-artifacts-verification.json が存在する場合は、解析できる必要があります。分類する前に除外対象と判定保留の集合を作成してください（セクション 4）。解析に失敗した場合は、停止してエラーを報告してください。
5. リスクのある修正 — セクション 6 の対話形式の選択（または残りのリスク項目をすべてスキップする s）なしに、code_removal、logic_change、mock_boundary、abstraction_change、test_refactor の作業を行わないでください。

編集後： セクション 7～8 は、呼び出したツールが正常終了した場合にのみ合格となります（ゼロ以外の終了コードは失敗です。クリーンアップの際も JSON 成果物を保持してください）。

1. 引数を解析する

$ARGUMENTS からフラグを抽出します：

• --dry-run - プレビューのみ
• --all - コードベース全体をスキャン
• --category <name> - 指定したカテゴリに絞り込む

2. 事前安全チェック

# Check for uncommitted changes
git status --porcelain

作業ディレクトリに変更がある場合は、警告します：

Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.

変更がある場合は stash を作成します：

git stash push -m "beagle-core: pre-fix-llm-artifacts backup"

3. レビュー結果を読み込む

既存のレビュー ファイルを確認します：

cat .beagle/llm-artifacts-review.json 2>/dev/null

ファイルがない場合：

• --all フラグが指定されている場合：まず review-llm-artifacts --all を実行して、プロジェクト全体のレビューを生成します
• それ以外の場合：次のメッセージを表示して失敗します："レビュー結果が見つかりません。まず review-llm-artifacts スキルを実行してください。"

ID の出力とロック（ゲート 2a）： ファイルが存在することを確認したら、解析した JSON のすべての指摘事項を出力し、振り分ける前に ID の集合をロックします：

python3 - <<'PY'
import json
r = json.load(open('.beagle/llm-artifacts-review.json'))
f = r['findings']
if not isinstance(f, list) or not f:
    raise SystemExit("No findings to lock; aborting.")
ids = [x.get('id') for x in f]
if any(not isinstance(i, int) for i in ids):
    raise SystemExit("All finding ids must be integers; aborting.")
if len(set(ids)) != len(ids):
    raise SystemExit("Duplicate finding ids detected; aborting.")
print("| id | category | file:line | description |")
print("|----|----------|-----------|-------------|")
for x in f:
    desc = (x.get('description') or '').replace('|', '\\|')[:80]
    print(f"| {x['id']} | {x.get('category')} | {x.get('file')}:{x.get('line')} | {desc} |")
print("Locked ids: {" + ", ".join(str(i) for i in sorted(set(ids))) + "}")
PY

上記の ID のみを判定し、修正してください。修正対象についての判断がこの表と異なる場合は、表に従ってください。

任意の検証オーバーレイ — .beagle/llm-artifacts-verification.json が存在する場合：

• status: false_positive の指摘事項 ID の集合を作成し、すべての修正リストから除外します。
• status: inconclusive の指摘事項 ID は、レビューで fix_safety が Safe となっていても、必ずリスクのある修正として扱います（セクション 6）。
• status: confirmed_issue の指摘事項 ID は、通常どおりレビュー JSON の fix_safety / risk を使用します。

検証ファイルがない場合、削除または dead-code の修正を適用する際に、次の警告を表示します："誤検知を減らすには、まず verify-llm-artifacts スキルを実行してください。"

ファイルが存在する場合、鮮度を検証します：

# Get stored git HEAD, scope, and target from JSON
stored_head=$(jq -r '.git_head'   .beagle/llm-artifacts-review.json)
stored_scope=$(jq -r '.scope // "all"'  .beagle/llm-artifacts-review.json)
stored_target=$(jq -r '.target // "."'  .beagle/llm-artifacts-review.json)
current_head=$(git rev-parse HEAD)

if [ "$stored_head" != "$current_head" ]; then
  echo "Warning: Review was run at commit $stored_head, but HEAD is now $current_head"
fi

古い場合は、次のように確認します："レビュー結果が古くなっています。再実行しますか？ (y/n)"。

• y → 古い JSON から読み取った元のスコープと対象で review-llm-artifacts を再実行し、その後再読み込みします。これによりユーザーの当初の意図が維持されます。ユーザーの差分と無関係な修正を適用したり、ユーザーが対象としていたファイルを見落としたりする可能性があるため、スコープを黙って広げたり狭めたりしないでください。具体的には：
  • scope == "changed" → review-llm-artifacts "$stored_target" を呼び出します（デフォルトのスコープはすでに変更ファイルです）。
  • scope == "all" → review-llm-artifacts --all "$stored_target" を呼び出します。
  • JSON に scope または target がない場合（スキーマ導入前のレビュー）は、中止しないでください。scope = "all"、target = "." として、次の警告を表示します：

    "レビュー JSON は scope/target スキーマ導入前のものです。プロジェクト全体のスキャン（--all）として再実行します。より限定したスコープ（デフォルトの変更ファイルの差分、またはサブディレクトリ）を意図していた場合は、ここでキャンセルし、review-llm-artifacts スキルを明示的に再実行してください。" ユーザーがキャンセルしない場合にのみ続行します。

• n → 中止します（修正は適用しません。古い指摘事項は信頼できません）。

4. 安全性に基づいて指摘事項を分類する

JSON の指摘事項を解析し、（ステップ 3 の検証オーバーレイを適用した後に）fix_safety フィールドで分類します：

安全な修正（自動適用）：

• unused_import - 未使用のインポート
• todo_comment - 古くなった TODO/FIXME コメント
• dead_code_obvious - 明らかに到達不能なコード
• verbose_comment - 冗長すぎる LLM 風のコメント
• redundant_type - 冗長な型注釈

リスクのある修正（確認が必要）：

• test_refactor - テスト構造の変更
• abstraction_change - クラス／関数の抽出
• code_removal - 機能するコードの削除
• mock_boundary - テストモックの範囲の変更
• logic_change - 動作に関わるあらゆる変更

5. 安全な修正を適用する

--dry-run の場合：

## Safe Fixes (would apply automatically)

| File | Line | Type | Description |
|------|------|------|-------------|
| src/api.py | 15 | unused_import | Remove `from typing import List` |
| src/models.py | 42 | verbose_comment | Remove 23-line docstring |
...

それ以外の場合は、カテゴリごとに安全な修正を適用します。エージェントがサブエージェントをサポートしている場合は、カテゴリごとに 1 つずつ並列にディスパッチします。サポートしていない場合は、以下の各指摘事項に適用される契約に従って、カテゴリを順番に処理し、修正ごとのレポートを同様に作成します。

Apply safe fixes for category "{category}"
Files: [list of files with findings in this category]
Instructions: For EACH finding, first confirm it is in the locked id set and that the
cited code exists at file:line (read it). If the file or code is absent, skip the finding
with a reason — do NOT create or rewrite a file to match the finding. Then apply each
confirmed fix, preserving surrounding code. Report success/failure/skip per fix by id.

カテゴリ（サブエージェントをサポートしている場合は並列化し、それ以外の場合は順次処理）：

• style - コメント、フォーマット
• dead-code - インポート、到達不能なコード
• tests - テスト関連の安全な修正
• abstraction - 安全なリファクタリング

6. リスクのある修正を処理する

リスクのある修正ごとに、対話形式で確認します：

[src/services/auth.py:156] Remove seemingly unused authenticate_legacy() method?
This method has no callers in the codebase but may be used externally.
(y)es / (n)o / (s)kip all risky:

ユーザーの選択を記録します：

• y - この修正を適用する
• n - この修正をスキップする
• s - 残りのリスクのある修正をすべてスキップする

7. 修正後の検証

プロジェクトの種類を検出し、適切なリンターを実行します：

Python：

# Check if ruff config exists
if [ -f "pyproject.toml" ] || [ -f "ruff.toml" ]; then
    ruff check --fix .
    ruff format .
fi

# Check if mypy config exists
if [ -f "pyproject.toml" ] || [ -f "mypy.ini" ]; then
    mypy .
fi

TypeScript/JavaScript：

# Check for eslint
if [ -f "eslint.config.js" ] || [ -f ".eslintrc.json" ]; then
    npx eslint --fix .
fi

# Check for TypeScript
if [ -f "tsconfig.json" ]; then
    npx tsc --noEmit
fi

Go：

if [ -f "go.mod" ]; then
    go vet ./...
    go build ./...
fi

8. テストを実行する

# Python
if [ -f "pyproject.toml" ] || [ -f "pytest.ini" ]; then
    pytest
fi

# JavaScript/TypeScript
if [ -f "package.json" ]; then
    npm test 2>/dev/null || yarn test 2>/dev/null || true
fi

# Go
if [ -f "go.mod" ]; then
    go test ./...
fi

9. 結果を報告する

## Fix Summary

### Applied Fixes
- [x] src/api.py:15 - Removed unused import `List`
- [x] src/models.py:42-64 - Removed verbose docstring
- [x] src/auth.py:156-189 - Removed dead method (user confirmed)

### Skipped Fixes
- [ ] src/services/cache.py:23 - User declined risky fix
- [ ] tests/test_api.py:45 - Test refactor skipped

### Verification Results
- Linter: PASSED
- Type check: PASSED
- Tests: PASSED (42 passed, 0 failed)

### Diff Summary
```bash
git diff --stat

クリーンアップ

すべての検証に成功した場合：

rm -f .beagle/llm-artifacts-review.json .beagle/llm-artifacts-verification.json

いずれかの検証に失敗した場合は、ファイルを保持して報告します：

Review file preserved at .beagle/llm-artifacts-review.json
Fix issues and re-run, or restore with: git stash pop

例

# Preview all fixes without applying
fix-llm-artifacts --dry-run

# Fix only dead code issues
fix-llm-artifacts --category dead-code

# Full codebase scan and fix
fix-llm-artifacts --all

# Fix style issues only, preview first
fix-llm-artifacts --category style --dry-run