KB-6693
dot-iu-cutter v0.5 Information Unit Fabric Addendum — Agent Prompt
23 min read Revision 1
dot-iu-cutterv0.5fabric-addendumagent-promptdesign-onlyws-1dieu44dieu382026-05-18
v0.5 Information Unit Fabric Addendum — Existing Design Map + WS-1 Design Brief
Phase: design-only
Date: 2026-05-18
Authority: User + GPT position + Opus review + GPT/Opus consensus
Agent mode: design-only, read-only grounding
0. Mục tiêu
Rà soát thiết kế dot-iu-cutter hiện tại, xác định phần thiếu thật so với mục tiêu dài hạn Information Unit Fabric, chốt đầu bài bổ sung theo 4 workstream, và soạn design brief chi tiết cho WS-1:
Relation Edge + Topic Graph + Assembly Contract.
Hệ thống sẽ quản lý số lượng lớn miếng thông tin, từ văn bản nội bộ Incomex, Hiến pháp/Luật nội bộ, quy trình, code, báo cáo, bài học, ghi chú kiến trúc, đến luật/chính sách của Chính phủ Việt Nam. Thiết kế phải hướng tới khả năng linh hoạt, không hardcode, có thể tự động thực sự, và không gãy khi scale lên hàng trăm nghìn đến hàng triệu IU.
Mục tiêu phase này KHÔNG phải triển khai. Mục tiêu là thống nhất đầu bài bổ sung và tạo brief đủ rõ để Agent/nhóm tiếp theo thiết kế sâu hoặc triển khai từng phần.
0.1. Design stance
Bắt buộc tuân thủ các nguyên tắc sau:
design_stance:
- Do not build a new mega-architecture.
- Reuse existing approved designs as authority.
- Design only the confirmed gaps G1..G5.
- Separate logical design from physical execution.
- Do not convert application-level features into core IU Fabric unless they are generalizable.
- SQL remains SSOT; Directus is assembly/UI layer; vector/NoSQL is projection only.
- PG First.
- Assembly First.
- No hardcoded labels, metadata keys, grammar profiles, topic types, source families, DSN, IP, container, collection, or vector store.
1. ĐỌC TRƯỚC — bắt buộc đọc hết trước khi viết
Agent PHẢI đọc và ghi nhận nội dung 10 tài liệu dưới đây trước khi viết bất kỳ dòng thiết kế nào. Đây là nền thiết kế lớn đã được duyệt. Nếu không đọc trước, Agent sẽ viết lại những phần đã có.
mandatory_read:
R1_relation_edge:
path: knowledge/dev/laws/dieu44-trien-khai/design/05-relation-edge-conformance-design.md
alias: P44-4A
contains: 8 core edge types, 3 candidate, INV-DUAL-1..4 anti-drift, reverse-index P1/P2/P3, auto-fix vs escalate, role/procedure separation
R2_topic_view:
path: knowledge/dev/laws/dieu38-trien-khai/closure/p11d-logical-topic-view-proof-design.md
alias: P11D
contains: topic field model, 5 query types Q-T1..Q-T5, assembly pipeline 5 steps, provenance, anti-patterns, edge cases, OPEN items P11D-alpha..zeta
R3_relation_closure:
path: knowledge/dev/laws/dieu38-trien-khai/closure/p11c-closure-note-2026-05-02.md
alias: P11C
contains: universal_edges là SSOT, Cap-4/Cap-5 contracts, execution defer P44-6
R4_iu_profile:
path: knowledge/dev/laws/dieu44-trien-khai/design/04-information-unit-profile-schema.md
alias: P38-XC
contains: universal substrate + UMC + DOT contract, capability matrix Cap-1..5, JSONB profile sketches
R5_master_plan:
path: knowledge/dev/laws/dieu44-trien-khai/v0.5-constitution-hardtest-design/dot-iu-cutter-v0.5-constitution-hardtest-master-plan-2026-05-17.md
alias: v0.5 Master Plan
contains: end-to-end factory pipeline S0..S7, architecture principles P1..P10, master sequencing Q0..Q9, open decisions OD-G1/G2/A1/S1/V1/M1/L1..L5/P1/R1/I1
R6_label_metadata:
path: knowledge/dev/laws/dieu44-trien-khai/v0.5-constitution-hardtest-design/dot-iu-cutter-v0.5-information-unit-label-metadata-registry-master-design-2026-05-17.md
alias: v0.5 Label/Metadata
contains: label registry concept, metadata-key registry, hot-key promotion policy, JSONB→normalize rule
R7_sql_nosql_hybrid:
path: knowledge/dev/laws/dieu44-trien-khai/v0.4-schema-binding/dot-iu-cutter-v0.4-sql-nosql-hybrid-information-unit-strategy-2026-05-17.md
alias: v0.4 Hybrid
contains: SQL SSOT, field classification taxonomy, JSONB normalize queue, automation invariants
R8_edit_merge:
path: knowledge/dev/laws/dieu44-trien-khai/design/23-p1-iu-text-as-code-edit-merge-design.md
alias: 23-P1
contains: Git-like workflow cho IU, proposal/review/merge model, multi-agent editorial pipeline
R9_split_merge_gap:
path: knowledge/dev/laws/dieu44-trien-khai/backlog/td-p1-split-merge-metadata-propagation-gap-2026-05-15.md
alias: TD-P1
contains: gap xác nhận — pipeline hiện chỉ có cắt lần đầu, chưa split/merge/metadata propagation
R10_gpt_position:
path: knowledge/dev/laws/dieu44-trien-khai/reviews/dot-iu-cutter-v0.5-fabric-addendum-topic-formation-gpt-position-2026-05-18.md
alias: GPT Position
contains: 4 workstream chấp thuận, deferred items, forbidden actions, recommended capabilities
Ngoài ra nên scan, không bắt buộc đọc full nhưng cần kiểm tra nếu có liên quan:
optional_scan:
- knowledge/dev/laws/dieu44-trien-khai/v0.4-schema-binding/dot-iu-cutter-v0.4-scale-automation-nonhardcode-review-2026-05-17.md
- knowledge/dev/laws/dieu44-trien-khai/v0.5-constitution-hardtest-design/dot-iu-cutter-v0.5-source-document-ingestion-pipeline-design-2026-05-17.md
- knowledge/dev/laws/dieu44-trien-khai/v0.5-constitution-hardtest-design/dot-iu-cutter-v0.5-canonicalization-and-address-grammar-design-2026-05-17.md
- knowledge/dev/laws/dieu38-trien-khai/closure/p11e-checker-proof-design.md
- knowledge/dev/laws/dieu38-trien-khai/LSL-01-information-unit-first.md
2. KHÔNG THIẾT KẾ LẠI — reference only
Các hạng mục dưới đây đã có thiết kế hoặc nguyên tắc đã chốt. Agent chỉ reference, KHÔNG redesign. Nếu cần bổ sung nhỏ thì ghi rõ “bổ sung so với [tài liệu X]”, không viết lại từ đầu.
do_not_redesign:
IU_to_IU_relation_edges:
source: P44-4A
status: design CLOSED, execution defer P44-6
what_exists: 8 core edge types references, depends_on, uses, implements, supersedes, contradicts, compatible_with, contains; 3 candidate derived_from, governed_by, published_in; INV-DUAL-1..4 anti-drift; reverse-index P1/P2/P3 framework
agent_action: reference only. Nếu WS-1 cần edge type mới cho IU↔non-IU thì ghi rõ bổ sung so với P44-4A.
topic_field_model:
source: P11D §3
status: logical design CLOSED, runtime defer Pilot Tier 1
what_exists: topic_code, topic_name, topic_namespace, topic_status, topic_confidence, topic_provenance; manual + section_derived; free-text topic_code + provenance bắt buộc; topic vocab table defer P44-6
agent_action: reference only. Nếu WS-1 muốn tạo minimal topic table sớm hơn thì ghi rõ đây là quyết định mới thay đổi P11D defer và justify.
topic_query_catalog:
source: P11D §5
status: logical proof CLOSED
what_exists: Q-T1 topic→units, Q-T2 group by publication, Q-T3 related via edges, Q-T4 quality flags, Q-T5 provenance trace; assembly pipeline 5 steps GATHER→ENRICH→GROUP→QUALITY→PROVENANCE
agent_action: reference only. Nếu WS-1 assembly contract cần abstract hóa thì build on top of Q-T pipeline, không thay thế.
label_metadata_registry_concept:
source: v0.5 Label/Metadata Master Design
status: concept CLOSED, table creation defer
what_exists: label_registry + metadata_key_registry concept, hot-key promotion policy, JSONB→normalize rule
agent_action: reference for WS-2. Không redesign concept.
sql_nosql_hybrid_strategy:
source: v0.4 Hybrid Strategy
status: CLOSED
what_exists: SQL là SSOT cho identity/lifecycle/governance/audit/idempotency; JSONB cho sparse evolving data; vector = rebuildable projection; non-hardcode audit PASS
agent_action: reference only. Mọi thiết kế mới phải tuân thủ.
edit_merge_model:
source: 23-P1 rev2
status: design note, chờ review/integration
what_exists: Git-like workflow, branch = edit_draft, commit = apply, merge = editorial approval; multi-agent proposal/review/merge
agent_action: reference for WS-4. Không redesign model, chỉ bổ sung integration với cutter lifecycle nếu cần.
3. THIẾT KẾ MỚI — trọng tâm thật của phase này
Dưới đây là 5 gap thật sự. Agent tập trung vào đây.
G1. Assembly Contract
G1_assembly_contract:
what: >
Abstract contract cho "assembly" — interface chung cho mọi loại assembly:
by original document, by topic, by compliance requirement, by entity/contract,
by code area, by process, by report, by lesson.
why: >
P10D đã chứng minh assembly by document.
P11D đã chứng minh assembly by topic.
Nhưng mỗi loại hiện là ad-hoc pipeline riêng, chưa có abstract layer chung.
Khi có nhiều loại assembly, không thể viết pipeline riêng hardcode cho từng loại.
reference_existing:
- P10D Nuxt Laws Page: assembly by document đã chạy
- P11D §6: assembly by topic logical pipeline
design_requirements:
- abstract contract: assembly_profile
- fields logical: profile_id, profile_type, input_selector, ordering_rule, inclusion_rule, exclusion_rule, relation_filter, source_family_filter, render_template, output_format, provenance_policy
- cách đăng ký assembly profile mới mà không hardcode
- cách assembly profile reference relation edges, topic, source profile, metadata key registry
- ít nhất 3 concrete profile sketches:
1: original_document
2: topic_thread
3: compliance_matrix
- giải thích nôm na bằng ví dụ đời thường
G2. IU ↔ non-IU Entity Binding
G2_iu_to_non_iu_entity_binding:
what: >
Cơ chế để IU trỏ/bind tới non-IU authority objects:
SQL entity, Directus item, code module, Git commit/file, report, process step,
contract, customer, order, invoice...
Binding không được copy toàn bộ data vào IU.
why: >
P44-4A universal_edges chủ yếu cho IU↔IU.
User yêu cầu nối miếng thông tin với SQL data.
Ví dụ: hợp đồng có khách hàng, địa chỉ, giá trị, điều khoản, trạng thái vòng đời nằm trong SQL.
IU cần biết trỏ tới đúng data authority thay vì copy text tĩnh.
options_to_evaluate:
A: extend universal_edges to support non-IU targets
B: create separate typed iu_entity_binding with minimal entity_reference_registry
C: store JSONB pointer in content_profile
D: hybrid — universal_edges remains IU↔IU; typed binding handles IU↔entity; assembly contract can consume both
constraints:
- SQL/entity source remains authority
- IU stores semantic reference and provenance, not duplicated full data
- binding must be auditable: who/when/why/source
- binding must support permission boundaries conceptually
- binding must support snapshot policy conceptually for rendered documents
- scale target: millions of bindings
- no full contract lifecycle design in this phase
- no executable SQL
minimal_viable_registry_warning: >
Đừng over-design entity_reference_registry ở phase này.
Hãy đánh giá minimal viable registry trước, ví dụ 4–5 field core.
Permission policy / snapshot policy có thể là logical placeholder hoặc deferred field nếu chưa có pilot thật.
output:
- option analysis
- recommendation
- trade-off matrix
- logical pseudo-schema only
- example: contract clause binds to customer_id and contract_id
- example: architecture IU binds to GitHub file or code module
G3. Topic Registry Decision
G3_topic_registry_decision:
what: >
Quyết định: tạo minimal topic_vocab table sớm, giữ free-text JSONB như P11D,
hay chốt logical topic registry contract trước và defer physical table creation.
why: >
P11D defer topic vocab table sang P44-6.
Nhưng nếu WS-1 cần pilot topic assembly thật thì free-text topic_code có rủi ro duplicate.
Cần phân biệt rõ logical registry approval khác với physical table creation.
options:
A: physical minimal topic_vocab table soon
B: continue JSONB free-text topic_code with duplicate mitigation
C: approve logical topic registry contract now, defer physical table creation
must_distinguish:
- logical registry contract
- physical table creation
- seed governance
- duplicate mitigation
- topic ownership
design_requirements:
- pro/con của từng option
- recommendation rõ ràng
- nếu chọn C, ghi rõ khi nào mới chuyển sang physical table
- không được tự mở schema migration
G4. Cross-source-family Assembly
G4_cross_source_family_assembly:
what: >
Thiết kế assembly xuyên source families:
Hiến pháp nội bộ → Luật nội bộ → Luật nhà nước → Quy trình → SQL data →
Code → Báo cáo → Bài học → Ghi chú kiến trúc.
why: >
P11D proof topic view mới chạy trên 3 publications cùng một source family.
User yêu cầu chiều thứ 2 đầy đủ: xâu chủ đề xuyên nhiều loại nguồn khác nhau.
must_include:
- source_family taxonomy:
internal_incomex_constitution
internal_incomex_law
internal_process
external_government_law
sql_entity
code_artifact
report
lesson
architecture_note
- authority semantics:
normative_authority: thứ có quyền quy định
evidence_authority: thứ chứng minh đã làm/chưa làm
implementation_authority: thứ đang chạy/thực thi thật
- ordering rule per assembly context:
compliance_external_law
internal_architecture
implementation_trace
contract_lifecycle
- relation types dùng để nối cross-family:
implements
constrains
governed_by
maps_to_requirement
maps_to_process
maps_to_code
evidenced_by
lesson_from
- example cụ thể:
topic = "cấu trúc collection"
chain = Hiến pháp nội bộ → Luật nội bộ → Quy trình → Directus/PG schema → Code → Report → Lesson
design_requirements:
- không xếp ngang hàng luật, report và code nếu authority khác nhau
- phân biệt rule nói gì, report chứng minh gì, code đang chạy gì
- assembly profile cho cross-family topic thread
G5. Directus Boundary Formal
G5_directus_boundary_formal:
what: >
Formal boundary document: Directus làm gì / không làm gì trong IU Fabric.
why: >
Nguyên tắc đã chốt: Directus = UI/form/template assembly/exposure;
SQL/IU Fabric = semantic authority/provenance/lifecycle.
Nhưng cần formal hóa để các session sau không vi phạm.
must_include:
Directus_responsibilities:
- UI/form
- inspection
- template assembly khi phù hợp
- preview
- read/write UI vào các collection được phép nếu đã có DOT/change package
IU_Fabric_responsibilities:
- semantic authority
- provenance
- IU lifecycle
- compliance mapping
- relation graph
- source/version/checksum
- assembly contract
- audit/governance
Directus_template_feature:
- có thể dùng cho hợp đồng/document rendering nếu đọc authoritative SQL/IU data
- không được biến Directus thành authority của hợp đồng hoặc IU
forbidden_for_Directus:
- không own IU lifecycle
- không own compliance mapping
- không own provenance/audit
- không bypass PG/governance
- không manual UI config nếu đã yêu cầu DOT-driven
governance:
- Directus config changes remain DOT/change-package governed
- Directus reads PG/Directus collections; PG remains source of truth
4. 4 Workstream bổ sung
WS-1 — Relation Edge + Topic Graph + Assembly Contract
WS_1:
priority: highest
scope: G1 + G2 + G3 + G4 + G5
note:
- IU↔IU relation đã có ở P44-4A, không redesign
- topic field model đã có ở P11D, không redesign
- WS-1 bổ sung gap thật: assembly contract, IU↔entity binding, topic registry decision, cross-source assembly, Directus boundary
WS-2 — Metadata Key Registry + Source Profile
WS_2:
scope:
- concrete hóa metadata_key_registry dựa trên v0.5 concept
- source profile cho internal_incomex_governance + external_government_law
- grammar profile per source family
note:
- không redesign label/metadata concept
- không tạo schema
WS-3 — Assembly by Topic
WS_3:
scope:
- dùng G1 Assembly Contract + P11D pipeline
- proof assembly by topic cho cross-source family
- logical SQL view/function prototype only
- ít nhất 2 assembly profile concrete: topic_thread + compliance_matrix
WS-4 — Edit / Amend / Supersede Pipeline
WS_4:
scope_now:
- identify interface requirements and dependencies only
- ensure WS-1 design does not block future amend/split/merge/supersede flows
defer_detailed_design:
- AMEND
- SUPERSEDE
- SPLIT
- MERGE
- RETIRE
- integration with MARK→SWEEP→REVIEW→CUT→VERIFY
- forward-compensation details
reference:
- 23-P1 edit/merge
- TD-P1 split/merge gap
5. Output
Tất cả output vào folder:
knowledge/dev/laws/dieu44-trien-khai/v0.5-fabric-addendum-scope/
Tạo 4 files:
files:
1_scope:
name: dot-iu-cutter-v0.5-fabric-addendum-existing-design-map-and-workstreams-2026-05-18.md
content:
- bản đồ thiết kế đã có
- tóm tắt 10 tài liệu mandatory_read, khoảng 300–500 chars mỗi tài liệu
- phần thiếu thật G1..G5 với justify
- 4 workstream definition WS-1..WS-4 với scope, dependencies, priority
- downstream sequence sau WS-1
- principles binding: SQL SSOT, PG First, Assembly First, no hardcode, Directus boundary
2_ws1_brief:
name: dot-iu-cutter-v0.5-WS1-relation-topic-assembly-design-brief-2026-05-18.md
content:
- G1 Assembly Contract design chi tiết
- G2 IU↔non-IU entity binding option analysis + recommendation
- G3 Topic registry decision
- G4 Cross-source-family assembly design
- G5 Directus boundary formal
- mỗi gap: problem, existing reference, options, recommendation, pseudo-schema/logical pattern, trade-offs, risks
- reference rõ tới P44-4A/P11D/v0.5 cho phần đã có
- ít nhất 3 ví dụ nôm na đời thường
3_open_decisions:
name: dot-iu-cutter-v0.5-fabric-addendum-open-decisions-2026-05-18.md
content:
- consolidated open decisions
- kế thừa OD từ v0.5 master plan + P11D + gap mới
- mỗi OD gồm: mô tả, options, impact nếu defer, recommendation
- phân loại:
resolve_in_WS1
defer_WS2
defer_WS3
defer_WS4
defer_post_pilot
4_report:
name: dot-iu-cutter-v0.5-fabric-addendum-report-2026-05-18.md
content:
- executive summary
- what was read
- what was found
- overlaps avoided
- gaps confirmed
- what was designed
- risks
- next steps
- forbidden respected
- git status
Tags cho tất cả files:
tags:
- dot-iu-cutter
- v0.5
- fabric-addendum
- design-only
- ws-1
- dieu44
- dieu38
- 2026-05-18
6. Ràng buộc tuyệt đối — Forbidden
forbidden:
- schema migration
- production write
- code change
- index DDL execution
- CUT
- VERIFY
- Constitution dry-run
- any dry-run
- bulk cut
- Directus mutation
- vector/NoSQL integration
- vector/NoSQL write
- contract template implementation
- create new PG table
- ALTER TABLE
- CREATE INDEX
- deploy
- restart service
- git commit
- redesign những gì đã chốt trong §2
7. Quality Gates
Trước khi upload mỗi file, Agent tự kiểm:
quality_gates:
QG1:
question: File này có redesign nội dung đã có trong §2 không?
required_action: Nếu có, cắt bỏ phần redesign, thay bằng reference rõ path + section.
QG2:
question: File này có vi phạm forbidden list §6 không?
required_action: Nếu có, dừng và báo cáo.
QG3:
question: Mỗi gap mới G1..G5 có ít nhất 1 ví dụ nôm na đời thường không?
required_action: Nếu không, thêm ví dụ.
QG4:
question: Schema sketch có phải executable migration SQL không?
required_action: Nếu có, đổi thành pseudo-schema hoặc YAML field list.
allowed:
- logical pattern
- pseudo-schema
- YAML field list
forbidden:
- CREATE TABLE executable SQL
- ALTER TABLE executable SQL
- CREATE INDEX executable SQL
- production-ready migration statement
QG5:
question: Assembly contract có abstract đủ để cover ít nhất 3 loại assembly khác nhau không?
required_action: Nếu không, thiết kế lại.
QG6:
question: IU↔entity binding có đánh giá đủ options A/B/C/D + trade-off không?
required_action: Nếu không, bổ sung.
QG7:
preferred_file_size: <= 15K chars
hard_file_size: <= 25K chars
required_action: Nếu vượt hard limit, tách section hoặc tóm gọn, nhưng không bỏ phân tích bắt buộc.
QG8:
question: G2 entity registry có bị over-design không?
required_action: Nếu có quá nhiều field chưa có pilot, tách thành core minimal + deferred fields.
8. Ghi chú cho Agent
- Giải thích bằng ngôn ngữ nôm na, dễ hiểu.
- Dùng ví dụ đời thường khi giải thích: nhà hàng, sổ tay, kho hàng, hợp đồng, thẻ khách hàng.
- Khi reference tài liệu cũ, ghi rõ path + section + câu chốt cụ thể. Không nói chung chung “đã thiết kế trước đó”.
- SQL là SSOT.
- PG First.
- Assembly First.
- Directus là UI/form/template assembly/exposure layer, không phải semantic authority.
- Vector/NoSQL là projection rebuild được, không phải authority.
- JSONB không được biến thành hidden authority.
- Nếu gặp conflict giữa thiết kế cũ và yêu cầu mới, flag rõ trong open decisions, không tự quyết.
- Mỗi output file phải tự đứng được, reader không bắt buộc đọc file khác mới hiểu.
- Không over-design. Đủ để mở WS-1 đúng hướng, không biến phase này thành thiết kế lại toàn bộ hệ thống.
- Agent self-advance bị cấm. Sau khi upload 4 files, dừng và route về GPT/User review.
9. Git / repo status
Không có code change expected.
Báo cáo trong file report:
git:
instruction: >
If Agent has read-only SSH access to VPS, report git status.
If not, state "no VPS access in this session" and skip.
Do NOT attempt write operations.
repo_ssot: /opt/incomex/dot
branch: current branch if accessible
HEAD: current HEAD if accessible
git_status_short_iu_cutter: output of git status --short -- iu-cutter if accessible
code_changed: false
commit_made: false
Không commit. Không write operation.