@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/codex/harness-infrastructure-as-code/SKILL.md

@@ -0,0 +1,279 @@
+# Harness Infrastructure as Code
+
+> Terraform, CloudFormation, and Pulumi analysis. Module structure, state management, drift prevention, and security posture for infrastructure definitions.
+
+## When to Use
+
+- When reviewing or designing Terraform, CloudFormation, or Pulumi configurations
+- When auditing IaC module structure, naming conventions, and state management
+- On PRs that modify infrastructure definitions or add new cloud resources
+- NOT for CI/CD pipeline configuration (use harness-deployment)
+- NOT for container orchestration (use harness-containerization)
+- NOT for application-level security (use harness-security-review)
+
+## Process
+
+### Phase 1: DETECT -- Identify IaC Tool and Structure
+
+1. **Detect IaC tooling.** Scan the project for infrastructure definitions:
+   - `*.tf` files -- Terraform (HCL)
+   - `terraform/` directory with `.terraform.lock.hcl`
+   - `cloudformation/`, `*.template.yaml`, `*.template.json` -- CloudFormation
+   - `Pulumi.yaml`, `Pulumi.*.yaml` -- Pulumi
+   - `cdk.json`, `cdk.out/` -- AWS CDK
+   - `infrastructure/`, `infra/` -- common IaC directories
+
+2. **Identify provider and backend.** Parse configuration for:
+   - Cloud providers (AWS, GCP, Azure) and their versions
+   - State backend (S3, GCS, Azure Blob, Terraform Cloud, local)
+   - Provider authentication method (environment variables, profiles, OIDC)
+   - Lock file presence and provider version constraints
+
+3. **Map module structure.** Build a dependency tree of modules:
+   - Root modules and their child module references
+   - Module source types (local path, registry, git)
+   - Module versioning (pinned vs. unpinned)
+   - Input variables and output values per module
+   - Shared modules used across multiple root configurations
+
+4. **Detect environment separation.** Identify how environments are managed:
+   - Workspaces (Terraform workspaces)
+   - Directory-per-environment (`environments/dev/`, `environments/prod/`)
+   - Variable files per environment (`terraform.tfvars`, `prod.tfvars`)
+   - Backend configuration per environment
+
+5. **Present detection summary:**
+
+   ```
+   IaC Detection:
+     Tool: Terraform v1.7
+     Provider: AWS (us-east-1, us-west-2)
+     Backend: S3 with DynamoDB locking
+     Modules: 8 local, 3 registry
+     Environments: dev, staging, prod (directory-per-env)
+     State files: 3 (one per environment)
+   ```
+
+---
+
+### Phase 2: ANALYZE -- Evaluate Patterns and Anti-Patterns
+
+1. **Check state management.** Verify state is properly configured:
+   - Remote backend with locking (not local state for shared infrastructure)
+   - State encryption at rest enabled
+   - State file does not contain secrets in plain text
+   - State is segmented per environment (no single state file for all environments)
+   - Backend configuration uses variables, not hardcoded values
+
+2. **Evaluate module design.** Check modules for:
+   - Single responsibility (one module does one thing)
+   - Input validation (variable validation blocks or type constraints)
+   - Output completeness (downstream consumers can get what they need)
+   - No hardcoded values that should be variables
+   - README or documentation for each module
+   - Consistent naming conventions across modules
+
+3. **Check resource naming and tagging.** Verify:
+   - Resources follow a consistent naming convention (e.g., `{project}-{env}-{resource}`)
+   - Required tags are present on all taggable resources (environment, team, cost-center)
+   - Tag values are consistent (no mix of "prod" and "production")
+   - Names do not contain environment-specific values in shared modules
+
+4. **Analyze dependency management.** Check for:
+   - Provider version constraints (required_providers block)
+   - Module version pinning (exact version or range)
+   - Lock file committed to version control
+   - No circular dependencies between modules
+   - Implicit dependencies are made explicit with depends_on where needed
+
+5. **Check for common anti-patterns:**
+   - Monolithic root modules (everything in one configuration)
+   - Hardcoded AMI IDs, account numbers, or region values
+   - Resources created outside of IaC (drift risk)
+   - Overly permissive IAM policies (wildcards on actions or resources)
+   - Missing lifecycle rules (prevent_destroy on critical resources)
+
+---
+
+### Phase 3: DESIGN -- Recommend Structure and Patterns
+
+1. **Recommend module decomposition.** If monolithic configurations are detected:
+   - Propose a module hierarchy based on service boundaries
+   - Separate networking, compute, storage, and security into distinct modules
+   - Design shared modules for common patterns (e.g., tagged S3 bucket, VPC)
+   - Provide module interface design (inputs, outputs)
+
+2. **Design state management strategy.** Recommend:
+   - One state file per environment per service
+   - Remote backend with encryption and locking
+   - State import plan for any resources created outside IaC
+   - Cross-state data sharing via `terraform_remote_state` or SSM parameters
+
+3. **Recommend drift detection workflow.** Design a process to catch manual changes:
+   - Scheduled `terraform plan` in CI to detect drift
+   - Alert on any planned changes that were not initiated by a PR
+   - Runbook for reconciling detected drift (import vs. revert)
+   - Tag resources as IaC-managed for auditability
+
+4. **Design environment promotion.** Recommend a workflow for infrastructure changes:
+   - Changes applied to dev first, then promoted to staging, then production
+   - Variable files per environment with appropriate overrides
+   - Approval gates before production applies
+   - Plan output reviewed as part of PR process
+
+5. **Recommend security hardening.** For each provider:
+   - Least-privilege IAM roles for IaC execution
+   - No inline policies (use managed policies or policy documents)
+   - Encryption enabled by default on all storage resources
+   - Network security groups with explicit deny rules
+   - Sensitive variables marked with `sensitive = true`
+
+---
+
+### Phase 4: VALIDATE -- Verify Configuration Correctness
+
+1. **Run static analysis.** Execute available validation tools:
+   - Terraform: `terraform validate`, `terraform fmt -check`
+   - CloudFormation: `cfn-lint` or `aws cloudformation validate-template`
+   - Pulumi: type checking via the chosen language runtime
+   - CDK: `cdk synth` to verify template generation
+   - General: `tflint`, `checkov`, or `tfsec` for security checks
+
+2. **Verify variable completeness.** For each root module:
+   - All declared variables have descriptions
+   - Required variables have no default values
+   - Optional variables have sensible defaults
+   - Variable types are specific (not `any`)
+   - Validation blocks exist for constrained values (e.g., allowed regions)
+
+3. **Check plan safety.** If a plan output is available:
+   - No unexpected resource deletions
+   - No changes to resources marked with `prevent_destroy`
+   - Replacements are expected (not caused by force-new arguments)
+   - Plan matches the intended change described in the PR
+
+4. **Verify security posture.** Run security-focused checks:
+   - No public S3 buckets or storage accounts
+   - No security groups allowing 0.0.0.0/0 on sensitive ports
+   - Encryption enabled on RDS, EBS, S3, and other storage
+   - IAM policies follow least privilege
+   - No credentials or secrets in variable defaults or outputs
+
+5. **Generate validation report:**
+
+   ```
+   IaC Validation: [PASS/WARN/FAIL]
+
+   Format check: PASS (all files formatted)
+   Validate: PASS (no syntax errors)
+   Security scan: WARN (2 findings)
+     - modules/storage/main.tf: S3 bucket missing server-side encryption
+     - modules/network/main.tf: security group allows 0.0.0.0/0 on port 22
+   Module design: WARN (3 modules missing input validation)
+   State management: PASS (remote backend with locking)
+
+   Recommendations:
+     1. Add aws_s3_bucket_server_side_encryption_configuration resource
+     2. Restrict SSH access to VPN CIDR range
+     3. Add variable validation blocks to network, compute, and storage modules
+   ```
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-infrastructure-as-code`** -- Primary invocation for IaC analysis.
+- **`harness validate`** -- Run after configuration changes to verify project health.
+- **`harness check-deps`** -- Verify IaC tool dependencies are installed.
+- **`emit_interaction`** -- Present design recommendations and gather decisions on module structure.
+
+## Success Criteria
+
+- IaC tooling, provider, and backend are correctly identified
+- Module structure is mapped with dependency relationships
+- State management is verified as remote, encrypted, and locked
+- Resource naming and tagging follow consistent conventions
+- Security posture is evaluated with no critical findings unaddressed
+- Static analysis tools pass without errors
+
+## Examples
+
+### Example: Terraform AWS Multi-Environment Setup
+
+```
+Phase 1: DETECT
+  Tool: Terraform v1.6.4
+  Provider: AWS (hashicorp/aws ~> 5.0)
+  Backend: S3 (us-east-1) with DynamoDB locking
+  Modules: 5 local (vpc, ecs, rds, s3, iam), 2 registry (datadog, cloudwatch)
+  Environments: dev, staging, prod (directory-per-env with shared modules)
+
+Phase 2: ANALYZE
+  State management: PASS (remote, encrypted, locked, per-env)
+  Module design: WARN
+    - modules/ecs has 450 lines -- recommend splitting into ecs-cluster
+      and ecs-service modules
+    - modules/rds missing variable validation for instance_class
+  Naming: PASS (consistent {project}-{env}-{resource} pattern)
+  Tags: WARN (cost-center tag missing on 3 resources)
+  Anti-patterns: 1 hardcoded AMI in modules/ecs/main.tf
+
+Phase 3: DESIGN
+  1. Split modules/ecs into ecs-cluster and ecs-service
+  2. Add data source for AMI lookup instead of hardcoded value
+  3. Add variable validation: instance_class must be db.t3.* or db.r6g.*
+  4. Add cost-center tag to default_tags in provider configuration
+  5. Add scheduled terraform plan for drift detection in CI
+
+Phase 4: VALIDATE
+  terraform fmt: PASS
+  terraform validate: PASS
+  tfsec: WARN (2 findings -- see above)
+  checkov: PASS
+  Result: WARN -- 5 improvements recommended, no blocking issues
+```
+
+### Example: CloudFormation with CDK
+
+```
+Phase 1: DETECT
+  Tool: AWS CDK v2.120 (TypeScript)
+  Provider: AWS (us-west-2)
+  Backend: CloudFormation (managed by CDK)
+  Stacks: 3 (NetworkStack, ComputeStack, StorageStack)
+  Environments: dev and prod via CDK context
+
+Phase 2: ANALYZE
+  Stack design: PASS (clean separation by concern)
+  Cross-stack references: PASS (using CfnOutput and Fn::ImportValue)
+  Security: WARN
+    - ComputeStack: EC2 instance has public IP and open SSH
+    - StorageStack: DynamoDB table missing point-in-time recovery
+  CDK constructs: Using L2 constructs (good -- higher abstraction)
+
+Phase 3: DESIGN
+  1. Add bastion host pattern instead of direct SSH to EC2
+  2. Enable point-in-time recovery on DynamoDB table
+  3. Add cdk-nag for automated security checks in synthesis
+  4. Add stack-level tags via Tags.of(stack).add()
+
+Phase 4: VALIDATE
+  cdk synth: PASS (3 templates generated)
+  cfn-lint: PASS (all templates valid)
+  Security: WARN (2 findings)
+  Result: WARN -- 2 security improvements needed
+```
+
+## Gates
+
+- **No local state for shared infrastructure.** Terraform configurations managing shared resources must use a remote backend with locking. Local state is blocking for any non-experimental configuration.
+- **No unpinned provider versions.** Provider version constraints must be explicit. Using `>=` without an upper bound or omitting version constraints entirely is a blocking finding.
+- **No public access to sensitive resources.** S3 buckets, databases, or storage accounts with public access enabled are blocking security findings.
+- **No credentials in IaC files.** Hardcoded access keys, passwords, or tokens in Terraform variables, CloudFormation parameters, or Pulumi configuration are blocking findings.
+
+## Escalation
+
+- **When state is corrupted or diverged:** Do not attempt automatic recovery. Report the state of divergence, recommend `terraform state pull` for backup, and advise manual reconciliation with a plan review before any apply.
+- **When resources exist outside IaC management:** Recommend a phased import strategy. Provide `terraform import` commands for each resource and note that import does not generate configuration -- the HCL must be written manually.
+- **When module versions are significantly outdated:** Present the version gap and changelog summary. If breaking changes exist, recommend a separate PR for the upgrade with a plan review before applying.
+- **When IaC tool version conflicts exist between team members:** Recommend pinning the tool version in `.terraform-version` (tfenv) or `Pulumi.yaml` and adding version checks to CI.

package/dist/agents/skills/codex/harness-infrastructure-as-code/skill.yaml

@@ -0,0 +1,80 @@
+name: harness-infrastructure-as-code
+version: "1.0.0"
+description: Terraform, CloudFormation, Pulumi patterns and IaC best practices
+cognitive_mode: advisory-guide
+tier: 3
+internal: false
+keywords:
+  - Terraform
+  - CloudFormation
+  - Pulumi
+  - IaC
+  - infrastructure
+  - HCL
+  - CDK
+  - AWS
+  - GCP
+  - Azure
+  - state
+  - module
+  - provider
+  - resource
+stack_signals:
+  - "*.tf"
+  - "terraform/"
+  - "cloudformation/"
+  - "*.template.yaml"
+  - "*.template.json"
+  - "Pulumi.yaml"
+  - "cdk.json"
+  - "infrastructure/"
+triggers:
+  - manual
+  - on_new_feature
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-infrastructure-as-code
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: provider
+      description: Cloud provider context (aws, gcp, azure)
+      required: false
+    - name: tool
+      description: IaC tool to focus on (terraform, cloudformation, pulumi, cdk)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-infrastructure-as-code
+    path: string
+type: rigid
+phases:
+  - name: detect
+    description: Identify IaC tool, provider, and module structure
+    required: true
+  - name: analyze
+    description: Evaluate resource definitions, state management, and module patterns
+    required: true
+  - name: design
+    description: Recommend module decomposition, naming, and drift prevention
+    required: true
+  - name: validate
+    description: Verify configuration correctness and security posture
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/harness-integration-test/SKILL.md

@@ -0,0 +1,271 @@
+# Harness Integration Test
+
+> Service boundary testing, API contract verification, and consumer-driven contract validation. Ensures services communicate correctly without requiring full end-to-end infrastructure.
+
+## When to Use
+
+- Testing API endpoints with real HTTP requests against a running service
+- Validating consumer-driven contracts between microservices (Pact, Spring Cloud Contract)
+- Verifying database interactions through repository or data access layers
+- NOT when testing pure business logic with no I/O (use unit tests or harness-tdd instead)
+- NOT when testing full user flows through a browser (use harness-e2e instead)
+- NOT when performing load or stress testing on APIs (use harness-load-testing instead)
+
+## Process
+
+### Phase 1: DISCOVER -- Map Service Boundaries and Dependencies
+
+1. **Identify service boundaries.** Scan the project structure for:
+   - API route definitions (Express routers, FastAPI endpoints, Spring controllers, Go HTTP handlers)
+   - Service client code (HTTP clients, gRPC stubs, message queue publishers/consumers)
+   - Shared type definitions or API schemas (OpenAPI specs, proto files, GraphQL schemas)
+
+2. **Map inter-service dependencies.** For each service, catalog:
+   - Upstream dependencies: services this service calls
+   - Downstream consumers: services that call this service
+   - Shared resources: databases, message queues, caches
+
+3. **Inventory existing integration tests.** Glob for test files in `tests/integration/`, `__integration__/`, `tests/api/`, and `contract-tests/`. Classify by type:
+   - API tests: send HTTP requests and assert responses
+   - Contract tests: verify provider/consumer agreements
+   - Repository tests: test data access against a real database
+
+4. **Identify coverage gaps.** Cross-reference discovered endpoints and service boundaries against existing tests. Flag untested:
+   - API endpoints with no request/response validation
+   - Service boundaries with no contract tests
+   - Error scenarios (4xx responses, timeout handling, retry behavior)
+
+5. **Select test strategy.** Based on the architecture:
+   - Monolith: API tests with supertest/httptest against the running application
+   - Microservices: consumer-driven contract tests with Pact plus API tests per service
+   - Event-driven: message contract tests plus async handler integration tests
+
+### Phase 2: MOCK -- Configure Test Doubles and Infrastructure
+
+1. **Set up test database.** Choose the appropriate strategy:
+   - **Testcontainers:** Spin up a real database in Docker for each test suite. Preferred for PostgreSQL, MySQL, MongoDB.
+   - **In-memory database:** SQLite in-memory for lightweight tests. Only when schema compatibility is confirmed.
+   - **Transaction rollback:** Wrap each test in a transaction and roll back. Fast but requires careful connection management.
+
+2. **Configure mock services for external dependencies.** For each upstream dependency:
+   - Create a mock server using the framework's built-in tools (Pact mock, WireMock, nock, MSW)
+   - Define request/response pairs from the API contract or OpenAPI spec
+   - Configure realistic error responses (500, 503, timeout) for error path testing
+
+3. **Set up contract broker (if using Pact).** Configure:
+   - Pact broker URL and authentication
+   - Consumer and provider version tagging strategy
+   - Webhook configuration for provider verification on deploy
+
+4. **Create test fixtures and seed data.** Generate:
+   - Database seed scripts for required reference data
+   - Request/response fixtures for common API payloads
+   - Factory functions for building test entities with sensible defaults
+
+5. **Verify mock infrastructure starts.** Run a smoke test that:
+   - Starts the test database and confirms connectivity
+   - Starts mock services and confirms they respond
+   - Seeds baseline data and confirms it is queryable
+
+### Phase 3: IMPLEMENT -- Write Integration Tests
+
+1. **Write API endpoint tests.** For each endpoint, test:
+   - Happy path: valid request returns expected response with correct status code and body
+   - Validation: invalid input returns 400 with descriptive error messages
+   - Authentication: unauthenticated requests return 401, unauthorized return 403
+   - Not found: requests for non-existent resources return 404
+   - Edge cases: empty collections, pagination boundaries, large payloads
+
+2. **Write consumer-driven contract tests (when applicable).** For each consumer-provider pair:
+   - Consumer side: define interactions (request/response pairs) the consumer expects
+   - Provider side: verify the provider satisfies all consumer contracts
+   - Use Pact matchers for flexible verification (type matching, regex, array-like)
+
+3. **Write repository/data access tests.** For each data access layer:
+   - CRUD operations with valid data
+   - Constraint violations (unique, foreign key, not-null)
+   - Query correctness (filters, sorting, pagination)
+   - Transaction behavior (isolation, rollback on error)
+
+4. **Write error handling and resilience tests.** Verify:
+   - Timeout behavior: service responds within SLA when dependency is slow
+   - Retry logic: transient failures trigger retries with backoff
+   - Circuit breaker: repeated failures open the circuit and return fallback
+   - Graceful degradation: partial dependency failure does not crash the service
+
+5. **Organize tests by execution speed.** Tag or separate:
+   - Fast integration tests (in-memory mocks, < 5 seconds): run on every commit
+   - Slow integration tests (testcontainers, external services, > 5 seconds): run on PR
+
+### Phase 4: VALIDATE -- Execute and Verify Contract Compliance
+
+1. **Run the full integration test suite.** Execute all tests with verbose output. Collect:
+   - Pass/fail counts per test category (API, contract, repository)
+   - Execution time per test and per suite
+   - Any tests that require external services to be running
+
+2. **Verify contract compliance.** If using Pact:
+   - Publish consumer pacts to the broker
+   - Run provider verification against published pacts
+   - Confirm the can-i-deploy check passes for the target environment
+
+3. **Validate test isolation.** Run tests in random order (if the framework supports it). Any test that fails only when run after a specific other test has a shared-state bug. Fix immediately.
+
+4. **Run `harness validate`.** Confirm the project passes all harness checks including the new integration test infrastructure.
+
+5. **Generate coverage report.** Summarize:
+   - Endpoints tested vs. total endpoints discovered
+   - Contract coverage: consumer-provider pairs with verified contracts
+   - Error scenarios covered vs. identified
+   - Recommended next steps for remaining gaps
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+## Harness Integration
+
+- **`harness validate`** -- Run in VALIDATE phase after all integration tests are implemented. Confirms project-wide health.
+- **`harness check-deps`** -- Run after MOCK phase to verify test infrastructure dependencies do not leak into production bundles.
+- **`emit_interaction`** -- Used at checkpoints to present contract verification results and coverage gaps to the human.
+- **Grep** -- Used in DISCOVER phase to find route definitions, HTTP client usage, and service boundary patterns.
+- **Glob** -- Used to catalog existing integration tests and contract files.
+
+## Success Criteria
+
+- Every API endpoint has at least one integration test covering the happy path
+- Every consumer-provider boundary has a verified contract (when using microservices)
+- Error scenarios (400, 401, 403, 404, 500, timeout) are tested for all public endpoints
+- All integration tests pass with test doubles -- no dependency on external staging environments for CI
+- Test isolation is verified: tests pass in any execution order
+- `harness validate` passes with the integration test suite in place
+
+## Examples
+
+### Example: Express API with Supertest and Testcontainers
+
+**DISCOVER output:**
+
+```
+Framework: Express 4.18 with TypeScript
+Database: PostgreSQL via Prisma
+Endpoints: 14 routes across 4 controllers (users, projects, tasks, auth)
+Existing tests: 3 integration tests in tests/integration/ (auth only)
+Coverage gaps: projects CRUD, tasks filtering, user profile update
+```
+
+**IMPLEMENT -- API endpoint test with supertest:**
+
+```typescript
+// tests/integration/projects.test.ts
+import request from 'supertest';
+import { app } from '../../src/app';
+import { prisma } from '../../src/db';
+import { createTestUser, generateAuthToken } from '../helpers/auth';
+
+describe('POST /api/projects', () => {
+  let authToken: string;
+
+  beforeAll(async () => {
+    const user = await createTestUser(prisma);
+    authToken = generateAuthToken(user.id);
+  });
+
+  afterAll(async () => {
+    await prisma.project.deleteMany();
+    await prisma.user.deleteMany();
+  });
+
+  it('creates a project with valid data', async () => {
+    const response = await request(app)
+      .post('/api/projects')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ name: 'Test Project', description: 'Integration test' });
+
+    expect(response.status).toBe(201);
+    expect(response.body).toMatchObject({
+      name: 'Test Project',
+      description: 'Integration test',
+    });
+    expect(response.body.id).toBeDefined();
+  });
+
+  it('returns 400 when name is missing', async () => {
+    const response = await request(app)
+      .post('/api/projects')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ description: 'No name' });
+
+    expect(response.status).toBe(400);
+    expect(response.body.errors).toContainEqual(expect.objectContaining({ field: 'name' }));
+  });
+
+  it('returns 401 without auth token', async () => {
+    const response = await request(app).post('/api/projects').send({ name: 'Unauthorized' });
+
+    expect(response.status).toBe(401);
+  });
+});
+```
+
+### Example: Pact Consumer-Driven Contract Test
+
+**IMPLEMENT -- Consumer side (frontend):**
+
+```typescript
+// contract-tests/consumer/project-service.pact.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { ProjectClient } from '../../src/clients/project-client';
+
+const { like, eachLike, uuid } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'Dashboard',
+  provider: 'ProjectService',
+});
+
+describe('ProjectService contract', () => {
+  it('returns a list of projects', async () => {
+    await provider
+      .given('projects exist for user')
+      .uponReceiving('a request for user projects')
+      .withRequest({
+        method: 'GET',
+        path: '/api/projects',
+        headers: { Authorization: like('Bearer token-123') },
+      })
+      .willRespondWith({
+        status: 200,
+        body: eachLike({
+          id: uuid(),
+          name: like('Project Alpha'),
+          createdAt: like('2026-01-15T10:30:00Z'),
+        }),
+      })
+      .executeTest(async (mockServer) => {
+        const client = new ProjectClient(mockServer.url);
+        const projects = await client.listProjects('token-123');
+        expect(projects).toHaveLength(1);
+        expect(projects[0].name).toBe('Project Alpha');
+      });
+  });
+});
+```
+
+## Gates
+
+- **No integration tests that require external staging environments for CI.** Every integration test must run with local test doubles (mocks, containers, in-memory databases). Tests that fail without a staging VPN are not integration tests -- they are environment tests.
+- **No shared mutable state between tests.** Each test must set up and tear down its own data. If tests fail when run in random order, shared state exists. Fix it before proceeding.
+- **No testing implementation details.** Integration tests assert on API contracts (status codes, response shapes, headers) and observable data changes -- not on internal function calls or database column values that are not part of the public contract.
+- **Contract changes must be coordinated.** If a provider contract test reveals a breaking change, do not silently update the consumer expectation. Flag it as a coordination point between teams.
+
+## Escalation
+
+- **When a service dependency has no API documentation or schema:** Cannot write accurate contract tests without knowing the contract. Escalate to the dependency team to provide an OpenAPI spec, proto file, or at minimum a Pact broker with published contracts.
+- **When Testcontainers fails in CI (Docker-in-Docker issues, resource limits):** Fall back to in-memory alternatives where possible. For databases that have no in-memory mode, escalate to DevOps to configure CI runners with Docker support.
+- **When contract verification fails on the provider side:** This indicates a real incompatibility between consumer expectations and provider implementation. Do not adjust the consumer test to match the provider bug. Escalate to the provider team with the failing interaction details.
+- **When integration tests exceed 5 minutes for a single service:** Triage by separating fast tests (mocked dependencies) from slow tests (testcontainers). Run fast tests on every commit, slow tests on PR only.