# AEGIS CYBER - Replit Agent Guide

## Overview
AEGIS CYBER is an enterprise-grade Agentic AI cybersecurity platform designed for African banking infrastructure, specifically targeting Uganda initially. Its primary purpose is to provide real-time threat detection, insider threat monitoring, automated compliance (Uganda's PDPO 2019), and robust role-based access control. The platform functions as a "Cognitive Security Layer" to identify anomalies in transactions, employee behavior, and network activity with sub-200ms response times. Key capabilities include Know Your Transaction (KYT), Agentic Commerce Guardrails, and a SupTech Gateway for regulatory reporting. The project aims to significantly reduce financial crime and operational risk in the African banking sector, with a strategic vision to evolve into a multi-tenant commercial platform.

## User Preferences
Preferred communication style: Simple, everyday language.

## Standing Agent Rules — POINTER INDEX

**Full verbatim text of all twenty-two mandatory agent rules lives in `docs/regulatory/STANDING_AGENT_RULES.md` (the Rule-12 slot is a deliberate non-addition, recorded there for audit clarity).** The one-line entries below are pointers, not the rules themselves — they are not sufficient on their own. Before acting on any rule-governed operation the agent must read the full text in that file, which carries the dated incident anchors, exception cases, worked examples, and the "supersedes any local convenience argument" closing imperatives that make each rule operationally load-bearing.

This pointer index replaces the previous inline rule blocks (relocated 2026-05-23, audit trail in FU-029, pre-reorg snapshot at `docs/regulatory/REPLIT_MD_SNAPSHOT_PRE_REORG_2026-05-23.md`).

1. **Credential and secret handling.** Never print/echo a secret's value (even partially, even for debugging); safe checks only (length / existence / hash); leak → stop and recommend rotation. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 1
2. **Schema deployment and pre-publish topology check.** `db:push` only touches dev; any schema-dependent publish needs the prod-SQL operator runbook + SELECT verify + post-publish topology smoke — on every schema-touching publish, not just the first. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 2
3. **AEGIS Security Audit + Carve-Outs Register refresh cadence.** Monthly, anchored to the 15th (audit on the 15th, register update within five business days, operator sign-off by month-end); a BoU-disclosed governance commitment. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 3
4. **Pre-rebuild runbook surfacing.** Before supporting any rebuild action, read `docs/regulatory/LAPTOP_REBUILD_RUNBOOK.md`, paste its Pending section, and await operator ack; trigger words include rebuild / repackage / new zip / down -v / --no-cache. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 4
5. **Realistic-not-aspirational claims.** Evaluate every claim against the codebase, not the prior artefact; three states (implemented + measured / implemented, unmeasured / not implemented); load-bearing words need verification before use. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 5
6. **Verify-before-asserting.** No completion claim without explicit evidence (build / smoke / regression / audit-chain) — observed, never inferred. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 6
7. **Dual-environment preservation.** A change to one environment (Replit / Docker laptop / bank prod) must preserve the others unless the operator authorises a single-environment change; surface impact first, test all affected. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 7
8. **Documentation-update obligation.** Operator-facing code changes require same-session doc updates; documentation drift equals a code-change failure. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 8
9. **Architect-review obligation.** Architect review BEFORE commit for `server/lib/` auth / session / audit-chain / encryption / tenant-isolation / KYT changes, security-table schema changes, `secret-boot-guard`, and security-purpose `docker-compose.yml` env changes. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 9
10. **Forbidden-files discipline.** No edits to `package.json`, `package-lock.json`, `vite.config.ts`, `drizzle.config.ts`, or any `tsconfig*` without explicit operator authorisation — including tooling (e.g. `npm install`) that rewrites them. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 10
11. **Backup-before-destructive-operation.** Any operation that destroys/replaces data, configuration, or deployment state needs explicit operator authorisation with the destruction stated plainly; no implicit destructive ops. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 11
12. *(Rule 12 slot is a deliberate non-addition audit record from 2026-05-23 — see `docs/regulatory/STANDING_AGENT_RULES.md` Rule 12 for the analysis.)*
13. **Publish-on-substantive-completion cadence.** Surface publish readiness at each substantive completion, not after several accumulate; docs-only / intermediate-WIP / framework-only edits do not trigger; surface accumulating publish-debt whenever the operator batches. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 13
14. **Deployment must verify function before serving (fail-fast).** Security-control init must assert FUNCTION (not mere existence) and `process.exit(1)` on failure before serving; a broken control crashes boot, never serves under a false-green state. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 14
15. **Logs may only assert what was verified.** Security-control success logs must state exactly what was checked ("present, predicate NOT verified" vs "present AND predicate-verified"); never imply more verification than occurred. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 15
16. **Idempotency must be effect-idempotent, not structure-idempotent.** "Skip if exists" on security-critical DDL (grants / roles / constraints / policies) is a hazard — existence ≠ correctness; use DROP+CREATE and sweep `server/` for the pattern. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 16
17. **Functional verification is per-environment and non-transitive.** A dev pass gates dev only; prod is not verified until the prod functional probe passes. The RLS diagnostic endpoint is PERMANENT prod infrastructure — re-run after any RLS / policy / grant / `current_tenant_id()` change. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 17
18. **Probe meta-rule: passes must pass for the right reason.** Pair every denial assertion with a positive-enforcement assertion in the same run; a denial pass without its paired positive is HOLLOW-GREEN (FAIL). → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 18
19. **Reporting format: tag every claim verified-vs-assumed.** Distinguish functionally-verified (with how) from deployed / assumed / structural (with the outstanding check named); never collapse "deployed" into "working." → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 19
20. **Pre-deploy standing-rules checklist.** Before any security-critical publish, state inline which rules apply and confirm each is satisfied with evidence, and surface the list to the advisor — a gate, not a reminder. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 20
21. **State-derivation discipline.** Derive current state from the authoritative record (FOLLOW-UPS.md closures AND git history, both required) at point-of-use, not from context / plan / prior turns; per-claim grounding; the record overrides the session plan; "re-grounded" labels are themselves state-claims. → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 21
22. **Destructive instructions to the operator must be exact and verified.** Before any delete/revoke/drop/disable/destroy instruction to the operator: verify the exact target from the authoritative source, name it precisely (never "the secret"/"the file"), explicitly list adjacent items NOT to touch and why (esp. similar names in the same pane), state what breaks if the wrong one goes, and if the target can't be verified, flag it rather than instruct. Governs agent→operator hand-instructions (complements Rule 11's agent-performed destruction). → `docs/regulatory/STANDING_AGENT_RULES.md` Rule 22

