docs: establish project constitution v1.0.1
Define governance for XER MCP Server with 5 core principles: - Test-First Development (TDD mandatory) - Extensibility Architecture (pluggable handlers) - MCP Protocol Compliance (strict spec adherence) - XER Format Fidelity (no data loss) - Semantic Versioning (MAJOR.MINOR.PATCH) Technical standards: Python 3.14, type hints, testing gates
This commit is contained in:
@@ -1,50 +1,133 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
<!--
|
||||
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
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### I. Test-First Development (NON-NEGOTIABLE)
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
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]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
**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]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
**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]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
### II. Extensibility Architecture
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
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]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
**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]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
**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]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
### 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
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
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]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
**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
|
||||
|
||||
Reference in New Issue
Block a user