Wiring Test Skill

Overview

The Problem: Tests can pass, code can compile, but the feature may never be wired up — command not registered, endpoint not mounted, module not imported, component never rendered. This is a common failure mode in integration.

The Solution: Wiring verification proves integration through three types of evidence:

1. Truths — Observable behaviors (shell commands returning exit 0)
2. Artifacts — Files that must exist with real implementation (not just empty files)
3. Wiring — Code patterns proving connection points (imports, registrations, mounts)

This skill helps you write strong truths, artifacts, and wiring fields for loom plan stage YAML metadata.

When to Use

• When writing loom plan stages (especially integration-verify stages)
• When verifying that a feature is actually integrated into the application
• When reviewing acceptance criteria to ensure they prove functional integration
• When debugging why a “passing” feature doesn’t work in practice

Wiring YAML Format Reference

Loom plans use three verification fields to prove integration:

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"

CRITICAL PATH RULE: All paths (artifacts, wiring.source) are relative to the stage’s working_dir field. If working_dir: "loom", then paths resolve from inside the loom/ directory.

YAML SYNTAX WARNING: NEVER put triple backticks inside YAML description fields. Use plain indented text for code examples instead.

Templates by Feature Type

CLI Command

For a new CLI command (e.g., loom verify <stage-id>):

truths:
  - "loom verify --help"  # Command responds
  - "loom verify stage-1 --suggest"  # Primary use case works

artifacts:
  - "src/commands/verify.rs"  # Implementation exists
  - "src/verify/mod.rs"  # Supporting module exists

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"

Path Context: If working_dir: "loom", these paths resolve to loom/src/commands/verify.rs, etc.

API Endpoint

For a REST endpoint (e.g., 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"

Note: Functional check (curl) proves endpoint is reachable, not just that tests pass.

Module/Library

For a new internal module (e.g., authentication module):

truths:
  - "cargo test auth::"  # Module tests pass
  - "cargo check"  # Module compiles in context

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 Component

For a React/Vue component (e.g., FeatureCard):

truths:
  - "npm test -- FeatureCard"  # Component tests pass
  - "npm run build"  # Component compiles

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"

Good vs Bad Examples

Bad: Too Broad

truths:
  - "cargo test"  # Only proves tests pass, not that feature works
  - "cargo build"  # Only proves it compiles

artifacts:
  - "src/"  # Too broad, proves nothing

wiring: []  # Missing — no integration proof

Problem: These checks don’t prove the feature is wired up or functional. Tests can pass even if the feature is never registered/mounted/imported.

Good: Specific and Functional

truths:
  - "loom verify stage-1 --suggest"  # Proves verify command works end-to-end
  - "loom verify --help | grep -q 'suggest'"  # Proves --suggest flag exists

artifacts:
  - "src/commands/verify.rs"  # Implementation file
  - "src/verify/checker.rs"  # Core logic file

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"

Why Better:

• Truths prove the actual command works (not just tests)
• Artifacts prove specific implementation files exist
• Wiring proves the command is registered in the CLI and exposed correctly

Refinement Questions

Before finalizing your wiring verification, ask yourself:

Truths

1. What exact command/endpoint/import will the user invoke?
   • Not “tests pass” but “the actual feature responds”
2. What output proves it’s working (not just “no error”)?
   • Look for specific output, exit codes, or behaviors
3. Can I test the primary use case end-to-end?
   • Don’t just check --help, actually run the feature

Artifacts

1. What files MUST exist for the feature to function?
   • Not just directories or test files, but actual implementation
2. Are these paths relative to working_dir?
   • Double-check the stage’s working_dir field
3. Do these files contain real code (not stubs/TODOs)?
   • Loom can check file size or grep for implementation patterns

Wiring

1. Where does the feature connect to the existing codebase?
   • Commands → CLI parser, Endpoints → router, Modules → parent import
2. What code pattern proves the connection exists?
   • Look for imports, registrations, mount calls, enum variants
3. Is the pattern specific enough to avoid false positives?
   • mod verify is better than just verify (could match comments)

Working Directory and Path Resolution

CRITICAL: All verification paths are relative to the stage’s working_dir field.

# 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"

Formula: RESOLVED_PATH = WORKTREE_ROOT + working_dir + path

Example: If:

• Worktree root: .worktrees/my-stage/
• working_dir: "loom"
• Artifact path: "src/feature.rs"

Then resolved path: .worktrees/my-stage/loom/src/feature.rs

NO PATH TRAVERSAL: Never use ../ in paths. All paths must be relative to working_dir or deeper.

Copy-Paste YAML Templates

CLI Command Template

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 Endpoint Template

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"

Module Template

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 Component Template

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"

Integration with Loom Verify Command

The loom verify <stage-id> command executes these checks:

1. Truths: Runs each shell command, expects exit 0
2. Artifacts: Checks files exist and are non-empty (> 100 bytes by default)
3. Wiring: Greps for patterns in source files, expects at least one match

Use loom verify <stage-id> --suggest to get fix suggestions when checks fail.

Final Checklist

Before finalizing your wiring verification:

• At least one truth proves the feature works end-to-end (not just tests)
• All artifacts are specific implementation files (not directories or test files)
• All wiring entries have specific patterns (not generic strings like “feature”)
• All paths are relative to working_dir (no ../ traversal)
• No triple backticks inside YAML description fields
• Patterns are specific enough to avoid false matches in comments
• Truth commands use -q flag for grep (silent mode, only exit code matters)

Common Pitfalls

1. Tests Pass ≠ Feature Works

   • Bad: truths: ["cargo test"]
   • Good: truths: ["loom verify stage-1"]

2. Generic Patterns Match Too Much

   • Bad: pattern: "verify" (matches comments, strings)
   • Good: pattern: "Commands::Verify" (specific enum variant)

3. Paths Wrong for working_dir

   • Bad: working_dir: "." with artifact "loom/src/file.rs" (creates double path)
   • Good: working_dir: "loom" with artifact "src/file.rs" (resolves correctly)

4. No Functional Verification

   • Bad: Only checking files exist and tests pass
   • Good: Actually running the command/endpoint/import and checking output

5. YAML Syntax Errors

   • Bad: Using triple backticks in description field
   • Good: Using plain indented text for code examples

Remember: Wiring verification is your last line of defense against “works in isolation, broken in integration” failures. Make it count.