weed

Weed

Allium ガーデンの草取りをします。.allium 仕様と実装コードを比較し、食い違いがある箇所を見つけて、その解消を支援します。

対話モード

このスキルは2つのモードで動作します。以下でユーザーに質問、確認、または回答を求める指示は、すべてモードに従います。

• 対話型 — 会話内で直接実行します。ユーザーに直接質問し、回答を待ちます。
• 非対話型 — weed サブエージェントとして実行される場合（Allium ループ内など）で、ユーザーに連絡できません。回答を推測してはいけません。各質問を出力内の未解決の指摘として報告し、仕様を更新する場合は open question 宣言として記録してから、その回答に依存しない作業を続けます。

起動

1. Allium の構文と検証ルールについて、言語リファレンスを読みます。
2. 関連する .allium ファイルを読みます（指定されていない場合は、プロジェクト内を検索して見つけます）。
3. allium CLI が利用可能な場合は、ファイルに対して allium check を実行し、構文が正しいことを確認します。
4. 対応する実装コードを読みます。

モード

呼び出し元のリクエストに応じて、次の3つのモードのいずれかで動作します。

確認。 仕様とコードの両方を読みます。場所を両方示して、すべての相違点を報告します。何も変更しません。

仕様の更新。 .allium ファイルを変更し、コードの実際の動作に合わせます。仕様は現在の動作を忠実に記述するものになります。

コードの更新。 実装を変更し、仕様の記述に合わせます。コードは仕様に忠実な実装になります。

モードが指定されていない場合は、既定で確認を行い、すべての指摘を報告します。

作業方法

仕様内の各エンティティ、ルール、トリガーについて、対応する実装を見つけます。重要なコードパスごとに、仕様がその動作を網羅しているか確認します。仕様がXと述べているのにコードがYを実行する場合と、コードがZを実行するのに仕様には記載がない場合の両方向の不一致を報告します。

プロセスレベルのチェック

構成要素ごとの比較に加えて、プロセスレベルの特性も確認します。

• コード内での遷移到達可能性。 仕様の遷移グラフで宣言されている各遷移について、実装にそれを発生させるコードパスがあるか確認します。宣言された遷移を発生させるコードパスがない場合は、指摘します。
• サーフェストリガーの網羅性。 外部刺激トリガーを持つ各ルールについて、実装に対応するエントリーポイント（API エンドポイント、Webhook ハンドラー、メッセージコンシューマー）があるか確認します。仕様で BackgroundCheckResultReceived がサーフェスによって提供されるとされている場合は、コードに対応するハンドラーがあるか確認します。
• コード内の未宣言遷移。 実装が仕様の遷移グラフに宣言されていない状態変更を発生させるか確認します。コードがエンティティを状態Aから状態Cに遷移させる一方で、グラフがA → B → Cのみを許可している場合は、指摘します。
• 不変条件の強制。 仕様内で式を伴う各不変条件について、実装がそれを強制しているか（データベース制約、アプリケーションレベルのチェック、テストのアサーション）確認します。強制する仕組みがない場合は、その欠落を指摘します。
• ボトムアップでのプロセス再構成。 ステータスフィールドを持つエンティティについて、コードから状態機械をたどり、存在する状態、コードが発生させる遷移、それをトリガーするアクターを特定します。再構成したプロセスを仕様の遷移グラフと比較します。再構成したプロセスをユーザーに提示し、確認を求めます。「コードから、Order のライフサイクルは次のようになっているとわかります。placed → paid → shipped → delivered で、placed または paid からキャンセルできます。仕様の遷移グラフと一致しますが、paid からのキャンセルが含まれていません。これは仕様の漏れですか、それともコードの不具合ですか？」

プロセスレベルの相違点は、構成要素レベルの相違点と併せて報告します。確認を始める前に、仕様の成熟度を把握するため仕様の評価を読みます。開発がその段階に達していない粗い仕様に対して、プロセスレベルの不足を指摘してはいけません。

相違の分類

不一致を見つけたら、その理由とともに分類を提案してください。呼び出し元が承認または上書きします。各相違を次のいずれかに分類します。

• 仕様のバグ。 仕様が誤っており、コードが正しい。仕様を修正します。
• コードのバグ。 コードが誤っており、仕様が正しい。コードを修正します。
• 理想設計。 仕様が意図する将来の動作を記述している。両方をそのままにしますが、ギャップを記録します。
• 意図的なギャップ。 相違が意図的である（例: 仕様が実装の詳細を抽象化している）。両方をそのままにします。

相違はレビューしやすいように、エンティティまたはルールごとにグループ化して提示してください。

コードがサービス境界をまたいで繰り返されるインターフェース契約を持つ場合（例: 複数の統合ポイントで同じシリアライゼーション要件）、仕様が再利用のために contract 宣言を使用しているか確認してください。コードのアサーションと不変条件（例: assert balance >= 0、クラスレベルのバリデーター）は、仕様の不変条件と一致している必要があります。仕様に対応する invariant Name { expression } がない場合は、そのギャップを指摘してください。

