initiative/.specify/memory/constitution.md

<!--
  Sync Impact Report
  ───────────────────
  Version change: 1.0.2 → 1.0.3 (PATCH — add merge-gate rule)
  Modified sections:
    - Development Workflow: added automated-checks merge gate
  Templates requiring updates:
    - .specify/templates/plan-template.md        ✅ no update needed
    - .specify/templates/spec-template.md         ✅ no update needed
    - .specify/templates/tasks-template.md        ✅ no update needed
  Follow-up TODOs: none
-->
# Encounter Console Constitution

## Core Principles

### I. Deterministic Domain Core

All domain logic MUST be implemented as pure state transitions.
Given the same input state and action, the output state MUST be
identical across runs. Side effects (I/O, randomness, clocks) MUST
be injected at the boundary, never sourced inside the domain layer.

- State transitions MUST be expressed as pure functions.
- Random values (e.g., dice rolls) MUST be passed in as resolved
  inputs, not generated within the domain.
- Domain functions MUST NOT depend on wall-clock time, network, or
  filesystem.

### II. Layered Architecture

The codebase MUST be organized into four layers with strict
dependency direction:

1. **Domain** — pure types, state transitions, validation rules.
   No imports from other layers.
2. **Application** — orchestrates domain operations, manages
   workflows, coordinates use cases. Application defines port
   interfaces that Adapters implement. May import Domain only.
3. **Adapters** — I/O, persistence, UI rendering, external APIs.
   May import Application and Domain.
4. **Agent** — AI-assisted features (suggestions, analysis).
   May import Application and Domain as read-only consumers.

A module in an inner layer MUST NOT import from an outer layer.

### III. Agent Boundary

The agent layer MAY read domain events and current state. The agent
MAY produce suggestions, annotations, or recommendations. The agent
MUST NOT mutate domain state directly. All agent-originated changes
MUST flow through the Application layer as explicit user-confirmed
commands.

- Agent output MUST be clearly labeled as suggestions.
- No silent or automatic application of agent recommendations.

### IV. Clarification-First

Before making any non-trivial assumption during specification,
planning, or implementation, the agent MUST surface a clarification
question to the user. "Non-trivial" means any decision that would
alter observable behavior, data model shape, or public API surface.
The agent MUST also ask when multiple valid interpretations exist,
when a choice would affect architectural layering, or when scope
would expand beyond the current spec. The agent MUST NOT silently
choose among valid alternatives.

### V. Escalation Gates

Any feature, requirement, or scope change not present in the current
spec MUST be rejected at implementation time until the spec is
explicitly updated. The workflow is:

1. Identify the out-of-scope item.
2. Document it as a proposal.
3. Update the spec via `/speckit.specify` or `/speckit.clarify`.
4. Only then proceed with implementation.

### VI. MVP Baseline Language

Constraints in this constitution and in specs MUST use MVP baseline
language ("MVP baseline does not include X") rather than permanent
architectural bans ("X is forbidden"). This preserves the option to
add capabilities in future iterations without constitutional
amendment. The current MVP baseline is local-first and single-user;
this is a starting scope, not a permanent restriction.

### VII. No Gameplay Rules in Constitution

This constitution MUST NOT contain concrete gameplay mechanics,
rule-system specifics, or encounter resolution logic. Such details
belong in feature specs. The constitution governs process,
architecture, and quality — not product behavior.

## Scope Constraints

- The Encounter Console's primary focus is initiative tracking and
  encounter state management. Adjacent capabilities (e.g., richer
  game-engine features) are not in the MVP baseline but may be
  added via spec updates in future iterations.
- Technology choices, UI framework, and storage mechanism are
  spec-level decisions, not constitutional mandates.
- Testing strategy (unit, integration, contract) is determined per
  feature spec; the constitution requires only that domain logic
  remains testable via pure-function assertions.

## Development Workflow

- No change may be merged unless all automated checks (tests and
  static analysis as defined by the project) pass.
- Every feature begins with a spec (`/speckit.specify`).
- Implementation follows the plan → tasks → implement pipeline.
- Domain logic MUST be testable without mocks for external systems.
- Long-running or multi-step state transitions SHOULD be verifiable
  through reproducible event logs or snapshot-style tests.
- Commits SHOULD be atomic and map to individual tasks where
  practical.
- Layer boundary compliance MUST be verified by automated import
  rules or architectural tests. Agent-assisted or manual review MAY
  supplement but not replace automated checks.

## Governance

This constitution is the highest-authority document for the
Encounter Console project. All specs, plans, and implementations
MUST comply with its principles.

**Amendment procedure**:
1. Propose change with rationale.
2. Update constitution via `/speckit.constitution`.
3. Verify downstream template compatibility (Sync Impact Report).
4. A human maintainer MUST review and commit the update before
   ratification takes effect.
5. Commit with version bump.

**Versioning policy**: MAJOR.MINOR.PATCH per semantic versioning.
- MAJOR: principle removal or backward-incompatible redefinition.
- MINOR: new principle or materially expanded guidance.
- PATCH: clarification, typo, or non-semantic refinement.

**Compliance review**: Every spec and plan MUST include a
Constitution Check section validating adherence to all principles.

**Version**: 1.0.3 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-03