@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/core/commands/sync.md

@@ -1,9 +1,9 @@
 # /sync — Sync & Refresh Umbrella Project
 
-One command for both **first-time setup** and **daily update** of an umbrella repo with git submodules.
-Safe to run repeatedly — detects what needs to be done automatically.
+Một lệnh cho cả **setup lần đầu** lẫn **cập nhật hằng ngày** một umbrella repo có git submodule.
+An toàn chạy lặp lại — tự phát hiện cần làm gì.
 
-**Optional argument:** `/sync [spec-branch]` — branch of the spec submodule to pull (e.g. `/sync develop`). If omitted, the branch is resolved automatically (see Step 0-D).
+**Argument tuỳ chọn:** `/sync [spec-branch]` — branch của spec submodule để pull (vd `/sync develop`). Nếu bỏ, branch được phân giải tự động (xem Step 0-D).
 
 ---
 
@@ -11,54 +11,54 @@ Safe to run repeatedly — detects what needs to be done automatically.
 
 **A. Git repo check**
 
-Verify current directory is inside a git repo. If not → stop:
+Xác minh thư mục hiện tại nằm trong git repo. Nếu không → dừng:
 ```
 ❌ Not a git repository. Open Claude Code from umbrella root and retry.
 ```
 
-**B. Read project config early**
+**B. Đọc project config sớm**
 
-Read `.agent/project-context.yaml` before running any git commands. Extract:
-- `setup.spec_source` → path of the spec submodule (e.g., `"my-project-specs"`)
-- `services` → map of domain → `{path, module, ...}` for each service submodule
+Đọc `.agent/project-context.yaml` trước khi chạy lệnh git nào. Trích:
+- `setup.spec_source` → path của spec submodule (vd `"my-project-specs"`)
+- `services` → map domain → `{path, module, ...}` cho mỗi service submodule
 
-This is needed to differentiate spec vs service submodules in Step 1.
+Cần cái này để phân biệt spec vs service submodule ở Step 1.
 
-If `.agent/project-context.yaml` does not exist → warn and set `spec_source = null`, `services = {}`.
+Nếu `.agent/project-context.yaml` không tồn tại → cảnh báo và set `spec_source = null`, `services = {}`.
 
 **C. Submodule status scan**
 
-Run `git submodule status --recursive` and classify each entry by its first character:
+Chạy `git submodule status --recursive` và phân loại mỗi entry theo ký tự đầu:
 
-| Char | Meaning | Action |
+| Char | Ý nghĩa | Hành động |
 |------|---------|--------|
-| `-` | Not initialized | → **Setup mode** |
-| ` ` | Matches recorded pointer | → OK |
-| `+` | Ahead of recorded pointer (local advance uncommitted) | → warn per submodule |
+| `-` | Chưa init | → **Setup mode** |
+| ` ` | Khớp pointer đã ghi | → OK |
+| `+` | Ahead của pointer đã ghi (local advance chưa commit) | → cảnh báo từng submodule |
 | `U` | Merge conflict | → **STOP** |
 
-If **any** entry has `U`:
+Nếu **bất kỳ** entry nào có `U`:
 ```
 ❌ Merge conflict in submodule: {path}
    Resolve manually before running /sync:
      cd {path} && git status
 ```
 
-If **any** entry has `+` (checked-out commit differs from the recorded pointer):
+Nếu **bất kỳ** entry nào có `+` (commit đang checkout khác pointer đã ghi):
 ```
 ℹ️ {path} is ahead of the umbrella's recorded pointer.
    /sync classifies it in Step 1b — if you're on a branch there, it stays untouched.
 ```
-Do not act on `+` here — Step 1b decides the right handling per submodule.
+Đừng xử lý `+` ở đây — Step 1b quyết định cách xử lý đúng cho từng submodule.
 
-Print detected mode: `Mode: Setup (first-time init)` or `Mode: Update (sync latest)`.
+In mode phát hiện: `Mode: Setup (first-time init)` hoặc `Mode: Update (sync latest)`.
 
 ---
 
 ## Step 1 — Umbrella Pull
 
