ADR-0001: Scope compliance claims to implemented controls

.github/workflows/ci.yml

@@ -304,6 +304,27 @@ jobs:
           name: documentation
           path: target/doc/
 
+  # ADR-0001: every compliance claim must be backed by an artifact.
+  # Pure-Python and dependency-free, so it needs no toolchain setup.
+  #
+  # Deliberately NOT in the ci-success needs list. This check is about documentation
+  # honesty and is independent of the Rust build; folding it into that umbrella would
+  # bury a green signal inside a job that is currently red for unrelated reasons it
+  # cannot influence. Read this job's own status instead, and make it a required check
+  # in branch protection if it should block merges.
+  compliance-claims:
+    name: Compliance Claims Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check compliance claims are backed
+        run: python3 scripts/check_compliance_claims.py
+
+      - name: Check SOC 2 evidence paths resolve
+        run: python3 scripts/check_evidence_paths.py
+
   # Summary job
   ci-success:
     name: CI Success

README.md

@@ -30,10 +30,10 @@ LLM-CoPilot-Agent is a comprehensive AI platform that serves as both a conversat
 - **Tool/Function Calling** - Extensible tool framework with validation and execution
 - **RAG Pipeline** - Document ingestion, chunking strategies, vector search, and generation
 
-### Compliance & Governance (Phase 5)
-- **SOC 2 Type II** - Control management, audits, findings, evidence collection
-- **HIPAA Compliance** - PHI access logging, BAA management, breach reporting
-- **Data Residency** - Policy enforcement, regional data controls, transfer workflows
+### Compliance & Governance (Design Stage)
+- **SOC 2 control mapping and evidence-collection design (no audit performed)** - see [`deployment/compliance/soc2-evidence-collection.yaml`](deployment/compliance/soc2-evidence-collection.yaml)
+- **HIPAA-oriented control catalog covering §164.308/310/312 (design stage, not operational)**
+- **Data residency policy model (design stage)**
 - **Content Filtering** - Safety filters, PII detection, moderation integration
 - **Usage Policies** - Policy evaluation, enforcement modes, violation tracking
 - **Audit Trail** - Comprehensive event logging, anomaly detection, retention
@@ -205,22 +205,24 @@ Enterprise AI/ML platform providing model management, agent orchestration, and R
 
 ### Compliance Service (Port 3009)
 
-Enterprise compliance management for SOC 2, HIPAA, and data residency requirements.
+Design-stage compliance service for SOC 2 control mapping, HIPAA safeguard cataloguing, and data residency policy modelling. Not deployed; see [`docs/adr/ADR-0001-compliance-claims-remediation.md`](docs/adr/ADR-0001-compliance-claims-remediation.md).
 
-| Feature | Description |
-|---------|-------------|
-| **Control Management** | SOC 2 controls with status tracking and evidence |
-| **Audit Management** | Schedule audits, track findings, generate reports |
-| **HIPAA Compliance** | PHI access logging, BAA management, breach reporting |
-| **Data Residency** | Regional policies, asset tracking, transfer workflows |
-| **Compliance Reports** | Gap analysis, risk assessment, audit readiness |
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Control Management** | SOC 2 controls with status tracking and evidence | Design |
+| **Audit Management** | Schedule audits, track findings, generate reports | Design |
+| **HIPAA Compliance** | PHI access logging, breach reporting | Design |
+| **Data Residency** | Regional policies, asset tracking, transfer workflows | Design |
+| **Compliance Reports** | Gap analysis, risk assessment, audit readiness | Design |
+
+> **Note:** The compliance service is not currently deployed in any environment. It appears in no `docker-compose.yml`, Kubernetes, or Helm manifest, and the database tables it queries are not yet created by any migration.
 
 **Endpoints:**
 - `GET/POST /api/v1/compliance/controls` - Control management
 - `GET/POST /api/v1/compliance/audits` - Audit management
 - `GET/POST /api/v1/compliance/findings` - Finding tracking
 - `POST /api/v1/hipaa/phi-access` - PHI access logging
-- `GET/POST /api/v1/hipaa/baa` - BAA management
+- `GET/POST /api/v1/hipaa/baa` - BAA registry records, design stage (tracking only; does not execute agreements)
 - `GET/POST /api/v1/data-residency/policies` - Residency policies
 - `POST /api/v1/data-residency/transfers` - Data transfers
 
@@ -467,17 +469,18 @@ CORS_ORIGIN=http://localhost:3000,https://your-domain.com
 | Phase 2 | Complete | Multi-tenancy & Auth |
 | Phase 3 | Complete | Advanced Features |
 | Phase 4 | Complete | Enterprise Operations |
