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

package/docs/05-reference/modules.md

@@ -0,0 +1,110 @@
+[📚 Docs](../README.md) › [Reference](README.md) › Stack Modules
+
+# Stack Modules
+
+> Mỗi module dưới `modules/` ship một `stack-profile.yaml` chứa layer pattern, naming rule, và test pattern riêng cho framework đó. Framework detect platform type từ `tech_stack.module` (hoặc `active_module` trong multi-service) và adapt mọi artifact sinh ra.
+
+---
+
+## Mục lục
+
+- [Danh sách module](#danh-sách-module)
+- [Platform type grouping](#platform-type-grouping)
+- [qc-playwright — QC automation stack](#qc-playwright--qc-automation-stack)
+
+---
+
+## Danh sách module
+
+15 module (xác minh bằng listing thư mục `modules/`):
+
+| Module | Language / Framework | Platform type |
+|--------|----------------------|---------------|
+| `java-spring` | Java + Spring Boot | backend |
+| `golang` | Go + Gin/Echo | backend |
+| `dotnet` | C# + .NET / ASP.NET Core | backend |
+| `php-laravel` | PHP + Laravel | backend |
+| `context-engineering` | Generic AI/LLM projects | backend |
+| `react` | TypeScript + React | web-frontend |
+| `nextjs` | TypeScript + Next.js | web-frontend |
+| `vue` | TypeScript + Vue 3 | web-frontend |
+| `nuxt` | TypeScript + Nuxt 3 + @nuxt/ui | web-frontend |
+| `angular` | TypeScript + Angular | web-frontend |
+| `flutter` | Dart + Flutter | mobile |
+| `react-native` | TypeScript + React Native / Expo | mobile |
+| `ios-swiftui` | Swift + SwiftUI | mobile |
+| `android-compose` | Kotlin + Jetpack Compose | mobile |
+| `qc-playwright` | Python + pytest-playwright + Page Object | QC / E2E (xem dưới) |
+
+---
+
+## Platform type grouping
+
+`platform_type` được suy ra từ module và quyết định cách adapt BDD vocabulary, tech-design sections, và test templates.
+
+| `platform_type` | Modules |
+|-----------------|---------|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+Ví dụ adapt theo platform type:
+
+- **BDD vocabulary** — backend dùng "submits a request" / "receives response"; web dùng "clicks" / "types into" / "navigates to"; mobile dùng "taps" / "enters" / "opens".
+- **Tech-design sections** — backend: §4 API Endpoints / §5 Service Flow / §6 Data Model…; web-frontend: §4 Screen/Component Breakdown / §5 State Management…; mobile: §4 Screen/Widget Breakdown / §5 State & Data Flow….
+- **Test templates** — Java → JUnit 5 + Mockito + `@WebMvcTest`; web → Vitest/Jest + Testing Library + Playwright/Cypress; Flutter → `testWidgets`; iOS → `XCTestCase`; Android → Compose rule + `@HiltAndroidTest`.
+
+---
+
+## qc-playwright — QC automation stack
+
+`qc-playwright` là **stack QC automation độc lập** với dev implementation module. Nó power native QC pipeline (`/qc-run-test`, `/qc-report`) và được chọn qua `tech_stack.qc_module` hoặc per `/qc-*` run — không phụ thuộc vào stack dev (java-spring, react, flutter…). Per-layer guides nằm ở `skills/qc/<stage>/`. Xem [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+
+**Stack** (từ `modules/qc-playwright/stack-profile.yaml`): Python 3 + pytest-playwright + Page Object Model. Report = Playwright Trace + pytest-html (**không** dùng Allure, không hand-written dashboard, không `record_video`).
+
+**Build commands:**
+
+| Mục đích | Command |
+|----------|---------|
+| 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>` |
+
+**Key architecture rules:**
+- **Markdown-first** — không sinh Python cho tới khi có `.Test.md` đã review cho feature.
+- Không hard-code URL/credential/timeout — đọc từ `Env.*` và `CONFIG[...]`.
+- Không `time.sleep()` — dùng Playwright auto-wait / `expect()`.
+- Mỗi test độc lập qua pytest-playwright fixtures (`page` / `logged_in_page` / …).
+- Page Object extends slim `BasePage`; tách 3 layer: locators `_x()`, actions `verb_noun()`, assertions `assert_x()` dùng `expect()`.
+- Locator priority: `data-testid` → role → label/text → CSS → tránh XPath.
+- Group test theo `(role, account)` để login/logout không interleave giữa các role.
+- Cover 100% TC trong `.Test.md` — mỗi TC kết thúc Pass/Fail/Skip, không để Draft.
+
+**Naming:** test case id `TC_<FEATURE>_<NNN>` · test class `TestFeatureHappyCase` · test function `test_TC<NNN>_<snake_case>` · page object `<feature>_page.py` (`<Feature>Page` extends `BasePage`).
+
+**Folder structure:**
+```
+docs/<project>/<feature>/   ← test-case Markdown (.Test.md) — source of truth
+pages/                      ← Page Object Model (base_page.py + <feature>_page.py)
+tests/                      ← pytest scripts, 1-1 với docs/ (conftest.py + 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
+```
+
+**Test layers:** functional (gui-screen / gui-feature / api) · integration (api/db/gui/kafka) · e2e (journey) · non-functional · exploratory.
+
+**Trace tags** (map QC test về scenario, drive `qc_status`):
+```python
+# @trace.verifies={UC-ID}-SC{N}
+# @trace.source=<official .feature path>
+# @trace.test_type=functional|integration|e2e|non-functional
+```
+
+> `/qc-run-test` ghi `pass|fail|skip|not_run` + `qc_run_at` vào `{trace_dir}/{UC-ID}.tsv` (song song với `dev_selftest`), surfaced trong Living Docs là kết quả QC automation **chính thức**. Mỗi FAIL được phân loại script-bug (fix selector/logic) vs product-gap (giữ FAIL + evidence, không bao giờ fake-pass).
+
+---
+
+*Xem thêm:* [Trace TSV Schema](trace-schema.md) (`qc_status` vs `dev_selftest`) · [Command Reference](commands.md) (pipeline `/qc-*`) · [02 · Guides · QC Automation](../02-guides/qc-automation.md).

package/docs/05-reference/trace-schema.md

@@ -0,0 +1,146 @@
+[📚 Docs](../README.md) › [Reference](README.md) › Trace TSV Schema
+
+# Trace TSV Schema
+
+> Schema chuẩn của `.trace/{UC-ID}.tsv` — file trace state per use-case. Mỗi UC một file: 1 header row + 1 data row mỗi scenario. Đây là nguồn dữ liệu cho `/validate-traces` và panel Living Docs.
+
+---
+
+## Mục lục
+
+- [Canonical TSV header](#canonical-tsv-header)
+- [Column reference](#column-reference)
+- [Two independent signals: dev_selftest vs qc_status](#two-independent-signals-dev_selftest-vs-qc_status)
+- [Status computation (validate-traces)](#status-computation-validate-traces)
+- [@trace tags across artifacts](#trace-tags-across-artifacts)
+- [trace-report.json](#trace-reportjson)
+
+---
+
+## Canonical TSV header
+
+Tab-separated, một header row + một data row mỗi scenario. Header chính xác (từ `generate-bdd.tmpl`):
+
+```
+sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	prd_version	bdd_version	tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
+```
+
+19 cột, theo đúng thứ tự trên.
+
+---
+
+## Column reference
+
+| # | Column | Ý nghĩa | Giá trị khởi tạo (`/generate-bdd`) | Ai ghi |
+|---|--------|---------|------------------------------------|--------|
+| 1 | `sc_id` | `{UC-ID}-SC{N}` — khóa chính của row | `{UC-ID}-SC{N}` | generate-bdd |
+| 2 | `sc_title` | Scenario title text | từ `.feature` | generate-bdd |
+| 3 | `spec_ver` | `@trace.sc_version` hiện tại của scenario | từ `.feature` | generate-bdd / validate-traces (reconcile) |
+| 4 | `gen_ver` | Version tại thời điểm code được sinh | `—` | generate-code |
+| 5 | `implemented_by` | `ClassName.method` cài đặt scenario | `—` | generate-code |
+| 6 | `test_count` | Số test verify scenario | `—` | dev-gen-test |
+| 7 | `test_classes` | Danh sách test class | `—` | dev-gen-test |
+| 8 | `dev_selftest` | Kết quả dev self-check: `pass` / `fail` / `not_run` | `—` | **dev-run-test** |
+| 9 | `dev_selftest_at` | Ngày chạy dev self-check (`YYYY-MM-DD`) | `—` | **dev-run-test** |
+| 10 | `qc_status` | Kết quả QC chính thức: `pass` / `fail` / `skip` / `not_run` | `—` | **qc-run-test** |
+| 11 | `qc_run_at` | Ngày chạy QC (`YYYY-MM-DD`) | `—` | **qc-run-test** |
+| 12 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 13 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 14 | `tech_doc_revision` | Tech-doc revision tại thời điểm codegen | `—` | generate-code |
+| 15 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
+| 16 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
+| 17 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
+| 18 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
+| 19 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
+
+> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
+
+---
+
+## Two independent signals: dev_selftest vs qc_status
+
+Trace TSV mang **hai cột tín hiệu độc lập** — không bao giờ trộn:
+
+| | `dev_selftest` (+ `dev_selftest_at`) | `qc_status` (+ `qc_run_at`) |
+|---|--------------------------------------|------------------------------|
+| Ghi bởi | `/dev-run-test` | `/qc-run-test` |
+| Ý nghĩa | Dev tự smoke-check code mình vừa sinh | Kết quả QC automation **chính thức** |
+| Giá trị | `pass` / `fail` / `not_run` | `pass` / `fail` / `skip` / `not_run` |
+| Stack | Dev implementation module | `qc-playwright` module |
+| Coverage chính thức? | **KHÔNG** — chỉ là dev self-check | **CÓ** — official QC result |
+| Keyed by | `@trace.verifies={UC-ID}` | `@trace.verifies={UC-ID}-SC{N}` |
+
+`/validate-traces` chỉ **đọc** hai cột này cho report — không bao giờ ghi đè (mỗi cột do command sở hữu nó quản lý). Living Docs hiển thị cả hai cạnh nhau.
+
+---
+
+## Status computation (validate-traces)
+
+`/validate-traces` tính cột `status` theo thứ tự ưu tiên (rule đầu tiên khớp thì dừng):
+
+| Rule | Status | Điều kiện |
+|------|--------|-----------|
+| 1 | `UNTRACKED` | `implemented_by == —` (chưa sinh code) |
+| 2 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
+| 3 | `DRIFT` | `spec_ver != gen_ver` (scenario đổi sau lần codegen gần nhất) |
+| 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
+
+Ngoài ra `/validate-traces` còn flag **`PRD_DRIFT`** (PRD version trong code/TSV trễ hơn PRD file hiện tại) và **`TECHDOC_DRIFT`** (code sinh từ tech-doc revision cũ).
+
+---
+
+## @trace tags across artifacts
+
+Mọi artifact link với nhau qua `@trace.*` tags.
+
+**`.feature` files:**
+```gherkin
+# @trace.id: FEAT-001-UC1
+# @trace.service: web-admin
+# @trace.module: react
+# @trace.prd_version: 1.2
+# @trace.bdd_version: 3
+# @trace.api_source: existing   # brownfield: API đã tồn tại, contract lấy từ PRD
+```
+Per-scenario trong file: `# @trace.scenario: {UC-ID}-SC{N}`, `# @trace.sc_version: 1.0`, `# @trace.business_rules: ...`.
+
+**Code:**
+```java
+// @trace.implements=FEAT-001-UC1-SC2
+// @trace.prd_version=1.2
+// @trace.bdd_version=3
+// @trace.tech_doc_revision=2
+```
+
+**Dev self-check tests:**
+```java
+// @trace.verifies=FEAT-001-UC1
+// @trace.service=api-backend
+// @trace.test_type=integration
+```
+
+**QC tests** (`qc-playwright`, drive `qc_status`):
+```python
+# @trace.verifies={UC-ID}-SC{N}
+# @trace.source=<official .feature path>
+# @trace.test_type=functional|integration|e2e|non-functional
+```
+
+---
+
+## trace-report.json
+
+`/validate-traces` ghi `{paths.trace_dir}/trace-report.json` — single source of truth cho web dashboards. Cấu trúc rút gọn:
+
+- `generated_at`, `domain`
+- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `tech_docs_count`
+- `prds[]` → `ucs[]` → `scenarios[]` — mỗi scenario có đầy đủ các trường của TSV row (gồm `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`)
+- `issues` — phân loại: `drift`, `gap`, `untracked`, `prd_version_drift`, `techdoc_drift`, mỗi entry kèm `fix` command gợi ý
+
+**TSV `"—"` → JSON mapping:** `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`.
+
+> **Umbrella mode:** mỗi service submodule giữ `.trace/` riêng (committed). `/validate-traces` (hoặc `/sync`) publish merged report vào `{spec_source}/.living-docs/` (canonical) + mirror `./.trace/trace-report.json` ở workspace hiện tại. Cả hai là generated mirror — gitignore, không commit.
+
+---
+
+*Xem thêm:* [Command Reference](commands.md) (`/validate-traces`, `/qc-run-test`, `/dev-run-test`) · [03 · Concepts](../03-concepts/) (traceability system).

package/docs/README.md

@@ -0,0 +1,51 @@
+# 📚 Spec-Driven Dev — Documentation
+
+> AI-First Spec-Driven Development for Claude Code: Discovery → PRD → Design-Spec → BDD →
+> Code → Dev self-check → QC automation, with traceability and human review gates.
+
+Tài liệu được chia theo **vai trò** và **chủ đề**. Bắt đầu ở mục phù hợp với bạn:
+
+| Bạn là… | Bắt đầu ở |
+|---------|-----------|
+| Người mới / cài đặt lần đầu | [01 · Getting Started](01-getting-started/) |
+| Product Owner | [Guide · Product Owner](02-guides/product-owner/README.md) |
+| Developer | [Guide · Developer](02-guides/developer/README.md) |
+| Tester | [Guide · Tester](02-guides/tester/README.md) |
+| QC Automation | [Guide · QC Automation](02-guides/qc-automation.md) |
+| Muốn hiểu kiến trúc | [03 · Concepts](03-concepts/) |
+| Vận hành / admin | [04 · Operations](04-operations/) |
+| Tra cứu lệnh | [05 · Reference](05-reference/) |
+
+---
+
+## Mục lục
+
+### 01 · [Getting Started](01-getting-started/)
+- [Installation](01-getting-started/installation.md) — cài framework, prerequisites
+- [Quick Start](01-getting-started/quickstart.md) — chạy feature đầu tiên end-to-end
+- [Core Concepts](01-getting-started/core-concepts.md) — khái niệm trong 5 phút
+
+### 02 · [Guides (theo vai trò)](02-guides/)
+- [Product Owner](02-guides/product-owner/README.md) — define-product, PRD, design-spec, review
+- [Developer](02-guides/developer/README.md) — BDD, tech-docs, code, dev self-check
+- [Tester](02-guides/tester/README.md) — spec-manifest, report-bug, propose-scenario, Living Docs
+- [QC Automation](02-guides/qc-automation.md) — pipeline `/qc-*`, qc_status
+
+### 03 · [Concepts](03-concepts/)
+- [Architecture](03-concepts/architecture.md) — layers, modules, plug-in system
+- [Pipeline](03-concepts/pipeline.md) — các phase Discovery → QC
+- [Traceability & Living Docs](03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+
+### 04 · [Operations](04-operations/)
+- [Sync & Update](04-operations/sync-and-update.md) — `/sync`, `/update-framework`, umbrella
+- [Bug Flow](04-operations/bug-flow.md) — report → fix → verify
+- [Publishing](04-operations/publishing.md) — build + npm publish
+
+### 05 · [Reference](05-reference/)
+- [Commands](05-reference/commands.md) — bảng đầy đủ mọi slash command
+- [Trace Schema](05-reference/trace-schema.md) — cột TSV, trace tags
+- [Modules](05-reference/modules.md) — stack modules (java-spring, react, …, qc-playwright)
+
+---
+
+*Mỗi file có breadcrumb điều hướng ở đầu. Phiên bản framework: xem `core/FRAMEWORK_VERSION`.*

package/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: |
+    docs/<project>/<feature>/      ← test-case Markdown (.Test.md) — source of truth
+    pages/                         ← Page Object Model
+    │   ├── base_page.py           ← slim BasePage (click/fill/wait/screenshot)
+    │   └── <feature>_page.py
+    tests/                         ← pytest scripts, 1-1 with docs/
+    │   ├── 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: "docs/<project>/<feature>/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhth2/spec-driven-dev-plugin",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "AI-First Spec-Driven Development workflow plugin for Claude Code",
   "bin": {
     "spec-driven-dev": "./bin/index.js"
@@ -24,7 +24,7 @@
     "skills/",
     "steps/",
     "templates/",
-    "ARCHITECTURE.md"
+    "docs/"
   ],
   "keywords": [
     "claude-code",

package/skills/code/SKILL.md

@@ -190,7 +190,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -202,7 +202,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -233,7 +233,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
 - File write operations (test files, trace TSVs) use paths **relative to** `service_root`
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
@@ -248,19 +248,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.
 
 ---
 
@@ -326,7 +348,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -360,7 +382,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,15 +527,22 @@ 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 → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
@@ -622,15 +652,22 @@ 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 → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |