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

package/core/commands/qc-report.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.
 
@@ -398,7 +403,7 @@ Proceed to the next step of the calling command.
 
 You are the **QC Report** stage — turn the latest run into a shareable report + evidence.
 
-## Skill (`skills/qc/qa-runner/report/`)
+## Skill (`{paths.qc_skills_dir}/qa-runner/report/`)
 
 - `report.md` — self-contained: pytest-html (`--html=reports/<feature>/report.html
   --self-contained-html`) + Playwright Trace (`test-results/<nodeid>/trace.zip`, viewed via
@@ -411,6 +416,12 @@ You are the **QC Report** stage — turn the latest run into a shareable report
    FAIL/SKIP has a trace + screenshot attached.
 3. Summarize TOTAL / PASS / FAIL / SKIP; for each FAIL include the `show-trace` command and
    whether it was classified script-bug or product-gap.
+4. **Hand off product-gaps to the specs (prompted).** For every FAIL classified **product-gap**
+   (a real defect, impl ≠ spec — not a script-bug), print a ready-to-run
+   `/report-bug {UC-ID} {one-line expected-vs-actual}` so QC files it to the shared spec repo.
+   `/report-bug`'s BUG_FLOW then routes the root cause (Code / BDD / PRD / Design / Env). Never
+   fake-pass a product-gap — it stays FAIL in `qc_status` until fixed + re-run. **script-bugs are
+   NOT filed** (QC fixes the script and re-runs). List the commands; do not auto-create the reports.
 
 ## Report
 
@@ -487,5 +498,11 @@ Next   : {suggested command with example arguments}
 /qc-report Complete — {UC-ID}
 Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
 Trace : test-results/<nodeid>/trace.zip  (python3 -m playwright show-trace <file>)
+
+Product-gaps to file ({g}):   ← run these so PO/Dev see them on /sync (script-bugs excluded)
+  /report-bug {UC-ID} {gap 1 — expected vs actual}
+  /report-bug {UC-ID} {gap 2 …}
+  (none → skip)
+
 Next: /validate-traces {UC-ID}   ← refresh Living Docs (qc_status), then create PR
 ```

package/core/commands/qc-review.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. Detect review mode from `$ARGUMENTS`/context: review test-case `.Test.md` (after design) or review Python scripts (after run). Read artifacts from `{paths.refinement_dir}/qc/{UC-ID}/` and the generated test/page-object source.*
+*Note: For this command, the target in Step 1 is a UC-ID. Detect review mode from `$ARGUMENTS`/context: review test-case `.Test.md` (after design) or review Python scripts (after run). Read artifacts from `{paths.qc_dir}/{UC-ID}/` and the generated test/page-object source.*
 
 ## 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.
 
@@ -403,7 +408,7 @@ You are the **QC Reviewer** — the shared review gate, run twice in the pipelin
 Detect mode: if the target artifacts are `.Test.md` → test-case review; if Python test/PO
 files exist for the UC and are newer → script review. If ambiguous, ask.
 
-## Skills (`skills/qc/qa-reviewer/`)
+## Skills (`{paths.qc_skills_dir}/qa-reviewer/`)
 
 Pick by mode + layer, load ONE file:
 - Test-case review: `test-case/{functional,e2e,integration,non-functional,exploratory}.md`

package/core/commands/qc-run-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 reviewed `.Test.md` from `{paths.refinement_dir}/qc/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
+*Note: For this command, the target in Step 1 is a UC-ID. Read the reviewed `.Test.md` from `{paths.qc_dir}/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
 
 ## 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.
 
@@ -407,7 +412,7 @@ Stack rules (MANDATORY — from `modules/qc-playwright/stack-profile.yaml`):
 - Cover **100%** of TCs in the file — every TC ends Pass/Fail/Skip (none left Draft).
 - Classify each FAIL: script-bug (fix selector/logic) vs product-gap (keep FAIL + evidence, never fake-pass).
 
-## Skills — pick the layer, load ONE file (`skills/qc/qa-runner/`)
+## Skills — pick the layer, load ONE file (`{paths.qc_skills_dir}/qa-runner/`)
 
 `functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
 `non-functional.md`, `exploratory/session.md`.
@@ -431,6 +436,12 @@ After the run, update `{paths.trace_dir}/{UC-ID}.tsv` — for each scenario row
 |--------|-------|
 | `qc_status` | `pass` if all QC tests for this SC passed · `fail` if any failed · `skip` if all skipped/xfail · `not_run` if no QC test covers it |
 | `qc_run_at` | today `YYYY-MM-DD` |
+| `qc_owner` | **who the SC is waiting on** (the PM/PO "pending" view): `dev` if FAIL = product-gap (real defect → dev fixes) · `po` if `skip`/`not_run` because an **open `DOC_GAPS` 🔴 Blocker** prevents testing (PO must clarify PRD/BDD) · `—` if `pass`, or FAIL = script-bug (QC's own to fix — transient) |
+| `qc_blocked_by` | linked artifact: `GAP-{id}` when blocked by a spec gap (set here) · `BUG-{id}` once `/report-bug` is filed for the product-gap (backfilled by `/report-bug`) · `—` otherwise |
+
+Set `qc_owner`/`qc_blocked_by` together with `qc_status`. On `pass`, **clear** both to `—`.
+For a product-gap FAIL, set `qc_owner=dev` now; the `BUG-{id}` is backfilled into `qc_blocked_by`
+when QC runs the `/report-bug` that `/qc-report` prompts.
 
 Leave all other columns unchanged — **never** touch `dev_selftest`/`dev_selftest_at`
 (owned by `/dev-run-test`). `qc_status` (official QC) and `dev_selftest` (dev smoke) are

package/core/commands/refine-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/report-bug.md

@@ -1,6 +1,8 @@
-# /report-bug — File a Spec-Traced Bug (Tester-Facing)
+# /report-bug — File a Spec-Traced Bug (Tester & QC-Facing)
 
-For **testers**. Produces a structured bug report with full spec context, classifies the likely
+For **testers and QC** — including **product-gaps** surfaced by the `/qc-*` pipeline
+(`/qc-run-test` FAIL classified product-gap, or a `DOC_GAPS` spec-defect blocker from
+`/qc-analyze`). Produces a structured bug report with full spec context, classifies the likely
 layer, and saves it for handoff to the dev team.
 
 **READ-ONLY on specs and code.** This command never edits PRD, BDD, tech-docs, or source.
@@ -134,6 +136,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 +150,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 +196,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.
 
@@ -446,6 +453,17 @@ State the classification as a suggestion (dev confirms during `/fix-bug`).
 Assign `BUG-{today YYYYMMDD}-{NN}` (NN = next sequence among existing reports).
 Write to `{paths.bug_reports_dir}/{BUG-ID}.md` (resolved to `{spec_source}/feedback/bug-reports/` in umbrella mode; create dir if needed) using the structure in the Output block, and also print it for pasting into Jira/Slack.
 
+## Step 5.5 — Backfill the trace (pending-view link)
+
+If Step 1 matched a specific failing scenario `{UC-ID}-SC{N}` **and** a trace row exists in
+`{paths.trace_dir}/{UC-ID}.tsv`, update **only** that row so the PO/PM "waiting-on" view points
+to this bug — leave every other column (incl. `qc_status`) unchanged:
+- `qc_blocked_by` = `{BUG-ID}`
+- `qc_owner` = `dev` if likely layer ∈ {Code, BDD, Design Spec, Env} · `po` if likely layer = PRD ambiguity
+
+Skip silently if no SC matched or no trace file/row exists (a bug can still be filed). This is
+the only write this command makes to operational state — it still **never** edits PRD/BDD/code.
+
 ## Step 6 — Handoff (so PO/Dev actually see it)
 
 The report only reaches PO/Dev if it is **committed and pushed to the shared spec repo**. A local file is a dead drop.
@@ -545,6 +563,7 @@ Next   : {suggested command with example arguments}
 🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (in shared spec repo)
 
 Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
+State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` by /fix-bug, `Closed` after /qc-run-test re-verify pass)
 
 Spec context
   PRD      : {prd_path} (v{prd_version})

package/core/commands/review-code.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/review-context.md

@@ -132,6 +132,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
@@ -144,6 +146,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`
@@ -188,6 +192,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/review-tech-docs.md

@@ -129,6 +129,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
@@ -141,6 +143,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`
@@ -185,6 +189,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/sync.md

@@ -144,9 +144,9 @@ Collect from output:
 
 ---
 
-## Step 1d — Surface Tester Feedback *(new bug reports / scenario proposals)*
+## Step 1d — Surface Tester/QC Feedback *(bug reports / scenario proposals / PRD change requests)*
 
-Tester `/report-bug` and `/propose-scenario` commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
+Tester & QC `/report-bug`, `/propose-scenario` (incl. Case B PRD change requests) commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
 
 - **Dev/tester in umbrella** → feedback came in via the spec submodule advance (Step 1c)
 - **PO working directly in the spec repo** → feedback came in via the umbrella/current-repo `git pull` (Step 1)
@@ -158,22 +158,25 @@ Pick the repo + range that pulled the feedback:
 If `feedback/` does not exist in REPO → skip silently.
 
 ```bash
-git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/ feedback/prd-change-requests/
 ```
 
-For each entry, read its title/summary and report:
+For each entry, read its title/summary + `State` and report. **Bug reports: surface only `State: Open`** as needing attention; list `Fixed`/`Closed` separately (or omit) so the PO/PM sees what's still pending:
 ```
-📥 New tester feedback (pulled this sync):
-   Bug reports:
-     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code]
+📥 New feedback (pulled this sync):
+   Bug reports (open):
+     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code · waiting: dev]
+   Bug reports (fixed, awaiting QC re-verify): BUG-20260605-02
    Scenario proposals:
      FT-001-trailing-spaces.md  → maps to AC2  (pending review)
