Test Container Boundaries

# Test Container Boundaries Command

Systematic container input interface discovery, behavior analysis, and boundary testing pipeline. Identifies all input channels (API endpoints, queue consumers, file uploads, webhooks, etc.), documents expected behaviors, and validates each input with realistic test data.

---

## Purpose

This command validates that **each container correctly handles all its input interfaces** by:
1. Discovering all input channels (HTTP endpoints, queue listeners, event handlers, file watchers)
2. Documenting expected behavior for each input type
3. Testing each input with realistic data and validating processing behavior

**Position in Pipeline**:

/fix-container → Validates container responsibilities ↓ /test-container-boundaries → Validates container input interfaces (YOU ARE HERE) ↓ /fix-container-boundaries → Fixes failing boundary tests (NEW) ↓ /fix-e2e → Tests full user journeys across containers

---

## Required Skill

**MANDATORY**: Load the `container-boundary-testing` skill before Phase 3:

.claude/skills/container-boundary-testing/SKILL.md

This skill defines:
- **Consistent test file format** (TypeScript `.test.ts` ONLY)
- **Standard test template** for all boundary tests
- **Docker usage patterns** for rebuild and restart
- **Test fixture guidelines**

---

## What This Command Does

### Phase 1: Input Channel Discovery (Parallel, Batched)
Spawn discovery agents for ALL containers (max 2 concurrent):
- Each agent examines container specs and implementation
- Identifies all input channels (API routes, queue handlers, webhooks, file triggers)
- Creates input definition files in `{container}/tests/container-inputs/`

### Phase 2: Behavior Analysis (Parallel, Batched)
For each discovered input across all containers (max 2 concurrent):
- Deep code analysis of input handling logic
- Documents expected behavior, data transformations, side effects
- Updates the input definition file with behavior details

### Phase 3: Boundary Testing (Sequential per Input)
For each input with documented behavior an individual task agent is lauched that:
- Creates/validates test fixtures (images, videos, JSON payloads, etc.)
- Executes realistic input against running container
- Validates processing matches documented behavior
- Fixes deviations or updates documentation
- Rebuilds and restarts docker images with local-start-all.sh|psl and local-stop-allsh|psl to validate fixes

### Phase 4: Reporting
Generate comprehensive boundary test report showing:
- Inputs discovered per container
- Behaviors documented
- Tests passed/failed
- Deviations found and fixed

---

## Prerequisites

Before running this command:

1. **`/local-setup` has completed** - `docker-compose.local.yml` exists at project root
2. **Docker is available** - Containers can be built and run
3. **Architecture registry exists** - `.arch-registry/README.md` with container list
4. **Container implementations exist** - Source code is present

---

## Usage

```bash
/test-container-boundaries                              # Test all containers
/test-container-boundaries --container=api              # Test specific container
/test-container-boundaries --container=api,processing   # Test multiple containers
/test-container-boundaries --phase=discovery            # Run only Phase 1
/test-container-boundaries --phase=analysis             # Run Phases 1-2
/test-container-boundaries --skip-existing              # Skip inputs already documented

---

Instructions

You are orchestrating the container boundary testing pipeline. This command:

1. Discovers all containers from .arch-registry/README.md
2. Spawns input discovery agents for ALL containers in parallel (batched, max 2 concurrent)
3. After ALL discovery agents complete, spawns behavior analysis agents for each input (batched, max 2 concurrent)
4. After ALL analysis agents complete, sequentially launch test agents that tests each input with realistic data and generate the test code + fixtures and that fix any deviations from expected behavior.
5. Generates final report

CRITICAL: All testing happens against running Docker containers using docker-compose.local.yml.

---

⚠️⚠️⚠️ CRITICAL: BATCHING AND CONCURRENCY RULES ⚠️⚠️⚠️

MANDATORY EXECUTION RULES - MUST BE FOLLOWED:

1. Maximum 2 concurrent agents per batch: NEVER spawn more than 4 Task agents at once
2. Sequential batch execution: NEVER start a new batch while a previous batch is still running
3. Always use run_in_background: false: All Task tool calls MUST set run_in_background: false to ensure blocking execution
4. Wait for batch completion: Use TaskOutput or wait for all agents in the current batch to return results BEFORE spawning the next batch

CORRECT Batch Execution Pattern:

Batch 1: Spawn agents 1-4 (run_in_background: false)
         → Wait for ALL 4 to complete
         → Only after ALL complete, proceed to...

Batch 2: Spawn agents 5-8 (run_in_background: false)
         → Wait for ALL 4 to complete
         → Only after ALL complete, proceed to...

... continue until all items processed

INCORRECT Patterns (DO NOT DO THIS):

❌ Spawning batch 2 while batch 1 agents are still running
❌ Using run_in_background: true
❌ Spawning more than 2 agents in a single batch
❌ Starting next phase before all batches in current phase complete

---

Execution Flow

Phase 1: Input Channel Discovery (PARALLEL, BATCHED - max 2 concurrent)
    │   ┌─────────────────────────────────────────────────────────────────────┐
    │   │  Batch 1 (up to 2 containers):                                      │
    │   │  ├── container-1 → Discovery Agent (finds input channels)           │
    │   │  ├── container-2 → Discovery Agent (finds input channels)           │
    │   │  └── ...                                                            │
    │   │  Wait for ALL in batch to complete