# Suggested File Name: HCMS-FO-ComplianceShield-v1.0-2026.md

# HCMS Compliance Shield
## Functional Outline (FO) — v1.0 LOCKED · The 3rd Pillar of the HCMS App Suite Infrastructure

---

## Document Control

| Field | Value |
| :---- | :---- |
| **Document Type** | Functional Outline (FO) — Final |
| **Version** | **1.0 LOCKED — Engineering Handoff Pending Final Confirmation** |
| **Date** | May 23, 2026 |
| **Owner** | HCMS N.V. (subsidiary of K&K Heritage Group N.V.) |
| **Author** | Sovereign HCMS Architect (AI Head of Business Unit) |
| **Approvers** | Chairman (Strategic) · CEO (Operational) · Compliance Advisor (Domain) · IQT Lead (Technical) |
| **Service Type** | Shared microservice / internal infrastructure |
| **HCMS App Suite Position** | **Shared Infrastructure** — consumed by Pillar I (HUMANABLE), Pillar II (ATLAS), and future apps |
| **Companion FOs** | `HCMS-FO-HUMANABLE-Final-v1.3-2026.md` (Pillar I — consumer) · `HCMS-FO-ATLAS-Final-v1.3-2026.md` (Pillar II — consumer) |

---

## Executive Summary

The **HCMS Compliance Shield** is a dedicated Laravel microservice that encapsulates HCMS's institutional knowledge of Suriname's regulatory environment into a single, version-controlled, audit-ready system. It is **consumed by HUMANABLE and ATLAS** (and any future HCMS apps) via internal HTTP API calls — not a feature inside either app, but a standalone service deployed on the same shared LiquidNet VPS.

The Compliance Shield is the **strategic moat** of HCMS N.V. — the codified version of years of practitioner-level expertise navigating Suriname's expatriate, employment, and tax frameworks. Global ATS/HR competitors do not have this. By isolating it into its own microservice, HCMS achieves: (1) zero duplication across apps, (2) a single source of truth for compliance rules, (3) independent ownership by the Compliance team, (4) cleaner upgrade paths when regulations change, and (5) a defensible institutional asset.

This FO scopes **eight compliance modules** plus the supporting infrastructure (API, data model, audit trail, deployment) needed to deliver v1.0. Build effort is estimated at ~12–16 weeks for v1.0, running in parallel with HUMANABLE and ATLAS engineering. Both consumer apps need the Compliance Shield operational by their Phase 9 (Compliance Shield Integration) milestone.

---

## 1. Identity & Purpose

| Element | Definition |
| :---- | :---- |
| **Name** | **HCMS Compliance Shield** |
| **Internal Codename** | `compliance-shield` |
| **Description** | Shared microservice encoding Suriname compliance rules, consumed by HCMS apps via internal API |
| **Strategic Role** | The Compliance Moat — codified institutional expertise in Suriname regulatory navigation |
| **Owner (Business)** | HCMS Compliance Advisor |
| **Owner (Technical)** | IQT Lead |
| **Consumers (v1)** | HUMANABLE (recruitment) · ATLAS (expat concierge) |
| **Consumers (v2+)** | HCMS Academy · HCMS Digi Coaches · K&K Heritage Group expansion apps |
| **Deployment Target** | Shared LiquidNet VPS (US region) — same server as HUMANABLE + ATLAS |
| **Network Posture** | Internal-only API — not exposed to public internet |
| **Authentication** | Shared service tokens between consumer apps and Compliance Shield |
| **Domain** | Internal: `compliance-shield.internal:8000` (or local socket) — no public DNS |

### 1.1 Why a Separate Microservice (Not a Module)

| Reason | Benefit |
| :---- | :---- |
| **Shared across HCMS apps** | HUMANABLE consumes for recruitment compliance; ATLAS consumes for expat compliance; future apps inherit for free |
| **Single source of truth** | When Suriname tax/labour law changes, update once — all consumer apps benefit instantly |
| **Independent ownership** | The HCMS Compliance Advisor owns the business logic; engineering deploys it |
| **Strategic moat** | Codifies HCMS's competitive advantage in discoverable, version-controlled code |
| **Audit clarity** | All compliance decisions logged centrally for EU AI Act, Suriname Data Protection Act, GDPR |
| **Easier regulatory updates** | New compliance rules deployed independently of consumer app release cycles |