-| Phase 5 | Complete | AI/ML Platform & Compliance |
+| Phase 5 | Complete | AI/ML Platform |
+| Phase 5 | Design Complete, Implementation In Progress | Compliance |
 | Phase 6 | Planned | Scale & Advanced Analytics |
 
-## Security & Compliance
+## Security
 
-- **SOC 2 Type II** - Comprehensive control framework
-- **HIPAA** - PHI protection and access logging
-- **GDPR** - Data residency and privacy controls
 - **Content Safety** - Multi-layer content filtering
 - **Audit Trail** - Complete activity logging
-- **Encryption** - At-rest and in-transit encryption
+- **Encryption** - At-rest and in-transit encryption (see `deployment/terraform/main.tf:243,298-299,340-344`)
+
+For the project's compliance posture — including why SOC 2 Type II, HIPAA, and GDPR are
+not claimed here — see [`docs/adr/ADR-0001-compliance-claims-remediation.md`](docs/adr/ADR-0001-compliance-claims-remediation.md).
 
 ## Contributing
 

deployment/compliance/soc2-evidence-collection.yaml

@@ -1,5 +1,8 @@
 # SOC 2 Type II Evidence Collection Procedures
 # Automated evidence gathering for compliance audit
+#
+# Status: Design Specification -- no audit performed.
+# See docs/adr/ADR-0001-compliance-claims-remediation.md
 
 evidenceCollection:
 
@@ -27,7 +30,7 @@ evidenceCollection:
 
           manual:
             - type: "Authentication Policy Document"
-              path: "docs/policies/authentication-policy.md"
+              path: "docs/policies/authentication-policy.md"  # TODO: artifact does not yet exist
               reviewFrequency: "Quarterly"
 
       - id: "CC6.1.2"
@@ -40,7 +43,7 @@ evidenceCollection:
 
             - type: "Session Timeout Settings"
               source: "Application code"
-              path: "services/auth/session.ts"
+              path: "services/auth/session.ts"  # TODO: artifact does not yet exist
 
   # CC6.2 - New User Provisioning
   CC6_2:
@@ -50,10 +53,10 @@ evidenceCollection:
         evidence:
           manual:
             - type: "Provisioning Procedure"
-              path: "docs/procedures/user-provisioning.md"
+              path: "docs/procedures/user-provisioning.md"  # TODO: artifact does not yet exist
 
             - type: "Background Check Records"
-              path: "hr/background-checks/"
+              path: "hr/background-checks/"  # TODO: artifact does not yet exist
               storage: "Secure HR system"
 
           automated:
@@ -71,7 +74,7 @@ evidenceCollection:
           automated:
             - type: "Password Policy Configuration"
               source: "Application code"
-              path: "services/auth/password-policy.ts"
+              path: "services/auth/password-policy.ts"  # TODO: artifact does not yet exist
 
             - type: "Password Change Audit"
               source: "Audit logs"
@@ -89,7 +92,7 @@ evidenceCollection:
 
           manual:
             - type: "Access Review Approval"
-              path: "compliance/access-reviews/"
+              path: "compliance/access-reviews/"  # TODO: artifact does not yet exist
               format: "PDF with manager signatures"
 
   # CC6.6 - Encryption
@@ -169,15 +172,15 @@ evidenceCollection:
 
             - type: "Backup Storage Verification"
               source: "AWS S3"
-              path: "s3://llm-copilot-backups/"
+              path: "s3://llm-copilot-backups/"  # TODO: artifact does not yet exist
               schedule: "Daily"
 
       - id: "CC7.3.2"
         description: "Disaster recovery testing"
         evidence:
           manual:
             - type: "DR Test Results"
-              path: "compliance/dr-tests/"
+              path: "compliance/dr-tests/"  # TODO: artifact does not yet exist
               schedule: "Quarterly"
               requiredSignoff: "CTO"
 
@@ -213,7 +216,7 @@ evidenceCollection:
 
             - type: "Test Coverage Reports"
               source: "Jest/Coverage"
-              path: "coverage/"
+              path: "coverage/"  # TODO: artifact does not yet exist
               schedule: "Per commit"
 
   # CC9.2 - Business Continuity
@@ -236,7 +239,7 @@ evidenceCollection:
         evidence:
           manual:
             - type: "Failover Test Report"
-              path: "compliance/failover-tests/"
+              path: "compliance/failover-tests/"  # TODO: artifact does not yet exist
               schedule: "Quarterly"
 
 # Automated Evidence Collection Scripts