-Note the current umbrella branch first (this is what `git pull` updates):
-`git rev-parse --abbrev-ref HEAD` → store as `umbrella_branch` and display it.
+Ghi branch umbrella hiện tại trước (đây là cái `git pull` cập nhật):
+`git rev-parse --abbrev-ref HEAD` → lưu thành `umbrella_branch` và hiển thị.
 
 ```bash
 # 1. Pull latest umbrella (includes updated submodule pointer records)
@@ -74,15 +74,15 @@ git submodule sync --recursive
 git submodule update --init {paths that were '-' in Step 0-C}
 ```
 
-If `git pull` exits non-zero → print the error and stop with `❌`.
+Nếu `git pull` exit khác 0 → in lỗi và dừng với `❌`.
 
 ---
 
-## Step 1b — Classify & Sync Each Submodule
+## Step 1b — Phân loại & Sync từng Submodule
 
-**The key idea:** `/sync` never imposes a branch on a submodule. It **inspects each submodule's current checkout** and respects it. This is how it knows which submodule you are working in vs which are passive dependencies.
+**Ý tưởng cốt lõi:** `/sync` không bao giờ áp một branch lên submodule. Nó **kiểm tra checkout hiện tại của từng submodule** và tôn trọng nó. Đây là cách nó biết submodule nào bạn đang làm vs cái nào là dependency thụ động.
 
-For each submodule (use `git submodule foreach` or iterate the paths), read its state:
+Với mỗi submodule (dùng `git submodule foreach` hoặc lặp các path), đọc state:
 
 ```bash
 # Inside each submodule:
@@ -90,30 +90,30 @@ git symbolic-ref --short -q HEAD   # → branch name, or empty/non-zero if DETAC
 git status --porcelain             # → non-empty means uncommitted local changes
 ```
 
-Classify into one of four cases and act accordingly:
+Phân loại vào một trong bốn case và xử lý tương ứng:
 
-| Case | Detected state | Action |
+| Case | State phát hiện | Hành động |
 |------|----------------|--------|
-| **Spec submodule** | `path == spec_source` | Advance to `spec_branch` (Step 1c below) |
-| **Active (on a branch)** | HEAD is a branch, not detached | **Do NOT checkout.** This is where you (or a teammate) are coding. Just `git -C {path} fetch` and report branch + ahead/behind. Leave the working tree exactly as-is. |
-| **Passive (detached, clean)** | Detached HEAD, no local changes | Safe to align to the umbrella's recorded pointer: `git submodule update {path}` |
-| **Dirty (uncommitted changes)** | `git status --porcelain` non-empty | **Never touch.** Warn: `⚠️ {path} has uncommitted changes — skipped. Commit or stash before syncing this submodule.` |
+| **Spec submodule** | `path == spec_source` | Advance tới `spec_branch` (Step 1c bên dưới) |
+| **Active (on a branch)** | HEAD là một branch, không detached | **KHÔNG checkout.** Đây là nơi bạn (hoặc đồng đội) đang code. Chỉ `git -C {path} fetch` và report branch + ahead/behind. Để working tree y nguyên. |
+| **Passive (detached, clean)** | Detached HEAD, không có thay đổi local | An toàn align về pointer đã ghi của umbrella: `git submodule update {path}` |
+| **Dirty (uncommitted changes)** | `git status --porcelain` non-empty | **Đừng đụng.** Cảnh báo: `⚠️ {path} has uncommitted changes — skipped. Commit or stash before syncing this submodule.` |
 
-> **Why this matters:** A blanket `git submodule update` checks every submodule out to a **detached HEAD** at the recorded pointer. If you have `feature/FEAT-01` checked out inside `user-service/` and are mid-work, that would silently move you off your branch. Classifying first protects your active work.
+> **Vì sao quan trọng:** Một `git submodule update` toàn bộ checkout mọi submodule về **detached HEAD** ở pointer đã ghi. Nếu bạn đang checkout `feature/FEAT-01` trong `user-service/` và đang làm dở, cái đó sẽ âm thầm chuyển bạn khỏi branch. Phân loại trước bảo vệ công việc đang làm của bạn.
 
 ---
 
-## Step 1c — Advance Spec Submodule *(only if `spec_source` is configured)*
+## Step 1c — Advance Spec Submodule *(chỉ khi `spec_source` được cấu hình)*
 
-The spec submodule is the one submodule we deliberately advance to a branch HEAD (PO pushes specs continuously).
+Spec submodule là submodule duy nhất ta cố ý advance tới một branch HEAD (PO push spec liên tục).
 
