@relipa/ai-flow-kit 0.1.5 → 0.1.7-beta.0

package/custom/skills/read-study-requirement/SKILL.md

@@ -76,7 +76,9 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
 
 5. Display Gate 1 prompt and wait for `APPROVED`.
 
-> After APPROVED, proceed to Gate 2. The lean doc is intentional — Gate 2 plan will fill in the details.
+> After APPROVED, proceed to Gate 2.
+> - **`gen-doc` tasks:** Gate 2 generates the output document immediately (no `plan.md`, no TDD). Self-review + task-summary.md are created automatically.
+> - **All other tasks:** Gate 2 plan fills in the implementation details.
 
 ---
 
@@ -111,6 +113,63 @@ Do this investigation **before** asking any questions. Come prepared.
 
 ---
 
+### Step 1.5: Detect & Read Figma Design (UI tickets only)
+
+Run this only when the ticket touches UI. Skip entirely for non-UI tickets.
+
+1. **Detect a Figma URL** in this order:
+   - `current.json` → `description`
+   - `current.json` → `supplementaryContext[]` items
+   - Pattern: `https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>`
+2. **No URL but ticket looks like UI** (mentions screen, page, component, layout, "theo design"):
+   ask the DEV **once** to paste a Figma URL. If DEV skips → write "Design: TBD" in the
+   Design Analysis section and continue. Do NOT ask again.
+3. **URL found** → invoke `figma-to-component` Steps 0–2.5 (verify MCP, read design,
+   detect & export images). Then persist the shared artifact:
+   - Create `plan/[ticket-id]/design/`
+   - Save raw response to `plan/[ticket-id]/design/nodes.json` (cache for later gates)
+   - Save exported images to `plan/[ticket-id]/design/images/`
+   - Write `plan/[ticket-id]/design/figma-manifest.json` (nodeId → image file) — per-ticket,
+     NOT a shared global manifest
+   - Write `plan/[ticket-id]/design/design-context.md` using the template below
+4. **Figma MCP not connected** → tell DEV to run `aiflow init -a figma` (or `-a figma-desktop`),
+   mark Design Analysis as "⚠️ pending MCP", and continue with the non-UI parts of the requirement.
+   Do NOT abort the ticket.
+
+**`design-context.md` template:**
+
+```markdown
+# Design Context: [ticket-id]
+
+**Figma URL:** <url>   **fileKey:** xxx   **nodeId:** 123-456
+**Fetched:** [YYYY-MM-DD]   **Adapter:** figma (REST) | figma-desktop
+
+## 1. Layout Structure
+- Node tree: Frame > Header / Body > Card[] / Footer
+- Flex direction, gap, padding, alignment per region
+
+## 2. Design Tokens
+| Type | Figma value | Project token |
+|------|-------------|---------------|
+| Color | #3B82F6 | blue-500 / --color-primary |
+| Type  | 16/600    | text-base font-semibold |
+| Space | 16px      | p-4 / gap-4 |
+
+## 3. Components to build
+- [ ] UserCard (variants: default, hover) — nodeId 78-910
+- [ ] Header — nodeId 12-3
+
+## 4. Image Map
+| nodeId | layer | file |
+|--------|-------|------|
+| 123-456 | Banner Top | design/images/banner-top-123-456.png |
+
+## 5. Notes
+- Anything not mapped 1:1 (custom fonts, effects…)
+```
+
+---
+
 ### Step 2: Clarify Requirements via Q&A
 
 Ask clarifying questions directly — **one question at a time**, wait for the developer's response before asking the next.
@@ -227,6 +286,15 @@ Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 
 ---
 
+## Design Analysis (UI tickets only)
+
+- **Source:** [Figma URL or "TBD" or "⚠️ pending MCP"]
+- **Artifact:** `plan/[ticket-id]/design/design-context.md`
+- **Summary:** layout, key components to build, design tokens to map, images exported
+- **Impact on approach:** how the design shapes the proposed solution
+
+---
+
 ## 4. Impact Analysis
 
 **Impact Level:** 🟢 Low / 🟡 Medium / 🔴 High

