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

package/commands/validate-traces.tmpl

@@ -1,11 +1,11 @@
 # /validate-traces — Traceability Coverage Matrix
 
-Read-only check of coverage between specs, code, and tests — including PRD version drift.
+Check read-only độ phủ giữa spec, code, và test — gồm cả PRD version drift.
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a domain name or specific UC-ID from `$ARGUMENTS`. There is no single file to resolve — the command scans multiple directories.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một tên domain hoặc UC-ID cụ thể từ `$ARGUMENTS`. Không có một file đơn để phân giải — lệnh quét nhiều thư mục.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -16,89 +16,89 @@ Read-only check of coverage between specs, code, and tests — including PRD ver
 
 ### Step 0 — Umbrella Mode Detection
 
-Check whether `services` array exists in `project-context.yaml`.
+Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không.
 
-**If `services` exists (umbrella mode):**
-- Resolve the trace dir(s):
-  - **If `setup.spec_source` is set (consolidated trace):** `all_trace_dirs = [ {spec_source}/.trace ]` — a **single** authoritative location in the spec repo. Scenarios carry their owning service via the `@trace.service` field, so no per-service split is needed. This is the common case.
-  - **Else (no spec_source — legacy per-service trace):** one dir per service — `services[N].trace_dir` if set, else `{services[N].path}/.trace`; `all_trace_dirs = [ dir1, dir2, … ]`, tagged by service name on read.
-- Step 1 reads TSVs from `all_trace_dirs`.
-- **Resolve the Living Docs home (generated report location):**
-  - If `setup.spec_source` is set → `living_docs_dir = {spec_source}/.living-docs`
-    *(the shared specs module — mounted inside every service/umbrella workspace, so the panel resolves it no matter which submodule the dev is standing in)*
-  - Else (umbrella without a separate spec repo) → `living_docs_dir = .living-docs` at umbrella root
-- **Resolve the panel mirror:** `panel_mirror = ./.trace` at the **current workspace root** (wherever this command runs). The VS Code panel reads `.trace/trace-report.json` from the open workspace — writing the report here is what makes the view non-empty when a dev opens a service submodule directly.
+**Nếu `services` tồn tại (umbrella mode):**
+- Phân giải trace dir:
+  - **Nếu `setup.spec_source` được set (consolidated trace):** `all_trace_dirs = [ {spec_source}/.trace ]` — một vị trí authoritative **duy nhất** trong spec repo. Scenario mang service sở hữu qua field `@trace.service`, nên không cần tách theo service. Đây là trường hợp phổ biến.
+  - **Else (không có spec_source — legacy per-service trace):** một dir mỗi service — `services[N].trace_dir` nếu set, else `{services[N].path}/.trace`; `all_trace_dirs = [ dir1, dir2, … ]`, gắn tag tên service khi đọc.
+- Step 1 đọc TSV từ `all_trace_dirs`.
+- **Phân giải Living Docs home (vị trí report sinh ra):**
+  - Nếu `setup.spec_source` được set → `living_docs_dir = {spec_source}/.living-docs`
+    *(specs module dùng chung — mount trong mọi service/umbrella workspace, nên panel phân giải nó bất kể dev đứng ở submodule nào)*
+  - Else (umbrella không có spec repo riêng) → `living_docs_dir = .living-docs` ở umbrella root
+- **Phân giải panel mirror:** `panel_mirror = ./.trace` ở **gốc workspace hiện tại** (nơi lệnh chạy). Panel VS Code đọc `.trace/trace-report.json` từ workspace đang mở — ghi report ở đây là cái làm view không rỗng khi dev mở một service submodule trực tiếp.
 
