integration-checker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integration Checker Skill

Core Principle

核心原则

Existence does not equal integration. A component existing is implementation-level verification; a component being connected is integration-level verification. Both are necessary. Neither is sufficient alone.

This skill catches the most common class of real-world bugs in AI-generated code: components that are individually correct but not connected to each other. A function can exist, contain real logic, pass correctness verification, and never be imported or called. An API endpoint can be defined but never wired into the router. An event handler can be registered but never receive events.

存在不等于集成。组件存在属于实现层面的验证，而组件已正确连接则属于集成层面的验证。两者缺一不可，单独一项都不足以确保功能正常。

本技能能够捕捉AI生成代码中最常见的一类真实bug：各个组件本身逻辑正确，但彼此之间未建立连接。例如，某个函数存在且包含有效逻辑、通过了正确性验证，但从未被导入或调用；某个API端点已定义，但未接入路由；某个事件处理器已注册，但从未接收过事件。

Purpose

用途

Verify cross-component wiring using four verification techniques. Phase 3.5 of the feature lifecycle (design -> plan -> implement -> integration check -> validate -> release).

When used standalone (not in the feature pipeline), operates on the current working directory or a specified path.

通过四种验证技术检查跨组件连接情况。处于功能生命周期的第3.5阶段（设计→规划→实现→集成检查→验证→发布）。

当独立使用（不纳入功能流水线）时，会针对当前工作目录或指定路径进行操作。

Operator Context

操作上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
Read-Only Analysis: This skill reads and reports. It does NOT fix wiring issues. Fixes route back to feature-implement or the user.
Language Detection First: Detect project language(s) before applying verification techniques. Different languages have different import/export patterns.
Three-State Classification: Every export gets exactly one status: WIRED, IMPORTED_NOT_USED, or ORPHANED. No ambiguous states.
Structural Not Semantic: Contract checking verifies shape and naming compatibility, not whether data is logically correct. WHY: semantic correctness requires runtime information we don't have.

CLAUDE.md合规性：执行前先读取并遵循仓库中的CLAUDE.md规则
只读分析：本技能仅读取代码并生成报告，不会修复连接问题。修复操作需跳转至feature-implement阶段或由用户手动完成。
优先检测语言：应用验证技术前先检测项目语言。不同语言的导入/导出模式存在差异。
三态分类：每个导出内容只会被标记为以下三种状态之一：WIRED（已连接）、IMPORTED_NOT_USED（已导入但未使用）、ORPHANED（孤立状态），无模糊状态。
结构而非语义：契约检查仅验证格式和命名兼容性，不判断数据在逻辑上是否正确。原因：语义正确性需要运行时信息，而本技能无法获取此类信息。

Default Behaviors (ON unless disabled)

默认行为（默认开启،可关闭）

Concise Reporting: Report facts. Show the wiring map, not prose about the wiring map.
Feature Pipeline Integration: When invoked within the feature pipeline, read implementation artifact from
```
.feature/state/implement/
```
for context on what was built.
Exclusion Patterns: Skip
```
node_modules/
```
,
```
vendor/
```
,
```
.git/
```
,
```
__pycache__/
```
,
```
dist/
```
,
```
build/
```
, test fixtures, and generated files. WHY: these contain intentionally unused exports (library code, vendored deps) that would flood the report with false positives.
Severity Ordering: Report ORPHANED (failure) before IMPORTED_NOT_USED (warning) before WIRED (pass). Users need to see failures first.

简洁报告：仅报告事实，展示连接关系图，而非冗长的文字描述。
功能流水线集成：当在功能流水线中调用时，会从
```
.feature/state/implement/
```
读取实现产物，明确已构建的内容，并将分析范围限定为已修改/新增的文件。
排除规则：跳过
```
node_modules/
```
、
```
vendor/
```
、
```
.git/
```
、
```
__pycache__/
```
、
```
dist/
```
、
```
build/
```
、测试夹具及生成文件。原因：这些文件中包含有意设置的未使用导出内容（如库代码、第三方依赖），会导致报告中出现大量误报。
按严重程度排序：优先报告ORPHANED（失败），其次是IMPORTED_NOT_USED（警告），最后是WIRED（通过）。用户需要优先查看失败项。

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需开启）

