docs: add comprehensive code quality standards guide

.gitmessage.txt

@@ -0,0 +1,47 @@
+# SAMO-DL Commit Message Template
+#
+# Quick setup:
+#   git config commit.template .gitmessage.txt
+#   # To make it global: git config --global commit.template "$(pwd)/.gitmessage.txt"
+#
+# Format: <type>(<scope>)!: <subject>
+# (scope is optional; add "!" for breaking changes)
+# Body: explain what and why, wrapped at ~72 chars per line
+# Footer: references and BREAKING CHANGE notes
+#
+# Types:
+#   feat:     A new feature
+#   fix:      A bug fix
+#   docs:     Documentation only changes
+#   style:    Formatting, whitespace, missing semicolons, no code change
+#   refactor: Code change that neither fixes a bug nor adds a feature
+#   perf:     A code change that improves performance
+#   test:     Adding missing tests or correcting existing tests
+#   build:    Changes to build system or external dependencies
+#   ci:       Changes to CI configuration files and scripts
+#   chore:    Other changes that don't modify src or test files
+#   revert:   Reverts a previous commit
+#
+# Rules:
+#   - ONE purpose per commit (no "and", "also", "plus")
+#   - Subject line ≤ 50 characters
+#   - Use imperative mood ("Add" not "Added")
+#   - No period at end of subject line
+#   - Wrap body at ~72 characters per line
+#   - Reference issues/PRs in footer (e.g., "Closes #123")
+#   - Use "BREAKING CHANGE: ..." in footer for breaking changes
+#
+# Examples:
+#   feat(auth): add login with email magic links
+#   fix(loader): resolve memory leak in model loading
+#   perf(infer): cache tokenizer to reduce setup time
+#   refactor(rate-limit): simplify token bucket logic
+#   docs(api): update inference usage examples
+#   style: run formatter across repo
+#   build: bump torch to 2.4.x
+#   ci: parallelize test matrix
+#   revert: revert "feat(auth): add magic links"
+#   feat(core)!: switch default precision to bfloat16
+#   BREAKING CHANGE: default precision is now bfloat16; set
+#   SAMO_PRECISION=float32 to keep previous behavior.
+#   Closes #174

CODE_QUALITY_README.md

