Phương pháp đánh giá và kiểm chứng

Lý thuyết, công thức, cách vận hành và kết quả evaluation của Agent 2, Agent 4 và outcome sau lộ trình.

Tài liệu này mô tả các phương pháp evaluation đang được dùng cho Agent 2, Agent 4 và toàn pipeline sau lộ trình: cơ sở lý thuyết, ý nghĩa, cách vận hành, công thức, mẫu số và cách đọc kết quả. Đây là tài liệu giải thích; business rule vẫn thuộc docs/EXAM_TRIAGE_AI_Spec.md.

Agent 3 không thuộc phạm vi Golden Dataset này: điểm và thứ hạng của Agent 3 là zero-LLM nên được kiểm bằng unit test, không cần nhãn người. Phần narrative advisory của Agent 3 thì có harness riêng (eval/agent3/, python -m eval.agent3.report) đo độ ổn định lời giải thích, không đo độ chính xác xếp hạng. Agent 4 có harness kỹ thuật riêng, không dùng annotation/adjudication của Agent 2 vì hard constraint của Planner có thể kiểm bằng toán và exact oracle.

[!IMPORTANT] Snapshot mới nhất là v0.4-mixed-synthetic-eval-5pc. Trong một lần kiểm tra harness, nhãn mock được dùng như ground truth để mọi công thức chạy end-to-end. Tuy nhiên dataset vẫn mang status="synthetic_mock"; vì vậy các số đo chưa phải Human Benchmark thật, không mở asset gate và không đóng OD-01..OD-04.

Artifact hiện hành:

báo cáo đọc nhanh: eval/results/golden_mock_v0.4-mixed-synthetic-eval-5pc.md;
kết quả máy đọc: eval/results/golden_mock_v0.4-mixed-synthetic-eval-5pc.json;
dataset: data/evaluation/golden/v0.4-mixed-synthetic-eval-5pc/.

Không ghi kết quả mới vào eval/results/report.md: file đó giữ snapshot lịch sử trước v0.4 kèm feedback có tên người dùng. Kết quả explain-back, blind_spot_score, Cascading Downgrade, Cross-Subject RAG và TPS của MVP cũ nằm ở eval/results/legacy_mvp_report.md và không là bằng chứng cho kiến trúc hiện tại. Mỗi snapshot mới phải có file kết quả riêng để không làm mất khả năng đối chiếu.

Bảng tổng hợp một trang cho toàn kiến trúc hybrid — gồm cả ba kết luận âm quan trọng nhất — là eval/results/hybrid_summary_2026-08-31.md.

1. Bức tranh tổng thể

1.1. Các lớp evaluation

Question Bank / Knowledge Map quality
        ↓
Human Benchmark / reference labels
        ↓
Agent 2 evidence sufficiency và stopping safety
        ↓
Diagnostic efficiency và mastery calibration synthetic
        ↓
Reproducibility của pipeline Agent 2

Agent 2 → Agent 3 → Agent 4 → Study Workspace
        ↓
Post-Plan Learning Outcome (track riêng)

Evaluation Agent 2 trả lời câu hỏi evidence có đủ để xác minh trạng thái kiến thức và stopping rule có an toàn/hiệu quả hay không. Post-Plan evaluation là track riêng, đo kết quả sau khi người học đã đi qua lộ trình; nó không được dùng để quy kết chất lượng riêng cho Agent 2.

1.2. Snapshot v0.4

Thuộc tính	Giá trị
Course	5
Knowledge Cluster	25
Agent 2 case	125
Case/Cluster	5
Raw 1–5	25 case/mức
Diagnostic turn/case	6
MCQ	250 turn
Short answer	250 turn
High-information/long answer	250 turn
Agent 2 case đủ điều kiện raw 4–5	50
Independent outcome hợp lệ	125

Mỗi case Agent 2 có đúng hai câu của mỗi loại. Raw 1–3 vẫn được giữ trong dataset để kiểm BR-01/BR-02, nhưng không được đưa vào mẫu số FCR/FNCR vì runtime phải route chúng quanh Agent 2.

2. Human Benchmark — chuẩn đối chiếu con người

2.1. Lý thuyết

Một hệ thống không thể tự dùng output của chính nó làm đáp án đúng. Human Benchmark cung cấp nhãn tham chiếu độc lập để đo lỗi của hệ thống.

Quy trình tối thiểu:

Case + rubric + evidence/context
       ├── Reviewer 1 chấm độc lập
       └── Reviewer 2 chấm độc lập
                    ↓
              So sánh bất đồng
                    ↓
          Adjudicator phân xử
                    ↓
             Final reference label

