update doc and optimize

casan-next-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)._