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

package/commands/generate-code.tmpl

@@ -47,9 +47,18 @@ Read `@trace.platform` from the feature file header.
 - If `web` or `app` → continue with phase logic below.
 
 **If `--phase=ui`:**
-Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feature`.
-Extract all `Then` clauses → collect implied response shapes and error states.
-If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
+Resolve the **mock shape source** (hybrid — prefer the real contract, fall back to System BDD):
+- **BE contract** `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` — if it exists, the mock adapter's port/DTO **shape** (request/response fields, types, error codes) comes from here → `mock_source = contract`. Most accurate; no shape rework at integration.
+- **System BDD** `{specs_dir}/{domain}/system/{TICKET-ID}*.feature` — always load `Then` clauses for **behavior + fixture values**. If no BE contract, the shape is inferred from these too → `mock_source = system-bdd`, and WARN:
+  ```
+  ⚠ BE contract not found — mock shape inferred from System BDD only.
+    System BDD describes behavior, not full request/response shape — the mock
+    may differ from the real API; expect adjustment at --phase=integration.
+    (Recommended: have BE publish {UC-ID}-tech-design.md first for an accurate mock.)
+  ```
+- If System BDD is also missing → warn "System BDD not found — mock layer will use placeholder fixtures." Continue.
+
+Store `mock_source` (`contract` | `system-bdd`) for the mock tags below.
 
 **Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
 Spec's frame links are the visual contract, and the local MCP reads them with far more
@@ -97,13 +106,18 @@ Code Connect mappings. Prefer Code-Connect-mapped components over inventing mark
 real token names, not hardcoded values.
 
 **If `--phase=integration`:**
-Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
+Resolve the design that drives the adapter (two layers):
+- **FE tech-design** (preferred — the port→endpoint→DTO mapping): `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md` §4, produced by `/generate-tech-docs` (FE path).
+- **BE API contract** (endpoint/shape source): `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
+
+Read `@trace.status` of whichever drives the adapter (the FE doc if present, else the BE contract).
 If `draft` or `in-review` → warn:
 ```
-⚠ Tech docs for {UC-ID} are {status}.
-  BE may not have a stable API contract yet.
-  Proceeding — ensure BE endpoint is deployed or confirm contract manually.
+⚠ Tech design for {UC-ID} ({platform}) is {status}.
+  Contract / adapter mapping may still change.
+  Proceeding — ensure BE endpoint is deployed or confirm the mapping manually.
 ```
+If the FE tech-design is **missing** → warn: "No FE tech-design found — falling back to the BE contract directly (adapter mapping inferred). Recommended: run `/generate-tech-docs {web|app .feature}` first."
 Locate existing mock adapter from `--phase=ui` run (search for `{UC-ID}MockApiAdapter` in `{paths.src_dir}/{domain}/`).
 If not found → warn: "Mock adapter not found — generating real API adapter from scratch using tech-doc contract."
 
@@ -200,30 +214,50 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Entry-point rule:** `@trace.implements` must appear on the **entry-point layer** as defined in `CLAUDE.md §2`. For REST APIs → Controller. For event-driven modules → event handler / consumer class. For context-engineering → the prompt orchestration function. Never put it only on an inner layer.
 
+### Test Selectors — emit stable element IDs *(FE/App UI only)*
+
+*Applies when `platform` is `web`/`app` and generating UI (`--phase=ui`, or default FE/App mode). Skip for BE.*
+
+Every **actionable** element (button, input, link, select, toggle, form-submit) MUST carry a **stable test-id** so QC locates it directly (no runtime scan):
+
+1. **Source the id.** If the FE tech-design `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md` exists, take ids **verbatim** from its §2b Test Selectors table (the contract). If it does not exist yet (e.g. `--phase=ui` before the FE tech-design), **generate ids by the convention** `{uc-lower}-{screen}-{element}-{type}` (e.g. `ft001-login-submit-btn`) so QC still has stable handles — they will be reconciled to the tech-design's §2b at integration.
+2. **Emit via the platform attribute** (from `@trace.testid_attr`, or by module):
+   - web (`react`/`nextjs`/`vue`/`angular`) → `data-testid="..."`
+   - React Native → `testID="..."`
+   - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` where the action needs it)
+   - native iOS → `accessibilityIdentifier = "..."`
+3. Only actionable elements; do not spam ids on static text. Keep ids identical to the tech-design map so QC Page Objects match on the first try.
+4. **Reused catalog component?** Pass the id via its **forwarding prop** (see the catalog `## Test-ID Forwarding` section — e.g. `<Button testId="ft001-login-submit-btn">`), not a raw attribute. If the component does not forward a test-id, or you are backfilling **existing/brownfield** screens (not freshly generated here), that is `/map-testids {UC-ID}`'s job — run it instead of editing shared components inline.
+
 ## Mock API Layer (`--phase=ui` only)
 
 *Skip this section entirely if `--phase` is not `ui`.*
 