package/custom/skills/review-plan/SKILL.md

@@ -6,6 +6,8 @@ keywords: review, code review, approve, summary, checklist
 
 # Review Plan — Gate 4
 
+> ⚠️ **Skip this gate for `gen-doc` tasks.** gen-doc tasks only use Gates 1 and 2 (Gate 2 includes self-review automatically). This gate applies to `feature`, `bug-fix`, `refactor`, `documentation`, and `investigation` tasks.
+
 > **GATE 4: Runs after AI has completed code generation.**
 >
 > Principle: AI self-reviews first (verification + impact-analysis), then presents a summary to the developer. The developer decides: APPROVED or report a bug.
@@ -77,6 +79,26 @@ Run in the following mandatory order:
 
 **If any step fails → fix first, do not proceed to Step 2.**
 
+### Step 1.5: Design Conformance Check (UI tickets only)
+
+If `plan/[ticket-id]/design/design-context.md` exists, compare the generated UI against the
+design — **visually against the rendered reference image, not just the text checklist.** Open
+`public/assets/figma/_reference-<nodeId>.png` (or the Figma frame) and the running UI, and check
+region by region (header / panel / sections / footer):
+
+- [ ] **Reference image compared** region by region; every visible difference listed
+- [ ] **Background** is the correct layer (paint order) and actually visible
+- [ ] **No-fabricate**: no element rendered that isn't in the design (no extra button/section)
+- [ ] **No-omit**: every text label + every image node is present in its region
+- [ ] Layout matches (arrangement/position per region, not a generic flow)
+- [ ] Colors match the Design Tokens table (project token or arbitrary value)
+- [ ] Typography matches (size, weight, line-height)
+- [ ] Every component listed in "Components to build" exists
+- [ ] Every image in the Image Map exists under `public/assets/figma/`
+
+Any mismatch → treat as a coding bug: fix before Step 2. A text-only checklist tick is NOT enough —
+if you have not actually looked at the reference image, say so. Skip this step for non-UI tickets.
+
 ### Step 2: Create Summary Report
 
 Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
@@ -139,8 +161,25 @@ Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 - [ ] Naming and Code Style follow conventions
 - [ ] Sufficient tests (unit + integration)
 - [ ] No dead code / leftover console.logs
+- [ ] UI matches `design-context.md` (layout, color, typography, spacing) — UI tickets only
 ```
 
+### Step 2.5: Retrospect + propose memory drafts
+
+Synthesize what was learned this task. **Priority order — human corrections first:** if this is a repeat pass through Gate 4 (the developer already sent "BUG: ..." at least once this task), the developer's own correction is the single highest-value lesson — scan back through this session for it and draft it even if you already drafted something for the earlier BUG at Step 4 (dedup will catch an exact repeat; don't skip capturing it out of caution). Only after that, add anything else genuinely new: architecture facts discovered, decisions made and why. For each candidate, create a **local draft** (no approval needed yet — `_pending/` is local-only, doc `docs/internal/Memory-Architecture-v1.0.md`):
+
+```
+ak memory draft --category 01.Lessons/dev --function-id [functionId] \
+  --slug <short-kebab-slug> --content "<≤150 từ, 1 fact>" \
+  --tags <tag1,tag2> --workflows coding --source "[ticket-id] / Gate 4"
+```
+
+Other useful categories here: `00.Shared/architecture` (facts about the system discovered while coding), `00.Shared/decisions` (a technical choice made and why). Skip this step if nothing genuinely new was learned — don't manufacture a memory just to have one.
+
+If `ak memory draft` reports a conflict (a similar memory already exists), don't create a duplicate — mention it to the developer instead so they can decide whether to edit the existing one.
+
+List the created draft(s) in the Step 3 message below so the developer knows what's sitting in `_pending/` — they (or anyone on the team) can inspect and `ak memory submit` it later when ready to share with the team.
+
 ### Step 3: GATE 4 — Present to Developer
 
 ```markdown
@@ -154,6 +193,7 @@ Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 - Tests: ✅ [N] passed / ❌ [N] failed  
 - Impact: [Low/Medium/High]
 - Checklist: [N/N] items ✅
+- Memory drafts created: [N] (local, `_pending/` — `ak memory submit` when ready to share)
 
 **You need to:**
 1. Review the summary above
@@ -176,10 +216,12 @@ Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 → Guide on creating a Pull Request
 
 **If the developer types "BUG: [description]" — coding bug:**
+→ **Immediately draft a memory** capturing exactly what the developer flagged and why it was wrong (`ak memory draft --category 01.Lessons/dev --function-id [functionId] --slug <slug> --content "<the bug + the fix>" --workflows coding --source "[ticket-id] / Gate 4 dev feedback"`) — do this before fixing, while the correction is fresh; don't wait for Step 2.5 on the next pass to catch it in hindsight.
 → Analyze bug, fix, rerun verification
 → Repeat from Step 1 of Gate 4
 
 **If the developer types "BUG: [description]" — requirement bug:**
+→ **Immediately draft a memory** (same category/command as above) capturing what was misunderstood about the requirement and what it actually should have been — this is a requirement-comprehension lesson, valuable even though Gate 1 itself has no retrospect step of its own.
 → Notify: "This is a requirement bug, requirement document needs update"
 → Return to Gate 1, update requirement.md, wait for APPROVED again
 

package/custom/templates/memory/CODEOWNERS

@@ -0,0 +1,8 @@
+# Áp dụng thủ công vào file CODEOWNERS của repo AK-Docs (mục 5.1.2 Memory-Architecture-v1.0.md).
+# GitLab tự gợi ý các reviewer này làm Consult khi diff đụng đúng thư mục — không phải approver
+# (approver luôn là PM, cấu hình riêng ở MR approval rule, không qua CODEOWNERS).
+
+99.Memory/00.Shared/architecture/ @TL
+99.Memory/00.Shared/domain/       @BA
+99.Memory/00.Shared/glossary/     @BA
+99.Memory/02.Instincts/           @TL

package/custom/templates/memory/ci/memory-finalize.yml

@@ -0,0 +1,9 @@
+# Áp dụng thủ công vào .gitlab-ci.yml của repo AK-Docs (mục 5.1.2 Memory-Architecture-v1.0.md).
+# Chạy khi MR label `memory` đã đủ approval từ PM — flip status, rebuild MEMORY.md, commit lên branch.
+memory-finalize:
+  stage: finalize
+  rules:
+    - if: '$CI_MERGE_REQUEST_LABELS =~ /memory/ && $CI_MERGE_REQUEST_APPROVED == "true"'
+  script:
+    - node scripts/ci/memory-finalize.js  # flip status: approved, điền reviewed_by, rebuild MEMORY.md
+                                            # (script CI thực tế nằm trong repo AK-Docs, không phải kit)

package/custom/templates/memory/ci/memory-lint.yml

@@ -0,0 +1,10 @@
+# Áp dụng thủ công vào .gitlab-ci.yml của repo AK-Docs (mục 5.1.2 Memory-Architecture-v1.0.md).
+# Chạy trên mọi MR có label `memory`, TRƯỚC khi PM approve.
+memory-lint:
+  stage: lint
+  rules:
+    - if: '$CI_MERGE_REQUEST_LABELS =~ /memory/'
+  script:
+    - node scripts/ci/memory-lint.js  # validate frontmatter đủ trường, ≤150 từ, 1 fact/file,
+                                       # id không trùng, id khớp đường dẫn file, quét secret/PII
+                                       # (script CI thực tế nằm trong repo AK-Docs, không phải kit)

package/custom/templates/memory/gitlab/merge_request_templates/memory.md

@@ -0,0 +1,18 @@
+## Memory MR — Ticket: <!-- TICKET-123 -->
+
+**Loại:** Thêm mới / Gỡ bỏ (soft-remove / hard-remove)
+**Mem-id(s):** <!-- mem-F003-refund-flow, mem-F003-prevent-429-error -->
+
+### Checklist PM (bắt buộc trước khi approve)
+
+- [ ] Đúng sự thật và còn hiệu lực?
+- [ ] Trace được nguồn gốc (`source:` trỏ đúng ticket/Gate)?
+- [ ] Nội dung ngắn gọn (≤150 từ), đúng khuôn mẫu 1 file = 1 fact?
+- [ ] Có hành động cụ thể áp dụng được (mục "Áp dụng")?
+- [ ] Phạm vi (`scope:`) hẹp nhất có thể — không lạm dụng `global`?
+- [ ] Không mâu thuẫn với `.rules/`?
+- [ ] Đã tham vấn đúng người cho nội dung nhạy cảm (TL cho kỹ thuật, BA/Comtor cho glossary/domain)?
+
+### Consult (tự động theo CODEOWNERS)
+
+TL/BA được tag tự động theo thư mục bị đụng — đây là góp ý, quyền quyết vẫn ở PM.

package/custom/templates/memory/memory-item.md

@@ -0,0 +1,25 @@
+---
+id: mem-<functionId>-<slug>       # CLI tự sinh từ vị trí file: mem-<functionId>-<slug>
+                                   # slug do AI đặt — ngắn, đọc là hiểu memory lưu gì
+                                   # (vd: basic-payment-flow, refund-flow, prevent-429-error).
+                                   # KHÔNG có timestamp: trùng slug trong cùng folder chính là
+                                   # tín hiệu chống trùng lặp — CLI hỏi "memory tương tự đã có,
+                                   # cập nhật bản cũ thay vì tạo mới?"
+type: lesson | fact | decision | glossary | instinct
+workflows: [coding, create-testcase]  # workflow nào cần recall; [all] nếu mọi workflow
+tags: [payment, refund, http-429]     # ascii-lowercase, AI tự sinh khi tạo draft —
+                                       # scorer CHỈ so khớp trên trường này (không so body — JP/VN)
+scope: F-003_Payment | global     # trùng với folder chứa file; global → file đặt trong _global/
+confidence: 0.6                   # AI tự chấm 0.3–0.7; reviewer chỉnh khi duyệt
+source: TICKET-123 / Gate 4       # trace: học được từ đâu
+status: pending                   # pending | approved | deprecated
+hits: 0                           # consolidate cập nhật từ telemetry local — không sửa tay
+created: 2026-07-09
+reviewed_by:                      # điền khi approve
+refs: []                          # (tùy chọn) file/dir code hoặc docs mà memory phụ thuộc
+verified_commit:                  # commit đã verify refs lần cuối (CLI tự điền)
+stale: false                      # hook tự set true khi refs thay đổi sau verified_commit
+---
+<Nội dung: TỐI ĐA 150 từ, 1 file = 1 fact duy nhất.>
+
+**Áp dụng:** <hành động cụ thể AI/người cần làm khi gặp tình huống này.>

package/custom/templates/memory/skeleton/MEMORY.md

@@ -0,0 +1,7 @@
+# 99.Memory — Project Brain Index
+
+> Auto-generated by `ak memory submit` / `ak memory remove` when a Merge Request is merged into `main`.
+> **Do not edit this file by hand** — it is rebuilt from the frontmatter of every `status: approved` file under `99.Memory/`.
+> One line per memory: `- [mem-id](path/to/file.md) — <hook ≤15 từ> (type, scope, workflows)`
+
+See `docs/internal/Memory-Architecture-v1.0.md` in ai-flow-kit for the full design.

package/custom/templates/shared/create-spec-workflow.md

@@ -7,6 +7,26 @@
 
 ---
 
+### Pre-flight BẮT BUỘC — Đồng bộ Source & Docs (đầu MỖI Gate)
+
+> Áp dụng cho **cả 4 Gate** bên dưới — không chỉ Gate 1. Chạy đủ các bước sau **trước khi** thực hiện bất kỳ hành động nào khác của gate đó.
+
+1. **Sync repo source (bên trong, không phải AK-Docs/Shared-Docs):** xác định thư mục repo source liên quan (field `repo` trong context, hoặc repo duy nhất mở trong workspace) → `cd` vào đó → chạy `git status --porcelain`; nếu working tree sạch, chạy `git pull --ff-only`. Nếu có thay đổi chưa commit, branch diverged, hoặc không có remote tracking branch → bỏ qua pull (không phải lỗi).
+2. **Sync `AK-Docs/`:** `cd` vào `AK-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+3. **Sync `Shared-Docs/`:** `cd` vào `Shared-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+4. Sau khi xong, `cd` quay lại thư mục làm việc ban đầu trước khi tiếp tục các bước khác của gate.
+
+Nếu `AK-Docs/` hoặc `Shared-Docs/` chưa tồn tại tại workspace root, hoặc không phải git repo → bỏ qua bước tương ứng, không cảnh báo.
+
+**Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** → **KHÔNG dừng workflow** — hiển thị cảnh báo và tiếp tục gate với dữ liệu local hiện có:
+
+```
+⚠️ CẢNH BÁO: Không thể pull [tên repo] — [lý do lỗi].
+→ Đang tiếp tục Gate [N] với dữ liệu local hiện tại, có thể chưa mới nhất.
+```
+
+---
+
 ### BA Skills
 
 Các skill sau đây được cài tự động vào `.claude/skills/ba-skills/` khi chạy `ak init` hoặc `ak up`.
@@ -76,6 +96,8 @@ Bàn giao Dev/Test
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 0):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra
 
 **Xác định `functionId` (BẮT BUỘC):**
@@ -115,6 +137,20 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD10, UC-
      → Bắt đầu Gate 1...
      ```
 
+#### Bước 0.5: Đảm bảo đang làm việc trên branch riêng của task (AK-Docs)
+
+Trước khi ghi bất kỳ file nào vào `02.BA-Specs/`, đảm bảo AK-Docs đang ở branch riêng của task này, không phải `main` (mọi thay đổi `AK-Docs` phải qua branch + Merge Request, PM duyệt cuối cùng trước khi merge vào `main`):
+
+1. Lấy `taskId` từ trường `taskId` trong `.aiflow/context/current.json`.
+2. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`).
+3. Nếu **chưa** ở branch `feature/[functionId]/[taskId]`:
+   - Hỏi BA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[functionId]/[taskId]` từ `main` — đồng ý không?"
+   - BA đồng ý → chạy `ak docs branch [functionId] [taskId] --yes`
+   - BA từ chối → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (BA tự quản lý branch)
+4. Nếu **đã** ở đúng branch (ví dụ resume từ session trước) → bỏ qua, tiếp tục.
+
+> ❌ Không tự thêm `--yes` khi chưa thấy BA gõ xác nhận rõ ràng trong hội thoại.
+
 #### Bước 1: Đọc và tổng hợp đầu vào
 - Đọc `.aiflow/context/current.json` — tiêu đề, mô tả, acceptance criteria, liên kết tài liệu
 - Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
@@ -215,6 +251,8 @@ Vui lòng cung cấp câu trả lời theo một trong 3 cách:
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 1: Tiếp nhận và đánh giá câu trả lời
 - Đối chiếu từng câu trả lời với câu hỏi trong `QnA-Log_v(m).md`
 - Phân loại:
@@ -292,6 +330,8 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 1: Liệt kê thành phần giao diện
 - Đọc tài liệu phân tích đã chốt
 - Xác định: ô nhập liệu, nút bấm, liên kết, vùng hiển thị lỗi, vùng hiển thị dữ liệu
@@ -345,6 +385,8 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 1: Khởi tạo Spec từ Template
 - **READ template:** `.claude/skills/ba-skills/skill-ba-uc-template-v1.md`
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-write-uc-spec-v1.md`
@@ -387,7 +429,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 → Nếu blocked: làm theo gate-review skill response protocol
 
 **Phản hồi đặc biệt:**
-- BA gõ `REVISION: [nội dung]` → cập nhật section liên quan → re-generate review file → hiển thị lại gate pause
+- BA gõ `REVISION: [nội dung]` → **trước khi sửa**, tạo ngay 1 memory draft ghi lại chính xác điều BA vừa chỉnh (`ak memory draft --category 01.Lessons/ba --function-id [functionId] --slug <slug> --content "<điều BA sửa + vì sao>" --workflows create-spec --source "[functionId] / Gate 4 BA feedback"`) — đây là tín hiệu giá trị nhất, đừng chờ Bước 7.5 mới bắt lại theo trí nhớ → cập nhật section liên quan → re-generate review file → hiển thị lại gate pause
 
 **Definition of Done:**
 - [ ] File `UC-Spec_v1.md` đúng vị trí và cấu trúc template
@@ -399,6 +441,30 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 > **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
 
+#### Bước 7.5: Retrospect + đề xuất memory draft
+
+Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên feedback của BA trước:** nếu có vòng `REVISION` nào đã xảy ra, đảm bảo điều BA sửa đã có draft (thường đã tạo ngay lúc REVISION ở trên — kiểm tra lại, đừng bỏ sót). Sau đó mới thêm những gì mới khác: business rule mới confirm, thuật ngữ cần làm rõ, quyết định đặc tả và lý do. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/internal/Memory-Architecture-v1.0.md`):
+
+```
+ak memory draft --category 00.Shared/domain --function-id [functionId] \
+  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
+  --tags <tag1,tag2> --workflows create-spec --source "[functionId] / Gate 4"
+```
+
+Category khác hữu ích ở đây: `00.Shared/glossary` (thuật ngữ JP↔VN↔EN mới xác nhận — flat, không cần `--function-id`), `01.Lessons/ba` (bài học khi làm spec), `00.Shared/decisions` (quyết định đặc tả). Bỏ qua bước này nếu không có gì thực sự mới. Nếu `ak memory draft` báo trùng, đừng tạo bản mới — báo cho BA để họ quyết định sửa bản cũ.
+
+#### Bước 8: Submit AK-Docs lên remote qua Merge Request
+
+Sau khi Gate 4 đã APPROVED (UC Spec hoàn thành):
+
+1. Soạn title + description cho Merge Request (tóm tắt UC Spec vừa hoàn thành, link ticket gốc), hiển thị cho BA xem trước.
+2. Hỏi BA: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
+   - BA đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
+   - BA từ chối → dừng, để BA tự commit/tạo MR khi sẵn sàng
+3. Thông báo BA: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng cho tài liệu, không phải BA tự merge.
+
+> ❌ Không tự thêm `--yes` khi chưa thấy BA gõ xác nhận rõ ràng trong hội thoại.
+
 ---
 
 ### Bản đồ Skills theo Gate
@@ -419,6 +485,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 - ❌ **KHÔNG** tiến Gate 3 khi vẫn còn câu hỏi Open
 - ❌ **KHÔNG chấp nhận APPROVED** ở Gate 1 hoặc Gate 2 khi còn bất kỳ câu hỏi nào trạng thái **Open** — từ chối và hiển thị danh sách câu hỏi cần trả lời
 - ✅ **BẮT BUỘC** chạy Bước 0 ở Gate 1 — xác nhận `functionId` và thư mục đầu ra trước khi làm bất cứ điều gì
+- ✅ **BẮT BUỘC** chạy Bước 0.5 ở Gate 1 — đảm bảo AK-Docs đang ở branch `feature/[functionId]/[taskId]` trước khi ghi file đầu tiên
 - ✅ **BẮT BUỘC** đọc skill từ `.claude/skills/ba-skills/` — không suy luận từ bộ nhớ
 - ✅ **BẮT BUỘC** invoke `gate-review` cuối mỗi gate và chờ APPROVED
 - ✅ **BẮT BUỘC** mọi thẻ tương tác trong HTML có `id` duy nhất

package/custom/templates/shared/create-testcase-workflow.md

@@ -7,6 +7,26 @@
 
 ---
 
+### Pre-flight BẮT BUỘC — Đồng bộ Source & Docs (đầu MỖI Gate)
+
+> Áp dụng cho **cả 4 Gate** bên dưới — không chỉ Gate 1. Chạy đủ các bước sau **trước khi** thực hiện bất kỳ hành động nào khác của gate đó.
+
+1. **Sync repo source (bên trong, không phải AK-Docs/Shared-Docs):** xác định thư mục repo source liên quan (field `repo` trong context, hoặc repo duy nhất mở trong workspace) → `cd` vào đó → chạy `git status --porcelain`; nếu working tree sạch, chạy `git pull --ff-only`. Nếu có thay đổi chưa commit, branch diverged, hoặc không có remote tracking branch → bỏ qua pull (không phải lỗi).
+2. **Sync `AK-Docs/`:** `cd` vào `AK-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+3. **Sync `Shared-Docs/`:** `cd` vào `Shared-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+4. Sau khi xong, `cd` quay lại thư mục làm việc ban đầu trước khi tiếp tục các bước khác của gate.
+
+Nếu `AK-Docs/` hoặc `Shared-Docs/` chưa tồn tại tại workspace root, hoặc không phải git repo → bỏ qua bước tương ứng, không cảnh báo.
+
+**Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** → **KHÔNG dừng workflow** — hiển thị cảnh báo và tiếp tục gate với dữ liệu local hiện có:
+
+```
+⚠️ CẢNH BÁO: Không thể pull [tên repo] — [lý do lỗi].
+→ Đang tiếp tục Gate [N] với dữ liệu local hiện tại, có thể chưa mới nhất.
+```
+
+---
+
 ### QA Skills
 
 Các skill sau đây được cài tự động vào `.claude/skills/test-skills/` khi chạy `ak init` hoặc `ak up`.
@@ -96,6 +116,8 @@ Sẵn sàng thực thi kiểm thử
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 0):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra
 
 **Xác định `functionId` (BẮT BUỘC):**
@@ -133,6 +155,20 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
      → Bắt đầu Gate 1...
      ```
 
