ln-642-layer-ownership-boundary-auditor

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

レイヤーと所有権の境界監査ツール

タイプ： L3 ワーカー

アーキテクチャのレイヤー境界を監査し、違反を検出する L3 ワーカーです。

目的と範囲

• architecture.md を読み込み、プロジェクトのレイヤー構造を確認します
• レイヤー違反を検出します（インフラストラクチャレイヤー以外にある I/O コード）
• レイヤー間の整合性に関する問題を検出します：
  • トランザクション境界（コミット／ロールバックの所有権）
  • セッションの所有権（DI とローカル）
• パターンの適用範囲を確認します（すべての HTTP 呼び出しがクライアント抽象化を使用していること）
• エラーハンドリングの重複を検出します
• 違反リストを返します

対象外：

• 非同期関数内のブロッキング I/O（async def 内の同期的な open／read）
• ファイア・アンド・フォーゲットのタスク（エラーハンドラーのない create_task）

入力

- architecture_path: string    # Path to docs/architecture.md
- codebase_root: string        # Root directory to scan
- skip_violations: string[]    # Files to skip (legacy)
- output_dir: string           # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"

# Domain-aware (optional)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

domain_mode="domain-aware" の場合： すべての Grep／Glob 操作では codebase_root の代わりに scan_path を使用します。すべての検出結果に domain フィールドを付与します。

ワークフロー

必須の読み込み： references/mcp_tool_preferences.md を読み込みます。

検出ポリシー：2 層検出（候補のスキャン、続いてコンテキストの検証）を使用します。検証方法が曖昧な場合にのみ references/two_layer_detection.md を読み込みます。 ツールポリシー：ホストの AGENTS.md が対象範囲外の独立したサブエージェントとして実行される場合があるため、ファイルの読み取り、検索、編集では、まず hex-line MCP を使用します。MCP の動作が不明確な場合にのみ references/mcp_integration_patterns.md を読み込みます。

参照情報、呼び出しパス、またはアーキテクチャの結合度が監査に大きく役立つ場合は、まず hex-graph を使用します。利用できる場合、ローカルのコードや設定の読み取りにはまず hex-line を使用します。MCP を利用できない場合、未対応の場合、またはインデックスが作成されていない場合は、組み込みの Read/Grep/Glob/Bash を引き続き使用し、レポートにフォールバックしたことを記載します。

フェーズ 1：アーキテクチャの把握

必須の読み込み： references/layer_rules.md を読み込みます。アーキテクチャプリセット（フォールバック）、I/O パターンの境界ルール（フェーズ 2）、適用範囲のチェック（フェーズ 4）、レイヤー間整合性ルール（フェーズ 3）を使用します。

Read docs/architecture.md

Extract from Section 4.2 (Top-Level Decomposition):
  - architecture_type: "Layered" | "Hexagonal" | "Clean" | "MVC" | etc.
  - layers: [{name, directories[], purpose}]

Extract from Section 5.3 (Infrastructure Layer Components):
  - infrastructure_components: [{name, responsibility}]

IF architecture.md not found:
  Use fallback presets from layer_rules.md

Build ruleset:
  FOR EACH layer:
    allowed_deps = layers that can be imported
    forbidden_deps = layers that cannot be imported

グラフによる高速化（利用できる場合）： contextStore.graph_indexed が true、または .hex-skills/codegraph/index.db が存在する場合：

• モジュールの結合度： analyze_architecture(path=scan_root, verbosity="full") を実行し、返された結合度の指標を使って、密結合しているレイヤーを特定します。
• レイヤー間呼び出し： トランザクション／セッション関連の関数に対して find_references(symbol) を実行し、レイヤーをまたいでコミット／ロールバックの所有権を追跡します。
• オーケストレーションの深さ： trace_paths(name="ServiceFn", file="...", path_kind="calls", direction="forward", depth=3, path=scan_root) を実行し、具体的なサービスシンボルから呼び出しチェーンの深さを測定して、フラットなオーケストレーションのチェックに使用します。
• 粗いセレクターまたはモジュールレベルのセレクターによる trace_paths の結果が空でも、そのレイヤーに問題がないとは判断できません。セレクターの範囲が広い場合は、inspect_symbol または grep／手動レビューに切り替えます。
• グラフが利用できない場合は、以下の grep ベースの検出に切り替えます。

