doc update

2026-07-06 23:26:19 +09:00
parent d695a598ee
commit 0c60ed33e9
4 changed files with 651 additions and 0 deletions
@@ -0,0 +1,201 @@
+# KẾ HOẠCH 17 — Loop Engineering / Agentic Loop Governance
+
+> Status 2026-07-06: **📋 planned — CHƯA implement.** Đây là plan thiết kế; không có
+> code trong đợt này. Mục tiêu: nâng CASAN từ "governance rời rạc" thành **Agentic
+> Loop Governance** — kỹ thuật hoá **vòng lặp agent** (không chỉ prompt).
+>
+> Nhãn trạng thái: xem legend ở `CASAN_BACKLOG_STATUS.md`.
+> Phụ thuộc: **07** (H5 audit chain, H6 AgentOps, C4 approval) · **10** (H3 eval —
+> gate mỗi vòng) · **13** (Control Plane — widget Loop + governed loop-policy) ·
+> **14** (RBAC — nới budget cần org-admin) · **16** (fail-closed, approval JWT thật,
+> secure-by-default — Plan-17 PHẢI tuân các bài học này) · **04** (self-improve —
+> meta-loop). Bổ trợ **08** (context compaction giữa các vòng).
+
+---
+
+## 1. Bối cảnh — vì sao cần "loops engineering"
+
+**Prompt engineering** tối ưu **một lần gọi**: câu vào tốt → câu ra tốt. Độ tin cậy
+phụ thuộc model + prompt, không có bảo đảm hệ thống.
+
+**Loops engineering** tối ưu **vòng lặp bao quanh model**: `observe → plan → act →
+verify → correct → lặp`, với **điều kiện dừng, gate mỗi vòng, ngân sách, phát hiện
+không hội tụ, phục hồi lỗi, leo thang cho người**. Độ tin cậy đến từ **cấu trúc vòng
+lặp**, không phải một prompt hoàn hảo.
+> *Prompt tốt cho câu trả lời hay; loop tốt cho **hệ thống đáng tin**.*
+
+### CASAN đã có sẵn bộ máy loop (đối chiếu FPT §10.4, §4.4, §14)
+7 harness component chính là cơ khí của một vòng lặp được kỹ thuật hoá:
+
+| Yếu tố loops-engineering | CASAN đã có |
+|---|---|
+| Cấu trúc lặp observe→act→verify→correct | **H7 Orchestration / điều phối** (FPT §10.4) |
+| Gate kiểm định mỗi vòng | **H3 Evaluation/Validation** + `security-check` action-gate |
+| Guardrail trong vòng (fail-closed) | **H4 Security** (deny-by-default) |
+| Leo thang cho người khi bí/rủi ro | **H5 Governance** + HITL approval (L0–L5, §4.4) |
+| Quản trị ngữ cảnh giữa các vòng | **H1 Context** + `context-compress.py` |
+| Quan sát/trace theo vòng | **H6 AgentOps** + audit hash-chain |
+| Cải thiện chính vòng lặp | `self-improve.py` (propose ≠ apply) |
+
+**Kết luận:** CASAN vốn là loop-engineering nhiều hơn prompt-engineering — chỉ **chưa
+đặt tên và chưa formalize các "loop primitive" hạng nhất.**
+
+### Khoảng trống (5 primitive còn thiếu)
+1. **Loop Budget Governor** — trần số bước / token / thời gian / chi phí mỗi vòng lặp → tự dừng (loop-breaker). *Chưa có.*
+2. **No-progress / Oscillation Detector** — phát hiện lặp cùng hành động hoặc không tiến gần mục tiêu → halt/leo thang. *Chưa có.*
+3. **Per-iteration Verify Contract** — mỗi vòng phải qua gate mới sang vòng sau; fail → correction có cấu trúc, không retry mù. *H3 có gate nhưng chưa là hợp đồng theo vòng.*
+4. **Loop Trace / Replay** — ghi từng vòng (state/action/verdict) để audit & tua lại một loop. *Audit chain có mảnh, chưa có "loop view".*
+5. **Meta-loop** — self-improve đề xuất sửa chính loop-policy → người duyệt. *Có self-improve, chưa mở sang loop policy.*
+
+---
+
+## 2. Nguyên tắc (bắt buộc, kế thừa Plan-16)
+- **Fail-closed toàn diện:** mọi primitive lỗi/thiếu dữ liệu/không đọc được policy ⇒ **HALT vòng lặp** (không "cho chạy tiếp"). Không có đường thoát fail-open.
+- **Deny-by-default budget:** run không có policy khớp ⇒ áp **ceiling mặc định chặt nhất**, không phải "vô hạn".
+- **Secure-by-default (không opt-in):** trong profile `prod`, loop governance **bật mặc định**; muốn tắt phải **opt-out tường minh có audit** (đảo lại lỗi ARCH-03 của Plan-16). Profile `dev` có thể nới nhưng vẫn ghi audit.
+- **Tăng tự chủ = cần duyệt cấp cao:** nới budget / hạ mức gate / tăng delegation-level (L→L+1) là **security-sensitive setting** ⇒ phải qua approval JWT thật (SEC-07) + SoD (proposer ≠ approver), versioned, rollback. Nối Plan-13/14.
+- **Mọi số có provenance:** output primitive bọc envelope `{source, artifact_path, commit, run_at, verified}` — cùng data-contract §8.6 Plan-13 (để Command Center "wow thực chất").
+- **Con người luôn có nút dừng:** loop-breaker ở **mức vòng lặp** (kill-switch granular hơn Plan-07 C7).
+- **Idempotent & tail-safe:** trace append-only, hash-linked; replay không sửa nguồn.
+
+---
+
+## 3. Định nghĩa "Vòng lặp CASAN chuẩn" (Loop Contract)
+
+Một **run** là chuỗi **iteration**. Mỗi iteration là một bản ghi bất biến:
+
+```
+Iteration = {
+  run_id, step,
+  intent,                     # ý định của bước (mục tiêu con)
+  action, tool, inputs_ref,   # hành động + tool + tham chiếu input (không nhúng secret)
+  gate_verdict,               # H3/H4: PASS | FAIL | DENY  (+ evidence_ref)
+  progress,                   # tín hiệu tiến độ (đơn điệu tăng khi tiến gần goal)
+  budget_snapshot,            # {steps, tokens, elapsed_s, cost_usd} tích luỹ
+  decision                    # CONTINUE | HALT | ESCALATE | DONE
+}
+```
+
+**Điều kiện dừng (bất kỳ cái nào đúng ⇒ kết thúc):**
+- `DONE` — verify đạt **success-criteria** của goal (không phải "model tự nói xong").
+- `HALT(budget)` — vượt trần Governor (Track 1).
+- `HALT(no-progress)` / `HALT(oscillation)` — Convergence detector (Track 2).
+- `ESCALATE(human)` — gate DENY nghiêm trọng, hoặc stall ở mức rủi ro cao ⇒ vào approvals inbox (Plan-13 §3.4).
+- `HALT(human)` — loop-breaker do người bấm.
+
+```mermaid
+flowchart TD
+    S["observe / plan"] --> A["act (tool call)"]
+    A --> G{"H3/H4 verify gate<br/>(Track 3)"}
+    G -- FAIL --> C["structured correction<br/>(bounded retries)"]
+    C --> G
+    G -- PASS --> B{"Budget Governor<br/>(Track 1)"}
+    B -- exceeded --> HB["HALT(budget)"]
+    B -- ok --> CV{"Convergence<br/>(Track 2)"}
+    CV -- STALLED/OSC --> ESC["ESCALATE / HALT"]
+    CV -- converging --> D{"success-criteria?"}
+    D -- yes --> DONE["DONE ✅"]
+    D -- no --> S
+    G -- DENY --> ESC
+    A -.trace.-> T[("Loop Trace<br/>append-only, hash-linked<br/>(Track 4)")]
+    G -.trace.-> T
+    B -.trace.-> T
+    CV -.trace.-> T
+```
+
+Vị trí file (sau Plan-01 restructure → `packages/casan-harness/`; hiện tại
+`.specify/scripts/bash/`). Config ở `.specify/config/`. Không nằm trong `apps/okr`.
+
+---
+
+## 4. Tasks theo track
+
+### Track 1 — Loop Budget Governor
+| Task | Việc | File | Verify (WSL) |
+|---|---|---|---|
+| 17.1 | Schema `loop-policy.yaml`: `defaults` + override theo `delegation_level` (L0–L5) + theo `project`. Trường: `max_steps`, `max_tokens`, `max_wall_clock_sec`, `max_cost_usd`, `max_corrections_per_step`, `on_exceed: halt\|escalate`. Bao gồm `profile: prod\|dev`. | mới `config/loop-policy.yaml` + `loop-policy.schema.json` | schema validate; thiếu policy → dùng default chặt nhất |
+| 17.2 | `loop-governor.py`: `check --run-id --step --tokens --elapsed --cost` → exit 0 = CONTINUE, exit 3 = HALT(budget) kèm lý do JSON (envelope provenance). **Deny-by-default**; đọc policy lỗi ⇒ exit 3 (fail-closed). | mới `loop-governor.py` | vượt trần → exit 3 + audit; policy hỏng → exit 3 |
+| 17.3 | Nới budget = **security-sensitive** → phải qua `control-plane-settings.py` (approval JWT thật + SoD + versioned + rollback). | nối Plan-13/14 | nới không approval → DENY |
+| 17.4 | Audit event khi HALT(budget) (hash-chain, Plan-07 H5). | nối audit | bản ghi truy được |
+
+### Track 2 — No-progress / Oscillation Detector
+| Task | Việc | File | Verify (WSL) |
+|---|---|---|---|
+| 17.5 | `loop-convergence.py observe --run-id --step --action-hash --progress` (append vào state run). `verdict --run-id` → `CONVERGING\|STALLED\|OSCILLATING`. | mới `loop-convergence.py` | chuỗi tiến bộ → CONVERGING |
+| 17.6 | Luật phát hiện: (a) **oscillation** = cùng `action-hash` lặp ≥ N (config); (b) **no-progress** = `progress` không cải thiện trong cửa sổ W bước; (c) **thrash** = xen kẽ 2 state. Ngưỡng N/W trong `loop-policy.yaml`. | cùng file | lặp action → OSCILLATING; phẳng W bước → STALLED |
+| 17.7 | STALLED/OSCILLATING → `on_stall: escalate\|halt` (mặc định escalate vào approvals inbox Plan-13). | nối Plan-13 §3.4 | stall → tạo pending approval |
+| 17.8 | Envelope provenance + audit khi phán quyết STALLED/OSC. | nối audit | verdict truy được nguồn |
+
+### Track 3 — Per-iteration Verify Contract
+| Task | Việc | File | Verify (WSL) |
+|---|---|---|---|
+| 17.9 | `loop-gate.py verify --run-id --step --artifact` → `PASS\|FAIL\|DENY` + `correction_hint`. Bọc H3 (faithfulness/eval) + H4 (security-check action-gate) thành **một hợp đồng theo vòng**. | mới `loop-gate.py` (điều phối H3/H4) | fixture pass→PASS; injection→DENY |
+| 17.10 | **Correction có cấu trúc**: FAIL → retry tối đa `max_corrections_per_step` (Track 1); vượt → ESCALATE. **Không** retry mù. | cùng file | quá số correction → ESCALATE |
+| 17.11 | **Fail-closed**: gate lỗi/timeout/không đọc được artifact ⇒ FAIL (không PASS ngầm). Kế thừa SEC-04/SEC-09 Plan-16. | cùng file | gate throw → FAIL |
+| 17.12 | Cấm "self-declared done": `DONE` chỉ hợp lệ khi verify đạt **success-criteria** khai báo trước (không dựa lời model). | contract check | model nói xong nhưng verify fail → không DONE |
+
+### Track 4 — Loop Trace / Replay
+| Task | Việc | File | Verify (WSL) |
+|---|---|---|---|
+| 17.13 | `loop-trace.py record` — append-only bản ghi Iteration (§3) vào audit chain **hash-linked** (nối H5). Không nhúng secret (chỉ `inputs_ref`). | mới `loop-trace.py` | ghi N bước → chain liên tục |
+| 17.14 | `loop-trace.py show --run-id` → "loop view" (từng vòng, verdict, budget, progress) — JSON + bảng người đọc. | cùng file | render đúng thứ tự bước |
+| 17.15 | `loop-trace.py replay --run-id` — **tua lại xác định**: chạy lại verify trên artifact đã ghi, so verdict cũ/mới ⇒ phát hiện non-determinism/tamper. | cùng file | sửa 1 artifact → replay lệch → cảnh báo |
+| 17.16 | `loop-trace.py verify-chain` — tamper-evidence (nối SEC-01/02 Plan-16, KMS-anchored khi TIER-2). | cùng file | sửa 1 bản ghi → chain BREAK |
+
+### Track 5 — Meta-loop (self-improving loop policy)
+| Task | Việc | File | Verify (WSL) |
+|---|---|---|---|
+| 17.17 | Mở rộng `self-improve.py propose`: dựa AgentOps (H6) + loop-trace, đề xuất **sửa loop-policy** (nới/siết budget, thêm gate, chỉnh cửa sổ convergence) ở dạng **dry-run proposal**. | nối Plan-04 | propose không đổi policy (dry-run) |
+| 17.18 | `apply` chỉ qua `control-plane-settings.py` (approval JWT thật + **SoD proposer≠approver** + versioned + rollback). | nối Plan-13/14/16 | apply không approval → DENY; rollback được |
+| 17.19 | Meta-loop cũng bị Governor giới hạn (không tự nới vô hạn budget của chính nó). | nối Track 1 | đề xuất nới quá trần org → chặn |
+
+### Track 6 — Orchestrator integration & Control Plane
+| Task | Việc | File | Verify |
+|---|---|---|---|
+| 17.20 | Wrapper `loop-run.sh`: mỗi turn gọi `loop-gate` → `loop-governor` → `loop-convergence` → `loop-trace.record`. Profile `prod` **bật mặc định**; opt-out phải tường minh + audit. | mới `loop-run.sh` | turn vi phạm bất kỳ gate → dừng đúng nhánh |
+| 17.21 | Nối `model-router.sh`: loop context compaction giữa vòng dùng `context-compress.py` (Plan-08) + must-keep. | nối Plan-08 | context giữa vòng bị nén, giữ must-keep |
+| 17.22 | Widget **Loop panel** trên Command Center (§8.6 Plan-13): budget gauge, convergence status, per-iteration ticker, **loop-breaker** (halt granular), click bước → Evidence drawer (loop-trace show). Data đọc-only từ artifact thật. | nối Plan-13 §8.6 | số khớp fixture; loop-breaker → HALT(human) |
+
+---
+
+## 5. Red-team / test (kế thừa phong cách adversarial-harness)
+| Test | Kỳ vọng |
+|---|---|
+| Runaway loop (không điều kiện dừng) | HALT(budget) trước trần; audit ghi |
+| Oscillation (A→B→A→B…) | Track 2 phát hiện OSCILLATING → escalate |
+| No-progress (chạy nhưng metric phẳng) | STALLED trong ≤ W bước |
+| Blind-retry abuse (spam correction) | dừng ở `max_corrections_per_step` → ESCALATE |
+| Self-declared done (model nói xong, verify fail) | KHÔNG DONE |
+| Policy tampering (sửa loop-policy né budget) | apply cần approval; `verify-chain` phát hiện sửa lén |
+| Fail-open probe (làm gate throw để "được chạy tiếp") | FAIL/HALT (fail-closed) |
+| Meta-loop tự nới budget vô hạn | chặn bởi trần org + SoD |
+| Replay tamper (sửa artifact đã ghi) | replay lệch verdict → cảnh báo; chain BREAK |
+
+**File test:** `.specify/tests/phase-loop-governor-tests.sh`, `phase-loop-convergence-tests.sh`,
+`phase-loop-gate-tests.sh`, `phase-loop-trace-tests.sh`, `phase-loop-metaloop-tests.sh`.
+Chạy trong **WSL Ubuntu** (deterministic, không cần model/docker/mạng). Nối
+`ci-harness-gate.sh`. Cập nhật tổng test ở `CASAN_HARDENING_STATUS.md`.
+
+---
+
+## 6. Tiêu chí hoàn thành (Definition of Done)
+- [ ] 5 primitive có script + config schema + test xanh trong WSL, nối CI.
+- [ ] Mọi primitive **fail-closed** (chứng minh bằng test làm gate lỗi → HALT/FAIL).
+- [ ] Loop governance **bật mặc định** ở profile `prod`; opt-out có audit.
+- [ ] Nới budget / hạ gate / tăng delegation-level đều cần **approval JWT thật + SoD** (không bypass bằng chuỗi non-empty — bài học M-08/SEC-07).
+- [ ] `loop-trace verify-chain` phát hiện tamper; `replay` phát hiện non-determinism.
+- [ ] Meta-loop `propose ≠ apply`; apply có versioned + rollback.
+- [ ] Widget Loop trên Command Center đọc **artifact thật** + click-to-evidence (không vanity).
+- [ ] Không đụng OKR app; core harness giữ nguyên số test hiện có + thêm suite loop.
+
+---
+
+## 7. Ghi chú trung thực
+- Đây là **[mới] — 📋 chưa implement**. Plan mô tả thiết kế; chưa có script nào được viết trong đợt này.
+- **Không phải làm lại từ đầu:** nền tảng (H3/H4/H5/H6/H7 + `self-improve.py` + `context-compress.py` + audit chain) đã có và test xanh. Plan-17 = **đặt tên "loop engineering" + bổ sung 5 primitive** bọc lên nền đó.
+- **Phụ thuộc cứng vào Plan-16:** các primitive chỉ "thật" khi approval JWT thật (SEC-07), fail-closed (SEC-04/09), tamper-evidence (SEC-01/02), secure-by-default (SEC-17/ARCH-03) đã vá. Nếu Plan-16 chưa xong, Track 1/3/5 vẫn viết được nhưng **enforcement còn hở** — phải ghi rõ khi báo cáo, không over-claim.
+- **Rẻ + verify offline trước:** khuyến nghị bắt đầu bằng **17.1–17.2 (Governor)** và **17.5–17.6 (Convergence)** — thuần Python/bash, deterministic, verify WSL ngay, không cần model/infra.
+- **Giá trị định vị:** biến CASAN thành **"Agentic Loop Governance"** — hợp trend 2026 và hợp câu chuyện "wow thực chất" (budget/convergence/loop-trace là số **đo được, verify được, click-to-evidence được**).
+
+---
+_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (H5 audit, H6 AgentOps, C4 approval, C7 kill-switch) · `CASAN_PLAN_10_TRACEABILITY_EVAL.md` (H3 eval — gate mỗi vòng) · `CASAN_PLAN_13_CONTROL_PLANE.md` (§3.4 HITL inbox, §8.6 Command Center — widget Loop + governed loop-policy) · `CASAN_PLAN_14_RBAC.md` (nới budget cần org-admin + SoD) · `CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md` (fail-closed, approval JWT thật, tamper-evidence) · `CASAN_PLAN_04_SELFIMPROVE.md` (meta-loop) · `CASAN_PLAN_08_CONTEXT_COMPRESSION.md` (compaction giữa vòng)._