@anhth2/spec-driven-dev-plugin 0.12.0 → 0.14.0

package/commands/validate-traces.md

@@ -168,7 +168,7 @@ If `services` section is present:
 - If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
 
 **2. Route to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
 - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
@@ -179,6 +179,7 @@ If `services` section is present:
 - Set `active_service = unresolved`
 
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs/bdd` — **always when `spec_source` is set.** All BDD (web/app/**system**) lives in the shared spec repo so every umbrella (FE/App/BE) reads the same scenarios; the FE tech-design gate + `/generate-code --phase=ui`/`--phase=integration` resolve the `system/` BDD here. *(Per-service `specs/bdd` only when there is no `spec_source`.)*
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
 - Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
@@ -188,8 +189,9 @@ If `services` section is present:
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, **all BDD (web/app/system)**, the **API contract (tech-docs)**, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** so every umbrella (FE/App/BE) and the PM read one source via `/sync`. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo (the PRD/BDD/design-spec/tech-docs there stay read-only for dev/QC — only PO edits those). In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
 
 ---
 
@@ -209,12 +211,12 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 |----------|--------|
 | `conventions.test_command` | service's `conventions.test_command` |
 | `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
-| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs/bdd`); ignore any service-level `specs_dir`** (BDD is cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
 - Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
 
@@ -400,16 +402,15 @@ Proceed to the next step of the calling command.
 Check whether `services` array exists in `project-context.yaml`.
 
 **If `services` exists (umbrella mode):**
-- Resolve the trace dir for each service:
-  - Use `services[N].trace_dir` if explicitly set
-  - Otherwise default to `{services[N].path}/.trace`
-- Set `all_trace_dirs = [ dir1, dir2, ... ]` — one per service
-- Step 1 will read TSVs from ALL dirs in `all_trace_dirs`, tagged by service name
-- **Resolve the Living Docs home (canonical report location):**
+- 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 merged report here is what makes the view non-empty when a dev opens a service submodule directly.
+- **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.
 
 **If no `services` key (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
@@ -461,11 +462,14 @@ If any layer is behind current PRD version → flag `PRD_DRIFT` and extract chan
 
 ### Step 5 — Tech-doc revision drift check
 
-For each UC that has a tech-doc, compare:
-- Current `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`
-- `tech_doc_revision` stored in `.tsv` (revision at time of codegen)
+For each UC that has a tech-doc, compare the stored revision against the current doc — for **both** tech-doc kinds:
 
-If code was generated from an older revision → flag `TECHDOC_DRIFT`.
+- **BE contract:** `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{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}/{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`.
+
+Skip whichever kind has no doc / no stored revision (`—`).
 
 ### Step 6 — Write status back to TSV
 
@@ -572,6 +576,7 @@ Schema:
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
+              "fe_tech_doc_revision": 0,
               "status": "OK | DRIFT | GAP | UNTRACKED",
               "last_updated": "<YYYY-MM-DD>"
             }
@@ -621,6 +626,15 @@ Schema:
         "current_revision": 0,
         "fix": "/generate-code <UC-ID>"
       }
+    ],
+    "fe_techdoc_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "code_revision": 0,
+        "current_revision": 0,
+        "fix": "/generate-code <UC-ID> --phase=integration"
+      }
     ]
   }
 }
@@ -630,44 +644,42 @@ Schema:
 - `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`: use integer; `0` if not yet generated
+- `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`; `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 19-col TSV):** if `qc_owner` / `qc_blocked_by` columns are **absent** from the header (a pre-upgrade TSV), treat them as `null` — do not error. The next `/generate-bdd` re-gen upgrades the header to include them.
+- **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.*
 