**Reversibility commitment.** Any rule that produces friction without proportionate value over coming weeks of work gets surfaced explicitly and retired with the same explicit process as its addition. The discipline framework is reversible, not permanent.

## System Architecture

### UI/UX
React 18 + TypeScript frontend (Wouter routing, TanStack React Query) styled with Tailwind CSS / shadcn/ui and Framer Motion. Ships the "Sovereign UI 2026 Edition": a high-contrast dark mode emphasising "Cognitive Ergonomics" — Crisis Mode UI, Glassmorphism HUD Cards, an AI Confidence Pulse, and an Auditor Mode — with real-time updates over WebSockets.

→ Full UI/UX narrative relocated to `docs/regulatory/ARCHITECTURE_DETAIL.md` (Relocated from replit.md 2026-06-19).

### Technical Implementations
Express.js 5 + TypeScript backend (REST + WebSocket) with token auth, bcrypt, Helmet, token-based CSRF, a fail-fast boot-time secret guard, and Drizzle ORM on PostgreSQL; resilience via circuit breaker, idempotent APIs, immutable log-chaining, a Sovereign Readiness Suite, and 6-node Sovereign Edge. Multi-tenant isolation is a three-layer substrate (per-request GUC writer + session-derived tenant resolution + PostgreSQL RLS), with AES-256-GCM field-level encryption across credential and customer-PII surfaces, Admin / Risk Manager / Auditor RBAC, SHA-256 audit-chaining, and Anthropic Claude threat scoring. Real PQC is limited to ML-KEM-768 (FIPS 203, KAT-verified); ML-DSA-65 and the `/api/pqc/handshake` route remain simulation. Compliance/governance, KYT, the AEGIS SOAR financial-crime case spine (prod-live through M4, HELD at the prod gate), and the made-real Class-A assurance surfaces are detailed in the relocated narrative.

→ Full technical narrative relocated to `docs/regulatory/ARCHITECTURE_DETAIL.md` (Relocated from replit.md 2026-06-19); per-finding verification receipts in `docs/regulatory/FOLLOW-UPS.md`.

