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

package/commands/dev-smoke-test.md

@@ -127,6 +127,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -139,6 +141,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -164,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`
@@ -175,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.)*
@@ -183,8 +188,10 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - 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.
 
 ---
 
@@ -204,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).
 
@@ -599,6 +606,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:
@@ -640,10 +677,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/fix-bug.md

@@ -84,7 +84,7 @@ Wait for explicit "Y" or "N" from the user before continuing.
 - "N" → stop and ask what the user wants to change.
 
 
-*Note: For this command, the target in Step 1 is a ticket ID (e.g., `PROJ-123`) or bug description from `$ARGUMENTS`. There is no file to resolve — proceed to context loading.*
+*Note: For this command, the target in Step 1 is a ticket ID (e.g., `PROJ-123`), a **filed bug `{BUG-ID}`** (a `{paths.bug_reports_dir}/{BUG-ID}.md` from `/report-bug` — e.g. a QC product-gap), or a bug description from `$ARGUMENTS`. If a `{BUG-ID}` is given, resolve & read that report for spec context; otherwise proceed to context loading.*
 
 ## Context
 # Context Loader — Load All Project Context
@@ -125,6 +125,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -137,6 +139,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -162,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`
@@ -173,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.)*
@@ -181,8 +186,10 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - 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.
 
 ---
 
@@ -202,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).
 
@@ -387,8 +394,9 @@ Proceed to the next step of the calling command.
 ---
 
 ## Phase 1 — Gather Info
+If a `{BUG-ID}` was given: read `{paths.bug_reports_dir}/{BUG-ID}.md` for the spec context, AC violated, expected-vs-actual, and the suggested layer — use it as the bug details (no need to re-ask).
 If ticket: fetch details (or ask user to paste).
-If no ticket — CHECKPOINT:
+If no ticket / BUG-ID — CHECKPOINT:
 1. Where does the bug occur? (module, endpoint, flow)
 2. Steps to reproduce?
 3. Expected vs Actual?
@@ -461,7 +469,11 @@ Proceed? (Y/N)
 ```
 
 ## Phase 3 — Fix
+
+*Umbrella mode: the buggy code lives in the **service submodule** resolved at context-loader Step 1.6 — create the branch and run every git/build step from **inside** `{service_root}`. Single-service: omit the `cd`.*
+
 ```bash
+cd {service_root}                              # umbrella: the service submodule; single-service: omit
 git checkout -b fix/{TICKET_ID}-{description}
 ```
 Apply fix. Add trace annotation if file has `@trace.implements`:
@@ -478,13 +490,37 @@ Test: "Regression {TICKET_ID}: {bug description}"
 ```
 Run test. If fail → debug and fix (max 3 iterations).
 
-## Phase 5 — Build & Commit
+## Phase 5 — Build & Commit (2-layer push in umbrella mode)
 ```bash
-{conventions.build_command}   # max 3 retries
+{conventions.build_command}   # max 3 retries — runs inside {service_root} in umbrella mode
+# Tầng 1 — push the fix branch in the service submodule (where the code lives):
 git add {files}
 git commit -m "fix({TICKET_ID}): {description}"
-git push -u origin fix/{TICKET_ID}-{slug}
+git push -u origin fix/{TICKET_ID}-{slug}      # then open a PR into the service's tracked branch
 ```