仕様更新のガイドライン

• 既存の -- allium: N バージョンマーカーを保持してください。バージョン番号は変更しないでください。
• 言語リファレンスで定義されているセクションの順序に従ってください。
• 実装ではなく動作を記述してください。ストレージ機構や API の詳細を暗示するフィールド名を書いていることに気づいたら、言い換えてください。
• 変数の値（しきい値、タイムアウト、制限）には config ブロックを使用してください。ルール内で数値をハードコードしないでください。
• 時間トリガーには、再発火を防ぐために常に requires ガードが必要です。
• 関係には with、射影には where を使用してください。取り違えないでください。
• フィールド間で比較されるインライン enum は、名前付き enum に抽出する必要があります。
• 新しいルールやエンティティを追加する場合は、ファイル構造に従って正しいセクションに配置してください。
• 他のサービスの config から導出される config 値（例: extended_timeout = base_timeout * 2）は、仕様内で修飾参照または式形式のデフォルトを使用してください。

コード更新のガイドライン

• プロジェクトの既存のスタイル、構造、命名の慣習に従ってください。
• 変更後にテストを実行してください。テストが失敗した場合は、テストを黙って調整するのではなく、失敗を報告してください。
• 直接のファイルを超えて影響を及ぼす変更（例: API 契約の変更、データベースマイグレーション、下流のコンシューマー）を指摘してください。
• 最小限で的を絞った変更を優先してください。相違の修正に直接必要でない限り、周囲のコードをリファクタリングしないでください。
• コード変更にマイグレーションまたはデプロイの手順が必要な場合は、これを明示的に記録してください。

境界

• 新しい仕様をゼロから構築することはしません。それは elicit スキルの役割です。
• コードから仕様を抽出することはしません。それは distill スキルの役割です。
• skills/allium/references/language-reference.md を変更することはしません。言語定義は別途管理されています。
• アーキテクチャ上の決定を行うことはしません。より広範な影響を指摘し、呼び出し元に判断を委ねます。

コンテキスト管理

仕様の整合性チェックでは、多数の編集・検証サイクルが必要になることがあります。対話形式で実行している場合、長い反復セッションになると予想される場合、またはコンテキストが大きくなりつつある場合は、仕様の選別専用に新しいチャットを開くようユーザーに助言してください。再開できるように、コピー＆ペースト用のプロンプトを提供してください。例: 「weed スキルを使用して、[Spec Name] 仕様と [Implementation Files] の間の相違の解決を続けてください。」

検証

.allium ファイルを編集するたびに、CLI がインストールされている場合は、変更したファイルに対して allium check を実行してください。報告された問題は、結果を提示する前に修正してください。CLI が利用できない場合は、言語リファレンスに照らして確認してください。CLI が見つからなかった最初の時点で、次のように記してください。「代わりに言語リファレンスに照らして検証します。自動チェックを利用する場合、CLI は Homebrew または crates.io から入手できます。詳しくは README をご覧ください。」

allium analyse が利用できる場合は、差異チェックの完了後に実行してください。構成要素ごとの比較では見落とすプロセスレベルの不足を特定するために、検出結果を活用してください。missing_producer の検出結果は、仕様上の不足（コードでは処理されているが、仕様ではモデル化されていない）またはコード上の不足（データパスを実装したものがいない）のいずれかを示している可能性があります。コードが対応しているかどうかを確認し、各検出結果を分類してください。検出結果をドメインに関する質問へ置き換える方法については、検出結果への対応を参照してください。

出力形式

差異を報告する際（check モード）は、各検出結果を次の形式で記述してください。

### [Entity/Rule name]
Spec: [what the spec says] (file:line)
Code: [what the code does] (file:line)
Classification: [proposed classification with reasoning]

関連する差異をまとめてください。影響が最も大きい検出結果から記述してください。

型付き結果（ループへの引き渡し）

Allium ループ内で weed サブエージェントとして実行する場合、weed-result.schema.jsonに準拠した単一の JSON オブジェクトだけを結果として返してください。それ以外は返さないでください。ループは構造化フィールド（verdict、各差異の classification、open_questions）に基づいて振り分けるため、説明文の解析に依存せず、振り分けと収束チェックが確定的に行われます。summary フィールドには、人が読める1行の要約だけを記載し、詳細は構造化フィールドに記載してください。空のリストには [] を使用し、すべてのフィールドを出力してください。対話形式で実行する場合は、これまでどおり上記の説明文形式で提示してください。型付きレコードは機械への引き渡し用であり、会話用ではありません。

{
  "phase": "weed",
  "mode": "check",
  "verdict": "dirty",
  "divergences": [
    { "subject": "Order.cancel", "classification": "code-bug", "spec": "cancel allowed from paid (shop.allium:42)", "code": "guarded to pending only (order.py:88)" }
  ],
  "open_questions": [],
  "artefacts": [],
  "summary": "1 divergence: Order.cancel (code-bug)"
}