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/2/3 + FinOps/SLO + Command Center + local-prod deploy smoke DONE (managed prod còn). 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/command + stale-aware /healthz). API serves REAL data; harness gate untouched (64/0/3). Run: npm run console:api + npm run console:ui. Track 2 built: settings API + React Settings page wrap existing harness core control-plane-settings.py and call rbac-check.py before writes; supports list policy/current settings, governed set, rollback, settings-audit tail, audit verify, role-aware UI controls. Track 3: kill-switch API + Incidents UI call kill-switch.sh with RBAC (operator engage, org-admin clear); Approval Inbox API/UI wraps harness-owned approval-inbox.py; delegation-policy.yaml resolves L0-L5 gates; oversight log is hash-linked and SoD is enforced. Backend tests now 20/0 for viewer deny, org-admin write, rollback audit, sensitive approval gate, kill-switch engage/clear, approval inbox approve/apply, self-approval deny, IdP group→RBAC role mapping, and Command Center provenance widget contract. Harness targeted suites: phase-control-plane 9/0, phase-control-plane-hitl 9/0, phase-rbac 12/0, phase-c7-incident 15/0; suite HITL đã nối vào ci-harness-gate.sh. Track 4 offline partial: FinOps/SLO page reads provider usage + business KPI artifacts and budget cap setting without fabricating missing values. Command Center §8.6 built: GET /api/v1/command returns nine evidence-backed widgets, including Plan-18 chat_loop, with {source, artifact_path, commit, run_at, verified} envelopes; React /command page has executive briefing VI/EN, live governance ticker, and evidence drawer. Deploy scaffold + local-prod smoke: Dockerfile.control-panel-api, Dockerfile.control-panel-ui, docker-compose.control-panel.yml, docker-compose.control-panel.local.yml, nginx/control-panel.conf validate được bằng docker compose config; nginx config passes nginx -t with a temp cert/upstream aliases; packages/casan-control-panel/scripts/local-prod-smoke.sh passes CP_LOCAL_SMOKE_PASS https_oidc=true actor=oidc-ops role=org-admin and asserts /api/v1/command returns all 9 widgets with provenance envelopes. prod-readiness-check.sh validates managed-prod host prerequisites (compose, TLS, oauth2-proxy OIDC env, nginx) without printing secrets. managed-prod-smoke.sh validates deployed endpoint auth enforcement (unauth blocked, spoofed identity headers blocked) and, with a real IdP cookie jar, authenticated /settings + /command behavior. Local-prod now runs that managed smoke with the mock-IdP authenticated cookie jar and emits CP_MANAGED_SMOKE_PASS actor=oidc-ops role=org-admin widgets=9. Nginx auth_request overwrites identity headers and API maps IdP groups → RBAC roles. Còn: managed host/cert/enterprise IdP env thật (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). Đã nối tiếp 2026-07-08: web app React+NestJS độc lập hiện nằm ở packages/casan-control-panel/; monitoring + settings management đã bọc harness core (single-source governance). Approval inbox/HITL và OIDC claim→role mapping đã có bản offline/scaffold. Còn lại: live 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 (SoD + reason), ghi audit	✅ self-approve DENY; approve setting proposal → apply qua governed store
13H.3	Oversight log view (ai-duyệt-gì) + xuất vào RAI report	✅ 1 quyết định → truy được actor/reason/time/hash

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 key harness dùng) qua API/UI bọc core CLI	ghi setting → version mới + giữ cũ	✅ API/UI hoạt động
13.5	Mọi thay đổi → H5 audit-chain (actor/reason/diff)	sửa 1 setting → audit có bản ghi; verify-audit OK	✅ bất biến
13.6	Rollback setting qua governed store	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	✅ settings API enforcement
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	✅ inbox + SoD + claim mapping
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	✅ API/UI bọc kill-switch.sh

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 UI cảnh báo từ cap setting; policy chặn nằm H6
13.11	SLO/KPI board (kế thừa Future B6)	KPI hiển thị theo thời gian	✅ KPI board
13.12	Deploy production-like: host + TLS + OIDC (nối Plan-07 T2.3/T2.6)	truy cập qua HTTPS + OIDC, không auth → chặn	✅ local-prod smoke + authenticated managed-smoke on local-prod + prod-readiness checker; live managed run cần cert/IdP/host thật

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 qua Control Panel: 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.
• Các key settings đang whitelist trong control-plane-settings.py quản lý được qua console (compression/cost/model/security/kill-switch/loop); kill-switch UI có.
• FinOps/SLO board đọc provider usage + business KPI artifact thật; thiếu budget cap thì báo chưa cấu hình.
• Approval inbox + delegation L0-L5 + oversight log có API/UI và test SoD/apply.
• Command Center §8.6 có API/UI: 9 widget evidence-backed (gồm chat_loop), provenance envelope, executive briefing VI/EN, live ticker, evidence drawer.
• Local production-like deploy có TLS + OIDC + oauth2-proxy + nginx auth_request; smoke pass qua HTTPS.
• Managed production readiness checker cho cert/host/enterprise IdP env thật.
• Managed production endpoint smoke script cho unauth/spoof/authenticated-cookie checks.
• Authenticated managed endpoint smoke pass trên local-prod HTTPS/OIDC endpoint (CP_MANAGED_SMOKE_PASS actor=oidc-ops role=org-admin widgets=9).
• Managed production deploy với cert/host/enterprise IdP thật (nối Plan-07 TIER 2).
• Red-team mục 5 targeted xanh: control-plane 9/0 + HITL 9/0 + RBAC 12/0 + C7 15/0; full gate dài đã pass qua adversarial 44/0 nhưng A6 mất thời gian nên không claim full-gate xanh trong lượt này.