Requirements Map: When a task plan exists (
```
.feature/state/plan/
```
), produce per-requirement wiring status. Only available in feature pipeline context.
Verbose Mode: Show WIRED components in addition to failures and warnings. Default only shows issues.

需求映射：当存在任务计划（
```
.feature/state/plan/
```
）时，生成每个需求的连接状态。仅在功能流水线上下文下可用。
详细模式：除失败项和警告项外，还会展示WIRED状态的组件。默认仅显示问题项。

What This Skill CAN Do

本技能可实现的功能

Build export/import maps for Go, Python, TypeScript, and JavaScript projects
Classify exports as WIRED, IMPORTED_NOT_USED, or ORPHANED
Detect hardcoded empty data, placeholder values, and dead parameters flowing through wired connections
Verify output shape compatibility between connected components
Produce per-requirement wiring status when a task plan exists
Operate standalone or as part of the feature pipeline

为Go、Python、TypeScript和JavaScript项目构建导出/导入关系图
将导出内容分类为WIRED、IMPORTED_NOT_USED或ORPHANED状态
检测硬编码空数据、占位符值及通过连接传递的无效参数
验证已连接组件之间的输出格式兼容性
当存在任务计划时，生成基于需求的连接状态报告
支持独立使用或集成到功能流水线中

What This Skill CANNOT Do

本技能无法实现的功能

Fix wiring issues (route to feature-implement or the user)
Verify runtime behavior or semantic correctness
Analyze dynamically-loaded modules, reflection-based wiring, or plugin architectures with certainty
Replace integration tests (this is static analysis, not execution)
Reason: This skill is static structural analysis. Runtime verification and fix application require different capabilities.

修复连接问题（需跳转至feature-implement阶段或由用户处理）
验证运行时行为或语义正确性
准确分析动态加载模块、基于反射的连接或插件架构
替代集成测试（本技能为静态分析，而非执行测试）
原因：本技能属于静态结构分析，运行时验证和修复操作需要不同的能力支持。

Instructions

操作步骤

Phase 0: PRIME

阶段0：准备（PRIME）

Goal: Establish context, detect language, identify scope.

Step 1: Detect execution context

Determine if running within the feature pipeline or standalone:

Pipeline: Check for
```
.feature/state/implement/
```
artifact. If present, load it to understand what was built and scope the check to changed/added files.
Standalone: Scope to the current working directory or user-specified path. Analyze all source files.

Step 2: Detect project language(s)

Identify language(s) from file extensions, build files, and project structure:

Indicator	Language
`go.mod` , `*.go`	Go
`pyproject.toml` , `setup.py` , `*.py`	Python
`tsconfig.json` , `.ts` , `.tsx`	TypeScript
`package.json` , `.js` , `.jsx`	JavaScript

Multiple languages may coexist. Run all applicable techniques for each.

Step 3: Identify language-specific patterns

Language	Export Pattern	Import Pattern	Common Integration Failures
Go	Capitalized identifiers at package level	`import "path/to/pkg"` then `pkg.Name`	Exported function in wrong package; interface satisfied but never used via interface type; `init()` side effects not triggered because package not imported
Python	Module-level definitions, `__all__` , `__init__.py` re-exports	`from module import name` , `import module`	Circular imports causing silent failures; `__init__.py` missing re-export; relative vs absolute import mismatch
TypeScript	`export` , `export default` , barrel files ( `index.ts` )	`import { name } from './module'`	Barrel file missing re-export; type-only import where value import needed; path alias not resolving
JavaScript	`module.exports` , `export` , `export default`	`require()` , `import`	CommonJS/ESM mismatch; default vs named export confusion

Gate: Language(s) detected. Scope established. Proceed to Phase 1.

目标：建立上下文、检测项目语言、确定分析范围。

步骤1：检测执行上下文

判断当前是否处于功能流水线中或独立运行：

流水线模式：检查是否存在
```
.feature/state/implement/
```
产物。若存在，加载该文件以了解已构建内容，并将分析范围限定为已修改/新增的文件。
独立模式：分析范围为当前工作目录或用户指定路径，覆盖所有源文件。

步骤2：检测项目语言

通过文件扩展名、构建文件及项目结构识别语言：

识别标识	对应语言
`go.mod` , `*.go`	Go
`pyproject.toml` , `setup.py` , `*.py`	Python
`tsconfig.json` , `.ts` , `.tsx`	TypeScript
`package.json` , `.js` , `.jsx`	JavaScript

