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

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.
 
@@ -223,19 +228,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -335,7 +362,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -444,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` or `dev_selftest_at` — those are owned by `/dev-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
 
@@ -463,8 +491,17 @@ gap_count        = rows where status == GAP
 dev_selftest_passing = rows where dev_selftest == pass
 dev_selftest_failing = rows where dev_selftest == fail
 dev_selftest_not_run = rows where dev_selftest in (not_run, —)
-# NOTE: this is the DEV self-check signal (did the dev run their own smoke tests),
-# NOT official QC/dev-team coverage — keep it labeled as such on the dashboard.
+# NOTE: dev_selftest is the DEV self-check signal (did the dev run their own smoke tests),
+# NOT official coverage — keep it labeled as such on the dashboard.
+qc_passing       = rows where qc_status == pass
+qc_failing       = rows where qc_status == fail
+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}/
 ```
 
@@ -495,6 +532,12 @@ Schema:
     "dev_selftest_passing": 0,
     "dev_selftest_failing": 0,
     "dev_selftest_not_run": 0,
+    "qc_passing": 0,
+    "qc_failing": 0,
+    "qc_skipped": 0,
+    "qc_not_run": 0,
+    "waiting_dev": 0,
+    "waiting_po": 0,
     "tech_docs_count": 0
   },
   "prds": [
@@ -522,6 +565,10 @@ Schema:
               "test_classes": ["<TestClass1>", "<TestClass2>"],
               "dev_selftest": "pass | fail | not_run",
               "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,
@@ -586,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`
+- **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)*
 
@@ -659,6 +707,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

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

@@ -0,0 +1,65 @@
+# QC automation module — Python + pytest-playwright + Page Object
+# Used by the /qc-* commands (the official QC automation pipeline ported from the QC team).
+# This is the QC test-authoring/execution stack, independent of the dev implementation
+# module (java-spring, react, flutter, …). Selected via tech_stack.qc_module or per /qc-* run.
+
+build:
+  test: "python3 -m pytest"
+  e2e: "python3 -m pytest -m e2e"
+  report: "python3 -m pytest --html=reports/<feature>/report.html --self-contained-html"
+  show_trace: "python3 -m playwright show-trace <test-results/<nodeid>/trace.zip>"
+
+architecture:
+  style: "Page Object Model over pytest-playwright — Markdown test-case first, Python second"
+  key_rules:
+    - "Markdown-first: never generate Python until a reviewed .Test.md exists for the feature"
+    - "No Allure, no hand-written dashboard, no record_video — use Playwright Trace + pytest-html"
+    - "No hard-coded URL/credential/timeout — read from Env.* and CONFIG[...]"
+    - "No time.sleep() — use Playwright auto-wait / expect()"
+    - "Each test independent via pytest-playwright fixtures (page / logged_in_page / …)"
+    - "Page Object extends slim BasePage; split 3 layers: locators _x(), actions verb_noun(), assertions assert_x() using expect()"
+    - "Locator priority: data-testid → role → label/text → CSS → avoid XPath"
+    - "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: |
+    {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 test-cases/
+    │   ├── conftest.py            ← fixtures: browser, page, logged_in_page, tracing
+    │   └── <project>/test_<feature>.py
+    utils/                         ← config_loader, logger, steps, test_ordering, report helpers
+    test_data/                     ← JSON datasets
+    config/config.yaml             ← browser, timeout, video/screenshot/trace toggles
+    reports/  test-results/        ← generated (gitignored): html report, trace.zip, screenshots
+
+coding_standards:
+  naming:
+    test_case_id: "TC_<FEATURE>_<NNN>"
+    test_class: "TestFeatureHappyCase"
+    test_function: "test_TC<NNN>_<snake_case>"
+    page_object: "<feature>_page.py with <Feature>Page class extending BasePage"
+    files:
+      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:
+    steps: "wrap steps with `with step(\"…\")` (from utils.steps import step)"
+    assertions: "Playwright expect() — never bare assert on dynamic UI"
+    fixtures: "auth fixtures register via register_auth_fixtures([...]) in project conftest"
+    fail_triage: "classify each FAIL as script-bug (fix selector/logic) vs product-gap (keep FAIL + evidence, never fake-pass)"
+
+testing:
+  layers: "functional (gui-screen / gui-feature / api), integration (api/db/gui/kafka), e2e (journey), non-functional, exploratory"
+  runner: "pytest-playwright; trace via context.tracing.start in conftest"
+  report: "pytest-html (--html ... --self-contained-html) + Playwright Trace viewer"
+
+trace_tags:
+  # QC tests map back to the framework's scenarios — drives qc_status in the trace TSV.
+  verifies: "# @trace.verifies={UC-ID}-SC{N}"
+  source: "# @trace.source=<official .feature path>"
+  test_type: "# @trace.test_type=functional|integration|e2e|non-functional"
+
+# qc_status: /qc-run-test writes pass|fail|skip|not_run + qc_run_at into {trace_dir}/{UC-ID}.tsv
+# (parallel to dev_selftest), surfaced in Living Docs as the OFFICIAL QC automation result.

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.
 
@@ -248,19 +253,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -360,7 +387,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -504,6 +532,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -622,6 +657,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

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.
 
@@ -163,19 +168,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -275,7 +302,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -442,6 +470,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -586,6 +621,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -687,6 +729,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

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.
 
@@ -237,19 +242,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -349,7 +376,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -471,6 +499,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |