CASAN/docs/plans/CASAN_PLAN_13_CONTROL_PLANE.md

# 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)._