CASAN/docs/plans/CASAN_PLAN_17_LOOP_ENGINEERING.md

# KẾ HOẠCH 17 — Loop Engineering / Agentic Loop Governance

> Status 2026-07-07: **🟢 T1–T6 implemented+tested (offline), 97/0 in WSL, wired into
> CI — all 5 loop primitives + orchestrator.** Governor (T1), Convergence (T2),
> Verify Contract (T3), Trace/Replay (T4 offline slice), Meta-loop (T5),
> Orchestrator `loop-run.sh` (T6, 17.20–17.21) are done as deny-by-default,
> fail-closed harness primitives (`loop-governor.py`, `loop-convergence.py`,
> `loop-gate.py`, `loop-trace.py`, `loop-metaloop.py`, `loop-run.sh` +
> `packages/casan-harness/config/loop-policy.yaml`/`loop-policy.schema.json` + `loop_common.py`).
> Suites: governor 15/0 · convergence 15/0 · gate 20/0 · trace 16/0 · metaloop 15/0 ·
> loop-run 16/0. Meta-loop changes route through the governed CP store
> (versioned + audit + rollback + SoD) and **actually change the governor's ceiling**;
> a loosen above `org_ceiling` is refused (17.19). **Remaining (infra-gated): T4
> chain KMS-anchor (A7 Vault), T6 Command Center widget 17.22 (C5), live H3-judge.**
>
> 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
`packages/casan-harness/scripts/bash/`). Config ở `packages/casan-harness/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:** `packages/casan-harness/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
- **T1–T6 đã implement+tested (offline, 97/0 WSL, nối CI)** — đủ 5 loop primitive +
  orchestrator. T4 mới là **offline slice** (hash-chain local; KMS-anchor head 17.16
  còn chờ A7). T5 meta-loop apply đi qua **governed CP store thật** (versioned +
  audit + rollback + SoD) và **đổi được ceiling của governor**; loosen vượt org_ceiling
  bị chặn (17.19). Còn lại (infra-gated): T4 KMS-anchor, T6 widget Command Center
  (17.22, dep C5), live H3-judge. Không over-claim: primitive "thật" nhờ Plan-16 đã
  vá (approval JWT SEC-07 ✅, fail-closed SEC-04/09 ✅, tamper-evidence SEC-01/02 ✅).
- **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)._