# FraudShield Constitution ## Core Principles ### I. Security-First (NON-NEGOTIABLE) Every component MUST handle sensitive financial data as a potential breach vector. - All PII and transaction data MUST be encrypted at rest (AES-256-GCM minimum) and in transit (TLS 1.3 minimum). - Credentials, API keys, and secrets MUST NEVER be stored in source code, configuration files, or logs. Use a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager). - Input validation MUST be applied at every system boundary. All user-supplied data is untrusted. - Authentication and authorization MUST be enforced on every endpoint. No anonymous access to any data. - Dependency scanning (Snyk, Dependabot, or equivalent) MUST run on every PR. Critical/High vulnerabilities block merge. - Principle of least privilege: services and users get only the permissions they need, nothing more. **Rationale**: A single data leak in a fraud detection system exposes not just the application but the financial data of thousands of customers. Security is not a feature; it is the foundation. ### II. Explainability Mandatory Every fraud detection decision MUST produce a human-readable, auditable explanation. - Each flagged transaction MUST include: which rules/features triggered, confidence score, and the reasoning chain. - Black-box ML predictions are NOT acceptable for production decisions without a parallel explainability layer (SHAP, LIME, or rule extraction). - Explanation format MUST be machine-parseable (JSON) AND human-readable (natural language summary). - Fraud analysts MUST be able to understand WHY a transaction was flagged within 30 seconds of reviewing the explanation card. **Rationale**: Financial compliance (SOX, PCI-DSS, LGPD/GDPR) requires auditable decisions. False positives that block legitimate transactions cost real money and erode customer trust. ### III. Test-First (NON-NEGOTIABLE) All detection logic MUST be written test-first with measurable accuracy gates. - TDD cycle enforced: write test → see it fail → implement → see it pass → refactor. - Detection rules and ML models MUST report: precision, recall, F1-score, false positive rate, false negative rate. These metrics block deployment if below thresholds. - Unit tests for every detection rule. Integration tests for every pipeline stage. Contract tests for every API boundary. - A representative dataset of known fraudulent AND legitimate transactions MUST exist for regression testing. - Tests MUST pass before merge. No exceptions, no `@skip`, no `--no-verify`. **Rationale**: A fraud detection system that silently misses fraud (false negatives) loses money. One that falsely flags legitimate transactions (false positives) loses customers. Both failure modes are unacceptable without measurement. ### IV. Full Observability Every transaction evaluation MUST leave a complete, traceable audit trail. - Structured logging (JSON format) with trace IDs propagated across all services. - Every fraud decision MUST log: transaction ID, timestamp, rules evaluated, scores, final verdict, explanation ID. - Metrics dashboards MUST show real-time: throughput, latency (p50/p95/p99), fraud rate, false positive rate, system health. - Alerting MUST fire on: detection pipeline latency exceeding SLA, error rate spike, detection rate anomaly (±3σ from baseline), system downtime. - All logs MUST be immutable and retained for the legally required period (minimum 5 years for financial data in most jurisdictions). **Rationale**: When a regulator or customer disputes a fraud decision, you need to reconstruct EXACTLY what happened, when, and why. Without observability, you are blind and liable. ### V. Data Privacy by Design Privacy MUST be designed into the system, not bolted on. - Data minimization: collect ONLY fields necessary for fraud detection. No "just in case" data collection. - Purpose limitation: data collected for fraud detection MUST NOT be reused for marketing, analytics, or any other purpose without explicit consent. - PII MUST be pseudonymized or anonymized wherever possible in logs, analytics, and non-production environments. - Right to deletion and right to explanation MUST be supported per LGPD/GDPR requirements. - All data flows MUST be documented in a Data Protection Impact Assessment (DPIA). **Rationale**: LGPD (Brazil) and GDPR (EU) carry fines up to 2-4% of global revenue. Financial data is classified as sensitive personal data, requiring explicit consent and heightened protection. ### VI. Simplicity (YAGNI) Start simple; add complexity only when proven necessary. - Rules-based detection (decision trees, scorecards) MUST be the default approach. Machine learning is adopted only when rules-based approaches demonstrably underperform against measured baselines. - Premature optimization is technical debt. Profile first, optimize second. - External dependencies MUST be justified: prefer standard library or well-maintained, widely-adopted packages over niche or unmaintained alternatives. - Microservices only when a monolith demonstrably fails to meet scalability or team autonomy requirements. **Rationale**: Financial fraud detection is a domain where correctness beats cleverness. A simple rule that catches 90% of fraud with 0.1% false positives beats a neural network that catches 95% with 5% false positives and is unexplainable. ## Security & Compliance Requirements ### Regulatory Compliance - **PCI-DSS**: System MUST NOT store full card numbers, CVV, or magnetic stripe data. Use tokenization for any card data reference. - **LGPD (Brazil)**: Full compliance with Lei Geral de Proteção de Dados. Data processing MUST have legal basis (legitimate interest for fraud prevention). DPO contact MUST be published. - **GDPR (EU)**: If EU customers are in scope, full GDPR compliance including Data Processing Agreements with all subprocessors. - **SOX**: If applicable (public company), all fraud detection logic changes MUST be auditable with change management records. ### Security Testing - SAST (Static Application Security Testing) on every commit. - DAST (Dynamic Application Security Testing) on every deploy to staging. - Dependency vulnerability scanning on every PR (Critical/High blocks merge). - Annual penetration test by external firm (or before first production release). ## Development Workflow & Quality Gates ### Branch Strategy - Feature branches from `main`: `NNN-short-feature-name/` (per spec-kit convention). - Direct commits to `main` are FORBIDDEN. All changes via PR. - PR MUST pass: all tests, linting, SAST, dependency scan, and at least one human review. ### Quality Gates (per spec-kit workflow) - **Spec gate**: Spec reviewed and approved BEFORE plan phase. - **Plan gate**: Technical plan reviewed and approved BEFORE task generation. - **Implementation gate**: All tasks completed, all tests green, constitution compliance verified. ### Definition of Done - [ ] Code implements all acceptance criteria from spec. - [ ] Tests pass (unit, integration, contract) with required coverage thresholds. - [ ] False positive rate and false negative rate measured and within thresholds. - [ ] Explanation cards validated for accuracy and readability. - [ ] Audit trail verified end-to-end. - [ ] PR reviewed and approved by at least one other developer. - [ ] Security scan passes (no critical or high vulnerabilities). - [ ] Documentation updated (README, API docs, runbooks). ## Governance This constitution is the highest authority for the FraudShield project. All design decisions, code reviews, and architectural choices MUST be evaluated against these principles. When a principle is violated, the violation MUST be explicitly documented and justified in the implementation plan's Complexity Tracking section. **Amendment Process**: 1. Propose amendment with rationale in a dedicated PR. 2. Discuss with at least two other team members. 3. Update constitution version following semantic versioning (MAJOR for principle removal/redefinition, MINOR for new principles/sections, PATCH for clarifications). 4. Update all dependent templates and documentation. 5. Merge only after consensus. **Compliance Review**: Every PR description MUST include a brief constitution compliance statement confirming which principles apply and that they are satisfied (or documenting justified exceptions). **Version**: 1.0.0 | **Ratified**: 2026-05-11 | **Last Amended**: 2026-05-11