项目可能包含多种语言，需为每种适用语言运行对应的验证技术。

步骤3：识别语言特定模式

语言	导出模式	导入模式	常见集成失败场景
Go	包级别的大写标识符	`import "path/to/pkg"` 后使用 `pkg.Name`	导出函数位于错误包中；接口已实现但从未通过接口类型使用；因包未导入导致 `init()` 副作用未触发
Python	模块级定义、 `__all__` 、 `__init__.py` 重导出	`from module import name` , `import module`	循环导入导致静默失败； `__init__.py` 缺失重导出；相对导入与绝对导入不匹配
TypeScript	`export` 、 `export default` 、桶文件（ `index.ts` ）	`import { name } from './module'`	桶文件缺失重导出；在需要值导入的场景使用了类型仅导入；路径别名无法解析
JavaScript	`module.exports` 、 `export` 、 `export default`	`require()` 、 `import`	CommonJS/ESM不兼容；默认导出与命名导出混淆

准入条件：已检测到项目语言、确定分析范围，进入阶段1。

Phase 1: EXPORT/IMPORT MAP

阶段1：导出/导入关系图

Goal: For every export in scope, determine its wiring status: WIRED, IMPORTED_NOT_USED, or ORPHANED.

Step 1: Discover exports

Scan source files for exported symbols. Be language-aware:

Go: Find all capitalized function, type, const, and var declarations at package level. Include method receivers on exported types.
Python: Find all module-level function/class/variable definitions. Check
```
__all__
```
if present (it restricts the public API). Check
```
__init__.py
```
for re-exports.
TypeScript/JavaScript: Find all
```
export
```
declarations,
```
export default
```
, and barrel file re-exports.

Record each export as:

{file, name, kind (function/type/const/var), line}

Step 2: Discover imports and usages

For each export found, search the codebase for:

Import: The symbol is imported (appears in an import statement referencing the exporting module)
Usage: The imported symbol is actually used (called, referenced, assigned, passed as argument) beyond the import statement itself

This two-step check is critical. WHY: An import without usage is IMPORTED_NOT_USED, which is a distinct failure mode from ORPHANED. It signals someone intended to use the component but didn't finish wiring it.

Step 3: Classify each export

Condition	Status	Severity
Exported, imported, AND used in at least one consumer	WIRED	Pass
Exported and imported, but never used beyond the import statement	IMPORTED_NOT_USED	Warning
Exported but never imported anywhere in the project	ORPHANED	Failure

Exclusions (do not flag as ORPHANED):

```
main()
```
functions and entry points
Interface implementations that satisfy an interface (Go)
Test helpers exported for use by
```
_test.go
```
files in other packages
Symbols listed in public API documentation or
```
__all__
```
in library packages
CLI command handlers wired via registration (e.g., cobra commands, click groups)
Exports in files matching exclusion patterns (vendor, node_modules, etc.)

Step 4: Build the export/import map

Produce a structured map:

undefined

目标：为范围内的每个导出内容确定连接状态：WIRED（已连接）、IMPORTED_NOT_USED（已导入但未使用）、ORPHANED（孤立状态）。

步骤1：发现导出内容

扫描源文件中的导出符号，需适配不同语言：

Go：查找包级别所有大写的函数、类型、常量和变量声明，包括导出类型的方法接收器。
Python：查找所有模块级别的函数/类/变量定义。若存在
```
__all__
```
则以其为准（它限定了公开API范围）。检查
```
__init__.py
```
中的重导出内容。
TypeScript/JavaScript：查找所有
```
export
```
声明、
```
export default
```
及桶文件重导出内容。

记录每个导出内容的信息：

{文件路径, 名称, 类型（函数/类型/常量/变量）, 行号}

。

步骤2：发现导入及使用情况

针对每个导出内容，在代码库中搜索：

导入：该符号是否被导入（出现在引用导出模块的导入语句中）
使用：导入后的符号是否实际被使用（如被调用、引用、赋值、作为参数传递），而非仅存在于导入语句中

这两步检查至关重要。原因：仅导入未使用属于IMPORTED_NOT_USED状态，与ORPHANED是不同的失败模式，意味着有人意图使用该组件但未完成连接。