Hai reviewer không được xem system output hoặc nhãn của nhau trước khi khóa vòng một. Adjudication không phải lấy đa số máy móc; adjudicator phải xem lại evidence, rubric và context rồi ghi lý do cho nhãn cuối.

2.2. Ý nghĩa với Agent 2

Với Agent 2, giảng viên bộ môn đánh giá:

câu trả lời đạt rubric đến đâu;
competency nào có evidence;
evidence đã đủ để verified chưa;
status hợp lý là verified, partial hay unverified.

2.3. Percent agreement giữa reviewer

Với hai reviewer và $N$ case:

Agreement_{reviewer}=\frac{\sum_{i=1}^{N}\mathbb{1}(r_{i1}=r_{i2})}{N}

Trong đó $\mathbb{1}(\cdot)$ bằng 1 khi hai nhãn giống nhau và 0 khi khác nhau. Percent agreement dễ hiểu nhưng không loại phần đồng ý có thể xảy ra ngẫu nhiên.

2.4. Cohen's Kappa

Với nhãn phân loại không có thứ tự:

\kappa=\frac{p_o-p_e}{1-p_e}

Trong đó:

$p_o$ là tỷ lệ đồng ý quan sát;
$p_e$ là tỷ lệ đồng ý kỳ vọng từ phân phối nhãn biên của hai reviewer.

Với rubric band có thứ tự, dùng Weighted Kappa:

\kappa_w=1-\frac{\sum_{i,j}w_{ij}O_{ij}} {\sum_{i,j}w_{ij}E_{ij}}

$w_{ij}$ là mức phạt khi reviewer 1 chọn mức $i$ và reviewer 2 chọn mức $j$ . Không được xếp not_assessed như mức mastery thấp nhất vì đây là trạng thái routing, không phải kết luận năng lực.

2.5. Cách vận hành trong dataset