-**Resolve the spec branch** (now that the submodule is initialized), in priority order:
+**Phân giải spec branch** (giờ submodule đã init), theo thứ tự ưu tiên:
 
-1. **Command argument** — if `$ARGUMENTS` contains a branch name → use it (one-off override)
-2. **`.gitmodules` config** — `git config -f .gitmodules --get submodule.{spec_source}.branch`. If set → use it (team's committed default)
-3. **Remote default** — else the spec repo's default branch: `git -C {spec_source} rev-parse --abbrev-ref origin/HEAD` (strip the `origin/` prefix)
+1. **Command argument** — nếu `$ARGUMENTS` chứa tên branch → dùng nó (override một lần)
+2. **`.gitmodules` config** — `git config -f .gitmodules --get submodule.{spec_source}.branch`. Nếu set → dùng nó (default committed của team)
+3. **Remote default** — else branch default của spec repo: `git -C {spec_source} rev-parse --abbrev-ref origin/HEAD` (bỏ prefix `origin/`)
 
-Store as `spec_branch` + `spec_branch_source` (argument | .gitmodules | remote-default). If it fell through to remote-default with nothing pinned, add this hint to the output:
+Lưu thành `spec_branch` + `spec_branch_source` (argument | .gitmodules | remote-default). Nếu nó rơi xuống remote-default mà không có gì pin, thêm hint này vào output:
 ```
 ℹ️ Spec submodule branch not pinned in .gitmodules — using remote default '{spec_branch}'.
    To pin it for the whole team:
@@ -121,7 +121,7 @@ Store as `spec_branch` + `spec_branch_source` (argument | .gitmodules | remote-d
      git add .gitmodules && git commit -m "chore: pin spec submodule branch"
 ```
 
-Then check it is safe: if the spec submodule has uncommitted changes → warn and skip (devs should treat specs as read-only). Otherwise use an **explicit checkout** (not bare `--remote`) so the branch is unambiguous:
+Rồi kiểm tra an toàn: nếu spec submodule có thay đổi chưa commit → cảnh báo và skip (dev nên coi spec là read-only). Ngược lại dùng **explicit checkout** (không phải `--remote` trần) để branch rõ ràng:
 
 ```bash
 cd {spec_source}
@@ -131,37 +131,37 @@ git pull origin {spec_branch}
 cd -                              # back to umbrella root
 ```
 
-Print: `Spec submodule {spec_source}: pulled branch '{spec_branch}' (source: {spec_branch_source})`
+In: `Spec submodule {spec_source}: pulled branch '{spec_branch}' (source: {spec_branch_source})`
 
-> **Why not `--remote` for service submodules?** Service submodules are version-locked by the umbrella's recorded pointer — this is intentional so all devs work from the same commit. `--remote` would bypass this lock and create uncommitted pointer drift. The spec submodule is the exception: PO pushes continuously, so we advance it to a branch HEAD — but we do it with an explicit `checkout {spec_branch}` rather than `--remote` so it never silently follows the wrong branch.
+> **Vì sao không `--remote` cho service submodule?** Service submodule bị version-lock bởi pointer đã ghi của umbrella — cố ý để mọi dev làm từ cùng commit. `--remote` sẽ bỏ qua lock này và tạo pointer drift chưa commit. Spec submodule là ngoại lệ: PO push liên tục, nên ta advance nó tới branch HEAD — nhưng làm bằng explicit `checkout {spec_branch}` thay vì `--remote` để nó không bao giờ âm thầm theo sai branch.
 
-If `git pull` or `git submodule update` exits non-zero → print the error and stop with `❌`.
+Nếu `git pull` hoặc `git submodule update` exit khác 0 → in lỗi và dừng với `❌`.
 
-Collect from output:
-- Which submodules changed SHA
-- Which were already up to date
-- The spec submodule's `{old_sha}..{new_sha}` (needed by Step 1d)
+Thu từ output:
+- Submodule nào đổi SHA
+- Cái nào đã up to date
+- `{old_sha}..{new_sha}` của spec submodule (cần cho Step 1d)
 
 ---
 
-## Step 1d — Surface Tester/QC Feedback *(bug reports / scenario proposals / PRD change requests)*
+## Step 1d — Surface Feedback của Tester/QC *(bug report / scenario proposal / PRD change request)*
 
-Tester & QC `/report-bug`, `/propose-scenario` (incl. Case B PRD change requests) commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
+`/report-bug`, `/propose-scenario` của tester & QC (gồm cả PRD change request Case B) commit feedback vào spec repo. Step này cho PO/Dev biết cái gì tới trong **lần** pull này, để họ được thông báo qua routine bình thường. Nó phủ cả hai đối tượng:
 
-- **Dev/tester in umbrella** → feedback came in via the spec submodule advance (Step 1c)
-- **PO working directly in the spec repo** → feedback came in via the umbrella/current-repo `git pull` (Step 1)
+- **Dev/tester trong umbrella** → feedback tới qua spec submodule advance (Step 1c)
+- **PO làm trực tiếp trong spec repo** → feedback tới qua `git pull` của umbrella/current-repo (Step 1)
 
-Pick the repo + range that pulled the feedback:
-- Umbrella with `spec_source` → `REPO={spec_source}`, range = spec submodule `{old_sha}..{new_sha}`
-- Otherwise (running inside the spec repo itself) → `REPO=.`, range = the `git pull` `{old_sha}..{new_sha}` from Step 1
+Chọn repo + range đã pull feedback:
+- Umbrella có `spec_source` → `REPO={spec_source}`, range = spec submodule `{old_sha}..{new_sha}`
+- Ngược lại (chạy trong chính spec repo) → `REPO=.`, range = `{old_sha}..{new_sha}` của `git pull` từ Step 1
 
-If `feedback/` does not exist in REPO → skip silently.
+Nếu `feedback/` không tồn tại trong REPO → skip âm thầm.
 
 ```bash
 git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/ feedback/prd-change-requests/
 ```
 
-For each entry, read its title/summary + `State` and report. **Bug reports: surface only `State: Open`** as needing attention; list `Fixed`/`Closed` separately (or omit) so the PO/PM sees what's still pending:
+Với mỗi entry, đọc title/summary + `State` và report. **Bug report: chỉ surface `State: Open`** là cần chú ý; liệt kê `Fixed`/`Closed` riêng (hoặc bỏ) để PO/PM thấy cái gì còn pending:
 ```
 📥 New feedback (pulled this sync):
    Bug reports (open):
@@ -173,42 +173,42 @@ For each entry, read its title/summary + `State` and report. **Bug reports: surf
      FT-001-bulk-export.md  → new requirement, needs an AC  (waiting: PO)
 ```
 
-If none changed → print `📥 Feedback: none new this sync`.
+Nếu không có gì đổi → in `📥 Feedback: none new this sync`.
 
-If the reader is a PO/Dev, add a one-line nudge:
+Nếu người đọc là PO/Dev, thêm một dòng nudge:
 `→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal via /generate-bdd · or add an AC to the PRD.`
 
 ---
 
 ## Step 2 — Post-sync State Check
 
-Run `git status --short` and check for modified submodule entries (lines starting with ` M` where the path matches a submodule).
+Chạy `git status --short` và kiểm tra entry submodule bị modified (dòng bắt đầu bằng ` M` mà path khớp một submodule).
 
-If any submodule pointer changed (typically the spec submodule after `--remote`):
+Nếu pointer submodule nào đổi (thường là spec submodule sau `--remote`):
 ```
 ⚠️ Submodule pointer(s) updated — commit to lock new version into umbrella:
    git add {spec_source} && git commit -m "chore: sync {spec_source} to latest"
 ```
 
-If no changes → `✅ Umbrella state clean — no commit needed`.
+Nếu không có thay đổi → `✅ Umbrella state clean — no commit needed`.
 
 ---
 
 ## Step 3 — Bootstrap Service Configs
 
-*Skip if `services` is empty.*
+*Skip nếu `services` rỗng.*
 
-For each entry in `services[]`:
+Với mỗi entry trong `services[]`:
 
-**A. If `{service.path}/.agent/project-context.yaml` already exists:**
-- Read `conventions.test_command` and `conventions.build_command`
+**A. Nếu `{service.path}/.agent/project-context.yaml` đã tồn tại:**
+- Đọc `conventions.test_command` và `conventions.build_command`
 - Report: `✅ {service.path} — test: {test_command} | build: {build_command}`
 
-**B. If missing — auto-create it:**
+**B. Nếu thiếu — tự tạo:**
 
-1. Determine `module` from umbrella `services[].module` (authoritative). If not set, auto-detect from files in `{service.path}/`:
+1. Xác định `module` từ umbrella `services[].module` (authoritative). Nếu không set, auto-detect từ file trong `{service.path}/`:
 
-   | File present | Detected module | test_command | build_command |
+   | File có mặt | Module phát hiện | test_command | build_command |
    |---|---|---|---|
    | `pom.xml` | `java-spring` | `mvn test` | `mvn compile` |
    | `build.gradle` or `build.gradle.kts` | `java-spring` | `./gradlew test` | `./gradlew build` |
@@ -223,9 +223,9 @@ For each entry in `services[]`:
    | `requirements.txt` or `pyproject.toml` | `context-engineering` | `pytest tests/ -v` | `pip install -r requirements.txt` |
    | *(none matched)* | `unknown` | `{{TEST_COMMAND}}` | `{{BUILD_COMMAND}}` |
 
-2. Create `{service.path}/.agent/` directory if it does not exist.
+2. Tạo thư mục `{service.path}/.agent/` nếu chưa có.
 
-3. Write `{service.path}/.agent/project-context.yaml`:
+3. Ghi `{service.path}/.agent/project-context.yaml`:
 
    ```yaml
    # Auto-generated by /sync — review and update as needed
@@ -244,18 +244,18 @@ For each entry in `services[]`:
    ```
 
 4. Report:
-   - If auto-detected: `✅ Created {service.path}/.agent/project-context.yaml (module: {module}, test: {test_command})`
-   - If unknown/placeholder: `⚠️ Created {service.path}/.agent/project-context.yaml — fill in {{TEST_COMMAND}} and {{BUILD_COMMAND}}`
+   - Nếu auto-detect: `✅ Created {service.path}/.agent/project-context.yaml (module: {module}, test: {test_command})`
+   - Nếu unknown/placeholder: `⚠️ Created {service.path}/.agent/project-context.yaml — fill in {{TEST_COMMAND}} and {{BUILD_COMMAND}}`
 
 ---
 
 ## Step 4 — Check `.gitignore`
 
-Check the generated Living Docs mirrors are gitignored:
-- `.trace/` in the current repo's `.gitignore` (or `.git/info/exclude`)
-- `.living-docs/` in the **specs module's** `.gitignore` (when `setup.spec_source` is set)
+Kiểm tra các Living Docs mirror được sinh ra có gitignore không:
+- `.trace/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`)
+- `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set)
 
-If either is missing:
+Nếu thiếu cái nào:
 ```
 ⚠️ Living Docs mirrors not gitignored — they are generated, never commit them:
    echo ".trace/" >> .gitignore
