diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index a4670ff..5eab847 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,50 +1,133 @@ -# [PROJECT_NAME] Constitution - + + +# XER MCP Server Constitution ## Core Principles -### [PRINCIPLE_1_NAME] - -[PRINCIPLE_1_DESCRIPTION] - +### I. Test-First Development (NON-NEGOTIABLE) -### [PRINCIPLE_2_NAME] - -[PRINCIPLE_2_DESCRIPTION] - +Test-Driven Development is mandatory for all feature implementation. Tests MUST be written and verified to fail before any implementation code is written. -### [PRINCIPLE_3_NAME] - -[PRINCIPLE_3_DESCRIPTION] - +**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 -### [PRINCIPLE_4_NAME] - -[PRINCIPLE_4_DESCRIPTION] - +**Rationale**: TDD ensures correctness, documents behavior, and prevents regressions. For an MCP server handling complex XER data, test coverage is essential to maintain reliability. -### [PRINCIPLE_5_NAME] - -[PRINCIPLE_5_DESCRIPTION] - +### II. Extensibility Architecture -## [SECTION_2_NAME] - +The system MUST be designed for extension through well-defined interfaces and plugin points. Future capabilities MUST be addable without modifying core components. -[SECTION_2_CONTENT] - +**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 -## [SECTION_3_NAME] - +**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. -[SECTION_3_CONTENT] - +### 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 - -[GOVERNANCE_RULES] - +This constitution supersedes all other development practices for the XER MCP Server project. When conflicts arise, this document takes precedence. -**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE] - +**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