agent2/annotations/*.jsonl: hai annotation cho mỗi Agent 2 case.
agent2/adjudication/*.jsonl: một final label cho mỗi case.
FCR/FNCR chỉ đọc final adjudicated label.

2.6. Kết quả v0.4

Track	Đơn vị	Hai annotation	Đồng ý	Bất đồng	Agreement
Agent 2	125 case	250	111	14	88.80%

Observed agreement đã tính được từ annotation files. Runner hiện chưa xuất Cohen's/Weighted Kappa vào JSON; vì vậy Kappa vẫn là phép đo cần bổ sung trước khi đánh giá chất lượng Human Benchmark thật.

3. Evidence-level FCR/FNCR — an toàn xác minh của Agent 2

3.1. Lý thuyết và semantics

verified chỉ có nghĩa evidence đạt confirmation policy trong phạm vi competency đã kiểm tra. Nó không khẳng định sinh viên hiểu toàn bộ Cluster.

Mỗi case raw 4–5 được quy về hai biến Boolean:

System:    verified / not verified
Reference: evidence sufficient / evidence insufficient

Từ đó tạo confusion matrix:

	Reference đủ evidence	Reference chưa đủ evidence
System `verified`	True Verified (TV)	False Verified (FV)
System không `verified`	False Not-Verified (FNV)	True Not-Verified (TNV)

3.2. Evidence-level False Confirmation Rate

FCR_{evidence}=\frac{FV}{FV+TNV}

Mẫu số là tất cả case reference cho rằng chưa đủ evidence. FCR trả lời:

Trong số case đáng lẽ không được xác minh, hệ thống xác minh nhầm bao nhiêu?

Đây là metric an toàn chính vì false confirmation có thể làm sinh viên bỏ qua phần kiến thức còn yếu.

3.3. Evidence-level False Non-confirmation Rate

FNCR_{evidence}=\frac{FNV}{FNV+TV}

FNCR trả lời:

Trong số case thực sự đã đủ evidence, hệ thống không xác minh bao nhiêu?

FNCR cao làm diagnostic dài hoặc bảo thủ quá mức, nhưng thường ít nguy hiểm hơn FCR cao.

3.4. Confirmation Accuracy

Accuracy_{evidence}=\frac{TV+TNV}{TV+FV+TNV+FNV}

Không dùng Accuracy một mình: nếu reference-negative chiếm đa số, hệ thống luôn trả not-verified vẫn có thể đạt accuracy cao nhưng không hữu ích.

3.5. Cách vận hành

Chỉ lấy case có observed_self_assessment_raw >= 4.
Đọc final adjudicated evidence_sufficient.
Chạy fixed baseline và CAT-lite trên cùng response prefix.
Chuyển status của mỗi policy thành verified/không verified.
Tính confusion matrix và các tỷ lệ theo mẫu số ở trên.

Thiết kế paired/shared-prefix giúp chênh lệch giữa hai policy không bị nhiễu bởi hai bộ câu trả lời khác nhau.

3.6. Kết quả v0.4

Policy	N	TV	FV	TNV	FNV	FCR	FNCR	Accuracy
Fixed baseline (replay log)	50	16	6	18	10	25.00%	38.46%	68.00%
CAT-lite (replay log)	50	16	7	17	10	29.17%	38.46%	66.00%
Runtime policy (đường code thật)	50	15	9	15	11	37.50%	42.31%	60.00%

CAT-lite tạo thêm một false confirmation, làm FCR tăng 4.17 điểm phần trăm so với fixed baseline. Vì vậy trên snapshot này CAT-lite tiết kiệm tài nguyên nhưng chưa thắng fixed baseline về an toàn.

[!WARNING] Hai hàng đầu đo sai chính sách. scripts/simulate_agent2_runs.py dựng Evidence trực tiếp từ response_log, nên nó tính cả câu mà runtime không hỏi; độ chồng lấn giữa bộ câu runtime thật sự hỏi và response_log chỉ 13.7%. Hàng runtime (eval.agent2.runtime_policy, artifact eval/results/agent2_fcr_runtime_v0.4-mixed-synthetic-eval-5pc.md) cho FCR 37.50% — số cũ lạc quan hơn thực tế. Mọi metric §31 từ nay phải chạy qua eval.agent2.runtime_policy, không qua replay. Cả ba hàng vẫn là mock (data_origin: "synthetic_mock") nên không đóng OD nào.

Hàng runtime được chạy 2026-08-25, khi SERVABLE_QUESTION_TYPES còn là {multiple_choice}. Từ 2026-08-29 tập này gồm cả high_information (ADR 15), nên số trên chưa phản ánh tập câu hiện tại; golden label cho high_information vẫn là seed_placeholder nên FCR cho loại câu đó chưa có số — không phải bằng 0.

4. Post-Plan Learning Outcome — kết quả sau lộ trình

Product flow không chèn independent post-test sau khi Agent 2 trả verified. Sinh viên đi thẳng qua Agent 3, Agent 4 và các hoạt động có sẵn trong Study Workspace. Vì vậy VOFR không phải metric vận hành của flow hiện tại. Kết quả VOFR trong artifact synthetic v0.4 chỉ là lịch sử kiểm tra harness, không phải outcome sinh viên thật.

Một đơn vị đánh giá là bộ ba:

(student_id, plan_id, learning_unit_id)

4.1. Post-Plan Outcome Failure Rate

PostPlanFailureRate= \frac{FailedFirstAttempts} {ValidFirstAttempts}

Metric này đo toàn pipeline sau lộ trình, không đo riêng Agent 2.

4.2. Outcome Coverage Rate

OutcomeCoverageRate= \frac{UnitsWithFirstAttempt} {AssignedUnits}

Failure rate phải luôn được đọc cùng coverage. Chỉ báo failure trên nhóm hoàn thành bài sẽ loại người bỏ dở khỏi mẫu số và làm kết quả trông tốt giả tạo.

4.3. First-attempt score và completion

mean_first_attempt_score là trung bình score lần đầu trên các unit có outcome hợp lệ. First attempt là attempt có attempt_number nhỏ nhất, không phải điểm cao nhất sau nhiều lần làm.

PlanCompletionRate= \frac{CompletedPlans} {AssignedPlans}

4.4. Time to first outcome

Với mỗi unit có first attempt:

TimeToFirstOutcome=ObservedAt_{first}-AssignedAt

Báo cáo tối thiểu mean, p50 và p95 theo giờ. Attempt xảy ra trước assigned_at là dữ liệu không hợp lệ, không được sửa âm thành 0.

4.5. Retry

RetryRate= \frac{RetriedUnits} {UnitsWithFirstAttempt}

RetryImprovement=Score_{attempt\ 2}-Score_{attempt\ 1}

retry_improvement chỉ đọc unit có attempt 2 và phải báo kèm retry_rate để tránh selection bias.

4.6. High-priority completion

HighPriorityCompletionRate= \frac{CompletedHighPriorityUnits} {AssignedHighPriorityUnits}

High priority phải do policy có version gán trong dataset. Evaluator không dùng fixed Top-K và không tự suy từ một ngưỡng priority score hard-code.

4.7. Trạng thái đo hiện tại

Runtime chưa có backend producer/persistence cho quiz attempt và completion. Frontend chỉ giữ điểm cuối và completion trong local state, nên các metric thật phải là N/A cho tới khi có snapshot outcome hợp lệ. Evaluator offline nhận JSONL version hóa; không có mẫu số thì trả null, không điền 0.

5. Diagnostic Efficiency — hiệu quả CAT-lite so với fixed

5.1. Lý thuyết

Adaptive diagnostic có giá trị khi đạt cùng chất lượng xác minh với ít câu hỏi hoặc ít thời gian hơn. Tiết kiệm nhưng làm FCR/FNCR xấu đi không được coi là cải tiến an toàn.

Với $N$ case:

AverageQuestions_P=\frac{1}{N}\sum_{i=1}^{N}Q_{i,P}

AverageTime_P=\frac{1}{N}\sum_{i=1}^{N}T_{i,P}

Chênh lệch tuyệt đối:

QuestionsSaved=AverageQuestions_{fixed}-AverageQuestions_{CAT}

SecondsSaved=AverageTime_{fixed}-AverageTime_{CAT}

Tỷ lệ giảm:

RelativeQuestionReduction= \frac{AverageQuestions_{fixed}-AverageQuestions_{CAT}} {AverageQuestions_{fixed}}

RelativeTimeReduction= \frac{AverageTime_{fixed}-AverageTime_{CAT}} {AverageTime_{fixed}}

5.2. Thiết kế paired

Fixed baseline dùng hết Cluster Budget có tên.
CAT-lite đọc cùng thứ tự response nhưng được dừng khi confirmation policy đạt.
Hai policy dùng cùng case và response prefix.
So sánh đồng thời efficiency delta và safety delta.

5.3. Kết quả v0.4

Metric	Fixed	CAT-lite	CAT-lite thay đổi
Câu hỏi trung bình	3.160	2.940	−0.220 (−6.96%)
Thời gian trung bình	362.86 s	344.34 s	−18.52 s (−5.10%)
Evidence FCR	25.00%	29.17%	+4.17 điểm %
Evidence FNCR	38.46%	38.46%	0.00 điểm %

Kết luận đúng cho snapshot: CAT-lite hiệu quả hơn về số câu/thời gian nhưng kém hơn về FCR. Không được chỉ báo cáo phần tiết kiệm.

6. Mastery Calibration/ECE — hiệu chuẩn mastery

6.1. Lý thuyết

Calibration đo mức một dự đoán xác suất/điểm có khớp tần suất quan sát hay không. Ví dụ, các case có mastery quanh 0.8 nên có outcome trung bình quanh 0.8.

Chia các prediction thành $B$ bin. Với bin $b$ :

\overline{M}_b=\frac{1}{|b|}\sum_{i\in b}Mastery_i

\overline{O}_b=\frac{1}{|b|}\sum_{i\in b}OutcomeScore_i

Sai số bin:

CalibrationError_b=|\overline{M}_b-\overline{O}_b|

Expected Calibration Error:

ECE=\sum_{b=1}^{B}\frac{|b|}{N} |\overline{M}_b-\overline{O}_b|

ECE càng gần 0 càng tốt. ECE không cho biết hệ thống over-confident hay under-confident ở bin nào; reliability table/diagram theo bin cần được xem cùng nếu muốn chẩn đoán hướng sai lệch.

6.2. Cách vận hành

Chỉ giữ case CAT-lite có mastery_score và outcome score hợp lệ.
Ghép theo case_id.
Chia mastery vào 10 equal-width bin: [0,0.1), …, [0.9,1.0].
So mean mastery với mean continuous outcome score của mỗi bin.
Cộng sai số tuyệt đối theo trọng số số phần tử bin.

Không dùng diagnostic score đã tạo mastery làm outcome, vì khi đó phép đo trở thành tự đối chiếu.

6.3. Kết quả v0.4

Mastery–outcome pair hợp lệ = 50
Số bin cấu hình = 10
ECE = 0.18156 ≈ 18.16%

Diễn giải: trung bình có trọng số theo bin, mastery và outcome lệch khoảng 0.182. ECE chưa có ngưỡng pass được duyệt và không tự đóng OD-03.

7. Reproducibility — khả năng tái tạo

7.1. Lý thuyết

Một metric không tái tạo được thì không thể dùng để so hai policy. Reproducibility yêu cầu cùng snapshot, code, constants và protocol phải tạo cùng payload kết quả.

Artifact cần pin:

dataset/version/status;
Question Bank và Knowledge Map SHA-256;
source commit và trạng thái dirty;
evaluated timestamp/timezone;
random seed;
baseline constants;
protocol và selection-policy version;
raw predictions và final labels;
hash mọi input mà evaluator thực sự đọc.

Với canonical JSON payload $X$ :

h=SHA256(CanonicalJSON(X))

Hai lần chạy pass khi:

h_1=h_2

Điều này chứng minh evaluator tất định trên cùng input; nó không chứng minh dataset đúng hoặc policy an toàn.

7.2. Cách vận hành

evaluate(root) chạy lần một.
evaluate(root) chạy lần hai trên cùng process/input.
Hai payload được serialize với key order chuẩn.
So SHA-256.
Regression test còn sinh dataset ở hai thư mục độc lập và so hash toàn cây.

7.3. Kết quả v0.4

Run 1 hash = 75a5359461228d5372a35371fdb21e1f4dbf22f54fe083a2f4e536f2fa79e0b2
Run 2 hash = 75a5359461228d5372a35371fdb21e1f4dbf22f54fe083a2f4e536f2fa79e0b2
Status = PASS

Manifest SHA-256:

c474194184ea9f137d09a312a219e50c3137e594d08269673b841b98b9a1bb7c

8. Tổng hợp trạng thái evaluation

Phương pháp	Trạng thái v0.4	Kết quả chính
Human Benchmark structure	Chạy bằng mock labels	A2 agreement 88.80%; chưa có Kappa
Evidence FCR/FNCR	Evaluated	Runtime policy FCR 37.50%, FNCR 42.31%; replay 25.00%/29.17% đo sai chính sách
Diagnostic Efficiency	Evaluated	giảm 6.96% câu, 5.10% thời gian; FCR tăng 4.17 điểm %
Mastery ECE	Evaluated	0.1816 trên 50 cặp mastery–outcome
Reproducibility	PASS	Hai metric payload hash giống nhau
FCR cho `high_information`	Chưa đo	Golden label là `seed_placeholder`
Agent 3 advisory stability	PASS, có điều kiện	3 tỷ lệ stability = 1.000; model đo đã EOL
Agent 4 P0 harness	FAIL	30 phút oracle regret; mọi nhóm khác PASS
Agent 4 advisory clause 4	Nửa câu trả lời	Không field nào đặt được hard constraint; lợi ích chưa đo
Post-Plan Outcome Failure	N/A	Chưa có runtime outcome snapshot
Outcome Coverage	N/A	Chưa có runtime outcome snapshot
First-attempt score	N/A	Chưa có runtime outcome snapshot
Plan completion	N/A	Chưa có runtime outcome snapshot
Time to first outcome	N/A	Chưa có runtime outcome snapshot
Retry rate/improvement	N/A	Chưa có runtime outcome snapshot
High-priority completion	N/A	Chưa có runtime outcome snapshot

Artifact v0.4 vẫn chứa VOFR synthetic để audit lịch sử, nhưng metric đó không còn thuộc product evaluation hiện hành. Không sửa artifact bất biến để làm nó trông như đã luôn dùng policy mới.

9. Các phép đo chưa nằm trong snapshot v0.4

Những phương pháp sau có giá trị nhưng chưa thuộc sáu phép đo hiện hành:

evidence-confidence calibration cho OD-04;
misconception precision/recall theo stable misconception ID;
Capacity gap MAE;
expert review, plan acceptance/adherence và A/B evaluation của Agent 4;
confidence interval và significance test;
reliability diagram theo mastery bin;
Cohen's/Weighted Kappa trong runner chính thức.
backend producer cho first attempt, retry và completion;
snapshot Post-Plan có consent/retention policy và version.

Không trình bày các mục này như đã evaluated.

10. Decision gates

Decision	Evidence cần có	Trạng thái sau v0.4
OD-01 Confirmation	Human FCR/FNCR + stopping study	OPEN; mới có synthetic baseline
OD-02 Budget	Paired efficiency không làm safety xấu đi	OPEN; CAT-lite FCR đang xấu hơn fixed trên mock
OD-03 Mastery	Calibration/predictive validity trên outcome thật	OPEN; mới có synthetic ECE
OD-04 Evidence Confidence	Confidence-error calibration	Chưa evaluated
`high_information` asset gate (§5.2/§5.3)	Rubric ≥3 tiêu chí đã duyệt + guardrail validator	MỞ 2026-08-29 (ADR 15) — mở bằng asset, không bằng số FCR
`short_answer` / `feynman` asset gate	Versioned rubric + human Golden Turn/Scenario + FCR	ĐÓNG; `short_answer` khi mở sẽ đi đường tất định
Planner advisory gate (§5.6)	Clause 4: không đặt hard constraint và lợi ích đo được	ĐÓNG (ADR 11/16); mới trả lời nửa đầu
Priority advisory gate (§5.5)	Stability narrative + audit envelope	MỞ (ADR 10); cần chạy lại stability trên model hiện tại

11. Lệnh chạy và mapping implementation

.venv/bin/python scripts/validate_golden_candidate_dataset.py \
  --dataset-root data/evaluation/golden/v0.4-mixed-synthetic-eval-5pc

.venv/bin/python scripts/evaluate_golden_mock.py \
  --dataset-root data/evaluation/golden/v0.4-mixed-synthetic-eval-5pc \
  --output eval/results/golden_mock_v0.4-mixed-synthetic-eval-5pc.json \
  --evaluated-at "2026-08-23T17:00:00+07:00"

.venv/bin/python scripts/evaluate_fcr.py \
  --dataset-root data/evaluation/golden/v0.4-mixed-synthetic-eval-5pc

Thành phần	Nguồn
Dataset contract	`scripts/build_golden_candidate_dataset.py`
Synthetic generator	`scripts/generate_synthetic_evaluation_dataset.py`
Chọn 5 case/Cluster	`scripts/compact_synthetic_evaluation_dataset.py`
Validation	`scripts/validate_golden_candidate_dataset.py`
Agent 2 fixed/CAT simulation	`scripts/simulate_agent2_runs.py`
Historical synthetic FCR/FNCR/VOFR/ECE	`scripts/evaluate_golden_mock.py`
Standalone FCR/FNCR	`scripts/evaluate_fcr.py`
FCR theo đường code runtime	`eval/agent2/runtime_policy.py` + `python -m eval.agent2.write_runtime_policy --write`
Agent 3 advisory stability	`eval/agent3/stability.py` + `python -m eval.agent3.report`
Agent 4 harness	`scripts/evaluate_agent4_planner.py`
Labeling protocol	`data/evaluation/golden/labeling-guide.md`
Post-Plan metrics	`scripts/evaluate_post_plan.py` + `eval/post_plan/`

12. Evaluation độc lập cho Agent 4 — Deterministic Planner

12.1. Vì sao Agent 4 không dùng annotation/adjudication ở P0

Agent 2 cần giảng viên vì các khái niệm như “evidence đủ” hay “đạt rubric” có yếu tố chuyên môn. Với Agent 4, phần P0 gồm các mệnh đề toán học: có vượt capacity hay không, có đặt sau deadline hay không, có mất session hay không và một allocation khác có xếp được nhiều phút hơn hay không. Các mệnh đề này được kiểm bằng checker độc lập và exact oracle, không cần người gán nhãn.

Harness nằm ngoài runtime:

request hợp lệ
   ├── allocate_plan()                  → output Planner
   ├── inventory/invariant checker      → hard-constraint counters
   ├── exact oracle trên case nhỏ       → allocation regret
   └── metamorphic variants             → stability của contract

Không module nào trong src/ import harness. Oracle không đi vào API production.

12.2. Golden Planning Scenarios

Mười scenario kỹ thuật cố định nằm tại tests/data/planner_scenarios/. Manifest:

dataset_id = agent4-golden-planning-scenarios
version = v1
status = deterministic_engineered_scenarios
human_benchmark = false
corpus_sha256 = 835a6d40347dfc71c1b56f3787d70a509a59e0c4428c33702540920cd261eb6c

Hai scenario cuối khoá hành vi của PACING_MODE = balanced: 09_balanced_pacing_ample_slack (còn nhiều slack thì rải đều) và 10_imminent_course_still_crams (deadline sát thì vẫn dồn).

Đây là engineered regression corpus, không phải dữ liệu sinh viên và không phải Human Benchmark. Mỗi scenario có request, expected output và README giải thích hành vi được khóa. Harness bỏ ba field version/disclaimer khi so snapshot rồi kiểm chúng riêng, tránh việc đổi version làm che lỗi hành vi.

12.3. Invariant Evaluation — P0

Lý thuyết và ý nghĩa

Invariant là mệnh đề phải đúng với mọi output hợp lệ, không phụ thuộc lịch có “đẹp” hay không. Nếu một invariant sai, output vi phạm contract hoặc hard constraint; không cần threshold thống kê để quyết định.

Với window $j$ :

Used_j=\sum_{s\in j}Duration_s\le Capacity_j

Với ngày $d$ và toàn response:

Planned_d=\sum_{j\in d}Used_j

TotalPlanned=\sum_d Planned_d

TotalDeferred=\sum_{s\in Deferred}Duration_s

Với session $s$ của môn $c$ :

Deadline_c=\varnothing\quad\lor\quad Date_s\le Deadline_c

Gọi $I$ là inventory session dựng độc lập từ request, $P$ là planned và $D$ là deferred. Exact-once yêu cầu multiset:

P\uplus D=I

Ngoài ra, session index của mỗi unit phải là prefix liên tục $0,1,\ldots,n-1$ .

Cách vận hành

Dựng inventory từ remaining_work_minutes và baseline công khai, không đọc danh sách output và không gọi private helper của allocator.
Dựng lại lattice ngày × timeframe từ request.
Thu planned/deferred bằng key (learning_unit_id, session_index).
Trừ planned minutes khỏi lattice để có residual capacity.
Tính lại reason code và shortfall_minutes cho từng deferred session.
Cộng tám counter; P0 chỉ PASS khi tất cả bằng 0.

Các counter:

deadline_violation_count
capacity_violation_count
minute_conservation_error
duplicate_session_count
lost_session_count
invalid_session_sequence_count
invalid_deferral_reason_count
unexplained_deferral_count

12.4. Differential/Exact Oracle Evaluation — P0

Lý thuyết

Differential evaluation chạy cùng một input qua hai implementation độc lập rồi so kết quả theo objective đã công bố. Ở đây implementation A là allocator greedy least-slack-first; implementation B là exact dynamic programming offline.

Oracle chỉ nhận case có tối đa 12 session và 6 slot. State:

State=(slot\_index,remaining\_capacity,prefix_1,\ldots,prefix_k)

Mỗi transition hoặc đóng slot hiện tại, hoặc đặt next-prefix session của một unit nếu session vừa residual capacity và không qua deadline. Không dùng timeout theo đồng hồ nên cùng input luôn duyệt cùng state space.

Objective lexicographic:

\max\left( ScheduledMinutes, ScheduledSessionCount, PriorityUtility, -CanonicalAssignment \right)

Trong đó:

PriorityUtility_s=MaxRank+1-PriorityRank_s

Canonical assignment dùng tuple (date, timeframe, learning_unit_id, session_index) để phá thế tất định.

Công thức regret

ScheduledMinutesRegret=M_{oracle}-M_{planner}

DeferredMinutesRegret=D_{planner}-D_{oracle}

ExtraSessionCount=N_{oracle}-N_{planner}

Zero minute-regret chưa đủ nếu objective thứ hai vẫn cho oracle nhiều session hơn. P0 yêu cầu cả ba bằng 0 trên corpus oracle.

Ý nghĩa kết quả

Regret dương chứng minh tồn tại allocation khả thi tốt hơn theo objective đã chọn cho chính input đó. Nó chưa tự chứng minh allocator production “sai”: trước khi sửa phải xác nhận objective oracle đúng với policy sản phẩm và counterexample không đến từ lỗi checker.

12.5. Property-based và Metamorphic Evaluation — P0

Lý thuyết

Khi không thể liệt kê mọi input, generator seeded lấy mẫu nhiều tổ hợp hợp lệ. Metamorphic testing không cần expected output hoàn chỉnh; nó kiểm quan hệ bắt buộc giữa output gốc $f(x)$ và output sau biến đổi $f(T(x))$ .

Các quan hệ equality:

f(reverseItems(x))=f(x)

f(reverseWindows(x))=f(x)

f(addZeroCapacityWindow(x))=f(x)

Quan hệ monotonicity:

DeferredMinutes(extendDeadline(x))\le DeferredMinutes(x)

DeferredMinutes(increaseCapacity(x))\le DeferredMinutes(x)

Khi xóa một unit, chỉ so các session identity còn tồn tại; deferred minutes của chúng không được tăng.

Generator dùng random.Random(seed), version agent4-seeded-v1, capacity thuộc {0,60,120,180} và phân tầng deadline trước start/trong horizon/ngoài horizon/null. Hash toàn payload được lưu trong artifact.

12.6. Quality và Stability — P1 mô tả

P1 giúp phát hiện vùng cần tối ưu nhưng chưa là release gate vì chưa có threshold được phê duyệt.

Capacity utilization:

Utilization=\frac{TotalPlannedMinutes}{H\times DailyCapacity}

Planned/deferred ratios:

PlannedRatio=\frac{TotalPlannedMinutes}{InventoryMinutes}

DeferredRatio=\frac{TotalDeferredMinutes}{InventoryMinutes}

Priority inversion thô đếm cặp session theo thời gian mà session sớm có rank số lớn hơn session muộn. Đây không mặc định là lỗi vì least-slack-first được phép ưu tiên deadline. Course starvation thô đếm môn có inventory nhưng không có session planned; metric cũng gồm case không capacity hoặc deadline đã qua nên phải đọc cùng context.

Stability dùng session identity (learning_unit_id, session_index). Với placement map trước/sau perturbation:

ChurnRate=\frac{|\{s:Placement_{before}(s)\ne Placement_{after}(s)\}|} {|Identity_{before}\cup Identity_{after}|}

Perturbation gồm kéo deadline, tăng capacity không đổi sessionization và xóa item cuối priority set. Báo cáo mean/p50/p95 theo nearest-rank.

12.7. Performance — P1 mô tả

Sau 5 warm-up, mỗi cỡ nhỏ/vừa/lớn chạy 100 vòng bằng perf_counter_ns. Báo cáo latency p50/p95/max và throughput. Timing phụ thuộc máy, bị loại khỏi reproducibility hash và chưa làm CI fail khi chưa có SLA.

12.8. Reproducibility của Agent 4 — P0 nền tảng

Harness chạy deterministic payload hai lần:

h_i=SHA256(CanonicalJSON(Payload_i))

Reproducible\iff h_1=h_2

Artifact pin seed, generator version, allocator/schema/baseline hashes, manifest và 30 file của mười golden scenario. Performance nằm ngoài hash. evaluated_at phải có timezone và không được lấy từ đồng hồ ngầm.

13. Kết quả Agent 4 — snapshot v2 (mới nhất)

Snapshot hiện hành là eval/results/agent4_planner_evaluation_v2.{json,md}, evaluated_at = 2026-08-31T12:00:00+00:00, chạy trên allocator PLANNER_VERSION = 1.1.0-deterministic với PACING_MODE = balanced. Cấu hình: seed 42, 10 golden scenario, 1.000 property case, 200 oracle case, generator agent4-seeded-v1.

Nhóm	Kết quả	Trạng thái
Golden regression	0/10 mismatch; 0 lỗi manifest	PASS
Invariants	0 lỗi ở cả 8 counter trên 1.010 case	PASS
Metamorphic	0/5.382 violation trên 1.000 case	PASS
Reproducibility	hai hash `a792f1b...5dd1` giống nhau	PASS
Exact oracle	regret 30 phút; 6 extra session; 7/200 case dương	FAIL
P0 tổng	Có oracle regret	FAIL

Oracle xếp được 10.530 phút, allocator xếp 10.500 — chênh đúng 30 phút, và deferred_minutes_regret cũng là 30. Trong bảy counterexample, hai case có minute-regret dương và sáu case có extra session; hai nhóm giao nhau. Pattern chính: allocator greedy có thể dùng một slot cho session dài trước, trong khi oracle ghép được nhiều session ngắn hơn hoặc tổng phút cao hơn. Counterexample đầy đủ nằm trong JSON artifact.

P1 trên 1.000 property case (descriptive_only, không tham gia PASS/FAIL):

Metric	Mean	P50	P95
Capacity utilization	0.1699	0.0000	0.8750
Planned minutes ratio	0.6315	1.0000	1.0000
Deferred minutes ratio	0.3685	0.0000	1.0000
Priority inversion/case	1.671	0	10
Course starvation/case	1.142	0	4
Churn rate/scenario có perturbation	0.4101	0.3333	1.0000

Stability chạy 1.460 biến thể trên 833 scenario. Performance được đo ngoài deterministic payload (measured_outside_deterministic_payload) và không phải release gate; trên máy ghi trong artifact (Python 3.11.9, Windows), latency p50/p95 là 0.019/0.0202 ms ở cỡ nhỏ, 0.1168/0.1504 ms ở cỡ vừa và 0.1399/0.2429 ms ở cỡ lớn. Đây là số đo mô tả của một máy, không phải SLA.

Snapshot v1 (eval/results/agent4_planner_evaluation_v1.{json,md}, 2026-08-23, 8 scenario) vẫn được giữ bất biến để đối chiếu lịch sử; nó cho cùng kết luận P0 FAIL với cùng 30 phút regret. Không sửa artifact cũ để nó trông như đã luôn chạy policy pacing mới.

Lệnh chạy:

.venv/bin/python scripts/evaluate_agent4_planner.py \
  --seed 42 \
  --property-cases 1000 \
  --oracle-cases 200 \
  --output eval/results/agent4_planner_evaluation_v2.json \
  --report eval/results/agent4_planner_evaluation_v2.md \
  --evaluated-at "2026-08-31T12:00:00+00:00"

PASS của các nhóm P0 khác chỉ chứng minh contract, invariant và reproducibility trên corpus đã chạy. Nó không chứng minh lịch tối ưu trên mọi input, hợp lý về sư phạm hay cải thiện kết quả học tập thật.

14. Thuật ngữ

Ground truth: nhãn tham chiếu độc lập với system output.
Annotation: nhãn vòng một của từng reviewer.
Adjudication: phân xử bất đồng để tạo final reference.
Evidence sufficiency: evidence có đủ để gán verified theo policy hay không.
Independent outcome: kết quả không tái sử dụng diagnostic evidence.
Calibration: dự đoán 0.8 tương ứng outcome trung bình xấp xỉ 0.8.
Reproducibility: cùng input/version/code tạo cùng kết quả có thể kiểm chứng.

Phương pháp đánh giá và kiểm chứng

On this page