# [AI Flow Kit] Docs Management Flow — v1.0

> **Đối tượng:** PM · BA · Dev · Tester · TL — mọi role cập nhật tài liệu trong `AK-Docs` / `Shared-Docs`
> **Trạng thái:** Draft — chờ PM review
> **Ngày:** 2026-07-13
> **Liên quan:** [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md) (mục 5.1 là tiền lệ kỹ thuật của flow này, áp dụng riêng cho `99.Memory/`) · [BA-Specs-Structure.md](./BA-Specs-Structure.md) · [Coding-Structure.md](./Coding-Structure.md) · [Testing-Structure.md](./Testing-Structure.md)

---

## 1. Mục Tiêu

`AK-Docs` (và `Shared-Docs`) là kho tài liệu dùng chung cho cả team — BA-Specs, Coding docs, Testing docs, Memory — tách khỏi source code repo. Tài liệu này chuẩn hóa **một quy trình Git duy nhất** cho việc cập nhật kho này, áp dụng cho mọi loại tài liệu và mọi role, để:

- **PM luôn là người chịu trách nhiệm chính** — review và merge kết quả cuối cùng vào `main`.
- Không ai (kể cả AI) push thẳng vào `main` — mọi thay đổi đi qua branch + Merge Request (MR).
- AI được phép **hỗ trợ** phần thao tác Git (tạo branch, commit, mở MR) để giảm việc tay chân, nhưng **không bao giờ tự quyết định** — mỗi hành động ghi (write) đều dừng lại chờ người dùng xác nhận rõ ràng trước khi chạy.

---

## 2. Nguyên Tắc Cốt Lõi

1. **`main` là nhánh chính thức, protected.** Chỉ chứa tài liệu đã được PM review và merge — không ai push trực tiếp.
2. **Mọi cập nhật tài liệu bắt đầu bằng một branch feature mới từ `main`**, đặt tên theo format:
   ```
   feature/<functionId>/<taskId>
   ```
   Ví dụ: `feature/F-001_User-Login/TICKET-100`.
3. **AI hỗ trợ 2 bước có thể tự động hoá, luôn có 1 điểm dừng xác nhận riêng cho mỗi bước:**
   - Tạo branch (nếu user chưa tự tạo) — AI hỏi "tạo branch X từ main, đồng ý không?" trước khi chạy.
   - Tạo MR (commit + push + mở MR kèm title/description) — AI hỏi "nội dung commit/MR như sau, đồng ý không?" trước khi chạy.
4. **PM là approver cuối cùng của MR.** Role khác (BA/Dev/QA/TL) có thể được tag để góp ý chuyên môn (consult), nhưng quyền merge vào `main` chỉ thuộc PM.

> Đây chính là mô hình đã thiết kế cho riêng `99.Memory/` ở [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md), mục 5.1 "Vai trò & Quy trình GitLab chi tiết" — tài liệu này mở rộng đúng mô hình đó ra **toàn bộ `AK-Docs`** (BA-Specs, Coding, Testing, Memory), không chỉ riêng Memory.

---

## 3. Phạm Vi Áp Dụng

| Repo | Nội dung | Áp dụng flow này? |
|---|---|---|
| `AK-Docs` | `01.QnA/`, `02.BA-Specs/`, `03.Testing/`, `04.Coding/`, `99.Memory/` — tài liệu riêng của từng dự án | ✅ Bắt buộc |
| `Shared-Docs` | Template dùng chung mọi dự án | ✅ Áp dụng, nhưng approver cuối có thể là AI Testing Team thay vì PM dự án (giống Flow B của Memory-Architecture) — mỗi dự án tự quyết định khi setup |

Flow này **không áp dụng** cho source code repo (Dev vẫn tạo PR code theo quy trình hiện có ở Gate 5 — `superpowers:requesting-code-review`). Đây là flow riêng cho kho **tài liệu**.

---

## 4. Mô Hình Nhánh Git

