# CASAN — Kiến trúc BEFORE → AFTER (Mốc 1: lúc mang đi thi)

> **File này = trạng thái "mang đi thi"** — commit freeze `fbcef96`, **trước** nhánh `feat/plan07-track-a-hardening`.
> So sánh với **base gốc** (bộ khung spec-kit vanilla trong ảnh). File tiếp theo (`CASAN_ARCHITECTURE_AFTER.md`) kể tiếp phần nâng cấp sau khi thi.
>
> 🖥️ **Bản trình chiếu trực quan (mở full-screen khi thuyết trình):** `casan-architecture.html` — mở trực tiếp bằng trình duyệt, có cả 3 mốc + 7 harness + 5 nhóm nâng cấp trên một trang.

---

## 0. Base gốc = bộ khung "spec-kit" vanilla (như ảnh)

Thư mục `.specify/scripts/bash/` ban đầu **chỉ có 5 file** — đây là khung tạo-đặc-tả tiêu chuẩn, **chưa có một dòng nào về an toàn / harness**:

| File base | Tác dụng | Thuộc về |
|---|---|---|
| `check-prerequisites.sh` | Kiểm tra công cụ/điều kiện trước khi chạy quy trình | spec-kit |
| `common.sh` | Hàm dùng chung (đường dẫn, tiện ích) | spec-kit |
| `create-new-feature.sh` | Dựng khung một feature mới theo đặc tả | spec-kit |
| `setup-plan.sh` | Dựng khung kế hoạch triển khai | spec-kit |
| `update-agent-context.sh` | Cập nhật ngữ cảnh cho agent | spec-kit |

*(Kèm `init-options.json`, `templates/`, `memory/`.)* → **Base chỉ biết "sinh khung dự án", không biết chặn tấn công, không ghi vết, không đo chi phí.**

---

## 1. Sau cải tiến (lúc thi): từ 5 → **37 script** + 8 bộ test

**Đã thêm 32 script CASAN** trên nền 5 file base, hiện thực **đủ 7 harness** (7 lớp bảo vệ) + các công cụ ký số/telemetry. Bảng dưới nhóm theo từng harness — **mỗi file là một mảnh của một lớp bảo vệ**.

### 🟦 H1 — Context (ngữ cảnh)
| File | Tác dụng |
|---|---|
| `context-validate.sh` | Kiểm tra `pipeline-context` hợp lệ — sub-agent lấy đường dẫn spec/artifact từ context, khỏi đoán |
| `casan-log.sh` | Ghi log theo cấp độ (debug/info…) cho toàn pipeline |

### 🟦 H2 — Tool (công cụ)
| File | Tác dụng |
|---|---|
| `tool-registry-gate.sh` | Đăng ký tool + **least-privilege** (agent chỉ gọi tool được phép) + **rate-limit** + **idempotency** (chống gọi lặp) |
| `validate-tool-input.sh` | Kiểm tra input gọi tool theo **JSON schema** — sai định dạng thì loại |
| `tool-exec.sh` | Chạy tool có **timeout cứng** — công cụ chạy loạn bị cắt giờ |
| `tool-audit-lib.sh` | Thư viện ghi **nhật ký mọi lần gọi tool** (hash-chain + ký) |
| `verify-tool-audit.sh` | Xác minh chuỗi nhật ký tool-calls còn nguyên vẹn |

### 🟦 H3 — Evaluation (đánh giá / model)
| File | Tác dụng |
|---|---|
| `model-router.sh` | Định tuyến model theo **vai trò** (classify / judge / generate) |
| `model-call.py` | Gọi model — **local (Ollama)** + đường **cloud (OpenAI/Anthropic)** |
| `model-fallback.sh` | Model A hỏng → tự chuyển sang model B |

### 🟥 H4 — Security (bảo mật)
| File | Tác dụng |
|---|---|
| `security-check.sh` | Quét **injection / secret / PII** ở **cả đầu vào lẫn đầu ra** |
| `artifact-scan.sh` | Quét **injection gián tiếp** giấu trong tài liệu **trước khi** vào ngữ cảnh AI |
| `security-gate.sh` | Cổng bảo mật tổng hợp — chạy loạt kiểm tra, ra một phán quyết chung |
| `pii-mask.py` | Che thông tin cá nhân (dùng chung bởi các control bảo mật) |

