KB-6116 rev 3

14 — Description Policy Endpoint and Execution Design Pack (rev 3)

8 min read Revision 3

iu-0description-policyexecution-designoption-1collection-registrypack-2b-preflightentity-enrichment-reconciliationrev3write-path-corrected

14 — Description Policy Endpoint and Execution Design Pack

Date: 2026-05-04 | Rev 3 Status: DESIGN — chưa execute, chưa DDL, chưa patch luật Input: Agent investigation PASS + Opus assessment + GPT review + Entity Enrichment Master reconciliation + Gemini write-path evidence Controlling: file 13 rev3 + agent report + du-thao-entity-enrichment-master-fix30.md Rev 2: +§2B Entity Enrichment Master reconciliation + 4-layer model + preflight queries Rev 3: +§2B.3A current deployed write path + wording fix + 4-layer model update

§1. Executive Summary

Agent investigation PASS: 11 câu hỏi read-only, 5-option comparison, HARD STOP đúng.
Preflight CONFIRMED: entity_enrichment table ABSENT (4/4 components absent).
Description Policy Tiering là blocker trước Pack 2B: IU data rows không có cột description physical.
Pack 2B vẫn đóng.
★ Rev 3: Sửa wording sai — hệ thống ĐÃ CÓ chỗ viết description (source entity columns, Gemini đã dùng). entity_enrichment chỉ là thiết kế nâng cấp tương lai.

§2. View-tier Source Check — RESOLVED

v_entity_full_classification.tier = dot_tools.tier (Đ35 DOT tier). Không liên quan description policy. CLOSED.

§2B. Description Write Paths + Entity Enrichment Master

§2B.1 Entity Enrichment Master — Thiết kế nâng cấp tương lai

Source: du-thao-entity-enrichment-master-fix30.md (DỰ THẢO v6, chờ Council vòng 5)

Thiết kế tạo bảng entity_enrichment làm master cho mô tả chi tiết, entity gốc = mirror, DOT sync. Gồm 5 functions, 3 HC checks (ENRICH-SEED/DRIFT/STALE), 2 DOTs (ENRICH-SYNC/VERIFY), 12 birth triggers, backfill 57K rows.

Trạng thái: DỰ THẢO v6, CHƯA DEPLOY. Preflight confirmed 4/4 components absent.

§2B.2 Preflight Result — entity_enrichment ABSENT

Component	Status
entity_enrichment table	ABSENT
HC-ENRICH checks	ABSENT
DOT-ENRICH tools	ABSENT
enrichment_pk_map config	ABSENT

§2B.3A Current Deployed Description Write Path — ĐÃ CÓ VÀ ĐANG DÙNG (★ Rev 3)

Hệ thống ĐÃ CÓ chỗ viết description. Cụ thể:

Thành phần	Chi tiết
Nơi viết	Cột `description` trực tiếp trên bảng gốc: `entity_species.description`, `tasks.description`, `dot_tools.description`, `collection_registry.description`, v.v.
Write path	Directus REST API — `PATCH /items/<collection>/<id>` với body `{"description": "..."}`
Ai đã viết	Gemini CLI — pilot entity_species (23), đợt 1 tasks (3) + dot_tools + agents, kế hoạch 4 đợt tổng 364 entity
Provenance	Sau khi viết: UPDATE entity_labels PROV-DOT → PROV-AI (Đ24 FAC-PROV)
Guide	`description-enrichment-guide.md` — agent đọc file → viết theo template → UPDATE qua Directus API
Tiến độ	Đang dần dần. H11b còn 2336 findings PROV-DOT (agent report Q5)
Auto-gen mức 1	fn_description_birth_guard (Đ4 §2.1.1) — PG trigger auto-gen description cơ bản khi INSERT, nhãn PROV-DOT

Câu đúng: entity_enrichment master chưa deploy, nhưng current source-entity description write path đã tồn tại và đã được dùng thực tế bởi Gemini.

Câu sai (đã sửa): ~~"Hệ thống chưa có chỗ viết description."~~

§2B.4 Phân biệt 4 lớp — UPDATED (★ Rev 3)

#	Lớp	Mô tả	Status
1	Current deployed write path	Cột `description` trên source entity + Directus REST API. Gemini/Agent đã viết trực tiếp. PROV-DOT (auto-gen) → PROV-AI (enrichment).	ĐÃ CÓ, ĐANG DÙNG
2	Entity Enrichment Master	Thiết kế nâng cấp: bảng `entity_enrichment` = master, entity gốc = mirror, DOT sync approved content.	DỰ THẢO v6, CHƯA DEPLOY
3	Description Policy	Chính sách routing/enforcement: entity loại nào cần enrichment (Tier A), loại nào miễn (Tier B).	ĐANG THIẾT KẾ (file 13+14)
4	IU structured-exempt	IU data rows dùng identity_profile JSONB, body, canonical_address thay description free-text.	Pilot (observed)