フェーズ 2：レイヤー違反の検出

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

FOR EACH violation_type IN layer_rules.md I/O Pattern Boundary Rules:
  grep_pattern = violation_type.detection_grep
  forbidden_dirs = violation_type.forbidden_in

  matches = Grep(grep_pattern, scan_root, include="*.py,*.ts,*.js")

  FOR EACH match IN matches:
    IF match.path NOT IN skip_violations:
      IF any(forbidden IN match.path FOR forbidden IN forbidden_dirs):
        violations.append({
          type: "layer_violation",
          severity: "HIGH",
          pattern: violation_type.name,
          file: match.path,
          line: match.line,
          code: match.context,
          allowed_in: violation_type.allowed_in,
          suggestion: f"Move to {violation_type.allowed_in}"
        })

フェーズ 3：レイヤー間の整合性チェック

3.1 トランザクション境界の違反

内容： 異なるレイヤー（リポジトリ＋サービス＋API）で、一貫性なく commit()/rollback() が呼び出されています。

検出：

repo_commits = Grep("\.commit\(\)|\.rollback\(\)", "**/repositories/**/*.py")
service_commits = Grep("\.commit\(\)|\.rollback\(\)", "**/services/**/*.py")
api_commits = Grep("\.commit\(\)|\.rollback\(\)", "**/api/**/*.py")

layers_with_commits = count([repo_commits, service_commits, api_commits].filter(len > 0))

安全なパターン（無視）：

• 同じコンテキスト内にコメント「# best-effort telemetry」がある
• ファイル名が _callbacks.py で終わる（進捗通知）
• 明示的な # UoW boundary コメントがある

違反ルール：

条件	重大度	問題
layers_with_commits >= 3	CRITICAL	すべてのレイヤーでUoWの所有権が混在
repo + api commits	HIGH	トランザクション制御がサービスレイヤーを迂回
repo + service commits	HIGH	UoWの所有者が不明確（リポジトリかサービスか）
service + api commits	MEDIUM	トランザクション制御がサービスとAPIにまたがる

例外： Sagaパターン／分散トランザクションで、明示的な補償アクションがある場合は、CRITICALをMEDIUMに引き下げます。// architecture decision またはADRでUoW境界が文書化されている場合は、スキップします。

推奨事項： UoWの所有者を1つに決め（サービスレイヤーを推奨）、他のレイヤーから commit() を削除します。

工数： L（アーキテクチャ上の決定とリファクタリングが必要）

3.2 セッション所有権の違反

内容： 同じ呼び出しチェーン内で、DIにより注入されたセッションとローカルで作成されたセッションが混在しています。

検出：

di_session = Grep("Depends\(get_session\)|Depends\(get_db\)", "**/api/**/*.py")
local_session = Grep("AsyncSessionLocal\(\)|async_sessionmaker", "**/services/**/*.py")
local_in_repo = Grep("AsyncSessionLocal\(\)", "**/repositories/**/*.py")

違反ルール：

条件	重大度	問題
同じモジュール内に di_session と local_in_repo がある	HIGH	APIが別のセッションを注入している一方で、リポジトリが独自のセッションを作成
DIベースのリポジトリを呼び出すサービスに local_session がある	MEDIUM	呼び出しチェーン内でセッションが一致しない

推奨事項： DIを一貫して使用するか、ローカルセッションを一貫して使用します。例外（テレメトリーなど）は文書化します。

工数： M

3.3 フラットなオーケストレーションの違反

内容： サービスレイヤーの関数が別のサービスを呼び出し、そのサービスがさらに別のサービスを呼び出すなど、深いオーケストレーションチェーンが形成されています。

検出： 必須読み込み： references/ai_ready_architecture.md を読み込みます。サービスのインポートをマッピングし、チェーンの深さを確認します。

違反ルール：

条件	重大度	問題
サービスチェーン >= 3（A->B->C->D）	HIGH	深いオーケストレーション
サービスチェーン = 2（A->B->C）	MEDIUM	フラット化を検討

推奨事項： すべてのサービスを同じ階層で呼び出すオーケストレーターを抽出します。各サービスはシンクになります。

工数： L

---

フェーズ 4：パターンの網羅性を確認

