name: wiring-test description: 为loom计划生成布线验证YAML。帮助代理证明功能已正确集成 — 命令已注册、端点已挂载、模块已导出、组件已渲染。在编写loom计划阶段的truths/artifacts/wiring字段时使用。 allowed-tools: Read, Grep, Glob, Edit, Write, Bash trigger-keywords: wiring, wiring-test, wiring test, integration test, integration verification, verify wiring, prove integration, command registered, endpoint mounted, module exported

布线测试技能

概述

问题： 测试可能通过，代码可能编译，但功能可能从未被布线 — 命令未注册、端点未挂载、模块未导入、组件未渲染。这是集成中的常见失败模式。

解决方案： 布线验证通过三种类型的证据来证明集成：

Truths（可观察行为） — 可观察的行为（shell命令返回退出码0）
Artifacts（实现文件） — 必须存在的文件，包含真实实现（不仅仅是空文件）
Wiring（代码模式） — 证明连接点的代码模式（导入、注册、挂载）

这个技能帮助您为loom计划阶段YAML元数据编写强大的truths、artifacts和wiring字段。

何时使用

当编写loom计划阶段时（特别是integration-verify阶段）
当验证功能是否实际集成到应用程序中时
当审查验收标准以确保它们证明功能集成时
当调试为什么一个“通过”的功能在实践中不工作时

布线YAML格式参考

Loom计划使用三个验证字段来证明集成：

truths:
  - "command-that-proves-behavior"
  - "another-observable-check"

artifacts:
  - "path/to/implementation.rs"
  - "path/to/another/file.ts"

wiring:
  - source: "path/to/integration/point.rs"
    pattern: "mod feature_name"
    description: "Feature module is imported in main"
  - source: "path/to/router.rs"
    pattern: "mount_feature_routes"
    description: "Feature routes are mounted in router"

关键路径规则： 所有路径（artifacts、wiring.source）都是相对于阶段的working_dir字段的。如果working_dir: "loom"，则路径从loom/目录内部解析。

YAML语法警告： 永远不要在YAML description字段中使用三重反引号。使用纯缩进文本代替代码示例。

按功能类型的模板

CLI命令

对于新的CLI命令（例如，loom verify <stage-id>）：

truths:
  - "loom verify --help"  # 命令响应
  - "loom verify stage-1 --suggest"  # 主要用例有效

artifacts:
  - "src/commands/verify.rs"  # 实现存在
  - "src/verify/mod.rs"  # 支持模块存在

wiring:
  - source: "src/main.rs"
    pattern: "mod commands"
    description: "Commands module imported"
  - source: "src/commands/mod.rs"
    pattern: "pub mod verify"
    description: "Verify command exported"
  - source: "src/main.rs"
    pattern: "Commands::Verify"
    description: "Verify variant in CLI enum"

路径上下文： 如果working_dir: "loom"，这些路径解析到loom/src/commands/verify.rs等。

API端点

对于REST端点（例如，POST /api/features）：

truths:
  - "curl -f -X POST http://localhost:8080/api/features -d '{\"name\":\"test\"}'"
  - "curl -f http://localhost:8080/api/features | grep -q '\"features\"'"

artifacts:
  - "src/handlers/features.rs"
  - "src/routes/api.rs"

wiring:
  - source: "src/routes/api.rs"
    pattern: "post(\"/features\", create_feature)"
    description: "POST /features route registered"
  - source: "src/main.rs"
    pattern: "mount(\"/api\", api_routes())"
    description: "API routes mounted in application"
  - source: "src/handlers/mod.rs"
    pattern: "pub mod features"
    description: "Features handler exported"

注意： 功能检查（curl）证明端点可达，而不仅仅是测试通过。

模块/库

对于新的内部模块（例如，身份验证模块）：

truths:
  - "cargo test auth::"  # 模块测试通过
  - "cargo check"  # 模块在上下文中编译

