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.

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