integrate

name	integrate
description	Derive integration tests from existing unit test xfails and UNSPECIFIED stubs. Uses integration-from-stub formula: catalog → review → triage → architect → write-integration → fix-green → reconcile-xfail → verify → commit. Each stub's expected behavior is the core invariant. Architect atom reads 7 architecture docs and cross-references against CRIT-1..CRIT-11 findings.
args	<entity-name-1> [entity-name-2] ...

Integration Tests from Stubs

Derive integration tests from existing unit test xfails (Bucket A: "requires real DB") and UNSPECIFIED stubs that exercise DB-dependent paths. Each stub's expected behavior is absolute truth — if the integration test fails, fix production code, never adjust the expected behavior.

Args

/integrate <entity-name-1> [entity-name-2] ...

Entity names (space-separated): creative, media-buy, delivery. Each must already have a unit test suite from /surface.

Hard Gate: Pre-Check

The catalog atom checks if tests/unit/test_{entity}.py exists. If not:

┌──────────────────────────────────────────────────────────┐
│  STOP: No entity test suite for {entity}.                │
│                                                          │
│  Run `/surface {entity}` first to create the             │
│  test surface map with obligations and stubs.            │
│                                                          │
│  Integration tests derive from the surface — no surface, │
│  nothing to derive from.                                 │
└──────────────────────────────────────────────────────────┘

Protocol

Step 1: Cook the molecule

python3 .claude/scripts/cook_formula.py \
  --formula .claude/formulas/integration-from-stub.yaml \
  --var "ENTITY_NAMES={all_args}" \
  --epic-title "Integrate: {all_args}"

Dry run first (recommended):

python3 .claude/scripts/cook_formula.py \
  --formula .claude/formulas/integration-from-stub.yaml \
  --var "ENTITY_NAMES={all_args}" \
  --epic-title "Integrate: {all_args}" \
  --dry-run

Step 2: Walk the molecule

bd ready → bd show <atom-id> → read description → execute → bd close <atom-id> → repeat

Each entity goes through 9 atoms:

catalog → review → triage → architect → write-integration → fix-green → reconcile-xfail → verify → commit

Barrier serialization: Entities execute in parallel within each atom phase, but write-integration waits for ALL entities' commit from the previous barrier (if any) to complete. This prevents merge conflicts.

Step 3: Done when all atoms closed

All entities committed. Finalize atom runs ./run_all_tests.sh and reports remaining xfails.

Atom Details

#	Atom	What It Does
1	catalog	Read unit test suite, classify xfails into Bucket A (needs DB) vs B (not implemented), select batch
2	review	Verify stub fidelity, fixture design, batch scope, no duplicates with existing integration tests
3	triage	Route: ALL_LOW → proceed, NEEDS_REFINEMENT → adjust, NEEDS_USER_INPUT → block
4	architect	Read 7 architecture docs, trace code paths per test, map layer boundaries, document violations as FINDINGs, design fixtures and adapter mocking strategy
5	write-integration	Create tests/integration/test_{entity}_v3.py following the architect plan exactly
6	fix-green	Fix production code for failing integration tests (stub is truth, code is wrong)
7	reconcile-xfail	Remove xfails for tests now covered by passing integration tests
8	verify	make quality + integration tests pass + xfail count reconciled
9	commit	Commit integration tests + production fixes

The Architect Atom (Why It Matters)

The architect atom is the key differentiator from regular /remediate. It:

1. Reads documented architecture — 7 specific documents define the layer boundaries, error handling contracts, and data flow expectations
2. Traces real code paths — for each stub, maps wrapper → _impl → DB → adapter
3. Cross-references CRIT findings — checks if the code path touches any of the 11 critical issues from the migration review
4. Documents violations — uses FINDING format when existing code violates architecture, rather than silently encoding broken behavior into tests
5. Does NOT copy patterns — "match existing patterns" is explicitly forbidden. Existing code may violate the architecture.

Required Reading for Architect

1. CLAUDE.md — 9 critical patterns
2. docs/development/structural-guards.md — 6 AST-enforced invariants
3. archive/code-reviews/00-migration-summary.md — CRIT-1..CRIT-11
4. archive/code-reviews/01-schema-model-layer.md — schema constraints
5. archive/code-reviews/02-api-boundary-layer.md — boundary constraints
6. archive/code-reviews/04-adapter-layer.md — adapter contracts
7. docs/development/architecture.md — system architecture

Iron Rule: Stub Intent Is Absolute Truth

The unit test stub defines WHAT to test. The integration test verifies the SAME behavior with real PostgreSQL. If the integration test fails, the production code is wrong — not the stub.

Outcome	Action
Integration test passes	Behavior works end-to-end
Fails with AssertionError	Production code bug → fix in fix-green atom
Fails with setup error	Fixture needs work → fix the fixture
Code violates architecture	FINDING → discuss before encoding into test

NEVER adjust the expected behavior to match current code.

Anti-Patterns

• Don't skip the architect atom — it catches architecture violations that unit tests with mocks cannot see
• Don't copy existing integration test patterns blindly — verify they follow the architecture
• Don't design tests to match broken code — document as FINDING
• Don't combine write-integration and fix-green — tests must exist before fixes
• Don't include Bucket B xfails ("not yet implemented") — those need production code, handled by B2
• Don't over-fixture — module-scope for expensive setup, function-scope for test-specific state

See Also

• /surface — Create entity test suites (prerequisite)
• /verify-spec — Verify test expectations against AdCP spec (run after surface)
• /remediate — Fill unit test stubs (different from integration derivation)
• /mol-execute — Execute individual beads tasks
• /guard — Structural guards that protect the architecture