-Authoritative trace state stays in each service submodule's `.trace/` (committed there).
-This step publishes the merged report to the **canonical Living Docs home** (the specs
-module) and drops a local mirror so the panel is never empty.
+**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 canonical merged report** to `{living_docs_dir}/` (`mkdir -p` it first):
-   - `{living_docs_dir}/trace-report.json` — merge every per-service `trace-report.json`
-     into one document, add a `"service"` field per scenario row, recalc summary aggregates.
-   - `{living_docs_dir}/{service-name}/{UC-ID}.tsv` — copy each service's TSVs, namespaced
-     by service. Overwrite; don't delete TSVs whose service source is gone (prior runs).
+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 (umbrella **or** a single service submodule) sees
-   data immediately: copy `{living_docs_dir}/trace-report.json` → `{panel_mirror}/trace-report.json`
-   (and the namespaced TSVs). If `panel_mirror` already resolves to `living_docs_dir`, skip.
+   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:**
    ```
-   Living Docs → {living_docs_dir}/  (canonical, in specs module)
-     user-service  : {N} TSV files
-     order-service : {N} TSV files
-     trace-report.json: merged ({total} scenarios across {S} services)
+   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 — both locations are generated, gitignored mirrors.** Add `.living-docs/` to the
-> **specs module's** `.gitignore` and `.trace/` to the current repo's `.gitignore`. The only
-> committed, authoritative trace state is each service submodule's own `.trace/`. The report
-> is regenerated by `/validate-traces` or `/sync` — never commit it.
+> **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`.
 
 ## Output
 
@@ -693,6 +705,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `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:
+
+```
+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:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| 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ò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).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -734,10 +776,13 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+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}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
 
 
 ```

package/commands/validate-traces.tmpl

@@ -19,16 +19,15 @@ Read-only check of coverage between specs, code, and tests — including PRD ver
 Check whether `services` array exists in `project-context.yaml`.
 
 **If `services` exists (umbrella mode):**
-- Resolve the trace dir for each service:
-  - Use `services[N].trace_dir` if explicitly set
-  - Otherwise default to `{services[N].path}/.trace`
-- Set `all_trace_dirs = [ dir1, dir2, ... ]` — one per service
-- Step 1 will read TSVs from ALL dirs in `all_trace_dirs`, tagged by service name
-- **Resolve the Living Docs home (canonical report location):**
+- 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 merged report here is what makes the view non-empty when a dev opens a service submodule directly.
+- **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.
 
 **If no `services` key (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
@@ -80,11 +79,14 @@ If any layer is behind current PRD version → flag `PRD_DRIFT` and extract chan
 
 ### Step 5 — Tech-doc revision drift check
 
-For each UC that has a tech-doc, compare:
-- Current `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`
-- `tech_doc_revision` stored in `.tsv` (revision at time of codegen)
+For each UC that has a tech-doc, compare the stored revision against the current doc — for **both** tech-doc kinds:
 
-If code was generated from an older revision → flag `TECHDOC_DRIFT`.
+- **BE contract:** `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{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}/{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`.
+
+Skip whichever kind has no doc / no stored revision (`—`).
 
 ### Step 6 — Write status back to TSV
 
@@ -191,6 +193,7 @@ Schema:
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
+              "fe_tech_doc_revision": 0,
               "status": "OK | DRIFT | GAP | UNTRACKED",
               "last_updated": "<YYYY-MM-DD>"
             }
@@ -240,6 +243,15 @@ Schema:
         "current_revision": 0,
         "fix": "/generate-code <UC-ID>"
       }
+    ],
+    "fe_techdoc_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "code_revision": 0,
+        "current_revision": 0,
+        "fix": "/generate-code <UC-ID> --phase=integration"
+      }
     ]
   }
 }
@@ -249,44 +261,42 @@ Schema:
 - `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`: use integer; `0` if not yet generated
+- `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`; `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 19-col TSV):** if `qc_owner` / `qc_blocked_by` columns are **absent** from the header (a pre-upgrade TSV), treat them as `null` — do not error. The next `/generate-bdd` re-gen upgrades the header to include them.
+- **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.*
 
