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

package/core/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`
@@ -183,6 +187,7 @@ 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`
 
 > **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.
 

package/core/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`
@@ -181,6 +185,7 @@ 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`
 
 > **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.
 
@@ -387,8 +392,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 +467,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 +488,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)
 
@@ -657,7 +691,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/core/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`
@@ -179,6 +183,7 @@ 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`
 
 > **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.
 
@@ -834,7 +839,7 @@ After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-I
 
 **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\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
 ```
 
 **Rules:**
@@ -842,7 +847,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tde
 - 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 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` all set to `—`.
   - SC no longer in `.feature` (removed) → delete its row.
 
 **Values to write for each scenario:**
@@ -860,6 +865,8 @@ 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` | `—` |

package/core/commands/generate-code.md

@@ -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`
@@ -181,6 +185,7 @@ 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`
 
 > **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.
 

package/core/commands/generate-design-spec.md

@@ -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`
@@ -181,6 +185,7 @@ 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`
 
 > **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.
 

package/core/commands/generate-prd.md

@@ -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`
@@ -181,6 +185,7 @@ 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`
 
 > **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.
 

package/core/commands/generate-spec-manifest.md

@@ -130,6 +130,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
@@ -142,6 +144,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`
@@ -186,6 +190,7 @@ 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`
 
 > **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.
 

package/core/commands/generate-tech-docs.md

@@ -146,6 +146,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
@@ -158,6 +160,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`
@@ -202,6 +206,7 @@ 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`
 
 > **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.
 

package/core/commands/learn.md

@@ -134,6 +134,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
@@ -146,6 +148,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`
@@ -190,6 +194,7 @@ 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`
 
 > **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.
 

package/core/commands/propose-scenario.md

@@ -1,7 +1,8 @@
-# /propose-scenario — Propose a New BDD Scenario (Tester-Facing)
+# /propose-scenario — Propose a New BDD Scenario (Tester & QC-Facing)
 
-For **testers** who discover an edge case not covered by existing BDD. Drafts a Gherkin scenario
-into a **proposals area** for PO/Dev to review and promote.
+For **testers and QC** who discover an edge case not covered by existing BDD (e.g. a `DOC_GAPS`
+missing-coverage gap from `/qc-analyze`). Drafts a Gherkin scenario into a **proposals area** for
+PO/Dev to review and promote.
 
 **Does NOT edit the canonical `.feature` file.** BDD is owned by PO/Dev — this command only writes
 a proposal. Promotion into the real BDD is a PO/Dev action.
@@ -134,6 +135,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
@@ -146,6 +149,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`
@@ -190,6 +195,7 @@ 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`
 
 > **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.
 
@@ -410,15 +416,28 @@ A BDD scenario must trace to a PRD acceptance criterion. Determine which case ap
 → This is a coverage gap. Proceed to draft the scenario (Step 3), mapped to that AC.
 
 **Case B — behavior is NOT in any AC** (genuinely new requirement):
-→ STOP. A scenario here would have nothing to trace to. Do **not** draft it as a BDD proposal.
-Instead output a **PRD change request** for the PO:
+→ Do **not** draft a BDD proposal (a scenario would have nothing to trace to). Instead **write a
+PRD change request file** so the PO actually sees it on `/sync` (do not just print it):
+
+Write to `{paths.prd_change_requests_dir}/{UC-ID}-{slug}.md` (resolved to
+`{spec_source}/feedback/prd-change-requests/` in umbrella mode; create dir if needed):
 ```