步骤3：分类每个导出内容

条件	状态	严重程度
已导出、已导入且至少在一个消费者中被使用	WIRED	通过
已导出且已导入，但除导入语句外从未被使用	IMPORTED_NOT_USED	警告
已导出但从未被代码库中任何部分导入	ORPHANED	失败

排除项（不会标记为ORPHANED）：

```
main()
```
函数及入口点
实现了接口的类型（Go）
为其他包中
```
_test.go
```
文件提供的测试助手
公开API文档或库包
```
__all__
```
中列出的符号
通过注册方式接入的CLI命令处理器（如cobra命令、click组）
符合排除规则的文件中的导出内容（如vendor、node_modules等）

步骤4：构建导出/导入关系图

生成结构化关系图：

undefined

Export/Import Map

导出/导入关系图

ORPHANED (Failure)

ORPHANED（失败）

File	Export	Kind	Imported By
api/handlers.go	HandleUserDelete	func	(none)
utils/format.py	format_currency	func	(none)

文件	导出内容	类型	被导入位置
api/handlers.go	HandleUserDelete	函数	（无）
utils/format.py	format_currency	函数	（无）

IMPORTED_NOT_USED (Warning)

IMPORTED_NOT_USED（警告）

File	Export	Kind	Imported By	Used?
api/handlers.go	HandleUserUpdate	func	routes/api.go	No

文件	导出内容	类型	被导入位置	是否使用
api/handlers.go	HandleUserUpdate	函数	routes/api.go	否

WIRED (Pass) — [N] components

WIRED（通过）—— [N]个组件

(Shown only in verbose mode)


**Gate**: All in-scope exports classified. Map produced. Proceed to Phase 2.

---

（仅在详细模式下展示）


**准入条件**：范围内所有导出内容已完成分类、关系图已生成，进入阶段2。

---

Phase 2: DATA FLOW AND CONTRACT CHECK

阶段2：数据流与契约检查

Goal: For WIRED components, verify that real data flows through the connections and that output shapes match input expectations.

This phase checks two things simultaneously because they both operate on the same set of WIRED connections identified in Phase 1.

目标：针对WIRED状态的组件，验证真实数据是否能在连接中流转，且输出格式匹配输入预期。

本阶段同时检查两项内容，因为它们都基于阶段1中识别的WIRED连接。

Data Flow Tracing

数据流追踪

For each WIRED connection, check whether real data actually reaches the component. Specifically look for:

Hardcoded empty data:

Empty arrays/slices passed to functions that iterate over them:
```
processItems([])
```
,
```
handleUsers([]User{})
```
Empty strings passed where meaningful content is expected
Zero values for IDs, counts, or sizes that should be populated
```
nil
```
/
```
None
```
/
```
null
```
/
```
undefined
```
passed where a real object is expected

Placeholder data:

TODO/FIXME/HACK comments adjacent to data assignment
Lorem ipsum, "test", "example", "placeholder" string literals in non-test code
Zeroed structs or objects with no fields populated:
```
User{}
```
,
```
{}
```

Dead parameters:

Function declares a parameter but never reads it (not just
```
_
```
convention)
Parameter is read only to immediately discard:
```
_ = param
```

Mock remnants:

```
return []
```
,
```
return nil
```
,
```
return {}
```
in non-test code paths where real data is expected
Hardcoded return values that bypass actual logic

Record each finding as:

{file, line, kind (empty-data|placeholder|dead-param|mock-remnant), description}

针对每个WIRED连接，检查真实数据是否确实传递到组件中。重点关注：

硬编码空数据：

向需要遍历的函数传递空数组/切片：
```
processItems([])
```
、
```
handleUsers([]User{})
```
向需要有效内容的位置传递空字符串
ID、计数、大小等应填充字段被设为零值
在需要真实对象的位置传递
```
nil
```
/
```
None
```
/
```
null
```
/
```
undefined
```

占位符数据：

数据赋值附近存在TODO/FIXME/HACK注释
非测试代码中出现Lorem ipsum、"test"、"example"、"placeholder"等字符串字面量
未填充任何字段的零值结构体或对象：
```
User{}
```
、
```
{}
```

无效参数：

函数声明了参数但从未读取（非
```
_
```
命名约定的情况）
参数仅被读取后立即丢弃：
```
_ = param
```

