fraudshield/.specify/memory/constitution.md

<!--
  Sync Impact Report
  Version change: 0.0.0 → 1.0.0 (initial constitution)
  Modified principles: N/A (initial creation)
  Added sections:
    - Core Principles (6 principles)
    - Security & Compliance Requirements
    - Development Workflow & Quality Gates
    - Governance
  Removed sections: N/A
  Templates requiring updates:
    - .specify/templates/plan-template.md ✅ aligned (Constitution Check gate present)
    - .specify/templates/spec-template.md ✅ aligned (requirements section compatible)
    - .specify/templates/tasks-template.md ✅ aligned (TDD + observability patterns supported)
  Follow-up TODOs: none
-->

# 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