# HTTP Client Coverage
all_http_calls = Grep("httpx\\.|aiohttp\\.|requests\\.", codebase_root)
abstracted_calls = Grep("client\\.(get|post|put|delete)", infrastructure_dirs)

IF len(all_http_calls) > 0:
  coverage = len(abstracted_calls) / len(all_http_calls) * 100
  IF coverage < 90%:
    violations.append({
      type: "low_coverage",
      severity: "MEDIUM",
      pattern: "HTTP Client Abstraction",
      coverage: coverage,
      uncovered_files: files with direct calls outside infrastructure
    })

# Error Handling Duplication
http_error_handlers = Grep("except\\s+(httpx\\.|aiohttp\\.|requests\\.)", codebase_root)
unique_files = set(f.path for f in http_error_handlers)

IF len(unique_files) > 2:
  violations.append({
    type: "duplication",
    severity: "MEDIUM",
    pattern: "HTTP Error Handling",
    files: list(unique_files),
    suggestion: "Centralize in infrastructure layer"
  })

フェーズ 5：スコアを算出

必須読み込み： references/audit_worker_core_contract.md と references/audit_scoring.md を読み込みます。

フェーズ 6：レポートを作成

必須読み込み： references/templates/audit_worker_report_template.md を読み込みます。

references/audit_summary_contract.md に従ってJSONサマリーを書き込みます。管理モードでは、呼び出し元から runId と summaryArtifactPath の両方が渡されます。スタンドアロンモードでは、共有コントラクトに従ってワーカーが独自の実行スコープのアーティファクトパスを生成します。

# Build markdown report in memory with:
# - AUDIT-META (standard penalty-based: score, counts)
# - Checks table (io_isolation, http_abstraction, error_centralization, transaction_boundary, session_ownership)
# - Findings table (violations sorted by severity)
# - DATA-EXTENDED: {architecture, coverage}

IF domain_mode == "domain-aware":
  Write to {output_dir}/642-layer-boundary-{current_domain}.md
ELSE:
  Write to {output_dir}/642-layer-boundary.md

フェーズ 7：サマリーを返す

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/642-layer-boundary-users.md
Score: 4.5/10 | Issues: 8 (C:1 H:3 M:4 L:0)

重要なルール

読み込み済みの references/audit_worker_core_contract.md を適用します。

• 最初に architecture.md を読む - アーキテクチャの種類を決めつけないでください
• 違反リストをスキップする - 段階的な修正対象としてマークされたレガシーファイルを尊重してください
• ファイル＋行＋コード - コンテキストとともに正確な場所を必ず示してください
• 実行可能な提案 - コードの移動先を必ず示してください
• 誤検知を避ける - 部分文字列だけでなく、パスに禁止ディレクトリが含まれていることを確認してください
• 独自の観点： レイヤー、所有権、オーケストレーションの境界のみを監査します。パッケージの健全性、一般的なコード品質、依存関係グラフのトポロジー、実行時の並行処理上の危険性は監査しないでください。
• 必要なアクション： すべての指摘に MOVE_BOUNDARY、CHOOSE_OWNER、FLATTEN_ORCHESTRATION のいずれかを使用してください。

完了の定義

読み込み済みの references/audit_worker_core_contract.md を適用します。

• docs/architecture.md からアーキテクチャを確認済み（またはフォールバックを使用済み）
• layer_rules.md のすべての違反タイプを確認済み
• レイヤー間の整合性を確認済み：
  • トランザクション境界を分析済み（コミット／ロールバックの分布）
  • セッションの所有権を分析済み（DI 対ローカル）
• HTTP 抽象化と 2 つの整合性指標についてカバレッジを算出済み
• 重大度、場所、提案を含む違反一覧を作成済み
• ドメインを考慮する場合：すべての Grep の対象を scan_path に限定し、検出結果にドメインを付記済み
• レポートを {output_dir}/642-layer-boundary[-{domain}].md に書き込み済み（単一の Write 呼び出しによるアトミックな書き込み）
• コントラクトに従って概要を作成済み

参照ファイル

• レイヤールール：references/layer_rules.md
• スコアリングへの影響：references/audit_scoring.md を使用します

---

バージョン： 2.1.0 最終更新日： 2026-02-08