残留模拟数据：

非测试代码路径中返回
```
return []
```
、
```
return nil
```
、
```
return {}
```
，但实际应返回真实数据
硬编码返回值绕过了实际逻辑

记录每个问题：

{文件路径, 行号, 类型（空数据|占位符|无效参数|残留模拟数据）, 描述}

。

Cross-Component Contract Checking

跨组件契约检查

For each WIRED connection where component A's output feeds into component B's input, verify structural compatibility:

Shape mismatches:

A returns

{id, name, email}

but B expects

{userId, displayName, emailAddress}

-- field naming mismatch

A returns a flat object but B destructures expecting nested structure
A returns a single item but B expects an array (or vice versa)

Type mismatches:

A returns a string ID but B expects a numeric ID
A returns an optional/nullable value but B accesses it without null check

Event/message contract mismatches:

Emitter sends event type
```
"user.created"
```
but handler listens for
```
"userCreated"
```
Message producer sends one schema, consumer expects different fields

Record each finding as:

{producer_file, consumer_file, mismatch_kind, description}

Important context: Contract checking is approximate in dynamic languages. Report findings with appropriate confidence:

High confidence: Explicit type annotations match/mismatch, struct/interface definitions
Medium confidence: Inferred from usage patterns, variable names, JSDoc/docstrings
Low confidence: Dynamic access patterns, computed property names, reflection

Gate: Data flow and contract findings recorded. Proceed to Phase 3.

针对每个组件A的输出作为组件B输入的WIRED连接，验证结构兼容性：

格式不匹配：

A返回

{id, name, email}

但B期望

{userId, displayName, emailAddress}

——字段名称不匹配

A返回扁平对象但B期望嵌套结构并尝试解构
A返回单个项但B期望数组（反之亦然）

类型不匹配：

A返回字符串类型ID但B期望数值类型ID
A返回可选/可空值但B未做空值检查就直接访问

事件/消息契约不匹配：

事件发射器发送
```
"user.created"
```
类型事件，但处理器监听
```
"userCreated"
```
消息生产者使用一种 schema，消费者期望另一种字段结构

记录每个问题：

{生产者文件, 消费者文件, 不匹配类型, 描述}

。

重要说明：动态语言中的契约检查是近似的，需根据置信度报告结果：

高置信度：显式类型注解匹配/不匹配、结构体/接口定义
中置信度：从使用模式、变量名、JSDoc/文档字符串推断
低置信度：动态访问模式、计算属性名、反射

准入条件：已记录数据流和契约检查结果，进入阶段3。

Phase 3: REPORT

阶段3：生成报告

Goal: Produce a structured integration report with actionable findings.

Step 1: Requirements integration map (pipeline mode only)

If running within the feature pipeline and a task plan exists in

.feature/state/plan/

For each requirement in the plan, trace the integration path from entry point to implementation:

Status	Meaning
WIRED	Requirement has a complete integration path from entry point to implementation
PARTIAL	Some components exist but the path has gaps (identify the gaps)
UNWIRED	Components may exist but no integration path connects them

undefined

目标：生成结构化集成报告，包含可执行的改进建议。

步骤1：需求集成映射（仅流水线模式）

若在功能流水线中运行且

.feature/state/plan/

存在任务计划：

针对计划中的每个需求，追踪从入口点到实现的集成路径：

状态	含义
WIRED	需求具备从入口点到实现的完整集成路径
PARTIAL	部分组件存在，但路径存在缺口（需明确缺口位置）
UNWIRED	组件可能存在，但无集成路径将其关联

undefined

Requirements Integration Map

需求集成映射

Requirement	Status	Integration Path
User can delete account	WIRED	DELETE /api/users/:id -> routes/api.go -> handlers.HandleUserDelete -> db.DeleteUser
Email notification on delete	PARTIAL	handlers.HandleUserDelete -> [GAP] -> email.SendNotification (exists but not called from handler)
Audit log on delete	UNWIRED	audit.LogEvent exists, but no call from any delete path


**Step 2: Compile integration report**

```markdown

需求	状态	集成路径
用户可删除账户	WIRED	DELETE /api/users/:id -> routes/api.go -> handlers.HandleUserDelete -> db.DeleteUser
删除操作触发邮件通知	PARTIAL	handlers.HandleUserDelete -> [缺口] -> email.SendNotification（存在但未被处理器调用）
删除操作记录审计日志	UNWIRED	audit.LogEvent存在，但所有删除路径均未调用


**步骤2：编译集成报告**

```markdown

