Incomex AI Portal
KB-69F9 rev 3

Phụ lục Điều 3 — Description Templates

7 min read Revision 3
lawappendixdieu3descriptiontemplate

PHỤ LỤC ĐIỀU 3 — DESCRIPTION TEMPLATES

Tính chất: Documentation mirror. Runtime SSOT = dot_config (Đ3 §2.6). Khi thay đổi: UPDATE dot_config TRƯỚC, cập nhật phụ lục SAU. Ngày tạo: 2026-04-22 S178 Fix 28 (Description Governance Package)

§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

  1. Contract v1 (Đ4 §2.1.1): Key phẳng [A-Za-z0-9_]+. Không nested. Thiếu/NULL → (chưa có). Nguyên văn, không eval.
  2. Direct vs Computed: (D) = từ to_jsonb(NEW). (C) = từ fn_description_context().
  3. Thêm template mới: INSERT dot_config key. 0 sửa code (NT4).
  4. Fallback 4 tầng theo Đ3 §2.6.
  5. Ngôn ngữ: tiếng Việt có dấu (Đ3 §2.1 C4). Giữ code/enum tiếng Anh.

§A.3 — Template mô tả chi tiết per entity type (mức 2 — AI enrichment)

Tính chất: Hướng dẫn cho AI agent viết mô tả chi tiết (PROV-AI). Đ3 §2.2 quy định NỘI DUNG, §A.3 quy định FORMAT. Quy tắc bắt buộc (Đ3 §2.5): Phải đọc mô tả cơ bản hiện tại + bao hàm/paraphrase thông tin cơ bản. Tiếng Việt có dấu (C4). Scope (Đ3 §2.5): §A.3 chỉ áp dụng cho thực thể kiến trúc. Bản ghi dữ liệu vận hành (ví dụ species system_issue) KHÔNG nằm trong scope enrichment — mô tả cơ bản (mức 1) đã đủ.

DOT (dot_tools) — Đ35 §4.1.1

Format: [Chức năng chính] thuộc [Luật]. [Cách hoạt động: đọc gì → xử lý gì → ghi gì]. [Trigger + tần suất]. Cặp: [paired_dot].

Context AI cần đọc: metadata row (tier, domain, trigger_type, operation, paired_dot) + source code (file_path) nếu có.

Ví dụ chuẩn:

Executor tổng hợp thuộc Đ22 (Tự chữa lành). Quét tất cả system_health_checks, dispatch theo executor_type (sql/function/builtin), log findings qua fn_log_issue. 5 guard security. Cron mỗi 3h. Cặp: dot-hc-executor-verify.

Collection (collection_registry) — Đ36

Format: [Vai trò governance]. Chứa [nội dung chính]. Lớp [Não/Kho/Cổng] (HP §B). Thuộc [Luật]. [Quan hệ FK chính nếu có].

Context AI cần đọc: governance_role, species, schema columns, FK constraints, database (directus=Kho, incomex_metadata=Não).

Ví dụ chuẩn:

Bảng đăng ký collection governed. Chứa metadata mỗi collection: governance_role, species_code, status. Lớp Kho. Thuộc Đ36 (Collection Protocol). FK tới entity_species, meta_catalog.

Config (dot_config)

Format: Tham số [chức năng]. Ảnh hưởng [hành vi]. Giá trị mặc định: [default]. Thuộc [Luật].

Context AI cần đọc: key name, current value, grep consumers trong code.

Ví dụ chuẩn:

Tham số thời gian tối đa executor chạy 1 cycle. Ảnh hưởng lockfile timeout dot-hc-executor. Giá trị mặc định: 600 giây. Thuộc Đ22 §4.3.

Species (entity_species) — Đ29

Format: Loài [đại diện nhóm gì]. Lớp [composition_level]. [Đặc điểm phân biệt]. [Quan hệ parent nếu có].

Context AI cần đọc: species metadata, composition_level, collection mapping.

Ví dụ chuẩn:

Loài đại diện DOT tools trong hệ thống. Lớp atom. Mỗi entity là 1 script thực thi, có trigger + paired DOT. Không có parent species.

Domain (dot_domains) — Đ35

Format: Domain quản lý phạm vi [chức năng]. [Số DOT thuộc domain]. [DOT chính tiêu biểu]. Thuộc [Luật].

Context AI cần đọc: domain rules, count DOTs per domain, representative DOTs.

Ví dụ chuẩn:

Domain quản lý phạm vi giám sát sức khỏe hệ thống. 7 DOT thuộc domain. Tiêu biểu: dot-hc-executor, dot-hc-executor-verify. Thuộc Đ22.

Governance (general — taxonomy, law_jurisdiction, label, v.v.)

Format: [Quy tắc/ràng buộc gì]. Áp dụng [đối tượng nào]. Thuộc [Luật]. [Enforcement mechanism nếu có].

Context AI cần đọc: entity metadata, related law, FK constraints.

Ví dụ chuẩn:

Quy tắc phân loại entity theo facet "Vai trò" (FAC-ROLE). Áp dụng mọi entity governed qua label_rules. Thuộc Đ24 (Luật Nhãn). Enforcement: PG trigger tự gán label khi INSERT.

Quy tắc chung

  1. Độ dài: 50–200 ký tự. Ngắn hơn = thiếu ngữ cảnh. Dài hơn = thừa.
  2. Jurisdiction bắt buộc mention: Ghi "Thuộc Đxx" để AI/người đọc biết ngay luật nào quản lý.
  3. Không lặp mô tả cơ bản nguyên văn: Paraphrase hoặc mở rộng, không copy-paste.
  4. Ngôn ngữ: Tiếng Việt có dấu. Giữ code/enum/tên DOT tiếng Anh.
  5. Provenance: Ghi đè description → UPDATE entity_labels: PROV-DOT → PROV-AI (Đ24 FAC-PROV).

CHANGELOG

Ngày Nội dung
S178 Fix 28 (2026-04-22) Tạo mới. 9 template (5 table-specific + 3 level-default + 1 default). Description Governance Package — Council 2 vòng.