## Engineering record

Detailed engineering history — incident remediations, follow-up tickets, architectural decisions, audit responses, and dated closure records of carry-list items — is maintained in `docs/regulatory/FOLLOW-UPS.md`. That follow-up register is the source of truth for `FU-XXX` entries and session-notes entries; this file is a high-level architectural reference only and is deliberately minimal because top-level reference documents are subject to automated compression that may summarise away detailed inline entries.

Operational knowledge about the Replit environment itself — discovered during build work, not about the platform under build — is collected in `docs/regulatory/PLATFORM_BEHAVIOUR_NOTES.md`. Brief working-reference format; current entries cover compression behaviour, tsconfig cache invalidation, commit-message drift, gitSha-null-in-prod-deploys, ir-drill-rows-persist-in-incident_slas, and the neondb-vs-heliumdb topology discovery with its LOGIN-row diagnostic.

**Prod invariants** (mirrors `docs/regulatory/PLATFORM_BEHAVIOUR_NOTES.md` — that file is the single source; these two are inlined because their silent loss is the most dangerous. The other three — esbuild-strips-identifiers, FOLLOW-UPS-needs-bash, house-style — stay as pointers there):
- **Prod `executeSql` is a read-only, RLS-bypassing replica (runs as `neondb_owner`).** Writes/DDL are refused (INSERT/UPDATE/DELETE/DDL blocked; queries transaction-wrap then ROLLBACK with no row data) — never attempt a prod write, and never a dev-style rolled-back role-switched isolation probe in prod, because the owner path bypasses RLS so such a probe is hollow-green there.
- **`aegis_app` is the app's RLS-subject role (non-superuser, non-`BYPASSRLS`); the owner role bypasses RLS.** Tenant-isolation checks MUST run as `aegis_app` (the least-privilege role real requests use) or they are hollow-green.

## Build priority — POINTER

**Active build ordering is maintained in `docs/regulatory/BUILD_PRIORITY_LIST.md`.** That file is the working order for outstanding build work (P0 through P5 with gate / deliverable / status per item), established 2026-05-23 by operator instruction "I don't want to defer any development." The carry list below remains the inventory snapshot of deferred / parked items; the priority list is the order in which the agent works through them.

**Publish-prerequisite gate (G0) — top of `BUILD_PRIORITY_LIST.md` (added 2026-06-17).** No schema-touching publish proceeds until EITHER the publish-time DB-migration-validator vs app-owns-its-schema collision is permanently fixed (Replit-support baseline resync + the Rule-9 refactor moving constraint ownership to the Drizzle schema file, leaving boot DDL to own only RLS policies) OR the operator consciously budgets the empty-migration drop-window in advance for that publish. Root cause + workaround receipts: FU-088; reusable quirk: `docs/regulatory/PLATFORM_BEHAVIOUR_NOTES.md`.

## Carry list (active items only)

Items currently deferred or parked. Do not act on any of these without explicit operator instruction. Closure records for previously-resolved carry items have been relocated to `docs/regulatory/FOLLOW-UPS.md` (search "Carry-list closure"); the audit trail is preserved by relocation, not deletion.

**Forward-looking from the 2026-05-13 session (full record in `docs/regulatory/FOLLOW-UPS.md` under "Session notes — 2026-05-13"):**
- Wave-13 BLOCKED badge: deterministic by-design fails per FU-003. **Do not act on Wave-13 BLOCKED without explicit operator instruction.**

**Agent-buildable (needs operator authorisation, not auto-batchable):**
- *(currently empty)*

**Deferred by design:**
- **FU-015** — UBO-aware erasure path. Open-deferred design surface, not a defect.