Integration Check Report

集成检查报告

Summary

摘要

Components checked: [N]
WIRED: [N]
IMPORTED_NOT_USED: [N]
ORPHANED: [N]
Data flow issues: [N]
Contract mismatches: [N]
Integration score: [WIRED / (WIRED + IMPORTED_NOT_USED + ORPHANED) * 100]%

已检查组件数：[N]
WIRED（已连接）：[N]
IMPORTED_NOT_USED（已导入未使用）：[N]
ORPHANED（孤立）：[N]
数据流问题：[N]
契约不匹配：[N]
集成得分：[WIRED / (WIRED + IMPORTED_NOT_USED + ORPHANED) * 100]%

Verdict: PASS / WARN / FAIL

结论：通过 / 警告 / 失败

PASS: No ORPHANED components, no data flow issues, no contract mismatches WARN: No ORPHANED, but has IMPORTED_NOT_USED or low-confidence contract findings FAIL: Has ORPHANED components, data flow issues, or high-confidence contract mismatches

通过：无ORPHANED组件、无数据流问题、无契约不匹配警告：无ORPHANED组件，但存在IMPORTED_NOT_USED或低置信度契约问题失败：存在ORPHANED组件、数据流问题或高置信度契约不匹配

Export/Import Map

导出/导入关系图

[From Phase 1 — only issues, unless verbose mode]

[来自阶段1 —— 仅展示问题项，详细模式下展示全部]

Data Flow Issues

数据流问题

[From Phase 2 — data flow findings]

[来自阶段2 —— 数据流检查结果]

Contract Mismatches

契约不匹配

[From Phase 2 — contract findings with confidence level]

[来自阶段2 —— 包含置信度的契约检查结果]

Requirements Integration Map

需求集成映射

[From Step 1 — if in pipeline mode]

[来自步骤1 —— 仅流水线模式展示]

Recommended Actions

建议操作

[Specific action for each ORPHANED component]
[Specific action for each IMPORTED_NOT_USED]
[Specific action for each data flow issue]
[Specific action for each contract mismatch]


**Step 3: Verdict and next steps**

| Verdict | Next Step |
|---------|-----------|
| **PASS** | Proceed to /feature-validate |
| **WARN** | Review warnings. Proceed if warnings are intentional (unused imports for future use, etc.). Fix if unintentional. |
| **FAIL** | Route back to /feature-implement with specific wiring tasks. Do NOT proceed to validation. |

**Gate**: Report produced with verdict and actionable recommendations.

---

[针对每个ORPHANED组件的具体操作]
[针对每个IMPORTED_NOT_USED的具体操作]
[针对每个数据流问题的具体操作]
[针对每个契约不匹配的具体操作]


**步骤3：结论与下一步**

| 结论 | 下一步操作 |
|---------|-----------|
| **通过** | 进入/feature-validate阶段 |
| **警告** | 查看警告内容。若为有意为之（如预留未使用导入用于后续功能）可继续；若为无意疏漏则修复问题。 |
| **失败** | 跳转至/feature-implement阶段并处理具体连接任务，**请勿**进入验证阶段。 |

**准入条件**：已生成包含结论和可执行建议的报告。

---

Error Handling

错误处理

Error	Cause	Solution
No source files found	Wrong scope path or empty project	Verify working directory, check scope parameter
Language not detected	No recognizable build files or source extensions	Specify language manually or check project structure
Too many exports to analyze	Large monorepo or library with thousands of exports	Narrow scope to changed files (use `git diff --name-only` against base branch)
False positive ORPHANED	Library code, plugin interfaces, or entry points	Check exclusion patterns. If legitimate public API, add to exclusions.
Circular import detected	Python circular imports or Go import cycles	Report as separate finding — circular imports are integration issues themselves
No implementation artifact	Running in pipeline mode but implement phase didn't checkpoint	Fall back to standalone mode using git diff to identify changed files