+   PRD change requests:
+     FT-001-bulk-export.md  → new requirement, needs an AC  (waiting: PO)
 ```
 
-If none changed → print `📥 Tester feedback: none new this sync`.
+If none changed → print `📥 Feedback: none new this sync`.
 
 If the reader is a PO/Dev, add a one-line nudge:
-`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal into BDD · or update PRD.`
+`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal via /generate-bdd · or add an AC to the PRD.`
 
 ---
 

package/core/commands/validate-traces.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.
 
@@ -467,7 +472,7 @@ If code was generated from an older revision → flag `TECHDOC_DRIFT`.
 *Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
 
 For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
-Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at` (owned by `/qc-run-test`); this command only reads them for the report.
+Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (owned by `/qc-run-test` + `/report-bug`); this command only reads them for the report.
 
 ### Step 7 — Compute dashboard aggregates
 
@@ -494,6 +499,9 @@ qc_skipped       = rows where qc_status == skip
 qc_not_run       = rows where qc_status in (not_run, —)
 # qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
 # shown alongside — never merged with — dev_selftest.
+waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
+waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify
+# qc_owner + qc_blocked_by answer "case nào đang chờ ai" — surface as a "Waiting on" column.
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/
 ```
 
@@ -528,6 +536,8 @@ Schema:
     "qc_failing": 0,
     "qc_skipped": 0,
     "qc_not_run": 0,
+    "waiting_dev": 0,
+    "waiting_po": 0,
     "tech_docs_count": 0
   },
   "prds": [
@@ -557,6 +567,8 @@ Schema:
               "dev_selftest_at": "<YYYY-MM-DD or null>",
               "qc_status": "pass | fail | skip | not_run",
               "qc_run_at": "<YYYY-MM-DD or null>",
+              "qc_owner": "dev | po | null",
+              "qc_blocked_by": "<BUG-id / GAP-id or null>",
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
@@ -621,7 +633,8 @@ Schema:
 - `tech_doc_revision`: use integer; `0` if not yet generated
 - `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
-- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`
+- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
+- **Backward-compat (older 19-col TSV):** if `qc_owner` / `qc_blocked_by` columns are **absent** from the header (a pre-upgrade TSV), treat them as `null` — do not error. The next `/generate-bdd` re-gen upgrades the header to include them.
 
 ### Step 8b — Living Docs Sync *(umbrella mode only)*
 

package/core/modules/qc-playwright/stack-profile.yaml

@@ -22,11 +22,11 @@ architecture:
     - "Group tests by (role, account) so login/logout never interleaves across roles"
     - "Cover 100% of TCs in the .Test.md — every TC ends Pass/Fail/Skip, none left Draft"
   folder_structure: |
-    docs/<project>/<feature>/      ← test-case Markdown (.Test.md) — source of truth
+    {paths.qc_dir}/{UC-ID}/test-cases/   ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
     pages/                         ← Page Object Model
     │   ├── base_page.py           ← slim BasePage (click/fill/wait/screenshot)
     │   └── <feature>_page.py
-    tests/                         ← pytest scripts, 1-1 with docs/
+    tests/                         ← pytest scripts, 1-1 with test-cases/
     │   ├── conftest.py            ← fixtures: browser, page, logged_in_page, tracing
     │   └── <project>/test_<feature>.py
     utils/                         ← config_loader, logger, steps, test_ordering, report helpers
@@ -41,7 +41,7 @@ coding_standards:
     test_function: "test_TC<NNN>_<snake_case>"
     page_object: "<feature>_page.py with <Feature>Page class extending BasePage"
     files:
-      test_case_md: "docs/<project>/<feature>/TC_<FEATURE>.Test.md"
+      test_case_md: "{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.Test.md"
       page_object: "pages/<feature>_page.py"
       test_script: "tests/<project>/test_<feature>.py"
   patterns:

package/core/skills/code/SKILL.md

@@ -152,6 +152,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
@@ -164,6 +166,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`
@@ -208,6 +212,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/skills/debug/SKILL.md

