15 — Description Policy Option 1 Execution Pack (rev 2)
15 — Description Policy Option 1 Execution Pack
Date: 2026-05-04 | Rev 2 Status: EXECUTION DESIGN — chưa execute, chờ GPT/User approve Rev 1→2: GPT 7 blocker — legal gate, DDL exact, fn execution-safe, H11 exact, unclassified resolve, seed tighten, smoke tighten
§1. Inputs / Controlling Docs
(Giữ nguyên rev1 — 10 docs tham chiếu.)
§2. Final Scope
DO: Add description_policy column, seed, amend fn spec, amend H11 specs, draft law wording.
DO NOT: No Pack 2B, no IU rows, no entity_enrichment deploy, no law/docs patch (draft only).
§3. Legal / Tooling Gate (★ Rev 2)
3.1 Căn cứ pháp lý
| Luật | Cho phép gì | Ràng buộc |
|---|---|---|
| Đ20 (Design Before Execution) | Thiết kế trước, execute sau | File 13-14-15 = design đã qua review |
| Đ36 (Collection Protocol) | collection_registry = governed, schema changes phải qua quy trình | ALTER TABLE phải có design doc + review |
| Đ4 (Birth Process) | fn_description_birth_guard amend = thay đổi birth logic | Phải capture original + restore plan |
| Đ3 (Metadata) | description_policy = metadata mới cho collection governance | Phải align §2.5 Tier concept |
| Đ43 (System Context) | H11a/H11b = health check SQL amend | Phải verify executor_ref trỏ đúng |
| Đ33 (Gateway) | Directus = gateway chính thức cho DB directus | DDL trên DB directus → Directus phải nhận field |
3.2 DDL legal path
Hệ thống dùng migration SQL files deploy qua CI/CD (GitHub → SSH → VPS → docker exec postgres psql). Không có DOT riêng cho ALTER TABLE — DDL đi qua migration script.
Agent execution path:
- SSH vào VPS
docker exec postgres psql -U directus -d directuschạy ALTER- Verify PG + Directus
Nếu phát hiện có DOT/tool chuyên cho schema change (ví dụ dot-schema-migrate) → dùng tool đó thay raw psql. Nếu không rõ → STOP trước DDL, báo về.
3.3 Function amend legal path
CREATE OR REPLACE FUNCTION qua psql = legal path hiện tại cho PG function amend. Không có DOT riêng cho function edit.
3.4 H11 amend legal path
H11a/H11b = KB query SQL files. Amend = update_document trên Agent Data KB. Executor đọc file từ KB path — verify executor_ref khớp sau amend.
§4. DDL / Directus Phase — Exact (★ Rev 2)
4.1 Preflight
-- 4.1a: Verify column NOT YET exists
SELECT column_name FROM information_schema.columns
WHERE table_name = 'collection_registry' AND column_name = 'description_policy';
-- Expected: 0 rows. Nếu exists → STOP (§11 condition 1).
-- 4.1b: Capture Directus field state BEFORE
SELECT field, type FROM directus_fields
WHERE collection = 'collection_registry' AND field = 'description_policy';
-- Expected: 0 rows.
4.2 DDL
ALTER TABLE collection_registry
ADD COLUMN description_policy TEXT NOT NULL DEFAULT 'unclassified'
CHECK (description_policy IN ('required_detailed', 'structured_exempt', 'unclassified'));
4.3 Verify PG
SELECT column_name, data_type, column_default, is_nullable
FROM information_schema.columns
WHERE table_name = 'collection_registry' AND column_name = 'description_policy';
-- Expected: description_policy | text | 'unclassified'::text | NO
-- Nếu absent → STOP.
4.4 Verify Directus auto-detect
SELECT field, type FROM directus_fields
WHERE collection = 'collection_registry' AND field = 'description_policy';
- Nếu field present → OK, proceed.
- Nếu field absent → kiểm
dot-schema-feedback-ensurehoặc DOT tương đương. Nếu có → chạy DOT. Nếu không rõ → STOP. Ghi TD. KHÔNG manual INSERT vào directus_fields.
§5. Seed — Exact (★ Rev 2 tightened)
5.1 Preflight — verify Tier A collections exist
SELECT collection_name FROM collection_registry
WHERE collection_name IN (
'dot_tools','collection_registry','entity_species','dot_config',
'dot_domains','dot_operations','dot_coverage_required','dot_domain_rules',
'law_jurisdiction','binding_registry','universal_rule_registry','modules',
'meta_catalog','taxonomy','taxonomy_facets','context_trigger_sources','workflows'
);
Expected: 17 rows. Nếu < 17 → STOP. Ghi tên collection thiếu. Không seed partial.
5.2 Preflight — verify Tier B collections exist
SELECT collection_name FROM collection_registry
WHERE collection_name IN (
'information_unit','unit_version',
'tac_logical_unit','tac_unit_version','tac_publication','tac_publication_member',
'system_issues','system_health_checks','birth_registry','entity_labels',
'trigger_registry','admin_fallback_log'
);
Expected: ≤ 12 rows. TAC collections có thể chưa registered. Ghi rõ:
| Collection | Nếu absent |
|---|---|
information_unit |
PHẢI tồn tại (Pack 2A registered COL-176) |
unit_version |
PHẢI tồn tại (Pack 2A registered COL-177) |
tac_logical_unit |
Có thể absent — ghi SKIPPED |
tac_unit_version |
Có thể absent — ghi SKIPPED |
tac_publication |
Có thể absent — ghi SKIPPED |
tac_publication_member |
Có thể absent — ghi SKIPPED |
system_issues |
PHẢI tồn tại |
system_health_checks |
PHẢI tồn tại |
birth_registry |
PHẢI tồn tại |
entity_labels |
PHẢI tồn tại |
trigger_registry |
PHẢI tồn tại |
admin_fallback_log |
Có thể absent — ghi SKIPPED |
5.3 Seed SQL
-- TIER A (17 collections — phải đủ 17)
UPDATE collection_registry SET description_policy = 'required_detailed'
WHERE collection_name IN (
'dot_tools','collection_registry','entity_species','dot_config',
'dot_domains','dot_operations','dot_coverage_required','dot_domain_rules',
'law_jurisdiction','binding_registry','universal_rule_registry','modules',
'meta_catalog','taxonomy','taxonomy_facets','context_trigger_sources','workflows'
);
-- TIER B (chỉ UPDATE collections tồn tại — skip absent)
UPDATE collection_registry SET description_policy = 'structured_exempt'
WHERE collection_name IN (
'information_unit','unit_version',
'system_issues','system_health_checks','birth_registry','entity_labels','trigger_registry'
);
-- TAC + admin_fallback_log: UPDATE riêng nếu preflight confirm tồn tại
5.4 Verify Seed — exact counts
SELECT description_policy, count(*)
FROM collection_registry GROUP BY description_policy ORDER BY 1;
Ghi output exact. So sánh:
required_detailed= 17 (nếu preflight 17/17)structured_exempt= 7 + N (7 chắc chắn + N TAC/admin nếu tồn tại)unclassified= 166 - 17 - (7+N) = phần còn lại
§6. Function Amendment — Execution-safe (★ Rev 2)
6.1 Capture original
SELECT pg_get_functiondef('fn_description_birth_guard'::regproc);
Agent PHẢI paste full output vào report TRƯỚC KHI amend. Đây là restore source.
6.2 Verify source matches expected
Agent report Q6 đã capture function logic. Key checkpoints:
- Function đọc
governance_roletừcollection_registry✓ - Function dùng
(to_jsonb(NEW)->>'description')✓ - Function có mode warn/block từ dot_config ✓
Nếu source KHÁC expected (ví dụ ai đó đã sửa giữa investigation và execution) → STOP. Paste diff, báo về.
6.3 Exact replacement strategy
CREATE OR REPLACE toàn bộ function. Không patch partial. Agent output = full function body mới.
Diff summary (chỉ thay đổi, giữ nguyên phần còn lại):
-- THÊM variable declaration:
_desc_policy TEXT;
-- THAY query lấy governance_role:
-- CŨ:
SELECT governance_role INTO _gov_role
FROM collection_registry WHERE collection_name = TG_TABLE_NAME;
-- MỚI:
SELECT governance_role, description_policy
INTO _gov_role, _desc_policy
FROM collection_registry WHERE collection_name = TG_TABLE_NAME;
-- THÊM ngay sau query (TRƯỚC mọi enforcement logic):
-- Tier B: early return
IF _desc_policy = 'structured_exempt' THEN
RETURN NEW;
END IF;
-- Tier C: warn + continue (KHÔNG exempt)
IF _desc_policy = 'unclassified' THEN
RAISE WARNING 'Đ4 §2.1: Bảng % chưa classify description_policy. Cần classify.', TG_TABLE_NAME;
END IF;
-- GIỮA NGUYÊN: toàn bộ logic excluded/governed/observed/C1-C3 enforcement
6.4 Validation sau amend
-- Verify function replaced
SELECT pg_get_functiondef('fn_description_birth_guard'::regproc);
-- Phải chứa 'description_policy' và 'structured_exempt'
-- Verify 21 triggers vẫn active
SELECT count(*) FROM pg_trigger
WHERE tgfoid = 'fn_description_birth_guard'::regproc AND tgenabled = 'O';
-- Expected: 21 (CREATE OR REPLACE không drop triggers)
6.5 Restore plan
-- Nếu cần rollback: CREATE OR REPLACE với original source captured §6.1
CREATE OR REPLACE FUNCTION fn_description_birth_guard() RETURNS TRIGGER AS $$
... (paste original source từ §6.1 capture)
$$ LANGUAGE plpgsql;
§7. H11 Amendment — Exact (★ Rev 2)
7.1 H11a — Description Basic Missing
File path: knowledge/current-state/queries/h11a-description-basic-missing
Old SQL block (count query):
SELECT count(*) AS h11a_total
FROM v_entity_full_classification v
WHERE v.governance_role = 'governed'
AND (v.description IS NULL OR btrim(v.description) = '');
New SQL block:
SELECT count(*) AS h11a_total
FROM v_entity_full_classification v
JOIN collection_registry cr ON cr.collection_name = v.source_table
WHERE v.governance_role = 'governed'
AND cr.description_policy = 'required_detailed'
AND (v.description IS NULL OR btrim(v.description) = '');
Tương tự cho count-per-table và detail-list queries trong cùng file — thêm JOIN + WHERE filter.
7.2 H11b — Decision: Defer Option B
H11b giữ nguyên rev1. Lý do:
- h11b_exclude_species đã handle operational entities.
- description_policy filter cho H11b = nice-to-have, không blocking.
- Giảm scope execution pack — ít thay đổi = ít rủi ro.
Ghi TD: "H11b thêm description_policy filter — sau execution pack này."
7.3 Verify executor_ref khớp
SELECT code, executor_ref FROM system_health_checks WHERE code = 'H11a';
-- executor_ref phải = 'knowledge__current-state__queries__h11a-description-basic-missing.sql'
-- hoặc format tương đương. Nếu KHÁC → STOP.
7.4 Baseline before/after
-- BEFORE amend (capture TRƯỚC khi sửa H11a SQL):
SELECT count(*) AS h11a_before
FROM v_entity_full_classification v
WHERE v.governance_role = 'governed'
AND (v.description IS NULL OR btrim(v.description) = '');
-- AFTER amend (capture SAU khi sửa H11a SQL):
SELECT count(*) AS h11a_after
FROM v_entity_full_classification v
JOIN collection_registry cr ON cr.collection_name = v.source_table
WHERE v.governance_role = 'governed'
AND cr.description_policy = 'required_detailed'
AND (v.description IS NULL OR btrim(v.description) = '');
-- h11a_after ≤ h11a_before. Tier A findings giữ nguyên.
7.5 Restore plan
Nếu rollback: update_document KB file H11a về nội dung original (captured trước amend).
§8. Unclassified Behavior — Explicit (★ Rev 2)
| Surface | Behavior cho unclassified |
Lý do |
|---|---|---|
| fn_description_birth_guard | WARN "cần classify" + continue logic bình thường (warn/block theo governance_role) | Không silent exempt — entity unclassified vẫn bị gate nếu governed |
| H11a | SKIP — không flag CRITICAL | Transitional: chưa biết entity cần description không → flag CRITICAL = noise |
| H11b | Giữ nguyên (không filter description_policy) | Defer H11b amend |
★ Transitional behavior ghi rõ: H11a skip unclassified là tạm thời. Khi tất cả 166 collections được classify (Tier A hoặc B) → không còn unclassified → behavior tự resolve.
★ Visibility: Agent report phải ghi count unclassified sau seed. Nếu unclassified > 100 → note "classify dần, không blocking."
§9. Current Write Path + Entity Enrichment Compatibility
9.1 Current write path
Gemini/Agent UPDATE description trực tiếp qua Directus API → không bị ảnh hưởng. description_policy chỉ ảnh hưởng fn_description_birth_guard (INSERT trigger) + H11a scan. UPDATE qua API không fire birth guard.
KHÔNG claim entity_enrichment deployed.
9.2 Entity Enrichment Master
ABSENT. Không deploy trong pack này. Future entity_enrichment có thể consume description_policy. Tương thích.
§10. Smoke Tests — Exact (★ Rev 2)
10.1 Verifiable tests (không cần INSERT)
| # | Test | Query | Expected |
|---|---|---|---|
| 1 | DDL column visible | §4.3 query | 1 row, type text |
| 2 | Directus field visible | §4.4 query | 1 row (hoặc STOP) |
| 3 | Seed required_detailed count | §5.4 query | 17 |
| 4 | Seed structured_exempt count | §5.4 query | 7 + N TAC |
| 5 | Seed unclassified count | §5.4 query | 166 - 17 - (7+N) |
| 6 | H11a baseline before | §7.4 before query | Ghi count |
| 7 | H11a count after | §7.4 after query | ≤ before |
| 8 | fn contains 'structured_exempt' | §6.4 query | True |
| 9 | 21 triggers still active | §6.4 trigger count | 21 |
| 10 | No IU rows | SELECT count(*) FROM information_unit |
0 |
| 11 | No entity_enrichment | SELECT to_regclass('entity_enrichment') |
NULL |
10.2 INSERT smoke tests — DEFERRED
INSERT test vào Tier A/B/C tables cần exact table + safe row + transactional rollback. Defer sang controlled test pack riêng sau execution pack PASS.
Lý do: execution pack đã phức tạp (DDL + seed + fn + H11). Thêm INSERT tests = thêm risk. Verify đủ bằng §10.1 (column + seed + fn source + trigger count + H11 baseline).
§11. Rollback / Compensation
| Step | Action |
|---|---|
| 1 | Restore fn_description_birth_guard (§6.5 — CREATE OR REPLACE original) |
| 2 | Restore H11a KB query (§7.5 — update_document original) |
| 3 | DROP COLUMN: ALTER TABLE collection_registry DROP COLUMN description_policy; |
| 4 | Verify Directus auto-removes field: SELECT field FROM directus_fields WHERE collection='collection_registry' AND field='description_policy'; → 0 rows |
| 5 | Ghi rollback reason vào KB report |
§12. STOP Conditions
| # | Condition | Action |
|---|---|---|
| 1 | description_policy column đã tồn tại |
STOP — reconcile |
| 2 | Directus không detect field sau DDL + không rõ DOT | STOP — ghi TD |
| 3 | fn source khác expected (Q6 capture) | STOP — paste diff |
| 4 | H11a executor_ref khác KB query path | STOP — báo |
| 5 | Raw SQL khi có DOT/legal tool | STOP — dùng tool |
| 6 | IU rows count > 0 | STOP |
| 7 | Pack 2B activity | STOP |
| 8 | entity_enrichment table xuất hiện | STOP |
| 9 | Tier A preflight < 17 collections | STOP |
| 10 | Tier B PHẢI-tồn-tại collection absent | STOP (information_unit, unit_version, system_issues, system_health_checks, birth_registry, entity_labels, trigger_registry) |
§13. Law/Docs Wording Drafts (★ Rev 2 — tách rõ: draft only, không patch)
Execution prompt KHÔNG patch luật/docs. Drafts dưới đây chờ review riêng.
Đ3 §2.5 draft addition
Description Policy:
collection_registry.description_policyencode Tier A (required_detailed), Tier B (structured_exempt), Tier C (unclassified). Tier B chỉ miễn description free-text, không miễn structured metadata.
description-enrichment-guide draft addition
§1 bổ sung: Trước khi enrichment batch, kiểm
collection_registry.description_policy. Chỉ enrichment chorequired_detailed. Skipstructured_exempt.
§14. Decision Request
File 15 rev2 = bản thi công chi tiết. Chưa execute.
GPT/User: approve → Opus soạn agent prompt → GPT review prompt → dispatch.
15 rev 2 | 2026-05-04 | Opus 4.6 | +legal gate, DDL exact, fn execution-safe, H11 exact, unclassified explicit, seed tightened, smoke deferred INSERT, law/docs draft only. Chờ approve.