+#### Bước 0.5: Đảm bảo đang làm việc trên branch riêng của task (AK-Docs)
+
+Trước khi ghi bất kỳ file nào vào `03.Testing/`, đảm bảo AK-Docs đang ở branch riêng của task này, không phải `main` (mọi thay đổi `AK-Docs` phải qua branch + Merge Request, PM duyệt cuối cùng trước khi merge vào `main`):
+
+1. Lấy `taskId` từ trường `taskId` trong `.aiflow/context/current.json`.
+2. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`).
+3. Nếu **chưa** ở branch `feature/[functionId]/[taskId]`:
+   - Hỏi QA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[functionId]/[taskId]` từ `main` — đồng ý không?"
+   - QA đồng ý → chạy `ak docs branch [functionId] [taskId] --yes`
+   - QA từ chối → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (QA tự quản lý branch)
+4. Nếu **đã** ở đúng branch (ví dụ resume từ session trước) → bỏ qua, tiếp tục.
+
+> ❌ Không tự thêm `--yes` khi chưa thấy QA gõ xác nhận rõ ràng trong hội thoại.
+
 #### Bước 1: Đọc và tổng hợp đầu vào
 - Đọc `.aiflow/context/current.json` — tiêu đề, mô tả, acceptance criteria, liên kết tài liệu
 - Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
