SSO MCP Server

<!-- ================================================================================ SYNC IMPACT REPORT ================================================================================ Version Change: N/A → 1.0.0 (Initial Creation) Modified Principles: N/A (Initial creation) Added Sections: - Core Principles (5 principles focused on Code Quality and Maintainability) - I. Clean Code Standards - II. Test-First Development - III. Code Review Requirements - IV. Documentation Standards - V. Continuous Improvement - Quality Gates section - Development Workflow section - Governance section Removed Sections: N/A (Initial creation) Templates Requiring Updates: - design-template.md: ✅ Ground-rules Check section already supports dynamic gates - spec-template.md: ✅ Compatible - requirements align with quality principles - tasks-template.md: ✅ Compatible - supports test-first workflow Follow-up TODOs: None ================================================================================ --> # SSO MCP Server Ground-rules ## Core Principles ### I. Clean Code Standards All code MUST adhere to clean code principles to ensure readability, maintainability, and consistency: - **Naming Conventions**: Variables, functions, classes, and files MUST use descriptive, intention-revealing names. Avoid abbreviations unless universally understood. - **Function Design**: Functions MUST do one thing well. Maximum function length is 30 lines; prefer shorter functions that are easily testable. - **Single Responsibility**: Each module, class, and function MUST have a single, well-defined responsibility. If a component does multiple things, refactor into smaller units. - **DRY Principle**: Duplication MUST be eliminated through appropriate abstraction. Three or more instances of similar code require extraction into a shared utility. - **Code Formatting**: All code MUST follow project-configured linting and formatting rules. Commits with linting errors are not permitted. **Rationale**: Clean code reduces cognitive load, accelerates onboarding, and minimizes defect introduction during maintenance. ### II. Test-First Development Testing is a mandatory part of the development workflow, not an afterthought: - **TDD Cycle**: When tests are requested, follow Red-Green-Refactor: 1. Write failing test that defines desired behavior 2. Implement minimum code to pass the test 3. Refactor while keeping tests green - **Test Coverage**: Critical business logic MUST have unit test coverage. Integration tests MUST cover API contracts and cross-component interactions. - **Test Quality**: Tests MUST be readable, independent, and fast. Flaky tests MUST be fixed immediately or quarantined with tracking issue. - **Contract Testing**: Any public API or interface change MUST include updated contract tests. **Rationale**: Tests provide confidence for refactoring, serve as executable documentation, and catch regressions before production. ### III. Code Review Requirements All code changes MUST undergo peer review before merging: - **Review Scope**: Every pull request MUST be reviewed by at least one team member not involved in writing the code. - **Review Checklist**: Reviewers MUST verify: - Code follows clean code standards (Principle I) - Tests exist and pass (Principle II) - No security vulnerabilities introduced - Changes are appropriately scoped (no unrelated changes) - Documentation updated if behavior changes - **Approval Requirements**: PRs require explicit approval before merge. Comments marked as blocking MUST be resolved. - **Self-Review**: Authors MUST self-review their PR before requesting review, checking diff for accidental inclusions. **Rationale**: Code review catches defects early, shares knowledge across the team, and ensures consistent code quality. ### IV. Documentation Standards Code MUST be self-documenting with strategic supplemental documentation: - **Self-Documenting Code**: Prefer clear code over comments. If code requires explanation, first attempt to clarify through better naming or structure. - **Required Documentation**: - Public APIs MUST have clear interface documentation - Complex algorithms MUST explain the "why" not the "what" - Configuration options MUST be documented with defaults and examples - Architecture decisions MUST be recorded in ADRs - **README Requirements**: Every repository/package MUST have a README with: - Purpose and scope - Quick start instructions - Development setup guide - **Keep Documentation Current**: Outdated documentation is worse than no documentation. Updates to behavior MUST include documentation updates in the same PR. **Rationale**: Good documentation accelerates onboarding, reduces support burden, and preserves institutional knowledge. ### V. Continuous Improvement Technical debt MUST be managed proactively, not accumulated indefinitely: - **Boy Scout Rule**: Leave code cleaner than you found it. Small improvements during feature work are encouraged when they don't expand scope significantly. - **Tech Debt Tracking**: Known technical debt MUST be documented with: - Description of the issue - Impact assessment - Proposed remediation - **Refactoring Discipline**: Large refactors MUST be planned and approved. They should not be mixed with feature work. - **Dependency Management**: Dependencies MUST be kept reasonably current. Security updates MUST be applied within defined SLA. **Rationale**: Proactive maintenance prevents codebase degradation and keeps development velocity sustainable. ## Quality Gates Development workflow includes mandatory quality gates that MUST pass before proceeding: | Gate | Trigger | Requirements | |------|---------|--------------| | Pre-commit | Before commit | Linting passes, no secrets in code | | Pre-merge | Before PR merge | All CI checks pass, review approved | | Pre-deploy | Before deployment | All tests pass, security scan clean | **Automation**: Quality gates SHOULD be enforced automatically through CI/CD pipelines. Manual gates are acceptable only when automation is not feasible. ## Development Workflow Standard development workflow enforces quality principles: 1. **Branch Creation**: Create feature branch from main with descriptive name 2. **Development**: Write code following clean code standards (Principle I) 3. **Testing**: Write/update tests following test-first approach (Principle II) 4. **Self-Review**: Review own changes before PR 5. **Pull Request**: Create PR with clear description and linked issues 6. **Code Review**: Address reviewer feedback (Principle III) 7. **Merge**: Squash merge after approval and CI pass 8. **Documentation**: Update documentation as needed (Principle IV) ## Governance These ground rules represent the project's quality standards and MUST be followed by all contributors: - **Precedence**: Ground rules take precedence over convenience. Shortcuts that violate principles require explicit approval and documented justification. - **Amendments**: Changes to ground rules require: 1. Written proposal with rationale 2. Team discussion and consensus 3. Version increment following semantic versioning 4. Migration plan if changes affect existing code - **Compliance**: All PRs and code reviews MUST verify compliance with these ground rules. Violations should be flagged and resolved before merge. - **Exceptions**: Temporary exceptions MAY be granted for time-critical fixes but MUST be tracked as tech debt for remediation. **Version**: 1.0.0 | **Ratified**: 2025-12-11 | **Last Amended**: 2025-12-11