fraudshield/.specify/memory/constitution.md

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