@@ -67,6 +67,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
@@ -79,6 +81,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`
@@ -123,6 +127,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/skills/design-spec/SKILL.md

@@ -141,6 +141,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
@@ -153,6 +155,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`
@@ -197,6 +201,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/skills/discovery/SKILL.md

@@ -46,6 +46,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
@@ -58,6 +60,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`
@@ -102,6 +106,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/skills/qc/qa-analyst/acceptance-criteria.md

@@ -51,6 +51,10 @@ Mỗi AC gắn mã trace: chức năng + BR-xx để TC sau này map 1-1.
 
 ## Output
 
-- Danh sách AC dạng Given/When/Then, có mã trace về chức năng và business rule.
+Ghi vào **mục Acceptance Criteria** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+
+- Danh sách AC dạng Given/When/Then, có mã trace về chức năng, business rule (BR-xx)
+  và scenario chính thức `{UC-ID}-SC{N}` của `.feature`.
 - Bảng ma trận: BR / chức năng × AC để xác nhận không bỏ sót.
 - Đây là đầu vào trực tiếp cho `qa-designer` (mỗi AC → ≥1 test case) và `qa-reviewer` (đối chiếu coverage).

package/core/skills/qc/qa-analyst/business-rules.md

@@ -49,7 +49,11 @@ Với rule có nhiều điều kiện kết hợp → gợi ý dựng **Decision
 
 ## Output
 
+Ghi vào **mục Business Rules** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+
 - Bảng business rule có ID (BR-xx) để TC trace ngược về.
-- Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `DOC_GAPS.md` (loại CONTRADICTORY / AMBIGUOUS,
-  cột "Ảnh hưởng" trỏ BR-xx) rồi ghi vào `DOC_GAPS.md`.
 - Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.
+
+Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`
+(loại CONTRADICTORY / AMBIGUOUS, cột "Ảnh hưởng" trỏ BR-xx).