<!--
SYNC IMPACT REPORT
==================
Version change: 1.0.0 → 1.0.1 (Technical standards update)

Modified principles: None

Modified sections:
- Technical Standards: Python version 3.11+ → 3.14

Added sections: None
Removed sections: None

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
- .specify/templates/checklist-template.md: ✅ No update needed

Follow-up TODOs: None
-->

# XER MCP Server Constitution

## Core Principles

### I. Test-First Development (NON-NEGOTIABLE)

Test-Driven Development is mandatory for all feature implementation. Tests MUST be written and verified to fail before any implementation code is written.

**Requirements**:
- Red-Green-Refactor cycle strictly enforced
- Tests MUST fail before implementation begins
- No feature is complete until tests pass
- Contract tests required for all MCP tool endpoints
- Integration tests required for XER parsing workflows

**Rationale**: TDD ensures correctness, documents behavior, and prevents regressions. For an MCP server handling complex XER data, test coverage is essential to maintain reliability.

### II. Extensibility Architecture

The system MUST be designed for extension through well-defined interfaces and plugin points. Future capabilities MUST be addable without modifying core components.

**Requirements**:
- Core parsing logic separated from MCP transport layer
- XER table handlers MUST be pluggable
- New MCP tools MUST be addable without core changes
- Configuration MUST support extension points
- Abstract base classes MUST define extension contracts

**Rationale**: XER files contain many table types, and the MCP protocol evolves. Extensibility ensures the server can grow to handle new requirements without architectural rewrites.

### III. MCP Protocol Compliance

All MCP server implementations MUST strictly comply with the Model Context Protocol specification. Non-compliant behavior is a blocking defect.

**Requirements**:
- All tool definitions MUST include complete JSON schemas
- Error responses MUST follow MCP error format
- Resource URIs MUST follow MCP conventions
- Transport layer MUST handle all MCP message types
- Capability negotiation MUST be implemented correctly

**Rationale**: MCP clients expect compliant servers. Protocol deviations cause integration failures and break the fundamental contract with AI assistants.

### IV. XER Format Fidelity

XER file parsing MUST preserve data integrity and accurately represent Primavera P6 project data. No data loss or corruption is acceptable.

**Requirements**:
- All standard XER table types MUST be recognized
- Field mappings MUST match P6 export specifications
- Date/time values MUST preserve timezone information
- Numeric precision MUST be maintained
- Unknown tables MUST be preserved, not discarded

**Rationale**: XER files represent critical project schedules. Data loss or misinterpretation can have serious business consequences for construction and engineering projects.

### V. Semantic Versioning

All releases MUST follow Semantic Versioning (MAJOR.MINOR.PATCH). Breaking changes MUST increment MAJOR version and include migration guidance.

**Requirements**:
- MAJOR: Breaking API changes, removed MCP tools, incompatible schema changes
- MINOR: New features, new MCP tools, backward-compatible additions
- PATCH: Bug fixes, documentation, non-functional improvements
- Breaking changes MUST be documented with migration paths
- Deprecations MUST be announced one MINOR version before removal

**Rationale**: Consumers of MCP servers need predictable upgrade paths. SemVer provides clear expectations about compatibility and change impact.

## Technical Standards

**Language**: Python 3.14
**Type Checking**: Type hints MUST be used throughout; mypy or equivalent MUST pass
**Formatting**: Code MUST conform to project linter/formatter (e.g., ruff, black)
**Dependencies**: MUST be pinned to specific versions in requirements files
**Logging**: Console logging for debugging; structured format preferred

## Development Workflow

**Branch Strategy**: Feature branches MUST be created for all non-trivial changes
**Code Review**: All changes MUST be reviewed before merge to main
**Testing Gates**:
- Unit tests MUST pass
- Contract tests MUST pass for MCP tools
- Integration tests MUST pass for XER parsing

**Documentation**:
- Public APIs MUST have docstrings
- MCP tools MUST have usage examples
- Breaking changes MUST update migration docs

## Governance

This constitution supersedes all other development practices for the XER MCP Server project. When conflicts arise, this document takes precedence.

**Amendment Process**:
1. Proposed amendments MUST be documented with rationale
2. Amendments MUST be reviewed and approved
3. Version MUST be incremented according to change type:
   - MAJOR: Principle removal or fundamental redefinition
   - MINOR: New principle or significant expansion
   - PATCH: Clarifications and wording improvements
4. All dependent templates MUST be reviewed for consistency

**Compliance Review**:
- All PRs MUST verify compliance with core principles
- TDD violations are blocking defects
- MCP protocol deviations are blocking defects
- Constitution Check in plan.md MUST be completed before implementation

**Version**: 1.0.1 | **Ratified**: 2026-01-06 | **Last Amended**: 2026-01-06