```
Repo AK-Docs (GitLab/GitHub)
main ──────●─────────────●─────────────●───────→   main = tài liệu chính thức (protected)
            \             \             ↑ merge (PM approve)
             \             \      feature/F-003_Report/TICKET-210   ← QA cập nhật testcase
              \       feature/F-002_Dashboard/TICKET-155             ← BA cập nhật UC-Spec
        feature/F-001_User-Login/TICKET-100                          ← Dev cập nhật coding docs
```

**Cấu hình bắt buộc (làm 1 lần khi setup dự án), tương tự Memory-Architecture §5.1.2:**

| Hạng mục | Cấu hình |
|---|---|
| Protected branch | `main` của `AK-Docs`: không push trực tiếp, chỉ merge qua MR |
| Approval rule | MR bắt buộc ≥1 approval từ **PM** |
| CODEOWNERS (tuỳ chọn) | `02.BA-Specs/ @BA` · `03.Testing/ @QA` · `99.Memory/00.Shared/architecture/ @TL` — để hệ thống tự gợi ý consult reviewer theo diff |
| MR template | Nhúng checklist PM (mục 6) + trường: functionId, taskId, loại tài liệu thay đổi |

---

## 5. Quy Trình Chi Tiết

```
Người dùng bắt đầu cập nhật tài liệu (BA-Spec / Coding docs / Testcase / Memory...)
      │
      ▼
BƯỚC 1 — Đảm bảo main mới nhất
  git checkout main && git pull origin main --ff-only
      │  (PHẢI làm trước khi tạo branch, tránh branch bị lệch/conflict)
      ▼
BƯỚC 2 — Đã có branch feature/<functionId>/<taskId> cho task này chưa?
      │ CHƯA CÓ
      ▼
  AI đề xuất: "Tạo branch feature/<functionId>/<taskId> từ main — đồng ý?"
      │ KHÔNG → dừng, user tự tạo branch thủ công nếu muốn
      ▼ CÓ
  AI chạy `ak docs branch <functionId> <taskId>` → pull main, tạo + push branch
      │
      ▼ (branch đã có sẵn → checkout thẳng, bỏ qua bước hỏi)
BƯỚC 3 — Cập nhật nội dung tài liệu trên branch
  AI viết draft (theo đúng Gate của workflow tương ứng — BA/Coding/Testing/Memory)
      │
      ▼
BƯỚC 4 — Self-review (KHÔNG cần PM ở bước này)
  Người tạo (BA/Dev/QA/TL) tự đọc lại nội dung AI viết, sửa trực tiếp nếu cần
  (giống gate-review: hover comment trong VS Code, hoặc sửa tay)
      │
      ▼
BƯỚC 5 — Hoàn thành Gate cuối của workflow tương ứng
  (Gate 4 BA-Spec / Gate cuối Coding docs / Gate 4 Testcase / Luồng LƯU TRỮ Memory)
      │
      ▼
BƯỚC 6 — AI đề xuất tạo Merge Request
  AI soạn title + description (link ticket, tóm tắt thay đổi) → hiển thị cho user
      │
      ▼
  "Nội dung commit/MR như trên — đồng ý tạo MR?"
      │ KHÔNG → dừng, user tự chỉnh sửa rồi yêu cầu lại
      ▼ CÓ
  AI chạy `ak docs submit --title "..." --description "..."` → commit + push + mở MR
      │
      ▼
BƯỚC 7 — PM REVIEW (điểm duyệt duy nhất, bắt buộc)
  PM đọc MR trên GitLab/GitHub
      │ CẦN SỬA → comment, quay lại BƯỚC 3
      │ TỪ CHỐI → đóng MR, lý do ghi lại công khai
      ▼ ĐỒNG Ý
  PM MERGE vào main
      │
      ▼
BƯỚC 8 — Đồng bộ
  Session/tool tiếp theo của mọi thành viên `git pull` main → thấy tài liệu mới
```

### Ai review, ai tự làm — làm rõ từng bước