-Authoritative trace state stays in each service submodule's `.trace/` (committed there).
-This step publishes the merged report to the **canonical Living Docs home** (the specs
-module) and drops a local mirror so the panel is never empty.
+**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 canonical merged report** to `{living_docs_dir}/` (`mkdir -p` it first):
-   - `{living_docs_dir}/trace-report.json` — merge every per-service `trace-report.json`
-     into one document, add a `"service"` field per scenario row, recalc summary aggregates.
-   - `{living_docs_dir}/{service-name}/{UC-ID}.tsv` — copy each service's TSVs, namespaced
-     by service. Overwrite; don't delete TSVs whose service source is gone (prior runs).
+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 (umbrella **or** a single service submodule) sees
-   data immediately: copy `{living_docs_dir}/trace-report.json` → `{panel_mirror}/trace-report.json`
-   (and the namespaced TSVs). If `panel_mirror` already resolves to `living_docs_dir`, skip.
+   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:**
    ```
-   Living Docs → {living_docs_dir}/  (canonical, in specs module)
-     user-service  : {N} TSV files
-     order-service : {N} TSV files
-     trace-report.json: merged ({total} scenarios across {S} services)
+   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 — both locations are generated, gitignored mirrors.** Add `.living-docs/` to the
-> **specs module's** `.gitignore` and `.trace/` to the current repo's `.gitignore`. The only
-> committed, authoritative trace state is each service submodule's own `.trace/`. The report
-> is regenerated by `/validate-traces` or `/sync` — never commit it.
+> **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`.
 
 ## Output
 

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.12.0
+0.14.0

package/core/commands/debug.md

@@ -169,7 +169,7 @@ If `services` section is present:
 - If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
 
 **2. Route to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
 - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
@@ -180,6 +180,7 @@ If `services` section is present:
 - Set `active_service = unresolved`
 
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs/bdd` — **always when `spec_source` is set.** All BDD (web/app/**system**) lives in the shared spec repo so every umbrella (FE/App/BE) reads the same scenarios; the FE tech-design gate + `/generate-code --phase=ui`/`--phase=integration` resolve the `system/` BDD here. *(Per-service `specs/bdd` only when there is no `spec_source`.)*
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
 - Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
@@ -189,8 +190,9 @@ If `services` section is present:
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, **all BDD (web/app/system)**, the **API contract (tech-docs)**, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** so every umbrella (FE/App/BE) and the PM read one source via `/sync`. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo (the PRD/BDD/design-spec/tech-docs there stay read-only for dev/QC — only PO edits those). In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
 
 ---
 
@@ -210,12 +212,12 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 |----------|--------|
 | `conventions.test_command` | service's `conventions.test_command` |
 | `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
-| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs/bdd`); ignore any service-level `specs_dir`** (BDD is cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
 - Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
 
@@ -618,6 +620,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `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:
+
+```
+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:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| 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ò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).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -659,10 +691,13 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+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}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
 
 
 ```

package/core/commands/define-product.md

@@ -166,7 +166,7 @@ If `services` section is present:
 - If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
 
 **2. Route to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
 - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
@@ -177,6 +177,7 @@ If `services` section is present:
 - Set `active_service = unresolved`
 
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs/bdd` — **always when `spec_source` is set.** All BDD (web/app/**system**) lives in the shared spec repo so every umbrella (FE/App/BE) reads the same scenarios; the FE tech-design gate + `/generate-code --phase=ui`/`--phase=integration` resolve the `system/` BDD here. *(Per-service `specs/bdd` only when there is no `spec_source`.)*
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
 - Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
@@ -186,8 +187,9 @@ If `services` section is present:
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, **all BDD (web/app/system)**, the **API contract (tech-docs)**, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** so every umbrella (FE/App/BE) and the PM read one source via `/sync`. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo (the PRD/BDD/design-spec/tech-docs there stay read-only for dev/QC — only PO edits those). In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
 
 ---
 
@@ -207,12 +209,12 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 |----------|--------|
 | `conventions.test_command` | service's `conventions.test_command` |
 | `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
-| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs/bdd`); ignore any service-level `specs_dir`** (BDD is cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
 - Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
 
@@ -552,6 +554,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `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:
+
+```
+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:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| 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ò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).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -593,10 +625,13 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+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}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
 
 
 ```