错误	原因	解决方案
未找到源文件	范围路径错误或项目为空	验证工作目录，检查范围参数
未检测到语言	无可识别的构建文件或源文件扩展名	手动指定语言或检查项目结构
待分析导出内容过多	大型单体仓库或包含数千个导出的库	将范围缩小到已修改文件（使用 `git diff --name-only` 对比基准分支）
ORPHANED误报	库代码、插件接口或入口点	检查排除规则。若为合法公开API，添加到排除列表
检测到循环导入	Python循环导入或Go导入循环	作为单独问题报告——循环导入本身属于集成问题
无实现产物	处于流水线模式但实现阶段未生成检查点	回退到独立模式，使用git diff识别已修改文件

Anti-Patterns

反模式

Anti-Pattern	Why Wrong	Do Instead
Checking only that imports exist	Import without usage is a distinct failure mode (IMPORTED_NOT_USED)	Verify import AND usage for each export
Treating all ORPHANED as bugs	Library code, plugin interfaces, and entry points are intentionally not imported internally	Apply exclusion patterns before flagging
Skipping data flow check because wiring exists	A component wired to always receive empty data is functionally disconnected	Check data flow for every WIRED connection
Running on entire monorepo in pipeline mode	Wastes time analyzing unchanged code	Scope to files changed since implementation started
Auto-fixing wiring issues	Integration fixes often require design decisions (which component should call which?)	Report issues, let human or feature-implement decide the fix
Treating low-confidence contract findings as failures	Dynamic language contract checking is approximate without runtime types	Report confidence level, only FAIL on high-confidence mismatches

反模式	问题所在	正确做法
仅检查导入是否存在	仅导入未使用是独立的失败模式（IMPORTED_NOT_USED）	针对每个导出内容，同时验证导入和使用情况
将所有ORPHANED标记为bug	库代码、插件接口和入口点本就不会被内部导入	在标记前应用排除规则
因已连接而跳过数据流检查	始终接收空数据的组件在功能上等同于未连接	针对每个WIRED连接检查数据流
流水线模式下扫描整个单体仓库	浪费时间分析未修改代码	将范围限定为实现阶段开始后修改的文件
自动修复连接问题	集成修复通常需要设计决策（如确定哪个组件调用哪个）	报告问题，由人工或feature-implement阶段决定修复方案
将低置信度契约问题标记为失败	动态语言的契约检查在无运行时类型的情况下是近似的	报告置信度，仅将高置信度不匹配标记为失败

Anti-Rationalization

反合理化

Rationalization Attempt	Why It's Wrong	Required Action
"The component exists and has real logic, so it's integrated"	Existence is not integration. A function that's never called is dead code.	Check import AND usage, not just existence
"It's imported, so it must be used"	Unused imports are a specific failure mode — someone started wiring but didn't finish	Verify the import is followed by actual usage
"The wiring looks right so data must flow"	Wiring to an empty array is functionally the same as no wiring	Trace actual data through each connection
"Contract checking is too hard in dynamic languages"	Approximate checking still catches obvious mismatches	Check what you can, report confidence levels
"These ORPHANED exports are for future use"	Future use is not current integration. Flag them now, exclude intentionally if confirmed.	Report all ORPHANED, let the user decide which are intentional
"Integration checking is overkill for a small change"	Small changes are where wiring gets forgotten — new function added but never called	Run the check. Scope narrows automatically for small changes.

合理化尝试	问题所在	必要操作
「组件存在且逻辑正确，所以已集成」	存在不等于集成。从未被调用的函数属于死代码	检查导入和使用情况，而非仅确认存在
「已导入，所以肯定在使用」	未使用的导入是特定失败模式——有人开始连接但未完成	验证导入后是否有实际使用
「连接看起来正确，所以数据肯定能流转」	连接到空数组在功能上等同于未连接	追踪每个连接中的实际数据
「动态语言的契约检查太难了」	近似检查仍能发现明显的不匹配	尽可能检查，并报告置信度
「这些ORPHANED导出是为未来功能预留的」	未来使用不等于当前集成。先标记，确认有意为之再排除	报告所有ORPHANED，由用户决定哪些是有意预留
「小改动没必要做集成检查」	小改动最容易遗漏连接——新增函数但从未被调用	执行检查，小改动会自动缩小分析范围

References

参考资料

Feature State Conventions
Gate Enforcement
Anti-Rationalization Core
ADR-078: Integration Checker

功能状态约定
准入规则强制执行
反合理化核心
ADR-078: Integration Checker