### 🟧 H5 — Governance (quản trị & nhật ký)
| File | Tác dụng |
|---|---|
| `governance-check.sh` | **Tách quyền (SoD)**, duyệt việc nhạy cảm, least-privilege |
| `verify-audit-chain.sh` | Xác minh **hash-chain** sổ kiểm toán — sửa 1 ký tự là gãy |
| `sign-audit-head.sh` | **Ký số HEAD** chuỗi audit (qua KMS hoặc khoá local) |
| `sign-policy-bundle.sh` | Ký gói **chính sách trung tâm** (dùng chung nhiều dự án) |
| `secrets-scan.sh` | Quét **secret lỡ commit** vào mã nguồn |
| `circuit-breaker-check.sh` | Quét **no-bypass** (không cho lách kiểm tra) + cầu dao ngắt khi model hỏng liên tiếp |
| `vault-kms.sh` | Ký qua **Vault Transit (KMS)** — chìa khoá nằm trong két |

### 🟨 H6 — AgentOps (vận hành & chi phí)
| File | Tác dụng |
|---|---|
| `agent-metrics.sh` | Đo **chi phí / độ trễ / token** mỗi bước + phát cảnh báo |
| `cost-spike-detect.sh` | Phát hiện **vọt chi phí** (bước tốn gấp N lần) |
| `drift-detect.sh` | Phát hiện **model đổi hành vi** theo thời gian |
| `hallucination-scan.py` | Quét **tín hiệu bịa đặt** trong output |
| `import-provider-telemetry.sh` | Nhập **số dùng thật** từ nhà cung cấp model |
| `provider-cost-lookup.py` | Tra chi phí thật theo từng bước |
| `business-kpi-report.sh` | Báo cáo **KPI nghiệp vụ** (cycle-time, rework…) |

### 🟩 H7 — Orchestration (điều phối)
| File | Tác dụng |
|---|---|
| `casan-harness.sh` | **Wrapper** chạy một bước qua **đủ các lớp harness** một mạch |
| `rollback-manager.sh` | **Rollback thật** khi một bước lỗi |
| `verify-harness-reuse.sh` | Chứng minh bộ harness **tái dùng được** cho nhiều dự án |

*(Kèm `guideH4-H5-H6.md` — ghi chú hướng dẫn.)*

---

## 2. Test lúc mang đi thi (8 bộ)

| Bộ test | Vai trò |
|---|---|
| `run-casan4-harness-tests.sh` | **35** kiểm thử happy-path + bằng chứng Level-5 |
| `adversarial-harness-tests.sh` | **44** đòn đối kháng (battery gốc) |
| `phase3-model-router-tests.sh` | Kiểm thử định tuyến model |
| `phase3-redteam-metrics.sh` | Đo **recall** red-team (model vs regex) |
| `phase3-judge-gate-tests.sh` | Cổng LLM-judge nhiều tầng |
| `generate-agentops-dashboard.py` | Sinh bảng theo dõi AgentOps (tĩnh) |
| `generate-casan-demo-context.py` | Sinh ngữ cảnh demo |
| `run-casan-harness-tests.ps1` | Bản PowerShell (Windows) |

---

## 3. Tóm tắt Mốc 1 (một dòng)

> **Base vanilla 5 file "chỉ sinh khung dự án"** → **CASAN lúc thi 37 script hiện thực đủ 7 lớp bảo vệ** (chặn injection, ghi vết ký số, đo chi phí, điều phối + rollback) — **chứng minh bằng ~79 kiểm thử đối kháng**.
>
> **Trạng thái công tâm lúc thi:** đây là mức **demo/PoC tốt** — chặn được tấn công trên sân khấu. Ba lớp H4/H5/H6 khi đó mới ~3.0/5, còn nhiều đường lọt "sát production" chưa vá (né tránh nâng cao, quản trị khoá, xoá nhật ký, alerting thật…).
>
> 👉 Những đường lọt đó chính là nội dung **`CASAN_ARCHITECTURE_AFTER.md`** — phần nâng cấp `feat/plan07-track-a-hardening` sau khi thi.