CASAN/docs/plans/CASAN_PLAN_02_LLM_SOURCEGEN.md

KẾ HOẠCH 02 — Nối LLM thật vào sinh source (thay template deterministic)

Status 2026-07-06: Đợt A MVP implemented + tested cho 01-srs và 02-bd. Mặc định vẫn dùng template deterministic; khi bật CASAN_GEN_MODE=model, hai step này gọi model-router.sh --role generate, H4 artifact-scan output nháp, validate tiêu chí tối thiểu, rồi mới ghi artifact. Lỗi model / output thiếu / H4 block đều fallback template và ghi source=template-fallback trong report.

Hiện casan-step.mjs vẫn sinh các step sau bằng template hard-code trong switch(step) [có, đọc code]; model đã dùng ở H3 judge + H4 semantic và nay ở source-gen đợt A. Kế hoạch: mở rộng dần để LLM thật sự sinh artifact, nhưng mọi output vẫn chui qua H1→H7.

Phụ thuộc: nên làm sau 03 (cloud patch) để có lựa chọn model mạnh cho bước khó; 01 giúp gọn nhưng không bắt buộc.

Bối cảnh code hiện tại [có]

• casan-step.mjs: mỗi case '<step>' gọi write(path, "<nội dung khuôn>") rồi report(...).
• judgeArtifact() gọi model-router.sh --role judge; ollamaAvailable() kiểm 127.0.0.1:11434; vắng model → SKIP (không chặn).
• model-router.sh → model-call.py là điểm gọi model chuẩn (đã có H4 trước, H6/H5 sau).

Nguyên tắc

• Sinh xong vẫn qua harness: không được để LLM ghi thẳng bỏ qua H4/H5/H7.
• Có golden để so: mỗi step cần tiêu chí chấp nhận + golden (drift/H3) để bắt output kém.
• Chuyển dần từng step, không thay cả 13 bước một lúc.
• Fallback về template: model vắng/kém → dùng template cũ (không vỡ pipeline).
• Deterministic-friendly: cố định seed/nhiệt độ thấp cho bước cần ổn định; ghi lại prompt vào audit (H5).

---

Chiến lược chuyển đổi (từng step, có cổng)

Thứ tự chuyển ưu tiên step rõ ràng, ít rủi ro trước:

Đợt	Step chuyển	Vì sao trước/sau
A	01-srs, 02-bd	văn bản có cấu trúc, dễ chấm, rủi ro thấp
B	03-spec, 06-plan	có review loop (STEP5/7) đỡ lỗi
C	08-dd, 09-tasks	phụ thuộc spec/plan tốt
D	10-implement (code)	rủi ro cao nhất → làm cuối, cần test thật (STEP12) làm lưới

---

Tasks

Task	Việc	File	Verify	Done khi
2.1	Trừu tượng hoá: thêm hàm generate(step, ctx) chọn model hoặc template theo cờ CASAN_GEN_MODE	casan-step.mjs	mode=template → hành vi cũ y hệt	✅ đợt A
2.2	Viết prompt-template cho mỗi step (đưa requirement + architecture + tiêu chí chấp nhận vào prompt)	mới prompts/<step>.md	prompt render đủ ngữ cảnh	có prompt từng step
2.3	Gọi model qua model-router.sh --role generate (KHÔNG gọi model-call trực tiếp)	casan-step.mjs	output đi qua H4 trước khi ghi	✅ đợt A (01-srs, 02-bd)
2.4	Chuẩn hoá output model → đúng file artifact + STEP-RESULT block	parser	verdict/artifacts hợp lệ	schema đúng
2.5	Nạp golden + tiêu chí cho H3 judge từng step	apps/okr/domain/golden-runs/	judge chấm được đạt/không	H3 hoạt động
2.6	Fallback: model SKIP/kém → dùng template (đợt A/B), hoặc REJECT → vòng review	casan-step.mjs	ép model lỗi → không vỡ	✅ đợt A
2.7	Chuyển đợt A (srs, bd) sang mode=model	pipeline	chạy full, 2 artifact do model sinh, qua harness	🟡 MVP done; full live pipeline smoke còn
2.8	Chuyển đợt B (spec, plan) + kiểm vòng REJECT hoạt động	pipeline	ép spec kém → STEP5 REJECT → retry	loop chạy
2.9	Chuyển đợt C (dd, tasks)	pipeline	artifact hợp lệ, drift trong ngưỡng	đợt C xong
2.10	Chuyển đợt D (implement code) — bắt buộc STEP12 chạy test thật làm cổng	pipeline	test dự án PASS mới nhận code	đợt D xong
2.11	Ghi prompt + model + token vào audit (H5) & telemetry (H6)	logging	audit có prompt, provider-usage có token	truy vết được

---

Cơ chế chất lượng (không chỉ "sinh cho có")

flowchart LR
    G["generate(step)"] --> H4["H4 quét output"]
    H4 --> J["H3 judge vs tiêu chí"]
    J -- "REJECT" --> RETRY["vòng review (STEP5/7/11)<br/>hoặc leo thang model"]
    J -- "PASS" --> DR["drift vs golden"]
    DR -- "lệch nhiều" --> RETRY
    DR -- "ổn" --> WRITE["ghi + audit (H5) + rollback-ready (H7)"]
    RETRY --> G

    style RETRY fill:#fff0c0,stroke:#b9770e
    style WRITE fill:#d0ffd0,stroke:#1e8449

• Leo thang model (escalation-on-demand): step bị H3 REJECT ≥ N lần → tự đề xuất dùng model mạnh hơn (nối 03). Đây là chỗ cloud/frontier đáng dùng.
• Code (đợt D): cổng cứng là STEP12 run-tests thật — code sinh ra không PASS test thì không được nhận.

Rủi ro

Rủi ro	Giảm thiểu
Model sinh sai/ảo	H3 judge + drift + test thật; fallback template
Không ổn định giữa các lần	nhiệt độ thấp/seed; golden so sánh
Chi phí tăng	H6 cost-spike + circuit-breaker; local trước, cloud khi cần
Bỏ qua harness	bắt buộc gọi qua model-router + wrapper, cấm ghi thẳng
Regression pipeline	CASAN_GEN_MODE=template luôn giữ đường cũ

Tiêu chí HOÀN THÀNH

• CASAN_GEN_MODE=template cho hành vi cũ y hệt (an toàn quay lui) ở đợt A.
• CASAN_GEN_MODE=model: đợt A–D artifact do LLM sinh, đều qua H1→H7. Đợt A đã có MVP cho 01-srs/02-bd.
• Code (đợt D) chỉ nhận khi STEP12 test PASS.
• Prompt/model/token vào audit (H5) + telemetry (H6).
• Có escalation khi H3 REJECT lặp; local vẫn là mặc định.

Sau kế hoạch này, câu "pipeline sinh source bằng AI" mới đúng nghĩa. Trước đó phải nói rõ đang dùng template.