+> **Umbrella mode — Tầng 2 (bump umbrella pointer):** the umbrella records a *commit* of the service
+> submodule, not a branch. After the fix-branch PR **merges** into the service's tracked branch, bump
+> the pointer so teammates pulling the umbrella don't hit "commit not found":
+> ```bash
+> cd -                                          # back to umbrella root
+> git add {service_root} && git commit -m "chore: bump {service_root} pointer (fix {TICKET_ID})"
+> git push
+> ```
+> Single-service mode: no umbrella pointer — Tầng 1 is the whole push. Full rule: Sync & Update §4.4 (commit 2 tầng).
+
+## Phase 5.5 — Close the bug report (if fixing a filed `{BUG-ID}`)
+
+*Skip if the target was a plain ticket/description (no `{BUG-ID}` file).*
+
+After the fix is committed, update `{paths.bug_reports_dir}/{BUG-ID}.md`:
+- Set `State` → `🟡 Fixed` and append a short **Resolution** (root cause + commit/PR link).
+- It is **not** `Closed` yet — QC owns verification: when `/qc-run-test` re-runs and `qc_status`
+  for the linked SC flips to `pass`, it becomes `🟢 Closed` (and `qc_owner`/`qc_blocked_by` clear).
+- Commit the updated report to the spec repo (same 2-layer push as `/report-bug`) so the PO/PM
+  "waiting-on" view reflects it on `/sync`.
+
+This is the only write `/fix-bug` makes to the feedback area — it still fixes **code** only,
+never edits PRD/BDD (spec changes are PO/Dev per BUG_FLOW Case 2–4).
 
 ## Phase 6 — Offer to Record a Lesson (optional)
 
@@ -605,6 +641,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:
@@ -646,10 +712,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.)*
 
 
 ```
@@ -657,7 +726,8 @@ Next   : {suggested command with example arguments}
 Root Cause: {analysis}
 Changes: {list}
 ✅ Regression test added | ✅ Build: SUCCESS
+{🐞 BUG-{id} → State: Fixed (pushed) — Closed after /qc-run-test re-verify pass | if fixing a filed bug}
 {📝 Lesson L-NNN recorded (if captured)}
 Branch: fix/{TICKET_ID}-{slug}
-Next: Create PR and link to ticket.
+Next: Create PR and link to ticket. {QC: re-run /qc-run-test {UC-ID} to verify + close the bug | if applicable}
 ```

package/commands/fix-bug.tmpl

@@ -3,7 +3,7 @@
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a ticket ID (e.g., `PROJ-123`) or bug description from `$ARGUMENTS`. There is no file to resolve — proceed to context loading.*
+*Note: For this command, the target in Step 1 is a ticket ID (e.g., `PROJ-123`), a **filed bug `{BUG-ID}`** (a `{paths.bug_reports_dir}/{BUG-ID}.md` from `/report-bug` — e.g. a QC product-gap), or a bug description from `$ARGUMENTS`. If a `{BUG-ID}` is given, resolve & read that report for spec context; otherwise proceed to context loading.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -11,8 +11,9 @@
 ---
 
 ## Phase 1 — Gather Info
+If a `{BUG-ID}` was given: read `{paths.bug_reports_dir}/{BUG-ID}.md` for the spec context, AC violated, expected-vs-actual, and the suggested layer — use it as the bug details (no need to re-ask).
 If ticket: fetch details (or ask user to paste).
-If no ticket — CHECKPOINT:
+If no ticket / BUG-ID — CHECKPOINT:
 1. Where does the bug occur? (module, endpoint, flow)
 2. Steps to reproduce?
 3. Expected vs Actual?
@@ -85,7 +86,11 @@ Proceed? (Y/N)
 ```
 
 ## Phase 3 — Fix
+
+*Umbrella mode: the buggy code lives in the **service submodule** resolved at context-loader Step 1.6 — create the branch and run every git/build step from **inside** `{service_root}`. Single-service: omit the `cd`.*
+
 ```bash
+cd {service_root}                              # umbrella: the service submodule; single-service: omit
 git checkout -b fix/{TICKET_ID}-{description}
 ```
 Apply fix. Add trace annotation if file has `@trace.implements`:
@@ -102,13 +107,37 @@ Test: "Regression {TICKET_ID}: {bug description}"
 ```
 Run test. If fail → debug and fix (max 3 iterations).
 