-Using the System BDD `Then` clauses loaded in Phase Detection:
+Build the mock from the `mock_source` resolved in Phase Detection — **shape** from the BE contract when present, **fixture values + behavior** always from System BDD `Then` clauses:
 
-1. **Extract fixture data** per scenario — success responses + error responses.
-2. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
+1. **Define the port shape** `{UC-ID}ApiPort` (request/response DTOs + error codes):
+   - `mock_source = contract` → field names / types / error codes taken **verbatim from the BE contract** §2 (API Endpoints) / §3 (Data Model) — the real shape.
+   - `mock_source = system-bdd` → shape **inferred** from System BDD `Then` clauses (provisional — see warning above).
+2. **Extract fixture data** per scenario from System BDD `Then` clauses — success + error responses (BDD is the source of truth for *values / behavior*, regardless of shape source).
+3. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
    - Implements interface `{UC-ID}ApiPort` (same interface the real adapter will implement)
-   - Each method returns fixture data matching the BDD `Then` clause
+   - Each method returns fixture data matching the BDD `Then` clause, in the port shape
    - Include both success and error states (map to error scenarios in BDD)
    - Traceability tags:
      ```
      @trace.mock_for={UC-ID}
+     @trace.mock_source={contract | system-bdd}
      @trace.system_bdd={paths.specs_dir}/{domain}/system/{UC-ID}*.feature
+     {@trace.be_contract={UC-ID}-tech-design.md   # only when mock_source=contract}
      ```
-3. **Wire into service/hook layer** via environment flag or DI:
+4. **Wire into service/hook layer** via environment flag or DI:
    ```
    const adapter = IS_MOCK ? new {UC-ID}MockApiAdapter() : new {UC-ID}ApiAdapter()
    ```
    - `IS_MOCK` defaults to `true` in development/test env until real adapter is generated.
 
-> Tester uses the mock adapter to test all FE scenarios without waiting for BE.
-> Mock fixture data is derived directly from System BDD — BDD is the source of truth.
+> Tester uses the mock adapter to test all FE scenarios without waiting for BE to **deploy**.
+> Shape comes from the BE contract when available (accurate, no integration rework); else from System BDD (provisional — adjust at `--phase=integration`). Fixture *values* always come from System BDD — BDD is the source of truth for behavior.
 
 ---
 
@@ -231,7 +265,7 @@ Using the System BDD `Then` clauses loaded in Phase Detection:
 
 *Skip this section entirely if `--phase` is not `integration`.*
 
-1. **Read tech-doc API contract** from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` — extract endpoints, request/response shapes, error codes.
+1. **Read the integration design.** Prefer the FE tech-design §4 (port→endpoint→DTO→error mapping) at `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md`, using the BE API contract `{UC-ID}-tech-design.md` as the endpoint / request-response / error-code source. If no FE tech-design exists, extract endpoints + shapes + error codes directly from the BE contract.
 2. **Read existing mock adapter** interface (`{UC-ID}ApiPort`) from the `--phase=ui` output.
 3. **Generate real API adapter** at `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
    - Implements the same `{UC-ID}ApiPort` interface as mock adapter
@@ -261,18 +295,19 @@ Using the System BDD `Then` clauses loaded in Phase Detection:
 
 ## Write Trace State
 
-Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find the existing row by `sc_id` and update only these columns:
+Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find the existing row by `sc_id` and update only these columns. *(Umbrella + `spec_source`: `trace_dir` resolves to `{spec_source}/.trace` — this command runs from `service_root` but writes the trace row into the **spec repo** (cross-repo); commit/push the spec submodule for the trace update, alongside the 2-tier code push.)*
 
 | Column | Value |
 |--------|-------|
 | `gen_ver` | copy `spec_ver` from the current `.tsv` row (= scenario version at time of codegen) |
 | `implemented_by` | `{ControllerClass}.{methodName}` |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
-| `tech_doc_revision` | `@trace.revision` from tech-doc header, or `—` if no tech-doc |
+| `tech_doc_revision` | `@trace.revision` from the **BE** contract `{UC-ID}-tech-design.md`, or `—` if none |
+| `fe_tech_doc_revision` | `@trace.revision` from the **FE** tech-design `{UC-ID}-tech-design-{platform}.md` when generating FE with `--phase=integration` (the doc whose §4 drove this adapter); `—` for BE, or for FE `--phase=ui` / no FE tech-design |
 | `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`) unchanged.
+Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`) unchanged.
 `status` is computed by `/validate-traces` — do not set here.
 
 ## Refresh Panel Mirror

package/commands/generate-design-spec.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).
 
@@ -841,6 +843,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:
@@ -882,10 +914,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.)*
 
 
 {If missing_frames is empty}:

package/commands/generate-prd.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).
 
@@ -644,6 +646,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:
@@ -685,10 +717,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/generate-spec-manifest.md

@@ -171,7 +171,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`
@@ -182,6 +182,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.)*
@@ -191,8 +192,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.
 
 ---
 
@@ -212,12 +214,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).
 
@@ -541,6 +543,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:
@@ -582,10 +614,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.)*
 
 
 ```