# Chính sách và nguồn kiểm chứng tài liệu

> Loại chính: Governance  
> Đối tượng: người viết và duyệt tài liệu

## Nguồn sự thật

Khi thông tin mâu thuẫn, dùng thứ tự:

1. hành vi được test tự động xác nhận;
2. code và migration đang thực thi;
3. cấu hình deploy/workflow đang hoạt động;
4. tài liệu chuẩn trong `docs/`;
5. README cục bộ và `docs-legacy/`;
6. ghi chú, kế hoạch và slide.

## Nguồn kiểm chứng theo chủ đề

| Chủ đề | Nguồn chính |
|---|---|
| HTTP API | `apps/ai-service/main.py`, `api/routes.py`, `api/dto.py` |
| Runtime wiring | `bootstrap.py`, `config.py` |
| RAG/guardrail | `rag/agent.py`, `rag/service.py`, `rag/answer.py` |
| Retrieval | `rag/routing.py`, `rag/sections.py`, `adapters/qdrant.py` |
| Persistence | `adapters/postgres.py`, `migrations/*.sql` |
| Web/BFF | `apps/web/app/api/chat/route.ts`, shared types |
| Ingestion | `ingestion/ingestion/cli.py`, chunk và load modules |
| Infrastructure | `infra/docker`, production Compose, Caddy, Helm/ArgoCD |
| CI/CD | `.github/workflows/*.yml` |
| Hành vi | test suites và `evals/production_manual_60.jsonl` |

## Quy tắc cập nhật

- Không biến kế hoạch thành tính năng hoàn tất.
- Phân biệt “có code”, “được test”, “đã deploy” và “đang phục vụ traffic”.
- Mỗi thay đổi interface phải cập nhật file chuẩn liên quan trong cùng pull request.
- Lệnh trong tài liệu phải được chạy thử hoặc đánh dấu rõ phụ thuộc cloud/hạ tầng.
- Không ghi số test, corpus hoặc benchmark không có ngày/model/hash.
- Mỗi file giữ một công việc đọc chính dù có section hỗ trợ loại Diátaxis khác.
- Kiểm tra toàn bộ relative links sau khi đổi tên hoặc di chuyển.

## Vòng đời

`docs/` là nguồn tài liệu chuẩn. `docs-legacy/` chỉ để tra lịch sử và raw notes;
không được dùng để kết luận hành vi hiện tại nếu chưa đối chiếu code. Tài liệu hết
hiệu lực phải được xoá hoặc ghi deprecated kèm link thay thế; không để hai file cùng
tự nhận là canonical.