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

package/commands/sync.tmpl

@@ -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,18 +285,18 @@ 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 `{spec_source}/specs/**/prd.md`
+- Rebuild `spec-manifest.yaml` map TICKET-ID → path PRD/BDD/tech-doc
+- In: `spec-manifest.yaml refreshed — {N} features indexed`
 
 ---