-⚠️ Not covered by any PRD AC — this is a new requirement, not a coverage gap.
-   Route to PO: add/extend an AC in {prd_path}, then re-run /generate-bdd.
-   Requested behavior: {description}
-   Suggested AC: "{draft AC text}"
+# PRD Change Request — {UC-ID}: {short title}
+
+> ⚠️ New requirement found in test — NOT covered by any PRD AC (not a coverage gap).
+| Field | Value |
+|---|---|
+| UC / Ticket | {UC-ID} |
+| PRD | {prd_path} (v{prd_version}) |
+| Source | {BUG-ID if any | tester/QC observation} |
+| Requested by | tester/QC |
+| Status | Open |
+
+**Requested behavior:** {description}
+**Suggested AC (draft for PO):** "{draft AC text}"
+**Route to PO:** add/extend an AC in {prd_path} → `/refine-prd` → re-run `/generate-bdd` → dev `/generate-code`.
 ```
-Then end (no proposal file written for BDD).
+Then go to Step 5 (handoff applies to this file too). Skip Step 3–4 (no BDD scenario for Case B).
 
 If unsure which case → show the AC list and ask the tester which AC this maps to, or confirm it's new.
 
@@ -447,7 +466,13 @@ git push                      # → PO/Dev see it on their next /sync
 ```
 
 - No push rights to the spec repo → open a PR / MR instead. Print this fallback.
-- For a **PRD change request** (Case B), the same handoff applies — commit the request doc so the PO sees it.
+- For a **PRD change request** (Case B), commit the request file instead:
+  ```bash
+  cd {spec_source}
+  git add feedback/prd-change-requests/{UC-ID}-{slug}.md
+  git commit -m "qa(prd-change): {UC-ID} — {title}"
+  git push
+  ```
 
 > PO/Dev are notified through their normal routine: `/sync` lists newly-pulled proposals.
 

package/core/commands/qc-analyze.md

@@ -133,6 +133,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
@@ -145,6 +147,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`
@@ -189,6 +193,7 @@ 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`
 
 > **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.
 
@@ -405,7 +410,7 @@ Boundary vs `/qc-plan`: you answer *"what is the requirement?"*; qc-plan answers
 the risk, what to ask dev?"*. When something is ambiguous/missing, record it as a gap and
 hand off to qc-plan — never invent an answer.
 
-## Skills (`skills/qc/qa-analyst/`)
+## Skills (`{paths.qc_skills_dir}/qa-analyst/`)
 
 Load only the file for the step you are doing (each is self-contained):
 - `spec-breakdown.md` — break a spec/PRD/user story into structure.
@@ -424,15 +429,29 @@ tests with `@trace.verifies` and write `qc_status` per scenario.
 
 ## DOC_GAPS (mandatory)
 
-Always produce a gaps file following `skills/qc/qa-analyst/DOC_GAPS.template.md`:
+Always produce a gaps file following `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`:
 - Each gap `GAP-xx`, classified MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, with severity (🔴 Blocker → 🟢 Low) and the affected function/BR/AC.
 - Never fabricate answers; mark assumptions as `ASSUMPTION` for PO/dev to confirm.
 - Any `🔴 Blocker` still `Open` ⇒ the UC is not ready for qc-design-test — hand off to qc-plan.