-**If no `services` key (single-service mode):**
+**Nếu không có key `services` (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
-- No umbrella sync needed
+- Không cần umbrella sync
 
 ---
 
-### Step 1 — Load TSV data
+### Step 1 — Nạp dữ liệu TSV
 
-**Umbrella mode:** read all `{trace_dir}/**/*.tsv` files from every dir in `all_trace_dirs`. For each TSV, tag its rows with the originating service name.
+**Umbrella mode:** đọc tất cả file `{trace_dir}/**/*.tsv` từ mọi dir trong `all_trace_dirs`. Với mỗi TSV, gắn tag row với tên service gốc.
 
-**Single-service mode:** read all `{paths.trace_dir}/{domain}/**/*.tsv` files matching the target domain (or `{paths.trace_dir}/**/*.tsv` for all domains if no domain filter).
+**Single-service mode:** đọc tất cả file `{paths.trace_dir}/{domain}/**/*.tsv` khớp domain target (hoặc `{paths.trace_dir}/**/*.tsv` cho mọi domain nếu không có domain filter).
 
-Each file gives the persisted trace state for that UC.
+Mỗi file cho trace state đã lưu của UC đó.
 
-**If no `.tsv` files found** in any of the trace dirs:
-- Scan all `{paths.specs_dir}/**/*.feature` files in the target domain to build an in-memory list of all scenarios.
-- Treat all scenarios as `UNTRACKED` (no code generated yet).
-- Print: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
-- Suggest: "Run `/generate-bdd {prd-file}` to initialize trace state, or `/generate-code {feature-file}` to generate code."
-- **Skip Steps 2–6 entirely.** Proceed directly to Step 7 using this in-memory state — do NOT abort.
+**Nếu không tìm thấy file `.tsv` nào** trong bất kỳ trace dir nào:
+- Quét tất cả file `{paths.specs_dir}/**/*.feature` trong domain target để dựng list in-memory mọi scenario.
+- Coi mọi scenario là `UNTRACKED` (chưa sinh code).
+- In: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
+- Đề xuất: "Run `/generate-bdd {prd-file}` to initialize trace state, or `/generate-code {feature-file}` to generate code."
+- **Bỏ qua hoàn toàn Step 2–6.** Đi thẳng tới Step 7 dùng state in-memory này — ĐỪNG abort.
 
-### Step 2 — Reconcile with current `.feature` files
+### Step 2 — Reconcile với file `.feature` hiện tại
 
-For each `.tsv` row, read the corresponding `.feature` file and get the **current** `@trace.sc_version` for that SC.
-If the `.feature` SC version differs from the `.tsv` `spec_ver` → update `spec_ver` in memory (will be written back).
+Với mỗi row `.tsv`, đọc file `.feature` tương ứng và lấy `@trace.sc_version` **hiện tại** cho SC đó.
+Nếu version SC trong `.feature` khác `spec_ver` của `.tsv` → cập nhật `spec_ver` trong memory (sẽ ghi lại).
 
-Also detect SCs present in `.feature` but missing from `.tsv` → add as new rows with `status: UNTRACKED`.
+Cũng phát hiện SC có trong `.feature` nhưng thiếu trong `.tsv` → thêm row mới với `status: UNTRACKED`.
 
-### Step 3 — Compute `status` per scenario
+### Step 3 — Tính `status` theo từng scenario
 
-Apply rules in priority order:
+Áp dụng quy tắc theo thứ tự ưu tiên:
 
-| Rule | Status | Condition |
+| Rule | Status | Điều kiện |
 |------|--------|-----------|
-| 1 | `UNTRACKED` | `implemented_by == —` (no code generated yet) |
+| 1 | `UNTRACKED` | `implemented_by == —` (chưa sinh code) |
 | 2 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
-| 3 | `DRIFT` | `spec_ver != gen_ver` (scenario updated since last codegen) |
-| 4 | `OK` | all of: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
+| 3 | `DRIFT` | `spec_ver != gen_ver` (scenario cập nhật từ lần codegen trước) |
+| 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
 
 ### Step 4 — PRD version drift check
 
-For each UC, compare:
-- Current PRD `| **Version** |` from `{paths.specs_dir}/{domain}/{prd-slug}/prd.md`
-- `prd_version` stored in `.tsv` (version at time of BDD generation)
-- `@trace.prd_version` in the code files implementing that UC
+Với mỗi UC, so:
+- PRD `| **Version** |` hiện tại từ `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md`
+- `prd_version` lưu trong `.tsv` (version tại thời điểm sinh BDD)
+- `@trace.prd_version` trong các file code implement UC đó
 
-If any layer is behind current PRD version → flag `PRD_DRIFT` and extract changelog entries since that version.
+Nếu layer nào sau version PRD hiện tại → gắn cờ `PRD_DRIFT` và trích các changelog entry kể từ version đó.
 
 ### Step 5 — Tech-doc revision drift check
 
-For each UC that has a tech-doc, compare the stored revision against the current doc — for **both** tech-doc kinds:
+Với mỗi UC có tech-doc, so revision đã lưu vs doc hiện tại — cho **cả hai** loại tech-doc:
 
-- **BE contract:** `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` vs `tech_doc_revision` in `.tsv`.
-  Code generated from an older revision → flag `TECHDOC_DRIFT`.
-- **FE tech-design:** `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` vs `fe_tech_doc_revision` in `.tsv` (per platform row).
-  FE code generated from an older revision → flag `FE_TECHDOC_DRIFT`.
+- **BE contract:** `@trace.revision` trong `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` vs `tech_doc_revision` trong `.tsv`.
+  Code sinh từ revision cũ hơn → gắn cờ `TECHDOC_DRIFT`.
+- **FE tech-design:** `@trace.revision` trong `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` vs `fe_tech_doc_revision` trong `.tsv` (theo từng row platform).
+  Code FE sinh từ revision cũ hơn → gắn cờ `FE_TECHDOC_DRIFT`.
 
-Skip whichever kind has no doc / no stored revision (`—`).
+Skip loại nào không có doc / không có revision đã lưu (`—`).
 
-### Step 6 — Write status back to TSV
+### Step 6 — Ghi status lại vào TSV
 
-*Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
+*Bỏ qua step này nếu không có file TSV nào (đã xử lý bởi path no-TSV của Step 1).*
 
-For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
-Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (owned by `/qc-run-test` + `/report-bug`); this command only reads them for the report.
+Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
+**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
 
-### Step 7 — Compute dashboard aggregates
+### Step 7 — Tính aggregate cho dashboard
 
 ```
-total_prds       = count distinct PRD files in {paths.specs_dir}/{domain}/*/prd.md
+total_prds       = count distinct PRD files in {paths.specs_dir}/{domain}/*/*.md  (file .md ở gốc mỗi feature folder = PRD)
 approved_prds    = PRDs with | Status | approved
 total_ucs        = count distinct UC-IDs across all .tsv files
 approved_ucs     = UCs with uc_status == approved
@@ -122,13 +122,13 @@ qc_not_run       = rows where qc_status in (not_run, —)
 # shown alongside — never merged with — dev_selftest.
 waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
 waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify
-# qc_owner + qc_blocked_by answer "case nào đang chờ ai" — surface as a "Waiting on" column.
+# qc_owner + qc_blocked_by trả lời "case nào đang chờ ai" — surface as a "Waiting on" column.
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/*/tech-docs/
 ```
 
-### Step 8 — Write JSON report
+### Step 8 — Ghi JSON report
 
-Write `{paths.trace_dir}/trace-report.json` (overwrite if exists). This file is the single source of truth for web dashboards — it contains the full snapshot at the time `/validate-traces` was last run.
+Ghi `{paths.trace_dir}/trace-report.json` (ghi đè nếu tồn tại). File này là source of truth duy nhất cho web dashboard — nó chứa snapshot đầy đủ tại thời điểm `/validate-traces` chạy lần cuối.
 
 Schema:
 
@@ -258,45 +258,45 @@ Schema:
 ```
 
 **Rules:**
-- `implemented_by`: use `null` (not `"—"`) in JSON when no value
-- `test_count`: use integer `0` (not `"—"`) when no tests
-- `test_classes`: use `[]` (not `"—"`) when no test classes
-- `tech_doc_revision` / `fe_tech_doc_revision`: use integer; `0` if not yet generated
-- `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
-- Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
-- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `fe_tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
-- **Backward-compat:** older TSVs may be missing newer columns from the header — treat any absent column as its empty value (do not error): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`. The next `/generate-bdd` re-gen upgrades the header to the current 22-column layout.
-
-### Step 8b — Living Docs Sync *(umbrella mode only)*
-
-*Skip this step in single-service mode.*
-
-**With `spec_source` set,** the authoritative trace TSVs already live in **one** place —
-`{spec_source}/.trace/` (committed in the spec repo). There is **no per-service merge**:
-each scenario row carries its owning service via `@trace.service`. This step just
-(re)generates the report and refreshes the local panel.
-
-1. **Write the report** to `{living_docs_dir}/trace-report.json` (`mkdir -p` first) — built
-   directly from `{spec_source}/.trace/*.tsv`, with a `"service"` field per scenario row and
-   the summary aggregates. *(Legacy no-`spec_source` umbrellas still merge every per-service
-   `trace-report.json` into one document, namespaced by service.)*
-
-2. **Mirror to the panel location** `{panel_mirror}` (`./.trace` at the current workspace
-   root) so a dev who opened *this* repo sees data immediately: copy
-   `{living_docs_dir}/trace-report.json` (+ the `{UC-ID}.tsv` files) → `{panel_mirror}/`.
-   If `panel_mirror` already resolves to `{spec_source}/.trace`, skip.
-
-3. **Print sync summary:**
+- `implemented_by`: dùng `null` (không phải `"—"`) trong JSON khi không có giá trị
+- `test_count`: dùng integer `0` (không phải `"—"`) khi không có test
+- `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
+- `tech_doc_revision` / `fe_tech_doc_revision`: dùng integer; `0` nếu chưa sinh
+- `code_coverage_pct` / `test_coverage_pct`: làm tròn về integer gần nhất (0–100)
+- Luôn ghi vào `{paths.trace_dir}/trace-report.json` bất kể domain filter — nếu có domain filter, chỉ gồm các PRD đó trong `prds[]` nhưng ghi domain vào field `domain`
+- **TSV `"—"` mapping**: khi đọc file TSV, map giá trị dash sang kiểu JSON: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `fe_tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
+- **Backward-compat:** TSV cũ có thể thiếu cột mới hơn trong header — coi cột vắng nào là giá trị rỗng của nó (đừng báo lỗi): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`. Lần `/generate-bdd` gen lại tiếp theo nâng header lên layout 22 cột hiện tại.
+
+### Step 8b — Living Docs Sync *(chỉ umbrella mode)*
+
+*Bỏ qua step này ở single-service mode.*
+
+**Với `spec_source` được set,** các trace TSV authoritative đã sống ở **một** chỗ —
+`{spec_source}/.trace/` (committed trong spec repo). **Không có merge theo service**:
+mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
+(re)generate report và làm mới panel local.
+
+1. **Ghi report** vào `{living_docs_dir}/trace-report.json` (`mkdir -p` trước) — dựng
+   trực tiếp từ `{spec_source}/.trace/*.tsv`, với field `"service"` mỗi scenario row và
+   các summary aggregate. *(Umbrella legacy không-`spec_source` vẫn merge mọi `trace-report.json`
+   theo service thành một document, namespace theo service.)*
+
+2. **Mirror tới panel location** `{panel_mirror}` (`./.trace` ở gốc workspace hiện tại)
+   để dev mở *repo này* thấy data ngay: copy
+   `{living_docs_dir}/trace-report.json` (+ các file `{UC-ID}.tsv`) → `{panel_mirror}/`.
+   Nếu `panel_mirror` đã phân giải về `{spec_source}/.trace`, skip.
+
+3. **In sync summary:**
    ```
    Living Docs → {living_docs_dir}/trace-report.json  ({total} scenarios across {S} services)
    Trace (authoritative) → {spec_source}/.trace/   (committed in spec repo)
    Panel mirror → {panel_mirror}/trace-report.json  (current workspace)
    ```
 
-> **Note:** the committed, authoritative trace state is `{spec_source}/.trace/*.tsv` (in the
-> spec repo — one place for the PM). The report (`.living-docs/`) and the panel mirror
-> (`./.trace` at a workspace that is not the spec repo) are **generated** — gitignore them;
-> they are regenerated by `/validate-traces` or `/sync`.
+> **Lưu ý:** trace state committed, authoritative là `{spec_source}/.trace/*.tsv` (trong
+> spec repo — một chỗ cho PM). Report (`.living-docs/`) và panel mirror
+> (`./.trace` ở workspace không phải spec repo) là **sinh ra** — gitignore chúng;
+> chúng được regenerate bởi `/validate-traces` hoặc `/sync`.
 
 ## Output
 
@@ -321,28 +321,28 @@ each scenario row carries its owning service via `@trace.service`. This step jus
 | {UC}-UC2    | SC1  | {title...}                   | v1.0  | v1.0  | ✅ {Controller.fn}   | —              | GAP      |
 
 Drift Detail:
-  {UC}-UC1-SC2 — spec v1.1 but code generated from v1.0
-    → Re-run: /generate-code {UC-ID}
+  {UC}-UC1-SC2 — spec v1.1 nhưng code sinh từ v1.0
+    → Chạy lại: /generate-code {UC-ID}
 
 PRD Version Drift:
-  {UC}-UC2 — code at PRD v1.0, PRD now at v1.2
-    Changes since v1.0:
+  {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2
+    Thay đổi kể từ v1.0:
       v1.1: {changelog entry}
       v1.2: {changelog entry}
     → /generate-bdd {prd-file} then /generate-code {UC-ID}
 
 Tech-Doc Revision Drift:
-  {UC}-UC3 — code generated from tech-doc revision 2, now at revision 4
-    → Review tech-doc changes then /generate-code {UC-ID}
+  {UC}-UC3 — code sinh từ tech-doc revision 2, giờ ở revision 4
+    → Review thay đổi tech-doc rồi /generate-code {UC-ID}
 
 Recommendations:
-  - /generate-code {UC-ID}      for DRIFT and UNTRACKED scenarios
-  - /dev-gen-test {UC-ID}     for GAP (missing tests)
-  - /generate-bdd {prd-file}    for PRD version drift
+  - /generate-code {UC-ID}      cho scenario DRIFT và UNTRACKED
+  - /dev-gen-test {UC-ID}     cho GAP (thiếu test)
+  - /generate-bdd {prd-file}    cho PRD version drift
 
-[Umbrella mode only]
+[Chỉ umbrella mode]
 Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)
 Panel mirror          → {panel_mirror}/trace-report.json  (current workspace)
-  Tip: run /validate-traces (or /sync) after each codegen session to refresh the panel.
-  Both are generated mirrors — do not commit (.living-docs/ + .trace/ in .gitignore).
+  Tip: chạy /validate-traces (hoặc /sync) sau mỗi phiên codegen để làm mới panel.
+  Cả hai là mirror sinh ra — đừng commit (.living-docs/ + .trace/ trong .gitignore).
 ```

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.14.0
+0.14.2