Skip to content

Domain conventions

Common social/e-commerce/auth semantics often get re-derived in every Gherkin criterion or silently dropped. The convention registry encodes them as enumerated tags.

Declaring conventions

"domain_conventions": [
  "timeline_includes_self",
  "follow_asymmetric",
  "auth_session_single_active"
]

Each tag maps (in convention_to_invariant.py) to a Squib INVARIANT line the architect MUST surface verbatim. Today's registry covers ~9 common conventions; PRs welcome to add more.

Validation

The framework's validate_architecture_against_spec validator runs after the architect emits its Squib but before any ICP fires. Every declared domain_conventions tag must appear as an INVARIANTS line in the architecture; missing tags trigger an architect retry with violations appended.

query_semantics

Closely related: query_semantics declares the shape of a query a use case should produce. Without it the architect tends to pick the lowest-common-denominator (find_by_id, find_all); with it the architect picks the right shape.

"query_semantics": [
  {"use_case": "GetTimelineUseCase", "shape": "self_plus_followees"},
  {"use_case": "GetUnreadInboxUseCase", "shape": "time_windowed"}
]

Common shapes: self_plus_followees, paginated, time_windowed, all_public, by_natural_key.

entity_lifecycle

Explicit state-machine declarations stop the Entity ICP from conflating lifecycle invariants with construction invariants:

"entity_lifecycle": [
  {"entity": "Tweet", "transitions": ["draft -> published", "published -> deleted"]},
  {"entity": "Order", "transitions": ["pending -> paid -> shipped -> delivered"]}
]

See also