@@ -216,6 +252,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 1: Đọc artifact đầu vào
 - Đọc `[functionId]_01_Requirement_Analysis_Result.md` — nắm toàn bộ 16 mục, Risk Matrix, Business Rules
 
@@ -287,6 +325,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 1: Đọc template và quy ước bắt buộc
 - **READ template:** `.claude/skills/test-skills/template/testcase-template.md` — **BẮT BUỘC** tuân thủ 100%
 - **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md`
@@ -376,6 +416,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+
 #### Bước 1: Review nội dung và đánh giá bao phủ
 - **READ skill:** `.claude/skills/test-skills/categories/00-core/00.04.testcase-review.md`
 - **READ skill:** `.claude/skills/test-skills/categories/99-review/99.01.coverage-review.md`
@@ -443,6 +485,30 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 > **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
 
+#### Bước 7.5: Retrospect + đề xuất memory draft
+
+Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên trước:** nếu review ở Bước 7 từng phát hiện Major/Critical issue phải sửa lại, đó là bài học giá trị nhất — đảm bảo có draft cho đúng issue đó. Sau đó mới thêm lỗi/bẫy môi trường gặp khi test, business rule cần làm rõ thêm. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/internal/Memory-Architecture-v1.0.md`):
+
+```
+ak memory draft --category 01.Lessons/qa --function-id [functionId] \
+  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
+  --tags <tag1,tag2> --workflows create-testcase --source "[functionId] / Gate 4"
+```
+
+Category khác hữu ích ở đây: `00.Shared/domain` (business rule phát hiện khi thiết kế test), `00.Shared/glossary` (thuật ngữ — flat, không cần `--function-id`). Bỏ qua bước này nếu không có gì thực sự mới. Nếu `ak memory draft` báo trùng, đừng tạo bản mới — báo cho QA để họ quyết định sửa bản cũ.
+
+#### Bước 8: Submit AK-Docs lên remote qua Merge Request
+
+Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):
+
+1. Soạn title + description cho Merge Request (tóm tắt bộ Test Case vừa hoàn thành, sign-off status, link ticket gốc), hiển thị cho QA xem trước.
+2. Hỏi QA: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
+   - QA đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
+   - QA từ chối → dừng, để QA tự commit/tạo MR khi sẵn sàng
+3. Thông báo QA: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng cho tài liệu, không phải QA tự merge.
+
+> ❌ Không tự thêm `--yes` khi chưa thấy QA gõ xác nhận rõ ràng trong hội thoại.
+
 ---
 
 ### Bản đồ Skills theo Gate
@@ -463,6 +529,7 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - ❌ **KHÔNG** sinh `04_Final_Result.md` mà thiếu `[functionId]_TestCase.md` (hoặc ngược lại)
 - ❌ **KHÔNG** tiến gate tiếp theo khi còn issue Critical hoặc Major chưa giải quyết
 - ✅ **BẮT BUỘC** chạy Bước 0 ở Gate 1 — xác nhận `functionId` và thư mục đầu ra trước khi làm bất cứ điều gì
+- ✅ **BẮT BUỘC** chạy Bước 0.5 ở Gate 1 — đảm bảo AK-Docs đang ở branch `feature/[functionId]/[taskId]` trước khi ghi file đầu tiên
 - ✅ **BẮT BUỘC** đọc skill từ `.claude/skills/test-skills/` — không suy luận từ bộ nhớ
 - ✅ **BẮT BUỘC** invoke `gate-review` cuối mỗi gate và chờ APPROVED
 - ✅ **BẮT BUỘC** tuân thủ 100% `testcase-template.md` ở Gate 3 và Gate 4