Incomex AI Portal
KB-3E5D

Điều 10-13: Luật Vận hành

5 min read Revision 1
lawdieu-10dieu-11dieu-12dieu-13injectidempotentlifecyclelive-catalog

ĐIỀU 10-13: LUẬT VẬN HÀNH & TỰ ĐỘNG HOÁ

Ghi chú v4.0: Constitution mục lục liệt kê 4 file riêng (law-10, 11, 12, 13). File này gộp tạm — sẽ tách khi hội đồng duyệt.

ĐIỀU 10: LUẬT INJECT — RULES PHẢI ĐẾN ĐÚNG NƠI AGENT ĐỌC

Rules chỉ có giá trị nếu agent BUỘC PHẢI đọc. Rules trong Agent Data mà agent phải search → quên → vi phạm. Giống biển báo không có camera.

Cơ chế:

  1. CLAUDE.md + AGENTS.md chứa BẢN RÚT GỌN Hiến pháp — checklist. Agent đọc TỰ ĐỘNG khi khởi động.
  2. .claude/skills/incomex-rules.md cập nhật mỗi khi Hiến pháp thay đổi.
  3. DOT scripts TỰ KIỂM TRA tuân thủ — không phụ thuộc agent "nhớ".

Agent vi phạm rule mà rule KHÔNG trong CLAUDE.md → lỗi thuộc HỆ THỐNG (chưa inject).

ĐIỀU 11: LUẬT IDEMPOTENT — SCRIPT PHẢI CHẠY LẠI ĐƯỢC

Mọi DOT script PHẢI idempotent — chạy lại không tạo duplicate, tự bỏ qua bước đã xong.

Verify step bắt buộc: Mỗi DOT sinh entity PHẢI có bước VERIFY CUỐI: kiểm tra TẤT CẢ outputs tồn tại. Thiếu → tự fix hoặc báo lỗi cụ thể.

Script lỗi giữa chừng + không verify = bất đồng bộ ẩn tích lũy — bug nguy hiểm nhất.

ĐIỀU 12: LUẬT VÒNG ĐỜI ĐẦY ĐỦ — SINH + SỬA + XOÁ

Entity Lifecycle phải cover TOÀN BỘ:

  • SINH: Qua DOT → ID → registry → metadata (Điều 4)
  • SỬA: Sửa → cập nhật TẤT CẢ registries + dependencies tự động
  • XOÁ: Query dependencies → có nơi dùng → CHẶN → deprecate trước → 0 dependencies → retire
  • GỘP: Entity mới → migrate data → update deps → deprecate cũ

Chỉ biết tạo mà không biết dọn = phình to mãi mãi.

→ Chi tiết: knowledge/dev/architecture/entity-lifecycle.md

ĐIỀU 13: LUẬT DANH MỤC SỐNG — TẠO = TỰ XUẤT HIỆN, XOÁ = TỰ BIẾN MẤT

"Điểm gãy của điểm gãy." Điều 2 nói "mọi thứ trong registry" — nhưng NẾU đăng ký registry phải NHỚ → quên → lệch → Registry-First = vô nghĩa.

§1. Nguyên tắc LIVE CATALOG

TẠO → danh sách TỰ ĐỘNG hiện
XOÁ → danh sách TỰ ĐỘNG ẩn
SỬA → danh sách TỰ ĐỘNG cập nhật

Phải "nhớ cập nhật danh sách" = THIẾT KẾ SAI.

§2. Hai mô hình

Mô hình A (ưu tiên): Registry IS source. Tạo TRONG registry → hệ thống đọc → UI hiện. Mô hình B: Source tách rời → auto-sync. DOT tools (file) → script scan → registry cập nhật.

v4.0 bổ sung: Mô hình A/B đều phải đảm bảo 5 tầng đồng bộ (Điều 0-H). DOT = cổng duy nhất cho cả 2 mô hình. Tạo entity qua DOT → PG + Directus + Nuxt + Agent Data + Qdrant đều tự biết.

§3. Quy tắc chọn mô hình

Thực thể Source thực tế Mô hình Giải pháp
Bảng UI table_registry (Directus) A — registry IS source ✅ Đã đúng
Modules modules (Directus) A — registry IS source ✅ Đã đúng
Workflows workflows (Directus) A — registry IS source ✅ Đã đúng
DOT tools Files trong dot/bin/ B — auto-sync dot-catalog-sync
Pages/Routes Files trong web/pages/ B — auto-sync Cần scan script
API endpoints Files trong web/server/api/ B — auto-sync Cần scan script
Components Files trong web/components/ B — auto-sync Cần scan script
Collections Directus system A — Directus IS source Query trực tiếp
Fields Directus system A — Directus IS source Query trực tiếp
Agent Data docs Agent Data API A — API IS source list_documents

Nguyên tắc: Mô hình A > Mô hình B. Nếu có thể di chuyển source vào Directus → chuyển sang Mô hình A.

§4. Meta-catalog = Catalog of Catalogs

meta_catalog (Directus collection):

Field Mục đích
registry_name Tên registry (vd: "table_registry")
entity_type Loại thực thể (vd: "Bảng UI")
source_model Enum: A hoặc B
source_location Nơi source thực tế
sync_script Tên DOT script sync (null nếu Mô hình A)
record_count Số records hiện tại — auto-query
species_count Số species liên quan
orphan_count Số orphans phát hiện
ui_page URL trang UI hiển thị
status active/planned/deprecated

AI hỏi "hệ thống có gì?" → query meta_catalog → trả lời CHÍNH XÁC.

§5. Danh sách phải đọc được bởi CẢ AI VÀ Con người

Mỗi danh mục (catalog) phải có 2 giao diện:

  1. AI đọc: Query Directus API hoặc Agent Data search → JSON/structured data
  2. Con người đọc: UI page trên Nuxt (dùng DirectusTable) hiển thị + filter/search

Con người xác nhận đúng trên UI → chắc chắn đúng cho AI. Một nguồn sự thật, hai cách truy cập.

§6. Auto-sync Mô hình B — BẮT BUỘC

PHẢI có: (1) Script scan (DOT tool) (2) Cron trigger (3) Event trigger sau deploy. Thiếu 1 → registry CHẮC CHẮN lệch.