KB-B518 rev 3
BAN HÀNH — Description Governance Package R2 FINAL (Fix 27)
15 min read Revision 3
enactedlaw-amendmentdieu3dieu4dieu35dieu43descriptionNT14council-r2-final
DỰ THẢO SỬA LUẬT — DESCRIPTION GOVERNANCE PACKAGE (R2 FINAL)
Tuân thủ NT14 (Thực thi được ngay) + NT2 (Tự động 100%)
Phiên: S178 Fix 27 | Ngày: 2026-04-22 Tác giả dự thảo: Claude Desktop Căn cứ: HP v4.6.3 NT14 rà soát phát hiện 4 luật vi phạm "thực thi được ngay" về description governance. Phạm vi: Amend 4 luật (Đ3, Đ4, Đ35, Đ43) + 1 phụ lục mới. Mỗi luật chỉ sửa phần SSOT của mình (Đ37 §4.12). Trạng thái: ★ R2 FINAL — BAN HÀNH. Council:
- R1: Gemini 9.5 MINOR + GPT 8.3 CHANGES → 8/9 patches applied, 1 rejected (GPT P6)
- R2: Gemini 10 APPROVE FINAL + GPT 9.0 APPROVE WITH MINOR (P9) + Desktop 8.5 CHANGES (P9-P13) → áp P9 luật + 4 deployment notes
- Tổng: 9 patches luật + 4 deployment notes. 0 blocker.
TỔNG QUAN THAY ĐỔI
| Luật | Sửa gì | SSOT | Tính chất |
|---|---|---|---|
| Đ3 | +§2.5 Hai mức mô tả (cơ bản + chi tiết) + §2.6 viện dẫn phụ lục template | Quy cách description | Bổ sung khái niệm mới |
| Đ4 | Amend §2.1: birth guard tự AUTO-GEN mô tả cơ bản khi NULL + companion trigger gán PROV-DOT | Enforcement tại birth | Mở rộng chức năng |
| Đ35 | Amend §4.1.1: +mapping cột PG → 3 phần DOT template | DOT description contract | Chi tiết hóa NT14 |
| Đ43 | Amend §9.1: tách H11 → H11a (cơ bản, CRITICAL) + H11b (chi tiết, WARNING) | Health check nội dung | Tách mức giám sát |
| Phụ lục Đ3 | File mới: dieu3-phu-luc-description-templates.md |
Chi tiết quy cách | Living doc |
I. AMEND ĐIỀU 3 — LUẬT METADATA
+§2.5 — Hai mức mô tả (MỚI)
Mọi entity có cột description phân biệt 2 mức:
| Mức | Tên | Ai viết | Khi nào | Nội dung | Provenance (Đ24) |
|---|---|---|---|---|---|
| Cơ bản | Mô tả cơ bản | Hệ thống tự sinh (PG trigger tại birth — Đ4 §2.1) | INSERT tự động | Metadata có sẵn trong PG: lớp cấu tạo (Đ0-B), loài (Đ29), domain, trigger, paired — theo template §2.6 | PROV-DOT |
| Chi tiết | Mô tả chi tiết | AI agent hoặc người | Sau birth, batch hoặc on-demand | Nhiệm vụ cụ thể, ngữ cảnh, lý do tồn tại — nội dung ngữ nghĩa máy không tự suy luận được | PROV-AI hoặc PROV-HUMAN |
Quy tắc:
- Mô tả cơ bản = bắt buộc 100%, hệ thống tự sinh. Thiếu = hạ tầng hỏng.
- Mô tả chi tiết = nâng cao, có lộ trình. Thiếu = công việc chưa hoàn thành.
- Mô tả chi tiết GHI ĐÈ mô tả cơ bản (cùng cột
description). Provenance label chuyển từPROV-DOT→PROV-AI/PROV-HUMAN(Đ24 FAC-PROV). - ★ R1 Gemini P3: Mô tả chi tiết PHẢI bao hàm hoặc paraphrase thông tin cơ bản. Agent/người viết PHẢI đọc mô tả cơ bản hiện tại trước khi ghi đè.
- Kiểm tra mức: xem provenance label (Đ24).
PROV-DOT= chỉ cơ bản.PROV-AI/PROV-HUMAN= đã chi tiết.
Viện dẫn: Template → Phụ lục Đ3 §A.1. Enforcement → Đ4 §2.1. Giám sát → Đ43 §9.1 (H11a/H11b). Provenance → Đ24 FAC-PROV.
+§2.6 — Phụ lục Template mô tả cơ bản (MỚI)
★ R1 GPT P1 — SSOT phân rõ:
dot_config= runtime SSOT DUY NHẤT cho template. Trigger/function đọc từ đây.- Phụ lục Đ3 = documentation mirror. Khi thay đổi: UPDATE
dot_configTRƯỚC, cập nhật phụ lục SAU.
★ R1 GPT P2 — Lookup chain 4 tầng:
1. desc_template_<table>_<composition_level> (ưu tiên cao nhất)
2. desc_template_<table> (table-specific)
3. desc_template_level_<composition_level> (level-default)
4. desc_template_default (fallback cuối)
5. NULL → KHÔNG gen, fail-safe (NT9)
Ngôn ngữ: Tiếng Việt có dấu mặc định (Đ3 §2.1 C4). Giữ nguyên code/enum/thuật ngữ kỹ thuật.
Viện dẫn: Chi tiết template → Phụ lục Đ3 §A.1.
Sửa §2.2 — Thêm viện dẫn
Bảng trên = quy cách NỘI DUNG mô tả chi tiết (mức 2, §2.5). Mô tả cơ bản (mức 1) theo template §2.6 + Phụ lục Đ3. DOT riêng xem Đ35 §4.1.1.
II. AMEND ĐIỀU 4 — LUẬT SINH SẢN
Amend §2.1 — Birth guard: KIỂM TRA → KIỂM TRA + TỰ SINH
★ R1 GPT P3 — Contract fn_render_description_template() v1:
CREATE OR REPLACE FUNCTION fn_render_description_template(
p_template TEXT, p_row_data JSONB
) RETURNS TEXT
-- CONTRACT v1:
-- Placeholder: {key} với key phẳng [A-Za-z0-9_]+ ONLY
-- KHÔNG nested path ở v1
-- key không tồn tại / NULL → render '(chưa có)'
-- Dữ liệu chèn nguyên văn, KHÔNG eval regex
★ R1 GPT P4 — fn_description_context() cho computed placeholders:
CREATE OR REPLACE FUNCTION fn_description_context(
p_table_name TEXT, p_row JSONB
) RETURNS JSONB
-- Computed placeholders (cross-table):
-- species_code: LEFT JOIN species_collection_map WHERE collection_name = p_table_name AND is_primary = true
-- composition_level: LEFT JOIN entity_species ON species_code
-- governance_role: LEFT JOIN collection_registry WHERE collection_name = p_table_name
-- _source_table: p_table_name (inject runtime)
-- JOIN miss → key = null → fn_render renders '(chưa có)'
--
-- ★ R2: source_database XÓA khỏi contract v1 (không dùng trong template enacted hiện tại,
-- chưa có join source chuẩn). Thêm lại khi có template cần + join đã chốt.
★ R2 P9 — Tách rõ 2 trigger, CHỐT DỨT KHOÁT (GPT R2 + Desktop R2 đồng ý):
| Trigger | Timing | Function | Nhiệm vụ |
|---|---|---|---|
trg_desc_guard_<table> |
BEFORE INSERT OR UPDATE | fn_description_birth_guard() |
Lookup template 4 tầng → render → gán NEW.description. KHÔNG ghi entity_labels. |
trg_desc_provenance_<table> |
AFTER INSERT | fn_auto_label_provenance() |
INSERT entity_labels row PROV-DOT cho entity vừa sinh. Cùng transaction, entity đã tồn tại → FK safe. |
Logic BEFORE INSERT (fn_description_birth_guard — mở rộng):
IF _desc = '' THEN
-- Lookup template 4 tầng (Đ3 §2.6)
_comp_level := (fn_description_context(TG_TABLE_NAME, to_jsonb(NEW)))->>'composition_level';
-- 1→2→3→4→NULL fail-safe
...
IF _template IS NOT NULL THEN
_row_data := to_jsonb(NEW) || fn_description_context(TG_TABLE_NAME, to_jsonb(NEW));
NEW.description := fn_render_description_template(_template, _row_data);
END IF;
END IF;
-- Sau auto-gen, kiểm tra C1-C3 như cũ
Logic AFTER INSERT (fn_auto_label_provenance):
CREATE OR REPLACE FUNCTION fn_auto_label_provenance()
RETURNS TRIGGER AS $$
BEGIN
-- Chỉ gán nếu entity chưa có provenance label nào
IF NOT EXISTS (
SELECT 1 FROM entity_labels
WHERE entity_code = NEW.code
AND label_code IN ('PROV-DOT','PROV-AI','PROV-HUMAN')
) THEN
INSERT INTO entity_labels(entity_code, label_code, assigned_by)
VALUES (NEW.code, 'PROV-DOT', 'fn_auto_label_provenance')
ON CONFLICT DO NOTHING;
END IF;
RETURN NEW;
END; $$ LANGUAGE plpgsql;
Quy tắc:
- Auto-gen chỉ khi description NULL/rỗng. Đã có → KHÔNG ghi đè (NT9).
- Template NULL → KHÔNG gen, fail-safe.
- 2 trigger cùng transaction — entity ra đời đã có description + PROV-DOT, 0 khoảng trống.
Viện dẫn: Template source + lookup → Đ3 §2.6. Template nội dung → Phụ lục Đ3 §A.1. Provenance → Đ24 FAC-PROV.
III. AMEND ĐIỀU 35 — LUẬT QUẢN TRỊ DOT
Amend §4.1.1 — Thêm mapping cột PG (NT14)
Giữ nguyên 3 phần DOT description contract. Thêm mapping:
| Phần | Cột PG source (dot_tools) | Loại | Ví dụ |
|---|---|---|---|
| [MỤC ĐÍCH] | name |
DIRECT | "Builds context pack" |
| [TRIGGER→OUTPUT] | trigger_type + cron_schedule + operation |
DIRECT | "cron → CONTEXT_PACK_BUILD" |
| [PAIRED DOT] | paired_dot |
DIRECT | "DOT-CONTEXT-PACK-VERIFY" |
Template: [{tier}] [{domain}] {trigger_type} trigger. Operation: {operation}. Paired: {paired_dot}.
Viện dẫn: Template cơ chế → Đ3 §2.6. Runtime SSOT = dot_config.
IV. AMEND ĐIỀU 43 — LUẬT BẢN ĐỒ HỆ THỐNG
Amend §9.1 — Tách H11
| Code | Tên | Detect gì | Severity | Ý nghĩa |
|---|---|---|---|---|
| H11a | Description Basic Missing | description IS NULL OR btrim(description) = '' |
CRITICAL | Hạ tầng auto-gen hỏng |
| H11b | Description Detail Missing | governed + description NOT NULL + (label PROV-DOT HOẶC 0 provenance label) |
WARNING | Chưa được AI/người enrichment. ★ R2 Desktop P13: giai đoạn chuyển tiếp detect cả entity 0 label (legacy). Sau migration provenance (§VIII bước 7) → thu hẹp chỉ PROV-DOT. |
Amend §9.2.1 — Thu hẹp routing only (★ R1 GPT P7)
| Bảng PG | Entity type | SSOT quy cách | Min length |
|---|---|---|---|
dot_tools |
DOT | Đ35 §4.1.1 | 50 |
| (các bảng khác) | (theo bảng) | Đ3 §2.2 | 30 |
Routing only. SSOT quy cách → Đ3 §2.2/§2.6/Đ35 §4.1.1.
V. PHỤ LỤC ĐIỀU 3 — FILE MỚI
File: dieu3-phu-luc-description-templates.md | Tính chất: Documentation mirror (runtime SSOT = dot_config §2.6)
§A.1 — Template per entity type
| source_table | dot_config key | Template | Placeholders (D/C) | Output ví dụ |
|---|---|---|---|---|
dot_tools |
desc_template_dot_tools |
[{tier}] [{domain}] {trigger_type} trigger. Operation: {operation}. Paired: {paired_dot}. |
tier(D), domain(D), trigger_type(D), operation(D), paired_dot(D) | [B] [context.pack] cron trigger. Operation: CONTEXT_PACK_BUILD. Paired: DOT-CONTEXT-PACK-VERIFY. |
collection_registry |
desc_template_collection_registry |
[{governance_role}] Collection {code}. Loài: {species_code}. |
governance_role(D), code(D), species_code(C) | [governed] Collection COL-DOT-TOOLS. Loài: registry. |
dot_config |
desc_template_dot_config |
Config key điều khiển {key}. |
key(D) | Config key điều khiển hc_executor_max_runtime_seconds. |
entity_species |
desc_template_entity_species |
Loài [{code}] thuộc lớp {composition_level}. |
code(D), composition_level(D) | Loài [dot] thuộc lớp atom. |
dot_domains |
desc_template_dot_domains |
Domain [{code}] quản lý phạm vi {name}. |
code(D), name(D) | Domain [context.pack] quản lý phạm vi Context Pack. |
| (level) | desc_template_level_atom |
[{status}] Nguyên tử {code} trong {_source_table}. |
status(D), code(D), _source_table(C) | [active] Nguyên tử CP-005 trong checkpoint_types. |
| (level) | desc_template_level_molecule |
[{status}] Phân tử {code} trong {_source_table}. |
status(D), code(D), _source_table(C) | [active] Phân tử CPS-001 trong checkpoint_sets. |
| (level) | desc_template_level_compound |
[{status}] Hợp chất {code} trong {_source_table}. |
status(D), code(D), _source_table(C) | [active] Hợp chất WF-001 trong workflows. |
| (default) | desc_template_default |
[{status}] Entity {code} trong {_source_table}. |
status(D), code(D), _source_table(C) | [active] Entity M-001 trong modules. |
§A.2 — Quy tắc template
- Contract v1 (R1 P3): Key phẳng
[A-Za-z0-9_]+. Không nested. Thiếu/NULL →(chưa có). Nguyên văn, không eval. - Direct vs Computed (R1 P4):
(D)= từto_jsonb(NEW).(C)= từfn_description_context(). - Thêm template: INSERT
dot_configkey. 0 sửa code (NT4). - Fallback 4 tầng theo §2.6.
- Ngôn ngữ: tiếng Việt có dấu. Giữ code/enum tiếng Anh.
VI. VIỆN DẪN LIÊN LUẬT (Đ37 §4.14)
- SSOT chính: Đ3 (quy cách 2 mức + template)
- Phụ thuộc: Đ0-B, Đ29, Đ24
- Mượn SSOT từ: Đ43 §9.2.1 (mapping), Đ35 §4.1.1 (DOT), Đ22 §4.3 (HC infra)
| Luật | Vị trí | Viện dẫn |
|---|---|---|
| Đ3 §2.2 | Cuối bảng | "Chi tiết → §2.5. Cơ bản → §2.6. DOT → Đ35 §4.1.1." |
| Đ4 §2.1 | Trong trigger spec | "Template → Đ3 §2.6. Lookup 4 tầng. Provenance → Đ24. Context → Đ29/Đ0-B." |
| Đ35 §4.1.1 | Sau mapping | "Runtime SSOT = dot_config (Đ3 §2.6)." |
| Đ43 §9.1 | Trước H11a/H11b | "2 mức → Đ3 §2.5. Provenance → Đ24." |
| Đ43 §9.2.1 | Đầu bảng | "Routing only. SSOT → Đ3/Đ35." |
VII. TIÊU CHÍ ĐO
| # | Tiêu chí | Cách đo |
|---|---|---|
| 1 | Entity mới sinh → có description + PROV-DOT | H11a = 0 findings 3 ngày |
| 2 | Đổi template = UPDATE dot_config, 0 sửa code | INSERT entity → description theo template mới |
| 3 | H11a CRITICAL khi hạ tầng hỏng | Xóa template → H11a alert |
| 4 | H11b WARNING khi chưa enrichment | Đếm PROV-DOT governed entities |
| 5 | Thêm entity type = INSERT dot_config | 0 sửa code/trigger/luật |
| 6 | Lookup 4 tầng hoạt động | INSERT entity không có table-specific template → dùng level_default |
VIII. LỘ TRÌNH TRIỂN KHAI
| Bước | Việc | Effort | Note |
|---|---|---|---|
| 1 | Seed templates vào dot_config (~10 key) | Low | |
| 2 | CREATE fn_render_description_template() contract v1 | Medium | |
| 3 | CREATE fn_description_context() | Medium | ★ R2: không bao gồm source_database v1 |
| 4 | CREATE fn_auto_label_provenance() | Low | |
| 5 | ALTER fn_description_birth_guard() thêm auto-gen + lookup 4 tầng | Medium | REPLACE function, KHÔNG cần DROP/CREATE trigger lại (★ R2 Desktop P10) |
| 6 | CREATE trigger trg_desc_provenance_<table> AFTER INSERT cho mỗi bảng governed |
Medium | ★ R2 P9: companion trigger riêng cho PROV-DOT |
| 7 | Migration provenance legacy: entity có description non-empty + 0 provenance label → gán PROV-HUMAN | Low | ★ R2 Desktop P12 |
| 8 | Tách H11 → H11a + H11b + upload 2 SQL queries KB | Low | |
| 9 | Backfill entity cũ: NULL + rỗng + ngắn + gaming → auto-gen cơ bản | Medium | ★ R1 P8 mở rộng scope |
| 10 | AI enrichment chi tiết (batch, user điều hành) | High | Pha sau |
| 11 | Chuyển birth guard sang mode block |
Config flip | Sau stable |
★ R2 Desktop P10 — Deployment note trigger ordering: trg_desc_guard_<table> PHẢI chạy SAU trigger auto-gen code (trg_auto_id_<table>). PG fire triggers alphabetically cùng timing → naming convention đã đảm bảo (auto_id < desc_guard alphabetically). Verify sau deploy.
IX. BIÊN BẢN COUNCIL
Vòng 1:
- Gemini 9.5 MINOR (3 patches) + GPT 8.3 CHANGES (8 patches)
- Applied: 8/9. Rejected: GPT P6 (extra_metadata — deterministic + Directus revisions + scope creep)
Vòng 2:
- Gemini 10 APPROVE FINAL + GPT 9.0 APPROVE WITH MINOR (P9) + Desktop 8.5 CHANGES (P9-P13)
- Applied P9 (luật): Chốt dứt khoát BEFORE/AFTER 2 trigger — mã gen description ≠ mã gán provenance
- Applied source_database cleanup: Xóa khỏi fn_description_context contract v1
- Applied P10-P13 (deployment): Trigger ordering + legacy migration + H11b transitional logic → §VIII
- Tổng: 9 patches luật + 4 deployment notes. 0 blocker.
Reports:
- R1 Gemini:
council-review-round1-description-governance-fix27-gemini-2026-04-22.md - R1 GPT:
council-review-round1-description-governance-fix27-gpt-2026-04-22.md
★ R2 FINAL BAN HÀNH | S178 Fix 27 | 2026-04-22 | Council 2 vòng: Gemini 10+9.5 / GPT 9.0+8.3 / Desktop 8.5 | 9 patches + 4 deployment notes | 0 blocker