@@ -264,20 +264,20 @@ If either is missing:
 
 ---
 
-## Step 5 — Refresh Living Docs *(umbrella mode only)*
+## Step 5 — Refresh Living Docs *(chỉ umbrella mode)*
 
-*Skip if `services` is empty.*
+*Skip nếu `services` rỗng.*
 
-**Resolve the Living Docs home (same rule as `/validate-traces`):**
-- `living_docs_dir` = `{spec_source}/.living-docs` if `setup.spec_source` is set, else `.living-docs` at umbrella root. *(The specs module is mounted inside every service workspace, so the panel resolves it even when a dev opens a single service submodule.)*
-- `panel_mirror` = `./.trace` at the current workspace root.
+**Phân giải Living Docs home (cùng quy tắc như `/validate-traces`):**
+- `living_docs_dir` = `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở umbrella root. *(Specs module được mount trong mọi service workspace, nên panel phân giải nó kể cả khi dev mở một service submodule đơn.)*
+- `panel_mirror` = `./.trace` ở gốc workspace hiện tại.
 
-1. For each service in `services[]`: if `{service.path}/.trace/` has `.tsv` files → copy them to `{living_docs_dir}/{service-name}/` (create dir if needed).
-2. Write merged `{living_docs_dir}/trace-report.json`:
-   - Aggregate each service's `.trace/` TSVs, add `"service"` field per row, recalc summary totals.
-3. **Mirror to the panel location:** copy `{living_docs_dir}/trace-report.json` (+ namespaced TSVs) → `{panel_mirror}/` so the panel in the currently-open repo is non-empty. Skip if `panel_mirror` already equals `living_docs_dir`.
+1. Với mỗi service trong `services[]`: nếu `{service.path}/.trace/` có file `.tsv` → copy chúng vào `{living_docs_dir}/{service-name}/` (tạo dir nếu cần).
+2. Ghi merged `{living_docs_dir}/trace-report.json`:
+   - Tổng hợp TSV `.trace/` của mỗi service, thêm field `"service"` mỗi row, tính lại summary totals.
+3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`.
 
