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-08: 🟡 Governance CORE + Track 1 Read-only Ops Console DONE. Track 1 built: real NestJS API + React UI at packages/casan-control-panel/ (read-only monitoring over harness telemetry: overview/runs/governance/security/incidents/tools/ traceability/drift/cost + stale-aware /healthz). Backend tests 7/0; API serves REAL data; harness gate untouched (64/0/3). Run: npm run console:api + npm run console:ui. Còn (Track 2/3/4): settings writes (wrap control-plane-settings.py), RBAC+approval inbox (Plan-14), FinOps/SLO + docker/deploy + TLS/OIDC (07 T2).

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: packages/casan-harness/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 packages/casan-harness/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.

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í: packages/casan-control-plane/ (sibling packages/casan-harness; Plan-01 ✅ done). 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).