@relipa/ai-flow-kit 0.1.7 → 0.1.8

package/docs/common/Docs-Management-Flow.md

@@ -0,0 +1,222 @@
+# [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` | `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.*

package/docs/common/INDEX.md

@@ -0,0 +1,37 @@
+# AI Flow Kit — Self-Help Index
+
+> **Purpose:** This file is the entry point for answering questions *about ai-flow-kit itself* — "how do I install this", "how does a PM use this", "how do I submit a memory", etc. — as opposed to questions about the ticket/feature the developer is currently working on.
+>
+> **For the AI:** Match the user's question against the "Ask about" column below, then read the linked file(s) before answering. Don't guess — if nothing below covers the question, say so plainly (see "Unanswered topics" at the bottom) instead of inventing behavior. Prefer citing the file path you read from so the user can verify.
+>
+> **For humans:** every file here also exists as a plain Markdown file — read it directly if you don't have an AI assistant handy.
+
+## Topic map
+
+| Ask about | Read | Notes |
+|---|---|---|
+| Install / setup, global vs local, first run | [getting-started.md](./getting-started.md), [QUICK_START.md](./QUICK_START.md) | |
+| What is the Gate Workflow, how do Gates 1–5 fit together | [AIFLOW.md](./AIFLOW.md) (§ Workflow Overview) | |
+| Roles — PM / DEV / AI responsibilities | [AIFLOW.md](./AIFLOW.md) (§ Roles) | Table is intentionally brief — see "Unanswered topics" for a fuller PM-specific guide |
+| All CLI commands (`ak ...`), options, examples | [cli-reference.md](./cli-reference.md) | |
+| Switching between Claude Code / Cursor / Gemini CLI mid-task | [ai-integration.md](./ai-integration.md) | |
+| Config levels (global / project / local state) | [configuration.md](./configuration.md) | |
+| Something isn't working (`command not found`, permission denied, etc.) | [troubleshooting.md](./troubleshooting.md) | |
+| Bug-fix / feature / refactor / investigation / impact-analysis / Figma workflows | [workflows/](./workflows/) | one file per task type |
+| What changed in the latest version | [CHANGELOG.md](./CHANGELOG.md) | check here before assuming a command still behaves like an older doc describes |
+| Manually create + submit a memory (`ak memory ...`) | [cli-reference.md](./cli-reference.md) (§ memory) | `99.Memory/` Project Brain — draft locally, `submit` opens a Merge Request, a teammate approves |
+| How AI recalls memories automatically in a new session | [CHANGELOG.md](./CHANGELOG.md) ([0.1.7] entry) | Layer 1 (`MEMORY.md` index) + Layer 2 (top-N scored, relevant to active ticket) injected by the session-start hook |
+| `AK-Docs/` folder structure — overview (all roles) | [Project-Structure.md](./Project-Structure.md) | top-level map: `AK-Docs/` sections + `Shared-Docs/` |
+| `AK-Docs/02.BA-Specs/` folder structure (BA) | [BA-Specs-Structure.md](./BA-Specs-Structure.md) | Requirements → Analysis → QnA → UC Specs, by Function-ID |
+| `AK-Docs/04.Coding/` folder structure (Dev) | [Coding-Structure.md](./Coding-Structure.md) | Requirements → Plans → TDD-Notes → Reviews → Pull-Requests, by Function-ID/Ticket-ID |
+| `AK-Docs/03.Testing/` folder structure (Tester) | [Testing-Structure.md](./Testing-Structure.md) | Strategies → Testcases → evidence, by Function-ID |
+| `99.Memory/` Project Brain — full design, scoring model, mem-id scheme, role/PM permissions | [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md) | v1.1 — Phase 1 (`draft/list/submit/remove`) is what's implemented today; later phases in this doc are roadmap, not shipped yet |
+| How updates to `AK-Docs`/`Shared-Docs` get reviewed — branch/Merge Request flow, who can merge to `main` | [Docs-Management-Flow.md](./Docs-Management-Flow.md) | Doc's own header says `Trạng thái: Draft — chờ PM review` — flag that when answering, don't present it as final policy |
+
+## Unanswered topics (do not invent — say so and stop here)
+
+These are real questions ai-flow-kit users ask that **don't have a public doc yet**. If asked about one of these, say the topic isn't documented yet and point to the closest thing above instead of guessing:
+
+- A dedicated "PM day-1 guide" (today PM guidance is folded into `AIFLOW.md` § Roles + `getting-started.md`, not a standalone walkthrough)
+
+> Maintaining this file: when you write a new `docs/common/*.md` (or curate one down from `docs/internal/`), add a row above and remove it from "Unanswered topics".