-Print sync result:
+In kết quả sync:
 ```
 Living Docs → {living_docs_dir}/ synced  (canonical, specs module)
   {service-name}: {N} TSVs
@@ -285,55 +285,55 @@ Living Docs → {living_docs_dir}/ synced  (canonical, specs module)
 Panel mirror → {panel_mirror}/  (current workspace)
 ```
 
-If no `.trace/` dirs found → `Living Docs: no trace data yet — run /generate-bdd then /generate-code first.`
+Nếu không tìm thấy dir `.trace/` → `Living Docs: no trace data yet — run /generate-bdd then /generate-code first.`
 
 ---
 
-## Step 6 — Refresh Spec Manifest *(if spec_source present)*
+## Step 6 — Refresh Spec Manifest *(nếu có spec_source)*
 
-*Skip if `setup.spec_source` is absent.*
+*Skip nếu `setup.spec_source` vắng.*
 
-If `spec-manifest.yaml` exists OR `setup.spec_source` is configured:
-- Re-scan `{spec_source}/specs/**/prd.md` files
-- Rebuild `spec-manifest.yaml` mapping TICKET-ID → PRD/BDD/tech-doc paths
-- Print: `spec-manifest.yaml refreshed — {N} features indexed`
+Nếu `spec-manifest.yaml` tồn tại HOẶC `setup.spec_source` được cấu hình:
+- Re-scan các file PRD `{spec_source}/specs/*/*/*.md` (file `.md` ở gốc mỗi feature folder = PRD; tech-docs/design-spec `.md` nằm sâu hơn nên không bị quét nhầm)
+- Rebuild `spec-manifest.yaml` map TICKET-ID → path PRD/BDD/tech-doc
+- In: `spec-manifest.yaml refreshed — {N} features indexed`
 
 ---
 
 ## Output
 
