Incomex AI Portal
KB-5A7E rev 3

Nguyên tắc Soạn Luật — SSOT v1.1

8 min read Revision 3

Nguyên tắc Soạn Luật — SSOT

v1.1 | 2026-04-19 | S178 Fix 18. Làm rõ §VIII amend flow: phân biệt article_number vs registry code, bổ sung convention đặt tên code amend. v1.0 | 2026-04-09 | Tách từ OR v7.55 §XII. Dùng khi soạn/sửa/amend bất kỳ điều luật nào trong Hiến pháp.

Tài liệu này CHỈ áp dụng khi soạn luật. Điều hành thường nhật dùng operating-rules.md riêng.

I. NGUYÊN TẮC NỀN

  1. Mục tiêu trước, chi tiết sau. Không lao vào schema/trigger trước khi trả lời được câu hỏi "luật này giải quyết vấn đề gì?".
  2. Hiến pháp chỉ đặt nguyên tắc + liệt kê tên luật. Mỗi điều luật mới phải có 1 dòng trong HP.
  3. Mọi luật phải khép kín. Hình dung được tình huống sai + cách xử lý.
  4. Luật không có giải pháp tự động = luật sai. Làm tay = thiết kế sai.

II. THỨ TỰ SOẠN

Bước 1 — Mục tiêu (bắt buộc chốt trước):

  • Vấn đề cụ thể cần giải quyết là gì?
  • Câu hỏi nào luật này trả lời?
  • Rõ ràng, ngắn gọn, không lý thuyết.

Bước 2 — Giải pháp tóm tắt:

  • Cách giải quyết cốt lõi (1-3 câu).
  • Khả thi, khép kín.
  • Desktop thống nhất giải pháp trước khi cho phép viết chi tiết.

Bước 3 — Viết chi tiết (5 phần).

III. CÔNG THỨC 5 PHẦN — BẮT BUỘC

Mọi điều luật PHẢI viết đủ 5 phần, từ tổng quát đến chi tiết:

Phần Nội dung Yêu cầu
1. Mục tiêu Vấn đề cần giải quyết, câu hỏi cần trả lời Rõ ràng, ngắn gọn, không lý thuyết
2. Giải pháp Giải pháp thực hiện từng mục tiêu Khả thi, khép kín, hình dung tình huống sai
3. Thành phần Bảng, trigger, DOT, config, collection con Danh sách cụ thể
4. Quy trình Quy trình thực hiện (6W) Khép kín, từng bước, có điểm đầu + điểm cuối
5. Chi tiết triển khai Schema, seed data, phân giai đoạn Đủ để agent triển khai

IV. MỖI GIẢI PHÁP — 5 CÂU HỎI BẮT BUỘC

# Câu hỏi
1 Giải pháp thiết kế kỹ thuật? (bảng, FK, junction)
2 Quy trình thực thi? (liệt kê + đặt tên)
3 DOT thực thi? (dual-trigger)
4 Quản trị sự thay đổi? (phát hiện + xử lý tự động)
5 Tự động 100%? (làm tay = thiết kế sai)

Trả lời thiếu 1 câu = giải pháp chưa đủ, chưa được viết chi tiết.

V. MỖI QUY TRÌNH — 7 THÔNG TIN BẮT BUỘC

# Thông tin Mô tả
1 Mã QT-{luật}-{stt} (quy trình phối hợp) hoặc DOT-{mã} (quy trình gọn trong 1 DOT)
2 Nhiệm vụ chính 1 câu mô tả QT làm gì
3 Điểm đầu Sự kiện/trigger nào khởi động QT
4 Điểm cuối Trạng thái nào = QT hoàn thành
5 Đối tượng phục vụ Luật/module nào dùng QT này (ban đầu = luật gốc, có thể thêm)
6 Mã gốc "Quê quán" — luật nào sinh ra QT này
7 Phục vụ MT QT phục vụ mục tiêu nào của luật gốc

VI. 2 LOẠI QUY TRÌNH

  • QT-{luật}-{stt}: Quy trình phối hợp dài hạn, nhiều bước, nhiều DOT tham gia.
  • DOT-{mã}: Quy trình gọn trong 1 DOT — các thông tin quản lý (7 mục) vẫn giống nhau.

Cả 2 loại đều quản lý trong collection workflows với cùng schema. Điểm đầu + điểm cuối của mỗi QT/DOT là data cần quản lý riêng (collection con workflow_endpoints hoặc tương đương).

VII. CHECKLIST TRƯỚC KHI BAN HÀNH LUẬT MỚI

  • Đã trả lời được "luật này giải quyết vấn đề gì?" bằng 1-2 câu rõ ràng
  • Đã viết đủ 5 phần theo §III
  • Mỗi giải pháp đã trả lời đủ 5 câu theo §IV
  • Mỗi quy trình có đủ 7 thông tin theo §V
  • Đã bổ sung 1 dòng tên luật vào Hiến pháp
  • Không có bước làm tay (CQ-3 tự thích nghi N, NT-02 tự động 100%)
  • Đã hình dung tình huống sai + cách phát hiện + cách xử lý tự động
  • Desktop đã duyệt mục tiêu + giải pháp tóm tắt TRƯỚC khi viết chi tiết

VIII. AMEND LUẬT CÓ SẴN