artifacts:
  - "src/auth/mod.rs"
  - "src/auth/jwt.rs"
  - "src/auth/session.rs"

wiring:
  - source: "src/lib.rs"
    pattern: "pub mod auth"
    description: "Auth module exported from library root"
  - source: "src/main.rs"
    pattern: "use crate::auth"
    description: "Auth module imported in main"

UI组件

对于React/Vue组件（例如，FeatureCard）：

truths:
  - "npm test -- FeatureCard"  # 组件测试通过
  - "npm run build"  # 组件编译

artifacts:
  - "src/components/FeatureCard.tsx"
  - "src/components/FeatureCard.test.tsx"

wiring:
  - source: "src/components/index.ts"
    pattern: "export { FeatureCard }"
    description: "FeatureCard exported from components barrel"
  - source: "src/pages/Dashboard.tsx"
    pattern: "<FeatureCard"
    description: "FeatureCard rendered in Dashboard"
  - source: "src/pages/Dashboard.tsx"
    pattern: "import.*FeatureCard"
    description: "FeatureCard imported in parent component"

好与坏的示例

坏：太宽泛

truths:
  - "cargo test"  # 仅证明测试通过，非功能工作
  - "cargo build"  # 仅证明编译

artifacts:
  - "src/"  # 太宽泛，证明无物

wiring: []  # 缺失 — 无集成证明

问题： 这些检查不证明功能已布线或功能有效。即使功能从未注册/挂载/导入，测试也能通过。

好：具体且功能化

truths:
  - "loom verify stage-1 --suggest"  # 证明verify命令端到端工作
  - "loom verify --help | grep -q 'suggest'"  # 证明--suggest标志存在

artifacts:
  - "src/commands/verify.rs"  # 实现文件
  - "src/verify/checker.rs"  # 核心逻辑文件

wiring:
  - source: "src/main.rs"
    pattern: "Commands::Verify"
    description: "Verify command variant in CLI enum"
  - source: "src/commands/mod.rs"
    pattern: "pub mod verify"
    description: "Verify module exported from commands"
  - source: "src/commands/verify.rs"
    pattern: "run_verification"
    description: "Core verification function exists"

为什么更好：

Truths证明实际命令工作（不仅仅是测试）
Artifacts证明特定实现文件存在
Wiring证明命令在CLI中注册并正确暴露

改进问题

在最终确定布线验证之前，问自己：

Truths

用户将调用什么确切的命令/端点/导入？
- 不是“测试通过”而是“实际功能响应”
什么输出证明它在工作（不仅仅是“无错误”）？
- 寻找特定输出、退出码或行为
我能测试主要用例端到端吗？
- 不要只检查--help，实际运行功能

Artifacts

功能必须存在哪些文件才能工作？
- 不仅仅是目录或测试文件，而是实际实现
这些路径是相对于working_dir的吗？
- 双重检查阶段的working_dir字段
这些文件包含真实代码吗（不是存根/TODO）？
- Loom可以检查文件大小或grep实现模式

Wiring

功能连接到现有代码库的哪里？
- 命令 → CLI解析器，端点 → 路由器，模块 → 父导入
什么代码模式证明连接存在？
- 寻找导入、注册、挂载调用、枚举变体
模式是否足够具体以避免误报？
- mod verify 比仅 verify 更好（可能匹配注释）

工作目录和路径解析

关键： 所有验证路径都是相对于阶段的working_dir字段的。

# Stage configuration
- id: my-stage
  working_dir: "loom"  # Commands execute from .worktrees/my-stage/loom/

  # Verification paths resolve relative to working_dir
  artifacts:
    - "src/feature.rs"  # Resolves to .worktrees/my-stage/loom/src/feature.rs

  wiring:
    - source: "src/main.rs"  # Resolves to .worktrees/my-stage/loom/src/main.rs
      pattern: "mod feature"
      description: "Feature module imported"

