Skip to content

Language & Semantics Contract

Rule

  • Intent vs State:
  • Intent artefacts (AID) MUST align with system state (AEM), not reflect it

  • Reflection implies derivation; alignment implies coordination

  • Decision vs System State:

  • Architect decisions (architecture_work.status = accepted) are NOT system state

  • System state exists ONLY when governance.forum_status = accepted

  • Pattern Semantics:

  • Patterns MUST NOT be described as part of the system unless governance-approved

  • Pattern proposals and emerging patterns are NOT system state

  • Lifecycle Terminology:

  • Use "generate" for creation of artefacts
  • Use "persist" for storage of artefacts
  • Use "promote" ONLY when governance-approved transition occurs

  • Avoid ambiguous terms like "becomes" or "turns into" without lifecycle context

  • Consistency:

  • Use consistent terminology across AEM, AID, ADR, and alignment artefacts
  • Avoid semantic drift in repeated runs

Rationale

  • Ensures clear distinction between intent, decisions, and system state
  • Prevents semantic drift and misalignment across artefacts
  • Enables accurate traceability and accountability in architecture work
  • Facilitates effective governance and decision-making processes

Applies To

  • Architecture Intent Documents (AID)
  • Architecture Evolution Maps (AEM)
  • Architecture Decision Records (ADR)
  • Alignment Reports
  • Architecture Work items
  • Governance processes and forums

Example

  • An AID proposes a new pattern based on emerging requirements. The AID describes the pattern proposal and rationale but does NOT claim the pattern is part of the system until it goes through governance and is accepted. The AEM reflects the current state of the system, which does not include the proposed pattern until governance approval is obtained. Alignment reports identify the gap between intent and state but do not treat proposed patterns as system state.

Precedence

Global rules follow this hierarchy:

  • global > project > prompt-local

Notes

  • Rules are hard constraints on architecture work
  • Global rules cannot be violated by project rules
  • Rules should be testable/enforceable
  • Rule conflicts should be detected and resolved

See Also