---

## 2. Architectural Pattern

### 2.1 Deployment Topology (Shared VPS)

The Compliance Shield deploys as a separate Laravel application on the **same LiquidNet VPS** that hosts HUMANABLE and ATLAS. Three Laravel applications coexist on one server:

```
┌─────────────────────────────────────────────────────────┐
│ LiquidNet US VPS · Ubuntu LTS · 16 GB RAM · 400 GB SSD │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  HUMANABLE   │  │    ATLAS     │  │  Compliance  │ │
│  │  Laravel 13+ │  │  Laravel 13+ │  │   Shield     │ │
│  │              │  │              │  │  Laravel 13+ │ │
│  │  Port 8001   │  │  Port 8002   │  │  Port 8003   │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
│         │                  │                  │         │
│         └──────────────────┴──────────────────┘         │
│                            │                            │
│                    ┌───────▼────────┐                  │
│                    │  PostgreSQL 16 │                  │
│                    │   + pgvector   │                  │
│                    │  (3 schemas)   │                  │
│                    └────────────────┘                  │
│                                                         │
│  Nginx (reverse proxy + SSL termination)                │
│  systemd (process management)                           │
└─────────────────────────────────────────────────────────┘
```

### 2.2 Inter-App Communication

| Aspect | Specification |
| :---- | :---- |
| **Protocol** | HTTP REST over `localhost` (same VPS) |
| **Authentication** | Service tokens via Laravel Sanctum (shared issuer) |
| **Encryption** | TLS recommended even on localhost for consistency (Let's Encrypt) |
| **Network exposure** | Internal-only — Compliance Shield NOT bound to public IP |
| **Rate limiting** | None at v1 (trusted internal callers); add at v2 if needed |
| **Versioning** | API versioned via URL prefix (e.g., `/v1/tax/pre-flight`) |

### 2.3 Stack Alignment

The Compliance Shield inherits the same `HUMANABLE §29 Development Stack & Delivery Guidelines`:
- Laravel 13+ · PHP 8.3+
- SQLite for local dev · PostgreSQL 16 + pgvector for staging/prod (shared DB server, separate schema `compliance_shield`)
- Database driver for cache/queue/session (no Redis)
- Local disk storage on shared VPS + Google Drive offsite backup
- Self-hosted Sentry monitoring (shared with HUMANABLE + ATLAS)
- No Docker, no Kubernetes, no managed cloud services

---

## 3. The Eight Compliance Modules

Each module is a discrete capability with: a clear purpose, defined trigger conditions, structured inputs and outputs, business logic, error handling, and audit trail.

### 3.1 Module 1 — 38% Expat Income Tax Pre-Flight

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Auto-calculate gross-up + Total Employment Cost (TEC) for expat hires; flag tax exposure before the offer letter is sent |
| **Trigger** | Called by HUMANABLE at offer drafting (Phase 4) when vacancy has `expat_flag = true`; called by ATLAS at financial track setup |
| **Inputs** | Net salary expectation · Allowances (housing, transport, school) · Benefits in kind · Currency · Assignment duration |
| **Outputs** | Gross-up calculation · Suriname 38% tax liability estimate · TEC breakdown · Risk flags (e.g., "exposure exceeds X threshold") |
| **Business Logic** | Codifies Suriname expatriate income tax rules including the 38% effective rate calculation methodology, allowance treatment, and TEC computation conventions used by HCMS practitioners |
| **Error Handling** | Returns explicit error if currency conversion fails, if inputs are incomplete, or if tax assumptions cannot be applied (e.g., unusual benefit structures) |
| **Audit Trail** | Every calculation logged with inputs, outputs, requestor app, timestamp, and Compliance Shield rule version |

### 3.2 Module 2 — Article 1639 Seniority Liability Flag

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Detect crew take-over scenarios; trigger the Clean Break Protocol workflow to eliminate inherited seniority liability |
| **Trigger** | Called by HUMANABLE at vacancy creation when employer indicates contractor crew transfer; called by ATLAS for expat assignment context |
| **Inputs** | Vacancy metadata · Employer history · Indicated crew take-over flag · Crew composition |
| **Outputs** | Risk flag (low/medium/high) · Recommended Clean Break Protocol steps · Required documentation list |
| **Business Logic** | Codifies Article 1639 of the Surinamese Civil Code, the patterns of seniority transfer in crew take-overs, and HCMS's Clean Break Protocol methodology |
| **Error Handling** | If crew composition unknown, returns "manual review required" with structured questions for the recruiter |
| **Audit Trail** | Each flag + Clean Break Protocol initiation logged |

### 3.3 Module 3 — Work Permit Pre-Screening

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Validate expat candidate visa eligibility against Suriname Ministry of Labour (Min. ATM) requirements before client submission |
| **Trigger** | Called by HUMANABLE at shortlist stage for expat-flagged candidates; called by ATLAS at immigration track initiation |
| **Inputs** | Candidate nationality · Education credentials · Years of experience · Role being filled · Employer details · Assignment duration |
| **Outputs** | Eligibility verdict (eligible/conditionally eligible/likely ineligible) · Required documents list · Estimated processing time · Risk factors |
| **Business Logic** | Encodes Suriname Ministry of Labour work permit requirements, Hoofd Vreemdelingendienst (Foreigners Service) visa rules, and HCMS-observed approval/rejection patterns |
| **Error Handling** | Conservative — when uncertain, returns "conditional" rather than "eligible" |
| **Audit Trail** | Every screening logged with full input + output for traceability |

### 3.4 Module 4 — Local Content Auto-Reporter

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Generate quarterly Local Content compliance reports for Tier-1 Operator clients (TotalEnergies, Newmont, Staatsolie, Chevron) |
| **Trigger** | Called by HUMANABLE + ATLAS quarterly; on-demand from employer portal |
| **Inputs** | Employer ID · Reporting period (quarter) · Placement records · Active expat records |
| **Outputs** | Structured Local Content report (PDF + JSON) showing: % Surinamese-national hires · Skills-transfer commitments fulfillment · Local procurement spend · Training-of-locals metrics |
| **Business Logic** | Codifies each Tier-1 Operator's specific Local Content thresholds and reporting templates (each operator has slightly different reporting requirements) |
| **Error Handling** | Returns warning if data is incomplete; can generate partial report with explicit gaps marked |
| **Audit Trail** | Every report generation logged + report PDF archived for 5-year retention |

### 3.5 Module 5 — EU AI Act Compliance Layer

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Log AI reasoning + confidence + human override audit trail for all AI-driven decisions across HCMS apps |
| **Trigger** | Called by every AI agent in HUMANABLE (8 agents) and ATLAS (AI concierge, predictive needs, vendor recommendation) before and after each AI decision |
| **Inputs** | AI decision context · Input data (sanitized) · AI provider (Claude/Gemini) · Model · Reasoning · Confidence score · Recommended action · Human override (if any) |
| **Outputs** | Confirmation of logging · Decision ID for traceability · Subject-Right-to-Explanation prepared payload (in case candidate requests) |
| **Business Logic** | Implements EU AI Act Article 13 (transparency) and Article 14 (human oversight) requirements; codifies the "high-risk AI system" controls applicable to recruitment and HR AI |
| **Error Handling** | If logging fails, AI decision still proceeds but consumer app is notified to retry-log; never blocks the decision pipeline |
| **Audit Trail** | This module IS the audit trail — primary table `ai_decision_audit` with permanent retention |

### 3.6 Module 6 — Bias Detection

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Auto-scan job descriptions and scorecards for biased language before publish/distribution |
| **Trigger** | Called by HUMANABLE on JD creation + scorecard creation; called by ATLAS on internal recruitment artifacts (rare) |
| **Inputs** | Text content (JD, scorecard, etc.) · Language · Context (role type, employer) |
| **Outputs** | Bias score (0-100) · Flagged phrases with explanations · Suggested rewrites · Threshold verdict (publish/review/block) |
| **Business Logic** | Detects gender-coded language, age-coded language, ableist language, ethnicity-implicating language, and other bias patterns; uses Claude API for nuanced detection beyond keyword matching |
| **Error Handling** | If Claude API unavailable, falls back to Gemini API; if both unavailable, returns "scan unavailable — recruiter manual review required" |
| **Audit Trail** | All scans logged with detected biases and final action taken |

### 3.7 Module 7 — GDPR Subject Request Portal

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Handle candidate/expat data subject requests (access, export, correction, deletion) across all HCMS apps |
| **Trigger** | Called by HUMANABLE + ATLAS when a candidate/expat submits a GDPR request from their dashboard |
| **Inputs** | Subject identity · Request type (access/export/rectification/erasure/objection/restriction) · Justification (if required) |
| **Outputs** | Aggregated subject data across all HCMS apps · Export packages · Deletion confirmations · SLA tracking |
| **Business Logic** | Implements GDPR Articles 15-21; aggregates data subject's records from HUMANABLE, ATLAS, and Compliance Shield's own tables; orchestrates cross-app deletion when applicable; respects retention exceptions (active engagement, legal hold) |
| **Error Handling** | Deletion requests with active engagement trigger 30-day SLA workflow with manual review escalation |
| **Audit Trail** | Full GDPR request lifecycle logged with regulatory-required precision |

### 3.8 Module 8 — Right-to-Work Verification

| Aspect | Specification |
| :---- | :---- |
| **Purpose** | Structured ID + work-permit verification workflow with audit-grade documentation |
| **Trigger** | Called by HUMANABLE pre-offer for expat candidates; called by ATLAS at immigration track milestones |
| **Inputs** | Candidate ID documents (uploaded) · Work permit application status · Visa status · Employer sponsorship details |
| **Outputs** | Verification verdict · Document completeness check · Expiration calendar · Next-action checklist |
| **Business Logic** | Codifies Suriname's right-to-work documentation requirements per category (skilled worker, executive, dependent spouse, etc.) |
| **Error Handling** | Conservative verdicts; missing documents always block "verified" status |
| **Audit Trail** | Verification events permanently logged; documents linked to verification record |

---

## 4. Consumer Integration Patterns

### 4.1 Service Token Authentication

Each consumer app holds a long-lived service token issued by the Compliance Shield. Tokens are stored in consumer app `.env` files (e.g., `COMPLIANCE_SHIELD_TOKEN=...`). Tokens are rotated quarterly.

### 4.2 API Call Pattern (Example — Tax Pre-Flight)

```php
// In HUMANABLE — at offer drafting
$response = Http::withToken(config('services.compliance_shield.token'))
    ->post(config('services.compliance_shield.url') . '/v1/tax/pre-flight', [
        'expat_flag' => true,
        'net_salary' => 8500,
        'currency' => 'USD',
        'allowances' => ['housing' => 2500, 'transport' => 500],
        'assignment_months' => 24,
        'employer_id' => $employer->id,
    ]);

if ($response->successful()) {
    $taxData = $response->json();
    // Use $taxData['gross_up'], $taxData['tec_breakdown'], etc.
}
```

### 4.3 Failure Modes

| Failure | Consumer App Behavior |
| :---- | :---- |
| **Compliance Shield unreachable** | Consumer app blocks the workflow step requiring compliance check; logs to Sentry; alerts Operations Manager. No silent fallback (compliance is non-negotiable). |
| **Compliance Shield returns error** | Consumer app surfaces the error to the recruiter with the specific module's error message |
| **Compliance Shield rule update mid-transaction** | Each call returns the rule version applied; consumer apps log this for audit |
| **Authentication token rejected** | Consumer app alerts Operations Manager + IT immediately |

### 4.4 Per-Module Consumer Map

| Module | HUMANABLE Consumes | ATLAS Consumes |
| :---- | :---- | :---- |
| 1. 38% Expat Tax Pre-Flight | ✅ Offer drafting | ✅ Financial track setup |
| 2. Article 1639 Flag | ✅ Vacancy creation | (Read-only) |
| 3. Work Permit Pre-Screening | ✅ Shortlist | ✅ Immigration track |
| 4. Local Content Auto-Reporter | ✅ Employer reports | ✅ Employer reports |
| 5. EU AI Act Layer | ✅ All 8 AI agents | ✅ AI concierge + matchers |
| 6. Bias Detection | ✅ JD + scorecard publish | (Limited use) |
| 7. GDPR Subject Portal | ✅ Candidate portal | ✅ Expat portal |
| 8. Right-to-Work Verification | ✅ Pre-offer | ✅ Immigration track |

---

## 5. Data Model

The Compliance Shield owns its own PostgreSQL schema (`compliance_shield`) on the shared database server. Tables:

| Table | Purpose |
| :---- | :---- |
| `consumer_apps` | Registered consumer apps (HUMANABLE, ATLAS) with service tokens |
| `tax_calculations` | All Module 1 calculations with inputs/outputs |
| `article_1639_flags` | All Module 2 detections + Clean Break Protocol records |
| `work_permit_screenings` | All Module 3 screenings |
| `local_content_reports` | Generated reports + audit trail |
| `ai_decision_audit` | EU AI Act compliance — every AI decision logged across all consumer apps |
| `bias_scans` | All Module 6 scans + verdicts |
| `gdpr_requests_central` | All cross-app GDPR requests with SLA tracking |
| `gdpr_request_data_packages` | Aggregated subject data exports |
| `right_to_work_verifications` | All Module 8 verifications + document references |
| `rule_versions` | Versioned compliance rules — when rules change, version increments and consumer apps see the new version on subsequent calls |
| `rule_update_audit` | Audit trail of who/when/why compliance rules changed |
| `request_log` | Every inbound API call from consumer apps for observability + rate analysis |
| `error_log` | All errors with full context for IQT Lead debugging |
| `users` | Compliance Shield admin users (Compliance Advisor, IQT Lead) |
| `sessions`, `jobs`, `failed_jobs`, `cache`, `cache_locks`, `pulse_*`, `personal_access_tokens` | Laravel framework tables (database driver mandate) |

---

## 6. API Specification (REST Endpoint Inventory)

All endpoints versioned at `/v1/`. Authentication via Bearer token in `Authorization` header.

| Method | Endpoint | Module | Purpose |
| :---- | :---- | :---- | :---- |
| POST | `/v1/tax/pre-flight` | 1 | Calculate gross-up + TEC + tax exposure |
| GET | `/v1/tax/historical/{tax_calculation_id}` | 1 | Retrieve prior calculation |
| POST | `/v1/article-1639/check` | 2 | Crew take-over Article 1639 risk check |
| POST | `/v1/article-1639/clean-break/initiate` | 2 | Initiate Clean Break Protocol workflow |
| POST | `/v1/work-permit/pre-screen` | 3 | Validate expat candidate eligibility |
| GET | `/v1/work-permit/required-documents/{role_type}` | 3 | Get required document list per role type |
| POST | `/v1/local-content/report/generate` | 4 | Generate quarterly report |
| GET | `/v1/local-content/report/{report_id}` | 4 | Retrieve generated report |
| POST | `/v1/ai-audit/log` | 5 | Log AI decision (called before/after each AI inference) |
| POST | `/v1/ai-audit/override` | 5 | Log human override of AI decision |
| GET | `/v1/ai-audit/subject/{subject_id}` | 5 | Get all AI decisions for a data subject (GDPR Right to Explanation) |
| POST | `/v1/bias/scan` | 6 | Scan text for biased language |
| POST | `/v1/gdpr/request` | 7 | Submit subject access/export/deletion request |
| GET | `/v1/gdpr/request/{request_id}/status` | 7 | Check request status + SLA position |
| POST | `/v1/gdpr/request/{request_id}/fulfill` | 7 | Mark request as fulfilled (internal use) |
| POST | `/v1/right-to-work/verify` | 8 | Submit candidate ID + work-permit docs for verification |
| GET | `/v1/right-to-work/expirations/{employer_id}` | 8 | Get upcoming expiration calendar for employer's expats |
| GET | `/v1/health` | — | Health check for monitoring |
| GET | `/v1/rule-versions` | — | Current rule versions per module |
| GET | `/v1/admin/audit-log` | — | (Admin-only) full audit log |

OpenAPI/Swagger specification produced in Phase 0.

---

## 7. Suriname Compliance Knowledge Base (Codified Rules)

The Compliance Shield contains an internal knowledge base of Suriname compliance rules organized as versioned configuration. Rules are NOT hardcoded — they live in `rule_versions` table and are loaded into application memory at startup.

### 7.1 38% Expat Tax Mechanics (Module 1)

- Base income tax rate methodology aligned to current Suriname Belastingdienst guidance
- Treatment of housing, transport, school, and other allowances
- Gross-up methodology
- TEC composition: gross salary + employer statutory contributions (Pension/AVS 6.0% · Health/ZV 5.5% · Accident/OV 1.0%) + benefits in kind + HCMS administrative fee

### 7.2 Article 1639 Clean Break Protocol (Module 2)

- Detection patterns: contractor crew transfer language in inquiry/vacancy
- Risk levels: Low (no crew transfer) · Medium (some crew transfer) · High (full crew take-over)
- Clean Break Protocol steps: written notice · settlement agreement · documentation requirements · new employer agreement structure

### 7.3 Work Permit Framework (Module 3)

- Ministry of Labour (Min. ATM) categories and requirements
- Hoofd Vreemdelingendienst visa requirements
- Education/experience thresholds per role category
- Estimated processing times by category (currently 6–12 weeks typical)
- Required documentation per category

### 7.4 Local Content Thresholds (Module 4)

Per-operator configuration:

| Operator | Minimum Local Content Threshold | Reporting Cadence |
| :---- | :---- | :---- |
| TotalEnergies | Per contract | Quarterly |
| Newmont (Merian) | Per contract | Quarterly |
| Staatsolie | Per contract | Quarterly + annual |
| Chevron | Per contract | Quarterly |

Specific thresholds and reporting templates loaded from per-employer configuration.

### 7.5 EU AI Act Implementation (Module 5)

- High-risk AI system classification for HR/recruitment AI
- Transparency requirements (Article 13)
- Human oversight requirements (Article 14)
- Subject Right to Explanation
- Risk classification per AI use case

### 7.6 Bias Detection Patterns (Module 6)

- Gender-coded language patterns
- Age-coded language patterns
- Nationality/ethnicity-implicating patterns
- Ableist language patterns
- Suriname-specific cultural sensitivity patterns

### 7.7 GDPR + Suriname Data Protection Act (Module 7)

- Right of access (Article 15)
- Right to rectification (Article 16)
- Right to erasure (Article 17)
- Right to restrict processing (Article 18)
- Right to data portability (Article 20)
- Right to object (Article 21)
- Suriname Data Protection Act alignment (where applicable)

### 7.8 Right-to-Work Requirements (Module 8)

- Required documents per work permit category
- Document expiration tracking (passport · visa · permit · residence permit)
- Multi-year reminder calendar

---

## 8. EU AI Act Implementation Detail (Module 5)

### 8.1 What Gets Logged Per AI Decision

| Field | Purpose |
| :---- | :---- |
| Decision ID | Unique identifier |
| Subject ID | The candidate/expat the decision is about |
| Consumer app | HUMANABLE or ATLAS |
| AI agent name | E.g., "HUMANABLE Triage Agent" |
| AI provider | Claude or Gemini |
| Model version | E.g., "claude-3.5-sonnet-20250523" |
| Decision type | Screening / matching / generation / classification |
| Input data hash | Hash of the input (PII-sanitized) |
| Output / recommendation | What the AI suggested |
| Confidence score | If applicable |
| Reasoning | The AI's explanation |
| Human action taken | Approved / overridden / modified / pending |
| Override reason | If human overrode |
| Rule version | Compliance Shield rule version at time of decision |
| Timestamp | UTC + Suriname local |

### 8.2 Subject Right to Explanation Workflow

When a candidate/expat submits a "Right to Explanation" request via GDPR Module 7, the Compliance Shield:

1. Looks up all `ai_decision_audit` records for that subject
2. Generates a structured, human-readable explanation per decision
3. Filters out HCMS-internal-only details
4. Returns the explanation package to the consumer app for delivery

---

## 9. Update & Versioning Process

When Suriname tax/labour law changes (or any rule needs updating):

1. **Compliance Advisor** drafts the rule change in a structured proposal
2. **IQT Lead** reviews technical implementation
3. **CEO** approves the rule change
4. Engineering deploys the rule update — `rule_versions` table gets a new entry
5. Consumer apps automatically use the new rule version on their next call
6. Audit trail: `rule_update_audit` logs who/when/why
7. Optional: backward-compatibility window for existing in-flight calculations

This decouples compliance rule updates from app release cycles — critical for responsiveness when regulations change unexpectedly.

---

## 10. Build Phasing

The Compliance Shield runs in parallel with HUMANABLE and ATLAS. Both consumer apps need it operational by their Phase 9.

| Phase | Window | Scope |
| :---- | :---- | :---- |
| **CS Phase 0 — Bootstrap** | Weeks 1–2 (parallel with HUMANABLE Phase 0) | Repo setup, VPS infra, Laravel 13+ scaffold, CI/CD, CLAUDE.md, base schema |
| **CS Phase 1 — Auth + API Foundation** | Weeks 3–4 | Service token authentication, base API framework, health check, rule versioning |
| **CS Phase 2 — Modules 5, 7 (Cross-Cutting)** | Weeks 5–8 | EU AI Act logging (needed by every consumer AI call) · GDPR Subject Portal foundation |
| **CS Phase 3 — Modules 1, 3 (Core HUMANABLE Needs)** | Weeks 9–14 | 38% Expat Tax Pre-Flight · Work Permit Pre-Screening |
| **CS Phase 4 — Modules 2, 8 (Verification + Risk)** | Weeks 15–20 | Article 1639 Flag + Clean Break · Right-to-Work Verification |
| **CS Phase 5 — Modules 4, 6 (Reporting + Detection)** | Weeks 21–26 | Local Content Auto-Reporter · Bias Detection |
| **CS Phase 6 — Hardening + Integration Testing** | Weeks 27–30 | Integration tests with HUMANABLE + ATLAS · Performance tuning · Compliance Advisor sign-off |

**Total estimated build: ~30 weeks for v1.0** (runs Weeks 1–30 in parallel with HUMANABLE/ATLAS, ready for both apps' Phase 9 consumer integration).

---

## 11. Development Stack & Delivery Guidelines

The Compliance Shield inherits the HUMANABLE §29 / ATLAS §20 Development Stack & Delivery Guidelines verbatim. Key points:

- **Backend**: Laravel 13+ · PHP 8.3+ · Composer · Filament 3 (for Compliance Advisor admin UI) · Laravel Pulse
- **Database**: SQLite local · PostgreSQL 16 + pgvector production (schema `compliance_shield` on shared DB server)
- **Drivers**: Database driver for cache, queue, session
- **Storage**: Local disk on shared VPS + Google Drive offsite backup
- **Deployment**: Standard Laravel deployment via `composer install` → `npm install` → `npm run build` → `php artisan migrate` → cache commands
- **External services**: Claude API + Gemini API (approved as fallback) for Module 6 Bias Detection
- **Monitoring**: Self-hosted Sentry (shared with HUMANABLE + ATLAS)
- **Hosting**: Shared LiquidNet US VPS (16 GB RAM minimum)
- **No Docker, no Redis, no Meilisearch, no managed cloud services**

### 11.1 Approved External Services (Inherits from HUMANABLE §29)

- ✅ Claude API (Module 6 bias detection)
- ✅ Gemini API (Claude fallback)
- ✅ Gmail SMTP (notifications)
- ✅ Google Drive (backup destination)
- ✅ Self-hosted Sentry

No additional external services proposed for the Compliance Shield.

---

## 12. Decision Log & Open Questions

### 12.1 Locked Decisions (v1.0)

| # | Decision | Resolution |
| :---- | :---- | :---- |
| 1 | Architectural pattern | Separate Laravel microservice (not module inside HUMANABLE/ATLAS) |
| 2 | Deployment topology | Shared LiquidNet US VPS (co-located with HUMANABLE + ATLAS) |
| 3 | Database | Shared PostgreSQL server, separate `compliance_shield` schema |
| 4 | Inter-app communication | Internal HTTP REST with Laravel Sanctum service tokens |
| 5 | Network exposure | Internal-only, not public-facing |
| 6 | Module count v1.0 | 8 modules |
| 7 | Build phasing | Parallel with consumer apps, ready by Phase 9 of each |
| 8 | Rule update process | Compliance Advisor → IQT Lead → CEO; deployed independently of consumer release cycles |
| 9 | Stack alignment | Inherits HUMANABLE §29 Development Stack & Delivery Guidelines verbatim |
| 10 | Languages (v1) | English only (matches HUMANABLE/ATLAS v1.3 scope reduction) |

### 12.2 Open Questions for Final Sign-Off

| # | Question | Recommended Default | Status |
| :---- | :---- | :---- | :---- |
| 1 | Confirm dedicated Compliance Advisor for ongoing rule maintenance | Confirm (named role required) | Awaiting Chairman sign-off |
| 2 | Confirm quarterly rule audit cadence | Quarterly | Awaiting sign-off |
| 3 | Confirm `compliance-shield.internal` naming convention | Confirm | Awaiting IQT |
| 4 | Subject Right to Explanation SLA | 14 calendar days | Awaiting sign-off |
| 5 | Compliance rule versioning strategy (semver vs date-based) | Date-based (e.g., `2026-Q3-001`) | Awaiting IQT |
| 6 | Issue Engineering Handoff Authorization | **Awaits explicit user confirmation per "ask first always" governance** | **PRIMARY** |

---

## 13. Implementation Note for Engineering Team

1. **Read this FO in full before writing any code.**
2. **The Compliance Shield is a separate Laravel application** — its own repository, its own deployment pipeline, its own data schema.
3. **It is consumed by HUMANABLE and ATLAS via HTTP** — DO NOT add it as a dependency in their composer.json.
4. **Service tokens are HCMS's responsibility** — never commit them.
5. **The rule knowledge base lives in versioned database records**, not hardcoded constants — engineering provides the framework; Compliance Advisor provides the content.
6. **The Compliance Shield must be operational by Week 30** — both consumer apps' Phase 9 depends on it.
7. **EU AI Act logging is highest priority** (Module 5) — every consumer AI call must log here. Build this first.
8. **Performance considerations**: per-call latency target <200ms for synchronous calls (tax pre-flight, work permit pre-screening); asynchronous fine for report generation (Module 4).
9. **Audit trail completeness is non-negotiable** — every API call logged in `request_log`, every business decision logged in module-specific tables.
10. **Decision Log + Open Questions** records the WHY — refer when implementation choices arise.

---

## 14. Companion Documents

| Document | Purpose | Status |
| :---- | :---- | :---- |
| `HCMS-FO-HUMANABLE-Final-v1.3-2026.md` | Pillar I consumer app — calls Compliance Shield from offer drafting, vacancy creation, shortlist, AI agents, etc. | v1.3 — companion to this FO |
| `HCMS-FO-ATLAS-Final-v1.3-2026.md` | Pillar II consumer app — calls Compliance Shield from immigration track, financial track, AI concierge, etc. | v1.3 — companion to this FO |
| `HCMS-CLAUDECODE-ComplianceShield-BootstrapPrompt-2026.md` | Engineering bootstrap prompt | To be produced on request |

---

*HCMS N.V. — A K&K Heritage Group N.V. Company · Paramaribo, Suriname*
*Compliance Shield FO v1.0 LOCKED · Strategic Moat Codified · Engineering Handoff Pending User Confirmation*
*Authored by: Sovereign HCMS Architect (AI Head of Business Unit) · May 23, 2026*