+- **Push genuine SPEC defects to the PO (not just keep them local).** A blocker that is a real
+  flaw in the official spec — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` in PRD/BDD — must reach
+  the PO via the feedback flow, not sit only in `DOC_GAPS.md`: file `/report-bug {UC-ID} {desc}`
+  (its BUG_FLOW classifies PRD vs BDD), or `/propose-scenario {UC-ID}` if the gap is missing test
+  coverage. `ASSUMPTION` / `OPEN QUESTION` gaps are confirmed via qc-plan's questions-for-dev — not filed as bugs.
 
 ## Output
 
-Write the analysis artifacts under `{paths.refinement_dir}/qc/{UC-ID}/` (requirement
-breakdown, BR table, data-flow, AC list with SC mapping, and `DOC_GAPS.md`).
+Write **exactly TWO files** under `{paths.qc_dir}/{UC-ID}/` — do **not** split the analysis
+into one-file-per-step (no separate spec-breakdown / business-rules / data-flow / AC files):
+
+1. **`{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`** — the single consolidated analysis.
+   Sections in order: requirement breakdown → business-rule table (`BR-xx`) → data-flow →
+   acceptance-criteria (`AC-xx`), each `BR`/`AC` mapped to its owning `{UC-ID}-SC{N}`.
+2. **`{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`** — the gaps file (per `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`).
+
+`{paths.qc_dir}` is a VISIBLE top-level folder in the QC repo (default `docs/`, **not** the
+hidden `.agent/review/`) so the QC team can open and process the output easily. The official
+spec stays in the PO spec submodule — do not write analysis there.
 
 ## Report
 
@@ -507,7 +526,8 @@ Next   : {suggested command with example arguments}
 
 ```
 /qc-analyze Complete — {UC-ID}
-Gaps: {N} ({blockers} blocker)
+Files: {paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md + DOC_GAPS.md   (2 files)
+Gaps: {N} ({blockers} blocker)   ← spec-defect blocker? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
 SC mapping: {M} BR/AC mapped to {K} scenarios
 Next: /qc-plan {UC-ID}   ← risk / what-if / questions-for-dev
       (resolve 🔴 Blocker gaps with PO/Dev first)

package/core/commands/qc-design-test.md

@@ -92,7 +92,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 UC-ID. Read the qc-analyze + qc-plan outputs from `{paths.refinement_dir}/qc/{UC-ID}/` and the official `.feature` (with `@trace.scenario` per scenario).*
+*Note: For this command, the target in Step 1 is a UC-ID. Read the qc-analyze + qc-plan outputs (`REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md`, `TEST_PLAN.md`) from `{paths.qc_dir}/{UC-ID}/` and the official `.feature` (with `@trace.scenario` per scenario).*
 
 ## Context
 # Context Loader — Load All Project Context
@@ -133,6 +133,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
@@ -145,6 +147,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`
@@ -189,6 +193,7 @@ 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`
 
 > **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.
 
@@ -400,7 +405,7 @@ You are the **QC Designer** — stage 3. Produce/maintain test-case Markdown fil
 (`.Test.md`) from the analyzed requirement + plan. Output feeds qc-run-test (Python) and
 qc-review. You do **not** write Python.
 
-## Skills — pick the layer, load ONE file (`skills/qc/qa-designer/`)
+## Skills — pick the layer, load ONE file (`{paths.qc_skills_dir}/qa-designer/`)
 
 | Layer | File |
 |---|---|
@@ -429,7 +434,7 @@ qc-run-test write `qc_status` per scenario.
 
 ## Output
 
-Write `.Test.md` files under `{paths.refinement_dir}/qc/{UC-ID}/test-cases/`.
+Write `.Test.md` files under `{paths.qc_dir}/{UC-ID}/test-cases/`.
 
 ## Report
 

package/core/commands/qc-plan.md

@@ -92,7 +92,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 UC-ID. Read the qc-analyze output (requirement breakdown + `DOC_GAPS.md`) from `{paths.refinement_dir}/qc/{UC-ID}/` and the official `.feature` for the UC.*
+*Note: For this command, the target in Step 1 is a UC-ID. Read the qc-analyze output (`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`) from `{paths.qc_dir}/{UC-ID}/` and the official `.feature` for the UC.*
 
 ## Context
 # Context Loader — Load All Project Context
@@ -133,6 +133,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
@@ -145,6 +147,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`
@@ -189,6 +193,7 @@ 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`
 
 > **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.
 
@@ -401,7 +406,7 @@ risk analysis, what-if scenarios, test scope/strategy per layer, and `questions-
 for any open/blocker gaps. You answer *"where is the risk, what must we ask?"* — you do not
 design concrete test cases (that is qc-design-test).
 
-## Skills (`skills/qc/qa-planner/`)
+## Skills (`{paths.qc_skills_dir}/qa-planner/`)
 
 - `test-plan.md` — self-contained: risk matrix, what-if, scope by test layer
   (functional / integration / e2e / non-functional), entry/exit criteria, and the
@@ -409,7 +414,7 @@ design concrete test cases (that is qc-design-test).
 
 ## Output
 
-Write the test plan to `{paths.refinement_dir}/qc/{UC-ID}/TEST_PLAN.md`. Scope the plan to
+Write the test plan to `{paths.qc_dir}/{UC-ID}/TEST_PLAN.md`. Scope the plan to
 the UC's scenarios (`{UC-ID}-SC{N}` from the `.feature`) so qc-design-test can design
 cases per scenario.