公式： RESOLVED_PATH = WORKTREE_ROOT + working_dir + path

示例： 如果：

工作树根：.worktrees/my-stage/
working_dir: "loom"
Artifact路径："src/feature.rs"

那么解析路径：.worktrees/my-stage/loom/src/feature.rs

无路径遍历： 永远不要在路径中使用../。所有路径必须相对于working_dir或更深。

复制粘贴YAML模板

CLI命令模板

truths:
  - "myapp command --help"
  - "myapp command arg1 arg2"  # Primary use case

artifacts:
  - "src/commands/command.rs"

wiring:
  - source: "src/main.rs"
    pattern: "Commands::CommandName"
    description: "Command variant in CLI enum"
  - source: "src/commands/mod.rs"
    pattern: "pub mod command"
    description: "Command module exported"

API端点模板

truths:
  - "curl -f -X GET http://localhost:PORT/api/endpoint"
  - "curl -f http://localhost:PORT/api/endpoint | grep -q 'expected_field'"

artifacts:
  - "src/handlers/endpoint.rs"
  - "src/routes/api.rs"

wiring:
  - source: "src/routes/api.rs"
    pattern: "get(\"/endpoint\", handler)"
    description: "Endpoint route registered"
  - source: "src/main.rs"
    pattern: "mount(\"/api\", routes)"
    description: "API routes mounted"

模块模板

truths:
  - "cargo test module::"
  - "cargo check"

artifacts:
  - "src/module/mod.rs"
  - "src/module/core.rs"

wiring:
  - source: "src/lib.rs"
    pattern: "pub mod module"
    description: "Module exported from library"
  - source: "src/main.rs"
    pattern: "use crate::module"
    description: "Module imported in main"

UI组件模板

truths:
  - "npm test -- ComponentName"
  - "npm run build"

artifacts:
  - "src/components/ComponentName.tsx"
  - "src/components/ComponentName.test.tsx"

wiring:
  - source: "src/components/index.ts"
    pattern: "export.*ComponentName"
    description: "Component exported from barrel"
  - source: "src/pages/Parent.tsx"
    pattern: "<ComponentName"
    description: "Component rendered in parent"

与Loom Verify命令的集成

loom verify <stage-id>命令执行这些检查：

Truths： 运行每个shell命令，期望退出码0
Artifacts： 检查文件存在且非空（默认大于100字节）
Wiring： 在源文件中grep模式，期望至少一个匹配

当检查失败时，使用loom verify <stage-id> --suggest获取修复建议。

最终清单

在最终确定布线验证之前：

[ ] 至少一个truth证明功能端到端工作（不仅仅是测试）
[ ] 所有artifacts都是特定的实现文件（不是目录或测试文件）
[ ] 所有wiring条目都有特定模式（不是通用字符串如“feature”）
[ ] 所有路径都相对于working_dir（无../遍历）
[ ] YAML description字段中无三重反引号
[ ] 模式足够具体以避免注释中的误匹配
[ ] Truth命令使用-q标志进行grep（静默模式，仅退出码重要）

常见陷阱

测试通过 ≠ 功能工作
- 坏：truths: ["cargo test"]
- 好：truths: ["loom verify stage-1"]
通用模式匹配太多
- 坏：pattern: "verify"（匹配注释、字符串）
- 好：pattern: "Commands::Verify"（特定枚举变体）
working_dir的路径错误
- 坏：working_dir: "." 与artifact "loom/src/file.rs"（创建双重路径）
- 好：working_dir: "loom" 与artifact "src/file.rs"（正确解析）
无功能验证
- 坏：仅检查文件存在和测试通过
- 好：实际运行命令/端点/导入并检查输出
YAML语法错误
- 坏：在description字段中使用三重反引号
- 好：使用纯缩进文本用于代码示例

记住： 布线验证是您对抗“孤立工作、集成中断”失败的最后一道防线。让它发挥价值。