# Contributing Guidelines & Engineering Protocols

**Project**: Atiku 2027 Presidential Election Situation Room & Collation System (ADC 🤝)  
**Powered By**: GetoCore Digital Innovation  
**Classification**: High-Security Campaign Engineering Infrastructure

Thank you for contributing to the 2027 Presidential Situation Room. This platform serves as the central command, parallel vote tabulation (PVT), and forensic evidence engine for the campaign of His Excellency Atiku Abubakar.

---

## 1. Branching Strategy & Git Workflow

We adhere to a disciplined Git branching model to safeguard the integrity of election night operations:

- **`main`**: Production release branch. Deployed to the cloud command servers and field PWA. Direct commits to `main` are strictly protected.
- **`develop`**: Primary staging and integration branch for testing new modules.
- **`feature/<name>`**: New feature additions (e.g. `feature/multilingual-voice-faq`, `feature/bvas-ble-sync`).
- **`fix/<issue>`**: Bug and layout fixes (e.g. `fix/mobile-queue-padding`, `fix/safari-date-picker`).
- **`audit/<topic>`**: Forensic OCR models, tribunal exhibit formats, and cryptographic upgrades.
- **`sec/<cve>`**: Emergency security patches and credential rotation.

---

## 2. Branch Protection Rules

1. **Pull Request Required**: No developer or admin may push directly to `main` or `develop`.
2. **Mandatory Reviews**: At least one senior GetoCore engineer must review and approve code changes.
3. **CI Status Checks**: All GitHub Actions workflows (`.github/workflows/ci.yml`) must pass with 0 errors:
   - TypeScript compilation (`npx tsc --noEmit`)
   - Next.js production build (`npm run build`)
   - Security audit & PII redaction checks
4. **Linear Git History**: Pull requests must be merged via **Squash and Merge** or **Rebase** to maintain a clean forensic audit log.

---

## 3. Commit Message Conventions (Conventional Commits)

Commit messages must be concise and descriptive, following the Conventional Commits specification:

- `feat:` A new user-facing capability (e.g., `feat: integrate hausa and igbo language models in guidance chatbot`)
- `fix:` A bug fix (e.g., `fix: prevent card overflow in bvas readiness module`)
- `sec:` Security enhancement or cryptographic hardening (e.g., `sec: implement aes-gcm 256-bit encryption for offline queue`)
- `perf:` Performance optimization (e.g., `perf: optimize indexeddb write latency during bulk collation`)
- `docs:` Documentation updates (e.g., `docs: add tribunal section 84 evidence guidelines`)

---

## 4. Non-Negotiable Engineering Standards

### 4.1 Offline-First Design
Every user interaction on `/agent` (reporting steps 1 through 5, incident reporting, assistant lookups) **MUST** work without internet connectivity. Always test components by toggling Offline mode in Chrome DevTools.

### 4.2 Zero Plaintext Sensitive Data
- Never commit private API keys, service account credentials, or database passwords.
- All offline queues written to `IndexedDB` or `LocalStorage` must pass through `encryptPayload()` in `src/lib/offlineCrypto.ts`.
- Sensitive agent phone numbers must be sanitized via `maskPhoneNumber()` (`0803***2222`).

### 4.3 Electoral Act 2022 Compliance
All calculations must strictly adhere to the Electoral Act 2022:
- **Section 47**: BVAS mandatory electronic accreditation.
- **Section 51**: Over-voting cancellation if Total Votes > BVAS Accredited Count.
- **Section 60**: Mandatory Form EC8A physical endorsement and photo capture.

---

## 5. Security Vulnerability Reporting

If you identify a potential security vulnerability or algorithmic discrepancy:
1. **DO NOT** open a public GitHub issue.
2. Immediately contact the GetoCore Cyber Defense Team at `security@getocore.com` or ping the Tech Desk directly within the Situation Room dashboard.