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-09: Plan-02 A–D implemented + tested (offline/local). Mặc định vẫn dùng template deterministic; khi bật CASAN_GEN_MODE=model, các step 01-srs, 02-bd, 03-spec, 05-plan, 07-dd, 08-testkit, 09-tasks, 10-implement gọi model-router.sh --role generate, H4 artifact-scan output nháp, validate token bắt buộc, ghi H5 sourcegen audit

• H6 sourcegen telemetry, rồi mới ghi artifact. Lỗi model / output thiếu / H4 block đều fallback template và ghi source=template-fallback trong report.

run-casan-pipeline.mjs đã có STEP10 implement draft + STEP12 run-tests gate thật; STEP5/STEP7/STEP11 có retry/escalation loop. Cloud OpenAI/Anthropic live smoke vẫn thuộc Plan-03 vì cần API key thật; Plan-02 local path dùng Ollama qua router, timeout sourcegen mặc định 240s cho prompt dài.

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, 05-plan	có review loop (STEP5/7) đỡ lỗi
C	07-dd, 08-testkit, 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	✅ A–D
2.2	Viết prompt-template cho mỗi step (đưa requirement + architecture + tiêu chí chấp nhận vào prompt)	packages/casan-harness/prompts/sourcegen/<step>.md	prompt render đủ ngữ cảnh	✅ 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	✅ A–D
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, run-casan-pipeline.mjs	ép model lỗi → không vỡ	✅ A–D
2.7	Chuyển đợt A (srs, bd) sang mode=model	pipeline/test	artifact do model sinh, qua harness	✅ done+test
2.8	Chuyển đợt B (spec, plan) + kiểm vòng REJECT hoạt động	pipeline/test	ép spec/plan kém → STEP5/7 REJECT → retry	✅ loop chạy
2.9	Chuyển đợt C (dd, testkit, tasks)	pipeline/test	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	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).
• CASAN_GEN_MODE=model: đợt A–D artifact đi qua model-router --role generate, H4 scan, required-token validation, fallback template khi lỗi, và harness H1→H7 ở pipeline.
• Code/implement draft (đợt D) chỉ được accept khi STEP12 run-tests PASS (implementation.accepted.json chỉ ghi sau PASS).
• Prompt/model/token vào H5 sourcegen audit + H6 sourcegen telemetry.
• Có escalation khi H3 REJECT lặp; local vẫn là mặc định, cloud/frontier chỉ dùng khi cấu hình CASAN_REVIEW_ESCALATE_MODEL + key.

Verify 2026-07-09

• phase2-sourcegen-tests.sh: 10/0 — A–D model-mode mocked router, fallback H4, audit/telemetry, STEP12 pass/fail acceptance.
• run-casan-pipeline.mjs full template smoke in /tmp: STEP1/2/3/5/6/7/8/8b/9/10/11 APPROVED, STEP12 PASS; loops STEP5→STEP3, STEP7→STEP6, STEP11→STEP10 exercised.
• App test gate: backend npm test -w backend 46 pass / 0 fail / 3 skip; frontend npm test -w frontend 16/0.
• Local Ollama generate path verified via model-router.sh --role generate (ollama:ornith:9b, real token telemetry); sourcegen prompts use 240s default timeout for long local generations.

Sau kế hoạch này, câu "pipeline sinh source bằng AI" đúng với mode model/local. Nếu cần OpenAI/Anthropic live-provider smoke và billing ground truth, làm tiếp theo Plan-03 vì cần API key/dịch vụ ngoài.