**Parked — surface as pre-deployment hygiene at end of build:**
- **MLCO_PASSWORD prod provisioning — DISCHARGED 2026-06-15 (FU-071).** MLCO_PASSWORD is now set in prod (required prodOnly boot secret satisfied; post-publish boot clean), the permanent second-senior `mlco` account is prod-live + scoped (role risk_manager, single aegis-sovereign binding), and the prod-positive two-eyes STR disposal proof is complete (admin maker → mlco checker → DISPOSITIONED, self-approve rejected 409 self_approval paired with the 200 positive). No longer a pre-deployment gap; closure record in FU-071.
- **Dev login credentials.** Operator cannot log in to the dev UI (a credentials puzzle, not an engineering defect; suspended 2026-05-08 by operator decision). Does NOT block platform operation, agent-assisted work (agent operates against codebase + DB directly), prod operation (operator logs in via the browser per the runbook), or any open FU. Do not debug dev login during normal build work; surface as pre-deployment hygiene when end-of-build approaches (clean deployments will likely re-establish dev credentials anyway) — must not disappear silently.
- **Synthetic prod test rows** (harmless: synthetic, encrypted-or-opaque, no PII; mostly non-approved / zero-disposition — the lone exception is the M3 prod-positive two-eyes proof case `6d894ee0`, intentionally APPROVED + DISPOSITIONED to prove the disposal works (still synthetic, opaque subjectRef, no PII); agent prod SQL is read-only and the seams expose no delete route, so remove in the natural maintenance step — no one-off delete route; linked `audit_chain_entries` are immutable by design and stay). **Full records in `docs/regulatory/FOLLOW-UPS.md`:**
  - KYC F1 walkthrough customer `6df338d1-6c05-4436-a56d-53e98e440d5f` (`kyc_customers`, REVIEW_REQUIRED, national_id encrypted) — KYC v1 Feature 1, 2026-06-13.
  - KYC F3 live-refusal decisions `a2eeded2-c812-4a02-89e2-962fe0d78b6b`, `180ff95e-f5a8-484d-88e7-3bb40a4e5ec2` (`kyc_decision_outcomes`, ESCALATE_TO_EDD / R-INDETERMINATE, against `6df338d1`) — KYC v1 Feature 3, 2026-06-14.
  - KYC F4 prod-probe examiner tokens (2× synthetic, `examiner_tokens`, 1h TTL, `f4probe@test.local`; Token B revoked, Token A expired) — KYC v1 Feature 4, 2026-06-15.
  - AEGIS SOAR Gate-2 case `c73c6026-5132-4bda-9973-95b2c4448f48` (`fincrime_cases` OPEN, opaque subject_ref) + its `CASE_OPENED` event + audit entry 9988 (immutable) — FU-066, 2026-06-15.
  - AEGIS SOAR M2 case `65543088-21a2-45b6-84a7-da3f2f3c538a` (`fincrime_cases` PENDING_MLCO_REVIEW, opaque subjectRef) + 4 `fincrime_case_evidence` + 7 `fincrime_case_events`; audit 10048–10052 immutable — FU-068, 2026-06-15.
  - AEGIS SOAR M3 prod-positive two-eyes disposal case `6d894ee0-2600-47f3-8d19-43d90f7ca7db` (`fincrime_cases` DISPOSITIONED/STR_RECOMMENDED, opaque subjectRef) + STR `c8207a47-da44-4b5c-9ea0-8cca172c53f0` (PREPARED, ack cols NULL) + approval `443624ee-59b7-4f55-ad54-2c913e0e5b30` (mlco checker) + 8 events/2 evidence; audit 10139–10143 immutable — FU-071, 2026-06-15.
  - AEGIS SOAR M3 self-approval-probe case `89615ca8-4dad-4e65-9633-99322ff90ce2` (`fincrime_cases` PENDING_MLCO_REVIEW; PREPARED STR never finalized, 0 approvals) — FU-071, 2026-06-15.
  - FU-107 Smoke A live-prod DSAR `3beeb004-3cf2-4c04-9a30-860e1e8db723` (`dsar_requests`, reference DSAR-2026-54EAF8, status received, PII AES-256-GCM `ENC:v1:`, tenant aegis-sovereign) + linked `dsar_audit_trail` received entry + `notification_logs` `559eac44…` (status sent, via auditDb) — FU-107 hotfix prod behavioral smoke (Smoke A), 2026-06-21. Opaque synthetic subject, no real PII.

**Closed (audit trail — closure records in `docs/regulatory/FOLLOW-UPS.md`):**
Closed carry items relocated to FOLLOW-UPS.md per the line-82 instruction above. Search: FU-032 (BoU security dossier), FU-033 (BOU_NARRATIVE_DRAFTS amendments — Wave-11 §1 paragraph, Wave-13 reframe).

The `proposeFollowUpTasks` channel is closed for this project per the operator's standing instruction; do not attempt to use it.