| Bước | Việc gì | Ai làm | Cần PM review? |
|---|---|---|---|
| 1 | Pull `main` mới nhất | AI (khi được xác nhận) hoặc user tự chạy | ❌ Không |
| 2 | Tạo branch `feature/<functionId>/<taskId>` | AI đề xuất, **user xác nhận Y/N**, AI thực thi | ❌ Không |
| 3 | Viết/sửa nội dung tài liệu | AI draft, role tương ứng (BA/Dev/QA/TL) chỉnh sửa | ❌ Không |
| 4 | Self-review nội dung | Người tạo tài liệu (role tương ứng) — **tự chịu trách nhiệm nội dung đúng chuyên môn** | ❌ Không — đây là self-review, không phải PM review |
| 5 | Hoàn thành Gate cuối workflow | AI + role tương ứng, theo quy trình Gate hiện có của từng loại tài liệu | ❌ Không |
| 6 | Commit + push + mở MR | AI đề xuất nội dung, **user xác nhận Y/N**, AI thực thi | ❌ Không |
| 7 | **Review & merge MR vào `main`** | **PM** (có thể tag TL/BA/QA consult theo CODEOWNERS, nhưng quyền quyết là PM) | ✅ **Bắt buộc — đây là điểm duyệt duy nhất** |
| 8 | Đồng bộ về máy mọi người | Tự động (`ak init`/`ak update` pull `main`) | ❌ Không |

> **Tóm gọn:** role tạo tài liệu (BA/Dev/QA/TL) chịu trách nhiệm **self-review đúng chuyên môn** trước khi gửi MR. **PM là người duyệt duy nhất trước khi merge vào `main`** — không có bước nào khác cần PM ngoài Bước 7.

---

## 6. Checklist PM Khi Review MR

1. Nội dung có đúng với ticket/yêu cầu gốc không?
2. Đúng loại tài liệu, đúng vị trí thư mục (theo BA-Specs-Structure / Coding-Structure / Testing-Structure / Memory-Architecture)?
3. Không phá vỡ liên kết tới tài liệu khác (link chéo UC-Spec ↔ Test Case ↔ Dev Plan)?
4. Đã self-review bởi đúng role trước khi gửi MR chưa (xem Bước 4)?
5. Có cần tham vấn TL/BA/QA cho nội dung kỹ thuật/nghiệp vụ nhạy cảm không?

---

## 7. Công Cụ Hỗ Trợ — CLI Mới

Hai lệnh mới trong `ai-flow-kit` (`scripts/docs-branch.js`, đăng ký trong `bin/aiflow.js`), dùng chung cho mọi workflow tạo tài liệu:

### 7.1 `ak docs branch <functionId> <taskId>`

Pull `main` mới nhất rồi tạo (hoặc checkout nếu đã có) branch `feature/<functionId>/<taskId>`.

```bash
ak docs branch F-001_User-Login TICKET-100 [--repo AK-Docs|Shared-Docs] [--base main]
```

- Nếu branch đã tồn tại (local hoặc remote) → checkout thẳng, không hỏi lại.
- Nếu `AK-Docs` đang có thay đổi chưa commit → dừng, yêu cầu xử lý trước.
- Nếu chưa có branch → in ra kế hoạch (`git checkout main && git pull ...`, `git checkout -b ...`, `git push -u ...`) và **chờ xác nhận** trước khi chạy.

### 7.2 `ak docs submit`

Commit + push branch tài liệu hiện tại, sau đó mở MR.

```bash
ak docs submit --title "docs(F-001_User-Login): update UC-Spec v2" \
                --description "Cập nhật spec theo QnA vòng 2, TICKET-100" \
                [--repo AK-Docs|Shared-Docs] [--base main]
```

- Chặn nếu đang đứng ở `main` (bắt buộc phải ở branch feature).
- Tự phát hiện GitLab/GitHub qua remote URL: dùng `glab mr create` hoặc `gh pr create` nếu có cài; nếu không, in ra link tạo MR thủ công (điền sẵn source/target branch + title).

### 7.3 Cơ chế xác nhận (bắt buộc, không có ngoại lệ)

Cả 2 lệnh trên đều **không thực thi bất kỳ thao tác ghi Git nào (checkout -b, commit, push) nếu thiếu xác nhận**:

