ln-642-layer-ownership-boundary-auditor

路径： 文件路径（references/、../ln-*）相对于此技能目录。

分层与所有权边界审计器

类型： L3 Worker

用于审计架构分层边界并检测违规情况的 L3 Worker。

目的与范围

• 阅读 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 操作使用 scan_path，而不是 codebase_root。为所有发现的问题添加 domain 字段。

工作流

必须阅读： 加载 references/mcp_tool_preferences.md。

检测策略：采用两层检测（候选项扫描，然后进行上下文验证）；仅在验证方法不明确时加载 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 为真，或 .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 事务边界违规

内容： 在不一致的层中调用 commit()/rollback()（repo + service + API）

检测：

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	事务控制绕过了 service 层
repo + service commits	HIGH	UoW 所有者不明确（repo 还是 service）
service + api commits	MEDIUM	事务控制横跨 service + API

例外： Saga 模式 / 分布式事务包含明确的补偿操作 -> 将 CRITICAL 降为 MEDIUM。若使用 // architecture decision 或 ADR 记录了 UoW 边界 -> 跳过。

建议： 选择单一 UoW 所有者（建议使用 service 层），从其他层移除 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 AND local_in_repo	HIGH	Repo 创建自己的会话，而 API 注入了不同的会话
service 中的 local_session 调用了基于 DI 的 repo	MEDIUM	调用链中的会话不匹配

建议： 始终使用 DI，或始终使用本地会话。记录例外情况（例如，telemetry）

工作量： M

3.3 扁平编排违规

内容： service 层函数调用其他 service，而这些 service 又调用其他 service，形成深层编排链。

检测： 必须阅读： 加载 references/ai_ready_architecture.md —— 映射 service 导入，查找链深度。

违规规则：

条件	严重程度	问题
Service 链 >= 3（A->B->C->D）	HIGH	深层编排
Service 链 = 2（A->B->C）	MEDIUM	考虑扁平化

建议： 提取一个以同一层级调用所有 service 的编排器。每个 service 都成为终端节点。

工作量： 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；在独立模式下，worker 会按照共享契约生成自己的、与运行关联的产物路径。

# 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