Quan hệ:

Description Policy (Lớp 3) — TEM ĐIỀU PHỐI
  ├─ Tier A (required_detailed)
  │    ├─ HIỆN TẠI: viết trực tiếp lên source entity (Lớp 1) qua Directus API
  │    └─ TƯƠNG LAI: viết qua entity_enrichment master (Lớp 2), DOT sync xuống entity
  ├─ Tier B (structured_exempt)
  │    └─ IU rows (Lớp 4) — dùng structured metadata, miễn description free-text
  └─ Tier C (unclassified) — phải classify trước

3 thứ KHÁC NHAU, BỔ SUNG NHAU:

Lớp 1 = bàn làm việc hiện tại — đã có, Gemini đã dùng.
Lớp 2 = phòng hồ sơ trung tâm dự kiến — bản vẽ, chưa xây.
Lớp 3 = quy định ai phải viết, ai được miễn — đang thiết kế.

§3. Option Disposition — Final

Giữ nguyên rev2. Option 2/4/5 REJECT. Option 1 + Option 3 = CANDIDATES.

§4. Recommended Endpoint (★ Rev 3 updated wording)

Option 1 — thêm field description_policy vào collection_registry.

collection_registry.description_policy chỉ là policy/routing endpoint:

Nó route cả current direct-source enrichment flow (Lớp 1) và future entity_enrichment flow (Lớp 2).
Nó không thay thế source description column (Lớp 1).
Nó không thay thế entity_enrichment master (Lớp 2).
Nó nói: "collection này thuộc Tier A (cần enrichment) hay Tier B (miễn) hay Tier C (chưa rõ)."

Lý do technical giữ nguyên: NT1 SSOT, NT13 PG First, fn đã đọc collection_registry (0 round-trip mới), H11 đã join.

§5-§6. Policy Values + Seed

Giữ nguyên rev2. 3 values (required_detailed / structured_exempt / unclassified). Tier A 17 bảng, Tier B 12 bảng, Tier C default.

§7. Law/Docs Amendment Plan (★ Rev 3 note)

Giữ nguyên rev2 + thêm:

description-enrichment-guide: ★ Guide hiện nói viết trực tiếp lên entity (đúng với current flow). Khi entity_enrichment deploy → guide update sang write-to-master. description_policy thêm bước "kiểm Tier trước khi enrichment batch" cho cả 2 flows.

§8. Runtime Execution Design

Giữ nguyên rev2 (Phase 0 preflight ĐÃ DONE — confirmed absent → Phase 1-5 bình thường).

§9. Preconditions / Hard Stops

Giữ nguyên rev2.

§10. Rà soát 2 vòng (★ Rev 3 thêm 1 điểm)

Vòng 1: Giữ nguyên. ✅ Vòng 2 điểm 1-7: Giữ nguyên.

★ Rev 3: Current write path có bị ảnh hưởng bởi description_policy? KHÔNG trực tiếp — Gemini/Agent viết qua Directus API, không bị fn_description_birth_guard gate (vì fn chỉ fire trên INSERT, không trên UPDATE description). description_policy ảnh hưởng H11a/H11b scan + fn birth gate (INSERT mới). Enrichment UPDATE hiện tại không bị block.

§11. Bài học phiên này (★ Rev 3 updated)

Lỗi 1 (rev1→rev2): Không rà Entity Enrichment Master trước khi thiết kế. Lỗi 2 (rev2→rev3): Nói "chưa có chỗ viết description" vì entity_enrichment chưa deploy — sai. Current write path (source entity + Directus API) đã tồn tại và Gemini đã dùng. Entity_enrichment chỉ là thiết kế nâng cấp.

Nguyên nhân gốc: Không search conversation history đủ sâu cho domain "description enrichment". Có tool search nhưng lười dùng → quyết định trên thông tin thiếu.

Sửa: Khi thiết kế component liên quan domain X → search KB + conversation_search + recent_chats cho MỌI artifact domain X. Không bỏ bước.

14 rev 3 | 2026-05-04 | Opus 4.6 | +§2B.3A current deployed write path + wording fix + 4-layer model update. Option 1 = policy routing, bổ sung (không thay thế) current write path và future enrichment master. Chờ GPT/User approve.