- **Người dùng chạy trực tiếp trong terminal** → lệnh tự hỏi (Y/N) qua prompt tương tác.
- **AI chạy thay mặt người dùng** → AI phải hiển thị đầy đủ kế hoạch (branch name / commit message / MR title & description) trong chat và **chờ người dùng gõ xác nhận** (ví dụ "đồng ý", "yes", "OK") trước khi thêm cờ `--yes` vào lệnh. AI **không được tự ý thêm `--yes`** khi chưa thấy xác nhận rõ ràng của người dùng trong hội thoại.
- Nếu chạy không có `--yes` và không có TTY tương tác (trường hợp AI gọi lệnh) → lệnh chỉ in kế hoạch, không làm gì cả, thoát với lỗi — an toàn theo mặc định.

> **Vì sao có bước "gõ `--yes`" thay vì để AI tự chạy interactive prompt:** kit này có sẵn hook `scripts/hooks/block-git-write.js` chặn cứng mọi lệnh `git commit/add/push/...` chạy trực tiếp qua Bash — triết lý xuyên suốt là **"AI làm draft — người review & approve"**. Hai lệnh `ak docs branch`/`ak docs submit` là cách hiện thực hoá đúng triết lý đó cho riêng luồng quản lý tài liệu: thao tác Git thật sự nằm trong CLI (không phải AI gõ `git commit` trực tiếp), nhưng **luôn cần một xác nhận tường minh của người dùng trong hội thoại trước khi CLI được phép chạy với `--yes`.**

---

## 8. Câu Hỏi Thường Gặp

**Nếu 2 người cùng sửa tài liệu cho cùng 1 `functionId`/`taskId`?**
→ Branch trùng tên — người thứ 2 chạy `ak docs branch` sẽ được checkout vào branch đã có sẵn (không tạo mới), tiếp tục làm việc trên cùng branch đó. Cần tự đồng bộ (pull) trước khi push để tránh conflict.

**Không cài `glab`/`gh` thì sao?**
→ `ak docs submit` vẫn commit + push branch bình thường, chỉ riêng bước mở MR sẽ in ra một link đã điền sẵn source/target branch + title để tự bấm mở trên trình duyệt.

**Có bắt buộc dùng CLI này không, hay tự làm bằng tay vẫn được?**
→ Không bắt buộc. `ak docs branch`/`ak docs submit` chỉ là công cụ hỗ trợ giảm thao tác tay; user luôn có thể tự `git checkout`, `git commit`, tạo MR thủ công như trước. Quy tắc branch `feature/<functionId>/<taskId>` + PM review ở `main` vẫn phải tuân theo dù làm bằng cách nào.

**Merge conflict khi PM merge MR thì ai xử lý?**
→ Người tạo MR (role tương ứng), không phải PM — PM chỉ review nội dung, không chịu trách nhiệm giải quyết conflict kỹ thuật.

---

## 9. Lộ Trình Triển Khai

### Phase 1 — Ngay khi rollout (đã có trong bản này)
1. `scripts/docs-branch.js` + lệnh `ak docs branch` / `ak docs submit`.
2. Setup GitLab/GitHub cho `AK-Docs`: protected `main`, approval rule PM, (tuỳ chọn) CODEOWNERS.
3. PM đọc và duyệt tài liệu này.

### Phase 2 — Sau khi PILOT ổn định
4. MR template có checklist PM (mục 6) nhúng sẵn.
5. Gắn bước "AI đề xuất tạo branch/MR" vào đúng điểm Gate cuối của từng workflow (`create-spec`, `create-testcase`, coding Gate 5, Memory Luồng Lưu Trữ) — hiện đã có hook điểm dừng tương tự ở `scripts/task.js` (`nextGate`, khi `currentGate >= maxGate`).
6. Đo lường: số MR/tuần, thời gian trung bình từ tạo MR → PM merge, số MR bị từ chối/yêu cầu sửa.

---

*Tài liệu này chuẩn hoá quy trình Git cho toàn bộ `AK-Docs`/`Shared-Docs`, dựa trên mô hình đã thiết kế riêng cho Memory ở [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md). Mọi thắc mắc liên hệ AI Testing Team.*