initiative/.specify/memory/constitution.md

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 three 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.

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

III. Clarification-First

Before making any non-trivial assumption during specification, planning, or implementation, Claude Code 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. Claude Code MUST also ask when multiple valid interpretations exist, when a choice would affect architectural layering, or when scope would expand beyond the current spec. Claude Code MUST NOT silently choose among valid alternatives.

IV. 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.

V. 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.

VI. 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., bestiary integration, richer game-engine features) may be added via spec updates.
• 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.
• All automated quality gates MUST run at the earliest feasible enforcement point (currently pre-commit via Lefthook). No gate may exist only as a CI step or manual process.
• When a feature adds, removes, or changes user-facing capabilities described in README.md, the README MUST be updated in the same change. Features that materially alter what the product does or how it is set up SHOULD also be reflected in the README.
• When a feature changes the tech stack, project structure, or architectural patterns documented in CLAUDE.md, the CLAUDE.md MUST be updated in the same change.

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: 2.2.1 | Ratified: 2026-03-03 | Last Amended: 2026-03-11