# 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ó")

```mermaid
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
- [x] `CASAN_GEN_MODE=template` cho hành vi cũ y hệt (an toàn quay lui).
- [x] `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.
- [x] Code/implement draft (đợt D) chỉ được accept khi STEP12 run-tests PASS (`implementation.accepted.json` chỉ ghi sau PASS).
- [x] Prompt/model/token vào H5 sourcegen audit + H6 sourcegen telemetry.
- [x] 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.