Process: define-flow produces isolated bounded contexts with no inter-context integration features — ACL/port implementation gap

[nullhack]

Problem

The define-flow process (interview → domain spec → simulation → feature refinement) produces one .feature file per bounded context. Each feature specifies the behavior within that context. But the context map describes relationships between contexts (triggers, calls, feeds), and none of those relationships become feature files.

The result: every bounded context is internally correct and fully tested in isolation, but no code exists to connect them. Ports are defined but never implemented. Adapters produce different entity types than the domain expects. The Anti-Corruption Layer — the translation between them — is never specified as a feature, so it is never built.

Why This Happens

The flow treats each bounded context as a silo:

1. interview → discovers contexts
2. create-domain-spec → specifies each context independently
3. simulate-spec → walks through each context in isolation
4. refine-features → produces one .feature per context

The context map (docs/spec/contexts/context_map.md) documents inter-context relationships, but it is a passive artifact — it never drives feature generation. No state in define-flow or develop-flow says: "for every edge on the context map, produce a feature that specifies the translation."

Industry Context

This is a well-documented gap in DDD adoption:

• Eric Evans (DDD, 2003, Ch. 14): The Anti-Corruption Layer is a first-class artifact that "translates in one or both directions as necessary between the two models." It is not optional — it is the mechanism that makes bounded contexts work together.

• Vlad Khononov (Learning DDD, 2021, Ch. 4): "Splitting your system into bounded contexts fixes only half the problem. Those contexts still have to work together as one product." The integration patterns (ACL, OHS, Shared Kernel, Conformist) must be chosen deliberately and implemented explicitly.

• Prickles Tenet A6 (2026): "Cross-context use goes through one named Anti-Corruption Layer per pair of contexts; nowhere else does the translation." The rule is lintable: import/no-restricted-paths enforces that cross-context imports go through the ACL.

• NILUS (Integration Test Topology, 2025): "I prefer event storming or context mapping as input to test design. The integration topology should be derived from domain interactions, not from whatever frameworks the teams happen to use." The context map should drive integration features.

• Consumer-Driven Contract Testing (Pact, Spring Cloud Contract): The established pattern for verifying inter-context compatibility. Contracts verify not just shape but semantics.

What Is Missing in the Flow

1. Context map edges do not generate features

The context map describes relationships like:

MARKET_DATA --calls--> HYPERLIQUID_ADAPTER
MARKET_DATA --calls--> YFINANCE_ADAPTER
SCHEDULER --triggers--> MARKET_DATA

None of these edges produce a feature file. The flow should treat every edge as a required deliverable.

2. Port implementations have no feature specification

Hexagonal architecture defines ports (interfaces) in the domain and adapters (implementations) at the boundary. The template correctly produces ports. But the concrete adapter — the class that implements ExchangeAdapterPort by calling HyperliquidAdapter and translating between their entity types — has no feature file, no BDD scenarios, no tests.

3. No integration test category

All tests are unit-level logic tests with mocks. No test category exercises the full path: domain service → port → adapter implementation → external system (or captured fixture). The testing pyramid has only the base (domain unit tests). The middle (adapter contract tests) and top (full-stack wiring tests) are missing.

4. No entity type compatibility verification

When two bounded contexts define entities with the same name but different structures (e.g., Candle with market_id: str vs Candle with market: MarketId), nothing detects this mismatch until integration time — which never comes.

Proposed Solutions

Flow Changes

1. Add integration-features state to define-flow. After refine-features produces per-context features, a new state inspects the context map and generates one .feature file per inter-context edge. These features specify:

   • The translation between entity types (ACL)
   • The contract the consumer expects from the provider
   • The error propagation across the boundary

2. Add port-implementation to develop-flow. After each bounded context is developed, the flow selects the next integration feature (the ACL/port implementation) and runs a TDD cycle against it. This ensures the glue code is tested, reviewed, and accepted just like any other feature.

3. Add cross-context import linting. Add an import/no-restricted-paths rule (or equivalent) that makes direct cross-context imports a build failure. All integration must go through the ACL.

Skill Changes

4. Add generate-integration-features skill. Reads the context map, identifies all edges, and produces stub .feature files for each ACL/port implementation. The SA/DE agent runs this during define-flow.

5. Add contract-test skill. For each ACL feature, generates consumer-driven contract tests that verify the translation between provider and consumer entity types.

6. Extend review-gate skill. Add a check: "Does every edge on the context map have a corresponding integration feature with passing tests?" If not, FAIL.

7. Extend accept-feature skill. Add a check: "Can the calling context actually invoke the provider through the ACL?" Verify the wiring, not just the traceability.

Process Changes

8. Entity name collision detection. When refine-features produces features, scan for identically-named entities across contexts. If Candle exists in both market_data and hyperliquid_adapter, flag it and require an ACL feature that translates between them.

9. Walking skeleton gate. Before any bounded context enters develop-flow, verify that at least one integration feature exists for each of its context map edges. No integration feature = no development.

10. Separate test categories. task test for unit tests (mocked, fast). task test-integration for adapter contract tests (real fixtures or captured responses). task test-e2e for full-stack wiring tests (1–2 per use case). All three must pass before merge.

Verification

After implementing these changes:

• ls docs/features/ should show integration features (e.g., exchange_adapter_integration.feature) alongside per-context features
• ls tests/features/ should show corresponding test directories
• beehave status --json should show integration scenarios with status "ok"
• Cross-context imports should fail linting (except through ACL modules)
• Entity name collisions should be detected and flagged during define-flow
• task test-integration should pass with real fixture data

Relationship to #178

#178 identifies the symptom: "all tests pass but nothing works end-to-end." This issue identifies the structural root cause: the flow has no mechanism to produce integration features from the context map. Fixing #178 without fixing this would add an integration gate but still leave teams without guidance on what to build for integration. This issue provides the missing feature-generation step.