# KẾ HOẠCH 04 — Khép vòng tự cải tiến (`casan improve`)

> Status 2026-07-06: **🟡 core implemented + tested (harness-owned).**
> `packages/casan-harness/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 <id>`: 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<br/>usage · audit · drift · KPI"] --> DRY["casan improve --dry-run<br/>sinh proposal + diff"]
    DRY --> REV{"Người/governance<br/>duyệt"}
    REV -- "REJECT" --> T
    REV -- "APPROVE" --> APP["casan improve --apply<br/>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á.