M-001: Thiết kế 3 Tầng Checkpoint

Version: v1-draft | Date: 2026-03-03 Lead: claude_ai | Critic: gemini Status: 🔨 Building (Sprint 3)

---

1. Tổng quan

Checkpoint = cơ chế xác nhận tiến độ tự động. Thay vì hỏi "xong chưa?", hệ thống tự biết qua 3 tầng kiểm tra.

Nguyên tắc: Con người KHÔNG làm tester. Hệ thống tự verify → tự tick → chỉ escalate khi cần.

2. Ba Tầng Checkpoint

┌─────────────────────────────────────────┐
│  L2 — User Approval                     │
│  Con người duyệt (chỉ exceptions)       │
│  ┌─────────────────────────────────────┐ │
│  │  L1 — AI Verification              │ │
│  │  AI Critic review + approve/reject  │ │
│  │  ┌─────────────────────────────────┐│ │
│  │  │  L0 — System Auto-check        ││ │
│  │  │  CI green, test pass, lint OK   ││ │
│  │  └─────────────────────────────────┘│ │
│  └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

L0 — System Auto-check (tự động 100%)

Checkpoint	Trigger	Nguồn
L0_ci_green	CI pipeline pass	GitHub Actions
L0_lint_pass	ESLint + TypeScript clean	CI
L0_test_pass	Unit/Integration tests pass	CI
L0_build_ok	Nuxt build thành công	CI
L0_deploy_ok	Deploy không lỗi	Firebase/VPS

Auto-tick: System comment [action: checkpoint_auto] → CommentModule tự tick L0.

L1 — AI Verification (bán tự động)

Checkpoint	Trigger	Nguồn
L1_code_review	AI đọc PR, check logic	AI Critic (Gemini)
L1_ssot_compliant	Tuân thủ SSOT/Constitution	AI Critic
L1_no_regression	Không phá chức năng cũ	AI review + L0 tests
L1_evidence_report	Có báo cáo kèm evidence	AI Lead

Quy trình:

1. AI Executor hoàn thành → comment [EXECUTOR] Done. PR #XXX
2. AI Critic review → comment [CRITIC] L1_code_review: PASS/FAIL + lý do
3. CommentModule tick/untick L1 dựa trên action trong comment

Phương án L1 enforcement (đã chốt S96): Phương án C — AI tự tạo, enforcement qua prompt. Nghĩa là: prompt hướng dẫn AI Critic phải check từng L1 checkpoint, nhưng không cần code enforcement phức tạp.

L2 — User Approval (chỉ khi cần)

Checkpoint	Trigger	Nguồn
L2_user_approved	User click approve	UI button
L2_exception_handled	User xử lý exception	Manual

Khi nào cần L2:

• L1 có FAIL → escalate lên User
• Task quan trọng (blueprint, SSOT change) → bắt buộc L2
• AI không chắc chắn → request L2

3. UI Design — CheckpointPanel

┌── Checkpoint Progress ────────────────────┐
│                                            │
│  L0 System    [████████████] 5/5  ✅       │
│  ├─ CI green          ✅                   │
│  ├─ Lint pass         ✅                   │
│  ├─ Tests pass        ✅                   │
│  ├─ Build OK          ✅                   │
│  └─ Deploy OK         ✅                   │
│                                            │
│  L1 AI Review [██████░░░░░░] 3/4  ⏳       │
│  ├─ Code review       ✅ (Gemini)          │
│  ├─ SSOT compliant    ✅                   │
│  ├─ No regression     ✅                   │
│  └─ Evidence report   ⏳ (pending)         │
│                                            │
│  L2 User     [░░░░░░░░░░░░] 0/1  🔒       │
│  └─ Approval          🔒 (waiting L1)      │
│                                            │
│  Overall: 8/10 — 80%                       │
└────────────────────────────────────────────┘

4. Data Model — Checkpoints

Collection: task_checkpoints (Directus — cần tạo mới)

Field	Type	Description
id	integer (PK)	Auto
task_id	integer (FK)	Task liên kết
checkpoint_key	string	VD: L0_ci_green, L1_code_review
layer	enum (L0/L1/L2)	Tầng
status	enum	pending / passed / failed / skipped
verified_by	string	agent_type hoặc "user"
comment_id	integer (FK, nullable)	Comment đã trigger checkpoint
date_updated	datetime	Auto

Comment → Checkpoint Auto-tick Flow

Comment created (action = "checkpoint_auto")
  → Parse checkpoint_key từ content
  → Upsert task_checkpoints record
  → Emit event @checkpoint-updated
  → UI re-render CheckpointPanel

5. Liên kết Sprint

• Sprint 1: Tạo collection task_checkpoints trong Directus
• Sprint 3: Build CheckpointPanel.vue, auto-tick logic, L1 enforcement

6. Liên kết

• Design tổng thể: design.md
• Tầm nhìn: comment-module.md
• Execution Plan: modules-execution-plan.md

---

Claude Code CLI: Collection task_checkpoints cần tạo trước khi code CheckpointPanel. Check Sprint 1 status.