L5 Clarify Đ32 — Unit-level Review + Change-set Approval
CLARIFY ĐIỀU 32 — UNIT-LEVEL REVIEW + CHANGE-SET APPROVAL
L5 Điều 38
Trạng thái: DỰ THẢO — chờ Council review + User duyệt Loại: Clarify Đ32 (Luật Phê duyệt v1.1) Tiền đề: L1 (Text Unit), L2 (Component/BOM), L3 (Metadata Governance), L4 (Birth Gate) Đóng blocker: 02D0 blocker "Đ32 chưa clarify unit-level review + change-set" Che phủ hở: 02DX QĐ6 — "Đ32 chưa clarify unit-level approval + change-set" GPT review: PASS, 16 chỉnh + 5 khuyến nghị đã áp dụng (vòng 1 + vòng 2)
§1. Mục đích
Clarify Đ32 để phê duyệt hoạt động ở cấp unit và change-set, không chỉ ở cấp document/system action. Đ32 v1.1 đã chốt APR flow chuẩn hóa (approval_requests, quorum, lifecycle) — L5 mở rộng granularity xuống unit mà không phá cơ chế lõi Đ32.
Vấn đề hiện tại: Đ32 phê duyệt ở mức "1 request = 1 action trên 1 object". Khi chuyển sang unit-centric (L1), sửa 1 văn bản có thể ảnh hưởng 10-50 units. Nếu mỗi unit 1 APR → quá tải. Nếu chỉ 1 APR cho cả document → mất traceability unit nào sửa gì.
Giải pháp: Change-set gom nhiều thay đổi, review ở cấp unit, approve ở cấp change-set thông qua APR Đ32.
§2. Phạm vi
Áp dụng cho review/approval mọi thay đổi nội dung trong scope Đ38: text unit sửa/tạo/retire, component changes thuộc scope Đ38/component registry khi được gom trong change-set, document version bump. Không thay đổi Đ32 cho các APR system-level hiện hành (birth, reclassify, amend law...).
Không làm: Không viết schema/trigger/workflow engine/UI cụ thể. Không định nghĩa lại L1/L2/L3/L4. Không thay đổi APR quorum/lifecycle lõi của Đ32. Không quyết định UI comment/thread model.
§3. Định nghĩa
§3.1 Review
Rà soát chất lượng nội dung/metadata của 1 unit hoặc 1 component. Review gắn vào unit/component riêng lẻ — mỗi unit có review state riêng.
Review ≠ approval. Review = "tôi đã đọc và đánh giá". Approval = "tôi cho phép chính thức hóa" (qua APR Đ32). Review có thể do agent hoặc human thực hiện. Approval phải tuân thủ quorum Đ32.
Review result và APR decision không được xóa/ghi đè. Re-review tạo cycle/record mới để giữ audit trail.
§3.2 Review state
Mỗi unit/component có review state riêng ở mức metadata (L3). Review state tối thiểu phân biệt: chưa review / đang review / review pass / review fail / cần re-review.
Tên trạng thái kỹ thuật/enum cụ thể thuộc design phase.
§3.3 Change-set
Tập hợp có chủ đích các thay đổi ở nhiều units/components, được gom lại để review chung, approve chung, và bump document version.
Đặc điểm:
- Change-set có scope rõ: liệt kê unit/component nào thay đổi, thay đổi gì (tạo mới / sửa version / retire).
- Change-set có lifecycle riêng (xem §5.2) — TÁCH BIỆT với APR lifecycle Đ32.
- Change-set có owner: ai tạo, ai chịu trách nhiệm.
- Change-set gắn vào 1 hoặc nhiều documents. Thông thường 1 document, nhưng cross-document change-set có thể xảy ra (VD: amend luật + sửa SOP liên quan).
§3.4 Change-set snapshot
Snapshot = tập object_id + version_id + diff/evidence tại thời điểm submit. Snapshot là bằng chứng đóng băng — reviewer và approver đánh giá trên snapshot, không phải trên object sống.
§3.5 Change-set ≠ APR
Change-set là container gom thay đổi. APR (Đ32) là cơ chế phê duyệt. Khi change-set submitted → tạo hoặc liên kết APR hợp pháp qua DOT theo Đ32 → quorum approve APR → change-set enacted.
Change-set bổ sung Đ32, không thay thế. Mọi approval vẫn đi qua APR pipeline. APR payload/evidence cũng phải self-contained hoặc tham chiếu hợp lệ tới change-set snapshot.
§4. Review gắn vào unit
§4.1 Nguyên tắc
Review unit cha KHÔNG tự động approve con (L1 §4.6). Mỗi unit trong change-set phải được review riêng hoặc được rule cho phép batch review.
§4.2 Batch review
Để tránh quá tải, cho phép batch review khi:
- Thay đổi nhỏ (VD: typo fix, metadata update) → rule cho phép reviewer đánh dấu "batch pass" cho nhiều units.
- Thay đổi lớn (VD: viết lại nội dung, thêm section mới) → phải review từng unit.
Phân loại thay đổi nhỏ/lớn = config rule, không hardcode trong phụ lục pháp lý. Mặc định: nếu không có rule phân loại, mọi thay đổi cần review riêng.
§4.3 Review không tự động cascade
- Review parent ≠ review children.
- Review 1 unit ≠ review units tham chiếu ngang (edges).
- Sửa unit → unit liên quan có thể cần re-review (DOT phát hiện impact, nhắc reviewer).
§4.4 Ai review?
- Agent có thể review (đánh giá chất lượng, kiểm logic, kiểm nhất quán).
- Human approval bắt buộc theo quorum Đ32 đối với high/medium risk. Human review requirement là policy/config theo risk — không hardcode trong L5.
- Review result = metadata trên unit (L3), không phải approval decision.
§5. Change-set gom thay đổi
§5.1 Tạo change-set
Agent hoặc human tạo change-set, liệt kê units/components bị ảnh hưởng. Change-set phải self-contained: đọc change-set phải hiểu scope thay đổi mà không cần truy thêm ngoài luồng (đồng nhất với Đ32 §2.2).
§5.2 Change-set lifecycle
Đây là lifecycle của change-set, KHÔNG phải APR lifecycle. APR vẫn tuân thủ Đ32 lifecycle riêng: pending → approved → applied hoặc pending → rejected/expired. Khi APR đạt approved/applied thì change-set mới được enacted theo rule.
draft → submitted → review_passed → approval_passed → enacted/applied
↘ rejected / withdrawn
| Trạng thái | Mô tả |
|---|---|
| draft | Đang soạn. Units có thể thay đổi. Chưa tạo APR. |
| submitted | Snapshot đóng băng. Tạo hoặc liên kết APR qua DOT theo Đ32. |
| review_passed | Tất cả units trong change-set đã review pass (hoặc batch pass theo rule). |
| approval_passed | APR đã pass quorum theo Đ32 §4.2. Change-set chờ enacted. |
| enacted/applied | Thay đổi chính thức. Units sửa → version mới enacted. Document bump version. |
| rejected | APR bị reject. Change-set có thể sửa và re-submit. |
| withdrawn | Owner rút change-set trước khi approval hoàn tất. |
§5.3 Đóng băng khi submitted
Khi change-set submitted → snapshot/versions trong change-set bị đóng băng. Sửa tiếp phải tạo revision mới hoặc withdraw/re-submit theo rule. Không sửa lén khi đang chờ approve.
§5.4 Cross-document change-set
Nếu thay đổi ảnh hưởng nhiều documents → 1 change-set gom hết. Mỗi document liên quan bump version khi enacted. Authority/quorum áp theo risk cao nhất trong set.
§6. Document approval tổng hợp
§6.1 Aggregate rule
Document approval = tổng hợp từ change-set approval. Trong scope Đ38, không approve document trực tiếp mà bỏ qua unit/change-set. Trừ APR system-level/document-level hiện hành ngoài scope Đ38 hoặc legacy flow — L5 không thay đổi các flow đó.
| Cấp | Cơ chế |
|---|---|
| Unit | Review (pass/fail) |
| Change-set | Gom units → APR → quorum approve |
| Document | Version bump khi change-set enacted |
§6.2 Document version bump
Document version bump được system-driven theo rule khi change-set enacted/applied. Ví dụ mặc định:
- Minor bump: thay đổi nội dung units (sửa text, thêm section).
- Major bump: thay đổi cấu trúc (thêm/xóa article, merge/split document).
Đây là ví dụ mặc định; phân loại version bump theo config/authority, không chốt pháp lý ở L5.
§6.3 Document enacted và published snapshot
Document enacted chỉ bao gồm tập units enacted/current thuộc published snapshot. Unit draft mới có thể tồn tại ngoài published snapshot/change-set, nhưng không làm document enacted chứa draft canonical. DOT kiểm nếu draft lọt vào published snapshot.
§7. Authority và quorum
§7.1 Tuân thủ Đ32 quorum
Change-set approval tuân thủ Đ32 §4.2 quorum hiện hành:
- high risk: ≥1 president approve + ≥2 ai_council approve + 0 reject
- medium risk: ≥1 president approve
- low risk: ≥1 approve hoặc rule auto-approve
Theo Đ32 hiện hành; nếu Đ32 amend thì L5 theo Đ32.
§7.2 Risk classification cho change-set
Risk tối thiểu = risk cao nhất trong set. Có thể nâng risk theo authority/rule; không hạ dưới max nếu không có exception/amend hợp pháp.
Risk classification cho từng loại thay đổi = config data. Ví dụ mặc định:
- Tạo mới/retire luật, amend cấu trúc = high
- Sửa nội dung luật, tạo SOP mới = medium
- Typo fix, metadata update = low
Config cụ thể thuộc design/seed phase.
§7.3 Human authority
- Enacted = bất biến (L1 §4.2). Sửa enacted unit phải qua change-set + APR mới.
- Agent không tự approve change-set chứa enacted content change. Phải có human authority.
- Self-approve cấm cho high-risk (Đ32 §4.3).
§8. Quan hệ với các metadata từ L3
§8.1 Review state = metadata trên unit/component
Review state (§3.2) là metadata field trên unit/component, quản theo L3. Fill type = agent manual (reviewer cập nhật) hoặc system auto (khi change-set enacted → review state transition theo rule: có thể chuyển sang current/accepted/archived). Tên trạng thái cụ thể thuộc design phase. DOT daily có thể kiểm consistency (VD: unit review pass nhưng change-set rejected → cần re-review).
§8.2 Approval status = metadata trên change-set
Change-set lifecycle (§5.2) có approval status riêng. Khi APR approval_passed → change-set status = approval_passed. Metadata này nằm ở cấp change-set, không trùng với unit review state.
§8.3 Enacted = lifecycle transition
Enacted là lifecycle transition (Đ4, L1 §3.7). Khi change-set enacted → units version mới transition sang enacted. Metadata cập nhật theo L3 (timestamps, version, status).
§8.4 APR/change-set metadata phải PG-native
Mọi metadata liên quan APR và change-set phải sống trong PG (Đ33, HP NT13). Không dùng file/KB/external store làm source of truth cho approval data.
§9. Quan hệ với birth gate (L4)
§9.1 Birth gate ≠ review/approval
Birth gate (L4) kiểm completeness tại INSERT. Review/approval (L5) kiểm nội dung + chất lượng sau INSERT. 2 cơ chế bổ sung:
- Unit mới tạo → qua birth gate (L4) → vào PG ở status draft → sống trong change-set → review → approve → enacted.
- Birth gate exception approval (L4 §7.3) đi qua APR Đ32, cùng pipeline.
§9.2 Version mới của enacted unit
Sửa enacted unit = tạo version mới (L1 §3.8). Version mới đi qua birth/creation validation tương ứng nếu được tạo như object/version record mới; cơ chế cụ thể theo L4/design. Version mới vào change-set + review + approve.
§10. Nguyên tắc bắt buộc
| # | Nguyên tắc | Cơ sở |
|---|---|---|
| 1 | Review gắn vào unit, không gắn vào document. Mỗi unit review state riêng. | L1 §4.6, QĐ6 |
| 2 | Review parent ≠ approve children. Không cascade. | L1 §4.6 |
| 3 | Change-set là container, APR là cơ chế approve. Mọi approval đi qua Đ32 APR pipeline. Change-set lifecycle tách biệt APR lifecycle. | Đ32 |
| 4 | Đóng băng snapshot khi submitted. Không sửa lén khi chờ approve. Sửa = withdraw/re-submit. | Đ32 §2.2, integrity |
| 5 | Quorum theo Đ32 §4.2 hiện hành. Risk-based. Change-set risk tối thiểu = max trong set. | Đ32 §4.2 |
| 6 | Enacted = bất biến. Sửa enacted = version mới + change-set + APR. | L1 §4.2, Đ4 |
| 7 | Agent không tự approve change-set chứa enacted content change. Phải human authority. | Đ32 §4.3 |
| 8 | Document version bump system-driven theo rule khi change-set enacted. Document không approve riêng trong scope Đ38. | §6 |
| 9 | Batch review cho phép theo rule, không phải mặc định. Mặc định = review riêng từng unit. | §4.2 |
| 10 | Change-set phải self-contained. Đọc change-set hiểu scope mà không truy ngoài luồng. APR evidence tham chiếu snapshot hợp lệ. | Đ32 §2.2 |
| 11 | Review result và APR decision không xóa/ghi đè. Re-review tạo cycle/record mới. | Audit trail |
| 12 | Document enacted chỉ chứa units enacted/current. Draft không lọt vào published snapshot. | §6.3 |
§11. Ranh giới — không làm gì trong phụ lục này
| Không làm | Lý do |
|---|---|
| Không thay đổi APR schema/quorum/lifecycle lõi Đ32 | Giữ nguyên Đ32 v1.1. L5 chỉ clarify granularity. |
| Không viết schema change-set cụ thể (bảng, cột, FK) | Design phase |
| Không viết workflow engine/UI cho review flow | Ngoài scope |
| Không chốt review tool/DOT list cụ thể | Design phase |
| Không định nghĩa lại text unit / component / metadata | Thuộc L1, L2, L3 |
| Không chốt birth gate enforcement | Thuộc L4 |
| Không chốt risk classification config cụ thể | Config data thuộc design/seed phase |
| Không quyết định UI comment/thread model | Ngoài scope phụ lục pháp lý |
§12. Liên kết với luật hiện hành
| Luật | Quan hệ |
|---|---|
| Đ32 v1.1 | L5 clarify granularity xuống unit + change-set. Giữ nguyên APR/quorum/lifecycle. |
| L1 (Text Unit) | Review gắn vào unit. Enacted bất biến. Version theo unit. |
| L2 (Component/BOM) | Component review + reuse decision trong change-set. |
| L3 (Metadata) | Review state + approval status = metadata fields. Fill/check theo L3. |
| L4 (Birth Gate) | Birth gate ≠ review/approval. 2 cơ chế bổ sung. Version mới qua cả 2. |
| Đ4 (Lifecycle) | Enacted = lifecycle transition. Change-set enacted → units transition. |
| Đ33 (PG) | APR/change-set metadata phải PG-native. |
| HP NT2 | Cơ chế máy: đóng băng, quorum check, cascade block. |
| HP NT13 | PG First. APR data sống trong PG. |
§13. Điều kiện PASS
| # | Điều kiện |
|---|---|
| 1 | Review gắn vào unit rõ ràng, nhất quán với L1 §4.6 |
| 2 | Change-set định nghĩa rõ, bổ sung Đ32 không thay thế. Lifecycle tách biệt APR lifecycle. |
| 3 | Document approval = aggregate từ change-set, nhất quán. Document enacted chỉ chứa units enacted/current. |
| 4 | Quorum tuân thủ Đ32 §4.2 hiện hành |
| 5 | Enacted bất biến nhất quán với L1, Đ4 |
| 6 | Birth gate vs review/approval phân tách rõ |
| 7 | Không trượt sang schema/workflow engine/UI |
| 8 | Không thay đổi APR lõi Đ32 |
| 9 | L5 cùng L1–L4 đóng toàn bộ legal blocker trong 02D0 |
| 10 | Council review + User duyệt |
DỰ THẢO | L5 Clarify Đ32 — Unit-level Review + Change-set Approval | GPT review: PASS (vòng 1 + vòng 2), 16 chỉnh + 5 khuyến nghị đã áp dụng | Chờ Council + User