Kiến trúc Rule Layers & Trigger Index (v1.5.3)

Rules là các tệp .md điều khiển hành vi của AI Agent — ranh giới, ưu tiên, và kỷ luật. Khác với Workflows (các bước thực thi), Rules định nghĩa ràng buộc mà agent phải tuân theo.

Ba thuộc tính then chốt giúp hệ thống hiệu quả:

Phân tầng — Kernel → Workspace → Project
Tiết lộ Lũy tiến — chỉ tải khi cần, không bao giờ tải hết cùng lúc
Trigger Index — bảng nhẹ ánh xạ hành động → tệp rule

🏗️ Ba Tầng Rule

┌──────────────────────────────────────────────────────┐
│ Tầng 1: KERNEL (Bất biến)                            │
│ Resources/ai-agents/kernel/invariants.md             │
│ → 11 invariants (I1-I11), chỉ audit đọc              │
├──────────────────────────────────────────────────────┤
│ Tầng 2: GOVERNED RULES (Toàn Workspace)              │
│ .agent/rules/*.md                                    │
│ → 10 rules, đồng bộ qua ./para install/update        │
│ → Áp dụng cho TẤT CẢ projects trong workspace        │
├──────────────────────────────────────────────────────┤
│ Tầng 3: PROJECT RULES (Riêng từng project)           │
│ Projects/<tên>/.agent/rules/*.md                     │
│ → Rules tùy chỉnh, bổ sung (không ghi đè)            │
│ → Khai báo qua rules.md trigger index                │
└──────────────────────────────────────────────────────┘

Tầng 1: Kernel (Bất biến)

Tệp: invariants.md — 11 quy tắc cứng, thay đổi cần RFC + tăng MAJOR version
Ai đọc: Chỉ /para-audit (quét toàn bộ) — workflow duy nhất được đọc toàn bộ kernel
Hình dung: Như bản Hiến pháp — ai cũng tuân theo, nhưng gần như không ai đọc toàn bộ mỗi ngày

Tầng 2: Governed Rules (Toàn Workspace)

Đồng bộ từ catalog.yml bởi ./para install hoặc ./para update. Áp dụng cho tất cả projects trong workspace.

Rule	Mục đích	Tải khi
`agent-behavior.md`	Giao tiếp, ngôn ngữ, giảm nhiễu	Luôn luôn (nhẹ)
`governance.md`	Ranh giới Kernel — hạn chế sửa đổi hệ thống	Chạm kernel/ hoặc .para/
`context-rules.md`	Thứ tự tải context + giao thức trigger index	Mỗi phiên
`hybrid-3-file-integrity.md`	Hot Lane + nén-không-xóa + /end sync	Thao tác trên tasks/
`para-discipline.md`	Tuân thủ phân loại PARA	Tạo/di chuyển files
`artifact-standard.md`	Tiêu chuẩn định dạng tài liệu	Tạo artifacts
`naming.md`	Đặt tên file/branch/commit	Tạo files mới
`vcs.md`	Best practices Git	Commit/push
`versioning.md`	Chính sách SemVer	Tăng version
`exports-data.md`	An toàn xuất dữ liệu	Xuất/chia sẻ

Tầng 3: Project Rules (Riêng từng project)

Vị trí: Projects/<tên>/.agent/rules/
Không đồng bộ từ repo — người dùng tạo qua /para-rule add
Bổ sung cho rules toàn cục, không bao giờ ghi đè
Ví dụ: dogfooding-policy, content-accuracy, sync-upstream

🎯 Trigger Index (Two-Tier Progressive Disclosure)

Hệ thống dùng hai tệp chỉ mục để agent biết rule nào tồn tại và khi nào cần tải — mà không cần đọc hết tất cả rule files ngay từ đầu.

Tier 1: Chỉ mục Rules Workspace (LUÔN ĐỌC)

Tệp: .agent/rules.md

Bảng nhẹ (~10 dòng) này được đọc ở đầu mỗi phiên. Agent ghi nhớ các triggers nhưng KHÔNG đọc tệp rule thực tế ngay.

| Rule                    | Trigger                                  | File                             |
| :---------------------- | :--------------------------------------- | :------------------------------- |
| Governance              | Chạm kernel/, .para/, hoặc file hệ thống | rules/governance.md              |
| Hybrid 3-File Integrity | Đọc/ghi artifacts/tasks/                 | rules/hybrid-3-file-integrity.md |
| ...                     | ...                                      | ...                              |

Tier 2: Chỉ mục Rules Project (CÓ ĐIỀU KIỆN)

Tệp: Projects/<tên>/.agent/rules.md

Chỉ đọc nếu project khai báo has_rules: true trong project.md.

| Rule              | Trigger                                 | File                 |
| :---------------- | :-------------------------------------- | :------------------- |
| Dogfooding Policy | Sửa repo/, đồng bộ files sang workspace | dogfooding-policy.md |
| Content Accuracy  | Viết nội dung tài liệu                  | content-accuracy.md  |

[!IMPORTANT] Agent đọc chỉ mục (bảng trigger), không phải tệp rules. Tệp rules chỉ được tải theo nhu cầu khi hành động khớp với trigger trong phiên làm việc. Đây là chìa khóa cho hiệu quả token.

🔄 Luồng Tải Rules

Đây là cách rules được tải trong một phiên làm việc điển hình:

/open
  ↓
Step 2.5a: Đọc .agent/rules.md (chỉ mục workspace) — LUÔN LUÔN
  → Ghi nhớ 10 triggers (KHÔNG đọc tệp rule)
  ↓
Step 2.5b: has_rules: true?
  → CÓ → Đọc Projects/<tên>/.agent/rules.md (chỉ mục project)
  → KHÔNG → Bỏ qua (chỉ rules project bị bỏ, rules workspace đã tải)
  ↓
Phiên code: agent sắp sửa repo/
  → Khớp: "Sửa repo/" → tải dogfooding-policy.md → tuân theo
  ↓
Agent nhận yêu cầu ad-hoc "xóa nút download"
  → Khớp: "yêu cầu ad-hoc" → tải hybrid-3-file-integrity.md → ghi hot lane trước

Cổng `has_rules`

# Trong project.md
has_rules: true # Cổng cho /open Step 2.5b (chỉ rules project)

true → /open đọc chỉ mục rules project
false hoặc thiếu → bỏ qua rules project (rules workspace vẫn được tải)
/para-audit update Step 5 kiểm tra tính nhất quán giữa has_rules và files thực tế

📊 Phạm Vi Workflow

Workflow	Chỉ mục Workspace	Chỉ mục Project	Chi tiết
`/open`	✅ Step 2.5a (LUÔN LUÔN)	✅ Step 2.5b (có điều kiện)	Workspace: luôn. Project: nếu `has_rules: true`
`/plan`	✅ Step 2.7 D1	✅ Step 2.7 D2 + Step 8.5	D1: ràng buộc workspace. D2: ràng buộc project
`/para-audit`	—	✅ Step 5 (update)	Kiểm tra nhất quán: `has_rules` vs chỉ mục vs disk
`/para-rule`	—	✅ Core	Quản lý CRUD rules

📚 Tham Khảo

Rule: Rule context-rules Rule #4 — Giao thức Two-Tier Progressive Disclosure
Workflow: /open Step 2.5a/2.5b, /plan Step 2.7 D1/D2
Kernel: Invariant I2 (rules cấp workspace)

→ Tìm hiểu Workflow /open — Tải Rules → Tìm hiểu Workflow /para-rule — Quản lý Project Rules → Học: Kiến trúc Hybrid 3-File → Học: Defense-in-Depth — Phục Hồi Context