§VIII.1 Nguyên tắc amend

  • Amend = giữ số điều (article_number) cũ, tăng version (vd: Đ27 v1.0 → v2.0).
  • Ghi rõ phần nào sửa, phần nào giữ.
  • Nếu amend đổi scope lớn → cân nhắc tạo luật mới thay vì amend.
  • Mọi amend vẫn phải qua checklist §VII.

§VIII.2 Phân biệt article_number và registry code (v1.1)

  • article_number = số điều luật (22, 35, HP...) — giữ nguyên qua mọi phiên bản. Đây là "mã điều luật" theo nghĩa pháp lý.
  • code = mã nội bộ trong normative_registry (NRM-LAW-22, NRM-CON-HP...) — PK duy nhất, mỗi phiên bản có code riêng.
  • Khi amend: article_number giữ nguyên, code tạo mới. Bản cũ được đánh dấu superseded_by trỏ sang bản mới.

§VIII.3 Convention đặt tên code khi amend (v1.1)

  • Format: {BASE_CODE}-V{MAJOR}P{MINOR} — P = point (thay dấu chấm, tránh ký tự đặc biệt trong code).
  • Ví dụ: NRM-LAW-22 (v1.0) → amend v1.1 → code mới = NRM-LAW-22-V1P1.
  • HP: NRM-CON-HP (v4.6.2) → amend v4.6.3 → code mới = NRM-CON-HP-V4P6P3.
  • Code bản gốc (không có hậu tố) luôn là bản đầu tiên seed vào registry.
  • Sau amend, bản cũ giữ status='enacted' + superseded_by trỏ bản mới. Retire bản cũ khi không cần giữ song song.

2 kiểu amend:

Kiểu A — Code-split (mặc định): Tạo code mới theo convention trên. Bản cũ nhận superseded_by trỏ sang bản mới. Dùng khi amend thay đổi nội dung luật, cần giữ trace lịch sử 2 phiên bản.

Kiểu B — In-place: Giữ nguyên code, chỉ bump version trong cùng row. Không tạo row mới, không có superseded_by. Dùng khi amend thuần extension/config (thêm section, thêm config key) mà không thay đổi nội dung pháp lý cốt lõi. Ví dụ: Đ43 v1.2 nhận extension ops_code_inventory — triết lý giữ 100%, chỉ mở rộng vận hành.

Quy tắc chọn kiểu: Nếu amend thay đổi điều khoản (§), quyền, nghĩa vụ, schema bảng → Kiểu A bắt buộc. Nếu chỉ bổ sung config/extension mà không sửa điều khoản → Kiểu B cho phép.

§VIII.4 Công cụ amend

  • Dùng DOT_NRM_AMEND (--code <old> --new-code <new> --new-version <ver>).
  • Script tự: INSERT draft mới + UPDATE old.superseded_by + INSERT normative_relations.
  • Sau đó dùng DOT_NRM_ENACT (--code <new>) để ban hành bản mới.
  • DOT_NRM_ENACT yêu cầu APR approved cho target code trước khi enact.

Các bước hậu enact bắt buộc (sau khi DOT_NRM_ENACT thành công):

Bước H1 — Kế thừa enforcement (chỉ Kiểu A):

  • Query: SELECT code FROM normative_registry WHERE superseded_by = <new_code>
  • Nếu tìm thấy predecessor: copy tất cả rows active từ law_dot_enforcement WHERE law_code = <old_code> sang law_code = <new_code>
  • Nếu predecessor có 0 enforcement rows VÀ nrm_doc_type_config.requires_enforcement = true → INSERT system_issues kind='enforcement_gap_inherited' (cảnh báo, không chặn)
  • Kiểu B: bỏ qua bước này (code không đổi, enforcement giữ nguyên)

Bước H2 — Retire bản cũ (chỉ Kiểu A):

  • UPDATE normative_registry SET status = 'retired' WHERE code = <old_code>
  • Trigger nrm_enacted_immutable cho phép chuyển enacted → retired (đã xác nhận)
  • Kiểu B: bỏ qua bước này (không có bản cũ riêng)

Bước H3 — Verify enforcement (cả 2 kiểu):

  • Query: SELECT COUNT(*) FROM law_dot_enforcement WHERE law_code = <enacted_code> AND status = 'active'
  • Nếu requires_enforcement = true VÀ count = 0 → DỪNG, báo lỗi
  • Nếu count > 0 → PASS

Thứ tự bắt buộc: H1 → H2 → H3. Không được đảo.

§VIII.5 Checklist hậu amend-enact

Sau mỗi lần amend + enact thành công, agent/operator PHẢI xác nhận:

  • Bản mới có enforcement records (H3 PASS)
  • Bản cũ đã retired (Kiểu A) hoặc N/A (Kiểu B)
  • normative_registry không có 2 bản cùng article_number đều status='enacted' (trừ khi có lý do giữ song song ghi rõ)
  • law_jurisdiction cho bản mới đã được cập nhật nếu scope thay đổi
  • admin_fallback_log không có entry overdue liên quan đến amend này

IX. THAM CHIẾU

  • Hiến pháp: knowledge/dev/laws/constitution.md
  • OR điều hành: knowledge/dev/ssot/operating-rules.md
  • Tracker luật: mục "Nhóm 3 — Soạn luật" trong project-progress-tracker.md

v1.1 | 2026-04-19 S178 Fix 18 | Làm rõ §VIII amend flow + convention code naming. v1.0 | 2026-04-09 | Tách từ OR v7.55 §XII để OR điều hành gọn hơn, tập trung hơn.