-## Phase 5 — Build & Commit
+## Phase 5 — Build & Commit (2-layer push in umbrella mode)
 ```bash
-{conventions.build_command}   # max 3 retries
+{conventions.build_command}   # max 3 retries — runs inside {service_root} in umbrella mode
+# Tầng 1 — push the fix branch in the service submodule (where the code lives):
 git add {files}
 git commit -m "fix({TICKET_ID}): {description}"
-git push -u origin fix/{TICKET_ID}-{slug}
+git push -u origin fix/{TICKET_ID}-{slug}      # then open a PR into the service's tracked branch
 ```
+> **Umbrella mode — Tầng 2 (bump umbrella pointer):** the umbrella records a *commit* of the service
+> submodule, not a branch. After the fix-branch PR **merges** into the service's tracked branch, bump
+> the pointer so teammates pulling the umbrella don't hit "commit not found":
+> ```bash
+> cd -                                          # back to umbrella root
+> git add {service_root} && git commit -m "chore: bump {service_root} pointer (fix {TICKET_ID})"
+> git push
+> ```
+> Single-service mode: no umbrella pointer — Tầng 1 is the whole push. Full rule: Sync & Update §4.4 (commit 2 tầng).
+
+## Phase 5.5 — Close the bug report (if fixing a filed `{BUG-ID}`)
+
+*Skip if the target was a plain ticket/description (no `{BUG-ID}` file).*
+
+After the fix is committed, update `{paths.bug_reports_dir}/{BUG-ID}.md`:
+- Set `State` → `🟡 Fixed` and append a short **Resolution** (root cause + commit/PR link).
+- It is **not** `Closed` yet — QC owns verification: when `/qc-run-test` re-runs and `qc_status`
+  for the linked SC flips to `pass`, it becomes `🟢 Closed` (and `qc_owner`/`qc_blocked_by` clear).
+- Commit the updated report to the spec repo (same 2-layer push as `/report-bug`) so the PO/PM
+  "waiting-on" view reflects it on `/sync`.
+
+This is the only write `/fix-bug` makes to the feedback area — it still fixes **code** only,
+never edits PRD/BDD (spec changes are PO/Dev per BUG_FLOW Case 2–4).
 
 ## Phase 6 — Offer to Record a Lesson (optional)
 
@@ -135,7 +164,8 @@ If `Y` → run the capture procedure below with `source=/fix-bug {TICKET_ID}`, a
 Root Cause: {analysis}
 Changes: {list}
 ✅ Regression test added | ✅ Build: SUCCESS
+{🐞 BUG-{id} → State: Fixed (pushed) — Closed after /qc-run-test re-verify pass | if fixing a filed bug}
 {📝 Lesson L-NNN recorded (if captured)}
 Branch: fix/{TICKET_ID}-{slug}
-Next: Create PR and link to ticket.
+Next: Create PR and link to ticket. {QC: re-run /qc-run-test {UC-ID} to verify + close the bug | if applicable}
 ```

package/commands/generate-bdd.md

@@ -123,6 +123,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -135,6 +137,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -160,7 +164,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`
@@ -171,6 +175,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.)*
@@ -179,8 +184,10 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - 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.
 
 ---
 
@@ -200,12 +207,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).
 
@@ -832,17 +839,19 @@ Feature: <Feature name>
 
 After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-ID}.tsv` for each UC.
 
+> **Umbrella + `spec_source`:** both the `.feature` files **and** the trace `.tsv` write to the **spec repo** (`{spec_source}/specs/bdd/…` and `{spec_source}/.trace/…`, resolved by context-loader) — a **single-repo** write, committed/pushed to the spec submodule. (Trace is consolidated in the spec repo so the PM manages all status in one place; code-side commands update it cross-repo later.)
+
 **TSV columns (tab-separated, one header row + one data row per scenario):**
 ```
-sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tdev_selftest\tdev_selftest_at\tqc_status\tqc_run_at\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
+sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tdev_selftest\tdev_selftest_at\tqc_status\tqc_run_at\tqc_owner\tqc_blocked_by\tprd_version\tbdd_version\ttech_doc_revision\tfe_tech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
 ```
 
 **Rules:**
 - If file does not exist → create with header row + all scenario rows.
 - If file exists (re-generation) → for each SC in the new `.feature`:
   - SC already in `.tsv` AND `spec_ver` is unchanged → update only: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave all other columns unchanged.
-  - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` unchanged.
-  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `tech_doc_revision` all set to `—`.
+  - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision`, `fe_tech_doc_revision` unchanged.
+  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`, `tech_doc_revision`, `fe_tech_doc_revision` all set to `—`.
   - SC no longer in `.feature` (removed) → delete its row.
 
 **Values to write for each scenario:**
@@ -860,9 +869,12 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tde
 | `dev_selftest_at` | `—` |
 | `qc_status` | `—` (official QC automation result — set by `/qc-run-test`) |
 | `qc_run_at` | `—` |
+| `qc_owner` | `—` (who a non-passing SC waits on: `dev` / `po` — set by `/qc-run-test` + `/report-bug`) |
+| `qc_blocked_by` | `—` (linked `BUG-{id}` / `GAP-{id}` — set by `/qc-run-test` + `/report-bug`) |
 | `prd_version` | `@trace.prd_version` from `.feature` header |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
-| `tech_doc_revision` | `—` |
+| `tech_doc_revision` | `—` (BE API contract revision — set by `/generate-code` + `/review-tech-docs`) |
+| `fe_tech_doc_revision` | `—` (FE client tech-design revision `{UC-ID}-tech-design-{platform}.md` — set by `/generate-code --phase=integration` + `/review-tech-docs` on an FE doc) |
 | `prd_status` | read `\| **Status** \|` from PRD metadata |
 | `uc_status` | `draft` for new UCs; keep existing value for re-gen |
 | `fe_phase` | `—` (set by `/generate-code --phase` when FE implements) |
@@ -873,21 +885,29 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tde
 # Refresh Living Docs panel mirror *(local, umbrella mode)*
 
 *Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
-the service `.trace/` IS the panel location, so nothing to mirror.*
+the repo's own `.trace/` IS the panel location, so nothing to mirror.*
 
-After updating the authoritative service TSV(s) at `{paths.trace_dir}`:
+After updating the authoritative TSV(s) at `{paths.trace_dir}`:
 
-1. Resolve `panel_mirror = ./.trace` at the **current workspace root** (where this command runs).
+**When `setup.spec_source` is set (consolidated trace — the common case):**
+`{paths.trace_dir}` resolves to `{spec_source}/.trace` — the single authoritative location.
+This command runs from `service_root`, so the write is **cross-repo into the spec submodule**;
+commit/push the spec submodule for the trace update (same as `feedback/`).
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root**.
 2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
-   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
-   (create the dir; overwrite). Use `active_service` for `{service-name}`.
+   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{UC-ID}.tsv` (create the dir; overwrite).
+   No per-service namespacing — there is one trace set; the owning service is carried in each
+   row's `@trace.service`.
+
+**Legacy (no `spec_source` — per-service trace):**
+Copy each just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+(namespaced by `active_service`).
 
 This keeps the open workspace's Living Docs panel current **between syncs** — it is a
-**local convenience mirror only**. The *canonical* report in the spec module
-(`{spec_source}/.living-docs/`) and the merged `trace-report.json` are rebuilt by
-`/sync` or `/validate-traces` (those need every service's data, so a single per-UC
-command cannot produce them). For orchestrated commands, do this once in the orchestrator
-after all sub-agents return — not inside each sub-agent.
+**local convenience mirror only**. The merged `trace-report.json` (canonical, in
+`{spec_source}/.living-docs/`) is rebuilt by `/sync` or `/validate-traces`. For orchestrated
+commands, do this once in the orchestrator after all sub-agents return — not inside each
+sub-agent.
 
 
 ## Output
@@ -914,6 +934,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:
@@ -955,10 +1005,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.)*
 
 
 ```