-# Report Footer — Standard Command Output Format
+# Report Footer — Định dạng output chuẩn cho mọi lệnh
 
-Every command report must end with this standard footer section.
+Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
 
 ## Status Badge
 
-Choose one based on outcome:
-- `✅ Complete` — all steps succeeded, no issues found
-- `❌ Failed` — command could not complete due to a blocking error
-- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+Chọn một theo kết quả:
+- `✅ Complete` — mọi bước thành công, không có vấn đề
+- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
+- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
 
 ## Output Artifacts
 
-List every file created or modified by this command:
+Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
 ```
 Output Artifacts:
-  {created|updated} {file-path} ({brief description})
-  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({mô tả ngắn})
+  {created|updated} {file-path} ({mô tả ngắn})
 ```
 
-If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
 
 ## Pipeline Position
 
-Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
-so the user always sees where this command sits in the end-to-end flow:
+In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
+để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
 
 ```
 Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
 ```
 
-Find the current command in this phase legend and mark **its** phase in the map above:
+Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
 
 | Phase | Commands |
 |-------|----------|
@@ -347,61 +347,61 @@ Find the current command in this phase legend and mark **its** phase in the map
 | QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
 | Trace Audit | `/validate-traces` |
 
-For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
 `Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
 
-**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
-**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
+**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
 
-## Next Command Suggestion
+## Gợi ý lệnh tiếp theo
 
-Suggest the logical next command based on workflow phase:
+Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 
-| Current command         | Suggest next                                  |
+| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
 |-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` to start your first feature |
+| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
-| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
-| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
 | /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
-| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
+| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
+| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
 | /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
 | /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
-| /dev-smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
-| /fix-bug                | Create PR and link to ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
-| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
-| /learn                  | Continue working — lesson applies on next command |
-| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
-
-Format the footer as:
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
+| /dev-smoke-test             | Tạo PR và link tới ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
+| /fix-bug                | Tạo PR và link tới ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
+| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
+| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
+
+Định dạng footer như sau:
 ```
 ---
 Status   : {badge}
-{Output Artifacts block}
+{khối Output Artifacts}
 Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {suggested command with example arguments}
+           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {lệnh gợi ý kèm ví dụ tham số}
 ```
-*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
 ```