docs: establish FraudShield constitution v1.0.0

6 core principles: Security-First, Explainability, Test-First,
Observability, Data Privacy by Design, Simplicity (YAGNI).
Includes Security & Compliance, Development Workflow, and Governance sections.

.specify/memory/constitution.md

@@ -1,50 +1,141 @@
-# [PROJECT_NAME] Constitution
-<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+<!--
+  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
 
-### [PRINCIPLE_1_NAME]
-<!-- Example: I. Library-First -->
-[PRINCIPLE_1_DESCRIPTION]
-<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+### I. Security-First (NON-NEGOTIABLE)
 
-### [PRINCIPLE_2_NAME]
-<!-- Example: II. CLI Interface -->
-[PRINCIPLE_2_DESCRIPTION]
-<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+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.
 
-### [PRINCIPLE_3_NAME]
-<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
-[PRINCIPLE_3_DESCRIPTION]
-<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+**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.
 
-### [PRINCIPLE_4_NAME]
-<!-- Example: IV. Integration Testing -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+### II. Explainability Mandatory
 
-### [PRINCIPLE_5_NAME]
-<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
-[PRINCIPLE_5_DESCRIPTION]
-<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+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.
 
-## [SECTION_2_NAME]
-<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+**Rationale**: Financial compliance (SOX, PCI-DSS, LGPD/GDPR) requires auditable decisions. False positives that block legitimate transactions cost real money and erode customer trust.
 
-[SECTION_2_CONTENT]
-<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+### III. Test-First (NON-NEGOTIABLE)
 
-## [SECTION_3_NAME]
-<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+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`.
 
-[SECTION_3_CONTENT]
-<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+**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
-<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
 
-[GOVERNANCE_RULES]
-<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+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.
 
-**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+**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