@@ -0,0 +1,209 @@
+# SAMO-DL Code Quality Standards
+
+## 🎯 Mission: Prevent Monster PRs Forever
+
+This document outlines the **strict rules** and **automated enforcement** designed to prevent the creation of massive, unfocused pull requests that slow down development and make code reviews impossible.
+
+## 🚫 THE PROBLEM WE SOLVE
+
+**Monster PRs** are pull requests that:
+- Change 100+ files
+- Add 1000+ lines of code
+- Mix multiple concerns (API + tests + docs + infrastructure)
+- Take weeks to review
+- Cause merge conflicts
+- Block progress
+
+## ✅ THE SOLUTION: Micro-PRs Only
+
+### **Hard Limits (Automated Enforcement)**
+```yaml
+# GitHub Actions - PR Size Guard
+max_files_changed: 50     # HARD STOP at 50 files
+max_lines_changed: 1500   # HARD STOP at 1500 lines
+max_commits_per_pr: 5     # HARD STOP at 5 commits
+branch_lifetime: 72h      # Auto-close or require split after 72h (extensions available for complex changes)
+```
+
+#### Requirement: PR purpose must be exactly one sentence
+- ✅ "Add user authentication system"
+- ✅ "Fix memory leak in model loading"
+- ❌ "Improve model architecture and fix bugs" *(TWO THINGS!)*
+- ❌ "Refactor training pipeline" *(TOO VAGUE!)*
+
+## 🛠️ AUTOMATED ENFORCEMENT
+
+### **1. Local Hooks (pre-commit + commit-msg)**
+Use the pre-commit framework (versioned via `.pre-commit-config.yaml`) to run format/lint/type/security checks on staged files. Enforce commit message format via a `commit-msg` hook (e.g., Commitizen).
+
+**Notes:**
+- Branch naming and "single purpose" are enforced in CI (see PR Scope Checker), not locally.
+- Hooks run automatically once installed (`pre-commit install` and `pre-commit install --hook-type commit-msg`).
+
+### **2. PR Scope Checker**
+```bash
+python scripts/check_pr_scope.py --strict
+```
+> **Note:** The PR scope checker script is available in the repository and actively maintained.
+Validates:
+- File count ≤ 50
+- Line changes ≤ 1500
+- Single purpose (no mixing concerns)
+- Branch naming compliance
+
+### **3. CI Pipeline Checks**
+GitHub Actions automatically:
+- Runs scope validation on PR creation
+- Fails builds that exceed limits
+- Prevents merging of out-of-scope PRs
+
+## 📋 DEVELOPMENT WORKFLOW
+
+### **Before Creating a Branch**
+```md
+# Answer these questions:
+1. Can I describe this in ONE sentence?
+2. Will this affect < 50 files?
+3. Can I complete this in < 4 hours?
+4. Is this EXACTLY ONE concern?
+5. Am I mixing API + tests + docs?
+
+# If ANY answer is NO: Split into separate PRs
+```
+
+### **Branch Naming Convention**
+```text
+feat/short-description      # New features
+fix/short-description       # Bug fixes
+chore/short-description     # Build/tooling changes
+refactor/short-description  # Code restructuring
+docs/short-description      # Documentation
+test/short-description      # Test additions
+```
+
+**Examples:**
+- ✅ `feat/add-user-auth`
+- ✅ `fix/validate-input`
+- ✅ `chore/update-deps`
+- ✅ `refactor/simplify-logic`
+- ❌ `feat/add-auth-and-fix-bugs` *(multiple concerns)*
+- ❌ `fix-stuff` *(too vague)*
+
+### **Commit Message Format**
+```gitcommit
+<type>(<scope>): <subject>
+
+<body - optional>
+```
+**Examples:**
+```gitcommit
+feat: add JWT token authentication
+fix: resolve memory leak in model loading
+chore: update Python dependencies
+refactor: simplify rate limiter logic
+```
+
+## 🏗️ CODE QUALITY TOOLS
+
+### **Automated Tools**
+- **Ruff**: Ultra-fast code formatting, linting, and import sorting (replaces Black, isort, flake8)
+- **pylint**: Advanced code analysis
+- **mypy**: Type checking
+- **bandit**: Security scanning
+- **safety**: Dependency vulnerability checks
+
+### **Pre-commit Hooks**
+Run automatically on commit:
+```bash
+pre-commit install  # Install hooks
+pre-commit run --all-files  # Run on all files
+```
+
+### **Development Commands**
+```bash
+make format      # Format code
+make lint        # Run linters
+make test        # Run tests
+make quality-check  # Run all quality checks
+```
+
+## 🚨 EMERGENCY OVERRIDES
+
+**Only for critical production issues:**
+```yaml
+override_label: "EMERGENCY-OVERRIDE"
+required_approvers: 2
+max_override_per_week: 1
+auto_close_after: 8h
+```
+
+> **Note:** Overrides require label + 2 approvers + admin "bypass PR requirements" permission, or a temporary policy change. GitHub cannot bypass required checks by workflow alone.
+
+## 📊 SUCCESS METRICS
+
+**Weekly Tracking:**
+- Average PR size: < 15 files
+- PR lifetime: < 24 hours
+- Number of scope violations: 0
+- Merge conflicts: < 1 per week
+
+**Red Flags (Auto-alert):**
+- Any PR > 50 files
+- Any branch > 48 hours old
+- Any PR title with "and", "also", "plus"
+- Any PR summary > 2 sentences (detailed descriptions in body are encouraged)
+
+## 🎯 WHY THIS WORKS
+
+### **Psychological Benefits**
+- **Small wins**: Frequent merges build momentum
+- **Fast feedback**: Quick reviews = faster iteration
+- **Reduced risk**: Smaller changes = easier rollback
+- **Team satisfaction**: Actually shipping features
+
+### **Technical Benefits**
+- **Fewer merge conflicts**: Smaller, focused changes
+- **Easier reviews**: 50 files vs 100+ files
+- **Better testing**: Isolated changes = targeted tests
+- **Faster CI/CD**: Smaller PRs = faster pipelines
+
+## 🚀 IMPLEMENTATION
+
+### **Immediate Actions**
+1. **Install pre-commit hooks**: `pre-commit install`
+2. **Set commit template**: `git config commit.template .gitmessage.txt`
+   > **Note:** The `.gitmessage.txt` file is included in the repository with a comprehensive commit message template following Conventional Commits standards.
+3. **Run scope checker**: `python scripts/check_pr_scope.py`
+4. **Review existing PRs**: Close any that violate rules
+
+### **Team Adoption**
+1. **Training session**: Walk through the rules
+2. **Documentation**: Share this guide
+3. **Examples**: Show good vs bad PR examples
+4. **Celebrate**: Recognize teams following the rules
+
+## 📞 SUPPORT
+
+**Questions?** Ask in the development channel.
+
+**Found a violation?** Use the PR comment template:
+```md
+🚨 **SCOPE VIOLATION DETECTED**
+This PR exceeds our size limits:
+- Files: [count]/50 max
+- Lines: [count]/1500 max
+- Multiple concerns: [list them]
+
+Please split into focused micro-PRs.
+```
+
+---
+
+## 🎉 CONCLUSION
+
+### Summary
+Small PRs = Fast reviews = Quick merges = Happy developers = Successful project
+
+**NO EXCEPTIONS. NO EXCUSES. NO "JUST THIS ONCE".**
+
+Welcome to the era of **productive, focused development!** 🚀