7. Ghi chú trung thực

• 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ý" hiện đã đi qua Plan-14 RBAC + approval/HITL + H5 audit; prod thật vẫn cần enterprise IdP/cert/host.

8. Kế hoạch thực thi — web app độc lập (historical baseline; đã build trong packages/casan-control-panel/)

Governance core (settings + RBAC) nằm trong harness và test xanh. Web app là lớp trình bày bọc core, không chứa logic governance riêng. Baseline này đã được hiện thực trong packages/casan-control-panel/; §8.6 Command Center và Ask CASAN read-only đã có, các mục còn lại nên đi theo RAI view, Chat MVP-1 Operator, hoặc managed production rollout.

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)	✅ npm run console:build
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	✅ npm run console:test 20/0
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	✅ backend/API coverage + targeted harness suites; frontend unit can be added later
13W.5	Deploy prod: host + TLS + OIDC (nối Plan-07 T2.3/T2.6)	✅ local-prod smoke; 🔌 managed prod

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	phase3-real-run-scoring.md + telemetry counts	GET /api/v1/command
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)	approval store + oversight	GET /api/v1/command
V3	Kill-switch đỏ + guardrail badges (deny-by-default)	Kiểm soát / rollback / accountability	incidents.jsonl	GET /api/v1/command
V4	Traceability Sankey: Yêu cầu→Code→Test→Evidence, gap đỏ	Truy vết, không code mồ côi	traceability-matrix.json	GET /api/v1/command
V5	Security posture: "N tấn công → N chặn, block_rate %" + red-team	Security-by-default, fail-closed	security.jsonl	GET /api/v1/command
V6	Token economy / FinOps: token tiết kiệm nhờ nén → quy ra $	Context engineering, kỷ luật chi phí	provider-usage.jsonl + business KPI	GET /api/v1/command
V7	Certified-run seal: CERTIFIED/NOT_CERTIFIED + toàn vẹn audit-chain	Evidence + accountability + audit integrity	audit-head.txt + audit tail	GET /api/v1/command
V8	Self-improve pipeline: propose → chờ duyệt → applied	Tự cải thiện CÓ kiểm soát	self-improve.py primitive + approval proposals	GET /api/v1/command

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 telemetry hiện có; nguồn quyết định vẫn là harness.
• Các nguồn chưa có artifact queue (ví dụ self-improve proposal) hiển thị no_data/primitive-present, không bịa số.
• Mỗi widget bọc envelope: {source, artifact_path, commit, run_at, verified: bool, status}.

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	Chuẩn hóa envelope provenance trong Control API; core --json bổ sung sau khi có widget cần gọi CLI live	✅ commandCenter() envelope có source/artifact_path/commit/run_at/verified/status
13V.1	API GET /api/v1/command gom 9 widget đọc-only, không ghi state	✅ console:test contract 26/0
13V.2	V1 Maturity gauge + radar H1–H7 (click widget → evidence drawer)	✅ /command widget + drawer
13V.3	V2 HITL panel + approvals inbox/oversight	✅ đọc approval store; thiếu artifact → no_data
13V.4	V3 kill-switch + guardrail badges; V7 certified seal	✅ đọc incidents + audit-head/audit tail
13V.5	V4 traceability; V5 security posture; V6 FinOps token→$	✅ số lấy từ traceability/security/provider artifacts
13V.6	V8 self-improve pipeline	✅ hiển thị primitive present + proposal nếu có trong inbox; không fabricate queue
13V.7	Executive Briefing mode (song ngữ VI/EN) + Live ticker + Evidence drawer dùng chung	✅ /command page
13V.8	Provenance guard: thiếu source→no_data/missing, stale vẫn qua freshness	✅ contract test + UI status badge
13V.9	Widget Loop/Chat chuyên sâu	✅ chat_loop widget + ticker/budget/replay evidence drawer (Plan-18 Track 8.3)

Hiện trạng: Command Center baseline và Widget Loop/Chat chuyên sâu đã có. RAI view nằm ở Plan-15 follow-up, không còn chặn Plan-13 baseline.

---

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